@zhushanwen/pi-subagent-workflow 0.1.0 → 0.2.0

package/examples/README.md

@@ -1,43 +0,0 @@
-# Workflow Examples
-
-4 个预制编排模板，展示 `workflow()` 嵌套调用 + `parallel()`/`pipeline()` 组合模式。
-
-## 文件清单
-
-| 模板 | 模式 | 说明 |
-|------|------|------|
-| `chain.example.js` | 顺序编排（UC-1） | `workflow("extract") → workflow("transform") → workflow("load") → agent(verify)`，每步输出作下步输入 |
-| `parallel.example.js` | 并行扇出（UC-2） | `parallel()` 同时跑多个独立 `agent()`，适合无依赖任务并发 |
-| `scatter-gather.example.js` | 分散-聚合（UC-3） | `workflow("split")` 分片 → `parallel()` 并行处理 → `workflow("merge")` 聚合 |
-| `map-reduce.example.js` | Map-Reduce（UC-4） | `workflow("map")` 映射 → `workflow("reduce")` 归约 |
-
-## ⚠️ 这些是模板，不能直接运行
-
-每个模板调用的子 workflow（如 `workflow("extract")`、`workflow("split")`）**未在本文件内定义**。运行前你必须：
-
-1. **复制模板到 workflows 目录**：
-   ```bash
-   cp chain.example.js ~/.pi/agent/workflows/chain.js
-   # 或项目级：cp chain.example.js .pi/workflows/chain.js
-   ```
-
-2. **定义被引用的子 workflow**：在 workflows 目录下创建 `extract.js`、`transform.js`、`load.js` 等，每个含 `meta` + `execute()` + `agent()`/`parallel()`/`pipeline()` 入口。
-
-3. **运行**：
-   ```bash
-   workflow run chain --args inputPath=/path/to/input.json
-   ```
-
-## 嵌套 workflow() 说明
-
-`workflow("name", args)` 在 worker 线程内调用另一个已注册的 workflow（详见 SKILL.md `workflow()` section）：
-
-- **返回值**：`AgentResult`——成功 `{ content, parsedOutput? }`，失败 `{ content: "", error }`
-- **循环检测**：自动追踪调用链（A→B→A 立即拒绝）
-- **预算继承**：子 workflow 继承父剩余预算，消耗累加回父
-- **并发配额**：嵌套按 depth 分层分配（`max(1, 6-depth)`），保底 1 槽防饿死
-
-## 相关文档
-
-- `skills/workflow-script-format/SKILL.md` — workflow script 完整 API
-- `docs/adr/030-subagents-workflow-merge.md` — 合并决策（决策 3 嵌套护栏）

package/examples/chain.example.js

