Docguard

🛡️ DocGuard

English · Português (BR) · Español

规格驱动开发的执行层。 验证。评分。执行。交付 AI Agent 真正能用的文档。

---

✨ 30 秒内看看 DocGuard 能发现什么——无需安装，无需配置：

npx docguard-cli demo

使用内置的示例项目运行。该项目包含刻意设置的偏差，并会展示发现的问题以及清晰的修复路径。

📚 文档：安装 · 现有项目 · Spec Kit · CI · 语言和框架 · 编码 Agent · 问题代码 · 故障排查

---

目录

• DocGuard 是什么？
• 为什么选择 DocGuard？
• 快速开始
• Spec Kit 集成
• 用法
• 验证器
• 阅读问题
• 模板
• AI Agent 支持
• 斜杠命令
• 示例
• 测试
• 企业采用
• CI/CD 集成
• 最新动态
• 文件结构
• 配置
• 研究致谢

---

什么是 DocGuard？

DocGuard 强制执行规范驱动开发（CDD）——一种以文档为事实来源，而非事后补充的开发方法。AI 负责编写文档，DocGuard 负责验证文档。

传统开发	规范驱动开发
先写代码，文档可有可无	先写文档，代码遵循文档
文档悄然过时	跟踪并强制管理偏差
文档是可选的	文档是必需的，且需要验证
一个 AI Agent，一个上下文	任意 Agent，通过规范文档共享上下文

DocGuard 是官方 GitHub Spec Kit 社区扩展。它会验证 Spec Kit 创建的产物，确保规范在整个开发生命周期中始终保持高质量。

🧭 工作原理（9 页简介）（PDF） · 📖 理念 · 📋 CDD 标准 · ⚖️ 比较 · 🔬 验证 · 🗺️ 路线图

架构

graph TD
    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (27)"]
    Commands --> guard["guard"]
    Commands --> generate["generate"]
    Commands --> score["score"]
    Commands --> diagnose["diagnose"]
    Commands --> setup["setup wizard"]
    Commands --> other["diff · init · fix · trace · impact · sync · reconcile · retire · specs · ignore<br/>explain · memory · upgrade · agents · hooks · badge · ci · watch"]

    guard --> Validators["Validators (34)"]
    generate --> Scanners["Scanners (4)<br/>routes · schemas · doc-tools · speckit"]
    score --> Scoring["Weighted Scoring<br/>8 categories"]
    diagnose --> Validators
    diagnose --> AIPrompts["AI-Ready<br/>Fix Prompts"]

    Validators --> Output["Output"]
    Scanners --> Output
    Scoring --> Output
    Output --> Terminal["Terminal"]
    Output --> JSON["JSON"]
    Output --> Badge["Badge"]

    style CLI fill:#2d5016,color:#fff
    style Validators fill:#1a3a5c,color:#fff
    style Scanners fill:#1a3a5c,color:#fff
    style Output fill:#5c3a1a,color:#fff

分发方式：Node.js 核心（npm） · Python 封装（PyPI） · GitHub Action（action.yml） · Spec Kit 扩展（ZIP）

---

为什么选择 DocGuard？

DocGuard 会将已声明的文档事实与仓库证据进行核对，并为 Agent 提供结构化的修复任务。确定性检查涵盖受支持的事实、引用和生成的章节。当实现与人工编写的需求和架构决策不一致时，这些内容仍具有权威性。

守护结果会说明已执行的检查。CDD 等级衡量的是结构成熟度。.docguard-evidence.json 中的精确声明可以依据当前本地证据验证选定的陈述；其他所有陈述仍未经验证。覆盖情况和未解决的声明会保持可见，以便团队选择合适的执行策略。

研究为评估这一方法提供了动机。一项 2026 年的研究发现，在其评估的场景中，仓库上下文文件通常并未提升任务成功率，反而增加了推理成本。研究还发现，Agent 通常会遵循这些指令。这些结果支持测试简洁且相关的上下文，并衡量实际任务成效；但并不能证明 DocGuard 有效。评估 AGENTS.md，2026 年 6 月修订。

当前路线图优先关注准确检测、可复现的证据、文档生命周期管理，以及由贡献者提供的回归案例。已发布的计划和已被取代的规范会从活跃的 AI 上下文中移除，但仍可通过 Git 恢复。

---

⚡ 快速开始

软件包命名：本仓库为 raccioly/docguard；在 npm 和 PyPI 上发布的软件包均名为 docguard-cli；安装后使用的命令为 docguard。这是同一个项目——-cli 后缀只是软件包注册表中的名称。该软件包不会运行安装脚本，因此 npm i -g docguard-cli --ignore-scripts 与之等效。

Node.js（npm）

# No install needed — run directly
npx docguard-cli diagnose

# Or install globally
npm i -g docguard-cli
docguard diagnose

Python（PyPI）

pip install docguard-cli
docguard diagnose

**注意：**Python 软件包是一个轻量封装，会调用 npx。系统必须安装 Node.js 18 或更高版本。

Docker（MCP 服务）

MCP 服务以容器映像的形式发布在 GHCR 上——无需安装 Node.js。映像公开，无需身份验证即可拉取：

# Run the MCP server against the current directory
docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:latest

入口点使用 stdio MCP 传输：标准输出是 JSON-RPC 通道，因此不要向其中管道传入其他内容。将要检查的项目挂载到 /workspace；工具默认检查该目录，工具调用中的 projectDir 必须是 /workspace 或其内部的目录（在映像名称后添加 --root <dir>，即可服务于另一个已挂载的目录树）。

在 CI 中固定版本，而不是跟踪 latest：

docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:0.34.9

该服务为 只读——绝不会写入已挂载的项目。

更多集成方式

• pre-commit — 每次提交时进行仅针对变更内容的检查：

  repos:
    - repo: https://github.com/raccioly/docguard
      rev: v0.45.1
      hooks: [{ id: docguard-guard }]   # docguard-guard-full for pre-push
  

• MCP（Claude、Cursor、任何 MCP 客户端）— claude mcp add docguard -- npx -y docguard-cli mcp；提供只读工具来检查文档（guard、score、diagnose 等），并逐次浏览一个有界章节——完整列表见 docs/ai-integration.md。注册表清单位于仓库内（server.json，适用于 Smithery）。
• GitLab CI — 组件位于 templates/ci/gitlab-component.yml（guard/score/ci 任务，附带 SARIF 工件）。
• Homebrew — brew install raccioly/tap/docguard。发布工作流会从已发布的 npm tarball 渲染 packaging/homebrew/ 中的公式模板，并将其推送到 tap。

核心工作流

# 1. Initialize docs for your project
npx docguard-cli init

# 2. Or reverse-engineer docs from existing code
npx docguard-cli generate

# 3. AI diagnoses issues and generates fix prompts
npx docguard-cli diagnose

# 4. Validate — use as CI gate
npx docguard-cli guard

# 5. Check maturity score
npx docguard-cli score

AI 循环

