first commit

2026-08-14 23:41:57 +08:00
commit 086803a8dd
471 changed files with 91938 additions and 0 deletions
@@ -0,0 +1,306 @@
+# 部署文档
+
+本文档覆盖 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` |