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)

在指定行后插入内容。

after：在此行后插入。传 0 表示在文件最开头插入
content：插入的内容
format、preview、brief：与 Replace 语义一致

`Delete`#

func Delete(path string, start, end int, format string, preview bool, brief bool, opts ...Option) (DeleteResult, error)

删除指定行范围。

start、end：行范围（闭区间），二者均不可省略
format、preview、brief：与 Replace 语义一致

`Write`#

func Write(spec string, preview bool, brief bool, opts ...Option) (WriteResult, error)

原始写入工具，直接覆盖文件内容。支持单文件和批量文件写入。

spec：JSON 字符串
- 单文件：{"file":"...","content":"..."}
- 多文件：{"files":[{"file":"...","content":"..."}]}
preview：如果为 true，只返回结果不写入文件
brief：返回精简结果（省略单文件详情）
JSON 解析失败时自动降级为字符级提取

范围检测#

`FuncRange`#

func FuncRange(path string, line int, opts ...Option) (FunctionRangeResult, error)

检测某一行所在的 {} 块或函数范围。支持 func、type、method 关键字回溯。

`TagRange`#

func TagRange(path string, line int, opts ...Option) (TagRangeResult, error)

检测某一行所在的 XML/HTML/Vue 标签配对范围。

`ResolveTargetSpan`#

func ResolveTargetSpan(path string, target ContentTarget, opts ...Option) (TargetSpan, error)

根据 ContentTarget 解析目标范围。ContentTarget.Kind 支持 "line"、"function"、"marker"、"tag"。

结构平衡检测#

`CheckStructureBalance`#

func CheckStructureBalance(path string, verbose bool, opts ...Option) (string, error)

检查文件中括号、花括号、方括号、HTML/XML 标签闭合和引号成对情况。

verbose=false：只输出不匹配项
verbose=true：输出全部匹配对

Session 管理#

`CreateSession`#

func CreateSession(file string, start, end int, opts ...Option) string

创建一个读会话，返回 UUID。SessionFromCache 的核心调用方。

`GetSession`#

func GetSession(id string) *ReadSession

按 UUID 查询读会话。已过期（>24h）或不存在时返回 nil。

`SessionFromCache`#

func SessionFromCache(id string, opts ...Option) (s *ReadSession, warning string)

查询会话并校验文件是否变更（行数对比）。文件变更时返回非空 warning 但不会阻塞操作，包含头尾样本行帮助 LLM 重新定位。

`CleanupSession`#

func CleanupSession(id string)

手动删除一个读会话记录。过期会话由后台 goroutine 每 30 分钟自动清理。

文件系统注入#

func WithFileSystem(fsys FileSystem) Option

通过该选项把 betools 限制到自定义文件系统，例如 workspace 包装器或沙箱视图。

Chip 存储#

`SaveChip`#

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

保存失败的 MCP 工具调用参数。当参数 JSON 长度 > 50 时写入 chip 存储。返回 chip ID，参数过短时返回 0。

内部维护一个最大 10 条记录的 FIFO 队列，同时持久化到 /tmp/bet-chips/。

`GetChip`#

func GetChip(id int) (*ChipRecord, error)

按 ID 查询 chip 记录。先从内存查找，内存中不存在时从 /tmp/bet-chips/chip-{id}.json 回退读取。

`ListChips`#

func ListChips() []int

返回内存中所有 chip ID，按存入顺序排列（旧 → 新）。

公开类型#

操作结果#

类型	字段	说明
`ShowResult`	Status, File, Start, End, Total, Content	文件读取结果
`ReplaceResult`	Status, File, Removed, Added, Total, Diff, Balance, Affected, Preview, Warning	替换结果。Warning 由 session 校验产生
`InsertResult`	Status, File, After, Added, Total, Diff, Balance, Affected, Preview	插入结果
`DeleteResult`	Status, File, Total, Diff, Balance, Affected, Preview	删除结果
`WriteResult`	Status, Files, Results([]WriteFileResult), Degraded, Warning, Preview	写入结果。Degraded 表示是否启用了降级解析
`WriteFileResult`	File, Lines, Bytes	写入的单文件结果
`FunctionRangeResult`	Start, End	函数范围结果
`TagRangeResult`	Start, End, Kind, Tag	标签范围结果。Tag 在单行标签时返回

平衡检测类型#

类型	字段	说明
`MatchedPair`	Symbol, OpenLine, CloseLine, Depth	成对符号
`UnbalancedItem`	Symbol, Line, Expected	不匹配符号
`QuoteWarning`	Symbol, Count, Lines	引号警告

批量操作输入#

类型	字段	说明

Session 相关#

类型	字段	说明
`ReadSession`	File, StartLine, EndLine, LineCount, CreatedAt	读会话记录

Chip 相关#

类型	字段	说明
`ChipRecord`	ID, Tool, Args	工具调用参数快照

目标解析#

类型	字段	说明
`ContentTarget`	Kind, Value	目标描述
`TargetSpan`	Start, End	解析为行范围

写入参数#

类型	字段	说明
`WriteSpecItem`	File, Content	单文件写入参数

错误哨兵#

var ErrInvalid = errors.New("invalid argument")
var ErrRead    = errors.New("read error")
var ErrWrite   = errors.New("write error")

所有 betools 返回的错误均可通过 errors.Is 与这三个哨兵值匹配。

betools — Go API 文档#

包说明#

公开函数#

文件操作#

Read#

Replace#

Insert#

Delete#

Write#