session-viewer-plugin

session-viewer-plugin

会话指标查看插件：为 Vue3 + Element Plus 宿主应用提供「本地会话浏览」页面组件，配套可挂载的服务端路由。云端文件管理能力已迁移至宿主 tnnotix。

• 本地会话：扫描本机会话快照 JSON，按会话卡片、月度分组、收藏筛选浏览，并提供步骤时间线 / Token / 工具调用等图表的详情页。

完整接入说明见 INTEGRATION.md。

架构（两种接入形态）

形态一（推荐）：进程内挂载 —— 单进程，零额外部署
┌───────────────────────────────┐
│ 宿主服务进程 (:3000)           │
│  静态页面 + 插件组件(同源fetch) │
│  createApp() 挂载 /api 路由 ───┼──▶ 本机会话快照目录
└───────────────────────────────┘

形态二（可选）：独立运行 —— 前台单进程
npx session-viewer-plugin ──▶ 静态托管页面 + API (:3001) ──▶ 同上数据源

快速开始

npm i session-viewer-plugin

形态一（进程内挂载）：

// 宿主服务端（Express 或原生 http 均可，详见 INTEGRATION.md §3）
import { createApp } from 'session-viewer-plugin/server'
const svApp = createApp()   // 未监听的 Express 实例，直接挂载/转发

// 宿主前端（同源模式，不传 baseUrl）
import 'session-viewer-plugin/ui.css'
import { SessionViewer, SessionDetail } from 'session-viewer-plugin/ui'

形态二（独立运行）：

# 安装并启动（一条命令，前台运行，Ctrl+C 停止）
npx session-viewer-plugin

# 或先全局安装、长期使用
npm i -g session-viewer-plugin
session-viewer-plugin start

启动后前台占住终端并打印 Server running on http://127.0.0.1:<port>，浏览器打开该地址即可查看页面 + API（同一端口）。按 Ctrl+C 停止并释放端口。

端口避让：未指定端口时默认 3001，被占用则自动 +1 重试（上限 +100）；显式指定端口（--port）时被占用则直接报错退出。

session-viewer-plugin --port 8080          # 指定端口（被占用报错退出）
session-viewer-plugin --host 0.0.0.0       # 局域网/容器访问
session-viewer-plugin --log-dir /path/to/metrics  # 覆盖扫描目录
session-viewer-plugin --help               # 查看帮助

包导出

宿主前端要求：Vue ≥ 3.4、Element Plus ≥ 2.4（需注册 v-loading 指令）。宿主服务端要求：Node ≥ 18。

环境变量

样本目录：默认扫描目录还包含 <opencode-metrics-plugin 日志根>/samples（Windows %LOCALAPPDATA%\opencode-metrics-plugin\Log\samples，macOS ~/Library/Logs/opencode-metrics-plugin/samples）。外部/分析样本（他人机器的会话快照）请放入该目录：仅用于可视化查看，插件孤儿补传只扫 metrics 目录本身，不会上传此处文件。服务启动时自动创建该目录。

开发

仓库为前后端双包结构，既可作为 npm 包发布，也可独立运行：

npm run setup         # 安装 server + frontend 依赖
npm run dev           # 同时启动后端(:3001)与前端开发壳(:5173)
npm run build         # 构建 server/dist、frontend/dist-ui 与 frontend/dist
npm run standalone    # 一键构建 + 前台启动独立服务

• 后端：Express 5 + TypeScript（server/），app.ts 为应用工厂（bin 与宿主挂载共用）。
• 前端：Vue 3 + Vite + Element Plus（显式导入）；frontend/src/plugin-entry.js 为库入口，独立开发壳为 frontend/src/main.js。
• 发布产物：server/dist（服务端）+ frontend/dist-ui（组件库，供宿主 import）+ frontend/dist（独立运行页面，供 bin 静态托管）。

数据持久化

收藏与会话自定义目录存储在用户级全局数据目录（env-paths 的 hm-plugin 数据目录），与包安装位置解耦：

• Windows：%LOCALAPPDATA%\hm-plugin-data
• macOS：~/Library/Application Support/hm-plugin-data
• Linux：~/.local/share/hm-plugin-data

因此 npx 缓存清理、npm uninstall -g 卸载、重装均不丢收藏数据。旧版（server/data/config.json）会在首次启动时自动迁移到该目录。