Agent 命令系统

内置 Wuu 引擎用 bash 在会话选定的执行环境中运行命令并控制后台任务。普通命令交付退出结果；可选的 Monitor 扩展负责持续观察 CI、API 和日志的变化。外部引擎有自己的命令实现；本页介绍 Wuu 的工具。

任务完成与上下文

主 Agent 会将已授权的任务推进到实现、适当验证和结果交付。它沿用会话中已有的授权，自行解决常规选择，并在用户补充说明或询问状态时保留当前目标。仅要求审查或规划不代表授权实施；提交和远端写入仍遵守会话的授权边界。

通用协作指导在模型请求之间保持稳定。可用工具、权限和可选扩展行为由运行时提供，不在基础提示词中假定存在。工具特有的恢复方法属于工具结果或说明。已完成的观察结果保持原有顺序，新结果和上下文变化通过追加进入会话。Provider 原生响应条目会保留供后续请求使用，包括会话重启后的续接。缓存是否命中仍由 provider 决定，并以返回的用量衡量。

Code Mode 调用与输出预算

Code Mode 默认开启。tools.bash 与直接工具提供相同的运行和控制操作。程序必须等待后台启动完成后再返回；后续程序需要句柄时，可用 store 保存。通过 searchTools("monitor") 和 describeTool(name) 获取扩展的准确工具名及参数，再调用 tools[name](args)。程序返回后，已接纳的监控由扩展负责。禁用扩展会同时移除它的工具和提示词指导。

在 run_code 内，工具返回生产者数据，供筛选和计算。打印工具结果时，输出其 structured_content；没有结构化数据时输出内容，不会替换成直接调用工具时的精简展示。通过首行 // @run_code: 选项中的 max_output_tokens，限制最终交给模型的合并文本。超出预算的输出会保存并返回恢复引用；已完成的观察结果在后续回放中保持不变。

生产者的限制仍然有效：文件和搜索分页、进程读取范围、命令输出传输上限、媒体大小限制，与模型文本预算分开。生产者报告省略数据时，通过返回的续读参数或完整日志引用获取剩余内容。

运行命令

bash 默认使用 action=run，接受 command、timeout_seconds、cwd、run_in_background、completion_mode、purpose 和 scope：

{
  "command": "go test ./internal/process",
  "timeout_seconds": 300,
  "purpose": "Check process lifecycle behavior",
  "scope": "targeted"
}

模型收到的是终端里看到的输出：先 stdout，再 stderr。命令成功时不附加其他内容。只有会影响下一步的信息才会出现：失败时的 Exit code N，某个流被截断时的完整日志路径，超时转后台，沙箱拒绝。每个流保留开头和结尾，测试框架的汇总即使中间被裁掉也能保留。这个视图会去掉终端颜色控制符和进度条重绘。被识别为测试、构建、lint 或类型检查的命令还会记录验证元数据；只有输出被截断时模型才会看到失败摘要，不会在后续请求中另行注入失败摘要，也不会因为工作区版本相同而阻止重试。scope 表示预期的检查范围（targeted、affected 或 full），不会改变命令实际运行哪些测试。purpose 只保存在审计日志里。

客户端和持久记录保留完整的 JSON 信封：退出码、耗时、两段摘录、字节数、分类、工作区版本、完整日志引用和哈希、验证详情。桌面终端面板从这个信封渲染。

命令必须非交互执行，不能依赖编辑器、pager 或终端提示。timeout_seconds 默认为 300，可设置为 1–3600 秒。可转交后台且启用提前转交时，Wuu 会在 10 秒或指定超时到达时结束前台等待，取较短者。同一个进程继续运行，保留输出和所属会话；结果包含进程 ID，完成结果会交付给所属会话。转交后，独立工具可以继续执行；依赖该命令的操作仍需等待它完成。进程 ID 不代表验证成功，也不代表命令已经停止。提前转交时，timed_out 为 false，exit_code 为 -1，promoted_process_id 标识仍待完成的工作。提前转交失败时继续原来的前台等待；到指定超时仍无法转交时，Wuu 才会停止进程。取消当前调用的轮次会停止前台命令，而不是将它转入后台。侧边对话无法从后台完成事件恢复，因此保留指定的前台等待时间。这些等待上限不限制后台进程的运行时长。

后台和交互任务

启动服务、watcher 或交互命令时，设置 run_in_background，不要在命令后添加 &：

{
  "command": "npm run dev",
  "run_in_background": true
}

调用会立即返回进程 ID。后台命令在伪终端中运行，方便桌面接管；macOS 和 Linux 支持 PTY，Windows 回退到管道。进程自然退出后，若所属会话仍在工作，结果会并入下一次模型请求；否则开始续转，wuu exec 会等待这次续转。模型已经读取的结果不会再次交付。成功消费结果的记录随答案持久化，重启恢复时不会重复已确认的结果。长期服务如果不应在退出时唤醒会话、也不应阻止当前任务结束，可在后台启动时或通过 bash action=update 设置 completion_mode=detached。

如果完成通知的续转失败或被中断，通知会保留为待处理状态。模型服务仍按现有的有限次数退避策略重试；到达终态后，不会再自动启动新轮次。重新打开会话或收到其他进程事件也不会重试这条失败通知。用户后续发送消息后才允许恢复。暂停的通知不会让其他已成功完成的工作一直等待自动续转。

