dsh-auto-flow 0.1.2 → 0.1.3

package/lib/index.d.ts

@@ -1,19 +1,127 @@
-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 { Q as RunSummary, X as RunState, _t as ScriptResult, dt as WorkflowListRouteModelsResult, f as FlowDataValue, ft as WorkflowListRunsRequest, g as FlowGraph, gt as ScriptPayload, lt as WorkflowListLlmRoutesResult, n as UnitEntryResult, rt as ScriptSourceInfo, st as WorkflowDefinition, t as RetryPlanSummary, tt as ScriptInfo, ut as WorkflowListRouteModelsRequest, vt as ScriptRunOptions, y as FlowSummary } from "./types-B5z-T_7S.js";
+import { Context, Service, Volatile } from "@deepseek-ai/cordis";
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import z from "@deepseek-ai/schemastery";
 //#region src/host/config.d.ts
+/** 一个脚本来源（哪个服务提供脚本、以及它在限定名/UI 里叫什么）。 */
+interface ScriptProviderConfig {
+  /** 提供脚本的 Cordis 服务名（`ctx.get(<service>)`），如 ag / playwrightBg。 */
+  service: string;
+  /** 来源 id：限定名的第一段与脚本身份的一部分（稳定、可路由，改它等于改身份）。 */
+  id?: string;
+  /** 来源展示名（UI 一级分类标题）；缺省用 id。 */
+  label?: string;
+}
+/**
+ * 一个用户脚本目录（外部用户自己写的本地脚本）。
+ *
+ * 目录里放 `scripts.json` 清单声明**入口**（只有入口是脚本，`lib/*.ts` 等只是被依赖的模块）。
+ * 用户脚本以**独立子进程**运行（经 `ctx.shell`，因此自带沙箱/超时/进程树回收），
+ * 与宿主内置脚本互不影响；代价是拿不到宿主的浏览器会话与站点凭证。
+ */
+interface UserScriptDirConfig {
+  /** 目录路径（绝对路径，或相对进程工作目录）。 */
+  dir: string;
+  /** 来源 id（限定名第一段）；缺省由目录名派生（小写、非字母数字转 `-`）。 */
+  id?: string;
+  /** 来源展示名（UI 一级分类标题）；缺省用 id。 */
+  label?: string;
+}
 /** 插件配置。 */
 interface Config {
-  /** 工作流运行产物根目录。 */
-  workspaceDir?: string;
+  /**
+   * 工作流运行产物根目录。
+   *
+   * 标了 volatile：它是设置页唯一可写字段，Settings 只允许写 volatile 路径，且
+   * `describe()` 只投影 volatile 字段（客户端设置行读的正是它）。Loader 解析后这里
+   * 是可读当前值的引用；改设置无需重启，每次读取经 `.get()` 取最新值。
+   */
+  workspaceDir?: Volatile<string>;
   /** AI 智能体节点的子代理递归深度上限（非负安全整数；0 禁止委托）。 */
   maxAgentDepth?: number;
   /** 运行日志保留天数（正整数）。 */
   runLogRetentionDays?: number;
+  /**
+   * 审批等待的**全局**超时（毫秒，不小于 {@link MIN_APPROVAL_TIMEOUT_MS}）。
+   *
+   * 缺省 {@link APPROVAL_GLOBAL_TIMEOUT_MS}。这个值同时决定两件事：宿主计时器何时放弃这次等待，
+   * 以及暂停实体上记录的 `globalDeadline`（过期之后任何恢复入口都必须拒绝它）。
+   */
+  approvalTimeoutMs?: number;
+  /**
+   * 单次运行最多执行多少个步骤（正整数；缺省 {@link DEFAULT_MAX_RUN_STEPS}）。
+   *
+   * 超出即停止整轮，停止原因写进运行记录（`AUTO_FLOW_LIMIT_EXCEEDED`）。
+   */
+  maxRunSteps?: number;
+  /**
+   * 单次运行最长墙钟毫秒（正整数；缺省 {@link DEFAULT_MAX_RUN_WALL_CLOCK_MS}）。
+   */
+  maxRunWallClockMs?: number;
+  /**
+   * 脚本节点并发上限（{@link MIN_RUN_CONCURRENCY}..{@link MAX_RUN_CONCURRENCY}；
+   * 缺省 = 引擎缺省 {@link MAX_CONCURRENCY}）。
+   */
+  maxRunConcurrency?: number;
+  /**
+   * 脚本来源清单（顺序 = UI 一级分类顺序）。每个来源经 `ctx.get(service)` 取，
+   * 并统一负责「外部用限定名（来源/脚本名）、provider 用库内名」的拆装。
+   * 缺省 = 单来源 ag，行为与本次改造前完全一致（脚本名不加前缀地兼容旧写法）。
+   */
+  scriptProviders?: ScriptProviderConfig[];
+  /**
+   * 外部用户脚本目录（缺省/空数组 = 关闭该能力）。每个目录成为一个来源分组，
+   * 见 {@link UserScriptDirConfig}；目录里必须有 `scripts.json` 清单。
+   */
+  userScriptDirs?: Array<string | UserScriptDirConfig>;
+  /** 用户脚本单次运行的超时（毫秒；非正数 → 用默认值）。 */
+  userScriptTimeoutMs?: number;
 }
