sillyspec 3.8.5 → 3.8.7

package/src/init.js

@@ -1,32 +1,55 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, statSync } from 'fs';
-import { join, resolve, dirname, basename } from 'path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync } from 'fs';
+import { join, resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir } from 'os';
-import { checkbox, confirm, input } from '@inquirer/prompts';
-import { ProgressManager } from './progress.js';
+import { checkbox, select, confirm, input } from '@inquirer/prompts';
 import chalk from 'chalk';
+import ora from 'ora';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-
-// ── 递归复制目录 ──
-function copyDirSync(src, dst) {
-  mkdirSync(dst, { recursive: true });
-  for (const entry of readdirSync(src, { withFileTypes: true })) {
-    if (entry.name === 'node_modules' || entry.name === '.git') continue;
-    const srcPath = join(src, entry.name);
-    const dstPath = join(dst, entry.name);
-    if (entry.isDirectory()) {
-      copyDirSync(srcPath, dstPath);
-    } else if (entry.name.endsWith('.md')) {
-      writeFileSync(dstPath, readFileSync(srcPath));
-    }
-  }
-}
+const TEMPLATE_DIR = resolve(__dirname, '..', 'templates');
 
 // ── 元数据映射 ──
 
+const DESCRIPTIONS = {
+  init: '绿地项目初始化 — 深度提问、调研、需求文档、路线图',
+  scan: '代码库扫描 — 支持快速扫描和深度扫描两阶段',
+  explore: '自由思考模式 — 讨论、画图、调研，不写代码',
+  brainstorm: '需求探索 — 结构化头脑风暴，生成设计文档（创建性工作前必用）',
+  plan: '编写实现计划 — 任务拆分与实现路径',
+  execute: '波次执行 — 子代理并行 + 强制 TDD + 两阶段审查',
+  verify: '验证实现 — 对照规范检查 + 测试套件',
+  archive: '归档变更 — 规范沉淀，可追溯',
+  commit: '智能提交 — 自动收集变更信息，生成 commit message',
+  status: '查看项目进度和状态',
+  continue: '自动判断并执行下一步',
+  state: '查看当前工作状态 — 显示 STATE.md 内容',
+
+  quick: '快速任务 — 跳过完整流程，直接做',
+  workspace: '工作区管理 — 初始化、管理多项目工作区，查看子项目状态',
+  export: '导出成功方案为可复用模板',
+};
 
+const ARG_HINTS = {
+  init: '[项目名]',
+  scan: '[可选：指定区域，如 \'api\' 或 \'auth\'] [--deep 深度扫描]',
+  explore: '[探索主题]',
+  brainstorm: '[需求或想法描述]',
+
+  plan: '[计划名]',
+  execute: '[任务编号或 \'all\']',
+  verify: '[可选：指定验证范围]',
+  archive: '[变更名]',
+  commit: '[可选：自定义 commit message]',
+  status: '',
+  continue: '',
+  state: '[可选备注]',
+
+  quick: '[任务描述]',
+  workspace: '[可选：add/remove/status/info]',
+  export: '<change-name> [--to <path>]',
+};
 
 const VALID_TOOLS = ['claude', 'claude_skills', 'cursor', 'openclaw', 'codex', 'gemini', 'opencode'];
 
@@ -40,6 +63,8 @@ const TOOL_LABELS = {
   opencode: 'OpenCode (通过 INSTRUCTIONS.md)',
 };
 
