Patchloom

Patchloom

一个二进制文件，适用于所有平台。为 AI Agent 提供结构化文件编辑。

Patchloom 是一个单二进制命令行工具，可让 AI 编码 Agent 在任何操作系统上安全、结构化地编辑文件。它按选择器（而非正则表达式）编辑 JSON、YAML 和 TOML，保留注释，理解 20 种语言的代码结构，将多个文件编辑合并为一次工具调用，并且在 Linux、macOS 和 Windows 上的行为完全一致。

它不是通用文件系统 MCP。 默认的 MCP 文件系统服务以文本形式读写文件。Patchloom 还提供试运行预览、由解析器支持的配置和 Markdown 编辑、AST 操作、支持撤销的多文件 batch/tx，以及供宿主使用的稳定 error_kind 提取结果。完整的编码 Agent（Claude Code、Codex、Cursor）负责控制循环；Patchloom 是它们（或 Rust 嵌入程序）调用的工具层。

# Edit a YAML value by selector without breaking comments or formatting
patchloom doc set config.yaml database.port 5432 --apply

# Batch 6 file edits into a single 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？ | 安装 | 快速开始 | 命令 | 对比 | 如何选择 | 架构 | 状态

为何选择 Patchloom？

问题所在

AI Agent 通过工具调用编辑文件。每次调用都需要往返一次 LLM。当任务涉及配置文件时，这个过程有三种失败模式：

1. 语法损坏。 Agent 使用文本替换来处理 JSON、YAML 或 TOML，导致输出无效（括号不匹配、缩进混乱、注释丢失）。
2. 往返开销。 编辑 6 个文件意味着需要 6 次独立的工具调用。每次都要等待 LLM 生成、执行、读取结果，并规划下一次调用。
3. 平台碎片化。 在 Linux 上，Agent 使用 sed、jq、grep。在 Windows 上，这些工具都不存在。Agent 只能改用冗长的 PowerShell，或因不熟悉语法而出错。

patchloom 如何解决这些问题

使用 patchloom 后的变化

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

Agent: batch with
  all 6 edits     ─── tool call ───▶  25s



                  5 round-trips saved
                                    Total: ~25s

主要功能

何时使用 patchloom，何时使用原生工具

Patchloom 并非所有文件操作的替代品。它的说明会准确告知 Agent 何时使用它，以及何时原生工具更快：

正确性优先于速度

对于简单的单文件编辑，Patchloom 并不比原生工具快。此类操作请使用原生工具。但原生文本替换无法安全地编辑结构化文件：对 YAML 使用 sed 可能会破坏缩进、删除注释或生成无效语法。doc set 会解析文件、根据选择器更改值，并写入有效内容。这种保证才是关键。

Patchloom 真正更快的场景是批量编辑多个文件。使用原生工具编辑 6 个文件，意味着要与 LLM 往返 6 次。一次 batch 调用就能完成相同的工作，只需往返 1 次。

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

安装

优先选择会随每次 GitHub Release 更新的渠道（Homebrew、Scoop、crates、 npm、Releases）。在 Windows 上，推荐使用 Scoop。winget （Patchloom.Patchloom）会随每次发布提供，通常会在 Microsoft 的发布流水线完成后保持最新 （如果搜索结果过时，请运行 winget source update）。Chocolatey 在社区审核期间通常会滞后。

# Homebrew (macOS/Linux)
brew install patchloom/tap/patchloom

# crates.io (requires Rust 1.95+, includes MCP server)
cargo install patchloom

# npm / npx (downloads the platform binary from GitHub Releases)
npx patchloom --version
# or: npm install -g patchloom

# Scoop (Windows; recommended Windows channel)
scoop bucket add patchloom https://github.com/patchloom/scoop-bucket
scoop install patchloom/patchloom

Linux、macOS 和 Windows 的预构建二进制文件可在 Releases 页面获取。 有关 shell 安装脚本、源码构建、shell 补全以及 winget / Chocolatey 的说明，请参阅安装。

