cortico-world-wardrobe-studio 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.3.0
+
+- Default to Chinese with a shared, persistent Chinese/English panel selector; preserve pending choices and JSON drafts when switching.
+- Add a detailed bilingual manual with reference/motion prompts, raw video gates, temporal matting steps, figure runtime requirements and import troubleshooting.
+- Add full field tables, complete fictional profiles and a downloadable JSON Schema.
+- Add read-only configuration checks, local installed-ID inspection and example/manual downloads in the panel.
+- Enforce the profile limit in UTF-8 bytes, including pasted input.
+
 ## 0.2.3
 
 - Follow the host theme with a dotted preview stage, compact outfit cards and horizontal option rows.

package/README.md

@@ -2,6 +2,8 @@
 
 Choose an outfit in a separate wardrobe panel, then configure only the options that belong to it. A local profile maps complete combinations to existing figure schemes. The original Coopanion wardrobe page and figure files remain unchanged.
 
+The extension defaults to Chinese. Use the Chinese/English selector above either panel; the choice is remembered across panels and restarts. It does not change the host language or imported names, and preserves pending outfit choices and JSON drafts.
+
 [中文说明](README_zh.md)
 
 ![Wholly fictional wardrobe example](assets/wardrobe.png)
@@ -12,14 +14,14 @@ The fictional Moss Fox demonstrates three different groups: trail outfits expose
 
 1. Install this folder using the manual World extension installer. Restart the Core process as requested and enable Wardrobe Studio. Verify it with isolated data before adopting it in a running deployment.
 2. Keep the desktop-pet World available. The default service origin is `http://127.0.0.1:7797`; change it in the extension configuration and restart this World if necessary.
-3. Import a local wardrobe JSON, choose an outfit and options, then Apply. See the [profile format](docs/profile-format.md) and the fictional example.
+3. Read Format reference in the import area, download the fictional example/JSON Schema, inspect installed IDs and Check configuration before importing. Then choose an outfit/options and Apply. See the [profile format](docs/profile-format.md) and the fictional example.
 4. Before uninstalling, use Restore previous appearance, verify success, disable the World and uninstall it. Normal stopping also attempts restoration. External appearance changes are preserved. See [lifecycle and recovery](docs/lifecycle.md).
 
 Every mapped combination must already have complete figure resources. The extension does not combine images into new clothing or fill missing motion. Coo's separate accessory contract continues to use its native wardrobe.
 
 ## Authoring guide
 
-The guide panel and agent tool cover complete dressed references, continuous action video, normal/half-speed and loop acceptance, temporal local matting, declared pose/expression support, runtime integration and versioned releases. The [full workflow](docs/agent-workflow.md) uses generic practices and a fictional example.
+The detailed guide includes copyable image/video prompts, input/output formats, alpha extraction and playback steps, a figure manifest scaffold, complete wardrobe JSON fields/examples, and stale-upgrade recovery. The guide panel and agent tool cover complete dressed references, continuous action video, normal/half-speed and loop acceptance, temporal local matting, declared pose/expression support, runtime integration and versioned releases. The [full workflow](docs/agent-workflow.md) uses generic practices and a fictional example.
 
 Tools: `wardrobe_list`, `wardrobe_choose`, `wardrobe_restore`, `wardrobe_authoring_guide`. Guidance returns instructions; it does not install tools, download models, run generation or read conversations.
 

package/README_zh.md

@@ -2,6 +2,8 @@
 
 在独立衣橱面板中，先选择服装，再显示这套服装自己的搭配选项。通过本地配置把选项组合映射到形象包已有的完整装扮，不修改 Coopanion 原生装扮页或角色文件。
 
+扩展默认中文，衣橱和制作指导上方可切换 English，并记住选择。切换不会改变 Coopanion 整体语言、已导入名称、待应用搭配或编辑中的 JSON。
+
 ![完全虚构的衣橱示例](assets/wardrobe.png)
 
 例如，虚构角色“苔星狐”的森林探险装有斗篷、足部装备；雨林装有雨帽、雨披颜色；观星装有护目镜。切换服装后，配置项随之改变。没有资源的组合不能应用。界面跟随宿主配色，采用点阵预览区、紧凑服装卡片和横排选项；本机预览读取形象包缩略图，公开示例只使用虚构角色。
@@ -10,14 +12,14 @@
 
 1. 在 World 扩展的手动安装中选择本包目录；按宿主提示重启进程，再启用“装扮工作室”。首次接入请先用隔离数据验证。
 2. 保持桌宠 World 可用。默认地址为 `http://127.0.0.1:7797`；端口不同可在扩展配置中修改，之后重启此 World。
-3. 打开扩展的“衣橱”面板，导入属于本机角色的 JSON 分组配置，选择服装和搭配，点击“应用装扮”。[配置格式](docs/profile-format.md)包含完整虚构示例。
+3. 打开扩展的“衣橱”面板，在导入区查看“格式说明”，下载虚构示例／JSON Schema，查看本机 ID，先“校验配置”再导入属于本机角色的 JSON 分组配置，选择服装和搭配，点击“应用装扮”。[配置格式](docs/profile-format.zh.md)包含完整虚构示例。
 4. 卸载前点击“恢复原外观”，确认成功后停用并卸载扩展。正常停用也会尝试恢复；在原生页另做的选择会被保留。[生命周期和异常恢复](docs/lifecycle.md)说明边界。
 
 本扩展不会把已有图片拼成未制作的服装，也不会自动补齐动作。先为每个有效搭配制作并验收完整资源，再配置其映射。Coo 自带配件使用独立契约，继续由原生页管理。
 
 ## 角色制作指导
 
