@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/src/execution/engine/engine-discovery-scan.ts

@@ -0,0 +1,269 @@
+// src/execution/engine/engine-discovery-scan.ts
+//
+// [W4] 引擎发现器：manifest 解析 + 三级搜索路径 + cli descriptor 装载。
+// 设计权威源：docs/design/subagent-engine-protocolization.md §3.4 发现与注册；
+// 实现级规格 impl-plan §2.4。
+//
+// 自注册模型（G1「新引擎零改 core」）：引擎包在自己的 package.json 里声明
+// `xyz-agent.subagentEngine` manifest，发现器扫描三级搜索路径命中即解析 manifest、
+// 装配 cli descriptor（portFactory = W2 EngineClient + RemoteEngine）并经
+// registerEngineDescriptor 装载进注册表——core 与本文件都不枚举引擎。
+//
+// 三级路径：
+//   L1 宿主发现根 = env `XYZ_AGENT_ENGINE_ROOTS`（path.delimiter 分隔）+
+//     HostServices.discoveryRoots().engines（宿主模块域，pi 壳在 pi-host.ts 提供）；
+//   L2 node 解析 = 宿主进程模块解析域的 node_modules（require.resolve 候选目录链的
+//     扫描化，见 deriveNodeModuleRoots）；打包态与 zsw vendor 态自然为空（规格明确
+//     这两态 L2 无效）；
+//   L3 显式配置 = <agentDir>/subagents/config.json 的 engines{} 段（config.ts），
+//     最后装载 = 用户/开发态覆盖（A12⑤ enabled:false 不进清单）。
+//
+// 发现时机（§3.4）：session_start 扫描一次 + 装载（装载结果即缓存——registry
+// descriptors）；hasEngine() 未命中走 ensureEngineDiscovered 同步补扫（只读 manifest
+// 不握手——portFactory 惰性，扫描绝不 spawn 引擎进程）。引擎清单投影（engines.json）
+// 归 engine-discovery.ts syncEnginesFile。
+//
+// 冲突与失败（A12）：manifest 缺必需字段/不可解析 → warn 跳过该包（不阻断其他引擎）；
+// 同 id 覆盖 → debug 留痕（core logger 三值无 info 级，debug 落宿主文件日志）；bin
+// 不存在/不可执行 → 标记不可用（不装载、不进清单）；protocol 不兼容 → 同不可用。
+
+import * as path from "node:path";
+
+import { CONSERVATIVE_CAPABILITIES } from "./engine-manifest.ts";
+import {
+  canExecute,
+  inspectEnginePackage,
+  type DiscoveredEngine,
+} from "./engine-inspect-package.ts";
+
+import { getLogger } from "../../core/logger.ts";
+import {
+  ENGINE_ROOTS_ENV,
+  deriveNodeModuleRoots,
+  parseEngineRootsEnv,
+  scanEngineRoot,
+} from "./engine-discovery-roots.ts";
+import { getHostServices, type DiscoveryRoot } from "../../core/host-services.ts";
+import { getEngineDataDir } from "./common/data-dir.ts";
+import { readExplicitEngines } from "./config.ts";
+import { EngineClient } from "./client/engine-client.ts";
+import { RemoteEngine } from "./client/remote-engine.ts";
+import { hasEngine, registerEngineDescriptor, type CliEngineDescriptor } from "./registry.ts";
+import { getHostUiRequestEndpoint } from "./host/host-ui-endpoint.ts";
+import type { EngineCapabilities } from "./types.ts";
+
+const logger = getLogger("subagents");
+
+export { ENGINE_ROOTS_ENV, parseEngineRootsEnv, deriveNodeModuleRoots };
+export { inspectEnginePackage };
+export type { DiscoveredEngine, PackageInspection } from "./engine-inspect-package.ts";
+
+/** 扫描结果（诊断面：skip/unusable 逐包留痕原因，对应 A12 负面场景）。 */
+export interface DiscoveryScanResult {
+  discovered: DiscoveredEngine[];
+  skipped: Array<{ pkgDir: string; reason: string }>;
+  unusable: Array<{ pkgDir: string; id: string | undefined; reason: string }>;
+}
+
+export interface DiscoverEnginesOptions {
+  /** 宿主种类（EngineClient pidfile 实例维度命名段：pi 壳 'pi'、runtime 'runtime'）。 */
+  hostKind: string;
+  /** L3 显式配置目录（<dir>/subagents/config.json 的 engines 段）。缺省 = 无 L3。 */
+  agentDir?: string;
+  /** 引擎数据根（EngineClient dataDir；缺省 portFactory 执行期 getEngineDataDir 解析）。 */
+  dataDir?: string;
+  /** env 覆盖（L1 根读取；缺省 process.env——测试注入隔离宿主 env）。 */
+  env?: NodeJS.ProcessEnv;
+  /** L2 覆盖（测试注入；缺省 = 宿主入口上溯 node_modules 链）。 */
+  nodeModuleRoots?: string[];
+  /** 附加发现根（调用方/测试追加的 L1 根，语义同 HostServices.engines）。 */
+  extraRoots?: DiscoveryRoot[];
+}
+
+// ============================================================
+// 扫描与装载
+// ============================================================
+
+/** 纯扫描（不装载注册表）。装载序 = L1 env → L1 宿主/附加根 → L2 → L3（后者覆盖前者）。 */
+export function scanEngines(opts: DiscoverEnginesOptions): DiscoveryScanResult {
+  const env = opts.env ?? process.env;
+  const result: DiscoveryScanResult = { discovered: [], skipped: [], unusable: [] };
+  const present = (entry: DiscoveredEngine): void => {
+    const idx = result.discovered.findIndex((d) => d.id === entry.id);
+    if (idx >= 0) {
+      logger.debug(
+        `[engine-discovery] engine id '${entry.id}' from '${entry.source}' overrides earlier ` +
+          `discovery from '${result.discovered[idx].source}' — same-id override`,
+      );
+      result.discovered[idx] = entry;
+      return;
+    }
+    result.discovered.push(entry);
+  };
+
+  const visitManifestPackage = (pkgDir: string, source: string): void => {
+    const inspection = inspectEnginePackage(pkgDir, source, opts.hostKind, env);
+    if (inspection.status === "skip") {
+      // 非引擎包（无 manifest 段）的静默 skip 不留痕——扫描常态；其余 skip warn。
+      if (!inspection.reason.includes("not an engine package")) {
+        logger.warn(`[engine-discovery] skipping ${pkgDir} (${source}): ${inspection.reason}`);
+        result.skipped.push({ pkgDir, reason: inspection.reason });
+      }
+      return;
+    }
+    if (inspection.status === "unusable") {
+      logger.warn(`[engine-discovery] engine unavailable: ${inspection.reason}`);
+      result.unusable.push({ pkgDir, id: inspection.id, reason: inspection.reason });
+      return;
+    }
+    present(inspection.entry);
+  };
+
+  // L1：env 宿主发现根（打包态主通道，W9 注入）
+  for (const dir of parseEngineRootsEnv(env)) {
+    scanEngineRoot(dir, (pkgDir) => visitManifestPackage(pkgDir, ENGINE_ROOTS_ENV));
+  }
+  // L1：宿主发现根第二通道（HostServices.engines）+ 调用方附加根
+  const hostRoots = [
+    ...(getHostServices().discoveryRoots?.().engines ?? []),
+    ...(opts.extraRoots ?? []),
+  ];
+  for (const root of hostRoots) {
+    scanEngineRoot(root.dir, (pkgDir) => visitManifestPackage(pkgDir, root.source));
+  }
+  // L2：宿主 node_modules（node 解析域；opts.nodeModuleRoots 测试覆盖）
+  const nodeRoots = opts.nodeModuleRoots ?? deriveNodeModuleRoots();
+  for (const dir of nodeRoots) {
+    scanEngineRoot(dir, (pkgDir) => visitManifestPackage(pkgDir, "node-modules"));
+  }
+  // L3：显式配置（最后装载 = 用户/开发态覆盖）
+  if (opts.agentDir !== undefined) {
+    for (const [id, entry] of Object.entries(readExplicitEngines(opts.agentDir))) {
+      const command = resolveExplicitCommand(entry.command, env);
+      if (command === undefined) {
+        const reason =
+          `engine '${id}' (config.json engines.${id}): command '${entry.command}' not found or not executable`;
+        logger.warn(`[engine-discovery] ${reason} — not registering`);
+        result.unusable.push({ pkgDir: `config.json engines.${id}`, id, reason });
+        continue;
+      }
+      present(buildExplicitDescriptor(id, command, entry, opts));
+    }
+  }
+  return result;
+}
+
+/**
+ * 历史发现装载的引擎 id 集（模块级；供 syncEnginesFile 投影时从注册表快照剔除
+ * 历史装载——投影逻辑与装载逻辑同 bundle 闭包，无跨模块实例副本问题）。
+ */
+const loadedDiscoveryIdSet = new Set<string>();
+
+/**
+ * 扫描 + 装载：descriptor 经 registerEngineDescriptor 进注册表（幂等覆盖——重复扫描
+ * 安全）。装载覆盖既有注册（含过渡期 inproc pi/zcode——auto 模式下 cli descriptor
+ * 胜出即设计 D3 语义）时 debug 留痕。
+ */
+export function discoverAndRegisterEngines(opts: DiscoverEnginesOptions): DiscoveryScanResult {
+  const result = scanEngines(opts);
+  for (const entry of result.discovered) {
+    const existed = hasEngine(entry.id);
+    registerEngineDescriptor(entry.id, entry.descriptor);
+    loadedDiscoveryIdSet.add(entry.id);
+    if (existed) {
+      logger.debug(
+        `[engine-discovery] engine '${entry.id}' descriptor overwritten in registry ` +
+          `(source '${entry.source}') — same-id override`,
+      );
+    }
+  }
+  return result;
+}
+
+/**
+ * 历史发现装载的引擎 id 快照（投影源计算消费面，见 engine-discovery.ts）。
+ */
+export function loadedDiscoveryIds(): string[] {
+  return [...loadedDiscoveryIdSet];
+}
+
+/**
+ * hasEngine 的补扫面（§3.4 发现时机：快照未命中触发一次同步补扫，只读 manifest
+ * 不握手）。消费方 = agent 解析期/路由期的存在性校验接线（宿主侧注入 hasEngineFn
+ * 时用本函数替代裸 hasEngine）——「装了包 → 下次解析即可用」。
+ */
+export function ensureEngineDiscovered(id: string, opts: DiscoverEnginesOptions): boolean {
+  if (hasEngine(id)) return true;
+  discoverAndRegisterEngines(opts);
+  return hasEngine(id);
+}
+
+/** L3 显式命令解析：含路径分隔符 → 按路径验证；裸命令名 → PATH 查找。失败 = 不可用。 */
+function resolveExplicitCommand(command: string, env: NodeJS.ProcessEnv): string | undefined {
+  if (command.includes("/") || command.includes("\\")) {
+    const p = path.isAbsolute(command) ? command : path.resolve(command);
+    return canExecute(p) ? p : undefined;
+  }
+  const pathVar = env["PATH"] ?? env["Path"] ?? "";
+  for (const dir of pathVar.split(path.delimiter)) {
+    if (dir === "") continue;
+    const p = path.join(dir, command);
+    if (canExecute(p)) return p;
+  }
+  return undefined;
+}
+
+/**
+ * L3 显式配置的 descriptor：无 manifest 面（用户手工配置 command）→ capabilities 取
+ * 全保守值 + warn（gate 同步拦生成，运行期不踩未声明能力）；无 modelCatalog / 无
+ * displayName（= id）。engineConfig 经 initialize.engineConfig 透传。
+ */
+function buildExplicitDescriptor(
+  id: string,
+  command: string,
+  entry: { args: string[]; config?: Record<string, string>; cwd?: string },
+  opts: DiscoverEnginesOptions,
+): DiscoveredEngine {
+  const env = opts.env ?? process.env;
+  logger.debug(
+    `[engine-discovery] engine '${id}' registered from config.json engines section with conservative capabilities (no manifest)`,
+  );
+  const caps: EngineCapabilities = { ...CONSERVATIVE_CAPABILITIES };
+  const descriptor: CliEngineDescriptor = {
+    kind: "cli",
+    command,
+    args: entry.args,
+    capabilities: caps,
+    portFactory: () => {
+      // 惰性求值理由同 manifest descriptor portFactory（扫描期早于 configureCore）。
+      const dataDir = opts.dataDir ?? getEngineDataDir(env);
+      const client = new EngineClient({
+        engineId: id,
+        command,
+        args: entry.args,
+        ...(entry.cwd !== undefined ? { cwd: entry.cwd } : {}),
+        hostKind: opts.hostKind,
+        dataDir,
+        envPrefixes: [],
+        // [W6 R3 MF-A] 同上：host/askUser 应答端经壳侧登记处接线。
+        uiRequestHandler: getHostUiRequestEndpoint(),
+        ...(entry.config !== undefined ? { engineConfig: entry.config } : {}),
+        manifestDiagnostics: { capabilities: caps, models: null },
+      });
+      return new RemoteEngine({
+        engineId: id,
+        client,
+        manifest: { capabilities: caps },
+        dataDir,
+        hostKind: opts.hostKind,
+        ...(entry.config !== undefined ? { engineConfig: entry.config } : {}),
+      });
+    },
+  };
+  return {
+    id,
+    source: "config.json",
+    ...(entry.config !== undefined ? { engineConfig: entry.config } : {}),
+    descriptor,
+  };
+}

