@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/orchestration/args-validator.ts

@@ -1,127 +0,0 @@
-// src/orchestration/args-validator.ts
-//
-// m3：参数校验单一 chokepoint（IF3 validateRunArgs + IF4 ArgsValidationError）。
-// lifecycle.runWorkflow 首行调用——§5.3 fail-fast：参数错误在 worker 启动前返回，
-// 带「read 脚本重看」指引。
-//
-// 设计决策（m3 design-review 探针实证）：
-// - ajv 选项钉死 { coerceTypes:true, strictSchema:false, allErrors:true, useDefaults:false }：
-//   coerceTypes 原地规范化弱 LLM 的字符串参数（'false'→false、'10'→10，m2 MAJOR-1 闭环）；
-//   strictSchema:false 容忍用户 workflow 的自定义关键字/format（默认 strict:true 会误判畸形）；
-//   useDefaults:false 不注入 schema default（脚本 fallback 语义不变）。
-// - 无缓存：ajv.compile 实测 0.006ms/次（[P-compile]），v5 §6.5 的 Map 缓存被探针证据推翻。
-// - null-scan + required 空串复查：coerceTypes 下 {target:null} 会被 coerce 成 "" 放行
-//   required（required 只查属性存在性）——null 视为缺失、必填字符串空串视为失败，
-//   与 review-fix-loop 脚本的 !target 语义对齐，保住「启动前 fail-fast」承诺。
-
-import Ajv from "ajv";
-
-import type { RunSpec } from "./models/run-spec.ts";
-
-/** 参数校验失败（§5.3）。三调用方各自 catch 并映射到返回类型。 */
-export class ArgsValidationError extends Error {
-  readonly workflowName: string;
-  /** ajv 校验错误数组（畸形 schema 时为 undefined）。 */
-  readonly errors?: readonly unknown[];
-
-  constructor(workflowName: string, message: string, errors?: readonly unknown[]) {
-    super(message);
-    this.name = "ArgsValidationError";
-    this.workflowName = workflowName;
-    this.errors = errors;
-  }
-}
-
-const ajv = new Ajv({
-  coerceTypes: true,
-  strictSchema: false,
-  allErrors: true,
-  useDefaults: false,
-});
-
-/** §5.3 错误文案：workflow 名 + errors 摘要 + info 指引。 */
-function formatMessage(name: string, errors: readonly unknown[]): string {
-  const lines = errors.map((e) => {
-    let path = "/";
-    let msg = "invalid";
-    if (e !== null && typeof e === "object") {
-      const err = e as Record<string, unknown>;
-      if (typeof err.instancePath === "string" && err.instancePath) path = err.instancePath;
-      if (typeof err.message === "string") msg = err.message;
-    }
-    return `- ${path}: ${msg}`;
-  });
-  return (
-    `Invalid args for workflow '${name}': ${errors.length} error(s)\n` +
-    `${lines.join("\n")}\n` +
-    `Read the workflow script file (location from <available_workflows>) for the parameter schema and usage.`
-  );
-}
-
-/**
- * 校验 spec.parameters（JSON Schema draft-07）对 spec.args 的约束。
- *
- * - spec.parameters === undefined → 跳过（安全退化：漏拷 parameters 退化是「不校验」非「校验错」）
- * - coerceTypes 原地规范化 spec.args（worker 启动 + 崩溃重建重跑共用同一对象，
- *   run.spec === spec，保证重跑路径参数一致）
- * - 失败 throw ArgsValidationError（非原始 ajv 错误）
- *
- * @throws ArgsValidationError 参数不合法或 schema 无效
- */
-export function validateRunArgs(spec: RunSpec): void {
-  const { parameters, args, scriptName } = spec;
-  if (parameters === undefined) return;
-
-  if (parameters === null || typeof parameters !== "object" || Array.isArray(parameters)) {
-    throw new ArgsValidationError(
-      scriptName,
-      `Workflow '${scriptName}' has an invalid parameter schema (expected object). Read the workflow script file (location from <available_workflows>) to inspect it.`,
-    );
-  }
-
-  // null-scan：null 值视为缺失（coerceTypes 会把 null→"" 放行 required，绕过 fail-fast）。
-  // 只删 schema 未声明 nullable 的键——type 含 "null"（如 ["string","null"]）的合法 null
-  // 输入保留（m3 exec-review M1 探针实证：全键删除会拒掉 nullable required 的合法值）。
-  const schema = parameters as Record<string, unknown>;
-  const properties =
-    schema.properties !== null && typeof schema.properties === "object"
-      ? (schema.properties as Record<string, unknown>)
-      : {};
-  for (const key of Object.keys(args)) {
-    if (args[key] !== null) continue;
-    const prop = properties[key];
-    let isNullable = false;
-    if (prop !== null && typeof prop === "object") {
-      const propType = (prop as Record<string, unknown>).type;
-      isNullable = Array.isArray(propType)
-        ? (propType as unknown[]).includes("null")
-        : propType === "null";
-    }
-    if (!isNullable) delete args[key];
-  }
-
-  let validate: ReturnType<Ajv["compile"]>;
-  try {
-    validate = ajv.compile(parameters);
-  } catch (err) {
-    // 真畸形 schema（如 type:'not-a-type'）→ 结构化 ArgsValidationError，不泄漏原始 throw
-    const detail = err instanceof Error ? err.message : String(err);
-    throw new ArgsValidationError(
-      scriptName,
-      `Workflow '${scriptName}' has an invalid parameter schema: ${detail}. Read the workflow script file (location from <available_workflows>) to inspect it.`,
-    );
-  }
-
-  if (!validate(args)) {
-    throw new ArgsValidationError(
-      scriptName,
-      formatMessage(scriptName, validate.errors ?? []),
-      validate.errors ?? undefined,
-    );
-  }
-  // 注：非空约束由 schema 声明（minLength/pattern），chokepoint 不发明约束——
-  // m3 exec-review M2：硬编码 trim 空串复查与 schema 显式语义（enum 含 ''/minLength:0）
-  // 矛盾。review-fix-loop 的 target 用 { minLength: 1, pattern: '\\S' } 表达。
-  // 校验失败时 spec.args 可能已被 null-scan/coerce 部分 mutate（文档化行为：失败后
-  // 调用方不应复用该 args 对象）。
-}

