Plumb

为 Agent 提供 IDE 智能能力——为无人值守工作设置护栏，为 Agent 集群提供协作支持。

Plumb 是一个 MCP 服务，为编码 Agent 提供 IDE 的智能层——由 LSP 支持的语义分析、tree-sitter 代码索引和项目记忆——并通过护栏保障安全：采用原子化、锁串行化写入并支持事务回滚，限制文件系统和 git 的访问范围，同时通过守护进程在自身崩溃后恢复运行。而且，你运行的所有 Agent 都共享同一个守护进程，因此 plumb 也能充当它们之间的协作层：各个 Agent 可以看到其他 Agent 的写入、互相发送消息，并移交工作而不是重复劳动。一个二进制文件，无需安装其他内容。

---

为什么选择 Plumb

大模型 Agent 通常通过将整个文件读入上下文窗口来工作——消耗大量 token、规模扩大时信息丢失、无法理解符号语义，而且不适合不加限制地操作真实代码仓库。Plumb 基于四大支柱构建，按优先级排列如下。

1. 可靠性与写入安全

让 Agent 连续一小时修改代码库，前提是写入不会损坏文件，崩溃也不会卡死会话。

• 原子 I/O — 每次写入都会先暂存到临时文件，再重命名到目标位置。绝不会发生部分写入。支持符号链接，兼容 CRLF。
• 按路径加锁 — 守护进程会对所有会话和聊天窗口中写入同一文件的并发操作进行串行化。不会发生竞态。
• 多文件事务 — 可跨数十个文件应用编辑；如果任何步骤失败，保证原子回滚。
• 抗崩溃守护进程 — plumb serve 是一个可重连的代理。如果守护进程崩溃或挂起，它会重新启动守护进程并重放握手；Agent 不会察觉。在途写入绝不会被静默重试。
• 乐观并发控制 — mtime/sha 校验可在过期编辑覆盖较新的更改之前将其拦截。

观看运行效果：docs/demos/ — two-agents-one-file.sh（拒绝过期写入，不会丢失任何内容）和 daemon-respawn.sh（如下所示——守护进程在会话中途被终止；Agent 的下一次编辑仍会成功）：

2. 多 Agent 协作

一个守护进程为你运行的每个 Agent 提供服务，因此它自然适合让 Agent 彼此看见并交流，而不只是避免互相覆盖写入。锁可以阻止两个 Agent 破坏同一个文件；协作则可以避免它们重复执行任务、基于同伴正在改写的函数签名进行变基，或发布即将被同伴进行中的工作作废的更改。

• 同伴感知（默认启用）——workspace_sessions 会列出每个活动会话及其写入内容，这些信息由守护进程记录。记录的是实际活动，而非其他 Agent 的说法：即将开始任务的 Agent 可以看到同伴已经在处理这些文件。（只读操作不会显示；失败或被拒绝的写入会保留记录，但标记为 [失败 — 未应用更改]——因此一眼就能分辨“同伴正在处理这里”和“更改已落地”。）
• Agent 间邮箱（默认启用，仅限同一工作区）——leave_note / check_messages 为会话提供带线程的交流渠道：将更改交给正在改写这些文件的同伴，或请同伴测量某种行为，而不是凭空假设。消息通过常规工具结果传递，因此 Agent 在工作时无需轮询也能收到。
• 建议性意图（可选启用：[collab] intents）——share_intent 用于声明 Agent 正在处理的内容；当同伴的写入涉及已声明的路径时，会在可能发生冲突的时刻收到提示。意图会明确标记为未经验证的声明，与守护进程记录的活动动态分开保存，并且绝不会阻止任何操作。
• 持久化发现（可选启用：[collab] knowledge_handoff）——share_findings 会立即将 Agent 刚刚学到的内容转化为可搜索、已清除秘密信息的项目记忆，让知识在产生它的会话结束后仍然留存。

协作在设计上仅提供建议——上述写入安全性绝不依赖 Agent 之间的配合。参考工具文档中的跨 Agent 共享以及[collab] 配置部分。

3. 语义智能

将编辑器具备的相同基础功能作为结构化工具提供：

• 由 LSP 支持的重构——rename_symbol、replace_symbol_body、safe_delete_symbol 能理解作用域、类型和引用。
• 内联真实诊断信息——每次写入都会附加实际的 gopls/pyright 输出，让 Agent 立即知道自己破坏了构建。
• 符号搜索——仅限你的代码，不会混入标准库或依赖项中的无关结果。

4. 上下文效率与安全控制

• 只读取所需内容——读取符号或行范围，而不是 2,000 行的文件。
• 由你控制的访问范围——每个连接都可设置路径允许列表（只读与可读写根目录），并采用分级 Git 门控（破坏性操作和网络操作默认关闭，需要明确确认）。参见 SECURITY.md。
• 一次往返即可完成初始化——session_start 会返回工作区、分支、近期提交、诊断信息和项目记忆。

