diff --git a/CLAUDE.md b/CLAUDE.md index 5ddf591..b15dd82 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -164,6 +164,20 @@ tests/ `pytest.ini_options` 中 `pythonpath = ["backend", "."]`,测试直接 import `agenteval` 和 `cli`。 +## Agent skills + +### Issue tracker + +工作项跟踪使用 `git.solahqb22.cn/solahqb/AgentEvalTool` 的 Gitea Issues。详见 `docs/agents/issue-tracker.md`。 + +### Triage labels + +Triage 使用五个默认角色标签。详见 `docs/agents/triage-labels.md`。 + +### Domain docs + +仓库采用单一上下文:根目录 `CONTEXT.md` 配合 `docs/adr/`。详见 `docs/agents/domain.md`。 + ## 部署关键信息 - **t480**:`sola-t480`(192.168.8.145:8001),Docker Compose **双容器**(`agenteval` + `openclaw-eval`) diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..bbe6605 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,14 @@ +# Domain Docs + +本仓库采用单一上下文领域文档布局。 + +## 探索前必读 + +- 根目录 `CONTEXT.md`:领域词汇与边界。 +- `docs/adr/`:与当前修改相关的架构决策。 + +文件缺失时直接继续,不要预先创建空文档。只有在术语或决策确实需要澄清时,才通过领域建模流程补充。 + +## 使用规则 + +Issue、规格、测试和代码应使用 `CONTEXT.md` 定义的领域术语,避免引入同义但含义不一致的新词。若修改与现有 ADR 冲突,必须显式指出冲突及重新决策的理由,不能静默覆盖。 diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..8cea29e --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,18 @@ +# Issue Tracker + +本仓库使用自托管 Gitea Issues: + +- 实例:`https://git.solahqb22.cn` +- 仓库:`solahqb/AgentEvalTool` +- Web:`https://git.solahqb22.cn/solahqb/AgentEvalTool/issues` +- API:`/api/v1/repos/solahqb/AgentEvalTool/issues` + +## 工作流 + +读取、创建和更新 Issue 时优先使用 Gitea REST API。认证 token 必须通过临时文件或进程环境注入,使用请求头传递;禁止写入仓库、remote URL、命令参数、日志或 Issue 正文。 + +创建前按标题搜索现有 Issue,避免重复。Issue 正文使用 Markdown;阶段进展写入评论;完成后更新状态为 closed。需要表达依赖时使用 Gitea Issue dependency API,而不是仅在正文中描述。 + +若本机已配置 `tea`,可使用非交互 flags;否则使用 `curl` 调用当前实例 Swagger 定义的 REST 接口。不要用 GitHub `gh` 命令或假设 GitHub 字段与 Gitea 完全一致。 + +Pull Request 默认不作为 triage 输入来源。 diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..7023c11 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,11 @@ +# Triage Labels + +| 技能角色 | Gitea 标签 | 含义 | +| --- | --- | --- | +| `needs-triage` | `needs-triage` | 等待维护者评估 | +| `needs-info` | `needs-info` | 等待报告者补充信息 | +| `ready-for-agent` | `ready-for-agent` | 规格完整,可由智能体执行 | +| `ready-for-human` | `ready-for-human` | 需要人工处理 | +| `wontfix` | `wontfix` | 决定不处理 | + +技能提到 triage 角色时,使用表中对应的 Gitea 标签。若仓库标签命名调整,应同步更新此表。 diff --git a/docs/deployment/volcengine-102-v1.0.md b/docs/deployment/volcengine-102-v1.0.md index ceedb09..f5c9e33 100644 --- a/docs/deployment/volcengine-102-v1.0.md +++ b/docs/deployment/volcengine-102-v1.0.md @@ -1,26 +1,43 @@ # volcengine-102 正式线部署指南 -**状态**:部署流程已实现;正式主机与密钥仍需由运维环境注入。 +**状态**:已部署并通过正式域名验收(最后验证:2026-08-09)。 **Compose**:`deploy/volcengine-102/docker-compose.yml` **入口脚本**:`scripts/deploy-volcengine-102.sh` -## 1. 部署边界 +## 1. 正式入口与流量路径 + +- 正式地址: +- DNS:`agenteval.solahqb22.cn` A 记录指向 `47.111.21.147`(`sola-aliyun-147`)。 +- HTTPS:147 Nginx 终止 TLS,并反代到 `101.96.206.102:8002`(`sola-volcengine-102`)。 +- WebSocket:Nginx 为 `/ws` 和 `/openclaw` 配置 HTTP/1.1 Upgrade。 +- 网络边界:102 的 `8002` 仅允许 `47.111.21.147/32` 访问,公网直连超时属于预期行为。 +- 证书:Let's Encrypt,实测有效期为 2026-07-20 至 2026-10-18;147 的 `certbot.timer` 已启用并处于 active 状态。 + +```mermaid +flowchart LR + Browser[浏览器] -->|HTTPS 443| DNS[agenteval.solahqb22.cn] + DNS --> Nginx[aliyun-147 Nginx] + Nginx -->|HTTP 8002,仅白名单| App[volcengine-102 AgentEval] + App --> OpenClaw[openclaw-eval] +``` + +## 2. 部署边界 正式线使用两个容器:`agenteval`(端口 `8002`)和 `openclaw-eval`(端口 `28789`)。SQLite 数据保存在 Docker named volume 中;生产 `.env` 不从代码仓库同步,必须预先放在远端: ```text -/opt/agenteval/deploy/volcengine-102/.env +/opt/sola/AgentEvalTool/deploy/volcengine-102/.env ``` -环境变量模板见 [`deploy/volcengine-102/.env.example`](../../deploy/volcengine-102/.env.example)。正式域名、API Key、OpenClaw token 和 webhook secret 不得写入 Git。 +环境变量模板见 [`deploy/volcengine-102/.env.example`](../../deploy/volcengine-102/.env.example)。API Key、OpenClaw token 和 webhook secret 不得写入 Git;正式域名和公开网络拓扑应记录在本指南中。 -## 2. 首次准备 +## 3. 首次准备 在正式主机完成 Docker/Compose、SSH 和镜像仓库访问配置,然后建立远端目录并准备 `.env`。本地只需要配置 SSH 别名或地址: ```bash -export AGENTEVAL_PROD_HOST=volcengine-102 -export AGENTEVAL_PROD_DIR=/opt/agenteval +export AGENTEVAL_PROD_HOST=sola-volcengine-102 +export AGENTEVAL_PROD_DIR=/opt/sola/AgentEvalTool export AGENTEVAL_PROD_BACKUP_DIR=/var/backups/agenteval ``` @@ -31,7 +48,7 @@ export AGENTEVAL_PROD_BACKUP_DIR=/var/backups/agenteval - 正式主机可拉取 `registry.solahqb22.cn/sola/openclaw:latest`。 - Docker named volume 和备份目录具备写权限。 -## 3. 发布流程 +## 4. 发布流程 发布必须基于已提交的 Git 版本;脚本会拒绝存在 tracked 未提交修改的工作区。推荐使用版本号加 commit 作为不可变镜像标签: @@ -40,15 +57,15 @@ scripts/deploy-volcengine-102.sh --dry-run --tag 0.8.0-6248568 scripts/deploy-volcengine-102.sh --tag 0.8.0-6248568 ``` -脚本依次执行:SSH 检查 → 版本读取 → 远端 `.env` 检查 → 同步已提交源代码 → 备份数据 volume → 远端构建带版本元数据的镜像 → 启动双容器 → 等待健康接口 → 校验版本/commit → 鉴权 API 冒烟。 +脚本依次执行:SSH 检查 → 版本读取 → 远端 `.env` 检查 → 通过 `git archive HEAD` 生成并同步已提交源代码 → 备份数据 volume → 远端构建带版本元数据的镜像 → 启动双容器 → 等待健康接口 → 校验版本/commit → 鉴权 API 冒烟。 后端启动入口 [`scripts/production-entrypoint.sh`](../../scripts/production-entrypoint.sh) 的规则是: - 全新数据库:创建初始 SQLModel schema,记录当前 Alembic 基线,再执行后续迁移。 -- 旧版无 `alembic_version` 的数据库:保留旧数据,记录基线,再执行后续迁移。 +- 旧版无 `alembic_version` 的数据库:保留旧数据,标记为 pre-Alembic base,再依次执行全部迁移。 - 已有 Alembic 版本的数据库:只执行 `alembic upgrade head`。 -## 4. 回滚 +## 5. 回滚 回滚只切换应用镜像,不自动降级数据库: @@ -58,16 +75,16 @@ scripts/deploy-volcengine-102.sh --rollback 0.8.0-previous 每次发布和回滚前都会在远端备份 named volume 到 `AGENTEVAL_PROD_BACKUP_DIR`。如果某个版本包含不可逆数据迁移,应先停止服务、恢复匹配的数据备份,再启动旧镜像;不得只回滚代码而忽略数据库版本。 -## 5. 发布后检查 +## 6. 发布后检查 ```bash ssh "$AGENTEVAL_PROD_HOST" \ - 'cd /opt/agenteval && docker compose -f deploy/volcengine-102/docker-compose.yml ps' + 'cd /opt/sola/AgentEvalTool && docker compose -f deploy/volcengine-102/docker-compose.yml ps' ``` -至少验证:`/api/health`、`/api/targets`、`/api/scenarios`、`/api/runs`、`/api/campaigns`、`/api/intelligent-evals`、`/api/model-configs` 和 `/openclaw/`。发现异常时保留部署输出、容器日志和备份文件,再执行回滚判断。 +至少通过正式域名验证:`/api/health`、`/api/targets`、`/api/scenarios`、`/api/runs`、`/api/campaigns`、`/api/intelligent-evals`、`/api/model-configs` 和 `/openclaw/`。`/ws` 应返回 `101 Switching Protocols`。发现异常时保留部署输出、容器日志和备份文件,再执行回滚判断。 -## 6. 线路关系 +## 7. 线路关系 ```mermaid flowchart LR