Live2d Puppet

Live2D Puppet

目标

把角色原图、See-through 分层 PSD 和自然语言目标交给 Codex 一类外部 Agent。Agent 通过 PuppetLoom CLI 自动创建项目，再按整模或指定部位完成结构分析、网格与关键形制作、权重和物理配置、自检、局部返修及准确 revision 的视觉证据。用户主要审查角色实际效果，并用“幅度小一点”“滞后太慢”“太弹”这类结果反馈继续调整；逐点编辑只是备用能力。桌面应用是查看、播放和人工兜底工具，不承载 Agent 编排或聊天入口。默认交付仍是普通 PuppetLoom 项目。用户明确需要 Cubism 时，使用 cubism export 输出 .cmo3/.moc3 和配套文件；已有 Editor 工程的同步仍可使用官方 API 桥接。直接导出与 API 同步的限制必须分别报告。第一次结果以“合理地会动”为目标，不用十五种嘴形或未经素材支持的复杂表情；需要实时麦克风口型时，默认只使用已有闭口和一个张口状态。

工作方式

先使用包装脚本运行 capabilities --json，确认 build.current、实际命令和配套 Skill 身份；不要根据软件版本号猜工具是否存在。包装脚本支持 PUPPETLOOM_ROOT 和 PUPPETLOOM_NODE；复制到仓库外的 Skill 必须明确项目根。按当前结果读取对应方法，不为一次局部修形加载全部制作流程：

使用 scripts/invoke_puppetloom.ps1 调用公开 CLI。当前任务已经有明确项目或仓库根目录时，测试、生成、中间、最终产物以及日志、截图、录屏和迁移暂存全部写在该根目录内；依赖、缓存和桌面应用用户数据留在机器工具目录，不冒充项目产物。普通项目先 inspect/create/verify/describe/render，再按任务和用户允许的证据形式选择 play 或 record；实际查看姿态图、4×4 次级运动图、准确 revision 的实时窗口，或获准生成的动态接触表/WebM 后才能判断结果。完整角色交付前还必须对同一个规范项目和准确 revision 运行 performance，以活动态与暂停态对照的 FPS、p95、p99、最差帧和长帧判断真实渲染是否稳定；固定 fixture、平均 FPS 或 ok: true 不能代替 valid: true。测试通过不等于视觉自然，视频也不是固定交付物。分层验收发现 See-Through 背景残片、低透明托底或可安全去除的硬矩形托底时，不把普通创建的保守 Alpha 清理冒充 PSD 已修复；先由外部 Agent 结合原图、单层和未增强合成确认异常边界，再通过同一包装脚本的 psd repair/review/finalize 生成新的 PSD、绑定视觉证据并形成不可改写的终态。Photoshop 已经运行时不得连接或复用用户会话，先让用户保存并关闭 Photoshop；自动化只能使用本次命令启动的会话，且有剩余文档时必须保留窗口可见、禁止退出。用户提供多份 PSD 或要求结合原画补件时，先建立逐部件来源清单并选定规范画布；不同分辨率 donor 只有在明确启用整画布等比例适配且宽高比一致时才能进入 Photoshop 配方。原 PSD 永不覆盖，未完成逐层细节与 Alpha 复核、未形成视觉终态或被拒绝的输出不得进入创建；详细边界和命令见 references/source-art-and-layering.md 与 references/from-zero-workflow.md。

