npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

dsh-motion

v0.10.3

Published

Code-generated math & science animations for DeepSeek Harness: frames-first preview, Manim clips, formula checks.

Readme

dsh-motion

npm

Unofficial community plugin. Not affiliated with or endorsed by DeepSeek. The name is descriptive (motion = animation); if the upstream project needs it, this package will be renamed.

代码生成的数学 / 科普动画,给 DeepSeek Harness 用的插件。 画面由代码逐帧生成,不经过任何文生视频(text-to-video)模型。

提供六个工具:

| 工具 | 作用 | |---|---| | motion_frames | 极简模式(默认):直接从场景出帧,不生成视频、不用 HF;几秒拿到 storyboard PNG 与 layout 问题;输出落 <project>/out/frames | | motion_doctor | 环境预检(一次调用):运行时 + 真实可用字体清单 + 公式转换 + API/函数/rate;按指纹缓存 12 h(不再按 Node 版本分叉) | | motion_setup | 环境自愈:建 venv、装 manimgx/sympy(tts=true 加 edge-tts);在宿主进程执行,不受模型 bash 沙箱限制 | | motion_render | 渲染 Manim / manimgx 场景;必须有 motion.project.json,APPROVALS.json 是前置账本(已通过就直接渲,未通过才走一次平台审批);输出落 <project>/out/render | | motion_probe | 成片自检:逐帧扫描全片(默认下采样到 480p,判据不变、不抽样)报告全黑/过曝,拼 contact sheet,并给出 fps/帧数/VFR/CFR | | formula_check | 用 SymPy 判断两个表达式是否恒等 |

外加三个技能:animation-router(题材路由 + API/命令速查)、design-spec(写 DESIGN.md)、qa-rubric(交付自检)。 它们由插件通过 ctx.skills 注册,安装后自动出现在会话技能目录,不需要再复制到 ~/.dsh/skills。

模块边界、进程拓扑、数据流与不变量见 ARCHITECTURE.md;设计理由与外部调研见 docs/ai-native-motion.md。

版本与发布说明

npm 页面只渲染 README,不提供每个版本的 release note;完整记录在 GitHub Releases。下面是当前版本摘要:

| 版本 | 日期 | 主要内容 | |---|---|---| | 0.10.3 | 2026-10-29 | 性能:motion_probe 帧数改读容器头、空镜扫描改 480p 下采样(逐帧不抽样),600 s 片 112 s → 12 s;新增 scanWidth 与 --full | | 0.10.2 | 2026-10-26 | 修复:会话工作目录改走 workingDirectory.ensure / session.header.cwd,取不到就报错;报错不再暗示“把项目搬到某处” |

| 0.10.1 | 2026-10-26 | 修复:项目集按 exec.agent.session.cwd 定位,不再误用插件进程 cwd(~/.dsh/profiles/<p>);metrics 也走同一坐标系 | | 0.10.0 | 2026-10-26 | 需求卡点固定七题(含时长/帧率/受众/风格/旁白);项目集收敛到会话工作区的 dsh-motion-projects/,解析不越界/不嵌套/无 legacy;账本通过后渲染不再逐次弹窗 | | 0.9.1 | 2026-10-26 | 文档:README 增加版本摘要与 Releases 链接(docs-only) | | 0.9.0 | 2026-10-26 | 项目根 manifest、审批门与审计、时间轴自检、TTS 缓存、VFR/CFR、运行账本、showcase 标准化 | | 0.6.0 | 2026-10-26 | 免费 edge-tts 旁白、词级 timing、SRT、混音 | | 0.5.0 | 2026-10-25 | requirements brief 硬门;无锁定时 motion_frames 拒绝出帧 | | 0.4.3 | 2026-10-25 | 预检合并为一次 motion_doctor,指纹缓存;TTL 边界修复 | | 0.4.2 | 2026-10-25 | render 规格生效;按帧数强制 CFR | | 0.4.1 | 2026-10-25 | 未 approved checkpoint 拒绝 render | | 0.4.0 | 2026-10-25 | 分档确认门、APPROVALS.json、pre-flight、CFR | | 0.3.0 | 2026-10-25 | 风格路由 registry/CLI;3b1b + whiteboard | | 0.2.0 | 2026-10-25 | Lemo 风格库、frames-first、showcase、probe/doctor 改进 | | 0.1.1 | 2026-10-25 | OIDC Trusted Publishing、npm badge、unofficial 标记 | | 0.1.0 | 2026-10-25 | 首个公开版本:4 个工具、3 个 skill |

