opencode-session-web

一个 OpenCode V2 CLI 插件：在本地起一个网页，管理所有项目的全部 session —— 浏览对话、重命名、删除、查看 token 与上下文用量。在 TUI 输入 /session-web 即可在浏览器打开。

✨ 功能

• 🌍 所有项目的 session 汇聚一个列表 —— 按项目筛选，按最近活动排序
• 💬 完整对话流：用户/助手文本、可折叠的 Thinking（推理）块、可折叠的工具调用（一行摘要：命令/文件/URL、退出码徽章、编辑操作渲染语法染色 diff）
• 📁 会话级 Files changed 汇总条：本会话改过的每个文件带 +/- 统计，点击跳到最后一次编辑
• 助手正文支持 Markdown 标题、列表、表格、引用、链接和代码。常用代码语言使用深色语法高亮；解析结果有缓存，代码在视口附近才高亮。未知语言和超过 12,000 字符的代码块保留普通样式。资源本地打包，原始 HTML 转义显示。
• ⚡ 长对话秒开：先渲染最近 50 条消息，通过“加载更早消息”按钮按 100 条向上翻阅，且保持阅读位置不跳动。统计和 JSON 导出始终覆盖整个会话。
• ✏️ 重命名 / 删除走官方 session API —— TUI/桌面端下次拉取即可见，无需重启
• 📊 用量统计一目了然：token 构成条（in/out/reasoning）、缓存读写、消息数，以及按 user/assistant/tools 细分的上下文窗口使用率进度条
• 💾 将 session 导出为 JSON 或自包含 HTML 快照
• 🌗 GitHub 风格浅色 / 深色主题，附系统跟随 —— 页面右上角一键切换，本地记忆；导出的 HTML 快照同样带主题切换
• ⌨️ /session-web 命令 —— 插件自动注册，一键在浏览器打开管理页
• 🖥️ ocsw CLI —— 同一个 npm 包附带独立终端命令：ocsw open <id>、ocsw ls、ocsw export <id>、ocsw rm <id>[,<id>...]、ocsw stop；完全独立，网页服务由 ocsw 自行提供（默认后台），无需 TUI

📦 安装

面向 OpenCode V2（opencode ≥ 2.0）。这是一个 CLI 插件：注册在 ~/.config/opencode/cli.json 的 plugins 字段（不存在则创建），不是 opencode.json。

方式 1：让 Agent 帮你装（推荐）

把这段话粘给 OpenCode 或任意 LLM Agent：

Install the opencode-session-web plugin by following the instructions here:
https://raw.githubusercontent.com/aihaipeng/opencode-session-web/main/README.md

方式 2：npm 安装

{
  "plugins": [{ "package": "opencode-session-web" }]
}

无需手动操作 —— OpenCode 启动时会自行拉取 npm 插件。插件只注册两个 TUI 命令；网页服务由 ocsw CLI 提供。保留已有条目；plugins 数组可同时装多个插件。加载卡住？见疑难解答。

方式 3：本地目录

git clone https://github.com/aihaipeng/opencode-session-web.git
cd opencode-session-web
bun install
bun run build

在目标项目创建 .opencode/plugins/opencode-session-web/tui.ts，内容一行（指向克隆仓库的构建产物）：

export { default } from "C:/path/to/opencode-session-web/dist/tui.js"

重启 opencode 即可加载。注意 2.0.16 的 cli.json 本地绝对路径不会触发加载，请走 .opencode/plugins/ 目录。

⬆️ 更新

• npm 安装：重启 opencode；插件在启动时重新解析。若仍加载旧版本，删除 ~/.cache/opencode/packages/opencode-session-web@latest/ 后再重启。
• 本地安装：git pull，然后 bun install && bun run build，重启。

🤖 给 LLM Agent 的说明

1. 不要让用户安装 Bun —— OpenCode 用自带运行时安装 npm 插件。启动卡住：运行 opencode --print-logs；若包解析卡死，删除 ~/.cache/opencode/ 后重试。

2. 编辑 ~/.config/opencode/cli.json（不存在则创建）—— CLI 插件在 plugins 字段，不是 opencode.json。

