# Terminal MCP 治理与确认机制外包实施任务书（2026-03-19）

> 生效日期：2026-03-19
> 文档类型：外包实施规格 + 开发任务书 + 验收清单
> 适用团队：外包开发团队、外包测试团队、内部技术验收团队
> 适用范围：`/terminal/` 页面、`/api/terminal/`、`/api/prompt/chat*`、terminal 命令配置与命令执行链路
> 环境边界：仅开发/测试环境，禁止接入生产权限或真实高风险执行通道

---

## 1. 背景与目标

当前 terminal 模块存在以下问题：

1. 前端仍调用旧路径，terminal 初始化、聊天、命令执行链路不稳定。
2. terminal 动态命令与 MCP/tool/API 能力混在一起，但没有统一的权限模型。
3. 现有 `mcp_enabled` 仅限制 Token 鉴权，不限制网页登录态 terminal。
4. 写操作没有 CLI 风格二次确认，也没有统一的审计闭环。
5. 命令配置页和命令 CRUD 权限过宽，不符合“操作终端”定位。

本任务书目标是把 terminal 改造成一个可验收、可审计、可分级授权的操作终端。

本期必须完成：

1. 修复 terminal 前端调用链，统一到现有后端真实路由。
2. 建立 terminal 命令风险分级与权限模型。
3. 建立右侧模式切换：`只读`、`逐次确认`、`自动确认`。
4. 建立 CLI 风格确认流程，不允许用弹窗替代。
5. 让 `mcp_enabled` 真正生效到网页登录态 terminal。
6. 建立 terminal 操作审计日志与最小可用查询能力。
7. 收紧 terminal 命令配置页与 CRUD 到 staff/admin。

本期明确不做：

1. 多人审批流。
2. 全自动生产执行。
3. 新引入第三方 workflow 引擎。
4. 新建与本任务无关的大规模架构重构。

---

## 2. 范围与边界

### 2.1 In Scope

1. `static/js/terminal.js` 的 terminal 初始化、聊天、provider/model、命令加载、命令执行链路。
2. `apps/terminal` 的页面视图、API、命令模型、执行服务、仓储、权限控制。
3. terminal 命令配置页及对应 CRUD API。
4. `mcp_enabled` 在网页登录态 terminal 的接入。
5. terminal 右侧操作模式区与 CLI 确认交互。
6. terminal 审计日志、后端确认 token、最小测试与验收脚本。

### 2.2 Out of Scope

1. 其他业务模块的业务逻辑重构。
2. prompt chat 的通用产品形态重做。
3. MCP SDK Token 管理页改版。
4. 生产部署与运维脚本改造。

### 2.3 强边界

1. 外包团队不得自行改变 `mcp_enabled` 语义。
2. 外包团队不得把“前端模式切换”当作安全控制，后端必须强制校验。
3. 外包团队不得用弹窗替代 CLI 确认。
4. 外包团队不得将风险分级自动推导为最终规则；配置值为主，HTTP method 只能作为兜底校验。
5. 外包团队不得把写操作隐藏进聊天入口。

---

## 3. 目标态定义

### 3.1 Terminal 运行模式

terminal 右侧必须提供以下三种模式：

1. `只读`
2. `逐次确认`
3. `自动确认`

模式定义如下：

| 模式 | read | write_low | write_high | admin |
| --- | --- | --- | --- | --- |
| 只读 | 允许 | 禁止 | 禁止 | 禁止 |
| 逐次确认 | 允许 | 需 CLI 二次确认 | 需 CLI 二次确认 | 需 CLI 二次确认且必须 staff/admin |
| 自动确认 | 允许 | 直接执行 | 直接执行 | 直接执行前仍必须通过 staff/admin 后端角色校验 |

说明：

1. `自动确认` 是终端交互模式，不是权限提升模式。
2. 普通用户即使切到 `自动确认`，也不能执行 `admin` 命令。
3. 若用户 `mcp_enabled=false`，terminal 只能停留在 `只读`，且动态命令不可执行。

### 3.2 命令风险分级

所有 terminal 动态命令必须落在以下四级之一：

1. `read`
2. `write_low`
3. `write_high`
4. `admin`

分级语义：

1. `read`：只读查询，不改变系统状态。
2. `write_low`：低风险写操作，可恢复、范围有限。
3. `write_high`：高风险写操作，可能影响关键配置、账户、状态流转或批量数据。
4. `admin`：仅 staff/admin 可执行的运维或治理类命令。

