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

package/src/bot-registry.mjs

@@ -0,0 +1,157 @@
+/**
+ * Multi-Bot registry for one personal-assistant profile.
+ *
+ * The registry owns Bot definitions. The DSH bridge installs each Bot prompt;
+ * its scoped tool guard enforces this registry's current policy on every call.
+ * Native session execution and approval decisions remain owned by DSH.
+ */
+
+const BOT_ID_PATTERN = /^[a-z][a-z0-9._-]{0,63}$/u;
+const PROFILE_PATTERN = /^[a-zA-Z0-9._:-]{1,128}$/u;
+const POLICY_MODES = new Set(['allowlist', 'denylist']);
+
+function requiredString(value, field) {
+  const text = String(value ?? '').trim();
+  if (!text) throw new TypeError(`${field} must be a non-empty string`);
+  return text;
+}
+
+function identifier(value, field, pattern) {
+  const text = requiredString(value, field);
+  if (!pattern.test(text)) throw new TypeError(`${field} has an invalid format`);
+  return text;
+}
+
+function uniqueStrings(value, field) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new TypeError(`${field} must be an array of strings`);
+  const result = [];
+  const seen = new Set();
+  for (const item of value) {
+    const text = requiredString(item, `${field} item`);
+    if (!seen.has(text)) {
+      seen.add(text);
+      result.push(text);
+    }
+  }
+  return result;
+}
+
+function normalizeToolPolicy(policy = {}) {
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
+    throw new TypeError('toolPolicy must be an object');
+  }
+  const mode = policy.mode === undefined ? 'allowlist' : requiredString(policy.mode, 'toolPolicy.mode');
+  if (!POLICY_MODES.has(mode)) throw new TypeError('toolPolicy.mode must be allowlist or denylist');
+  return Object.freeze({
+    mode,
+    allow: Object.freeze(uniqueStrings(policy.allow, 'toolPolicy.allow')),
+    deny: Object.freeze(uniqueStrings(policy.deny, 'toolPolicy.deny')),
+    requireApproval: Object.freeze(uniqueStrings(policy.requireApproval, 'toolPolicy.requireApproval')),
+  });
+}
+
+function freezeDefinition(definition) {
+  return Object.freeze({
+    ...definition,
+    toolPolicy: normalizeToolPolicy(definition.toolPolicy),
+  });
+}
+
+/**
+ * @param {object} input
+ * @param {string} [profileId]
+ * @returns {Readonly<{botId:string,displayName:string,systemPromptRevision:string,systemPrompt?:string,memoryNamespace:string,toolPolicy:object,metadata:object}>}
+ */
+export function normalizeBotDefinition(input = {}, profileId = 'default') {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new TypeError('Bot definition must be an object');
+  const normalizedProfile = identifier(profileId, 'profileId', PROFILE_PATTERN);
+  const botId = identifier(input.botId ?? input.id, 'botId', BOT_ID_PATTERN);
+  const displayName = requiredString(input.displayName ?? input.name ?? botId, 'displayName');
+  const systemPromptRevision = requiredString(input.systemPromptRevision, 'systemPromptRevision');
+  const systemPrompt = input.systemPrompt === undefined ? undefined : requiredString(input.systemPrompt, 'systemPrompt');
+  const agentPreset = input.agentPreset === undefined ? undefined : requiredString(input.agentPreset, 'agentPreset');
+  const memoryNamespace = input.memoryNamespace === undefined
+    ? `assistant:${normalizedProfile}:bot:${botId}`
+    : requiredString(input.memoryNamespace, 'memoryNamespace');
+  const metadata = input.metadata === undefined ? {} : input.metadata;
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) throw new TypeError('metadata must be an object');
+  return freezeDefinition({
+    botId,
+    displayName,
+    systemPromptRevision,
+    ...(systemPrompt === undefined ? {} : { systemPrompt }),
+    ...(agentPreset === undefined ? {} : { agentPreset }),
+    memoryNamespace,
+    toolPolicy: input.toolPolicy ?? {},
+    metadata: Object.freeze({ ...metadata }),
+  });
+}
+
+export class BotRegistry {
+  constructor({ profileId = 'default', bots = [] } = {}) {
+    this.profileId = identifier(profileId, 'profileId', PROFILE_PATTERN);
+    this._bots = new Map();
+    for (const definition of bots) this.register(definition);
+  }
+
+  register(definition) {
+    const bot = normalizeBotDefinition(definition, this.profileId);
+    if (this._bots.has(bot.botId)) throw new Error(`BOT_ALREADY_EXISTS: ${bot.botId}`);
+    this._bots.set(bot.botId, bot);
+    return bot;
+  }
+
+  upsert(definition) {
+    const bot = normalizeBotDefinition(definition, this.profileId);
+    this._bots.set(bot.botId, bot);
+    return bot;
+  }
+
+  get(botId) {
+    const id = identifier(botId, 'botId', BOT_ID_PATTERN);
+    return this._bots.get(id);
+  }
+
+  require(botId) {
+    const bot = this.get(botId);
+    if (!bot) throw new Error(`BOT_NOT_FOUND: ${botId}`);
+    return bot;
+  }
+
+  has(botId) {
+    return this._bots.has(String(botId ?? '').trim());
+  }
+
+  remove(botId) {
+    const id = identifier(botId, 'botId', BOT_ID_PATTERN);
+    return this._bots.delete(id);
+  }
+
+  list() {
+    return [...this._bots.values()];
+  }
+
+  resolve(botId) {
+    const bot = this.require(botId);
+    return {
+      botId: bot.botId,
+      systemPromptRevision: bot.systemPromptRevision,
+      ...(bot.systemPrompt === undefined ? {} : { systemPrompt: bot.systemPrompt }),
+      ...(bot.agentPreset === undefined ? {} : { agentPreset: bot.agentPreset }),
+      memoryNamespace: bot.memoryNamespace,
+      toolPolicy: bot.toolPolicy,
+    };
+  }
+
+  snapshot() {
+    return Object.freeze({
+      profileId: this.profileId,
+      bots: Object.freeze(this.list().map(bot => ({ ...bot, toolPolicy: { ...bot.toolPolicy } }))),
+    });
+  }
+}
+
+export function createBotRegistry(options) {
+  return new BotRegistry(options);
+}

