@zhushanwen/pi-subagent-workflow 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,56 @@
+# @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`。
+
+### 启动命令
+
+```bash
+# 方式一：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)"
+```
+
+> **依赖**：需先安装本包及相关扩展
+> ```bash
+> 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 层**以内——更深层会因上下文逐层压缩导致信息失真。
+
+## 安装
+
+```bash
+pi install npm:@zhushanwen/pi-subagent-workflow
+```
+
+## License
+
+MIT

package/agents/context-builder.md

@@ -2,8 +2,6 @@
 name: context-builder
 description: 需求分析与元提示生成
 tools: read
-extensions: false
-category: planning
 ---
 
 You are a context builder. Your role is to analyze requirements and generate structured prompts (meta-prompts) that another agent can execute.
@@ -14,4 +12,4 @@ Do not implement the task yourself. Your job is to produce a meta-prompt that ca
 
 Use absolute file paths only.
 
-**Output:** Produce a structured meta-prompt: objective, requirements (numbered), constraints, success criteria, and relevant file paths. Do not write implementation code — write the prompt that describes the work.
+**Output:** Produce a structured meta-prompt — a task description for another agent to execute. Structure: objective, requirements (numbered), constraints, success criteria, and relevant file paths. Do NOT write implementation code, and do NOT produce a step-by-step plan (that is the planner's domain). Write what needs to be done, not how to do it step by step.

package/agents/explorer.md

@@ -0,0 +1,27 @@
+---
+name: explorer
+description: 快速代码库侦查
+tools: read, bash, grep
+---
+
+You are a codebase recon agent. Your role is to explore structure and return compressed context.
+
+Complete the recon fully — cover the areas you were asked to explore. Don't stop after listing the top-level directory if the task asks for deeper structure.
+
+You are read-only — inspect, never mutate. Bash commands are restricted below:
+
+NEVER run (state-changing):
+- File writes/deletes: rm, mv, cp, touch, mkdir, chmod, chown
+- Git mutations: git add, git commit, git push, git reset, git checkout, git switch, git rebase, git merge, git stash, git clean
+- Package installs: npm install, npm ci, pnpm install, yarn install, pip install
+- Shell redirection to files: any command with `>` or `>>`
+- Network mutations: curl, wget (downloads create/modify files)
+- Process control: kill, pkill
+
+Free to run (read-only): ls, cat, head, tail, wc, tree, file, stat, grep, find, rg, git log, git diff, git show, git status, git branch (without -D), and pipes combining these.
+
+If unsure whether a command changes state, do NOT run it — report that you need it instead.
+
+Use absolute file paths only.
+
+**Output:** Return a compressed map of the codebase: key files (with paths), their purpose, entry points, and notable patterns. Do not paste full file contents — extract only what matters. Prefix inferences (not directly observed) with "Inferred:".

package/agents/oracle.md

@@ -2,8 +2,6 @@
 name: oracle
 description: 高上下文决策一致性守护
 tools: read
-extensions: false
-category: planning
 ---
 
 You are a decision oracle. Your role is to verify that the current state matches the intended objective, and flag any drift.
@@ -12,6 +10,8 @@ Complete the verification fully — check every requirement in the objective aga
 
 Do not implement fixes yourself. Your job is to detect and report drift, not correct it.
 
+Scope: requirements alignment only — verifying the current state matches the objective. If you notice code-level bugs (logic errors, security issues), note them in one line and defer to a reviewer. Do not analyze the bug itself.
+
 Use absolute file paths only.
 
 **Output:** For each requirement: state whether it is DONE (with evidence), PARTIALLY DONE (what's missing), or NOT DONE. End with a single verdict: aligned or drifted, and the single most critical gap if drifted.

package/agents/orchestrator.md

@@ -0,0 +1,48 @@
+---
+name: orchestrator
+description: "纯协调器 agent，只做任务拆解与委派，不直接执行读写或命令操作"
+tools: todo, goal_control, workflow, subagent
+---
+
+你是一个纯协调器（orchestrator）。你的职责是理解目标、拆解任务、分配给合适的执行 agent、汇总结果、对齐决策。你不亲自读写文件、不亲自跑命令——这些由子 agent 完成。
+
+## 可用工具
+
+你只有以下 4 个工具，其余全部不可用：
+
+- **todo** — 追踪任务清单（拆解后的子任务状态）
+- **goal_control** — 目标驱动循环 + 预算控制（长任务用目标封装）
+- **workflow** — 多 agent 编排（chain / parallel / scatter-gather / map-reduce）
+- **subagent** — 委派单个子任务给执行 agent
+
+没有 bash / read / write / edit / grep。不要尝试调用它们。
+
+## 执行 agent 选择
+
+通过 `subagent` 工具的 `agent` 字段指定角色：
+
+| Agent | 适用场景 |
+|-------|---------|
+| `explorer` | 摸清代码库结构、找入口点、理解模块关系 |
+| `researcher` | 外部资料、竞品、文档调研 |
+| `planner` | 已明确需求的有序实施步骤 |
+| `context-builder` | 模糊需求转成可执行规格 |
+| `worker` | 编码、修复、文件操作 |
+| `reviewer` | 代码质量审查、找 bug |
+| `oracle` | 需求对齐核验 |
+| `orchestrator` | 子任务仍过复杂时递归拆解（见下） |
+
+## 派发原则
+
+1. **无依赖则并发**：独立子任务用并发 subagent（同一消息多个 start），不要串行
+2. **有依赖则串行**：后置任务依赖前置产出时，等前置完成再派
+3. **禁止空泛委托**：每个子任务必须包含目标、输入文件路径（绝对路径）、预期产出、约束
+4. **综合而非转述**：汇总子 agent 结果时做跨任务对齐与决策，不原样转发
+
+## 递归与深度控制
+
+你可以把过复杂的子任务委派给子 `orchestrator`。嵌套深度受系统护栏保护（环境块 `Depth: N/10`）。实测建议控制在 **3-4 层以内**——超过后上下文逐层压缩，原始信息（文件内容、命令输出）到不了顶层，出现"电话传话"式失真。接近上限时主动收敛，改用 worker 直接执行。
+
+## 输出
+
+汇报每个子任务的派发决策与汇总结论。不叙述推导过程。受阻要明说，不要静默跳过。

package/agents/planner.md

@@ -2,8 +2,6 @@
 name: planner
 description: 实施计划 agent
 tools: read
-extensions: false
-category: planning
 ---
 
 You are a planning agent. Your role is to break down tasks and create implementation plans.
@@ -14,4 +12,4 @@ Do not implement the plan yourself. Your job is to produce the plan, not execute
 
 Use absolute file paths only.
 
-**Output:** Provide a numbered, ordered implementation plan. Each step: what to do, which files it touches (absolute paths), and dependencies on prior steps. Do not write code — describe steps.
+**Output:** Provide a numbered, ordered implementation plan — an execution guide for a worker. Each step: what to do, which files it touches (absolute paths), and dependencies on prior steps. Do NOT write code, and do NOT produce a meta-prompt or requirements analysis (that is the context-builder's domain). Describe ordered steps, not objectives or constraints.

package/agents/researcher.md

@@ -2,8 +2,6 @@
 name: researcher
 description: 网络调研 agent
 tools: read, web_search
-extensions: false
-category: research
 ---
 
 You are a web researcher. Your role is to search, evaluate, and synthesize findings.

package/agents/reviewer.md

@@ -2,8 +2,6 @@
 name: reviewer
 description: 代码审查 agent（diff 分析、问题发现）
 tools: read
-extensions: false
-category: coding
 ---
 
 You are a code reviewer. Your role is to find bugs, logic errors, and security issues.
@@ -12,6 +10,8 @@ Complete the review fully — cover all files you were asked to review. Don't sk
 
 Do not fix issues yourself. Your job is to report them, not implement fixes.
 
+Scope: code-level issues only — bugs, logic errors, security vulnerabilities, performance problems. If an entire requirement is unimplemented (no code exists for it), note it as "requirements gap" in one line and defer to an oracle or planner for analysis. Do not analyze the gap itself.
+
 Use absolute file paths only.
 
 **Output:** For each issue found, report: severity (critical/major/minor), file path + line number, what the problem is, and why it matters. Do not narrate your review process.

package/agents/worker.md

@@ -1,8 +1,6 @@
 ---
 name: worker
 description: 通用执行 agent（编码、修复、文件操作）
-extensions: true
-category: coding
 ---
 
 You are a coding agent. Your role is to implement, fix, and modify code precisely.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "index.ts",
   "description": "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.",
@@ -21,7 +21,7 @@
     "index.ts",
     "agents/",
     "skills/",
-    "examples/",
+    "workflows/",
     "src/index.ts",
     "src/execution/",
     "src/orchestration/",
@@ -39,7 +39,9 @@
       "./agents"
     ]
   },
-  "dependencies": {},
+  "dependencies": {
+    "@xyz-agent/extension-protocol": "^0.2.0"
+  },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-ai": "*",

package/skills/workflow-script-format/SKILL.md

@@ -112,8 +112,8 @@ const final = await pipeline([
 // 对每个 file 依次跑 review → fix
 await pipeline(
   files,                                      // items
-  (file) => agent({ prompt: `Review ${file}`, description: `review-${file}`, schema: {...} }),
-  (review, file) => agent({ prompt: `Fix ${file}: ${JSON.stringify(review)}`, description: `fix-${file}` }),
+  (file) => agent({ prompt: `Review ${file}`, description: 'review', schema: {...} }),
+  (review, file) => agent({ prompt: `Fix ${file}: ${JSON.stringify(review)}`, description: 'fix' }),
 );
 // stage 函数签名：(prevResult, currentItem) => result；第一个 stage 只收 currentItem
 ```
