用途
ln-613-code-comments-auditor 是一个内联代码文档审计技能，类型为 L3 Worker。它专门审计内联代码文档的质量与合规性，范围包括注释、docstring 以及语言特定的文档块（如 JSDoc、XML 文档）。
该技能适用于任意技术栈，会自动检测注释语法。它的审计范围严格限定在注释/docstring/JSDoc/XML 文档，不涉及代码设计质量、命名质量、测试质量、架构质量或功能正确性——除非注释与代码相互矛盾。
主要能力
技能围绕六个审计类别展开：
- WHY 而非 WHAT：检查注释是否解释理由，而非复述显而易见的代码行为；不应重复代码本身。
- 密度（15-20%）：检查注释与代码的比例是否处于合理区间，避免注释过多或过少。
- 禁止内容：不得出现日期/作者信息、历史记录说明、注释中的代码示例。
- Docstring 质量：检查是否与函数签名匹配、参数是否被记录、返回类型是否准确。
- 时效性：检查注释是否与代码行为一致、是否存在过时引用、示例是否可运行。
- 遗留清理：检查是否存在无上下文的 TODO、被注释掉的代码块、不受支持的说明。
技能会为每个违规项记录严重级别、位置（file:line）、工作量估算（S/M/L）和建议，并按严重级别统计违规数量，计算合规评分（X/10）。
严重级别映射包括：注释中出现作者姓名或日期为 CRITICAL；被注释掉的代码块、过时/陈旧注释为 HIGH；显而易见的 WHAT 注释、密度偏差超过 5% 为 MEDIUM；轻微密度偏差为 LOW。
使用方式
技能接收 contextStore，其中包含 tech_stack、project_root、output_dir。工作流程为：解析上下文、扫描源文件（依据 tech_stack 检测）、提取内联注释与 docstring/JSDoc、执行六类审计检查、收集发现、计算评分、写入报告。
报告写入 {output_dir}/ln-613--global.md，类别为 "Inline Code Documentation"，检查项包括 why_not_what、density、forbidden_content、docstrings_quality、actuality、legacy_cleanup。摘要按 references/audit_summary_contract.md 输出。在托管模式下，调用方传入 runId 和 summaryArtifactPath；在独立模式下，worker 按共享契约生成自己的运行范围产物路径。当 summaryArtifactPath 缺失时，独立运行时摘要写入 .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json，并可选在结构化输出中回显同一摘要。
技能要求强制读取 references/audit_worker_core_contract.md、references/mcp_tool_preferences.md、references/audit_scoring.md 和 references/templates/audit_worker_report_template.md。在扫描阶段，主路径使用 outline(file_path) 和 discovery-first read_file() 分析代码文件；仅在审计转为后续编辑时才使用 edit_ready=true、verbosity="full"；不使用 hex-graph，因为注释质量是代码阅读问题而非语义图问题。
适用场景
适用于需要对代码库内联文档进行质量审计的场景，例如在代码审查流程中检查注释规范、docstring 完整性、注释时效性，或清理遗留的注释代码与无上下文 TODO。由于通用适配任意语言，可用于多技术栈项目。
限制
技能只报告违规，不自动修复；协调器负责汇总给用户。禁止修改规则文件（_rules.md、_standards.md）以使违规通过。当注释与代码矛盾时，应标记文档需要更新，而不是将其变成通用代码质量审查。注释解释显而易见行为时应被移除。位置精度要求始终包含 file:line 以便程序化导航。
版本为 4.0.0，最后更新于 2026-03-01。