# 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 集成）
```

本阶段是后续所有阶段的基础。