package/src/bot-tool-policy.mjs

@@ -0,0 +1,48 @@
+import { CLOUD_BROWSER_TOOL_NAMES, CLOUD_EXECUTION_TOOL_NAMES, CLOUD_DESKTOP_TOOL_NAMES } from './cloud-computer-tools.mjs';
+
+export const PA_SAFE_TOOL_NAMES = Object.freeze([...CLOUD_BROWSER_TOOL_NAMES, ...CLOUD_EXECUTION_TOOL_NAMES, ...CLOUD_DESKTOP_TOOL_NAMES, 'assistant_schedule', 'bot_memory_search', 'bot_memory_save', 'bot_plan_update']);
+const safe = new Set(PA_SAFE_TOOL_NAMES);
+
+/** deny 优先；空 allowlist 是零权限。任何 Bot 配置都不能扩大固定 PA 安全面。 */
+export function personalAssistantToolDecision(policy, name) {
+  if (!safe.has(name)) return { allowed: false, code: 'PERSONAL_ASSISTANT_HOST_TOOL_FORBIDDEN' };
+  if (!policy || !['allowlist', 'denylist'].includes(policy.mode) || !['allow', 'deny', 'requireApproval'].every(key => Array.isArray(policy[key]) && policy[key].every(value => typeof value === 'string'))) {
+    return { allowed: false, code: 'BOT_TOOL_POLICY_INVALID' };
+  }
+  if (policy.deny.includes(name) || (policy.mode === 'allowlist' && !policy.allow.includes(name))) return { allowed: false, code: 'BOT_TOOL_POLICY_DENIED' };
+  return { allowed: true, requireApproval: policy.requireApproval.includes(name) };
+}
+
+const guidance = {
+  PERSONAL_ASSISTANT_HOST_TOOL_FORBIDDEN: '此工具不属于云电脑或 Bot 私有能力，禁止调用 Host 工具。',
+  BOT_TOOL_POLICY_INVALID: 'Bot 工具策略无效；请由用户检查 mode、allow、deny 和 requireApproval。',
+  BOT_TOOL_POLICY_DENIED: '当前 Bot 的工具策略禁止此调用；请由用户检查该 Bot 的允许/拒绝名单。',
+  BOT_TOOL_APPROVAL_REQUIRED: '当前执行没有一次性宿主批准；请通过宿主批准通道重新发起调用。',
+  BOT_TOOL_APPROVAL_UNAVAILABLE: '宿主批准通道不可用，工具未执行；请配置能够答复此云端会话的真实批准通道后重试。',
+  BOT_TOOL_APPROVAL_REJECTED: '宿主拒绝了本次调用，工具未执行；需要新的明确批准才能重试。',
+  BOT_TOOL_APPROVAL_CANCELLED: '批准请求或工具调用已取消，工具未执行；需要重新发起调用。',
+  BOT_TOOL_APPROVAL_TIMEOUT: '批准请求在 30 秒内没有完成，工具未执行；请连接批准通道后重新发起调用。',
+};
+export const policyReason = code => `${code}: ${guidance[code] || '工具未获授权。'}`;
+export const policyDenial = code => ({ kind: 'deny', reason: policyReason(code), info: { name: 'PersonalAssistantPolicyError', code, reason: guidance[code] } });
+
+/** 只消费真实 DSH approval.request 的闭集结果，超时与取消不能产生授权。 */
+export async function requestBotToolApproval({ agent, execution, approval, timeoutMs = 30_000 }) {
+  if (typeof approval?.request !== 'function') return { granted: false, code: 'BOT_TOOL_APPROVAL_UNAVAILABLE' };
+  if (execution.signal?.aborted) return { granted: false, code: 'BOT_TOOL_APPROVAL_CANCELLED' };
+  const deadline = new AbortController();
+  const signal = execution.signal ? AbortSignal.any([execution.signal, deadline.signal]) : deadline.signal;
+  let timer;
+  const timeout = new Promise(resolve => { timer = setTimeout(() => { deadline.abort(); resolve('timeout'); }, timeoutMs); });
+  let onAbort;
+  const cancelled = execution.signal ? new Promise(resolve => { onAbort = () => resolve('cancelled'); execution.signal.addEventListener('abort', onAbort, { once: true }); }) : undefined;
+  const request = Promise.resolve().then(() => approval.request({ agent: execution.agent || agent, toolName: execution.name,
+    callId: execution.callId, reason: '此 Bot 的 requireApproval 要求当前工具调用获得一次性批准。', signal })).catch(() => 'unavailable');
+  let outcome;
+  try { outcome = await Promise.race([request, timeout, ...(cancelled ? [cancelled] : [])]); }
+  finally { clearTimeout(timer); if (onAbort) execution.signal.removeEventListener('abort', onAbort); }
+  if (deadline.signal.aborted) return { granted: false, code: 'BOT_TOOL_APPROVAL_TIMEOUT' };
+  if (signal.aborted && outcome !== 'timeout') return { granted: false, code: 'BOT_TOOL_APPROVAL_CANCELLED' };
+  if (outcome === 'allowed-once') return { granted: true };
+  return { granted: false, code: ({ rejected: 'BOT_TOOL_APPROVAL_REJECTED', cancelled: 'BOT_TOOL_APPROVAL_CANCELLED', timeout: 'BOT_TOOL_APPROVAL_TIMEOUT' })[outcome] || 'BOT_TOOL_APPROVAL_UNAVAILABLE' };
+}