package/src/execution/engine/engine-discovery.ts

@@ -1,13 +1,19 @@
 // src/execution/engine/engine-discovery.ts
 //
-// [U7] 引擎列表状态文件同步（registry → <agentDir>/subagents/engines.json）。
+// [U7 → W4] 引擎列表状态文件同步（→ <agentDir>/subagents/engines.json）。
 //
 // 为什么落文件而不是 session entry：Settings 引擎选择器在无活跃 session 时也要可开
 // （冷启动/全局设置），session entry 绑定会话生命周期兜不住；engines.json 是进程外
 // 可读的全局状态，extension（pi 进程）为唯一写入者，runtime RPC 读——数据所有权清晰。
 //
-// 动态性（用户要求）：清单来自代码注册表（registerEngine 调用点），未来新增引擎
-// （AcpEngine 等）零改动出现在 GUI——本文件与前端都不枚举引擎。
+// 动态性（W4 协议化）：清单来自「三级发现的装载结果 ∪ 代码注册表」——发现器
+// （engine-discovery-scan.ts）在同步前扫描（L1 env 根 / HostServices.engines /
+// L2 node 解析 / L3 config.json），把引擎包 manifest 自注册的 cli descriptor 装载进
+// 注册表；inproc 过渡注册（组合根 registerXxxEngine）与发现装载合流构成本次投影。
+// 新引擎 = 装一个包（W5/W7 后），本文件与前端都不枚举引擎。
+//
+// 投影契约（设计 §3.4 投影面表）：清单 = 已发现且可执行的 id 数组；契约
+// {v:1, engines: string[]} 不改（A11 宿主表面不变量）。
 
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -15,6 +21,7 @@ import * as path from "node:path";
 import { SUBAGENTS_ENGINES_FILENAME, type SubagentEnginesFile } from "@xyz-agent/extension-protocol";
 
 import { listEngines } from "./registry.ts";
