name: ruic-pixel-explainer description: 生成粗像素 RPG 横屏讲解片，按实际生图能力分为参考角色生图与纯代码两条路线。有生图用4×4动作小人和独立半身表情图，无生图用半身、大头平面脸、无突出鼻子的代码角色；两路都配角色专属场景、语义组件与确定性MP4导出。适用读书讲解、像素讲堂、像《刻意练习》那种视频及大小人物样片。 user-invocable: true metadata: dsh: compatibility: native requires: - node - ffmpeg - python3 - curl

ruic-pixel-explainer · 粗像素电影式讲解片

把知识点演成像素世界中的动作，交付带口播的 16:9 MP4 与可修改工程。默认 1920×1080 / 30 fps；时长、文案、人物、场景以用户这次要求为准。

先判断模式

• 新主题 / 新人物 / 新场景：原创生成。参考片决定像素粗细、比例、灯光与节奏；人物与道具重新设计。
• 沿用已有一期：只修改该期数据和需要的场景，保留其他期。
• 逐帧恢复参考视频：仅在用户明确要求恢复素材或重建原画面时使用。恢复像素不是原创动画，也不能把整片画面包当成可编辑人物骨骼。详见 references/reference-modes.md。

先检查生图能力，再选路线

以本次宿主实际可调用的工具或使用者已配置且授权的图片生成后端为准。能读图片、目录里有一段生图脚本、或模型名称里写 img2，都不等于已具备可运行的生图能力。不为这条技能重复安装插件、下载模型或寻找密钥。

A开工读 references/imagegen-route.md，用 scripts/register_actor_sheet.py 与 assets/imagegen-template/sprite-actor.mjs 接入。B开工读 references/code-route.md，复制已升级的 assets/cinematic-template/。无论哪路，都复用同一套字幕、讲解组件与导出器。

有工具但当前生成失败或额度受限时，说明实际限制，按任务允许的范围改用已有PNG或B，不偷偷称调用成功。用户硬性要求特定生图方法时，先完成可独立推进的文案、场景与资产需求，缺该方法的角色生成不能冒充完成。

已有React游戏工程 ~/Desktop/zcode/ai-explain-game/game/ 仍可用于完整地图、选择题、评分和通关流程，接口见 references/pipeline.md。只在需要其交互时接入；旧14×21精灵不是当前角色规范，不能原样放大作大人物。

把模板复制到本次项目再改；不修改已验收的旧期。产线检查入口缺失时核实实际工程，不另装替代系统。权威源是 ~/.agents/skills/ruic-pixel-explainer/，其他agent经软链使用。

视觉重点

用户希望的是原片那种简单、可读的粗像素，不是更精细的像素插画。不要默认加密集纹理、蒸汽朋克装饰、发丝、亮晶晶大眼或满屏棋盘光环。

• 大人物是独立半身设计：从完整帽子或头盔到腰线，包含肩膀、胸部、袖子、手臂和方手，腿脚不入镜。保留参考的脸与服装；不能把全身小人放大裁腿冒充半身。
• 小人物是同一人的Q版行动版：大头、短身体、厚的阶梯轮廓、平面小脸。保留帽饰、眼色、眼罩、发型与服装；可正面或轻3/4走路，不强求解剖侧脸。A用4×4动作表；B至少有站立、走路和庆祝，别缩成看不清的小点。
• 脸上不额外画鼻子：无突出的侧鼻、鼻梁、中央鼻影或鼻尖高光。用眼睛、小嘴和少量腮红表达表情。PNG路线不在资产上再绘五官；代码路线的面部轮廓保持平整。
• 环境与人物不是同一个细节尺度：建筑的大体块比人物像素更大；细小表面线条少而低对比。避免密集 AI 插画，也避免把整面墙画成巨型棋盘。
• 场景对应角色：按角色气质、服装与本期动作设计空间，不给所有人套同一个房间或只换背景色。最新样片的暖色排练室与月窗创作工坊是差异化示例，不是固定身份和世界。
• 空间靠层次成立：后墙 / 人物 / 讲解道具 / 前景桌边或平台 / 原生分辨率光照 / 字幕。桌边可以挡腿，道具不能挡脸，字幕保留独立暗区。
• 每场一个主光源：暖灯或屏幕光形成局部明暗，边缘压暗；柔光不必像素化，脸与道具轮廓要保持硬边。按参考片选择暖棕、灰绿或冷夜色，别把固定蓝紫色板套到所有主题。
• HUD 服务于场景：大人物引入可以先不显示章节轨。进入小人物关卡后再出现简短导航与署名。地点卡可选，别把三件套硬塞满每一镜。
• 字幕按参考片选字体：本样板用真实加载的 Fusion Pixel 粗像素字，白色外描边＋暗内描边＋金色关键词。不是默认系统圆体。保持单行，长度以实际排版为准，超过宽度就分拍。

