context-restore

Skill that restores conversation context when users want to "continue where we left off". Reads compressed context files, extracts key information (recent operations, projects, tasks), and provides structured output to help users quickly resume their work.

# Context Restore Skill

## 快速开始

```bash
# 基础使用 - 恢复上下文
/context-restore

# 指定恢复级别
/context-restore --level detailed
/context-restore -l minimal

# 命令行工具
python scripts/restore_context.py --level normal

# 获取结构化摘要（供其他技能使用）
python scripts/restore_context.py --summary

# 用户确认流程
python scripts/restore_context.py --confirm

# Telegram 消息分块发送
python scripts/restore_context.py --telegram

# ========== Phase 3: 自动触发集成 ==========

# 自动检测并恢复上下文（检测到变化时自动恢复）
python scripts/restore_context.py --auto

# 自动模式，静默输出（适合 cron）
python scripts/restore_context.py --auto --quiet

# 仅检查变化（返回退出码 0/1）
python scripts/restore_context.py --check-only

# 安装 cron 自动监控任务
python scripts/restore_context.py --install-cron
```

---

## 功能说明

### 核心价值

让用户在 `/new`（开启新会话）后快速恢复工作状态：
- 无需重复解释背景
- 秒级恢复到之前的工作状态
- 自然语言触发，无感恢复
- 支持用户确认流程
- Telegram 消息自动分块

### 目标用户场景

| 场景 | 用户需求 | 恢复内容 |
|------|---------|---------|
| 跨天继续工作 | 昨天做到哪了？ | 项目进度、待办任务 |
| 任务切换后回来 | 之前在做什么？ | 当前任务状态、关键文件 |
| 中断后继续 | 接着刚才的聊 | 对话历史节点 |
| 周期性回顾 | 这周做了哪些事？ | 时间线摘要、成果列表 |

---

## 触发条件

### 中文关键词

```
核心词: 恢复上下文、继续之前的工作
扩展词: 恢复、接着、继续、之前聊到哪了、继续之前的工作、
        继续之前的任务、接着做、回到之前的工作、恢复工作状态
```

### 英文关键词

```
核心词: restore context、continue previous work
扩展词: continue、resume、what was I doing、where did we leave off、
        get back to work、resume session
```

### 命令格式

```
/context-restore [选项]
/restore [选项]
恢复上下文 [级别]
restore context [level]
```

### 级别参数

| 参数 | 效果 |
|------|------|
| `minimal` / `min` / `简短` | 极简模式（核心状态一句话） |
| `normal` / `default` / `正常` | 标准模式（默认，项目+任务） |
| `detailed` / `full` / `详细` | 完整模式（完整上下文+时间线） |

---

## 执行流程

```
1. 检测意图 → 关键词/命令识别
2. 加载上下文 → 读取 compressed_context/latest_compressed.json
3. 解析内容 → JSON 或纯文本格式
4. 提取信息 → 项目、任务、操作、时间线
5. 格式化输出 → 根据级别生成报告
6. 发送确认 → 用户确认后继续工作
```

---

## 恢复级别

### Minimal（极简）

**输出内容**：
- 核心状态一句话
- 1个活跃任务

**示例输出**：
```
✅ 上下文已恢复

状态：Hermes Plan 进行中（数据管道完成，待测试）
```

### Normal（标准，默认）

**输出内容**：
- 项目状态列表
- 待办任务列表
- 最近操作记录
- MEMORY.md 高亮

**示例输出**：
```
✅ 上下文已恢复

当前活跃项目：
1. 🏛️ Hermes Plan - 数据分析助手（进度：80%）
2. 🌐 Akasha Plan - 自主新闻系统（进度：45%）

待办任务：
- [高] 编写数据管道测试用例
- [中] 设计 Akasha UI 组件
- [低] 更新 README 文档

最近操作（今天）：
- 完成数据清洗模块
- 添加 3 个新 cron 任务
- 修改配置文件
```

### Detailed（完整）

