# live2d-puppet

Adopt this skill: https://proskills.md/skills/other/cheshiremew-puppetloom-skills-live2d-puppet

Page: https://proskills.md/skills/other/cheshiremew-puppetloom-skills-live2d-puppet
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/live2d-puppet/SKILL.md
size: 21856
sha: f4aa7d97e1845d5333e1b937de248831f0be457f
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/SKILL.md

```text
---
name: live2d-puppet
description: "使用 PuppetLoom 让外部 Agent 通过 CLI 从分层角色 PSD 创建或改善可动 2D 角色，可按整模或指定部位完成分析、网格与运动制作、自检、返修和准确 revision 的证据闭环；也用于检查关键形、权重、透视、次级运动与校准结果，通过 CLI 依次演示编辑器和角色窗口的真实功能，以及直接导出 Cubism 工程和运行时文件或使用 Editor 桥接。Use when an external agent such as Codex should create or improve a PuppetLoom character through the CLI, review exact-revision visual evidence, demonstrate the real editor and runtime under CLI control, or bridge a verified project to official Cubism runtime files. 不用于在桌面应用里内嵌 Agent 对话框、让用户默认承担逐点调网格、纯视频生成或没有相关角色/模型的普通图像编辑。"
---

# 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 必须明确项目根。按当前结果读取对应方法，不为一次局部修形加载全部制作流程：

| 当前任务 | 读取方法 |
| --- | --- |
| 从 PSD 创建角色或更新源 PSD | `references/from-zero-workflow.md` |
| 分部制作、检查与返修 | `references/agent-review-and-repair.md`；涉及形状或运动时加读 `references/visual-rigging-rules.md` |
| 原素材闭眼、脸缘和五官的目标修形 | `references/shape-target-workflow.md`；视觉标准沿用 `references/visual-rigging-rules.md` |
| 拆发、替换头饰等通用补件，或局部关键形修形 | `references/asset-and-geometry-workflow.md`；视觉判断沿用 `references/visual-rigging-rules.md` |
| 缺原图、See-Through 分层、源图错误 | `references/source-art-and-layering.md`；明确选择本地推理时再读 `references/see-through-local-deployment.md` |
| 录屏、编辑器和角色窗口演示 | `references/runtime-demonstration.md` |
| 用户接受、拒绝、手动校准或学习反馈 | `references/calibration-and-learning.md` |
| Cubism、moc3、model3 或官方工具兼容 | `references/cubism-bridge-workflow.md` |

使用 `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`。

## 资源

- `references/from-zero-workflow.md`：输入边界、完整 CLI 顺序、Agent-first 修改优先级、PSD 迁移、静态/动态证据检查和桌面交接。
- `references/source-art-and-layering.md`：从角色需求取得可绑定原图、官方在线 See-Through 默认交接、获准自动 API 与最后可选的本地部署边界、单条生图指令和 PSD 重组验收。
- `assets/blue-whale-maid-reference/`：项目长期参考素材；鲸鱼娘原画保留作可选观察参考，其可复用的正向画风已经写入原图流程，只有用户明确要求使用整张参考图时才进入生图上下文；分层 PSD、转头图和表情图只供分层、绑定和补表情时查看。
- `references/see-through-local-deployment.md`：本地 See-Through 的启用条件、C/D/E 盘环境检查、硬件与分辨率门槛、已知问题和后续优化顺序。
- `references/agent-review-and-repair.md`：外部 Agent 与软件的职责边界、结构化制作规格、看图—返修循环、缺陷路由和用户验收。
- `references/visual-rigging-rules.md`：从本项目历史中保留下来的结构、透视和次级运动判断。
- `references/shape-target-workflow.md`：角色结构标记、眼睑分区、脸形目标、两种目标变换、只读预览与按缺陷返修。
- `references/asset-and-geometry-workflow.md`：通用补件的参考、配准、试装与恢复，自然拆发和局部关键形的区域操作。
- `references/runtime-demonstration.md`：编辑器优先、角色窗口在后、公共 runtime CLI 控制、只读演示和可靠窗口保活。
- `references/calibration-and-learning.md`：用户校准如何进入项目、软件或 Skill，及其证据门槛。
- `references/cubism-bridge-workflow.md`：官方格式边界、参数映射、Editor 版本与授权、严格同步、侧车生成、最终目录和视觉验收。
- `scripts/invoke_puppetloom.ps1`：定位 PuppetLoom、必要时构建并原样转发包括 `psd repair/review/finalize` 在内的 CLI 命令和退出码。
- `scripts/acquire_layered_psd.ps1`、`scripts/acquire_layered_psd.py` 与 `scripts/finalize_psd_review.py`：通过 ModelScope See-Through 的公开 Gradio API 上传已获准原图，或在本地复核用户带回的原图和 PSD；生成原图与实际上传副本、归一化原图、带名称预览、真实可见图层重组、对照图、检查记录和一次传输重试证据，并确定性定稿三档视觉结论。它们不启动或安装本地 See-Through 推理服务。
- `requirements-layering.txt`：PSD 重组与对照图所需、已在 `D:\Tools\Python310` 验证的 Pillow 和 psd-tools 版本。
- `scripts/demo_puppetloom.ps1` 与 `scripts/demo_puppetloom.mjs`：通过 CLI 驱动真实 Electron 完成可录制的只读演示，并按需保持窗口。
- `scripts/file_budget.py`：Skill 自我修改前后的本地活动文本预算门槛。

## 输出与完成

PSD-only 任务返回同一个自包含运行目录，至少保留原图、实际上传副本、PSD、图层预览、`inspect`、真实图层重组对照、`visual-review.json` 和 `result.json`。Agent 必须实际看图，把结论记录为 `accepted`、`accepted-with-repairs` 或 `rejected`，再用 `scripts/acquire_layered_psd.ps1 -FinalizeReview` 校验并同步唯一结论；结构检查和数值差异不能代替视觉判断。`accepted-with-repairs` 只容纳不改变主要语义、轮廓和遮挡结构的小问题，并在用户明确接受携带这些问题时才进入创建；真正阻止可靠创建的问题进入 `blockingIssues` 并拒绝候选。完成 PSD-only 范围后立即停止，不返回项目目录或绑定规格。

创建任务返回项目目录、绑定等级、禁用功能和视觉证据路径；整模或分部任务返回 `scope`、自然语言目标、from/to revision、各部位的 `awaiting-visual-review/not-present/needs-assets/blocked` 状态、实际操作、前后对比、所采用的连续证据、最终 `verification`、总 `blockers` 和任务报告路径。用户问“这轮最新版”“都解决了吗”或“看看解决了哪些”时，先从完整任务、批注和纠正中重建需求清单，再对每项已批准要求沿同一条完成链核对：软件与公开 CLI 确实具备能力，普通默认路径或用户指定入口实际启用了它，规范项目的准确 revision 已保存对应数据，匹配该 revision 的视觉证据已经查看，依赖观感的结果已经交给用户判断，并且素材或官方工具边界已如实报告。完成链中任何一环没有成立，就只报告已经到达的层级和剩余工作，不能宣称整项完成；隐藏的可选开关、测试副本、产物目录和单独通过的 fixture 都不能代替正式用户路径与规范项目。已有项目只保留一个规范项目目录，以内部 revision、session 和证据历史作为版本真源，不复制 `project-rN` 目录冒充版本管理。交付前检查本任务的测试、生成、中间和最终文件都位于规范项目或当前仓库根目录内，再用桌面端 `edit` 或 `play` 实际打开该规范路径，并确认“最近项目”记录的是同一个绝对路径；只完成 CLI `create` 或打开了暂存副本都不算完成。只有 `verification.valid`、完整角色准确 revision 的 `performance.valid`、实际姿态与每个准确 revision 的允许证据都看过、报告中的项目指纹和窗口比例匹配、目标部位产生以源图像像素计可见而合理的运动、未点名区域和已接受结果没有明显退化、用户要求的角色窗口或编辑器链能够打开，才算普通项目结果在客观范围内成立。依赖观感的幅度、延迟和回弹在用户判断前只是待确认结果，不能因为自检全绿就宣称完成。

Cubism 直接导出任务还要返回源 revision、指纹、工程与运行时版本、参数 ID 映射、CMO3/model3 路径，以及 Core 和目标 Editor 的实际验证结果。`cubism export` 的 `awaiting-visual-review` 表示尚待看图；必须对照实际导出图集、UV、九向、闭眼及中间帧，在 Editor 打开并保存后才能报告对应范围通过。`cubism verify` 只证明目录结构和引用。API 桥接另行报告 Editor/API 状态、兼容计划、`strictReady` 和 blocking/warning；严格同步或用户已接受的 partial 结果仍需 Cubism Viewer 复核。需要用户判断时展示前后画面并说明具体变化，不用“应该好了”代替视觉证据。
```

## File: skills/live2d-puppet/scripts/acquire_layered_psd.ps1
size: 2041
sha: a28715f74d30d12cd9c51572b26dcd4548d78730
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/scripts/acquire_layered_psd.ps1

```text
[CmdletBinding()]
param(
  [Parameter(Position = 0)]
  [string]$InputImage,

  [ValidateRange(768, 1600)]
  [int]$Resolution = 1024,

  [ValidateRange(0, 9999)]
  [int]$Seed = 42,

  [switch]$SplitLimbs,

  [string]$ReviewPsd,

  [string]$FinalizeReview,

  [string]$OutputRoot,

  [string]$ServiceUrl = "https://ljsabc-see-through.ms.show",

  [ValidateRange(30, 3600)]
  [int]$TimeoutSeconds = 900,

  [switch]$Check
)

$ErrorActionPreference = "Stop"
if ([string]::IsNullOrWhiteSpace($OutputRoot)) {
  $OutputRoot = Join-Path $PSScriptRoot "..\runtime\see-through"
}
$pythonPath = "D:\Tools\Python310\python.exe"
if (-not (Test-Path -LiteralPath $pythonPath)) {
  $pythonPath = (Get-Command python.exe -ErrorAction Stop).Source
}

$scriptPath = Join-Path $PSScriptRoot "acquire_layered_psd.py"
$pythonArguments = @($scriptPath)

if ($Check -and -not [string]::IsNullOrWhiteSpace($FinalizeReview)) {
  throw "Check and FinalizeReview are mutually exclusive."
}

if ($Check) {
  $pythonArguments += "--check"
} elseif (-not [string]::IsNullOrWhiteSpace($FinalizeReview)) {
  if (-not [string]::IsNullOrWhiteSpace($InputImage) -or -not [string]::IsNullOrWhiteSpace($ReviewPsd)) {
    throw "InputImage and ReviewPsd cannot be used with FinalizeReview."
  }
  $pythonArguments += @("--finalize-review", (Resolve-Path -LiteralPath $FinalizeReview).Path)
} else {
  if ([string]::IsNullOrWhiteSpace($InputImage)) {
    throw "InputImage is required unless -Check is used."
  }
  $resolvedInput = (Resolve-Path -LiteralPath $InputImage).Path
  $pythonArguments += $resolvedInput
  if (-not [string]::IsNullOrWhiteSpace($ReviewPsd)) {
    $pythonArguments += @("--review-psd", (Resolve-Path -LiteralPath $ReviewPsd).Path)
  }
  if ($SplitLimbs) {
    $pythonArguments += "--split-limbs"
  }
}

$pythonArguments += @(
  "--resolution", $Resolution,
  "--seed", $Seed,
  "--output-root", [System.IO.Path]::GetFullPath($OutputRoot),
  "--service-url", $ServiceUrl,
  "--timeout", $TimeoutSeconds
)

& $pythonPath @pythonArguments
exit $LASTEXITCODE
```

## File: skills/live2d-puppet/scripts/acquire_layered_psd.py
size: 35955
sha: ace35140d14257b19ab9e69da0f6c3df8c594595
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/scripts/acquire_layered_psd.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/scripts/acquire_layered_psd.py

## File: skills/live2d-puppet/scripts/demo_puppetloom.mjs
size: 13688
sha: 766d7dd59655a77971506dccaa5667f4ada6a690
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/scripts/demo_puppetloom.mjs

