pi-graph

中文 | English

为 Pi agent harness 提供可恢复、可审计的多 Agent 状态图编排。

pi-graph 用显式 state、nodes、edges 和 reducers 组织并行研究、专业分工、独立审查、人工审批与失败恢复。所有 Agent 节点仍通过 Pi SDK 在进程内运行。

简单任务优先使用一个 Pi agent loop。只有确实需要并行、独立 reviewer、持久角色记忆或人工门控时才使用图。

安装

要求 Node.js >= 22.19.0，并已安装 Pi。

从 npm 安装：

pi install npm:@shying/pi-graph

快速开始

图从以下位置发现：

| 范围 | 路径 | |---|---| | 用户 | ~/.pi/agent/graphs/*.json | | 当前项目 | <project>/.pi/graphs/*.json |

项目图只在 Pi 信任当前项目后加载。可以先安装一个示例：

mkdir -p ~/.pi/agent/graphs
curl -fsSL https://raw.githubusercontent.com/huang-sh/pi-graph/main/examples/research-review.json \
  -o ~/.pi/agent/graphs/research-review.json

启动 Pi 后：

/pig list
/pig validate research-review
/pig visualize research-review
/pig run research-review 为这个仓库设计一个安全的缓存失效方案

如果图在 human 节点暂停：

/pig resume <runId> true

核心模型

input → entry → fan-out → barrier → reviewer → loop / end

每个 superstep 中的节点读取同一份不可变 state；成功写入在 step 结束时统一提交。并行节点写入同一路径时必须配置 reducer。

节点

| 类型 | 用途 | |---|---| | agent | 研究、实现、审查等 Agent 工作 | | set | 确定性状态转换 | | human | 暂停并请求批准、选择或输入 |

Agent 上下文

| 模式 | 适合场景 | |---|---| | isolated | 独立 reviewer、并行分支、一次性专家 | | thread | 同一职责跨循环保留私有 Pi session 历史 | | shared | 多个节点共享可审计的 graph-state 消息通道 |

未声明 context 时默认使用 thread（0.1.0 起，之前为 isolated），未声明的 agent 节点在循环中保留私有会话历史。同一 threadKey 不能并发运行或跨不同 cwd。

编写图时：

• 使用 edges 表示静态连接、fan-out、barrier 和条件回环；
• 使用 response.schema 校验关键 Agent handoff；
• 使用 collect 汇总当前轮并行结果，避免循环中无限累积；
• 大型报告使用 artifact，state 只保留摘要和引用；
• 用 graph limits 约束整个 run，用 node limits 约束单个 Agent 调用。

完整字段见 Graph Schema；可直接从 examples 复制现有图。

命令

/pig list
/pig validate [graph]
/pig run <graph> [task or JSON]
/pig resume <runId> [value or JSON]
/pig inspect [runId] [--full|--inventory|state.path]
/pig delete <runId>
/pig visualize <graph>

模型也可以调用 pi_graph_run、pi_graph_resume 和 pi_graph_inspect。运行时会显示简洁的节点状态与 token 看板。

/pig inspect 默认返回摘要；/pig delete 会确认后清理 checkpoint、私有 thread 历史和 artifacts。

示例

| 示例 | 展示能力 | |---|---| | research-review | 并行研究、barrier、thread writer、独立 reviewer | | coding-review | 持久 coder、审查、人工批准、修订循环 | | shared-handoff | shared 消息通道 | | idea-tournament | 多路 fan-out 与 barrier judge | | open-ended-debate | 中立分题、两个持久辩手、认输条件边 | | science-research | 人工门控、研究循环、artifact 报告 | | science-research-auto | 可用于 headless/CI 的自动研究图 |

持久化与安全

• Run 数据由扩展保存在 ~/.pi/agent/pi-graph/；使用 /pig inspect、/pig resume 和 /pig delete 管理。
• Checkpoint 提供 at-least-once 恢复，不保证外部副作用 exactly-once；可重试写操作仍需幂等。
• readOnly 是工具 allowlist，不是操作系统 sandbox；高风险工作流应放入容器或 OS sandbox。
• 非交互运行需要 policy.allowNonInteractive；非交互写操作还需要 policy.allowNonInteractiveMutations。
• Graph/node timeout 通过 abort signal 协作终止，provider 和 tool 需要及时响应取消。

实现与故障语义见 Architecture。

开发

npm run check
npm test
npm run validate:examples

• Schema reference
• Architecture
• Changelog

License

MIT