--- name: sciomc description: 使用 AUTO 模式编排并行 scientist agents 进行全面分析 argument-hint: <研究目标> level: 4 --- # 研究技能 编排并行的 scientist agents 来执行完整的研究工作流，并可选使用 AUTO 模式实现全自动执行。 ## 概览 研究是一个多阶段工作流，会将复杂的研究目标拆解为可并行进行的调查： 1. **分解** - 将研究目标拆成独立的阶段/假设 2. **执行** - 在每个阶段上并行运行 scientist agents 3. **验证** - 交叉验证发现并检查一致性 4. **综合** - 汇总结果并生成完整报告 ## 用法示例 ``` /oh-my-claudecode:sciomc # 带用户检查点的标准研究 /oh-my-claudecode:sciomc AUTO: # 全自动执行直到完成 /oh-my-claudecode:sciomc status # 检查当前研究会话状态 /oh-my-claudecode:sciomc resume # 恢复被中断的研究会话 /oh-my-claudecode:sciomc list # 列出所有研究会话 /oh-my-claudecode:sciomc report # 为会话生成报告 ``` ### 快速示例 ``` /oh-my-claudecode:sciomc What are the performance characteristics of different sorting algorithms? /oh-my-claudecode:sciomc AUTO: Analyze authentication patterns in this codebase /oh-my-claudecode:sciomc How does the error handling work across the API layer? ``` ## 研究协议 ### 阶段分解模式 给定一个研究目标时，将其分解为 3-7 个独立阶段： ```markdown ## 研究分解 **目标：** <原始研究目标> ### 阶段 1：<阶段名称> - **重点：** 此阶段要调查什么 - **假设：** 预期发现（如适用） - **范围：** 要检查的文件/区域 - **层级：** LOW | MEDIUM | HIGH ### 阶段 2：<阶段名称> ... ``` ### 并行调用 Scientist 通过 Task 工具并行触发独立阶段： ``` // 阶段 1 - 简单数据收集 Task(subagent_type="oh-my-claudecode:scientist", model="haiku", prompt="[RESEARCH_STAGE:1] Investigate...") // 阶段 2 - 标准分析 Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt="[RESEARCH_STAGE:2] Analyze...") // 阶段 3 - 复杂推理 Task(subagent_type="oh-my-claudecode:scientist", model="opus", prompt="[RESEARCH_STAGE:3] Deep analysis of...") ``` ### 智能模型路由 **关键：始终显式传递 `model` 参数！** | 任务复杂度 | Agent | Model | 用途 | |-----------------|-------|-------|---------| | 数据收集 | `scientist` (model=haiku) | haiku | 文件枚举、模式计数、简单查找 | | 标准分析 | `scientist` | sonnet | 代码分析、模式识别、文档审查 | | 复杂推理 | `scientist` | opus | 架构分析、横切关注点、假设验证 | ### 路由决策指南 | 研究任务 | 层级 | 示例 Prompt | |---------------|------|----------------| | "Count occurrences of X" | LOW | "Count all usages of useState hook" | | "Find all files matching Y" | LOW | "List all test files in the project" | | "Analyze pattern Z" | MEDIUM | "Analyze error handling patterns in API routes" | | "Document how W works" | MEDIUM | "Document the authentication flow" | | "Explain why X happens" | HIGH | "Explain why race conditions occur in the cache layer" | | "Compare approaches A vs B" | HIGH | "Compare Redux vs Context for state management here" | ### 验证循环 并行执行完成后，验证研究发现： ``` // 交叉验证阶段 Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt=" [RESEARCH_VERIFICATION] 交叉验证以下发现的一致性： 阶段 1 发现： 阶段 2 发现： 阶段 3 发现： 检查： 1. 各阶段之间的矛盾 2. 缺失的关联 3. 覆盖空白 4. 证据质量 输出：[VERIFIED] 或 [CONFLICTS:] ") ``` ## AUTO 模式 AUTO 模式会通过循环控制自动运行完整的研究工作流。 ### 循环控制协议 ``` [RESEARCH + AUTO - ITERATION {{ITERATION}}/{{MAX}}] 你上一次尝试没有输出完成 Promise。请继续执行。 当前状态：{{STATE}} 已完成阶段：{{COMPLETED_STAGES}} 待完成阶段：{{PENDING_STAGES}} ``` ### Promise 标签 | Tag | 含义 | 使用时机 | |-----|---------|-------------| | `[PROMISE:RESEARCH_COMPLETE]` | 研究已成功完成 | 所有阶段完成、已验证、报告已生成 | | `[PROMISE:RESEARCH_BLOCKED]` | 无法继续 | 缺少数据、访问问题、循环依赖 | ### AUTO 模式规则 1. **最大迭代次数：** 10（可配置） 2. **持续直到：** 输出 Promise 标签或达到最大迭代次数 3. **状态跟踪：** 每个阶段完成后持久化 4. **取消：** `/oh-my-claudecode:cancel` 或 "stop"、"cancel" ### AUTO 模式示例 ``` /oh-my-claudecode:sciomc AUTO: Comprehensive security analysis of the authentication system [Decomposition] - Stage 1 (LOW): Enumerate auth-related files - Stage 2 (MEDIUM): Analyze token handling - Stage 3 (MEDIUM): Review session management - Stage 4 (HIGH): Identify vulnerability patterns - Stage 5 (MEDIUM): Document security controls [Execution - Parallel] Firing stages 1-3 in parallel... Firing stages 4-5 after dependencies complete... [Verification] Cross-validating findings... [Synthesis] Generating report... [PROMISE:RESEARCH_COMPLETE] ``` ## 并行执行模式 ### 独立数据集分析（并行） 当各阶段分析不同的数据源时： ``` // 同时触发全部阶段 Task(subagent_type="oh-my-claudecode:scientist", model="haiku", prompt="[STAGE:1] Analyze src/api/...") Task(subagent_type="oh-my-claudecode:scientist", model="haiku", prompt="[STAGE:2] Analyze src/utils/...") Task(subagent_type="oh-my-claudecode:scientist", model="haiku", prompt="[STAGE:3] Analyze src/components/...") ``` ### 假设组测试（并行） 当需要测试多个假设时： ``` // 同时测试多个假设 Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt="[HYPOTHESIS:A] Test if caching improves...") Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt="[HYPOTHESIS:B] Test if batching reduces...") Task(subagent_type="oh-my-claudecode:scientist", model="sonnet", prompt="[HYPOTHESIS:C] Test if lazy loading helps...") ``` ### 交叉验证（顺序） 当验证依赖于全部研究发现时： ``` // 等待所有并行阶段完成 [stages complete] // 然后顺序进行验证 Task(subagent_type="oh-my-claudecode:scientist", model="opus", prompt=" [CROSS_VALIDATION] 验证所有发现之间的一致性： - 发现 1：... - 发现 2：... - 发现 3：... ") ``` ### 并发上限 **最多允许 20 个并发 scientist agents**，以防止资源耗尽。 如果阶段数超过 20，请分批执行： ``` Batch 1: Stages 1-5 (parallel) [等待完成] Batch 2: Stages 6-7 (parallel) ``` ## 会话管理 ### 目录结构 ``` .omc/research/{session-id}/ state.json # 会话状态与进度 stages/ stage-1.md # 阶段 1 研究发现 stage-2.md # 阶段 2 研究发现 ... findings/ raw/ # scientist 输出的原始发现 verified/ # 验证后的发现 figures/ figure-1.png # 生成的可视化图表 ... report.md # 最终综合报告 ``` ### 状态文件格式 ```json { "id": "research-20240115-abc123", "goal": "原始研究目标", "status": "in_progress | complete | blocked | cancelled", "mode": "standard | auto", "iteration": 3, "maxIterations": 10, "stages": [ { "id": 1, "name": "阶段名称", "tier": "LOW | MEDIUM | HIGH", "status": "pending | running | complete | failed", "startedAt": "ISO 时间戳", "completedAt": "ISO 时间戳", "findingsFile": "stages/stage-1.md" } ], "verification": { "status": "pending | passed | failed", "conflicts": [], "completedAt": "ISO 时间戳" }, "createdAt": "ISO 时间戳", "updatedAt": "ISO 时间戳" } ``` ### 会话命令 | Command | 操作 | |---------|--------| | `/oh-my-claudecode:sciomc status` | 显示当前会话进度 | | `/oh-my-claudecode:sciomc resume` | 恢复最近一次中断的会话 | | `/oh-my-claudecode:sciomc resume ` | 恢复指定会话 | | `/oh-my-claudecode:sciomc list` | 列出所有会话及其状态 | | `/oh-my-claudecode:sciomc report ` | 生成/重新生成报告 | | `/oh-my-claudecode:sciomc cancel` | 取消当前会话（保留状态） | ## 标签提取 Scientists 使用结构化标签来表示研究发现。使用以下模式提取： ### 发现标签 ``` [FINDING:] <evidence and analysis> [/FINDING] [EVIDENCE:<finding-id>] - File: <path> - Lines: <range> - Content: <relevant code/text> [/EVIDENCE] [CONFIDENCE:<level>] # HIGH | MEDIUM | LOW <reasoning for confidence level> ``` ### 提取用 Regex 模式 ```javascript // 发现提取 const findingPattern = /\[FINDING:(\w+)\]\s*(.*?)\n([\s\S]*?)\[\/FINDING\]/g; // 证据提取 const evidencePattern = /\[EVIDENCE:(\w+)\]([\s\S]*?)\[\/EVIDENCE\]/g; // 置信度提取 const confidencePattern = /\[CONFIDENCE:(HIGH|MEDIUM|LOW)\]\s*(.*)/g; // 阶段完成 const stageCompletePattern = /\[STAGE_COMPLETE:(\d+)\]/; // 验证结果 const verificationPattern = /\[(VERIFIED|CONFLICTS):?(.*?)\]/; ``` ### 证据窗口 提取证据时，包含上下文窗口： ``` [EVIDENCE:F1] - File: /src/auth/login.ts - Lines: 45-52 (context: 40-57) - Content: ```typescript // 第 45-52 行，包含上下各 5 行上下文 ``` [/EVIDENCE] ``` ### 质量校验 研究发现必须满足质量阈值： | 质量检查 | 要求 | |---------------|-------------| | 提供证据 | 每个 [FINDING] 至少有 1 个 [EVIDENCE] | | 标注置信度 | 每个发现都必须有 [CONFIDENCE] | | 引用来源 | 文件路径必须是绝对路径且有效 | | 可复现 | 另一个 agent 也能够验证 | ## 报告生成 ### 报告模板 ```markdown # 研究报告：{{GOAL}} **会话 ID：** {{SESSION_ID}} **日期：** {{DATE}} **状态：** {{STATUS}} ## 执行摘要 {{2-3 段关键发现摘要}} ## 方法论 ### 研究阶段 | 阶段 | 重点 | 层级 | 状态 | |-------|-------|------|--------| {{STAGES_TABLE}} ### 方法 {{分解思路与执行策略说明}} ## 关键发现 ### 发现 1：{{TITLE}} **置信度：** {{HIGH|MEDIUM|LOW}} {{带证据的详细发现}} #### 证据 {{嵌入的证据块}} ### 发现 2：{{TITLE}} ... ## 可视化 {{FIGURES}} ## 交叉验证结果 {{验证摘要，以及已解决的冲突}} ## 局限性 - {{局限性 1}} - {{局限性 2}} - {{未覆盖的范围及原因}} ## 建议 1. {{可执行建议}} 2. {{可执行建议}} ## 附录 ### 原始数据 {{原始发现文件链接}} ### 会话状态 {{指向 state.json 的链接}} ``` ### 图表嵌入协议 Scientists 使用以下标记生成可视化： ``` [FIGURE:path/to/figure.png] Caption: Description of what the figure shows Alt: Accessibility description [/FIGURE] ``` 报告生成器会嵌入图表： ```markdown ## 可视化 ![Figure 1: Description](figures/figure-1.png) *Caption: Description of what the figure shows* ![Figure 2: Description](figures/figure-2.png) *Caption: Description of what the figure shows* ``` ### 图表类型 | 类型 | 用途 | 生成者 | |------|---------|--------------| | 架构图 | 系统结构 | scientist | | 流程图 | 流程流转 | scientist | | 依赖图 | 模块关系 | scientist | | 时间线 | 事件顺序 | scientist | | 对比表 | A vs B 分析 | scientist | ## 配置 `.claude/settings.json` 中的可选配置： ```json { "omc": { "research": { "maxIterations": 10, "maxConcurrentScientists": 5, "defaultTier": "MEDIUM", "autoVerify": true, "generateFigures": true, "evidenceContextLines": 5 } } } ``` ## 取消 ``` /oh-my-claudecode:cancel ``` 或者说："stop research"、"cancel research"、"abort" 进度会保存在 `.omc/research/{session-id}/` 中，便于恢复。 ## 故障排查 **卡在验证循环中？** - 检查各阶段之间是否存在冲突的发现 - 查看 `state.json` 中的具体冲突 - 可能需要采用不同方法重新运行特定阶段 **Scientists 返回的发现质量较低？** - 检查层级分配，复杂分析需要 HIGH 层级 - 确保 prompt 中包含清晰的范围和预期输出格式 - 检查研究目标是否过于宽泛 **AUTO 模式耗尽迭代次数？** - 查看状态以确认卡在何处 - 检查目标是否能用现有数据达成 - 考虑拆分为更小的研究会话 **报告中缺少图表？** - 确认 `figures/` 目录存在 - 检查发现中的 `[FIGURE:]` 标签 - 确保路径相对于会话目录