-“角色制作指导”面板和 agent 工具提供分阶段工作流：角色与完整穿衣参考定稿、连续动作视频、原速／半速及循环验收、本地连续抠像、姿态与表情支持范围、运行时接入和版本发布。[完整指南](docs/agent-workflow.md)只包含可复用的制作流程，没有个人角色或历史素材。
+“角色制作指导”提供可复制的参考图／动作提示词、输入输出与帧格式、连续抠像步骤、形象接口骨架、完整衣橱 JSON 字段／示例、升级故障排查。面板和 agent 工具提供分阶段工作流：角色与完整穿衣参考定稿、连续动作视频、原速／半速及循环验收、本地连续抠像、姿态与表情支持范围、运行时接入和版本发布。[完整指南](docs/agent-workflow.zh.md)只包含可复用的制作流程，没有个人角色或历史素材。
 
 工具：`wardrobe_list`、`wardrobe_choose`、`wardrobe_restore`、`wardrobe_authoring_guide`。指导工具只返回说明，不安装工具、下载模型、执行生成任务或读取聊天记录。
 

package/describe.json

@@ -69,7 +69,7 @@
     },
     {
       "name": "wardrobe_authoring_guide",
-      "description": "Read the staged character and outfit authoring workflow. This returns guidance and acceptance criteria; it does not run generation, download models, read conversations or upload assets.",
+      "description": "Read detailed character/outfit production steps, prompts, media acceptance requirements, wardrobe JSON fields/examples and troubleshooting. This returns guidance only; it does not generate assets, download models, read conversations or upload files.",
       "tags": [
         "read"
       ],
@@ -86,15 +86,17 @@
               "review",
               "matte",
               "runtime",
-              "release"
+              "release",
+              "profile",
+              "troubleshooting"
             ]
           }
         },
         "additionalProperties": false
       },
       "summary": {
-        "zh": "读取从角色定稿到连续动画验收的制作指导。",
-        "en": "Read staged guidance for character references and reviewed continuous animation."
+        "zh": "读取详细制作步骤、衣橱 JSON 格式及故障排查。",
+        "en": "Read production steps, wardrobe JSON format and troubleshooting."
       }
     }
   ],

package/docs/agent-workflow.md

@@ -1,55 +1,190 @@
-# Character and outfit authoring · `src/guide.js`
+# Make your own character and outfits
+
+This manual is displayed in the extension too. All examples use the wholly fictional Moss Fox. The extension supplies instructions, local profile validation and appearance selection. Image/video generation, matting and figure runtime authoring use separate tools chosen by you.
+
+## [plan] 1. Plan the deliverable and tools
 
-This guide supplies a staged production workflow. Wardrobe Studio itself does not generate images or videos, install packages, download models, run a cloud job or inspect conversations. An agent uses tools explicitly made available by the person doing the work.
+Two deliverables are needed: a working figure pack containing animations, and a wardrobe profile grouping existing schemes. A wardrobe JSON is not a figure pack. Importing it cannot install media or generate an outfit.
 
-## 1. Define the deliverable
+1. For an existing character, inventory its figure.json, runtime entry, scheme IDs and motion vocabulary. Add reviewed resources to a private copy. For a new character, first build and test a figure API 2 pack, then group its outfits.
+2. Define identity, silhouette, outlines, proportions, camera, intended display size and each outfit's own controls. Moss Fox Trail has cape and footwear; Stargazer has only a visor. List only combinations you intend to produce.
+3. Make an action matrix per complete combination: one-shots, loops, directional walk/run, seated holds and declared expressions. Base it on the actual runtime; there is no universal required action count.
+4. Inventory available image/video tools, matting tools, GPU memory and disk. Reuse tested environments. Get agreement before downloading large models or changing environments. Privately record package/model versions, locations, disk changes and rollback.
+5. Pilot one combination and one short action. Pass raw playback, transparency and actual runtime gates before expanding production.
+
+Recommended private layout (a convention, not an import format):
+
+```text
+character-project/
+  project.json                 identity, outfit/action matrix, versions
+  references/<scheme>/v001.png
+  recipes/<scheme>/<action>/v001.json
+  raw/<scheme>/<action>/v001.webm
+  reviews/<scheme>/<action>/v001.json
+  alpha/<scheme>/<action>/v001/000000.png
+  staged-figure/               manifest, runtime and reviewed assets
+  wardrobe.json               mapping imported by this extension
+```
 
-Read the target figure API and vocabulary. Inventory existing animation and generation tools. Agree character identity, style, proportions, camera and intended on-screen size. Define each outfit's own controls and the complete combinations with animation resources. Use a fictional character or references the person is entitled to use.
+Keep originals and accepted versions. Avoid duplicate complete uncompressed frame caches. Keep personal production projects outside public extension repositories.
 
