@harness-mix/cli 0.1.8 → 0.1.10

package/scripts/pets-test.cjs

@@ -0,0 +1,146 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { createPetMarket, readAsarHeader } = require('../src/main/native/pets');
+
+function buildSyntheticAsar(targetPath, petName, blobContent) {
+  const tree = {
+    files: {
+      webview: {
+        files: {
+          assets: {
+            files: {
+              [`${petName}-spritesheet-v1-0123456789abcdef.webp`]: {
+                size: blobContent.length,
+                offset: '0',
+              },
+            },
+          },
+        },
+      },
+    },
+  };
+  const jsonBuf = Buffer.from(JSON.stringify(tree), 'utf8');
+  const jsonLen = jsonBuf.length;
+  const padLen = (4 - (jsonLen % 4)) % 4;
+  const pickleSize = 8 + jsonLen + padLen;
+  const head = Buffer.alloc(16);
+  head.writeUInt32LE(4, 0);
+  head.writeUInt32LE(pickleSize, 4);
+  head.writeUInt32LE(jsonLen + 4, 8);
+  head.writeUInt32LE(jsonLen, 12);
+  const asarBuf = Buffer.concat([head, jsonBuf, Buffer.alloc(padLen), blobContent]);
+  fs.writeFileSync(targetPath, asarBuf);
+}
+
+(async () => {
+  const testRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-mix-pets-test-'));
+  const fakeAsarDir = path.join(testRoot, 'resources');
+  fs.mkdirSync(fakeAsarDir, { recursive: true });
+  const fakeAsarPath = path.join(fakeAsarDir, 'app.asar');
+  const fakeCodexBin = path.join(fakeAsarDir, 'codex.exe');
+  fs.writeFileSync(fakeCodexBin, '');
+
+  const fakeSpriteBlob = Buffer.from('RIFF....WEBPVP8 ...fake-sprite-data...', 'utf8');
+  buildSyntheticAsar(fakeAsarPath, 'synthetic-buddy', fakeSpriteBlob);
+
+  const petsDir = path.join(testRoot, 'installed-pets');
+  fs.mkdirSync(petsDir, { recursive: true });
+
+  const env = {
+    CODEXHOST_STOCK_CODEX_PATH: fakeCodexBin,
+    HARNESS_MIX_PETS_DIR: petsDir,
+  };
+
+  try {
+    // 1. Verify readAsarHeader
+    const asarInfo = readAsarHeader(fakeAsarPath);
+    assert.ok(asarInfo.blobBase > 16, 'asar blobBase should be past header');
+    const assetFiles = asarInfo.tree?.files?.webview?.files?.assets?.files;
+    assert.ok(assetFiles && typeof assetFiles === 'object', 'asset tree found');
+
+    // 2. Test createPetMarket catalog()
+    const market = createPetMarket({ env });
+    const catalog = market.catalog();
+    assert.equal(catalog.officialAvailable, true, 'synthetic asar should be available');
+    assert.equal(catalog.petsDir, petsDir, 'petsDir matches env override');
+
+    const officialPet = catalog.data.find(p => p.id === 'synthetic-buddy');
+    assert.ok(officialPet, 'synthetic-buddy should be present in catalog');
+    assert.equal(officialPet.source, 'official');
+    assert.equal(officialPet.installed, false);
+    assert.equal(officialPet.displayName, 'Synthetic Buddy');
+
+    // Curated community pets should also be listed
+    const curatedSample = catalog.data.find(p => p.id === 'komi-shouko-pixel');
+    assert.ok(curatedSample, 'curated community pet komi-shouko-pixel should be present');
+    assert.equal(curatedSample.installed, false);
+
+    // 3. Test preview() for official pet
+    const previewRes = market.preview({ id: 'synthetic-buddy' });
+    assert.equal(previewRes.id, 'synthetic-buddy');
+    assert.equal(previewRes.mime, 'image/webp');
+    const previewBuf = Buffer.from(previewRes.dataBase64, 'base64');
+    assert.equal(previewBuf.toString('utf8'), fakeSpriteBlob.toString('utf8'), 'preview base64 should match sprite blob');
+
+    // Invalid pet id checks
+    assert.throws(() => market.preview({ id: '../bad-pet' }), /Invalid pet id/);
+    assert.throws(() => market.preview({ id: 'non-existent-pet' }), /Unknown pet/);
+
+    // 4. Test install() of official pet
+    const installRes = await market.install({ id: 'synthetic-buddy' });
+    assert.equal(installRes.id, 'synthetic-buddy');
+    assert.equal(installRes.installed, true);
+    assert.equal(installRes.alreadyInstalled, false);
+
+    const installedDir = path.join(petsDir, 'synthetic-buddy');
+    assert.ok(fs.existsSync(installedDir), 'pet directory created');
+    const petJsonPath = path.join(installedDir, 'pet.json');
+    const petSpritePath = path.join(installedDir, 'spritesheet.webp');
+    assert.ok(fs.existsSync(petJsonPath), 'pet.json exists');
+    assert.ok(fs.existsSync(petSpritePath), 'spritesheet.webp exists');
+
+    const meta = JSON.parse(fs.readFileSync(petJsonPath, 'utf8'));
+    assert.equal(meta.id, 'synthetic-buddy');
+    assert.equal(meta.displayName, 'Synthetic Buddy');
+    assert.equal(meta.spritesheetPath, 'spritesheet.webp');
+
+    // Installing again should be a no-op returning alreadyInstalled: true
+    const reinstallRes = await market.install({ id: 'synthetic-buddy' });
+    assert.equal(reinstallRes.alreadyInstalled, true);
+
+    // Catalog should now reflect installed: true
+    const updatedCatalog = market.catalog();
+    const installedEntry = updatedCatalog.data.find(p => p.id === 'synthetic-buddy');
+    assert.ok(installedEntry, 'installed pet present');
+    assert.equal(installedEntry.installed, true);
+    assert.equal(installedEntry.source, 'installed');
+
+    // 5. Test community() fallback and search
+    const communityRes = await market.community({ search: 'komi' });
+    assert.ok(communityRes.total >= 1);
+    assert.equal(communityRes.data[0].id, 'komi-shouko-pixel');
+
+    // 6. Test uninstall()
+    const uninstallRes = market.uninstall({ id: 'synthetic-buddy' });
+    assert.equal(uninstallRes.id, 'synthetic-buddy');
+    assert.equal(uninstallRes.removed, true);
+    assert.ok(!fs.existsSync(installedDir), 'pet directory should be deleted');
+
+    // Calling uninstall again should return removed: false
+    const uninstallAgain = market.uninstall({ id: 'synthetic-buddy' });
+    assert.equal(uninstallAgain.removed, false);
+
+    // Catalog after uninstall reflects installed: false
+    const catalogAfterUninstall = market.catalog();
+    const uninstalledEntry = catalogAfterUninstall.data.find(p => p.id === 'synthetic-buddy');
+    assert.equal(uninstalledEntry.installed, false);
+
+    console.log('Pets market native tests passed successfully!');
+  } finally {
+    fs.rmSync(testRoot, { recursive: true, force: true });
+  }
+})();

