前言¶

在智能体工作流里做短视频或动图，常见两条路径：接入 Manim、MoviePy 等大框架，跟着它们的对象模型走；或者调桌面剪辑软件，难以在无头环境自动化。后者对 DSH 这类以 CLI 和插件串联任务的宿主并不友好。motion-weaver 走另一条路：自己算每一帧，再交给外部 ffmpeg 编码 MP4，或由 Pillow 输出 GIF 与静态图；不依赖完整视频框架栈，适合把「组图、脚本、数据序列」收成可交付的媒体文件。

下面介绍该插件的定位、能力、安装与典型用法；事实以仓库 README 与 DSH 侧清单为准。

这是什么¶

motion-weaver（维护者 JiamingShi-JsPhys）是面向 agent 工作流的确定性渲染工具：从静态图序列、已有视频片段、matplotlib 脚本、CSV 数字序列或声明式 JSON 场景生成画面，再输出 MP4、GIF 或单帧静图。转场、Ken Burns 位移、烧录字幕、AAC 配乐与语音旁白在安装包内一并提供。

插件在社区目录中归类为工作流；仓库当前标注版本 1.0.0（README：Actions: 4，Tests: 179）。DSH 侧通过 .dsh-plugin/plugin.json、index.js 与 cordis.patch.yml 接入；Node 入口仅为垫片，实际渲染器为 Python 的 run.py。

核心功能¶

五种输入源¶

渲染入口 run.py 按 --source 选择来源，经 Composer 合成时间轴后交给编码器：

输出与编码¶

• MP4：帧以 H×W×3 uint8 流式写入 ffmpeg stdin，H.264，可选 AAC。
• GIF / still：Pillow 处理调色板与抖动；静图可为 PNG / JPEG / WebP。

整条 MP4 管线不一次性缓冲全片，有利于长片段下的内存占用控制。

失败形态可枚举¶

每次运行给出类型化结论：PASS、FAIL 或 UNVERIFIED，进程退出码分别为 0、1、3。例如缺少 ffmpeg、脚本超时或异常、路径错误等会映射到不同结论，便于上层工作流分支，而不是只靠解析 stderr。

--source script 在独立子进程中执行，120 秒墙钟超时；挂起或崩溃会降为 UNVERIFIED，避免拖垮主渲染进程。README 明确说明：该隔离不是安全沙箱，子进程仍保留文件系统与网络访问，只应对可信代码使用；细节见仓库 SECURITY.md。

智能体侧技能¶

安装后可在支持技能调度的宿主中使用：

/motion-weaver    compose images or a matplotlib script into an MP4 or GIF

安装与启用¶

仓库提供三种安装思路；在 DSH 生态中，以插件渠道注册本仓库 Git 地址为预期路径。

方法一：插件市场 URL 注册¶

向宿主登记本仓库 Git URL，再安装其声明的插件。重复登记无害，第二次会提示已存在：

https://github.com/JiamingShi-JsPhys/motion-weaver

.claude-plugin/marketplace.json 将插件名 motion-weaver 指向 source: "./"，仓库根目录即插件根。package.json 中 dsh.bundle.patch 指向 ./cordis.patch.yml。

方法二：命令行安装（Claude Code 示例）¶

资料原文给出的 marketplace 安装示例：

claude plugin install motion-weaver --marketplace https://github.com/JiamingShi-JsPhys/motion-weaver.git

无插件渠道的宿主可直接使用仓库根目录：无构建步骤，安装 Python 依赖后探测环境：

pip install -r requirements.txt
python run.py --action probe

注意：仅复制 run.py 会导致路径解析失败；run.py 依赖同目录下的 scripts/engine.py 与 scripts/script_runner.py，三者为一组。

方法三：由智能体协助安装¶

指向本仓库请智能体完成插件安装；若无插件渠道，可改为拉取仓库并执行 pip install -r requirements.txt。

依赖与策略¶

编码依赖本机可用的 ffmpeg（解码视频、编码 MP4）。策略测试（tests/test_policy.py）要求 scripts/ 下模块除 numpy、Pillow、matplotlib 外不得擅自引入其他库，便于审计渲染核心。

权限与安全：插件与 run.py 以当前 DSH / 宿主进程权限运行；安装前请阅读源码、许可证（README 含开源与安全声明）及 SECURITY.md，再决定是否接入生产工作流。

典型用法¶

CLI：多图转 MP4¶

README 快速开始中的直接驱动示例（交叉淡化与字幕）：

# two stills -> MP4, crossfade, captions
python run.py --action render_video \
    --input a.png b.png \
    --subtitle captions.json

常用动作包括 render_video、render_gif、render_still；具体参数以 run.py --help 与仓库文档为准。

渲染链路（概念）¶

1. run.py 选择 source，对应 ImageSlides / VideoSlides / ScriptSlides / SeriesSlides / SceneSlides。
2. Composer 处理时间轴、转场与字幕；转场与相邻幻灯片重叠，总时长按 README 公式缩短而非简单拼接。
3. 编码器按 --action 分流至 ffmpeg 或 Pillow。

脚本源时，script_runner.py 在子进程将帧写入临时目录（frame_00000.png …），父进程编码后删除临时目录。

适用场景与注意¶

适合：需要在无头环境把智能体或流水线产出的图、轻量脚本动画、数据曲线、JSON 场景收成 MP4/GIF 的开发者；希望渲染栈小、可审计、退出码可编排的 DSH 工作流。

不适合或需谨慎：依赖重量级时间轴剪辑、复杂非线性编辑特性的项目；不信任的任意 Python 脚本作为 --source script 输入（无沙箱隔离）。

配乐与画面长度：有音轨时短轨会填充、长轨会裁切，并在报告中说明；实现上刻意避免对某些管道场景使用 -shortest，以免音画长度失配。

结尾¶

motion-weaver 用单一 Python 渲染核心统一五种输入，对外只把帧交给 ffmpeg 与 Pillow，并把成功、失败与「无法判定」分开报告，便于嵌进 agent 工作流。进一步了解与安装可参考社区目录与源码仓库。

• 目录页：https://www.skillhub.cn/plugins/JiamingShi-JsPhys/motion-weaver
• GitHub：https://github.com/JiamingShi-JsPhys/motion-weaver