{ "metadata": { "id": "ch16", "title": "第16章：代码 Agent", "volume": "vol5", "volume_title": "专项篇", "word_count": 3409, "difficulty": "intermediate", "prerequisites": [ "ch06", "ch09" ], "key_concepts": [ "概述：当 AI 学会写代码", "代码 Agent 的能力光谱", "代码 Agent 与传统 IDE 辅助的本质区别", "代码 Agent 的核心架构", "架构总览", "上下文管理：代码 Agent 的生命线", "工具集设计", "代码生成与补全", "从补全到生成：范式转变", "多文件代码生成", "代码审查与重构", "自动化代码审查", "智能代码重构", "Bug 检测与修复", "Agent 驱动的 Bug 修复流程" ], "learning_objectives": [], "estimated_tokens": 2045, "source_file": "vol5/ch16_代码Agent.md" }, "overview": "", "sections": [ { "id": "16.1", "title": "16.1 概述：当 AI 学会写代码", "level": 2, "content": "代码 Agent 是 Agent 技术在软件工程领域的深度应用。它不仅仅是\"AI 代码补全\"——那只是 NLP 的简单应用；真正的代码 Agent 是一个能够理解项目上下文、自主完成复杂编码任务的智能体。", "subsections": [ { "id": "16.1.1", "title": "16.1.1 代码 Agent 的能力光谱", "content": "- **代码补全**（Code Completion）：根据上下文预测下一个 Token，如 GitHub Copilot 的行内补全\n- **代码生成**（Code Generation）：根据自然语言描述生成完整函数或模块\n- **代码解释**（Code Explanation）：理解并解释现有代码的逻辑和意图\n- **代码重构**（Code Refactoring）：在保持行为不变的前提下改进代码结构\n- **Bug 检测与修复**（Bug Detection & Fix）：定位缺陷并提供修复方案\n- **代码审查**（Code Review）：系统性检查代码质量、安全性、性能\n- **项目脚手架**（Project Scaffolding）：从零搭建项目结构、配置、依赖" }, { "id": "16.1.2", "title": "16.1.2 代码 Agent 与传统 IDE 辅助的本质区别", "content": "| 维度 | 传统 IDE 辅助 | 代码 Agent |\n|------|--------------|-----------|\n| 交互模式 | 被动触发 | 主动规划与执行 |\n| 上下文范围 | 当前文件/光标位置 | 整个项目仓库 |\n| 任务粒度 | 行级/块级补全 | 功能级/模块级任务 |\n| 自主性 | 无 | 多步规划、工具调用、自我修正 |\n| 反馈循环 | 无 | 运行测试、读取错误、迭代修复 |" } ] }, { "id": "16.2", "title": "16.2 代码 Agent 的核心架构", "level": 2, "content": "", "subsections": [ { "id": "16.2.1", "title": "16.2.1 架构总览", "content": "" }, { "id": "16.2.2", "title": "16.2.2 上下文管理：代码 Agent 的生命线", "content": "上下文管理是代码 Agent 最关键的挑战。代码项目通常有数万甚至数十万行代码，远超 LLM 的上下文窗口。\n\n**分层上下文策略：**" }, { "id": "16.2.3", "title": "16.2.3 工具集设计", "content": "代码 Agent 的能力取决于其工具集。以下是生产级代码 Agent 的核心工具：\n\n\n**关键设计要点：**\n\n1. **路径安全**：所有文件操作必须验证路径不越界，防止路径遍历攻击\n2. **命令白名单**：终端执行只允许预定义的安全命令，禁止 `rm -rf` 等危险操作\n3. **输出截断**：限制命令输出和搜索结果长度，避免上下文爆炸\n4. **超时控制**：所有命令执行设置超时，防止死循环" } ] }, { "id": "16.3", "title": "16.3 代码生成与补全", "level": 2, "content": "", "subsections": [ { "id": "16.3.1", "title": "16.3.1 从补全到生成：范式转变", "content": "传统代码补全是\"填空题\"——已知上下文，预测下一行。而代码 Agent 的生成能力是\"作文题\"——给定需求描述，产出完整实现。\n\n{code}\n{code}" }, { "id": "16.3.2", "title": "16.3.2 多文件代码生成", "content": "真实项目中的代码生成通常涉及多个文件。Agent 需要理解项目结构，按依赖顺序分步生成：" } ] }, { "id": "16.4", "title": "16.4 代码审查与重构", "level": 2, "content": "", "subsections": [ { "id": "16.4.1", "title": "16.4.1 自动化代码审查", "content": "代码审查 Agent 需要像资深工程师一样思考——不仅检查语法，还要审查设计、安全、性能。\n\n{diff[:6000]}" }, { "id": "16.4.2", "title": "16.4.2 智能代码重构", "content": "重构 Agent 比审查更进一步——直接修改代码，并通过测试验证正确性：\n\n{original[:8000]}" } ] }, { "id": "16.5", "title": "16.5 Bug 检测与修复", "level": 2, "content": "", "subsections": [ { "id": "16.5.1", "title": "16.5.1 Agent 驱动的 Bug 修复流程", "content": "Bug 修复 Agent 需要：理解错误信息 → 追踪代码路径 → 定位根因 → 生成修复 → 验证修复。" }, { "id": "16.5.2", "title": "16.5.2 常见 Bug 模式库", "content": "维护 Bug 模式库可显著增强检测能力：" } ] }, { "id": "16.6", "title": "16.6 代码解释与文档生成", "level": 2, "content": "", "subsections": [ { "id": "16.6.1", "title": "16.6.1 智能代码解释", "content": "{code[:6000]}" }, { "id": "16.6.2", "title": "16.6.2 文档自动生成", "content": "{code}" } ] }, { "id": "16.7", "title": "16.7 项目脚手架生成", "level": 2, "content": "", "subsections": [ { "id": "16.7.1", "title": "16.7.1 从描述到完整项目", "content": "" } ] }, { "id": "16.8", "title": "16.8 生产级实践：Claude Code 与 Cursor 的 Agent 化", "level": 2, "content": "", "subsections": [ { "id": "16.8.1", "title": "16.8.1 Claude Code 的 Agentic Loop", "content": "Claude Code 代表了代码 Agent 的前沿实践：\n\n1. **Agentic Loop**：Agent 自主规划、执行、验证\n2. **Full Context**：读取整个仓库理解全局\n3. **Tool Use**：通过工具与项目交互\n4. **Self-Correction**：失败时自动分析、调整" }, { "id": "16.8.2", "title": "16.8.2 Cursor 风格的 IDE 集成模式", "content": "" } ] }, { "id": "16.9", "title": "16.9 最佳实践与常见陷阱", "level": 2, "content": "", "subsections": [ { "id": "16.9.1", "title": "16.9.1 最佳实践", "content": "**1. 分层上下文策略**\n- CRITICAL 层：当前编辑的文件及其直接依赖\n- HIGH 层：接口定义、类型声明\n- MEDIUM 层：项目配置、架构文档\n- 严格管理 Token 预算，为 LLM 回复预留空间\n\n**2. 增量修改优于全量生成**\n- 使用精确的字符串替换，而非重写整个文件\n- `replace_in_file(old_string, new_string)` 比 `write_file(whole_content)` 更安全\n- 修改前创建备份，失败时可回滚\n\n**3. 测试驱动验证**\n- 每次修改后运行测试，确保不引入回归\n- 先运行已有测试确认当前状态（baseline）\n- 修改后对比测试结果，只处理新增失败\n\n**4. 安全边界**\n- 文件操作：禁止路径遍历（`realpath` + 前缀检查）\n- 命令执行：白名单策略，禁止 shell 元字符拼接\n- 代码生成：拒绝生成包含恶意模式的代码\n\n**5. 用户确认机制**\n- 破坏性操作（删除文件、执行不可逆命令）前要求确认\n- 展示 diff 预览，让用户审核后再应用\n- 提供撤销能力（git stash 或文件备份）" }, { "id": "16.9.2", "title": "16.9.2 常见陷阱", "content": "**陷阱 1：上下文幻觉**\n- Agent 可能\"编造\"不存在的函数或 API\n- 缓解：强制 Agent 先用搜索工具验证函数是否存在\n\n**陷阱 2：过度重构**\n- Agent 可能把能用的代码\"优化\"到无法运行\n- 缓解：每次重构后必须运行测试；无测试的文件禁止重构\n\n**陷阱 3：依赖冲突**\n- Agent 生成的代码可能引入与项目不兼容的依赖\n- 缓解：读取现有依赖文件（requirements.txt / package.json），在约束内选择\n\n**陷阱 4：循环修正**\n- Agent 修复 A 时引入 B，修复 B 时又引入 A，陷入死循环\n- 缓解：设置最大迭代次数；记录已修复的问题列表\n\n**陷阱 5：忽略项目约定**\n- Agent 可能不遵循项目的编码规范和架构约定\n- 缓解：将 `.eslintrc`、`pyproject.toml` 等配置文件纳入上下文" } ] }, { "id": "16.10", "title": "16.10 总结", "level": 2, "content": "代码 Agent 是 Agent 技术最成熟的应用领域之一。其核心挑战不是\"能不能生成代码\"，而是如何：\n\n1. **理解上下文**：在有限 Token 预算内传递最相关的项目信息\n2. **保证正确性**：通过测试验证和自我审查确保生成代码的质量\n3. **安全可控**：在给予 Agent 能力的同时设置安全边界\n4. **渐进增强**：从补全到生成，从单文件到多文件，从辅助到自主\n\n未来的代码 Agent 将更加深入地集成开发工具链——从需求分析到代码编写、测试、部署、监控，形成完整的软件开发闭环。但核心原则不变：**Agent 是工具，开发者是决策者。** 最终的代码质量责任，永远在人而不在机器。", "subsections": [] }, { "id": "16.11", "title": "16.11 延伸阅读", "level": 2, "content": "1. **Claude Code 官方文档** — Anthropic 的 Agentic 编程助手设计理念\n2. **Cursor 文档** — IDE 集成式 AI 编程的最佳实践\n3. **Aider** — 开源终端代码 Agent，支持多种 LLM\n4. **SWE-bench** — 代码 Agent 的标准评测基准\n5. **HumanEval / MBPP** — 代码生成能力的评估数据集", "subsections": [] } ], "code_blocks": [ { "id": "code-1", "language": "text", "description": "代码 Agent 是 Agent 技术在软件工程领域的深度应用。它不仅仅是\"AI 代码补全\"——那只是 NLP 的简单应用；真正的代码 Agent 是一个能够理解项目上下文、自主完成复杂编码任务的智能", "code": "补全 → 生成 → 解释 → 重构 → Debug → 审查 → 架构设计 → 全流程开发\n │ │ │ │ │ │ │ │\n简单 单文件 理解 模式 定位 质量门 系统级 自主完成\n触发 级别 已有 级别 并修 禁 思考 完整项目\n 代码 优化 复问题 防护", "section_ref": "16.1.1", "runnable": false, "dependencies": [] }, { "id": "code-2", "language": "text", "description": "", "code": "┌─────────────────────────────────────────────────────┐\n│ 用户界面层 │\n│ IDE 插件 / CLI / Web IDE / 聊天界面 │\n└──────────────┬──────────────────────┬───────────────┘\n │ │\n┌──────────────▼──────────────────────▼───────────────┐\n│ Agent 编排层 │\n│ ┌─────────┐ ┌──────────┐ ┌─────────────────┐ │\n│ │ 任务规划 │ │ 上下文管理 │ │ 自我反思与修正 │ │\n│ │ Planner │ │ Context │ │ Reflector │ │\n│ │ │ │ Manager │ │ │ │\n│ └────┬────┘ └────┬─────┘ └────────┬────────┘ │\n└───────┼────────────┼─────────────────┼─────────────┘\n │ │ │\n┌───────▼────────────▼─────────────────▼─────────────┐\n│ 工具层 │\n│ ┌────────┐ ┌────────┐ ┌────────┐ ┌───────────┐ │\n│ │ 文件 │ │ 代码 │ │ 终端 │ │ 搜索 │ │\n│ │ 读写 │ │ 解析 │ │ 执行 │ │ 引擎 │ │\n│ └────────┘ └────────┘ └────────┘ └───────────┘ │\n│ ┌────────┐ ┌────────┐ ┌───────────────────────┐ │\n│ │ Git │ │ 包管理 │ │ LSP / 语言服务 │ │\n│ │ 操作 │ │ │ │ │ │\n│ └────────┘ └────────┘ └───────────────────────┘ │\n└─────────────────────────────────────────────────────┘\n │\n┌───────▼─────────────────────────────────────────────┐\n│ 项目环境层 │\n│ 文件系统 / 依赖管理 / 配置文件 / 测试框架 │\n└─────────────────────────────────────────────────────┘", "section_ref": "16.2.1", "runnable": false, "dependencies": [] }, { "id": "code-3", "language": "python", "description": "分层上下文策略：", "code": "from dataclasses import dataclass, field\nfrom enum import Enum\nfrom typing import Optional\nimport os\n\nclass ContextPriority(Enum):\n \"\"\"上下文优先级，用于决定哪些内容优先放入 Prompt\"\"\"\n CRITICAL = 1 # 当前编辑的文件、直接依赖\n HIGH = 2 # 相关接口定义、类型声明\n MEDIUM = 3 # 项目配置、架构说明\n LOW = 4 # 历史对话、相似代码片段\n\n@dataclass\nclass CodeContext:\n \"\"\"代码上下文单元\"\"\"\n file_path: str\n content: str\n priority: ContextPriority\n token_count: int = 0\n relevance_score: float = 0.0\n\n def __post_init__(self):\n # 粗略估算 Token 数（实际应使用 tokenizer）\n self.token_count = len(self.content) // 4\n\n@dataclass\nclass ContextManager:\n \"\"\"代码上下文管理器\"\"\"\n max_tokens: int = 128000\n reserved_for_response: int = 8000\n contexts: list[CodeContext] = field(default_factory=list)\n\n @property\n def available_tokens(self) -> int:\n used = sum(c.token_count for c in self.contexts)\n return self.max_tokens - self.reserved_for_response - used\n\n def add_context(self, ctx: CodeContext) -> bool:\n \"\"\"添加上下文，返回是否成功\"\"\"\n if ctx.token_count <= self.available_tokens:\n self.contexts.append(ctx)\n self.contexts.sort(key=lambda c: c.priority.value)\n return True\n return False\n\n def build_prompt_context(self) -> str:\n \"\"\"构建最终 Prompt 中的上下文\"\"\"\n sections = []\n for ctx in self.contexts:\n sections.append(\n f\"--- File: {ctx.file_path} ---\\n\"\n f\"```{self._get_language(ctx.file_path)}\\n\"\n f\"{ctx.content}\\n```\\n\"\n )\n return \"\\n\".join(sections)\n\n @staticmethod\n def _get_language(file_path: str) -> str:\n ext = os.path.splitext(file_path)[1].lower()\n lang_map = {\n '.py': 'python', '.js': 'javascript', '.ts': 'typescript',\n '.rs': 'rust', '.go': 'go', '.java': 'java',\n '.cpp': 'cpp', '.c': 'c', '.rb': 'ruby',\n }\n return lang_map.get(ext, '')", "section_ref": "16.2.2", "runnable": true, "dependencies": [] }, { "id": "code-4", "language": "python", "description": "代码 Agent 的能力取决于其工具集。以下是生产级代码 Agent 的核心工具：", "code": "from abc import ABC, abstractmethod\nfrom typing import Any\nimport subprocess\nimport os\n\nclass BaseTool(ABC):\n \"\"\"工具基类\"\"\"\n @property\n @abstractmethod\n def name(self) -> str: pass\n\n @property\n @abstractmethod\n def description(self) -> str: pass\n\n @abstractmethod\n def execute(self, **kwargs) -> Any: pass\n\n def to_schema(self) -> dict:\n \"\"\"转换为 OpenAI Function Calling 格式\"\"\"\n return {\n \"type\": \"function\",\n \"function\": {\n \"name\": self.name,\n \"description\": self.description,\n \"parameters\": self._get_parameters_schema()\n }\n }\n\n @abstractmethod\n def _get_parameters_schema(self) -> dict: pass\n\n\nclass FileReadTool(BaseTool):\n \"\"\"文件读取工具 — 带安全检查\"\"\"\n def __init__(self, working_dir: str, max_lines: int = 2000):\n self.working_dir = working_dir\n self.max_lines = max_lines\n\n @property\n def name(self) -> str:\n return \"read_file\"\n\n @property\n def description(self) -> str:\n return \"读取指定文件的内容，支持指定行范围。\"\n\n def execute(self, path: str, offset: int = 0, limit: int = None) -> str:\n full_path = os.path.join(self.working_dir, path)\n # 安全检查：防止路径遍历攻击\n real_path = os.path.realpath(full_path)\n if not real_path.startswith(os.path.realpath(self.working_dir)):\n return \"错误：不允许访问工作目录之外的文件\"\n try:\n with open(real_path, 'r', encoding='utf-8') as f:\n lines = f.readlines()\n limit = limit or self.max_lines\n selected = lines[offset:offset + limit]\n numbered = [\n f\"{i + offset + 1:>6}: {line.rstrip()}\"\n for i, line in enumerate(selected)\n ]\n return \"\\n\".join(numbered)\n except FileNotFoundError:\n return f\"错误：文件 {path} 不存在\"\n\n def _get_parameters_schema(self) -> dict:\n return {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\"type\": \"string\", \"description\": \"文件路径\"},\n \"offset\": {\"type\": \"integer\", \"description\": \"起始行号\", \"default\": 0},\n \"limit\": {\"type\": \"integer\", \"description\": \"读取行数\", \"default\": 2000}\n },\n \"required\": [\"path\"]\n }\n\n\nclass TerminalTool(BaseTool):\n \"\"\"终端命令执行工具 — 白名单安全策略\"\"\"\n def __init__(self, working_dir: str, timeout: int = 60):\n self.working_dir = working_dir\n self.timeout = timeout\n self.allowed_commands = [\n 'python', 'pip', 'npm', 'npx', 'cargo', 'go',\n 'git', 'ls', 'cat', 'grep', 'find', 'pytest',\n 'eslint', 'prettier', 'mypy', 'ruff'\n ]\n\n @property\n def name(self) -> str:\n return \"run_command\"\n\n @property\n def description(self) -> str:\n return \"在项目目录中执行终端命令，仅允许预定义的安全命令列表。\"\n\n def execute(self, command: str) -> str:\n first_word = command.strip().split()[0] if command.strip() else ''\n base_cmd = os.path.basename(first_word)\n if base_cmd not in self.allowed_commands:\n return f\"错误：命令 '{base_cmd}' 不在允许列表中\"\n try:\n result = subprocess.run(\n command, shell=True, cwd=self.working_dir,\n capture_output=True, text=True, timeout=self.timeout\n )\n output = []\n if result.stdout:\n output.append(result.stdout[:5000])\n if result.stderr:\n output.append(f\"[STDERR] {result.stderr[:3000]}\")\n if result.returncode != 0:\n output.append(f\"[退出码] {result.returncode}\")\n return \"\\n\".join(output) if output else \"(无输出)\"\n except subprocess.TimeoutExpired:\n return f\"错误：命令执行超时（{self.timeout}秒）\"\n except Exception as e:\n return f\"执行错误：{e}\"\n\n def _get_parameters_schema(self) -> dict:\n return {\n \"type\": \"object\",\n \"properties\": {\n \"command\": {\"type\": \"string\", \"description\": \"要执行的命令\"}\n },\n \"required\": [\"command\"]\n }\n\n\nclass CodeSearchTool(BaseTool):\n \"\"\"代码搜索工具\"\"\"\n def __init__(self, working_dir: str):\n self.working_dir = working_dir\n self.skip_dirs = {\n '.git', 'node_modules', '__pycache__',\n '.venv', 'target', 'dist', 'build'\n }\n\n @property\n def name(self) -> str:\n return \"search_code\"\n\n @property\n def description(self) -> str:\n return \"在项目中搜索代码，支持文件名搜索和内容正则搜索。\"\n\n def execute(self, pattern: str, file_pattern: str = None,\n max_results: int = 20) -> str:\n import re\n results = []\n regex = re.compile(pattern, re.IGNORECASE)\n for root, dirs, files in os.walk(self.working_dir):\n dirs[:] = [d for d in dirs if d not in self.skip_dirs]\n for fname in files:\n if file_pattern and not re.match(file_pattern, fname):\n continue\n fpath = os.path.join(root, fname)\n rel_path = os.path.relpath(fpath, self.working_dir)\n try:\n with open(fpath, 'r', encoding='utf-8', errors='ignore') as f:\n for i, line in enumerate(f, 1):\n if regex.search(line):\n results.append(f\"{rel_path}:{i}: {line.strip()[:120]}\")\n if len(results) >= max_results:\n return \"\\n\".join(results)\n except (IOError, OSError):\n continue\n return \"\\n\".join(results) if results else \"(未找到匹配)\"\n\n def _get_parameters_schema(self) -> dict:\n return {\n \"type\": \"object\",\n \"properties\": {\n \"pattern\": {\"type\": \"string\", \"description\": \"搜索模式（正则表达式）\"},\n \"file_pattern\": {\"type\": \"string\", \"description\": \"文件名过滤\"},\n \"max_results\": {\"type\": \"integer\", \"description\": \"最大结果数\", \"default\": 20}\n },\n \"required\": [\"pattern\"]\n }", "section_ref": "16.2.3", "runnable": true, "dependencies": [ "subprocess" ] }, { "id": "code-5", "language": "python", "description": "传统代码补全是\"填空题\"——已知上下文，预测下一行。而代码 Agent 的生成能力是\"作文题\"——给定需求描述，产出完整实现。", "code": "from dataclasses import dataclass\n\n@dataclass\nclass GenerationRequest:\n description: str # 自然语言描述\n language: str # 目标语言\n existing_code: str = \"\" # 已有代码\n style_guide: str = \"\" # 编码风格指南\n tests_required: bool = True\n\n@dataclass\nclass GenerationResult:\n code: str\n explanation: str\n test_code: str = \"\"\n dependencies: list[str] = None\n confidence: float = 0.0\n\n\nclass AgentCodeGenerator:\n \"\"\"基于 Agent 的代码生成器\"\"\"\n\n def __init__(self, llm_client, context_manager):\n self.llm = llm_client\n self.context = context_manager\n\n def generate(self, request: GenerationRequest) -> GenerationResult:\n \"\"\"生成代码的完整流程\"\"\"\n # Step 1: 任务分析\n task_plan = self._analyze_task(request)\n # Step 2: 收集上下文\n relevant_ctx = self.context.select_for_task(request.description)\n # Step 3: 生成代码\n code = self._generate_code(request, task_plan, relevant_ctx)\n # Step 4: 自我审查\n reviewed_code = self._self_review(code, request)\n # Step 5: 生成测试\n test_code = \"\"\n if request.tests_required:\n test_code = self._generate_tests(reviewed_code, request.language)\n return GenerationResult(\n code=reviewed_code,\n explanation=task_plan['approach'],\n test_code=test_code,\n confidence=task_plan.get('confidence', 0.8)\n )\n\n def _analyze_task(self, request: GenerationRequest) -> dict:\n \"\"\"分析任务，生成实现计划\"\"\"\n prompt = f\"\"\"分析以下代码生成任务。\n\n需求：{request.description}\n语言：{request.language}\n\n输出 JSON：\n{{\n \"complexity\": \"simple|medium|complex\",\n \"approach\": \"实现思路\",\n \"edge_cases\": [\"边界情况\"],\n \"confidence\": 0.8\n}}\"\"\"\n response = self.llm.generate(prompt)\n import json\n try:\n return json.loads(response)\n except json.JSONDecodeError:\n return {\"complexity\": \"medium\", \"approach\": response, \"confidence\": 0.6}\n\n def _generate_code(self, request, plan, contexts) -> str:\n ctx_text = \"\\n\\n\".join(\n f\"// {c.file_path}\\n{c.content}\" for c in contexts[:5]\n )\n prompt = f\"\"\"根据需求生成 {request.language} 代码。\n\n需求：{request.description}\n思路：{plan['approach']}\n复杂度：{plan['complexity']}\n\n上下文：\n{ctx_text}\n\n要求：完整可运行、遵循最佳实践、包含类型注解和文档。\"\"\"\n return self.llm.generate(prompt)\n\n def _self_review(self, code: str, request: GenerationRequest) -> str:\n \"\"\"自我审查生成的代码\"\"\"\n prompt = f\"\"\"审查以下 {request.language} 代码：\n1. 逻辑错误 2. 安全问题 3. 性能问题 4. 风格 5. 是否满足需求\n\n需求：{request.description}\n", "section_ref": "16.3.1", "runnable": true, "dependencies": [] }, { "id": "code-6", "language": "text", "description": "{code}", "code": "\n有问题直接输出修正后的完整代码，没问题输出原代码。\"\"\"\n return self.llm.generate(prompt)\n\n def _generate_tests(self, code: str, language: str) -> str:\n prompt = f\"\"\"为以下 {language} 代码生成单元测试，覆盖正常和边界情况。\n", "section_ref": "16.3.1", "runnable": false, "dependencies": [] }, { "id": "code-7", "language": "text", "description": "{code}", "code": "\n只输出测试代码。\"\"\"\n return self.llm.generate(prompt)", "section_ref": "16.3.1", "runnable": false, "dependencies": [] }, { "id": "code-8", "language": "python", "description": "真实项目中的代码生成通常涉及多个文件。Agent 需要理解项目结构，按依赖顺序分步生成：", "code": "@dataclass\nclass FileSpec:\n path: str\n purpose: str\n depends_on: list[str]\n content: str = None\n\nclass MultiFileGenerator:\n \"\"\"多文件代码生成器\"\"\"\n\n def generate_module(self, module_name: str, description: str,\n language: str) -> list[FileSpec]:\n # Step 1: 规划文件结构\n file_specs = self._plan_file_structure(module_name, description, language)\n # Step 2: 按依赖顺序生成\n generated = []\n for spec in file_specs:\n dep_contents = {\n g.path: g.content for g in generated\n if g.path in spec.depends_on\n }\n spec.content = self._generate_single_file(spec, dep_contents, language)\n generated.append(spec)\n return generated\n\n def _plan_file_structure(self, module_name, description, language):\n \"\"\"通过 LLM 规划模块文件结构\"\"\"\n prompt = f\"\"\"为 {language} 模块规划文件结构。\n\n模块：{module_name}\n功能：{description}\n\n输出 JSON 文件列表：[{{\"path\": \"...\", \"purpose\": \"...\", \"depends_on\": [\"...\"]}}]\"\"\"\n # 实际实现需解析 LLM 返回的 JSON\n ...", "section_ref": "16.3.2", "runnable": true, "dependencies": [] }, { "id": "code-9", "language": "python", "description": "代码审查 Agent 需要像资深工程师一样思考——不仅检查语法，还要审查设计、安全、性能。", "code": "from enum import Enum\n\nclass Severity(Enum):\n INFO = \"info\"\n WARNING = \"warning\"\n ERROR = \"error\"\n CRITICAL = \"critical\"\n\nclass ReviewCategory(Enum):\n SECURITY = \"安全\"\n PERFORMANCE = \"性能\"\n CORRECTNESS = \"正确性\"\n DESIGN = \"设计\"\n\n@dataclass\nclass ReviewIssue:\n file_path: str\n line_number: int\n severity: Severity\n category: ReviewCategory\n title: str\n description: str\n suggestion: str\n\n@dataclass\nclass ReviewReport:\n issues: list[ReviewIssue]\n summary: str\n overall_score: float\n files_reviewed: int\n\n\nclass CodeReviewAgent:\n \"\"\"代码审查 Agent — 多维度审查\"\"\"\n\n REVIEW_DIMENSIONS = {\n ReviewCategory.SECURITY: \"\"\"检查：SQL 注入、XSS、硬编码密钥、\n不安全反序列化、路径遍历、权限校验缺失\"\"\",\n ReviewCategory.PERFORMANCE: \"\"\"检查：N+1 查询、不必要嵌套循环、\n内存分配、同步阻塞、缓存缺失\"\"\",\n ReviewCategory.CORRECTNESS: \"\"\"检查：空值处理、边界条件、\n竞态条件、异常遗漏、资源泄漏\"\"\",\n ReviewCategory.DESIGN: \"\"\"检查：单一职责、过度耦合、\n魔法数字、代码重复、缺少抽象\"\"\",\n }\n\n def review_diff(self, diff_content: str,\n file_context: dict[str, str] = None) -> ReviewReport:\n \"\"\"审查 Git Diff\"\"\"\n all_issues = []\n for category, prompt_prefix in self.REVIEW_DIMENSIONS.items():\n issues = self._review_dimension(\n diff_content, category, prompt_prefix, file_context\n )\n all_issues.extend(issues)\n\n score = self._calculate_score(all_issues)\n summary = self._generate_summary(all_issues, score)\n return ReviewReport(\n issues=all_issues, summary=summary,\n overall_score=score,\n files_reviewed=len(file_context or {})\n )\n\n def _review_dimension(self, diff, category, prompt_prefix, file_context):\n \"\"\"按单维度审查 — 返回问题列表\"\"\"\n context_text = \"\"\n if file_context:\n for path, content in list(file_context.items())[:3]:\n context_text += f\"\\n--- {path} ---\\n{content[:1500]}\\n\"\n\n prompt = f\"\"\"{prompt_prefix}\n\n代码变更：", "section_ref": "16.4.1", "runnable": true, "dependencies": [] }, { "id": "code-10", "language": "text", "description": "{diff[:6000]}", "code": "{context_text}\n\n输出 JSON 问题列表（无问题则为空数组）：\n[{{\"file_path\":\"...\", \"line_number\":42, \"severity\":\"warning\",\n\"title\":\"...\", \"description\":\"...\", \"suggestion\":\"...\"}}]\"\"\"\n # 解析 LLM 返回并构建 ReviewIssue 列表\n ...\n\n def _calculate_score(self, issues: list[ReviewIssue]) -> float:\n deductions = {\n Severity.CRITICAL: 3.0, Severity.ERROR: 2.0,\n Severity.WARNING: 1.0, Severity.INFO: 0.2,\n }\n total = sum(deductions.get(i.severity, 0) for i in issues)\n return max(0.0, 10.0 - total)", "section_ref": "16.4.1", "runnable": false, "dependencies": [] }, { "id": "code-11", "language": "python", "description": "重构 Agent 比审查更进一步——直接修改代码，并通过测试验证正确性：", "code": "class RefactoringAgent:\n \"\"\"智能重构 Agent\"\"\"\n\n REFACTORING_PATTERNS = {\n \"extract_function\": \"提取函数：将重复或过长的代码块提取为独立函数\",\n \"simplify_conditional\": \"简化条件：简化复杂的 if/else 逻辑\",\n \"eliminate_duplicate\": \"消除重复：识别并合并重复代码\",\n \"type_annotation\": \"添加类型注解：为函数和变量添加类型提示\",\n }\n\n def apply_refactoring(self, file_path: str, pattern: str,\n target: str) -> dict:\n \"\"\"应用重构并通过测试验证\"\"\"\n original = self.file_tools.read(file_path)\n\n # 生成重构后的代码\n prompt = f\"\"\"对以下代码应用「{pattern}」重构。\n\n目标区域：{target}", "section_ref": "16.4.2", "runnable": true, "dependencies": [] }, { "id": "code-12", "language": "text", "description": "{original[:8000]}", "code": "\n重构说明：{self.REFACTORING_PATTERNS.get(pattern, pattern)}\n要求：只修改目标区域，功能完全不变。输出完整文件。\"\"\"\n\n new_content = self.llm.generate(prompt)\n\n # 写入并验证\n self.file_tools.write(file_path, new_content)\n test_result = self.terminal.execute(\"pytest -x -q 2>&1 | head -50\")\n\n if \"passed\" not in test_result.lower() or \"failed\" in test_result.lower():\n self.file_tools.write(file_path, original) # 回滚\n return {\"success\": False, \"reason\": \"测试失败，已回滚\"}\n\n return {\"success\": True, \"message\": f\"成功应用 {pattern}\"}", "section_ref": "16.4.2", "runnable": false, "dependencies": [] }, { "id": "code-13", "language": "python", "description": "Bug 修复 Agent 需要：理解错误信息 → 追踪代码路径 → 定位根因 → 生成修复 → 验证修复。", "code": "@dataclass\nclass BugReport:\n error_message: str\n stack_trace: str = \"\"\n reproduction_steps: str = \"\"\n expected_behavior: str = \"\"\n actual_behavior: str = \"\"\n\n@dataclass\nclass BugFix:\n diagnosis: str\n root_cause_file: str\n root_cause_line: int\n fix_description: str\n fix_code: str\n confidence: float\n\n\nclass BugFixAgent:\n \"\"\"Bug 检测与修复 Agent\"\"\"\n\n def diagnose_and_fix(self, bug: BugReport) -> BugFix:\n # 1. 分析错误信息\n analysis = self._analyze_error(bug)\n # 2. 收集相关代码\n files = self._collect_relevant_code(bug, analysis)\n # 3. 定位根因\n root_cause = self._locate_root_cause(bug, files, analysis)\n # 4. 生成修复\n fix = self._generate_fix(bug, root_cause, files)\n # 5. 验证修复\n return self._verify_fix(fix)\n\n def _analyze_error(self, bug: BugReport) -> str:\n prompt = f\"\"\"分析错误信息，推断原因。\n\n错误：{bug.error_message}\n堆栈：{bug.stack_trace[:3000]}\n复现步骤：{bug.reproduction_steps}\n\n输出：错误类型、涉及的模块、排查方向。\"\"\"\n return self.llm.generate(prompt)\n\n def _collect_relevant_code(self, bug, analysis):\n \"\"\"从堆栈跟踪中提取文件路径，读取相关代码\"\"\"\n import re\n files = {}\n paths = re.findall(r'File \"([^\"]+)\"', bug.stack_trace)\n for p in paths:\n content = self.tools['file'].execute(path=p)\n if content and \"错误\" not in content:\n files[p] = content\n return files\n\n def _locate_root_cause(self, bug, files, analysis):\n \"\"\"通过 LLM 定位根因\"\"\"\n files_text = \"\\n\".join(f\"=== {p} ===\\n{c[:4000]}\" for p, c in files.items())\n prompt = f\"\"\"根据错误和代码，定位根因。\n\n错误：{bug.error_message}\n分析：{analysis}\n\n代码：\n{files_text}\n\n输出 JSON：{{\"root_cause_file\":\"...\", \"root_cause_line\":42,\n\"explanation\":\"...\", \"fix_direction\":\"...\"}}\"\"\"\n import json\n response = self.llm.generate(prompt)\n try:\n return json.loads(response)\n except json.JSONDecodeError:\n return {\"explanation\": response, \"confidence\": 0.3}", "section_ref": "16.5.1", "runnable": true, "dependencies": [] }, { "id": "code-14", "language": "python", "description": "维护 Bug 模式库可显著增强检测能力：", "code": "BUG_PATTERNS = [\n {\n \"pattern\": \"unhashable_type_in_set\",\n \"description\": \"不可哈希类型放入 set 或 dict 键\",\n \"detection\": r\"TypeError.*unhashable type\",\n \"auto_fix\": \"使用 frozenset 或 tuple 替代\"\n },\n {\n \"pattern\": \"off_by_one\",\n \"description\": \"循环边界或索引偏移错误\",\n \"detection\": r\"IndexError.*out of range\",\n \"auto_fix\": \"检查 range() 和 slice 的边界\"\n },\n {\n \"pattern\": \"null_reference\",\n \"description\": \"空值解引用\",\n \"detection\": r\"AttributeError.*NoneType\",\n \"auto_fix\": \"添加 None 检查或 Optional 类型\"\n },\n {\n \"pattern\": \"resource_leak\",\n \"description\": \"文件/连接未正确关闭\",\n \"detection\": r\"open\\(.*[^:]with\",\n \"auto_fix\": \"使用 with 语句\"\n },\n]", "section_ref": "16.5.2", "runnable": true, "dependencies": [] }, { "id": "code-15", "language": "python", "description": "", "code": "class CodeExplainer:\n \"\"\"根据受众调整解释深度\"\"\"\n\n LEVELS = {\n \"beginner\": \"用类比帮助理解，避免术语\",\n \"intermediate\": \"解释实现细节和设计决策\",\n \"expert\": \"分析架构权衡和性能特征\",\n }\n\n def explain(self, code: str, language: str = \"python\",\n level: str = \"intermediate\") -> str:\n style = self.LEVELS[level]\n prompt = f\"\"\"解释以下 {language} 代码。受众：{level}（{style}）\n", "section_ref": "16.6.1", "runnable": true, "dependencies": [] }, { "id": "code-16", "language": "text", "description": "{code[:6000]}", "code": "\n格式：\n## 功能概述\n## 工作原理（逐步）\n## 关键概念\n## 设计要点\"\"\"\n return self.llm.generate(prompt)", "section_ref": "16.6.1", "runnable": false, "dependencies": [] }, { "id": "code-17", "language": "python", "description": "", "code": "class DocGenerator:\n \"\"\"文档生成 Agent\"\"\"\n\n def generate_docstring(self, code: str, language: str) -> str:\n \"\"\"Google 风格文档字符串\"\"\"\n prompt = f\"\"\"为以下代码生成 Google 风格文档字符串。\n包含 Args, Returns, Raises, Example。\n", "section_ref": "16.6.2", "runnable": true, "dependencies": [] }, { "id": "code-18", "language": "text", "description": "{code}", "code": "\n直接输出文档字符串（含三引号）。\"\"\"\n return self.llm.generate(prompt)\n\n def generate_readme(self, project_name: str,\n description: str, files_info: str) -> str:\n prompt = f\"\"\"为项目生成 README.md。\n\n项目：{project_name}\n描述：{description}\n文件信息：{files_info}\n\n格式：标题、描述、功能、安装、快速开始、配置、API、贡献。\"\"\"\n return self.llm.generate(prompt)", "section_ref": "16.6.2", "runnable": false, "dependencies": [] }, { "id": "code-19", "language": "python", "description": "", "code": "@dataclass\nclass ProjectSpec:\n name: str\n description: str\n tech_stack: str\n features: list[str]\n deployment: str = \"docker\"\n testing: str = \"pytest\"\n\nclass ProjectScaffolder:\n \"\"\"项目脚手架 Agent\"\"\"\n\n def scaffold(self, spec: ProjectSpec) -> dict:\n # 1. 规划结构\n structure = self._plan_structure(spec)\n # 2. 生成源文件\n created = []\n for f in structure['files']:\n content = self._generate_file(f, spec)\n self.file.write(f['path'], content)\n created.append(f['path'])\n # 3. 生成配置（pyproject.toml, Dockerfile, .gitignore 等）\n configs = self._generate_configs(spec)\n for path, content in configs.items():\n self.file.write(path, content)\n created.append(path)\n # 4. 安装依赖并验证\n return {\n \"project\": spec.name,\n \"files\": created,\n \"install\": self.terminal.execute(\"pip install -r requirements.txt\"),\n }\n\n def _generate_configs(self, spec: ProjectSpec) -> dict[str, str]:\n configs = {}\n if 'python' in spec.tech_stack.lower():\n configs['pyproject.toml'] = self._gen_pyproject(spec)\n configs['requirements.txt'] = self._gen_requirements(spec)\n if 'docker' in spec.deployment:\n configs['Dockerfile'] = self._gen_dockerfile(spec)\n configs['docker-compose.yml'] = self._gen_compose(spec)\n configs['.gitignore'] = self._gen_gitignore(spec)\n configs['README.md'] = self._gen_readme(spec)\n return configs", "section_ref": "16.7.1", "runnable": true, "dependencies": [] }, { "id": "code-20", "language": "python", "description": "4. Self-Correction：失败时自动分析、调整", "code": "class AgenticCodeAssistant:\n \"\"\"模拟 Claude Code 风格的 Agentic Loop\"\"\"\n\n def __init__(self, llm_client, working_dir: str):\n self.llm = llm_client\n self.tools = self._setup_tools(working_dir)\n self.history: list[dict] = []\n self.max_iterations = 20\n\n def run(self, task: str) -> str:\n self.history = [\n {\"role\": \"system\", \"content\": self._system_prompt()},\n {\"role\": \"user\", \"content\": task}\n ]\n for _ in range(self.max_iterations):\n response = self.llm.chat(self.history)\n if not self._needs_tool_call(response):\n return response # 任务完成\n tool_results = self._execute_tools(response)\n self.history.append({\"role\": \"assistant\", \"content\": response})\n self.history.append({\"role\": \"user\", \"content\": tool_results})\n return \"达到最大迭代次数。\"\n\n def _system_prompt(self) -> str:\n return \"\"\"你是高级编程助手。工作流程：\n1. 理解需求 → 2. 阅读代码 → 3. 制定计划 →\n4. 逐步实现 → 5. 运行测试 → 6. 自我修正\n\n原则：最小化修改，修改后必须验证，不确定先问。\"\"\"", "section_ref": "16.8.1", "runnable": true, "dependencies": [] }, { "id": "code-21", "language": "text", "description": "", "code": "┌─────────────────────────────────────────┐\n│ Cursor / IDE │\n│ ┌──────────┐ ┌──────────┐ ┌───────┐ │\n│ │ Tab补全 │ │ Chat │ │Composer│ │\n│ │ 行内预测 │ │ 上下文对话│ │ 多文件 │ │\n│ └─────┬────┘ └─────┬────┘ └───┬───┘ │\n│ │ │ │ │\n│ ┌─────▼─────────────▼──────────▼───┐ │\n│ │ Context Engine │ │\n│ │ 嵌入索引 + 相关性检索 + │ │\n│ │ 语义去重 + Token 预算管理 │ │\n│ └─────────────┬───────────────────┘ │\n│ │ │\n│ ┌─────────────▼───────────────────┐ │\n│ │ Codebase Index │ │\n│ │ AST解析 + 向量索引 + 符号表 │ │\n│ └─────────────────────────────────┘ │\n└─────────────────────────────────────────┘", "section_ref": "16.8.2", "runnable": false, "dependencies": [] } ], "tables": [ { "headers": [ "维度", "传统 IDE 辅助", "代码 Agent" ], "data": [ [ "交互模式", "被动触发", "主动规划与执行" ], [ "上下文范围", "当前文件/光标位置", "整个项目仓库" ], [ "任务粒度", "行级/块级补全", "功能级/模块级任务" ], [ "自主性", "无", "多步规划、工具调用、自我修正" ], [ "反馈循环", "无", "运行测试、读取错误、迭代修复" ] ] } ], "key_takeaways": [], "common_pitfalls": [], "related_chapters": [ "ch06", "ch09", "ch27" ] }