diagnose  →  AI reads prompts  →  AI fixes docs  →  guard verifies
   ↑                                                       ↓
   └───────────────── issues found? ←──────────────────────┘

diagnose 是主要命令。它会运行所有验证器，将每项失败映射为 AI 可执行的修复提示，并输出修复计划。你的 AI agent 会运行它、修复文档，然后运行 guard 进行验证。

机械修复与 Agent 修复

DocGuard 将文档漂移分为两类，并明确区分：

类型	示例	修复方式
机械修复（确定性）	API-REFERENCE.md 中记录的端点已被 OpenAPI 规范确认不存在	docguard fix --write 会自行删除该行及详细说明块——无需 AI
Agent 修复（需要判断）	将 X-Ray 说明文字章节改写为 CloudWatch；编写新端点的请求/响应内容	通过 diagnose / fix --doc 提示交由 AI agent 处理

docguard fix --write 只会修改标记为 `` 的文档（可使用 --force 覆盖），支持幂等操作，并会准确打印变更内容。它绝不会改写说明文字——这由 agent 负责。

持续文档工作流

guard ──▶ fix --write (mechanical, auto) ──▶ guard ──▶ diagnose (agent prompts for the rest)

• CI / pre-commit：docguard hooks --type pre-commit --auto-fix 会安装一个钩子，应用机械修复、重新暂存文档，然后运行 guard；剩余问题会以 agent 提示的形式呈现。
• 由 Agent 驱动：docguard diagnose --auto 会搭建缺失文档的框架并应用机械修复，然后为剩余的内容改写任务生成提示。
• 供自动化使用的 JSON：guard/diagnose --format json 会包含 mechanicalFixes 数组，并为每个问题标注 mechanical 或 agent，以便 agent 精确地应用修复或委派处理。

---

🌱 Spec Kit 集成

DocGuard 是 GitHub Spec Kit 框架的一个社区扩展。Spec Kit 专注于通过 /speckit.specify 和 /speckit.plan 等 AI 斜杠命令创建规范；DocGuard 则专注于验证规范的质量。

它们如何协同工作

┌─────────────────┐          ┌──────────────────┐
│    Spec Kit      │          │    DocGuard       │
│                  │          │                   │
│  /speckit.specify│ ──────→  │  docguard guard   │
│  Creates specs   │          │  Validates specs  │
│  (AI-driven)     │          │  (automated)      │
└─────────────────┘          └──────────────────┘

阶段	工具	执行内容
1. 初始化	specify init	创建 .specify/ 目录和模板
2. 编写规范	/speckit.specify	AI 创建包含 FR-ID 和用户故事的 spec.md
3. 验证	docguard guard	检查规范质量（必需章节、FR/SC ID）
4. 规划	/speckit.plan	AI 创建包含技术上下文的 plan.md
5. 验证	docguard guard	检查计划质量（章节、结构）
6. 任务	/speckit.tasks	AI 创建包含分阶段任务拆分的 tasks.md
7. 验证	docguard guard	检查任务质量（阶段、T-ID）
8. 实现	/speckit.implement	AI 编写代码
9. 强制执行	docguard guard	最终质量关卡 — CI/CD

DocGuard 在 Spec Kit 项目中验证的内容

• spec.md — 必需章节（用户场景、需求、成功标准）、FR-xxx ID、SC-xxx ID
• plan.md — 摘要、技术上下文、项目结构章节
• tasks.md — 分阶段任务拆分（阶段 1、2、3+）、T-xxx 任务 ID
• constitution.md — 在 .specify/memory/constitution.md 或项目根目录检测
• 需求可追溯性 — FR、SC、NFR、US、AC、UC、SYS、ARCH、MOD、T ID

作为 Spec Kit 扩展安装

docguard init 会为你完成这些操作：当 specify CLI（Spec Kit ≥ 0.11.2，即扩展声明的最低版本）位于 PATH 中时，它会为仓库当前使用的编码 Agent 初始化 Spec Kit，然后注册已安装软件包中自带的 DocGuard 扩展。注册过程不会下载任何内容。如果项目已注册的扩展来自其他 DocGuard 版本，init 会在版本不同时重新注册（保留其优先级），docguard upgrade --apply 也会执行相同操作。只有在每个必需的钩子（speckit.docguard.brief 在 specify 前运行、speckit.docguard.preflight 在 tasks 前运行、speckit.docguard.guard 在 implement 后运行）都能解析为 Agent 可运行的命令文件后，init 才会提示工作流钩子已启用；否则会指出缺少哪个钩子。Spec Kit 不会为其 generic 集成注册扩展命令，因此对于 generic，DocGuard 会将这些命令写入 Spec Kit 自身命令所在的目录（默认是 .agent/commands/）。每次失败都会打印 Spec Kit 自身的错误信息和手动运行的命令。只有 init 和 upgrade --apply 会修改 Spec Kit；其他命令至多打印一行提示。

DocGuard 自身的技能会放在 Agent 读取技能的位置：Claude Code 使用 .claude/skills/（其他基于技能的集成使用其技能目录），通用集成或 DocGuard 无法放置技能的 Agent 使用 .agent/。对于仅支持命令的集成（例如 Gemini），DocGuard 会提供 Spec Kit 的 speckit.docguard.* 命令，不会额外复制文件。如果已安装，命令和技能文件会从 PATH 调用 docguard；否则会调用固定到其随附版本的 npx --yes docguard-cli@<version>；它们绝不会获取 @latest。

DocGuard 打印的建议（Next: …、Fix: …）只有在对应文件存在于 Agent 的目录中时才会提供斜杠命令，并采用该 Agent 使用的形式（Claude Code 中为 /speckit-docguard-guard，generic 中为 /speckit.docguard.guard）；否则会打印 CLI 命令。

docguard init 会注册已安装软件包中的扩展副本。若要自行注册，请使用发行版 ZIP 文件或本地检出版本。在默认的 Spec Kit 设置中，单独运行 specify extension add docguard 不起作用：DocGuard 位于 Spec Kit 的社区目录中，而 Spec Kit 仅使用该目录进行发现。

specify extension add docguard --from https://github.com/raccioly/docguard/releases/download/vX.Y.Z/spec-kit-docguard-vX.Y.Z.zip
specify extension add ./node_modules/docguard-cli/extensions/spec-kit-docguard --dev

有关钩子、规范生命周期注册表和端到端工作流，请参阅 Spec Kit 指南。

这会注册 extension.yml 中列出的 speckit.docguard.* 命令（在 Claude Code 等基于技能的 Agent 中以 /speckit-docguard-guard 等形式调用），以及运行这些命令的工作流钩子。

---

使用方法

DocGuard 提供 27 个命令（“日常 5 项” + 22 个情境工具，包括生命周期协调、文档依赖审查、需求锚点、Agent 规则解析、抑制项列表、退役与规范跟踪、零安装的 demo、mcp 服务以及 ci 流水线门禁）。另外 6 个一次性脚手架生成器可通过 docguard init --with <name> 使用。旧版命令形式在 v1.0 发布前仍保持兼容，并会显示对应的新命令。

