Add lightweight interactive planning workflows: Lite-Plan-B and Lite-Plan-C

- Introduced Lite-Plan-B for hybrid mode planning with multi-agent parallel exploration and primary agent merge/clarify/plan capabilities. - Added Lite-Plan-C for Codex subagent orchestration, featuring intelligent task analysis, parallel exploration, and adaptive planning based on task complexity. - Both workflows include detailed execution processes, session setup, and structured output formats for exploration and planning results.
2026-02-16 02:43:15 +08:00 · 2026-01-22 21:40:57 +08:00
parent 6428febdf6
commit 407b2e6930
6 changed files with 2688 additions and 271 deletions
--- a/策略补充.md
+++ b/策略补充.md
@@ -73,7 +73,7 @@ Codex subagent **没有系统提示词**，无法像 Claude Code 那样通过 `s
 ### 4.2 角色文件位置

 ```
-.codex/agents/
+~/.codex/agents/
 ├── cli-explore-agent.md          # 代码探索
 ├── cli-lite-planning-agent.md    # 轻量规划
 ├── code-developer.md             # 代码开发
@@ -86,11 +86,15 @@ Codex subagent **没有系统提示词**，无法像 Claude Code 那样通过 `s
 ### 4.3 角色加载模板

 ```javascript
-// 标准 spawn_agent 消息结构
+// 标准 spawn_agent 消息结构（角色路径传递，agent 自己读取）
 spawn_agent({
  message: `
-## ROLE DEFINITION
-${Read('.codex/agents/{agent-type}.md')}
+## 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}
@@ -101,19 +105,21 @@ ${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` |
+| `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. 结构化交付模式

@@ -182,16 +188,18 @@ Worker 3: src/database/** → 数据层变更

 ## 7. 消息设计规范

-### 7.1 spawn_agent message 结构（含角色加载）
+### 7.1 spawn_agent message 结构（角色路径传递）

 ```text
-## ROLE DEFINITION
-{角色文件内容 - 从 .codex/agents/*.md 读取}
+## 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 ASSIGNMENT
-
 Goal: 一句话目标（做什么）

 Scope:
@@ -213,6 +221,8 @@ Quality bar:
 - 验收标准 2
 ```

+> **注意**：角色文件路径放在 MANDATORY FIRST STEPS，由 agent 自己读取。主流程不传递角色内容。
+
 ### 7.2 send_input 追问模式

 ```text
@@ -247,7 +257,7 @@ spawn_agent(new_message) → 创建新 agent

 ## 9. 最佳实践清单

- [ ] **首条消息加载角色**：从 `.codex/agents/*.md` 读取角色定义
+- [ ] **角色文件路径传递**：在 MANDATORY FIRST STEPS 中指定 `~/.codex/agents/*.md` 路径，由 agent 自己读取
 - [ ] 创建前明确 Goal/Scope/Context/Deliverables/Quality bar
 - [ ] 按职责或模块域拆分，避免文件冲突
 - [ ] 要求统一输出模板，便于合并
@@ -257,13 +267,278 @@ spawn_agent(new_message) → 创建新 agent
 - [ ] 超时后评估是否继续等待或催促收敛
 - [ ] 合并结果时检查冲突和一致性

+### 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 命令转换规范

-## 10. 转换概述
+## 11. 转换概述

-### 10.1 核心差异
+### 11.1 核心差异

 | 维度 | Claude Code | Codex |
 |------|-------------|-------|
@@ -273,16 +548,16 @@ spawn_agent(new_message) → 创建新 agent
 | **追问/续做** | `resume` 参数 | `send_input()` |
 | **生命周期** | 自动回收 | 显式 `close_agent()` |

-### 10.2 转换原则
+### 11.2 转换原则

 1. **角色前置**：每个 subagent 首条消息必须包含角色定义
 2. **批量等待**：利用 `wait({ ids: [...] })` 实现真并行
 3. **结果汇聚**：主 agent 负责合并多个 subagent 结果
 4. **显式清理**：任务完成后统一 close

-## 11. 转换模板
+## 12. 转换模板

-### 11.1 Claude Task 调用转换
+### 12.1 Claude Task 调用转换

 **Claude 原始调用**：
 ```javascript
@@ -301,7 +576,7 @@ Execute architecture exploration...
 **Codex 转换后**：
 ```javascript
 // Step 1: 读取角色定义
-const roleDefinition = Read('.codex/agents/cli-explore-agent.md')
+const roleDefinition = Read('~/.codex/agents/cli-explore-agent.md')

 // Step 2: 创建 subagent（角色 + 任务合并）
 const agentId = spawn_agent({
@@ -329,7 +604,7 @@ const result = wait({ ids: [agentId], timeout_ms: 300000 })
 close_agent({ id: agentId })
 ```

-### 11.2 并行多 Agent 转换
+### 12.2 并行多 Agent 转换

 **Claude 原始调用**（并行 3 个 agent）：
 ```javascript
@@ -345,7 +620,7 @@ const tasks = angles.map(angle =>
 **Codex 转换后**：
 ```javascript
 // Step 1: 读取角色定义（只读一次）
-const roleDefinition = Read('.codex/agents/cli-explore-agent.md')
+const roleDefinition = Read('~/.codex/agents/cli-explore-agent.md')

 // Step 2: 并行创建多个 subagent
 const agentIds = angles.map(angle => {
@@ -378,9 +653,9 @@ const aggregatedFindings = agentIds.map(id => results.status[id].completed)
 agentIds.forEach(id => close_agent({ id }))
 ```

-## 12. lite-plan 命令转换示例
+## 13. lite-plan 命令转换示例

-### 12.1 Phase 1: 探索阶段转换
+### 13.1 Phase 1: 探索阶段转换

 **Claude 原始实现**：
 ```javascript
@@ -404,7 +679,7 @@ Execute **${angle}** exploration...
 **Codex 转换后**：
 ```javascript
 // Step 1: 加载角色定义
-const exploreRole = Read('.codex/agents/cli-explore-agent.md')
+const exploreRole = Read('~/.codex/agents/cli-explore-agent.md')

 // Step 2: 并行创建探索 subagent
 const explorationAgents = selectedAngles.map((angle, index) => {
@@ -470,7 +745,7 @@ explorationAgents.forEach((agentId, index) => {
 explorationAgents.forEach(id => close_agent({ id }))
 ```

-### 12.2 Phase 3: 规划阶段转换
+### 13.2 Phase 3: 规划阶段转换

 **Claude 原始实现**：
 ```javascript
@@ -489,7 +764,7 @@ Generate implementation plan and write plan.json.
 **Codex 转换后**：
 ```javascript
 // Step 1: 加载规划角色
-const planningRole = Read('.codex/agents/cli-lite-planning-agent.md')
+const planningRole = Read('~/.codex/agents/cli-lite-planning-agent.md')

 // Step 2: 创建规划 subagent
 const planningAgent = spawn_agent({
@@ -547,13 +822,13 @@ const planResult = wait({
 close_agent({ id: planningAgent })
 ```

-## 13. 完整工作流转换模板
+## 14. 完整工作流转换模板

-### 13.1 Codex 多阶段工作流结构
+### 14.1 Codex 多阶段工作流结构

 ```javascript
 // ==================== Phase 1: 探索 ====================
-const exploreRole = Read('.codex/agents/cli-explore-agent.md')
+const exploreRole = Read('~/.codex/agents/cli-explore-agent.md')
 const explorationAgents = []

 // 并行创建探索 agents
@@ -616,7 +891,7 @@ Proceed to generate recommendations based on responses.
 }

 // ==================== Phase 3: 规划 ====================
-const planRole = Read('.codex/agents/cli-lite-planning-agent.md')
+const planRole = Read('~/.codex/agents/cli-lite-planning-agent.md')

 const planAgent = spawn_agent({
  message: `
@@ -637,9 +912,9 @@ close_agent({ id: planAgent })
 // ... (主 agent 直接处理用户交互)
 ```

-## 14. 角色文件管理
+## 15. 角色文件管理

-### 14.1 角色文件结构规范
+### 15.1 角色文件结构规范

 ```markdown
 ---
@@ -662,18 +937,18 @@ color: {blue|green|yellow|cyan|...}
 **NEVER**: ...
 ```

-### 14.2 新增角色检查清单
+### 15.2 新增角色检查清单

- [ ] 文件位于 `.codex/agents/` 目录
+- [ ] 文件位于 `~/.codex/agents/` 目录
 - [ ] 包含 YAML front matter (name, description, color)
 - [ ] 定义 Core Capabilities
 - [ ] 定义 Execution Process/Workflow
 - [ ] 包含 Key Reminders (ALWAYS/NEVER)
 - [ ] 在 §4.4 角色映射表中添加条目

-## 15. 常见转换问题
+## 16. 常见转换问题

-### 15.1 run_in_background 处理
+### 16.1 run_in_background 处理

 **Claude**：`run_in_background=false` 表示同步等待
 **Codex**：始终异步，通过 `wait()` 控制同步点
@@ -687,7 +962,7 @@ const agentId = spawn_agent({ message: "..." })
 const result = wait({ ids: [agentId] })  // 阻塞直到完成
 ```

-### 15.2 resume 转换
+### 16.2 resume 转换

 **Claude**：使用 `resume` 参数恢复 agent
 **Codex**：使用 `send_input` 继续交互
@@ -701,7 +976,7 @@ send_input({ id: previousAgentId, message: "Continue..." })
 const result = wait({ ids: [previousAgentId] })
 ```

-### 15.3 TaskOutput 轮询转换
+### 16.3 TaskOutput 轮询转换

 **Claude**：`TaskOutput({ task_id, block: false })` 轮询
 **Codex**：`wait({ ids, timeout_ms })` 带超时等待
@@ -721,11 +996,11 @@ while (result.timed_out) {
 }
 ```

-## 16. 转换检查清单
+## 17. 转换检查清单

 转换 Claude 多 Agent 命令到 Codex 时，确保：

- [ ] **角色加载**：首条 message 包含 `.codex/agents/*.md` 内容
+- [ ] **角色加载**：首条 message 包含 `~/.codex/agents/*.md` 内容
 - [ ] **并行优化**：多个独立 agent 使用批量 `wait({ ids: [...] })`
 - [ ] **超时处理**：设置合理 `timeout_ms`，处理 `timed_out` 情况
 - [ ] **结果汇聚**：主 agent 负责合并 `status[id].completed`