@zhushanwen/subagent-core 0.2.0

package/src/orchestration/models/types.ts

@@ -0,0 +1,301 @@
+/**
+ * Workflow Extension — Engine 共享类型
+ *
+ * Engine 层全局基础类型。零 infra 依赖——不 import 任何 infra 文件，
+ * 可独立编译测试（D-12 三层架构，AC-1）。
+ *
+ * 核心内容：
+ * - 状态机：RunStatus = "running" | "done"（2 态，一次性生命周期，FR-3）
+ * + DoneReason（completed/failed/aborted/budget_limited/time_limited）
+ * - AgentCallOpts / AgentResult / AgentUsage（单次 agent 调用的输入/输出）
+ * - ExecutionTraceNode / TracePatch / ToolCallEntry / WorkerLogEntry（trace 数据）
+ *
+ * 层归属：Engine（数据结构 + 不变式守卫）。
+ */
+
+import type { ExecutionRecord } from "../../execution/types.ts";
+
+// ── 状态机 ────────────────────────────────────────────────────
+
+/**
+ * 状态机：2 态（D-12 / FR-3，一次性生命周期——run 不可挂起）。
+ *
+ * running → done
+ *
+ * `done` 是唯一终态，具体原因由 DoneReason 区分。
+ */
+export type RunStatus = "running" | "done";
+
+/** 终态原因。done 时必有（WorkflowRun 不变式）。 */
+export type DoneReason =
+  | "completed"
+  | "failed"
+  | "aborted"
+  | "budget_limited"
+  | "time_limited"
+  // m3：runAndWait 合成返回值专用——参数校验失败（run 从未创建，不进入 run.state.reason）
+  | "invalid_args";
+
+/** 合法的状态转换。空数组 = 无出边（done 终态）。 */
+export const VALID_RUN_TRANSITIONS: Record<RunStatus, readonly RunStatus[]> = {
+  running: ["done"] as const,
+  done: [] as const,
+};
+
+export const ALL_RUN_STATUSES: readonly RunStatus[] = ["running", "done"] as const;
+
+export const ALL_DONE_REASONS: readonly DoneReason[] = [
+  "completed",
+  "failed",
+  "aborted",
+  "invalid_args",
+  "budget_limited",
+  "time_limited",
+] as const;
+
+/** done 为终态，无出边。 */
+export function isDone(status: RunStatus): boolean {
+  return status === "done";
+}
+
+export function canRunTransition(from: RunStatus, to: RunStatus): boolean {
+  return (VALID_RUN_TRANSITIONS[from] as readonly RunStatus[]).includes(to);
+}
+
+// ── Agent 调用 ────────────────────────────────────────────────
+
+/**
+ * 单次 agent 调用的输入选项。
+ *
+ * D-12 仅重组执行编排，AgentCallOpts 形状保持兼容。
+ */
+export interface AgentCallOpts {
+ /** The task prompt to send to the agent. */
+  prompt: string;
+ /**
+ * Optional JSON schema for structured output.
+ * When provided, the schema is passed via PI_WORKFLOW_SCHEMA env to the subprocess,
+ * which activates the structured-output tool + turn_end hook.
+ * The tool's execute validates model output against the schema.
+ * On success, `parsedOutput` on the result is set to `tool_execution_end.result.details`
+ * (the validated, parsed data object — not the raw tool call args).
+ */
+  schema?: Record<string, unknown>;
+ /**
+ * Model to use (e.g. "router-openai/glm-5.1").
+ * When omitted, pi's default model is used.
+ */
+  model?: string;
+ /**
+ * Thinking level override (e.g. "high", "medium", "low").
+ * M2: Added to align with subagent path's ExecuteOptions.thinkingLevel.
+ * When omitted, agent .md frontmatter thinkingLevel is used (via resolveIdentity/getAgentConfig).
+ */
+  thinkingLevel?: string;
+ /** Scene name passed through to the worker for model-selection hints. */
+  scene?: string;
+ /**
+ * Wall-clock timeout in milliseconds. When > 0, aborts the subprocess
+ * if it runs longer than this, regardless of external signal.
+ * Per-call，归 AgentCall 实体（G-027）。
+ */
+  timeoutMs?: number;
+ /**
+ * Turn 上限（turn limiter 用）。
+ *
+ * [预算语义对齐] 未传或 <=0 = 不限 turn；此时也不按 turns 估算 spawn watchdog——
+ * 仅当 env XYZ_SUBAGENT_SPAWN_WATCHDOG_MS 设置时才按绝对时限挂 watchdog（见
+ * session-runner.resolveSpawnWatchdogMs）。mapToExecuteOptions 原样透传到
+ * ExecuteOptions.maxTurns → 引擎 task-spec → runSpawn。
+ */
+  maxTurns?: number;
+ /**
+ * Skill name to load (e.g. "code-review"). Resolved to SKILL.md path
+ * and injected via --skill flag in the subprocess.
+ */
+  skill?: string;
+ /**
+ * Resolved absolute path to the skill directory or SKILL.md file.
+ * Set by agent-opts-resolver when opts.skill is present.
+ */
+  skillPath?: string;
+ /** Human-readable description for logging and debugging. */
+  description?: string;
+ /**
+ * Agent ref (absolute .md path). Resolved by resolveIdentity via getAgentConfig,
+ * which injects the agent's systemPrompt/model/tools/thinkingLevel. Not handled by
+ * resolveAgentOpts (single-responsibility: agent ref ownership belongs to resolveIdentity,
+ * M2 fix — previously overlapped causing double-injection + model-tier confusion).
+ */
+  agent?: string;
+ /**
+ * System prompt injection CONTENT (not file paths).
+ * Set by agent-opts-resolver: schema structured-output instruction string.
+ * Agent systemPrompt is NOT included here (handled by resolveIdentity/agentConfig).
+ * mapToExecuteOptions passes this through to ExecuteOptions.appendSystemPrompt
+ * (same name/semantics, transparent passthrough).
+ */
+  appendSystemPrompt?: string[];
+ /**
+ * Schema JSON for PI_WORKFLOW_SCHEMA env var.
+ * Set by agent-opts-resolver when opts.schema is present; passed as env var
+ * to activate the structured-output tool + hook.
+ */
+  schemaEnv?: string;
+ /**
+ * Per-call 工作目录（ADR-029 决策 1）。传给 child_process.spawn 的 cwd option。
+ *
+ * 用于 worktree 隔离：传入 worktree 绝对路径，spawn 的 pi 子进程绑定到该目录，
+ * 其内部的 createAgentSession/ResourceLoader/bash 工具都在该目录运行。
+ * undefined 时 spawn 继承 workflow 进程的 cwd（向后兼容）。
+ */
+  cwd?: string;
+  /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
+  fork?: boolean;
+  /**
+   * 执行引擎 id（P4 D9 三层优先级的第一层：调用参数级，workflow step 显式指定）。
+   * 仅限「必须某引擎独有能力」的场景使用并注释原因（D9③ workflow 脚本不写死
+   * engine——环境差异由 frontmatter/全局默认承载）；透传链 worker-script-builder
+   * agent() → execute-agent-call → SAR 路由层。
+   */
+  engine?: string;
+  /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
+  worktree?: boolean;
+  /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.
+   * Worker-layer flag only — not forwarded to ExecuteOptions (mapToExecuteOptions drops it). */
+  returnMeta?: boolean;
+}
+
+/**
+ * 单次 agent 调用的资源用量（FR-7 跨 turn 累积）。
+ */
+export interface AgentUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextTokens: number;
+  turns: number;
+}
+
+/**
+ * 单次 tool 调用记录（FR-7 从 agent JSONL 流采）。
+ */
+export interface ToolCallEntry {
+ /** Tool name. */
+  name: string;
+ /** Args preview string. */
+  input: string;
+}
+
+/**
+ * 单次 agent 调用的结果（统一形态）。
+ *
+ * Engine 直接消费 SubprocessAgentRunner 返回值；callCache replay 时 worker
+ * 取 parsedOutput ?? content（见 worker-script-builder.ts 消息处理）。
+ */
+export interface AgentResult {
+ /** Raw text output from the agent. */
+  content: string;
+ /**
+ * Parsed structured output.
+ * Present when `schema` was provided and the output was valid JSON.
+ * Source: tool_execution_end.result.details（validated data object）。
+ */
+  parsedOutput?: unknown;
+ /** Token and cost usage accumulated across all assistant turns. */
+  usage?: AgentUsage;
+ /** Wall-clock duration in milliseconds. */
+  durationMs?: number;
+ /** True when the pi process exited with code 0. */
+  error?: string;
+ /**
+ * Pi session ID for the subagent process (uuidv7).
+ * Present when pi emits a session header (default in --mode json).
+ * Can be used to locate the session JSONL file for post-run inspection (G-017)。
+ */
+  sessionId?: string;
+ /**
+ * Session JSONL 绝对路径（不含目录的文件名在 subagents 侧 AgentResult.sessionFile）。
+ * 由 mapToWorkflowAgentResult 从 subagents AgentResult 透传——让 workflow 编排层
+ * 继承 subagent 执行管道产出的 session 文件路径，overlay/GUI 可直接定位。
+ * 窗口期内可能 undefined（session 尚未创建成功）。
+ */
+  sessionFile?: string;
+ /**
+ * Absolute path of the git worktree used for filesystem isolation (set when
+ * worktree isolation is active). Injected by executeAndAwait from record.worktreeHandle.path.
+ *
+ * ⚠️ Diagnostic only, may not exist: executeAndAwait's finalizeRecord cleans up the
+ * worktree (git worktree remove --force) before returning, so by the time this field
+ * reaches the caller the directory has typically been deleted. Use it only for log/trace
+ * correlation (e.g. attributing a session jsonl to its worktree origin) — never as a cwd
+ * for a subsequent agent or filesystem operation (would ENOENT).
+ */
+  worktreePath?: string;
+ /** All tool calls collected from JSONL stream (FR-7). */
+  toolCalls?: ToolCallEntry[];
+}
+
+// ── Trace ─────────────────────────────────────────────────────
+
+/**
+ * 执行追踪节点（事件流 D-10 单一来源）。
+ */
+export interface ExecutionTraceNode {
+  stepIndex: number;
+  agent: string;
+  task: string;
+  model: string;
+  status: "pending" | "running" | "completed" | "failed";
+ /** Phase name for TUI grouping. Set from explicit opts.phase or global _currentPhase. */
+  phase?: string;
+  startedAt?: string;
+  completedAt?: string;
+  result?: AgentResult;
+  error?: string;
+ /**
+ * Pi session ID (uuidv7) for the subagent process.
+ * Used to locate the session JSONL for post-run inspection.
+ */
+  sessionId?: string;
+ /**
+ * Session JSONL 绝对路径。finalizeCall 从 result.sessionFile 透传。
+ * 持久化到快照（serializeRun），跨 session 重水合后保留。
+ */
+  sessionFile?: string;
+ /**
+ * Live 执行进度对象（running 时存在，done 时由 dispatchAgentCall 清除）。
+ *
+ * 挂在 node 上（D-10 单源延伸：AgentCall.traceNode 与 Trace.nodes 共享同一引用）。
+ * TUI 通过 trace.toArray() 读 node.live，派生 getEventLog/getCurrentActivity 实时展示。
+ * 不持久化（序列化时 strip；重跑时由 dispatchAgentCall 重建）。
+ */
+  live?: ExecutionRecord;
+}
+
+/**
+ * Trace.update 用的 patch（字段全可选）。
+ *
+ * 不变式：只改单个 node 的 status/result/error/completedAt/sessionId。
+ * callId 不存在时 update 为 no-op（D-10）。
+ */
+export interface TracePatch {
+  status?: "pending" | "running" | "completed" | "failed";
+  result?: AgentResult;
+  error?: string;
+  completedAt?: string;
+  sessionId?: string;
+  sessionFile?: string;
+}
+
+// ── Worker 诊断 ───────────────────────────────────────────────
+
+/**
+ * Worker console.* 捕获条目（run 级诊断，仅展示在 TUI widget，不泄漏到 input area）。
+ */
+export interface WorkerLogEntry {
+  level: "log" | "warn" | "error" | "info";
+  message: string;
+}