+import { discoverAndRegisterEngines, loadedDiscoveryIds } from "./engine-discovery-scan.ts";
 import { writeAtomicFileSync } from "../../shared/atomic-write.ts";
 
 /** engines.json 落盘缩进（与 subagent-core 其他 JSON store 的 JSON_INDENT 约定一致）。 */
@@ -26,17 +33,33 @@ export function getEnginesFilePath(agentDir: string): string {
 }
 
 /**
- * 把注册表引擎列表同步到 engines.json（session_start 时调用）。
+ * 三级发现装载 + 把引擎清单同步到 engines.json（session_start 时调用）。
+ *
+ * 发现时机（W4 §2.4）：与 syncEnginesFile 同点——扩展组合根的模块加载点与
+ * session_start 兜底点即本函数既有调用点（调用方零改动），扫描一次 + 装载进注册表
+ * （装载结果即缓存）；只读 manifest 不握手（portFactory 惰性，扫描不 spawn 引擎）。
+ *
+ * 投影源（§3.4 投影面表「清单 = 已发现且可执行」）= 本次发现装载结果 ∪ inproc 过渡
+ * 注册快照（listEngines() 剔除历史发现装载的 id——registry 无撤销 API，引擎包卸载
+ * 后已装载 descriptor 会滞留，投影时经 loadedDiscoveryIds 排除即「卸载 → 下次扫描
+ * 自动消失」清理通道；A4 新引擎装包零改 core 出现在清单）。W11 删 inproc 后清单 =
+ * 纯发现结果（零命中 → 空清单，GUI 按既有语义给 engine_not_found + 安装指引）。
  *
  * 幂等：内容与现文件一致时零写入（mtime 不动——读侧无谓失效）；写入走 tmp+rename
  * 原子替换（shared/atomic-write 统一原语，U6b 迁移——与池 config 同防线）。
- * fail-safe：任何 IO 异常吞掉（可发现性降级不阻塞
- * session 启动——GUI 兜底显示 ['pi']）。
+ * fail-safe：发现与 IO 异常都吞掉（可发现性降级不阻塞 session 启动——GUI 兜底显示
+ * 既有清单）。
  */
 export function syncEnginesFile(agentDir: string): void {
   try {
+    // inproc 过渡注册快照：注册表全集剔除历史发现装载的 id（清理通道语义，见头注释）
+    const loadedIds = new Set(loadedDiscoveryIds());
+    const inprocSnapshot = listEngines().filter((id) => !loadedIds.has(id));
+    // [W4] 三级发现装载（fail-safe 内——扫描失败不阻塞投影与 session 启动）。
+    const scan = discoverAndRegisterEngines({ hostKind: "pi", agentDir });
     const filePath = getEnginesFilePath(agentDir);
-    const payload: SubagentEnginesFile = { v: 1, engines: listEngines(), updatedAt: Date.now() };
+    const engines = [...new Set([...inprocSnapshot, ...scan.discovered.map((e) => e.id)])];
+    const payload: SubagentEnginesFile = { v: 1, engines, updatedAt: Date.now() };
     const serialized = JSON.stringify(payload, null, JSON_INDENT);
     try {
       const existing = fs.readFileSync(filePath, "utf8");

package/src/execution/engine/engine-inspect-package.ts

@@ -0,0 +1,282 @@
+// src/execution/engine/engine-inspect-package.ts
+//
+// [W4] 单引擎包检查管线（engine-discovery-scan.ts 拆出——max-lines 纪律 + 职责域
+// 独立）：读 package.json → manifest 字段级解析 → bin 可执行验证 → cli descriptor
+// 装配。纯「候选包目录 → 三态检查产物」，无搜索路径/装载状态（留在 discovery-scan）。
+// 设计权威源：docs/design/subagent-engine-protocolization.md §3.4 + impl-plan §2.4。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { isProtocolVersionCompatible, type ModelCatalogEntry } from "@zhushanwen/subagent-engine-sdk";
+
+import {
+  describeValue,
+  parseCapabilities,
+  parseEnvPrefixes,
+  parseModelCatalog,
+  resolveManifestBin,
+} from "./engine-manifest.ts";
+
+import { getLogger } from "../../core/logger.ts";
+import { getEngineDataDir } from "./common/data-dir.ts";
+import { EngineClient } from "./client/engine-client.ts";
+import { RemoteEngine, type RemoteEngineManifestSnapshot } from "./client/remote-engine.ts";
+import type { CliEngineDescriptor } from "./registry.ts";
+import { getHostUiRequestEndpoint } from "./host/host-ui-endpoint.ts";
+import type { EngineCapabilities } from "./types.ts";
+
+const logger = getLogger("subagents");
+
+/** 单个引擎包的检查产物。 */
+export type PackageInspection =
+  | { status: "ok"; entry: DiscoveredEngine }
+  | { status: "skip"; reason: string }
+  | { status: "unusable"; id: string | undefined; reason: string };
+
+/** 发现成功的引擎条目（装载序；同 id 后者覆盖前者）。 */
+export interface DiscoveredEngine {
+  id: string;
+  /** 发现源标签（env 名 / 宿主根 source / node-modules / config.json）。 */
+  source: string;
+  /** L3 显式 config（initialize.engineConfig 透传；L1/L2 manifest 发现无此项）。 */
+  engineConfig?: Record<string, string>;
+  descriptor: CliEngineDescriptor;
+}
+
+/** 检查管线中间步的失败产物（skip/unusable；ok 只由主管线终点产出）。 */
+type ManifestInspectionFailure = Extract<PackageInspection, { status: "skip" | "unusable" }>;
+
+/** 读 + JSON 解析 package.json（不可读/坏 JSON/非对象 → skip）。 */
+function readEnginePackageJson(pkgDir: string): { pkg: Record<string, unknown> } | ManifestInspectionFailure {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(path.join(pkgDir, "package.json"), "utf8");
+  } catch (err) {
+    return { status: "skip", reason: `package.json unreadable: ${errorMessage(err)}` };
+  }
+  let pkg: unknown;
+  try {
+    pkg = JSON.parse(raw);
+  } catch (err) {
+    return { status: "skip", reason: `package.json is not valid JSON: ${errorMessage(err)}` };
+  }
+  if (typeof pkg !== "object" || pkg === null) {
+    return { status: "skip", reason: "package.json is not an object" };
+  }
+  return { pkg: pkg as Record<string, unknown> };
+}
+
+/** xyz-agent.subagentEngine manifest 段提取（无段/形态坏 → 各自的 skip reason）。 */
+function extractEngineManifest(pkg: Record<string, unknown>): { manifest: Record<string, unknown> } | { skipReason: string } {
+  // 无 manifest 段 = 不是引擎包：扫描常态（node_modules 大量无关包），静默跳过不 warn。
+  const agentNs = pkg["xyz-agent"];
+  if (typeof agentNs !== "object" || agentNs === null) {
+    return { skipReason: "no xyz-agent.subagentEngine manifest (not an engine package)" };
+  }
+  const manifest = (agentNs as Record<string, unknown>)["subagentEngine"];
+  if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+    return { skipReason: "xyz-agent.subagentEngine is not an object" };
+  }
+  return { manifest: manifest as Record<string, unknown> };
+}
+
+// ── 必需字段：id / bin / protocol（缺失或形态坏 → warn 跳过该包）──
+function validateRequiredManifestFields(
+  m: Record<string, unknown>,
+): { id: string; manifestBin: string; protocol: number } | ManifestInspectionFailure {
+  const id = m["id"];
+  if (typeof id !== "string" || id.trim() === "") {
+    return { status: "skip", reason: "manifest id is required (non-empty string)" };
+  }
+  const manifestBin = m["bin"];
+  if (typeof manifestBin !== "string" || manifestBin.trim() === "") {
+    return { status: "skip", reason: `engine '${id}': manifest bin is required (non-empty string)` };
+  }
+  const protocol = m["protocol"];
+  if (typeof protocol !== "number" || !Number.isInteger(protocol)) {
+    return {
+      status: "skip",
+      reason: `engine '${id}': manifest protocol is required (integer; got ${describeValue(protocol)})`,
+    };
+  }
+  if (!isProtocolVersionCompatible(protocol)) {
+    return {
+      status: "unusable",
+      id,
+      reason:
+        `engine '${id}': manifest protocol ${protocol} is not compatible ` +
+        `(core supports >=1 <2) — upgrade the engine package or the host core`,
+    };
+  }
+  return { id, manifestBin, protocol };
+}
+
+/**
+ * bin 解析 + 可执行验证：manifest bin = package.json npm bin 的 key（设计 §3.4 示例
+ * 形态）；package.json bin 为字符串时直接作相对路径。解析不出真实入口 = bin 缺失面。
+ */
+function resolveVerifiedEngineBin(
+  pkgDir: string,
+  pkg: Record<string, unknown>,
+  manifestBin: string,
+  id: string,
+): { binPath: string } | ManifestInspectionFailure {
+  const binPath = resolveManifestBin(pkgDir, pkg, manifestBin);
+  if (binPath === undefined) {
+    return {
+      status: "skip",
+      reason: `engine '${id}': manifest bin '${manifestBin}' does not resolve via package.json bin`,
+    };
+  }
+  if (!canExecute(binPath)) {
+    return {
+      status: "unusable",
+      id,
+      reason: `engine '${id}': bin not found or not executable: ${binPath}`,
+    };
+  }
+  return { binPath };
+}
+
+/**
+ * displayName / description（可选；displayName 缺省 = id 由消费面兜底
+ * （listEnginesByDisplayName 的 `?? id`），快照只存显式值防「缺省填充」被误读；
+ * description 当前无消费面，仅做形态校验）。
+ */
+function parseOptionalDisplayFields(m: Record<string, unknown>, id: string): string | undefined {
+  let displayName: string | undefined;
+  const rawDisplayName = m["displayName"];
+  if (rawDisplayName !== undefined) {
+    if (typeof rawDisplayName === "string" && rawDisplayName.trim() !== "") {
+      displayName = rawDisplayName;
+    } else {
+      logger.warn(`[engine-discovery] engine '${id}': displayName must be a non-empty string — ignoring`);
+    }
+  }
+  const rawDescription = m["description"];
+  if (rawDescription !== undefined && typeof rawDescription !== "string") {
+    logger.warn(`[engine-discovery] engine '${id}': description must be a string — ignoring`);
+  }
+  return displayName;
+}
+
+/** cli descriptor 装配（portFactory 惰性求值：EngineClient + RemoteEngine）。 */
+function buildManifestCliDescriptor(params: {
+  id: string;
+  binPath: string;
+  hostKind: string;
+  env: NodeJS.ProcessEnv;
+  caps: EngineCapabilities;
+  envPrefixes: string[];
+  modelCatalog: { dynamic: boolean; models: ModelCatalogEntry[] } | null | undefined;
+  displayName: string | undefined;
+  manifestSnapshot: RemoteEngineManifestSnapshot;
+}): CliEngineDescriptor {
+  const { id, binPath, hostKind, env, caps, envPrefixes, modelCatalog, displayName, manifestSnapshot } = params;
+  return {
+    kind: "cli",
+    command: binPath,
+    args: [],
+    capabilities: caps,
+    portFactory: () => {
+      // 惰性求值：portFactory 在 getEngine 首次取用时才执行（registry 惰性单例），
+      // 那时宿主已 configureCore（或宿主进程 env 已带数据根）——扫描期可能早于
+      // configureCore，直接调 getEngineDataDir 会触 core_host_not_configured。
+      const dataDir = getEngineDataDir(env);
+      const client = new EngineClient({
+        engineId: id,
+        command: binPath,
+        args: [],
+        hostKind,
+        dataDir,
+        envPrefixes,
+        // [W6 R3 MF-A] host/askUser 应答端：壳侧登记处在 portFactory 惰性执行期取值
+        //（晚于 session_start 注册，未注册 → undefined → 引擎收 {unsupported:true}）。
+        uiRequestHandler: getHostUiRequestEndpoint(),
+        manifestDiagnostics: {
+          capabilities: caps,
+          models: modelCatalog === undefined || modelCatalog === null ? null : modelCatalog.models,
+        },
+      });
+      return new RemoteEngine({
+        engineId: id,
+        client,
+        manifest: manifestSnapshot,
+        dataDir,
+        hostKind,
+      });
+    },
+    manifest: {
+      ...(modelCatalog !== undefined ? { modelCatalog } : {}),
+      ...(displayName !== undefined ? { displayName } : {}),
+    },
+  };
+}
+
+/**
+ * 检查单个候选包目录（读 package.json → manifest 字段级解析 → bin 可执行验证）。
+ * 三态：ok（装载）/ skip（必需字段缺失/不可解析——warn 跳过该包）/ unusable
+ * （protocol 不兼容、bin 不可执行——标记不可用，不进清单）。
+ */
+export function inspectEnginePackage(
+  pkgDir: string,
+  source: string,
+  hostKind: string,
+  env: NodeJS.ProcessEnv,
+): PackageInspection {
+  const pkgStep = readEnginePackageJson(pkgDir);
+  if (!("pkg" in pkgStep)) return pkgStep;
+  const manifestStep = extractEngineManifest(pkgStep.pkg);
+  if (!("manifest" in manifestStep)) return { status: "skip", reason: manifestStep.skipReason };
+  const m = manifestStep.manifest;
+  const fields = validateRequiredManifestFields(m);
+  if ("reason" in fields) return fields;
+  const { id, manifestBin } = fields;
+  const binStep = resolveVerifiedEngineBin(pkgDir, pkgStep.pkg, manifestBin, id);
+  if (!("binPath" in binStep)) return binStep;
+
+  // ── capabilities（必需；缺键取最保守值 + warn；未知键忽略 + warn）──
+  const caps = parseCapabilities(id, m["capabilities"]);
+
+  // ── envPrefixes（可选，缺省 []；非法条目丢弃该前缀 + warn，包仍可用——A12②）──
+  const envPrefixes = parseEnvPrefixes(id, m["envPrefixes"]);
+
+  // ── modelCatalog（可选；缺省 = 不注入保持 undefined——解析器不得把省略填成
+  //    models: []，否则「无枚举面」语义不可达，RemoteEngine.listModels 会说谎）──
+  const modelCatalog = parseModelCatalog(id, m["modelCatalog"]);
+
+  const displayName = parseOptionalDisplayFields(m, id);
+
+  const manifestSnapshot: RemoteEngineManifestSnapshot = {
+    capabilities: caps,
+    ...(modelCatalog !== undefined ? { modelCatalog } : {}),
+  };
+
+  const descriptor = buildManifestCliDescriptor({
+    id,
+    binPath: binStep.binPath,
+    hostKind,
+    env,
+    caps,
+    envPrefixes,
+    modelCatalog,
+    displayName,
+    manifestSnapshot,
+  });
+  return { status: "ok", entry: { id, source, descriptor } };
+}
+
+/** 可执行探测（X_OK；ENOENT/EACCES/平台不支持 → false）。 */
+export function canExecute(p: string): boolean {
+  try {
+    fs.accessSync(p, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}