# Patchloom
[](https://github.com/patchloom/patchloom/actions/workflows/ci.yml)
[](https://github.com/patchloom/patchloom/actions/workflows/security.yml)
[](https://crates.io/crates/patchloom)
[](https://github.com/patchloom/patchloom/releases/latest)
[](./LICENSE)
[](#)
[](https://github.com/patchloom/patchloom/actions/workflows/ci.yml)
[](https://www.bestpractices.dev/projects/13097)
[](https://securityscorecards.dev/viewer/?uri=github.com/patchloom/patchloom)
[](https://github.com/patchloom/patchloom/actions/workflows/fossa.yml)
[](https://patchloom.github.io/patchloom/)
[](https://marketplace.visualstudio.com/items?itemName=patchloom.patchloom)
[](https://crates.io/crates/patchloom)
**单一二进制文件。全平台支持。专为 AI agent 设计的结构化文件编辑。**
Patchloom 是一个单一二进制文件的 CLI 工具，可为 AI 编码 agent 在任何操作系统上提供安全、结构化的文件编辑功能。它通过选择器（而非正则表达式）编辑 JSON、YAML 和 TOML，保留注释，通过 tree-sitter 理解代码结构（支持 20 种语言），将多个文件编辑批处理为一次工具调用，并在 Linux、macOS 和 Windows 上以完全相同的方式运行。
```
# 通过 selector 编辑 YAML 值，且不会破坏 comments 或 formatting
patchloom doc set config.yaml database.port 5432 --apply
# 将 6 个文件 edits 批量合并为单次 tool call
patchloom batch --apply <<'EOF'
doc.set package.json version "2.0.0"
doc.set config.yaml app.version "2.0.0"
doc.set config.toml project.version "2.0.0"
replace README.md "1.0.0" "2.0.0"
replace CHANGELOG.md "1.0.0" "2.0.0"
file.create VERSION "2.0.0"
EOF
```
**[为什么选择 Patchloom？](#why-patchloom)** | **[安装](#install)** | **[快速开始](#quick-start)** | **[命令](#commands)** | **[对比](#how-patchloom-compares)** | **[架构](#how-it-works-with-your-ai-agent)** | **[状态](#status)**
## 为什么选择 Patchloom？
### 问题所在
AI agent 通过工具调用来编辑文件。每次调用都会产生一次与 LLM 的往返交互。当一个任务涉及配置文件时，该过程有三种失败模式：
1. **语法损坏。** agent 对 JSON、YAML 或 TOML 使用文本替换，导致生成无效输出（大括号不匹配、缩进错误、丢失注释）。
2. **往返开销。** 编辑 6 个文件意味着需要 6 次单独的工具调用。每次调用都要等待 LLM 生成、执行、读取结果并计划下一次调用。
3. **平台碎片化。** 在 Linux 上，agent 使用 `sed`、`jq`、`grep`。而在 Windows 上，这些都不存在。agent 只能退回到冗长的 PowerShell，或者因不熟悉的语法而犯错。
### Patchloom 如何逐一解决
| 问题 | Patchloom 如何解决它 |
|---|---|
| **语法损坏** | `doc` 命令会解析文件，通过选择器路径更改值，并写入有效的输出。保留注释和格式。无需正则表达式。 |
| **往返开销** | `batch` 和 `tx` 将 N 个操作合并为 1 次工具调用。六个文件编辑变成一条命令，失败时支持原子回滚。 |
| **平台碎片化** | 单一的静态二进制文件，零依赖。在 Linux、macOS 和 Windows 上具有相同的命令、相同的标志和相同的行为。 |
### Patchloom 带来的改变
|
**不使用 Patchloom**（6 次工具调用）
```
Agent: edit file 1 ─── tool call ───▶ 15s
Agent: edit file 2 ─── tool call ───▶ 15s
Agent: edit file 3 ─── tool call ───▶ 15s
Agent: edit file 4 ─── tool call ───▶ 15s
Agent: edit file 5 ─── tool call ───▶ 15s
Agent: edit file 6 ─── tool call ───▶ 15s
Total: ~90s
```
|
**使用 Patchloom batch**（1 次工具调用）
```
Agent: batch with
all 6 edits ─── tool call ───▶ 25s
5 round-trips saved
Total: ~25s
```
|
### 核心能力
| 能力 | 功能描述 | 示例 |
|---|---|---|
| **基于解析器的编辑** | 通过选择器编辑 JSON/YAML/TOML，保留注释和格式 | `doc set config.yaml db.port 5432 --apply` |
| **单次调用批量处理 N 个文件** | `batch` 和 `tx` 将操作合并为一次工具调用，并支持回滚 | `batch --apply < ops.txt` |
| **保留注释** | YAML/TOML 的注释在所有编辑操作中都会保留，包括调整数组大小 | `doc append config.yaml tags '"v2"' --apply` |
| **标题感知的 Markdown** | 根据标题（而非行号）编辑章节、表格和列表 | `md table-append README.md --heading "API" --row "\| new \| row \|" --apply` |
| **感知 AST 的代码操作** | 使用 tree-sitter（支持 20 种语言）列出、重命名、替换和分析符号 | `ast rename src/ old_name new_name --apply` |
| **原子回滚** | 如果格式化或验证步骤失败，`strict: true` 会还原所有文件 | `tx plan.json --apply` |
| **MCP server** | 将所有操作作为结构化的 MCP 工具调用公开 | `patchloom mcp-server` |
| **跨平台** | 在 Linux、macOS、Windows 上表现完全一致。不需要 `sed`、`jq`、`grep`。 | 到处使用同一个二进制文件 |
### 何时使用 Patchloom 与原生工具
Patchloom 并不能替代所有的文件操作。它的指令会准确地告诉 agent 何时该使用它，以及何时使用原生工具会更快：
| 任务 | 使用 Patchloom？ | 原因 |
|---|---|---|
| 通过选择器编辑 JSON/YAML/TOML 的值 | **是** | 解析器确保输出有效，并保留注释 |
| 在一项任务中编辑 3 个及以上文件 | **是** | `batch`/`tx` 消除了往返交互 |
| 向 Markdown 表格追加一行 | **是** | 感知标题，无需猜测行号 |
| 读取单个文件 | 否 | 原生的 `read_file` 更快 |
| 简单文本搜索 | 否 | 原生的 `grep` 更快 |
| 单文件文本替换 | 否 | 原生的 `search_replace` 更快 |
### 准确性高于速度
对于简单的单文件编辑，Patchloom 并不比原生工具快。对于这些操作请使用原生工具。但是原生文本替换无法安全地编辑结构化文件：对 YAML 使用 `sed` 可能会破坏缩进、去除注释或产生无效语法。`doc set` 会解析文件，通过选择器更改值，并写入有效的输出。这种保证才是核心意义所在。
Patchloom *确实*更快的地方在于多文件批处理。通过原生工具进行六次文件编辑意味着要与 LLM 进行六次往返交互。而一次 `batch` 调用可以在单次往返中完成相同的工作。
基准测试详情（通过 Grok Build 使用 Claude Opus 4，共 11 项任务）
```
Task PL-CLI MCP Native
────────────────────── ────── ────── ──────
search 18.5s 12.7s 13.9s ◀ ~same
replace 36.1s 26.6s 26.1s ◀ ~same
doc_set 30.9s 16.9s 13.7s ◀ native fastest
md_table 15.5s 13.5s 15.3s ◀ MCP fastest
tx_multi_file 41.4s 28.5s 22.9s ◀ native fastest
batch_6_files 50.6s 46.6s 30.3s ◀ native fastest
batch_mixed_ops 24.7s 13.6s 20.9s ◀ MCP fastest
yaml_comment_preserve 18.1s 11.6s 16.1s ◀ MCP fastest
md_insert 15.0s 11.7s 15.7s ◀ MCP fastest
file_ops 26.0s 16.6s 17.2s ◀ ~same
tidy 45.0s 30.3s 41.7s ◀ MCP fastest
────────────────────── ────── ────── ──────
TOTAL 321.9s 228.5s 233.8s
```
总体而言，MCP 模式胜出（228.5秒 对比 原生 233.8秒），因为结构化的工具调用完全跳过了 shell 语法的构建。MCP 赢了 5/11 项任务；原生赢了 3/11 项；3 项平局。由于 shell 构建的开销，CLI 模式始终是最慢的。
## 安装
```
# Homebrew (macOS/Linux)
brew install patchloom/tap/patchloom
# crates.io (要求 Rust 1.95+，包含 MCP server)
cargo install patchloom
```
适用于 Linux、macOS 和 Windows 的预编译二进制文件位于
[Releases](https://github.com/patchloom/patchloom/releases/latest) 页面。
有关 shell 安装脚本、源码构建和 shell 自动补全设置，请参阅[安装说明](./docs/getting-started/installation.md)。
### 编辑器扩展
为 VS Code、Cursor、Windsurf 或 VSCodium 安装配套扩展：
- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=patchloom.patchloom)
- [Open VSX Registry](https://open-vsx.org/extension/patchloom/patchloom)
该扩展会自动发现 CLI（或为您安装），生成 AGENTS.md，配置 MCP server，并在命令面板中添加快捷操作。详情请参阅[编辑器扩展指南](./docs/getting-started/editor-extension.md)。
## 快速开始
### 1. 设置您的项目
```
patchloom init
```
这会在新项目中创建 `AGENTS.md`，或将规则追加到现有的 agent 指令文件中，提供 shell 自动补全，并检测 MCP 配置机会。传入 `-y` 可跳过确认提示。
如果您只想要规则文本：
```
patchloom agent-rules >> AGENTS.md
# 或者自定义 output：
patchloom agent-rules --mode mcp >> AGENTS.md # MCP-only (no CLI examples)
patchloom agent-rules --platform windows >> AGENTS.md # Windows-only syntax
```
如果存在 `.vscode/` 或 `.cursor/`，`init` 还会输出可直接复制的 `.vscode/mcp.json` 或 `.cursor/mcp.json` 片段。
### 2. 安全地编辑配置文件
```
# Parser-backed：修改值，保留 comments 和 formatting
patchloom doc set config.yaml database.port 5432 --apply
```
### 3. 将多次编辑合并为一次调用
```
patchloom batch --apply <<'EOF'
doc.set config.json version "2.0"
md.upsert_bullet AGENTS.md "Rules" "- Always test"
replace src/main.rs "v1" "v2"
EOF
```
或者使用带有格式化和验证生命周期的 JSON 计划：
```
{
"version": "1",
"operations": [
{ "op": "doc.set", "path": "config.json", "selector": "version", "value": "2.0" },
{ "op": "md.upsert_bullet", "path": "AGENTS.md", "heading": "Rules", "bullet": "- Always test" },
{ "op": "replace", "path": "src/main.rs", "from": "v1", "to": "v2" }
],
"format": [{ "cmd": "cargo fmt --all" }],
"validate": [{ "cmd": "cargo test", "required": true }]
}
```
```
patchloom tx plan.json --apply
```
`tx` 计划是受信任的输入。`format` 和 `validate` 会通过宿主机的 shell（Unix 上为 `sh -c`，Windows 上为 `cmd /C`）运行其 `cmd` 字段，因此请仅运行您信任的计划。
### 4. 或者使用 MCP 进行结构化工具调用（无需 shell 语法）
```
patchloom mcp-server
```
支持 MCP 的 agent 直接以结构化 JSON 形式调用 patchloom 工具，无需进行 shell 引号处理或命令构建。agent 只需发送 `{"path": "config.json", "selector": "version", "value": "2.0"}`，而无需构建 `patchloom doc set config.json version '"2.0"' --apply`。
有关各 agent 的配置和完整的安全模型，请参阅 [MCP 设置指南](./docs/getting-started/mcp-setup.md)。
### 作为 Rust 库使用
将 patchloom 作为依赖项添加（使用 `default-features = false` 可省略 MCP server）：
```
[dependencies]
patchloom = { version = "0.3", default-features = false }
```
```
use patchloom::api::{self, ApplyMode};
use std::path::Path;
// Replace text (preview only, no disk write)
let result = api::replace_text(
Path::new("src/config.rs"),
"old_value", "new_value",
&api::ReplaceOptions::default(),
ApplyMode::Preview,
)?;
println!("{}", result.diff);
// Set a value in a JSON file
api::doc_set(
Path::new("config.json"),
"version",
serde_json::json!("2.0"),
ApplyMode::Apply,
)?;
```
所有 API 类型均为 `Send + Sync`。除了 `api` 模块外，实用工具模块也是公开的：`containement`（工作区路径保护）、`exec`（shell 命令执行）、`files`（文件遍历和二进制检测）以及 `write`（带有策略转换的原子文件写入）。完整接口请参阅 `patchloom::api` 模块文档。
## 新手入门
| 资源 | 您将学到什么 |
|---|---|
| [安装说明](https://patchloom.github.io/patchloom/getting-started/installation.html) | 安装选项和 shell 自动补全 |
| [核心概念](https://patchloom.github.io/patchloom/getting-started/concepts.html) | 写入模式、事务计划和退出代码 |
| [MCP 设置](https://patchloom.github.io/patchloom/getting-started/mcp-setup.html) | 将 patchloom 配置为您 agent 的 MCP server |
| [编辑器扩展](./docs/getting-started/editor-extension.md) | VS Code、Cursor、Windsurf 和 VSCodium 集成 |
| [快速入门](https://patchloom.github.io/patchloom/getting-started/quickstart.html) | 5 分钟演练 |
| [参考](https://patchloom.github.io/patchloom/reference/) | 每一个命令、操作和模式 |
| [示例](./examples/README.md) | 事务计划模板 |
## 命令
### 针对 Agent 优化（比原生工具更快或更安全）
| 命令 | 功能描述 | 适用场景 |
|---|---|---|
| `batch` | 单次调用中面向行的多文件编辑 | 使用简单语法编辑 3 个及以上的文件 |
| `tx` | 带有格式化/验证生命周期的 JSON 计划 | 需要回滚的复杂多文件编辑 |
| `doc` | 基于解析器的 JSON/YAML/TOML 编辑 | 在不破坏语法的情况下更改配置值 |
| `md` | 感知标题的 Markdown 编辑 | 更新文档中的表格、章节和列表 |
| `ast` | 通过 tree-sitter（支持 20 种语言）感知 AST 的符号操作 | 重命名标识符、列出符号、影响分析 |
| `patch` | 应用带有陈旧检测的 unified diff | 安全地重放补丁 |
| `tidy` | 文本文件的空白字符和换行符规范化 | 用于文本整洁度的 CI 检查 |
| `mcp-server` | MCP 协议服务器 | 支持 MCP 的 agent（无需 shell 语法） |
### 通用功能（在脚本和 CI 中同样实用）
| 命令 | 描述 |
|---|---|
| `search` | 跨文本文件进行快速的文本字面量或正则表达式搜索 |
| `replace` | 跨文本文件进行机械的字符串替换，并提供 diff 预览 |
| `append` | 向现有文件追加内容 |
| `create` | 创建包含的新文件 |
| `delete` | 删除文件 |
| `rename` | 移动（重命名）文件 |
| `read` | 读取文件内容，支持可选的行范围 |
| `status` | 显示哪些文件有未提交的更改 |
| `explain` | 用通俗易懂的语言总结 tx 计划 |
| `undo` | 从 `--apply` 创建的备份中恢复文件 |
| `completions` | 生成 shell 自动补全（bash、zsh、fish、elvish） |
| `init` | 在项目中设置 patchloom（agent 规则、补全、MCP） |
| `schema` | 导出具有层级过滤和系统提示词的操作 schema |
| `agent-rules` | 为您的项目生成 agent 指令 |
## Patchloom 的对比
| 工具 | 优势 | Patchloom 的不同之处 |
|------|----------|------------------------|
| **jq** | JSON 查询/转换 | patchloom 还能处理 YAML、TOML、Markdown；支持跨文件批处理；保留注释 |
| **yq** | YAML/JSON 查询/转换 | patchloom 通过 CST 编辑保留 YAML 注释；增加了 Markdown、批处理和原子事务 |
| **dasel** | 多格式获取/设置 | patchloom 增加了批处理（单次调用 N 次编辑）、原子回滚、格式化/验证生命周期 |
| **sd** | 正则表达式查找/替换 | patchloom 增加了基于解析器的结构化编辑；批处理；绝不产生无效的 JSON/YAML |
| **comby** | 结构化代码模式 | patchloom 针对的是配置文件和 agent 工作流，而非源代码模式匹配 |
关键区别在于：patchloom 是专为 AI agent 工作流设计的。一次 `batch` 或 `tx` 调用即可替代 N 次顺序工具调用，从而减少往返交互并消除部分失败的状态。
### 对比 Agent 原生编辑工具
上表将 patchloom 与人类使用的 CLI 工具进行了对比。但是 agent 已经内置了编辑功能：Claude Code 的 `edit_file`、Cursor 的 apply、Grok Build 的 `search_replace`、Aider 的 `/code` 块。为什么还要在其之上添加 patchloom 呢？
**Agent 原生工具使用的是文本匹配。** 它们找到一段文本并将其替换。这对源代码有效，但在结构化配置文件上会失败：
|
**Agent 对 YAML 使用 `search_replace`**
```
database:
# Production settings
host: db.prod.internal
port: 5432 # PostgreSQL default
pool_size: 10
```
agent 将 `port: 5432` 替换为 `port: 5433`。结果取决于具体实现。许多 agent 会丢失行内注释、破坏缩进，或者因为周围的上下文发生变化而导致匹配失败。
|
**Agent 使用 `patchloom doc set`**
```
patchloom doc set config.yaml \
database.port 5433 --apply
```
YAML 解析器更改选择器路径上的值。注释、缩进、键的排序以及所有其他格式都会被保留。输出始终是有效的 YAML。
|
| Agent 原生工具的局限性 | Patchloom 如何解决它 |
|---|---|
| **破坏注释** | CST 级别的 YAML/TOML 编辑可保留所有注释 |
| **每次工具调用只能处理一个文件** | `batch`/`tx` 在一次调用中编辑 N 个文件（在基准测试中快 6.7 倍） |
| **无法回滚** | 如果验证失败，带有 `strict: true` 的 `tx` 会还原所有文件 |
| **依赖平台** | 在 Linux、macOS、Windows 上使用相同的二进制文件和语法 |
| **上下文陈旧风险** | `patch apply` 使用模糊匹配来处理上下文漂移 |
## 它如何与您的 AI Agent 协作
两种集成模式，具备相同的能力：
```
flowchart LR
subgraph CLI["CLI mode (any agent)"]
direction TB
A["patchloom agent-rules >> AGENTS.md"] --> B["Agent reads AGENTS.md"]
B --> C{"What kind of edit?"}
C -->|Simple edit| D["Native tool (faster)"]
C -->|Config edit| E["patchloom doc (safer)"]
C -->|Markdown edit| F["patchloom md (smarter)"]
C -->|Multi-file edit| G["patchloom batch (batched)"]
end
subgraph MCP["MCP mode (MCP-capable agents)"]
direction TB
H["patchloom mcp-server"] --> I["Agent discovers tools via MCP"]
I --> J["Structured JSON tool calls"]
J --> K["No shell syntax needed"]
end
```
## 状态
跨 22 个命令的 1500 多项测试。已通过 Grok 4.3、GPT-5.4 和 Claude Opus 4.6 测试。
| 组件 | 状态 |
|---|---|
| CLI | 已发布在 [crates.io](https://crates.io/crates/patchloom) 和 [Homebrew](https://github.com/patchloom/homebrew-tap) 上 |
| 编辑器扩展 | 已发布在 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=patchloom.patchloom) 和 [Open VSX](https://open-vsx.org/extension/patchloom/patchloom) 上 |
## 完整命令参考
每个命令、标志、事务操作和退出代码都记录在 **[命令参考](https://patchloom.github.io/patchloom/reference/)** 中（也可在 [docs/reference/README.md](docs/reference/README.md) 查看）。
## 许可证
根据以下任一许可证授权：
- MIT 许可证 ([LICENSE](./LICENSE))
- Apache License, Version 2.0 ([LICENSE-APACHE](./LICENSE-APACHE))
由您选择。
### Agent 集成测试
`make agent-test` 会运行 19 个 pytest 场景，以验证 AI agent 在接到指令时是否能正确使用 patchloom。`make bench-agent` 会跨 11 项任务运行三方基准测试（CLI 对比 MCP 对比 原生）。使用 `MODEL=X` 可切换模型，使用 `RUNS=N` 可减少方差。需要 LLM API 密钥。不属于 `make check` 的一部分。详情请参阅 [tests/agent/README.md](./tests/agent/README.md)。
## 安全
有关当前的安全报告指南，请参阅 [SECURITY.md](./SECURITY.md)。