@skylandnpm/octopus-proxy 0.1.33 → 0.1.34

package/README.md

@@ -18,8 +18,12 @@ octopus-proxy identity
 
 Proxy 主动连接 Hub 的 `/ws/proxy-chat`，无需开放入站端口或安装 sshd。Claw 经 `/ws/claw-chat` 建立到 Proxy 的内层 TLS 1.3 会话；Hub 只转发加密字节。首次打开工作区显示主机公钥指纹，点击 Trust 后按 Hub 地址和机器人 ID 固定；之后指纹变化会拒绝连接。每次连接都要输入运行 Proxy 服务账号的主机密码，由主机上的 PAM（Linux）或 Open Directory（macOS）验证。断线或连续 60 分钟没有用户操作后需要重新认证。服务安装时生成主机身份，`octopus-proxy identity` 可在主机上查看指纹。安装主机需提供 OpenSSL 和 C 编译器；Linux 还需 PAM 开发头文件。机器人 Secret 仅用于 Hub 路由，不能单独授权工作区。
 
+macOS 12.3 及以上运行 `octopus-proxy onboard` 时，配置保存后、服务启动前会准备截屏辅助程序并申请系统屏幕录制权限；已授权时不会重复弹窗。交互模式和 `--non-interactive` 均执行此步骤，`--no-install-service` 也会申请。请在系统弹窗中允许访问；拒绝、超时或辅助程序编译失败时，向导提示原因与授权路径，并继续初始化。之后可在“系统设置 → 隐私与安全性 → 屏幕录制（或屏幕与系统音频录制）”中授权 `octopus-desktop-capture` 或系统列出的启动程序，再重启 Proxy。Linux 没有通用的截屏授权弹窗，需使用桌面用户的图形会话环境；平台依赖与设置见[桌面快照说明](../../docs/claw-desktop-snapshots.md)。
+
 添加授权项目时，填写项目 ID 后会询问是否继续添加；直接回车即可结束添加并继续保存配置。
 
