@dsh-workbench/shared 1.1.7 → 1.1.9

package/src/host/flow/run.ts

@@ -0,0 +1,325 @@
+import { evalPredicate, resolveInput, resolveValue } from './expr.js';
+import type {
+  FlowAction,
+  FlowActionContext,
+  FlowActionRegistry,
+  FlowActionStep,
+  FlowDefinition,
+  FlowResult,
+  FlowRunOptions,
+  FlowRetry,
+  FlowScope,
+  FlowStepEvent,
+  RegisteredFlowAction,
+} from './types.js';
+
+type Sleep = (ms: number, signal: AbortSignal) => Promise<void>;
+
+class StepFailure extends Error {
+  readonly stepId: string;
+
+  constructor(stepId: string, cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.name = 'StepFailure';
+    this.stepId = stepId;
+    this.cause = cause;
+  }
+}
+
+function abortError(): Error {
+  const error = new Error('流程已停止');
+  error.name = 'AbortError';
+  return error;
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === 'AbortError';
+}
+
+function defaultSleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    function onAbort(): void {
+      clearTimeout(timer);
+      resolve();
+    }
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function targetOf(flow: FlowDefinition, scope: FlowScope): string {
+  if (flow.target === undefined) return flow.id;
+  const value = resolveValue(flow.target, scope);
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : flow.id;
+}
+
+function stopped(steps: Readonly<Record<string, unknown>>, target: string): FlowResult {
+  return { status: 'stopped', target, steps };
+}
+
+/**
+ * 建一个内存里的动作注册表；每个流程运行时各有一份，没有模块级状态。
+ * @returns 注册表。
+ */
+export function createFlowActionRegistry(): FlowActionRegistry {
+  const entries = new Map<string, RegisteredFlowAction>();
+  return {
+    register(name, action, meta) {
+      const trimmed = name.trim();
+      if (trimmed === '') throw new Error('动作名不能为空');
+      entries.set(trimmed, { name: trimmed, action, meta: meta ?? {} });
+    },
+    get(name) {
+      return entries.get(name);
+    },
+    has(name) {
+      return entries.has(name);
+    },
+    list() {
+      return [...entries.values()];
+    },
+  };
+}
+
+async function callWithRetry(
+  action: FlowAction,
+  input: unknown,
+  context: FlowActionContext,
+  retry: FlowRetry | undefined,
+  sleep: Sleep,
+  signal: AbortSignal,
+  onAttempt?: (attempt: number) => void,
+): Promise<unknown> {
+  const attempts = Math.max(0, Math.min(5, Math.trunc(retry?.attempts ?? 0)));
+  const delayMs = Math.max(0, Math.min(60_000, Math.trunc(retry?.delayMs ?? 0)));
+  let last: unknown;
+  for (let attempt = 1; attempt <= attempts + 1; attempt += 1) {
+    if (signal.aborted) throw abortError();
+    onAttempt?.(attempt);
+    try {
+      return await action(input, context);
+    } catch (error) {
+      last = error;
+      if (signal.aborted) throw abortError();
+      if (attempt > attempts) break;
+      if (delayMs > 0) await sleep(delayMs, signal);
+    }
+  }
+  throw last;
+}
+
+interface RunOneOptions {
+  readonly step: FlowActionStep;
+  readonly title: string;
+  readonly stepId: string;
+  readonly scope: FlowScope;
+  readonly actions: FlowActionRegistry;
+  readonly signal: AbortSignal;
+  readonly runId: string;
+  readonly workspace: string;
+  readonly sleep: Sleep;
+  readonly now: () => number;
+  readonly emit: (event: FlowStepEvent) => void;
+}
+
+async function runOneInner(options: RunOneOptions): Promise<unknown> {
+  const { step, title, stepId, scope, actions, signal, runId, workspace, sleep, now, emit } =
+    options;
+  const entry = actions.get(step.action);
+  if (entry === undefined) throw new Error(`注册表里没有这个动作：${step.action}`);
+  const input = resolveInput(step.with, scope);
+  const context: FlowActionContext = {
+    signal,
+    runId,
+    workspace,
+    stepId,
+    log: (text) => {
+      emit({ stepId, title, status: 'running', message: text });
+    },
+    login: (url) => {
+      emit({ stepId, title, status: 'needs-login', loginUrl: url });
+    },
+  };
+
+  if (step.poll !== undefined) {
+    const everyMs = Math.max(100, Math.min(60_000, Math.trunc(step.poll.everyMs)));
+    const rawMax = Math.trunc(step.poll.maxMs);
+    const maxMs = rawMax === 0 ? 0 : Math.max(everyMs, Math.min(1_800_000, rawMax));
+    const startedAt = now();
+    let pollAttempt = 0;
+    for (;;) {
+      if (signal.aborted) throw abortError();
+      pollAttempt += 1;
+      emit({
+        stepId,
+        title,
+        status: 'running',
+        attempt: pollAttempt,
+        message: `第 ${pollAttempt} 次`,
+      });
+      const value = await callWithRetry(entry.action, input, context, step.retry, sleep, signal);
+      if (evalPredicate(step.poll.until, { ...scope, value })) return value;
+      if (maxMs > 0 && now() - startedAt >= maxMs) {
+        if (step.poll.onTimeout === 'continue') return undefined;
+        throw new Error(`步骤 ${step.id} 轮询超时（${maxMs}ms）`);
+      }
+      await sleep(everyMs, signal);
+    }
+  }
+
+  return callWithRetry(entry.action, input, context, step.retry, sleep, signal, (attempt) => {
+    emit({ stepId, title, status: 'running', attempt });
+  });
+}
+
+async function runOne(options: RunOneOptions): Promise<unknown> {
+  try {
+    return await runOneInner(options);
+  } catch (error) {
+    if (error instanceof StepFailure || isAbortError(error)) throw error;
+    throw new StepFailure(options.stepId, error);
+  }
+}
+
+/**
+ * 顺序跑一条流程：条件跳过、重试、轮询、逐项展开、子流程、取消；失败停在具体步骤。
+ * 不碰平台、不落盘；动作怎么实现由注册表决定。
+ * @param options 流程、输入、动作表、取消信号、身份与进度回调。
+ * @returns 成功 / 失败 / 停止；失败带 `failedStep`。
+ */
+export async function runFlow(options: FlowRunOptions): Promise<FlowResult> {
+  const { flow, input, actions, signal, runId, workspace, onStep } = options;
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? (() => Date.now());
+  const steps: Record<string, unknown> = {};
+  const emit = (event: FlowStepEvent): void => {
+    try {
+      onStep(event);
+    } catch {
+    }
+  };
+  const target = targetOf(flow, { in: input, steps });
+  const shouldStop = (): boolean =>
+    flow.stopWhen !== undefined && evalPredicate(flow.stopWhen, { in: input, steps });
+
+  if (shouldStop()) return { status: 'ok', target, steps };
+
+  for (const step of flow.steps) {
+    if (signal.aborted) return stopped(steps, target);
+    const title = step.title ?? step.id;
+    try {
+      if (shouldStop()) return { status: 'ok', target, steps };
+
+      if (step.when !== undefined && !evalPredicate(step.when, { in: input, steps })) {
+        emit({ stepId: step.id, title, status: 'skipped' });
+        if (shouldStop()) return { status: 'ok', target, steps };
+        continue;
+      }
+
+      if ('flow' in step) {
+        emit({ stepId: step.id, title, status: 'running' });
+        const subInput = resolveInput(step.with, { in: input, steps });
+        const nested = await runFlow({
+          flow: step.flow,
+          input: subInput,
+          actions,
+          signal,
+          runId: `${runId}/${step.id}`,
+          workspace,
+          onStep: (event) => {
+            emit({
+              ...event,
+              stepId: `${step.id}.${event.stepId}`,
+              title: `${title} / ${event.title}`,
+            });
+          },
+          sleep,
+          now,
+        });
+        if (nested.status === 'failed') {
+          const failed =
+            nested.failedStep === undefined ? step.id : `${step.id}.${nested.failedStep}`;
+          throw new StepFailure(failed, nested.error ?? new Error(`子流程失败在 ${failed}`));
+        }
+        steps[step.id] = nested.steps;
+        if (nested.status === 'stopped') return stopped(steps, target);
+        emit({ stepId: step.id, title, status: 'ok' });
+        if (shouldStop()) return { status: 'ok', target, steps };
+        continue;
+      }
+
+      if (step.forEach !== undefined) {
+        const over = resolveValue(step.forEach.over, { in: input, steps });
+        if (!Array.isArray(over)) {
+          throw new Error(`步骤 ${step.id} 的 forEach.over 不是数组`);
+        }
+        const max = Math.max(1, Math.min(50, Math.trunc(step.forEach.max)));
+        if (over.length > max) {
+          throw new Error(`步骤 ${step.id} 的 forEach 有 ${over.length} 项，超过上限 ${max}`);
+        }
+        const output: unknown[] = [];
+        for (const [index, item] of over.entries()) {
+          if (signal.aborted) return stopped(steps, target);
+          output.push(
+            await runOne({
+              step,
+              title,
+              stepId: `${step.id}[${index}]`,
+              scope: { in: input, steps, item },
+              actions,
+              signal,
+              runId,
+              workspace,
+              sleep,
+              now,
+              emit,
+            }),
+          );
+        }
+        steps[step.id] = output;
+        emit({ stepId: step.id, title, status: 'ok' });
+        if (shouldStop()) return { status: 'ok', target, steps };
+        continue;
+      }
+
+      steps[step.id] = await runOne({
+        step,
+        title,
+        stepId: step.id,
+        scope: { in: input, steps },
+        actions,
+        signal,
+        runId,
+        workspace,
+        sleep,
+        now,
+        emit,
+      });
+      emit({ stepId: step.id, title, status: 'ok' });
+      if (shouldStop()) return { status: 'ok', target, steps };
+    } catch (error) {
+      if (signal.aborted || isAbortError(error)) return stopped(steps, target);
+      if (error instanceof StepFailure) {
+        emit({ stepId: error.stepId, title, status: 'failed', message: error.message });
+        return {
+          status: 'failed',
+          target,
+          steps,
+          failedStep: error.stepId,
+          error: error.cause ?? error,
+        };
+      }
+      emit({ stepId: step.id, title, status: 'failed', message: String(error) });
+      return { status: 'failed', target, steps, failedStep: step.id, error };
+    }
+  }
+
+  return { status: 'ok', target, steps };
+}

