dsh-auto-flow 0.1.1 → 0.1.2

package/lib/index.d.ts

@@ -1,134 +1,212 @@
-import { ExecKillResult, ExecReadResult, ExecRequest, ExecResult, Greeting } from "./types.js";
+import { E as ScriptInfo, F as WorkflowListRouteModelsResult, I as WorkflowListRunsRequest, N as WorkflowListLlmRoutesResult, P as WorkflowListRouteModelsRequest, S as RunState, j as WorkflowDefinition, l as FlowSummary, o as FlowGraph, r as FlowDataValue, w as RunSummary } from "./types-B4zlU2vb.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import z from "@deepseek-ai/schemastery";
-//#region src/index.d.ts
-/** dsh-auto-flow 的插件配置。 */
+//#region src/host/config.d.ts
+/** 插件配置。 */
 interface Config {
-  /** 问候前缀。 */
-  prefix?: string;
-  /** 单条 `exec` 命令允许的最大 UTF-8 字节长度。 */
-  maxCommandBytes?: number;
+  /** 工作流运行产物根目录。 */
+  workspaceDir?: string;
+  /** AI 智能体节点的子代理递归深度上限（非负安全整数；0 禁止委托）。 */
+  maxAgentDepth?: number;
+  /** 运行日志保留天数（正整数）。 */
+  runLogRetentionDays?: number;
 }
