adspecs 0.1.23 → 0.1.25

package/.adspecs/session-logger.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "adspecs session logger configuration",
+  "version": 1,
+  "trigger_keywords": ["保存会话", "记录会话", "save session", "log session"],
+  "auto_triggers": {
+    "pre_compact": true,
+    "session_end": true,
+    "long_session_minutes": 30
+  },
+  "summary_max_chars": 200,
+  "max_artifacts_listed": 20,
+  "log_extension": ".log",
+  "filename_pattern": "YYYYMMDD-HHmmss_{module}_ai-session.log",
+  "recovery_suffix": "-recovery"
+}

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "adspecs",
       "description": "AI Coding研发协同开发插件",
-      "version": "0.1.23",
+      "version": "0.1.25",
       "source": "./",
       "author": {
         "name": "Qingwen Chen",

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "adspecs",
   "displayName": "adspecs AI Plugin",
   "description": "AI first工程规范驱动开发插件",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "author": {
     "name": "Qingwen Chen",
     "email": "cqinwn@qq.com",

package/.qoder-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/CLAUDE.md

@@ -23,8 +23,9 @@ adspecs/
 │   ├── scripts/                 #   Helper scripts (bash, PowerShell, Python)
 │   ├── feature.json             #   Default feature tracking template (JSON, primary)
 │   ├── feature.yml              #   Feature tracking human-readable view (YAML, synced from JSON)
+│   ├── session-logger.json      #   AI session logger trigger configuration (keywords, auto-triggers)
 │   └── project.json             #   Default project metadata template
-├── skills/                      # 19 skill definitions (each with SKILL.md)
+├── skills/                      # 20 skill definitions (each with SKILL.md)
 │   ├── project-init/            #   Project scaffolding
 │   ├── adspecs-biz-analysis/    #   7-step business requirement analysis
 │   ├── adspecs-new-requirement/ #   Deep business requirement analysis + mock review
@@ -43,6 +44,7 @@ adspecs/
 │   ├── adspecs-utest/           #   JUnit 5 + Mockito unit test code + reports
 │   ├── adspecs-export-word/     #   Export Markdown to Word (.docx) with cover page + TOC
 │   ├── adspecs-update-status/   #   Feature status update + tracking matrix output
+│   ├── adspecs-save-session/    #   Save AI session log to docs/80-development/800-log/
 │   ├── sie-front-code-review/   #   React+TS+AntDesign code review
 │   └── wiki-update/             #   Sync docs/ to wiki/ (full + incremental modes)
 ├── references/                  # Reference projects & conventions copied during `/project-init`
@@ -101,12 +103,15 @@ Hooks are configured in `hooks/hooks.json` and run as Node.js scripts:
 | `SessionStart`                                    | `session-start.js`        | Injects `skills/using-saeplugin/SKILL.md` as agent context (no-op if skill doesn't exist) |
 | `SessionStart`                                    | `wiki-queue.js init`      | Initialize wiki update queue file in `.claude/`                                           |
 | `SessionStart`                                    | `commit-queue.js init`    | Initialize commit candidates queue file in `.claude/`                                     |
+| `SessionStart`                                    | `session-logger.js init`  | Detect unsaved previous session → inject recovery reminder or normal guidance              |
+| `PreCompact`                                      | `session-logger.js mark`  | Context compaction imminent → inject urgent save reminder for Claude to write log          |
 | `PostToolUse` (Write/Edit on code/doc files)      | `wiki-queue.js enqueue`   | Track changed files for wiki sync                                                         |
 | `PostToolUse` (Write on `pipeline-manifest.json`) | `commit-queue.js enqueue` | Track completed features for commit                                                       |
 | `Stop`                                            | `wiki-queue.js report`    | Suggest wiki sync at session end                                                          |
 | `Stop`                                            | `commit-queue.js report`  | Suggest commit at session end                                                             |
+| `Stop`                                            | `session-logger.js report`| Mark session as missed if log not saved → recovery at next SessionStart                    |
 
-Hook scripts use `__dirname` for path resolution (not CWD). Queue files stored in `.claude/` (`.commit-candidates`, `.wiki-update-queue`).
+Hook scripts use `__dirname` for path resolution (not CWD). Queue files stored in `.claude/` (`.commit-candidates`, `.wiki-update-queue`, `.session-save-marker`).
 
 ## Path Configuration
 
@@ -126,6 +131,7 @@ Skills support configurable output directories via `.adspecs/paths.json` in the
     "prd_dir": "docs/20-prd",
     "design_dir": "docs/30-system-design",
     "test_report_dir": "docs/80-development",
+    "session_log_dir": "docs/80-development/800-log",
     "export_dir": "docs/90-export",
     "wiki_dir": "wiki"
   }
@@ -143,7 +149,8 @@ Skills support configurable output directories via `.adspecs/paths.json` in the
 | `prd_dir`             | `docs/20-prd`                   | adspecs-prd, adspecs-plan (input), adspecs-front-spec (input), wiki-update (source)                                                 |
 | `design_dir`          | `docs/30-system-design`         | adspecs-plan (output), adspecs-tasks, adspecs-front-spec (output), adspecs-front-tasks, adspecs-utest (input), wiki-update (source) |
 | `test_report_dir`     | `docs/80-development`           | adspecs-utest (test reports)                                                                                                        |
-| `export_dir`          | `docs/90-export`                | adspecs-export-word (Word 导出输出)                                                                                                  |
+| `session_log_dir`     | `docs/80-development/800-log`   | session-logger (AI session logs, triggered by keyword / PreCompact / session end)                                                    |
+| `export_dir`          | `docs/90-export`                | adspecs-export-word (Word 导出输出)                                                                                                 |
 | `wiki_dir`            | `wiki`                          | wiki-update (output target)                                                                                                         |
 
 `/project-init` generates this file automatically with default values. Users can edit it to customize output paths for their project structure.
@@ -178,7 +185,7 @@ Projects initialized by this plugin follow this layout:
 | ------------------------------ | -------------------------------------------------- |
 | `docs/20-prd/`                 | Requirements specs (PRD)                           |
 | `docs/30-system-design/`       | System design + SQL + frontend design + task lists |
-| `docs/40-project_conventions/` | ECP coding standards                               |
+| `docs/40-project_conventions/` | coding standards                                   |
 | `.adspecs/templates/`          | Standard document templates                        |
 | `web-ui/`                      | Frontend production project                        |
 | `service/`                     | Backend Java service modules                       |
@@ -192,6 +199,13 @@ This plugin requires the **superpowers** plugin for coding-phase skills:
 - `verification-before-completion` — Pre-completion verification
 - `finishing-a-development-branch` — Branch cleanup / PR creation
 
+## publish
+
+```bash
+npm version patch --no-git-tag-version
+npm publish --registry=https://registry.npmjs.org
+```
+
 ## Installation & Distribution
 
 ```bash

package/hooks/hooks.json

@@ -14,6 +14,20 @@
           {
             "type": "command",
             "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/commit-queue.js init"
+          },
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-logger.js init"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-logger.js mark"
           }
         ]
       }
@@ -55,6 +69,10 @@
           {
             "type": "command",
             "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/commit-queue.js report"
+          },
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-logger.js report"
           }
         ]
       }

package/hooks/session-logger.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+
+/**
+ * Session Logger — AI 会话日志自动保存 Hook
+ *
+ * 在 SessionStart / PreCompact / Stop 三个事件中管理会话保存状态，
+ * 通过 additionalContext 引导 Claude 自行生成并写入结构化日志文件。
+ *
+ * 用法:
+ *   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');
+
+// ── 路径解析 ──────────────────────────────────────────────
+// 使用 process.cwd() 定位目标项目（不用 __dirname，因为 __dirname 指向插件目录）
+const PROJECT_ROOT = process.cwd();
+const CLAUDE_DIR = path.join(PROJECT_ROOT, '.claude');
+const MARKER_FILE = path.join(CLAUDE_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(CLAUDE_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（供 Claude 读取） */
+function outputContext(eventName, contextText) {
+  var output = {
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      additionalContext: contextText,
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+}
+
+/** 计算两个 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);
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "adspecs",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "AI first 工程规范驱动开发插件 — 支持 npm 安装和 CLI 初始化",
   "bin": {
-    "adspecs": "./bin/adspecs.js"
+    "adspecs": "bin/adspecs.js"
   },
   "main": "./src/utils.js",
   "files": [