context-restore

# 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. 恢复级别选择

| 使用场景 | 推荐级别 |
|---------|---------|
| 快速确认当前状态 | Minimal |
| 日常继续工作 | Normal（默认） |
| 深度回顾/汇报 | Detailed |

### 3. 与其他技能配合

```markdown
# 恢复上下文 + 获取详细信息
/context-restore --level normal
-> 然后调用 memory_get 获取 MEMORY.md 详情

# 恢复上下文 + 搜索特定话题
/context-restore --level normal
-> 然后调用 memory_search "某个关键词"
```

---

## 配置文件

```yaml
# SKILL_CONFIG.md
context-restore:
  default_level: "normal"
  auto_trigger: true
  
  output:
    show_timeline: true
    max_projects: 5
    max_recent_actions: 10
    include_file_list: true
  
  limits:
    minimal_token: 50
    normal_token: 200
    detailed_token: 500
```

---

## 数据源

### 必需文件

```
./compressed_context/latest_compressed.json
```

### 可选文件

```
./memory/MEMORY.md          # 长期记忆
./memory/YYYY-MM-DD.md      # 每日记录
./projects/*/status.json    # 项目状态文件
```

### 上下文文件格式

```json
{
  "version": "1.0",
  "lastUpdated": "2026-02-06T23:42:00Z",
  "sessions": {
    "main": {"id": "main-2026-02-06", "active": true},
    "isolated": [...]
  },
  "projects": {...},
  "recentActions": [...],
  "timeline": [...]
}
```

---

## Phase 2: 时间线与对比功能 (Timeline & Comparison)

### 新增功能

#### 1. `--timeline` 时间线视图

按不同周期聚合历史操作，提供更清晰的进度回顾：

```bash
# 按天显示（默认）
python restore_context.py --timeline --period daily

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

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

# 限制时间范围（最近30天）
python restore_context.py --timeline --period weekly --days 30
```

**输出示例（weekly）：**
```
📅 Week 6 (Feb 2-8)
├── ✅ 完成数据管道测试
├── ✅ 部署新功能到生产环境
└── 🚀 项目: Hermes Plan, Akasha Plan

📅 Week 5 (Jan 26 - Feb 1)
├── ✅ 启动 Akasha UI 改进
└── 🚀 项目: Hermes Plan
```

#### 2. `--filter` 内容过滤

只显示匹配特定条件的内容：

```bash
# 只显示与 Hermes 相关的内容
python restore_context.py --filter "Hermes"

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

# 组合使用
python restore_context.py --filter "Hermes" --level detailed
```

**过滤逻辑：**
- 不区分大小写匹配
- 保留匹配行的上下文（前后2行）
- 如果没有匹配，返回提示信息

#### 3. `--diff` 上下文对比

比较两个版本的上下文差异：

```bash
# 基本对比
python restore_context.py --diff old.json new.json

# 详细对比
python restore_context.py --diff old.json new.json --level detailed

# 输出到文件
python restore_context.py --diff old.json new.json --output diff_report.txt
```

**对比报告包含：**
- 时间差
- 新增/移除/修改的项目
- 新增/移除的任务
- 新增/移除的操作
- 消息数量变化

### API 参考

```python
# 时间线提取
extract_timeline(content: str, period: str = "daily", days: int = 30) -> dict

# 内容过滤
filter_context(content: str, filter_pattern: str) -> str

# 上下文对比
compare_contexts(old: str, new: str) -> dict

# 格式化对比报告
format_diff_report(diff: dict, old_file: str, new_file: str) -> str
```

### 使用场景

#### 场景 1: 每日进度回顾

```bash
# 查看本周进度
python restore_context.py --timeline --period weekly
```

#### 场景 2: 项目变更追踪

```bash
# 只关注 Hermes 项目
python restore_context.py --filter "Hermes" --timeline --period weekly
```

#### 场景 3: 周期性对比报告

```bash
#!/bin/bash
# 生成每日对比报告
python restore_context.py --diff context_yesterday.json context_today.json \
    --output daily_diff_$(date +\%Y\%m\%d).txt
```

---

## Phase 3: 自动触发集成 (Auto Trigger)

### 新增功能

#### 1. 上下文变化检测 (Context Change Detection)

使用哈希算法检测上下文是否发生变化：

```python
from restore_context import hash_content, detect_context_changes, load_cached_hash, save_cached_hash

# 检测变化
current_hash = hash_content(current_content)
previous_hash = load_cached_hash()
if detect_context_changes(current_content, previous_content):
    print("Context changed!")

# 保存哈希缓存
save_cached_hash(current_hash, context_file)
```

#### 2. `--auto` 自动触发模式

自动检测上下文变化并在检测到变化时自动恢复：

```bash
# 自动检测并恢复
python restore_context.py --auto

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

# 指定恢复级别
python restore_context.py --auto --level detailed
```

#### 3. `--check-only` 检查模式

仅检查变化而不恢复，适合外部监控系统：

```bash
# 检查变化（返回退出码）
python restore_context.py --check-only
# 退出码 0: 无变化
# 退出码 1: 检测到变化
```

