@kingsoftcloud/agentkit-personal-assistant 0.1.10 → 0.1.13

package/src/client/index.mjs

@@ -35,7 +35,8 @@ export function createPersonalAssistantClient({ gateway, profileId = 'default' }
     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 }),
+    // 网关公开的是单数 session.create；旧的 sessions.create 从未进入云端会话通道。
+    createSession: input => request('personal-assistant.session.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 }),
@@ -67,9 +68,9 @@ 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 { fitDesktopBox, mapDisplayPoint, mergeWheel, normalizeDisplay } from './desktop-view.mjs';
 import { createDesktopControl } from './desktop-control.mjs';
-import { createClipboardChannel, isPasteShortcut, isCopyShortcut, copyCloudClipboard, pasteToCloud, readLocalClipboard } from './components/desktop-clipboard.mjs';
+import { createClipboardChannel, isPasteShortcut, isCopyShortcut, copyShortcutEvents, copyCloudClipboard, readCloudClipboardAfterCopy, clipboardTextOf, pasteToCloud, readLocalClipboard, writeLocalClipboard } from './components/desktop-clipboard.mjs';
 import { PersonalAssistantConversation } from './conversation.mjs';
 import { createAssistantWorkbench, AssistantNativeRightbar } from './native-workbench.mjs';
 import { publicBotDirectory, resolveAssistantBotId } from './bot-directory.mjs';
@@ -77,6 +78,14 @@ export const PERSONAL_ASSISTANT_CLIENT_BUILD = typeof __PA_CLIENT_BUILD__ === 's
 const FIRST_FRAME_TIMEOUT_MS = 12_000;
 let clientReact;
 export function setClientReactRuntime(runtime) { clientReact = runtime; }
+let clientMarkdown;
+/**
+ * 注入宿主 DSH 的 ui-primitives —— 原生 Markdown 渲染器（MarkdownText）所在模块。
+ * 老宿主导出的模块里没有 MarkdownText 时传 undefined，对话视图退回自带极简渲染。
+ */
+export function setClientMarkdownRuntime(runtime) {
+  clientMarkdown = runtime && typeof runtime.MarkdownText === 'function' ? runtime : undefined;
+}
 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)',
@@ -84,12 +93,67 @@ const ui = {
 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);
