322 lines
8.4 KiB
Markdown
322 lines
8.4 KiB
Markdown
# Phase 2：执行引擎
|
||
|
||
日期：2026-04-04
|
||
状态：待实施
|
||
|
||
依赖：Phase 1 完成
|
||
|
||
---
|
||
|
||
## 1. 本阶段目的
|
||
|
||
实现代码指挥官的核心执行能力：
|
||
- AI CLI Adapter：统一接口适配不同 AI CLI
|
||
- Sandbox Executor：沙盒环境执行
|
||
- Direct Executor：直接执行低风险任务
|
||
- Security Classifier：安全分级
|
||
|
||
---
|
||
|
||
## 2. 详细任务
|
||
|
||
### 2.1 AI CLI Adapter
|
||
|
||
**新文件**: `backend/app/agents/tools/ai_adapter.py`
|
||
|
||
```python
|
||
from abc import ABC, abstractmethod
|
||
from pathlib import Path
|
||
from dataclasses import dataclass
|
||
|
||
@dataclass
|
||
class CodeExecutionResult:
|
||
success: bool
|
||
message: str
|
||
files_created: list[str]
|
||
output: str
|
||
error: str | None
|
||
|
||
class AICLIAdapter(ABC):
|
||
@property
|
||
@abstractmethod
|
||
def cli_name(self) -> str:
|
||
"""CLI 命令名称，如 'claude', 'gemini'"""
|
||
pass
|
||
|
||
@property
|
||
@abstractmethod
|
||
def requires_workspace(self) -> bool:
|
||
"""是否需要工作目录"""
|
||
pass
|
||
|
||
@abstractmethod
|
||
def build_command(self, prompt: str, workspace: Path | None) -> list[str]:
|
||
"""构建 CLI 命令"""
|
||
pass
|
||
|
||
@abstractmethod
|
||
def parse_output(self, output: str) -> CodeExecutionResult:
|
||
"""解析 CLI 输出"""
|
||
pass
|
||
|
||
@abstractmethod
|
||
def is_installed(self) -> bool:
|
||
"""检查 CLI 是否已安装"""
|
||
pass
|
||
|
||
class ClaudeAdapter(AICLIAdapter):
|
||
cli_name = "claude"
|
||
requires_workspace = True
|
||
|
||
def build_command(self, prompt: str, workspace: Path | None) -> list[str]:
|
||
return ["claude", "-p", prompt, "--dangerously-skip-permissions"]
|
||
|
||
# ... 其他方法实现
|
||
|
||
class GeminiAdapter(AICLIAdapter):
|
||
cli_name = "gemini"
|
||
requires_workspace = False
|
||
# ...
|
||
|
||
class CodexAdapter(AICLIAdapter):
|
||
cli_name = "codex"
|
||
# ...
|
||
|
||
class OpenCodeAdapter(AICLIAdapter):
|
||
cli_name = "opencode"
|
||
# ...
|
||
```
|
||
|
||
### 2.2 Security Classifier
|
||
|
||
**新文件**: `backend/app/agents/tools/security_classifier.py`
|
||
|
||
```python
|
||
from enum import Enum
|
||
|
||
class RiskLevel(Enum):
|
||
LOW = "low" # 直接执行
|
||
HIGH = "high" # 沙盒执行
|
||
|
||
class SecurityClassifier:
|
||
HIGH_RISK_KEYWORDS = [
|
||
"修改", "编辑", "删除", "移动",
|
||
"Jarvis", "backend", "frontend",
|
||
"git", "config", ".env",
|
||
]
|
||
|
||
LOW_RISK_KEYWORDS = [
|
||
"demo", "示例", "贪食蛇", "俄罗斯方块",
|
||
"小游戏", "独立项目", "新项目",
|
||
"创建一个", "写一个",
|
||
]
|
||
|
||
def classify(self, task_description: str, target_path: str | None = None) -> RiskLevel:
|
||
# 1. 检查高风险关键词
|
||
if any(kw in task_description for kw in self.HIGH_RISK_KEYWORDS):
|
||
return RiskLevel.HIGH
|
||
|
||
# 2. 检查目标路径
|
||
if target_path and self._is_project_path(target_path):
|
||
return RiskLevel.HIGH
|
||
|
||
# 3. 检查低风险关键词
|
||
if any(kw in task_description for kw in self.LOW_RISK_KEYWORDS):
|
||
return RiskLevel.LOW
|
||
|
||
# 4. 默认高风险
|
||
return RiskLevel.HIGH
|
||
|
||
def _is_project_path(self, path: str) -> bool:
|
||
# 检查是否指向 Jarvis 项目路径
|
||
return "Jarvis" in path or "backend/app" in path
|
||
```
|
||
|
||
### 2.3 Sandbox Executor
|
||
|
||
**新文件**: `backend/app/agents/tools/sandbox_executor.py`
|
||
|
||
```python
|
||
import tempfile
|
||
import shutil
|
||
import asyncio
|
||
from pathlib import Path
|
||
from dataclasses import dataclass, field
|
||
from typing import AsyncGenerator
|
||
|
||
@dataclass
|
||
class SandboxEnvironment:
|
||
workspace_path: Path
|
||
session_id: str
|
||
|
||
@staticmethod
|
||
async def create() -> "SandboxEnvironment":
|
||
"""创建新的沙盒环境"""
|
||
temp_dir = tempfile.mkdtemp(prefix="jarvis_code_")
|
||
session_id = Path(temp_dir).name
|
||
return SandboxEnvironment(
|
||
workspace_path=Path(temp_dir),
|
||
session_id=session_id,
|
||
)
|
||
|
||
async def cleanup(self):
|
||
"""清理沙盒环境"""
|
||
if self.workspace_path.exists():
|
||
shutil.rmtree(self.workspace_path)
|
||
|
||
@dataclass
|
||
class ExecutionResult:
|
||
success: bool
|
||
exit_code: int
|
||
stdout: str
|
||
stderr: str
|
||
files_created: list[str] = field(default_factory=list)
|
||
|
||
class SandboxExecutor:
|
||
def __init__(self, adapter: AICLIAdapter, timeout: int = 300):
|
||
self.adapter = adapter
|
||
self.timeout = timeout
|
||
self._sessions: dict[str, SandboxEnvironment] = {}
|
||
|
||
async def execute(
|
||
self,
|
||
prompt: str,
|
||
session_id: str | None = None
|
||
) -> AsyncGenerator[str, None]:
|
||
"""执行代码任务，yield 实时输出"""
|
||
# 1. 创建或复用沙盒环境
|
||
if session_id and session_id in self._sessions:
|
||
env = self._sessions[session_id]
|
||
else:
|
||
env = await SandboxEnvironment.create()
|
||
self._sessions[env.session_id] = env
|
||
session_id = env.session_id
|
||
|
||
# 2. 构建命令
|
||
cmd = self.adapter.build_command(prompt, env.workspace_path)
|
||
|
||
# 3. 异步执行，实时 yield 输出
|
||
process = await asyncio.create_subprocess_exec(
|
||
*cmd,
|
||
stdout=asyncio.subprocess.PIPE,
|
||
stderr=asyncio.subprocess.PIPE,
|
||
cwd=str(env.workspace_path),
|
||
)
|
||
|
||
# 4. 实时读取输出
|
||
while True:
|
||
line = await process.stdout.readline()
|
||
if not line:
|
||
break
|
||
yield line.decode()
|
||
|
||
# 5. 等待完成
|
||
await process.wait()
|
||
|
||
# 6. 收集结果
|
||
return ExecutionResult(
|
||
success=process.returncode == 0,
|
||
exit_code=process.returncode or 0,
|
||
stdout=...,
|
||
stderr=...,
|
||
files_created=self._list_created_files(env.workspace_path),
|
||
)
|
||
|
||
async def cleanup_session(self, session_id: str):
|
||
"""清理指定会话"""
|
||
if session_id in self._sessions:
|
||
await self._sessions[session_id].cleanup()
|
||
del self._sessions[session_id]
|
||
```
|
||
|
||
### 2.4 Direct Executor
|
||
|
||
**新文件**: `backend/app/agents/tools/direct_executor.py`
|
||
|
||
```python
|
||
class DirectExecutor:
|
||
def __init__(self, adapter: AICLIAdapter, timeout: int = 60):
|
||
self.adapter = adapter
|
||
self.timeout = timeout
|
||
|
||
async def execute(self, prompt: str) -> ExecutionResult:
|
||
"""直接执行，不需要沙盒"""
|
||
if not self.adapter.is_installed():
|
||
return ExecutionResult(
|
||
success=False,
|
||
exit_code=-1,
|
||
stdout="",
|
||
stderr=f"{self.adapter.cli_name} is not installed",
|
||
)
|
||
|
||
cmd = self.adapter.build_command(prompt, None)
|
||
|
||
process = await asyncio.create_subprocess_exec(
|
||
*cmd,
|
||
stdout=asyncio.subprocess.PIPE,
|
||
stderr=asyncio.subprocess.PIPE,
|
||
)
|
||
|
||
try:
|
||
stdout, stderr = await asyncio.wait_for(
|
||
process.communicate(),
|
||
timeout=self.timeout,
|
||
)
|
||
return ExecutionResult(
|
||
success=process.returncode == 0,
|
||
exit_code=process.returncode or 0,
|
||
stdout=stdout.decode(),
|
||
stderr=stderr.decode(),
|
||
)
|
||
except asyncio.TimeoutError:
|
||
process.kill()
|
||
return ExecutionResult(
|
||
success=False,
|
||
exit_code=-1,
|
||
stdout="",
|
||
stderr=f"Execution timed out after {self.timeout}s",
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 核心文件清单
|
||
|
||
| 文件 | 操作 | 说明 |
|
||
|------|------|------|
|
||
| `ai_adapter.py` | 新增 | 抽象基类 + 4 个具体实现 |
|
||
| `security_classifier.py` | 新增 | 安全分级器 |
|
||
| `sandbox_executor.py` | 新增 | 沙盒执行器 |
|
||
| `direct_executor.py` | 新增 | 直接执行器 |
|
||
|
||
---
|
||
|
||
## 4. 验收标准
|
||
|
||
- [ ] `AICLIAdapter` 可以正确识别 4 种 CLI
|
||
- [ ] `SecurityClassifier` 能正确分类高低风险
|
||
- [ ] `SandboxExecutor` 能创建、执行、清理沙盒
|
||
- [ ] `DirectExecutor` 能直接执行低风险任务
|
||
- [ ] 所有执行器支持流式输出
|
||
|
||
---
|
||
|
||
## 5. 风险与缓解
|
||
|
||
| 风险 | 缓解 |
|
||
|------|------|
|
||
| AI CLI 未安装 | `is_installed()` 检查 + 友好提示 |
|
||
| 执行超时 | `timeout` 参数控制 |
|
||
| 沙盒清理遗漏 | 使用 `finally` 块确保清理 |
|
||
|
||
---
|
||
|
||
## 6. 依赖关系
|
||
|
||
```
|
||
Phase 1（基础设施）
|
||
↓
|
||
本阶段 → Phase 3（Agent 集成）
|
||
→ Phase 4（流式交互）
|
||
```
|