# Astrion `server/` 196 个 API 端点职责分类盘点报告

> 任务：运行时边界整理（Gateway/RuntimeService）前置普查 —— 回答「196 个端点里到底有多少需要动」。
> 分析方法：只读代码分析（grep 全部 `@<bp>.route` 装饰器后逐个读取端点函数体），未修改任何文件。
> 统计口径：以 Flask 路由注册（Methods 合并计数）为准，共 **196** 个，与已知分布完全一致（逐文件核验过）。

---

## 0. 结论速览（先给答案）

| 类别 | 数量 | 占 196 的比例 | 是否要动 |
|---|---|---|---|
| **T1 任务受理**（创建/启动一轮 Agent 任务） | **3** | **1.5%** | ✅ 必须迁移到 RuntimeService 公共入口 |
| **T2 任务控制**（取消/停止/审批回答/提问回答） | **13** | **6.6%** | ✅ 必须迁移（收敛为公共控制接口） |
| **T3 任务观察**（轮询状态/事件流 idx/offset） | **14** | **7.1%** | ⚠️ 可不迁移：只读 REST 语义，HTTP 适配层保留即可 |
| **C CRUD**（会话/工作区/配置/文件/页面） | **131** | **66.8%** | ❌ 不动 |
| **S 状态查询**（系统状态/git/docker/usage） | **20** | **10.2%** | ❌ 不动 |
| **A 认证管理**（登录/token/用户/API 用户） | **15** | **7.7%** | ❌ 不动 |
| **合计** | **196** | 100% | — |

**核心答案：真正需要「Gateway 化」的最低必要集合 = T1 + T2 = 16 个端点，占 196 的 8.2%。**
若把任务观察（T3，共享事件流读取协议）也纳入公共接口设计边界，则为 30 个端点（15.3%），
但 T3 中绝大多数只是读内存任务记录/磁盘状态，**可以不动**——观察类本来就是 REST 语义本身，
Gateway 只需在 T1 受理时返回 task_id，CLI/定时任务各自复用 T3 的轮询协议即可。

> **审阅注释（2026-09-07｜R1 范围）**：此分类用于估算 HTTP 改动面，不能据此判断运行时职责是否已经收敛。保留查询端点/轮询协议与提供内部查询接口不冲突；定时触发器不应被迫通过 HTTP 才能观察任务。迁移完成标准应来自状态责任表和调用链验收，而非固定端点数量。

10 个 socketio 事件中，与任务运行耦合的仅 2 个：`send_message`（T1，已废弃短路）与 `stop_task`（T2）。

---

## 1. 分类统计总表

### 1.1 类别 × 数量 × 文件分布

| 类别 | 数量 | 分布（文件：数量） |
|---|---|---|
| **T1 任务受理** | 3 | api_v1.py:1，tasks/api.py:1，workflow_runtime_api.py:1 |
| **T2 任务控制** | 13 | tasks/api.py:5，conversation.py:3，chat/approval.py:3，api_v1.py:1，workflow_runtime_api.py:1 |
| **T3 任务观察** | 14 | conversation.py:4，tasks/api.py:3，chat/approval.py:3，api_v1.py:1，workflow_runtime_api.py:1，multi_agent.py:1，conversation_bootstrap.py:1 |
| **C CRUD** | 131 | conversation.py:26，api_v1.py:19，admin.py:17，multi_agent.py:11，chat/permission.py:10，workflow_page.py:6，status/host_workspace.py:6，chat/settings.py:5，files.py:5，status/docker.py:5，status/file_open.py:4，chat/files.py:3，chat/misc.py:2，status/sandbox.py:1，status/app.py:1，auth.py:7，app_legacy.py:2，tasks/skills.py:1 |
| **S 状态查询** | 20 | status/base.py:4，status/git.py:2，status/sandbox.py:2，chat/misc.py:3，status/docker.py:1，status/app.py:1，usage.py:1，admin.py:3，auth.py:1，api_v1.py:1，chat/terminal.py:1 |
| **A 认证管理** | 15 | auth.py:8，admin.py:6，chat/terminal.py:1 |
| **合计** | **196** | 26 个文件（与任务给定的分布完全一致） |

### 1.2 按文件展开

