sillyspec 3.17.8 → 3.17.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.17.8",
+  "version": "3.17.10",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/modules.js

@@ -47,7 +47,18 @@ function parseModuleCardFrontmatter(content) {
 }
 
 /**
- * rebuild: 从模块卡片 + 源码重建 _module-map.yaml
+ * 从模块卡片 + 源码重建 _module-map.yaml
+ *
+ * schema_version 2 扩展字段：
+ *   - role: 模块职责描述
+ *   - core_files: 核心源文件列表
+ *   - test_files: 测试文件列表
+ *   - entrypoints: 入口点
+ *   - depends_on: 依赖的其他模块
+ *   - used_by: 被哪些模块使用
+ *   - risk_level: 风险等级（low/medium/high）
+ *   - verify_commands: 验证命令（build/test/lint）
+ *   - related_docs: 关联文档路径
  */
 export async function rebuildModuleMap(cwd) {
   const mapPath = findModuleMapPath(cwd);
@@ -107,10 +118,12 @@ export async function rebuildModuleMap(cwd) {
     headCommit = execSync('git rev-parse --short HEAD', { cwd, encoding: 'utf8', timeout: 5000 }).trim();
   } catch { /* ignore */ }
 
-  let yaml = `schema_version: 1\n`;
+  let yaml = `schema_version: 2\n`;
   yaml += `generated_at: ${now}\n`;
   yaml += `generator: sillyspec-modules-rebuild\n`;
   if (headCommit) yaml += `source_commit: ${headCommit}\n`;
+  yaml += `\n# Module Context Index — 机器可读的模块上下文索引\n`;
+  yaml += `# scan 阶段自动生成，brainstorm/plan/execute 阶段按任务命中模块精准注入上下文\n`;
   yaml += `\nmodules:\n`;
 
   // 合并：已有映射 + 新卡片
@@ -121,13 +134,31 @@ export async function rebuildModuleMap(cwd) {
 
   for (const moduleId of allModuleIds) {
     const card = cards.find(c => c.moduleId === moduleId);
+    const cardContent = card ? readFileSync(join(modulesDir, card.filename), 'utf8') : '';
+
+    // 从模块卡片提取 context index 字段
+    const role = extractSection(cardContent, '定位') || '';
+    const contract = extractSection(cardContent, '契约摘要') || '';
+    const logic = extractSection(cardContent, '关键逻辑') || '';
+    const notes = extractSection(cardContent, '注意事项') || '';
+
     yaml += `  ${moduleId}:\n`;
     yaml += `    status: active\n`;
     if (card) yaml += `    doc: modules/${card.filename}\n`;
     else yaml += `    doc: modules/${moduleId}.md\n`;
-    // 保留已有 _module-map.yaml 中的 paths 等字段（如果有的话）
     yaml += `    needs_review: false\n`;
     yaml += `    review_reasons: []\n`;
+    // context index 字段（v2）
+    if (role) yaml += `    role: "${escapeYamlString(role)}"\n`;
+    // core_files / test_files / entrypoints 从已有 _module-map 保留，或从卡片文件名推导
+    const existingPaths = existingModules[moduleId]?.paths || [];
+    if (existingPaths.length > 0) {
+      yaml += `    core_files:\n`;
+      for (const p of existingPaths) yaml += `      - ${p}\n`;
+    }
+    if (card) yaml += `    verify_commands: []\n`;
+    yaml += `    risk_level: low\n`;
+    if (contract || logic) yaml += `    related_docs: []\n`;
     yaml += `\n`;
   }
 
@@ -138,6 +169,7 @@ export async function rebuildModuleMap(cwd) {
     console.log(`   - ${id}`);
   }
   console.log(`\n⚠️  注意：rebuild 只重建骨架。tags/entrypoints/main_symbols/depends_on/used_by 需要重新运行 scan 或手动补充。`);
+  console.log(`ℹ️  schema 已升级到 v2，支持 role/core_files/test_files/entrypoints/depends_on/risk_level/verify_commands 等字段。`);
 }
 
 /**
@@ -163,13 +195,17 @@ export async function showModuleStatus(cwd) {
     const moduleMatch = line.match(/^  ([a-zA-Z0-9_-]+):$/);
     if (moduleMatch) {
       if (currentModule) modules.push(currentModule);
-      currentModule = { id: moduleMatch[1], hasTags: false, hasEntryPoints: false, hasDepends: false, needsReview: false };
+      currentModule = { id: moduleMatch[1], hasTags: false, hasEntryPoints: false, hasDepends: false, needsReview: false, hasRole: false, hasCoreFiles: false, hasRisk: false, hasVerify: false };
     }
     if (currentModule) {
       if (line.includes('tags:')) currentModule.hasTags = true;
       if (line.includes('entrypoints:')) currentModule.hasEntryPoints = true;
       if (line.includes('depends_on:')) currentModule.hasDepends = true;
       if (line.includes('needs_review: true')) { currentModule.needsReview = true; needsReview = true; }
+      if (line.includes('role:')) currentModule.hasRole = true;
+      if (line.includes('core_files:')) currentModule.hasCoreFiles = true;
+      if (line.includes('risk_level:')) currentModule.hasRisk = true;
+      if (line.includes('verify_commands:')) currentModule.hasVerify = true;
     }
   }
   if (currentModule) modules.push(currentModule);
@@ -178,14 +214,18 @@ export async function showModuleStatus(cwd) {
   console.log(`模块数量：${modules.length}\n`);
 
   const maxId = Math.max(5, ...modules.map(m => m.id.length));
-  console.log(`  ${'模块'.padEnd(maxId)}  tags  entry  deps  review`);
-  console.log(`  ${'─'.repeat(maxId)}  ────  ─────  ────  ──────`);
+  console.log(`  ${'模块'.padEnd(maxId)}  tags  entry  deps  role  core  risk  review`);
+  console.log(`  ${''.padEnd(maxId, '─')}  ────  ─────  ────  ────  ────  ────  ──────`);
   for (const m of modules) {
     const tags = m.hasTags ? '✅' : '⬜';
     const entry = m.hasEntryPoints ? '✅' : '⬜';
     const deps = m.hasDepends ? '✅' : '⬜';
+    const role = m.hasRole ? '✅' : '⬜';
+    const core = m.hasCoreFiles ? '✅' : '⬜';
+    const risk = m.hasRisk ? '✅' : '⬜';
+    const verify = m.hasVerify ? '✅' : '⬜';
     const review = m.needsReview ? '⚠️' : '✅';
-    console.log(`  ${m.id.padEnd(maxId)}  ${tags}     ${entry}     ${deps}     ${review}`);
+    console.log(`  ${m.id.padEnd(maxId)}  ${tags}     ${entry}     ${deps}     ${role}     ${core}     ${risk}     ${verify}     ${review}`);
   }
 
   if (needsReview) {
@@ -194,7 +234,22 @@ export async function showModuleStatus(cwd) {
 }
 
 /**
- * 从 _module-map.yaml 聚合生成 dependencies.md
+ * 从模块卡片提取指定 section 的内容
+ */
+function extractSection(content, sectionName) {
+  const match = content.match(new RegExp(`## ${escapeRegExp(sectionName)}\\n([\\s\\S]*?)(?=\\n##|$)`));
+  return match ? match[1].trim().split('\n')[0] : '';  // 只取第一行作为摘要
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function escapeYamlString(s) {
+  return s.replace(/"/g, '\\"').replace(/\n/g, ' ').slice(0, 200);  // 截断避免过长
+}
+
+/**
  */
 export async function generateDependenciesMd(cwd) {
   const mapPath = findModuleMapPath(cwd);

package/src/run.js

@@ -64,6 +64,149 @@ import { buildExecuteSteps } from './stages/execute.js'
 import { buildPlanSteps } from './stages/plan.js'
 import { formatExecuteSummary } from './worktree-apply.js'
 
+/**
+ * 从 _module-map.yaml 读取模块上下文索引
+ * 用于 brainstorm/plan/execute 阶段按任务命中模块精准注入上下文
+ *
+ * @param {string} specBase - 规范目录（.sillyspec 或 specRoot）
+ * @param {string} projectName - 项目名
+ * @returns {object|null} 解析后的模块索引，null 表示无索引
+ */
+function loadModuleContextIndex(specBase, projectName) {
+  try {
+    const { existsSync, readFileSync } = require('fs')
+    const { join } = require('path')
+    const mapPath = join(specBase, 'docs', projectName, 'modules', '_module-map.yaml')
+    if (!existsSync(mapPath)) return null
+    const content = readFileSync(mapPath, 'utf8')
+    return parseModuleMapSimple(content)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 根据 AI 输出的任务描述，匹配相关模块并生成上下文注入文本
+ * 匹配策略：模块 id / role / doc 路径中的关键词
+ *
+ * @param {string} taskDescription - 任务描述（来自 plan.md / step prompt / outputText）
+ * @param {object} moduleIndex - loadModuleContextIndex 返回值
+ * @param {string} specBase - 规范目录
+ * @param {string} projectName - 项目名
+ * @returns {string} 上下文注入文本，空字符串表示无匹配模块
+ */
+function buildModuleContextInjection(taskDescription, moduleIndex, specBase, projectName) {
+  if (!moduleIndex || !taskDescription) return ''
+  const { existsSync } = require('fs')
+  const { join } = require('path')
+
+  const taskLower = taskDescription.toLowerCase()
+  const matched = []
+
+  for (const [moduleId, data] of Object.entries(moduleIndex)) {
+    let score = 0
+    let matchReasons = []
+    // 模块 id 匹配
+    if (taskLower.includes(moduleId.toLowerCase())) { score += 3; matchReasons.push(`id:${moduleId}`) }
+    // role 描述匹配
+    if (data.role && taskLower.includes(data.role.toLowerCase())) { score += 2; matchReasons.push('role') }
+    // core_files 路径匹配
+    const coreFiles = data.paths || data.core_files || []
+    for (const p of coreFiles) {
+      if (taskLower.includes(p.toLowerCase())) { score += 1; matchReasons.push(`file:${p}`); break }
+    }
+    if (score > 0) matched.push({ moduleId, data, score, matchReasons })
+  }
+
+  if (matched.length === 0) return ''
+
+  matched.sort((a, b) => b.score - a.score)
+
+  let injection = '\n### 📦 模块上下文（按相关性排序，来自 Module Context Index）\n\n'
+  injection += `> 以下模块上下文由 scan 阶段生成的 _module-map.yaml 自动匹配。\n`
+  injection += `> Matched modules: ${matched.map(m => m.moduleId).join(', ')}\n`
+  injection += `> Reasons: ${matched.map(m => m.matchReasons.join(', ')).join('; ')}\n\n`
+
+  for (const { moduleId, data } of matched) {
+    injection += `#### ${moduleId}\n`
+    if (data.role) injection += `- **职责**: ${String(data.role).slice(0, 100)}\n`
+    const riskLevel = data.risk_level || 'medium'
+    injection += `- **风险等级**: ${riskLevel}\n`
+    const coreFiles = data.paths || data.core_files || []
+    if (coreFiles.length > 0) injection += `- **核心文件**: ${coreFiles.join(', ')}\n`
+    if (data.doc) {
+      const docPath = join(specBase, 'docs', projectName, data.doc)
+      const exists = existsSync(docPath)
+      injection += `- **模块文档**: ${data.doc}${exists ? ' ✅' : ' ⚠️ 不存在'}\n`
+    }
+    const deps = data.depends_on || []
+    if (deps.length > 0) injection += `- **依赖**: ${deps.join(', ')}\n`
+    const usedBy = data.used_by || []
+    if (usedBy.length > 0) injection += `- **被引用**: ${usedBy.join(', ')}\n`
+    injection += '\n'
+  }
+
+  return injection
+}
+
+// 复用 modules.js 的简单 YAML 解析（避免循环依赖）
+function parseModuleMapSimple(content) {
+  const modules = {}
+  let currentModule = null
+  let currentKey = null
+  let currentArray = null
+
+  for (const line of content.split('\n')) {
+    const moduleMatch = line.match(/^  ([a-zA-Z0-9_-]+):$/)
+    if (moduleMatch) {
+      if (currentArray && currentModule && currentKey) {
+        modules[currentModule][currentKey] = currentArray
+      }
+      currentModule = moduleMatch[1]
+      modules[currentModule] = {}
+      currentKey = null
+      currentArray = null
+      continue
+    }
+    if (!currentModule) continue
+
+    const arrayFieldMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons|core_files|test_files|related_docs|verify_commands):$/)
+    if (arrayFieldMatch) {
+      if (currentArray && currentKey) modules[currentModule][currentKey] = currentArray
+      currentKey = arrayFieldMatch[1]
+      currentArray = []
+      continue
+    }
+
+    const inlineArrayMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons|core_files|test_files|related_docs|verify_commands): \[(.*)\]$/)
+    if (inlineArrayMatch) {
+      if (currentArray && currentKey) modules[currentModule][currentKey] = currentArray
+      const vals = inlineArrayMatch[2].split(',').map(v => v.trim()).filter(Boolean)
+      modules[currentModule][inlineArrayMatch[1]] = vals
+      currentKey = null
+      currentArray = null
+      continue
+    }
+
+    const scalarMatch = line.match(/^    (status|doc|needs_review|role|risk_level): (.+)$/)
+    if (scalarMatch) {
+      if (currentArray && currentKey) { modules[currentModule][currentKey] = currentArray; currentArray = null; currentKey = null }
+      modules[currentModule][scalarMatch[1]] = scalarMatch[2]
+      continue
+    }
+
+    const itemMatch = line.match(/^      - (.+)$/)
+    if (itemMatch && currentArray !== null) {
+      currentArray.push(itemMatch[1].trim())
+      continue
+    }
+  }
+  if (currentArray && currentModule && currentKey) {
+    modules[currentModule][currentKey] = currentArray
+  }
+  return modules
+}
+
 /**
  * 同步触发辅助函数：_write 后 best-effort 同步到平台
  */
@@ -487,6 +630,19 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     }
   }
 
