153 lines
4.0 KiB
Markdown
153 lines
4.0 KiB
Markdown
# Phase 1：基础设施
|
||
|
||
日期：2026-04-04
|
||
状态：待实施
|
||
|
||
---
|
||
|
||
## 1. 本阶段目的
|
||
|
||
新增代码指挥官 Agent 的基础架子，包括：
|
||
- State 定义（角色、状态）
|
||
- Prompt 模板
|
||
- 工具注册
|
||
- Agent 注册
|
||
|
||
---
|
||
|
||
## 2. 详细任务
|
||
|
||
### 2.1 State 定义
|
||
|
||
**文件**: `backend/app/agents/state.py`
|
||
|
||
```python
|
||
# 新增 AgentRole
|
||
class AgentRole(str, Enum):
|
||
# ... 现有角色 ...
|
||
CODE_COMMANDER = "code_commander"
|
||
|
||
# 新增 CodeCommanderState
|
||
class CodeCommanderState(TypedDict):
|
||
task_type: str # "demo" | "project" | "modification"
|
||
ai_provider: str # "claude" | "gemini" | "codex" | "opencode"
|
||
sandbox_mode: bool # True = 沙盒执行，False = 直接执行
|
||
workspace_path: str | None # 临时工作目录
|
||
execution_session_id: str | None # PTY 会话 ID
|
||
```
|
||
|
||
### 2.2 Prompt 模板
|
||
|
||
**文件**: `backend/app/agents/prompts.py`
|
||
|
||
```python
|
||
# 代码指挥官系统提示
|
||
CODE_COMMANDER_SYSTEM_PROMPT = """你是一个代码指挥官，负责协调 AI 写代码助手。
|
||
|
||
你的职责：
|
||
1. 接收用户选择的 AI 提供商（Claude/Gemini/Codex/OpenCode）
|
||
2. 接收用户的写代码需求
|
||
3. 进行安全分级判定
|
||
4. 路由到合适的执行器
|
||
|
||
安全分级规则：
|
||
- 低风险：demo、示例、贪食蛇游戏等独立项目
|
||
- 高风险：修改现有项目、涉及 Jarvis 项目、路径操作等
|
||
|
||
执行模式：
|
||
- 直接执行：低风险任务，直接运行
|
||
- 沙盒执行：高风险任务，在临时目录隔离执行"""
|
||
|
||
# 沙盒执行说明
|
||
SANDBOX_EXECUTION_PROMPT = """将在隔离的临时目录中执行任务。
|
||
任务完成后，工作目录会被保留供下载。"""
|
||
|
||
# 直接执行说明
|
||
DIRECT_EXECUTION_PROMPT = """将直接执行任务。
|
||
如果需要交互，请等待用户输入。"""
|
||
```
|
||
|
||
### 2.3 工具注册
|
||
|
||
**文件**: `backend/app/agents/tools/__init__.py`
|
||
|
||
```python
|
||
# 新增工具集
|
||
CODE_COMMANDER_TOOLSET = {
|
||
"code_commander": [
|
||
"execute_code_task",
|
||
"get_execution_status",
|
||
"send_interactive_input",
|
||
"download_workspace",
|
||
"cleanup_workspace",
|
||
]
|
||
}
|
||
|
||
# 在 SUB_COMMANDER_TOOLSETS 中添加
|
||
SUB_COMMANDER_TOOLSETS: dict[str, list[str]] = {
|
||
# ... 现有工具集 ...
|
||
"code_commander": CODE_COMMANDER_TOOLSET["code_commander"],
|
||
}
|
||
```
|
||
|
||
### 2.4 Agent 注册
|
||
|
||
**文件**: `backend/app/agents/registry/builtins.py`
|
||
|
||
```python
|
||
# 新增 CodeCommanderManifest
|
||
CodeCommanderManifest = AgentManifest(
|
||
id="code_commander",
|
||
name="代码指挥官",
|
||
description="协调 AI 写代码助手的指挥官",
|
||
system_prompt=CODE_COMMANDER_SYSTEM_PROMPT,
|
||
role=AgentRole.CODE_COMMANDER,
|
||
sub_commanders=[], # 代码指挥官没有子指挥官
|
||
tools=["execute_code_task", "get_execution_status",
|
||
"send_interactive_input", "download_workspace", "cleanup_workspace"],
|
||
permission_class=PermissionClass.HIGH, # 需要较高权限
|
||
side_effect_scope=SideEffectScope.WORKSPACE,
|
||
supports_retry=True,
|
||
idempotent=False,
|
||
safe_for_parallel_use=False,
|
||
requires_confirmation=True,
|
||
)
|
||
|
||
# 注册到 AGENT_MANIFESTS
|
||
AGENT_MANIFESTS: dict[str, AgentManifest] = {
|
||
# ... 现有 agent ...
|
||
"code_commander": CodeCommanderManifest,
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 核心文件清单
|
||
|
||
| 文件 | 操作 | 说明 |
|
||
|------|------|------|
|
||
| `state.py` | 修改 | 新增 `CODE_COMMANDER` 角色和 `CodeCommanderState` |
|
||
| `prompts.py` | 修改 | 新增三个 prompt 常量 |
|
||
| `tools/__init__.py` | 修改 | 新增工具集注册 |
|
||
| `registry/builtins.py` | 修改 | 新增 `CodeCommanderManifest` |
|
||
|
||
---
|
||
|
||
## 4. 验收标准
|
||
|
||
- [ ] `AgentRole.CODE_COMMANDER` 存在且值正确
|
||
- [ ] `CODE_COMMANDER_SYSTEM_PROMPT` 包含完整指令
|
||
- [ ] 工具集已注册且可通过 `SUB_COMMANDER_TOOLSETS` 访问
|
||
- [ ] `CodeCommanderManifest` 已注册且包含所有必要字段
|
||
|
||
---
|
||
|
||
## 5. 依赖关系
|
||
|
||
```
|
||
本阶段 → Phase 2（执行引擎）
|
||
→ Phase 3（Agent 集成）
|
||
```
|
||
|
||
本阶段是后续所有阶段的基础。
|