3. 以对象形式加入插件（纯包名字符串也可以），保留已有条目：

   {
     "plugins": [{ "package": "opencode-session-web" }]
   }

4. 无需手动 npm install / bun add —— OpenCode 启动时自行拉取 npm 插件。

5. 重启 opencode。在 TUI 输入 /session-web，或在终端执行 ocsw open <id>（ocsw ls 可列出 id）打开页面验证。

🚀 使用

| 操作 | 结果 | | --- | --- | | TUI 输入 /session-web | 在浏览器打开管理页，并直接定位到当前会话 | | TUI 输入 /session-export | 将 TUI 当前会话导出为自包含 HTML 快照，写入该会话所属项目目录下的 session-exports/，并以 toast 提示文件路径 | | 点击 session | 详情视图：对话 + 统计面板 | | ✎ / 🗑 按钮 | 重命名 / 删除（删除为两段式：按钮变红，再点一次确认） | | 详情头部 ✏️ 按钮 | Your messages 面板：你发过的全部消息按日期分组 —— 点击日期展开当日，点击条目跳转定位（面板不关闭，可拖动标题栏移动） | | 行内 ⧉ 按钮 | 复制 opencode --session <id>，可在终端直接恢复该 session | | 勾选 + 侧栏 🗑 角标按钮 | 批量删除选中 session（两段式：按钮变红，再点一次确认） | | 项目筛选框旁的 ☑ | 全选 / 取消全选当前视图内的 session | | 拖动侧栏边缘 | 调整列表宽度以查看长标题（自动记忆） | | ⬇ / </> 按钮 | 导出原始 JSON / 导出自包含 HTML 快照（全量代码高亮，离线可开；顶部统计区固定、可折叠，并带同款可拖动消息目录面板） | | Session details 栏 | 折叠式统计：上下文窗口、token、消息数 | | 头部下方 Files changed 芯片 | 会话改过的每个文件带 +/- 统计；点击跳到最后一次编辑该文件的消息 |

🖥️ CLI：ocsw

npm 包同时附带一个独立终端命令 —— 完全独立，无需 TUI。全局安装后即可使用：

ocsw                    # 显示命令表格（等同 -h）
ocsw open <id>          # 打开页面并跳转到该会话；命令立即返回，
                        # 页面由后台服务承载
ocsw ls                 # 先输出汇总行（projects/sessions 数量），再按项目列出
                        # 会话（时间、id、标题）
ocsw export <id>        # 导出会话为自包含 HTML 并自动打开
ocsw rm <id>[,<id>...]  # 彻底删除会话——按 id（唯一前缀）；逗号或空格
                         # 分隔一次删多个
ocsw stop               # 停止后台服务

• open/export 必须带会话 id —— 先 ocsw ls 查看。id 支持唯一前缀匹配（ocsw export ses_f2b6）；打开时永远以 ?session=<id> 深链定位，详情页不会出现空白。
• 页面由 ocsw 自身服务：open 拉起后台服务并立即返回；已在运行的服务会被直接复用。ocsw stop 停止。-p <n> 指定端口——缺省静默探测第一个可用端口（4310-4314，失败用随机端口）。
• 一次性命令（ls/export/rm）不留任何驻留进程：为其自起的 opencode 服务在结束时一并关闭；只有 open 保持进程运行（页面 daemon）。
• rm 只按 id 删除（与 TUI/桌面端相同的存储级删除 DELETE /api/session/:id——彻底删除、不可恢复、非归档）。opencode 允许不同项目同名，项目名不是可靠目标，故不支持。单个 id（唯一前缀）不询问直接删；多个 id（逗号或空格分隔，任意空白混排：a,b = a, b = a b = 换行分隔均可，空元素忽略；PowerShell 下逗号串需加引号）先列清单再问 y/N（非 y 一律取消；脚本中可 echo y | ocsw rm ...）。批量中任一 id 无效则整批失败、零删除；重复 id 自动去重。
• ls 的汇总行用淡绿、项目名用亮洋红、会话 id 用青色高亮；export 打印的文件路径用暗绿色。染色仅在终端输出时启用，管道/重定向保持纯文本。
• export：导出到会话所属项目目录（session-exports/<标题>-<时间戳>.html），打印路径并自动打开。
• 所有命令都会自动发现运行中的 opencode 服务，没有则启动一个后台服务。