+/**
+ * 配置 schema：Loader 校验的类静态 Config 就是这个值（见 service.ts 的 static Config）。
+ *
+ * 输入侧泛型只能是 `any`：schemastery 推导出的输入类型是 `ObjectS<…> & Dict`，其中 `Dict` 来自
+ * cosmokit，无法在生成的 .d.ts 里被命名（TS2883，tsdown 构建会失败）。输出侧仍由 {@link Config}
+ * 精确约束，故插件内所有取值都有类型。上游 agent-default-model 干脆不写注解，本包因要导出
+ * schema 而必须写，故退到这一层。
+ *
+ * `workspaceDir` 的 `.volatile()` 是设置页可写的前提；`.min(1)` 则把「空目录」挡在写入/加载处
+ * （原先由 installSection 的 validate 钩子做，该钩子已随 installSection 一起被上游删除）。
+ */
+declare const Config: z<any, Config>;
 //#endregion
-//#region src/host/service.d.ts
+//#region src/host/features/scripts/registry.d.ts
+/** 一个来源 + 它的运行面（provider 契约的结构化最小面）。 */
+interface ScriptProvider {
+  /** 来源身份：限定名的前缀、UI 一级分类。 */
+  source: ScriptSourceInfo;
+  /**
+   * 本库脚本清单（`name` 是**库内名**，不含来源前缀）。
+   *
+   * 类型取 `ScriptInfo`（脚本在工作流里的**消费侧视图**）而不是线格式 `ScriptMeta`：
+   * 用户脚本清单是**不可信输入**（`userScriptDirs` 下的 JSON 由用户写），
+   * `params[].children` 可能缺 —— 消费侧视图里它是可选，线格式里必填。
+   * 两侧的分歧已由 `packages/shared/policy.facts.json` 的 `contractDivergence` 登记。
+   */
+  listScripts(): Promise<ScriptInfo[]>;
+  /**
+   * 按**库内名**运行。调用方传入的限定名已由本注册表拆掉前缀。
+   *
+   * 参数用契约真源类型（而不是 `Record<string, unknown>`）：两个实现（插件服务、用户脚本目录）
+   * 本来就拿得到真类型，中间接口擦成 `unknown` 只会逼调用点在接缝上写 `as`。
+   */
+  runScript(script: string, payload: ScriptPayload, options?: ScriptRunOptions, signal?: AbortSignal | undefined): Promise<ScriptResult>;
+}
+/** 解析成功：限定名 + 该由谁跑 + 用什么库内名跑。 */
+interface ResolvedScript {
+  /** 对外身份（限定名）。 */
+  qualified: string;
+  provider: ScriptProvider;
+  /** provider 内的脚本名（拆掉来源前缀）。 */
+  localName: string;
+}
+//#endregion
+//#region src/host/contracts.d.ts
 /** 一次运行的结算结果（模型工具 workflow_run 消费）。 */
 interface RunOutcome {
   runId: string;
@@ -24,110 +132,200 @@ interface RunOutcome {
   steps: RunState['steps'];
 }
 /**
- * playwright-ag 的运行时契约（最小面）：本插件经 ctx.get('playwrightAg') 消费，不硬依赖其包。
- * 这是 playwright-ag host 服务 `run`/`listScripts` 的镜像，真源在其 src/host/service.ts 与
- * src/types.ts（ScriptResult/ScriptMeta）——两侧保持结构化同步，改动时须一起改。
+ * 【为什么本包**不**声明 `Context.ag` / `Context.playwrightBg`】官方 dsh 的惯例是
+ * **每个插件声明自己的槽位**（实测官方包：`Context.agents: AgentRegistry`、
+ * `agentLoop: AgentLoop`、`typertGateway: TypertGateway`），**消费方不替供应方声明**。
+ *
+ * 此前本包写了 `ag?: ScriptProviderContract`，而 `dsh-ag` 自己写的是 `ag: AgService` ——
+ * 同一个 key 两处不同类型，实测放进同一个 TS 程序会报 `TS2717` + `TS2687`，
+ * 今天不报只是因为业务包互不依赖、永远不在同一个程序里。
+ *
+ * 删掉本包的声明后：冲突从根上消失（不是「改成一致」，是**根本没有第二处声明**），
+ * 而且对**任意数量**的供应方都成立 —— 加一个 `bg` 不需要回来改这里。
+ * 读供应方一律走 {@link scriptProviderOf}。
  */
-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 调用。 */
     autoFlow: AutoFlowService;
-    /** 浏览器自动化脚本服务（playwright-ag 插件），缺失时 runFlow 报错。 */
-    playwrightAg?: PlaywrightAgContract;
   }
 }
