只读子智能体与本机协调
使用 wenext_agent 委派独立研究或审查。子会话使用受限读取工具,运行服务管理队列、取消和恢复;研究结果不能代替父任务的批准或检查。
适用范围
Wenext-Pi 通过 Pi 1.1.0 的真实 createAgentSession 创建独立研究/审查会话。运行服务负责身份、队列、结果、取消及恢复;默认工作流决定是否委派,父智能体判断研究结果。适用于任意技术栈,不要求业务仓库添加脚本。
当前提供只读子智能体。源码写入 worker、worktree、自动合并、嵌套委派和独立客户端稳定 SDK 尚未交付。子会话位于当前 Node 进程,具有独立 cwd、SessionManager 和工具集,不是独立进程或操作系统沙箱。
工具与接口
父智能体使用 wenext_agent 工具(不是斜杠命令):
| action | 参数 | 结果 |
|---|---|---|
| create | 可选 cwd,相对项目根 | 智能体身份;固定 read_only、depth=1,继承创建时的模型 |
| send | agentId、message | 新 Run 身份,初始 queued;同一智能体不能同时有两个活动 Run |
| wait | runId,可选 timeoutMs=0–30000,默认 1000 | 终态或等待结束时的当前状态;等待超时不取消运行 |
| result | runId | 状态、原因、最多 16000 字符结果 |
| list | 无 | 当前父会话/任务最近 100 次尝试,不含结果正文;按需调用 result |
| cancel | runId | 取消排队项,或中止并等待本宿主的活动子会话清理 |
运行服务位于 runtime/agents/service.ts,不依赖 Pi;SDK 会话与只读工具在 adapters/pi/child-session.ts,宿主工具接入在 adapters/pi/parallel.ts。这些是单 npm 包内部模块。
任务转换使用内部接口 AgentRunService.quiesceTask(parentSessionId, taskId | undefined, reason): Promise<() => void>。reason 为 task_switched 或 task_finished;成功返回释放函数,调用者在提交或放弃转换后必须释放。taskId 未提供时只暂停该父会话的委派入口,不取消任何任务。Pi 适配器 prepareTransition(ctx, reason, nextTaskId?, signal?) 返回 { commit, release },commit(action) 仅接受同步的状态变更。
行为约定
身份、权限与资源
- 智能体保存 id、parentSessionId、taskId、显式规范化 cwd、provider/model、depth、profile 和可续接 sessionFile。Run 保存独立 id、agentId、任务/父会话、owner 的 PID/主机/token、状态/时间、实际 child sessionId 和结果。parentRunId 为后续运行树预留,当前根宿主通过 parentSessionId 关联,不编造父 Run。
- 工具要求当前任务已经
wenext_start,研究可发生在 plan 阶段;不需要源码写入批准。每个动作重新核对父会话/任务。不同会话不能接管对方正在运行的智能体。 - 子级只注册
wenext_read、wenext_list、wenext_search、wenext_read_input:限定在显式 cwd 内,规范化路径拒绝越界及状态目录;read 为普通文件分块读取(24 KiB),list 每页 200 项,可传 offset 并跟随 nextOffset,search 为有界字面量搜索(1000 项、200 ms、30 条)。incomplete 搜索提示限定相关 path 再查,空结果不能证明不存在。遍历中跳过保护目录不算主动越权;显式访问仍拒绝。不调用 shell 或外部搜索进程。 - 子级不加载项目/用户 Pi 扩展、MCP、codemode、技能、提示模板、AGENTS 或业务工作流;父级需在委派消息中提供相关需求。Pi 原扩展在主会话的使用方式保留。无写入、审批、父任务修改或再次委派工具,无法通过模型请求自行增加能力。
- 使用父宿主公共 ModelRegistry 的配置与请求时认证/传输,支持沿用账号登录。凭据不进入智能体/Run/请求记录。已创建智能体的模型不会随父级之后选模型而改变。暂不支持
pi-virtual模型。 - 每项目默认最多 2 个运行项,最多 16 个活动/排队项;每父会话/任务最多 8 个智能体,复用已有智能体继续对话。内部服务可设置 1–4 并发,持久化 policy 要求同项目各宿主使用相同上限;CLI 未提供并发上限配置入口。
- 单次消息/结果最多 16000 字符;不按模型回合或工具调用次数终止。普通文件读取/参数错误可在当前会话纠正,越权工具和路径仍使运行失败。已取消信号在模型请求入口再次检查。默认 120 秒发出取消信号,关闭自动重试、自动压缩和 cache warming。取消依赖 SDK/provider 遵守 AbortSignal,不保证能强杀忽略信号的第三方传输。
冻结输入与独立审查
createPiChildFactory 增加可选 inputs: Record<string, {file, sha256}>、freshContext、requireAllInputs。输入最多 4 项,每项为已规范化普通文件(最多 1 MiB);构建工具时核验原始文件 SHA-256 后冻结在内存。wenext_read_input({name, offset?}) 每次最多 24 KiB,返回 text/nextOffset/truncated,按 UTF-8 边界切分;只授权命名输入,不开放其目录。无输入的普通研究智能体不获得额外文件访问权。
freshContext=true 每次创建新会话;requireAllInputs=true 需要所有输入字节区间完整交付,否则 Run 失败。Pi 方案审查使用这两个选项,并沿用现有限流/取消/用量采集;普通研究智能体默认仍可续接。审查专用 input 进一步受本地状态 128 KiB 上限限制。具体批准规则见 方案审查契约。
持久化、恢复与清理
<project-state>/runtime/agents/ # 旧本地 layout 为 .runtime/agents
policy.json
agents/<agent-id>/agent.json
runs/<run-id>.json
requests/<run-id>.json # 本地委派消息,不上传,不自动重放任务子会话 JSONL 位于 <task>/agents/<agent-id>/sessions/;旧共享布局的会话可能仍在 runtime/agents 下,恢复时按任务归属处理。
状态迁移为 queued → running → succeeded/failed/cancelled;宿主崩溃留下的 queued/running,在重启核实本机 PID 已退出后标记 interrupted。未知/其他主机的持有者保持占用;PID 被复用时保守判定为存活。损坏的运行记录拒绝继续调度,不静默释放未知槽位。
恢复只读取状态,不根据旧请求启动模型。相同父会话和任务下,显式 send 可以打开已有子会话文件,创建新 Run;其他父会话应创建自己的智能体。未完成 JSONL 可供后续模型看到,但旧工具调用不会由恢复逻辑直接重放。
父回合 AbortSignal、取消后的 agent_settled、会话切换/分叉/树切换和宿主退出都会清理本宿主所属子任务。单个 cancel 不取消兄弟;等待结束不销毁智能体,下次 send 复用其会话。能力越权、模型失败、清理失败均不能写成 succeeded;普通只读工具错误允许纠正后继续。结果和事件不会批准或完成父任务。
同一个 Pi session 内,wenext_create(child/unrelated)、wenext_continue、/wenext-task 切换任务,以及 wenext_finish 完成任务,也会自动收束旧任务的 Run:
- 先校验创建参数/关系/已存在目录、继续目标或完成前置条件。无效请求不取消研究;继续当前任务(含 id/目录别名)不取消研究。手动绑定也验证真实任务,不再写入不存在的任务指针。
- 获取父会话转换租约,暂停该父会话的 create/send 和排队启动。按父会话 + 旧 taskId 选择活动 Run;其它父会话和其它任务不会被取消,终态结果保留。
- 排队项直接 cancelled,运行项发送 AbortSignal,并等待所有子会话 dispose 和终态持久化。取消原因分别为 task_switched/task_finished。完成任务在质量检查前收束,并持有租约直到完成流程结束。
- 在 pointer 同步锁内核对调用未取消、仍为同一 Pi session、完整原指针未变,再执行绑定/最终完成。等待期间状态变化则拒绝覆盖;所有成功/失败路径释放租约。
清理失败不能被取消原因覆盖为成功清理。终态未能落盘、其它存活宿主持有 Run、未知持有者或资源清理失败时,转换失败,原绑定保留(除非已被外部操作修改)。已取消的子 Run 不会因后续转换/质量检查失败而自动重启。cleanup_error 所属宿主仍存活时,重试转换也会阻止;停止该宿主以释放其资源后再恢复。不同宿主通过同一本机租约协调,不远程强杀对方会话。
需要研究结论时仍应先 wait/result;自动取消用于释放未完成工作,不会生成缺失的研究结论。工具仍按当前活动任务隔离;切回原未完成任务可查询旧 Run,完成后历史文件保留在原 agents 状态目录,不新增跨任务读取工具。
终态保存遇到锁竞争最多重试 5 秒;持续写盘失败不声称持久化成功,运行记录保留占用,退出后恢复为 interrupted。状态文件和会话暂不自动 GC;消息和结果留在本机状态目录。
本机跨进程协调
runtime/state-lock.ts 先完整写入 owner,再通过硬链接原子取得锁;同一同步调用栈允许重入,不跨 await 重入。存活 PID 的锁不会因经过某个时长而被偷取。已退出 owner 的锁通过单独恢复锁协调回收;未知 owner 拒绝抢占。锁冲突使用 WENEXT_STATE_CONFLICT,同步操作由调用方重试。
覆盖任务元数据读改写、会话指针 revision、memory 的 expectedVersion 检查与写入、项目智能体队列/槽位,以及跨 await 的完成租约。完成流程的最终绑定检查、任务归档及指针删除在同一同步锁范围内。各文件仍通过原子替换持久化;这不是多文件崩溃事务或多主机共享存储协议。
父会话转换租约与同步 pointer/task 锁分开;等待子会话释放时不占用同步状态锁。工具/手动入口负责异步收束,底层同步 createBoundTask/continueBoundTask/finishBoundTask 不自行调度子智能体;其它嵌入宿主若持有 Run,也需遵守先 quiesce、再受控提交、最后 release 的内部协议。直接写文件或绕过宿主协议的调用不在自动收束保证内。
runPi 拒绝同进程重入并在退出时还原 cwd。子级只使用显式 cwd 的 SDK 会话,不并发执行 piMain 或 process.chdir。
结果与错误处理
| 场景 | 预期 |
|---|---|
| 两个 cwd 并发读取不同文件 | 结果与 sessionId 独立,宿主 cwd 不变 |
| 第三个 Run / 两个独立宿主 | 按项目上限排队,活动计数不超过 policy |
| 父级切换模型后 send | 子级保留创建时的模型,通过原 registry 请求 |
| 写入/审批/委派工具调用 | 未注册,失败;即使模型后来声称成功仍为 failed |
| symlink 越界 / 读取运行状态 | 拒绝 |
| 未纠正的工具错误 / provider error / 能力越权 | failed,不改变父任务 |
| 父取消 / 切换 / 退出 / 120 秒超时 | AbortSignal 到达子会话,等待释放后终结 |
| 排队项取消遇到锁竞争 | 有限重试,不丢掉取消请求 |
| SIGKILL 宿主 / 持锁进程 | 重启标记 interrupted / 回收死锁;不重放 |
| 两进程追加 children / 更新同一指针 | 不丢追加项,revision 单调增长 |
| 两进程按同一 memory version 更新 | 只允许一个成功,另一个明确冲突 |
| 外部进程切换完成中的父会话绑定 | 明确锁冲突,不能被完成流程误清理 |
| create child/unrelated、continue、手动绑定、finish | 运行与排队 Run 均收束后才转换;完成前先收束再检查 |
| 继续当前任务、无效/重复创建、目标不存在、预取消 | 保留当前研究;无错误绑定 |
| 收束过程中 create/send、另一个宿主请求委派 | 租约冲突;其它父会话仍可运行 |
| dispose 失败或终态未落盘 | 拒绝转换;不把取消当作已清理 |
| 等待期间调用取消或原指针变化 | 拒绝状态提交;释放租约;不重放已取消 Run |
| 收束后质量门禁失败 | 父任务保持未完成;释放委派入口,可显式再次 send |
观测边界
事件 child_run_state 保留智能体、Run、任务和父子会话的关联、状态及有限原因码。用量只保留模型服务提供方实际提供的观测,不把估算变成真实用量;遥测不含消息、结果正文、代码和凭据。