# 代码指挥官 (Code Commander) 实施计划索引

本目录用于存放代码指挥官模块的分阶段规划文档。

## 文档说明

| 文件 | 说明 |
|------|------|
| `README.md` | 总览、阶段关系、实施顺序 |
| `phase-1-infrastructure.md` | 基础设施：State、Prompt、注册 |
| `phase-2-execution-engine.md` | 执行引擎：AI Adapter、沙盒、直接执行 |
| `phase-3-agent-integration.md` | Agent 集成：Graph 节点、边路由 |
| `phase-4-streaming-interaction.md` | 流式交互：PTY 终端、WebSocket |
| `phase-5-frontend-integration.md` | 前端集成：Vue 组件、xterm.js |

## 推荐阅读顺序

1. 先阅读本 README 了解整体架构
2. 再按顺序阅读 phase 1 ~ phase 5
3. 实施时严格按阶段推进

---

## 总体设计原则

1. **用户选择式交互** - 不是自动分流，用户显式选择 AI 提供商
2. **安全分级执行** - 低风险直接执行，高风险沙盒隔离
3. **流式终端体验** - 实时显示 AI 执行过程，支持用户交互
4. **临时目录隔离** - 每个任务在独立临时目录执行，执行后清理

---

## 阶段总览图

```
Phase 1 ──────────────────────────────────────────────────────────────┐
│ 基础设施 (Infrastructure)                                              │
│ - State 定义                                                         │
│ - Prompt 模板                                                        │
│ - 工具注册                                                           │
│ - Agent 注册                                                         │
│                                                                      │
│ 核心文件: state.py, prompts.py, tools/__init__.py, builtins.py     │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 2 ──────────────────────────────────────────────────────────────┐
│ 执行引擎 (Execution Engine)                                            │
│ - AI CLI Adapter (统一接口)                                          │
│ - Sandbox Executor                                                   │
│ - Direct Executor                                                    │
│ - Security Classifier                                                │
│                                                                      │
│ 核心文件: ai_adapter.py, sandbox_executor.py, direct_executor.py,   │
│          security_classifier.py                                       │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 3 ──────────────────────────────────────────────────────────────┐
│ Agent 集成 (Agent Integration)                                        │
│ - Graph 节点                                                         │
│ - 边路由                                                             │
│ - 任务模型                                                           │
│                                                                      │
│ 核心文件: graph.py, schemas/task.py                                  │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 4 ──────────────────────────────────────────────────────────────┐
│ 流式交互 (Streaming Interaction)                                      │
│ - PTY 终端                                                           │
│ - WebSocket 端点                                                     │
│ - 流式输出集成                                                       │
│ - 交互输入                                                           │
│                                                                      │
│ 核心文件: terminal_engine.py, routers/terminal.py, stream_output.py │
└────────────────────────────────────────────────────────────────────┘
         │
         ▼
Phase 5 ──────────────────────────────────────────────────────────────┐
│ 前端集成 (Frontend Integration)                                       │
│ - 页面组件                                                           │
│ - 终端显示组件                                                       │
│ - WebSocket 服务                                                     │
│ - 路由配置                                                           │
│                                                                      │
│ 核心文件: CodeCommander.vue, TerminalDisplay.vue, terminalWs.ts      │
└────────────────────────────────────────────────────────────────────┘
```

---

## 架构概览

```
┌─────────────────────────────────────────────────────────────┐
│                        Vue 前端                              │
│  [用户选择: Claude/Gemini/Codex/OpenCode] + [输入需求]        │
└────────────────────────┬────────────────────────────────────┘
                         │ WebSocket 流式输出
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    FastAPI 后端                              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │          代码指挥官 (Code Commander Agent)            │    │
│  │  1. 接收 AI 类型 + 用户需求                          │    │
│  │  2. 安全分级判定                                     │    │
│  │  3. 路由到对应执行器                                 │    │
│  └─────────────────────────────────────────────────────┘    │
│                            │                                 │
│         ┌──────────────────┼──────────────────┐            │
│         ▼                  ▼                  ▼            │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐       │
│  │ 直接执行器  │    │ 沙盒执行器  │    │  终端引擎   │       │
│  │(低风险任务) │    │(高风险任务) │    │  PTY + 流式 │       │
│  └────────────┘    └────────────┘    └────────────┘       │
└────────────────────────┬────────────────────────────────────┘
                         │ subprocess 调用
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              CLI 进程 (claude/gemini/codex/opencode)        │
│                    在临时目录中执行                           │
└─────────────────────────────────────────────────────────────┘
```

---

## Demo 项目借鉴映射

| Demo 项目 | 主要借鉴点 | 对应 Phase |
|---------|-----------|-----------|
| **golutra** | PTY 终端、多 CLI 适配、工作流隔离 | Phase 2, 4 |
| **golutra CLI** | LocalSocket IPC、命令分发 | Phase 2 |
| **golutra Shim** | 进程启动、信号处理 | Phase 2 |

---

## 实施顺序

```
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5
   │         │         │         │         │
   │         │         │         │         └── 前端 UI + 路由
   │         │         │         └── PTY + WebSocket
   │         │         └── Graph 节点 + 边路由
   │         └── AI Adapter + Sandbox
   └── State + Prompt + 注册
```

---

## 文件变更追踪

| Phase | 新增文件 | 修改文件 |
|-------|---------|---------|
| Phase 1 | `tools/__init__.py` (改) | `state.py`, `prompts.py`, `registry/builtins.py` |
| Phase 2 | `ai_adapter.py`, `sandbox_executor.py`, `direct_executor.py`, `security_classifier.py` | - |
| Phase 3 | `schemas/task.py` (改) | `graph.py` |
| Phase 4 | `terminal_engine.py`, `routers/terminal.py`, `stream_output.py`, `interactive_input.py` | - |
| Phase 5 | `CodeCommander.vue`, `TerminalDisplay.vue`, `terminalWs.ts` | `router/index.ts` |

---

## 注意事项

| 注意事项 | 说明 |
|---------|------|
| 不要跳过 Phase | 每个阶段都是下一个的基础 |
| AI CLI 前置检查 | 确保服务器上已安装对应 CLI |
| 临时目录及时清理 | 防止磁盘空间泄漏 |
| WebSocket 重连 | 前端实现自动重连机制 |