adspecs 0.1.41 → 0.2.0

package/hooks/session-logger.js

@@ -1,346 +1,346 @@
-#!/usr/bin/env node
-
-/**
- * Session Logger — AI 会话日志自动保存 Hook
- *
- * 在 SessionStart / PreCompact / Stop 三个事件中管理会话保存状态，
- * 通过 additionalContext 引导 AI Agent 自行生成并写入结构化日志文件。
- * 支持 Claude Code 和 Qoder 双平台。
- *
- * 用法:
- *   node hooks/session-logger.js init   — SessionStart: 检测恢复 / 注入引导
- *   node hooks/session-logger.js mark   — PreCompact:   紧急保存提醒
- *   node hooks/session-logger.js report — Stop:         标记未保存 / 清理
- */
-
-const fs = require('fs');
-const path = require('path');
-const platform = require('./platform');
-
-// ── 路径解析 ──────────────────────────────────────────────
-// 项目根由 platform.getProjectRoot() 解析：优先 CLAUDE_PROJECT_DIR，兜底 cwd
-// （不用 __dirname——它指向插件目录而非目标项目）
-const PROJECT_ROOT = platform.getProjectRoot();
-const STATE_DIR = platform.getStateDir(PROJECT_ROOT);
-const MARKER_FILE = path.join(STATE_DIR, '.session-save-marker');
-const CONFIG_FILE = path.join(PROJECT_ROOT, '.adspecs', 'session-logger.json');
-const PATHS_FILE = path.join(PROJECT_ROOT, '.adspecs', 'paths.json');
-const FEATURE_FILE = path.join(PROJECT_ROOT, '.adspecs', 'feature.json');
-
-// ── 默认配置 ──────────────────────────────────────────────
-const DEFAULT_CONFIG = {
-  trigger_keywords: ['保存会话', '记录会话', 'save session', 'log session'],
-  summary_max_chars: 200,
-  max_artifacts_listed: 20,
-  log_extension: '.log',
-  recovery_suffix: '-recovery',
-};
-
-const DEFAULT_LOG_DIR = 'docs/80-development/800-log';
-
-// ── 工具函数 ──────────────────────────────────────────────
-
-/** 安全读取 JSON 文件，解析失败或不存在返回 fallback */
-function loadJson(filePath, fallback) {
-  if (!fs.existsSync(filePath)) {
-    return fallback;
-  }
-  try {
-    var raw = fs.readFileSync(filePath, 'utf8');
-    return JSON.parse(raw);
-  } catch (_err) {
-    return fallback;
-  }
-}
-
-/** 从 feature.json 的 active 字段提取模块 ID */
-function resolveModuleId() {
-  var feature = loadJson(FEATURE_FILE, {});
-  var active = feature.active || '';
-
-  if (!active) {
-    return { id: 'GEN', name: 'generic' };
-  }
-
-  // 取路径末段（如 docs/20-prd/003-user-auth -> 003-user-auth）
-  var segments = active.split(/[\\/]/).filter(Boolean);
-  var lastSegment = segments.length > 0 ? segments[segments.length - 1] : '';
-
-  if (!lastSegment) {
-    return { id: 'GEN', name: 'generic' };
-  }
-
-  // 提取编号前缀（如 003-user-auth -> 003-user-auth）
-  var match = lastSegment.match(/^([a-z0-9]+(?:-[a-z0-9]+)*)/i);
-  if (match && match[1]) {
-    return { id: match[1], name: lastSegment };
-  }
-
-  return { id: lastSegment, name: lastSegment };
-}
-
-/** 读取日志输出目录 */
-function resolveLogDir() {
-  var pathsConfig = loadJson(PATHS_FILE, {});
-  var paths = pathsConfig.paths || {};
-  return paths.session_log_dir || DEFAULT_LOG_DIR;
-}
-
-/** 读取用户配置 */
-function loadConfig() {
-  var userConfig = loadJson(CONFIG_FILE, {});
-  // 合并默认配置（用户配置覆盖默认）
-  var merged = {};
-  Object.keys(DEFAULT_CONFIG).forEach(function (key) {
-    merged[key] = userConfig[key] !== undefined ? userConfig[key] : DEFAULT_CONFIG[key];
-  });
-  return merged;
-}
-
-/** 读取 marker 文件 */
-function readMarker() {
-  if (!fs.existsSync(MARKER_FILE)) {
-    return null;
-  }
-  try {
-    var raw = fs.readFileSync(MARKER_FILE, 'utf8').trim();
-    if (!raw) return null;
-    // JSONL 格式，取最后一行（最新态）
-    var lines = raw.split(/\r?\n/).filter(Boolean);
-    return JSON.parse(lines[lines.length - 1]);
-  } catch (_err) {
-    return null;
-  }
-}
-
-/** 写入 marker 文件（覆盖写，单行最新态） */
-function writeMarker(data) {
-  fs.mkdirSync(STATE_DIR, { recursive: true });
-  fs.writeFileSync(MARKER_FILE, JSON.stringify(data) + '\n', 'utf8');
-}
-
-/** 清空 marker 文件 */
-function clearMarker() {
-  if (fs.existsSync(MARKER_FILE)) {
-    fs.unlinkSync(MARKER_FILE);
-  }
-}
-
-/** 生成时间戳字符串 YYYYMMDD-HHmmss */
-function formatTimestamp(date) {
-  var d = date || new Date();
-  var yyyy = d.getFullYear();
-  var MM = String(d.getMonth() + 1).padStart(2, '0');
-  var dd = String(d.getDate()).padStart(2, '0');
-  var HH = String(d.getHours()).padStart(2, '0');
-  var mm = String(d.getMinutes()).padStart(2, '0');
-  var ss = String(d.getSeconds()).padStart(2, '0');
-  return yyyy + MM + dd + '-' + HH + mm + ss;
-}
-
-/** 输出 additionalContext 到 stdout（供 AI 平台读取，使用平台统一协议） */
-function outputContext(eventName, contextText) {
-  platform.outputContext(eventName, contextText);
-}
-
-/** 计算两个 ISO 时间戳之间的分钟数 */
-function elapsedMinutes(startISO) {
-  if (!startISO) return 0;
-  var start = new Date(startISO);
-  var now = new Date();
-  var diffMs = now - start;
-  return Math.round(diffMs / 60000);
-}
-
-// ── 子命令：init（SessionStart） ─────────────────────────
-
-function cmdInit() {
-  var marker = readMarker();
-  var mod = resolveModuleId();
-  var logDir = resolveLogDir();
-  var config = loadConfig();
-
-  // 检测是否需要恢复
-  if (marker && marker.type === 'session_missed') {
-    var elapsed = elapsedMinutes(marker.startedAt);
-    var recoveryText = [
-      '<session-logger>',
-      '## ⚠️ 上次会话日志未保存',
-      '',
-      '上次会话：' + (marker.startedAt || '未知') + ' 启动，模块 ' + (marker.module || 'GEN') + '，已运行约 ' + elapsed + ' 分钟',
-      '日志未保存原因：会话异常结束或用户执行了 /clear',
-      '',
-      '### 恢复选项',
-      '- 确认恢复：我会生成 ' + logDir + '/' + formatTimestamp() + '_' + (marker.module || 'GEN') + '_ai-session' + config.recovery_suffix + config.log_extension,
-      '- 跳过恢复：回复"跳过恢复"或"skip recovery"',
-      '',
-      '恢复日志基于用户描述的上次会话要点生成，质量依赖用户输入。',
-      '</session-logger>',
-    ].join('\n');
-
-    // 写新 marker（覆盖旧的 session_missed）
-    writeMarker({
-      type: 'session_started',
-      module: mod.id,
-      moduleName: mod.name,
-      timestamp: new Date().toISOString(),
-      startedAt: new Date().toISOString(),
-      saved: false,
-      saveCount: 0,
-      compactRequestedAt: null,
-      missedAt: marker.missedAt || null,
-      recoveryFrom: marker,
-    });
-
-    outputContext('SessionStart', recoveryText);
-    console.log('[session-logger] Recovery reminder injected for module ' + (marker.module || 'GEN'));
-    return;
-  }
-
-  // 常规启动：注入引导
-  var keywords = config.trigger_keywords.join(' / ');
-  var guideText = [
-    '<session-logger>',
-    '## AI 会话日志保存指南',
-    '',
-    '当前模块：' + mod.id + ' (' + mod.name + ')',
-    '日志目录：' + logDir + '/',
-    '',
-    '### 何时保存（按优先级）',
-    '1. **关键词触发**（最高优先级）：用户输入包含以下任一词时 → 立即保存：',
-    '   ' + keywords,
-    '2. **会话即将结束**：任务完成、用户表示结束 → 主动保存',
-    '3. **长会话节点**：每完成一个重要阶段（如系统设计完成、任务清单生成）→ 主动保存',
-    '4. **/clear 前**：用户表示要 /clear 时 → 建议先保存',
-    '',
-    '### 如何保存',
-    '使用 Write 工具写入：' + logDir + '/{YYYYMMDD-HHmmss}_' + mod.id + '_ai-session' + config.log_extension,
-    '内容遵循 adspecs-save-session SKILL.md 中的模板。',
-    '',
-    '### 注意',
-    '- Summary 必须实质性，禁止"本次会话讨论了需求"等空洞描述',
-    '- Key Artifacts 必须是真实存在的文件路径',
-    '- 同一会话多次保存产生多个文件（时间戳区分），第 N 次的 Summary 聚焦上次保存后的进展',
-    '- /clear 是 CLI 内建命令，不会触发 Stop hook，请在用户提到 /clear 时主动提醒保存',
-    '</session-logger>',
-  ].join('\n');
-
-  // 写新 marker
-  writeMarker({
-    type: 'session_started',
-    module: mod.id,
-    moduleName: mod.name,
-    timestamp: new Date().toISOString(),
-    startedAt: new Date().toISOString(),
-    saved: false,
-    saveCount: 0,
-    compactRequestedAt: null,
-    missedAt: null,
-  });
-
-  outputContext('SessionStart', guideText);
-  console.log('[session-logger] Session started for module ' + mod.id);
-}
-
-// ── 子命令：mark（PreCompact） ───────────────────────────
-
-function cmdMark() {
-  var marker = readMarker();
-  var mod = resolveModuleId();
-  var logDir = resolveLogDir();
-  var config = loadConfig();
-  var now = new Date();
-  var timestamp = formatTimestamp(now);
-
-  // 更新 marker
-  var newMarker = {
-    type: 'compact_pending',
-    module: mod.id,
-    moduleName: mod.name,
-    timestamp: now.toISOString(),
-    startedAt: (marker && marker.startedAt) || now.toISOString(),
-    saved: false,
-    saveCount: (marker && marker.saveCount) || 0,
-    compactRequestedAt: now.toISOString(),
-    missedAt: null,
-  };
-  writeMarker(newMarker);
-
-  // 注入紧急提醒
-  var filename = timestamp + '_' + mod.id + '_ai-session' + config.log_extension;
-  var filePath = logDir + '/' + filename;
-
-  var urgentText = [
-    '<session-logger>',
-    '## 🚨 上下文即将压缩 — 立即保存会话日志',
-    '',
-    '这是**最高优先级操作**，请在继续其他任务之前完成：',
-    '',
-    '1. 使用 Write 工具写入：' + filePath,
-    '2. 内容遵循 adspecs-save-session SKILL.md 中的模板',
-    '3. Summary 聚焦' + (newMarker.saveCount > 0 ? '上次保存后的进展（第 ' + (newMarker.saveCount + 1) + ' 次保存）' : '本次会话的关键内容'),
-    '',
-    '完成后，marker 会自动更新。',
-    '</session-logger>',
-  ].join('\n');
-
-  outputContext('PreCompact', urgentText);
-  console.log('[session-logger] PreCompact: urgent save requested for ' + filename);
-}
-
-// ── 子命令：report（Stop） ───────────────────────────────
-
-function cmdReport() {
-  var marker = readMarker();
-
-  if (!marker) {
-    // 无 marker，静默退出
-    return;
-  }
-
-  // 已保存 → 清空 marker
-  if (marker.saved === true) {
-    clearMarker();
-    console.log('[session-logger] Session log saved, marker cleared.');
-    return;
-  }
-
-  // 未保存 → 标记 session_missed
-  if (marker.type === 'session_started' || marker.type === 'compact_pending') {
-    marker.type = 'session_missed';
-    marker.missedAt = new Date().toISOString();
-    marker.timestamp = new Date().toISOString();
-    writeMarker(marker);
-
-    console.log('');
-    console.log('═══ [session-logger] ══════════════════════════════════');
-    console.log('[session-logger] WARNING: session log NOT saved');
-    console.log('[session-logger] Module: ' + (marker.module || 'GEN'));
-    console.log('[session-logger] Next SessionStart will offer recovery');
-    console.log('══════════════════════════════════════════════════════');
-    console.log('');
-  }
-}
-
-// ── 主入口 ────────────────────────────────────────────────
-
-var action = process.argv[2];
-
-switch (action) {
-  case 'init':
-    cmdInit();
-    break;
-
-  case 'mark':
-    cmdMark();
-    break;
-
-  case 'report':
-    cmdReport();
-    break;
-
-  default:
-    console.error('[session-logger] Unknown action: ' + (action || '(none)'));
-    console.error('[session-logger] Usage: node hooks/session-logger.js init|mark|report');
-    process.exit(1);
-}
+#!/usr/bin/env node
+
+/**
+ * Session Logger — AI 会话日志自动保存 Hook
+ *
+ * 在 SessionStart / PreCompact / Stop 三个事件中管理会话保存状态，
+ * 通过 additionalContext 引导 AI Agent 自行生成并写入结构化日志文件。
+ * 支持 Claude Code 和 Qoder 双平台。
+ *
+ * 用法:
+ *   node hooks/session-logger.js init   — SessionStart: 检测恢复 / 注入引导
+ *   node hooks/session-logger.js mark   — PreCompact:   紧急保存提醒
+ *   node hooks/session-logger.js report — Stop:         标记未保存 / 清理
+ */
+
+const fs = require('fs');
+const path = require('path');
+const platform = require('./platform');
+
+// ── 路径解析 ──────────────────────────────────────────────
+// 项目根由 platform.getProjectRoot() 解析：优先 CLAUDE_PROJECT_DIR，兜底 cwd
+// （不用 __dirname——它指向插件目录而非目标项目）
+const PROJECT_ROOT = platform.getProjectRoot();
+const STATE_DIR = platform.getStateDir(PROJECT_ROOT);
+const MARKER_FILE = path.join(STATE_DIR, '.session-save-marker');
+const CONFIG_FILE = path.join(PROJECT_ROOT, '.adspecs', 'session-logger.json');
+const PATHS_FILE = path.join(PROJECT_ROOT, '.adspecs', 'paths.json');
+const FEATURE_FILE = path.join(PROJECT_ROOT, '.adspecs', 'feature.json');
+
+// ── 默认配置 ──────────────────────────────────────────────
+const DEFAULT_CONFIG = {
+  trigger_keywords: ['保存会话', '记录会话', 'save session', 'log session'],
+  summary_max_chars: 200,
+  max_artifacts_listed: 20,
+  log_extension: '.log',
+  recovery_suffix: '-recovery',
+};
+
+const DEFAULT_LOG_DIR = 'docs/80-development/800-log';
+
+// ── 工具函数 ──────────────────────────────────────────────
+
+/** 安全读取 JSON 文件，解析失败或不存在返回 fallback */
+function loadJson(filePath, fallback) {
+  if (!fs.existsSync(filePath)) {
+    return fallback;
+  }
+  try {
+    var raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+  } catch (_err) {
+    return fallback;
+  }
+}
+
+/** 从 feature.json 的 active 字段提取模块 ID */
+function resolveModuleId() {
+  var feature = loadJson(FEATURE_FILE, {});
+  var active = feature.active || '';
+
+  if (!active) {
+    return { id: 'GEN', name: 'generic' };
+  }
+
+  // 取路径末段（如 docs/20-prd/003-user-auth -> 003-user-auth）
+  var segments = active.split(/[\\/]/).filter(Boolean);
+  var lastSegment = segments.length > 0 ? segments[segments.length - 1] : '';
+
+  if (!lastSegment) {
+    return { id: 'GEN', name: 'generic' };
+  }
+
+  // 提取编号前缀（如 003-user-auth -> 003-user-auth）
+  var match = lastSegment.match(/^([a-z0-9]+(?:-[a-z0-9]+)*)/i);
+  if (match && match[1]) {
+    return { id: match[1], name: lastSegment };
+  }
+
+  return { id: lastSegment, name: lastSegment };
+}
+
+/** 读取日志输出目录 */
+function resolveLogDir() {
+  var pathsConfig = loadJson(PATHS_FILE, {});
+  var paths = pathsConfig.paths || {};
+  return paths.session_log_dir || DEFAULT_LOG_DIR;
+}
+
+/** 读取用户配置 */
+function loadConfig() {
+  var userConfig = loadJson(CONFIG_FILE, {});
+  // 合并默认配置（用户配置覆盖默认）
+  var merged = {};
+  Object.keys(DEFAULT_CONFIG).forEach(function (key) {
+    merged[key] = userConfig[key] !== undefined ? userConfig[key] : DEFAULT_CONFIG[key];
+  });
+  return merged;
+}
+
+/** 读取 marker 文件 */
+function readMarker() {
+  if (!fs.existsSync(MARKER_FILE)) {
+    return null;
+  }
+  try {
+    var raw = fs.readFileSync(MARKER_FILE, 'utf8').trim();
+    if (!raw) return null;
+    // JSONL 格式，取最后一行（最新态）
+    var lines = raw.split(/\r?\n/).filter(Boolean);
+    return JSON.parse(lines[lines.length - 1]);
+  } catch (_err) {
+    return null;
+  }
+}
+
+/** 写入 marker 文件（覆盖写，单行最新态） */
+function writeMarker(data) {
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+  fs.writeFileSync(MARKER_FILE, JSON.stringify(data) + '\n', 'utf8');
+}
+
+/** 清空 marker 文件 */
+function clearMarker() {
+  if (fs.existsSync(MARKER_FILE)) {
+    fs.unlinkSync(MARKER_FILE);
+  }
+}
+
+/** 生成时间戳字符串 YYYYMMDD-HHmmss */
+function formatTimestamp(date) {
+  var d = date || new Date();
+  var yyyy = d.getFullYear();
+  var MM = String(d.getMonth() + 1).padStart(2, '0');
+  var dd = String(d.getDate()).padStart(2, '0');
+  var HH = String(d.getHours()).padStart(2, '0');
+  var mm = String(d.getMinutes()).padStart(2, '0');
+  var ss = String(d.getSeconds()).padStart(2, '0');
+  return yyyy + MM + dd + '-' + HH + mm + ss;
+}
+
+/** 输出 additionalContext 到 stdout（供 AI 平台读取，使用平台统一协议） */
+function outputContext(eventName, contextText) {
+  platform.outputContext(eventName, contextText);
+}
+
+/** 计算两个 ISO 时间戳之间的分钟数 */
+function elapsedMinutes(startISO) {
+  if (!startISO) return 0;
+  var start = new Date(startISO);
+  var now = new Date();
+  var diffMs = now - start;
+  return Math.round(diffMs / 60000);
+}
+
+// ── 子命令：init（SessionStart） ─────────────────────────
+
+function cmdInit() {
+  var marker = readMarker();
+  var mod = resolveModuleId();
+  var logDir = resolveLogDir();
+  var config = loadConfig();
+
+  // 检测是否需要恢复
+  if (marker && marker.type === 'session_missed') {
+    var elapsed = elapsedMinutes(marker.startedAt);
+    var recoveryText = [
+      '<session-logger>',
+      '## ⚠️ 上次会话日志未保存',
+      '',
+      '上次会话：' + (marker.startedAt || '未知') + ' 启动，模块 ' + (marker.module || 'GEN') + '，已运行约 ' + elapsed + ' 分钟',
+      '日志未保存原因：会话异常结束或用户执行了 /clear',
+      '',
+      '### 恢复选项',
+      '- 确认恢复：我会生成 ' + logDir + '/' + formatTimestamp() + '_' + (marker.module || 'GEN') + '_ai-session' + config.recovery_suffix + config.log_extension,
+      '- 跳过恢复：回复"跳过恢复"或"skip recovery"',
+      '',
+      '恢复日志基于用户描述的上次会话要点生成，质量依赖用户输入。',
+      '</session-logger>',
+    ].join('\n');
+
+    // 写新 marker（覆盖旧的 session_missed）
+    writeMarker({
+      type: 'session_started',
+      module: mod.id,
+      moduleName: mod.name,
+      timestamp: new Date().toISOString(),
+      startedAt: new Date().toISOString(),
+      saved: false,
+      saveCount: 0,
+      compactRequestedAt: null,
+      missedAt: marker.missedAt || null,
+      recoveryFrom: marker,
+    });
+
+    outputContext('SessionStart', recoveryText);
+    console.log('[session-logger] Recovery reminder injected for module ' + (marker.module || 'GEN'));
+    return;
+  }
+
+  // 常规启动：注入引导
+  var keywords = config.trigger_keywords.join(' / ');
+  var guideText = [
+    '<session-logger>',
+    '## AI 会话日志保存指南',
+    '',
+    '当前模块：' + mod.id + ' (' + mod.name + ')',
+    '日志目录：' + logDir + '/',
+    '',
+    '### 何时保存（按优先级）',
+    '1. **关键词触发**（最高优先级）：用户输入包含以下任一词时 → 立即保存：',
+    '   ' + keywords,
+    '2. **会话即将结束**：任务完成、用户表示结束 → 主动保存',
+    '3. **长会话节点**：每完成一个重要阶段（如系统设计完成、任务清单生成）→ 主动保存',
+    '4. **/clear 前**：用户表示要 /clear 时 → 建议先保存',
+    '',
+    '### 如何保存',
+    '使用 Write 工具写入：' + logDir + '/{YYYYMMDD-HHmmss}_' + mod.id + '_ai-session' + config.log_extension,
+    '内容遵循 ads-save-session SKILL.md 中的模板。',
+    '',
+    '### 注意',
+    '- Summary 必须实质性，禁止"本次会话讨论了需求"等空洞描述',
+    '- Key Artifacts 必须是真实存在的文件路径',
+    '- 同一会话多次保存产生多个文件（时间戳区分），第 N 次的 Summary 聚焦上次保存后的进展',
+    '- /clear 是 CLI 内建命令，不会触发 Stop hook，请在用户提到 /clear 时主动提醒保存',
+    '</session-logger>',
+  ].join('\n');
+
+  // 写新 marker
+  writeMarker({
+    type: 'session_started',
+    module: mod.id,
+    moduleName: mod.name,
+    timestamp: new Date().toISOString(),
+    startedAt: new Date().toISOString(),
+    saved: false,
+    saveCount: 0,
+    compactRequestedAt: null,
+    missedAt: null,
+  });
+
+  outputContext('SessionStart', guideText);
+  console.log('[session-logger] Session started for module ' + mod.id);
+}
+
+// ── 子命令：mark（PreCompact） ───────────────────────────
+
+function cmdMark() {
+  var marker = readMarker();
+  var mod = resolveModuleId();
+  var logDir = resolveLogDir();
+  var config = loadConfig();
+  var now = new Date();
+  var timestamp = formatTimestamp(now);
+
+  // 更新 marker
+  var newMarker = {
+    type: 'compact_pending',
+    module: mod.id,
+    moduleName: mod.name,
+    timestamp: now.toISOString(),
+    startedAt: (marker && marker.startedAt) || now.toISOString(),
+    saved: false,
+    saveCount: (marker && marker.saveCount) || 0,
+    compactRequestedAt: now.toISOString(),
+    missedAt: null,
+  };
+  writeMarker(newMarker);
+
+  // 注入紧急提醒
+  var filename = timestamp + '_' + mod.id + '_ai-session' + config.log_extension;
+  var filePath = logDir + '/' + filename;
+
+  var urgentText = [
+    '<session-logger>',
+    '## 🚨 上下文即将压缩 — 立即保存会话日志',
+    '',
+    '这是**最高优先级操作**，请在继续其他任务之前完成：',
+    '',
+    '1. 使用 Write 工具写入：' + filePath,
+    '2. 内容遵循 ads-save-session SKILL.md 中的模板',
+    '3. Summary 聚焦' + (newMarker.saveCount > 0 ? '上次保存后的进展（第 ' + (newMarker.saveCount + 1) + ' 次保存）' : '本次会话的关键内容'),
+    '',
+    '完成后，marker 会自动更新。',
+    '</session-logger>',
+  ].join('\n');
+
+  outputContext('PreCompact', urgentText);
+  console.log('[session-logger] PreCompact: urgent save requested for ' + filename);
+}
+
+// ── 子命令：report（Stop） ───────────────────────────────
+
+function cmdReport() {
+  var marker = readMarker();
+
+  if (!marker) {
+    // 无 marker，静默退出
+    return;
+  }
+
+  // 已保存 → 清空 marker
+  if (marker.saved === true) {
+    clearMarker();
+    console.log('[session-logger] Session log saved, marker cleared.');
+    return;
+  }
+
+  // 未保存 → 标记 session_missed
+  if (marker.type === 'session_started' || marker.type === 'compact_pending') {
+    marker.type = 'session_missed';
+    marker.missedAt = new Date().toISOString();
+    marker.timestamp = new Date().toISOString();
+    writeMarker(marker);
+
+    console.log('');
+    console.log('═══ [session-logger] ══════════════════════════════════');
+    console.log('[session-logger] WARNING: session log NOT saved');
+    console.log('[session-logger] Module: ' + (marker.module || 'GEN'));
+    console.log('[session-logger] Next SessionStart will offer recovery');
+    console.log('══════════════════════════════════════════════════════');
+    console.log('');
+  }
+}
+
+// ── 主入口 ────────────────────────────────────────────────
+
+var action = process.argv[2];
+
+switch (action) {
+  case 'init':
+    cmdInit();
+    break;
+
+  case 'mark':
+    cmdMark();
+    break;
+
+  case 'report':
+    cmdReport();
+    break;
+
+  default:
+    console.error('[session-logger] Unknown action: ' + (action || '(none)'));
+    console.error('[session-logger] Usage: node hooks/session-logger.js init|mark|report');
+    process.exit(1);
+}