sillyspec 3.13.0 → 3.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",
@@ -27,6 +27,7 @@
     "@inquirer/prompts": "^7.10.1",
     "chalk": "^5.6.2",
     "chokidar": "^4.0",
+    "js-yaml": "^4.2.0",
     "open": "^10.1",
     "ora": "^9.3.0",
     "sql.js": "^1.14.1",

package/src/index.js

@@ -94,6 +94,7 @@ async function main() {
 
   // 解析全局选项
   let json = false;
+  let saveWorkflowRunFlag = false;
   let targetDir = process.cwd();
   let tool = null;
   let interactive = false;
@@ -102,6 +103,8 @@ async function main() {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--json') {
       json = true;
+    } else if (args[i] === '--save') {
+      saveWorkflowRunFlag = true;
     } else if (args[i] === '--dir' && args[i + 1]) {
       targetDir = resolve(args[i + 1]);
       i++;
@@ -485,6 +488,137 @@ SillySpec platform — SillyHub 平台同步
       await pm.renameChange(dir, oldName, newName);
       break;
     }
+    case 'workflow': {
+      const wfSub = filteredArgs[1];
+      if (!wfSub || wfSub === 'help' || wfSub === '--help') {
+        console.log(`
+SillySpec workflow — 工作流管理
+
+用法:
+  sillyspec workflow check <name> [--project <project>] [--json]
+  sillyspec workflow list
+`);
+        break;
+      }
+      if (wfSub === 'list') {
+        const { listWorkflows } = await import('./workflow.js');
+        const names = listWorkflows(dir);
+        if (names.length === 0) {
+          console.log('未找到 workflow 定义（.sillyspec/workflows/*.yaml）');
+        } else {
+          console.log(`可用 workflow：`);
+          for (const name of names) {
+            const { loadWorkflow } = await import('./workflow.js');
+            const wf = loadWorkflow(dir, name);
+            const specVer = wf?.spec_version || wf?.version || '?';
+            const mode = wf?.orchestration?.mode || '?';
+            const roles = wf?.roles?.length || 0;
+            console.log(`  ${name} (spec v${specVer}, ${mode}, ${roles} roles)`);
+          }
+        }
+        break;
+      }
+      if (wfSub === 'check') {
+        const { loadWorkflow, runPostCheck, listWorkflows, saveWorkflowRun } = await import('./workflow.js');
+        const wfName = filteredArgs[2];
+        if (!wfName) {
+          console.error('❌ 请指定 workflow 名称，例如：sillyspec workflow check scan-docs --project sillyspec');
+          process.exit(2);
+        }
+        const wf = loadWorkflow(dir, wfName);
+        if (!wf) {
+          console.error(`❌ 未找到 workflow: ${wfName}`);
+          console.error(`可用 workflow：${listWorkflows(dir).join(', ') || '无'}`);
+          process.exit(2);
+        }
+        // depends_on 校验
+        if (wf._validationErrors && wf._validationErrors.length > 0) {
+          console.error('❌ workflow YAML 校验失败：');
+          for (const err of wf._validationErrors) {
+            console.error(`   ${err}`);
+          }
+          process.exit(2);
+        }
+        // spec_version 校验
+        const specVer = wf.spec_version || wf.version;
+        if (!specVer) {
+          console.error('❌ workflow YAML 缺少 spec_version 字段');
+          process.exit(2);
+        }
+        const SUPPORTED_SPECS = [1];
+        if (!SUPPORTED_SPECS.includes(specVer)) {
+          console.error(`❌ 不支持的 spec_version: ${specVer}（支持: ${SUPPORTED_SPECS.join(', ')}）`);
+          process.exit(2);
+        }
+        // 解析 --project
+        const projectIdx = filteredArgs.indexOf('--project');
+        const project = projectIdx !== -1 && filteredArgs[projectIdx + 1] ? filteredArgs[projectIdx + 1] : null;
+        // 解析 --json（已在顶层解析）
+        const isJson = json;
+        // 解析 --change
+        const changeIdx = filteredArgs.indexOf('--change');
+        const changeName = changeIdx !== -1 && filteredArgs[changeIdx + 1] ? filteredArgs[changeIdx + 1] : null;
+
+        if (!project && wfName !== 'archive-impact') {
+          console.error('❌ 请指定 --project，例如：--project sillyspec');
+          process.exit(2);
+        }
+
+        // 执行检查
+        let resolvedWf = wf;
+        const placeholders = {};
+        if (changeName) placeholders['change-name'] = changeName;
+        // 替换占位符
+        let jsonStr = JSON.stringify(resolvedWf);
+        if (changeName) jsonStr = jsonStr.replace(/<change-name>/g, changeName);
+        resolvedWf = JSON.parse(jsonStr);
+
+        const projectName = project || 'sillyspec';
+        const result = runPostCheck(resolvedWf, dir, projectName, placeholders);
+
+        if (isJson) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          // 带项目维度前缀的输出（从统一结果对象格式化）
+          const lines = [`\n📋 Workflow Post-Check: ${result.workflow} (project: ${result.project})\n`];
+          for (const r of (result.roles || [])) {
+            const icon = r.status === 'pass' ? '✅' : '❌';
+            lines.push(`${icon} [${result.project}] ${r.name} (${r.id})`);
+            const roleFailures = (result.failures || []).filter(f => f.role_id === r.id);
+            for (const f of roleFailures) {
+              lines.push(`   └─ ${f.message}`);
+            }
+          }
+          const wfFailures = (result.workflow_checks || []).filter(c => c.status === 'fail');
+          if (wfFailures.length > 0) {
+            lines.push('');
+            for (const f of wfFailures) {
+              lines.push(`❌ [${result.project}] 全局: ${f.detail}`);
+            }
+          }
+          lines.push('');
+          if (result.status === 'pass') {
+            lines.push('✅ 全部检查通过');
+          } else {
+            lines.push('❌ 存在失败项');
+          }
+          console.log(lines.join('\n'));
+        }
+
+        // exit code: 0=通过, 1=检查失败, 2=参数/YAML错误
+        if (saveWorkflowRunFlag) {
+          const saved = saveWorkflowRun(result, { cwd: dir, source: 'cli' });
+          if (saved) {
+            if (!isJson) console.log(`\n📁 结果已归档：${saved}`);
+          }
+        }
+        process.exit(result.status === 'pass' ? 0 : 1);
+      } else {
+        console.error(`❌ 未知子命令: workflow ${wfSub}`);
+        process.exit(1);
+      }
+      break;
+    }
     case 'modules': {
       const modulesSub = filteredArgs[1];
       if (!modulesSub || modulesSub === 'help' || modulesSub === '--help') {

package/src/run.js

@@ -584,6 +584,88 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     }
   }
 
