# session-continuity

**Repository Path**: chazzorg/session-continuity

## Basic Information

- **Project Name**: session-continuity
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# session-continuity

中文 | [English](README.en.md)

`session-continuity` 是一个 OpenClaw 插件，用于在 OpenClaw 因空闲、重置或会话轮转而创建新 session 时，显式生成并注入上一会话的交接上下文。

它主要解决长时间无对话后 OpenClaw 静默切换新 session 的问题：对话端没有明显提示，模型却已经失去旧上下文，容易误以为自己仍理解前文。这个插件会记录上一 session 的 transcript，生成一份紧凑交接摘要，并在下一次 prompt 构建前注入，让模型明确知道“这是新 session”，并基于交接摘要继续工作。

## 功能

- 监听 `session_end`，记录上一会话元数据并关联到下一个 session。
- 读取归档 transcript，包括 `*.jsonl.reset.*` 这类 reset 后的 session 文件。
- 先从 transcript 尾部快速写入一份草稿交接，避免摘要模型较慢时首轮没有上下文。
- 在后台生成 LLM 精摘要；如果首轮已注入草稿，则把精摘要保存为 `finalHandoffSummary`，不覆盖真实注入内容。
- 在 `before_prompt_build` 阶段把 handoff 注入到新 session 的 prompt。
- 默认只注入一次，避免后续轮次重复消耗上下文。
- 状态文件默认保存在 `~/.openclaw/state/session-continuity.json`。

## 项目结构

- `dist/index.js` - OpenClaw 插件入口。
- `openclaw.plugin.json` - 插件 manifest 和配置 schema。
- `scripts/install-local.sh` - 把当前项目同步到 OpenClaw 全局扩展目录。

## 安装

在仓库目录执行：

```bash
npm run install:local
openclaw gateway restart
```

安装脚本会把项目同步到：

```text
~/.openclaw/extensions/session-continuity
```

然后确认 OpenClaw 配置中启用了插件：

```json
{
  "plugins": {
    "entries": {
      "session-continuity": {
        "enabled": true,
        "hooks": {
          "allowPromptInjection": true,
          "timeouts": {
            "session_end": 60000,
            "before_prompt_build": 5000
          }
        },
        "config": {
          "maxTranscriptChars": 60000,
          "maxHandoffChars": 2200,
          "readyWaitMs": 4000,
          "pendingTtlMs": 604800000,
          "maxStateSessions": 80,
          "summaryTimeoutMs": 55000,
          "injectOnce": true
        }
      }
    }
  }
}
```

## 验证

语法检查：

```bash
npm run check
```

检查运行时插件状态：

```bash
openclaw plugins inspect session-continuity --runtime --json
```

检查状态文件摘要：

```bash
npm run status
```

检查最近 hook 日志：

```bash
journalctl -u openclaw.service --no-pager --since "2 hours ago" | rg "session-continuity|before_prompt_build|session_end|session_start"
```

## 配置项

- `enabled` - 设置为 `false` 可关闭插件逻辑。
- `statePath` - 自定义 handoff 状态文件路径。
- `maxTranscriptChars` - 用于摘要的 transcript 尾部最大字符数，默认 `60000`。
- `maxHandoffChars` - handoff 摘要最大字符数，默认 `2200`。
- `readyWaitMs` - `before_prompt_build` 等待 handoff 就绪的时间，默认 `4000`，最大 `4500`。
- `pendingTtlMs` - pending handoff 的最长保留时间，默认 7 天。
- `maxStateSessions` - 状态文件中最多保留的 session 记录数，默认 `80`。
- `summaryTimeoutMs` - 后台 LLM 精摘要最长等待时间，默认 `55000`。
- `injectOnce` - 成功注入后是否消费 handoff，默认 `true`。
- `summarizeReasons` - 需要生成摘要的 session 结束原因列表。

## 升级与维护

这个仓库是源码真相源。OpenClaw 实际加载的是安装后的副本：

```text
~/.openclaw/extensions/session-continuity
```

修改本仓库后，按下面流程同步到运行环境：

```bash
npm run check
npm run install:local
openclaw gateway restart
```