+//#endregion
+//#region src/host/service.d.ts
 /**
  * 服务类即插件。依赖消费约定：
  * - 可选依赖用 ctx.inject（settings），缺失照常加载；
  * - storageDomain 是硬依赖，[Service.init] 缺失时大声失败（不静默内存态）；
- * - playwrightAg 用 ctx.get 读取，未组合时 runFlow 报 playwright-missing；
+ * - ag 用 ctx.get 读取，未组合时 runFlow 报 ag-missing；
  * - 持久层在 [Service.init] 异步打开。
  */
 declare class AutoFlowService extends TypertRemoteService {
-  /** Config 的 Schema。Cordis 约定：Loader 读类静态 Config，请放在类上（模块级同名导出不会被识别）。 */
-  static Config: z<Config>;
-  /** 校验后的配置（settings scope 可在运行时覆盖，故非 readonly）。 */
-  private resolved;
+  /** Config 的 Schema。Cordis 约定：Loader 读类静态 Config，请放在类上（模块级同名导出不会被识别）。
+   *  输入侧 any 的理由见 config.ts 的 Config 注释（`Dict` 无法在 .d.ts 中命名）。 */
+  static Config: z<any, Config>;
+  /** Loader 解析后的配置。volatile 字段是运行期可读的引用，故每次用时重新解析。 */
+  private readonly config;
   /** 已打开的持久化领域；未组合 storageDomain 时保持 null。 */
   private storage;
-  /** 运行中的工作流运行时（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;
+  /** 运行态注册表：运行时句柄 / 取消控制器 / 运行日志 / 终态持久化。 */
+  private readonly runs;
+  /** 脚本目录与注册表：内置脚本来源 + 用户脚本目录。 */
+  private readonly catalog;
+  /** 运行编排：起运行 / 审批 / 嵌套 / Agent 委派 / 取消放行。 */
+  private readonly coordinator;
+  /**
+   * 应用单元入口结果（单元名 → 该单元的入口结果）；空表 = 宿主没有信任门，根本没有去挂单元。
+   *
+   * 【为什么存 Promise 而不是地址】地址要等单元服务监听就绪才知道（端口可能来自本地开发配置），而
+   * 客户端半边每次打开浮层只问一次、并把"给不出地址"当终态：若把"还没就绪"也写成失败，宿主刚起来那
+   * 一下点开就会被永久判成"没有入口"。存 Promise 让那一次询问等到结果（失败折成带原因的结果）。
+   */
+  private unitEntries;
+  /** 「宿主没有信任门」这条 warn 是否已经记过（每次打开浮层都会走到那条分支，故只记一次）。 */
+  private warnedNoGate;
   constructor(ctx: Context, config?: Config);
+  /**
+   * 按当前配置归一化一次。
+   *
+   * 每次调用都从 volatile 引用取最新值，所以设置页改完立刻生效 —— 调用方不要缓存结果，
+   * 需要时现取（各消费点拿到的都是 `() => this.currentResolved()` 这样的取值闭包）。
+   */
+  private currentResolved;
+  /**
+   * 解析脚本名 → 具体来源与库内名（限定名优先，其次唯一命中的库内名）。
+   * 实现在 features/scripts/catalog.ts；此方法保持公开，因为模型工具与测试都从服务面取它。
+   */
+  resolveScript(name: string): Promise<ResolvedScript | undefined>;
   /** 异步初始化：打开持久层。storageDomain 是本插件硬依赖——缺失时大声失败，
    * 不静默退化成内存态（否则 saveFlow 假装成功但重启即丢数据，是数据丢失陷阱）。 */
   protected [Service.init](): Promise<void>;
-  /** 把同一份 Config schema 注册为可编辑的 settings namespace。 */
+  /**
+   * 声明本插件的设置展示策略。
+   *
+   * 上游 0.2.0-rc.2 删掉了 `installSection`：插件的 Config schema 由 Loader 持有，Settings
+   * 扫描已装插件自动出表单，插件侧只剩「展示策略」要声明。`auto: false` = 本插件自带设置行
+   * （见 src/client/apply.ts 注册的 `settings.general.item`），不要再自动生成一个页面。
+   *
+   * 配置热生效**不在这里**：靠 Config 上 `workspaceDir` 的 `.volatile()` 与读取时的
+   * `.get()`（见 currentResolved），所以本方法不再持有 onChange / readConfig 之类状态。
+   */
   private registerSettings;
   /** 卸载时中止在飞运行并关闭已打开的领域（Domain 句柄由调用方持有并按 effect 回收）。 */
   private registerStorageCleanup;
-  /** 依据当前 resolved 配置重建运行日志（workspaceDir / 保留期变更时随之重建）。 */
-  private rebuildRunStore;
+  /**
+   * 挂载本插件的前端应用单元（登记表在 `src/app-units.ts`，装配在 `features/app-unit/mount.ts`）。
+   *
+   * 【为什么用 `ctx.inject` 而不是硬依赖 connection】单元服务要宿主提供"给入口 HTML 加门"的能力
+   * （平台 connection 的进程令牌与签名 cookie）；有些宿主组合（例如桌面端走 `file://` + IPC）没有这个
+   * 服务 —— 缺失时插件照常加载，只是没有那个整页面板（`unitUrl` 给出原因），其余能力不受影响。
+   *
+   * 【为什么依赖表逐个列在这里而不是把服务交给 BFF】BFF 走的是进程内直取（不经 `{ ok, value }` 信封
+   * 那条通道），它能取到什么**只由这张表决定**；漏接一个编译期就红，不会拖到运行时才发现某个面板
+   * 功能是空的。
+   *
+   * 【为什么不在回调里 await 单元就绪】端口被占用属于环境问题：它不该让整个插件（含模型工具与斜杠
+   * 命令）加载失败。故失败只走"这个单元没起来"这一条通道：结果里带原因，宿主日志留一条 warn。
+   *
+   * 【加一个单元不再需要改这里】这里只有**一次**通用挂载调用：它按登记表把全部单元各挂一份。
+   */
+  private registerAppUnits;
+  /**
+   * 某个应用单元的入口结果（带进程令牌的地址，或一条给面板看的原因）。
+   *
+   * 客户端半边把地址当 iframe 的 `src`：地址里带着进程令牌，单元服务据此换出 HttpOnly cookie
+   * （见 `app-unit` 的 README 的门一节）。
+   *
+   * 【为什么是 async】等单元就绪再回答 —— 见 `unitEntries` 字段的注释：客户端每次打开浮层只问一次，
+   * 把"还没就绪"也当成"没有入口"会让宿主刚起来那一下点开被永久判错。
+   *
+   * 【为什么按单元名问】会话面板里有几个入口就有几个单元（清单见 `src/client/dock-units.ts`）：地址只由
+   * 询问方决定，宿主不替它挑一个。客户端半那边用的是**单元名的字面量**（它不许 import 登记表），与登记表
+   * 的对应由 `tests/client/apply.spec.tsx` 的一条断言守住；这里再判一次"在不在登记表里" —— 那一档的
+   * 原因要能让用户自查。
+   *
+   * @param unit - 单元名（登记表 `APP_UNITS` 的键）。
+   * @returns `{ url }` 或 `{ url: null, reason }`（缺前端、端口被占、本地开发配置非法…各自带原因与
+   *   处置命令）；宿主没有信任门、或这个名字不在登记表里时，各给一条说明。
+   *   **宿主没有信任门那一条在宿主日志留一条 warn。**
+   */
+  unitUrl(unit: string): Promise<UnitEntryResult>;
   /** 列举全部工作流摘要（id + 名称 + 描述 + 节点数 + 输入键；按 id 升序）。 */
   listFlows(): Promise<FlowSummary[]>;
   /** 列举历史运行摘要（按 updatedAt 倒序，来自插件自持运行日志；支持按会话/工作流过滤，含归属标签）。
    * @param request - 可选过滤：发起会话与工作流（两个条件可同时使用）。 */
   listRuns(request: WorkflowListRunsRequest): Promise<RunSummary[]>;
-  /** 按 id 读取工作流文档（不存在或未组合 storageDomain 时返回 null）。 */
+  /**
+   * 按 id 读取工作流文档（不存在或未组合 storageDomain 时返回 null）。
+   *
+   * 读时会把脚本节点的**库内名**规范化为限定名（见 `canonicalizeScriptNames`）—— 修的是
+   * 「同一脚本两个身份」这个病根，而不是在下拉那一个消费点上再打一次补丁。
+   */
   loadFlow(flowId: string): Promise<WorkflowDefinition | null>;
-  /** 按 id 保存工作流文档（domain 打开时落盘，否则仅返回原样；失败大声抛出）。 */
+  /**
+   * 按 id 保存工作流文档（domain 打开时落盘，否则仅返回原样；失败大声抛出）。
+   *
+   * 写时同样规范化：这是**保证不变量成立的那一步** —— 画布新建的工作流以示例种子起步，
+   * 而种子按设计存库内名（来源 id 是运行时配置，静态模板不能硬编码它），所以只有在落盘前
+   * 改写一次，存档里才会是规范形态。返回值是**实际落盘**的文档（不再是入参原样）。
+   *
+   * 【为什么这个入口**不**做语义校验】它是画布的自动保存（fire-and-forget）：半成品草稿
+   * 必须落盘 —— 一旦拦下，用户那次编辑就静默丢了（`useFlowAutosave` 是 `void` 调用，没人接
+   * 这个 rejection）。这里曾经调 `assertFlowValid`，于是「把某字段标成必填但还没填」「数值越界」
+   * 这类**编辑中的常态**会让整份文档存不进去，而界面上没有任何提示。
+   *
+   * 判据没有消失，只是换了承载者（同一份 `validateFlow`，强度按阶段分档）：
+   * - **展示**：画布客户端算同一份诊断并画成节点徽标 / 字段级提示（`useFlowDiagnostics`）；
+   * - **拒绝**：运行入口（`RunCoordinator`，失败有错误卡片承载）与模型工具 `workflow_save`
+   *   （错误回到模型手里，它可以改）各自显式调 `assertFlowValid`。
+   *
+   * @throws {Error} 规范化或存储层失败（domain 不可用、写盘出错）—— 这些是真失败，必须冒泡。
+   */
   saveFlow(flowId: string, flow: WorkflowDefinition): Promise<WorkflowDefinition>;
+  /**
+   * 语义校验入口：**委托给运行协调器的同一入口**（判据只有一处）。
+   *
+   * 调用方按阶段自己决定强度：模型工具 `workflow_save` 在写盘前调它（错误回到模型手里），
+   * 运行入口调它并带上脚本参数清单与环境能力集（失败有错误卡片承载）。
+   * 画布自动保存**不调**它 —— 理由见 `saveFlow` 的文档。
+   *
+   * @param flow - 待校验的文档（应当已经规范化）。
+   * @throws {RemoteError} `autoFlow/invalid-flow`（见 `RunCoordinator.assertFlowValid`）。
+   */
+  assertFlowValid(flow: WorkflowDefinition): Promise<void>;
+  /**
+   * 把文档里脚本节点的库内名规范化为限定名。
+   *
+   * **快路径（不碰脚本目录）**：文档里没有需要解析的库内名时直接返回原文档。判据只用同步可得
+   * 的信息（`scriptRegistry().sources()` 来自配置），因此「已经全是限定名」的文档（如 ygs
+   * 那几个）零额外开销，也不会因为脚本目录故障而受影响。
+   *
+   * **兜底必须有主**：脚本目录解析失败（来源服务缺失、`listScripts` 抛错、同来源内重名）时
+   * 返回**原文档**并放行。触发条件 = 脚本目录不可用；为什么在这里处理 = 目录的问题不该让
+   * 「打开工作流」失败；用户看到 = 工作流正常打开，下拉显示原名（客户端兜底负责）。
+   */
+  private canonicalize;
   /** 按 id 删除工作流。 */
   deleteFlow(flowId: string): Promise<{
     deleted: boolean;
   }>;
-  /** 列出可运行脚本清单（展示名/描述/参数/产物装配规则；playwright-ag 为准，缺失时返回空）。 */
+  /**
+   * 列出可运行脚本清单（展示名/描述/参数/产物装配规则 + 来源 + 加载诊断）。
+   *
+   * `name` 是**限定名**（`ag/xhs/collect`、`my-scripts/daily-report`），
+   * 来源是身份的一部分 —— 多个脚本库各有同名脚本时不会互相覆盖；`source` 供 UI 做一级分类。
+   * 未组合任何脚本来源时返回空（与改造前一致）。
+   */
   listScripts(): Promise<ScriptInfo[]>;
-  /** 列出实时 LLM 模型路由（llm/vision/agent 节点的 provider 下拉）。 */
+  /** 列出实时 LLM 模型路由（llm/agent 节点的 provider 下拉）。 */
   listLlmRoutes(): WorkflowListLlmRoutesResult;
-  /** 列出某实时模型路由上的模型目录（llm/vision/agent 节点的 model 下拉）。 */
+  /** 列出某实时模型路由上的模型目录（llm/agent 节点的 model 下拉）。 */
   listRouteModels(request: WorkflowListRouteModelsRequest): Promise<WorkflowListRouteModelsResult>;
   /**
    * 启动一次工作流运行（@Remote，画布触发）：按层级并发执行 表单→脚本→审批，审批经画布 approveRun/cancelRun 放行。
    * 返回 runId 即返回，进度经 runState 轮询；校验失败抛 invalid-flow（含诊断项）。
    * sessionId 用于把产物落到「当前会话工作区」（缺省回退配置 workspaceDir）。
    */
+  /** 画布触发运行（实现见 features/runs/coordinator.ts）：只等到「运行已启动」即返回 runId。 */
   runFlow(request: {
     flow: FlowGraph;
     workflowId?: string;
@@ -136,41 +334,36 @@ declare class AutoFlowService extends TypertRemoteService {
   }): 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 输入（会话上下文注入）。 */
+  /** 轮询运行状态（内存权威；未在内存中时读运行日志兜底）。 */
+  runState(runId: string): Promise<RunState | null>;
+  /** 取消运行（协作式；画布根运行会连带取消其审批上抛队列里的嵌套运行）。 */
+  cancelRun(runId: string): Promise<RunState>;
+  /** 放行/驳回一个等待中的审批（宿主重启后会自动先恢复该运行，再应用这次答复）。 */
+  approveRun(runId: string, choice: string): Promise<RunState>;
+  /**
+   * 恢复一个暂停中的运行（宿主重启 / 进程被杀之后的续跑入口）。
+   *
+   * @param runId - 目标运行（磁盘上要有中途快照与未答复的暂停实体）。
+   * @returns 恢复后的运行状态（已在跑）。
+   */
+  resumeRun(runId: string): Promise<RunState>;
+  /**
+   * **重试未成功项**（与「重新运行」并列、行为可区分）。
+   *
+   * 读该运行的批次台账，算出没成功的业务键，只补做那些；正常执行不读台账。
+   * 无业务键的批次被**明确拒绝**（`autoFlow/batch-not-retryable`），不静默退化成按下标跳过。
+   *
+   * @param runId - 目标运行（终态记录或暂停态现场都行）。
+   * @returns 新运行的 runId + 本次计划（待补条数 / 跳过策略）。
+   * @throws `autoFlow/run-not-found` / `autoFlow/run-not-retryable` / `autoFlow/batch-not-retryable`。
+   */
+  retryRun(runId: string): Promise<{
+    runId: string;
+    plan: RetryPlanSummary;
+  }>;
+  /** 由模型工具触发一次工作流运行（实现见 features/runs/coordinator.ts）。 */
   runForAgent(flowId: string, args: Record<string, FlowDataValue>, agent: unknown, signal?: AbortSignal): Promise<RunOutcome>;
-  /** 把最近一条用户消息的图片/文本补填进运行参数（image/task）；无会话或已显式传入时原样返回。 */
-  private resolveSessionRunArgs;
-  /** 执行 /workflow 命令：不带参数列出工作流；/workflow <id> [key=value ...] 运行并等待结算。 */
+  /** /workflow 斜杠命令的处理器（实现见 features/runs/coordinator.ts）。 */
   runWorkflowCommand(invocation: {
     agent: unknown;
     rawInput: string;
@@ -182,30 +375,6 @@ declare class AutoFlowService extends TypertRemoteService {
     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>;
-  /**
-   * 解析运行时的「画布可见运行」：若传入的是画布面向的根 runId 且其审批上抛队列非空，
-   * 则返回队首待处理的嵌套运行（跳过已不再等待的残留项）；否则返回该运行时本身。
-   */
-  private resolveRuntime;
-  /**
-   * 从审批上抛队列中取出当前应处理的运行时：
-   * - 若传入的是被上抛的嵌套运行时（有反向指针），从根的队列里移除自身并返回自身；
-   * - 若传入的是根运行，取出并返回队首嵌套运行，队列为空时返回根自身。
-   */
-  private takePendingApproval;
-  /** 清除审批等待超时定时器（放行/驳回/终态时调用）。 */
-  private clearApprovalTimer;
-  private failRun;
-  private persistRun;
 }
 //#endregion
 export { AutoFlowService as default };