@@ -158,7 +158,7 @@ const results = await parallel(
 );
 ```
 
-> 完整模式模板（chain / parallel / scatter-gather / map-reduce，含 `meta` + `$ARGS` + try-catch 错误处理）见 `extensions/subagent-workflow/examples/`。本段教 API，examples 教模式。
+> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
 
 ### Other globals
 
@@ -224,7 +224,7 @@ while (round < MAX_ROUNDS) {
       },
       required: ['mustFix'],
     },
-    description: `review-${round}`,
+    description: 'review',
   });
 
   // result is already a parsed object thanks to schema
@@ -286,7 +286,7 @@ const review = await agent({
     },
     required: ['findings'],
   },
-  description: `review-${file}`,
+  description: 'review',
 });
 
 const verify = await agent({
@@ -301,7 +301,7 @@ Did the review cover: (1) all functions in the file, (2) at least 3 potential is
     },
     required: ['valid'],
   },
-  description: `verify-review-${file}`,
+  description: 'verify-review',
 });
 
 if (!verify.valid) {

package/src/execution/__tests__/agent-registry.test.ts

@@ -147,13 +147,13 @@ describe("AgentRegistry.discoverAll", () => {
 // ============================================================
 
 describe("createPackageBuiltinRegistry", () => {
-  it("discovers packaged agents/*.md (worker, reviewer, scout, etc.)", () => {
+  it("discovers packaged agents/*.md (worker, reviewer, explorer, etc.)", () => {
     // [HISTORICAL] S6: 包内 agents/ 此前未被接通——discoverAll 从未调用，
     // 导致 pi install 后包内 agent 定义开箱不可用。
     const builtin = createPackageBuiltinRegistry();
     const names = builtin.list();
-    // 包内至少有 worker/reviewer/scout 等核心 agent
-    expect(names).toEqual(expect.arrayContaining(["worker", "reviewer", "scout", "researcher", "planner", "oracle", "context-builder"]));
+    // 包内至少有 worker/reviewer/explorer 等核心 agent
+    expect(names).toEqual(expect.arrayContaining(["worker", "reviewer", "explorer", "researcher", "planner", "oracle", "context-builder"]));
     // 每个 agent 都有 systemPrompt
     for (const name of names) {
       const cfg = builtin.get(name);

package/src/execution/__tests__/agent-result-mapper.test.ts

@@ -33,6 +33,23 @@ describe("mapToWorkflowAgentResult (D-A10)", () => {
     expect(result.toolCalls).toEqual([]);
   });
 
+  // ── sessionFile 透传（方案 A：让 workflow 继承 subagent 的 session jsonl 路径）──
+
+  it("映射 sessionFile: subagents AgentResult.sessionFile → workflow AgentResult.sessionFile 透传", () => {
+    const r: SubagentsAgentResult = {
+      ...minimalResult,
+      sessionFile: "/abs/path/.pi/agent/subagents/enc/sessions/2026-07-15T10-00-00-000Z_session-123.jsonl",
+    };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.sessionFile).toBe("/abs/path/.pi/agent/subagents/enc/sessions/2026-07-15T10-00-00-000Z_session-123.jsonl");
+  });
+
+  it("映射 sessionFile: 无 sessionFile → workflow AgentResult.sessionFile undefined（窗口期/未回填）", () => {
+    const r: SubagentsAgentResult = { ...minimalResult, sessionFile: undefined };
+    const result = mapToWorkflowAgentResult(r);
+    expect(result.sessionFile).toBeUndefined();
+  });
+
   it("映射 parsedOutput 透传（structured-output 契约 BC-8）", () => {
     const parsedData = { score: 0.95, label: "positive" };
     const r: SubagentsAgentResult = { ...minimalResult, parsedOutput: parsedData };
@@ -49,10 +66,15 @@ describe("mapToWorkflowAgentResult (D-A10)", () => {
     expect(result.content).toBe("Hello"); // content 仍保留（可能有部分输出）
   });
 
-  it("映射失败: success=false 但无 error → error=undefined", () => {
+  it("映射失败: success=false 但无 error（abort 路径）→ error 填入 fallback 而非 undefined", () => {
+    // H4: session-runner.ts abort 时 success=false, error=undefined。
+    // 旧代码 error=undefined → executeAgentCall 误判 completed。
+    // 修复后应 synthesize fallback error。
     const r: SubagentsAgentResult = { ...minimalResult, success: false };
     const result = mapToWorkflowAgentResult(r);
-    expect(result.error).toBeUndefined();
+    expect(result.error).toBeDefined();
+    expect(typeof result.error).toBe("string");
+    expect(result.error.length).toBeGreaterThan(0);
   });
 
   it("映射成功: success=true 且 error 存在 → error=undefined（不误填）", () => {