sandtable 0.3.0 → 0.4.0

package/dashboard/dashboard.html

@@ -285,10 +285,12 @@ body.filter-active #left{border-right-color:#d5dce6}
     <div id="tree-tabs">
       <button class="on" data-c="all">全部</button>
       <button data-c="roadmap">路线图</button>
+      <button data-c="todo">待办</button>
       <button data-c="decision">决策</button>
       <button data-c="spec">规格</button>
       <button data-c="convention">纪律</button>
       <button data-c="ops">运维</button>
+
       <button data-c="archive">档案</button>
     </div>
     <div id="tree"></div>
@@ -358,9 +360,9 @@ function toggleTagCat(cn){
   if(expandedTagCats[cn]){expandedTagCats[cn]=false}else{expandedTagCats[cn]=true}
   renderTagBar();
 }
-var CLABEL = {roadmap:'路线图与进度',decision:'决策记录',spec:'业务规格',convention:'协作纪律',ops:'运维与基建',archive:'历史档案',template:'工具模板',unknown:'未分类'};
-var PRIMARY = {roadmap:1,decision:1};
-var ETYPE = {phase:'roadmap',milestone:'roadmap',task:'roadmap',subtask:'roadmap',roadmap:'roadmap',backlog:'roadmap',conclusion:'roadmap',decision:'decision',refactor:'decision',spec:'spec',intent:'spec',prompt:'spec',convention:'convention',agent:'ops',runbook:'ops',journal:'archive',handover:'archive',plan_doc:'archive',template:'template'};
+var CLABEL = {roadmap:'路线图与进度',todo:'待办清单',decision:'决策记录',spec:'业务规格',convention:'协作纪律',ops:'运维与基建',archive:'历史档案',template:'工具模板',unknown:'未分类'};
+var PRIMARY = {roadmap:1,decision:1,todo:1};
+var ETYPE = {phase:'roadmap',milestone:'roadmap',task:'roadmap',subtask:'roadmap',roadmap:'roadmap',backlog:'todo',todo:'todo',conclusion:'roadmap',decision:'decision',refactor:'decision',spec:'spec',intent:'spec',prompt:'spec',convention:'convention',agent:'ops',runbook:'ops',optimization:'roadmap',journal:'archive',handover:'archive',plan_doc:'archive',template:'template'};
 function normCat(c){if(!c)return'unknown';var m={conventions:'convention',specs:'spec',decisions:'decision',plans:'roadmap',journals:'archive',journal:'archive'};return m[c]||c}
 function normTg(tg){if(!tg||tg==='archived')return'past';return tg}
 

package/harness/install-hooks.sh

@@ -1,17 +1,53 @@
 #!/bin/sh
 # Install sandtable git hooks into the current repo
-# Usage: sh harness/install-hooks.sh [project-root]
+# Usage: sh harness/install-hooks.sh [project-root] [--force]
+
+ROOT=""
+FORCE=0
+for arg in "$@"; do
+  case "$arg" in
+    --force) FORCE=1 ;;
+    *) ROOT="$arg" ;;
+  esac
+done
+ROOT="${ROOT:-$(pwd)}"
 
-ROOT="${1:-$(pwd)}"
 HOOKS_DIR="$ROOT/.git/hooks"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
 if [ ! -d "$HOOKS_DIR" ]; then
   echo "Error: not a git repository (no .git/hooks)"
   exit 1
 fi
 
