sillyspec 3.12.8 → 3.13.0

package/package.json

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

package/src/index.js

@@ -474,6 +474,45 @@ SillySpec platform — SillyHub 平台同步
       }
       break;
     }
+    case 'change-rename': {
+      const oldName = filteredArgs[1];
+      const newName = filteredArgs[2];
+      if (!oldName || !newName) {
+        console.error('❌ 用法: sillyspec change-rename <旧变更名> <新变更名>');
+        process.exit(1);
+      }
+      const pm = new ProgressManager();
+      await pm.renameChange(dir, oldName, newName);
+      break;
+    }
+    case 'modules': {
+      const modulesSub = filteredArgs[1];
+      if (!modulesSub || modulesSub === 'help' || modulesSub === '--help') {
+        console.log(`
+SillySpec modules — 模块文档管理
+
+用法:
+  sillyspec modules rebuild        从模块卡片 + 源码重建 _module-map.yaml
+  sillyspec modules status         显示模块索引状态
+  sillyspec modules migrate        旧格式模块文档迁移到新格式
+`);
+        break;
+      }
+      if (modulesSub === 'rebuild') {
+        const { rebuildModuleMap } = await import('./modules.js');
+        await rebuildModuleMap(dir);
+      } else if (modulesSub === 'status') {
+        const { showModuleStatus } = await import('./modules.js');
+        await showModuleStatus(dir);
+      } else if (modulesSub === 'migrate') {
+        const { migrateModuleDocs } = await import('./modules.js');
+        await migrateModuleDocs(dir);
+      } else {
+        console.error(`❌ 未知子命令: modules ${modulesSub}`);
+        process.exit(1);
+      }
+      break;
+    }
     default:
       console.error(`❌ 未知命令: ${command}`);
       printUsage();

package/src/modules.js

