better-edit-tools 文档#

better-edit-tools 是面向 coding agent 的可靠文件编辑基础设施。它通过校验模型生成的编辑、原子写入、可执行错误引导和恢复路径，降低过期或异常编辑盲目覆盖文件的风险。

本站围绕三个问题组织内容：

  • 如何使用 MCP server、CLI 或 Go library？
  • 编辑器如何检测模型生成的过期或不安全编辑？
  • 为什么采用当前的校验、恢复和协议行为？

文档包括使用指南、可靠编辑设计说明、历史决策记录和 Go API 参考。

对 AI Agent / LLM 的提示#

本站点的每个页面都提供两种可直接访问的原始格式，方便你抓取和分析：

  • Markdown 源文件：将任意页面 URL 末尾的 index.html 替换为 index.md 即可。例如：
    • HTML 页面：/decisions/
    • Markdown 源：/decisions/index.md
  • 站点摘要 llms.txt：访问根目录的 llms.txt，可获取所有页面的标题、描述及对应的 Markdown 源链接。

如果你发现文档有误或希望讨论某条历史决策，请点击页面中的 发起 issue 按钮，会自动带上 docs:talk 标签。

从这里开始#

项目 README#

better-edit-tools#

English | 中文

面向 coding agent 的可靠文件编辑基础设施：Go 原生实现，同时提供 MCP server、CLI 和可嵌入的 Go library。 它通过校验模型生成的编辑、原子写入、可执行错误引导和恢复路径，降低过期或异常编辑盲目覆盖文件的风险。 实验性项目：工具名称、参数和行为可能随着设计继续调整。不要把具体工具名写死到 prompt 中，优先使用能力描述或动态解析的方式选择工具。 工具描述与错误消息统一为英文，因为它们主要由 LLM 消费。

Coding agent 经常会在文件已经变化后，继续使用此前读取到的内容和行号执行编辑。可靠的编辑器不能只有 write：它还需要识别目标范围、校验前提、在失败时保留原文件，并告诉 agent 下一步该怎么做。

为什么需要它#

better-edit-tools 围绕下面这条编辑闭环设计：

be-read
  |
  +--> 当前内容 + viewed_code_id
              |
              v
be-replace / be-insert / be-delete
              |
              +--> old 内容硬校验
              +--> viewed_code_id 一致性信号
              |
              +--> 成功后原子写入
              +--> 失败后重新读取、重试、回滚或恢复

项目把模型犯错当作系统设计输入，而不是偶然异常。当前的可靠性机制包括：

  • 定点替换前使用精确的 old 内容校验；
  • 使用 viewed_code_id 校验会话中的目标范围是否发生变化；
  • 原子写入与预览模式；
  • 错误消息直接给出下一步工具动作；
  • 使用事务快照和 chip 机制恢复失败操作；
  • 结构感知的范围检测和括号检查，避开字符串与注释的干扰。

详细设计和失败模型参见面向 Coding Agent 的可靠编辑。

如果你是 Go 开发者，想在 Agent 框架中直接嵌入编辑能力，请参见 Go API 文档。

🤖 想让 AI 自动帮你完成本地安装？请参见 大模型自配置指南。

📜 想了解项目历史决策和已关闭的功能提议，请参见 历史决策记录。

让 AI Agent 自己安装：

install this mcp server:https://conglinyizhi.github.io/better-edit-tools-mcp/llms.txt

工具说明#

be-balance#

检查括号、花括号、方括号、HTML/XML 标签闭合以及引号是否成对。扫描时避开字符串与注释中的干扰符号。verbose 参数控制输出详细程度：

  • false（默认）：只输出不匹配项
  • true：输出全部匹配对

——即使混着代码、标记和字符串，也能把结构问题揪出来。

be-read#

只读查看工具，按行号展示文件内容。end 用正数指定结束行，传 0 或负数则自动扩展到所在函数范围。适合在不手动计算区间的情况下快速获取上下文。返回 viewed_code_id（v0.4+），可用于后续 be-replace 的行数校验。

——不用自己算范围，就能看到最需要的那一段上下文。

be-replace#

精确替换指定行范围的内容。支持通过 viewed_code_id 参数关联 be-read 的查询结果，自动校验行数是否一致。传入 old 时会校验当前文件内容是否与旧内容一致，不一致时直接返回错误。服务端也接受 old_text 作为别名。

——已知目标区间时，直接做最小范围精确替换。

be-insert#

在指定行后插入内容，line=0 表示插入到文件开头。服务端也接受 after_line 作为同义参数。增量编辑中最直接的原语，减少对原有内容的扰动。

——把新内容插到准确位置，尽量不扰动原文件。

be-insert-chip#

从文件（file:///绝对路径）或 chip 缓存（chip://{id}）读取内容并插入到指定行。不传 from 时列出所有可用的 chip ID。本工具桥接了失败操作与恢复之间的断层：当 be-write 因 JSON 格式异常失败并将参数保存为 chip 后，be-insert-chip 可将该内容回放到目标文件中。

