# 部署文档

本文档覆盖 Local Agent 的全部部署方式：本地运行、Docker 协作引擎镜像、Tsecbench 托管模式镜像，以及完整的配置项说明与常见问题排障。

---

## 1. 架构概览

```
┌────────────────────────────────────────────────┐
│  控制层 agent（Go 二进制，本项目根目录）          │
│  - HTTP/WS 服务（Gin），serve web/static 前端    │
│  - 多轮工具调用循环（LLM 驱动）                  │
│  - run_coop 工具：调起协作容器异步执行子任务       │
└──────────────┬─────────────────────────────────┘
               │ docker run / 子进程
   ┌───────────┼─────────────┬───────────────┐
   ▼           ▼             ▼               ▼
 pi-coop    pigo-coop    claude-coop    supervisor.sh
（pi 引擎） （pigo 引擎） （Claude Code）  （本地子进程模式，
  默认                                   Tsecbench 托管用）
```

| 组件 | 目录 | 说明 |
| --- | --- | --- |
| 控制层 | `main.go` + `internal/` | Agent 核心、HTTP/WS 服务、工具实现 |
| 前端 | `web/static/` | 由控制层直接 serve，无需单独部署 |
| pi 引擎 | `pi-coop/` | **默认协作引擎**，基于 npm 包 `@earendil-works/pi-coding-agent` |
| pigo 引擎 | `pigo/` | Go 自研引擎，需交叉编译二进制后构建镜像 |
| claude 引擎 | `claude code/` | 包装 Claude Code CLI，仅支持 anthropic 协议 |
| 托管镜像 | `tencent/` | Tsecbench 平台一体化镜像（控制层 + worker 本地子进程模式） |

---

## 2. 环境要求

| 依赖 | 版本 | 用途 |
| --- | --- | --- |
| Go | ≥ 1.22（以 go.mod 为准） | 编译控制层 / pigo |
| Docker | 任意现代版本 | 构建协作镜像 / run_coop 工具 |
| Node | ≥ 22.19 | pi 引擎运行时（仅容器内需要，宿主机不用装） |
| WSL（Windows） | — | 在 Windows 上构建 Linux 镜像时使用 |
| Python 3 + paramiko | 可选 | 仅 `deploy_*.py` 远程部署脚本需要 |

---

## 3. 配置说明

### 3.1 配置优先级

```
环境变量  >  .env 文件  >  data/api-config.json  >  内置默认值
```

- `.env` 放在程序工作目录，启动时自动加载（已存在的环境变量优先）。
- `api-config.json` 由 Web 设置页写入，存于数据目录（`AGENT_DATA_DIR`）。
- 容器部署时通过 `docker run -e` 注入的环境变量具有最高优先级。

### 3.2 LLM 配置（协作引擎共用）

| 环境变量 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- |
| `LLM_API_KEY` | ✅ | — | LLM API 密钥 |
| `LLM_BASE_URL` | ✅ | — | 接口地址。anthropic 协议会自动剥离 `/v1`、`/v1/messages`、`/messages` 后缀 |
| `LLM_MODEL` | ✅ | — | 模型名，需与供应商支持的格式完全一致（如 `deepseek-v4-pro` / `deepseek-v4-flash`） |
| `LLM_PROVIDER` | ✅ | `openai` | `openai` / `anthropic` |
| `LLM_ENGINE` | 否 | `pi` | 协作引擎：`pi` / `pigo` / `claude` |
| `COOP_MODE` | 否 | `local` | 协作模式（`local` 为本地子进程模式） |

DeepSeek Anthropic 端点示例：

```
LLM_BASE_URL=https://api.deepseek.com/anthropic
LLM_PROVIDER=anthropic
LLM_MODEL=deepseek-v4-flash
```

### 3.3 控制层运行配置

| 环境变量 | 内置默认 | 说明 |
| --- | --- | --- |
| `AGENT_PORT` | `8080` | Web 服务端口 |
| `AGENT_WORKSPACE` | 当前目录 | Agent 可读写的根目录 |
| `AGENT_DATA_DIR` | `<workspace>/data` | 会话与配置存储目录 |
| `AGENT_AUTH_CODE` | 空（关闭） | 访问授权码，云端部署强烈建议设置 |
| `AGENT_MAX_CONTEXT_TOKENS` | `1000000` | 超过该估算值触发历史压缩 |
| `AGENT_KEEP_RECENT_MESSAGES` | `50` | 压缩时保留的最近消息数 |
| `AGENT_MAX_TOOL_RESULT_CHARS` | `100000` | 单次工具结果最大字符数 |
| `AGENT_MAX_ITERATIONS` | `50` | 单轮最多工具调用次数 |
| `AGENT_TOOL_TIMEOUT_SECONDS` | `600` | 单次工具执行超时 |
| `AGENT_REQUEST_TIMEOUT_SECONDS` | `600` | 单次 LLM 请求超时 |
| `AGENT_STREAM_OUTPUT_TOKENS` | `65536` | 流式输出 max_tokens（防截断关键项） |
| `AGENT_COMPACTION_TOKENS` | `16384` | 压缩摘要最大输出 token |
| `AGENT_TEMPERATURE` | `0.3` | 采样温度 |
| `AGENT_DOCKER_SOCKET` | 平台默认 | Docker 连接地址（本地 unix socket / npipe / 远程） |