+/**
+ * 「未开通」引导页的唯一事实来源：云电脑面板、设置页、首页共用同一套判断与动作。
+ *
+ * reason 由 Studio 给出：needs-create（账号下确实没有实例）、credential-unavailable（有实例但
+ * 凭证取不到）、unavailable（连状态都读不到，多为 Studio 未登录云端或网关不可达）。
+ * 只有确认没有实例时才给「开通」入口——一个子账号一个个人助理，已开通必须复用，避免重复创建；
+ * candidates 非空时一律优先连接已发现的实例。
+ */
+export function unconfiguredGuidance(binding) {
+  const reason = typeof binding?.reason === 'string' ? binding.reason : '';
+  const candidates = Array.isArray(binding?.candidates) ? binding.candidates.filter(row => typeof row?.agentId === 'string' && row.agentId) : [];
+  const check = { id: 'check', label: '检查开通状态' };
+  if (candidates.length > 0) return {
+    tone: 'reuse', title: '发现已开通的个人助理',
+    detail: `账号下已有 ${candidates.length} 个个人助理。一个子账号只需要一个，直接连接即可复用，不会重复创建。`,
+    actions: [{ id: 'connect', label: '连接已发现的个人助理', primary: true }, check],
+  };
+  if (reason === 'needs-create') return {
+    tone: 'create', title: '开通个人助理',
+    detail: '一个子账号可开通一个个人助理。开通后会得到一位云端持续运行的助理和一台专属云电脑，关掉 Studio 也会继续工作。',
+    actions: [{ id: 'create', label: '开通个人助理', primary: true }, check],
+  };
+  if (reason === 'credential-unavailable') return {
+    tone: 'reuse', title: '正在恢复连接凭证',
+    detail: '个人助理实例已经在账号下，但云端暂时没有返回连接凭证。重新获取即可复用现有实例，不需要重新开通。',
+    actions: [{ id: 'connect', label: '重新获取连接凭证', primary: true }, check],
+  };
+  const detail = typeof binding?.detail === 'string' && binding.detail ? binding.detail : '';
+  return {
+    tone: 'retry', title: '暂时读不到开通状态',
+    detail: `${detail}请先确认 Studio 已登录云端账号，再重新检查一次；确认账号下确实没有个人助理后再开通，避免重复创建。`,
+    actions: [check, { id: 'create', label: '确认未开通后开通', primary: false }],
+  };
+}
+
+const onboardingSteps = tone => tone === 'reuse'
+  ? ['确认账号下的个人助理实例', '直接连接即可复用，不会重复创建', '需要看画面或动手时，打开「云电脑」接管']
+  : ['登录 Studio 云端账号，开通个人助理（约 1–2 分钟）', '连接后即可在「个人助理」页对话，云端 7×24 运行', '需要看画面或动手时，打开「云电脑」接管'];
+
+const onboardingStyle = {
+  page: { flex: '1 1 auto', minHeight: 0, overflowY: 'auto', display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 14, padding: '32px 20px', textAlign: 'center', boxSizing: 'border-box' },
+  eyebrow: { fontSize: 11, letterSpacing: '0.1em', textTransform: 'uppercase', color: 'var(--dsw-alias-label-secondary, #536174)' },
+  title: { margin: 0, fontSize: 20, fontWeight: 600, letterSpacing: '-0.01em' },
+  detail: { margin: 0, maxWidth: 460, lineHeight: 1.75, color: 'var(--dsw-alias-label-secondary, #536174)' },
+  steps: { margin: 0, padding: 0, listStyle: 'none', display: 'flex', flexDirection: 'column', gap: 8, textAlign: 'left', maxWidth: 460 },
+  step: { display: 'flex', gap: 10, alignItems: 'flex-start', lineHeight: 1.7 },
+  stepIndex: { flex: 'none', width: 20, height: 20, borderRadius: 999, display: 'grid', placeItems: 'center', fontSize: 12, background: 'color-mix(in srgb, currentColor 10%, transparent)' },
+  actions: { display: 'flex', gap: 10, flexWrap: 'wrap', justifyContent: 'center', alignItems: 'center', marginTop: 4 },
+  primary: { ...ui, borderRadius: 8, padding: '8px 16px', cursor: 'pointer', font: 'inherit', fontSize: 13, fontWeight: 500, border: 'none', background: 'var(--dsw-alias-label-primary, #17202c)', color: 'var(--dsw-alias-bg-layer-1, #fff)' },
+  ghost: { ...ui, borderRadius: 8, padding: '8px 14px', cursor: 'pointer', font: 'inherit', fontSize: 13, background: 'transparent' },
+  notice: { margin: 0, maxWidth: 460, color: 'var(--dsw-alias-label-secondary, #536174)', fontSize: 12, lineHeight: 1.7 },
+  diag: { alignSelf: 'center', color: 'var(--dsw-alias-label-tertiary, #76808e)', fontSize: 11, opacity: 0.8, maxWidth: '100%', overflowWrap: 'anywhere' },
+};
+
 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 useLayoutEffect = R.useLayoutEffect || useEffect;
   const [config, setConfig] = useState(null);
   const [bots, setBots] = useState([]);
   const [directoryError, setDirectoryError] = useState('');
@@ -105,11 +169,16 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
   const [binding, setBinding] = useState(null);
   const [busy, setBusy] = useState('');
   const [clipboardNotice, setClipboardNotice] = useState('');
+  const [desktopDiagnostics, setDesktopDiagnostics] = useState(null);
+  // 桌面卡片尺寸由「可用宽 × 可用高」共同决定：全屏后高度不够时按高度反推宽度，
+  // 保证远端整幅画面（含云浏览器顶部地址/输入条）完整可见，不靠滚动兜底。
+  const [desktopDisplay, setDesktopDisplay] = useState(() => normalizeDisplay());
+  const [stageBox, setStageBox] = useState(null);
   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 canvasRef = useRef(null), inputRef = useRef(null), viewRef = useRef(null), cursorRef = useRef(null), stageAreaRef = useRef(null), controlCapsuleRef = 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 });
