---
name: ads-save-session
description: "保存当前 AI 会话为结构化 Markdown 日志。生成含摘要、产物清单、决策记录的 .log 文件到 docs/80-development/800-log/。Use when user asks to save session, log session, or before /clear."
agent_created: true
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` — 路径配置