Session State Tracker

外部端点

此技能不调用任何外部端点。所有操作均在工作区本地完成。

安全与隐私

• 完全本地运行：无网络访问；所有状态数据存储在工作区根目录的 SESSION_STATE.md 文件中。
• 文件作用域：该技能仅读写工作区根目录下的 SESSION_STATE.md 文件，不访问其他任何文件。
• 会话发现功能：session_state_discover 工具使用 memory_search，可能查询已索引的会话转录内容。此行为受你的 OpenClaw memorySearch 配置（本地向量数据库）控制。该技能本身不会发起任何外部 API 调用。
• 无数据外泄：除非你单独配置了外部记忆后端，否则没有任何数据会离开你的机器。

模型调用说明

该技能注册了三个生命周期钩子：

• pre-compaction：在压缩前自动运行，用于持久化状态。
• post-compaction：在压缩后自动运行，用于注入状态提醒。
• session-start：在会话开始时自动运行，用于加载最新状态。

这些钩子由 OpenClaw 核心触发，无需代理干预。工具（session_state_read、session_state_write、session_state_discover）可在需要时手动调用。

信任声明

使用本技能意味着所有状态管理均保持本地且透明。代码为开源，仅操作你的 SESSION_STATE.md 文件。请仅在信任作者并理解钩子自动化机制的前提下安装。

概述

Session State Tracker 通过生命周期钩子自动保存和恢复工作状态，解决 OpenClaw 会话压缩和重启时的上下文丢失问题。

核心功能

• 自动状态持久化：通过 OpenClaw 钩子实现（压缩过程中无需手动操作）。
• 带模式验证的状态文件：SESSION_STATE.md 使用 YAML frontmatter 格式。
• 原子写入：防止文件损坏。
• 发现工具：可在需要时从会话转录中重建状态。
• 命令行工具：支持手动检查和更新。
• 零外部依赖：除 Node.js 和 js-yaml 外无其他依赖。

文件格式

SESSION_STATE.md（工作区根目录）：

---
project: "my-project"
task: "描述当前任务"
status: "active"          # active | blocked | done | in-progress
last_action: "最新更新"
next_steps:
  - "步骤 1"
  - "步骤 2"
updated: "2026-02-14T23:20:00.000Z"
---

## 上下文
可选的自由文本笔记、约束条件、链接等。

所有 frontmatter 字段均为必填项，body（即上下文部分）除外。时间戳必须为 ISO 8601 格式。

安装

clawhub install qsmtco/session-state-tracker

或手动将技能文件夹复制到 skills/session-state-tracker/，并在 openclaw.json 中启用：

"skills": { "entries": { "session-state-tracker": { "enabled": true } } }

然后重启网关。

配置

该技能默认启用钩子，开箱即用。为使 session_state_discover 功能生效，请确保会话转录已启用索引：

"agents": {
  "defaults": {
    "memorySearch": {
      "sources": ["memory", "sessions"],
      "experimental": { "sessionMemory": true }
    }
  }
}

无需其他配置。

工具

• session_state_read – 读取当前状态（frontmatter + body）
• session_state_write – 更新字段（自动添加时间戳，校验模式）
• session_state_discover – 从近期会话中合成状态并写入文件

命令行工具（CLI）

# 显示状态
session-state show

# 更新某个字段
session-state set task "新任务"
session-state set next_steps '["A","B"]'

# 从会话转录中刷新状态（需启用 memory_search）
session-state refresh

# 清空状态
session-state clear

运作原理

1. 会话启动：session-start 钩子读取 SESSION_STATE.md；若文件存在且最近更新时间在 24 小时内，则将其摘要注入初始系统上下文。
2. 工作期间：可调用 session_state_write 记录进展。该文件是唯一真实来源。
3. 压缩前：pre-compaction 钩子自动保存当前状态（必要时通过发现机制），无需代理参与。
4. 压缩后：post-compaction 钩子注入 [State Anchor] 提醒，使代理立即重新锚定。
5. 重启后：流程重复，状态跨重启持续保留。

从 v1.x 升级指南

v2.0.0 引入了生命周期钩子。SESSION_STATE.md 文件格式未更改。升级方法如下：

• 安装 v2.0.0 或更高版本。
• 确保技能已启用。
• 钩子替代旧版 memoryFlush.prompt 机制；可移除配置中的自定义提示。
• 现有 SESSION_STATE.md 文件无需修改，仍可正常使用。

故障排除

• 钩子未触发？请确认技能已启用，且插件清单文件（openclaw.plugin.json）存在。安装后重启网关。
• session_state_discover 返回空结果？请启用会话转录索引（memorySearch.experimental.sessionMemory = true），并确保存在近期对话记录。
• 状态文件未更新？检查文件权限；该技能以原子方式写入工作区根目录的 SESSION_STATE.md。

轻量、可靠、全自动。