#89 fact-only CLI discovery engine：给守护进程装一双「只报事实、不下判断」的眼睛

figuretu/eyrie · 6fc7e10...cc84312（feat/agent-discovery）· 2026-06-20 · 自包含，读完即弃

写法说明：本文按「逐跳走读」展开——每个机制都给真实代码片段（取自分支、经裁剪，青色斜体注释为解读所加，灰色斜体是源码原注释的保留或意译），每段代码标注所在文件。每条旅程结尾有一张「排查路标」：将来出问题时，症状对应去哪个文件看哪个函数。本报告只做理解，不做 code review。

1TL;DR

守护进程过去只知道「这个 provider 配了没、启没启用」，从不去磁盘上看 Claude / Codex 的命令行工具到底装没装。这个 PR 加了一台只报事实的探测引擎：它在 PATH 上找可执行文件、跑 --version 解析版本号、定位 CLI 的元数据目录，然后只汇报它看到了什么——装在哪、什么版本、哪些目录在——绝不输出「能不能用」这种判断。

判断留给上面一层「地基」。地基把事实折叠成可用性（availability）和漂移（drift）状态，落库持久化，再通过两个新 tRPC 端点（providers.list / providers.refresh）端给前端。整个设计的灵魂是一条克制的规矩：探到的安装路径一旦被锚定，就跨多次探测一直盯着它；哪天它消失了，就每次探测都报「漂移」，永远不自动改投到引擎新排出来的那个安装——改投是用户的显式动作，不是探测的副作用。

动机来自 commit 与 PR 描述：把 CLI「在不在场」这件事变成守护进程能持续观测、能持久化、能解释「为什么不对劲」的一等状态——而不是每次要用时临时 which 一下、装没装全凭运气。

2变更地图（称重）

2365 行改动里几乎没有机械搬运——没有 rename、没有 lockfile、没有等价替换。除了若干测试为适配新构造函数签名补了一两行，其余全是设计承载代码。新增文件集中在一个全新目录 agent/discovery/，地基与接线散在既有 agent 模块里。

3架构一图流

结构上多了一个进程角色：一台后台探测引擎，在守护进程启动时被装配进来、点火做一次全量探测，并在守护进程关闭时被 dispose。读取路径（detectAll）依旧是纯数据库读，只是现在读出来的行里多了探测写回去的几列。

前端这次拿到两个新入口：providers.list（读出每个启用 provider 的可用性，含持久化的探测态）和 providers.refresh（对一个 provider 重新探测一次再返回刷新后的可用性）。另外加了一条编译期边界：discovery/ 目录下的任何文件都不许 import 任何 provider 适配器——探测引擎是共享基础设施，只能「按 kind」认识 provider，不能反过来钻进某个具体适配器里。

4数据与状态先行

先把这个 PR 引入的几个形状的「样子」看清，行为留给后面的旅程。整套类型的共同主题是把「缺席」和「故障」掰成两件事：每一处状态都是三态而不是布尔。

4.1探测快照 DiscoveryResult 与它的三态们

引擎对一个 CLI 探完，产出一个 DiscoveryResult。注意它没有任何「能不能用」字段——只有装态、候选列表、版本、目录、时间戳。

// 安装结论：errored 故意区别于 not-installed——探测故障绝不能读成「不在」
export type InstallStatus = 'installed' | 'not-installed' | 'errored'

// 一个 PATH 候选的探测结论：可执行命中('ok') 或 在场但用不了('errored')
export type CliCandidateStatus = 'ok' | 'errored'

// 元数据目录的存在性：unreadable 是探测故障，不是缺席
export type DirectoryProbeStatus = 'present' | 'absent' | 'unreadable'

// --version 的结果：跑没跑、能不能解析、超时还是出错
export type VersionStatus =
  | 'ok' | 'unparseable' | 'timeout' | 'errored' | 'skipped'

