@meiyukichan/dsh-sandore 0.1.0-rc.6

package/packages/microflow/step-navigator.spec.ts

@@ -0,0 +1,301 @@
+/**
+ * step-navigator.ts（StepNavigator）的单元测试：Step 级路由迁移回归。
+ *
+ * 验证 resolveNextNodes 从 workflow dag-navigator 迁入 microflow 后路由行为
+ * 与迁移前完全一致——并行/条件（批量 shouldExecute 分支 id 数组）/shell 匹配/循环
+ * （首入·回边·maxIter 硬上限·breakCondition 跳出·嵌套作用域归零）/无命中线性
+ * 兜底/跨 Stage 目标不路由（nodeIndex 拆分：microflow 只持当前 Stage Step 图）。
+ * @module dsh-sandore/microflow/src/step-navigator.spec
+ */
+import { Context } from '@deepseek-ai/cordis';
+import type { LlmRuntime } from '@deepseek-ai/dsh-llm';
+import type { SessionStore } from '@deepseek-ai/dsh-session';
+import { describe, expect, it } from 'vitest';
+
+import type { WorkflowDefinition, WorkflowStage } from '../workflow/schema';
+import { FakeLlm, textChunks } from '../tests/mocks/llm.ts';
+import { FakeShell, successResult } from '../tests/mocks/shell.ts';
+import { FakeSubagents } from '../tests/mocks/subagents.ts';
+import { FakeSubprocess } from '../tests/mocks/subprocess.ts';
+import { StepNavigator } from './step-navigator.ts';
+import type { ResolveNextNodesContext } from './step-navigator.ts';
+import type { LoopState } from './loop-manager.ts';
+
+/** 组装测试 ctx（注入 FakeLlm + FakeShell + 占位 sessions）。 */
+function makeCtx(): { ctx: Context; llm: FakeLlm; shell: FakeShell } {
+  const ctx = new Context();
+  const llm = new FakeLlm();
+  const shell = new FakeShell();
+  const subagents = new FakeSubagents();
+  const subprocess = new FakeSubprocess();
+  llm.providers.push({ id: 'p', name: 'Provider' });
+  llm.models.set('p', [{ provider: 'p', id: 'm', name: 'Model' }]);
+  ctx.provide('llm', llm as unknown as LlmRuntime);
+  ctx.provide('shell', shell);
+  ctx.provide('subagents', subagents);
+  ctx.provide('subprocess', subprocess);
+  ctx.provide('sessions', {} as unknown as SessionStore);
+  ctx.provide('fs', {});
+  return { ctx, llm, shell };
+}
+
+/** 构造单 Stage 工作流定义（steps 为流控位，完整定义在顶层 steps）。 */
+function makeDef(stages: WorkflowStage[], steps: WorkflowDefinition['steps']): WorkflowDefinition {
+  return { id: 'wfl', name: 'wfl', version: '1', stages, steps: steps ?? [], settings: {} };
+}
+
+/** 组装调度上下文（visitCounts + 透传变量；不传 recentStepSessionId → fork 降级临时会话）。 */
+function ctxWith(visitCounts: Record<string, number>): ResolveNextNodesContext {
+  return { visitCounts, passThroughVars: {} };
+}
+
+/** 新建 StepNavigator（绑定 stage + def，loopState 共享可变数组）。 */
+function makeNavigator(
+  ctx: Context,
+  stage: WorkflowStage,
+  def: WorkflowDefinition,
+  loopState: LoopState = { activeLoopStack: [], activeLoopIterationStack: [] },
+): StepNavigator {
+  return new StepNavigator(ctx, { defaultTimeoutMs: 60000 }, loopState, stage, def);
+}
+
+describe('StepNavigator Step 级路由迁移回归', () => {
+  describe('并行/线性兜底', () => {
+    it('无 branches → 数组顺序下一 Step（线性兜底）', async () => {
+      const { ctx } = makeCtx();
+      const stage: WorkflowStage = {
+        id: 'stg-1', name: 's1', steps: [{ id: 'step-a' }, { id: 'step-b' }],
+      };
+      const def = makeDef([stage], [{ id: 'step-a' }, { id: 'step-b' }]);
+      const nav = makeNavigator(ctx, stage, def);
+      const result = await nav.resolveNextNodes('step-a', ctxWith({}));
+      expect(result.nextNodeIds).toEqual(['step-b']);
+    });
+
+    it('并行分支（多 next 无 condition）→ 全部纳入下一批', async () => {
+      const { ctx } = makeCtx();
+      const stage: WorkflowStage = {
+        id: 'stg-1', name: 's1',
+        steps: [{ id: 'step-a', branches: [{ next: 'step-b' }, { next: 'step-c' }] }, { id: 'step-b' }, { id: 'step-c' }],
+      };
+      const def = makeDef([stage], [{ id: 'step-a' }, { id: 'step-b' }, { id: 'step-c' }]);
+      const nav = makeNavigator(ctx, stage, def);
+      const result = await nav.resolveNextNodes('step-a', ctxWith({}));
+      expect(result.nextNodeIds).toEqual(['step-b', 'step-c']);
+    });
+
+    it('跨 Stage 目标不进 Step 路由（nodeIndex 拆分：microflow 只持当前 Stage Step 图）', async () => {
+      const { ctx } = makeCtx();
+      // step-a 的并行分支 next 指向 stage-2 的 step-b（不在当前 Stage 索引）→ 不路由，
+      // 且 step-a 为当前 Stage 末位无数组后续 → 返回空（跨 Stage 由引擎 tryAdvanceStage 承接）。
+      const stage1: WorkflowStage = {
+        id: 'stg-1', name: 's1', steps: [{ id: 'step-a', branches: [{ next: 'step-b' }] }],
+      };
+      const stage2: WorkflowStage = { id: 'stg-2', name: 's2', steps: [{ id: 'step-b' }] };
+      const def = makeDef([stage1, stage2], [{ id: 'step-a' }, { id: 'step-b' }]);
+      const nav = makeNavigator(ctx, stage1, def);
+      const result = await nav.resolveNextNodes('step-a', ctxWith({}));
+      expect(result.nextNodeIds).toEqual([]);
+    });
+  });
+
+  describe('条件分支（shouldExecute）', () => {
+    // step-a 条件分支目标 step-c（≠ 数组下一 step-b），便于区分「条件命中」与「线性兜底」。
+    const stage: WorkflowStage = {
+      id: 'stg-1', name: 's1',
+      steps: [{ id: 'step-a', branches: [{ condition: { type: 'prompt', value: { promptText: 'go-c?' } }, next: 'step-c' }] }, { id: 'step-b' }, { id: 'step-c' }],
+    };
+    const def = makeDef([stage], [{ id: 'step-a' }, { id: 'step-b' }, { id: 'step-c' }]);
+
+    it('shouldExecute 数组含目标 id → 走条件分支目标（非数组顺序）', async () => {
+      const { ctx, llm } = makeCtx();
+      llm.streamHandler = () => textChunks('{"shouldExecute": ["step-c"]}');
+      const nav = makeNavigator(ctx, stage, def);
+      const result = await nav.resolveNextNodes('step-a', ctxWith({}));
+      expect(result.nextNodeIds).toEqual(['step-c']);
+      expect(result.branchMeta?.result).toContain('shouldExecute');
+    });
+
+    it('shouldExecute 空数组 → 跳过条件分支，线性兜底到数组下一 Step', async () => {
+      const { ctx, llm } = makeCtx();
+      llm.streamHandler = () => textChunks('{"shouldExecute": []}');
+      const nav = makeNavigator(ctx, stage, def);
+      const result = await nav.resolveNextNodes('step-a', ctxWith({}));
+      // 条件不命中 → 数组顺序兜底 step-b（而非条件目标 step-c）。
+      expect(result.nextNodeIds).toEqual(['step-b']);
+    });
+
+    it('多条件分支一次批量评估：branchMeta 只写一次且全部命中分支路由', async () => {
+      const { ctx, llm } = makeCtx();
+      const multiStage: WorkflowStage = {
+        id: 'stg-1', name: 's1',
+        steps: [{
+          id: 'step-a',
+          branches: [
+            { condition: { type: 'prompt', value: { promptText: 'go-c?' } }, next: 'step-c' },
+            { condition: { type: 'prompt', value: { promptText: 'go-d?' } }, next: 'step-d' },
+          ],
+        }, { id: 'step-b' }, { id: 'step-c' }, { id: 'step-d' }],
+      };
+      const multiDef = makeDef([multiStage], [{ id: 'step-a' }, { id: 'step-b' }, { id: 'step-c' }, { id: 'step-d' }]);
+      llm.streamHandler = () => textChunks('{"shouldExecute": ["step-c", "step-d"]}');
+      const nav = makeNavigator(ctx, multiStage, multiDef);
+      const result = await nav.resolveNextNodes('step-a', ctxWith({}));
+      // 批量一次 fork：两条分支全部命中（branchMeta 只写一次，不再被最后一条覆盖）。
+      expect(result.nextNodeIds).toEqual(['step-c', 'step-d']);
+      expect(result.branchMeta?.status).toBe('completed');
+      expect(result.branchMeta?.result).toContain('shouldExecute');
+      expect(llm.calls).toHaveLength(1);
+    });
+  });
+
+  describe('条件分支（shell matchesExpectation label）', () => {
+    const stage: WorkflowStage = {
+      id: 'stg-1', name: 's1',
+      steps: [{ id: 'step-a', branches: [{ condition: { type: 'shell', value: { command: 'echo ok' } }, label: 'ok', next: 'step-c' }] }, { id: 'step-b' }, { id: 'step-c' }],
+    };
+    const def = makeDef([stage], [{ id: 'step-a' }, { id: 'step-b' }, { id: 'step-c' }]);
+
+    it('shell stdout 匹配 label → 走条件分支目标', async () => {
+      const { ctx, shell } = makeCtx();
+      shell.runHandler = async spec => successResult(spec, 'ok');
+      const nav = makeNavigator(ctx, stage, def);
+      const result = await nav.resolveNextNodes('step-a', ctxWith({}));
+      expect(result.nextNodeIds).toEqual(['step-c']);
+    });
+
+    it('shell stdout 不匹配 label → 跳过，线性兜底', async () => {
+      const { ctx, shell } = makeCtx();
+      shell.runHandler = async spec => successResult(spec, 'no');
+      const nav = makeNavigator(ctx, stage, def);
+      const result = await nav.resolveNextNodes('step-a', ctxWith({}));
+      expect(result.nextNodeIds).toEqual(['step-b']);
+    });
+  });
+
+  describe('循环分支', () => {
+    // 单循环：step-loop（loop head）→ step-iter（回边目标）→ maxIter 后 exitTo step-done。
+    const stage: WorkflowStage = {
+      id: 'stg-1', name: 's1',
+      steps: [
+        { id: 'step-loop', branches: [{ next: 'step-iter', loop: { maxIterations: 3, next: 'step-iter', exitTo: 'step-done' } }] },
+        { id: 'step-iter', branches: [{ next: 'step-loop' }] },
+        { id: 'step-done' },
+      ],
+    };
+    const def = makeDef([stage], [{ id: 'step-loop' }, { id: 'step-iter' }, { id: 'step-done' }]);
+
+    it('首入循环（不在活跃循环）→ pushActiveLoop + 回边目标', async () => {
+      const { ctx } = makeCtx();
+      const loopState: LoopState = { activeLoopStack: [], activeLoopIterationStack: [] };
+      const nav = makeNavigator(ctx, stage, def, loopState);
+      const result = await nav.resolveNextNodes('step-loop', ctxWith({ 'step-loop': 0 }));
+      expect(result.nextNodeIds).toEqual(['step-iter']);
+      // 首入压栈：activeLoopNodeId = step-loop，迭代计数 = 1。
+      expect(nav.loopManagerInstance.activeLoopNodeId).toBe('step-loop');
+      expect(nav.loopManagerInstance.buildLoopIterationPath()).toEqual([1]);
+    });
+
+    it('回边（已在活跃循环）→ incrementLoopIteration + 回边目标', async () => {
+      const { ctx } = makeCtx();
+      const loopState: LoopState = { activeLoopStack: [], activeLoopIterationStack: [] };
+      const nav = makeNavigator(ctx, stage, def, loopState);
+      // 先首入（压栈 + 计数 1）。
+      await nav.resolveNextNodes('step-loop', ctxWith({ 'step-loop': 0 }));
+      // 回边：visitCount=1 < maxIter=3 → 继续。
+      const result = await nav.resolveNextNodes('step-loop', ctxWith({ 'step-loop': 1 }));
+      expect(result.nextNodeIds).toEqual(['step-iter']);
+      expect(nav.loopManagerInstance.buildLoopIterationPath()).toEqual([2]);
+    });
+
+    it('maxIterations 硬上限 → 跳出（reset + pop + exitTo）', async () => {
+      const { ctx } = makeCtx();
+      const loopState: LoopState = { activeLoopStack: [], activeLoopIterationStack: [] };
+      const visitCounts: Record<string, number> = {};
+      const nav = makeNavigator(ctx, stage, def, loopState);
+      // 驱动 3 次回边：首入(0) → 回边(1) → 回边(2) → 第 3 次回边 visitCount=3 >= maxIter=3 跳出。
+      await nav.resolveNextNodes('step-loop', { ...ctxWith(visitCounts), visitCounts: { 'step-loop': 0 } });
+      await nav.resolveNextNodes('step-loop', { ...ctxWith(visitCounts), visitCounts: { 'step-loop': 1 } });
+      await nav.resolveNextNodes('step-loop', { ...ctxWith(visitCounts), visitCounts: { 'step-loop': 2 } });
+      const result = await nav.resolveNextNodes('step-loop', ctxWith({ 'step-loop': 3 }));
+      expect(result.nextNodeIds).toEqual(['step-done']);
+      // 跳出后弹栈：无活跃循环。
+      expect(nav.loopManagerInstance.activeLoopNodeId).toBeNull();
+    });
+
+    it('breakCondition shouldBreak=true → 跳出 exitTo（非 maxIter 硬上限）', async () => {
+      const { ctx, llm } = makeCtx();
+      const breakStage: WorkflowStage = {
+        id: 'stg-1', name: 's1',
+        steps: [
+          { id: 'step-loop', branches: [{ next: 'step-iter', loop: { maxIterations: 5, breakCondition: { type: 'prompt', value: { promptText: 'done?' } }, next: 'step-iter', exitTo: 'step-done' } }] },
+          { id: 'step-iter', branches: [{ next: 'step-loop' }] },
+          { id: 'step-done' },
+        ],
+      };
+      const breakDef = makeDef([breakStage], [{ id: 'step-loop' }, { id: 'step-iter' }, { id: 'step-done' }]);
+      const loopState: LoopState = { activeLoopStack: [], activeLoopIterationStack: [] };
+      const nav = makeNavigator(ctx, breakStage, breakDef, loopState);
+      // 首入（push）。
+      await nav.resolveNextNodes('step-loop', ctxWith({ 'step-loop': 0 }));
+      // 回边 visitCount=1 < maxIter=5，breakCondition 返回 shouldBreak=true → 跳出。
+      llm.streamHandler = () => textChunks('{"shouldBreak": true}');
+      const result = await nav.resolveNextNodes('step-loop', ctxWith({ 'step-loop': 1 }));
+      expect(result.nextNodeIds).toEqual(['step-done']);
+      expect(result.loopMeta?.result).toContain('shouldBreak');
+      expect(nav.loopManagerInstance.activeLoopNodeId).toBeNull();
+    });
+
+    it('嵌套循环：内层跳出后归零内层作用域 visitCount，外层仍活跃', async () => {
+      const { ctx } = makeCtx();
+      const nestStage: WorkflowStage = {
+        id: 'stg-1', name: 's1',
+        steps: [
+          { id: 'step-outer', branches: [{ next: 'step-inner', loop: { maxIterations: 2, next: 'step-inner', exitTo: 'step-done' } }] },
+          { id: 'step-inner', branches: [{ next: 'step-iter', loop: { maxIterations: 1, next: 'step-iter', exitTo: 'step-outer' } }] },
+          { id: 'step-iter', branches: [{ next: 'step-inner' }] },
+          { id: 'step-done' },
+        ],
+      };
+      const nestDef = makeDef([nestStage], [{ id: 'step-outer' }, { id: 'step-inner' }, { id: 'step-iter' }, { id: 'step-done' }]);
+      const loopState: LoopState = { activeLoopStack: [], activeLoopIterationStack: [] };
+      const nav = makeNavigator(ctx, nestStage, nestDef, loopState);
+      // 外层首入（push outer）。
+      await nav.resolveNextNodes('step-outer', ctxWith({ 'step-outer': 0 }));
+      expect(nav.loopManagerInstance.activeLoopNodeId).toBe('step-outer');
+      // 内层首入（push inner，迭代计数嵌套 [1,1]）。
+      await nav.resolveNextNodes('step-inner', ctxWith({ 'step-inner': 0 }));
+      expect(nav.loopManagerInstance.buildLoopIterationPath()).toEqual([1, 1]);
+      // step-iter 执行后回边到 step-inner（visitCount 累加）。
+      await nav.resolveNextNodes('step-iter', ctxWith({ 'step-iter': 0 }));
+      // 内层回边 visitCount=1 >= maxIter=1 → 跳出，exitTo=step-outer。
+      const innerBreak = await nav.resolveNextNodes('step-inner', ctxWith({ 'step-inner': 1 }));
+      expect(innerBreak.nextNodeIds).toEqual(['step-outer']);
+      // 内层弹栈：外层仍活跃；内层作用域节点（step-iter）visitCount 归零。
+      expect(nav.loopManagerInstance.activeLoopNodeId).toBe('step-outer');
+      expect(nav.loopManagerInstance.buildLoopIterationPath()).toEqual([1]);
+    });
+  });
+
+  describe('节点边界', () => {
+    it('未知 nodeId → 返回空（不报错）', async () => {
+      const { ctx } = makeCtx();
+      const stage: WorkflowStage = { id: 'stg-1', name: 's1', steps: [{ id: 'step-a' }] };
+      const def = makeDef([stage], [{ id: 'step-a' }]);
+      const nav = makeNavigator(ctx, stage, def);
+      const result = await nav.resolveNextNodes('nope', ctxWith({}));
+      expect(result.nextNodeIds).toEqual([]);
+    });
+
+    it('loopManagerInstance 暴露共享循环管理器（供引擎/执行器 ID 后缀与迭代路径）', () => {
+      const { ctx } = makeCtx();
+      const stage: WorkflowStage = { id: 'stg-1', name: 's1', steps: [{ id: 'step-a' }] };
+      const def = makeDef([stage], [{ id: 'step-a' }]);
+      const loopState: LoopState = { activeLoopStack: [], activeLoopIterationStack: [] };
+      const nav = makeNavigator(ctx, stage, def, loopState);
+      // 同一实例：引擎从 stepNavigator.loopManagerInstance 取后注入 StageExecutor。
+      expect(nav.loopManagerInstance).toBe(nav.loopManagerInstance);
+      expect(nav.loopManagerInstance.activeLoopNodeId).toBeNull();
+    });
+  });
+});

