better-edit-tools 文档

大模型自配置指南

Mon, 01 Jan 0001 00:00:00 +0000

大模型自配置指南#

本文档面向需要帮用户把 better-edit-tools 二进制安装到本地的 AI Agent（Kimi Code、Claude Code、Cline 等）。

目标#

下载对应系统的 Release 二进制、校验 SHA-256、放置到稳定位置，并把绝对路径返回给用户或交给下一步 MCP 配置逻辑。

除非用户明确要求，否则不要修改用户的 MCP 客户端配置文件。 你的任务只是把二进制安装好并验证可用。

工作流#

检测平台
- 系统：linux、darwin（macOS）或 windows
- 架构：amd64 或 arm64
- Windows 推荐路径：%LOCALAPPDATA%\better-edit-tools\bin\better-edit-tools.exe
- Linux/macOS 推荐路径：${HOME}/.local/share/better-edit-tools/bin/better-edit-tools
选择 Release URL
- 基础地址：https://github.com/conglinyizhi/better-edit-tools-mcp/releases/latest/download/
- 包名：better-edit-tools-${OS}-${ARCH}.tar.gz
- 校验文件：checksums.txt
- 如需指定版本，把 latest 替换为 tag，例如 v0.12.0。
下载并校验
- 同时下载包和 checksums.txt。
- 计算包的 SHA-256。
- 与 checksums.txt 中的预期值对比。
- 校验不通过时中止，并告知用户。
解压并放置
- 如安装目录不存在则创建。
- 将包解压到安装目录。
- Linux/macOS 下确保二进制有执行权限（chmod +x）。
报告结果
- 返回二进制的绝对路径。
- 提醒 --lang 参数：如果用户 MCP 客户端需要中文工具描述，在 args 中加入 "--lang", "zh"。

平台说明#

系统	推荐安装目录	二进制名
Linux	`${HOME}/.local/share/better-edit-tools/bin`	`better-edit-tools`
macOS	`${HOME}/.local/share/better-edit-tools/bin`	`better-edit-tools`
Windows	`%LOCALAPPDATA%\better-edit-tools\bin`	`better-edit-tools.exe`

自检清单#

二进制存在于报告的绝对路径。
better-edit-tools --version 能返回预期版本。
如果用户使用中文模型，提醒其在 MCP 参数中加入 --lang zh。

CLI 使用

Mon, 01 Jan 0001 00:00:00 +0000

CLI 使用#

better-edit-tools 除了作为 MCP server 运行外，还提供 8 个核心编辑工具的 CLI 子命令，适合 shell 脚本、Pi Agent 或偏好命令行调用的场景。

基本用法#

better-edit-tools <command> [options]

不带子命令时启动 MCP server（stdio）。

子命令#

文件操作#

read：读取文件行范围。
replace：替换指定行范围。
insert：在指定行后插入内容。
delete：删除指定行范围。
write：写入或覆盖文件。

内容识别#

balance：检查括号、引号、标签成对情况。
func-range：检测某行所在的函数或 {} 块范围。
tag-range：检测某行所在的 XML/HTML/Vue 标签范围。

常用示例#

# 读取 1-10 行
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 "..."

# 在第 4 行后插入
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"

# 结构检查 / 范围检测
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

管道与 stdin 支持#

为了避免 shell 引号转义问题，部分命令支持 --content-file 和 --old-file，并把路径设为 - 表示从 stdin 读取。

Go API 文档

Mon, 01 Jan 0001 00:00:00 +0000

betools — Go API 文档#

包说明#

import "github.com/conglinyizhi/better-edit-tools-mcp/pkg/betools"

betools 是 better-edit-tools 的核心编辑库，可直接嵌入 Go Agent 框架使用。它提供文件读取、内容替换、插入、删除、批量操作、全局写入、函数范围检测等原语，所有写操作都经过原子写入（临时文件 + rename）保护。

版本要求：Go 1.26+

公开函数#

文件操作#

`Read`#