+  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, wheelPending: { x: 0, y: 0 }, wheelFrame: 0, pressed: new Set(), buttons: new Set(), composition: false, retries: 0, taskId: '', mode: 'control', frameMetadata: null, reconnectAllowed: false, controlError: '' });
   state.current.botId = botId;
   const rpc = async (operation, payload = {}) => {
     if (typeof request !== 'function') throw new Error('Studio Host 尚未连接');
@@ -134,11 +203,12 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
     send,
     changed: value => {
       const current = state.current; current.controlPhase = value.phase; current.readOnly = value.readOnly; current.controlEpoch = value.controlEpoch;
+      if (value.phase === 'controlling') current.controlError = '';
       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); },
+    failed: message => { state.current.controlError = message || '控制权暂不可用'; if (state.current.mounted) setNotice(message); },
   });
   // 剪贴板请求复用同一条桌面 WS（云端 desktop-ws 的 clipboard.read / clipboard.write），
   // 用 requestId 关联回复；旧版云端不认这两个消息类型，超时后给明确提示而不是转圈。
@@ -163,6 +233,7 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
     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 (current.mounted) setDesktopDiagnostics(null);
     if (announce && current.mounted) { setPhase(current.config?.configured ? 'idle' : 'unconfigured'); setReadOnly(true); }
   };
   const ended = value => {
@@ -201,28 +272,81 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
     for (const event of events) sent = input(event) || sent;
     return sent;
   };
-  // ⌘C：先把按键原样交给云电脑，让云端应用自己完成“复制”，再取回云端剪贴板。
-  // 之前只读剪贴板不转发按键，用户按 ⌘C 等于没复制，还会在输入框里反复触发按键。
+  // 剪贴板读写和桌面输入共用 human 控制租约。旁观状态下先申请接管并等待
+  // 服务端回执，避免“写入剪贴板”先于 lease 成功而稳定收到 409。
+  const ensureClipboardControl = async () => {
+    const current = state.current;
+    const snapshot = controlRef.current?.snapshot;
+    if (!current.session || current.socket?.readyState !== 1) { clipboardNotify('云电脑尚未连接，请先打开桌面'); return false; }
+    if (snapshot && snapshot.phase === 'controlling' && snapshot.readOnly === false) return true;
+    if (current.suspended || current.resuming) { clipboardNotify('云电脑正在恢复，请稍候再试'); return false; }
+    if (!snapshot?.available) { clipboardNotify('当前为只读旁观，请先打开控制模式'); return false; }
+    current.controlError = '';
+    if (!controlRef.current.acquire()) { clipboardNotify('当前无法接管云电脑，请重试'); return false; }
+    const deadline = Date.now() + 8000;
+    while (Date.now() < deadline) {
+      await new Promise(resolve => setTimeout(resolve, 50));
+      const latest = controlRef.current.snapshot;
+      if (latest.phase === 'controlling' && latest.readOnly === false) return true;
+      if (current.controlError) break;
+    }
+    clipboardNotify(current.controlError || '接管云电脑超时，请重试');
+    return false;
+  };
+  // ⌘C：先把复制按键交给云电脑，让云端应用自己完成“复制”，再取回云端剪贴板。
+  // 云端桌面始终是 Linux，不能把 macOS 的 Meta 映射为 Super_L，否则 Linux 应用不会执行复制。
   const copyCloudClipboardToLocal = async () => {
-    const modifier = /Mac|iPhone|iPad/u.test(String(globalThis.navigator?.platform || '')) ? 'Meta' : 'Control';
+    if (!await ensureClipboardControl()) return { ok: false, code: 'CLIPBOARD_CONTROL_REQUIRED' };
+    // 先记住旧 selection，再发 Ctrl+C；X11 的 selection owner 在按键后异步更新，
+    // 直接 sleep 150ms 仍可能读到旧文本，尤其是中文/浏览器渲染进程较忙时。
+    const before = await clipboardRef.current.read().catch(() => ({ text: '' }));
+    let sent = false;
     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'); }
+      try { sent = sendDesktopKeys(copyShortcutEvents()) !== false; }
+      finally { state.current.pressed.delete('_copyShortcut'); }
+    }
+    if (!sent) { clipboardNotify('复制按键未发送，请先接管云电脑后再试'); return { ok: false, code: 'CLIPBOARD_KEY_NOT_SENT' }; }
+    let settled;
+    try {
+      settled = await readCloudClipboardAfterCopy({
+        readCloud: () => clipboardRef.current.read(),
+        beforeText: clipboardTextOf(before),
+      });
+    } catch (error) {
+      clipboardNotify(error?.message || '读取云电脑剪贴板失败，请重试');
+      return { ok: false, code: error?.code || 'CLIPBOARD_READ_FAILED' };
     }