| 文件 | 总数 | T1 | T2 | T3 | C | S | A |
|---|---|---|---|---|---|---|---|
| conversation.py | 33 | 0 | 3 | 4 | 26 | 0 | 0 |
| admin.py | 26 | 0 | 0 | 0 | 17 | 3 | 6 |
| api_v1.py | 23 | 1 | 1 | 1 | 19 | 1 | 0 |
| auth.py | 16 | 0 | 0 | 0 | 7 | 1 | 8 |
| multi_agent.py | 12 | 0 | 0 | 1 | 11 | 0 | 0 |
| chat/permission.py | 10 | 0 | 0 | 0 | 10 | 0 | 0 |
| tasks/api.py | 9 | 1 | 5 | 3 | 0 | 0 | 0 |
| workflow_page.py | 6 | 0 | 0 | 0 | 6 | 0 | 0 |
| status/host_workspace.py | 6 | 0 | 0 | 0 | 6 | 0 | 0 |
| status/docker.py | 6 | 0 | 0 | 0 | 5 | 1 | 0 |
| chat/approval.py | 6 | 0 | 3 | 3 | 0 | 0 | 0 |
| files.py | 5 | 0 | 0 | 0 | 5 | 0 | 0 |
| chat/settings.py | 5 | 0 | 0 | 0 | 5 | 0 | 0 |
| chat/misc.py | 5 | 0 | 0 | 0 | 2 | 3 | 0 |
| status/file_open.py | 4 | 0 | 0 | 0 | 4 | 0 | 0 |
| status/base.py | 4 | 0 | 0 | 0 | 0 | 4 | 0 |
| workflow_runtime_api.py | 3 | 1 | 1 | 1 | 0 | 0 | 0 |
| status/sandbox.py | 3 | 0 | 0 | 0 | 1 | 2 | 0 |
| chat/files.py | 3 | 0 | 0 | 0 | 3 | 0 | 0 |
| status/git.py | 2 | 0 | 0 | 0 | 0 | 2 | 0 |
| status/app.py | 2 | 0 | 0 | 0 | 1 | 1 | 0 |
| chat/terminal.py | 2 | 0 | 0 | 0 | 0 | 1 | 1 |
| app_legacy.py | 2 | 0 | 0 | 0 | 2 | 0 | 0 |
| usage.py | 1 | 0 | 0 | 0 | 0 | 1 | 0 |
| tasks/skills.py | 1 | 0 | 0 | 0 | 1 | 0 | 0 |
| conversation_bootstrap.py | 1 | 0 | 0 | 1 | 0 | 0 | 0 |
| **合计** | **196** | **3** | **13** | **14** | **131** | **20** | **15** |

---

## 2. T1 / T2 / T3 类端点详细清单

> 内部调用均指**端点函数体最终触达的运行时函数**。所有任务受理/控制最终收敛到
> `server/tasks/models.py` 的单例 `task_manager`（TaskManager）：
> `create_chat_task` 创建 TaskRecord 并 spawn 后台线程 `_run_chat_task` → `chat_flow.run_chat_task_sync` 执行；
> 控制类调 `cancel_task / enqueue_runtime_guidance / enqueue_runtime_pending_message / remove_runtime_pending_message / promote_runtime_pending_to_guidance`；
> 观察类调 `get_task / get_events_since / list_tasks / get_conversation_running_status`。
> 这正是「公共任务入口（RuntimeService）」要收敛的核心面。

### 2.1 T1 任务受理类（3 个）—— 必须 Gateway 化

| # | 路径 | 方法 | 文件:行 | 内部调用 | 迁移复杂度 |
|---|---|---|---|---|---|
| T1-1 | `/api/tasks` | POST | tasks/api.py:111 `create_task_api` | `task_manager.create_chat_task(...)`（前置：goal 状态清理、`_build_skill_context_messages` 技能上下文构建、conversation 补建、`_normalize_media/files_payload` 媒体归一化） | **中**：受理本身已是 task_manager 薄封装，但 HTTP 层有 ~100 行参数归一化/技能上下文/补建对话逻辑可下沉给 RuntimeService 统一处理（CLI/定时任务同样需要） |
| T1-2 | `/api/v1/workspaces/<id>/messages` | POST | api_v1.py:254 `send_message_api` | `ensure_conversation_loaded` + prompt/personalization 应用到 `terminal.context_manager` + `apply_personalization_preferences` + `task_manager.create_chat_task(...)` | **中**：prompt/personalization 文件校验与应用属于 HTTP 适配层职责（可保留），核心受理改为调用 RuntimeService |
| T1-3 | `/api/workflow/activate` | POST | workflow_runtime_api.py:38 `api_activate_workflow` | `activate_workflow()`（modules/workflow_flow）→ `try_acquire_main_task_gate` 门闸 → `task_manager.create_chat_task(..., message_source="workflow", session_data=含 gate_token)` | **大**：工作流激活语义（会话补建/模式继承/msg_index 游标）+ 主任务门闸 token 移交任务线程，逻辑最重；建议 HTTP 层保留状态机编排，仅把 `create_chat_task` 调用统一切到 RuntimeService 入口 |

