@clowder-ai/companion 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clowder AI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,4 @@
+Companion imagery and theme tokens originate in Clowder AI (MIT).
+See source-lock.json for the exact public source revision and content hashes.
+The conversation transport and controls continue the F317 companion implementation
+by the Clowder AI contributors. No private runtime data or pet metadata is included.

package/manifest.json

@@ -0,0 +1,55 @@
+{
+  "pluginId": "official.companion",
+  "version": "0.1.0-alpha.1",
+  "contractVersion": "0.1.0",
+  "name": "猫猫球",
+  "icon": {
+    "type": "png",
+    "src": "renderer/skins/ragdoll-v1.png"
+  },
+  "description": {
+    "default": "Talk, think and find your shared history with your companion.",
+    "translations": {
+      "zh-CN": "和猫猫说话、查资料，回到同一段聊天继续工作。"
+    }
+  },
+  "runtime": {
+    "transport": "builtin"
+  },
+  "features": [
+    {
+      "id": "companion",
+      "name": "猫猫球",
+      "resources": [],
+      "capabilities": [
+        "windows.create"
+      ],
+      "contributions": [
+        {
+          "type": "desktop-window",
+          "id": "companion"
+        }
+      ]
+    }
+  ],
+  "contributions": [
+    {
+      "type": "desktop-window",
+      "id": "companion",
+      "role": "companion",
+      "bridgeVersion": "1.0.0",
+      "surface": {
+        "entrypoint": "renderer/index.html",
+        "integrity": "sha256-yVHMFz5zEuDTwQO/pgNRScotBqRzGd9o9wIIhadJDNQ="
+      },
+      "presentation": {
+        "width": 330,
+        "height": 350,
+        "frame": false,
+        "transparent": true,
+        "alwaysOnTop": true,
+        "skipTaskbar": true
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@clowder-ai/companion",
+  "version": "0.1.0-alpha.1",
+  "description": "The desktop voice body for your Clowder companion",
+  "license": "MIT",
+  "type": "module",
+  "files": ["renderer", "plugin.yaml", "manifest.json", "LICENSE", "NOTICE", "source-lock.json"],
+  "exports": { "./manifest": "./manifest.json" },
+  "engines": { "node": ">=22.12.0" },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node --test test/*.test.mjs",
+    "typecheck": "node scripts/check.mjs",
+    "lint": "node scripts/check.mjs",
+    "prepack": "pnpm build"
+  },
+  "devDependencies": {
+    "@clowder-ai/plugin-contract": "0.1.0-beta.16",
+    "@clowder-ai/plugin-sdk": "0.1.0-beta.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zts212653/clowder-ai-plugins.git",
+    "directory": "packages/companion"
+  }
+}

package/plugin.yaml

@@ -0,0 +1,55 @@
+{
+  "pluginId": "official.companion",
+  "version": "0.1.0-alpha.1",
+  "contractVersion": "0.1.0",
+  "name": "猫猫球",
+  "icon": {
+    "type": "png",
+    "src": "renderer/skins/ragdoll-v1.png"
+  },
+  "description": {
+    "default": "Talk, think and find your shared history with your companion.",
+    "translations": {
+      "zh-CN": "和猫猫说话、查资料，回到同一段聊天继续工作。"
+    }
+  },
+  "runtime": {
+    "transport": "builtin"
+  },
+  "features": [
+    {
+      "id": "companion",
+      "name": "猫猫球",
+      "resources": [],
+      "capabilities": [
+        "windows.create"
+      ],
+      "contributions": [
+        {
+          "type": "desktop-window",
+          "id": "companion"
+        }
+      ]
+    }
+  ],
+  "contributions": [
+    {
+      "type": "desktop-window",
+      "id": "companion",
+      "role": "companion",
+      "bridgeVersion": "1.0.0",
+      "surface": {
+        "entrypoint": "renderer/index.html",
+        "integrity": "sha256-yVHMFz5zEuDTwQO/pgNRScotBqRzGd9o9wIIhadJDNQ="
+      },
+      "presentation": {
+        "width": 330,
+        "height": 350,
+        "frame": false,
+        "transparent": true,
+        "alwaysOnTop": true,
+        "skipTaskbar": true
+      }
+    }
+  ]
+}

package/renderer/client.mjs

@@ -0,0 +1,42 @@
+export class CompanionRequestError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'CompanionRequestError';
+    }
+}
+/** Browser-safe client: no Node imports, credentials, second transcript store or transport fallback. */
+export function createCompanionClient(bridge) {
+    async function invoke(command, kind) {
+        const reply = await bridge.request(command);
+        if (reply.kind === 'error')
+            throw new CompanionRequestError(reply.code);
+        if (reply.kind !== kind)
+            throw new CompanionRequestError('unavailable');
+        return reply;
+    }
+    return {
+        state: () => invoke({ kind: 'state' }, 'state'),
+        prepare: () => invoke({ kind: 'prepare' }, 'state'),
+        connectAudio: () => invoke({ kind: 'audio.connect' }, 'ok'),
+        closeAudio: () => invoke({ kind: 'audio.close' }, 'ok'),
+        muteMicrophone: (muted) => invoke({ kind: 'audio.microphone', muted }, 'ok'),
+        muteSpeaker: (muted) => invoke({ kind: 'audio.speaker', muted }, 'ok'),
+        stop: () => invoke({ kind: 'stop' }, 'ok'),
+        text: async (text, clientMessageId) => {
+            const receipt = await invoke({ kind: 'text', text, clientMessageId }, 'delivery');
+            if (receipt.delivery !== 'accepted')
+                throw new CompanionRequestError('unconfirmed');
+            return receipt;
+        },
+        documents: (allowed) => invoke({ kind: 'documents', allowed }, 'state'),
+        screenPick: async () => (await invoke({ kind: 'screen.pick' }, 'selection')).selectionId,
+        screenOpen: (selectionId, label) => invoke({ kind: 'screen.open', selectionId, label }, 'ok'),
+        screenFrame: (selectionId, frame) => invoke({ kind: 'screen.frame', selectionId, frame }, 'ok'),
+        screenClose: () => invoke({ kind: 'screen.close' }, 'ok'),
+        openConversation: () => invoke({ kind: 'conversation.open' }, 'navigation'),
+        resize: (expanded) => invoke({ kind: 'view.resize', expanded }, 'ok'),
+        subscribe: (listener) => bridge.subscribe(listener),
+    };
+}

package/renderer/conversation.mjs

@@ -0,0 +1,122 @@
+import { explainError } from './errors.mjs';
+
+/** Local controls only. Durable messages, identity and preferences belong to the Host. */
+export class CompanionConversation {
+  constructor({ client, createPeer, render, transcript, stopScreen, uuid = () => crypto.randomUUID() }) {
+    Object.assign(this, { client, createPeer, render, transcript, stopScreen, uuid });
+    this.active = false;
+    this.generation = 0;
+    this.phase = 'idle';
+    this.muted = false;
+    this.silent = false;
+  }
+  show(message) {
+    this.message = message;
+    this.render({ phase: this.phase, identity: this.identity, muted: this.muted, silent: this.silent, message });
+  }
+  current(generation) { return this.active && generation === this.generation; }
+  listening() { return this.muted ? '麦克风已静音' : '正在听，直接说话就好'; }
+  async begin() {
+    if (this.active || this.stopping || this.changingDocuments) return;
+    this.active = true;
+    this.phase = 'connecting';
+    const generation = ++this.generation;
+    // Must reach the isolated preload while the click still has user activation.
+    const preparation = this.client.prepare();
+    this.show('正在连接…');
+    this.deadline = setTimeout(() => { if (this.current(generation)) void this.end('连接超时 · 点击开始聊天重试'); }, 60_000);
+    try {
+      const identity = await preparation;
+      if (!this.current(generation)) return;
+      if (identity.phase !== 'ready') throw { code: 'unavailable' };
+      this.identity = identity;
+      const peer = this.createPeer(event => {
+        if (!this.current(generation)) return;
+        if (event.type === 'connected') { clearTimeout(this.deadline); this.phase = 'talking'; this.show(this.listening()); }
+        if (event.type === 'recovering') this.show('连接暂时中断 · 正在等待恢复');
+        if (event.type === 'recovered') this.show(this.listening());
+        if (event.type === 'transcript' || event.type === 'turn-done') this.transcript(event);
+        if (event.type === 'error') void this.end(explainError(event));
+      });
+      this.peer = peer;
+      peer.muteMic(this.muted); peer.muteSpeaker(this.silent);
+      await peer.connect();
+      if (!this.current(generation)) await peer.close();
+    } catch (error) {
+      if (this.current(generation)) await this.end(explainError(error));
+    }
+  }
+  async releaseLocal(message) {
+    this.active = false;
+    ++this.generation;
+    this.pendingText = undefined;
+    clearTimeout(this.deadline);
+    const peer = this.peer;
+    this.peer = undefined;
+    this.phase = 'idle';
+    this.show(message);
+    await Promise.allSettled([peer?.close(), this.stopScreen()]);
+  }
+  async end(message = '语音已结束 · 麦克风已关闭') {
+    if (this.stopping) return this.stopping;
+    const local = this.releaseLocal(message);
+    const operation = Promise.all([local, this.client.stop()]);
+    this.stopping = operation;
+    try { await operation; }
+    catch { this.show('麦克风已关闭 · 连接收尾尚未确认'); }
+    finally { if (this.stopping === operation) this.stopping = undefined; }
+  }
+  async refresh() {
+    if (this.refreshing) return;
+    this.refreshing = true;
+    const generation = this.generation;
+    try {
+      const identity = await this.client.state();
+      if (generation !== this.generation) return;
+      this.identity = identity;
+      if (this.active && ['closed', 'failed', 'idle'].includes(identity.phase)) {
+        await this.end('连接已结束 · 点击开始聊天继续');
+      } else this.show(this.message ?? '点开始聊天，直接对我说话');
+    } catch (error) {
+      if (generation === this.generation) {
+        if (this.active) await this.end(explainError(error));
+        else this.show(explainError(error));
+      }
+    } finally { this.refreshing = false; }
+  }
+  async documents(allowed) {
+    if (this.changingDocuments) return;
+    this.changingDocuments = true;
+    // No implicit new microphone grant after changing a preference.
+    const changing = this.client.documents(allowed);
+    const local = this.releaseLocal('正在更新资料查询设置…');
+    try {
+      const identity = await changing;
+      await local;
+      this.identity = identity;
+      this.show(allowed ? '资料查询已开启 · 点击开始聊天继续' : '资料查询已暂停 · 点击开始聊天继续');
+    } catch (error) { this.show(explainError(error)); }
+    finally { this.changingDocuments = false; }
+  }
+  async send(text) {
+    text = text.trim();
+    if (!text || !this.active || this.phase !== 'talking' || this.sending) return false;
+    if (!this.pendingText || this.pendingText.text !== text) this.pendingText = { text, id: this.uuid() };
+    const input = this.pendingText;
+    const generation = this.generation;
+    this.sending = true;
+    try {
+      await this.client.text(input.text, input.id);
+      if (this.pendingText === input) this.pendingText = undefined;
+      if (!this.current(generation)) return false;
+      this.transcript({ type: 'transcript', role: 'user', text, typed: true });
+      this.show(this.listening());
+      return true;
+    } catch (error) {
+      if (this.current(generation)) this.show(explainError(error));
+      return false;
+    } finally { this.sending = false; }
+  }
+  muteMic() { this.muted = !this.muted; this.peer?.muteMic(this.muted); this.show(this.phase === 'talking' ? this.listening() : this.message); }
+  muteSpeaker() { this.silent = !this.silent; this.peer?.muteSpeaker(this.silent); this.show(this.message); }
+}

package/renderer/errors.mjs

@@ -0,0 +1,13 @@
+const messages = {
+  permission_required: '请点击开始聊天，或在系统提示中允许本次使用',
+  session_required: '连接已结束 · 点击开始聊天继续',
+  busy: '上一段交流正在收尾 · 稍后再开始',
+  selection_changed: '猫猫球的选择已更新 · 点击开始聊天继续',
+  carrier_unavailable: '实时语音暂不可用 · 可以打开聊天继续交流',
+  cancelled: '操作已取消',
+  unconfirmed: '发送尚未确认 · 文字已保留，可检查聊天记录后重试',
+};
+export function explainError(error) {
+  if (error?.name === 'NotAllowedError') return '未获得麦克风权限 · 请在系统设置中允许后重试';
+  return messages[error?.code] ?? '连接暂时不可用 · 请重试或打开聊天继续';
+}

package/renderer/index.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>猫猫球</title><link rel="stylesheet" href="./theme.css"><link rel="stylesheet" href="./style.css"></head>
+<body>
+  <section id="details" hidden>
+    <header><strong id="chat-name">猫猫</strong><span>本次交流</span><button type="button" id="collapse" aria-label="收起文字">收起 ⌄</button></header>
+    <div id="transcript" role="log" aria-live="polite"><p class="empty">可以直接说，也可以写一句。</p></div>
+    <form id="compose"><input id="message" aria-label="给猫猫写一句" placeholder="写一句…" maxlength="8000"><button type="submit" aria-label="发送">↑</button></form>
+  </section>
+  <div id="pet" aria-label="猫猫，拖动可以移动" role="img"></div>
+  <section id="dock" aria-label="和猫猫交流">
+  <p id="identity">猫猫球</p>
+  <div class="voice-state"><div id="orb" aria-hidden="true"></div><p id="status" role="status">点开始聊天，直接对我说话</p></div>
+  <div id="idle"><button type="button" id="begin" disabled>开始聊天</button></div>
+  <div id="controls" hidden>
+    <button type="button" id="mic" aria-label="关闭麦克风" title="关闭麦克风"><svg aria-hidden="true" viewBox="0 0 24 24"><rect x="9" y="3" width="6" height="12" rx="3"/><path d="M5 11a7 7 0 0 0 14 0M12 18v4M8 22h8"/></svg><span>静音</span></button>
+    <button type="button" id="speaker" aria-label="关闭播音" title="关闭播音"><svg aria-hidden="true" viewBox="0 0 24 24"><path d="m11 4-6 5H2v6h3l6 5zM15 8a6 6 0 0 1 0 8M18 4a11 11 0 0 1 0 16"/></svg><span>关声音</span></button>
+    <button type="button" id="write" aria-label="展开文字交流" aria-expanded="false" title="写一句 / 看文字"><svg aria-hidden="true" viewBox="0 0 24 24"><path d="M13 5H6a2 2 0 0 0-2 2v11a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2v-7M15 4l5 5M9 15l1-5 8-8 4 4-8 8z"/></svg><span>文字</span></button>
+    <button type="button" id="end" aria-label="结束语音" title="结束本次通话"><svg aria-hidden="true" viewBox="0 0 24 24"><path d="m7 7 10 10M7 17 17 7"/></svg><span>结束</span></button>
+  </div>
+  <div id="access">
+    <button type="button" id="history">打开聊天</button>
+    <button type="button" id="share" hidden title="选择窗口或屏幕后共享给当前模型；不共享系统声音">共享屏幕</button>
+    <button type="button" id="documents" title="资料查询设置；不包含屏幕共享">资料查询</button>
+  </div>
+  <p id="screen-status" role="status" hidden></p>
+  <p id="connection-scope"></p>
+  </section>
+  <script type="module" src="./surface.mjs"></script>
+</body></html>

package/renderer/peer.mjs

@@ -0,0 +1,23 @@
+/** Presentation adapter only. The Host preload owns capture, SDP and the provider channel. */
+export class VoicePeer {
+  constructor(onEvent, client) {
+    this.onEvent = onEvent;
+    this.client = client;
+    this.unsubscribe = client.subscribe(event => {
+      if (!this.closed && event.kind === 'audio') {
+        const { kind, ...value } = event;
+        this.onEvent(value);
+      }
+    });
+  }
+  async connect() { if (!this.closed) await this.client.connectAudio(); }
+  muteMic(muted) { void this.client.muteMicrophone(muted).catch(() => this.failed()); }
+  muteSpeaker(muted) { void this.client.muteSpeaker(muted).catch(() => this.failed()); }
+  failed() { if (!this.closed) this.onEvent({ type: 'error', code: 'unavailable' }); }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.unsubscribe();
+    await this.client.closeAudio();
+  }
+}

package/renderer/screen-share.mjs

@@ -0,0 +1,100 @@
+export class ScreenShare {
+  constructor(api, onState, media = navigator.mediaDevices, elements = document) {
+    this.api = api;
+    this.onState = onState;
+    this.media = media;
+    this.elements = elements;
+    this.epoch = 0;
+  }
+  async start() {
+    if (this.pending || this.stream) return;
+    const stopped = this.stop();
+    const selection = this.api.screenRequest();
+    const epoch = this.epoch;
+    this.pending = true;
+    this.onState({ sharing: false, pending: true, message: '请在系统选择器中选择窗口或屏幕' });
+    let stream;
+    try {
+      const [, selectionId] = await Promise.all([stopped, selection]);
+      if (epoch !== this.epoch) return;
+      // macOS system picker supplies the exact source. Audio has a separate grant.
+      stream = await this.media.getDisplayMedia({ video: { frameRate: 2 }, audio: false });
+      if (epoch !== this.epoch) {
+        stream.getTracks().forEach((track) => {
+          track.stop();
+        });
+        return;
+      }
+      this.stream = stream;
+      const track = stream.getVideoTracks()[0];
+      if (!track) throw new Error('没有取得共享画面');
+      const checkTrack = () => {
+        if (track.readyState !== 'live' || track.muted) throw new Error('共享画面已结束');
+      };
+      const ended = () => void this.stop('画面已不可用 · 共享已停止').catch(() => {
+        this.onState({ sharing: false, pending: false, message: '画面已停止 · Host撤销尚未确认' });
+      });
+      track.onended = ended;
+      track.onmute = ended;
+      checkTrack();
+      const label = track.label || '所选画面';
+      await this.api.screenStart(selectionId, label);
+      if (epoch !== this.epoch) return;
+      checkTrack();
+      this.video = this.elements.createElement('video');
+      this.video.muted = true;
+      this.video.srcObject = stream;
+      await this.video.play();
+      if (epoch !== this.epoch) return;
+      this.canvas = this.elements.createElement('canvas');
+      const capture = async () => {
+        if (epoch !== this.epoch) return;
+        checkTrack();
+        const { videoWidth: width, videoHeight: height } = this.video;
+        if (!width || !height) throw new Error('暂时没有可用画面');
+        const scale = Math.min(1, 1280 / Math.max(width, height));
+        this.canvas.width = Math.max(1, Math.round(width * scale));
+        this.canvas.height = Math.max(1, Math.round(height * scale));
+        this.canvas.getContext('2d').drawImage(this.video, 0, 0, this.canvas.width, this.canvas.height);
+        await this.api.screenFrame(selectionId, {
+          width: this.canvas.width,
+          height: this.canvas.height,
+          image: this.canvas.toDataURL('image/jpeg', 0.7),
+        });
+        if (epoch === this.epoch)
+          this.timer = setTimeout(() => void capture().catch(() => this.stop('画面暂不可用 · 共享已停止')), 1500);
+      };
+      await capture();
+      if (epoch !== this.epoch) return;
+      this.pending = false;
+      this.onState({ sharing: true, pending: false, label });
+    } catch (error) {
+      stream?.getTracks().forEach((track) => {
+        track.stop();
+      });
+      if (epoch === this.epoch)
+        await this.stop(
+          error.name === 'NotAllowedError'
+            ? '未能开始共享：没有选定画面或系统未允许。可点共享屏幕重试。'
+            : '未能开始共享 · 请重试',
+        );
+    }
+  }
+  async stop(message = '未共享屏幕') {
+    this.epoch++;
+    this.pending = false;
+    clearTimeout(this.timer);
+    this.stream?.getTracks().forEach((track) => {
+      track.onended = null;
+      track.onmute = null;
+      track.stop();
+    });
+    this.stream = undefined;
+    this.video?.pause();
+    if (this.video) this.video.srcObject = null;
+    this.video = undefined;
+    this.canvas = undefined;
+    this.onState({ sharing: false, pending: false, message });
+    await this.api.screenStop();
+  }
+}

package/renderer/style.css

@@ -0,0 +1,309 @@
+* {
+  box-sizing: border-box;
+}
+html,
+body {
+  margin: 0;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: transparent;
+}
+body {
+  font:
+    13px -apple-system,
+    BlinkMacSystemFont,
+    "PingFang SC",
+    sans-serif;
+  color: var(--cafe-text);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: flex-end;
+  padding: 10px;
+}
+[hidden] {
+  display: none !important;
+}
+button,
+input {
+  font: inherit;
+}
+button {
+  cursor: pointer;
+  border: 0;
+  color: inherit;
+}
+button:focus-visible,
+input:focus-visible {
+  outline: 2px solid var(--cafe-accent);
+  outline-offset: 3px;
+}
+button:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+#pet {
+  width: 96px;
+  height: 104px;
+  flex-shrink: 0;
+  background: url("./skins/yanyan-codex.webp") 0 0 / 768px 936px;
+  animation: idle 4.8s steps(6) infinite;
+  -webkit-app-region: drag;
+  filter: drop-shadow(0 4px 5px #0003);
+}
+@keyframes idle {
+  to {
+    background-position-x: -576px;
+  }
+}
+#dock {
+  width: 100%;
+  flex-shrink: 0;
+  padding: 11px 12px 10px;
+  background: var(--cafe-surface-elevated);
+  border: 1px solid var(--cafe-border-subtle);
+  border-radius: 20px;
+  box-shadow: 0 4px 16px #0002;
+}
+.voice-state {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 7px;
+  min-height: 25px;
+}
+#orb {
+  width: 8px;
+  height: 8px;
+  flex-shrink: 0;
+  border-radius: 50%;
+  background: var(--cafe-text-muted);
+}
+body.connecting #orb {
+  background: var(--semantic-warning);
+  animation: pulse 1.5s ease-in-out infinite;
+}
+body.connected #orb {
+  background: var(--semantic-success);
+  animation: pulse 3.5s ease-in-out infinite;
+}
+@keyframes pulse {
+  50% {
+    opacity: 0.5;
+  }
+}
+#status {
+  margin: 0;
+  line-height: 1.45;
+  text-align: center;
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+#idle {
+  padding: 7px 0 4px;
+}
+#begin {
+  width: 100%;
+  border-radius: 12px;
+  padding: 10px 20px;
+  font-weight: 600;
+  background: var(--accent-100);
+}
+#begin:hover {
+  background: var(--accent-200);
+}
+#controls {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 4px;
+  padding: 6px 0 9px;
+}
+#controls button {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 5px;
+  min-height: 51px;
+  border-radius: 11px;
+  background: transparent;
+  font-size: 11px;
+  white-space: nowrap;
+}
+#controls button:hover {
+  background: var(--cafe-surface);
+}
+#controls button[aria-pressed="true"],
+#controls button[aria-expanded="true"] {
+  background: var(--accent-100);
+  color: var(--accent-700);
+}
+#controls #end {
+  color: var(--semantic-critical);
+}
+#controls #end:hover {
+  background: var(--semantic-critical-surface);
+}
+#controls svg {
+  width: 19px;
+  height: 19px;
+  stroke: currentColor;
+  fill: none;
+  stroke-width: 1.8;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+#access {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  padding-top: 7px;
+  border-top: 1px solid var(--cafe-border-subtle);
+}
+#share {
+  flex: 1;
+  min-height: 32px;
+  padding: 6px 10px;
+  border-radius: 9px;
+  font-weight: 600;
+  background: var(--accent-100);
+  color: var(--accent-700);
+}
+#share:hover {
+  background: var(--accent-200);
+}
+#share[aria-pressed="true"] {
+  background: var(--semantic-success-surface);
+  color: var(--semantic-success);
+}
+#documents {
+  background: transparent;
+  color: var(--cafe-text-secondary);
+  font-size: 11px;
+  padding: 7px 3px;
+  border-radius: 6px;
+}
+#documents:hover {
+  background: var(--cafe-surface);
+}
+#screen-status {
+  margin: 8px 0 0;
+  padding: 7px 9px;
+  font-size: 11px;
+  line-height: 1.5;
+  overflow-wrap: anywhere;
+  border-radius: 8px;
+  background: var(--semantic-warning-surface);
+  color: var(--cafe-text-secondary);
+}
+#screen-status[data-state="sharing"] {
+  background: var(--semantic-success-surface);
+}
+#connection-scope {
+  margin: 7px 0 0;
+  text-align: center;
+  font-size: 10px;
+  line-height: 1.4;
+  color: var(--cafe-text-muted);
+}
+#details {
+  align-self: stretch;
+  min-height: 0;
+  flex: 1;
+  margin-bottom: 5px;
+  background: var(--cafe-surface-elevated);
+  border: 1px solid var(--cafe-border-subtle);
+  border-radius: 18px;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  box-shadow: 0 3px 16px #0002;
+}
+#details header {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--cafe-border-subtle);
+}
+#details header span {
+  color: var(--cafe-text-muted);
+  font-size: 11px;
+  flex: 1;
+}
+#collapse {
+  background: transparent;
+  font-size: 12px;
+  padding: 4px;
+  color: var(--cafe-text-secondary);
+}
+#transcript {
+  min-height: 0;
+  flex: 1;
+  overflow-y: auto;
+  padding: 10px 14px;
+  line-height: 1.65;
+}
+#transcript p {
+  margin: 0 0 12px;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+#transcript .user {
+  color: var(--cafe-text-secondary);
+}
+#transcript .user::before,
+#transcript .assistant::before {
+  display: block;
+  margin-bottom: 3px;
+  font-size: 10px;
+  color: var(--cafe-text-muted);
+}
+#transcript .user::before {
+  content: "你";
+}
+#transcript .assistant::before {
+  content: var(--speaker-label, "猫猫");
+}
+#transcript .tool {
+  font-size: 11px;
+  color: var(--cafe-text-secondary);
+}
+.empty {
+  color: var(--cafe-text-muted);
+}
+#compose {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  border-top: 1px solid var(--cafe-border-subtle);
+  padding: 9px;
+}
+#message {
+  width: 100%;
+  min-width: 0;
+  border: 0;
+  padding: 5px 3px;
+  background: transparent;
+  color: inherit;
+}
+#compose button {
+  border-radius: 50%;
+  background: var(--accent-100);
+  min-width: 30px;
+  height: 30px;
+}
+@media (prefers-reduced-motion: reduce) {
+  #pet,
+  body.connecting #orb,
+  body.connected #orb {
+    animation: none;
+  }
+}
+#history { background: transparent; color: var(--cafe-text-secondary); padding: 7px 3px; font-size: 11px; }
+#identity { margin: 0 0 3px; text-align: center; font-weight: 600; }
+#pet[data-skin="xianxian-codex"] { background-image: url("./skins/xianxian-codex.webp"); }
+#pet[data-skin="ragdoll-v1"], #pet[data-skin="yarn-ball"] { background: url("./skins/ragdoll-v1.png") center / contain no-repeat; animation: none; }
+#pet[data-skin="yarn-ball"] { background-image: url("./skins/yarn-ball.png"); }

