@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/execution/engine/engines/zcode/preparer.ts

@@ -1,363 +0,0 @@
-// src/execution/engine/engines/zcode/preparer.ts
-//
-// ZcodeEngine preparer（P3）：spawn 前唯一副作用模块（设计 §3.3.7）——隔离 HOME 池化
-// + 池内 config.json 引导（凭据 + model.main）。TS 重写自 zsub 的
-// bootstrapIsolatedHome / model-router.js（真机验证过的机制），差异点：
-//   - **凭据源 = v2 config 单源（2026-08-25 用户拍板）**：只读 `~/.zcode/v2/config.json`
-//     （ZCode 桌面登录态落点，GUI 管理面）。曾泛化过「v2 + cli config 双源合并」，
-//     但 `~/.zcode/cli/config.json` 不在 GUI 管理面、可能残留历史验证配置
-//     （8/24 zsub 开发残留把默认模型劫持到失效 router 端点的 401 事故），撤掉依赖；
-//   - 池目录必须经 resolvePoolDir（paths.ts SSOT，禁自拼——池布局要与 journal/refs
-//     共享同一形状，设计 §3.3.9）；
-//   - 凭据缺失/模型不可解析抛结构化 ZcodePrepareError（错误码对齐设计 §3.3.3：
-//     engine_credential_missing / model_not_available），一律先于进程创建。
-//
-// 为什么池按 provider+model 隔离（与设计 §3.3.9「agent 名池」不同）：并发 run 指向
-// 同一 HOME 但模型不同时，config.json 的 model.main 会出现「后写覆盖先写」的串池——
-// zsub 的 per-model HOME 池正是防这个；本引擎以 provider+model 为隔离粒度，agent 维度
-// 的池化留给宿主 refs.json（W3 对齐点）。
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import { resolvePoolDir } from "../../paths.ts";
-import {
-  ZCODE_FALLBACK_DEFAULT_MODEL,
-  ZCODE_POOL_CONFIG_SUFFIX,
-  ZCODE_V2_CONFIG_PATH_SUFFIX,
-} from "./constants.ts";
-
-// ============================================================
-// 结构化错误（prepare 期——进程创建前 reject 的载体）
-// ============================================================
-
-export type ZcodePrepareErrorCode =
-  | "engine_credential_missing"
-  | "model_not_available"
-  | "engine_capability_unsupported";
-
-/** prepare 期错误：code 对齐设计 §3.3.3 错误规格表，message 自带恢复指引。 */
-export class ZcodePrepareError extends Error {
-  readonly code: ZcodePrepareErrorCode;
-
-  constructor(code: ZcodePrepareErrorCode, message: string) {
-    super(`[${code}] ${message}`);
-    this.name = "ZcodePrepareError";
-    this.code = code;
-  }
-}
-
-// ============================================================
-// 源 config 读取（运行时 guard，禁 any）
-// ============================================================
-
-/** provider 注册表条目的最小消费面（凭据 + 模型清单校验）。 */
-export interface ZcodeProviderEntry {
-  options?: { apiKey?: unknown };
-  models?: Record<string, unknown>;
-  [k: string]: unknown;
-}
-
-interface SourceConfig {
-  /** provider 注册表（来自 v2 config，逐条运行时 guard）。 */
-  providers: Map<string, ZcodeProviderEntry>;
-  /** 源文件 mtime（池 config 免重写的比对基准；不可读 = 0）。 */
-  mtimeMs: number;
-}
-
-/** unknown 的 Record 窄化 guard（替代 as 全可选断言——taste/no-unsafe-cast）。 */
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
-/** provider 条目一律按 ZcodeProviderEntry 消费（索引签名形态，无需逐键校验）。 */
-function isProviderEntry(v: unknown): v is ZcodeProviderEntry {
-  return isRecord(v);
-}
-
-function readSourceConfig(absPath: string): SourceConfig {
-  const empty: SourceConfig = { providers: new Map(), mtimeMs: 0 };
-  let raw: string;
-  try {
-    raw = fs.readFileSync(absPath, "utf8");
-  } catch {
-    return empty;
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return empty;
-  }
-  if (!isRecord(parsed)) return empty;
-  const conf: SourceConfig = { providers: new Map(), mtimeMs: 0 };
-  const provider = parsed["provider"];
-  if (isRecord(provider)) {
-    for (const [id, entry] of Object.entries(provider)) {
-      if (isProviderEntry(entry)) conf.providers.set(id, entry);
-    }
-  }
-  try {
-    conf.mtimeMs = fs.statSync(absPath).mtimeMs;
-  } catch {
-    // 源被并发删除等场景：mtime 取 0（比对恒不触发重写，池内完好配置继续用）
-    conf.mtimeMs = 0;
-  }
-  return conf;
-}
-
-// ============================================================
-// 模型解析（v2 单源，zsub resolve 同构）
-// ============================================================
-
-function modelShort(ref: string): string {
-  return ref.slice(ref.lastIndexOf("/") + 1);
-}
-
-function providerOf(ref: string): string {
-  return ref.slice(0, ref.lastIndexOf("/"));
-}
-
-function hasApiKey(entry: ZcodeProviderEntry): boolean {
-  const key = entry.options?.apiKey;
-  return typeof key === "string" && key !== "";
-}
-
-export interface ZcodeSourcePaths {
-  /** 桌面登录态 config（唯一凭据源）。缺省 ~/.zcode/v2/config.json。 */
-  v2ConfigPath?: string;
-}
-
-function defaultV2ConfigPath(): string {
-  return path.join(os.homedir(), ...ZCODE_V2_CONFIG_PATH_SUFFIX);
-}
-
-/** 短名（无 provider 前缀）解析的默认 provider（zsub DEFAULT_PROVIDER_ID 同构）。 */
-const DEFAULT_PROVIDER_ID = "builtin:bigmodel-coding-plan";
-
-/**
- * 短名模型（如 "GLM-5.3"）的默认 provider 决策。让位条件（对齐点⑦）：显式默认引擎
- * 模型配置引入时（config.json 出现 per-engine model 映射 / engineRouting 级模型缺省），
- * 本函数的「内置常量优先」须让位为「配置值优先」——引擎路由层（engine/routing.ts 的
- * taskModel 判定处）是引入该配置时应同步调整的决策点，避免出现「路由按配置模型选了
- * 引擎、prepare 却按内置常量落池」的分裂。首期无该配置，常量即权威。
- */
-function defaultProviderForShortName(
-  merged: Map<string, ZcodeProviderEntry>,
-  withKey: Array<[string, ZcodeProviderEntry]>,
-): string {
-  if (merged.has(DEFAULT_PROVIDER_ID)) return DEFAULT_PROVIDER_ID;
-  return withKey[0]![0];
-}
-
-/**
- * 解析并校验模型引用 → 规范化全名 `provider/model`。
- *
- * 解析链（requested > 默认链）：
- *   1. 显式 requested（task.model）；
- *   2. ZCODE_FALLBACK_DEFAULT_MODEL（zsub 同构兜底）。
- *
- * 校验对「带 apiKey 的 provider 注册表」做（没配凭据的 provider 写进池也跑不起来，
- * resolve 期报错比运行时挂掉可诊断——zsub 经验）。provider 存在但无 apiKey →
- * engine_credential_missing；provider/模型不存在 → model_not_available（列可用清单）。
- */
-export function resolveZcodeModelRef(requested: string | undefined, sources?: ZcodeSourcePaths): string {
-  const v2 = readSourceConfig(sources?.v2ConfigPath ?? defaultV2ConfigPath());
-  const merged = v2.providers;
-  const withKey = [...merged.entries()].filter(([, e]) => hasApiKey(e));
-  const wanted = requested?.trim() || undefined;
-  const target = wanted ?? ZCODE_FALLBACK_DEFAULT_MODEL;
-
-  if (withKey.length === 0) {
-    const hint = wanted
-      ? `model="${wanted}" 不能校验`
-      : `默认模型 "${target}" 不能校验`;
-    throw new ZcodePrepareError(
-      "engine_credential_missing",
-      `zcode 引擎找不到任何带 apiKey 的 provider（${hint}）。已读源：${sources?.v2ConfigPath ?? defaultV2ConfigPath()}。` +
-        `恢复指引：先在 ZCode 桌面端登录并配置 provider（v2 config 内存在含 apiKey 的条目）后重试；` +
-        `凭据配置说明见 docs/research/agent-engine-zcode.md。`,
-    );
-  }
-
-  const provider = target.includes("/")
-    ? providerOf(target)
-    : defaultProviderForShortName(merged, withKey);
-  const short = modelShort(target);
-  const entry = merged.get(provider);
-  if (!entry) {
-    const known = withKey.map(([id]) => id).join(", ");
-    throw new ZcodePrepareError(
-      "model_not_available",
-      `未知 provider "${provider}"（带凭据的 provider: ${known}）。` +
-        `恢复指引：改用上述 provider 之一（全名 provider/model），或先在 ZCode 桌面端配置该 provider 后重试。`,
-    );
-  }
-  if (!hasApiKey(entry)) {
-    throw new ZcodePrepareError(
-      "engine_credential_missing",
-      `provider "${provider}" 存在但未配置 apiKey。` +
-        `恢复指引：在 ZCode 桌面端为该 provider 登录配置凭据，或改用已配凭据的 provider（${withKey.map(([id]) => id).join(", ")}）后重试。`,
-    );
-  }
-  const models = Object.keys(entry.models ?? {});
-  if (models.length > 0 && !models.includes(short)) {
-    throw new ZcodePrepareError(
-      "model_not_available",
-      `未知模型 "${short}"（provider ${provider} 下可用: ${models.join(", ")}）。` +
-        `恢复指引：改用该 provider 下的模型，或先在 ZCode 桌面端启用目标模型后重试。`,
-    );
-  }
-  return `${provider}/${short}`;
-}
-
-// ============================================================
-// 模型清单（U7 可发现性——v2 单源聚合，与 resolveZcodeModelRef 的凭据校验同判据）
-// ============================================================
-
-/**
- * 列出当前环境 zcode 引擎实际可用的模型（v2 config 内带 apiKey 的 provider × 其
- * models 清单）。消费方：EnginePort.listModels（system prompt 引擎段 / GUI）。
- * 失败安全：v2 config 不可读 → 空清单（可发现性降级不阻塞主流程）。
- */
-export function listZcodeModels(sources?: ZcodeSourcePaths): Array<{ id: string; name?: string }> {
-  const v2 = readSourceConfig(sources?.v2ConfigPath ?? defaultV2ConfigPath());
-  const out: Array<{ id: string; name?: string }> = [];
-  for (const [pid, entry] of v2.providers) {
-    if (!hasApiKey(entry)) continue;
-    const providerName =
-      typeof entry["name"] === "string" && entry["name"].trim() !== "" ? entry["name"].trim() : undefined;
-    const models = Object.keys(entry.models ?? {});
-    for (const model of models) {
-      out.push({
-        id: `${pid}/${model}`,
-        ...(providerName !== undefined ? { name: `${providerName} · ${model}` } : {}),
-      });
-    }
-  }
-  return out;
-}
-
-// ============================================================
-// 池 key 与目录
-// ============================================================
-
-/** provider id 安全化（builtin:bigmodel → builtin-bigmodel；zsub providerDirName 同构）。 */
-function sanitizeProviderDirName(p: string): string {
-  return p.replace(/[^A-Za-z0-9._-]/g, "-");
-}
-
-/**
- * 池 key：`home-<provider>-<modelShort>`（zsub homePoolDir 同构——provider+model 维度
- * 隔离防并发串池，见文件头注释）。model 短名只清洗路径敌对字符（分隔符/空白），
- * 保留点号（GLM-5.3 / mimo-v2.5-pro 原样——zsub 同判）；进入文件系统时由
- * resolvePoolDir 的 sanitizeSeg 再做一层统一编码。
- */
-export function computeZcodePoolKey(modelRef: string): string {
-  const provider = providerOf(modelRef);
-  const short = modelShort(modelRef).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-  return `home-${sanitizeProviderDirName(provider)}-${short.length > 0 ? short : "default"}`;
-}
-
-// ============================================================
-// 隔离 HOME 引导（bootstrapIsolatedHome TS 重写）
-// ============================================================
-
-export interface ZcodePreparedHome {
-  /** 规范化模型全名 provider/model。 */
-  modelRef: string;
-  /** 池 key（handle.poolKey 数据源）。 */
-  poolKey: string;
-  /** 池目录绝对路径 = 隔离 HOME。 */
-  homeDir: string;
-  /** 池内 config.json 绝对路径。 */
-  configPath: string;
-  /** 本次是否实际重写了 config（mtime 免重写命中时 false——resume/复用轮零开销）。 */
-  wroteConfig: boolean;
-}
-
-/**
- * 池 config 是否需要重写（zsub homeNeedsBootstrap 同构）：
- *   1. 池目录或池内 config.json 不存在（首次建池）；
- *   2. 池内 config.json 损坏（torn write 防线：mtime 看似新但内容不完整）；
- *   3. 任一「实际被用到的」源 config 的 mtime 比池内 config 新（凭据/模型清单刷新过）。
- * 源不可读但池配置完好：保留池现状——没有更好依据时不破坏可用状态。
- */
-function homeNeedsBootstrap(configPath: string, sourceMtimeMs: number): boolean {
-  if (!fs.existsSync(configPath)) return true;
-  let poolMtimeMs = 0;
-  try {
-    JSON.parse(fs.readFileSync(configPath, "utf8"));
-    poolMtimeMs = fs.statSync(configPath).mtimeMs;
-  } catch {
-    return true;
-  }
-  return sourceMtimeMs > poolMtimeMs;
-}
-
-/** 池 config.json 缩进（人读友好——与 zsub 产出的文件形态一致）。 */
-const CONFIG_INDENT_SPACES = 2;
-
-/**
- * 引导隔离 HOME 的 provider 配置（spawn 前调用）。
- *
- * - 只写 {model, provider}，刻意不含 plugins 块：第二重门禁——subagent 进程在隔离
- *   HOME 下不加载宿主插件（含 subagent-workflow 自身），物理隔断递归派发。
- * - tmp+rename 原子写：跨进程并发 bootstrap 下读者永远看到完整文件。进程内无需
- *   zsub 的互斥链——本实现全同步 fs（无 await 让出点），单线程事件循环天然不交错。
- * - 只写目标 provider 一个条目（spawn 池每池单 provider 单模型，凭据落盘面最小）。
- */
-export function prepareZcodeHome(opts: {
-  engineDataDir: string;
-  modelRef: string;
-  sources?: ZcodeSourcePaths;
-}): ZcodePreparedHome {
-  const { engineDataDir, modelRef } = opts;
-  const poolKey = computeZcodePoolKey(modelRef);
-  const homeDir = resolvePoolDir(engineDataDir, "zcode", poolKey);
-  const configPath = path.join(homeDir, ...ZCODE_POOL_CONFIG_SUFFIX);
-
-  const v2Path = opts.sources?.v2ConfigPath ?? defaultV2ConfigPath();
-  const v2 = readSourceConfig(v2Path);
-  const provider = providerOf(modelRef);
-  const entry = v2.providers.get(provider);
-  if (entry === undefined) {
-    // provider 不在 v2 注册表：模型引用不可解释（resolve 期漏网或直接调用）
-    throw new ZcodePrepareError(
-      "model_not_available",
-      `未知 provider "${provider}"（v2 config 无该条目：${v2Path}）。` +
-        `恢复指引：先经 resolveZcodeModelRef 校验模型引用，或先在 ZCode 桌面端配置该 provider 后重试。`,
-    );
-  }
-  if (!hasApiKey(entry)) {
-    // provider 存在但无凭据：resolve 与 bootstrap 之间凭据被撤（并发改动）
-    throw new ZcodePrepareError(
-      "engine_credential_missing",
-      `provider "${provider}" 存在但未配置 apiKey（${v2Path} 重读无凭据）。` +
-        `恢复指引：确认 ZCode 桌面端登录态有效后重试；凭据配置说明见 docs/research/agent-engine-zcode.md。`,
-    );
-  }
-
-  const hitSourceMtime = v2.mtimeMs;
-  let wroteConfig = false;
-  if (homeNeedsBootstrap(configPath, hitSourceMtime)) {
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    const payload = JSON.stringify({ model: { main: modelRef }, provider: { [provider]: entry } }, null, CONFIG_INDENT_SPACES);
-    const tmp = `${configPath}.tmp-${process.pid}-${Date.now()}`;
-    try {
-      fs.writeFileSync(tmp, payload, "utf8");
-      fs.renameSync(tmp, configPath);
-    } finally {
-      // rename 成功后 tmp 已不存在；失败时清残留，避免污染 HOME 目录
-      try {
-        if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
-      } catch (err) {
-        // rename 失败路径的残留清理是 best-effort——记录后继续（tmp 文件不参与读取）
-        void err;
-      }
-    }
-    wroteConfig = true;
-  }
-  return { modelRef, poolKey, homeDir, configPath, wroteConfig };
-}