#### 4. `--install-cron` Cron 集成

安装自动上下文监控任务：

```bash
# 安装 cron 任务（默认每5分钟检查）
python restore_context.py --install-cron

# 自定义检查间隔
python restore_context.py --install-cron --cron-interval 10
```

输出示例：
```
✅ Cron script created: /home/athur/.openclaw/workspace/skills/context-restore/scripts/auto_context_monitor.sh
ℹ️  To install, run:
  echo "*/5 * * * * /home/athur/.openclaw/workspace/skills/context-restore/scripts/auto_context_monitor.sh >> /var/log/context_monitor.log 2>&1" >> ~/.crontab
  crontab ~/.crontab
```

### 使用场景

#### 场景 1: 定期自动恢复

```bash
# 设置 cron 任务，每5分钟自动检查并恢复
*/5 * * * * python3 /home/athur/.openclaw/workspace/skills/context-restore/scripts/restore_context.py --auto --quiet >> /var/log/context_restore.log 2>&1
```

#### 场景 2: 外部监控系统集成

```bash
#!/bin/bash
# 外部监控系统脚本
if python3 restore_context.py --check-only; then
    echo "No changes detected"
else
    echo "Context changed - triggering restore"
    python3 restore_context.py --auto
fi
```

#### 场景 3: 会话开始时自动恢复

在用户新会话开始时自动触发恢复：

```python
# 在会话初始化时调用
from restore_context import check_and_restore_context

result = check_and_restore_context(
    context_file='./compressed_context/latest_compressed.json',
    auto_mode=True,
    quiet=False,
    level='normal'
)

if result['changed'] and result['restored']:
    print(result['report'])
```

### API 参考

```python
# 变化检测函数
hash_content(content: str) -> str
detect_context_changes(current: str, previous: str) -> bool
load_cached_hash(cache_file: str) -> Optional[str]
save_cached_hash(content_hash: str, context_file: str, cache_file: str) -> bool

# 自动恢复函数
check_and_restore_context(
    context_file: str,
    auto_mode: bool = False,
    quiet: bool = False,
    level: str = 'normal'
) -> dict

# 通知函数
send_context_change_notification(context_file: str, auto_mode: bool) -> bool

# Cron 集成函数
generate_cron_script() -> str
install_cron_job(script_path: str = None, interval_minutes: int = 5) -> bool
```

### 通知集成

当检测到上下文变化时，可以触发外部通知：

```python
# 通知脚本示例 (notify_context_change.py)
import sys

if __name__ == '__main__':
    # 解析参数
    context_file = sys.argv[2]  # --file 参数
    auto_mode = '--auto' in sys.argv
    
    # 发送通知（可集成 Telegram、邮件等）
    send_telegram_message(f"Context changed: {context_file}")
    send_email_notification(f"Context changed on {auto_mode}")
```

---

## 文件结构

```
skills/context-restore/
├── SKILL.md                    # 技能定义（本文档）
├── README.md                   # 项目说明
├── references/
│   └── design.md              # 设计决策文档
├── scripts/
│   ├── __init__.py
│   ├── restore_context.py     # 核心实现（完整代码）
│   │   └── 函数：
│   │       ├── load_compressed_context()  # 加载上下文文件
│   │       ├── parse_metadata()           # 解析元数据
│   │       ├── extract_recent_operations() # 提取最近操作
│   │       ├── extract_key_projects()      # 提取项目信息
│   │       ├── extract_ongoing_tasks()      # 提取任务信息
│   │       ├── extract_memory_highlights() # 提取MEMORY引用
│   │       ├── extract_timeline()          # Phase 2: 提取时间线
│   │       ├── filter_context()            # Phase 2: 过滤内容
│   │       ├── get_context_summary()       # 获取结构化摘要
│   │       ├── compare_contexts()          # Phase 2: 对比上下文
│   │       ├── format_diff_report()        # Phase 2: 格式化对比报告
│   │       ├── restore_context()           # 主入口函数
│   │       ├── hash_content()              # Phase 3: 内容哈希
│   │       ├── detect_context_changes()    # Phase 3: 变化检测
│   │       ├── load_cached_hash()          # Phase 3: 加载缓存哈希
│   │       ├── save_cached_hash()          # Phase 3: 保存缓存哈希
│   │       ├── check_and_restore_context() # Phase 3: 自动恢复
│   │       ├── send_context_change_notification() # Phase 3: 通知
│   │       ├── generate_cron_script()      # Phase 3: 生成cron脚本
│   │       └── install_cron_job()          # Phase 3: 安装cron任务
│   └── robustness_improvements.py  # 健壮性改进模块
│
├── docs/
│   ├── USAGE.md               # 使用指南（完整示例）
│   ├── API.md                 # API 参考文档
│   └── auto_context_monitor.sh   # Phase 3: 自动监控脚本
└── tests/
    ├── __init__.py
    ├── test_restore_basic.py   # 基础功能测试
    ├── test_error_handling.py # 错误处理测试
    └── test_integration.py     # 集成测试
```