dsh-mobile-plugin 0.5.17 → 0.5.19

package/config/agent-presets/standard/agent.cordis.yml

@@ -110,14 +110,23 @@
     config:
       - id: tool-subagent-control
         name: '@deepseek-ai/dsh-tool-subagent-control'
+      # 独立的 `list_agents` 入口只在 0.2.1 及更早存在；0.2.2 把它并进了主包，
+      # 子路径没了。这一行保留是为了老运行时，启动时宿主会按「这一代认不认这个
+      # 子路径」把副本里的这一行整行拿掉（见 lib/host-compat.cjs 的 dropRows）。
       - id: tool-subagent-list-agents
         name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+      # 子代理挑模型的开关，两代运行时键名不同：0.2.1 及更早读
+      # `modelSelectionSettings`，0.2.2 起改成 `modelSelection`（另加
+      # `modelDiscovery` 才让模型查得到可选模型）。两个键都写：各自的 schema 只认
+      # 自己那个、另一个原样忽略，所以同一份预设挂到哪一代都对。
       - id: tool-subagent
         name: '@deepseek-ai/dsh-tool-subagent'
         config:
           provider: spawn
           toolName: subagent
           modelSelectionSettings: true
+          modelSelection: true
+          modelDiscovery: true
           backgroundMode: continuable
       - id: tool-subagent-fork
         name: '@deepseek-ai/dsh-tool-subagent'

package/host.js