-    return copyCloudClipboard({ readCloud: () => clipboardRef.current.read(), notify: clipboardNotify });
+    return copyCloudClipboard({ readCloud: async () => settled, writeLocal: text => writeHostClipboard(text), notify: clipboardNotify });
+  };
+  // 本机剪贴板优先走 Host 进程（pbpaste/pbcopy）：Studio 渲染器没有 clipboard 权限，
+  // navigator.clipboard 在面板里会被拒，⌘C/⌘V 就成了空操作。旧 Host 不支持时再退回浏览器 API。
+  const readHostClipboard = async () => {
+    try {
+      const value = await rpc('personal-assistant.clipboard.read');
+      if (typeof value?.text === 'string') return value.text;
+    } catch { /* 旧 Host 没有剪贴板 RPC，退回浏览器剪贴板 */ }
+    return readLocalClipboard();
+  };
+  const writeHostClipboard = async text => {
+    try { await rpc('personal-assistant.clipboard.write', { text: String(text ?? '') }); return; }
+    catch { /* 同上 */ }
+    await writeLocalClipboard(String(text ?? ''));
   };
   const pasteLocalClipboardToCloud = () => pasteToCloud({
-    readLocal: () => readLocalClipboard(),
+    readLocal: () => readHostClipboard(),
     writeCloud: text => clipboardRef.current.write(text),
     sendKeys: sendDesktopKeys,
+    ensureControl: ensureClipboardControl,
+    notify: clipboardNotify,
+  });
+  // paste 事件兜底：macOS 上 Electron 的编辑菜单可能先把 ⌘V 吃掉，但浏览器仍会把
+  // 剪贴板内容作为 paste 事件交给聚焦的输入框，这里直接把文本写进云电脑剪贴板。
+  const pasteTextToCloud = text => pasteToCloud({
+    readLocal: async () => String(text ?? ''),
+    writeCloud: value => clipboardRef.current.write(value),
+    sendKeys: sendDesktopKeys,
+    ensureControl: ensureClipboardControl,
     notify: clipboardNotify,
   });
   const drawLatest = async () => {
@@ -306,7 +430,8 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
         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.session = value.sessionId; current.readOnly = Boolean(value.readOnly); current.display = normalizeDisplay(value.display); setDesktopDisplay(current.display);
+          setDesktopDiagnostics(value.diagnostics || null);
           current.mode = mode;
           controlRef.current.reset(value);
           const inputs = current.pendingInputs; current.pendingInputs = [];
@@ -320,6 +445,9 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
         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') {
+          // 旧版 runtime 对 clipboard 消息只回无 requestId 的通用错误帧；
+          // 立刻结束在途请求，直接给出“版本较旧”提示，避免再等 5 秒超时。
+          if (clipboardRef.current?.accept(value)) return;
           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; }
@@ -336,6 +464,9 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
       socket.onerror = () => { if (valid()) setNotice('桌面通道暂时断开，正在重连'); };
       socket.onclose = event => {
         if (!valid()) return;
+        // 挂起/异常关闭都要立即结束在途请求；否则面板会等到超时才知道
+        // 剪贴板操作没有完成，而重连后的响应也不应误认领旧 requestId。
+        clipboardRef.current?.rejectAll();
         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; }
@@ -388,7 +519,18 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
     } 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');