```text
import { execFile } from "node:child_process";
import { mkdir } from "node:fs/promises";
import { join, normalize, resolve } from "node:path";
import { promisify } from "node:util";
import { _electron as electron } from "playwright";

const execFileAsync = promisify(execFile);

function parseArguments(argv) {
  const options = { paceMs: 320, keepOpen: false };
  for (let index = 0; index < argv.length; index += 1) {
    const argument = argv[index];
    if (argument === "--keep-open") options.keepOpen = true;
    else if (argument === "--root") options.root = argv[++index];
    else if (argument === "--project") options.project = argv[++index];
    else if (argument === "--revision") options.revision = Number(argv[++index]);
    else if (argument === "--pace") options.paceMs = Number(argv[++index]);
    else throw new Error(`未知参数：${argument}`);
  }
  if (!options.root || !options.project) throw new Error("必须提供 --root 和 --project。" );
  if (!Number.isInteger(options.paceMs) || options.paceMs < 120 || options.paceMs > 2000) throw new Error("--pace 必须是 120 到 2000 之间的整数毫秒。" );
  if (options.revision !== undefined && (!Number.isInteger(options.revision) || options.revision < 0)) throw new Error("--revision 必须是非负整数。" );
  return options;
}

function emit(value) {
  process.stdout.write(`${JSON.stringify(value)}\n`);
}

function samePath(left, right) {
  const canonical = (value) => normalize(resolve(value)).replace(/[\\/]+$/, "").toLocaleLowerCase("en-US");
  return canonical(left) === canonical(right);
}

function parseJson(output, label) {
  try { return JSON.parse(output); }
  catch { throw new Error(`${label} 没有返回有效 JSON：${output.slice(0, 500)}`); }
}

const options = parseArguments(process.argv.slice(2));
const root = resolve(options.root);
const project = resolve(options.project);
const wrapper = join(root, "skills", "live2d-puppet", "scripts", "invoke_puppetloom.ps1");
const desktopMain = join(root, "apps", "desktop", "dist", "electron", "main.js");
const runProfile = join("D:\\Tools", "PuppetLoom", "agent-demo", `${Date.now()}-${process.pid}`);
const runtimeManifest = join(runProfile, "runtime-control.json");
const runtimeEnvironment = { PUPPETLOOM_ROOT: root, PUPPETLOOM_CONTROL_MANIFEST: runtimeManifest };
const delay = (milliseconds) => new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));

async function runCli(arguments_, environment = {}) {
  const { stdout } = await execFileAsync("powershell.exe", [
    "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", wrapper, ...arguments_
  ], {
    cwd: root,
    env: { ...process.env, ...environment },
    encoding: "utf8",
    windowsHide: true,
    maxBuffer: 16 * 1024 * 1024
  });
  return stdout.trim();
}

async function cliJson(arguments_, environment = {}) {
  return parseJson(await runCli([...arguments_, "--json"], environment), arguments_.join(" "));
}

async function waitForRuntimeViewer() {
  let lastError;
  for (let attempt = 0; attempt < 80; attempt += 1) {
    try {
      const inspection = await cliJson(["runtime", "inspect"], runtimeEnvironment);
      const viewer = inspection.viewers?.find((candidate) => samePath(candidate.projectDirectory, project));
      if (viewer) return { inspection, viewer };
    } catch (cause) { lastError = cause; }
    await delay(250);
  }
  throw new Error(`角色窗口启动后仍未出现在 runtime inspect 中${lastError ? `：${lastError.message}` : "。"}`);
}

async function setRange(locator, value) {
  await locator.evaluate((element, nextValue) => {
    const setValue = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
    setValue?.call(element, String(nextValue));
    element.dispatchEvent(new Event("input", { bubbles: true }));
    element.dispatchEvent(new Event("change", { bubbles: true }));
  }, value);
}

const historyBefore = await cliJson(["history", "--project", project]);
const revision = options.revision ?? historyBefore.currentRevision;
if (revision !== historyBefore.currentRevision) {
  throw new Error(`编辑器演示必须使用规范项目当前 revision；当前为 ${historyBefore.currentRevision}，请求为 ${revision}。`);
}

await mkdir(runProfile, { recursive: true });
let electronApp;
let viewerId;
const sourceId = `agent-demo-${process.pid}`;

try {
  electronApp = await electron.launch({
    args: [desktopMain, "--edit", "--project", project],
    cwd: root,
    env: {
      ...process.env,
      ELECTRON_DISABLE_SECURITY_WARNINGS: "true",
      PUPPETLOOM_ALLOW_MULTIPLE: "1",
      PUPPETLOOM_E2E_USER_DATA: runProfile
    }
  });

  const editor = await electronApp.firstWindow();
  editor.on("pageerror", (cause) => process.stderr.write(`[editor pageerror] ${cause.message}\n`));
  await editor.getByTestId("editor").waitFor({ timeout: 30_000 });
  await editor.waitForFunction(() => {
    const canvas = document.querySelector(".editor-canvas");
    return canvas instanceof HTMLCanvasElement && canvas.width > 0 && canvas.height > 0;
  }, undefined, { timeout: 30_000 });

  const baseline = await editor.evaluate((directory) => window.puppetloom.readEditorWorkspace(directory), project);
  if (baseline.calibration.revision !== revision) throw new Error(`编辑器实际打开 revision ${baseline.calibration.revision}，预期 ${revision}。`);
  const baselineDraft = JSON.stringify(baseline.draft ?? null);
  emit({ demo: "editor-ready", project, revision, paceMs: options.paceMs });

  const navigation = editor.getByRole("navigation", { name: "编辑工作区" });
  const openWorkspace = async (name, pattern) => {
    await navigation.getByRole("button", { name: pattern }).click();
    await editor.waitForTimeout(options.paceMs);
    emit({ demo: "editor-workspace", name });
  };

  await openWorkspace("01 项目总览", /01 项目总览/);
  await openWorkspace("02 结构与网格", /02 结构与网格/);
  const meshButton = editor.getByRole("button", { name: "网格与权重", exact: true });
  await meshButton.click();
  await editor.waitForTimeout(options.paceMs);
  const autonomousPreview = editor.getByRole("button", { name: "自主预览", exact: true });
  if (await autonomousPreview.count()) {
    await autonomousPreview.click();
    await editor.waitForTimeout(options.paceMs * 2);
    await editor.getByRole("button", { name: "暂停动作", exact: true }).click();
  }
  await meshButton.click();

  await openWorkspace("03 参数与姿态", /03 参数与姿态/);
  for (const pose of ["头部姿态 -0.88, 0", "头部姿态 0.88, 0", "头部姿态 0, -0.82", "头部姿态 0, 0.82", "头部姿态 0, 0"]) {
    await editor.getByRole("button", { name: pose, exact: true }).click();
    await editor.waitForTimeout(Math.max(120, Math.round(options.paceMs * 0.75)));
  }

  await openWorkspace("04 表情与物理", /04 表情与物理/);
  const expressionRange = editor.locator(".dynamics-inspector section").first().locator('input[type="range"]').first();
  if (await expressionRange.count()) {
    await setRange(expressionRange, 0.8);
    await editor.waitForTimeout(options.paceMs);
    await setRange(expressionRange, 0);
  }
  const behaviorButtons = editor.locator(".system-catalog section").last().locator("button");
  if (await behaviorButtons.count()) {
    await behaviorButtons.first().click();
    const playBehavior = editor.locator(".dynamics-inspector .transport-row").getByRole("button", { name: "播放", exact: true });
    if (await playBehavior.count()) {
      await playBehavior.click();
      await editor.waitForTimeout(options.paceMs * 2);
      const pauseBehavior = editor.locator(".dynamics-inspector .transport-row").getByRole("button", { name: "暂停", exact: true });
      if (await pauseBehavior.count()) await pauseBehavior.click();
    }
  }

  await openWorkspace("05 预览与验收", /05 预览与验收/);
  const previewSamples = editor.locator(".preview-sample-list button");
  for (let index = 0; index < Math.min(7, await previewSamples.count()); index += 1) {
    await previewSamples.nth(index).click();
    await editor.waitForTimeout(Math.max(120, Math.round(options.paceMs * 0.6)));
  }
  for (const background of ["深色", "浅色", "透明"]) {
    await editor.locator(".segmented-control").getByRole("button", { name: background, exact: true }).click();
    await editor.waitForTimeout(Math.max(120, Math.round(options.paceMs * 0.7)));
  }

  const viewerPromise = electronApp.waitForEvent("window", { timeout: 30_000 });
  await editor.getByRole("button", { name: "运行角色窗口", exact: true }).click();
  const viewerPage = await viewerPromise;
  viewerPage.on("pageerror", (cause) => process.stderr.write(`[viewer pageerror] ${cause.message}\n`));
  await viewerPage.getByTestId("viewer").waitFor({ timeout: 30_000 });
  await viewerPage.waitForFunction(() => {
    const canvas = document.querySelector("canvas");
    return canvas instanceof HTMLCanvasElement && canvas.width > 0 && canvas.height > 0;
  }, undefined, { timeout: 30_000 });

  const { viewer } = await waitForRuntimeViewer();
  viewerId = viewer.id;
  if (viewer.revision !== undefined && viewer.revision !== revision) throw new Error(`runtime inspect 返回 revision ${viewer.revision}，预期 ${revision}。`);
  emit({ demo: "viewer-ready", viewerId, revision: viewer.revision ?? revision, expressions: viewer.expressions.length, behaviors: viewer.behaviors.length });

  const setPose = async (name, values) => {
    const arguments_ = ["runtime", "set", "--viewer", String(viewerId), "--source", sourceId];
    for (const [flag, value] of Object.entries(values)) arguments_.push(`--${flag}`, String(value));
    arguments_.push("--priority", "90", "--ttl", String(Math.max(1000, options.paceMs * 5)));
    await cliJson(arguments_, runtimeEnvironment);
    emit({ demo: "runtime-pose", name });
    await delay(options.paceMs);
  };

  await setPose("向左", { "head-yaw": -0.85, "body-sway": -0.35, "body-roll": -0.12, "gaze-x": -0.45 });
  await setPose("向右", { "head-yaw": 0.85, "body-sway": 0.35, "body-roll": 0.12, "gaze-x": 0.45 });
  await setPose("抬头", { "head-pitch": -0.75, "body-pitch": -0.2, "gaze-y": -0.4 });
  await setPose("低头", { "head-pitch": 0.75, "body-pitch": 0.2, "gaze-y": 0.4 });
  await setPose("侧倾", { "head-roll": -0.65, "body-roll": -0.2 });
  await setPose("眨眼张嘴", { blink: 1, "mouth-open": 0.8 });
  await setPose("回到中立", { "head-yaw": 0, "head-pitch": 0, "head-roll": 0, "body-sway": 0, "body-pitch": 0, "body-roll": 0, "gaze-x": 0, "gaze-y": 0, blink: 0, "mouth-open": 0 });

  for (const expression of viewer.expressions.slice(0, 2)) {
    await cliJson(["runtime", "trigger", "--viewer", String(viewerId), "--source", sourceId, "--expression", expression.id, "--duration", String(Math.max(500, options.paceMs * 2)), "--priority", "90"], runtimeEnvironment);
    emit({ demo: "runtime-expression", id: expression.id, name: expression.name });
    await delay(Math.max(500, options.paceMs * 2));
  }

  const preferredBehaviorIds = ["action-nod", "action-wave-left", "action-body-bounce", "action-ear-flick", "action-tail-wag"];
  const selectedBehaviors = [];
  for (const id of preferredBehaviorIds) {
    const behavior = viewer.behaviors.find((candidate) => candidate.id === id);
    if (behavior) selectedBehaviors.push(behavior);
  }
  for (const behavior of viewer.behaviors) {
    if (selectedBehaviors.length >= 5) break;
    if (!selectedBehaviors.some((candidate) => candidate.id === behavior.id)) selectedBehaviors.push(behavior);
  }
  for (const behavior of selectedBehaviors) {
    await cliJson(["runtime", "trigger", "--viewer", String(viewerId), "--source", sourceId, "--behavior", behavior.id, "--priority", "90"], runtimeEnvironment);
    emit({ demo: "runtime-behavior", id: behavior.id, name: behavior.name });
    await delay(Math.min(1400, Math.max(options.paceMs * 2, Math.round(behavior.duration * 650))));
  }

  await cliJson(["runtime", "release", "--viewer", String(viewerId), "--source", sourceId], runtimeEnvironment);
  viewerId = undefined;

  const workspaceAfter = await editor.evaluate((directory) => window.puppetloom.readEditorWorkspace(directory), project);
  const historyAfter = await cliJson(["history", "--project", project]);
  if (workspaceAfter.calibration.revision !== revision || historyAfter.currentRevision !== revision) throw new Error("演示过程中项目 revision 发生了变化。" );
  if (JSON.stringify(workspaceAfter.draft ?? null) !== baselineDraft) throw new Error("演示过程中校准草稿发生了变化。" );
  if (editor.isClosed() || viewerPage.isClosed()) throw new Error("演示结束前窗口已经关闭。" );

  emit({ demo: "ready", project, revision, editor: true, viewer: true, keepOpen: options.keepOpen, runtimeReleased: true, profile: runProfile });
  if (options.keepOpen) await electronApp.waitForEvent("close", { timeout: 0 });
  else await electronApp.close();
} catch (cause) {
  if (viewerId !== undefined) {
    try { await cliJson(["runtime", "release", "--viewer", String(viewerId), "--source", sourceId], runtimeEnvironment); }
    catch { /* The viewer may already be gone. */ }
  }
  const message = cause instanceof Error ? cause.stack ?? cause.message : String(cause);
  process.stderr.write(`${message}\n`);
  emit({ demo: "failed", project, revision, keepOpen: options.keepOpen, windowsKeptOpen: Boolean(options.keepOpen && electronApp) });
  process.exitCode = 3;
  if (options.keepOpen && electronApp) await electronApp.waitForEvent("close", { timeout: 0 });
  else if (electronApp) await electronApp.close();
}
```

## File: skills/live2d-puppet/scripts/demo_puppetloom.ps1
size: 1331
sha: 7fdec0da76498b3fc57318573e291dab65e4b516
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/scripts/demo_puppetloom.ps1

```text
[CmdletBinding()]
param(
  [Parameter(Mandatory = $true)]
  [string]$Project,

  [ValidateRange(0, 2147483647)]
  [int]$Revision = -1,

  [ValidateRange(120, 2000)]
  [int]$PaceMs = 320,

  [switch]$KeepOpen
)

$ErrorActionPreference = "Stop"
$puppetLoomRoot = if ($env:PUPPETLOOM_ROOT) { $env:PUPPETLOOM_ROOT } else { "E:\Code\PuppetLoom" }
$puppetLoomRoot = (Resolve-Path -LiteralPath $puppetLoomRoot).Path
$projectPath = (Resolve-Path -LiteralPath $Project).Path
$nodePath = "D:\Tools\NodeJS\node.exe"

if (-not (Test-Path -LiteralPath $nodePath)) {
  $nodePath = (Get-Command node.exe -ErrorAction Stop).Source
}

$cliPath = Join-Path $puppetLoomRoot "apps\cli\dist\index.js"
$desktopPath = Join-Path $puppetLoomRoot "apps\desktop\dist\electron\main.js"
if (-not (Test-Path -LiteralPath $cliPath) -or -not (Test-Path -LiteralPath $desktopPath)) {
  $npmPath = (Get-Command npm.cmd -ErrorAction Stop).Source
  & $npmPath run build --prefix $puppetLoomRoot
  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
}

$arguments = @(
  (Join-Path $PSScriptRoot "demo_puppetloom.mjs"),
  "--root", $puppetLoomRoot,
  "--project", $projectPath,
  "--pace", [string]$PaceMs
)
if ($Revision -ge 0) { $arguments += @("--revision", [string]$Revision) }
if ($KeepOpen) { $arguments += "--keep-open" }

& $nodePath @arguments
exit $LASTEXITCODE
```

## File: skills/live2d-puppet/scripts/file_budget.py
size: 2532
sha: 74b89a6ace17c4fbad88a6312eeccc133cf2db07
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/scripts/file_budget.py

```text
#!/usr/bin/env python3
"""Check every active UTF-8 text file in this Skill against the local budget."""

from __future__ import annotations

import os
import sys
from dataclasses import dataclass
from pathlib import Path

MAX_OUTER_TOOL_TOKENS = 9_000
BYTES_PER_OUTER_TOOL_TOKEN = 4
IGNORED = {
    ".git", ".pytest_cache", ".ruff_cache", ".venv", "__pycache__",
    "archive", "artifacts", "build", "dist", "node_modules", "output",
    "outputs", "runtime", "venv",
}
TEXT_ASSET_SUFFIXES = {".csv", ".json", ".md", ".toml", ".tsv", ".txt", ".xml", ".yaml", ".yml"}

@dataclass(frozen=True)
class FileBudget:
    path: Path
    byte_count: int
    estimated_tokens: int

def estimate_outer_tool_tokens(byte_count: int) -> int:
    return (byte_count + BYTES_PER_OUTER_TOOL_TOKEN - 1) // BYTES_PER_OUTER_TOOL_TOKEN

def collect_file_budgets(root: Path) -> list[FileBudget]:
    records: list[FileBudget] = []
    for current, directories, files in os.walk(root):
        directories[:] = sorted(name for name in directories if name not in IGNORED)
        for name in sorted(files):
            path = Path(current) / name
            relative = path.relative_to(root)
            if relative.parts and relative.parts[0] == "assets" and path.suffix.lower() not in TEXT_ASSET_SUFFIXES:
                continue
            data = path.read_bytes()
            try:
                data.decode("utf-8")
            except UnicodeDecodeError:
                continue
            records.append(FileBudget(relative, len(data), estimate_outer_tool_tokens(len(data))))
    return sorted(records, key=lambda item: item.path.as_posix())

def validate_file_budgets(root: Path) -> list[str]:
    return [
        f"{item.path.as_posix()} exceeds {MAX_OUTER_TOOL_TOKENS} estimated tokens ({item.estimated_tokens})"
        for item in collect_file_budgets(root)
        if item.estimated_tokens > MAX_OUTER_TOOL_TOKENS
    ]

def main() -> int:
    root = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
    records = collect_file_budgets(root)
    for item in sorted(records, key=lambda value: (-value.estimated_tokens, value.path.as_posix())):
        print(f"{item.estimated_tokens:>6} tokens  {item.byte_count:>7} bytes  {item.path.as_posix()}")
    errors = validate_file_budgets(root)
    if errors:
        print("FILE BUDGET FAIL")
        for error in errors:
            print(f"- {error}")
        return 1
    print(f"FILE BUDGET PASS {root}")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())
```

## File: skills/live2d-puppet/scripts/finalize_psd_review.py
size: 7891
sha: 8e8289d8945206b619c6c338500501e78723bd12
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/scripts/finalize_psd_review.py