@@ -0,0 +1,427 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { DB } from './db.js';
+
+/**
+ * 查找项目下的 _module-map.yaml 路径
+ */
+function findModuleMapPath(cwd) {
+  // 查找 .sillyspec/docs/<project>/modules/_module-map.yaml
+  const docsDir = join(cwd, '.sillyspec', 'docs');
+  if (!existsSync(docsDir)) return null;
+
+  const projects = readdirSync(docsDir, { withFileTypes: true })
+    .filter(e => e.isDirectory());
+
+  for (const proj of projects) {
+    const mapPath = join(docsDir, proj.name, 'modules', '_module-map.yaml');
+    if (existsSync(mapPath)) return mapPath;
+  }
+
+  // 如果没有找到已有的，返回第一个项目的路径（用于创建）
+  if (projects.length > 0) {
+    return join(docsDir, projects[0].name, 'modules', '_module-map.yaml');
+  }
+
+  return null;
+}
+
+/**
+ * 从模块卡片文件名提取 module_id
+ */
+function parseModuleIdFromFilename(filename) {
+  return filename.replace(/\.md$/, '');
+}
+
+/**
+ * 从模块卡片读取 frontmatter 中的 module_id
+ */
+function parseModuleCardFrontmatter(content) {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return {};
+  const fm = fmMatch[1];
+  const moduleIdMatch = fm.match(/^module_id:\s*(.+)$/m);
+  return {
+    module_id: moduleIdMatch ? moduleIdMatch[1].trim() : null
+  };
+}
+
+/**
+ * rebuild: 从模块卡片 + 源码重建 _module-map.yaml
+ */
+export async function rebuildModuleMap(cwd) {
+  const mapPath = findModuleMapPath(cwd);
+  if (!mapPath) {
+    console.error('❌ 未找到 .sillyspec/docs/<project>/modules/ 目录');
+    console.log('   提示：先运行 sillyspec run scan 生成模块文档');
+    return;
+  }
+
+  const modulesDir = join(mapPath, '..');
+  const existingMap = existsSync(mapPath) ? readFileSync(mapPath, 'utf8') : null;
+
+  // 收集现有模块卡片
+  const cards = [];
+  if (existsSync(modulesDir)) {
+    const files = readdirSync(modulesDir).filter(f => f.endsWith('.md') && f !== '_module-map.yaml');
+    for (const f of files) {
+      const content = readFileSync(join(modulesDir, f), 'utf8');
+      const fm = parseModuleCardFrontmatter(content);
+      const moduleId = fm.module_id || parseModuleIdFromFilename(f);
+      cards.push({ filename: f, moduleId });
+    }
+  }
+
+  // 解析现有 _module-map.yaml 保留已有字段
+  let existingModules = {};
+  if (existingMap) {
+    // 简单解析：提取 modules: 下的条目
+    const lines = existingMap.split('\n');
+    let currentModule = null;
+    let inModules = false;
+    for (const line of lines) {
+      if (line.startsWith('modules:')) { inModules = true; continue; }
+      if (!inModules) continue;
+      if (line.startsWith('  ') === false && line.trim() !== '') break;
+      const moduleMatch = line.match(/^  ([a-zA-Z0-9_-]+):/);
+      if (moduleMatch) {
+        currentModule = moduleMatch[1];
+        existingModules[currentModule] = existingModules[currentModule] || { paths: [] };
+      }
+    }
+  }
+
+  // 如果没有模块卡片也没有已有映射
+  if (cards.length === 0 && Object.keys(existingModules).length === 0) {
+    console.log('📭 没有模块卡片，也没有已有的模块映射');
+    console.log('   提示：先运行 sillyspec run scan 生成模块文档');
+    return;
+  }
+
+  // 生成新的 _module-map.yaml
+  // 保留已有的完整字段，补齐新卡片
+  const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  let headCommit = '';
+  try {
+    const { execSync } = await import('child_process');
+    headCommit = execSync('git rev-parse --short HEAD', { cwd, encoding: 'utf8', timeout: 5000 }).trim();
+  } catch { /* ignore */ }
+
+  let yaml = `schema_version: 1\n`;
+  yaml += `generated_at: ${now}\n`;
+  yaml += `generator: sillyspec-modules-rebuild\n`;
+  if (headCommit) yaml += `source_commit: ${headCommit}\n`;
+  yaml += `\nmodules:\n`;
+
+  // 合并：已有映射 + 新卡片
+  const allModuleIds = new Set([
+    ...Object.keys(existingModules),
+    ...cards.map(c => c.moduleId)
+  ]);
+
+  for (const moduleId of allModuleIds) {
+    const card = cards.find(c => c.moduleId === moduleId);
+    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`;
+    yaml += `\n`;
+  }
+
+  writeFileSync(mapPath, yaml, 'utf8');
+  console.log(`✅ _module-map.yaml 已重建：${mapPath}`);
+  console.log(`   模块数量：${allModuleIds.size}`);
+  for (const id of allModuleIds) {
+    console.log(`   - ${id}`);
+  }
+  console.log(`\n⚠️  注意：rebuild 只重建骨架。tags/entrypoints/main_symbols/depends_on/used_by 需要重新运行 scan 或手动补充。`);
+}
+
+/**
+ * status: 显示模块索引状态
+ */
+export async function showModuleStatus(cwd) {
+  const mapPath = findModuleMapPath(cwd);
+  if (!mapPath || !existsSync(mapPath)) {
+    console.log('📭 未找到 _module-map.yaml');
+    console.log('   提示：先运行 sillyspec run scan 生成模块文档');
+    return;
+  }
+
+  const content = readFileSync(mapPath, 'utf8');
+
+  // 简单解析
+  const lines = content.split('\n');
+  const modules = [];
+  let currentModule = null;
+  let needsReview = false;
+
+  for (const line of lines) {
+    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 };
+    }
+    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 (currentModule) modules.push(currentModule);
+
+  console.log(`\n_module-map.yaml: ${mapPath}`);
+  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)}  ────  ─────  ────  ──────`);
+  for (const m of modules) {
+    const tags = m.hasTags ? '✅' : '⬜';
+    const entry = m.hasEntryPoints ? '✅' : '⬜';
+    const deps = m.hasDepends ? '✅' : '⬜';
+    const review = m.needsReview ? '⚠️' : '✅';
+    console.log(`  ${m.id.padEnd(maxId)}  ${tags}     ${entry}     ${deps}     ${review}`);
+  }
+
+  if (needsReview) {
+    console.log(`\n⚠️  有模块标记为 needs_review，建议检查或重新 scan`);
+  }
+}
+
+/**
+ * 从 _module-map.yaml 聚合生成 dependencies.md
+ */
+export async function generateDependenciesMd(cwd) {
+  const mapPath = findModuleMapPath(cwd);
+  if (!mapPath || !existsSync(mapPath)) return;
+
+  const content = readFileSync(mapPath, 'utf8');
+  const modules = parseModuleMapSimple(content);
+
+  if (Object.keys(modules).length === 0) return;
+
+  const depsPath = join(mapPath, '..', 'dependencies.md');
+  const maxName = Math.max(6, ...Object.keys(modules).map(k => k.length));
+
+  let md = `# Module Dependencies\n\n`;
+  md += `> 自动生成，由 sillyspec 维护\n\n`;
+  md += `| ${'Module'.padEnd(maxName)} | Depends On | Used By |\n`;
+  md += `| ${''.padEnd(maxName, '-')}:--- | :--- | :--- |\n`;
+
+  for (const [id, data] of Object.entries(modules)) {
+    const depends = (data.depends_on || []).join(', ') || '—';
+    const usedBy = (data.used_by || []).join(', ') || '—';
+    md += `| ${id.padEnd(maxName)} | ${depends} | ${usedBy} |\n`;
+  }
+
+  writeFileSync(depsPath, md, 'utf8');
+  console.log(`✅ dependencies.md 已生成`);
+}
+
+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;
+
+    // Array field like depends_on:\n  - xxx
+    const arrayFieldMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons):$/);
+    if (arrayFieldMatch) {
+      if (currentArray && currentKey) modules[currentModule][currentKey] = currentArray;
+      currentKey = arrayFieldMatch[1];
+      currentArray = [];
+      continue;
+    }
+
+    // Inline array like tags: [a, b]
+    const inlineArrayMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons): \[(.*)\]$/);
+    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;
+    }
+
+    // Scalar field
+    const scalarMatch = line.match(/^    (status|doc|needs_review): (.+)$/);
+    if (scalarMatch) {
+      if (currentArray && currentKey) { modules[currentModule][currentKey] = currentArray; currentArray = null; currentKey = null; }
+      modules[currentModule][scalarMatch[1]] = scalarMatch[2];
+      continue;
+    }
+
+    // Array item
+    const itemMatch = line.match(/^      - (.+)$/);
+    if (itemMatch && currentArray !== null) {
+      currentArray.push(itemMatch[1].trim());
+      continue;
+    }
+  }
+
+  // Flush last
+  if (currentArray && currentModule && currentKey) {
+    modules[currentModule][currentKey] = currentArray;
+  }
+
+  return modules;
+}
+
+/**
+ * migrate: 旧格式模块文档迁移到新格式
+ */
+export async function migrateModuleDocs(cwd) {
+  const mapPath = findModuleMapPath(cwd);
+  if (!mapPath || !existsSync(mapPath)) {
+    console.error('❌ 未找到 _module-map.yaml');
+    return;
+  }
+
+  const modulesDir = join(mapPath, '..');
+  const files = readdirSync(modulesDir).filter(f => f.endsWith('.md') && f !== '_module-map.yaml');
+
+  if (files.length === 0) {
+    console.log('📭 没有模块文档需要迁移');
+    return;
+  }
+
+  let migrated = 0;
+  let skipped = 0;
+
+  for (const f of files) {
+    const filePath = join(modulesDir, f);
+    const content = readFileSync(filePath, 'utf8');
+
+    // 检查是否已经是新格式（有 schema_version + doc_type: module-card）
+    if (content.includes('schema_version:') && content.includes('doc_type: module-card')) {
+      skipped++;
+      continue;
+    }
+
+    // 提取模块名（从 H1 或文件名）
+    const h1Match = content.match(/^# (.+)$/m);
+    const moduleId = h1Match ? h1Match[1].trim().replace(/\s+/g, '-').toLowerCase() : f.replace('.md', '');
+
+    // 提取旧的“职责”和“注意事项”作为语义内容保留
+    const dutyMatch = content.match(/## 职责\n([\s\S]*?)(?=\n##|$)/);
+    const notesMatch = content.match(/## 注意事项\n([\s\S]*?)(?=\n##|$)/);
+    const designMatch = content.match(/## 当前设计\n([\s\S]*?)(?=\n##|$)/);
+    const interfaceMatch = content.match(/## 对外接口[\s\S]*?(?=\n##|$)/);
+
+    const duty = dutyMatch ? dutyMatch[1].trim() : '';
+    const notes = notesMatch ? notesMatch[1].trim() : '';
+    const design = designMatch ? designMatch[1].trim() : '';
+
+    // 检查是否有人工备注
+    const manualMatch = content.match(/<!-- MANUAL_NOTES_START -->([\s\S]*?)<!-- MANUAL_NOTES_END -->/);
+    const manualContent = manualMatch ? manualMatch[1].trim() : '';
+
+    // 生成新格式
+    let newContent = `---
+schema_version: 1
+doc_type: module-card
+module_id: ${moduleId}
+---
+
+# ${moduleId}
+
+`;
+
+    if (duty) {
+      newContent += `## 定位
+
+${duty}
+
+`;
+    } else {
+      newContent += `## 定位
+
+（待补充）
+
+`;
+    }
+
+    if (design || interfaceMatch) {
+      newContent += `## 契约摘要
+
+`;
+      if (interfaceMatch) newContent += `${interfaceMatch[0].replace('## 对外接口', '').trim()}
+
+`;
+      else newContent += `（待从源码提取）
+
+`;
+    } else {
+      newContent += `## 契约摘要
+
+（待从源码提取）
+
+`;
+    }
+
+    if (design) {
+      newContent += `## 关键逻辑
+
+${design}
+
+`;
+    } else {
+      newContent += `## 关键逻辑
+
+（待补充）
+
+`;
+    }
+
+    if (notes) {
+      newContent += `## 注意事项
+
+${notes}
+
+`;
+    } else {
+      newContent += `## 注意事项
+
+（待补充）
+
+`;
+    }
+
+    newContent += `## 人工备注
+
+<!-- MANUAL_NOTES_START -->
+${manualContent}
+<!-- MANUAL_NOTES_END -->
+`;
+
+    writeFileSync(filePath, newContent, 'utf8');
+    migrated++;
+  }
+
+  console.log(`✅ 迁移完成`);
+  console.log(`   已迁移：${migrated} 个`);
+  console.log(`   已跳过（新格式）：${skipped} 个`);
+  if (migrated > 0) {
+    console.log(`\n⚠️  迁移后的卡片可能需要补充内容，建议检查并运行 sillyspec modules status`);
+  }
+}

package/src/progress.js

@@ -393,6 +393,57 @@ export class ProgressManager {
     });
   }
 
+  /**
+   * 重命名变更：同步更新 DB + 目录
+   * @param {string} cwd - 项目根目录
+   * @param {string} oldName - 旧变更名
+   * @param {string} newName - 新变更名
+   */
+  async renameChange(cwd, oldName, newName) {
+    if (!oldName || !newName) {
+      console.warn('⚠️  renameChange: 旧名或新名为空，跳过');
+      return;
+    }
+    if (oldName === newName) {
+      console.warn('⚠️  renameChange: 新旧名称相同，跳过');
+      return;
+    }
+    const db = await this._ensureDB(cwd);
+    // 检查旧名是否存在
+    const existing = db.transaction((sqlDb) => {
+      const row = sqlDb.exec(`SELECT name, status FROM changes WHERE name = ?`, [oldName]);
+      if (!row || !row[0] || row[0].values.length === 0) return null;
+      return { name: row[0].values[0][0], status: row[0].values[0][1] };
+    });
+    if (!existing) {
+      console.error(`❌ 变更 ${oldName} 不存在`);
+      return;
+    }
+    // 检查新名是否已存在
+    const conflict = db.transaction((sqlDb) => {
+      const row = sqlDb.exec(`SELECT name FROM changes WHERE name = ?`, [newName]);
+      return row && row[0] && row[0].values.length > 0;
+    });
+    if (conflict) {
+      console.error(`❌ 变更 ${newName} 已存在`);
+      return;
+    }
+    // 重命名目录
+    const oldDir = this._changePath(cwd, oldName);
+    const newDir = this._changePath(cwd, newName);
+    if (existsSync(oldDir)) {
+      renameSync(oldDir, newDir);
+    } else {
+      mkdirSync(newDir, { recursive: true });
+    }
+    // 更新 DB
+    const now = new Date().toISOString();
+    db.transaction((sqlDb) => {
+      sqlDb.run(`UPDATE changes SET name = ?, last_active = ? WHERE name = ?`, [newName, now, oldName]);
+    });
+    console.log(`✅ 变更已重命名：${oldName} → ${newName}`);
+  }
+
   /**
    * 从活跃列表移除变更（归档时调用，不物理删除）
    * SQL: UPDATE changes SET status = 'archived'

package/src/run.js

@@ -224,6 +224,7 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   console.log('- 不要回头修改已完成的步骤')
   console.log('- 不要编造不存在的 CLI 子命令')
   console.log('- 完成后立即执行 --done 命令，不得跳过')
+  console.log('- 不要用 mv/rename 重命名变更目录，必须用 `sillyspec change-rename <旧名> <新名>`')
   console.log('- 文档类型文件（.md/.yaml/.json 等）头部必须包含 author（git 用户名）和 created_at（精确到秒）')
   console.log('- 执行构建/测试前必须先读 local.yaml，优先使用其中配置的命令、路径和环境变量；未配置时才使用默认值')
   // 路径安全规则：防止 AI 拼错变更目录
@@ -310,6 +311,7 @@ export async function runCommand(args, cwd) {
         const autoName = `${date}-new-change`
         console.log(`🔄 自动创建变更：${autoName}`)
         console.log(`  提示：可以用 --change <名称> 指定自定义变更名`)
+        console.log(`  或事后重命名：sillyspec change-rename ${autoName} <新名称>`)
         progress = await pm.initChange(cwd, autoName)
         changeName = autoName
       } else {

package/src/stages/archive.js

@@ -35,10 +35,11 @@ export const definition = {
 5. 将 git diff 文件按 \`_module-map.yaml\` 的 paths glob 匹配到模块
 6. 生成模块影响矩阵：
 
-| 模块 | 影响类型 | 相关文件 | 更新内容摘要 |
-|------|----------|----------|-------------|
+| 模块 | 影响类型 | 相关文件 | 更新内容摘要 | needs_review |
+|------|----------|----------|-------------|-------------|
 
    影响类型：逻辑变更 / 数据结构变更 / 接口变更 / 调用关系变更 / 配置变更 / 新增
+   needs_review：如果影响无法完全确定，标记为 true
 
 7. 未匹配到任何模块的文件归入"未匹配文件"表格
 8. 生成 \`.sillyspec/changes/<change-name>/module-impact.md\`，格式：
@@ -52,8 +53,8 @@ created_at: <now-datetime>
 ## 变更：<change-name>
 
 ## 模块影响矩阵
-| 模块 | 影响类型 | 相关文件 | 更新内容摘要 |
-|------|----------|----------|-------------|
+| 模块 | 影响类型 | 相关文件 | 更新内容摘要 | needs_review |
+|------|----------|----------|-------------|-------------|
 
 ## 未匹配文件
 | 文件路径 | 说明 |
@@ -61,8 +62,8 @@ created_at: <now-datetime>
 
 ## 更新结果
 （sync-module-docs 步骤完成后回填）
-| 模块文档 | 操作 | 状态 |
-|----------|------|------|
+| 目标 | 操作 | 状态 |
+|------|------|------|
 \`\`\`
 
 ### 输出
@@ -72,71 +73,74 @@ module-impact.md 路径 + 影响模块数量 + 未匹配文件数量`,
     },
     {
       name: 'sync-module-docs',
-      prompt: `根据 module-impact.md 同步更新模块设计文档。
+      prompt: `根据 module-impact.md 同步更新模块索引和卡片文档。
 
-### 原则
-- 模块文档正文**永远描述当前状态**（快照模式），不是变更日志
-- 底部只保留轻量变更索引
-- 模块文档是下一次 AI 开发前必须读取的上下文
+### ⚠️ 核心原则：结构化事实改 _module-map.yaml，语义解释改模块卡片
+- \`_module-map.yaml\` 是唯一的结构化索引源（paths/tags/entrypoints/depends_on/used_by/status/needs_review）
+- 模块卡片只负责语义说明（定位/契约摘要/关键逻辑/注意事项/人工备注）
+- 一个信息只维护一次，不要两边重复
 
 ### 操作
 1. 读取 \`.sillyspec/changes/<change-name>/module-impact.md\`
 2. 如果没有受影响模块（只有 unmapped）→ 提示用户，跳过同步
-3. 对每个受影响模块：
-   a. 读取 \`.sillyspec/docs/<project>/modules/<module>.md\`（如不存在则新建）
-   b. 根据 module-impact.md 中的"更新内容摘要"，更新模块文档
-   c. **更新规则**：
-      - 新建：全量生成，使用下方模板
-      - 更新：只改相关章节（当前设计/对外接口/依赖关系等），保持其他章节不变
-      - 正文重写为当前状态，不追加历史
-      - 底部"变更索引"追加一行：\`| <日期> | <变更名> | <一句话摘要> |\`
-   d. 更新头部元数据：\`> 最后更新：<now-date>\`、\`> 最近变更：<change-name>\`
-4. 展示所有模块文档的更新内容（diff 摘要），请用户确认
-5. 用户确认后，写入 \`.sillyspec/docs/<project>/modules/*.md\`
-6. 用户拒绝时，不写入模块文档，但提示"module-impact.md 已保留，可稍后手动同步"
-7. 回填 module-impact.md 的"更新结果"表格
-
-### 模块文档模板
+3. 对每个受影响模块，按影响类型分别更新：
+
+#### 更新 _module-map.yaml 的规则
+- **路径变化** → 更新对应模块的 paths
+- **依赖变化** → 更新 depends_on / used_by（同时更新反向模块的 used_by / depends_on）
+- **导出符号变化** → 更新 entrypoints / main_symbols
+- **新增模块** → 添加完整条目
+- **模块废弃** → status: deprecated
+- **不确定的影响** → needs_review: true, review_reasons 追加原因
+- 如果 _module-map.yaml 的 generated_at 已过时，更新为当前时间
+
+#### 更新模块卡片（modules/<module-id>.md）的规则
+- **契约语义变化**（新增/删除对外能力） → 更新"契约摘要"
+- **关键逻辑变化** → 更新"关键逻辑"
+- **边界变化**（模块职责扩大/缩小） → 更新"定位"
+- **注意事项变化** → 更新"注意事项"
+- **内部实现变化**（不影响对外接口） → 通常不更新卡片
+- **人工备注** → 永远保护，不覆盖
+
+#### 人工备注保护
+1. 用正则提取 \`<!-- MANUAL_NOTES_START -->\` 到 \`<!-- MANUAL_NOTES_END -->\` 之间的内容
+2. 生成新卡片后，原样回填到人工备注区域
+3. 如果标记缺失或重复 → 在 _module-map.yaml 中标记 needs_review: true
+
+#### 新建模块卡片模板
 \`\`\`markdown
-# <module-name>
-
-> 最后更新：<now-date>
-> 最近变更：<change-name>
-> 模块路径：<glob patterns>
+---
+schema_version: 1
+doc_type: module-card
+module_id: <module-id>
+---
 
-## 职责
-（一句话说清这个模块做什么）
+# <module-id>
 
-## 当前设计
-（架构、数据流、关键逻辑 — 描述当前状态，不是历史）
+## 定位
 
-## 对外接口
-| 接口 | 说明 | 调用方 |
-|------|------|--------|
+## 契约摘要
 
-## 关键数据流
-\`\`\`text
-调用方 → 模块.方法() → 依赖模块.方法() → 返回结果
-\`\`\`
+## 关键逻辑
 
-## 设计决策
-| 决策 | 理由 | 来源 |
-|------|------|------|
+## 注意事项
 
-## 依赖关系
-### 依赖本模块
-### 本模块依赖
+## 人工备注
 
-## 注意事项
-（维护提醒、已知限制、修改时需同步检查的模块）
+<!-- MANUAL_NOTES_START -->
 
-## 变更索引
-| 日期 | 变更 | 摘要 |
-|------|------|------|
+<!-- MANUAL_NOTES_END -->
 \`\`\`
 
+4. 展示所有更新内容（diff 摘要），请用户确认
+5. 用户确认后，写入 _module-map.yaml 和受影响的模块卡片
+6. 用户拒绝时，不写入，但提示"module-impact.md 已保留，可稍后手动同步"
+7. 回填 module-impact.md 的"更新结果"表格，区分目标：
+   - 目标列写 "\`_module-map.yaml: <module-id>\`" 或 "\`modules/<module-id>.md\`"
+8. **同步完成后**，运行 \`sillyspec modules rebuild\` 刷新索引（如果需要），或手动更新 dependencies.md
+
 ### 输出
-已更新的模块文档路径列表 + 用户确认状态`,
+已更新的文件路径列表 + 用户确认状态`,
       outputHint: '模块文档更新结果',
       optional: false
     },

package/src/stages/brainstorm.js

@@ -12,13 +12,15 @@ export const definition = {
 2. 确认 currentStage 为 "brainstorm"
 3. 如果有进行中的 brainstorm，提示选择继续或重新开始
 4. 如果未初始化，提示先运行 sillyspec init
+5. **检查变更名称是否有意义**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change\`），先询问用户确认实际变更名，然后运行 \`sillyspec change-rename <旧名> <新名>\` 重命名
 
 ### 输出
 当前状态摘要（1-2 句话）
 
 ### 注意
 - 以 CLI 返回为准，不要自行推断阶段
-- 如果阶段不对，输出正确提示并停止`,
+- 如果阶段不对，输出正确提示并停止
+- **不要用 mv 命令重命名变更目录**，必须使用 \`sillyspec change-rename\`，否则 DB 和目录会脱节`,
       outputHint: '状态摘要',
       optional: false
     },
@@ -32,14 +34,25 @@ export const definition = {
 3. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`
 4. 询问本次需求属于哪个子项目
 5. 棕地项目：读取 .sillyspec/docs/<project>/scan/ 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
-6. 查看进行中的变更：\`ls .sillyspec/changes/ | grep -v archive\`
+6. **加载模块索引**：读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（如存在）
+   - 这一步是高频操作，_module-map.yaml 回答“哪个文件属于哪个模块、模块之间怎么依赖”
+   - 用 tags/aliases 字段做需求关键词→模块的粗匹配
+   - 用 entrypoints 字段快速了解模块对外能力
+7. 查看进行中的变更：\`ls .sillyspec/changes/ | grep -v archive\`
+
+### 模块匹配方法
+读取 _module-map.yaml 后，根据用户描述的需求关键词，匹配相关模块：
+- 需求中提到"登录""认证""token" → 匹配 tags/aliases 中含这些词的模块
+- 需求中提到特定文件路径 → 匹配 paths 字段
+- 匹配结果用于后续 design.md 的文件变更清单
 
 ### 输出
-项目现状理解摘要（3-5 句话，关键约定和架构决策）
+项目现状理解摘要（3-5 句话，关键约定和架构决策）+ 可能涉及的模块列表
 
 ### 注意
 - 始终询问本次需求属于哪个子项目
-- 棕地项目必须读取数据模型章节`,
+- 棕地项目必须读取数据模型章节
+- 模块匹配只是粗筛，后续步骤会细化`,
       outputHint: '上下文摘要',
       optional: false
     },

package/src/stages/doctor.js

@@ -238,9 +238,38 @@ timeout 5 which docker 2>/dev/null && echo "✅ Docker 可用" || echo "ℹ️ D
       outputHint: '外部依赖检查结果',
       optional: false
     },
+    {
+      name: '模块文档健康检查',
+      prompt: `检查模块索引和卡片文档的健康状态。
+
+### 操作
+1. 运行 \`sillyspec modules status\` 查看模块索引概览
+2. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`
+3. 对每个模块，检查：
+   - module_id 是否有对应的卡片文件（modules/<module-id>.md）
+   - 卡片文件是否有有效的 frontmatter（schema_version, doc_type, module_id）
+   - 人工备注标记是否配对（MANUAL_NOTES_START 和 MANUAL_NOTES_END 必须成对出现）
+   - needs_review 为 true 的模块列表
+4. 汇总结果
+
+### 输出格式
+\`\`\`
+📋 模块文档健康检查
+✅ _module-map.yaml — 存在，N 个模块
+⚠️  auth-service — needs_review=true，原因：...
+❌ payment-service — 卡片文件缺失
+✅ 所有模块人工备注标记配对正常
+\`\`\`
+
+### 注意
+- 如果 _module-map.yaml 不存在，输出"模块索引未生成，建议运行 scan"
+`,
+      outputHint: '模块文档健康状态',
+      optional: false
+    },
     {
       name: '汇总报告',
-      prompt: `汇总前三步的所有检查结果，生成最终的自检报告。
+      prompt: `汇总前四步的所有检查结果，生成最终的自检报告。
 
 ### 输出格式
 \`\`\`

package/src/stages/execute.js

@@ -41,9 +41,13 @@ const fixedPrefix = [
 7. 根据 plan.md 中的任务文件路径匹配 _module-map.yaml 中的模块
 8. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
 9. 实现代码时遵循模块文档中描述的接口约定、数据流和依赖关系
+10. **利用模块索引快速定位源码**：
+    - 用 entrypoints 字段直接找到模块对外 API 的源码位置
+    - 用 main_symbols 字段找到核心类/函数的定义位置
+    - 子代理优先读模块卡片理解语义，再读 entrypoints/main_symbols 对应的源码
 
 ### 输出
-已加载的上下文摘要（含模块文档）`,
+已加载的上下文摘要（含模块文档 + 源码锚点）`,
     outputHint: '上下文摘要',
     optional: false
   },

package/src/stages/plan.js

@@ -38,9 +38,14 @@ export const fixedPrefix = [
 6. 根据 design.md 的文件变更清单匹配 _module-map.yaml 中的模块
 7. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
 8. 将模块文档作为制定计划的上下文，确保计划符合模块当前设计
+9. **利用模块依赖关系辅助分析**：
+   - 用 depends_on 判断哪些模块会被间接影响
+   - 用 used_by 判断变更会不会影响下游模块
+   - 将依赖关系纳入 Wave 分组决策（依赖同一模块的任务尽量同 Wave）
+   - 如果变更涉及多个有依赖关系的模块，在 plan.md 的任务总表中标注模块依赖
 
 ### 输出
-已加载的文件清单（含模块文档）`,
+已加载的文件清单（含模块文档 + 模块依赖关系摘要）`,
     outputHint: '文件清单',
     optional: false
   },

package/src/stages/scan.js

@@ -191,52 +191,127 @@ local.yaml 生成结果（已存在/已生成）`,
     },
     {
       name: '生成模块映射',
-      prompt: `生成模块映射配置文件，建立"文件路径 → 模块"的稳定映射。
+      prompt: `生成模块索引文件 \`_module-map.yaml\`，它是 agent 高频读取的机器索引。
+
+### ⚠️ 重要：这个文件是唯一的结构化索引源
+所有结构化事实（paths/tags/entrypoints/depends_on/used_by）只维护在这个文件里。
+模块卡片（modules/*.md）只负责人类语义说明，不重复索引信息。
 
 ### 操作
-1. 检查 \.sillyspec/docs/<project>/modules/_module-map.yaml\` 是否已存在，已存在则跳过
-2. 分析项目 src/ 目录结构（或主代码目录），识别模块划分：
-   - 用 \`find . -maxdepth 2 -type d -not -path "*/node_modules/*" -not -path "*/.git/*"\` 查看目录结构
-   - 每个独立目录（有明确职责的）识别为一个模块
-   - 路径用 glob 模式（如 \`src/auth/**\`）
-3. 生成 \.sillyspec/docs/<project>/modules/_module-map.yaml\`
-4. 如果 modules/ 目录不存在，先创建
-5. 原子写入（先写 tmp 文件再 rename）
+1. 检查 \`.sillyspec/docs/<project>/modules/_module-map.yaml\` 是否已存在，已存在则跳过
+2. 分析项目源码目录结构，识别模块划分：
+   - 用 \`find . -maxdepth 3 -type d -not -path "*/node_modules/*" -not -path "*/.git/*"\` 查看目录结构
+   - 每个有明确职责的独立目录识别为一个模块
+   - 路径用 glob 模式
+3. 用 grep/rg 分析每个模块：
+   - \`main_symbols\`：模块导出的主要函数/类/常量（grep export / module.exports / def / class）
+   - \`entrypoints\`：对外 API 端点或命令入口（grep route / router / @Controller / @GetMapping 等）
+   - \`tags\`：模块相关关键词标签
+   - \`aliases\`：模块的别名（其他开发者可能怎么称呼这个模块）
+4. 分析跨模块依赖关系：
+   - 用 grep import/require 分析模块间的引用链
+   - 填充 depends_on（本模块依赖谁）和 used_by（谁依赖本模块）
+5. 生成 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`
+6. 如果 modules/ 目录不存在，先创建
+7. 原子写入（先写 tmp 文件再 rename）
 
 ### YAML 格式
 \`\`\`yaml
-# 模块映射（自动生成，可手动修改）
-# 用于 archive 阶段识别变更影响的模块
+schema_version: 1
+project: <project-name>
+source_commit: <git-head-short>
+generated_at: <now-datetime>
+generator: sillyspec-scan
+
 modules:
-  <module-name>:
+  <module-id>:
+    status: active
+    doc: modules/<module-id>.md
     paths:
       - <glob-pattern>
-    description: <一句话描述>
+    tags:
+      - <tag1>
+      - <tag2>
+    aliases:
+      - <alias1>
+    entrypoints:
+      - <exported-symbol-or-api-endpoint>
+    main_symbols:
+      - <exported-class-or-function>
+    depends_on:
+      - <other-module-id>
+    used_by:
+      - <other-module-id>
+    needs_review: false
+    concerns: []
+    review_reasons: []
 \`\`\`
 
 ### 示例
 \`\`\`yaml
-modules:
-  core:
-    paths:
-      - src/core/**
-      - src/utils/**
-    description: 核心工具和公共逻辑
+schema_version: 1
+project: multi-agent-platform
+source_commit: abc1234
+generated_at: 2026-06-02 22:00:00
+generator: sillyspec-scan
 
-  stages:
+modules:
+  auth-service:
+    status: active
+    doc: modules/auth-service.md
     paths:
-      - src/stages/**
-    description: 阶段定义（brainstorm/plan/execute/verify/archive等）
+      - src/modules/auth/**
+      - src/middleware/auth.js
+    tags:
+      - auth
+      - jwt
+      - rbac
+      - middleware
+    aliases:
+      - login
+      - token
+      - authentication
+    entrypoints:
+      - authenticate
+      - authorize
+      - signToken
+      - refreshToken
+    main_symbols:
+      - AuthService
+      - AuthController
+      - hashPassword
+      - verifyPassword
+    depends_on:
+      - users
+      - redis
+    used_by:
+      - api-routes
+      - admin-routes
+    needs_review: false
+    concerns: []
+    review_reasons: []
 \`\`\`
 
+### 关键规则
+- module-id 用 kebab-case（如 auth-service）
+- depends_on / used_by 引用其他模块的 module-id
+- tags 和 aliases 用于 brainstorm 阶段的需求→模块匹配，尽量覆盖开发者可能用的词
+- entrypoints 和 main_symbols 用于 execute 阶段快速定位源码
+- 不要编造无法从源码 grep 到的符号
+- 如果无法确定依赖关系，depends_on/used_by 留空列表，不要猜
+
 ### 输出
 _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
       outputHint: '_module-map.yaml 生成状态',
       optional: true
     },
     {
-      name: '生成模块核心文档',
-      prompt: `根据 _module-map.yaml 中的模块划分，为每个模块生成核心文档（用于后续归档和开发上下文）。
+      name: '生成模块卡片文档',
+      prompt: `根据 _module-map.yaml 中的模块划分，为每个模块生成精简卡片文档。
+
+### ⚠️ 重要：模块卡片只负责人类语义说明
+结构化索引（paths/tags/entrypoints/depends_on/used_by）已经在 _module-map.yaml 里维护。
+卡片里不要重复这些信息，只写 _module-map.yaml 无法表达的语义内容。
 
 ### 操作
 1. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`，获取模块列表和路径
@@ -255,32 +330,48 @@ _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
 - 环境探测结果摘要（构建工具、语言框架）
 - scan 文档关键信息摘要（ARCHITECTURE.md 的技术栈、CONVENTIONS.md 的代码风格要点，如已生成）
 \`\`\`
-模块名：<module-name>
+模块名：<module-id>
 模块路径：<glob patterns>
-目标文件：.sillyspec/docs/<project>/modules/<module>.md
+目标文件：.sillyspec/docs/<project>/modules/<module-id>.md
 
 操作：
 1. 用 grep/rg 搜索模块路径范围内的源码（禁止读源码全文）
-2. 提取：模块职责、对外接口（导出函数/API）、关键依赖、设计要点
+2. 提取：模块职责、对外接口、关键逻辑、注意事项
 3. 按以下模板写入目标文件：
 
-# <module-name>
-> 最后更新：<now-date>
-> 最近变更：scan（初始生成）
-> 模块路径：<glob patterns>
-
-## 职责
-## 当前设计
-## 对外接口（表格）
-## 关键数据流
-## 设计决策（表格）
-## 依赖关系
+---
+schema_version: 1
+doc_type: module-card
+module_id: <module-id>
+---
+
+# <module-id>
+
+## 定位
+（负责什么，不负责什么 — 明确边界）
+
+## 契约摘要
+（核心能力列表，具体导出符号以 _module-map.yaml 的 entrypoints/main_symbols 为准）
+
+## 关键逻辑
+（最核心的流程摘要，用 text 伪代码，不超过 3-5 行）
+
 ## 注意事项
-## 变更索引（表格，初始为空）
+（维护提醒、已知限制、修改时需同步检查的模块）
+
+## 人工备注
+
+<!-- MANUAL_NOTES_START -->
+
+<!-- MANUAL_NOTES_END -->
 
 规则：
 - 不要编造接口或依赖，只写 grep/rg 能搜到的
-- 模板与 archive 阶段格式一致
+- 目标长度：500-1000 字 / 80-150 行
+- 如果模块特别复杂（状态机、多角色交互、复杂领域规则），可以在 modules/details/ 下生成扩展文档（如 details/<module-id>-flow.md），agent 默认不读
+- 不要重复 _module-map.yaml 中的索引信息
+- 不要写设计决策表、完整依赖表、变更索引长表
+- 人工备注区域保持空标记，留给用户填写
 \`\`\`
 
 等待所有子代理完成，验证文件是否生成且非空。
@@ -290,6 +381,72 @@ _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
       outputHint: '模块文档生成状态',
       optional: true
     },
+    {
+      name: '生成业务流程和术语表（可选）',
+      prompt: `根据模块依赖关系和源码，生成跨模块业务流程文档和术语表。
+
+⚠️ 这一步是可选的。如果项目模块简单、流程不明显，可以跳过。
+
+### flows/ 目录
+目标目录：\`.sillyspec/docs/<project>/flows/\`
+
+根据 _module-map.yaml 中的模块依赖关系，识别跨模块业务流程：
+1. 读取 \`_module-map.yaml\`，分析 used_by 链条
+2. 用 grep/rg 搜索路由定义、API 端点、事件处理
+3. 识别跨模块的完整业务流程（如登录→下单→支付）
+4. 每个流程生成一个文件：\`flows/<flow-name>.md\`
+
+文件格式：
+\`\`\`markdown
+# <flow-name>
+
+## 目标
+（一句话描述这个流程的业务目的）
+
+## 参与模块
+- module-a：做什么
+- module-b：做什么
+
+## 流程摘要
+\`\`\`text
+step1 → step2 → step3
+\`\`\`
+
+## 失败回滚
+| 失败点 | 处理 |
+|---|---|
+\`\`\`
+
+### glossary.md
+目标文件：\`.sillyspec/docs/<project>/glossary.md\`
+
+提取项目专有术语：
+1. 用 grep 搜索 TODO/FIXME 注释中的术语定义
+2. 从数据库表注释提取
+3. 从 README 和文档中提取定义段落
+
+文件格式：
+\`\`\`markdown
+# Glossary
+
+## Session
+在本项目中，session 指...（项目内特殊含义）
+
+## Order
+订单主实体，代表...（业务定义）
+\`\`\`
+
+### 操作
+1. 分析模块依赖关系，识别可能的业务流程
+2. 如果发现 2+ 个跨模块流程，生成 flows/ 文档
+3. 提取术语生成 glossary.md
+4. 如果没有明显的流程或术语，跳过此步
+
+### 输出
+生成的文件路径列表（或"已跳过"）`,
+      outputHint: '流程和术语表生成状态',
+      optional: true
+    },
     {
       name: '自检和提交',
       prompt: `验证扫描完整性，清理并提交。
@@ -298,8 +455,9 @@ _module-map.yaml 生成结果（已存在/已生成/模块列表）`,
 1. 检查 7 份 scan 文档是否全部生成
 2. 检查模块文档状态（如有）
 3. 自检门控：ARCHITECTURE（技术栈+Schema摘要）、CONVENTIONS（隐形规则+代码风格）、STRUCTURE（目录结构）、INTEGRATIONS（外部依赖）、TESTING（测试现状）、CONCERNS（技术债务）、PROJECT（项目概览）
-4. 清理：\`rm -f .sillyspec/docs/<project>/scan/_env-detect.md\`
-5. \`git add .sillyspec/\` — 暂存扫描结果（不要 commit，由用户通过统一提交工具处理）
+4. 检查 flows/ 和 glossary.md 是否已生成（如有）
+5. 清理：\`rm -f .sillyspec/docs/<project>/scan/_env-detect.md\`
+6. \`git add .sillyspec/\` — 暂存扫描结果（不要 commit，由用户通过统一提交工具处理）
 
 ### 输出
 扫描完整性报告

package/src/stages/verify.js

@@ -63,9 +63,10 @@ export const definition = {
 6. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
 7. 根据 design.md 的文件变更清单匹配 _module-map.yaml 中的模块
 8. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
+9. **检查模块索引可信度**：如果相关模块的 needs_review 为 true，提示"该模块索引可能不可信，需要回看模块卡片或源码"
 
 ### 输出
-文件加载确认清单（含模块文档）`,
+文件加载确认清单（含模块文档 + 索引可信度）`,
       outputHint: '文件确认清单',
       optional: false
     },