@mickorz/opencode-agentic-workflow 0.5.1 → 0.6.0

package/dist/workflows/loader.d.ts

@@ -1,124 +1,32 @@
 /**
- * 声明式 workflow 装载器（P4）—— 用户自定义流程的 JSON 形态
+ * 代码 workflow 装载器 —— 用户自定义流程的 JS 模块形态（唯一形态）
  *
- * 装载契约（详见 dev-docs/planning/P4-custom-workflows.md）：
- *   - 入口：.json 文件路径 或 目录（扫一层 *.json）；相对项目目录
- *   - 步骤七类（互斥键）：agent / checkpoint / verify / fileExists / subflow /
- *     pipeline（条目并发 fan-out，{{item}} 引用条目）/ race（≥2 提示竞速取首胜）
- *   - 模板：{{topic}}、{{args.x}}、{{steps.<name>}}；pipeline 提示额外支持
- *     {{item}}（条目字面替换，先于通用模板解析）；未知变量 = 步骤失败
- *   - 并发步骤的 resume 粒度：pipeline/race 各占一个 journal 步骤单元
- *     （completed 即整体跳过；中断重跑整步——与 sequence 前缀语义一致）
- *   - 错误语义：装载期文件级 skip+warn（不阻断其他文件与内置流程）；
- *     运行期步骤级 failed（走既有 journal/resume 语义）
+ * v0.6.0 产品决策：声明式 JSON 流程面下线（设计未定型，暂只保留代码流程）。
+ * 历史 JSON 机器（validateWorkflow / toDefinition / 模板解析）在 git 历史与
+ * dev-docs/design 中留档，重设计时再取。
+ *
+ * 装载契约：
+ *   - 入口：.js / .mjs / .cjs 文件路径或目录（扫一层，忽略点开头文件）；相对 baseDir
+ *   - 模块导出：default / definition / workflow 三形态之一，最小形状校验
+ *     （id/version 非空字符串 + run 函数）
+ *   - <pkg>/core 裸说明符重写（v0.6.0）：用户 flows 目录通常解析不到本包
+ *     （包在 opencode 全局缓存，不在用户 node_modules 链上）——装载时把
+ *     "<pkg>/core" 重写为插件自身 dist/core 的绝对 file URL 再导入，
+ *     保证拿到与宿主同一模块实例（executor / ambient 状态已接线）。
+ *     实现方式：同目录隐藏临时 .mjs（保留用户目录的相对/npm 解析语义）
+ *     → import → 清理；目录不可写时回退 data: URL 导入。
+ *   - .json 入口不再装载：显式文件或目录内 .json 都给出迁移提示（fail-loud）
+ *   - 错误语义：装载期文件级 skip+warn（不阻断其他文件与内置流程）
  *
  * 纪律：本文件属于 Core 侧资产装载，禁止 import OpenCode API
  * （架构不变量）；路径解析基准由调用方（plugin）传入。
  */
 import type { AnyWorkflowDefinition } from "../registry/registry.js";
-/** 步骤四类的声明形态（互斥键由校验保证） */
-interface AgentStepDecl {
-    name: string;
-    agent: string;
-    /** P1-4 调用级选项（仅 agent 步可用） */
-    model?: string;
-    timeoutMs?: number;
-    retries?: number;
-}
-interface CheckpointStepDecl {
-    name: string;
-    checkpoint: string;
-}
-interface VerifyStepDecl {
-    name: string;
-    verify: {
-        artifact: string;
-        criteria?: string;
-        reviewers?: number;
-        label?: string;
-        /** P2-11：投票阈值 (0,1]，缺省 1 = 全票 */
-        threshold?: number;
-        /** P2-11：多视角评审（一个 lens 一个评审员，覆盖 reviewers/criteria） */
-        lenses?: Array<{
-            name: string;
-            criteria: string;
-        }>;
-    };
-}
-interface FileExistsStepDecl {
-    name: string;
-    fileExists: string;
-}
-/** P2-9 子工作流步骤：subflow = 目标 flow id（模板）；args 值支持模板 */
-interface SubflowStepDecl {
-    name: string;
-    subflow: string;
-    args?: Record<string, string | number | boolean>;
-}
-/**
- * 并发流水线步骤（声明式 pipeline）：pipeline = 每条目提示模板（{{item}} 引用条目，
- * 其余变量走通用模板）；items = 条目模板数组（每项解析后原样作为条目值）。
- * 条目并发、单阶段（多阶段链用代码式 combinator）；结果数组（与 items 对齐）
- * 并入 state[outputAs ?? name]。
- */
-interface PipelineStepDecl {
-    name: string;
-    pipeline: string;
-    /** 条目（每项为模板） */
-    items: string[];
-    /** 结果并入 state 的键（缺省 = 步骤名） */
-    outputAs?: string;
-    /** 失败模式（与代码式 pipeline 同语义，缺省 fail-fast） */
-    onFailure?: "fail-fast" | "continue";
-    /** agent 调用级选项（每条目同规则透传） */
-    model?: string;
-    timeoutMs?: number;
-    retries?: number;
-}
-/**
- * 竞速步骤（声明式 race）：race = 竞速提示模板数组（≥2），并发起跑、
- * 首个成功者输出并入 state[outputAs ?? name]；全败抛 WorkflowRaceError。
- */
-interface RaceStepDecl {
-    name: string;
-    race: string[];
-    /** 结果并入 state 的键（缺省 = 步骤名） */
-    outputAs?: string;
-}
-type StepDecl = AgentStepDecl | CheckpointStepDecl | VerifyStepDecl | FileExistsStepDecl | SubflowStepDecl | PipelineStepDecl | RaceStepDecl;
-export interface DeclarativeWorkflow {
-    id: string;
-    version?: string;
-    description?: string;
-    /** argsSchema（JSON Schema）；缺省 = 仅 topic（工具恒传） */
-    args?: Record<string, unknown>;
-    steps: StepDecl[];
-    /** 输出模板；缺省 = 最后一个 agent 步的输出 */
-    output?: string;
-}
-/** 单文件校验：返回声明对象或错误文案（含文件名前缀） */
-export declare function validateWorkflow(raw: unknown, file: string): {
-    ok: true;
-    value: DeclarativeWorkflow;
-} | {
-    ok: false;
-    error: string;
-};
-/**
- * 模板解析：{{topic}} / {{args.x}} / {{steps.<name>}}（允许空白）。
- * 未知变量抛错（步骤级失败、journal 可见，绝不静默空串）。
- */
-export declare function resolveTemplate(template: string, args: Record<string, unknown>, stepOutputs: ReadonlyMap<string, string>): string;
-/** P0-2：声明对象 -> 可注册 definition（workflow_define 内联定义复用同一转换） */
-export declare function toDefinition(dw: DeclarativeWorkflow): AnyWorkflowDefinition;
 /**
- * 装载自定义流程（声明式 JSON + 代码式 JS 模块，P2-14 起统一入口）。
+ * 装载自定义流程（代码式 JS 模块；v0.6.0 起唯一形态）。
  * 文件级错误 warn+跳过（与装载纪律一致：观测/装载不能成为主链路故障源）。
  */
 export declare function loadCustomWorkflows(entries: string[], baseDir: string, reservedIds?: string[]): Promise<{
     definitions: AnyWorkflowDefinition[];
     errors: string[];
 }>;
-/** @deprecated 旧名（P2-14 起装载范围扩展到代码流程），等价 loadCustomWorkflows */
-export declare const loadDeclarativeWorkflows: typeof loadCustomWorkflows;
-export {};