zen-gitsync 2.18.27 → 2.19.1

package/src/cli/peer.js

@@ -0,0 +1,272 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// `g peer` —— 跨机器通信的配置入口（g ai 与另一台机器上的 g ai 对话）。
+//
+// 三条命令构成最小闭环：
+//   A 上 `g peer on`          → 打印本机地址与令牌
+//   B 上 `g peer add 服务器 <地址> --token <令牌>`  → 校验一次 /info 并把对端 id 记下来
+//   B 上 `g peer ask 服务器 "你那边有哪些项目"`      → 直接跑通一轮跨机器问答
+//
+// 为什么不把这些塞进 config.json / 界面：peer 身份只跟机器有关、且是"一次配好长期用"，
+// 命令行更快，也便于在两台机器上照抄同一套步骤。
+
+import os from 'node:os';
+import chalk from 'chalk';
+
+import {
+  ensureSelf,
+  updateSelf,
+  readState,
+  listPeers,
+  removePeer,
+  upsertPeer,
+  PEER_DEFAULT_PORT,
+  maskToken
+} from '../peer/store.js';
+import { fetchPeerInfo, askPeer } from '../peer/client.js';
+
+const USAGE = `
+用法:
+  g peer                          查看本机节点身份与已登记的对端
+  g peer on [--name 昵称] [--port 5600] [--host 0.0.0.0]
+                                  开启本机的 peer 端口(重启 g ui 后生效)
+  g peer off                      关闭本机的 peer 端口
+  g peer add <昵称> <地址> --token <令牌>
+                                  登记一台对端,例如:
+                                  g peer add 服务器 http://192.168.1.20:5600 --token <令牌>
+  g peer rm <昵称|id>             移除一台对端
+  g peer ask <昵称|id> <问题>     向对端提一个问题(端到端自检)
+  g peer help                     显示本帮助
+
+说明:
+  · peer 端口是**独立端口**,与 g ui 的随机端口无关;只有 g ui 在跑时才监听。
+  · 令牌在「g peer on」时自动生成,对端要填的就是这串;它等价于"允许对方问我"的钥匙,
+    不要贴到聊天/仓库里。
+  · 地址用对端在局域网内的 IP(下面会列出本机可作为地址的网卡)。
+`.trim();
+
+/** 列出本机可能对外的 IPv4 地址（给用户抄地址用，跳过回环与虚拟网卡）。 */
+function localAddresses() {
+  const out = [];
+  for (const [name, list] of Object.entries(os.networkInterfaces())) {
+    for (const item of list || []) {
+      if (item.family !== 'IPv4' && item.family !== 4) continue;
+      if (item.internal) continue;
+      out.push({ name, address: item.address });
+    }
+  }
+  return out;
+}
+
+/** 从 argv 里取 `--key value` / `--flag`。 */
+function parseFlags(argv) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) { flags[key] = next; i += 1; } else { flags[key] = true; }
+    } else {
+      rest.push(a);
+    }
+  }
+  return { flags, rest };
+}
+
+async function cmdStatus() {
+  const state = await ensureSelf();
+  const self = state.self;
+  console.log(chalk.bold('本机节点'));
+  console.log(`  昵称   ${self.name}`);
+  console.log(`  节点 id ${self.id}`);
+  console.log(`  端口   ${self.host}:${self.port}  ${self.enabled ? chalk.green('已开启') : chalk.gray('未开启（g peer on 开启）')}`);
+  console.log(`  令牌   ${self.enabled ? self.token : maskToken(self.token)}`);
+
+  const peers = await listPeers();
+  console.log('');
+  console.log(chalk.bold(`对端（${peers.length}）`));
+  if (!peers.length) {
+    console.log(chalk.gray('  还没有。在另一台机器上 `g peer on`，然后 `g peer add <昵称> <地址> --token <令牌>`。'));
+    return;
+  }
+  for (const p of peers) {
+    let tag = chalk.gray('[离线]');
+    try {
+      const info = await fetchPeerInfo(p, { timeoutMs: 2000 });
+      tag = chalk.green('[在线]') + chalk.gray(` ${info.name} ${info.version || ''}`.trimEnd());
+    } catch (e) {
+      tag = chalk.gray(`[离线] ${e.message}`);
+    }
+    console.log(`  ${p.name.padEnd(12)} ${p.url}  ${tag}`);
+  }
+}
+
+async function cmdOn(flags) {
+  const port = flags.port ? Number(flags.port) : PEER_DEFAULT_PORT;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    console.error(chalk.red(`端口不合法: ${flags.port}`));
+    process.exitCode = 1;
+    return;
+  }
+  const before = await ensureSelf();
+  const after = await updateSelf({
+    enabled: true,
+    port,
+    name: typeof flags.name === 'string' ? flags.name : undefined,
+    host: typeof flags.host === 'string' ? flags.host : undefined
+  });
+  const self = after.self;
+
+  console.log(chalk.green(`已开启 peer：${self.host}:${self.port}（节点 ${self.id}「${self.name}」）`));
+  if (before.self.enabled !== true) {
+    console.log(chalk.yellow('重启 g ui 后才会真正开始监听（端口在服务启动时绑定）。'));
+  }
+  console.log('');
+  console.log(chalk.bold('给另一台机器用的信息'));
+  console.log(`  地址: http://<本机局域网 IP>:${self.port}`);
+  const addrs = localAddresses();
+  if (addrs.length) {
+    console.log(chalk.gray('  本机可用的局域网地址:'));
+    for (const a of addrs) console.log(chalk.gray(`    ${a.address}  (${a.name})`));
+  } else {
+    console.log(chalk.gray('  没探到局域网地址（可能没连网络）。'));
+  }
+  console.log(`  令牌: ${self.token}`);
+  console.log('');
+  console.log(chalk.gray('在另一台机器上执行：'));
+  console.log(chalk.gray(`  g peer add ${self.name} http://${addrs[0]?.address || '<本机IP>'}:${self.port} --token ${self.token}`));
+}
+
+async function cmdOff() {
+  await ensureSelf();
+  await updateSelf({ enabled: false });
+  console.log(chalk.green('已关闭本机的 peer 端口（重启 g ui 后不再监听）。'));
+}
+
+async function cmdAdd(rest, flags) {
+  const [name, url] = rest;
+  const token = typeof flags.token === 'string' ? flags.token.trim() : '';
+  if (!name || !url) {
+    console.error(chalk.red('用法: g peer add <昵称> <地址> --token <令牌>'));
+    process.exitCode = 1;
+    return;
+  }
+  if (!token) {
+    console.error(chalk.red('缺少 --token。<令牌> 在对端机器执行 `g peer on` 时会打印。'));
+    process.exitCode = 1;
+    return;
+  }
+  const normalized = url.startsWith('http') ? url : `http://${url}`;
+
+  // 先探一次：能连上 + 令牌对 + 拿到对方的真实 id（之后按 id 寻址，改 IP 也不会认错人）
+  let info;
+  try {
+    info = await fetchPeerInfo({ url: normalized.replace(/\/+$/, ''), token }, { timeoutMs: 5000 });
+  } catch (e) {
+    console.error(chalk.red(`登记失败：${e.message}`));
+    console.error(chalk.gray('排查顺序：对端 g ui 是否在跑 → 对端是否 `g peer on` → 局域网是否互通（防火墙）→ 令牌是否正确。'));
+    process.exitCode = 1;
+    return;
+  }
+
+  await upsertPeer({ id: info.id || '', name, url: normalized, token });
+  console.log(chalk.green(`已登记对端「${name}」→ ${normalized}（对方节点 ${info.id || '未知'}「${info.name}」）`));
+  console.log(chalk.gray(`自检：g peer ask ${name} "你那边现在有哪些项目？"`));
+}
+
+async function cmdRm(rest) {
+  const ref = rest[0];
+  if (!ref) {
+    console.error(chalk.red('用法: g peer rm <昵称|id>'));
+    process.exitCode = 1;
+    return;
+  }
+  const { removed, peer } = await removePeer(ref);
+  console.log(removed ? chalk.green(`已移除对端「${peer.name}」`) : chalk.yellow(`没有找到「${ref}」`));
+}
+
+async function cmdAsk(rest) {
+  const ref = rest[0];
+  const question = rest.slice(1).join(' ').trim();
+  if (!ref || !question) {
+    console.error(chalk.red('用法: g peer ask <昵称|id> <问题>'));
+    process.exitCode = 1;
+    return;
+  }
+  const state = await ensureSelf();
+  const peers = await listPeers();
+  const peer = peers.find((p) => p.id.toLowerCase() === ref.toLowerCase() || p.name.toLowerCase() === ref.toLowerCase());
+  if (!peer) {
+    console.error(chalk.red(`没有找到对端「${ref}」。现有：${peers.map((p) => p.name).join(' / ') || '（空）'}`));
+    process.exitCode = 1;
+    return;
+  }
+  const full = (await readState()).peers.find((p) => p.url === peer.url);
+  console.log(chalk.gray(`→ 正在问「${peer.name}」（对方是另一个智能体，可能需要一会儿）…`));
+  try {
+    const result = await askPeer(full, state.self, question);
+    console.log('');
+    console.log(chalk.bold(`【${peer.name}】`));
+    console.log(result.answer || chalk.yellow('（对方没有给出正文）'));
+    console.log('');
+    console.log(chalk.gray(`用时 ${(result.ms / 1000).toFixed(1)}s，会话 ${result.sessionId || '新会话'}`));
+  } catch (e) {
+    console.error(chalk.red(`提问失败：${e.message}`));
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * `g peer` 入口。
+ * @param {string[]} argv 已经去掉 `peer` 之后的参数
+ */
+export async function runPeerCli(argv = []) {
+  const sub = argv[0] || 'status';
+  const { flags, rest } = parseFlags(argv.slice(1));
+
+  switch (sub) {
+    case 'status':
+    case 'ls':
+      await cmdStatus();
+      return;
+    case 'on':
+      await cmdOn(flags);
+      return;
+    case 'off':
+      await cmdOff();
+      return;
+    case 'add':
+      await cmdAdd(rest, flags);
+      return;
+    case 'rm':
+    case 'remove':
+      await cmdRm(rest);
+      return;
+    case 'ask':
+      await cmdAsk(rest);
+      return;
+    case 'help':
+    case '-h':
+    case '--help':
+      console.log(USAGE);
+      return;
+    default:
+      console.error(chalk.red(`未知子命令: ${sub}`));
+      console.log(USAGE);
+      process.exitCode = 1;
+  }
+}

package/src/config.js

@@ -249,25 +249,28 @@ export function normalizeAgentDefaultPrompt(value) {
  *   · firecrawl —— 无 key 也能用（按 IP 限流），注册免费 key 后每月 1,000 credits
  *   · tavily    —— 必须有 key（免费 1,000 credits/月）
  *   · exa       —— 必须有 key（免费 $10 credits/月）
+ *   · searxng   —— 自建实例，不需要 key；必须在 baseUrls.searxng 填实例地址
  */
-export const WEB_SEARCH_PROVIDERS = ['firecrawl', 'tavily', 'exa'];
+export const WEB_SEARCH_PROVIDERS = ['firecrawl', 'tavily', 'exa', 'searxng'];
 // 聚合模式标识（与 src/cli/ai/webSearch.js 的 WEB_SEARCH_AGGREGATE_ID 一致）。
 // 作为「默认搜索引擎」的合法取值 = 每次搜索都并发多家、合并去重。
 export const WEB_SEARCH_AGGREGATE_ID = 'all';
 const WEB_SEARCH_DEFAULT_PROVIDER = 'firecrawl';
 const WEB_SEARCH_API_KEY_MAX = 300;
+const WEB_SEARCH_BASE_URL_MAX = 300;
 const WEB_SEARCH_PROXY_MAX = 300;
 
 /**
  * 规范化「联网搜索」配置（全局配置，跨项目共享）。
  *
- * 形状：{ enabled, provider, apiKeys: {[provider]: key}, proxy }
+ * 形状：{ enabled, provider, apiKeys: {[provider]: key},
+ *         baseUrls: {[provider]: url}, proxy }
  *
  * 语义约定：
  *   · undefined / null → null（没配过，调用方回落 defaultConfig = 默认开启 + firecrawl）
  *   · 非普通对象（含数组）→ null（手改坏了，整组回落默认，与 normalizeAgent* 同一口径）
  *   · **单个字段坏只回落该字段**，不整组拒绝 —— 一个 key 写错不该把"开关/代理"也重置
- *   · apiKeys 只保留白名单 provider 的键；非字符串值 → 该键置空串
+ *   · apiKeys / baseUrls 只保留白名单 provider 的键；非字符串值 → 该键置空串
  *   · proxy 空串是合法值（= 直连），照写；非字符串 → 空串
  */
 export function normalizeWebSearch(value) {
@@ -276,9 +279,14 @@ export function normalizeWebSearch(value) {
   const rawKeys = (value.apiKeys && typeof value.apiKeys === 'object' && !Array.isArray(value.apiKeys))
     ? value.apiKeys : {};
   const apiKeys = {};
+  const rawBaseUrls = (value.baseUrls && typeof value.baseUrls === 'object' && !Array.isArray(value.baseUrls))
+    ? value.baseUrls : {};
+  const baseUrls = {};
   for (const p of WEB_SEARCH_PROVIDERS) {
     const v = rawKeys[p];
     apiKeys[p] = typeof v === 'string' ? v.trim().slice(0, WEB_SEARCH_API_KEY_MAX) : '';
+    const u = rawBaseUrls[p];
+    baseUrls[p] = typeof u === 'string' ? u.trim().slice(0, WEB_SEARCH_BASE_URL_MAX) : '';
   }
   const providerRaw = typeof value.provider === 'string' ? value.provider.trim().toLowerCase() : '';
   // 'all' = 聚合模式，也是合法的默认值（见 src/cli/ai/webSearch.js 的 resolveMode）
@@ -287,6 +295,7 @@ export function normalizeWebSearch(value) {
     enabled: typeof value.enabled === 'boolean' ? value.enabled : true,
     provider: providerOk ? providerRaw : WEB_SEARCH_DEFAULT_PROVIDER,
     apiKeys,
+    baseUrls,
     proxy: typeof value.proxy === 'string' ? value.proxy.trim().slice(0, WEB_SEARCH_PROXY_MAX) : '',
   };
 }
@@ -400,7 +409,8 @@ const defaultConfig = {
   webSearch: {
     enabled: true,
     provider: 'firecrawl',
-    apiKeys: { firecrawl: '', tavily: '', exa: '' },
+    apiKeys: { firecrawl: '', tavily: '', exa: '', searxng: '' },
+    baseUrls: { firecrawl: '', tavily: '', exa: '', searxng: '' },
     proxy: '',
   },
   // 工作台任务执行器（claude | opencode | codex | codebuddy）。全局配置，跨项目共享。

package/src/gitCommit.js

@@ -276,7 +276,29 @@ async function main() {
     }
 
     const startUIServer = await loadStartUIServer();
-    await startUIServer(false, false); // 传入noOpen=false, savePort=false
+
+    // `g ui --role=hub --port=5598`：跨机器的常驻节点。
+    //   hub     —— 只挂公共板块（工作台/项目管理/系统监控/思维导图），项目级路由一律不注册
+    //   project —— 默认，7 个板块都在（保持原行为）
+    // 端口在 hub 下是**钉死**的（被占直接失败，不顺延）：它会长期被别的进程按固定
+    // 地址访问，悄悄换端口比启动失败更难排查。
+    const readFlag = (name) => {
+      const withEq = process.argv.find((a) => a.startsWith(`--${name}=`));
+      if (withEq) return withEq.slice(name.length + 3).trim();
+      const idx = process.argv.indexOf(`--${name}`);
+      return idx >= 0 ? String(process.argv[idx + 1] || '').trim() : '';
+    };
+    const uiRole = readFlag('role').toLowerCase();
+    const uiPortRaw = Number(readFlag('port'));
+    const uiPort = Number.isInteger(uiPortRaw) && uiPortRaw > 0 && uiPortRaw < 65536 ? uiPortRaw : undefined;
+    // 自动拉起的 hub 带 --no-open：它是后台常驻进程，弹浏览器等于每次开项目窗口
+    // 都多蹦一个标签页。
+    const uiNoOpen = process.argv.includes('--no-open');
+
+    await startUIServer(uiNoOpen, false, {
+      role: uiRole === 'hub' ? 'hub' : (uiRole === 'full' ? 'full' : 'project'),
+      port: uiPort
+    }); // savePort=false
     return;
   }
 
@@ -312,6 +334,17 @@ async function main() {
     return;
   }
 
+  // 跨机器通信(g peer):让这台机器上的 g ai 与另一台机器的 g ai 互相提问。
+  //
+  // 配置写进 <DATA_DIR>/peers.json(不跟项目走),端口是**独立**的一个固定端口 ——
+  // 主服务没有认证层,绝不能把整张 /api 暴露到局域网,细节见 src/peer/server.js。
+  // 同样只认 argv[2],避免 `g -m peer` 被判成子命令。
+  if (process.argv[2] === 'peer') {
+    const { runPeerCli } = await import('./cli/peer.js');
+    await runPeerCli(process.argv.slice(3));
+    return;
+  }
+
   // 检查是否是添加脚本命令
   if (process.argv.includes('addScript')) {
     await addScriptToPackageJson();

package/src/paths.js

@@ -61,6 +61,12 @@ export const LEGACY_INSTANCES_DIR = path.join(os.homedir(), '.zen-gitsync-instan
 // 这里只登记路径,不参与搬迁。
 export const LEGACY_INSTANCES_FILE = path.join(os.homedir(), '.zen-gitsync-instances.json');
 
+// ── 跨机器 peer（g ai 与 g ai 对话）────────────────────────────
+// 身份(昵称/头像/token/固定端口) + 对端清单 + 每个对端续聊用的会话 id。
+// 与 config.json 分开存:它只跟"这台机器"有关,不属于任何项目,也不该跟着
+// 项目配置一起被同步/备份。
+export const PEERS_FILE = path.join(DATA_DIR, 'peers.json');
+
 // ── CLI 贴图 ─────────────────────────────────────────────────
 export const AI_IMAGES_DIR = path.join(DATA_DIR, 'ai-images');
 // 旧的是 ~/.git-commit-tool/ai-images(父目录名与主配置不同,少了个 .json)

package/src/peer/client.js

@@ -0,0 +1,165 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// peer 客户端：本机 g ai 去问别的机器（跨机器通信的"出口"）。
+//
+// 与 server.js 是镜像的两半：
+//   server.js —— 别人来问我（入口，固定端口，令牌校验）
+//   client.js —— 我去问别人（出口，读 peers.json 里的地址与令牌）
+//
+// 这一层不做自动发现：局域网里没有可信的发现协议（mDNS 在 Windows 上默认不开，
+// 广播包也穿不过 Wi-Fi 隔离），地址必须由用户显式登记 —— 也就意味着**不存在**
+// "随便一台机器就能连上来问"的情况，这正是我们要的。
+
+import {
+  listPeers,
+  findPeer,
+  getSessionId,
+  setSessionId,
+  ensureSelf
+} from './store.js';
+
+const INFO_TIMEOUT_MS = 4000;
+const ASK_TIMEOUT_MS = 10 * 60 * 1000;
+
+/**
+ * 打一个 peer 接口，统一超时与错误文案。
+ * @param {string} url
+ * @param {{method?:string, token:string, body?:object, timeoutMs?:number}} opts
+ */
+async function callPeer(url, { method = 'GET', token, body, timeoutMs = INFO_TIMEOUT_MS } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  timer.unref?.();
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token || ''}`,
+        ...(body ? { 'Content-Type': 'application/json' } : {})
+      },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: controller.signal
+    });
+    const text = await res.text();
+    let data = null;
+    try { data = text ? JSON.parse(text) : null; } catch { data = null; }
+
+    if (res.status === 401) throw new Error('令牌无效（对端 peers.json 里的 token 与本机不匹配）');
+    if (!res.ok || !data || data.ok === false) {
+      throw new Error(data?.error || `对端返回 ${res.status}`);
+    }
+    return data;
+  } catch (err) {
+    if (err?.name === 'AbortError') {
+      throw new Error(`连 ${url} 超时（${Math.round(timeoutMs / 1000)}s）`);
+    }
+    if (err instanceof TypeError) {
+      throw new Error(`连不上 ${url}（对方 g ui 没开 peer 端口、防火墙拦了，或地址写错）`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 取对端的身份信息（同时兼作"在不在线"的探活）。
+ * @param {{url:string, token:string}} peer
+ * @param {{timeoutMs?:number}} [opts]
+ */
+export async function fetchPeerInfo(peer, { timeoutMs = INFO_TIMEOUT_MS } = {}) {
+  return callPeer(`${peer.url}/api/peer/info`, { token: peer.token, timeoutMs });
+}
+
+/**
+ * 向对端提问，拿回它的回答。
+ *
+ * @param {object} peer peers.json 里的一条
+ * @param {object} self 本机身份（把 id 带过去，对端据此保持会话连续性）
+ * @param {string} question
+ * @param {{timeoutMs?:number}} [opts]
+ * @returns {Promise<{answer:string, sessionId:string, ms:number}>}
+ */
+export async function askPeer(peer, self, question, { timeoutMs = ASK_TIMEOUT_MS } = {}) {
+  const data = await callPeer(`${peer.url}/api/peer/ask`, {
+    method: 'POST',
+    token: peer.token,
+    body: { question, from: self?.id || '' },
+    timeoutMs
+  });
+  if (peer.id && data.sessionId) {
+    await setSessionId(`out:${peer.id}`, data.sessionId).catch(() => {});
+  }
+  return data;
+}
+
+/**
+ * 工具层用的"我都有哪些对端"—— 附带一次快速探活。
+ *
+ * 为什么把探活放在这里而不是常驻心跳：对端可能十天半个月不开机，常驻心跳只会
+ * 白烧请求；工具调用是低频的，届时有几台就探几台（并发，2s 级超时）。
+ *
+ * @param {{probe?:boolean}} [opts]
+ * @returns {Promise<Array<{id:string,name:string,url:string,online:boolean,label?:string}>>}
+ */
+export async function listPeerStatus({ probe = true } = {}) {
+  const peers = await listPeers();
+  if (!peers.length) return [];
+  return Promise.all(peers.map(async (p) => {
+    if (!probe) return { ...p, online: false };
+    try {
+      const info = await fetchPeerInfo(p, { timeoutMs: 2000 });
+      return { id: info.id || p.id, name: info.name || p.name, url: p.url, online: true, label: info.version || '' };
+    } catch {
+      return { ...p, online: false };
+    }
+  }));
+}
+
+/**
+ * 按 id 或昵称提问（工具层入口）。
+ *
+ * @param {string} ref 对端 id 或昵称；空 = 只有一台对端时自动选它
+ * @param {string} question
+ */
+export async function askPeerByRef(ref, question) {
+  const self = (await ensureSelf()).self;
+  const key = String(ref || '').trim();
+
+  let peer = key ? await findPeer(key) : null;
+  if (!peer && !key) {
+    const all = await listPeers();
+    if (all.length === 1) {
+      peer = await findPeer(all[0].url);
+    } else if (all.length > 1) {
+      throw new Error(`有多台对端，请指定 peer：${all.map((p) => p.name).join(' / ')}`);
+    }
+  }
+  if (!peer) {
+    const all = await listPeers();
+    throw new Error(all.length
+      ? `没有名为「${key}」的对端。现有：${all.map((p) => p.name).join(' / ')}`
+      : '还没有登记任何对端。在**对端机器**上开 `g peer on`，拿到它的地址和令牌后，在这台机器上执行 `g peer add <昵称> <地址> --token <令牌>`。');
+  }
+  if (!peer.url || !peer.token) throw new Error(`对端「${peer.name}」缺少地址或令牌，请重新 \`g peer add\``);
+
+  const result = await askPeer(peer, self, question);
+  return { peer, ...result };
+}
+
+/** 取与某个对端的上一次会话 id（调试/CLI 用）。 */
+export async function lastSessionIdOf(peerId) {
+  return getSessionId(`out:${peerId}`);
+}