sillyspec 3.9.0 → 3.10.0

package/src/stages/doctor.js

@@ -0,0 +1,303 @@
+// SillySpec Doctor — 项目自检阶段
+// 检查项通过 prompt 中的 bash 命令执行，此文件仅定义步骤结构
+
+
+export const definition = {
+  name: 'doctor',
+  title: '项目自检',
+  description: '检查 SillySpec 配置、构建环境和外部依赖',
+  auxiliary: true,
+  steps: [
+    {
+      name: 'SillySpec 内部检查',
+      prompt: `运行 SillySpec 内部检查。逐项执行以下命令并汇总结果：
+
+### 1. 目录结构完整性
+\`\`\`bash
+# 检查 .sillyspec/ 及子目录
+for d in .sillyspec .sillyspec/projects .sillyspec/docs .sillyspec/changes .sillyspec/.runtime; do
+  [ -d "$d" ] && echo "✅ $d" || echo "❌ $d"
+done
+# 检查 progress.json
+[ -f .sillyspec/.runtime/progress.json ] && echo "✅ progress.json 存在" || echo "❌ progress.json 不存在"
+node -e "JSON.parse(require('fs').readFileSync('.sillyspec/.runtime/progress.json','utf8')); console.log('✅ progress.json 可解析')" 2>/dev/null || echo "⚠️ progress.json 不可解析"
+\`\`\`
+
+### 2. 项目配置检查
+\`\`\`bash
+ls .sillyspec/projects/*.yaml 2>/dev/null
+# 对每个 yaml 文件，检查 name 和 path 字段，验证 path 存在
+for f in .sillyspec/projects/*.yaml; do
+  [ -f "$f" ] || continue
+  name=$(grep '^name:' "$f" | head -1 | sed 's/^name:[[:space:]]*//')
+  p=$(grep '^path:' "$f" | head -1 | sed 's/^path:[[:space:]]*//')
+  [ -z "$name" ] && echo "⚠️ $(basename $f) — 缺少 name"
+  [ -z "$p" ] && echo "⚠️ $(basename $f) — 缺少 path"
+  [ -n "$p" ] && [ ! -d "$p" ] && echo "❌ $(basename $f) — path 不存在: $p"
+  [ -n "$name" ] && [ -n "$p" ] && [ -d "$p" ] && echo "✅ $(basename $f) — $name ($p)"
+done
+\`\`\`
+
+### 3. 进度数据一致性
+\`\`\`bash
+# 读取 currentChange 并检查目录存在性
+node -e "
+const p = JSON.parse(require('fs').readFileSync('.sillyspec/.runtime/progress.json','utf8'));
+const cc = p.currentChange;
+if (!cc) { console.log('ℹ️ 无当前变更'); process.exit(0); }
+const dir = '.sillyspec/changes/' + cc;
+const exists = require('fs').existsSync(dir);
+console.log(exists ? '✅ currentChange 目录存在: ' + cc : '❌ currentChange 目录不存在: ' + cc);
+// 检查各阶段产出
+const stages = p.stages || {};
+for (const [name, sd] of Object.entries(stages)) {
+  if (sd.status === 'completed' && sd.steps.length > 0) {
+    const hasOutput = sd.steps.some(s => s.output && s.output.trim());
+    console.log('  ' + name + ': ' + (hasOutput ? '✅ 有产出' : '⚠️ 已完成但无产出记录'));
+  }
+}
+" 2>/dev/null || echo "⚠️ 无法读取 progress.json"
+\`\`\`
+
+### 4. 孤儿文件检查
+\`\`\`bash
+node -e "
+const fs = require('fs');
+const dir = '.sillyspec/changes';
+if (!fs.existsSync(dir)) { console.log('ℹ️ changes/ 目录不存在'); process.exit(0); }
+const subs = fs.readdirSync(dir).filter(f => fs.statSync(dir+'/'+f).isDirectory());
+if (subs.length === 0) { console.log('ℹ️ 无变更目录'); process.exit(0); }
+let progress;
+try { progress = JSON.parse(fs.readFileSync('.sillyspec/.runtime/progress.json','utf8')); } catch { console.log('⚠️ 无法读取 progress.json'); subs.forEach(s => console.log('❓ ' + s)); process.exit(0); }
+const known = new Set();
+if (progress.currentChange) known.add(progress.currentChange);
+for (const sd of Object.values(progress.stages || {})) {
+  (sd.steps || []).forEach(s => { if (s.output) known.add(s.output); });
+}
+subs.forEach(s => {
+  console.log(known.has(s) ? '✅ ' + s + ' — 已关联' : '⚠️ ' + s + ' — 孤儿目录（可清理）');
+});
+"
+\`\`\`
+
+### 5. 配置文件检查
+\`\`\`bash
+# 检查 local.yaml 和 STACK.md
+for f in .sillyspec/projects/*.yaml; do
+  [ -f "$f" ] || continue
+  name=$(grep '^name:' "$f" | head -1 | sed 's/^name:[[:space:]]*//')
+  p=$(grep '^path:' "$f" | head -1 | sed 's/^path:[[:space:]]*//')
+  [ -z "$p" ] && continue
+  local_yaml="$p/.sillyspec/local.yaml"
+  stack_md="$p/.sillyspec/STACK.md"
+  [ -f "$local_yaml" ] && echo "✅ local.yaml ($name)" || echo "⚠️ local.yaml ($name) — 不存在"
+  if [ -f "$local_yaml" ]; then
+    grep -q 'build:' "$local_yaml" && echo "  ✅ build 命令已配置" || echo "  ⚠️ 缺少 build 命令"
+    grep -q 'test:' "$local_yaml" && echo "  ✅ test 命令已配置" || echo "  ⚠️ 缺少 test 命令"
+  fi
+  [ -f "$stack_md" ] && echo "✅ STACK.md ($name)" || echo "⚠️ STACK.md ($name) — 不存在"
+done
+\`\`\`
+
+### 输出
+汇总所有检查结果，按以下格式：
+\`\`\`
+## SillySpec 内部
+✅/⚠️/❌ 各项状态
+\`\`\`
+
+### 注意
+- 不要编造路径或结果，严格基于命令输出
+- 如果 .sillyspec/ 不存在，直接输出 ❌ 并跳过后续检查`,
+      outputHint: 'SillySpec 内部检查结果',
+      optional: false
+    },
+    {
+      name: '构建环境检查',
+      prompt: `检查项目构建环境。先探测项目使用的构建工具，再逐项检查可用性。
+
+### 1. 探测构建工具
+\`\`\`bash
+# 确定项目路径（使用 progress.json 中的项目或当前目录）
+PROJECT_DIR=$(node -e "
+const fs=require('fs');
+try{const p=JSON.parse(fs.readFileSync('.sillyspec/.runtime/progress.json','utf8'));if(p.project){console.log(p.project);process.exit(0)}}catch{}
+const files=fs.readdirSync('.sillyspec/projects').filter(f=>f.endsWith('.yaml'));
+if(files.length>0){const c=fs.readFileSync('.sillyspec/projects/'+files[0],'utf8');const m=c.match(/^path:\\s*(.+)/m);console.log(m?m[1].trim():'.')}else console.log('.')
+" 2>/dev/null)
+echo "项目目录: $PROJECT_DIR"
+
+# 探测构建工具
+for f in pom.xml build.gradle package.json requirements.txt pyproject.toml go.mod Cargo.toml; do
+  [ -f "$PROJECT_DIR/$f" ] && echo "检测到: $f"
+done
+[ -f "$PROJECT_DIR/.sillyspec/STACK.md" ] && cat "$PROJECT_DIR/.sillyspec/STACK.md" | head -30
+\`\`\`
+
+### 2. 构建工具可用性
+根据上面检测到的工具，运行对应检查（未检测到的跳过）：
+
+**Maven 项目：**
+\`\`\`bash
+timeout 10 mvn -v 2>/dev/null | head -1 && echo "✅ Maven 可用" || echo "❌ Maven 不可用"
+[ -f ~/.m2/settings.xml ] && echo "✅ Maven settings.xml 存在" || echo "⚠️ Maven settings.xml 不存在"
+timeout 10 java -version 2>&1 | head -1
+\`\`\`
+
+**Gradle 项目：**
+\`\`\`bash
+timeout 10 gradle -v 2>/dev/null | head -1 && echo "✅ Gradle 可用" || echo "❌ Gradle 不可用"
+\`\`\`
+
+**Node.js 项目：**
+\`\`\`bash
+timeout 5 node -v 2>/dev/null && echo "✅ Node.js 可用" || echo "❌ Node.js 不可用"
+timeout 5 npm -v 2>/dev/null && echo "✅ npm 可用" || echo "❌ npm 不可用"
+timeout 5 pnpm -v 2>/dev/null && echo "✅ pnpm 可用" || echo "ℹ️ pnpm 未安装"
+# 检查 registry
+npm config get registry 2>/dev/null
+\`\`\`
+
+**Python 项目：**
+\`\`\`bash
+timeout 5 python3 --version 2>/dev/null && echo "✅ Python3 可用" || echo "❌ Python3 不可用"
+timeout 5 pip3 --version 2>/dev/null && echo "✅ pip3 可用" || echo "❌ pip3 不可用"
+\`\`\`
+
+### 3. Maven 私服检查（仅 Maven 项目）
+\`\`\`bash
+# 从 settings.xml 提取仓库地址
+if [ -f ~/.m2/settings.xml ]; then
+  grep -oP 'https?://[^<"]+:[0-9]+' ~/.m2/settings.xml 2>/dev/null | sort -u | while read url; do
+    timeout 5 curl -s -o /dev/null -w "%{http_code}" "$url" 2>/dev/null
+    echo " — $url"
+  done
+fi
+# 从 pom.xml 提取
+if [ -f "$PROJECT_DIR/pom.xml" ]; then
+  grep -oP 'https?://[^<"]+:[0-9]+' "$PROJECT_DIR/pom.xml" 2>/dev/null | sort -u | while read url; do
+    code=$(timeout 5 curl -s -o /dev/null -w "%{http_code}" "$url" 2>/dev/null)
+    [ "$code" = "000" ] && echo "❌ 私服不可达: $url（超时）" || echo "✅ 私服可达 ($code): $url"
+  done
+fi
+\`\`\`
+
+### 4. 运行时环境
+\`\`\`bash
+timeout 5 node -v 2>/dev/null && echo "Node.js: $(node -v)" || echo "❌ Node.js 未安装"
+timeout 5 git --version 2>/dev/null && echo "Git: $(git --version)" || echo "❌ Git 未安装"
+timeout 10 git remote -v 2>/dev/null | head -2
+timeout 5 git ls-remote --heads origin 2>/dev/null >/dev/null && echo "✅ Git remote 可达" || echo "⚠️ Git remote 不可达"
+timeout 5 java -version 2>&1 | head -1
+timeout 5 python3 --version 2>/dev/null
+\`\`\`
+
+### 输出
+汇总所有检查结果：
+\`\`\`
+## 构建环境
+✅/⚠️/❌ 各项状态
+\`\`\`
+
+### 注意
+- 未检测到的构建工具直接跳过，不要报错
+- timeout 超时的命令视为不可用
+- 不编造结果`,
+      outputHint: '构建环境检查结果',
+      optional: false
+    },
+    {
+      name: '外部依赖检查',
+      prompt: `检查外部依赖工具是否可用。
+
+### 1. Context7 MCP
+\`\`\`bash
+# 检查 MCP 配置
+for f in ~/.config/claude/claude_desktop_config.json ~/.cursor/mcp.json ~/.openclaw/mcp.json; do
+  [ -f "$f" ] && echo "MCP 配置文件: $f" && grep -i context7 "$f" 2>/dev/null && echo "✅ Context7 已配置" || true
+done
+# 也检查 sillyspec 自身的 setup
+node -e "
+try{const m=require(require('path').join(require('os').homedir(),'.sillyspec','config.json'));console.log('✅ sillyspec config 存在')}catch{console.log('ℹ️ 无 sillyspec 全局配置')}
+" 2>/dev/null
+\`\`\`
+
+### 2. grep.app
+\`\`\`bash
+timeout 5 curl -s -o /dev/null -w "%{http_code}" https://grep.app 2>/dev/null | grep -q "200" && echo "✅ grep.app 可达" || echo "⚠️ grep.app 不可达"
+\`\`\`
+
+### 3. 其他 AI 工具（可选）
+\`\`\`bash
+# 检查常用 AI/开发工具
+timeout 5 which gh 2>/dev/null && echo "✅ GitHub CLI 可用" || echo "ℹ️ GitHub CLI 未安装"
+timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ Docker 未安装"
+\`\`\`
+
+### 输出
+\`\`\`
+## 外部依赖
+✅/⚠️/❌ 各项状态
+\`\`\`
+
+### 注意
+- 不编造结果
+- 工具未安装用 ℹ️ 标记（非错误），不可达用 ⚠️`,
+      outputHint: '外部依赖检查结果',
+      optional: false
+    },
+    {
+      name: '汇总报告',
+      prompt: `汇总前三步的所有检查结果，生成最终的自检报告。
+
+### 输出格式
+\`\`\`
+🔍 SillySpec Doctor — 项目自检报告
+
+## SillySpec 内部
+✅ .sillyspec/ 目录结构 — 正常
+✅ projects/*.yaml — N 个项目已注册
+⚠️  local.yaml (xxx) — 缺少 test 命令
+❌ progress.json — brainstorm 标记完成但 design.md 不存在
+
+## 构建环境
+✅ Node.js v23.4.0 — 可用
+✅ npm 10.x — 可用
+✅ Java 17.0.2 — 可用
+❌ Maven 私服 (10.0.0.1:8081) — 不可达（超时）
+
+## 外部依赖
+✅ Context7 MCP — 已配置
+⚠️  grep.app — 不可达
+\`\`\`
+
+### 要求
+- 基于前 3 步的实际输出汇总，不要编造
+- 每类问题归入对应分区
+- 全部通过给出 🎉
+- 如果有 ❌ 或 ⚠️，在末尾逐项给出修复建议
+
+### 修复建议模板
+根据问题类型给出具体可操作的修复命令：
+
+**常见问题及修复：**
+- CLI 未安装 → \`npm install -g sillyspec\`
+- 缺少 local.yaml → \`sillyspec init\` 重新生成，或手动创建
+- local.yaml 缺少 build/test → 补充对应命令
+- 缺少 STACK.md → \`sillyspec run scan\` 重新扫描
+- progress.json 不一致 → \`sillyspec run <阶段> --reset\` 重置对应阶段
+- 孤儿目录 → 确认后 \`rm -rf .sillyspec/changes/<目录名>\`
+- Maven 私服不可达 → 检查 VPN、settings.xml 配置、私服状态
+- Git remote 不可达 → 检查网络、SSH key 或凭证
+- 工具未安装 → 给出安装命令（如 \`brew install maven\`）
+
+每条建议格式：
+\`\`\`
+💡 修复：<问题描述>
+   <具体命令或操作>
+\`\`\``,
+      outputHint: '完整自检报告',
+      optional: false
+    }
+  ]
+}