+  // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
+  if (['brainstorm', 'plan', 'execute'].includes(stageName) && projectName) {
+    const moduleIndex = loadModuleContextIndex(specBase || join(cwd, '.sillyspec'), projectName)
+    if (moduleIndex && Object.keys(moduleIndex).length > 0) {
+      // 尝试从 step prompt / changeName 匹配模块
+      const taskDesc = step.prompt || changeName || ''
+      const injection = buildModuleContextInjection(taskDesc, moduleIndex, specBase || join(cwd, '.sillyspec'), projectName)
+      if (injection) {
+        promptText = injection + '\n' + promptText
+      }
+    }
+  }
+
   // 平台模式 prompt 自检：确保没有裸相对输出路径
   // 只匹配正向写入指令中的裸路径，避免误杀「禁止写入 .sillyspec/」等安全说明
   if ((platformOpts?.specRoot || platformOpts?.runtimeRoot) && stageName === 'scan') {
@@ -1749,7 +1905,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         try { unlinkSync(platformOptsFile) } catch {}
 
         // CLI 层 post-check（替代旧的简单检查）
-        const { runScanPostCheck, printScanPostCheckResult } = await import('./scan-postcheck.js')
+        const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('./scan-postcheck.js')
         const postResult = runScanPostCheck({
           cwd,
           specDir: platformOpts.specRoot,
@@ -1761,6 +1917,22 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         })
         printScanPostCheckResult(postResult)
 
+        // 生成结构化 JSON 并写入 runtime（供 SillyHub 消费）
+        const structured = formatStructuredResult(postResult, {
+          workspace_id: platformOpts.workspaceId,
+          scan_run_id: platformOpts.scanRunId,
+          source_root: cwd,
+          spec_root: platformOpts.specRoot,
+          runtime_root: platformOpts.runtimeRoot,
+        })
+        const postcheckJsonPath = writeStructuredResult(structured, platformOpts.specRoot, {
+          runtimeRoot: platformOpts.runtimeRoot,
+          scanRunId: platformOpts.scanRunId,
+        })
+        if (postcheckJsonPath) {
+          console.log(`📄 postcheck-result.json 已写入: ${postcheckJsonPath}`)
+        }
+
         // 将 post-check 结果写入 manifest
         manifest.scan_post_check = {
           status: postResult.status,
@@ -1788,11 +1960,17 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       }
     }
 