• MCP Registry 名称：mcp-name: io.github.patchloom/patchloom

编辑器扩展

为 VS Code、Cursor、Windsurf 或 VSCodium 安装配套扩展：

• VS Code Marketplace
• Open VSX Registry

该扩展会自动发现 CLI（或为你安装 CLI）、生成 AGENTS.md、配置 MCP 服务，并向命令面板添加快速操作。详情请参阅编辑器扩展指南。

快速入门

1. 设置项目

patchloom init

这会在新项目中创建 AGENTS.md，或将规则追加到现有的 Agent 指令文件中，提供 shell 补全，并检测可配置 MCP 的机会。传入 -y 可跳过确认提示。

如果你只需要规则文本：

patchloom agent-rules >> AGENTS.md

# Or tailor the 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 代码片段。

你的 AI Agent 会读取 AGENTS.md，并了解何时使用 patchloom 而非原生工具。

2. 安全地编辑配置文件

# Parser-backed: changes the value, preserves comments and formatting
patchloom doc set config.yaml database.port 5432 --apply

3. 将多项编辑合并到一次调用中

patchloom batch --apply <<'EOF'
doc.set config.json version '"2.0.0"'
md.upsert_bullet AGENTS.md "Rules" "- Always test"
replace src/main.rs "v1" "v2"
EOF

值优先按 JSON 解析：未加引号的 2.0 会变成数字。像上面那样使用嵌套引号可强制将其设为字符串（Unix shell）。

在 Windows PowerShell 中（不支持 bash heredoc），请将操作写入文件：

@'
doc.set config.json version "\"2.0.0\""
md.upsert_bullet AGENTS.md "Rules" "- Always test"
replace src/main.rs "v1" "v2"
'@ | Set-Content ops.txt -Encoding utf8
patchloom batch --apply ops.txt

或者使用包含 format 和 validate 生命周期的 JSON 计划：

{
  "version": 1,
  "operations": [
    { "op": "doc.set", "path": "config.json", "selector": "version", "value": "2.0.0" },
    { "op": "md.upsert_bullet", "path": "AGENTS.md", "heading": "Rules", "bullet": "- Always test" },
    { "op": "replace", "path": "src/main.rs", "old": "v1", "new": "v2" }
  ],
  "format": [{ "cmd": "cargo fmt --all" }],
  "validate": [{ "cmd": "cargo test", "required": true }]
}

patchloom tx plan.json --apply

tx 计划属于可信输入。format 和 validate 会通过宿主 shell 执行其 cmd 字段（Unix 上为 sh -c，Windows 上为 cmd /C），因此只运行你信任的计划。

4. 或使用 MCP 执行结构化工具调用（无需 shell 语法）

安装并启用 MCP 支持后，启动服务：

PATCHLOOM_MCP_SURFACE=core 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： 设置 PATCHLOOM_MCP_SURFACE=core，启用包含 12 个工具（list_files、搜索/读取/替换、doc/md、execute_plan、operation_schema、server_info）的工具包，让架构保持精简。未设置该环境变量时，产品默认仍提供完整工具清单。执行文件列表和编辑时，优先单独使用 Patchloom MCP（无需再配备第二个文件系统 MCP）。Cursor / Claude / Codex 的粘贴配置和完整安全模型，请参阅 MCP 设置指南。

使用 VS Code、Cursor 或 Windsurf？ Patchloom 扩展会自动完成设置：安装二进制文件、运行 init，并配置编辑器的 MCP 设置。

作为 Rust 库使用

用 Patchloom 替代私有编辑栈的宿主团队：请参阅嵌入式宿主案例研究 （for_agent、peels、fuzzy refuse、apply_fragment、仅路径操作）。

将 patchloom 添加为依赖项（使用 default-features = false 可排除 CLI/MCP/AST）：

[dependencies]
patchloom = { version = "0.37.6", default-features = false } 