package/src/host/flow/types.ts

@@ -0,0 +1,199 @@
+/**
+ * 一条流程：按顺序跑的步骤清单；步骤里的动作按名字从注册表取。
+ */
+export interface FlowDefinition {
+  readonly id: string;
+  readonly title: string;
+  readonly target?: FlowValue | undefined;
+  readonly stopWhen?: FlowPredicate | undefined;
+  readonly steps: readonly FlowStep[];
+}
+
+/**
+ * 重试：`attempts` 是额外次数，总共最多 6 次。
+ */
+export interface FlowRetry {
+  readonly attempts: number;
+  readonly delayMs?: number | undefined;
+}
+
+/**
+ * 轮询：每次调动作，`until` 判停；`maxMs: 0` 表示不限时。
+ * `onTimeout: 'continue'` 把 `undefined` 写进步骤结果，交给后面的 `when` 决定。
+ */
+export interface FlowPoll {
+  readonly everyMs: number;
+  readonly maxMs: number;
+  readonly until: FlowPredicate;
+  readonly onTimeout?: 'fail' | 'continue' | undefined;
+}
+
+/**
+ * 逐项展开：`over` 求成数组，每项用 `item` 作用域跑一次，最多 `max` 项。
+ */
+export interface FlowForEach {
+  readonly over: FlowValue;
+  readonly as: string;
+  readonly max: number;
+}
+
+/**
+ * 一步：调用一个注册表里的动作，可选重试、轮询、逐项展开。
+ */
+export interface FlowActionStep {
+  readonly id: string;
+  readonly title?: string | undefined;
+  readonly action: string;
+  readonly with?: Readonly<Record<string, FlowValue>> | undefined;
+  readonly when?: FlowPredicate | undefined;
+  readonly retry?: FlowRetry | undefined;
+  readonly poll?: FlowPoll | undefined;
+  readonly forEach?: FlowForEach | undefined;
+}
+
+/**
+ * 一步：跑另一条流程；`with` 求出来的对象就是子流程的 `in`，结果挂在 `steps.<id>` 下。
+ */
+export interface FlowSubFlowStep {
+  readonly id: string;
+  readonly title?: string | undefined;
+  readonly flow: FlowDefinition;
+  readonly with?: Readonly<Record<string, FlowValue>> | undefined;
+  readonly when?: FlowPredicate | undefined;
+}
+
+/**
+ * 一步要么调动作，要么跑子流程。
+ */
+export type FlowStep = FlowActionStep | FlowSubFlowStep;
+
+/**
+ * 步骤入参里的一个值：字面量、引用，或二选一。
+ * 引用只从 `in` / `steps` / `item` / `value` 起头；`value` 只在 `poll.until` 里。
+ */
+export type FlowValue =
+  | { readonly $ref: string }
+  | { readonly $lit: unknown }
+  | { readonly $default: readonly [FlowValue, FlowValue] };
+
+/**
+ * 条件表达式：相等、包含、存在、与、非；没有算术与函数调用。
+ */
+export type FlowPredicate =
+  | { readonly $eq: readonly [FlowValue, FlowValue] }
+  | { readonly $in: readonly [FlowValue, readonly unknown[]] }
+  | { readonly $exists: FlowValue }
+  | { readonly $and: readonly FlowPredicate[] }
+  | { readonly $not: FlowPredicate };
+
+/**
+ * 求值现场：流程输入、已经跑完的步骤输出、当前 `forEach` 项、当前 `poll` 返回值。
+ */
+export interface FlowScope {
+  readonly in: unknown;
+  readonly steps: Readonly<Record<string, unknown>>;
+  readonly item?: unknown;
+  readonly value?: unknown;
+}
+
+/**
+ * 动作执行时拿到的现场：取消信号、这次跑的 id 与工作区、当前步骤 id、一行进度、登录提示。
+ */
+export interface FlowActionContext {
+  readonly signal: AbortSignal;
+  readonly runId: string;
+  readonly workspace: string;
+  readonly stepId: string;
+  log(text: string): void;
+  login(url: string): void;
+}
+
+/**
+ * 动作的可选元数据：给人看的标题、入参形状、以及“会不会改平台”。
+ * `writes` 只给外层审批用，不参与执行。
+ */
+export interface FlowActionMeta {
+  readonly title?: string | undefined;
+  readonly description?: string | undefined;
+  readonly input?: Readonly<Record<string, unknown>> | undefined;
+  readonly writes?: boolean | undefined;
+}
+
+/**
+ * 一个动作：实现完全自由，引擎只按名字调它。
+ */
+export type FlowAction = (input: unknown, context: FlowActionContext) => Promise<unknown>;
+
+/**
+ * 注册表里的一格：名字、实现、元数据。
+ */
+export interface RegisteredFlowAction {
+  readonly name: string;
+  readonly action: FlowAction;
+  readonly meta: FlowActionMeta;
+}
+
+/**
+ * 动作注册表：流程只能引用这里登记过的名字。
+ */
+export interface FlowActionRegistry {
+  register(name: string, action: FlowAction, meta?: FlowActionMeta): void;
+  get(name: string): RegisteredFlowAction | undefined;
+  has(name: string): boolean;
+  list(): readonly RegisteredFlowAction[];
+}
+
+/**
+ * 步骤事件：开始、成功、跳过、失败、需要登录；重试时带第几次。
+ */
+export interface FlowStepEvent {
+  readonly stepId: string;
+  readonly title: string;
+  readonly status: 'running' | 'ok' | 'skipped' | 'failed' | 'needs-login';
+  readonly attempt?: number | undefined;
+  readonly message?: string | undefined;
+  readonly loginUrl?: string | undefined;
+}
+
+/**
+ * 跑一条流程要的那几件：流程、输入、动作表、取消信号、身份与进度回调。
+ * `sleep` / `now` 可注入，测试里用假时钟。
+ */
+export interface FlowRunOptions {
+  readonly flow: FlowDefinition;
+  readonly input: unknown;
+  readonly actions: FlowActionRegistry;
+  readonly signal: AbortSignal;
+  readonly runId: string;
+  readonly workspace: string;
+  readonly onStep: (event: FlowStepEvent) => void;
+  readonly sleep?: ((ms: number, signal: AbortSignal) => Promise<void>) | undefined;
+  readonly now?: (() => number) | undefined;
+}
+
+/**
+ * 一次跑的结果：成功、失败或停止；停止不是失败。
+ */
+export interface FlowResult {
+  readonly status: 'ok' | 'failed' | 'stopped';
+  readonly target: string;
+  readonly steps: Readonly<Record<string, unknown>>;
+  readonly failedStep?: string | undefined;
+  readonly error?: unknown;
+}
+
+/**
+ * 一条校验问题：指到具体路径，给 agent 或人直接改。
+ */
+export interface FlowProblem {
+  readonly path: string;
+  readonly problem: string;
+}
+
+/**
+ * 校验结果：`ok` 为真表示没有 problems。
+ */
+export interface FlowCheck {
+  readonly ok: boolean;
+  readonly problems: readonly FlowProblem[];
+}

