feat(agent): complete closed-loop runtime and pricing fallback

2026-03-05 15:34:37 +08:00
parent b02a322bf3
commit b486e78ff3
67 changed files with 3832 additions and 7 deletions
@@ -786,6 +786,86 @@

 ---

+## Agent Runtime
+
+### POST /agent/runs
+
+创建一次 Agent 异步运行任务（需要认证）。
+
+**Request:**
+```json
+{
+  "session_id": "string? (optional, 为空时自动创建会话)",
+  "prompt": "string (1-5000 chars)"
+}
+```
+
+**Response:** 202 Accepted
+```json
+{
+  "task_id": "string",
+  "session_id": "string",
+  "created": true
+}
+```
+
+**Errors:**
+- 401: 未认证
+- 403: 非会话 owner
+- 422: 请求参数无效
+
+---
+
+### POST /agent/runs/{session_id}/resume
+
+恢复一次等待工具结果的 Agent 运行（需要认证）。
+
+**Request:**
+```json
+{
+  "tool_call_id": "string"
+}
+```
+
+**Response:** 202 Accepted
+```json
+{
+  "task_id": "string",
+  "session_id": "string",
+  "created": false
+}
+```
+
+**Errors:**
+- 401: 未认证
+- 403: 非会话 owner
+- 422: 请求参数无效
+
+---
+
+### GET /agent/runs/{session_id}/events
+
+订阅 Agent SSE 事件流（需要认证）。
+
+**Headers:**
+- `Last-Event-ID` (optional): 断点续传游标
+
+**Response:** 200 OK
+`Content-Type: text/event-stream`
+
+```text
+id: 2-0
+event: RUN_STARTED
+data: {"session_id":"..."}
+
+```
+
+**Errors:**
+- 401: 未认证
+- 403: 非会话 owner
+
+---
+
 ## Infra

 ### GET /infra/health
@@ -173,6 +173,29 @@ curl -sS "${WEB_BASE_URL}/api/v1/profile/me" \
 - 定位：检查 `worker-*` tmux 窗口和对应日志文件。
 - 修复：重启 tmux 会话，确认并发配置与队列名（critical/default/bulk）。

+### 2.1) Agent Runtime run/resume 事件不闭环
+
+- 症状：`POST /api/v1/agent/runs` 返回 202，但前端事件流没有 `RUN_FINISHED`。
+- 定位步骤：
+
+```bash
+# 1) 检查 celery worker 是否消费 agent 任务
+grep -E "tasks\.agent\.run_command|RUN_STARTED|RUN_FINISHED|RUN_ERROR" logs/worker-default.log
+
+# 2) 检查 API SSE 事件读取（带 Last-Event-ID）
+curl -N "${WEB_BASE_URL}/api/v1/agent/runs/<session_id>/events" \
+  -H "Authorization: Bearer <access_token>" \
+  -H "Last-Event-ID: 1-0"
+
+# 3) 检查 Redis 连通（必要时）
+docker compose --env-file .env -f infra/docker/docker-compose.yml exec -T redis redis-cli ping
+```
+
+- 修复建议：
+  - 若 worker 无消费：重启 `worker-default` 窗口并确认 `core.agent.infrastructure.queue.tasks` 已被 Celery include。
+  - 若 worker 有事件但 API 无输出：排查 Redis stream 前缀配置与 session_id 是否一致。
+  - 若出现 `RUN_ERROR`：按 error_id 回查后端日志，不在 API/SSE 中暴露敏感上下文。
+
 ### 3) JWT 或认证异常

 - 症状：接口持续 401/403。
@@ -247,3 +270,4 @@ docker compose --env-file .env -f infra/docker/docker-compose.yml up -d --force-
 | 2026-02-28 | 邀请码功能：新增 invite_codes 表、profiles.referred_by，注册时可选填邀请码并记录邀请关系 |
 | 2026-03-02 | 文档整理：修正 auth 端点名称（/verifications）、补充 profile 路由文档、修复 L2/L3 验证命令 |
 | 2026-03-02 | 修正 bootstrap 命令：init-job 需要使用 `uv run python -m core.runtime.cli bootstrap` |
+| 2026-03-05 | 新增 Agent Runtime run/resume/events 运维排障流程（Celery + Redis + Last-Event-ID） |