mslxdff 0.1.203 → 0.1.208

package/src/cli/index.js

@@ -1,70 +1,73 @@
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { assertMinNode } from "../compat.js";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "..", "package.json"), "utf8")).version;
-
-// deep CLI entry — single inlet: run(args) — hides all command branching inside
-export async function run(args = process.argv.slice(2)) {
-  // 运行环境门（强制）：项目要求 Node >=18（ADR-0024），不满足则人话退出
-  if (!assertMinNode()) process.exit(1);
-  const { handleHelp, handleUpdate, handleRefreshToken, handleShowToken, handleUninstall, handleLog, handlePlugins, handleChat, handleStatus, handleFree, handleAutostart } = await import("./commands/system.js");
-  if (await handleHelp(args, VERSION)) return;
-  if (await handleUpdate(args, VERSION)) return;
-  if (await handleRefreshToken(args)) return;
-  if (await handleShowToken(args)) return;
-  const { handleTimezone } = await import("./commands/timezone.js");
-  if (await handleTimezone(args)) return;
-
-  const { handleStop, handleRestart } = await import("./commands/daemon.js");
-  if (await handleStop(args)) return;
-  if (await handleRestart(args, VERSION)) return;
-  if (await handleUninstall(args)) return;
-  if (await handleLog(args)) return;
-  if (await handlePlugins(args)) return;
-  if (await handleChat(args)) return;
-  if (await handleStatus(args, VERSION)) return;
-  const { handleStats } = await import("./commands/stats.js");
-  if (await handleStats(args)) return;
-
-  const { handleModel } = await import("./commands/model.js");
-  if (await handleModel(args)) return;
-  const { handleSetto } = await import("./commands/sync.js");
-  if (await handleSetto(args)) return;
-  const { handleClaudeDesktop } = await import("./commands/claude-desktop.js");
-  if (await handleClaudeDesktop(args)) return;
-  const { handleWorkbuddy } = await import("./commands/workbuddy.js");
-  if (await handleWorkbuddy(args)) return;
-
-  if (await handleAutostart(args)) return;
-  if (await handleFree(args)) return;
-
-  const { handleProviders, handleProvider } = await import("./commands/provider.js");
-  if (await handleProviders(args)) return;
-  if (await handleProvider(args)) return;
-
-  const { handleDebug } = await import("./commands/daemon.js");
-  await handleDebug(args);
-
-  const { handleGroupCreate, handleGroupCommand, handleAddToGroup, handleResetBan, handleLeaveGroup, handleDelGroup } = await import("./commands/group.js");
-  if (await handleGroupCreate(args)) return;
-  if (await handleGroupCommand(args)) return;
-  if (await handleAddToGroup(args)) return;
-  if (await handleResetBan(args)) return;
-  if (await handleLeaveGroup(args)) return;
-  if (await handleDelGroup(args)) return;
-
-  const { handleUseGroup } = await import("./commands/use-group.js");
-  if (await handleUseGroup(args)) return;
-  const { handlePort, handleDaemonFlag, handleBareRun } = await import("./commands/daemon.js");
-  if (await handlePort(args)) return;
-  if (await handleDaemonFlag(args, VERSION)) return;
-  if (await handleBareRun(args, VERSION)) return;
-
-  const { startDaemonMain } = await import("./bootstrap.js");
-  await startDaemonMain(VERSION);
-}
-
-export { VERSION };
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assertMinNode } from "../compat.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "..", "package.json"), "utf8")).version;
+
+// deep CLI entry — single inlet: run(args) — hides all command branching inside
+export async function run(args = process.argv.slice(2)) {
+  // 运行环境门（强制）：项目要求 Node >=18（ADR-0024），不满足则人话退出
+  if (!assertMinNode()) process.exit(1);
+  const { handleHelp, handleUpdate, handleRefreshToken, handleShowToken, handleUninstall, handleLog, handlePlugins, handleChat, handleStatus, handleFree, handleAutostart } = await import("./commands/system.js");
+  if (await handleHelp(args, VERSION)) return;
+  if (await handleUpdate(args, VERSION)) return;
+  if (await handleRefreshToken(args)) return;
+  if (await handleShowToken(args)) return;
+  const { handleTimezone } = await import("./commands/timezone.js");
+  if (await handleTimezone(args)) return;
+
+  const { handleStop, handleRestart } = await import("./commands/daemon.js");
+  if (await handleStop(args)) return;
+  if (await handleRestart(args, VERSION)) return;
+  if (await handleUninstall(args)) return;
+  if (await handleLog(args)) return;
+  if (await handlePlugins(args)) return;
+  if (await handleChat(args)) return;
+  if (await handleStatus(args, VERSION)) return;
+  const { handleStats } = await import("./commands/stats.js");
+  if (await handleStats(args)) return;
+
+  const { handleModel } = await import("./commands/model.js");
+  if (await handleModel(args)) return;
+  const { handleSetto } = await import("./commands/sync.js");
+  if (await handleSetto(args)) return;
+  const { handleClaudeDesktop } = await import("./commands/claude-desktop.js");
+  if (await handleClaudeDesktop(args)) return;
+  const { handleWorkbuddy } = await import("./commands/workbuddy.js");
+  if (await handleWorkbuddy(args)) return;
+
+  if (await handleAutostart(args)) return;
+  if (await handleFree(args)) return;
+
+  const { handleV6Pool } = await import("./commands/v6-pool.js");
+  if (await handleV6Pool(args)) return;
+
+  const { handleProviders, handleProvider } = await import("./commands/provider.js");
+  if (await handleProviders(args)) return;
+  if (await handleProvider(args)) return;
+
+  const { handleDebug } = await import("./commands/daemon.js");
+  await handleDebug(args);
+
+  const { handleGroupCreate, handleGroupCommand, handleAddToGroup, handleResetBan, handleLeaveGroup, handleDelGroup } = await import("./commands/group.js");
+  if (await handleGroupCreate(args)) return;
+  if (await handleGroupCommand(args)) return;
+  if (await handleAddToGroup(args)) return;
+  if (await handleResetBan(args)) return;
+  if (await handleLeaveGroup(args)) return;
+  if (await handleDelGroup(args)) return;
+
+  const { handleUseGroup } = await import("./commands/use-group.js");
+  if (await handleUseGroup(args)) return;
+  const { handlePort, handleDaemonFlag, handleBareRun } = await import("./commands/daemon.js");
+  if (await handlePort(args)) return;
+  if (await handleDaemonFlag(args, VERSION)) return;
+  if (await handleBareRun(args, VERSION)) return;
+
+  const { startDaemonMain } = await import("./bootstrap.js");
+  await startDaemonMain(VERSION);
+}
+
+export { VERSION };