@@ -1,92 +0,0 @@
-// chain.example.js — 顺序编排模板（UC-1）
-//
-// 模式：workflow("step-a") → workflow("step-b") → workflow("step-c") → agent(verify)
-// 每步输出作下步输入。展示 workflow() 顺序嵌套调用 + try-catch 错误处理。
-//
-// 用法：复制本文件到 .pi/workflows/ 或 ~/.pi/agent/workflows/，改 workflow 名后：
-//   workflow run chain --args inputPath=/path/to/input.json
-//
-// ⚠️ lintScript 约束（本模板已遵守）：
-//   - 必须含 agent()/parallel()/pipeline() 入口之一（本模板末端 agent verify 兼满足 + 真实模式）
-//   - 禁止 bare IIFE（用 top-level await）
-//   - 禁止用 result 作变量名（lintScript 对 result 变量的 .output / .parsedOutput / .content 访问报 error）
-
-const meta = {
-  name: "chain",
-  description: "顺序编排模板：workflow A→B→C，每步输出作下步输入，末端 agent 校验",
-  phases: ["extract", "transform", "load", "verify"],
-};
-
-const fs = require("fs");
-
-// ── 入参（$ARGS）──────────────────────────────────────────────────
-const inputPath = $ARGS.inputPath;
-if (!inputPath) {
-  // 缺参直接 throw（在 try 外，不会被 catch 吞掉，workflow 引擎报清晰错误）
-  throw new Error("chain 缺少必需参数 inputPath。用法：workflow run chain --args inputPath=/path/to/input.json");
-}
-if (!fs.existsSync(inputPath)) {
-  throw new Error("inputPath 不存在: " + inputPath);
-}
-
-log("chain 开始，inputPath=" + inputPath);
-
-let currentPhase = "init";
-let outcome;
-
-try {
-  // ── 段 1：extract（workflow 嵌套调用）─────────────────────────────
-  phase("extract");
-  currentPhase = "extract";
-  // workflow() 返回 AgentResult { content, parsedOutput?, usage?, error? }
-  // 调用名为 "extract" 的子 workflow，传入 inputPath
-  const a = await workflow("extract", { source: inputPath });
-  if (a.error) throw new Error("extract 失败: " + a.error);
-
-  // ── 段 2：transform（a.content 作下步输入）────────────────────────
-  phase("transform");
-  currentPhase = "transform";
-  const b = await workflow("transform", { raw: a.content });
-  if (b.error) throw new Error("transform 失败: " + b.error);
-
-  // ── 段 3：load（b.content 作下步输入）──────────────────────────────
-  phase("load");
-  currentPhase = "load";
-  const c = await workflow("load", { normalized: b.content });
-  if (c.error) throw new Error("load 失败: " + c.error);
-
-  // ── 段 4：verify（agent 校验，兼满足 lintScript entry-point）──────
-  phase("verify");
-  currentPhase = "verify";
-  const verify = await agent({
-    prompt: "校验以下 chain 输出是否完整、无遗漏关键字段。输出 valid + summary。\n\n" + c.content,
-    schema: {
-      type: "object",
-      properties: {
-        valid: { type: "boolean", description: "chain 输出是否通过校验" },
-        summary: { type: "string", description: "校验摘要" },
-      },
-      required: ["valid", "summary"],
-    },
-    description: "chain-verify",
-  });
-  if (!verify.valid) throw new Error("chain verify 失败: " + verify.summary);
-
-  outcome = {
-    status: "ok",
-    phase: currentPhase,
-    final: c.content,
-    verify: verify.summary,
-    message: "chain 完成：extract → transform → load → verify 全绿",
-  };
-} catch (err) {
-  // 错误处理：返回 error 对象，不 crash（workflow 引擎据 status 决策，非 throw 中断）
-  outcome = {
-    status: "error",
-    phase: currentPhase,
-    error: err && err.message ? err.message : String(err),
-    message: "chain 在 " + currentPhase + " 段失败",
-  };
-}
-
-return outcome;

package/examples/map-reduce.example.js

@@ -1,99 +0,0 @@
-// map-reduce.example.js — 映射-归约模板（UC-4）
-//
-// 模式（两段）：
-//   段 1 map:    parallel(items.map(i => workflow("map", {item:i}))) → mapped[]
-//   段 2 reduce: workflow("reduce", mapped) → 归约结果
-//
-// 与 scatter-gather 的区别：scatter-gather 强调数据分片（split 决定分片数）；
-// map-reduce 强调对固定 items 数组的变换+聚合（items 已知，map 变换、reduce 聚合）。
-//
-// 用法：复制本文件到 .pi/workflows/ 或 ~/.pi/agent/workflows/，改 workflow 名后：
-//   workflow run map-reduce --args itemsPath=/path/to/items.json
-//
-// ⚠️ lintScript 约束（本模板已遵守）：
-//   - 含 parallel() 入口（兼展示 workflow() 嵌套：map + reduce）
-//   - 禁止 bare IIFE / 禁止变量名 result
-
-const meta = {
-  name: "map-reduce",
-  description: "映射-归约模板：parallel map → reduce 两段",
-  phases: ["map", "reduce"],
-};
-
-const fs = require("fs");
-
-// ── 入参（$ARGS）──────────────────────────────────────────────────
-const itemsPath = $ARGS.itemsPath;
-if (!itemsPath) {
-  throw new Error("map-reduce 缺少必需参数 itemsPath。用法：workflow run map-reduce --args itemsPath=/path/to/items.json");
-}
-if (!fs.existsSync(itemsPath)) {
-  throw new Error("itemsPath 不存在: " + itemsPath);
-}
-
-log("map-reduce 开始，itemsPath=" + itemsPath);
-
-let currentPhase = "init";
-let outcome;
-
-try {
-  // 读 items 数组（外部数据，非 workflow 状态文件）
-  const rawItems = JSON.parse(fs.readFileSync(itemsPath, "utf-8"));
-  if (!Array.isArray(rawItems) || rawItems.length === 0) {
-    throw new Error("itemsPath 内容非数组或为空");
-  }
-  log("读入 " + rawItems.length + " 个 item");
-
-  // ── 段 1：map（parallel 对每个 item 并行变换）────────────────────
-  phase("map");
-  currentPhase = "map";
-  // parallel() allSettled 语义：单个 map 失败不 reject
-  const mappedRaw = await parallel(
-    rawItems.map((item, idx) => workflow("map", { item, itemIndex: idx })),
-  );
-
-  const mapped = [];
-  let mapFailed = 0;
-  for (let i = 0; i < mappedRaw.length; i++) {
-    const m = mappedRaw[i];
-    if (!m || m.error) {
-      // map 失败的 item 用 error 占位传入 reduce，由 reduce 决定跳过还是报错
-      mapped.push({ itemIndex: i, status: "failed", error: m ? m.error : "无返回" });
-      mapFailed++;
-    } else {
-      mapped.push({ itemIndex: i, status: "ok", content: m.content });
-    }
-  }
-  if (mapFailed === rawItems.length) {
-    throw new Error("全部 map 失败（" + mapFailed + "/" + rawItems.length + "）");
-  }
-  log("map 完成：ok=" + (rawItems.length - mapFailed) + " failed=" + mapFailed);
-
-  // ── 段 2：reduce（workflow 聚合所有 map 结果）───────────────────
-  phase("reduce");
-  currentPhase = "reduce";
-  const reduced = await workflow("reduce", {
-    mapped,
-    totalItems: rawItems.length,
-    mapFailed,
-  });
-  if (reduced.error) throw new Error("reduce 失败: " + reduced.error);
-
-  outcome = {
-    status: mapFailed > 0 ? "partial" : "ok",
-    phase: currentPhase,
-    items_total: rawItems.length,
-    map_failed: mapFailed,
-    reduced: reduced.content,
-    message: "map-reduce 完成：map " + rawItems.length + " 项（失败 " + mapFailed + "）→ reduce",
-  };
-} catch (err) {
-  outcome = {
-    status: "error",
-    phase: currentPhase,
-    error: err && err.message ? err.message : String(err),
-    message: "map-reduce 在 " + currentPhase + " 段失败",
-  };
-}
-
-return outcome;

package/examples/parallel.example.js

@@ -1,82 +0,0 @@
-// parallel.example.js — 并行编排模板（UC-2）
-//
-// 模式：parallel([workflow("analyze-a"), workflow("analyze-b"), workflow("analyze-c")])
-// 多个 workflow 并行执行，Promise.allSettled 语义（部分失败不 reject，在 outcome 标 failed）。
-//
-// 用法：复制本文件到 .pi/workflows/ 或 ~/.pi/agent/workflows/，改 workflow 名后：
-//   workflow run parallel --args target=src/main.ts
-//
-// ⚠️ 分层配额规则（来源：T2 system-architecture §并发池分层配额，ADR-030 并发上限来源）：
-//   - 全局并发上限 maxConcurrent = 6（ConcurrencyPool 默认值，T2 实现）
-//   - 嵌套 workflow 时按 depth 分层：depth=N 时该层可用配额 = max(1, 6 - N)
-//     例：顶层 workflow（depth=0）可用 6 槽；其内再 fork workflow（depth=1）可用 5 槽；
-//     depth=5 时保底 1 槽（max(1, 6-5)=1），防饿死。
-//   - parallel() 内的 workflow() 调用共享父 workflow 的配额池，超出自动排队（不报错）。
-//   - 本模板 parallel 3 个 workflow：顶层配额 6 足够，无需排队。
-//
-// ⚠️ lintScript 约束（本模板已遵守）：
-//   - 含 parallel() 入口（兼展示 workflow() 嵌套）
-//   - 禁止 bare IIFE / 禁止变量名 result
-
-const meta = {
-  name: "parallel",
-  description: "并行编排模板：parallel([workflow A, B, C])，allSettled 语义，分层配额注释",
-  phases: ["parallel-analyze"],
-};
-
-// ── 入参（$ARGS）──────────────────────────────────────────────────
-const target = $ARGS.target;
-const tasks = $ARGS.tasks || ["analyze-a", "analyze-b", "analyze-c"]; // 默认 3 路并行
-if (!target) {
-  throw new Error("parallel 缺少必需参数 target。用法：workflow run parallel --args target=src/main.ts");
-}
-
-log("parallel 开始，target=" + target + " tasks=" + JSON.stringify(tasks));
-
-let outcome;
-
-try {
-  phase("parallel-analyze");
-
-  // parallel() 接受 Promise 数组；workflow() 返回 Promise<AgentResult>。
-  // allSettled 语义：单个 workflow 失败（返回 error 字段）不会让 parallel reject，
-  // 全部完成后统一收集，在 outcome 里按 per-task 标 ok/failed。
-  const rawResults = await parallel(
-    tasks.map((taskName) => workflow(taskName, { target, task: taskName })),
-  );
-
-  // 逐个检查 error 字段（workflow 失败入 error 字段，不 throw）
-  const perTask = [];
-  let hasFailed = false;
-  for (let i = 0; i < rawResults.length; i++) {
-    const r = rawResults[i];
-    if (!r || r.error) {
-      perTask.push({ task: tasks[i], status: "failed", error: r ? r.error : "workflow 无返回" });
-      hasFailed = true;
-    } else {
-      perTask.push({ task: tasks[i], status: "ok", content: r.content });
-    }
-  }
-
-  outcome = {
-    status: hasFailed ? "partial" : "ok",
-    phase: "parallel-analyze",
-    tasks: perTask,
-    ok_count: perTask.filter((t) => t.status === "ok").length,
-    failed_count: perTask.filter((t) => t.status === "failed").length,
-    message: hasFailed
-      ? "parallel 完成（部分失败）：ok=" + perTask.filter((t) => t.status === "ok").length +
-        " failed=" + perTask.filter((t) => t.status === "failed").length
-      : "parallel 全绿：全部 " + perTask.length + " 个 workflow 成功",
-  };
-} catch (err) {
-  // parallel 整体 reject 罕见（通常是引擎级故障），仍兜底返回 error 对象不 crash
-  outcome = {
-    status: "error",
-    phase: "parallel-analyze",
-    error: err && err.message ? err.message : String(err),
-    message: "parallel 执行抛异常",
-  };
-}
-
-return outcome;

package/examples/scatter-gather.example.js

@@ -1,106 +0,0 @@
-// scatter-gather.example.js — 分发-收集模板（UC-3）
-//
-// 模式（三段）：
-//   段 1 scatter: workflow("split", data) → 出 shards[]
-//   段 2 process: parallel(shards.map(s => workflow("process", {shard:s}))) → 并行处理
-//   段 3 gather:  workflow("merge", results) → 合并
-//
-// 用法：复制本文件到 .pi/workflows/ 或 ~/.pi/agent/workflows/，改 workflow 名后：
-//   workflow run scatter-gather --args dataPath=/path/to/big.json
-//
-// ⚠️ lintScript 约束（本模板已遵守）：
-//   - 含 parallel() 入口（兼展示 workflow() 嵌套：split/merge + process）
-//   - 禁止 bare IIFE / 禁止变量名 result
-
-const meta = {
-  name: "scatter-gather",
-  description: "分发-收集模板：split → parallel process → merge 三段",
-  phases: ["scatter", "process", "gather"],
-};
-
-const fs = require("fs");
-
-// ── 入参（$ARGS）──────────────────────────────────────────────────
-const dataPath = $ARGS.dataPath;
-if (!dataPath) {
-  throw new Error("scatter-gather 缺少必需参数 dataPath。用法：workflow run scatter-gather --args dataPath=/path/to/big.json");
-}
-if (!fs.existsSync(dataPath)) {
-  throw new Error("dataPath 不存在: " + dataPath);
-}
-
-log("scatter-gather 开始，dataPath=" + dataPath);
-
-let currentPhase = "init";
-let outcome;
-
-try {
-  // ── 段 1：scatter（split workflow 分片数据）──────────────────────
-  phase("scatter");
-  currentPhase = "scatter";
-  const splitOutcome = await workflow("split", {
-    source: dataPath,
-    // split workflow 决定分片数（按数据量/可用配额），返回 shards 数组
-  });
-  if (splitOutcome.error) throw new Error("split 失败: " + splitOutcome.error);
-
-  // split workflow 返回的 content 应是分片清单（JSON 字符串或 parsedOutput 数组）
-  // 用 schema 让 split 直接返回结构化 shards（参考 workflow-script-format 结构化输出规则）
-  const shards = splitOutcome.parsedOutput || JSON.parse(splitOutcome.content);
-  if (!Array.isArray(shards) || shards.length === 0) {
-    throw new Error("split 返回的 shards 非数组或为空");
-  }
-  log("split 出 " + shards.length + " 个分片");
-
-  // ── 段 2：process（parallel 并行处理每个分片）────────────────────
-  phase("process");
-  currentPhase = "process";
-  // parallel() allSettled 语义：单个分片处理失败不 reject，收集后统一判断
-  const processed = await parallel(
-    shards.map((shard, idx) => workflow("process", { shard, shardIndex: idx })),
-  );
-
-  const shardResults = [];
-  let failedShards = 0;
-  for (let i = 0; i < processed.length; i++) {
-    const p = processed[i];
-    if (!p || p.error) {
-      shardResults.push({ shardIndex: i, status: "failed", error: p ? p.error : "无返回" });
-      failedShards++;
-    } else {
-      shardResults.push({ shardIndex: i, status: "ok", content: p.content });
-    }
-  }
-  if (failedShards === shards.length) {
-    throw new Error("全部分片处理失败（" + failedShards + "/" + shards.length + "）");
-  }
-  log("process 完成：ok=" + (shards.length - failedShards) + " failed=" + failedShards);
-
-  // ── 段 3：gather（merge workflow 合并结果）───────────────────────
-  phase("gather");
-  currentPhase = "gather";
-  const merged = await workflow("merge", {
-    shardResults,
-    totalShards: shards.length,
-    failedShards,
-  });
-  if (merged.error) throw new Error("merge 失败: " + merged.error);
-
-  outcome = {
-    status: failedShards > 0 ? "partial" : "ok",
-    phase: currentPhase,
-    shards_total: shards.length,
-    shards_failed: failedShards,
-    merged: merged.content,
-    message: "scatter-gather 完成：split " + shards.length + " → process（失败 " + failedShards + "）→ merge",
-  };
-} catch (err) {
-  outcome = {
-    status: "error",
-    phase: currentPhase,
-    error: err && err.message ? err.message : String(err),
-    message: "scatter-gather 在 " + currentPhase + " 段失败",
-  };
-}
-
-return outcome;

package/src/interface/gui-adapter.ts

