@zhushanwen/pi-subagent-workflow

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.

Packages

Package details

extensionskill

Install @zhushanwen/pi-subagent-workflow from npm and Pi will load the resources declared by the package manifest.

npm report

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

Package: @zhushanwen/pi-subagent-workflow
Version: 0.3.2
Published: Jul 24, 2026
Downloads: 439/mo · 336/wk
Author: zhushanwen321
License: MIT
Types: extension, skill
Size: 1.6 MB
Dependencies: 1 dependency · 5 peers

Pi manifest JSON

{
  "extensions": [
    "./index.ts"
  ],
  "skills": [
    "./skills"
  ],
  "agents": [
    "./agents"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@zhushanwen/pi-subagent-workflow

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

内置 Agents

Agent	角色	是否执行
`context-builder`	模糊需求 → 可执行规格（meta-prompt）	只写 what
`planner`	已明确需求 → 有序实施步骤	只写 how
`explorer`	代码库结构摸底（只读）	不改文件
`researcher`	外部资料 / 竞品 / 文档调研	不改文件
`worker`	编码 / 修复 / 文件操作	可改文件
`reviewer`	代码质量审查、找 bug	只读
`oracle`	需求对齐核验	只读
`orchestrator`	纯协调器：拆解 + 委派，不直接执行	只协调
`general-purpose`	兜底，无角色假设	按需

Orchestrator 协调器模式

主 agent 禁用 bash / read / write / edit 等执行工具，只保留协调类工具，被迫作为纯协调器：拆解任务 → 委派 subagent → 汇总结果。orchestrator agent 自身也可递归委派子 orchestrator，实现分层任务拆解（深度受 Depth: N/10 护栏保护）。

可用工具仅 4 个：todo、goal_control、workflow、subagent。

启动命令

# 方式一：CLI 工具白名单（临时验证最快）
pi --tools todo,goal_control,workflow,subagent

# 方式二：白名单 + 注入 orchestrator 的 system prompt（推荐，主进程也具备协调器视角）
pi --tools todo,goal_control,workflow,subagent \
   --append-system-prompt "$(cat ~/.pi/agent/npm/node_modules/@zhushanwen/pi-subagent-workflow/agents/orchestrator.md)"

依赖：需先安装本包及相关扩展
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 深度护栏（fork 链 + 嵌套取 max），超过抛 ForkDepthExceededError。实测建议控制在 3-4 层以内——更深层会因上下文逐层压缩导致信息失真。

安装

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

License

MIT