Catenary：为 AI 编码 agent 装上"结构化思维"的项目

一款强制 agent 用 LSP 思考的工具

想象这样一个场景：你给 AI 编程助手下了个任务——"把这个模块里所有调用过 calculate() 函数的地方找出来，并检查它们有没有做空值判断"。一个普通的 agent 会怎么做？它大概率会先 grep -r "calculate" .，然后把扫出来的每一个文件都读一遍，几十 KB 的上下文就这样被吞掉了——而你真正需要的，不过是"哪些地方调用了这个函数、它们的签名是什么"这几十个字符。

Catenary 解决的就是这个问题。它不是一个新的大模型，也不是又一个 agent 框架。它的作用非常明确：强制 AI 编程 agent 用语言服务器的思维读代码，而不是暴力文本搜索。

---

背景：让 agent 读代码的方式"降级"了

在 IDE 里，程序员早已习惯了 LSP（Language Server Protocol）带来的智能跳转、引用查找、代码补全。LSP 的本质是把语言智能抽象成一个标准协议：编辑器不需要内置每种语言的解析器，只需向语言服务器发请求，服务器返回结构化的语义信息。

2024 年底，Anthropic 推出了 MCP（Model Context Protocol），让 AI 工具可以通过标准接口调用外部工具。MCP 很快得到了 OpenAI、Google、Microsoft 的跟进，成为 AI agent 时代的"USB-C 接口"。有了 MCP，agent 理论上可以调用 LSP 工具了。

但问题来了：有了工具，不代表 agent 会用它。 开发者给了 agent grep、find、原生文件读取，再加上 LSP 导航，agent 就会挑最容易的那个——通常是 grep -r "pattern"。这样既浪费上下文 token，又容易遗漏语义结构（比如注释里的文字、重命名后的符号）。

Catenary 的设计哲学就是：把"笨办法"从菜单上删掉。

---

核心机制：PreToolUse Hook 的强制路由

Catenary 的核心是一个运行在 AI 客户端（Claude Code、Gemini CLI 等）上的 PreToolUse Hook。这个钩子会在 agent 每次发起 shell 命令之前拦截审查：

• 如果 agent 试图执行 grep、find、cat 等原始文本命令 → 拒绝执行，并在报错信息中告诉 agent 应该用哪个等效的 Catenary 命令替代
• catenary grep <pattern> 会通过 LSP 查询符号、引用和文本搜索，结果是符号名 + 签名 + 引用位置——可能只有几十字节，而不需要把整个文件拉进来
• catenary glob <path> 通过 LSP 查询文件大纲和目录结构，而不是暴力 ls / find
• 文件编辑通过宿主工具（Edit/Write）完成后，运行 catenary diagnostics 可以即时获取 LSP 诊断结果，无需重新读取文件

整个流程是"构造上保证"的，而不是靠 prompt 引导 agent 自觉——这是 Catenary 与其他"建议用 LSP"的方案最本质的区别。

MCP 协议层面：只做心跳，不过度介入

值得注意的是，Catenary 的 MCP 实现非常克制：它只暴露了心跳通道和工作区根目录同步，不提供任何查询类工具。这是有意为之——让 MCP 专注协调，而不是试图替代 LSP 工具。这种"各司其职"的设计让协议层保持简洁，降低了 agent 的困惑。

---

技术架构：daemon 模式 + 共享语言服务器池

Catenary 由一个常驻 daemon 进程管理，daemon 在后台维护一个共享的语言服务器池：

agents ──▶  Catenary daemon  ──▶  shared LSP server pool
                                  rust-analyzer · pyright · gopls · …

多个 agent 会话可以同时连接到同一个 daemon，共享同一组语言服务器实例。比如同一个项目目录下，rust-analyzer 只需要启动一次，所有会话都能复用它的索引。这对于大型代码库的多 agent 协作场景尤为重要——避免了每个 agent 都冷启动一个 LSP server 的重复开销。

四个接入层面完全解耦：

