adspecs 0.1.23 → 0.1.24

package/skills/adspecs-save-session/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: adspecs-save-session
+description: "保存当前 AI 会话为结构化 Markdown 日志。生成含摘要、产物清单、决策记录的 .log 文件到 docs/80-development/800-log/。Use when user asks to save session, log session, or before /clear."
+argument-hint: "[--summary-only]"
+user-invocable: true
+compatibility: 需要 .adspecs/ 目录结构
+---
+
+# AI 会话日志保存
+
+将当前 Claude Code 会话内容生成结构化摘要，写入 `docs/80-development/800-log/` 目录下的 `.log` Markdown 文件。
+
+## 适用场景
+
+- 用户显式输入「保存会话」「记录会话」「save session」「log session」
+- 会话即将结束（任务完成、用户表示结束）
+- 长会话节点（完成系统设计、任务清单等重要阶段）
+- 用户执行 `/clear` 前
+- PreCompact 触发（上下文即将压缩）
+- 上次会话未保存的恢复场景
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+### 参数说明
+
+| 参数 | 必填 | 说明 | 示例 |
+|------|------|------|------|
+| `--summary-only` | 否 | 仅生成 Summary，跳过 Key Artifacts 和 Decisions | `--summary-only` |
+
+## 执行步骤
+
+### 1. 读取配置
+
+读取以下文件（缺失时使用默认值）：
+
+- `.adspecs/paths.json` → `paths.session_log_dir`（默认 `docs/80-development/800-log`）
+- `.adspecs/feature.json` → `active` 字段（提取模块 ID）
+- `.adspecs/session-logger.json` → 用户自定义配置
+
+**模块 ID 提取规则**：
+- `active` 为空 → 使用 `GEN`
+- `active = docs/20-prd/003-user-auth` → 取末段 `003-user-auth`
+- 正则 `/^([a-z0-9]+(?:-[a-z0-9]+)*)/i` 提取编号前缀
+
+### 2. 计算文件名
+
+格式：`{YYYYMMDD-HHmmss}_{module-id}_ai-session.log`
+
+示例：
+- `20260730-143522_003-user-auth_ai-session.log`
+- `20260730-150000_GEN_ai-session.log`（无 active 模块时）
+- `20260730-160000_003-user-auth_ai-session-recovery.log`（恢复场景）
+
+### 3. 生成 Markdown 日志
+
+使用以下模板：
+
+```markdown
+# AI Session Log
+
+- Date: YYYY-MM-DD HH:mm:ss
+- Module: {id} ({name})
+- Trigger: manual | pre_compact | session_end | recovery
+- Duration: ~Nmin
+- Turns: N
+- Skills invoked: skill1, skill2, ...
+
+## Summary
+
+（200 字以内，实质性摘要，禁止空洞描述）
+
+**必须包含**：
+- 本次会话解决的核心问题
+- 关键决策及其理由
+- 重要产出物概述
+
+**禁止**：
+- "本次会话讨论了需求"等空洞描述
+- 重复用户问题
+- 无实质内容的总结
+
+## Key Artifacts
+
+- docs/20-prd/003-user-auth/003-user-auth_产品需求说明书.md (created)
+- docs/30-system-design/003-user-auth_system-design.md (created)
+- docs/30-system-design/003-user-auth_schema.sql (created)
+
+**规则**：
+- 列出本次会话创建或修改的真实文件路径
+- 每个文件标注 `(created)` 或 `(modified)`
+- 最多列出 20 个文件（按重要性排序）
+- 若使用 `--summary-only`，跳过此节
+
+## Decisions & Open Issues
+
+- [决策] 采用 JWT 而非 Session 认证，原因：无状态、易扩展
+- [决策] 数据库使用 PostgreSQL，理由：团队熟悉、JSON 支持好
+- [待定] 第三方 OAuth 接入范围待用户确认
+- [待定] 性能指标（QPS 目标）需与运维对齐
+
+**规则**：
+- `[决策]`：已确定的技术方案、架构选择、工具选型等
+- `[待定]`：未解决的问题、待确认的需求、待对齐的指标
+- 若使用 `--summary-only`，跳过此节
+```
+
+### 4. 写入文件
+
+使用 Write 工具将生成的 Markdown 内容写入计算出的文件路径。
+
+### 5. 更新 marker
+
+读取 `.claude/.session-save-marker`，更新以下字段：
+- `saved: true`
+- `saveCount: saveCount + 1`
+- `timestamp: 当前 ISO 时间戳`
+
+若 marker 不存在，创建新 marker：
+
+```json
+{
+  "type": "session_started",
+  "module": "{module-id}",
+  "moduleName": "{module-name}",
+  "timestamp": "ISO",
+  "startedAt": "ISO",
+  "saved": true,
+  "saveCount": 1,
+  "compactRequestedAt": null,
+  "missedAt": null
+}
+```
+
+### 6. 输出确认
+
+```
+[session-logger] Saved: {filename}
+[session-logger] Location: {logDir}/{filename}
+[session-logger] Save count: {saveCount}
+```
+
+## 多次保存规则
+
+同一会话可多次保存（时间戳区分文件）：
+
+- **第 1 次保存**：Summary 覆盖整个会话
+- **第 N 次保存**（N > 1）：Summary 聚焦「上次保存后的进展」
+- 每次保存的 Key Artifacts 列出**本次新增/修改**的文件
+
+通过 marker 的 `saveCount` 字段判断当前是第几次保存。
+
+## 恢复场景
+
+当 marker 文件存在且 `type == session_missed` 时：
+
+1. SessionStart 注入恢复提醒
+2. 用户确认恢复后，调用本 skill
+3. 文件名后缀加 `-recovery`（如 `20260730-160000_003-user-auth_ai-session-recovery.log`）
+4. Summary 基于用户描述的上次会话要点生成
+
+## 注意事项
+
+- Summary 必须实质性，禁止空洞描述
+- Key Artifacts 必须是真实存在的文件路径（可用 Glob 验证）
+- 日志文件使用 `.log` 扩展名（纯文本 Markdown）
+- 日志文件应纳入 git 跟踪（作为开发审计轨迹）
+- 若 `.adspecs/` 目录不存在，提示用户先执行 `/project-init`
+
+## 相关文件
+
+- `hooks/session-logger.js` — Hook 脚本（触发信号）
+- `.claude/.session-save-marker` — 状态 marker 文件
+- `.adspecs/session-logger.json` — 用户配置
+- `.adspecs/paths.json` — 路径配置

