动态图形工具 rakibulrocky14/miran-fann-dsh

Miran Fann for DeepSeek Harness

在这台 Mac 上做动态图形，从 dsh 会话里发起。插件启动 Miran 引擎，把它的工具以 mcp__miran__* 交给模型，并在 dsh 设置里加一个 Miran 分区。

dsh session ──tool call──► dsh mcp-client ──stdio──► ~/.miran/bin/miran mcp
▲ │
└────────────── frame, video, project JSON ◄───────────┘

安装

先装引擎，插件只负责连上它。

npx miran-fann setup # the engine in ~/.miran/bin/miran

如果已装 dsh，setup 会自动把插件加进 web 配置档；引擎每次自动更新，都会带上同版本的插件。想手动添加，在 dsh web 侧边栏打开 Plugins，填下面的地址，或者执行：

dsh plugin --profile web add github:rakibulrocky14/miran-fann-dsh#v0.1.6

需要 dsh 0.2.1-rc.2 或更新版本（npm i -g @deepseek-ai/dsh@next）。

安装后重启 dsh web。dsh --profile web --dump-config 能看到 miran-fann 层，就说明加载成功。

登录

Miran 的工具只对已登录的安装生效。打开 Settings → Miran：页面显示账号、引擎版本、GPU 后端，以及工具是否已连接。Sign in 走真实流程（浏览器打开 miranfann.com，引擎收到验证码）；Sign out 结束登录。插件从不伪造登录，也从不绕过登录。

设置

Settings → Miran 上的每一项都从引擎读取、也写回引擎，所以 dsh、Claude Code 和 Codex 三边一致：

| 部分 | 作用 |
| Account | 当前登录的是谁；通过引擎登录和登出 |
| Engine | 路径、版本、GPU，缺失时给出 setup 命令 |
| Workspace | 引擎读写的文件夹 |
| Tools | 工具面（default、lean、full）；由引擎自己决定 |
| dsh tools | 连接状态、重新连接 |
| Live viewer | 启动查看器、查看器主题、时间单位、预览质量 |
| Render defaults | 导出质量、文件大小上限、默认音色 |
| API keys | Google Gemini、ElevenLabs、OpenRouter、fal、Replicate |
| Generation | 图像、视频和草稿模型，单次调用与每日上限，已花费金额 |
| Voices | 默认音色、云端音色、内置音色 |
| Feedback and updates | 分享反馈、自动更新、版本、立即更新 |
| Skills | 这个插件提供给智能体的技能 |

密钥会写进 dsh 的凭据存储，也写进 Miran 自己的密钥存储，作为 secret 字段。页面只显示最后四个字符。同名的环境变量优先级高于这两处。

Built-in plugins → Miran 标签页用卡片展示同样的状态，并带 Open live viewer。

工具与技能

模型看到的引擎工具形如 mcp__miran__<tool>。默认列表就是引擎自己的 MIRAN_TOOLS_DEFAULT；Settings → Tools 提供引擎 choice、lean（约 30 个工具，其余通过 runScript 调用）和 full（schema 里的全部工具）。

技能放在 skills/<name>/SKILL.md，加载进 dsh 的技能注册表，所以 /miran-... 和模型侧加载用的是同一批文件。先从 miran-dsh-studio 开始，它会点名其他技能。

| 技能 | 教什么 |
| miran-dsh-studio | 工作顺序、调研、节拍表、交接图 |
| miran-dsh-directions | 按 brief 选视觉方向，绝不套用固定风格 |
| miran-dsh-reference | 研究参考视频，转成片子自己的节奏与运动 |
| miran-dsh-shots | 屏幕上放什么：平面、让节拍活起来 |
| miran-dsh-design | 层级、可读的字号、纵深、真实 UI |
| miran-dsh-type | 排版、揭示与阅读文字 |
| miran-dsh-motion | 缓动、时序、停留、运动库 |
| miran-dsh-cuts | 镜头长度、剪辑、转场 |
| miran-dsh-camera | 纵深、推镜、3D 屏幕、变焦对焦 |
| miran-dsh-sound | 音乐、事件、电平、drop |
| miran-dsh-polish | 收尾、调色、导出、字幕 |
| miran-dsh-launch | 发布片的叙事弧 |
| miran-dsh-explainer | 讲解片的结构 |
| miran-dsh-social | 9:16、钩子、字幕、循环 |

配置

配置档设置放在 cordis.patch.yml；每个字段都有默认值。

| 字段 | 默认值 | 含义 |
| enginePath | "" | 引擎二进制文件；留空则用 ~/.miran/bin/miran，再找 PATH（MIRAN_BINARY 也算） |
| workspace | "" | 引擎读写的文件夹；留空交给引擎决定 |
| tools | "default" | default 跟随 MIRAN_TOOLS_DEFAULT，lean 列出约 30 个工具，full 列出全部 |
| viewer | true | 随引擎启动实时查看器 |
| viewerPort | 47800 | 首选查看器端口；被占用时用下一个空闲端口 |

故障排查

「Miran engine not found」 — 运行 npx miran-fann setup，或把 enginePath 指向二进制文件。设置页会打印它查找过的路径。

工具已连接，但调用提示需要登录 — 打开 Settings → Miran 登录；引擎对每次工具调用都校验账号。

Settings 里没有 Miran 区块 — 浏览器端没加载。先确认 dsh --profile <name> --dump-config 列出了 miran-fann，然后重启 dsh web 并刷新页面。

渲染没有返回图片 — 引擎以 MCP image parts 发送图片；dsh 在会话里显示。如果调用只返回文本，说明引擎拒绝了这次渲染，消息里会说明原因。

查看器打不开 — 端口被占用。改 viewerPort，或停掉另一个查看器。