• CLI：通过宿主 shell 工具调用，调用 catenary grep/glob/diagnostics
• Hooks：PreToolUse allowlist 强制路由
• MCP：心跳 + 工作区根目录同步，无查询工具
• TUI：实时观测 daemon 的 LSP 会话和流量

---

支持的编程语言

Catenary 本身是语言无关的 Router，决定支持哪些语言取决于你配置了哪些语言服务器。官方文档明确支持：

语言	推荐语言服务器	状态
Rust	rust-analyzer	⭐ 主力
Python	pyright-langserver / ruff	⭐ 主力
Go	gopls	常用
JavaScript/TypeScript	typescript-language-server	常用
C/C++	ccls / clangd	可用
Java	eclipse.jdt.ls	可用

配置方式通过 TOML 文件（~/.config/catenary/config.toml）完成，风格简洁。对于主流语言，有 auto_install = true 选项，Catenary 可以在会话启动时自动安装和更新语言服务器的验证版本。

---

上手体验：安装配置与日常使用

安装（Homebrew）

brew install twowells/tap/catenary

其他安装方式包括官方 install.sh 脚本（Linux/macOS）和 cargo install catenary-cli。

配置语言服务器

[lsp.server.rust-analyzer]
[lsp.server.pyright-langserver]
args = ["--stdio"]

[lsp.language.rust]
servers = ["rust-analyzer"]
[lsp.language.python]
servers = ["pyright-langserver"]

[servers]
auto_install = true

验证安装

catenary doctor    # 检查配置是否正确
catenary roots ls  # 查看已索引的工作区

Agent 端配置（以 Claude Code 为例）

需要配置 MCP 服务器声明和 PreToolUse Hook。具体方式在 AGENTS.md 中有详细说明（该文件长达 10KB，内容非常详尽）。

---

局限与争议

Catenary 的定位是"工作流执行器"，而不是"安全沙箱"。它自己在文档里明确写道："这不是安全沙箱——Makefile 仍然可以执行任意命令，Catenary 的职责更窄但更有用：保证 agent 的读操作走结构化搜索，写操作走被追踪的路径。"

这意味着：

• 安全靠宿主环境负责：如果一个恶意的 agent 在你的机器上执行了 rm -rf ~，Catenary 无法阻止
• 依赖宿主插件质量：PreToolUse Hook 的效果取决于 AI 客户端（Claude Code、Gemini CLI）对这些插件的支持程度
• 多语言项目需逐一配置：每种语言都需要手动配置对应的语言服务器，学习成本不为零
• macOS/Linux only：暂无 Windows 原生支持

---

行业意义

MCP 在 2025 年已经获得 OpenAI、Google、Microsoft 的全面支持，成为事实上的 AI Agent 工具调用标准。在这场"MCP 生态"竞争中，Catenary 找到了一个独特的细分定位：不是又一个 MCP 服务器，而是 MCP 与 LSP 之间的高质量桥梁。

它的价值主张在当前 agent 工具生态中有一定代表性：不是做"更多工具"，而是做"更好的路由"。随着 AI 编程工具从"辅助人类"进化到"自主完成任务"，代码导航的质量直接影响 agent 的任务完成率。Catenary 通过架构设计，把"用 LSP 思考"从一种建议变成了一种必然。

---

总结

维度	评分/说明
定位	MCP-LSP 智能路由层，面向 AI 编码 agent
核心价值	强制结构化代码搜索，降低 token 消耗
技术栈	Rust + async-rust + tokio + ratatui(TUI)
License	AGPL-3.0 + 商业许可（双 License）
部署难度	中等（需配置语言服务器）
上手门槛	低（CLI 直观），但需理解 LSP 概念
推荐场景	高频使用 AI 编程工具的团队、追求 agent 执行效率的开发者
不推荐场景	Windows 用户、单语言轻量项目、安全强隔离需求场景

一句话推荐：如果你每天花大量时间在 Cursor、Claude Code 等工具里写代码，Catenary 值得一试——它不改变你的工作流，但它让 agent 用更聪明的方式理解你的代码。