package/src/orchestration/models/workflow-run.ts

@@ -0,0 +1,254 @@
+/**
+ * Workflow Extension — WorkflowRun
+ *
+ * 单次 workflow run 的聚合根。封装状态机 + runtime 生命周期 + 不变式守卫。
+ * 架构核心——所有字段变更通过方法（transition/assignRuntime/releaseRuntime/
+ * replaceRuntime），engine 模块不直接打洞（AC-3）。
+ *
+ * 层归属：Engine。依赖 RunRuntime（具体类，D-12 允许）+ RunSpec/RunState + 类型。
+ *
+ * 关键不变式（必须全测）：
+ * I1: state.status === "running" ⟺ runtime !== undefined
+ * I2: state.status === "done" ⟹ state.reason !== undefined
+ *
+ * 状态机（一次性生命周期，2 态）：
+ * 构造（status="running"，I1 构造期跳过——runtime 由 assignRuntime 注入）
+ * running ──transition("done", reason)──→ done (releaseRuntime + completedAt)
+ * done ──(no out edges, zombie)
+ *
+ * 「创建即 running」与 I1 的协调（F4）：构造瞬间 running 而 runtime 尚未注入，
+ * I1 在构造期跳过（仅查 I2），完整校验由 assignRuntime/transition/replaceRuntime
+ * 末尾的 validateInvariants 维持；构造到 assignRuntime 的 I1 窗口由调用方
+ * （lifecycle.runWorkflow 在 assignRuntime 之后才 runs.set）保证对外不可见。
+ *
+ * worker-error-retry（G5-001 + G6-001）：
+ * - replaceRuntime(newRt): 前置 status==="running"（G6-001），原子释放前一个 runtime
+ * + 绑定新 runtime，全程保持不变式 I1（中间不经过 runtime===undefined 的可见状态）。
+ *
+ * 参考：domain-models.md §1（聚合根定义）、clarification.md G3-001/G5-001/G6-001。
+ */
+
+import { RunRuntime } from "./run-runtime.ts";
+import type { RunSpec } from "./run-spec.ts";
+import type { RunState } from "./run-state.ts";
+import type { DoneReason, RunStatus } from "./types.ts";
+import { canRunTransition } from "./types.ts";
+
+// ── WorkflowRunMeta ──────────────────────────────────────────
+
+/**
+ * 聚合根级 meta（非 RunState 的一部分，不随 trace 持久化到 worker JSONL）。
+ *
+ * workerErrorCount/scriptErrorCount 跨 runtime 存活（C.5：error-recovery 重试计数载体），
+ * 因为 retry 会 replaceRuntime，但计数是 run 级而非 runtime 级。
+ */
+export interface WorkflowRunMeta {
+ /** ISO 时间戳，run 创建/启动时刻。 */
+  startedAt: string;
+ /** ISO 时间戳，transition("done") 时设置。 */
+  completedAt?: string;
+ /** Worker 线程错误计数（C.5：跨 runtime 存活，重试计数载体）。 */
+  workerErrorCount?: number;
+ /** 脚本错误计数（C.5：跨 runtime 存活）。 */
+  scriptErrorCount?: number;
+}
+
+// ── WorkflowRun ──────────────────────────────────────────────
+
+export class WorkflowRun {
+  readonly runId: string;
+  readonly spec: RunSpec;
+  state: RunState;
+  runtime?: RunRuntime;
+  meta: WorkflowRunMeta;
+
+ /**
+ * 创建聚合根。初始状态 "running"（一次性生命周期：run 从创建起即在执行，
+ * runtime 由紧随其后的 assignRuntime 注入）。也可传入 done 状态用于重水合
+ * 已完成的 run（loadAll 后的只读聚合）。
+ *
+ * 不变式 I1 构造期跳过——「创建即 running」要求构造瞬间 runtime===undefined
+ * 合法（runtime 必须由 assignRuntime 注入，构造函数无从持有）；重水合的
+ * running 快照同样无 worker。I1 的运行时校验在 assignRuntime/transition/
+ * replaceRuntime 末尾的 validateInvariants 处生效。
+ */
+  constructor(
+    runId: string,
+    spec: RunSpec,
+    state: RunState,
+    meta: WorkflowRunMeta,
+  ) {
+    this.runId = runId;
+    this.spec = spec;
+    this.state = state;
+    this.meta = meta;
+ // runtime 在构造时始终为 undefined——run 创建时无活 worker，loadAll 重水合
+ // 时也不恢复 runtime（worker 必须由 lifecycle 重新 start）。
+    this.runtime = undefined;
+ // 构造期仅校验 I2（I1 跳过，见方法 doc）；I1 由 assignRuntime 末尾
+ // validateInvariants 恢复。
+    this.validateInvariantI2();
+  }
+
+ /**
+ * 从持久化快照重水合聚合根。与构造函数同语义（构造期跳过 I1——持久化的
+ * running 状态没有 worker，进程被杀后 worker 不可能还活着）。保留独立工厂
+ * 标注重水合意图；调用方（D-4 kill-9 恢复）负责在 session_start 时把残留
+ * running 转 done,failed，恢复 I1。
+ *
+ * @throws I2 违反（done 快照缺 reason 仍是 bug，不可跳过）
+ */
+  static reconstruct(runId: string, spec: RunSpec, state: RunState, meta: WorkflowRunMeta): WorkflowRun {
+    return new WorkflowRun(runId, spec, state, meta);
+  }
+
+ // ── 不变式校验 ─────────────────────────────────────────────
+
+ /**
+ * 校验不变式 I1 + I2。违反抛错（聚合根自我保护，fail-fast）。
+ * 在每个 mutation 方法末尾调用（防御式编程 + 测试可断言）。
+ */
+  private validateInvariants(): void {
+    this.validateInvariantI2();
+ // I1: status==="running" ⟺ runtime!==undefined
+    if (this.state.status === "running" && this.runtime === undefined) {
+      throw new Error(
+        `WorkflowRun invariant I1 violated: status==="running" but runtime is undefined (runId=${this.runId})`,
+      );
+    }
+    if (this.state.status !== "running" && this.runtime !== undefined) {
+      throw new Error(
+        `WorkflowRun invariant I1 violated: status!=="running" but runtime is defined (runId=${this.runId})`,
+      );
+    }
+  }
+
+ /**
+ * 仅校验不变式 I2（done ⟹ reason）。构造期用——「创建即 running」与重水合的
+ * running 快照都无 runtime（I1 构造期跳过），但 I2 必须保证（done 缺 reason 是真 bug）。
+ */
+  private validateInvariantI2(): void {
+    if (this.state.status === "done" && this.state.reason === undefined) {
+      throw new Error(
+        `WorkflowRun invariant I2 violated: status==="done" but reason is undefined (runId=${this.runId})`,
+      );
+    }
+  }
+
+ // ── 状态机转换 ─────────────────────────────────────────────
+
+ /**
+ * 状态机转换。合法转换：running→done。
+ *
+ * running 的进入不走 transition——构造即 running，replaceRuntime 保持 running。
+ * 调用 transition("running") 抛错，防止绕过 runtime 注入直接改状态。
+ *
+ * 副作用：
+ * - →done: releaseRuntime + 设 state.reason + meta.completedAt
+ *
+ * @param target 目标状态（不允许 "running"——runtime 注入只走 assignRuntime/replaceRuntime）
+ * @param reason →done 时必填（done ⟹ reason，不变式 I2）
+ * @throws 非法转换 / done 缺 reason / target==="running"
+ */
+  transition(target: RunStatus, reason?: DoneReason): void {
+ // "running" 必须经 assignRuntime（需 runtime 参数，transition 无法提供）
+    if (target === "running") {
+      throw new Error(
+        `WorkflowRun.transition: cannot transition to "running" directly — use assignRuntime() (runId=${this.runId})`,
+      );
+    }
+
+    if (!canRunTransition(this.state.status, target)) {
+      throw new Error(
+        `WorkflowRun.transition: illegal transition ${this.state.status} → ${target} (runId=${this.runId})`,
+      );
+    }
+
+ // →done 需 reason（不变式 I2）
+    if (target === "done" && reason === undefined) {
+      throw new Error(
+        `WorkflowRun.transition: transition to "done" requires a reason (runId=${this.runId})`,
+      );
+    }
+
+ // 副作用：先清理 runtime（releaseRuntime 守不变式 I1），再改 status
+ // （canRunTransition 已排除 target==="running"，此处 target 恒为 "done"）
+    this.releaseRuntime();
+    this.state.status = target;
+    this.state.reason = reason;
+    this.meta.completedAt = new Date().toISOString();
+
+    this.validateInvariants();
+  }
+
+ // ── Runtime 生命周期 ───────────────────────────────────────
+
+ /**
+ * 绑定 runtime（run 创建后注入执行资源）。
+ *
+ * 前置：status==="running" && runtime===undefined（runWorkflow 创建路径——
+ * 构造即 running 但 runtime 延迟到此处注入）。
+ * 原子地：设 runtime 后末尾 validateInvariants，恢复构造期跳过的 I1
+ * （running ⟺ runtime!==undefined）。
+ *
+ * @throws runtime 已定义 / status 不是 "running"（done 僵尸不可复活）
+ */
+  assignRuntime(rt: RunRuntime): void {
+    if (this.runtime !== undefined) {
+      throw new Error(
+        `WorkflowRun.assignRuntime: runtime already defined (runId=${this.runId})`,
+      );
+    }
+    if (this.state.status !== "running") {
+      throw new Error(
+        `WorkflowRun.assignRuntime: requires status==="running" (current: ${this.state.status}, runId=${this.runId})`,
+      );
+    }
+ // 原子绑定：构造期 I1 处于跳过窗口（running 而 runtime undefined），设 runtime
+ // 后末尾 validateInvariants 恢复 I1。调用方在 assignRuntime 后才对外注册
+ // （lifecycle.runWorkflow 的 runs.set 后移），窗口外部不可见。
+    this.runtime = rt;
+    this.validateInvariants();
+  }
+
+ /**
+ * 解绑 runtime（done 时由 transition 调用，也可独立调用）。
+ *
+ * 前置：无（runtime===undefined 时 no-op，幂等）。
+ * 副作用：调 runtime.release("terminal") 释放 worker/controller，置 runtime=undefined。
+ */
+  releaseRuntime(): void {
+    if (this.runtime === undefined) return;
+    this.runtime.release("terminal");
+    this.runtime = undefined;
+ // 不改 status——调用方（transition）负责。独立调用时调用方需自行确保
+ // status 一致（如 worker-error-retry 用 replaceRuntime 而非 release+assign）。
+  }
+
+ /**
+ * 原地替换 runtime（G5-001：worker-error-retry）。
+ *
+ * 前置：status==="running"（G6-001：终态 run 拒绝重建）。
+ * 原子地：释放旧 runtime（worker.terminate + abort）+ 绑定新 runtime，
+ * 全程 status 保持 "running"，不变式 I1 不违反（中间无 runtime===undefined 可见态）。
+ *
+ * 与 release+assign 的区别：replaceRuntime 不改 status，中间同步完成，
+ * 外部观察不到违反不变式的瞬间。
+ *
+ * @throws status!=="running"
+ */
+  replaceRuntime(rt: RunRuntime): void {
+    if (this.state.status !== "running") {
+      throw new Error(
+        `WorkflowRun.replaceRuntime: requires status==="running" (current: ${this.state.status}, runId=${this.runId})`,
+      );
+    }
+ // 原子替换：旧 runtime 释放（terminate+abort），新 runtime 绑定。
+ // status 保持 "running"，runtime 全程 !== undefined，I1 不违反。
+    if (this.runtime !== undefined) {
+      this.runtime.release("terminal");
+    }
+    this.runtime = rt;
+    this.validateInvariants();
+  }
+}