package/renderer/surface.mjs

@@ -0,0 +1,105 @@
+import { createCompanionClient } from './client.mjs';
+import { CompanionConversation } from './conversation.mjs';
+import { explainError } from './errors.mjs';
+import { VoicePeer } from './peer.mjs';
+import { ScreenShare } from './screen-share.mjs';
+import { TranscriptView } from './transcript-view.mjs';
+
+const $ = id => document.getElementById(id);
+const status = text => { $('status').textContent = text; };
+const transcript = new TranscriptView($('transcript'));
+let expanded = false;
+let sharing = false;
+let pendingScreen = false;
+
+if (!window.clowderCompanion) {
+  status('请从 Clowder 的插件页面打开猫猫球');
+  for (const id of ['begin', 'documents', 'history']) $(id).disabled = true;
+} else {
+  const client = createCompanionClient(window.clowderCompanion);
+  const screen = new ScreenShare({
+    screenRequest: () => client.screenPick(),
+    screenStart: (selectionId, label) => client.screenOpen(selectionId, label),
+    screenFrame: (selectionId, frame) => client.screenFrame(selectionId, {
+      ...frame, frameId: crypto.randomUUID(), sourceLabel: '所选画面', observedAt: Date.now(),
+    }),
+    screenStop: () => client.screenClose(),
+  }, value => {
+    sharing = value.sharing;
+    pendingScreen = value.pending === true;
+    $('share').textContent = sharing ? '停止共享' : pendingScreen ? '取消选屏' : '共享屏幕';
+    $('share').setAttribute('aria-pressed', String(sharing));
+    $('screen-status').hidden = !sharing && !pendingScreen && value.message === '未共享屏幕';
+    $('screen-status').textContent = sharing ? `正在共享：${value.label}` : value.message;
+    $('screen-status').dataset.state = sharing ? 'sharing' : pendingScreen ? 'pending' : 'stopped';
+  });
+  const conversation = new CompanionConversation({
+    client, createPeer: callback => new VoicePeer(callback, client), stopScreen: () => screen.stop(),
+    transcript: event => event.type === 'turn-done' ? transcript.finish(event) : transcript.append(event.role, event.text, !event.typed),
+    render(value) {
+      const active = value.phase !== 'idle';
+      document.body.className = value.phase === 'talking' ? 'connected' : active ? 'connecting' : '';
+      $('idle').hidden = active; $('controls').hidden = !active;
+      $('share').hidden = value.phase !== 'talking';
+      $('compose').querySelector('button').disabled = value.phase !== 'talking';
+      $('begin').disabled = !value.identity;
+      status(value.message);
+      const identity = value.identity;
+      if (identity) {
+        $('identity').textContent = identity.displayName;
+        $('chat-name').textContent = identity.displayName;
+        $('pet').setAttribute('aria-label', `${identity.displayName}，拖动可以移动`);
+        $('pet').dataset.skin = identity.skin;
+        $('dock').setAttribute('aria-label', `和${identity.displayName}交流`);
+        $('message').setAttribute('aria-label', `给${identity.displayName}写一句`);
+        document.documentElement.style.setProperty('--speaker-label', JSON.stringify(identity.carrier.displayName));
+        $('documents').textContent = `资料查询 · ${identity.documentsAllowed ? '开启' : '暂停'}`;
+        $('documents').setAttribute('aria-pressed', String(identity.documentsAllowed));
+        $('connection-scope').textContent = identity.duty.catId === identity.carrier.catId
+          ? (active && identity.documentsAllowed ? `资料工具 · ${identity.toolsReady ? '已连接' : '连接中'}` : '交流保存在同一段聊天中')
+          : `${identity.duty.displayName} · 实时语音由${identity.carrier.displayName}承载`;
+      }
+      for (const [id, muted, target, off, on] of [
+        ['mic', value.muted, '麦克风', '取消静音', '静音'],
+        ['speaker', value.silent, '播音', '开声音', '关声音'],
+      ]) {
+        $(id).setAttribute('aria-pressed', String(muted));
+        $(id).setAttribute('aria-label', `${muted ? '开启' : '关闭'}${target}`);
+        $(id).querySelector('span').textContent = muted ? off : on;
+      }
+    },
+  });
+  function details(value) {
+    expanded = value;
+    $('details').hidden = !value;
+    $('write').setAttribute('aria-expanded', String(value));
+    void client.resize(value).catch(error => status(explainError(error)));
+  }
+  $('begin').onclick = () => { transcript.reset(); void conversation.begin(); };
+  $('end').onclick = () => void conversation.end();
+  $('mic').onclick = () => conversation.muteMic();
+  $('speaker').onclick = () => conversation.muteSpeaker();
+  $('write').onclick = () => details(!expanded);
+  $('collapse').onclick = () => details(false);
+  $('share').onclick = () => void (sharing || pendingScreen ? screen.stop('屏幕共享已停止') : screen.start()).catch(() => status('屏幕共享已停止'));
+  $('history').onclick = () => void client.openConversation().then(result => {
+    if (result.delivery === 'unconfirmed') status('打开聊天尚未确认 · 请从 Clowder 查看猫猫球聊天');
+  }).catch(error => status(explainError(error)));
+  $('documents').onclick = () => void conversation.documents(conversation.identity?.documentsAllowed === false);
+  $('compose').onsubmit = async event => {
+    event.preventDefault();
+    const text = $('message').value;
+    if (await conversation.send(text)) {
+      if ($('message').value === text) $('message').value = '';
+    }
+  };
+  const unsubscribe = client.subscribe(event => {
+    if (event.kind === 'media-stopped') void conversation.releaseLocal('语音已停止 · 点击开始聊天继续');
+  });
+  const monitor = setInterval(() => void conversation.refresh(), 3000);
+  void conversation.refresh();
+  window.addEventListener('beforeunload', () => {
+    clearInterval(monitor); unsubscribe();
+    void conversation.end();
+  });
+}