日常 5 项——95% 的情况下，你会用到这些命令：

命令	功能
init	初始化项目（交互式操作使用 --wizard · 使用 --with <name> 调用脚手架生成器）
guard	根据规范文档进行验证——包含 34 个验证器
diff	显示文档与代码之间的差异（使用 --since <ref> 启用影响分析模式）
sync	刷新反映代码事实的文档章节，包括根据代码绘制的 module-graph 和 entity-diagram Mermaid 图表——始终保持记忆为最新状态
score	结构化 CDD 成熟度评分（0-100；并非 guard 判定结果；使用 --diff 比较不同引用之间的差异）

工具（按需使用，但适合日常工作）：

命令	用途
demo	零安装演示——使用内置的持续漂移测试样例运行 guard（npx docguard-cli demo）
diagnose	AI 编排器——一条命令完成 guard → 输出修复提示词
fix	为特定文档生成 AI 修复说明（--doc <name> --format prompt）
fix --write	应用确定性修复（不使用 AI——版本升级、计数、锚点、章节）
fix --history	查看每项已应用机械修复的审计日志（来自 .docguard/fixed.json）
generate	根据现有代码库逆向生成文档（AI 扫描使用 --plan）——会在 DATA-MODEL.md 中生成从检测到的架构（Prisma/Drizzle/TypeORM/Sequelize/Django/Rails）自动绘制的 Mermaid ER 图。--spec <area> 会为一个代码区域编写实况 Spec Kit 规格说明：为在那里找到的每个路由、导出符号、环境变量或实体生成一个需求候选项（每条陈述均由 Agent 编写），并登记为 origin: as_built；随后 guard 会报告新增或消失的事实（SPR007）
agent	单次执行的 Agent 任务图，或针对单项任务的有界当前证据包（--task <text>、--format json）
explain <warning|CODE>	粘贴任意警告——或类似 SEC001 的发现代码——即可获取验证器的文档字符串、修复路径以及抑制方式
verify --evidence	评估严格的陈述到源文件声明，涵盖带类型的 JSON 值、有界集合计数、已保存的 oasdiff JSON 和已保存的 Buf JSON Lines。结果会区分范围内的验证、矛盾、过时输入、证据不足和不支持的格式。
verify --semantic	提取文档中记载的数字/限制/枚举（保留天数、速率限制、GSI/角色数量、状态枚举），生成供 Agent 对照代码检查的任务列表——这是正则表达式/AST 无法发现的语义漂移类别
verify --instructions	审查 AGENTS.md/CLAUDE.md 本身是否存在漂移：重复规则、永不与始终矛盾、过时的文件指针、未知命令——并将成对聚类的规则列为需要 Agent 判断的任务
feedback	审查任意发现或合成的误报/漏报/不支持样例；验证其相反控制项，确定性地缩减样例，搜索开放和已关闭的重复项，并可选择输出仅用于测试的贡献。不会自动提交任何内容。
retire	查找已完成或已被取代的规划材料（--plan/--check；--fail-on-warning 会将建议性候选项设为门槛），并明确从活动 AI 上下文中移除干净的受跟踪文档。.docguard-archive.json 会记录恢复元数据和已退役的需求标识，--retention-ref 可证明源修订仍可访问。这与整合功能文档的 Spec Kit Archive 扩展相互独立。
reconcile	构建自某个 Git 引用以来只读的代码↔规格说明审查图。对机械事实、已批准意图、决策、不相关更改和不受支持的证据进行分类；--write 仅应用机械生成部分的刷新。
review	查找自上次审查以来所覆盖代码发生变化的文档章节（--accept <doc>#<id> --reason、--prune、--suggest）
anchors	列出每个 @implements/@req 标签、其解析到的需求，以及其锚定的符号、陈述、路由或文件，并显示用于解析的层级（--spec <id>、--file <path>、--format json）
ignore	列出项目中的所有抑制项（.docguardignore 条目及其 # reason 和 expires: 日期、.docguard.json 忽略数组、内联 pragma、N/A 标记、基线），并显示其状态；--format claimspec 会将带有原因的 .docguardignore 条目导出为 claimspec ignore 文档，并报告未纳入的内容
rules	查看各类运行环境（Codex、Claude Code、Cursor、Copilot、OpenHands）会为某个路径加载哪些 Agent 指令文件、加载原因以及字节数（--for <path>、--harness）
specs	维护带版本的规格说明注册表，对新规格说明进行预检，并应用由证据门控、结果有界且会重新生成活动上下文的完成事务。经验证的持续维护规格说明可记录后续审查维护，而无需重新打开或重复编写规格说明。specs require 是规格说明优先门槛：对受管路径的更改必须指定其规格说明，或声明 Spec-Exempt: <kind> — <reason>。
specs --check / specs --write	验证或刷新 .docguard-specs.json，该文件是不可变规格说明 ID、经审查的生命周期/沿袭/范围、产物摘要、任务状态、明确限定范围的测试证据以及归档墓碑的字节稳定索引。刷新会保留已审查区块。
specs preflight [--path <spec>]	编写规格说明前，打印当前规格说明的生命周期和证据。规划前，检查生成的草稿是否存在结构性阻碍，并将语义重叠作为仅供审查的证据报告。
specs approve --id <spec-id>	在注册表中记录某人对某项规格说明的批准；使用 --delivery 时，还可记录其 planned、in_progress 或 implemented 状态。默认仅生成计划；使用 --write 才会记录。验证仍由 specs complete 负责。
mcp	MCP 服务——将检查功能（guard、score、explain、verify、report、diagnose）和精确的文档导航（某个文件的文档、文档大纲、单个章节、任务上下文）作为原生工具提供给 Claude、Cursor 和任何 MCP 客户端；docguard_guard 每条事实只返回一次，除非调用时设置 detail: "full"。Stdio：claude mcp add docguard -- npx docguard-cli mcp。团队共享 HTTP：docguard mcp --transport http --port 8585（默认绑定环回地址；绑定非环回地址时必须使用 --api-key）
report	用于审计的合规证据包——包含就绪情况、guard 判定、结构成熟度、ALCOA+ 属性和修复历史，并附带 Git 提交和具备篡改检测功能的 sha256 完整性哈希（--format json、--out <file>）。仅提供证据，不作为门槛：始终以 0 退出
ci	流水线门槛：通过一条命令完成 guard + 结构成熟度检查，并评估为 READY/ATTENTION/BLOCKED——绝不生成脚手架或修改源文件；唯一写入项是其自身的 .docguard/history.jsonl（可使用 --no-history 禁用）。--threshold <n> 会在分数低于指定值时失败，严格模式使用 --fail-on-warning，解析器使用 --format json
score --trend	根据记录的 ci 运行结果查看分数走势——迷你趋势图、变化量，以及带提交标记的最近 10 次运行
memory	按领域汇总准确性概况（端点 / 实体 / 环境 / 技术）
memory --diff	深入查看哪些具体声明与代码不符
memory --pack	写入 .docguard/context-pack.md——适用于 AI Agent 会话启动的精简上下文，并标明代码事实依据
score --diff	深入查看哪些检查拉低了各项分类的分数
trace / trace --reverse <file>	需求可追溯性——正向和反向追踪
trace --features	按功能查看规格说明遵循度评分（需求覆盖率、任务完成度、任务证据、产物）——按问题严重程度从高到低排列，并附修复提示
upgrade [--apply] [--pr]	检查 npm 是否有较新的 CLI（唯一会联系注册表的命令），并迁移 .docguard.json 架构；--pr 会创建 PR。安装的版本发布超过 14 天后，guard 的文本输出、MCP 服务和上下文包会建议运行 docguard upgrade；不会自动升级任何内容（DOCGUARD_NO_UPDATE_HINT=1 可关闭提示）
watch	实时模式：文件更改时重新运行 guard
init --with <name> 脚手架工具——在初始化时选择：