——从文件或失败缓存回放内容，精确插入到指定位置。

be-delete#

删除单行、行范围或 JSON 数组指定的多行。范围删除时同时接受 start/end 和 start_line/end_line 两种写法。始终围绕行粒度工作，强调操作的可预测性。

——行级精度的删除，结果可控。

be-write#

原始写入工具，直接写入完整文件内容。

  • 单文件：{"file":"...","content":"..."}
  • 多文件：{"files":[{"file":"...","content":"..."}]}

标准 JSON 解析失败时自动切换到状态机式的降级提取逻辑，最大程度保证 AI 生成内容顺利落盘。content 中的字面 \n 会被自动检测并转换为真正的换行符，解决 MCP 链路上 JSON 双重转义导致多行内容变一行的问题。

——就算大模型输出的 JSON 出错，也会尽量把这次长输出救回来。

be-func-range#

定位某一行所属的 {} 块或函数范围。基于花括号计数，兼顾字符串和注释环境，比简单的分隔符查找更适合真实源码。

——找到的不是随便一个花括号，而是真正的函数边界。

be-tag-range#

查找某一行所在的 XML/HTML/Vue 标签配对范围。相当于面向标记语言的范围定位工具。

——直接定位标签对，把编辑边界收敛到真正的容器范围。

设计特点#

  • 原子写入：文件修改通过临时文件 + 重命名完成，进程崩溃也不会损坏源文件。
  • 批量编辑智能排序：批量操作自动从下往上执行，无需手动调整行号顺序。
  • 标准错误响应：严格按 MCP 规范，错误时返回 isError: true。
  • Go 原生实现：无运行时依赖，单二进制分发，启动快、易嵌入。
  • 容错 JSON 解析：AI 生成内容出现转义错误时，be-write 自动降级为字符级提取，避免 JSON 格式问题导致写入失败。
  • Session 状态桥接：be-read 返回 viewed_code_id，be-replace 可传入校验行数一致性。
  • 英文单语描述：工具描述只写英文一份；LLM 客户端天然多语言，描述语言不影响理解质量。

使用方法#

构建#

go build -o better-edit-tools ./cmd/better-edit-tools

编译产物在 ./better-edit-tools。

运行#

./better-edit-tools

添加 --no-prefix 可隐藏工具名的 be- 前缀（如 be-read 变为 read），适用于无法重新编辑工具名的 MCP 控制器。

在 MCP 客户端中注册#

添加到 MCP 客户端配置：

{
  "mcpServers": {
    "better-edit-tools": {
      "command": "/path/to/better-edit-tools/better-edit-tools"
    }
  }
}

Claude Desktop 配置文件位置：

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json

命令行使用#

同一个二进制文件也可以作为命令行工具直接使用。传入子命令时执行单次操作并退出；不传子命令时仍按原有行为启动 MCP server。

# 读取
./better-edit-tools read --file main.go --start 1 --end auto

# 替换
./better-edit-tools replace --file main.go --start 5 --end 10 --content "..."

# 插入
./better-edit-tools insert --file main.go --after-line 4 --content "..."

# 删除
./better-edit-tools delete --file main.go --start 5 --end 10

# 写入
./better-edit-tools write --file main.go --content "package main\n\nfunc main() {}"

# 结构检查 / 范围检测
./better-edit-tools balance --file main.go
./better-edit-tools func-range --file main.go --line 12
./better-edit-tools tag-range --file index.html --line 8

使用 --output json 输出机器可解析的 JSON，--preview 只查看 diff 不写入文件。

./better-edit-tools read --file main.go --start 1 --end 10 --output json
./better-edit-tools replace --file main.go --start 5 --end 10 --content "..." --preview

注意：viewed_code_id 和事务/快照工具依赖进程内 session 状态，目前仅保留在 MCP 模式下使用。

安装#

安装脚本根据当前系统和架构自动下载最新 Release，校验 SHA-256 后安装到 ~/.local/share/better-edit-tools/bin/。也可传 tag 参数安装指定版本。

bash <(curl -fsSL https://raw.githubusercontent.com/conglinyizhi/better-edit-tools-mcp/main/scripts/install.sh)
bash <(curl -fsSL https://raw.githubusercontent.com/conglinyizhi/better-edit-tools-mcp/main/scripts/install.sh) v0.2

Release 产物提供 Linux、macOS、Windows 的 amd64/arm64 包和对应的 .sha256 校验文件。Windows 使用 .zip 打包。Release notes 按 Conventional Commits 分组生成。

致谢#

工具集中的 replace、insert、delete 等操作灵感来自 includewudi/fast-edit。

许可证#

MIT

面向 Coding Agent 的可靠编辑 Forward