角色闭眼与头脸造型先按 references/shape-target-workflow.md 标记实际结构，使用 fit-landmarks / curve-warp 和 author preview/apply 制作可核对的目标；自动起稿不是最终形状。其他分部制作的正式入口是外部 Agent 先看基线，再用 agent specification 取得当前 revision 的结构化模板，填写 goal/anatomy/parts/intent/rationale，最后运行 agent plan/apply --spec <json>。anatomy 是本角色的结构事实，不是通用风格参数：头脸和嘴保留实际眼线、嘴线与中轴，前后发写实际发束及根部，左右耳分别写实际图层、轴心和全顶点固定/释放权重，头饰与上衣也写各自连接轴心和全顶点权重；头饰还必须明确选择 headwearPerspective: "crown" 或 null，不得根据长宽比或旧角色形状猜。每个部位都必须填写基于准确 revision 画面的非空 rationale；原样模板、占位理由、空壳 anatomy、未覆盖实际图层或缺少理由会被 CLI 拒绝，不能用安全默认值冒充视觉判断。parts 可覆盖头脸、眼睛、嘴、前发、后发、呆毛、耳朵、头饰、身体、上衣、裙摆、尾巴和配饰。先运行只读 agent plan，核对 inputMode: structured-specification、baseRevision、草稿接管、目标图层、anatomy 覆盖、各部位状态、检查、返修、素材请求和 blockers；计划符合目标后再运行 agent apply。自然语言 --instruction/--scope 只保留只读计划兼容，不能正式 apply 或创建 revision：自然语言理解、看图判断和返修决策由本 Skill 中的外部 Agent 承担，软件只执行和验证明确规格。整模执行按确定顺序处理所有存在的部位，每个部位单独形成可恢复 revision，最后返回整模 verification、总状态和报告路径。项目没有相应图层时报告 not-present，现有结构无法支持目标表情且确实缺少素材时报告 needs-assets，不能伪造图层或把它们说成已经制作完成。

“完成整模”“检查遗漏”或“继续把现有角色做好”不等于立即运行整模 apply。已有 revision 和接受记录的成熟项目先运行 history/verify/describe，查看当前准确 revision 的整模及所有实际存在部位，并列出必须保留的已接受结果；只为确实观察到的缺陷生成 selected 或单部位规格。若没有待修缺陷，不执行 apply，不制造无意义 revision。CLI 的整模 apply 不是整体事务：已完成部位会逐个提交，后续部位变成 blocked 不会自动撤销前面的 revision；返回后必须核对每个部位的实际 from/to revision、session 和报告，不能只看总状态。

agent front-hair plan/apply 与 agent secondary plan/apply 仍是精确控制和兼容入口；正式整模或分部制作优先使用顶层结构化规格入口。标准表情和动作库使用 actions plan/apply。参数结构使用 author inspect/apply；局部关键形先用 author geometry 分页定位，再以选区和 transform-keyform 修形，不让模型猜整层顶点数组。轴心和权重仍用 describe --layer <id> 与稀疏 calibrate。固定连接与自由端的判断由 references/visual-rigging-rules.md 负责；补件归位和试装由 references/asset-and-geometry-workflow.md 负责。edit 只在用户明确想手调，或公开 CLI 确实无法表达局部修正时打开，不用扩建手工编辑器代替外部 Agent 制作。

范围必须服从用户目标：用户要求整模时审查整模，真正写入只覆盖已证明需要修复的部位；用户只点名一个部位时只使用对应部位 ID，不擅自扩展。用户要求调整“整个图层顺序”时，范围是当前角色全部可见遮挡关系，不会被最后指出的某个脖子、兜帽或配饰问题收窄。用户在任务中追加的限制立即作用于后续操作；后来的截图、批注或单项纠正默认只修正点名项，除非用户明确替换目标，不得把此前同一任务的完整范围收窄成最后一个问题。用户说“只使用现有素材”时，不生成、下载、增强或改写 PSD/纹理，needs-assets 只报告缺口；用户说“不要视频”时不运行 record，改看 render --project <directory> --output <new-directory> --revision <n> --size 1080 --focus <part>、4×4 运动表和 play --project <directory> --revision <n>。已有接受结果必须保留可恢复 revision，并作为未点名区域的保护基线；用户明确把某个项目作为只读对照时，另建获准的工作副本并核对对照项目未变。现有项目只缺多房束、侧脸深度或躯干体积等后来增加的字段时，先使用 extensions plan/apply 在当前项目追加可恢复 revision，不得重新创建项目；软件升级、CLI 新能力或项目格式新增字段不等于源 PSD 变化。源 PSD 确实变化时，用 migrate 在规范项目内部的新暂存目录建立候选，完整复核后归档旧运行状态并把候选晋升回原规范路径，不能在旁边留下 Character-v2 作为第二个最新版。每次自动制作后都比较修改前后，并查看准确 revision 的连续运动：安全姿态通过只证明没有已知翻转，不能证明目标部位真的在动、根部没有脱离、原有效果没有退化。Agent 必须实际打开各部位返回的 focusComparisonSheet 和 4×4 focusMotionSheet，检查连续帧并记录仍存在的问题；focusMotionManifest 只用于定位需要放大的单帧，不得只读 JSON 后宣布完成。Cubism 请求使用同一包装脚本的 cubism 命令族：直接导出走 cubism export；已有 Editor 工程的检查、预览或同步才走原 API 桥接计划。

