用途
enhance-docs 用于在改进文档结构、准确性与 RAG 就绪度时使用。它分析文档的可读性、结构与 RAG 优化情况，帮助用户发现并修复文档中的问题。
主要能力
该技能会执行以下工作流：发现（查找所有 .md 文件）、解析（提取结构与内容）、检查（根据模式运行模式检查）、报告（生成 markdown 输出）、修复（若使用 --fix 则应用自动修复）。
它检查的文档位置包括：用户文档（docs/.md、README.md，面向人类阅读的指南）、智能体文档（agent-docs/.md，AI 参考材料）、项目记忆（CLAUDE.md、AGENTS.md，AI 上下文/指令）。
检测模式涵盖以下类别：
- 链接验证（HIGH）：损坏的锚点链接、指向不存在文件的链接、格式错误的链接语法。
- 结构验证（HIGH）：标题层级（无跳级、每文档单个 H1）、带语言标签的代码块、基于“迷失在中间”研究的位置感知内容（关键信息位于文档开头或结尾，支撑细节位于中间），并标记埋没在中间部分的重要内容。推荐结构为：概述/目的（开头）、快速开始/TL;DR、详细内容、参考/API、总结/要点（结尾）。
- Token 效率（HIGH，AI 模式）：Token 估算（字符数 / 4 或词数 * 1.3）；识别不必要的赘述（如“In this document...”“As you can see...”等）与冗长短语（如“in order to”改为“to”、“due to the fact that”改为“because”等）。目标：项目记忆文件约 1500 tokens，参考文档可灵活。
- RAG 优化（MEDIUM，AI 模式）：分块大小指南（>1000 tokens 过长需拆分，<50 tokens 过短需合并，200-500 tokens 为检索最优）；语义边界（每节单一主题、自包含章节、清晰章节标题）；上下文锚点（避免章节开头使用“It”“This”等歧义指代）。
- 信息密度（MEDIUM，AI 模式）：优先使用表格而非散文，顺序项优先使用列表而非段落，示例、命令、配置使用代码块。
- 交叉引用质量（MEDIUM）：内部链接使用相对路径，外部链接保持稳定（避免提交哈希），参考部分指向规范来源。
- 平衡建议（MEDIUM，Both 模式）：长内容（超过 500 词无标题）缺少章节标题、重要信息埋没在文档后部、长文档缺少 TL;DR 或摘要。
使用方式
解析参数：从 $ARGUMENTS 中拆分参数，targetPath 为第一个不以 -- 开头的参数（默认为 .），fix 为是否包含 --fix，aiMode 为是否包含 --ai。
优化模式：
- AI-Only 模式（--ai）：适用于 agent-docs 与 RAG 优化文档，进行激进 Token 削减、密集信息打包、自包含章节以便检索、最优分块边界。
- Both 模式（--both，默认）：适用于面向用户的文档，在可读性与 AI 友好性之间取得平衡，为人类与检索器提供清晰结构。
自动修复：仅自动修复 HIGH 确定性问题。修复内容包括：不一致标题（H1 → H3 变为 H1 → H2）、冗长短语（替换为简洁替代）、缺失代码语言（根据内容检测添加）。
输出格式为 markdown，包含文档分析标题、文件路径、模式、Token 数、按确定性统计的问题数量，以及链接问题、结构问题、效率问题（AI 模式）、RAG 问题（AI 模式）等表格。
适用场景
适用于需要改进文档结构、准确性与 RAG 就绪度的场景，包括用户文档、智能体文档与项目记忆文件的优化。
限制
自动修复仅限 HIGH 确定性问题；需保留原始语气与风格；默认模式下需平衡 AI 优化与人类可读性；不删除内容，仅重构或精简。