cortico-world-ellen-voice 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0
+
+- 新增 `ellen_install_figure`：把一张透明底 PNG 立绘装成 Coopanion 形象包（自动生成 figure.json、
+  model.json、全部骨架贴图与缩略图），装完即可在「装扮」页选中。
+- 附带极简 PNG 编解码（`src/png.ts`，只依赖 node:zlib），不引入任何第三方依赖；
+  支持 8/16 位、灰度/RGB/调色板/RGBA、非隔行。
+- 新增设置项 `figuresDir`：留空时按 Coopanion.exe 所在目录推断 `data\home\companion\data\figures`。
+- 扩展仍不附带任何角色美术：模板目录里只有两份 JSON 和贴图清单，图片由使用者自己提供。
+
 ## 0.1.0
 
 - 首个版本：`ellen_speak` 合成语音并作为附件交回模型，`ellen_send_voice` 直接发 QQ 语音条。

package/README.md

@@ -20,9 +20,19 @@ TTS 代理可以是任何返回音频字节的 HTTP 服务：GPT-SoVITS 微调
 - **ellen_speak** `{ text, lang? }`：合成语音，把音频作为附件交回模型。
   模型拿到的是 `log:` 句柄，可以再交给 `qq_draft(voice=<句柄>)` 走草稿确认。
 - **ellen_send_voice** `{ text, to?, group?, lang? }`：合成 + 直接发语音条，一步到位。
+- **ellen_install_figure** `{ path, id, name, overwrite? }`：把一张**透明底 PNG** 立绘装成形象包。
+  装出来的包放在 `data\home\companion\data\figures\<id>\`，装完在「装扮」页就能选。
+  做法是把图等比缩到 847×859 的画布，骨架贴图全部写成透明占位——所以是静态立绘，不会换姿势。
 
 语言缺省 `auto`，支持 `zh` / `ko` / `en` / `ja`。
 
+## 关于形象
+
+本扩展**不附带任何角色美术**。`template/` 里只有两份 JSON 和一份贴图清单，没有图；
+立绘由使用者自己提供（自绘、委托画师，或按所在地区的同人规则使用官方素材——后者请自行确认授权）。
+
+白底图需要先抠成透明底再喂给 `ellen_install_figure`，工具不替你做抠图。
+
 ## 配置
 
 在 Coopanion 的扩展设置里填：
@@ -33,6 +43,7 @@ worlds.ellen-voice.oneBotUrl       OneBot 正向 WS 地址
 worlds.ellen-voice.token           OneBot access token（可空）
 worlds.ellen-voice.maxChars        单次合成字数上限（默认 200）
 worlds.ellen-voice.defaultPrivate  默认私聊 QQ 号
+worlds.ellen-voice.figuresDir      形象安装目录（留空按程序目录推断）
 ```
 
 ## 许可

package/package.json

@@ -1,38 +1,40 @@
-{
-    "name":  "cortico-world-ellen-voice",
-    "version":  "0.1.0",
-    "type":  "module",
-    "description":  "Ellen Joe voice world for Coopanion: speak through a local GPT-SoVITS service and deliver voice bars to QQ",
-    "author":  "deepseek study",
-    "license":  "MIT",
-    "main":  "./src/index.ts",
-    "keywords":  [
-                     "cortico-world",
-                     "cortico",
-                     "tts",
-                     "qq",
-                     "voice"
-                 ],
-    "engines":  {
-                    "node":  "\u003e=22"
-                },
-    "cortico":  {
-                    "kind":  "world",
-                    "api":  6,
-                    "displayName":  "艾莲语音",
-                    "icon":  "src/icon.svg",
-                    "describe":  "describe.json",
-                    "tags":  [
-                                 "voice",
-                                 "qq",
-                                 "external-setup"
-                             ]
-                },
-    "files":  [
-                  "src",
-                  "describe.json",
-                  "README.md",
-                  "CHANGELOG.md",
-                  "LICENSE"
-              ]
-}
+{
+    "name":  "cortico-world-ellen-voice",
+    "version":  "0.2.0",
+    "type":  "module",
+    "description":  "Ellen Joe voice world for Coopanion: speak through a local GPT-SoVITS service, deliver voice bars to QQ, and install a figure pack from your own PNG",
+    "author":  "deepseek study",
+    "license":  "MIT",
+    "main":  "./src/index.ts",
+    "keywords":  [
+                     "cortico-world",
+                     "cortico",
+                     "tts",
+                     "qq",
+                     "voice",
+                     "figure"
+                 ],
+    "engines":  {
+                    "node":  "\u003e=22"
+                },
+    "cortico":  {
+                    "kind":  "world",
+                    "api":  6,
+                    "displayName":  "艾莲语音",
+                    "icon":  "src/icon.svg",
+                    "describe":  "describe.json",
+                    "tags":  [
+                                 "voice",
+                                 "qq",
+                                 "external-setup"
+                             ]
+                },
+    "files":  [
+                  "src",
+                  "template",
+                  "describe.json",
+                  "README.md",
+                  "CHANGELOG.md",
+                  "LICENSE"
+              ]
+}

