跳转至

文档与功能同步治理升级

1. 结论

本次不再增加一份手写功能目录,也不让脚本假装理解业务语义。治理核心是:

人声明文档影响,机器验证声明、路径、暂存状态和可重复生成结果。

先以 Google Maps 采集主流程建立一页用户视角产品文档,再让现有文档分类、索引、检查、提交和发布流程认识这层文档。历史文档不批量迁移。

2. 背景与问题

当前仓库已有 raw / specs / wiki / issues / rules / changelog,但各层回答的是来源、计划、实现知识、故障经验和工作流,缺少一份明确描述“用户现在能做什么”的当前产品行为文档。

现有 pnpm docs:check 能检查 frontmatter、INDEX 收录和 wikilink,但不能阻止这些漂移:

  • 功能代码变化后,没有任何文档影响声明;
  • README 版本和真实 package.json 版本可能不一致;
  • README 可能引用已经移动的规则文件;
  • 自动生成的 INDEX 可以长期未重建,检查仍通过;
  • 提交门禁只要求 ISSUE / SPEC 关联,不验证受影响文档是否和代码一起暂存。

3. 目标与非目标

3.1 目标

  1. 新增 docs/product/,只描述用户可见的当前产品行为,并先完成一个主流程试点。
  2. 所有包含产品影响路径变更的提交都必须显式填写 Docs-Impact trailer。首期产品影响路径为 src/** 和 wxt.config.ts。
  3. 非 none 的文档路径必须存在,且必须在同次提交中暂存。
  4. none 必须带具体理由,不能只写裸 none。
  5. 提供不写工作区的文档重建一致性检查。
  6. 提供统一的日常验证命令和发布一致性检查。
  7. 保持当前轻量 frontmatter parser,不引入新的 YAML 依赖。

3.2 非目标

  • 不新增手写 docs/catalog/features.json 或其他重复事实源。
  • 不做所谓“业务语义自动判断”。
  • 不根据 diff glob 自动猜测具体应该更新哪篇文档。
  • 不一次迁移现有全部历史文档。
  • 不创建没有真实用例的空测试目录。
  • 不在本期强制增加 GitHub Actions 或修改远端分支保护。
  • 不要求每种改动同时创建 product / spec / wiki / issue / test 全套文档。

4. 文档职责边界

层 回答的问题 本期动作
product 用户现在如何使用、会看到什么、限制是什么 新增并试点
specs 接下来要做什么、如何验收 保留
wiki 当前技术实现和字段语义是什么 保留
issues 出过什么问题、如何修复 保留
rules 团队遇到某类工作时怎么做 补充治理规则
raw 原始输入和证据是什么 保留
changelog 每个版本发生了什么 保留

产品文档不得复制 Wiki 的实现细节,也不得复制 Issue 的故障复盘。它只保留用户完成任务所需的信息,并链接到相关工程文档。

5. Docs-Impact 提交契约

首期以一份明确、保守的路径列表判断“是否必须声明”,不判断“具体应该更新哪篇文档”:

  • src/**:产品运行代码;
  • wxt.config.ts:扩展名称、权限、host permissions、入口和 manifest 行为配置。

package.json 暂不作为 Docs-Impact 触发路径:依赖和开发脚本变动不必然改变产品行为;版本与发布一致性由 release:check 单独约束。若未来出现稳定的用户可见 package 字段,再通过评审扩展触发列表。

5.1 有文档影响

Docs-Impact: docs/product/google-maps-collection.md, docs/wiki/multi-stage-scrape-pipeline.md

机器只验证:

  1. trailer 存在且只能有一条;
  2. 路径位于 docs/ 且以 .md 结尾;
  3. 路径在提交后的索引中存在;
  4. 路径出现在本次 staged 变更中。

5.2 无文档影响

Docs-Impact: none — 删除未引用 JWT 辅助文件,不改变用户路径、接口或配置语义

none 后必须有非空、具体的理由。门禁不判断理由是否“业务上正确”,评审者负责判断。

5.3 兼容现有门禁

现有 ISSUE / SPEC 关联规则继续生效;Docs-Impact 是额外契约,不替代问题归档和规格关联。

6. 实施拆分与串行门禁

每一项均遵守“修改 → 验证 → 独立对抗审查 → PASS 后进入下一项”:

  • 修复 README 版本与规则路径漂移。
  • 新增 docs/product/INDEX.md 和 Google Maps 采集主流程产品文档。
  • 扩展 docs_lib.py,让 product 成为正式文档层。
  • 扩展 check-docs.py,检查 product INDEX 收录。
  • 扩展 rebuild-docs.py,生成 product INDEX 与相关汇总。
  • 更新 mkdocs.yml、docs/README.md、目录规范和治理规则。
  • 实现 docs:rebuild:check,在临时目录比较生成结果,不写当前工作区。
  • 扩展 commit-msg hook,执行 Docs-Impact 契约。
  • 在隔离临时 Git 仓库验证 hook 的通过与拒绝路径。
  • 新增无业务写入的统一 verify,并关闭 pnpm 11 的 script 前自动 install。
  • 六个 diff 扫描器对缺失/损坏/非法 baseline fail closed,且合法空 baseline 可用。
  • ISSUE audit grep 支持 expect: absent(默认)、expect: present、paths 与仅供 present 使用的 allow_paths;扫描 scope 内全部 UTF-8 普通文本文件并明确跳过含 NUL 或非法 UTF-8 的二进制;pattern / description / paths / allow_paths 必须加引号,expect 只允许加引号或精确、区分大小写的 plain absent / present;顶层只接受无缩进 plain audit_grep: 或 audit_grep: [],quoted key、冒号前空格、根级缩进、重复 key 均拒绝;显式 tag、inline comment、block scalar、无法识别的对象行、重复字段等未支持 YAML 形态与空字段、symlink 一律 fail closed;默认 scope 的全部后代普通文本均扫描,不按同名目录额外排除,任何后代目录不可枚举时退出 2;正确解码 YAML 双引号转义并可靠执行跨行/PCRE 风格历史 pattern;未知字段、非法路径/正则或 grep 执行失败返回退出码 2,不再伪装为通过。
  • 新增只检查的发布专用 release:check。
  • 运行最终编译、文档检查、扫描和独立总审查。

7. 验收标准

7.1 文档层

  • docs/product/INDEX.md 被分类器识别为 product,不是 root。
  • 产品试点页包含用户前提、入口、流程、采集范围、状态/错误、限制和可验证操作。
  • pnpm docs:check 能发现 product 文档漏收录。
  • MkDocs 导航能访问产品文档。

7.2 重建一致性

  • pnpm docs:rebuild:check 在干净且已同步的文档树上退出 0。
  • 人工制造 INDEX 漂移时退出非 0,并列出漂移文件。
  • 命令结束后 git status --short 不新增变化。

7.3 Docs-Impact

隔离测试至少覆盖:

  • src/ 变更但无 trailer:拒绝。
  • wxt.config.ts 变更但无 trailer:拒绝。
  • 写了不存在的文档路径:拒绝。
  • 文档存在但未 staged:拒绝。
  • Docs-Impact: none 无理由:拒绝。
  • 合法路径且文档同时 staged:通过。
  • 合法 none — 具体理由:通过。
  • 没有产品影响路径变更:不强制 trailer。
  • 仅修改 docs/** 或 scripts/**,且未修改 src/** / wxt.config.ts:不强制 trailer。

7.4 日常与发布门禁

  • pnpm verify 串行执行类型检查、文档检查、治理脚本测试和现有静态扫描,不修改业务数据、版本号、changelog 或构建产物。
  • pnpm-workspace.yaml 的 verifyDepsBeforeRun: false 在 script body 之前关闭 pnpm 自动安装;依赖未准备时前置脚本退出 2,提示人工运行 pnpm install,且不创建 node_modules、.wxt 或 postinstall sentinel。
  • 六个 baseline diff 扫描器在基线缺失、损坏或 schema 非法时退出 2;合法 version: 1 + hits: [] 不误判;verify 通过 && 传播失败。
  • scan:issue-coverage --strict 先解码 YAML scalar,以 grep -zE 做跨行预选排序,但 grep 的候选结果绝不缩小最终扫描集合;随后用原始完整 Python 正则精确扫描全部已枚举 UTF-8 文本,兼容 \\A / \\Z、[\\s\\S]、JS [^]、lazy quantifier、大上限和负向前瞻。仅 grep rc=1 视为有效 0 预选;非法正则、grep rc>1 或执行异常均报告 ISSUE、pattern、stderr/异常并退出 2。
  • pnpm release:check 只检查、不构建、不生成 changelog。准备构建产物仍使用既有 pnpm build;生成根 changelog 仍使用既有 pnpm docs:changelog。
  • release:check 的必需输入为 package.json、dist-v2/chrome-mv3/manifest.json、docs/changelog/development-log.md 和根 CHANGELOG.md;任一缺失都退出非 0。
  • 精确解析 package.json.version 与 manifest JSON 的 version,两者必须字符串全等。
  • docs/changelog/development-log.md 必须存在一条非模板 ## 标题,标题中包含当前 v<package version>。
  • 根 CHANGELOG.md 必须存在精确标题前缀 ## [v<package version>]。
  • manifest 缺失、manifest 版本不符、开发日志缺当前版本、根 changelog 缺当前版本四类负向用例均退出非 0,并报告具体文件和修复动作。
  • 失败信息不得自动修改版本、重跑 build 或重生成 changelog。

8. 回滚策略

  • 所有治理能力均落在文档、脚本、package scripts 和本地 hooks 中,不改变业务数据模型。
  • 若新门禁误拦截,先回滚对应脚本和 hook 变更;不得用长期 --no-verify 代替修复。
  • docs/product/ 是新增层,回滚时删除导航与分类支持后再删除试点页,不影响原五层知识库。

9. 已知边界

  • 本地 hook 可被 --no-verify 绕过,因此它是默认工作流约束,不是不可绕过的安全边界。
  • 当前没有 tracked 自动化业务测试;本期只对新增治理脚本建立可重复的命令级验证,不虚构业务测试覆盖。
  • GitHub Actions 和分支保护需在确认远端 PR 工作流后另开 SPEC。

10. 决策记录

  • 2026-08-23:否决手写 features.json,避免制造重复事实源。
  • 2026-08-23:否决伪语义检查和 diff-glob 业务推断,改为显式 Docs-Impact 声明。
  • 2026-08-23:产品文档只做 Google Maps 采集主流程试点,不批量迁移历史文档。
  • 2026-08-23:自动测试暂不作为所有业务改动的统一硬门槛,允许记录明确的人工浏览器验证证据。