dsh-remotion-launcher

方便一键启动mcp工程Remotion Studio用；在 DeepSeek Harness（DSH）里一键构建 / 启动 / 停止 Remotion Studio 动画工程，该工程是mcp模式，启动后需要你自己去配置mcp，配置好后你就可以让dsh去使用生成各种自己想要的网页动画视频。

插件和工程是两个独立包：本仓库只是启动器，工程是另一个包 remotion-studio。工程包安装可选择github或npm官网下载。

它做什么

装上后在 DSH 右下角出现一个可拖动的悬浮按钮（🎬），点开是一个面板：

区域	说明
工程	显示当前工程目录，可安装 / 更换（详见下一节）
启动服务	先构建前端，构建成功再 `npx tsx server/index.ts`；构建失败就不启动（避免跑着旧前端）。构建命令跟工程走：有 `build` 脚本就 `npm run build`（`prebuild` 的代码生成才会执行），没有才 `npx vite build`。可在设置里关掉自动构建
构建前端	单独的构建入口收进了「设置」，一般用不到（启动会自动构建）
端口	可改，避免和别的软件抢 4380；写进本机配置，重启不丢
日志	独立一个 tab，占满面板高度；可按「全部 / 服务 / 构建 / 安装」过滤，切进来就停在最新一行并打开跟随，往上翻才暂停。启动 / 构建 / 安装 / 更新工程时会自动切过来并选好对应来源
MCP 配置	一键复制 `mcpServers` JSON（stdio / HTTP 两种接法），粘到连接器即可
变更	启动器和工程两份变更记录都能看；来源切换与版本 chip 固定在顶部，只有条目滚动
版本与更新	启动器自身的新版检查与一键升级（详见「更新」一节）

面板结构

标题栏（可拖）          状态灯 · 名称 · 版本 · 更新 ⟳ · 关闭 ×
状态区（不滚动）        ● 运行中  :4380   地址 [复制]     ← 固定
主操作（不滚动）        [启动服务 / 停止服务] [打开浏览器]  ← 固定
下载源（不滚动）        源 [npmmirror ▾]                     ← 固定，所有联网操作都走它
tab                   概览 | 日志 N | 设置 | 变更
内容（各自滚动）        概览=工程+MCP+更新 · 日志=工具栏+全高日志 · 设置=工程/端口/更新 · 变更=按版本列条目

主操作永远在最上面，不会被日志或折叠区顶下去；按 Esc 收起面板。

位置、端口、工程目录、是否自动构建都存 Host 侧（~/.dsh/remotion-launcher.json），换浏览器、换端口不会丢。

变更说明从哪来

面板里的「变更」有两份，取法不一样：

看哪份	当前版本	新版本（本地还没有）
启动器	包内 `CHANGELOG.md`	面板顶部那个 npm 源拉 tgz 取文件（默认 npmmirror）；1.8s 后才用 jsdelivr / unpkg 兜底
工程	工程根目录 `CHANGELOG.md`	同上（包名 `remotion-studio-mcp`）

npm registry 本身不提供「读单个文件」的接口（registry.npmjs.org 直接 404、npmmirror 的 /files/ 是 403），所以只能要么拉包自己解、要么走 npm 包的 CDN。

默认走国内镜像，且源优先：先向 <registry>/<pkg>/<version> 要 dist.tarball → 下载 tgz → 自己用 zlib + tar 头解析出 CHANGELOG.md（不依赖系统 tar，Windows 上也能用，也不起 npm 进程）。1.8 秒还没回来，才并发问 jsdelivr / unpkg 兜底 —— 国内实测镜像路 1 秒内返回，而 jsdelivr 经常直接超时，等它纯属浪费。取到过就落盘缓存，之后离线也能看。面板右上角会标出这次是哪来的：本地文件 / 本地缓存 / npm CDN · jsdelivr / npm 包；底部那行还会用一句话讲清具体位置，例如

v1.1.2 是本机安装的版本，条目直接读自工程目录下的 CHANGELOG.md。
v1.1.3 本机没有，从 npm 包的 CDN（jsdelivr）取到。

不会拿别的版本顶替：目标版本在取到的那份文件里没有对应段落时，界面会直说「这份记录里没有 vX」并列出它实际记录了哪些版本，而不是把第一条当成这一版展示。

底注下面那行小字是这次真正的出处（绝对路径或 tarball URL），可以直接拿去核对 —— 工程目录和 node_modules 里的安装目录经常不是同一个，光看「本地」两个字分不清。

