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

package/src/client/markdown.mjs

@@ -0,0 +1,130 @@
+/**
+ * 极简 Markdown 渲染：只覆盖模型回答里真正常见的语法，不引入第三方依赖。
+ *
+ * 支持：围栏代码块、行内代码、粗体、斜体、链接、无序/有序列表、引用、标题、
+ * 分隔线、段落内换行。已知限制：不解析表格、嵌套列表、HTML（一律按文本转义显示）。
+ */
+
+const FENCE = /^```\s*([\w+#.-]*)\s*$/u;
+const HEADING = /^(#{1,6})\s+(.*)$/u;
+const UL = /^\s*[-*+]\s+(.*)$/u;
+const OL = /^\s*(\d{1,3})[.)]\s+(.*)$/u;
+const QUOTE = /^\s*>\s?(.*)$/u;
+const RULE = /^\s*([-*_])\s*(?:\1\s*){2,}$/u;
+
+/** 把 Markdown 源码切成块；纯函数，方便单测。 */
+export function parseMarkdown(source) {
+  const text = typeof source === 'string' ? source.replace(/\r\n?/gu, '\n') : '';
+  const lines = text.split('\n');
+  const blocks = [];
+  let index = 0;
+  const flushParagraph = buffer => {
+    if (buffer.length === 0) return;
+    blocks.push({ type: 'paragraph', text: buffer.join('\n') });
+    buffer.length = 0;
+  };
+  const paragraph = [];
+  while (index < lines.length) {
+    const line = lines[index];
+    const fence = FENCE.exec(line);
+    if (fence) {
+      flushParagraph(paragraph);
+      const body = [];
+      index += 1;
+      while (index < lines.length && !/^```\s*$/u.test(lines[index])) { body.push(lines[index]); index += 1; }
+      index += 1; // 跳过收尾围栏（缺失时按到文末处理）
+      blocks.push({ type: 'code', lang: fence[1] || '', text: body.join('\n') });
+      continue;
+    }
+    if (line.trim() === '') { flushParagraph(paragraph); index += 1; continue; }
+    const heading = HEADING.exec(line);
+    if (heading) {
+      flushParagraph(paragraph);
+      blocks.push({ type: 'heading', level: heading[1].length, text: heading[2].trim() });
+      index += 1; continue;
+    }
+    if (RULE.test(line)) { flushParagraph(paragraph); blocks.push({ type: 'rule' }); index += 1; continue; }
+    const quote = QUOTE.exec(line);
+    if (quote) {
+      flushParagraph(paragraph);
+      const body = [quote[1]];
+      index += 1;
+      while (index < lines.length && QUOTE.test(lines[index])) { body.push(QUOTE.exec(lines[index])[1]); index += 1; }
+      blocks.push({ type: 'quote', text: body.join('\n') });
+      continue;
+    }
+    const bullet = UL.exec(line), ordered = OL.exec(line);
+    if (bullet || ordered) {
+      flushParagraph(paragraph);
+      const list = { type: ordered ? 'ordered' : 'unordered', items: [], start: ordered ? Number(ordered[1]) : 1 };
+      while (index < lines.length) {
+        const current = UL.exec(lines[index]), numbered = OL.exec(lines[index]);
+        if (!current && !numbered) break;
+        list.items.push((current ? current[1] : numbered[2]).trim());
+        index += 1;
+      }
+      blocks.push(list);
+      continue;
+    }
+    paragraph.push(line);
+    index += 1;
+  }
+  flushParagraph(paragraph);
+  return blocks;
+}
+
+/** 行内语法：先按转义字符切分，再逐段套用 `code` / **bold** / *italic* / [text](url)。 */
+export function parseInline(source) {
+  const text = typeof source === 'string' ? source : '';
+  const nodes = [];
+  const pushText = value => { if (value) nodes.push({ type: 'text', text: value }); };
+  let rest = text;
+  while (rest.length > 0) {
+    const code = /^`([^`]+)`/u.exec(rest);
+    if (code) { nodes.push({ type: 'code', text: code[1] }); rest = rest.slice(code[0].length); continue; }
+    const bold = /^\*\*([^*\n]+)\*\*/u.exec(rest) || /^__([^_\n]+)__/u.exec(rest);
+    if (bold) { nodes.push({ type: 'strong', text: bold[1] }); rest = rest.slice(bold[0].length); continue; }
+    const italic = /^\*([^*\s][^*\n]*)\*/u.exec(rest) || /^_([^_\s][^_\n]*)_/u.exec(rest);
+    if (italic) { nodes.push({ type: 'em', text: italic[1] }); rest = rest.slice(italic[0].length); continue; }
+    const link = /^\[([^\]]+)\]\(([^)\s]+)\)/u.exec(rest);
+    if (link) { nodes.push({ type: 'link', text: link[1], href: link[2] }); rest = rest.slice(link[0].length); continue; }
+    const next = rest.slice(1).search(/[`*_[\]\n]/u);
+    const take = next < 0 ? rest.length : next + 1;
+    pushText(rest.slice(0, take));
+    rest = rest.slice(take);
+  }
+  // 相邻纯文本合并，避免不成对的 * / _ 被切成多个片段（渲染结果等价，便于断言与调试）。
+  return nodes.reduce((merged, node) => {
+    const last = merged[merged.length - 1];
+    if (node.type === 'text' && last && last.type === 'text') merged[merged.length - 1] = { type: 'text', text: last.text + node.text };
+    else merged.push(node);
+    return merged;
+  }, []);
+}
+
+/** 渲染为 React 元素树；`h` 是 createElement，`styles` 由视图传入。 */
+export function renderMarkdown(h, source, styles = {}) {
+  const blocks = parseMarkdown(source);
+  if (blocks.length === 0) return null;
+  const inline = (text, keyPrefix) => parseInline(text).map((node, order) => {
+    const key = `${keyPrefix}-i${order}`;
+    if (node.type === 'code') return h('code', { key, style: styles.inlineCode }, node.text);
+    if (node.type === 'strong') return h('strong', { key }, node.text);
+    if (node.type === 'em') return h('em', { key }, node.text);
+    if (node.type === 'link') return /^(https?:|mailto:|cloud-file:)/iu.test(node.href) ? h('a', { key, href: node.href, target: '_blank', rel: 'noreferrer noopener', style: styles.link }, node.text) : h('span', { key }, node.text);
+    return h('span', { key }, node.text);
+  });
+  return blocks.map((block, order) => {
+    const key = `b${order}`;
+    if (block.type === 'code') return h('pre', { key, style: styles.codeBlock }, h('code', null, block.text));
+    if (block.type === 'heading') return h('div', { key, style: { ...styles.heading, ...(block.level <= 2 ? styles.headingStrong : null) } }, inline(block.text, key));
+    if (block.type === 'rule') return h('hr', { key, style: styles.rule });
+    if (block.type === 'quote') return h('blockquote', { key, style: styles.quote }, inline(block.text, key));
+    if (block.type === 'unordered' || block.type === 'ordered') {
+      const tag = block.type === 'ordered' ? 'ol' : 'ul';
+      return h(tag, { key, style: styles.list, start: block.type === 'ordered' && block.start !== 1 ? block.start : undefined },
+        block.items.map((item, position) => h('li', { key: `${key}-l${position}` }, inline(item, `${key}-l${position}`))));
+    }
+    return h('p', { key, style: styles.paragraph }, inline(block.text, key));
+  });
+}

