@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

package/src/execution/manifest-store.ts

@@ -1,256 +0,0 @@
-import * as fs from "node:fs";
-import * as fsPromises from "node:fs/promises";
-import * as path from "node:path";
-
-import { bestEffort } from "./best-effort.ts";
-
-export interface ManifestRecord {
-  id: string;
-  rootSessionId: string;
-  /** 直接父 subagent record ID（层级树构建用）。顶层 record 缺失（undefined）。M3a 补字段。 */
-  parentRecordId?: string;
-  agentName: string;
-  /**
-   * 终态枚举：finalizeRecord 写 running/closed/cancelled 三态。
-   * SP-1 重构：旧 completed/failed 合并为 closed（L1 统一终态）。
-   * cancelled 保持独立（用户取消语义）。crashed 不进 manifest——
-   * crashed 是重启重建时靠 sidecar 四分支推断的派生态（见 record-store.ts reconstructAll）。
-   * 历史 "error"/"completed"/"failed" 值由读侧 mapManifestStatus 向后兼容映射。
-   */
-  status: "running" | "closed" | "cancelled";
-  createdAt: number;
-  completedAt?: number;
-  sessionFile?: string;
-  /** FR-7 补字段：manifest 写入时从 ExecutionRecord 抓取，供 manifestToSubagent 投影真实值。 */
-  task?: string;
-  slug?: string;
-  model?: string;
-}
-
-/** JSON.stringify 缩进空格数（no-magic-numbers 合规）。 */
-const MANIFEST_INDENT_SPACES = 2;
-
-/** [perf] 缓存校验戳（与 record-store.ts Stamp 同构；manifest 是小文件，mtime+size 足够）。 */
-interface Stamp {
-  mtimeMs: number;
-  size: number;
-}
-
-function statStamp(p: string): Stamp | null {
-  try {
-    const s = fs.statSync(p);
-    return { mtimeMs: s.mtimeMs, size: s.size };
-  } catch {
-    return null;
-  }
-}
-
-/** 合法 manifest status 集合（3 态；运行时守卫用，磁盘文件可能陈旧/损坏）。
- * SP-1：completed/failed 合并为 closed。读侧 mapManifestStatus 向后兼容旧值。
- * crashed 不在其中。 */
-const VALID_MANIFEST_STATUSES: ReadonlySet<string> = new Set([
-  "running",
-  "closed",
-  "cancelled",
-  "completed", // 向后兼容旧 manifest 数据
-  "failed",     // 向后兼容旧 manifest 数据
-]);
-
-/**
- * 校验 JSON.parse 产物是否为合法 ManifestRecord。
- * 关键字段类型检查——不合法返回 false，调用方据此过滤（防损坏/陈旧文件污染投影）。
- */
-function isValidManifest(value: unknown): value is ManifestRecord {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as Record<string, unknown>;
-  return (
-    typeof v.id === "string" &&
-    typeof v.rootSessionId === "string" &&
-    typeof v.agentName === "string" &&
-    typeof v.createdAt === "number" &&
-    typeof v.status === "string" &&
-    VALID_MANIFEST_STATUSES.has(v.status)
-  );
-}
-
-export class ManifestStore {
-  private readonly dir: string;
-
-  /** [perf] per-file 缓存：file → { stamp, record }。record=null 表示「已解析但非法」（缓存
-   *  负结果避免反复 parse 损坏文件）。stat 戳变化（writeManifest tmp→rename 后 mtime/size 变）
-   *  自动失效；删除的文件在下次扫描时修剪。 */
-  private readonly cache = new Map<string, { stamp: Stamp; record: ManifestRecord | null }>();
-
-  constructor(dir: string) {
-    this.dir = dir;
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-  }
-
-  /**
-   * 原子写：tmp → fsync → rename → fsync dir。真异步（fs.promises，不阻塞 event loop）。
-   *
-   * rename 失败时 best-effort 清理残留 tmp（用 renamed 标志在 catch 中决定是否 unlink），
-   * 不掩盖原错误。失败向上抛——调用方（finalizeRecord）决定降级策略。
-   */
-  async writeManifest(record: ManifestRecord): Promise<void> {
-    const filePath = path.join(this.dir, `${record.id}.json`);
-    const tmpPath = `${filePath}.tmp.${process.pid}`;
-    const content = JSON.stringify(record, null, MANIFEST_INDENT_SPACES);
-
-    let renamed = false;
-    try {
-      // 1. 写 tmp → fsync 文件
-      const fh = await fsPromises.open(tmpPath, "w");
-      try {
-        await fh.writeFile(content, "utf-8");
-        await fh.sync();
-      } finally {
-        await fh.close();
-      }
-
-      // 2. rename tmp → final（放入 try：失败时 catch 清理 tmp）
-      await fsPromises.rename(tmpPath, filePath);
-      renamed = true;
-
-      // 3. fsync 目录（best-effort：POSIX 不要求，失败不否定已成功的 rename）
-      try {
-        const dirFh = await fsPromises.open(this.dir, "r");
-        try {
-          await dirFh.sync();
-        } finally {
-          await dirFh.close();
-        }
-      } catch (dirSyncErr) {
-        bestEffort(dirSyncErr, "fsync dir (writeManifest)");
-      }
-    } catch (err) {
-      // rename 未成功 → 清理残留 tmp（best-effort，不掩盖原错误）
-      if (!renamed) {
-        try {
-          await fsPromises.unlink(tmpPath);
-        } catch (cleanupErr) {
-          // best-effort：tmp 可能已被 rename 消费或从未创建。不影响主错误（下面 re-throw err）
-          bestEffort(cleanupErr, "unlink tmp (writeManifest)");
-        }
-      }
-      throw err;
-    }
-  }
-
-  /**
-   * 按 id 读 manifest。文件不存在/JSON 损坏/schema 不合法均返回 null。
-   * 调用方需处理 null。
-   */
-  async readManifest(id: string): Promise<ManifestRecord | null> {
-    const filePath = path.join(this.dir, `${id}.json`);
-    try {
-      const content = await fsPromises.readFile(filePath, "utf-8");
-      const parsed: unknown = JSON.parse(content);
-      return isValidManifest(parsed) ? parsed : null;
-    } catch {
-      // 文件缺失（ENOENT）或 JSON 损坏（SyntaxError）均降级为 null
-      return null;
-    }
-  }
-
-  /**
-   * 同步读取所有 manifest 记录（best-effort，损坏/非法文件跳过）。
-   * 供 RecordStore.collectRecords 投影 orphan 记录使用——替代对私有 dir 的反射访问。
-   * 仅返回通过 isValidManifest 校验的记录。
-   *
-   * [perf] per-file 缓存 + stat 戳校验：collectRecords 每次渲染都调本方法，旧实现每次
-   * 全量 readFileSync + JSON.parse 千级 manifest（实测 ~300ms/次）。命中缓存的文件零读取。
-   */
-  listAllSync(): readonly ManifestRecord[] {
-    let files: string[];
-    try {
-      files = fs.readdirSync(this.dir);
-    } catch {
-      return [];
-    }
-    const names = files.filter((f) => f.endsWith(".json") && !f.includes(".tmp."));
-    const disk = new Set(names);
-
-    // 修剪已删除文件
-    for (const f of this.cache.keys()) {
-      if (!disk.has(f)) this.cache.delete(f);
-    }
-
-    const results: ManifestRecord[] = [];
-    for (const file of names) {
-      const filePath = path.join(this.dir, file);
-      const stamp = statStamp(filePath);
-      if (!stamp) {
-        this.cache.delete(file);
-        continue;
-      }
-      const cached = this.cache.get(file);
-      if (cached && cached.stamp.mtimeMs === stamp.mtimeMs && cached.stamp.size === stamp.size) {
-        if (cached.record) results.push(cached.record);
-        continue;
-      }
-      try {
-        const content = fs.readFileSync(filePath, "utf-8");
-        const parsed: unknown = JSON.parse(content);
-        const record = isValidManifest(parsed) ? parsed : null;
-        this.cache.set(file, { stamp, record });
-        if (record) results.push(record);
-      } catch (fileErr) {
-        // best-effort：损坏/非法文件跳过（debug 记录便于排查）。缓存负结果防反复 parse。
-        this.cache.set(file, { stamp, record: null });
-        bestEffort(fileErr, `read manifest ${file} (listAllSync)`);
-      }
-    }
-    return results;
-  }
-
-  /**
-   * 启动时恢复 tmp 文件。
-   * 3 分支逻辑：
-   * 1. manifest 已存在 → 删 tmp（陈旧）
-   * 2. tmp 合法 + manifest 缺失 → rename tmp 为 manifest
-   * 3. tmp 非法 + manifest 缺失 → 删 tmp
-   */
-  async recoverTmpFiles(): Promise<{ deleted: number; recovered: number }> {
-    let deleted = 0;
-    let recovered = 0;
-
-    const files = fs.readdirSync(this.dir);
-    const tmpFiles = files.filter((f) => f.includes(".json.tmp."));
-
-    for (const tmpFile of tmpFiles) {
-      const tmpPath = path.join(this.dir, tmpFile);
-      const manifestId = tmpFile.split(".json.tmp.")[0];
-      const manifestPath = path.join(this.dir, `${manifestId}.json`);
-
-      if (fs.existsSync(manifestPath)) {
-        // 分支 1: manifest 已存在，删 tmp
-        fs.unlinkSync(tmpPath);
-        deleted++;
-      } else {
-        // 试解析 tmp
-        try {
-          const content = fs.readFileSync(tmpPath, "utf-8");
-          const parsed: unknown = JSON.parse(content);
-          if (isValidManifest(parsed)) {
-            // 分支 2: tmp 是合法 manifest，rename 为正式文件
-            fs.renameSync(tmpPath, manifestPath);
-            recovered++;
-          } else {
-            // 分支 3b: 合法 JSON 但非合法 manifest（缺必填字段），删
-            fs.unlinkSync(tmpPath);
-            deleted++;
-          }
-        } catch {
-          // 分支 3a: JSON.parse 失败，删
-          fs.unlinkSync(tmpPath);
-          deleted++;
-        }
-      }
-    }
-
-    return { deleted, recovered };
-  }
-}

