diff --git a/codex SUBAGENT 策略补充.md b/codex SUBAGENT 策略补充.md deleted file mode 100644 index 0a3be2c5..00000000 --- a/codex SUBAGENT 策略补充.md +++ /dev/null @@ -1,1027 +0,0 @@ -# Codex Subagent 策略补充文档 - -## 1. 核心架构特点 - -| 特点 | 说明 | -|------|------| -| **独立会话上下文** | 每个 subagent 有独立 `agent_id`，上下文完全隔离 | -| **并行执行** | 可同时创建多个 subagent 并行处理不同子任务 | -| **无状态恢复** | `close_agent` 后不可恢复，需重新创建并粘贴旧输出 | -| **显式生命周期** | 需主动管理创建、等待、关闭全流程 | -| **无系统提示词** | subagent 无内置 system prompt，需在首条消息加载角色 | - -## 2. API 调用模式 - -### 2.1 标准流程 - -``` -spawn_agent → wait → [send_input] → close_agent - ↓ ↓ ↓ ↓ - 创建任务 获取结果 追问纠偏 清理回收 -``` - -### 2.2 关键 API 语义 - -| API | 作用 | 注意事项 | -|-----|------|----------| -| `spawn_agent({ message })` | 创建 subagent | 返回 `agent_id` | -| `wait({ ids, timeout_ms })` | 获取结果 | **唯一取结果入口**，非 close | -| `send_input({ id, message, interrupt })` | 继续交互 | `interrupt=true` 慎用 | -| `close_agent({ id })` | 关闭回收 | 不可逆，关闭后无法恢复 | - -### 2.3 常见误区 - -- **误区**：以为 `close_agent` 返回结果 -- **正解**：`wait` 才是获取结果的入口，`close_agent` 只是清理 - -- **误区**：`timeout` 超时 = 任务失败 -- **正解**：超时只表示未在指定时间内完成，可继续 `wait` 或 `send_input` 催促 - -## 3. 与 Claude Code Task 工具对比 - -| 维度 | Codex Subagent | Claude Code Task | -|------|----------------|------------------| -| **创建方式** | `spawn_agent({ message })` | `Task({ subagent_type, prompt })` | -| **结果获取** | `wait({ ids })` 显式等待 | 同步返回或 `TaskOutput` 轮询 | -| **多 agent 等待** | 支持批量 `wait({ ids: [a,b,c] })` | 需分别调用或并行发起 | -| **追问/纠偏** | `send_input` 继续交互 | 需 `resume` 参数恢复 agent | -| **中断能力** | `interrupt=true` 可打断 | 无对应机制 | -| **生命周期** | 需显式 `close_agent` 清理 | 自动回收 | -| **系统提示词** | **无**，需首条消息加载角色 | 内置 agent 定义 | -| **上下文传递** | 在 message 中显式传递 | 部分 agent 可访问当前上下文 | - -### 3.1 适用场景对比 - -**Codex Subagent 更适合**： -- 需要批量等待多个并行任务的场景 -- 需要多轮交互、迭代纠偏的复杂任务 -- 对 agent 生命周期有精细控制需求 - -**Claude Code Task 更适合**： -- 单次执行、快速返回的任务 -- 需要利用预定义 agent 类型的场景 -- 简单的并行任务分发 - -## 4. 角色加载规范（关键差异） - -### 4.1 问题背景 - -Codex subagent **没有系统提示词**，无法像 Claude Code 那样通过 `subagent_type` 自动加载角色定义。 - -**解决方案**：在 `spawn_agent` 的首条 message 中显式加载角色文件。 - -### 4.2 角色文件位置 - -``` -~/.codex/agents/ -├── cli-explore-agent.md # 代码探索 -├── cli-lite-planning-agent.md # 轻量规划 -├── code-developer.md # 代码开发 -├── context-search-agent.md # 上下文搜索 -├── debug-explore-agent.md # 调试探索 -├── doc-generator.md # 文档生成 -└── ... (共 20+ 角色) -``` - -### 4.3 角色加载模板 - -```javascript -// 标准 spawn_agent 消息结构（角色路径传递，agent 自己读取） -spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first) -2. Read: .workflow/project-tech.json -3. Read: .workflow/project-guidelines.json - -## TASK CONTEXT -${taskContext} - -## DELIVERABLES -${deliverables} -` -}) -``` - -> **注意**：角色文件由 agent 自己读取，主流程只传递路径。详见 §9.1 角色加载模式。 - -### 4.4 角色映射表 - -| Claude subagent_type | Codex 角色文件 | -|----------------------|----------------| -| `cli-explore-agent` | `~/.codex/agents/cli-explore-agent.md` | -| `cli-lite-planning-agent` | `~/.codex/agents/cli-lite-planning-agent.md` | -| `code-developer` | `~/.codex/agents/code-developer.md` | -| `context-search-agent` | `~/.codex/agents/context-search-agent.md` | -| `debug-explore-agent` | `~/.codex/agents/debug-explore-agent.md` | -| `doc-generator` | `~/.codex/agents/doc-generator.md` | -| `action-planning-agent` | `~/.codex/agents/action-planning-agent.md` | -| `test-fix-agent` | `~/.codex/agents/test-fix-agent.md` | -| `universal-executor` | `~/.codex/agents/universal-executor.md` | - -## 5. 结构化交付模式 - -### 5.1 推荐输出模板 - -```text -Summary: -- 一句话总结任务完成情况 - -Findings: -- 发现 1：具体描述 -- 发现 2：具体描述 - -Proposed changes: -- 文件/模块：path/to/file -- 变更点：具体修改内容 -- 风险点：潜在影响 - -Tests: -- 需要新增/更新的用例： -- 需要运行的测试命令： - -Open questions: -1. 待澄清问题 1 -2. 待澄清问题 2 -``` - -### 5.2 两阶段工作流 - -``` -阶段 1：澄清 - spawn_agent → 只输出 Open questions - ↓ - 主 agent 回答问题 - ↓ -阶段 2：执行 - send_input → 输出完整方案 -``` - -**优势**：减少因理解偏差导致的返工 - -## 6. 并行拆分策略 - -### 6.1 按职责域拆分（推荐） - -| Worker | 职责 | 交付物 | 禁止事项 | -|--------|------|--------|----------| -| **A（调研）** | 定位入口、调用链、相似实现 | 文件+符号+证据点 | 不写方案 | -| **B（方案）** | 最小改动实现路径 | 变更点清单+风险评估 | 不写代码 | -| **C（测试）** | 测试策略、边界条件 | 用例列表+覆盖点 | 不实现测试 | - -### 6.2 按模块域拆分 - -``` -Worker 1: src/auth/** → 认证模块变更 -Worker 2: src/api/** → API 层变更 -Worker 3: src/database/** → 数据层变更 -``` - -### 6.3 拆分原则 - -1. **文件隔离**：避免多个 subagent 同时建议修改同一文件 -2. **职责单一**：每个 subagent 只做一件事 -3. **边界清晰**：超出范围必须在 `Open questions` 请求确认 -4. **最小上下文**：只传递完成任务所需的最小信息 - -## 7. 消息设计规范 - -### 7.1 spawn_agent message 结构（角色路径传递） - -```text -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/{agent-type}.md (MUST read first) -2. Read: .workflow/project-tech.json -3. Read: .workflow/project-guidelines.json - ---- - -Goal: 一句话目标（做什么） - -Scope: -- 可做：允许的操作范围 -- 不可做：明确禁止的事项 -- 目录限制：只看 src/auth/** -- 依赖限制：不允许引入新依赖 - -Context: -- 关键路径：src/auth/login.ts -- 现状摘要：当前使用 JWT 认证 -- 约束条件：必须兼容现有 API - -Deliverables: -- 按模板输出 Summary/Findings/Proposed changes/Tests/Open questions - -Quality bar: -- 验收标准 1 -- 验收标准 2 -``` - -> **注意**：角色文件路径放在 MANDATORY FIRST STEPS，由 agent 自己读取。主流程不传递角色内容。 - -### 7.2 send_input 追问模式 - -```text -# 回答澄清问题 -Re: Open question 1 - 答案是 XXX -Re: Open question 2 - 请按 YYY 方式处理 - -# 请继续输出完整方案 -``` - -## 8. 错误处理与恢复 - -### 8.1 超时处理 - -``` -wait(timeout=30s) → timed_out=true - ↓ -选项 1: 继续 wait，等待完成 -选项 2: send_input 催促收敛 -选项 3: close_agent 放弃 -``` - -### 8.2 已关闭 agent 恢复 - -``` -close_agent(id) → agent 不可恢复 - ↓ -spawn_agent(new_message) → 创建新 agent - ↓ -在 message 中粘贴旧输出作为上下文 -``` - -## 9. 最佳实践清单 - -- [ ] **角色文件路径传递**：在 MANDATORY FIRST STEPS 中指定 `~/.codex/agents/*.md` 路径，由 agent 自己读取 -- [ ] 创建前明确 Goal/Scope/Context/Deliverables/Quality bar -- [ ] 按职责或模块域拆分，避免文件冲突 -- [ ] 要求统一输出模板，便于合并 -- [ ] 用 `wait` 获取结果，不依赖 `close_agent` -- [ ] 复杂任务使用两阶段工作流（先澄清后执行） -- [ ] 不要提前 close，除非确定不再需要交互 -- [ ] 超时后评估是否继续等待或催促收敛 -- [ ] 合并结果时检查冲突和一致性 - -### 9.1 角色加载模式（重要） - -**❌ 错误模式：主流程读取角色内容并传递** -```javascript -// 主流程读取角色文件内容 -const exploreRole = Read('~/.codex/agents/cli-explore-agent.md') - -spawn_agent({ - message: ` -## ROLE DEFINITION -${exploreRole} // 内容嵌入到 message 中 - -## TASK -... -` -}) -``` - -**问题**： -- message 体积膨胀，传输开销大 -- 角色内容在主流程上下文中占用空间 -- 不符合 agent 自主性原则 - -**✅ 正确模式：传递路径，agent 自己读取** -```javascript -spawn_agent({ - message: ` -## TASK ASSIGNMENT -... - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first) -2. Read: .workflow/project-tech.json -3. Read: .workflow/project-guidelines.json -... -` -}) -``` - -**优势**： -- message 精简，只传递任务相关内容 -- agent 拥有完整的角色理解上下文 -- 遵循 agent 自主执行原则 - ---- - -## 10. Subagent 深度交互准则 - -### 10.1 核心理念：充分交流优于多次调用 - -**传统模式问题**： -- 探索 → 澄清 → 规划 分离执行，上下文断裂 -- 每个阶段独立 subagent，信息传递有损耗 -- 多轮用户交互，体验割裂 - -**优化理念**： -- **单 subagent 深度交互** > 多 subagent 浅层调用 -- **澄清与规划合并**，一次完成上下文积累 -- **send_input 多轮对话**，保持上下文连贯 - -### 10.2 澄清 + 规划合并模式 - -**原有分离模式**（Claude lite-plan）： -``` -Phase 1: spawn explore-agent × N → wait → close -Phase 2: 主 agent 收集澄清问题 → 用户回答 -Phase 3: spawn planning-agent → wait → close -``` - -**优化合并模式**（Codex 推荐）： -``` -Phase 1: spawn explore-agent × N → wait (保持 agent 活跃) -Phase 2: send_input 传递澄清答案 → agent 继续生成 plan -Phase 3: wait 获取最终 plan → close -``` - -**实现示例**： -```javascript -// ==================== 合并模式：探索 + 澄清 + 规划 ==================== - -// Step 1: 创建探索 agent（带规划能力） -const exploreRole = Read('~/.codex/agents/cli-explore-agent.md') -const planningRole = Read('~/.codex/agents/cli-lite-planning-agent.md') - -const agent = spawn_agent({ - message: ` -## ROLE DEFINITION (DUAL ROLE) - -### Primary: Exploration -${exploreRole} - -### Secondary: Planning (activated after clarification) -${planningRole} - ---- - -## TASK ASSIGNMENT - -### Phase 1: Exploration -Goal: Explore codebase for "${task_description}" -Output: Structured findings + clarification questions (if any) - -### Phase 2: Await Clarification (if questions exist) -Output format for questions: -\`\`\` -CLARIFICATION_NEEDED: -Q1: [question] | Options: [A, B, C] | Recommended: [A] -Q2: [question] | Options: [A, B] | Recommended: [B] -\`\`\` - -### Phase 3: Generate Plan (after clarification) -Trigger: Receive clarification answers via send_input -Output: plan.json following schema - -### Deliverables -- exploration.json (Phase 1) -- plan.json (Phase 3, after clarification) -` -}) - -// Step 2: 等待探索结果 -const exploreResult = wait({ ids: [agent], timeout_ms: 600000 }) - -// Step 3: 解析是否需要澄清 -const needsClarification = exploreResult.status[agent].completed.includes('CLARIFICATION_NEEDED') - -if (needsClarification) { - // Step 4: 获取用户回答（主 agent 处理） - const userAnswers = collectUserAnswers(exploreResult) - - // Step 5: 通过 send_input 继续交互（关键：不 close） - send_input({ - id: agent, - message: ` -## CLARIFICATION ANSWERS -${userAnswers.map(a => `Q: ${a.question}\nA: ${a.answer}`).join('\n\n')} - -## NEXT STEP -Based on exploration findings and clarification answers, generate plan.json. -Follow schema: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json -` - }) - - // Step 6: 等待规划结果 - const planResult = wait({ ids: [agent], timeout_ms: 900000 }) -} - -// Step 7: 最终清理 -close_agent({ id: agent }) -``` - -### 10.3 多轮 send_input 交互模式 - -**场景**：复杂任务需要多次迭代确认 - -```javascript -// 创建 agent -const agent = spawn_agent({ message: roleDefinition + taskPrompt }) - -// 第一轮：获取初步方案 -const round1 = wait({ ids: [agent], timeout_ms: 300000 }) - -// 第二轮：用户反馈后迭代 -send_input({ - id: agent, - message: ` -## USER FEEDBACK -${userFeedback} - -## REQUEST -Revise the plan based on feedback. Focus on: -1. ${focusPoint1} -2. ${focusPoint2} -` -}) -const round2 = wait({ ids: [agent], timeout_ms: 300000 }) - -// 第三轮：确认细节 -send_input({ - id: agent, - message: ` -## CONFIRMATION -Plan approved with minor adjustments: -- Change task T2 scope to include ${additionalScope} -- Add dependency T1 → T3 - -## FINAL REQUEST -Output final plan.json with these adjustments. -` -}) -const finalResult = wait({ ids: [agent], timeout_ms: 300000 }) - -// 清理 -close_agent({ id: agent }) -``` - -### 10.4 简化命令设计原则 - -**原则 1：减少 Phase 数量** -| 原有模式 | 优化模式 | -|----------|----------| -| Phase 1: Explore | Phase 1: Explore + Clarify + Plan (单 agent) | -| Phase 2: Clarify | ↑ | -| Phase 3: Plan | ↑ | -| Phase 4: Confirm | Phase 2: Confirm (主 agent) | -| Phase 5: Execute | Phase 3: Execute | - -**原则 2：延迟 close_agent** -```javascript -// ❌ 错误：过早关闭 -const result = wait({ ids: [agent] }) -close_agent({ id: agent }) // 关闭后无法继续交互 -// ... 发现需要追问，只能重建 agent - -// ✅ 正确：延迟关闭 -const result = wait({ ids: [agent] }) -// 检查是否需要继续交互 -if (needsMoreInteraction(result)) { - send_input({ id: agent, message: followUpMessage }) - const result2 = wait({ ids: [agent] }) -} -close_agent({ id: agent }) // 确认不再需要后才关闭 -``` - -**原则 3：上下文复用** -```javascript -// ❌ 错误：每个阶段独立 agent，上下文丢失 -const exploreAgent = spawn_agent({ message: explorePrompt }) -const exploreResult = wait({ ids: [exploreAgent] }) -close_agent({ id: exploreAgent }) - -const planAgent = spawn_agent({ - message: planPrompt + JSON.stringify(exploreResult) // 需要手动传递上下文 -}) - -// ✅ 正确：单 agent 多阶段，上下文自动保持 -const agent = spawn_agent({ message: dualRolePrompt }) -const exploreResult = wait({ ids: [agent] }) -send_input({ id: agent, message: "Now generate plan based on your findings" }) -const planResult = wait({ ids: [agent] }) // agent 自动保持探索上下文 -close_agent({ id: agent }) -``` - -### 10.5 效果对比 - -| 指标 | 分离模式 | 合并模式 | 提升 | -|------|----------|----------|------| -| Agent 创建数 | 3-5 | 1-2 | 60-80% ↓ | -| 用户交互轮次 | 3-4 | 1-2 | 50% ↓ | -| 上下文传递损耗 | 高 | 低 | 显著 ↓ | -| 总执行时间 | 长（多次 spawn/close） | 短（复用 agent） | 30-50% ↓ | -| 结果一致性 | 中（多 agent 可能不一致） | 高（单 agent 统一视角） | 显著 ↑ | - -### 10.6 适用场景判断 - -**使用合并模式**（推荐）： -- 探索 → 澄清 → 规划 流程 -- 诊断 → 澄清 → 修复方案 流程 -- 任何需要多阶段但上下文强相关的任务 - -**使用分离模式**： -- 多角度并行探索（不同角度独立，无需共享上下文） -- 职责完全不同的阶段（如：代码生成 vs 测试生成） -- 需要不同专业角色的场景 - ---- - -# Claude → Codex 多 Agent 命令转换规范 - -## 11. 转换概述 - -### 11.1 核心差异 - -| 维度 | Claude Code | Codex | -|------|-------------|-------| -| **角色定义** | `subagent_type` 参数自动加载 | 首条 message 显式加载 | -| **并行执行** | 多个 `Task()` 调用 | 多个 `spawn_agent()` + 批量 `wait()` | -| **结果获取** | 同步返回或 TaskOutput 轮询 | `wait({ ids })` 显式等待 | -| **追问/续做** | `resume` 参数 | `send_input()` | -| **生命周期** | 自动回收 | 显式 `close_agent()` | - -### 11.2 转换原则 - -1. **角色前置**：每个 subagent 首条消息必须包含角色定义 -2. **批量等待**：利用 `wait({ ids: [...] })` 实现真并行 -3. **结果汇聚**：主 agent 负责合并多个 subagent 结果 -4. **显式清理**：任务完成后统一 close - -## 12. 转换模板 - -### 12.1 Claude Task 调用转换 - -**Claude 原始调用**： -```javascript -Task( - subagent_type = "cli-explore-agent", - run_in_background = false, - description = "Explore: architecture", - prompt = ` -## Task Objective -Execute architecture exploration... -... -` -) -``` - -**Codex 转换后**： -```javascript -// Step 1: 读取角色定义 -const roleDefinition = Read('~/.codex/agents/cli-explore-agent.md') - -// Step 2: 创建 subagent（角色 + 任务合并） -const agentId = spawn_agent({ - message: ` -## ROLE DEFINITION -${roleDefinition} - ---- - -## TASK ASSIGNMENT - -### Task Objective -Execute architecture exploration... -... - -### Output Format -Summary/Findings/Proposed changes/Tests/Open questions -` -}) - -// Step 3: 等待结果 -const result = wait({ ids: [agentId], timeout_ms: 300000 }) - -// Step 4: 清理（可延迟到所有任务完成） -close_agent({ id: agentId }) -``` - -### 12.2 并行多 Agent 转换 - -**Claude 原始调用**（并行 3 个 agent）： -```javascript -// Claude: 发送多个 Task 调用 -const tasks = angles.map(angle => - Task( - subagent_type = "cli-explore-agent", - prompt = `Explore ${angle}...` - ) -) -``` - -**Codex 转换后**： -```javascript -// Step 1: 读取角色定义（只读一次） -const roleDefinition = Read('~/.codex/agents/cli-explore-agent.md') - -// Step 2: 并行创建多个 subagent -const agentIds = angles.map(angle => { - return spawn_agent({ - message: ` -## ROLE DEFINITION -${roleDefinition} - ---- - -## TASK ASSIGNMENT -Goal: Execute ${angle} exploration -Scope: ${scopeForAngle(angle)} -Context: ${contextForAngle(angle)} -Deliverables: JSON output following exploration schema -` - }) -}) - -// Step 3: 批量等待所有结果（关键优势） -const results = wait({ - ids: agentIds, - timeout_ms: 600000 // 10 分钟 -}) - -// Step 4: 汇总结果 -const aggregatedFindings = agentIds.map(id => results.status[id].completed) - -// Step 5: 批量清理 -agentIds.forEach(id => close_agent({ id })) -``` - -## 13. lite-plan 命令转换示例 - -### 13.1 Phase 1: 探索阶段转换 - -**Claude 原始实现**： -```javascript -// lite-plan.md Phase 1 -const explorationTasks = selectedAngles.map((angle, index) => - Task( - subagent_type="cli-explore-agent", - run_in_background=false, - description=`Explore: ${angle}`, - prompt=` -## Task Objective -Execute **${angle}** exploration... -## Assigned Context -- **Exploration Angle**: ${angle} -... -` - ) -) -``` - -**Codex 转换后**： -```javascript -// Step 1: 加载角色定义 -const exploreRole = Read('~/.codex/agents/cli-explore-agent.md') - -// Step 2: 并行创建探索 subagent -const explorationAgents = selectedAngles.map((angle, index) => { - return spawn_agent({ - message: ` -## ROLE DEFINITION -${exploreRole} - ---- - -## TASK ASSIGNMENT - -### Task Objective -Execute **${angle}** exploration for task planning context. - -### Assigned Context -- **Exploration Angle**: ${angle} -- **Task Description**: ${task_description} -- **Exploration Index**: ${index + 1} of ${selectedAngles.length} -- **Output File**: ${sessionFolder}/exploration-${angle}.json - -### MANDATORY FIRST STEPS -1. Run: ccw tool exec get_modules_by_depth '{}' -2. Run: rg -l "{keyword}" --type ts -3. Execute: cat ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json -4. Read: .workflow/project-tech.json -5. Read: .workflow/project-guidelines.json - -### Expected Output -**File**: ${sessionFolder}/exploration-${angle}.json -**Format**: JSON following explore-json-schema - -### Success Criteria -- [ ] Schema obtained -- [ ] At least 3 relevant files identified -- [ ] JSON output follows schema exactly -` - }) -}) - -// Step 3: 批量等待所有探索完成 -const explorationResults = wait({ - ids: explorationAgents, - timeout_ms: 600000 -}) - -// Step 4: 检查超时 -if (explorationResults.timed_out) { - // 部分 agent 可能仍在运行，决定是否继续等待 - console.log('部分探索超时，继续等待或使用已完成结果') -} - -// Step 5: 收集结果 -const completedExplorations = {} -explorationAgents.forEach((agentId, index) => { - const angle = selectedAngles[index] - if (explorationResults.status[agentId].completed) { - completedExplorations[angle] = explorationResults.status[agentId].completed - } -}) - -// Step 6: 清理 -explorationAgents.forEach(id => close_agent({ id })) -``` - -### 13.2 Phase 3: 规划阶段转换 - -**Claude 原始实现**： -```javascript -Task( - subagent_type="cli-lite-planning-agent", - run_in_background=false, - description="Generate detailed implementation plan", - prompt=` -Generate implementation plan and write plan.json. -## Output Schema Reference -... -` -) -``` - -**Codex 转换后**： -```javascript -// Step 1: 加载规划角色 -const planningRole = Read('~/.codex/agents/cli-lite-planning-agent.md') - -// Step 2: 创建规划 subagent -const planningAgent = spawn_agent({ - message: ` -## ROLE DEFINITION -${planningRole} - ---- - -## TASK ASSIGNMENT - -### Objective -Generate implementation plan and write plan.json. - -### Schema Reference -Execute: cat ~/.claude/workflows/cli-templates/schemas/plan-json-schema.json - -### Project Context (MANDATORY) -1. Read: .workflow/project-tech.json -2. Read: .workflow/project-guidelines.json - -### Task Description -${task_description} - -### Multi-Angle Exploration Context -${manifest.explorations.map(exp => ` -#### ${exp.angle} -Path: ${exp.path} -`).join('\n')} - -### User Clarifications -${JSON.stringify(clarificationContext) || "None"} - -### Complexity Level -${complexity} - -### Requirements -- Generate plan.json following schema -- Tasks: 2-7 structured tasks (group by feature, NOT by file) -- Include depends_on for true dependencies only - -### Output -Write: ${sessionFolder}/plan.json -Return: Brief completion summary -` -}) - -// Step 3: 等待规划完成 -const planResult = wait({ - ids: [planningAgent], - timeout_ms: 900000 // 15 分钟 -}) - -// Step 4: 清理 -close_agent({ id: planningAgent }) -``` - -## 14. 完整工作流转换模板 - -### 14.1 Codex 多阶段工作流结构 - -```javascript -// ==================== Phase 1: 探索 ==================== -const exploreRole = Read('~/.codex/agents/cli-explore-agent.md') -const explorationAgents = [] - -// 并行创建探索 agents -for (const angle of selectedAngles) { - explorationAgents.push(spawn_agent({ - message: ` -## ROLE DEFINITION -${exploreRole} - ---- - -## TASK: ${angle} Exploration -${buildExplorationPrompt(angle, task_description)} -` - })) -} - -// 批量等待 -const exploreResults = wait({ ids: explorationAgents, timeout_ms: 600000 }) - -// 收集结果 -const explorations = collectResults(exploreResults, selectedAngles) - -// 清理探索 agents -explorationAgents.forEach(id => close_agent({ id })) - -// ==================== Phase 2: 澄清（可选）==================== -const clarifications = aggregateClarifications(explorations) - -if (clarifications.length > 0) { - // 两阶段模式：先收集问题，再追问 - const clarifyAgent = spawn_agent({ - message: ` -## ROLE: Clarification Collector - -## Questions to Ask User -${clarifications.map((q, i) => `${i+1}. ${q.question}`).join('\n')} - -## Output Format -List questions with options and recommended choice. -` - }) - - const clarifyResult = wait({ ids: [clarifyAgent] }) - - // 主 agent 收集用户回答后，继续追问 - send_input({ - id: clarifyAgent, - message: ` -## User Responses -${userResponses.map(r => `Q: ${r.question}\nA: ${r.answer}`).join('\n\n')} - -## Next Step -Proceed to generate recommendations based on responses. -` - }) - - const finalClarify = wait({ ids: [clarifyAgent] }) - close_agent({ id: clarifyAgent }) -} - -// ==================== Phase 3: 规划 ==================== -const planRole = Read('~/.codex/agents/cli-lite-planning-agent.md') - -const planAgent = spawn_agent({ - message: ` -## ROLE DEFINITION -${planRole} - ---- - -## TASK: Generate Implementation Plan -${buildPlanningPrompt(task_description, explorations, clarificationContext)} -` -}) - -const planResult = wait({ ids: [planAgent], timeout_ms: 900000 }) -close_agent({ id: planAgent }) - -// ==================== Phase 4: 确认 & 执行 ==================== -// ... (主 agent 直接处理用户交互) -``` - -## 15. 角色文件管理 - -### 15.1 角色文件结构规范 - -```markdown ---- -name: {agent-name} -description: | - {简短描述，1-3行} -color: {blue|green|yellow|cyan|...} ---- - -{角色定义正文} - -## Core Capabilities -... - -## Execution Process -... - -## Key Reminders -**ALWAYS**: ... -**NEVER**: ... -``` - -### 15.2 新增角色检查清单 - -- [ ] 文件位于 `~/.codex/agents/` 目录 -- [ ] 包含 YAML front matter (name, description, color) -- [ ] 定义 Core Capabilities -- [ ] 定义 Execution Process/Workflow -- [ ] 包含 Key Reminders (ALWAYS/NEVER) -- [ ] 在 §4.4 角色映射表中添加条目 - -## 16. 常见转换问题 - -### 16.1 run_in_background 处理 - -**Claude**：`run_in_background=false` 表示同步等待 -**Codex**：始终异步，通过 `wait()` 控制同步点 - -```javascript -// Claude: run_in_background=false -Task(subagent_type="...", run_in_background=false, prompt="...") - -// Codex: spawn + 立即 wait -const agentId = spawn_agent({ message: "..." }) -const result = wait({ ids: [agentId] }) // 阻塞直到完成 -``` - -### 16.2 resume 转换 - -**Claude**：使用 `resume` 参数恢复 agent -**Codex**：使用 `send_input` 继续交互 - -```javascript -// Claude: resume -Task(subagent_type="...", resume=previousAgentId, prompt="Continue...") - -// Codex: send_input（需 agent 未 close） -send_input({ id: previousAgentId, message: "Continue..." }) -const result = wait({ ids: [previousAgentId] }) -``` - -### 16.3 TaskOutput 轮询转换 - -**Claude**：`TaskOutput({ task_id, block: false })` 轮询 -**Codex**：`wait({ ids, timeout_ms })` 带超时等待 - -```javascript -// Claude: 轮询模式 -while (!done) { - const output = TaskOutput({ task_id: id, block: false }) - if (output.status === 'completed') done = true - sleep(1000) -} - -// Codex: 超时等待 + 重试 -let result = wait({ ids: [id], timeout_ms: 30000 }) -while (result.timed_out) { - result = wait({ ids: [id], timeout_ms: 30000 }) // 继续等待 -} -``` - -## 17. 转换检查清单 - -转换 Claude 多 Agent 命令到 Codex 时，确保： - -- [ ] **角色加载**：首条 message 包含 `~/.codex/agents/*.md` 路径 -- [ ] **并行优化**：多个独立 agent 使用批量 `wait({ ids: [...] })` -- [ ] **超时处理**：设置合理 `timeout_ms`，处理 `timed_out` 情况 -- [ ] **结果汇聚**：主 agent 负责合并 `status[id].completed` -- [ ] **显式清理**：任务完成后调用 `close_agent` -- [ ] **追问模式**：需要续做时使用 `send_input`，不要提前 close -- [ ] **输出模板**：要求 subagent 使用统一结构化输出格式 - -## 18. Skill/命令设计原则 - -### 18.1 内容独立性 - -**Codex skill/命令文档中不应包含与 Claude 的对比内容**： - -- 对比表格属于转换准则（本文档），不属于最终产物 -- skill 文档应专注于 Codex 机制本身的使用 -- 避免引入无关上下文，保持文档简洁 - -### 18.2 模式选择灵活性 - -**不过度约束设计思路**： - -- 文档提供的模式（单 agent / 多 agent / 混合）是可选方案 -- 根据具体场景选择合适模式 -- 主 agent 可作为协调器，灵活利用各种机制 diff --git a/codex SUBAGENT.md b/codex SUBAGENT.md deleted file mode 100644 index 56cf53c1..00000000 --- a/codex SUBAGENT.md +++ /dev/null @@ -1,85 +0,0 @@ -# Codex Subagent 使用规范（说明文档） - -## 1. Subagent 是什么 - -Subagent 是由主 agent（当前对话）临时创建的“并行工作单元”，用于把任务拆分后并行推进；每个 subagent 有独立会话上下文，通过 `agent_id` 标识。 - -## 2. 核心特性 - -- **并行处理**：可同时创建多个 subagent，分别负责调研、方案、测试、实现建议等子任务。 -- **结构化交付**：适合要求 subagent 按固定模板输出（如 `Summary/Findings/Proposed changes/Tests/Open questions`），便于主 agent 汇总合并。 -- **迭代追问**：subagent 首次回包后，主 agent 可继续补充信息、纠偏或扩展任务。 -- **Open questions 工作流**：subagent 可先只提澄清问题；待主 agent 回答后再输出方案与测试建议。 - -## 3. 生命周期与 API 约定 - -### 3.1 创建 subagent - -- 调用：`functions.spawn_agent({ agent_type?, message })` -- 返回：`agent_id` - -建议在 `message` 中明确： - -- `Goal`：一句话目标 -- `Scope`：可做/不可做（目录、文件类型、是否允许引入依赖、是否允许跑命令） -- `Context`：最小必要上下文（关键路径、现状摘要、约束） -- `Deliverables`：强制输出格式 -- `Quality bar`：验收标准 - -### 3.2 获取结果（关键点） - -- 调用：`functions.wait({ ids, timeout_ms? })` -- 结果：出现在 `status[agent_id].completed`（subagent 回包内容） -- 超时：`timed_out=true` 不等于失败，可继续 `wait` 或 `send_input` 催促收敛 - -> 注意：`close_agent` 不是“返回结果”的前置条件；拿结果靠 `wait`。 - -### 3.3 继续追问/纠偏 - -- 调用：`functions.send_input({ id, message, interrupt? })` -- `interrupt=true`：用于立刻打断并纠偏（慎用，优先用普通追问） - -### 3.4 结束回收 - -- 调用：`functions.close_agent({ id })` -- 一旦关闭：该 subagent **不可恢复**；只能重新 `spawn_agent` 新的，并粘贴旧输出/上下文续做 - -## 4. 输出模板（推荐） - -要求 subagent 统一用以下结构回包，便于合并： - -```text -Summary: -- ... - -Findings: -- ... - -Proposed changes: -- 文件/模块： -- 变更点： -- 风险点： - -Tests: -- 需要新增/更新的用例： -- 需要运行的测试命令（如适用）： - -Open questions: -1. ... -2. ... -``` - -## 5. 并行拆分建议（高收益模式） - -- **Worker A（调研）**：定位入口、调用链、相似实现；交付“文件+符号+证据点”，不写方案。 -- **Worker B（方案）**：最小改动实现路径、兼容性与风险；交付“变更点清单”。 -- **Worker C（测试）**：测试策略、边界条件、Mock 点；交付“用例列表+覆盖点”。 - -原则：尽量按“模块/文件域”拆分，避免多个 subagent 同时建议修改同一文件导致冲突。 - -## 6. 常见坑与约定 - -- **不 close 也能拿结果**：`wait` 才是取结果的入口；`close_agent` 只是收尾清理。 -- **关闭不可逆**：想续聊就不要提前 close；若已 close，只能新建并补发上下文。 -- **范围控制**：subagent 只做分配的子任务，超出范围必须在 `Open questions` 里请求确认。 -