package/src/host/host-actions.ts

@@ -0,0 +1,7 @@
+import type { HostActions } from './port-types.js';
+import { configSyncAction, configSyncHandler } from './config-sync.js';
+import { profileCreateAction, profileCreateHandler } from './profile-create.js';
+
+export function createHostActions(): HostActions {
+  return { configSyncAction, configSyncHandler, profileCreateAction, profileCreateHandler };
+}

package/src/host/host-kit.ts

@@ -0,0 +1,26 @@
+import type { EnvSupplyPort } from './port-types.js';
+import { createFlowHost, type FlowHost } from './flow/kit.js';
+import { sessionIdOf, sessionWorkspace } from './tool-kit.js';
+
+/**
+ * 宿主 kit 的公共部分：flow、工具侧 session 读法、外部供给装法。
+ */
+export interface HostKit {
+  readonly flow: FlowHost;
+  readonly sessionIdOf: typeof sessionIdOf;
+  readonly sessionWorkspace: typeof sessionWorkspace;
+  readonly libInstallCommand: EnvSupplyPort['libInstallCommand'];
+}
+
+/**
+ * 建一份宿主 kit；每个挂载点一份，没有模块级状态。
+ * @returns flow / sessionIdOf / sessionWorkspace / libInstallCommand。
+ */
+export function createHostKit(parts: { readonly libInstallCommand: EnvSupplyPort['libInstallCommand'] }): HostKit {
+  return {
+    flow: createFlowHost(),
+    sessionIdOf,
+    sessionWorkspace,
+    libInstallCommand: parts.libInstallCommand,
+  };
+}