package/src/config.ts

@@ -12,6 +12,8 @@ export interface EllenVoiceConfig {
   maxChars: number;
   /** 默认私聊对象；调用 ellen_send_voice 不给 to 时用它。 */
   defaultPrivate: string;
+  /** 形象包安装目录；留空时按 Coopanion 程序所在目录自动推断。 */
+  figuresDir: string;
 }
 
 export const ELLEN_DEFAULTS = {
@@ -21,4 +23,5 @@ export const ELLEN_DEFAULTS = {
   token: '',
   maxChars: 200,
   defaultPrivate: '',
+  figuresDir: '',
 } as const satisfies EllenVoiceConfig;

package/src/definition.ts

@@ -48,11 +48,31 @@ export const ELLEN_TOOL_DECLS = {
     },
     tags: ['speak', 'act'],
   } satisfies Omit<ToolDef, 'handler'>,
+  install: {
+    name: 'ellen_install_figure',
+    description:
+      '把一张透明底 PNG 立绘装成 Coopanion 的形象包（生成 figure.json / model.json / 贴图），' +
+      '装好后在「装扮」页的头像列表里就能选。扩展本身不附带任何角色美术，图片由使用者自己提供；' +
+      '只接受透明底 PNG，白底图请先抠图。',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: '立绘 PNG 的绝对路径' },
+        id: { type: 'string', description: '包 id，小写字母和数字，例如 ellen' },
+        name: { type: 'string', description: '展示名，例如 艾莲·乔' },
+        overwrite: { type: 'boolean', description: '已存在同名包时是否覆盖' },
+      },
+      required: ['path', 'id', 'name'],
+      additionalProperties: false,
+    },
+    tags: ['setup'],
+  } satisfies Omit<ToolDef, 'handler'>,
 };
 
 export const ELLEN_TOOL_LIST: ReadonlyArray<Omit<ToolDef, 'handler'>> = [
   ELLEN_TOOL_DECLS.speak,
   ELLEN_TOOL_DECLS.send,
+  ELLEN_TOOL_DECLS.install,
 ];
 
 export const EllenVoice: WorldDefinition<EllenVoiceConfig> = {
@@ -73,6 +93,10 @@ export const EllenVoice: WorldDefinition<EllenVoiceConfig> = {
         zh: '合成语音并直接以语音条发到 QQ 私聊或群。',
         en: 'Synthesises speech and sends it as a voice bar to a QQ private chat or group.',
       },
+      ellen_install_figure: {
+        zh: '把一张透明底 PNG 立绘装成 Coopanion 形象包。',
+        en: 'Turns a transparent-background PNG into a Coopanion figure pack.',
+      },
     }),
     events: [
       {

package/src/figure-pack.ts

@@ -0,0 +1,127 @@
+/**
+ * 形象包生成器：把用户给的一张透明底 PNG 变成 Coopanion 能读的 figure 包。
+ *
+ * 包的结构照抄本目录 template/（figure.json、model.json、textures.json 里列的骨架贴图名称），
+ * 其中 tex/figure.png 换成用户那张图，其余贴图写成 1×1 透明像素——骨架还在，但只看得见图本身。
+ * 扩展不附带任何角色美术，图由使用者自己提供。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { blankPng, decodePng, encodePng, fitIntoCanvas } from './png.ts';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** 骨架画布尺寸，与模板里的 model.view（268×272）× 3.16 像素单位对齐。 */
+const CANVAS = { width: 847, height: 859 };
+const THUMB = 144;
+
+export interface InstallOptions {
+  /** 源图片（透明底 PNG）绝对路径。 */
+  source: string;
+  /** 包 id，小写字母数字短横，例如 ellen。 */
+  id: string;
+  /** 展示名，例如 艾莲·乔。 */
+  name: string;
+  /** figures 根目录（Coopanion 的 data/home/companion/data/figures）。 */
+  figuresDir: string;
+  /** 已存在的包是否覆盖。 */
+  overwrite: boolean;
+}
+
+export interface InstallResult {
+  dir: string;
+  files: number;
+  canvas: { width: number; height: number };
+  sourceSize: { width: number; height: number };
+}
+
+function templateDir(): string {
+  const candidates = [
+    join(HERE, '..', 'template'),
+    join(HERE, '..', '..', 'template'),
+  ];
+  for (const dir of candidates) {
+    if (existsSync(join(dir, 'figure.json'))) return dir;
+  }
+  throw new Error('扩展缺少 template/（figure.json、model.json、textures.json）');
+}
+
+function readJson<T>(path: string): T {
+  return JSON.parse(readFileSync(path, 'utf8')) as T;
+}
+
+/** 校验 id：Coopanion 的选项 id 只接受小写字母和数字（含短横会整体拒绝）。 */
+export function normalizeId(raw: string): string {
+  const cleaned = String(raw ?? '').trim().toLowerCase().replace(/[^a-z0-9]/g, '');
+  if (!cleaned) throw new Error('id 不能为空：只能用小写字母和数字');
+  if (cleaned.length > 32) throw new Error('id 太长：最多 32 位');
+  return cleaned;
+}
+
+export function installFigure(options: InstallOptions): InstallResult {
+  const id = normalizeId(options.id);
+  const name = String(options.name ?? '').trim() || id;
+  const sourcePath = resolve(options.source);
+  if (!existsSync(sourcePath)) throw new Error(`找不到图片：${sourcePath}`);
+
+  const sourceImage = decodePng(readFileSync(sourcePath));
+  const figure = fitIntoCanvas(sourceImage, CANVAS.width, CANVAS.height, 0.94);
+  const thumb = fitIntoCanvas(sourceImage, THUMB, THUMB, 0.92);
+
+  const packDir = join(options.figuresDir, id);
+  if (existsSync(packDir) && !options.overwrite) {
+    throw new Error(`形象包已存在：${packDir}（overwrite=true 可覆盖）`);
+  }
+
+  const tpl = templateDir();
+  const figureJson = readJson<Record<string, unknown>>(join(tpl, 'figure.json'));
+  const modelJson = readJson<Record<string, unknown>>(join(tpl, 'model.json'));
+  const textures = readJson<string[]>(join(tpl, 'textures.json'));
+
+  const thumbRel = `thumbs/${id}.png`;
+  figureJson.id = id;
+  figureJson.name = { zh: name, en: name };
+  figureJson.thumb = thumbRel;
+  figureJson.version = String(figureJson.version ?? '0.1.0');
+
+  const axes = figureJson.axes as Array<Record<string, unknown>> | undefined;
+  const schemeAxis = axes?.find((axis) => axis.id === 'scheme');
+  if (schemeAxis) {
+    schemeAxis.options = [{ id: 'deepseek', name: { zh: name, en: name }, thumb: thumbRel }];
+    delete schemeAxis.source;
+  }
+  figureJson.presets = [];
+
+  const schemes = modelJson.schemes as Array<Record<string, unknown>> | undefined;
+  if (Array.isArray(schemes) && schemes.length > 0) {
+    for (const scheme of schemes) scheme.label = name;
+  }
+
+  mkdirSync(join(packDir, 'tex'), { recursive: true });
+  mkdirSync(join(packDir, 'thumbs'), { recursive: true });
+
+  const blank = blankPng();
+  let files = 0;
+  for (const rel of textures) {
+    const target = join(packDir, rel);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, blank);
+    files += 1;
+  }
+
+  writeFileSync(join(packDir, 'tex', 'figure.png'), encodePng(figure));
+  files += 1;
+  writeFileSync(join(packDir, thumbRel), encodePng(thumb));
+  files += 1;
+  writeFileSync(join(packDir, 'figure.json'), JSON.stringify(figureJson, null, 2), 'utf8');
+  writeFileSync(join(packDir, 'model.json'), JSON.stringify(modelJson), 'utf8');
+  files += 2;
+
+  return {
+    dir: packDir,
+    files,
+    canvas: CANVAS,
+    sourceSize: { width: sourceImage.width, height: sourceImage.height },
+  };
+}

package/src/png.ts

@@ -0,0 +1,218 @@
+/**
+ * 极简 PNG 编解码（不依赖任何第三方库）。
+ *
+ * 只做形象安装用到的那点事：把用户给的 PNG 解成 RGBA、按目标尺寸缩放、再编码回 PNG。
+ * 支持 8/16 位、颜色类型 0（灰度）、2（RGB）、3（调色板）、6（RGBA）、非隔行。
+ * 不支持 APNG、16 位小端以外的异常组合、隔行（Adam7）——遇到就报错，让用户重新导一张。
+ */
+import { deflateSync, inflateSync } from 'node:zlib';
+
+export interface RgbaImage {
+  width: number;
+  height: number;
+  /** 逐像素 RGBA，长度 = width * height * 4。 */
+  data: Uint8Array;
+}
+
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+const CRC_TABLE = (() => {
+  const table = new Int32Array(256);
+  for (let n = 0; n < 256; n += 1) {
+    let c = n;
+    for (let k = 0; k < 8; k += 1) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c;
+  }
+  return table;
+})();
+
+function crc32(buf: Buffer): number {
+  let c = -1;
+  for (let i = 0; i < buf.length; i += 1) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+function paeth(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}
+
+/** 解 PNG 为 RGBA。 */
+export function decodePng(input: Uint8Array): RgbaImage {
+  const buf = Buffer.from(input);
+  if (buf.length < 8 || !buf.subarray(0, 8).equals(SIGNATURE)) throw new Error('不是 PNG 文件');
+
+  let offset = 8;
+  let width = 0;
+  let height = 0;
+  let bitDepth = 8;
+  let colorType = 6;
+  let interlace = 0;
+  let palette: number[] | null = null;
+  let trns: number[] | null = null;
+  const idat: Buffer[] = [];
+
+  while (offset + 8 <= buf.length) {
+    const length = buf.readUInt32BE(offset);
+    const type = buf.toString('ascii', offset + 4, offset + 8);
+    const body = buf.subarray(offset + 8, offset + 8 + length);
+    offset += 12 + length;
+
+    if (type === 'IHDR') {
+      width = body.readUInt32BE(0);
+      height = body.readUInt32BE(4);
+      bitDepth = body[8];
+      colorType = body[9];
+      interlace = body[12];
+    } else if (type === 'PLTE') {
+      palette = Array.from(body);
+    } else if (type === 'tRNS') {
+      trns = Array.from(body);
+    } else if (type === 'IDAT') {
+      idat.push(Buffer.from(body));
+    } else if (type === 'IEND') {
+      break;
+    }
+  }
+
+  if (!width || !height) throw new Error('PNG 缺少 IHDR');
+  if (interlace !== 0) throw new Error('不支持隔行 PNG（Adam7），请用普通模式重新导出');
+  if (bitDepth !== 8 && bitDepth !== 16) throw new Error(`不支持的位深 ${bitDepth}`);
+
+  const channels = colorType === 6 ? 4 : colorType === 2 ? 3 : colorType === 0 ? 1 : colorType === 3 ? 1 : 0;
+  if (!channels) throw new Error(`不支持的颜色类型 ${colorType}`);
+
+  const bytesPerSample = bitDepth / 8;
+  const bpp = channels * bytesPerSample;
+  const stride = width * bpp;
+  const raw = inflateSync(Buffer.concat(idat));
+  if (raw.length < (stride + 1) * height) throw new Error('PNG 数据不完整');
+
+  const out = new Uint8Array(width * height * 4);
+  const line = new Uint8Array(stride);
+  const prev = new Uint8Array(stride);
+
+  for (let y = 0; y < height; y += 1) {
+    const filter = raw[y * (stride + 1)];
+    const rowStart = y * (stride + 1) + 1;
+    raw.copy(line, 0, rowStart, rowStart + stride);
+    for (let x = 0; x < stride; x += 1) {
+      const a = x >= bpp ? line[x - bpp] : 0;
+      const b = prev[x];
+      const c = x >= bpp ? prev[x - bpp] : 0;
+      let value = line[x];
+      if (filter === 1) value = (value + a) & 0xff;
+      else if (filter === 2) value = (value + b) & 0xff;
+      else if (filter === 3) value = (value + ((a + b) >> 1)) & 0xff;
+      else if (filter === 4) value = (value + paeth(a, b, c)) & 0xff;
+      line[x] = value;
+    }
+
+    for (let x = 0; x < width; x += 1) {
+      const src = x * bpp;
+      const dst = (y * width + x) * 4;
+      let r = 0;
+      let g = 0;
+      let b = 0;
+      let alpha = 255;
+      if (colorType === 6) {
+        r = line[src]; g = line[src + bytesPerSample]; b = line[src + bytesPerSample * 2]; alpha = line[src + bytesPerSample * 3];
+      } else if (colorType === 2) {
+        r = line[src]; g = line[src + bytesPerSample]; b = line[src + bytesPerSample * 2];
+      } else if (colorType === 0) {
+        r = line[src]; g = r; b = r;
+      } else if (colorType === 3 && palette) {
+        const index = line[src];
+        r = palette[index * 3] ?? 0;
+        g = palette[index * 3 + 1] ?? 0;
+        b = palette[index * 3 + 2] ?? 0;
+        if (trns && index < trns.length) alpha = trns[index];
+      }
+      out[dst] = r; out[dst + 1] = g; out[dst + 2] = b; out[dst + 3] = alpha;
+    }
+    prev.set(line);
+  }
+
+  return { width, height, data: out };
+}
+
+/** 编码 RGBA 为 PNG（8 位、非隔行、filter 0）。 */
+export function encodePng(image: RgbaImage): Uint8Array {
+  const { width, height, data } = image;
+  const stride = width * 4;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y += 1) {
+    raw[y * (stride + 1)] = 0;
+    Buffer.from(data.buffer, data.byteOffset + y * stride, stride).copy(raw, y * (stride + 1) + 1);
+  }
+
+  const chunk = (type: string, body: Buffer): Buffer => {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(body.length, 0);
+    head.write(type, 4, 'ascii');
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([Buffer.from(type, 'ascii'), body])), 0);
+    return Buffer.concat([head, body, crc]);
+  };
+
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+
+  return Buffer.concat([
+    SIGNATURE,
+    chunk('IHDR', ihdr),
+    chunk('IDAT', deflateSync(raw, { level: 9 })),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+/** 透明单像素 PNG，用来占位骨架上的空部件。 */
+export function blankPng(): Uint8Array {
+  return encodePng({ width: 1, height: 1, data: new Uint8Array(4) });
+}
+
+/**
+ * 等比缩放进 canvasWidth × canvasHeight，居中、底部对齐、留 padding 比例的空白。
+ * 透明像素按直通 alpha 采样（不做预乘），避免边缘发黑。
+ */
+export function fitIntoCanvas(
+  image: RgbaImage,
+  canvasWidth: number,
+  canvasHeight: number,
+  fill = 0.94,
+): RgbaImage {
+  const scale = Math.min((canvasWidth * fill) / image.width, (canvasHeight * fill) / image.height);
+  const drawW = Math.max(1, Math.round(image.width * scale));
+  const drawH = Math.max(1, Math.round(image.height * scale));
+
+  const out = new Uint8Array(canvasWidth * canvasHeight * 4);
+  const offsetX = Math.round((canvasWidth - drawW) / 2);
+  const offsetY = Math.round((canvasHeight - drawH) / 2);
+
+  for (let y = 0; y < drawH; y += 1) {
+    const sy = Math.min(image.height - 1, Math.floor((y + 0.5) * image.height / drawH));
+    for (let x = 0; x < drawW; x += 1) {
+      const sx = Math.min(image.width - 1, Math.floor((x + 0.5) * image.width / drawW));
+      const src = (sy * image.width + sx) * 4;
+      const dx = offsetX + x;
+      const dy = offsetY + y;
+      if (dx < 0 || dy < 0 || dx >= canvasWidth || dy >= canvasHeight) continue;
+      const dst = (dy * canvasWidth + dx) * 4;
+      out[dst] = image.data[src];
+      out[dst + 1] = image.data[src + 1];
+      out[dst + 2] = image.data[src + 2];
+      out[dst + 3] = image.data[src + 3];
+    }
+  }
+  return { width: canvasWidth, height: canvasHeight, data: out };
+}

package/src/world.ts

@@ -5,12 +5,13 @@
  * 直接发到 QQ。语音字节可以随工具回执交给模型（blobs），由模型再用 qq_draft(voice=…)
  * 发出去；也可以一步到位，由本 World 自己连 OneBot 发。
  */
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { createHash } from 'node:crypto';
 import type { ConfigGroup, Logger, ToolDef, ToolOutcome, World, WorldHost, WorldWebUiDecl } from 'cortico/core/types.ts';
 import { nullLogger } from 'cortico/core/util.ts';
 import { ELLEN_TOOL_DECLS } from './definition.ts';
+import { installFigure } from './figure-pack.ts';
 import type { EllenVoiceConfig } from './config.ts';
 
 export interface EllenWorldDeps {
@@ -100,6 +101,13 @@ export class EllenVoiceWorld implements World {
                 'x-hot': false,
                 description: '工具调用不带 QQ 号时用这个。',
               },
+              'worlds.ellen-voice.figuresDir': {
+                type: 'string',
+                title: '形象目录',
+                'x-hot': false,
+                description:
+                  '装形象时装到这里；留空按 Coopanion 程序目录推断 data\\home\\companion\\data\\figures。',
+              },
             },
           },
         },
