# 代码指挥官实施清单（可勾选执行版）

日期：2026-04-04
状态：执行清单
适用范围：基于 `phase-1` ~ `phase-5` 整理

---

## 使用说明

- 完成前使用 `- [ ]`
- 完成后改成 `- [x]`
- Day 1-3 为后端基础设施
- Day 4-5 为后端执行引擎
- Day 6 为 Agent 集成
- Day 7-8 为流式交互
- Day 9-10 为前端集成

---

## Day 1：State + Prompt + 注册

Day 1 目标：完成代码指挥官 Agent 的基础架子

- [ ] 新增 `CODE_COMMANDER = "code_commander"` 到 `AgentRole` 枚举
- [ ] 新增 `CodeCommanderState` TypedDict（包含 task_type, ai_provider, sandbox_mode 等）
- [ ] 新增 `CODE_COMMANDER_SYSTEM_PROMPT` 系统提示
- [ ] 新增 `SANDBOX_EXECUTION_PROMPT` 沙盒执行说明
- [ ] 新增 `DIRECT_EXECUTION_PROMPT` 直接执行说明
- [ ] 在 `SUB_COMMANDER_TOOLSETS` 中注册 `CODE_COMMANDER_TOOLSET`
- [ ] 新增 `CodeCommanderManifest` 到 `AGENT_MANIFESTS`
- [ ] 补 Phase 1 单元测试

**验收：确认 `AgentRole.CODE_COMMANDER` 存在且值正确**

---

## Day 2：AI CLI Adapter（统一接口）

Day 2 目标：实现适配不同 AI CLI 的统一接口

- [ ] 新增 `AICLIAdapter` 抽象基类
  - `cli_name` 属性
  - `requires_workspace` 属性
  - `build_command()` 方法
  - `parse_output()` 方法
  - `is_installed()` 方法
- [ ] 新增 `ClaudeAdapter` 实现
- [ ] 新增 `GeminiAdapter` 实现
- [ ] 新增 `CodexAdapter` 实现
- [ ] 新增 `OpenCodeAdapter` 实现
- [ ] 新增 `CodeExecutionResult` 数据类
- [ ] 补 Day 2 单元测试

**验收：`AICLIAdapter` 可以正确识别 4 种 CLI**

---

## Day 3：Security Classifier + Direct Executor

Day 3 目标：实现安全分级和直接执行器

- [ ] 新增 `RiskLevel` 枚举（LOW/HIGH）
- [ ] 新增 `SecurityClassifier` 类
  - `HIGH_RISK_KEYWORDS` 列表
  - `LOW_RISK_KEYWORDS` 列表
  - `classify()` 方法实现
  - `_is_project_path()` 方法实现
- [ ] 新增 `DirectExecutor` 类
  - `execute()` 方法（异步）
  - 超时控制
  - `is_installed()` 检查
- [ ] 补 Day 3 单元测试

**验收：`SecurityClassifier` 能正确分类高低风险**

---

## Day 4：Sandbox Environment + Sandbox Executor

Day 4 目标：实现沙盒执行器

- [ ] 新增 `SandboxEnvironment` 类
  - `create()` 静态方法（创建临时目录）
  - `cleanup()` 方法
  - `workspace_path` 属性
  - `session_id` 属性
- [ ] 新增 `SandboxExecutor` 类
  - `execute()` 方法（异步，yield 流式输出）
  - `cleanup_session()` 方法
  - `_list_created_files()` 方法
- [ ] 实现超时控制
- [ ] 补 Day 4 单元测试

**验收：`SandboxExecutor` 能创建、执行、清理沙盒**

---

## Day 5：执行引擎集成测试

Day 5 目标：确保执行引擎各组件协同工作

- [ ] 集成测试：`SecurityClassifier` + `DirectExecutor`
- [ ] 集成测试：`SecurityClassifier` + `SandboxExecutor`
- [ ] 集成测试：4 种 `AICLIAdapter` 的 `build_command()`
- [ ] 端到端测试：低风险任务直接执行
- [ ] 端到端测试：高风险任务沙盒执行
- [ ] 确认沙盒目录创建和清理正常

**验收：所有执行器支持流式输出，且正确路由**

---

## Day 6：Graph 节点 + 边路由

Day 6 目标：将代码指挥官接入 LangGraph

- [ ] 新增 `code_commander_node` 函数
  - 获取用户需求和 AI 提供商
  - 调用 `SecurityClassifier`
  - 根据风险等级选择执行器
  - 返回执行结果
- [ ] 在 `NODES` 字典中注册 `code_commander`
- [ ] 新增 `_should_route_to_code_commander()` 路由函数
- [ ] 在 `graph.py` 中添加条件边
- [ ] 新增 `CodeTask`, `CodeExecutionResult` 模型到 `schemas/task.py`
- [ ] 补 Day 6 单元测试

**验收：高风险任务路由到沙盒，低风险路由到直接执行**

---

## Day 7：PTY Terminal Engine

Day 7 目标：实现 PTY 终端管理

- [ ] 新增 `PTYSession` 数据类
- [ ] 新增 `PTYManager` 类
  - `spawn()` 方法
  - `write()` 方法
  - `read()` 方法（异步生成器）
  - `resize()` 方法
  - `kill()` 方法
- [ ] 实现 `asyncio.subprocess` 进程管理
- [ ] 实现输出队列
- [ ] 补 Day 7 单元测试

**验收：PTY 会话可以启动、读写、终止**

---

## Day 8：WebSocket + 流式输出

Day 8 目标：实现 WebSocket 端点和流式输出

- [ ] 新增 `ConnectionManager` 类
- [ ] 新增 `/ws/terminal/{session_id}` WebSocket 端点
- [ ] 实现连接管理（connect/disconnect）
- [ ] 新增 `StreamOutput` 类
- [ ] 实现 `stream_execution()` 方法
- [ ] 新增 `InteractiveInputHandler` 类
- [ ] 实现用户输入传递到 PTY
- [ ] 补 Day 8 集成测试

**验收：WebSocket 连接正常，输出实时推送**

---

## Day 9：Vue 页面组件

Day 9 目标：前端代码指挥官主页面

- [ ] 新增 `CodeCommander.vue` 页面组件
  - AI 提供商选择器
  - 任务输入框
  - 执行按钮
  - 终端显示区域
  - 交互输入框
  - 下载/清理按钮
- [ ] 补 Day 9 组件测试

**验收：用户可以选择 AI 提供商并输入任务**

---

## Day 10：TerminalDisplay + WebSocket 服务 + 路由

Day 10 目标：完成前端集成

- [ ] 新增 `TerminalDisplay.vue` 组件（xterm.js）
  - 终端渲染
  - ANSI 颜色支持
  - 用户输入处理
- [ ] 新增 `terminalWs.ts` WebSocket 服务
  - 连接管理
  - 自动重连
  - 消息处理
- [ ] 在 `router/index.ts` 新增 `/code-commander` 路由
- [ ] 端到端测试：完整执行流程
- [ ] 确认前端与后端 WebSocket 通信正常

**验收：用户可以在前端看到实时终端输出并交互**

---

## 最终验收

- [ ] 用户可以选择 AI 提供商（Claude/Gemini/Codex/OpenCode）
- [ ] 低风险任务（如贪食蛇 demo）直接执行
- [ ] 高风险任务在临时目录沙盒执行
- [ ] 终端输出实时流式显示
- [ ] 用户可以中途输入交互（如 "y" 确认）
- [ ] 临时目录执行后正确清理
- [ ] 前端页面正常展示
- [ ] 回归测试通过（现有功能不受影响）