缓存放在哪

从 npm 取到的变更记录会落盘，下次离线也能看：

位置	说明
`$DSH_HOME`（默认 `~/.dsh`，Windows 上是 `%USERPROFILE%\.dsh`）	缓存目录，和 `remotion-launcher.json` 同级
`changelog-<包名>-<版本>.md`	一个版本一个文件，例如 `changelog-remotion-studio-mcp-1.1.3.md`

文件名带包名是有意的：早先只按 changelog-project-<版本>.md 命名，换个工程撞上同版本号就会读错。缓存只增不减（一个版本一个文件，几 KB 到十几 KB），想清就直接删该目录下的 changelog-*.md；旧命名（changelog-project-*.md）的文件已不再被读取，可以一并删掉。

拖动与窗口缩放

悬浮按钮和面板记的是**「离最近两条边多远」**，不是屏幕绝对坐标：

拖动后改变窗口大小 → 按边距重新计算，图标仍贴着原来那条边，不会被甩到别处
窗口缩小到放不下时只是这一帧被夹在视口内，存档值不动；放大回去仍回到你放的位置
顶部会避开 Windows 桌面版的标题栏（那里是窗口拖拽区，停上去会变成拖窗口）

接上 MCP

服务跑起来只是有了编辑器；要 agent 能调工具，还得把工程挂成 MCP 连接器。

面板里的 MCP 配置 卡片已经把路径和端口算好了，点「复制 JSON」，粘到连接器管理页的自定义连接器里，再点「信任」就行 —— 不用自己拼工程路径。

两种接法按需切换（选择记在本机）：

接法	配置内容	什么时候用
`stdio`	`command: node` + 工程内的 `tsx` + `server/mcp-proxy.ts`，`SERVER_URL` 指向本机端口	常驻子进程，服务没开也能用（首次调用会自动拉起）；改工具代码要重连
`HTTP`	`{ "type": "http", "url": "http://127.0.0.1:<端口>/mcp" }`	连已经在跑的服务，不起新进程；服务一停就断

卡片左侧那个小圆点是就绪状态：绿色可直接用，黄点表示还差条件（没装工程 / 依赖没装齐 / 服务没跑），下方一行会说明差什么。想核对内容就点标题展开 JSON 预览（路径长会折行，不横向切）。

复制走 navigator.clipboard，被浏览器拦下时自动退回 execCommand；两条都不行就直接把 JSON 展开给你，手动全选复制。

安装

DSH 版本要求：>=0.2.1-rc.2。

第一步：装插件（三选一）

npm（国内推荐走 npmmirror 镜像源）

dsh plugin --profile web add dsh-remotion-launcher

GitHub

dsh plugin --profile web add github:laojingwei/dsh-remotion-launcher

本地开发

dsh plugin --profile web add "link:<插件目录>"

也可以走DSH自带的功能：设置 → 插件 → 添加插件，填包名或地址。

装完重启 DSH（客户端清单在启动时构建）。

第二步：拿到工程

插件本身不含工程。重启后面板第一行会显示「工程 · 未安装」，点右边「安装」：

做法	什么时候用
使用此目录	你已经 clone / 解压了工程，直接指过去
下载并安装	本机没有工程，从 npm 拉一份

「下载并安装」的流程：选目录（弹系统文件夹对话框）→ 由 host 用面板顶部那个下载源依次跑

npm pack remotion-studio-mcp@latest --registry=<下载源> --pack-destination <临时目录>
tar -xzf <tgz> -C <临时目录>/x --strip-components=1   # 先解到临时目录
# 再把临时目录按规则合并进目标目录（见下「合并规则」），不是整目录倒进去
npm install --registry=<下载源>          # 在目标目录里，最慢的一步

合并规则（安装与更新一致）

工程根目录里混着「代码」和「你的东西」，整目录替换会连数据一起抹掉，所以按三类处理：

类别	路径	行为
本机状态	`data` `public` `out` `dist` `node_modules` `.git` `.github` `.remotion-bundle` `.browser` `workspace.json` `memory` `.workbuddy` `.log` `.tmp`	完全不碰（不读不拷不删），即使包里带了同名路径也一样
按名字覆盖	`plugins/` `docs/`	只处理包里也有的同名项：同名 → 先删再拷（清掉上一版残留文件）；包里有、目标没有 → 新增；包里没有 → 一律留着
只补缺失	`.other_modules/`	已存在就跳过（里面有自己下载的第三方工具，README 里还有一张你会改的登记表），只补包里新增的

