enhance-docs

enhance-docs

分析文档的可读性、结构和 RAG 优化情况。

解析参数

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');
const aiMode = args.includes('--ai');

文档位置

类型	位置	用途
用户文档	docs/*.md、README.md	面向人类的指南
Agent 文档	agent-docs/*.md	AI 参考资料
项目记忆	CLAUDE.md、AGENTS.md	AI 上下文/指令

优化模式

仅 AI 模式（--ai）

适用于 agent-docs 和经过 RAG 优化的文档：

• 大幅减少 token 数量
• 高密度信息组织
• 便于检索的自包含章节
• 最佳分块边界

两者兼顾模式（--both，默认）

适用于面向用户的文档：

• 兼顾可读性与 AI 友好性
• 为人类读者和检索器提供清晰的结构

工作流

1. 发现 - 查找所有 .md 文件
2. 解析 - 提取结构和内容
3. 检查 - 根据模式运行模式检查
4. 报告 - 生成 Markdown 输出
5. 修复 - 如果使用 --fix，则应用自动修复

检测模式

1. 链接验证（高）

• 失效的锚点链接（[text](#missing-anchor)）
• 指向不存在文件的链接
• 格式错误的链接语法

2. 结构验证（高）

标题层级：

• 不得跳级（H1 → H3，中间没有 H2）
• 每份文档只能有一个 H1
• 代码块需标注语言

根据位置判断内容（基于“迷失在中间”研究）：

• 关键内容放在文档开头或结尾
• 补充细节放在中间
• 标记埋在中间章节的重要内容

推荐结构：

1. Overview/Purpose (START - high attention)
2. Quick Start / TL;DR
3. Detailed Content
4. Reference / API
5. Summary / Key Points (END - high attention)

3. Token 效率（高 - AI 模式）

Token 估算： characters / 4 或 words * 1.3

不必要的赘述：

• “在本文档中……”
• “如您所见……”
• “让我们来探讨……”
• “需要注意的是……”

冗长表达：

冗长表达	简洁表达
“为了”	“为”
“由于……这一事实”	“因为”
“具有……的能力”	“可以”
“在当前这个时间点”	“现在”
“出于……的目的”	“为”
“如果发生……的情况”	“如果”

**目标：**项目记忆文件约 1500 个 token；参考文档可灵活调整。

4. RAG 优化（中 - AI 模式）

分块大小指南：

大小	问题
>1000 个 token	太长，应拆分为子主题
<50 个 token	太短，应与相关内容合并
200-500 个 token	最适合检索

语义边界：

• 每个章节只讨论一个主题
• 章节应自成一体（避免以“It”“This”开头）
• 章节标题应清晰描述内容

上下文锚点：

# Bad - ambiguous start
## Configuration
It requires several settings...

# Good - self-contained
## Configuration
The plugin configuration requires several settings...

5. 信息密度（中 - AI 模式）

优先使用表格而非散文：

# Bad - verbose
The function accepts a path parameter which is required,
a limit parameter which defaults to 10, and an optional
format parameter.

# Good - dense
| Param | Required | Default | Description |
|-------|----------|---------|-------------|
| path | Yes | - | File path |
| limit | No | 10 | Max results |
| format | No | json | Output format |

有序事项优先使用列表而非段落。

示例、命令和配置使用代码块。

6. 交叉引用质量（中）

• 内部链接应使用相对路径
• 外部链接应保持稳定（避免使用提交哈希）
• 参考章节应指向权威来源

7. 平衡性建议（中 - 两者兼顾模式）

• 长篇内容（超过 500 个词且没有标题）缺少章节标题
• 重要信息埋在文档后部
• 长文档缺少 TL;DR 或摘要

自动修复

问题	修复
标题不一致	将 H1 → H3 调整为 H1 → H2
冗长表达	替换为简洁表达
缺少代码语言标注	根据内容检测结果添加

输出格式

## Documentation Analysis: {name}

**File**: {path}
**Mode**: {AI-only | Both}
**Tokens**: ~{count}

| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |

### Link Issues
| Line | Issue | Fix | Certainty |

### Structure Issues
| Line | Issue | Fix | Certainty |

### Efficiency Issues [AI mode]
| Line | Issue | Fix | Certainty |

### RAG Issues [AI mode]
| Line | Issue | Fix | Certainty |

模式统计

类别	模式数	模式	确定性
链接	3	共享	高
结构	4	共享	高
Token 效率	3	AI	高
RAG 优化	3	AI	中
信息密度	2	AI	中
交叉引用	2	共享	中
平衡性	3	两者兼顾	中
总计	20	-	-

### 冗长表达 ```markdown In order to configure the plugin, you need to... ``` ```markdown To configure the plugin... ``` ### RAG 分块 ```markdown ## Installation [2000+ tokens of mixed content covering install, config, and usage] ``` ```markdown ## Installation [400 tokens - installation only]

Configuration

[300 tokens - config only]

Usage

[400 tokens - usage only]

</good_example>

### 位置感知内容
<bad_example>
```markdown
## Introduction
[Long background...]

## History
[More context...]

## Critical Setup Steps
[Important info buried in middle]

</bad_example> <good_example>

## Quick Start (Critical)
[Important setup steps at START]

## Background
[Supporting context in middle]

## Reference
[Details...]

## Key Reminders
[Critical points repeated at END]

</good_example>

表格与散文

<bad_example>

The API accepts three parameters. The first is `query` which is required.
The second is `limit` which defaults to 10. The third is `format`.

</bad_example> <good_example>

| Param | Required | Default |
|-------|----------|---------|
| query | Yes | - |
| limit | No | 10 |
| format | No | json |

</good_example>

参考资料

• agent-docs/CONTEXT-OPTIMIZATION-REFERENCE.md - 令牌预算、位置感知、分块
• agent-docs/PROMPT-ENGINEERING-REFERENCE.md - 结构、信息密度

约束

• 仅自动修复确定性高的问题
• 保留原有语气和风格
• 平衡 AI 优化与可读性（默认模式）
• 不要删除内容，只重新组织或精简