Coo 形象包机制与 Live2D 接入研究：从清单、Body 契约到 PSD 自动转换

[DanieleWolfHOLO]

把这段时间对 Coo 形象包机制和 Live2D 接入的梳理写成了一份研究报告，发在这里想和作者、以及做形象包的朋友对一对。原报告含 3 张运行截图，本帖从略。

这是一份社区技术整理，不是 Coopanion 官方文档。 基于 Coopanion 0.2.13 的安装目录源码与「酒狐第 1 版」形象包写成，写作于 2026-10-29。0.2.14 对形象包的文件读取做了一处重要放宽，相关差异集中在文末「版本注记」，正文仍按 0.2.13 的边界描述。

——从清单、Body 契约到 PSD 自动转换与运行时边界

技术整理：Daniele贤狼赫萝 & DeepSeek Harness
研究对象：Coopanion / Cortico desktop-pet 形象包体系
版本：1.0
日期：2026 年 10 月 29 日

导读：先用一句话说清楚

如果把 Coo 想象成一个舞台，那么“形象包”就是上台表演的演员。

Coo 不关心演员长什么样，它只关心三件事：演员站在哪、朝哪边、现在在做什么动作。形象包负责回答这三件事，并把自己画出来。

所以，形象包不是一张图片，也不是一个 Live2D 文件，而是一个小文件夹：

• figure.json：演员说明书，告诉 Coo 入口在哪、叫什么名字；
• figure.js：演员本体，负责画自己、动起来、响应表情词；
• model.json / tex：演员的零件和贴图，可选。

Coo 自带一个“身体引擎”（body.js）和一个“网格渲染器”（rig.js）。形象包可以用它们，也可以完全不用，自己拿 canvas 或 WebGL 画。Live2D 属于后者：它不是引擎自带能力，而是一个能接管绘制的形象包。

摘要

本文以 Coopanion 0.2.13 / Cortico desktop-pet 的实际源码为对象，梳理 Coo 形象包的加载链路、清单格式、Body 契约、绘制模式、沙箱与安装切换机制。在此基础上，分析 Live2D 模型接入 Coo 的两种路线：A 方案由形象包内嵌/加载用户自备的 Cubism Core，B 方案将模型重建为 Coopanion 的 puppet 格式。文章还记录了 PSD 自动拆层、模板模式、通用近似特效与 Figure Importer 插件的实现边界，并给出授权、版权、Expandable Application、AGPL 与安全方面的注意事项。

关键词：Coopanion；Cortico；形象包；Body 契约；puppet；Live2D；Cubism Core；PSD 自动转换

1 引言

Coo 是 Coopanion 的桌面宠物角色。它看起来只是一个会说话、会走路的小人，但实际运行时分成了多层：Electron 外壳、Cortico World、桌面宠物服务、形象包沙箱，以及形象包自己的绘制代码。理解这些层之间的关系，是判断“能不能装 Live2D”“能不能自动转换 PSD”“引擎到底是谁的”等问题的前提。

本文不讨论 Coopanion 的对话、语音、QQ 或电脑操作能力，只聚焦形象包机制。资料来源是当前安装目录中的实际文件，而不是产品宣传页：

• web/figure-frame.js：形象包沙箱与 Body 契约；
• web/kit/body.js：身体模拟、表情、粒子、交互；
• web/kit/rig.js：2D 贴图网格与 rot/warp 变形器；
• web/coo/figure.js、web/whale/figure.js：两个内置形象示例；
• Daniele贤狼赫萝提供的「酒狐第 1 版」形象包与 PSD。

2 系统分层与加载链路

2.1 四层结构

可以把系统分成四层：

层	职责	典型文件
Coo 应用	窗口、World 服务、对话与桌面交互	Coopanion 主程序
桌面宠物 World	舞台、形象包管理、皮肤状态、安装/切换	src/server.ts、src/packs.ts
形象包沙箱	加载 pack 的 JS，执行 Body 契约，隔离网络	web/figure-frame.js
形象包	自己的绘制、模型、贴图、动作词	figure.json、figure.js、model.json

2.2 加载链路

一次形象包加载大致经过以下步骤：

