编码基本工具

[SATA260]

编码基本工具

功能职责

给 Agent 一组改工作区的基本工具：读文件、改文件、列目录、搜索、跑命令，以及读写工作区里的 markdown 计划。

• 按路径读文件，可指定起始行和行数
• 整文件写入，或按旧文本替换改一处
• 列目录、按内容搜索、按文件名查找
• 在工作区里跑 bash 或 powershell，可取消
• 列出、读取、覆盖工作区 .cursor/ 下的 markdown 计划
• 路径先落到本会话工作目录；目录外必须等人批过才能执行
• 超长输出截断，必要时落到旁路文件，不撑爆上下文

边界

• 不冻结会话工作目录；只消费会话上已有的目录
• 不实现 Git；用户侧 Git 仍走原有仓库操作
• 不实现记忆工具；目录和专题仍走已有记忆
• 不决定 ask / plan / agent 本轮能跑哪些名字；未绑定的调用由三模式拒绝
• 计划工具只动 .cursor/ 下的 markdown；改仓库其他文件用 write / edit
• 一次替换只改第一处匹配；匹配不到或匹配不唯一则失败，不静默改错
• 工具失败写成结果喂回模型，不打死这一次执行
• 同一会话里改文件的调用排队，避免两处同时写同一份

内部拆分

工作区路径（Workspace）

把模型给的路径收成工作区内的绝对路径，并判断是否出界。不管文件内容，不跑命令。

type PathRef struct {
    Workspace string // 本会话已冻结的工作目录
    Raw       string // 模型给的相对或绝对路径
    Abs       string // 收成后的绝对路径
    Outside   bool   // 落在工作目录外
}

func Resolve(workspace, raw string) (PathRef, error) // 收成绝对路径，并标出是否出界。
func InWorkspace(workspace, abs string) bool         // 判断绝对路径是否仍在工作目录内。

读文件（Read）

读一个文件给模型看。不改磁盘。

type ReadRequest struct {
    Path   PathRef
    Offset int // 起始行，从 1 计；0 表示从头
    Limit  int // 最多返回多少行；0 表示不限制
}

type FileView struct {
    Path      string
    Content   string
    Truncated bool
}

func Read(req ReadRequest) (FileView, error) // 读文件；超长则截断并标明。

改文件（Write）

整文件覆盖，或按旧文本替换一处。不列目录，不跑命令。

type WriteRequest struct {
    Path    PathRef
    Content string
}

type EditRequest struct {
    Path PathRef
    Old  string // 要替换的原文，必须唯一
    New  string
}

type Change struct {
    Path string
    Diff string // 给人看的行级差异
    Line int    // 第一处改动的新文件行号
}

func Write(req WriteRequest) (Change, error) // 覆盖写入整个文件。
func Edit(req EditRequest) (Change, error)   // 只替换第一处唯一匹配；不唯一则失败。

浏览（Explore）

列目录、按内容搜、按名字找。不改文件。

type ListRequest struct {
    Path PathRef
}

type SearchRequest struct {
    Workspace string
    Pattern   string
    Path      string // 缩小范围；空则整个工作区
}

type FindRequest struct {
    Workspace string
    Name      string // 文件名或通配
    Path      string
}

type Entry struct {
    Path  string
    IsDir bool
}

type Match struct {
    Path string
    Line int
    Text string
}

func List(req ListRequest) ([]Entry, error)   // 列出该目录下的条目。
func Grep(req SearchRequest) ([]Match, error) // 按内容搜索。
func Find(req FindRequest) ([]Entry, error)   // 按文件名查找。

命令（Shell）

在工作区里跑一条命令。不解释 Git 语义，不写计划文件。

type CommandRequest struct {
    Workspace string
    Program   string // bash 或 powershell
    Script    string
}

type CommandResult struct {
    Output    string
    ExitCode  int
    Truncated bool
    FullPath  string // 超长时旁路文件路径
}

func Run(req CommandRequest) (CommandResult, error) // 执行命令并收回输出。
func Cancel()                                       // 取消进行中的命令。

计划文档（Plan）

只在工作区 .cursor/ 下读写 markdown 计划。不改仓库其他文件。

type PlanDoc struct {
    Name    string // 短文件名；无后缀时补 .md
    Content string
}

func ListPlans(workspace string) ([]string, error)             // 列出已有计划名。
func ReadPlan(workspace, name string) (PlanDoc, error)         // 读一篇计划。
func WritePlan(workspace string, doc PlanDoc) (PlanDoc, error) // 覆盖写一篇计划。

流程

用户想让 Agent 看文件、改一处、搜一下或跑条命令；规划时只动计划文档。出工作区的路径要等人批准。

// 用户已有会话和工作目录，输入「读这个文件」
Run.Start(...)
Model.Stream(...)
Workspace.Resolve(...)
Read.Read(...)

// 用户输入「把这段换成那样」
Workspace.Resolve(...)
Write.Edit(...)

// 用户输入「搜一下调用点」
Explore.Grep(...)

// 用户输入「跑测试」
Shell.Run(...)

// 用户输入「先写计划」
Plan.WritePlan(...)

// 用户取消正在跑的命令
Shell.Cancel(...)

// 模型指向工作区外的路径
Workspace.Resolve(...) // Outside=true
// 未批准则不执行；批准后再 Write / Read / Shell