BlackBean/pigo/coop/RUN.md

pigo 协作运行指南

只讲怎么跑。原理、架构、完整参数见 README.md。

---

1. 前置检查（1 分钟）

go version        # 与 go.mod 一致（当前 go 1.27rc1）
docker images     # 确认已有 pigo-worker:latest

没有 pigo-worker:latest 时先导入它，否则构建会失败。

---

2. 构建

# Windows PowerShell：
$env:GOOS="linux"; $env:CGO_ENABLED="0"
go build -trimpath -ldflags="-s -w" -o coop/tmp/pigo-linux-amd64 ./cmd/pigo

# Linux/macOS：
GOOS=linux CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o coop/tmp/pigo-linux-amd64 ./cmd/pigo

docker build -f coop/Dockerfile -t pigo-coop .

---

3. 运行

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

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

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

mkdir -p blackboard

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

不挂载 $HOME/.pigo 时，agent 会话只在容器生命周期内有效（单次 run 内跨轮不受影响）。

3.3 常用参数速查

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

---

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 轮运行日志

result.json 是给外部调度方（如 agent-web 的 run_coop 工具）直接解析的标准结果文件，字段固定：status、exit_code、summary、flag、artifacts。

---

5. 常见运行问题

报错 / 现象	处理
退出 2：必须提供 MODEL / BASE_URL / API_KEY	补传环境变量
DONE already exists	正常，上一次运行已留标记（幂等）
找不到 pigo-worker:latest	先导入基础镜像再 build
想从头重跑	删除挂载目录里的 DONE 与 result.json 后重新 run