export type DiscoveryResult = {
  kind: AgentProviderKind          // 这个 CLI 撑哪个 provider，地基用它对上库里的行
  status: InstallStatus
  candidates: CliCandidate[]       // 每个在磁盘上留了痕的 PATH 候选，按 PATH 优先级排
  version?: string                 // primary 候选解析出的版本
  versionStatus: VersionStatus
  directories: DirectoryProbe[]    // 定位到的元数据目录，只记在不在 + 变更指纹，从不读内容
  probedAt: number
}

每个候选（CliCandidate）带 path / status / primary。primary 标的是「引擎会用的那一个」——PATH 顺序里第一个 ok 候选。这个「列出全部候选、只钦点第一个能用的」结构，是后面那条 unreadable 修复的直接产物（见旅程 A）。

4.2持久化快照 ProviderDetectionSnapshot 与可用性的「诚实分裂」

地基把事实折叠成一个会落库的快照。它存进 agent_providers.agentInfoJson，是 daemon 内部结构，从不跨进 @eyrie/api。

export type ProviderDetectionSnapshot = {
  installStatus: ProviderInstallStatus  // 比引擎多一个 'unknown'：没编目 / 没探过的行
  version?: string
  binaryPath?: string          // 「在用的那个安装」——锚点。漂移检测就盯着它
  detectedAt: number
  reason?: string              // 为什么探测态是降级的：漂移 / 探测故障 / 版本故障
}

最关键的认知更新在 AgentAvailability 上：available 和 installStatus 被刻意分成两件事。一句源码注释把界限钉死了——available 是「配了、启用了、有适配器撑着」，installStatus 是「磁盘上那个二进制到底找没找到」。两者无关：一个 provider 可以 available: true 同时 installStatus: 'not-installed'（配置齐全但 CLI 没装）。

export type AgentAvailability = {
  // ...
  available: boolean           // 配了 + 启用 + 有适配器——不是「装没装」的声明
  installStatus?: ProviderInstallStatus  // 诚实的安装信号，和 available 分开
  binaryPath?: string          // 检测解析出的在用安装绝对路径
  detectedAt?: number          // 上次探测的 unix 毫秒，给「最近检查于」显示
  reason?: string              // 检测降级的原因，含「已装但探测/版本出错」
  // ...
}

这套字段原样镜像进 packages/api 的 AgentAvailabilityDto（多了 capabilities / models / sessionConfig 这些既有面），给前端用。DTO 里 installStatus 的联合类型 'installed' | 'not-installed' | 'errored' | 'unknown' 是手抄的，不是从 daemon 类型导入的——这是跨仓边界的常规做法。

5底座：探测引擎的两条公共机制

两条旅程（启动 sweep、前端 refresh）都从同一个引擎下潜。下潜前先建立两个公共认知：所有外部接触都走「端口」，以及引擎怎么管并发与生命周期。

5.1四个可替换端口：为什么要这层抽象

引擎不直接调 execFile 或 fs，而是把所有「跨出自己进程」的动作收进四个端口：跑命令、stat 文件、读时钟、读平台事实。测试给这四个全塞假货，于是探测能在任何 CI 机器上跑——哪怕那台机器根本没装 Claude / Codex。这就是这层抽象存在的理由：探测结果不再取决于跑测试的机器上恰好装了什么。

export type DiscoveryPorts = {
  command: CommandRunner   // 跑 --version，唯一真正需要子进程的缝
  files: FileProber        // stat 文件/目录，从不打开或读内容
  clock: Clock             // 供给探测时间戳
  platform: PlatformInfo   // 平台事实：PATH 各项、home 目录、环境变量
}

PlatformInfo 是个快照值对象，不是实时查询——一个假平台就能在测试里完全决定跨操作系统的路径解析（假装自己是 linux、home 在 /home/tester、PATH 是某两个目录）。命令运行器有个克制的契约：非零退出和超时都resolve 而不是 throw，把「进程跑挂了」变成一个可分类的结果而不是要 catch 的异常。

5.2引擎：合并并发探测 + dispose 中止