如需查看经过测量且可复现的数据，请参见 docs/use-cases.md——读取一个函数所需的上下文比读取整个文件少 2.9×–33.4×（该比例表示文件中有多少内容是你不需要的）；而 find_references 会返回真实调用位置，文本搜索结果中则有 60% 是噪声。页面也公布了不理想的数据：read_multiple_files 的有效负载比原生读取文件多 1.31×（低于 1.32×，但仍然不划算——原因见 Scenario 10）。每个数据都由 scripts/measure-use-cases.py 重新生成。

---

快速开始

Plumb 是一个单二进制文件——从零开始，直到获得第一个答案：

1. 安装

# Homebrew (macOS + Linux) — recommended
brew install plumbkit/plumb/plumb

# or with Go
go install github.com/plumbkit/plumb/cmd/plumb@latest

# or grab a prebuilt binary: https://github.com/plumbkit/plumb/releases

**macOS 说明：**预构建的二进制文件尚未经过公证——首次运行时，你可能需要执行 xattr -d com.apple.quarantine ./plumb，或右键点击 →「打开」。使用 Homebrew 安装则不会遇到这个问题。

2. 连接你的 Agent

plumb setup claude-code      # also: claude-desktop, codex, gemini, cursor, …

plumb setup 会为你写入 MCP 配置——无需手动编辑 JSON。

3. 打开项目并试用

确保所需的语言服务器位于 $PATH 中（Go 对应 gopls， Python 对应 pyright，……），然后让你的 Agent 回答一个实际问题。在 Claude Code 中：

cd your/project
claude "Use plumb to orient in this repo (session_start), then show me
everywhere <Handler> is called and what would break if I changed its signature."

Plumb 会解析工作区并运行 session_start 以了解项目概况，然后基于真实的 LSP 和拓扑数据作答——包括实际调用点和影响范围——而不是根据文件转储猜测。它是只读的；不会修改任何内容。（任何已连接的 Agent 都可使用——只需粘贴提示词。）

没有 go.mod/pyproject.toml，也不是 git 仓库？运行一次 plumb init，固定 工作区根目录（它还会创建 .plumb/context.md 和项目配置）。

完整操作指南 → docs/getting-started.md。

---

语言支持（如实说明）

Plumb 会针对每种语言协商 LSP 能力，并内置 tree-sitter 索引，无需语言服务器即可搜索和导航。支持分为多个等级——我们宁可准确说明，也不夸大支持的语言数量。

等级	语言	可用功能
一流支持（经 CI 测试，使用真实二进制文件集成）	Go（gopls）、Python（pyright）	完整 LSP：定义、引用、重命名、诊断、层级结构 + 所有写入工具
已验证	Java（jdtls）、Rust（rust-analyzer）、Swift（sourcekit-lsp）、TypeScript/JS（typescript-language-server）、Zig（zls）、Kotlin（kotlin-lsp）、HTML（vscode-html-language-server）	完整 LSP；只需将服务器放入 $PATH，即可自动启用（可通过 [lsp.<lang>] enabled = false 排除任意语言）。HTML 有一项限制：该服务器无法访问文件系统，因此只能根据已打开的文档作答
搜索与导航（tree-sitter，无需 LSP）	31 种以上，包括 JS/TS/TSX、Ruby、C、C#、Elixir、Scala、PHP、JSON、CSS、SCSS、XML、Lua、C++、Objective-C、Dart、Bash、SQL、HCL、Dockerfile、TOML、YAML、Markdown	排序后的符号搜索、大纲，以及通过 Topology 索引探索图结构

真实二进制文件验证已在 macOS 和 Linux 上完成——截至 2026-08-21，全部九个适配器均通过了针对这两个平台上真实服务器二进制文件的集成测试。详情（包括三个看似适配器错误的工具链陷阱）请参阅 docs/adding-an-lsp.md。Windows 已记录但尚未支持——守护进程的 Unix 套接字架构需要移植。

---

工作原理

plumb serve 是一个轻量级、可重连的 stdio 代理。实际工作由一个共享的后台守护进程完成，因此语言服务器在不同聊天会话间始终保持热启动状态。

flowchart TD
    A1["Claude"] --> S1["plumb serve *"]
    A2["Codex"] --> S2["plumb serve *"]
    A3["Gemini"] --> S3["plumb serve *"]
    S1 --> K["plumb.sock"]
    S2 --> K
    S3 --> K
    K --> D["plumb daemon **"]
    D --> SDB[("stats.db ***<br/>global — all projects")]
    D --> G["gopls → /projects/foo"]
    D --> P["pyright → /projects/bar"]
    G --> F1[("/projects/foo/.plumb/ ***<br/>topology.db · memory.db")]
    P --> F2[("/projects/bar/.plumb/ ***<br/>topology.db · memory.db")]

