Markdown Gatekeeper

项目简介

Markdown Gatekeeper 是一个本地优先的文档权威性管理工具，专门解决多人协作项目（尤其是人类开发者与 Claude、Codex 等 AI Agent 共存的代码库）中，Markdown 文档「谁说了算」的问题。AI Agent 往往会根据自身理解修改或新建文档，但如果没有任何机制来认定哪份文档是「权威版本」，人类维护者将面临严重的文档碎片化和信息不一致问题。Gatekeeper 的核心思路是：文档不会仅仅因为某个 AI Agent 声称它权威就变成权威——必须经过人类审核确认流程，才能被确立为当前权威文档。

核心功能

• 本地优先设计：无需云服务，无需 MCP 依赖，基于本地 Git 工作流，文档状态完全由仓库本身控制
• 零触摸初始化：运行 mdg init . 即可自动发现项目中的 AI 相关文档，完成分类、归档和权威性审查，无需人工干预
• 多 AI 主机适配：内置 Claude Code 和 Codex 适配器，支持一键安装对应的 Skill 和启动器，自动在相关 AI 主机中激活管理协议
• 证据链机制：每次文档发布都会生成不可变的 Evidence 记录，包含版本历史、变更原因和审核确认信息，支持追溯
• 争议文档隔离：未确认的多版本文档自动进入提案状态（docs/proposals/），只有经过人类审核通过后才能进入当前权威目录（docs/current/）
• 自动检测漂移：系统持续监控文档与代码实现的一致性，当代码变更快过文档更新时，自动标记风险
• 命令行工作流：提供完整的 CLI 工具集，支持 status、scan、resolve、reconcile、publish 等命令，融入现有开发流程

技术实现

Markdown Gatekeeper 的技术实现围绕「权威性判定」这一核心问题展开。系统不依赖任何远程服务，所有状态数据存储在仓库本地的 .authority/ 目录下。.registry.json 是当前权威文档的确定性指针映射，记录每份文档的最新确认版本；.authority/evidence/ 目录存放不可变的审查记录，每条记录对应一次发布事件，新记录仅记录变更部分而非全量复制；docs/current/ 存放已确认的权威文档；docs/proposals/ 存放待审核的提案文档。

在 AI 协同层面，Gatekeeper 为 Claude Code 和 Codex 分别提供独立的适配器，这些适配器在孤立环境中运行，不持有仓库写权限，只能提交格式验证过的审查数据。人类审核者通过 mdg adopt 流程处理来自 AI 的文档提案，最终由确定性发布者（publisher）控制写操作何时真正生效。这一设计确保了：即使 AI 声称某份文档是权威的，在人类明确审核确认之前，它不会进入 docs/current/ 目录。

初始化流程（mdg init）采用零触摸设计，系统自动推断哪些文档可能是 AI 创建或修改的，基于文件路径、命名模式和在 Git 历史中的出现时机进行分类，高置信度的文档自动发布，低置信度的进入人工审核队列，整个过程无需用户输入任何参数。

快速上手

第一步：安装 npm install -g github:nanlogic/markdown-gatekeeper

第二步：安装 AI 主机适配器 mdg setup claude（为 Claude Code 安装） mdg setup codex（为 Codex 安装） mdg setup status（验证安装状态）

第三步：初始化项目 mdg init .

第四步：日常使用 mdg status .：查看权威性状态 mdg scan .：扫描文档，发现重复或未管理的声明 mdg resolve ：查询特定主题的当前权威文档 mdg check .：检测直接编辑和注册表漂移

第五步：文档发布审核 mdg propose 创建提案 mdg publish 发布审核通过的文档

适用人群

• 多 AI Agent 协作项目的维护者：团队同时使用 Claude Code、Codex 等 AI 编程工具，容易出现文档版本混乱的开发者
• 重视文档准确性的开源项目：文档即产品的核心资产，需要防止 AI 自行更新文档导致信息失真的维护者
• AI 代码审查流程中的管理者：希望在 AI 提出的文档变更进入代码库前，有明确人工审核节点的项目负责人
• 大型代码库的技术负责人：代码量大、AI 工具使用频繁，需要追踪文档来源的开发者