full-stack-coding-assistant-agent 0.1.0__py3-none-any.whl

full_stack_coding_assistant_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,849 @@
+Metadata-Version: 2.4
+Name: full-stack-coding-assistant-agent
+Version: 0.1.0
+Summary: 企业级全栈代码助手智能体 - 多智能体协作架构
+Author-email: Kingsdom005 <liyanqi@example.com>
+Maintainer-email: Kingsdom005 <liyanqi@example.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Kingsdom005/full-stack-coding-assistant-agent
+Project-URL: Repository, https://github.com/Kingsdom005/full-stack-coding-assistant-agent
+Project-URL: Issue Tracker, https://github.com/Kingsdom005/full-stack-coding-assistant-agent/issues
+Keywords: ai,agent,coding-assistant,multi-agent,llm,code-generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: litellm>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+
+# Full-Stack Coding Assistant Agent
+
+企业级全栈代码助手智能体 - 多智能体协作架构
+
+## 🐍 Python 版本要求
+
+- **最低版本**: Python 3.11
+- **推荐版本**: Python 3.13+ (性能最优)
+- **已测试版本**: 3.11, 3.12, 3.13
+
+### 检查 Python 版本
+
+```bash
+python --version
+# 或
+python3 --version
+```
+
+### 创建虚拟环境 (Python 3.13+)
+
+```bash
+# 使用 venv (推荐)
+python -m venv venv
+source venv/bin/activate
+
+# 或使用 conda
+conda create -n coding-agent python=3.13
+conda activate coding-agent
+```
+
+---
+
+## 📦 安装
+
+### 方法 1: 使用 pip 安装（推荐）
+
+```bash
+# 安装最新稳定版本
+pip install full-stack-coding-assistant-agent
+
+# 安装指定版本
+pip install full-stack-coding-assistant-agent==0.1.0
+
+# 安装预发布版本
+pip install --pre full-stack-coding-assistant-agent
+```
+
+安装后，可以使用 `fscaa` 命令启动工具：
+
+```bash
+fscaa "开发一个用户登录功能"
+```
+
+### 方法 2: 从源码安装
+
+```bash
+git clone git@github.com:Kingsdom005/full-stack-coding-assistant-agent.git
+cd full-stack-coding-assistant-agent
+pip install -e ".[dev]"
+```
+
+---
+
+## 架构概述
+
+本项目实现了一个基于多智能体架构的企业级全栈代码助手，包含以下核心组件：
+
+- **Coordinator** - 轻量级协调器，负责任务拆解和调度
+- **Frontend Agent** - 前端专家智能体
+- **Backend Agent** - 后端专家智能体
+- **Test Agent** - 测试专家智能体
+- **Audit Agent** - 代码审计智能体
+
+## 技术栈
+
+- **LiteLLM** - 统一大模型接口，支持多模型切换和 Fallback
+- **SQLite** - 零部署嵌入式数据库 (Python 3.13+ 内置支持)
+- **CodeBuddy CLI** - 代码执行和沙箱环境
+
+## 项目结构
+
+```
+full-stack-coding-assistant-agent/
+├── full_stack_coding_assistant_agent/  # Python 包
+│   ├── __init__.py                    # 包初始化
+│   ├── cli.py                         # CLI 入口
+│   ├── main.py                        # 主入口文件
+│   ├── coordinator/                   # 协调器和调度器
+│   │   ├── coordinator.py            # 主协调器
+│   │   └── dag.py                   # DAG 任务调度器
+│   ├── agents/                       # 智能体模块
+│   │   ├── base_agent.py             # Agent 基类
+│   │   ├── frontend_agent.py
+│   │   ├── backend_agent.py
+│   │   ├── test_agent.py
+│   │   └── audit_agent.py
+│   ├── model/                        # 模型路由
+│   │   ├── model_router.py           # LiteLLM 封装
+│   │   └── config.py                 # 模型配置
+│   ├── storage/                      # 数据存储
+│   │   ├── context_db.py             # SQLite 操作封装
+│   │   └── schema.sql                # 数据库表结构
+│   ├── executor/                     # 代码执行器
+│   │   └── cb_integration.py        # CodeBuddy CLI 集成
+│   └── utils/                        # 工具模块
+│       ├── version.py                # 版本管理工具
+│       └── ...
+├── .github/workflows/                # GitHub Actions 工作流
+│   ├── ci.yml                        # CI 工作流
+│   └── cd.yml                        # CD 工作流
+├── VERSION                           # 版本号文件
+├── CHANGELOG.md                      # 变更日志
+├── config.yaml                       # 应用配置
+├── run.sh                           # 运行脚本
+├── requirements.txt                  # 依赖清单
+├── pyproject.toml                    # 项目元数据
+├── .env.example                      # 环境变量模板
+└── README.md                         # 项目说明
+```
+
+## 🚀 快速开始
+
+### 1. 克隆项目
+
+```bash
+git clone git@github.com:Kingsdom005/full-stack-coding-assistant-agent.git
+cd full-stack-coding-assistant-agent
+git checkout develop  # 切换到开发分支
+```
+
+### 2. 创建虚拟环境 (Python 3.13+)
+
+```bash
+# 方法 1: 使用 venv
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# 或
+venv\Scripts\activate     # Windows
+
+# 方法 2: 使用 conda
+conda create -n coding-agent python=3.13
+conda activate coding-agent
+```
+
+### 3. 安装依赖
+
+```bash
+pip install -r requirements.txt
+# 或
+pip install -e ".[dev]"  # 包含开发依赖
+```
+
+### 4. 配置环境变量
+
+```bash
+cp .env.example .env
+vim .env  # 编辑 .env，填写 TENCENT_API_KEY
+```
+
+**.env 文件最少配置：**
+
+```bash
+TENCENT_API_KEY=sk-your_actual_key_here
+TENCENT_API_BASE=https://api.hunyuan.cloud.tencent.com/hyllm/v1
+```
+
+### 5. 运行项目
+
+```bash
+# 方法 1: 直接运行
+python main.py "开发一个用户登录功能" "包含前后端实现"
+
+# 方法 2: 使用运行脚本
+chmod +x run.sh
+./run.sh "开发一个用户登录功能" "包含前后端实现"
+```
+
+---
+
+## 🔧 配置说明
+
+### 模型配置 (`model/config.py`)
+
+```python
+MODEL_CONFIG = {
+    "default": "hunyuan-lite",
+    "agents": {
+        "frontend": "hunyuan-lite",      # 前端 Agent 使用轻量模型
+        "backend":  "hunyuan-standard",   # 后端 Agent 使用标准模型
+        "test":     "hunyuan-lite",       # 测试 Agent 使用轻量模型
+        "audit":    "hunyuan-pro",        # 审计 Agent 使用专业模型
+    },
+    "tencent": {
+        "api_base": "https://api.hunyuan.cloud.tencent.com/hyllm/v1",
+        "api_key": os.getenv("TENCENT_API_KEY"),
+    },
+    "fallback_chain": ["hunyuan-lite", "hunyuan-standard"],
+}
+```
+
+### 获取 API Key
+
+1. 访问 [腾讯云控制台](https://console.cloud.tencent.com/)
+2. 进入 "混元大模型" 产品页
+3. 创建应用并获取 API Key
+
+---
+
+## 📊 运行示例
+
+```bash
+# 示例 1: 开发登录功能
+python main.py "开发一个用户登录功能" "包含前后端实现，支持 JWT 认证"
+
+# 示例 2: 开发 RESTful API
+python main.py "开发一个博客 API" "支持 CRUD 操作，使用 FastAPI"
+
+# 示例 3: 修复 Bug
+python main.py "修复用户注册 Bug" "邮箱验证不生效"
+```
+
+**输出示例：**
+
+```
+============================================================
+全栈代码助手智能体 (Full-Stack Coding Assistant Agent)
+============================================================
+
+[1/3] 初始化协调器...
+[2/3] 提交任务: 开发一个用户登录功能
+  主任务 ID: task_a1b2c3d4
+
+[3/3] 开始执行任务...
+------------------------------------------------------------
+[backend] 执行中...
+[frontend] 执行中...
+[test] 执行中...
+[audit] 执行中...
+------------------------------------------------------------
+
+执行结果:
+============================================================
+
+[task_a1b2c3d4_backend]:
+  状态: completed
+
+[task_a1b2c3d4_frontend]:
+  状态: completed
+
+[task_a1b2c3d4_test]:
+  状态: completed
+
+[task_a1b2c3d4_audit]:
+  状态: completed
+
+任务状态汇总:
+============================================================
+  backend: completed
+  frontend: completed
+  test: completed
+  audit: completed
+
+完成！
+```
+
+---
+
+## 🏗️ 架构设计
+
+### 分层混合架构
+
+```
+┌─────────────────────────────────────────┐
+│           User / API Layer              │
+└──────────────────┬──────────────────────┘
+                   │
+┌─────────────────────────────────────────┐
+│         Coordinator (Lite)              │
+│   - 任务拆解  - DAG 调度  - 上下文管理  │
+└──────────────────┬──────────────────────┘
+                   │
+        ┌──────────┼──────────┐
+        │          │          │
+┌───────▼───┐ ┌───▼──────┐ ┌▼──────────┐
+│ Frontend  │ │ Backend  │ │   Test    │
+│  Agent    │ │  Agent   │ │   Agent   │
+└───────────┘ └──────────┘ └───────────┘
+                                    │
+┌───────────────────────────────────▼─────┐
+│            Audit Agent                   │
+│     (异步审计，不阻塞主流程)              │
+└─────────────────────────────────────────┘
+
+        共享上下文 (SQLite)
+```
+
+### 模型路由策略
+
+- 默认使用腾讯混元免费模型 (`hunyuan-lite`)
+- 各 Agent 可配置不同模型
+- 支持 Fallback 链式降级
+
+### 数据存储设计
+
+使用 SQLite 零部署方案 (Python 3.13+ 内置支持)，设计四张核心表：
+
+- `tasks` - 任务记录
+- `code_changes` - 代码变更记录
+- `api_contracts` - 前后端接口契约
+- `audit_reports` - 审计意见
+
+---
+
+#### Mermaid 架构图（GitHub 可自动渲染）
+
+```mermaid
+graph BT
+    A["用户 / CLI"] --> B["Main Entry (main.py)"]
+    B --> C["Coordinator"]
+    C --> D["DAGScheduler"]
+    D --> E["BackendAgent"]
+    D --> F["FrontendAgent"]
+    D --> G["TestAgent"]
+    D --> H["AuditAgent"]
+    E --> I[("SQLite Context DB")]
+    F --> I
+    G --> I
+    H --> I
+    C --> J["ModelRouter (LiteLLM)"]
+    J --> K["腾讯混元大模型"]
+```
+
+#### DAG 任务依赖关系图
+
+```mermaid
+graph TD
+    A["task_xxx_backend<br/>(无依赖, 最先执行)"] --> B["task_xxx_frontend<br/>(依赖: backend)"]
+    A --> C["task_xxx_test<br/>(依赖: backend)"]
+    B --> C
+    B --> D["task_xxx_audit<br/>(依赖: 所有)"]
+    C --> D
+```
+
+---
+
+## 🔬 技术细节深挖
+
+> 本章节深入剖析项目的设计原理和实现细节，帮助开发者和架构师理解系统全貌。
+
+---
+
+### 1. System Prompt 与 Rules 设计
+
+#### 1.1 System Prompt 设计原则
+
+所有 Agent 的 System Prompt 通过各子类的 `get_system_prompt()` 方法硬编码实现，遵循以下设计原则：
+
+| 设计原则 | 说明 |
+|---------|------|
+| **明确角色定义** | 每个 Agent 都有清晰的专家角色定位（如"资深后端开发专家"） |
+| **职责边界清晰** | 明确列出该 Agent 负责的职责（3-5 条） |
+| **输出格式强制约束** | 使用 `### FILE:` 标记 + 代码块格式，确保输出可被机器解析 |
+| **工程化约束** | 要求生成可直接运行的完整项目（含配置文件） |
+
+#### 1.2 各 Agent 的 System Prompt 要点
+
+- **FrontendAgent**：角色"资深前端开发专家"（React/Vue/Angular）；输出格式 `### FILE: frontend/App.tsx` + 代码块；工程约束：必须生成 `package.json` / `tsconfig.json` / `public/index.html`
+- **BackendAgent**：角色"资深后端开发专家"（Python/Java/Node.js）；输出格式 `### FILE: backend/main.py` + 代码块；特殊设计：要求在代码注释中嵌入 API 契约（供 FrontendAgent 消费）
+- **TestAgent**：角色"资深测试开发专家"（Jest + RTL / pytest）；输出格式 `### FILE: tests/test_api.py` + 代码块；工程约束：必须生成 `jest.config.js` / `setupTests.ts`
+- **AuditAgent**：角色"资深代码安全审计专家"（OWASP Top 10）；输出格式 **JSON**（每行一个 JSON 对象，含 `severity`/`category`/`message`/`suggestion`）
+
+#### 1.3 API 契约嵌入机制（前后端协同的关键）
+
+`BackendAgent` 的 System Prompt 要求在代码注释中嵌入结构化 API 契约：
+
+```python
+### API_CONTRACT_START
+endpoint: /api/login
+method: POST
+request_schema: {"username": "string", "password": "string"}
+response_schema: {"token": "string", "user": {"id": "int", "name": "string"}}
+### API_CONTRACT_END
+```
+
+`BackendAgent._extract_api_contracts()` 方法解析这些注释，存入 `api_contracts` 表。
+`FrontendAgent.execute()` 从数据库读取契约，注入到自己的 prompt 中，实现前后端契约驱动开发。
+
+#### 1.4 Rules 的实现方式
+
+项目中没有独立的 `rules/` 配置文件，规则通过三层机制实现：
+
+| 层级 | 实现方式 | 示例 |
+|------|---------|------|
+| **隐式规则** | System Prompt 中的指令 | "代码必须可直接运行" |
+| **显式规则** | 代码中的硬编码逻辑 | `_parse_llm_code_output()` 强制解析 `### FILE:` 格式 |
+| **配置规则** | `config.yaml` + `model/config.py` | `fallback_chain: ["hunyuan-lite", "hunyuan-standard"]` |
+
+---
+
+### 2. 上下文工程（Context Engineering）
+
+#### 2.1 上下文存储设计
+
+使用 SQLite 作为零部署的上下文数据库，设计四张核心表：
+
+```sql
+tasks         -- 任务记录（task_id, description, status, result, error）
+code_changes  -- 代码变更记录（task_id, agent_type, file_path, change_type, diff）
+api_contracts -- API 契约（task_id, endpoint, method, request_schema, response_schema）
+audit_reports -- 审计意见（task_id, severity, category, message, suggestion, file_path）
+```
+
+索引策略：在 `task_id` 字段上建立索引，加速上下文查询。
+
+#### 2.2 上下文传递机制
+
+```
+用户需求
+  │
+  ▼
+Coordinator.submit_task()
+  │  创建 main_task_id
+  │  为每个 Agent 创建子任务：{main_task_id}_{agent_type}
+  │  将共享 context（description, requirements）注入每个任务
+  ▼
+DAGScheduler.add_task(task_id, agent_type, dependencies, context)
+  │  将任务加入 DAG，建立依赖边
+  ▼
+DAGScheduler.get_runnable_tasks()
+  │  返回所有依赖已完成的任务（入度为 0）
+  ▼
+Coordinator.run() → agent.execute(task_id, context)
+  │  context = DAGScheduler.get_task_context(task_id)
+  │     ↓ 合并依赖任务的结果到 context:
+  │     context[f"{dep_agent_type}_result"] = dep_result
+  ▼
+下游 Agent 的 execute() 方法从 context 中读取上游结果
+```
+
+#### 2.3 迭代模式上下文收集
+
+`BaseAgent._collect_existing_code()` 方法：
+
+1. 扫描 `output_dir/{agent_type}/` 目录下所有已有文件
+2. 格式化为 `### FILE: {rel_path}\n{content}\n` 格式
+3. 注入到 LLM 的 user_prompt 中，实现"基于已有代码迭代修改"
+
+#### 2.4 Agent 执行 Trace 保存
+
+每次 Agent 执行后，完整的 LLM 输入输出会被保存到 `output_dir/traces/{agent_type}/{timestamp}_{task_id}.md`：
+
+```markdown
+# Agent Trace: backend
+
+## Token 用量
+| Step | 模型 | Prompt Tokens | ... |
+
+## 系统提示词 (System Prompt)
+...
+
+## 用户提示词 (User Prompt)
+...
+
+## LLM 原始输出 (Raw Response)
+...
+
+## 解析结果 (Parsed Result)
+- 生成/修改的文件: backend/main.py, backend/models.py
+- 提取的 API 契约: POST /api/login, GET /api/users
+```
+
+---
+
+### 3. 规约驱动开发（Spec-Driven Development）
+
+#### 3.1 设计理念
+
+项目支持从结构化需求文档（PDF/TXT/MD）中提取需求，驱动代码生成。
+
+#### 3.2 实现方式
+
+| 组件 | 文件路径 | 功能 |
+|------|---------|------|
+| `utils/pdf_reader.py` | PDF/TXT/MD 读取器 | 提取文本、清洗格式、分块处理大文档 |
+| `main.py --pdf` | CLI 参数 | 从 PDF 文件加载项目需求 |
+| 交互模式 `load` 命令 | 交互式加载 | 在对话中动态加载规约文档 |
+| `dataset/` | 测试数据集 | 存放示例规约文档，用于测试和演示 |
+
+#### 3.3 使用流程
+
+```bash
+# 方式 1：命令行直接指定 PDF
+python main.py --pdf docs/需求规格说明书.pdf "开发一个订单管理系统"
+
+# 方式 2：交互模式中加载
+python main.py
+>>> load docs/需求规格说明书.pdf
+>>> 请基于以上文档开发后端 API
+
+# 方式 3：继续已有项目 + 加载新需求 PDF
+python main.py --continue output/20260530_230000_xxx --pdf new_spec.pdf
+```
+
+---
+
+### 4. Skills 与 MCP
+
+#### 4.1 Skills（技能机制）
+
+当前项目**未使用独立的 Skills 机制**。各 Agent 的"技能"通过其 System Prompt 中的角色定义和职责描述来体现。
+
+未来可扩展方向：将 Agent 能力拆分为可插拔的 Skill 模块，通过配置文件动态组合。
+
+#### 4.2 MCP（Model Context Protocol）
+
+当前项目**未集成 MCP**。模型调用通过 **LiteLLM** 统一接口实现，支持：
+
+- 多模型切换（按 Agent 类型配置不同模型）
+- Fallback 链式降级（主模型失败时自动切换）
+- Token 用量追踪（每次调用记录 prompt/completion/total tokens）
+- 流式输出支持（`stream_chat()` 方法）
+
+---
+
+### 5. CodeBuddy Agent SDK 集成
+
+#### 5.1 架构
+
+```
+Coordinator / Agent
+       │
+       ▼
+CodeBuddyExecutor（静态方法类）
+       │
+       ▼  subprocess.run()
+CodeBuddy CLI
+       │
+       ▼
+沙箱环境（代码执行 / 测试运行 / 代码审查）
+```
+
+#### 5.2 封装的 CLI 命令
+
+| 方法 | CLI 命令 | 功能 |
+|------|---------|------|
+| `apply_code_edit()` | `codebuddy apply-edit` | 应用代码修改（将 LLM 生成的代码写入文件） |
+| `run_code()` | `codebuddy run-code` | 在沙箱中运行代码（支持 python/javascript/typescript） |
+| `run_tests()` | `codebuddy run-tests` | 运行测试套件 |
+| `review_code()` | `codebuddy review` | AI 代码审查（输出 JSON 格式审查意见） |
+| `get_suggestions()` | `codebuddy suggest` | 获取代码补全建议 |
+
+#### 5.3 配置与错误处理
+
+- CLI 路径和超时时间通过 `model/config.py` 中的 `CODEBUDDY_CONFIG` 配置
+- 超时控制：默认 60 秒，可通过参数覆盖
+- 错误处理：捕获 `subprocess.TimeoutExpired`（超时）和 `FileNotFoundError`（CLI 未安装）
+
+---
+
+### 6. 多 Agent 协同机制
+
+#### 6.1 协同架构
+
+```mermaid
+graph TD
+    User["用户需求"] --> Coord["Coordinator"]
+    Coord --> Selector["AgentSelector (LLM 分析)"]
+    Selector -->|"agents: [backend, frontend]"| Coord
+    Coord --> DAG["DAGScheduler"]
+    DAG -->|"task_xxx_backend (无依赖)"| Backend["BackendAgent"]
+    Backend -->|"API 契约 → DB"| DB[("SQLite")]
+    DAG -->|"task_xxx_frontend (依赖 backend)"| Frontend["FrontendAgent"]
+    DB -->|"读取 API 契约"| Frontend
+    DAG -->|"task_xxx_test (依赖 backend,frontend)"| Test["TestAgent"]
+    DAG -->|"task_xxx_audit (依赖所有)"| Audit["AuditAgent"]
+    Backend -->|"结果 → context"| Frontend
+    Frontend -->|"结果 → context"| Test
+    Test -->|"结果 → context"| Audit
+```
+
+#### 6.2 任务依赖与调度
+
+| 任务 | 依赖 | 说明 |
+|------|------|------|
+| `task_xxx_backend` | 无 | 最先执行，生成 API 和契约 |
+| `task_xxx_frontend` | `backend` | 读取后端契约，生成前端代码 |
+| `task_xxx_test` | `backend`, `frontend` | 读取前后端代码，生成测试 |
+| `task_xxx_audit` | `backend`, `frontend`, `test` | 审计所有代码 |
+
+DAG 调度器使用**拓扑排序**确定执行顺序，支持并行执行无依赖关系的任务。
+
+#### 6.3 失败级联机制
+
+当某个 Agent 执行失败时：
+
+1. `DAGScheduler.mark_failed(task_id)` 被调用
+2. `_cascade_failure(task_id)` 通过 **BFS 遍历**所有下游任务
+3. 所有下游任务被标记为 `failed`（避免死锁）
+4. 错误信息记录到数据库，包含级联取消的原因
+
+#### 6.4 智能 Agent 选择
+
+`AgentSelector` 使用轻量模型（frontend 配置的模型）分析用户需求：
+
+1. 构建包含用户需求和可选 Agent 列表的 prompt
+2. LLM 输出 JSON：`{"agents": ["backend", "frontend"], "reason": "..."}`
+3. `_fix_dependencies()` 自动修正依赖（如选中 frontend 但未选中 backend，则自动添加）
+
+#### 6.5 Token 用量汇总
+
+每次执行完成后，`Coordinator._collect_usage_summary()` 收集所有 Agent 的 token 用量：
+
+- 每个 Agent 的 `_usage_log` 记录每次 LLM 调用的详细信息
+- 汇总报告保存到 `output_dir/usage_summary.md`
+- 控制台打印格式化的汇总表格
+
+---
+
+### 7. CI/CD 流程详解
+
+#### 7.1 流水线全景
+
+```mermaid
+graph LR
+    A["Push / PR"] --> B["Lint & Format"]
+    B --> C["Type Check"]
+    C --> D["Tests"]
+    D --> E["Build"]
+    E --> F["✅ 通过"]
+    B -->|失败| G["❌ 失败通知"]
+    C -->|失败| G
+    D -->|失败| G
+```
+
+#### 7.2 各阶段详解
+
+| 阶段 | 工具 | 检查内容 | 失败处理 |
+|------|------|---------|---------|
+| **Lint & Format** | `black --check` | 代码格式是否符合 PEP 8 | 终止流水线 |
+| | `isort --check-only` | import 语句排序 | 终止流水线 |
+| | `flake8` | 语法错误、未使用变量、复杂度 | 终止流水线 |
+| **Type Check** | `mypy` | 类型注解一致性检查 | 终止流水线 |
+| **Tests** | `pytest` + `coverage` | 单元测试覆盖率（目标 >80%） | 终止流水线 |
+| **Build** | `python -m build` | 构建 wheel 包并验证导入 | 终止流水线 |
+
+#### 7.3 测试矩阵
+
+```yaml
+strategy:
+  matrix:
+    python-version: ["3.11", "3.12", "3.13"]
+```
+
+确保在三个 Python 版本下测试全部通过。
+
+#### 7.4 Mock API Key 策略
+
+CI 环境中的测试不依赖真实 LLM API 调用：
+
+```yaml
+- name: Run tests
+  env:
+    TENCENT_API_KEY: ci-mock-key
+    TENCENT_API_BASE: https://mock-api.example.com/v1
+  run: |
+    pytest tests/ -v --tb=short \
+      --ignore=agents --ignore=executor \
+      --ignore=output --ignore=dataset
+```
+
+测试聚焦于纯逻辑模块（DAG 调度、输出管理、配置验证、模块导入）。
+
+#### 7.5 覆盖率报告
+
+- 终端输出：`--cov-report=term`
+- XML 报告：`--cov-report=xml`（用于 Codecov 上传）
+- HTML 报告：`--cov-report=html`（本地查看）
+
+---
+
+## 🧪 测试
+
+```bash
+# 运行单元测试
+pytest tests/
+
+# 运行测试并生成覆盖率报告
+pytest --cov=agents --cov=coordinator --cov=model --cov=storage --cov-report=html
+```
+
+---
+
+## 🔄 CI/CD
+
+本项目使用 GitHub Actions 进行持续集成和持续部署，工作流配置位于 `.github/workflows/` 目录。
+
+### CI 流水线（`.github/workflows/ci.yml`）
+
+| 阶段 | 说明 | 触发条件 |
+|------|------|----------|
+| **Lint & Format** | black + isort + flake8 代码风格检查，VERSION 文件格式校验 | push / PR 到 main/master/develop |
+| **Type Check** | mypy 静态类型检查 | push / PR 到 main/master/develop |
+| **Tests** | pytest 单元测试 (Python 3.11/3.12/3.13) | push / PR 到 main/master/develop |
+| **Build** | 构建验证 | 前三个阶段通过后 |
+
+### CD 流水线（`.github/workflows/cd.yml`）
+
+CD 流水线在推送 git tag（以 `v` 开头）或手动触发时执行：
+
+| 阶段 | 说明 | 触发条件 |
+|------|------|----------|
+| **Validate** | 校验 VERSION 文件格式、版本号一致性、CHANGELOG 条目 | git tag v* / 手动触发 |
+| **Build** | 构建 wheel 包，twine 检查 | Validate 通过后 |
+| **Publish to Test PyPI** | 发布到 Test PyPI（可选） | Build 通过后 |
+| **Publish to PyPI** | 发布到正式 PyPI | Build 通过后 |
+| **Create GitHub Release** | 创建 GitHub Release，附上 wheel 包 | 发布到 PyPI 后 |
+
+### 发布流程
+
+1. 更新 `CHANGELOG.md`，将 `[Unreleased]` 内容移动到新版本条目
+2. 更新 `VERSION` 文件：
+   ```bash
+   python utils/version.py --bump patch  # 升级 patch 版本（如 0.1.0 -> 0.1.1）
+   # 或
+   python utils/version.py --bump minor  # 升级 minor 版本（如 0.1.0 -> 0.2.0）
+   # 或
+   python utils/version.py --bump major  # 升级 major 版本（如 0.1.0 -> 1.0.0）
+   ```
+3. 提交版本更新：
+   ```bash
+   git add VERSION CHANGELOG.md
+   git commit -m "chore: release v0.1.1"
+   git push origin develop
+   ```
+4. 创建并推送 git tag：
+   ```bash
+   git tag v0.1.1
+   git push origin v0.1.1
+   ```
+5. GitHub Actions CD 工作流自动触发，发布到 PyPI
+
+### 本地运行 CI 检查
+
+```bash
+# 格式检查
+black --check .
+isort --check-only .
+flake8 . --max-line-length=120
+
+# 类型检查
+pip install -e ".[dev]"
+mypy .
+
+# 运行测试
+TENCENT_API_KEY=sk-mock-key pytest tests/ -v
+
+# 校验版本号
+python utils/version.py --validate $(cat VERSION)
+```
+
+> 注：CI 中的测试聚焦于纯逻辑模块（DAG 调度、输出管理、配置验证、模块导入），不依赖真实 LLM API 调用。
+
+---
+
+## 📁 分支策略
+
+本项目采用 **Git Flow** 分支策略：
+
+- `main` - 生产分支，稳定版本
+- `develop` - 开发集成分支
+- `feature/*` - 功能分支
+- `bugfix/*` - Bug 修复分支
+- `hotfix/*` - 紧急修复分支
+
+### 开发流程
+
+```bash
+# 1. 切换到 develop 分支
+git checkout develop
+
+# 2. 创建功能分支
+git checkout -b feature/new-feature
+
+# 3. 开发并提交
+git add -A
+git commit -m "feat: 新功能描述"
+
+# 4. 推送到远程
+git push origin feature/new-feature
+
+# 5. 创建 Pull Request 合并到 develop
+```
+
+---
+
+## 🤝 贡献指南
+
+1. Fork 本项目
+2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 创建 Pull Request
+
+---
+
+## 📄 License
+
+MIT License
+
+---
+
+## 📧 联系方式
+
+- 作者: Your Name
+- 邮箱: your.email@example.com
+- GitHub: [@Kingsdom005](https://github.com/Kingsdom005)