npm install -g opencode-session-web   # 将 ocsw 加入 PATH

发布前本地开发：在仓库根目录执行一次 npm link，之后任意目录可直接用 ocsw（撤销：npm rm -g opencode-session-web）；仓库内任意子目录也可 npm run ocsw -- <args>。

🧠 工作原理

• 列表读取 GET /api/session —— 全局跨项目列表（OpenCode V2）
• API 请求复用 OpenCode 提供给 CLI 插件的客户端（含鉴权）；无需另外启动 opencode serve
• 重命名 / 删除代理官方 session API（PATCH / DELETE /api/session/:id）—— 所以改动会同步到 TUI 和桌面端
• 上下文使用率 = 最后一条助手消息的 token 用量 ÷ 模型上下文窗口（来自 GET /api/model）；user/assistant/tools 细分按字符占比估算 —— API 未暴露精确的分部分 token
• 页面只绑定 127.0.0.1，服务路径只有一条：网页由 ocsw CLI 自身承载——open 拉起后台服务（ocsw stop 停止）；TUI 插件不自建服务，它的命令只是驱动同一套 CLI 核心；一次性命令（ls/export/rm）结束后不留任何进程
• 打开页面永远带 ?session=<id> 深链；无深链直接访问时页面显示明确的空态，不做猜测
• 无鉴权 —— 本机任意进程都能访问；请保持仅本地使用

🛠️ 疑难解答

• ocsw open 提示 "background server did not become ready"：后台服务未能绑定端口。用 -p <n> 换一个空闲端口重试；若有残留记录，ocsw stop 会清理。
• 页面打不开 / 显示 "Is opencode running?"：网页服务只在 ocsw open（或 TUI /session-web）启动后存在。ocsw ls 不依赖页面服务——连它也失败时，运行 opencode --print-logs 查找 [opencode-session-web] 日志。opencode --pure 会跳过所有外部插件 —— 可用来排查。
• 没有 /session-web 命令：确认插件装在 cli.json 的 plugins 字段（V2 CLI 插件不读 opencode.json 的 plugin 字段），且 opencode ≥ 2.0。插件不再接受 options.port —— 端口由 ocsw open -p 提供。
• 页面能开但 "Failed to load sessions"：opencode --print-logs 查看服务端错误；旧版本（< 1.0）面向 V1 API，请升级到 1.x。
• 上下文显示 —：从 GET /api/model 解析不到该模型的上下文窗口（自定义/OAuth 模型有时缺失 limit）。
• TUI 卡在加载界面：自带运行时解析包卡住（代理/慢网络常见）。删除 ~/.cache/opencode/ 重试，或改用源码构建。

🧑‍💻 开发

bun install
bun run build      # 打包服务端、声明及内嵌全部脚本的 ui.html
bun run typecheck  # tsc --noEmit
bun run test       # 构建并验证 web 路由、页面集成、CLI 命令、markdown 安全与资源释放

📂 项目结构

src/
├── index.ts       # no-op server 入口（V2 包加载器要求；功能在 CLI 入口）
├── tui.ts         # CLI 插件壳：/session-web 与 /session-export 驱动 CLI 核心
├── cli.ts         # ocsw 终端命令：open / export / ls / rm / stop
├── core.ts        # 两个入口共用的数据访问、web 服务与导出核心
├── ui.html        # 网页 UI（vanilla JS，GitHub 浅色/深色主题）
├── render.ts      # 页面与 HTML 导出共用的会话渲染模块
├── markdown.ts    # 安全 Markdown 渲染、有上限的缓存、按需代码高亮
├── markdown-browser.ts # 浏览器入口，打包后内嵌到 ui.html
└── markdown.css   # Markdown 排版和语法颜色

如果这个插件对你有用，欢迎点个 ⭐ —— 帮助更多人发现它。

📄 许可

MIT