ln-611-docs-structure-auditor

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

文档结构审计员（L3 Worker）

类型： L3 Worker

专门审计项目文档结构质量的工作器。

目的与范围

• 审计文档在 8 个类别中的结构质量
• 扫描项目中的所有 .md 文件；存在 AGENTS.md 时，根据它构建层级结构
• 向协调器返回结构化发现，包含严重程度、位置和建议
• 计算文档结构合规分数（X/10）

输入

必须读取： 加载 references/audit_worker_core_contract.md、references/docs_quality_contract.md、references/markdown_read_protocol.md 和 references/mcp_tool_preferences.md。 可选规则目录：仅在需要精确规则 ID、路径矩阵或允许的占位符例外时，加载 references/docs_quality_rules.json。 工具策略：你可能作为独立子 Agent 运行，此时宿主的 AGENTS.md 不在适用范围内，因此读取、搜索和编辑文件时默认优先使用 hex-line MCP。仅在 MCP 行为不明确时加载 references/mcp_integration_patterns.md。

接收包含以下内容的 contextStore：tech_stack、project_root、output_dir。

对于此纯文档工作器，hex-line 为可选工具。若可用，可将其用作处理大型 Markdown 大纲和定向读取的加速工具；否则继续使用内置的 Read/Grep/Glob/Bash。

工作流

1. 解析上下文： 从 contextStore 提取技术栈、项目根目录和 output_dir
2. 存在时加载注册表： 有 docs/project/.context/doc_registry.json 时，将其作为首选路由来源
3. 扫描文档： 查找项目中的所有 .md 文件（AGENTS.md、CLAUDE.md、README.md、docs/**）
4. 优先读取章节： 对于较长的文档，先查看大纲，再读取标题标记、Quick Navigation、Agent Entry 和 Maintenance
5. 构建树： 存在 AGENTS.md 时，根据其指向的链接构建层级结构；否则根据 CLAUDE.md 构建
6. 审计类别 1-7： 执行结构检查（见下方“审计类别”）
7. 收集发现： 记录每项违规及其严重程度、位置（文件:行）、工作量估算（S/M/L）和建议
8. 计算分数： 按严重程度统计违规数，并计算合规分数（X/10）
9. 编写报告： 按照 references/templates/audit_worker_report_template.md 编写完整 Markdown 报告，并通过单次 Write 调用写入 {output_dir}/611-structure.md
10. 返回摘要： 向协调器返回最简摘要（见“输出格式”）

审计类别

#	类别	检查内容
1	层级与链接	存在 AGENTS.md 时，以其作为规范根文件；所有文档都可通过链接访问；不存在孤立文件；不存在失效链接
2	单一事实来源	不重复内容；将重复内容替换为指向源内容的链接；所有权明确
3	主动精简	删除冗长或重复的内容；将正文改为表格；删除无意义信息；即使文件未超限，也要进行精简；参见 size_limits.md
4	要求合规性	标题标记正确；顶层章节正确；未超出大小限制；没有违规代码块；文档链接符合技术栈
5	时效性指标	检测过时信号：内容中的日期超过 6 个月；引用不受支持的 API/工具；TODO/FIXME 标记；仍保留占位文本；深入事实核查由专门工作器负责
6	旧内容清理	不包含历史章节；不包含“已更改”说明；不包含不受支持的信息；只保留当前状态
7	技术栈适配	链接/引用与项目技术栈相符；.NET 项目中没有 Python 示例；使用适用于正确平台的官方文档
8	导入模式合规性	仓库根目录存在 AGENTS.md 时，CLAUDE.md 必须恰好包含一行 @AGENTS.md，以及有明确边界的、特定于运行环境的差异内容（总计 ≤50 行）。CLAUDE.md 中任何与 AGENTS.md 重复的内容都属于偏离。原理参见 references/agent_instructions_writing_guide.md

严重性映射

问题类型	严重性
过时指标（旧日期、不受支持的引用、TODO 标记）	中
失效链接、孤立文档	高
内容重复	中
未利用精简机会	低
旧内容/历史内容	中
错误的技术栈引用	高
导入模式偏离（CLAUDE.md 中重复 AGENTS.md 内容、存根文件过长、缺少 @AGENTS.md 行）	高

评分算法

必须阅读： 加载 references/audit_scoring.md。

输出格式

必须阅读： 加载 references/templates/audit_worker_report_template.md。

按照 references/audit_summary_contract.md 编写 JSON 摘要。在托管模式下，调用方会传入 runId 和 summaryArtifactPath；在独立模式下，工作器根据共享契约生成自己的、限定于本次运行的产物路径。

将报告写入 {output_dir}/611-structure.md，其中 category: "Documentation Structure"，检查项为：hierarchy_links、ssot、compression、requirements_compliance、freshness_indicators、legacy_cleanup、stack_adaptation、import_pattern_compliance。

按照 references/audit_summary_contract.md 返回摘要。

独立模式下，仍须将相同的 JSON 摘要写入工作器自行生成的、限定于本次运行的产物路径，并遵循共享契约。

关键规则

遵循已加载的 references/audit_worker_core_contract.md。

• 不要自动修复： 仅报告违规项；协调器会汇总结果并提供给用户
• 考虑技术栈： 使用 contextStore 中的 tech_stack 执行特定于技术栈的检查（例如 .NET 与 Node.js 的文档标准）
• 不进行深入事实核查： 仅检测过时信号（日期、不受支持的引用、TODO 标记）
• 始终精简： 大小限制是上限，不是目标。100 行的文件优于 300 行的文件
• 文档中不写代码： 文档应通过表格或 ASCII 图描述算法。代码应放在代码库中
• 以代码为准： 文档与代码不一致时，应报告文档需要更新，而不是代码
• 删除，不归档： 应删除旧内容，而不是将其移至“存档”
• 精确标注位置： 始终提供 file:line，以便通过程序导航
• 共享契约优先： 占位符策略、模板元数据策略和无代码例外均以 docs_quality_contract.md / docs_quality_rules.json 为准

完成定义

应用已加载的 references/audit_worker_core_contract.md。

• contextStore 解析成功（包括 output_dir）
• 已审计全部 8 个结构类别
• 已收集包含严重程度、位置、工作量和建议的发现
• 已使用扣分算法计算分数
• 已将报告写入 {output_dir}/611-structure.md（使用单次 Write 调用原子写入）
• 已根据契约编写摘要

参考文件

• 大小限制和目标：references/size_limits.md
• 详细检查清单：references/audit_checklist.md

---

版本： 1.0.0 最后更新： 2026-03-01