DiscoveryEngine 包着 catalog 和 ports，对外只有 probeAll() / reprobe(kind) / dispose()。它解决的具体问题是：一阵突发的 reprobe 请求不该对同一个 CLI 同时 spawn 好几个 --version 进程。

async reprobe(kind: AgentProviderKind): Promise<DiscoveryResult> {
  if (this.disposed) throw new Error('DiscoveryEngine has been disposed')
  const entry = this.entriesByKind.get(kind)
  if (!entry) throw new Error(`Unknown discovery CLI kind: ${kind}`)

  const existing = this.inFlight.get(kind)
  if (existing) return existing      // 同 kind 已有在飞的探测：直接复用，不再 spawn

  const probe = probeCli(entry, this.ports, options).finally(() => {
    this.inFlight.delete(kind)       // 落定后清缓存，下次 reprobe 是全新一轮
  })
  this.inFlight.set(kind, probe)
  return probe
}

dispose(): void {                    // 中止在飞的版本命令并拦住后续探测；幂等
  if (this.disposed) return
  this.disposed = true
  this.abortController.abort()       // 共享 AbortSignal，已穿进每个版本命令
  this.inFlight.clear()
}

合并的实现就是一张 inFlight: Map<kind, Promise>：探测进行中，同 kind 的并发调用拿到的是同一个 Promise；探测一落定（finally）就把缓存删掉，所以「再探一次」永远是新一轮，不会读到陈旧结果。dispose 把一个贯穿所有 --version 调用的 AbortSignal 一拉，守护进程关闭时不会有孤儿子进程吊在那里。

6旅程 A：探一个 CLI（probeCli 的内部）

这是引擎的核心动作，reprobe 最终落到这里。走通它，你就知道「装态」「版本」「目录」这三类事实分别是怎么被磁盘上的真实痕迹推导出来的——以及两个 fix commit 各自堵的是哪个洞。

probeCli 自己是个清爽的编排：扫出候选 → 推导装态 → 对 primary 候选跑版本 → 把版本盖回 primary（让单候选和顶层一致）→ 探目录 → 组装快照。它从不 throw：每一处外部接触都被包起来，一个故障变成一个被分类的 status，而不是一次崩溃。

A.1扫 PATH 候选：记下每一个「留了痕」的路径

第一个 fix commit（"stop masking unreadable installs behind a later PATH hit"）改的就是这里。它的尸检报告是这样的：原来用一个共享的 errored 布尔，只要后面任何一个候选成功了，这个布尔就被丢弃——于是一个优先级更高、但读不了的安装被静默掩盖：primary 沉到一个 shell 根本不会去跑的低优先级路径上，故障从结果里彻底蒸发。

现在的写法是：每个在磁盘上留了痕的 PATH 项都留着，按优先级排，各自打 ok 或 errored（带原因）。真正缺席的（stat 返回 null）才丢弃。

for (const path of executableCandidates(entry.command, ports.platform)) {
  try {
    const stat = await ports.files.stat(path)
    if (!stat) continue            // 缺席：正常的「这儿没有」，不算痕迹
    if (stat.isFile && stat.executable) {
      candidates.push({ path, status: 'ok', primary: !hasPrimary })
      hasPrimary = true            // primary = PATH 顺序里第一个 ok，永不落在不可读路径上
    } else {
      // 在场但不是可运行的可执行文件——值得汇报的痕，但绝不是可用安装
      candidates.push({ path, status: 'errored', primary: false,
        error: 'not an executable file' })
    }
  } catch (error) {
    // stat 故障（如权限错误）是探测故障，与缺席分开
    candidates.push({ path, status: 'errored', primary: false, error: errorMessage(error) })
  }
}

配套的 executableCandidates（在 paths.ts）还做了一件去重：PATH 里被列了两次的同一个目录（shell 配置常见的产物）是一个查找位置、不是两个安装，按解析后的路径去重、保留第一次，免得同一个候选被回显两遍。