package/src/bot-tool-scope.mjs

@@ -0,0 +1,40 @@
+import { personalAssistantToolDecision, policyDenial, policyReason, requestBotToolApproval } from './bot-tool-policy.mjs';
+
+/** PA 的唯一工具边界：继承层过滤 + own-layer 服务端守卫 + scoped 模型呈现过滤。 */
+export function restrictPersonalAssistantToolScope(agent, botId, { getPolicy = () => ({ mode: 'allowlist', allow: [], deny: [], requireApproval: [] }), approvalTimeoutMs = 30_000 } = {}) {
+  const tools = agent?.ctx?.get?.('tools');
+  if (typeof tools?.restrict !== 'function' || typeof tools?.guard !== 'function' || typeof agent.ctx.on !== 'function') {
+    throw Object.assign(new Error('Personal Assistant requires scoped tool restrictions and guards'), { code: 'PERSONAL_ASSISTANT_TOOL_SCOPE_UNAVAILABLE', status: 503 });
+  }
+  const granted = new Set();
+  const decide = name => { try { return personalAssistantToolDecision(getPolicy(), name); } catch { return { allowed: false, code: 'BOT_TOOL_POLICY_INVALID' }; } };
+  tools.restrict({ allow: [] });
+  agent.ctx.on('tools/pre-execute', async (execution, next) => {
+    const decision = decide(execution.name);
+    if (!decision.allowed) return policyDenial(decision.code);
+    const upstream = await next();
+    if (upstream.kind === 'deny' || upstream.kind === 'cancel' || !decision.requireApproval) return upstream;
+    if (!['allow', 'ask'].includes(upstream.kind)) return policyDenial('BOT_TOOL_POLICY_INVALID');
+    if (typeof execution.token !== 'symbol') return policyDenial('BOT_TOOL_APPROVAL_REQUIRED');
+    const approval = agent.ctx.get('approval');
+    const result = await requestBotToolApproval({ agent, execution, approval, timeoutMs: approvalTimeoutMs });
+    console.info(JSON.stringify({ event: 'personal-assistant.tool.approval', botId, tool: execution.name, outcome: result.granted ? 'allowed-once' : result.code }));
+    if (!result.granted) return policyDenial(result.code);
+    granted.add(execution.token);
+    // 同一真实批准同时满足已有 ask；不把尚未答复的 ask 转成允许。
+    return { kind: 'allow' };
+  });
+  tools.guard(execution => {
+    const decision = decide(execution.name);
+    const approvedOnce = granted.delete(execution.token);
+    const code = !decision.allowed ? decision.code : decision.requireApproval && !approvedOnce ? 'BOT_TOOL_APPROVAL_REQUIRED' : undefined;
+    if (!code) return undefined;
+    console.warn(JSON.stringify({ event: 'personal-assistant.tool.denied', botId, tool: execution.name, code }));
+    return policyReason(code);
+  });
+  agent.ctx.on('tools/result', execution => { granted.delete(execution.token); });
+  agent.ctx.on('system-prompt/assemble', async (_assembly, _context, next) => {
+    const result = await next();
+    return { ...result, tools: result.tools.filter(tool => decide(tool.name).allowed) };
+  });
+}