```text
from __future__ import annotations

import hashlib
import json
import secrets
from datetime import datetime, timezone
from pathlib import Path
from typing import Any

class ReviewFinalizationError(RuntimeError):
    pass

def _read_object(path: Path, label: str) -> dict[str, Any]:
    try:
        value = json.loads(path.read_text(encoding="utf-8"))
    except json.JSONDecodeError as error:
        raise ReviewFinalizationError(f"{label} is not valid JSON: {path}") from error
    if not isinstance(value, dict):
        raise ReviewFinalizationError(f"{label} must contain a JSON object: {path}")
    return value

def _sha256(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as source:
        while chunk := source.read(1024 * 1024):
            digest.update(chunk)
    return digest.hexdigest()

def _atomic_write(path: Path, value: Any) -> None:
    temporary = path.with_name(f".{path.name}.{secrets.token_hex(4)}.tmp")
    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
    temporary.replace(path)

def _file(value: Any, label: str) -> Path:
    if not isinstance(value, str) or not value.strip():
        raise ReviewFinalizationError(f"{label} path is missing")
    path = Path(value).resolve(strict=True)
    if not path.is_file():
        raise ReviewFinalizationError(f"{label} is not a file: {path}")
    return path

def _validate_evidence(review_path: Path, review: dict[str, Any], result: dict[str, Any]) -> None:
    recorded_review = result.get("reviewEvidence", {}).get("visualReview")
    if not isinstance(recorded_review, str) or Path(recorded_review).resolve() != review_path:
        raise ReviewFinalizationError("result.json does not point to this visual-review.json")
    views = review.get("requiredViews")
    if not isinstance(views, dict):
        raise ReviewFinalizationError("visual-review.json is missing requiredViews")
    for key in ("sourceNormalized", "recomposition", "comparison", "previewIndex"):
        _file(views.get(key), f"requiredViews.{key}")
    if views.get("previewContactSheet") is not None:
        _file(views["previewContactSheet"], "requiredViews.previewContactSheet")

    psd = _file(result.get("psd"), "result.psd")
    if _sha256(psd) != result.get("psdSha256"):
        raise ReviewFinalizationError("PSD hash no longer matches result.json")
    source = result.get("source")
    if not isinstance(source, dict):
        raise ReviewFinalizationError("result.json is missing source provenance")
    original = _file(source.get("sourceOriginal"), "result.source.sourceOriginal")
    if _sha256(original) != source.get("sha256"):
        raise ReviewFinalizationError("Original source hash no longer matches result.json")

def _validate_checks(review: dict[str, Any], status: str) -> None:
    checks = review.get("checks")
    if not isinstance(checks, list) or not checks:
        raise ReviewFinalizationError("visual-review.json is missing checks")
    required = {
        "face-and-eyes",
        "hair-and-headwear",
        "clothing-and-limbs",
        "layer-order-and-occlusion",
        "background-and-alpha",
        "overall-recomposition",
    }
    found: set[str] = set()
    values: list[str] = []
    for index, check in enumerate(checks):
        if not isinstance(check, dict):
            raise ReviewFinalizationError(f"checks[{index}] must be an object")
        check_id = check.get("id")
        value = check.get("status")
        if not isinstance(check_id, str) or not check_id:
            raise ReviewFinalizationError(f"checks[{index}].id is missing")
        if value not in {"pass", "repair", "fail", "not-applicable"}:
            raise ReviewFinalizationError(f"checks[{index}].status must be pass, repair, fail, or not-applicable")
        found.add(check_id)
        values.append(value)
    missing = sorted(required - found)
    if missing:
        raise ReviewFinalizationError(f"visual-review.json is missing required checks: {missing}")
    if "fail" in values and status != "rejected":
        raise ReviewFinalizationError("A failed visual check requires rejected status")
    if "repair" in values and status == "accepted":
        raise ReviewFinalizationError("A repair visual check requires accepted-with-repairs or rejected status")

def finalize_review(review_value: str | Path) -> dict[str, Any]:
    review_path = Path(review_value).resolve(strict=True)
    if review_path.name.lower() != "visual-review.json":
        raise ReviewFinalizationError("--finalize-review must point to visual-review.json")
    result_path = review_path.parent / "result.json"
    if not result_path.is_file():
        raise ReviewFinalizationError(f"Matching result.json is missing: {result_path}")

    review = _read_object(review_path, "visual-review.json")
    result = _read_object(result_path, "result.json")
    if result.get("ok") is not True:
        raise ReviewFinalizationError("Only a successful PSD acquisition or local review can be finalized")
    _validate_evidence(review_path, review, result)

    status = review.get("status")
    allowed = {"accepted", "accepted-with-repairs", "rejected"}
    if status not in allowed:
        raise ReviewFinalizationError(f"Review status must be one of {sorted(allowed)}")
    _validate_checks(review, status)
    blockers = review.get("blockingIssues", [])
    repairs = review.get("repairPlan", [])
    if not isinstance(blockers, list) or not isinstance(repairs, list):
        raise ReviewFinalizationError("blockingIssues and repairPlan must be arrays")
    if status != "rejected" and blockers:
        raise ReviewFinalizationError(f"{status} cannot contain blockingIssues")
    if status == "accepted" and repairs:
        raise ReviewFinalizationError("Use accepted-with-repairs when repairPlan is not empty")
    if status == "accepted-with-repairs" and not repairs:
        raise ReviewFinalizationError("accepted-with-repairs requires a non-empty repairPlan")
    if status == "rejected" and not blockers:
        raise ReviewFinalizationError("rejected requires at least one blocking issue")

    reviewed_at = review.get("reviewedAt")
    if not isinstance(reviewed_at, str) or not reviewed_at.strip():
        reviewed_at = datetime.now(timezone.utc).isoformat()
    reviewer = review.get("reviewer")
    if not isinstance(reviewer, str) or not reviewer.strip():
        reviewer = "external Agent"
    ready = status != "rejected"
    review.update(
        acceptedForNextStage=ready,
        reviewedAt=reviewed_at,
        reviewer=reviewer,
        rule="The external Agent visually decides accepted, accepted-with-repairs, or rejected. This finalized record is authoritative; structural inspect and numeric metrics cannot decide it.",
    )
    next_step = {
        "accepted": "PSD-only task complete. The reviewed PSD is ready if the user later asks to create a PuppetLoom project.",
        "accepted-with-repairs": "PSD-only task complete. Carry the recorded repair plan into any later project and complete it before final delivery.",
        "rejected": "PSD-only task complete. Do not create a project from this rejected candidate; repair the PSD or acquire another candidate.",
    }[status]
    result.update(
        stage="psd-visual-review-finalized",
        readyForCreate=ready,
        visualReviewStatus=status,
        blockingIssues=blockers,
        repairPlan=repairs,
        reviewedAt=reviewed_at,
        reviewer=reviewer,
        next=next_step,
    )
    _atomic_write(review_path, review)
    _atomic_write(result_path, result)
    return {
        "ok": True,
        "stage": "psd-visual-review-finalized",
        "runDirectory": str(review_path.parent),
        "status": status,
        "readyForCreate": ready,
        "visualReview": str(review_path),
        "result": str(result_path),
    }
```

## File: skills/live2d-puppet/scripts/invoke_puppetloom.ps1
size: 1417
sha: 9017b94a0afec99eef221837d7921e353f70cedd
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/scripts/invoke_puppetloom.ps1

```text
[CmdletBinding()]
param(
  [Parameter(Mandatory = $true, Position = 0)]
  [ValidateSet("capabilities", "assets", "inspect", "create", "verify", "describe", "migrate", "render", "performance", "psd", "agent", "author", "actions", "calibrate", "compare", "history", "restore", "evidence", "enhance", "record", "play", "edit", "runtime", "cubism", "extensions")]
  [string]$Command,

  [Parameter(ValueFromRemainingArguments = $true)]
  [string[]]$Arguments
)

$ErrorActionPreference = "Stop"
$puppetLoomRoot = if ($env:PUPPETLOOM_ROOT) { $env:PUPPETLOOM_ROOT } else { Join-Path $PSScriptRoot "..\..\.." }
$puppetLoomRoot = (Resolve-Path -LiteralPath $puppetLoomRoot).Path
$cliPath = Join-Path $puppetLoomRoot "apps\cli\dist\index.js"
$nodePath = if ($env:PUPPETLOOM_NODE) { (Resolve-Path -LiteralPath $env:PUPPETLOOM_NODE).Path } else { (Get-Command node.exe -ErrorAction Stop).Source }

$buildScript = Join-Path $puppetLoomRoot "scripts\build-cli.mjs"
if (-not (Test-Path -LiteralPath $buildScript)) { throw "PUPPETLOOM_ROOT must contain scripts/build-cli.mjs." }
$buildCheck = & $nodePath $buildScript --check
if ($LASTEXITCODE -ne 0) {
  [Console]::Error.WriteLine("CLI build is missing or stale; building current source.")
  & $nodePath $buildScript | ForEach-Object { [Console]::Error.WriteLine($_) }
  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
}

& $nodePath $cliPath $Command @Arguments
exit $LASTEXITCODE
```

## File: skills/live2d-puppet/references/agent-review-and-repair.md
size: 14460
sha: 2ed9e165be8c0782cfd33e86cd89e6155bc1444c
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/agent-review-and-repair.md

````text
# 外部 Agent 看图、制作与返修

## 职责边界

用户要求增强制作能力或借鉴其它项目时，先按目标部位比较同一素材的实际效果与实现，再选择要改的地方。脸部看中立、左右、上下和斜向组合，分清整体体积、五官修形及遮挡；头发先分开检查随头转动与惯性摆动。记录参考的具体方法、当前缺陷、采用或不采用的理由，并用同素材前后画面验证。参数名字和范围相同不代表角度或运动相同，须注明方向、幅度和渲染入口。测试与工具改进不能代替制作效果，某一部位完成后继续处理原任务剩余部位，不把整模任务收窄成反复修一个局部。

外部 Agent 负责理解用户说的“自然、克制、活泼、跟紧、柔软”等结果目标，决定处理哪些部位，实际查看基线和修改后的图像/连续帧，判断轮廓、体积、遮挡、连接、节奏和角色原有效果是否成立，并据此决定下一轮数值或更高层结构修改。这里的 Agent 是 Codex、Claude 等通过 CLI 操作项目的外部执行者，不是 PuppetLoom 桌面应用里的聊天框或常驻运行时。

PuppetLoom 负责读取 PSD 和项目、生成结构化规格模板、验证明确的数值与图层、制作网格/关键形/物理、执行安全检查和有限的确定性收敛、提交 revision、生成准确证据、检测并发冲突以及恢复历史。软件不得用几条关键词正则冒充自然语言理解，也不得把结构安全检查说成审美判断。

## 正式规格合同

先为当前 revision 生成模板：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 agent specification --project E:\Puppets\Character --scope whole --json
```

模板的 `kind` 固定为 `puppetloom-rig-spec`，`scope` 明确区分 `whole` 与 `selected`，`baseRevision` 绑定当前项目，`parts` 只包含项目实际存在且本轮获准处理的部位，并列出当前稳定 `layerIds`。整模计划仍必须逐项报告全部职责：不存在的部位标为 `not-present`，规格漏掉实际存在的部位则停止，不能静默使用默认值。外部 Agent 必须在看过基线、局部图层和 `describe --layer` 后修改 `goal`、填写角色专属 `anatomy`、每个部位的 `intent` 和 `rationale`，再保存为 JSON。模板数值只是安全起点，不能原样当成“已经理解用户”；`layerIds` 不能沿用旧角色或为了省事删掉，自动目标不精确时必须以本次项目的稳定 ID 修正。

`anatomy` 必须描述本次角色，而不是复制另一角色的网格代码。头脸至少记录双眼、鼻、嘴与下巴的实际控制点，倾斜或不对称原画不能被拉平成镜像模板；嘴部同时记录 `mouthLeft/mouth/mouthRight` 和实际嘴型网格修正。前发与后发按画面中的发帽、刘海、侧锁、卷发和呆毛职责写实际轴心与发束，权重数组长度必须匹配当前 ArtMesh。左右耳分别记录各自图层、连接根和覆盖全部网格顶点的 `physicsRelease`，不能共享一个镜像动作；头饰和上衣同样要明确固定区与自由区。每个头饰图层必须显式写 `headwearPerspective: "crown"` 或 `null`：只有真正的宽皇冠/冠带结构选择 crown，月牙夹、发卡、链坠和窄吊饰选择 null。`agent plan` 会按当前 revision 核对这些覆盖，空对象、局部顶点样例或无关字段不能通过。

主运动部位使用 `amplitude/response/stability`。前发额外使用 `ahogeAmplitude/ahogeResponse/ahogeStability/lagResponse/lagDamping/deformationScale`；其它次级运动使用 `lagResponse/lagDamping/deformationScale`。幅度表示目标可见度，response 表示跟随速度，stability 和 lagDamping 控制收敛与回弹，lagResponse 控制物理追赶速度，deformationScale 控制局部关键形变形。裙摆还可使用 `garmentStructure` 区分软垂布料与保体积支撑结构，并用 `garmentFlexibility` 单独控制支撑结构中下段的受限弹性。支撑类型、整体摆动速度和局部柔性是三个独立判断：“塌陷”先修结构，“太慢”调 response/lag，“太硬”调 flexibility，不能靠降低摆幅把软布伪装成裙撑，也不能靠锁死整件裙子维持体积。`rationale` 必须写看到了什么和为什么这样改，不能只复述数字。

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 agent plan --project E:\Puppets\Character --spec E:\Puppets\rig-spec-r0.json --json
& <skill>\scripts\invoke_puppetloom.ps1 agent apply --project E:\Puppets\Character --spec E:\Puppets\rig-spec-r0.json --json
```

`plan` 必须返回 `inputMode: structured-specification`。规格 revision 过期、同一部位重复、参数越界、目标图层不存在、anatomy 未覆盖当前网格或范围与用户目标不符时停止并重新观察，不通过改 `baseRevision` 强行套用旧判断。`--instruction/--scope` 是只读旧调用兼容入口；没有 `--spec` 的 `apply` 必须被拒绝，正式外部 Agent 流程不依赖软件解析自然语言。

生成规格前以当前项目为真源，检查目标部位的稳定 layer ID、语义角色、`alphaTopology`、连接区域、轴心、已有绑定以及每个参数实际驱动的图层。以前角色、参考素材或历史规格只能帮助观察，不能默认继承部件关系、运动方向或物理响应。用户指出当前角色的分层或连接与以前不同，或质疑两个部件是否仍被连带驱动时，即使 `plan` 全绿，也先用 `describe` 和实际参数输入检查结构与耦合，再决定是改规格、做项目校准还是修软件；不要先靠缩小幅度掩盖语义错误。

## 看图—返修循环

1. 在任何写入前运行 `history/verify/describe/render`，按用户允许的形式选择 `play` 或 `record`，并实际打开基线姿态、整体动作和次级运动证据。先记录 accepted session 对应的角色原有效果、实际存在部位和不能退化的区域。
2. 生成当前 revision 的规格模板。外部 Agent 依据用户目标、基线和刚核对的当前结构选择部位、填写数值和理由，运行只读 `plan`，核对目标图层、素材状态、草稿、检查项和阻断项。
3. 在获准的工作项目执行 `apply`。每个完成部位都有独立 from/to revision；整模后续部位阻断不会自动撤销已提交 revision，因此逐项核对 session 与 `history`。实际打开全部 `focusComparisonSheet` 和 4×4 `focusMotionSheet`，检查前后差异与完整连续运动。只有需要定位某一帧时才读取 `focusMotionManifest`。不能只打开整模缩略图，也不能只读 JSON。
4. 给每个部位作出明确视觉判断：`accept`、`repair`、`needs-assets`、`not-present` 或 `blocked`。判断至少覆盖中立一致性、近大远小、根部/关节连接、自由端形变、遮挡穿插、回正连续性、回弹次数与未点名区域退化。失败项必须指出具体部位、姿态或连续帧、看到的现象和对应证据；不能只给出“通过多少项”的计数。
5. 若只是幅度、速度、阻尼或局部变形量不合适，在当前 revision 重新生成模板，填写新的结构化规格并再跑一轮。若参数关系、关键形或物理图结构不够表达，升级到 `author inspect/apply`；只有少量已知顶点、轴心或权重需要修正时才用 `describe --layer` 与稀疏 `calibrate`。不要为了回避 Agent 判断去扩建桌面手工编辑器。
6. 每轮返修都重新查看准确 to revision 的静态和连续证据。目标成立且没有明显退化才停止；同一可见缺陷经过一轮合理参数返修仍基本不变时，不再反复猜幅度或降低阈值，转入下面的根因检查。确认现有 CLI 或素材确实无法表达后，恢复最后可接受 revision，把真实阻断报告给用户。

## 重复缺陷的根因检查

把同一位置的源 Alpha、neutral 状态 ArtMesh、目标姿态下的网格/轮廓边界和最终实际像素并排比较，确认问题最早在哪一层出现。再检查图层语义、`alphaTopology`、根部与铰链、长边界边、局部权重、关键形方向、遮挡顺序和证据阈值。`plan` 全绿只说明规格在当前结构假设下满足已有检查，不证明语义关系本身正确。目标运动量以源图像像素计算；归一化参数变化、网格节点移动或亚像素差异本身不证明观众能看到运动。若根因在可复用的网格、语义或变形算法，按软件缺陷处理并增加通用测试；若只与该 PSD 的局部几何有关，留在项目校准。

同一个 ArtMesh 或纹理可能同时包含头皮、中央刘海、侧发、呆毛、双耳或头饰。共享网格不等于共享语义、根部和运动：先按 Alpha 连通区域、连接结构和视觉职责划分语义区，再分别约束稳定体积、随头结构和自由端次级运动。不要因为它们位于同一图层就让整个网格同幅平移、旋转或回弹。

## 卡顿与动作停顿的区分

用户说“卡”“顿一下”“跟不上”时，先对当前规范项目的准确 revision 运行 `performance`，不要先猜显卡，也不要拿固定 fixture 的结果代替。活动态和暂停态都出现相近的 p95/p99 或长帧，优先判断为窗口、系统调度或测量环境问题；暂停态稳定而只有活动态失败，判断为 PuppetLoom 渲染、模型求值、临时对象或 GPU 上传路径问题，先修软件并用同一项目复测。两者都通过但视觉仍像停住，说明帧没有丢，问题在动作事件的硬保持、响应速度、稳定性、回正曲线或次级运动节奏；实际查看 `play` 或用户允许的连续证据，再修改规格或通用动作曲线。不能用降低运动幅度掩盖掉帧，也不能用性能全绿否定用户看到的机械停顿。

报告时把事实分开写清：`active/paused` 帧时间证明是否掉帧，`renderCpu` 帮助定位活动渲染开销，连续画面证明动作是否硬停或响应过慢。`diagnosis.frameDropSource` 是基于活动/暂停对照的程序判断，不替代 Agent 对动作节奏的视觉判断。性能修复后必须在同一 revision 再测，不能只跑通用基准；动作修复后必须查看进入、停顿、回正三个阶段的连续性，不能只看极值姿态。

## 缺陷如何路由