package/src/host/http.ts

@@ -7,6 +7,7 @@ import {
   type ProvisionHandler,
   type ProvisionRequest,
 } from './provision.js';
+import type { RuntimeStatus } from './adapter-types.js';
 import { WorkbenchDataError } from './data-error.js';
 import { writeResultForClient } from './write-result.js';
 
@@ -251,13 +252,10 @@ export function capabilityHandler(
   };
 }
 
-export interface OpencliHealth {
-  readonly command: string;
-  readonly source: 'env' | 'isolated' | 'path';
-  readonly isolated: string | null;
-}
-
-export function healthHandler(ctx: DshHostContext, opencli?: OpencliHealth): RouteHandler {
+export function healthHandler(
+  ctx: DshHostContext,
+  runtimes?: Readonly<Record<string, RuntimeStatus>>,
+): RouteHandler {
   return () => {
     const profile = ctx.get<{ dir?: string }>('profileContext');
     const dir = profile?.dir;
@@ -268,7 +266,7 @@ export function healthHandler(ctx: DshHostContext, opencli?: OpencliHealth): Rou
       profileDir: dir ?? null,
       pid: process.pid,
       now: new Date().toISOString(),
-      ...(opencli === undefined ? {} : { opencli }),
+      ...(runtimes === undefined ? {} : { runtimes }),
     };
   };
 }