@@ -20,7 +20,7 @@ import { installProcessGuard } from './lib/host-guard.cjs'
 import { DIRECTORY_PICKER_ROW, TOOL_ROWS, pinInsertedRows, syncPresetDir } from './lib/host-compat.cjs'
 import { dropBareNameSelfMounts } from './lib/host-patches.cjs'
 import {
-  assertEntriesActivated,
+  auditStartupEntries as assertEntriesActivated,
   boot,
   evaluatePluginCompatibility,
   getDshRuntimeVersion,
@@ -29,11 +29,19 @@ import {
   loadLayeredEnv,
   loadOverlayPatches,
   loadProfile,
-  PROFILE_TEMPLATES,
   readProfileCompatibility,
   resolveProfileDir,
 } from '@deepseek-ai/dsh-app-boot'
 
+/**
+ * 新建 profile 时的初始组合层。
+ *
+ * 不从 `dsh-app-boot` 取 `PROFILE_TEMPLATES`：0.2.2 把这份清单挪进了
+ * `@deepseek-ai/dsh-official-bundles`，旧位置不再导出，而静态导入一个不存在的
+ * 命名导出是让整个宿主起不来（不是降级）。这里本来就只要 web 那一档的两行。
+ */
+const WEB_PROFILE_BUNDLES = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app']
+
 const BIN_NAME = 'dsh-mobile-plugin'
 const PROFILE_NAME = process.env.DSH_MOBILE_PROFILE || 'mobile'
 const PACKAGE_DIR = dirname(fileURLToPath(import.meta.url))
@@ -58,7 +66,7 @@ try {
   const home = process.env.DSH_HOME
   const profileDir = resolveProfileDir(PROFILE_NAME, home)
   // Idempotent: an already-initialized profile keeps its own patch layer.
-  initProfile(profileDir, PROFILE_TEMPLATES.web)
+  initProfile(profileDir, WEB_PROFILE_BUNDLES)
   const profile = loadProfile(BIN_NAME, PROFILE_NAME, INSTALL_ANCHOR, home, { userLayer: true })
 
   /**
@@ -142,6 +150,19 @@ try {
     )
   }
 
+  // 预设里「列子代理」那一行挂的是 `dsh-tool-subagent-control` 的一个子入口。
+  // 0.2.2 把那个工具并进了主包，子路径没有了 —— 留着它，每建一个会话都会有一行
+  // 起不来，而能力本身还在。判据是**这一代运行时认不认这个子路径**，不按版本号猜。
+  const listAgentsEntry = '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+  let listAgentsRowGone = false
+  try {
+    runtimeRequire?.resolve(listAgentsEntry)
+  } catch {
+    listAgentsRowGone = true
+    process.stderr.write(`${BIN_NAME}: 这一代运行时没有 ${listAgentsEntry}（该工具已并在主包里），预设副本里那一行不再挂\n`)
+  }
+  const dropPresetIds = listAgentsRowGone ? ['tool-subagent-list-agents'] : []
+
   // 预设里的两行默认按裸名写：Loader 从它自己的位置解析，命中哪一份不由我们决定。
   // 解析到了同代的那份就改写一份副本给它，路径写死成那一份的入口。
   const presetRoots = {}
@@ -149,11 +170,12 @@ try {
     const hit = pinnedRows.get(id)
     if (hit) presetRoots[id] = hit.entry
   }
-  const presetDir = TOOL_ROWS.some(({ id }) => presetRoots[id] !== undefined)
+  const presetDir = TOOL_ROWS.some(({ id }) => presetRoots[id] !== undefined) || dropPresetIds.length > 0
     ? syncPresetDir(
       join(PACKAGE_DIR, 'config', 'agent-presets'),
       join(profileDir, '.mobile-agent-presets'),
       presetRoots,
+      { dropIds: dropPresetIds },
     )
     : join(PACKAGE_DIR, 'config', 'agent-presets')
 

package/lib/host-compat.cjs

@@ -8,6 +8,9 @@
  * 所以启动时先问运行时那棵树要同代的那一份，拿到就把行的 `name` 换成它的入口绝对路径，
  * 绕开按裸名解析；拿不到就保持原样，让官方检查去禁用并打印原因。
  *
+ * 还有另一种形状：入口本身没了（0.2.2 把 `list_agents` 并进主包，子路径随之下线）。
+ * 那一条换成哪一份都没用，只能整行从预设副本里拿掉 —— 见 `dropRows`。
+ *
  * 这里只放纯函数：`host.js` 一 import 就 `boot()` 整个宿主，测试碰不得。
  */
 
@@ -76,21 +79,64 @@ function rewriteToolNames(source, targets) {
  * @param {string} presetDir 包内 `config/agent-presets`
  * @param {string} outDir 宿主可写的目标目录
  * @param {Record<string, string>} targets 行 id → 入口绝对路径
+ * @param {{ dropIds?: string[] }} [options] 这一代运行时里不再有独立入口的行
  * @returns {string} 真正该交给 `agent-presets` roots 的目录
  */
-function syncPresetDir(presetDir, outDir, targets) {
+function syncPresetDir(presetDir, outDir, targets, options = {}) {
   fs.rmSync(outDir, { recursive: true, force: true })
   fs.cpSync(presetDir, outDir, { recursive: true })
-  if (Object.keys(targets).length === 0) return outDir
+  const dropIds = options.dropIds ?? []
+  if (Object.keys(targets).length === 0 && dropIds.length === 0) return outDir
   for (const entry of fs.readdirSync(outDir, { recursive: true, withFileTypes: true })) {
     if (!entry.isFile() || !entry.name.endsWith('.yml')) continue
     const file = path.join(entry.parentPath ?? entry.path, entry.name)
-    const { text, changed } = rewriteToolNames(fs.readFileSync(file, 'utf8'), targets)
-    if (changed.length > 0) fs.writeFileSync(file, text)
+    const original = fs.readFileSync(file, 'utf8')
+    const trimmed = dropRows(original, dropIds)
+    const { text, changed } = rewriteToolNames(trimmed, targets)
+    if (changed.length > 0 || trimmed !== original) fs.writeFileSync(file, text)
   }
   return outDir
 }
 
+/**
+ * 去掉预设里指定的整行（含它下面缩进更深的配置）。
+ *
+ * 给「这一代运行时里已经没有这个独立入口」的行用：留着它，Loader 会按裸名去 import
+ * 一个不存在的子路径，那一行起不来；能力本身可能已经并进主包，所以不是缺工具，
+ * 只是多了一条注定失败的行。
+ *
+ * @param {string} source 预设文件内容
+ * @param {string[]} ids 要整行删掉的入口 id
+ * @returns {string} 删完的文本（没命中就原样返回）
+ */
+function dropRows(source, ids) {
+  if (ids.length === 0) return source
+  const targets = new Set(ids)
+  const lines = source.split('\n')
+  const indentOf = (line) => line.length - line.trimStart().length
+  const kept = []
+  let dropping = false
+  let dropIndent = 0
+  for (const line of lines) {
+    const id = ROW_ID.exec(line)
+    if (dropping) {
+      // 同级的下一行或更浅的一行就是这条的边界；更深的仍是它的配置。
+      if (id || (line.trim() !== '' && indentOf(line) <= dropIndent)) dropping = false
+    }
+    if (id && targets.has(id[2])) {
+      dropIndent = indentOf(line)
+      // 紧挨着这一行上方的注释块是在说它，跟着一起删；留下会说反话的说明。
+      while (kept.length > 0 && kept[kept.length - 1].trim().startsWith('#') && indentOf(kept[kept.length - 1]) >= dropIndent) {
+        kept.pop()
+      }
+      dropping = true
+      continue
+    }
+    if (!dropping) kept.push(line)
+  }
+  return kept.join('\n')
+}
+
 /**
  * 把 patch 层里命中目标的 `name` 换成入口绝对路径。
  *
@@ -115,6 +161,7 @@ module.exports = {
   TOOL_ROWS,
   DIRECTORY_PICKER_ROW,
   rewriteToolNames,
+  dropRows,
   syncPresetDir,
   pinInsertedRows,
 }

package/lib/impl.js

@@ -33,6 +33,7 @@ const { lanUrls, advertisedCandidates, phoneCandidates, ipv6Candidates, withManu
 const { pairingPayload } = require('./relay/pairing-payload.cjs')
 const { resolvePort } = require('./relay/port-allocator.cjs')
 const { createPreviewService } = require('./relay/preview.js')
+const { mountTerminal, mountCli } = require('./mobile/services.js')
 // 手机打开「电脑上的网页版」时用的那枚一次性登录令牌（见 mobile/host-web.js）。
 const hostWeb = require('./mobile/host-web.js')
 // 本机设备凭据库：/api/relay/revoke-all 必须同时吊销局域网直连的 dshc_ 凭据，
@@ -42,6 +43,7 @@ const credentials = require('./shared/credentials-entry.js').credentialsEntry()
 const { createApiProxy } = require('./mobile/host-bridge.js')
 const { installApprovalBridge } = require('./mobile/approvals.js')
 const { installQuestionBridge } = require('./mobile/questions.js')
+const { installNarration } = require('./mobile/narration.js') // 过程播报：默认关，开关真值每步现读
 // 「手机上最近来过没有」：守卫记、控制面状态读。单独一个模块，装配层只转交。
 const activity = require('./mobile/activity.cjs')
 const { installSessionCleanup } = require('./session-cleanup.cjs')
@@ -50,6 +52,7 @@ const { installSessionCleanup } = require('./session-cleanup.cjs')
 const statsScheduler = require('./mobile/stats-scheduler.cjs')
 // 扩展卡的宿主侧：`extension_present` 工具与卡状态账本（见 mobile/extensions.js）。
 const { installExtensions } = require('./mobile/extensions.js')
+const { mountPhoneControl } = require('./mobile/phone/index.js') // 「让 AI 操作手机」，见 mobile/phone/
 const { activeGuard } = require('./host-guard.cjs')
 // 桌面端侧栏展开态的快照存储。桌面把这份状态只记在浏览器 localStorage 里，宿主必须
 // 有一个落盘处：客户端半边（lib/client.js）上报 → 这里 → 移动端读取。
@@ -360,6 +363,7 @@ function apply(ctx) {
     return undefined
   }, `${name}: extension tool`)
   mount('统计采集', () => ctx.effect(() => statsScheduler.start(ctx), `${name}: stats collect`))
+  mount('过程播报', () => ctx.effect(() => installNarration(ctx), `${name}: process narration`))
 
   const status = createStatusView({
     state,
@@ -487,6 +491,8 @@ function apply(ctx) {
     // 一样必须包在 ctx.effect 里，否则插件重载时重复注册会直接抛错。
     registerUpgradeRoute: (route) => mountRoute(route, true),
     preview,
+    terminalService: mountTerminal(ctx, { authorized, name }), cliService: mountCli(ctx, { authorized, name }),
+    phoneService: mountPhoneControl(ctx, { authorized, credentials, instanceId: state.instanceId, name }),
     // 网页版登录令牌那条：handler 在这里造好、按依赖交给路由表，理由与 preview 一样——
     // 它要读的是本进程的 `ctx.webServer` 与 `ctx.get('connection')`。
     hostWeb: hostWeb.handleHostWeb,

package/lib/mobile/cli/acp.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * 一个 ACP 适配器子进程 = 一条 CLI 会话的**连接层**。
+ *
+ * 协议实现用官方库 `@agentclientprotocol/sdk`（稳定 v1 入口），不自己写 JSON-RPC：
+ * 那正是这次不做「逐家适配」的关键 —— 四家 CLI 的差别全被适配器吃掉了，这里只认一种协议。
+ *
+ * 为什么用动态 `import()`：插件这一层是 CJS（`lib/mobile/package.json`），而 SDK 是纯 ESM。
+ * 稳定入口**零运行时依赖**（zod 只是可选 peer，稳定入口没 import 它），所以这个 import 不
+ * 会拖出额外的东西。
+ *
+ * `session/update` 一律走 `onNotification` 自己接，**不用** SDK 的 `ActiveSession`：后者会把
+ * 每条更新再排进一个内部队列供 `nextUpdate()` 取，我们从不取，等于给每个会话攒一个只涨不
+ * 落的数组。
+ */
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const { Readable, Writable } = require('node:stream');
+
+const { childEnv } = require('./agents.js');
+const { openImage } = require('./images.js');
+
+/** 握手超时：适配器第一次要 npx 下载，给足；再久就当它起不来了。 */
+const START_TIMEOUT_MS = 180000;
+
+/**
+ * 报给适配器的客户端身份。
+ *
+ * `version` **不能省**：ACP 的 `Implementation` 把它标成可选，但 opencode 那边的校验是
+ * 必填的 —— 少这一格整条 `initialize` 会回 `-32602 Invalid params`，表现就是界面上一直
+ * 「正在启动」（适配器根本没接上）。codex / claude 不挑，所以只有 opencode 会露出来。
+ */
+const CLIENT_INFO = { name: 'dsh-mobile', version: pluginVersion() };
+
+function pluginVersion() {
+  try {
+    const version = require('../../package.json').version;
+    return typeof version === 'string' && version ? version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+let sdkPromise = null;
+
+function loadSdk() {
+  if (!sdkPromise) sdkPromise = import('@agentclientprotocol/sdk');
+  return sdkPromise;
+}
+
+function noop() {}
+
+/**
+ * 起适配器并完成握手，返回一个会话句柄。
+ *
+ * 失败一律抛错，`message` 是要给用户看的人话（服务层把它变成一条 notice 块 + exit 帧）。
+ */
+async function startAgent({ spec, cwd, env, onUpdate, onPermission, onStderr, onExit }) {
+  const sdk = await loadSdk();
+  const child = spawn(spec.command, spec.args, {
+    cwd,
+    env: env || childEnv(spec.command),
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  let exited = false;
+  child.stdin.on('error', noop);
+  child.stdout.on('error', noop);
+  child.stderr.on('error', noop);
+
+  let stderrTail = '';
+  if (onStderr) {
+    child.stderr.on('data', (chunk) => {
+      const text = String(chunk);
+      stderrTail = (stderrTail + text).slice(-2000);
+      onStderr(text);
+    });
+  }
+
+  child.on('error', (error) => {
+    if (exited) return;
+    exited = true;
+    onExit?.(error && error.message ? error.message : '适配器起不来');
+  });
+
+  const app = sdk.client({ name: 'dsh-mobile' });
+  app.onRequest(sdk.methods.client.session.requestPermission, async (ctx) => {
+    // 适配器等这一个 promise 决定「放不放行」，所以它必须**只有一条** resolve 路径：
+    if (!onPermission) return { outcome: { outcome: 'cancelled' } };
+    return onPermission(ctx.params);
+  });
+  app.onNotification(sdk.methods.client.session.update, (ctx) => {
+    try {
+      onUpdate?.(ctx.params && ctx.params.update);
+    } catch { /* 一条更新解析失败不该掐断整条流 */ }
+  });
+
+  const stream = sdk.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+  const conn = app.connect(stream);
+
+  conn.closed.then(() => {
+    if (exited) return;
+    exited = true;
+    onExit?.(stderrTail.trim().split('\n').slice(-1)[0] || '适配器退出了');
+  }, noop);
+
+  /** 握手整体超时。 */
+  const deadline = new Promise((_resolve, reject) => {
+    setTimeout(() => {
+      reject(new Error('适配器启动超时，可能卡在下载或登录上'));
+    }, START_TIMEOUT_MS).unref?.();
+  });
+
+  let promptCapabilities = null;
+  const session = await Promise.race([
+    (async () => {
+      const initialized = await conn.agent.request(sdk.methods.agent.initialize, {
+        protocolVersion: sdk.PROTOCOL_VERSION,
+        // 不认领文件系统与终端能力：四家 CLI 都有自己的文件访问，我们替它读写反而要多做
+        // 一套实现，做漏了就是一条静默失败的路。
+        clientCapabilities: { terminal: false },
+        clientInfo: CLIENT_INFO,
+      });
+      // 这家认不认图片输入：握手时它自己说。不说就按「不支持」处理 —— 硬塞 image 块过去，
+      // 有的适配器会直接回一条参数错误，把整轮提问连正文一起废掉。
+      promptCapabilities = (initialized && initialized.agentCapabilities && initialized.agentCapabilities.promptCapabilities) || null;
+      const created = await conn.agent.request(sdk.methods.agent.session.new, {
+        cwd,
+        mcpServers: [],
+      });
+      return { sessionId: created.sessionId, created };
+    })(),
+    deadline,
+  ]);
+
+  function kill() {
+    try { conn.close(); } catch { /* 已经关了 */ }
+    try { child.kill('SIGTERM'); } catch { /* 已经退出 */ }
+  }
+
+  return {
+    child,
+    sessionId: session.sessionId,
+    created: session.created,
+    /**
+     * 会话创建时给出的可配置项（模型 / 思考档 / 权限模式…）与模式表。
+     *
+     * ACP 把它们定成「客户端画一组下拉、选中就回一条 set」，各家 CLI 的差别全被吃掉：
+     * opencode 把模型放在 `configOptions`，claude 把模式放在 `modes`，codex 两者都给。
+     * 所以手机上的「选模型」不需要为每家写一套，照着这两张表画就行。
+     */
+    configOptions: Array.isArray(session.created.configOptions) ? session.created.configOptions : [],
+    modes: session.created.modes ?? null,
+    /** 这家认不认图片输入（握手时它自己声明的 `promptCapabilities.image`）。 */
+    get supportsImages() { return Boolean(promptCapabilities && promptCapabilities.image); },
+    get alive() { return !exited; },
+    /**
+     * 发一轮提问；resolve 时这一轮结束（ACP 的 `session/prompt` 就是这么定的）。
+     *
+     * `images` 是已经存好的图片元数据（`{ attachmentId, mediaType }`）：按 ACP 的 image 块
+     * 发过去 —— `{type:'image', data, mimeType}`，字节在这一次请求里内联（ACP 只有这一种
+     * 传法，没有「你自己去读这个路径」的入口，我们也没认领 fs 能力）。
+     */
+    prompt(text_, images) {
+      const blocks = [];
+      for (const image of Array.isArray(images) ? images : []) {
+        const stored = openImage(image && image.attachmentId);
+        if (!stored) continue;
+        try {
+          blocks.push({
+            type: 'image',
+            data: fs.readFileSync(stored.path).toString('base64'),
+            mimeType: stored.mediaType || image.mediaType || 'image/png',
+          });
+        } catch { /* 读不出来就只丢这一张，正文照发 */ }
+      }
+      if (text_) blocks.push({ type: 'text', text: text_ });
+      if (blocks.length === 0) blocks.push({ type: 'text', text: '' });
+      return conn.agent.request(sdk.methods.agent.session.prompt, {
+        sessionId: session.sessionId,
+        prompt: blocks,
+      });
+    },
+    cancel() {
+      return conn.agent.notify(sdk.methods.agent.session.cancel, { sessionId: session.sessionId });
+    },
+    /** 改一项配置（选模型 / 换思考档）。`configId` 就是 `configOptions[].id`。 */
+    setConfigOption(configId, value) {
+      return conn.agent.request(sdk.methods.agent.session.setConfigOption, {
+        sessionId: session.sessionId,
+        configId,
+        value,
+      });
+    },
+    /** 换模式（claude 的 Manual / Accept edits / Plan 那一组）。 */
+    setMode(modeId) {
+      return conn.agent.request(sdk.methods.agent.session.setMode, {
+        sessionId: session.sessionId,
+        modeId,
+      });
+    },
+    close() {
+      // 会话收尾是尽力而为：适配器不支持 `session/close` 就直接断进程。
+      try {
+        conn.agent.request(sdk.methods.agent.session.close, { sessionId: session.sessionId }).catch(noop);
+      } catch { /* 同上 */ }
+      kill();
+      setTimeout(kill, 1500).unref?.();
+    },
+    kill,
+  };
+}
+
+module.exports = { startAgent, loadSdk, START_TIMEOUT_MS };

package/lib/mobile/cli/agents.js

@@ -0,0 +1,217 @@
+'use strict';
+
+/**
+ * CLI 对话的适配器白名单 —— `/api/mobile/v1/cli/*` 能起什么进程的**全部**依据。
+ *
+ * 与远程终端那份白名单（`mobile/terminal.js` 的 `AGENTS`）是同一档边界，只是走的口子不同：
+ * 终端把 CLI 的 TUI 原样搬给手机，这里让 CLI 以 **ACP（Agent Client Protocol）** 的方式跑，
+ * 手机收到的是结构化的「消息 / 工具调用 / 审批请求」，于是对话页能像正常对话一样渲染。
+ *
+ * 四种 CLI 起法有两种：
+ *
+ *   - `gemini --acp`、`opencode acp`：CLI **自己**就实现了 ACP 服务端，直接起。
+ *   - codex / claude：CLI 本身没有 ACP，靠官方 npm 桥（`@agentclientprotocol/*`）。桥包自带
+ *     对应的 CLI 依赖、并复用本机登录态，所以本机装没装 `codex` / `claude` 不影响。
+ *
+ * **这张表是兜底，不是清单本身**：真正「能起哪些」来自官方 ACP 注册表（见 `cli/registry.js`），
+ * 注册表里走 npx 分发的都能起，新 CLI 上线不必我们发版。下面这四条是它的降级档 —— 离线、
+ * 注册表拉不到、盘上也没有缓存时，仍然有四家用，而不是一个空清单。
+ *
+ * 内置这四条**永远出现在清单里**（它们是本仓维护的那一档，桥包由 npx 按需拉）；注册表补进来
+ * 的那些则要求「这台电脑上真的装了」——见 `installedPackages`。
+ *
+ * `cursor-agent` / `aider` 没有 ACP 实现，所以在这一侧根本不存在 —— 它们仍然只能从终端页进
+ * （那一份表在 `terminal.js`，两边各管各的能力面）。
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { findExecutable } = require('../terminal.js');
+
+/**
+ * `transport` 只描述**怎么起**，不代表能力差别：
+ *   - `native`：CLI 自带的 ACP 子命令，参数写在 `args`。
+ *   - `npx`   ：官方桥包。本机已经全局装了同名可执行就直接用，否则 `npx -y <包名>`。
+ *
+ * `package` 是 npx 分发那一档的包名（注册表里可能带版本，原样收着：版本由注册表钉住）。
+ */
+const AGENTS = [
+  {
+    id: 'codex',
+    label: 'Codex',
+    transport: 'npx',
+    package: '@agentclientprotocol/codex-acp',
+    bin: 'codex-acp',
+  },
+  {
+    id: 'claude',
+    label: 'Claude Code',
+    transport: 'npx',
+    package: '@agentclientprotocol/claude-agent-acp',
+    bin: 'claude-agent-acp',
+  },
+  {
+    id: 'gemini',
+    label: 'Gemini CLI',
+    transport: 'native',
+    bin: 'gemini',
+    args: ['--acp'],
+  },
+  {
+    id: 'opencode',
+    label: 'OpenCode',
+    transport: 'native',
+    bin: 'opencode',
+    args: ['acp'],
+  },
+];
+
+function findAgent(id) {
+  return AGENTS.find((agent) => agent.id === id) || null;
+}
+
+/**
+ * 子进程的 PATH。
+ *
+ * 宿主可能是从 Finder / 应用图标起的，那种进程的 PATH 常常只有 `/usr/bin:/bin`，`npx` 的
+ * shebang 是 `#!/usr/bin/env node`，找不着 node 就直接退出。所以把「当前跑宿主的那个 node」
+ * 和「适配器所在目录」垫到最前面 —— 只补这两处，不去猜用户 shell 的 PATH。
+ */
+function childEnv(command, env = process.env) {
+  const key = env.PATH !== undefined || env.Path === undefined ? 'PATH' : 'Path';
+  const base = env[key] || '';
+  const seen = new Set();
+  const merged = [path.dirname(process.execPath), path.dirname(command), ...base.split(path.delimiter)]
+    .filter((dir) => {
+      if (!dir || seen.has(dir)) return false;
+      seen.add(dir);
+      return true;
+    });
+  return { ...env, [key]: merged.join(path.delimiter) };
+}
+
+/** 去掉 `@scope/name@1.2.3` 尾部的版本，得到 npm 认的包名。 */
+function barePackage(pkg) {
+  const name = String(pkg || '').trim();
+  if (!name) return '';
+  // `@scope/name@1.2.3` / `name@1.2.3`：最后一个 `@` 在首位之后才是版本分隔。
+  const at = name.lastIndexOf('@');
+  return at > 0 ? name.slice(0, at) : name;
+}
+
+/** 一个 `node_modules` 目录下有没有这个包（两段式名字按第一段进一层）。 */
+function hasPackageIn(dir, name) {
+  try {
+    const stat = fs.statSync(path.join(dir, name));
+    return stat.isDirectory();
+  } catch {
+    try {
+      return fs.statSync(path.join(dir, name, 'package.json')).isFile();
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * 这台电脑上已经装了的 npm 包（只认名字，一份 Set）。
+ *
+ * 为什么要它：注册表里有二十来家能 npx 拉起的 ACP 适配器，全列出来等于给用户看一屏他从没
+ * 装过的东西 —— 点下去要么下载几十秒，要么卡在登录上。手机上要的是「这台电脑现在能聊哪些」。
+ *
+ * 三个来源，全是读目录（不 spawn npm，列一次清单不该等一个子进程）：
+ *
+ *   1. 跑宿主的那个 node 旁边的 `lib/node_modules`（Homebrew / 官方安装包的路子）；
+ *   2. `NPM_CONFIG_PREFIX` 指的全局根（用户自己配过的）；
+ *   3. `~/.npm/_npx` 下每一份 `node_modules`（npx 拉过一次就留在那儿，桥包通常就在这一档）。
+ *
+ * 探不到就返回空集 —— 那种情况下注册表那一条当「没装」处理，内置四条照旧在。
+ */
+function installedPackages(env = process.env) {
+  const roots = [];
+  if (env.NPM_CONFIG_PREFIX) roots.push(path.join(env.NPM_CONFIG_PREFIX, 'lib', 'node_modules'));
+  if (env.NPM_GLOBAL_ROOT) roots.push(env.NPM_GLOBAL_ROOT);
+  roots.push(path.join(path.dirname(process.execPath), '..', 'lib', 'node_modules'));
+  roots.push(path.join(os.homedir(), '.npm-global', 'lib', 'node_modules'));
+  const npxCache = path.join(os.homedir(), '.npm', '_npx');
+  try {
+    for (const entry of fs.readdirSync(npxCache)) {
+      roots.push(path.join(npxCache, entry, 'node_modules'));
+    }
+  } catch {
+    // 没有 npx 缓存目录就是没走过 npx：不影响别的来源。
+  }
+
+  const names = new Set();
+  for (const dir of roots) {
+    let entries = [];
+    try { entries = fs.readdirSync(dir); } catch { continue; }
+    for (const entry of entries) {
+      if (entry.startsWith('.')) continue;
+      if (entry.startsWith('@')) {
+        let scoped = [];
+        try { scoped = fs.readdirSync(path.join(dir, entry)); } catch { continue; }
+        for (const child of scoped) names.add(`${entry}/${child}`);
+        continue;
+      }
+      names.add(entry);
+    }
+  }
+  return names;
+}
+
+/** 这个包在这台电脑上装了没有（`bin` 在 PATH 里也算装了 —— 那是同一件事的另一半）。 */
+function isInstalled(agent, installed, env = process.env) {
+  if (!agent) return false;
+  if (agent.bin && findExecutable(agent.bin, env)) return true;
+  const name = barePackage(agent.package);
+  return Boolean(name && installed && installed.has(name));
+}
+
+/**
+ * 这台电脑上能不能起这个 CLI。
+ *
+ * 回 `{ ok: true, command, args, via }` 或 `{ ok: false, reason }`；`reason` 直接给界面用，
+ * 所以是一句人话，不是错误码。
+ *
+ * `ok` 说的是「现在点得下去、起得来」：`npx` 那一档只要本机有 npx 就成立（首次会下载桥包，
+ * 之后走缓存）。要不要把它列进选择卡是另一件事，由 `isInstalled` 判（见 `service.listAgents`）。
+ *
+ * `npx` 那一档的参数要跟着一起给：注册表里不少包本身不是 ACP 服务端，得靠自己的子命令进
+ * ACP 模式（`cline --acp`、`bob acp`、`droid exec --output-format acp-daemon`）。只给包名
+ * 的话进程起来就是一个普通 CLI，握手永远等不到 —— 表现是「一直在启动」。
+ */
+function resolveAgent(agent, env = process.env) {
+  if (!agent) return { ok: false, reason: '不认识这个 CLI' };
+  try {
+    const extra = Array.isArray(agent.args) ? agent.args.filter((arg) => typeof arg === 'string') : [];
+    if (agent.transport === 'native') {
+      const bin = findExecutable(agent.bin, env);
+      if (!bin) return { ok: false, reason: `这台电脑上没有装 ${agent.label}`, via: 'native' };
+      return { ok: true, command: bin, args: extra, via: 'native' };
+    }
+    // 桥包已经全局装过就省掉一次 npx 解析；没有就交给 npx 拉（首次会下载，之后走缓存）。
+    const installedBin = agent.bin ? findExecutable(agent.bin, env) : null;
+    if (installedBin) return { ok: true, command: installedBin, args: extra, via: 'installed' };
+    const npx = findExecutable('npx', env) || findExecutable('npm', env);
+    if (!npx) return { ok: false, reason: `这台电脑上没有 npx，起不了 ${agent.label}` };
+    const args = path.basename(npx) === 'npx'
+      ? ['-y', agent.package, ...extra]
+      : ['exec', '-y', '--', agent.package, ...extra];
+    return { ok: true, command: npx, args, via: 'npx' };
+  } catch {
+    return { ok: false, reason: `探测 ${agent.label} 的时候出错了` };
+  }
+}
+
+module.exports = {
+  AGENTS,
+  findAgent,
+  resolveAgent,
+  childEnv,
+  installedPackages,
+  isInstalled,
+  barePackage,
+};