企业官网建设流程全解析

Agent Zero text_editor_remote 工具指南：通过 A0 CLI 安全地远程读写与修补主机文件

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero

导读

text_editor_remote是 Agent Zero（plugins/_a0_connector 连接器插件）提供的远程文件编辑工具：当 A0 CLI 客户端连接到当前 Agent Zero 实例并广播了远程文件访问能力时，Agent 即可通过该工具在运行 CLI 的那台机器上执行文件的读取（read）、整体写入（write）与局部修补（patch）。本文以 agent.system.tool.text_editor_remote.md 为骨架，结合 text_editor_remote.py、text_editor_freshness.py 等源码，完整讲解参数契约、三种 patch 形式、新鲜度（freshness）防呆机制、权限模型与实战调用示例，帮助你区分"CLI 主机文件"与"服务器/Docker 文件"两条编辑通道，并掌握在远程机器上精准、安全地修改文件的完整流程。

何时使用 text_editor_remote：远程文件与服务器文件的边界

text_editor_remote的设计初衷是让 Agent 直接操作用户本机（即运行 A0 CLI 的机器）上的文件。其提示词明确规定了适用场景：

• 用户要求访问已连接的本地机器上的文件；
• 用户要求访问A0 CLI 主机上的文件；
• 用户明确表示不要使用 Docker/服务器文件。

在这些场景下，Agent 应使用text_editor_remote，而不是服务端（server-side）的文件工具。反之，如果任务对象是 Agent Zero 自身运行时（服务器/Docker 一侧）的文件，则应使用常规的服务端文件工具。边界规则在 host-file-editing 技能 中被进一步强调："这些路径和文件属于 CLI 主机，不属于 Agent Zero 服务器或 Docker 容器"。

提示词还特别指出路径语义的关键区别：相对路径是相对于 CLI 主机文件系统的，Agent 绝不能把相对路径改写成/a0/usr/workdir这样的形式——该路径属于 Agent Zero 服务器/Docker 一侧，改写会导致文件定位错误甚至误操作服务器文件。

参数契约：action、path 与三种操作模式的参数要求

工具的完整参数定义如下：

从源码 text_editor_remote.py 可以看到参数校验是严格的前置门：

• action缺失时返回action is required (read, write, or patch)；
• action不在{read, write, patch}内返回Unknown action: ...；
• path为空返回path is required；
• write缺少content返回content is required for write。

也就是说，Agent 若以错误形态调用该工具，会得到明确的可读错误信息，而不是静默失败，这保证了提示词与运行时行为的一致性。

read：按行范围读取

read可选传入line_from与line_to（源码中通过int()强制转换，text_editor_remote.py），用于控制返回内容的行数，避免大文件一次性灌满上下文。成功响应会返回文件路径、总行数（total_lines）与内容，例如：

README.md 128 lines >>> <文件内容> <<<

write：整体写入

write要求提供content，其语义是用新内容整体替换文件，或创建新文件。提示词与技能都强调：write只应在"确实需要整体替换或创建整个文件"时使用；用户说"改一下"或"不要重写整个文件"时，应优先走patch通道。

patch：三种修补形态

patch是核心能力，且三种形态互斥。源码 patch_request.py 中的parse_patch_request会执行"恰好一种"校验：edits、patch_text、old_text/new_text同时出现多个时返回错误provide exactly one patch form: edits, patch_text, or old_text/new_text；一个都没有时返回edits, patch_text, or old_text/new_text is required for patch。

patch 形式一：old_text + new_text（精确替换）

适用于简单"把 X 改成 Y"的请求。约束是old_text必须精确匹配文件中唯一一段现有文本；如果它命中多处，需要加长old_text以缩小匹配范围，否则无法唯一确定替换目标。这是默认推荐的最安全补丁形式。