+`octopus-proxy doctor` 会显示“桌面截屏支持”和“屏幕录制权限”：macOS 检查系统版本、辅助程序、活动显示器和当前授权状态；未授权时给出 onboard 申请及系统设置指引。Linux 检查图形会话、显示器和截屏依赖，缺少依赖、无桌面或不支持的 Wayland 环境会显示具体提示；Linux 无统一的授权查询接口，因此会明确显示权限尚无法确认，需在 Claw 实际截屏验证。诊断不触发授权弹窗、不截屏，`doctor --fix` 也不会自动申请截屏权限。这些检查使用运行 doctor 的用户与环境；服务以其他启动程序或图形会话运行时，其权限与环境需要单独确认。
+
 如果旧配置中的项目 ID 重复或有错误项，先列出项目，再按序号删除指定项。此命令直接读取原始配置，因此配置校验失败时也能使用；删除前会生成仅当前用户可读的备份。清理完成后检查配置并重启服务：
 
 ```sh

package/dist/{chunk-2RX5VSBS.js → chunk-BIL5ROSQ.js}

@@ -11714,8 +11714,8 @@ async function ensureHostIdentity(stateDirectory) {
 }
 
 // src/daemon.ts
-import { mkdir as mkdir9 } from "node:fs/promises";
-import { join as join12 } from "node:path";
+import { mkdir as mkdir10 } from "node:fs/promises";
+import { join as join13 } from "node:path";
 
 // src/workspace-diff.ts
 import { execFile as execFile2 } from "node:child_process";
@@ -12247,6 +12247,9 @@ var Operations = [
   "terminal.remove",
   "terminal.input",
   "terminal.attach",
+  "desktop.list",
+  "desktop.capture",
+  "desktop.read",
   "artifacts.list",
   "artifacts.history",
   "artifacts.read",
@@ -12266,7 +12269,7 @@ var CommandSchema = z.object({
   sessionId: z.string().optional(),
   payload: z.record(z.unknown()).default({})
 }).strict();
-var isReadOperation = (operation) => /\.(status|snapshot|list|get|messages|diff|todos|children|logs|projects|read|search|history|models|agents|commands|providers|mcp)$/.test(operation);
+var isReadOperation = (operation) => operation === "desktop.capture" || /\.(status|snapshot|list|get|messages|diff|todos|children|logs|projects|read|search|history|models|agents|commands|providers|mcp)$/.test(operation);
 
 // src/journal.ts
 var Journal = class {
@@ -12275,8 +12278,9 @@ var Journal = class {
   }
   active = /* @__PURE__ */ new Map();
   queues = /* @__PURE__ */ new Map();
-  execute(command, action) {
-    const hash = createHash4("sha256").update(JSON.stringify(command)).digest("hex"), active = this.active.get(command.id);
+  execute(command, action, owner) {
+    const activeKey = command.operation.startsWith("desktop.") ? JSON.stringify([owner, command.id]) : command.id;
+    const hash = createHash4("sha256").update(JSON.stringify(command)).digest("hex"), active = this.active.get(activeKey);
     if (active) {
       if (active.hash !== hash) return Promise.resolve(this.failure(command, "Request id reused"));
       return active.result;
@@ -12312,8 +12316,8 @@ var Journal = class {
       }).catch(() => {
       });
     }
-    this.active.set(command.id, { hash, result });
-    result.finally(() => this.active.delete(command.id)).catch(() => {
+    this.active.set(activeKey, { hash, result });
+    result.finally(() => this.active.delete(activeKey)).catch(() => {
     });
     return result;
   }
@@ -12841,7 +12845,7 @@ var SecureChat = class {
     }
     session.lastAction = Date.now();
     sendJson(session.tls, { type: "response", id: command.id, botId: command.botId, status: "accepted" });
-    const response = await this.journal.execute(command, () => this.dispatch(command, id));
+    const response = await this.journal.execute(command, () => this.dispatch(command, id), id);
     if (this.sessions.get(id) === session && session.authenticated) sendJson(session.tls, response);
   }
   closeSession(id) {
@@ -15745,7 +15749,10 @@ var DAEMON_OPERATIONS = [
   "terminal.resize",
   "terminal.remove",
   "terminal.input",
-  "terminal.attach"
+  "terminal.attach",
+  "desktop.list",
+  "desktop.capture",
+  "desktop.read"
 ];
 function unsupportedOperation(kind, operation) {
   throw new Error(`Unsupported ${kind} operation: ${operation}`);
@@ -17238,19 +17245,277 @@ var TerminalManager = class {
   }
 };
 
+// src/desktop.ts
+import { execFile as execFile6 } from "node:child_process";
+import { promisify as promisify6 } from "node:util";
+import { createHash as createHash9, randomUUID as randomUUID16 } from "node:crypto";
+import { chmod as chmod3, mkdir as mkdir9, mkdtemp, readFile as readFile9, rename as rename4, rm as rm3, stat as stat8 } from "node:fs/promises";
+import { join as join12 } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
+var DESKTOP_IMAGE_LIMIT = 20 * 1024 * 1024;
+var DESKTOP_CHUNK_LIMIT = 512 * 1024;
+var PNG_SIGNATURE = Buffer.from("89504e470d0a1a0a", "hex");
+var executeFile = promisify6(execFile6);
+var executeDesktop = async (file, args) => {
+  try {
+    return (await executeFile(file, args, { timeout: 15e3, killSignal: "SIGKILL", maxBuffer: 256 * 1024, encoding: "utf8" })).stdout;
+  } catch (error) {
+    const detail = error;
+    if (detail.code === "ENOENT") throw new Error(`\u684C\u9762\u622A\u5C4F\u7F3A\u5C11\u4F9D\u8D56\uFF1A${file}\u3002\u8BF7\u5728 Proxy \u4E3B\u673A\u5B89\u88C5\u540E\u91CD\u8BD5\u3002`);
+    if (detail.killed) throw new Error("\u684C\u9762\u622A\u5C4F\u8D85\u65F6\uFF0C\u8BF7\u68C0\u67E5 Proxy \u4E3B\u673A\u7684\u684C\u9762\u4F1A\u8BDD\u540E\u91CD\u8BD5\u3002");
+    throw new Error(`\u684C\u9762\u622A\u5C4F\u5931\u8D25\uFF1A${detail.stderr?.trim().slice(0, 2048) || detail.message}`);
+  }
+};
+var DESKTOP_PERMISSION_GUIDANCE = "\u8BF7\u5728\u201C\u7CFB\u7EDF\u8BBE\u7F6E \u2192 \u9690\u79C1\u4E0E\u5B89\u5168\u6027 \u2192 \u5C4F\u5E55\u5F55\u5236\uFF08\u6216\u5C4F\u5E55\u4E0E\u7CFB\u7EDF\u97F3\u9891\u5F55\u5236\uFF09\u201D\u4E2D\u6388\u6743 octopus-desktop-capture \u6216\u7CFB\u7EDF\u5217\u51FA\u7684\u542F\u52A8\u7A0B\u5E8F\uFF0C\u7136\u540E\u91CD\u542F Proxy\u3002";
+async function requestDesktopPermission(stateDirectory) {
+  return new PlatformDesktop(stateDirectory).requestScreenCapturePermission();
+}
+async function checkDesktop(stateDirectory) {
+  return new PlatformDesktop(stateDirectory).diagnose();
+}
+function parseXrandr(text) {
+  const displays = [];
+  for (const line of text.split("\n")) {
+    const match = /^\s*\d+:\s+([+*]*)(\S+)\s+(\d+)\/\d+x(\d+)\/\d+([+-]\d+)([+-]\d+)/.exec(line);
+    if (!match) continue;
+    const [, flags, id, width, height, x, y] = match;
+    displays.push({ id, name: id, primary: flags.includes("*"), builtIn: /^(eDP|LVDS|DSI)/i.test(id), width: Number(width), height: Number(height), x: Number(x), y: Number(y) });
+  }
+  return displays;
+}
+function parseWlrRandr(text) {
+  const displays = [];
+  for (const block of text.split(/(?=^\S)/m)) {
+    const name = /^(\S+)(?:\s+"(.*)")?/.exec(block);
+    const mode = /^\s+(\d+)x(\d+)\s+px[^\n]*\([^\n]*current[^\n]*\)/m.exec(block);
+    if (!name || !mode || !/^\s+Enabled:\s+yes\s*$/m.test(block)) continue;
+    const rotated = /^\s+Transform:\s+(?:90|270|flipped-90|flipped-270)\s*$/m.test(block);
+    displays.push({ id: name[1], name: name[2] || name[1], primary: false, builtIn: /^(eDP|LVDS|DSI)/i.test(name[1]), width: Number(mode[rotated ? 2 : 1]), height: Number(mode[rotated ? 1 : 2]) });
+  }
+  return displays;
+}
+function publicDisplay(display) {
+  return { id: display.id, name: display.name, primary: display.primary, builtIn: display.builtIn, width: display.width, height: display.height };
+}
+var PlatformDesktop = class {
+  constructor(stateDirectory, system = process.platform, environment = process.env, execute3 = executeDesktop) {
+    this.stateDirectory = stateDirectory;
+    this.system = system;
+    this.environment = environment;
+    this.execute = execute3;
+  }
+  helper;
+  linuxMode() {
+    if (this.environment.WAYLAND_DISPLAY || this.environment.XDG_SESSION_TYPE === "wayland") {
+      if (!this.environment.WAYLAND_DISPLAY || !this.environment.XDG_RUNTIME_DIR) throw new Error("Proxy \u672A\u8FDE\u63A5 Wayland \u684C\u9762\u4F1A\u8BDD\uFF0C\u8BF7\u4F7F\u7528\u684C\u9762\u7528\u6237\u7684 WAYLAND_DISPLAY \u548C XDG_RUNTIME_DIR\u3002");
+      return "wayland";
+    }
+    if (!this.environment.DISPLAY) throw new Error("Proxy \u4E3B\u673A\u6CA1\u6709\u53EF\u7528\u7684\u56FE\u5F62\u684C\u9762\u4F1A\u8BDD\uFF0C\u8BF7\u8BBE\u7F6E\u684C\u9762\u7528\u6237\u7684 DISPLAY \u548C XAUTHORITY\u3002");
+    return "x11";
+  }
+  macHelper() {
+    if (this.helper) return this.helper;
+    this.helper = (async () => {
+      await mkdir9(this.stateDirectory, { recursive: true, mode: 448 });
+      const target = join12(this.stateDirectory, "octopus-desktop-capture");
+      const source = fileURLToPath4(new URL("../native/desktop-macos.m", import.meta.url));
+      const sourceInfo = await stat8(source), existing = await stat8(target).catch(() => null);
+      if (existing?.isFile() && existing.mtimeMs >= sourceInfo.mtimeMs && (existing.mode & 63) === 0) return target;
+      const temporary = `${target}.${randomUUID16()}`;
+      try {
+        await this.execute("/usr/bin/clang", ["-O2", "-fobjc-arc", "-mmacosx-version-min=12.3", "-framework", "Foundation", "-framework", "AppKit", "-framework", "ScreenCaptureKit", "-framework", "CoreMedia", "-framework", "CoreVideo", "-framework", "VideoToolbox", "-framework", "ImageIO", source, "-o", temporary]);
+        await chmod3(temporary, 448);
+        await rename4(temporary, target);
+        return target;
+      } finally {
+        await rm3(temporary, { force: true });
+      }
+    })();
+    this.helper.catch(() => {
+      this.helper = void 0;
+    });
+    return this.helper;
+  }
+  async linuxDisplays() {
+    const wayland = this.linuxMode() === "wayland";
+    try {
+      const text = await this.execute(wayland ? "wlr-randr" : "xrandr", wayland ? [] : ["--listactivemonitors"]);
+      return wayland ? parseWlrRandr(text) : parseXrandr(text);
+    } catch (error) {
+      if (wayland) throw new Error(`${error instanceof Error ? error.message : error} \u9996\u7248 Wayland \u9700\u8981\u652F\u6301 wlr-output-management \u548C grim \u622A\u5C4F\u7684\u684C\u9762\uFF1BGNOME/KDE Wayland \u6682\u4E0D\u652F\u6301\u3002`);
+      throw error;
+    }
+  }
+  async requestScreenCapturePermission() {
+    if (this.system !== "darwin") return "not-required";
+    const result = (await this.execute(await this.macHelper(), ["request-permission"])).trim();
+    if (result !== "granted" && result !== "denied") throw new Error("\u5C4F\u5E55\u5F55\u5236\u6388\u6743\u68C0\u67E5\u8FD4\u56DE\u4E86\u65E0\u6548\u7ED3\u679C\u3002");
+    return result;
+  }
+  async diagnose() {
+    const results = [];
+    const record2 = (name, status, detail) => results.push({ name, status, detail });
+    try {
+      if (this.system === "darwin") {
+        const version = (await this.execute("/usr/bin/sw_vers", ["-productVersion"])).trim();
+        const match = /^(\d+)\.(\d+)(?:\.\d+)?$/.exec(version);
+        if (!match) throw new Error("\u65E0\u6CD5\u8BC6\u522B macOS \u7248\u672C\uFF0C\u65E0\u6CD5\u786E\u8BA4\u622A\u5C4F\u652F\u6301\u3002");
+        if (Number(match[1]) < 12 || Number(match[1]) === 12 && Number(match[2]) < 3) throw new Error(`macOS ${version} \u4E0D\u652F\u6301\u684C\u9762\u622A\u5C4F\uFF0C\u9700\u8981 macOS 12.3 \u53CA\u4EE5\u4E0A\u3002`);
+        const helper = await this.macHelper();
+        try {
+          const displays = await this.list();
+          record2("\u684C\u9762\u622A\u5C4F\u652F\u6301", "ok", `macOS ${version} \u652F\u6301 ScreenCaptureKit\uFF1B${displays.length} \u4E2A\u6D3B\u52A8\u663E\u793A\u5668\uFF1B\u8F85\u52A9\u7A0B\u5E8F\u53EF\u7528`);
+        } catch (error) {
+          record2("\u684C\u9762\u622A\u5C4F\u652F\u6301", "warn", error instanceof Error ? error.message : String(error));
+        }
+        try {
+          const permission = (await this.execute(helper, ["permission-status"])).trim();
+          if (permission !== "granted" && permission !== "denied") throw new Error("\u5C4F\u5E55\u5F55\u5236\u6388\u6743\u68C0\u67E5\u8FD4\u56DE\u4E86\u65E0\u6548\u7ED3\u679C\u3002");
+          record2("\u5C4F\u5E55\u5F55\u5236\u6743\u9650", permission === "granted" ? "ok" : "warn", permission === "granted" ? "\u5DF2\u6388\u6743\uFF08\u5F53\u524D\u7528\u6237\u53CA\u542F\u52A8\u7A0B\u5E8F\uFF09\uFF1B\u68C0\u67E5\u672A\u8BFB\u53D6\u684C\u9762\u56FE\u7247\u3002" : `\u672A\u6388\u6743\u6216\u6388\u6743\u5C1A\u672A\u751F\u6548\uFF1B\u8FD0\u884C octopus-proxy onboard \u7533\u8BF7\u3002${DESKTOP_PERMISSION_GUIDANCE}`);
+        } catch (error) {
+          record2("\u5C4F\u5E55\u5F55\u5236\u6743\u9650", "warn", `\u65E0\u6CD5\u68C0\u67E5\uFF1A${error instanceof Error ? error.message : error} ${DESKTOP_PERMISSION_GUIDANCE}`);
+        }
+      } else if (this.system === "linux") {
+        const mode = this.linuxMode();
+        if (mode === "wayland" && /(?:^|[:;])(GNOME|KDE|PLASMA)(?:$|[:;])/i.test(this.environment.XDG_CURRENT_DESKTOP ?? "")) throw new Error("GNOME/KDE Wayland \u6682\u4E0D\u652F\u6301\u684C\u9762\u622A\u5C4F\uFF1B\u8BF7\u4F7F\u7528 X11 \u6216\u517C\u5BB9 wlr-output-management \u4E0E grim \u7684 Wayland \u684C\u9762\u3002");
+        const displays = await this.list();
+        if (mode === "wayland") await this.execute("grim", ["-h"]);
+        else {
+          let version;
+          try {
+            version = await this.execute("magick", ["import", "-version"]);
+          } catch (error) {
+            if (!(error instanceof Error) || !error.message.startsWith("\u684C\u9762\u622A\u5C4F\u7F3A\u5C11\u4F9D\u8D56\uFF1Amagick\u3002")) throw error;
+            version = await this.execute("import", ["-version"]);
+          }
+          if (!/^(?:Features|Delegates[^:\r\n]*):[^\r\n]*\b(?:x|X11)\b/im.test(version)) throw new Error("ImageMagick \u672A\u542F\u7528 X11 \u652F\u6301\uFF0C\u8BF7\u5B89\u88C5\u652F\u6301 X11 \u7684 ImageMagick\u3002");
+        }
+        record2("\u684C\u9762\u622A\u5C4F\u652F\u6301", "ok", `${mode === "x11" ? "X11" : "Wayland"} \u56FE\u5F62\u4F1A\u8BDD\u53EF\u8BBF\u95EE\uFF1B${displays.length} \u4E2A\u6D3B\u52A8\u663E\u793A\u5668\uFF1B\u622A\u5C4F\u4F9D\u8D56\u53EF\u7528${mode === "wayland" ? "\uFF1B\u622A\u5C4F\u534F\u8BAE\u9700\u5B9E\u9645\u622A\u5C4F\u9A8C\u8BC1" : ""}`);
+        record2("\u5C4F\u5E55\u5F55\u5236\u6743\u9650", "warn", "Linux \u65E0\u7EDF\u4E00\u7684\u622A\u5C4F\u6388\u6743\u72B6\u6001\u63A5\u53E3\uFF1B\u5F53\u524D\u56FE\u5F62\u4F1A\u8BDD\u53EF\u8BBF\u95EE\uFF0C\u5B9E\u9645\u622A\u5C4F\u6743\u9650\u9700\u5728 Claw \u70B9\u51FB\u201C\u622A\u5C4F\u201D\u9A8C\u8BC1\u3002");
+      } else throw new Error(`\u5F53\u524D\u5E73\u53F0 ${this.system} \u4E0D\u652F\u6301\u684C\u9762\u622A\u5C4F\uFF0C\u4EC5\u652F\u6301 macOS 12.3 \u53CA\u4EE5\u4E0A\u548C Linux\u3002`);
+    } catch (error) {
+      record2("\u684C\u9762\u622A\u5C4F\u652F\u6301", "warn", error instanceof Error ? error.message : String(error));
+      record2("\u5C4F\u5E55\u5F55\u5236\u6743\u9650", "warn", "\u672A\u68C0\u67E5\uFF1A\u622A\u5C4F\u73AF\u5883\u6216\u4F9D\u8D56\u4E0D\u53EF\u7528\uFF1B\u8BF7\u5148\u5904\u7406\u201C\u684C\u9762\u622A\u5C4F\u652F\u6301\u201D\u7684\u63D0\u793A\u3002");
+    }
+    return results;
+  }
+  async list() {
+    let displays;
+    if (this.system === "darwin") {
+      displays = JSON.parse(await this.execute(await this.macHelper(), ["list"]));
+    } else if (this.system === "linux") {
+      displays = (await this.linuxDisplays()).map(publicDisplay);
+    } else throw new Error("\u684C\u9762\u622A\u5C4F\u4EC5\u652F\u6301 macOS 12.3 \u53CA\u4EE5\u4E0A\u548C Linux\u3002");
+    if (!displays.length) throw new Error("\u6CA1\u6709\u53EF\u622A\u5C4F\u7684\u6D3B\u52A8\u663E\u793A\u5668\uFF0C\u8BF7\u68C0\u67E5 Proxy \u4E3B\u673A\u7684\u56FE\u5F62\u4F1A\u8BDD\u3002");
+    return displays;
+  }
+  async capture(displayId) {
+    const display = (await this.list()).find((item) => item.id === displayId);
+    if (!display) throw new Error("\u6240\u9009\u663E\u793A\u5668\u5DF2\u65AD\u5F00\uFF0C\u8BF7\u5237\u65B0\u663E\u793A\u5668\u5217\u8868\u540E\u91CD\u8BD5\u3002");
+    await mkdir9(this.stateDirectory, { recursive: true, mode: 448 });
+    const directory = await mkdtemp(join12(this.stateDirectory, "desktop-capture-"));
+    const output = join12(directory, "screen.png");
+    try {
+      if (this.system === "darwin") {
+        await this.execute(await this.macHelper(), ["capture", display.id, output]);
+      } else if (this.linuxMode() === "wayland") {
+        await this.execute("grim", ["-o", display.id, "-t", "png", output]);
+      } else {
+        const region = (await this.linuxDisplays()).find((item) => item.id === display.id);
+        if (!region) throw new Error("\u6240\u9009\u663E\u793A\u5668\u5DF2\u65AD\u5F00\uFF0C\u8BF7\u5237\u65B0\u663E\u793A\u5668\u5217\u8868\u540E\u91CD\u8BD5\u3002");
+        if (region.x < 0 || region.y < 0) throw new Error("X11 \u663E\u793A\u5668\u5750\u6807\u8D85\u51FA\u6839\u7A97\u53E3\uFF0C\u8BF7\u68C0\u67E5\u663E\u793A\u5668\u5E03\u5C40\u3002");
+        const args = ["-silent", "-window", "root", "-crop", `${region.width}x${region.height}+${region.x}+${region.y}`, "+repage", `png:${output}`];
+        try {
+          await this.execute("magick", ["import", ...args]);
+        } catch (error) {
+          if (!(error instanceof Error) || !error.message.startsWith("\u684C\u9762\u622A\u5C4F\u7F3A\u5C11\u4F9D\u8D56\uFF1Amagick\u3002")) throw error;
+          await this.execute("import", args);
+        }
+      }
+      const info = await stat8(output);
+      if (!info.isFile() || !info.size || info.size > DESKTOP_IMAGE_LIMIT) throw new Error("\u684C\u9762\u622A\u56FE\u4E3A\u7A7A\u6216\u8D85\u8FC7 20 MiB \u4E0A\u9650\u3002");
+      return { display, bytes: await readFile9(output) };
+    } finally {
+      await rm3(directory, { recursive: true, force: true });
+    }
+  }
+};
+var DesktopManager = class {
+  constructor(backend) {
+    this.backend = backend;
+  }
+  captures = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  closed = false;
+  async dispatch(command, owner) {
+    if (this.closed) throw new Error("\u684C\u9762\u622A\u5C4F\u670D\u52A1\u5DF2\u505C\u6B62\u3002");
+    const p = command.payload;
+    if (command.operation === "desktop.list") return this.backend.list();
+    if (command.operation === "desktop.capture") {
+      if (typeof p.displayId !== "string" || !p.displayId) throw new Error("\u8BF7\u9009\u62E9\u663E\u793A\u5668\u3002");
+      if (this.pending.has(owner)) throw new Error("\u6B63\u5728\u622A\u5C4F\uFF0C\u8BF7\u7B49\u5F85\u5F53\u524D\u622A\u5C4F\u5B8C\u6210\u3002");
+      const token = {};
+      this.pending.set(owner, token);
+      try {
+        const { display, bytes } = await this.backend.capture(p.displayId);
+        if (this.closed || this.pending.get(owner) !== token) throw new Error("\u8FDE\u63A5\u5DF2\u9501\u5B9A\uFF0C\u622A\u5C4F\u7ED3\u679C\u5DF2\u4E22\u5F03\u3002");
+        if (!bytes.length || bytes.length > DESKTOP_IMAGE_LIMIT) throw new Error("\u684C\u9762\u622A\u56FE\u4E3A\u7A7A\u6216\u8D85\u8FC7 20 MiB \u4E0A\u9650\u3002");
+        if (bytes.length < 24 || !bytes.subarray(0, 8).equals(PNG_SIGNATURE) || bytes.toString("ascii", 12, 16) !== "IHDR") throw new Error("\u622A\u5C4F\u672A\u8FD4\u56DE\u6709\u6548\u7684 PNG \u56FE\u7247\u3002");
+        const width = bytes.readUInt32BE(16), height = bytes.readUInt32BE(20);
+        if (!width || !height) throw new Error("\u684C\u9762\u622A\u56FE\u5C3A\u5BF8\u65E0\u6548\u3002");
+        const info = { id: randomUUID16(), display: publicDisplay(display), capturedAt: (/* @__PURE__ */ new Date()).toISOString(), mime: "image/png", width, height, size: bytes.length, sha256: createHash9("sha256").update(bytes).digest("hex") };
+        this.clearCapture(owner);
+        const timer = setTimeout(() => this.clearCapture(owner), 6e4);
+        timer.unref();
+        this.captures.set(owner, { info, bytes, timer });
+        return info;
+      } finally {
+        if (this.pending.get(owner) === token) this.pending.delete(owner);
+      }
+    }
+    if (command.operation === "desktop.read") {
+      const capture = this.captures.get(owner);
+      if (!capture || p.id !== capture.info.id) throw new Error("\u5FEB\u7167\u5DF2\u8FC7\u671F\u6216\u4E0D\u53EF\u8BFB\u53D6\uFF0C\u8BF7\u91CD\u65B0\u622A\u5C4F\u3002");
+      const offset = p.offset ?? 0, length = p.length ?? DESKTOP_CHUNK_LIMIT;
+      if (typeof offset !== "number" || !Number.isSafeInteger(offset) || offset < 0 || offset > capture.bytes.length || typeof length !== "number" || !Number.isSafeInteger(length) || length < 1 || length > DESKTOP_CHUNK_LIMIT) throw new Error("\u5FEB\u7167\u8BFB\u53D6\u8303\u56F4\u65E0\u6548\u3002");
+      return { id: capture.info.id, offset, size: capture.info.size, mime: "image/png", sha256: capture.info.sha256, data: capture.bytes.subarray(offset, offset + length).toString("base64") };
+    }
+    throw new Error(`Unsupported desktop operation: ${command.operation}`);
+  }
+  clearCapture(owner) {
+    const capture = this.captures.get(owner);
+    if (capture) {
+      clearTimeout(capture.timer);
+      capture.bytes.fill(0);
+      this.captures.delete(owner);
+    }
+  }
+  closeOwned(owner) {
+    this.pending.delete(owner);
+    this.clearCapture(owner);
+  }
+  close() {
+    this.closed = true;
+    this.pending.clear();
+    for (const owner of this.captures.keys()) this.clearCapture(owner);
+  }
+};
+
 // src/daemon.ts
 async function runDaemon(configPath, authenticate = verifyHostPassword) {
   const config = await loadConfig(configPath);
-  await mkdir9(config.stateDirectory, { recursive: true, mode: 448 });
-  const workspace = new Workspace(config.projects), runtime = createRuntime(config), uploads = new Uploads(workspace, join12(config.stateDirectory, "uploads")), journal = new Journal(join12(config.stateDirectory, "journal"));
+  await mkdir10(config.stateDirectory, { recursive: true, mode: 448 });
+  const workspace = new Workspace(config.projects), runtime = createRuntime(config), uploads = new Uploads(workspace, join13(config.stateDirectory, "uploads")), journal = new Journal(join13(config.stateDirectory, "journal"));
   let secureChat;
   function emit(projectId, event, data) {
     secureChat?.publish(projectId, event, data);
   }
   const terminals = new TerminalManager(workspace, (owner, project, event, data) => secureChat?.sendTo(owner, project, event, data));
-  const adapter = createAdapter(runtime, workspace, uploads, emit), artifacts = new Artifacts(workspace, join12(config.stateDirectory, "artifacts"), emit);
+  const desktop = new DesktopManager(new PlatformDesktop(config.stateDirectory));
+  const adapter = createAdapter(runtime, workspace, uploads, emit), artifacts = new Artifacts(workspace, join13(config.stateDirectory, "artifacts"), emit);
   const projectRegistry = new ProjectRegistry(configPath, config, runtime, adapter);
   async function dispatch(c, secureSessionId) {
+    if (c.operation.startsWith("desktop.")) return desktop.dispatch(c, secureSessionId);
     if (c.operation.startsWith("terminal.")) return terminals.dispatch(c, secureSessionId);
     const p = c.payload;
     if (c.operation === "runtime.status") return { ...await runtime.status(), capabilities: adapter.supportedOperations() };
@@ -17309,7 +17574,10 @@ async function runDaemon(configPath, authenticate = verifyHostPassword) {
   }
   const identity = await ensureHostIdentity(config.stateDirectory);
   await ensureHostAuth(config.stateDirectory);
-  secureChat = new SecureChat(config, identity, journal, dispatch, (owner) => terminals.closeOwned(owner), authenticate);
+  secureChat = new SecureChat(config, identity, journal, dispatch, (owner) => {
+    terminals.closeOwned(owner);
+    desktop.closeOwned(owner);
+  }, authenticate);
   await runtime.init().catch((error) => console.error(`${runtime.kind} startup:`, error.message));
   secureChat.start();
   const scan = setInterval(async () => {
@@ -17326,6 +17594,7 @@ async function runDaemon(configPath, authenticate = verifyHostPassword) {
     clearInterval(scan);
     secureChat?.stop();
     terminals.close();
+    desktop.close();
     runtime.detach();
     adapter.close();
   }
@@ -17363,5 +17632,8 @@ export {
   ensureHostIdentity,
   createRuntime,
   createAdapter,
+  DESKTOP_PERMISSION_GUIDANCE,
+  requestDesktopPermission,
+  checkDesktop,
   runDaemon
 };

package/dist/cli.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import {
   ConfigError,
+  DESKTOP_PERMISSION_GUIDANCE,
   SERVICE_LABEL,
   SYSTEMD_UNIT,
   TOOL_KINDS,
   Uploads,
   Workspace,
   atomicJson,
+  checkDesktop,
   createAdapter,
   createRuntime,
   daemonEntryPath,
@@ -20,11 +22,12 @@ import {
   launchdPlistPath,
   loadConfig,
   proxyVersion,
+  requestDesktopPermission,
   resolveConfigPath,
   runDaemon,
   supportedPlatform,
   systemdUnitPath
-} from "./chunk-2RX5VSBS.js";
+} from "./chunk-BIL5ROSQ.js";
 
 // src/cli.ts
 import { spawn } from "node:child_process";
@@ -357,6 +360,7 @@ async function runDoctor(opts) {
     record("\u914D\u7F6E\u6821\u9A8C", "fail", error instanceof Error ? error.message : String(error));
   }
   if (config) {
+    results.push(...await checkDesktop(config.stateDirectory));
     try {
       await mkdir3(config.stateDirectory, { recursive: true, mode: 448 });
       await access2(config.stateDirectory, constants.W_OK);
@@ -383,6 +387,10 @@ async function runDoctor(opts) {
       }
     }
   }
+  if (!config) {
+    record("\u684C\u9762\u622A\u5C4F\u652F\u6301", "warn", "\u672A\u68C0\u67E5\uFF1A\u914D\u7F6E\u4E0D\u53EF\u7528\uFF1B\u5148\u8FD0\u884C octopus-proxy onboard \u6216\u4FEE\u590D\u914D\u7F6E\u3002");
+    record("\u5C4F\u5E55\u5F55\u5236\u6743\u9650", "warn", "\u672A\u68C0\u67E5\uFF1A\u65E0\u6CD5\u786E\u5B9A\u622A\u5C4F\u8F85\u52A9\u7A0B\u5E8F\u7684\u72B6\u6001\u76EE\u5F55\u3002");
+  }
   if (config) {
     const probeConfig = { ...config, tool: { ...config.tool, autoStart: false } };
     const runtime = createRuntime(probeConfig), workspace = new Workspace(config.projects);
@@ -636,6 +644,14 @@ async function runOnboard(opts) {
   console.log(`\u5DF2\u5199\u5165\u914D\u7F6E\uFF1A${opts.configPath}\uFF080600\uFF09`);
   stateDirectory = expandHome(stateDirectory);
   await mkdir4(stateDirectory, { recursive: true, mode: 448 });
+  try {
+    if (platform2() === "darwin") console.log("\u6B63\u5728\u68C0\u67E5\u5C4F\u5E55\u5F55\u5236\u6743\u9650\uFF1B\u5982\u51FA\u73B0\u7CFB\u7EDF\u6388\u6743\u63D0\u793A\uFF0C\u8BF7\u5141\u8BB8 Proxy \u8BFB\u53D6\u684C\u9762\u3002");
+    const permission = await requestDesktopPermission(stateDirectory);
+    if (permission === "granted") console.log("\u5C4F\u5E55\u5F55\u5236\u6743\u9650\uFF1A\u5DF2\u6388\u6743\uFF0C\u53EF\u5728 Claw \u7684\u201C\u5FEB\u7167\u201D\u4E2D\u622A\u5C4F\u3002");
+    else if (permission === "denied") console.log(`\u8B66\u544A\uFF1A\u5C1A\u672A\u83B7\u5F97\u5C4F\u5E55\u5F55\u5236\u6743\u9650\uFF0C\u521D\u59CB\u5316\u5C06\u7EE7\u7EED\u3002${DESKTOP_PERMISSION_GUIDANCE}`);
+  } catch (error) {
+    console.log(`\u8B66\u544A\uFF1A\u65E0\u6CD5\u7533\u8BF7\u5C4F\u5E55\u5F55\u5236\u6743\u9650\uFF0C\u521D\u59CB\u5316\u5C06\u7EE7\u7EED\uFF1A${error instanceof Error ? error.message : error} ${DESKTOP_PERMISSION_GUIDANCE}`);
+  }
   try {
     const response = await fetch(hubUrl, { redirect: "manual", signal: AbortSignal.timeout(5e3) });
     console.log(`Hub \u8FDE\u901A\u6027\uFF1AHTTP ${response.status}`);

package/dist/main.js

@@ -2,7 +2,7 @@
 import {
   ConfigError,
   runDaemon
-} from "./chunk-2RX5VSBS.js";
+} from "./chunk-BIL5ROSQ.js";
 
 // src/main.ts
 runDaemon(process.env.OCTOPUS_PROXY_CONFIG ?? "proxy.json").catch((error) => {

package/native/desktop-macos.m

@@ -0,0 +1,141 @@
+#import <AppKit/AppKit.h>
+#import <ScreenCaptureKit/ScreenCaptureKit.h>
+#import <ImageIO/ImageIO.h>
+#import <VideoToolbox/VideoToolbox.h>
+
+static BOOL finished = NO;
+static int resultCode = 1;
+
+static void fail(NSString *message) {
+  fprintf(stderr, "%s\n", message.UTF8String);
+  resultCode = 1;
+  finished = YES;
+}
+
+static NSString *permissionMessage(void) {
+  return @"无法读取桌面。请在 Proxy 主机的“系统设置 → 隐私与安全性 → 屏幕录制（或屏幕与系统音频录制）”中授权 octopus-desktop-capture 或其启动程序，并重启 Proxy 后重试。";
+}
+
+static NSDictionary *displayInfo(CGDirectDisplayID displayId) {
+  NSString *name = [NSString stringWithFormat:@"显示器 %u", displayId];
+  for (NSScreen *screen in NSScreen.screens) {
+    if ([screen.deviceDescription[@"NSScreenNumber"] unsignedIntValue] == displayId) {
+      name = screen.localizedName;
+      break;
+    }
+  }
+  return @{@"id": [NSString stringWithFormat:@"%u", displayId], @"name": name,
+           @"primary": @((BOOL)(displayId == CGMainDisplayID())), @"builtIn": @((BOOL)CGDisplayIsBuiltin(displayId)),
+           @"width": @(CGDisplayPixelsWide(displayId)), @"height": @(CGDisplayPixelsHigh(displayId))};
+}
+
+@interface DesktopFrame : NSObject <SCStreamOutput, SCStreamDelegate>
+@property(nonatomic, strong) SCStream *stream;
+@property(nonatomic, copy) NSString *path;
+@property(nonatomic) BOOL received;
+@end
+
+@implementation DesktopFrame
+- (void)stream:(SCStream *)stream didStopWithError:(NSError *)error {
+  dispatch_async(dispatch_get_main_queue(), ^{ if (!finished) fail(permissionMessage()); });
+}
+- (void)stream:(SCStream *)stream didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer ofType:(SCStreamOutputType)type {
+  if (self.received || type != SCStreamOutputTypeScreen || !CMSampleBufferIsValid(sampleBuffer)) return;
+  NSArray *attachments = (__bridge NSArray *)CMSampleBufferGetSampleAttachmentsArray(sampleBuffer, NO);
+  NSNumber *status = attachments.firstObject[SCStreamFrameInfoStatus];
+  if (!status || status.integerValue != SCFrameStatusComplete) return;
+  CVPixelBufferRef pixel = CMSampleBufferGetImageBuffer(sampleBuffer);
+  if (!pixel) return;
+  self.received = YES;
+  CGImageRef image = NULL;
+  OSStatus conversion = VTCreateCGImageFromCVPixelBuffer(pixel, NULL, &image);
+  BOOL saved = NO;
+  if (conversion == noErr && image) {
+    CGImageDestinationRef destination = CGImageDestinationCreateWithURL((__bridge CFURLRef)[NSURL fileURLWithPath:self.path], CFSTR("public.png"), 1, NULL);
+    if (destination) {
+      CGImageDestinationAddImage(destination, image, NULL);
+      saved = CGImageDestinationFinalize(destination);
+      CFRelease(destination);
+    }
+    CGImageRelease(image);
+  }
+  [stream stopCaptureWithCompletionHandler:^(NSError *error) {
+    dispatch_async(dispatch_get_main_queue(), ^{
+      if (finished) return;
+      if (saved) { resultCode = 0; finished = YES; }
+      else fail(@"无法保存桌面 PNG 截图，请检查 Proxy 状态目录。" );
+    });
+  }];
+}
+@end
+
+int main(int argc, const char *argv[]) {
+  @autoreleasepool {
+    if (@available(macOS 12.3, *)) {
+      if (argc == 2 && strcmp(argv[1], "permission-status") == 0) {
+        puts(CGPreflightScreenCaptureAccess() ? "granted" : "denied");
+        return 0;
+      }
+      if (argc == 2 && strcmp(argv[1], "request-permission") == 0) {
+        BOOL granted = CGPreflightScreenCaptureAccess();
+        if (!granted) granted = CGRequestScreenCaptureAccess();
+        puts(granted ? "granted" : "denied");
+        return 0;
+      }
+      if (argc == 2 && strcmp(argv[1], "list") == 0) {
+        CGDirectDisplayID ids[64];
+        uint32_t count = 0;
+        if (CGGetActiveDisplayList(64, ids, &count) != kCGErrorSuccess) {
+          fail(@"无法读取活动显示器，请检查 Proxy 是否运行在已登录的图形桌面会话中。" );
+          return 1;
+        }
+        NSMutableArray *displays = [NSMutableArray array];
+        for (uint32_t i = 0; i < count; i++) {
+          if (CGDisplayMirrorsDisplay(ids[i]) == kCGNullDirectDisplay) [displays addObject:displayInfo(ids[i])];
+        }
+        NSData *data = [NSJSONSerialization dataWithJSONObject:displays options:0 error:NULL];
+        fwrite(data.bytes, 1, data.length, stdout);
+        return 0;
+      }
+      if (argc != 4 || strcmp(argv[1], "capture") != 0) { fail(@"截屏参数无效。" ); return 1; }
+      char *end = NULL;
+      unsigned long requested = strtoul(argv[2], &end, 10);
+      if (!requested || *end || requested > UINT32_MAX) { fail(@"显示器 ID 无效。" ); return 1; }
+      if (!CGPreflightScreenCaptureAccess()) {
+        CGRequestScreenCaptureAccess();
+        fail(permissionMessage());
+        return 1;
+      }
+      DesktopFrame *frame = [DesktopFrame new];
+      frame.path = [NSString stringWithUTF8String:argv[3]];
+      [SCShareableContent getShareableContentExcludingDesktopWindows:NO onScreenWindowsOnly:YES completionHandler:^(SCShareableContent *content, NSError *error) {
+        if (error || !content) { dispatch_async(dispatch_get_main_queue(), ^{ fail(permissionMessage()); }); return; }
+        SCDisplay *display = nil;
+        for (SCDisplay *candidate in content.displays) if (candidate.displayID == (CGDirectDisplayID)requested) { display = candidate; break; }
+        if (!display) { dispatch_async(dispatch_get_main_queue(), ^{ fail(@"所选显示器已断开，请刷新显示器列表后重试。" ); }); return; }
+        SCContentFilter *filter = [[SCContentFilter alloc] initWithDisplay:display excludingWindows:@[]];
+        SCStreamConfiguration *configuration = [SCStreamConfiguration new];
+        configuration.width = CGDisplayPixelsWide(display.displayID);
+        configuration.height = CGDisplayPixelsHigh(display.displayID);
+        configuration.pixelFormat = kCVPixelFormatType_32BGRA;
+        configuration.showsCursor = YES;
+        configuration.queueDepth = 3;
+        configuration.minimumFrameInterval = CMTimeMake(1, 30);
+        frame.stream = [[SCStream alloc] initWithFilter:filter configuration:configuration delegate:frame];
+        NSError *outputError = nil;
+        if (![frame.stream addStreamOutput:frame type:SCStreamOutputTypeScreen sampleHandlerQueue:dispatch_queue_create("octopus.desktop.frame", DISPATCH_QUEUE_SERIAL) error:&outputError]) {
+          dispatch_async(dispatch_get_main_queue(), ^{ fail(@"无法启动桌面截屏。" ); }); return;
+        }
+        [frame.stream startCaptureWithCompletionHandler:^(NSError *startError) {
+          if (startError) dispatch_async(dispatch_get_main_queue(), ^{ fail(permissionMessage()); });
+        }];
+      }];
+      NSDate *deadline = [NSDate dateWithTimeIntervalSinceNow:12];
+      while (!finished && deadline.timeIntervalSinceNow > 0) [[NSRunLoop mainRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.05]];
+      if (!finished) fail(@"桌面截屏超时，请检查主机的图形会话与屏幕录制权限。" );
+      return resultCode;
+    }
+    fail(@"桌面截屏需要 macOS 12.3 及以上。" );
+    return 1;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skylandnpm/octopus-proxy",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "type": "module",
   "description": "Octopus host proxy: OpenCode, Codex, ZCode and Pi adapters with service installer CLI",
   "bin": {