-    // 非 platform 模式 scan 也做轻量 post-check
+    // 非 platform 模式 scan 也做轻量 post-check + 结构化输出
     if (stageName === 'scan' && !platformOpts.specRoot && !platformOpts.runtimeRoot) {
-      const { runScanPostCheck, printScanPostCheckResult } = await import('./scan-postcheck.js')
+      const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('./scan-postcheck.js')
       const postResult = runScanPostCheck({ cwd, specDir: null, outputText })
       printScanPostCheckResult(postResult)
+      // 结构化结果写入 .sillyspec/.runtime/
+      const structured = formatStructuredResult(postResult, { source_root: cwd })
+      const postcheckJsonPath = writeStructuredResult(structured, join(cwd, '.sillyspec'))
+      if (postcheckJsonPath) {
+        console.log(`📄 postcheck-result.json 已写入: ${postcheckJsonPath}`)
+      }
     }
 
     validateMetadata(cwd, stageName, specBase)

package/src/scan-postcheck.js

@@ -5,7 +5,7 @@
  * 平台模式下必须通过所有 check 才能 success，否则降级。
  */
 
-import { existsSync, readdirSync, readFileSync } from 'fs'
+import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync } from 'fs'
 import { join, basename } from 'path'
 
 const REQUIRED_SCAN_DOCS = [
@@ -198,6 +198,138 @@ export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {}
   return { status, checks }
 }
 
