index-knowledge

index-knowledge

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

用法

--create-new   # Read existing → remove all → regenerate from scratch
--max-depth=2  # Limit directory depth (default: 5)

默认：更新模式（修改现有文件，并在必要时创建新文件）

---

工作流（高层级）

1. 发现 + 分析（并发）
   • 启动并行探索 Agent（在一条消息中发起多个 Task 调用）
   • 主会话：bash 结构分析 + LSP 代码映射 + 阅读现有 AGENTS.md
2. 评分与决策 - 根据汇总结果确定 AGENTS.md 的位置
3. 生成 - 先生成根目录文件，再并行生成子目录文件
4. 审查 - 去重、精简、验证

**所有阶段都要使用 TodoWrite。实时将状态从 in_progress 标记为 completed。**

TodoWrite([
  { id: "discovery", content: "Fire explore agents + LSP codemap + read existing", status: "pending", priority: "high" },
  { id: "scoring", content: "Score directories, determine locations", status: "pending", priority: "high" },
  { id: "generate", content: "Generate AGENTS.md files (root + subdirs)", status: "pending", priority: "high" },
  { id: "review", content: "Deduplicate, validate, trim", status: "pending", priority: "medium" }
])

---

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

将「discovery」标记为 in_progress。

启动并行探索 Agent

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

// All Task calls in ONE message = parallel execution

Task(
  description="project structure",
  subagent_type="explore",
  prompt="Project structure: PREDICT standard patterns for detected language → REPORT deviations only"
)

Task(
  description="entry points",
  subagent_type="explore",
  prompt="Entry points: FIND main files → REPORT non-standard organization"
)

Task(
  description="conventions",
  subagent_type="explore",
  prompt="Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) → REPORT project-specific rules"
)

Task(
  description="anti-patterns",
  subagent_type="explore",
  prompt="Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments → LIST forbidden patterns"
)

Task(
  description="build/ci",
  subagent_type="explore",
  prompt="Build/CI: FIND .github/workflows, Makefile → REPORT non-standard patterns"
)

Task(
  description="test patterns",
  subagent_type="explore",
  prompt="Test patterns: FIND test configs, test structure → REPORT unique conventions"
)

**动态生成 Agent**：完成 bash 分析后，根据项目规模启动额外的探索 Agent：

因素	阈值	额外 Agent
文件总数	>100	每 100 个文件增加 1 个
代码总行数	>10k	每 10k 行增加 1 个
目录深度	≥4	深入探索增加 2 个
大型文件（>500 行）	>10 个	为复杂度热点增加 1 个
单体仓库	检测到	每个包/工作区增加 1 个
多种语言	>1	每种语言增加 1 个

# Measure project scale first
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 files, 50k lines, depth 6, 15 large files → spawn additional agents
Task(
  description="large files",
  subagent_type="explore",
  prompt="Large file analysis: FIND files >500 lines, REPORT complexity hotspots"
)

Task(
  description="deep modules",
  subagent_type="explore",
  prompt="Deep modules at depth 4+: FIND hidden patterns, internal conventions"
)

Task(
  description="cross-cutting",
  subagent_type="explore",
  prompt="Cross-cutting concerns: FIND shared utilities across directories"
)
// ... more based on calculation

主会话：并发分析

Task Agent 执行期间，主会话执行以下工作：

1. Bash 结构分析

# Directory depth + file counts
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

# Files per directory (top 30)
find . -type f -not -path '*/\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30

# Code concentration by extension
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

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

2. 阅读现有 AGENTS.md

For each existing file found:
  Read(filePath=file)
  Extract: key insights, conventions, anti-patterns
  Store in EXISTING_AGENTS map

如果使用 --create-new：先阅读所有现有文件（保留上下文）→ 再删除所有文件 → 重新生成。

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

lsp_servers()  # Check availability

# Entry points (parallel)
lsp_document_symbols(filePath="src/index.ts")
lsp_document_symbols(filePath="main.py")

# Key symbols (parallel)
lsp_workspace_symbols(filePath=".", query="class")
lsp_workspace_symbols(filePath=".", query="interface")
lsp_workspace_symbols(filePath=".", query="function")

# Centrality for top exports
lsp_find_references(filePath="...", line=X, character=Y)

LSP 回退方案：如果不可用，则依靠探索 Agent 和 AST-grep。

合并 bash、LSP、现有文件和 Task Agent 的结果。将「discovery」标记为 completed。

---

阶段 2：评分与位置决策

将「scoring」标记为 in_progress。

评分矩阵

因素	权重	高阈值	来源
文件数	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: "high complexity" },
  { path: "src/api", score: 12, reason: "distinct domain" }
]

将「scoring」标记为 completed。

---

阶段 3：生成 AGENTS.md

将「generate」标记为 in_progress。

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

# PROJECT KNOWLEDGE BASE

**Generated:** {TIMESTAMP}
**Commit:** {SHORT_SHA}
**Branch:** {BRANCH}

## OVERVIEW
{1-2 sentences: what + core stack}

## STRUCTURE
\`\`\`
{root}/
├── {dir}/    # {non-obvious purpose only}
└── {entry}
\`\`\`

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|

## CODE MAP
{From LSP - skip if unavailable or project <10 files}

| Symbol | Type | Location | Refs | Role |

## CONVENTIONS
{ONLY deviations from standard}

## ANTI-PATTERNS (THIS PROJECT)
{Explicitly forbidden here}

## UNIQUE STYLES
{Project-specific}

## COMMANDS
\`\`\`bash
{dev/test/build}
\`\`\`

## NOTES
{Gotchas}

质量门槛：50-150 行，不提供泛泛建议，不包含显而易见的信息。

子目录 AGENTS.md（并行）

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

// All in single message = parallel
Task(
  description="AGENTS.md for src/hooks",
  subagent_type="general",
  prompt="Generate AGENTS.md for: src/hooks
    - Reason: high complexity
    - 30-80 lines max
    - NEVER repeat parent content
    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS
    - Write directly to src/hooks/AGENTS.md"
)

Task(
  description="AGENTS.md for src/api",
  subagent_type="general",
  prompt="Generate AGENTS.md for: src/api
    - Reason: distinct domain
    - 30-80 lines max
    - NEVER repeat parent content
    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS
    - Write directly to src/api/AGENTS.md"
)
// ... one Task per AGENTS_LOCATIONS entry

结果会直接返回。将「generate」标记为 completed。

---

阶段 4：审查与去重

将「review」标记为 in_progress。

针对每个生成的文件：

• 删除泛泛的建议
• 删除与父目录重复的内容
• 精简至规定长度
• 验证是否采用电报式风格

将「review」标记为 completed。

---

最终报告

=== index-knowledge Complete ===

Mode: {update | create-new}

Files:
  ✓ ./AGENTS.md (root, {N} lines)
  ✓ ./src/hooks/AGENTS.md ({N} lines)

Dirs Analyzed: {N}
AGENTS.md Created: {N}
AGENTS.md Updated: {N}

Hierarchy:
  ./AGENTS.md
  └── src/hooks/AGENTS.md

---

反模式

• 固定 Agent 数量：必须根据项目规模/深度调整 Agent 数量
• 顺序执行：必须并行（在一条消息中发起多个 Task 调用）
• 忽略现有文件：即使使用 --create-new，也必须先阅读现有文件
• 过度记录：并非每个目录都需要 AGENTS.md
• 冗余：子级不得重复父级内容
• 泛泛内容：删除适用于所有项目的内容
• 冗长风格：采用电报式风格，否则就不要写