A.2stat 一个路径：symlink 这一坑，和「悬空链接」的判别

第二个 fix commit（"fix CLI installations missed when on PATH as symlinks"）改的是 nodeFileProber.stat。坑是这样的：claude 和 codex 装在 PATH 上几乎总是一个软链，指向某个带版本号目录里的真实可执行文件（npm / Homebrew 的常规）。原来用 lstat，看到的是链接节点本身（isFile=false），于是一个装好好的 CLI 被报成 not-installed。

改法：用跟随最终软链的 stat，让可执行性检查看到链接目标。但这又带出一个细节——ENOENT 对「真不存在」和「悬空软链」是同一个错误码。于是在 ENOENT 上回落到 lstat 把两者掰开：悬空软链在磁盘上仍然存在，那是个探测故障（一个坏掉的安装），绝不是缺席。

async stat(path) {
  try {
    // 跟随最终软链：PATH 上的 CLI 几乎都是软链进版本化安装，
    // 可执行检查必须看链接目标，不是链接节点本身。
    const stats = await followStat(path)
    return { isFile: stats.isFile(), executable: isExecutable(stats.mode), /* ... */ }
  } catch (error) {
    if (!isMissingPathError(error)) throw error
    // ENOENT 既报「真缺席」也报「悬空软链」。lstat 把它们分开：
    const linkStats = await lstat(path).catch(() => null)
    if (linkStats) throw error    // 链接还在 = 坏安装 = 探测故障，重抛去记账，绝不收成「缺席」
    return null                    // lstat 也没有 = 真缺席
  }
}

A.3三态收口：把候选列表压成一个装态

候选扫完，一个三行函数把它压成 InstallStatus。顺序很关键：有 ok 就是 installed；没有 ok 但有痕迹（全是 errored）就是 errored；一片空白才是干净的 not-installed。

function installStatusFor(candidates: CliCandidate[]): InstallStatus {
  if (candidates.some((c) => c.status === 'ok')) return 'installed'
  return candidates.length > 0 ? 'errored' : 'not-installed'
  // 有痕但没一个能用 → errored；一个痕都没有 → 干净的 not-installed
}

版本探测则把「跑没跑成」也分了类：超时是 timeout、跑了但没解析出版本号是 unparseable、非零退出且无版本是 errored、没安装可探就是 skipped。版本号同时读 stdout 和 stderr——有些 CLI 把版本打到 stderr。

7旅程 B：漂移策略（前端 refresh 一个 provider）

这是全 PR 设计密度最高的一段。用户操作：在 UI 上点「刷新」一个 provider。引擎吐出新鲜事实后，buildDetectionSnapshot 决定这些事实相对于上次意味着什么——而它的全部纪律就一句话：盯着锚点，发现异常就报，永不自动改投。

B.1service 这一跳：探一次、折叠、窄写回

refreshProviderDetection 先取行、确认启用，再调私有的 detectProvider，最后从 detectAll() 里捞出刷新后的可用性返回。detectProvider 是接缝处：它判断这个 kind 能不能用 catalog 探（不能就原样不动），能的话探一次、把上一份快照和新事实喂给 buildDetectionSnapshot，再走一次窄写回。

private async detectProvider(row: AgentProviderRow): Promise<void> {
  const engine = this.discovery
  if (!engine || !isAgentProviderKind(row.kind) || !usesCatalogDetection(row)) return
  const result = await engine.reprobe(row.kind)
  const snapshot = buildDetectionSnapshot(parseDetectionFields(row.agentInfoJson), result)
  // 上一份快照（含锚点）+ 新事实 → 新快照，漂移逻辑全在 buildDetectionSnapshot 里
  await this.repo.updateProviderDetection(row.id, {
    agentInfoJson: JSON.stringify(snapshot),
    capabilitiesUpdatedAt: snapshot.detectedAt,
  })
}

