@xyagent/cli 1.0.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyagent/cli",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "private": false,
   "description": "Relay-first CLI for pairing and bridging OpenClaw gateway traffic",
   "type": "module",
@@ -18,12 +18,12 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=18"
   },
   "scripts": {
     "build:plugin": "node scripts/build-openclaw-plugin.mjs",
     "prepublishOnly": "node scripts/build-openclaw-plugin.mjs",
-    "postinstall": "node -e 'import(process.cwd()+\"/src-ext/core/daemonRestart.mjs\").then(m=>m.kickstartDaemons()).catch(()=>{})'",
+    "postinstall": "node src-ext/postinstall.mjs",
     "test": "node --test --test-concurrency=1 'test/**/*.test.mjs'",
     "test:coverage": "node --test --experimental-test-coverage test/tunnel/core.test.mjs"
   },

package/src/tunnel_service.mjs

@@ -4,6 +4,8 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 
+import { buildPathString, resolveSiblingBinDirs } from "./core.mjs";
+
 export function startTunnelRuntime({
   localPort,
   relayUrl,
@@ -473,7 +475,7 @@ function getTunnelServiceStatus(localPort, runtime) {
   };
 }
 
-function writeTunnelLaunchScript({ localPort, startArgs, nodePath, agentlinkHome }) {
+export function writeTunnelLaunchScript({ localPort, startArgs, nodePath, agentlinkHome }) {
   const scriptPath = resolveTunnelLaunchScriptPath(localPort);
   fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
   const capturedHome = os.homedir();
@@ -482,12 +484,26 @@ function writeTunnelLaunchScript({ localPort, startArgs, nodePath, agentlinkHome
     const appData =
       (process.env.APPDATA ?? "").trim() ||
       path.join(capturedHome, "AppData", "Roaming");
+    // ScheduledTask 的 PATH 是注册表值，看不到安装时进程里的增量（尤其是桌面端
+    // 私有 Node 的目录）—— 与 bridge 启动脚本同口径快照 PATH，`%` 转义防意外展开。
+    // 兄弟目录解析显式用 win32 语义（生产 win 上与默认 path 等价；
+    // 让 macOS 上跑的单测也能验证真实的反斜杠路径拆解）。
+    const defaultPath = buildPathString(
+      [
+        ...resolveSiblingBinDirs(nodePath, path.win32),
+        path.join(capturedHome, ".volta", "bin"),
+        path.join(appData, "npm"),
+        "C:\\Program Files\\nodejs",
+      ],
+      ";",
+    );
     const script = [
       "@echo off",
       `set "HOME=${capturedHome}"`,
       `set "USERPROFILE=${capturedHome}"`,
       `set "APPDATA=${appData}"`,
       `set "AGENTLINK_HOME=${capturedAgentlinkHome}"`,
+      `set "PATH=${defaultPath.replaceAll("%", "%%")};%PATH%"`,
       `"${nodePath}" ${startArgs.map((arg) => quoteWindowsCommandArg(arg)).join(" ")}`,
       "",
     ].join("\r\n");

package/src-ext/bin.mjs

@@ -9,6 +9,14 @@ import { newCid } from "../src-shared/correlation.mjs";
 import { runAgentCommand } from "./commands/agent.mjs";
 import { runServiceCommand } from "./commands/service.mjs";
 import { printHelp } from "./commands/help.mjs";
+import { EXT_AGENT_RUNTIME_KINDS } from "./core/runtimeRegistry.mjs";
+
+// `agentlink-agent <runtime>` 承载的 runtime 集合。hermes 也走这里（它的 bridge
+// 就是 agentlink-agent hermes），所以不是直接用 EXT_AGENT_RUNTIME_KINDS，而是
+// 在其之上加 hermes —— 用登记表派生，避免这里再多一份手抄的 runtime 名单。
+const AGENT_SUBCOMMAND_RUNTIMES = Object.freeze([
+  ...EXT_AGENT_RUNTIME_KINDS, "hermes",
+]);
 
 const PKG_NAME = "agentlink-agent";
 
@@ -83,19 +91,12 @@ async function main() {
     node: process.version,
   });
 
-  process.on("SIGINT", () => {
-    log.info("bridge.signal.recv", "SIGINT", { signal: "SIGINT" });
-  });
-  process.on("SIGTERM", () => {
-    log.info("bridge.signal.recv", "SIGTERM", { signal: "SIGTERM" });
-  });
+  if (AGENT_SUBCOMMAND_RUNTIMES.includes(subcommand)) {
+    await runAgentCommand({ runtime: subcommand, options, positional, log });
+    return;
+  }
 
   switch (subcommand) {
-    case "claude":
-    case "codex":
-    case "hermes":
-      await runAgentCommand({ runtime: subcommand, options, positional, log });
-      return;
     case "service":
       await runServiceCommand({ options, positional, log });
       return;

package/src-ext/commands/agent.mjs

@@ -1,7 +1,13 @@
 import { runClaudeBridge } from "../runtime/claude/index.mjs";
 import { runCodexBridge } from "../runtime/codex/index.mjs";
 import { runHermesBridge } from "../runtime/hermes/index.mjs";
+import { runCursorBridge } from "../runtime/cursor/index.mjs";
+import { runOpenCodeBridge } from "../runtime/opencode/index.mjs";
+import { runQwenBridge } from "../runtime/qwen/index.mjs";
+import { runKimiBridge } from "../runtime/kimi/index.mjs";
+import { runCodeBuddyBridge } from "../runtime/codebuddy/index.mjs";
 import { runPairInstall, runUninstall } from "./pair.mjs";
+import { hasBridgeImplementation } from "../core/runtimeRegistry.mjs";
 
 /**
  * `agentlink-agent <runtime> [action] [args]` 分发。
@@ -32,6 +38,19 @@ export async function runAgentCommand({ runtime, options, positional, log }) {
     return;
   }
 
+  // 到这里说明用户要的是**前台 bridge**。配对能力与桥接能力是两层（见
+  // core/runtimeRegistry.mjs）：opencode 本轮能配对、但没有 bridge 实现。
+  // 必须在这里显式说清楚，而不是掉进下面 switch 的 default 报一句含糊的
+  // "unsupported runtime"（用户刚配对成功，会以为是自己装错了）。
+  if (!hasBridgeImplementation(runtime)) {
+    rtLog.error("bridge.not_implemented", "runtime is pairable but has no bridge implementation", { runtime });
+    process.stderr.write(
+      `runtime \`${runtime}\` 本轮只支持配对（pair / uninstall），还没有 bridge 实现。\n` +
+      `配对凭证已可正常保存；等 bridge 落地后无需重新配对。\n`,
+    );
+    process.exit(2);
+  }
+
   rtLog.info("bridge.preflight.pass", "runtime dispatcher entered", {
     runtime,
     args_count: positional.length,
@@ -47,6 +66,21 @@ export async function runAgentCommand({ runtime, options, positional, log }) {
     case "hermes":
       await runHermesBridge({ options, positional, log: rtLog });
       return;
+    case "cursor":
+      await runCursorBridge({ options, positional, log: rtLog });
+      return;
+    case "opencode":
+      await runOpenCodeBridge({ options, positional, log: rtLog });
+      return;
+    case "qwen":
+      await runQwenBridge({ options, positional, log: rtLog });
+      return;
+    case "kimi":
+      await runKimiBridge({ options, positional, log: rtLog });
+      return;
+    case "codebuddy":
+      await runCodeBuddyBridge({ options, positional, log: rtLog });
+      return;
     default:
       rtLog.error("bridge.unknown_runtime", "unsupported runtime", { runtime });
       process.stderr.write(`unsupported runtime: ${runtime}\n`);

package/src-ext/commands/pair.mjs

@@ -26,13 +26,59 @@ import {
 } from "../service/serviceManager.mjs";
 import { ensureHermesApiServer } from "../runtime/hermes/envSetup.mjs";
 import { manageHermesGateway } from "../runtime/hermes/gatewayManager.mjs";
-import { ensureDefaultWorkspace } from "../core/defaultWorkspace.mjs";
+import { ensureDefaultWorkspace, DEFAULT_WORKSPACE_RUNTIMES } from "../core/defaultWorkspace.mjs";
+import { ensureRelayDefaultWorkspace } from "../core/defaultWorkspaceSync.mjs";
+import { hasBridgeImplementation } from "../core/runtimeRegistry.mjs";
+import { opencodePreflight } from "../runtime/opencode/preflight.mjs";
+import { deepagentsPreflight } from "../runtime/deepagents/preflight.mjs";
+import { qwenPreflight } from "../runtime/qwen/index.mjs";
+import { kimiPreflight } from "../runtime/kimi/index.mjs";
+import { codeBuddyPreflight } from "../runtime/codebuddy/index.mjs";
 import os from "node:os";
 import path from "node:path";
 
+/**
+ * 配对**前**要跑的 runtime 本机自检。
+ *
+ * 只登记「除了配对之外没有别的地方会校验二进制」的 runtime：claude / codex 的
+ * 二进制会在 bridge 启动时被各自的 preflight 拦住，pair 阶段不重复探（保持既有行为）；
+ * opencode 本轮没有 bridge，pair 是唯一的校验时机。
+ *
+ * 🔴 必须在 consumePairCode **之前**跑：配对码是一次性的，先消费再发现本机没装
+ * 会把用户的码白烧掉，只能回 App 重新出码。
+ */
+const PAIR_PREFLIGHTS = Object.freeze({
+  opencode: opencodePreflight,
+  deepagents: deepagentsPreflight,
+  qwen: qwenPreflight,
+  kimi: kimiPreflight,
+  codebuddy: codeBuddyPreflight,
+});
+
 export async function runPairInstall({ runtime, code, options, log }) {
   const relay = resolveRelayUrl(options.relay);
   const pLog = log.child({ comp: "pair" });
+
+  // 0. 本机自检（见 PAIR_PREFLIGHTS 注释：必须早于 consume）
+  const preflight = PAIR_PREFLIGHTS[runtime];
+  if (preflight) {
+    const pf = await preflight({ log: pLog });
+    if (!pf.ok) {
+      pLog.error("pair.preflight.failed", "runtime preflight failed before consume", {
+        runtime, err: pf.error || "",
+      });
+      process.stderr.write(
+        `配对失败：本机 ${runtime} 不可用。\n` +
+        `   ${pf.hint || pf.error || "runtime 预检未通过"}\n` +
+        `   配对码未被消费，装好后可用同一个码重试。\n`,
+      );
+      process.exit(65);
+    }
+    pLog.info("pair.preflight.ok", "runtime preflight passed", {
+      runtime, version: pf.version || "",
+    });
+  }
+
   pLog.info("pair.consume.start", "consuming pair code", { code, relay });
 
   // 1. consume
@@ -82,9 +128,16 @@ export async function runPairInstall({ runtime, code, options, log }) {
   // 2.6 align-runtime-default-workspace: 对 claude/codex 配对时 eager 创建默认工作区。
   // 这样新装用户配对完、打开 App 导入列表时，默认工作区已物理存在。
   // openclaw/hermes 有原生默认工作区（openclaw.json / profileHome），跳过。
-  if (runtime === "claude" || runtime === "codex") {
+  if (DEFAULT_WORKSPACE_RUNTIMES.includes(runtime)) {
     try {
-      const wsPath = await ensureDefaultWorkspace(runtime);
+      const profileName = runtime === "hermes" ? pairStateData.hermesProfileName : undefined;
+      const wsPath = await ensureDefaultWorkspace(runtime, { profileName });
+      await ensureRelayDefaultWorkspace({
+        runtime,
+        relayUrl: relay,
+        bridgeToken: pairStateData.bridge_token,
+        profileName,
+      });
       pLog.info("pair.default_workspace.created", "default workspace ensured", {
         runtime, path: wsPath,
       });
@@ -96,6 +149,19 @@ export async function runPairInstall({ runtime, code, options, log }) {
     }
   }
 
+  // 2.7 无 bridge 实现的 runtime（见 core/runtimeRegistry.mjs 的 PAIR_ONLY）：
+  // 配对到此为止。**不能**继续装 service —— service 里跑的是
+  // `agentlink-agent <runtime>`，没有 bridge 实现时它会立刻退出，只会给用户留下
+  // 一个反复重启的空转 launchd/systemd 单元 + 一句吓人的「进程 3 秒内未运行起来」。
+  // 也不做 MCP fanout（本轮没有对应适配器）。凭证已落地，bridge 落地后无需重配。
+  if (!hasBridgeImplementation(runtime)) {
+    pLog.info("pair.bridge.not_implemented", "paired; skipping service install (no bridge yet)", { runtime });
+    process.stdout.write(
+      `ℹ️  ${runtime} 本轮只支持配对：凭证已保存，后台服务与 MCP 配置留待 bridge 实现后接入。\n`,
+    );
+    return;
+  }
+
   // 3. 装 service（可被 --no-service / --manual 跳过）
   if (options["no-service"] || options.manual) {
     process.stdout.write("⚠️  已跳过后台服务安装（--no-service）\n");
@@ -230,7 +296,8 @@ export async function ensureHermesEnvAndProbe(log, opts = {}) {
     // 一套默认值 127.0.0.1:8642 在 listen，append 默认值不改行为）。
     restartMatters =
       r.overridden.length > 0 ||
-      r.appended.includes("API_SERVER_ENABLED");
+      r.appended.some((key) =>
+        key === "API_SERVER_ENABLED" || key === "API_SERVER_KEY");
   } else if (r.kept.length > 0) {
     // status === "ok"，但仍然把用户已设的 host/port 列出来给用户确认
     const keepStr = r.kept.map(({ key, value }) => `${key}=${value}`).join(", ");
@@ -408,33 +475,65 @@ export async function runUninstall({ runtime, options, log }) {
   // 1.5 撤 MCP fanout —— 把 ~/.claude.json / ~/.codex/config.toml /
   // ~/.hermes/config.yaml 里 agentlink server entry 删掉(用户其它 MCP server
   // 一字不动)。失败不致命,后面 service / state 清理继续。
+  //
+  // 两个清理各有各的闸，判据**不共用**：
+  //   · MCP 撤销 → 有没有 MCP 适配器（listAdapters()/hasMcpAdapter，唯一真相在
+  //     mcpRuntimeFanout 的 ADAPTERS 表）。没有适配器就没写过配置，deregister
+  //     只会回一条 unknown_runtime 的伪失败告警。
+  //   · service 卸载 → 有没有 bridge 实现（PAIR_ONLY runtime 压根没装过 service，
+  //     serviceUninstall 会撞「runtime must be one of ...」）。
+  // 曾经两者都挂在 hasBridgeImplementation 上：当前两集合恰好相同所以看不出问题，
+  // 但下一轮给 opencode 补上 MCP 适配器时（bridge 仍未实现），共用判据会让新写的
+  // 适配器被静默跳过。拆开后各自跟着自己的真相源走。
+  const bridgeCapable = hasBridgeImplementation(runtime);
+  // 动态 import 保持原样（adapters 会拉进 vendored TOML/YAML，不该为一次卸载常驻）；
+  // 加载失败按「没有适配器」处理 —— 模块都进不来，deregister 更不可能成功。
+  let mcpCapable = false;
   try {
-    const { deregister } = await import("../core/mcpRuntimeFanout.mjs");
-    const r = await deregister(runtime, {
-      projectCwd: process.cwd(),
-      log: pLog,
-    });
-    if (r.ok && r.changed) {
-      process.stdout.write(`✅ 已从 ${runtime} 移除 agentlink MCP server\n`);
-    } else if (!r.ok) {
-      process.stderr.write(`⚠️  MCP 配置清理失败 (${r.reason || "unknown"});其它清理继续。\n`);
-    }
+    const { hasMcpAdapter } = await import("../core/mcpRuntimeFanout.mjs");
+    mcpCapable = hasMcpAdapter(runtime);
   } catch (err) {
-    pLog.warn("uninstall.fanout.failed", "mcp deregister failed", {
+    pLog.warn("uninstall.mcp.probe_failed", "cannot load mcp fanout module; skipping mcp cleanup", {
       err: err?.message || String(err),
     });
   }
+  if (!bridgeCapable) {
+    pLog.info("uninstall.bridge.not_implemented", "skipping service cleanup (no bridge for this runtime)", { runtime });
+  }
+  if (!mcpCapable) {
+    pLog.info("uninstall.mcp.no_adapter", "skipping mcp cleanup (no mcp adapter for this runtime)", { runtime });
+  }
+  if (mcpCapable) {
+    try {
+      const { deregister } = await import("../core/mcpRuntimeFanout.mjs");
+      const r = await deregister(runtime, {
+        projectCwd: process.cwd(),
+        log: pLog,
+      });
+      if (r.ok && r.changed) {
+        process.stdout.write(`✅ 已从 ${runtime} 移除 agentlink MCP server\n`);
+      } else if (!r.ok) {
+        process.stderr.write(`⚠️  MCP 配置清理失败 (${r.reason || "unknown"});其它清理继续。\n`);
+      }
+    } catch (err) {
+      pLog.warn("uninstall.fanout.failed", "mcp deregister failed", {
+        err: err?.message || String(err),
+      });
+    }
+  }
 
   // 2. 卸 service (launchd plist / systemd-user / schtasks)
   let serviceResult = null;
-  try {
-    serviceResult = serviceUninstall(runtime, pLog);
-    pLog.info("uninstall.service.done", "service uninstalled", serviceResult);
-  } catch (err) {
-    pLog.warn("uninstall.service.failed", "service uninstall failed", {
-      err: err?.message || String(err),
-    });
-    process.stderr.write(`⚠️  service uninstall: ${err?.message || err}\n`);
+  if (bridgeCapable) {
+    try {
+      serviceResult = serviceUninstall(runtime, pLog);
+      pLog.info("uninstall.service.done", "service uninstalled", serviceResult);
+    } catch (err) {
+      pLog.warn("uninstall.service.failed", "service uninstall failed", {
+        err: err?.message || String(err),
+      });
+      process.stderr.write(`⚠️  service uninstall: ${err?.message || err}\n`);
+    }
   }
 
   // 3. 清本地状态文件（除非用户显式保留）

package/src-ext/commands/service.mjs

@@ -14,7 +14,7 @@ export async function runServiceCommand({ options, positional, log }) {
   const action = (positional[0] || "").toLowerCase();
   const runtime = options.runtime || options.r || positional[1] || "";
   if (!runtime) {
-    process.stderr.write("service 子命令需要 -r claude|codex\n");
+    process.stderr.write("service 子命令需要 -r claude|codex|cursor|opencode|qwen|kimi|codebuddy\n");
     process.exit(2);
   }
   const svcLog = log.child({ comp: "service", rt: runtime });

package/src-ext/core/activeRuns.mjs

@@ -11,7 +11,8 @@
 /**
  * @returns {{
  *   register: (entry: {sessionKey?: string|null, threadId?: string|null, runId?: string|null, kill: (reason?: string) => void}) => () => void,
- *   abort: (params?: {key?: string, runId?: string}) => {aborted: number, matched: string[]},
+ *   abort: (params?: {key?: string, runId?: string}) => {aborted: number, matched: string[], status?: string},
+ *   abortAll: (reason?: string) => {aborted: number, matched: string[]},
  *   size: () => number,
  * }}
  */
@@ -36,8 +37,7 @@ export function createActiveRunRegistry({ log } = {}) {
    * 杀掉匹配的活跃 run。匹配顺序：
    *   1. runId 精确命中
    *   2. key 命中 sessionKey 或 threadId
-   *   3. 都没命中且当前只有一个活跃 run → 杀它（key 口径不一致的兜底，
-   *      单会话场景下用户意图无歧义）
+   * 旧协议只有 key 时必须唯一命中；没有命中或命中多个都不误杀。
    */
   function abort({ key, runId } = {}) {
     const wantRun = String(runId || "").trim();
@@ -51,11 +51,12 @@ export function createActiveRunRegistry({ log } = {}) {
         ([, r]) => r.sessionKey === wantKey || r.threadId === wantKey,
       );
     }
-    if (targets.length === 0 && runs.size === 1) {
-      targets = [...runs.entries()];
-      log?.info?.("activeRuns.abort.fallback",
-        "abort key matched nothing, killing the single active run",
-        { key: wantKey, runId: wantRun });
+    if (!wantRun && targets.length > 1) {
+      log?.warn?.("activeRuns.abort.ambiguous", "legacy abort key matched multiple runs", {
+        key: wantKey,
+        matched: targets.map(([, run]) => run.runId || run.threadId),
+      });
+      return { aborted: 0, matched: [], status: "ambiguous" };
     }
     const matched = [];
     for (const [id, r] of targets) {
@@ -72,5 +73,21 @@ export function createActiveRunRegistry({ log } = {}) {
     return { aborted: matched.length, matched };
   }
 
-  return { register, abort, size: () => runs.size };
+  function abortAll(reason = "shutdown") {
+    const matched = [];
+    for (const [id, run] of [...runs.entries()]) {
+      runs.delete(id);
+      matched.push(run.runId || run.threadId || String(id));
+      try {
+        run.kill(reason);
+      } catch (err) {
+        log?.warn?.("activeRuns.abort_all.kill_failed", "kill threw", {
+          runId: run.runId, err: err?.message || String(err),
+        });
+      }
+    }
+    return { aborted: matched.length, matched };
+  }
+
+  return { register, abort, abortAll, size: () => runs.size };
 }

package/src-ext/core/defaultWorkspace.mjs

@@ -1,37 +1,62 @@
 /**
- * defaultWorkspace.mjs — claude/codex 默认工作区路径管理
+ * defaultWorkspace.mjs — runtime 默认工作区路径管理
  *
  * 提供三个函数：
- *   workspacesRoot()              — 工作区根目录（~/agentlink），供 default + 用户新建工作区共用
+ *   workspacesRoot()              — 工作区根目录（${AGENTLINK_HOME}/workspaces），供 default + 用户新建工作区共用
  *   defaultWorkspacePath(runtime) — 纯路径计算，不建目录（供 scan 合成 entry 用）
  *   ensureDefaultWorkspace(runtime) — mkdir -p 后返回路径（pair 时 eager 创建 + dispatch 懒建）
  *
  * 路径结构：<workspacesRoot()>/<runtime>/default
- *   例如 ~/agentlink/claude/default
- *        ~/agentlink/codex/default
+ *   例如 ~/.agentlink/workspaces/claude/default
+ *        ~/.agentlink/workspaces/codex/default
  *
- * 注意：工作区根 ~/agentlink（非隐藏、用户可见的项目目录）刻意与 CLI 状态目录
- * ~/.agentlink（隐藏，放审计日志 / 凭证 / sessions）分开——前者是 agent 实际读写
- * 代码的项目根，后者是工具自身状态，二者不能混在一起（参 openclaw 官方同款建议：
- * workspace 要与 ~/.openclaw 分离）。用户新建工作区走 <workspacesRoot()>/<runtime>/<name>。
+ * 工作区根统一位于状态根的 `workspaces/` 子目录，避免散落到用户主目录；凭证和
+ * session 仍保留在状态根的其它文件中。用户新建工作区走 <workspacesRoot()>/<runtime>/<name>。
  *
  * 改名 agentlink 时只需改 workspacesRoot() 的返回值（统一来源）。
  */
 
 import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
 import { ensureGitRepo } from "./ensureGitRepo.mjs";
 
+export const DEFAULT_WORKSPACE_RUNTIMES = Object.freeze([
+  "openclaw", "hermes", "claude", "codex", "cursor", "opencode", "qwen", "kimi", "codebuddy",
+]);
+
+function agentlinkHome() {
+  return String(process.env.AGENTLINK_HOME || "").trim() || path.join(os.homedir(), ".agentlink");
+}
+
+function openclawDefaultWorkspace() {
+  const home = String(process.env.OPENCLAW_HOME || "").trim() || path.join(os.homedir(), ".openclaw");
+  const configPath = path.join(home, "openclaw.json");
+  try {
+    const parsed = JSON.parse(fsSync.readFileSync(configPath, "utf8"));
+    const configured = String(parsed?.agents?.defaults?.workspace || "").trim();
+    if (configured) return path.isAbsolute(configured) ? configured : path.resolve(home, configured);
+  } catch {}
+  return path.join(home, "workspace");
+}
+
+function hermesDefaultWorkspace(profileName) {
+  const configured = String(process.env.HERMES_HOME || "").trim();
+  if (configured) return path.resolve(configured.startsWith("~") ? path.join(os.homedir(), configured.slice(1)) : configured);
+  if (String(profileName || "").trim()) return path.join(os.homedir(), ".hermes", "profiles", String(profileName).trim());
+  return path.join(os.homedir(), ".hermes");
+}
+
 /**
- * 返回工作区根目录的绝对路径（~/agentlink），不建目录。
+ * 返回工作区根目录的绝对路径（${AGENTLINK_HOME}/workspaces），不建目录。
  * default 与用户新建工作区都挂在它下面：<root>/<runtime>/<name>。
  *
  * @returns {string}  绝对路径
  */
 export function workspacesRoot() {
-  return path.join(os.homedir(), "agentlink");
+  return path.join(agentlinkHome(), "workspaces");
 }
 
 /**
@@ -40,7 +65,12 @@ export function workspacesRoot() {
  * @param {string} runtime  "claude" | "codex"
  * @returns {string}        绝对路径
  */
-export function defaultWorkspacePath(runtime) {
+export function defaultWorkspacePath(runtime, { profileName } = {}) {
+  if (!DEFAULT_WORKSPACE_RUNTIMES.includes(runtime)) {
+    throw new Error(`unsupported default workspace runtime: ${runtime}`);
+  }
+  if (runtime === "openclaw") return openclawDefaultWorkspace();
+  if (runtime === "hermes") return hermesDefaultWorkspace(profileName);
   return path.join(workspacesRoot(), runtime, "default");
 }
 
@@ -55,8 +85,8 @@ export function defaultWorkspacePath(runtime) {
  * @param {{ _execFile?: Function }} [opts]  测试注入
  * @returns {Promise<string>}  绝对路径
  */
-export async function ensureDefaultWorkspace(runtime, { _execFile } = {}) {
-  const p = defaultWorkspacePath(runtime);
+export async function ensureDefaultWorkspace(runtime, { _execFile, profileName } = {}) {
+  const p = defaultWorkspacePath(runtime, { profileName });
   await fs.mkdir(p, { recursive: true, mode: 0o700 });
   if (runtime === "codex") {
     await ensureGitRepo(p, { _execFile });

package/src-ext/core/defaultWorkspaceSync.mjs

@@ -0,0 +1,20 @@
+import { defaultWorkspacePath } from "./defaultWorkspace.mjs";
+
+function baseUrl(value) {
+  return String(value || "").replace(/\/+$/, "");
+}
+
+export async function ensureRelayDefaultWorkspace({ runtime, relayUrl, bridgeToken, profileName, fetchImpl = globalThis.fetch }) {
+  if (typeof fetchImpl !== "function") throw new Error("default workspace sync: fetch unavailable");
+  const workspacePath = defaultWorkspacePath(runtime, { profileName });
+  const response = await fetchImpl(`${baseUrl(relayUrl)}/v1/gateways/me/default_workspace`, {
+    method: "PUT",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Agent-Bridge-Token": String(bridgeToken || ""),
+    },
+    body: JSON.stringify({ workspace_path: workspacePath, workspace_name: "default" }),
+  });
+  if (!response.ok) throw new Error(`default workspace sync failed: HTTP ${response.status}`);
+  return response.json();
+}

package/src-ext/core/installationIdentity.mjs

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { CLI_STATE_DIR_NAME } from "./attachAuditLog.mjs";
+
+const INSTALLATION_ID_FILE = "installation-identity.json";
+const INSTALLATION_ID_VERSION = 1;
+const PRIVATE_DIRECTORY_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function installationStateDir() {
+  const configured = process.env.AGENTLINK_HOME?.trim();
+  return configured || path.join(os.homedir(), CLI_STATE_DIR_NAME);
+}
+
+function installationIdentityFile() {
+  return path.join(installationStateDir(), INSTALLATION_ID_FILE);
+}
+
+function parseInstallationIdentity(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error("installation identity file is invalid JSON");
+  }
+  const installationId = String(value?.installation_id || "").trim();
+  if (value?.version !== INSTALLATION_ID_VERSION || !UUID_V4_RE.test(installationId)) {
+    throw new Error("installation identity file has an invalid schema");
+  }
+  return installationId;
+}
+
+function readExistingIdentity(file) {
+  try {
+    return parseInstallationIdentity(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * Return one random, non-hardware installation identity shared by every
+ * runtime in this CLI data directory. A hard-link publication makes creation
+ * no-clobber and atomic even when multiple runtime services boot together.
+ */
+export function getOrCreateInstallationId() {
+  const dir = installationStateDir();
+  const file = installationIdentityFile();
+  fs.mkdirSync(dir, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
+  const existing = readExistingIdentity(file);
+  if (existing) return existing;
+
+  const installationId = randomUUID();
+  const temporary = path.join(
+    dir,
+    `.${INSTALLATION_ID_FILE}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  const payload = `${JSON.stringify({
+    version: INSTALLATION_ID_VERSION,
+    installation_id: installationId,
+    created_at: new Date().toISOString(),
+  }, null, 2)}\n`;
+
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporary, "wx", PRIVATE_FILE_MODE);
+    fs.writeFileSync(descriptor, payload, "utf8");
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    try {
+      fs.linkSync(temporary, file);
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+  } finally {
+    if (descriptor !== undefined) {
+      try { fs.closeSync(descriptor); } catch {}
+    }
+    try { fs.unlinkSync(temporary); } catch {}
+  }
+
+  return readExistingIdentity(file);
+}
+
+export const _test = Object.freeze({
+  installationIdentityFile,
+  parseInstallationIdentity,
+});