session-viewer-plugin 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# session-viewer-plugin
+
+会话指标查看插件：提供可嵌入 Vue3 + Element Plus 宿主应用（如 tnnotix）的视图组件库，搭配一个独立伴生服务（HTTP + CORS）提供数据。
+
+- **本地会话**：扫描本机会话快照 JSON，按会话卡片、月度分组、收藏筛选浏览，并提供步骤时间线 / Token / 工具调用等图表的详情页。
+- **云端数据**：管理 AGC（华为云存储）桶内文件，支持按前缀浏览、下载、重命名、删除，并可在线配置凭证与连通性测试。
+
+## 架构
+
+```
+宿主应用(任意 Vue3+EP)                  伴生服务(本插件 bin)
+┌────────────────────┐   HTTP/CORS   ┌──────────────────────┐
+│ SessionViewer      │ ────────────▶ │ GET /api/sessions    │──▶ 本机会话快照目录
+│ SessionDetail      │               │ GET /api/cloud/*     │──▶ AGC 云存储
+│ CloudFileList      │               │ ...                  │──▶ 运行时配置(data 目录)
+└────────────────────┘               └──────────────────────┘
+```
+
+宿主只负责渲染，服务独立进程运行（同机部署即可，前端经 `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
+```
+
+```js
+import { createApp } from 'vue'
+import ElementPlus from 'element-plus'
+import 'element-plus/dist/index.css'
+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')
+```
+
+### 导出内容
+
+| 导出 | 说明 |
+| --- | --- |
+| `SessionViewer` | 会话列表页（含侧栏分组/收藏/搜索），`@select-session` 返回会话 id |
+| `SessionDetail` | 会话详情页，props：`sessionId`（必填）、`baseUrl`；插槽 `#header-actions` |
+| `CloudFileList` | 云端文件管理页 |
+| `API_BASE_KEY` / `setApiBase` / `getApiBase` / `useApiBase` | API 基址管理；组件 prop `baseUrl` 优先于 provide 注入 |
+
+宿主要求：Vue ≥ 3.4、Element Plus ≥ 2.4（需 `app.use(ElementPlus)` 或至少注册 `v-loading` 指令）。
+
+## Docker 部署
+
+```bash
+npm run build:server
+docker build -t session-viewer-plugin .
+docker run -d -p 3001:3001 session-viewer-plugin
+```
+
+## 开发
+
+仓库为前后端双包结构：
+
+```bash
+npm run setup         # 安装 server + frontend 依赖
+npm run dev           # 同时启动后端(:3001)与前端开发壳(:5173)
+npm run build         # 构建 server/dist 与 frontend/dist-ui
+```
+
+- 后端：Express 5 + TypeScript（`server/`）。
+- 前端：Vue 3 + Vite + Element Plus（显式导入）；`frontend/src/plugin-entry.js` 为库入口，独立开发壳为 `frontend/src/main.js`。
+- 发布产物：`server/dist`（伴生服务）+ `frontend/dist-ui`（组件库）。