@kingsoftcloud/agentkit-personal-assistant 0.1.10 → 0.1.13

package/src/client/components/desktop-clipboard.mjs

@@ -57,15 +57,62 @@ export function pasteShortcutEvents() {
   ]);
 }
 
+/**
+ * 云端桌面里的复制快捷键也始终是 Linux 的 Control+C。
+ * 宿主是 macOS 时，页面收到的是 ⌘C，但不能把 Super_L 发给 X11；
+ * Super_L+C 不会触发大多数 Linux 应用的复制动作。
+ */
+export function copyShortcutEvents() {
+  return Object.freeze([
+    Object.freeze({ type: 'key', action: 'down', key: 'Control_L' }),
+    Object.freeze({ type: 'key', action: 'down', key: 'c' }),
+    Object.freeze({ type: 'key', action: 'up', key: 'c' }),
+    Object.freeze({ type: 'key', action: 'up', key: 'Control_L' }),
+  ]);
+}
+
+/**
+ * 等待云桌面处理完 Ctrl+C 再读取 selection。
+ *
+ * X11 selection 是异步的：应用收到按键后才会把内容交给 clipboard owner，
+ * 立即 read 很容易拿到上一次内容，中文通常因此看起来像“乱码/没复制成功”。
+ * 若新内容与旧内容相同，仍在最短等待窗口后接受它，支持用户重复复制同一段文字。
+ */
+export async function readCloudClipboardAfterCopy({ readCloud, beforeText = '', timeoutMs = 1200, settleMs = 180, pollMs = 50, sleep = delay => new Promise(resolve => setTimeout(resolve, delay)), now = Date.now } = {}) {
+  if (typeof readCloud !== 'function') throw clipError('CLIPBOARD_READ_FAILED', '读取云电脑剪贴板失败，请重试');
+  const timeout = Number.isFinite(timeoutMs) && timeoutMs >= 0 ? timeoutMs : 1200;
+  const settle = Number.isFinite(settleMs) && settleMs >= 0 ? settleMs : 180;
+  const poll = Number.isFinite(pollMs) && pollMs > 0 ? pollMs : 50;
+  const clock = typeof now === 'function' ? now : Date.now;
+  const started = Number(clock());
+  let latest = '';
+  while (Number(clock()) - started <= timeout) {
+    const value = await readCloud();
+    latest = clipboardTextOf(value);
+    const elapsed = Number(clock()) - started;
+    if (latest && (latest !== String(beforeText ?? '') || elapsed >= settle)) return { text: latest, changed: latest !== String(beforeText ?? '') };
+    if (elapsed >= timeout) break;
+    await sleep(Math.min(poll, timeout - elapsed));
+  }
+  return { text: latest, changed: latest !== String(beforeText ?? '') };
+}
+
 /** 把云端的错误码翻成用户能照做的中文；英文原文只作为兜底。 */
 export function clipboardFriendlyError(error) {
   const code = String(error?.code || '');
+  if (code === 'COMPUTER_USER_CONTROLLED') return '当前有人正在操作云电脑，请等对方交还后再复制或粘贴';
+  if (code === 'COMPUTER_LEASE_CONFLICT') return '云电脑正在被其他任务使用，请稍后再复制或粘贴';
   if (['COMPUTER_LEASE_REQUIRED', 'DESKTOP_CONTROL_GRANT_REQUIRED', 'DESKTOP_READ_ONLY', 'DESKTOP_CONTROL_EPOCH_CHANGED'].includes(code)) {
     return '需要先点画面接管云电脑，才能读写云端剪贴板';
   }
   if (['DESKTOP_SESSION_IDLE', 'DESKTOP_SESSION_NOT_FOUND', 'CLIPBOARD_CLOSED'].includes(code)) {
     return '云电脑已空闲或断开，请先恢复画面再试';
   }
+  if (code === 'CLIPBOARD_UPGRADE_REQUIRED') return '当前云端版本尚不支持剪贴板，请更新云端助理后重试';
+  if (code === 'CLIPBOARD_CONTROL_REQUIRED') return '需要先接管云电脑，才能读写云端剪贴板';
+  if (code === 'CLIPBOARD_RESPONSE_INVALID') return '云端没有确认剪贴板操作成功，请重试';
+  if (code === 'CLIPBOARD_TIMEOUT') return '云端剪贴板响应超时，请检查连接后重试';
+  if (code === 'CLIPBOARD_UNAVAILABLE') return '云电脑尚未连接，请恢复画面后重试';
   if (code === 'CLIPBOARD_TEXT_TOO_LARGE') return '剪贴板内容超过 64 KiB，云电脑剪贴板放不下';
   if (['DESKTOP_UNAVAILABLE', 'DESKTOP_FRAME_FAILED', 'DESKTOP_SESSION_FAILED'].includes(code)) return '云电脑暂时不可用，请稍后重试';
   if (['CLIPBOARD_FAILED', 'CLOUD_SESSION_FAILED'].includes(code)) return '剪贴板操作失败，请重试';
@@ -86,12 +133,17 @@ const nextRequestId = () => {
  * 云端契约（runtime/desktop-ws.mjs）：
  *   发 `{ type: 'clipboard.read' | 'clipboard.write', requestId, text? }`
  *   收 `{ type: 'clipboard.response', requestId, ok, value | error }`
- * 超时是必需的：旧版云端会直接回 DESKTOP_MESSAGE_UNSUPPORTED（不带 requestId），
- * 没有超时按钮就会一直转圈，所以这里超时即明确提示"云端待更新"。
+ * 旧版云端的 DESKTOP_MESSAGE_UNSUPPORTED 没有 requestId，收到后立即结束
+ * 在途请求；没有任何响应时只报告超时，不凭网络延迟猜测版本。
  */
 export function createClipboardChannel({ send, timeoutMs = 5000, controlEpoch, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
   const pending = new Map();
+  const epochOf = () => {
+    try { return typeof controlEpoch === 'function' ? controlEpoch() : undefined; }
+    catch { return undefined; }
+  };
   const settle = (entry, settleWith) => {
+    if (!entry || !pending.has(entry.id)) return;
     pending.delete(entry.id);
     clearTimer(entry.timer);
     settleWith();
@@ -101,33 +153,46 @@ export function createClipboardChannel({ send, timeoutMs = 5000, controlEpoch, s
     const timer = setTimer(() => {
       const entry = pending.get(id);
       if (!entry) return;
-      settle(entry, () => reject(clipError('CLIPBOARD_TIMEOUT', '云端助理版本较旧，剪贴板通道未启用（重新部署后可用）')));
+      settle(entry, () => reject(clipError('CLIPBOARD_TIMEOUT', '云端剪贴板响应超时，请检查连接后重试')));
     }, timeoutMs);
+    const epoch = epochOf();
     pending.set(id, {
-      id, timer, resolve,
+      id, timer, type, epoch, resolve,
       reject: error => reject(error),
     });
     let sent = false;
     // handoff 会话里云端要求与 input 一样带 controlEpoch；非 handoff 会话会忽略它。
-    let epoch;
-    try { epoch = typeof controlEpoch === 'function' ? controlEpoch() : undefined; }
-    catch { epoch = undefined; }
     try { sent = send({ type, requestId: id, ...(Number.isSafeInteger(epoch) ? { controlEpoch: epoch } : {}), ...extra }) !== false; }
     catch (error) { settle(pending.get(id), () => reject(clipError('CLIPBOARD_UNAVAILABLE', '云电脑尚未连接，剪贴板暂不可用', error))); return; }
     // send() 返回 false 表示 socket 不在 OPEN：立刻失败，别让用户白等 5 秒。
     if (!sent) settle(pending.get(id), () => reject(clipError('CLIPBOARD_UNAVAILABLE', '云电脑尚未连接，剪贴板暂不可用')));
   });
-  return Object.freeze({
+  const channel = Object.freeze({
     read: () => request('clipboard.read').then(value => ({ text: clipboardTextOf(value) })),
-    write: text => request('clipboard.write', { text: String(text) }).then(value => ({ written: value?.written !== false })),
+    write: text => request('clipboard.write', { text: String(text) }).then(() => ({ written: true })),
     /** socket.onmessage 里把 clipboard.response 交给它；返回是否消费了这条消息。 */
     accept(message) {
+      if (message?.type === 'error' && message.code === 'DESKTOP_MESSAGE_UNSUPPORTED' && pending.size > 0) {
+        channel.rejectAll(clipError('CLIPBOARD_UPGRADE_REQUIRED', '当前云端版本尚不支持剪贴板，请更新云端助理后重试'));
+        return true;
+      }
       if (!message || message.type !== 'clipboard.response') return false;
       const entry = pending.get(String(message.requestId || ''));
       if (!entry) return false;
       settle(entry, () => {
-        if (message.ok !== false) entry.resolve(message.value);
-        else entry.reject(clipError(message.error?.code || 'CLIPBOARD_FAILED', message.error?.message || '', message.error));
+        if (Number.isSafeInteger(entry.epoch) && entry.epoch !== epochOf()) {
+          entry.reject(clipError('DESKTOP_CONTROL_EPOCH_CHANGED', '云电脑控制权已改变，本次剪贴板操作未完成')); return;
+        }
+        if (message.ok === false) {
+          entry.reject(clipError(message.error?.code || 'CLIPBOARD_FAILED', message.error?.message || '', message.error)); return;
+        }
+        const valid = entry.type === 'clipboard.read'
+          ? typeof message.value === 'string' || typeof message.value?.text === 'string'
+          : message.value?.written === true;
+        if (message.ok !== true || !valid) {
+          entry.reject(clipError('CLIPBOARD_RESPONSE_INVALID', '云端没有确认剪贴板操作成功，请重试')); return;
+        }
+        entry.resolve(message.value);
       });
       return true;
     },
@@ -137,6 +202,7 @@ export function createClipboardChannel({ send, timeoutMs = 5000, controlEpoch, s
     },
     get size() { return pending.size; },
   });
+  return channel;
 }
 
 /** 画布上的 ⌘V / Ctrl+V 是否该走"本地→云端"的粘贴流程（而不是把按键原样转给云桌面）。 */
@@ -159,14 +225,25 @@ export function isCopyShortcut(event) {
  * 粘贴：本地剪贴板 → 云电脑剪贴板 → 云桌面 Ctrl+V。
  * notify 负责把结果写进面板上的轻提示；返回结构化结果方便调用方/测试断言。
  */
-export async function pasteToCloud({ readLocal, writeCloud, sendKeys, notify = () => {} } = {}) {
+export async function pasteToCloud({ readLocal, writeCloud, sendKeys, ensureControl, notify = () => {} } = {}) {
   const read = readLocal || (() => readLocalClipboard());
   let text = '';
   try { text = await read(); }
   catch (error) { notify(clipboardFriendlyError(error) || '浏览器不允许读取剪贴板，请按 ⌘V / Ctrl+V 再试'); return { ok: false, code: error?.code || 'CLIPBOARD_READ_FAILED' }; }
   if (!text) { notify('本地剪贴板是空的，没有可粘贴的内容'); return { ok: false, code: 'CLIPBOARD_EMPTY' }; }
   if (byteLength(text) > MAX_CLIPBOARD_BYTES) { notify('剪贴板内容超过 64 KiB，云电脑剪贴板放不下'); return { ok: false, code: 'CLIPBOARD_TOO_LARGE' }; }
-  try { await writeCloud(text); }
+  if (typeof ensureControl === 'function') {
+    try {
+      if (!await ensureControl()) { notify('需要先接管云电脑，才能粘贴到云电脑'); return { ok: false, code: 'CLIPBOARD_CONTROL_REQUIRED' }; }
+    } catch (error) {
+      notify(clipboardFriendlyError(error) || '接管云电脑失败，请重试');
+      return { ok: false, code: error?.code || 'CLIPBOARD_CONTROL_REQUIRED' };
+    }
+  }
+  try {
+    const result = await writeCloud(text);
+    if (result?.written !== true) throw clipError('CLIPBOARD_RESPONSE_INVALID', '云端没有确认剪贴板写入成功，请重试');
+  }
   catch (error) { notify(clipboardFriendlyError(error) || '写入云电脑剪贴板失败，请重试'); return { ok: false, code: 'CLIPBOARD_WRITE_FAILED' }; }
   if (typeof sendKeys === 'function') {
     let sent = false;
@@ -180,8 +257,16 @@ export async function pasteToCloud({ readLocal, writeCloud, sendKeys, notify = (
 }
 
 /** 复制：云电脑剪贴板 → 本地剪贴板。 */
-export async function copyCloudClipboard({ readCloud, writeLocal, notify = () => {} } = {}) {
+export async function copyCloudClipboard({ readCloud, writeLocal, ensureControl, notify = () => {} } = {}) {
   const write = writeLocal || (text => writeLocalClipboard(text));
+  if (typeof ensureControl === 'function') {
+    try {
+      if (!await ensureControl()) { notify('需要先接管云电脑，才能复制云电脑内容'); return { ok: false, code: 'CLIPBOARD_CONTROL_REQUIRED' }; }
+    } catch (error) {
+      notify(clipboardFriendlyError(error) || '接管云电脑失败，请重试');
+      return { ok: false, code: error?.code || 'CLIPBOARD_CONTROL_REQUIRED' };
+    }
+  }
   let value;
   try { value = await readCloud(); }
   catch (error) { notify(clipboardFriendlyError(error) || '读取云电脑剪贴板失败，请重试'); return { ok: false, code: 'CLIPBOARD_READ_FAILED' }; }

package/src/client/conversation.mjs

@@ -26,6 +26,33 @@
 
 import { renderMarkdown } from './markdown.mjs';
 
+/**
+ * 宿主 DSH 的 MarkdownText 需要的 chrome 文案（代码块复制/折行、脚注）。
+ * 结构对齐 ui-chat 的 markdownLabels()：缺了 code 会在遇到代码块时直接抛错。
+ */
+const MARKDOWN_LABELS = {
+  code: {
+    copyLabel: '复制',
+    copiedLabel: '已复制',
+    toolbarLabels: { codeLabel: '代码', wrapLabel: '自动换行', unwrapLabel: '取消换行' },
+  },
+  footnotes: '脚注',
+};
+
+/**
+ * 渲染助理消息正文。
+ *
+ * 优先用宿主 DSH 暴露的原生 MarkdownText：micromark 解析 + DSH 原生 .markdown 样式，
+ * 表格、标题层级、代码高亮、链接行为与 DSH 会话一致，插件不再自己维护解析器。
+ * 宿主没有这个模块（老版本）时退回本目录 markdown.mjs 的极简渲染。
+ */
+export function renderAssistantBody(h, text, styles, markdown) {
+  const MarkdownText = markdown?.MarkdownText;
+  const source = typeof text === 'string' ? text : '';
+  if (typeof MarkdownText === 'function') return h(MarkdownText, { text: source, labels: MARKDOWN_LABELS });
+  return renderMarkdown(h, source, styles) || '…';
+}
+
 const EMPTY_HINT = '有什么可以帮你？';
 /** 这两类失败是“消息根本没开始跑”的瞬时状态：云端现在会按会话排队重试，
  * 历史会话里残留的记录不再渲染成任务失败，避免对话结束后一直显示红色失败。 */
@@ -159,6 +186,22 @@ const styles = {
 
 const text = value => (typeof value === 'string' ? value : '');
 
+const SESSION_POINTER_PREFIX = 'agentkit.personal-assistant.current-session.v1';
+const sessionPointerKey = scope => {
+  const agentId = text(scope?.agentId), botId = text(scope?.botId);
+  return agentId && botId ? `${SESSION_POINTER_PREFIX}:${encodeURIComponent(agentId)}:${encodeURIComponent(botId)}` : '';
+};
+const readSessionPointer = key => {
+  if (!key) return '';
+  try { return text(globalThis.localStorage?.getItem(key)); } catch { return ''; }
+};
+const writeSessionPointer = (key, sessionId) => {
+  const value = text(sessionId);
+  if (!key || !value) return;
+  try { globalThis.localStorage?.setItem(key, value); } catch { /* 宿主可能禁用存储，不影响云端会话 */ }
+};
+const sessionFailure = (code, message, status = 503) => Object.assign(new Error(message), { code, status });
+
 /** 与 DSH 原生对话框一致的发送箭头。 */
 const sendGlyph = h => h('svg', { width: 16, height: 16, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 2.2, strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': true },
   h('path', { d: 'M12 19V5M5 12l7-7 7 7' }));
@@ -167,13 +210,17 @@ const plusGlyph = h => h('svg', { width: 15, height: 15, viewBox: '0 0 24 24', f
 const closeGlyph = h => h('svg', { width: 10, height: 10, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 2.4, strokeLinecap: 'round', 'aria-hidden': true },
   h('path', { d: 'M6 6l12 12M18 6L6 18' }));
 
-export function PersonalAssistantConversation({ React: R, request, scope, onOpenComputer = null } = {}) {
+export function PersonalAssistantConversation({ React: R, request, scope, markdown = undefined, onOpenComputer = null } = {}) {
   if (!R) return '个人助理对话尚未就绪，请重新打开';
   const { createElement: h, useCallback, useEffect, useRef, useState } = R;
+  // Hook 依赖稳定身份，避免父组件仅创建新的 scope 对象就重新初始化会话。
+  const pointerKey = sessionPointerKey(scope);
   const [phase, setPhase] = useState('loading');
   const [error, setError] = useState('');
   const [sessions, setSessions] = useState([]);
   const [sessionId, setSessionId] = useState('');
+  const [runtimeInstanceId, setRuntimeInstanceId] = useState('');
+  const [stateStorage, setStateStorage] = useState('');
   const [messages, setMessages] = useState([]);
   const [draft, setDraft] = useState('');
   const [attachments, setAttachments] = useState([]);
@@ -263,8 +310,15 @@ export function PersonalAssistantConversation({ React: R, request, scope, onOpen
     try {
       const snapshot = await call('personal-assistant.session.snapshot', { sessionId: id });
       if (!aliveRef.current || sessionRef.current !== id || generation !== generationRef.current) return;
-      cursorRef.current = Number(snapshot?.cursor) || 0;
-      const history = Array.isArray(snapshot?.messages) ? snapshot.messages : [];
+      if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)
+        || !Array.isArray(snapshot.messages) || !Array.isArray(snapshot.turns)
+        || !Number.isSafeInteger(snapshot.cursor) || snapshot.cursor < 0) {
+        throw sessionFailure('PERSONAL_ASSISTANT_SESSION_SNAPSHOT_INVALID', '云端会话快照格式无效，请重新同步');
+      }
+      setRuntimeInstanceId(text(snapshot?.runtimeInstanceId));
+      setStateStorage(text(snapshot?.stateStorage));
+      cursorRef.current = snapshot.cursor;
+      const history = snapshot.messages;
       setMessages(history.map((message, index) => ({
         id: text(message?.id) || `history-${index}`,
         role: text(message?.role) || 'assistant',
@@ -272,13 +326,37 @@ export function PersonalAssistantConversation({ React: R, request, scope, onOpen
         done: true,
       })));
       setAwaiting(snapshot.turns?.some(turn => ['queued', 'running'].includes(turn.status)) || false);
+      writeSessionPointer(pointerKey, id);
       setPhase('ready');
     } catch (failure) {
       if (!aliveRef.current || generation !== generationRef.current) return;
+      // 找不到快照也可能是重启/状态卷短暂不可见；保留指针，只由显式选择
+      // 或新建成功替换，避免下次初始化把历史缺失误认成首次使用。
       setPhase('error');
       setError(failure?.message || '无法读取会话内容');
     }
-  }, [call]);
+  }, [call, pointerKey]);
+
+  const createSession = useCallback(async () => {
+    if (!aliveRef.current) return;
+    if (sendingRef.current || awaitingRef.current || queueRef.current.length > 0) {
+      setQueueNotice('当前会话还有进行中的任务，请等待完成后再新建会话');
+      return;
+    }
+    setPhase('loading');
+    setError('');
+    try {
+      const created = await call('personal-assistant.session.create', {});
+      const createdId = text(created?.sessionId);
+      if (!createdId) throw sessionFailure('PERSONAL_ASSISTANT_SESSION_CREATE_INVALID', '云端没有返回有效的新会话标识');
+      setSessions(previous => [...previous.filter(row => text(row?.sessionId) !== createdId), { sessionId: createdId, title: text(created?.title) || '新会话' }]);
+      await openSession(createdId);
+    } catch (failure) {
+      if (!aliveRef.current) return;
+      setPhase('error');
+      setError(failure?.message || '新会话创建失败，请重试');
+    }
+  }, [call, openSession]);
 
   const bootstrap = useCallback(async () => {
     setPhase('loading');
@@ -287,20 +365,39 @@ export function PersonalAssistantConversation({ React: R, request, scope, onOpen
     try {
       const listed = await call('personal-assistant.sessions.list');
       if (!aliveRef.current) return;
-      const available = Array.isArray(listed?.sessions) ? listed.sessions : [];
+      if (!Array.isArray(listed?.sessions)) throw sessionFailure('PERSONAL_ASSISTANT_SESSION_LIST_INVALID', '云端会话目录格式无效，请重试');
+      const sessionIds = new Set();
+      if (listed.sessions.some(row => {
+        const id = text(row?.sessionId);
+        if (!row || typeof row !== 'object' || !id || sessionIds.has(id)) return true;
+        sessionIds.add(id);
+        return false;
+      })) {
+        throw sessionFailure('PERSONAL_ASSISTANT_SESSION_LIST_INVALID', '云端会话目录包含无效会话，请重试');
+      }
+      const available = listed.sessions;
+      setRuntimeInstanceId(text(listed.runtimeInstanceId));
+      setStateStorage(text(listed.stateStorage));
       setSessions(available);
-      if (available.length > 0) { await openSession(text(available[0].sessionId)); return; }
-      const created = await call('personal-assistant.session.create', {});
-      if (!aliveRef.current) return;
-      const createdId = text(created?.sessionId);
-      setSessions(createdId ? [{ sessionId: createdId, title: text(created?.title) || '新会话' }] : []);
-      await openSession(createdId);
+      const remembered = readSessionPointer(pointerKey);
+      // 即使目录里还有其他会话，也不能悄悄换过去掩盖当前会话丢失。
+      if (remembered && !available.some(row => text(row.sessionId) === remembered)) {
+        throw sessionFailure('PERSONAL_ASSISTANT_SESSION_STATE_MISSING', '云端历史会话暂时不可见，请检查实例状态后重试，或手动选择会话');
+      }
+      if (available.length > 0) {
+        const selected = available.find(row => text(row.sessionId) === remembered) || available[0];
+        await openSession(text(selected.sessionId));
+        return;
+      }
+      // 有过成功打开的会话却突然拿到空目录，通常是 PVC/状态目录/Bot 范围出了问题。
+      // 不再静默创建一个空会话；用户可以通过头部的“新任务”显式确认创建。
+      await createSession();
     } catch (failure) {
       if (!aliveRef.current) return;
       setPhase('error');
       setError(failure?.message || '会话通道暂时不可用');
     }
-  }, [call, openSession]);
+  }, [call, createSession, openSession, pointerKey]);
 
   useEffect(() => {
     aliveRef.current = true;
@@ -320,23 +417,26 @@ export function PersonalAssistantConversation({ React: R, request, scope, onOpen
       try {
         const page = await call('personal-assistant.session.events', { sessionId, cursor: cursorRef.current });
         if (cancelled) return;
-        cursorRef.current = Number(page?.cursor ?? cursorRef.current) || 0;
-        mergeEvents(page?.events);
-        if (Array.isArray(page.turns)) {
-          setAwaiting(page.turns.some(turn => ['queued', 'running'].includes(turn.status)));
-          const active = page.turns.findLast(turn => ['queued', 'running'].includes(turn.status));
-          const labels = { cloud_computer: '操作云电脑', cloud_workspace: '处理云端文件', cloud_bash: '执行云端命令', cloud_run_code: '运行云端代码', assistant_schedule: '设置云端任务' };
-          const tool = active?.progress?.tool;
-          setProgressText(tool ? `${active.progress.state === 'running' ? '正在' : '已完成'}${labels[tool] || (tool.startsWith('cloud_browser_') ? '操作云端浏览器' : '执行工具')}` : '');
-          const visibleFailures = page.turns
-            .filter(turn => ['failed', 'interrupted', 'cancelled'].includes(turn.status) && !TRANSIENT_TURN_ERRORS.has(String(turn.error || '')))
-            .map(turn => ({ type: 'step', id: `turn-status-${turn.turnId}`, text: `任务${turn.status === 'failed' ? '失败' : '已中断'}：${turnErrorText(turn.error)}` }));
-          mergeEvents(visibleFailures);
+        if (!page || typeof page !== 'object' || Array.isArray(page) || !Array.isArray(page.events)
+          || !Array.isArray(page.turns) || !Number.isSafeInteger(page.cursor)) {
+          throw sessionFailure('PERSONAL_ASSISTANT_SESSION_EVENTS_INVALID', '云端会话增量格式无效，请重新同步');
         }
+        if (page.cursor < cursorRef.current) throw sessionFailure('SESSION_CURSOR_STALE', '会话日志已更新，请重新同步', 409);
+        cursorRef.current = page.cursor;
+        mergeEvents(page.events);
+        setAwaiting(page.turns.some(turn => ['queued', 'running'].includes(turn.status)));
+        const active = page.turns.findLast(turn => ['queued', 'running'].includes(turn.status));
+        const labels = { cloud_computer: '操作云电脑', cloud_workspace: '处理云端文件', cloud_bash: '执行云端命令', cloud_run_code: '运行云端代码', assistant_schedule: '设置云端任务' };
+        const tool = active?.progress?.tool;
+        setProgressText(tool ? `${active.progress.state === 'running' ? '正在' : '已完成'}${labels[tool] || (tool.startsWith('cloud_browser_') ? '操作云端浏览器' : '执行工具')}` : '');
+        const visibleFailures = page.turns
+          .filter(turn => ['failed', 'interrupted', 'cancelled'].includes(turn.status) && !TRANSIENT_TURN_ERRORS.has(String(turn.error || '')))
+          .map(turn => ({ type: 'step', id: `turn-status-${turn.turnId}`, text: `任务${turn.status === 'failed' ? '失败' : '已中断'}：${turnErrorText(turn.error)}` }));
+        mergeEvents(visibleFailures);
         setError('');
       } catch (failure) {
         if (!cancelled) {
-          if (failure.code === 'SESSION_CURSOR_STALE') { void openSession(sessionId); return; }
+          if (failure.code === 'SESSION_CURSOR_STALE' || failure.code === 'PERSONAL_ASSISTANT_SESSION_EVENTS_INVALID') { void openSession(sessionId); return; }
           setError(failure.message || '云端连接中断，正在恢复；任务不会改到本机执行');
         }
       }
@@ -488,13 +588,23 @@ export function PersonalAssistantConversation({ React: R, request, scope, onOpen
     return () => window.removeEventListener('beforeunload', warn);
   }, [queue.length]);
 
-  const header = h('header', { style: styles.header },
+  const sessionScopeTitle = [
+    sessionId ? '当前助理线程已持久化' : '',
+    runtimeInstanceId ? `运行实例 ${runtimeInstanceId}` : '',
+    stateStorage ? `状态 ${stateStorage}` : '',
+  ].filter(Boolean).join(' · ');
+
+  // Studio(macOS) 的拖拽区靠 data-window-drag 标记：PA 页面没有外壳 tab strip，需要自己的头部行。
+  const header = h('header', { style: styles.header, 'data-window-drag': '' },
     h('h1', { style: styles.title }, '个人助理'),
-    h('span', { style: styles.status }, phase === 'ready' ? '云端常驻，关掉窗口也会继续' : phase === 'loading' ? '正在连接…' : '连接不可用'),
+    h('span', { style: styles.status, title: sessionScopeTitle || undefined }, phase === 'ready' ? '云端常驻，关掉窗口也会继续' : phase === 'loading' ? '正在连接…' : '连接不可用'),
     h('span', { style: styles.spacer }),
-    onOpenComputer ? h('button', { type: 'button', onClick: onOpenComputer, 'aria-label': '打开云电脑侧栏', title: '打开或重新打开云电脑侧栏', style: { ...styles.ghost, display: 'inline-flex', alignItems: 'center', gap: 6 } }, h('svg', { width: 16, height: 16, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.6, 'aria-hidden': true }, h('rect', { x: 3, y: 4, width: 18, height: 13, rx: 2 }), h('path', { d: 'M8 21h8M12 17v4' })), '云电脑') : null);
+    // 会话目录是云端恢复/多 Bot 隔离的后台能力，个人助理主界面只保留一条连续线程。
+    // 不把 sessionId 下拉框暴露给用户，避免把基础设施概念变成日常管理负担。
+    h('button', { type: 'button', 'data-window-drag-recall': '', disabled: phase === 'loading' || sending || awaiting || queue.length > 0, onClick: () => void createSession(), 'aria-label': '开始新任务', title: queue.length > 0 ? '请等待排队消息发送后再开始新任务' : '开始一个新的助理任务线程', style: styles.ghost }, '新任务'),
+    onOpenComputer ? h('button', { type: 'button', 'data-window-drag-recall': '', onClick: onOpenComputer, 'aria-label': '打开云电脑侧栏', title: '打开或重新打开云电脑侧栏', style: { ...styles.ghost, display: 'inline-flex', alignItems: 'center', gap: 6 } }, h('svg', { width: 16, height: 16, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.6, 'aria-hidden': true }, h('rect', { x: 3, y: 4, width: 18, height: 13, rx: 2 }), h('path', { d: 'M8 21h8M12 17v4' })), '云电脑') : null);
 
-  return h('section', { 'data-personal-assistant-conversation': 'true', style: styles.page, onClick: async event => {
+  return h('section', { 'data-personal-assistant-conversation': 'true', 'data-agent-id': text(scope?.agentId) || undefined, 'data-bot-id': text(scope?.botId) || undefined, 'data-session-id': sessionId || undefined, 'data-runtime-instance-id': runtimeInstanceId || undefined, 'data-state-storage': stateStorage || undefined, style: styles.page, onClick: async event => {
     const link = event.target.closest?.('a[href^="cloud-file:"]');
     if (!link) return;
     event.preventDefault();
@@ -507,7 +617,9 @@ export function PersonalAssistantConversation({ React: R, request, scope, onOpen
     } catch (failure) { setError(failure.message || '云端文件下载失败'); }
   } }, header,
     h('style', null, '@keyframes pa-awaiting { 0%, 100% { opacity: 0.35 } 50% { opacity: 1 } }'),
-    error && messages.length > 0 ? h('div', { role: 'alert', style: { padding: '8px 16px', background: '#fff0d6' } }, error) : null,
+    error && messages.length > 0 ? h('div', { role: 'alert', style: { padding: '8px 16px', background: '#fff0d6', display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' } },
+      h('span', null, error),
+      sessionId ? h('button', { type: 'button', style: styles.ghost, disabled: phase === 'loading', onClick: () => void openSession(sessionId) }, '重新同步会话') : null) : null,
     h('div', { ref: scrollerRef, 'data-personal-assistant-messages': 'true', style: styles.scroller, onScroll: event => {
       const element = event.currentTarget;
       followLatestRef.current = element.scrollHeight - element.clientHeight - element.scrollTop < 64;
@@ -524,7 +636,7 @@ export function PersonalAssistantConversation({ React: R, request, scope, onOpen
           return h('div', { key: message.id, style: mine ? styles.rowUser : styles.row },
             h('span', { style: styles.who }, mine ? '你' : '助理'),
             h('div', { style: mine ? styles.bubbleUser : styles.bubble },
-              mine ? (message.text || '…') : (renderMarkdown(h, message.text || '', styles) || '…')),
+              mine ? (message.text || '…') : renderAssistantBody(h, message.text, styles, markdown)),
             message.status === 'failed' ? h('button', { onClick: () => void submit(outboxRef.current.get(message.clientTurnId)), disabled: sending }, `${message.failure} · 重试发送`) : null);
         }),
         awaiting ? h('div', { key: 'awaiting', style: styles.row },

package/src/client/desktop-view.mjs

@@ -5,6 +5,12 @@ export const DESKTOP_STREAM_IDLE_MS = 10_000;
 export const DESKTOP_ACTIVE_POLL_MS = 100;
 export const DESKTOP_IDLE_POLL_MS = 1_000;
 export const DESKTOP_MOUSE_HZ = 30;
+/**
+ * 滚轮一个"刻度"对应的像素距离：runtime 把 wheel 的 deltaY 当成刻度数转成
+ * `xdotool click --repeat N`，所以客户端必须先把像素累计成刻度再发。
+ * 鼠标滚轮一格通常 100px 左右（正好 1 次），触控板平滑滚动的碎事件靠累计凑满。
+ */
+export const WHEEL_PIXEL_STEP = 100;
 
 export function normalizeDisplay(display = {}) {
   const width = Number(display.width) || DEFAULT_DESKTOP_DISPLAY.width;
@@ -30,6 +36,22 @@ export function mapDisplayPoint({ clientX, clientY, rect, display = DEFAULT_DESK
   return { x, y };
 }
 
+/**
+ * 把远端桌面按 contain 方式装进可用区域：同时受可用宽、可用高与 maxWidth 约束，
+ * 保证整幅画面（含顶部输入条）永远完整可见，永远不会被容器或滚动位置切掉。
+ * 与 mapDisplayPoint 使用同一套 contain 数学，因此点击映射始终按真实 rect 计算。
+ */
+export function fitDesktopBox({ availableWidth, availableHeight, display = DEFAULT_DESKTOP_DISPLAY, maxWidth = Number.POSITIVE_INFINITY } = {}) {
+  const target = normalizeDisplay(display);
+  const width = Number(availableWidth) > 0 ? Number(availableWidth) : 0;
+  const height = Number(availableHeight) > 0 ? Number(availableHeight) : 0;
+  const cap = Number(maxWidth) > 0 ? Number(maxWidth) : Number.POSITIVE_INFINITY;
+  if (!width || !height) return { width: 0, height: 0 };
+  const boxWidth = Math.min(width, cap, height * (target.width / target.height));
+  const round = value => Math.round(value * 100) / 100;
+  return { width: round(boxWidth), height: round(boxWidth * (target.height / target.width)) };
+}
+
 export function framePayload(frame) {
   if (!frame || typeof frame !== 'object') return null;
   const seq = Number(frame.seq);
@@ -66,3 +88,20 @@ export function isLeaseConflict(error) {
 export function isInputEventWritable({ connected, readOnly } = {}) {
   return Boolean(connected && !readOnly);
 }
+
+/**
+ * 把同一动画帧内的多个原生 wheel 事件合并成一次远端输入。
+ * pending 保存"还不够一格"的像素余数（跨帧保留，触控板碎事件不会丢），
+ * 返回的 clicks 是本次要发的刻度数（0 表示这一帧不用发，省掉一次远端 xdotool）。
+ */
+export function mergeWheel(pending = { x: 0, y: 0 }, { deltaX = 0, deltaY = 0 } = {}, step = WHEEL_PIXEL_STEP) {
+  const size = Number(step) > 0 ? Number(step) : WHEEL_PIXEL_STEP;
+  const x = (Number(pending?.x) || 0) + (Number(deltaX) || 0);
+  const y = (Number(pending?.y) || 0) + (Number(deltaY) || 0);
+  const clicksX = Math.trunc(x / size);
+  const clicksY = Math.trunc(y / size);
+  return {
+    pending: Object.freeze({ x: x - clicksX * size, y: y - clicksY * size }),
+    clicks: Object.freeze({ deltaX: clicksX, deltaY: clicksY }),
+  };
+}

package/src/client/entry.mjs

@@ -1,8 +1,18 @@
-import { apply, inject, setClientReactRuntime } from './index.mjs';
+import { apply, inject, setClientMarkdownRuntime, setClientReactRuntime } from './index.mjs';
+
 window.__ModuleLoader__.load({
   id: '@kingsoftcloud/agentkit-personal-assistant',
   factory: require => {
     setClientReactRuntime(require('react'));
+    // 宿主 DSH 的 ui-primitives 暴露原生 Markdown 渲染器（MarkdownText）；
+    // 老宿主没有这个模块时传 undefined，对话视图自动退回自带极简渲染。
+    let primitives;
+    try {
+      primitives = require('@deepseek-ai/dsh-client-ui-primitives');
+    } catch {
+      primitives = undefined;
+    }
+    setClientMarkdownRuntime(primitives);
     return { name: 'agentkit-personal-assistant', inject, apply };
   },
 });