+      state.current.bots = []; setBots([]); setBotId('');
+      // 配置接口本身失败（Studio 未登录、网关不可达）时不能直接判死：desktop.status 不抛错，
+      // 用它区分「账号下确实没有实例」与「暂时读不到状态」，把开通/复用入口交给引导页。
+      const snapshot = retried ? null : await bindingSnapshot(signal).catch(() => null);
+      if (signal?.aborted || !state.current.mounted) return;
+      if (snapshot?.configured) { setBinding(null); await refreshConnection(signal, true); return; }
+      if (snapshot) {
+        setBinding(typeof snapshot.reason === 'string' && snapshot.reason ? snapshot : { ...snapshot, reason: 'unavailable', detail: bindingFailure(error) });
+        setPhase('unconfigured');
+        return;
+      }
+      setPhase('directory-error');
       setDirectoryError(directoryUnsupported(error) ? '云端助理需要更新，请更新后重新连接。' : failure(error));
     }
   };
@@ -407,9 +549,28 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
     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); };
+    return () => { current.mounted = false; observer?.disconnect(); if (current.pointerFrame) cancelAnimationFrame(current.pointerFrame); if (current.wheelFrame) cancelAnimationFrame(current.wheelFrame); 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 });
+  // 触控板一次滑动手势会推几十上百个 wheel 事件。以前每个事件都发一条 input，
+  // 云端每个都要跑一次 xdotool 且顺带触发一次抓帧，滚起来就明显迟滞；这里按动画帧
+  // 合并：像素累计够一格才发一条 wheel（余数跨帧保留），鼠标一格 = 一次滚动，触控板
+  // 按累计距离滚动，消息数和远端开销都降一个数量级。
+  const wheel = event => {
+    event.preventDefault();
+    const current = state.current;
+    const pending = current.wheelPending || (current.wheelPending = { x: 0, y: 0 });
+    current.wheelPending = { x: pending.x + (Number(event.deltaX) || 0), y: pending.y + (Number(event.deltaY) || 0) };
+    if (current.wheelFrame) return;
+    current.wheelFrame = requestAnimationFrame(() => {
+      current.wheelFrame = 0;
+      if (!current.mounted) return;
+      const merged = mergeWheel(current.wheelPending);
+      current.wheelPending = merged.pending;
+      if (!merged.clicks.deltaX && !merged.clicks.deltaY) return;
+      input({ type: 'wheel', deltaX: merged.clicks.deltaX, deltaY: merged.clicks.deltaY });
+    });
+  };
   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); }
@@ -451,9 +612,56 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
   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';
+  // 接管状态紧贴桌面卡片下方；测量时扣掉胶囊本身，避免状态条把画面挤出右栏。
+  useLayoutEffect(() => {
+    if (!computerVariant) return undefined;
+    const node = stageAreaRef.current;
+    if (!node) return undefined;
+    const measure = () => {
+      const rect = node.getBoundingClientRect();
+      const measuredCapsuleHeight = controlCapsuleRef.current?.getBoundingClientRect?.().height || 0;
+      // Some hosts expose the parent rect for an unlaid-out child during the
+      // first pass. Cap the measurement so that transient geometry cannot
+      // collapse the desktop card to 0x0; ResizeObserver will refine it later.
+      const capsuleHeight = active || selectable ? Math.min(128, Math.max(44, measuredCapsuleHeight)) : 0;
+      const availableHeight = Math.max(0, rect.height - (capsuleHeight ? capsuleHeight + 10 : 0));
+      const next = fitDesktopBox({ availableWidth: rect.width, availableHeight, display: desktopDisplay, maxWidth: 1280 });
+      setStageBox(previous => {
+        if (!(next.width > 0 && next.height > 0)) return previous ?? null;
+        return previous && Math.abs(previous.width - next.width) < 0.5 && Math.abs(previous.height - next.height) < 0.5 ? previous : next;
+      });
+    };
+    measure();
+    const observer = typeof ResizeObserver === 'function' ? new ResizeObserver(measure) : null;
+    observer?.observe(node);
+    if (controlCapsuleRef.current) observer?.observe(controlCapsuleRef.current);
+    return () => observer?.disconnect();
+  }, [computerVariant, desktopDisplay, active, selectable, controlPhase, notice, clipboardNotice]);
+  const guidance = phase === 'unconfigured' ? unconfiguredGuidance(binding) : null;
+  const onboardingClick = action => {
+    if (action === 'check') void refreshConnection();
+    else void bindAssistant(action);
+  };
+  const onboarding = guidance ? h('div', { 'data-personal-assistant-onboarding': 'true', style: onboardingStyle.page },
+    h('div', { 'data-window-drag': '', style: { display: 'flex', flexDirection: 'column', gap: 4, alignItems: 'center' } },
+      h('div', { style: onboardingStyle.eyebrow }, '个人助理 · 开通引导'),
+      h('h2', { style: onboardingStyle.title }, guidance.title)),
+    h('p', { style: onboardingStyle.detail }, guidance.detail),
+    h('ol', { style: onboardingStyle.steps },
+      onboardingSteps(guidance.tone).map((text, index) => h('li', { key: text, style: onboardingStyle.step },
+        h('span', { style: onboardingStyle.stepIndex }, String(index + 1)), h('span', null, text)))),
+    h('div', { style: onboardingStyle.actions },
+      guidance.actions.map(action => h('button', {
+        key: action.id, disabled: Boolean(busy), style: action.primary ? onboardingStyle.primary : onboardingStyle.ghost,
+        onClick: () => onboardingClick(action.id),
+      }, busy === action.id ? (action.id === 'create' ? '正在开通…' : action.id === 'connect' ? '正在连接…' : '检查中…') : action.label)),
+      busy ? h('span', { role: 'status', style: onboardingStyle.notice }, '处理中，请稍候…') : null),
+    notice ? h('p', { role: 'status', style: onboardingStyle.notice }, notice) : null,
+    h('details', { style: onboardingStyle.diag }, h('summary', { style: { cursor: 'pointer' } }, '诊断'),
+      h('small', { 'data-personal-assistant-build': PERSONAL_ASSISTANT_CLIENT_BUILD }, `构建 ${PERSONAL_ASSISTANT_CLIENT_BUILD}`))) : null;
   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 }),
