ims-flow-dashboard 1.2.0

package/scan.mjs

@@ -0,0 +1,779 @@
+#!/usr/bin/env node
+// ims-flow-dashboard 扫描器
+// 用法: node scan.mjs [serve] [过滤词] [--open] [--port=N]
+//   快照模式: node scan.mjs [过滤词] [--open]   → 生成单文件 dashboard.html
+//   服务模式: node scan.mjs serve [--port=N]     → 本地服务, 页面内「重新扫描」按钮生效
+// 扫描 projects.json 注册的根目录下所有 openspec/ 工作区,
+// 收集变更/工件/任务进度/健康检查数据, 生成单文件 dashboard.html
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as http from 'node:http';
+import { exec } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const TOOL_DIR = path.dirname(fileURLToPath(import.meta.url));
+const USER_CONFIG_DIR = path.join(os.homedir(), '.imsflow');
+// 配置查找顺序: 包目录 projects.json (clone/开发模式) → ~/.imsflow/projects.json (npm 全局安装模式)
+const PROJECTS_FILE = fs.existsSync(path.join(TOOL_DIR, 'projects.json'))
+  ? path.join(TOOL_DIR, 'projects.json')
+  : path.join(USER_CONFIG_DIR, 'projects.json');
+const OUT_HTML = path.join(TOOL_DIR, 'dashboard.html');
+
+// ---------- 工具函数 ----------
+
+function readText(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+function exists(p) {
+  try { return fs.statSync(p).isDirectory() || fs.statSync(p).isFile(); } catch { return false; }
+}
+
+function listDir(p) {
+  try { return fs.readdirSync(p, { withFileTypes: true }); } catch { return []; }
+}
+
+// 官方 spec-driven 工件兜底（仓库没有自定义 schema 时）
+const OFFICIAL_ARTIFACTS = [
+  { id: 'proposal', generates: 'proposal.md' },
+  { id: 'specs', generates: 'specs/**/*.md' },
+  { id: 'design', generates: 'design.md' },
+  { id: 'tasks', generates: 'tasks.md' },
+];
+
+// ---------- schema.yaml 解析（行级状态机, 只提取需要的字段） ----------
+
+function parseSchemaYaml(yamlText) {
+  const artifacts = [];
+  const lines = yamlText.split(/\r?\n/);
+  let current = null;
+  let inGates = false;
+  let inRequires = false;
+
+  for (const raw of lines) {
+    const line = raw; // 保留缩进
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // 新工件: "  - id: xxx"
+    const m = trimmed.match(/^-\s+id:\s*(\S+)/);
+    if (m && /^-\s/.test(trimmed)) {
+      current = { id: m[1], generates: null, gates: [], requires: [] };
+      artifacts.push(current);
+      inGates = false;
+      inRequires = false;
+      continue;
+    }
+
+    if (!current) continue;
+
+    // requires 块列表项: "- proposal" (无冒号)
+    if (inRequires && /^-\s+[^:#]+$/.test(trimmed)) {
+      current.requires.push(trimmed.replace(/^-\s+/, '').trim());
+      continue;
+    }
+
+    const kv = trimmed.match(/^(?:-\s*)?([\w-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const [, key, value] = kv;
+
+    if (key === 'requires') {
+      inGates = false;
+      inRequires = true;
+      current.requires = [];
+      if (value.startsWith('[')) {
+        current.requires = value.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
+        inRequires = false;
+      } else if (value) {
+        current.requires = [value.trim()];
+        inRequires = false;
+      }
+    } else if (key === 'generates') {
+      current.generates = value.replace(/^["']|["']$/g, '');
+      inGates = false;
+      inRequires = false;
+    } else if (key === 'gates') {
+      inGates = true;
+      inRequires = false;
+    } else if (inGates && (key === 'sections-present' || key === 'must-contain')) {
+      // 行内: - sections-present: [A, B, C]  或  - must-contain: "erDiagram"
+      if (value.startsWith('[')) {
+        const inner = value.slice(1, -1);
+        const items = inner.split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+        current.gates.push({ 'sections-present': items });
+      } else {
+        const v = value.replace(/^["']|["']$/g, '');
+        if (v) current.gates.push({ 'must-contain': v });
+      }
+    } else if (key === 'id' && !value) {
+      // 忽略
+    }
+  }
+  return artifacts.filter(a => a.generates);
+}
+
+function loadWorkspaceSchema(openspecDir) {
+  // 1. config.yaml 拿 schema 名
+  const configText = readText(path.join(openspecDir, 'config.yaml'));
+  let schemaName = 'spec-driven';
+  if (configText) {
+    const m = configText.match(/^schema:\s*(\S+)/m);
+    if (m) schemaName = m[1];
+  }
+  // 2. 读 schemas/<name>/schema.yaml
+  const schemaText = readText(path.join(openspecDir, 'schemas', schemaName, 'schema.yaml'));
+  let artifacts = null;
+  if (schemaText) {
+    artifacts = parseSchemaYaml(schemaText);
+  }
+  if (!artifacts || artifacts.length === 0) {
+    artifacts = schemaName === 'spec-driven'
+      ? OFFICIAL_ARTIFACTS
+      : OFFICIAL_ARTIFACTS; // 找不到 schema 定义一律按官方 4 工件兜底
+  }
+  return { schemaName, artifacts };
+}
+
+// ---------- 单个变更的工件与任务收集 ----------
+
+function artifactFiles(changeDir, generates) {
+  // 返回 [{rel, content}]；glob 工件收集所有匹配文件
+  const files = [];
+  if (generates.includes('*')) {
+    const base = generates.split('/')[0];
+    const specsDir = path.join(changeDir, base);
+    (function walk(dir) {
+      for (const e of listDir(dir)) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) walk(full);
+        else if (e.name.endsWith('.md')) {
+          files.push({ rel: path.relative(changeDir, full).replace(/\\/g, '/'), content: readText(full) || '' });
+        }
+      }
+    })(specsDir);
+  } else {
+    const full = path.join(changeDir, generates);
+    if (fs.existsSync(full)) {
+      files.push({ rel: generates, content: readText(full) || '' });
+    }
+  }
+  return files;
+}
+
+function artifactExists(changeDir, generates) {
+  if (generates.includes('*')) {
+    return artifactFiles(changeDir, generates).length > 0;
+  }
+  return fs.existsSync(path.join(changeDir, generates));
+}
+
+function collectTasks(changeDir) {
+  const text = readText(path.join(changeDir, 'tasks.md'));
+  if (text === null) return null;
+  const groups = [];
+  let group = null;
+  for (const raw of text.split(/\r?\n/)) {
+    const hm = raw.match(/^##\s+(.*)/);
+    if (hm) {
+      group = { title: hm[1].trim(), items: [] };
+      groups.push(group);
+      continue;
+    }
+    const tm = raw.match(/^(-|\s*)-\s+\[( |x|X)\]\s+(.*)$/);
+    if (tm) {
+      if (!group) { group = { title: '任务', items: [] }; groups.push(group); }
+      group.items.push({ text: tm[3].trim(), done: tm[2].toLowerCase() === 'x' });
+    }
+  }
+  const items = groups.flatMap(g => g.items);
+  const done = items.filter(i => i.done).length;
+  return { open: items.length - done, done, total: items.length, groups };
+}
+
+// ---------- 健康检查 ----------
+
+const DDL_RE = /^\s*(ALTER TABLE|CREATE TABLE|CREATE INDEX|DROP TABLE|DROP INDEX)/im;
+
+function healthCheck(change, artifacts) {
+  const issues = [];   // {level: 'error'|'warn', msg}
+  const checks = [];   // {name, pass, detail} 用于页面展示
+
+  const byGen = {};
+  for (const a of artifacts) byGen[a.generates] = a;
+
+  // 1. gates 检查（规则来自 schema.yaml, 与源码门禁同源）
+  for (const a of artifacts) {
+    if (!a.gates || a.gates.length === 0) continue;
+    const existsNow = change.artifacts.find(x => x.id === a.id)?.exists;
+    if (!existsNow) continue; // 工件未产出, 由进度反映, 不算违规
+
+    const file = path.join(change.dir, a.generates);
+    const content = readText(file) || '';
+    for (const gate of a.gates) {
+      if (gate['sections-present']) {
+        for (const s of gate['sections-present']) {
+          const pass = content.includes(s);
+          checks.push({ name: `${a.generates} 含检查节「${s}」`, pass });
+          if (!pass) issues.push({ level: 'error', msg: `${a.generates} 缺检查节「${s}」` });
+        }
+      }
+      if (gate['must-contain']) {
+        const pass = content.includes(gate['must-contain']);
+        checks.push({ name: `${a.generates} 含「${gate['must-contain']}」`, pass });
+        if (!pass) issues.push({ level: 'error', msg: `${a.generates} 缺少「${gate['must-contain']}」` });
+      }
+    }
+  }
+
+  // 2. 时序检查: apply 后工件(有 requires: [tasks] 的)已产出但 tasks 未全勾
+  const applyArtifacts = artifacts.filter(a => a.requiresTasks);
+  // requiresTasks 由 parseSchemaYaml 补充 —— 简化: generates 以 ims- 开头且非 api/db 的(test-plan/release-steps/retrospective)
+  const postApply = artifacts.filter(a => /^ims-(test-plan|release-steps|retrospective)\.md$/.test(a.generates));
+  if (change.tasks && change.tasks.open > 0) {
+    for (const a of postApply) {
+      const existsNow = change.artifacts.find(x => x.id === a.id)?.exists;
+      if (existsNow) {
+        const msg = `时序违约: tasks 还有 ${change.tasks.open} 项未勾选, 但 ${a.generates} 已产出`;
+        checks.push({ name: `${a.generates} 产出时序`, pass: false });
+        issues.push({ level: 'warn', msg });
+      }
+    }
+  }
+
+  // 3. DDL 权威源漂移: release-steps 有 DDL 而 db-changes 没有
+  const rs = change.artifacts.find(x => /release-steps/.test(x.generates) && x.exists);
+  const db = change.artifacts.find(x => /db-changes/.test(x.generates) && x.exists);
+  if (rs && db) {
+    const rsContent = readText(path.join(change.dir, rs.generates)) || '';
+    const dbContent = readText(path.join(change.dir, db.generates)) || '';
+    if (DDL_RE.test(rsContent) && !DDL_RE.test(dbContent)) {
+      const msg = 'DDL 漂移: DDL 只出现在 release-steps, ims-db-changes.md 未记录';
+      checks.push({ name: 'DDL 权威源唯一', pass: false });
+      issues.push({ level: 'error', msg });
+    }
+  }
+
+  return { issues, checks };
+}
+
+// ---------- 产物完整性（对照模板节结构） ----------
+
+// 人工 review 标记文件（change 目录存在其一即视为已审查）
+const REVIEW_FILES = ['review.md', 'reviewed.md'];
+
+function stripSectionNo(title) {
+  // 去掉 "1. " / "一、" / "2、" 等节编号
+  return title.replace(/^\s*\d+[.、)]?\s*/, '').replace(/^[一二三四五六七八九十]+\s*[、.]\s*/, '').replace(/[*`]/g, '').trim();
+}
+
+function extractSections(text) {
+  // 提取 ## 级标题（跳过代码块），返回去编号后的节名数组
+  const names = new Set();
+  let inCode = false;
+  for (const raw of (text || '').split(/\r?\n/)) {
+    if (raw.trim().startsWith('```')) { inCode = !inCode; continue; }
+    if (inCode) continue;
+    const m = raw.match(/^##\s+(.+)$/);
+    if (m) {
+      const name = stripSectionNo(m[1]);
+      // 过滤模板占位标题: <!-- xxx --> / {xxx} 等
+      if (name && !/[<>{}]/.test(name)) names.add(name);
+    }
+  }
+  return [...names];
+}
+
+function artifactCompleteness(changeDir, artifactMeta, templateDir) {
+  // 已声明 sections-present gates 的工件以 gates 为权威源, 跳过模板比对避免重复
+  if (!templateDir || artifactMeta.generates.includes('*')) return null;
+  if ((artifactMeta.gates || []).some(g => g['sections-present'])) return null;
+  const tpl = readText(path.join(templateDir, path.basename(artifactMeta.generates)));
+  if (!tpl) return null;
+  const tplSecs = extractSections(tpl);
+  if (!tplSecs.length) return null;
+  const content = readText(path.join(changeDir, artifactMeta.generates)) || '';
+  const cSecs = new Set(extractSections(content));
+  const missing = tplSecs.filter(s => !cSecs.has(s) && !content.includes(s));
+  return { total: tplSecs.length, missing };
+}
+
+// ---------- 生命周期阶段 ----------
+
+const STAGE_LABEL = {
+  created: '刚创建', proposing: '提议中', ready: '待实施', applying: '实施中',
+  applied: '待审查', reviewed: '已审查', archived: '已归档',
+};
+
+function computeLifecycle(change, artifactsMeta, archived) {
+  const requiresOf = id => (artifactsMeta.find(a => a.id === id) || {}).requires || [];
+  // apply 后工件 = 直接 requires tasks 的工件（ims-test-plan / ims-release-steps）
+  const postApplyIds = artifactsMeta.filter(a => requiresOf(a.id).includes('tasks')).map(a => a.id);
+  const planningArts = artifactsMeta.filter(a => !postApplyIds.includes(a.id));
+  const produced = new Set(change.artifacts.filter(a => a.exists).map(a => a.id));
+  const planningProduced = planningArts.filter(a => produced.has(a.id)).length;
+  const postApplyProduced = postApplyIds.filter(id => produced.has(id)).length;
+  const tasks = change.tasks;
+  const tasksAllDone = !!tasks && tasks.total > 0 && tasks.open === 0;
+  const tasksStarted = !!tasks && tasks.done > 0;
+  const planningAll = planningArts.length > 0 && planningProduced === planningArts.length;
+  const postApplyAll = postApplyIds.length === 0 || postApplyProduced === postApplyIds.length;
+
+  let stage;
+  if (archived) stage = 'archived';
+  else if (change.reviewed) stage = 'reviewed';
+  else if (planningAll && tasksAllDone && postApplyAll) stage = 'applied';
+  else if (planningAll && (tasksStarted || postApplyProduced > 0)) stage = 'applying';
+  else if (planningAll) stage = 'ready';
+  else if (planningProduced > 0) stage = 'proposing';
+  else stage = 'created';
+
+  const missingPlanning = planningArts.filter(a => !produced.has(a.id)).map(a => a.generates);
+  const missingPost = postApplyIds.filter(id => !produced.has(id)).map(id => (artifactsMeta.find(a => a.id === id) || {}).generates);
+  const incomplete = change.artifacts
+    .filter(a => a.exists && a.missing && a.missing.length)
+    .map(a => ({ id: a.id, file: a.generates, missing: a.missing }));
+
+  let nextAction = '';
+  switch (stage) {
+    case 'created': nextAction = '刚创建 — 运行 /opsx:propose 开始生成提议工件'; break;
+    case 'proposing': nextAction = '提议中 — 待产出: ' + missingPlanning.join('、'); break;
+    case 'ready': nextAction = '规划工件齐全，可执行 /opsx:apply 开始实施' + (incomplete.length ? `（注意：${incomplete.length} 个产物结构不完整）` : ''); break;
+    case 'applying': {
+      const parts = [];
+      if (tasks && tasks.open > 0) parts.push(`剩 ${tasks.open} 项任务未完成`);
+      if (missingPost.length) parts.push('待产出: ' + missingPost.join('、'));
+      nextAction = '实施中 — ' + (parts.join('；') || '进行中');
+      break;
+    }
+    case 'applied': nextAction = '全部产物已产出 — 等待人工 review（在变更目录创建 review.md 即标记已审查）'; break;
+    case 'reviewed': nextAction = '已审查 — 可执行 openspec archive 归档'; break;
+    case 'archived': nextAction = '已归档'; break;
+  }
+
+  return {
+    stage,
+    label: STAGE_LABEL[stage],
+    reviewed: !!change.reviewed,
+    planning: { total: planningArts.length, produced: planningProduced },
+    postApply: { total: postApplyIds.length, produced: postApplyProduced },
+    tasksAllDone,
+    incomplete,
+    nextAction,
+  };
+}
+
+// ---------- 需求标题提取（proposal.md 的 H1 + 引用行 + 禅道/story 单号） ----------
+
+function extractTitle(changeDir, artifacts) {
+  const proposal = artifacts.find(a => a.id === 'proposal');
+  const file = proposal ? path.join(changeDir, proposal.generates) : path.join(changeDir, 'proposal.md');
+  const text = readText(file);
+  if (!text) return null;
+
+  const lines = text.split(/\r?\n/);
+
+  // 1. H1 标题（在进入 ## 正文前找）
+  let title = null;
+  for (const l of lines) {
+    if (/^##\s+/.test(l)) break; // 无 H1
+    const m = l.match(/^#\s+(.+)$/);
+    if (m) { title = m[1].trim(); break; }
+  }
+  if (title) {
+    title = title.replace(/^提案[：:]\s*/, '');
+    title = title.replace(/[（(][\w#-]+[)）]\s*$/i, '').trim(); // 去尾部英文 slug 括注
+  } else {
+    // 2. 无 H1: 用 ## Why 首行做标题（常见形态: "需求 568937【模块】标题：正文…" 或长句）
+    let why = '';
+    for (let i = 0; i < lines.length; i++) {
+      if (!/^##\s+Why/.test(lines[i])) continue;
+      for (let j = i + 1; j < lines.length && j < i + 8; j++) {
+        const t = lines[j].trim();
+        if (t && !t.startsWith('#')) { why = t; break; }
+      }
+      break;
+    }
+    if (why) {
+      const ci = why.indexOf('：');
+      title = (ci > 0 && ci <= 45) ? why.slice(0, ci)
+        : (why.split('。')[0] || why).slice(0, 45);
+    }
+  }
+
+  // 3. meta 行: 引用行(> …)或 "（对应）禅道需求…" 开头的行
+  let meta = '';
+  for (const l of lines.slice(0, 12)) {
+    const t = l.trim();
+    if (/^>\s*\S/.test(t)) { meta = t.replace(/^>\s*/, ''); break; }
+    if (/^(对应)?禅道需求/.test(t)) { meta = t; break; }
+  }
+
+  // 4. 需求单号: 前 15 行内按优先级匹配
+  const src = lines.slice(0, 15).join(' ');
+  const m = src.match(/禅道(?:需求)?[：:#\s]*(\d{4,})/)
+    || src.match(/需求\s*[#：:]?\s*(\d{4,})/)
+    || src.match(/story\s*#?(\d{4,})/i)
+    || src.match(/#(\d{5,})/);
+  const reqId = m ? m[1] : null;
+
+  if (!title && !meta && !reqId) return null;
+  return { text: title || '', meta, reqId };
+}
+
+// ---------- 工作区扫描 ----------
+
+// 变更来源元数据: change 目录下 meta.yaml 的 created-by / created-at
+// 约定值: trae | tuanjieai | workbuddy | human (其他值原样显示)
+function extractMeta(changeDir) {
+  const text = readText(path.join(changeDir, 'meta.yaml'));
+  if (!text) return null;
+  const by = text.match(/^created-by:\s*(\S+)/m);
+  if (!by) return null;
+  const at = text.match(/^created-at:\s*([^\s]+)/m);
+  return { createdBy: by[1], createdAt: at ? at[1] : null };
+}
+
+function scanChange(changeDir, artifacts, opts = {}) {
+  const includeContent = opts.includeContent !== false;
+  const name = path.basename(changeDir);
+  const change = {
+    name,
+    dir: changeDir,
+    artifacts: [],
+    tasks: null,
+    reviewed: false,
+    health: { issues: [], checks: [] },
+  };
+  // 人工 review 标记
+  change.reviewed = listDir(changeDir).some(e => e.isFile() && REVIEW_FILES.includes(e.name.toLowerCase()));
+  for (const a of artifacts) {
+    const files = includeContent ? artifactFiles(changeDir, a.generates) : [];
+    const entry = {
+      id: a.id,
+      generates: a.generates,
+      description: a.description || '',
+      exists: includeContent ? files.length > 0 : artifactExists(changeDir, a.generates),
+      files,
+      missing: null,
+      sectionsTotal: null,
+    };
+    if (entry.exists && includeContent) {
+      const comp = artifactCompleteness(changeDir, a, opts.templateDir);
+      if (comp) { entry.missing = comp.missing; entry.sectionsTotal = comp.total; }
+    }
+    change.artifacts.push(entry);
+  }
+  change.tasks = collectTasks(changeDir);
+  change.title = extractTitle(changeDir, artifacts);
+  change.meta = extractMeta(changeDir);
+  change.health = healthCheck(change, artifacts);
+  change.lifecycle = computeLifecycle(change, artifacts, !!opts.archived);
+  return change;
+}
+
+function scanWorkspace(rootDir, openspecDir, baseRoot) {
+  const { schemaName, artifacts } = loadWorkspaceSchema(openspecDir);
+  const changesDir = path.join(openspecDir, 'changes');
+  const archiveDir = path.join(changesDir, 'archive');
+  const templateDir = path.join(openspecDir, 'schemas', schemaName, 'templates');
+
+  const active = listDir(changesDir)
+    .filter(e => e.isDirectory() && e.name !== 'archive')
+    .map(e => scanChange(path.join(changesDir, e.name), artifacts, { includeContent: true, templateDir }));
+
+  const archived = listDir(archiveDir)
+    .filter(e => e.isDirectory())
+    .map(e => scanChange(path.join(archiveDir, e.name), artifacts, { includeContent: true, templateDir, archived: true }));
+
+  // 主规格统计
+  const specsDir = path.join(openspecDir, 'specs');
+  let specCount = 0, reqCount = 0;
+  (function walk(dir) {
+    for (const e of listDir(dir)) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.name === 'spec.md') {
+        specCount++;
+        const t = readText(full) || '';
+        reqCount += (t.match(/^### Requirement:/gm) || []).length;
+      }
+    }
+  })(specsDir);
+
+  return {
+    root: rootDir,
+    baseRoot: baseRoot || rootDir, // 所属扫描根（projects.json 里配置的根）
+    openspecDir,
+    schemaName,
+    active,
+    archived,
+    specs: { capabilities: specCount, requirements: reqCount },
+  };
+}
+
+function findWorkspaces(roots) {
+  const workspaces = [];
+  for (const root of roots) {
+    if (!exists(root)) { console.error(`[warn] 根目录不存在: ${root}`); continue; }
+    // root 自身的 openspec/
+    const own = path.join(root, 'openspec');
+    if (exists(own)) workspaces.push(scanWorkspace(root, own, root));
+    // 一级子目录的 openspec/
+    for (const e of listDir(root)) {
+      if (!e.isDirectory() || e.name === 'openspec') continue;
+      const sub = path.join(root, e.name, 'openspec');
+      if (exists(sub)) workspaces.push(scanWorkspace(path.join(root, e.name), sub, root));
+    }
+  }
+  return workspaces;
+}
+
+// ---------- 主流程 ----------
+
+function loadRoots() {
+  let roots = [];
+  try {
+    const cfg = JSON.parse(readText(PROJECTS_FILE) || '{}');
+    roots = cfg.roots || [];
+  } catch (e) {
+    console.error('[warn] projects.json 读取失败:', e.message);
+  }
+  if (roots.length === 0) {
+    console.error('未配置扫描根目录。请在以下任一位置创建 projects.json (参考 projects.example.json):');
+    console.error('  ' + path.join(TOOL_DIR, 'projects.json') + '        (源码 clone 模式)');
+    console.error('  ' + path.join(USER_CONFIG_DIR, 'projects.json') + '          (npm 全局安装模式)');
+    process.exit(1);
+  }
+  return roots;
+}
+
+function filterRoots(roots, filterWord) {
+  if (!filterWord) return roots;
+  const w = filterWord.toLowerCase();
+  const hit = roots.filter(r => r.toLowerCase().includes(w) || path.basename(r).toLowerCase().includes(w));
+  if (hit.length === 0) {
+    console.error(`没有匹配「${filterWord}」的根路径。已配置: ${roots.join(', ')}`);
+    process.exit(1);
+  }
+  return hit;
+}
+
+// serve 模式安全版: 读取失败/为空返回空数组, 不退出进程（由 API 决定如何响应）
+function safeLoadRoots() {
+  try {
+    const cfg = JSON.parse(readText(PROJECTS_FILE) || '{}');
+    return Array.isArray(cfg.roots) ? cfg.roots.filter(r => typeof r === 'string' && r.trim()) : [];
+  } catch { return []; }
+}
+// 页面「工作区」面板增/删根后持久化到 projects.json
+function saveRoots(roots) {
+  fs.mkdirSync(path.dirname(PROJECTS_FILE), { recursive: true });
+  fs.writeFileSync(PROJECTS_FILE, JSON.stringify({ roots }, null, 2) + '\n', 'utf-8');
+}
+// 读 POST body（JSON, 上限 64KB）
+function readBody(req, limit = 64 * 1024) {
+  return new Promise((resolve, reject) => {
+    const chunks = []; let size = 0;
+    req.on('data', c => {
+      size += c.length;
+      if (size > limit) { reject(new Error('请求体过大')); req.destroy(); return; }
+      chunks.push(c);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+    req.on('error', reject);
+  });
+}
+function isDirectory(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+function samePath(a, b) {
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+function scanAll(filterWord, rootsOverride) {
+  const roots = rootsOverride || filterRoots(loadRoots(), filterWord);
+  console.log(`扫描 ${roots.length} 个根目录...`);
+  const workspaces = findWorkspaces(roots);
+  for (const ws of workspaces) {
+    console.log(`  ✓ ${ws.root} (schema=${ws.schemaName}, active=${ws.active.length}, archived=${ws.archived.length})`);
+  }
+  return { generatedAt: new Date().toISOString(), roots, workspaces };
+}
+
+// 注入 HTML 模板（模板与扫描器分离, 便于独立调整页面）
+const TEMPLATE_FILE = path.join(TOOL_DIR, 'template.html');
+const TEMPLATE = readText(TEMPLATE_FILE);
+if (!TEMPLATE) {
+  console.error(`模板缺失: ${TEMPLATE_FILE}`);
+  process.exit(1);
+}
+
+// 模板热加载 —— serve 是常驻进程: 若只在启动时读一次模板, 改完 template.html 后
+//   ① 页面永远吐旧 UI; ② /api/rescan 会把旧 UI 写回 dashboard.html, 覆盖掉磁盘上的新构建。
+// 所以每次构建前比对 mtime, 变了就重新读盘。
+let _tplText = TEMPLATE, _tplMtime = 0;
+try { _tplMtime = fs.statSync(TEMPLATE_FILE).mtimeMs; } catch {}
+function templateMtime() { try { return fs.statSync(TEMPLATE_FILE).mtimeMs; } catch { return 0; } }
+function currentTemplate() {
+  const mt = templateMtime();
+  if (mt && mt !== _tplMtime) {
+    const t = readText(TEMPLATE_FILE);
+    if (t) {
+      _tplText = t; _tplMtime = mt;
+      console.log(`[template] 检测到模板更新, 已重新加载 (${(t.length / 1024).toFixed(1)} KB)`);
+    }
+  }
+  return _tplText;
+}
+
+// 必须用函数替换: json 内容含 $` $' $& 等序列时, 字符串替换会做特殊展开破坏数据
+function buildHtml(data) {
+  const json = JSON.stringify(data).replace(/</g, '\\u003c');
+  const tpl = currentTemplate();
+  const html = tpl.replace('__DATA__', () => json);
+  // 构建指纹: 排查「页面还是旧的」时, 一眼看出这页是哪份模板、什么时候生成的
+  const stamp = `<!-- imsflow build: template=${_tplMtime} ${new Date().toISOString()} tpl=${tpl.length}B -->`;
+  return /<!DOCTYPE html[^>]*>/i.test(html) ? html.replace(/<!DOCTYPE html[^>]*>/i, (m) => m + '\n' + stamp) : html;
+}
+
+const args = process.argv.slice(2);
+const wantOpen = args.includes('--open');
+const positional = args.filter(a => !a.startsWith('--'));
+const serveMode = positional.includes('serve');
+// 非 flag 位置参数（除 serve 外）= 根路径过滤词（按名称或路径模糊匹配）
+const filterWord = positional.filter(a => a !== 'serve').pop() || null;
+
+if (serveMode) {
+  // ---- 服务模式: imsflow serve [--port=N] ----
+  // 页面内「重新扫描」按钮调 /api/rescan 实时重扫, 解决快照模式的刷新问题
+  const portArg = args.find(a => a.startsWith('--port='));
+  const PORT = portArg ? parseInt(portArg.slice(7), 10) : 17771;
+  let cachedHtml = null;
+  let cachedTpl = 0;    // 当前 cachedHtml 所用的模板 mtime
+  let lastData = null;  // 最近一次扫描数据, 模板热更新时用它重建页面（不必重扫）
+  // 统一「重建 + 落盘」入口, 保证内存缓存与磁盘快照一致
+  const refresh = (data) => {
+    lastData = data;
+    cachedHtml = buildHtml(data);
+    cachedTpl = templateMtime();
+    try { fs.writeFileSync(OUT_HTML, cachedHtml, 'utf-8'); } catch {}
+    return cachedHtml;
+  };
+
+  const server = http.createServer(async (req, res) => {
+    const url = (req.url || '/').split('?')[0];
+    const sendJson = (code, obj) => {
+      res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8' });
+      res.end(JSON.stringify(obj));
+    };
+    try {
+      if (url === '/api/roots' && req.method === 'GET') {
+        // 页面「工作区」面板拉取已配置的扫描根
+        sendJson(200, { ok: true, roots: safeLoadRoots(), configPath: PROJECTS_FILE });
+      } else if (url === '/api/roots' && req.method === 'POST') {
+        // 增/删扫描根: 校验后持久化到 projects.json, 再全量重扫（loadRoots 重新读盘）
+        const body = JSON.parse(await readBody(req));
+        const action = body.action;
+        const raw = String(body.root || '').trim();
+        if (!raw) { sendJson(400, { ok: false, error: '路径为空' }); return; }
+        const roots = safeLoadRoots();
+        if (action === 'add') {
+          const abs = path.resolve(raw);
+          if (!isDirectory(abs)) { sendJson(400, { ok: false, error: `目录不存在: ${abs}` }); return; }
+          if (roots.some(r => samePath(r, abs))) { sendJson(400, { ok: false, error: '该路径已在扫描列表中' }); return; }
+          roots.push(abs);
+          saveRoots(roots);
+        } else if (action === 'remove') {
+          if (!roots.some(r => samePath(r, raw))) { sendJson(400, { ok: false, error: '该路径不在扫描列表中' }); return; }
+          if (roots.length <= 1) { sendJson(400, { ok: false, error: '至少保留一个扫描根，移除后列表为空会导致服务无内容可扫' }); return; }
+          saveRoots(roots.filter(r => !samePath(r, raw)));
+        } else {
+          sendJson(400, { ok: false, error: 'action 必须是 add 或 remove' });
+          return;
+        }
+        const data = scanAll(null);
+        refresh(data);
+        console.log(`[roots:${action}] ${raw} · 现在 ${data.workspaces.length} 个工作区`);
+        sendJson(200, { ok: true, roots: data.roots });
+      } else if (url === '/api/rescan') {
+        // GET = 全量重扫（页面路径筛选器负责聚焦）; POST {roots:[...]} = 只扫勾选的根, 不落盘
+        let subset = null;
+        if (req.method === 'POST') {
+          const body = JSON.parse(await readBody(req));
+          const configured = safeLoadRoots();
+          subset = [...new Set((Array.isArray(body.roots) ? body.roots : []).filter(r => configured.some(c => samePath(c, String(r)))))];
+          if (subset.length === 0) { sendJson(400, { ok: false, error: '未选择任何已配置的扫描根' }); return; }
+        } else if (safeLoadRoots().length === 0) {
+          sendJson(500, { ok: false, error: 'projects.json 未配置任何扫描根' });
+          return;
+        }
+        const t0 = Date.now();
+        const data = scanAll(null, subset);
+        refresh(data); // 顺手刷新磁盘快照
+        console.log(`[rescan] ${subset ? `选中 ${subset.length} 根` : '全量'} · ${data.workspaces.length} 个工作区 · ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify(data));
+      } else if (url === '/' || url === '/index.html') {
+        if (!cachedHtml) {
+          refresh(scanAll(null));
+          console.log(`初始扫描完成, 页面 ${(cachedHtml.length / 1024).toFixed(0)} KB`);
+        } else if (templateMtime() !== cachedTpl && lastData) {
+          // 模板文件改过了 → 用上次扫描数据重建（不必重扫），刷新页面即可看到新 UI
+          refresh(lastData);
+          console.log('[template] 热更新生效, 页面已重建');
+        }
+        // no-store: 不设的话浏览器会启发式缓存, 模板改完刷新页面仍是旧 UI,
+        // 会被误判成「没生效」而重复排查构建链路。
+        res.writeHead(200, {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-store, no-cache, must-revalidate',
+          'Pragma': 'no-cache',
+        });
+        res.end(cachedHtml);
+      } else {
+        res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('not found');
+      }
+    } catch (e) {
+      // 扫描中途出错不能让进程崩掉 —— 崩了用户页面就直接"不见了"
+      console.error('[serve] 请求处理出错:', e.message);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+        res.end('扫描失败: ' + e.message);
+      }
+    }
+  });
+
+  server.on('error', (e) => {
+    if (e.code === 'EADDRINUSE') {
+      console.error(`端口 ${PORT} 已被占用（可能已有一个 imsflow serve 在跑，浏览器直接开 http://localhost:${PORT} 即可）。`);
+      console.error(`换端口: imsflow serve --port=17772`);
+    } else {
+      console.error(e.message);
+    }
+    process.exit(1);
+  });
+
+  server.listen(PORT, () => {
+    const url = `http://localhost:${PORT}`;
+    console.log(`imsflow serve 已启动: ${url}`);
+    console.log(`模板: ${TEMPLATE_FILE}`);
+    console.log(`       ${(currentTemplate().length / 1024).toFixed(1)} KB · mtime ${_tplMtime}（改动后刷新页面即生效, 无需重启）`);
+    console.log('页面内「↻ 重新扫描」按钮已激活（快照模式无此能力）');
+    console.log('Ctrl+C 退出');
+    exec(`start "" "${url}"`);
+  });
+} else {
+  // ---- 快照模式: imsflow [过滤词] [--open] ----
+  const data = scanAll(filterWord);
+  const html = buildHtml(data);
+  fs.writeFileSync(OUT_HTML, html, 'utf-8');
+  const sizeKB = (fs.statSync(OUT_HTML).size / 1024).toFixed(0);
+  console.log(`\n已生成: ${OUT_HTML} (${sizeKB} KB)`);
+  if (wantOpen) {
+    exec(`start "" "${OUT_HTML}"`);
+    console.log('已在浏览器打开（快照模式；页面内重扫需 imsflow serve）');
+  }
+}