sillyspec 3.18.2 → 3.18.4

package/src/index.js

@@ -31,7 +31,9 @@ SillySpec CLI — 规范驱动开发工具包
     --done --output "..."      完成当前步骤
     --skip                     跳过可选步骤
     --status                   查看阶段进度
-    --reset                    重置阶段
+    --reset                    重置阶段（从头开始）
+    --reopen                   重新打开已完成阶段进入修订模式
+    --from-step <index|name>   配合 --reopen：从指定步骤开始修订
     --change <name>            设置当前变更名
     --spec-dir <path>          指定规范目录（默认 <项目>/.sillyspec）
     --runtime-root <path>       平台模式：运行时产物根路径
@@ -43,6 +45,10 @@ SillySpec CLI — 规范驱动开发工具包
     scan, brainstorm, plan, execute, verify, archive
     quick, explore, status, doctor
 
+  Revision mode:
+    已完成阶段不能直接重跑。使用 --reopen --from-step 进入受控修订。
+    重开会使下游阶段自动标记为 stale，但不修改已有产物文件。
+
   sillyspec progress <cmd>     进度记录（轻量，不强制顺序）
     init                       初始化项目数据库
     show                       查看当前进度
@@ -50,6 +56,8 @@ SillySpec CLI — 规范驱动开发工具包
     add-step <stage> <name>    添加步骤
     update-step <s> <n> --status <st> [--output <t>]
     complete-stage <stage>     标记阶段完成
+    check                      状态一致性检查（只报告，不修复）
+    repair [--apply]           修复状态元数据（默认 dry-run，--apply 才修改）
     validate                   校验并修复
     reset [--stage X]          重置进度
 