> 注：`.env.example` 中的数值是保守示例。复杂任务（长思考、大输出）请参照上表默认值，尤其是 `AGENT_STREAM_OUTPUT_TOKENS`——过低会导致 LLM 思考阶段耗尽配额、工具调用被截断。

### 3.4 托管模式开关

| 环境变量 | 说明 |
| --- | --- |
| `BENCHMARK_TOKEN` | 非空时进入 Tsecbench 托管模式：启动即自动开跑评测，无需外部触发；为空则是普通本地/云部署 |

### 3.5 遗留变量

`SILICONFLOW_API_KEY` / `SILICONFLOW_BASE_URL` / `AGENT_MODEL` 为早期硅基流动专用配置，仍向后兼容；新部署统一使用 `LLM_*` 系列。

---

## 4. 部署方式一：本地直接运行

### 4.1 开发运行

```powershell
go run .
```

打开 http://localhost:8080 ，在 Web 设置页填入 API Key（写入 `data/api-config.json`），或提前配置 `.env`。

### 4.2 生产运行（Linux + systemd）

1. 交叉编译（Windows 上）：

```powershell
$env:GOOS="linux"; $env:GOARCH="amd64"; $env:CGO_ENABLED="0"
go build -trimpath -ldflags="-s -w" -o agent-linux-amd64 .
```

2. 上传 `agent-linux-amd64` 与 `web/static/` 到服务器 `/opt/agent/`：

```
/opt/agent/agent                # 二进制（chmod 755）
/opt/agent/web/static/          # 前端
/opt/agent/.env                 # 配置（可选，也可全部用环境变量）
```

3. systemd 单元 `/etc/systemd/system/agent-web.service`：

```ini
[Unit]
Description=Local Agent Web
After=network.target

[Service]
WorkingDirectory=/opt/agent
Environment=LLM_API_KEY=sk-xxxx
Environment=LLM_BASE_URL=https://api.deepseek.com/anthropic
Environment=LLM_MODEL=deepseek-v4-flash
Environment=LLM_PROVIDER=anthropic
ExecStart=/opt/agent/agent
Restart=always

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload && systemctl enable --now agent-web
curl -s http://localhost:8080/api/v1/health   # 验证
```

---

## 5. 部署方式二：Docker 协作引擎

控制层通过 `run_coop` 工具调起协作容器。**镜像名与容器名前缀是代码内置约定，不可更改**：

| 引擎 | 镜像名 | 容器名前缀 |
| --- | --- | --- |
| pi（默认） | `pi-coop` | `pi-coop-` |
| pigo | `pigo-coop` | `pigo-coop-` |
| claude | `claude-coop` | `claude-coop-` |

### 5.1 构建 pi-coop（默认引擎，推荐）

```bash
# 仓库根目录，构建上下文为 pi-coop/，无需预编译任何二进制
docker build -f pi-coop/Dockerfile -t pi-coop pi-coop/
```

镜像内含 node 22 + npm 全局安装的 pi coding agent + 系统/Python 工具。
运行参数（由 run_coop 自动注入，也可手动测试）：

```bash
docker run --rm \
  -e MODEL=deepseek-v4-flash \
  -e BASE_URL=https://api.deepseek.com/anthropic \
  -e API_KEY=<your-key> \
  -e PROTOCOL=anthropic \
  -e TASK="任务描述" \
  -e ROUND_MAX=6 \
  pi-coop
```

### 5.2 构建 pigo-coop

需先交叉编译 pigo 二进制（构建上下文为 `pigo/`）：

```bash
cd pigo
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 .
```

### 5.3 构建 claude-coop

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

仅支持 anthropic 协议；openai 协议请求会被拒绝，请切换引擎或更换端点。

### 5.4 切换引擎

Web 设置页修改协作引擎，或设置 `LLM_ENGINE=pigo` / `LLM_ENGINE=claude`。切换前确保对应镜像已构建。

---

