code-intelligence

Files (3)

• SKILL.md
• tools.test.ts
• tools.ts

SKILL.md (first lines)

# code-intelligence — `repo_symbol_answer` v1

把"对某个代码仓库的自然语言问题"映射到"带引用的回答 + 结构化 source"，跟 kb_answer 是同一抽象的代码仓库版本。

## 接口

```ts
repo_symbol_answer({
  question: string,             // 自然语言
  repo_path: string,            // 当前 turn 所在机器上的仓库绝对路径
  options?: {
    paths?: string[],           // 限定 glob (默认 全 repo)
    languages?: ('ts'|'js'|'py'|'go')[],  // 限定语言（默认全部）
    max_sources?: number,       // 默认 6, max 12
    answer_style?: 'concise'|'default'|'detailed',
  }
})
→ {
  success: true,
  repo_path, question,
  answer, confidence: 'high'|'medium'|'low',
  sources: [{
    file_path,                  // 仓库根目录相对路径
    line_range: [start, end],
    excerpt,
    evidence_type: 'definition'|'reference'|'call'|'grep',  // AST symbol kind 或 lexical
    symbol?: string,            // 涉及的符号名
    score,
  }],
  diagnostics: { retrieval_counts, used_llm, used_reranker, low_score, latency_ms, ast_parsed_files }
}
| { success: false, error, code: 'REPO_NOT_FOUND'|'REPO_EMPTY'|'INVALID_REPO'|'INTERNAL_ERROR' }
```

## v1 scope

支持：
- 语言：TypeScript / JavaScript / Python / Go（复用 `src/ast/` 已有 grammar wasm）
- AST kind：function / method / class / interface / variable 定义；call expression（reference 弱版本）；import
- Lexical fallback：ripgrep on `*.{ts,tsx,js,jsx,py,go}`，覆盖 prose / comment / config / string literals
- 文件枚举：gitignore-aware（`.git`, `node_modules`, `dist`, `build`, `__pycache__` 等 default skip）
- LLM synthesis：palette:mid，evidence type hierarchy（AST definition > AST call > grep）
- Reranker + sigmoid 归一化 + no-hit cutoff
- pickDiverse: score-first when reranker used

不支持（v2+）：
- Cross-file 真 reference search（需要 type inference，LSP 才能精确）
- 概念级 embedding 搜索（"实现 feature Y 在哪"）
- 多语言比 v1 多
- Watcher / 预建 index（v1 on-demand 解析 + 进程内 cache）

## Worker 执行位置

`repo_symbol_answer` 是 `runtime: 'local'` 工具：主体 turn 在主体本机检索，worker turn
在对应 worker 本机检索。`repo_path` 必须是当前 turn 所在机器可见的绝对路径，不能拿
主体路径去查 worker，也不能拿 worker 路径转回主体。

工具里的 palette:mid 综合仍复用当前进程的 `LLMRouter`。worker 的 provider 是
`RemoteLLMProvider`，因此只有 LLM call 会透明转回主体；`stat`、`rg`、tree-sitter 和
源码读取都留在 worker 本机。worker 没有真实 `MemoryManager` 时，可选 reranker 跳过，
不影响 AST + grep 检索和 LLM 综合。

## 名字为什么是 "symbol_answer" 而不是 "answer"

v1 初版实测后明确：retrieval 强烈依赖 query 里**显式出现 ASCII symbol identifier**（function/class/variable/type 名）。三类 query 实测对照：

| query 类型 | 例 | v1 表现 |
|---|---|---|
| **Symbol lookup** | "buildToolContext 在哪定义" / "X 接受什么参数" / "Y 类有哪些方法" | ✅ excellent，AST 直击定义 + 全部引用 |
| **Concept / "怎么决定"** | "sub-agent 怎么决定 backend" | ❌ AST 0 hit（symbol 不在 query 里），LLM 只能从 grep noise 综合，confidence medium 且不完整 |
| **Pattern 广覆盖** | "哪些 skill 是 centralized" | ❌ LLM 只看 top 6 chunk，错过全部 matched files |

所以工具名带 "symbol" 反映真实 capability：**这是 symbol-level 快速通道，不是通用 code QA**。

非 symbol 类查询（concept、pattern、跨文件 trace）应该派 `spawn_subagent` 做 multi-step navigation。

## 跟 sub-agent 边界

- **repo_symbol_answer**：1 个 tool call，5-15s，几千 token。Symbol 必须在 query 里。
- **spawn_subagent**：multi-step navigation + 推理。30s-5min，几万 token。Concept / pattern / 跨文件 trace / 没有显式 symbol 的 query 都走这条。

不确定哪条：先 repo_symbol_answer 试，低 confidence + diagnostics.retrieval_counts.ast_def=0 时升级到 sub-agent。

From maxesisn/maxclaw-oss, MIT.

More from maxesisn/maxclaw-oss