Gepetto 研究协议解析AI 实现规划流水线中的研究决策、并行执行与结果合并机制Meshery 仓库实践【免费下载链接】mesheryMeshery, the cloud native manager项目地址: https://gitcode.com/GitHub_Trending/me/meshery导读本文以 Meshery 仓库内.agents/skills/gepetto/references/research-protocol.md为骨架系统讲解 Gepetto 技能中“研究决策与执行”环节的完整运作机制如何从一份粗糙的 spec规格描述中提取研究主题、如何决定是否需要代码库/网络研究、如何以并行子代理方式执行研究、以及为何必须由父代理统一写入claude-research.md。读完本文你将掌握一套可直接复用的“Spec → 研究 → 决策”工程方法论理解 AI 辅助实现规划流水线中研究环节的职责边界与并发安全设计。研究协议在 Gepetto 流水线中的定位Gepetto 是一个将模糊想法雕刻为可实施计划的多步规划技能其完整流水线为Research → Interview → Spec Synthesis → Plan → External Review → Sections在 Gepetto 技能定义 中整个工作流被细分为 17 个编号步骤而Step 4Research Decision与 Step 5Execute Research正是由研究协议research-protocol.md所定义。研究环节之后访谈Step 6、规格综合Step 8、计划生成Step 9都会消费研究产出的claude-research.md——例如 访谈协议 明确要求访谈必须基于初始 spec 与研究成果用研究结论“跳过已被回答的问题、追问已发现权衡点的细节”。因此研究协议是整个流水线信息质量的源头。在 Meshery 仓库中这一技能位于.agents/skills/gepetto/目录。根据 仓库 Agent 工具布局说明.agents/skills/是仓库内所有打包工作流的唯一事实来源Claude Code 通过相对符号链接.claude/skills指向它进行发现因此研究协议中描述的运行机制在仓库的 Agent 体系中是真实可用的。Step 4研究决策——决定“研究什么”研究协议将第一步定义为“研究决策”。这一阶段的核心产出不是研究结果本身而是明确研究类型与主题清单。4.1 读取并分析 spec 文件提取研究主题执行者需要通读调用时传入的 spec 文件如planning/auth-spec.md并通过四类维度识别潜在研究主题涉及的技术React、Python、PostgreSQL、Redis 等功能类型认证、文件上传、实时同步、缓存等架构模式微服务、事件驱动、Serverless 等集成点第三方 API、OAuth 提供方、支付网关等基于识别结果生成 3–5 条可搜索的研究主题建议格式上建议携带年份以保证时效性例如React authentication patterns 2025 PostgreSQL full-text search best practices Redis session storage patterns如果 spec 内容过于模糊协议提供了兜底策略——退回到基于已检测语言/框架的通用建议General best practices for {detected_language/framework} Security considerations for {feature_type}4.2 询问代码库研究需求随后通过AskUserQuestion向用户确认是否需要先研究现有代码库选项设计为二选一question: Is there existing code I should research first? header: Codebase options: - label: Yes, research the codebase description: Analyze existing patterns, conventions, dependencies - label: No existing code description: This is a new project or standalone feature该选项决定了是否启动代码库研究子代理用于摸底项目结构、既有模式与约定、依赖及测试体系——对于像 Meshery 这样同时包含 Go 服务端server/、React 前端ui/、CLImesheryctl/和多目录文档站docs/的大型仓库代码库研究尤其重要。4.3 询问网络研究需求将 4.1 推导出的主题作为多选项呈现给用户question: Should I research current best practices for any of these topics? header: Web Research multiSelect: true options: - label: {derived_topic_1} description: Based on spec mention of {X} - label: {derived_topic_2} description: Based on spec mention of {Y} - label: {derived_topic_3} description: Based on spec mention of {Z}若用户选择 Other则需要跟进获取自定义主题。这一设计保证了网络研究始终与 spec 中出现的具体关切点绑定而非泛泛而谈。4.4 处理“无研究”场景若用户既未选择代码库研究、也未选择网络研究则完全跳过 Step 5直接进入 Step 6访谈。这一短路路径在 SKILL.md 的 Step 5 说明 中同样被强调“Skip this step entirely if user chose no research in step 4.”Step 5执行研究——并行子代理与父代理写入关键模式子代理返回结果父代理写文件研究协议中最重要的一条纪律是DO NOThave subagents write to files directly. This avoids race conditions and keeps control with the main context.即子代理subagent只负责把研究发现以 markdown 形式返回禁止直接写文件所有文件写入统一由主上下文父代理完成。这样设计有两层动机一是避免多个并行子代理并发写盘造成竞态条件race conditions二是将控制权收拢在主上下文中便于统一合并与取舍。这与 外部评审协议 中“Gemini/Codex 评审通过 CLI 返回分析、由主流程写 review 文件”的做法一脉相承。5.1 代码库研究若被选中启动subagent_typeExplore的 Task 工具提示词要求子代理理解四件事Task tool: subagent_type: Explore description: Research codebase patterns prompt: | Research this codebase to understand: - Project structure and architecture - Existing patterns and conventions - Dependencies and how theyre used - Testing setup (framework, patterns, how tests are run) Focus areas from user: {user_specified_areas_if_any} Return your findings as markdown. DO NOT write to any files. Return findings in your response.注意 prompt 末尾的双重约束“Return your findings as markdown”与“DO NOT write to any files”将结果返回方式与文件写入权限彻底分离。5.2 网络研究若主题被选中同样使用 Explore 子代理但要求其调用WebSearch/WebFetch完成四步流程检索权威来源 → 抓取候选页面提取建议 → 跨来源交叉验证 → 综合成带明确建议的结论Task tool: subagent_type: Explore description: Research best practices prompt: | Research current best practices for the following topics: {selected_topics_list} For each topic: 1. Use WebSearch to find authoritative sources 2. Use WebFetch on promising results to extract recommendations 3. Cross-validate information across sources 4. Synthesize findings with clear recommendations Return your findings as markdown. Always cite sources with URLs. DO NOT write to any files. Return findings in your response.与代码库研究不同的是网络研究要求“Always cite sources with URLs”为后续规格综合保留可追溯依据。5.3 并行执行当代码库与网络研究都需要时协议明确要求在单条消息中同时发起两个 Task 工具调用single message with multiple tool calls实现真正的并行# Single message with multiple tool calls: [Task tool call 1: Explore subagent for codebase] [Task tool call 2: Explore subagent for web research]并行设计的前提正是 5.1 所述的“只返回、不写盘”约束——两个子代理互不触碰文件系统输出天然隔离因此可以安全并发。5.4 合并结果并写文件等待全部子代理完成后将结果合并写入planning_dir/claude-research.md。协议对文件结构不做强制约束“Structure the file however makes sense for the findings”把组织自由交给主上下文。该文件随后成为访谈Step 6、规格综合Step 8的输入并出现在最终规划目录结构中。边界情况处理表研究协议用一张表格系统性地定义了异常路径的处理策略CaseHandlingSpec 文件模糊基于检测到的语言/框架给出通用选项用户不选择研究跳过 Step 5直接进入 Step 6访谈单个子代理失败记录警告仅用成功的研究结果写文件两个子代理都失败记录错误询问用户重试或继续只有一种研究类型运行单个子代理文件只写对应内容这五条策略体现了“部分成功也可继续、全部失败则向用户寻求裁决”的容错哲学研究是可选增强环节不应阻塞整个规划流水线。研究产物如何被后续环节消费研究协议产出的claude-research.md并非孤立文件而是贯穿 Gepetto 流水线的关键中间产物这一点可从同目录协议与 SKILL.md 交叉印证访谈环节访谈协议 要求访谈由初始 spec 与研究结果共同驱动用研究跳过已答问题、深挖已暴露的复杂度。规格综合SKILL.md Step 8 将“初始输入 研究结果 访谈答案”三者合并为claude-spec.md。断点恢复SKILL.md 的恢复机制按文件存在情况判定续跑位置——发现claude-research.md即从访谈Step 6恢复因此研究文件同时充当流水线的持久化检查点。章节拆分章节索引协议 与章节文件编写协议 说明最终 plan 会被切成自包含的sections/section-NN-*.md研究阶段沉淀的代码库模式与最佳实践会以“Implementation details”形式沉淀进各章节。在 Meshery 仓库中的落地要点技能发现路径仓库将技能统一收口在 .agents/skills各工具Codex、OpenCode、Claude Code通过各自原生扫描或符号链接发现研究协议中的机制不依赖任何工具私有目录。规划目录约定研究产物固定写入planning/claude-research.md与claude-interview.md、claude-spec.md、claude-plan.md、reviews/、sections/共同构成完整规划目录结构。运行前提研究协议依赖Task子代理工具与AskUserQuestion交互工具属于 Claude Code 技能运行环境网络研究还需子代理具备 WebSearch/WebFetch 能力。若环境缺失对应能力应退化为仅执行代码库研究或直接跳过。结语研究协议的价值在于把“调研”从一次随意的动作规范化为可决策、可并行、可容错、可恢复的标准流程以 spec 为输入推导研究主题用二选一/多选交互明确研究边界靠“子代理只返回、父代理只写盘”的职责切分保证并发安全再以claude-research.md作为下游访谈与规格综合的持久化输入。这一机制同样适用于任何需要“先想清楚、再动手编码”的 AI 辅助规划场景可作为团队沉淀自身 AI 工程工作流时的参考范式。【免费下载链接】mesheryMeshery, the cloud native manager项目地址: https://gitcode.com/GitHub_Trending/me/meshery创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考