数值、角色比例与配方见 references/style-dna.md。最新视频的四张视觉锚点在 assets/reference-frames/，用于定标，不把示例角色或场景当成所有主题的默认。

让人物有事可演

粗像素不等于只有小人走路和嘴巴开合。根据每个知识点选择可操作的讲解组件，把一句抽象结论转成看得见的事件链：资料进入收藏栏 → 需要时检索 → 做题暴露卡点 → 对照反馈 → 获得能力。按当前主题重选比喻，不把这条链硬套到所有视频。

• 优先组合道具动作与信息反馈：资料卡、物品栏、开合书页、检索槽、题目板、卡点旗、答案对照、经验条、成就或解锁提示。组件有独立状态与时间参数，不能只贴静态文字框。
• 同一段落内按语义推进不同组件；一个组件成为焦点时，上一组件停止、变暗或退场。别把所有组件一起弹出，也别用密集装饰替代内容。
• 人物参与因果过程：拿取、关闭、标记、回答、核对和获得；让道具状态变化发生在相应口播，而不只是人物在空场景里来回走。
• 数量、对错和进度在场景内可被理解；示意游戏读数不要伪装成真实统计。框体、卡片、图标继续使用简洁硬边粗像素，保持安静背景和清楚的脸。
• 对照或答题面板留在头部上方或旁边，反馈条与角色行走路径错开；桌边、门与道具的前后关系正确，组件不盖脸、不压字幕。

组件 API 和如何编排事件见 references/teaching-components.md。模板中 components.mjs 可独立复用；episode.visualBeats 启用增强事件层，具体标签与时点由本期 JSON 传入。

从文案到成片

1. 确认主题、时长和参考风格。明确数字或专有事实才查出处；纯教学比喻不为凑事实表虚构引用。用户让你选文案就直接写。
2. 把文案分成语义拍，给每拍一个动作：物品出现、表情变化、走路、拿取、验证或开门。同场景可以有多句口播，不必每句话切镜头。
3. 人物与场景分别设计。新人物应改变剪影或特征组合，而不只是给老精灵换颜色。先锁定同一人的身份特征，再分别完成半身和小人物，不让两种景别变成两个人。
4. 逐句合成口播，量真实时长，再填字幕、说话区间与动作时间。口播走使用者自己的配音后端（HTTP API 或本地 TTS 命令；本技能不带内置音色，接法见 references/pipeline.md 第 5 节）——先 voice_track.py --check 验证接好、试听音色，再测语速；不要靠极端变速迁就拍脑袋的时间轴。使用者已有成品音轨就不必合成，render_episode.mjs --audio 直接指过去，但时间码仍按真实时长排。
5. 用时间的纯函数绘制，先取少量关键静帧检查比例与遮挡，再逐帧出片。同帧重截不一致必须修正；CSS 墙钟动画和 Math.random() 不进入录制画面。

用户已经授权具体样片或给了明确结构时，直接把样片做完给他审。复杂长片、内容有实质歧义时才澄清，不把分镜确认或静帧确认当作所有任务的固定停工门。

命令与入口

# B：先复制纯代码模板。episode.json 改文案与角色参数，scene.mjs 改场景与动作。
cp -R <技能目录>/assets/cinematic-template <本次项目目录>
python3 <本次项目目录>/serve.py --port 8778 --open

# 口播两步走；work 换到本期独立工作目录。
# 配音后端由使用者自己提供（HTTP API / 本地命令 / tts.config.json，见 references/pipeline.md 第 5 节），
# 没配置时脚本会报错并给出接法。先 --check 合成一句试听。
python3 <技能目录>/scripts/voice_track.py --check
python3 <技能目录>/scripts/voice_track.py --lines lines.json --work <work> --tts-only
python3 <技能目录>/scripts/voice_track.py --lines lines-abs.json --work <work> --out voice.wav

