Zy Session

zy-session

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

When to Use

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

存储路径

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

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

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: 选择备份

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. 对比备份时间与需求更新时间，分情况处理：

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

TodoWrite 恢复字段映射

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

备份章节 → Todo 状态映射：

仅支持：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 通过以下数据契约联动：