# MoreAgentWork

**Repository Path**: wenbing123/more-agent-work

## Basic Information

- **Project Name**: MoreAgentWork
- **Description**: 基于 Python asyncio 的多 Agent 协作系统，实现 **需求分析 → 产品设计 → 代码开发 → 代码审核 → 发布部署** 的全流程自动化。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多 Agent 协作开发框架 v2.0

> 基于 Python asyncio 的多 Agent 协作系统，实现 **需求分析 → 产品设计 → 代码开发 → 代码审核 → 发布部署** 的全流程自动化。
> 
> **v2.0 新增**：两阶段代码生成 / 逐文件审查 / 崩溃续跑恢复 / 单文件重试 / 交互式模式 / 实时心跳进度

---

## 目录

- [快速开始](#快速开始)
- [系统架构](#系统架构)
- [项目结构](#项目结构)
- [运行模式](#运行模式)
  - [交互式启动](#交互式启动)
  - [命令行参数](#命令行参数)
- [核心设计](#核心设计)
  - [状态机引擎](#状态机引擎)
  - [两阶段代码生成](#两阶段代码生成)
  - [逐文件代码审查](#逐文件代码审查)
  - [崩溃续跑与状态恢复](#崩溃续跑与状态恢复)
  - [数据流与上下文隔离](#数据流与上下文隔离)
- [五大业务 Agent](#五大业务-agent)
- [多层安全与容错机制](#多层安全与容错机制)
  - [LLM 调用层重试](#llm-调用层重试)
  - [单文件级重试](#单文件级重试)
  - [管线级重试](#管线级重试)
  - [Agent 权限沙箱](#agent-权限沙箱)
- [消息总线 (MessageBus)](#消息总线-messagebus)
- [配置说明](#配置说明)
- [日志与进度显示](#日志与进度显示)
- [产物与状态文件](#产物与状态文件)
- [扩展开发](#扩展开发)
- [技术栈](#技术栈)
- [常见问题](#常见问题)

---

## 快速开始

### 环境要求

- Python 3.10+
- Git（发布阶段需要）
- 有效的 DeepSeek API Key

### 安装

```bash
pip install -r requirements.txt
```

### 配置

编辑 `config.yaml`，至少配置 DeepSeek API Key：

```yaml
model_gateway:
  providers:
    deepseek:
      endpoint: https://api.deepseek.com
      api_key: sk-your-deepseek-api-key
```

### 运行

```bash
python main.py
```

交互式选择模式：

```
╭──────────────────────────────╮
│  多智能体协作开发框架 v2.0    │
╰──────────────────────────────╯
  运行模式:
    [1] 新建项目 — 全流程：需求分析 → 设计 → 开发 → 审查 → 发布
    [2] 优化已有项目 — 基于审查问题修复代码

  已有项目 (2 个):
    [1] snake_game
    [2] admin-system

  请选择模式 [1/2] 或指定已有项目编号:
```

---

## 系统架构

```
┌──────────────────────────────────────────────────────────────┐
│                      表示层 (CLI)                             │
│              main.py — 交互式模式 + argparse                  │
├──────────────────────────────────────────────────────────────┤
│                    编排层 (Orchestrator)                       │
│   orchestrator.py — 状态机引擎 + 进度可视化 + 检查点/回滚      │
│   集成：ContextManager / RecoveryEngine / AuditLogger         │
├──────────────────────────────────────────────────────────────┤
│                   业务层 (Business Agents)                     │
│  ┌────────────┐  ┌──────────┐  ┌───────────┐                │
│  │ requirement │→ │  design  │→ │ code_dev  │                │
│  │  需求分析    │  │ 产品设计  │  │  代码开发  │                │
│  └────────────┘  └──────────┘  └─────┬─────┘                │
│                                      │  ↕                    │
│  ┌────────────┐              ┌───────┴──────┐                │
│  │  release   │←─────────────│ code_review  │                │
│  │  发布部署   │              │   代码审核    │                │
│  └────────────┘              └──────────────┘                │
│              ↑ 异步消息 (MessageBus) ↑                        │
├──────────────────────────────────────────────────────────────┤
│                  基础设施层 (Infrastructure)                   │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────┐      │
│  │ ModelGateway │  │StorageEngine │  │  ToolRegistry  │      │
│  │ call_text()  │  │ 产物 + 状态  │  │ 沙箱 + 黑名单  │      │
│  │ 心跳 + 重试  │  │ 检查点 + 日志│  │ 路径穿越拦截   │      │
│  └──────────────┘  └──────────────┘  └────────────────┘      │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────┐      │
│  │RecoveryEngine│  │ AuditLogger  │  │  MessageBus    │      │
│  │ 错误分类自愈  │  │ 全链路追踪   │  │ 去重 + ACK     │      │
│  └──────────────┘  └──────────────┘  └────────────────┘      │
└──────────────────────────────────────────────────────────────┘
```

---

## 项目结构

```
E:\MoreAgentWork\
├── main.py                 # 入口：交互式模式 + CLI 参数 + 组件初始化
├── orchestrator.py         # 总控：状态机 + 进度可视化 + 检查点/回滚
├── message_bus.py          # 消息总线：去重 + ACK 确认 + 持久化 + DLQ
├── model_gateway.py        # 模型网关：call_text() + 心跳 + 重试 + 降级
├── storage.py              # 存储引擎：状态/检查点/上下文/审计日志
├── tool_registry.py        # 工具注册表：沙箱隔离 + 文件黑名单保护
├── context_manager.py      # 上下文管理：白名单隔离 + 截断保护
├── error_recovery.py       # 错误恢复：分类 → 自愈策略匹配
├── audit_logger.py         # 审计追踪：全链路 JSONL + query/failures
├── config.yaml             # 配置：模型映射、提示词、超时、降级链
├── requirements.txt        # Python 依赖
├── agents/                 # 业务 Agent
│   ├── base.py             # BaseAgent 基类 + 结构化输出校验
│   ├── requirement.py      # 需求分析 Agent
│   ├── design.py           # 产品设计 Agent
│   ├── code_dev.py         # 代码开发 Agent（两阶段 + 崩溃续跑）
│   ├── code_review.py      # 代码审查 Agent（逐文件 + 崩溃续跑）
│   └── release.py          # 发布 Agent（Git→Gitee→VM→Docker）
├── tools/                  # 工具链
│   ├── git_tool.py         # Git 操作
│   └── docker_tool.py      # Docker + SSH
└── tests/                  # 单元测试
```

### 运行时目录

```
temp/                       # 代码开发工作区
  └── {project-name}/        # 项目目录
        ├── main.py           # 生成的代码文件
        ├── _plan.json        # 代码开发状态文件（续跑恢复用）
        └── _review_plan.json # 审查状态文件（通过 sync 复制）
workspace/
  ├── repo/{project-name}/   # 同步后的项目（审查 + 发布用）
  ├── .state/                # 管道状态文件
  │     ├── current_state.json  # 当前阶段 + 上下文
  │     └── checkpoint_N.json   # 各阶段完成快照
  ├── agents/                # Agent 上下文和产物
  └── logs/                  # 审计日志 + 性能日志
```

---

## 运行模式

### 交互式启动

直接运行 `python main.py` 进入交互式模式：

```
╭──────────────────────────────╮
│  多智能体协作开发框架 v2.0    │
╰──────────────────────────────╯
  运行模式:
    [1] 新建项目 — 全流程：需求分析 → 设计 → 开发 → 审查 → 发布
    [2] 优化已有项目 — 基于审查问题修复或增加功能

  已有项目 (2 个):
    [1] snake_game
    [2] admin-system

  请选择模式 [1/2] 或指定已有项目编号:
```

**模式 1 — 新建项目**：输入项目描述，执行完整流水线。

**模式 2 — 优化已有项目**：选择要修改的项目，输入优化描述（如"修改登录页样式"），系统会跳过需求分析和设计阶段，直接进入开发→审查循环，针对已有代码做出修改。

**直接输入项目编号**：等同于模式 2，快捷选择已有项目。

### 命令行参数

```bash
python main.py                          # 交互式启动
python main.py --resume                 # 从最新检查点恢复
python main.py --rollback code_review   # 回退到代码审查阶段
python main.py --trace                  # 启用实时审计追踪
```

**恢复与回退**：

```bash
# 流程中断后恢复
python main.py --resume
# → 加载 workspace/.state/current_state.json
# → 恢复到上次中断的阶段
# → Agent 自动检测 _plan.json / _review_plan.json 跳过已完成文件

# 回退到某个阶段重新执行
python main.py --rollback code_development   # 回到代码开发阶段
python main.py --rollback code_review        # 回到代码审查阶段
```

---

## 核心设计

### 状态机引擎

```
INIT → REQUIREMENT → DESIGN → DEVELOPMENT → REVIEW → RELEASE → COMPLETED
         │              │         │            │   │        │
         └──→ FAILED ←──┘         └──→ DESIGN  │   │        │
                                    (回退)     │   │        │
                                               │   │        │
                             DEVELOPMENT ←─────┘   │        │
                             (修复后重新审核)        │        │
                                                   │        │
                             FAILED ←──────────────┘        │
                                                     FAILED ←┘
```

每个阶段完成后自动保存检查点到 `workspace/.state/checkpoint_N.json`。

### 两阶段代码生成

代码开发 Agent 采用**规划→生成**两阶段模式，替代传统的一次性生成：

```
Phase 1: _plan_files()               Phase 2: _generate_file()
  调用 LLM 规划文件结构                  逐文件调用 LLM 生成代码
       │                                      │
       ▼                                      ▼
  [                                               [1/3] 生成 main.py ... ✓ (2450 字符)
    {"path":"main.py","description":"入口"},       [2/3] 生成 game.py ... ✓ (3200 字符)  
    {"path":"game.py","description":"逻辑"},       [3/3] 生成 requirements.txt ... ✓ (180 字符)
    {"path":"requirements.txt","description":"依赖"}
  ]                                               每个文件独立 LLM 上下文
                                                  写入磁盘 + 状态更新
```

**设计优势**：
- 单文件独立 LLM 上下文，生成质量更高
- 每个文件独立超时和重试，不会因一个文件失败而全部重来
- 进度实时可见：`[3/12] 生成 utils.py ... ✓ (1200 字符)`
- 规划结果以层级树状展示：

```
  ✓ 规划完成: 12 个文件
  项目结构：
    ✅ app.py  — 根组件，定义应用布局框架
    ✅ config.py  — TypeScript编译配置文件
    models/
      ├── ✅ user.py  — 用户状态管理，处理登录注销
      ├── employee.py  — 角色权限状态管理
    routes/
      ├── auth.py  — 认证路由
      ├── admin.py  — 管理后台路由
```

### 逐文件代码审查

代码审查 Agent 同样采用**扫描→逐文件审查→汇总**模式：

```
_load_review_plan()                     _review_file_with_retry()
  扫描项目目录 → 构建审查清单               逐文件调用 LLM 审查 + 重试
       │                                      │
       ▼                                      ▼
  [                                         [1/15] 审查 models/user.py (2800 字符) ... ✓ (2 个问题, 1 高, 1 中)
    {"path":"models/user.py","status":"done","issues":[...]},   [2/15] 审查 config.py (800 字符) ... ✓ (无问题)
    {"path":"config.py","status":"pending","issues":[]}         ...
  ]                                         
                                          最终汇总：
                                          ==================================================
                                          审查报告汇总 (1/3 轮)
                                          ==================================================
                                          总文件数: 15   审查成功: 14   审查失败: 1
                                          高优先级: 2   中优先级: 3   低优先级: 5
                                          🔴 高优先级问题:
                                            [models/user.py] 硬编码密码存在安全风险
```

### 崩溃续跑与状态恢复

**两层续跑机制**：

```
┌─ 第 1 层：管道级 (Orchestrator) ─────────────────────────┐
│  指令：python main.py --resume                            │
│  文件：workspace/.state/current_state.json                │
│  作用：恢复到上次中断的管道阶段                              │
│                                                          │
│  { "state": "code_development", "context": {...} }        │
├──────────────────────────────────────────────────────────┤
│  第 2 层：文件级 (Agent 内部，自动触发)                      │
│                                                          │
│  代码开发：temp/{project}/_plan.json                      │
│  [{"path":"main.py","status":"done","retries":0},         │
│   {"path":"game.py","status":"failed","retries":3},       │
│   {"path":"utils.py","status":"pending","retries":0}]     │
│                                                          │
│  代码审查：workspace/repo/{project}/_review_plan.json     │
│  [{"path":"main.py","status":"done","issues":[...]},      │
│   {"path":"game.py","status":"pending","issues":[]}]      │
└──────────────────────────────────────────────────────────┘
```

**恢复流程示例**：

```
# 代码开发生成了 5/15 个文件后网络中断
$ python main.py --resume
  → Orchestrator: 恢复到 code_development 阶段
  → code_dev: 检测到 _plan.json, 5 个 done, 10 个 pending
  → 跳过已完成的 5 个，从第 6 个继续
  ✓ 规划完成: 5/15 个已完成, 0 个失败待重试

# 又生成 3 个后再次中断
$ python main.py --resume
  → 同流程，_plan.json 已有 8 个 done
  → 从第 9 个继续
```

### 数据流与上下文隔离

```
用户输入 → CLI → Orchestrator → 唤醒当前阶段 Agent
                                    │
Agent.execute(context)               │
  → ContextManager.get_view() 获取隔离上下文
  → 构造 prompt → LLM 生成
  → 写回 ContextManager.update()
  → 持久化到 StorageEngine
                                    │
Orchestrator 根据 result.status 转换状态 → 下一阶段 Agent
```

每个 Agent 只能看到白名单字段，防止上下文污染：

| Agent | 可见字段 | 字符上限 |
|-------|---------|---------|
| requirement | `user_input`, `project_specs` | 无限制 |
| design | 需求产出 + `user_input` + `project_specs` | 无限制 |
| code_dev | 设计产出 + `user_input` + `project_specs` | 30,000 |
| code_review | 开发产出 + `project_specs` | 无限制 |
| release | 开发产出 + 审查产出 + `project_specs` | 无限制 |

---

## 五大业务 Agent

### 需求分析 Agent (RequirementAgent)

纯 LLM 推理，输出结构化 PRD：功能概述、业务流程、用户角色、模块拆分、需求禁忌、交付标准。

### 产品设计 Agent (DesignAgent)

将需求转化为技术方案：架构风格、技术栈、模块划分、数据模型、API 端点、安全策略、部署方案。

### 代码开发 Agent (CodeDevAgent)

**两阶段生成流程**：

1. **Phase 1 — 规划文件结构**：调用 LLM 输出 `[{path, description}]` JSON 清单，支持从 `_plan.json` 续跑恢复
2. **Phase 2 — 逐文件生成**：每个文件独立调用 LLM，带 3 次重试（指数退避 2^n 秒），实时进度显示

**安全机制**：
- 同名项目自动追加 `-2`/`-3` 后缀，防止覆盖
- `_generate_file_with_retry()` 每完成一个文件即更新状态
- 失败的标记为 `failed`，不影响其他文件

### 代码审查 Agent (CodeReviewAgent)

**逐文件审查流程**：

1. **扫描项目文件**：构建审查清单 `_review_plan.json`，跳过非代码文件
2. **逐文件审查**：每个文件独立调用 LLM，四维度检查，带 3 次重试
3. **汇总报告**：统计高/中/低优先级问题，打印汇总表格

**审查维度**：
- 代码规范（命名、格式、注释）
- 潜在 BUG（空指针、类型错误、逻辑错误）
- 安全漏洞（注入、硬编码凭据、不安全调用）
- 性能与最佳实践

**容错策略**：单文件重试 3 次耗尽后标记失败并继续，不影响其他文件。最终汇总区分「审查成功」和「审查失败」文件。

### 发布部署 Agent (ReleaseAgent)

六步流水线：Git 本地操作 → Gitee 创建仓库推送 → SSH VM 编译 → Docker 构建 → 推送镜像仓库 → 启动服务。

仓库名使用项目名（从 `code_development_output.project_name` 获取）。

---

## 多层安全与容错机制

### 三层重试体系

```
┌─ Layer 1: LLM 调用层 (ModelGateway) ─────────────────────┐
│  每次 API 调用独立重试，指数退避 (2^n 秒，上限 30s)        │
│  超时自动翻倍 (60→120→240s)                               │
│  网络错误切换 fallback 模型                                │
│  格式错误注入修正 prompt                                   │
│  内容截断自动续写                                          │
├─ Layer 2: 单文件级重试 (Agent 内部) ──────────────────────┤
│  _generate_file_with_retry(): 每个文件最多 3 次重试       │
│  _review_file_with_retry(): 每个文件最多 3 次重试         │
│  每次重试均重新请求 LLM（不重放旧请求）                     │
│  超过重试次数 → 标记失败 → 继续下一个文件                  │
├─ Layer 3: 管线级重试 (Orchestrator) ──────────────────────┤
│  _execute_with_retry(): 整个阶段最多 3 次重试              │
│  累计错误 ≥ 5 → 终止流程                                  │
│  自动回退到上一阶段（auto_rollback）                       │
└───────────────────────────────────────────────────────────┘
```

### Agent 权限沙箱

开发 Agent 的 ToolRegistry 具备两级安全防线：

| 防线 | 机制 | 说明 |
|------|------|------|
| **沙箱隔离** | `Path.resolve()` 后检查路径是否在工作目录内 | 拒绝 `../../../etc/passwd` 路径穿越 |
| **文件黑名单** | `_protected_files` 集合 | 禁止覆盖 `main.py`、`orchestrator.py`、`config.yaml` 等框架源文件 |

`set_work_dir(str(self.project_dir))` 将工作目录锁定为 `temp/{project}/`，确保 Agent 只能在该目录内操作。

---

## 消息总线 (MessageBus)

基于 `asyncio.Queue` 的点对点 Agent 通信，用于审核↔开发的修复闭环。

| 机制 | 说明 |
|------|------|
| **预写日志** | 消息入队前先持久化到 `message_queue.jsonl` |
| **死信队列 (DLQ)** | 目标 Agent 未注册时入 DLQ，支持 `replay_dlq()` 重放 |
| **去重** | `_processed_ids` 集合，相同 `msg_id` 不重复投递 |
| **ACK 确认** | `get_message()` 消费后记录 `_acked_ids`，确认投递完成 |

---

## 配置说明

### model_gateway

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `default_timeout` | LLM 调用超时（秒） | 120 |
| `max_retries` | LLM 调用最大重试 | 2 |
| `providers` | 多 Provider 端点 (deepseek/dashscope/ollama) | - |
| `agent_model_mapping` | 各 Agent 使用的模型 | 见下表 |
| `fallback_chain` | 模型降级链 | `deepseek-chat → deepseek-reasoner` |
| `agent_prompts` | 各 Agent 的 System Prompt | - |

**各 Agent 模型分配**：

| Agent | Provider | Model |
|-------|----------|-------|
| requirement | DeepSeek | deepseek-chat |
| design | DeepSeek | deepseek-chat |
| code_dev | DeepSeek | deepseek-chat |
| code_review | DashScope | ZHIPU/GLM-5.1 |
| release | Ollama | qwen2:7b |

### orchestrator

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `max_review_rounds` | 审核最大驳回轮次 | 3 |
| `agent_timeout_seconds` | Agent 执行超时（秒） | 300 |
| `checkpoint_enabled` | 检查点开关 | true |
| `auto_rollback_on_failure` | 自动回退开关 | true |
| `max_pipeline_retries` | 管线最大重试次数 | 2 |
| `max_cumulative_errors` | 累计错误上限 | 5 |

### gitee / registry / deploy

发布阶段凭据配置：
- `gitee`: Gitee 仓库 API + 账号/密码
- `registry`: 阿里云容器镜像仓库地址 + 凭据
- `deploy`: VM 远程部署 SSH 凭据 (192.168.56.10)

---

## 日志与进度显示

### 实时心跳

长时间等待 LLM 响应时，自动输出心跳进度：

```
  💻 [代码开发] code_dev 开始执行... (超时 300s)
  💻 [code_dev] 正在调用 deepseek-chat 生成代码...
  ⏳ [code_dev] 等待 LLM 响应中... (已等待 8s)
  ⏳ [code_dev] 等待 LLM 响应中... (已等待 16s)
  ⏳ [code_dev] 等待 LLM 响应中... (已等待 24s)
```

### 阶段进度可视化

每个阶段开始时显示整体进度条：

```
┌────────────────────────────────────────────────────────────┐
│  🏗  多智能体协作开发流程                                   │
│  📋 [ ✅] 需求分析                                          │
│  🎨 [ ✅] 产品设计                                          │
│  💻 [ ▶] 代码开发 ...                                       │
│  🔍 [ ⬜] 代码审查                                          │
│  🚀 [ ⬜] 版本发布                                          │
└────────────────────────────────────────────────────────────┘
```

### LLM 请求/响应日志

每次调用大模型时输出完整请求和响应（超过 20000 字符自动截断标注长度）：

```
[code_dev] >>> LLM REQUEST | model=deepseek-chat | endpoint=https://api.deepseek.com
[code_dev] system_prompt (1200 chars):
你是顶级工业级全栈开发工程师...
[code_dev] user_prompt (3500 chars):
请为以下项目生成文件 "main.py" 的完整代码...
[code_dev] <<< LLM RESPONSE (2450 chars):
import pygame
...
```

### 文件生成/审查进度

```
  📐 [Phase 1/2] 正在规划 snake_game 的文件结构...
  ✓ 规划完成: 12 个文件
  项目结构：
    app.py  — 根组件
    models/
      ├── user.py  — 用户状态管理
      ...

  💻 [Phase 2/2] 逐文件生成代码 (共 12 个，已完成 0，待生成 12)...
    [1/12] 生成 app.py ... ✓ (2450 字符)
    [2/12] 生成 models/user.py ... ✓ (1800 字符)
    [3/12] 生成 utils/req.py ... ✗ (Read timed out)将在 2s 后重试
    [3/12] 生成 utils/req.py (重试 1/3)... ✓ (1200 字符)

  🔍 代码审查 (共 12 个文件，已完成 0，待审查 12，第 1/3 轮)...
    [1/12] 审查 app.py (2450 字符) ... ✓ (2 个问题, 1 高, 1 中)
    [2/12] 审查 models/user.py (1800 字符) ... ✓ (无问题)
```

### 失败终结报告

```
╔══════════════════════════════════════════════════╗
║   ❌  流程执行失败！                              ║
║                                                  ║
║   📋  需求分析  ✅                                ║
║   🎨  产品设计  ✅                                ║
║   💻  代码开发  ❌                                ║
║   🔍  代码审查  ⬜                                ║
║   🚀  版本发布  ⬜                                ║
╚══════════════════════════════════════════════════╝
```

---

## 产物与状态文件

### 完整生命周期

```
temp/{project}/                  workspace/repo/{project}/
  ├── _plan.json                   ├── _plan.json (从 temp 同步)
  ├── main.py                      ├── _review_plan.json
  ├── models/                      ├── main.py              
  │   └── user.py                  ├── models/              
  └── ...                          │   └── user.py          
                                   └── ...
        │                                    │
        └── _sync_to_repo() ─────────────────┘
```

### 状态文件格式

**_plan.json** (代码开发进度)：

```json
[
  {
    "path": "main.py",
    "description": "程序入口",
    "status": "done",
    "retries": 0
  },
  {
    "path": "game.py",
    "description": "游戏核心逻辑",
    "status": "failed",
    "retries": 3
  },
  {
    "path": "utils.py",
    "description": "工具函数",
    "status": "pending",
    "retries": 0
  }
]
```

**_review_plan.json** (审查进度)：

```json
[
  {
    "path": "main.py",
    "status": "done",
    "retries": 0,
    "issues": [
      {
        "severity": "high",
        "description": "未处理空指针异常",
        "fix_suggestion": "添加 try-except 包裹"
      }
    ]
  },
  {
    "path": "config.py",
    "status": "pending",
    "retries": 0,
    "issues": []
  }
]
```

---

## 扩展开发

### 添加新 Agent

1. 在 `agents/` 下创建类，继承 `BaseAgent`：
   ```python
   from .base import BaseAgent, TaskState

   class MyAgent(BaseAgent):
       available_tools = []
       require_structured_output = True

       async def execute(self, context):
           response = await self.model.call_text(self.name, prompt)
           # ... process and return
   ```

2. 在 `context_manager.py` 的 `AGENT_VIEW_WHITELIST` 添加上下文白名单
3. 在 `orchestrator.py` 的状态机中添加新状态
4. 在 `main.py` 中注册到 Orchestrator

### 添加新 Provider

在 `config.yaml` 的 `model_gateway.providers` 添加端点，支持 OpenAI 兼容 API。

### 添加新工具

1. 在 `tool_registry.py` 中注册 `ToolDefinition`
2. 在 Agent 的 `available_tools` 中添加工具名

---

## 技术栈

| 组件 | 技术 |
|------|------|
| 异步框架 | Python asyncio |
| LLM 后端 | DeepSeek API / DashScope API / Ollama |
| 配置 | PyYAML |
| 终端 UI | rich (Panel, Text) |
| HTTP | requests |
| SSH | paramiko |
| Git | GitPython |

---

## 常见问题

### Q: 运行后一直显示"等待 LLM 响应中"是什么情况？
A: 这是正常的心跳提示，表示 LLM 正在处理。每 8 秒输出一次，如果超过 120 秒会触发超时重试。

### Q: 代码开发中断了，如何从断点续跑？
A: 运行 `python main.py --resume`，系统会自动检测 `_plan.json` 中已完成和未完成的文件，跳过已完成的继续生成。

### Q: 项目名冲突了怎么办？
A: v2.0 新增自动防冲突机制：如果 `temp/{project}` 已存在，自动追加 `-2`、`-3` 后缀创建新目录。

### Q: 如何针对已有项目做修改？
A: 启动时选择模式 2（优化已有项目），输入要修改的内容。系统会跳过需求分析和设计阶段，直接进入开发→审查循环。

### Q: 审查阶段某个文件审查失败了会影响其他文件吗？
A: 不会。每个文件独立重试 3 次，耗尽后标记失败并继续审查下一个文件。最终汇总会区分成功和失败的文件。

### Q: 开发 Agent 会覆盖框架自身的源码吗？
A: 不会。ToolRegistry 内置文件黑名单保护 `main.py`、`orchestrator.py`、`config.yaml` 等框架源文件，且工作目录被沙箱锁定在 `temp/{project}/`。