package/src/stages/execute.js

@@ -0,0 +1,287 @@
+import { existsSync, readFileSync } from 'fs'
+import path from 'path'
+
+export const definition = {
+  name: 'execute',
+  title: '波次执行',
+  description: '子代理并行 + 强制 TDD + 两阶段审查',
+  steps: [] // 动态构建，由 buildExecuteSteps() 生成
+}
+
+// 固定前缀步骤定义
+const fixedPrefix = [
+  {
+    name: '状态检查',
+    prompt: `检查当前状态，确认可以执行 execute。
+
+### 操作
+1. 运行 \`sillyspec progress show\`
+2. 确认 currentStage 为 execute
+3. 如果不是 → 检查是否有未完成的 tasks.md
+4. 确认执行范围（$ARGUMENTS 指定 wave/task 或全部）
+
+### 输出
+当前状态 + 执行范围确认`,
+    outputHint: '当前状态 + 执行范围',
+    optional: false
+  },
+  {
+    name: '加载上下文',
+    prompt: `加载计划、设计和代码库上下文。
+
+### 操作
+1. 读取 tasks.md（执行计划）
+2. 读取 design.md（技术方案）
+3. 读取 CONVENTIONS.md、ARCHITECTURE.md
+4. 读取 local.yaml（构建命令）
+5. 加载 CODEBASE-OVERVIEW.md
+
+### 输出
+已加载的上下文摘要`,
+    outputHint: '上下文摘要',
+    optional: false
+  },
+  {
+    name: '确认执行范围',
+    prompt: `解析任务，确认执行范围和确认模式。
+
+### 操作
+1. 从 plan 中解析 Wave 分组和任务列表
+2. 根据任务描述关键词为每个 Task 建议模型：
+   - 架构/复杂推理 → 最强模型
+   - 常规实现 → 中等模型
+   - 简单修改 → 快速模型
+   - 文档/写作 → 写作模型
+3. 用户在 tasks.md 中的 [model:xxx] 标签优先
+4. 询问用户执行确认频率：
+   - 每个 Wave 确认 — 每个 Wave 完成后展示结果
+   - AI 自主判断 — BLOCKED 或计划外变更时才询问
+   - 全自动 — 全部自动执行
+5. 查询知识库：读取 \`.sillyspec/knowledge/INDEX.md\`，根据 Task 关键词匹配
+
+### 输出
+Wave 分组 + 模型分配 + 确认模式 + 知识库匹配结果
+
+### 注意
+- 默认推荐"每个 Wave 确认"`,
+    outputHint: 'Wave 分组 + 模型分配',
+    optional: false
+  }
+]
+
+// 固定后缀步骤定义
+const fixedSuffix = [
+  {
+    name: '知识库审阅',
+    prompt: `检查本轮执行产生的新知识。
+
+### 操作
+1. 检查 \`.sillyspec/knowledge/uncategorized.md\` 中待确认条目
+2. 如有 → 提示用户审阅
+3. 用户确认后改为 [已确认]，可归类到专题文件
+
+### 输出
+新知识条目数量 + 审阅提示（或"无新知识"）`,
+    outputHint: '知识条目数量',
+    optional: true
+  },
+  {
+    name: '完成确认',
+    prompt: `所有任务完成后的收尾。
+
+### 操作
+1. 询问用户下一步：
+   - 验证 → sillyspec run verify
+   - 归档 → /sillyspec:archive
+   - 继续开发
+2. 提示 git add 暂存变更
+
+### 输出
+用户选择 + 下一步命令
+
+### 注意
+- 完成后运行 \`sillyspec run execute --done\` 即可自动推进阶段`,
+    outputHint: '用户选择',
+    optional: false
+  }
+]
+
+/**
+ * 从 plan 文件解析 Wave 分组
+ */
+function parseWavesFromPlan(planContent) {
+  const waves = []
+  const lines = planContent.split('\n')
+  let currentWave = null
+  let currentTask = null
+
+  for (const line of lines) {
+    const waveMatch = line.match(/^#+\s*Wave\s+(\d+)/i)
+    if (waveMatch) {
+      currentWave = { index: parseInt(waveMatch[1]), tasks: [] }
+      currentTask = null
+      waves.push(currentWave)
+      continue
+    }
+
+    if (!currentWave) continue
+
+    const taskMatch = line.match(/^[-*]\s*\[[ x]\]\s*(.+)/)
+    if (taskMatch) {
+      const taskNoMatch = taskMatch[1].match(/\btask-(\d+)\b/i)
+      currentTask = {
+        index: taskNoMatch ? parseInt(taskNoMatch[1], 10) : null,
+        name: taskMatch[1].trim(),
+        file: '',
+        steps: '',
+        reference: ''
+      }
+      // 兼容旧格式：任务名后跟 (文件路径)
+      const fileMatch = taskMatch[1].match(/\(([^)]+)\)$/)
+      if (fileMatch) {
+        currentTask.file = fileMatch[1]
+        currentTask.name = taskMatch[1].replace(/\([^)]+\)$/, '').trim()
+      }
+      currentWave.tasks.push(currentTask)
+      continue
+    }
+
+    // 解析子行信息（修改/参考/步骤）
+    if (currentTask) {
+      const modMatch = line.match(/^\s+-\s*修改:\s*(.+)/)
+      if (modMatch) { currentTask.file = modMatch[1].trim(); continue }
+
+      const refMatch = line.match(/^\s+-\s*参考:\s*(.+)/)
+      if (refMatch) { currentTask.reference = refMatch[1].trim(); continue }
+
+      const stepMatch = line.match(/^\s+-\s*步骤:/)
+      if (stepMatch) { currentTask.steps = line.replace(/^\s+-\s*步骤:\s*/, '').trim(); continue }
+
+      // 步骤续行（数字开头的子步骤）
+      if (currentTask.steps && line.match(/^\s+\d+\./)) {
+        currentTask.steps += '\n' + line.trim()
+      }
+    }
+  }
+
+  return waves
+}
+
+/**
+ * 为 Wave 生成 prompt（强制子代理执行）
+ */
+function buildWavePrompt(wave, waveIndex, changeDir) {
+  // 构建子代理 prompt 模板（每个任务的蓝图内容）
+  const subagentTemplates = wave.tasks.map((t, ti) => {
+    const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
+    const taskFile = changeDir ? `${changeDir}/tasks/task-${taskNum}.md` : ''
+    const taskFileExists = taskFile && existsSync(taskFile)
+    let taskContent = ''
+    if (taskFileExists) {
+      try { taskContent = readFileSync(taskFile, 'utf8').trim() } catch { taskContent = '（无法读取任务蓝图文件）' }
+    }
+    const fileInfo = t.file ? ` (${t.file})` : ''
+    return `\`\`\`
+任务：${t.name}${fileInfo}
+${taskContent ? `蓝图内容：\n${taskContent}` : '（无蓝图文件，按任务描述执行）'}
+
+操作：
+1. 先读后写 — 读取要修改的文件，理解现有结构
+2. 按 TDD 步骤实现
+3. 运行对应测试确认通过
+4. 报告改动文件和测试结果
+
+铁律：
+- 只做蓝图/任务描述里写的事，不增不减
+- 蓝图有问题 → 报告问题，不要自己改
+- 先写测试，再写代码
+- grep 确认方法存在，不要编造
+\`\`\``
+  }).join('\n\n')
+
+  const taskList = wave.tasks.map((t, ti) => {
+    const taskNum = String(t.index || (ti + 1)).padStart(2, '0')
+    let s = `- [ ] ${t.name}`
+    if (t.file) s += ` (${t.file})`
+    return s
+  }).join('\n')
+
+  return `## Wave ${waveIndex}: 执行以下任务
+
+## 执行方式（必须严格遵守）
+
+**每个任务必须由独立子代理执行，你不要自己写代码。**
+
+你的角色是调度者 + 审查者：
+1. 为每个任务启动一个子代理（Agent tool），同 Wave 内可并行
+2. 子代理完成后审查结果
+3. 勾选 plan.md 中的 checkbox
+4. 记录改动文件和测试结果
+
+### 子代理 prompt 模板
+为每个任务使用以下 prompt 启动子代理：
+
+${subagentTemplates}
+
+### Wave 开始前
+1. 读取 design.md 的「编码铁律」章节（如果存在），严格遵守
+2. 读取 plan.md 了解全局任务划分和依赖关系
+3. 确认本 Wave 的输入/输出契约（前置 Wave 产出了什么，本 Wave 需要消费什么）
+4. 检查前置 Wave 的产出是否完整（文件是否存在、测试是否通过）
+5. **上下文分层加载**：
+   - 🔥 热上下文：design.md 编码铁律 + 当前 Wave 任务（必须加载）
+   - 🌡️ 温上下文：CONVENTIONS.md + ARCHITECTURE.md（需要时加载）
+   - ❄️ 冷上下文：其他变更的 design.md、历史 plan.md（不要主动加载，除非明确需要）
+
+### 本 Wave 任务
+${taskList}
+
+### 调度要求
+1. 同一 Wave 内任务可并行启动子代理
+2. **Reverse Sync**：子代理报告实现与 design.md 不一致时，先检查是代码错了还是文档有遗漏
+3. **不要频繁编译！** 编译很慢，只在以下情况运行：
+   - 写了大量代码后需要验证语法正确性
+   - 最后一个 Wave 完成后做一次全量编译验证
+   - 用户明确要求编译时
+4. 每个任务完成后：
+   - 勾选 plan.md / tasks.md 中对应任务的 checkbox
+   - 记录改动文件和测试结果
+5. 遇到 BLOCKED → 记录原因，选择：重试/跳过/停止
+
+### 完成后
+运行 sillyspec run execute --done --input "用户原始反馈" --output "Wave ${waveIndex} 结果摘要"`
+}
+
+/**
+ * 动态构建 execute 步骤列表
+ * @param {string|null} planFilePath - plan 文件路径，null 则用默认 3 Wave
+ * @returns {Array} 步骤列表
+ */
+export function buildExecuteSteps(planFilePath = null) {
+  let waves
+  let changeDir = null
+
+  if (planFilePath && existsSync(planFilePath)) {
+    const planContent = readFileSync(planFilePath, 'utf8')
+    waves = parseWavesFromPlan(planContent)
+    // 从 planFilePath 推导 changeDir: .sillyspec/changes/<name>/plan.md
+    changeDir = path.dirname(planFilePath)
+  }
+
+  // 如果没解析出 Wave，生成默认 3 个
+  if (!waves || waves.length === 0) {
+    waves = []
+    for (let i = 1; i <= 3; i++) {
+      waves.push({ index: i, tasks: [{ name: `默认任务 ${i}`, file: 'TBD' }] })
+    }
+  }
+
+  const waveSteps = waves.map((wave, i) => ({
+    name: `Wave ${i + 1} 执行`,
+    prompt: buildWavePrompt(wave, i + 1, changeDir),
+    outputHint: `Wave ${i + 1} 执行结果`,
+    optional: false
+  }))
+
+  return [...fixedPrefix, ...waveSteps, ...fixedSuffix]
+}