@@ -113,7 +121,7 @@ export class EllenVoiceWorld implements World {
   }
 
   tools(): ToolDef[] {
-    return [this.speakTool(), this.sendTool()];
+    return [this.speakTool(), this.sendTool(), this.installTool()];
   }
 
   // ---------------------------------------------------------------- 工具
@@ -188,6 +196,56 @@ export class EllenVoiceWorld implements World {
 
   // ---------------------------------------------------------------- 内部
 
+  /** 把用户给的一张透明底 PNG 装成形象包。 */
+  private installTool(): ToolDef {
+    return {
+      ...ELLEN_TOOL_DECLS.install,
+      tags: ['setup'],
+      handler: async (args): Promise<string> => {
+        const source = typeof args.path === 'string' ? args.path.trim() : '';
+        if (!source) return '[bad input] path 不能为空';
+        const id = typeof args.id === 'string' ? args.id.trim() : '';
+        if (!id) return '[bad input] id 不能为空（小写字母和数字）';
+        const name = typeof args.name === 'string' ? args.name.trim() : id;
+
+        try {
+          const figuresDir = this.resolveFiguresDir();
+          const result = installFigure({
+            source,
+            id,
+            name,
+            figuresDir,
+            overwrite: args.overwrite === true,
+          });
+          this.log.info(`ellen-voice: 已安装形象 ${result.dir}`);
+          return [
+            `[形象已安装] ${name}（id=${id}）`,
+            `目录：${result.dir}`,
+            `源图：${result.sourceSize.width}×${result.sourceSize.height} → 画布 ${result.canvas.width}×${result.canvas.height}`,
+            `写入 ${result.files} 个文件（骨架贴图全部为透明占位）。`,
+            '',
+            '下一步：打开「装扮」页刷新，形象列表里就会出现它；如果已经打开着，切走再切回以重新读盘。',
+            '说明：这是静态贴图，不会换姿势；人物大小沿用形象包里的画布比例。',
+          ].join('\n');
+        } catch (error) {
+          return `[install failed] ${this.errText(error)}`;
+        }
+      },
+    };
+  }
+
+  /** figures 根目录：设置里填了就用，否则按 Coopanion.exe 的位置推断。 */
+  private resolveFiguresDir(): string {
+    const configured = this.cfg.figuresDir?.trim();
+    if (configured) return resolve(configured);
+    const exeDir = dirname(process.execPath);
+    const guess = join(exeDir, 'data', 'home', 'companion', 'data', 'figures');
+    if (existsSync(guess)) return guess;
+    throw new Error(
+      '找不到形象目录：请在扩展设置里把 figuresDir 填成 Coopanion 的 data\\home\\companion\\data\\figures',
+    );
+  }
+
   private cleanText(raw: unknown): string {
     const text = typeof raw === 'string' ? raw.trim() : '';
     if (!text) return '';