feat(repository):代码库探索能力重构 — 从 runtime 自动注入到模型主动工具调用

[phantom5099]

背景问题

当前系统存在以下核心问题：

入口层：Runtime 替模型猜需求
当前 runtime 基于用户最新消息做正则启发式判定（路径锚点、符号锚点、引号文本锚点），猜测用户是否需要代码库信息。这种模糊匹配策略召回率偏弱，且"一轮最多打一类 retrieval"的限制使模型在复杂场景下无法灵活探索。

归属层：代码库能力挂在错误的位置
internal/context/repository 承载了 Git 扫描、文件检索、安全过滤、结果裁剪等完整领域能力，但这些不是 prompt 组装逻辑。context 的职责是消费已经准备好的投影结果并渲染 prompt section，而不是长期承载代码库探索的实现。这种错位还强化了"代码库检索是 prompt 隐式注入附属物"的错误心智。

工具层： codebase_* 完全缺失，filesystem_* 语义不等价
通用 filesystem_* 工具虽然能读文件和搜文本，但不提供 changed-files、结构化 retrieval 和 workspace 级安全裁剪语义。当前 prompt assets 仍在强化 filesystem_* 优先的策略，进一步削弱了代码库探索路径。

符号检索层：只有 Go-first 实现，跨语言盲区
codebase_search_symbol 只有 Go-first 的正则匹配，面对 Python/Java/TypeScript/Rust 等仓库退化为纯文本搜索，精度和结构化程度大幅下降。放弃逐个语言引入外部解析库（Python ast、JavaParser、tsc API）是因为会导致运行时灾难（JVM/Node 依赖）、API 完全不统一、无增量更新。
closes: #535

方案

本 PR 落地以下方案：

1. 领域层迁出
新建 internal/repository 作为中性领域层，将 Git 事实、定向检索、安全过滤、Fingerprint（从 checkpoint 迁入）、FileChangeKind/FileChangeEntry 等能力统一收拢。internal/context/repository 整包删除，所有引用切到新包。checkpoint 的 per-edit snapshot 版本链功能不迁移。

2. 工具入口
新增 3 个专职工具：

• 代码库探索：codebase_read / codebase_search_text / codebase_search_symbol

工具输出采用结构化优先格式（字段名固定），codebase_search_text 不返回代码体，codebase_search_symbol 仅返回 path/line_hint/kind/signature（声明头 ≤ 512 字符），硬约束确保模型必须调用 codebase_read 才能获取实现内容。

3. Runtime 退出自动检索
删除全部正则锚点提取、changed-files 启发式判定、auto retrieval query 构造链路。保留迁移期最小 Git Summary 注入（branch/dirty/ahead/behind），其余仓库信息由模型主动通过工具获取。

4. Tree-sitter 跨语言索引
引入纯 Go 的 github.com/odvcencio/gotreesitter（CGO-free，206 种 grammar），构建 codebase_search_symbol 三层 fallback 架构：

Go AST 快速路径（.go 文件，保留现有正则实现）
    ↓ 非 Go 或未命中
Tree-sitter 内存倒排索引（map[lower(name)] → []SymbolLocation）
    ↓ 无 grammar 或解析失败
Whole-word 文本搜索（最终兜底，所有语言）

索引器设计：惰性初始化（首次搜索时构建，不增加启动时间）、sync.RWMutex 线程安全、文件 mtime+size 增量更新（仅重解析变更文件）。

5. Prompt 策略同步
tool_usage.md 中明确 git_* / codebase_* 优先于 filesystem_* 的代码库探索路径，并写入硬约束规则。

涉及变更

新增模块（internal/repository/）
中性领域层，聚合 Summary、ChangedFiles、Inspect、Retrieve、Fingerprint 及 Tree-sitter 索引能力。不直接暴露给模型，仅作为 tools 的底层依赖。

新增工具（internal/tools/git/、internal/tools/codebase/）
6 个工具各自独立文件，含 schema 定义、参数校验、结构化输出。注册到 tool registry 和 compact 管理链路。每个工具附带单元测试（共 22 用例）。

删除模块（internal/context/repository/）
整包删除 6 文件 ~4000 行。原有能力已完整迁移到 internal/repository。

核心重构（internal/runtime/repository_context.go）
删除约 280 行自动注入逻辑（正则锚点提取、changed-files 启发式、retrieval query 构造），精简为仅返回最小 Git Summary。

Fingerprint 迁移（internal/checkpoint → internal/repository）
ScanWorkdir、DiffFingerprints、FileChangeKind、FileChangeEntry 迁出，checkpoint 的 PerEditSnapshotStore 版本链功能不受影响。

Prompt Assets（tool_usage.md）
新增 repository exploration 指引章节，废弃旧的 bash git 操作优先提示。

设计约束

• 不重写底层检索算法：现有 Git summary、changed files、安全过滤、结果裁剪均沿用已有实现。
• 不引入 LSP / embedding：Tree-sitter 仅做语法级定义提取，不做类型推断或语义级引用追踪。
• verify/git_diff 不变：继续服务 final verify 阶段，不并入推理期工具链。
• 索引驻留内存：进程退出即释放，第一版不持久化到磁盘。

预期收益

1. 消除 runtime 猜需求的脆弱链路 — 代码库检索的触发权完全交给模型，不再有漏注入/误注入。
2. 多语言符号检索 — Python/TypeScript/Java/Rust 等语言通过 Tree-sitter 统一提取结构化符号定义。
3. O(1) 符号查询 — 内存倒排索引 + mtime 增量更新，避免每次调用全量遍历工作区。
4. 明确的工具职责边界 —，codebase_* 处理代码库探索，filesystem_* 处理通用文件操作。

验证

go build ./...                    # 编译通过
go test ./... -count=1            # 68 包全部 OK

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[codecov]

Codecov Report

❌ Patch coverage is 77.88889% with 199 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/repository/retrieve.go	64.78%	42 Missing and 33 partials ⚠️
internal/repository/treesitter_index.go	82.87%	19 Missing and 18 partials ⚠️
internal/repository/treesitter.go	74.56%	15 Missing and 14 partials ⚠️
internal/runtime/run.go	6.25%	14 Missing and 1 partial ⚠️
internal/gateway/validate.go	14.28%	6 Missing ⚠️
internal/tools/codebase/searchsymbol.go	94.93%	2 Missing and 2 partials ⚠️
internal/tools/codebase/searchtext.go	94.80%	2 Missing and 2 partials ⚠️
internal/runtime/toolexec.go	50.00%	3 Missing ⚠️
internal/tools/codebase/read.go	97.10%	1 Missing and 1 partial ⚠️
internal/tools/filesystem/copy_file.go	33.33%	1 Missing and 1 partial ⚠️
... and 12 more

📢 Thoughts on this report? Let us know!