first commit

claude code/RUN.md

@@ -0,0 +1,70 @@
+# 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`