@zhushanwen/pi-subagent-workflow9.7.0

Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.

zhushanwen321 Published 23 hours ago MIT ~3.3K downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Reports 0

No reports yet.

Readme

@zhushanwen/pi-subagent-workflow

Pi 的 subagent + workflow 合并包：任务委派 + 多 agent 编排（chain / parallel / scatter-gather / map-reduce），单包统一执行链 + 分层配额（ADR-030）。

工具范围（7 tools）

工具	action 集合	关键参数
`subagent_start`	—（单动作）	`task` + `slug`（≤35 字符）必填，`agent`（.md 绝对路径，缺省 general-purpose）、`model`、`engine`、`fork`、`worktree`、`maxTurns`、`idleTimeoutMs` 等 start 场景可选字段
`subagent_manage`	`list` / `cancel` / `close`（3 个）	`cancel` / `close`：`subagentId` 必填
`subagent_message`	`message` / `fork-from`（2 个）	`message`：`subagentId` + `text` 必填；`fork-from`：`sourceSubagentId` 必填
`subagents`	—（单动作，批量派发，deferred 延迟加载）	`tasks` 必填（每元素一个自包含任务 prompt，全部并行、结果一条通知收尾），可选 `agents`（逗号分隔 .md 绝对路径，单值或与 tasks 一一对应）、`aggregate`、`slug`、`model` 等；run 级状态控制走 `workflow_control`
`workflow_run`	—（单动作）	`name`（`.js` 绝对路径）+ 可选 `args` / 预算，见「Workflow 生命周期」节
`workflow_control`	`status` / `abort` / `resume`（3 个）	`abort` / `resume`：`runId` 必填，见「Workflow 生命周期」节
`workflow-script`	`generate` / `lint` / `save` / `delete` / `list`（5 个）	`generate`：`script` + `name`（可选 `description`）；`save`：`name`（可 `newName` 改名）；`lint` / `delete`：`name`

工具激活（deferred）

subagents / workflow-script 两工具注册为 exposure: "deferred"——不占常驻工具声明，由 pi 内置 tool_search 工具检索命中后按需激活。taiji 宿主内开箱即用（宿主启动时已激活 tool_search）；独立 pi 使用需在 <agentDir>/settings.json（默认 ~/.pi/agent/settings.json）开启：

{ "defaultTools": ["+tool_search"] }

+ 前缀是增量修饰（保留 read/bash/edit/write 默认集）。未开启 tool_search 时这两个工具对模型不可见。

内置 Agents

按「读/写 × 视角」正交切分，10 个角色零重叠（C1 起随 @zhushanwen/subagent-core 的 agents/ 资产分发，<available_subagents> 的 <location> 指向 core 包 agents/ 内各 agent .md 的绝对路径）：

Agent	角色	读/写
`explorer`	代码库侦查：找入口 / 追调用链 / 摸结构	只读
`planner`	复杂任务拆解为有序实施计划（合并需求澄清）	只读产文档
`coder`	代码实现、修改、测试（唯一改代码的角色）	可改
`reviewer`	代码审查与需求验收（含 git diff）	只读
`doc-reviewer`	文档审查（四遍方法论，事实锚点核实；spec / 设计文档）	只读
`debugger`	运行时故障诊断，钉根因	只读*
`analyst`	深度项目分析，产出给人读的报告	只读
`researcher`	外部资料调研（依赖 tavily skill）	只读
`orchestrator`	纯协调器：拆解 + 委派，不直接执行	只协调
`general-purpose`	兜底，无角色假设	按需

* debugger 可加临时诊断日志，但必须诊断后恢复，不改业务代码（修复归 coder）。

日常调用链路：

陌生代码改动：  explorer → (planner) → coder → reviewer
修 bug：       debugger 定位 → coder 修复+补测试 → reviewer 验收
新功能开发：    planner → [coder 并行多包] → reviewer 验收
深度调研：      analyst (项目) / researcher (网页)