输入获取也由外部 Agent 编排。原画生成后先展示并等待用户确认，再固定列出三种路线：推荐用户在指定 ModelScope 网页以 1024 自行上传并下载 PSD；用户选择偷懒选项后由 Agent 自动上传这张已确认原画；在线入口不可用时才推荐本地部署。选择 Agent 代传本身就是对本次具体上传的授权，不再重复询问；没有选择就不得上传。本地复核用户带回的 PSD 不等于本地部署 See-Through。本地安装、硬件门槛、已知问题和优化路线以 references/see-through-local-deployment.md 为真源；项目画风参考、唯一生图交接、1024 默认分辨率、单主体素材边界、上传副本和三档视觉验收以 references/source-art-and-layering.md 为真源。用户只要求“生成 PSD”“测试分层”或“看看 See-Through 是否可用”时，范围严格停在原图、实际上传副本、PSD、真实可见图层重组和已定稿的视觉结论；不得创建 PuppetLoom 项目、编写绑定规格或进入 agent plan/apply，除非用户随后明确要求继续制作。测试输入必须是真正打开检查过的正常日系二次元角色图，不能用抽象图或几何测试卡。实际生图继续由外部图像工具承担，不把模型、提示词引擎或 Agent 运行时塞进 PuppetLoom。参考视频和获准生成的姿态参考图只作观察证据，不进入 PSD、纹理或项目素材；最终运动范围仍服从原素材能支撑的透视。

用户要求创建完整角色时，先判断现有眼白、虹膜和睫毛能否支持几何眨眼；缺闭眼贴图不等于缺眨眼能力。只有几何闭合不能保持角色眼形、眼睛烘焙在脸部或目标需要特定手绘造型时，才补闭眼素材。一个张口等确实缺少的必要素材由外部 Agent 生成、检查并接入，不再逐项索取授权。已有闭嘴就是 mouthOpen=0，不得重画；微张嘴和音素嘴形只有用户明确需要对应表情或触发方式时才增加，不作为麦克风口型的默认状态。用户明确说“只使用现有素材”“不要生图”时才停止补素材并报告 needs-assets。生成闭眼前先确认睁眼结构是否独立；睁眼已经烘焙在脸部时，闭眼素材必须完整遮住原眼或先修 PSD，不能只叠两条眼线。闭眼和嘴形必须继承原画的线稿、睫毛体量、眼角、口腔配色、阴影和抗锯齿，不能用一条弧线或粗糙符号糊弄；完整规则见 references/visual-rigging-rules.md。

一次角色校准只属于当前项目。候选 revision 先做足以安全展示的定向检查并交给用户看；用户接受后用 evidence --project <directory> --session <id> --status accepted 记录，再运行获准范围内的完整回归或推送。任何相关 session 仍是 unreviewed 时只能称为候选，不能报告“完成”“已修好”或把它当成以后角色的模板；用户拒绝时，记录被否定的 session 和具体缺陷；需要撤回时只恢复受影响范围，不撤销其他有效工作。用户同时给出新方向或已授权继续修复时，重新看图并返修该项，不因拒绝旧候选而停止任务，也不把尚未解决的问题改记为接受。用户给出同一部位的新方向时，优先把结果反馈交给现有 Agent 或高层 authoring 入口，不要求用户指出顶点编号。多个独立项目反复出现同一错误，是修改 PuppetLoom 通用算法的充分证据但不是唯一入口；一个真实项目若已用代码与数据证明是可复用的软件缺陷，也可在增加通用 fixture、真实项目回归和非退化证据后修软件。角色专属顶点、轴心和权重仍留在项目校准中，不能升级成其它角色的默认几何。用户明确要求同步优化本 Skill 时，把已经验证的制作方法、入口变化和错误判断一并修正，检查主说明与各引用文件是否矛盾；不自动调用其它 Skill，也不对已获授权的修改重复询问。没有修改授权时只记录建议。修改前后运行 scripts/file_budget.py。