+  // scan 阶段 step 2 "构建扫描项目列表" 完成后，按项目展开 perProject 步骤
+  if (stageName === 'scan' && steps[currentIdx]?.name === '构建扫描项目列表') {
+    // 解析项目列表：从 step 2 输出提取，或回退读取 projects/*.yaml
+    let projectNames = []
+    if (outputText) {
+      // 匹配 "1. project-name" 格式
+      const matches = outputText.match(/^\s*\d+\.\s+(\S+)/gm)
+      if (matches) {
+        projectNames = matches.map(m => m.replace(/^\s*\d+\.\s+/, '').replace(/[—\-:].*$/, '').trim())
+      }
+    }
+    if (projectNames.length === 0) {
+      // 回退：读取所有已注册项目
+      console.warn('⚠️ 未能从 step 2 输出解析项目列表，回退扫描所有注册项目')
+      const projectsDir = join(cwd, '.sillyspec', 'projects')
+      if (existsSync(projectsDir)) {
+        projectNames = readdirSync(projectsDir)
+          .filter(f => f.endsWith('.yaml'))
+          .map(f => f.replace(/\.yaml$/, ''))
+      }
+    }
+    if (projectNames.length === 0) {
+      projectNames = ['sillyspec'] // 最终兜底
+    }
+
+    // 保存到 runtime 供后续使用 + 防重复展开
+    const scanStatePath = join(cwd, '.sillyspec', '.runtime', 'scan-projects.json')
+    mkdirSync(join(cwd, '.sillyspec', '.runtime'), { recursive: true })
+    let scanState = { projects: projectNames, expanded: false }
+    if (existsSync(scanStatePath)) {
+      try { scanState = JSON.parse(readFileSync(scanStatePath, 'utf8')) } catch {}
+    }
+
+    // 收集当前步骤之后所有 perProject 步骤
+    const stageDef = stageRegistry[stageName]
+    const allSteps = stageDef?.steps || []
+    const perProjectSteps = allSteps.filter(s => s.perProject)
+
+    // 防重复展开：runtime 标记 或 steps 已含项目标识
+    const alreadyExpanded = scanState.expanded || steps.some(s => s.name?.match(/\[.+\]\s*$/))
+    if (!alreadyExpanded && perProjectSteps.length > 0) {
+      // 找到当前步骤（step 2）在动态 steps 中的位置
+      const insertBase = currentIdx + 1
+      let insertPos = insertBase
+      for (const pName of projectNames) {
+        // 读取项目配置获取 projectRoot
+        const projYaml = join(cwd, '.sillyspec', 'projects', `${pName}.yaml`)
+        let projectRoot = '.'
+        if (existsSync(projYaml)) {
+          const yamlContent = readFileSync(projYaml, 'utf8')
+          const pathMatch = yamlContent.match(/^path:\s*(.+)/m)
+          if (pathMatch) projectRoot = pathMatch[1].trim()
+        }
+        const docOutputDir = `.sillyspec/docs/${pName}`
+        const contextPrefix = `\n---\n## 当前项目\n- **项目名**: ${pName}\n- **项目路径**: ${projectRoot}\n- **文档输出**: ${docOutputDir}\n\n⚠️ 本步骤只处理上面这个项目，不要处理其他项目。\n---\n\n`
+
+        for (const ppStep of perProjectSteps) {
+          steps.splice(insertPos, 0, {
+            name: `${ppStep.name} [${pName}]`,
+            project: pName,
+            status: 'pending',
+            prompt: contextPrefix + ppStep.prompt,
+            outputHint: ppStep.outputHint,
+            optional: ppStep.optional
+          })
+          insertPos++
+        }
+      }
+      // 移除原始的 perProject 步骤（未展开的版本）
+      for (let i = steps.length - 1; i >= 0; i--) {
+        if (steps[i].perProject && !steps[i].name?.includes('[')) {
+          steps.splice(i, 1)
+        }
+      }
+      console.log(`  📝 已按项目展开 ${perProjectSteps.length} 个步骤 × ${projectNames.length} 个项目 = ${perProjectSteps.length * projectNames.length} 个项目步骤`)
+      console.log(`  📁 扫描项目：${projectNames.join(', ')}`)
+      // 标记已展开，防止 resume 重复插入
+      scanState.expanded = true
+      writeFileSync(scanStatePath, JSON.stringify(scanState))
+    }
+  }
+
   const nextPendingIdx = steps.findIndex(s => s.status === 'pending')
 
   if (nextPendingIdx === -1) {
@@ -687,6 +769,83 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
 
   const defSteps = await getStageSteps(stageName, cwd, progress)
   console.log(`✅ Step ${currentIdx + 1}/${steps.length} 完成：${steps[currentIdx].name}\n`)
+
+  // Workflow post_check：scan 深度扫描完成后自动检查产物
+  if (stageName === 'scan' && steps[currentIdx]?.name?.includes('深度扫描')) {
+    try {
+      const { loadWorkflow, runPostCheck, formatCheckReport, saveWorkflowRun } = await import('./workflow.js')
+      const wf = loadWorkflow(cwd, 'scan-docs')
+      if (wf) {
+        // 确定当前项目：优先从 step metadata 读取，回退从 display name 提取
+        const currentProjectName = steps[currentIdx].project
+          || (steps[currentIdx].name.match(/\[([^\]]+)\]\s*$/) || [])[1]
+          || null
+
+        // 确定要检查的项目列表
+        let projectsToCheck = []
+        if (currentProjectName) {
+          // 按项目展开模式：只检查当前项目
+          projectsToCheck = [currentProjectName]
+        } else {
+          // 兼容旧模式（未展开）：检查所有项目
+          const projectsDir = join(cwd, '.sillyspec', 'projects')
+          const projectFiles = existsSync(projectsDir)
+            ? readdirSync(projectsDir).filter(f => f.endsWith('.yaml'))
+            : []
+          projectsToCheck = projectFiles.map(f => f.replace(/\.yaml$/, ''))
+        }
+
+        let anyFailed = false
+        for (const pName of projectsToCheck) {
+          const result = runPostCheck(wf, cwd, pName)
+          const report = formatCheckReport(result)
+          console.log(report)
+          if (result.status === 'fail') {
+            anyFailed = true
+            // retry_prompts 由 _checkWorkflow 自动生成
+            for (const rp of (result.retry_prompts || [])) {
+              console.log(`\n🔄 重试提示（项目 ${pName}）：\n`)
+              console.log(rp.prompt)
+            }
+          }
+          const saved = saveWorkflowRun(result, { cwd, source: 'run.js', stage: 'verify', step: steps[currentIdx]?.name })
+          if (saved) console.log(`📁 结果已归档：${saved}`)
+        }
+        if (anyFailed) {
+          console.log(`\n⚠️ 存在检查失败项，请按上面的重试提示修复后再继续。`)
+        }
+      }
+    } catch (e) {
+      console.warn(`⚠️ workflow 检查跳过：${e.message}`)
+    }
+  }
+
+  // Workflow post_check：archive extract-module-impact 完成后检查产物
+  if (stageName === 'archive' && steps[currentIdx]?.name?.includes('extract-module-impact')) {
+    try {
+      const { loadWorkflow, runPostCheck, formatCheckReport, saveWorkflowRun } = await import('./workflow.js')
+      const wf = loadWorkflow(cwd, 'archive-impact')
+      if (wf && changeName) {
+        const raw = JSON.stringify(wf)
+        const resolved = JSON.parse(raw.replace(/<change-name>/g, changeName))
+        const result = runPostCheck(resolved, cwd, 'sillyspec')
+        // 只报告 impact-analyzer 的结果（doc-syncer 是后续步骤）
+        const impactResult = (result.roles || []).find(r => r.id === 'impact-analyzer')
+        if (impactResult) {
+          const icon = impactResult.status === 'pass' ? '✅' : '❌'
+          console.log(`${icon} module-impact.md 检查${impactResult.status === 'pass' ? '通过' : '失败'}`)
+          for (const f of (result.failures || []).filter(f => f.role_id === 'impact-analyzer')) {
+            console.log(`   └─ ${f}`)
+          }
+        }
+        const saved = saveWorkflowRun(result, { cwd, source: 'run.js', stage: 'archive', step: steps[currentIdx]?.name })
+        if (saved) console.log(`📁 结果已归档：${saved}`)
+      }
+    } catch (e) {
+      console.warn(`⚠️ workflow 检查跳过：${e.message}`)
+    }
+  }
+
   if (printNext) {
     await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null)
   }

