推荐起点 · v0.2.1
给 Codex / Claude Code 等本地助理
让助理帮你准备模型
一套本地制作技能、确定性脚本和素材规范。让你自己的助理从已备好的图层走到可编辑项目与候选 MOC3。
- 包内有什么
- SKILL.md、使用指南、脚本、素材 schema、原创样例和 MIT 写入器。
- 解压后做什么
- 让助理先读取 SKILL.md，再选择分层素材或单图入口。
- 你会得到什么
- 可编辑源 ZIP + 候选运行时 ZIP。新输出仍需 Core、画面和动作验收。
01 / CHOOSE YOUR PACKAGE
你想做哪一步？
技能是工具，源项目用于修改，运行时用于播放。
原创四参数示例
给想继续调整网格与动作的人
打开源项目，继续编辑
五层原创几何素材，带近似呼吸、左右眼压缩和嘴层拉伸。用它熟悉编辑器的基础姿态与参数端点。
- 包内有什么
- project.mesh2d.json、项目清单和素材许可；图层像素嵌在 JSON 中。
- 解压后做什么
- 在网页网格编辑器选择“打开网格项目”，导入其中的 JSON。
- 你会得到什么
- 可继续修改、保存和重开的源项目。需要播放时，另行导出运行时。
已验收的示例模型
给想直接预览或接入网页的人
加载模型，看看它动起来
同一原创几何示例的真实 MOC3 导出包。已通过官方 Core、画面对比、声明动作和 ZIP 重开检查。
- 包内有什么
- model.moc3、model.model3.json、PNG 贴图、测试动作、验收记录与许可。
- 下载后做什么
- 在 Studio 使用本地 ZIP 预览，或连同全部依赖部署到你的网页。
- 要继续修改？
- 此包没有 editable 源；保留旁边的源项目。仅有 MOC3 不保证恢复完整编辑工程。
这里公开的是原创几何测试素材。示例中的眼压缩和嘴拉伸属于近似形变，不能当作完整眨眼、张嘴或骨骼绑定。三个包均不包含官方 Core、SDK、Editor 或用户私有角色。
02 / FIRST STEPS
选完包，下一步怎么做？
先跑原创样例，再换成有权使用的素材。
技能包
解压，交给你自己的助理
- 解压得到
live2d-local/，先读指南和许可。 - 把下面的指令发给你的 Codex、Claude Code 或其他本地助理。
- 检查样例输出后，再按素材规范准备自己的图层。
读取 ./live2d-local/SKILL.md 和 README.md。先用包内原创分层 PNG 样例生成可编辑源项目和候选运行时包；保留原件，输出到新目录。报告实际检查结果，不把候选包或角色名称当作验收通过。
可把文件夹放入你所用助理的技能目录，或直接让它读取 SKILL.md。无需宿主账号；脚本不会自动下载模型或调用图像 API。
在 live2d-local 目录运行
node scripts/image-input.mjs layers \
examples/independent-layers/layers.json \
demo-output输出到全新目录 demo-output/
- editable/
- project.mesh2d.json
editable-project.zip - runtime/
- model.moc3 + 贴图 + 动作
candidate-model.zip
候选包生成 ≠ 视觉验收通过。继续在兼容编辑器与合法运行时中检查。
03 / HOW IT WORKS
像素、源项目与运行时，各走一步。
保留源工程，运行时作为另一份交付物。
已有分层 PNG 或 PSD
PNG 图层加角色 manifest 可直接进入流程。已有 PSD 可经浏览器支持的平面 PSD 导入器保存为 mesh2d；CLI 不解析 PSD。
单张图片 / PNG
先用你实际可用、已授权的图像工具分层并补全遮挡区域，再检查真实 RGBA 图层。PSD 是可选交换格式，内部可以一直用 PNG + manifest。
- 01
准备真实图层
分割或生成部件，补出隐藏区域；没有工具则报告缺失步骤。
- 02
记录角色与坐标
role manifest 保存顺序、偏移、最终 PNG 哈希、许可与参数语义。
- 03
网格与关键形
依据 alpha 支持范围生成规则网格，建立并检查两个端点形状。
- 04
保存可编辑源
mesh2d JSON 保留图层、像素、网格与端点，供后续编辑和重开。
- 05
有限 MOC3 写入
实验 MIT 写入器生成真实 MOC3、model3.json、纹理图集与测试动作。
- 06
验收与预览
官方 Core 校验、源画面对比、参数组合、真实动作及 ZIP 重开。
为什么这样设计？
素材规范让工具之间能交接；共享画布坐标让各层对齐；可编辑源让你不用为一次修改丢掉工程；独立运行时包用于预览和部署。每一步都有可检查的文件，失败时能指出具体阶段。
参考 Bunraku §3、§5 与附录 G ↗ 的部件分类、RGBA 隐藏区补全、alpha 几何、跨层协调关键姿态和运行时插值思路。本技能以现有图像工具或手工素材、确定性网格和预设替代论文的训练组件；它不是论文模型或复现实验，也不捆绑论文图片、权重或数据。
当前能够导出的边界
- 1–4 个独立运动参数每个网格最多一个动态参数；一个参数可以驱动多个网格。
- 扁平 ArtMesh、线性端点最多16个可见网格、8192总顶点、4096像素纹理图集。
- 同网格叠加、旋转、层级、蒙版和物理尚未支持超出边界会拒绝，不静默丢动作；完整眼嘴、关节招手与 cmo3 工程不在当前输出范围。
04 / INSIDE THE SKILL
助理读什么，脚本负责什么？
本地脚本、固定职责、明确的输入输出。
live2d-local/
SKILL.md / README.md
IMAGE-ENTRYPOINTS.md
IMAGE-TO-LAYERS-PROMPT.md
AGENT-PROMPTS.md
PROVENANCE.json / LICENSE
scripts/
examples/
studio/spec/
vendor/experimental-moc3/素材 schema、PNG 样例与 MIT 写入器都在包内。官方 Core 由你合法取得，包中不含官方运行时二进制。
阅读技能 README ↗image-input.mjs流程入口layers从分层 manifest 生成两个包；single-demo做整图呼吸；tool-request生成图像工具请求。materials.mjs素材检查- 检查路径、PNG、文件及像素哈希、角色和坐标，依据 alpha 支持范围生成带边缘余量的规则网格。
cli.mjs源项目与导出inspect检查项目；materials建立源；source打包可编辑工程；export生成候选运行时。verify-core.mjs运行时检查- 使用你提供的固定版本官方 Core，核对真实加载、拓扑、UV、层序与参数形变；不能代替画面和动作检查。
png.mjs / zip.mjs本地文件处理- 有预算限制的 PNG 解码、图集编码及 ZIP 打包。脚本没有 npm 依赖或自动安装步骤。
默认离线、本地处理。 脚本不会调用宿主 Agent、上传素材或绑定某个付费 API。外部生图取决于你的现有工具和授权；私有素材需要另行确认处理目的地。官方 SDK / Editor 的获取与条款由你确认；实验写入器不是官方 Cubism 导出器。
05 / WHEN SOMETHING STOPS
遇到问题，先定位这一层。
下载了 ZIP，编辑器为什么打不开？
源项目 ZIP 先解压，再在“打开网格项目”中选择 project.mesh2d.json。运行时 ZIP 则在 Studio 的本地模型入口打开。技能 ZIP 是给本地助理和 Node 脚本用的，不是一个可直接播放的模型。
重复运行提示“Output already exists”，或 Node 运行失败？
每次选择一个全新的输出目录，原件和已有输出不会被覆盖。脚本需要已安装的 Node 22.12+。不支持的 PNG 类型，请用自己的本地图像工具导出为8位 RGB/RGBA、非交错 PNG；无需运行 npm install。
图层哈希、坐标或角色检查失败？
修改 PNG 后，重新记录最终文件 SHA-256；角色、偏移与画布尺寸须和真实文件一致。检查安全相对路径、唯一图层 ID 及明确的眼睛参数语义。重复整张合成图不能冒充拆层，视觉审批和隐藏区补全也不能由名字证明。
为什么眨眼像压缩、张嘴像拉伸，或导出被拒？
开放眼补丁或闭嘴线只提供近似形变，缺少的闭眼线、眼睑遮挡和口腔内部须先补素材。导出还会检查每个网格的动态驱动数、参数数量及结构边界。不要删掉失败检查来换取“成功”；先调整素材或网格绑定。
生成 MOC3 后，怎样确认真的可用？
Core 通过只是第一步。检查贴图方向、轮廓和遮挡，比较默认值、端点组合及中点（单参数为0/0.5/1），播放声明动作，并保存、重开 ZIP。空白、静态画面或文件头正确都不是完整验收。包中不含 Core；使用合法取得的匹配运行时。
反馈时说明你用了哪个包、系统与 Node 版本、失败阶段、错误文本和可分享的截图或合成复现。请勿将私有角色、密钥或未获授权的素材附到公开 Issues。
READY WHEN YOU ARE
先用原创样例，走完一遍。
拿到可编辑源，确认运行时，再开始自己的角色。