- 原画或 PSD 已缺失主要结构、语义分错、画布错位，或前后内容粘在同一图层造成遮挡错误：停止绑定，按原画与分层流程把候选标为 `rejected`。若内容完整且只是几个独立图层顺序错误，记录明确的 layer ID 和相对关系，创建后使用 `move-layer` authoring 操作形成可恢复 revision，再看中立和动作证据；不要直接改项目 JSON 或源 PSD。
- 整体方向、角色气质、运动节奏或审美幅度不对：外部 Agent 改结构化规格。
- 图层语义、Alpha 部件、根部/铰链或自动目标识别错误：先用 `describe` 取证；跨多个项目重复，或单个项目已经用通用代码路径和可复现数据证明算法根因时，修 PuppetLoom 算法并补通用 fixture，否则在规格中限定图层或做项目校准。
- 关键形关系、参数维度、变形器层级、表达式或物理图不够：外部 Agent 使用 `author inspect/apply`，PuppetLoom 只验证并提交明确操作。
- 单个关键形的局部轮廓偏差：按 `asset-and-geometry-workflow.md` 使用分页 `author geometry` 与区域 `transform-keyform`；轴心或权重偏差继续用稀疏 `calibrate`，保留 from/to 证据。
- 已授权的拆发、头饰或其它素材替换：按 `asset-and-geometry-workflow.md` 准备参考、配准并尽早试装，先区分摆放、遮挡、绑定和素材绘制问题，再决定重画。
- 先判断闭眼是否真的缺素材：左右眼白与睫毛完整时，眼部制作入口可从原图生成几何闭合关键形，以眼白遮罩隐藏虹膜，不必补画闭眼图。先看半闭、全闭和转头组合中的睫毛形状、厚度与眼角，再决定是否采用；有自定义眨眼绑定时保留并检查父级，不能叠加两套闭合。需要特定手绘闭眼造型时可使用贴图模式，切换时保留关键形。张口等确实缺少的原画素材，经验证后通过 `enhance` 接入；已有闭嘴不重画。微张嘴或音素嘴形只有用户明确需要时才增加。不能以“缺闭眼贴图”直接判定角色不能眨眼，也不能以参数有变化代替画面检查。
- 结构和安全检查全绿但画面难看、僵硬或破坏原效果：仍判为 `repair` 或失败；这是外部 Agent 必须承担的视觉判断。

## 给用户的验收

`agent apply` 成功执行后返回 `status: awaiting-visual-review`、`visualReview: unreviewed`；`ok: true` 只代表本次制作命令执行成功。分部报告的 `executionStatus: succeeded` 同样不代表造型合格。外部 Agent 必须根据准确 revision 的原画、局部阶段图、整体图和连续动作作出视觉判断；无需新增内置模型或聊天服务。报告一旦指出具体造型缺陷，该项就保持未通过，修复并重新看图后才能改变结论。历史制作报告保留执行时状态，用户接受后的状态以对应校准 session 为准，不把 Agent 自检冒充用户接受。

先展示候选角色窗口或准确 revision 的前后/连续效果，再报告完成部位、缺失部位、素材边界和仍需用户判断的观感。每个未通过项说明它在什么姿态或帧出现、画面具体哪里不对、证据在哪里以及当前能否修复；不要只报告检查计数。候选接受后才把对应 session 标为 `accepted` 并运行完整回归；拒绝后标记受影响 session 和具体缺陷；撤回只针对相关变化。用户已授权继续返修或给出新方向时，修正目标再预览，不自动停止整个任务。不要把测试清单当作主要交付。用户不满意时先接收“哪里看起来不对”的结果反馈，由 Agent 自己定位部位和参数；只有 CLI 不能表达的局部问题才邀请用户手调。

闭眼或头脸需要实际修形时使用 `shape-target-workflow.md` 的结构标记、目标点/曲线及只读预览。先核对像素职责，再看目标和实际输出；不能把默认生成器当作针对人物的造型判断。
````

## File: skills/live2d-puppet/references/asset-and-geometry-workflow.md
size: 9495
sha: c1adb9ea0ea868fd0a346c12d3085bc8f6390acb
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/asset-and-geometry-workflow.md

```text
# 补件与局部修形

参考方案只有在相同原画、相同动作输入的前后动态对照中改善观感，才能替换当前方案。无翻折、坐标误差小、静态九向正确都不等于脸部运动自然。观察脸颊、下巴与五官的相对关系是否随动作反复拉长、缩短或滑动；先隔离左右、上下转动，再检查正常速度下的组合。极限往复用于暴露问题，不能冒充日常展示，也不能只放慢录像掩盖变形。用户指出观感变差时，撤销此前的“通过”结论，保留失败候选作对照；不因已经投入开发或来源是参考项目就继续推为默认。

本方法只使用 `capabilities` 实际公开的 CLI，不内置模型调用。用户限制现有素材时只检查已有内容；已授权制作需要的补件由宿主当前可用的图像工具生成，不把特定供应商名称或机器路径当成能力保证。

## 参考与配准

先 `assets reference --project <目录> --layer <模板ID> --json`。返回的 cleanPath 是干净原素材，contextPath 是完整角色，annotationPath 标明原素材范围；标注图只用于说明，不能把框线生成到补件里。记录 reference ID、baseRevision、sourceRect 和画布。给生成器说明要保留的线稿、配色、接触阴影，以及这次真正需要改变的部分。

当前登记入口接受 PNG 并保留其 Alpha，不自动去除纯色底或棋盘格。优先要求真实透明 PNG；若宿主只能输出纯色底，先通过可用的确定性去底工具获得透明 PNG，再检查边缘。不能把“PNG 格式”或一张棋盘背景图当成透明成功。

生成器保留了声明画框时，用 frame 配准。generatedRect 是原始生成 PNG 中的内容框，sourceRect 是该框在原画布中的目标像素矩形；尺寸不同不等于目标角色需要缩放，非等比拉伸必须明确 allowStretch。生成器重新居中、旋转或改变留白时，用 landmarks 配准：在原始 PNG 与源画布中标记对应点，至少两点，优先根部、尖端和不共线的侧边第三点。查看 rmsErrorPixels；不要为了通过而放大容差。镜像必须明确 mirrorX/mirrorY，不能用翻转掩盖错误对应点。

调用 `assets register --project <目录> --reference <ID> --image <原始PNG> --registration <JSON> --json`。记录不可变 registration ID；调整位置时从同一原始 PNG 创建新配准，不反复缩放已处理结果。超出角色画布会被拒绝，不会自动裁掉素材。坐标统一按像素边界、左上原点、X 向右、Y 向下解释。

## 尽早试装再决定是否重画

用 assembly JSON 指定当前 baseRevision、additions（registrationId、未占用的 layerId，可选 name/order）和 replaceLayerIds。`assets preview --assembly <JSON>` 生成整个人物的前后姿态证据而不推进当前 revision；替换列表里的旧图层在候选中隐藏，不删除源图。新增图层继承模板的父级、部位响应和经空间重投影的关键形/权重，仍须实际看中性与转向画面。

先按正常观看尺寸看组合，再放大定位问题。位置、比例、旋转、镜像或留白不对时修配准；遮挡不对时修顺序或替换列表；根部漂移时查父级和局部固定权重；只有素材本身画错才重新生成。孤立部件很像原图不代表组合正确，隐藏区域的小差异也不自动构成返工理由。

试装成立后 `assets apply --plan <ID>`，它校验版本与素材哈希后通过现有校准事务写入。版本变化时重新准备参考和试装，不能手改旧计划的 baseRevision。查看实际 session 和证据，用户接受后才标 accepted；拒绝沿现有 history/restore 恢复。恢复保留原始 PNG、配准和历史，不手工删文件。

## 自然拆发

按发束走势、根部和前后穿插拆分，不把像素连通域直接等同于一束头发，也不为了绑定方便切成整齐条带。同一逻辑发束可能需要多个绘制片段才能表达交错遮挡；多个片段共用运动判断，不能给每块可见岛随机独立摆动。每束保留被遮挡处必要的连续体积，并保持原有接触阴影。

先装回完整角色检查轮廓、根部衔接和前后关系，再制作专属摆动。先验证自然组合成立，再调幅度和滞后；转动之后露出的缺口才是需要补画的证据。源 PSD 的整体结构已损坏时仍回到源图修复，不用大量补件遮住未知问题。

## 局部关键形

需要从原图定义眼睑或脸形目标时，先读 `shape-target-workflow.md`：用 `author inspect-shape` 核对坐标和像素职责，使用 `fit-landmarks` / `curve-warp` 制作目标，`author preview` 看标记、结果与中间姿态后再写入。已有区域平移、缩放与平滑仍按下述方法处理。

制作前先根据当前原画确定目标形状，再选择工具。眼部至少明确内外眼角、原眼线倾斜、睫毛尖端和厚度；左右眼分别判断，眼白、虹膜遮罩与睫毛共同闭合。优先从原眼部连续变形，用户要求原图变形时不能借闭眼补图替代制作。程序自动生成的曲线只是初稿；出现折角、眼角拉长、重影或眼线体量丢失，就继续修关键形，不以无翻折作为通过。三角形跨度无法承载曲线时，局部调整网格并保留原画 UV、已有权重和其它关键形，避免把网格外包络当成笔画。半闭、全闭、重新睁开分别检查，并在上下与左右转头时复核连接。

角色专属的眼角位置、曲线与脸部修形写入角色的关键形数据，通过 `author apply` / `calibrate` 保存；不把这个人物的数值加入通用默认值。头脸制作返回的 `measurements` 是观察数据，不能为了追求某个近远眼比例或下半脸伸缩比而强行修改原画。保持清楚的头脸、表情、物理职责，按实际目标修正，不因另一软件也采用某公式就默认接受。

完整头部九向关键形与程序化左右/上下转动是同一动作的两种来源，不能直接叠加。只有已经制作完整 yaw/pitch 关键形的图层，才在同一 `author apply` 事务中提交 `{ "op": "set-layer-head-pose", "layerId": "实际ID", "mode": "keyforms" }`；它关闭该层的程序化 yaw/pitch，保留 headRoll、表情、视线与次级运动。`mode: procedural` 恢复程序化路径，不删除关键形，因此恢复前也须处理同轴绑定，避免再次叠加。局部修形仍使用默认程序化路径，不因一个局部关键形就切换完整头部来源。

同层只保留一个完整 yaw/pitch 双参数头部绑定，表情先求值再随这个表面转动。补充张口图与备用闭眼图也要跟随同一脸部表面。合并同轴绑定前先查物理图：直接输入与延迟输出组成的惯性差值必须成对保留，不能因直接输入也是 yaw 就吞进造型。停止后检查两项抵消，运动中检查滞后。已有完整关键形时，通过 `author apply` 修改它，不能继续调用程序化头脸制作并把参数变化当成效果改善。闭眼必须检查中立和转头组合中的三角形方向，仅凭睁眼九向图或没有报错不足以通过。

参考的眼白闭合建立在规则列网格上，不能直接把同一细弧线压缩套到任意轮廓三角网。若中立闭眼已翻折，先处理眼白网格；通过现有 `calibrate` 每次修改一层，重投影该层所有关键形，再重建闭合端点。规则网格恢复原纹理坐标会改变原来的局部中立修形，必须对照睁眼原画和转头，不可声称外观完全不变。现有眼部制作会保留已有闭合绑定；修复时须明确 upsert 更新，不能只重跑制作命令。

转移已验证的同素材参考姿态时，按原画坐标和源网格三角形采样位移，保留中立网格，不能按顶点编号直接复制。完整头部位移写入后核对旧 yaw/pitch 绑定；兼容的纯几何增量应合并成一个清楚的主绑定，并检查端点及半程输出不变，不长期留下两组数值相互抵消。混有表情、物理、透明度或不同轴的绑定不能盲目合并。参考不存在的补充嘴形和闭眼图另行检查连接，不宣称它们也已经得到参考验证。

`author geometry --binding <ID> --values <按轴顺序的值> --revision <n> --offset 0 --limit 64` 按需分页；它返回实际三角网格或 warp 网格，nativeBezier 为 false。rest/position 是父级变换之前的归一化画布坐标，不能把屏幕截图坐标直接填进去。

通过 `author apply` 的 operations 提交 `transform-keyform`，明确 bindingId、已有关键形 values、coordinateSpace: rest-canvas、selection 和有序 transforms。选区支持 all、indices、rect、circle、line；柔化在选区内部发生，整个操作期间选区按中性几何固定。translate/scale/rotate/bend/smooth 的字段和单位见当前项目 `docs/AGENT_USAGE.md`；smooth 默认保留外轮廓与孔洞边界。保留当前稀疏增量，不反复累加同一旧指令。

缺少关键值时先使用 `insert-binding-key` 插入完整行/列，保持原插值再局部修改。结果仍须核对其他关键形、未点名区域、准确版本的静态与连续运动；工具调用成功不等于画面自然。接口超时后先读取 history 和当前 revision，确认是否已提交，再决定重试，不能盲目重放修改。
```

## File: skills/live2d-puppet/references/calibration-and-learning.md
size: 4769
sha: 21dee5116986d212abef4ff3efd92b19659d4498
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/calibration-and-learning.md

```text
# 校准证据与学习

## 三种改进对象

项目校准保存某个角色的事实：一个控制点、轴心、网格顶点或权重怎样调整后更自然。软件算法保存跨角色稳定成立的自动推导。Skill 保存 Agent 如何选择工具、检查证据和决定升级层级。三者不能混写。

用户在桌面编辑器保存一次修改后，`calibration/sessions` 会记录前后覆盖、补丁、指纹和 revision，`reports/calibration` 会记录姿态、运动、前后拼图和差异。Agent 用 `history/compare` 读取它们，不要求用户重新描述拖了哪个点。用户的“接受/拒绝”要写入该 session，形成带结果判断的证据。

Agent 自动制作产生的 revision 和 session 走同一条证据链。用户通常只需判断角色结果，并用自然语言说明幅度、延迟、回弹、穿插或轮廓哪里不合适；正式的部位 Agent 或高层 authoring 能承接时直接使用这份反馈，不把它翻译成“请用户自己找点并拖动”。只有公开能力确实无法表达的局部问题才交给桌面校准。

用户拒绝后标记受影响 session 为 `rejected` 并记录具体问题，不能把旧候选当作通过。需要撤回时只撤回相关变化，复核未点名结果没有被撤销；用户已授权继续修复或提出新方向时，根据新证据修正目标并预览，不重复套用失败参数，也不自动停止整个任务。使用 `record` 时，动态证据还要保存报告中的项目路径、基础 SHA-256、准确 revision、启动时当前 revision 和窗口比例，不能从文件名推测它属于哪个状态；用户不要视频时改用准确 revision 的高清静态、4×4 连续帧和实时窗口，不把 `record` 设成接受/拒绝的前提。

## 从项目到软件

一个角色的接受记录本身不足以修改通用自动绑定算法，但“至少两个项目”不是绝对前置条件。升级软件默认需要证明根因位于可复用的代码、语义识别或几何算法，而不是该角色专属顶点：多个独立项目重复出现同一错误是充分证据；单个真实项目若能用通用代码路径、可复现输入和因果对照证明同样的算法缺陷，也可以修软件。两种情况都必须把修复写成可识别语义而非角色专用顶点列表，增加通用 fixture 或最小复现，并在现有测试 PSD、该真实项目和相关非退化证据上验证。不能证明通用根因时，修改留在项目校准。这个门槛不阻止 Skill 调用用户已经明确批准、软件已经公开提供并经过真实项目验证的整模或分部 Agent 入口，但 Skill 必须准确报告请求 scope、各部位状态、素材缺口和阻断项。修改软件前保存可恢复的代码基线，修改后运行类型检查、构建、单元/集成、Electron 用户链、视觉和性能测试。推送远端只在用户授权范围内执行。

算法问题示例：同类侧发总被归入后发、合并头饰的左右耳根持续定位反了。项目问题示例：某张 PSD 的呆毛根部比 Alpha 自动估计高两个网格点。后者留在项目，不能硬编码进所有角色。

## 从项目到 Skill

只有用户明确要求优化未来 Agent 行为或同步项目 Skill 时才修改 Skill；不自动启用其它 Skill。适合 Skill 的证据是制作判断或流程反复犯错，例如只相信测试不看图、把上下看做整体平移、擅自把参考视频加入项目、把一次角色校准当成通用规律。视觉算法本身应改软件，不应塞进更长的提示词来掩盖。

修改 Skill 前先运行 `scripts/file_budget.py <skill-directory>`，说明将改哪些规则及理由；用户已授权同步优化时直接执行，未授权时只提出建议。同步检查主说明、制作流程和视觉规则，不能只改一个引用文件而留下相反指令。修改后运行预算与相关契约检查；只有命令入口发生变化才验证对应 CLI。若任何活动文本超过 9,000 估算 tokens，按单一职责拆分并更新路由，不能删掉必要能力来过门槛。

## 证据最小记录

每次向用户汇报至少包含项目路径、点名部位与自然语言目标、from/to revision、相关 session ID、修改的稳定 ID、参数或 Agent 操作、前后对比路径、采用的静态/实时/动态证据及指纹、安全检查结果和仍未解决的视觉问题。差异图只定位变化，最终判断必须看角色图和对应 revision 的允许证据；还要说明目标部位是否真的产生以源图像像素计可见的连续运动、根部是否稳定，以及未点名区域和历史 accepted 结果是否出现退化。没有实际查看证据时不得说“已经修好”。
```

## File: skills/live2d-puppet/references/cubism-bridge-workflow.md
size: 9377
sha: 283be251c919dda7c898b2feeb3dfc25f627afb7
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/cubism-bridge-workflow.md

````text
# Cubism 官方格式桥接

## 直接导出 CMO3 / MOC3