package/renderer/theme.css

@@ -0,0 +1,267 @@
+/*
+ * F056 Phase E — OKLCH 系统化升级 · Design System Primitives
+ *
+ * 本文件持有"非身份性"七类色 token + Brand alias + Surface/Elevation/Scrim + cafe 兼容 alias。
+ *
+ * 拆分（每文件 ≤350 行硬限制 + design system 关注点分离）：
+ *   theme-tokens.css       — primitives：Brand + Neutral + Accent + Semantic + Code + Chart + Avatar Fallback + Scrim + cafe alias
+ *   cat-persona-tokens.css — Cat Persona 单 hue 派生（每只猫 4 档 × 2 mode）
+ *   connector-tokens.css   — IM connector 品牌色（独立体系，不随主题派生）
+ *   theme-extras.css       — F155 Guide tokens + warm-pastel Notice tokens
+ *
+ * 哲学：HSL 是给程序员算颜色方便的，OKLCH 是给用户感知一致的。
+ *       统一 token 派生公式让"换主题色 = 改一个 hue 值，全应用自动适配"。
+ */
+
+:root {
+  /* ============================================================
+   * Layer 0: Brand + Hue/Chroma anchors
+   *
+   * --accent-hue 控制品牌/交互色（按钮、链接、accent scale）。
+   * --surface-hue 控制页面底色色调（独立于 accent，KD-34）。
+   * 原始 #fdf8f3 ≈ oklch(0.98 0.008 ~80)，warm-beige/vanilla。
+   * ============================================================ */
+  --accent-hue: 50; /* warm gold — 品牌主色旋钮（aligned with INIT_LIGHT） */
+  --accent-chroma: 0.14;
+  --surface-hue: 80; /* warm beige — 页面底色旋钮，独立于 accent（KD-34） */
+  --surface-chroma: 0.01; /* surface 四档共享色度 — Tuner 调一个全变 */
+  --brand-cat-cafe-pink: oklch(0.62 var(--accent-chroma) var(--accent-hue)); /* 派生 — logo / splash */
+}
+
+/* ============================================================
+ * LIGHT MODE (default :root)
+ * ============================================================ */
+:root {
+  /* --- 1. Neutral 11档（warm neutral, hue ~30, low chroma） --- */
+  --neutral-50: oklch(0.985 0.005 30);
+  --neutral-100: oklch(0.965 0.005 30);
+  --neutral-200: oklch(0.915 0.005 30);
+  --neutral-300: oklch(0.84 0.005 30);
+  --neutral-400: oklch(0.71 0.005 30);
+  --neutral-500: oklch(0.56 0.005 30);
+  --neutral-600: oklch(0.45 0.005 30);
+  --neutral-700: oklch(0.36 0.005 30);
+  --neutral-800: oklch(0.27 0.005 30);
+  --neutral-900: oklch(0.2 0.005 30);
+  --neutral-950: oklch(0.13 0.005 30);
+
+  /* --- 2. App Accent 9档（单 hue 派生）— L=0.55 base 保证 vs neutral-50 ≥4.5:1 (WCAG normal text) --- */
+  --accent-50: oklch(0.97 calc(var(--accent-chroma) * 0.2) var(--accent-hue));
+  --accent-100: oklch(0.94 calc(var(--accent-chroma) * 0.3) var(--accent-hue));
+  --accent-200: oklch(0.88 calc(var(--accent-chroma) * 0.5) var(--accent-hue));
+  --accent-300: oklch(0.78 calc(var(--accent-chroma) * 0.7) var(--accent-hue));
+  --accent-400: oklch(0.65 calc(var(--accent-chroma) * 0.9) var(--accent-hue));
+  --accent-500: oklch(0.55 var(--accent-chroma) var(--accent-hue)); /* base — 按钮文字 ≥4.5:1 */
+  --accent-600: oklch(0.45 var(--accent-chroma) var(--accent-hue)); /* hover */
+  --accent-700: oklch(0.35 calc(var(--accent-chroma) * 0.9) var(--accent-hue)); /* active */
+  --accent-900: oklch(0.2 calc(var(--accent-chroma) * 0.5) var(--accent-hue));
+
+  /* --- 4. Semantic 5色（固定，不派生）— L 选定保证 vs cafe-surface 对比度 ≥3:1（WCAG icon） --- */
+  --semantic-critical: oklch(0.55 0.12 35); /* unread + error + delete + critical 合并 */
+  --semantic-success: oklch(0.55 0.12 135);
+  --semantic-warning: oklch(0.55 0.12 45); /* 暖橙：对比度 ≥3:1 (icon) */
+  --semantic-info: oklch(0.55 0.12 210); /* 跨线程气泡蓝亦用 */
+  --semantic-spotlight: oklch(0.65 0.12 45); /* F155 guide + quest input glow 合并 */
+  --semantic-critical-surface: oklch(0.96 0.03 35);
+  --semantic-success-surface: oklch(0.96 0.03 135);
+  --semantic-warning-surface: oklch(0.96 0.04 45);
+  --semantic-info-surface: oklch(0.96 0.03 210);
+  --semantic-spotlight-surface: oklch(0.96 0.04 45);
+
+  /* --- 5. Code Block（github-light 风格固定 palette） --- */
+  --code-bg: oklch(0.9 0.005 30);
+  --code-text: oklch(0.19 0.02 30);
+  --code-keyword: oklch(0.5 0.18 320);
+  --code-string: oklch(0.5 0.15 140);
+  --code-comment: oklch(0.55 0.05 100);
+  --code-function: oklch(0.5 0.18 250);
+  --code-number: oklch(0.5 0.18 30);
+  --code-border: oklch(0.9 0.005 30);
+
+  /* --- 6. Chart palette 12色（OKLCH H 均匀分布 30°/60°） --- */
+  --chart-1: oklch(0.55 0.15 30);
+  --chart-2: oklch(0.55 0.15 90);
+  --chart-3: oklch(0.55 0.15 150);
+  --chart-4: oklch(0.55 0.15 210);
+  --chart-5: oklch(0.55 0.15 270);
+  --chart-6: oklch(0.55 0.15 330);
+  --chart-7: oklch(0.45 0.18 30);
+  --chart-8: oklch(0.45 0.18 90);
+  --chart-9: oklch(0.45 0.18 150);
+  --chart-10: oklch(0.45 0.18 210);
+  --chart-11: oklch(0.45 0.18 270);
+  --chart-12: oklch(0.45 0.18 330);
+
+  /* --- 7. Avatar Fallback 8色（hash-based 固定） --- */
+  --avatar-fallback-1: oklch(0.65 0.12 30);
+  --avatar-fallback-2: oklch(0.65 0.12 75);
+  --avatar-fallback-3: oklch(0.65 0.12 120);
+  --avatar-fallback-4: oklch(0.65 0.12 165);
+  --avatar-fallback-5: oklch(0.65 0.12 210);
+  --avatar-fallback-6: oklch(0.65 0.12 255);
+  --avatar-fallback-7: oklch(0.65 0.12 300);
+  --avatar-fallback-8: oklch(0.65 0.12 345);
+
+  /* --- Surface 四档（light: 基于 develop_base 实测 hex 反推 OKLCH） ---
+   * 四档共享 --surface-hue，chroma = --surface-chroma × 层级系数：
+   *   sunken   L=0.92  ×1.5  ActivityBar / code / field
+   *   surface  L=0.95  ×1.2  ThreadSidebar / RightPanel
+   *   elevated L=0.99  ×0.5  Chat 主区（高 L 需低 C 趋白）
+   *   canvas   L=0.995 ×0.3  Card 浮起（最浅最白） */
+  --cafe-surface-sunken: oklch(0.92 calc(var(--surface-chroma) * 1.5) var(--surface-hue));
+  --cafe-surface: oklch(0.95 calc(var(--surface-chroma) * 1.2) var(--surface-hue));
+  --cafe-surface-elevated: oklch(0.99 calc(var(--surface-chroma) * 0.5) var(--surface-hue));
+  --cafe-surface-canvas: oklch(0.995 calc(var(--surface-chroma) * 0.3) var(--surface-hue));
+
+  /* --- Cafe semantic shortcuts（映射到 Neutral / App Accent / Semantic） --- */
+  --cafe-text: var(--neutral-900);
+  --cafe-text-secondary: var(--neutral-600);
+  --cafe-text-muted: var(--neutral-500);
+  --cafe-border: var(--neutral-300);
+  --cafe-border-subtle: var(--neutral-200);
+  --cafe-accent: var(--accent-500);
+  --cafe-accent-hover: var(--accent-600);
+  --cafe-accent-foreground: var(--neutral-50);
+  --cafe-crosspost: var(--semantic-info);
+  --cafe-interactive: var(--neutral-700);
+
+  /* --- Elevation 阴影（light: 单层黑阴影） --- */
+  --shadow-elevation-1: 0 1px 2px oklch(0 0 0 / 0.06);
+  --shadow-elevation-2: 0 4px 10px oklch(0 0 0 / 0.1);
+  --shadow-elevation-3: 0 14px 28px oklch(0 0 0 / 0.15);
+
+  /* --- Scrim 三档（modal / drawer / lightbox 后的 dim layer） --- */
+  --scrim-light: oklch(0 0 0 / 0.2);
+  --scrim-dim: oklch(0 0 0 / 0.4);
+  --scrim-heavy: oklch(0 0 0 / 0.65);
+
+  /* --- Overlay content text（always-light on dark scrim — lightbox / modal / tooltip） --- */
+  --overlay-fg: oklch(0.98 0 0);
+  --overlay-fg-muted: oklch(0.98 0 0 / 0.8);
+
+  /* --- 兼容旧通用 alias --- */
+  --color-cafe-accent: var(--cafe-accent);
+  --color-base-white: var(--cafe-surface);
+  --color-base-black: var(--cafe-text);
+  --bg-app: var(--cafe-surface);
+  --text-primary: var(--cafe-text);
+  --text-secondary: var(--cafe-text-secondary);
+}
+
+/* ============================================================
+ * DARK MODE
+ * ============================================================ */
+[data-theme="dark"] {
+  /* Dark accent/surface hue/chroma — aligned with INIT_DARK */
+  --accent-hue: 35;
+  --accent-chroma: 0.08;
+  --surface-hue: 30;
+
+  /* --- 1. Neutral 11档（dark: L 反转） --- */
+  --neutral-50: oklch(0.13 0.005 30);
+  --neutral-100: oklch(0.18 0.005 30);
+  --neutral-200: oklch(0.24 0.005 30);
+  --neutral-300: oklch(0.35 0.005 30);
+  --neutral-400: oklch(0.4 0.005 30);
+  --neutral-500: oklch(0.66 0.005 30);
+  --neutral-600: oklch(0.75 0.005 30);
+  --neutral-700: oklch(0.84 0.005 30);
+  --neutral-800: oklch(0.88 0.005 30);
+  --neutral-900: oklch(0.95 0.005 30);
+  --neutral-950: oklch(0.98 0.005 30);
+
+  /* --- 2. App Accent 9档（dark: 略亮 + 降饱和） --- */
+  --accent-50: oklch(0.22 calc(var(--accent-chroma) * 0.3) var(--accent-hue));
+  --accent-100: oklch(0.28 calc(var(--accent-chroma) * 0.4) var(--accent-hue));
+  --accent-200: oklch(0.34 calc(var(--accent-chroma) * 0.5) var(--accent-hue));
+  --accent-300: oklch(0.44 calc(var(--accent-chroma) * 0.7) var(--accent-hue));
+  --accent-400: oklch(0.55 calc(var(--accent-chroma) * 0.8) var(--accent-hue));
+  --accent-500: oklch(0.68 calc(var(--accent-chroma) * 0.9) var(--accent-hue));
+  --accent-600: oklch(0.78 var(--accent-chroma) var(--accent-hue));
+  --accent-700: oklch(0.85 calc(var(--accent-chroma) * 0.9) var(--accent-hue));
+  --accent-900: oklch(0.95 calc(var(--accent-chroma) * 0.4) var(--accent-hue));
+
+  /* --- 4. Semantic 5色（dark: 略亮 + 微调） --- */
+  --semantic-critical: oklch(0.7 0.17 25);
+  --semantic-success: oklch(0.7 0.17 145);
+  --semantic-warning: oklch(0.7 0.17 70);
+  --semantic-info: oklch(0.7 0.17 230);
+  --semantic-spotlight: oklch(0.8 0.17 70);
+  --semantic-critical-surface: oklch(0.25 0.05 25);
+  --semantic-success-surface: oklch(0.25 0.05 145);
+  --semantic-warning-surface: oklch(0.25 0.05 70);
+  --semantic-info-surface: oklch(0.25 0.05 230);
+  --semantic-spotlight-surface: oklch(0.25 0.06 70);
+
+  /* --- 5. Code Block（vscode-dark+ 风格固定 palette） --- */
+  --code-bg: oklch(0.25 0.005 30);
+  --code-text: oklch(0.9 0.02 30);
+  --code-keyword: oklch(0.72 0.16 280);
+  --code-string: oklch(0.72 0.14 140);
+  --code-comment: oklch(0.5 0.04 100);
+  --code-function: oklch(0.78 0.14 210);
+  --code-number: oklch(0.72 0.16 30);
+  --code-border: oklch(0.35 0.005 30);
+
+  /* --- 6. Chart palette（dark: L 略提到 0.68/0.78） --- */
+  --chart-1: oklch(0.68 0.14 30);
+  --chart-2: oklch(0.68 0.14 90);
+  --chart-3: oklch(0.68 0.14 150);
+  --chart-4: oklch(0.68 0.14 210);
+  --chart-5: oklch(0.68 0.14 270);
+  --chart-6: oklch(0.68 0.14 330);
+  --chart-7: oklch(0.78 0.12 30);
+  --chart-8: oklch(0.78 0.12 90);
+  --chart-9: oklch(0.78 0.12 150);
+  --chart-10: oklch(0.78 0.12 210);
+  --chart-11: oklch(0.78 0.12 270);
+  --chart-12: oklch(0.78 0.12 330);
+
+  /* --- 7. Avatar Fallback（dark: L 略降） --- */
+  --avatar-fallback-1: oklch(0.55 0.13 30);
+  --avatar-fallback-2: oklch(0.55 0.13 75);
+  --avatar-fallback-3: oklch(0.55 0.13 120);
+  --avatar-fallback-4: oklch(0.55 0.13 165);
+  --avatar-fallback-5: oklch(0.55 0.13 210);
+  --avatar-fallback-6: oklch(0.55 0.13 255);
+  --avatar-fallback-7: oklch(0.55 0.13 300);
+  --avatar-fallback-8: oklch(0.55 0.13 345);
+
+  /* --- Surface 四档（dark — 铲屎官 2026-06-10 调优）---
+   * sunken=0.36 / surface=0.28 / elevated=0.21 / canvas=0.24
+   * Chroma = base chroma × 0.15 (0.0022/0.0018/0.0008/0.0004).
+   * 空间映射见 console-tokens.css（light/dark 统一，不再镜像） */
+  --cafe-surface-sunken: oklch(0.36 0.0022 var(--surface-hue));
+  --cafe-surface: oklch(0.28 0.0018 var(--surface-hue));
+  --cafe-surface-elevated: oklch(0.21 0.0008 var(--surface-hue));
+  --cafe-surface-canvas: oklch(0.24 0.0004 var(--surface-hue));
+
+  /* --- Cafe semantic shortcuts dark（重新映射 Neutral） --- */
+  --cafe-text: var(--neutral-900);
+  --cafe-text-secondary: var(--neutral-600);
+  --cafe-text-muted: var(--neutral-500);
+  --cafe-border: var(--neutral-300);
+  --cafe-border-subtle: var(--neutral-400);
+  --cafe-accent: var(--accent-500);
+  --cafe-accent-hover: var(--accent-600);
+  --cafe-accent-foreground: var(--neutral-50);
+  --cafe-crosspost: var(--semantic-info);
+  --cafe-interactive: var(--neutral-700);
+
+  /* --- Elevation 阴影（dark: inset 高光 + 深外阴影） --- */
+  --shadow-elevation-1: 0 1px 2px oklch(0 0 0 / 0.5), inset 0 1px 0 oklch(1 0 0 / 0.1);
+  --shadow-elevation-2: 0 6px 14px oklch(0 0 0 / 0.55), inset 0 1px 0 oklch(1 0 0 / 0.14);
+  --shadow-elevation-3: 0 16px 32px oklch(0 0 0 / 0.65), inset 0 1px 0 oklch(1 0 0 / 0.18);
+
+  /* --- Scrim（dark: 加深） --- */
+  --scrim-light: oklch(0 0 0 / 0.4);
+  --scrim-dim: oklch(0 0 0 / 0.6);
+  --scrim-heavy: oklch(0 0 0 / 0.8);
+
+  /* --- 兼容旧 alias --- */
+  --color-base-white: var(--cafe-surface);
+  --color-base-black: var(--cafe-text);
+  --bg-app: var(--cafe-surface);
+  --text-primary: var(--cafe-text);
+  --text-secondary: var(--cafe-text-secondary);
+}