package/src/client/native-workbench.mjs

@@ -0,0 +1,62 @@
+/** 云电脑只注册原生 DSH 右侧栏内容，不拥有布局、全屏或本地执行会话。 */
+export const ASSISTANT_COMPUTER_KIND = 'personal-assistant-computer';
+export const ASSISTANT_PANEL_ID = 'personal-assistant';
+const unavailableReason = '当前 Studio 的原生侧栏组件需要更新，请安装本次随插件提供的宿主组件包。';
+const unavailable = () => Object.assign(new Error(unavailableReason), { code: 'PERSONAL_ASSISTANT_NATIVE_SIDEBAR_REQUIRED' });
+
+function ComputerTab(props) { return props.workbench.render(props); }
+
+export function createAssistantWorkbench({ sidebarRight, slots, panelId = ASSISTANT_PANEL_ID } = {}) {
+  const available = typeof sidebarRight?.registerPanelSurface === 'function'
+    && typeof sidebarRight?.openPanelTab === 'function' && typeof sidebarRight?.setPanelExpanded === 'function'
+    && typeof slots?.inject === 'function' && typeof slots?.register === 'function';
+  const listeners = new Set();
+  let binding, disposed = false;
+  let snapshot = Object.freeze({ binding: undefined });
+  const emit = () => { snapshot = Object.freeze({ binding }); for (const listener of [...listeners]) listener(); };
+  const requireAvailable = () => {
+    if (!available) throw unavailable();
+    if (disposed) throw new Error('云电脑工作面板已关闭');
+  };
+  let releaseSurface, releaseTab;
+  const api = {
+    available, unavailableReason: available ? null : unavailableReason,
+    subscribe: listener => { listeners.add(listener); return () => listeners.delete(listener); },
+    getSnapshot: () => snapshot,
+    bind(scope, request) {
+      requireAvailable();
+      if (!scope?.agentId || !scope?.botId || typeof request !== 'function') throw new Error('云端助理尚未连接');
+      const changed = binding && (binding.scope.agentId !== scope.agentId || binding.scope.botId !== scope.botId);
+      if (changed) { releaseSurface(); releaseSurface = sidebarRight.registerPanelSurface(panelId); }
+      binding = Object.freeze({ scope: Object.freeze({ ...scope }), request }); emit();
+      api.open();
+    },
+    open() {
+      requireAvailable();
+      if (binding) sidebarRight.openPanelTab(panelId, ASSISTANT_COMPUTER_KIND);
+    },
+    collapse() { requireAvailable(); sidebarRight.setPanelExpanded(panelId, false); },
+    dispose() {
+      if (disposed) return;
+      disposed = true; releaseTab?.(); releaseSurface?.(); listeners.clear();
+    },
+  };
+  if (available) {
+    releaseSurface = sidebarRight.registerPanelSurface(panelId);
+    releaseTab = slots.inject('sidebar.right.panel.tab', () => slots.register({
+      name: 'sidebar.right.panel.tab', key: ASSISTANT_COMPUTER_KIND, inject: () => ({ workbench: api }),
+    }, ComputerTab));
+  }
+  return api;
+}
+
+/** 仅渲染已授权原生 tab 的内容；窗口与全屏均归 DSH 所有。 */
+export function AssistantNativeRightbar({ React: R, workbench, Panel, active = true, fullscreen = false }) {
+  const { createElement: h, useSyncExternalStore } = R;
+  const value = useSyncExternalStore(workbench.subscribe, workbench.getSnapshot, workbench.getSnapshot);
+  if (!active || !value.binding) return null;
+  const { scope, request } = value.binding;
+  return h(Panel, { key: `${scope.agentId}:${scope.botId}:${scope.sessionId || ''}`,
+    request, initialBotId: scope.botId, initialSessionId: scope.sessionId, agentId: scope.agentId,
+    variant: 'native-tab', active, nativeFullscreen: fullscreen });
+}

