session-viewer-plugin 0.1.1 → 0.1.3

package/README.md

@@ -1,90 +1,76 @@
 # session-viewer-plugin
 
-会话指标查看插件：提供可嵌入 Vue3 + Element Plus 宿主应用（如 tnnotix）的视图组件库，搭配一个独立伴生服务（HTTP + CORS）提供数据。
+会话指标查看插件：为 Vue3 + Element Plus 宿主应用提供「本地会话浏览」与「AGC 云端文件管理」页面组件，配套可挂载的服务端路由。
 
 - **本地会话**：扫描本机会话快照 JSON，按会话卡片、月度分组、收藏筛选浏览，并提供步骤时间线 / Token / 工具调用等图表的详情页。
-- **云端数据**：管理 AGC（华为云存储）桶内文件，支持按前缀浏览、下载、重命名、删除，并可在线配置凭证与连通性测试。
+- **云端数据**：管理 AGC（华为云存储）桶内文件：前缀浏览、全桶模糊搜索（定位 + 剪枝）、下载、重命名、删除、文件夹递归删除、复制下载令牌。
 
-## 架构
+完整接入说明见 **[INTEGRATION.md](./INTEGRATION.md)**。
+
+## 架构（两种接入形态）
 
 ```
-宿主应用(任意 Vue3+EP)                  伴生服务(本插件 bin)
-┌────────────────────┐   HTTP/CORS   ┌──────────────────────┐
-│ SessionViewer      │ ────────────▶ │ GET /api/sessions    │──▶ 本机会话快照目录
-│ SessionDetail      │               │ GET /api/cloud/*     │──▶ AGC 云存储
-│ CloudFileList      │               │ ...                  │──▶ 运行时配置(data 目录)
-└────────────────────┘               └──────────────────────┘
+形态一（推荐）：进程内挂载 —— 单进程，零额外部署
+┌───────────────────────────────┐
+│ 宿主服务进程 (:3000)           │
+│  静态页面 + 插件组件(同源fetch) │
+│  createApp() 挂载 /api 路由 ───┼──▶ 本机会话快照目录 / AGC 云存储
+└───────────────────────────────┘
+
+形态二（可选）：独立伴生服务 —— 分进程部署
+宿主页面 ──baseUrl──▶ session-viewer-plugin bin (:3001) ──▶ 同上数据源
 ```
 
-宿主只负责渲染，服务独立进程运行（同机部署即可，前端经 `baseUrl` 直连或反向代理）。
-
-## 快速开始（伴生服务）
+## 快速开始
 
 ```bash
 npm i session-viewer-plugin
-npx session-viewer-plugin          # 默认 http://127.0.0.1:3001
 ```
 
-### 环境变量
-
-| 变量 | 默认值 | 说明 |
-| --- | --- | --- |
-| `PORT` | `3001` | 监听端口 |
-| `HOST` | `127.0.0.1` | 绑定地址；容器部署需设 `0.0.0.0` |
-| `LOG_DIR` | 内置目录集 | 覆盖扫描目录（单目录；容器部署时配合卷挂载使用） |
-| `AGC_CREDENTIALS_FILE` | - | AGC 凭证 JSON 文件路径（优先级最高） |
-| `AGC_CREDENTIALS_JSON` | - | AGC 凭证内联 JSON 字符串 |
-
-### AGC 凭证
-
-固定通过项目文件配置，按优先级：**环境变量 > 包内默认文件**。
+**形态一（进程内挂载）**：
 
-- 包内默认文件：`server/src/assets/agc-apiclient.json`（构建时随包发布到 `server/dist/assets/`），仓库内维护。
-- 环境变量覆盖：`AGC_CREDENTIALS_FILE`（凭证文件路径）或 `AGC_CREDENTIALS_JSON`（内联 JSON）。
-- 必填字段：`client_id`、`client_secret`、`project_id`、`bucket_name`；`region` 缺省为 `CN`。
-
-## 宿主应用集成（Vue3 + Element Plus）
-
-```bash
-npm i session-viewer-plugin element-plus @element-plus/icons-vue
+```ts
+// 宿主服务端（Express 或原生 http 均可，详见 INTEGRATION.md §3）
+import { createApp } from 'session-viewer-plugin/server'
+const svApp = createApp()   // 未监听的 Express 实例，直接挂载/转发
 ```
 
 ```js
-import { createApp } from 'vue'
-import ElementPlus from 'element-plus'
-import 'element-plus/dist/index.css'
+// 宿主前端（同源模式，不传 baseUrl）
 import 'session-viewer-plugin/ui.css'