use patchloom::api::{self, ApplyMode, ReplaceOptions, edit_error_kind, EditErrorKind};
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",
    &ReplaceOptions::default(),
    ApplyMode::Preview,
    None,
)?;
println!("{}", result.diff);

// Agent hosts: shared primary+fallback policy (unique, require_change, fuzzy @ 0.90)
let opts = ReplaceOptions::for_agent();
// Fail closed: zero matches become EditErrorKind::NoMatch
match api::replace_in_content("body", "missing", "x", &opts) {
    Ok(r) => println!("changed={}", r.changed),
    Err(e) => assert_eq!(edit_error_kind(&e), Some(EditErrorKind::NoMatch)),
}
// for_agent auto-refuses over-wide fuzzy; custom options use api::fuzzy_span_suspicious
// Buffer multi-op + host write: api::refuse_batch_if_suspicious_fuzzy after apply_content_edits
// Invalid options and bad regex peel InvalidInput (CLI/tx typed errors included)
match api::replace_in_content("body", "", "x", &ReplaceOptions::default()) {
    Err(e) => assert_eq!(edit_error_kind(&e), Some(EditErrorKind::InvalidInput)),
    Ok(_) => panic!("empty pattern must error"),
}

// Set a value in a JSON file
api::doc_set(
    Path::new("config.json"),
    "version",
    serde_json::json!("2.0"),
    ApplyMode::Apply,
    None,
)?;

// Multi-doc YAML: merge into document 0 (selector None = root only)
api::doc_merge(
    Path::new("stream.yaml"),
    serde_json::json!({"env": "prod"}),
    ApplyMode::Apply,
    None,
    Some("0"),
)?;

// Sole-path text load: binary → EditErrorKind::Binary; invalid UTF-8 → InvalidEncoding
let _text = api::load_text(Path::new("notes.md"))?;

所有 API 类型均为 Send + Sync。除 api 模块外，工具模块也公开提供：containment（工作区路径保护）、exec（shell 命令执行）、files（文件遍历、load_text_strict、二进制检测）、backup（用于 Apply 后验证/回滚的 restore_path_from_latest_backup），以及 write（采用策略转换的原子文件写入）。需要临时目录的库用户（例如 Agent）可使用 PathGuard::builder(cwd).allow_temp_directory()（可处理 macOS 上的 /tmp）；请参阅 containment 和 api 模块的 rustdoc。多文档裸键和错误根节点合并会通过 edit_error_kind 转换为 EditErrorKind::TypeError。创建/重命名时目标已存在会转换为 EditErrorKind::AlreadyExists（或使用 api::is_already_exists / api::error_kind_str 获取 CLI 稳定的 "already_exists" 字符串）。细粒度类型也提供对应的布尔转换方法（is_not_found、is_conflicts、is_changes_detected、is_type_error、is_format_failed、is_guard_rejected、is_invalid_input、is_no_match、is_ambiguous），与 edit_error_kind 一致。

替换操作的失败时关闭 / shell 令牌选项：CLI 的 replace --require-change 和 --command-position（也适用于 plan/MCP 字段和库中的 ReplaceOptions）。Agent 宿主：在主要和备用替换路径中使用 ReplaceOptions::for_agent()（自动拒绝可疑跨度）；自定义选项在模糊 Apply 后仍需调用 api::fuzzy_span_suspicious / FuzzySpanPolicy；缓冲多操作宿主在 apply_content_edits 后调用 api::refuse_batch_if_suspicious_fuzzy（#2064）。仅供库使用的 AST 修改器：ast_rename / ast_replace_in_symbol / ast_rename_batch（启用 ast + files 功能），以及 FunctionSigEdit::parse_rust。有序的宿主接入流程：嵌入式宿主检查清单（#2009）。完整接口：docs.rs/patchloom。

入门

命令

针对 Agent 优化（比原生工具更快或更安全）

通用命令（也适用于脚本和 CI）

patchloom 的对比

主要区别在于：patchloom 专为 AI Agent 工作流设计。一次 batch 或 tx 调用即可取代 N 次顺序工具调用，减少往返次数并消除部分失败状态。