func Read(path string, start int, endLine int, brief bool, opts ...Option) (ShowResult, string, error)

读取指定文件的行范围。返回内容包括完整内容和 viewed_code_id（第二个返回值）。viewed_code_id 可传给 Replace 进行行数校验。

start：起始行号（>= 1）
endLine：结束行号。传 0 或负数时自动扩展到所在函数范围（基于 FuncRange）
返回 viewed_code_id：UUID v4，用于后续 Replace 的 session 校验
opts：可选的 WithFileSystem(...) 注入，用于沙箱或 workspace 受限场景

Show 仍然保留为兼容别名。

`Replace`#

func Replace(path string, start, end int, old *string, content string, format string, preview bool, sessionID string, brief bool, opts ...Option) (ReplaceResult, error)

精确替换指定行范围的内容。

start、end：行范围（闭区间），二者均不可省略
old：可选，非 nil 时会校验当前文件内容与 old 是否一致，不一致则返回错误
content：替换后的内容
format：写入后的格式（“trim” 或 “"）
preview：如果为 true，只返回 diff 不写入文件
sessionID：可选，传 be-read 返回的 viewed_code_id 时校验行数一致性
brief：返回精简结果（省略 diff 和 balance）

`Insert`#

func Insert(path string, after int, content string, format string, preview bool, brief bool, opts ...Option) (InsertResult, error)

在指定行后插入内容。

Mon, 01 Jan 0001 00:00:00 +0000

Chip 机制设计决策#

1. 设计动机#

在 MCP（Model Context Protocol）调用链路中，LLM 生成的工具参数常常因为 JSON 转义、字段缺失、格式错乱等原因导致调用失败。一旦失败，原始的参数内容可能只出现在一次性的错误响应里，后续轮次中模型很难精确复现完全相同的内容，尤其是大段代码写入（be-write）或多行替换时。

Chip 机制的核心目标是把“失败现场”或“被删除的内容”临时保存下来，作为模型后续恢复操作的可靠数据来源。它相当于在进程内维护了一个轻量级的 FIFO 缓存队列，让 LLM 可以通过专用工具 be-insert-chip 把之前丢失或删除的内容重新插入到目标文件中，从而降低因一次调用失败而导致整轮任务中断的概率。

2. 何时会创建 chip#

当前有两种场景会触发 chip 记录：

2.1 工具调用失败时自动保存参数#

当某个工具调用返回错误，且入参序列化后的 JSON 长度大于 50 字节时，服务端会调用 SaveChip(tool, args, errMsg) 把原始参数保存为 chip。

func SaveChip(tool string, args map[string]any, errMsg string) string

参数 JSON 长度 ≤ 50 字节时不保存，避免记录过多无意义的短参数。
保存成功后返回 chip ID（如 a3f7b2）；不需要恢复时返回空字符串。

2.2 删除操作时保存被删除内容#

be-delete 在真正落盘前，会把被删除的非空内容通过 SaveContentChip 保存为 chip，并在返回的 warnings 中提示模型：

deletedContent := strings.Join(fileLines[start-1:end], "")
if deletedContent != "" {
 chipID, chipWarn := SaveContentChip("be-delete", deletedContent)
 warnings = append(warnings, fmt.Sprintf("deleted content saved as chip://%s", chipID))
}

这让误删后可以通过 be-insert-chip 把内容重新插回文件。

better-edit-tools 文档

大模型自配置指南

大模型自配置指南#

目标#

工作流#

平台说明#

自检清单#

CLI 使用

CLI 使用#

基本用法#

子命令#

文件操作#

内容识别#

常用示例#

管道与 stdin 支持#

Go API 文档

betools — Go API 文档#

包说明#

公开函数#

文件操作#

Read#

Replace#

Insert#

Chip 机制设计决策#

1. 设计动机#

2. 何时会创建 chip#

2.1 工具调用失败时自动保存参数#

2.2 删除操作时保存被删除内容#

`Read`#

`Replace`#

`Insert`#