CocoSearch：把本地代码搜索做成 agent 可用的混合检索层
让 agent 在陌生代码库里找东西，最烦人的部分通常不是“搜索”本身，而是搜索结果太碎。
你问“认证流程在哪里”，它可能先 grep auth，再 grep login，然后读几个文件，发现名字其实叫 session_renewal。你问“改这个配置解析会影响哪里”，它可能能找到当前文件，却不知道反向依赖和调用边界。结果就是很多 token 花在试探式文件读取上，真正用于判断和修改的上下文反而不够。
今天想记下的 VioletCranberry/coco-search，就是一个偏本地、偏实用的代码检索层。它不是新的聊天应用，而是把代码库索引成一套 CLI、Web dashboard、交互式 REPL 和 MCP 工具：agent 可以用自然语言搜代码，也可以带上语言、符号类型、依赖影响这类约束。
按 GitHub repository API、README、release page、license 文件、tag 列表和默认分支浅克隆在 2026-07-06 能看到的公开信息，CocoSearch 当前有 36 stars、6 forks。仓库主语言是 Python，许可证是 MIT，创建于 2026-02-16，最近 push 时间是 2026-07-05 09:52 UTC。最新 release 是 v0.1.48，GitHub release 页面显示发布时间为 2026-06-04 16:51 UTC。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | VioletCranberry/coco-search |
| 定位 | 本地优先的混合代码搜索 CLI / Dashboard / MCP server |
| Stars | 36 |
| Forks | 6 |
| 主语言 | Python |
| 许可证 | MIT |
| 仓库创建时间 | 2026-02-16 |
| 最近 push | 2026-07-05 09:52 UTC |
| 最新版本 | v0.1.48 |
| 版本发布时间 | 2026-06-04 16:51 UTC |
| 核心思路 | 用向量检索、全文检索、符号过滤和依赖图给 agent 提供更少但更准的代码上下文 |
不是只做 semantic search，而是混合检索
CocoSearch 的 README 里最值得注意的一点，是它没有把“语义搜索”当成唯一答案。
它的检索管线把 pgvector 的向量相似度和 PostgreSQL tsvector 全文检索合在一起，再用 Reciprocal Rank Fusion 做排序融合。代码搜索里这很现实：自然语言问题需要语义匹配，但函数名、类名、配置键和错误码又经常需要关键字精确命中。
比如你搜“authentication middleware”，向量检索可能找到处理登录状态的函数；但如果仓库里有 AuthMiddleware、auth_middleware 或 validateAuthHeader，关键字和标识符分析也不应该被丢掉。CocoSearch 会识别 camelCase、snake_case、PascalCase 这类代码标识符，并支持按 symbol type、symbol name、language 做过滤。
这比单纯把代码 chunk 丢进向量库更像工程工具。它承认代码不是普通文档：名字、边界、定义位置、依赖关系都很重要。
Tree-sitter 让结果不像随机行号
很多代码搜索工具的问题是返回“命中的几行”，但这几行不一定是完整语义单元。Agent 看到一个片段，还要继续读上文、下文、相关定义，才能判断它是否真有用。
CocoSearch 用 Tree-sitter 做上下文扩展。README 中列出的行为是：结果可以扩展到包围它的函数或类边界，避免只返回任意行号附近的片段。它还维护 parse health，告诉你索引里哪些文件解析正常、哪些只是部分解析、哪些没有 grammar。
这对 agent 尤其有用。Agent 不只是要知道“这里出现了 auth”，还要知道这个命中在什么函数里、函数大概做什么、是否是定义而不是调用、是不是当前语言的可解析结构。越接近真实代码结构，agent 后续少读错文件的概率就越低。
依赖图是它比普通搜索更进一步的地方
另一个有意思的点是 dependency graph。
CocoSearch 不是只返回搜索结果，还提供 file-level dependency extraction。README 里列出的 extractor 覆盖 Python、JavaScript/TypeScript、Go、Terraform、Helm、GitHub Actions、GitLab CI、Docker Compose、ArgoCD、Markdown 等场景，并提供 forward dependency tree 和 reverse impact analysis。
这让它不只是“帮我找到代码”，而是开始回答“改这里会碰到谁”。比如：
- 改一个 GitHub Actions workflow 前，先看它依赖哪些脚本和配置；
- 改一个 TypeScript module 前，查有哪些文件反向依赖它；
- 让 agent 做 PR review 时，不只看 diff，还让它看可能的影响半径；
- 在多仓库场景里，把相关 index 连接起来做 cross-index search。
这些能力很适合 MCP。Agent 可以先用 search_code 找到候选位置，再用 dependency/impact 工具判断修改范围，而不是在 shell 里连续跑一串不稳定的 grep。
接入方式偏开发者友好
CocoSearch 的入口比较清楚。README 给了两条服务路径：本地 Ollama embedding，或 OpenAI/OpenRouter 这类远程 embedding provider。底层存储需要 PostgreSQL + pgvector，默认可以用 Docker Compose 起服务。
常用界面也有几种：
- CLI：
uvx cocosearch index /path/to/project和uvx cocosearch search "authentication flow" --pretty； - Web dashboard：管理多个项目、触发索引、查看高亮结果、图表和日志；
- 交互式 REPL：适合连续试搜索条件；
- MCP server：给 Claude Code、Claude Desktop、OpenCode 等 MCP client 调用。
这几个入口覆盖的是不同工作方式。单次查询用 CLI；想观察索引状态用 dashboard；调试检索质量用 analyze；接到 agent 工作流里则用 MCP。对一个小项目来说，接口面已经挺完整。
适合什么场景
我觉得 CocoSearch 适合三类人。
第一类是已经在用 coding agent 的开发者。你发现 agent 经常花很多轮在“找位置”，尤其是在大型 Python、TypeScript、Go、Rust 或 IaC 仓库里来回 grep。CocoSearch 可以作为一个更结构化的本地搜索工具接进去。
第二类是维护多项目代码的人。它支持 cross-index search，也有 dashboard 的多项目管理，这对同时处理几个服务、库、配置仓库的人有意义。
第三类是想自己观察检索质量的人。analyze、parse health、pipeline diagnostics、cache、symbol filter 这些功能，说明作者在乎“为什么这个结果排在前面”。这比黑盒 RAG 更适合工程调试。
需要注意的地方
第一，它不是零依赖小脚本。要发挥主要能力，需要 PostgreSQL + pgvector，默认本地 embedding 还要 Ollama。虽然 Docker Compose 降低了启动成本，但这仍然比一个纯 CLI grep wrapper 重。
第二，项目很新。仓库创建于 2026-02-16，目前只有 36 stars。最新 release 是 v0.1.48，版本号也说明它还在快速迭代。适合试用和小范围接入，不适合不经评估就放到强依赖生产流程里。
第三，README 的能力面很宽：混合检索、依赖图、dashboard、MCP、Claude skills、PR review。范围宽是优点，也意味着要实际跑一遍自己的仓库，确认哪些语言和工作流真的被支持得够好。
第四，语义检索仍然需要判断。CocoSearch 能减少盲搜，但不能替代代码阅读、测试和 review。尤其是 agent 拿到搜索结果以后，仍然应该读关键文件、验证依赖关系，并运行项目自己的检查。
小结
CocoSearch 吸引我的地方，是它把 agent 代码搜索里的几个真实痛点放在了一起：自然语言找不到精确命名、关键字搜索缺少意图、向量搜索不懂符号边界、grep 不会告诉你反向影响。
把这些能力做成本地索引，再通过 CLI、dashboard 和 MCP 暴露出来，是一个很实用的方向。它不会让 agent 突然懂完整系统，但可以让 agent 少一点试探式翻文件，多一点带结构的上下文。
如果你已经在实际仓库里用 coding agent，尤其是经常让它做探索、修 bug、review diff 或分析依赖影响，CocoSearch 值得拿一个复杂但不关键的项目试一下。它的价值不在于替代工程判断，而在于把“找代码”这一步变得更像工具调用，而不是猜谜。