实际含义：plugins/ 下你自己装的插件（dream-3d、glm-tts…）永远不会被动，只有与内置示例插件（_example-*）同名的才会被新版覆盖 —— 工程自带的插件都带 _example- 前缀，正常不会撞名。日志里会写明：覆盖 N 项代码文件；内置插件更新 X 个；新增内置插件 Y 个；保留你自己的 Z 项。

也可以自己 clone：

git clone https://github.com/laojingwei/remotion-studio-mcp.git <工程目录>
cd <工程目录>
npm install

然后在面板里 更换 → 选择该目录 → 使用此目录。

工作方式

DSH 浏览器页面
   └─ client.js（shell.overlay 悬浮按钮 + 面板）
        │  fetch 同源 /remotion-plugin/*
        ▼
   index.js（host 半部，跑在 DSH 的 Node 进程里）
        ├─ spawn: npm run build（无 build 脚本时 npx vite build）→ <工程>/dist/web
        ├─ spawn: npx tsx server/index.ts → http://localhost:4380
        └─ spawn: npm pack / tar / npm install（只在下载工程时）

host 半部只做进程管理和状态
服务地址可以在右侧栏「浏览器」标签里打开，和 agent 共用同一个界面
DSH 退出时插件会杀掉自己拉起的子进程，避免端口被孤儿进程占用

工程目录（安装 / 更换）

面板第一行永远是「工程」，点右边按钮展开卡片：

字段	说明
目录	点「选择」弹系统文件夹对话框，也可以直接粘路径
使用此目录	指向本机已有的工程，不下载任何东西
下载并安装	从 npm 下载一份新工程到这个目录

下载源不在这里了 —— 它在面板顶部常驻一行，见下面「下载源」一节。

下载源

面板顶部常驻一行 源 [npmmirror ▾]，所有联网操作都只认这一个值：

用到它的地方	说明
启动时 / 手动查更新	查启动器和工程的最新版本
一键更新启动器	装新版本
下载 / 更新工程	`npm pack` + `npm install`
变更说明	本地没有的版本，从该源拉 tgz 取 `CHANGELOG.md`

预设三个：国内镜像 npmmirror（默认）、npm 官方、自定义…。选了自定义会在下面展开一行地址输入框，回车或点「应用」生效。改完直接落盘（remotion-launcher.json），并立刻用新源重查一次版本。

变更说明对源是「优先」而不是「唯一」：源先发请求，1.8 秒还没回来才并发问 jsdelivr / unpkg 兜底（国内源通常 1 秒内就回来了，所以实际基本都走源）。

更新

启动时静默检查

每次 DSH 启动、插件加载 3 秒后，host 半部会去 registry 查一次最新版本（用面板里存的下载源，默认 npmmirror）。不弹窗、不打断，只把结果放进状态：

有新版本 → 悬浮按钮右上角出现小圆点，点开面板顶部是一条黄色横幅
没有新版 / 查不到（离线、镜像没同步）→ 什么都不显示，只在「版本与更新」里留一行检查时间

面板里那个 ⟳ 按钮可以随时手动重查。

能不能一键更新，看你是怎么装的

host 半部用 pluginManager.listBundles() 的 source 判断来源（不是猜目录，GitHub 装的包同样落在 node_modules 里）：

安装方式	来源长什么样	面板行为
npm	`dsh-remotion-launcher@^1.1.0`	显示「一键更新启动器」，点一下就地升级
GitHub / Git	`github:you/repo`、`git+https://…`	只提示，给出要粘的命令
本地链接	`link:D:\…\dsh-remotion-launcher`	同上（改源码即可，不必更新）
本地目录 / tarball	`file:…`、`….tgz`	同上

非 npm 安装时，面板里写清楚两步：

# ① 设置 → 插件 → 找到 dsh-remotion-launcher，卸载
# ② 按原来的方式装回来：
dsh plugin --profile web remove dsh-remotion-launcher
dsh plugin --profile web add github:laojingwei/dsh-remotion-launcher

一键更新：能热换就热换，换不掉才让你重启

npm 安装的插件走 DSH 自己的插件管理接口，一次点击完成「卸旧 → 装新」：

removeBundle(旧版)  →  installBundle(新版)  →  新实例接管？
                                              ├─ 是：已完成，没重启
                                              └─ 否：已装好，重启 DSH 生效

判定不靠 DSH 的口头承诺：ChangeResult.application 只说明文件写成了，HMR 到底有没有把新代码拉起来，要靠「新实例握手」——装机前在 ~/.dsh/remotion-launcher-update.json 里写 installing，真正跑起来的那份代码会在 apply() 时发现「标记里的目标版本 = 自己」，于是回写 bootedAt。旧实例等这条证据，等到就是热更新成功，等不到就是需要重启
两种情况面板都如实显示：「已更新到 x.y.z（新实例已接管，没重启 DSH）」或「已装好 x.y.z，重启 DSH 后生效，当前运行 a.b.c」，需要重启时还会带上 DSH 给的原因（host-module / package-moved / unmanaged-plugin / module-comparison）
装完再点更新不会再装一遍，直接告诉你「已经装好，重启生效」
卸载后装不上会自动回滚到开装前盘上那版，不会把已经装好的新版降回去，也不会让你面对一个消失的插件
进度写在同一个标记文件里：DSH 中途退出，下次启动会认出「上次没走完」；确认生效后自动清档
宿主没开 HMR 时不做卸载，直接装新版，同样提示重启才生效

为什么必须先卸再装：HMR 开着时对一个已安装的包直接 installBundle，DSH 会以 already-installed 拒绝——覆盖一个正在跑的包会把旧实例留在内存里。

环境变量 DSH_REMOTION_BOOT_WAIT_MS 可调等待新实例接管的毫秒数（默认 3000），测试里设 0 跳过等待。

配置

工程目录的优先级：面板里选的（存 settings）→ 自动探测 → 环境变量。

自动探测顺序：插件目录的上一级 → 上一级里的 remotion-studio/、app/ → 再上一层。

变量	默认	说明
`REMOTION_STUDIO_ROOT`	自动探测	工程根；面板里选过之后以面板为准
`REMOTION_PROJECT_PACKAGE`	`remotion-studio-mcp`	从 npm 下载的工程包名
`REMOTION_PORT`	`4380`	服务端口（面板里也能改）
`REMOTION_AUTO_BUILD`	开	设 `0` 则「启动服务」不再先构建（面板里的开关优先级更高）
`DSH_REGISTRY`	`https://registry.npmmirror.com`	下载源；同时用于查更新，面板里改过之后以面板为准

启动时会检查工程根下有没有 package.json 和 server/；缺了就在日志里说明，并把面板切成「安装工程」形态，而不是让你点一个必然失败的启动按钮。

已知行为

点「启动服务」会先构建：构建成功才拉起服务；构建失败不启动，并说明原因（原因见「日志」）
端口已被占用：启动前先探 /api/health，通就标记「已在运行（非本插件启动）」，不会重复拉起，也无法从这里停止；端口被别的程序占着时不会白跑一次构建，直接让你换端口
构建串行：构建进行中再点启动，会复用那次构建而不是并列起第二个 vite
服务运行中不能构建 / 换工程 / 改端口
停止卡住：「停止中」超过 6 秒会把按钮变成「强制重置」，只清插件状态不动进程

发布（给维护者）

npm version patch          # 或 minor / major
npm publish                # 包名 dsh-remotion-launcher（若已占用请改 name 或加 scope）
git push --follow-tags

发布前建议在 package.json 里补上 repository / homepage / bugs 字段，npm 页面会据此显示源码入口。

开发自检

npm run smoke           # 两个半区的导出契约 + __ModuleLoader__ 格式 + 白名单 require
npm run host-sim        # 用假 Context 跑 apply()，验证路由、状态、落盘、锚点、变更日志解析
npm run update-sim      # 假 pluginManager + 本地假 registry：热更新 / 拒绝 / 回滚
npm run ui-sim          # 真浏览器（本机 Edge headless + CDP）加载真的 client.js
npm run check:encoding  # Windows：确认 PowerShell 能原样传回中文路径
npm test                # 以上全部

ui-sim 会起一个假的 host 接口，用真浏览器渲染 client.js，然后脚本化「拖动 → 改视口 → 再改回来」，断言图标始终在视口内、边距不变、能回到原位；顺带截三档视口的面板图。找不到 Edge / Chrome 时打印「跳过」并以 0 退出，不会卡住 npm test。

都不需要启动 DSH。host-sim / update-sim / ui-sim 会把配置写在系统临时目录，不碰真实配置。

dsh-remotion-launcher

インストール

README