codedb 中文教程：先验证索引，再把上下文交给 Agent
codedb 用 Zig 维护符号、全文、调用方和依赖索引，再通过 MCP、CLI 或本机 HTTP 服务提供查询。它的价值在于缩小 Agent 要读的范围；检索结果仍是静态线索，不等于程序真实运行时的完整路径。
1. 手工核对发布资产
首次试用不要直接把远程脚本交给 shell。打开官方 Releases，下载与你的平台相符的二进制和 checksums.sha256，核对 SHA-256，再执行 codedb --version。这样可以把“下载了什么”和“写了哪些配置”分开检查。
2. 从一个非敏感仓库开始
export CODEDB_NO_TELEMETRY=1
codedb mcp /path/to/test-repo官方把项目标为 Alpha，API 和快照格式仍可能改变。测试仓库应包含几条你已经知道答案的符号、调用关系和依赖，同时避开密钥、客户代码和大型生成目录。遥测默认开启；上面的环境变量关闭官方描述的聚合统计。
3. 第一次只配置一个 MCP 客户端
官方安装器会检测 Claude Code、Codex、Gemini CLI、Cursor、Windsurf 和 Devin，并可能分别写入配置；它还涉及 Claude Code hook 和 DeepWiki 远程 MCP。先按照 MCP 文档手动配置一个测试客户端，记录前后 diff。确认启动命令、根目录和工具列表正确后，再扩展到别的客户端。
4. 明确选择全本地查询
本地符号、BM25、trigram 和图检索不需要上传代码，但 codedb_context 默认使用 hybrid。官方说明 hybrid 可能发送任务，以及最多 24 个受限路径与片段候选；semantic=local 才是不发送查询或源码的模式。敏感仓库第一次抽查应明确指定本地模式。
5. 用已知事实验证索引
选择一个公共函数、一个跨文件调用和一个依赖关系，分别检查 outline、explain 和 callpath。还要修改一个文件，确认 status 与增量结果能跟上。动态导入、反射、依赖注入、生成代码和运行时配置可能漏出静态索引，因此不能只看结果数量。
6. 怎样看官方 benchmark
官方列出了 M4 Pro、固定仓库和固定轮次下的延迟与响应体大小。数据能说明作者测过哪些路径，却不能证明你的语言组合、仓库规模和 Agent 任务会得到同样结果。实际评估应记录答案正确率、首次建索引时间、常驻内存、查询耗时和传给模型的字节数。
7. 同类对比：codedb 与 code-review-graph
相比 code-review-graph，codedb 更偏向常驻低延迟导航、全文搜索和任务上下文组合；前者更强调 SQLite 代码图、影响半径、执行流、测试关系和 CI 风险评论。选型时用同一组真实问题比较覆盖率，不要只比工具数量或项目方速度数字。
8. 验证状态与边界
未验证：发布资产校验、索引速度、语言覆盖、callpath 正确率、文件监视、客户端配置写入、HTTP 安全、遥测关闭、托管 embedding 的服务端声明和 benchmark。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
近期变化与关注原因
编码 Agent 在大型仓库里反复读整文件，会增加延迟和上下文消耗。codedb 把常用结构查询放进常驻索引，并通过 MCP 提供 context、explain、callpath、list_dir 和 status 等入口。
适合谁用
适合中大型代码库里的符号定位、调用方查询、依赖浏览、任务上下文压缩和跨客户端 MCP 复用。动态调用、反射、生成代码、运行时配置和未完整解析的语言会限制结构结果；安全审查、最终修改和测试仍需其他工具完成。
采用建议
codedb 值得用一个非敏感测试仓库评估，但要先固定版本、手工核验资产、关闭不需要的遥测，并从 semantic=local 开始。只有当已知符号、调用方和路径的抽查可靠，且实际上下文确实减少，才适合扩展到主仓库。
原教程未展开的系统信息
核心功能
本地结构与全文索引
扫描仓库后维护 outlines、符号、trigram、word index 和依赖关系；文件变化会触发增量更新。
面向 Agent 的组合查询
codedb_context 按任务组合候选片段，codedb_explain 返回定义与调用方，codedb_callpath 查找两个符号间的已解析路径。默认只向客户端展示五个一站式工具，减少工具列表噪声。
MCP、CLI 与本机 HTTP
同一索引可通过 MCP stdio、codedb CLI 或默认 localhost:7719 的可选 HTTP 服务查询。安装器会向检测到的多个客户端增量写入 MCP 配置。
常见问题
codedb 默认是完全离线的吗？
不是。结构检索在本地，但默认 hybrid 可能把任务以及受限的候选路径和片段发送到托管 embedding 服务。明确使用 semantic=local 才是官方描述的全本地查询路径。
codedb 会收集源码或搜索词吗？
官方称默认遥测只含工具调用次数、延迟和启动统计，不含源码、路径和查询；不过遥测默认开启。需要关闭时设置 CODEDB_NO_TELEMETRY=1 或使用 --no-telemetry，并自行核对网络行为。
为什么不建议直接执行官方 curl 安装命令？
安装器会下载二进制，并可能给多个客户端写 MCP、hook 和远程服务配置。第一次更适合手动下载 release、核对 checksums.sha256，再只配置一个测试客户端。
codedb 的 callpath 能证明真实运行路径吗？
不能。它反映工具成功解析的静态关系；反射、动态导入、依赖注入、配置和外部服务可能不在图里，仍需测试、日志或 tracing 复核。
codedb 和 code-review-graph 怎么选？
主要需求是快速符号、全文和任务上下文检索时先试 codedb；主要需求是影响范围、执行流、测试关系和 CI 评论时先试 code-review-graph。应在同一组真实任务上比较正确率、耗时和数据边界。