package/src/cli/interactive.js

@@ -1,121 +1,121 @@
-// 交互式选择器：↑/↓ 移动，←/→ 翻页，Enter 确认，q/Esc 取消；ANSI 原地重绘。
-// 页高按终端行数自适应（items ≤ 页高时不分页，行为与旧版全量渲染一致）。
-const PAGE_RESERVE = 6; // 页头 1 + 帮助 2 + 余量
-
-function pageSizeFor(items) {
-  const rows = Number(process.stdout?.rows) || 24;
-  const size = Math.max(4, rows - PAGE_RESERVE);
-  return items.length > size ? size : items.length || 1;
-}
-
-export async function pickInteractive(items, startCursor = 0) {
-  const { renderChooser, renderChooserHelp, parseKey } = await import("../chooser.js");
-  const size = pageSizeFor(items);
-  let page = 0;
-  let cursor = Math.min(Math.max(startCursor, 0), items.length - 1);
-  const draw = () => {
-    const usePage = size < items.length;
-    const lines = [...renderChooser(items, cursor, usePage ? { index: page, size } : {}), ...renderChooserHelp(false, usePage)];
-    process.stdout.write("\x1b[2J\x1b[H" + lines.join("\n"));
-  };
-  draw();
-  return new Promise((resolve) => {
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-    process.stdin.setEncoding("utf8");
-    const cleanup = () => {
-      process.stdin.removeListener("data", onData);
-      process.stdin.setRawMode(false);
-      process.stdin.pause();
-      process.stdout.write("\n");
-    };
-    const onData = (chunk) => {
-      const key = parseKey(String(chunk));
-      const pages = Math.max(1, Math.ceil(items.length / size));
-      if (key === "up") {
-        cursor = (cursor - 1 + items.length) % items.length;
-        page = Math.floor(cursor / size);
-        draw();
-      } else if (key === "down") {
-        cursor = (cursor + 1) % items.length;
-        page = Math.floor(cursor / size);
-        draw();
-      } else if (key === "pageup") {
-        page = (page - 1 + pages) % pages;
-        cursor = page * size;
-        draw();
-      } else if (key === "pagedown") {
-        page = (page + 1) % pages;
-        cursor = Math.min(page * size, items.length - 1);
-        draw();
-      } else if (key === "enter") {
-        cleanup();
-        resolve(items[cursor].id);
-      } else if (key === "cancel") {
-        cleanup();
-        resolve(null);
-      }
-    };
-    process.stdin.on("data", onData);
-  });
-}
-
-// 多选勾选：↑/↓ 移动，←/→ 翻页，Space 勾选/取消，Enter 保存，q/Esc 取消（返回 Set 或 null）
-export async function pickInteractiveMulti(items, initialPicked = new Set(), startCursor = 0) {
-  const { renderChooser, renderChooserHelp, parseKey } = await import("../chooser.js");
-  const size = pageSizeFor(items);
-  let page = 0;
-  let cursor = Math.min(Math.max(startCursor, 0), items.length - 1);
-  const picked = new Set(items.filter((it) => initialPicked.has(it.id)).map((it) => it.id));
-  const draw = () => {
-    const usePage = size < items.length;
-    const rows = items.map((it, i) => ({ ...it, picked: picked.has(it.id) }));
-    const lines = [...renderChooser(rows, cursor, { multi: true, ...(usePage ? { index: page, size } : {}) }), ...renderChooserHelp(true, usePage)];
-    process.stdout.write("\x1b[2J\x1b[H" + lines.join("\n"));
-  };
-  draw();
-  return new Promise((resolve) => {
-    process.stdin.setRawMode(true);
-    process.stdin.resume();
-    process.stdin.setEncoding("utf8");
-    const cleanup = () => {
-      process.stdin.removeListener("data", onData);
-      process.stdin.setRawMode(false);
-      process.stdin.pause();
-      process.stdout.write("\n");
-    };
-    const onData = (chunk) => {
-      const key = parseKey(String(chunk));
-      const pages = Math.max(1, Math.ceil(items.length / size));
-      if (key === "up") {
-        cursor = (cursor - 1 + items.length) % items.length;
-        page = Math.floor(cursor / size);
-        draw();
-      } else if (key === "down") {
-        cursor = (cursor + 1) % items.length;
-        page = Math.floor(cursor / size);
-        draw();
-      } else if (key === "pageup") {
-        page = (page - 1 + pages) % pages;
-        cursor = page * size;
-        draw();
-      } else if (key === "pagedown") {
-        page = (page + 1) % pages;
-        cursor = Math.min(page * size, items.length - 1);
-        draw();
-      } else if (key === "space") {
-        const id = items[cursor].id;
-        if (picked.has(id)) picked.delete(id);
-        else picked.add(id);
-        draw();
-      } else if (key === "enter") {
-        cleanup();
-        resolve(new Set(picked));
-      } else if (key === "cancel") {
-        cleanup();
-        resolve(null);
-      }
-    };
-    process.stdin.on("data", onData);
-  });
-}
+// 交互式选择器：↑/↓ 移动，←/→ 翻页，Enter 确认，q/Esc 取消；ANSI 原地重绘。
+// 页高按终端行数自适应（items ≤ 页高时不分页，行为与旧版全量渲染一致）。
+const PAGE_RESERVE = 6; // 页头 1 + 帮助 2 + 余量
+
+function pageSizeFor(items) {
+  const rows = Number(process.stdout?.rows) || 24;
+  const size = Math.max(4, rows - PAGE_RESERVE);
+  return items.length > size ? size : items.length || 1;
+}
+
+export async function pickInteractive(items, startCursor = 0) {
+  const { renderChooser, renderChooserHelp, parseKey } = await import("../chooser.js");
+  const size = pageSizeFor(items);
+  let page = 0;
+  let cursor = Math.min(Math.max(startCursor, 0), items.length - 1);
+  const draw = () => {
+    const usePage = size < items.length;
+    const lines = [...renderChooser(items, cursor, usePage ? { index: page, size } : {}), ...renderChooserHelp(false, usePage)];
+    process.stdout.write("\x1b[2J\x1b[H" + lines.join("\n"));
+  };
+  draw();
+  return new Promise((resolve) => {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write("\n");
+    };
+    const onData = (chunk) => {
+      const key = parseKey(String(chunk));
+      const pages = Math.max(1, Math.ceil(items.length / size));
+      if (key === "up") {
+        cursor = (cursor - 1 + items.length) % items.length;
+        page = Math.floor(cursor / size);
+        draw();
+      } else if (key === "down") {
+        cursor = (cursor + 1) % items.length;
+        page = Math.floor(cursor / size);
+        draw();
+      } else if (key === "pageup") {
+        page = (page - 1 + pages) % pages;
+        cursor = page * size;
+        draw();
+      } else if (key === "pagedown") {
+        page = (page + 1) % pages;
+        cursor = Math.min(page * size, items.length - 1);
+        draw();
+      } else if (key === "enter") {
+        cleanup();
+        resolve(items[cursor].id);
+      } else if (key === "cancel") {
+        cleanup();
+        resolve(null);
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+// 多选勾选：↑/↓ 移动，←/→ 翻页，Space 勾选/取消，Enter 保存，q/Esc 取消（返回 Set 或 null）
+export async function pickInteractiveMulti(items, initialPicked = new Set(), startCursor = 0) {
+  const { renderChooser, renderChooserHelp, parseKey } = await import("../chooser.js");
+  const size = pageSizeFor(items);
+  let page = 0;
+  let cursor = Math.min(Math.max(startCursor, 0), items.length - 1);
+  const picked = new Set(items.filter((it) => initialPicked.has(it.id)).map((it) => it.id));
+  const draw = () => {
+    const usePage = size < items.length;
+    const rows = items.map((it, i) => ({ ...it, picked: picked.has(it.id) }));
+    const lines = [...renderChooser(rows, cursor, { multi: true, ...(usePage ? { index: page, size } : {}) }), ...renderChooserHelp(true, usePage)];
+    process.stdout.write("\x1b[2J\x1b[H" + lines.join("\n"));
+  };
+  draw();
+  return new Promise((resolve) => {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write("\n");
+    };
+    const onData = (chunk) => {
+      const key = parseKey(String(chunk));
+      const pages = Math.max(1, Math.ceil(items.length / size));
+      if (key === "up") {
+        cursor = (cursor - 1 + items.length) % items.length;
+        page = Math.floor(cursor / size);
+        draw();
+      } else if (key === "down") {
+        cursor = (cursor + 1) % items.length;
+        page = Math.floor(cursor / size);
+        draw();
+      } else if (key === "pageup") {
+        page = (page - 1 + pages) % pages;
+        cursor = page * size;
+        draw();
+      } else if (key === "pagedown") {
+        page = (page + 1) % pages;
+        cursor = Math.min(page * size, items.length - 1);
+        draw();
+      } else if (key === "space") {
+        const id = items[cursor].id;
+        if (picked.has(id)) picked.delete(id);
+        else picked.add(id);
+        draw();
+      } else if (key === "enter") {
+        cleanup();
+        resolve(new Set(picked));
+      } else if (key === "cancel") {
+        cleanup();
+        resolve(null);
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}

package/src/cli/join-core.js

@@ -1,99 +1,99 @@
-import { createGroupsService } from "../groups.js";
-import { createPeersService } from "../peers.js";
-import { loadToken } from "../state.js";
-import { markJoined, syncAllJoinedGroups } from "./group-helpers.js";
-import { compatFetch, timeoutSignal } from "../compat.js";
-import { errMsg } from "./util.js";
-
-const DEFAULT_PORT = 8989;
-const JOIN_TIMEOUT_MS = 8000;
-
-/** 组长地址归一化 + 人话校验（ADR-0006 术语 leader-host）：`1.2.3.4` → `http://1.2.3.4:8989`。 */
-export function normalizeLeaderUrl(raw, { defaultPort = DEFAULT_PORT } = {}) {
-  const s = String(raw ?? "").trim();
-  if (!s) return { ok: false, reason: "请填写组长地址（如 1.2.3.4:8989）" };
-  if (/\s/.test(s)) return { ok: false, reason: "地址不能包含空格" };
-  const schemeMatch = /^([a-z][a-z0-9+.-]*):\/\//i.exec(s);
-  if (schemeMatch && !/^https?$/i.test(schemeMatch[1])) {
-    return { ok: false, reason: "只支持 http:// 或 https:// 开头的地址" };
-  }
-  const withScheme = Boolean(schemeMatch);
-  let body = withScheme ? s.slice(schemeMatch[0].length) : s;
-  if (body.endsWith("/")) body = body.replace(/\/+$/, "");
-  if (body.includes("/")) return { ok: false, reason: "暂不支持带路径的地址（只填 ip:端口）" };
-  if (!body) return { ok: false, reason: "地址缺少主机名" };
-  let host = body;
-  let port = null;
-  const v6End = body.lastIndexOf("]");
-  const ci = body.lastIndexOf(":");
-  if (!(v6End >= 0 && v6End === body.length - 1 && ci < v6End)) {
-    if (ci >= 0) {
-      host = body.slice(0, ci);
-      const p = body.slice(ci + 1);
-      if (!/^\d{1,5}$/.test(p)) return { ok: false, reason: "端口必须是数字（1-65535）" };
-      port = Number(p);
-      if (port < 1 || port > 65535) return { ok: false, reason: "端口超出范围（1-65535）" };
-    }
-  }
-  if (!host) return { ok: false, reason: "地址缺少主机名" };
-  const isV6 = /^\[[0-9a-fA-F:.]+\]$/.test(host);
-  if (!isV6 && !/^[\w.-]+$/.test(host)) return { ok: false, reason: "主机名含非法字符（支持 ip、域名或 [ipv6]）" };
-  const url = withScheme
-    ? `${schemeMatch[1].toLowerCase()}://${host}${port ? `:${port}` : ""}`
-    : `http://${host}:${port ?? defaultPort}`;
-  return { ok: true, url };
-}
-
-/**
- * 加入远端组（宽带/静态共用核心）：归一化 → POST /v1/groups/join → markJoined → 同步 peers。
- * 只返回结果对象，不打印、不 exit——由 CLI 命令与交互式向导各自决定展示与退出码。
- */
-export async function joinGroupCore({ leaderHost, name, isBroadband = false, args = [] }) {
-  const norm = normalizeLeaderUrl(leaderHost);
-  if (!norm.ok) return { ok: false, error: norm.reason, reason: norm.reason };
-  const leaderUrl = norm.url;
-  const groupName = String(name ?? "").trim();
-  if (!groupName) return { ok: false, leaderUrl, error: "组名不能为空" };
-  const groups = createGroupsService({});
-  const peers = createPeersService({});
-  const myToken = (await loadToken()).token;
-  const kind = isBroadband ? "broadband" : "static";
-  let joinBody;
-  if (isBroadband) {
-    const relayId = `relay://${myToken.slice(0, 8)}`;
-    joinBody = { name: groupName, key: groupName, leaderUrl, url: relayId, token: myToken, kind };
-  } else {
-    const { effectivePort } = await import("./policy.js");
-    joinBody = { name: groupName, key: groupName, leaderUrl, myPort: effectivePort(args), token: myToken, kind };
-  }
-  try {
-    const res = await compatFetch(`${leaderUrl}/v1/groups/join`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(joinBody),
-      signal: timeoutSignal(JOIN_TIMEOUT_MS),
-    });
-    if (!res.ok) {
-      const text = await res.text().catch(() => "");
-      return { ok: false, leaderUrl, error: `HTTP ${res.status} ${text.slice(0, 200)}` };
-    }
-    const data = await res.json().catch(() => ({}));
-    const myUrl = data.you?.url || joinBody.url || "";
-    markJoined({ name: groupName, leaderUrl, myUrl, memberName: myUrl, kind });
-    const synced = await syncAllJoinedGroups({ peers, groups });
-    const s = synced.find((x) => x.name === groupName);
-    return {
-      ok: true,
-      leaderUrl,
-      name: groupName,
-      myUrl,
-      memberName: myUrl,
-      kind,
-      added: s?.added ?? 0,
-      syncError: s?.error || null,
-      token: myToken,
-    };
-  } catch (err) {
-    return { ok: false, leaderUrl, error: errMsg(err) };
-  }
-}
+import { createGroupsService } from "../groups.js";
+import { createPeersService } from "../peers.js";
+import { loadToken } from "../state.js";
+import { markJoined, syncAllJoinedGroups } from "./group-helpers.js";
+import { compatFetch, timeoutSignal } from "../compat.js";
+import { errMsg } from "./util.js";
+
+const DEFAULT_PORT = 8989;
+const JOIN_TIMEOUT_MS = 8000;
+
+/** 组长地址归一化 + 人话校验（ADR-0006 术语 leader-host）：`1.2.3.4` → `http://1.2.3.4:8989`。 */
+export function normalizeLeaderUrl(raw, { defaultPort = DEFAULT_PORT } = {}) {
+  const s = String(raw ?? "").trim();
+  if (!s) return { ok: false, reason: "请填写组长地址（如 1.2.3.4:8989）" };
+  if (/\s/.test(s)) return { ok: false, reason: "地址不能包含空格" };
+  const schemeMatch = /^([a-z][a-z0-9+.-]*):\/\//i.exec(s);
+  if (schemeMatch && !/^https?$/i.test(schemeMatch[1])) {
+    return { ok: false, reason: "只支持 http:// 或 https:// 开头的地址" };
+  }
+  const withScheme = Boolean(schemeMatch);
+  let body = withScheme ? s.slice(schemeMatch[0].length) : s;
+  if (body.endsWith("/")) body = body.replace(/\/+$/, "");
+  if (body.includes("/")) return { ok: false, reason: "暂不支持带路径的地址（只填 ip:端口）" };
+  if (!body) return { ok: false, reason: "地址缺少主机名" };
+  let host = body;
+  let port = null;
+  const v6End = body.lastIndexOf("]");
+  const ci = body.lastIndexOf(":");
+  if (!(v6End >= 0 && v6End === body.length - 1 && ci < v6End)) {
+    if (ci >= 0) {
+      host = body.slice(0, ci);
+      const p = body.slice(ci + 1);
+      if (!/^\d{1,5}$/.test(p)) return { ok: false, reason: "端口必须是数字（1-65535）" };
+      port = Number(p);
+      if (port < 1 || port > 65535) return { ok: false, reason: "端口超出范围（1-65535）" };
+    }
+  }
+  if (!host) return { ok: false, reason: "地址缺少主机名" };
+  const isV6 = /^\[[0-9a-fA-F:.]+\]$/.test(host);
+  if (!isV6 && !/^[\w.-]+$/.test(host)) return { ok: false, reason: "主机名含非法字符（支持 ip、域名或 [ipv6]）" };
+  const url = withScheme
+    ? `${schemeMatch[1].toLowerCase()}://${host}${port ? `:${port}` : ""}`
+    : `http://${host}:${port ?? defaultPort}`;
+  return { ok: true, url };
+}
+
+/**
+ * 加入远端组（宽带/静态共用核心）：归一化 → POST /v1/groups/join → markJoined → 同步 peers。
+ * 只返回结果对象，不打印、不 exit——由 CLI 命令与交互式向导各自决定展示与退出码。
+ */
+export async function joinGroupCore({ leaderHost, name, isBroadband = false, args = [] }) {
+  const norm = normalizeLeaderUrl(leaderHost);
+  if (!norm.ok) return { ok: false, error: norm.reason, reason: norm.reason };
+  const leaderUrl = norm.url;
+  const groupName = String(name ?? "").trim();
+  if (!groupName) return { ok: false, leaderUrl, error: "组名不能为空" };
+  const groups = createGroupsService({});
+  const peers = createPeersService({});
+  const myToken = (await loadToken()).token;
+  const kind = isBroadband ? "broadband" : "static";
+  let joinBody;
+  if (isBroadband) {
+    const relayId = `relay://${myToken.slice(0, 8)}`;
+    joinBody = { name: groupName, key: groupName, leaderUrl, url: relayId, token: myToken, kind };
+  } else {
+    const { effectivePort } = await import("./policy.js");
+    joinBody = { name: groupName, key: groupName, leaderUrl, myPort: effectivePort(args), token: myToken, kind };
+  }
+  try {
+    const res = await compatFetch(`${leaderUrl}/v1/groups/join`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(joinBody),
+      signal: timeoutSignal(JOIN_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      return { ok: false, leaderUrl, error: `HTTP ${res.status} ${text.slice(0, 200)}` };
+    }
+    const data = await res.json().catch(() => ({}));
+    const myUrl = data.you?.url || joinBody.url || "";
+    markJoined({ name: groupName, leaderUrl, myUrl, memberName: myUrl, kind });
+    const synced = await syncAllJoinedGroups({ peers, groups });
+    const s = synced.find((x) => x.name === groupName);
+    return {
+      ok: true,
+      leaderUrl,
+      name: groupName,
+      myUrl,
+      memberName: myUrl,
+      kind,
+      added: s?.added ?? 0,
+      syncError: s?.error || null,
+      token: myToken,
+    };
+  } catch (err) {
+    return { ok: false, leaderUrl, error: errMsg(err) };
+  }
+}