package/packages/microflow/step-navigator.ts

@@ -0,0 +1,300 @@
+/**
+ * Stage 内 Step 级 DAG 导航器（Task 3：Step 级 DAG 调度，迁自 workflow 的 dag-navigator）。
+ *
+ * **包职责边界（用户原则）**：Step 生命周期（含路由 resolveNextNodes + 执行 + 判断 + 收尾 +
+ * 循环计数）全归 microflow。本模块持有当前 Stage 的 Step 节点索引 `stepIndex`，以
+ * `resolveNextNodes()` 作为 Step 级调度单一入口，内部自建 {@link BranchEvaluator}（fork-based
+ * 条件评估）+ {@link LoopManager}（循环跳出/计数模型，缺陷 3 不动）承担 Step 级分支/循环路由。
+ * 一个 Stage 内部执行（含 Step 路由）自包含在 microflow 完成，才到下一 Stage（Stage→Stage 推进
+ * + Stage 级条件评估留 workflow 的 dag-navigator）。
+ *
+ * 构建 Stage 内 Step 节点索引 `stepIndex`（分离式合并：`stage.steps` 流控位 + 顶层
+ * `definition.steps` 完整定义，按 id 交叉引用）。**分支是唯一出边单元**（统一
+ * `branches: [{ next, condition?, loop? }]`）：
+ * - 并行分支（无 `condition`）始终纳入下一批；
+ * - 条件分支（有 `condition`）一次批量评估（fork step 会话注入全量历史，AI 返回
+ *   shouldExecute 分支 id 数组，shell 逐条走 `matchesExpectation(label)`）；
+ * - 循环分支（有 `loop`，`next` 为回边）命中后经 `checkLoopBreak` 判定跳出（exitTo）或继续下一
+ *   迭代。无分支或无命中时按定义数组顺序线性兜底；跨 Stage 目标不在此路由（交由引擎
+ *   `tryAdvanceStage` 跨阶段推进）。`branchMeta` / `loopMeta` 保留评估现场。
+ * @module dsh-sandore/microflow/src/step-navigator
+ */
+import type { Context } from '@deepseek-ai/cordis';
+
+import { BranchEvaluator } from './branch-evaluator.ts';
+import type { BranchEvalOptions, BranchEvaluatorConfig } from './branch-evaluator.ts';
+import { LoopManager } from './loop-manager.ts';
+import type { LoopState } from './loop-manager.ts';
+
+import type { BranchMeta, DagBranch, WorkflowDefinition, WorkflowStage, WorkflowStep } from '../workflow/schema';
+
+/** 分离式合并后的完整 Step（顶层定义 + 流控 branches）。 */
+export type MergedStepRef = WorkflowStep & { readonly branches?: DagBranch[] | undefined };
+
+/** Step 节点视图（出边统一在 branches；同 Stage 内节点，跨 Stage 目标不在此索引）。 */
+export interface StepNodeRef {
+  /** 所属 Stage（始终可用，供数组顺序兜底与同 Stage 判定）。 */
+  readonly stage: WorkflowStage;
+  /** 合并后的完整 Step。 */
+  readonly step: MergedStepRef;
+  readonly id: string;
+  readonly name: string;
+  readonly branches?: DagBranch[] | undefined;
+}
+
+/** `resolveNextNodes` 的调度上下文（由 StageExecutor.buildContext 注入的共享状态）。 */
+export interface ResolveNextNodesContext {
+  /** 节点访问计数（循环节点记为回边次数，初始 0）。 */
+  readonly visitCounts: Record<string, number>;
+  /** 已解析的透传变量（`${xxx}` → 值）。 */
+  readonly passThroughVars: Readonly<Record<string, string>>;
+  readonly signal?: AbortSignal;
+  /**
+   * 当前 step 的子代理会话 ID（fork-based 判断：缺陷 2/4 改造）。
+   *
+   * 由 `stage-executor.buildContext` 从最近命令节点的 `sessionMeta.childId`
+   * （`synthetic === false` 真实子代理会话）取。条件分支 `evaluateConditions` 与
+   * 循环跳出 `checkLoopBreak` 消费：fork 此会话注入全量历史，AI 在 fork 会话上跑判断
+   * 即可见全部 I/O。合成 session（prompt/shell）或无已执行命令节点时为 undefined
+   * （判断降级为临时会话）。
+   */
+  readonly recentStepSessionId?: string;
+}
+
+/** `resolveNextNodes` 的返回：下一批节点 ID 与评估现场。 */
+export interface ResolveNextNodesResult {
+  readonly nextNodeIds: string[];
+  readonly branchMeta?: BranchMeta;
+  readonly loopMeta?: BranchMeta;
+}
+
+/** 去重并保序。 */
+function dedupe(ids: readonly string[]): string[] {
+  return [...new Set(ids)];
+}
+
+/**
+ * Stage 内 Step 级 DAG 导航器。
+ *
+ * 持有当前 Stage 的 `stepIndex`（stepId → 节点视图）、内置 {@link BranchEvaluator}/
+ * {@link LoopManager} 承担 Step 级分支/循环路由。循环节点 ID 后缀、迭代路径经
+ * {@link StepNavigator.loopManagerInstance} 暴露给 StageExecutor/引擎共享。
+ */
+export class StepNavigator {
+  private readonly stepIndex = new Map<string, StepNodeRef>();
+  private readonly evaluator: BranchEvaluator;
+  private readonly loopManager: LoopManager;
+
+  constructor(
+    private readonly ctx: Context,
+    config: BranchEvaluatorConfig,
+    loopState: LoopState,
+    stage: WorkflowStage,
+    workflowDef: WorkflowDefinition,
+  ) {
+    this.buildStepIndex(stage, workflowDef);
+    this.evaluator = new BranchEvaluator(ctx, config);
+    this.loopManager = new LoopManager(ctx, config, loopState);
+  }
+
+  /** 循环管理器（StageExecutor/引擎共享，用于 ID 后缀与迭代路径）。 */
+  get loopManagerInstance(): LoopManager {
+    return this.loopManager;
+  }
+
+  /**
+   * Step 级调度单一入口。
+   *
+   * 统一分支路由（branches 是唯一出边单元）：
+   * ① 并行分支（无 condition）始终纳入下一批（多条并发）；
+   * ② 条件分支（有 condition）一次批量评估（AI 返回 shouldExecute 分支 id 数组；
+   *    shell 走 `matchesExpectation(label)`），命中纳入；
+   * ③ 循环分支（有 loop，next 为回边）：**首入与回边都调 `checkLoopBreak`**（只读
+   *    visitCount，递增已由 `runLoop` 在处理节点前完成，等价基准 `processNode`
+   *    L93-94 + L164）；跳出走 `exitTo`（先 `resetLoopVisitCounts`+`popActiveLoop`），
+   *    继续回 `loop.next`（同循环 `incrementLoopIteration` / 首入 `pushActiveLoop`）；
+   * ④ 无任何命中时按定义数组顺序线性兜底；无 Step 级目标返回空
+   *    （由引擎 `tryAdvanceStage` 跨阶段推进）。
+   */
+  async resolveNextNodes(nodeId: string, context: ResolveNextNodesContext): Promise<ResolveNextNodesResult> {
+    const node = this.stepIndex.get(nodeId);
+    if (node === undefined) {
+      return { nextNodeIds: [] };
+    }
+    const branches = node.branches ?? [];
+    if (branches.length === 0) {
+      const arrayNext = this.arrayNextStep(node);
+      return arrayNext === undefined ? { nextNodeIds: [] } : { nextNodeIds: [arrayNext] };
+    }
+
+    const parallel = branches.filter(branch => branch.condition === undefined && branch.loop === undefined);
+    const conditional = branches.filter(branch => branch.condition !== undefined && branch.loop === undefined);
+    const loopBranches = branches.filter(branch => branch.loop !== undefined);
+
+    const nextNodeIds: string[] = [];
+    let branchMeta: BranchMeta | undefined;
+    for (const branch of parallel) {
+      if (this.sameStageStep(node, branch.next) !== undefined) {
+        nextNodeIds.push(branch.next);
+      }
+    }
+
+    // 条件分支：一次批量评估（Round 20 批量模板——AI 一次 fork 返回 shouldExecute 分支
+    // id 数组，shell 逐条匹配 label）。branchMeta 只写一次（修复多条件分支覆盖 bug：
+    // 旧逐条循环里 branchMeta 被最后一条覆盖，只保留最后一个分支的评估现场）。
+    if (conditional.length > 0) {
+      const { result, passedBranchIds } = await this.evaluator.evaluateConditions(
+        conditional.map(b => ({ branch: b, condition: b.condition! })),
+        this.branchEvalOptions(node, context),
+      );
+      branchMeta = {
+        status: 'completed',
+        result: result.output,
+        ...(result.sessionHandle === null ? {} : { sessionId: result.sessionHandle }),
+      };
+      for (const nextId of passedBranchIds) {
+        if (this.sameStageStep(node, nextId) !== undefined) nextNodeIds.push(nextId);
+      }
+    }
+
+    // 循环分支：对齐基准模型——checkLoopBreak 总是调（只读 visitCount，不递增，
+    // 递增已由 runLoop 在处理节点前完成，等价基准 processNode L93-94 + L164 总调）。
+    // 跳出时 resetLoopVisitCounts（归零该循环作用域）+ popActiveLoop + exitTo
+    // （仅当已在该循环回边时；首入即跳出无栈可弹）；继续时同循环 incrementLoopIteration、
+    // 首入/嵌套 pushActiveLoop。
+    let loopResult: ResolveNextNodesResult | undefined;
+    for (const branch of loopBranches) {
+      const loop = branch.loop!;
+      const wasInThisLoop = this.loopManager.activeLoopNodeId === node.id;
+      // checkLoopBreak 只读 visitCount（不递增），根治命令门双重计数（缺陷 3 case ①）。
+      const visitCount = context.visitCounts[node.id] ?? 0;
+      // 缺陷 4（fork-based 改造）：传入当前 step 会话 id，checkLoopBreak fork 注入全量历史
+      // （不手动传 I/O 文本——fork 会话携带循环体全部 I/O，AI 在 fork 会话上跑判断即可见）。
+      const outcome = await this.loopManager.checkLoopBreak(
+        { id: node.id, loop },
+        visitCount,
+        {
+          ...(context.recentStepSessionId === undefined ? {} : { stepSessionId: context.recentStepSessionId }),
+          stepId: node.id,
+          passThroughVars: context.passThroughVars,
+        },
+      );
+      if (outcome.shouldBreak) {
+        // 跳出：仅已在该循环（回边）才归零作用域 + 弹栈（首入即跳出无栈可弹）。
+        // 归零作用域推翻缺陷 22 的「进入时归零」，改用基准「跳出时归零」语义。
+        if (wasInThisLoop) {
+          this.loopManager.resetLoopVisitCounts(context.visitCounts);
+          this.loopManager.popActiveLoop();
+        }
+        const exitTo = loop.exitTo;
+        loopResult = {
+          nextNodeIds: exitTo !== undefined && this.sameStageStep(node, exitTo) !== undefined ? [exitTo] : [],
+          ...(outcome.loopMeta === undefined ? {} : { loopMeta: outcome.loopMeta }),
+        };
+        break;
+      }
+      // 继续：同循环 incrementLoopIteration；首入或嵌套 pushActiveLoop。
+      if (wasInThisLoop) {
+        this.loopManager.incrementLoopIteration();
+      } else {
+        this.loopManager.pushActiveLoop(node.id, loop.maxIterations);
+      }
+      const loopTo = loop.next;
+      if (loopTo !== undefined && this.sameStageStep(node, loopTo) !== undefined) {
+        // 缺陷 23：continue 分支同样透传 outcome.loopMeta（checkLoopBreak 在 shouldBreak=false
+        // 时也产出 loopMeta(completed)，loop-manager.spec L174-175 实证）。修复前仅 break
+        // 分支透传，导致每次「继续」迭代的 breakCondition 评估现场静默丢失（审计/可观测性缺口）。
+        // 不改计数语义：visitCount 递增仍由 runLoop 单一完成（缺陷 3 已重构），路由条目仅
+        // 快照当前值——continue 透传不引入双重计数。
+        loopResult = {
+          nextNodeIds: [loopTo],
+          ...(outcome.loopMeta === undefined ? {} : { loopMeta: outcome.loopMeta }),
+        };
+        break;
+      }
+      // 回边目标无效（跨 Stage/缺失）：回滚刚压栈后退出（仅 !wasInThisLoop 时刚 push）。
+      if (!wasInThisLoop) {
+        this.loopManager.resetLoopVisitCounts(context.visitCounts);
+        this.loopManager.popActiveLoop();
+      }
+      const exitTo = loop.exitTo;
+      // 缺陷 23：continue 分支回边目标无效的回滚路径同样透传 loopMeta（评估已完成）。
+      loopResult = {
+        nextNodeIds: exitTo !== undefined && this.sameStageStep(node, exitTo) !== undefined ? [exitTo] : [],
+        ...(outcome.loopMeta === undefined ? {} : { loopMeta: outcome.loopMeta }),
+      };
+      break;
+    }
+
+    // 循环命中时，循环路由优先于前进分支（循环接管本轮调度）。
+    if (loopResult !== undefined) {
+      return loopResult;
+    }
+
+    // 无循环：前进分支 + 数组顺序兜底。
+    if (nextNodeIds.length > 0) {
+      return { nextNodeIds: dedupe(nextNodeIds), ...(branchMeta === undefined ? {} : { branchMeta }) };
+    }
+    const arrayNext = this.arrayNextStep(node);
+    if (arrayNext !== undefined) {
+      nextNodeIds.push(arrayNext);
+    }
+    return { nextNodeIds: dedupe(nextNodeIds), ...(branchMeta === undefined ? {} : { branchMeta }) };
+  }
+
+  /** 数组顺序的下一 Step（同 Stage 内，线性兜底）。 */
+  private arrayNextStep(node: StepNodeRef): string | undefined {
+    const steps = node.stage.steps;
+    const index = steps.findIndex(step => step.id === node.id);
+    return index < 0 ? undefined : steps[index + 1]?.id;
+  }
+
+  /** 组装分支评估选项（候选分支 + 透传变量 + 循环上下文 + fork 源会话 + stepId + 取消信号）。 */
+  private branchEvalOptions(node: StepNodeRef, context: ResolveNextNodesContext): BranchEvalOptions {
+    const loopContext = this.loopManager.getLoopIterationContext();
+    return {
+      ...(node.branches === undefined ? {} : { branches: node.branches }),
+      passThroughVars: context.passThroughVars,
+      loopTurn: loopContext.loopTurn,
+      loopMaxIterations: loopContext.loopMaxIterations,
+      ...(context.recentStepSessionId === undefined ? {} : { stepSessionId: context.recentStepSessionId }),
+      stepId: node.id,
+      ...(context.signal === undefined ? {} : { signal: context.signal }),
+    };
+  }
+
+  /** 目标节点是否为本 Stage 内的 Step（跨 Stage 目标返回 undefined，交由引擎跨阶段推进）。 */
+  private sameStageStep(node: StepNodeRef, targetId: string): StepNodeRef | undefined {
+    const target = this.stepIndex.get(targetId);
+    if (target === undefined) {
+      return undefined;
+    }
+    if (target.stage.id !== node.stage.id) {
+      return undefined;
+    }
+    return target;
+  }
+
+  /**
+   * 构建当前 Stage 的 Step 节点索引（分离式合并）。
+   *
+   * `stage.steps` 提供流控位（id + branches），`workflowDef.steps` 提供完整定义
+   * （command/映射/gates 等），按 id 合并成执行用的完整 Step。
+   */
+  private buildStepIndex(stage: WorkflowStage, workflowDef: WorkflowDefinition): void {
+    const definitions = new Map((workflowDef.steps ?? []).map(step => [step.id, step] as const));
+    for (const flowStep of stage.steps) {
+      const definitionStep = definitions.get(flowStep.id);
+      const merged: MergedStepRef = definitionStep === undefined
+        ? flowStep as MergedStepRef
+        : { ...definitionStep, ...(flowStep.branches === undefined ? {} : { branches: flowStep.branches }) };
+      this.stepIndex.set(flowStep.id, {
+        stage,
+        step: merged,
+        id: flowStep.id,
+        name: merged.name ?? flowStep.id,
+        branches: merged.branches,
+      });
+    }
+  }
+}