# 新样板与老游戏均提供 window.__player.set(ms) / total。
node <技能目录>/scripts/stills.mjs --url http://127.0.0.1:8778/ --out stills --times 1.6,6.2,10.5,14.8,18.4 --dsf 1.5
node <技能目录>/scripts/render_episode.mjs --url http://127.0.0.1:8778/ --out sample.mp4 --audio voice.wav --fps 30 --dsf 1.5 --size 1920x1080 --threads 2

1280×720 视口 × dsf 1.5 直接得到 1920×1080 截图，避免先截 2560 再 Lanczos 柔化像素。需要其他尺寸时保留像素边界，并实际核对输出。编码默认两线程，不能把全机吃满。

交付与声明

交付 MP4、可修改工程、关键静帧、口播文本与真实规格。输出放用户指定目录；当前宿主要求 outputs/ 时遵守宿主，不把固定桌面路径写死到每个任务。

检查视频时长、帧数、音轨、字幕安全区和时间轴确定性；有交互才检查实际输入与自动继续。渲完直接给用户审，不派代理重复整片审片。

原创片没有逐帧 RGB 一致性承诺。 视觉参考只是风格与规格依据；只有实际采用恢复像素并完成校验时才可报告恢复数据的像素一致性。不要拿这套指标证明原创生成与原片看不出区别。

✦ RuiC Pixel Explainer

一条粗像素电影式讲解片生成产线（Agent Skill）：给一段口播文案，产出带配音的 1920×1080 / 30fps 横屏像素讲解片（MP4）+ 一份可改的工程。 知识点被演成像素世界里的动作：资料卡飞进收藏栏、检索槽查不到内容、合上笔记答题、卡点被标记、答案对照、经验条与钥匙奖励。 角色资源按宿主能力走两条路线：有生图用参考图生成透明动作表，没有生图直接代码绘制半身与 Q 版小人。

源流派：像《刻意练习》＝"神"的武器那一类像素游戏风读书讲解片。 本仓库把这种风格做成可复现的产线：画面是时间的纯函数，逐帧导出、逐帧确定（同一帧重截两次字节必须一致），不靠录屏。

三条 20 秒样片 · 收藏 / 橙发 / 蓝发

🎬 演示 ·《收藏不等于学会》20 秒

deepseek flash生成

https://github.com/user-attachments/assets/522644ab-0875-4d18-8994-306fc1beb279

大人物 0–10 秒：收藏了一堆干货，真要用时，却想不起来。／ 存下来，不等于学会了。／ 你缺的，是一次提取。 小人物 10–20 秒：合上笔记，先答一道题。／ 卡住做标记，马上对答案。／ 答出来，钥匙才真正属于你。

🎬 演示 · 双角色样片（橙发 / 蓝发）

GPT6.1Sol 生成

https://github.com/user-attachments/assets/7ae16020-a06b-488a-8e5e-c2cc143761b7

https://github.com/user-attachments/assets/6ca09ced-0c1f-48b1-8515-1868c6ef87c6

同一套产线换两名角色与两套场景：半身开场 4 个表情 ＋ 4×4 小人格 16 个姿态，各 20 秒。

橙发角色 · 排练室：别急着从头开始。 蓝发角色 · 月窗工坊：先动手，再等灵感。

这是什么

• 输入：一段口播文案（一句一行）。
• 输出：一条 20 秒级的成品 MP4（1920×1080 / 30fps / 带配音）+ 可继续修改的工程 + 关键静帧 + 真实规格。
• 做法：把文案拆成语义拍，给每一拍设计一个看得见的动作（进入、检索、答题、标记、对照、奖励），再把场景、道具、字幕与镜头按时间画出来，逐帧导出。
• 角色：两套资源、两条路线 —— A 生图（参考图 → 每角色 4×4 透明动作表 ＋ 半身表情表 → 注册后由 SpriteActor 绘制）／ B 代码（半身与 Q 版小人由绘制函数直接画）。两路共用同一套组件、字幕与导出器。