**输出内容**：
- 完整会话概览
- 所有项目详情
- 完整任务队列（按优先级分类）
- 7天时间线
- 原始内容预览

**示例输出**：
```
✅ 上下文已恢复（完整模式）

═══════════════════════════════════════
📊 会话概览
═══════════════════════════════════════
当前会话：#2026-02-06-main
活跃 Isolated Sessions：3个
最后活动：2小时前

═══════════════════════════════════════
🎯 核心项目状态
═══════════════════════════════════════
1. Hermes Plan（进行中）- 进度：80%
2. Akasha Plan（待恢复）- 进度：45%

[...完整时间线和历史记录]
```

---

## API / 命令行参数

### Python API

```python
from restore_context import (
    restore_context,
    get_context_summary,
    extract_timeline,
    compare_contexts,
    filter_context
)

# 基础恢复
report = restore_context(filepath, level="normal")

# 获取结构化摘要（供其他技能使用）
summary = get_context_summary(filepath)
# 返回格式：
# {
#   "success": True,
#   "metadata": {...},
#   "operations": [...],
#   "projects": [...],
#   "tasks": [...],
#   "timeline": {...},
#   "memory_highlights": [...]
# }

# 提取时间线
timeline = extract_timeline(content, period="weekly", days=30)
# 返回格式：
# {
#   "period": "weekly",
#   "total_days": 30,
#   "total_operations": 15,
#   "timeline": [
#     {
#       "period_label": "Week 6 (Feb 2-8)",
#       "date_range": "2026-02-02 to 2026-02-08",
#       "operations": [...],
#       "projects": [...],
#       "highlights": [...]
#     }
#   ]
# }

# 对比两个版本
diff = compare_contexts(old_file, new_file)
# 返回格式：
# {
#   "success": True,
#   "added_projects": [...],
#   "removed_projects": [...],
#   "modified_projects": [...],
#   "operations_added": [...],
#   "operations_removed": [...],
#   "time_diff_hours": 24.0,
#   ...
# }

# 过滤内容
filtered = filter_context(content, "Hermes Plan")
```

### 命令行参数

```bash
python restore_context.py [选项]

基础选项：
  --file, -f           上下文文件路径（默认：绝对路径 compressed_context/latest_compressed.json）
  --level, -l          恢复级别（minimal/normal/detailed，默认：normal）
  --output, -o         输出文件路径
  --summary, -s        输出结构化摘要（JSON 格式）
  --confirm            添加用户确认流程（询问用户是否继续）
  --telegram           Telegram 消息分块发送（自动分割长消息）
  --since              仅包含指定日期后的操作（YYYY-MM-DD 格式）
  --help, -h           显示帮助信息

Phase 2 - 时间线与过滤选项：
  --timeline           启用时间线视图
  --period             时间线聚合周期（daily/weekly/monthly，默认：daily）
  --filter             过滤关键词，只显示匹配内容
  --diff               对比两个版本（需要两个文件路径）

Phase 3 - 自动触发选项：
  --auto               自动模式：检测到变化时自动恢复，无需用户确认
  --quiet              静默模式：仅显示必要消息（与 --auto 配合使用）
  --check-only         仅检查变化，不恢复（返回退出码 0/1）
  --install-cron       生成并安装 cron 自动监控任务
  --cron-interval      Cron 间隔分钟数（默认：5，与 --install-cron 配合）
```

### 完整命令行示例