package/renderer/transcript-view.mjs

@@ -0,0 +1,40 @@
+export class TranscriptView {
+  constructor(container) {
+    this.container = container;
+    this.activeRows = new Map();
+    this.completed = new Set();
+  }
+  append(role, text, chunk = false) {
+    const pinned = this.nearBottom();
+    this.container.querySelector('.empty')?.remove();
+    let row = chunk ? this.activeRows.get(role) : undefined;
+    if (!row) {
+      row = this.container.ownerDocument.createElement('p');
+      row.className = role;
+      this.container.append(row);
+      if (chunk) this.activeRows.set(role, row);
+    }
+    row.textContent += text;
+    if (pinned) this.container.scrollTop = this.container.scrollHeight;
+  }
+  finish({ role, transcript, turnId }) {
+    if (!['user', 'assistant'].includes(role) || (turnId && this.completed.has(turnId))) return;
+    const pinned = this.nearBottom();
+    let row = this.activeRows.get(role);
+    if (!row && transcript) {
+      this.append(role, '', true);
+      row = this.activeRows.get(role);
+    }
+    if (row && typeof transcript === 'string') row.textContent = transcript;
+    this.activeRows.delete(role);
+    if (turnId) this.completed.add(turnId);
+    if (pinned) this.container.scrollTop = this.container.scrollHeight;
+  }
+  nearBottom() {
+    return this.container.scrollHeight - this.container.scrollTop - this.container.clientHeight < 32;
+  }
+  reset() {
+    this.activeRows.clear();
+    this.completed.clear();
+  }
+}