-import { SessionViewer, CloudFileList, API_BASE_KEY } from 'session-viewer-plugin/ui'
-
-const app = createApp({
-  components: { SessionViewer, CloudFileList },
-  template: `
-    <SessionViewer base-url="http://127.0.0.1:3001" @select-session="onSelect" />
-  `,
-})
-app.use(ElementPlus)                       // 需注册 v-loading 指令
-app.provide(API_BASE_KEY, 'http://127.0.0.1:3001')  // 或统一注入基址，组件可不传 prop
-app.mount('#app')
+import { SessionViewer } from 'session-viewer-plugin/ui'
 ```
 
-### 导出内容
+**形态二（独立服务）**：
+
+```bash
+npx session-viewer-plugin          # 默认 http://127.0.0.1:3001
+```
+
+## 包导出
 
 | 导出 | 说明 |
 | --- | --- |
-| `SessionViewer` | 会话列表页（含侧栏分组/收藏/搜索），`@select-session` 返回会话 id |
-| `SessionDetail` | 会话详情页，props：`sessionId`（必填）、`baseUrl`；插槽 `#header-actions` |
-| `CloudFileList` | 云端文件管理页 |
-| `API_BASE_KEY` / `setApiBase` / `getApiBase` / `useApiBase` | API 基址管理；组件 prop `baseUrl` 优先于 provide 注入 |
+| `session-viewer-plugin/ui` | `SessionViewer` / `SessionDetail` / `CloudFileList` / `API_BASE_KEY` / `setApiBase` 等基址工具 |
+| `session-viewer-plugin/ui.css` | 组件样式 |
+| `session-viewer-plugin/server` | `createApp()` 工厂（未监听的 Express 实例） |
+| `npx session-viewer-plugin` | 独立服务 bin（`PORT` / `HOST` 环境变量） |
 
-宿主要求：Vue ≥ 3.4、Element Plus ≥ 2.4（需 `app.use(ElementPlus)` 或至少注册 `v-loading` 指令）。
+宿主前端要求：Vue ≥ 3.4、Element Plus ≥ 2.4（需注册 `v-loading` 指令）。宿主服务端要求：Node ≥ 18。
 
-## Docker 部署
+## 环境变量
 
-```bash
-npm run build:server
-docker build -t session-viewer-plugin .
-docker run -d -p 3001:3001 session-viewer-plugin
-```
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `LOG_DIR` | 内置目录集 | 会话快照扫描目录（单目录）；默认自动探测 hm-plugin-nodejs 与 opencode-metrics-plugin 的标准落盘目录（Linux 为 `~/.local/state/opencode-metrics-plugin/metrics`） |
+| `AGC_CREDENTIALS_FILE` | - | AGC 凭证 JSON 文件路径 |
+| `AGC_CREDENTIALS_JSON` | - | AGC 凭证内联 JSON 字符串 |
+| `PORT` | `3001` | 独立服务监听端口（bin 形态） |
+| `HOST` | `127.0.0.1` | 独立服务绑定地址；容器部署需 `0.0.0.0`（bin 形态） |
+
+**样本目录**：默认扫描目录还包含 `<opencode-metrics-plugin 日志根>/samples`（Windows `%LOCALAPPDATA%\opencode-metrics-plugin\Log\samples`，macOS `~/Library/Logs/opencode-metrics-plugin/samples`）。外部/分析样本（他人机器的会话快照）请放入该目录：仅用于可视化查看，插件孤儿补传只扫 metrics 目录本身，不会上传此处文件。服务启动时自动创建该目录。
+
+**AGC 凭证**：npm 包不含凭证文件。凭证归属 opencode-metrics-plugin（AGC 桶上传方），运行时通过 `AGC_CREDENTIALS_FILE` / `AGC_CREDENTIALS_JSON` 注入；必填字段 `client_id`、`client_secret`、`project_id`、`bucket_name`，`region` 缺省 `CN`。未配置时本地会话功能不受影响，云端功能返回 503。
 
 ## 开发
 
@@ -96,6 +82,6 @@ npm run dev           # 同时启动后端(:3001)与前端开发壳(:5173)
 npm run build         # 构建 server/dist 与 frontend/dist-ui
 ```
 
-- 后端：Express 5 + TypeScript（`server/`）。
+- 后端：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`（组件库）。
+- 发布产物：`server/dist`（服务端）+ `frontend/dist-ui`（组件库）。