session 与历史记录

session 是持久化的 OpenSquilla 会话。你可以通过它查看过去的工作、恢复一段会话、导出 transcript，或停止仍在运行的 turn。

在以下情况使用 session：

从 CLI 或 Web UI 继续之前的聊天；
查找某个 artifact、成本报告或 channel 线程对应的 session key；
导出 transcript 用于排障或分享；
中止长时间运行的 turn 而不删除 session；
在不再需要旧 session 后删除它们。

前置要求

session 命令使用 gateway 的 RPC 接口。在运行大多数 session 命令之前，请先启动或连接 gateway：

opensquilla gateway run

或使用托管的后台 gateway：

opensquilla gateway start --json
opensquilla gateway status

列出最近的 session

opensquilla sessions list
opensquilla sessions list --limit 20
opensquilla sessions list --status idle
opensquilla sessions list --agent main
opensquilla sessions list --channel telegram
opensquilla sessions list --since 2026-05-01

在脚本中使用 --json：

opensquilla sessions list --json

查看一个 session

opensquilla sessions show <session-key>
opensquilla sessions show <session-key> --json

输出包含已解析的 session key、agent id、状态、模型、更新时间、标题，以及在可用时的最近预览。

恢复 session

opensquilla sessions resume <session-key>

该命令会在现有 session 上打开终端聊天。当你希望保留相同的会话状态而不是新开聊天时使用。

中止正在运行的 turn

opensquilla sessions abort <session-key>
opensquilla sessions abort <session-key> --json

abort 会停止正在运行的 turn（如果存在）。它不会删除 session。

导出 transcript

导出 Markdown：

opensquilla sessions export <session-key>
opensquilla sessions export <session-key> --output session.md

导出 JSON：

opensquilla sessions export <session-key> --format json --output session.json

导出的 transcript 可用于错误报告、审计，或将任务转入文档。在公开分享导出内容前，请移除其中的密钥、私有本地路径、provider token 以及私密 channel 标识符。

删除 session

opensquilla sessions delete <session-key>
opensquilla sessions delete <session-key> --yes

删除 session 用于清理。如果之后可能仍需要 transcript，请先导出。

Web UI 工作流

Web UI 使用同一套 session 系统。在控制台中，使用聊天 session 选择器切换 session、查看状态以及继续最近的工作。

打开：

http://127.0.0.1:18791/control/

排障

如果命令无法连接到 gateway：

opensquilla gateway status
opensquilla doctor

如果旧的上下文以摘要形式出现，说明该 session 可能对较早的历史进行了 compaction。这在上下文压力下的长 session 中是正常现象。当确切文本很重要时，请导出 session。