@mzzsfy/dsh-rs-workflow 0.2.4 → 1.0.0

package/lib/orchestrator.mjs

@@ -0,0 +1,428 @@
+// orchestrator — 主循环工具行:rs_workflow_start/status/resume/cancel/message/resume_from/verdict 七工具
+// 编排以分段 continuable job 推进:每段 = jobs.start 包装 driver.runSegment,settle 负载经 tool-jobs
+// 完成通知唤醒主循环;推进责任唯一在 rs_workflow_resume(页签 control 仅清 paused/裁决)
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { gate } from './planner-gate.mjs'
+import { validateTemplate } from './template.mjs'
+import { startRun, buildSeed } from './driver/index.mjs'
+import { registry, registerInitiator, unregisterInitiator, registerResumer } from './driver/control.mjs'
+import { reportStore } from './store.mjs'
+import { loadJson } from './storage.mjs'
+import { normalizeConfig } from './settings-schema.mjs'
+
+const MAX_REJECTS = 3
+const SEGMENT_KIND = 'rsww-segment'
+const SETTLE_OUTPUT_LIMIT = 64 * 1024
+
+// 已启用模板表(自有存储 → {entry, parsed};gate/驱动共用此形态)
+export function enabledTemplates() {
+  const out = []
+  for (const entry of loadJson('templates.json', [])) {
+    if (entry.enabled === false || typeof entry.json !== 'string') continue
+    try {
+      const parsed = JSON.parse(entry.json)
+      if (validateTemplate(parsed).length === 0) out.push({ entry, parsed })
+    } catch { /* 损坏模板不进候选 */ }
+  }
+  return out
+}
+
+/** 模式行激活入口(config: { role:'orchestrator', templateId });宿主服务缺一目工具即报错 */
+export function registerOrchestrator(ctx, config) {
+  const expectedTemplateId = config.templateId
+  // 连续拒单计数与现役 run:行实例内存态,进程重启清零
+  const rejectCounts = new Map()
+  const activeRuns = new Map()
+
+  const registered = ctx.inject(['tools', 'workflowEngine', 'jobs'], (tctx) => {
+    const engine = tctx.workflowEngine
+    const jobs = tctx.jobs
+
+    const configOf = () => normalizeConfig(loadJson('config.json', undefined))
+
+    const agentIdOf = (agent) => String(agent?.id ?? '')
+
+    // 会话现役 run:同会话同一时刻至多一个未终态 run
+    const currentRunId = (agent) => {
+      const runId = activeRuns.get(agentIdOf(agent))
+      if (runId === undefined) return undefined
+      // run 可能已被页签删除:get 抛异常须自愈清位,不能让编排入口变砖
+      let record
+      try { record = reportStore().get(runId) } catch { record = undefined }
+      if (record === undefined || record.finishedAt !== undefined) {
+        activeRuns.delete(agentIdOf(agent))
+        return undefined
+      }
+      return runId
+    }
+
+    // 段 job:jobs.start 包装 runSegment;settle 负载进 output,经 tool-jobs 完成通知唤醒主循环
+    function startSegmentJob(agent, driver) {
+      const promise = driver.runSegment()
+      return jobs.start({
+        kind: SEGMENT_KIND,
+        label: `若水编排段推进 ${driver.runId}`,
+        outputLimitBytes: SETTLE_OUTPUT_LIMIT,
+        owner: agent,
+        run: () => ({
+          cancel: () => driver.cancel(),
+          done: promise.then((payload) => ({ status: 'completed', output: JSON.stringify(payload) })),
+        }),
+      })
+    }
+
+    // 断点续跑挂靠:board resume-from 经此回调在原会话重建种子 run(engine/parent 闭包自本域)
+    function startSeedRun(agent, record, fromStepId, inputs) {
+      const templates = enabledTemplates()
+      const template = templates.find((t) => t.entry.id === record.templateId)
+      if (template === undefined) return { ok: false, error: `模板不存在或已禁用: ${record.templateId}` }
+      // 单活跃约束:种子 run 与 start 工具同守卫;主循环成为其推进者(activeRuns 注册,补拉/守卫生效)
+      const current = currentRunId(agent)
+      if (current !== undefined) return { ok: false, error: `本会话已有进行中的编排 ${current},不可续跑` }
+      const seed = buildSeed(record, record.plan, fromStepId, inputs)
+      const driver = startRun({
+        template: template.parsed, templateSet: templates.map((t) => t.parsed),
+        plan: record.plan, warnings: record.warnings ?? [],
+        request: record.request, inputs: seed.inputs, state: seed,
+        sessionId: agentIdOf(agent), workspace: agent.session?.header?.cwd ?? process.cwd(),
+        engine, slots: configOf().slots ?? {}, budgets: configOf().budgets ?? {},
+        parent: agent,
+      })
+      activeRuns.set(agentIdOf(agent), driver.runId)
+      // 种子 run 首段拉起:与 start 工具同责,缺此则续跑 run 停在 running 无活跃段
+      startSegmentJob(agent, driver)
+      return { ok: true, runId: driver.runId }
+    }
+
+    function finishRun(agent, runId) {
+      if (currentRunId(agent) === runId) activeRuns.delete(agentIdOf(agent))
+    }
+
+    // 段拉起挂靠:页签裁决受理后 board 经此回到本域拉下一段(幂等:活跃段不重拉);点位与 initiator 挂靠一致
+    function ensureResumer(agent) {
+      registerResumer(agentIdOf(agent), (runId) => {
+        const driver = registry.drivers.get(runId)
+        if (driver === undefined || driver.active) return false
+        startSegmentJob(agent, driver)
+        return true
+      })
+    }
+
+    const tools = [
+      defineTool({
+        name: 'rs_workflow_start',
+        description: [
+          '启动若水工作流编排:提交用户请求原文与结构化规划,受理后引擎分段推进。',
+          '受理返回 { ok, runId, status };规划被拒返回 { ok:false, errors }(按 errors 修正重交;连续 3 次被拒须回退直接答复并说明)。',
+          'templateId 必须等于本组合锚定的模板 id;plan 缺省 = 保底全序(不推荐,多步骤任务应提交 steps/brief)。',
+        ].join(''),
+        parameters: {
+          request: { type: 'string', required: true, description: '用户请求原文(逐字,不转写)' },
+          templateId: { type: 'string', required: true, description: '本组合锚定的模板 id' },
+          inputs: { type: 'object', additionalProperties: true, description: '模板顶层 inputs 的键值,值必须为字符串' },
+          plan: {
+            type: 'object',
+            additionalProperties: true,
+            description: '结构化规划 { steps: [{ref, note?, done?}], brief? }:steps 各步要点(note)与验收口径(done);缺省 = 保底全序',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              ok: { type: 'boolean', required: true },
+              runId: { type: 'string' },
+              status: { type: 'string' },
+              errors: { type: 'array', items: { type: 'object', additionalProperties: true } },
+              hint: { type: 'string' },
+            },
+          },
+          render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+          const agent = exec.agent
+          // 工具参数扁平:gate 入参 = 顶层三字段 + plan(steps/brief)组装(见 feat/orchestrator.md)
+          const gatePlan = {
+            request: args.request, templateId: args.templateId, inputs: args.inputs,
+            brief: args.plan?.brief, steps: args.plan?.steps,
+          }
+          const rejects = (id) => {
+            const next = (rejectCounts.get(id) ?? 0) + 1
+            rejectCounts.set(id, next)
+            return next
+          }
+          const rejected = (errors) => {
+            const count = rejects(agentIdOf(agent))
+            if (count >= MAX_REJECTS) return { ok: false, errors, hint: `已连续 ${MAX_REJECTS} 次规划被拒,本会话编排入口关闭:回退直接答复并向用户说明` }
+            return { ok: false, errors, hint: '修正 plan 后重新调用;连续 3 次失败将回退直接答复' }
+          }
+          // 连续拒单达上限:本会话工具恒失败
+          if ((rejectCounts.get(agentIdOf(agent)) ?? 0) >= MAX_REJECTS) {
+            return { ok: false, errors: [], hint: `已连续 ${MAX_REJECTS} 次规划被拒,本会话编排入口关闭:回退直接答复并向用户说明` }
+          }
+          if (currentRunId(agent) !== undefined) {
+            return { ok: false, errors: [], hint: `本会话已有进行中的编排 ${currentRunId(agent)},先等待终态或取消` }
+          }
+          const templates = enabledTemplates()
+          const template = templates.find((t) => t.entry.id === args.templateId)
+          if (template === undefined) {
+            // 组合/环境错误而非规划错误:不计连续拒单,hint 指向组合而非 plan
+            return { ok: false, errors: [{ target: 'templateId', message: `模板不存在或未启用: ${args.templateId}` }], hint: '本组合未启用该模板:检查组合锚定与模板启用状态,勿修改 plan' }
+          }
+          const outcome = gate(gatePlan, template, { expectedTemplateId })
+          if (!outcome.ok) return rejected(outcome.errors)
+          const driver = startRun({
+            template: template.parsed, templateSet: templates.map((t) => t.parsed),
+            plan: outcome.planScript, warnings: outcome.warnings ?? [],
+            request: args.request, inputs: args.inputs ?? {},
+            engine, slots: configOf().slots ?? {}, budgets: configOf().budgets ?? {},
+            // 会话工作区取自会话 header(子代理继承同源);宿主 cwd 仅兜底
+            sessionId: agentIdOf(agent), workspace: agent.session?.header?.cwd ?? process.cwd(),
+            parent: agent,
+          })
+          rejectCounts.delete(agentIdOf(agent))
+          activeRuns.set(agentIdOf(agent), driver.runId)
+          // 断点续跑挂靠:本会话 agent 成为推进器,board resume-from 据此重建种子 run
+          registerInitiator(agentIdOf(agent), (record, fromStepId, inputs) => startSeedRun(agent, record, fromStepId, inputs))
+          ensureResumer(agent)
+          startSegmentJob(agent, driver)
+          return { ok: true, runId: driver.runId, status: driver.state.status }
+        },
+      }),
+      defineTool({
+        name: 'rs_workflow_status',
+        description: '查询若水编排状态:runId 缺省 = 本会话现役 run。返回 status/awaitingResume(补拉判定信号)/steps 账目/waiting 待裁决摘要。',
+        parameters: {
+          runId: { type: 'string', description: '缺省 = 本会话现役 run' },
+        },
+        output: {
+          schema: { type: 'object', additionalProperties: true },
+          render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+          const store = reportStore()
+          const runId = typeof args.runId === 'string' && args.runId !== '' ? args.runId : currentRunId(exec.agent)
+          if (runId === undefined) return { ok: false, error: '本会话无现役 run(编排未启动)' }
+          let record
+          try { record = store.get(runId) } catch { record = undefined }
+          if (record === undefined) return { ok: false, error: '运行记录不存在:' + runId }
+          // 唤醒轮挂靠:主循环任一唤醒轮必先 status,借机注册断点续跑推进器(进程重启后表空,
+          // 页签 resume-from 恰是重启中断的唯一恢复路径,不能依赖 start/resume 才有挂靠)
+          registerInitiator(agentIdOf(exec.agent), (record2, fromStepId, inputs) => startSeedRun(exec.agent, record2, fromStepId, inputs))
+          ensureResumer(exec.agent)
+          const driver = registry.drivers.get(runId)
+          const steps = {}
+          for (const [id, s] of Object.entries(record.state?.steps ?? {})) {
+            steps[id] = { status: s.status, failCount: s.failCount ?? 0 }
+          }
+          const waiting = []
+          if (record.status === 'waiting_approval') {
+            const stepId = record.state?.waitingApproval
+            const planStep = (record.plan?.steps ?? []).find((p) => p.ref === stepId)
+            waiting.push({ stepId, note: planStep?.note ?? '', done: planStep?.done ?? '' })
+          }
+          // paused+已入队裁决:主循环据 pendingVerdicts 可知 resume 拉段后裁决将生效
+          const pendingVerdicts = (record.state?.pendingApprovals ?? []).length
+          return {
+            ok: true, runId, status: record.status,
+            awaitingResume: record.status === 'paused' && driver?.awaitingResume === true,
+            steps,
+            // 宿主校验工具输出须为纯 JSON:undefined 值键会被判无效输出
+            ...(waiting.length > 0 ? { waiting } : {}),
+            ...(pendingVerdicts > 0 ? { pendingVerdicts } : {}),
+            summary: record.summary ?? '',
+          }
+        },
+      }),
+      defineTool({
+        name: 'rs_workflow_resume',
+        description: [
+          '拉起若水编排下一段(推进责任唯一在此):paused 拉起时同步置 running;已推进/终态返回 skipped。',
+          '裁决回写后、页签恢复后、running 无活跃段(待拉起)时调用。',
+        ].join(''),
+        parameters: {
+          runId: { type: 'string', required: true, description: '要推进的 run' },
+        },
+        output: {
+          schema: { type: 'object', additionalProperties: true },
+          render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+          const store = reportStore()
+          let record
+          try { record = store.get(args.runId) } catch { record = undefined }
+          if (record === undefined) return { ok: false, error: '运行记录不存在:' + args.runId }
+          if (record.finishedAt !== undefined) {
+            finishRun(exec.agent, args.runId)
+            return { ok: true, runId: args.runId, status: record.status, summary: record.summary }
+          }
+          const driver = registry.drivers.get(args.runId)
+          if (driver === undefined) {
+            return { ok: false, error: '编排驱动器未注册(进程重启后 run 已收敛为终态,请 rs_workflow_status 确认)' }
+          }
+          // 页签已推进(有活跃段):不重复拉起
+          if (driver.active) return { ok: true, runId: args.runId, status: record.status, skipped: true }
+          if (record.status === 'paused') {
+            driver.state.status = 'running'
+            driver.awaitingResume = false
+            driver.persistState()
+          }
+          if (record.status === 'waiting_approval') {
+            return { ok: true, runId: args.runId, status: record.status, skipped: true, hint: '先裁决(control approve/reject 或经会话页签),再 resume 拉起下一段' }
+          }
+          startSegmentJob(exec.agent, driver)
+          registerInitiator(agentIdOf(exec.agent), (record2, fromStepId, inputs) => startSeedRun(exec.agent, record2, fromStepId, inputs))
+          ensureResumer(exec.agent)
+          return { ok: true, runId: args.runId, status: record.status }
+        },
+      }),
+      defineTool({
+        name: 'rs_workflow_cancel',
+        description: '取消若水编排(幂等):running 有活跃段则 abort 收敛;waiting_approval/paused 即时终态;已终态返回摘要无副作用。',
+        parameters: {
+          runId: { type: 'string', required: true, description: '要取消的 run' },
+        },
+        output: {
+          schema: { type: 'object', additionalProperties: true },
+          render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+          const store = reportStore()
+          let record
+          try { record = store.get(args.runId) } catch { record = undefined }
+          if (record === undefined) return { ok: false, error: '运行记录不存在:' + args.runId }
+          if (record.finishedAt !== undefined) {
+            finishRun(exec.agent, args.runId)
+            return { ok: true, runId: args.runId, status: record.status, summary: record.summary }
+          }
+          const driver = registry.drivers.get(args.runId)
+          if (driver === undefined) return { ok: false, error: '编排驱动器未注册' }
+          driver.cancel()
+          const hint = '已完成步骤保留,可在会话页签断点续跑'
+          if (driver.active) {
+            await driver.runSegment().catch(() => {})
+            let after
+            try { after = store.get(args.runId) } catch { after = undefined }
+            finishRun(exec.agent, args.runId)
+            return { ok: true, runId: args.runId, status: after?.status ?? 'cancelled', summary: after?.summary ?? '', hint }
+          }
+          let after
+          try { after = store.get(args.runId) } catch { after = undefined }
+          finishRun(exec.agent, args.runId)
+          return { ok: true, runId: args.runId, status: after?.status ?? 'cancelled', hint }
+        },
+      }),
+      defineTool({
+        name: 'rs_workflow_message',
+        description: '向进行中的若水编排转达用户纠偏:下一步骤边界进入编排(纠偏类经主循环转译后 inject 注入后续指令)。',
+        parameters: {
+          runId: { type: 'string', required: true, description: '目标 run' },
+          text: { type: 'string', required: true, description: '用户纠偏内容(转译后)' },
+          inject: { type: 'boolean', description: 'true = 注入后续指令;缺省 false 排队' },
+        },
+        output: {
+          schema: { type: 'object', additionalProperties: true },
+          render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args) {
+          const driver = registry.drivers.get(args.runId)
+          if (driver === undefined) return { ok: false, error: '编排驱动器未注册(run 未终态但不在内存,或已终态)' }
+          const accepted = driver.handlePost({ kind: 'message', text: args.text, inject: args.inject === true })
+          return accepted ? { ok: true } : { ok: false, error: 'run 已终态,消息不予受理' }
+        },
+      }),
+      defineTool({
+        name: 'rs_workflow_resume_from',
+        description: [
+          '断点续跑/从头重跑(主循环通道,与页签 ResumePicker 同能力):目标 run 须终态或已收敛。',
+          '经挂靠机制在原会话重建种子 run:done 步骤产出继承,fromStepId 及其后代闭包重置(缺省 = 从第一个未完成步续跑);',
+          'inputs 可选覆盖模板入参。旧 run 记录保留作审计,旧 run 未消费的纠偏消息不带入新 run。',
+        ].join(''),
+        parameters: {
+          runId: { type: 'string', required: true, description: '要续跑的 run(终态)' },
+          fromStepId: { type: 'string', description: '从该步骤重来(其后代全部重置);缺省 = 断点续跑' },
+          inputs: { type: 'object', additionalProperties: true, description: '覆盖模板顶层 inputs,值必须为字符串' },
+        },
+        output: {
+          schema: { type: 'object', additionalProperties: true },
+          render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+          const store = reportStore()
+          let record
+          try { record = store.get(args.runId) } catch { record = undefined }
+          if (record === undefined) return { ok: false, error: '运行记录不存在:' + args.runId }
+          // 活跃守卫:未终态(或 driver 仍在内存)不可续跑,与页签 resume-from 同口径
+          if (registry.drivers.has(args.runId) || record.finishedAt === undefined) {
+            return { ok: false, error: '运行进行中,不可续跑' }
+          }
+          // 会话归属守卫:仅原 run 所属会话的主循环可续跑,防跨会话接管他人 run
+          if (record.sessionId !== agentIdOf(exec.agent)) {
+            return { ok: false, error: '该 run 属于其他会话,本会话不可续跑' }
+          }
+          if (args.fromStepId !== undefined && (record.plan?.steps?.some((p) => p.ref === args.fromStepId)) !== true) {
+            return { ok: false, error: 'fromStepId 不在剧本中:' + args.fromStepId }
+          }
+          if (currentRunId(exec.agent) !== undefined) {
+            return { ok: false, error: `本会话已有进行中的编排 ${currentRunId(exec.agent)},不可续跑` }
+          }
+          // 唤醒轮挂靠兜底:重启后 initiator 表空,续跑前借本调用重注册(status/resume 同款)
+          registerInitiator(agentIdOf(exec.agent), (record2, fromStepId, inputs) => startSeedRun(exec.agent, record2, fromStepId, inputs))
+          ensureResumer(exec.agent)
+          const outcome = startSeedRun(exec.agent, record, args.fromStepId, args.inputs)
+          if (!outcome.ok) return { ok: false, error: outcome.error }
+          return { ok: true, runId: outcome.runId, hint: '旧 run 未消费的纠偏消息不带入新 run;rs_workflow_status 跟踪推进' }
+        },
+      }),
+      defineTool({
+        name: 'rs_workflow_verdict',
+        description: [
+          '回写若水编排裁决(主循环裁决通道,与页签先到先得):run 处于 waiting_approval 时受理。',
+          'autoApprove=true 代审:by=main-agent + 代审意见;ask_user 转呈真人:by=user + 用户意见。裁决后 rs_workflow_resume 拉起下一段。',
+        ].join(''),
+        parameters: {
+          runId: { type: 'string', description: '要裁决的 run(缺省 = 本会话现役 run)' },
+          verdict: { type: 'string', required: true, description: 'approve = 通过;reject = 驳回(重做)' },
+          reason: { type: 'string', required: true, description: '裁决意见(审计必填):驳回=重做口径,通过=放行依据' },
+          by: { type: 'string', description: '裁决来源:main-agent=代审(缺省);user=真人转呈后的用户裁决' },
+        },
+        output: {
+          schema: { type: 'object', additionalProperties: true },
+          render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+          if (args.verdict !== 'approve' && args.verdict !== 'reject') {
+            return { ok: false, error: 'verdict 须为 approve|reject' }
+          }
+          if (typeof args.reason !== 'string' || args.reason.trim() === '') {
+            return { ok: false, error: 'reason 必填(审计口径与页签一致)' }
+          }
+          const by = args.by === 'user' ? 'user' : 'main-agent'
+          const runId = typeof args.runId === 'string' && args.runId !== '' ? args.runId : currentRunId(exec.agent)
+          if (runId === undefined) return { ok: false, error: '本会话无现役 run(编排未启动)' }
+          const driver = registry.drivers.get(runId)
+          if (driver === undefined) return { ok: false, error: '编排驱动器未注册(run 未终态但不在内存,或已终态)' }
+          const accepted = driver.handlePost({ kind: args.verdict, by, reason: args.reason })
+          const record = reportStore().get(runId)
+          if (accepted) {
+            return { ok: true, runId, status: record?.status, hint: '裁决已受理;rs_workflow_resume 拉起下一段' }
+          }
+          // 竞态口径:页签先裁时后到方不受理,但 run 可能已翻 running 且无活跃段(等 resume 拉起),
+          // 主循环须继续承担推进责任,否则 run 挂死在 running 无段状态
+          if (!driver.active && record?.status === 'running') {
+            startSegmentJob(exec.agent, driver)
+            return { ok: true, runId, status: record.status, hint: '裁决已被页签先裁(先到先得);已代为拉起下一段' }
+          }
+          return { ok: false, error: '裁决未受理(状态不符或已被页签先裁)' }
+        },
+      }),
+    ]
+    for (const tool of tools) tctx.effect(() => tctx.tools.register(tool), 'rs-workflow orchestrator: ' + tool.name)
+    // 行上下文(tool context)无 agent 属性,effect 回调在此返回 undefined 触发宿主 dispose 契约异常,
+    // 导致整个 inject 回调失败、七工具全部未注册(43267fc 引入,实机定位);清理由既有路径承担:
+    // run 终态 finishRun/unregisterInitiator 与 cancel 的 finishRun 清 activeRuns;行销毁后的
+    // stale initiator 表项在下次 start 受理时被覆盖,不产生跨会话续跑。
+  })
+  return { rejectCounts, activeRuns }
+}