-Create a private project with a source manifest, environment/install inventory, generation recipes, raw clips, playback reviews, alpha sequences and a staged runtime package. Keep public extension code separate. Model weights and caches remain in their tool directories; record their locations privately instead of copying them into every project.
+## [reference] 2. Approve complete dressed references
 
-## 2. Approve complete dressed references
+Input: approved identity/style references and a complete outfit design. Output: one complete dressed image for every legal combination, plus directional references when needed.
 
-Approve a complete character reference for every legal outfit combination. Keep the same identity, proportions, camera, outlines and material rendering. Check both front and directional views when actions require them. Light fabrics need an identifiable boundary. Accessories and repeated marks must have a consistent orientation and perspective. Use a plain white background if it gives stable generation and cleaner character appearance.
+1. Keep a PNG reference master. A portrait canvas such as 768 × 1152 is a starting point, not an extension requirement; match your video workflow. Include all hair, hands and feet with breathing room.
+2. Keep camera height, framing, proportions, outlines and shading consistent across combinations. Use a neutral standing pose. Use plain white when it gives clean generation; no floor shadows, captions, watermarks or ground lines.
+3. Confirm face/hair identity, limb connections, garment silhouette, accessories and repeated mark orientation. Light fabric needs a visible drawn boundary; distinguish white material from white background. Front/side views must describe the same design.
+4. Approve the entire dressed character before animation. Record its version and SHA256. Never replace the approved reference with an old experiment.
 
-For the fictional Moss Fox, a trail outfit can have cape colour and footwear; a rain outfit can have hood position and raincoat colour; a stargazer outfit can have a visor position. These groups belong to different outfits.
+Adapt this reference-image prompt:
 
-## 3. Validate one continuous action
+```text
+The same fictional Moss Fox as the approved identity reference: orange fur,
+cream muzzle, clean dark cartoon outlines, simple shaded colours and stable
+head/body proportions. Wearing the approved leaf-green trail cape and brown
+walking boots, with the same cartoon rendering as the character. Full body,
+neutral relaxed standing pose, hands and feet visible, fixed eye-level camera,
+centered portrait framing, plain white background, no floor shadow or text.
+```
 
-Use the full dressed reference plus an action video. The action reference specifies action type, direction and rhythm. Natural changes in trajectories and cloth motion are acceptable. Use continuous video generation for the complete moving outfit. Pilot one short action and review it before expanding the action list.
+Use a clean single complete character as the identity input and a separate motion video for action. A multi-pose collage is unsuitable unless the workflow explicitly supports it.
 
-Reuse an already validated accelerated recipe. A working SCAIL-2 configuration uses 8 steps, CFG=1, shift=1 and a compatible acceleration LoRA at strength=1. Keep the exact model and node versions with the recipe. For each new action, allow at most three targeted accelerated versions, then at most two original non-accelerated 20-step versions; consider 40 steps after diagnosing remaining problems. Restore the full CFG/shift/LoRA configuration when changing recipes. Every new action starts with its fast recipe; accepted footage remains reusable regardless of its step count.
+## [video] 3. Generate one continuous action
 
