3.1 为什么需要本地 Agent

本地 Agent 的价值不是“回答更聪明”，而是进入了真实工程环境。

它能做网页对话做不了的事

能力	意义
读文件	不需要你复制粘贴上下文
搜索代码	能找调用链、相似实现、测试位置
修改文件	直接生成可审查 diff
运行命令	用测试、lint、build 验证结果
读取规范	自动加载 AGENTS.md / CLAUDE.md
管理多轮修复	命令失败后能继续定位
接工具	通过 MCP、skills、hooks 扩展能力

本手册里的主力 CLI

本手册默认把三类工具作为本地 Agent 主体：

工具	核心定位
Claude Code	成熟生态和复杂任务协作，适合 skills、hooks、subagents、MCP 组合
Codex	工程执行和验证闭环，适合明确委派、测试、review 和 OpenAI 生态
OpenCode	开放多模型 TUI，适合 provider 切换、本地模型、LSP 和自定义 agent

Gemini CLI 只作为辅助位：适合大上下文资料整理、免费额度探索和第二意见。它不是本手册训练本地开发闭环的主线。

本地 Agent 的工作方式

一个正常任务不应该是：

sequenceDiagram
  participant User as 用户
  participant Agent
  User->>Agent: 帮我做一下
  Agent->>Agent: 开始乱改

而应该是：

sequenceDiagram
  participant User as 用户
  participant Agent
  User->>Agent: 给目标、范围、验收标准
  Agent->>Agent: 先读代码，不写文件
  Agent-->>User: 输出计划和风险
  User->>Agent: 审计划
  Agent->>Agent: 小步改动
  Agent->>Agent: 跑验证
  User->>Agent: 看 diff

这就是工程化使用和随缘使用的区别。

本地 Agent 的风险

本地 Agent 有真实文件和命令能力，因此也有真实风险：

• 改错文件。
• 删除重要内容。
• 跑高风险命令。
• 引入依赖。
• 修改配置。
• 测试没过却说完成。

所以本地 Agent 必须配合：

• 明确任务边界。
• 最小权限。
• Git diff review。
• 验证命令。
• 规范文件。

最小启动策略

第一次用本地 Agent，不要做大任务。

选择一个：

• 小 bug。
• 单文件样式调整。
• 补一个测试。
• 写一个脚本。
• 整理 README。

用它练习完整闭环，而不是追求大而全。