sillyspec 3.15.0 → 3.16.0

package/src/run.js

@@ -10,6 +10,7 @@ import { ProgressManager } from './progress.js'
 import { stageRegistry, auxiliaryStages } from './stages/index.js'
 import { buildExecuteSteps } from './stages/execute.js'
 import { buildPlanSteps } from './stages/plan.js'
+import { formatExecuteSummary } from './worktree-apply.js'
 
 /**
  * 同步触发辅助函数：_write 后 best-effort 同步到平台
@@ -146,7 +147,7 @@ async function ensureStageSteps(progress, stageName, cwd) {
 /**
  * 输出当前步骤的 prompt
  */
-async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjectName) {
+async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjectName, platformOpts = {}) {
   const step = steps[stepIndex]
   const total = steps.length
   const projectName = dbProjectName || basename(cwd)
@@ -217,6 +218,43 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   if (changeName && promptText.includes('<change-name>')) {
     promptText = promptText.replace(/<change-name>/g, changeName)
   }
+  // 平台模式：注入路径覆盖指令（仅 scan 阶段）
+  if (stageName === 'scan') {
+    const projectName = dbProjectName || basename(cwd)
+    const specSillyspec = platformOpts?.specRoot
+      ? join(platformOpts.specRoot, '.sillyspec')
+      : join(cwd, '.sillyspec')
+    const docsRoot = join(specSillyspec, 'docs', projectName)
+    const projectsRoot = join(specSillyspec, 'projects')
+
+    promptText = promptText.replace(/\{DOCS_ROOT\}/g, docsRoot)
+    promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, projectsRoot)
+
+    // 平台模式附加指令
+    if (platformOpts?.specRoot || platformOpts?.runtimeRoot) {
+      const platformDirectives = []
+      if (platformOpts.specRoot) {
+        platformDirectives.push(
+          `## ⚠️ 平台模式\n` +
+          `文档路径已参数化：\n` +
+          `- 文档根目录: \`${docsRoot}/\`\n` +
+          `- 项目注册表: \`${projectsRoot}/\`\n` +
+          `创建目录: \`mkdir -p ${docsRoot}/{scan,modules,flows} ${projectsRoot}\`\n`
+        )
+      }
+      if (platformOpts.runtimeRoot) {
+        const scanRunId = platformOpts.scanRunId || 'scan-' + new Date().toISOString().slice(0, 19).replace(/[T:]/g, '-')
+        platformDirectives.push(
+          `运行时产物写入: \`${platformOpts.runtimeRoot}/scan-runs/${scanRunId}/\`\n`
+        )
+      }
+      if (platformOpts.workspaceId) {
+        platformDirectives.push(`workspace_id: ${platformOpts.workspaceId}`)
+      }
+      promptText = platformDirectives.join('\n') + '\n\n' + promptText
+    }
+  }
+
   console.log(promptText)
   console.log(`\n### ⚠️ 铁律`)
   console.log('- **文档是核心资产，代码是文档的产物。** 没有文档就没有代码——文档是 AI 的记忆，是团队协作的基础，是后续维护的唯一依据。任何代码产出必须先有对应的设计/规范文档支撑。')