用户要求一键双格式导出时，使用这一条路线，不要要求先在 Editor 重新建模。首次在 PuppetLoom 根目录运行 `node scripts/setup-cubism-exporter.mjs`，使用固定版本的 PSD2Live/Umamo 依赖；随后通过包装脚本调用：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 cubism export --project E:\Puppets\Character --output E:\Puppets\Character-cubism --editor-version 5.3 --runtime-version 5.0 --json
```

工程目标默认 Editor 5.3.01 起，运行时目标默认 SDK 5.0；两者独立选择。保留源 revision、指纹、参数 ID 映射、输出文件及 `export-status.json`。图集按原像素组成二次幂页面，不能把小图层 PNG 直接当 Cubism 图集。导出只转换当前造型，不自动修复原项目的错误造型；原程序化层级转换为可编辑网格关键形。

返回 `awaiting-visual-review` 后，用 `node scripts/check-native-export.mjs <导出目录> <项目目录>` 运行本机官方 Core，对照顶点、透明度、UV、拓扑和实际导出图集的画面。在目标 Editor 中打开、检查和另存 CMO3，再通过 Editor 导出 MOC3；把其 model3 路径追加到上述命令，检查 `qa-editor` 中的九向与闭眼对照。不要重排图集后仍按原 UV 逐值比较。原画贴图位置与动作关键形必须分别保留，不能用变形后的默认网格反推原画位置。不能拿同一转换库自己读回成功，或只拿原纹理重画成功，代替真正导出文件的视觉验证。`cubism verify` 也不代表画面通过。

以下章节仅描述原有 Editor API 交接路线，不能把其顶点写入限制套用到直接编码导出。

这条流程用于把 PuppetLoom 项目交给 Live2D Cubism 官方运行时，不替代 PuppetLoom 自身项目，也不绕过 Cubism Editor。公开 JSON 可以由 PuppetLoom 生成、合并和检查；专有 `finalize` 的输入 `.moc3` 必须由 Cubism Editor 官方导出。Cubism Core 是读取运行库，不是公开的 moc3 编译器。

## 能力和停止边界

PuppetLoom 可以生成 `.exp3.json`、`.motion3.json`、`.physics3.json` 和 `.cdi3.json`，读取并合并 Editor 导出的 `.model3.json`，复制其 moc、纹理和其它引用，并检查引用边界、缺失文件、JSON、纹理解码和 `MOC3` 文件头。它也可以连接 Editor External API，读取授权、模型、参数和对象，在一个可回滚事务中同步参数、参数关键点及 API 公开的 ArtMesh/变形器属性。

External API 1.1.0 当前没有写入 ArtMesh 顶点坐标或 Warp 控制点坐标的操作，也不能完整表达 PuppetLoom 的程序化面部表面、网格位移、平移和非等比缩放。遇到这些内容时，`plan` 必须输出 blocking issue，默认同步在 `EditBegin` 前停止。不能把“参数已经创建”“model3 引用有效”或“MOC3 文件头存在”说成网格已经转换或视觉已经等价。

`--allow-partial` 会同步仍可写的参数和属性，同时留下网格由用户在 Editor 中完成。只有用户明确接受这个结果边界时才使用；返回的 `partial: true`、blocking 和 warnings 进入交付记录，不能在汇报时省略。

## 版本、授权和输入

结构同步要求 Editor 支持 External API 1.1.0；当前对应 Cubism Editor 5.4 alpha 或后续提供同一 API 的版本。5.3.03 可以检查连接、读取参数、临时预览、清除预览、验证文件和打开 Viewer，但不能执行 1.1.0 结构编辑。先用 `editor inspect` 读取实际能力，不只根据安装目录猜版本。

首次连接需要在 Editor 的“外部应用程序集成的设置”中启用服务并授予 Allow；结构同步还要授予 Edit，当前模型必须处于 Modeling 模式。PuppetLoom 不自动安装 Editor/SDK、不替用户接受许可，也不分发 Cubism Core。授权 Token 默认属于 `%LOCALAPPDATA%\PuppetLoom\cubism-editor-token.txt`，CLI JSON 不输出 Token；用户需要其它位置时传 `--token-file`。

桥接的必要输入是一个已经验证的 PuppetLoom 项目。最终导出还需要 Cubism Editor 从对应角色正式导出的 `.model3.json`、`.moc3`、纹理及其侧车。ArtMesh 最好与原 PSD 图层同名；名称不能唯一匹配时严格同步停止，不猜目标对象。

## 先分析，不先承诺

统一通过包装脚本调用：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 cubism plan --project E:\Puppets\Character --json
& <skill>\scripts\invoke_puppetloom.ps1 cubism prepare --project E:\Puppets\Character --output E:\Puppets\Character-cubism-work --json
```

`plan` 不写文件，先读取当前有效 revision，返回参数映射、binding 覆盖、expression/motion/physics 数量和 issues。`strictReady: true` 只表示当前 PuppetLoom 内容没有已知 blocking；它仍不代替 Editor 导出和 Viewer 检查。`prepare` 输出必须是尚不存在的新目录，生成映射、兼容报告和 JSON 侧车，不生成 `.moc3`。`puppetloom/cubism-bridge.json` 是本次桥接记录。

只要用户问“能否兼容”或“还缺什么”，运行 `plan` 后解释实际覆盖即可，不需要先启动 Editor。只有用户要求检查一个已有官方运行时文件时，可以直接运行 `cubism verify --model <model3.json> --json`；这不需要 PuppetLoom 项目。

## Editor 检查和参数预览

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 cubism editor inspect --json
& <skill>\scripts\invoke_puppetloom.ps1 cubism editor preview --project E:\Puppets\Character --pose left --json
& <skill>\scripts\invoke_puppetloom.ps1 cubism editor preview --project E:\Puppets\Character --pose blink --json
& <skill>\scripts\invoke_puppetloom.ps1 cubism editor clear-preview --json
```

`inspect` 的 `approved`、`editApproved`、`editApiAvailable`、`modelUid`、`editMode`、parameters、objects 和 warnings 决定下一步。`preview` 使用稳定的 `SetParameterValues` 临时缓存，可检查 `neutral/left/right/up/down/blink/mouth`，不修改模型文件；检查完成后运行 `clear-preview`。

## 严格事务同步

支持 API 1.1.0 且权限、模式和当前模型都正确后运行：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 cubism editor sync --project E:\Puppets\Character --json
```

同步前再次读取计划和 Editor 当前结构。同 ID 参数范围或默认值不一致、目标 ArtMesh 不能唯一匹配、项目包含不可写几何或程序化变形时，严格模式停止，不静默改写。真正写入时全部操作位于一个 `EditBegin/EditEnd` 事务；任一步失败以 `EditEnd { Cancel: true }` 回滚。成功结果记录 applied/skipped operations，失败不能靠部分 Editor 状态冒充完成。

## 标准参数映射

| PuppetLoom 语义 | Cubism 参数 | 换算 |
| --- | --- | --- |
| head-yaw / head-pitch / head-roll | `ParamAngleX/Y/Z` | 原值乘 30 |
| body-sway / body-pitch / body-roll | `ParamBodyAngleX/Y/Z` | 原值乘 10 |
| gaze-x / gaze-y | `ParamEyeBallX/Y` | 原值 |
| breath | `ParamBreath` | 负值裁到 0 |
| blink | `ParamEyeLOpen`、`ParamEyeROpen` | `1 - value` |
| mouth-open | `ParamMouthOpenY` | 原值 |

自定义参数使用稳定的 `ParamPuppetLoom...` ID。命名表情以默认值为基准生成 Add 差值；行为轨道生成 motion 曲线；PuppetLoom 参数弹簧只能转换成 physics3 的近似，必须在 Viewer 中复核幅度和响应。

## Editor 导出后的最终目录

同步并人工补齐不可写网格后，由 Cubism Editor 使用官方导出生成 moc、model3 和纹理。不要用占位 moc 或手写二进制替代。然后整理到一个尚不存在的新目录：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 cubism finalize `
  --project E:\Puppets\Character `
  --editor-model E:\CubismExport\Character.model3.json `
  --output E:\Puppets\Character-cubism-runtime `
  --json

& <skill>\scripts\invoke_puppetloom.ps1 cubism verify --model E:\Puppets\Character-cubism-runtime\Character.model3.json --json
& <skill>\scripts\invoke_puppetloom.ps1 cubism open --model E:\Puppets\Character-cubism-runtime\Character.model3.json
```

`finalize` 不改 Editor 导出目录、不覆盖现有目标。它在旁路暂存目录复制全部原引用，合并 PuppetLoom expression、motion、physics 和 display-info，通过结构验证后才发布；失败时返回并保留暂存路径，不能把它当作成功目录。

`cubism verify` 只证明 model3 Version、目录内引用、JSON、纹理和 MOC3 文件头成立，不能读取 moc3 内部顶点或证明视觉等价。最终还要在 Cubism Viewer 中实际打开，检查中立、左右、上下、眨眼、嘴部、已有表情、动作和物理。若 `strictReady: false`，只有用户明确接受的 partial 范围可以交付，不能改称完整官方模型转换。

## 交付记录

向用户返回 PuppetLoom 项目路径和 source revision、Editor/API 状态、兼容计划路径或 JSON、`strictReady`、blocking/warning、同步是否 partial、Editor 官方 model3/moc3 来源、最终 model3 路径、`verification.valid` 和 Viewer 实际检查结果。结构验证与视觉验收分开写；尚未安装支持 1.1.0 的 Editor、未授予 Edit、未由 Editor 导出 moc3 或未看 Viewer 时，准确停在对应边界。
````

## File: skills/live2d-puppet/references/from-zero-workflow.md
size: 30002
sha: a5f43601334da0ea1d1246b67c0225d6e1462636
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/from-zero-workflow.md

````text
# 从零创建与复核

## 输入边界

理想输入是一张原始角色图和由它直接生成的 See-Through 分层 PSD。原图用于检查分层重组是否改变角色，PSD 是 PuppetLoom 的必要运行素材。只有 PSD 也可继续，但要报告没有原图作为重组一致性参考。只有原图时先展示确认，再列出三种选择：推荐用户在 `https://modelscope.cn/studios/ljsabc/See-Through/?st=1WIdxVcPQ8ylM43-0Vr14FQ` 以 1024 自行上传、下载 PSD；用户选择偷懒选项后由 Agent 代传当前已确认图片；在线入口不可用时才推荐本地部署。完全没有角色图时，把当前身份、角色设计和项目画风参考直接交给图像模型，取得完成度正常且关键部件可辨的日系二次元原画，实际打开检查并展示给用户，等待确认后再列出这三种路线。不把普通 PNG 改后缀或自行猜层当成分层结果，也不用抽象图或几何测试卡代替正式二次元角色输入。

合适的角色原图为日系二次元单人半身或全身，头部基本端正，脸部基本对称，双眼自然睁开，闭口中立，关键部位没有严重遮挡。人物可以有轻微动态，不限定头身比，也不能为了分层擅自做矮或做成 Q 版。PSD 至少应尽量提供脸、双眼、虹膜/睫毛、眉毛、前发、后发、脖子和上身。缺层时软件会降级，不要把“还能运行”说成“完整语义绑定”。复杂伴生角色只用于压力测试或独立素材，不与正式人物分层结果混为一体。

自动拆层不会替代验收。下载后先验证确实是 PSD，再运行 `inspect`，查看图层预览，并强制从 PSD 实际可见图层重新合成，不能信任内置预览图。把同画布归一化原图、重组图、白底/深色底和差异图一起查看。单独检查从后到前的图层顺序：后裙应在裸露腿后，腿在前裙后，后发在脖子和脸后，眉毛在脸前；实际设计不同则以原画为准。若只是完整独立图层顺序错误，记录为 `accepted-with-repairs`，创建后用 `move-layer` 形成可恢复 revision；若前后结构已粘在同一层，或核心五官/身体区域缺失、第二主体串层、严重错位、有效 Alpha 大面积污染、PSD 无法读取，则拒绝并停止，不转为孤立部件生图、绿幕抠图或代码拼接。呆毛、小配饰、少量边缘残留、孤立噪点和轻微颜色变化等不改变主要轮廓与遮挡的问题也可后修。结构检查和数值差异不能替代视觉结论。

用户只要求生成 PSD、测试 See-Through 或检查分层质量时，在保存原图副本、实际上传副本、PSD、预览、`inspect`、重组对照和 `accepted/accepted-with-repairs/rejected` 三档记录后停止。Agent 填写 `visual-review.json` 后必须通过 `acquire_layered_psd.ps1 -FinalizeReview` 校验并同步 `result.json`，不得手工维护两份互相独立的结论。不得创建项目、编写绑定规格或调用 `agent plan/apply`。只有用户明确要求继续制作角色且分层视觉验收成立，才把原图传给 `create --reference` 并进入后续 CLI 顺序。

## CLI 顺序

统一通过 `scripts/invoke_puppetloom.ps1` 调用：

开始前先确定本次唯一的规范根目录。任务已经有明确的 PuppetLoom 项目或代码仓库时，输入副本、PSD 修复运行目录、生成素材、规格、迁移候选、测试产物、报告、截图、录屏和最终文件全部写在该根目录内的 `artwork/work/requests/reports/archive` 等职责目录中，不在下载目录、仓库旁边或临时盘另建任务根目录。机器依赖、包缓存和桌面应用用户数据不属于项目产物，可以留在统一工具目录。尚无项目时先在用户指定的仓库或父目录中确定将成为规范项目的目录，再以它作为后续输出边界；下面的盘符只是占位示例。

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 inspect --input E:\Input\character.psd --json
& <skill>\scripts\invoke_puppetloom.ps1 create --input E:\Input\character.psd --reference E:\Input\character.png --output E:\Puppets\Character --seed 42 --json
& <skill>\scripts\invoke_puppetloom.ps1 verify --project E:\Puppets\Character --json
& <skill>\scripts\invoke_puppetloom.ps1 describe --project E:\Puppets\Character --json
& <skill>\scripts\invoke_puppetloom.ps1 render --project E:\Puppets\Character --output E:\Puppets\Character\reports\agent-baseline --suite calibration --revision 0 --size 1080 --focus whole --json
& <skill>\scripts\invoke_puppetloom.ps1 performance --project E:\Puppets\Character --output E:\Puppets\Character\reports\performance-r0 --revision 0 --json
& <skill>\scripts\invoke_puppetloom.ps1 record --project E:\Puppets\Character --output E:\Puppets\Character\reports\agent-motion-r0 --mode autonomous --revision 0 --json
& <skill>\scripts\invoke_puppetloom.ps1 record --project E:\Puppets\Character --output E:\Puppets\Character\reports\agent-secondary-r0 --mode secondary --revision 0 --json
```

### 创建前需要修 PSD 时

运行前先确认 Photoshop 没有在使用。包装脚本检测到任何已运行的 Photoshop 进程时，必须在连接 COM、改变窗口状态或打开文档之前拒绝执行；不得为了自动化隐藏、退出或复用用户当前会话。自动化结束时只有其会话不存在剩余文档才允许退出 Photoshop，否则保留窗口可见并报告异常。

普通创建只会在导入时忽略透明度很低、范围极小且与主体断开的高置信度 Alpha 噪点，不会生成一份已经清理好的 PSD。用户需要交付修复后的 PSD、残片超过这条保守清理边界，或已确认某个图层/区域需要改动时，使用包装脚本的 `psd` 命令族。先查看原图、未增强白底/深色底合成、单层预览和 Alpha 定位证据；存在多份候选时先建立逐部件来源清单，选定基础 PSD 和规范画布，再把已经证实的修改写进 JSON 配方。整层都是独立背景残片或托底时才用 `delete-layer`；只有矩形范围完全属于杂质，且不碰主体轮廓、阴影、抗锯齿和隐藏的运动延展时才用 `clear-region`；白边和边缘污染分别只在证据成立时使用 `remove-white-matte` 与 `defringe`。若要保留语义层、只替换其中已经客观清理的杂质，把保持完整画布和原始位置的透明清洁层列入 `sources`，再用 `duplicate-layer`、`delete-layer` 和 `rename-layer` 替换原层；不能裁成局部素材后凭目测重新摆放。检测到矩形边界本身不等于可以删，不能把角色本来需要的补底、被遮挡结构或有效颜色块当作硬矩形托底。

配方必须使用 `version: 1`、`kind: "puppetloom-photoshop-psd-repair"`、`basePsd`、至少一项 `operations`，并在 `checks.requiredLayers` 中列出修复后必须保留的核心层；有原图时同时填写 `referenceImage`。`sources[].canvasPolicy` 与 `extract-white-region.canvasPolicy` 默认是 `require-match`；只有同一整画布构图、宽高比一致但分辨率不同的 donor 才显式改成 `fit-full-canvas`。预演会把基础 PSD、每份 donor、每个原画补件输入的尺寸、哈希和实际缩放记录进 `input-manifest.json`，尺寸不匹配或宽高比不同会在启动 Photoshop 前拒绝。所有图层选择器、`splitX` 和 `[left, top, right, bottom]` 都使用规范画布坐标并来自本次检查，不能照抄旧角色或示例坐标。正式修复先做只读预演，再执行到待视觉复核状态：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 psd repair --recipe E:\Puppets\work\maid-repair\recipe.json --output E:\Puppets\work\maid-repair\maid-repaired.psd --workdir E:\Puppets\work\maid-repair\run --dry-run --json
& <skill>\scripts\invoke_puppetloom.ps1 psd repair --recipe E:\Puppets\work\maid-repair\recipe.json --output E:\Puppets\work\maid-repair\maid-repaired.psd --workdir E:\Puppets\work\maid-repair\run --json
```

