sillyspec 3.7.13 → 3.7.15

package/src/run.js

@@ -0,0 +1,320 @@
+/**
+ * sillyspec run 命令实现
+ *
+ * CLI 成为流程引擎，AI 变成步骤执行器。
+ */
+import { basename, join } from 'path'
+import { existsSync, readdirSync, mkdirSync, writeFileSync } from 'fs'
+import { ProgressManager } from './progress.js'
+import { stageRegistry, getNextStage } from './stages/index.js'
+import { buildExecuteSteps } from './stages/execute.js'
+
+/**
+ * 获取阶段的步骤定义（execute 需要动态构建）
+ */
+function getStageSteps(stageName, cwd) {
+  if (stageName === 'execute') {
+    const plansDir = join(cwd, '.sillyspec', 'plans')
+    let planFile = null
+    if (existsSync(plansDir)) {
+      const files = readdirSync(plansDir).filter(f => f.endsWith('.md')).sort()
+      if (files.length > 0) planFile = join(plansDir, files[files.length - 1])
+    }
+    return buildExecuteSteps(planFile)
+  }
+  const def = stageRegistry[stageName]
+  return def ? def.steps : null
+}
+
+/**
+ * 确保阶段的 steps 已初始化到 progress.json
+ */
+function ensureStageSteps(progress, stageName, cwd) {
+  if (!progress.stages) progress.stages = {}
+
+  const steps = getStageSteps(stageName, cwd)
+  if (!steps) return false
+
+  if (!progress.stages[stageName] || !progress.stages[stageName].steps || progress.stages[stageName].steps.length === 0) {
+    progress.stages[stageName] = {
+      status: 'in-progress',
+      startedAt: new Date().toISOString(),
+      completedAt: null,
+      steps: steps.map(s => ({ name: s.name, status: 'pending' }))
+    }
+    return true // 需要写入
+  }
+
+  // 检查步骤数量是否匹配（execute 动态步骤可能变化）
+  if (progress.stages[stageName].steps.length !== steps.length) {
+    // 保留已完成的状态，重新构建步骤列表
+    const oldSteps = progress.stages[stageName].steps
+    progress.stages[stageName].steps = steps.map((s, i) => {
+      const old = oldSteps[i]
+      if (old && old.name === s.name) return old
+      return { name: s.name, status: 'pending' }
+    })
+    return true
+  }
+
+  return false
+}
+
+/**
+ * 输出当前步骤的 prompt
+ */
+function outputStep(stageName, stepIndex, steps, cwd) {
+  const step = steps[stepIndex]
+  const total = steps.length
+  const projectName = basename(cwd)
+
+  console.log(`---`)
+  console.log(`stage: ${stageName}`)
+  console.log(`step: ${stepIndex + 1}/${total}`)
+  console.log(`stepName: ${step.name}`)
+  console.log(`project: ${projectName}`)
+  console.log(`---\n`)
+  console.log(`## Step ${stepIndex + 1}/${total}: ${step.name}\n`)
+  console.log(step.prompt)
+  console.log(`\n### 完成后执行`)
+  console.log(`sillyspec run ${stageName} --done --output "你的摘要"`)
+}
+
+/**
+ * sillyspec run <stage> 主命令
+ */
+export function runCommand(args, cwd) {
+  // 解析参数
+  const stageName = args[0]
+  const flags = args.slice(1)
+
+  if (!stageName || !stageRegistry[stageName]) {
+    console.error(`❌ 未知阶段: ${stageName || '(未指定)'}`)
+    console.error(`可选: ${Object.keys(stageRegistry).join(', ')}`)
+    process.exit(1)
+  }
+
+  const isDone = flags.includes('--done')
+  const isSkip = flags.includes('--skip')
+  const isStatus = flags.includes('--status')
+  const isReset = flags.includes('--reset')
+
+  // 解析 --output
+  let outputText = null
+  const outputIdx = flags.indexOf('--output')
+  if (outputIdx !== -1 && flags[outputIdx + 1]) {
+    outputText = flags[outputIdx + 1]
+  }
+
+  const pm = new ProgressManager()
+  let progress = pm.read(cwd)
+
+  if (!progress) {
+    console.error('❌ 未找到 progress.json，请先运行 sillyspec init')
+    process.exit(1)
+  }
+
+  // --reset
+  if (isReset) {
+    return resetStage(pm, progress, stageName, cwd)
+  }
+
+  // 确保步骤已初始化
+  const changed = ensureStageSteps(progress, stageName, cwd)
+  if (changed) {
+    pm._write(cwd, progress)
+    progress = pm.read(cwd)
+  }
+
+  // --status
+  if (isStatus) {
+    return showStatus(progress, stageName)
+  }
+
+  // --skip
+  if (isSkip) {
+    return skipStep(pm, progress, stageName, cwd)
+  }
+
+  // --done
+  if (isDone) {
+    return completeStep(pm, progress, stageName, cwd, outputText)
+  }
+
+  // 默认：输出当前步骤
+  return runStage(progress, stageName, cwd)
+}
+
+function runStage(progress, stageName, cwd) {
+  const stageData = progress.stages[stageName]
+  if (!stageData || !stageData.steps) {
+    console.error(`❌ 阶段 ${stageName} 未初始化`)
+    process.exit(1)
+  }
+
+  const steps = stageData.steps
+  const currentIdx = steps.findIndex(s => s.status !== 'completed' && s.status !== 'skipped')
+
+  if (currentIdx === -1) {
+    const total = steps.length
+    console.log(`✅ ${stageName} 阶段已完成（${total}/${total} 步）`)
+    const next = getNextStage(stageName)
+    if (next) {
+      console.log(`\n下一步：sillyspec run ${next}`)
+      console.log(`或：/sillyspec:${next}`)
+    }
+    process.exit(2)
+  }
+
+  const stageDef = stageRegistry[stageName]
+  const defSteps = getStageSteps(stageName, cwd)
+  if (defSteps && defSteps[currentIdx]) {
+    outputStep(stageName, currentIdx, defSteps, cwd)
+  }
+}
+
+function completeStep(pm, progress, stageName, cwd, outputText) {
+  const stageData = progress.stages[stageName]
+  if (!stageData || !stageData.steps) {
+    console.error(`❌ 阶段 ${stageName} 未初始化`)
+    process.exit(1)
+  }
+
+  const steps = stageData.steps
+  const currentIdx = steps.findIndex(s => s.status === 'pending')
+
+  if (currentIdx === -1) {
+    console.error('没有待完成的步骤')
+    process.exit(1)
+  }
+
+  // 标记完成
+  steps[currentIdx].status = 'completed'
+  steps[currentIdx].completedAt = new Date().toISOString()
+  if (outputText) {
+    const MAX_OUTPUT = 200
+    if (outputText.length > MAX_OUTPUT) {
+      steps[currentIdx].output = outputText.slice(0, MAX_OUTPUT) + '…'
+      // Save full output to artifacts/
+      const artifactsDir = join(cwd, '.sillyspec', '.runtime', 'artifacts')
+      mkdirSync(artifactsDir, { recursive: true })
+      const ts = new Date().toISOString().replace(/[:.]/g, '-')
+      writeFileSync(join(artifactsDir, `${stageName}-step${currentIdx + 1}-${ts}.txt`), outputText)
+    } else {
+      steps[currentIdx].output = outputText
+    }
+  }
+
+  // 检查是否还有下一步
+  const nextPendingIdx = steps.findIndex(s => s.status === 'pending')
+
+  if (nextPendingIdx === -1) {
+    // 全部完成
+    stageData.status = 'completed'
+    stageData.completedAt = new Date().toISOString()
+
+    const next = getNextStage(stageName)
+    if (next) {
+      progress.currentStage = next
+      if (!progress.stages[next]) progress.stages[next] = { status: 'pending', steps: [], startedAt: null, completedAt: null }
+      if (progress.stages[next].status === 'pending' || !progress.stages[next].status) {
+        progress.stages[next].status = 'in-progress'
+        progress.stages[next].startedAt = new Date().toISOString()
+      }
+    }
+
+    progress.lastActive = new Date().toISOString()
+    pm._write(cwd, progress)
+
+    const total = steps.length
+    console.log(`✅ ${stageName} 阶段已完成（${total}/${total} 步）`)
+    if (next) {
+      console.log(`\n下一步：sillyspec run ${next}`)
+      console.log(`或：/sillyspec:${next}`)
+    }
+    return
+  }
+
+  progress.lastActive = new Date().toISOString()
+  pm._write(cwd, progress)
+
+  const defSteps = getStageSteps(stageName, cwd)
+  console.log(`✅ Step ${currentIdx + 1}/${steps.length} 完成：${steps[currentIdx].name}\n`)
+  outputStep(stageName, nextPendingIdx, defSteps, cwd)
+}
+
+function skipStep(pm, progress, stageName, cwd) {
+  const stageData = progress.stages[stageName]
+  if (!stageData || !stageData.steps) {
+    console.error(`❌ 阶段 ${stageName} 未初始化`)
+    process.exit(1)
+  }
+
+  const steps = stageData.steps
+  const currentIdx = steps.findIndex(s => s.status === 'pending')
+
+  if (currentIdx === -1) {
+    console.error('没有待跳过的步骤')
+    process.exit(1)
+  }
+
+  const defSteps = getStageSteps(stageName, cwd)
+  const stepDef = defSteps ? defSteps[currentIdx] : null
+  if (stepDef && !stepDef.optional) {
+    console.error(`❌ 步骤 "${steps[currentIdx].name}" 不可跳过`)
+    process.exit(1)
+  }
+
+  steps[currentIdx].status = 'skipped'
+  steps[currentIdx].skippedAt = new Date().toISOString()
+  progress.lastActive = new Date().toISOString()
+  pm._write(cwd, progress)
+
+  console.log(`⏭️ Step ${currentIdx + 1}/${steps.length} 已跳过：${steps[currentIdx].name}`)
+
+  // 输出下一步
+  const nextPendingIdx = steps.findIndex(s => s.status === 'pending')
+  if (nextPendingIdx !== -1 && defSteps) {
+    console.log('')
+    outputStep(stageName, nextPendingIdx, defSteps, cwd)
+  }
+}
+
+function showStatus(progress, stageName) {
+  const stageData = progress.stages[stageName]
+  const stageDef = stageRegistry[stageName]
+
+  if (!stageData || !stageData.steps || stageData.steps.length === 0) {
+    console.log(`阶段：${stageName}（${stageDef.title}）`)
+    console.log(`进度：未初始化`)
+    return
+  }
+
+  const steps = stageData.steps
+  const completed = steps.filter(s => s.status === 'completed' || s.status === 'skipped').length
+  const bar = '█'.repeat(completed) + '░'.repeat(steps.length - completed)
+
+  console.log(`阶段：${stageName}（${stageDef.title}）`)
+  console.log(`进度：[${bar}] ${completed}/${steps.length}\n`)
+
+  const firstPending = steps.findIndex(s => s.status === 'pending')
+
+  steps.forEach((step, i) => {
+    const icon = step.status === 'completed' ? '✅' : step.status === 'skipped' ? '⏭️' : '⬜'
+    const isCurrent = step.status === 'pending' && i === firstPending
+    console.log(`${icon} Step ${i + 1}: ${step.name}${isCurrent ? ' ← 当前' : ''}`)
+  })
+}
+
+function resetStage(pm, progress, stageName, cwd) {
+  const defSteps = getStageSteps(stageName, cwd)
+  progress.stages[stageName] = {
+    status: 'in-progress',
+    startedAt: new Date().toISOString(),
+    completedAt: null,
+    steps: defSteps ? defSteps.map(s => ({ name: s.name, status: 'pending' })) : []
+  }
+  progress.lastActive = new Date().toISOString()
+  pm._write(cwd, progress)
+  console.log(`🔄 ${stageName} 阶段已重置`)
+}