@@ -264,6 +302,50 @@ export async function runCommand(args, cwd) {
   const isConfirm = flags.includes('--confirm')
   const isSkipApproval = flags.includes('--skip-approval')
 
+  // 平台模式参数（供 SillyHub 等平台调用）
+  const getFlagValue = (name) => {
+    const idx = flags.indexOf(name)
+    return idx !== -1 && flags[idx + 1] ? flags[idx + 1] : null
+  }
+  const platformOpts = {
+    specRoot: getFlagValue('--spec-root'),
+    runtimeRoot: getFlagValue('--runtime-root'),
+    workspaceId: getFlagValue('--workspace-id'),
+    scanRunId: getFlagValue('--scan-run-id'),
+  }
+
+  // 跨 --done 生命周期：优先从 metadata 文件恢复 platformOpts
+  // 首次 scan 时写入，后续 --done 读取
+  const platformOptsFile = join(cwd, '.sillyspec', '.runtime', 'platform-scan.json')
+  if (isDone || isSkip) {
+    // --done/--skip 阶段：从文件恢复
+    try {
+      const { readFileSync } = await import('fs')
+      const saved = JSON.parse(readFileSync(platformOptsFile, 'utf8'))
+      if (saved.specRoot) platformOpts.specRoot = saved.specRoot
+      if (saved.runtimeRoot) platformOpts.runtimeRoot = saved.runtimeRoot
+      if (saved.workspaceId) platformOpts.workspaceId = saved.workspaceId
+      if (saved.scanRunId) platformOpts.scanRunId = saved.scanRunId
+    } catch {
+      // 文件不存在，说明不是平台模式，跳过
+    }
+  } else if (platformOpts.specRoot || platformOpts.runtimeRoot) {
+    // 首次 scan：持久化 platformOpts
+    try {
+      const { mkdirSync, writeFileSync } = await import('fs')
+      mkdirSync(join(cwd, '.sillyspec', '.runtime'), { recursive: true })
+      writeFileSync(platformOptsFile, JSON.stringify({
+        specRoot: platformOpts.specRoot,
+        runtimeRoot: platformOpts.runtimeRoot,
+        workspaceId: platformOpts.workspaceId,
+        scanRunId: platformOpts.scanRunId,
+        savedAt: new Date().toISOString(),
+      }, null, 2) + '\n')
+    } catch {
+      // 静默失败，不影响主流程
+    }
+  }
+
   // 解析 --output
   let outputText = null
   const outputIdx = flags.indexOf('--output')
@@ -285,6 +367,26 @@ export async function runCommand(args, cwd) {
     changeName = flags[changeIdx + 1]
   }
 
+  // 未知参数 fail-fast
+  const knownFlags = new Set([
+    '--done', '--skip', '--status', '--reset', '--confirm', '--skip-approval',
+    '--output', '--input', '--change',
+    '--spec-root', '--runtime-root', '--workspace-id', '--scan-run-id',
+    '--json', '--dir', '--help',
+  ])
+  for (let i = 0; i < flags.length; i++) {
+    const f = flags[i]
+    if (f.startsWith('--')) {
+      if (!knownFlags.has(f)) {
+        console.error(`❌ 未知参数: ${f}`)
+        console.error(`已知参数: ${[...knownFlags].sort().join(', ')}`)
+        process.exit(1)
+      }
+      // 跳过 value 参数
+      i++
+    }
+  }
+
   const isAuxiliary = auxiliaryStages.includes(stageName)
 
   const pm = new ProgressManager()
@@ -360,11 +462,11 @@ export async function runCommand(args, cwd) {
 
   // --done
   if (isDone) {
-    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange })
+    return await completeStep(pm, progress, stageName, cwd, outputText, inputText, { confirm: isConfirm, changeName: effectiveChange, platformOpts })
   }
 
   // 默认：输出当前步骤