package/src/orchestration/concurrency-gate.ts

@@ -1,69 +0,0 @@
-/**
- * Workflow Extension — Concurrency Gate
- *
- * 并发信号量薄封装。Engine 层 dispatchAgentCall 通过 withSlot 包装
- * executeAgentCall，gate 仅处理 signal abort 检查。实际并发调度
- * 由 SubagentService 内部的 ConcurrencyPool 统一管理。
- *
- * Wave 3 (D-A7)：withSlot 退化为 abort 薄封装，不独立占池。
- * 并发槽位由 execution/ConcurrencyPool（SubagentService 持有）统一管理，
- * 消除 gate + pool 双重计数的 2N 问题（T3.20）。
- *
- * 层归属：Infra（D-12）。RunRuntime 直接持有具体类。
- */
-
-// ── Constants ─────────────────────────────────────────────────
-
-/**
- * 默认并发上限（D-13）。保留常量向后兼容。
- * 实际并发由 ConcurrencyPool 管理。
- */
-export const DEFAULT_CONCURRENCY = 4;
-
-// ── Public options ────────────────────────────────────────────
-
-export interface ConcurrencyGateOptions {
- /** 最大并发数，缺省 4（D-13）。保留向后兼容。 */
-  maxConcurrency?: number;
-}
-
-// ── ConcurrencyGate ───────────────────────────────────────────
-
-export class ConcurrencyGate {
-  private readonly maxConcurrency: number;
-
-  constructor(opts: ConcurrencyGateOptions | number = {}) {
-    this.maxConcurrency =
-      typeof opts === "number" ? opts : (opts.maxConcurrency ?? DEFAULT_CONCURRENCY);
-  }
-
- /** 当前在飞的 agent 调用数（不独立计槽，恒为 0）。 */
-  get activeCount(): number {
-    return 0;
-  }
-
- /** 排队等待派发的调用数（不独立计槽，恒为 0）。 */
-  get queueLength(): number {
-    return 0;
-  }
-
- /**
-  * 获取一个并发槽位，执行 `fn`。
-  *
-  * Wave 3 简化：不独立管理槽位。仅做 signal pre-abort 检查，
-  * 直接执行 fn。实际并发调度由 SubagentService 的 ConcurrencyPool 负责。
-  *
-  * @param fn 槽位获取后执行的异步函数
-  * @param signal 外部 abort signal（pre-aborted 时立即 reject）
-  * @returns fn 的返回值
-  * @throws AbortError（signal 已 abort 时）
-  */
-  async withSlot<T>(fn: () => Promise<T>, signal?: AbortSignal): Promise<T> {
-    if (signal?.aborted) {
-      const err = new Error("Operation aborted before start");
-      err.name = "AbortError";
-      throw err;
-    }
-    return fn();
-  }
-}

