Pi Agent 工具系统：Read、Write、Edit 与 Bash 的实现原理
内容提要
Pi agent的核心工具包括read、write、edit和bash。read按行读取文件，write创建或覆盖文件，edit精确替换唯一匹配的代码，bash执行命令并保留末尾输出。工具间通过观察、决策、修改、验证的闭环协作，确保代码修改安全高效。
延伸解读
精确替换的“乐观锁”设计
edit工具要求oldText唯一匹配，相当于一种轻量级乐观锁。模型基于当前文件版本生成修改，若文件在读取后被其他进程改动，oldText匹配失败，工具会拒绝覆盖，避免基于过期信息修改。相比按行号修改，这更安全，因为文件新增行会导致行号偏移。
bash保留末尾输出的考量
与read保留开头不同，bash默认保留最后2000行或50KB输出，因为测试、编译和日志的错误通常在末尾。若输出被截断，完整输出会保存到临时文件，便于后续查看。这种设计针对调试场景优化，确保模型能获取关键错误信息。
工具协作的闭环流程
四个工具形成观察、决策、修改、验证的闭环：read/bash用于观察，LLM决策，edit/write修改，bash验证。例如，添加接口时，先用bash搜索路由，read读取文件，edit插入路由，write创建控制器，再运行测试验证。这种流程确保修改安全高效。
Q&A
Pi agent的核心工具包括哪些？
Pi agent的核心工具包括read、write、edit和bash。
Pi agent的read工具如何工作？
read工具按行读取文件，支持offset和limit参数，默认最多返回前2000行或50KB，哪个先达到就按哪个截断，并提示模型使用offset继续读取。
Pi agent的write工具如何避免并发冲突？
write工具会为每个文件建立mutation queue，确保对同一文件的写入操作顺序执行，防止多个并行工具同时修改导致内容互相覆盖。
Pi agent的edit工具为什么要求oldText唯一匹配？
edit工具要求oldText精确匹配且唯一，以避免歧义。如果oldText在文件中有多处匹配，工具会拒绝修改，因为不知道应该修改哪一个。这相当于一种轻量级乐观锁，确保修改安全。
Pi agent的bash工具为什么保留末尾输出？
bash工具保留最后2000行或50KB的输出，因为测试、编译和日志输出的错误通常在末尾，这样便于模型查看错误信息。如果发生截断，完整输出会保存到临时文件。
Pi agent的四个工具是如何协作完成代码修改的？
四个工具通过观察、决策、修改、验证的闭环协作。例如，模型先用bash搜索路由，用read读取文件，用edit插入路由，用write创建新文件，再用bash运行测试，如果失败则read相关文件，edit修复，再bash验证。
