Refactor API calls to use csrfFetch for enhanced security across multiple views, including loop-monitor, mcp-manager, memory, prompt-history, rules-manager, session-detail, and skills-manager. Additionally, add Phase 1 and Phase 2 documentation for session initialization and orchestration loop in the ccw-loop-b skill.

2026-02-13 02:41:50 +08:00 · 2026-02-07 10:54:12 +08:00
parent f7dfbc0512
commit 92b0d175a7
49 changed files with 2003 additions and 480 deletions
--- a/.codex/skills/ccw-loop-b/SKILL.md
+++ b/.codex/skills/ccw-loop-b/SKILL.md
@@ -1,38 +1,60 @@
 ---
-name: CCW Loop-B
-description: Hybrid orchestrator pattern for iterative development. Coordinator + specialized workers with batch wait support. Triggers on "ccw-loop-b".
-argument-hint: TASK="<task description>" [--loop-id=<id>] [--mode=<interactive|auto|parallel>]
+name: ccw-loop-b
+description: Hybrid orchestrator pattern for iterative development. Coordinator + specialized workers with batch wait, parallel split, and two-phase clarification. Triggers on "ccw-loop-b".
+allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep
 ---

 # CCW Loop-B - Hybrid Orchestrator Pattern

-协调器 + 专用 worker 的迭代开发工作流。支持单 agent 深度交互、多 agent 并行、混合模式灵活切换。
+协调器 + 专用 worker 的迭代开发工作流。支持三种执行模式（Interactive / Auto / Parallel），每个 action 由独立 worker agent 执行，协调器负责调度、状态管理和结果汇聚。

-## Arguments
-
-| Arg | Required | Description |
-|-----|----------|-------------|
-| TASK | No | Task description (for new loop) |
-| --loop-id | No | Existing loop ID to continue |
-| --mode | No | `interactive` (default) / `auto` / `parallel` |
-
-## Architecture
+## Architecture Overview

 ```
 +------------------------------------------------------------+
 |                    Main Coordinator                         |
 |  职责: 状态管理 + worker 调度 + 结果汇聚 + 用户交互        |
 +------------------------------------------------------------+
-                              |
-         +--------------------+--------------------+
-         |                    |                    |
-         v                    v                    v
+          |                    |                    |
+          v                    v                    v
 +----------------+   +----------------+   +----------------+
 | Worker-Develop |   | Worker-Debug   |   | Worker-Validate|
 | 专注: 代码实现 |   | 专注: 问题诊断 |   | 专注: 测试验证 |
 +----------------+   +----------------+   +----------------+
+          |                    |                    |
+          v                    v                    v
+   .workers/              .workers/             .workers/
+   develop.output.json    debug.output.json     validate.output.json
 ```

+### Subagent API
+
+| API | 作用 | 注意事项 |
+|-----|------|----------|
+| `spawn_agent({ message })` | 创建 worker，返回 `agent_id` | 首条 message 加载角色 |
+| `wait({ ids, timeout_ms })` | 等待结果 | **唯一取结果入口**，非 close |
+| `send_input({ id, message })` | 继续交互/追问 | `interrupt=true` 慎用 |
+| `close_agent({ id })` | 关闭回收 | 不可逆，确认不再交互后才关闭 |
+
+## Key Design Principles
+
+1. **协调器保持轻量**: 只做调度和状态管理，具体工作交给 worker
+2. **Worker 职责单一**: 每个 worker 专注一个领域（develop/debug/validate）
+3. **角色路径传递**: Worker 自己读取角色文件，主流程不传递内容
+4. **延迟 close_agent**: 确认不再需要交互后才关闭 worker
+5. **两阶段工作流**: 复杂任务先澄清后执行，减少返工
+6. **批量等待优化**: 并行模式用 `wait({ ids: [...] })` 批量等待
+7. **结果标准化**: Worker 输出遵循统一 WORKER_RESULT 格式
+8. **灵活模式切换**: 根据任务复杂度选择 interactive/auto/parallel
+
+## Arguments
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| TASK | One of TASK or --loop-id | Task description (for new loop) |
+| --loop-id | One of TASK or --loop-id | Existing loop ID to continue |
+| --mode | No | `interactive` (default) / `auto` / `parallel` |
+
 ## Execution Modes

 ### Mode: Interactive (default)