+    ...(computerVariant ? { ...(stageBox && stageBox.width > 0 && stageBox.height > 0 ? { width: `${stageBox.width}px`, height: `${stageBox.height}px` } : { width: '100%', aspectRatio: `${desktopDisplay.width} / ${desktopDisplay.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 => {
@@ -461,7 +669,7 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
       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' } }),
+    }, onContextMenu: event => event.preventDefault(), onWheel: wheel, 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),
@@ -471,7 +679,7 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
         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 }); } }));
+    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, onPaste: event => { const text = event.clipboardData?.getData?.('text/plain') ?? ''; if (!text) return; event.preventDefault(); void pasteTextToCloud(text); }, 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)' };
@@ -482,17 +690,29 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
         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 } },
+      h('div', { 'data-personal-assistant-desktop-layout': 'true', style: { flex: 1, minHeight: 0, minWidth: 0, overflow: 'hidden', display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 12, padding: '20px 16px 12px', boxSizing: 'border-box' } },
+      h('div', { ref: stageAreaRef, 'data-personal-assistant-desktop-stack': 'true', style: { width: '100%', maxWidth: 1280, minHeight: 0, flex: '1 1 auto', display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 10 } },
+      onboarding || stage,
+      active || selectable ? h('div', { ref: controlCapsuleRef, 'data-personal-assistant-control-capsule': 'true', role: 'status', 'aria-live': 'polite', style: { flex: 'none', 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 && !readOnly ? h('button', { style: { ...ghostStyle, padding: '3px 9px', fontSize: 11 }, onClick: releaseControl }, '交还') : 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}`))));
+      ),
+      h('details', { style: { flex: 'none', 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('div', { style: { paddingTop: 8, lineHeight: 1.7 } },
+          h('div', null, `客户端：${PERSONAL_ASSISTANT_CLIENT_BUILD}`),
+          desktopDiagnostics ? h('div', null, `云电脑包：${desktopDiagnostics.packageVersion || '未知'} · 清单：${desktopDiagnostics.manifestVersion || '未知'}`) : null,
+          desktopDiagnostics?.runtimeBuild && desktopDiagnostics.runtimeBuild !== 'unknown' ? h('div', null, `运行时构建：${desktopDiagnostics.runtimeBuild}`) : null,
+          desktopDiagnostics?.computerImage && desktopDiagnostics.computerImage !== 'unknown' ? h('div', null, `电脑镜像：${desktopDiagnostics.computerImage}`) : null,
+          desktopDiagnostics?.dock ? h('div', null, `Dock：${desktopDiagnostics.dock.position} · ${desktopDiagnostics.dock.iconCount} 个图标`) : null,
+        )),
+      );
   }
   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 } },