+/**
+ * 将 postcheck 结果转换为结构化 JSON（SillyHub 可消费格式）
+ *
+ * failure_category 标准化：
+ *   - warning  : 非致命问题，不阻塞流程
+ *   - error    : 文档缺失/内容不完整，需要修复
+ *   - critical : 安全问题（source_root 泄漏/路径污染）
+ *
+ * 结构化字段：
+ *   - violations      : 明确违反约束的条目（source_root 泄漏等）
+ *   - missing_outputs : 预期文件不存在
+ *   - path_pollution  : 产物写入了错误路径
+ *   - bad_references  : 引用了不存在的命令/资源
+ *   - quality_warnings: AI 输出中包含错误标记等质量信号
+ *
+ * @param {object} result - runScanPostCheck 返回值
+ * @param {object} [meta] - 附带元数据（workspace_id, scan_run_id, timestamp 等）
+ * @returns {object} 结构化 JSON
+ */
+export function formatStructuredResult(result, meta = {}) {
+  const structured = {
+    schema_version: 1,
+    generated_at: new Date().toISOString(),
+    overall_status: result.status,
+    // 路径溯源（供平台消费）
+    ...(meta.workspace_id ? { workspace_id: meta.workspace_id } : {}),
+    ...(meta.scan_run_id ? { scan_run_id: meta.scan_run_id } : {}),
+    ...(meta.source_root ? { source_root: meta.source_root } : {}),
+    ...(meta.spec_root ? { spec_root: meta.spec_root } : {}),
+    ...(meta.runtime_root ? { runtime_root: meta.runtime_root } : {}),
+    summary: {
+      total_checks: result.checks.length,
+      critical: 0,
+      error: 0,
+      warning: 0,
+    },
+    failure_categories: {
+      violations: [],
+      missing_outputs: [],
+      path_pollution: [],
+      bad_references: [],
+      quality_warnings: [],
+    },
+    checks: result.checks.map(c => ({
+      name: c.name,
+      severity: c.severity === 'failed' ? 'critical' : c.severity,
+      detail: c.detail,
+    })),
+  }
+
+  // 分类到 failure_categories
+  for (const check of result.checks) {
+    const severity = check.severity === 'failed' ? 'critical' : check.severity
+    const entry = { name: check.name, detail: check.detail, severity }
+
+    // 路径污染类
+    if (check.name === 'source_root_leak') {
+      structured.failure_categories.path_pollution.push(entry)
+      structured.failure_categories.violations.push(entry)
+    }
+    // 文档缺失类
+    else if (check.name === 'all_docs_missing' || check.name === 'partial_docs_missing' || check.name === 'missing_docs') {
+      structured.failure_categories.missing_outputs.push(entry)
+    }
+    // 引用无效类
+    else if (check.name === 'local_config_invalid') {
+      structured.failure_categories.bad_references.push(entry)
+    }
+    // AI 输出质量类
+    else if (['tool_use_error', 'api_error_529', 'rate_limit_exhausted', 'fallback_or_skip'].includes(check.name)) {
+      structured.failure_categories.quality_warnings.push(entry)
+    }
+    // manifest/project 列表问题
+    else if (check.name === 'manifest_write_failed' || check.name === 'project_list_parse_failed') {
+      structured.failure_categories.violations.push(entry)
+    }
+    // 文档缺少 header
+    else if (check.name === 'docs_missing_header') {
+      structured.failure_categories.quality_warnings.push(entry)
+    }
+    // 兜底：归入 violations
+    else {
+      structured.failure_categories.violations.push(entry)
+    }
+  }
+
+  // 汇总计数
+  for (const check of result.checks) {
+    if (check.severity === 'failed') structured.summary.critical++
+    else structured.summary.warning++
+  }
+
+  return structured
+}
+
+/**
+ * 将结构化结果写入 JSON 文件（平台模式供 SillyHub 消费）
+ *
+ * 本地模式：写入 specDir/.runtime/postcheck-result.json
+ * 平台模式：写入 runtimeRoot/scan-runs/{scan_run_id}/postcheck-result.json
+ *
+ * @param {object} structured - formatStructuredResult 返回值
+ * @param {string} specDir - 规范目录（本地模式使用）
+ * @param {object} [opts] - 平台模式选项
+ * @param {string} [opts.runtimeRoot] - 平台模式运行时根目录
+ * @param {string} [opts.scanRunId] - scan run ID
+ * @returns {string|null} 写入的文件路径，失败时返回 null
+ */
+export function writeStructuredResult(structured, specDir, opts = {}) {
+  if (!specDir && !opts.runtimeRoot) return null
+  try {
+    let outPath
+    if (opts.runtimeRoot && opts.scanRunId) {
+      const scanRunDir = join(opts.runtimeRoot, 'scan-runs', opts.scanRunId)
+      mkdirSync(scanRunDir, { recursive: true })
+      outPath = join(scanRunDir, 'postcheck-result.json')
+    } else if (specDir) {
+      const runtimeDir = join(specDir, '.runtime')
+      mkdirSync(runtimeDir, { recursive: true })
+      outPath = join(runtimeDir, 'postcheck-result.json')
+    } else {
+      return null
+    }
+
+    writeFileSync(outPath, JSON.stringify(structured, null, 2) + '\n')
+    return outPath
+  } catch (e) {
+    console.warn(`  ⚠️ postcheck-result.json 写入失败: ${e.message}`)
+    return null
+  }
+}
+
 /**
  * 打印 post-check 结果到 stdout
  */