bash 也提供后台命令控制操作：

操作	用途
read	通过 process_id 读取输出；把返回的下一个偏移量作为 offset_bytes 可增量读取
write	向仍有有效输入句柄的进程发送 input；需要时附上换行
stop	停止进程树
list	查看当前会话的受管进程
update	修改 completion_mode（resume 或 detached）

读取默认最多返回 32 KiB。省略 wait_ms 时立即返回快照；指定后等待新输出或退出，最长 300,000 毫秒。持续输出会按节奏返回，而不是每收到一个字节就结束等待。控制操作的结果以简短纯文本交给模型，客户端保留 JSON 信封。

命令完成通过事件交付，不再定时唤醒模型复查。持续观察交给 Monitor，其脚本负责查询间隔、过滤、暂时失败的重试和退出条件。stdout 的完整行产生事件；stderr 保留诊断，不会单独唤醒模型。

历史 process 和旧版 bash 记录仍可显示。新调用使用 bash 控制操作，不再注册独立的 process 工具。

目录、环境和权限

cwd 默认为工作区根目录，必须解析到已存在且允许访问的目录。绑定 worktree 的 worker 在分配给它的检出目录中执行。每次 bash 调用都会启动新 shell，cd、alias 和临时环境修改不会跨调用保留。

Wuu 通过 shell 启动器解析 Bash，Windows 使用 Git Bash。前台和后台命令共用环境准备逻辑：移除继承的构建期 GOROOT，设置非交互默认值；PTY 启动时再按需恢复终端相关设置。

命令分类用于权限检查和调度，不等于文件系统沙箱。在受限模式下，前台和后台命令都使用已配置的文件系统进程沙箱。如果没有可执行限制的 provider，启动会失败，不会静默改成不受限执行。内置后端在 macOS 上使用 Seatbelt，在 Linux 上使用 Landlock。Linux 内核必须启用 Landlock ABI 3 或更高版本，且当前进程能够使用；后端不可用时会拒绝执行。网络隔离不在此契约内。模式和平台限制见权限。

写入被拒绝后，不应换一条 shell 命令绕过限制。任务确实需要访问边界外的路径时，应添加已授权的工作区根目录，或显式切换会话模式。Wuu 没有逐条命令弹窗审批。

编辑文件并验证修改

所有内置模型配置统一使用 read_file 读取文件、edit_file 局部修改、write_file 新建或完整重写。切换模型或启动派生会话时，编辑工具保持一致。本地模型原有的命令执行限制继续保留。

读取文件后，向 edit_file 提供从当前内容复制的文本：

{
  "path": "example.txt",
  "old_text": "hello",
  "new_text": "hello world"
}

匹配不到或匹配不唯一时，文件保持不变，工具会返回候选位置供恢复。读取相关范围后，补足精确上下文再重试；只有确定要修改所有匹配项时才使用 replace_all=true。新建文件时，向 write_file 提供 path、content，可用 create_only=true 拒绝覆盖已有文件。超过 32 KiB 的已有文件仍需指定覆盖策略。两种编辑工具都保留路径和权限检查，并发布文件变更及结构化差异。

命令执行可用时，单独调用 bash 验证修改：

{
  "command": "test -f example.txt",
  "timeout_seconds": 30,
  "purpose": "Check the new file exists"
}

命令失败会保留已完成的修改。验证转入后台后，必须等到终态结果才能判断是否通过。重跑验证时，不要重复已经成功的编辑。

Wuu 不再执行内置 apply_patch 及其 dry_run、then_run 选项。恢复会话时，历史补丁记录仍可读取和展示，后续编辑使用上述工具。外部 Codex 引擎管理的工具保持不变。

启用 Code Mode 后，read_file、write_file、edit_file、bash 和 process 仍可直接调用。run_code 用于组合调用和计算，基础操作无需 JavaScript 包装。显式补读会返回请求的内容。嵌套结果保留完整数据，只有最终输出受预算限制，超出内容归档供补读，不改写历史消息。

日志与存续时间

普通命令输出和保存的完整工具日志会先脱敏，再返回或持久化。后台进程记录以及合并的 stdout/stderr 日志在磁盘上可能包含原始文本，工具返回时才脱敏。不要把密钥放入参数或输出，分享日志前应自行检查。

运行中的后台日志可能持续增长。结束后的日志会压缩为最多 8 MiB 的尾部；启动维护会清理已结束超过 30 天且没有待交付完成通知的记录和日志。因此，之前的字节偏移可能早于当前保留的输出，应使用结果返回的偏移，不要假设完整日志始终可读。前台命令执行期间也会把输出缓存在内存中，异常高输出可能占用大量内存。

默认的 lifecycle=session 会参与运行时清理，managed 会跳过这类清理。两者都不是操作系统服务管理器。Wuu 重启后无法恢复丢失的 PTY 或 stdin 句柄，重新发现的进程也可能没有可靠退出码。不再需要进程时应显式停止，不要依赖会话标签页的存续时间。停止前，Wuu 会检查进程身份，避免误操作已被复用的 PID，然后先请求温和退出，必要时再终止进程树。

桌面进程控件和模型工具使用同一个管理器。app-server 的进程方法会检查 thread 归属；客户端不能仅凭猜到进程 ID 就操作其他 thread 的进程。接入说明见 app-server 协议。