package/src/client/bot-directory.mjs

@@ -0,0 +1,23 @@
+/** 仅传输目录展示字段；系统提示词、工具策略与凭据不进入浏览器。 */
+export const DIRECTORY_BOT_ID = '__directory__';
+export function publicBotDirectory(rows) {
+  if (!Array.isArray(rows) || rows.length > 128) throw new TypeError('助理目录格式无效');
+  const seen = new Set();
+  return rows.map(row => {
+    const botId = String(row?.botId || '').trim();
+    const displayName = String(row?.displayName || botId).trim();
+    if (!botId || botId.length > 64 || /[\u0000-\u001f]/u.test(botId) || botId === DIRECTORY_BOT_ID || seen.has(botId) || !displayName || displayName.length > 256) throw new TypeError('助理目录格式无效');
+    seen.add(botId);
+    return { botId, displayName: botId === 'default' && displayName === 'Personal Assistant' ? '默认助理' : botId === 'researcher' && displayName === 'Researcher' ? '研究助理' : displayName };
+  });
+}
+
+/** 系统确定唯一绑定；不把内部逻辑 Bot 变成用户必须选择的产品分类。 */
+export function resolveAssistantBotId(rows, boundBotId = '') {
+  const bots = publicBotDirectory(rows);
+  const bound = String(boundBotId || '').trim();
+  const selected = bound ? bots.find(bot => bot.botId === bound)
+    : bots.find(bot => bot.botId === 'default') || (bots.length === 1 ? bots[0] : undefined);
+  if (!selected) throw Object.assign(new Error('云端助理绑定尚未就绪，请稍后重试'), { code: 'PERSONAL_ASSISTANT_BINDING_UNAVAILABLE' });
+  return selected.botId;
+}

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