package/lib/planner-gate.mjs

@@ -0,0 +1,195 @@
+// planner-gate — 规划校验闸(v5 新增,纯函数):校验主模型 PLAN_SCHEMA 提交并生成 run 执行剧本
+// 契约源 docs/rsww-v5/feat/planner-gate.md;错误/警告形态 [{ target, message }],与 template-save 一致
+
+const err = (target, message) => ({ target, message })
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v)
+const nonEmpty = (v) => typeof v === 'string' && v.trim() !== ''
+const PLACEHOLDER_RE = /\{([^{}]+)\}/g
+
+// 模板直接依赖表:显式 after;缺省 = 文档序前一步;升级步(onExhausted 目标)脱离常规图无缺省边
+export function templateDeps(parsed) {
+  const steps = Array.isArray(parsed?.steps) ? parsed.steps : []
+  const byId = new Map(steps.filter((s) => isObj(s) && typeof s.id === 'string').map((s) => [s.id, s]))
+  const escalateOnly = new Set()
+  for (const s of steps) {
+    if (isObj(s) && s.type === 'approve' && typeof s.onExhausted === 'string' && s.onExhausted !== 'blocked' && byId.has(s.onExhausted)) {
+      escalateOnly.add(s.onExhausted)
+    }
+  }
+  const order = steps.map((s, i) => (isObj(s) && typeof s.id === 'string' ? s.id : `#${i}`))
+  const deps = new Map()
+  steps.forEach((s, i) => {
+    if (!isObj(s) || typeof s.id !== 'string') return
+    let d
+    if (Array.isArray(s.after)) d = s.after
+    else if (escalateOnly.has(s.id) || i === 0) d = []
+    else {
+      // 缺省边依赖文档序最近的前一个常规步骤:升级步仅审批耗尽可达,常规步不得依赖它
+      let j = i - 1
+      while (j >= 0 && escalateOnly.has(order[j])) j--
+      d = j >= 0 ? [order[j]] : []
+    }
+    deps.set(s.id, d.filter((x) => byId.has(x) && x !== s.id))
+  })
+  return { deps, byId, order, escalateOnly }
+}
+
+// 压缩依赖:被裁剪步骤的依赖按传递闭包穿透( kept→自身;pruned→其压缩依赖集 )
+function compressed(depsOf, id, kept) {
+  if (kept.has(id)) return [id]
+  const out = []
+  for (const d of depsOf.get(id) ?? []) out.push(...compressed(depsOf, d, kept))
+  return out
+}
+
+const dedup = (arr) => [...new Set(arr)]
+
+// 占位符引用的步骤集(prompt/input/flow 中的 {stepId.out})
+function referencedSteps(step) {
+  const texts = []
+  if (typeof step.prompt === 'string') texts.push(step.prompt)
+  if (isObj(step.input)) texts.push(...Object.values(step.input).filter((v) => typeof v === 'string'))
+  if (typeof step.flow === 'string') texts.push(step.flow)
+  const refs = new Set()
+  for (const text of texts) {
+    for (const m of text.matchAll(PLACEHOLDER_RE)) {
+      const ph = m[1]
+      if (ph === 'request' || ph === 'item' || ph === 'item.index' || ph.startsWith('input.')) continue
+      const dot = ph.indexOf('.')
+      if (dot > 0) refs.add(ph.slice(0, dot))
+    }
+  }
+  return refs
+}
+
+// 主入口:gate(plan, template, expected)
+// plan = orchestrator 组装后的 PLAN_SCHEMA(request/templateId/inputs 顶层注入;brief/steps 来自 plan 工具参数)
+// 显式 plan = plan 工具参数含 steps/brief 任一字段;plan 缺省(或空对象)→ 保底全序
+export function gate(plan, template, expected) {
+  const explicit = plan != null && (plan.steps !== undefined || plan.brief !== undefined)
+  const stepsIn = explicit && Array.isArray(plan.steps) ? plan.steps : []
+  const templateId = plan != null && typeof plan.templateId === 'string' ? plan.templateId : (typeof expected?.expectedTemplateId === 'string' ? expected.expectedTemplateId : '')
+  const inputs = plan != null && isObj(plan.inputs) ? plan.inputs : {}
+
+  // #1 模板存在且 enabled(失败即短路:后续规则全部依赖模板)
+  if (templateId === '' || !isObj(template) || !isObj(template.entry) || template.entry.id !== templateId) {
+    return { ok: false, errors: [err('templateId', `模板不存在: ${templateId}`)] }
+  }
+  if (template.entry.enabled === false) {
+    return { ok: false, errors: [err('templateId', `模板已禁用: ${templateId}`)] }
+  }
+  const parsed = isObj(template.parsed) ? template.parsed : { steps: [] }
+  const { deps: depsOf, byId, escalateOnly } = templateDeps(parsed)
+
+  const errors = []
+  const warnings = []
+
+  // #1b 组合锚定
+  if (typeof expected?.expectedTemplateId === 'string' && expected.expectedTemplateId !== '' && templateId !== expected.expectedTemplateId) {
+    errors.push(err('templateId', `与本组合锚定模板不符: ${templateId}`))
+  }
+
+  const kept = new Set()
+  const indexOf = new Map()
+  if (explicit) {
+    // #2 steps 非空
+    if (!Array.isArray(plan.steps) || plan.steps.length === 0) {
+      errors.push(err('steps', '至少保留一个步骤'))
+    } else {
+      plan.steps.forEach((entry, i) => {
+        const ref = isObj(entry) ? entry.ref : entry
+        if (typeof ref !== 'string' || !byId.has(ref)) {
+          errors.push(err(`steps[${i}].ref`, `未知步骤: ${typeof ref === 'string' ? ref : JSON.stringify(ref) ?? ref}`))
+          return
+        }
+        if (kept.has(ref)) {
+          errors.push(err(`steps[${i}].ref`, `步骤重复: ${ref}`))
+          return
+        }
+        kept.add(ref)
+        indexOf.set(ref, i)
+      })
+    }
+  }
+
+  const tStepOf = (id) => byId.get(id)
+
+  if (kept.size > 0) {
+    // #5 子序列拓扑:顺序颠倒 / 审批目标与 for_each 数据源被裁 / 占位符引用被裁步
+    for (const id of kept) {
+      const s = tStepOf(id)
+      for (const d of depsOf.get(id) ?? []) {
+        if (kept.has(d)) {
+          if ((indexOf.get(d) ?? 0) > (indexOf.get(id) ?? 0)) {
+            errors.push(err('steps', `裁剪破坏依赖: ${id} 依赖 ${d},但顺序颠倒`))
+          }
+        }
+      }
+      if (s.type === 'approve' && typeof s.target === 'string' && !kept.has(s.target)) {
+        errors.push(err('steps', `approve 目标不在剧本: ${s.target}(审批步 ${id} 不可裁剪其裁决对象)`))
+      } else if (s.type === 'approve' && typeof s.target === 'string' && (indexOf.get(s.target) ?? Infinity) > (indexOf.get(id) ?? 0)) {
+        errors.push(err('steps', `裁剪破坏依赖: ${id} 依赖 ${s.target},但顺序颠倒`))
+      }
+      if (typeof s.for_each === 'string') {
+        const src = s.for_each.split('.')[0]
+        if (!kept.has(src)) errors.push(err('steps', `for_each 数据源不在剧本: ${src}`))
+      }
+      for (const ref of referencedSteps(s)) {
+        if (!kept.has(ref)) errors.push(err('steps', `裁剪破坏依赖: ${id} 依赖 ${ref},但 ${ref} 不在剧本中`))
+      }
+      // w1 审批耗尽出口被裁
+      if (s.type === 'approve' && typeof s.onExhausted === 'string' && s.onExhausted !== 'blocked' && !kept.has(s.onExhausted)) {
+        warnings.push(err('steps', `审批步 ${id} 的耗尽出口 ${s.onExhausted} 不在剧本,耗尽兜底降级为 blocked`))
+      }
+    }
+
+    // 僵尸升级步:保留升级步但其审批步被裁——永不就绪且 run 会误判 completed
+    for (const id of kept) {
+      if (!escalateOnly.has(id)) continue
+      const guarded = [...kept].some((k) => { const st = byId.get(k); return st?.type === 'approve' && st.onExhausted === id })
+      if (!guarded) errors.push(err('steps', `升级步 ${id} 保留但其审批步不在剧本:升级步须与审批步同裁同留`))
+    }
+  }
+
+  if (explicit && stepsIn.length > 0) {
+    // #6 note/done 非空
+    stepsIn.forEach((entry, i) => {
+      const ref = isObj(entry) ? entry.ref : entry
+      if (typeof ref !== 'string' || !kept.has(ref)) return
+      if (!nonEmpty(isObj(entry) ? entry.note : undefined)) errors.push(err(`steps[${i}].note`, `步骤 ${ref} 的执行要点为空`))
+      if (!nonEmpty(isObj(entry) ? entry.done : undefined)) errors.push(err(`steps[${i}].done`, `步骤 ${ref} 的验收口径为空`))
+    })
+  }
+
+  // #7 inputs 键 ⊆ 模板声明,值必须为字符串
+  const declared = isObj(parsed.inputs) ? parsed.inputs : {}
+  for (const [k, v] of Object.entries(inputs)) {
+    if (!Object.hasOwn(declared, k)) errors.push(err(`inputs.${k}`, `未声明的入参: ${k}`))
+    else if (typeof v !== 'string') errors.push(err(`inputs.${k}`, `入参必须为字符串: ${k}`))
+  }
+
+  // #8 显式 plan 时 brief 非空
+  if (explicit && !nonEmpty(plan.brief)) errors.push(err('brief', '验收口径为空'))
+
+  if (errors.length > 0) return { ok: false, errors }
+
+  // 剧本生成
+  const scriptSteps = explicit
+    ? stepsIn.map((entry) => ({ ref: entry.ref, note: typeof entry.note === 'string' ? entry.note : '', done: typeof entry.done === 'string' ? entry.done : '' }))
+    : parsed.steps.filter((s) => isObj(s) && typeof s.id === 'string').map((s) => ({ ref: s.id, note: '', done: '' }))
+  // 保底路径全序保留:压缩闭包 = 剧本全集(explicit 时 kept 已是剧本)
+  if (!explicit) for (const s of scriptSteps) kept.add(s.ref)
+  const deps = {}
+  for (const s of scriptSteps) {
+    deps[s.ref] = dedup((depsOf.get(s.ref) ?? []).flatMap((d) => compressed(depsOf, d, kept))).filter((d) => d !== s.ref)
+  }
+  if (!explicit && template.entry.autoApprove === true) {
+    warnings.push(err('plan', '保底全序且模板 autoApprove=true:代审将按模板内联口径执行,无任务级验收口径'))
+  }
+  const brief = explicit ? plan.brief.trim() : (typeof template.entry.description === 'string' ? template.entry.description : '')
+  return {
+    ok: true,
+    planScript: { source: explicit ? 'model' : 'fallback', brief, steps: scriptSteps, deps },
+    warnings,
+  }
+}