@@ -45,7 +67,7 @@ Coordinator -> Show menu -> User selects -> spawn worker -> wait -> Display resu

 ### Mode: Auto

-自动按预设顺序执行，worker 完成后自动切换到下一阶段。
+自动按预设顺序执行，worker 完成后协调器决定下一步。

 ```
 Init -> Develop -> [if issues] Debug -> Validate -> [if fail] Loop back -> Complete
@@ -53,241 +75,342 @@ Init -> Develop -> [if issues] Debug -> Validate -> [if fail] Loop back -> Compl

 ### Mode: Parallel

-并行 spawn 多个 worker 分析不同维度，batch wait 汇聚结果。
+并行 spawn 多个 worker，batch wait 汇聚结果，协调器综合决策。

 ```
 Coordinator -> spawn [develop, debug, validate] in parallel -> wait({ ids: all }) -> Merge -> Decide
 ```

+## Execution Flow
+
+```
+Input Parsing:
+   └─ Parse arguments (TASK | --loop-id + --mode)
+   └─ Convert to structured context (loopId, state, mode)
+
+Phase 1: Session Initialization
+   └─ Ref: phases/01-session-init.md
+      ├─ Create new loop OR resume existing loop
+      ├─ Initialize state file and directory structure
+      └─ Output: loopId, state, progressDir, mode
+
+Phase 2: Orchestration Loop
+   └─ Ref: phases/02-orchestration-loop.md
+      ├─ Mode dispatch: interactive / auto / parallel
+      ├─ Worker spawn with structured prompt (Goal/Scope/Context/Deliverables)
+      ├─ Wait + timeout handling + result parsing
+      ├─ State update per iteration
+      └─ close_agent on loop exit
+```
+
+**Phase Reference Documents** (read on-demand when phase executes):
+
+| Phase | Document | Purpose |
+|-------|----------|---------|
+| 1 | [phases/01-session-init.md](phases/01-session-init.md) | Argument parsing, state creation/resume, directory init |
+| 2 | [phases/02-orchestration-loop.md](phases/02-orchestration-loop.md) | 3-mode orchestration, worker spawn, batch wait, result merge |
+
+## Data Flow
+
+```
+User Input (TASK | --loop-id + --mode)
+    ↓
+[Parse Arguments]
+    ↓ loopId, state, mode
+
+Phase 1: Session Initialization
+    ↓ loopId, state (initialized/resumed), progressDir
+
+Phase 2: Orchestration Loop
+    ↓
+    ┌─── Interactive Mode ──────────────────────────────────┐
+    │ showMenu → user selects → spawn worker → wait →       │
+    │ parseResult → updateState → close worker → loop       │
+    └───────────────────────────────────────────────────────┘
+    ┌─── Auto Mode ─────────────────────────────────────────┐
+    │ selectNext → spawn worker → wait → parseResult →      │
+    │ updateState → close worker → [loop_back?] → next      │
+    └───────────────────────────────────────────────────────┘
+    ┌─── Parallel Mode ─────────────────────────────────────┐
+    │ spawn [develop, debug, validate] → batch wait →       │
+    │ mergeOutputs → coordinator decides → close all        │
+    └───────────────────────────────────────────────────────┘
+    ↓
+return finalState
+```
+
 ## Session Structure

 ```
 .workflow/.loop/