它不是什么：

• 不是文生视频模型 —— 每一帧都由代码按时间确定性绘制/合成（A 路线的角色贴图来自生图，但走位、动作、时间轴与字幕仍由代码决定），因此可复现、可回退、可改一个字重出。
• 不做精细插画。粗像素是故意的：块面要大、纹理要少、脸要清楚；密集纹理、发丝、亮晶晶大眼、满屏花纹都是反方向。
• 不把整片画面包当成可编辑骨骼 —— 逐帧恢复原片像素是另一条口径，详见 references/reference-modes.md。

✨ 它能做什么

1. 两档人物，一套身份

半身人物是独立的腰线以上设计（从完整帽子或头盔到腰线：肩、胸、袖子、手臂与方手，腿脚不入镜）；Q 版小人是同一个人的大头行动版（约 24×31，大头短身、厚的阶梯轮廓，站立 / 走路 / 庆祝）。 脸上不额外画鼻子 —— 无突出侧鼻、鼻梁、中央鼻影或鼻尖高光，用眼睛、小嘴和少量腮红表达表情。

人物资源按宿主能力分两条路线（详见 references/imagegen-route.md 与 references/code-route.md）：

• A · 生图角色：参考图 → 每角色一张 4×4 透明动作表（16 格）＋一张 半身表情表 → register_actor_sheet.py 按 alpha 间隔注册 → SpriteActor 在 Canvas 里绘制；
• B · 代码角色：不依赖任何生图能力，用升级后的 frontActor / sideActor 直接绘制，可通过 hairStyle / headwear / 眼色 / 眼罩等字段配置。

⚠️ 旧线索里那套 14×21 小精灵不符合当前规范，不能只换色或放大继续用。

2. 八个可复用讲解组件（assets/cinematic-template/components.mjs）

坐标是原生 1920×1080，值 / 状态 / 标签 / 透明度都由该期时间轴决定：

它们都是世界里的道具或 HUD，不是整页截图；标签从当期 episode 数据传入 —— 库本身不绑定任何一期的口播、音色或语速。

3. 语义事件时间轴（visualBeats）

在 episode.json 里给一条时间轴，scene.mjs 的增强分支就会按事件把组件一个个开出来（不写就是简版）：

{
  "visualBeats": {
    "collectAt": 500, "queryAt": 2000, "contrastAt": 4500, "retrieveAt": 7000,
    "testAt": 11000, "closeAt": 11000, "markAt": 13500, "checkAt": 14500,
    "correctAt": 16500, "rewardAt": 17300, "unlockAt": 18200, "walkAt": 15400
  },
  "componentLabels": {
    "inventoryTitle": "收藏栏", "queryTitle": "调取记忆", "contrast": "存下 ≠ 学会",
    "taskTitle": "当前任务", "prompt": "本次问题", "wrongAnswer": "尝试回答",
    "rightAnswer": "参考答案", "reward": "能力已解锁"
  }
}

一拍一个因果变化：资料飞入时看库存，检索失败时看结果，核对时看回答与参考答案，成功后才给奖励。 面板与角色行动分开编排（角色初始站位 / 行走经过区域 / 终点都要考虑）；绘制顺序是背景 → 人物与手持道具 → 奖励与 HUD，别让开门的矩形把奖章抹掉。

4. 逐帧确定（这条产线的硬门槛）

CinematicScene.draw(canvas, ms) 是纯时间函数；表面纹理用固定随机种子；window.__player.set(ms) 单点定位。 出片时逐帧截图喂 ffmpeg —— 同一帧截两次必须字节一致，不一致就停下修，不许把 CSS 墙钟动画或 Math.random() 放进录制画面。

🧩 它怎么工作

flowchart LR
  A[口播文案] --> B[拆成语义拍<br/>每拍一个动作]
  B --> C[人物与场景分别设计<br/>先锁身份特征，再做半身与小人]
  C --> D[逐句配音 · 后端自带<br/>量真实时长 → 排字幕与动作]
  D --> E[纯时间函数绘制<br/>先静帧查比例与遮挡]
  E --> F[逐帧导出<br/>t 定点截图 → ffmpeg]
  F --> G[MP4 + 可改工程<br/>+ 关键静帧 + 真实规格]

