代码指挥官 (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 |
推荐阅读顺序
- 先阅读本 README 了解整体架构
- 再按顺序阅读 phase 1 ~ phase 5
- 实施时严格按阶段推进
总体设计原则
- 用户选择式交互 - 不是自动分流，用户显式选择 AI 提供商
- 安全分级执行 - 低风险直接执行，高风险沙盒隔离
- 流式终端体验 - 实时显示 AI 执行过程，支持用户交互
- 临时目录隔离 - 每个任务在独立临时目录执行，执行后清理
阶段总览图
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 重连 | 前端实现自动重连机制 |