与 Agent 原生编辑工具的对比

上表将 patchloom 与供人使用的命令行工具进行比较。但 Agent 已经内置了编辑功能：Claude Code 的 edit_file、Cursor 的 apply、Grok Build 的 search_replace、Aider 的 /code 块。为什么还要在此基础上使用 patchloom？

**Agent 原生工具使用文本匹配。**它们查找一段文本并替换它。这适用于源代码，但处理结构化配置文件时就会出错：

database:
  # Production settings
  host: db.prod.internal
  port: 5432  # PostgreSQL default
  pool_size: 10

patchloom doc set config.yaml \
  database.port 5433 --apply

**适合继续使用原生工具的情况：**读取单个文件、简单文本搜索，以及不需要保留注释的单文件文本替换。patchloom 的 Agent 规则会明确告诉 Agent 在何时使用各类方法。

何时使用哪种工具

详细说明：比较 · 嵌入器宿主检查清单 · MCP 设置

库宿主：嵌入器宿主检查清单：双路径 ReplaceOptions::for_agent()（主要路径 + 回退路径，包含 refuse_suspicious_fuzzy），通过 edit_error_kind / is_* / is_fuzzy_span_suspicious 处理错误，并用 #[non_exhaustive] 的 _ 分支；缓冲区多操作后，使用多操作 ContentEditsResult.op_honesty + refuse_batch_if_suspicious_fuzzy（#2064）；plan/tx 使用最宽的 matched_text；可选的 apply_content_edits_to_file_with_span_policy。自定义选项在模糊 Apply 后仍使用 api::fuzzy_span_suspicious / FuzzySpanPolicy。

**上下文预算：**按行范围 read、search --count / --files-with-matches、单次 batch/tx，对大型流使用 --jsonl。

如何与 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

状态

25 个命令对应 5900 多项测试。已使用 Grok 4.3、GPT-5.4 和 Claude Opus 4.6 进行测试。

完整命令参考

所有命令、标志、事务操作和退出代码均记录在**命令参考**中（也可在 docs/reference/README.md 查看）。

许可证

可任选以下许可证之一：

• MIT 许可证（LICENSE）
• Apache 许可证 2.0 版（LICENSE-APACHE）

贡献

请参阅 CONTRIBUTING.md。

在提交拉取请求前进行本地验证，请运行 make check。它涵盖主要的 Linux 测试和 lint 门禁：格式检查、clippy、单元测试（包括功能矩阵任务）、集成测试、PTY 测试、发布说明结构、测试规范、生成文档的新鲜度（check-patchloom-md、check-readme）、server-json-test、verify-homebrew-version-test、打包脚本单元测试（scoop-manifest-test、chocolatey-package-test、pack-mcpb-test、force-release-version-test）、workflow-sanity-test、apply-release-notes-test 和 dco-check-test。它并不涵盖 GitHub 要求的所有检查：audit、deny 和 Windows 检查仍在 GitHub Actions 中运行。在本地迭代时，make check-fast 与之相同，但只跳过 check-patchloom-md（仍会运行 check-readme、server-json-test、verify-homebrew-version-test、打包脚本测试、workflow-sanity-test、apply-release-notes-test 和 dco-check-test）。

拉取请求标题必须使用一个 Conventional Commits 前缀（feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert；不能包含逗号或 +）。请参阅 CONTRIBUTING.md。

所有提交都必须使用 git commit -s 签署。

Agent 集成测试

make agent-test 会运行 19 个 pytest 场景，以验证 AI Agent 在收到指令后能否正确使用 patchloom。make bench-agent 会针对 11 项任务运行 3 路基准测试（CLI 与 MCP、原生方式对比）。使用 MODEL=X 切换模型，使用 RUNS=N 降低方差。需要 LLM API 密钥。不属于 make check 的一部分。详情请参阅 tests/agent/README.md。

安全

有关当前的安全问题报告指南，请参阅 SECURITY.md。