### 2.2 T2 任务控制类（13 个）—— 必须 Gateway 化

| # | 路径 | 方法 | 文件:行 | 内部调用 | 迁移复杂度 |
|---|---|---|---|---|---|
| T2-1 | `/api/tasks/<task_id>/cancel` | POST | tasks/api.py:284 `cancel_task_api` | `task_manager.cancel_task()` + `GoalStateManager.mark_stopped(REASON_USER_CANCEL)` 停止对话残留目标 | **小** |
| T2-2 | `/api/v1/tasks/<task_id>/cancel` | POST | api_v1.py:444 `cancel_task_api_v1` | `task_manager.cancel_task()` | **小** |
| T2-3 | `/api/tasks/<task_id>/runtime_guidance` | POST | tasks/api.py:305 `enqueue_runtime_guidance_api` | `task_manager.enqueue_runtime_guidance()`（向运行中任务注入引导消息） | **小** |
| T2-4 | `/api/tasks/<task_id>/runtime_queue` | POST | tasks/api.py:333 `enqueue_runtime_queue_message_api` | `task_manager.enqueue_runtime_pending_message()`（运行中追问入队） | **小** |
| T2-5 | `/api/tasks/<task_id>/runtime_queue/<message_id>` | DELETE | tasks/api.py:361 `delete_runtime_queue_message_api` | `task_manager.remove_runtime_pending_message()` | **小** |
| T2-6 | `/api/tasks/<task_id>/runtime_queue/<message_id>/guide` | POST | tasks/api.py:383 `guide_runtime_queue_message_api` | `task_manager.promote_runtime_pending_to_guidance()` | **小** |
| T2-7 | `/api/workflow/deactivate` | POST | workflow_runtime_api.py:210 `api_deactivate_workflow` | `deactivate_workflow_by_user()`；若池中有通知且门闸空闲则再 `task_manager.create_chat_task(...)` 派发一轮 | **中**：控制 + 条件受理二合一，建议保留编排、收敛 Task 调用 |
| T2-8 | `/api/sub_agents/stop_all` | POST | conversation.py:2059 `stop_all_sub_agents` | `sub_agent_manager.soft_stop_all_agents()` / `sub_agent_manager.terminate_sub_agent()`（多智能体软停 / 传统模式终结） | **小** |
| T2-9 | `/api/sub_agents/<task_id>/terminate` | POST | conversation.py:2108 `terminate_sub_agent` | `sub_agent_manager.terminate_sub_agent(task_id=...)` | **小** |
| T2-10 | `/api/background_commands/<command_id>/cancel` | POST | conversation.py:2222 `cancel_background_command` | `background_command_manager.cancel_command(command_id)` | **小** |
| T2-11 | `/api/user-questions/<question_id>/answer` | POST | chat/approval.py:63 `answer_user_question` | `user_question_manager.answer(...)`（回答喂回运行中任务工具循环） | **小** |
| T2-12 | `/api/plan-approvals/<approval_id>/answer` | POST | chat/approval.py:107 `answer_plan_approval` | `plan_approval_manager.answer(...)`（计划通过后工具循环切 execute 模式） | **小** |
| T2-13 | `/api/tool-approvals/<approval_id>/decision` | POST | chat/approval.py:150 `decide_tool_approval` | `tool_approval_manager.decide(...)` | **小** |

### 2.3 T3 任务观察类（14 个）—— 可不迁移（只读，HTTP 适配层保留）