🛣 工程路由（按宿主生图能力选）

无论哪条路，都复用同一套字幕、讲解组件与导出器；四条视觉锚点在 assets/reference-frames/（只用于定标，不当作所有主题的默认角色与场景）。

自带样板里有什么（assets/cinematic-template/）：

• scene.mjs —— 画人物（frontActor / sideActor）、后景、道具、前景、灯光、HUD、字幕；内置零件：吊灯、座钟、书架、椅子、地板、聚光锥、暗角、金边面板、问号、钥匙
• episode.json —— 主题 / 作者 / 时长 / 帧率 / 切点 / 角色配色（actor：发色、发亮部、外套、外套亮部、围巾、肤色三档、配件）、章节、说话区间（voice）、字幕（lines）、事件层（visualBeats 可选）
• components.mjs —— 上面那八个组件
• index.html —— 播放器 + window.__player.set(ms)/total（导出器认这个钩子）
• serve.py —— 本机 HTTP 服务，支持音频 byte-range
• assets/fonts/ —— Fusion Pixel 12px（OFL-1.1，含许可证）；assets/voice.wav —— 20 秒示范配音，新主题必须替换（用自己的后端生成，或直接换成品音轨，见「配音与时间轴」）

🚀 快速开始

先按 SKILL.md 确认宿主有没有可用的生图能力，再选路线：有生图走 A（见 references/imagegen-route.md），没有就走 B（下面这套）。

# 0) B 路线：复制纯代码模板到本次项目（别直接改模板）
cp -R assets/cinematic-template <本次项目目录>
cd <本次项目目录>

# 1) 改 episode.json：主题、角色配色与可选字段（hairStyle / headwear / eye / eyePatch）、说话区间、字幕（以及可选的 visualBeats）
#    ⚠️ 改配色 ≠ 设计新角色；模板字段不足以表现新轮廓时，扩展 scene.mjs 的 frontActor / sideActor 与新场景代码

# 2) 起本机预览
python3 serve.py --port 8778 --open

# 3) 逐句配音 + 量真实时长（两步走；配音后端要你自己给，先 --check 验证）
python3 <技能目录>/scripts/voice_track.py --check
python3 <技能目录>/scripts/voice_track.py --lines lines.json     --work work --tts-only
python3 <技能目录>/scripts/voice_track.py --lines lines-abs.json --work work --out voice.wav

# 4) 静帧预检（先看比例、遮挡、字幕安全区）
node <技能目录>/scripts/stills.mjs --url http://127.0.0.1:8778/ --out stills --times 1.6,6.2,10.5,14.8,18.4 --dsf 1.5

# 5) 逐帧出片
node <技能目录>/scripts/render_episode.mjs --url http://127.0.0.1:8778/ --out sample.mp4 \
     --audio voice.wav --fps 30 --dsf 1.5 --size 1920x1080 --threads 2

A 路线先注册生成的角色资产，再把 sprite-actor.mjs 接到模板上（完整接法见 assets/imagegen-template/INTEGRATION.md）：

python3 <技能目录>/scripts/register_actor_sheet.py --sheet mini.png     --grid 4x4 --canvas 256 --baseline 240 --out assets/sprites
python3 <技能目录>/scripts/register_actor_sheet.py --sheet half-body.png --grid 2x2 --canvas 512 --baseline 500 --out assets/bust

🔊 配音后端由你自己提供（HTTP API 或本地 TTS 命令）；本技能不带内置音色，--check 先试听一句，接法与配置见 references/pipeline.md 第 5 节。

--dsf 1.5 是用意的：1280×720 视口 ×1.5 直接得到 1920×1080 截图，避免先截 2560 再 Lanczos 下采样把像素边缘柔掉。要别的尺寸就自己核对输出。

🎨 视觉定标

