# 贡献指南 | Contributing

感谢你考虑为 说人话 做贡献。

## 提交新短语

新短语是最常见的贡献类型。提 PR 时请包含以下信息：

在提新短语之前，先做一个判断：

- 如果它只是现有模式的同义变体，优先补 `benchmark`、例句或 `operation-manual`，不要急着把词表越堆越长
- 只有满足下面至少一条，才建议新增词条：
  - 这个说法在多个来源反复出现
  - 它改变了误杀边界
  - 现有模式无法稳定吸收它

### 1. 确定 Tier

| Tier | 标准 | 示例 |
|------|------|------|
| Tier 1 | 删掉这个词/短语后句子信息量没有减少 | "值得注意的是""delve" |
| Tier 2 | 单独出现合理，聚集出现是 AI 味信号 | "然而""此外""nuanced" |
| Tier 3 | 常见词，只在全文饱和时有问题 | "重要""significant" |

**判断不了就先放 Tier 2。**

### 2. 提供例句

每个新短语至少附一个改写前后的对比：

```
❌ 值得一提的是，该方案在多个维度上表现优异。
✅ 该方案在延迟和吞吐上都跑赢了基线。
```

### 3. 说明是否有误杀风险

这个词/短语在什么场景下是合理的？例如：

- "杠杆"在金融领域是标准术语，不应标记
- "navigate" 在航海/地图语境中是正确用词

如果有误杀风险，请同时建议添加到 `references/severity.md` 的误杀防护列表。

### 4. 说明为什么不能只做“变体归并”

至少回答一个：

- 这个说法和现有代表项相比，多了什么新的姿态或风险？
- 为什么补 benchmark 或操作说明还不够？
- 它会不会让现有规则误判真人语境？

## 提交结构反模式

新增 `references/structures.md` 条目时，请包含：

1. 模式名称
2. 问题描述（为什么这是 AI 味）
3. 中文 + 英文的 ❌/✅ 对比（如果是跨语言模式）
4. 适用场景说明（全场景还是仅 aggressive 档位）

## 提交评测用例

`evals/benchmark.md` 欢迎新增用例。格式见文件内说明。两类都需要：

- **该改的**：包含 AI 味的文本 + 预期改写方向
- **不该误杀的**：看起来像 AI 味但实际合理的文本 + 不改的理由

在加 benchmark 之前，先判断动作类型：

- 如果你发现的是“现有规则没覆盖到的新场景边界”，优先补 `benchmark`
- 如果你发现的是“现有模式能吃住，但维护者容易判断不一致”，优先补 `references/operation-manual.md`
- 如果只是词表里的同义变体，通常不需要同时改 `phrases` 和 `benchmark`
- 涉及无源引用、mixed 场景、被讨论词、系统主语这类容易误杀的边界，默认优先加 benchmark

## 提交 bad case

如果你遇到“改完还是像 AI”的真实案例，优先用 GitHub 的 [bad case 模板](.github/ISSUE_TEMPLATE/bad-case.md) 提交。模板会要求你写清楚：

- 原文或已脱敏片段
- 使用工具和加载方式：`lite`（只加载 `SKILL.md`）或 `full`（`SKILL.md` + `references/`）
- 场景：`chat / status / docs / public-writing / code-context / mixed`
- 你觉得哪里仍然不自然
- 哪些事实、术语、命令、引用或责任主体不能改坏

不要提交未授权的私聊全文、敏感信息、账号、密钥、内部链接或真实个人身份信息。公开仓库里的 bad case 应优先是脱敏片段、公开来源观察，或经过授权的样本。

## PR 规范

1. 一个 PR 只做一件事（加短语、加结构、加评测用例、改文档）
2. 更新 `CHANGELOG.md`
3. 如果改了规则逻辑，同步更新 `SKILL.md` 和对应的 `references/` 文件
4. 如果改了 benchmark 的数量、口径或判分逻辑，同步更新 `evals/run-eval.md` 和结果文档引用
5. 提交前在仓库根目录运行 `python3 automation/check_repo.py`，全绿后再提；新增「N 条 / N cases」类计数文案时，同时登记到脚本的 `ANCHORS` 表

## 维护者：Community Observation Intake

