@leiyi-works/dsh-aivideo 0.0.0-stage → 2.7.0

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# @leiyi-works/dsh-aivideo · AI视频（Flova + 人物/场景/剧本素材 + H3 出片）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH Web UI 的一站式视频生产插件：**Flova 负责小说→剧本→分镜**，**人物 / 场景 / 剧本素材面板**负责翻素材，**RunningHub H3 / Seedance 负责分镜→出片**，全部在同一个插件里。
+
+面板**本体**内置八个页签：**生成 / 视频 / 人物 / 场景 / 剧本 / 使用说明 / 脚本 / Flova** —— 「视频」页只读浏览/播放 `D:\DSH工作区\AI创作\视频` 里的已生成成片；使用说明与运行脚本都随插件打包，并自动同步到 `~/.dsh/h3-kit/`，因此 DSH 备份会一并带上（换机可直接恢复）。
+
+## 三个本地素材插件已合并进本插件（2026-11-14）
+
+原来的 `dsh-character-gallery`（人物）、`dsh-scene-gallery`（场景）、`dsh-script-library`（剧本）已合并进来，现在**只装这一个插件**就同时具备：
+
+| 能力 | 来源 | 实现 |
+|---|---|---|
+| **人物面板** | `dsh-character-gallery` | 只读路由 `GET /runninghub-app/characters` + `GET /runninghub-app/character-image?path=…`；角色库固定 `D:\DSH工作区\AI创作\人物`，每个子目录一个角色，`三视图.png` 必需，定妆图/各角度视图/角色说明.md 可选 |
+| **场景面板** | `dsh-scene-gallery` | 只读路由 `GET /runninghub-app/scenes`（支持 `?dir=`）+ `GET /runninghub-app/scene-image?path=…`；默认扫描 `D:\DSH工作区\AI创作\场景` |
+| **剧本面板** | `dsh-script-library` | 只读路由 `GET /runninghub-app/script-library` + `GET /runninghub-app/script-file?path=…` + `GET /runninghub-app/script-image?path=…`；默认扫描 `D:\DSH工作区\AI创作\剧本`，只收「像剧本」的 .md（过滤手册/README/API 等文档） |
+
+三个来源插件的源码目录仍保留在 `D:\DSH工作区\dsh-character-gallery`、`dsh-scene-gallery`、`dsh-script-library` 作参考，但已从 profile 的依赖与 bundles 中移除（避免重复注册面板、路由与左栏入口）。
+
+素材面板的目录默认值 = 原 profile 里的配置，可用 `~/.dsh/runninghub-app.json` 的同名键覆盖（读到就用，读不到用默认；不需要界面配置）：
+
+| 配置键 | 作用 | 默认值 |
+|---|---|---|
+| `characterDir` | 人物库根目录 | `D:\DSH工作区\AI创作\人物` |
+| `dirs` | 场景扫描目录（每项只扫一层） | `["D:\DSH工作区\AI创作\场景"]` |
+| `scriptDirs` | 剧本扫描目录（每项只扫一层） | `["D:\DSH工作区\AI创作\剧本"]` |
+| `imageDirs` | 剧本正文内嵌图片白名单 | 原 profile 的 8 个目录（ComfyUI-run 六项 + AI创作 场景/剧本） |
+
+## Flova 已合并进本插件（2026-11-14）
+
+原来的独立插件 `dsh-flova` 已合并进来，现在**只装这一个插件**就同时具备：
+
+| 能力 | 实现 |
+|---|---|
+| **Flova 技能** `flova` | Host 注册 skill provider，正文在 `skill/flova-SKILL.md`；对话里直接说「用 flova 写剧本/拆分镜」即可 |
+| **Flova 账号状态** | 只读路由 `GET /runninghub-app/flova/status`（调用 `flova auth status` + `flova account user`，带 5 秒缓存，不消耗积分）|
+| **面板「Flova」页** | 显示登录状态、积分余额、账号邮箱、CLI 路径、检查时间，可刷新；附使用说明 |
+
+`dsh-flova` 源码目录仍保留在 `D:\DSH工作区\dsh-flova` 作参考，但已从 profile 的依赖与 bundles 中移除（避免重复注册技能）。
+
+## 打开方式（左栏入口 + 右栏引导页 + 设置页）
+
+| 入口 | 行为 |
+|---|---|
+| **左侧栏「AI视频」** | 点一下：左侧对话留在前台，**DSH 原生右侧栏**打开/聚焦「AI视频」tab（八页签）；右栏关掉后再点可重新打开；连续点只会聚焦同一 tab，不会重复实例。若原生右栏不可用，自动回退为整页面板。 |
+| 右侧栏「+」引导页 →「AI视频」 | 与上面相同的原生右栏 tab。 |
+| 设置 →「AI视频」 | 整页版本（同一面板）。 |
+
+左侧入口注册在 `sidebar.panellist`（order 42），图标复用本插件的 AI视频 tab 图标；点击时先 `ctx.layout.selectPanel(null)` 回到会话，再在 microtask 里调用 `ctx.sidebarRight.openTab("h3-direct")`（原生右栏 API 在会话被全局面板覆盖时会拒绝打开，所以顺序不能反）。内部 id（`h3-direct` / `h3-direct-panel`）保持不变，避免破坏既有 layout 状态；**用户可见文案一律是「AI视频」**。
+
+## 面板八页
+
+从上面任一入口打开后，顶部可切换：
+
+| 页签 | 内容 |
+|---|---|
+| **生成** | 现有工作流面板：载入 RunningHub 工作流 → 选择视频生成区块 → 编辑参数（提示词/时长/种子/比例等）→ 确认弹窗后提交 → 轮询输出成片 URL |
+| **视频** | 浏览 `D:\DSH工作区\AI创作\视频` 里的一层 `.mp4`（子目录「抽帧」等不列出）：名称/大小/时间列表 + 点击**面板内播放**（原生 `<video controls>`，可拖动进度/音量/全屏）+ 刷新 + 复制目录路径；空态提示「还没有生成的视频」 |
+| **人物** | 角色 chips 切换；三视图大图 + 定妆图/正面/侧面/背面/特写缩略网格；点图**放大预览**、复制完整路径；显示角色说明.md |
+| **场景** | 按目录筛选的缩略图网格（全部 / 各目录 chips）；点图放大预览、复制完整路径 |
+| **剧本** | 下拉切换剧本 + 正文 Markdown 渲染（标题/列表/表格/代码块/引用/行内代码）；正文内嵌图片可点开放大；复制完整路径 |
+| **使用说明** | 渲染插件自带 `docs/H3工作流手册.md`（标题/表格/列表/代码块/引用/加粗），支持刷新 |
+| **脚本** | 列出插件自带 `scripts/` 下的运行脚本（文件名/大小/时间），点开只读查看代码，可「复制路径」 |
+| **Flova** | Flova 登录状态、积分余额、账号邮箱、CLI 路径与检查时间，可刷新 |
+
+> 「剧本」页是本地剧本库阅读器；「脚本」页是插件自带运行脚本查看器，两者不是一回事。
+> 不再有单独的「H3 使用说明」右侧栏入口；说明与脚本都在「AI视频」面板内部。
+
+## Better Sidebar 可选
+
+「AI视频」的右栏 tab 通过 **DSH 原生右侧栏**注册（`ctx.sidebarRightTabs.register` + `sidebar.right.pane.tab` slot + `ctx.sidebarRight.openTab`），**不依赖 dsh-better-sidebar**：
+
+- 装了 Better Sidebar：仍从原生右栏「+」引导页打开，行为一致（本插件不调用 `betterSidebar` 服务）；也可从 设置 →「AI视频」打开同一面板。
+- **没装 Better Sidebar（当前默认）**：功能完全不变——右栏「+」→「AI视频」，八页签正常。
+- 八页签在右栏和设置页里都可用；说明/脚本的 `~/.dsh/h3-kit/` 同步与 Better Sidebar 无关，不受影响。
+
+## 内置说明 + 脚本与自动同步（重要）
+
+插件自带两个目录作为**唯一源**（随插件代码版本走）：
+
+- `docs/H3工作流手册.md` — 使用说明
+- `scripts/` — 运行脚本（`run-xianxia-v7.js`、`run-xianxia-v6b.js`、`run-battle2x15.js`、`run-miyu-v2.js`、`README.md`）
+
+插件**加载时**会把它们逐字节覆盖复制到：
+
+```
+%USERPROFILE%\.dsh\h3-kit\H3工作流手册.md
+%USERPROFILE%\.dsh\h3-kit\scripts\run-xianxia-v7.js
+%USERPROFILE%\.dsh\h3-kit\scripts\run-xianxia-v6b.js
+%USERPROFILE%\.dsh\h3-kit\scripts\run-battle2x15.js
+%USERPROFILE%\.dsh\h3-kit\scripts\run-miyu-v2.js
+%USERPROFILE%\.dsh\h3-kit\scripts\README.md
+```
+
+同步失败只记日志、不影响插件。这样 `@xiaoyuyu6420/dsh-backup` 备份 `~/.dsh` 时，会连同**使用说明 + 脚本**一起打包。
+
+- 改说明/脚本只改插件里的 `docs/`、`scripts/`，然后重载插件（`set_plugin` 关→开触发 HMR，**禁止 remove_bundle**）或打开一次面板，`~/.dsh/h3-kit/` 即更新。
+- 手动刷新说明：面板「使用说明」页 → 刷新（`GET /runninghub-app/manual` 每次调用也会重同步手册）。
+
+## Host 只读路由
+
+| 路由 | 说明 |
+|---|---|
+| `GET /runninghub-app/manual` | `{name, path, mtime, content}`，固定读插件自带 `docs/H3工作流手册.md` |
+| `GET /runninghub-app/scripts` | `[{name, sizeKB, mtime}]`，只列 `scripts/` 下 `.js`/`.md` |
+| `GET /runninghub-app/script?name=<文件名>` | `{name, path, mtime, content}`；白名单（`scripts/` 内 `.js`/`.md`）之外/穿越/不存在 → 404，>512KB → 413 |
+| `GET /runninghub-app/videos` | `[{name, path, sizeMB, mtime}]`，扫描 `D:\DSH工作区\AI创作\视频` 的一层 `.mp4`（跳过子目录），mtime 倒序；目录不存在时自动创建并返回 `[]` |
+| `GET /runninghub-app/video?path=<绝对路径>` | 只允许 `AI创作\视频` 内的 `.mp4`；支持 `Range`（206 + `Content-Range`，可拖动进度/边下边播），`Content-Type: video/mp4`；越权/不存在/非 mp4 → 404；非 GET → 405 |
+| `GET /runninghub-app/characters` | 角色列表：`{character, dir, files:[{name,type,sizeKB,mtime,path}], cover, notes}` |
+| `GET /runninghub-app/character-image?path=<绝对路径>` | 只允许角色库内的 png/jpg/jpeg/webp/gif；越权/非图片 → 404 |
+| `GET /runninghub-app/scenes`（可选 `?dir=`） | 场景图片列表：`{dir, name, path, sizeKB, mtime}`，mtime 倒序 |
+| `GET /runninghub-app/scene-image?path=<绝对路径>` | 只允许配置场景目录内的 png/jpg/jpeg/webp；越权/非图片 → 404 |
+| `GET /runninghub-app/script-library`（可选 `?dir=`） | 剧本 .md 列表：`{dir, name, path, sizeKB, mtime}`，只收通过「剧本」过滤的文件 |
+| `GET /runninghub-app/script-file?path=<绝对路径>` | `{name, path, mtime, content}`；只允许剧本目录内、通过剧本过滤的 .md；>512KB → 413 |
+| `GET /runninghub-app/script-image?path=<绝对路径>` | 剧本内嵌图片；只允许 `imageDirs` 白名单内的 png/jpg/jpeg/webp |
+| `GET /runninghub-app/flova/status` | Flova 登录状态 + 积分（只读 CLI，5 秒缓存） |
+
+素材/剧本路由全部**只读 GET/HEAD**（其它方法 405），图片按目录白名单 + 扩展名白名单校验，剧本读取带目录白名单、剧本过滤与 512KB 上限；不会放任意路径读取。
+
+## 换机恢复步骤
+
+1. 新机器装好 DSH，恢复 `~/.dsh`（用 dsh-backup 的恢复功能）。
+2. 恢复后 `~/.dsh/h3-kit/H3工作流手册.md` 与 `~/.dsh/h3-kit/scripts/` 已随备份还原（运行脚本可直接 `node ~/.dsh/h3-kit/scripts/run-xianxia-v7.js`）。
+3. 安装/启用本插件（`@leiyi-works/dsh-aivideo`）后，插件加载会以插件自带版本覆盖同步一次 `~/.dsh/h3-kit/`，保证与插件版本一致。
+4. 配置 `~/.dsh/runninghub-app.json`（`apiKey`、`workflowId`、可选 `baseUrl`、`pollIntervalMs`；素材目录可选 `characterDir` / `dirs` / `scriptDirs` / `imageDirs`）后即可在面板「生成」页与三个素材页使用。
+
+## 文件结构
+
+```
+index.js               # Host：RunningHub API 工具/路由 + manual/scripts/video 只读路由
+                       #       + 人物/场景/剧本素材只读路由 + 说明&脚本同步
+client.js              # Client：AI视频 面板（生成/视频/人物/场景/剧本/使用说明/脚本/Flova 八页签）
+docs/H3工作流手册.md     # 内置使用说明（同步源）
+scripts/*.js           # 内置运行脚本（同步源）
+scripts/README.md      # 脚本说明（同步源）
+skill/flova-SKILL.md   # 内置 flova 技能正文
+cordis.patch.yml       # 插入 runninghub-app 行
+locale/*.json          # 插件标题/描述（AI视频）
+icon.svg               # 图标
+```
+
+## 配置
+
+`~/.dsh/runninghub-app.json`（可由 `RUNNINGHUB_APP_CONFIG` 覆盖路径）：`apiKey`、`baseUrl`、`workflowId`、`pollIntervalMs` 等；素材面板目录键见上文表格。原 H3 生成功能与同步机制互不影响。
+
+## 面板设置入口
+
+本插件**没有可在界面修改的设置**（`apiKey`/`baseUrl`/`workflowId`/`pollIntervalMs` 与素材目录只能编辑 `~/.dsh/runninghub-app.json`，Host 也无配置写路由），因此面板头部**不放**齿轮按钮。原 DSH 设置页里的「H3」入口已按用户要求**删除**（不再注册 settings.section），不影响 AI视频 面板八页签与生成功能。