| # | 路径 | 方法 | 文件:行 | 内部调用 | 迁移复杂度 |
|---|---|---|---|---|---|
| T3-1 | `/api/tasks` | GET | tasks/api.py:34 `list_tasks_api` | `task_manager.list_tasks()`（任务列表/状态过滤） | 小（不需迁移） |
| T3-2 | `/api/conversations/<cid>/running-status` | GET | tasks/api.py:56 | `task_manager.get_conversation_running_status()` 聚合主任务+子智能体+后台命令+多智能体 | 小 |
| T3-3 | `/api/tasks/<task_id>` | GET | tasks/api.py:229 `get_task_api` | `task_manager.get_task()` + `get_events_since(rec, offset)`（**事件流 idx/offset 轮询协议**） | 小 |
| T3-4 | `/api/v1/tasks/<task_id>` | GET | api_v1.py:415 `get_task_events` | `task_manager.get_task()` + `get_events_since(rec, offset)`（同一协议） | 小 |
| T3-5 | `/api/workflow/status` | GET | workflow_runtime_api.py:295 | `WorkflowStateManager.progress_snapshot()` | 小 |
| T3-6 | `/api/sub_agents` | GET | conversation.py:1892 `list_sub_agents` | `sub_agent_manager.get_overview()` + 通知去重计算 | 小 |
| T3-7 | `/api/sub_agents/<task_id>/activity` | GET | conversation.py:2001 | 读 `progress.jsonl` 活动记录（含 limit 上限） | 小 |
| T3-8 | `/api/background_commands` | GET | conversation.py:2139 | `background_command_manager.list_records()` | 小 |
| T3-9 | `/api/background_commands/<command_id>` | GET | conversation.py:2184 | `background_command_manager.get_record_with_output()`（实时输出） | 小 |
| T3-10 | `/api/user-questions/pending` | GET | chat/approval.py:48 | `user_question_manager.list_pending()` | 小 |
| T3-11 | `/api/plan-approvals/pending` | GET | chat/approval.py:92 | `plan_approval_manager.list_pending()` | 小 |
| T3-12 | `/api/tool-approvals/pending` | GET | chat/approval.py:135 | `tool_approval_manager.list_pending()` | 小 |
| T3-13 | `/api/multiagent/active_sub_agents` | GET | multi_agent.py:483 | `sub_agent_manager.get_multi_agent_state()`（子智能体实例+token 统计） | 小 |
| T3-14 | `/api/conversations/<cid>/bootstrap` | GET | conversation_bootstrap.py:146 | 聚合 meta+messages+`task_manager.get_conversation_running_status()`+task_replay（纯只读） | 小 |

---

## 3. socketio 事件盘点（10 个）

| # | 事件 | 文件:行 | 职责 | 分类 |
|---|---|---|---|---|
| S1 | `connect` | socket_handlers.py:24 | socket_token 握手鉴权、绑定 user/terminal | A |
| S2 | `disconnect` | socket_handlers.py:76 | 清理 sid→user 映射、stop flag 生命周期 | A |
| S3 | `stop_task` | socket_handlers.py:128 | 置 sid 级 stop flag，指挥运行中任务停流（唯一 WS 任务控制通道） | **T2** |
| S4 | `terminal_subscribe` | socket_handlers.py:152 | 订阅真实终端输出流 | S/C |
| S5 | `terminal_unsubscribe` | socket_handlers.py:198 | 取消订阅 | S/C |
| S6 | `get_terminal_output` | socket_handlers.py:211 | 拉取终端输出片段 | S |
| S7 | `send_message` | socket_handlers.py:240 | **WS 聊天入口（已废弃）**：函数体已短路返回 `DEPRECATED`，死代码保留紧急回退（原路径：`start_chat_task` → 任务线程）；任务受理已全部改走 REST `/api/tasks` | **T1（废弃）** |
| S8 | `client_chunk_log` | socket_handlers.py:372 | 前端分块渲染日志上报（限流写盘） | C |
| S9 | `client_stream_debug_log` | socket_handlers.py:386 | 前端流调试日志上报 | C |
| S10 | `send_command` | conversation.py:2462 | 系统命令 `clear/status/terminals`（只读/清空历史，无 Agent 执行）；REST 对应 `/api/commands` | C |

**WS 侧结论**：10 个事件中仅 `stop_task`（T2，活跃）与 `send_message`（T1，已废弃）与任务运行时耦合，且 `send_message` 已是死代码。
事件流观察（task/terminal output）由 WS 直接转发 HTTP 轮询结果，无需 Gateway 化。

---

## 4. 结论：真正需要「Gateway 化」的端点占比与理由

### 4.1 数字结论

- **必须迁移到 RuntimeService 公共入口（受理 + 控制）= T1(3) + T2(13) = 16 个 = 8.2%**
  - 其中 T1 仅 **3 个（1.5%）**：`POST /api/tasks`、`POST /api/v1/.../messages`、`POST /api/workflow/activate`。
  - 这 16 个端点的函数体**最终都调用同一批 task_manager / sub_agent_manager / background_command_manager / approval 方法**，
    即「运行时控制面」已经收敛在几个单例方法上——Gateway 化的实质就是把这几个方法提升为 RuntimeService 的公共入口，
    Web / CLI / 定时任务复用，HTTP 端点从「直接调 manager」改为「调 RuntimeService」。