首次启动任务时，`--output` 必须是新的 PSD 路径，`--workdir` 必须是新的操作目录，原 PSD 永不覆盖。任务中断或 Photoshop 失败时保留该目录，不删除半成品；输入没有变化时用原命令、原输出和同一个 workdir 重跑，命令会校验输入哈希、归档局部输出并恢复同一任务。第二条命令正常完成 Photoshop 和自动检查后会返回退出码 4、`status: awaiting-visual-review`；这是要求外部 Agent 看图的预期暂停，不是修复失败。实际打开返回的 `recomposition.png`、`on-white.png`、`on-dark.png`、`on-checker.png`、`layer-contact-sheet.png`、`layer-detail-sheet.png`、`layer-alpha-sheet.png` 和有原图时的 `reference-comparison.png`。缩略总览用于扫查全部图层，细节图用于确认每个部件的完整轮廓与画布截断，Alpha 图用于确认浅色实体内部不透明；不能把颜色亮度直接当作 Alpha，也不能只看整图后填写结论。逐项填写操作目录自动生成且已绑定证据哈希的 `visual-review.json`，然后定稿：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 psd finalize --workdir E:\Puppets\work\maid-repair\run --decision E:\Puppets\work\maid-repair\run\visual-review.json --json
```

若 Photoshop 已经产出新的 PSD，需要重新打开现有结果、补齐或再生证据，使用下面的替代入口；`psd review` 不是每次 `psd repair` 后还要机械重复的一步，它和 repair 都会进入同一个视觉定稿关口：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 psd review --input E:\Puppets\work\maid-repair\maid-repaired.psd --recipe E:\Puppets\work\maid-repair\recipe.json --workdir E:\Puppets\work\maid-repair\review --json
& <skill>\scripts\invoke_puppetloom.ps1 psd finalize --workdir E:\Puppets\work\maid-repair\review --decision E:\Puppets\work\maid-repair\review\visual-review.json --json
```

自动结构或 Alpha 检查失败时停止，不能靠视觉结论强行接受。`accepted` 才能直接把新 PSD 交给 `create`；`accepted-with-repairs` 必须保留非阻断修复计划，并继续遵守用户明确接受后才能进入创建、未修完不能报告成品的上层规则；`rejected` 停止。最终结论绑定输出 PSD 和全部证据哈希，证据或 PSD 改变后必须重新运行 repair 或 review，不能改写已经定稿的终态。

先查看 `inspect` 返回的 `preflight`：普通创建保持自动 Alpha 清理，不传高级例外参数。系统默认只移除透明度很低、范围极小且与主体断开的高置信度噪点，眼睛高光、细发丝和装饰等疑似有效细节继续保留，源 PSD 始终不改。`--preserve-alpha-noise` 只用于诊断时保留全部区域；只有用户明确接受可能误删绘画细节时才使用 `--clean-alpha` 激进清理。不要把这两个高级例外变成普通用户创建角色前必须勾选或决定的步骤。

`create` 输出必须是规范根目录内的新目录或空目录；每次 `record` 也使用该项目内部新的证据目录，软件不会覆盖同名证据。上面的 `record` 只在确实需要连续视频且用户允许时运行，不是固定交付物。参考图缺失时省略参数，不得代入不对应的图片。成功生成 `semantic/grouped/minimal` 任一等级都返回 0；2 是输入或补丁无效，3 是文件系统、项目或运行时错误。创建完成后始终维护一个规范项目目录，以内部 revision、session 和证据历史管理版本，不复制 `Character-r1/Character-r2` 一类目录。

`visual-review.json` 已记录独立图层顺序修复时，先用 `author inspect` 取得稳定 layer ID，再用 `author apply` 提交 `move-layer` 操作。`beforeLayerId` 表示把目标放到参照层后面，`afterLayerId` 表示放到参照层前面；二者只能提供一个。用户要求调整“整个图层顺序”时，必须从后到前检查当前角色每一组可见重叠和遮挡关系，不能只核对新增、替换或用户最后指出的图层；收到更新 PSD 后即使只有少数纹理变化，也要重新完成这次全局遮挡闭环。每次移动后重新 `render` 中立、眨眼和相关动作极值，确认腿与前后裙、后发与脸颈、外衣与脖子、项链主体与吊坠、脸与眉眼等实际设计关系成立，并查看连续运动中是否穿插或露出断面。示例关系只提醒常见风险，最终顺序仍以该角色原画和 PSD 重组为准。不要直接改 `puppetloom.json`，也不要静默改写源 PSD。

```json
{
  "version": 1,
  "baseRevision": 0,
  "label": "修正独立图层遮挡顺序",
  "operations": [
    { "op": "move-layer", "layerId": "back-skirt", "beforeLayerId": "left-leg" },
    { "op": "move-layer", "layerId": "back-hair", "beforeLayerId": "neck" },
    { "op": "move-layer", "layerId": "left-eyebrow", "afterLayerId": "face" }
  ]
}
```

这里的 ID 只是结构示例，实际补丁必须使用当前项目 `author inspect` 返回的 ID 和 revision；不能照抄示例。

## Agent-first 修改顺序

创建后的基础结果和已有项目都通过外部 Agent 调用 CLI 继续工作。用户要求整模时处理整模，点名一个部位时不扩写成其它部位。选择修改入口时遵守下面的优先级：

1. 外部 Agent 先看基线，用 `agent specification` 取得结构化模板并填写明确意图，再使用 `agent plan/apply --spec` 完成整模或分部闭环。软件负责确定性制作、自检、安全收敛、提交和证据；理解用户、视觉判断和下一轮返修由外部 Agent 负责。
2. 顶层 Agent 无法表达、但参数、关键形、变形器或物理能够表达的目标，使用 `author inspect/apply` 高层修改。
3. 只有局部顶点、轴心或权重需要修正时，才使用 `describe --layer` 和稀疏 `calibrate`。
4. `edit` 是用户明确想手调或公开 CLI 无法表达局部修正时的备用入口。桌面应用不运行 Agent 编排，不把用户变成人工网格制作员，也不继续补手工工具来绕开 Agent 任务。

已有项目执行“完成整模”“检查遗漏”“继续做完”前先审查，后写入。运行 `history/verify/describe`，读取当前 revision、所有实际存在的部位、accepted/rejected/unreviewed session，并用准确 revision 的高分辨率整模和局部证据检查已接受结果。整模审查覆盖所有实际存在部位，但 `apply` 只覆盖确有可见缺陷且本轮获准修改的部位；不要为了覆盖部位清单而重做已经成立的结果。若没有待修缺陷，不执行 `apply`、`author apply` 或 `calibrate`，不创建新 revision。

用户问“这轮最新版”“全部做完了吗”或要求查看这轮解决的问题时，先从完整任务、批注和后续纠正重建需求清单。逐项读取公开入口的实际默认值或本次调用参数、规范项目当前 revision 的真实数据、匹配证据和接受记录；不能从代码存在、帮助文本、测试夹具或隔离副本反推正式用户路径已经启用。`test/artifacts`、临时迁移目录和报告副本不能参与“哪个是最新版”的判断。后来的单项截图只修正该项，不自动取消此前仍在同一任务内的其它要求。

整模的正式入口是先取得与当前 revision 绑定的模板，由外部 Agent 看图后编辑成 `rig-spec-rN.json`，再计划和执行：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 agent specification --project E:\Puppets\Character --scope whole --json
& <skill>\scripts\invoke_puppetloom.ps1 agent plan --project E:\Puppets\Character --spec E:\Puppets\rig-spec-r0.json --json
& <skill>\scripts\invoke_puppetloom.ps1 agent apply --project E:\Puppets\Character --spec E:\Puppets\rig-spec-r0.json --json
```

只处理一个部位时，在生成规格模板时把 `--scope` 设为稳定 ID：`headFace`、`eyes`、`mouth`、`frontHair`、`backHair`、`ahoge`、`ears`、`headwear`、`body`、`topCloth`、`skirt`、`tail` 或 `accessory`。例如：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 agent specification --project E:\Puppets\Character --scope frontHair --json
& <skill>\scripts\invoke_puppetloom.ps1 agent plan --project E:\Puppets\Character --spec E:\Puppets\front-hair-spec-r0.json --json
& <skill>\scripts\invoke_puppetloom.ps1 agent apply --project E:\Puppets\Character --spec E:\Puppets\front-hair-spec-r0.json --json
```

模板不能原样执行。外部 Agent 必须根据用户目标和实际基线填写 `goal`、角色专属 `anatomy`、选择 `parts`、调整每个部位的数值 `intent` 并写出基于画面的 `rationale`。先逐层检查模板列出的当前 `layerIds`；结构敏感部位必须按本项目写实：头脸和嘴保留实际斜轴，前后发写实际发束与根部，左右耳、头饰和上衣写实际轴心及覆盖全部网格顶点的固定/释放权重，头饰显式选择 `crown` 或 `null`。不能复制旧角色的发束数量、耳根、镜像方向、头饰长宽比规则或对称脸点。`plan` 只读，先核对 `inputMode: structured-specification`、`baseRevision`、`requestedParts`、草稿、目标 layer、anatomy 覆盖、各部位 `checks/repairs/assetRequests`、`canApply` 和 `blockers`。存在不兼容草稿、结构覆盖不全、自检失败或 revision 冲突时停止，不清空用户的其它工作。`apply` 只接受 `--spec`，按确定顺序处理存在的部位，每个成功部位形成独立可回滚 revision、session、前后证据和 Agent 报告；最后返回整模 `verification` 和汇总报告。`not-present` 表示项目没有相应图层，`needs-assets` 表示现有结构无法实现目标、确实需要补充素材，`blocked` 才是本轮无法继续的问题。不得伪造缺失图层，也成功执行的部位是 `awaiting-visual-review`，不得把命令成功或上述三种状态说成视觉制作完成。

整模 `apply` 不是整体事务。它逐部位提交，前面已完成的 revision 不会因为后续部位 `blocked` 自动回滚；返回后逐项核对 `status`、实际 from/to revision、session、报告路径和 `history`。当前只有前发 Agent 能在提案等价时明确返回无变化，其它主运动和次级部位可能仍提交 revision，所以成熟项目不能用整模 `apply` 代替只读审查。`coherenceChecks` 只覆盖软件当前声明的跨部位规则，不能替代对全部历史 accepted 结果的视觉保护清单。若整模最终阻断且已落盘的候选没有被接受，标记所有受影响 session 为 `rejected`，恢复最后接受的 revision 并复核。

`agent front-hair plan/apply`、`agent secondary plan/apply` 以及顶层 `--instruction/--scope` 是保留的精细或旧调用兼容入口；正式外部 Agent 流程使用结构化规格，不能把理解自然语言的责任推回软件。桌面应用只用于播放、查看和必要的人工兜底，不应出现项目内嵌的 Agent 对话入口。

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 agent front-hair plan --project E:\Puppets\Character --instruction "检查并重做前发运动" --json
& <skill>\scripts\invoke_puppetloom.ps1 agent front-hair apply --project E:\Puppets\Character --instruction "检查并重做前发运动" --json
& <skill>\scripts\invoke_puppetloom.ps1 agent secondary plan --project E:\Puppets\Character --part tail --instruction "尾巴根部固定，回弹自然" --json
```

其它当前可由高层结构表达的修改使用：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 author inspect --project E:\Puppets\Character --json
& <skill>\scripts\invoke_puppetloom.ps1 author apply --project E:\Puppets\Character --patch E:\Input\authoring.json --json
```

补丁只包含用户点名部位所需的参数、关键形、变形器或物理操作，并使用刚读取的 base revision。已有项目若被用户明确指定为只读对照，不在其中执行 `apply`、`author apply` 或 `calibrate`；只对另行获准的工作项目写入，并在交付前核对对照项目没有变化。用户在任务中追加的范围和素材限制立即生效：说“只使用现有素材”时不得运行 `enhance`、生成或下载新图、修改 PSD 或把参考图加入项目；允许继续制作现有素材能支持的部位，缺口只报告为 `needs-assets`。说“不要视频”时不得运行 `record`，不能把证据偏好擅自改写成素材或能力扩展。

用户要求建立或补齐标准表情、肢体、耳朵、尾巴等可触发动作时，先按真实图层只读规划，再写入同一项目的可恢复 revision：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 actions plan --project E:\Puppets\Character --json
& <skill>\scripts\invoke_puppetloom.ps1 actions apply --project E:\Puppets\Character --json
```

逐项核对 `completed/not-present/needs-assets`，不能因为动作库命令成功就把缺素材部位说成完成。重复计划应无待写入变化；若它仍提出相同修改，先查项目 revision 和幂等性，不继续制造 revision。

## 视觉复核

始终查看准确 revision 的 `pose-sheet.png`、`motion-sheet.png`、每个 `focusComparisonSheet` 和 4×4 `focusMotionSheet`；只有需要定位单帧时才读取 `focusMotionManifest`，不能只读取路径或 JSON。需要新的高清证据时运行 `render --project <directory> --output <new-directory> --revision <n> --size 1080 --focus <part>`，并用 `play --project <directory> --revision <n>` 打开同一候选。打开新 revision 前关闭或明确替换旧角色窗口，不能让用户在多个过期窗口中猜哪个是当前结果。主姿态逐格检查中立、左右转、向上看、向下看和四个组合方向；动态进入、保持、退出确实影响判断且用户允许视频时，再运行 `record --project <directory> --output <new-directory> --mode autonomous --revision <n>`。secondary 证据必须证明主运动归零；若使用报告，其 `headAndBodyFrozen: true`，且头、身体、视线、呼吸、眨眼和嘴部极值都应为 0，再检查前后发、呆毛、耳朵、衣摆与尾巴的独立惯性。报告中的绝对项目路径、`baseProjectSha256`、`revision`、`currentRevisionAtStart` 和窗口比例必须匹配本次任务，不能拿旧进程、旧视频或文件名推测代替。放大查看脸缘、眼角、前发发梢、头皮/发饰边界和脖子连接，不能只看整张缩略图。

`verify.valid`、13 个安全姿态和 Agent checks 只证明对应结构与安全条件，不证明自然，也不证明参数最终让画面产生了有效运动。修改后必须使用 from/to revision 的前后证据，并在准确 to revision 上检查允许的连续证据：目标部位应以源图像像素计产生可见连续变化，根部没有脱离，进入、保持、回正和回弹没有跳变，未点名区域及历史 accepted 结果没有明显退化。归一化数值改变或不到一个源像素的位移不能冒充“肉眼可见”。若参数存在但目标部位不动，或全绿检查下实际观感更差，本次结果仍失败；恢复旧 revision 后停止，不修改阈值掩盖结果。

视觉异常先用摘要 `describe` 找稳定 ID，再运行 `describe --layer <id> --revision <n>`。顶点补丁使用输出中的完整 `delta`，不是在当前画面上重复累加；权重使用该顶点的当前绝对值。`alphaTopology.componentCount/components` 用于识别一个纹理中合并的头饰、双耳或其它分离部件，再决定是否需要多个锚点、局部权重或重新分层。坐标原点在画面左上，X 向右、Y 向下；`side` 是角色自身的解剖学左右，角色 left 通常位于画面右侧。不要直接改 `puppetloom.json`。

缺少闭眼或张口时，先检查 PSD、项目现有图层和 `requests/asset-requests.json`，盘点中立状态已经具备什么。已有闭嘴图层直接作为 `mouthOpen=0`，不能再生成一张闭嘴图替换它；默认只处理真正缺少的一个张口；左右闭眼先检查独立眼白与睫毛是否支持几何闭合，不能仅因没有 eyeClosed 图层就发起补图。微张嘴或音素嘴形只有用户明确需要对应表情或独立触发时才补，不参与默认麦克风口型选择。生成闭眼前先检查睁眼、虹膜和睫毛是否是独立图层，还是已经烘焙进脸部；烘焙眼不能靠线状覆盖物真正闭合，必须生成带正确肤色和睫毛的完整眼睑遮挡补片，或先修复 PSD，并在准确 revision 的合成中确认原眼完全消失。完整角色制作中，真正缺少的默认表情由 Agent 生成和检查，不再向用户逐项索取授权。生成时同时参考原画、PSD 重组图和请求裁图，严格继承线稿、睫毛体量、眼角、口腔配色、阴影和抗锯齿；闭眼不能是一条弧线。PNG 的尺寸、Alpha、位置、左右和覆盖率符合请求后才运行 `enhance --assets <directory>`；命令返回的 `accepted` 才算接入，`rejected` 不能当成成功。用户明确限定现有素材或禁止生图时保留请求但不执行增强，并报告 `needs-assets`。

## 现有项目接入新增能力

软件升级、CLI 新增能力或项目格式增加字段不等于源 PSD 变化。规范项目仍使用原来保存的同一 PSD，而只是缺少后来增加的多房束、侧脸深度或可选躯干体积数据时，先运行：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 extensions plan --project E:\Puppets\Character --json
& <skill>\scripts\invoke_puppetloom.ps1 extensions apply --project E:\Puppets\Character --json
```