+//#endregion
+//#region src/host/service.d.ts
+/** 一次运行的结算结果（模型工具 workflow_run 消费）。 */
+interface RunOutcome {
+  runId: string;
+  ok: boolean;
+  /** Output 节点的最终值（无 output 节点时为 undefined）。 */
+  result?: FlowDataValue | undefined;
+  error?: string | undefined;
+  steps: RunState['steps'];
+}
+/**
+ * playwright-ag 的运行时契约（最小面）：本插件经 ctx.get('playwrightAg') 消费，不硬依赖其包。
+ * 这是 playwright-ag host 服务 `run`/`listScripts` 的镜像，真源在其 src/host/service.ts 与
+ * src/types.ts（ScriptResult/ScriptMeta）——两侧保持结构化同步，改动时须一起改。
+ */
+interface PlaywrightAgContract {
+  /** 进程内运行（非 @Remote）：可带 AbortSignal，取消时穿透关闭浏览器会话。 */
+  runScript(script: string, payload: Record<string, FlowDataValue>, options?: {
+    baseDir?: string | undefined;
+    runId?: string | undefined;
+    browser?: {
+      headless?: boolean;
+      channel?: string;
+    } | undefined;
+    timeoutMs?: number | undefined;
+  }, signal?: AbortSignal | undefined): Promise<ScriptResultWire>;
+  listScripts(): Promise<ScriptInfo[]>;
+}
+/** ScriptRunMeta 的镜像（真源 playwright-ag src/types.ts）。 */
+type ScriptRunMetaWire = {
+  startedAt: number;
+  finishedAt: number;
+  durationMs: number;
+};
+/** ScriptResult 的镜像：必须无损——meta（耗时）与 error.code（稳定错误码）不得丢弃。 */
+type ScriptResultWire = {
+  ok: true;
+  script: string;
+  data: FlowDataValue;
+  meta: ScriptRunMetaWire;
+} | {
+  ok: false;
+  script: string;
+  error: {
+    code: string;
+    message: string;
+  };
+  meta: ScriptRunMetaWire;
+};
 declare module '@deepseek-ai/cordis' {
   interface Context {
-    /** 示例服务（Host 提供，浏览器经 @Remote 调用）。 */
+    /** Host 提供服务，浏览器经 @Remote 调用。 */
     autoFlow: AutoFlowService;
+    /** 浏览器自动化脚本服务（playwright-ag 插件），缺失时 runFlow 报错。 */
+    playwrightAg?: PlaywrightAgContract;
   }
-  interface Events {
-    /**
-     * 一次问候已提交（域事件，跨插件实时通知 seam）。发出方在 `send` 提交后
-     * emit；其它插件可 `ctx.on('autoFlow/recorded', ...)` 订阅。
-     * @mode emit
-     */
-    'autoFlow/recorded'(payload: {
-      readonly greeting: Greeting;
-    }): void;
-  }
-}
-/**
- * 消息来源归属（MessageSourceMap）示例：若本插件要让「模型消息」归属到自己
- * （如经 `exec.deferContext` 注入的用户消息），在此新增一个 kind 并在
- * UserMessage.source 里使用。问候走会话事件而非模型消息，故此处仅声明词汇、
- * 不强制接线（参考 @deepseek-ai/dsh-goal 的 goal 来源声明）。
- */
-declare module '@deepseek-ai/dsh-llm' {
-  interface MessageSourceMap {}
 }
 /**
- * 示例服务：类本身就是插件——static inject / Config 是 Cordis 类插件的约定，
- * 构造器里的注册（工具/事件/设置/命令）随插件卸载自动回收。
- *
- * 平台服务消费方式（跨插件协作走 Cordis 服务、禁止互相 import）：
- * - 必需依赖用 `static inject`（tools）；
- * - 可选依赖用 `ctx.inject([...], cb)`（settings / commands / systemPrompt /
- *   autoFlowFormatter）——服务缺失时插件照常加载；
- * - shell / sandboxPolicy 是可选服务：用 `ctx.get(...)` 读取，未组合时
- *   `exec` 报错、插件其余部分照常工作；
- * - 持久层异步打开走 `[Service.init]`（storageDomain 可选：缺省退化为内存态）。
+ * 服务类即插件。依赖消费约定：
+ * - 可选依赖用 ctx.inject（settings），缺失照常加载；
+ * - storageDomain 是硬依赖，[Service.init] 缺失时大声失败（不静默内存态）；
+ * - playwrightAg 用 ctx.get 读取，未组合时 runFlow 报 playwright-missing；
+ * - 持久层在 [Service.init] 异步打开。
  */
 declare class AutoFlowService extends TypertRemoteService {
-  /** 依赖的服务；缺失时 Loader 会等待其出现。 */
-  static inject: string[];
-  /** Config 的 Schema（Cordis 类插件约定：Loader 读类静态 `Config` 校验注入并补齐默认值；
-   * 模块级同名导出不会被 Loader 识别——生成插件请把 Schema 放在类上）。 */
+  /** Config 的 Schema。Cordis 约定：Loader 读类静态 Config，请放在类上（模块级同名导出不会被识别）。 */
   static Config: z<Config>;
   /** 校验后的配置（settings scope 可在运行时覆盖，故非 readonly）。 */
   private resolved;
-  /** 问候的内存视图（domain storage 是持久层）。 */
-  private readonly greetings;
-  /** 已打开的持久化领域；无后端时保持 null（内存态兜底）。 */
+  /** 已打开的持久化领域；未组合 storageDomain 时保持 null。 */
   private storage;
-  /** 第二包提供的格式化服务；未安装第二包时保持 null（可选依赖）。 */
-  private formatter;
-  /** 最近一次提交的问候（由 `autoFlow/recorded` 监听器维护，供 @Remote last）。 */
-  private lastRecorded;
-  /** 后台进程句柄（@Remote 轻执行自管；不依赖 ctx.jobs，见 exec 说明）。 */
-  private readonly background;
-  private nextBgId;
-  private nextId;
+  /** 运行中的工作流运行时（runId → 状态 + 审批放行句柄）；终态后回收。 */
+  private readonly runRuntimes;
+  /** 进行中运行的中止控制器（runId → AbortController）；cancelRun 触发，终态回收。 */
+  private readonly runControllers;
+  /** 插件自持的运行日志（追加式按天 JSONL；终态 settled 记录只写一次）。 */
+  private runStore;
+  /** 已追加进运行日志的 runId（终态 append 幂等守卫）。 */
+  private readonly persistedRunIds;
+  /** 进行中的终态追加（runId → append Promise）；结算返回前 await 它保证落盘先于结算。 */
+  private readonly pendingPersists;
   constructor(ctx: Context, config?: Config);
-  /**
-   * 异步初始化钩子（Cordis 类插件约定）：构造完成后运行。持久层在这里打开——
-   * 与 @deepseek-ai/dsh-message-feedback 的 `[Service.init]` 同构；storageDomain
-   * 是可选服务，缺失时保持内存态兜底。
-   */
+  /** 异步初始化：打开持久层。storageDomain 是本插件硬依赖——缺失时大声失败，
+   * 不静默退化成内存态（否则 saveFlow 假装成功但重启即丢数据，是数据丢失陷阱）。 */
   protected [Service.init](): Promise<void>;
-  /** 模型工具：复用 @Remote send；presentCall + presentResult 双态展示。 */
-  private registerTool;
-  /** 设置：同一份 Config schema 注册为可编辑 namespace，入口配置作为 base 层。 */
+  /** 把同一份 Config schema 注册为可编辑的 settings namespace。 */
   private registerSettings;
-  /** 从持久化领域恢复内存视图与自增 id。 */
-  private hydrateFromStorage;
-  /** 斜杠命令：用户键入 /auto-flow 后直接进 handler（不经过模型）。 */
-  private registerCommand;
-  /** 系统提示词：贡献一条模型可见指引（name 唯一、order 升序拼接）。 */
-  private registerSystemPrompt;
-  /** 事件：监听自身域事件维护 lastRecorded 缓存（演示 ctx.on —— 监听器随 fiber 回收）。
-   * 其它插件也可 ctx.on('autoFlow/recorded', ...) 订阅，实现跨插件实时通知。 */
-  private registerEvents;
-  /** 卸载时回收所有未结束的后台进程（@Remote 轻执行自管句柄，必须随 fiber 清理）。 */
-  private registerBackgroundCleanup;
-  /** 跨插件服务消费：第二包（dsh-auto-flow-core）可选提供 autoFlowFormatter。
-   * 用 ctx.inject 而非 static inject——第二包未安装时插件照常加载（send 走无格式化兜底）。 */
-  private registerCore;
+  /** 卸载时中止在飞运行并关闭已打开的领域（Domain 句柄由调用方持有并按 effect 回收）。 */
+  private registerStorageCleanup;
+  /** 依据当前 resolved 配置重建运行日志（workspaceDir / 保留期变更时随之重建）。 */
+  private rebuildRunStore;
+  /** 列举全部工作流摘要（id + 名称 + 描述 + 节点数 + 输入键；按 id 升序）。 */
+  listFlows(): Promise<FlowSummary[]>;
+  /** 列举历史运行摘要（按 updatedAt 倒序，来自插件自持运行日志；支持按会话/工作流过滤，含归属标签）。
+   * @param request - 可选过滤：发起会话与工作流（两个条件可同时使用）。 */
+  listRuns(request: WorkflowListRunsRequest): Promise<RunSummary[]>;
+  /** 按 id 读取工作流文档（不存在或未组合 storageDomain 时返回 null）。 */
+  loadFlow(flowId: string): Promise<WorkflowDefinition | null>;
+  /** 按 id 保存工作流文档（domain 打开时落盘，否则仅返回原样；失败大声抛出）。 */
+  saveFlow(flowId: string, flow: WorkflowDefinition): Promise<WorkflowDefinition>;
+  /** 按 id 删除工作流。 */
+  deleteFlow(flowId: string): Promise<{
+    deleted: boolean;
+  }>;
+  /** 列出可运行脚本清单（展示名/描述/参数/产物装配规则；playwright-ag 为准，缺失时返回空）。 */
+  listScripts(): Promise<ScriptInfo[]>;
+  /** 列出实时 LLM 模型路由（llm/vision/agent 节点的 provider 下拉）。 */
+  listLlmRoutes(): WorkflowListLlmRoutesResult;
+  /** 列出某实时模型路由上的模型目录（llm/vision/agent 节点的 model 下拉）。 */
+  listRouteModels(request: WorkflowListRouteModelsRequest): Promise<WorkflowListRouteModelsResult>;
+  /**
+   * 启动一次工作流运行（@Remote，画布触发）：按层级并发执行 表单→脚本→审批，审批经画布 approveRun/cancelRun 放行。
+   * 返回 runId 即返回，进度经 runState 轮询；校验失败抛 invalid-flow（含诊断项）。
+   * sessionId 用于把产物落到「当前会话工作区」（缺省回退配置 workspaceDir）。
+   */
+  runFlow(request: {
+    flow: FlowGraph;
+    workflowId?: string;
+    name?: string;
+    sessionId?: string;
+  }): Promise<{
+    runId: string;
+  }>;
+  /** 解析本次运行应写入的工作区根目录：优先触发会话的 header.cwd，否则配置 workspaceDir 兜底。 */
+  private resolveWorkspaceRoot;
+  /**
+   * 启动一次运行并返回结算句柄（宿主内部，供 @Remote runFlow 与模型工具共用）。
+   * @param flow 画布（本方法负责校验）。
+   * @param waitApproval 审批等待器工厂 (runtime, step, options) => Promise<string>（返回选中的选项标签）。
+   * @param runContext 运行归属与触发方：workflowId/name/sessionId 是运行记录归属标签；
+   *   workspaceRoot 是产物根目录（缺省配置 workspaceDir）；有 parent 且部署有 subagents 时
+   *   AI 智能体节点才可用；recordSession 存在时把 auto-flow/* 运行事实追加为会话事件（会话进度）；
+   *   depth 是调用工作流节点的嵌套深度。
+   */
+  private startRun;
+  /** 画布审批等待器：挂起直至 approveRun/cancelRun 放行；30 分钟无人处理则自动取消。 */
+  private canvasWaitApproval;
+  /** 审批提问等待器：经 userQuestions 交互卡片让用户选择；无交互 UI 时回退画布审批。 */
+  private chatWaitApproval;
+  /**
+   * 调用工作流节点（硬→硬复用）的嵌套运行：加载目标工作流、合并 args、复用本运行的
+   * parent/session/signal 再跑一次 startRun，并把其 Output 值作为节点结果回灌。
+   * @param workflowId 目标工作流 id。
+   * @param args 覆盖目标工作流表单默认值的运行参数。
+   * @param parent 外层运行的父代理（审批卡片与会话归属用）。
+   * @param recordSession 外层运行的会话记录目标（嵌套进度追加到同一会话）。
+   * @param signal 外层运行的取消信号（取消外层即中止嵌套运行）。
+   * @param depth 当前嵌套深度（0 = 顶层）；达到上限即拒绝，防无限递归。
+   */
+  private runNestedWorkflow;
+  /** 画布场景的嵌套审批上抛：把嵌套运行加入根运行的上抛队列，画布经根 runId 即可看到/操作它。 */
+  private delegatedCanvasWaitApproval;
+  /** 供模型工具：按 flowId 加载并运行，args 覆盖表单默认值，等待完成返回结算结果。
+   *  同时把最近一条用户消息的图片/文本补填进缺失的 image/task 输入（会话上下文注入）。 */
+  runForAgent(flowId: string, args: Record<string, FlowDataValue>, agent: unknown, signal?: AbortSignal): Promise<RunOutcome>;
+  /** 把最近一条用户消息的图片/文本补填进运行参数（image/task）；无会话或已显式传入时原样返回。 */
+  private resolveSessionRunArgs;
+  /** 执行 /workflow 命令：不带参数列出工作流；/workflow <id> [key=value ...] 运行并等待结算。 */
+  runWorkflowCommand(invocation: {
+    agent: unknown;
+    rawInput: string;
+    signal: AbortSignal;
+  }): Promise<{
+    kind: 'success';
+    text?: string;
+  } | {
+    kind: 'error';
+    text: string;
+  }>;
+  /** 把 AI 智能体节点的子任务委托给子代理（LLM + 工具循环），返回最终文本。 */
+  private delegateToAgent;
+  /** 轮询运行状态（内存权威；未在内存中时读运行日志兜底）。 */
+  runState(runId: string): Promise<RunState | null>;
+  /** 取消运行：协作式取消，中止在飞的脚本/LLM/shell/HTTP，引擎在下一个步骤边界停下；若正等待审批则放行让引擎退出。
+   *  画布面向的根运行取消时会连带取消其整个审批上抛队列中的嵌套运行。 */
+  cancelRun(runId: string): Promise<RunState>;
+  /** 审批选择：choice = 审批节点的某个选项标签；画布用根 runId 操作时，自动作用于当前待处理的嵌套审批（队首）。 */
+  approveRun(runId: string, choice: string): Promise<RunState>;
   /**
-   * 追加一条问候并返回记录（写透 domain storage；若有第二包则先格式化；提交后发域事件）。
-   *
-   * 不追加自定义会话事件：harness 的 session 持久化读路径会拒绝 `KNOWN_SESSION_EVENT_TYPES`
-   * 之外的事件类型（除非信封标记 `ignorable`，而 `Session.append` 无此参数），把插件
-   * 自定义事件写进会话日志会导致该会话在重启后无法打开。
+   * 解析运行时的「画布可见运行」：若传入的是画布面向的根 runId 且其审批上抛队列非空，
+   * 则返回队首待处理的嵌套运行（跳过已不再等待的残留项）；否则返回该运行时本身。
    */
-  send(text: string): Promise<Greeting>;
-  /** 返回全部问候记录（内存视图，已由 domain storage 水合）。 */
-  list(): Promise<Greeting[]>;
-  /** 返回最近一次提交的问候（由域事件监听器维护），首次提交前为 null。 */
-  last(): Promise<Greeting | null>;
+  private resolveRuntime;
   /**
-   * 执行一条命令行（宿主内经 ctx.shell，与 bash 工具同一执行器，绝不经过模型）。
-   * 输出只回调用方、不进会话日志。@Remote 严格契约保证浏览器端完整类型与校验。
-   *
-   * 相比模型工具（@deepseek-ai/dsh-tool-bash）的 shell 面，@Remote 轻执行只能拿到
-   * 能映射过来的子集：timeoutMs / stdoutMaxBytes / sandboxPolicy / 后台任务 / 结果保真。
-   * 模型工具专属的 seam（shellEnv.collect 需要 ToolExecution、sandbox 升级需要 approval
-   * + callId、abort 需要 ToolExecution.signal）不适用于 @Remote，此处不做。
-   *
-   * 注意：@Remote 方法不能带 `agent: Agent` 参数——第三方仓库的 typert 生成器无法解析
-   * `agent` lookup（其 wire 类型 SessionId 是 branded 类型，官方 monorepo 内才可用）。
-   * 因此沙箱策略退化为「部署默认」（`sandboxPolicy.resolve()` 无 session）。
-   *
-   * 后台执行不走 ctx.jobs（那是给模型工具 job_output/job_kill 用的，需要 agent owner +
-   * dsh-tool-jobs 控制器，@Remote 里拿不到）：直接用 `shell.start()` 拿 ShellProcess
-   * 句柄，自管在 this.background Map 里，execRead/execKill 直接操作句柄；卸载时统一 kill。
-   *
-   * shell / sandboxPolicy 是可选依赖：未组合时抛对应 RemoteError，插件其余照常。
+   * 从审批上抛队列中取出当前应处理的运行时：
+   * - 若传入的是被上抛的嵌套运行时（有反向指针），从根的队列里移除自身并返回自身；
+   * - 若传入的是根运行，取出并返回队首嵌套运行，队列为空时返回根自身。
    */
-  exec(request: ExecRequest): Promise<ExecResult>;
-  /** 读后台进程的下一次增量/终态输出（自管 ShellProcess 句柄，不依赖 ctx.jobs）。 */
-  execRead(jobId: string): Promise<ExecReadResult>;
-  /** 请求取消后台进程（自管 ShellProcess 句柄，不依赖 ctx.jobs）。 */
-  execKill(jobId: string): Promise<ExecKillResult>;
+  private takePendingApproval;
+  /** 清除审批等待超时定时器（放行/驳回/终态时调用）。 */
+  private clearApprovalTimer;
+  private failRun;
+  private persistRun;
 }
 //#endregion
-export { AutoFlowService, AutoFlowService as default, Config };
+export { AutoFlowService as default };
 //# sourceMappingURL=index.d.ts.map