# 质量规范

> 版本：基线 1.0（2026-06-12）。依据：PRD §1.4 产品原则 2/5、§5 非功能需求、§7 发布判据；story-repo-spec 0.6 §2.2。

---

## 1. 运行时与依赖（硬约束）

1.1 Node ≥ 22；**零第三方运行时依赖**。新增依赖的 PR 必须被驳回，除非先修订 PRD。

1.2 禁止引入 Python、pip、.env；安装即用，无环境配置步骤。

1.3 开发期依赖（测试框架等）允许，但必须不进入发布产物。

## 2. 职责分界（宪法级，评审必查）

2.1 **脚本能做的归脚本，做不到的归 AI 语义判断**：可计数项（字数、频次、格式校验、关键词命中）必须用脚本实现，禁止让模型估算；语义判断（是否真泄密、正文是否写到了某事）必须归 AI，**禁止用正则硬凑语义判断**。

2.2 机检必须零 token；AI 调用每章预算：**完整两审 = 2 次**（事实审查 1 + 编辑审 1，各自独立上下文）；**降级模式 = 1 次**（单上下文顺序审）。超预算由宿主壳/编排层拒绝，不在 `runReviews` 内硬凑。

2.3 **精准读取**：每类数据文件必须配"定位读到所需一段"的脚本接口；写作材料组装默认用片段，禁止默认整文件读取。

## 3. 编码与平台（CI 强制）

3.1 一切文件 IO 显式 UTF-8 无 BOM；禁止依赖系统 locale。

3.2 Windows 中文环境是一等公民：CI 必须含 Windows 中文路径全链路测试（建库→写章→定稿→重建缓存）。中文路径、中文文件名在任何代码路径上都必须正确处理。

3.3 书仓库工程化由**建书流程**（`persistCreateBook`，序1）负责：`git init` + `git config core.quotepath false` + `.gitignore`（必含 `.cache/` 与 `工作区/`）。`git init` 幂等可重复；`.gitignore` 追加不覆盖既有条目。M5 安装器只负责宿主侧环境，不再代行书仓库初始化。

3.4 缩进两空格。

## 4. 测试要求

4.1 每个 CI 验收项对应 PRD/spec 的一条可验证承诺，最低集合：

- 删光 `.cache/` 全量重建，查询结果不变；
- Windows 中文路径全链路；
- 定稿原子性（中途失败时工作区原样保留）；
- 防呆方言（系统写出的 YAML 平铺/块列表/危险值引号）。

4.2 修 bug 必须附回归测试；同一问题第二次出现视为流程缺陷，必须复盘。

## 5. 评审清单（PR 必过）

- [ ] 不新增运行时依赖、不引入 Python
- [ ] 作者界面文案符合术语表（PRD §8），无废止词、无机器味
- [ ] 错误路径符合错误处理规范（永不带堆栈崩溃）
- [ ] 可计数逻辑在脚本里，语义判断不在正则里
- [ ] 行为变更先改了文档（PRD/spec），代码与文档一致

## 6. 工具链与约定（已定）

6.1 测试框架：Node 内置 `node:test` + `node:assert/strict`（`npm test` = `node --test`）。无第三方测试依赖。

6.2 lint / 格式化：**零依赖铁律下不引入 ESLint/Prettier**。语法用 `node --check` 兜底；确定性用宿主壳 drift check（`node scripts/build-host-shells.mjs --check`）+ package validator 兜底。缩进两空格、行尾 LF 由评审清单人工把关。

6.3 退出码：`0` 成功 / `1` 失败（见错误处理规范 §5）。

6.4 commit message 前缀沿用现状：`feat` / `fix` / `docs` / `chore`（本仓库开发用）。发布产物（marketplace/CHANGELOG）版本走 `docs/operations/plugin-release.md` 流程。

6.5 版本号：`v7/package.json` 在 M5 发版前为预发版号（`7.0.0-alpha`）；发版时升 `7.0.0` 并与 README 徽章、`.claude-plugin/marketplace.json`、`plugin.json`、`CHANGELOG.md` 一致——README 版本表是 `plugin-version.yml` CI 硬约束，发版必须同步。