@@ -504,11 +724,17 @@ export function PersonalAssistantPanel({ request, initialBotId = '', openInSideb
       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,
+    onboarding || 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('div', { style: { paddingTop: 8, lineHeight: 1.8, overflowWrap: 'anywhere' } },
+          h('div', null, `云端实例：${config?.agentId || '未开通'}`),
+          h('div', null, `连接标识：${botId || '未连接'}`),
+          h('div', null, `画面帧率：${fps} fps`),
+          desktopDiagnostics ? h('div', null, `云电脑包：${desktopDiagnostics.packageVersion || '未知'} · 清单：${desktopDiagnostics.manifestVersion || '未知'}`) : null,
+          desktopDiagnostics?.dock ? h('div', null, `Dock：${desktopDiagnostics.dock.position} · ${desktopDiagnostics.dock.iconCount} 个图标`) : null,
+          h('div', null, '快捷键会转发到云电脑；Esc 优先退出全屏'))),
       h('small', { 'data-personal-assistant-build': PERSONAL_ASSISTANT_CLIENT_BUILD, style: { opacity: 0.75 } }, `构建 ${PERSONAL_ASSISTANT_CLIENT_BUILD}`)));
 }
 
@@ -520,14 +746,21 @@ export function PersonalAssistantHome({ request, nativeWorkbench } = {}) {
   const { createElement: h, useEffect, useState, useCallback } = R;
   const [scope, setScope] = useState(null);
   const [error, setError] = useState('');
+  const [binding, setBinding] = useState(null);
+  const [bindingBusy, setBindingBusy] = useState('');
   const [attempt, retry] = useState(0);
   useEffect(() => {
     let cancelled = false;
-    setScope(null); setError('');
+    setScope(null); setError(''); setBinding(null);
     void (async () => {
       try {
         const config = await request('personal-assistant.configuration');
-        if (!config.configured) throw new Error('个人助理尚未开通，请先在设置中连接云端实例');
+        if (!config.configured) {
+          // 未开通不是错误：读一次不抛错的绑定快照，交给引导页决定「开通」还是「复用」。
+          const snapshot = await request('personal-assistant.desktop.status').catch(() => null);
+          if (!cancelled) setBinding(snapshot || { configured: false, reason: 'unavailable', candidates: [] });
+          return;
+        }
         const directory = await request('personal-assistant.bots.list');
         if (directory.directoryAvailable !== true) throw new Error('暂时无法连接云端助理，请稍后重试');
         const botId = resolveAssistantBotId(directory.bots, config.botId || directory.primaryBotId);
@@ -543,13 +776,38 @@ export function PersonalAssistantHome({ request, nativeWorkbench } = {}) {
     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]);
+  const guidance = binding ? unconfiguredGuidance(binding) : null;
+  const runBinding = action => {
+    if (bindingBusy) return;
+    setBindingBusy(action); setError('');
+    void (async () => {
+      try { await request(`personal-assistant.desktop.${action}`); retry(value => value + 1); }
+      catch (reason) { setError(reason?.message || '操作失败，请稍后重试'); }
+      finally { setBindingBusy(''); }
+    })();
+  };
+  if (!scope && guidance) return h('div', { 'data-personal-assistant-onboarding': 'true', style: onboardingStyle.page },
+    h('div', { 'data-window-drag': '', style: { display: 'flex', flexDirection: 'column', gap: 4, alignItems: 'center' } },
+      h('div', { style: onboardingStyle.eyebrow }, '个人助理 · 开通引导'),
+      h('h2', { style: onboardingStyle.title }, guidance.title)),
+    h('p', { style: onboardingStyle.detail }, guidance.detail),
+    h('ol', { style: onboardingStyle.steps },
+      onboardingSteps(guidance.tone).map((text, index) => h('li', { key: text, style: onboardingStyle.step },
+        h('span', { style: onboardingStyle.stepIndex }, String(index + 1)), h('span', null, text)))),
+    h('div', { style: onboardingStyle.actions },
+      guidance.actions.map(action => h('button', {
+        key: action.id, disabled: Boolean(bindingBusy),
+        style: action.primary ? onboardingStyle.primary : onboardingStyle.ghost,
+        onClick: () => action.id === 'check' ? retry(value => value + 1) : runBinding(action.id),
+      }, bindingBusy === action.id ? '处理中…' : action.label))),
+    error ? h('p', { role: 'alert', style: { ...onboardingStyle.notice, color: '#b42318' } }, error) : null);
   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() }));
+  }, h(PersonalAssistantConversation, { React: R, request: scopedRequest, scope, markdown: clientMarkdown, onOpenComputer: () => nativeWorkbench.open() }));
 
 }
 
