172 lines
11 KiB
Markdown
172 lines
11 KiB
Markdown
# 代码指挥官 (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 重连 | 前端实现自动重连机制 |
|