# claude-coop 镜像构建与运行说明

## 构建镜像

在仓库根目录（`agent/`）执行：

```bash
DOCKER_BUILDKIT=0 docker build -f "claude code/Dockerfile" -t claude-coop "claude code/"
```

> 构建上下文是 `claude code/` 目录（注意路径含空格，需引号包裹）。

## 镜像内容

| 组件 | 说明 |
| --- | --- |
| 基础镜像 | `node:22-alpine`（node 22 + npm） |
| 编码 agent | `@anthropic-ai/claude-code`（claude CLI，headless 模式入口） |
| MCP runtime | `@modelcontextprotocol/sdk`（blackboard MCP server 依赖） |
| 系统工具 | curl wget git jq openssl ripgrep file |
| Python | python3 + 常用库（requests/cryptography/paramiko/PyYAML/numpy 等） |
| blackboard 工具 | MCP server（`/mcp/blackboard-server.mjs`），提供 read/post/done 三个工具 |

## 与 pi-coop 的差异

| 维度 | pi-coop | claude-coop |
| --- | --- | --- |
| 编码 agent | pi（@earendil-works/pi-coding-agent） | Claude Code（@anthropic-ai/claude-code） |
| 工具注册 | pi extension（-e flag） | MCP server（--mcp-config） |
| 模型配置 | provider 体系（--provider coop --model X） | ANTHROPIC_* 环境变量 |
| 协议支持 | openai + anthropic | 仅 anthropic（Claude Code 限制） |
| session 提取 | NDJSON 首行 session header | JSON result 的 session_id 字段 |
| session 恢复 | --session-id | --resume |
| 权限 | 无（pi 无权限弹窗） | --dangerously-skip-permissions（headless 必需，非 root） |

## 环境变量契约（与 pi-coop 一致）

| 变量 | 说明 | 必填 |
| --- | --- | --- |
| MODEL | 模型名（如 deepseek-v4-flash） | 是 |
| BASE_URL | Anthropic 兼容 API base-url（不带 /v1） | 是 |
| API_KEY | API key | 是 |
| PROTOCOL | 协议（claude-coop 仅支持 anthropic） | 否 |
| TASK | 任务描述（或挂载 $BB/task.md） | 是 |
| BLACKBOARD | 黑板目录（默认 /blackboard） | 否 |
| ROUND_MAX | 最大轮次（默认 10） | 否 |
| TIMEOUT | 单轮超时秒数（默认 600） | 否 |
| FAIL_MODE | agent 失败时：stop（默认）/ continue | 否 |

## 手动测试

```bash
# 测试镜像工具链
docker run --rm --entrypoint sh claude-coop -c 'which claude node python3 curl wget jq; claude --version'

# 测试 blackboard MCP server
docker run --rm --entrypoint sh claude-coop -c 'BB=/tmp/bb mkdir -p /tmp/bb && BB=/tmp/bb node /mcp/blackboard-server.mjs & sleep 1 && kill %1'
```

## 控制层适配

控制层 `tools_coop.go` 中 `coopImage` 常量当前为 `"pi-coop"`。如需切换到 claude-coop：

```go
const coopImage = "claude-coop"
```

环境变量注入逻辑无需改动（MODEL/BASE_URL/API_KEY/PROTOCOL 契约一致），但需注意：
- Claude Code 仅支持 Anthropic 协议端点，`coopBaseURL` 对 anthropic 不再补 `/v1`（已修复）
- `PROTOCOL=anthropic` 时，`BASE_URL` 应为 `https://api.deepseek.com/anthropic`