sandtable 0.3.0

package/src/cli/sandtable.js

@@ -0,0 +1,970 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const { exec } = require('child_process');
+const { scan } = require('../scanner/scan');
+const { build, EVENT_TYPES, classifyEventPriority } = require('../builder/build');
+
+const VERSION = '0.3.0';
+const command = process.argv[2] || 'help';
+const root = process.argv[3] || process.cwd();
+
+// ---- detectEnvironment: 扫描项目，检测所有可用的 IDE 指令目录 ----
+function detectEnvironment(projectRoot) {
+  var envs = [];
+
+  // 1. Cursor: .cursor/rules/
+  if (fs.existsSync(path.join(projectRoot, '.cursor', 'rules'))) {
+    envs.push({ type: 'cursor', targetDir: '.cursor/rules', targetFile: '.cursor/rules/sandtable-event-log.mdc', format: 'mdc', entryLine: null });
+  }
+
+  // 2. libero: docs/skills/
+  if (fs.existsSync(path.join(projectRoot, 'docs', 'skills'))) {
+    envs.push({ type: 'docs-skills', targetDir: 'docs/skills', targetFile: 'docs/skills/sandtable-event-log.md', format: 'md', entryLine: null });
+  }
+
+  // 3. Claude Code: .claude/
+  if (fs.existsSync(path.join(projectRoot, '.claude'))) {
+    envs.push({ type: 'claude', targetDir: '.claude/skills/sandtable-event-log', targetFile: '.claude/skills/sandtable-event-log/SKILL.md', format: 'skill-md', entryLine: null });
+  }
+
+  // 4. Trae: .trae/rules/
+  if (fs.existsSync(path.join(projectRoot, '.trae', 'rules'))) {
+    envs.push({ type: 'trae', targetDir: '.trae/rules', targetFile: '.trae/rules/sandtable-event-log.md', format: 'md', entryLine: null });
+  }
+
+  // 5. Cline: .clinerules/
+  if (fs.existsSync(path.join(projectRoot, '.clinerules'))) {
+    // .clinerules can be a file or directory
+    var clineStat = fs.statSync(path.join(projectRoot, '.clinerules'));
+    if (clineStat.isDirectory()) {
+      envs.push({ type: 'cline', targetDir: '.clinerules', targetFile: '.clinerules/sandtable-event-log.md', format: 'md', entryLine: null });
+    }
+  }
+
+  // 6. GitHub Copilot: .github/
+  if (fs.existsSync(path.join(projectRoot, '.github'))) {
+    var githubDir = path.join(projectRoot, '.github', 'instructions');
+    if (!fs.existsSync(githubDir)) {
+      // Will create on --apply
+    }
+    envs.push({ type: 'github', targetDir: '.github/instructions', targetFile: '.github/instructions/sandtable-event-log.instructions.md', format: 'instructions-md', entryLine: null });
+  }
+
+  // 7. AGENTS.md exists (but no exclusive directory matched above)
+  var hasExclusiveDir = envs.some(function(e) {
+    return e.type === 'cursor' || e.type === 'docs-skills' || e.type === 'claude' || e.type === 'trae' || e.type === 'cline' || e.type === 'github';
+  });
+
+  if (!hasExclusiveDir) {
+    var agentsPath = path.join(projectRoot, 'AGENTS.md');
+    var claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+
+    if (fs.existsSync(agentsPath)) {
+      envs.push({ type: 'agents', targetDir: '.sandtable', targetFile: '.sandtable/rules.md', format: 'rules-md',
+        entryLine: '--apply 时将自动注入事件日志规则到 AGENTS.md', autoInject: true });
+    } else if (fs.existsSync(claudeMdPath)) {
+      envs.push({ type: 'claude-md', targetDir: '.sandtable', targetFile: '.sandtable/rules.md', format: 'rules-md',
+        entryLine: '--apply 时将自动注入事件日志规则到 CLAUDE.md', autoInject: true });
+    } else {
+      // Nothing detected — offer generic
+      envs.push({ type: 'generic', targetDir: '.sandtable', targetFile: '.sandtable/rules.md', format: 'rules-md',
+        entryLine: '--apply 时将自动创建 AGENTS.md 并注入事件日志规则', autoInject: true });
+    }
+  }
+
+  return envs;
+}
+
+// ---- generateRuleContent: 按格式和语言生成规则内容 ----
+function generateRuleContent(format, lang) {
+  var isZh = lang === 'zh';
+
+  var bodyLines = [];
+  if (isZh) {
+    bodyLines.push('# Sandtable 事件记录');
+    bodyLines.push('');
+    bodyLines.push('当以下重要事件发生时，调用 `sandtable event-log` 记录到项目仪表盘。');
+    bodyLines.push('');
+    bodyLines.push('## 触发场景');
+    bodyLines.push('');
+    bodyLines.push('| 场景 | 命令示例 |');
+    bodyLines.push('|------|----------|');
+    bodyLines.push('| 需求对齐/方案拍板 | `sandtable event-log 1 "确定使用JWT登录方案" alignment high @user "登录" "docs/specs/login.md" --continue <threadId>` |');
+    bodyLines.push('| 规格文档变更 | `sandtable event-log 2 "API响应格式新增分页字段" spec-change medium @AI "API" "docs/specs/api.md"` |');
+    bodyLines.push('| 代码完成/待审查 | `sandtable event-log 3 "完成用户注册接口" code-done medium @AI "注册"` |');
+    bodyLines.push('| 审查通过 | `sandtable event-log 3 "登录模块审查通过" review-pass medium @user "登录"` |');
+    bodyLines.push('| 审查驳回/返工 | `sandtable event-log 3 "支付模块需重写异常处理" review-reject high @user "支付"` |');
+    bodyLines.push('| Git 重要操作 | `sandtable event-log 3 "合并feature/login到main" git-merge medium @AI "git"` |');
+    bodyLines.push('| 测试通过 | `sandtable event-log 4 "用户模块单测全部通过" test-pass medium` |');
+    bodyLines.push('| 测试失败 | `sandtable event-log 4 "支付集成测试3个失败" test-fail high` |');
+    bodyLines.push('| 审批/交接完成 | `sandtable event-log 5 "发版审批通过" approved high @user` |');
+    bodyLines.push('| 基础设施变更 | `sandtable event-log 6 "数据库迁移v2.1完成" infra medium` |');
+    bodyLines.push('| 人类提出新需求 | `sandtable event-log 1 "用户要求增加导出PDF功能" new-requirement high @user "导出"` |');
+    bodyLines.push('| 教训/坑位沉淀 | `sandtable event-log 7 "批量操作前必须备份，防止数据丢失" lesson high @AI "备份"` |');
+    bodyLines.push('');
+    bodyLines.push('## 参数说明');
+    bodyLines.push('');
+    bodyLines.push('- **typeId**: 1=对齐与拍板 2=规格演进 3=代码变更 4=测试与质量 5=审批与交接 6=运维与基建 7=教训沉淀');
+    bodyLines.push('- **impact**: high / medium / low');
+    bodyLines.push('- **actor**: @AI 或 @user');
+    bodyLines.push('- **tags**: 逗号分隔');
+    bodyLines.push('- **refDoc**: 关联文档路径（可选）');
+    bodyLines.push('- **threadId**: `--continue <id>` 关联同一线程的多个事件');
+    bodyLines.push('');
+    bodyLines.push('## 线程示例');
+    bodyLines.push('');
+    bodyLines.push('```bash');
+    bodyLines.push('# 开始一个线程');
+    bodyLines.push('sandtable event-log 3 "开始实现登录功能" code-start medium @AI "登录" "" login-2026-05-24');
+    bodyLines.push('# 追加到同一线程');
+    bodyLines.push('sandtable event-log 3 "登录实现完成" code-done medium @AI "登录" "" --continue login-2026-05-24');
+    bodyLines.push('```');
+    bodyLines.push('');
+    bodyLines.push('## 注意');
+    bodyLines.push('');
+    bodyLines.push('- 每次重要操作后主动记录，不要等用户提醒');
+    bodyLines.push('- 标题要有意义，便于后续在仪表盘中检索');
+    bodyLines.push('- 关联事件使用 --continue 保持线程连贯');
+  } else {
+    bodyLines.push('# Sandtable Event Logging');
+    bodyLines.push('');
+    bodyLines.push('Record significant development events using `sandtable event-log` for the project dashboard.');
+    bodyLines.push('');
+    bodyLines.push('## Trigger Scenarios');
+    bodyLines.push('');
+    bodyLines.push('| Scenario | Example Command |');
+    bodyLines.push('|----------|----------------|');
+    bodyLines.push('| Alignment/decision | `sandtable event-log 1 "Decided on JWT auth" alignment high @user "auth" "docs/specs/auth.md" --continue <threadId>` |');
+    bodyLines.push('| Spec evolution | `sandtable event-log 2 "Added pagination to API response" spec-change medium @AI "API" "docs/specs/api.md"` |');
+    bodyLines.push('| Code complete/review | `sandtable event-log 3 "User registration endpoint done" code-done medium @AI "registration"` |');
+    bodyLines.push('| Review passed | `sandtable event-log 3 "Login module review passed" review-pass medium @user "login"` |');
+    bodyLines.push('| Review rejected/rework | `sandtable event-log 3 "Payment module needs error handling rewrite" review-reject high @user "payment"` |');
+    bodyLines.push('| Git operations | `sandtable event-log 3 "Merged feature/login to main" git-merge medium @AI "git"` |');
+    bodyLines.push('| Tests passed | `sandtable event-log 4 "All user module unit tests passing" test-pass medium` |');
+    bodyLines.push('| Tests failed | `sandtable event-log 4 "3 payment integration tests failing" test-fail high` |');
+    bodyLines.push('| Approval/handover | `sandtable event-log 5 "Release approval granted" approved high @user` |');
+    bodyLines.push('| Infra/ops | `sandtable event-log 6 "Database migration v2.1 applied" infra medium` |');
+    bodyLines.push('| New requirements | `sandtable event-log 1 "User requests PDF export feature" new-requirement high @user "export"` |');
+    bodyLines.push('| Lessons learned | `sandtable event-log 7 "Always backup before batch ops" lesson high @AI "backup"` |');
+    bodyLines.push('');
+    bodyLines.push('## Parameters');
+    bodyLines.push('');
+    bodyLines.push('- **typeId**: 1=Alignment 2=Spec 3=Code 4=Test 5=Approval 6=Infra 7=Lesson');
+    bodyLines.push('- **impact**: high / medium / low');
+    bodyLines.push('- **actor**: @AI or @user');
+    bodyLines.push('- **tags**: comma-separated');
+    bodyLines.push('- **refDoc**: optional linked document path');
+    bodyLines.push('- **threadId**: `--continue <id>` to chain events in a thread');
+    bodyLines.push('');
+    bodyLines.push('## Thread Example');
+    bodyLines.push('');
+    bodyLines.push('```bash');
+    bodyLines.push('# Start a thread');
+    bodyLines.push('sandtable event-log 3 "Start implementing login" code-start medium @AI "login" "" login-2026-05-24');
+    bodyLines.push('# Continue the thread');
+    bodyLines.push('sandtable event-log 3 "Login implementation complete" code-done medium @AI "login" "" --continue login-2026-05-24');
+    bodyLines.push('```');
+    bodyLines.push('');
+    bodyLines.push('## Notes');
+    bodyLines.push('');
+    bodyLines.push('- Record events proactively after significant actions');
+    bodyLines.push('- Use meaningful titles for dashboard searchability');
+    bodyLines.push('- Use --continue to keep related events in one thread');
+  }
+
+  var body = bodyLines.join('\n');
+
+  switch (format) {
+    case 'mdc':
+      // Cursor .mdc with YAML frontmatter
+      return '---\nalwaysApply: true\n---\n\n' + body;
+    case 'skill-md':
+      // Claude Code SKILL.md with YAML frontmatter
+      return '---\nname: sandtable-event-log\ndescription: ' + (isZh ? '记录重要开发事件到 sandtable 项目仪表盘' : 'Record significant development events to the sandtable project dashboard') + '\n---\n\n' + body;
+    case 'instructions-md':
+      // GitHub Copilot instructions
+      return '# Sandtable Event Logging\n\n' + bodyLines.slice(1).join('\n');
+    default:
+      // Plain markdown for docs/skills, .trae/rules, .clinerules, .sandtable/rules.md
+      return body;
+  }
+}
+
+// ---- injectToMainDoc: 向 CLAUDE.md / AGENTS.md 追加事件日志规则 ----
+function injectToMainDoc(filePath, lang) {
+  var isZh = lang === 'zh';
+  var marker = 'sandtable event-log';
+  var existing = '';
+  if (fs.existsSync(filePath)) {
+    existing = fs.readFileSync(filePath, 'utf-8');
+    if (existing.indexOf(marker) !== -1) return false; // already injected
+  }
+  var lines = [];
+  if (isZh) {
+    lines.push('');
+    lines.push('## Sandtable 事件日志');
+    lines.push('');
+    lines.push('**每次完成可独立表述的代码/设计/决策动作后，立即调用 `sandtable event-log` 记录。不要等用户提醒。**');
+    lines.push('');
+    lines.push('详细规则见 `.sandtable/rules.md`。');
+  } else {
+    lines.push('');
+    lines.push('## Sandtable Event Logging');
+    lines.push('');
+    lines.push('**After every significant code/design/decision action, immediately call `sandtable event-log` to record it. Do not wait for a reminder.**');
+    lines.push('');
+    lines.push('See `.sandtable/rules.md` for details.');
+  }
+  var content = existing + lines.join('\n') + '\n';
+  writeWithBackup(filePath, content);
+  return true;
+}
+
+// ---- writeClaudeCodeHook: 创建 SessionStart 强提醒 hook ----
+function writeClaudeCodeHook(projectRoot, lang) {
+  var hooksDir = path.join(projectRoot, '.claude', 'hooks');
+  var hookPath = path.join(hooksDir, 'sandtable-reminder.sh');
+  var isZh = lang === 'zh';
+
+  var script = '#!/bin/bash\n';
+  if (isZh) {
+    script += '# Sandtable 事件日志强提醒 — 每次 session 开始时注入\n';
+    script += "cat <<'SANDBTABLE_EOR'\n";
+    script += '<system-reminder>\n';
+    script += '【Sandtable 事件日志铁律】\n';
+    script += '本次 session 中，每完成一个独立动作（代码修改/设计定稿/决策拍板/错误修复），\n';
+    script += '必须立即调用 sandtable event-log 记录。禁止事后补录，禁止等用户提醒。\n';
+    script += '命令速查: sandtable event-log <typeId> "标题" <subtype> <impact> @AI "标签"\n';
+    script += 'typeId: 1=对齐拍板 2=规格演进 3=代码变更 4=测试质量 5=审批交接 6=运维基建 7=教训沉淀\n';
+    script += '详细规则见 .sandtable/rules.md\n';
+    script += '</system-reminder>\n';
+    script += 'SANDBTABLE_EOR\n';
+  } else {
+    script += '# Sandtable event log reminder — injected at session start\n';
+    script += "cat <<'SANDBTABLE_EOR'\n";
+    script += '<system-reminder>\n';
+    script += '[Sandtable Event Log Rule]\n';
+    script += 'After every significant action (code change, design decision, bug fix) in this session,\n';
+    script += 'immediately call sandtable event-log to record it. No backfilling, no waiting for reminders.\n';
+    script += 'Quick ref: sandtable event-log <typeId> "title" <subtype> <impact> @AI "tags"\n';
+    script += 'See .sandtable/rules.md for details.\n';
+    script += '</system-reminder>\n';
+    script += 'SANDBTABLE_EOR\n';
+  }
+
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+  writeWithBackup(hookPath, script);
+
+  // Update .claude/settings.json to register the hook
+  var settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  var settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8')); } catch(e) {}
+  }
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+
+  // Check if already registered
+  var alreadyRegistered = settings.hooks.SessionStart.some(function(h) {
+    return h.command && h.command.indexOf('sandtable-reminder') !== -1;
+  });
+  if (!alreadyRegistered) {
+    settings.hooks.SessionStart.push({
+      command: 'bash ' + hookPath.replace(/\\/g, '/')
+    });
+    writeWithBackup(settingsPath, JSON.stringify(settings, null, 2));
+  }
+
+  return true;
+}
+
+// ---- initCommand: dry-run 报告 or --apply 写入 ----
+function initCommand(projectRoot, applyMode, lang, hooksMode) {
+  var envs = detectEnvironment(projectRoot);
+  var sandtableDir = path.join(projectRoot, '.sandtable');
+  var configPath = path.join(sandtableDir, 'config.json');
+  var eventLogPath = path.join(sandtableDir, 'event-log.jsonl');
+
+  // ---- Print detection report ----
+  console.log('Sandtable Init — 项目环境扫描报告');
+  console.log('项目: ' + projectRoot);
+  console.log('');
+
+  if (envs.length === 0) {
+    console.log('未检测到任何已知 IDE 指令目录。');
+    console.log('将使用通用模式：.sandtable/rules.md');
+  } else {
+    console.log('检测到 ' + envs.length + ' 个指令目标:');
+    for (var i = 0; i < envs.length; i++) {
+      var e = envs[i];
+      console.log('  ' + (i + 1) + '. [' + e.type + '] → ' + e.targetFile);
+    }
+  }
+
+  console.log('');
+  console.log('将创建/更新:');
+  console.log('  - ' + configPath);
+  console.log('  - ' + eventLogPath + ' (空容器)');
+  for (var i = 0; i < envs.length; i++) {
+    console.log('  - ' + envs[i].targetFile);
+  }
+
+  // Entry line hints — separate auto-inject from manual
+  var entryHints = [], autoHints = [];
+  for (var i = 0; i < envs.length; i++) {
+    if (envs[i].entryLine) {
+      if (envs[i].autoInject) autoHints.push(envs[i].entryLine);
+      else entryHints.push(envs[i].entryLine);
+    }
+  }
+  if (autoHints.length > 0) {
+    console.log('');
+    console.log('⚡ --apply 将自动注入:');
+    for (var i = 0; i < autoHints.length; i++) {
+      console.log('  ' + (i + 1) + '. ' + autoHints[i]);
+    }
+  }
+  if (entryHints.length > 0) {
+    console.log('');
+    console.log('⚠  手动步骤:');
+    for (var i = 0; i < entryHints.length; i++) {
+      console.log('  ' + (i + 1) + '. ' + entryHints[i]);
+    }
+  }
+
+  // Hook availability for Claude Code
+  var hasClaudeEnv = envs.some(function(e) { return e.type === 'claude'; });
+  if (hasClaudeEnv) {
+    console.log('');
+    if (hooksMode) {
+      console.log('⚡ SessionStart 强提醒 hook → .claude/hooks/sandtable-reminder.sh');
+    } else {
+      console.log('💡 可选: --hooks 安装 SessionStart 强提醒 hook（每次 session 开头注入日志铁律）');
+    }
+  }
+
+  if (!applyMode) {
+    console.log('');
+    console.log('以上为 dry-run 报告。要实际写入文件，请运行:');
+    console.log('  sandtable init --apply' + (lang ? ' --lang ' + lang : '') + (hasClaudeEnv ? ' [--hooks]' : ''));
+    console.log('');
+    console.log('已存在文件将在写入前备份为 .bak.<timestamp>');
+    return;
+  }
+
+  // ---- --apply: write files ----
+  console.log('');
+  console.log('正在写入文件...');
+
+  // 1. Create .sandtable/ directory
+  if (!fs.existsSync(sandtableDir)) {
+    fs.mkdirSync(sandtableDir, { recursive: true });
+    console.log('  ✓ 创建 ' + sandtableDir);
+  }
+
+  // 2. Write .sandtable/config.json
+  var config = {
+    version: '0.3.0',
+    createdAt: new Date().toISOString(),
+    projectRoot: projectRoot,
+    paths: {
+      convention: 'docs/convention',
+      spec: 'docs/specs',
+      archive: 'docs/archive'
+    }
+  };
+  writeWithBackup(configPath, JSON.stringify(config, null, 2));
+
+  // 3. Create empty event-log.jsonl
+  if (!fs.existsSync(eventLogPath)) {
+    fs.writeFileSync(eventLogPath, '', 'utf-8');
+    console.log('  ✓ 创建 ' + eventLogPath + ' (空)');
+  } else {
+    console.log('  - ' + eventLogPath + ' 已存在，保留');
+  }
+
+  // 4. Copy .sandtable.json template
+  var templateSrc = path.join(__dirname, '..', '..', 'templates', '.sandtable.template.json');
+  var sandtableJsonDest = path.join(projectRoot, '.sandtable.json');
+  if (fs.existsSync(templateSrc)) {
+    if (!fs.existsSync(sandtableJsonDest)) {
+      writeWithBackup(sandtableJsonDest, fs.readFileSync(templateSrc, 'utf-8'));
+    } else {
+      console.log('  - .sandtable.json 已存在，保留');
+    }
+  }
+
+  // 5. Write rule files
+  for (var i = 0; i < envs.length; i++) {
+    var env = envs[i];
+    var fullPath = path.join(projectRoot, env.targetFile);
+    var targetDir = path.dirname(fullPath);
+
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+
+    var content = generateRuleContent(env.format, lang);
+    writeWithBackup(fullPath, content);
+  }
+
+  // 6. Inject event-log rule into main doc (CLAUDE.md / AGENTS.md)
+  var mainDocInjected = false;
+  for (var i = 0; i < envs.length; i++) {
+    var env = envs[i];
+    var mainDocPath = null;
+    if (env.type === 'agents') {
+      mainDocPath = path.join(projectRoot, 'AGENTS.md');
+    } else if (env.type === 'claude-md') {
+      mainDocPath = path.join(projectRoot, 'CLAUDE.md');
+    } else if (env.type === 'generic') {
+      mainDocPath = path.join(projectRoot, 'AGENTS.md');
+    }
+    if (mainDocPath) {
+      var injected = injectToMainDoc(mainDocPath, lang);
+      if (injected) {
+        console.log('  ✓ 注入事件日志规则 → ' + path.basename(mainDocPath));
+        mainDocInjected = true;
+      } else if (fs.existsSync(mainDocPath)) {
+        console.log('  - ' + path.basename(mainDocPath) + ' 已有 sandtable 规则，跳过');
+      }
+    }
+  }
+
+  // 7. Install Claude Code SessionStart hook (only with --hooks)
+  if (hooksMode && hasClaudeEnv) {
+    writeClaudeCodeHook(projectRoot, lang);
+    console.log('  ✓ 安装 SessionStart 强提醒 hook → .claude/hooks/sandtable-reminder.sh');
+  }
+
+  console.log('');
+  console.log('✓ 初始化完成。运行 sandtable build 生成数据，然后 sandtable serve 查看仪表盘。');
+
+  // Only show manual hints for non-main-doc entry types
+  var remainingHints = [];
+  for (var i = 0; i < entryHints.length; i++) {
+    var env = envs[i];
+    if (env && (env.type === 'agents' || env.type === 'claude-md' || env.type === 'generic')) continue;
+    remainingHints.push(entryHints[i]);
+  }
+  if (remainingHints.length > 0) {
+    console.log('');
+    console.log('⚠  别忘了手动步骤:');
+    for (var i = 0; i < remainingHints.length; i++) {
+      console.log('  ' + (i + 1) + '. ' + remainingHints[i]);
+    }
+  }
+}
+
+// ---- writeWithBackup: 写前备份 ----
+function writeWithBackup(filePath, content) {
+  if (fs.existsSync(filePath)) {
+    var bakPath = filePath + '.bak.' + Date.now();
+    fs.copyFileSync(filePath, bakPath);
+    console.log('  ⓘ 备份 ' + path.basename(filePath) + ' → ' + path.basename(bakPath));
+  }
+  fs.writeFileSync(filePath, content, 'utf-8');
+  console.log('  ✓ 写入 ' + filePath);
+}
+
+function enableWatchMode(projectRoot) {
+  var docsDir = path.join(projectRoot, 'docs');
+  var configFile = path.join(projectRoot, '.sandtable.json');
+  var sandtableDir = path.join(projectRoot, '.sandtable');
+
+  console.log('Watch: 监控 docs/ 、.sandtable/ 和 .sandtable.json 变更...');
+
+  function scheduleRebuild() {
+    if (watchTimer) clearTimeout(watchTimer);
+    watchTimer = setTimeout(function() {
+      console.log('\n[watch] 检测到变更，自动 rebuild...');
+      var result = build(projectRoot);
+      console.log('[watch] rebuild 完成 — ' + (result.outputs ? result.outputs.length + ' files' : 'ok'));
+    }, 300); // debounce 300ms
+  }
+
+  var watchTimer = null;
+
+  // Watch docs directory
+  if (fs.existsSync(docsDir)) {
+    try {
+      fs.watch(docsDir, { recursive: true }, function(evt, filename) {
+        if (filename) scheduleRebuild();
+      });
+    } catch (e) {
+      fs.watch(docsDir, function(evt, filename) {
+        if (filename) scheduleRebuild();
+      });
+    }
+  }
+
+  // Watch .sandtable/ directory (event-log.jsonl, token-log.jsonl, etc.)
+  if (fs.existsSync(sandtableDir)) {
+    try {
+      fs.watch(sandtableDir, { recursive: true }, function(evt, filename) {
+        if (filename) scheduleRebuild();
+      });
+    } catch (e) {
+      fs.watch(sandtableDir, function(evt, filename) {
+        if (filename) scheduleRebuild();
+      });
+    }
+  }
+
+  // Watch .sandtable.json
+  if (fs.existsSync(configFile)) {
+    fs.watch(configFile, function(evt, filename) {
+      scheduleRebuild();
+    });
+  }
+}
+
+function startServer(projectRoot, port, openBrowser, watchMode) {
+  const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+    '.png': 'image/png',
+    '.jsonl': 'text/plain; charset=utf-8',
+    '.svg': 'image/svg+xml',
+  };
+
+  const sandtableRoot = path.resolve(__dirname, '..', '..');
+  const allowedPrefixes = [
+    path.join(sandtableRoot, 'dashboard'),
+    path.join(sandtableRoot, 'data'),
+  ];
+
+  function isAllowed(filePath) {
+    // Always allow files under sandtable's dashboard/data
+    for (var i = 0; i < allowedPrefixes.length; i++) {
+      if (filePath.startsWith(allowedPrefixes[i])) return true;
+    }
+    // Allow any file under the project root (but not .env, .git, node_modules, credentials)
+    if (filePath.startsWith(projectRoot)) {
+      var rel = path.relative(projectRoot, filePath);
+      if (rel.startsWith('.git') || rel.startsWith('node_modules') ||
+          rel.startsWith('.env') || rel.includes('credentials') ||
+          rel.includes('.pem') || rel.includes('.pfx')) {
+        return false;
+      }
+      return true;
+    }
+    return false;
+  }
+
+  http.createServer(function(req, res) {
+    var url = req.url === '/' ? '/dashboard/dashboard.html' : req.url;
+    url = url.replace(/^\/(css|js)\//, '/dashboard/$1/');
+
+    var filePath = path.join(sandtableRoot, url);
+
+    // If not found under sandtable root, try project root
+    if (!(fs.existsSync(filePath) && fs.statSync(filePath).isFile())) {
+      var clean = url.split('?')[0].split('#')[0];
+      var projPath = path.join(projectRoot, clean);
+      if (fs.existsSync(projPath) && fs.statSync(projPath).isFile()) {
+        filePath = projPath;
+      }
+    }
+
+    if (!isAllowed(filePath)) {
+      res.writeHead(403, { 'Content-Type': 'text/plain' });
+      return res.end('403 Forbidden');
+    }
+
+    var ext = path.extname(filePath);
+    try {
+      if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+        res.writeHead(200, {
+          'Content-Type': MIME[ext] || 'text/plain',
+          'Cache-Control': 'no-cache, no-store, must-revalidate',
+          'Pragma': 'no-cache',
+          'Expires': '0',
+        });
+        res.end(fs.readFileSync(filePath));
+      } else {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('404 Not Found');
+      }
+    } catch (e) {
+      res.writeHead(500, { 'Content-Type': 'text/plain' });
+      res.end('500: ' + e.message);
+    }
+  }).listen(port, function() {
+    console.log('Sandtable v' + VERSION + ' — http://localhost:' + port);
+    console.log('Project: ' + projectRoot);
+
+    if (watchMode) enableWatchMode(projectRoot);
+
+    if (openBrowser) {
+      var platform = process.platform;
+      var cmd;
+      if (platform === 'darwin') {
+        cmd = 'open http://localhost:' + port;
+      } else if (platform === 'win32') {
+        cmd = 'start http://localhost:' + port;
+      } else {
+        cmd = 'xdg-open http://localhost:' + port;
+      }
+      exec(cmd, function(err) {
+        if (err) console.log('请手动打开: http://localhost:' + port);
+      });
+    }
+  });
+}
+
+switch (command) {
+  case 'scan':
+    console.log(JSON.stringify(scan(root), null, 2));
+    break;
+  case 'build':
+    console.log(JSON.stringify(build(root), null, 2));
+    break;
+  case 'init': {
+    var applyMode = process.argv.indexOf('--apply') !== -1;
+    var hooksMode = process.argv.indexOf('--hooks') !== -1;
+    var langIdx = process.argv.indexOf('--lang');
+    var lang = 'zh';
+    if (langIdx !== -1 && process.argv[langIdx + 1]) {
+      lang = process.argv[langIdx + 1] === 'en' ? 'en' : 'zh';
+    }
+    initCommand(process.cwd(), applyMode, lang, hooksMode);
+    break;
+  }
+  case 'summarize': {
+    const scanResult = scan(root);
+    const missing = scanResult.files.filter(f => !f.hasSummary);
+    console.log(JSON.stringify({
+      command: 'summarize',
+      projectRoot: root,
+      totalFiles: scanResult.totalFiles,
+      missingCount: missing.length,
+      files: missing.map(f => ({
+        path: f.path,
+        category: f.category,
+        elementType: f.elementType,
+        title: f.title
+      }))
+    }, null, 2));
+    break;
+  }
+  case 'version':
+    console.log('sandtable v' + VERSION);
+    break;
+  case 'serve': {
+    var port = parseInt(process.argv[3], 10) || 3000;
+    var watchMode = process.argv.indexOf('--watch') !== -1;
+    startServer(process.cwd(), port, true, watchMode);
+    break;
+  }
+  case 'event-log': {
+    // Record event: sandtable event-log <typeId> <title> [subtype] [impact] [actor] [tags] [refDoc] [threadId] [--tokens <in>,<out>] [--continue <threadId>]
+
+    // Extract named flags first, then build clean positional args
+    var rawArgs = process.argv.slice(3); // everything after "event-log"
+    var contThreadId = null;
+    var tokensVal = null;
+    var cleanArgs = [];
+    for (var ai = 0; ai < rawArgs.length; ai++) {
+      if (rawArgs[ai] === '--continue' && ai + 1 < rawArgs.length) {
+        contThreadId = rawArgs[ai + 1]; ai++; // skip value
+      } else if (rawArgs[ai] === '--tokens' && ai + 1 < rawArgs.length) {
+        tokensVal = rawArgs[ai + 1]; ai++; // skip value
+      } else {
+        cleanArgs.push(rawArgs[ai]);
+      }
+    }
+
+    var typeId = cleanArgs[0] || '3';
+    var title = cleanArgs[1] || '';
+    var subtype = cleanArgs[2] || 'manual';
+    var impact = cleanArgs[3] || 'medium';
+    var actor = cleanArgs[4] || 'AI';
+    var tagsRaw = cleanArgs[5] || '';
+    var refDoc = cleanArgs[6] || '';
+    var threadId = contThreadId || cleanArgs[7] || '';
+
+    if (!title) {
+      console.log('用法: sandtable event-log <typeId> <title> [subtype] [impact] [actor] [tags] [refDoc] [threadId] [--tokens <in>,<out>] [--continue <threadId>]');
+      console.log('  typeId: 1=对齐与拍板 2=规格演进 3=代码变更 4=测试与质量 5=审批与交接 6=运维与基建 7=教训沉淀');
+      process.exit(1);
+    }
+
+    if (!EVENT_TYPES[typeId]) {
+      console.log('错误：typeId 必须为 1-7');
+      console.log('  1=对齐与拍板 2=规格演进 3=代码变更 4=测试与质量 5=审批与交接 6=运维与基建 7=教训沉淀');
+      process.exit(1);
+    }
+
+    // Resolve project root
+    var projectRoot = cleanArgs[8] || process.cwd();
+
+    var sandtableDir = path.join(projectRoot, '.sandtable');
+    if (!fs.existsSync(sandtableDir)) fs.mkdirSync(sandtableDir, { recursive: true });
+
+    var tags = tagsRaw ? tagsRaw.split(',').map(function(t) { return t.trim(); }) : [];
+    var ref = refDoc ? { doc: refDoc } : {};
+
+    var eventId = 'evt-' + Date.now().toString(36) + '-' + Math.random().toString(36).substring(2, 8);
+
+    var event = {
+      id: eventId,
+      timestamp: new Date().toISOString(),
+      type: EVENT_TYPES[typeId] || '代码变更',
+      typeId: typeId,
+      subtype: subtype,
+      title: title,
+      ref: ref,
+      impact: impact,
+      actor: actor,
+      tags: tags,
+      threadId: threadId || null,
+    };
+    event.priority = classifyEventPriority(event);
+
+    // Write event-log.jsonl
+    var logPath = path.join(sandtableDir, 'event-log.jsonl');
+    fs.appendFileSync(logPath, JSON.stringify(event) + '\n');
+
+    // Write audit log
+    var auditPath = path.join(sandtableDir, 'audit.log');
+    var auditEntry = JSON.stringify({
+      timestamp: event.timestamp,
+      command: 'event-log',
+      eventId: eventId,
+      type: event.type,
+      title: title,
+      cwd: projectRoot,
+    });
+    fs.appendFileSync(auditPath, auditEntry + '\n');
+
+    console.log('event-log: [' + event.priority + '] ' + event.type + ' — ' + title + (threadId ? ' (thread: ' + threadId + ')' : ''));
+
+    // --tokens <in>,<out> : auto-log token usage for this event
+    if (tokensVal) {
+      var tokensParts = tokensVal.split(',');
+      var tIn = parseInt(tokensParts[0], 10) || 0;
+      var tOut = parseInt(tokensParts[1], 10) || 0;
+      if (tIn > 0 || tOut > 0) {
+        var COST_PER_1K = { input: 0.003, output: 0.006 }; // DeepSeek V4 Pro ¥/1K
+        var tCost = (tIn / 1000) * COST_PER_1K.input + (tOut / 1000) * COST_PER_1K.output;
+        tCost = Math.round(tCost * 10000) / 10000;
+        var tokenEntry = {
+          timestamp: event.timestamp,
+          skill: 'event-log',
+          tokensIn: tIn,
+          tokensOut: tOut,
+          totalTokens: tIn + tOut,
+          cost: tCost,
+          source: 'event-log',
+          eventId: eventId,
+          note: null,
+        };
+        var tokenLogPath = path.join(sandtableDir, 'token-log.jsonl');
+        fs.appendFileSync(tokenLogPath, JSON.stringify(tokenEntry) + '\n');
+        console.log('  token-log: ' + (tIn + tOut).toLocaleString() + ' tokens (est. ¥' + tCost + ')');
+      }
+    }
+    break;
+  }
+  case 'token-log': {
+    var skill = process.argv[3] || '';
+    var tokensIn = parseInt(process.argv[4], 10) || 0;
+    var tokensOut = parseInt(process.argv[5], 10) || 0;
+    var note = process.argv[6] || '';
+    var projectRoot = process.argv[7] || process.cwd();
+
+    if (!skill) {
+      console.log('用法: sandtable token-log <skill> <tokensIn> <tokensOut> [note] [projectRoot]');
+      console.log('  skill: 操作名称（如 build, event-log, scan）');
+      console.log('  tokensIn: 输入 token 数');
+      console.log('  tokensOut: 输出 token 数');
+      process.exit(1);
+    }
+
+    var sandtableDir = path.join(projectRoot, '.sandtable');
+    if (!fs.existsSync(sandtableDir)) fs.mkdirSync(sandtableDir, { recursive: true });
+
+    var COST_PER_1K = { input: 0.003, output: 0.006 }; // DeepSeek V4 Pro ¥/1K
+    var cost = (tokensIn / 1000) * COST_PER_1K.input + (tokensOut / 1000) * COST_PER_1K.output;
+    cost = Math.round(cost * 10000) / 10000;
+
+    var entry = {
+      timestamp: new Date().toISOString(),
+      skill: skill,
+      tokensIn: tokensIn,
+      tokensOut: tokensOut,
+      totalTokens: tokensIn + tokensOut,
+      cost: cost,
+      note: note || null,
+    };
+
+    var logPath = path.join(sandtableDir, 'token-log.jsonl');
+    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n');
+
+    // Audit
+    var auditPath = path.join(sandtableDir, 'audit.log');
+    var auditEntry = JSON.stringify({
+      timestamp: entry.timestamp,
+      command: 'token-log',
+      skill: skill,
+      tokensIn: tokensIn,
+      tokensOut: tokensOut,
+      cwd: projectRoot,
+    });
+    fs.appendFileSync(auditPath, auditEntry + '\n');
+
+    console.log('token-log: ' + skill + ' — ' + (tokensIn + tokensOut).toLocaleString() + ' tokens (est. $' + cost + ')');
+    break;
+  }
+  case 'uninstall': {
+    var applyMode = process.argv.indexOf('--apply') !== -1;
+    var dryRun = !applyMode;
+    var projectRoot = process.argv[3] || process.cwd();
+
+    // Known sandtable files (relative to project root)
+    var knownFiles = [
+      '.sandtable/config.json',
+      '.sandtable/event-log.jsonl',
+      '.sandtable/event-log.errors.jsonl',
+      '.sandtable/audit.log',
+      '.sandtable/token-log.jsonl',
+      '.sandtable/rules.md',
+      '.sandtable.json',
+      '.cursor/rules/sandtable-event-log.mdc',
+      'docs/skills/sandtable-event-log.md',
+      '.claude/skills/sandtable-event-log/SKILL.md',
+      '.trae/rules/sandtable-event-log.md',
+      '.clinerules/sandtable-event-log.md',
+      '.github/instructions/sandtable-event-log.instructions.md',
+    ];
+
+    var existing = [];
+    for (var i = 0; i < knownFiles.length; i++) {
+      var fp = path.join(projectRoot, knownFiles[i]);
+      if (fs.existsSync(fp)) {
+        var stat = fs.statSync(fp);
+        existing.push({ rel: knownFiles[i], abs: fp, isDir: stat.isDirectory() });
+      }
+    }
+
+    // Also check .sandtable/ for any other files
+    var sandtableDir = path.join(projectRoot, '.sandtable');
+    if (fs.existsSync(sandtableDir)) {
+      var entries = fs.readdirSync(sandtableDir);
+      for (var i = 0; i < entries.length; i++) {
+        var full = path.join(sandtableDir, entries[i]);
+        var rel = '.sandtable/' + entries[i];
+        // Skip if already in the list
+        var alreadyKnown = false;
+        for (var j = 0; j < existing.length; j++) {
+          if (existing[j].rel === rel) { alreadyKnown = true; break; }
+        }
+        if (!alreadyKnown) {
+          var stat = fs.statSync(full);
+          existing.push({ rel: rel, abs: full, isDir: stat.isDirectory() });
+        }
+      }
+    }
+
+    if (existing.length === 0) {
+      console.log('未找到 sandtable 创建的文件。');
+      break;
+    }
+
+    console.log('Sandtable Uninstall — ' + (dryRun ? 'dry-run（预览）' : '执行清理'));
+    console.log('项目: ' + projectRoot);
+    console.log('');
+    console.log('找到 ' + existing.length + ' 个 sandtable 文件/目录:');
+    for (var i = 0; i < existing.length; i++) {
+      console.log('  ' + (existing[i].isDir ? '[DIR] ' : '[   ] ') + existing[i].rel);
+    }
+
+    if (dryRun) {
+      console.log('');
+      console.log('以上为 dry-run 预览。要实际删除，请运行:');
+      console.log('  sandtable uninstall --apply');
+      console.log('');
+      console.log('注意：');
+      console.log('  - sandtable 不会删除用户主文档（AGENTS.md、CLAUDE.md 等）');
+      console.log('  - 如果你在 AGENTS.md/CLAUDE.md 中手动添加了 @.sandtable/rules.md 入口行，请自行删除');
+      break;
+    }
+
+    // --apply: delete files
+    console.log('');
+    console.log('正在删除...');
+    var deleted = 0;
+    var errors = 0;
+
+    // Delete files first, then directories (reverse order so files go before their parent dirs)
+    var filesFirst = existing.filter(function(e) { return !e.isDir; });
+    var dirsFirst = existing.filter(function(e) { return e.isDir; });
+
+    for (var i = 0; i < filesFirst.length; i++) {
+      try {
+        fs.unlinkSync(filesFirst[i].abs);
+        console.log('  ✓ 删除 ' + filesFirst[i].rel);
+        deleted++;
+      } catch (e) {
+        console.log('  ✗ 删除失败 ' + filesFirst[i].rel + ': ' + e.message);
+        errors++;
+      }
+    }
+
+    // Try to remove directories (may fail if not empty — that's OK)
+    for (var i = 0; i < dirsFirst.length; i++) {
+      try {
+        fs.rmdirSync(dirsFirst[i].abs);
+        console.log('  ✓ 删除 ' + dirsFirst[i].rel);
+        deleted++;
+      } catch (e) {
+        // Directory not empty or other error — skip silently
+      }
+    }
+
+    // Try to remove .sandtable/ if empty
+    try {
+      fs.rmdirSync(sandtableDir);
+    } catch (e) {
+      // Not empty or doesn't exist — fine
+    }
+
+    console.log('');
+    console.log('✓ 完成: 删除 ' + deleted + ' 个, ' + (errors > 0 ? errors + ' 个失败' : '全部成功'));
+    console.log('');
+    console.log('⚠  如果你在 AGENTS.md/CLAUDE.md 中手动添加了入口行，请自行删除。');
+    break;
+  }
+  case 'help':
+  default:
+    console.log('sandtable v' + VERSION + ' — AI 编程项目可视化指挥面板\n');
+    console.log('用法:');
+    console.log('  sandtable init       [--apply] [--lang zh|en]  扫描环境 + 准备规则文件');
+    console.log('  sandtable scan       [projectRoot]             扫描文档目录');
+    console.log('  sandtable build      [projectRoot]             生成 data/*.json');
+    console.log('  sandtable serve      [port] [--watch]          启动服务 + 打开浏览器');
+    console.log('  sandtable summarize  [projectRoot]             列出缺少摘要块的文件');
+    console.log('  sandtable event-log  <typeId> <title> [...]    记录人机协同事件');
+    console.log('  sandtable token-log  <skill> <in> <out> [...]  追加 token 消耗日志');
+    console.log('  sandtable uninstall  [--apply]                 清理 sandtable 创建的文件');
+    console.log('  sandtable version                              显示版本');
+    console.log('  sandtable help                                 显示帮助');
+    console.log('');
+    console.log('v0.3 新特性:');
+    console.log('  - serve 命令启动 HTTP 服务 + 自动打开浏览器');
+    console.log('  - 双视图架构：doc 树 + 事件流');
+    console.log('  - event-log 记录人机对话中的真实事件');
+    console.log('  - init --apply 写入专属命名空间，不污染主 doc');
+    console.log('  - npm 全局安装：npm install -g sandtable');
+    break;
+}