@@ -174,6 +182,14 @@ async function main() {
         case 'show':
           pm.show(dir, progChangeName);
           break;
+        case 'check':
+          await pm.checkConsistency(dir, progChangeName);
+          break;
+        case 'repair': {
+          const repairApply = filteredArgs.includes('--apply');
+          await pm.repairConsistency(dir, { apply: repairApply, changeName: progChangeName });
+          break;
+        }
         case 'validate':
           await pm.validate(dir, progChangeName);
           break;
@@ -313,7 +329,8 @@ SillySpec worktree — git worktree 隔离管理
   sillyspec worktree create <change-name> [--base <branch>]   创建隔离 worktree
   sillyspec worktree apply <change-name> [--check-only]        校验并应用变更到主工作区
   sillyspec worktree list                                      列出所有活跃 worktree
-  sillyspec worktree cleanup <change-name>                      强制清理 worktree
+  sillyspec worktree cleanup <change-name> [--force]           强制清理 worktree
+  sillyspec worktree doctor [--fix] [--stale-hours N]          健康检查 + 修复
 
 选项:
   --base <branch>       create: 指定基础分支（默认当前 HEAD）
@@ -413,11 +430,13 @@ SillySpec worktree — git worktree 隔离管理
           const forceFlag = args.includes('--force');
           try {
             const result = wm.cleanup(wtName, { force: forceFlag });
-            if (result.result === 'cleaned') {
+            if (result.result === 'cleaned' || result.result === 'force-cleaned') {
               console.log(`✅ worktree 已清理: ${wtName} (mode: ${result.mode})`);
-            } else if (result.result === 'force-cleaned') {
-              console.log(`⚠️  worktree 已强制清理: ${wtName} (mode: ${result.mode})`);
-              console.log(`   原因: git worktree remove 失败，通过直接删除目录完成`);
+              if (result.details?.length > 0) {
+                for (const d of result.details) {
+                  if (d.startsWith('⚠️')) console.log(`   ${d}`);
+                }
+              }
             } else if (result.result === 'skipped') {
               console.log(`⏭️  worktree 跳过清理: ${wtName} (mode: ${result.mode})`);
               console.log(`   原因: in-place 模式没有隔离目录需要清理`);
@@ -430,6 +449,34 @@ SillySpec worktree — git worktree 隔离管理
           }
           break;
         }
+        case 'doctor': {
+          const fixFlag = args.includes('--fix');
+          const staleIdx = args.indexOf('--stale-hours');
+          const staleHours = staleIdx !== -1 && args[staleIdx + 1] ? parseInt(args[staleIdx + 1], 10) : 24;
+          const diag = wm.doctor({ fix: fixFlag, staleHours });
+          if (diag.issues.length === 0) {
+            console.log('✅ worktree 健康检查通过，无异常');
+          } else {
+            console.log(`🔍 发现 ${diag.issues.length} 个问题：\n`);
+            for (const issue of diag.issues) {
+              const icon = issue.fixable ? '⚠️' : '❌';
+              console.log(`  ${icon} [${issue.type}] ${issue.name}: ${issue.detail}`);
+            }
+            if (fixFlag) {
+              console.log(`\n🔧 修复完成：`);
+              for (const f of diag.fixed) console.log(`  ✅ ${f}`);
+              if (diag.unfixable.length > 0) {
+                for (const u of diag.unfixable) console.log(`  ❌ ${u}`);
+              }
+              if (diag.fixed.length === 0 && diag.unfixable.length === 0) {
+                console.log('  无需修复');
+              }
+            } else {
+              console.log(`\n💡 运行 sillyspec worktree doctor --fix 自动修复`);
+            }
+          }
+          break;
+        }
         default:
           console.error(`❌ 未知子命令: worktree ${wtSubCmd}`);
           console.log('   运行 sillyspec worktree --help 查看帮助');

package/src/init.js

@@ -108,12 +108,39 @@ async function doInstall(projectDir, tools, subprojects = [], specDir = null) {
   // projectDir: 源码项目根目录（用于工具检测、指令注入、.gitignore）
   const spec = specDir || join(projectDir, '.sillyspec');
 
-  // 外部 specDir 时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）
+  // 外部 specDir 时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
+  // ⚠️ 必须保护真实资产：若本地 .sillyspec 含 changes/（非空）、projects/（非空）
+  // 或 sillyspec.db（进度库），说明该项目本身就用 SillySpec 管理，整体删除会丢资产。
+  // 此时只清运行时残留，拒绝整删；确无资产时才视为旧残留清理。
   const legacyDir = join(projectDir, '.sillyspec');
   if (specDir && existsSync(legacyDir)) {
-    try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
-    if (!existsSync(legacyDir)) console.log('🧹 已清理旧版本残留的源码 .sillyspec/ 目录');
-    else console.error('⚠️ 清理残留 .sillyspec/ 失败');
+    let hasChanges = false;
+    try {
+      const changesDir = join(legacyDir, 'changes');
+      if (existsSync(changesDir)) hasChanges = readdirSync(changesDir).length > 0;
+    } catch {}
+    let hasProjects = false;
+    try {
+      const projectsDir = join(legacyDir, 'projects');
+      if (existsSync(projectsDir)) hasProjects = readdirSync(projectsDir).length > 0;
+    } catch {}
+    const hasDb = existsSync(join(legacyDir, 'sillyspec.db'));
+
+    if (hasChanges || hasProjects || hasDb) {
+      // 真实资产存在：拒绝整体删除，仅清理运行时残留
+      console.error('❌ [sillyspec] 拒绝删除源码目录的 .sillyspec/：检测到真实资产（changes/、projects/ 或 sillyspec.db）。');
+      console.error('   该项目似乎本身就用 SillySpec 管理。如需改用外部 spec 目录，请先手动迁移/备份。');
+      console.error('   本次仅清理运行时残留（.runtime/、local.yaml、codebase/）。');
+      for (const residue of ['.runtime', 'local.yaml', 'codebase']) {
+        const p = join(legacyDir, residue);
+        if (existsSync(p)) { try { rmSync(p, { recursive: true, force: true }) } catch {} }
+      }
+    } else {
+      // 无真实资产：确属旧版本残留，安全删除
+      try { rmSync(legacyDir, { recursive: true, force: true }) } catch {}
+      if (!existsSync(legacyDir)) console.log('🧹 已清理旧版本残留的源码 .sillyspec/ 目录');
+      else console.error('⚠️ 清理残留 .sillyspec/ 失败');
+    }
   }
 
   // 创建基础目录

package/src/knowledge-match.js

@@ -0,0 +1,130 @@
+/**
+ * knowledge-match.js — knowledge 关键词匹配引擎
+ * 从 INDEX.md 解析知识条目，按任务上下文匹配并生成 hit report
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+/**
+ * 从 INDEX.md 解析所有知识条目
+ * @param {string} indexDir - knowledge 目录路径
+ * @returns {{ category: string, keywords: string[], file: string, anchor: string, display: string, line: string }[]}
+ */
+export function parseKnowledgeIndex(indexDir) {
+  const indexPath = join(indexDir, 'INDEX.md')
+  if (!existsSync(indexPath)) return []
+
+  const content = readFileSync(indexPath, 'utf8')
+  const entries = []
+  let currentCategory = ''
+
+  for (const line of content.split('\n')) {
+    // 匹配 ## Category 行
+    const catMatch = line.match(/^##\s+(.+)/)
+    if (catMatch) {
+      currentCategory = catMatch[1].trim()
+      continue
+    }
+
+    // 匹配条目行：- 关键词1|关键词2 → [显示名](文件名#锚点)
+    const entryMatch = line.match(/^-\s+(.+?)\s*→\s*\[(.+?)\]\(([^#)]+)(?:#([^)]+))?\)/)
+    if (entryMatch) {
+      const keywords = entryMatch[1].split('|').map(k => k.trim()).filter(Boolean)
+      const display = entryMatch[2].trim()
+      const file = entryMatch[3].trim()
+      const anchor = entryMatch[4] ? entryMatch[4].trim() : ''
+      entries.push({ category: currentCategory, keywords, file, anchor, display, line })
+    }
+  }
+
+  return entries
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * 单个关键词是否命中上下文。
+ * - 过短关键词（<2 字符）视为噪音，不参与匹配
+ * - 非 ASCII（中文等）用子串匹配
+ * - ASCII 关键词用词边界匹配，避免子串误命中（如 "DB" 不命中 "dashboard"）
+ */
+function keywordMatchesContext(keyword, contextLower) {
+  const kw = keyword.toLowerCase().trim()
+  if (kw.length < 2) return false
+  if (/[^\x00-\x7f]/.test(kw)) return contextLower.includes(kw)
+  return new RegExp(`(^|[^a-z0-9])${escapeRegex(kw)}([^a-z0-9]|$)`).test(contextLower)
+}
+
+/**
+ * 用任务上下文匹配知识条目
+ * @param {string} indexDir - knowledge 目录路径
+ * @param {string} taskContext - 任务上下文（task 名称 + 描述，用于关键词匹配）
+ * @returns {{ matched: boolean, entries: Array, report: string, json: object }}
+ */
+export function matchKnowledge(indexDir, taskContext) {
+  const indexPath = join(indexDir, 'INDEX.md')
+
+  // INDEX.md 不存在
+  if (!existsSync(indexPath)) {
+    return {
+      matched: false,
+      entries: [],
+      report: 'Status: no matches (INDEX.md not found)',
+      json: { matched: false, entry_count: 0, entries: [] }
+    }
+  }
+
+  const allEntries = parseKnowledgeIndex(indexDir)
+  if (allEntries.length === 0 || !taskContext) {
+    return {
+      matched: false,
+      entries: [],
+      report: 'Status: no matches',
+      json: { matched: false, entry_count: 0, entries: [] }
+    }
+  }
+
+  const contextLower = taskContext.toLowerCase()
+  const matched = allEntries.filter(entry => {
+    return entry.keywords.some(kw => keywordMatchesContext(kw, contextLower))
+  })
+
+  if (matched.length === 0) {
+    return {
+      matched: false,
+      entries: [],
+      report: 'Status: no matches',
+      json: { matched: false, entry_count: 0, entries: [] }
+    }
+  }
+
+  const sources = matched.map(e => {
+    const base = e.anchor ? `${e.file}#${e.anchor}` : e.file
+    return ` - ${base}`
+  }).join('\n')
+
+  const report = [
+    'Knowledge Context',
+    '─────────────────',
+    `Status: matched`,
+    `Entries: ${matched.length}`,
+    'Sources:',
+    sources
+  ].join('\n')
+
+  const json = {
+    matched: true,
+    entry_count: matched.length,
+    entries: matched.map(e => ({
+      file: e.file,
+      anchor: e.anchor,
+      keywords: e.keywords,
+      category: e.category
+    }))
+  }
+
+  return { matched: true, entries: matched, report, json }
+}