默认要求：

1. 新增动态命令如果未显式标注风险级别，不允许执行。
2. 已有命令全部补齐风险级别。
3. 命令风险级别必须体现在命令配置模型、API 返回和前端展示中。

### 3.3 MCP 开关生效规则

当 `request.user.account_profile.mcp_enabled=false` 时：

1. terminal 页面仍可打开。
2. 纯聊天仍可使用。
3. terminal 动态命令不加载，或加载后全部标记不可用。
4. `/api/terminal/commands/available/` 仅返回可用的内建只读命令或空列表。
5. `/api/terminal/commands/execute_by_name/` 对动态命令执行直接拒绝。
6. 右侧模式锁定为 `只读`，并显示 MCP 已关闭的说明。

---

## 4. 实施总拆分

建议拆成 5 个任务包，允许并行，但必须按依赖顺序合并。

### WP-01 路由与调用链修复

目标：先让 terminal 当前主链路可稳定访问。

任务：

1. 修复 terminal 前端所有旧路径调用。
2. 修复 terminal 配置页仍引用旧 terminal API 的问题。
3. 统一 terminal 前端请求入口，避免后续权限逻辑散落。
4. 保证 provider/model/chat/commands/execute 全链路走现有真实后端路由。

交付物：

1. 修复后的 API 路径对照表。
2. terminal 初始化和聊天链路通过截图/录屏。
3. 路由一致性测试。

验收标准：

1. terminal 页面打开后不出现旧路径 404。
2. 动态命令列表可加载。
3. 聊天、provider、model 切换可正常工作。

### WP-02 命令治理模型与后端权限

目标：建立 terminal 的后端治理骨架。

任务：

1. 在 terminal 命令模型中新增治理字段：
   - `risk_level`
   - `requires_mcp`
   - `enabled_in_terminal`
2. 为已有命令补齐治理字段迁移和数据回填策略。
3. 新增统一权限校验服务，供 terminal 执行入口调用。
4. 收紧 terminal 命令 CRUD 和配置页权限到 staff/admin。
5. 统一 `available` 接口过滤规则，只返回当前用户有权看到的命令。

交付物：

1. 数据模型变更说明。
2. 迁移脚本与回填策略。
3. 权限矩阵表。

验收标准：

1. 普通用户无法访问 terminal 命令配置页。
2. 普通用户无法调用 terminal 命令 CRUD。
3. 不同用户看到的命令列表按权限正确过滤。

### WP-03 右侧模式与 CLI 确认

目标：把“只读/逐次确认/自动确认”落到产品交互和后端确认协议。

任务：

1. 右侧增加 terminal 操作模式区和风险提示区。
2. terminal 前端增加状态机：
   - `normal`
   - `pending_params`
   - `pending_confirmation`
3. 对需确认命令，第一次执行不落地，返回确认提示和后端签发的一次性 `confirmation_token`。
4. 用户在 terminal 输入明确确认词后，再次提交执行。
5. 用户输入取消词时，应终止确认流程并回到普通输入态。
6. 禁止使用浏览器弹窗、模态框、原生 confirm。

确认协议强制要求：

1. `confirmation_token` 必须绑定用户、命令名、参数摘要、风险级别、模式、过期时间。
2. token 一次性使用，重复提交必须失败。
3. token 过期必须失败。
4. 参数改动后旧 token 失效。
5. 后端必须再次检查用户角色和 `mcp_enabled`。

CLI 确认文案必须包含：

1. 命令名
2. 风险级别
3. 参数摘要
4. 当前模式
5. 明确确认词
6. 取消方式

交付物：

1. CLI 确认交互说明。
2. 确认协议文档。
3. 关键截图或录屏。

验收标准：

1. `逐次确认` 模式下，写命令首次不会直接落地。
2. 输入确认词后执行成功，输入取消词后不执行。
3. token 篡改、过期、重复使用、参数变化全部失败。

### WP-04 MCP 开关接入与审计

目标：让网页登录态 terminal 真正受 `mcp_enabled` 控制，并补齐操作审计。

任务：

1. 在 terminal 执行 API 上接入 `mcp_enabled` 检查。
2. 在动态命令列表 API 上接入 `mcp_enabled` 过滤。
3. 在 terminal 页面初始化配置里返回当前用户 terminal 能力快照：
   - `mcp_enabled`
   - `available_modes`
   - `current_mode`
   - `role`
4. 新增 terminal 操作审计模型或在现有审计体系中增加 terminal 专属记录结构。
5. 记录成功、失败、取消、确认超时等状态。