package/src/orchestration/models/workflow-script-registry.ts

@@ -0,0 +1,35 @@
+/**
+ * Workflow Extension — WorkflowScriptRegistry 仓库接口
+ *
+ * workflow 脚本的仓库（repository）接口——Engine 定义、Infra 实现。
+ *
+ * 与 Ports 节的 3 个注入 port（AgentRunner/RunStore/WorkerHost）的区别：
+ * - 3 个 port 是"执行依赖"（子进程/文件系统/线程），注入到 LifecycleDeps
+ * - WorkflowScriptRegistry 是"发现依赖"（扫描文件系统），是 repository（§8），
+ * 不进 LifecycleDeps，由 Interface 层 tool 直接调用（list/get 脚本）
+ *
+ * 优先级：tmp > project > user（domain-models.md §8）。60s TTL，按 workspaceRoot 分桶。
+ * 实现在 Infra 层 WorkflowScriptRegistryImpl（扫描 + 缓存 + 去重）。
+ *
+ * 层归属：Engine（interface），Infra（impl）。
+ *
+ * 参考：domain-models.md §8。
+ */
+import type { WorkflowScript } from "./workflow-script.ts";
+
+/**
+ * workflow 脚本仓库接口（repository，需 mock 文件扫描）。
+ */
+export interface WorkflowScriptRegistry {
+ /** 扫描并返回所有 workflow 脚本（含 available=false 的解析失败项）。去重按 tmp>project>user。 */
+  loadAll(): Promise<WorkflowScript[]>;
+
+ /** 按名查单个脚本（含缓存）。返回 undefined 当 name 不存在。 */
+  get(name: string): Promise<WorkflowScript | undefined>;
+
+ /** 按绝对路径加载单个脚本（workflowRef 统一解析入口——S2 路径统一）。 */
+  getPath(ref: string): Promise<WorkflowScript | undefined>;
+
+ /** 失效缓存——下次 loadAll/get 重新扫描文件系统。 */
+  invalidate(): void;
+}