# Zy Session

> 快速会话备份与恢复，防止终端崩溃丢失上下文

- Skill: `ian-zy1/zy-session` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ian-zy1/zy-session`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ian-zy1/zy-session/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Ian-zy1 (https://skillmd.com/u/ian-zy1)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ian-zy1/zy-session

---


# zy-session

> 快速会话备份与恢复，防止终端崩溃丢失上下文

## When to Use

- 用户说 `/zy-bak`、`/backup`、`备份会话` → 执行备份
- 用户说 `/zy-recall`、`/recall`、`恢复会话` → 执行恢复
- 用户要离开/结束会话时 → 建议备份
- 用户新开一个会话回到之前的项目时 → 建议恢复

## 存储路径

`~/.claude/skills/zy-session/memory/{project_slug}/`

每个项目独立子目录。slug 使用**最后两层目录**避免通用名冲突：

| 工作目录 | 存储路径 |
|---------|---------|
| `/Users/yongzhao/dev/project/auth` | `memory/project_auth/` |
| `/Users/yongzhao/dev/project/java/hw/docs` | `memory/hw_docs/` |
| `/Users/yongzhao`（home 目录） | `memory/yongzhao/` |

**slug 计算逻辑（备份和恢复共用）**：

```
if [ "$(pwd)" = "$HOME" ]; then
  PROJECT_SLUG="$(basename "$HOME")"
else
  DIR_PARENT=$(basename "$(dirname "$(pwd)")")
  DIR_BASE=$(basename "$(pwd)")
  PROJECT_SLUG="${DIR_PARENT}_${DIR_BASE}"
