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 并创建目录

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 个备份：

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 逻辑）：

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: 验证当前状态

检查备份后是否有变化：

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 恢复字段映射

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 是否存在且未采纳，提醒用户