package/src/cloud-computer-tools.mjs

@@ -0,0 +1,245 @@
+/**
+ * DSH tool adapters for the dedicated Cloud Computer.
+ *
+ * The Personal Assistant runtime never opens Chromium or executes a host
+ * command itself. Every browser/terminal operation crosses the versioned
+ * Computer Broker protocol and is bound to one Bot task lease. The computer
+ * image owns `computer-agentd`, Chromium/CDP and the terminal sandbox.
+ */
+import {
+  COMPUTER_ACTION_NAMES,
+  createActionRequest,
+  createLeaseRequest,
+  createReleaseRequest,
+} from './computer-broker-protocol.mjs';
+import { createDesktopTool } from './desktop-tools.mjs';
+import { createWorkspaceTool } from './workspace-tools.mjs';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+export const PERSONAL_ASSISTANT_BROWSER_CAPABILITY = 'personal-assistant-browser/v1';
+export const PERSONAL_ASSISTANT_CODE_EXECUTION_CAPABILITY = 'personal-assistant-code-execution/v1';
+export const CLOUD_COMPUTER_CAPABILITY = 'cloud-computer/v1';
+export const COMPUTER_AGENTD_CONTRACT = 'computer-agentd';
+export const COMPUTER_BROKER_URL_ENV = 'COMPUTER_BROKER_URL';
+// computer-agentd owns the real Chromium/CDP process and the terminal
+// executor. These explicit contracts keep capability discovery tied to the
+// implementation instead of to a capability-name string alone.
+export const CLOUD_BROWSER_BACKEND = Object.freeze({ engine: 'chromium', protocol: 'cdp', owner: COMPUTER_AGENTD_CONTRACT });
+export const CLOUD_EXECUTION_BACKEND = Object.freeze({ command: 'runCommand', code: 'executeCode', owner: COMPUTER_AGENTD_CONTRACT });
+
+export const CLOUD_BROWSER_TOOL_NAMES = Object.freeze([
+  'cloud_browser_open',
+  'cloud_browser_snapshot',
+  'cloud_browser_click',
+  'cloud_browser_type',
+  'cloud_browser_press',
+  'cloud_browser_screenshot',
+  'cloud_browser_download',
+  'cloud_browser_close',
+]);
+export const CLOUD_EXECUTION_TOOL_NAMES = Object.freeze(['cloud_bash', 'cloud_run_code']);
+export const CLOUD_DESKTOP_TOOL_NAMES = Object.freeze(['cloud_computer', 'cloud_workspace']);
+
+const CODE_LANGUAGES = Object.freeze(['javascript', 'python']);
+const KEY_ALLOWLIST = Object.freeze([
+  'Enter', 'Tab', 'Escape', 'Backspace', 'Delete', 'ArrowUp', 'ArrowDown',
+  'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown', 'Space',
+]);
+const ACTIONS = new Set(COMPUTER_ACTION_NAMES);
+const text = (value, field) => {
+  const result = String(value ?? '').trim();
+  if (!result) throw new TypeError(`${field} must be a non-empty string`);
+  return result;
+};
+const bounded = (value, field, maxBytes) => {
+  const result = text(value, field);
+  if (Buffer.byteLength(result, 'utf8') > maxBytes) throw new TypeError(`${field} exceeds ${maxBytes} bytes`);
+  return result;
+};
+const taskIdOf = (value) => bounded(value ?? 'interactive', 'taskId', 128);
+const output = value => [{ type: 'text', text: String(value?.result || '') }];
+const resultSchema = { type: 'object', properties: { result: { type: 'string' } }, required: ['result'] };
+const envelope = value => ({ result: typeof value === 'string' ? value : JSON.stringify(value) ?? '' });
+const schema = (properties = {}, required = []) => ({
+  type: 'object', properties, required, additionalProperties: false,
+});
+
+function actionDefinition(name, description, properties, required, operation, operationExecutor, mapArgs = args => ({ ...args })) {
+  return {
+    name,
+    description,
+    parameters: schema(properties, required),
+    output: { schema: resultSchema, render: (_args, value) => output(value) },
+    execute: async (args, execution) => envelope(await operationExecutor(operation, mapArgs(args || {}), execution)),
+  };
+}
+
+/**
+ * Create broker-backed tools for one Bot. A lease is acquired lazily on the
+ * first action, so simply loading the plugin cannot claim a user's computer.
+ */
+export function createComputerToolset({
+  broker,
+  userId,
+  assistantId,
+  botId,
+  computerId,
+  taskId = 'interactive',
+  leaseTtlMs = 60_000,
+  now = () => Date.now(),
+  agent,
+} = {}) {
+  if (!broker || typeof broker.action !== 'function' || typeof broker.acquireLease !== 'function' || typeof broker.renewLease !== 'function') {
+    throw new TypeError('A connected Computer Broker client is required');
+  }
+  const identity = {
+    ...(userId === undefined ? {} : { userId: text(userId, 'userId') }),
+    assistantId: text(assistantId, 'assistantId'),
+    botId: text(botId, 'botId'),
+    computerId: text(computerId, 'computerId'),
+  };
+  const initialTaskId = taskIdOf(taskId);
+  let activeLease = null;
+  let disposed = false;
+
+  async function ensureLease(requestedTaskId = initialTaskId, signal) {
+    if (disposed) throw new Error('COMPUTER_TOOLSET_DISPOSED');
+    const activeTaskId = taskIdOf(requestedTaskId);
+    // 即使本地缓存未过期，也向 Broker 幂等确认一次；用户可能已经接管了旧租约。
+    if (activeLease && (activeLease.taskId !== activeTaskId || activeLease.expiresAt <= now())) await release().catch(() => {});
+    const idempotencyKey = `${identity.assistantId}:${identity.botId}:${identity.computerId}:${activeTaskId}`;
+    const deadline = Date.now() + 120000;
+    let response;
+    for (;;) {
+      signal?.throwIfAborted();
+      if (disposed) throw new Error('COMPUTER_TOOLSET_DISPOSED');
+      try { response = await broker.acquireLease(createLeaseRequest({ ...identity, taskId: activeTaskId, idempotencyKey, ttlMs: leaseTtlMs })); break; }
+      catch (error) {
+        if (error?.code !== 'COMPUTER_USER_CONTROLLED' || Date.now() >= deadline) throw error;
+        activeLease = null;
+        // 只等待取得新租约，不重放已经开始或结果未知的输入。
+        await sleep(500, undefined, { signal });
+      }
+    }
+    const lease = response?.lease;
+    if (!lease?.leaseId) throw new Error('COMPUTER_LEASE_INVALID');
+    activeLease = lease;
+    return lease;
+  }
+
+  async function release() {
+    if (!activeLease) return false;
+    const lease = activeLease;
+    activeLease = null;
+    const response = await broker.releaseLease(createReleaseRequest({ ...identity, taskId: lease.taskId, leaseId: lease.leaseId, botId: identity.botId }));
+    return response?.released === true;
+  }
+
+  async function action(name, args = {}, execution = {}) {
+    if (!ACTIONS.has(name)) throw new TypeError(`Unsupported computer action: ${name}`);
+    const lease = await ensureLease(execution?.taskId, execution?.signal);
+    const request = createActionRequest({
+      ...identity,
+      taskId: lease.taskId,
+      leaseId: lease.leaseId,
+      action: name,
+      args,
+    });
+    const cancellation = new AbortController();
+    const signal = execution.signal ? AbortSignal.any([execution.signal, cancellation.signal]) : cancellation.signal;
+    let renewing = false, heartbeat;
+    const renew = async () => {
+      if (disposed) throw new Error('COMPUTER_TOOLSET_DISPOSED');
+      const response = await broker.renewLease({ ...identity, taskId: lease.taskId, leaseId: lease.leaseId, ttlMs: leaseTtlMs }, { signal });
+      if (response?.lease?.leaseId !== lease.leaseId) throw new Error('COMPUTER_LEASE_INVALID');
+      if (activeLease?.leaseId === lease.leaseId) activeLease = response.lease;
+    };
+    try {
+      signal.throwIfAborted();
+      await renew();
+      signal.throwIfAborted();
+      heartbeat = setInterval(() => {
+        if (renewing || signal.aborted) return;
+        renewing = true;
+        void renew().catch(error => cancellation.abort(error)).finally(() => { renewing = false; });
+      }, Math.max(50, Math.min(20_000, Math.floor(leaseTtlMs / 3))));
+      heartbeat.unref?.();
+      return await broker.action(request, { signal });
+    }
+    catch (error) {
+      // 旧租约已被用户接管或撤销。只清缓存，不重放可能已经执行的动作。
+      if (Number(error?.status) === 409) activeLease = null;
+      throw error;
+    }
+    finally { clearInterval(heartbeat); cancellation.abort(new Error('COMPUTER_ACTION_FINISHED')); }
+  }
+
+  const definitions = [
+    createDesktopTool({ action, agent }),
+    createWorkspaceTool({ action }),
+    actionDefinition('cloud_browser_open', 'Open a public URL in the dedicated Cloud Computer browser.', { url: { type: 'string' } }, ['url'], 'open', action, args => ({ url: bounded(args.url, 'url', 4096) })),
+    actionDefinition('cloud_browser_snapshot', 'Read bounded text and links from the current Cloud Computer page.', {}, [], 'snapshot', action),
+    actionDefinition('cloud_browser_click', 'Click a CSS selector in the Cloud Computer browser.', { selector: { type: 'string' } }, ['selector'], 'click', action, args => ({ selector: bounded(args.selector, 'selector', 1024) })),
+    actionDefinition('cloud_browser_type', 'Type bounded text into the focused Cloud Computer browser element.', { text: { type: 'string' }, selector: { type: 'string' } }, ['text'], 'type', action, args => ({ text: bounded(args.text, 'text', 16 * 1024), ...(args.selector === undefined ? {} : { selector: bounded(args.selector, 'selector', 1024) }) })),
+    actionDefinition('cloud_browser_press', 'Press one allowlisted key in the Cloud Computer browser.', { key: { type: 'string' } }, ['key'], 'press', action, args => {
+      const key = bounded(args.key, 'key', 64);
+      if (!KEY_ALLOWLIST.includes(key)) throw new TypeError(`Key is not allowlisted: ${key}`);
+      return { key };
+    }),
+    actionDefinition('cloud_browser_screenshot', 'Capture the current Cloud Computer browser viewport.', {}, [], 'screenshot', action),
+    actionDefinition('cloud_browser_download', 'Download a bounded file through the Cloud Computer browser.', { url: { type: 'string' }, selector: { type: 'string' }, timeoutMs: { type: 'number' } }, [], 'download', action, args => ({
+      ...(args.url === undefined ? {} : { url: bounded(args.url, 'url', 4096) }),
+      ...(args.selector === undefined ? {} : { selector: bounded(args.selector, 'selector', 1024) }),
+      ...(args.timeoutMs === undefined ? {} : { timeoutMs: Number(args.timeoutMs) }),
+    })),
+    actionDefinition('cloud_browser_close', 'Close the Cloud Computer browser session.', {}, [], 'stop', action),
+    actionDefinition('cloud_bash', 'Run bash, git, ssh and skill scripts in the Cloud Computer workspace. Public internet (DNS/HTTPS/SSH) is available by default; host credentials and private desktop control endpoints remain isolated.', { command: { type: 'string' }, timeoutMs: { type: 'number' } }, ['command'], 'terminal.exec', action, args => ({
+      language: 'shell', command: bounded(args.command, 'command', 16 * 1024), ...(args.timeoutMs === undefined ? {} : { timeoutMs: Number(args.timeoutMs) }),
+    })),
+    actionDefinition('cloud_run_code', 'Run bounded JavaScript or Python inside the Cloud Computer terminal sandbox.', { language: { type: 'string', enum: [...CODE_LANGUAGES] }, code: { type: 'string' }, timeoutMs: { type: 'number' } }, ['language', 'code'], 'terminal.exec', action, args => {
+      const language = bounded(args.language, 'language', 32);
+      if (!CODE_LANGUAGES.includes(language)) throw new TypeError(`Unsupported code language: ${language}`);
+      return { language, code: bounded(args.code, 'code', 64 * 1024), ...(args.timeoutMs === undefined ? {} : { timeoutMs: Number(args.timeoutMs) }) };
+    }),
+  ];
+
+  return Object.freeze({
+    identity: Object.freeze({ ...identity }),
+    capabilities: Object.freeze([PERSONAL_ASSISTANT_BROWSER_CAPABILITY, PERSONAL_ASSISTANT_CODE_EXECUTION_CAPABILITY, CLOUD_COMPUTER_CAPABILITY]),
+    tools: Object.freeze(definitions),
+    get lease() { return activeLease; },
+    execute(name, args, execution) {
+      const definition = definitions.find(item => item.name === name);
+      if (!definition) throw new TypeError(`Unknown personal assistant computer tool: ${name}`);
+      return definition.execute(args, execution);
+    },
+    async executeRaw(name, args, execution) {
+      const result = await this.execute(name, args, execution);
+      try { return JSON.parse(result.result); } catch { return result.result; }
+    },
+    async release() { return release(); },
+    async dispose() { disposed = true; await release().catch(() => {}); },
+  });
+}
+
+/** Execute a bounded command through computer-agentd's terminal executor. */
+export function runCommand(toolset, command, options = {}, execution) {
+  if (!toolset || typeof toolset.execute !== 'function') throw new TypeError('toolset is required');
+  return toolset.execute('cloud_bash', { command, ...options }, execution);
+}
+
+/** Execute bounded JavaScript/Python code through computer-agentd. */
+export function executeCode(toolset, language, code, options = {}, execution) {
+  if (!toolset || typeof toolset.execute !== 'function') throw new TypeError('toolset is required');
+  return toolset.execute('cloud_run_code', { language, code, ...options }, execution);
+}
+
+/** Register broker-backed tools through the public DSH tools service. */
+export function registerComputerTools({ agent, register, toolset } = {}) {
+  if (!toolset || typeof toolset.tools?.[Symbol.iterator] !== 'function') throw new TypeError('toolset is required');
+  const injected = agent?.ctx?.get?.('tools');
+  const add = typeof register === 'function' ? register : injected?.register?.bind(injected);
+  if (typeof add !== 'function') throw new TypeError('A public DSH tools.register function is required');
+  const disposers = toolset.tools.map(definition => add(definition)).filter(item => typeof item === 'function');
+  return Object.freeze({ names: Object.freeze(toolset.tools.map(item => item.name)), definitions: toolset.tools, disposers });
+}