fi
```

> ⚠️ 注意：slug 只取最后两层目录。如果两个项目路径最后两层相同（如 `/a/dev/src` 和 `/b/dev/src`），会冲突——遇到时提醒用户。

---

## 备份流程（`/zy-bak`）

### Step 1: 确定项目 slug 并创建目录

```bash
mkdir -p ~/.claude/skills/zy-session/memory/${PROJECT_SLUG}
```

### Step 2: 生成备份文件名

格式：`YYYY-MM-DD_HHMM[_description].md`

示例：`2026-01-11_1430_session.md` 或 `2026-01-11_1430_用户登录模块.md`

### Step 3: 收集会话信息

**始终收集**：
- 当前时间戳
- 工作目录
- 当前 todo 列表（从对话上下文）
- zy-track 活跃需求快照（如果 `.project/requirements/` 存在）：每个需求一行，格式 `需求编号 + 目标（一句话）+ 进度（X/Y 标准完成）`

**条件收集**（仅在适用时）：
- Git 信息：分支、状态、最近 3 次提交

**询问用户**（仅在上下文不明确时）：
- 项目名称/概述
- 关键架构决策
- 重要文件路径

**不收集**：目录树、最近修改文件、环境变量、密钥

### Step 4: 清理旧备份（仅本项目）

保留最近 3 个备份：

```bash
ls -t ~/.claude/skills/zy-session/memory/${PROJECT_SLUG}/*.md 2>/dev/null | tail -n +4 | xargs rm -f 2>/dev/null
```

### Step 5: 生成备份文件

使用备份模板写入文件：@templates/backup-template.md

### 备份自检清单

```
□ 文件写入 ~/.claude/skills/zy-session/memory/{project_slug}/？
□ 文件名格式正确（时间戳）？
□ 待办事项是否完整？
□ 关键文件路径是否准确？
□ Git 信息（如适用）是否记录？
□ 恢复提示中是否包含 cd 命令？
□ 同项目旧备份已清理（保留最近 3 个）？
```

---

## 恢复流程（`/zy-recall`）

### Step 1: 列出可用备份

优先查找**当前目录对应项目**的备份（使用上面的 slug 逻辑）：

```bash
ls -lt ~/.claude/skills/zy-session/memory/${PROJECT_SLUG}/*.md 2>/dev/null | head -10
```

如果当前项目无备份，列出**所有项目**的备份（按时间排序）。

### Step 2: 选择备份

| 情况 | 行为 |
|------|------|
| 当前项目有备份 | 默认加载最新的 |
| 当前项目无备份 | 展示所有项目的备份供选择 |
| 带参数 | `/zy-recall 2026-01-11_1430_用户登录.md` 或 `/zy-recall 用户登录` |
| `--list` | 仅展示，不加载 |

### Step 3: 读取并解析备份文件

使用 Read 工具加载备份内容。

### Step 4: 切换工作目录

**立即**切换到备份中的工作目录。如果目录不存在，警告用户并询问正确路径——**不要静默失败**。

### Step 5: 恢复工作状态

恢复到上下文的内容：
1. **项目概述** — 正在做什么项目
2. **当前任务** — 当时在做什么
3. **Todo 列表** — 用 `todowrite` 重建（字段映射见下方）
4. **架构决策** — 做出的关键决策
5. **关键文件** — 重要文件位置
6. **恢复提示** — 恢复需要的命令

### Step 6: 验证当前状态

检查备份后是否有变化：

```bash
if git rev-parse --is-inside-work-tree &>/dev/null; then
  git status --short
  git log -3 --oneline
fi
```

如有新提交、分支变更、未提交变更差异，提醒用户。

### Step 7: 报告恢复结果

使用恢复输出模板展示摘要：@templates/restore-output-template.md

### Step 8: 衔接 zy-track（深度联动）

如果 `.project/requirements/` 存在：

1. **读取每个需求的状态**：目标、完成标准进度（X/Y）、最后更新时间
2. **对比备份时间与需求更新时间**，分情况处理：

| 情况 | 输出 |
|------|------|
| 需求在备份后有新进展 | `📌 需求 {NNN} 在你备份后有新进展（{进度}），建议 /zy-track resume` |
| 需求在备份后无变化 | `📌 需求 {NNN} 上次停在 {进度}，继续？` |
| 需求有未采纳的 `.xr.md` 评审结果 | `📌 需求 {NNN} 有未采纳的交叉评审结果，建议先处理` |

3. **一键跳转**：用户确认后，直接执行 resume 逻辑（读取需求文件、展示目标和范围外、确认会话范围），不需要用户再手动输入 `/zy-track resume`
4. 如果用户说"不用"，跳过，完成恢复

---

## TodoWrite 恢复字段映射

```javascript
todowrite({
  todos: [
    { content: "任务描述", status: "in_progress|pending|completed", priority: "high|medium|low" }
  ]
})
```

**备份章节 → Todo 状态映射**：

| 备份章节 | Todo 状态 |
|---------|----------|
| `### 进行中` | `"in_progress"` |
| `### 待办` | `"pending"` |
| `### 已完成` | `"completed"` |

**仅支持**：`content`, `status`, `priority` 三个字段。不支持 `activeForm`, `description`, `assignee` 等。

---

## 错误处理

### 无备份文件

```
⚠️ 未找到备份文件
请先使用 /zy-bak 创建备份
查找路径: ~/.claude/skills/zy-session/memory/
```

### 工作目录不存在

```
⚠️ 备份中的工作目录不存在: {{BACKUP_PWD}}
请确认项目位置后手动 cd
```

---

## Common Traps

1. **备份中不要记录环境变量或密钥** — 备份文件是明文 markdown，会泄露敏感信息
2. **不要跳过旧备份清理** — 无限制增长会占满磁盘，保留最近 3 个即可
3. **恢复时工作目录已删除不要静默失败** — 必须警告用户并询问正确路径
4. **todo 恢复只支持三个字段** — content/status/priority，不要尝试映射不支持的字段

## Related Skills

- **zy-track**：恢复会话后自动检测活跃需求，提供具体状态和一键 resume（见恢复流程 Step 8）
- **zy-xr**：恢复会话后，如果需求有未处理的交叉评审结果，提醒用户先处理

## 联动协议

本 skill 与 zy-track 通过以下数据契约联动：

| 联动 | 方向 | 触发时机 | 数据契约 |
|------|------|---------|---------|
| 备份含需求快照 | session → track | `/zy-bak` 时 | 需求列表 + 每个需求的进度（X/Y 标准完成），写入备份文件 |
| 恢复衔接需求 | session → track | `/zy-recall` 后 | 读取 `.project/requirements/*.md`，对比备份时间，分情况建议 |
| 评审结果检测 | session → xr | `/zy-recall` 后 | 检查 `*.xr.md` 是否存在且未采纳，提醒用户 |