审计最小字段要求：

1. `user_id`
2. `username`
3. `session_id`
4. `command_name`
5. `risk_level`
6. `mode`
7. `params_summary`
8. `confirmation_required`
9. `confirmation_status`
10. `result_status`
11. `error_message`
12. `duration_ms`
13. `created_at`

交付物：

1. 审计字段定义。
2. 审计查询示例。
3. MCP 开关接入说明。

验收标准：

1. `mcp_enabled=false` 时终端动态命令不可执行。
2. 纯聊天仍可正常使用。
3. 每次动态命令执行都产生审计记录。

### WP-05 测试、文档与验收资产

目标：保证外包交付可重复验证，不接受“手工点过没问题”。

任务：

1. 补齐后端权限测试、确认 token 测试、路由契约测试。
2. 补齐前端 terminal 关键流程测试。
3. 输出 terminal 权限矩阵、模式矩阵、命令分级清单。
4. 输出交付说明、回归清单、已知限制。

交付物：

1. 自动化测试代码。
2. 回归脚本与执行记录。
3. 风险矩阵与命令分级清单。
4. 最终交付报告。

验收标准：

1. 所有强制测试通过。
2. 交付说明完整。
3. 内部验收团队可按文档直接复现。

---

## 5. 接口契约（外包必须按此实现）

## 5.1 Terminal 命令列表接口

接口：`GET /api/terminal/commands/available/`

响应最小字段必须包含：

1. `name`
2. `description`
3. `type`
4. `category`
5. `parameters`
6. `risk_level`
7. `requires_mcp`
8. `confirmation_required`
9. `terminal_enabled`

行为要求：

1. 只能返回当前用户可见且可在 terminal 暴露的命令。
2. 不得把 `admin` 命令暴露给普通用户。
3. 当 `mcp_enabled=false` 时，不返回需 MCP 的动态命令。

## 5.2 Terminal 命令执行接口

接口：`POST /api/terminal/commands/execute_by_name/`

第一次请求最小输入：

1. `name`
2. `params`
3. `session_id`
4. `mode`

第一次响应有两种结果：

1. 直接执行成功/失败
2. 返回确认请求

当需要确认时，响应最小字段必须包含：

1. `success=false`
2. `confirmation_required=true`
3. `confirmation_token`
4. `confirmation_prompt`
5. `command_summary`
6. `risk_level`

二次确认请求最小输入：

1. `name`
2. `params`
3. `session_id`
4. `mode`
5. `confirmation_token`
6. `confirmation_input`

二次确认行为要求：

1. 后端重新校验 token、用户、参数、角色、MCP 权限。
2. 校验通过才真正执行。
3. 失败返回明确错误码或可识别错误信息。

## 5.3 Terminal 页面初始化能力快照

可通过现有 session 接口扩展，或新增轻量接口。

最小返回项：

1. `mcp_enabled`
2. `role`
3. `available_modes`
4. `current_mode`
5. `reason_if_locked`

目的：

1. 让前端据此锁定右侧模式。
2. 避免前端自行猜测权限。

---

## 6. 关键实现规则

## 6.1 前端规则

1. 所有请求路径统一走真实后端路由，不允许保留旧 `/api/prompt/terminal/*` 和 `/prompt/api/*`。
2. CLI 确认必须在 terminal 输出区呈现，不得出现弹窗。
3. 参数收集与确认收集必须是两个不同状态，不能互相覆盖。
4. 切换模式后，只影响后续命令，不应篡改已签发的确认 token。
5. 输出区要清楚标识风险级别和当前模式。

## 6.2 后端规则

1. 权限控制必须在 API 层和执行层都做，不接受仅前端拦截。
2. 命令是否可执行由后端最终裁定。
3. `admin` 命令必须绑定 staff/admin 身份校验。
4. 审计必须在成功与失败路径都落记录。
5. 命令风险级别缺失时默认拒绝执行，不允许默认降级为 `read`。

## 6.3 数据迁移规则

1. 需要新增迁移为已有命令补齐治理字段。
2. 迁移必须提供默认回填策略。
3. 回填策略必须在文档中写明。
4. 若无法自动判定已有命令级别，宁可默认收紧，不允许默认放开。

---

## 7. 测试计划（外包必须交付）

## 7.1 后端测试

至少覆盖以下场景：