源码中该形态会先被转换为统一上下文补丁：exact_replace_to_patch_text生成*** Begin Patch/*** Update File: <path>包裹的-（删除）与+（新增）行，再以patch_text形式下发（text_editor_remote.py、patch_request.py）。

patch 形式二：patch_text（上下文锚定补丁）

适用于"上下文锚定"的修改，尤其在插入/删除之后、行号可能已发生偏移的场景。技能 host-file-editing 给出了 patch_text 的书写规则：

• patch_text针对单个文件支持 update hunk；
• 插入：使用一个@@ existing line锚点，后续每行以+开头表示新增行；
• 替换：使用@@ before target后跟-old与+new配对；或使用@@ old target后跟同样的替换对；
• 同一个 hunk 中，同一行旧文本不能既作为上下文又作为删除（不能重复）；
• 每个非头部内容行必须以且仅以三种前缀之一开头：空格（上下文）、+（新增）、-（删除）；
• 一次插入不能堆叠多个@@锚点。

patch 形式三：edits（行号区间编辑）

edits是一组基于行号的小范围编辑，仅应在"刚读取过最新内容"的前提下使用（提示词原话：editsonly for fresh, surgical line ranges）。它面向的是基于最新远程读取结果的行号区间手术式修改；如果新鲜度检查拒绝了一个行号补丁，应该重新读取文件并用更新后的行号重试。

新鲜度机制：防止基于过期行号的破坏性修补

行号编辑最大的风险是"读到的是旧版本，patch 的是新版本"导致错位误伤。为此连接器实现了新鲜度（freshness）检查：

• 每次成功的read/write都会记录该文件的元数据（realpath、mtime、total_lines），存储于 Agent 数据中以_a0_connector_text_editor_remote_mtimes为键（见 patch_state.py 与 text_editor_freshness.py）。
• 在执行基于行号的edits修补前，工具会先发一个stat操作获取 CLI 主机上文件的当前元数据，再调用check_patch_freshness比对 mtime：若文件自上次读取后已变化，返回patch_stale_read；若从未读取过该文件，返回patch_need_read（patch_state.py）。
• 这两个错误码在 text_editor_remote.py 中会被映射为对应的提示模板（fw.text_editor.patch_need_read.md、fw.text_editor.patch_stale_read.md），引导 Agent"先 read 再 patch"。
• 修补成功后，工具会根据补丁的行数变化推演文件新状态（apply_patch_post_state）：只有当编辑是"等量替换"（删除行数等于新增行数）且行数对得上时才信任新 mtime，否则将状态标记为 stale，强制后续操作重新读取（patch_state.py）。

此外，如果连接的 CLI 版本过旧、不支持stat操作（错误信息包含unknown op: stat），工具会返回unsupported_cli_freshness，提示"升级 CLI 后重试"（[text_editor_remote.py](https://link.gitcode.com/i/2c0b3593a8a4071ab7c4fab9a5a842d0#L34-L37, L298-L303)），避免在无新鲜度保护的情况下盲目行号修补。

可用性与权限：无 CLI 连接、只读模式下的行为

工具的可用性和权限在运行时检查，而不是静态假设。提示词要求：如果没有 CLI 连接、远程文件访问被禁用、或写入/修补需要 Read&Write 权限，Agent 必须如实向用户报告，绝不能静默回退到服务端文件工具。

源码 text_editor_remote.py 的判定逻辑如下：

• 当前上下文中没有任何 CLI 客户端连接：返回no CLI client connected to Agent Zero. Make sure the CLI is connected to this instance.；
• 存在候选客户端但都不允许写（write_enabled为假）且当前操作是write/patch：返回no connected CLI currently allows remote file writes. Press F3 to switch the CLI to Read&Write.；
• 没有任何客户端广播远程文件访问能力：返回no connected CLI currently advertises remote file access.。

这里对应两种访问模式（见 host-file-editing 技能 的 Access Modes）：

• Read&Write：允许读、写、修补，可修改 CLI 主机；修改应保持窄小而有意（keep changes narrow and intentional）。
• Read only：仅可检查文件；若写入被阻止，告知用户按F3将本地文件访问切换到 Read&Write。

提示词的注入本身也是按需的：remote_tool_prompts.py中的_remote_file_prompt_available只在该连接广播了enabled的远程文件元数据时才返回真（remote_tool_prompts.py），而扩展 _70_include_remote_tool_stubs.py 会在构建工具提示时动态注入或移除本提示词——没有连接时 Agent 甚至看不到这个工具。

完整调用示例

以下 JSON 是提示词中给出的标准调用形态（读取已连接本地机器上的文件）：

{ "thoughts": [ "The user asked for a file on the connected local machine, so I should read it through the A0 CLI host." ], "headline": "Reading file on connected local machine", "tool_name": "text_editor_remote", "tool_args": { "action": "read", "path": "README.md", "line_from": 1, "line_to": 80 } }

对应地，一个"精确替换"的 patch 调用形如：

{ "tool_name": "text_editor_remote", "tool_args": { "action": "patch", "path": "config.yaml", "old_text": "timeout: 30", "new_text": "timeout: 60" } }

一个基于最新读取的行号编辑（edits）调用形如：

{ "tool_name": "text_editor_remote", "tool_args": { "action": "patch", "path": "src/main.py", "edits": [ { "from": 42, "to": 43, "content": " return value\n" } ] } }

底层调用链：文件操作如何抵达 CLI 主机

text_editor_remote本身不直接读文件，而是把操作通过 WebSocket 事件connector_file_op发送给选中的 CLI 客户端，由 CLI 在主机上执行后再把结果（可能以分块的 JSON/base64 帧connector_file_op_result返回，见 AGENTS.md）送回。关键链路（text_editor_remote.py）：

1. 依据上下文（context_id）收集候选客户端（remote_tool_sids_for_context），并调用select_remote_file_target_sid选择目标；写操作会要求write_enabled；
2. 生成op_id（UUID），把op、path、context_id及附加参数（如line_from/line_to、content、patch_text、edits）打包；
3. 注册一个 pending 文件操作（store_pending_file_op，挂载 asyncio Future），随后通过共享的 WebSocket 管理器向目标 socket 广播事件；
4. 以FILE_OP_TIMEOUT = 30.0秒等待响应；CLI 断开返回"selected CLI client disconnected"，超时返回timed out waiting for CLI to respond（[text_editor_remote.py](https://link.gitcode.com/i/2c0b3593a8a4071ab7c4fab9a5a842d0#L32, L245-L254)）。

失败处理与最佳实践清单

综合提示词与技能文档，推荐的编辑流程与失败处理如下：

编辑流程（Editing Flow）：

1. 检查文件前、或准备基于行号的编辑前，先用read；
2. 只有整体替换/新建文件才用write；
3. 简单精确替换优先用patch+old_text/new_text；
4. 上下文锚定修改（尤其插入/删除后行号可能偏移）用patch_text；
5. 仅基于最新一次远程读取结果，用patch+edits做小范围行号编辑；
6. 行号补丁被新鲜度检查拒绝时，重新read并用更新后的行号重试。

失败处理（Failure Handling）：

• 无 CLI 连接：请用户将 A0 CLI 连接到当前 Agent Zero 实例；
• 写入被阻止：告知用户按 F3 切换到 Read&Write；
• 超时或 CLI 断连：总结失败原因，等待重连后重试。

复杂编辑：对于复杂的远程编辑，可选择性加载技能host-file-editing（SKILL.md），它提供了上述边界、访问模式、patch 文本规则与失败处理的完整指引，是 Agent 在远程主机上安全编辑文件的"操作手册"。

测试与契约保障

该工具的提示词与运行时行为被仓库测试显式锁定：例如 test_tool_action_contracts.py 引用了 agent.system.tool.text_editor_remote.md 作为契约的一部分，test_a0_connector_prompt_gating.py 验证远程工具提示词按连接元数据动态注入/移除的门控逻辑，test_default_prompt_budget.py 则确保这些提示词在默认提示词预算内可控。可以推断，提示词中"无连接时报错而非回退服务端工具""写操作需 Read&Write"等约束均有对应的自动化验证，这保证了不同版本间该工具的行为一致性。

小结

text_editor_remote把 Agent 的编辑能力安全地延伸到 CLI 主机文件系统：它以明确的参数契约约束 read/write/patch 三种操作，以"三种 patch 形态互斥 + 新鲜度检查 + 权限门控"层层防护，确保远程文件修改既精准又不越界。使用时牢记两条铁律：用户要的是本机/CLI 主机文件时用它，绝不回退服务端工具；相对路径永远指向 CLI 主机，绝不改写成/a0/usr/workdir。配合host-file-editing技能与 F3 权限切换，即可在远程主机上完成从读取、精确替换到上下文锚定修补的完整文件操作。

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero