pi-agent-workflow

可复用的 Pi 分代理 Workflow 扩展。当前目录与业务项目同级，暂不修改任何业务项目。

目标

• 通过 WorkflowSpec 描述项目任务
• 每个 batch 使用一个独立的 Pi AgentSession
• 支持并发、重试、取消和 dry-run
• 使用 session.subscribe() 采集子 Agent 生命周期
• 在 TUI 中显示聚合状态和 batch 状态
• 将状态保存到当前项目的 .pi/workflow-runs/<runId>/
• 业务项目自己负责题目读取、结果校验和写回

临时测试

目录中的可复制示例：

examples/example.ts

在任意项目中：

pi -e D:/dev/proj/repos/pi-agent-workflow/extensions/pi-workflow.ts

运行示例：

/workflow-run D:/dev/proj/repos/pi-agent-workflow/examples/example.ts 9

示例会创建 9 个 demo job，每 3 个 job 交给一个子 Agent，并将结果写入当前项目：

.pi/workflow-runs/example-latest-results.json

通用命令：

/workflow-run .pi/workflows/example.ts arg1 arg2
/workflow-run .pi/workflows/example.ts 202609 --concurrency 4 --retries 2
/workflow-run .pi/workflows/example.ts 202609 --timeout 3600000
/workflow-run .pi/workflows/example.ts 202609 --resume <runId>
/workflow-run .pi/workflows/example.ts 202609 --force
/workflow-run .pi/workflows/example.ts 202609 --persist-sessions
/workflow-run .pi/workflows/example.ts 202609 --dry-run
/workflow-status
/workflow-status <runId>
/workflow-cancel <runId>
/workflow-retry <runId> <batchId>
/workflow-events <runId> [limit]

其它项目可以直接复制 examples/example.ts 到自己的 .pi/workflows/，然后替换 Job、Result、loadJobs、buildPrompt、parseResponse 和 applyResults。

GESP 真实集成测试 Spec 位于：

test/gesp-real-integration.workflow.ts

它只读取同级 gesp-exam-prep/data/raw/cpp-l1-202609.json 的 3 道题，使用真实 child AgentSession 校验解析结果，不写回题库。应在当前 Pi 会话中通过 workflow_run 调用，避免脱离 Pi TUI 后丢失活动模型上下文。

当前还没有把 GESP Spec 放入本目录，也没有连接 gesp-exam-prep。

WorkflowSpec 最小形式

import type { WorkflowSpec } from "pi-agent-workflow/src/types.ts";

type Job = { id: string; text: string };
type Result = { id: string; value: string };

const workflow: WorkflowSpec<Job, Result> = {
  name: "example",
  batchSize: 3,
  concurrency: 4,
  retries: 2,

  async loadJobs(_ctx, args) {
    return [{ id: args[0] || "demo", text: "..." }];
  },

  buildPrompt(batch) {
    return JSON.stringify(batch);
  },

  parseResponse(text, batch) {
    // 在这里解析并校验模型返回，必须校验 ID 和结果数量。
    return batch.map((job) => ({ id: job.id, value: text }));
  },

  async applyResults(results, _ctx) {
    // 由项目自己决定如何安全写回。
    console.log(results.length);
  },

  getJobId(job) {
    return job.id;
  },
};

export default workflow;

运行产物

.pi/workflow-runs/<runId>/
├── state.json
├── results.jsonl
├── events.jsonl
└── sessions/              # only with --persist-sessions

events.jsonl 只记录生命周期和错误元数据，不记录模型隐藏思维过程。

GitHub / npm

项目地址：

https://github.com/pgciq/pi-agent-workflow

npm 包名：

pi-agent-workflow

安装到 Pi：

pi install npm:pi-agent-workflow

本地开发版本：

pi -e D:/dev/proj/repos/pi-agent-workflow/extensions/pi-workflow.ts

自动发布 Workflow：

.github/workflows/publish.yml

发布需要在 GitHub 仓库配置 NPM_TOKEN Secret。