# 参与本仓

本仓是公开仓：欢迎 Issue、Discussions 与 Pull Request。本档分两部分——**A 贡献指南**（欢迎什么、怎么提、怎么被处理、版权与许可）与 **B 公开文本规范**（提交信息／注释／文档的写作与机检；**机检未过不会被合并**）。

## A. 贡献指南

### A1. 欢迎哪些贡献

- **问题报告**：拦截误阻或漏拦、收口判定异常、兼容性、文档错误。
- **设计讨论**：判据口径、任务级作用域、收口强制形态、与同类机制的分工。
- **代码修改**：缺陷修复、测试补强、文档与示例。
- **不适合的**：绕过或削弱治理机制的改动（放宽拦截、美化判定、伪造完成证据）——本仓的机制红线**只允许加强方向**。

### A2. 如何反馈

- 具体问题 → [Issue](https://github.com/zxc663/shisan-xinuo-dsh-plugin/issues/new/choose)，按类型选模板（Bug／兼容性／文档／设计讨论）。
- 还没有定论的议题 → [Discussions](https://github.com/zxc663/shisan-xinuo-dsh-plugin/discussions)。
- 安全问题 → 走私密渠道，见 [SECURITY.md](SECURITY.md)；本插件不是安全边界，请先读该档。

### A3. 如何提出代码修改

- 分支 + Pull Request，描述按模板填：变更动机、影响面、**可重跑验证命令与退出码**。
- 合并门禁：`npm test` 全绿 + 公开文本机检通过（CI 自动执行）。
- 尽量带证据：命令、退出码、样本；判据与阈值**先于跑分冻结**（预注册制），事后改判据要留痕。

### A4. 贡献如何被处理

- 维护者审核后决定是否合并；**欢迎贡献不等于全部采纳**。
- 方向、优先级与合并决定留在维护者手里；不接受的会给出理由，不静默丢弃。
- 讨论可以很开放，但仓内结论只以 `docs/` 与可重跑证据为准。

### A5. 版权与许可

- 本仓采用 MIT。提交贡献即表示同意按 MIT 授权（inbound=outbound），**无需单独签署贡献者协议**。
- 引用他人代码与资产须保留原始许可与出处（本仓已有 Apache-2.0 组件的出处记录）。

## B. 公开文本规范（机检门禁）

本规范定义本仓**公开文本**（提交信息、代码注释、文档）的写作与提交规范，并给出可重跑的机检。

### B1. 原则

公开文本只呈现三类内容：**工程事实**、**设计决策（内容＋依据）**、**可复现证据**。

不呈现：人员归因（谁批准/谁要求/谁拍板）、开发会话过程、内部环境与工具具名、AI 工具或模型具名。

- 决策写法：`决策：<内容>（依据：<证据/理由>）`——不写「经……批准/裁决」。
- 内部过程记录（会话流水、评审往来、批次推进细节）放本地档案，不随仓。

### B2. 提交信息

- 格式：`type(scope): 摘要`
  - type ∈ `feat | fix | docs | test | chore | refactor | perf | build | ci`
  - scope 可选：`core | gate | budget | rules | docs | ci | release | …`（小写短词）
- 摘要：祈使句、一行、≤72 字符、结尾不加句号；中文可用，术语保留原文。
- 正文（可选）：说明**为什么**与关键细节；引用文档用仓库相对路径。
- 允许的自动化提交：`Merge …`、`Revert …`、`fixup!`/`squash!` 前缀不受格式约束。
- 硬禁词见 B5；本规范自 2026-10-13 起对**新提交**生效，历史提交不追溯。

示例：

```
feat(gate): 断言复核接入回合收尾自动复查
fix(rules): 修复 icacls 豁免在授权参数下失效
docs: 补充拦截换芯的语义回归说明
```

### B3. 代码注释

- 只写：意图、约束、边界条件、坑与规避方式；面向读者的公共接口说明用中性工程语言。
- 不写：日期/会话/批次流水、人员归因、内部环境或工具具名。
- 与代码行为无关的过程叙述放本地档案，不进源码。

### B4. 文档

- 公开文档面向读者：产品说明、设计记录、实验与验收证据；写作遵循 §0。
- 变更记录（CHANGELOG）按事实与决策书写，不写人员归因。
- 数据与引文可溯源；不确定项显式标注，不用夸大措辞。

### B5. 词汇表（★＝机检硬禁）

| 类别 | 禁止示例 | 替代写法 |
|---|---|---|
| ★ 人员决策归因 | 用户裁决 / 用户拍板 / 用户授意 / 用户令 | `决策：<内容>（依据：…）` |
| ★ AI 工具具名 | Codex / Claude / ChatGPT / OpenAI / ZCode | 删除，或写「开发环境」 |
| ★ AI 模型具名 | GPT-4 等 | 删除 |
| ★ AI 生成自述 | 由 AI/模型生成、AI 助手 | 删除 |
| 过程用语（建议） | 呈批 / 待批 / 接令 | 直接写决策与状态（如「待定」「已定」） |

注：产品语义中的「用户」不受限（如「需要用户确认」「用户明示目标」），机检只拦**决策归因**形态；技术协议名/配置字面量不受限（如 `openai-completions`、`openai/v1` 端点字面量）；**对标/竞品机制引用不受限**（如对照某产品的 Stop hook 机制）——受限的是**以工具为主语/署名的执行叙述**（如「由 X 完成」「本机 X 执行」）。

### B6. 机检

```bash
node scripts/check-voice.mjs                     # 扫描全部受控文件（工作树）
node scripts/check-voice.mjs --commits <A>..<B>  # 扫描提交信息范围
```

- `npm test` 已内置工作树扫描（`tests/repo-voice.test.mjs`）；CI 对推送/PR 的**新增提交范围**执行提交信息检查。
- 自校验文件（本档、机检脚本、其测试）为固定豁免集；如需新增豁免，在此处说明理由并保持可审计。