知识索引工具Skill index-knowledge

---

名称: 索引知识 描述: 为代码库生成层次化的AGENTS.md知识库。创建根目录 + 复杂度评分的子目录文档。

索引知识

生成层次化的AGENTS.md文件。根目录 + 复杂度评分的子目录。

用法

--create-new   # 读取现有 → 删除所有 → 从头重新生成
--max-depth=2  # 限制目录深度（默认：5）

默认：更新模式（修改现有 + 在适当处创建新的）

---

工作流程（高层）

1. 发现 + 分析（并发）
   • 启动并行探索智能体（在一条消息中多个Task调用）
   • 主会话：bash结构 + LSP代码映射 + 读取现有AGENTS.md
2. 评分与决策 - 根据合并的发现确定AGENTS.md位置
3. 生成 - 先根目录，然后并行子目录
4. 审查 - 去重、修剪、验证

<critical> TodoWrite所有阶段。实时标记进行中 → 已完成。

TodoWrite([
  { id: "discovery", content: "启动探索智能体 + LSP代码映射 + 读取现有", status: "pending", priority: "high" },
  { id: "scoring", content: "评分目录，确定位置", status: "pending", priority: "high" },
  { id: "generate", content: "生成AGENTS.md文件（根目录 + 子目录）", status: "pending", priority: "high" },
  { id: "review", content: "去重、验证、修剪", status: "pending", priority: "medium" }
])

</critical>

---

阶段1：发现 + 分析（并发）

标记“discovery”为进行中。

启动并行探索智能体

在一条消息中多个Task调用并行执行。结果直接返回。

// 所有Task调用在一条消息中 = 并行执行

Task(
  description="项目结构",
  subagent_type="explore",
  prompt="项目结构：预测检测语言的标准模式 → 仅报告偏差"
)

Task(
  description="入口点",
  subagent_type="explore",
  prompt="入口点：查找主文件 → 报告非标准组织"
)

Task(
  description="约定",
  subagent_type="explore",
  prompt="约定：查找配置文件（.eslintrc, pyproject.toml, .editorconfig） → 报告项目特定规则"
)

Task(
  description="反模式",
  subagent_type="explore",
  prompt="反模式：查找'不要'、'从不'、'总是'、'已弃用'注释 → 列出禁止模式"
)

Task(
  description="构建/CI",
  subagent_type="explore",
  prompt="构建/CI：查找 .github/workflows, Makefile → 报告非标准模式"
)

Task(
  description="测试模式",
  subagent_type="explore",
  prompt="测试模式：查找测试配置、测试结构 → 报告独特约定"
)

<dynamic-agents> 动态智能体生成：在bash分析后，根据项目规模生成额外探索智能体：

因素	阈值	额外智能体
总文件数	>100	每100文件 +1
总行数	>10k	每10k行 +1
目录深度	≥4	深度探索 +2
大文件（>500行）	>10文件	复杂度热点 +1
单体仓库	检测到	每包/工作空间 +1
多语言	>1	每语言 +1