package/src/orchestration/config-loader.ts

@@ -1,315 +0,0 @@
-/**
- * Workflow Config Loader — 统一资源发现版（ADR-031）
- *
- * 扫描逻辑委托给 shared/resource-discovery（与 agent 发现共享同一套扫描源）。
- * 本文件只保留 workflow 专属的 meta 提取（经 shared/meta-parser.ts IF1 统一 parser）+ 60s TTL 缓存。
- *
- * m2 收敛：删 extractMetaViaRegex + safeEvalObject(new Function)，改调 parseResourceMeta
- * （真实 YAML 解析 @pi-meta 块注释，发现期不执行作者代码，v5 原则 6 no-eval）。
- * toCachedMeta 整对象透传（...meta），不再 {name,description,phases} 解构——消灭第 1 处重映射。
- *
- * Failed imports are marked available=false — the loader never throws.
- */
-
-
-import { resolve } from "node:path";
-
-// WorkflowMeta 规范来源是 shared/resource-meta.ts（m1 DM1）；WorkflowSource 来自 workflow-script
-import type { WorkflowSource } from "./models/workflow-script.ts";
-import { clearLintMemo } from "./models/workflow-script.ts";
-import type { WorkflowMeta } from "../shared/resource-meta.ts";
-import { getCachedFile, getCachedFileContent, clearFileCache } from "../shared/resource-discovery.ts";
-import { parseResourceMeta } from "../shared/meta-parser.ts";
-import { normalizeRef, WORKFLOW_REF_EXT } from "../shared/agent-ref.ts";
-export type { WorkflowMeta, WorkflowSource };
-
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { getLogger } from "@zhushanwen/pi-extension-logger";
-
-const logger = getLogger("config-loader");
-
-import {
-  discoverResources,
-  findWorkspaceRoot,
-  type ResourceSource,
-  type ScanConfig,
-} from "../shared/resource-discovery.ts";
-
-// ── Public types ──────────────────────────────────────────────
-
-export interface CachedWorkflowMeta extends WorkflowMeta {
-  /** Absolute path to the script file */
-  path: string;
-  /** false when the script failed to load or has no valid meta export */
-  available: boolean;
-  /** Whether this is a saved (fixed) or temporary (ad-hoc) workflow */
-  source: WorkflowSource;
-}
-
-// ── Internal types ────────────────────────────────────────────
-
-interface CacheEntry {
-  meta: CachedWorkflowMeta;
-  /** 文件 mtime（m5：mtime 键控判失效——删 60s TTL，mtime 未变即命中）。 */
-  mtimeMs: number;
-}
-
-// ── Constants ─────────────────────────────────────────────────
-
-// m5：删 60s TTL——mtime 键控判失效（TTL 只服务 getWorkflow 且造成 60s 陈旧窗口）。
-
-// ── Cache ─────────────────────────────────────────────────────
-
-// Keyed by workspace root so that switching projects does not serve stale entries.
-const cache = new Map<string, Map<string, CacheEntry>>();
-
-function getCacheBucket(workspaceRoot: string): Map<string, CacheEntry> {
-  let bucket = cache.get(workspaceRoot);
-  if (!bucket) {
-    bucket = new Map<string, CacheEntry>();
-    cache.set(workspaceRoot, bucket);
-  }
-  return bucket;
-}
-
-function isCacheValid(entry: CacheEntry): boolean {
-  // m5：mtime 判变——文件 mtime 未变即命中（删 TTL 后文件变更立即反映）
-  const file = getCachedFile(entry.meta.path);
-  return file !== null && file.mtimeMs === entry.mtimeMs;
-}
-
-// ── Helpers ───────────────────────────────────────────────────
-
-/** Extract filename stem (no directory, no extension). */
-function stem(filePath: string): string {
-  const base = filePath.split("/").pop() ?? filePath;
-  const dot = base.lastIndexOf(".");
-  return dot > 0 ? base.slice(0, dot) : base;
-}
-
-// ── ResourceSource → WorkflowSource 映射 ─────────────────────
-
-/** 统一模块的 ResourceSource 映射为 workflow 的 saved/tmp 语义 */
-function toWorkflowSource(source: ResourceSource): WorkflowSource {
-  return source === "project-pi-tmp" ? "tmp" : "saved";
-}
-
-/**
- * 按路径推导 ResourceSource（IF4/外部 #5 残留）。
- *
- * getWorkflowByPath 可加载任意绝对路径（不限扫描源），此前硬编码 "user-pi"
- * 使 workspaceRoot/.pi/workflows/.tmp/ 下的临时脚本按路径加载被错标 saved
- * （discoverWorkflows 对同文件正确标 tmp，两路径不一致）。修正：路径落在
- * tmp 目录前缀内 → "project-pi-tmp"，其余 → "user-pi"（非 tmp 路径输出不变，DS4）。
- */
-function deriveResourceSource(filePath: string, workspaceRoot: string): ResourceSource {
-  const tmpDir = resolve(workspaceRoot, ".pi/workflows/.tmp");
-  const normalized = resolve(filePath);
-  return normalized === tmpDir || normalized.startsWith(`${tmpDir}/`) ? "project-pi-tmp" : "user-pi";
-}
-
-// ── 单文件 → CachedWorkflowMeta（IF1 parseResourceMeta + 整对象透传）──
-
-/**
- * 提取单个文件的 meta（经 IF1 parseResourceMeta），失败时标 available=false（fail-safe 不抛）。
- *
- * m2：整对象透传（...meta），不再 {name,description,phases} 解构——消灭第 1 处重映射，
- * parameters/usage/when/notFor 一路流到 script.meta。仅认 @pi-meta 新格式（D1 无 adapter）。
- */
-async function toCachedMeta(
-  filePath: string,
-  source: ResourceSource,
-): Promise<CachedWorkflowMeta> {
-  const fallbackName = stem(filePath);
-  const wfSource = toWorkflowSource(source);
-  try {
-    const content = getCachedFileContent(filePath); // m5：统一 mtime 缓存层
-    if (content === null) throw new Error("file not readable");
-    const meta = parseResourceMeta(content, "workflow");
-    if (meta && meta.kind === "workflow") {
-      return { ...meta, path: filePath, available: true, source: wfSource };
-    }
-    // m2 exec-review MINOR-4：文件可读但 meta=null → 旧 const meta 格式或格式错误，
-    // 静默 available=false（D1 无 adapter）。warn 帮助用户定位需迁移到 @pi-meta 的存量 workflow。
-    logger.warn(
-      `[config-loader] ${filePath}: 未解析到 @pi-meta 元数据（旧 const meta 格式需迁移）→ available=false`,
-    );
-  } catch (err) {
-    // 读失败 → available=false（fail-safe 不抛，与原行为一致）
-    logger.debug(`[config-loader] skip unreadable workflow file ${filePath}`, {
-      reason: err instanceof Error ? err.message : String(err),
-    });
-  }
-  return {
-    kind: "workflow",
-    name: fallbackName,
-    description: "",
-    phases: [],
-    path: filePath,
-    available: false,
-    source: wfSource,
-  };
-}
-
-// ── Public API ────────────────────────────────────────────────
-
-/**
- * workflow 发现的扫描配置。每个字段显式声明一个扫描源目录。
- *
- * 生产环境用 defaultScanConfig() 构造默认值（全局 ~/.pi/agent/* 目录）。
- * 测试/隔离环境构造完整 config 指向 tmp 目录，完全不碰全局文件系统。
- */
-export interface WorkflowScanConfig {
-  /** 项目级脚本目录（workspaceRoot/.pi/workflows） */
-  projectDir: string;
-  /** user 级脚本目录（~/.pi/agent/workflows） */
-  userDir: string;
-  /** 临时脚本目录（workspaceRoot/.pi/workflows/.tmp） */
-  tmpDir: string;
-  /** npm 包扫描目录（~/.pi/agent/npm/node_modules 等） */
-  npmDirs: string[];
-}
-
-/**
- * 把 WorkflowScanConfig 转为统一模块的 ScanConfig。
- *
- * 测试隔离场景下传入完整 config——此时按声明的 projectDir/tmpDir 反推
- * workspaceRoot（与原行为一致：resolve(config.projectDir, "../..")）。
- * 生产场景（省略或部分 config）走 findWorkspaceRoot(cwd)。
- */
-function toScanConfig(
-  configOrCwd: Partial<WorkflowScanConfig> & { cwd?: string } | undefined,
-): ScanConfig {
-  // 测试隔离：传入了 projectDir，直接反推 workspaceRoot
-  if (configOrCwd?.projectDir) {
-    const workspaceRoot = resolve(configOrCwd.projectDir, "../..");
-    return {
-      kind: "workflows",
-      workspaceRoot,
-      agentDir: "test-no-agent-dir",
-      includeTmp: true,
-    };
-  }
-
-  // 生产默认
-  const cwd = configOrCwd?.cwd;
-  const workspaceRoot = findWorkspaceRoot(cwd);
-  return {
-    kind: "workflows",
-    workspaceRoot,
-    agentDir: getAgentDir(),
-    includeTmp: true,
-  };
-}
-
-/**
- * 从指定 config 扫描所有 workflow 脚本，按 tmp>project>npm>user 优先级
- * 去重，60s TTL 缓存（按 workspaceRoot 分桶）。
- *
- * 扫描逻辑委托给 shared/resource-discovery（与 agent 发现共享同一套扫描源）。
- *
- * Never throws. 解析失败的脚本以 available=false 返回。
- *
- * @param configOrCwd 完整 WorkflowScanConfig（隔离用）、部分字段（覆盖默认）、
- *                   或省略（纯生产默认）。可选 cwd 用于推导 workspaceRoot。
- */
-export async function discoverWorkflows(
-  configOrCwd?: Partial<WorkflowScanConfig> & { cwd?: string },
-): Promise<CachedWorkflowMeta[]> {
-  const scanConfig = toScanConfig(configOrCwd);
-  const workspaceRoot = scanConfig.workspaceRoot;
-
-  // 统一发现：返回已去重的资源列表（按优先级合并）
-  const resources = await discoverResources(scanConfig);
-
-  // 提取 meta（逐文件）
-  const mergedMap = new Map<string, CachedWorkflowMeta>();
-  for (const resource of resources) {
-    const cachedMeta = await toCachedMeta(resource.path, resource.source);
-    // available=false 的不覆盖已有的 available=true（与统一模块逻辑一致）
-    if (!cachedMeta.available && mergedMap.has(cachedMeta.name)) {
-      continue;
-    }
-    mergedMap.set(cachedMeta.name, cachedMeta);
-  }
-
-  // 按 name 码点序输出（KV-cache 契约，与 injector 层一致）：不依赖发现层
-  // 优先级迭代序 / readdir 枚举序，重建结果顺序稳定。
-  const merged = Array.from(mergedMap.values()).sort((a, b) =>
-    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
-  );
-
-  // Update cache (scoped to current workspace root)
-  const bucket = getCacheBucket(workspaceRoot);
-  for (const wf of merged) {
-    const file = getCachedFile(wf.path);
-    bucket.set(wf.name, { meta: wf, mtimeMs: file?.mtimeMs ?? 0 });
-  }
-
-  return merged;
-}
-
-/**
- * Load and cache all available workflow scripts from project-level
- * (.pi/workflows/) and user-level (~/.pi/agent/workflows/) directories.
- *
- * discoverWorkflows() 的生产 preset——用全局默认目录。
- *
- * Never throws. Failed imports are returned with available=false.
- */
-export async function loadWorkflows(): Promise<CachedWorkflowMeta[]> {
-  return discoverWorkflows();
-}
-
-/**
- * Get a specific workflow by name.
- * Returns cached result if still valid, otherwise triggers a fresh load.
- */
-export async function getWorkflow(name: string): Promise<CachedWorkflowMeta | undefined> {
-  const workspaceRoot = findWorkspaceRoot();
-  const bucket = getCacheBucket(workspaceRoot);
-  const cached = bucket.get(name);
-  if (cached && isCacheValid(cached)) {
-    return cached.meta;
-  }
-
-  const workflows = await loadWorkflows();
-  return workflows.find((wf) => wf.name === name);
-}
-
-/**
- * 按绝对路径加载单个 workflow（workflowRef 统一解析入口——S2 路径统一）。
- *
- * - ~/ 前缀展开；相对路径/非 .js 引用返回 undefined（引用唯一形态 = 绝对路径）
- * - 任意路径（不限扫描源）：内置包内脚本、用户任意位置脚本均可执行
- * - meta 提取失败/文件不可读 → available=false（fail-safe，不抛）
- * - [perf] 与 getWorkflow(name) 对称走 bucket 缓存（key=绝对路径，与 stem 名不冲突），
- *   消除 workflow tool 主路径每次 run 的全文 regex + YAML.parse（mtime 判变失效）
- */
-export async function getWorkflowByPath(ref: string): Promise<CachedWorkflowMeta | undefined> {
-  const filePath = normalizeRef(ref, WORKFLOW_REF_EXT);
-  if (filePath === null) return undefined;
-  const workspaceRoot = findWorkspaceRoot();
-  const bucket = getCacheBucket(workspaceRoot);
-  const cached = bucket.get(filePath);
-  if (cached && isCacheValid(cached)) {
-    return cached.meta;
-  }
-  // IF4：source 按路径推导——.tmp 前缀 → project-pi-tmp（→ "tmp"），其余 user-pi 维持现值
-  const meta = await toCachedMeta(filePath, deriveResourceSource(filePath, workspaceRoot));
-  const file = getCachedFile(filePath);
-  if (file) bucket.set(filePath, { meta, mtimeMs: file.mtimeMs });
-  return meta;
-}
-
-/**
- * Invalidate the internal meta cache.
- * The next call to loadWorkflows or getWorkflow will re-scan directories.
- */
-export function invalidateCache(): void {
-  // m5：清统一 mtime 缓存层 + bucket（测试隔离 + mtime 漏判场景手动刷新兜底）
-  // IF9：连带清 workflow-script validate 的 lint memo（同源文件缓存，测试隔离统一走它）
-  clearFileCache();
-  cache.clear();
-  clearLintMemo();
-}