package/src/cloud-files.mjs

@@ -0,0 +1,57 @@
+import { open, mkdir } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+
+export const CLOUD_ATTACHMENT_MAX_BYTES = 512 * 1024;
+const fail = message => Object.assign(new Error(message), { code: 'CLOUD_FILE_INVALID', status: 400 });
+const segments = path => {
+  if (typeof path !== 'string' || path.length > 2048) throw fail('文件路径无效');
+  const parts = path.split('/');
+  if (!parts.length || parts.length > 32 || parts.some(part => !part || part === '.' || part === '..' || /[\\\u0000-\u001f]/u.test(part))) throw fail('文件必须位于云电脑工作区内');
+  return parts;
+};
+
+/** 逐层固定目录 FD，拒绝符号链接；命令并发换名不能把 Runtime 的文件访问引到私有目录。 */
+export function createCloudFileStore(root) {
+  const ownedPrefix = (botId, sessionId) => `uploads/${createHash('sha256').update(JSON.stringify([botId, sessionId])).digest('hex').slice(0, 32)}/`;
+  const withParent = async (path, create, task) => {
+    const parts = segments(path); let parent = await open(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+      for (const part of parts.slice(0, -1)) {
+        const target = `/proc/self/fd/${parent.fd}/${part}`;
+        if (create) await mkdir(target, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+        const next = await open(target, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        await parent.close(); parent = next;
+      }
+      return await task(`/proc/self/fd/${parent.fd}/${parts.at(-1)}`);
+    } finally { await parent.close(); }
+  };
+  const read = path => withParent(path, false, async target => {
+    const file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const info = await file.stat();
+      if (!info.isFile() || info.size > CLOUD_ATTACHMENT_MAX_BYTES) throw fail('仅支持不超过 512 KiB 的普通文件');
+      const bytes = Buffer.alloc(CLOUD_ATTACHMENT_MAX_BYTES + 1);
+      const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+      if (bytesRead > CLOUD_ATTACHMENT_MAX_BYTES) throw fail('文件超过 512 KiB');
+      return bytes.subarray(0, bytesRead);
+    } finally { await file.close(); }
+  });
+  return {
+    async upload({ botId, sessionId, name, dataUrl }) {
+      if (typeof name !== 'string' || name.length > 120 || /[\/\\\u0000-\u001f]/u.test(name)) throw fail('文件名无效');
+      const match = typeof dataUrl === 'string' && dataUrl.match(/^data:([a-z0-9.+-]+\/[a-z0-9.+-]+);base64,([A-Za-z0-9+/]*={0,2})$/iu);
+      if (!match || match[2].length > Math.ceil(CLOUD_ATTACHMENT_MAX_BYTES / 3) * 4) throw fail('附件格式无效或超过 512 KiB');
+      const bytes = Buffer.from(match[2], 'base64');
+      if (bytes.length > CLOUD_ATTACHMENT_MAX_BYTES || bytes.toString('base64') !== match[2]) throw fail('附件编码无效');
+      const path = ownedPrefix(botId, sessionId) + randomUUID() + '-' + name;
+      await withParent(path, true, async target => { const file = await open(target, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); try { await file.writeFile(bytes); } finally { await file.close(); } });
+      return { path, name, bytes: bytes.length, mediaType: match[1].toLowerCase() };
+    },
+    async attachment({ botId, sessionId, path }) {
+      if (typeof path !== 'string' || !path.startsWith(ownedPrefix(botId, sessionId))) throw fail('附件不属于当前云端会话');
+      return read(path);
+    },
+    async download(path) { const data = await read(path); return { path, name: path.split('/').at(-1), bytes: data.length, data: data.toString('base64') }; },
+  };
+}

package/src/cloud-model.mjs

@@ -0,0 +1,10 @@
+/** 个人助理新建声明的默认模型；显式指定其他模型时仍尊重声明。 */
+export const DEFAULT_PERSONAL_ASSISTANT_MODEL = 'deepseek-v4.1-flash-1017';
+
+export function cloudModelDefinition(model = DEFAULT_PERSONAL_ASSISTANT_MODEL) {
+  return {
+    id: model, name: model, contextWindow: 131072, maxTokens: 8192,
+    // 只有经云网关实际图像输入验证的默认模型声明视觉能力。
+    input: model === DEFAULT_PERSONAL_ASSISTANT_MODEL ? ['text', 'image'] : ['text'],
+  };
+}

package/src/cloud-session-transport.mjs

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+
+const fail = (code, message, status = 503) => Object.assign(new Error(message), { code, status });
+
+/** 独立于桌面画面的云会话连接；只使用 Host 签发的 Agent/Bot control 票据。 */
+export function createCloudSessionTransport({ issueTicket, WebSocketImpl, ca, timeoutMs = 15_000 }) {
+  const connections = new Map();
+  async function connect(scope, signal) {
+    const key = JSON.stringify([scope.agentId, scope.botId]);
+    if (connections.has(key)) return connections.get(key);
+    const promise = (async () => {
+      const ticket = await issueTicket({ ...scope, mode: 'control' }, signal);
+      if (typeof WebSocketImpl !== 'function') throw fail('PERSONAL_ASSISTANT_CLOUD_SESSION_UNAVAILABLE', '云端会话连接组件不可用');
+      return new Promise((resolve, reject) => {
+        let socket, opened = false, idle;
+        const pending = new Map();
+        const error = () => fail('PERSONAL_ASSISTANT_CLOUD_SESSION_UNAVAILABLE', '云端会话连接中断；请核对发送状态后重试');
+        const invalidate = failure => {
+          clearTimeout(idle); clearTimeout(openTimer);
+          if (connections.get(key) === promise) connections.delete(key);
+          for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(failure); }
+          pending.clear();
+          if (!opened) reject(failure);
+        };
+        const touch = () => { clearTimeout(idle); idle = setTimeout(() => socket.close(1000, 'session idle'), 300_000); idle.unref?.(); };
+        const openTimer = setTimeout(() => { invalidate(error()); socket?.close(); }, timeoutMs);
+        openTimer.unref?.();
+        try { socket = new WebSocketImpl(ticket.wsUrl, ['agentkit.personal-assistant.desktop.v1', `agentkit.desktop.ticket.${ticket.ticket}`], { ca }); }
+        catch { invalidate(error()); return; }
+        socket.onopen = () => {
+          opened = true; clearTimeout(openTimer); touch();
+          resolve({
+            close: () => { invalidate(error()); socket.close(1000, 'Host disposed'); },
+            request(operation, payload, signal) {
+              if (socket.readyState !== 1) return Promise.reject(error());
+              const requestId = randomUUID();
+              return new Promise((resolve, reject) => {
+                const finish = (failure, value) => { const entry = pending.get(requestId); if (!entry) return; pending.delete(requestId); clearTimeout(entry.timer); signal?.removeEventListener('abort', abort); failure ? reject(failure) : resolve(value); };
+                const abort = () => finish(fail('PERSONAL_ASSISTANT_REQUEST_ABORTED', '请求已取消；已提交的云端任务会继续运行', 499));
+                if (signal?.aborted) { reject(signal.reason || error()); return; }
+                const timer = setTimeout(() => finish(fail('PERSONAL_ASSISTANT_CLOUD_SESSION_TIMEOUT', '云端响应超时；发送结果待确认，请勿重复创建任务', 504)), timeoutMs);
+                timer.unref?.();
+                pending.set(requestId, { timer, reject: failure => finish(failure), resolve: value => finish(null, value) });
+                signal?.addEventListener('abort', abort, { once: true });
+                touch();
+                try { socket.send(JSON.stringify({ type: 'session.request', requestId, agentId: scope.agentId, botId: scope.botId, operation, payload })); }
+                catch { finish(error()); }
+              });
+            },
+          });
+        };
+        socket.onmessage = event => {
+          let value; try { value = JSON.parse(String(event.data)); } catch { return; }
+          if (value.type === 'error') {
+            const failure = fail(value.code === 'DESKTOP_MESSAGE_UNSUPPORTED' ? 'PERSONAL_ASSISTANT_CLOUD_SESSION_UPGRADE_REQUIRED' : value.code || 'PERSONAL_ASSISTANT_CLOUD_SESSION_UNAVAILABLE', value.code === 'DESKTOP_MESSAGE_UNSUPPORTED' ? '当前云端版本不支持对话，请升级云端助理；不会使用本机执行' : '云端拒绝会话请求', value.status || 409);
+            invalidate(failure); socket.close(); return;
+          }
+          if (value.type !== 'session.response') return;
+          const entry = pending.get(value.requestId);
+          if (!entry) return;
+          if (value.agentId !== scope.agentId || value.botId !== scope.botId) { entry.reject(fail('PERSONAL_ASSISTANT_AGENT_MISMATCH', '云端会话身份不一致', 403)); return; }
+          if (value.ok) entry.resolve(value.value);
+          else entry.reject(fail(value.error?.code || 'PERSONAL_ASSISTANT_CLOUD_SESSION_FAILED', value.error?.message || '云端会话请求失败', value.error?.status || 503));
+        };
+        socket.onclose = () => invalidate(error());
+        socket.onerror = () => { invalidate(error()); try { socket.close(); } catch {} };
+      });
+    })();
+    connections.set(key, promise);
+    try { return await promise; } catch (error) { if (connections.get(key) === promise) connections.delete(key); throw error; }
+  }
+  return {
+    async request(scope, operation, payload, signal) { return (await connect(scope, signal)).request(operation, payload, signal); },
+    dispose() { for (const connection of connections.values()) void connection.then(value => value.close()).catch(() => {}); connections.clear(); },
+  };
+}