package/src/execution/model-config-service.ts

@@ -1,219 +0,0 @@
-// src/runtime/model-config-service.ts
-//
-// 配置 + 模型解析领域 Service。"给定 agent 名 + 用户参数 + 主 agent 模型，用哪个模型？"
-//
-// 与 SubagentService（执行/记录/通知域）正交——本 Service 不碰 pool/store/notifier。
-// 上游：SubagentService.execute 内部调 resolveModel。
-// session_start 时经 initModel 注入 modelRegistry。
-
-import { AgentRegistry } from "./agent-registry.ts";
-import {
-  loadGlobalConfig,
-} from "./config.ts";
-import {
-  type AgentConfig,
-  type ModelInfo,
-  type ModelRegistryLike,
-  type ResolvedModel,
-  resolveModel,
-} from "./model-resolver.ts";
-import type { SubagentsGlobalConfig } from "./types.ts";
-
-// ============================================================
-// 类型
-// ============================================================
-
-/** Service 构造参数（进程级，跨 session 不变）。 */
-export interface ModelConfigServiceInit {
-  agentDir: string;
-  /** 项目根目录（ctx.cwd，用于推导 workspaceRoot 扫描 project 级资源）。 */
-  cwd: string;
-}
-
-/** session_start 注入参数（session 级，每次重建）。 */
-export interface ModelServiceSessionInit {
-  /** 模型注册表（鉴权 + 发现）。null 立即抛错（fail-fast）。 */
-  modelRegistry: ModelRegistryLike | null;
-  /** 当前 session ID。 */
-  sessionId: string;
-  /**
-   * 主 agent 当前 model（session_start 时注入，model_select 时刷新）。
-   *
-   * renderCall 阶段的 ToolRenderContext 不含 model 字段（SDK 限制），无法直接拿到
-   * 主 agent model。缓存后 renderCall 的 resolveModel 能命中第三层（ctxModel），
-   * 让标题行恢复显示 model——即使未显式传 model 也能展示默认 model。
-   *
-   * [HISTORICAL] 99f20da1e 引入三层 fallback 后，renderCall 因拿不到 ctxModel
-   * 而 resolveModel 拗错→降级不显示 model。此缓存修复该降级。
-   */
-  ctxModel?: ModelInfo;
-}
-
-// ============================================================
-// ModelConfigService
-// ============================================================
-
-/**
- * 配置 + 模型解析 Service。进程级单例。
- *
- *   ┌──────────────────────────────────────────────────────┐
- *   │  globalConfig（~/.pi/.../config.json，仅 maxConcurrent）│
- *   │  agentRegistry（agent .md 发现 + frontmatter）         │
- *   │  modelRegistry（SDK 注入的可用模型）                    │
- *   │                                                      │
- *   │  resolveModel: override → agentConfig → 主 agent model │
- *   └──────────────────────────────────────────────────────┘
- */
-export class ModelConfigService {
-  private globalConfig: SubagentsGlobalConfig;
-  private readonly agentRegistry: AgentRegistry;
-  private readonly agentRegistryDir: string;
-  private modelRegistry: ModelRegistryLike | null = null;
-  private _sessionId: string | undefined;
-  /** 主 agent 当前 model 缓存（session_start 注入，model_select 刷新）。 */
-  private _ctxModel: ModelInfo | undefined;
-
-  constructor(init: ModelConfigServiceInit) {
-    this.agentRegistryDir = init.agentDir;
-    this.globalConfig = loadGlobalConfig(init.agentDir);
-    this.agentRegistry = new AgentRegistry();
-  }
-
-  // ── 生命周期（index.ts 调）──────────────────────────────
-
-  /**
-   * session_start 注入。封装 3 步固定时序：
-   *   1. reloadGlobalConfig（复用时拿最新 config）
-   *   2. injectModelRegistry（fail-fast：null 抛错）
-   *   3. setSessionId
-   */
-  initModel(init: ModelServiceSessionInit): void {
-    // 1. 重载配置（agent 按需 loadByPath，无预热扫描）
-    this.globalConfig = loadGlobalConfig(this.agentRegistryDir);
-
-    // 2. modelRegistry（fail-fast）
-    if (init.modelRegistry === null) {
-      throw new Error("modelRegistry is required but got null");
-    }
-    this.modelRegistry = init.modelRegistry;
-
-    // 3. sessionId + ctxModel 缓存（model_select 后续调 setCtxModel 刷新）
-    this._sessionId = init.sessionId;
-    this._ctxModel = init.ctxModel;
-  }
-
-  /**
-   * 刷新主 agent model 缓存。model_select 事件时调用。
-   * renderCall 的 resolveModel 读此缓存以显示标题行 model。
-   */
-  setCtxModel(model: ModelInfo | undefined): void {
-    this._ctxModel = model;
-  }
-
-  // ── 模型解析（SubagentService.execute 内部调）──────────────
-
-  /**
-   * 解析 agent 的模型（三层：override → agentConfig → 主 agent model）。
-   *
-   * @param agentRef   agent 引用（.md 绝对路径；查 agentConfig 的 model override）
-   * @param override   调用方显式 override（最高优先级）
-   * @param ctxModel   主 agent 当前模型（兜底，直接透传）
-   */
-  resolveModel(
-    agentRef: string,
-    override?: { model?: string; thinkingLevel?: string },
-    ctxModel?: ModelInfo,
-    /** 已解析的 agent 配置（调用方已加载时复用，避免同一 agentRef 二次 loadByPath）。 */
-    agentConfig?: AgentConfig,
-  ): ResolvedModel {
-    this.assertReady();
-    const config = agentConfig ?? (agentRef ? this.agentRegistry.loadByPath(agentRef) : undefined);
-    // ctxModel 优先用显式传入（execute 路径），其次用 session 缓存（renderCall 路径）
-    return resolveModel(config, this.modelRegistry!, override, ctxModel ?? this._ctxModel);
-  }
-
-  /** 查询 agent 配置（SubagentService 内部判定 defaultBackground 用）。
-   *  undefined = 合法缺省语义（未点名 / 默认 general-purpose 形态）。 */
-  getAgentConfig(agentRef?: string): AgentConfig | undefined {
-    return agentRef ? this.agentRegistry.loadByPath(agentRef) : undefined;
-  }
-
-  /**
-   * 查询 agent 配置——显式 ref 失败即 throw（SubagentService.resolveIdentity 用）。
-   *
-   * 与 getAgentConfig 的语义分界（「用户显式点名」vs「默认 general-purpose」）：
-   * 用户显式点名的 agentRef（工具 agent 参数 / workflow agent({agent}) opts）解析
-   * 失败 = 配置错误，必须显式报错——错误文案含 <available_subagents> 恢复指引
-   * （对齐 workflow name not found 反馈风格），不允许静默降级为无配置
-   * general-purpose 形态（systemPrompt/工具白名单全丢且零反馈）。默认形态
-   * （不传 agent）走 getAgentConfig：undefined = 合法缺省，走 override → ctxModel 兑底。
-   */
-  getRequiredAgentConfig(agentRef: string): AgentConfig {
-    return this.agentRegistry.loadByPath(agentRef, true);
-  }
-
-  // ── 配置读取（subagent-service 调）────────────────────────
-
-  /** 全局配置深拷贝（调用方拿到副本，改不影响 Service 内部）。 */
-  getGlobalConfig(): SubagentsGlobalConfig {
-    return structuredClone(this.globalConfig);
-  }
-
-  /** 内部：session id 缓存（initModel 注入；当前无消费者，保留供未来 session 作用域需求）。 */
-  get sessionId(): string | undefined {
-    return this._sessionId;
-  }
-
-  /** agent 配置目录（SubagentService 构造 store/SessionRunnerContext 时读）。 */
-  getAgentDir(): string {
-    return this.agentRegistryDir;
-  }
-
-  /** modelRegistry（SubagentService 构造 factoryCtx 时读）。已注入保证非 null。 */
-  getModelRegistry(): ModelRegistryLike {
-    if (this.modelRegistry === null) {
-      throw new Error("modelRegistry not injected (initModel not called?)");
-    }
-    return this.modelRegistry;
-  }
-
-  // ── 内部 ────────────────────────────────────────────────
-
-  /** 校验 modelRegistry 已注入。 */
-  private assertReady(): void {
-    if (this.modelRegistry === null) {
-      throw new Error("modelRegistry not injected (initModel not called?)");
-    }
-  }
-}
-
-// ============================================================
-// 进程单例访问器
-// ============================================================
-
-// 用 globalThis[Symbol.for] 持有进程单例，避免 jiti 因路径字符串不同加载多份模块
-// 导致单例分裂（详见 docs/standards.md §7.5）。
-const MODEL_SERVICE_SLOT_KEY = Symbol.for("@zhushanwen/pi-subagents.model-service");
-
-type ModelServiceSlot = { current: ModelConfigService | null };
-
-function getModelServiceSlot(): ModelServiceSlot {
-  // globalThis 无 symbol 索引签名，但运行时支持 symbol 键——用 Reflect 安全读写，
-  // 避免双重断言。ModelServiceSlot 是运行时保证的固定形状（同文件唯一写入点）。
-  let slot = Reflect.get(globalThis, MODEL_SERVICE_SLOT_KEY) as ModelServiceSlot | undefined;
-  if (!slot) {
-    slot = { current: null };
-    Reflect.set(globalThis, MODEL_SERVICE_SLOT_KEY, slot);
-  }
-  return slot;
-}
-
-/** 获取进程单例。session_start 前为 null。 */
-export function getModelConfigService(): ModelConfigService | null {
-  return getModelServiceSlot().current;
-}
-
-/** 设置进程单例（session_start 首次创建时）。 */
-export function setModelConfigService(service: ModelConfigService): void {
-  getModelServiceSlot().current = service;
-}