package/source-lock.json

@@ -0,0 +1,31 @@
+{
+  "repository": "https://github.com/zts212653/clowder-ai",
+  "commit": "bc9ff2d395a8522a4e5cc93fd317b65cdd9ea1bc",
+  "files": [
+    {
+      "source": "packages/web/src/app/theme-tokens.css",
+      "destination": "src/theme.css",
+      "sha256": "165b96ef77a04755bb84bc2278f5d52587fa40e893575e53ef5f85f2ec89e5cf"
+    },
+    {
+      "source": "packages/web/public/concierge/skins/yanyan-codex/spritesheet.webp",
+      "destination": "assets/skins/yanyan-codex.webp",
+      "sha256": "44aee212783ab15ec73f7ce44f67c894e9ab7a7f36674b71a1161d62dafc1d72"
+    },
+    {
+      "source": "packages/web/public/concierge/skins/xianxian-codex/spritesheet.webp",
+      "destination": "assets/skins/xianxian-codex.webp",
+      "sha256": "5f653974735a4104dfdaf1845128494a5cb5164cb2f45fecb2072a167c80e8a5"
+    },
+    {
+      "source": "packages/web/public/concierge/skins/ragdoll-v1/idle.png",
+      "destination": "assets/skins/ragdoll-v1.png",
+      "sha256": "001c7f3660b348e2531694d9dc455378a0c007c765e0936a48e61eedf9c30025"
+    },
+    {
+      "source": "packages/web/public/concierge/sprites/ragdoll/idle.png",
+      "destination": "assets/skins/yarn-ball.png",
+      "sha256": "001c7f3660b348e2531694d9dc455378a0c007c765e0936a48e61eedf9c30025"
+    }
+  ]
+}