package/src/setup.js

@@ -11,15 +11,7 @@ const __dirname = dirname(__filename);
 
 // ── Skill 定义 ──
 
-const SKILLS = [
-  {
-    id: 'playwright-e2e',
-    name: 'Playwright E2E 测试参考',
-    description: 'E2E 测试编写最佳实践，AI 执行测试任务时自动读取',
-    source: join(__dirname, '..', 'templates', 'skills', 'playwright-e2e'),
-    target: 'playwright-e2e',
-  },
-];
+const SKILLS = [];
 
 // ── MCP 工具定义 ──
 

package/src/stages/brainstorm.js

@@ -0,0 +1,210 @@
+export const definition = {
+  name: 'brainstorm',
+  title: '头脑风暴',
+  description: '探索需求、分析技术方案、识别风险',
+  steps: [
+    {
+      name: '状态检查',
+      prompt: `检查 .sillyspec/.runtime/progress.json 确认当前状态。
+
+### 操作
+1. 运行 \`sillyspec progress show\`
+2. 确认 currentStage 为 "brainstorm"
+3. 如果有进行中的 brainstorm，提示选择继续或重新开始
+4. 如果未初始化，提示先运行 sillyspec init
+
+### 输出
+当前状态摘要（1-2 句话）
+
+### 注意
+- 以 CLI 返回为准，不要自行推断阶段
+- 如果阶段不对，输出正确提示并停止`,
+      outputHint: '状态摘要',
+      optional: false
+    },
+    {
+      name: '加载项目上下文',
+      prompt: `加载项目现有上下文，理解代码结构和约定。
+
+### 操作
+1. 检查是否工作区模式：\`ls .sillyspec/projects/*.yaml\`
+2. 工作区模式：加载 CODEBASE-OVERVIEW.md + 共享规范 + 子项目上下文
+3. 单项目模式：加载 PROJECT.md、REQUIREMENTS.md、ROADMAP.md
+4. 棕地项目：读取 docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
+5. 查看进行中的变更：\`ls .sillyspec/changes/ | grep -v archive\`
+
+### 输出
+项目现状理解摘要（3-5 句话，关键约定和架构决策）
+
+### 注意
+- 工作区模式下需要询问本次需求属于哪个子项目
+- 棕地项目必须读取数据模型章节`,
+      outputHint: '上下文摘要',
+      optional: false
+    },
+    {
+      name: '协作与复用检查',
+      prompt: `检查是否有同名变更或可复用模板。
+
+### 操作
+1. 检查已有变更：\`ls .sillyspec/changes/ | grep -v archive\`
+   - 有相关变更 → 提示用户，避免重复
+2. 检查全局模板：\`ls ~/.sillyspec/templates/\`
+   - 有匹配模板 → 询问是否基于模板
+3. 无相关内容 → 跳过，不输出
+
+### 输出
+检测到的相关变更和可用模板（无则输出"无冲突，继续"）`,
+      outputHint: '已有变更和可用模板',
+      optional: true
+    },
+    {
+      name: '原型/设计图分析',
+      prompt: `如果用户提供了截图、图片或 HTML 原型，分析提取结构。
+
+### 操作
+1. 识别图片中的页面结构（区域、组件、布局）
+2. 提取表单字段（名称、类型、必填、选项）
+3. 提取交互流程（页面跳转、按钮行为）
+4. 提取标注和备注（业务规则、权限说明）
+5. 展示分析结果，请用户确认遗漏
+
+### 输出
+页面结构树 + 字段列表 + 交互流程图
+
+### 注意
+- 没有原型则跳过此步骤
+- 多页面时逐页分析，不要一次全部输出
+- 图片信息 > 文字描述，不要忽略视觉信息`,
+      outputHint: '页面结构和交互流程',
+      optional: true
+    },
+    {
+      name: '需求范围评估',
+      prompt: `评估需求复杂度，判断是否需要拆分。
+
+### 操作
+1. 根据分析结果判断复杂度
+2. 满足以下任意 2 条建议拆分：
+   - 3+ 个可独立交付的功能模块
+   - 3+ 种角色有不同权限和视图
+   - 跨页面状态流转（审批流、多步表单）
+   - 模块间耦合度低可独立开发
+3. 需要拆分 → 生成 MASTER.md，规划子阶段
+4. 不需要拆分 → 继续
+
+### 输出
+拆分方案（如需要）或"无需拆分"确认
+
+### 注意
+- 简单 CRUD 不拆
+- 拆分方案需用户确认`,
+      outputHint: '拆分方案或无需拆分确认',
+      optional: true
+    },
+    {
+      name: '对话式探索',
+      prompt: `通过对话探索需求细节。
+
+### 操作
+1. 从最核心的一个问题开始（用户到底想要什么？）
+2. 等待用户回答后再问下一个
+3. 根据回答判断：信息够了 → 进入方案 / 需要追问 → 只问一个
+4. 探索顺序（按需）：目的 → 约束 → 边界 → 成功标准
+
+### 输出
+需求理解摘要（用户确认的需求点列表）
+
+### 铁律
+- 一次只问一个问题
+- 2-3 轮问答就应进入方案讨论
+- 多选题优于开放式问题
+- YAGNI — 砍掉不需要的功能`,
+      outputHint: '需求理解摘要',
+      optional: false
+    },
+    {
+      name: '提出 2-3 种方案',
+      prompt: `基于需求理解，提出 2-3 种实现方案。
+
+### 操作
+1. 每种方案列出：核心思路、优势、劣势
+2. 给出推荐方案和理由
+3. 等待用户选择或调整
+
+### 输出
+方案对比表 + 推荐方案
+
+### 注意
+- 方案差异要实质性的，不要为了凑数
+- 推荐理由要具体`,
+      outputHint: '方案对比和推荐',
+      optional: false
+    },
+    {
+      name: '分段展示设计',
+      prompt: `按复杂度分段展示设计方案，逐段确认。
+
+### 操作
+1. 简单项目：几句话整体描述
+2. 复杂项目：每段 200-300 字，逐段展示
+3. 每段展示后等待用户确认
+4. 收集修改意见，调整设计
+
+### 输出
+用户确认的完整设计方案
+
+### 注意
+- 不要一次输出大段文字
+- 逐段确认，确保用户跟上`,
+      outputHint: '用户确认的设计方案',
+      optional: false
+    },
+    {
+      name: '写设计文档并自审',
+      prompt: `撰写 design 文档并进行 AI 自审。
+
+### 操作
+1. 将确认的设计写入 \`.sillyspec/changes/<变更名>/design.md\`
+2. 自审检查：
+   - 需求覆盖：是否完整覆盖 Step 6 确认的需求
+   - 约束一致性：是否与 CONVENTIONS.md、ARCHITECTURE.md 一致
+   - 真实性：表名/字段名来自真实 schema 或标注"新增"
+   - YAGNI：是否包含不必要功能
+   - 验收标准：是否具体可测试
+3. 自审发现问题 → 修改后重新检查
+4. 全部通过 → 进入下一步
+
+### 输出
+design.md 文件路径 + 自审结果
+
+### 注意
+- 自审不通过不要进入下一步
+- 不确定的问题标注「⚠️ 自审存疑」`,
+      outputHint: 'design.md 路径 + 自审结果',
+      optional: false
+    },
+    {
+      name: '用户确认并输出技术方案',
+      prompt: `用户确认设计方案，生成最终技术方案。
+
+### 操作
+1. 展示 design.md 摘要给用户
+2. 请用户选择：✅ 确认 / ✏️ 修改 / ❌ 推翻重来
+3. 确认后：
+   - 将技术方案写入 \`.sillyspec/changes/<变更名>/design.md\`
+   - 包含：架构决策、文件变更清单、数据模型、API 设计、代码风格参照
+   - Git 提交
+
+### 输出
+最终 design.md 路径 + Git commit hash
+
+### 注意
+- 必须等待用户明确确认
+- 禁止在确认前推进到后续阶段
+- 推翻重来回到 Step 6`,
+      outputHint: '最终 design.md 路径 + commit hash',
+      optional: false
+    }
+  ]
+}