@@ -1,136 +0,0 @@
-/**
- * GUI 协议适配层 —— TUI/RPC 双模渲染支持。
- *
- * 封装 @xyz-agent/extension-protocol 的 helpers，供 subagent/workflow/bg-notify 使用。
- * 当 extension-protocol 包可用后，替换 import 即可（stub 接口完全对齐）。
- *
- * 协议核心：
- *   - isGuiCapable(ctx) → RPC 模式返回 true
- *   - guiComponent(type, props) → 构造结构化 GuiComponent
- *   - guiResult(component) → 包装为 GuiRenderResult，放进 details.__gui__
- *
- * 渲染入口：
- *   - tool result: details.__gui__（execute 返回时构造）
- *   - message: details.__gui__（sendMessage 时附带）
- *
- * @see docs/extensions/gui-protocol-guide.md
- */
-
-// ============================================================
-// 类型（对齐 @xyz-agent/extension-protocol）
-// ============================================================
-
-/** GuiContext —— Pi ExtensionContext 的结构化子集。 */
-export interface GuiContext {
-  hasUI?: boolean;
-}
-
-/** GuiComponent 类型枚举（本扩展实际使用的子集）。 */
-export type GuiComponentType =
-  | "task-list"
-  | "workflow-runs"
-  | "subagent-trace"
-  | "stats-line";
-
-/** 各类型对应的 props 形状。 */
-export interface TaskListProps {
-  title: string;
-  items: Array<{
-    label: string;
-    status: "pending" | "in_progress" | "completed" | "failed" | "cancelled";
-    detail?: string;
-  }>;
-  summary?: string;
-}
-
-export interface WorkflowRunsProps {
-  runs: Array<{
-    runId: string;
-    name: string;
-    status: string;
-    reason?: string;
-    durationMs?: number;
-    error?: string;
-  }>;
-}
-
-export interface SubagentTraceProps {
-  agent: string;
-  status: "running" | "done" | "failed" | "cancelled";
-  stats?: {
-    turns?: number;
-    tokens?: number;
-    durationMs?: number;
-  };
-  result?: string;
-}
-
-export interface StatsLineProps {
-  items: Array<{
-    label: string;
-    value: string;
-    severity?: "ok" | "warn" | "danger";
-  }>;
-}
-
-export type GuiComponentProps = {
-  "task-list": TaskListProps;
-  "workflow-runs": WorkflowRunsProps;
-  "subagent-trace": SubagentTraceProps;
-  "stats-line": StatsLineProps;
-};
-
-export interface GuiComponent<T extends GuiComponentType = GuiComponentType> {
-  type: T;
-  props: GuiComponentProps[T];
-}
-
-export interface GuiRenderResult {
-  v: 1;
-  component: GuiComponent;
-}
-
-// ============================================================
-// Helpers（stub 实现，对齐 @xyz-agent/extension-protocol）
-// ============================================================
-
-/**
- * 检测当前环境是否支持 GUI 渲染（RPC 模式）。
- * Pi TUI 模式下 hasUI 为 true，RPC 模式下为 false。
- */
-export function isGuiCapable(ctx: GuiContext): boolean {
-  return ctx.hasUI === false;
-}
-
-/**
- * 构造 GuiComponent，带类型推断。
- */
-export function guiComponent<T extends GuiComponentType>(
-  type: T,
-  props: GuiComponentProps[T],
-): GuiComponent<T> {
-  return { type, props };
-}
-
-/**
- * 构造 GuiRenderResult，放进 details.__gui__。
- * 递归删除 undefined 字段。
- */
-export function guiResult(component: GuiComponent): GuiRenderResult {
-  return { v: 1, component: stripUndefined(component) as GuiComponent };
-}
-
-/**
- * 递归删除 undefined 字段（JSON.stringify 会丢弃 undefined，但数组中会变 null）。
- */
-function stripUndefined(obj: unknown): unknown {
-  if (obj === null || typeof obj !== "object") return obj;
-  if (Array.isArray(obj)) return obj.map(stripUndefined);
-  const result: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
-    if (value !== undefined) {
-      result[key] = stripUndefined(value);
-    }
-  }
-  return result;
-}