-  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval)
+  return await runStage(pm, progress, stageName, cwd, effectiveChange, isSkipApproval, platformOpts)
 }
 
 /**
@@ -379,7 +481,7 @@ function resolveChangeNameAuto(cwd) {
   return null
 }
 
-async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false) {
+async function runStage(pm, progress, stageName, cwd, changeName, skipApproval = false, platformOpts = {}) {
   // execute 阶段启动前检查审批
   if (stageName === 'execute' && !skipApproval) {
     const approval = await checkApproval(cwd, changeName)
@@ -443,7 +545,7 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
 
   const defSteps = await getStageSteps(stageName, cwd, progress)
   if (defSteps && defSteps[currentIdx]) {
-    await outputStep(stageName, currentIdx, defSteps, cwd, changeName, progress.project || null)
+    await outputStep(stageName, currentIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
   }
 }
 
@@ -526,7 +628,7 @@ function validateFileLocations(cwd, stageName, progress, changeName) {
 }
 
 async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
-  const { printNext = true, confirm = false, changeName } = options
+  const { printNext = true, confirm = false, changeName, platformOpts = {} } = options
   const stageData = progress.stages[stageName]
   if (!stageData || !stageData.steps) {
     console.error(`❌ 阶段 ${stageName} 未初始化`)
@@ -547,10 +649,13 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     const MAX_OUTPUT = 200
     if (outputText.length > MAX_OUTPUT) {
       steps[currentIdx].output = outputText.slice(0, MAX_OUTPUT) + '…'
-      const artifactsDir = join(cwd, '.sillyspec', '.runtime', 'artifacts')
-      mkdirSync(artifactsDir, { recursive: true })
+      // 平台模式：artifact 写入 runtime-root，否则写 .sillyspec/.runtime/artifacts
+      const artifactBase = platformOpts?.runtimeRoot
+        ? join(platformOpts.runtimeRoot, 'scan-runs', platformOpts.scanRunId || 'unknown')
+        : join(cwd, '.sillyspec', '.runtime', 'artifacts')
+      mkdirSync(artifactBase, { recursive: true })
       const ts = new Date().toISOString().slice(0,19).replace(/[-T:]/g, '')
-      writeFileSync(join(artifactsDir, `${changeName || 'unknown'}-${stageName}-step${currentIdx + 1}-${ts}.txt`), outputText)
+      writeFileSync(join(artifactBase, `${changeName || 'unknown'}-${stageName}-step${currentIdx + 1}-${ts}.txt`), outputText)
     } else {
       steps[currentIdx].output = outputText
     }
@@ -682,6 +787,56 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       appendFileSync(inputsPath, entry)
     }
 
+    // 平台模式：scan 完成后生成 manifest.json
+    if (stageName === 'scan' && platformOpts.specRoot) {
+      try {
+        const { mkdirSync, writeFileSync } = await import('fs')
+        const { join } = await import('path')
+        const { execSync } = await import('child_process')
+        const manifestDir = join(platformOpts.specRoot, '.sillyspec')
+        mkdirSync(manifestDir, { recursive: true })
+        let sourceCommit = null
+        try {
+          sourceCommit = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', timeout: 5000 }).trim()
+        } catch {}
+        const manifest = {
+          workspace_id: platformOpts.workspaceId || null,
+          scan_run_id: platformOpts.scanRunId || null,
+          source_commit: sourceCommit,
+          generated_at: new Date().toISOString(),
+          schema_version: 1,
+        }
+        const manifestPath = join(manifestDir, 'manifest.json')
+        writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
+        console.log(`📄 manifest.json 已写入: ${manifestPath}`)
+        if (!sourceCommit) {
+          console.log(`⚠️  source_commit 无法获取（可能非 git 目录），已设为 null`)
+        }
+        // 清理平台参数临时文件
+        const { unlinkSync } = await import('fs')
+        const platformOptsFile = join(cwd, '.sillyspec', '.runtime', 'platform-scan.json')
+        try { unlinkSync(platformOptsFile) } catch {}
+
+        // 平台模式后置校验：检查 source_root 是否被污染
+        if (platformOpts.specRoot) {
+          const { readdirSync } = await import('fs')
+          const localDocsDir = join(cwd, '.sillyspec', 'docs')
+          try {
+            if (existsSync(localDocsDir)) {
+              const entries = readdirSync(localDocsDir, { recursive: true }).filter(e => e.endsWith('.md'))
+              if (entries.length > 0) {
+                console.warn(`⚠️ 平台模式后置校验：source_root 下存在 ${entries.length} 个文档文件：`)
+                console.warn(`   路径：${localDocsDir}/`)  
+                console.warn(`   可能原因：agent 未遵守路径覆盖，将文档写入到了 cwd 而非 spec-root`)
+              }
+            }
+          } catch {}
+        }
+      } catch (e) {
+        console.warn(`⚠️  manifest.json 写入失败: ${e.message}`)
+      }
+    }
+
     validateMetadata(cwd, stageName)
 
     // 验证关键文件是否在正确的变更目录下
@@ -745,7 +900,21 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     console.log(`✅ ${stageName} 阶段已完成（${total}/${total} 步）`)
 
     if (stageName === 'execute') {
-      console.log('\n👉 下一步：sillyspec run verify（验证通过后才能归档）')
+      // execute run summary：展示真实可得的结构化信息
+      try {
+        const lastOutput = steps[steps.length - 1]?.output || ''
+        const summary = formatExecuteSummary({
+          changeName,
+          stepsCompleted: total,
+          stepsTotal: total,
+          agentSummary: lastOutput,
+          cwd,
+        })
+        console.log(`\n${summary}`)
+      } catch (e) {
+        // summary 失败不影响主流程
+        console.log('\n👉 下一步：sillyspec run verify（验证通过后才能归档）')
+      }
     } else if (stageName === 'verify') {
       console.log('\n👉 下一步：sillyspec run archive（验证通过，可以归档了）')
     } else if (stageName === 'archive') {
@@ -847,7 +1016,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
   }
 
   if (printNext) {
-    await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null)
+    await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
   }
   return { stageCompleted: false, currentIdx, nextPendingIdx }
 }
@@ -885,7 +1054,7 @@ async function skipStep(pm, progress, stageName, cwd, changeName) {
   const nextPendingIdx = steps.findIndex(s => s.status === 'pending')
   if (nextPendingIdx !== -1 && defSteps) {
     console.log('')
-    await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null)
+    await outputStep(stageName, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
   }
 }
 
@@ -1030,7 +1199,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
         }
       }
     }
-    await outputStep(currentStage, pendingIdx, defSteps, cwd, changeName, progress.project || null)
+    await outputStep(currentStage, pendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
     return
   }
 
@@ -1039,7 +1208,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
     process.exit(1)
   }
 
-  const result = await completeStep(pm, progress, currentStage, cwd, outputText, inputText, { printNext: false, changeName })
+  const result = await completeStep(pm, progress, currentStage, cwd, outputText, inputText, { printNext: false, changeName, platformOpts })
   if (!result) return
   progress = await pm.read(cwd, changeName)
 
@@ -1060,7 +1229,7 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
         }
       }
     }
-    await outputStep(currentStage, nextPendingIdx, defSteps, cwd, changeName, progress.project || null)
+    await outputStep(currentStage, nextPendingIdx, defSteps, cwd, changeName, progress.project || null, platformOpts)
     return
   }
 
@@ -1102,6 +1271,6 @@ async function runAutoMode(pm, progress, cwd, flags, changeName) {
         }
       }
     }
-    await outputStep(next, firstPending, nextSteps, cwd, changeName, progress.project || null)
+    await outputStep(next, firstPending, nextSteps, cwd, changeName, progress.project || null, platformOpts)
   }
 }

package/src/stages/doctor.js

@@ -91,6 +91,48 @@ for f in .sillyspec/projects/*.yaml; do
 done
 \`\`\`
 
+### 6. Worktree 隔离环境检查
+\`\`\`bash
+# 检测当前目录是否在 submodule 中
+SUPERPROJECT=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
+if [ -n "$SUPERPROJECT" ]; then
+  echo "⚠️ 当前目录在 git submodule 内，worktree 隔离不可用"
+else
+  echo "✅ 不在 submodule 中"
+fi
+
+# 检测是否已在 linked worktree 中
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+if [ "$GIT_DIR" != "$GIT_COMMON" ] && [ -z "$SUPERPROJECT" ]; then
+  echo "✅ 已在 linked worktree 中"
+else
+  echo "ℹ️ 在主仓库中（非 worktree）"
+fi
+
+# 检查 worktree 存储目录是否被 .gitignore 忽略
+WT_DIR='.sillyspec/.runtime/worktrees'
+if git check-ignore -q "$WT_DIR" 2>/dev/null; then
+  echo "✅ worktree 目录已被 .gitignore 忽略 ($WT_DIR)"
+else
+  echo "❌ worktree 目录未被 .gitignore 忽略 ($WT_DIR) — worktree 创建将被阻断"
+  echo "   修复: 在 .gitignore 中添加 $WT_DIR/"
+fi
+
+# 检查 DB 中的 isolation 状态
+DB_FILE='.sillyspec/.runtime/sillyspec.db'
+if [ -f "$DB_FILE" ]; then
+  echo ""
+  echo "isolation 状态（来自 sillyspec.db）:"
+  sqlite3 -header -column "$DB_FILE" "SELECT name, isolation_status AS status, isolation_mode AS mode, isolation_reason AS reason FROM changes WHERE status='active'" 2>/dev/null || echo "⚠️ 查询 isolation 失败"
+else
+  echo ""
+  echo "ℹ️ sillyspec.db 不存在（尚未初始化）"
+fi
+else
+  echo "ℹ️ gate-status.json 不存在（尚未进入 execute 阶段）"
+fi
+\`\`\`\n
 ### 输出
 汇总所有检查结果，按以下格式：
 \`\`\`

package/src/stages/execute.js

@@ -61,8 +61,14 @@ const fixedPrefix = [
 3. 后续所有子代理的 cwd 设为该 worktree 路径
 4. 如果创建失败 → 报错并停止（不要在无隔离状态下继续）
 
+### 降级模式
+CLI 可能自动降级（sandbox 限制、已在 linked worktree 中）：
+- \`mode: native-worktree\` — 已在 linked worktree，直接复用
+- \`mode: in-place-fallback\` — git worktree add 失败，降级为 in-place + baseline protection
+- 这两种模式都会输出 worktree 路径和分支名，正常继续即可
+
 ### 输出
-worktree 路径 + 分支名
+worktree 路径 + 分支名 + 模式（如果有）
 
 ### 完成后执行
 sillyspec run execute --done --output "worktree 路径 + 分支名"`,
@@ -184,19 +190,40 @@ const fixedSuffix = [
     name: '完成确认',
     prompt: `所有任务完成后的收尾。
 
-### 操作（有 worktree）
+先检查当前 worktree 的隔离模式：
+\`\`\`bash
+node -e "import('./src/worktree.js').then(w => { const wm = new w.WorktreeManager(); const m = wm.getMeta('<change-name>'); console.log(m ? JSON.stringify({mode: m.mode, path: m.worktreePath}) : 'no meta'); })"
+# 或从 DB 读取：
+sqlite3 -json .sillyspec/.runtime/sillyspec.db "SELECT isolation_status, isolation_mode, isolation_reason FROM changes WHERE name='<change-name>'" 2>/dev/null
+\`\`\`
+
+### 操作（mode = worktree，SillySpec 创建的隔离 worktree）
 1. 运行 \`sillyspec worktree apply --check-only <change-name>\`
 2. 展示 diff 摘要（文件列表 + 变更统计）
 3. 检查结果说明（是否通过文件清单校验）
 4. 用户确认后运行 \`sillyspec worktree apply <change-name>\`
-5. apply 成功 → 自动 cleanup
+5. apply 成功 → 运行 \`sillyspec worktree cleanup <change-name>\` → 输出 Worktree: cleaned
 6. apply 失败 → 展示错误详情，用户选择重试或手动处理
 7. 如果用户不想 apply → 运行 \`sillyspec worktree cleanup <change-name>\` 丢弃
 8. 建议下一步：\`sillyspec run verify\`
 
+### 操作（mode = native-worktree，用户已有的 linked worktree）
+1. 运行 \`sillyspec worktree apply --check-only <change-name>\`
+2. 展示 diff 摘要
+3. 用户确认后运行 \`sillyspec worktree apply <change-name>\`
+4. **不要运行 cleanup** — 这是用户自己的 worktree，SillySpec 不能删除
+5. 输出 Worktree: kept（SillySpec 未创建此 worktree，保留不动）
+6. 建议下一步：\`sillyspec run verify\`
+
+### 操作（mode = in-place-fallback，降级模式无隔离目录）
+1. 展示本次执行摘要（\`git diff\` 查看变更）
+2. 跳过 apply 和 cleanup（没有隔离 worktree）
+3. 输出 Worktree: none（降级为 in-place，无隔离目录需要清理）
+4. 建议下一步：\`sillyspec run verify\`
+
 ### 操作（无 worktree / --no-worktree 模式）
-1. 跳过 apply 和 cleanup 步骤（因为没有 worktree）
-2. 展示本次执行摘要
+1. 展示本次执行摘要
+2. 输出 Worktree: none
 3. 提示用户直接使用 \`git diff\` 查看变更
 4. 建议下一步：\`sillyspec run verify\`
 

package/src/stages/quick.js

@@ -27,12 +27,12 @@ export const definition = {
 1. 使用预注入的 git 用户名：\`<git-user>\`
 2. 无 \`--change\`：创建 .sillyspec/quicklog/QUICKLOG-\`<git-user>\`.md\`（已存在则追加），写入：
    \`\`\`
-   ## ql-<YYYYMMDD>-<NNN>-<short4> | <now-datetime> | <一句话任务描述>
+   ## ql-<YYYYMMDD>-<NNN>-<XXXX> | <now-datetime> | <一句话任务描述>
    状态：进行中
    文件：<预估要改的文件>
    \`\`\`
-   - ID 格式：\`ql-YYYYMMDD-NNN-XXXX\`（如 ql-20260603-001-a3f2）
-   - \`XXXX\` 是 4 位随机十六进制（防多文件/并发冲突）
+   - ID 格式：\`ql-YYYYMMDD-NNN-XXXX\`
+   - \`XXXX\` 是 4 位随机十六进制字符（如 a3f2、b7c1、00ef），**不是描述词缩写**
    - 追加前扫描文件中已有的 \`ql-<当天日期>-\` 前缀的最大序号，+1 作为新序号
    - 每天从 001 开始，跨日重新计数
    - 此 ID 可被 design.md / plan.md / archive / module 变更索引引用

package/src/stages/scan.js

@@ -12,7 +12,7 @@ export const definition = {
 1. 列出项目顶层目录：\`ls -d */ 2>/dev/null | grep -v node_modules | grep -v '.git' | grep -v '.sillyspec'\`
 2. 对每个顶层目录，快速判断是否为独立项目（检查 package.json / pom.xml / build.gradle / pyproject.toml / go.mod 等构建文件）
 3. 对每个疑似独立项目，检测技术栈：\`cat <dir>/package.json 2>/dev/null | head -5\` 或类似
-4. 对比 \`.sillyspec/projects/\` 已有配置，找出未注册的子项目
+4. 对比 \`{PROJECTS_ROOT}/\` 已有配置，找出未注册的子项目
 
 ### 判断标准（满足任一即为子项目）
 - 有独立的构建文件（package.json, pom.xml, build.gradle, pyproject.toml 等）
@@ -41,8 +41,8 @@ export const definition = {
       prompt: `确定本次要扫描的项目列表。
 
 ### 操作