• 脸：约 18–28 格宽、20–24 格高；头发 2–3 个块面；肤色 3 层就够；不要细发丝、渐变脸、虹膜反光；不画鼻子（无侧鼻、鼻梁、中央鼻影、鼻尖高光），表情靠眼睛、小嘴与少量腮红。
• 手：可与身体略分离，方块手势，有肩膀和衣领。
• 场景密度：两三个识别物就能定地点（修理铺＝桌椅＋灯＋钟；记忆关卡＝书＋路＋锁门），且场景要对应角色（按角色气质与本期动作设计空间，不套同一个房间或只换背景色）；大部分处在暗部，纹理只用来辨认材质。
• 光与色：暖主光约 #d8c58c；外围近黑棕或灰绿；皮肤 #edc49c / #ddb18c / #bf926c；轮廓 #19221e；金边与关键词 #cfab57 / #d9a13e；青绿只给反馈或路径。每场一个主光源，前景桌边挡腿、道具不挡脸、字幕占最后层。
• 字幕：本地 Fusion Pixel，通常 60–72 px，纸白外描边＋暗内描边＋一个金色关键词；单行居中、底部暗区；超宽按语义拆拍，不强行缩小。
• HUD：半身开场可以先不给章节轨；进小人物关卡后再出现导航、署名、计数或反馈 —— 不是每镜都塞满导航＋地点卡＋进度＋状态卡。

🔊 配音与时间轴

• 中文口播约 4.5 字/秒，但句读、数字、英文都会拉长 —— 所以先 TTS 量真实时长，再排字幕与动作，不靠极端变速迁就拍脑袋的时间轴。
• voice_track.py 默认拒绝段落重叠（要叠声才传 --allow-overlap）；不裁句尾凑预算；拼轨时把每句摆到它的 at（前面补静音），所以画面时间轴与配音天然对齐。
• 出片端按画面长度补静音，不用 -shortest（音频短一点会把画面尾巴吃掉）。
• 配音后端由你自己提供（本技能不带任何内置音色）：HTTP API 或本地 TTS 命令两种接法、请求/响应约定与配置优先级见 references/pipeline.md 第 5 节；--check 一句话验证接好没有。
• 已经有成品音轨（真人录音、别的工具合成）就跳过合成，把 render_episode.mjs --audio 指过去；但字幕与动作仍要按它的真实时长排。

✅ 验收清单

• 同一帧重截两次字节一致（render_episode.mjs 自带抽帧自检）；确定性问题先修再渲。
• 关键静帧逐张看：半身脸的表情结构、半身与小人比例、前景遮挡、字幕字形与安全区。
• ffprobe 核对：时长、帧数、帧率、音轨。
• 文字：单行、不压字幕带、不盖脸；数字有出处、示意读数不伪装成真实统计。
• 交付：MP4 + 可改工程 + 关键静帧 + 口播文本 + 真实规格；渲完直接给用户审，不派代理重复整片审片。

原创片没有逐帧 RGB 一致性承诺 —— 视觉参考只作风格与规格依据；只有实际采用恢复像素并完成校验时，才可以报告像素一致性。

📦 目录

RuiC-pixel-explainer/
├─ SKILL.md                     技能主文件（放进 ~/.agents/skills/ 就能被 Agent 调用）
├─ references/
│  ├─ imagegen-route.md         A 路线：生图角色的两套资源（4×4 动作表＋半身表情表）与提示词约束
│  ├─ code-route.md             B 路线：升级后的代码角色函数与可配置字段
│  ├─ style-dna.md              视觉定标：三档分辨率 / 人物 / 场景密度 / 光色 / 字幕字体
│  ├─ cinematic-profile.md      B 样板配方（人物参数、镜头切点、说话区间、验证重点）
│  ├─ teaching-components.md    讲解组件与语义事件（怎么做"有东西在演"）
│  ├─ reference-modes.md        原创参考 vs 素材恢复两条口径
│  └─ pipeline.md               工程接法（旧 React 工程 + 配音后端 + 导出器）
├─ scripts/
│  ├─ voice_track.py            逐句 TTS（后端自带：HTTP API / 本地命令，带缓存）→ 量时长 → 按时间轴拼一条音轨
│  ├─ register_actor_sheet.py   角色图集注册：按 alpha 间隔切分、统一缩放、脚底/腰线锚点
│  ├─ render_episode.mjs        逐帧导出（自带同帧重截一致性检查）
│  └─ stills.mjs                静帧质检（渲片前必跑）
├─ assets/
│  ├─ imagegen-template/        A 路线的静音资产检查页与 SpriteActor 适配器（不含角色 PNG）
│  ├─ refere