启动那条旅程（startProviderDiscovery → sweepProviderDetection）复用同一个 detectProvider，只是对所有启用 provider 各探一遍。它是故意 fire-and-forget 的：探测故障在引擎里已经降级成事实，绝不该阻塞或拖垮守护进程启动；在 sweep 落定前，detectAll 一直端上次持久化的那份快照。

B.2锚点分流：buildDetectionSnapshot 的五个出口

核心函数读一个变量就分流：anchor = previous.binaryPath——上次记下的「在用安装」路径。没有锚点（第一次探）就采纳引擎的 primary 当锚点。有锚点，就按「锚点还在不在、在不在原位、还能不能用」分五路。

const anchor = previous.binaryPath
if (anchor === undefined) return firstDetection(result, okCandidates)
const primary = okCandidates.find((c) => c.primary)
if (primary && primary.path !== anchor) return anchorDrifted(previous, result, anchor, true)
// ↑ 引擎现在把别的路径排第一了 = 漂移，但下面仍优先确认锚点本身在不在
const anchored = okCandidates.find((c) => c.path === anchor)
if (anchored) return anchorPresent(previous, result, anchor, anchored.version)
const erroredAnchor = result.candidates.find(
  (c) => c.path === anchor && c.status === 'errored')
if (erroredAnchor) return anchorProbeFailed(previous, result, anchor)
return anchorDrifted(previous, result, anchor, okCandidates.length > 0)

五个出口各自给一个 reason：锚点原位还在 → 干净（清 reason）；锚点没了但别处有 → install-path-changed；锚点没了别处也没 → previous-install-missing；锚点路径还在但用不了 → install-probe-failed；已装但 --version 挂了 → version-probe-failed。漂移的两个出口都保住锚点、保留上次的版本号当上下文，并把 installStatus 标成 errored。

function anchorDrifted(previous, result, anchor, hasAlternative): ProviderDetectionSnapshot {
  const snapshot: ProviderDetectionSnapshot = {
    installStatus: 'errored',
    binaryPath: anchor,          // 锚点原样保住，不换成引擎新排第一的那个
    detectedAt: result.probedAt,
    reason: hasAlternative ? 'install-path-changed' : 'previous-install-missing',
  }
  if (previous.version !== undefined) snapshot.version = previous.version
  return snapshot
}

这条策略最反直觉、也最该记住的一点：漂移会在每一次后续探测上反复上报，不是只报一次。把漂移过的快照再喂回去，reason 不会被清掉——除非锚点回到原位、或用户显式改投。一次性的警告等于「换了个马甲的静默改投」，所以这里故意让这个状态一直黏着。

为什么不走直觉做法：一个被悄悄换掉的二进制，正是你最想暴露而不是隐藏的事——它可能是装错、可能是被别的东西占了名字。把异常摆出来让用户决定，比替用户做主安全。

8旅程 C：读可用性（providers.list → detectAll）

读路径刻意保持「纯 DB 读」——它从不触发探测，只把库里那行（含探测写回去的列）映射成可用性。新鲜探测只发生在启动 sweep 和显式 refresh 两处。

detectAll 读启用的行、逐行映射成可用性。映射里有个门控：只有当 catalog 的 PATH 探测确实描述了这行将要启动的那个可执行文件时，才把持久化的探测字段合并进去。版本号则无条件读（它是 provider 自带的诊断数据）。

const base = {
  providerId: row.id, kind: row.kind, transport: row.transport, name: row.name,
  available: row.enabled && Boolean(module),   // available 与「装没装」无关
  ...parseProviderVersion(row.agentInfoJson),
  ...(usesCatalogDetection(row) ? parseDetectionFields(row.agentInfoJson) : {}),
  // ↑ 只有 catalog 探测对得上这行实际会跑的命令，才合并 installStatus 等字段
}

这个门控（usesCatalogDetection）挡掉两种行：一种自定义了 command（指向某个非 catalog 默认的可执行），一种在 env 里覆盖了 PATH。理由是：PATH 决定一个 provider 实际启动哪个 basename 命令，所以一旦行级覆盖了它，守护进程自己 PATH 上的探测就不再权威——在引擎能用 provider 专属 env 去探之前，这些行宁可不合并探测字段，也不给一个可能错的安装信号。

