SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场ln-611-docs-structure-auditor

ln-611-docs-structure-auditor

写作与研究

查看项目

更新于 10-15 17:11

技能介绍

用途

ln-611-docs-structure-auditor 是一个文档结构性质量审计工具，类型为 L3 Worker。其目标是对项目文档进行结构质量审计，覆盖 8 个类别，并返回结构化发现给协调者，包含严重级别、位置和建议。它还会为“文档结构”计算合规分数（X/10）。

主要能力与审计类别

该工具按以下 8 个类别进行结构检查：

  1. 层级与链接：当存在 AGENTS.md 时以其为规范根；所有文档应可通过链接到达；无孤立文件；无失效链接。
  2. 单一事实来源（SSOT）：无内容重复；重复内容应替换为指向来源的链接；所有权清晰。
  3. 主动压缩：消除冗长/冗余内容；将散文转为表格；移除无意义信息；即使文件未超限也进行压缩；参考 size_limits.md。
  4. 需求合规：正确的头部标记、正确的顶部章节、在大小限制内、无非法代码块、与技术栈匹配的文档链接。
  5. 时效性信号：检测过期信号，如内容中超过 6 个月的日期、不再受支持的 API/工具引用、TODO/FIXME 标记、遗留的占位文本；深度事实核查由专门 worker 处理。
  6. 遗留内容清理：无历史章节；无“was changed”之类变更说明；无不受支持的信息；仅保留当前状态。
  7. 技术栈适配：链接/引用与项目技术栈匹配；例如不在 .NET 项目中放 Python 示例；使用正确平台的官方文档。
  8. 导入模式合规：当仓库根存在 AGENTS.md 时，CLAUDE.md 必须恰好包含一行 @AGENTS.md，以及一段有界的、与特定 harness 相关的增量内容（总计 ≤50 行）。CLAUDE.md 中任何重复 AGENTS.md 的内容都视为漂移。参见 references/agent_instructions_writing_guide.md 了解理由。

严重级别映射

  • 时效性信号（旧日期、不受支持的引用、TODO 标记）：MEDIUM
  • 失效链接、孤立文档：HIGH
  • 内容重复：MEDIUM
  • 缺失压缩机会：LOW
  • 遗留/历史内容：MEDIUM
  • 错误技术栈引用：HIGH
  • 导入模式漂移（CLAUDE.md 中重复 AGENTS.md 内容、桩文件过大、缺少 @AGENTS.md 行）：HIGH

使用方式

该工具接收包含 tech_stack、project_root、output_dir 的 contextStore。工作流程如下：

  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. 收集发现：记录每条违规的严重级别、位置（file:line）、工作量估算（S/M/L）、建议。
  8. 计算分数：按严重级别统计违规，计算合规分数（X/10）。
  9. 写报告：按 references/templates/audit_worker_report_template.md 构建完整 markdown 报告，通过单次 Write 调用写入 {output_dir}/611-structure.md。
  10. 返回摘要：向协调者返回最小摘要。

强制读取的参考文件

  • references/audit_worker_core_contract.md
  • references/docs_quality_contract.md
  • references/markdown_read_protocol.md
  • references/mcp_tool_preferences.md
  • references/audit_scoring.md（用于评分算法）
  • references/templates/audit_worker_report_template.md（用于输出格式）
  • 可选：references/docs_quality_rules.json（仅在需要精确规则 ID、路径矩阵或白名单占位符例外时加载）
  • 可选：references/mcp_integration_patterns.md（仅在 MCP 行为不明确时加载）

工具策略

该工具可能在隔离的子代理中运行，此时宿主 AGENTS.md 不在作用域内，因此默认优先使用 hex-line MCP 进行文件读取、搜索和编辑。hex-line 对此外仅文档类 worker 是可选的，可用时作为大型 markdown 大纲和定向读取的加速器；否则继续使用内置 Read/Grep/Glob/Bash。

输出格式

按 references/audit_summary_contract.md 写入 JSON 摘要。在托管模式下，调用方会传入 runId 和 summaryArtifactPath；在独立模式下，worker 按共享契约自行生成运行范围内的工件路径。

报告写入 {output_dir}/611-structure.md，包含 category: "Documentation Structure" 以及 checks: hierarchy_links、ssot、compression、requirements_compliance、freshness_indicators、legacy_cleanup、stack_adaptation、import_pattern_compliance。

适用场景

  • 需要审计项目文档结构质量时。
  • 需要检查文档层级、链接完整性、内容重复、压缩机会、需求合规、时效性信号、遗留内容和技术栈适配时。
  • 需要检查 AGENTS.md 与 CLAUDE.md 之间导入模式合规性时。

限制与关键规则

  • 不自动修复：只报告违规；协调者汇总后交由用户处理。
  • 技术栈感知：使用 contextStore 的 tech_stack 应用技术栈特定检查（如 .NET 与 Node.js 文档标准）。
  • 不做深度事实核查：仅检测时效性信号（日期、不受支持的引用、TODO 标记）。
  • 始终压缩：大小限制是上限而非目标；用 100 行文件代替 300 行文件是一种收益。
  • 文档中无代码：文档通过表格或 ASCII 图描述算法；代码属于代码库。
  • 代码即真相：当文档与代码矛盾时，报告文档需要更新（而非代码）。
  • 删除而非归档：遗留内容应被移除，而非移至“archive”。
  • 位置精确：始终包含 file:line 以便程序化导航。
  • 共享契约优先：占位符策略、模板元数据策略和无代码例外来自 docs_quality_contract.md / docs_quality_rules.json。

完成定义

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

参考文件

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

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