## 6. 部署方式三：Tsecbench 托管模式（tencent/）

一体化镜像 = 控制层 agent + pi worker（本地子进程模式）+ 安全工具集，适合上传到 Tsecbench 评测平台。

### 6.1 前置准备

镜像构建依赖以下文件，**均不在 git 仓库内，需自行准备**：

| 文件 | 说明 |
| --- | --- |
| `tencent/agent-linux-amd64` | 控制层交叉编译产物（见 4.2 步骤 1） |
| `tencent/tools/nuclei` | 漏洞扫描器静态二进制 |
| `tencent/tools/observer_ward` | 指纹识别静态二进制 |
| `tencent/tools/chisel` | 内网隧道静态二进制 |
| `tencent/tools/nuclei-templates/` | Nuclei 模板库 |
| `tencent/tools/FingerprintHub-defaultv4/plugins/` | observer_ward 指纹规则库 |

### 6.2 构建与导出

在 **WSL** 中执行（脚本内 PROJECT_ROOT 按实际路径调整）：

```bash
bash tencent/build.sh
# 或自定义镜像名：IMAGE_NAME=myagent bash tencent/build.sh
```

脚本流程：检查二进制 → `docker build`（上下文为项目根，`.dockerignore` 排除无关文件）→ `docker save | gzip` 导出。

产物：`tencent/agent.tar.gz`（约 350MB），直接上传 Tsecbench 平台即可。

### 6.3 本地验证镜像

```bash
docker run --rm -p 8081:8080 \
  -e LLM_API_KEY=sk-xxxx \
  -e LLM_BASE_URL=https://api.deepseek.com/anthropic \
  -e LLM_MODEL=deepseek-v4-flash \
  -e LLM_PROVIDER=anthropic \
  tsecbench-agent:latest
```

- 打开 http://localhost:8081 验证 Web 界面。
- 平台托管时由运行时注入 `BENCHMARK_TOKEN`，agent 检测到后自动启动评测流程。
- 镜像内不含 `data/` 目录与任何预置配置，全部由环境变量注入。

---

## 7. 验证与排障

### 7.1 健康检查

```bash
curl http://localhost:8080/api/v1/health      # 服务存活（始终放行，不受授权码保护）
curl http://localhost:8080/api/v1/llm/config  # 查看生效的 LLM 配置（需授权码）
```

### 7.2 常见问题

| 现象 | 原因与解决 |
| --- | --- |
| 侧栏显示「模型未配置」 | 未设置 `LLM_API_KEY`，也未在 Web 设置页填写。配置后重启或刷新 |
| LLM 请求 404 | Base URL 拼接问题。anthropic 协议不要手动加 `/v1`，程序会自动处理后缀；openai 协议填到根地址即可 |
| 工具调用 JSON 被截断、任务失败 | `AGENT_STREAM_OUTPUT_TOKENS` 过低，LLM 思考阶段耗尽 max_tokens。保持默认 65536 |
| run_coop 报找不到镜像 | 对应引擎镜像未构建（见第 5 节），或镜像名不符合约定（必须是 `pi-coop` / `pigo-coop` / `claude-coop`） |
| run_coop 容器秒退 | 检查 `MODEL` / `BASE_URL` / `API_KEY` 是否有效；`docker logs <容器名>` 看具体报错 |
| 长命令超时 | `AGENT_TOOL_TIMEOUT_SECONDS` / `AGENT_REQUEST_TIMEOUT_SECONDS` 调大（默认 600s） |
| Web 界面 401 | 设置了 `AGENT_AUTH_CODE`，先在弹窗输入授权码 |
| 历史压缩后丢上下文 | 调大 `AGENT_KEEP_RECENT_MESSAGES`（默认 50）与 `AGENT_COMPACTION_TOKENS`（默认 16384） |

### 7.3 安全检查清单

- [ ] `.env` 与 API Key 未提交到 git（`.gitignore` 已包含 `.env`）
- [ ] 云端公开部署已设置 `AGENT_AUTH_CODE`
- [ ] API Key 泄露后立即在供应商侧吊销并轮换
- [ ] Docker Socket 未暴露给不受信任的网络
- [ ] `AGENT_WORKSPACE` 限定在专用目录，避免指向系统根目录

---

## 8. 端口与产物速查

| 场景 | 端口 | 产物 |
| --- | --- | --- |
| 本地运行 | 8080（`AGENT_PORT`） | — |
| pi/pigo/claude 协作镜像 | — | `pi-coop` / `pigo-coop` / `claude-coop` 镜像 |
| Tsecbench 托管 | 8080（容器内） | `tencent/agent.tar.gz` |