写回则是一次外科手术式的窄更新：只写 agent_info_json + capabilities_updated_at 两列，绝不碰用户编辑过的 command / args / env / secret / config / enabled。因为探测态和用户配置共用同一行 provider 行，一次整行 upsert 会把用户的编辑冲掉。

async updateProviderDetection(id: string, update: ProviderDetectionUpdate): Promise<void> {
  this.db.update(agentProvidersTable)
    .set({
      agentInfoJson: update.agentInfoJson,
      capabilitiesUpdatedAt: update.capabilitiesUpdatedAt,
      updatedAt: Date.now(),          // 只这三列；用户配置字段一个都不写
    })
    .where(eq(agentProvidersTable.id, id)).run()
}

9心智模型补丁

10新词表

11测试与风险地图

测试占了近一半篇幅，且不是凑数——漂移策略的每一条边、两个 fix 的回归、窄写不冲配置，都有用例钉住。下面左栏是「有兜底的」，右栏是「薄冰」。纯事实陈述。

✅ 有兜底的

⚠️ 薄冰

12验收提示（别被这些吓到）

• 有"只写不读"的预留字段，不是漏接线：DirectoryProbe.marker（目录变更指纹）和 directories 整块都被探测、被持久化，但当前没有任何消费者——它们是给 PR 描述里点名 deferred 的 fs-watch 新鲜度铺路的，不是忘了接。
• catalog 把版本参数写成 versionArgs 数组、目录位置写成声明式数据，看着像过度设计；这是为同样 deferred 的「写」功能（写可执行路径 / provider 原生配置）让同一份声明能复用，刻意不写成闭包。
• packages/api 那几个文件几乎全是照抄：AgentAvailabilityDto 手抄 daemon 的 AgentAvailability、installStatus 联合类型手写而非导入——这是跨仓边界（api 要对外自洽、不依赖 daemon 内部类型）的常规，不是重复代码失误。
• acp provider 永远没有 installStatus：它不在 CLI_CATALOG 里，usesCatalogDetection 直接把它挡在外面，可用性里只有版本（若有）。这是预期，不是探测漏了它。
• 第一个 commit 标题带 "(#86)"：那是早先已合并的「wire CLI presence detection」PR，本分支在其基础上把探测引擎补全。不是本 PR 自指。
• 没有数据库迁移：探测态复用既有的 agentInfoJson / capabilitiesUpdatedAt 两列，没动 schema——所以你在 diff 里找不到 migration 文件是正常的。

13覆盖声明

本报告基于对分支 6fc7e10...cc84312（4 commits、39 文件、+2335/−30）的全量精读。所有引用的代码片段均由作者亲自 Read 对应文件后裁剪，未引用任何二手转述。

• 逐文件精读（src）：discovery/ 全部 9 个源文件（types/catalog/ports/paths/version/probe/engine/testing/index）+ provider-detection.ts + agent/types.ts；以及 registry.ts / service.ts / repository.ts / drizzle-repository.ts / index.ts / trpc/services.ts 的完整 diff。
• API 面：dto.ts / trpc.ts / services.ts / check-boundaries.mjs 的完整 diff。
• 测试：全文读了 provider-detection.test 与 agent-provider-discovery.test；其余 7 个测试套件按 describe/it 标题与关键断言提取行为，未逐行复述。
• 两个 fix commit 的 message + stat 单独审阅，作为旅程 A「原来错在哪」的依据。
• 未独立验证：未在本机运行测试或构建（PR 描述称 bun run verify 本地通过、1233 passed / 20 skipped）；薄冰区的「无测试」均指未见到对应用例，非断言其必然有 bug。

figuretu/eyrie · feat/agent-discovery（PR #89）· 4 commits · +2335/−30 · 本报告为一次性理解辅助，不维护、不作为真相源。