# 首先测量项目规模
total_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
total_lines=$(find . -type f \( -name "*.ts" -o -name "*.py" -o -name "*.go" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')
large_files=$(find . -type f \( -name "*.ts" -o -name "*.py" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')
max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)

示例生成（所有在一条消息中并行执行）：

// 500文件，50k行，深度6，15大文件 → 生成额外智能体
Task(
  description="大文件",
  subagent_type="explore",
  prompt="大文件分析：查找 >500行文件，报告复杂度热点"
)

Task(
  description="深层模块",
  subagent_type="explore",
  prompt="深度4+的深层模块：查找隐藏模式、内部约定"
)

Task(
  description="横切关注点",
  subagent_type="explore",
  prompt="横切关注点：查找跨目录的共享实用程序"
)
// ... 根据计算更多

</dynamic-agents>

主会话：并发分析

当Task智能体执行时，主会话执行：

1. Bash结构分析

# 目录深度 + 文件计数
find . -type d -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c

# 每目录文件数（前30）
find . -type f -not -path '*/\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30

# 按扩展名代码集中度
find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20

# 现有AGENTS.md / CLAUDE.md
find . -type f \( -name "AGENTS.md" -o -name "CLAUDE.md" \) -not -path '*/node_modules/*' 2>/dev/null

2. 读取现有AGENTS.md

对每个找到的现有文件：
  Read(filePath=file)
  提取：关键洞察、约定、反模式
  存储在EXISTING_AGENTS映射中

如果 --create-new：首先读取所有现有（保留上下文） → 然后删除所有 → 重新生成。

3. LSP代码映射（如果可用）

lsp_servers()  # 检查可用性

# 入口点（并行）
lsp_document_symbols(filePath="src/index.ts")
lsp_document_symbols(filePath="main.py")

# 关键符号（并行）
lsp_workspace_symbols(filePath=".", query="class")
lsp_workspace_symbols(filePath=".", query="interface")
lsp_workspace_symbols(filePath=".", query="function")

# 顶部导出的中心性
lsp_find_references(filePath="...", line=X, character=Y)

LSP后备：如果不可用，依赖探索智能体 + AST-grep。

合并：bash + LSP + 现有 + Task智能体结果。标记“discovery”为已完成。

---

阶段2：评分与位置决策

标记“scoring”为进行中。

评分矩阵

因素	权重	高阈值	来源
文件计数	3x	>20	bash
子目录计数	2x	>5	bash
代码比率	2x	>70%	bash
独特模式	1x	有自己的配置	explore
模块边界	2x	有 index.ts/init.py	bash
符号密度	2x	>30符号	LSP
导出计数	2x	>10导出	LSP
引用中心性	3x	>20引用	LSP

决策规则

评分	操作
根目录（.）	总是创建
>15	创建AGENTS.md
8-15	如果独特领域则创建
<8	跳过（父目录覆盖）

输出

AGENTS_LOCATIONS = [
  { path: ".", type: "root" },
  { path: "src/hooks", score: 18, reason: "高复杂度" },
  { path: "src/api", score: 12, reason: "独特领域" }
]

标记“scoring”为已完成。

---

阶段3：生成AGENTS.md

标记“generate”为进行中。

根目录AGENTS.md（完整处理）

# 项目知识库

**生成时间：** {TIMESTAMP}
**提交：** {SHORT_SHA}
**分支：** {BRANCH}

## 概述
{1-2句：什么 + 核心技术栈}

## 结构
\`\`\`
{根目录}/
├── {目录}/    # {仅非明显目的}
└── {入口}
\`\`\`

## 查找位置
| 任务 | 位置 | 备注 |
|------|----------|-------|

## 代码映射
{来自LSP - 如果不可用或项目 <10文件则跳过}

| 符号 | 类型 | 位置 | 引用 | 角色 |

## 约定
{仅偏离标准的部分}

## 反模式（本项目）
{此处明确禁止的内容}

## 独特风格
{项目特定}

## 命令
\`\`\`bash
{开发/测试/构建}
\`\`\`

## 备注
{注意事项}

质量门限：50-150行，无通用建议，无显而易见信息。

子目录AGENTS.md（并行）

为每个位置在一条消息中启动通用智能体（并行执行）：

// 所有在单条消息中 = 并行
Task(
  description="为src/hooks生成AGENTS.md",
  subagent_type="general",
  prompt="生成AGENTS.md用于：src/hooks
    - 原因：高复杂度
    - 最大30-80行
    - 从不重复父目录内容
    - 部分：概述（1行），结构（如果 >5子目录），查找位置，约定（如果不同），反模式
    - 直接写入src/hooks/AGENTS.md"
)

Task(
  description="为src/api生成AGENTS.md",
  subagent_type="general",
  prompt="生成AGENTS.md用于：src/api
    - 原因：独特领域
    - 最大30-80行
    - 从不重复父目录内容
    - 部分：概述（1行），结构（如果 >5子目录），查找位置，约定（如果不同），反模式
    - 直接写入src/api/AGENTS.md"
)
// ... 每个AGENTS_LOCATIONS条目一个Task

结果直接返回。标记“generate”为已完成。

---

阶段4：审查与去重

标记“review”为进行中。

对每个生成的文件：

• 移除通用建议
• 移除父目录重复内容
• 修剪到大小限制
• 验证电报风格

标记“review”为已完成。

---

最终报告

=== 索引知识完成 ===

模式：{更新 | 创建新}

文件：
  ✓ ./AGENTS.md（根目录，{N}行）
  ✓ ./src/hooks/AGENTS.md（{N}行）

分析目录数：{N}
创建AGENTS.md数：{N}
更新AGENTS.md数：{N}

层次结构：
  ./AGENTS.md
  └── src/hooks/AGENTS.md

---

反模式

• 静态智能体数量：必须根据项目大小/深度变化智能体数量
• 顺序执行：必须并行（在一条消息中多个Task调用）
• 忽略现有：总是首先读取现有，即使使用 --create-new
• 过度文档化：并非每个目录都需要AGENTS.md
• 冗余：子目录从不重复父目录内容
• 通用内容：移除适用于所有项目的内容
• 冗长风格：电报风格或丢弃