2,462 星买的不是渲染器,是一份 32 KB 的说明书
它不是一个装上运行就出片的软件,而是一份写给 AI 编码 agent 的规则集。sarpstar/cinecode 建于 2026-11-03,MIT,主语言 Python,仓库自述是「用代码做电影」。
核对日 2026-11-14 有 2,462 星、424 fork、11 个未结 issue,pushed_at 停在 11-12,updated_at 是今天。created_at 与最近推送之间只隔了九天。
releases 与 tags 两个接口都返回空数组,全仓只有 9 次提交、3 个贡献者。没有版本号,安装就是 git clone 到 skills 目录,更新靠 git pull。
入口不是可执行程序,而是根目录的 SKILL.md 与 AGENTS.md。前者 32,786 字节,带 Claude Code 的 hook 配置;后者 1,004 字节,只交代「要拍片先读 SKILL.md」。
| 字段 | 核对值 |
|---|---|
| 仓库 | sarpstar/cinecode · main 分支 |
| 星标 / fork / 未结 issue | 2,462 / 424 / 11 |
| 建库 / 最近推送 | 2026-11-03 / 2026-11-12 |
| 许可证 / 主语言 | MIT / Python |
| Release / tag / 提交 | 0 / 0 / 9 |
| 贡献者 / 订阅者 | 3 / 16 |
所以「电影」是流程产物:agent 写代码生成每一帧,headless Chrome 逐帧截图,ffmpeg 合成 MP4。仓库自己不出图,也不带模型。
三个 Hook 盯住对话,六道门把人卡在每一次确认上
机制的核心不是渲染,是把拍片拆成一道道必须被人批准的关卡。SKILL.md 的 frontmatter 注册了三个 hook,全部指向同一段 node 查找器,最终调用 scripts/hook.cjs 拉起 guard.py。
| Hook | 触发点 | 作用 |
|---|---|---|
| UserPromptSubmit | 用户发消息 | 提问前先查「用户有没有看过」 |
| Stop | 一轮结束 | 拦住交付了草稿却不给确认按钮的回合 |
| PreToolUse(matcher *) | 每次工具调用 | 对话过大、大图入聊、助手超过 25 步等 |
三个 hook 的 onFailure 都是 continue,即 guard 自己出错也不拦用户。开工先问两件事:模式与用途;模式决定深度,用途决定片种,之后的默认提问、参考、关卡与检查都跟着用途走。
| 维度 | Quick 模式 | Film 模式 |
|---|---|---|
| 产物 | 一个自包含 film.html | three.js 分镜 + 分层声音 |
| 画面 / 声音 | Canvas 2D 或 three.js / Web Audio | 八套预设 / 分层 beds、拟音、旁白 |
| 确认次数 | 约 3 次 | 逐步 6–8 次,直出约 3 次 |
| 适用时长 | 约 3 分钟以内 | 十分钟以上的纪录片、叙事片 |
内建规则写得像验收清单,SKILL.md 把它归成五条:
- 前 2 秒从第 1 帧就要有运动,且经过测量
- 每一帧都是时间的纯函数,重渲染结果一致
- 每个外部文件下载时即登记一行许可
- 长渲染后台运行并写状态文件,含预计剩余时间
- agent 只看小尺寸拼图,不把整图塞进对话
有意思的是体量:guard.py 有 103,011 字节,是 SKILL.md 的 3.14 倍。执行规则的代码比规则本身大三倍,说明这套 kit 真正押注的是「别让 agent 偷步」。
15.87 MB 的仓库里,一张演示动图占了 73.63%
递归 git tree 显示,这个仓库的重量几乎全在展示素材,不在代码。truncated 为 false,180 个节点 = 168 个 blob + 12 个 tree,逐 blob 累加 15,870,968 字节。
| 目录 / 文件 | 文件数 | 字节 |
|---|---|---|
| docs/ 合计 | 15 | 12,947,801 |
| 其中 docs/media/ | 14 | 12,897,807 |
| 其中 reel.gif 单个 | 1 | 11,686,272 |
| scripts/ | 39 | 931,377 |
| styles/ | 61 | 713,445 |
| references/ | 24 | 493,604 |
| tests/ | 3 | 305,750 |
| templates/ 与 starter/ | 12 / 5 | 184,865 / 63,863 |
| 四份 README 合计 | 4 | 191,764 |
docs/ 只有 15 个文件却占去八成体积,README 里 12 张静帧加这张 30 秒动图,是仓库唯一的「成片证据」。真正可执行的 scripts、starter、tests 合起来 47 个文件、1,300,990 字节。
styles/ 有 58 份 .md 配方,styles/index.json 实测也是 58 条。其中 51 条来自 lemomo-ai/lemo-opuscar 的钉死提交 d33bdea,只有 7 条标了 source: cinecode。README 写的「51 外来、7 自有」与文件对得上,这点没水分。
体量有三套互不相等的口径,混用就会算错。下表按来源分开列,正文只采信 git tree:
| 口径 | 数值 | 统计范围 |
|---|---|---|
| git tree 逐 blob 累加 | 15,870,968 字节 | 全部 168 个文件 |
| languages 接口 | 1,238,666 字节 | Python 1,013,465 / HTML 150,017 / JS 75,184 |
| 仓库 size 字段 | 13,639 KB | GitHub 自有算法,不引用 |
languages 不统计 md、json、gif、jpg,与 tree 差一个数量级;两者绝不能相加,也不能拿 size 字段反推文件体积。
- 身份:2,462 星 / 424 fork / 11 未结 / 建库 11-03 / pushed 11-12 / MIT。
- 版本:releases 与 tags 均空,9 次提交、3 位贡献者,无版本号。
- 体量:tree 180 节点、15,870,968 字节,reel.gif 占 73.63%。
- 构成:styles 58 份(51 外来 / 7 自有)、scripts 39、四份 README 191,764 字节。
- 边界:未安装、未渲染、未复现样片;11 个未结中 5 个 issue、6 个 PR。
核对时间 2026-11-14,星标与 issue 为实时值。
「不需要付费服务」这句,要连环境要求一起读
工具包是 MIT 免费的,但跑通它要自备一整套本机环境与若干外部账号。README 首屏写 No paid service is required,紧接着的环境要求却列了一整排前置条件。
| 前置条件 | README 写的门槛 |
|---|---|
| 运行时 | Node.js 22+、Python 3.9+、ffmpeg |
| 浏览器 | Google Chrome / Chromium / Edge,需可用 GPU |
| 宿主 agent | Claude Code 最佳,Cursor / Codex / Antigravity 亦可 |
| guard 版本 | Claude Code 2.1.295 及以上才注册 exec 形式 hook |
| 磁盘 | Quick 几百 MB,Film 每部几 GB |
安装是一行 git clone 到 ~/.claude/skills/cinecode,或在 Claude Code 里说「安装这个 skill」。Cursor、Codex、Antigravity 也能跑,但 guard 的三个 hook 只在 Claude Code 生效,其它宿主里工具检查照跑、实时拦截缺席。
联网边界 README 自己讲清了。渲染、混音与检查可离线,Quick 起始模板也可离线;但参考检索、音乐、首次下载字体与风格、以及 three.js 场景取库都要联网。LICENSES.csv 里 three@0.186.1 与 postprocessing@6.39.5 从 jsDelivr 按版本加载,不打包进仓库。
旁白可选,但要你自己的 Gemini key(有免费额度)或 ElevenLabs;图库素材要 Pixabay 的免费 key。「零依赖」指的是脚本只用标准库与系统工具,不是整条链路零外部资源。
商用同样要自己兜底,README 把边界写得很细:
- 逐项登记字体与素材许可到 LICENSES.csv,成片旁留 credits 文本
- 仓库按 MIT「原样提供」,发布者对影片许可负责,并注明「这不是法律建议」
- CI 三作业:Windows、Ubuntu、以及「无 Git 无 bash 的 Windows」,都开真实 Chrome 与 ffmpeg 测试
- README 自承「还没在 Windows 上完整做过一部片子」,旧版客户端可能标 GUARD OFF
画面不花模型钱,但那段 100–250 步的长对话花
最该打折读的是成本口径:代码出图不消耗模型,陪它走完流程的对话消耗。README 说画面由代码生成、不产生模型费用,同一份 FAQ 又给出 30–60 秒短片通常要 100–250 步,每一步都重读整段对话。
| 成本项 | README 自述 |
|---|---|
| 单部短片步数 | 30–60 秒 Quick 片通常 100–250 步 |
| 每步开销 | 重读整段对话,对话越长每步越贵 |
| 缓解办法 | 对话变长就换新会话,靠 STATE.md 续上 |
| 额外建议 | 关掉用不到的 skill、插件与连接器,用 usage.py 查 token |
这些缓解办法本身就承认了账单在哪。所谓免费,是把成本从 API 挪到了你的 agent 订阅与等待时间;真要拍十分钟的长片,先算的是会话轮次,不是显卡。
工程活动的密度更值得看。9 次提交里 sarpstar 占 7 次,claude 与 cursoragent 各 1 次,后两次都是 11-03 改 README;11-12 那两次也只是加 X 徽章、改一句推荐语。2,462 星对 9 次提交,热度远跑在工程前面。
11 个未结也要拆开,否则容易误读成「11 个待修 bug」:
| 类型 | 数量 | 内容 |
|---|---|---|
| 真 issue | 5 | #12 ffmpeg 7.1 上 apad 无界、音频永不结束,仓库自带测试也挂住 |
| PR | 6 | #11、#13、#15 都冲着同一个 master_audio.py 死循环 |
| 其它 PR 方向 | 3 | 本地页改用 127.0.0.1、免 Chromium 的 WebView 通道、Android app |
#12 从 11-12 开着、0 条评论,报告者连最小复现命令与四种组合的对照表都给了;PR #15 则说安装 Chromium 约 400 MB,在 iSH、Termux 上会直接崩。免费工具包的落地阻力,恰好集中在它不打包的那几样东西上。
所以判断不是「能不能出片」,而是你愿意替它承担哪一段。这套 kit 值得读的,是把审美决策拆成可检查的关卡、把外部素材拆成可回溯的许可记录;不值得信的,是「零成本」三个字。真正被消耗的从来不是 GPU,是你陪 agent 走完 100–250 步的注意力——先看住它,再谈出片。