package/scripts/switch-harness-test.cjs

@@ -2,7 +2,7 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const { HostRuntime } = require('../src/main/host/runtime');
-const { CAP, buildHandoffContext } = require('../src/main/host/handoff');
+const { CAP, buildHandoffContext, composeHandoffEnvelope } = require('../src/main/host/handoff');
 
 /**
  * 跨 Harness 原地切换（switchHarness）脚本级测试：
@@ -13,15 +13,18 @@ const { CAP, buildHandoffContext } = require('../src/main/host/handoff');
 const wait = async fn => { for (let i = 0; i < 300; i++) { if (fn()) return; await new Promise(r => setTimeout(r, 10)); } throw new Error('Timed out'); };
 
 function fakeHarness(id, name) {
-  const state = { sent: [], opens: [], closed: 0, hold: null, withFileChange: false };
+  const state = { sent: [], opens: [], closed: 0, hold: null, withFileChange: false, openError: null, openWait: null, sendError: null };
   const adapter = {
     manifest: { id, name, aliases: [id], capabilities: {} },
     async open(input) {
       state.opens.push({ restore: input.thread.restore === true, nativeSessionId: input.thread.nativeSessionId, nativeSessionFile: input.thread.nativeSessionFile });
+      if (state.openWait) await state.openWait;
+      if (state.openError) throw new Error(state.openError);
       return { nativeSessionId: input.thread.nativeSessionId };
     },
     async send(session, text, hooks) {
       state.sent.push(text);
+      if (state.sendError) throw new Error(state.sendError);
       if (state.hold) { state.hold.hooks = hooks; return; } // 挂起：Turn 保持 running，等待测试手动 settle
       if (state.withFileChange) hooks.emit({ kind: 'file-change', changes: [{ path: 'src/login.ts', before: '', after: 'x', complete: true, changeType: 'added' }] });
       hooks.emit({ kind: 'text-delta', text: `${name} 回复` });
@@ -46,6 +49,8 @@ async function main() {
   assert.deepEqual(optimized.conversationTail.map(message => message.role), ['user', 'assistant', 'user', 'assistant']);
   assert.equal(optimized.conversationTail.at(-1).text, longSolution, '最新方案应获得更大的交接预算');
   assert.ok(optimized.conversationTail.reduce((sum, message) => sum + message.text.length, 0) <= CAP.totalChars);
+  assert.match(composeHandoffEnvelope({ fromHarnessId: 'a', context: {}, intent: 'review' }), /Do not modify files/);
+  assert.match(composeHandoffEnvelope({ fromHarnessId: 'a', context: {}, intent: 'reanalyze' }), /Reanalyze the task independently/);
 
   await fs.mkdir('output', { recursive: true });
   const root = await fs.mkdtemp(path.resolve('output/switch-harness-'));
@@ -90,17 +95,21 @@ async function main() {
     const checkpointBeforeSend = rt.handoffs.get(thread.id, firstCheckpointId);
     assert.equal(checkpointBeforeSend.intent, 'continue');
     assert.equal(checkpointBeforeSend.fileState.files.some(file => file.path === 'src/login.ts' && file.changeType === 'added'), true);
-    assert.equal(rt.handoffs.owned(thread.id, firstCheckpointId).status, 'checkpoint-created');
-    assert.equal(thread.restore, false, '新 Harness 上是全新原生会话');
-    assert.equal(rt.sessions.has(thread.id), false, '切换后旧原生会话已关闭');
+    assert.equal(rt.handoffs.owned(thread.id, firstCheckpointId).status, 'ready');
+    assert.equal(b.state.opens[0].restore, false, '新 Harness 上是全新原生会话');
+    assert.equal(thread.restore, undefined, '目标 Session 打开后清理瞬态 restore 标记');
+    assert.equal(thread.pendingHandoff.phase, 'ready');
+    assert.equal(rt.sessions.has(thread.id), true, '目标 Harness 连接成功后才完成切换');
     assert.equal(a.state.closed, 1);
-    assert.equal(b.state.opens.length, 0, '目标 Harness 惰性拉起，切换瞬间不开进程');
+    assert.equal(b.state.opens.length, 1, '切换阶段预先连接目标 Harness');
     assert.equal(thread.messages.filter(m => m.role === 'user').length, 1, '/switch 指令本身不落在会话里');
+    await assert.rejects(rt.switchHarness(thread.id, 'a'), /上一次 Harness 接力尚未完成/);
+    assert.ok((await rt.listCommands({ threadId: thread.id })).some(command => command.id === 'switch-cancel'));
 
     // 4) 切换后首轮：信封注入 prompt，可见消息保持干净，注入后清除标记
     await rt.send(thread.id, '继续');
     await settle(thread.id);
-    assert.equal(b.state.opens.length, 1);
+    assert.equal(b.state.opens.length, 1, '首轮发送复用切换阶段已连接的目标 Session');
     assert.equal(b.state.opens[0].restore, false);
     assert.notEqual(thread.nativeSessionId, aNativeId);
     assert.match(b.state.sent[0], /\[Harness Mix handoff\]/);
@@ -119,18 +128,18 @@ async function main() {
     await settle(thread.id);
     assert.ok(!b.state.sent[1].includes('[Harness Mix handoff]'), '信封只注入一次');
 
-    // 6) 切回 A：原生会话引用恢复（惰性 open 走 restore 路径），chain 压栈两条
+    // 6) 切回 A：原生会话引用恢复并在提交切换前验证连接，chain 压栈两条
     await rt.send(thread.id, '/switch a');
     assert.equal(thread.harnessId, 'a');
     assert.equal(thread.harnessChain.length, 2);
     assert.equal(thread.harnessChain[1].harnessId, 'b');
     assert.equal(thread.nativeSessionId, aNativeId, '切回恢复原原生会话标识');
-    assert.equal(thread.restore, true);
-    await rt.send(thread.id, '我回来了');
-    await settle(thread.id);
+    assert.equal(thread.restore, undefined);
     assert.equal(a.state.opens.length, 2);
     assert.equal(a.state.opens[1].restore, true, '切回走原生恢复路径');
     assert.equal(a.state.opens[1].nativeSessionId, aNativeId);
+    await rt.send(thread.id, '我回来了');
+    await settle(thread.id);
     assert.match(a.state.sent[1], /\[Harness Mix handoff\]/, '切回首轮同样注入信封');
 
     // 7) 守卫：执行中 / 同 Harness / 未知 Harness / 草稿 / 协作子任务
@@ -152,7 +161,65 @@ async function main() {
     const child = await rt.createThread({ harnessId: 'a', cwd: root, parentThreadId: thread.id });
     await assert.rejects(rt.switchHarness(child.id, 'b'), /协作子任务/);
 
-    // 8) 持久化：threads.json 里切换链完整（含原生会话引用，供重启后惰性恢复）
+    // 8) 待投递接力可显式取消：关闭目标 Session，恢复源 Harness，不污染既有链
+    const chainBeforeCancel = thread.harnessChain.length;
+    const cancelCandidate = await rt.switchHarness(thread.id, 'b', { intent: 'review' });
+    assert.equal(thread.pendingHandoff.phase, 'ready');
+    await rt.send(thread.id, '/switch cancel');
+    assert.equal(thread.harnessId, 'a');
+    assert.equal(thread.pendingHandoff, undefined);
+    assert.equal(thread.harnessChain.length, chainBeforeCancel);
+    assert.equal(rt.handoffs.owned(thread.id, cancelCandidate.checkpointId).status, 'cancelled');
+    assert.equal(rt.sessions.get(thread.id)?.adapter, a.adapter);
+
+    // 9) 目标连接失败时事务回滚：线程归属、原生源 Session 与 chain 都恢复
+    const c = fakeHarness('c', 'Gamma');
+    c.state.openError = 'Gamma auth expired';
+    rt.adapters.set('c', c.adapter); rt.status.c = { available: true };
+    await assert.rejects(rt.switchHarness(thread.id, 'c'), /已恢复原 Harness.*Gamma auth expired/);
+    assert.equal(thread.harnessId, 'a');
+    assert.equal(thread.pendingHandoff, undefined);
+    assert.equal(thread.harnessChain.length, chainBeforeCancel);
+    assert.equal(rt.sessions.get(thread.id)?.adapter, a.adapter);
+    const rolledBack = [...rt.handoffs.checkpoints.values()].find(row => row.targetHarnessId === 'c');
+    assert.equal(rolledBack.status, 'rolled-back');
+
+    // 10) 首轮投递失败保留检查点；下一次发送复用同一目标 Session 和同一检查点重试
+    a.state.withFileChange = false;
+    const retryThread = await rt.createThread({ harnessId: 'a', cwd: root });
+    await rt.send(retryThread.id, '准备接力重试');
+    await settle(retryThread.id);
+    const retrySwitch = await rt.switchHarness(retryThread.id, 'b', { intent: 'review' });
+    b.state.sendError = 'temporary transport failure';
+    await rt.send(retryThread.id, '先审查');
+    await settle(retryThread.id);
+    assert.equal(retryThread.pendingHandoff.phase, 'failed');
+    assert.equal(rt.handoffs.owned(retryThread.id, retrySwitch.checkpointId).status, 'failed');
+    b.state.sendError = null;
+    await rt.send(retryThread.id, '重试审查');
+    await settle(retryThread.id);
+    assert.equal(retryThread.pendingHandoff, undefined);
+    assert.equal(rt.handoffs.owned(retryThread.id, retrySwitch.checkpointId).status, 'active');
+    assert.match(b.state.sent.at(-1), /Handoff mode: review.*Do not modify files/s);
+
+    // 11) 并发切换按 Thread 串行化：第二个 RPC 不得在第一个连接期间再创建检查点
+    const concurrentThread = await rt.createThread({ harnessId: 'a', cwd: root });
+    await rt.send(concurrentThread.id, '准备并发切换');
+    await settle(concurrentThread.id);
+    const d = fakeHarness('d', 'Delta');
+    let releaseDelta;
+    d.state.openWait = new Promise(resolve => { releaseDelta = resolve; });
+    rt.adapters.set('d', d.adapter); rt.status.d = { available: true };
+    const firstSwitch = rt.switchHarness(concurrentThread.id, 'd');
+    await wait(() => rt.switching.has(concurrentThread.id));
+    await assert.rejects(rt.switchHarness(concurrentThread.id, 'b'), /正在切换 Harness/);
+    releaseDelta();
+    await firstSwitch;
+    assert.equal(concurrentThread.harnessId, 'd');
+    await rt.cancelHarnessSwitch(concurrentThread.id);
+    assert.equal(concurrentThread.harnessId, 'a');
+
+    // 12) 持久化：threads.json 里切换链完整（含原生会话引用，供重启后惰性恢复）
     await rt.store.save(rt.threads);
     const persisted = (await rt.store.load()).find(t => t.id === thread.id);
     assert.equal(persisted.harnessId, 'a');

package/scripts/tool-concurrency-regression-test.cjs

@@ -89,20 +89,22 @@ async function main() {
     const call = { type: 'assistant', message: { content: [{ type: 'tool_use', id: 'same-id', name: 'Read', input: { file_path: 'a.txt' } }] } };
     for (const event of projectEvent(call)) emitA(event);
     emitB({ kind: 'tool', toolCallId: 'same-id', title: 'Read', state: 'running', input: 'b.txt' });
-    assert.equal(notifications.filter(n => n.method === 'item/completed' && n.params?.item?.type === 'mcpToolCall').length, 0);
+    assert.equal(notifications.filter(n => n.method === 'item/completed' && n.params?.item?.type === 'dynamicToolCall').length, 0);
     for (const event of projectEvent({ type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: 'same-id', content: [{ type: 'text', text: 'only A' }] }] } })) emitA(event);
     emitB({ kind: 'tool', toolCallId: 'same-id', state: 'error', output: 'only B failed' });
-    const completed = notifications.filter(n => n.method === 'item/completed' && n.params?.item?.type === 'mcpToolCall');
+    const completed = notifications.filter(n => n.method === 'item/completed' && n.params?.item?.type === 'dynamicToolCall');
     assert.equal(completed.length, 2);
-    assert.equal(completed.find(n => n.params.threadId === a.id).params.item.result.content[0].text, 'only A');
-    assert.equal(completed.find(n => n.params.threadId === b.id).params.item.error.message, 'only B failed');
+    assert.equal(completed.find(n => n.params.threadId === a.id).params.item.contentItems[0].text, 'only A');
+    const failedB = completed.find(n => n.params.threadId === b.id).params.item;
+    assert.equal(failedB.status, 'failed');
+    assert.equal(failedB.contentItems[0].text, 'only B failed');
     assert.equal(a.tools[0].input, '{"file_path":"a.txt"}');
     assert.equal(a.tools[0].output, 'only A');
     assert.equal(b.tools[0].output, 'only B failed');
     emitB({ kind: 'tool', toolCallId: 'same-id', state: 'error', output: { error: 'late detail' } });
-    const late = notifications.filter(n => n.method === 'item/completed' && n.params?.item?.type === 'mcpToolCall').at(-1);
+    const late = notifications.filter(n => n.method === 'item/completed' && n.params?.item?.type === 'dynamicToolCall').at(-1);
     assert.equal(late.params.threadId, b.id);
-    assert.equal(late.params.item.result.content[0].text, '{"error":"late detail"}');
+    assert.equal(late.params.item.contentItems[0].text, '{"error":"late detail"}');
     emitA({ kind: 'completed', finalAnswer: true });
     assert.equal(rt.execution.isRunning(b.id), true);
     emitB({ kind: 'completed', finalAnswer: true });

package/src/assets/icons/cline-color.svg

@@ -0,0 +1 @@
+<svg fill="currentColor" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Cline</title><path d="M17.035 3.991c2.75 0 4.98 2.24 4.98 5.003v1.667l1.45 2.896a1.01 1.01 0 01-.002.909l-1.448 2.864v1.668c0 2.762-2.23 5.002-4.98 5.002H7.074c-2.751 0-4.98-2.24-4.98-5.002V17.33l-1.48-2.855a1.01 1.01 0 01-.003-.927l1.482-2.887V8.994c0-2.763 2.23-5.003 4.98-5.003h9.962zM8.265 9.6a2.274 2.274 0 00-2.274 2.274v4.042a2.274 2.274 0 004.547 0v-4.042A2.274 2.274 0 008.265 9.6zm7.326 0a2.274 2.274 0 00-2.274 2.274v4.042a2.274 2.274 0 104.548 0v-4.042A2.274 2.274 0 0015.59 9.6z"></path><path d="M12.054 5.558a2.779 2.779 0 100-5.558 2.779 2.779 0 000 5.558z"></path></svg>

package/src/assets/skins/codex-styler/ASSET_LICENSES.md

@@ -0,0 +1,36 @@
+# Asset licenses
+
+Original artwork shipped in the built-in Codex Styler themes is distributed
+under Creative Commons Attribution 4.0 International (CC BY 4.0).
+
+| Asset                                                  | Origin                                                                                                                                                    |                                             Dimensions | License                                   |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -----------------------------------------------------: | ----------------------------------------- |
+| Codex Styler CS orbit logo, dark and light appearances | Generated specifically for this project, 2026-07-16                                                                                                       | 1254×1254 sources; platform exports generated by Tauri | CC BY 4.0                                 |
+| Nocturne Studio background                             | Generated specifically for this project, 2026-07-16                                                                                                       |                                              1600×1000 | CC BY 4.0                                 |
+| Quiet Garden background                                | Generated specifically for this project, 2026-07-16                                                                                                       |                                              1600×1000 | CC BY 4.0                                 |
+| Gilded Grandeur background                             | Generated specifically for this project with the built-in image generation workflow, 2026-07-17                                                           |                                               1586×992 | CC BY 4.0                                 |
+| Merry Big Top background                               | Generated specifically for this project with the built-in image generation workflow, 2026-07-17                                                           |                                               1586×992 | CC BY 4.0                                 |
+| Moss chameleon calibrated direction atlas              | Generated specifically for this project; non-linear direction calibration, shared cropping, chroma-key removal, and exact-alpha WebP encoding, 2026-07-16 |                              181 frames across 4 pages | CC BY 4.0                                 |
+| Pico parrot calibrated direction atlas                 | Generated specifically for this project; natural pose frames retained, background and watermark excluded, 2026-07-17                                      |                              189 frames across 4 pages | CC BY 4.0                                 |
+| Puddle frog calibrated direction atlas                 | Generated specifically for this project; natural pose frames retained, non-linear direction calibration, background and watermark excluded, 2026-07-17    |                              211 frames across 5 pages | CC BY 4.0                                 |
+| Mochi cat calibrated direction atlas                   | Generated specifically for this project; adaptive matte, shared ground line, and seamless loop closure, 2026-07-17                                        |                              175 frames across 4 pages | CC BY 4.0                                 |
+| Token Thief calibrated direction atlas                 | User-provided generated video; dual-corner watermark exclusion, gray-speck cleanup, shared ground line, and non-linear direction calibration, 2026-07-17  |                              101 frames across 3 pages | CC BY 4.0                                 |
+| Reset God calibrated direction atlas                   | User-provided generated video; dual-corner watermark exclusion, gray-speck cleanup, shared ground line, and non-linear direction calibration, 2026-07-17  |                              100 frames across 3 pages | CC BY 4.0                                 |
+| README and desktop companion portraits                 | Representative frames derived from the six calibrated direction atlases; exact cell crop, normalized transparent canvas, and alpha cleanup, 2026-07-17    |                                    6 images at 480×480 | CC BY 4.0                                 |
+| Codex Styler manager screenshots                       | Captured from the English manager UI in matching light and dark appearances, 2026-07-17                                                                   |                                   2 images at 1320×840 | CC BY 4.0                                 |
+| Composer game object set                               | Generated specifically for Triple Drop, Capsule Crane, and Mission Map; chroma-key removal and lossless-alpha WebP encoding, 2026-07-20                   |                        4 transparent images at 160×160 | CC BY 4.0                                 |
+| Composer Interactions documentation screenshots        | Captured from the English manager and a live local Codex configuration session, 2026-07-20                                                                |                       1280×720 and 1474×538 WebP files | Documentation evidence; Codex UI excluded |
+| Companion Creator H.264 test fixture                   | Synthetic half-second color-frame video generated specifically for local media decoding and E2E regression tests, 2026-07-17                              |                               160×90, 12 fps, 6 frames | CC BY 4.0                                 |
+
+No source code, image, video, sprite, logo, or other asset from
+Fei-Away/Codex-Dream-Skin or xplol/KaMenisACat is redistributed by this
+repository. Those projects are implementation and style references only.
+
+Documentation screenshots of themes applied to Codex Desktop are included to
+demonstrate compatibility. Original Codex interface elements, product names,
+and trademarks visible in those screenshots remain the property of their
+respective owners and are not relicensed by this project. Codex Styler theme
+artwork and companion artwork remain covered by the project asset license.
+
+Asset dimensions, frame order, and replacement guidance are recorded in
+[docs/assets-and-replacement.md](docs/assets-and-replacement.md).

package/src/assets/skins/codex-styler/NOTICE

@@ -0,0 +1,11 @@
+Codex Styler
+Copyright 2026 Codex Styler contributors
+
+Codex Styler is an independent, unofficial project. It is not affiliated
+with, endorsed by, or sponsored by OpenAI.
+
+OpenAI and Codex are trademarks of OpenAI, L.L.C. Their names are used only
+to describe compatibility with the OpenAI Codex Desktop application.
+
+Third-party dependency notices and the release inventory policy are recorded
+in THIRD_PARTY_NOTICES.md.

package/src/assets/skins/heige/ASSET_PROVENANCE.md

@@ -0,0 +1,56 @@
+# 视觉素材来源与再分发状态
+
+本表记录当前仓库能够证明的事实与项目所有者作出的发布决定。Git 历史能证明文件何时进入仓库，不能单独证明原始作者、生成工具、授权链或再分发许可。
+
+`node scripts/check-asset-provenance.mjs --check` 校验清单完整性。公开发布前必须运行 `node scripts/check-asset-provenance.mjs --release`；它接受「已验证可公开再分发」或「项目所有者确认公开发布」两种状态。后者表示项目所有者在知悉来源记录边界后明确接受公开发布风险，不等同于第三方法律意见或商业授权证明。
+
+2026-07-17，项目所有者确认当时清单中的视觉素材可以随 `v5.2.1` 公开发布。2026-07-18，项目所有者提供两张当前 Mac 的 Codex 真机截图，并明确要求更新到 GitHub 项目介绍区；同日提供两张悟空主题生成图，明确要求制作成内置预设并公开发布。2026-08-11，项目所有者提供一张当前 Mac 的 WorkBuddy 真机截图（Miku 488137 主题），并明确要求补充到 GitHub 项目介绍区开头。2026-08-23，项目所有者提供一张 HeiGe 皮肤启动器 5.5.15 真机截图，并明确要求放入 GitHub 介绍页面作为更新声明。后续新增素材仍须逐项登记，未经验证或所有者确认的状态继续阻断 Release。
+
+| 仓库路径 | 用途 | 已知创建或来源证据 | 已知许可 | 再分发状态 | 替换行动 |
+| --- | --- | --- | --- | --- | --- |
+| `assets/miku-character.png` | Miku 主题角色图层 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `assets/launcher/miku-launcher-icon.png` | macOS 启动器图标母版 | 2026-08-19 按项目所有者要求，以 `assets/miku-character.png` 为参考经图像生成工具编辑衍生 | 未知，继承角色源图未验证的授权状态 | 项目所有者确认公开发布 | 公开分发前补齐角色及源图授权，或替换为原创素材 |
+| `assets/launcher/AppIcon.icns` | macOS 启动器 Bundle 图标 | 2026-08-19 由 `assets/launcher/miku-launcher-icon.png` 的标准尺寸 iconset 确定性衍生 | 未知，继承图标母版与角色源图未验证的授权状态 | 项目所有者确认公开发布 | 与图标母版同步替换或补齐权利记录 |
+| `assets/launcher/LauncherLogo.png` | macOS 启动器窗口内置 Logo | 2026-08-21 按项目所有者要求，以 `assets/miku-character.png` 中的核心人物为参考，经图像生成工具重构为正方形上半身构图 | 未知，继承角色源图未验证的授权状态 | 项目所有者确认公开发布 | 公开分发前补齐角色及源图授权，或替换为原创素材 |
+| `assets/miku-full-canvas.png` | Miku 主题完整画布 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `assets/miku-hero.png` | Miku 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `assets/miku-polaroid.png` | Miku 主题拍立得装饰 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `assets/miku-portrait-reference.png` | Miku 主题肖像参考 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐可核验来源或替换 |
+| `assets/miku-reference.png` | Miku 主题构图参考 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐可核验来源或替换 |
+| `assets/miku-sidebar-wash.png` | Miku 主题侧栏纹理 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `assets/previews/genshin-impact-codex-ui-1.webp` | Genshin 预设预览 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐来源记录或替换预览 |
+| `assets/previews/genshin-impact-codex-ui-2.webp` | Genshin 预设预览 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐来源记录或替换预览 |
+| `assets/previews/love-and-deepspace-codex-ui-1.webp` | Love and Deepspace 预设预览 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐来源记录或替换预览 |
+| `assets/previews/love-and-deepspace-codex-ui-2.webp` | Love and Deepspace 预设预览 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐来源记录或替换预览 |
+| `assets/previews/miku-studio.webp` | Miku Studio 预览 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐来源记录或替换预览 |
+| `assets/previews/naruto-codex-ui-1.webp` | Naruto 预设预览 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐来源记录或替换预览 |
+| `assets/previews/naruto-codex-ui-2.webp` | Naruto 预设预览 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐来源记录或替换预览 |
+| `assets/previews/wuthering-waves-codex-ui-1.webp` | Wuthering Waves 预设预览 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐来源记录或替换预览 |
+| `assets/previews/wuthering-waves-codex-ui-2.webp` | Wuthering Waves 预设预览 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补齐来源记录或替换预览 |
+| `custom-pet/miku-future/spritesheet.webp` | Miku 宠物精灵图 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的精灵图 |
+| `docs/images/appearance-theme-contrast.jpg` | 外观主题配色设置说明截图 | 仓库标注为运行截图，但原始采集与画面权利记录缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补充自有截图与来源记录 |
+| `docs/images/dalao-live.jpg` | 大佬点烟主题运行截图 | 仓库标注为运行截图，但原始采集与画面权利记录缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补充自有截图与来源记录 |
+| `docs/images/genshin-dawn-live.jpg` | Genshin Dawn 运行截图 | 仓库标注为运行截图，但原始采集与画面权利记录缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补充自有截图与来源记录 |
+| `docs/images/genshin-night-live.jpg` | Genshin Night 运行截图 | 仓库标注为运行截图，但原始采集与画面权利记录缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补充自有截图与来源记录 |
+| `docs/images/macos-launcher-5.5.15-live.webp` | HeiGe 皮肤启动器 5.5.15 真机截图 | 项目所有者于 2026-08-23 提供当前 Mac 启动器 PNG，并明确要求发布到 GitHub 介绍页面作为更新声明；仓库保存压缩 WebP | 截图内第三方角色、标识及应用图标的权利不随截图转移 | 项目所有者确认公开发布 | 保留原始截图与本条提供记录 |
+| `docs/images/theme-center-live.webp` | HeiGe 主题中心运行截图 | 项目所有者于 2026-07-18 提供当前 Mac 真机 PNG，并明确要求发布到 GitHub；仓库保存压缩 WebP | 截图内第三方角色、标识及界面元素的权利不随截图转移 | 项目所有者确认公开发布 | 保留原始截图与本条提供记录 |
+| `docs/images/theme-switcher-live.webp` | Miku 主题及顶部切换入口运行截图 | 项目所有者于 2026-07-18 提供当前 Mac 真机 PNG，并明确要求发布到 GitHub；仓库保存压缩 WebP | 截图内第三方角色、标识及界面元素的权利不随截图转移 | 项目所有者确认公开发布 | 保留原始截图与本条提供记录 |
+| `docs/images/wechat-group-qr.png` | 微信交流群二维码 | 项目所有者于 2026-07-18 提供当前个人微信二维码 PNG，并明确要求替换 GitHub 项目介绍图片 | 个人头像、昵称及二维码由项目所有者提供 | 项目所有者确认公开发布 | 保留本条提供记录；二维码失效时及时替换 |
+| `docs/images/workbuddy-miku-live.webp` | WorkBuddy 换肤运行截图（Miku 488137 主题） | 项目所有者于 2026-08-11 提供当前 Mac WorkBuddy 真机 PNG，并明确要求补充到 GitHub 项目介绍区开头；仓库保存压缩 WebP | 截图内第三方角色、标识及界面元素的权利不随截图转移 | 项目所有者确认公开发布 | 保留原始截图与本条提供记录 |
+| `docs/images/wuthering-live.jpg` | Wuthering Waves 主题运行截图 | 仓库标注为运行截图，但原始采集与画面权利记录缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补充自有截图与来源记录 |
+| `themes/dalao-dianyan/hero.webp` | Dalao Dianyan 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补充人物及图像权利记录 |
+| `themes/deepspace-dawn/hero.webp` | Deepspace Dawn 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `themes/deepspace-star/hero.webp` | Deepspace Star 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `themes/dragonball-nimbus/hero.webp` | 龙珠筋斗云主题主视觉 | 项目所有者于 2026-07-18 提供生成 PNG，并明确要求制作预设后公开发布；仓库保存压缩 WebP | 画面含第三方角色形象，项目未取得可独立核验的第三方授权文件 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的原创角色素材 |
+| `themes/dragonball-super-saiyan/hero.webp` | 龙珠超级赛亚人主题主视觉 | 项目所有者于 2026-07-18 提供生成 PNG，并明确要求制作预设后公开发布；仓库保存压缩 WebP | 画面含第三方角色形象，项目未取得可独立核验的第三方授权文件 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的原创角色素材 |
+| `themes/genshin-dawn/hero.webp` | Genshin Dawn 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `themes/genshin-night/hero.webp` | Genshin Night 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `themes/miku-488137/hero.webp` | Miku 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `themes/miku-488137/logo.webp` | Miku 主题 Logo | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续补充标识来源或替换 |
+| `themes/miku-488137/polaroid.webp` | Miku 主题拍立得装饰 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `themes/naruto-hokage/hero.webp` | Naruto Hokage 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `themes/naruto-sasuke/hero.webp` | Naruto Sasuke 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `themes/wuthering-echo/hero.webp` | Wuthering Echo 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+| `themes/wuthering-tide/hero.webp` | Wuthering Tide 主题主视觉 | 来源证据缺失，授权未验证 | 未知 | 项目所有者确认公开发布 | 后续可替换为权利记录更完整的素材 |
+
+MIT 许可证只适用于软件代码，不自动改变第三方可能拥有的素材权利。项目所有者确认发布表示接受当前发布决定及其风险。新增、替换或删除图片后，必须运行 `node scripts/check-asset-provenance.mjs --check`，并在同一变更中同步本表。

package/src/assets/skins/heige/NOTICE.md

@@ -0,0 +1,13 @@
+# 软件许可、视觉素材与商标
+
+本仓库是非官方项目，与 OpenAI、Crypton Future Media、miHoYo/HoYoverse、Kuro Games、Shueisha、Papergames 及其合作方不存在隶属、认可或背书关系。
+
+MIT License 只覆盖本仓库的软件代码，不自动覆盖图片、角色设计、人物肖像、商标、截图或其他第三方内容。免责声明、「仅供学习」「非商业用途」「粉丝作品」「来自网络」或「AI 生成」等表述，不会产生授权，也不会替代原作者、肖像权人或商标权人的许可。
+
+当前视觉素材的逐项证据与处置状态见 `ASSET_PROVENANCE.md`。部分素材缺少完整来源记录，公开打包、Release 和再分发仍有发布风险。项目所有者已在知悉该边界后确认随 `v5.2.1` 公开发布；该确认不构成对第三方权利的法律判断。使用者在复制、修改或再次分发这些素材前，应自行评估并取得所需权利。
+
+Hatsune Miku（初音未来）、Genshin Impact（原神）、Wuthering Waves（鸣潮）、Naruto（火影忍者）、Love and Deepspace（恋与深空）及相关名称、角色设计和标识归各自权利人所有。提及这些名称只用于描述现有预设，不表示获得许可。
+
+## English summary
+
+The MIT License covers software code only. It does not grant permission to copy or redistribute bundled artwork, screenshots, likenesses, character designs, or trademarks. The project owner has explicitly accepted the documented provenance risk for the v5.2.1 public release. See `ASSET_PROVENANCE.md` before further redistribution.

package/src/assets/skins/heige/themes/dalao-dianyan/theme.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "id": "dalao-dianyan",
+  "name": "大佬 · 点烟",
+  "hero": "hero.webp",
+  "appearance": "dark",
+  "previewFocus": { "x": 50, "y": 8 },
+  "colors": {
+    "accent": "#e09a52",
+    "secondary": "#9aa3b0",
+    "surface": "#111111",
+    "text": "#f2e8da"
+  }
+}

package/src/assets/skins/heige/themes/deepspace-dawn/theme.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "id": "deepspace-dawn",
+  "name": "恋与深空 · 晨曦",
+  "hero": "hero.webp",
+  "appearance": "light",
+  "previewFocus": { "x": 50, "y": 8 },
+  "colors": {
+    "accent": "#8f7fe8",
+    "secondary": "#f097c8",
+    "surface": "#f6f2fb",
+    "text": "#4a4668"
+  }
+}

package/src/assets/skins/heige/themes/deepspace-star/theme.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "id": "deepspace-star",
+  "name": "恋与深空 · 星辰",
+  "hero": "hero.webp",
+  "appearance": "dark",
+  "previewFocus": { "x": 50, "y": 8 },
+  "colors": {
+    "accent": "#9d8bff",
+    "secondary": "#f097c8",
+    "surface": "#201a40",
+    "text": "#e8e2ff"
+  }
+}

package/src/assets/skins/heige/themes/dragonball-nimbus/theme.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "id": "dragonball-nimbus",
+  "name": "龙珠 · 筋斗云",
+  "hero": "hero.webp",
+  "appearance": "light",
+  "previewFocus": { "x": 72, "y": 24 },
+  "thumbnailFocus": { "x": 66, "y": 31 },
+  "thumbnailZoom": 350,
+  "colors": {
+    "accent": "#4FC3F7",
+    "secondary": "#F6C445",
+    "surface": "#F3F7FF",
+    "text": "#14213D"
+  }
+}

package/src/assets/skins/heige/themes/dragonball-super-saiyan/theme.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "id": "dragonball-super-saiyan",
+  "name": "龙珠 · 超级赛亚人",
+  "hero": "hero.webp",
+  "appearance": "light",
+  "previewFocus": { "x": 67, "y": 3 },
+  "thumbnailFocus": { "x": 67, "y": 15 },
+  "thumbnailZoom": 400,
+  "colors": {
+    "accent": "#F5C451",
+    "secondary": "#52C7F2",
+    "surface": "#FFF8E8",
+    "text": "#282033"
+  }
+}

package/src/assets/skins/heige/themes/genshin-dawn/theme.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "id": "genshin-dawn",
+  "name": "原神 · 晨曦",
+  "hero": "hero.webp",
+  "appearance": "light",
+  "previewFocus": { "x": 50, "y": 24 },
+  "colors": {
+    "accent": "#5b7fd6",
+    "secondary": "#e0aa3e",
+    "surface": "#f2f1fb",
+    "text": "#2c3a6b"
+  }
+}

package/src/assets/skins/heige/themes/genshin-night/theme.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "id": "genshin-night",
+  "name": "原神 · 星夜",
+  "hero": "hero.webp",
+  "appearance": "dark",
+  "previewFocus": { "x": 50, "y": 17 },
+  "colors": {
+    "accent": "#e0b458",
+    "secondary": "#7a86d8",
+    "surface": "#171a2e",
+    "text": "#f0e6c8"
+  }
+}