+
+// 指令文件工具：注入规范引用到指令文件
 const INSTRUCTION_TOOLS = ['codex', 'gemini', 'opencode'];
 
 const INSTRUCTION_FILE_MAP = {
@@ -53,16 +78,83 @@ const INJECTION_CONTENT = `## SillySpec — 规范驱动开发
 在执行开发任务时，遵循以下规范：
 
 ### 代码规范
-- 写代码前先读取 \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\`（代码风格）和 \`.sillyspec/docs/<project>/scan/ARCHITECTURE.md\`（架构）
+- 写代码前先读取 \`.sillyspec/codebase/CONVENTIONS.md\`（代码风格）和 \`.sillyspec/codebase/ARCHITECTURE.md\`（架构）
 - 调用已有方法前，用 grep 确认方法存在，不许编造
-- 遵循 \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\` 中的代码风格
+- 遵循 \`.sillyspec/codebase/CONVENTIONS.md\` 中的代码风格
 
 ### 工作流程
-- 读取 \`.sillyspec/.runtime/progress.json\` 确认当前阶段（使用 \`sillyspec progress show\`）
+- 读取 \`.sillyspec/STATE.md\` 确认当前阶段
 - 各阶段产出文件位于 \`.sillyspec/changes/<变更名>/\` 下
+- 详细流程参考模板文件：\`.sillyspec/.templates/\`（brainstorm.md, plan.md, execute.md 等）
 `;
 
-// ── 注入指令文件 ──
+// ── 适配器 ──
+
+function generateClaude(projectDir, name, desc, body, argHint, version) {
+  const outDir = join(projectDir, '.claude', 'commands', 'sillyspec');
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, `${name}.md`),
+`---
+description: ${desc}
+argument-hint: "${argHint}"
+version: "${version}"
+---
+
+${body}`
+  );
+}
+
+function generateClaudeSkills(projectDir, name, desc, body, argHint, version) {
+  const outDir = join(projectDir, '.claude', 'skills', `sillyspec-${name}`);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, 'SKILL.md'),
+`---
+name: sillyspec:${name}
+description: ${desc}
+version: "${version}"
+---
+
+${body}`
+  );
+}
+
+function generateCursor(projectDir, name, desc, body, argHint, version) {
+  const outDir = join(projectDir, '.cursor', 'commands');
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, `sillyspec-${name}.md`),
+`---
+name: /sillyspec-${name}
+id: sillyspec-${name}
+description: ${desc}
+version: "${version}"
+---
+
+${body}`
+  );
+}
+
+function generateOpenclaw(projectDir, name, desc, body, argHint, version) {
+  const outDir = join(projectDir, '.openclaw', 'skills', `sillyspec-${name}`);
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, 'SKILL.md'),
+`---
+name: sillyspec:${name}
+description: ${desc}
+version: "${version}"
+---
+
+${body}`
+  );
+}
+
+const GENERATORS = {
+  claude: generateClaude,
+  claude_skills: generateClaudeSkills,
+  cursor: generateCursor,
+  openclaw: generateOpenclaw,
+};
+
+// ── 指令文件注入 ──
 
 function injectInstructions(tool, projectDir) {
   const fileName = INSTRUCTION_FILE_MAP[tool];
@@ -106,33 +198,22 @@ function isTTY() {
 
 // ── 核心安装逻辑 ──
 
-async function doInstall(projectDir, tools, subprojects = []) {
+async function doInstall(projectDir, tools, isWorkspace, subprojects = []) {
   // 创建基础目录
-  // .sillyspec/projects/    → 项目注册表
-  // .sillyspec/docs/<name>/ → 统一文档中心
-  // .sillyspec/knowledge/   → 跨项目共享知识库
-  // .sillyspec/.runtime/    → progress (gitignored)
-
-  // 注册当前项目到 projects/
-  const projectName = basename(projectDir) || 'project';
-  const projectsDir = join(projectDir, '.sillyspec', 'projects');
-  mkdirSync(projectsDir, { recursive: true });
-  const projectYamlPath = join(projectsDir, `${projectName}.yaml`);
-  if (!existsSync(projectYamlPath)) {
-    writeFileSync(projectYamlPath, `name: ${projectName}\npath: .\nstatus: active\n`);
+  // .sillyspec/codebase/    → scan
+  // .sillyspec/codebase/details/ → scan (deep)
+  // .sillyspec/changes/     → brainstorm/plan
+  // .sillyspec/changes/archive/ → archive
+  // .sillyspec/quicklog/    → quick
+  // .sillyspec/knowledge/   → archive (spec 沉淀)
+  // .sillyspec/.runtime/    → runtime data (gitignored)
+  // (plan 内容已合并到 tasks.md)
+  if (isWorkspace) {
+    mkdirSync(join(projectDir, '.sillyspec', 'shared'), { recursive: true });
+    mkdirSync(join(projectDir, '.sillyspec', 'workspace'), { recursive: true });
   }
 
-  // 创建 docs/<projectName>/scan/ 子目录（代码扫描结果）
-  const scanDir = join(projectDir, '.sillyspec', 'docs', projectName, 'scan');
-  mkdirSync(scanDir, { recursive: true });
-  const gitkeepPath = join(scanDir, '.gitkeep');
-  if (!existsSync(gitkeepPath)) writeFileSync(gitkeepPath, '');
-
-  // 创建 shared/workspace 目录
-  mkdirSync(join(projectDir, '.sillyspec', 'shared'), { recursive: true });
-  mkdirSync(join(projectDir, '.sillyspec', 'workspace'), { recursive: true });
-
-  // 创建知识库骨架
+  // 创建知识库骨架（所有模式）
   const knowledgeDir = join(projectDir, '.sillyspec', 'knowledge');
   mkdirSync(knowledgeDir, { recursive: true });
   const indexPath = join(knowledgeDir, 'INDEX.md');
@@ -150,13 +231,6 @@ async function doInstall(projectDir, tools, subprojects = []) {
     mkdirSync(join(runtimeDir, sub), { recursive: true });
   }
 
-  // 创建初始 progress.json
-  const progressPath = join(runtimeDir, 'progress.json');
-  if (!existsSync(progressPath)) {
-    const pm = new ProgressManager();
-    pm.init(projectDir);
-  }
-
   // 创建初始 user-inputs.md
   const inputsPath = join(runtimeDir, 'user-inputs.md');
   if (!existsSync(inputsPath)) {
@@ -164,7 +238,7 @@ async function doInstall(projectDir, tools, subprojects = []) {
   }
 
   const gitignorePath = join(projectDir, '.gitignore');
-  const ignoreRules = ['.sillyspec/codebase/SCAN-RAW.md', '.sillyspec/local.yaml', '.sillyspec/.runtime/'];
+  const ignoreRules = ['.sillyspec/STATE.md', '.sillyspec/codebase/SCAN-RAW.md', '.sillyspec/local.yaml', '.sillyspec/.runtime/'];
   if (existsSync(gitignorePath)) {
     const content = readFileSync(gitignorePath, 'utf8');
     let updated = content.trimEnd();
@@ -178,38 +252,83 @@ async function doInstall(projectDir, tools, subprojects = []) {
     writeFileSync(gitignorePath, ignoreRules.join('\n') + '\n');
   }
 
-  // 注入指令文件（codex/gemini/opencode）
+  // 生成 slash command 文件
+  const templateFiles = readdirSync(TEMPLATE_DIR).filter(f => f.endsWith('.md'));
+  let count = 0;
+
   for (let i = 0; i < tools.length; i++) {
     const toolName = tools[i];
+    const label = TOOL_LABELS[toolName] || toolName;
+
     if (INSTRUCTION_TOOLS.includes(toolName)) {
-      injectInstructions(toolName, projectDir);
+      const spinner = ora(`安装 ${label}... (${i + 1}/${tools.length})`).start();
+      try {
+        injectInstructions(toolName, projectDir);
+        // 复制模板文件到 .sillyspec/.templates/
+        const templatesSourceDir = join(TEMPLATE_DIR);
+        const templatesDir = join(projectDir, '.sillyspec', '.templates');
+        if (!existsSync(templatesDir)) {
+          mkdirSync(templatesDir, { recursive: true });
+          for (const file of readdirSync(templatesSourceDir)) {
+            if (file.endsWith('.md')) {
+              copyFileSync(join(templatesSourceDir, file), join(templatesDir, file));
+            }
+          }
+        }
+        spinner.succeed(`${label} 完成`);
+        count++;
+      } catch (err) {
+        spinner.fail(`${label} 失败: ${err.message}`);
+        throw err;
+      }
+      continue;
+    }
+
+    const spinner = ora(`安装 ${label}... (${i + 1}/${tools.length})`).start();
+    try {
+      const gen = GENERATORS[toolName];
+      const ver = getVersion();
+      for (const file of templateFiles) {
+        const name = file.replace('.md', '');
+        const desc = DESCRIPTIONS[name] || `SillySpec ${name}`;
+        const argHint = ARG_HINTS[name] || '';
+        const body = readFileSync(join(TEMPLATE_DIR, file), 'utf8');
+        gen(projectDir, name, desc, body, argHint, ver);
+        count++;
+      }
+      spinner.succeed(`${label} 完成`);
+    } catch (err) {
+      spinner.fail(`${label} 失败: ${err.message}`);
+      throw err;
     }
   }
 
-  // 复制 skills 到 .claude/skills/（给 Claude Code 使用）
-  const claudeSkillsDir = join(projectDir, '.claude', 'skills');
-  // 优先从 npm 包自带位置复制，其次从 ~/.agents/skills/
-  const npmSkillsDir = join(__dirname, '..', '.claude', 'skills');
-  const localSkillsDir = join(homedir(), '.agents', 'skills');
-  const skillsSource = existsSync(npmSkillsDir) ? npmSkillsDir : existsSync(localSkillsDir) ? localSkillsDir : null;
-  if (skillsSource) {
-    const sillyspecSkills = readdirSync(skillsSource).filter(f => f.startsWith('sillyspec-') && statSync(join(skillsSource, f)).isDirectory());
-    if (sillyspecSkills.length > 0) {
-      mkdirSync(claudeSkillsDir, { recursive: true });
-      for (const skill of sillyspecSkills) {
-        copyDirSync(join(skillsSource, skill), join(claudeSkillsDir, skill));
+  // 工作区子项目配置 → projects/*.yaml
+  if (isWorkspace && subprojects.length > 0) {
+    const projectsDir = join(projectDir, '.sillyspec', 'projects');
+    mkdirSync(projectsDir, { recursive: true });
+    for (const p of subprojects) {
+      const pFile = join(projectsDir, `${p.name}.yaml`);
+      if (!existsSync(pFile)) {
+        writeFileSync(pFile,
+`# ${p.name}
+name: ${p.name}
+path: ${p.path}
+role: ${p.role || p.name}${p.repo ? `\nrepo: ${p.repo}` : ''}
+`
+        );
       }
-      console.log(chalk.green('    ✓ Claude Code skills 已同步 (' + sillyspecSkills.length + ' 个)'));
     }
-  } else {
-    console.log(chalk.yellow('    ⚠ 未找到 skills 目录，跳过 Claude Code skills 同步'));
   }
+
+  return count;
 }
 
 // ── 安装完成总结 ──
 
-function showSummary(version, tools) {
+function showSummary(version, tools, isWorkspace, count) {
   const toolLabels = tools.map(t => TOOL_LABELS[t] || t);
+  const mode = isWorkspace ? '多项目工作区' : '单项目';
 
   console.log('');
   console.log(chalk.green('  ═══════════════════════════════════════'));
@@ -217,13 +336,20 @@ function showSummary(version, tools) {
   console.log(chalk.green('  ═══════════════════════════════════════'));
   console.log('');
   console.log(`  已安装工具: ${chalk.cyan(toolLabels.join(', '))}`);
+  console.log(`  模式: ${chalk.yellow(mode)}`);
+  console.log('');
+  console.log(`  📄 ${count} 个命令已就绪`);
   console.log('  📁 .sillyspec/ — 项目规范目录');
   console.log('');
-  console.log('  下一步：使用 AI 技能开始工作');
-  console.log('    OpenClaw:    ' + chalk.bold('/sillyspec:brainstorm'));
-  console.log('    Claude Code: ' + chalk.bold('/sillyspec:brainstorm'));
+  console.log('  入口选择：');
+  console.log('    全新项目：' + chalk.bold('/sillyspec:init'));
+  console.log('    已有代码：' + chalk.bold('/sillyspec:scan'));
+  console.log('    自由思考：' + chalk.bold('/sillyspec:explore "你的想法"'));
+  console.log('');
+  console.log(chalk.gray('  重启你的 AI 工具以使 slash commands 生效。'));
   console.log('');
   console.log(chalk.dim('  💡 推荐安装 MCP 工具增强 AI 能力：sillyspec setup'));
+  console.log(chalk.dim('     Context7 — 查最新文档 | grep.app — 搜开源实现 | Chrome DevTools — 浏览器自动化'));
   console.log('');
 }
 
@@ -241,7 +367,7 @@ export function getVersion() {
 // ── 主命令 ──
 
 export async function cmdInit(projectDir, options = {}) {
-  const { tool, interactive } = options;
+  const { tool, workspace, interactive } = options;
   const version = getVersion();
 
   // ── 交互式模式（--interactive 或 -i）──
@@ -273,11 +399,20 @@ export async function cmdInit(projectDir, options = {}) {
       validate: (answer) => answer.length > 0 || '至少选择一个工具',
     });
 
-    // 子项目引导（始终执行）
+    // 工作区模式
+    const isWorkspace = await select({
+      message: '选择项目模式',
+      choices: [
+        { name: '单项目模式', value: 'false' },
+        { name: '多项目工作区', value: 'true' },
+      ],
+    }) === 'true';
+
+    // 工作区子项目引导
     let subprojects = [];
-    {
+    if (isWorkspace) {
       console.log('');
-      console.log(chalk.yellow('📋 添加子项目'));
+      console.log(chalk.yellow('📋 工作区模式 — 添加子项目'));
       console.log(chalk.dim('   子项目是工作区中的独立项目目录（如 frontend/、backend/）'));
       console.log('');
 
@@ -340,8 +475,8 @@ export async function cmdInit(projectDir, options = {}) {
     }
 
     console.log('');
-    await doInstall(projectDir, selectedTools, subprojects);
-    showSummary(version, selectedTools);
+    const count = await doInstall(projectDir, selectedTools, isWorkspace, subprojects);
+    showSummary(version, selectedTools, isWorkspace, count);
     return;
   }
 
@@ -359,17 +494,23 @@ export async function cmdInit(projectDir, options = {}) {
     tools = detectTools(projectDir);
   }
 
-  await doInstall(projectDir, tools);
+  const count = await doInstall(projectDir, tools, !!workspace);
 
   console.log('');
   console.log(chalk.green(`  ✅ SillySpec v${version} 安装完成！`));
   console.log('');
+  console.log(`  📄 ${count} 个命令已就绪`);
   console.log('  📁 .sillyspec/ — 项目规范目录');
   console.log('');
-  console.log('  下一步：使用 AI 技能开始工作');
-  console.log(`    OpenClaw:    ${chalk.bold('/sillyspec:brainstorm')}`);
-  console.log(`    Claude Code: ${chalk.bold('/sillyspec:brainstorm')}`);
+  console.log('  下一步：');
+  console.log(`    全新项目 → ${chalk.bold('/sillyspec:init')}`);
+  console.log(`    已有代码 → ${chalk.bold('/sillyspec:scan')}`);
+  console.log(`    自由探索 → ${chalk.bold('/sillyspec:explore "你的想法"')}`);
+  if (workspace) {
+    console.log(`    管理子项目 → ${chalk.bold('/sillyspec:workspace add')}`);
+  }
   console.log('');
   console.log(chalk.dim('  💡 增强能力：sillyspec setup（安装 MCP 工具）'));
+  console.log(chalk.dim('  💡 完整配置：sillyspec init --interactive'));
   console.log('');
 }

package/src/setup.js

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

package/templates/archive.md

@@ -0,0 +1,120 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 核心约束（必须遵守）
+- ❌ 未经验证就归档（必须先确认验证通过）
+- ❌ 未勾选的 checkbox 未告知用户就归档
+- ❌ 归档后留下活跃变更的残留状态
+- ❌ 覆盖已存在的归档目录
+
+## 变更名称
+$ARGUMENTS
+
+---
+
+## 流程
+
+### 1. 前置检查（门禁）
+
+读取 `.sillyspec/changes/<change-name>/` 下所有必要文件，逐项检查：
+
+- [ ] **文件完整性：** 检查 `design.md` 是否存在，缺失则警告
+- [ ] **任务完成度：** 读取 `tasks.md`，统计已完成/未完成任务数。**有未完成的 → 用 AskUserQuestion 询问：**
+  - ① 继续归档（未完成任务将被标记完成）
+  - ② 取消，回去完成任务
+
+> 任一门禁不通过且用户选择取消 → 终止流程。
+
+### 2. 展示归档清单
+
+展示即将归档的内容摘要：
+- 变更目录名
+- 包含的文件列表
+- 任务完成统计（✅ 已完成 / ⬜ 未完成）
+- 一句话总结本次变更
+- quicklog 修改记录（如有 `.sillyspec/changes/<change-name>/quicklog/` 目录）
+
+### 3. Spec 沉淀
+
+将 `.sillyspec/changes/<change-name>/` 下的设计文档**复制到 `.sillyspec/knowledge/` 主目录**，确保已完成的设计规范可被后续变更参考。如目标已存在同名文件则跳过并提示。
+
+### 4. 用户确认
+
+用 AskUserQuestion 让用户确认：
+- ① 确认归档
+- ② 取消
+
+### 4.5 生成归档摘要
+
+在变更目录下自动生成 `SUMMARY.md`：
+
+```markdown
+# <变更名> 归档
+
+- 创建：YYYY-MM-DD
+- 完成：YYYY-MM-DD
+- 涉及阶段：brainstorm → plan → execute → verify
+
+## 关键决策
+- （从 design.md 提取 3-5 条核心决策）
+
+## 产出文件
+- design.md — 设计文档
+- tasks.md — 任务清单
+- quicklog/ — 关联 quick 修改（N次）
+  - quick1: 描述
+  - quick2: 描述
+
+## 代码变更统计
+- 新增 X 文件，修改 Y 文件，删除 Z 文件
+- 详见 CHANGELOG.md
+```
+
+在变更目录下自动生成 `CHANGELOG.md`：
+
+```bash
+# 收集该变更相关的 git commit（按变更名过滤或按时间范围）
+git log --oneline --no-merges -- .sillyspec/changes/<change-name>/ 2>/dev/null
+# 以及变更目录创建后的所有 commit
+git log --oneline --no-merges --since="<创建时间>" -- "*.ts" "*.js" "*.vue" "*.java" 2>/dev/null
+```
+
+写入 CHANGELOG.md，格式：
+```markdown
+# <变更名> 变更日志
+
+## brainstorm 阶段
+- (相关 commit)
+
+## plan 阶段
+- (相关 commit)
+
+## execute 阶段
+- (相关 commit)
+
+## quick 修改
+- (相关 commit)
+
+## verify 阶段
+- (相关 commit)
+```
+
+### 5. 执行归档
+
+- 目标路径：`.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/`
+- **检查目标路径是否已存在**，存在则中止并报错，防止覆盖
+- 移动变更目录到归档路径
+
+### 6. 归档后更新
+
+- **tasks.md：** 确保所有 checkbox 都已勾选 `[x]`
+- **ROADMAP.md**（如存在）：标记对应 Phase 已完成
+- **Git 暂存：** `git add .sillyspec/`
+
+**工作区模式下：** 如果变更属于某个子项目，cd 到子项目目录执行 git add。工作区根目录无 git 则跳过。
+
+💡 归档产出已暂存。准备好后用 `/sillyspec:commit` 提交。
+
+### 最后说：
+
+> ✅ 变更 `<change-name>` 已归档到 `archive/YYYY-MM-DD-<change-name>/`。继续：`/sillyspec:brainstorm "新想法"`