前言¶

在 DeepSeek Harness（DSH）里维护插件仓库时，README 首屏和插件市场条目往往只能放一张静态截图。一张图很难交代「从哪进入、点哪个页签、最后得到什么」；录屏则要人工操作、剪首尾、压体积，还要让首尾能无缝循环。若素材本来就是仓库里的 PNG 截图，排版、淡入淡出、时间轴和编码其实可以收成一条自动化管线。

下面介绍社区插件 dsh-readme-reel（维护者 dingchenhui0618-arch）。它把 docs/shots/ 里的截图排成约 6 秒无声循环短片，输出透明背景 webm、通用 gif 和 封面帧，可直接放进 README 或市场条目。插件挂在 DSH 的 webServer 上，对话视图里提供「首屏短片」面板；也可单独用命令行 bin/reel.mjs 跑同一套管线。仓库采用 MIT 许可证，当前版本 0.1.0（见 package.json），尚未发布到 npm。

这是什么¶

dsh-readme-reel 的定位是：以截图作为唯一信息源，自动完成分镜、交叉淡入、进度指示与时间轴计算，编码交给本机 ffmpeg。它不叠字、不配音、不依赖字体——短片里的信息只能来自截图本身。

社区目录 SkillHub 条目 将其归类为「趣味换装」；工程侧更准确的说法是 README / 市场首屏的 hero reel 生成工具。

核心功能¶

三件产物与清单¶

生成完成后，默认写入项目下的 docs/reel/（可通过参数改输出目录）：

面板里可直接预览 webm / gif / 封面，并提供「复制 Markdown」，便于粘贴 cover.png 与 reel.gif 的引用。

时间轴与循环¶

「6 秒循环」来自可校验的约束，而不是文案凑数：

• 每幕停留为整数毫秒，Σ停留 + 转场数 × 转场时长 与 durationMs 一致（默认 6000）。
• loop: true 时，最后一幕经转场回到第一幕，使 t=0 与 t=duration 为同一帧，便于 <video loop> 与 GIF 无缝重播。
• 仓库内 test/storyboard.test.mjs、test/encode.test.mjs 对时间轴与编码结果做断言；无 ffmpeg 时编码相关用例会 skip，而非误报失败。

DSH 面板与 CLI 共用管线¶

• 面板：在目标仓库会话中扫描 docs/shots/*.png，勾选素材、用 ↑/↓ 调整播放顺序，点「生成」。
• CLI：node bin/reel.mjs 支持自动模式、分镜文件模式、临时指定素材预览；PNG 编解码与画面合成在 Node 内完成（不依赖 sharp / canvas），ffmpeg 为唯一外部依赖，通过环境变量 DSH_README_REEL_FFMPEG 或 PATH 发现。

明确不做的能力¶

• 不渲染文字；只吃 PNG，不处理视频、JPEG，也不是录屏工具。
• GIF 为 8-bit 调色板，深色渐变可能有轻微 banding；需要真 alpha 时用 webm。
• 没有时间轴拖拽编辑器，顺序与停留靠面板或 storyboard.json 维护。

安装与启用¶

装到某个 DSH profile（插件市场常见的安装方式）：

dsh plugin --profile <你的 profile> add github:dingchenhui0618-arch/dsh-readme-reel

本地开发时可从路径安装（README 示例为 Windows 路径，按本机目录替换）：

dsh plugin --profile <你的 profile> add D:\Projects\dsh-readme-reel

装好后重启 DSH，对话视图会出现「首屏短片」Tab。插件依赖 profile 中的 Web GUI（dsh-web-app 那一套）；纯 CLI 手建的空 profile 可能显示 pending (waiting for service: webServer)，属于 DSH 服务依赖语义，不代表安装失败。桌面端可在应用内安装插件，profile 由应用管理，一般无需手敲上述命令。

运行环境：Node.js >= 20；编码需要本机安装 ffmpeg。仓库里的 lib/ 为入库构建产物，安装时不编译。

典型用法¶

在 DSH 面板里生成¶

1. 打开要做短片的插件仓库会话（默认在工作目录查找 docs/shots/*.png）。
2. 切换到「首屏短片」：查看 ffmpeg 是否可用、分镜来源、画幅/时长/fps 与扫描到的截图。
3. 勾选素材、调整顺序，点「生成」；产物写入 <项目>/docs/reel/。
4. 使用「复制 Markdown」粘贴到 README。

命令行¶

自动模式：将 docs/shots/ 内 PNG 按文件名排序，平均分配到默认 6 秒：

node bin/reel.mjs --project .

分镜模式（推荐，可纳入版本库）：

node bin/reel.mjs docs/storyboard.json

临时预览指定几张图：

node bin/reel.mjs --sources docs/shots/a.png,docs/shots/b.png --duration 2000 --width 960 --height 600

仓库 README 中用三张真实截图复现整条片子：

node bin/reel.mjs docs/storyboard.json

storyboard.json 示例¶

{
  "version": 1,
  "title": "dsh-readme-reel · 首屏短片",
  "durationMs": 6000,
  "fps": 30,
  "size": { "width": 1100, "height": 626 },
  "loop": true,
  "layout": "plain",
  "transition": "fade",
  "transitionMs": 360,
  "scenes": [
    { "src": "docs/shots/shot-01-home.png", "hold": 1500 },
    { "src": "docs/shots/shot-02-conversation.png", "hold": 1500 },
    { "src": "docs/shots/shot-03-panel.png", "hold": 2600 }
  ]
}

scenes[].hold 为相对权重，实际毫秒由水位分配（distributeHolds）计算；transition 可选 fade / slide-left / cut，layout 可选 window / plain。完整参数见 node bin/reel.mjs --help。

常用默认值：--duration 6000、--fps 30、--width 960、--height 600；gif 侧 --gif-width 640、--gif-fps 20、--matte #0b0e14。退出码：0 成功，1 生成失败，2 参数错误。

适用场景与注意¶

适合谁：已有成套 UI 截图、希望 README 或 SkillHub 条目首屏用短循环展示多步操作的 DSH 插件作者；也适合在 CI 里用 --json 只输出 manifest 做产物校验。

权限与安全：插件以当前 DSH 进程的权限运行，会读写会话工作目录下的截图与 docs/reel/ 输出，并调用本机 ffmpeg。安装前请阅读 GitHub 源码 与 MIT 许可证，确认符合你的环境与合规要求。

生态说明：DSH 社区插件目录（如 SkillHub）为独立站点，与 DeepSeek / 幻方无官方从属关系；本文事实来自仓库 README 与 package.json。

结尾¶

若你已经在仓库里维护 docs/shots/ 截图，dsh-readme-reel 把「首屏短片」从手工剪辑收成一条可复现命令或面板操作：透明 webm 给现代 Markdown 渲染器，gif 与封面给仍只支持静态图的场景。经过上面的步骤，产物与 reel.json 清单可一并进库，方便核对是否被改动。

• 目录页：https://www.skillhub.cn/plugins/dingchenhui0618-arch/dsh-readme-reel
• 源码与文档：https://github.com/dingchenhui0618-arch/dsh-readme-reel