108 lines
2.9 KiB
Markdown
108 lines
2.9 KiB
Markdown
# pigo 协作运行指南
|
||
|
||
> 只讲怎么跑。原理、架构、完整参数见 [README.md](./README.md)。
|
||
|
||
---
|
||
|
||
## 1. 前置检查（1 分钟）
|
||
|
||
```bash
|
||
go version # 与 go.mod 一致（当前 go 1.27rc1）
|
||
docker images # 确认已有 pigo-worker:latest
|
||
```
|
||
|
||
没有 `pigo-worker:latest` 时先导入它，否则构建会失败。
|
||
|
||
---
|
||
|
||
## 2. 构建
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
```bash
|
||
docker build -f coop/Dockerfile -t pigo-coop .
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 运行
|
||
|
||
### 3.1 直接运行（不保留任何数据）
|
||
|
||
```bash
|
||
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 会话）
|
||
|
||
```bash
|
||
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`。
|
||
|
||
保留黑板后查看：
|
||
|
||
```bash
|
||
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 |
|