# pigo 协作 —— 调用文档

> 在 Docker 容器内运行一个 pigo agent（单 agent）完成 /blackboard/task.md 中的任务，工作区为 /blackboard/workspace，完成时通过 blackboard 工具创建 DONE；supervisor 把结果以结构化 JSON（result.json）落盘，供外部调度方直接解析。

---

## 1. 原理与架构

```
                +------------------ docker 容器 pigo-coop ----------------+
                |                                                        |
  TASK/MODEL/   |   +---------- supervisor.sh（单 agent 编排）-------+   |
  API_KEY ──────┼─▶ |  每轮运行一个 pigo 进程：                       |   |
                |   |   └─ agent ──▶ cwd = /blackboard/workspace      |   |
                |   |      (--resume 会话 · 角色 prompt agent.md)      |   |
                |   +──────┬────────────────────────────────----------+   |
                |          ▼                                               |
                |   /blackboard（任务黑板：task.md + workspace + DONE）    |
                +-----------------------------------------------------------+
```

- **单 agent**：每轮一个 pigo 进程串行推进，无评审者；工作区 `/blackboard/workspace` 是普通文件工具（read/write/bash）的根目录。
- **原子完成标记**：`DONE` 只能通过 `blackboard` 工具 `done`（`O_CREATE|O_EXCL`）创建，supervisor 检测到 `DONE` 即收尾。
- **连续上下文**：headless 运行自动持久化会话，supervisor 从 stream-json 首事件提取 `sessionId`，下一轮用 `--resume` 恢复，agent 跨轮记住自己的思考。
- **协议注入**：任务协议（AGENTS.md）副本放入工作区，pigo 自动注入系统提示；角色 prompt 通过 `--append-system-prompt` 注入。
- **结构化结果**：任务结束（成功/未解出/超时/失败）统一写 `$BB/result.json`，字段：`status`、`exit_code`、`summary`、`flag`、`artifacts`。

---

## 2. 前置条件

| 依赖 | 说明 |
| --- | --- |
| Go 工具链 | 版本与 `go.mod` 一致（当前 `go 1.27rc1`），用于交叉编译 pigo 二进制 |
| Docker | 本机已有基础镜像 `pigo-worker:latest`（Alpine，含 bash/git/wget/flock/timeout/CA 证书） |
| 模型后端 | 任意 OpenAI 兼容 API（如 DeepSeek、Ollama、OpenRouter），需可访问的 base-url 与 API key |

---

## 3. 构建

### 3.1 交叉编译 pigo（含 blackboard 工具）

Windows PowerShell：

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

Linux/macOS：

```bash
GOOS=linux CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o coop/tmp/pigo-linux-amd64 ./cmd/pigo
```

产物 `coop/tmp/pigo-linux-amd64` 是纯静态 Linux 二进制（约 30MB）。

### 3.2 构建镜像

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

> 镜像直接 `FROM pigo-worker:latest`（复用本机已有镜像，不拉取 golang/alpine），只覆盖 pigo 二进制并加入 supervisor 与协作 prompt，构建通常秒级完成。

---

## 4. 环境变量（运行参数）

| 变量 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `MODEL` | ✅ | — | 模型名，如 `deepseek-chat` |
| `BASE_URL` | ✅ | — | OpenAI 兼容 API base-url |
| `API_KEY` | ✅ | — | API key |
| `PROTOCOL` | 否 | 按 model 推断 | 协议 `openai` / `anthropic` |
| `TASK` | 二选一 | — | 任务描述；不填则需挂载 `$BB/task.md` |
| `BLACKBOARD` | 否 | `/blackboard` | 黑板根目录（即 `BB`） |
| `PROMPTS` | 否 | `/prompts` | 协作 prompt 目录（镜像内固定，一般不用改） |
| `ROUND_MAX` | 否 | `10` | 最大轮次 |
| `TIMEOUT` | 否 | `600` | 单轮超时秒数，`0`=不超时 |
| `FAIL_MODE` | 否 | `stop` | agent 失败时：`stop`=立即退出（默认）\| `continue`=继续下一轮 |

---

## 5. 运行示例

### 5.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
```

### 5.2 保留黑板产物与连续会话（推荐）

```bash
mkdir -p blackboard
docker run --rm \
  -v $PWD/blackboard:/blackboard \            # 黑板产物落盘
  -v $HOME/.pigo:/root/.pigo \                # 保留 agent 会话（--resume 依赖）
  -e MODEL=deepseek-chat \
  -e BASE_URL=https://api.deepseek.com \
  -e API_KEY=<your-key> \
  -e TASK="..." \
  pigo-coop