@@ -618,6 +876,8 @@ export function PersonalAssistantSettings({ request, openComputer = null } = {})
   const [settingsError, setSettingsError] = useState('');
   const [settingsNotice, setSettingsNotice] = useState('');
   const [settingsBusy, setSettingsBusy] = useState(false);
+  const [binding, setBinding] = useState(null);
+  const [bindingBusy, setBindingBusy] = useState('');
 
   const check = useCallback(async () => {
     setChecking(true); setError('');
@@ -625,6 +885,8 @@ export function PersonalAssistantSettings({ request, openComputer = null } = {})
     try {
       const current = await request('personal-assistant.configuration');
       setConfig(current);
+      if (current?.configured) setBinding(null);
+      else setBinding(await request('personal-assistant.desktop.status').catch(() => null));
       if (current?.configured) {
         const directory = await request('personal-assistant.bots.list');
         setBots(Array.isArray(directory?.bots) ? directory.bots : []);
@@ -654,6 +916,14 @@ export function PersonalAssistantSettings({ request, openComputer = null } = {})
     } finally { setChecking(false); }
   }, [request]);
 
+  const runBinding = useCallback(async action => {
+    if (bindingBusy) return;
+    setBindingBusy(action); setError('');
+    try { await request(`personal-assistant.desktop.${action}`); await check(); }
+    catch (reason) { setError(reason?.message || '操作失败，请稍后重试'); }
+    finally { setBindingBusy(''); }
+  }, [bindingBusy, check, request]);
+
   const agentId = config?.agentId || '';
   const canConfirm = Boolean(agentId) && confirmText.trim() === agentId;
   const closeAssistant = useCallback(async () => {
@@ -712,6 +982,17 @@ export function PersonalAssistantSettings({ request, openComputer = null } = {})
   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));
+  const guidance = configured ? null : unconfiguredGuidance(binding);
+  const guidanceCard = guidance ? h('div', { 'data-personal-assistant-onboarding': 'true', style: settingsStyle.card },
+    h('div', { style: { ...settingsStyle.rowFirst, flexDirection: 'column', gap: 8, alignItems: 'stretch' } },
+      h('div', { style: { fontSize: 15, fontWeight: 600 } }, guidance.title),
+      h('div', { style: settingsStyle.note }, guidance.detail),
+      h('div', { style: settingsStyle.actions },
+        guidance.actions.map(action => h('button', {
+          key: action.id, disabled: Boolean(bindingBusy),
+          style: action.primary ? settingsStyle.button : { ...settingsStyle.button, background: 'transparent' },
+          onClick: () => action.id === 'check' ? void check() : void runBinding(action.id),
+        }, bindingBusy === action.id ? '处理中…' : action.label))))) : null;
 
   const envSensitiveStyle = { ...settingsStyle.note, display: 'inline-flex', gap: 4, alignItems: 'center' };
   const envActionsStyle = { ...settingsStyle.actions, marginTop: 6 };
@@ -777,10 +1058,11 @@ export function PersonalAssistantSettings({ request, openComputer = null } = {})
   };
 
   return h('section', { 'data-personal-assistant-settings': 'true', style: settingsStyle.page },
-    h('div', null,
+    h('div', { 'data-window-drag': '' },
       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,
+    guidanceCard,
     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 绑定')),