0.7.0 / 0.8.0 未单独发布,改动已并入 0.9.0。

两种模式

| | 极简模式(默认) | 交付模式 | |---|---|---| | 画面来源 | motion_frames:按时间点直接出 PNG | motion_render → MP4 → HyperFrames 合成 | | 是否需要 HF | 不需要 | 需要(字幕、编码;旁白/混音也可走本地免费路线) | | 检查方式 | 看帧(读图),没有"渲染完再抽帧" | motion_probe / hyperframes check | | 典型耗时 | 2–6 秒/次 | 数秒–数十秒;HF 合成为分钟级 | | 什么时候用 | 写场景、调节奏、改版式 | 定稿后出片 |

先出帧、改到满意,再决定要不要渲染成片。motion_probe 是给已经存在的视频做体检的,不是默认步骤。

项目骨架、时间轴与账本

新项目用脚手架起,不要从空白开始:

node scripts/scaffold.mjs my-film --title "欧拉公式" --duration 30
node scripts/timeline-check.mjs dsh-motion-projects/my-film --strict
node scripts/run-report.mjs dsh-motion-projects/my-film --wall 752
  • 模板生成 motion.project.json / scene.py / timeline.json / timeline.py / narration.json / assemble.py / DESIGN.md;
  • 一个项目 = 一部片子,放在会话工作目录下的 dsh-motion-projects/<目录名>(可用 MOTION_PROJECTS_HOME 改); 工具路径用 ctx.workingDirectory.ensure() / session.header.cwd 定位(不是插件进程的 cwd,那是 profile 目录;都取不到就直接报错);
  • 项目集只有这一层:dsh-motion-projects/registry.json 是可删可重建的索引,不参与寻址;
  • motion.project.json 是唯一项目根,id 在这里,目录改名不影响身份;APPROVALS.json / out/ / audio/ / .dsh-motion/ 都相对它;
  • 解析不越界、不向上找:workspace 外的 scene.py 一律 unmanaged;子目录里的项目会被拒绝(不允许嵌套);
  • 正式 motion_render 必须有项目根;临时场景只能出帧,或用 --explore 调试;
  • 工具入参可以给项目目录名({"file": "my-film"})或场景文件的绝对路径;
  • 仓库自带的 showcase/* 不在项目集内,跑它们用 MOTION_PROJECTS_HOME=showcase;
  • 管理项目集:node scripts/projects.mjs list|show|repair|rename|registry;
  • timeline.py 的 TimedScene.cue() 在运行时对比 self.time,落后超过 0.35s 打印 [late];
  • timeline-check 检查 cue 乱序/越界、旁白晚于画面、旁白压到下一拍;
  • 每个项目写 <project>/.dsh-motion/metrics.jsonl,run-report 汇总 active / wall,避免把 compute 百分比当端到端收益;
  • motion_probe 报 vfr:true 时,raw 只是中间片,交付前用 assemble.py 或 motion_render 归一成 CFR。

旁白 narrate 默认按文本/音色/语速缓存并并发 3 句;mix --report-gaps 输出每个旁白间隙的 dB。

风格库

默认 瑞士动态排版(swiss-motion);另外四套按题材选。四套改编自 Lemo-Opuscar,3b1b 来自 Manim 社区,均非自创。

| 风格 | 适合 | 规范 | |---|---|---| | swiss-motion(默认) | 公式、定义、数据结论 | STYLE · tokens | | dataviz | 趋势、比较、分布、科学数据 | STYLE · tokens | | blueprint | 几何证明、结构、尺寸关系 | STYLE · tokens | | whiteboard | 科学解释、课程、机制说明 | STYLE · tokens | | 3b1b | 线代、微积分、概率、神经网络 | STYLE · tokens |

参考与示例统一用 HyperFrames 的库:examples、catalog、frame.md。本仓库不再内置样片/分集;showcase/ 只放可复现的演示。

路由是显式的:node scripts/route-style.mjs "<题材>"(点名优先 → registry 打分 → 默认 swiss-motion;分数并列/为 0 时要求确认)。规则在 styles/registry.json。

迭代预算(首帧 ≤60s、输出 ≤30k、上下文 ≤100k、读图 ≤10)见 docs/performance-budget.md。

开工前先过需求卡点:npm run plan -- "竖屏抖音,讲导数,要旁白",会推断画幅、交付、风格的候选项,再交给 ask_user_question;能推断的不问。

项目 DESIGN.md 头部写 style: <slug> + style_version: 1.0.0。风格来源、HF 集成、抽帧能力与 Lemo 调研见 docs/ai-native-motion.md。

演示

五个类别各一支 10 秒内短片,记录出帧/渲染耗时:

每个 showcase 目录都是标准项目(带 motion.project.json);成片在 final/,生成物在 out/。 汇总见 showcase/README.md。

开工前确认

requirements / start 的确认必须带 --confirmation <ask_user_question id>;brief 哈希由脚本自动生成。

顺序是硬性的:

  1. 需求卡点(画幅 / 交付 / 风格 / 受众 / 旁白)
  2. 脚本 / 文案(逐句旁白、上屏文字、公式)
  3. 分镜(镜头、秒数、画面、运动、字幕)
  4. DESIGN.md + 3 张风格帧(只出帧,不渲染)
  5. 交付清单(尺寸 / fps / 时长 / 文件 / 音频 / 字幕)
  6. 用户明确说“可以开始 / 开始做 / 按这个执行”

motion_render 只在账本没通过时才走 Harness 的 ctx.approval.request: 账本全 approved 说明需求/脚本/分镜/开工都确认过了,渲染不再重复问,只往审计里记一条 ledger-approved。账本缺失或未通过时用户在界面里确认一次,拒绝则渲染失败。 想恢复“每次渲染都问”,在插件配置里加 confirmEveryRender: true。 APPROVALS.json 始终是前置条件(CLI/无平台路径也会校验)。 拒绝、--explore 绕过、平台审批与跳过审批都会写进 <project>/.dsh-motion/approvals.jsonl。

motion_frames 也会拦:项目有账本、但需求没落全「时长 / 画幅 / 帧率 / 交付 / 风格 / 受众 / 旁白」时,直接拒绝出帧。 第一步永远是固定七题一次问完,然后落账:

npm run approvals -- init <project> --mode standard
npm run approvals -- set <project> requirements approved \
  --duration 30s --aspect 1920x1080 --fps 30fps --delivery narrated \
  --style 3b1b --audience high --narration zh-neutral \
  --confirmation q_... --note "用户确认"

没听到第 6 步的明确指令,不写完整场景、不出全片。清单模板见 skills/animation-router/references/confirmation.md。

按体量分档:light(≤15 s 无旁白:脚本+分镜合并)、standard(15–60 s 或旁白)、full(>60 s 或多段,加 animatic)。确认状态落在项目里的 APPROVALS.json:

npm run approvals -- init <project> --mode light
npm run approvals -- set <project> start approved --confirmation q_... --note "用户说可以开始"
npm run approvals -- check <project>

安装

# npm
npm install -g dsh-motion

# 或在 DSH 插件管理器里安装 dsh-motion

安装后重启 DeepSeek Harness,然后先跑一次预检:

motion_doctor

它把运行时、真实可用字体、公式转换和 API/函数/rate 一次带回(按机器指纹缓存 12 小时,重复调用几乎不耗时)。 ready.math=false 时调用 motion_setup,不要自己用 bash 建 venv——venv 在 workspace 外,会被沙箱拒绝。

依赖

| 依赖 | 是否必需 | 说明 | |---|---|---| | Node.js ≥ 22 | 必需 | engines 声明 | | Python 3 + venv | 数学功能需要 | manimgx、sympy;极简出帧只需这一项 | | FFmpeg + ffprobe | 成片/探针需要 | 后期与抽帧;出帧不需要;不随包分发 | | Chrome | 用了 HF 才需要 | HyperFrames 优先复用系统 Chrome | | HyperFrames | 交付模式需要 | npx hyperframes,不随包分发 |

准备 Python 环境

# 推荐:插件内 motion_setup,或命令行(幂等,缺什么补什么)
npm run setup
npm run setup -- --tts     # 旁白依赖 edge-tts / numpy
npm run setup -- --force   # 删掉旧 venv 重建

# 手动兜底
python3 -m venv ~/.dsh/data/dsh-motion/venv
~/.dsh/data/dsh-motion/venv/bin/pip install manimgx sympy

Windows 把 bin/ 换成 Scripts\,可执行文件加 .exe。

配置

插件配置(或在 profile 的 cordis.patch.yml 里传入):

- insert:
    - id: motion
      name: dsh-motion
      config:
        motionHome: ~/.dsh/data/dsh-motion
        workspace: <会话 cwd>/dsh-motion-projects      # 默认值;也可用 MOTION_PROJECTS_HOME
        venv: ~/.dsh/data/dsh-motion/venv
        python: /opt/homebrew/bin/python3.13   # 可选;默认找 python3.13/3.12/3.11/3
        packages: [manimgx, sympy, manimgx-fonts, manimgx-fonts-cjk]  # 可选;motion_setup 安装清单
        tts: false                             # 可选;true 时追加 edge-tts / numpy
        ffmpeg: /opt/homebrew/bin/ffmpeg

解析顺序:插件配置 → 环境变量(MOTION_HOME / MOTION_PROJECTS_HOME / MOTION_VENV / MOTION_FFMPEG)→ 默认目录 → 系统 PATH。

快速开始

0. 先建项目

node scripts/scaffold.mjs demo --title "演示" --duration 10
cd dsh-motion-projects/demo

项目根由 motion.project.json 标识;正式渲染必须能找到它。临时场景可以只出帧,但不要用于交付。

1. 写一个 Manim 场景

# scene.py
import manimgx as m
from manimgx import *

class Demo(Scene):
    def construct(self):
        ax = Axes(x_range=[-2, 2], y_range=[-1, 4])
        self.play(Create(ax))
        self.wait(1)

2. 先出帧(默认,不需要 HF)

// motion_frames
{ "file": "demo", "times": ["1.2", "4.5", "end"] }

返回 storyboard PNG 路径与 layout 问题清单(实测 3–4 帧约 3–5 秒)。看图改场景,不满意就再来一轮;这一步不生成 mp4,也不需要 HyperFrames。

3. 需要成片时再渲染

// motion_render
{ "file": "demo", "scene": "Demo", "width": 1920, "height": 1080, "fps": 60 }

4. 公式先验

// formula_check
{ "left": "diff(0.5*exp(x), x)", "right": "0.5*exp(x)" }

旁白(免费路线)

不依赖付费 API、不需要账号。默认用 edge-tts(微软 Edge 朗读接口的非官方封装:免费、联网、带词级时间戳);离线兜底用 macOS say。

一次性准备:

python3 -m venv .venv-tts
.venv-tts/bin/pip install edge-tts numpy   # Windows: .venv-tts\Scripts\pip

narration.json 只描述文本和节拍,语音参数可以写在 edge 里,也可以命令行覆盖:

{
  "duration": 30,
  "edge": { "voice": "zh-CN-XiaoxiaoNeural", "rate": "+10%" },
  "lines": [
    { "id": 1, "start": 0.65, "text": "先看这个函数……" }
  ]
}

生成逐句音频、词级 timing.json 和 captions.srt:

npm run narrate -- dsh-motion-projects/foo --voice zh-CN-XiaoxiaoNeural --rate +10%

混音(可选音乐、自动 duck、−14 LUFS / −1 dBTP),需要时直接压进现有视频:

npm run mix -- dsh-motion-projects/foo --music assets/bed.wav \
  --mux out/foo.mp4 --mux-out out/foo-narrated.mp4

| 产物 | 内容 | |---|---| | audio/edge/l1.mp3 | 逐句人声;按“文本 + 音色 + 参数”缓存 | | audio/edge/timing.json | 每句起止 + 词级时间 | | audio/edge/captions.srt | 与配音对齐的字幕 | | audio/master.wav | 48 kHz / 24-bit 母带 | | audio/mix.json | 响度、真峰值、duck 参数 |

没有网络时:

npm run narrate -- dsh-motion-projects/foo --provider say --voice Tingting --rate 230

say 不提供词级时间,字幕按 token 权重估算,并在 timing.json 标 estimated。Python 解释器可用 --python 或 MOTION_TTS_PYTHON 指定。

edge-tts 免费但非官方接口:需要联网,无 SLA;商业发行建议换 Apache 2.0 的 Fun-CosyVoice3 或真人配音。

和 HyperFrames 的关系

本插件不是渲染框架,默认只产出画面素材;成片合成、字幕、编码交给 HyperFrames。旁白与混音可以用上面的免费路线,不强制走 HF:

npx hyperframes init my-video
npx hyperframes add data-chart          # 约 450 个现成 block / component
npx hyperframes check                   # 运行时、版式、对比度
npx hyperframes render -o out.mp4
  • 风格契约:HF 用 frame.md(DESIGN.md 的超集)做 brand truth;本仓库的 DESIGN.md / styles/<name>/ 是同一套思路的轻量版,两边可以互读。
  • 参考库:不要把参考片塞进本仓库;直接看 HF 的 examples、catalog 和 frame.md templates。
  • 分工:manimgx 负责公式/坐标/几何这类确定性画面;HF 负责排版、图文、字幕与交付;免费旁白路线负责 TTS、时间轴与混音。
  • HF 不必先出片再截图:npx hyperframes snapshot <project> --at 2.9,10.4 直接抓指定时刻的 PNG;--frames 10 --review 出 contact sheet;只有要完整序列时才 render --format png-sequence。

字幕建议“一份 transcript 出两个产物”:烧录进画面 + 独立 .srt。

故障排除

| 现象 | 原因 | 处理 | |---|---|---| | 找不到 Python 虚拟环境 | 未建 venv | 调用 motion_setup(或 npm run setup),不要手动在 workspace 外建 | | 找不到渲染器: …/manimgx | venv 里没装 | pip install manimgx | | motion_frames 报 layout 问题 | 压字 / 出画 / 字号过小 | 按返回的 [n] 逐条改场景;退出码 1 是“有问题”,不是崩溃 | | 渲染断字 / 字体回退 | 字体未声明 @font-face | 把 .woff2 放工程 assets/fonts/ 并声明 | | ffprobe 缺失 | 只装了 ffmpeg | 装完整 FFmpeg,插件会退回 ffmpeg -i 解析 | | 抽帧全黑 | 片头/片尾空镜 | 用 tpad=stop_mode=clone 补帧,或剪掉 |

本地开发(维护者)

桌面 App 独占 desktop profile,CLI 不能管理它(dsh plugin --profile desktop 会直接报错)。 把插件切到当前 checkout 的完整步骤、验证命令和禁忌清单记在 MAINTAINING.md。

一句话版本:插件管理器里卸载 dsh-motion → 安装本地目录 /path/to/dsh-motion → ⌘⇧R 重启; 之后 motion_doctor 第一行的「插件来源」会直接说明当前跑的是本地 checkout 还是 npm 安装。

日常改代码不需要重装:link 安装一次后,改 lib/ops.js / lib/doctor.js 会在下一次工具调用时按 mtime 热加载;只有改工具名/参数 schema 才需要 ⌘⇧R。风格、tokens.json、场景文件本来就是运行时读取,不用重启。详见 docs/dev-loop.md,也可以完全绕开 Harness:

node scripts/dev.mjs frames showcase/swiss-euler/scene.py 1,3,end   # → showcase/swiss-euler/out/frames/scene.png
node scripts/dev.mjs render --explore showcase/swiss-euler/scene.py --fps 30   # 演示项目无账本,仅调试

发版(维护者)

首次发布会把包名与 2FA 绑好;之后走 GitHub Actions 的 Trusted Publishing(OIDC),不需要 token、不需要 OTP,自动附带 provenance 签名。

一次性绑定

npm 包设置 → Settings → Trusted Publisher → GitHub Actions:

| 字段 | 值 | |---|---| | Organization or user | cogito0823 | | Repository | dsh-motion | | Workflow filename | release.yml | | Environment | 留空 |

Allowed actions:勾 npm publish 即可(npm dist-tag 用不到)。

发一版

npm version patch          # 0.1.0 -> 0.1.1
git push --follow-tags     # 触发 .github/workflows/release.yml

工作流会:校验 tag 与 package.json 版本一致 → check + smoke → npm publish --provenance --access public。

两个必须知道的坑

  1. npm CLI 必须 ≥ 11.5.1。Node 22 自带的 npm 10 不支持 OIDC,会把占位 token 发出去,registry 返回误导性的 404 not in this registry。工作流里已加 npm install -g npm@latest。
  2. 发布后不是立刻可见。CLI 会打印 Your package is being processed and may take a few minutes to become available,通常 1–2 分钟后 npm view 才查得到。这不是失败。

验证

npm view dsh-motion version
npm view dsh-motion@<version> dist.attestations   # 应含 provenance / SLSA v1

npm 包页面会出现 “Built and signed on GitHub Actions”。

许可

MIT(见 LICENSE)。第三方依赖与调用关系见 NOTICE.md。