package/skills/project-init/SKILL.md

@@ -933,6 +933,7 @@ find "$TARGET/front-demo" -type f | wc -l
 ├── extensions.yml
 ├── feature.json
 ├── project.json          # 阶段 6 从 references 复制，阶段 6.5 用当前会话数据合并更新
+├── session-logger.json   # AI 会话日志自动保存配置（hooks/session-logger.js 读取）
 ├── templates/
 │   ├── 01-业务需求分析模板.md
 │   ├── 02-产品需求说明书模板.md
@@ -1126,6 +1127,7 @@ mkdir -p "$TARGET/.adspecs"
     "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"
   }
@@ -1143,6 +1145,7 @@ mkdir -p "$TARGET/.adspecs"
 | `prd_dir`             | `docs/20-prd`                   | adspecs-prd、adspecs-plan（输入）、adspecs-front-spec（输入）、wiki-update（源）                                               |
 | `design_dir`          | `docs/30-system-design`         | adspecs-plan（输出）、adspecs-tasks、adspecs-front-spec（输出）、adspecs-front-tasks、adspecs-utest（输入）、wiki-update（源） |
 | `test_report_dir`     | `docs/80-development`           | adspecs-utest（测试报告）                                                                                                      |
+| `session_log_dir`     | `docs/80-development/800-log`   | session-logger（AI 会话日志）                                                                                                  |
 | `export_dir`          | `docs/90-export`                | adspecs-export-word（Word 导出输出）                                                                                           |
 | `wiki_dir`            | `wiki`                          | wiki-update（输出目标）                                                                                                        |
 

package/src/lib/paths-defaults.js

@@ -15,6 +15,7 @@ const DEFAULT_PATHS = {
   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',
 };

package/src/lib/scaffolder.js

@@ -55,7 +55,7 @@ async function scaffold(opts) {
     decisions,
     subDecisions = { conventions: 'skip', templates: {} },
     modeUpgrade = { detected: false, emptyDirs: [] },
-    logger = () => {},
+    logger = () => { },
   } = opts;
 
   const report = {
@@ -545,7 +545,15 @@ function writePathsJson(targetDir) {
  * 根据前端演示源解析前端规范目录名
  */
 function resolveFrontendStandard(frontDemoSource) {
-  return frontDemoSource === 'antd-front-demo' ? 'ant6-front-standard' : 'ecp-front-standard';
+  let nowFrontendStantard = 'antd-front-demo'
+  if (frontDemoSource === 'antd-front-demo') {
+    nowFrontendStantard = 'ant6-front-standard'
+  } else if (frontDemoSource === 'front-demo') {
+    nowFrontendStantard = 'ecp-front-standard'
+  } else if (frontDemoSource === 'vue3-front-standard') {
+    nowFrontendStantard = 'vue3-front-standard'
+  }
+  return nowFrontendStantard
 }
 
 module.exports = { scaffold };