package/src/stages/explore.js

@@ -0,0 +1,34 @@
+export const definition = {
+  name: 'explore',
+  title: '自由探索',
+  description: '讨论、调研、画图，不写实现代码',
+  auxiliary: true,
+  steps: [
+    {
+      name: '自由探索',
+      prompt: `围绕用户给出的话题做技术探索，不进入实现。
+
+### 操作
+1. 明确探索边界：这次只讨论、调研、画图和识别风险
+2. 如果需要代码库上下文，可以读取：
+   - \`.sillyspec/projects/*.yaml\`
+   - \`.sillyspec/docs/<project>/scan/ARCHITECTURE.md\`
+   - \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\`
+   - \`.sillyspec/changes/<change-name>/design.md\`
+3. 可以用 \`rg\` / \`ls\` / \`cat\` 调查已有结构和集成点
+4. 输出 2-3 个有价值方向、关键风险和下一步建议
+5. 如果用户要求保存结论，先明确保存位置，再写入对应文档
+
+### 输出
+探索结论、选项对比、风险清单或 ASCII 图
+
+### 铁律
+- 不写实现代码
+- 不安装依赖
+- 不修改文件，除非用户明确要求保存探索结论
+- 不强行推进到 brainstorm/plan/execute`,
+      outputHint: '探索结论',
+      optional: false
+    }
+  ]
+}

package/src/stages/index.js

@@ -0,0 +1,28 @@
+import { definition as brainstorm } from './brainstorm.js'
+import { definition as propose } from './propose.js'
+import { definition as plan } from './plan.js'
+import { definition as execute } from './execute.js'
+import { definition as verify } from './verify.js'
+import { definition as scan } from './scan.js'
+import { definition as quick } from './quick.js'
+import { definition as explore } from './explore.js'
+import { definition as archive } from './archive.js'
+import { definition as status } from './status.js'
+import { definition as doctor } from './doctor.js'
+
+export const stageRegistry = {
+  brainstorm,
+  propose,
+  plan,
+  execute,
+  verify,
+  scan,
+  quick,
+  explore,
+  archive,
+  status,
+  doctor
+}
+
+// 辅助命令（在没有 progress.json 时也可执行）
+export const auxiliaryStages = ['scan', 'quick', 'explore', 'archive', 'status', 'doctor']