@forget2save/opencode-trajectory

v0.1.1

Published

11 days ago

Inspect and export complete OpenCode conversation trajectories, including tools, reasoning, changes, compaction, and child sessions.

0High
0Medium
0Low

forget2save

opencode opencode-plugin trajectory conversation trace debugging tui

@forget2save/opencode-trajectory

在 OpenCode 中查看和导出完整对话 trajectory。它不只展示用户和助手文本，还会保留 OpenCode 已存储的：

reasoning 文本与时间；
工具名称、调用 ID、状态、完整输入、输出、错误、元数据和附件；
file、patch、snapshot、step-start、step-finish；
subtask、agent、retry、compaction；
消息模型、Agent、token、成本、错误和原始 JSON；
当前会话的全部后代/子 Agent 会话。

插件有两个可独立使用的入口：

| 入口 | 用途 | | --- | --- | | @forget2save/opencode-trajectory/tui | 在 TUI 中直接打开全屏、可搜索的 trajectory 查看器，不经过模型 | | @forget2save/opencode-trajectory | 提供 trajectory_export 工具和 /trajectory-export 命令，导出离线 HTML、Markdown 或 JSON |

安装

需要 OpenCode >=1.16.0 <1.19.0。TUI 入口与经过验证的 OpenTUI 0.4.5、Solid 1.9.12 配套。

安装交互查看器：

opencode plugin @forget2save/opencode-trajectory/tui -g

如需导出工具，再安装服务端入口：

opencode plugin @forget2save/opencode-trajectory -g

也可以在 opencode.jsonc 中显式配置两个入口：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    [
      "@forget2save/opencode-trajectory/tui",
      {
        "includeChildSessions": true,
        "maxSessions": 500,
        "outputDirectory": ".opencode/trajectory"
      }
    ],
    [
      "@forget2save/opencode-trajectory",
      {
        "includeChildSessions": true,
        "maxSessions": 500,
        "outputDirectory": ".opencode/trajectory"
      }
    ]
  ]
}

TUI 查看器

进入任意会话后执行：

/trajectory

别名为 /trace。这是 TUI 本地命令，不发送提示词、不调用模型，也不增加 token 消耗。

| 快捷键 | 行为 | | --- | --- | | j / k、↑ / ↓ | 选择上一条或下一条消息 | | Enter | 展开或收起选中消息 | | / | 搜索提示词、推理、工具输入/输出、路径和元数据 | | f | 在全部、对话、工具、推理、变更、控制事件之间筛选 | | a | 展开或收起全部消息 | | x | 在展开内容中显示原始 part/message JSON | | e | 导出当前完整快照为离线 HTML | | r | 立即刷新 | | ? | 查看快捷键 | | Esc | 清除搜索/筛选，再按一次返回原会话 |

查看器监听消息、part 和会话事件；活动会话变化后会自动重新读取。子会话以 ↳ 层级标记，并与主会话消息按时间组成一条全局 timeline。

导出工具

在对话中执行以下命令；省略格式时默认生成 HTML：

/trajectory-export html
/trajectory-export markdown
/trajectory-export json

Agent 也可以直接调用：

trajectory_export({ format: "html", include_subsessions: true })

默认写入当前项目的 .opencode/trajectory/。写入使用同目录临时文件和原子重命名，避免留下半成品。

HTML 是不依赖 CDN 的单文件查看器，支持：

全文搜索与按角色/事件类型筛选；
单条或全局展开/收起；
完整工具输入输出和 reasoning；
每个 part 和 message 的原始 JSON；
从页面下载同一快照的原始 JSON；
打印样式。

JSON 的顶层格式为：

{
  "schemaVersion": 1,
  "capturedAt": "2026-08-14T00:00:00.000Z",
  "rootSessionID": "session-id",
  "sessions": [
    {
      "info": {},
      "depth": 0,
      "children": [],
      "messages": [
        {
          "info": {},
          "parts": [],
          "sourceIndex": 0
        }
      ]
    }
  ]
}

sourceIndex 保留 API 原始数组位置；展示 timeline 会按消息创建时间稳定排序。未知或未来新增的 part 字段不会被丢弃。

配置

| 配置项 | 默认值 | 说明 | | --- | --- | --- | | includeChildSessions | true | 递归读取全部后代会话；设为 false 时只看当前会话 | | maxSessions | 500 | 单次 trajectory 最多读取的会话数，范围 1..10000；超限会明确失败而不是静默截断 | | outputDirectory | .opencode/trajectory | 导出目录；相对路径以当前会话工作目录为起点，也支持绝对路径 |

“完整”的边界

这里的完整是指 OpenCode 会话 API 当前存储并返回的全部 message info、parts 和后代会话。以下内容无法凭插件恢复：

模型供应商从未返回给 OpenCode 的隐藏 chain-of-thought；
已被用户或 OpenCode 永久删除的数据；
API 只保留摘要而未保留原文的外部内容；
导出瞬间仍在运行的工具未来才产生的输出。

如果 reasoning part 已由 OpenCode 保存，插件会原样展示和导出，不做二次摘要。

隐私与安全

Trajectory 很可能包含源码、文件路径、命令、环境信息、工具输出和其他敏感数据：

插件只通过本机 OpenCode API 读取数据；
导出完全写入本地，不自动分享或上传；
导出文件默认位于 .opencode/trajectory/，应加入项目忽略规则；
分享 HTML、Markdown 或 JSON 前必须自行审查；
不要把导出文件提交到公开仓库。

OpenCode 自带的 opencode export 适合获取原始会话 JSON；本插件重点补充 TUI 交互查看、子会话递归、统一 timeline 和可读的离线报告。

开发

npm install
npm run typecheck
npm test
npm run verify
npm pack --dry-run

npm run verify 会执行类型检查、测试、构建和双入口 smoke test。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@forget2save/opencode-trajectory

安装

TUI 查看器

导出工具

配置

“完整”的边界

隐私与安全

开发