```bash
# 使用默认配置
python restore_context.py

# 详细模式输出到文件
python restore_context.py --level detailed --output report.txt

# 最小模式
python restore_context.py -l minimal

# 自定义文件路径
python restore_context.py -f /path/to/context.json

# 结构化 JSON 输出
python restore_context.py --summary

# 用户确认流程
python restore_context.py --confirm

# Telegram 消息分块发送
python restore_context.py --telegram

# ========== Phase 2: 时间线与过滤 ==========

# 按天显示时间线（默认）
python restore_context.py --timeline --period daily

# 按周显示时间线
python restore_context.py --timeline --period weekly

# 按月显示时间线
python restore_context.py --timeline --period monthly

# 过滤特定内容
python restore_context.py --filter "Hermes"

# 只显示项目相关信息
python restore_context.py --filter "project"

# ========== Phase 2: 上下文对比 ==========

# 对比两个版本
python restore_context.py --diff old.json new.json

# 对比并输出详细报告
python restore_context.py --diff old.json new.json --level detailed

# ========== Phase 3: 自动触发示例 ==========

# 自动检测并恢复（检测到变化时自动恢复）
python restore_context.py --auto

# 自动模式，静默输出（适合 cron）
python restore_context.py --auto --quiet

# 检查变化（外部监控使用）
python restore_context.py --check-only
echo $?  # 0=无变化, 1=有变化

# 安装 cron 任务
python restore_context.py --install-cron

# 安装 cron 任务（每10分钟）
python restore_context.py --install-cron --cron-interval 10

# 完整自动恢复（详细级别）
python restore_context.py --auto --level detailed
```

---

## 输出格式

### 标准消息格式

```markdown
✅ **上下文已恢复** [级别标识]

[主要内容块]

---
💡 **操作建议**
• 建议操作 1
• 建议操作 2
```

### Normal 级别统一输出格式

```
✅ **上下文已恢复**

📊 **压缩信息:**
- 原始消息: {original_count}
- 压缩后: {compressed_count}
- 压缩率: {compression_ratio}%

🔄 **最近操作:**
- 操作1
- 操作2

🚀 **项目:**
- **项目名称** - 描述
```

### Telegram 消息分块

当消息超过 4000 字符时，自动分块发送：

```bash
# Telegram 模式下，输出会自动分割
python restore_context.py --telegram
# [1/3]
# 第一块内容...
# [2/3]
# 第二块内容...
# [3/3]
# 第三块内容...
```

### 平台适配

| 平台 | 格式调整 |
|------|---------|
| Telegram | 使用 emoji 前缀，自动分块发送（--telegram） |
| Discord | 使用 embed 格式 |
| WhatsApp | 无 markdown，简化格式 |
| CLI | 纯文本，树形结构 |

---

## 错误处理

| 场景 | 处理方式 | 用户消息 |
|------|---------|---------|
| 文件不存在 | 创建空上下文，记录警告 | "未找到历史上下文，将从新会话开始" |
| 文件损坏 | 尝试降级读取 | "上下文文件异常，已重置为初始状态" |
| 解析失败 | 返回 minimal 版本 | "部分上下文无法恢复，已获取核心信息" |
| 权限错误 | 记录日志，静默失败 | "无法访问上下文文件，请检查权限" |

---

## 与其他技能的集成

### 集成关系

```
Context-Restore 依赖:
├── context-save (保存上下文)
├── memory_get (读取 MEMORY.md)
└── memory_search (搜索历史)

Context-Restore 提供给:
├── summarize (项目摘要)
├── task-manager (待办列表)
└── weekly-review (时间线回顾)
```

### 配合 context-save 使用

```markdown
**context-save**：会话结束时自动保存上下文
**context-restore**：会话开始时恢复上下文

配合流程：
1. 用户结束会话 → context-save 自动保存
2. 用户 new session → context-restore 自动/手动触发
3. 用户确认 → 继续工作
```

### 供其他技能调用的结构化输出

```python
from restore_context import get_context_summary

def my_skill():
    summary = get_context_summary()
    
    if summary['success']:
        # 使用项目信息
        for project in summary['projects']:
            process_project(project)
        
        # 使用任务信息
        for task in summary['tasks']:
            schedule_task(task)
        
        # 使用最近操作
        for operation in summary['operations']:
            log_operation(operation)
```

---

## 最佳实践

### 1. 推荐使用流程

```markdown
1. 用户进入新会话
2. 说 "继续之前的工作"
3. 查看恢复报告
4. 选择继续的任务
5. 开始工作
```

### 2. 恢复级别选择

| 使用场景 | 推荐级别 |
|---------|-