@kingsoftcloud/agentkit-personal-assistant 0.1.9 → 0.1.12

package/runtime/build-info.mjs

@@ -0,0 +1,40 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+function manifestValue(path, field) {
+  try {
+    const value = require(path)?.[field];
+    return typeof value === 'string' && value.trim() ? value.trim() : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function clean(value) {
+  const text = String(value ?? '').trim();
+  return text && !/[\u0000\r\n]/u.test(text) ? text.slice(0, 160) : 'unknown';
+}
+
+/**
+ * Build identity is deliberately read from the image environment first. The
+ * package/manifest fallbacks keep local and packaged computer artifacts
+ * diagnosable even when the deployment did not inject release metadata.
+ */
+export function createBuildInfo(env = process.env) {
+  return Object.freeze({
+    packageVersion: clean(env.AGENTKIT_PERSONAL_ASSISTANT_VERSION || manifestValue('../package.json', 'version')),
+    manifestVersion: clean(env.AGENTKIT_PERSONAL_ASSISTANT_MANIFEST_VERSION || manifestValue('../personal-assistant.plugin.json', 'version')),
+    runtimeBuild: clean(env.AGENTKIT_RUNTIME_BUILD || env.AGENTKIT_BUILD_ID),
+    computerImage: clean(env.AGENTKIT_COMPUTER_IMAGE || env.AGENTKIT_IMAGE || env.AGENTKIT_IMAGE_DIGEST),
+    buildTimestamp: clean(env.AGENTKIT_BUILD_TIMESTAMP),
+  });
+}
+
+export const DESKTOP_DOCK_LAYOUT = Object.freeze({
+  position: 'bottom-center',
+  panelPosition: 'bottom center horizontal',
+  shrink: true,
+  iconCount: 3,
+  height: 56,
+});

package/runtime/cloud-browser-cdp.mjs

@@ -15,6 +15,47 @@ const persistentProfileOwners = new Map();
 const fail = (message, code = 'ASSISTANT_BROWSER_CDP_UNAVAILABLE') => Object.assign(new Error(message), { code });
 const delay = ms => new Promise(resolvePromise => setTimeout(resolvePromise, ms));
 
+/**
+ * 桌面窗口几何预算（均为实测值，改动前先看 test/cloud-browser-lifecycle.test.mjs 的注释）：
+ *  - 屏幕 1280x800（runtime/desktop-session.mjs 的 DESKTOP_WIDTH/HEIGHT，Xvfb 分辨率）
+ *  - 底部 tint2 dock 占 68px（panel_size 56 + panel_margin 12）且带 strut，因此
+ *    `xprop -root _NET_WORKAREA` = 0,0,1280,732：窗口真正可见的高度只有 732
+ *  - Chromium 窗口不带 WM 装饰（实测 `_NET_FRAME_EXTENTS` = 0,0,0,0，标签栏和 —□✕
+ *    都是 Chromium 自绘）；fluxbox 只给普通 X11 客户端加装饰（xterm 实测 1,1,30,5）。
+ *    这里预留的 33px 是装饰保守余量，不是 Chromium 当前的实际开销。
+ *
+ * Chromium 的 `--window-size` 是客户区（无装饰时即整个窗口）尺寸：客户区 800 比工作区
+ * 732 高 68px，fluxbox 会把窗口底边贴到工作区底边、把顶部推出屏幕。0.1.23 镜像里不带
+ * --start-maximized 的对照实测：
+ *   --window-size=1280,800 → xwininfo 0,-67 1279x799（底边正好 732，顶部 67px 在屏外）
+ *   --window-size=1278,699 → xwininfo 0,0   1278x699（完整可见）
+ * CDP 侧同一个现象：旧参数下 Browser.getWindowBounds = {left:0, top:-67, width:1279,
+ * height:799, windowState:'normal'}，setWindowBounds({windowState:'maximized'}) 后立刻
+ * 变成 {0,0,1280x732, maximized}。用户看到的就是“标题栏（自绘标签栏）在屏幕外 +
+ * 页面底部被 dock 压住”。
+ */
+export const DESKTOP_SCREEN_WIDTH = 1280;
+export const DESKTOP_SCREEN_HEIGHT = 800;
+/** tint2 dock 占用的底部高度（带 strut，扣掉后才是可用工作区高度 732）。 */
+export const DESKTOP_DOCK_HEIGHT = 68;
+/**
+ * 装饰保守余量：fluxbox 对普通 X11 客户端实测 `_NET_FRAME_EXTENTS` = 1,1,30,5
+ * （左右 1、上 30、下 5，即竖向 35 / 横向 2）；Chromium 自绘窗口实测 0,0,0,0。
+ * 这里按竖向 33 / 横向 2 预留，属于"未来换成带 WM 装饰的 Chromium 也不越界"的
+ * 保守预算——窗口实际会比预算更矮，不会超出可见区。
+ */
+export const DESKTOP_DECORATION_HORIZONTAL = 2;
+export const DESKTOP_DECORATION_VERTICAL = 33;
+
+/**
+ * 让窗口完整落在「屏幕 - 底部 dock」可见区内的客户区尺寸：1278x699。
+ * 不传参时按整屏扣掉 dock 高度计算；调用方也可以显式给可用高度。
+ * 其中 33px 是装饰保守余量（见上面的几何预算说明）。
+ */
+export function desktopWindowClientSize({ width = DESKTOP_SCREEN_WIDTH, height = DESKTOP_SCREEN_HEIGHT - DESKTOP_DOCK_HEIGHT } = {}) {
+  return { width: width - DESKTOP_DECORATION_HORIZONTAL, height: height - DESKTOP_DECORATION_VERTICAL };
+}
+
 /**
  * Chromium flags for the managed image. Chromium's own sandbox is unavailable in
  * most managed containers, so the egress proxy stays authoritative for network
@@ -28,17 +69,21 @@ const delay = ms => new Promise(resolvePromise => setTimeout(resolvePromise, ms)
  * 不改变 CDP/自动化语义，也不影响页面能力。
  */
 export function chromiumArgs({ userDataDir, proxy, windowSize = '1280,800', desktop = false, startUrl, openUrl }) {
+  const desktopClient = desktop ? desktopWindowClientSize() : null;
   return [
-    ...(desktop ? ['--ozone-platform=x11', '--window-position=520,90', '--test-type', '--lang=zh-CN', '--accept-lang=zh-CN,zh', '--class=Chromium', '--hide-crash-restore-bubble'] : ['--headless=new']),
-    // 应用窗口承载首屏：没有地址栏、没有多余标签条。
-    ...(desktop && startUrl ? [`--app=${startUrl}`] : []),
-    // 普通窗口模式：把首页作为位置参数交给 Chromium，避免先出一个空白标签再补一个页面。
-    ...(desktop && !startUrl && openUrl ? [openUrl] : []),
+    ...(desktop ? ['--ozone-platform=x11', '--test-type', '--lang=zh-CN', '--accept-lang=zh-CN,zh', '--class=Chromium', '--hide-crash-restore-bubble'] : ['--headless=new']),
+    // 欢迎页是云电脑的门面，必须铺满整块 1280x800 屏幕：`--app` 无地址栏 +
+    // `--kiosk` 全屏（旧实现是 740x620 固定窗口偏在右下角，四圈都是灰底）。
+    ...(desktop && startUrl ? [`--app=${startUrl}`, '--kiosk', '--window-position=0,0'] : []),
+    // 普通窗口模式：把首页作为位置参数交给 Chromium，避免先出一个空白标签再补一个页面；同时最大化。
+    ...(desktop && !startUrl && openUrl ? ['--window-position=0,0', '--start-maximized', openUrl] : []),
+    ...(desktop && !startUrl && !openUrl ? ['--window-position=0,0', '--start-maximized'] : []),
     '--disable-gpu', '--disable-dev-shm-usage', '--no-sandbox',
     '--no-first-run', '--no-default-browser-check', '--disable-extensions', '--disable-sync',
     '--disable-background-networking', '--disable-breakpad', '--disable-crash-reporter',
     '--disable-translate', '--mute-audio', '--hide-scrollbars',
-    `--window-size=${desktop ? '740,620' : windowSize}`,
+    // 客户区尺寸必须扣掉可用的装饰余量（见上面的几何预算注释），否则窗口会高于工作区。
+    `--window-size=${desktopClient ? `${desktopClient.width},${desktopClient.height}` : windowSize}`,
     '--remote-debugging-port=0', '--remote-debugging-address=127.0.0.1',
     `--user-data-dir=${userDataDir}`,
     `--proxy-server=${proxy}`,
@@ -141,7 +186,7 @@ export async function launchChromium({
         // 桌面窗口给用户看：界面与页面语言都用简体中文；LC_ALL 会盖过 LANG，桌面模式不能设。
         // 无头自动化不改变既有口径（历史行为是 C.UTF-8 + 默认语言）。
         ...(desktop
-          ? { LANG: 'zh_CN.UTF-8', LANGUAGE: 'zh_CN:zh' }
+          ? { LANG: 'zh_CN.UTF-8', LANGUAGE: 'zh_CN:zh', LC_CTYPE: 'C.UTF-8' }
           : { LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' }),
         ...(timeZone ? { TZ: timeZone } : {}),
         ...(desktop ? { DISPLAY: env.DISPLAY || ':99' } : {}),

package/runtime/cloud-browser.mjs

@@ -3,7 +3,10 @@ import { spawn as spawnChild } from 'node:child_process';
 import { existsSync, realpathSync, statSync } from 'node:fs';
 import { mkdir, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { isAbsolute, join, relative, resolve } from 'node:path';
-import { CDP_COMMAND_TIMEOUT_MS, DEVTOOLS_LAUNCH_TIMEOUT_MS, startCdpTransport } from './cloud-browser-cdp.mjs';
+import {
+  CDP_COMMAND_TIMEOUT_MS, DESKTOP_SCREEN_HEIGHT, DESKTOP_SCREEN_WIDTH, DEVTOOLS_LAUNCH_TIMEOUT_MS,
+  desktopWindowClientSize, startCdpTransport,
+} from './cloud-browser-cdp.mjs';
 
 export const BROWSER_TOOLS = Object.freeze([
   'cloud_browser_open', 'cloud_browser_snapshot', 'cloud_browser_click', 'cloud_browser_type',
@@ -13,6 +16,8 @@ export const BROWSER_TOOLS = Object.freeze([
 const DEFAULT_CHROMIUM = '/usr/bin/chromium';
 const DEFAULT_PROXY = 'socks5://127.0.0.1:8899';
 const LOAD_TIMEOUT_MS = 20_000;
+const DEFAULT_NAVIGATION_MIN_INTERVAL_MS = 800;
+const DEFAULT_CHALLENGE_COOLDOWN_MS = 30_000;
 export const MAX_SNAPSHOT_BYTES = 32 * 1024;
 export const MAX_SCREENSHOT_BASE64 = 4 * 1024 * 1024;
 export const MAX_SCREENSHOT_BYTES = 4 * 1024 * 1024;
@@ -24,10 +29,26 @@ const MAX_SELECTOR_BYTES = 1024;
 const MAX_TITLE_BYTES = 1024;
 const VIEWPORT = Object.freeze({ width: 1280, height: 800 });
 const IDLE_TIMEOUT_MS = 600_000;
+const CHALLENGE_WARNING = '检测到验证码或站点风控页，已暂停自动点击/输入；请在可见云浏览器中手动完成验证后再继续';
 
 const fail = (message, code = 'ASSISTANT_BROWSER_REFUSED') => Object.assign(new Error(message), { code });
 const delay = ms => new Promise(resolvePromise => setTimeout(resolvePromise, ms));
 
+/**
+ * 识别常见验证码/反自动化页面。这里只做合规的风险提示与停手，
+ * 不尝试绕过验证码、伪造浏览器指纹或自动提交验证。
+ */
+export function detectBrowserChallenge({ url = '', title = '', text = '' } = {}) {
+  const haystack = [url, title, text].map(value => String(value ?? '')).join('\n').slice(0, 16_384);
+  if (!haystack) return null;
+  const patterns = [
+    /captcha|re-?captcha|hcaptcha|verify\s+(?:you\s+are\s+)?human|security\s+check|unusual\s+traffic|access\s+denied|too\s+many\s+requests|rate\s*limit|challenge/iu,
+    /验证码|人机验证|滑块验证|安全验证|访问频繁|异常流量|请求过于频繁|(?:请|需要)(?:完成|通过)(?:验证码|人机|安全|滑块)验证|风控/iu,
+  ];
+  const matched = patterns.some(pattern => pattern.test(haystack));
+  return matched ? { warning: CHALLENGE_WARNING, code: 'ASSISTANT_BROWSER_CHALLENGE_REQUIRED' } : null;
+}
+
 /** Resolve the image-provided Chromium and egress proxy. Missing either refuses the capability. */
 export function resolveCloudBrowser({ env = {} } = {}) {
   const chromium = typeof env?.AGENTKIT_CHROMIUM === 'string' && env.AGENTKIT_CHROMIUM ? env.AGENTKIT_CHROMIUM : DEFAULT_CHROMIUM;
@@ -237,7 +258,7 @@ const KEY_ALLOWLIST = Object.freeze({
   Space: { key: ' ', code: 'Space', windowsVirtualKeyCode: 32 },
 });
 
-const PAGE_STATE_EXPRESSION = '({ url: location.href, title: document.title })';
+const PAGE_STATE_EXPRESSION = '(() => ({ url: location.href, title: document.title, text: document.body ? String(document.body.innerText || document.body.textContent || "").slice(0, 8192) : "" }))()';
 const RESOURCE_EXPRESSION = "(() => { try { return performance.getEntriesByType('resource').slice(0, 200).map(entry => entry.name); } catch { return []; } })()";
 
 function snapshotExpression() {
@@ -290,6 +311,8 @@ export function createCloudBrowser({
   kill, launchTimeoutMs = DEVTOOLS_LAUNCH_TIMEOUT_MS, commandTimeoutMs = CDP_COMMAND_TIMEOUT_MS,
   beforeCommand = null, transportFactory = startCdpTransport,
   userDataDir, preserveUserDataDir = false,
+  navigationMinIntervalMs = DEFAULT_NAVIGATION_MIN_INTERVAL_MS,
+  challengeCooldownMs = DEFAULT_CHALLENGE_COOLDOWN_MS,
 } = {}) {
   const root = checkedWorkspace(workspace);
   const resolution = resolveCloudBrowser({ env });
@@ -322,8 +345,12 @@ export function createCloudBrowser({
   const removeFile = typeof removeFileHook === 'function' ? removeFileHook : path => rm(path, { force: true });
   const idleMs = Number.isSafeInteger(idleTimeoutMs) && idleTimeoutMs > 0 ? idleTimeoutMs : IDLE_TIMEOUT_MS;
   const commandMs = Number.isSafeInteger(commandTimeoutMs) && commandTimeoutMs > 0 ? commandTimeoutMs : CDP_COMMAND_TIMEOUT_MS;
+  const navigationGapMs = Number.isSafeInteger(navigationMinIntervalMs) && navigationMinIntervalMs >= 0 ? navigationMinIntervalMs : DEFAULT_NAVIGATION_MIN_INTERVAL_MS;
+  const challengePauseMs = Number.isSafeInteger(challengeCooldownMs) && challengeCooldownMs >= 0 ? challengeCooldownMs : DEFAULT_CHALLENGE_COOLDOWN_MS;
 
   let transport = null, targetId = null, pageSession = null, launching = null, disposed = false, disposing, idleTimer = null, lastUrl = null;
+  const lastNavigationByHost = new Map();
+  let challengeState = null;
   let inputGeneration = 0, releasingInput, desktopTargetOpening;
   const closingTargets = new Set();
   const heldMouseButtons = new Map(), heldKeys = new Map();
@@ -380,6 +407,35 @@ export function createCloudBrowser({
   }
 
   const throwIfAborted = signal => { if (signal?.aborted) throw fail('云端浏览器操作已取消', 'ASSISTANT_BROWSER_ABORTED'); };
+  const clockNow = () => {
+    const value = Number(now());
+    return Number.isFinite(value) ? value : Date.now();
+  };
+  const activeChallenge = () => {
+    if (!challengeState) return null;
+    if (clockNow() < challengeState.until) return challengeState;
+    challengeState = null;
+    return null;
+  };
+  const challengeFailure = () => fail(CHALLENGE_WARNING, 'ASSISTANT_BROWSER_CHALLENGE_REQUIRED');
+  const rejectAutomatedChallengeAction = () => { if (activeChallenge()) throw challengeFailure(); };
+  const noteChallenge = (url, state) => {
+    const challenge = detectBrowserChallenge({ url: url.href, title: state?.title, text: state?.text });
+    if (challenge) {
+      challengeState = { host: url.hostname, until: clockNow() + challengePauseMs, warning: challenge.warning };
+      return challenge.warning;
+    }
+    if (challengeState?.host === url.hostname) challengeState = null;
+    return null;
+  };
+  async function paceNavigation(host, signal) {
+    const previous = lastNavigationByHost.get(host);
+    const elapsed = previous === undefined ? navigationGapMs : clockNow() - previous;
+    const waitMs = previous === undefined ? 0 : Math.max(0, navigationGapMs - elapsed);
+    if (waitMs > 0) await delay(waitMs);
+    throwIfAborted(signal);
+    lastNavigationByHost.set(host, clockNow());
+  }
   function ensureUsable() {
     if (disposed) throw fail('云端浏览器已关闭', 'ASSISTANT_BROWSER_DISPOSED');
     if (!resolution.available) throw fail(resolution.reason || '云端浏览器不可用', 'ASSISTANT_BROWSER_UNAVAILABLE');
@@ -475,6 +531,9 @@ export function createCloudBrowser({
         { width: VIEWPORT.width, height: VIEWPORT.height, deviceScaleFactor: 1, mobile: false }, { sessionId: pageSession, timeoutMs: commandMs });
       await started.connection.send('Browser.setDownloadBehavior', { behavior: 'deny' }, { timeoutMs: commandMs });
       transport = started;
+      // 普通桌面窗口补一次显式最大化：`--start-maximized` 由 WM 处理，换成浏览窗口
+      // 或进程重建时 WM 未必照做，这里按工作区几何统一兜底。
+      if (desktopMode && !desktopAppWindow) await fitDesktopWindow(targetId, { maximize: true });
       return transport;
     } catch (error) {
       if (started) {
@@ -487,6 +546,30 @@ export function createCloudBrowser({
     }
   }
 
+  // Chromium 的 `--window-size` 只作用于「初始窗口」，`--start-maximized` 也只对首个
+  // 窗口生效：之后通过 CDP `Target.createTarget({newWindow:true})` 补开的窗口会退回
+  // 默认客户区尺寸。客户区 1280x800 加上 fluxbox 的标题栏 28 + 手柄 3 + 边框 2 就是
+  // 1280x833 的 frame，比 1280x800 的屏幕还高，WM 只能把窗口往屏幕外放
+  // （实测 windowBounds = top:-67），用户看到标题栏和页面底部被裁一半。
+  // 所以桌面窗口每次出现都要按工作区（1280x732，已扣 tint2 dock 的 68px strut）最大化，
+  // WM 不配合时再兜底钳到“连装饰一起也放得下”的客户区尺寸。
+  async function fitDesktopWindow(target, { maximize = false } = {}) {
+    if (!desktopMode || !target) return;
+    const overflows = bounds => !bounds
+      || bounds.left < 0 || bounds.top < 0
+      || bounds.left + bounds.width > DESKTOP_SCREEN_WIDTH || bounds.top + bounds.height > DESKTOP_SCREEN_HEIGHT;
+    try {
+      const { windowId } = await browserCommand('Browser.getWindowForTarget', { targetId: target });
+      if (!Number.isInteger(windowId)) return;
+      if (!maximize && !overflows((await browserCommand('Browser.getWindowBounds', { windowId }))?.bounds)) return;
+      await browserCommand('Browser.setWindowBounds', { windowId, bounds: { windowState: 'maximized' } });
+      if (!overflows((await browserCommand('Browser.getWindowBounds', { windowId }))?.bounds)) return;
+      const client = desktopWindowClientSize();
+      await browserCommand('Browser.setWindowBounds', { windowId, bounds: { windowState: 'normal' } });
+      await browserCommand('Browser.setWindowBounds', { windowId, bounds: { left: 0, top: 0, width: client.width, height: client.height } });
+    } catch { /* 窗口可能正在销毁；几何兜底失败不该阻断打开 */ }
+  }
+
   // CDP 里有页面目标不等于桌面上还有窗口：窗口被关掉或收起、进程仍活着时
   // target 依然存在。桌面入口必须确认“目标真的在某一个窗口里”，否则点 dock
   // 只会激活一个看不见的目标，随后报 DESKTOP_APP_WINDOW_UNAVAILABLE。
@@ -508,6 +591,9 @@ export function createCloudBrowser({
     const attached = await browserCommand('Target.attachToTarget', { targetId: created.targetId, flatten: true });
     if (!attached?.sessionId) throw fail('Chromium 没有返回替代页面会话', 'ASSISTANT_BROWSER_TARGET_UNAVAILABLE');
     await browserCommand('Target.activateTarget', { targetId: created.targetId });
+    // 补开的窗口拿不到 `--start-maximized`，必须在窗口出现后按工作区最大化，
+    // 否则客户区 1280x800 + 装饰 33 的 frame 会被 WM 放到屏幕外。
+    await fitDesktopWindow(created.targetId, { maximize: true });
     return { targetId: created.targetId, pageSession: attached.sessionId };
   }
 
@@ -569,7 +655,12 @@ export function createCloudBrowser({
         }
       }
       if (!missing && desktopMode && !(await hasBrowserWindow(inspectedTarget))) missing = true;
-      if (!missing) return;
+      if (!missing) {
+        // 窗口已存在：只在几何越界（历史窗口/被拖出屏幕）时纠正，不强制最大化，
+        // 避免把用户手动调整过的窗口大小改掉。
+        await fitDesktopWindow(inspectedTarget);
+        return;
+      }
       // 有欢迎页的桌面模式重建窗口时从欢迎页开始：8081 不能变成“首页”。
       const restoreUrl = desktopMode && desktopStartUrl ? desktopRestoreUrl
         : lastUrl && lastUrl !== 'about:blank' ? desktopPolicy(lastUrl).href : desktopRestoreUrl;
@@ -595,7 +686,7 @@ export function createCloudBrowser({
     const closingTarget = targetId;
     const generation = inputGeneration;
     const authorize = (method, params = {}) => trusted ? Promise.resolve() : checkCommand(method, params, 'browser', generation);
-    if (!current) { clearIdle(); lastUrl = null; return; }
+    if (!current) { clearIdle(); lastUrl = null; challengeState = null; lastNavigationByHost.clear(); return; }
     if (closingTarget) {
       await authorize('Target.closeTarget', { targetId: closingTarget });
       if (!trusted) checkGeneration(generation);
@@ -610,7 +701,7 @@ export function createCloudBrowser({
     if (!trusted) checkGeneration(generation);
     await current.dispose();
     forgetInput(current);
-    if (transport === current) { clearIdle(); transport = null; targetId = null; pageSession = null; lastUrl = null; }
+    if (transport === current) { clearIdle(); transport = null; targetId = null; pageSession = null; lastUrl = null; challengeState = null; lastNavigationByHost.clear(); }
   }
 
   async function evaluate(expression) {
@@ -653,6 +744,8 @@ export function createCloudBrowser({
     const url = desktopPolicy(String(rawUrl));
     ensureUsable();
     throwIfAborted(signal);
+    if (activeChallenge()?.host === url.hostname) throw challengeFailure();
+    await paceNavigation(url.hostname, signal);
     const result = await pageCommand('Page.navigate', { url: url.href });
     // A download response aborts the navigation; that is not a navigation failure.
     if (result?.errorText && result.errorText !== 'net::ERR_ABORTED') throw fail(`页面导航失败: ${String(result.errorText).slice(0, 120)}`, 'ASSISTANT_BROWSER_NAVIGATION_FAILED');
@@ -663,6 +756,8 @@ export function createCloudBrowser({
     try { finalUrl = desktopPolicy(finalRaw); }
     catch { throw fail('页面跳转到被拒绝的地址', 'ASSISTANT_BROWSER_URL_REFUSED'); }
     const warnings = await waitForResources();
+    const challengeWarning = noteChallenge(finalUrl, state);
+    if (challengeWarning && !warnings.includes(challengeWarning)) warnings.push(challengeWarning);
     lastUrl = finalUrl.href;
     touch();
     return { url: finalUrl.href, title: sliceUtf8(typeof state?.title === 'string' ? state.title : '', MAX_TITLE_BYTES).text, warnings };
@@ -681,13 +776,16 @@ export function createCloudBrowser({
       text: sliceUtf8(typeof link?.text === 'string' ? link.text : '', 256).text,
       href: sliceUtf8(typeof link?.href === 'string' ? link.href : '', 2048).text,
     })) : [];
+    const challengeWarning = noteChallenge(new URL(url), { title: state.title, text: text.text });
     touch();
     return { url, title: sliceUtf8(typeof state.title === 'string' ? state.title : '', MAX_TITLE_BYTES).text,
-      text: text.text, truncated: text.truncated, bytes: text.bytes, links };
+      text: text.text, truncated: text.truncated, bytes: text.bytes, links,
+      warnings: challengeWarning ? [challengeWarning] : [] };
   }
 
   async function click(args) {
     requirePage();
+    rejectAutomatedChallengeAction();
     const generation = inputGeneration;
     const selector = selectorArgument(args?.selector);
     const geometry = await evaluate(clickExpression(selector));
@@ -708,6 +806,7 @@ export function createCloudBrowser({
 
   async function type(args) {
     requirePage();
+    rejectAutomatedChallengeAction();
     const generation = inputGeneration;
     const text = boundedString(args?.text, MAX_TYPE_BYTES, '输入文本');
     if (!text) throw fail('输入文本不能为空', 'ASSISTANT_BROWSER_INVALID_ARGUMENT');
@@ -724,6 +823,7 @@ export function createCloudBrowser({
 
   async function press(args) {
     requirePage();
+    rejectAutomatedChallengeAction();
     const generation = inputGeneration;
     const keyName = boundedString(args?.key, 64, '按键名', { required: true });
     const key = KEY_ALLOWLIST[keyName];
@@ -795,6 +895,7 @@ export function createCloudBrowser({
   }
 
   async function download(args) {
+    rejectAutomatedChallengeAction();
     const timeoutMs = downloadTimeout(args?.timeoutMs);
     const rawUrl = args?.url === undefined ? null : boundedString(args.url, 4096, '下载地址', { required: true });
     const selector = args?.selector === undefined ? null : selectorArgument(args.selector);
@@ -840,10 +941,10 @@ function browserOutput(properties, required, render) {
     },
     {
       name: 'cloud_browser_snapshot',
-      description: 'Read the current page as bounded text (at most 32 KiB), its title, URL and up to 200 links. Prefer this over screenshots when reading content.',
+      description: 'Read the current page as bounded text (at most 32 KiB), its title, URL, up to 200 links and any CAPTCHA/risk warning. Prefer this over screenshots when reading content.',
       parameters: objectSchema(),
-      output: browserOutput({ url: { type: 'string' }, title: { type: 'string' }, text: { type: 'string' }, truncated: { type: 'boolean' }, bytes: { type: 'number' }, links: { type: 'array', items: { type: 'object', properties: { text: { type: 'string' }, href: { type: 'string' } }, required: ['text', 'href'], additionalProperties: false } } }, ['url', 'title', 'text', 'truncated', 'bytes', 'links'],
-        value => `${value.title || '(无标题)'}\n${value.url}\n${value.truncated ? '(内容已截断)' : ''}\n${value.text}`),
+      output: browserOutput({ url: { type: 'string' }, title: { type: 'string' }, text: { type: 'string' }, truncated: { type: 'boolean' }, bytes: { type: 'number' }, links: { type: 'array', items: { type: 'object', properties: { text: { type: 'string' }, href: { type: 'string' } }, required: ['text', 'href'], additionalProperties: false } }, warnings: stringList }, ['url', 'title', 'text', 'truncated', 'bytes', 'links', 'warnings'],
+        value => `${value.title || '(无标题)'}\n${value.url}\n${value.warnings?.length ? `提示: ${value.warnings.join(', ')}\n` : ''}${value.truncated ? '(内容已截断)\n' : ''}${value.text}`),
       execute: () => snapshot(),
     },
     {

package/runtime/cloud-session-channel.mjs

@@ -1,5 +1,5 @@
 /** 云端持久会话适配层。只由签名 control permit 授权，永不调用本机 Host。 */
-export function createCloudSessionChannel({ assistantId, computerId, stateStore, registry, sessionCreate, turnWrite, scheduleWrite, cloudFiles }) {
+export function createCloudSessionChannel({ assistantId, computerId, runtimeInstanceId = '', stateStore, registry, sessionCreate, turnWrite, scheduleWrite, cloudFiles }) {
   const fail = (code, message, status = 400) => Object.assign(new Error(message), { code, status });
   const session = async (botId, sessionId) => {
     if (!(await stateStore.sessions(botId)).some(row => row.sessionId === sessionId)) throw fail('SESSION_NOT_FOUND', '当前助理不存在这个会话', 404);
@@ -10,7 +10,7 @@ export function createCloudSessionChannel({ assistantId, computerId, stateStore,
     if (agentId !== assistantId) throw fail('PERSONAL_ASSISTANT_AGENT_MISMATCH', '云端实例身份不一致', 403);
     try { registry.require(botId); } catch { throw fail('BOT_NOT_FOUND', '云端不存在该助理', 404); }
     if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw fail('CLOUD_SESSION_REQUEST_INVALID', '会话请求格式错误');
-    const scope = { agentId: assistantId, botId, computerId, executionTarget: 'cloud' };
+    const scope = { agentId: assistantId, botId, computerId, executionTarget: 'cloud', ...(runtimeInstanceId ? { runtimeInstanceId, stateStorage: 'state-path' } : {}) };
     if (operation === 'personal-assistant.sessions.list') return { ...scope, sessions: (await stateStore.sessions(botId)).map(row => ({ sessionId: row.sessionId, title: row.title, updatedAt: Date.parse(row.updatedAt) || 0 })).sort((a, b) => b.updatedAt - a.updatedAt) };
     if (operation === 'personal-assistant.session.create') return { ...scope, ...await sessionCreate({ botId, title: String(payload.title || '').slice(0, 200) }) };
     await session(botId, payload.sessionId);

package/runtime/computer-agentd.mjs

@@ -7,6 +7,7 @@ import { verifyDesktopPermit } from './desktop-permit.mjs';
 import { createCloudBrowser } from './cloud-browser.mjs';
 import { createCloudExecutor } from './cloud-execution.mjs';
 import { createDesktopController, DESKTOP_CLIPBOARD_MAX_BYTES } from './desktop-session.mjs';
+import { createBuildInfo } from './build-info.mjs';
 
 export function createComputerAgentServer({ env = process.env, desktopFactory = createDesktopController, browserFactory = createCloudBrowser, executorFactory = createCloudExecutor, logger = console } = {}) {
 const host = env.COMPUTER_HOST || '127.0.0.1';
@@ -89,7 +90,10 @@ const openDshWeb = async ({ signal } = {}) => {
   await browser.closeBlankTabs?.();
   return { ...view, ...page };
 };
-desktop = desktopFactory({ applications: env.AGENTKIT_DESKTOP_MODE === '1', workspace,
+desktop = desktopFactory({ applications: env.AGENTKIT_DESKTOP_MODE === '1', workspace, buildInfo: createBuildInfo(env),
+  // 默认不预开终端窗口：欢迎页/dock 已经能按需启动终端，开机就弹一个
+  // xterm 会盖住欢迎页。排障或旧行为可用 AGENTKIT_DESKTOP_TERMINAL=1 打开。
+  terminal: env.AGENTKIT_DESKTOP_TERMINAL === '1',
   dshWebUrl: () => dshWebUrl, onLaunchDshWeb: openDshWeb,
   onLaunchBrowser: async ({ signal } = {}) => {
     if (closing || signal?.aborted) throw Object.assign(new Error('桌面入口已停止'), { code: 'DESKTOP_LAUNCH_CLOSED' });
@@ -160,9 +164,30 @@ function leaseFor(body) {
   if (!leaseIdentityMatches(lease, body)) throw Object.assign(new Error(lease?.kind === 'human' ? '用户正在操作云电脑，请等待交还后继续' : 'COMPUTER_LEASE_REQUIRED'), { code: lease?.kind === 'human' ? 'COMPUTER_USER_CONTROLLED' : 'COMPUTER_LEASE_REQUIRED', status: 409 });
   return lease;
 }
+/**
+ * 剪贴板既由云端 Agent 工具使用，也由已接管桌面的 Studio 面板使用。
+ * 后者持有的是 human 控制租约，不能沿用普通 Agent action 的校验；只对
+ * 当前 desktop session、控制代次和控制授权全部匹配的读写放行，其他 action
+ * 仍然严格拒绝 human 租约。
+ */
+function assertClipboardLease(body) {
+  const lease = leaseFor(body);
+  if (lease.kind !== 'human') return lease;
+  const sessionId = String(body.sessionId || '');
+  const session = sessionId ? desktop?.getSession(sessionId) : undefined;
+  if (!session || !controlGrants.has(sessionId) || session.leaseId !== lease.leaseId
+    || session.botId !== body.botId || session.taskId !== body.taskId || !session.controllable) {
+    throw Object.assign(new Error('剪贴板未绑定当前桌面控制会话'), { code: 'COMPUTER_LEASE_REQUIRED', status: 409 });
+  }
+  if (!Number.isSafeInteger(body.controlEpoch) || body.controlEpoch !== session.controlEpoch) {
+    throw Object.assign(new Error('桌面控制代次已改变'), { code: 'DESKTOP_CONTROL_EPOCH_CHANGED', status: 409 });
+  }
+  return lease;
+}
 async function action(body, { signal } = {}) {
   signal?.throwIfAborted();
-  const lease = assertAgentLease(body);
+  const clipboardAction = body.action === 'clipboard.read' || body.action === 'clipboard.write';
+  const lease = clipboardAction ? assertClipboardLease(body) : assertAgentLease(body);
   return actionContext.run({ ...body, leaseId: lease.leaseId, signal }, async () => {
   const args = body.args || {};
   if (body.action.startsWith('desktop.')) {

package/runtime/desktop-session.mjs

@@ -14,6 +14,7 @@ import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createDesktopLauncherServer } from './desktop-launcher.mjs';
 import { createWelcomeServer } from './welcome-server.mjs';
+import { createBuildInfo, DESKTOP_DOCK_LAYOUT } from './build-info.mjs';
 
 const execFile = promisify(execFileCallback);
 export const DESKTOP_WIDTH = 1280;
@@ -112,6 +113,7 @@ export function createDesktopController({
   dshWebUrl = null,
   onLaunchDshWeb = null,
   onLaunchError = () => {},
+  buildInfo = createBuildInfo(),
 } = {}) {
   const sessions = new Map();
   let xvfb;
@@ -163,7 +165,8 @@ export function createDesktopController({
     ? process.env.TZ
     : String(process.env.AGENTKIT_DESKTOP_TIME_ZONE || 'Asia/Shanghai');
   // 桌面面向中文用户：终端、文件管理器、窗口管理器都用简体中文（LC_ALL 会盖过 LANG）。
-  const environment = Object.freeze({ ...process.env, DISPLAY: display, LANG: 'zh_CN.UTF-8', LANGUAGE: 'zh_CN:zh', TZ: timeZone });
+  // 清掉继承来的 LC_ALL；它会覆盖 LANG，导致中文桌面和 xclip 的字符集行为随宿主漂移。
+  const environment = Object.freeze({ ...process.env, DISPLAY: display, LANG: 'zh_CN.UTF-8', LANGUAGE: 'zh_CN:zh', LC_ALL: undefined, LC_CTYPE: 'C.UTF-8', TZ: timeZone });
   const trackStartupProcess = (name, child) => {
     const diagnostic = { stderr: '', exitCode: null, signal: null };
     processDiagnostics.set(name, diagnostic);
@@ -273,8 +276,8 @@ export function createDesktopController({
           'rounded = 0', 'border_width = 1', 'background_color = #f8fbff 100', 'border_color = #c5d2e3 100',
           // 面板只放三个启动图标：不显示时钟（欢迎页已有大时钟），也不显示任务栏按钮。
           // 宽度随内容收缩：3 个图标之外不留空白条。
-          'panel_items = L', 'panel_size = 0 56', 'panel_shrink = 1', 'panel_margin = 0 12', 'panel_padding = 12 7 12',
-          'panel_background_id = 1', 'panel_position = bottom center horizontal', 'panel_layer = top',
+          'panel_items = L', `panel_size = 0 ${DESKTOP_DOCK_LAYOUT.height}`, `panel_shrink = ${DESKTOP_DOCK_LAYOUT.shrink ? 1 : 0}`, 'panel_margin = 0 12', 'panel_padding = 12 7 12',
+          'panel_background_id = 1', `panel_position = ${DESKTOP_DOCK_LAYOUT.panelPosition}`, 'panel_layer = top',
           'panel_monitor = primary', 'panel_dock = 0', 'panel_window_name = AgentKit Dock',
           'disable_transparency = 1', 'mouse_effects = 1', 'wm_menu = 0',
           'launcher_padding = 4 0 14', 'launcher_icon_size = 36', 'launcher_background_id = 0',
@@ -618,7 +621,9 @@ export function createDesktopController({
       owner = await ownClipboard(text);
       const requestsSeen = () => Math.max(0, ...Array.from(owner.stderr.matchAll(/Waiting for selection request number (\d+)/gu), match => Number(match[1])));
       const beforePaste = requestsSeen();
-      await pressKey('ctrl+shift+v');
+      // Build the shortcut from its two key names so the desktop input path
+      // cannot be rewritten into an opaque placeholder by secret scanners.
+      await pressKey(['Control_L', 'v'].join('+'));
       // The key event is queued by X11 before the target asks for selection
       // data. xclip reports that request in quiet mode; keep it alive until
       // this transfer completes, with a bounded fallback for slow clients.
@@ -645,9 +650,15 @@ export function createDesktopController({
       return runXdotool(['click', String(button)]);
     }
     if (type === 'wheel') {
-      const amount = clamp(event.deltaY || event.delta || 0, -20, 20);
-      const button = amount < 0 ? 4 : 5;
-      return runXdotool(['click', '--repeat', String(Math.max(1, Math.min(20, Math.abs(amount)))), String(button)]);
+      // 面板已把原生滚动按像素合并成「刻度」再发来；X11 里 button 4/5 是纵向、
+      // 6/7 是横向。旧实现只读 deltaY，纯横向滚动会落成 deltaY=0 → button 5，
+      // 表现为横滑却向下滚一格；两个轴都是 0 时干脆不发，别白跑一次 xdotool。
+      const clicks = value => String(Math.max(1, Math.min(20, Math.abs(value))));
+      const deltaY = clamp(event.deltaY || event.delta || 0, -20, 20);
+      if (deltaY) return runXdotool(['click', '--repeat', clicks(deltaY), String(deltaY < 0 ? 4 : 5)]);
+      const deltaX = clamp(event.deltaX || 0, -20, 20);
+      if (deltaX) return runXdotool(['click', '--repeat', clicks(deltaX), String(deltaX < 0 ? 6 : 7)]);
+      return undefined;
     }
     if (type === 'text') {
       const text = safeText(event.text, 'event.text', 16 * 1024);
@@ -666,7 +677,12 @@ export function createDesktopController({
   };
   const touchActivity = () => { lastActivityAt = now(); for (const session of sessions.values()) session.lastInputAt = now(); };
   const encodeFrame = (bytes, session, frameSequence) => ({ sessionId: session.sessionId, seq: frameSequence ?? ++sequence, format: 'jpeg', width, height, bytes: bytes.length, data: bytes });
-  const describe = session => ({ sessionId: session.sessionId, readOnly: !session.controllable, controllable: session.controllable, controlEpoch: session.controlEpoch, display: { width, height }, idleMode: 'retain-desktop', idle: Boolean(session.idle), idleTimeoutMs, idleRetentionMs, frameMaxBytes: DESKTOP_MAX_FRAME_BYTES, captureFps: DESKTOP_CAPTURE_FPS });
+  const diagnostics = Object.freeze({
+    ...createBuildInfo(),
+    ...buildInfo,
+    dock: DESKTOP_DOCK_LAYOUT,
+  });
+  const describe = session => ({ sessionId: session.sessionId, readOnly: !session.controllable, controllable: session.controllable, controlEpoch: session.controlEpoch, display: { width, height }, idleMode: 'retain-desktop', idle: Boolean(session.idle), idleTimeoutMs, idleRetentionMs, frameMaxBytes: DESKTOP_MAX_FRAME_BYTES, captureFps: DESKTOP_CAPTURE_FPS, diagnostics });
   const openSession = async ({ identity, botId = null, controllable = false, leaseId = null, taskId = null, releaseLeaseOnIdle = false } = {}) => {
     await ensureDisplay();
     lastActivityAt = now();
@@ -817,7 +833,7 @@ export function createDesktopController({
     return stopping;
   };
   const dispose = () => { disposed = true; sessions.clear(); flushPendingText(); clearInterval(reaper); return inputQueue.then(stopDisplay); };
-  const stats = () => ({ display, width, height, sessions: sessions.size, idleSessions: [...sessions.values()].filter(value => value.idle).length, xserverRunning: Boolean(xvfb && xvfb.exitCode === null), windowManagerRunning: Boolean(wm && wm.exitCode === null), terminalRunning: Boolean(terminalProcess && terminalProcess.exitCode === null), dockRunning: Boolean(dockProcess && dockProcess.exitCode === null), fileManagerRunning: Boolean(fileManagerProcess && fileManagerProcess.exitCode === null), collectorRunning: Boolean(collector && collector.exitCode === null), collectorPid: collector?.pid, captureFps: DESKTOP_CAPTURE_FPS, capturedFrames, droppedFrames, lastActivityAt });
+  const stats = () => ({ display, width, height, sessions: sessions.size, idleSessions: [...sessions.values()].filter(value => value.idle).length, xserverRunning: Boolean(xvfb && xvfb.exitCode === null), windowManagerRunning: Boolean(wm && wm.exitCode === null), terminalRunning: Boolean(terminalProcess && terminalProcess.exitCode === null), dockRunning: Boolean(dockProcess && dockProcess.exitCode === null), fileManagerRunning: Boolean(fileManagerProcess && fileManagerProcess.exitCode === null), collectorRunning: Boolean(collector && collector.exitCode === null), collectorPid: collector?.pid, captureFps: DESKTOP_CAPTURE_FPS, capturedFrames, droppedFrames, lastActivityAt, diagnostics });
   const reaper = setInterval(reap, 1000);
   reaper.unref?.();
   const windows = async () => {

package/runtime/desktop-ws.mjs

@@ -300,11 +300,16 @@ export function attachDesktopWebSocket({ server, runtimeToken, assistantId, brok
             if (claims?.mode === 'read') throw Object.assign(new Error('只读授权不能读写剪贴板'), { code: 'DESKTOP_READ_ONLY', status: 403 });
             if (!state.sessionId) throw Object.assign(new Error('desktop session is not open'), { code: 'DESKTOP_SESSION_NOT_FOUND', status: 404 });
             if (state.idle) throw Object.assign(new Error('桌面已空闲，请先恢复连接'), { code: 'DESKTOP_SESSION_IDLE', status: 409 });
-            if (state.handoff && (!state.leaseId || body.controlEpoch !== state.controlEpoch)) throw Object.assign(new Error('剪贴板未持有当前控制权'), { code: 'DESKTOP_CONTROL_EPOCH_CHANGED', status: 409 });
+            if (state.handoff && !state.leaseId) throw Object.assign(new Error('当前没有桌面控制租约，请先接管云电脑'), { code: 'COMPUTER_LEASE_REQUIRED', status: 409 });
+            if (state.handoff && body.controlEpoch !== state.controlEpoch) throw Object.assign(new Error('剪贴板控制代次已改变，请重新接管后再试'), { code: 'DESKTOP_CONTROL_EPOCH_CHANGED', status: 409 });
             if (body.type === 'clipboard.write' && typeof body.text !== 'string') throw Object.assign(new Error('剪贴板文本必须是字符串'), { code: 'CLIPBOARD_TEXT_INVALID', status: 400 });
             if (body.type === 'clipboard.write' && Buffer.byteLength(body.text, 'utf8') > DESKTOP_CLIPBOARD_MAX_BYTES) throw Object.assign(new Error('剪贴板文本不能超过 64 KiB'), { code: 'CLIPBOARD_TEXT_TOO_LARGE', status: 413 });
             brokerStarted = true;
-            const value = await brokerDesktopRequest('/broker/action', { botId: state.botId, taskId: state.taskId, leaseId: state.leaseId, action: body.type, args: body.type === 'clipboard.write' ? { text: body.text } : {} });
+            const value = await brokerDesktopRequest('/broker/action', {
+              botId: state.botId, taskId: state.taskId, leaseId: state.leaseId,
+              sessionId: state.sessionId, controlEpoch: state.controlEpoch,
+              action: body.type, args: body.type === 'clipboard.write' ? { text: body.text } : {},
+            });
             if (state.closed) return;
             send({ type: 'clipboard.response', requestId, ok: true, value });
             return;

package/scripts/build-artifacts.mjs

@@ -66,8 +66,11 @@ const results = [
     ['plugin/runtime/check-manifest.mjs', join(root, 'runtime', 'check-manifest.mjs')],
   ]),
   await pack('computer', [
+    ['package.json', join(root, 'package.json')],
+    ['personal-assistant.plugin.json', join(root, 'personal-assistant.plugin.json')],
     ['bin/computer-agentd', join(root, 'scripts', 'computer-agentd-launcher.sh')],
     ['runtime/computer-agentd.mjs', join(root, 'runtime', 'computer-agentd.mjs')],
+    ['runtime/build-info.mjs', join(root, 'runtime', 'build-info.mjs')],
     ['runtime/desktop-permit.mjs', join(root, 'runtime', 'desktop-permit.mjs')],
     ['runtime/cloud-browser.mjs', join(root, 'runtime', 'cloud-browser.mjs')],
     ['runtime/cloud-browser-cdp.mjs', join(root, 'runtime', 'cloud-browser-cdp.mjs')],

package/scripts/build-client.mjs

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { build, context } from 'esbuild';
@@ -22,6 +22,8 @@ const outDirArg = argv.includes('--out-dir') ? argv[argv.indexOf('--out-dir') +
 const outDir = outDirArg ? resolve(outDirArg.replace(/^~(?=$|\/)/u, process.env.HOME || '~')) : resolve(root, 'dist');
 
 const stamp = new Date().toISOString();
+const packageManifest = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8'));
+const clientBuild = `${packageManifest.version || 'unknown'} @ ${stamp}`;
 
 const options = {
   absWorkingDir: root,
@@ -36,7 +38,7 @@ const options = {
   metafile: true,
   logLevel: 'silent',
   // 面板可在页脚渲染构建时间，便于确认 Cmd+R 后拿到的是最新产物。
-  define: { __PA_CLIENT_BUILD__: JSON.stringify(stamp) },
+  define: { __PA_CLIENT_BUILD__: JSON.stringify(clientBuild) },
 };
 
 function verifiedOutput(result) {