pi 协作运行指南

只讲怎么跑。原理、架构见 Dockerfile 与 supervisor.sh。

1. 前置检查（1 分钟）

docker --version     # 确认 Docker 可用
node --version       # 本机构建不需要，仅容器内 pi 需要 node>=22.19

与 pigo-coop 不同，pi-coop 不需要预编译二进制：pi 通过 npm 全局安装在镜像内， extension（coop.ts）由 pi 的 jiti 直接加载 .ts，无需预编译。

2. 构建

在仓库根目录执行（构建上下文为 pi-coop/ 目录，避免把 pi/、pigo/ 等大目录发给 daemon）：

docker build -f pi-coop/Dockerfile -t pi-coop pi-coop/

构建会：

拉取 node:24-bookworm-slim 基础镜像；
npm install -g @earendil-works/pi-coding-agent（pi 本体）；
装系统工具（git/ripgrep/python3/jq/openssl…）与 Python 常用库；
拷入 coop extension、supervisor、协议与提示。

国内构建慢时，Dockerfile 已用清华 PyPI 镜像加速 pip。npm 若慢可配 --build-arg 或宿主 npm 镜像。

3. 运行

3.1 直接运行（不保留任何数据）

docker run --rm \
  -e MODEL=deepseek-chat \
  -e BASE_URL=https://api.deepseek.com \
  -e API_KEY=<your-key> \
  -e PROTOCOL=openai \
  -e TASK="请为 XX 编写设计文档并实现原型" \
  -e ROUND_MAX=6 \
  pi-coop

3.2 推荐运行（保留黑板产物 + 跨 run 会话）

mkdir -p blackboard

docker run --rm \
  -v "$PWD/blackboard:/blackboard" \
  -e MODEL=deepseek-chat \
  -e BASE_URL=https://api.deepseek.com \
  -e API_KEY=<your-key> \
  -e PROTOCOL=openai \
  -e TASK="请为 XX 编写设计文档并实现原型" \
  -e ROUND_MAX=6 \
  pi-coop

3.3 常用参数速查

参数	必填	默认	用途
`MODEL`	✅	—	模型名
`BASE_URL`	✅	—	OpenAI/Anthropic 兼容 base-url
`API_KEY`	✅	—	API key
`PROTOCOL`	否	`openai`	`openai` / `anthropic`
`TASK`	✅（或用 `task.md`）	—	任务描述
`ROUND_MAX`	否	`10`	最大轮次
`TIMEOUT`	否	`600`	单轮超时秒数（`0`=不限）

环境变量与 pigo-coop 完全一致，run_coop 工具无需改动即可注入。

4. 结果怎么看

完成：stdout 打印 [supervisor] status=solved，退出码 0。
未完成：达到 ROUND_MAX，status=unsolved，退出码 1。
参数错：退出码 2。

保留黑板后查看：

ls blackboard/workspace/     # agent 产物
cat blackboard/DONE          # 最终交付总结
cat blackboard/result.json   # 结构化结果（status/exit_code/summary/flag/artifacts）
cat blackboard/logs/round-1.log   # 第 1 轮运行日志（pi --mode json 的 NDJSON 流）

result.json 字段固定：status、exit_code、summary、flag、artifacts，与 pigo-coop 完全一致，外部调度方（如 agent-web 的 run_coop 工具）解析逻辑无需改动。

5. 与 pigo-coop 的差异

维度	pigo-coop	pi-coop
agent	Go 编译的 pigo 二进制	npm 安装的 pi（TypeScript）
模型接入	CLI `--base-url`/`--protocol` 直传	coop extension 读环境变量注册 provider
blackboard 工具	pigo 内置（blackboard_tool.go）	coop extension 注册（coop.ts）
输出格式	`-o stream-json`	`--mode json`（NDJSON，首行 session header）
session 恢复	`--resume <id>`	`--session-id <id> --session-dir <dir>`
cwd	`-C <dir>`	进程 cwd（supervisor 先 `cd`）
协议（task.md/DONE/result.json）	一致	一致
环境变量（MODEL/BASE_URL/...）	一致	一致

6. 常见运行问题

报错 / 现象	处理
退出 2：`必须提供 MODEL / BASE_URL / API_KEY`	补传环境变量
`DONE already exists`	正常，上一次运行已留标记（幂等）
`MissingSessionCwdError`	跨轮 resume 时 session 记录的 cwd（/blackboard/workspace）不存在；确保挂载未变
extension 加载失败	确认镜像内 `/extensions/coop.ts` 存在；`pi -e` 用 jiti 加载 ts，无需预编译
想从头重跑	删除挂载目录里的 `DONE` 与 `result.json` 后重新 run

4.2 KiB Raw Permalink Blame History Unescape Escape