01 · 这件事

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 / 未结 issue2,462 / 424 / 11
建库 / 最近推送2026-11-03 / 2026-11-12
许可证 / 主语言MIT / Python
Release / tag / 提交0 / 0 / 9
贡献者 / 订阅者3 / 16

所以「电影」是流程产物:agent 写代码生成每一帧,headless Chrome 逐帧截图,ffmpeg 合成 MP4。仓库自己不出图,也不带模型。

02 · 核心机制

三个 Hook 盯住对话,六道门把人卡在每一次确认上

机制的核心不是渲染,是把拍片拆成一道道必须被人批准的关卡。SKILL.md 的 frontmatter 注册了三个 hook,全部指向同一段 node 查找器,最终调用 scripts/hook.cjs 拉起 guard.py。

Hook触发点作用
UserPromptSubmit用户发消息提问前先查「用户有没有看过」
Stop一轮结束拦住交付了草稿却不给确认按钮的回合
PreToolUse(matcher *)每次工具调用对话过大、大图入聊、助手超过 25 步等

三个 hook 的 onFailure 都是 continue,即 guard 自己出错也不拦用户。开工先问两件事:模式与用途;模式决定深度,用途决定片种,之后的默认提问、参考、关卡与检查都跟着用途走。

维度Quick 模式Film 模式
产物一个自包含 film.htmlthree.js 分镜 + 分层声音
画面 / 声音Canvas 2D 或 three.js / Web Audio八套预设 / 分层 beds、拟音、旁白
确认次数约 3 次逐步 6–8 次,直出约 3 次
适用时长约 3 分钟以内十分钟以上的纪录片、叙事片

内建规则写得像验收清单,SKILL.md 把它归成五条:

有意思的是体量:guard.py 有 103,011 字节,是 SKILL.md 的 3.14 倍。执行规则的代码比规则本身大三倍,说明这套 kit 真正押注的是「别让 agent 偷步」。

03 · 关键细节与数据

15.87 MB 的仓库里,一张演示动图占了 73.63%

递归 git tree 显示,这个仓库的重量几乎全在展示素材,不在代码。truncated 为 false,180 个节点 = 168 个 blob + 12 个 tree,逐 blob 累加 15,870,968 字节。

目录 / 文件文件数字节
docs/ 合计1512,947,801
其中 docs/media/1412,897,807
其中 reel.gif 单个111,686,272
scripts/39931,377
styles/61713,445
references/24493,604
tests/3305,750
templates/ 与 starter/12 / 5184,865 / 63,863
四份 README 合计4191,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 KBGitHub 自有算法,不引用

languages 不统计 md、json、gif、jpg,与 tree 差一个数量级;两者绝不能相加,也不能拿 size 字段反推文件体积。

数据核对:数字来自 api.github.com 的仓库、目录、releases、tags、languages、contributors、commits、search/issues 接口及仓库内文件原文。

核对时间 2026-11-14,星标与 issue 为实时值。

04 · 怎么用

「不需要付费服务」这句,要连环境要求一起读

工具包是 MIT 免费的,但跑通它要自备一整套本机环境与若干外部账号。README 首屏写 No paid service is required,紧接着的环境要求却列了一整排前置条件。

前置条件README 写的门槛
运行时Node.js 22+、Python 3.9+、ffmpeg
浏览器Google Chrome / Chromium / Edge,需可用 GPU
宿主 agentClaude 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 把边界写得很细:

05 · 冷思考

画面不花模型钱,但那段 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」:

类型数量内容
真 issue5#12 ffmpeg 7.1 上 apad 无界、音频永不结束,仓库自带测试也挂住
PR6#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 步的注意力——先看住它,再谈出片。

去看原始仓库

sarpstar/cinecode:给编码 agent 的拍片规则集,MIT,靠 SKILL.md、guard 脚本与 58 份风格配方驱动出片

前往 GitHub

相关平台

#Skill #Claude Code #视频生成 #开源