1. terminal 命令列表按用户权限过滤。
2. 普通用户不能看到 `admin` 命令。
3. `mcp_enabled=false` 时动态命令不可见或不可执行。
4. `read` 命令在三种模式下都能执行。
5. `write_low` 在 `只读` 模式被拒绝。
6. `write_low` 在 `逐次确认` 模式首次返回确认请求。
7. `write_low` 在 `自动确认` 模式直接执行。
8. `write_high` 的确认流程与审计记录完整。
9. `admin` 命令对普通用户拒绝，对 staff/admin 放行。
10. `confirmation_token` 过期、重复、篡改、参数变化时全部失败。

## 7.2 前端测试

至少覆盖以下场景：

1. terminal 初始化不再请求旧路径。
2. provider/model/chat 链路正常。
3. 右侧模式切换生效。
4. 参数收集流程正常。
5. 确认流程正常。
6. 取消确认后状态恢复。
7. `mcp_enabled=false` 时 UI 锁定与提示正确。

## 7.3 集成验收用例

至少准备 4 条端到端链路：

1. 只读查询命令
2. 低风险写命令
3. 高风险写命令
4. admin 命令

每条链路必须给出：

1. 前置条件
2. 输入命令
3. 预期输出
4. 预期审计记录

---

## 8. 强制验收标准（DoD）

以下条目必须全部满足，否则本批次不得验收通过。

1. terminal 前端不再请求旧路径。
2. terminal 聊天与动态命令链路可稳定运行。
3. `mcp_enabled` 对网页登录态 terminal 已生效。
4. 命令分级已落模型、接口、前端展示、权限执行四个层面。
5. `只读/逐次确认/自动确认` 三种模式已实现。
6. 写命令的 CLI 确认流程已实现，不使用任何弹窗。
7. terminal 命令配置页与 CRUD 已收紧为 staff/admin。
8. 审计日志已覆盖成功、失败、取消、超时四类状态。
9. 自动化测试通过。
10. 交付文档完整。

---

## 9. 外包提交与交付规范

外包团队最终必须提交以下内容：

1. 代码提交与 PR 链接
2. 数据迁移说明
3. 风险分级清单
4. API 变更说明
5. 测试清单与执行结果
6. 关键流程截图或录屏
7. 已知限制与残余风险
8. 回滚说明

提交要求：

1. 不允许把无关重构混入本批次。
2. 不允许把前端改动、后端改动、迁移改动、文档改动全部塞进一个无法审阅的超大提交。
3. 每个 PR 必须标明对应任务包。

---

## 10. 外包团队无权自行决定的事项

以下事项已冻结，外包团队不得自行变更：

1. terminal 右侧模式固定为：`只读`、`逐次确认`、`自动确认`
2. 确认交互固定为 CLI 风格，不使用弹窗
3. 风险级别固定为：`read`、`write_low`、`write_high`、`admin`
4. `mcp_enabled=false` 时仅允许纯聊天，不允许动态命令执行
5. `自动确认` 不能替代后端角色校验
6. terminal 命令配置页与 CRUD 必须收紧到 staff/admin

---

## 11. 建议实施顺序

外包团队必须按以下顺序执行，不允许跳步：

1. 先完成路由与调用链修复
2. 再完成命令模型与权限控制
3. 再完成右侧模式与 CLI 确认
4. 再完成 MCP 开关接入与审计
5. 最后补齐测试与交付文档

原因：

1. 路由不稳会导致后续调试全部失真。
2. 权限模型不先落地，确认模式会缺少后端边界。
3. 审计必须建立在最终执行路径稳定之后。

---

## 12. 给内部验收团队的直接检查项

内部验收时可直接按下列顺序检查：

1. 打开 `/terminal/`，确认无旧路径报错。
2. 切换 provider/model，发送普通聊天，确认正常。
3. 检查命令列表是否带 `risk_level`。
4. 普通用户执行 `read`、`write_low`、`admin` 三类命令，确认权限行为正确。
5. 将测试账号 `mcp_enabled` 关闭，确认 terminal 动态命令不可用但聊天可用。
6. 检查 `逐次确认` 模式下 CLI 确认文本与 token 行为。
7. 检查一条成功写操作和一条失败写操作的审计记录。

---

## 13. 备注

本任务书即为本批次 terminal MCP 治理与确认机制改造的唯一执行和验收依据。

如实现结果与本文冲突，以本文为准；如外包团队认为现有代码存在更优实现路径，可在不改变本文行为约束的前提下提交实现说明，但不得自行改变产品定义、权限边界或验收口径。
