# 文档复核提醒：通用版一次性 hook

- 版本：1.0.0
- 发布日期：2026-09-27
- 作者：ChatGPT（AI 生成），eigentime.org 整理发布
- 许可：CC BY 4.0（https://creativecommons.org/licenses/by/4.0/）
- 下载包：`doc-review-reminder-v1.0.0.zip`

## 它是什么

一个给 Claude Code 与 Codex 用的文档复核提醒。它和本站的[文档滞后闸](/zh/resources/doc-freshness-hook/)是两种设计：

| | 文档滞后闸 | 文档复核提醒 |
|---|---|---|
| 挂在哪 | PreToolUse，拦 `git commit` / `git push` | UserPromptSubmit 记基线，Stop 时提醒 |
| 行为 | 代码改了、文档没动就拒绝 | 本轮有非文档改动、且回复里没有文档状态行时，提醒一次 |
| 要求 | 碰到文档路径 | 回复里写一行 `Docs: updated / not needed / pending (理由)`（或中文「文档：已更新／无需更新／待更新（理由）」） |
| 适合 | 有明确文档约定的个人仓库 | 通用场景，不想用正则拦截提交命令 |

它要的是「写明评估结论」，不是「随便改一个 Markdown」。状态行只证明代理报告了，不证明文档写对了。

## 行为要点

- 每个用户回合开始时记下工作区与 HEAD 的快照；Stop 时对比，只看这一轮真正变了的非文档路径。
- 每个会话每轮最多提醒一次；`stop_hook_active` 为真或已提醒过就不再开口，防止续跑循环。
- Claude 返回 `additionalContext`，Codex 返回 `decision:"block"` + `reason`。两者都会让对话多跑一轮，不是零成本通知。
- 读不了输入、git 状态或超出资源预算时放行，但返回一条 `systemMessage` 明说「复核被跳过」，不装成通过。
- 状态文件放在 `<git-dir>/agent-doc-review/`，只存哈希，不存文件内容。
- 依赖：Node.js ≥ 20、PATH 上有 git；无第三方依赖、不联网、不提交、不改文档。

## 安装

解压后按包里的 `INSTALL-PROMPT.md` 操作，或把它交给 AI 代理：

1. 把 `.agent-hooks/` 复制到目标仓库根目录（先查冲突）。
2. 把 `config/claude.settings.fragment.json` 合并进 `.claude/settings.json`，`config/codex.hooks.fragment.json` 合并进 `.codex/hooks.json`。合并，不覆盖已有 hook。
3. 跑自带测试（命令见包内 README）。
4. 在客户端里用 `/hooks` 确认注册；Codex 还要完成信任审阅。在一次性仓库里各测一次「会提醒」「不提醒」「不循环」。

`AGENTS.example.md` 是一份配套的个人代理指引示例，只供参考合并，不要拿它替换现有的全局或仓库指令。

## 验证边界

- **已验证**：本站于 2026-09-27 在 Node 24（Linux/WSL）上跑过包内 35 条测试，全部通过。
- **未验证**：没有在真实的 Claude Code 或 Codex 客户端里做注册与端到端测试；也没在原生 Windows 上跑过。用之前请自己做第 4 步。
- 两家的 hook 事件与输出字段都在变，以当前官方文档为准。