-cp harness/post-commit "$HOOKS_DIR/post-commit.sandtable"
-cp harness/post-merge "$HOOKS_DIR/post-merge.sandtable"
+# ---- Conflict detection: check for existing non-sandtable hooks ----
+CONFLICTS=""
+for hook in post-commit post-merge; do
+  HOOK_PATH="$HOOKS_DIR/$hook"
+  if [ -f "$HOOK_PATH" ] && ! grep -q "sandtable" "$HOOK_PATH" 2>/dev/null; then
+    CONFLICTS="$CONFLICTS $hook"
+  fi
+done
+
+if [ -n "$CONFLICTS" ] && [ "$FORCE" != "1" ]; then
+  echo "Error: 已有非 sandtable hook 存在:$CONFLICTS"
+  echo ""
+  echo "sandtable 不会覆盖已有 hook，以免破坏其他工具链。选项："
+  echo "  1. 手动合并: 在现有 hook 末尾添加以下行："
+  echo "     sh .git/hooks/<hook>.sandtable"
+  echo "  2. 强制覆盖: sh $(basename "$0") --force"
+  echo ""
+  echo "已有 hook 内容预览:"
+  for hook in $CONFLICTS; do
+    echo "  --- $hook ---"
+    sed 's/^/  | /' "$HOOKS_DIR/$hook"
+    echo "  -------------"
+  done
+  exit 1
+fi
+
+cp "$SCRIPT_DIR/post-commit" "$HOOKS_DIR/post-commit.sandtable"
+cp "$SCRIPT_DIR/post-merge" "$HOOKS_DIR/post-merge.sandtable"
 chmod +x "$HOOKS_DIR/post-commit.sandtable"
 chmod +x "$HOOKS_DIR/post-merge.sandtable"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandtable",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AI 编程项目可视化指挥面板 — 双视图 dashboard，多源数据融合",
   "main": "src/cli/sandtable.js",
   "bin": {

package/server.js

@@ -3,7 +3,27 @@ const fs = require('fs');
 const path = require('path');
 
 const ROOT = path.resolve(__dirname);
-const PORT = parseInt(process.env.PORT || process.argv[2], 10) || 3000;
+const PORT = parseInt(process.env.PORT || process.argv[2], 10) || 5199;
+
+// Parse --host and --token from CLI args (safe by default: 127.0.0.1)
+let HOST = '127.0.0.1';
+let TOKEN = '';
+for (let i = 0; i < process.argv.length; i++) {
+  if (process.argv[i] === '--host' && process.argv[i + 1] && !process.argv[i + 1].startsWith('--')) {
+    HOST = process.argv[i + 1];
+    i++;
+  } else if (process.argv[i] === '--token') {
+    if (process.argv[i + 1] && !process.argv[i + 1].startsWith('--')) {
+      TOKEN = process.argv[i + 1];
+      i++;
+    } else {
+      TOKEN = require('crypto').randomBytes(16).toString('hex');
+    }
+  }
+}
+if ((HOST === '0.0.0.0' || HOST === '::') && !TOKEN) {
+  TOKEN = require('crypto').randomBytes(16).toString('hex');
+}
 
 const MIME = {
   '.html': 'text/html; charset=utf-8',
@@ -31,6 +51,27 @@ function isAllowed(filePath) {
 }
 
 http.createServer((req, res) => {
+  // Token authentication (when binding to public interface)
+  if (TOKEN) {
+    let qIdx = req.url.indexOf('?');
+    let hasToken = false;
+    if (qIdx !== -1) {
+      let qs = req.url.substring(qIdx + 1);
+      let pairs = qs.split('&');
+      for (let pi = 0; pi < pairs.length; pi++) {
+        let kv = pairs[pi].split('=');
+        if (decodeURIComponent(kv[0]) === 'token' && kv[1] === TOKEN) {
+          hasToken = true;
+          break;
+        }
+      }
+    }
+    if (!hasToken) {
+      res.writeHead(401, { 'Content-Type': 'text/plain; charset=utf-8' });
+      return res.end('401 Unauthorized — 请在 URL 后添加 ?token=' + TOKEN);
+    }
+  }
+
   let url = req.url === '/' ? '/dashboard/dashboard.html' : req.url;
   url = url.replace(/^\/(css|js)\//, '/dashboard/$1/');
 
@@ -54,7 +95,8 @@ http.createServer((req, res) => {
     res.writeHead(500, { 'Content-Type': 'text/plain' });
     res.end('500: ' + e.message);
   }
-}).listen(PORT, () => {
-  console.log('Sandtable: http://localhost:' + PORT);
+}).listen(PORT, HOST, () => {
+  console.log('Sandtable: http://' + HOST + ':' + PORT);
+  if (TOKEN) console.log('Token: ' + TOKEN + '  (访问需携带 ?token=' + TOKEN + ')');
   console.log('Project:', ROOT);
 });

package/src/cli/sandtable.js

@@ -8,7 +8,7 @@ const { exec } = require('child_process');
 const { scan } = require('../scanner/scan');
 const { build, EVENT_TYPES, classifyEventPriority } = require('../builder/build');
 
-const VERSION = '0.3.0';
+const VERSION = '0.4.0';
 const command = process.argv[2] || 'help';
 const root = process.argv[3] || process.cwd();
 
@@ -194,33 +194,161 @@ function generateRuleContent(format, lang) {
   }
 }
 
-// ---- injectToMainDoc: 向 CLAUDE.md / AGENTS.md 追加事件日志规则 ----
-function injectToMainDoc(filePath, lang) {
+// ---- injectToMainDoc: 向 CLAUDE.md / AGENTS.md 注入事件日志规则 ----
+// 使用 <!-- sandtable:begin -->...<!-- sandtable:end --> 标记包裹，uninstall 时精确擦除
+function injectToMainDoc(filePath, lang, dryRun) {
   var isZh = lang === 'zh';
-  var marker = 'sandtable event-log';
+  var beginMark = '<!-- sandtable:begin -->';
+  var endMark = '<!-- sandtable:end -->';
   var existing = '';
   if (fs.existsSync(filePath)) {
     existing = fs.readFileSync(filePath, 'utf-8');
-    if (existing.indexOf(marker) !== -1) return false; // already injected
+    if (existing.indexOf(beginMark) !== -1) {
+      if (!dryRun) console.log('  - ' + path.basename(filePath) + ' 已有 sandtable 注入标记，跳过');
+      return false; // already injected
+    }
   }
+
   var lines = [];
+  lines.push('');
+  lines.push(beginMark);
   if (isZh) {
-    lines.push('');
     lines.push('## Sandtable 事件日志');
     lines.push('');
     lines.push('**每次完成可独立表述的代码/设计/决策动作后，立即调用 `sandtable event-log` 记录。不要等用户提醒。**');
     lines.push('');
+    lines.push('命令速查: `sandtable event-log --type code-change --title "标题" --subtype code-done --impact medium --actor @AI --tags "标签" --thread threadId`');
+    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('Quick ref: `sandtable event-log --type code-change --title "title" --subtype code-done --impact medium --actor @AI --tags "tags" --thread threadId`');
+    lines.push('');
     lines.push('See `.sandtable/rules.md` for details.');
   }
-  var content = existing + lines.join('\n') + '\n';
-  writeWithBackup(filePath, content);
+  lines.push(endMark);
+
+  var newContent = existing + lines.join('\n') + '\n';
+
+  if (dryRun) {
+    console.log('  [DRY-RUN] 将注入 ' + path.basename(filePath) + ':');
+    console.log('  --- diff ---');
+    console.log('  + ' + lines.slice(1, -1).join('\n  + '));
+    console.log('  --- end ---');
+    return true;
+  }
+
+  writeWithBackup(filePath, newContent);
+  return true;
+}
+
+// ---- removeFromMainDoc: uninstall 时识别标记精确擦除 ----
+function removeFromMainDoc(filePath, dryRun) {
+  var beginMark = '<!-- sandtable:begin -->';
+  var endMark = '<!-- sandtable:end -->';
+
+  if (!fs.existsSync(filePath)) return false;
+
+  var content = fs.readFileSync(filePath, 'utf-8');
+  var beginIdx = content.indexOf(beginMark);
+  var endIdx = content.indexOf(endMark);
+
+  if (beginIdx === -1 || endIdx === -1) return false;
+
+  // Find the newline before beginMark (to clean up the blank line)
+  var beforeBegin = content.lastIndexOf('\n', beginIdx);
+  if (beforeBegin === -1) beforeBegin = 0;
+
+  var afterEnd = endIdx + endMark.length;
+  // Consume trailing newline if present
+  if (content[afterEnd] === '\n') afterEnd++;
+
+  if (dryRun) {
+    console.log('  [DRY-RUN] 将从 ' + path.basename(filePath) + ' 移除注入块:');
+    console.log('  --- to remove ---');
+    console.log(content.substring(beforeBegin, afterEnd).replace(/^/gm, '  - '));
+    console.log('  --- end ---');
+    return true;
+  }
+
+  var cleaned = content.substring(0, beforeBegin) + content.substring(afterEnd);
+  writeWithBackup(filePath, cleaned);
+  return true;
+}
+
+// ---- appendToGitignore: 自动追加 sandtable 条目到 .gitignore ----
+// 使用 # sandtable:begin/end 标记包裹，uninstall 时精确擦除
+function appendToGitignore(projectRoot, dryRun) {
+  var gitignorePath = path.join(projectRoot, '.gitignore');
+  var beginMark = '# sandtable:begin';
+  var endMark = '# sandtable:end';
+  var existing = '';
+  if (fs.existsSync(gitignorePath)) {
+    existing = fs.readFileSync(gitignorePath, 'utf-8');
+    if (existing.indexOf(beginMark) !== -1) {
+      if (!dryRun) console.log('  - .gitignore 已有 sandtable 标记，跳过');
+      return false;
+    }
+  }
+
+  var block = [
+    '',
+    beginMark,
+    '# Sandtable 自动生成条目 — 请勿手动编辑此块',
+    'data/',
+    '.sandtable/token-log.jsonl',
+    '.sandtable/audit.log',
+    '.sandtable/.token',
+    endMark,
+    '',
+  ].join('\n');
+
+  if (dryRun) {
+    console.log('  [DRY-RUN] 将追加到 .gitignore:');
+    console.log('  --- diff ---');
+    console.log('  + ' + block.replace(/\n/g, '\n  + '));
+    console.log('  --- end ---');
+    return true;
+  }
+
+  writeWithBackup(gitignorePath, existing + block);
+  return true;
+}
+
+// ---- removeFromGitignore: uninstall 时擦除 sandtable gitignore 块 ----
+function removeFromGitignore(projectRoot, dryRun) {
+  var gitignorePath = path.join(projectRoot, '.gitignore');
+  var beginMark = '# sandtable:begin';
+  var endMark = '# sandtable:end';
+
+  if (!fs.existsSync(gitignorePath)) return false;
+
+  var content = fs.readFileSync(gitignorePath, 'utf-8');
+  var beginIdx = content.indexOf(beginMark);
+  var endIdx = content.indexOf(endMark);
+
+  if (beginIdx === -1 || endIdx === -1) return false;
+
+  var beforeBegin = content.lastIndexOf('\n', beginIdx);
+  if (beforeBegin === -1) beforeBegin = 0;
+
+  var afterEnd = endIdx + endMark.length;
+  if (content[afterEnd] === '\n') afterEnd++;
+  if (content[afterEnd] === '\n') afterEnd++; // consume trailing blank line
+
+  if (dryRun) {
+    console.log('  [DRY-RUN] 将从 .gitignore 移除 sandtable 块:');
+    console.log('  --- to remove ---');
+    console.log(content.substring(beforeBegin, afterEnd).replace(/^/gm, '  - '));
+    console.log('  --- end ---');
+    return true;
+  }
+
+  var cleaned = content.substring(0, beforeBegin) + content.substring(afterEnd);
+  writeWithBackup(gitignorePath, cleaned);
   return true;
 }
 
@@ -238,8 +366,8 @@ function writeClaudeCodeHook(projectRoot, lang) {
     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 event-log --type code-change --title "标题" --subtype code-done --impact medium --actor @AI --tags "标签"\n';
+    script += 'type: alignment | spec | code-change | test | approval | ops | lesson\n';
     script += '详细规则见 .sandtable/rules.md\n';
     script += '</system-reminder>\n';
     script += 'SANDBTABLE_EOR\n';
@@ -250,7 +378,8 @@ function writeClaudeCodeHook(projectRoot, lang) {
     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 += 'Quick ref: sandtable event-log --type code-change --title "title" --subtype code-done --impact medium --actor @AI --tags "tags"\n';
+    script += 'type: alignment | spec | code-change | test | approval | ops | lesson\n';
     script += 'See .sandtable/rules.md for details.\n';
     script += '</system-reminder>\n';
     script += 'SANDBTABLE_EOR\n';
@@ -285,7 +414,7 @@ function writeClaudeCodeHook(projectRoot, lang) {
 }
 
 // ---- initCommand: dry-run 报告 or --apply 写入 ----
-function initCommand(projectRoot, applyMode, lang, hooksMode) {
+function initCommand(projectRoot, applyMode, lang, hooksMode, injectAgentsMd) {
   var envs = detectEnvironment(projectRoot);
   var sandtableDir = path.join(projectRoot, '.sandtable');
   var configPath = path.join(sandtableDir, 'config.json');
@@ -325,7 +454,11 @@ function initCommand(projectRoot, applyMode, lang, hooksMode) {
   }
   if (autoHints.length > 0) {
     console.log('');
-    console.log('⚡ --apply 将自动注入:');
+    if (injectAgentsMd) {
+      console.log('⚡ --inject-agents-md 启用 → 将注入主文档:');
+    } else {
+      console.log('💡 可选: --inject-agents-md 自动注入事件日志规则到主文档');
+    }
     for (var i = 0; i < autoHints.length; i++) {
       console.log('  ' + (i + 1) + '. ' + autoHints[i]);
     }
@@ -352,9 +485,11 @@ function initCommand(projectRoot, applyMode, lang, hooksMode) {
   if (!applyMode) {
     console.log('');
     console.log('以上为 dry-run 报告。要实际写入文件，请运行:');
-    console.log('  sandtable init --apply' + (lang ? ' --lang ' + lang : '') + (hasClaudeEnv ? ' [--hooks]' : ''));
+    console.log('  sandtable init --apply' + (lang ? ' --lang ' + lang : '') + (hasClaudeEnv ? ' [--hooks]' : '') + ' [--inject-agents-md]');
     console.log('');
     console.log('已存在文件将在写入前备份为 .bak.<timestamp>');
+    console.log('');
+    console.log('💡 --inject-agents-md: 注入事件日志规则到 CLAUDE.md/AGENTS.md（使用 <!-- sandtable:begin/end --> 标记包裹，uninstall 可精确擦除）');
     return;
   }
 
@@ -370,7 +505,7 @@ function initCommand(projectRoot, applyMode, lang, hooksMode) {
 
   // 2. Write .sandtable/config.json
   var config = {
-    version: '0.3.0',
+    version: '0.4.0',
     createdAt: new Date().toISOString(),
     projectRoot: projectRoot,
     paths: {
@@ -414,25 +549,30 @@ function initCommand(projectRoot, applyMode, lang, hooksMode) {
     writeWithBackup(fullPath, content);
   }
 
-  // 6. Inject event-log rule into main doc (CLAUDE.md / AGENTS.md)
+  // 6. Inject event-log rule into main doc (only with --inject-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 规则，跳过');
+  if (injectAgentsMd) {
+    console.log('');
+    console.log('注入主文档 (--inject-agents-md):');
+    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 usedDryRun = !applyMode; // In dry-run, show diff instead of writing
+        var injected = injectToMainDoc(mainDocPath, lang, usedDryRun);
+        if (injected) {
+          if (applyMode) console.log('  ✓ 注入事件日志规则 → ' + path.basename(mainDocPath));
+          mainDocInjected = true;
+        } else if (fs.existsSync(mainDocPath)) {
+          console.log('  - ' + path.basename(mainDocPath) + ' 已有 sandtable 规则，跳过');
+        }
       }
     }
   }
@@ -443,6 +583,13 @@ function initCommand(projectRoot, applyMode, lang, hooksMode) {
     console.log('  ✓ 安装 SessionStart 强提醒 hook → .claude/hooks/sandtable-reminder.sh');
   }
 
+  // 8. Append sandtable entries to .gitignore (auto, always)
+  var gitignoreDryRun = !applyMode;
+  appendToGitignore(projectRoot, gitignoreDryRun);
+  if (applyMode && fs.existsSync(path.join(projectRoot, '.gitignore'))) {
+    console.log('  ✓ 追加 sandtable 条目至 .gitignore');
+  }
+
   console.log('');
   console.log('✓ 初始化完成。运行 sandtable build 生成数据，然后 sandtable serve 查看仪表盘。');
 
@@ -525,7 +672,9 @@ function enableWatchMode(projectRoot) {
   }
 }
 
-function startServer(projectRoot, port, openBrowser, watchMode) {
+function startServer(projectRoot, port, openBrowser, watchMode, host, token) {
+  host = host || '127.0.0.1';
+  token = token || '';
   const MIME = {
     '.html': 'text/html; charset=utf-8',
     '.css': 'text/css; charset=utf-8',
@@ -562,6 +711,27 @@ function startServer(projectRoot, port, openBrowser, watchMode) {
   }
 
   http.createServer(function(req, res) {
+    // Token authentication (when binding to public interface)
+    if (token) {
+      var qIdx = req.url.indexOf('?');
+      var hasToken = false;
+      if (qIdx !== -1) {
+        var qs = req.url.substring(qIdx + 1);
+        var pairs = qs.split('&');
+        for (var pi = 0; pi < pairs.length; pi++) {
+          var kv = pairs[pi].split('=');
+          if (decodeURIComponent(kv[0]) === 'token' && kv[1] === token) {
+            hasToken = true;
+            break;
+          }
+        }
+      }
+      if (!hasToken) {
+        res.writeHead(401, { 'Content-Type': 'text/plain; charset=utf-8' });
+        return res.end('401 Unauthorized — 请在 URL 后添加 ?token=' + token);
+      }
+    }
+
     var url = req.url === '/' ? '/dashboard/dashboard.html' : req.url;
     url = url.replace(/^\/(css|js)\//, '/dashboard/$1/');
 
@@ -599,9 +769,12 @@ function startServer(projectRoot, port, openBrowser, watchMode) {
       res.writeHead(500, { 'Content-Type': 'text/plain' });
       res.end('500: ' + e.message);
     }
-  }).listen(port, function() {
-    console.log('Sandtable v' + VERSION + ' — http://localhost:' + port);
+  }).listen(port, host, function() {
+    console.log('Sandtable v' + VERSION + ' — http://' + host + ':' + port);
     console.log('Project: ' + projectRoot);
+    if (token) {
+      console.log('Token: ' + token + '  (访问需携带 ?token=' + token + ')');
+    }
 
     if (watchMode) enableWatchMode(projectRoot);
 
@@ -632,12 +805,13 @@ switch (command) {
   case 'init': {
     var applyMode = process.argv.indexOf('--apply') !== -1;
     var hooksMode = process.argv.indexOf('--hooks') !== -1;
+    var injectAgentsMd = process.argv.indexOf('--inject-agents-md') !== -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);
+    initCommand(process.cwd(), applyMode, lang, hooksMode, injectAgentsMd);
     break;
   }
   case 'summarize': {
@@ -661,109 +835,227 @@ switch (command) {
     console.log('sandtable v' + VERSION);
     break;
   case 'serve': {
-    var port = parseInt(process.argv[3], 10) || 3000;
+    var port = parseInt(process.argv[3], 10) || 5199;
     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
+
+    // Parse --host (default: 127.0.0.1, safe by default)
+    var hostIdx = process.argv.indexOf('--host');
+    var host = '127.0.0.1';
+    if (hostIdx !== -1 && process.argv[hostIdx + 1] && process.argv[hostIdx + 1].indexOf('--') !== 0) {
+      host = process.argv[hostIdx + 1];
+    }
+
+    // Parse --token (required when binding to 0.0.0.0)
+    var tokenIdx = process.argv.indexOf('--token');
+    var token = '';
+    var tokenPath = path.join(process.cwd(), '.sandtable', '.token');
+    if (tokenIdx !== -1) {
+      var nextArg = process.argv[tokenIdx + 1];
+      if (nextArg && nextArg.indexOf('--') !== 0) {
+        token = nextArg;
+        // Persist user-provided token
+        try { fs.writeFileSync(tokenPath, token, 'utf-8'); } catch(e) {}
       } else {
-        cleanArgs.push(rawArgs[ai]);
+        token = require('crypto').randomBytes(16).toString('hex');
+        try { fs.writeFileSync(tokenPath, token, 'utf-8'); } catch(e) {}
       }
     }
-
-    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 ((host === '0.0.0.0' || host === '::') && !token) {
+      // Try to load persisted token first
+      try { if (fs.existsSync(tokenPath)) token = fs.readFileSync(tokenPath, 'utf-8').trim(); } catch(e) {}
+      if (!token) {
+        token = require('crypto').randomBytes(16).toString('hex');
+        try { fs.writeFileSync(tokenPath, token, 'utf-8'); } catch(e) {}
+      }
+      console.log('⚠ 绑定 ' + host + ' 将暴露服务到网络，token: ' + token);
     }
 
-    if (!EVENT_TYPES[typeId]) {
-      console.log('错误：typeId 必须为 1-7');
-      console.log('  1=对齐与拍板 2=规格演进 3=代码变更 4=测试与质量 5=审批与交接 6=运维与基建 7=教训沉淀');
-      process.exit(1);
-    }
+    startServer(process.cwd(), port, true, watchMode, host, token);
+    break;
+  }
+      case 'event-log': {
+      // Named flags (v0.3.1+, recommended):
+      //   sandtable event-log --type <slug> --title <text> [--subtype <text>] [--impact <level>]
+      //                       [--actor <@AI|@user>] [--tags <tags>] [--ref <path>] [--thread <id>]
+      //                       [--tokens-in <n> --tokens-out <n>] [--project <path>]
+      //
+      // Legacy positional (deprecated):
+      //   sandtable event-log <typeId> <title> [subtype] [impact] [actor] [tags] [refDoc] [threadId]
+      //                       [--tokens <in>,<out>] [--continue <threadId>]
+
+      // Type slug → typeId mapping
+      var TYPE_SLUGS = {
+        'alignment': '1', 'spec': '2', 'code-change': '3',
+        'test': '4', 'approval': '5', 'ops': '6', 'lesson': '7',
+      };
+      var TYPE_SLUG_NAMES = {
+        '1': 'alignment', '2': 'spec', '3': 'code-change',
+        '4': 'test', '5': 'approval', '6': 'ops', '7': 'lesson',
+      };
+
+      var rawArgs = process.argv.slice(3);
+
+      // Detect mode: if first arg starts with --, use named mode
+      var isNamedMode = rawArgs.length > 0 && rawArgs[0].indexOf('--') === 0;
+
+      var typeId, title, subtype, impact, actor, tagsRaw, refDoc, threadId, projectRoot;
+      var tokensIn = 0, tokensOut = 0;
+
+      if (isNamedMode) {
+        // ---- Named flag mode ----
+        var flagMap = {};
+        for (var ai = 0; ai < rawArgs.length; ai++) {
+          var arg = rawArgs[ai];
+          if (arg.indexOf('--') === 0) {
+            var key = arg.replace(/^--/, '');
+            var val = (ai + 1 < rawArgs.length && rawArgs[ai + 1].indexOf('--') !== 0) ? rawArgs[ai + 1] : 'true';
+            flagMap[key] = val;
+            if (val !== 'true') ai++;
+          }
+        }
 
-    // Resolve project root
-    var projectRoot = cleanArgs[8] || process.cwd();
+        var typeSlug = flagMap['type'] || '';
+        typeId = TYPE_SLUGS[typeSlug] || '';
+        if (!typeId) {
+          console.log('错误：--type 必须是以下之一:');
+          console.log('  alignment | spec | code-change | test | approval | ops | lesson');
+          process.exit(1);
+        }
 
-    var sandtableDir = path.join(projectRoot, '.sandtable');
-    if (!fs.existsSync(sandtableDir)) fs.mkdirSync(sandtableDir, { recursive: true });
+        title = flagMap['title'] || '';
+        subtype = flagMap['subtype'] || 'manual';
+        impact = flagMap['impact'] || 'medium';
+        actor = flagMap['actor'] || 'AI';
+        tagsRaw = flagMap['tags'] || '';
+        refDoc = flagMap['ref'] || '';
+        threadId = flagMap['thread'] || '';
+        tokensIn = parseInt(flagMap['tokens-in'], 10) || 0;
+        tokensOut = parseInt(flagMap['tokens-out'], 10) || 0;
+        projectRoot = flagMap['project'] || process.cwd();
 
-    var tags = tagsRaw ? tagsRaw.split(',').map(function(t) { return t.trim(); }) : [];
-    var ref = refDoc ? { doc: refDoc } : {};
+      } else {
+        // ---- Legacy positional mode (deprecated) ----
+        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++;
+          } else if (rawArgs[ai] === '--tokens' && ai + 1 < rawArgs.length) {
+            tokensVal = rawArgs[ai + 1]; ai++;
+          } else {
+            cleanArgs.push(rawArgs[ai]);
+          }
+        }
 
-    var eventId = 'evt-' + Date.now().toString(36) + '-' + Math.random().toString(36).substring(2, 8);
+        typeId = cleanArgs[0] || '3';
+        title = cleanArgs[1] || '';
+        subtype = cleanArgs[2] || 'manual';
+        impact = cleanArgs[3] || 'medium';
+        actor = cleanArgs[4] || 'AI';
+        tagsRaw = cleanArgs[5] || '';
+        refDoc = cleanArgs[6] || '';
+        threadId = contThreadId || cleanArgs[7] || '';
+        projectRoot = cleanArgs[8] || process.cwd();
+
+        if (tokensVal) {
+          var tokensParts = tokensVal.split(',');
+          tokensIn = parseInt(tokensParts[0], 10) || 0;
+          tokensOut = parseInt(tokensParts[1], 10) || 0;
+        }
+      }
 
-    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);
+      if (!title) {
+        if (isNamedMode) {
+          console.log('用法: sandtable event-log --type <slug> --title <text> [options]');
+          console.log('');
+          console.log('必选:');
+          console.log('  --type    事件类型: alignment | spec | code-change | test | approval | ops | lesson');
+          console.log('  --title   一句话标题');
+          console.log('');
+          console.log('可选:');
+          console.log('  --subtype    子类型 (如 code-done, review-pass, alignment)');
+          console.log('  --impact     影响级别: high | medium | low (默认 medium)');
+          console.log('  --actor      执行角色: @AI | @user (默认 @AI)');
+          console.log('  --tags       逗号分隔标签');
+          console.log('  --ref        关联文档路径');
+          console.log('  --thread     线程ID (关联同一线程事件)');
+          console.log('  --tokens-in  输入 token 数');
+          console.log('  --tokens-out 输出 token 数');
+          console.log('  --project    项目根目录 (默认当前目录)');
+          console.log('');
+          console.log('示例:');
+          console.log('  sandtable event-log --type code-change --title "完成登录接口" --subtype code-done --impact medium --actor @AI --tags "登录,API" --thread login-dev');
+          console.log('  sandtable event-log --type alignment --title "确定JWT方案" --impact high --actor @user');
+        } else {
+          console.log('用法: sandtable event-log <typeId> <title> [subtype] [impact] [actor] [tags] [refDoc] [threadId]');
+          console.log('  typeId: 1=对齐与拍板 2=规格演进 3=代码变更 4=测试与质量 5=审批与交接 6=运维与基建 7=教训沉淀');
+          console.log('  (位置参数已弃用，推荐使用 --type --title 命名参数)');
+        }
+        process.exit(1);
+      }
 
-    // Write event-log.jsonl
-    var logPath = path.join(sandtableDir, 'event-log.jsonl');
-    fs.appendFileSync(logPath, JSON.stringify(event) + '\n');
+      if (!EVENT_TYPES[typeId]) {
+        console.log('错误：--type 无效。有效值: alignment | spec | code-change | test | approval | ops | lesson');
+        process.exit(1);
+      }
 
-    // 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');
+      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 + ')' : ''));
+      var slugName = TYPE_SLUG_NAMES[typeId] || '';
+      console.log('event-log: [' + event.priority + '] ' + event.type + ' — ' + title + (threadId ? ' (thread: ' + threadId + ')' : ''));
+      if (!isNamedMode) {
+        console.log('  (提示: 位置参数已弃用，下次推荐: --type ' + slugName + ' --title "...")');
+      }
 
-    // --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;
+      // --tokens-in + --tokens-out: auto-log token usage
+      if (tokensIn > 0 || tokensOut > 0) {
+        var COST_PER_1K = { input: 0.003, output: 0.006 };
+        var tCost = (tokensIn / 1000) * COST_PER_1K.input + (tokensOut / 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,
+          tokensIn: tokensIn,
+          tokensOut: tokensOut,
+          totalTokens: tokensIn + tokensOut,
           cost: tCost,
           source: 'event-log',
           eventId: eventId,
@@ -771,12 +1063,11 @@ switch (command) {
         };
         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 + ')');
+        console.log('  token-log: ' + (tokensIn + tokensOut).toLocaleString() + ' tokens (est. ¥' + tCost + ')');
       }
+      break;
     }
-    break;
-  }
-  case 'token-log': {
+case 'token-log': {
     var skill = process.argv[3] || '';
     var tokensIn = parseInt(process.argv[4], 10) || 0;
     var tokensOut = parseInt(process.argv[5], 10) || 0;
@@ -889,17 +1180,64 @@ switch (command) {
       console.log('  ' + (existing[i].isDir ? '[DIR] ' : '[   ] ') + existing[i].rel);
     }
 
+    // Check for sandtable injection markers in main docs
+    var mainDocs = ['AGENTS.md', 'CLAUDE.md'];
+    var hasInjections = false;
+    for (var i = 0; i < mainDocs.length; i++) {
+      var docPath = path.join(projectRoot, mainDocs[i]);
+      if (fs.existsSync(docPath)) {
+        var docContent = fs.readFileSync(docPath, 'utf-8');
+        if (docContent.indexOf('<!-- sandtable:begin -->') !== -1) {
+          hasInjections = true;
+          if (dryRun) {
+            console.log('');
+            removeFromMainDoc(docPath, true); // dry-run: show diff
+          }
+        }
+      }
+    }
+    if (!hasInjections) {
+      console.log('');
+      console.log('主文档中未找到 sandtable 注入标记。');
+    }
+
+    // Check for sandtable gitignore block
+    var gitignorePath = path.join(projectRoot, '.gitignore');
+    if (fs.existsSync(gitignorePath)) {
+      var giContent = fs.readFileSync(gitignorePath, 'utf-8');
+      if (giContent.indexOf('# sandtable:begin') !== -1) {
+        if (dryRun) {
+          console.log('');
+          removeFromGitignore(projectRoot, true);
+        }
+      }
+    }
+
     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 入口行，请自行删除');
+      console.log('  - sandtable 注入标记 (<!-- sandtable:begin/end -->) 可被 uninstall --apply 精确擦除');
+      console.log('  - .gitignore 中 sandtable 条目 (# sandtable:begin/end) 也会被移除');
+      console.log('  - 如果你在 AGENTS.md/CLAUDE.md 中手动添加了其他 sandtable 内容，请自行删除');
       break;
     }
 
+    // --apply: first clean up injected content from main docs
+    for (var i = 0; i < mainDocs.length; i++) {
+      var docPath = path.join(projectRoot, mainDocs[i]);
+      if (fs.existsSync(docPath)) {
+        var removed = removeFromMainDoc(docPath, false);
+        if (removed) console.log('  ✓ 从 ' + mainDocs[i] + ' 移除 sandtable 注入块');
+      }
+    }
+
+    // --apply: remove sandtable gitignore block
+    var giRemoved = removeFromGitignore(projectRoot, false);
+    if (giRemoved) console.log('  ✓ 从 .gitignore 移除 sandtable 条目');
+
     // --apply: delete files
     console.log('');
     console.log('正在删除...');
@@ -952,7 +1290,7 @@ switch (command) {
     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 serve      [port] [--watch] [--host <ip>] [--token <token>]  启动服务 + 打开浏览器');
     console.log('  sandtable summarize  [projectRoot]             列出缺少摘要块的文件');
     console.log('  sandtable event-log  <typeId> <title> [...]    记录人机协同事件');
     console.log('  sandtable token-log  <skill> <in> <out> [...]  追加 token 消耗日志');

package/src/scanner/scan.js

@@ -45,10 +45,10 @@ const PRIMARY_TYPES = new Set([
 ]);
 
 // ---- MECE display categories (PM 6 大分类 + template) ----
-// §10 libero PM 视角：路线图(在做什么)/决策(为什么)/规格(长什么样)/协作(怎么协作)/运维(跑在哪)/档案(走过什么路)
+// §10 libero PM 视角 — 9 大分类
 // Primary-only 类别 (roadmap, decision) 不出现在 filterType checkbox 中
 const DISPLAY_CATEGORIES = {
-  roadmap:    { label: '路线图与进度', elementTypes: ['phase', 'milestone', 'task', 'subtask', 'roadmap', 'backlog'] },
+  roadmap:    { label: '路线图与进度', elementTypes: ['phase', 'milestone', 'task', 'subtask', 'roadmap', 'backlog', 'optimization', 'todo'] },
   decision:   { label: '决策记录',     elementTypes: ['decision', 'refactor'] },
   spec:       { label: '业务规格',     elementTypes: ['spec', 'intent', 'prompt'] },
   convention: { label: '协作纪律',     elementTypes: ['convention'] },
@@ -58,7 +58,7 @@ const DISPLAY_CATEGORIES = {
 };
 
 // Primary-only categories (all elementTypes in these categories are kind=primary, show always)
-const PRIMARY_CATEGORIES = new Set(['roadmap', 'decision']);
+const PRIMARY_CATEGORIES = new Set(['roadmap', 'decision', 'todo']);
 
 function normalizeCategory(elementType) {
   for (const [cat, def] of Object.entries(DISPLAY_CATEGORIES)) {