```

> 会话持久化在 `~/.pigo/sessions`（容器内为 `/root/.pigo`）。**不挂载 `$HOME` 时，会话只存在于容器生命周期内**——跨 `docker run` 不保留；每次 `run` 内部跨轮仍有效。

### 5.3 结果与退出码

- 任务完成（检测到 `DONE`）：退出码 `0`，`result.json` 的 `status=solved`。
- 达到 `ROUND_MAX` 仍未完成：退出码 `1`，`status=unsolved`，检查黑板与日志。
- 单轮超时被强杀：`status=timeout`（退出码 124）。
- 参数缺失 / 非法：退出码 `2`。

---

## 6. 黑板目录结构

```
/blackboard/
├── task.md            # 任务描述（勿修改）
├── AGENTS.md          # 任务协议（工作区有副本）
├── workspace/         # agent 工作区 = 其 cwd（产物全部在这里）
├── DONE               # 完成标记（只用 blackboard done 创建）
├── result.json        # 结构化结果（supervisor 结束时生成）
├── sessions/          # agent 的 session id（supervisor 内部维护，供 --resume）
└── logs/              # 每轮运行日志：round-N.log
```

---

## 7. blackboard 工具（agent 侧 API）

pigo 在 `BB` 环境变量存在时自动注册 `blackboard` 工具；普通运行不受影响。agent 通过该工具原子读写黑板：

| 操作 | 参数 | 行为 |
| --- | --- | --- |
| `read` | （可选 `path`） | 无 `path`：返回黑板全局快照（task.md、workspace 清单、DONE 状态、环境）；有 `path`：返回黑板内单文件内容（如 `workspace/exploit.py`） |
| `post` | `file`、`content` | 原子追加消息到 `messages/<file>`；`file` 必须是裸 `*.md` 名（防目录穿越），内容 ≤ 32 KiB |
| `done` | `summary` | 原子创建 `DONE`（`O_CREATE|O_EXCL`）；已存在则报错且不覆盖。仅交付完整时调用 |

环境变量 `BB` / `ROUND` / `NAME` 由 supervisor 注入。

---

## 8. 验证与调试

### 8.1 无模型端到端验证（mock）

`coop/tmp/mock_openai.py` 是一个 OpenAI 兼容 mock server，驱动 agent 依次调用 `blackboard done`，用于验证单 agent 编排与 DONE 原子性：

```bash
# 终端 1：启动 mock（本机）
python coop/tmp/mock_openai.py 8899

# 终端 2：运行容器，base-url 指向 mock（按环境替换宿主地址）
docker run --rm \
  -v $PWD/blackboard:/blackboard \
  -e MODEL=mock -e BASE_URL=http://<host-ip>:8899 -e API_KEY=test \
  -e TASK="验证任务" -e ROUND_MAX=3 -e TIMEOUT=120 \
  pigo-coop
```

预期：agent 完成并创建 `DONE`，容器退出 0，`blackboard/result.json` 中 `status=solved`。

### 8.2 查看日志

```bash
# 黑板挂载后：
cat blackboard/logs/round-1.log   # 第 1 轮的 stream-json 事件
cat blackboard/sessions/agent.session  # 下一轮 --resume 用的 session id
```

### 8.3 常见问题

| 现象 | 原因 / 处理 |
| --- | --- |
| 退出码 `2` 且提示缺 MODEL/BASE_URL/API_KEY | 未传必填环境变量 |
| 容器内报 `DONE already exists` | 正常：DONE 幂等，上一次运行已留标记 |
| 跨 run 后 agent 不记得之前轮次 | 未挂载 `$HOME/.pigo`；会话在容器内 `~/.pigo/sessions`，`--rm` 后丢失 |
| `docker build` 报找不到 `pigo-worker:latest` | 先 `docker pull` 或在目标机导入该基础镜像 |
| 构建期 `chmod` 被拒 | 已用 `COPY --chmod=755` 规避（NTFS 挂载构建上下文会丢可执行位） |

---

## 9. 任务协议要点（详见 `/blackboard/AGENTS.md`）

每轮：**读取 task.md → 检查已有产物 → 推进任务 → 完成后用 blackboard done 创建 DONE**。红线：不直接写 DONE；不伪造命令/提交结果；不修改 task.md 与 AGENTS.md。