1. 项目概述为AI编码助手引入“子进程”思维如果你用过像Antigravity、Cursor这类AI编码助手肯定经历过这种抓狂时刻你让它修复一个复杂的Bug它先是读取了十几个相关文件然后运行了测试接着分析了一堆日志最后在你满怀期待时它突然“失忆”了开始重复之前的问题或者干脆忘记了最初的目标。这不是它笨而是它的“工作内存”——上下文窗口——被塞爆了。每一次文件读取、每一条命令输出、每一个错误堆栈都在无情地挤占它用来思考和推理的宝贵空间。spawn-agent这个技能就是为了根治这个问题而生的。它的核心思想非常程序员主代理Orchestrator负责高层决策和规划而将具体的、脏活累活式的执行任务委托给一个独立的“子进程”——也就是另一个AI代理Worker去完成。你可以把主代理想象成你的技术总监它了解整个项目的架构、业务逻辑和最终目标。而spawn-agent就是它手下的一个得力工具能让它随时召唤一个专注的“高级工程师”Gemini CLI或Codex CLI去处理一个具体的、边界清晰的任务比如“重构auth.service.ts里的JWT验证函数”、“统计src/目录下所有的TODO注释并分类”、“分析packages/backend的依赖关系图”。这个“高级工程师”会在一个全新的、干净的环境中工作。它只看到与当前任务相关的文件和指令心无旁骛地写代码、跑测试、出结果。完成后它把一份简洁的报告和修改后的代码如果需要交还给“技术总监”。技术总监的脑子里始终保持着对项目全景的清晰认知没有被各种中间过程的噪音污染。这样一来主代理的“内存”利用率从捉襟见肘的25%提升到了游刃有余的40%以上它能持续进行有效的宏观思考和复杂编排。我最初接触这个想法时觉得它简直是打开了新世界的大门。我们总在抱怨AI的上下文不够长但spawn-agent提供了一种更优雅的解决方案不是无脑地堆叠上下文长度那只会让成本飙升且效率递减而是通过架构设计让AI学会“分工协作”。这特别适合我们这些需要处理大型、复杂项目的开发者无论是全栈应用的重构还是微服务系统的调试都能显著提升AI助手的可用性和产出质量。2. 核心设计思路从单线程到多代理协作2.1 理解上下文污染的根源要理解spawn-agent的价值得先看清问题本质。传统的AI编码助手工作模式是“单线程阻塞式”的。你给它一个任务它必须在自己唯一的上下文里完成所有步骤理解需求、浏览代码、编写修改、执行命令、分析结果。这个过程会产生大量中间态信息。举个例子你让AI“给用户登录接口添加速率限制”。它可能会读取login.controller.ts15%上下文。读取user.service.ts以理解用户查询逻辑15%。运行npm test看看现有测试是否通过20%的测试输出日志。发现一个无关的测试失败于是去读test-setup.js10%。编写新的速率限制中间件代码。再次运行测试输出新的结果20%。到第6步时最初的指令和login.controller.ts的细节可能已经被挤到上下文窗口的边缘甚至被“遗忘”了。AI可能会开始纠结于那个无关的测试失败或者忘记速率限制的具体规则。这就是上下文污染导致的“任务漂移”。spawn-agent的设计哲学是关注点分离。它将“规划与审查”Orchestration和“执行与验证”Execution这两个关注点分离开交给两个不同的代理实例处理。每个实例拥有独立且纯净的上下文专事专办。2.2 Orchestrator-Worker 模型详解这个模型借鉴了分布式系统中常见的主从Master-Worker或管理者-工作者Manager-Worker模式。1. Orchestrator协调者/主代理角色项目总指挥。它由你直接对话的AI助手如Antigravity扮演。核心职责需求分析理解你的原始指令拆解出可以独立委托的子任务。任务规划定义子任务的目标、范围、输入文件和约束条件。Worker调度决定调用哪个WorkerGemini 还是 Codex以何种模式安全、自动等执行。结果集成与审查接收Worker的输出验证其正确性将更改集成回主项目视图并向你汇报。2. Worker工作者/子代理角色特种兵。由spawn-agent脚本启动的Gemini CLI或Codex CLI实例扮演。核心职责专注执行在一个全新的会话中只关注Orchestrator下达的单一任务。本地操作根据任务要求读取指定文件编写或修改代码在项目目录中运行命令如构建、测试、Lint。结果交付将执行结果成功/失败、修改摘要、控制台输出以结构化的格式返回给Orchestrator。3. 协议与边界两者之间通过一个精心定义的“任务提示词”Prompt进行通信。这个提示词就是一份极其清晰的工作说明书SOW它必须包含绝对目标要做什么例如修复api/users/route.ts中第45行的空指针异常精确范围能碰哪些文件例如仅限api/users/目录下的.ts文件严格约束绝对不能做什么例如不得修改数据库模式、不得更改API响应格式交付格式结果长什么样例如提供修改后的代码块并附上npm test通过的结果截图因为Worker是“无头”的headless它无法像Orchestrator一样向你提问澄清。因此编写一份滴水不漏的任务提示词是成功使用spawn-agent的关键技能。模糊的指令会导致Worker要么僵住要么做出破坏性的更改。2.3 与简单“/命令”或插件的本质区别你可能会问这和我在ChatGPT里用个“/code”指令或者在IDE里装个AI插件有什么区别区别在于上下文隔离的彻底性。普通AI指令/插件它们仍然运行在同一个AI会话上下文中。你让插件“运行测试”它的输出会立刻追加到你当前的对话里继续占用上下文。本质上这只是在同一个线程里调用了不同的函数。spawn-agent它通过系统调用物理上启动了一个全新的、独立的CLI进程gemini或codex exec。这个新进程拥有从零开始的上下文。它完成任务后进程结束上下文销毁。只有一份精炼的成果被送回到主会话。这是一种进程级别的隔离确保了污染的绝对避免。这就好比前者是让一个工程师在堆满图纸的办公桌上同时处理五件事后者是项目经理把其中一件具体的事打印成工单交给一个在干净工位上的工程师单独完成完成后只交回一份完工报告。3. 环境搭建与核心配置实战3.1 前置条件选择你的“Worker引擎”spawn-agent本身只是一个调度脚本和协议定义它需要后端真正的AI CLI来执行任务。目前官方支持两大引擎1. Gemini CLI安装npm install -g google/gemini-cli特点由Google开发与Gemini模型深度集成。启动速度快对代码库的静态分析如理解项目结构、跨文件引用能力很强适合需要大量阅读和理解的“调研型”任务。身份验证安装后通常需要运行gemini auth login通过浏览器完成OAuth登录关联你的Google账户。2. Codex CLI安装npm install -g openai/codex特点由OpenAI开发注Codex是GPT系列早期用于代码的模型此处CLI可能泛指OpenAI的代码能力接口。以强大的逻辑推理和代码生成能力见长并且在“沙盒”环境中执行命令更为谨慎和安全适合复杂的逻辑实现和重构。身份验证需要设置OPENAI_API_KEY环境变量。实操心得网络与代理设置这两个CLI工具都可能需要访问海外API。请确保你的网络环境允许稳定的国际连接。如果你在开发环境中使用了网络代理通常需要在Shell配置文件如~/.bashrc或~/.zshrc中为npm和CLI工具配置代理。例如export HTTP_PROXYhttp://your-proxy-address:port export HTTPS_PROXYhttp://your-proxy-address:port安装后务必用gemini --version或codex --version测试是否安装成功以及基础网络是否通畅。连接失败是后续步骤最常见的绊脚石。3.2 安装与集成让Antigravity获得新技能spawn-agent以“技能”Skill的形式提供给Antigravity。Antigravity会自动扫描特定目录下的SKILL.md文件来学习新能力。推荐安装方式全局安装这种方式一次安装所有项目受益。# 1. 克隆仓库到Antigravity的全局技能目录 git clone https://github.com/khanhbkqt/spawn-agent.git ~/.gemini/antigravity/skills/spawn-agent # 2. 关键一步赋予执行权限 chmod x ~/.gemini/antigravity/skills/spawn-agent/scripts/spawn-agent.sh完成以上两步后当你下次启动Antigravity时它就会自动发现并加载spawn-agent技能。你可以在对话中直接使用它定义的新能力。验证安装是否成功一个简单的验证方法是直接运行脚本不通过Antigravitycd /path/to/your/project ~/.gemini/antigravity/skills/spawn-agent/scripts/spawn-agent.sh --help如果能看到详细的帮助信息说明脚本本身可执行且路径正确。项目级安装可选如果你希望某个技能只对特定项目生效可以克隆到项目内的.agent/skills/目录下。这对于管理不同项目所需的特定技能版本很有用。3.3 技能发现机制解析理解Antigravity如何发现技能有助于你调试安装问题。Antigravity启动时会按优先级扫描一系列目录来寻找SKILL.md文件项目本地目录./.agent/skills/用户全局目录~/.gemini/antigravity/skills/这是我们刚才安装的位置其他配置目录可能包括~/.cursor/skills/等取决于AI助手类型SKILL.md文件是这个技能的核心。它用自然语言描述了技能名称和用途Antigravity通过阅读这个来理解spawn-agent是干什么的。调用方式定义了AI助手应该如何“思考”去使用这个技能通常包括何时使用、输入是什么、预期输出是什么。参数和示例提供了具体的命令行调用示例AI可以模仿这些示例来构造正确的系统命令。所以当你对Antigravity说“请使用spawn-agent技能让Gemini帮我们分析一下这个模块的依赖”Antigravity会回忆起在SKILL.md中读到的关于spawn-agent的描述。根据你话语中的意图“分析依赖”匹配到“研究型任务”。从SKILL.md的示例中组合出一个大致的命令模板。将你的自然语言指令转化为具体的命令行参数例如--gemini --yolo -p Analyze dependencies in module X...。在后台执行这个脚本命令。4. Worker代理深度对比与选型指南选择Gemini CLI还是Codex CLI作为Worker不是个人喜好问题而是根据任务特性做出的技术选型。用错了工具事倍功半。4.1 Gemini CLI敏捷的代码库侦察兵核心优势上下文理解与速度Gemini CLI在处理与“代码阅读”和“快速理解”相关的任务上表现突出。它的设计似乎优化了对项目结构的快速索引和文件内容的关联分析。最适合的场景代码库探索与调研当你刚接手一个新项目需要快速了解某个目录下的所有文件是做什么的、它们之间如何调用。例如“列出src/utils/下所有工具函数并简要说明其用途。”影响性分析修改一个函数前需要知道哪些地方调用了它。例如“找出项目中所有导入formatCurrency函数的地方。”生成摘要或报告基于代码内容生成文档。例如“阅读/docs和/src下的主要文件生成一份项目架构概览Markdown。”简单的、范围明确的查找与替换例如“将src/components/里所有console.log替换为logger.info。”工作模式特点--yolo模式适用度高因为主要是读取和非破坏性操作可以放心使用全自动模式快速获取结果。对项目根目录的package.json、tsconfig.json等文件依赖较强它能利用这些文件更好地理解项目环境。4.2 Codex CLI严谨的代码外科医生核心优势逻辑推理与安全执行Codex CLI或其背后的模型在代码生成的逻辑严密性、遵循复杂指令以及在其“安全沙盒”内执行命令方面往往更令人放心。它更像一个深思熟虑的工程师。最适合的场景复杂的逻辑实现需要实现一个具有复杂条件判断、状态管理或算法的函数。例如“在src/calculator.ts中实现一个支持四则运算和括号的表达式解析器。”代码重构将一段冗长、混乱的代码重构成清晰、可维护的模块。例如“将UserService类中超过50行的createUser方法拆分为validateInput、hashPassword、saveToDb三个私有方法。”Bug修复尤其是需要推理出Bug根本原因的场景。例如“根据提供的错误堆栈TypeError: Cannot read property name of undefined定位并修复src/api/profile.js中可能导致此问题的代码。”需要运行测试验证的修改Codex的沙盒环境对运行npm test、pytest等命令的支持和隔离做得更好。工作模式特点建议从--safe或--auto-edit模式开始对于写操作先观察一下它的修改建议是否合理再逐步提高信任级别。对任务描述的精确性要求极高模糊的指令可能导致它过度推理或做出过于保守甚至错误的修改。4.3 决策矩阵与实战选择我个人的选择策略可以总结为以下表格任务特征推荐选择理由与示例“是什么”/“在哪里”探索、查找、统计Gemini CLI任务目标是获取信息而非改变系统。Gemini更快更擅长关联信息。例“统计src/下所有// TODO:和// FIXME:注释按文件分组列出。”“怎么做”/“改哪里”实现、重构、修复Codex CLI任务目标是产生或修改代码需要严谨的逻辑和安全性。例“在utils/validation.js中为validateEmail函数添加对国际化邮箱地址的支持。”任务简单、范围极小修改单个文件中的几行任意Gemini更快风险低可以追求速度。例“将config.js中的apiTimeout从5000改为10000。”任务复杂、涉及多文件跨模块重构Codex CLI需要更强的逻辑推理来保证修改的一致性。例“将lib/logger从单例模式重构为可注入的类并更新src/services/下所有使用它的文件。”需要运行项目命令验证测试、构建Codex CLI其沙盒环境对命令执行的管理通常更可靠。纯文本/文档分析Gemini CLI对自然语言的理解和摘要能力可能更强。踩坑记录不要“从一而终”早期我因为习惯了Gemini的速度所有任务都丢给它。结果在一次数据库迁移脚本的生成任务中翻车了。任务要求“基于models/下的Sequelize模型生成一个PostgreSQL迁移文件”。Gemini快速读取了所有模型但生成的迁移文件在关联关系和索引处理上出现了逻辑错误。后来用Codex CLI以--safe模式重新执行它每一步都给出了更详细的推理并生成了正确的up和down函数。从此我明白工具是拿来用的不是拿来粉的。根据任务选工具是专业性的体现。5. 任务编排的艺术从指令到可执行提示词使用spawn-agent最大的挑战也是最能体现你作为“Orchestrator”价值的地方在于如何将模糊的人类指令转化为Worker能精确执行的“机器指令”。这本质上是一种“提示词工程”。5.1 使用预制模板标准化操作流程项目提供了三个现成的Markdown模板强烈建议从它们开始。这能强制你进行结构化思考。1.implementation-task.md(实现任务模板)当你需要添加新功能、编写新模块或进行重构时使用。# Implementation Task: [简短描述如“Add user profile update endpoint”] ## Goal [清晰的一句话目标如“Create a PUT /api/users/:id endpoint that allows updating user‘s name and email, with validation.”] ## Scope **Files to read/modify:** - src/routes/users.ts (modify) - src/controllers/userController.ts (modify) - src/services/userService.ts (modify) - src/validators/userValidator.ts (create or modify) **Files that MUST NOT be touched:** - src/models/User.ts (database schema) - src/config/database.ts - Any file outside the src/ directory. ## Implementation Details - Use Joi for request validation. - The update should be partial (PATCH semantics). - Return the updated user object in the response. - Ensure the endpoint is added to the OpenAPI/Swagger spec if it exists. ## Verification - Run npm run test:unit to ensure new logic is tested. - Run npm run lint to check code style. - Do NOT run integration tests or start the server. ## Output Format 1. List all changed files with a diff summary. 2. Provide the exact command run for verification and its output. 3. Note any issues or warnings encountered.关键点Scope部分必须像防火墙规则一样明确白名单可修改和黑名单不可触碰都要有。Verification告诉Worker如何自检。2.research-task.md(研究任务模板)用于代码分析、架构理解等只读操作。# Research Task: Analyze Authentication Flow ## Goal Understand how the JWT-based authentication works in our backend, focusing on token generation, verification, and refresh mechanisms. ## Scope (Read-Only) **Directories to analyze:** - packages/backend/src/auth/ - packages/backend/src/middleware/ **Key Questions to Answer:** 1. Which library is used for JWT (jsonwebtoken, jose, etc.)? 2. Where is the secret key stored and how is it loaded? 3. What is the token expiry time? 4. Is there a refresh token mechanism? If yes, where is it handled? 5. List all middleware functions related to auth and their order in the request pipeline. ## Constraints - **DO NOT MODIFY ANY FILES.** - Only read the files mentioned above and any files they directly import. - If you need to run a command to understand the project (e.g., npm list), you may do so. ## Output Format A structured Markdown report with sections for each key question.关键点Constraints里的DO NOT MODIFY ANY FILES必须大写强调。Key Questions引导Worker进行有目的的调研而非泛泛而谈。3.bugfix-task.md(Bug修复模板)用于针对性修复已知问题。# Bug Fix: Null pointer in user avatar URL ## Problem Description When a new user registers without uploading an avatar, the user.avatarUrl field is null. The frontend attempts to display this null value in an img src tag, causing a console error. The error occurs in src/components/UserAvatar.vue. ## Suspected Location - Primary: src/components/UserAvatar.vue - Related: src/services/userService.js (where user object is fetched) ## Goal Modify the code to provide a default avatar image when avatarUrl is null or undefined. ## Fix Requirements 1. In UserAvatar.vue, add a computed property or a method to return a default image URL (e.g., ‘/images/default-avatar.png‘) if user.avatarUrl is falsy. 2. Ensure the fix is minimal and does not change the component‘s props interface or other logic. 3. The default image path should be configurable via a prop or a constant at the top of the file. ## Verification - Check if the component still works correctly when avatarUrl is a valid URL. - Ensure no new linting errors are introduced (npm run lint). ## Output Format Show the diff for UserAvatar.vue. Explain the chosen approach.5.2 编写高效的Inline Prompt内联提示词对于非常简单的任务使用-p参数直接传递提示词更快捷。但必须遵循一个简洁而完整的结构./scripts/spawn-agent.sh --gemini --yolo -p “ # Task: Count TODOs ## Goal: Find and count all TODO and FIXME comments in the src/ directory, grouped by file. ## Files: Read all .js, .ts, .jsx, .tsx, .vue files under src/ ## Constraints: DO NOT modify any files. Only read operations. ## When done: Output a markdown table with columns: Filename, TODO count, FIXME count, Total. ”内联提示词编写原则结构清晰用##标题划分区块便于Worker解析。指令肯定使用“Do this”而不是“Can you do this?”。边界明确Files和Constraints是安全护栏。输出具体告诉Worker你需要什么格式的结果否则它可能给你一大段散文。5.3 高级编排模式1. 链式委托谨慎使用有时一个任务可以分解为顺序执行的子任务。例如“先分析日志找出最常报错的API再定位该API的代码并尝试修复”。注意spawn-agent本身不直接支持将一个Worker的输出自动作为另一个Worker的输入。这需要Orchestrator也就是你或主AI来手动协调Step 1: 运行一个research-task分析日志输出最常报错的API端点名称。Step 2: 你或主AI读取结果然后构造第二个bugfix-task针对那个特定的端点代码进行修复。切勿在一个模糊的提示词里让Worker自己去“分析然后修复”这极易导致范围失控。2. 混合代理策略对于一个大型重构你可以先用Gemini CLI(--yolo) 快速执行一个research-task摸清所有需要修改的文件和依赖。分析调研报告后用Codex CLI(--auto-edit) 分批执行多个精细的implementation-task每次只修改一个逻辑模块。3. 结果审查与集成Worker完成任务后永远不要假设100%成功。Orchestrator必须审查输出日志检查是否有错误或警告。文件变更用git diff如果项目用Git查看具体修改了哪些内容是否符合预期。运行验证亲自运行一下Worker执行的验证命令如npm test确保系统状态正常。 这个“审查-集成”环节是保证多代理协作最终质量的关键闸门。6. 实战全流程从零构建一个功能模块让我们通过一个完整的、虚构的实战案例将前面所有知识串联起来。假设我们有一个Node.js后端项目我们需要添加一个“文章点赞”功能。6.1 阶段一项目调研与规划使用Gemini CLI首先我们得先了解现有项目结构。# 使用Gemini CLI进行快速、只读的调研 ./scripts/spawn-agent.sh --gemini --yolo --timeout 180 \ -p “ # Task: Project Structure Research for ‘Like‘ Feature ## Goal: Understand the current backend structure to plan where to add article like functionality. ## Scope (Read-Only): - Analyze the src/ directory structure. - Identify existing models (especially Article and User), routes, controllers, and services. - Find how similar features (e.g., ‘comments‘, ‘bookmarks‘) are implemented. - Locate the database schema definition (Prisma, Sequelize, or plain SQL files). ## Constraints: DO NOT MODIFY ANY FILES. Only read. ## Output Format: 1. Brief overview of src/ structure. 2. Paths to key files: Article model, User model, main router file. 3. Description of the ORM/query layer being used. 4. A suggestion for where to add the new Like model/route/service based on existing patterns. ”执行后我们可能得到一份报告告诉我们项目使用Express Prisma。Article模型在prisma/schema.prisma中定义。路由在src/routes/下类似功能评论的代码在src/routes/comments.ts和src/services/commentService.ts。建议在src/routes/articles.ts下添加POST /articles/:id/like路由并创建src/services/likeService.ts。6.2 阶段二数据库与模型层变更使用Codex CLI根据调研结果我们需要先扩展数据模型。这是一个需要严谨操作的步骤。# 首先创建一个详细的实现任务文件 cat /tmp/like-model-task.md EOF # Implementation Task: Add Like Model and Database Schema ## Goal Extend the database schema to support an Article Like feature, following the existing project patterns. ## Scope **Files to modify:** - prisma/schema.prisma (ADD a new Like model and relation) - prisma/migrations/ (WILL be generated by Prisma CLI, do not create manually) **Files to read for context:** - prisma/schema.prisma (existing Article and User models) - package.json (to confirm Prisma version and scripts) **Files that MUST NOT be touched:** - All files in src/ (this is for schema only) - Any other configuration files. ## Implementation Details 1. In prisma/schema.prisma: - Add a new model Like with fields: id (String id default(cuid())), createdAt (DateTime default(now())), articleId (String), userId (String). - Establish relations: Like belongs to one Article (article field) and one User (user field). - Add likes field (as Like[]) to the Article model. - Add likedArticles field (as Like[]) to the User model. 2. The articleId and userId fields should have db.ObjectId if using MongoDB, or appropriate relation attributes for PostgreSQL. 3. **CRITICAL**: After modifying the schema, run npx prisma migrate dev --name add_like_model to generate the migration. This command MUST be run. 4. If the command fails, output the error and stop. Do not attempt to fix other issues. ## Verification - After running the migration, verify that a new migration file is created in prisma/migrations/. - Run npx prisma generate to ensure the Prisma Client types are updated (this is usually automatic with migrate dev). ## Output Format 1. Show the diff for prisma/schema.prisma. 2. Show the full terminal output of the prisma migrate dev command. 3. Confirm the name of the created migration file. EOF # 使用Codex CLI执行以安全模式开始 ./scripts/spawn-agent.sh --codex --safe -f /tmp/like-model-task.md在--safe模式下Codex CLI会展示它计划执行的每一步修改schema、运行命令并征求你的确认。确认无误后它才会执行。这一步完成后数据库层面就准备好了。6.3 阶段三业务逻辑与API层实现使用Codex CLI接下来实现服务层和路由层。cat /tmp/like-service-task.md EOF # Implementation Task: Implement Like Service and Route ## Goal Create the service and route for the article like feature, following the existing patterns seen in commentService.ts and comments.ts. ## Scope **Files to create:** - src/services/likeService.ts **Files to modify:** - src/routes/articles.ts (add new like routes) - src/controllers/articleController.ts (optional, if the pattern uses controllers) **Files to read for pattern:** - src/services/commentService.ts - src/routes/comments.ts - src/controllers/commentController.ts (if exists) ## Implementation Details 1. In src/services/likeService.ts: - Create functions likeArticle(articleId, userId), unlikeArticle(articleId, userId), getLikesCount(articleId), hasUserLiked(articleId, userId). - Use the Prisma Client (import from prisma/client) for database operations. - Handle errors (e.g., article not found, duplicate like) and throw appropriate HTTP-friendly errors. 2. In src/routes/articles.ts: - Add a new route group /articles/:articleId/likes. - Implement POST / (to like) and DELETE / (to unlike). They should require user authentication (assume an authMiddleware is already applied). - Import and use the new likeService. 3. Follow the exact code style (indentation, import order, naming conventions) of the existing files. ## Verification - Run npm run lint to check for style issues. - Run npm run type-check or tsc --noEmit if available to ensure no TypeScript errors. - **DO NOT** run the full test suite if it‘s long. ## Output Format 1. Show the complete content of the newly created likeService.ts. 2. Show the diff for articles.ts highlighting the added routes. 3. Provide the output of the lint and type-check commands. EOF # 这次可以用--auto-edit模式因为我们信任Codex的编码能力且范围清晰 ./scripts/spawn-agent.sh --codex --auto-edit -f /tmp/like-service-task.md6.4 阶段四集成测试与最终审查最后Orchestrator也就是你需要亲自进行集成审查。审查代码仔细阅读Worker生成的likeService.ts和修改后的articles.ts检查逻辑是否正确错误处理是否完备是否遵循了项目规范。运行测试手动运行项目的测试特别是针对新功能的测试如果之前有让Worker写单元测试的话。启动服务尝试本地启动服务用API工具如Postman测试POST /articles/123/likes和DELETE /articles/123/likes端点是否正常工作。提交代码将经过验证的更改提交到版本控制系统。通过这个四步流程我们清晰地划分了职责Gemini负责快速侦察Codex负责严谨的构建而人类或主AI负责最终的质量把关和决策。整个过程中主AI助手的上下文始终保持干净专注于整体的功能规划和进度协调。7. 常见问题、故障排查与高级技巧7.1 安装与启动问题问题1脚本执行权限错误bash: ./scripts/spawn-agent.sh: Permission denied解决确保已运行chmod x /path/to/spawn-agent/scripts/spawn-agent.sh。如果是在Windows的WSL或Git Bash中还要注意文件系统权限。问题2Antigravity找不到技能检查技能目录确认spawn-agent文件夹是否克隆到了正确的目录~/.gemini/antigravity/skills/。检查SKILL.md确保文件夹内存在SKILL.md文件并且内容可读。重启Antigravity有些AI助手需要在启动时加载技能尝试完全重启你的AI编码助手应用。问题3Gemini/Codex CLI命令未找到Error: spawn gemini ENOENT解决确认CLI已全局安装which gemini或which codex。确认安装后的二进制文件所在目录已加入系统的PATH环境变量。对于某些包管理器如pnpm全局安装的包可能不在标准PATH需要额外配置。7.2 任务执行中的典型问题问题4Worker修改了不该改的文件根因任务提示词中的Scope或Constraints定义模糊或缺失。预防始终使用## Files to read/modify:和## Files that MUST NOT be touched:明确列出文件。使用目录路径而非通配符如用src/services/auth/代替模糊的src/。在Constraints中强调DO NOT MODIFY ANY FILES OUTSIDE THE SCOPE。补救立即使用git checkout -- file如果使用Git回滚被意外修改的文件。问题5Worker陷入循环或输出无意义内容根因提示词指令存在歧义或任务过于开放导致Worker“迷茫”。解决立即中断如果设置了--timeout等待超时否则可能需要手动在终端按CtrlC终止进程。简化任务将大任务拆分成更小、更具体的子任务。提供更多上下文在提示词中引用一个具体的、正确的代码示例作为参考范式。切换代理如果Gemini卡住尝试用Codex反之亦然。问题6Worker运行的命令导致副作用如安装了大量包根因在Verification部分或提示词中给予了过高的权限或模糊的指令如“确保测试通过”Worker可能会自行运行npm install等命令。预防在Verification部分明确指定只读或无害的命令例如Run npm run lint -- --dry-run(如果支持)Run npm test -- --listTests(只列出测试不执行)Do NOT run npm install or any command that modifies node_modules.7.3 性能与成本优化技巧善用--timeout为任务设置合理的超时时间如--timeout 120表示2分钟。防止因任务卡住而长时间占用资源和产生不必要的API费用。明确文件范围在Scope中精确指定需要读取的文件列表避免Worker去索引整个庞大的node_modules或.git目录这能极大缩短任务启动时间和Token消耗。离线或本地模型如果条件允许且你使用的CLI支持配置本地模型如通过Ollama可以将其指向本地部署的大模型以消除网络延迟和API成本。这需要在你的环境变量或CLI配置中设置。结果缓存对于常见的调研任务如“项目结构是什么”结果变化不频繁。你可以让Worker将输出保存到文件--output report.md之后直接复用无需重复执行。7.4 与其他开发流程集成与Git工作流结合在发起一个可能产生大量修改的implementation-task前务必先创建一个新的Git分支如feat/add-like。让Worker在该分支上操作。完成后你可以清晰地审查git diff轻松地回滚或调整。这为AI驱动的开发提供了版本控制的安全网。与CI/CD管道结合你可以创建一个“AI代码审查”任务。让Worker特别是Codex CLI以--safe模式运行对Pull Request中的代码差异进行分析并生成一个“AI审查意见”作为评论。这可以作为人工审查的补充。注意这需要将spawn-agent脚本集成到你的CI服务器中并妥善管理API密钥。作为学习与探索工具对于开源项目你可以使用spawn-agent的research-task来快速学习其架构。例如“分析Vue.js 3的响应式系统核心源码packages/reactivity/的实现原理”。这比手动翻阅文件要高效得多尤其适合在介入大型项目前快速建立认知。spawn-agent代表的是一种范式转变从让一个AI去完成所有事转向让多个AI各司其职由人类或一个更高级的AI进行统筹。它放大了AI在具体执行层面的能力同时通过隔离机制保护了核心的规划与推理能力不受污染。掌握它意味着你不仅是在使用一个工具更是在实践一种更高效、更可持续的人机协作架构。