当一批新的 AI 姿态链在公开讨论里重复出现（Linux.do / V2EX / X / 知乎 / Reddit 等），用这个流程做一次 intake，而不是只加一条词表条目。这是维护者面向的流程，不是执行改写时要走的。

### 触发条件

- 公开讨论里**多处独立吐槽**同一类表达，不是单点
- 这类模式不在 `phrases-zh.md` 已收录词表里，但变体彼此重复
- 新 SOTA 模型发布后某一类表达突然高频（例如 Claude Opus 4.7、GPT-5.4 的"接住体"）
- 已有模式的边界被反例撑破：技术语境里某词被误杀，或咨询 / 安抚语境里新话术漏杀

### Intake 五步

1. **溯源**：在 `evals/real-samples.md` 或 `CHANGELOG.md` 里记录 2-3 处公开讨论链接，作为观察来源。不做未授权整段转录
2. **抽象姿态链**：把重复出现的**一串表达**归纳成 1-2 句识别信号。姿态链比单词更稳：`我就在这里 / 不躲不藏 / 稳稳接住 / 你不是……你只是……` 合起来才是"过度接住 + 心理判断"
3. **判宾语 / 判场景**：列出放行边界——哪些宾语、哪些场景是误杀区。避免"看到 `接住` 就改平"
4. **双向补样本**：
   - 补 `SF` 覆盖姿态层命中（预期改写）
   - 补 `SNF` 覆盖放行边界（预期不动）
   - 有条件再补 1 条 `real-samples.md` 整段样本（含 3 维评分）
5. **升级规则**：`phrases-zh.md` 里相关条目改为"按宾语 / 场景判断"，`operation-manual.md` 的 `识别信号` 和 `保留条件` 同步补放行边界

### 什么时候不走 intake

- 只是单点吐槽，没有形成重复模式 → 先记在 `tasks/` 的观察备忘里，等下一次命中再启动
- 只是已有类别的字面变体 → 走"提交新短语"开头的变体归并判断，不需要完整 intake
- 观察来源是私聊 / 未授权转录 → 先脱敏或合成，不要直接进 `real-samples.md`

### 回读检查

- 新增的 SF / SNF 是否成对出现（该改 + 该放）
- 升级后的规则是否明确写了放行边界
- CHANGELOG 是否记录观察来源，而不是只写"新增规则"
- 这一轮 intake 是否不小心把某个技术语境的表达一并改平（尤其 `docs / code-context`）

### 参考实例

- `v1.7.3 Community Intake / 接住体` 是第一个完整走完这套 intake 的版本；观察来源见 CHANGELOG 的 v1.7.3 区块和 `evals/real-samples.md` 的"社区观察：为什么'接住体'一眼像 AI"
- `v1.7.4` 新增的 `SNF-22 / SNF-23` 是第 3 步"判宾语"的回归护栏，用来保护技术语境里的"接住请求 / 接住流量"不被误杀

### 自动化运行（v1.8.2 起）

`automation/` 顶层目录里有一套 intake automation 工具：把一批样本扔进 `tasks/current/intake/inbox/<日期>.md`（本地工作目录），跑一条 `codex exec` 命令，得到一份 `tasks/current/intake/reports/<日期>-intake.md`，按"已覆盖 / 变体归并 / 候选新模式"三档归类，并给出最多四类建议动作（`无动作 / 补 benchmark / 补 operation-manual / 考虑新增词条或结构`）。

具体命令、文件约定和强约束见 `automation/README.md`；prompt 本体见 `automation/intake-prompt.md`；协议规范见 `automation/intake.md`。

边界：自动化只覆盖上面"Intake 五步"里的第 2-3 步（抽象姿态链、判宾语 / 判场景），且只输出建议；第 1 步溯源、第 4 步双向补样本、第 5 步升级规则仍需人工评估和操作。**Intake 报告默认不会、也不应该自动改 `benchmark.md` / `phrases-zh.md` / `structures.md` / `operation-manual.md`。**

## 不接受的贡献

- 纯粹基于个人偏好的词汇增删（需要有 AI 文本频率依据或多人共识）
- 与特定平台深度绑定的改动（本项目保持平台无关）
- 添加非 MIT 兼容的内容