- **可迁移但不强制 = T3(14) = 7.1%**：纯只读。轮询协议（task_id + from/offset + events）本身就是 REST 语义，
  CLI/定时任务可直接复用相同协议，HTTP 适配层保留即可；未来若要统一查询接口可让 RuntimeService 暴露 `get_task_events`，但**不是本次改造的必要条件**。
- **完全不需要动 = C(131) + S(20) + A(15) = 166 = 84.7%**：CRUD、状态查询、认证管理与 Agent 运行时零耦合。

> **审阅注释（2026-09-07｜R1 配置耦合）**：“零耦合”与下文灰区说明不一致。窄核验确认 `server/chat/permission.py:166–185`、`:265–284`、`:352–368` 分别排队修改运行中的权限、执行环境和网络权限；work-mode 则在 `:420–445` 拒绝运行中切换。可保留 HTTP 路由，但这些状态修改/校验规则需要明确归属。建议理解为“多数无需改动外部接口，涉及运行态的内部调用按契约评审”，不是排除在运行时审查之外。

### 4.2 剩余 166 个端点为何可以不动

1. **C（131）**：会话/工作区/文件/配置/工作流定义/多智能体角色与设置的增删改查，全部是磁盘读写 + terminal 状态读写，
   不触发、不控制、不观察任何 Agent 任务执行。典型如 `POST /api/conversations`（有活跃任务时只建视图文件，不启动任务）、
   `POST /api/multiagent/conversations`（仅建对话并写 metadata，不发派 agent）、`PUT /api/workflows/<name>`（WORKFLOW.md 落盘）。
   唯一接近灰区的是 `POST /api/conversations/<id>/compress`（深层压缩会同步 `asyncio.run(run_deep_compression)` 调用 LLM，
   但**不创建 task_manager 任务、不经事件流、无状态轮询**，属于 HTTP 层可同步执行的对话维护操作，判定为 C 并建议改造时单独评审）。
2. **S（20）**：status/docker/git/usage/sandbox/health 等只读查询，返回宿主环境与系统状态，与任务运行时无关。
3. **A（15）**：登录/注册/CSRF/socket-token/API 用户管理/二级口令，纯认证域。
4. **页面/静态路由**（已计入 C）：`/`、`/new`、`/workflows`、`/multiagent/*`、`/admin/*` 等 17 个 SPA 入口与静态资源路由，只是 `send_static_file`。
5. **灰区说明（已统计进 C）**：`chat/permission.py` 的 3 个模式切换 POST（permission-mode / execution-mode / network-permission）在任务运行期间会把切换**入队（queue_permission_mode_change 等 pending 机制）**由工具循环消费，对运行中任务有延迟影响；但它们的本质是**配置写入**（空闲时立即生效、运行中排队后生效），与「取消/停止/审批」这类任务控制操作性质不同，故判 C。若 RuntimeService 需要支持「运行中改权限」，仅需把这 3 个方法也纳入公共入口的可选能力，不构成本次改造的必要条件。

### 4.3 改造建议要点（基于分类的推论）

- RuntimeService 首批公共方法最小集：`create_task(受理)`、`cancel_task`、`enqueue_runtime_guidance`、`enqueue_runtime_pending_message(+remove/promote)`、
  以及可选的 `get_task_events`（观察，供 CLI 复用）。
- `chat/approval.py` 的 3 个 answer/decision（T2）与 `conversation.py` 的 3 个 stop/terminate/cancel（T2）走同一批 manager 方法，
  属于同一控制面，建议一并收敛（或至少让 CLI 具备「提交审批答复」能力时复用）。
- workflow 激活/停用的状态机编排（门闸 token、会话补建、通知派发）建议保留在 HTTP 层，只下沉 Task 创建调用，控制迁移风险。

> **审阅注释（2026-09-07｜R2 过渡边界）**：认可作为分步迁移手段。长期职责应让工作流服务承接激活、会话补建、门闸移交与失败回滚，HTTP 只解析请求和映射响应；若暂不迁移，应标注剩余兼容依赖。同样，API 入口中的模型/偏好应用等业务规则是否留在路由，应以非 HTTP 调用是否需要复用来判断。

### 4.4 方法与口径声明

- 全部 196 个端点经 `grep -E "@[a-zA-Z_]+\.route"` 逐文件提取并核对数量（26 文件合计 196，与任务给定的分布逐文件一致）。
- 分类依据为端点函数体实际行为（阅读每一处路由函数），非凭路径猜——凡能触发 `task_manager.create_chat_task` / 后台线程 / 任务控制方法者才归入 T1/T2。
- WS 侧 `send_message` 已确认函数体首行即短路返回废弃提示，其 T1 归类基于历史职责（死代码保留的回退分支），已单独标注。