@kingsoftcloud/agentkit-personal-assistant 0.0.0-stage → 0.1.7

package/src/client/index.mjs

@@ -0,0 +1,733 @@
+/** Browser-safe Personal Assistant client and Cloud Computer panel. */
+
+export class PersonalAssistantGatewayUnavailableError extends Error {
+  constructor() {
+    super('Personal Assistant gateway is not connected');
+    this.name = 'PersonalAssistantGatewayUnavailableError';
+    this.code = 'PERSONAL_ASSISTANT_GATEWAY_UNAVAILABLE';
+  }
+}
+
+function gatewayRequest(gateway, operation, payload) {
+  if (!gateway || typeof gateway.request !== 'function') throw new PersonalAssistantGatewayUnavailableError();
+  return gateway.request(operation, payload);
+}
+
+export function createPersonalAssistantClient({ gateway, profileId = 'default' } = {}) {
+  let selectedBotId = null;
+  const request = (operation, payload = {}) => gatewayRequest(gateway, operation, { ...payload, profileId });
+  const desktop = {
+    open: input => request('personal-assistant.desktop.session.open', { ...input, botId: input?.botId ?? selectedBotId }),
+    ticket: input => request('personal-assistant.desktop.ticket', { ...input, botId: input?.botId ?? selectedBotId }),
+    frame: input => request('personal-assistant.desktop.frame', input),
+    input: input => request('personal-assistant.desktop.input', input),
+    close: input => request('personal-assistant.desktop.session.close', input),
+  };
+  return Object.freeze({
+    configuration: () => request('personal-assistant.configuration'),
+    listBots: () => request('personal-assistant.bots.list'),
+    getBot: botId => request('personal-assistant.bots.get', { botId }),
+    selectBot(botId) {
+      selectedBotId = String(botId ?? '').trim();
+      if (!selectedBotId) throw new TypeError('botId must be a non-empty string');
+      return selectedBotId;
+    },
+    selectedBot: () => selectedBotId,
+    session: input => request('personal-assistant.session.create', { ...input, botId: input?.botId ?? selectedBotId }),
+    listSessions: botId => request('personal-assistant.sessions.list', { botId: botId ?? selectedBotId }),
+    createSession: input => request('personal-assistant.sessions.create', { ...input, botId: input?.botId ?? selectedBotId }),
+    listMessages: sessionId => request('personal-assistant.sessions.messages.list', { sessionId, botId: selectedBotId }),
+    appendMessage: (sessionId, input) => request('personal-assistant.sessions.messages.append', { sessionId, ...input, botId: input?.botId ?? selectedBotId }),
+    listTurns: sessionId => request('personal-assistant.sessions.turns.list', { sessionId, botId: selectedBotId }),
+    submitTurn: (sessionId, input) => request('personal-assistant.sessions.turns.submit', { sessionId, ...input, botId: input?.botId ?? selectedBotId }),
+    searchMemory: query => request('personal-assistant.memory.search', { query, botId: selectedBotId }),
+    remember: input => request('personal-assistant.memory.upsert', { ...input, botId: input?.botId ?? selectedBotId }),
+    listSchedules: botId => request('personal-assistant.schedules.list', { botId: botId ?? selectedBotId }),
+    createSchedule: input => request('personal-assistant.schedules.create', { ...input, botId: input?.botId ?? selectedBotId }),
+    deleteSchedule: scheduleId => request('personal-assistant.schedules.delete', { scheduleId, botId: selectedBotId }),
+    computerStatus: computerId => request('personal-assistant.computer.status', { computerId, botId: selectedBotId }),
+    computerAction: input => request('personal-assistant.computer.action', { ...input, botId: input?.botId ?? selectedBotId }),
+    browserOpen: url => request('personal-assistant.computer.action', { action: 'open', args: { url }, botId: selectedBotId }),
+    browserSnapshot: () => request('personal-assistant.computer.action', { action: 'snapshot', args: {}, botId: selectedBotId }),
+    browserClick: selector => request('personal-assistant.computer.action', { action: 'click', args: { selector }, botId: selectedBotId }),
+    browserType: (text, selector) => request('personal-assistant.computer.action', { action: 'type', args: { text, ...(selector === undefined ? {} : { selector }) }, botId: selectedBotId }),
+    browserPress: key => request('personal-assistant.computer.action', { action: 'press', args: { key }, botId: selectedBotId }),
+    browserScreenshot: () => request('personal-assistant.computer.action', { action: 'screenshot', args: {}, botId: selectedBotId }),
+    browserDownload: args => request('personal-assistant.computer.action', { action: 'download', args: args || {}, botId: selectedBotId }),
+    browserClose: () => request('personal-assistant.computer.action', { action: 'stop', args: {}, botId: selectedBotId }),
+    cloudBash: (command, timeoutMs) => request('personal-assistant.computer.action', { action: 'terminal.exec', args: { language: 'shell', command, ...(timeoutMs === undefined ? {} : { timeoutMs }) }, botId: selectedBotId }),
+    cloudRunCode: (language, code, timeoutMs) => request('personal-assistant.computer.action', { action: 'terminal.exec', args: { language, code, ...(timeoutMs === undefined ? {} : { timeoutMs }) }, botId: selectedBotId }),
+    clipboardRead: () => request('personal-assistant.computer.action', { action: 'clipboard.read', args: {}, botId: selectedBotId }),
+    clipboardWrite: text => request('personal-assistant.computer.action', { action: 'clipboard.write', args: { text }, botId: selectedBotId }),
+    desktop,
+  });
+}
+
+export const inject = Object.freeze(['slots', 'connection', 'sidebarRight']);
+export const PERSONAL_ASSISTANT_PANEL_ID = 'personal-assistant';
+export const PERSONAL_ASSISTANT_CLIENT_DEFAULTS = Object.freeze({ enabled: false, autoConnect: false });
+export const PERSONAL_ASSISTANT_COMPUTER_TAB = 'personal-assistant-computer';
+import { mapDisplayPoint, normalizeDisplay } from './desktop-view.mjs';
+import { createDesktopControl } from './desktop-control.mjs';
+import { createClipboardChannel, isPasteShortcut, isCopyShortcut, copyCloudClipboard, pasteToCloud, readLocalClipboard } from './components/desktop-clipboard.mjs';
+import { PersonalAssistantConversation } from './conversation.mjs';
+import { createAssistantWorkbench, AssistantNativeRightbar } from './native-workbench.mjs';
+import { publicBotDirectory, resolveAssistantBotId } from './bot-directory.mjs';
+export const PERSONAL_ASSISTANT_CLIENT_BUILD = typeof __PA_CLIENT_BUILD__ === 'string' ? __PA_CLIENT_BUILD__ : '开发模式';
+const FIRST_FRAME_TIMEOUT_MS = 12_000;
+let clientReact;
+export function setClientReactRuntime(runtime) { clientReact = runtime; }
+const ui = {
+  background: 'var(--dsw-alias-bg-layer-1, #fff)', color: 'var(--dsw-alias-label-primary, #17202c)',
+  border: '1px solid var(--dsw-alias-border-default, #d8dee8)',
+};
+const bindingFailure = error => typeof error?.message === 'string' && error.message && !/^(fetch failed|Failed to fetch)$/u.test(error.message) ? error.message.slice(0, 180) : '云电脑连接失败，请稍后重试';
+const failure = error => error?.code === 'PERSONAL_ASSISTANT_DIRECTORY_UNAVAILABLE' && Number(error?.status) === 409 ? '当前云端版本尚不支持助理列表，请更新云端助理后重试' : '连接暂时不可用，请稍后重试';
+const directoryUnsupported = error => Number(error?.status) === 409 && ['PERSONAL_ASSISTANT_DIRECTORY_UNSUPPORTED', 'PERSONAL_ASSISTANT_DIRECTORY_UNAVAILABLE'].includes(error?.code);
+const keyNames = { Control: 'Control_L', Meta: 'Super_L', Alt: 'Alt_L', Shift: 'Shift_L', Enter: 'Return', Escape: 'Escape', Tab: 'Tab', Backspace: 'BackSpace', Delete: 'Delete', ArrowUp: 'Up', ArrowDown: 'Down', ArrowLeft: 'Left', ArrowRight: 'Right', ' ': 'space' };
+
+export function PersonalAssistantPanel({ request, initialBotId = '', openInSidebar = null, variant = 'page', nativeFullscreen = false } = {}) {
+  const R = clientReact || globalThis.React;
+  if (!R) return '个人助理页面尚未就绪，请重新打开';
+  const { createElement: h, useEffect, useRef, useState } = R;
+  const [config, setConfig] = useState(null);
+  const [bots, setBots] = useState([]);
+  const [directoryError, setDirectoryError] = useState('');
+  const [directoryCloseCode, setDirectoryCloseCode] = useState(null);
+  const [diagnosticsOpen, setDiagnosticsOpen] = useState(false);
+  const [botId, setBotId] = useState(initialBotId);
+  const [phase, setPhase] = useState('loading');
+  const [notice, setNotice] = useState('');
+  const [readOnly, setReadOnly] = useState(true);
+  const [attempt, setAttempt] = useState(0);
+  const [fps, setFps] = useState(0);
+  const [controlPhase, setControlPhase] = useState('observe');
+  const [binding, setBinding] = useState(null);
+  const [busy, setBusy] = useState('');
+  const [clipboardNotice, setClipboardNotice] = useState('');
+  const controlRef = useRef(null);
+  const clipboardRef = useRef(null), clipboardTimerRef = useRef(null);
+  const canvasRef = useRef(null), inputRef = useRef(null), viewRef = useRef(null), cursorRef = useRef(null);
+  const fullscreenRef = useRef(nativeFullscreen); fullscreenRef.current = nativeFullscreen;
+  const state = useRef({ mounted: true, socket: null, generation: 0, frameEpoch: 0, session: null, suspended: false, resuming: false, pendingInputs: [], display: { width: 1280, height: 800 }, readOnly: true, botId, config: null, reconnect: null, firstFrame: null, receivedSeq: -1, pendingFrame: null, decoding: false, frames: 0, lastMove: 0, pressed: new Set(), buttons: new Set(), composition: false, retries: 0, taskId: '', mode: 'control', frameMetadata: null, reconnectAllowed: false });
+  state.current.botId = botId;
+  const rpc = async (operation, payload = {}) => {
+    if (typeof request !== 'function') throw new Error('Studio Host 尚未连接');
+    return request(operation, payload);
+  };
+  const send = body => {
+    const current = state.current;
+    if (current.socket?.readyState !== 1) return false;
+    current.socket.send(JSON.stringify(body)); return true;
+  };
+  const releaseInputs = () => {
+    const current = state.current;
+    for (const key of current.pressed) controlRef.current?.input({ type: 'key', action: 'up', key });
+    for (const button of current.buttons) controlRef.current?.input({ type: 'button', action: 'up', button });
+    current.pressed.clear(); current.buttons.clear();
+  };
+  const releasePointer = () => {
+    for (const button of state.current.buttons) controlRef.current?.input({ type: 'button', action: 'up', button });
+    state.current.buttons.clear();
+  };
+  if (!controlRef.current) controlRef.current = createDesktopControl({
+    send,
+    changed: value => {
+      const current = state.current; current.controlPhase = value.phase; current.readOnly = value.readOnly; current.controlEpoch = value.controlEpoch;
+      if (value.readOnly && cursorRef.current) cursorRef.current.style.visibility = 'hidden';
+      if (value.phase === 'observe') { current.pressed.clear(); current.buttons.clear(); }
+      if (current.mounted) { setReadOnly(value.readOnly); setControlPhase(value.phase); }
+    },
+    failed: message => { if (state.current.mounted) setNotice(message); },
+  });
+  // 剪贴板请求复用同一条桌面 WS（云端 desktop-ws 的 clipboard.read / clipboard.write），
+  // 用 requestId 关联回复；旧版云端不认这两个消息类型，超时后给明确提示而不是转圈。
+  if (!clipboardRef.current) clipboardRef.current = createClipboardChannel({ send, controlEpoch: () => controlRef.current?.snapshot?.controlEpoch });
+  const releaseControl = () => { releaseInputs(); controlRef.current.release(); state.current.pressed.clear(); state.current.buttons.clear(); };
+  const flushPointer = () => {
+    const current = state.current;
+    if (current.pointerFrame) cancelAnimationFrame(current.pointerFrame);
+    current.pointerFrame = null;
+    const next = current.lastPointer; current.lastPointer = null;
+    if (next && (!current.readOnly || current.controlPhase === 'acquiring') && (!current.sentPointer || next.x !== current.sentPointer.x || next.y !== current.sentPointer.y)) {
+      controlRef.current.input({ type: 'pointermove', ...next }); current.sentPointer = next;
+    }
+  };
+  const clearTimers = () => {
+    clearTimeout(state.current.reconnect); clearTimeout(state.current.firstFrame);
+    state.current.reconnect = null; state.current.firstFrame = null;
+  };
+  const close = (announce = true) => {
+    const current = state.current; current.reconnectAllowed = false; clearTimers(); releaseControl(); current.generation += 1;
+    clipboardRef.current?.rejectAll();
+    try { send({ type: 'close' }); current.socket?.close(1000, 'panel closed'); } catch {}
+    controlRef.current.reset({ readOnly: true }); current.lastDrawnFrame = null; current.socket = null; current.session = null; current.pendingFrame = null; current.frameMetadata = null; current.readOnly = true; inputRef.current?.blur();
+    current.suspended = false; current.resuming = false; current.pendingInputs = []; current.frameEpoch++;
+    if (announce && current.mounted) { setPhase(current.config?.configured ? 'idle' : 'unconfigured'); setReadOnly(true); }
+  };
+  const ended = value => {
+    close(false); setReadOnly(true); setPhase('closed');
+    setNotice(value?.reason === 'lease-lost' || Number(value?.status) === 409
+      ? '控制租约已失效，桌面连接已关闭；请重新连接或选择只读旁观'
+      : value?.code === 'DESKTOP_SESSION_NOT_FOUND' || Number(value?.status) === 404
+        ? '桌面会话已结束（可能因空闲超时），请重新连接'
+        : '桌面连接已结束，可重新连接云电脑');
+  };
+  const input = event => {
+    const current = state.current;
+    if (event.type !== 'pointermove') flushPointer();
+    if (current.suspended || current.resuming) {
+      if (event.type === 'pointermove') return false;
+      const controlling = current.mode === 'control';
+      if (controlling) {
+        if (current.pendingInputs.length >= 32) { close(); setNotice('恢复期间输入过快，请重新连接'); return false; }
+        current.pendingInputs.push(event);
+      }
+      if (!current.resuming) resumeIdle();
+      return controlling;
+    }
+    if (!current.session || current.socket?.readyState !== 1) { setNotice('云电脑尚未连接，输入未发送'); return false; }
+    return controlRef.current.input(event);
+  };
+  const clipboardNotify = message => {
+    if (!state.current.mounted) return;
+    setClipboardNotice(message);
+    if (clipboardTimerRef.current) clearTimeout(clipboardTimerRef.current);
+    clipboardTimerRef.current = setTimeout(() => { if (state.current.mounted) setClipboardNotice(''); }, 4000);
+  };
+  // 合成按键走现有桌面输入通道：只读旁观时 input() 会拒发并返回 false，由粘贴流程提示先接管。
+  const sendDesktopKeys = events => {
+    let sent = false;
+    for (const event of events) sent = input(event) || sent;
+    return sent;
+  };
+  // ⌘C：先把按键原样交给云电脑，让云端应用自己完成“复制”，再取回云端剪贴板。
+  // 之前只读剪贴板不转发按键，用户按 ⌘C 等于没复制，还会在输入框里反复触发按键。
+  const copyCloudClipboardToLocal = async () => {
+    const modifier = /Mac|iPhone|iPad/u.test(String(globalThis.navigator?.platform || '')) ? 'Meta' : 'Control';
+    if (!state.current.pressed.has('_copyShortcut')) {
+      state.current.pressed.add('_copyShortcut');
+      try {
+        sendDesktopKeys([
+          { type: 'key', action: 'down', key: modifier },
+          { type: 'key', action: 'down', key: 'c' },
+          { type: 'key', action: 'up', key: 'c' },
+          { type: 'key', action: 'up', key: modifier },
+        ]);
+        await new Promise(resolve => setTimeout(resolve, 150));
+      } finally { state.current.pressed.delete('_copyShortcut'); }
+    }
+    return copyCloudClipboard({ readCloud: () => clipboardRef.current.read(), notify: clipboardNotify });
+  };
+  const pasteLocalClipboardToCloud = () => pasteToCloud({
+    readLocal: () => readLocalClipboard(),
+    writeCloud: text => clipboardRef.current.write(text),
+    sendKeys: sendDesktopKeys,
+    notify: clipboardNotify,
+  });
+  const drawLatest = async () => {
+    const current = state.current;
+    if (current.decoding) return;
+    current.decoding = true;
+    try {
+      while (current.pendingFrame) {
+        const job = current.pendingFrame; current.pendingFrame = null;
+        let bitmap;
+        try {
+          bitmap = await createImageBitmap(new Blob([job.bytes], { type: 'image/jpeg' }));
+          if (!current.mounted || current.suspended || job.frameEpoch !== current.frameEpoch || job.generation !== current.generation || job.seq < current.receivedSeq || !canvasRef.current) continue;
+          current.lastDrawnFrame = job;
+          const canvas = canvasRef.current, rect = canvas.getBoundingClientRect();
+          const dpr = Math.max(1, globalThis.devicePixelRatio || 1);
+          canvas.width = Math.max(1, Math.round(rect.width * dpr)); canvas.height = Math.max(1, Math.round(rect.height * dpr));
+          const context = canvas.getContext('2d'), display = current.display;
+          const scale = Math.min(canvas.width / display.width, canvas.height / display.height);
+          const width = display.width * scale, height = display.height * scale;
+          context.clearRect(0, 0, canvas.width, canvas.height);
+          context.drawImage(bitmap, (canvas.width - width) / 2, (canvas.height - height) / 2, width, height);
+          const waitingForFirstFrame = current.firstFrame !== null;
+          current.frames += 1; clearTimeout(current.firstFrame); current.firstFrame = null; current.retries = 0;
+          if (waitingForFirstFrame) setNotice('');
+          setPhase(current.readOnly ? 'readonly' : 'ready'); setAttempt(0);
+        } catch { if (current.mounted) setNotice('桌面帧无法解码，请重试'); }
+        finally { bitmap?.close(); }
+      }
+    } finally { current.decoding = false; }
+  };
+  const markIdle = value => {
+    const current = state.current;
+    clearTimeout(current.firstFrame); current.firstFrame = null;
+    current.suspended = true; current.resuming = false; current.readOnly = true; current.pendingInputs = []; current.frameEpoch++;
+    current.pendingFrame = null; current.frameMetadata = null; current.pressed.clear(); current.buttons.clear(); current.frames = 0;
+    setFps(0); setReadOnly(true); setPhase('dormant'); setNotice(value?.leaseReleased === false ? '已空闲，画面已暂停；控制权仍由外部任务管理' : '已空闲，控制权已释放；操作桌面即可恢复');
+  };
+  const resumeIdle = () => {
+    const current = state.current;
+    if (current.resuming || !current.suspended) return;
+    if (current.socket?.readyState !== 1) { void open(current.mode, false, current.pendingInputs); return; }
+    current.resuming = true; setPhase('resuming'); setNotice('正在恢复桌面并检查控制权，请稍候。');
+    send({ type: 'resume', mode: current.mode, activity: true });
+    const generation = current.generation, socket = current.socket;
+    current.firstFrame = setTimeout(() => { if (current.mounted && current.generation === generation && current.firstFrame !== null) socket.close(4000, 'resume frame timeout'); }, FIRST_FRAME_TIMEOUT_MS);
+  };
+  const open = async (mode = 'read', reconnecting = false, bufferedInputs = []) => {
+    const current = state.current;
+    const selected = String(current.botId || '').trim();
+    if (!current.config?.configured) { setPhase('unconfigured'); return; }
+    if (!selected || !current.bots?.some(bot => bot.botId === selected)) { setNotice('云端助理尚未就绪，请稍后重试'); return; }
+    close(false);
+    current.pendingInputs = bufferedInputs; current.resuming = bufferedInputs.length > 0;
+    const generation = ++current.generation;
+    current.reconnectAllowed = true;
+    if (!reconnecting) current.retries = 0;
+    current.mode = mode; current.taskId ||= `studio-desktop-${globalThis.crypto.randomUUID()}`;
+    current.receivedSeq = -1; current.frameMetadata = null;
+    setPhase(reconnecting ? 'reconnecting' : 'connecting'); setNotice('首次或休眠后连接可能需要数秒，请稍候。');
+    try {
+      const ticket = await rpc('personal-assistant.desktop.ticket', { agentId: current.config.agentId, botId: selected, mode: mode === 'observe' ? 'control' : mode });
+      if (!current.mounted || generation !== current.generation) return;
+      const socket = new WebSocket(ticket.wsUrl, ['agentkit.personal-assistant.desktop.v1', `agentkit.desktop.ticket.${ticket.ticket}`]);
+      socket.binaryType = 'arraybuffer'; current.socket = socket;
+      const valid = () => current.mounted && current.generation === generation;
+      socket.onopen = () => {
+        if (!valid()) { socket.close(); return; }
+        send({ type: 'open', botId: selected, taskId: current.taskId, mode, ...(ticket.leaseId ? { leaseId: ticket.leaseId } : {}) });
+        current.firstFrame = setTimeout(() => { if (valid()) { setNotice('云电脑响应较慢，正在重新连接'); socket.close(4000, 'first frame timeout'); } }, FIRST_FRAME_TIMEOUT_MS);
+      };
+      socket.onmessage = event => {
+        if (!valid()) return;
+        if (typeof event.data !== 'string') {
+          const meta = current.frameMetadata; current.frameMetadata = null;
+          const bytes = event.data;
+          if (!meta || !Number.isSafeInteger(meta.seq) || meta.seq <= current.receivedSeq || !(bytes instanceof ArrayBuffer) || bytes.byteLength === 0 || bytes.byteLength > 307200) return;
+          if (current.suspended) return;
+          current.receivedSeq = meta.seq; current.pendingFrame = { bytes, seq: meta.seq, generation, frameEpoch: current.frameEpoch }; void drawLatest(); return;
+        }
+        let value; try { value = JSON.parse(event.data); } catch { return; }
+        if (value.type === 'ready') {
+          current.suspended = false; current.resuming = false; current.receivedSeq = -1;
+          current.session = value.sessionId; current.readOnly = Boolean(value.readOnly); current.display = normalizeDisplay(value.display);
+          current.mode = mode;
+          controlRef.current.reset(value);
+          const inputs = current.pendingInputs; current.pendingInputs = [];
+          if (!current.readOnly) for (const event of inputs) controlRef.current.input(event);
+          else { current.pressed.clear(); current.buttons.clear(); }
+          setReadOnly(current.readOnly); setNotice('云电脑已连接，正在准备桌面画面'); return;
+        }
+        if (value.type === 'control') { controlRef.current.accept(value); setNotice(''); return; }
+        if (value.type === 'idle') { markIdle(value); return; }
+        if (value.type === 'frame') { if (!value.unchanged) current.frameMetadata = value; return; }
+        if (value.type === 'clipboard.response') { clipboardRef.current?.accept(value); return; }
+        if (value.type === 'closed') { if (value.retryable !== true) ended(value); return; }
+        if (value.type === 'error') {
+          if (Number.isSafeInteger(value.controlEpoch) && value.controlEpoch < current.controlEpoch) return;
+          setNotice(value.message || value.code || '云电脑请求失败');
+          if (current.handoffSupported && value.recoverable === true) { controlRef.current.reject(value); return; }
+          if (value.recoverable === true && Number(value.status) === 409) {
+            if (value.code === 'DESKTOP_SESSION_IDLE') markIdle();
+            else { current.pendingInputs = []; current.readOnly = true; current.pressed.clear(); current.buttons.clear(); setReadOnly(true); setPhase('readonly'); }
+            return;
+          }
+          if (Number(value.status) === 409 && mode === 'control' && !current.session) { void open(state.current.handoffSupported ? 'observe' : 'read'); return; }
+          if ([404, 409].includes(Number(value.status)) || value.code === 'DESKTOP_SESSION_NOT_FOUND') ended(value);
+          else if (!current.session) { setPhase('error'); close(false); }
+        }
+      };
+      socket.onerror = () => { if (valid()) setNotice('桌面通道暂时断开，正在重连'); };
+      socket.onclose = event => {
+        if (!valid()) return;
+        if (current.suspended && event.code !== 1000) { clearTimeout(current.firstFrame); current.firstFrame = null; current.socket = null; setPhase('dormant'); return; }
+        current.session = null; clearTimeout(current.firstFrame); current.firstFrame = null;
+        if (!current.reconnectAllowed || event.code === 1000) { ended(); return; }
+        if (document.hidden) { setPhase('hidden'); return; }
+        const count = ++current.retries; setAttempt(count);
+        if (count > 5) { current.reconnectAllowed = false; setPhase('error'); setNotice('无法连接云电脑，请检查实例状态或网络后重试'); return; }
+        setPhase('reconnecting'); current.reconnect = setTimeout(() => { void open(mode, true, current.pendingInputs); }, Math.min(8000, 1000 * 2 ** (count - 1)));
+      };
+    } catch (error) { if (current.mounted && generation === current.generation) { setPhase('error'); setNotice(failure(error)); } }
+  };
+  // Studio 负责发现实例、恢复/生成凭证；页面只读取公开状态，绝不接触凭据。
+  const bindingSnapshot = async signal => {
+    if (signal?.aborted) return null;
+    try { const value = await rpc('personal-assistant.desktop.status'); return value && typeof value === 'object' ? value : null; }
+    catch (error) {
+      if (error?.code === 'PERSONAL_ASSISTANT_OPERATION_UNAVAILABLE' || error?.status === 404) return null;
+      return { configured: false, reason: 'unavailable', detail: bindingFailure(error), candidates: [] };
+    }
+  };
+  const bindAssistant = async action => {
+    if (busy) return;
+    setBusy(action);
+    setNotice(action === 'create' ? '正在创建个人助理，可能需要几分钟…' : '正在获取云端连接凭证…');
+    try { await rpc(`personal-assistant.desktop.${action}`); setNotice(''); await refreshConnection(); }
+    catch (error) { setNotice(bindingFailure(error)); setBinding(await bindingSnapshot().catch(() => null)); }
+    finally { setBusy(''); }
+  };
+  const refreshConnection = async (signal, retried = false) => {
+    close(false); setPhase('loading'); setNotice(''); setDirectoryError(''); setDirectoryCloseCode(null);
+    try {
+      const value = await rpc('personal-assistant.configuration');
+      if (signal?.aborted || !state.current.mounted) return;
+      state.current.config = value; setConfig(value);
+      if (!value.configured) {
+        const snapshot = await bindingSnapshot(signal);
+        if (signal?.aborted || !state.current.mounted) return;
+        state.current.bots = []; setBots([]); setBotId(''); setBinding(snapshot); setPhase('unconfigured');
+        if (snapshot?.configured && !retried) { await refreshConnection(signal, true); return; }
+        return;
+      }
+      setBinding(null);
+      const result = await rpc('personal-assistant.bots.list');
+      if (signal?.aborted || !state.current.mounted) return;
+      if (result.directoryAvailable !== true) throw Object.assign(new Error('directory unavailable'), { code: 'PERSONAL_ASSISTANT_DIRECTORY_UNAVAILABLE', status: 409 });
+      const available = publicBotDirectory(result.bots);
+      state.current.bots = available; state.current.handoffSupported = result.features?.includes('desktop-handoff/v1') === true; setBots(available);
+      const selected = available.length ? resolveAssistantBotId(available, initialBotId || value.botId) : '';
+      state.current.botId = selected; setBotId(selected); setPhase(available.length ? 'idle' : 'empty');
+      if (selected && ['computer', 'native-tab'].includes(variant)) void open(state.current.handoffSupported ? 'observe' : 'read');
+    } catch (error) {
+      if (signal?.aborted || !state.current.mounted) return;
+      if (Number.isInteger(error?.closeCode) && error.closeCode >= 1000 && error.closeCode <= 4999) setDirectoryCloseCode(error.closeCode);
+      state.current.bots = []; setBots([]); setBotId(''); setPhase('directory-error');
+      setDirectoryError(directoryUnsupported(error) ? '云端助理需要更新，请更新后重新连接。' : failure(error));
+    }
+  };
+  useEffect(() => {
+    const current = state.current; current.mounted = true;
+    const controller = new AbortController();
+    void refreshConnection(controller.signal);
+    const interval = setInterval(() => { if (current.mounted) setFps(current.frames); current.frames = 0; }, 1000);
+    const visibility = () => {
+      if (document.hidden) { releaseControl(); send({ type: 'pause' }); }
+      else if (current.socket?.readyState === 1) send({ type: 'resume' });
+      else if (current.reconnectAllowed && current.config?.configured && current.session === null && current.socket) void open(current.mode, true);
+    };
+    const observer = typeof ResizeObserver === 'function' ? new ResizeObserver(() => { if (current.lastDrawnFrame) { current.pendingFrame = current.lastDrawnFrame; void drawLatest(); } }) : null;
+    if (canvasRef.current) observer?.observe(canvasRef.current);
+    const blur = () => releaseControl();
+    const outside = event => { if (!viewRef.current?.contains(event.target)) releaseControl(); };
+    document.addEventListener('visibilitychange', visibility); window.addEventListener('blur', blur); document.addEventListener('pointerdown', outside, true);
+    return () => { current.mounted = false; observer?.disconnect(); if (current.pointerFrame) cancelAnimationFrame(current.pointerFrame); controller.abort(); close(false); clearInterval(interval); document.removeEventListener('visibilitychange', visibility); window.removeEventListener('blur', blur); document.removeEventListener('pointerdown', outside, true); };
+  }, [request]);
+  const point = event => mapDisplayPoint({ clientX: event.clientX, clientY: event.clientY, rect: canvasRef.current.getBoundingClientRect(), display: state.current.display });
+  const pointer = event => {
+    event.preventDefault(); const current = state.current, button = [1, 2, 3][event.button] || 1;
+    if (event.type === 'pointerdown') { inputRef.current?.focus(); canvasRef.current?.setPointerCapture(event.pointerId); if (input({ type: 'button', action: 'down', button, ...point(event) })) current.buttons.add(button); }
+    else { input({ type: 'button', action: 'up', button, ...point(event) }); current.buttons.delete(button); if (canvasRef.current?.hasPointerCapture(event.pointerId)) canvasRef.current.releasePointerCapture(event.pointerId); }
+  };
+  const key = event => {
+    if (state.current.composition || event.isComposing || event.nativeEvent?.isComposing || event.key === 'Process' || event.key === 'Unidentified') return;
+    // 画布上的 ⌘V/Ctrl+V 是"把本地剪贴板贴进云电脑"，不能把裸按键转给 Linux 桌面（它要的是 Ctrl+V）。
+    if (isPasteShortcut(event)) { event.preventDefault(); void pasteLocalClipboardToCloud(); return; }
+    if (isCopyShortcut(event)) {
+      event.preventDefault();
+      // 长按/重复的 keydown 不再触发第二次复制。
+      if (event.type === 'keydown' && !event.repeat) void copyCloudClipboardToLocal();
+      return;
+    }
+    const modified = event.ctrlKey || event.metaKey || event.altKey;
+    // 普通文本只走 input/compositionend，避免同一按键被发送两遍。
+    if (event.key.length === 1 && !modified) return;
+    if (event.key === 'Escape' && fullscreenRef.current) return;
+    event.preventDefault();
+    const name = keyNames[event.key] || event.key;
+    if (!/^[A-Za-z0-9_]+$/u.test(name)) return;
+    if (event.type === 'keydown') { if (!event.repeat && input({ type: 'key', action: 'down', key: name })) state.current.pressed.add(name); }
+    else { input({ type: 'key', action: 'up', key: name }); state.current.pressed.delete(name); }
+  };
+  const stateText = { loading: '正在检查助理状态', idle: '准备连接', dormant: '已空闲', resuming: '正在恢复桌面', unconfigured: '个人助理尚未开通', empty: '暂时没有可用助理', 'directory-error': '暂时无法读取助理列表', connecting: '正在启动云电脑', readonly: '只读旁观', ready: '正在控制云电脑', reconnecting: '正在恢复连接', hidden: '画面已暂停', closed: '桌面连接已结束', error: '连接暂时不可用' }[phase];
+  const buttonStyle = { ...ui, borderRadius: 6, padding: '7px 12px', cursor: 'pointer', font: 'inherit' };
+  const active = ['ready', 'readonly', 'hidden', 'reconnecting', 'dormant', 'resuming'].includes(phase);
+  const selectable = bots.length > 0;
+  const bindingReason = binding?.reason || '';
+  const candidateCount = Array.isArray(binding?.candidates) ? binding.candidates.length : 0;
+  const bindingTitle = bindingReason === 'needs-create' ? '还没有创建个人助理'
+    : bindingReason === 'credential-unavailable' ? '正在恢复个人助理的连接凭证'
+    : bindingReason === 'unavailable' ? '暂时无法自动连接个人助理' : '个人助理尚未开通';
+  const bindingDetail = bindingReason === 'needs-create' ? '云账号下还没有个人助理实例，创建后即可在这里连接专属云电脑。'
+    : bindingReason === 'credential-unavailable' ? '云端暂时没有返回连接凭证，可以重新获取。'
+    : bindingReason === 'unavailable' ? (binding?.detail || '请检查云端登录状态后重试。')
+    : '开通完成后，即可在这里连接专属云电脑。';
+  const emptyTitle = phase === 'unconfigured' ? bindingTitle : phase === 'empty' ? '助理正在准备中' : phase === 'directory-error' ? '暂时无法连接云端助理' : '正在检查助理状态';
+  const emptyDetail = phase === 'unconfigured' ? bindingDetail : phase === 'empty' ? '云端初始化完成后，可用助理会显示在这里。' : phase === 'directory-error' ? directoryError : '请稍候';
+  const computerVariant = variant === 'computer' || variant === 'native-tab';
+  const stage = h('div', { ref: viewRef, 'data-personal-assistant-desktop-card': computerVariant ? 'true' : undefined, style: {
+    position: 'relative', background: 'var(--dsw-alias-bg-layer-2, #f1f3f6)',
+    ...(computerVariant ? { width: '100%', aspectRatio: `${state.current.display.width} / ${state.current.display.height}`, flex: 'none', minWidth: 0, borderRadius: 14, overflow: 'hidden', boxShadow: '0 0 0 1px var(--dsw-alias-border-default, #d8dee8), 0 8px 28px #1018280d' } : { flex: 1, minHeight: 240 }),
+  } },
+    ['dormant', 'resuming'].includes(phase) ? h('div', { role: 'status', style: { position: 'absolute', inset: 0, zIndex: 1, pointerEvents: 'none', display: 'grid', placeItems: 'center', padding: 16, textAlign: 'center', background: 'color-mix(in srgb, var(--dsw-alias-bg-layer-1, #fff) 82%, transparent)', color: 'var(--dsw-alias-label-primary, #17202c)' } }, phase === 'dormant' ? '已空闲，操作桌面即可恢复' : '正在恢复桌面…') : null,
+    h('canvas', { ref: canvasRef, 'aria-label': '云电脑桌面', tabIndex: active ? 0 : -1, onPointerDown: pointer, onPointerUp: pointer, onPointerCancel: releasePointer, onLostPointerCapture: releasePointer, onPointerLeave: () => { if (cursorRef.current) cursorRef.current.style.visibility = 'hidden'; }, onPointerMove: event => {
+      const current = state.current, latest = event.nativeEvent?.getCoalescedEvents?.().at(-1) || event;
+      if (cursorRef.current) { const rect = canvasRef.current.getBoundingClientRect(); cursorRef.current.style.transform = `translate(${latest.clientX - rect.left}px, ${latest.clientY - rect.top}px)`; cursorRef.current.style.visibility = current.readOnly ? 'hidden' : 'visible'; }
+      current.lastPointer = point(latest);
+      if (!current.pointerFrame) current.pointerFrame = requestAnimationFrame(() => { if (current.mounted) flushPointer(); });
+    }, onContextMenu: event => event.preventDefault(), onWheel: event => { event.preventDefault(); input({ type: 'wheel', deltaY: event.deltaY / 100, deltaX: event.deltaX / 100 }); }, onKeyDown: key, onKeyUp: key, style: { ...(computerVariant ? { position: 'absolute', inset: 0 } : {}), width: '100%', height: '100%', display: 'block', visibility: active ? 'visible' : 'hidden', pointerEvents: active ? 'auto' : 'none', touchAction: 'none', cursor: readOnly ? 'default' : 'none' } }),
+    h('div', { ref: cursorRef, 'aria-hidden': true, style: { position: 'absolute', top: 0, left: 0, pointerEvents: 'none', visibility: 'hidden', zIndex: 2, width: 18, height: 22 } }, h('svg', { viewBox: '0 0 18 22', width: 18, height: 22 }, h('path', { d: 'M1 1v16l4-4 3 7 3-1-3-7h6z', fill: '#fff', stroke: '#162033', strokeWidth: 1.2 }))),
+    !active ? h('div', { style: { position: 'absolute', inset: 0, display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 10, padding: 16, textAlign: 'center' } },
+      h('h2', { style: { margin: 0, fontSize: 18, fontWeight: 500 } }, selectable ? stateText : emptyTitle),
+      h('p', { style: { margin: 0, maxWidth: 380, lineHeight: 1.7, color: 'var(--dsw-alias-label-secondary, #536174)' } }, selectable ? notice || '连接后即可使用云端桌面，关闭面板会释放本次控制。' : emptyDetail),
+      !selectable && phase !== 'loading' ? h('div', { style: { display: 'flex', gap: 8, flexWrap: 'wrap', justifyContent: 'center', alignItems: 'center' } },
+        phase === 'unconfigured' && bindingReason === 'needs-create' ? h('button', { style: buttonStyle, disabled: Boolean(busy), onClick: () => void bindAssistant('create') }, busy === 'create' ? '正在创建…' : '创建个人助理') : null,
+        phase === 'unconfigured' && (bindingReason === 'credential-unavailable' || candidateCount > 0) ? h('button', { style: buttonStyle, disabled: Boolean(busy), onClick: () => void bindAssistant('connect') }, busy === 'connect' ? '正在获取…' : bindingReason === 'credential-unavailable' ? '重新获取连接凭证' : '连接已发现的个人助理') : null,
+        h('button', { style: { ...buttonStyle, background: 'transparent' }, disabled: Boolean(busy), onClick: () => void refreshConnection() }, '检查开通状态'),
+        busy ? h('span', { role: 'status', style: { color: 'var(--dsw-alias-label-secondary, #536174)', fontSize: 12 } }, '处理中，请稍候…') : null) : null) : null,
+    h('input', { ref: inputRef, 'aria-label': '云电脑文本输入', autoComplete: 'off', disabled: !active || (readOnly && !controlRef.current.snapshot.available && !(state.current.mode === 'control' && ['dormant', 'resuming'].includes(phase))), tabIndex: -1, style: { position: 'absolute', width: 1, height: 1, opacity: 0, left: 0, top: 0 }, onKeyDown: key, onKeyUp: key, onCompositionStart: () => { state.current.composition = true; }, onCompositionEnd: event => { state.current.composition = false; const text = event.currentTarget.value; event.currentTarget.value = ''; if (text) input({ type: 'text', text }); }, onInput: event => { if (state.current.composition || event.nativeEvent?.isComposing) return; const text = event.currentTarget.value; event.currentTarget.value = ''; if (text) input({ type: 'text', text }); } }));
+  const secondaryInk = 'var(--dsw-alias-label-secondary, #536174)';
+  const ghostStyle = { ...buttonStyle, background: 'transparent', color: 'inherit', border: ui.border };
+  const pillStyle = { ...buttonStyle, borderRadius: 999, padding: '7px 16px', border: 'none', fontWeight: 500, background: 'var(--dsw-alias-label-primary, #17202c)', color: 'var(--dsw-alias-bg-layer-1, #fff)' };
+  if (computerVariant) {
+    return h('section', { 'data-personal-assistant-computer': 'true', style: { ...ui, border: 'none', height: '100%', minHeight: 0, minWidth: 0, display: 'flex', flexDirection: 'column', background: 'var(--dsw-alias-bg-base, #fff)', color: 'inherit', fontSize: 13 } },
+      variant !== 'native-tab' ? h('div', { style: { display: 'flex', alignItems: 'center', gap: 8, padding: '8px 12px', borderBottom: ui.border } },
+        h('strong', { style: { fontWeight: 500 } }, '云电脑'),
+        h('span', { role: 'status', 'aria-live': 'polite', style: { color: secondaryInk, fontSize: 12 } }, stateText),
+        null) : null,
+      readOnly && active && !controlRef.current.snapshot.available ? h('div', { role: 'alert', style: { background: '#fff0d6', color: '#763c00', padding: '8px 12px' } }, '只读旁观：鼠标和键盘不会发送到云电脑') : null,
+      h('div', { 'data-personal-assistant-desktop-layout': 'true', style: { flex: 1, minHeight: 0, minWidth: 0, overflow: 'auto', display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 12, padding: '20px 16px 12px', boxSizing: 'border-box' } },
+      h('div', { 'data-personal-assistant-desktop-stack': 'true', style: { width: '100%', maxWidth: 1280, margin: 'auto 0', display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 12, flex: 'none' } }, stage,
+      active || selectable ? h('div', { 'data-personal-assistant-control-capsule': 'true', role: 'status', 'aria-live': 'polite', style: { display: 'flex', flexWrap: 'wrap', justifyContent: 'center', alignItems: 'center', gap: 6, width: 'fit-content', maxWidth: '100%', boxSizing: 'border-box', padding: '7px 12px', borderRadius: 999, background: 'var(--dsw-alias-bg-layer-1, #fff)', border: ui.border, boxShadow: '0 1px 4px #10182808', lineHeight: 1.5 } },
+        !active && selectable ? h('button', { style: pillStyle, disabled: ['connecting', 'resuming'].includes(phase), onClick: () => void open(state.current.handoffSupported ? 'observe' : 'read') }, phase === 'connecting' ? '正在启动…' : '重新连接') : null,
+        active && readOnly ? h('span', { style: { color: secondaryInk, fontSize: 12 } }, controlPhase === 'acquiring' ? '正在接管…' : controlPhase === 'releasing' ? '正在交还…' : '助理正在使用 · 点画面即可接管') : null,
+        active && readOnly && controlRef.current.snapshot.available ? h('button', { style: { ...pillStyle, padding: '3px 9px', fontSize: 11 }, onClick: () => controlRef.current.acquire() }, '接管') : null,
+        active && !readOnly ? h('span', { style: { color: secondaryInk, fontSize: 12 } }, '您拥有控制权 · 点画面外释放') : null,
+        active && notice ? h('span', { style: { color: secondaryInk, fontSize: 12 } }, notice) : null,
+        // 剪贴板不再放按钮：面板里只保留 ⌘V 粘贴 / ⌘C 复制与一行状态文字。
+        active && clipboardNotice ? h('span', { role: 'status', 'aria-live': 'polite', style: { color: secondaryInk, fontSize: 12 } }, clipboardNotice) : null) : null),
+      h('details', { style: { alignSelf: 'flex-end', color: 'var(--dsw-alias-label-tertiary, #76808e)', fontSize: 11, opacity: 0.8, maxWidth: '100%', overflowWrap: 'anywhere' } }, h('summary', { style: { cursor: 'pointer' } }, '诊断'), h('small', { 'data-personal-assistant-build': PERSONAL_ASSISTANT_CLIENT_BUILD }, `构建 ${PERSONAL_ASSISTANT_CLIENT_BUILD}`))));
+  }
+  return h('section', { 'data-personal-assistant-panel': 'true', style: { ...ui, border: 'none', height: '100%', minHeight: 0, display: 'flex', flexDirection: 'column', fontSize: 13 } },
+    h('header', { style: { display: 'flex', flexWrap: 'wrap', gap: 8, alignItems: 'center', padding: 12, borderBottom: ui.border } },
+      h('strong', { style: { fontWeight: 500, marginRight: 8 } }, '个人助理'),
+      selectable && ['idle', 'closed', 'error'].includes(phase) ? h('button', { style: buttonStyle, onClick: () => void refreshConnection() }, '刷新助理列表') : null,
+      typeof openInSidebar === 'function' ? h('button', { style: buttonStyle, onClick: openInSidebar }, '放到右侧栏') : null,
+      selectable ? h('button', { style: buttonStyle, disabled: ['connecting', 'resuming'].includes(phase), onClick: () => phase === 'dormant' ? resumeIdle() : void open(state.current.handoffSupported ? 'observe' : 'control') }, phase === 'dormant' ? '恢复画面' : readOnly && phase === 'readonly' ? '申请控制' : active ? '重新连接' : '连接云电脑') : null,
+      selectable ? h('button', { style: buttonStyle, disabled: phase === 'connecting', onClick: () => void open('read') }, '只读旁观') : null,
+      active ? h('span', { role: 'status', 'aria-live': 'polite', style: { marginLeft: 'auto', color: 'var(--dsw-alias-label-secondary, #536174)' } }, stateText) : null),
+    phase === 'readonly' ? h('div', { role: 'alert', style: { background: '#fff0d6', color: '#763c00', padding: '8px 12px' } }, '当前为只读旁观，鼠标和键盘输入不会发送；可申请控制') : null,
+    active && notice ? h('div', { role: 'status', style: { padding: '8px 12px' } }, notice) : null,
+    stage,
+    h('footer', { style: { display: 'flex', alignItems: 'start', justifyContent: 'space-between', gap: 12, padding: '7px 12px', color: 'var(--dsw-alias-label-secondary, #536174)', borderTop: ui.border } },
+      h('details', { open: diagnosticsOpen, onToggle: event => setDiagnosticsOpen(event.currentTarget.open) }, h('summary', { style: { cursor: 'pointer' } }, '诊断'),
+        directoryCloseCode ? h('div', { style: { paddingTop: 8 } }, `目录连接关闭码：${directoryCloseCode}`) : null,
+        h('div', { style: { paddingTop: 8, lineHeight: 1.8, overflowWrap: 'anywhere' } }, h('div', null, `云端实例：${config?.agentId || '未开通'}`), h('div', null, `连接标识：${botId || '未连接'}`), h('div', null, `画面帧率：${fps} fps`), h('div', null, '快捷键会转发到云电脑；Esc 优先退出全屏'))),
+      h('small', { 'data-personal-assistant-build': PERSONAL_ASSISTANT_CLIENT_BUILD, style: { opacity: 0.75 } }, `构建 ${PERSONAL_ASSISTANT_CLIENT_BUILD}`)));
+}
+
+
+/** 主面板：对话式入口，云电脑在右侧栏。 */
+export function PersonalAssistantHome({ request, nativeWorkbench } = {}) {
+  const R = clientReact || globalThis.React;
+  if (!R) return '个人助理页面尚未就绪，请重新打开';
+  const { createElement: h, useEffect, useState, useCallback } = R;
+  const [scope, setScope] = useState(null);
+  const [error, setError] = useState('');
+  const [attempt, retry] = useState(0);
+  useEffect(() => {
+    let cancelled = false;
+    setScope(null); setError('');
+    void (async () => {
+      try {
+        const config = await request('personal-assistant.configuration');
+        if (!config.configured) throw new Error('个人助理尚未开通，请先在设置中连接云端实例');
+        const directory = await request('personal-assistant.bots.list');
+        if (directory.directoryAvailable !== true) throw new Error('暂时无法连接云端助理，请稍后重试');
+        const botId = resolveAssistantBotId(directory.bots, config.botId || directory.primaryBotId);
+        if (!cancelled) setScope({ agentId: config.agentId, botId });
+      } catch (failure) { if (!cancelled) setError(failure.message || '云端助理暂不可用'); }
+    })();
+    return () => { cancelled = true; };
+  }, [request, attempt]);
+  const scopedRequest = useCallback((operation, payload = {}) => {
+    if (!scope) throw new Error('云端助理尚未连接');
+    if (payload.agentId && payload.agentId !== scope.agentId) throw new Error('云端实例不一致');
+    if (operation !== 'personal-assistant.bots.list' && payload.botId && payload.botId !== scope.botId) throw new Error('云端助理不一致');
+    return request(operation, { ...payload, ...scope });
+  }, [request, scope?.agentId, scope?.botId]);
+  useEffect(() => { if (scope && nativeWorkbench?.available) nativeWorkbench.bind(scope, scopedRequest); else if (scope) setError(nativeWorkbench?.unavailableReason || '当前宿主需要更新原生侧栏组件'); }, [nativeWorkbench, scopedRequest, scope?.agentId, scope?.botId]);
+  if (!scope) return h('div', { role: 'status', style: { padding: 24 } }, error || '正在连接云端个人助理…', error ? h('button', { onClick: () => retry(value => value + 1) }, '重新连接') : null);
+  if (!nativeWorkbench?.available) return h('div', { role: 'alert', style: { padding: 24 } }, '当前宿主尚未提供原生云电脑侧栏，请更新 Studio 后重新打开。');
+  return h('div', {
+    key: `${scope.agentId}:${scope.botId}`, 'data-personal-assistant-home': 'true',
+    'data-agent-id': scope.agentId, 'data-bot-id': scope.botId,
+    style: { flex: '1 1 0px', height: '100%', maxHeight: '100%', minHeight: 0, minWidth: 0, overflow: 'hidden', boxSizing: 'border-box', display: 'flex', flexDirection: 'column' },
+  }, h(PersonalAssistantConversation, { React: R, request: scopedRequest, scope, onOpenComputer: () => nativeWorkbench.open() }));
+
+}
+
+
+const settingsStyle = {
+  page: { padding: '2px 2px 28px', display: 'flex', flexDirection: 'column', gap: 18, maxWidth: 700, fontSize: 13, color: 'var(--dsw-alias-label-primary, #17202c)' },
+  title: { margin: 0, fontSize: 18, fontWeight: 600, letterSpacing: '-0.01em' },
+  lede: { margin: 0, color: 'var(--dsw-alias-label-secondary, #536174)', fontSize: 13, lineHeight: 1.7 },
+  card: { border: ui.border, borderRadius: 12, overflow: 'hidden' },
+  row: { display: 'flex', gap: 16, padding: '12px 14px', borderTop: '1px solid var(--dsw-alias-border-default, #d8dee8)', alignItems: 'flex-start' },
+  rowFirst: { display: 'flex', gap: 16, padding: '12px 14px', alignItems: 'flex-start' },
+  label: { width: 116, flex: 'none', color: 'var(--dsw-alias-label-secondary, #536174)', fontSize: 13, lineHeight: 1.7 },
+  value: { flex: 1, minWidth: 0, fontSize: 13, lineHeight: 1.7, overflowWrap: 'anywhere' },
+  mono: { fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace', fontSize: 12 },
+  actions: { display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' },
+  button: { ...ui, borderRadius: 8, padding: '6px 11px', cursor: 'pointer', font: 'inherit', fontSize: 13 },
+  note: { color: 'var(--dsw-alias-label-secondary, #536174)', fontSize: 12, lineHeight: 1.7 },
+  badge: { display: 'inline-block', borderRadius: 999, padding: '1px 8px', fontSize: 12, lineHeight: 1.7 },
+  badgeOk: { background: 'color-mix(in srgb, #067647 12%, transparent)', color: '#067647' },
+  badgeIdle: { background: 'color-mix(in srgb, #946200 14%, transparent)', color: '#946200' },
+  badgeError: { background: 'color-mix(in srgb, #b42318 12%, transparent)', color: '#b42318' },
+};
+
+/** 设置页里的「个人助理」一节：状态、连接自检、能力与记忆位置。 */
+export function PersonalAssistantSettings({ request, openComputer = null } = {}) {
+  const R = clientReact || globalThis.React;
+  if (!R) return '设置页尚未就绪，请重新打开 Studio';
+  const { createElement: h, useEffect, useState, useCallback } = R;
+  const [config, setConfig] = useState(null);
+  const [bots, setBots] = useState(null);
+  const [error, setError] = useState('');
+  const [checking, setChecking] = useState(false);
+  const [checkedAt, setCheckedAt] = useState('');
+
+  const check = useCallback(async () => {
+    setChecking(true); setError('');
+    const started = Date.now();
+    try {
+      const current = await request('personal-assistant.configuration');
+      setConfig(current);
+      if (current?.configured) {
+        const directory = await request('personal-assistant.bots.list');
+        setBots(Array.isArray(directory?.bots) ? directory.bots : []);
+      } else { setBots([]); }
+      setCheckedAt(`${new Date().toLocaleTimeString('zh-CN', { hour12: false })} · ${Date.now() - started} ms`);
+    } catch (reason) {
+      setError(reason?.message || '连接检查失败');
+      setCheckedAt(`${new Date().toLocaleTimeString('zh-CN', { hour12: false })} · 失败`);
+    } finally { setChecking(false); }
+  }, [request]);
+
+  useEffect(() => { void check(); }, [check]);
+
+  const configured = config?.configured === true;
+  const status = config === null ? '检查中' : configured ? '已开通' : '尚未开通';
+  const statusStyle = { ...settingsStyle.badge, ...(config === null ? settingsStyle.badgeIdle : configured ? settingsStyle.badgeOk : settingsStyle.badgeIdle) };
+  const line = (label, value, first = false) => h('div', { style: first ? settingsStyle.rowFirst : settingsStyle.row },
+    h('div', { style: settingsStyle.label }, label), h('div', { style: settingsStyle.value }, value));
+
+  return h('section', { 'data-personal-assistant-settings': 'true', style: settingsStyle.page },
+    h('div', null,
+      h('h1', { style: settingsStyle.title }, '个人助理'),
+      h('p', { style: { ...settingsStyle.lede, marginTop: 6 } }, '云端持续运行的助理，带一台独立云电脑。关掉窗口它也在工作；对话与云电脑在左侧「个人助理」页。')),
+    error ? h('div', { role: 'alert', style: { ...settingsStyle.note, color: '#b42318', background: 'color-mix(in srgb, #b42318 8%, transparent)', border: '1px solid color-mix(in srgb, #b42318 25%, transparent)', borderRadius: 10, padding: '9px 12px' } }, error) : null,
+    h('div', { style: settingsStyle.card },
+      line('状态', h('span', null, h('span', { style: statusStyle }, status), checkedAt ? h('span', { style: settingsStyle.note }, `　上次检查 ${checkedAt}`) : null), true),
+      line('云端实例', config?.agentId ? h('span', { style: settingsStyle.mono }, config.agentId) : h('span', { style: settingsStyle.note }, configured ? '未返回实例标识' : '开通后由 Studio 绑定')),
+      line('网关', config?.gatewayUrl ? h('span', { style: settingsStyle.mono }, config.gatewayUrl) : h('span', { style: settingsStyle.note }, '由 Studio Host 配置')),
+      line('助理连接', h('span', { style: settingsStyle.note }, bots === null ? '检查中' : bots.length ? '已连接你的助理' : '助理尚未就绪')),
+      line('记忆', h('div', null, h('div', { style: settingsStyle.mono }, '/workspace/assistant-state'),
+        h('div', { style: settingsStyle.note }, '记忆、会话与定时任务随云电脑持久保存，换设备也在'))),
+      line('云端能力', h('div', null,
+        h('div', null, '默认开启：云端命令执行、云端浏览器'),
+        h('div', { style: settingsStyle.note }, '都跑在隔离工作区：读不到本机文件与凭证，不能访问内网与本机地址；敏感操作会先请你确认'))),
+      line('插件版本', h('span', { style: settingsStyle.note }, `构建 ${PERSONAL_ASSISTANT_CLIENT_BUILD}`))),
+    h('div', { style: settingsStyle.actions },
+      h('button', { style: settingsStyle.button, disabled: checking, onClick: () => void check() }, checking ? '正在检查…' : '检查连接'),
+      h('span', { style: settingsStyle.note }, '检查会读取开通状态并拉取一次助理列表，不会启动云电脑')));
+}
+
+export function PersonalAssistantPanelIcon({ size } = {}) {
+  const R = clientReact;
+  const edge = Number(size) > 0 ? Number(size) : 16;
+  if (!R?.createElement) return '助';
+  return R.createElement('svg', {
+    width: edge, height: edge, viewBox: '0 0 16 16', fill: 'none', stroke: 'currentColor', strokeWidth: 1.4,
+    strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': 'true', focusable: 'false', style: { display: 'block' },
+  },
+  R.createElement('path', { d: 'M3.4 3.2h9.2a1.3 1.3 0 0 1 1.3 1.3H7.7l-2.9 2.3v-2.3H3.4a1.3 1.3 0 0 1-1.3-1.3V4.5a1.3 1.3 0 0 1 1.3-1.3z' }),
+  R.createElement('path', { d: 'M8.1 5.6l.62 1.46 1.46.62-1.46.62L8.1 9.76l-.62-1.46-1.46-.62 1.46-.62z' }));
+}
+export function PersonalAssistantComputerTabGlyph({ size } = {}) {
+  const R = clientReact;
+  const edge = Number(size) > 0 ? Number(size) : 16;
+  if (!R?.createElement) return null;
+  return R.createElement('svg', {
+    width: edge, height: edge, viewBox: '0 0 16 16', fill: 'none', stroke: 'currentColor', strokeWidth: 1.4,
+    strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': 'true', focusable: 'false',
+    style: { display: 'block', flex: '0 0 auto' },
+  },
+  R.createElement('rect', { x: 2.2, y: 3.4, width: 11.6, height: 7.4, rx: 1.4 }),
+  R.createElement('path', { d: 'M6.6 13.4h2.8' }),
+  R.createElement('path', { d: 'M8 10.8v2.6' }));
+}
+
+export function PersonalAssistantComputerTabTitle() {
+  const R = clientReact;
+  const glyph = PersonalAssistantComputerTabGlyph({ size: 15 });
+  if (!R?.createElement || !glyph) return '云电脑';
+  return R.createElement('span', { style: { display: 'inline-flex', alignItems: 'center', gap: '6px', lineHeight: 1 } },
+    glyph, R.createElement('span', null, '云电脑'));
+}
+export function apply(ctx) {
+  if (!ctx?.slots?.inject || !ctx.slots.register) throw new TypeError('Personal Assistant client requires the public DSH slots service');
+  const request = async (operation, payload = {}) => {
+    if (!ctx.connection?.rpc?.call) throw new PersonalAssistantGatewayUnavailableError();
+    const result = await ctx.connection.rpc.call('/api', 'personal-assistant', { operation, payload });
+    if (!result?.ok) throw Object.assign(new Error(result?.error?.message || 'Studio Host 请求失败'), { code: result?.error?.code, status: result?.error?.details?.status, closeCode: result?.error?.details?.closeCode });
+    return result.value;
+  };
+  // 注册一律走作用域助手：任一条注册失败只降级该入口，绝不让插件激活整体失败（激活失败会导致 Studio 重置 profile）。
+  const scope = (factory, label) => {
+    try {
+      const run = () => factory();
+      if (typeof ctx.effect === 'function') return ctx.effect(run, label);
+      return run();
+    } catch (error) {
+      try { console.warn(`[personal-assistant] ${label} 注册失败`, error); } catch {}
+      return undefined;
+    }
+  };
+  const nativeWorkbench = createAssistantWorkbench({ sidebarRight: ctx.sidebarRight, slots: ctx.slots });
+  if (nativeWorkbench) {
+    nativeWorkbench.render = props => AssistantNativeRightbar({ ...props, React: clientReact || globalThis.React, workbench: nativeWorkbench, Panel: PersonalAssistantPanel });
+    scope(() => () => nativeWorkbench.dispose(), 'personal-assistant: native workbench');
+  }
+  scope(() => ctx.slots.inject('main', () => ctx.slots.register({
+    name: 'main', key: PERSONAL_ASSISTANT_PANEL_ID, inject: () => ({ request, nativeWorkbench }),
+  }, PersonalAssistantHome)), 'personal-assistant: main panel');
+  scope(() => ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({
+    name: 'sidebar.panellist', id: PERSONAL_ASSISTANT_PANEL_ID, order: 90, label: '个人助理',
+  }, PersonalAssistantPanelIcon)), 'personal-assistant: sidebar row');
+  // Studio 设置页里的「个人助理」一节（原产品页被去重后留下的位置）。
+  scope(() => ctx.slots.inject('settings.section', () => ctx.slots.register({
+    name: 'settings.section', id: `${PERSONAL_ASSISTANT_PANEL_ID}-settings`, order: 196, label: '个人助理',
+    inject: () => ({ request }),
+  }, PersonalAssistantSettings)), 'personal-assistant: settings section');
+  // 普通会话标签页仍可注册；全局个人助理页面使用原生 panel surface，不创建本地会话。
+  const registerComputerTab = () => {
+    if (typeof ctx.inject !== 'function') return;
+    scope(() => ctx.inject(['sidebarRightTabs'], (sub) => {
+      const cleanups = [];
+      const add = (dispose) => { if (typeof dispose === 'function') cleanups.push(dispose); };
+      try {
+        const tabs = sub.sidebarRightTabs;
+        if (tabs === undefined || typeof tabs.register !== 'function') return undefined;
+        add(tabs.register({
+          id: PERSONAL_ASSISTANT_COMPUTER_TAB,
+          kind: PERSONAL_ASSISTANT_COMPUTER_TAB,
+          title: () => '云电脑',
+          guide: [{
+            order: 20,
+            title: () => '云电脑',
+            description: () => '个人助理的云端电脑画面，可获取控制权',
+          }],
+        }));
+        add(sub.slots.inject('sidebar.right.pane.tab', () => sub.slots.register({
+          name: 'sidebar.right.pane.tab', key: PERSONAL_ASSISTANT_COMPUTER_TAB, inject: () => ({ request }),
+        }, props => PersonalAssistantPanel({ ...props, variant: 'computer' }))));
+        add(sub.slots.inject('sidebar.right.pane.tab.title', () => sub.slots.register({
+          name: 'sidebar.right.pane.tab.title', key: PERSONAL_ASSISTANT_COMPUTER_TAB,
+        }, PersonalAssistantComputerTabTitle)));
+      } catch (error) {
+        try { console.warn('[personal-assistant] 右侧栏注册失败', error); } catch {}
+      }
+      return () => { for (const dispose of cleanups.reverse()) dispose(); };
+    }), 'personal-assistant: right tab');
+  };
+  registerComputerTab();
+}
+export const createClientPlugin = createPersonalAssistantClient;