-Keep retries purposeful: record the visible defect and change the prompt, seed or input that addresses it. Mark unresolved actions separately and continue other actions within the agreed compute budget.
-
-## 4. Gate on complete video playback
-
-Watch each complete raw video at normal and half speed. For loops, watch at least three consecutive cycles at both speeds. Check identity, outfit, proportions, limb connections, occlusion, missing body/fabric, flicker, abnormal colour regions, stable camera/background and natural start/end states. Assess at intended display size, with a larger view available for diagnosing visible problems.
-
-A review record contains source SHA256, resolution, frame rate, frame count, version, parameters, elapsed generation time, both playback checks, loop checks where relevant, a concrete observation and pass/fail. A still or automated score cannot fill the playback fields. Obtain user review when required by the task before expanding production.
-
-## 5. Propagate reviewed transparency locally
-
-After raw footage passes, form and visually inspect a first-frame object mask. A compact local workflow uses SAM2 tiny for the initial proposal, explicit positive/negative corrections and GrabCut on that mask, then MatAnyone2 for temporal alpha propagation. Preserve the original RGB.
-
-Inspect enclosed background gaps around limbs independently from light garments. White material must remain opaque. Where playback reveals a specific missing garment area, correct alpha inside the verified source boundary. Preserve the preceding alpha/version so the correction is reversible.
-
-Composite the entire clip against dark and saturated backgrounds and repeat normal, half-speed and loop reviews. Save lossless RGBA output plus compact review videos. Avoid accumulating multiple complete uncompressed frame caches. Downloading or installing large new tools requires the person's agreement.
-
-## 6. Integrate motion and declared expressions
-
-Give each clip a fixed whole-character uniform coordinate transform and stable ground anchor. Connect side-facing locomotion to actual horizontal translation. Validate left/right facing, long/short movements, entry, stopping, neutral recovery, turns, jump landing, sit/rise and outfit switches.
-
-Declare expression support per pose. Moving video keeps its source-native face unless a temporal face method has separately passed playback review. Standing and seated holds can use features from their own pose with measured fixed anchors. Review every declared expression for every outfit and supported pose. The acceptance manifest records missing coverage instead of treating registration as visual approval.
-
-## 7. Package and verify
-
-Validate self-contained script/image imports under the real figure sandbox and its content policy. Verify files and transferred raw footage by SHA256. Stage and validate a package before switching it into use; keep an intact previous version and prior appearance settings. Check the actual runtime rather than only standalone media.
-
-For this wardrobe extension, create a local profile mapping existing complete schemes. Figure files remain unchanged. The profile is not included in the public extension release.
-
-## 8. Publish generic tooling
-
-Publish reviewed source, generic documentation and wholly fictional demonstrations. Inspect the exact npm archive and the repository history. Exclude private character/outfit names, reference sources, user images/videos, local paths, machine names, account details, credentials, cloud addresses, chat exports, generation logs and personal profiles. Keep only a private note linking production evidence to the generalized workflow.
-
-The authoring guide is guidance, not evidence that a generated asset has passed any gate. The production record must contain the actual observations.
+Inputs: approved complete outfit image, motion reference and a saved compatible workflow. Output: one continuous raw action video retaining its original image stream and timing.
+
+1. Prepare a fixed-camera motion clip with one whole visible character, clear action/facing/rhythm and a plain white background. Trim irrelevant lead-in/out while retaining the complete action. Match duration, fps and frame count to the actual workflow; do not remove landing or return to idle.
+2. In a tested SCAIL-2 workflow, connect the complete dressed image to the character/reference-image input and the motion clip to the action-driving input. Check actual node labels and input previews in the installed version. Save the complete API workflow and pin node/model versions; there is no universally portable node-workflow JSON.
+3. With a compatible already validated accelerated recipe, start at 8 steps, CFG=1, shift=1 and compatible acceleration LoRA strength=1. This is a starting recipe, not a guarantee that arbitrary weights are compatible. Do not silently install missing models.
+4. Per new action: at most three targeted accelerated versions; then up to two original non-accelerated 20-step versions; consider 40 only after diagnosis. Restore the complete CFG/shift/LoRA recipe when switching. Each new action starts fast. Keep accepted 20/40-step footage.
+5. Reference motion specifies type, facing and rhythm. Allow natural trajectory, occlusion and cloth differences. Generate the complete dressed moving subject continuously. Do not construct the outfit body using independent frame images, texture swaps, optical-flow transport or simple stretching.
+
+Adapt this motion prompt:
+
+```text
+The same fully dressed Moss Fox throughout: same face, fur, cape, boots,
+clean cartoon outlines and proportions. Perform one friendly wave following
+the reference rhythm: neutral standing, raise one forearm, wave naturally,
+lower the arm and settle back into the same neutral stance. Fixed camera
+and scale, full body visible, plain white background. Cape follows the
+shoulder naturally; hands stay intact and connected to the arms.
+```
+
+Record workflow, model/LoRA hashes, prompts, reference hashes, seed, steps, CFG, shift, size, fps, frame count, elapsed time and retry reason. 512 × 768 at 24 fps is a workflow choice, not a wardrobe-import rule. Follow the actual model's frame-count constraints.
+
+## [review] 4. Accept complete raw playback
+
+1. Watch each entire clip at normal and half speed. For loops, play at least three consecutive cycles at each speed. Use intended pet size first and a larger diagnostic view when needed.
+2. Check identity, outfit design/colour, proportions, connected hands/feet, occlusion, intact body/fabric, flicker, abnormal colour patches, stable camera/background and natural start/end. A wave returns to its intended idle; a jump includes landing; walking has the correct facing.
+3. Write concrete pass/fail observations for both speeds and loop joins. A still, contact sheet or automatic score cannot fill playback fields. Unwatched clips remain pending.
+4. Diagnose before retrying: check identity/motion inputs, masks when used, node compatibility and prompts, then adjust the relevant cause or seed within the retry budget. Keep difficult actions separately pending rather than substituting the wrong motion.
+
+Example private review record (a project convention, not an extension schema):
+
+```json
+{
+  "scheme": "trailleafboots",
+  "action": "wave",
+  "version": "v001",
+  "sourceSha256": "<actual 64-hex SHA256>",
+  "width": 512,
+  "height": 768,
+  "fps": 24,
+  "frameCount": 73,
+  "loop": false,
+  "normalSpeed": {"result": "pending", "observation": ""},
+  "halfSpeed": {"result": "pending", "observation": ""},
+  "loopJoin": {"result": "not-applicable", "observation": "one-shot"},
+  "decision": "pending"
+}
+```
+
+Read metadata from the actual file; do not copy the example values. Hash-check transfers. Preserve accepted raw originals at their original resolution, rate and complete duration before making alpha assets.
+
+## [matte] 5. Propagate transparency locally
+
+Input: accepted raw video. Output: temporally stable alpha retaining original character RGB, plus complete playback proof on contrasting backgrounds.
+
+1. Decode at source presentation times. A confirmed constant-rate clip must not gain invented or resampled frames. For variable-rate sources, preserve timestamps or deliberately convert to a documented constant rate and recheck motion.
+2. Make an initial foreground proposal with an existing compact local model such as SAM2 tiny. Review and correct foreground/background points; GrabCut can refine a seed mask. These are separate tools, not a bundled one-click feature of this extension.
+3. Mark light clothes as foreground and white limb gaps as background. Check enclosed arm/torso and leg/garment gaps separately from the exterior. A white-colour threshold alone cannot distinguish them reliably.
+4. Propagate with MatAnyone2 or another already verified video-matting workflow. If a newly revealed gap appears later, correct an appropriate keyframe and re-propagate the segment using that tool's supported method. Do not repaint the subject independently on each frame.
+5. Preserve original RGB. Keep soft antialiasing while checking white spill. Restore verified missing cloth only inside its actual source boundary; never recolour white fabric to conceal a mask error.
+6. Save lossless RGBA PNG on the same canvas, with consistent numbering, frame count and timing metadata. Use a consistent alpha convention, normally straight alpha. JPEG cannot store transparency. Do not auto-crop or recenter every frame independently.
+7. Play the complete composite against dark grey, saturated purple/green and checkerboard backgrounds at normal and half speed, plus loop joins. Inspect background islands, missing fabric, halos, edge flicker, limb gaps and position stability. A first mask/contact sheet is insufficient.
+
+Optional extraction command for a confirmed constant-rate source; FFmpeg is a separate prerequisite. Create the destination directory first:
+
+```sh
+ffmpeg -i raw.webm -fps_mode passthrough frames/%06d.png
+```
+
+This only extracts RGB; it does not remove backgrounds. Keep one working frame cache and accepted RGBA masters rather than duplicating full sequences for every preview.
+
+## [runtime] 6. Build a working figure pack
+
+RGBA frames and wardrobe JSON do not animate by themselves. Adapt an existing compatible body's documented clip map in a private copy, or implement and test the installed figure API for a new character.
+
+The figure API 2 factory contract is:
+
+```text
+exportedFactory(base, { model, scheme, kit, loadImage, asset, host })
+  -> body with required step(dt), layout(), do(word)
+```
+
+The host loads figure.json entry and invokes its named export, supplying an asset resolver and drawing root. Declare only actually implemented words. Walking additionally needs the host's walk/stop, layout and event behaviour; drawing methods alone do not implement locomotion. Check current figure-frame.js and kit/body.js contracts for a new runtime.
+
+Directory and manifest scaffold, not a finished animated body:
+
+```text
+forest-fox/
+  figure.json
+  figure.js             implements/export createFoxBody
+  model.json            your runtime's clip map, if used
+  thumbs/trail.png
+  thumbs/rain.png
+  clips/<scheme>/<action>/000000.png
+```
+
+```json
+{
+  "manifest": 2,
+  "api": 2,
+  "id": "forest-fox",
+  "version": "1.0.0",
+  "name": {"en": "Moss Fox", "zh": "苔星狐"},
+  "about": {"en": "A fictional cartoon forest fox.", "zh": "虚构的森林狐狸。"},
+  "entry": "figure.js",
+  "export": "createFoxBody",
+  "model": "model.json",
+  "thumb": "thumbs/trail.png",
+  "axes": [{
+    "id": "appearance",
+    "name": {"en": "Appearance", "zh": "完整外观"},
+    "options": [
+      {"id": "trailleafboots", "name": {"en": "Trail"}, "thumb": "thumbs/trail.png"},
+      {"id": "rainupgold", "name": {"en": "Rain"}, "thumb": "thumbs/rain.png"}
+    ]
+  }],
+  "vocab": [],
+  "can": {"walk": false}
+}
+```
+
+The scaffold deliberately declares no completed actions. Add real vocab and walk capabilities after implementation. model.json is runtime-specific data, not a universal host video-manifest format. MP4/WebM playback is not guaranteed by the sandbox: check its CSP/asset policy or use image assets with a tested compatible runtime. Keep modules/assets in the pack; avoid external CDNs.
+
+Apply one fixed whole-character uniform transform per clip and a consistent floor anchor. Connect side-facing walk/run to actual horizontal translation. Check both directions, short/long movement, entry/stopping, turning, landing, sit/rise and outfit switches. Never auto-crop or recenter individual frames.
+
+Moving clips retain native faces unless a separately verified temporal face method is available. Idle/seated expressions require pose-specific measured anchors and review of every declared expression. Registering names is not proof of visual coverage.
+
+Install the staged figure with the host importer and verify it in the actual pet. It must appear in the local figure list and play each intended scheme before you import the wardrobe mapping in the JSON format section.
+
+## [release] 7. Import, organize and hand off
+
+1. Keep approved references, complete workflows, raw sources, hashes, generation time/cost and actual playback observations. Keep failed versions compact with defect/retry reasons.
+2. Verify the staged figure in the actual sandbox before replacing an installed copy. Preserve the old pack and appearance settings; use a reversible staged installation. Never silently rewrite built-in packs.
+3. Create schema=1 wardrobe JSON. figure is the installed pack ID; each variant points to an existing scheme. Check configuration before Import. This checks structure/IDs, not visual approval or complete animation coverage.
+4. Test each outfit's controls, supported combinations, Apply, outside native choices, Restore, disable and reactivation. Before uninstalling, Restore and verify while the pet service is available.
+5. Hand off accepted raw/alpha assets, working figure pack, local wardrobe JSON, coverage matrix and rollback note. Keep personal references/profiles outside public extension repositories.
+6. Public releases contain generic code/docs and wholly fictional examples. Audit the exact npm archive and Git history for private character/outfit names, media, machine paths, credentials, cloud addresses and chats. SHA256-check transfers. Guidance describes requirements; production observations establish acceptance.