* plumb serve 是一个可重连的代理——如果守护进程崩溃或挂起，它会重新启动一个并重放握手，让会话继续运行，Agent 不会察觉。

** 一个共享进程，在每次对话中重复使用。

*** SQLite。一个全局 stats.db（工具统计数据 + 情景摘要）；每个工作区下的 .plumb/ 中有两个项目级索引——topology.db（代码图）和 memory.db（记忆搜索）。架构详情 → docs/architecture.md。

语言服务器在不同聊天会话间保持热启动状态，每个路径的锁由所有连接共享，符号索引会在每次写入后实时更新。完整架构 → docs/architecture.md。

---

监控（TUI）

不带任何参数运行 plumb，即可打开实时仪表板，查看 Agent 正在做什么：每次工具调用的实时情况、守护进程健康状态、各工具的统计信息，以及可供跟踪和筛选的流式日志。这是发现失控循环或确认编辑已生效的最快方法。

---

核心功能

Plumb 提供 61 个工具。你会经常使用的工具：

session_start · workspace_symbols · get_definition · find_references · rename_symbol · edit_file · transaction_apply · diagnostics

其他工具涵盖文件系统读写、LSP 层级结构、分层 git、可选的本地 Topology 索引（排序搜索 + 影响范围／路径分析，无需语言服务器）、持久化项目级记忆，以及跨 Agent 协作（对等会话、Agent 邮箱、可选启用的意图和知识交接）。完整 API 参考：docs/tools.md。

---

配置

全局或项目级 config.toml，也可以使用环境变量。运行 plumb config show，查看包含来源信息的最终配置。

[edits]
strict = true                  # require read_file before edit_file
rate_limit_per_minute = 30     # bound runaway agent loops

[git]
allow_destructive = false      # reset/checkout/rebase off by default
allow_push = false             # push/fetch/pull off by default

完整设置参考：docs/configuration.md。

---

难点所在

Agent 已经能够很好地阅读代码；而无人监督地编写代码——以并发、事务化、可恢复的方式进行——仍未得到解决。Plumb 押注这是值得优先解决的另一半。项目还处于早期阶段，语言支持范围也说明了这一点：小而经过验证的核心，其余部分则明确标记为实验性。

---

路线图

Plumb 尚未达到 1.0。核心功能——写入安全性、弹性守护进程、Topology 索引和项目记忆——已在日常使用。迈向 1.0 的工作主要是验证核心之外的功能，并改进分发。欢迎提交问题和想法。

已发布

• 支持并发安全、原子化、事务化写入，并可回滚
• 崩溃后可恢复并重新连接的守护进程
• Tree-sitter Topology 索引 + 项目级记忆
• 跨 Agent 协作：对等状态感知 + Agent 邮箱（默认启用），意图 + 知识交接（可选启用）
• 已验证的 Go 和 Python LSP 适配器（使用真实二进制文件）

迈向 1.0。 Plumb 不会从 0.9 直接跃升至 1.0，而是连续发布一系列主题明确的小版本——0.10 到 0.19——每个版本围绕一个连贯的主题。**0.19.x 是最后一个 0.x 版本；**之后将发布 1.0，作为明确的稳定性承诺。有意将原生 Windows 支持安排在 1.0 之后（1.1），而非设为 1.0 的门槛。主题规划如下：

• 0.10 — 分发 + 如实说明功能（Homebrew、语义重排序 → 正式发布）
• 0.11 — 使用真实二进制文件验证实验性 LSP 适配器（zls ✓ 已验证；Kotlin ✓ 已在 JetBrains 的 kotlin-lsp 上验证）
• 0.12 — 通过 Build Server Protocol 指南支持 Xcode 上的 Swift
• 0.13 — 守护进程稳健性（git 写入崩溃安全、存活探测）
• 0.14 — Agent 易用性 + 工具界面
• 0.15 — 如实说明功能 + 完整配置选项
• 0.16 — 稳定化 + 跨平台验证
• 0.17 — 分发 + 便于发现（注册表）
• 0.18 — 验证 + 文档
• 0.19 — 长期运行验证 + 反馈，最后一个 0.x 版本（持续发布补丁，不设正式 RC）
• 1.0 — 正式发布：承诺稳定性 + 核心功能经过验证

完整细节、原因说明，以及 1.0 之后的事项（Windows、Tree-sitter 清理）见 docs/roadmap.md。

贡献

架构和代码风格请参阅 CONTRIBUTING.md 和 AGENTS.md。所有文本均采用澳大利亚英语。贡献即表示你同意遵守行为准则。

许可证

MIT — 详见 LICENSE。