只有用户目标和素材确实需要躯干体积时才添加 `--torso-volume`，不能把它当成所有角色的默认身体效果。`plan` 必须读取项目自己的源 PSD，并把新增数据作为同一规范目录中的可恢复 revision；执行后重新检查需求清单，不能只凭 `extensions` 命令成功就宣称所有点名能力都已进入项目。

## 更新 PSD

收到同一角色的新 PSD 时，不在规范项目旁边创建另一个最新版，也不直接覆盖仍在使用的项目文件。先在规范项目内部建立新的迁移工作目录和候选目录，运行：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 migrate --project E:\Puppets\Character --input E:\Puppets\Character\work\psd-refresh-v2\input\character-v2.psd --reference E:\Puppets\Character\work\psd-refresh-v2\input\character-v2.png --output E:\Puppets\Character\work\psd-refresh-v2\candidate --json
```

查看候选的 `reports/migration.json` 和 `migration-patch.json`。`exact` 才允许迁移几何校准和兼容的项目专属补充；`geometry-changed`、`missing` 或 `ambiguous` 必须按新 PSD 重新描述、制作、渲染和校准，不能复制旧权重后缩小幅度掩盖。随后在候选上完成全局图层顺序、全部点名部位、表情、动作极值和连续运动复核。候选通过后，把原规范项目的旧运行状态移动到项目内部带时间或 revision 的 `archive` 目录，再把候选晋升到原规范项目路径；这是一次可恢复的项目内晋升，不删除旧状态，也不留下 `Character-v2` 与原目录竞争“最新版”。晋升后重新运行 `history/verify/describe/render`，并核对项目保存的源 PSD 哈希就是用户本轮提供的文件。

## 结果反馈与人工备用

用户对自动结果的反馈优先由外部 Agent 解释为同一范围的新规格，例如“摆动幅度小一点”“滞后太慢”“呆毛太弹”。Agent 重新查看当前 revision，生成新模板并调整对应 `intent/rationale`；高层 authoring 能承接时才修改对应关键形或物理。不要先要求用户指出顶点、权重或参数编号。

只有自动或高层入口不能表达的局部校正才用 JSON 稀疏补丁和 `calibrate`，每次修改后用 `compare`。用户明确希望自己调时运行：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 edit --project E:\Puppets\Character
```

候选结果先运行定向安全检查并展示准确 revision 的高清画面或角色窗口，不在用户看候选前先耗时跑完整回归或执行推送。用户接受后运行 `evidence --project <directory> --session <id> --status accepted`，再完成获准范围内的完整回归和发布操作。用户拒绝自动制作或人工校正时，运行 `history` 找出本次所有 session，分别用 `evidence --project <directory> --session <id> --status rejected` 标为 `rejected`，再 `restore --revision <最后接受的 revision> --base-revision <当前 revision>`，撤回应只涉及被拒绝的变化，并检查准确 revision 的恢复证据；用户已授权继续修复或提出新方向时按具体缺陷继续返修。恢复会保留新审计记录。

运行角色用 `play --project <directory> --revision <n>`，明确检查的 revision，避免当前校准变化后仍观察旧窗口。不要为了演示而自动接入可选闭眼/嘴形；缺少它们时，眨眼和嘴部保持安全状态即可。完整项目交付前用新的项目内证据目录运行 `performance --project <directory> --output <new-directory> --revision <n> --json`。它会锁定准确 revision，在真实角色窗口分别测量活动态和暂停态，返回每轮 FPS、p95、p99、最差帧、40ms 以上长帧、直接渲染耗时和 `diagnosis.frameDropSource`；只有 `valid: true` 才通过，`ok: true` 只表示命令成功完成。固定 23 层 fixture、只看平均 FPS 或未注明 revision 的旧报告都不能替代本项目证据。完整项目交付前还要通过桌面端 `edit` 或 `play` 实际读取晋升后的规范绝对路径，并检查“最近项目”出现的是同一路径而不是迁移候选、旧副本或仓库外目录；CLI 创建成功但桌面端没有读取规范项目，不算完成项目交付。
````

## File: skills/live2d-puppet/references/runtime-demonstration.md
size: 3119
sha: 307f4cc72efff5a9038de7d0974767a87485bf24
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/runtime-demonstration.md

````text
# CLI 实时演示

## 适用范围

用户要求外部 Agent 配合录制 PuppetLoom 功能演示、快速证明角色受 Agent 控制，或明确要求“先编辑器、后角色窗口、演示结束不要关窗”时使用本流程。这里的控制入口是 Skill 脚本和 PuppetLoom 公共 CLI，不是 Windows 鼠标模拟，也不把临时 Playwright 片段当成正式入口。

## 唯一演示入口

先用 `history` 读取规范项目当前 revision；不能从会话记忆、旧窗口标题或报告目录猜版本。默认演示当前 revision，用户明确点名 revision 时也必须与编辑器实际打开的当前 revision 一致：

```powershell
& <skill>\scripts\invoke_puppetloom.ps1 history --project E:\Puppets\Character --json
& <skill>\scripts\demo_puppetloom.ps1 -Project E:\Puppets\Character -Revision 41 -PaceMs 320 -KeepOpen
```

`demo_puppetloom.ps1` 是确定性的 CLI 演示入口。它通过真实 Electron 驱动依次展示 `01 项目总览`、`02 结构与网格`、`03 参数与姿态`、`04 表情与物理`、`05 预览与验收`，只操作预览、姿态和播放控件；随后才打开角色窗口。不要另写一次性内联 Playwright 脚本，也不要绕过 `invoke_puppetloom.ps1` 直接调用 `apps/cli/dist/index.js`。

角色窗口出现后，脚本通过包装入口执行 `runtime inspect`，按返回的 viewer ID、实际表情和实际行为决定可演示内容，再使用 `runtime set/trigger/release`。姿态段覆盖左右、上下、侧倾、眨眼、嘴部和中立；表情与动作不存在时按真实能力跳过，不因固定中文按钮或固定动作名缺失而让整场演示失败。控制来源使用独立 source ID，结束时必须 `release`，让角色回到自主运动。

`PaceMs` 控制每一步可见时长，录屏中的快速证明通常使用 240–420 毫秒；不能快到画面尚未更新就进入下一项。`-KeepOpen` 表示脚本在输出 `{"demo":"ready"}` 后继续等待真实 Electron 进程，编辑器和角色窗口都保持打开，直到用户自己关闭。保活必须等待 Electron 的关闭事件，不能使用没有活动进程句柄的悬空顶层 Promise。

## 只读与失败边界

演示不调整校准滑杆、不保存草稿、不执行 `apply/calibrate/actions apply/extensions apply`，也不增加 revision。开始时记录 revision 与现有草稿，结束前再次读取；任一发生变化都判为失败。脚本为独立演示进程使用 `D:\Tools\PuppetLoom\agent-demo` 下的运行配置，不把缓存或日志写进角色项目和调用仓库。

每个编辑器工作区和运行时动作完成后都会输出结构化进度。只有依次看到 editor-ready、五个 editor-workspace、viewer-ready、runtime-pose/表情/动作以及最终 ready，且再次核对 revision 未变，才算演示链完成。选择器或运行时步骤失败时如实输出 failed；用户要求保留窗口时仍等待当前 Electron 进程，不通过关闭重开掩盖失败。修复入口或脚本后从完整演示重新验证，不能拿普通 E2E 测试通过代替这条真实路径。
````

## File: skills/live2d-puppet/references/see-through-local-deployment.md
size: 5098
sha: 80f8fc35144acb9ec5cefc894ba53524b83fef64
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/see-through-local-deployment.md

````text
# See-Through 本地部署与优化

## 何时使用

本地 See-Through 是最后可选项，不是默认路线。原画确认后优先让用户在 ModelScope 网页自行上传并下载 PSD；用户选择 Agent 代传时才走在线 API。只有在线入口不可用、用户仍要继续并明确选择本地运行时，才安装或启动本地项目。用户带回 PSD 后在本机复核不等于本地部署。

当前 Windows 工作机上的项目目录是 `E:\Code\see-through-webui`。不要为了让这个项目运行而在其它目录再复制一份 See-Through，也不要未经检查就重复安装 CUDA、Python、PyTorch 或模型。开始前先检查 `nvidia-smi`、`where.exe python`、现有虚拟环境和 C、D、E 盘的 CUDA/PyTorch/模型缓存；兼容的现有组件继续使用，确实缺失的依赖才补装。Python、pip 缓存和可复用工具优先放在 `D:\Tools`，项目、虚拟环境、模型缓存和输出保留在 D 或 E 盘，不主动占用 C 盘。下载失败时改用可用镜像源并保留安装日志，不通过反复删除环境碰运气。

## 已验证门槛与启动

本地 WebUI 面向 Windows 10/11、NVIDIA RTX 20 系及以上显卡；8GB 显存、8GB 内存和约 20GB 可用磁盘是最低实用门槛，首次下载约 6GB。RTX 2080 Super 8GB 可以运行，但 1024 推理接近显存上限，进入共享显存后会显著变慢。

在项目目录中先验证现有环境，而不是直接重装：

```powershell
nvidia-smi
& E:\Code\see-through-webui\venv\Scripts\python.exe -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available(), torch.cuda.get_device_name(0))"
```

缺少项目环境时才运行 `install.bat`，成功后用 `run.bat` 启动，在浏览器打开它报告的本机地址。安装、启动和一次推理都要检查退出码与日志；声称安装成功前必须用一张已经打开确认过的正常日系二次元单人图跑通 PSD 输出，并按主 Skill 路由的分层复核流程生成重组对照和视觉结论。测试图不能用抽象测试卡，也不能用正式用户原画之外的文件冒充正式结果。

## 分辨率与显存

当前 WebUI 接受 512 到 2048，自动取最近的 64 倍数，因此 704 可以运行；最低值是 512。512、704 或 768 只适合连通性与快速预检，不能靠后期高清放大修复已经拆错的语义。正式原画默认 LayerDiff 使用 1024；深度阶段默认 720/768 即可。出现显存不足时先降低预检分辨率或恢复正确的 offload，不自动牺牲正式结果，也不把共享显存导致的极慢误判为程序卡死。

## 当前本地版本的已知问题

`E:\Code\see-through-webui` 是可恢复的本地工作副本，已有针对这台机器的修改，不能把它与官方在线服务混为一谈。继续优化前先查看 Git diff 和实际日志，保护已经存在的改动。

- WebUI 当前固定传入 `--no_group_offload`。这会让 8GB 显卡更容易超过物理显存；应恢复可选的 group offload，并在同一图片、同一 seed 下比较 NF4 与官方 BF16 block-swap 路径。
- 当前 Marigold 为每个图层重复运行“一层加全图”的双图推理。它能降低单次显存，但约二十个图层会重复二十次，且各次深度缺少统一批次校准，是耗时过长和排序不稳定的来源。
- 当前 Alpha 总和先被裁剪到 0～255，随后却检查是否大于 256；这个条件永远不会成立，会影响前后发、眉毛、眼睛和服装等重叠区域的深度判断。
- See-Through 按单个动漫人物和固定身体语义槽工作。人物旁边的鹿、第二个完整角色或大型伴生物容易串入头发、服装、翅膀或配饰层；正式输入默认单主体，第二主体应独立处理。

## 后续优化顺序

先修推理链路，再考虑模型训练：

1. 修正 Alpha 遮挡条件，并为重叠层增加可复现测试。
2. 恢复 8GB 显存可用的 group offload，固定输入与 seed 对 NF4、BF16 block-swap 做视觉和耗时对照。
3. 把 Marigold 改为每批 4～6 层，并让每批共享同一张全图深度作统一校准；跳过完全透明的空层。
4. 把流程拆为语义拆层、预览确认、深度排序和 PSD 四阶段。拆层已经缺眼、串入第二主体或主要部件错误时立即停止，不继续浪费时间跑深度。
5. 接入项目已有的 AnimeInstanceSegmentation 或 SAM2 入口，让用户或 Agent 先选定主人物；只有主实例进入 LayerDiff，第二主体另行处理。
6. 增加人物掩码越界、异常连通区域、语义层缺失、图层顺序矛盾和重组误差检查，并始终保留原图、PSD、预览、日志和同参数对照。

不建议在这台机器上重新训练 LayerDiff。完整训练需要远超单张 8GB 消费显卡的算力；本地工作的重点是稳定推理、提前止损、统一深度和视觉验收。任何优化都先用测试素材确认，再处理用户原画；结果仍须由外部 Agent 实际看图，不能用运行成功或指标变小代替分层正确。
````

## File: skills/live2d-puppet/references/shape-target-workflow.md
size: 7211
sha: fcaeeb1aa09d6194d9aae06c733c4022e16a5ecb
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/shape-target-workflow.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/shape-target-workflow.md

## File: skills/live2d-puppet/references/source-art-and-layering.md
size: 20938
sha: d6fde0707a8f8ee448bb3108dc0fa0958f2251ac
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/source-art-and-layering.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/source-art-and-layering.md

## File: skills/live2d-puppet/references/visual-rigging-rules.md
size: 14946
sha: 60b961ed9808c0f1e712d81ff6cb0056b768e452
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/visual-rigging-rules.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/references/visual-rigging-rules.md

## File: skills/live2d-puppet/assets/blue-whale-maid-reference/blue-whale-maid-layered.psd
size: 2857545
sha: 4d020716111d2f2627e725721180dee8c9b4bc45
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/blue-whale-maid-layered.psd

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/blue-whale-maid-layered.psd

## File: skills/live2d-puppet/assets/blue-whale-maid-reference/blue-whale-maid-source-art.png
size: 1236392
sha: 2941d1eb18bd61c407f14bf83a53924e298e9194
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/blue-whale-maid-source-art.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/blue-whale-maid-source-art.png

## File: skills/live2d-puppet/assets/blue-whale-maid-reference/closed-eye-expression-reference.png
size: 111789
sha: 04a9bfdcb63c0b3fe8a8403da99d4422ac0cdbc5
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/closed-eye-expression-reference.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/closed-eye-expression-reference.png

## File: skills/live2d-puppet/assets/blue-whale-maid-reference/closed-mouth-expression-reference.png
size: 506007
sha: b3151eea5d13de1c46247f3b468aab9d4eb2cefa
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/closed-mouth-expression-reference.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/closed-mouth-expression-reference.png

## File: skills/live2d-puppet/assets/blue-whale-maid-reference/head-turn-deformation-guide.png
size: 1743615
sha: 222e7570421c96bc75489c64997bed93e52d1df7
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/head-turn-deformation-guide.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/head-turn-deformation-guide.png

## File: skills/live2d-puppet/assets/blue-whale-maid-reference/open-mouth-expression-reference.png
size: 739311
sha: 12938428776dedf182437441a435df97498ab437
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/open-mouth-expression-reference.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/assets/blue-whale-maid-reference/open-mouth-expression-reference.png

## File: skills/live2d-puppet/.gitignore
size: 33
sha: b37e781abdb8aa436b13895bf7183aea046ef2d7
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/.gitignore

```text
__pycache__/
*.py[cod]
/runtime/
```

## File: skills/live2d-puppet/agents/openai.yaml
size: 409
sha: acee7242e23ef37ee252477609a4fe5b6f7158c4
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/agents/openai.yaml

```text
interface:
  display_name: "Live2D Puppet"
  short_description: "让 Agent 用 PuppetLoom 制作、检查和校准角色"
  default_prompt: "Use $live2d-puppet as an external Codex workflow: operate PuppetLoom through its CLI, run agent plan/apply for the whole model or the requested part, inspect every exact-revision comparison and motion artifact, and use the official Cubism bridge only when requested."
```

## File: skills/live2d-puppet/requirements-layering.txt
size: 33
sha: 239e4a9fb608c42ecd566fb5eae08f4aacc952e2
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/requirements-layering.txt

```text
Pillow==12.2.0
psd-tools==1.17.4
```

## File: skills/live2d-puppet/tests/test_cubism_export_contract.py
size: 2403
sha: 76be026dd5ea304eba71d5eadd1b2b3c094d4c81
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/tests/test_cubism_export_contract.py

