better-edit-tools 文档#

欢迎来到 better-edit-tools 文档站。这里面向开发者、维护者和 AI Agent，提供工具使用说明、历史决策记录以及 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 | 中文

实验性项目：工具名称、参数和行为都可能随着设计继续调整。不要把具体工具名写死到 prompt 里，优先使用能力描述或动态解析的方式选择工具。

一个高性能的 MCP（Model Context Protocol）文件编辑工具集 —— Go 原生实现，提供原子写入、批量编辑智能排序、函数范围自动检测。旨在减少大模型修改文件产生的 token 数量，并尽可能挽回因参数错误导致的各种问题。 工具描述在启动时通过 --lang <zh|en> 本地化；不传则回退到 LANG 环境变量，最终默认英文。

⚠️ 中文用户请注意：如果你使用中文大模型（如 Kimi、文心一言等），请在 MCP 配置中显式添加 "args": ["--lang", "zh"]，否则工具描述会回退为英文，增加模型理解和调用成本。 根据最新的调查结果，暂时不再推荐中文大模型使用中文提示词，因为相同含义下的中文提示词的分词器会让 token 数量更长

如果你是 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 可传入校验行数一致性。
  • 多语言描述：--lang <zh|en> 切换工具描述语言；参数名和行为不变。

使用方法#

构建#

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

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

运行#

./better-edit-tools --lang zh

不传 --lang 时从 LANG 环境变量推断，失败则默认英文。

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

在 MCP 客户端中注册#

添加到 MCP 客户端配置：

{
  "mcpServers": {
    "better-edit-tools": {
      "command": "/path/to/better-edit-tools/better-edit-tools",
      "args": ["--lang", "zh"]
    }
  }
}

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

大模型自配置指南 Forward