-+-- {loopId}.json              # Master state
-+-- {loopId}.workers/          # Worker outputs
-|   +-- develop.output.json
-|   +-- debug.output.json
-|   +-- validate.output.json
-+-- {loopId}.progress/         # Human-readable progress
-    +-- develop.md
-    +-- debug.md
-    +-- validate.md
-    +-- summary.md
+├── {loopId}.json                    # Master state (API + Skill shared)
+├── {loopId}.workers/                # Worker structured outputs
+│   ├── init.output.json
+│   ├── develop.output.json
+│   ├── debug.output.json
+│   ├── validate.output.json
+│   └── complete.output.json
+└── {loopId}.progress/               # Human-readable progress
+    ├── develop.md
+    ├── debug.md
+    ├── validate.md
+    └── summary.md
 ```

-## Subagent API
+## State Management

-| API | 作用 |
-|-----|------|
-| `spawn_agent({ message })` | 创建 agent，返回 `agent_id` |
-| `wait({ ids, timeout_ms })` | 等待结果（唯一取结果入口） |
-| `send_input({ id, message })` | 继续交互 |
-| `close_agent({ id })` | 关闭回收 |
+Master state file: `.workflow/.loop/{loopId}.json`

-## Implementation
+```json
+{
+  "loop_id": "loop-b-20260122-abc123",
+  "title": "Task title",
+  "description": "Full task description",
+  "mode": "interactive | auto | parallel",
+  "status": "running | paused | completed | failed",
+  "current_iteration": 0,
+  "max_iterations": 10,
+  "created_at": "ISO8601",
+  "updated_at": "ISO8601",

-### Coordinator Logic
-
-```javascript
-// ==================== HYBRID ORCHESTRATOR ====================
-
-// 1. Initialize
-const loopId = args['--loop-id'] || generateLoopId()
-const mode = args['--mode'] || 'interactive'
-let state = readOrCreateState(loopId, taskDescription)
-
-// 2. Mode selection
-switch (mode) {
-  case 'interactive':
-    await runInteractiveMode(loopId, state)
-    break
-
-  case 'auto':
-    await runAutoMode(loopId, state)
-    break
-
-  case 'parallel':
-    await runParallelMode(loopId, state)
-    break
-}
-```
-
-### Interactive Mode (单 agent 交互或按需 spawn worker)
-
-```javascript
-async function runInteractiveMode(loopId, state) {
-  while (state.status === 'running') {
-    // Show menu, get user choice
-    const action = await showMenuAndGetChoice(state)
-
-    if (action === 'exit') break
-
-    // Spawn specialized worker for the action
-    const workerId = spawn_agent({
-      message: buildWorkerPrompt(action, loopId, state)
-    })
-
-    // Wait for worker completion
-    const result = wait({ ids: [workerId], timeout_ms: 600000 })
-    const output = result.status[workerId].completed
-
-    // Update state and display result
-    state = updateState(loopId, action, output)
-    displayResult(output)
-
-    // Cleanup worker
-    close_agent({ id: workerId })
+  "skill_state": {
+    "phase": "init | develop | debug | validate | complete",
+    "action_index": 0,
+    "workers_completed": [],
+    "parallel_results": null,
+    "pending_tasks": [],
+    "completed_tasks": [],
+    "findings": []
  }
 }
 ```

-### Auto Mode (顺序执行 worker 链)
+**Control Signal Checking**: 协调器在每次 spawn worker 前检查 `state.status`:
+- `running` → continue
+- `paused` → exit gracefully, wait for resume
+- `failed` → terminate

-```javascript
-async function runAutoMode(loopId, state) {
-  const actionSequence = ['init', 'develop', 'debug', 'validate', 'complete']
-  let currentIndex = state.skill_state?.action_index || 0
+**Recovery**: If state corrupted, rebuild from `.progress/` markdown files and `.workers/*.output.json`.

-  while (currentIndex < actionSequence.length && state.status === 'running') {
-    const action = actionSequence[currentIndex]
+## Worker Catalog

-    // Spawn worker
-    const workerId = spawn_agent({
-      message: buildWorkerPrompt(action, loopId, state)
-    })
+| Worker | Role File | Purpose | Output Files |
+|--------|-----------|---------|--------------|
+| [init](workers/worker-init.md) | ccw-loop-b-init.md | 会话初始化、任务解析 | init.output.json |
+| [develop](workers/worker-develop.md) | ccw-loop-b-develop.md | 代码实现、重构 | develop.output.json, develop.md |
+| [debug](workers/worker-debug.md) | ccw-loop-b-debug.md | 问题诊断、假设验证 | debug.output.json, debug.md |
+| [validate](workers/worker-validate.md) | ccw-loop-b-validate.md | 测试执行、覆盖率 | validate.output.json, validate.md |
+| [complete](workers/worker-complete.md) | ccw-loop-b-complete.md | 总结收尾 | complete.output.json, summary.md |

-    const result = wait({ ids: [workerId], timeout_ms: 600000 })
-    const output = result.status[workerId].completed
+### Worker Dependencies

-    // Parse worker result to determine next step
-    const workerResult = parseWorkerResult(output)
+| Worker | Depends On | Leads To |
+|--------|------------|----------|
+| init | - | develop (auto) / menu (interactive) |
+| develop | init | validate / debug |
+| debug | init | develop / validate |
+| validate | develop or debug | complete / develop (if fail) |
+| complete | - | Terminal |

-    // Update state
-    state = updateState(loopId, action, output)
+### Worker Sequences

-    close_agent({ id: workerId })
-
-    // Determine next action
-    if (workerResult.needs_loop_back) {
-      // Loop back to develop or debug
-      currentIndex = actionSequence.indexOf(workerResult.loop_back_to)
-    } else if (workerResult.status === 'failed') {
-      // Stop on failure
-      break
-    } else {
-      currentIndex++
-    }
-  }
-}
+```
+Simple Task (Auto):     init → develop → validate → complete
+Complex Task (Auto):    init → develop → validate (fail) → debug → develop → validate → complete
+Bug Fix (Auto):         init → debug → develop → validate → complete
+Analysis (Parallel):    init → [develop ‖ debug ‖ validate] → complete
+Interactive:            init → menu → user selects → worker → menu → ...
 ```

-### Parallel Mode (批量 spawn + wait)
+## Worker Prompt Protocol

-```javascript
-async function runParallelMode(loopId, state) {
-  // Spawn multiple workers in parallel
-  const workers = {
-    develop: spawn_agent({ message: buildWorkerPrompt('develop', loopId, state) }),
-    debug: spawn_agent({ message: buildWorkerPrompt('debug', loopId, state) }),
-    validate: spawn_agent({ message: buildWorkerPrompt('validate', loopId, state) })
-  }
-
-  // Batch wait for all workers
-  const results = wait({
-    ids: Object.values(workers),
-    timeout_ms: 900000  // 15 minutes for all
-  })
-
-  // Collect outputs
-  const outputs = {}
-  for (const [role, workerId] of Object.entries(workers)) {
-    outputs[role] = results.status[workerId].completed
-    close_agent({ id: workerId })
-  }
-
-  // Merge and analyze results
-  const mergedAnalysis = mergeWorkerOutputs(outputs)
-
-  // Update state with merged results
-  updateState(loopId, 'parallel-analysis', mergedAnalysis)
-
-  // Coordinator decides next action based on merged results
-  const decision = decideNextAction(mergedAnalysis)
-  return decision
-}
-```
-
-### Worker Prompt Builder
+### Spawn Message Structure (§7.1)

 ```javascript
 function buildWorkerPrompt(action, loopId, state) {
-  const workerRoles = {
-    develop: '~/.codex/agents/ccw-loop-b-develop.md',
-    debug: '~/.codex/agents/ccw-loop-b-debug.md',
-    validate: '~/.codex/agents/ccw-loop-b-validate.md',
-    init: '~/.codex/agents/ccw-loop-b-init.md',
-    complete: '~/.codex/agents/ccw-loop-b-complete.md'
-  }
-
  return `
 ## TASK ASSIGNMENT

 ### MANDATORY FIRST STEPS (Agent Execute)
-1. **Read role definition**: ${workerRoles[action]} (MUST read first)
+1. **Read role definition**: ~/.codex/agents/ccw-loop-b-${action}.md (MUST read first)
 2. Read: .workflow/project-tech.json
 3. Read: .workflow/project-guidelines.json

 ---

-## LOOP CONTEXT
+Goal: ${goalForAction(action, state)}

- **Loop ID**: ${loopId}
- **Action**: ${action}
- **State File**: .workflow/.loop/${loopId}.json
- **Output File**: .workflow/.loop/${loopId}.workers/${action}.output.json
- **Progress File**: .workflow/.loop/${loopId}.progress/${action}.md
+Scope:
+- 可做: ${allowedScope(action)}
+- 不可做: ${forbiddenScope(action)}
+- 目录限制: ${directoryScope(action, state)}

-## CURRENT STATE
+Context:
+- Loop ID: ${loopId}
+- State: .workflow/.loop/${loopId}.json
+- Output: .workflow/.loop/${loopId}.workers/${action}.output.json
+- Progress: .workflow/.loop/${loopId}.progress/${action}.md

-${JSON.stringify(state, null, 2)}
+Deliverables:
+- 按 WORKER_RESULT 格式输出
+- 写入 output.json 和 progress.md

-## TASK DESCRIPTION
-
-${state.description}
-
-## EXPECTED OUTPUT
-
-\`\`\`
-WORKER_RESULT:
- action: ${action}
- status: success | failed | needs_input
- summary: <brief summary>
- files_changed: [list]
- next_suggestion: <suggested next action>
- loop_back_to: <action name if needs loop back>
-
-DETAILED_OUTPUT:
-<structured output specific to action type>
-\`\`\`
-
-Execute the ${action} action now.
+Quality bar:
+- ${qualityCriteria(action)}
 `
 }
 ```

-## Worker Roles
+**关键**: 角色文件由 worker 自己读取，主流程只传递路径。不嵌入角色内容。

-| Worker | Role File | 专注领域 |
-|--------|-----------|----------|
-| init | ccw-loop-b-init.md | 会话初始化、任务解析 |
-| develop | ccw-loop-b-develop.md | 代码实现、重构 |
-| debug | ccw-loop-b-debug.md | 问题诊断、假设验证 |
-| validate | ccw-loop-b-validate.md | 测试执行、覆盖率 |
-| complete | ccw-loop-b-complete.md | 总结收尾 |
+### Worker Output Format (WORKER_RESULT)

-## State Schema
+```
+WORKER_RESULT:
+- action: {action_name}
+- status: success | failed | needs_input
+- summary: <brief summary>
+- files_changed: [list]
+- next_suggestion: <suggested next action>
+- loop_back_to: <action name if needs loop back, or null>

-See [phases/state-schema.md](phases/state-schema.md)
+DETAILED_OUTPUT:
+<action-specific structured output>
+```
+
+### Two-Phase Clarification (§5.2)
+
+Worker 遇到模糊需求时采用两阶段模式:
+
+```
+阶段 1: Worker 输出 CLARIFICATION_NEEDED + Open questions
+阶段 2: 协调器收集用户回答 → send_input → Worker 继续执行
+```
+
+```javascript
+// 解析 worker 是否需要澄清
+if (output.includes('CLARIFICATION_NEEDED')) {
+  const userAnswers = await collectUserAnswers(output)
+  send_input({
+    id: workerId,
+    message: `## CLARIFICATION ANSWERS\n${userAnswers}\n\n## CONTINUE EXECUTION`
+  })
+  const finalResult = wait({ ids: [workerId], timeout_ms: 600000 })
+}
+```
+
+## Parallel Split Strategy (§6)
+
+### Strategy 1: 按职责域拆分（推荐）
+
+| Worker | 职责 | 交付物 | 禁止事项 |
+|--------|------|--------|----------|
+| develop | 定位入口、调用链、实现方案 | 变更点清单 | 不做测试 |
+| debug | 问题诊断、风险评估 | 问题清单+修复建议 | 不写代码 |
+| validate | 测试策略、覆盖分析 | 测试结果+质量报告 | 不改实现 |
+
+### Strategy 2: 按模块域拆分
+
+```
+Worker 1: src/auth/**     → 认证模块变更
+Worker 2: src/api/**      → API 层变更
+Worker 3: src/database/** → 数据层变更
+```
+
+### 拆分原则
+
+1. **文件隔离**: 避免多个 worker 同时修改同一文件
+2. **职责单一**: 每个 worker 只做一件事
+3. **边界清晰**: 超出范围用 `CLARIFICATION_NEEDED` 请求确认
+4. **最小上下文**: 只传递完成任务所需的最小信息
+
+## Result Merge (Parallel Mode)
+
+```javascript
+function mergeWorkerOutputs(outputs) {
+  return {
+    develop: parseWorkerResult(outputs.develop),
+    debug: parseWorkerResult(outputs.debug),
+    validate: parseWorkerResult(outputs.validate),
+    conflicts: detectConflicts(outputs),  // 检查 worker 间建议冲突
+    merged_at: getUtc8ISOString()
+  }
+}
+```
+
+**冲突检测**: 当多个 worker 建议修改同一文件时，协调器标记冲突，由用户决定。
+
+## TodoWrite Pattern
+
+### Phase-Level Tracking (Attached)
+
+```json
+[
+  {"content": "Phase 1: Session Initialization", "status": "completed"},
+  {"content": "Phase 2: Orchestration Loop (auto mode)", "status": "in_progress"},
+  {"content": "  → Worker: init", "status": "completed"},
+  {"content": "  → Worker: develop (task 2/5)", "status": "in_progress"},
+  {"content": "  → Worker: validate", "status": "pending"},
+  {"content": "  → Worker: complete", "status": "pending"}
+]
+```
+
+### Parallel Mode Tracking
+
+```json
+[
+  {"content": "Phase 1: Session Initialization", "status": "completed"},
+  {"content": "Phase 2: Parallel Analysis", "status": "in_progress"},
+  {"content": "  → Worker: develop (parallel)", "status": "in_progress"},
+  {"content": "  → Worker: debug (parallel)", "status": "in_progress"},
+  {"content": "  → Worker: validate (parallel)", "status": "in_progress"},
+  {"content": "  → Merge results", "status": "pending"}
+]
+```
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, then Phase 1 execution
+2. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute
+3. **Parse Every Output**: Extract WORKER_RESULT from worker output for next decision
+4. **Worker 生命周期**: spawn → wait → [send_input if needed] → close，不长期保留 worker
+5. **结果持久化**: Worker 输出写入 `.workflow/.loop/{loopId}.workers/`
+6. **状态同步**: 每次 worker 完成后更新 master state
+7. **超时处理**: send_input 请求收敛，再超时则使用已有结果继续
+8. **DO NOT STOP**: Continuous execution until completed, paused, or max iterations
+
+## Error Handling
+
+| Error Type | Recovery |
+|------------|----------|
+| Worker timeout | send_input 请求收敛 → 再超时则跳过 |
+| Worker failed | Log error, 协调器决策是否重试 |
+| Batch wait partial timeout | 使用已完成结果继续 |
+| State corrupted | 从 progress 文件和 worker output 重建 |
+| Conflicting worker results | 标记冲突，由用户决定 |
+| Max iterations reached | 生成总结，记录未完成项 |
+
+## Coordinator Checklist
+
+### Before Each Phase
+
+- [ ] Read phase reference document
+- [ ] Check current state and control signals
+- [ ] Update TodoWrite with phase tasks
+
+### After Each Worker
+
+- [ ] Parse WORKER_RESULT from output
+- [ ] Persist output to `.workers/{action}.output.json`
+- [ ] Update master state file
+- [ ] close_agent (确认不再需要交互)
+- [ ] Determine next action (continue / loop back / complete)
+
+## Reference Documents
+
+| Document | Purpose |
+|----------|---------|
+| [workers/](workers/) | Worker 定义 (init, develop, debug, validate, complete) |

 ## Usage

@@ -304,20 +427,3 @@ See [phases/state-schema.md](phases/state-schema.md)
 # Resume existing loop
 /ccw-loop-b --loop-id=loop-b-20260122-abc123
 ```
-
-## Error Handling
-
-| Situation | Action |
-|-----------|--------|
-| Worker timeout | send_input 请求收敛 |
-| Worker failed | Log error, 协调器决策是否重试 |
-| Batch wait partial timeout | 使用已完成结果继续 |
-| State corrupted | 从 progress 文件重建 |
-
-## Best Practices
-
-1. **协调器保持轻量**: 只做调度和状态管理，具体工作交给 worker
-2. **Worker 职责单一**: 每个 worker 专注一个领域
-3. **结果标准化**: Worker 输出遵循统一 WORKER_RESULT 格式
-4. **灵活模式切换**: 根据任务复杂度选择合适模式
-5. **及时清理**: Worker 完成后 close_agent 释放资源