脚手架工具	生成内容
agents	AGENTS.md、CLAUDE.md、.cursor/rules/、.github/copilot-instructions.md
hooks	Git pre-commit / pre-push 钩子
ci	GitHub Actions / 流水线 YAML
badge	README 的 Shields.io 评分徽章
llms	llms.txt（便于 AI 阅读的摘要）
publish	外部文档站点配置（Mintlify）——实验性功能

单独运行（docguard init --with hooks），或组合运行（docguard init --with agents,hooks,badge,ci）。

要声明确切事实，请将 templates/evidence-manifest.json 复制到 .docguard-evidence.json，将其中的字面 Markdown 模板指向一条唯一陈述， 并将该值绑定到受支持的本地来源。在 CI 中启用守护程序之前，先运行 docguard verify --evidence --format json。 外部兼容性声明使用已保存的 oasdiff 或 Buf 输出，并要求为每个声明的仓库输入提供当前的 SHA-256 标识。

弃用别名——setup · agents · hooks · badge · llms · publish · impact 在 v1.0 前仍保持兼容，并会在 stderr 中显示黄色警告。audit → guard 为永久别名且不显示警告；ci 是当前的一等流水线命令。

CLI 标志

标志	说明	命令
--dir <path>	项目目录（默认：.）；显式选择后，不再提供祖先根目录指引	全部
--verbose	显示详细输出	全部
--quiet / -q	不显示横幅 — 适用于钩子、CI 循环和脚本	全部
--format json	机器可读输出（纯净 JSON，不含 ANSI 转义序列）	guard、score、diff、trace、diagnose、memory、impact、explain、verify、reconcile、retire、specs、ignore
--format claimspec	在 stdout 输出 claimspec v1 ignore 文档，并根据随附的 schema 验证；无法导出的内容会发送到 stderr	ignore
--format sarif	输出 SARIF 2.1.0 — 将发现项作为规则/结果，供 GitHub Code Scanning 和 SARIF 仪表板使用	guard
--format junit	输出 JUnit XML — 每个验证器对应一个 testcase，适用于 GitLab CI（artifacts:reports:junit）、Jenkins、Azure DevOps、CircleCI	guard
--update-baseline	在旧版仓库中采用 DocGuard，避免第一天就出现红灯：将今天的发现项冻结到已提交的 .docguard.baseline.json 中；此后 guard/ci 只会拦截新增偏差。抑制情况始终可见（“已抑制 N 个既有发现项”），而 --no-baseline 会显示完整情况	guard
--full	生成 llms-full.txt（内联完整文档正文），而不是 llms.txt 链接索引	llms
--compact	与 --format json 搭配使用：每项事实只出现一次，格式与 MCP guard 工具默认返回的格式相同	guard
--pack	写入 .docguard/context-pack.md — Agent 会话启动上下文	memory
--symbols	与 --pack 搭配使用：添加符号映射（最核心的文件及其导出名称，大小不超过 memory.symbolMap.maxBytes）；需主动启用：冻结的 Agent 上下文基准测试（协议 v3）显示此功能没有退步，也没有收益，因此默认不启用	memory
--sync	从 AGENTS.md 重新生成 Agent 文件系列（CLAUDE.md、Copilot、Cursor 等）；带哈希标记，除非使用 --force，否则绝不触碰手动编写的文件	agents
--check	对已同步的 Agent 文件系列进行 CI 门禁 — 若某个变体已过时，则以状态码 2 退出	agents
--force	覆盖现有文件（创建 .bak 备份）	generate、agents、init
--force-redo	绕过 .docguard/fixed.json 中的往返抑制	fix --write
--profile <name>	入门版 / 标准版 / 企业版	init
--no-spec-kit	跳过 Spec Kit：不调用 specify，也不创建 .specify/；仍会安装 DocGuard 自带的 Agent 技能	init
--spec-kit	与 --profile starter 搭配使用，同时初始化 Spec Kit（入门版默认跳过）	init
--changed-only [--since <ref>]	提交前轻量模式：仅对已更改文件运行快速验证器（包括受覆盖文档的依赖项）	guard
--timings	按验证器显示耗时分析（从最慢到最快）	guard
--show-failing	即使状态为 PASS，也显示警告/错误	guard
--pin	将正在运行的 CLI 版本记录到 .docguard.json 中（确保可复现）	guard
--diff	按类别深入查看	score、memory
--check-only	若版本落后则以状态码 1 退出（用于 CI）	upgrade
--apply	实际执行迁移	upgrade
--pr	创建包含迁移内容的 PR	upgrade
--reverse <file>	反向追踪（代码 → 文档）	trace
--no-indirect	跳过反向导入图分析（分析引用了已更改文件的模块相关文档）	impact、diff --since
--prs	分析未合并 PR 的文档冲突 — 两个 PR 影响同一规范文档 = 合并顺序风险（需要 gh CLI）	impact
--transport http --port --host --api-key --path	通过 Streamable HTTP 而非 stdio 提供 MCP 服务（团队共享服务；除非设置了 api-key，否则仅限环回访问）	mcp
--root <dir>	提供另一目录树的服务：工具调用可传入其中的 projectDir（可重复指定）。若未设置，则 projectDir 必须位于所提供服务的目录内	mcp
--history	显示修复审计日志	fix
从嵌套包中运行且未指定 --dir 时，DocGuard 只检查所选目录。如果有界祖先目录扫描发现某个 .docguard.json 或 npm/pnpm 工作区声明涵盖了该包，stderr 会显示一条精确的仓库范围重运行命令。DocGuard 不会自动更改范围。JSON、SARIF 和 JUnit 的 stdout 输出仍然有效；机器运行会在 stderr 上收到一条类型化的 docguard.repository-root-guidance JSON 诊断信息。本地配置、显式指定 --dir、未匹配的工作区或嵌套的 Git 边界都会抑制此建议。

示例输出