Orchestrator 协调器模式

orchestrator 是纯协调器角色：拆解任务 → 委派 subagent → 汇总结果，自身不做执行类工作。orchestrator agent 自身也可递归委派子 orchestrator，实现分层任务拆解（深度受 Depth: N/10 护栏保护）。

工具约束（C1/D-5）：内置模板不携带 tools: frontmatter 白名单，subagent 不以 --tools 白名单启动——工具约束回归宿主默认工具范围，orchestrator 靠角色职责（职责边界段）约束自身只做协调。想要白名单的用户在 <workspace>/.agents/agents/ 放同名 .md 覆写（发现优先级 project 级最高，稳定遮蔽内置），或临时用 pi CLI 的 --tools 白名单验证：

pi --tools todo,goal_control,workflow_run,subagent_start,ask_user

依赖：需先安装本包及相关扩展
pi install npm:@zhushanwen/pi-subagent-workflow
pi install npm:@zhushanwen/pi-todo
pi install npm:@zhushanwen/pi-goal
--tools 白名单按 tool 注册名匹配。注意 goal 扩展注册的 tool 名是 goal_control（非 goal）。

递归深度

系统内置 n = 10 深度护栏（MAX_FORK_DEPTH，fork 链与通用嵌套两个计数器共享上限、取严者生效）：fork 链超限抛 ForkDepthExceededError，通用嵌套护栏报 nested_spawn_rejected。实测建议控制在 3-4 层以内——更深层会因上下文逐层压缩导致信息失真。

Workflow 生命周期

Workflow run 有两类结束形态：终局（done，outcome 区分 done / failed / cancelled / time_limited——成败已定）与中断（interrupted 暂停态——执行被打断但可续跑）。workflow_run 启动 run；workflow_control 共 3 个 action：status / abort / resume。run 的 name 仅接受 .js 绝对路径（通常是 <available_workflows> 条目的 <location>；任意声明 @pi-meta kind:"workflow" 的绝对 .js 路径均可），裸名 / 相对路径拒绝（not_found，拒单文案列全部可用条目及 location，按 location 重试即可）。

abort（主动取消）：{"action":"abort","runId":"<id>"}（可选 "error":"<reason>"）→ cancelled 终局。要新结果就重新 run
resume（断点续跑）：{"action":"resume","runId":"<id>"}（可选 args 校验一致性与时间预算）——对 interrupted run 从断点恢复：已完成的调用回放缓存零 token、未完成的按三档恢复（会话完整 → 捞回结果；请求未完成 → 同会话续写；会话不在 → 整跑）；/workflows resume <id> 同能力
session 切换/关闭时，所有 running run 转 interrupted 暂停态（被打断不记失败）——回原 session 可 resume 续跑
持久化 = record 事件流（<runId>.record.jsonl，append-only 单一事实源）：状态由事件流折叠得出；旧 wf-run-v1/wf-run-v2 快照文件为历史遗留，读侧不消费
worker 崩溃自动重建重试（默认 3 次）：重建时在途 agent 调用被清除重跑，已完成的调用保留 replay 缓存，不重复消耗 token

性能：sessions-index.json 持久化索引

冷启动首扫的 identity 探测结论持久化为 <enc>/sessions-index.json（<enc> = agentDir 下 subagents/ 内按 cwd 编码的目录段，索引落 sessions 目录同级；stat 戳自校验、tmp(pid+seq)+rename 原子写、60s 节流、损坏/版本不符静默回退全量探测），真实目录（1744 jsonl / 671MB）实测冷扫描中位数 972.8ms → 80.6ms（12.1x，预算 ≤300ms）。可复现验收脚本：bench/cold-scan.bench.ts（冷扫描计时 + 输出等价断言）、bench/concurrent-scan.bench.ts（3 实例并发 + 随机变异四判定）。

安装

pi install npm:@zhushanwen/pi-subagent-workflow

License

MIT