package/src/stages/archive.js

@@ -20,20 +20,21 @@ export const definition = {
     },
     {
       name: 'extract-module-impact',
-      prompt: `分析本次变更影响的模块，生成模块影响记录。
+      prompt: `按照 \`.sillyspec/workflows/archive-impact.yaml\` 中定义的 \`impact-analyzer\` 角色规则，分析本次变更影响的模块。
 
 ### 操作
-1. 读取变更目录下的 proposal.md、design.md、tasks.md
-2. 运行 \`git diff --name-only HEAD~1\`（或 \`git diff --name-only --cached\`）获取真实修改文件列表
-3. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`
+1. 读取 \`.sillyspec/workflows/archive-impact.yaml\`，了解角色定义和检查规则
+2. 读取变更目录下的 proposal.md、design.md、tasks.md
+3. 运行 \`git diff --name-only HEAD~1\`（或 \`git diff --name-only --cached\`）获取真实修改文件列表
+4. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`
    - **如果不存在**：提示"建议运行 scan 生成模块映射"，但继续执行。跳到步骤 7 生成只有 unmapped 部分的 module-impact.md
-4. 三重交叉验证：
+5. 三重交叉验证：
    - 声明范围：proposal.md / design.md 中的"变更范围"/"文件变更清单"
    - 任务范围：tasks.md / plan.md 中的任务文件路径
    - 真实变更：git diff 文件列表
    - **以 git diff 为准**（真实 > 声明）
-5. 将 git diff 文件按 \`_module-map.yaml\` 的 paths glob 匹配到模块
-6. 生成模块影响矩阵：
+6. 将 git diff 文件按 \`_module-map.yaml\` 的 paths glob 匹配到模块
+7. 生成模块影响矩阵：
 
 | 模块 | 影响类型 | 相关文件 | 更新内容摘要 | needs_review |
 |------|----------|----------|-------------|-------------|
@@ -41,33 +42,10 @@ export const definition = {
    影响类型：逻辑变更 / 数据结构变更 / 接口变更 / 调用关系变更 / 配置变更 / 新增
    needs_review：如果影响无法完全确定，标记为 true
 
-7. 未匹配到任何模块的文件归入"未匹配文件"表格
-8. 生成 \`.sillyspec/changes/<change-name>/module-impact.md\`，格式：
-
-\`\`\`markdown
-# 模块影响分析
-
-author: <git-user>
-created_at: <now-datetime>
-
-## 变更：<change-name>
-
-## 模块影响矩阵
-| 模块 | 影响类型 | 相关文件 | 更新内容摘要 | needs_review |
-|------|----------|----------|-------------|-------------|
-
-## 未匹配文件
-| 文件路径 | 说明 |
-|----------|------|
-
-## 更新结果
-（sync-module-docs 步骤完成后回填）
-| 目标 | 操作 | 状态 |
-|------|------|------|
-\`\`\`
-
-### 输出
-module-impact.md 路径 + 影响模块数量 + 未匹配文件数量`,
+8. 未匹配到任何模块的文件归入"未匹配文件"表格
+9. 生成 \`.sillyspec/changes/<change-name>/module-impact.md\`
+10. 完成后运行 workflow 检查：
+    \`node -e "import('./src/workflow.js').then(w => { /* 用 loadWorkflow 加载 archive-impact，用 runPostCheck 检查 */ })\``,
       outputHint: 'module-impact.md 路径 + 影响摘要',
       optional: false
     },

package/src/stages/scan.js