-1. \`ls .sillyspec/projects/*.yaml 2>/dev/null\` — 列出所有已注册项目
-2. 对每个项目，检查已有的 scan 文档状态：\`ls .sillyspec/docs/<project>/scan/*.md 2>/dev/null\`
+1. \`ls {PROJECTS_ROOT}/*.yaml 2>/dev/null\` — 列出所有已注册项目
+2. 对每个项目，检查已有的 scan 文档状态：\`ls {DOCS_ROOT}/scan/*.md 2>/dev/null\`
 3. 按以下格式展示：
 
 \`\`\`
@@ -75,7 +75,7 @@ export const definition = {
 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\`（临时文件，扫描完删除）
+4. 结果保存到 \`{DOCS_ROOT}/scan/_env-detect.md\`（临时文件，扫描完删除）
 
 ### 输出
 每个项目的环境探测结果摘要`,
@@ -90,7 +90,7 @@ export const definition = {
 ### 操作
 对扫描列表中的每个项目分别执行：
 1. 检查 7 份文档是否存在：ARCHITECTURE、STRUCTURE、CONVENTIONS、INTEGRATIONS、TESTING、CONCERNS、PROJECT
-   路径：\`.sillyspec/docs/<project>/scan/<DOC>.md\`
+   路径：\`{DOCS_ROOT}/scan/<DOC>.md\`
 2. 列出已有 ✅ 和缺失 ⬜
 
 ### 输出
@@ -187,7 +187,7 @@ local.yaml 生成结果（已存在/已生成）`,
 
 ### 操作
 对扫描列表中的每个项目分别执行：
-1. 检查 \`.sillyspec/docs/<project>/modules/_module-map.yaml\` 是否已存在，已存在则跳过
+1. 检查 \`{DOCS_ROOT}/modules/_module-map.yaml\` 是否已存在，已存在则跳过
 2. 分析项目源码目录结构，识别模块划分：
    - 用 \`find . -maxdepth 3 -type d -not -path "*/node_modules/*" -not -path "*/.git/*"\` 查看目录结构
    - 每个有明确职责的独立目录识别为一个模块
@@ -200,7 +200,7 @@ local.yaml 生成结果（已存在/已生成）`,
 4. 分析跨模块依赖关系：
    - 用 grep import/require 分析模块间的引用链
    - 填充 depends_on（本模块依赖谁）和 used_by（谁依赖本模块）
-5. 生成 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`
+5. 生成 \`{DOCS_ROOT}/modules/_module-map.yaml\`
 6. 如果 modules/ 目录不存在，先创建
 7. 原子写入（先写 tmp 文件再 rename）
 
@@ -305,8 +305,8 @@ _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
 
 ### 操作
 对扫描列表中的每个项目分别执行：
-1. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`，获取模块列表和路径
-2. 检查 \`.sillyspec/docs/<project>/modules/\` 下已有的模块文档（<module>.md）
+1. 读取 \`{DOCS_ROOT}/modules/_module-map.yaml\`，获取模块列表和路径
+2. 检查 \`{DOCS_ROOT}/modules/\` 下已有的模块文档（<module>.md）
 3. 列出每个模块的状态：已有文档 / 缺失
 4. **必须停下来问用户**：
    - 展示模块列表及现有文档状态
@@ -323,7 +323,7 @@ _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
 \`\`\`
 模块名：<module-id>
 模块路径：<glob patterns>
-目标文件：.sillyspec/docs/<project>/modules/<module-id>.md
+目标文件：{DOCS_ROOT}/modules/<module-id>.md
 
 操作：
 1. 用 grep/rg 搜索模块路径范围内的源码（禁止读源码全文）
@@ -380,7 +380,7 @@ module_id: <module-id>
 ⚠️ 这一步是可选的。如果项目模块简单、流程不明显，可以跳过。
 
 ### flows/ 目录
-目标目录：\`.sillyspec/docs/<project>/flows/\`
+目标目录：\`{DOCS_ROOT}/flows/\`
 
 根据 _module-map.yaml 中的模块依赖关系，识别跨模块业务流程：
 1. 读取 \`_module-map.yaml\`，分析 used_by 链条
@@ -410,7 +410,7 @@ step1 → step2 → step3
 \`\`\`
 
 ### glossary.md
-目标文件：\`.sillyspec/docs/<project>/glossary.md\`
+目标文件：\`{DOCS_ROOT}/glossary.md\`
 
 提取项目专有术语：
 1. 用 grep 搜索 TODO/FIXME 注释中的术语定义
@@ -446,11 +446,11 @@ step1 → step2 → step3
 
 ### 操作
 对扫描列表中的每个项目分别执行：
-1. 检查 7 份 scan 文档是否全部生成（\`.sillyspec/docs/<project>/scan/\`）
-2. 检查模块文档状态（\`.sillyspec/docs/<project>/modules/\`）
+1. 检查 7 份 scan 文档是否全部生成（\`{DOCS_ROOT}/scan/\`）
+2. 检查模块文档状态（\`{DOCS_ROOT}/modules/\`）
 3. 自检门控：ARCHITECTURE（技术栈+Schema摘要）、CONVENTIONS（隐形规则+代码风格）、STRUCTURE（目录结构）、INTEGRATIONS（外部依赖）、TESTING（测试现状）、CONCERNS（技术债务）、PROJECT（项目概览）
 4. 检查 flows/ 和 glossary.md 是否已生成（如有）
-5. 清理：\`rm -f .sillyspec/docs/<project>/scan/_env-detect.md\`
+5. 清理：\`rm -f {DOCS_ROOT}/scan/_env-detect.md\`
 6. \`git add .sillyspec/\` — 暂存扫描结果（不要 commit，由用户通过统一提交工具处理）
 
 ### 输出

package/src/workflow.js

@@ -630,8 +630,12 @@ export function generateAllRolePrompts(wf, projectName, context = {}) {
  * @returns {string|null} 保存路径，失败返回 null
  */
 export function saveWorkflowRun(result, options = {}) {
-  const { cwd = '.', source = 'unknown', stage, step } = options
-  const runDir = join(cwd, '.sillyspec', '.runtime', 'workflow-runs')
+  const { cwd = '.', source = 'unknown', stage, step, runtimeRoot, scanRunId } = options
+  // 平台模式：写入 runtime-root/scan-runs/<scan-run-id>/workflow-runs/
+  // 本地模式：写入 cwd/.sillyspec/.runtime/workflow-runs/
+  const runDir = runtimeRoot
+    ? join(runtimeRoot, 'scan-runs', scanRunId || 'unknown', 'workflow-runs')
+    : join(cwd, '.sillyspec', '.runtime', 'workflow-runs')
   try {
     mkdirSync(runDir, { recursive: true })
   } catch (e) {