@@ -0,0 +1,194 @@
+/**
+ * 云电脑剪贴板：本地 ⇄ 云端的两个可见入口。
+ *
+ * 云端桌面是 Linux（Xvfb + fluxbox），宿主可能是 macOS，所以「粘贴」永远是两步：
+ *   1) 读**本地**剪贴板（navigator.clipboard.readText，浏览器可能直接拒绝）；
+ *   2) 写**云电脑**剪贴板（computer.action / clipboard.write），再向云桌面合成一次
+ *      **Ctrl+V**（不是 ⌘V）——云桌面不认识 macOS 的 Command 键。
+ * 「复制」方向相反：读云电脑剪贴板 → 写本地剪贴板。
+ *
+ * 所有外部能力都从 props 注入（readCloud / writeCloud / sendKeys），因此这个模块既能被
+ * 面板直接渲染，也能在 Node 测试里跑真实的编排逻辑，不需要浏览器环境。
+ */
+
+/** 云端 desktop-session 的剪贴板上限是 64 KiB，客户端先拦一次，避免发一半才 413。 */
+export const MAX_CLIPBOARD_BYTES = 64 * 1024;
+
+const clipError = (code, message, cause) => Object.assign(new Error(message), { code, cause });
+
+const byteLength = value => {
+  try { return new TextEncoder().encode(value).length; }
+  catch { return value.length; }
+};
+
+/** clipboardRead() 兼容 `{ text }` 与裸字符串两种返回。 */
+export const clipboardTextOf = value => (typeof value === 'string' ? value : String(value?.text ?? ''));
+
+/** 读本地剪贴板：非安全上下文 / 未授权时浏览器会抛错，必须换成用户能懂的提示。 */
+export async function readLocalClipboard({ clipboard } = {}) {
+  const api = clipboard || globalThis.navigator?.clipboard;
+  if (!api || typeof api.readText !== 'function') throw clipError('CLIPBOARD_UNAVAILABLE', '当前环境不允许读取剪贴板，请点「粘贴」按钮再试');
+  try {
+    const text = await api.readText();
+    return typeof text === 'string' ? text : '';
+  } catch (error) {
+    throw clipError('CLIPBOARD_READ_DENIED', '浏览器不允许读取剪贴板，请按 ⌘V / Ctrl+V 再试', error);
+  }
+}
+
+/** 写本地剪贴板：同样要兜住浏览器拒绝（页面失焦、权限被拒都会走到这里）。 */
+export async function writeLocalClipboard(text, { clipboard } = {}) {
+  const api = clipboard || globalThis.navigator?.clipboard;
+  if (!api || typeof api.writeText !== 'function') throw clipError('CLIPBOARD_UNAVAILABLE', '当前环境不允许写入剪贴板，请手动复制');
+  try { await api.writeText(String(text ?? '')); }
+  catch (error) { throw clipError('CLIPBOARD_WRITE_DENIED', '浏览器不允许写入剪贴板，请重试', error); }
+}
+
+/**
+ * 云桌面里的粘贴快捷键：Linux 桌面要 Control_L + v。
+ * 无论宿主是 macOS 还是 Windows，最终发给云端的都是这组 X11 keysym。
+ */
+export function pasteShortcutEvents() {
+  return Object.freeze([
+    Object.freeze({ type: 'key', action: 'down', key: 'Control_L' }),
+    Object.freeze({ type: 'key', action: 'down', key: 'v' }),
+    Object.freeze({ type: 'key', action: 'up', key: 'v' }),
+    Object.freeze({ type: 'key', action: 'up', key: 'Control_L' }),
+  ]);
+}
+
+/** 把云端的错误码翻成用户能照做的中文；英文原文只作为兜底。 */
+export function clipboardFriendlyError(error) {
+  const code = String(error?.code || '');
+  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_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 '剪贴板操作失败，请重试';
+  if (code === 'CLIPBOARD_TEXT_INVALID') return '剪贴板内容格式不被云端接受，请重试';
+  if (error?.message) return String(error.message);
+  return code ? `剪贴板操作失败（${code}）` : '剪贴板操作失败，请重试';
+}
+
+let requestSequence = 0;
+const nextRequestId = () => {
+  const random = globalThis.crypto?.randomUUID?.();
+  return random ? `clip-${random}` : `clip-${Date.now().toString(36)}-${(requestSequence += 1)}`;
+};
+
+/**
+ * 云电脑桌面 WS 上的剪贴板请求通道（一个连接一个实例）。
+ *
+ * 云端契约（runtime/desktop-ws.mjs）：
+ *   发 `{ type: 'clipboard.read' | 'clipboard.write', requestId, text? }`
+ *   收 `{ type: 'clipboard.response', requestId, ok, value | error }`
+ * 超时是必需的：旧版云端会直接回 DESKTOP_MESSAGE_UNSUPPORTED（不带 requestId），
+ * 没有超时按钮就会一直转圈，所以这里超时即明确提示"云端待更新"。
+ */
+export function createClipboardChannel({ send, timeoutMs = 5000, controlEpoch, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+  const pending = new Map();
+  const settle = (entry, settleWith) => {
+    pending.delete(entry.id);
+    clearTimer(entry.timer);
+    settleWith();
+  };
+  const request = (type, extra) => new Promise((resolve, reject) => {
+    const id = nextRequestId();
+    const timer = setTimer(() => {
+      const entry = pending.get(id);
+      if (!entry) return;
+      settle(entry, () => reject(clipError('CLIPBOARD_TIMEOUT', '云端助理版本较旧，剪贴板通道未启用（重新部署后可用）')));
+    }, timeoutMs);
+    pending.set(id, {
+      id, timer, 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({
+    read: () => request('clipboard.read').then(value => ({ text: clipboardTextOf(value) })),
+    write: text => request('clipboard.write', { text: String(text) }).then(value => ({ written: value?.written !== false })),
+    /** socket.onmessage 里把 clipboard.response 交给它；返回是否消费了这条消息。 */
+    accept(message) {
+      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));
+      });
+      return true;
+    },
+    /** 连接断开/关闭时把在途请求全部失败掉，避免按钮永远转圈。 */
+    rejectAll(error = clipError('CLIPBOARD_CLOSED', '云电脑连接已断开，剪贴板操作未完成')) {
+      for (const entry of [...pending.values()]) settle(entry, () => entry.reject(error));
+    },
+    get size() { return pending.size; },
+  });
+}
+
+/** 画布上的 ⌘V / Ctrl+V 是否该走"本地→云端"的粘贴流程（而不是把按键原样转给云桌面）。 */
+export function isPasteShortcut(event) {
+  if (!event || String(event.key ?? '').toLowerCase() !== 'v') return false;
+  if (event.altKey || event.shiftKey) return false;
+  if (event.isComposing || event.nativeEvent?.isComposing) return false;
+  return event.metaKey === true || event.ctrlKey === true;
+}
+
+/** ⌘C / Ctrl+C：把云电脑剪贴板内容取回本地（面板不再放按钮，只用快捷键）。 */
+export function isCopyShortcut(event) {
+  if (!event || String(event.key ?? '').toLowerCase() !== 'c') return false;
+  if (event.altKey || event.shiftKey) return false;
+  if (event.isComposing || event.nativeEvent?.isComposing) return false;
+  return event.metaKey === true || event.ctrlKey === true;
+}
+
+/**
+ * 粘贴：本地剪贴板 → 云电脑剪贴板 → 云桌面 Ctrl+V。
+ * notify 负责把结果写进面板上的轻提示；返回结构化结果方便调用方/测试断言。
+ */
+export async function pasteToCloud({ readLocal, writeCloud, sendKeys, 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); }
+  catch (error) { notify(clipboardFriendlyError(error) || '写入云电脑剪贴板失败，请重试'); return { ok: false, code: 'CLIPBOARD_WRITE_FAILED' }; }
+  if (typeof sendKeys === 'function') {
+    let sent = false;
+    try { sent = sendKeys(pasteShortcutEvents()) !== false; }
+    catch (error) { return { ok: true, code: 'CLIPBOARD_KEY_FAILED', error }; }
+    // 只读旁观时输入通道拒发按键：内容已到云端剪贴板，但要明确告诉用户还差接管这一步。
+    if (!sent) { notify('已写入云电脑剪贴板，但当前没有控制权；接管云电脑后再按 Ctrl+V'); return { ok: true, code: 'CLIPBOARD_KEY_NOT_SENT' }; }
+  }
+  notify('已粘贴到云电脑');
+  return { ok: true };
+}
+
+/** 复制：云电脑剪贴板 → 本地剪贴板。 */
+export async function copyCloudClipboard({ readCloud, writeLocal, notify = () => {} } = {}) {
+  const write = writeLocal || (text => writeLocalClipboard(text));
+  let value;
+  try { value = await readCloud(); }
+  catch (error) { notify(clipboardFriendlyError(error) || '读取云电脑剪贴板失败，请重试'); return { ok: false, code: 'CLIPBOARD_READ_FAILED' }; }
+  const text = clipboardTextOf(value);
+  if (!text) { notify('云电脑剪贴板是空的，没有可复制的内容'); return { ok: false, code: 'CLIPBOARD_EMPTY' }; }
+  try { await write(text); }
+  catch (error) { notify(clipboardFriendlyError(error) || '浏览器不允许写入剪贴板，请重试'); return { ok: false, code: 'CLIPBOARD_WRITE_FAILED' }; }
+  notify('已复制到本地');
+  return { ok: true, text };
+}