@@ -37,117 +37,104 @@ export const definition = {
       optional: false
     },
     {
-      name: '检查已有扫描文档和子项目列表',
-      prompt: `检查已有扫描文档和子项目列表。
+      name: '构建扫描项目列表',
+      prompt: `确定本次要扫描的项目列表。
 
 ### 操作
-1. \`ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .\` — 检查已有文档
-1. \`ls .sillyspec/docs/*/scan/ 2>/dev/null\` — 检查已有文档
-2. \`wc -l .sillyspec/docs/*/scan/*.md 2>/dev/null\` — 文档行数
-3. 显示子项目列表供选择扫描范围
-
-### ⛔ 重要：已有文档时的处理
-如果发现已有 scan 文档（如 7 份齐全），**必须停下来问用户**：
-- 列出已有文档状态（哪些存在、哪些缺失）
-- 明确提供两个选项：**重新扫描（全部覆盖）** 或 **只补扫描缺失的文档**
+1. \`ls .sillyspec/projects/*.yaml 2>/dev/null\` — 列出所有已注册项目
+2. 对每个项目，检查已有的 scan 文档状态：\`ls .sillyspec/docs/<project>/scan/*.md 2>/dev/null\`
+3. 按以下格式展示：
+
+\`\`\`
+扫描项目列表：
+1. sillyspec（主项目）— scan 文档：0/7 已存在
+2. dashboard（子项目）— scan 文档：0/7 已存在
+\`\`\`
+
+4. **必须停下来问用户**：
+   - 选择要扫描的项目（默认全部）
+   - 每个项目的扫描策略：**重新扫描（全部覆盖）** / **只补扫描缺失的文档** / **跳过**
+
+### ⛔ 重要
 - **不要自行决定跳过**，等用户选择后再继续
+- 最终确定的项目列表将用于后续所有步骤
+- **后续每个需要生成文档的步骤，都必须对列表中的每个项目分别执行**
 
 ### 输出
-已有文档状态 + 等待用户选择`,
-      outputHint: '工作区和文档状态',
+确认后的扫描项目列表（项目名 + 扫描策略）`,
+      outputHint: '扫描项目列表',
       optional: false
     },
     {
       name: '构建环境探测',
-      prompt: `探测项目的构建环境和依赖。
+      perProject: true,
+      prompt: `探测当前项目的构建环境和依赖。
 
 ### 操作
-1. \`cat package.json pom.xml build.gradle go.mod Cargo.toml requirements.txt pyproject.toml Gemfile composer.json 2>/dev/null\`
-2. \`find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null\`
-3. 结果保存到 \`.sillyspec/docs/<project>/scan/_env-detect.md\`（临时文件，扫描完删除）
+对扫描列表中的每个项目重复以下操作：
+1. 进入项目目录（子项目用其 path，如 \`packages/dashboard/\`）
+2. \`cat package.json pom.xml build.gradle go.mod Cargo.toml requirements.txt pyproject.toml Gemfile composer.json 2>/dev/null\`
+3. \`find <project-dir> -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null\`
+4. 结果保存到 \`.sillyspec/docs/<project>/scan/_env-detect.md\`（临时文件，扫描完删除）
 
 ### 输出
-环境探测结果摘要`,
+每个项目的环境探测结果摘要`,
       outputHint: '环境探测摘要',
       optional: false
     },
     {
       name: '断点续扫检测',
-      prompt: `检测已有扫描文档，只生成缺失的。
+      perProject: true,
+      prompt: `检测当前项目已有扫描文档，列出缺失的。
 
 ### 操作
-1. \`PROJECT=$(sqlite3 -json '.sillyspec/.runtime/sillyspec.db' "SELECT name FROM project WHERE id=1" 2>/dev/null | node -e "const r=JSON.parse(require('fs').readFileSync(0,'utf8'));console.log(r.length>0?r[0].name:'')" 2>/dev/null || basename "$(pwd)")\`
-2. 检查 7 份文档是否存在：ARCHITECTURE、STRUCTURE、CONVENTIONS、INTEGRATIONS、TESTING、CONCERNS、PROJECT
-3. 列出已有 ✅ 和缺失 ⬜
-4. 只生成缺失的文档
+对扫描列表中的每个项目分别执行：
+1. 检查 7 份文档是否存在：ARCHITECTURE、STRUCTURE、CONVENTIONS、INTEGRATIONS、TESTING、CONCERNS、PROJECT
+   路径：\`.sillyspec/docs/<project>/scan/<DOC>.md\`
+2. 列出已有 ✅ 和缺失 ⬜
 
 ### 输出
-已有/缺失文档列表`,
+每个项目的已有/缺失文档列表`,
       outputHint: '断点续扫状态',
       optional: false
     },
     {
       name: '深度扫描 — 7 份文档（子代理并行）',
-      prompt: `使用子代理并行生成 7 份扫描文档。**你必须使用子代理执行，不要自己写文档。**
-
-### 执行方式
-1. 为每个扫描任务启动独立子代理（可并行），每个子代理负责 1-2 份文档
-2. 子代理直接用 grep/rg 搜索源码并写入文件，结果不回传到你的上下文
-3. 等待所有子代理完成后，验证文件是否生成且非空
-
-### 子代理任务分配
-
-**子代理 A — 技术架构**
-目标文件：\`.sillyspec/docs/<project>/scan/ARCHITECTURE.md\`
-搜索范围：技术栈 + 数据库 Schema + 架构模式
-- 用 grep/rg 搜索（\`@Entity\`、\`schema.prisma\`、\`models.py\` 等），**禁止读源码全文**
-- Schema 只记表名+说明+字段数
-- 包含 \`## 技术栈\` \`## 架构概览\` \`## 数据模型（摘要）\`
-- 参考 _env-detect.md（如存在）
-
-**子代理 B — 代码约定**
-目标文件：\`.sillyspec/docs/<project>/scan/CONVENTIONS.md\`
-搜索范围：框架隐形规则 + 实体继承 + 代码风格
-- 用 grep 搜索拦截器/插件/逻辑删除/基类/审计字段，**禁止读源码全文**
-- 根据检测到的语言/框架自行决定搜索什么模式
-- 提取 3-5 个典型示例
-- 包含 \`## 框架隐形规则\` \`## 实体继承规范\` \`## 代码风格\`
-- 参考 _env-detect.md（如存在）
-
-**子代理 C — 目录结构 + 外部集成**
-目标文件：\`.sillyspec/docs/<project>/scan/STRUCTURE.md\` + \`.sillyspec/docs/<project>/scan/INTEGRATIONS.md\`
-搜索范围：目录树 + 模块说明 + 外部集成
-- 用 find/ls/tree 和 grep，**禁止读源码全文**
-- 搜索 API 调用、MQ 配置、缓存、第三方 SDK
-- STRUCTURE.md：目录树+模块说明
-- INTEGRATIONS.md：外部集成（按类型分组）
-- 参考 _env-detect.md（如存在）
-
-**子代理 D — 测试 + 债务 + 项目概览**
-目标文件：\`.sillyspec/docs/<project>/scan/TESTING.md\` + \`.sillyspec/docs/<project>/scan/CONCERNS.md\` + \`.sillyspec/docs/<project>/scan/PROJECT.md\`
-搜索范围：测试文件 + TODO/FIXME + 过时依赖 + 项目信息
-- 用 grep 搜索测试文件、TODO/FIXME、过时依赖，**禁止读源码全文**
-- TESTING.md：测试结构
-- CONCERNS.md：技术债务（按严重程度分组）
-- PROJECT.md：项目概览
-- 参考 _env-detect.md（如存在）
-
-### 每个子代理的共同要求
-- **上下文注入**：主 agent 在启动子代理前，必须将以下信息拼入子代理 prompt：
-  - 项目名（直接用本次 prompt 中的实际项目名）
-  - 断点续扫步骤列出的缺失文档列表（哪些要生成、哪些跳过）
-  - 环境探测结果摘要（构建工具、语言框架、关键依赖）
-  - _env-detect.md 内容（如存在，直接贴入）
-- 路径用反引号，不编造
-- 目标文件不存在则创建，已存在则覆盖
-- 只生成缺失文档（根据断点续扫结果）
+      perProject: true,
+      prompt: `按照 \`.sillyspec/workflows/scan-docs.yaml\` 中定义的角色和检查规则，使用子代理并行生成当前项目的 7 份扫描文档。
+
+**你必须使用子代理执行，不要自己写文档。**
+**对扫描列表中的每个项目分别执行以下流程。**
+
+### 操作
+1. 读取 \`.sillyspec/workflows/scan-docs.yaml\`，了解角色定义、输出要求和检查规则
+2. 对每个项目（扫描列表中标记为需生成/覆盖的项目）：
+   a. 将 \`<project>\` 替换为实际项目名，得到该项目的目标文件路径
+   b. 为每个角色启动独立子代理（可并行），每个子代理负责 1-2 份文档
+   c. 子代理的搜索范围限定在该项目目录内（子项目如 \`packages/dashboard/\`，不要搜索主项目源码）
+   d. 子代理直接用 grep/rg 搜索源码并写入文件，结果不回传到你的上下文
+   e. 等待该项目所有子代理完成后，验证文件是否生成且非空
+   f. 该项目完成后，继续下一个项目
+3. 所有项目完成后，运行以下命令检查产物：
+   \`node -e "import('./src/workflow.js').then(w => { const r = w.runPostCheck(w.loadWorkflow('.', 'scan-docs'), '.', '<project>'); console.log(w.formatCheckReport(r)) })\`
+   对每个项目分别执行（将 \`<project>\` 替换为实际项目名）
+4. 如果检查报告有失败项，按报告中的角色和文件重试失败的部分
+
+### 子代理上下文注入
+启动每个子代理前，将以下信息拼入子代理 prompt：
+- 项目名（直接用实际项目名）
+- 目标文件路径（从 workflow YAML 中 \`<project>\` 替换后的路径）
+- 检查要求（从 workflow YAML 中该角色的 checks）
+- 断点续扫步骤列出的缺失文档列表
+- 环境探测结果摘要（如有 _env-detect.md，直接贴入）
+- **⚠️ 必须强调：子代理必须用 write 工具将文件写入磁盘**
 
 ### 完成后
-验证 7 份文档全部生成且非空，列出结果：
+列出每个项目的 7 份文档状态：
 - ✅ ARCHITECTURE.md / ❌ 缺失
 - ✅ CONVENTIONS.md / ❌ 缺失
 - ...`,
-      outputHint: '7 份文档生成状态',
+      outputHint: '7 份文档生成状态（含 workflow 检查报告）',
       optional: false
     },
     {
@@ -191,13 +178,15 @@ local.yaml 生成结果（已存在/已生成）`,
     },
     {
       name: '生成模块映射',
-      prompt: `生成模块索引文件 \`_module-map.yaml\`，它是 agent 高频读取的机器索引。
+      perProject: true,
+      prompt: `生成当前项目的模块索引文件 \`_module-map.yaml\`。
 
 ### ⚠️ 重要：这个文件是唯一的结构化索引源
 所有结构化事实（paths/tags/entrypoints/depends_on/used_by）只维护在这个文件里。
 模块卡片（modules/*.md）只负责人类语义说明，不重复索引信息。
 
 ### 操作
+对扫描列表中的每个项目分别执行：
 1. 检查 \`.sillyspec/docs/<project>/modules/_module-map.yaml\` 是否已存在，已存在则跳过
 2. 分析项目源码目录结构，识别模块划分：
    - 用 \`find . -maxdepth 3 -type d -not -path "*/node_modules/*" -not -path "*/.git/*"\` 查看目录结构
@@ -307,13 +296,15 @@ _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
     },
     {
       name: '生成模块卡片文档',
-      prompt: `根据 _module-map.yaml 中的模块划分，为每个模块生成精简卡片文档。
+      perProject: true,
+      prompt: `根据当前项目的 \`_module-map.yaml\` 生成模块卡片文档。
 
 ### ⚠️ 重要：模块卡片只负责人类语义说明
 结构化索引（paths/tags/entrypoints/depends_on/used_by）已经在 _module-map.yaml 里维护。
 卡片里不要重复这些信息，只写 _module-map.yaml 无法表达的语义内容。
 
 ### 操作
+对扫描列表中的每个项目分别执行：
 1. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`，获取模块列表和路径
 2. 检查 \`.sillyspec/docs/<project>/modules/\` 下已有的模块文档（<module>.md）
 3. 列出每个模块的状态：已有文档 / 缺失
@@ -383,7 +374,8 @@ module_id: <module-id>
     },
     {
       name: '生成业务流程和术语表（可选）',
-      prompt: `根据模块依赖关系和源码，生成跨模块业务流程文档和术语表。
+      perProject: true,
+      prompt: `根据当前项目的模块依赖关系和源码，生成跨模块业务流程文档和术语表。
 
 ⚠️ 这一步是可选的。如果项目模块简单、流程不明显，可以跳过。
 
@@ -449,18 +441,20 @@ step1 → step2 → step3
     },
     {
       name: '自检和提交',
-      prompt: `验证扫描完整性，清理并提交。
+      perProject: true,
+      prompt: `验证当前项目的扫描完整性，清理并提交。
 
 ### 操作
-1. 检查 7 份 scan 文档是否全部生成
-2. 检查模块文档状态（如有）
+对扫描列表中的每个项目分别执行：
+1. 检查 7 份 scan 文档是否全部生成（\`.sillyspec/docs/<project>/scan/\`）
+2. 检查模块文档状态（\`.sillyspec/docs/<project>/modules/\`）
 3. 自检门控：ARCHITECTURE（技术栈+Schema摘要）、CONVENTIONS（隐形规则+代码风格）、STRUCTURE（目录结构）、INTEGRATIONS（外部依赖）、TESTING（测试现状）、CONCERNS（技术债务）、PROJECT（项目概览）
 4. 检查 flows/ 和 glossary.md 是否已生成（如有）
 5. 清理：\`rm -f .sillyspec/docs/<project>/scan/_env-detect.md\`
 6. \`git add .sillyspec/\` — 暂存扫描结果（不要 commit，由用户通过统一提交工具处理）
 
 ### 输出
-扫描完整性报告
+每个项目的扫描完整性报告
 
 ### 注意
 - ❌ 修改代码 / 编造路径 / 读源码全文`,

package/src/workflow.js

@@ -0,0 +1,670 @@
+/**
+ * SillySpec Workflow Engine
+ * 
+ * 定义、检查和执行结构化工作流。
+ * 职责：
+ *   - 加载 .sillyspec/workflows/*.yaml
+ *   - 运行 post_check 验证产物
+ *   - 按角色定位失败 + 生成重试 prompt
+ *   - 根据 role 定义生成 role prompts（Level 2）
+ */
+
+import { readFileSync, existsSync, readdirSync, writeFileSync, mkdirSync } from 'fs'
+import { join, resolve, basename } from 'path'
+import jsYaml from 'js-yaml'
+
+// ─── Workflow 加载 ───
+
+/**
+ * 查找并加载指定名称的 workflow YAML
+ * @param {string} cwd - 项目根目录
+ * @param {string} name - workflow 名称（如 'scan-docs'）
+ * @returns {object|null} workflow 定义，或 null
+ */
+export function loadWorkflow(cwd, name, validate = true) {
+  const wfDir = join(cwd, '.sillyspec', 'workflows')
+  if (!existsSync(wfDir)) return null
+
+  // 优先找 <name>.yaml，其次找 <name>.yml
+  for (const ext of ['.yaml', '.yml']) {
+    const f = join(wfDir, `${name}${ext}`)
+    if (existsSync(f)) {
+      const raw = readFileSync(f, 'utf8')
+      const wf = jsYaml.load(raw)
+      if (validate) {
+        const errors = validateWorkflow(wf)
+        if (errors.length > 0) return { _validationErrors: errors, ...wf }
+      }
+      return wf
+    }
+  }
+  return null
+}
+
+/**
+ * 校验 workflow YAML 结构
+ * @param {object} wf - workflow 定义
+ * @returns {string[]} 错误列表，空数组表示通过
+ */
+export function validateWorkflow(wf) {
+  const errors = []
+  const roles = wf.roles || []
+  const roleIds = new Set(roles.map(r => r.id))
+
+  for (const role of roles) {
+    if (!role.id) {
+      errors.push(`role 缺少 id 字段`)
+      continue
+    }
+    // depends_on 校验
+    const deps = role.depends_on || []
+    for (const depId of deps) {
+      if (!roleIds.has(depId)) {
+        errors.push(`role "${role.id}" 的 depends_on 引用了不存在的 role "${depId}"`)
+      }
+    }
+    // depends_on 循环检测（简单两层：A→B→A）
+    for (const depId of deps) {
+      const depRole = roles.find(r => r.id === depId)
+      if (depRole && (depRole.depends_on || []).includes(role.id)) {
+        errors.push(`循环依赖："${role.id}" ↔ "${depId}"`)
+      }
+    }
+    // from_role 校验
+    const inputs = role.inputs || {}
+    if (!Array.isArray(inputs)) {
+      // inputs is a mapping
+      if (inputs.from_role) {
+        if (!roleIds.has(inputs.from_role)) {
+          errors.push(`role "${role.id}" 的 inputs.from_role 引用了不存在的 role "${inputs.from_role}"`)
+        }
+        if (inputs.output) {
+          const sourceRole = roles.find(r => r.id === inputs.from_role)
+          if (sourceRole) {
+            const outputExists = (sourceRole.outputs || []).some(o => {
+              const outputName = o.name || o.path?.split('/').pop()?.replace(/\.md$/, '') || ''
+              return outputName === inputs.output
+            })
+            if (!outputExists) {
+              errors.push(`role "${role.id}" 的 inputs.from_role "${inputs.from_role}" 没有名为 "${inputs.output}" 的 output`)
+            }
+          }
+        }
+        if (!deps.includes(inputs.from_role)) {
+          errors.push(`role "${role.id}" 的 inputs.from_role "${inputs.from_role}" 未在 depends_on 中声明`)
+        }
+      }
+    } else {
+      // inputs is an array (legacy format)
+      for (const input of inputs) {
+        if (input.from_role) {
+          if (!roleIds.has(input.from_role)) {
+            errors.push(`role "${role.id}" 的 inputs.from_role 引用了不存在的 role "${input.from_role}"`)
+          }
+          if (!deps.includes(input.from_role)) {
+            errors.push(`role "${role.id}" 的 inputs.from_role "${input.from_role}" 未在 depends_on 中声明`)
+          }
+        }
+      }
+    }
+  }
+  return errors
+}
+
+/**
+ * 列出所有可用 workflow
+ */
+export function listWorkflows(cwd) {
+  const wfDir = join(cwd, '.sillyspec', 'workflows')
+  if (!existsSync(wfDir)) return []
+  const files = readdirSync(wfDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
+  return files.map(f => f.replace(/\.(yaml|yml)$/, ''))
+}
+
+// ─── 占位符替换 ───
+
+/**
+ * 替换 workflow YAML 中的 <project> 占位符
+ * @param {object} wf - workflow 定义（会被修改）
+ * @param {string} projectName - 项目名
+ */
+function replaceProjectPlaceholder(wf, projectName) {
+  const json = JSON.stringify(wf)
+  const replaced = json.replace(/<project>/g, projectName)
+  return JSON.parse(replaced)
+}
+
+// ─── Post Check ───
+
+/**
+ * 检查结果项
+ * @typedef {{ role: string, output: string, path: string, check: string, passed: boolean, detail?: string }} CheckResult
+ */
+
+/**
+ * 对单个 output 运行检查
+ * @param {object} outputDef - output 定义
+ * @param {string} basePath - 被检查的文件所在目录
+ * @param {string} cwd - 项目根目录
+ * @returns {CheckResult}
+ */
+function checkOutput(outputDef, projectName, cwd) {
+  // 将 <project> 替换为实际项目名
+  const rawPath = (outputDef.path || '').replace(/<project>/g, projectName)
+  const fullPath = resolve(cwd, rawPath)
+  const checks = outputDef.checks || []
+  const results = []
+
+  for (const check of checks) {
+    switch (check.type) {
+      case 'file_exists': {
+        const exists = existsSync(fullPath)
+        results.push({ passed: exists, check: 'file_exists', detail: exists ? '' : `文件不存在: ${rawPath}` })
+        break
+      }
+      case 'no_empty_files': {
+        if (existsSync(fullPath)) {
+          const content = readFileSync(fullPath, 'utf8')
+          const empty = content.trim().length === 0
+          results.push({ passed: !empty, check: 'no_empty_files', detail: empty ? `文件为空: ${rawPath}` : '' })
+        } else {
+          results.push({ passed: false, check: 'no_empty_files', detail: `文件不存在: ${rawPath}` })
+        }
+        break
+      }
+      case 'min_lines': {
+        if (existsSync(fullPath)) {
+          const content = readFileSync(fullPath, 'utf8')
+          const lines = content.split('\n').length
+          const min = check.min || 1
+          results.push({ passed: lines >= min, check: `min_lines(${min})`, detail: lines >= min ? '' : `文件只有 ${lines} 行，要求至少 ${min} 行: ${rawPath}` })
+        } else {
+          results.push({ passed: false, check: `min_lines(${check.min || 1})`, detail: `文件不存在: ${rawPath}` })
+        }
+        break
+      }
+      case 'contains_sections': {
+        if (existsSync(fullPath)) {
+          const content = readFileSync(fullPath, 'utf8')
+          const sections = check.sections || []
+          const missing = sections.filter(s => !content.includes(`## ${s}`))
+          results.push({ passed: missing.length === 0, check: 'contains_sections', detail: missing.length > 0 ? `缺少章节: ${missing.join(', ')} — ${rawPath}` : '' })
+        } else {
+          results.push({ passed: false, check: 'contains_sections', detail: `文件不存在: ${rawPath}` })
+        }
+        break
+      }
+      case 'no_placeholder': {
+        if (existsSync(fullPath)) {
+          const content = readFileSync(fullPath, 'utf8')
+          const patterns = check.patterns || ['待补充', 'TODO', 'TBD', '未分析', '根据项目情况', '根据实际情况', '按需填写']
+          // 只匹配独立成行的占位文本，不匹配行内引用
+          const lineMatches = patterns.filter(p => {
+            const regex = new RegExp(`^\s*[-*]?\s*${p}\s*$`, 'm')
+            return regex.test(content)
+          })
+          results.push({ passed: lineMatches.length === 0, check: 'no_placeholder', detail: lineMatches.length > 0 ? `包含占位文本: ${lineMatches.map(m => `"${m}"`).join(', ')} — ${rawPath}` : '' })
+        } else {
+          results.push({ passed: false, check: 'no_placeholder', detail: `文件不存在: ${rawPath}` })
+        }
+        break
+      }
+      default:
+        results.push({ passed: true, check: check.type, detail: `未知检查类型，跳过: ${check.type}` })
+    }
+  }
+
+  return results
+}
+
+/**
+ * 运行 workflow 的 post_check
+ * @param {object} wf - workflow 定义
+ * @param {string} cwd - 项目根目录
+ * @param {string} projectName - 项目名
+ * @returns {{ passed: boolean, roleResults: Array<{ roleId: string, roleName: string, passed: boolean, failures: string[] }>, workflowFailures: string[] }}
+ */
+/**
+ * 统一的 Workflow Check 结果协议
+ * CLI 和 run.js 共用同一份结构化结果
+ *
+ * 返回结构：
+ * {
+ *   workflow: string,       // workflow 名称
+ *   project: string,        // 项目名
+ *   status: 'pass'|'fail', // 总体状态
+ *   spec_version: number,   // spec 版本
+ *   roles: [{ id, name, status, outputs: [{ path, status, checks: [{ type, status, detail }] }] }],
+ *   workflow_checks: [{ type, status, detail }],
+ *   failures: [{ level: 'role'|'workflow', role_id?, output?, check, message }],
+ *   retry_prompts: [{ role_id, role_name, prompt }]
+ * }
+ */
+export function runPostCheck(wf, cwd, projectName, placeholders = {}) {
+  let resolved = replaceProjectPlaceholder(wf, projectName)
+  if (Object.keys(placeholders).length > 0) {
+    let json = JSON.stringify(resolved)
+    for (const [key, value] of Object.entries(placeholders)) {
+      json = json.replace(new RegExp(`<${key}>`, 'g'), value)
+    }
+    resolved = JSON.parse(json)
+  }
+  return _checkWorkflow(resolved, cwd, projectName)
+}
+
+function _checkWorkflow(wf, cwd, projectName) {
+  const workflowName = wf.name || 'unknown'
+  const specVersion = wf.spec_version || wf.version || 0
+  const workflowChecks = wf.checks?.workflow_level || []
+  const roles = []
+  const failures = []
+  const workflowCheckResults = []
+
+  // 1. 角色级别检查
+  for (const role of wf.roles || []) {
+    const roleId = role.id
+    const roleName = role.name || roleId
+    const outputDefs = role.outputs || []
+    const outputs = []
+
+    for (const outputDef of outputDefs) {
+      const rawPath = (outputDef.path || '').replace(/<project>/g, projectName)
+      const checkResults = checkOutput(outputDef, projectName, cwd)
+      const outputPassed = checkResults.every(c => c.passed)
+
+      outputs.push({
+        path: rawPath,
+        status: outputPassed ? 'pass' : 'fail',
+        checks: checkResults.map(c => ({
+          type: c.check,
+          status: c.passed ? 'pass' : 'fail',
+          detail: c.detail
+        }))
+      })
+
+      for (const cr of checkResults) {
+        if (!cr.passed) {
+          failures.push({
+            level: 'role',
+            role_id: roleId,
+            output: rawPath,
+            check: cr.check,
+            message: cr.detail
+          })
+        }
+      }
+    }
+
+    const rolePassed = outputs.every(o => o.status === 'pass')
+    roles.push({
+      id: roleId,
+      name: roleName,
+      status: rolePassed ? 'pass' : 'fail',
+      outputs
+    })
+  }
+
+  // 2. 工作流级别检查
+  for (const check of workflowChecks) {
+    switch (check.type) {
+      case 'file_count': {
+        const scanDir = join(cwd, '.sillyspec', 'docs', projectName, check.path || 'scan/')
+        if (existsSync(scanDir)) {
+          const files = readdirSync(scanDir).filter(f => f.endsWith('.md'))
+          const min = check.min || 0
+          if (files.length < min) {
+            const detail = `文件数不足: ${scanDir} 有 ${files.length} 个 .md 文件，要求至少 ${min} 个`
+            workflowCheckResults.push({ type: 'file_count', status: 'fail', detail })
+            failures.push({ level: 'workflow', check: 'file_count', message: detail })
+          } else {
+            workflowCheckResults.push({ type: 'file_count', status: 'pass', detail: '' })
+          }
+        } else {
+          const detail = `目录不存在: ${scanDir}`
+          workflowCheckResults.push({ type: 'file_count', status: 'fail', detail })
+          failures.push({ level: 'workflow', check: 'file_count', message: detail })
+        }
+        break
+      }
+      case 'no_empty_files': {
+        const scanDir = join(cwd, '.sillyspec', 'docs', projectName, check.path || 'scan/')
+        if (existsSync(scanDir)) {
+          const files = readdirSync(scanDir).filter(f => f.endsWith('.md'))
+          let anyEmpty = false
+          for (const f of files) {
+            const content = readFileSync(join(scanDir, f), 'utf8')
+            if (content.trim().length === 0) {
+              const detail = `空文件: ${join(scanDir, f)}`
+              workflowCheckResults.push({ type: 'no_empty_files', status: 'fail', detail })
+              failures.push({ level: 'workflow', check: 'no_empty_files', message: detail })
+              anyEmpty = true
+            }
+          }
+          if (!anyEmpty) {
+            workflowCheckResults.push({ type: 'no_empty_files', status: 'pass', detail: '' })
+          }
+        } else {
+          const detail = `目录不存在: ${scanDir}`
+          workflowCheckResults.push({ type: 'no_empty_files', status: 'fail', detail })
+          failures.push({ level: 'workflow', check: 'no_empty_files', message: detail })
+        }
+        break
+      }
+      default:
+        workflowCheckResults.push({ type: check.type, status: 'pass', detail: '' })
+    }
+  }
+
+  const allPassed = roles.every(r => r.status === 'pass') && workflowCheckResults.every(c => c.status === 'pass')
+
+  // 生成 retry prompts
+  const retryPrompts = []
+  if (!allPassed) {
+    for (const role of roles.filter(r => r.status === 'fail')) {
+      const roleFailures = failures.filter(f => f.role_id === role.id)
+      const targetFiles = [...new Set(roleFailures.map(f => f.output).filter(Boolean))]
+      const roleDef = (wf.roles || []).find(r => r.id === role.id)
+      const constraints = roleDef?.constraints || []
+      let prompt = `上一次 workflow 执行存在失败项，请重试。\n\n`
+      prompt += `### 失败角色：${role.name} (${role.id})\n失败原因：\n`
+      for (const f of roleFailures) {
+        prompt += `- ${f.message}\n`
+      }
+      prompt += `\n`
+      for (const fp of targetFiles) {
+        prompt += `目标文件：\`${fp}\`\n`
+      }
+      if (constraints.length > 0) {
+        prompt += `约束：\n`
+        for (const c of constraints) {
+          prompt += `- ${c}\n`
+        }
+      }
+      prompt += `\n⚠️ 你必须确保文件写入指定路径。不要只报告完成，请用 write 工具实际写入。`
+      retryPrompts.push({ role_id: role.id, role_name: role.name, prompt })
+    }
+  }
+
+  return {
+    workflow: workflowName,
+    project: projectName,
+    status: allPassed ? 'pass' : 'fail',
+    spec_version: specVersion,
+    roles,
+    workflow_checks: workflowCheckResults,
+    failures,
+    retry_prompts: retryPrompts
+  }
+}
+
+/**
+ * 格式化检查结果为人类可读报告（兼容旧接口）
+ */
+export function formatCheckReport(result) {
+  const lines = []
+  lines.push('\n📋 Workflow Post-Check 报告\n')
+
+  for (const r of (result.roles || [])) {
+    const icon = r.status === 'pass' ? '✅' : '❌'
+    lines.push(`${icon} ${r.name} (${r.id})`)
+    // 兼容新旧格式
+    const outputFailures = (r.outputs || []).flatMap(o =>
+      (o.checks || []).filter(c => c.status === 'fail').map(c => c.detail)
+    )
+    for (const f of outputFailures) {
+      lines.push(`   └─ ${f}`)
+    }
+  }
+
+  if ((result.workflow_checks || []).some(c => c.status === 'fail')) {
+    lines.push('')
+    for (const c of result.workflow_checks) {
+      if (c.status === 'fail') {
+        lines.push(`❌ 全局检查失败: ${c.detail}`)
+      }
+    }
+  }
+
+  if (result.status === 'pass') {
+    lines.push('\n✅ 全部检查通过')
+  } else {
+    lines.push('\n❌ 存在失败项，请根据以下重试提示修复：')
+  }
+
+  return lines.join('\n')
+}
+
+// ─── 兼容适配层 ───
+
+/**
+ * 兼容旧接口：generateRetryPrompt
+ * @deprecated 直接用 runPostCheck 返回的 retry_prompts
+ */
+export function generateRetryPrompt(wf, checkResult, projectName) {
+  const resolved = replaceProjectPlaceholder(wf, projectName)
+  const lines = []
+  lines.push('上一次 workflow 执行存在失败项，请重试。\n')
+
+  const roles = resolved.roles || []
+  const roleResults = checkResult.roles || []
+  for (const r of roleResults) {
+    if (r.status === 'pass') continue
+    const role = roles.find(rl => rl.id === r.id)
+    if (!role) continue
+
+    lines.push(`### 失败角色：${r.name} (${r.id})`)
+    lines.push(`失败原因：`)
+    const roleFailures = (checkResult.failures || []).filter(f => f.role_id === r.id)
+    for (const f of roleFailures) {
+      lines.push(`- ${f.message}`)
+    }
+    lines.push('')
+
+    for (const output of (role.outputs || [])) {
+      lines.push(`目标文件：\`${output.path}\``)
+    }
+
+    if (role.constraints && role.constraints.length > 0) {
+      lines.push('约束：')
+      for (const c of role.constraints) {
+        lines.push(`- ${c}`)
+      }
+    }
+
+    lines.push('')
+    lines.push('⚠️ 你必须确保文件写入指定路径。不要只报告完成，请用 write 工具实际写入。')
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+// ─── Role Prompt 生成（Level 2）───
+
+/**
+ * 根据 workflow role 定义生成子代理 prompt
+ * @param {object} wf - workflow 定义
+ * @param {string} roleId - 角色ID
+ * @param {string} projectName - 项目名
+ * @param {object} context - 额外上下文（envSummary, missingDocs 等）
+ * @returns {string|null} 生成的 prompt，或 null（角色不存在）
+ */
+export function generateRolePrompt(wf, roleId, projectName, context = {}) {
+  const resolved = replaceProjectPlaceholder(wf, projectName)
+  const role = (resolved.roles || []).find(r => r.id === roleId)
+  if (!role) return null
+
+  const lines = []
+  lines.push(`## 子代理任务：${role.name} (${roleId})`)
+  lines.push('')
+  lines.push(`项目：${projectName}`)
+
+  // 任务描述
+  if (role.task) {
+    lines.push(`任务：${role.task}`)
+  }
+
+  // 依赖角色的输出（depends_on + from_role）
+  const deps = role.depends_on || []
+  if (deps.length > 0) {
+    lines.push('')
+    lines.push('前置依赖（已完成角色的输出）：')
+    const inputs = role.inputs || {}
+    for (const depId of deps) {
+      const depRole = (resolved.roles || []).find(r => r.id === depId)
+      if (!depRole) continue
+      if (inputs.from_role === depId) {
+        lines.push(`- ${depRole.name}（${depId}）：${inputs.output_description || ''}`)
+        if (inputs.output) {
+          const depOutput = (depRole.outputs || []).find(o => {
+            const outputName = o.name || o.path?.split('/').pop()?.replace(/\.md$/, '') || ''
+            return outputName === inputs.output
+          })
+          if (depOutput) {
+            lines.push(`  输出文件：${depOutput.path}`)
+          }
+        }
+      } else {
+        lines.push(`- ${depRole.name}（${depId}）`)
+        for (const o of (depRole.outputs || [])) {
+          lines.push(`  输出：${o.path}`)
+        }
+      }
+    }
+  }
+
+  // 输入提示
+  const inputs = role.inputs || {}
+  const inputPaths = inputs.paths || []
+  const inputHints = inputs.hints || {}
+  if (inputPaths.length > 0) {
+    lines.push('')
+    lines.push('搜索范围：')
+    for (const p of inputPaths) {
+      lines.push(`- ${p}`)
+    }
+  }
+  if (inputHints.grep_patterns && inputHints.grep_patterns.length > 0) {
+    lines.push('')
+    lines.push('搜索关键词：')
+    lines.push(`- ${inputHints.grep_patterns.join(', ')}`)
+  }
+
+  // 额外上下文
+  if (context.envSummary) {
+    lines.push('')
+    lines.push('环境探测结果：')
+    lines.push(context.envSummary)
+  }
+  if (context.missingDocs) {
+    lines.push('')
+    lines.push('缺失文档列表：')
+    lines.push(context.missingDocs)
+  }
+
+  // 输出目标
+  const outputs = role.outputs || []
+  lines.push('')
+  lines.push('目标文件：')
+  for (const o of outputs) {
+    lines.push(`- \`${o.path}\``)
+  }
+
+  // 约束
+  if (role.constraints && role.constraints.length > 0) {
+    lines.push('')
+    lines.push('约束：')
+    for (const c of role.constraints) {
+      lines.push(`- ${c}`)
+    }
+  }
+
+  // 检查要求（告诉子代理需要满足什么）
+  for (const o of outputs) {
+    const checks = o.checks || []
+    for (const check of checks) {
+      if (check.type === 'contains_sections' && check.sections) {
+        lines.push('')
+        lines.push(`必须包含章节：${check.sections.map(s => `"## ${s}"`).join(', ')}`)
+      }
+      if (check.type === 'min_lines') {
+        lines.push(`文件长度要求：至少 ${check.min} 行`)
+      }
+    }
+  }
+
+  lines.push('')
+  lines.push('⚠️ 必须用 write 工具将文件写入磁盘！写完后用 read 工具确认文件存在！')
+
+  return lines.join('\n')
+}
+
+/**
+ * 为 workflow 的所有角色生成 role prompts
+ * @param {object} wf - workflow 定义
+ * @param {string} projectName - 项目名
+ * @param {object} context - 额外上下文
+ * @returns {Array<{ roleId: string, roleName: string, prompt: string }>}
+ */
+export function generateAllRolePrompts(wf, projectName, context = {}) {
+  const resolved = replaceProjectPlaceholder(wf, projectName)
+  const roles = resolved.roles || []
+  return roles.map(role => ({
+    roleId: role.id,
+    roleName: role.name || role.id,
+    prompt: generateRolePrompt(resolved, role.id, projectName, context)
+  }))
+}
+
+// ─── Workflow Run 归档 ───
+
+
+/**
+ * 将 workflow check 结果归档到 .sillyspec/.runtime/workflow-runs/
+ * @param {object} result - runPostCheck 返回的结构化结果
+ * @param {object} options
+ * @param {string} options.cwd - 项目根目录
+ * @param {string} [options.source] - 调用来源（'run.js' / 'cli'）
+ * @param {string} [options.stage] - 阶段名（scan/archive）
+ * @param {string} [options.step] - 步骤名
+ * @returns {string|null} 保存路径，失败返回 null
+ */
+export function saveWorkflowRun(result, options = {}) {
+  const { cwd = '.', source = 'unknown', stage, step } = options
+  const runDir = join(cwd, '.sillyspec', '.runtime', 'workflow-runs')
+  try {
+    mkdirSync(runDir, { recursive: true })
+  } catch (e) {
+    console.warn('⚠️ 无法创建 workflow-runs 目录:', e.message)
+    return null
+  }
+
+  const now = new Date()
+  const ts = now.toISOString().replace(/[-:T]/g, '').slice(0, 14)
+  const filename = `${ts}-${result.workflow || 'unknown'}-${result.project || 'default'}-${result.status}.json`
+  const filepath = join(runDir, filename)
+
+  const record = {
+    run_id: filename.replace('.json', ''),
+    created_at: now.toISOString(),
+    source,
+    ...(stage ? { stage } : {}),
+    ...(step ? { step } : {}),
+    workflow: result.workflow,
+    project: result.project,
+    status: result.status,
+    spec_version: result.spec_version,
+    roles: result.roles,
+    workflow_checks: result.workflow_checks,
+    failures: result.failures,
+    retry_prompts: result.retry_prompts
+  }
+
+  try {
+    writeFileSync(filepath, JSON.stringify(record, null, 2), 'utf8')
+    return filepath
+  } catch (e) {
+    console.warn('⚠️ 保存 workflow run 失败:', e.message)
+    return null
+  }
+}