@zhushanwen/subagent-core 0.2.0

package/src/orchestration/args-validator.ts

@@ -0,0 +1,127 @@
+// 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/config-loader.ts

@@ -0,0 +1,316 @@
+/**
+ * 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 { getHostServices } from "../core/host-services.ts";
+import { getLogger } from "../core/logger.ts";
+
+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, "../..")），hostRoots
+ * 置空（隔离 = 不注入宿主根，仅 project 根可命中）。
+ * 生产场景（省略或部分 config）走 findWorkspaceRoot(cwd) + 宿主注入 workflows 根。
+ */
+function toScanConfig(
+  configOrCwd: Partial<WorkflowScanConfig> & { cwd?: string } | undefined,
+): ScanConfig {
+  // 测试隔离：传入了 projectDir，直接反推 workspaceRoot
+  if (configOrCwd?.projectDir) {
+    const workspaceRoot = resolve(configOrCwd.projectDir, "../..");
+    return {
+      kind: "workflows",
+      workspaceRoot,
+      hostRoots: [],
+      includeTmp: true,
+    };
+  }
+
+  // 生产默认（hostRoots 现取——pi 壳 discoveryRoots 每次现取 getAgentDir，实例隔离）
+  const cwd = configOrCwd?.cwd;
+  const workspaceRoot = findWorkspaceRoot(cwd);
+  return {
+    kind: "workflows",
+    workspaceRoot,
+    hostRoots: getHostServices().discoveryRoots?.()?.workflows ?? [],
+    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();
+}