package/docs/agent-workflow.zh.md

@@ -0,0 +1,188 @@
+# 从零制作自己的角色与装扮
+
+本手册也在扩展内显示。所有例子仅使用虚构角色“苔星狐”。本扩展提供指导、衣橱配置校验和外观切换；生图、视频生成、抠像及角色运行时代码需要使用你选择的其他工具。
+
+## [plan] 1. 明确交付物与工具
+
+最终需要两种不同的文件：能够播放动作的“形象资源包”，以及给已有搭配分组的“衣橱配置 JSON”。衣橱 JSON 不是角色资源包，导入它不会安装视频、自动换衣或生成动作。
+
+1. 已有角色新增服装：先盘点 figure.json、入口脚本、装扮 ID、动作词汇和播放器，在私有副本中扩展资源。全新角色：先完成并验收 figure API 2 资源包，再给外观分组。
+2. 确定身份、轮廓线、比例、画风、镜头和桌面实际显示大小。分别定义每套服装的配置项，例如苔星狐的探险装有斗篷和足部装备，观星装只有护目镜。只列出准备实际制作的完整搭配。
+3. 为每个完整搭配建立动作清单：一次性动作、循环动作、左右行走／跑步、坐定姿态和独立表情。以目标运行时真正支持的能力为准，没有统一的必需动作数量。
+4. 盘点已有生图工具、连续视频工作流、抠像工具、显存和磁盘。复用已验证环境；下载大模型或修改环境前先取得同意，私下记录版本、安装位置、磁盘变更和卸载回退步骤。
+5. 先拿一个搭配、一个短动作打通原视频、抠像和实际桌宠播放，再扩大制作范围。
+
+建议私有目录如下。这是整理建议，不是扩展导入格式：
+
+```text
+character-project/
+  project.json                 角色设定、搭配／动作清单、版本
+  references/<scheme>/v001.png
+  recipes/<scheme>/<action>/v001.json
+  raw/<scheme>/<action>/v001.webm
+  reviews/<scheme>/<action>/v001.json
+  alpha/<scheme>/<action>/v001/000000.png
+  staged-figure/               manifest、运行时、已验收素材
+  wardrobe.json                导入扩展的分组映射
+```
+
+保留源文件和已验收版本。完整未压缩帧只保留必要缓存，不为每个预览重复保存整套帧。公开仓库不包含个人制作工程。
+
+## [reference] 2. 先定稿完整穿衣参考图
+
+输入：已经确认的人物／画风参考和一套完整服装设计。输出：每个有效搭配的一张完整穿衣角色图，有侧向动作时补充相应方向参考。
+
+1. 参考主图建议保存 PNG。768 × 1152 竖图可作为起点，并非扩展硬性尺寸；实际视频工作流可能要求其他分辨率。头发、双手和双脚完整入镜，四周保留余量。
+2. 不同搭配保持同一镜头高度、构图、比例、轮廓线和材质画法，采用中性站姿。白底能够稳定生成时使用纯白背景，不带投影、地面线、文字和水印。
+3. 检查脸与头发身份、肢体连接、衣服结构、配件位置和重复标记朝向。浅色服装要有清晰绘制边界；不能把白色布料和白色背景混为一体。正侧视图必须是同一设计。
+4. 整张完整角色图验收后再生成动作，记录版本和 SHA256。新参考定稿后，不用旧试验图覆盖。
+
+可调整的参考图提示词：
+
+```text
+与已确认身份参考相同的虚构苔星狐：橙色皮毛、奶油色口鼻，
+清楚的深色卡通轮廓线、简洁明暗和统一头身比例。
+穿已确认的叶绿色探险斗篷和棕色步行靴，服装与角色画风一致。
+全身、中性放松站姿、手脚完整可见、固定平视镜头、竖向居中构图，
+纯白背景，没有地面投影、文字或水印。保持脸、毛发与身体比例一致。
+```
+
+通常使用一张完整角色图作为身份输入，动作视频作为动作输入。除非工作流明确支持，不把多姿势拼图送进单人物图生视频参考口。
+
+## [video] 3. 生成一个完整连续动作
+
+输入：已验收的完整穿衣图、动作参考视频、已保存的兼容工作流。输出：完整连续原视频，保留原始画面与时序。
+
+1. 动作参考只有一个角色，固定镜头，全身可见，类型、方向、节奏清楚，简单白底。裁掉无关前后内容，但保留完整动作。时长、帧率和帧数遵循实际工作流，不截掉落地或回归静止部分。
+2. 使用已跑通的 SCAIL-2 时，完整穿衣图接到角色／参考图输入，动作视频接到动作驱动输入。核对本机节点版本的真实名称和输入预览，保存完整 API 工作流与节点／模型版本。不同节点版本不能保证通用同一份工作流 JSON。
+3. 已有兼容且通过验证的加速配方时，先用 8 步、CFG=1、shift=1、对应加速 LoRA 强度=1。这是经过验证的起点，不代表任意模型与 LoRA 兼容，也不能悄悄下载缺失权重。
+4. 每个新动作先最多三版加速配置；仍不合格再最多两版原始非加速 20 步；诊断后才考虑 40 步。切换时同时恢复完整 CFG、shift 和 LoRA，不能只改步数。一个动作失败不代表其他动作都要加步，已合格的高步数素材继续保留。
+5. 动作参考只约束类型、朝向和节奏，允许新衣服的轨迹、遮挡、布料运动自然变化。完整穿衣主体通过连续视频生成，不用逐帧独立生图、贴图替换、光流搬运或简单拉伸拼出服装。
+
+可调整的连续动作提示词：
+
+```text
+始终是参考图中的同一只完整穿衣苔星狐，脸、皮毛、斗篷、靴子、
+清晰卡通轮廓和身体比例保持一致。按照参考节奏完成一次友好挥手：
+中性站姿开始，抬起一侧前臂，自然挥手，放下手臂，回到相同中性站姿。
+固定镜头和角色大小，全身完整入镜，纯白背景。
+斗篷随肩臂自然运动，双手完整并与手臂正常连接。
+```
+
+记录完整工作流、模型／LoRA 哈希、提示词、参考哈希、种子、步数、CFG、shift、尺寸、帧率、帧数、耗时和重试原因。512 × 768、24 fps 只是工作流参数示例，不是衣橱导入要求；视频帧数遵循实际模型约束。
+
+## [review] 4. 先验收原始视频
+
+1. 每条完整观看原速与半速。循环动作在两种速度下各连续至少三轮，先以桌宠实际大小观察，需要诊断时再放大。
+2. 检查身份、服装设计／颜色、比例、手脚连接、遮挡、身体／布料缺失、闪烁、异常色块、镜头／背景稳定和首尾状态。挥手回归预定静止，跳跃要有落地，行走要有正确朝向。
+3. 两种速度和循环接缝分别填写具体观察、通过／失败。抽帧、拼图、指标不能代填播放验收，没有完整看过的保持“待验收”。
+4. 先找原因再重试：核对身份图、动作输入、遮罩（若使用）、节点兼容和提示词，再在限定次数内针对性修改。难解决动作独立标记待处理，不能换成错误动作冒充完成。
+
+私有验收记录示例。这是工程整理建议，不是扩展 JSON：
+
+```json
+{
+  "scheme": "trailleafboots",
+  "action": "wave",
+  "version": "v001",
+  "sourceSha256": "<填写真实的64位十六进制SHA256>",
+  "width": 512,
+  "height": 768,
+  "fps": 24,
+  "frameCount": 73,
+  "loop": false,
+  "normalSpeed": {"result": "pending", "observation": ""},
+  "halfSpeed": {"result": "pending", "observation": ""},
+  "loopJoin": {"result": "not-applicable", "observation": "一次性动作"},
+  "decision": "pending"
+}
+```
+
+参数从实际文件读取，不照抄示例。合格原视频下载时保留原尺寸、帧率和完整时长，校验传输 SHA256，再提取透明素材。
+
+## [matte] 5. 本地连续抠像
+
+输入：通过播放验收的原视频。输出：保持原人物 RGB、时间连续的透明度序列，以及完整多背景播放检查。
+
+1. 按源时间解码。确认恒定帧率时不再采样或发明帧；可变帧率要保留时间戳，或先明确转换为恒定帧率、记录转换并重新验收动作。
+2. 用已有本地小工具（如 SAM2 tiny）得到首帧前景建议，明确添加前景／背景点，人工检查；可用 GrabCut 细化种子遮罩。这些是独立工具流程，不是扩展内置的一键抠图按钮。
+3. 浅色衣料标为前景，手臂与身体之间的白色空隙标为背景。分别检查封闭的腋下／手臂间隙、腿与衣物间隙、外轮廓，不能仅凭白色阈值区分。
+4. 用 MatAnyone2 或其他已验收视频抠像流程传播透明度。后续才出现的空隙，按工具支持的方法在合适关键帧纠正，再传播相应片段，不逐帧独立重绘人物。
+5. 保留原 RGB 和合理抗锯齿，同时检查白色污染；确认布料误删后，只在真实原边界内恢复透明度，不用染黑白衣料掩盖遮罩问题。
+6. 保存同一画布的无损 RGBA PNG 序列，连续命名，统一 alpha 约定（通常为 straight alpha），记录帧数、帧率和时间。JPEG 不支持透明度；不要逐帧自动裁边或各自平移居中。
+7. 在深灰、饱和紫／绿和棋盘格背景上，完整观看原速、半速和循环接缝。检查残留背景岛、误删衣料、白边、边缘闪烁、肢体间隙和位置抖动。首帧或缩略拼图不能代替整条验收。
+
+已有 FFmpeg 且确认源视频恒定帧率时，可这样抽帧；先创建输出目录：
+
+```sh
+ffmpeg -i raw.webm -fps_mode passthrough frames/%06d.png
+```
+
+命令只抽取 RGB，不会自动去背景。保留一份工作缓存和合格透明主素材，不为每个预览重复存整套帧。
+
+## [runtime] 6. 制作真正能播放的形象包
+
+透明帧和衣橱 JSON 本身不会动，仍需实现宿主形象运行时。已有兼容角色可在私有副本中按其播放器规则扩展映射；从零制作时先实现、测试本机安装版本的 figure API。
+
+当前 figure API 2 工厂接口：
+
+```text
+exportedFactory(base, { model, scheme, kit, loadImage, asset, host })
+  -> 必需包含 step(dt)、layout()、do(word) 的 body
+```
+
+宿主从 figure.json 的 entry 加载模块，调用 export 指定的工厂，提供本地资源解析与绘制根元素。只声明真正实现的词。行走还需要宿主所用的 walk／stop、layout、事件行为，绘制方法不等于移动。新播放器应核对当前 figure-frame.js 和 kit/body.js 契约。
+
+目录与 manifest 骨架如下，不是已完成的动画播放器：
+
+```text
+forest-fox/
+  figure.json
+  figure.js             实现并导出 createFoxBody
+  model.json            自己播放器的动作映射（若使用）
+  thumbs/trail.png
+  thumbs/rain.png
+  clips/<scheme>/<action>/000000.png
+```
+
+```json
+{
+  "manifest": 2,
+  "api": 2,
+  "id": "forest-fox",
+  "version": "1.0.0",
+  "name": {"en": "Moss Fox", "zh": "苔星狐"},
+  "about": {"en": "A fictional cartoon forest fox.", "zh": "虚构的森林狐狸。"},
+  "entry": "figure.js",
+  "export": "createFoxBody",
+  "model": "model.json",
+  "thumb": "thumbs/trail.png",
+  "axes": [{
+    "id": "appearance",
+    "name": {"en": "Appearance", "zh": "完整外观"},
+    "options": [
+      {"id": "trailleafboots", "name": {"en": "Trail"}, "thumb": "thumbs/trail.png"},
+      {"id": "rainupgold", "name": {"en": "Rain"}, "thumb": "thumbs/rain.png"}
+    ]
+  }],
+  "vocab": [],
+  "can": {"walk": false}
+}
+```
+
+骨架故意不声明已完成动作，实现后再填写真实 vocab 和移动能力。model.json 是自己播放器的数据，不是宿主通用视频清单。沙箱不保证直接支持 MP4／WebM，要核对当前 CSP／资源策略，或采用已验证的图片帧播放器。模块、资源放在包内，不依赖外部 CDN。
+
+每条动作使用固定的整体等比变换和地面锚点，侧向行走／跑步伴随实际横向移动。检查左右、短长距离、起步停步、转向、落地、坐下起身、换装，不逐帧重新裁边／居中。
+
+运动视频保留原生面部，除非另有通过验收的时间连续表情方法。站立／坐定表情使用本姿态测量锚点，逐套检查每个声明表情；注册进列表不代表视觉覆盖完整。
+
+通过宿主形象导入器安装暂存包，先在真正桌宠中验证，确认本机列表能读取它、每个目标 scheme 正常播放，再导入“衣橱 JSON”章节的映射。
+
+## [release] 7. 整理、导入与交付
+
+1. 保留合格参考、完整工作流、原视频、哈希、耗时／费用和真实播放观察；失败版本只保留必要素材及失败／重试原因。
+2. 替换前在真实沙箱校验暂存包，备份原包和外观设置，可回退安装，不悄悄改写内置角色。
+3. 创建 schema=1 衣橱配置，figure 填已安装包 ID，每个 variant 指向已有 scheme。先“校验配置”再导入；这里只校验结构／ID，不等于视频已验收或动作齐全。
+4. 检查每套服装的独立选项、有效组合、应用、原生页外部选择、恢复、停用和重启。卸载本扩展前，在桌宠服务可用时先恢复并确认。
+5. 交付合格原视频／透明素材、可运行形象包、本机衣橱 JSON、动作／表情覆盖和回退说明。个人参考、配置留在公开扩展仓库之外。
+6. 公开工具仅包含通用源码、说明和完全虚构示例。检查确切 npm 包及 Git 历史，排除个人角色／服装名、素材、机器路径、凭证、服务器地址和聊天记录。传输校验 SHA256。指南写的是要求，实际制作记录才证明已通过验收。

package/docs/lifecycle.md

@@ -6,6 +6,8 @@ Wardrobe Studio reads a local desktop-pet HTTP service at a configurable loopbac
 
 Importing a profile writes `wardrobe-studio/profiles.json` under the extension's supplied data directory. Applying a combination uses the desktop pet's standard appearance API; this changes its selected figure/scheme as an ordinary wardrobe selection does. It never edits the original figure manifest, assets, code, other extensions or the application.
 
+The extension defaults to Chinese independently of the host language. Its Chinese/English selector stores only `{language}` in its own `wardrobe-studio/preferences.json`, shared by both panels and retained across restart. It does not change the host language, profiles or appearance. Imported names remain user-provided text. Switching panel language preserves the pending outfit selection and JSON draft.
+
 Before the first change, a write-ahead lease saves the previous figure/scheme and intended change to `wardrobe-studio/lease.json`. Subsequent changes owned by this extension retain that original restoration target. Requests are serialized. Other skin preferences are read afresh and preserved.
 
 ## Stop, disable and uninstall