dsh-doc-guard（文档-代码一致性守护） > Document-Code Consistency Guard for DeepSeek Harness. > A read-only DSH plugin that audits your versioned Markdown design docs against the > actual repository: header version numbers, changelog tables, directory-structure trees, > module/test counts, and cross-document references. It detects drift (docs saying one > thing, code being another) and outputs actionable, severity-sorted fix suggestions. > Install with: dsh plugin --profile web add "github:<your-github-user>/dsh-doc-guard#main". 很多仓库用「版本化 Markdown 文档」记录设计：doc/ 下多份文档，头部有 文档版本：vX.Y， 更新记录是 Markdown 表格，正文含目录结构树、模块/系统清单、测试计数、验收数字与文档间互相引用。 代码改完后文档极易漂移：改了代码没加更新记录行、版本号没递增、结构树与真实文件树不符、 测试数与验收记录对不上、文档间引用版本不一致。 dsh-doc-guard 用纯启发式、全程只读地审计这些维度，检测漂移并按严重度输出可直接执行的修复建议。 是 DSH 生态中第一个做「文档漂移审计」的插件（context-doctor 只审上下文注入成本，不审文档漂移）。 ## 特性 | 审计维度 | 说明 | 漂移类型 | 严重度 | | --- | --- | --- | --- | | 版本号一致性 | 头部 **文档版本：vX.Y**（或 > - 文档版本：vX.Y）与更新记录表最新行版本比对；文档间 对应技术设计 vX 引用值与目标文档当前版本比对 | version_mismatch | high | | 更新记录表 | 解析 \| 版本 \| 日期 \| 更新内容 \| 表格：最新版本≠头部版本、更新内容为空（禁止只改版本号不记内容） | version_mismatch / missing_record | high / medium | | 代码变更未记录 | 最近代码文件 mtime 晚于记录表最新日期超过窗口 → 「可能有未记录的代码变更」（mtime 启发式，安全边界内不执行 git） | stale_record | low | | 结构树漂移 | 代码块中 ├──/└── 目录树 vs 真实文件系统（自动排除构建/VCS 目录；目录级摘要树只比目录层级） | tree_missing / tree_extra | medium / low | | 模块/系统清单 | N 个 System / N 份文档 / N 个测试文件 等计数声明 vs 真实计数（目录条目/文档数/测试数） | count_mismatch | low | | 测试计数 | Core 199/199、Net 91 通过/4 跳过 等验收数字 vs 测试源文件静态统计（按扩展名识别 [Fact]/it(/#[test]/def test_/@Test/func Test，不执行测试） | count_mismatch | low | | 文档间交叉引用 | 详见 §X / 见实现文档 §X → 被引文档是否存在；对应技术设计 vX → 版本值是否等于被引文档当前版本 | cross_ref / version_mismatch | high | 全部启发式可配置、可忽略；误报宁可少——无法确定性解析的目标一律跳过，不猜测。 ## 快速安装 bash # GitHub 源（构建产物 lib/ 已入库，无需构建） dsh plugin --profile web add "github:<your-github-user>/dsh-doc-guard#main" 安装后重启 dsh web，doc_guard 工具即出现在模型工具列表；dsh --profile web --dump-config | grep doc-guard 应输出含 id: doc-guard 的挂载记录。 ## 工具用法 doc_guard 参数： cwd?: string 审计起点目录（默认当前会话工作目录） docs?: string[] 要审计的文档路径（默认自动发现 cwd 下 doc*/ 目录 + 根目录含版本头的 *.md） includeCounts?: boolean 是否做测试计数/模块计数启发式（默认 true） detail?: 'summary' | 'developer' 默认 summary；developer 附可定位 receipt（路径+行号） 输出：canonical JSON 报告（见下），渲染为分节文本 ### canonical JSON jsonc { "tool": "doc_guard", "version": 1, "cwd": "/path/to/repo", "docs": [ { "path": "doc/实现文档.md", "headerVersion": "v1.43", "records": [{ "version": "v1.43", "date": "2026-08-15", "hasSummary": true }] } ], "drifts": [ { "severity": "high", "kind": "version_mismatch", "doc": "doc/实现文档.md", "detail": "头部文档版本 v1.43 与更新记录表最新行版本 v1.42（第 8 行）不一致", "evidence": "文档版本：v1.43；更新记录 v1.42 / 2026-08-14", "fix": "在 doc/实现文档.md 更新记录表追加 v1.43 行（含日期与更新内容），或把头部版本改回 v1.42" } ], "stats": { "docsScanned": 3, "driftCount": 1 }, "suggestions": [ { "severity": "high", "text": "…" } ] } detail=developer 时附加 receipt：每份文档的版本头/记录表行号、每条漂移所在行号、 测试文件静态统计明细（路径+标记数）——供 Agent 定点修复。 ## 配置（cordis 配置节） yaml # ~/.dsh/profiles/web/cordis.patch.yml 或 cordis.yml 中 - insert: - id: doc-guard name: 'dsh-doc-guard' config: docsPatterns: ["doc/**/*.md", "*.md"] # 自动发现的文档 glob ignoreTreePaths: [".git", "bin", "obj", "node_modules", "dist", "lib", ".dsh"] # 结构树忽略 countTolerance: 1 # 计数对比容差（±N 内算一致） staleCommitWindow: 5 # "代码改了文档没动"窗口（天，mtime 启发式） maxEvidenceLen: 200 # 报告 evidence 片段最大长度（字符） maxFileBytes: 524288 # 单文件大小硬上限（字节），超限跳过 > staleCommitWindow 语义为「最近 N 天内有代码变更但文档记录未跟进」。 > 因安全边界禁止执行 git（见下），实现为只读 mtime 启发式而非提交数。 ## 安全边界（硬性要求） - 全程只读：只用 ctx.fs 的 resolve/stat/readText/listDir 子集； 唯一的 node:fs 使用是只读 stat 取文件 mtime（陈旧度启发式），不写、不删、不执行； - 单文件 > 512 KB 跳过（maxFileBytes 可配，硬上限）； - 报告不含完整文件内容：只含路径、统计与 ≤200 字符的证据片段； - 不执行测试、不跑构建：测试计数用静态扫描（按扩展名匹配测试标记）； - 不修改任何文件：审计前后仓库内容逐字节不变（有测试断言）。 ## 防误报设计（误报宁可少） - 更新记录表区域（历史快照）不参与当前状态判定：v1.42：对应实现文档 v1.41 是历史事实，不是当前引用； - 里程碑/作用域验收数字（M3 83/83 全绿、Core 153/153 + Net 24/24）不与全局总数对比—— 仅当全文是单一通用标签（tests 290/290 等）且声明数 ≤3 时才与静态统计对比； - 目录级摘要树（无文件名明细）只比对目录层级，不报 tree_extra； - 树中未展开的目录（列出但无子行）不报其内容为 extra；隐藏/临时文件（.env、*.tmpdir）忽略； - 流程图/时序图/ASCII 框图（└──▶ M5 ──▶ M6、───┬───┘）不会被误判为结构树； - 多树块文档只取行数最多的主结构树；game01.slnx 这类文件标签不会当目录根。 ## 工程结构 dsh-doc-guard/ ├── package.json # name=dsh-doc-guard, type=module, main=./lib/index.js, │ # dsh.bundle.patch=./cordis.patch.yml; peerDeps: @deepseek-ai/cordis ├── cordis.patch.yml # - insert: [{ id: doc-guard, name: 'dsh-doc-guard' }] ├── tsconfig.json # 编译到 lib/types/（纯 tsc，无打包器） ├── scripts/ │ ├── setup-dsh-deps.mjs # 定位本机 DSH 安装并链接 @deepseek-ai/* 依赖（junction/symlink） │ ├── build.sh # setup + tsc（POSIX） │ ├── build-win.mjs # 等效 Windows 构建（无 bash 依赖） │ ├── self-test.mjs # 对任意仓库跑审计引擎 │ └── verify-drift.mjs # 注入漂移验证（真实仓库拷贝 + 篡改版本号） ├── src/ │ ├── index.ts # apply(ctx)：注册 doc_guard 工具 + 配置读取 │ ├── audit.ts # 编排：runAudit 全链路 + developer receipt │ ├── scan.ts # 文档发现、版本头/更新记录表/结构树/计数/交叉引用解析、测试静态统计 │ ├── diff.ts # 结构树 vs 磁盘对比（虚拟根/摘要树/穷尽目录处理） │ ├── analyze.ts # 六类漂移判定 + 严重度分级 + 修复建议 + 分节渲染 │ └── types.ts # canonical 类型 + 配置 + fs 服务面子集 └── tests/ # node --test（54 用例，零测试依赖，真实临时目录端到端） ## 开发 / 测试 / 构建 bash npm install # 安装 typescript/@types/node（devDeps） npm run setup # 定位本机 DSH 安装，链接 @deepseek-ai/* 依赖 npm test # node --test 'tests/*.test.ts'（54 用例） npm run build:win # Windows 构建；POSIX 用 npm run build（scripts/build.sh） node scripts/self-test.mjs /path/to/repo # 对真实仓库跑审计引擎 构建产物 lib/（lib/index.js + lib/types/*）入库提交——GitHub 源安装依赖它，用户无需构建即可 dsh plugin add。 ## FAQ Q: 为什么不执行 git log 判断「代码改了文档没动」？ 安全边界禁止执行任何命令（含 git）。实现为只读 mtime 启发式：最近代码文件修改时间 vs 更新记录最新日期。 Q: 测试计数为什么有时不报？ 只有「全文单一通用标签（tests/测试/全部）且声明 ≤3」的验收数字才与全局静态统计对比； Core 199/199、M3 83/83 这类带作用域的里程碑数字无法静态映射，宁可少报。 Q: 报告会泄露文档内容吗？ 不会。报告只含路径、统计与 ≤200 字符证据片段（maxEvidenceLen 可调）。 Q: 支持哪些测试框架标记？ 按扩展名静态匹配：C# [Fact]/[Theory]、JS/TS it(/test(、Rust #[test]、 Python def test_、Java/Kotlin @Test、Go func Test。 ## License BSD-3-Clause。见 LICENSE。