诊断与 Replay

诊断与 replay 有助于解释 OpenSquilla 某个 turn 中发生了什么。当结果出乎意料、缓慢、昂贵、被中断，或仅凭聊天记录难以复现时，请使用它们。

诊断

诊断是通过 gateway 暴露的运行时日志控制。

查看状态：

opensquilla diagnostics status
opensquilla diagnostics status --json

启用诊断：

opensquilla diagnostics on

当维护者需要更深入的 provider 请求证据时，启用原始 turn 调用捕获：

opensquilla diagnostics on --raw

收集到足够证据后关闭诊断：

opensquilla diagnostics off

何时使用诊断

在以下情况下使用诊断：

provider 重试、超时或空响应；
SquillaRouter 模型决策；
prompt-cache 或 cache-break 调查；
compaction 生命周期事件；
大型工具结果压缩；
channel 投递失败；
异常高的成本或延迟。

避免让原始诊断开启的时间超过必要时长。原始捕获可能包含私有 prompt、工具输出、本地路径或 provider 可见的内容。

Replay 一个已记录的 turn

Replay 从决策日志中读取一个已记录的 turn 并打印人类可读的对话内容。它是只读的：不会重新运行工具。

opensquilla replay --session <session-key> --turn <turn-id>

在以下情况使用 replay：

聊天已经进行下去，但你需要检查较早的某个 turn；
错误报告需要简明的复现证据；
你希望将对话输出与诊断及成本数据进行对比。

TUI Replay 基准测试

开发者可以在没有实时 provider 的情况下重放确定性的终端聊天 fixture：

uv run python scripts/bench_tui_replay.py --renderer opentui --fixture long-stream --summary-json .artifacts/tui/opentui-long-stream.json
uv run python scripts/bench_tui_replay.py --renderer opentui --fixture dense-history --summary-json .artifacts/tui/opentui-dense-history.json

基准测试摘要包括 renderer 可用性、事件计数、文本大小、工具与 router 决策计数、墙钟时间、flush 计数、最大缓冲文本、合并比率、对话条目计数、可见视口计数、展开的工具计数、视口投影时间、最终文本匹配状态、插件错误计数以及错误。

阅读 features/tui-frontend.md 了解后端状态，阅读 tui-real-terminal-harness.md 了解终端级别的启动证据。

将 Replay 与 Sessions 搭配使用

首先找到 session：

opensquilla sessions list
opensquilla sessions show <session-key>

当精确上下文很重要时，导出完整 session：

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

安全共享

在公开共享诊断、replay 输出或导出的 sessions 之前，请移除：

provider key 与 bearer token；
私有的本地路径；
私有的 channel 标识；
不应公开的客户、项目或账户名称；
包含机密内容的原始 provider prompt 或工具输出。