dsh-free-media
给 DeepSeek Harness 装上免费的图片生成、视频生成和视频理解。 MIT。
一个插件，三个工具，一份 skill。其中两个工具完全不需要任何 API Key。
| 工具 | 能力 | 要不要 Key | 实测状态 |
|---|
free_image_generate | 文生图 | 不要 | ✅ 已实机出图 |
video_extract_frames | 视频抽帧（视频理解） | 不要 | ✅ 已实机跑通 |
free_video_generate | 文生视频 / 图生视频 | 要（免费注册） | ✅ 已端到端出片 |
另外附带一份 free-media skill：当工具不够灵活（需要组合、自定义参数、跑管道）时，agent 可以直接调用包内脚本。
为什么是这三个
市面上的免费方案要么需要 Key，要么已经失效，要么对 A 卡不可用。这个插件只保留实测还在工作的那些：
- 出图走 Pollinations 免费端点，零 Key。注意：免费模型现在只剩
sana，老教程里的 turbo / flux 已失效（实测返回 HTTP 500）；而且必须带 width/height，否则会收到 HTTP 200 加一个 0 字节的空响应。这两点都已经在脚本里处理。
- 视频理解用 ffmpeg 抽帧 + 读图：零外部依赖、零 Key、数据不出本机。能白嫖的云端 VLM 免费层要么大陆连不上（Gemini），要么默认会在额度用尽后转按量扣费（百炼）。
- 视频生成走智谱
cogvideox-flash：官方文档把它归在 models/free/ 下，大陆直连、无需信用卡。这是目前能确认真正免费的云端文生视频之一（Veo / 百炼 / 硅基流动 / 模搭 / Pollinations 的视频模型都没有免费层）。
中文提示词会自动免费翻译成英文（走 text.pollinations.ai，同样零 Key）——因为免费出图端点看到中文会整体滑向写实风。
安装
dsh plugin --profile <你的profile> add dsh-free-media
装完重启 DSH，并新开一个会话（DSH 的工具集在会话创建时快照，旧会话不会带上新工具）。
Desktop 应用用户注意：desktop profile 由应用独占管理，命令行会报
profile "desktop" is managed exclusively by the Electron application。
请改用图形界面：设置 → 内置插件 → 添加插件，或让 agent 用插件管理工具安装。
从本地源码装（开发用）：
dsh plugin --profile <profile> add -w /path/to/dsh-free-media
环境要求
- Node ≥ 18（脚本用到全局
fetch；DSH 本身要求更高）
ffmpeg / ffprobe 在 PATH（只影响 video_extract_frames）。可用 FFMPEG_PATH / FFPROBE_PATH 覆盖- 视频生成需要免费注册的 Key
视频生成的 Key
两个免费供应商二选一：
Key 三选一（优先级从高到低）：
- 工具参数
key / 脚本 --key
- 环境变量
ZHIPU_API_KEY / AGNES_API_KEY
- 文件
~/.dsh/free-media-keys.json：{"zhipu":"xxx","agnes":"yyy"}
建议先 dryRun: true（或 --dry-run）看请求体，确认无误再实跑。
实测数据（2026-10-03）
出图：640×640 3.2 秒，中文提示词自动译成 a red fox sitting in the snow。
视频生成，两次完整成功：
| 文生视频 | 图生视频 |
|---|
| 全流程耗时 | 41 秒 | 53 秒 |
| 产物 | 1280×960 h264，5.108s，约 1.05 MB | 同规格，约 1.65 MB |
| 附产物 | 封面 jpg（来自响应的 cover_image_url） | 同 |
| 水印 | 右下角烧入「AI生成」（免费档默认） | 同 |
抽帧：6 秒视频 → 6 帧，时间码精确 0/1/2/3/4/5 秒；scene 模式在硬切处精确命中 3s 与 6s。
两个容易误判的点（已写进 skill）：
fps=30 是请求值，不是产物值——实际容器 r_frame_rate 是 37/1。断言产物规格一律以 ffprobe 为准。- 免费档时长不可调——
cogvideox-flash 契约里没有 duration 字段（只有付费的 Vidu 系列有），产物固定约 5.1 秒。
局限（请如实告知用户）
- 免费出图档会静默降采样。实测：请求 512×512 得到 512×512，但请求 1024×1024 得到 768×768，
请求 1280×720 和 1920×1080 都得到 1024×576——后三者恰好都是 589,824 像素，
即免费档上限约 0.59 MP。所以返回值里
size 是请求值、actualSize 才是真实值，
两者不一致时另有 sizeNote 说明。断言产物规格请用 actualSize。
- 免费出图档对精确计数不可靠。同一个「三个男生和一个女生举起酒杯」的提示词，实测三次得到
3 人 / 5～6 人 / 2 男 1 女，酒杯时有时无。需要精确人数或画面文字时不要用它。
- 抽帧不含音轨。问「视频里说了什么」需要另配 ASR；不要根据画面猜台词。
- 抽帧丢时序。帧是离散快照，帧间运动与短暂事件会漏。
- 免费档限流。出图的 402/429 是常态而非封禁，脚本会自动退避（15s→30s→45s→60s）；连发多张会自己把自己限流住。
- 免费不等于有 SLA。Agnes 官方明写免费计划不保证可用性；这类「免费 API」随时可能调整。视频生成失败时脚本会打印上游原始响应，不要只报「失败了」。
- 视频生成超时会给出任务 id。拿 id 稍后再查，不要盲目重提任务。
开发
npm run check # 四个文件的语法检查
npm test # 离线自测：用 mock ctx 验证插件注册了什么
node test/verify-package.mjs # 用市场自己的模块校验包合规性
npm test 不启动 DSH，用 mock ctx 断言：skill 被注册、frontmatter 被正确剥离、
三个工具的 JSON Schema 形状正确、render() 面对空值不抛异常、以及
lib/index.js 不含任何 @deepseek-ai/* import。
最后一条是硬约束，原因见下。
实现约束（改代码前必读）
-
绝不 import 任何 @deepseek-ai/* 包。
第三方插件的模块位置在 <profile>/node_modules/<pkg>/lib/，而 profile 的 pnpm 配置是
autoInstallPeers: false + nodeLinker: hoisted，宿主包并不在那里。实测
import.meta.resolve('@deepseek-ai/dsh-tools') 从该位置直接 ERR_MODULE_NOT_FOUND。
顶层 import 失败就等于插件加载失败，而 DSH 的启动是全有或全无——一个坏插件会让整个
profile 起不来。所以宿主代码只用 node 内置模块，服务一律经 ctx 取。
-
工具定义必须用「标准 JSON Schema」。
官方 defineTool() 会先做 parameterSchemaSpecToJsonSchema() 再把结果交给注册表，
也就是注册表收到的是标准形式。绕过 defineTool 就得自己给标准形式：
required 是字符串数组，不是每个属性上的 required: true。
npm test 里有断言专门守住这一点。
-
出网交给子进程里的 node 脚本。
宿主求值环境没有 fetch；包内 scripts/*.mjs 只用 node 内置能力，
出网、重试、落盘都在里面。参数以 argv 数组直传、不开 shell。
-
脚本里的「是否被直接执行」判定必须用 realpathSync 比较。
以 link: 方式安装时，宿主拿到的是符号链接路径
（…\profiles\desktop\node_modules\dsh-free-media\scripts\img.mjs），
而 Node 默认把 import.meta.url 解析成 realpath（D:\…\projects\dsh-free-media\…）。
早先写成 import.meta.url === pathToFileURL(process.argv[1]).href，两者不等
→ main() 从不运行 → 进程退出 0 但 stdout 为空，调用方只看到一句
「stdout 不是合法 JSON」。test/plugin.test.mjs 里有一条用目录 junction 复现该场景的回归测试。
-
改了 lib/ 必须重启 DSH 才生效；改了 scripts/ 立即可用。
宿主半边是进程启动时加载进内存的，之后磁盘上的 lib/ 变了也不会重载
（插件的 disable/enable 也不够）。而脚本是每次调用新 spawn 的子进程，从磁盘现读。
这个差异很容易让人误判「改了没生效 / 生效了」，排查时先分清改的是哪一半。
目录
dsh-free-media/
├── package.json # dsh.bundle.patch + engines.dsh
├── cordis.patch.yml # 挂载层（inject: tools, skills）
├── lib/index.js # 宿主半边：注册 skill + 三个工具
├── scripts/ # 可独立运行的脚本（出网/重试/落盘都在这）
│ ├── img.mjs
│ ├── vframes.mjs
│ └── vgen.mjs
├── skills/free-media/SKILL.md
└── test/
├── plugin.test.mjs # 离线自测（mock ctx）
└── verify-package.mjs # 用市场模块校验合规性
License
MIT。本插件通过 HTTP 调用第三方免费服务（Pollinations / 智谱 / Agnes）；
提示词会发送给相应服务商，请自行评估数据敏感性。