```text
import unittest
import subprocess
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]

class CubismExportContractTests(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        cls.skill = (ROOT / "SKILL.md").read_text(encoding="utf-8")
        cls.cubism = (ROOT / "references/cubism-bridge-workflow.md").read_text(encoding="utf-8")

    def test_cubism_bridge_preserves_the_official_boundary(self) -> None:
        combined = self.skill + self.cubism
        for phrase in (
            ".moc3", ".model3.json", "External API 1.1.0", "strictReady",
            "--allow-partial", "EditEnd { Cancel: true }", "ParamEyeLOpen",
            "cubism finalize", "cubism verify", "Cubism Viewer",
        ):
            self.assertIn(phrase, combined)
        self.assertIn("cubism export", combined)
        self.assertIn("awaiting-visual-review", combined)
        self.assertIn("实际导出图集", combined)
        self.assertIn("ArtMesh 顶点坐标或 Warp 控制点坐标", self.cubism)

    def test_wrapper_matches_the_real_cubism_cli(self) -> None:
        expectations = {
            ("cubism", "--help"): ("export", "plan", "prepare", "finalize", "verify", "open", "editor"),
            ("cubism", "export", "--help"): ("--project", "--output", "--editor-version", "--runtime-version"),
            ("cubism", "plan", "--help"): ("--project", "--json"),
            ("cubism", "finalize", "--help"): ("--project", "--editor-model", "--output"),
            ("cubism", "verify", "--help"): ("--model", "--json"),
            ("cubism", "editor", "--help"): ("inspect", "sync", "preview", "clear-preview"),
            ("cubism", "editor", "sync", "--help"): ("--project", "--allow-partial", "--token-file"),
        }
        wrapper = ROOT / "scripts" / "invoke_puppetloom.ps1"
        for arguments, flags in expectations.items():
            result = subprocess.run(
                ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(wrapper), *arguments],
                cwd=ROOT,
                capture_output=True,
                text=True,
                encoding="utf-8",
                errors="replace",
                timeout=30,
                check=False,
            )
            self.assertEqual(result.returncode, 0, result.stderr)
            for flag in flags:
                self.assertIn(flag, result.stdout)
```

## File: skills/live2d-puppet/tests/test_project_lifecycle_and_runtime_contracts.py
size: 4238
sha: bb09ebc1d7d760b56dd051bea914ed549db26987
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/tests/test_project_lifecycle_and_runtime_contracts.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/tests/test_project_lifecycle_and_runtime_contracts.py

## File: skills/live2d-puppet/tests/test_psd_repair_skill_contract.py
size: 3839
sha: 13b2d4413953b9c6595ad7f861ee0adb5eda4ead
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/tests/test_psd_repair_skill_contract.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/tests/test_psd_repair_skill_contract.py

## File: skills/live2d-puppet/tests/test_runtime_performance_contracts.py
size: 1378
sha: ba3c44da6a6ecac5cc1c50e6c431fb0d4ee0dbd1
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/tests/test_runtime_performance_contracts.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/tests/test_runtime_performance_contracts.py

## File: skills/live2d-puppet/tests/test_skill_contracts.py
size: 34016
sha: da23eb27e9235e4a6fb711041b8d6cbb31fd5017
upstream: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/tests/test_skill_contracts.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/cheshiremew/puppetloom/blob/main/skills/live2d-puppet/tests/test_skill_contracts.py

## File: README.md
upstream: https://github.com/cheshiremew/puppetloom/blob/main/README.md

````text
<!-- readme-header:start -->

<p align="center">
  <img src="./assets/readme/logo.svg" width="112" alt="PuppetLoom">
</p>

<h1 align="center">PuppetLoom</h1>

<p align="center">
  <strong>把分层角色 PSD 变成可自动制作、可验证、可继续校准的 2D 动态角色。</strong>
</p>

<p align="center">
  <strong>中文</strong> · <a href="./README.en.md">English</a> · <a href="./README.ja.md">日本語</a> | <a href="./docs/AGENT_USAGE.md">文档</a> | <a href="./CONTRIBUTING.md">贡献</a> | <a href="https://github.com/CheshireMew/PuppetLoom/issues">反馈</a>
</p>

<p align="center">
  <a href="https://x.com/0xCheshire" title="X"><img src="https://img.shields.io/badge/X-%400xCheshire-000000?logo=x&amp;logoColor=white" alt="X：@0xCheshire"></a>
  <a href="https://t.me/CheshireBTC" title="Telegram"><img src="https://img.shields.io/badge/Telegram-CheshireBTC-26A5E4?logo=telegram&amp;logoColor=white" alt="Telegram：CheshireBTC"></a>
  <a href="https://blog.blacknico.com/" title="Blog"><img src="https://img.shields.io/badge/Blog-blog.blacknico.com-2E7D32?logo=rss&amp;logoColor=white" alt="博客：blog.blacknico.com"></a>
  <a href="https://blacknico.com/" title="Homepage"><img src="https://img.shields.io/badge/Home-blacknico.com-1F6FEB?logo=googlechrome&amp;logoColor=white" alt="个人主页：blacknico.com"></a>
</p>

<p align="center">
  <a href="https://github.com/CheshireMew/PuppetLoom/stargazers"><img src="https://img.shields.io/github/stars/CheshireMew/PuppetLoom?style=flat" alt="GitHub Stars"></a>
  <a href="https://github.com/CheshireMew/PuppetLoom/forks"><img src="https://img.shields.io/github/forks/CheshireMew/PuppetLoom?style=flat" alt="GitHub Forks"></a>
  <a href="https://github.com/CheshireMew/PuppetLoom/blob/main/LICENSE"><img src="https://img.shields.io/github/license/CheshireMew/PuppetLoom?style=flat" alt="Repository License"></a>
</p>

<!-- readme-header:end -->

<p align="center">
  <img src="./assets/readme/puppetloom-cover-v2.png" width="100%" alt="PuppetLoom：让分层角色动起来">
</p>

## 从分层 PSD 到可以持续制作的角色

<p align="center">
  <img src="./assets/readme/hero.svg" width="100%" alt="分层 PSD 经过结构化绑定、revision 证据，成为可自主运动的 2D 角色">
</p>

PuppetLoom 是一套 Windows 桌面应用、确定性 CLI、普通目录项目格式和外部 Agent Skill。它读取分层角色 PSD，生成保守的初始绑定，验证中立姿态和 12 个运动姿态，把每次修改保存为可恢复 revision，最后在透明桌面窗口中运行。桌面应用负责创建、查看、播放和人工兜底；外部 Agent 通过公开 CLI 与仓库内 Skill 制作和返修角色，软件内部不增加 Agent 对话或隐藏的模型调用。

第一次结果追求的是“在现有素材能支持的范围内合理地会动”。PuppetLoom 软件本身不会用参数伪造缺少的闭眼或嘴形；完整 Agent 制作流程可以按原画风格补齐真正缺少的表情素材，已有闭嘴不会重画。动作不安全时会缩小范围或阻断；每次校准都先生成证据，再切换当前 revision。

## See-Through 与效果边界

PuppetLoom 从单张原画开始的自动流程建立在 [See-Through](https://github.com/shitagaki-lab/see-through) 提供的动漫角色分层能力之上。See-Through 把确认后的原画转换为带原始画布坐标和透明通道的分层 PSD，是原画进入 PuppetLoom 结构分析、绑定和验证的重要的一环。我们感谢 See-Through 作者及其论文 [“See-through: Single-image Layer Decomposition for Anime Characters”](https://arxiv.org/abs/2602.03749)。PuppetLoom 不内置或再分发 See-Through 的代码与模型；默认使用官方在线演示，只有在线入口不可用且用户主动选择时才考虑本地部署。

PuppetLoom 的目标是用自动化流程较快得到效果不错、可以使用、够用的简单 2D 动态角色，但它不等于专业定制 Live2D。自动分层和自动绑定难以替代画师对遮挡托底、表情素材和可动结构的专门设计，也难以替代建模师对大角度转头、精细网格、复杂物理和演出节奏的逐项打磨。需要更高完成度时，应找专业角色画师和 Live2D 建模师制作。

## 你能得到什么

| 你要完成的事 | PuppetLoom 交付的结果 |
| --- | --- |
| 从 PSD 创建角色 | 图层预检、Alpha 连通域与噪点判断、语义控制点、不规则 ArtMesh、保守绑定，以及强验证通过后才发布的普通项目目录。 |
| 让角色自然地待机和运动 | 呼吸、视线先行的转头、颈部与上半身跟随、按重量延迟的头发/服装/尾巴，以及由短动作段落组成的自主时间线。 |
| 让外部 Agent 制作或返修 | 结构化规格 → 只读计划 → 分部执行；每个部位返回准确 revision、局部前后对比、连续运动表、阻断项和最终验证。 |
| 自己检查和微调 | 可编辑图层、轴心、网格、权重与响应参数的桌面编辑器；草稿可恢复，保存、接受、拒绝和恢复都会留下历史。 |
| 驱动和录制角色 | 鼠标、摄像头、麦克风、快捷键和外部来源按优先级、混合权重与 TTL 合成；保存可回放输入 JSON 和可恢复 WebM。 |
| 批量管理角色 | 制作中心统一处理单图分层任务、多项目体检、能力缺口、环境检查和更新；跨项目分析只从重复问题与已接受证据提出候选。 |
| 做直播与演出 | 左右眼、眉毛、笑容、脸颊、A/I/U/E/O、上半身和双手输入；服装/道具/预设、碰撞约束、非破坏 Take 以及 OSC/VMC、MIDI、手柄和控制面板适配。 |
| 发布到网页或 OBS | 导出透明 Web/OBS 目录和单文件 Web SDK；状态与动作可以继续由网页 API 控制。 |
| 交给 Cubism | 一次导出可编辑 cmo3、moc3、纹理及 exp3/motion3/physics3/cdi3，分别选择工程与运行时版本；也保留 Editor API 交接路线。 |

项目保留 PSD 的可见图层、顺序、坐标、透明度和混合模式记录，支持标准/自定义参数、一维与二维关键形态、变形器、表情、参数物理和具名行为。头部转向会收窄并移动远侧眼睛，但眼睛和眉毛始终保持完全不透明；只有耳朵、侧发等外围部件会在接近脸缘时降低可见度，近远侧发的绘制深度也可以随方向交换。

对于现有项目，`extensions plan/apply` 可以用下一条可恢复 revision 接入多房束头发、六点侧脸深度和显式躯干体积曲线，不必重新创建项目。`actions plan/apply` 按真实图层补齐标准表情、点头、摇头、鞠躬、观察、短说话、身体弹动、挥手、踏步、耳朵轻弹和尾巴摇摆，并逐部位报告已完成、不存在或缺少素材。

## 快速开始

当前只验收 Windows x64。普通用户可以使用项目生成的 NSIS 安装器；从源码运行需要 Node.js 24 或更高版本、npm 11，以及支持 WebGL2 的显卡。

```powershell
git clone https://github.com/CheshireMew/PuppetLoom.git
cd PuppetLoom
npm ci
npm run build
npm run desktop
```

仓库根目录的 `启动PuppetLoom.cmd` 提供同一桌面入口，缺少编译产物时会自动构建。用户数据、缓存和日志写入配置的 PuppetLoom 数据根，不把本机状态混进仓库。

## 创建并运行一个角色

1. 把分层角色 PSD 拖入创建窗口。原始角色图可选，只用于比较重新合成是否改变角色。
2. 查看 Alpha 连通域、高置信度噪点、保留的疑似绘画细节，以及自动拆分和回退拆分结果。
3. 选择一个新目录或空目录。PuppetLoom 会先在旁路目录完成创建与强验证，成功后才一次性发布到目标目录。
4. 进入校准编辑器检查或修改，也可以直接打开透明角色窗口。

角色窗口支持置顶、鼠标穿透、系统级鼠标跟随、本机摄像头面捕、麦克风口型，以及当前项目真实具有的表情和动作。主窗口会恢复上次的位置、大小和最大化状态；角色窗口按项目恢复位置、大小、置顶、跟随模式和缩放，换显示器后会自动移回可见区域。鼠标穿透不会在重启后恢复，避免窗口变得无法操作。摄像头先记录自然睁眼和闭口基线，过滤非零中立分数、单眼误检与重连残留，避免眼睛或嘴型长期停在半透明交叉淡化状态。

视频录制可以选择透明、黑、白、绿幕或自定义纯色背景，设置输出分辨率、24/30/60 FPS、手动或定时停止，并可录入已经开启的麦克风。录制时显示已用时间，定时录制同时显示剩余时间；停止后会明确显示文件收尾阶段，成功后由视频预览统一承载保存结果。普通录制只生成 WebM；需要复现或调试时可额外勾选动作数据，保存鼠标跟随、面捕、口型、表情、动作和外部控制的可回放 JSON。回放会校验项目 revision 并暂时隔离实时输入。窗口意外关闭时保留 `.partial.webm` 和中断报告，不静默丢失录制。

## 交给外部 Agent 制作

让能够运行仓库 CLI 的外部 Agent 读取 [`skills/live2d-puppet/SKILL.md`](skills/live2d-puppet/SKILL.md)，再提供 PSD 或现有 PuppetLoom 项目，以及以结果为中心的要求：

> 使用仓库里的 live2d-puppet Skill，把这份分层 PSD 创建为 PuppetLoom 项目。只使用现有素材；先展示基线证据，再按部位制作，并保留所有已经接受的 revision。

改善现有角色时，不需要告诉 Agent 顶点编号，直接描述你想看到的变化：

> 改善转头和前发跟随。脸部体积要稳定，发根不能脱离，回弹再小一点；不要改动已经接受的眼睛和嘴部结果。

正式写入路径是 `agent specification` → `agent plan --spec` → `agent apply --spec`。外部 Agent 负责理解自然语言和查看视觉证据；PuppetLoom 负责确定性执行结构化规格、验证结果，并把每个部位记录为 `completed`、`not-present`、`needs-assets` 或 `blocked`。完整流程见 [Agent 调用说明](docs/AGENT_USAGE.md)。

需要配合录屏或快速证明外部控制时，运行 `.\skills\live2d-puppet\scripts\demo_puppetloom.ps1 -Project D:\Puppets\my-character -KeepOpen`。它先展示五个编辑工作区，再通过公共 runtime CLI 驱动角色窗口；整个演示只读，不改变 revision 或校准草稿。详细边界由同一 Skill 的实时演示流程维护。

## CLI：完成第一个项目

所有确定性命令都可以返回 JSON。下面的连续路径会检查 PSD，在 Git 忽略的 `workspace` 目录中创建项目，验证后打开角色窗口：

```powershell
$input = "D:\Characters\my-character.psd"
$project = Join-Path $PWD "workspace\my-character"

node .\apps\cli\dist\index.js inspect --input $input --json
node .\apps\cli\dist\index.js create --input $input --output $project --seed 42 --json
node .\apps\cli\dist\index.js verify --project $project --json
node .\apps\cli\dist\index.js play --project $project
```

用 `describe`、`render`、`record`、`compare` 和 `history` 检查准确 revision；用 `calibrate`、`author`、`actions`、`extensions` 或结构化 `agent` 流程创建下一条可恢复 revision。只有源 PSD 确实更新时才使用 `migrate` 创建新项目；`export` 会把当前有效 revision 烘焙到新的可移植目录。完整命令与退出码见 [Agent 调用说明](docs/AGENT_USAGE.md)。

日常批量生产使用 `source`、`doctor`、`library scan`、`tracking-assets`、`production-config`、`take`、`improvements analyze` 和 `export-web`。这些命令与桌面制作中心共用项目格式，具体流程见 [制作中心与批量生产](docs/PRODUCTION_WORKFLOW.md)。

## 项目、revision 与证据

PuppetLoom 项目是普通目录，不使用私有压缩包。它包含项目清单、源 PSD、纹理、当前校准、revision session、报告、可选素材请求，以及输入与表演录制。写入操作核对 base revision 和项目锁，在验证与证据全部完成后才切换一次 current revision；恢复同样创建新的可追踪 revision，不删除历史。

```text
my-character/
  puppetloom.json
  source/source.psd
  textures/
  calibration/current.json
  calibration/sessions/
  reports/
  requests/
  supplements/
```

字段与兼容规则见 [项目格式](docs/PROJECT_FORMAT.md)，人和 Agent 共用的审查循环见 [校准证据说明](docs/CALIBRATION_EVIDENCE.md)，产物生命周期见 [版本与产物管理](docs/VERSIONING.md)。

## Cubism 的真实边界

PuppetLoom 的 `cubism export` 使用 PSD2Live 所用的 Umamo 编码器直接生成 `.cmo3` 和 `.moc3`，并输出纹理、动作、表情和物理。首次运行 `node scripts/setup-cubism-exporter.mjs` 配置依赖；桌面导出中心与 CLI 使用同一实现。默认工程目标为 Editor 5.3.01 起、运行时目标为 SDK 5.0，可分别选择版本。导出会保留当前修订的实际网格运动，但程序化变形器被转换为网格关键形，不能声称原建模层级完全相同。文件生成后仍需视觉复核，见 [Cubism 导出与 Editor 桥接](docs/CUBISM_BRIDGE.md)。

## 文档

- [校准编辑器说明](docs/EDITOR_GUIDE.md)：人工检查、草稿、校准、证据和运行预览。
- [Agent 调用说明](docs/AGENT_USAGE.md)：结构化规格、分部返修、authoring、迁移与退出码。
- [架构说明](docs/ARCHITECTURE.md)：core、renderer、CLI、desktop 与外部 Agent 的职责边界。
- [验收记录](docs/VALIDATION.md) 与 [测试说明](docs/TESTING.md)：已经验证的链路，以及仍需真实素材或人工判断的范围。
- [统一姿态模型](docs/COHERENT_POSE_MODEL.md)：头部、身体、视线、透视、遮挡和次级运动关系。
- [Cubism 官方格式桥接](docs/CUBISM_BRIDGE.md)：
````