$ npx docguard-cli generate

🔮 DocGuard Generate — my-project
   Scanning codebase to generate canonical documentation...

  Detected Stack:
    language: TypeScript ^5.0
    framework: Next.js ^14.0
    database: PostgreSQL
    orm: Drizzle 0.33
    testing: Vitest
    hosting: AWS Amplify

  ✅ ARCHITECTURE.md (4 components, 6 tech)
  ✅ DATA-MODEL.md (12 entities detected)
  ✅ ENVIRONMENT.md (18 env vars detected)
  ✅ TEST-SPEC.md (45 tests, 8/10 services mapped)
  ✅ SECURITY.md (auth: NextAuth.js)
  ✅ REQUIREMENTS.md (spec-kit aligned)
  ✅ AGENTS.md
  ✅ CHANGELOG.md
  ✅ DRIFT-LOG.md

  Generated: 9  Skipped: 0

---

🔍 验证器

每次 guard 检查时，DocGuard 都会运行 34 个自动化验证器。在适用其证据模型的情况下，面向源代码的验证器会识别语言；仓库和文档验证器则独立于源代码语言运行。

计数说明： guard 会打印 30 行结果，而不是 29 行。Structure 会在同一个验证器键下发出第二条检查结果（Doc Sections），因此行数代表的是检查项，而不是验证器。公布的数量是已发布的 cli/validators/*.mjs 模块数，并由测试强制执行——不要通过计算输出行数来推断。 | # | 验证器 | 检查内容 | 默认状态 | |:--|:----------|:--------------|:--------| | 1 | Structure | 必需的 CDD 文件是否存在；每条 AGENTS.md 链是否符合 Agent 的加载限制（默认 32 KiB；针对现有债务按链设置额度） | ✅ 已启用 | | 2 | Doc Sections | 规范文档是否包含必需章节（或 N/A 标记） | ✅ 已启用 | | 3 | Docs-Sync | 文档中引用的路由/服务及 OpenAPI 交叉检查 | ✅ 已启用 | | 4 | Drift-Comments | // DRIFT: 注释是否记录在 DRIFT-LOG.md 中（默认跳过测试文件） | ✅ 已启用 | | 5 | Changelog | CHANGELOG.md 是否包含 [Unreleased] 章节 | ✅ 已启用 | | 6 | Test-Spec | 是否按 TEST-SPEC.md 规则编写测试 | ✅ 已启用 | | 7 | Environment | 是否记录环境变量，是否存在 .env.example | ✅ 已启用 | | 8 | Security | 源代码中是否存在硬编码密钥 | ✅ 已启用 | | 9 | Architecture | 导入是否遵循分层边界（遵循 config.ignore） | ✅ 已启用 | | 10 | Freshness | 文档是否相对于代码变更过时（通过 git log --follow 感知重命名） | ✅ 已启用 | | 11 | Traceability | 需求 ID（FR、SC、NFR、US、AC、T）是否可追溯到测试 | ✅ 已启用 | | 12 | Docs-Diff | 代码产物是否与文档中记录的实体一致 | ✅ 已启用 | | 13 | API-Surface | API-REFERENCE.md 中的端点是否与实际路由一致（OpenAPI 交叉检查） | ✅ 已启用 | | 14 | Metadata-Sync | 文档中的版本引用是否一致 | ✅ 已启用 | | 15 | Docs-Coverage | 代码功能是否在文档中有所提及 | ✅ 已启用 | | 16 | Doc-Quality | 写作质量（可读性、被动语态、原子性、IEEE 830） | ✅ 已启用 | | 17 | TODO-Tracking | 未跟踪的 TODO/FIXME 和跳过的测试（默认跳过测试文件） | ✅ 已启用 | | 18 | Schema-Sync | 数据库模型是否记录在 DATA-MODEL.md 中 | ✅ 已启用 | | 19 | Spec-Kit | 规范质量验证（FR-ID、必需章节、分阶段任务、唯一规范编号） | ✅ 已启用 | | 20 | Document-Lifecycle | 精确的终止状态、提示性完成信号、覆盖不完整情况，以及清单/工作树不一致 | ✅ 已启用 | | 21 | Spec-Registry | 不可变的规范标识、字节稳定的证据投影、已审查生命周期的保留，以及归档/存储一致性 | ✅ 已启用 | | 22 | Evidence | 精确声明的 Markdown 语句是否与当前类型化 JSON、有界集合或已保存的兼容性报告相符；不受支持和缺失的证据仍会显示 | ✅ 已启用 | | 23 | Cross-Reference | 内部 Markdown 链接和锚点是否有效（提供“你是不是想说……”提示）；当仓库将 Obsidian 双链用作文件链接时（存在 .obsidian 或目标可解析），会验证这些链接 | ✅ 已启用 | | 24 | Generated-Staleness | source=code 章节是否与扫描器输出一致；status: draft 文档的时效性 | ✅ 已启用 | | 25 | Canonical-Sync | DocGuard 自身 README 中的数量声明是否符合代码事实（仅限 DocGuard 仓库——其他地方为 N/A） | ✅ 已启用 | | 26 | Metrics-Consistency | 硬编码数字是否与实际计数一致，包括针对 package.json 的运行时依赖声明（也会读取 Spec Kit 章程） | ✅ 已启用 | | 27 | Surface-Sync | 条目级可枚举漂移——文档表格/列表中的名称（命令、检查项等）是否与代码事实一致（通过 surfaceSync.surfaces 启用；未配置时为 N/A） | ✅ 已启用 | | 28 | Diff-Suspicion | 变更驱动检查：若文档/Agent 指令文件引用了自 ref 以来变更的代码，且共享已移除的领域符号，则会标记以供审查（arXiv 2010.01625，F1 74.7） | ✅ 已启用 | | 29 | Reference-Existence | 双版本检查：若反引号括起的代码符号在文档上次更新时存在、但在 HEAD 中已不存在，则会标记为过时（arXiv 2212.01479） | ✅ 已启用 | | 30 | API-Doc-Smells | 过长（≥300 个单词）/过简（≤6 个正文词）的 API 文档单元，以签名标题章节为依据（F1 0.90/0.95） | ✅ 已启用 | | 31 | Doc-Dependency | 声明了 covers= 的文档章节：若所覆盖符号的代码自上次 docguard review --accept 以来发生语义变更，则会报告（格式、注释和行移动不计）；需通过声明启用 | ✅ 已启用 | | 32 | Path-Scoped-Rules | 各执行环境的 Agent 指令文件（嵌套的 AGENTS.md/CLAUDE.md、Claude Code 规则和技能、Cursor .mdc、Copilot .instructions.md、OpenHands 技能）：不匹配任何已跟踪文件的作用域 glob、指向缺失路径的引用（包括路由表）、针对某一路径加载且超出字节预算的指令，以及执行环境无法读取的作用域 | ✅ 已启用 | | 33 | Doc-Ownership | 在 .docguard.json 中设置 ownership 映射时：没有文档章节负责的源目录、两个同等具体的所有者、不匹配任何内容的模式、指向缺失文档的条目；还会根据 Devin 的限制检查已提交的 .devin/wiki.json，并检查其中路径是否已不存在 | ✅ 已启用 | | 34 | Suppressions | .docguardignore 中 expires: 日期已过期（不再排除任何内容）、失效日期不是日历日期，或设置了 suppressions.requireReason 但没有 # reason 的条目 | ✅ 已启用 | | 35 | Requirement-Anchors | 使用 .docguard-anchor-lock.jsonl 或 anchors.enabled 时：自审查后代码或需求发生变更的已审查代码→需求链接（ANC001/ANC002）、标签已不存在的已审查链接（ANC003）、引用未声明或已退役需求的标签（ANC007/ANC008）、锁定文件问题（ANC005/ANC009），以及读取文件时低于其精确层级的情况（ANC010）。docguard anchors 会列出所有链接；anchors accept 会记录审查 | ✅ 已启用 | 按验证器控制（位于 .docguard.json 中）：

{
  "validators": {
    "test-spec": false,                 // disable (kebab-case OR camelCase both accepted)
    "freshness": true
  },
  "severity": {
    "todoTracking": "high",             // warnings fail CI
    "freshness": "low"                  // warnings ignored for exit code
  },
  "findingSeverity": {
    "TRC004": "low",                    // only this finding becomes informational
    "SEC001": "high"                    // this exact code always blocks
  }
}

精确的 findingSeverity 条目优先于验证器严重级别。Guard JSON、SARIF 和 JUnit 会保留检测器的固有严重级别，并添加有效严重级别 以及策略来源。除非明确配置了对应的精确稳定代码，否则固有错误仍会阻止流程。

---

🎚️ 解读一条发现

一条发现过去只用一个 confidence 字段回答一个问题——“你应该有多担心？”——这意味着该字段同时承担了三个互不兼容的职责。DocGuard 现在将它们分开。这些维度彼此独立：会阻止流程的 error 可能是升级处理，而 high 置信度的发现仍可能需要由人工判断。

字段	回答的问题	值
severity / effectiveSeverity	CI 是否会阻止流程？	error、warn、info
disposition	由谁决定——工具还是你？	act、escalate
confidence	检测器对其观察结果有多确定？	high、low
evidence.status	经审核的语料库是否测量过此代码？	measured、not-measured
parserTier	是哪个分析器生成了它？	js-ast、py-ast、regex-fallback、fallback-language、mixed、not-applicable

act — DocGuard 确认存在缺陷并指出修正方法。可以安全应用，包括通过 docguard fix 或 Agent 应用。

escalate — DocGuard 观察到一个信号；由你来判断。新鲜度 FRS002（“自文档审核以来已有 13 次代码提交”）是典型情况：计数来自 git log，因此精确且 confidence: high——但它只表明文档该审核了，绝不表示文档有误。为了不再显示升级提示而编辑文档，会破坏信号，却无法解决任何问题。经过判断后保留升级提示，也是正确的处理结果。

evidence.status 会告诉你置信度标签有多大参考价值。measured 会引用经过审核的精确率语料库，并给出 n 和 Wilson 下界；not-measured 表示该标签只是维护者的先验判断，仅此而已。大多数代码都未经测量——这不代表其发现有误，只代表未经验证；docguard feedback 正是出于这个原因对它们进行抽样。

parserTier 会告诉你检测器能看到什么。js-ast 和 py-ast 表示使用了语法树。regex-fallback 表示该语言有解析器（JS/TS、Python），但该文件无法使用解析器。fallback-language 表示 DocGuard 完全没有该语言的解析器——Go、Java、Kotlin、Ruby、Rust、PHP、C#——因此其中的路由和环境变量读取会按模式匹配。无论哪种情况，未发现问题都只是弱证据；所属验证器会报告 applicability: partial，并说明语言和文件数量。所有受支持语言中的环境变量都会按模式匹配；没有环境变量模式的源语言（Swift、Scala 等）会使 Environment 检查结果为 partial，而不是静默通过。

每条发现都会在 guard --format json 中显示所有渠道，在 SARIF 的 result.properties 中显示，并在 diagnose --format json 中按问题显示（该命令还会输出 dispositionCounts 汇总）。guard、diagnose、ci 和 report 都会在判定结果旁打印 act/escalate 分类；report 还会在发现表中为每个渠道添加一列。运行 docguard explain <CODE> 可查看单个代码的证据。

---

📄 模板

DocGuard 提供 18 个专业模板，包含元数据、徽章和修订历史：

模板	类型	用途
ARCHITECTURE.md	标准	系统设计、组件、分层边界
DATA-MODEL.md	标准	架构、实体、关系
SECURITY.md	标准	身份验证、权限、密钥管理
TEST-SPEC.md	标准	测试策略、覆盖率要求
ENVIRONMENT.md	标准	环境变量、部署配置
REQUIREMENTS.md	标准	与 Spec-kit 对齐的 FR/SC ID、用户故事
DEPLOYMENT.md	标准	基础设施、CI/CD、DNS
ADR.md	标准	架构决策记录
ROADMAP.md	标准	项目阶段、功能跟踪
KNOWN-GOTCHAS.md	实现	症状 → 易错点 → 修复条目
TROUBLESHOOTING.md	实现	错误诊断指南
RUNBOOKS.md	实现	运维流程
VENDOR-BUGS.md	实现	第三方问题跟踪器
CURRENT-STATE.md	实现	部署状态、技术债务
AGENTS.md	Agent	AI Agent 行为规则
CHANGELOG.md	跟踪	变更日志
DRIFT-LOG.md	跟踪	偏差跟踪
llms.txt	生成	适合 AI 阅读的项目摘要（llmstxt.org）

---

🤖 AI Agent 支持

一键安装 MCP

• Claude Code：claude mcp add docguard -- npx docguard-cli mcp
• Claude Desktop：从最新版本下载 docguard-v<version>.mcpb，并将其拖到 Settings → Extensions 中——系统会询问要分析哪个项目文件夹。无需 npm，也无需编辑 JSON。
• Anything MCP：DocGuard 是官方 MCP 注册表中的已验证命名空间（io.github.raccioly/docguard）。

DocGuard 兼容 所有主流 AI 编码 Agent。所有标准文档均为纯 Markdown——不会被供应商锁定。

Agent	兼容性	自动生成配置
Claude Code	✅	docguard agents --agent claude
GitHub Copilot	✅	docguard agents --agent copilot
Cursor	✅	docguard agents --agent cursor
Windsurf	✅	docguard agents --agent windsurf
Cline	✅	docguard agents --agent cline
Google Gemini CLI	✅	docguard agents --agent gemini
Kiro (AWS)	✅	—

常驻提醒钩子（Claude Code）

docguard hooks --claude            # install   (remove: docguard hooks --claude --remove)

在项目的 .claude/settings.json 中注册一个 PostToolUse 钩子。Agent 编辑标准文档后，系统会提醒它运行 docguard guard --changed-only；编辑文档引用的代码文件后，则会提醒它运行 docguard impact。支持安全合并（只会添加或移除 DocGuard 自身的条目），每个文件每 30 分钟最多提醒一次，并且钩子运行时绝不会中断会话（按约定静默处理错误）。需显式选择启用——init 不会为你安装此钩子。

---

⚡ 斜杠命令

DocGuard 提供四个斜杠命令（此仓库中的 commands/）：

命令	功能
/docguard.guard	运行所有验证器的质量验证
/docguard.review	分析文档质量并提出改进建议
/docguard.fix	针对具体问题生成定向修复提示词
/docguard.score	CDD 成熟度评分及改进路线图

命令的安装位置取决于你使用的 Agent。对于使用技能的 Spec Kit 集成（Claude Code、 Codex、Cursor、Copilot），DocGuard 会改为安装其技能，Spec Kit 则会安装 speckit.docguard.* 扩展命令。只有在 Spec Kit 的 generic 集成中，或不存在 Spec Kit 集成时，/docguard.* 文件才会写入 .agent/commands/。 编码 Agent 参考列出了各个 Agent 对应的确切路径。

---

🧠 AI 技能（企业版）

除斜杠命令外，DocGuard 还提供 5 项企业级 AI 技能——深入的行为协议，不仅告诉 AI Agent 运行什么，还会指导它们如何思考、验证和迭代。技能的设计参考了 Spec Kit 的技能架构。

技能	功能
docguard-guard	6 步质量门禁，包含严重性分级（CRITICAL→LOW）、结构化报告和修复
docguard-fix	7 步调研工作流，包含针对每份文档的代码库调研和 3 轮迭代验证
docguard-review	只读的语义跨文档分析，包含 6 轮分析和质量评分
docguard-score	CDD 成熟度评估，附带基于 ROI 的改进路线图和等级提升路径
docguard-sync	就地刷新反映代码实际情况的文档章节，并在代码变更时标记需要审阅的文字说明章节

工作流钩子

DocGuard 作为自动化质量门禁集成到 spec-kit 工作流中：

钩子	触发时机	行为
before_specify	/speckit.specify 之前	必需 — 向 Agent 介绍现有规范（speckit.docguard.brief）
before_tasks	/speckit.tasks 之前	必需 — 对生成的规范执行预检（speckit.docguard.preflight）
after_implement	/speckit.implement 之后	必需 — 运行 DocGuard guard；随后可选择记录完成状态
after_converge	/speckit.converge 之后	可选 — 记录规范完成状态（speckit.docguard.complete）
after_tasks	/speckit.tasks 之后	可选 — 显示 CDD 成熟度评分

编排脚本

对于高级用户和 CI/CD 管道，DocGuard 提供带有 --json 输出的 bash 脚本：

脚本	用途
docguard-check-docs.sh	发现项目文档，返回包含元数据的 JSON 清单
docguard-suggest-fix.sh	运行 guard、解析结果并输出按优先级排序的修复项
docguard-init-doc.sh	初始化带有元数据标题的规范文档

---

📁 示例

通过三个真实项目了解 DocGuard 的实际效果：

示例	场景	展示内容
01-express-api	没有任何文档的 Node.js API	从零启动：generate → 立即获得文档覆盖
02-python-flask	文档已偏离的 Python 应用	偏离检测：发现文档与实际情况不符
03-spec-kit-project	完整的 CDD + Spec Kit	黄金标准：了解成熟度的体现

请参阅 examples/README.md 查看分步说明。

---

🧪 测试

测试套件

npm test    # 3,283 tests (node:test, zero test dependencies)

覆盖全部 27 条命令、所有验证器、项目类型检测、合规配置文件、JSON/SARIF/JUnit 输出、打包后的 npm tarball，以及重放为回归用例的下游实测报告。静态测试用例声明的数量是该数字的下限：如果该数字低于测试文件声明的数量，Metrics-Consistency 就会标记此行。

CI 矩阵

Node.js	OS	状态
18	ubuntu-latest	✅
20	ubuntu-latest	✅
22	ubuntu-latest	✅
24	ubuntu-latest	✅

自我验证（自用验证）

DocGuard 会在 CI 中对自身运行 guard、score、diff、diagnose 和 badge 命令，确保该工具通过自身的检查。

---

🏢 企业采用

所有操作都在本地或 CI 中运行——无需 SaaS，也不会有数据离开你的基础设施。 适用于公司规模的关键功能：

需求	DocGuard 方案
在旧代码仓库中采用，且第一天不会导致流水线失败	guard --update-baseline 会将现有问题冻结到已提交的 .docguard.baseline.json 中；此后只有新的偏差会触发拦截（抑制项始终可见）
合规审查的审计轨迹	docguard report——带有提交标记的证据包（guard 判定、按代码分类的问题、CDD 评分、ALCOA+ 数据完整性属性、修复历史），并附带防篡改的 sha256 完整性哈希
所有 CI 系统，不只是 GitHub	guard --format sarif（GitHub Code Scanning）· --format junit（GitLab、Jenkins、Azure DevOps、CircleCI）· --format json（其他任意系统）
发展轨迹，而非快照	docguard ci 会将每次运行记录到 .docguard/history.jsonl；score --trend 会显示迷你趋势图和变化量
团队中的 AI Agent	MCP 服务（stdio 或团队共享的 HTTP）以只读工具形式提供 guard、score、verify、report、文档导航和任务上下文；agents --sync 可防止整套 Agent 文件出现偏差
审计人员熟悉的数据完整性框架	score 和 report 内置 ALCOA+ 评分（采用 FDA 21 CFR Part 11 / EMA Annex 11 术语）

⚙️ CI/CD 集成

**完整配置示例：**请参阅 docs-canonical/CI-RECIPES.md，了解 guard、自动修复（将机械性修复提交回 PR）、夜间同步、PR 评分和 pre-commit 配置。

GitHub Actions — Guard（最常见）

name: DocGuard Guard
on: [pull_request, push]
permissions: { pull-requests: write }   # for the sticky PR comment (optional)
jobs:
  docguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: raccioly/[email protected]
        with:
          command: guard

该 Action 会安装发布时配套的 docguard-cli 版本，因此固定 Action 版本也会固定 CLI 版本。设置 docguard-version: latest（或指定确切的 x.y.z）即可覆盖。

在拉取请求中，guard 模式还会提供 PR 行内反馈（两项默认均已启用）：

输入项	默认值	描述
annotations	true	在 PR 差异中添加行内 ::error/::warning 注解，每个 guard 问题对应一条（最多 50 条；最后会提示省略了多少条）
pr-comment	true	添加置顶 PR 评论，包含 guard 判定、主要问题（按代码分类），以及 PR 修改的文件会影响哪些规范文档（diff --since origin/<base>）。需要 permissions: pull-requests: write；若未配置，则降级为日志警告

即使 guard 失败，两项功能也会运行——这正是反馈最重要的时候。想要使用原生代码扫描集成？通过 docguard guard --format sarif，即可使用 github/codeql-action/upload-sarif 直接上传到 GitHub Code Scanning。

GitHub Actions — 自动修复（将机械性修复提交回 PR）

name: DocGuard Auto-Fix
on: { pull_request: { types: [opened, synchronize, reopened] } }
permissions: { contents: write, pull-requests: write }
jobs:
  autofix:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.full_name == github.repository
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 0
      - uses: raccioly/[email protected]
        with: { command: fix, auto-commit: 'true', comment-on-pr: 'true' }

Pre-commit 钩子

npx docguard-cli hooks --type pre-commit

工作流模板（可直接复制）

Spec Kit 扩展和独立文件中都附带两个可直接使用的模板：

• extensions/spec-kit-docguard/templates/github-workflows/docguard-guard.yml — 必需的 CI 门禁
• extensions/spec-kit-docguard/templates/github-workflows/docguard-autofix.yml — PR 自动修复

✨ 最新动态

近期版本亮点：

• 校准后的发现通道 — 现在每条发现都包含 disposition、evidence.status 和 parserTier，与 severity 和 confidence 并列，因此“是否阻止 CI”“由谁决定”“检测器有多确定”“是否测量过这段代码”以及“由哪个分析器发现”不再挤在一个过载字段中。请参阅解读发现。
• 采用基线 — guard --update-baseline 会将旧版代码库现有的发现固化到已提交的 .docguard.baseline.json 中；之后，guard/ci 只会拦截新的偏差，且抑制项始终清晰可见。现在即可采用，按自己的节奏逐步清理。
• docguard report — 带提交标识的合规证据包（guard 判定、按代码分类的发现、CDD 评分、ALCOA+ 属性、修复历史），并附带防篡改的 sha256 完整性哈希。也作为 docguard_report MCP 工具提供。
• 评分历史 + score --trend — docguard ci 会将每次运行记录到 .docguard/history.jsonl；趋势视图会显示迷你折线图和随时间变化的差值。
• guard 的三种机器可读格式 — --format json、--format sarif（GitHub Code Scanning）和 --format junit（GitLab、Jenkins、Azure DevOps、CircleCI）。
• MCP 服务，支持 stdio + 团队 HTTP — 将 guard、score、verify、report、文档导航和任务上下文作为只读 Agent 工具：claude mcp add docguard -- npx docguard-cli mcp。
• Agent 文件系列同步 — agents --sync 将 AGENTS.md 视为规范来源，并重新生成 CLAUDE.md / .cursor/rules / Copilot / Gemini 变体，同时添加可防止偏移的来源哈希标记。
• verify --evidence、verify --semantic 和 verify --instructions — 首先检查精确的本地证据声明，将剩余的数字/限制/枚举提取为 Agent 任务，并审查 Agent 指令文件中的矛盾和过时指针。
• docguard agent — 一次性执行有序任务图，并预先填入代码事实，将约 10 次 Agent 往返合并为一次调用。
• docguard agent --task <text> — 可选地从经批准的现行规范和规范文档中获取任务上下文，并提供带哈希的摘录、来源/测试指针、严格预算和如实弃答。冻结的 27 次运行评估保留了所有受测行为；与上下文包相比，中位步骤数减少了 50%，延迟降低了 17%，但未缓存的输入令牌增加了 80%。

完整历史请参阅 CHANGELOG.md。

---

📁 文件结构

your-project/
├── .specify/                        # Spec Kit (if using specify init)
│   ├── specs/
│   │   └── 001-feature/
│   │       ├── spec.md              # Requirements (FR-IDs, user stories)
│   │       ├── plan.md              # Implementation plan
│   │       └── tasks.md             # Task breakdown
│   ├── memory/
│   │   └── constitution.md          # Project principles
│   └── templates/
│
├── docs-canonical/                  # CDD canonical docs (the "blueprint")
│   ├── ARCHITECTURE.md              # System design, components
│   ├── DATA-MODEL.md                # Database schemas
│   ├── SECURITY.md                  # Auth, permissions, secrets
│   ├── TEST-SPEC.md                 # Required tests, coverage
│   ├── ENVIRONMENT.md               # Environment variables
│   └── REQUIREMENTS.md              # Spec-kit aligned FR/SC IDs
│
├── docs-implementation/             # Current state (optional)
│   ├── KNOWN-GOTCHAS.md
│   ├── TROUBLESHOOTING.md
│   ├── RUNBOOKS.md
│   └── CURRENT-STATE.md
│
├── AGENTS.md                        # AI agent behavior rules
├── CHANGELOG.md                     # Change tracking
├── DRIFT-LOG.md                     # Documented deviations
├── llms.txt                         # AI-friendly summary
└── .docguard.json                   # DocGuard configuration

---

⚙️ 配置

在项目根目录创建 .docguard.json（由 docguard init 自动生成）：

{
  "projectName": "my-project",
  "version": "0.4",
  "profile": "standard",
  "projectType": "webapp",
  "validators": {
    "structure": true,
    "docsSync": true,
    "drift": true,
    "changelog": true,
    "testSpec": true,
    "security": true,
    "environment": true,
    "docQuality": true,
    "specKit": true
  }
}

所有选项请参阅配置指南。

---

🔬 研究成果致谢

DocGuard 的质量评估和文档生成模式参考了亚利桑那大学和美国国防部联合互操作性测试司令部（JITC）的同行评审研究：

• AITPG — 使用多 Agent 辩论和 RAG 的 AI 驱动测试计划生成器（Lopez 等，IEEE TSE 2026）
• TRACE — 通过校准可解释性进行电信根因分析（Lopez 等，IEEE TMLCN 2026）

首席研究员：Martin Manuel Lopez · ORCID 0009-0002-7652-2385

完整引用请参阅 CONTRIBUTING.md。

这些标签衡量什么。 DocGuard 借用了 TRACE 的 HIGH/MEDIUM/LOW 词汇，作为确定性的分层标准（验证器检查通过率）。DocGuard 实际衡量的是检测器精确率：在一个带标签且刻意保持平衡的基准语料库上，公布样本量及 Wilson 95% 置信区间，见 benchmarks/baseline.json（规范：schemas/docguard-benchmark-baseline.schema.json）。其中每个数值都附有说明，阐明在平衡语料库上测得的基准精确率与仓库中过时声明的基础比率有所不同。请参阅 VALIDATION.md。

---

⭐ 星标历史

---

🔒 隐私与供应链

DocGuard 以本地优先：不收集遥测数据、不做分析、不向外发送数据——完整的（简短）政策见 PRIVACY.md。npm 版本发布时会附带 来源证明， 你可以据此验证每个 tarball 都由 GitHub Actions 从此仓库构建而成。

📄 许可证

MIT — 可免费使用、修改和分发。

---

由 Ricardo Accioly 倾心打造 ❤️