figure.json
  -> figure-frame 读取 manifest
  -> import(entry) 并取 export 函数
  -> factory(base, { model, scheme, kit, loadImage, asset, host })
  -> 返回 body
  -> 每帧调用 body.step(dt)
  -> 读取 body.layout() 决定位置、朝向、命中、气泡
  -> 词表触发 body.do(word)

其中 kit 由宿主注入，包含 createBody 与 createRig。形象包可以选择使用，也可以完全忽略。

2.3 引擎归属

本文对照的 body.js / rig.js 来自：

packages/cortico-world-desktop-pet/web/kit

Coo 自己的 web/coo/figure.js 调用 kit.createBody；鲸鱼 web/whale/figure.js 使用 createRig；酒狐包同样通过 opts.kit.createBody / opts.kit.createRig 使用这套 kit。酒狐包本身不包含 body.js / rig.js 的源码，它只是调用宿主提供的 kit。

结论：这套引擎是 Coopanion 桌面宠物 World 自带的公共 puppet 引擎，不是酒狐包或 DSH 私有引擎。其许可证为 AGPL-3.0-or-later。

3 形象包规范

3.1 目录与清单

一个最小形象包可以只有清单和入口；带自绘模型的包通常还会有 model.json、贴图和缩略图。

文件/目录	必需	作用
figure.json	是	清单：id、名称、入口、导出、模型、词表、轴
figure.js	是	入口模块，导出 factory
model.json	否	形象包自己的模型数据，Coo 解析后传给 factory
tex/*.png	否	贴图、部件图、表情图
thumb.png	否	装扮页缩略图

figure.json 的骨架如下：

{
  "manifest": 2,
  "api": 2,
  "id": "my_figure",
  "name": { "zh": "我的形象", "en": "My Figure" },
  "about": { "zh": "...", "en": "..." },
  "entry": "figure.js",
  "export": "createMyBody",
  "model": "model.json",
  "thumb": "thumb.png",
  "vocab": [],
  "axes": []
}

id 必须匹配 ^[a-z0-9][a-z0-9-]{0,31}$：小写字母/数字开头，只含小写字母、数字、连字符，最长 32 字符。中文文件名直接转 id 容易产生非法值，需要清洗或加前缀。

3.2 Factory 契约

入口函数签名是固定的：

export async function createMyBody(base, opts) {
  // base: pack 的基准 URL
  // opts: { model, scheme, kit, loadImage, asset, host }
  return {
    step(dt) {},
    layout() { return { x: 128, facing: 1, mode: 'idle' }; },
    do(word) {},
  };
}

step / layout / do 是必需方法。可选能力包括 resize、walk、set、words、gestures、colors、anchors、extent、hits、snapshot、preload、reset 等。

3.3 Body 与 Layout

Coo 只通过 layout 认识形象，而不关心内部是 SVG、Canvas 还是 WebGL。常用字段如下：

字段	含义
x / facing	舞台位置与朝向（1 右，-1 左）
mode	idle / walk / run / sit / sleep / drag / air 等
busy / moving	是否在忙、是否在移动
box	整体范围，用于裁剪/命中
hit	点击命中圆或矩形
bubble	气泡锚点
side	悬停按钮所在侧

3.4 三种绘制方式

形象包有三种典型实现：

（1）kit.createBody：只画，不管运动

Coo 自己的形象属于这一类。createBody 负责走路、坐下、表情、粒子、拖拽、阴影，形象只需要实现 figure.draw。

（2）kit.createRig：网格 + 变形器

鲸鱼和酒狐属于这一类。部件是矩形贴图 + 网格，变形器只有 rot / warp，物理由 JS 弹簧计算。它是 Live2D-like，但不是 Cubism。

（3）完全自绘

形象包可以忽略 kit，自己创建 canvas / SVG / WebGL，自己实现 step / layout / do。Live2D 适配包必须走这条路，因为它需要 Cubism Core 解析 moc3。

3.5 沙箱与资源

形象包运行在 opaque origin 的 iframe 中。0.2.13 及更早版本的 CSP 禁止一切 fetch，只允许来自 pet server 的脚本和图片；0.2.14 起允许 fetch 读取本包目录下的文件（见文末「版本注记」）。无论哪个版本，都意味着：

• 不能从 CDN 拉取 Core、moc3 或贴图；
• 模型、贴图、motion 必须在本机或包内；
• 不能写入服务器，不能读本地任意文件；
• 视频、音频元素和字体不能直接加载；声音要在 figure.json 的 sounds 里声明，由桌宠页播放。

3.6 安装与切换

内置包位于 web/coo、web/whale；导入包解压到 figures/。服务端接口负责列出、导入、安装和切换：

/api/figures
/api/figures/import
/api/figures/import/install
/api/skin

切换皮肤时，figure 字段决定形象，scheme 决定配色/服装；axes 定义可选值，vocab 决定 bot 能使用哪些表情/动作词。

4 Live2D 接入 Coo

4.1 为什么需要 Cubism Core

Live2D 模型包通常只包含 model3.json、moc3、贴图、motion 和 physics。moc3 是编译后的模型数据，本身不是可执行程序。Cubism Core 负责解析 moc3、计算 ArtMesh/变形/参数，再把可绘制数据交给渲染器。因此，只要模型仍然是 moc3，运行时就需要 Core。

模型包通常不包含 Core；Core 是单独的 SDK 运行时文件，例如 live2dcubismcore.min.js。

4.2 A 方案：Cubism 包装

A 方案写一个 Live2D 形象包：

• 在 foreignObject 中放 canvas；
• 加载用户提供的 Cubism Core；
• 读取 model3.json / moc3 / 贴图 / motion；
• 每帧 update + draw；
• 实现 step / layout / do，把 Coo 的 idle / walk / sit / 表情映射到 Live2D 参数。

这条路线保留原模型的 motion / physics，但需要处理 Core 授权、包体大小、沙箱 CSP、低配设备性能与状态映射。

4.3 B 方案：重建为 puppet

B 方案把 Live2D 模型拆成 PNG 部件，重新建立 Coopanion 的 puppet：

• 没有 Cubism Core；
• 没有原 motion / physics；
• 用 createRig 的网格、枢轴、弹簧重建；
• 性能更好、包开放、可编辑、可开源。

PSD 是 B 方案最干净的输入；如果只有 moc3，则先需要官方 Cubism 工具或离线烘焙，不能直接解析。

4.4 授权边界

Live2D 的 Open Software License 不是开源许可证；Core 仍是专有软件。把 Core 提交到 MIT 仓库、随 Release 分发、或用开源许可证再发布，都可能违反许可。较稳的架构是：

开源适配层（MIT）
+ 用户自行提供官方 Cubism Core
+ 不内置、不下载、不托管 Core
+ 不代替用户签约
+ 生成包只保存在本机

注意：不分发 Core 会显著降低风险，但不自动等于“不需要任何协议”。是否构成衍生作品、是否需要 Publication License，应以 Live2D 的书面回复为准。

5 PSD 自动转换与效果实现

5.1 PSD 到 puppet 的流水线

自动转换的目标不是“复制一张图”，而是把分层 PSD 变成可动的部件：

PSD
 -> 读取图层
 -> 按名字/包围盒识别 body/head/hair/arm/leg/skirt
 -> 导出 PNG
 -> 生成 puppet.json（parts/grid/pivots/deformers/physics）
 -> 生成 figure.json + 通用 figure.js
 -> 安装、切换

默认 standard 档：身体/头 6×6，头发 10×12，裙摆 8×10，按部件启用弹簧。对于合并层，可按 alpha 连通域或模板固定框拆分左右。

5.2 模板模式

酒狐第 1 版是手工校准的完整 rig：实时画脸、fxG、头发/尾巴/耳朵/小狐狸弹簧、腿部折叠。模板模式只替换贴图，复用 model.json 与 figure.js：

• 按模板 units/pivots 计算每个部件的 PSD 裁剪框；
• 从合并层裁出 arm_L/R、leg_L/R、shoe_L/R、ear_L/R、眼睛和眉毛；
• 复用模板的 23 个纹理资产与特效代码；
• 不匹配模板时自动退回基础模式。

5.3 通用近似特效

不匹配模板的 PSD 会走基础 puppet。运行时额外提供一层与模型无关的 SVG 特效：绕头星星、思考气泡、冷汗、怒气、问号/感叹号、倾听弧线、sparkle；以及 puppet.json 中定义的弹簧。

通用模式目前不包含实时画脸；脸仍是 PSD 静态图层。它是“近似特效”，不是第 1 版的完整画脸。

5.4 Figure Importer 插件

插件把“选 PSD / 装包 / 换皮肤”串成一条本地流程：

• 监听 data/figure-inbox/ 或让用户选择 PSD；
• 自动清洗 id（中文、下划线、长度、开头字符）；
• 模板模式优先，失败回退基础 puppet；
• 调用 /api/figures/import + install 安装；
• 调用 /api/skin 切换；失败尝试回滚；
• Live2D A 窗口只提供 Core/模型选择与官方许可入口，不内置 Core。

6 注意事项与风险

以下问题在实现和发布前必须明确。

主题	注意事项	建议
Cubism Core	专有运行时；不能随 MIT 仓库/Release 分发	用户自备 Core；不内置、不下载、不托管
模型版权	moc3/贴图/motion 版权归原作者；转换不等于获得授权	只处理用户有权使用的模型；不提供模型下载
开源 ≠ 无版权	公开仓库、无 LICENSE、社区默认都不等于授权	检查 LICENSE；没有许可就按保留所有权利处理
Expandable Application	可生成不确定数量模型的应用可能需要单独审查	向 Live2D 书面确认，不要假设个人非商业免签
引擎许可	body.js/rig.js 为 AGPL-3.0-or-later	修改/分发/网络服务遵守 AGPL；不能改成 MIT
模板素材	酒狐模板归模板作者所有	发布时明确其许可证；不要默认套 MIT
沙箱	figure frame 无任意外联、无写入；0.2.14 起只可读本包目录	Core、moc3、贴图本地化；不要依赖 CDN
自动推断	左右拆分、五官、pivots 可能偏；复杂遮挡会穿模	UI 标注“近似”，保留基础模式回退
性能	每帧 canvas 上传、过多纹理、过高网格会拖慢	缓存静态层、纹理图集、限制网格/帧率

6.1 技术安全

自动转换器不应执行 PSD/Live2D 内的任意脚本；解析应放在受限进程，限制文件大小、图层数和超时。ZIP 导入要防目录穿越；生成包只能写入指定目录。形象包沙箱不允许任意外联和写入（0.2.14 起只可读本包目录），但插件侧仍要校验路径。

6.2 性能

酒狐模板的每帧画脸会把 canvas 重新上传为纹理；这是它昂贵的地方。通用 puppet 的静态贴图更轻。若要做通用画脸，建议缓存静态脸部、只在眨眼/口型变化时更新纹理，并限制网格数量。

7 结论

Coo 的形象包机制不是“加载某个模型格式”，而是“加载一个实现 Body 契约的 JS 包”。它自带 body.js/rig.js 这套 puppet 引擎，但允许形象包完全接管绘制。Live2D 能装进 Coo，靠的是自定义 Live2D pack + 用户自备 Cubism Core，而不是引擎原生支持。

PSD 自动转换走的是另一条路：把分层图变成 Coopanion 的 puppet，没有 Core、没有 Live2D 运行时，代价是失去原 motion/physics。酒狐第 1 版是这条路线的手工校准模板；通用模式只能做到近似特效，不能保证每个 PSD 都达到同样质量。

因此，工程上最稳的组合是：Coo 自带引擎 + 开放 puppet 格式 + 模板模式（完整特效）+ 通用近似模式（回退）+ Live2D A 窗口（用户自备 Core）。法律上则要分别处理 Core、模型、引擎 AGPL、模板素材与 Expandable Application，不能用一个“非商业”结论覆盖全部。

附录 A 最小 Body 骨架

export async function createMyBody(base, opts) {
  const host = opts.host;
  const root = host.root;
  return {
    step(dt) {
      // 推进动画、更新 SVG/Canvas
    },
    layout() {
      return {
        x: 128, facing: 1, mode: 'idle',
        box: [0, 0, 256, 256],
        hit: [[128, 128, 100]],
        bubble: [128, 0],
      };
    },
    do(word) {
      // 响应表情/动作词
    },
  };
}

附录 B puppet.json 字段

{
  "version": 1,
  "profile": "standard",
  "canvas": [0, 0, 256, 256],
  "ground": 256,
  "parts": [
    { "id": "body", "texture": "tex/body.png",
      "box": [64, 96, 128, 144], "grid": [6, 6],
      "z": 10, "parent": "body" }
  ],
  "deformers": {
    "body": { "kind": "rot", "pivot": [128, 240] }
  },
  "physics": [
    { "deformer": "hairSway", "stiffness": 16, "damping": 6, "limit": 16 }
  ]
}

附录 C 源码与资料

packages/cortico-world-desktop-pet/web/figure-frame.js
packages/cortico-world-desktop-pet/web/kit/body.js
packages/cortico-world-desktop-pet/web/kit/rig.js
packages/cortico-world-desktop-pet/web/coo/figure.js
packages/cortico-world-desktop-pet/web/whale/figure.js

Live2D 官方资料：

https://www.live2d.com/zh-CHS/sdk/license/

https://www.live2d.com/eula/live2d-open-software-license-agreement_cn.html

版本注记：0.2.14 放开了包内文件读取

本文写作时对照的是 0.2.13。2026-10-29 发布的 0.2.14 改了一条关键边界：

• 形象包的页面现在可以用 fetch 读取自己目录内的文件，官方发布说明举的例子正是 Live2D 模型和贴图（/figure-frame 的 connect-src 能否放开到 'self'：现在形象包没法读自己的资源文件 #469）；
• 仍然读不到其他形象包，也读不到 Coopanion 自己的接口；
• 0.2.13 及更早版本不允许任何 fetch，当时要把 moc3 放进包里，只能把它转成 model.moc3.js 这样的 base64 模块再 import。

对本文第 4 节的影响很直接：A 方案不再需要为了兼容 0.2.13 而把模型和贴图全部 base64 内联，model3.json、moc3、贴图、motion 可以直接放在包目录里按需读取。但 Cubism Core 的授权边界没有变——Core 仍是专有运行时，仍然建议由用户自备、不随包分发。截至本文发布，最新版是 0.2.15。

想听听大家的意见

1. Live2D 的归属：在 api: 2 的兼容承诺下，Live2D 更适合继续做社区 pack，还是值得提供一个可选的官方 kit.createLive2D？前者不动契约，后者能统一 Core 加载与授权提示，但会把专有运行时带进官方边界。
2. 包内大文件的做法：0.2.14 之后，moc3 / 贴图直读的推荐上限是多少（导入上限是 128 MB，但运行时内存和首帧时间另算）？还需要继续鼓励 base64 JS 来兼容 0.2.13 吗？
3. 模板格式：模板模式的 units / pivots / effects 有没有机会沉淀成一种可共享的模板格式，让第三方模板包也能复用，而不是只认「酒狐第 1 版」？
4. PSD 自动转换的验收标准：哪些部件（脸、手指、裙摆、合并层）必须人工校准？社区能不能一起做一组标好层的测试 PSD，作为转换器的回归基准？
5. Core 授权：不分发 Core、只做适配层的做法，是否已有社区案例或 Live2D 的书面回复可以参考？「Expandable Application」的边界有没有更明确的解释？

---

本文是技术整理，不构成法律意见；Live2D 授权、模型版权、AGPL 义务与 Expandable Application 的最终判断，应以官方书面回复和合同为准。

[Phantivia]

谢谢这份整理。几个问题的答复:

1. Live2D 继续留给社区形象包来做，官方不出 kit.createLive2D,专有运行时不进官方的代码。
2. 形象包导入的 128 MB 上限下个版本取消，超过 128 MB 时确认框里会提示体积。0.2.14 起形象包可以 fetch 自己目录里的文件，不需要再为 0.2.13 把模型和贴图内联成 base64。
3. 模板格式和 PSD 自动转换的验收标准，现在没有计划。
4. Live2D 的授权问题，官方不提供意见。