@mzzsfy/dsh-rs-workflow 1.0.0 → 1.0.2

package/engine/flow-exec.js

@@ -0,0 +1,23 @@
+// 单批次执行器脚本:宿主 workflowEngine 裸 vm body,globals 仅 agent/parallel/pipeline/phase/log/args,无模块语法
+const BATCH_PHASE = '若水批次'
+const NULL_OUTPUT_ERROR = '子代理未提交结构化产出'
+
+const errorText = (error) => String((error && error.message) || error)
+const settle = (callId, outputs) => outputs === null
+  ? { callId, ok: false, error: NULL_OUTPUT_ERROR }
+  : { callId, ok: true, outputs }
+
+const { calls } = args
+// v5 引擎 parallel 契约:零参 thunk 数组(每个 thunk 失败→null),不再是 promise 数组;
+// agent() options 键存在则值必须是 JSON(undefined 不行),缺省键须整键省略
+const dispatches = calls.map((call) => () => agent(call.prompt, {
+  label: call.label,
+  phase: BATCH_PHASE,
+  ...call.schema !== undefined ? { schema: call.schema } : {},
+  ...call.provider !== undefined ? { provider: call.provider } : {},
+  ...call.model !== undefined ? { model: call.model } : {},
+}).then((outputs) => settle(call.callId, outputs))
+  .catch((error) => ({ callId: call.callId, ok: false, error: errorText(error) })))
+
+const results = await parallel(dispatches)
+return { results }

package/lib/board.mjs

@@ -1,6 +1,8 @@
 // board — /api/rsww/* 路由薄分发:数据权威态在 store 单例/自有文件存储(v5/{templates,config}.json)/driver 控制队列单例,路由无业务状态
 // 运行时路由 v5 恢复:runs/run/control(approve|reject 增 by/reason)/resume-from(种子续跑,不拉段)/run-remove/release/unrelease/released
 // 规划受理不经 HTTP:rs_workflow_start 是 orchestrator 工具行(见 feat/orchestrator.md)
+// 安全边界(全仓库约定,AGENTS.md):不做 host 认证,无 Host 白名单/rebinding 防线/token 校验;
+// 认证由宿主原生 cookie/startup-auth 承担,写路由跨源防护以 Origin 同源比对为上限
 import { reportStore, ACTIVE_STATES } from './store.mjs'
 import { registry, post, initiatorOf, resumerOf } from './driver/control.mjs'
 import { validateTemplate, validateTemplateSet } from './template.mjs'
@@ -67,21 +69,26 @@ guardedRoute.post = (handler) => async (req, res) => {
   return guardedRoute(handler)(req, res)
 }
 
-function readJsonBody(req) {
+function readJsonBody(req, res) {
   return new Promise((resolve, reject) => {
     let size = 0
     const chunks = []
+    let over = false
     req.on('data', (chunk) => {
       size += chunk.length
       if (size > BODY_MAX_BYTES) {
+        // 只暂停流入并标记超限,不销毁 socket:连接毁了 guardedRoute 的 400 就送不出去
+        over = true
+        req.pause()
         reject(new Error('请求体超过上限'))
-        req.destroy()
         return
       }
-      chunks.push(chunk)
+      if (!over) chunks.push(chunk)
     })
-    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
-    req.on('error', reject)
+    req.on('end', () => { if (!over) resolve(Buffer.concat(chunks).toString('utf8')) })
+    req.on('error', () => { if (!over) reject(new Error('请求体读取失败')) })
+    // 超限后 end 不再流到(已暂停):挂 res 收尾销毁,防 socket 悬挂
+    res.on('finish', () => req.destroy())
   })
 }
 
@@ -238,11 +245,11 @@ export function registerBoardRoutes(ctx) {
       sendJson(res, 200, run)
     }), 'rsww run detail route')
     route('/api/rsww/control', guardedRoute.post(async (req, res) => {
-      const body = JSON.parse(await readJsonBody(req))
+      const body = JSON.parse(await readJsonBody(req, res))
       sendJson(res, 200, handleControl(body ?? {}))
     }), 'rsww control route')
     route('/api/rsww/resume-from', guardedRoute.post(async (req, res) => {
-      const body = JSON.parse(await readJsonBody(req))
+      const body = JSON.parse(await readJsonBody(req, res))
       const runId = typeof body.runId === 'string' ? body.runId : ''
       const record = store.get(runId)
       if (!record) throw new Error('运行记录不存在:' + runId)
@@ -255,14 +262,21 @@ export function registerBoardRoutes(ctx) {
       if (fromStepId !== undefined && record.plan?.steps?.some((p) => p.ref === fromStepId) !== true) {
         throw new Error('fromStepId 不在剧本中:' + fromStepId)
       }
-      const inputs = body.inputs && typeof body.inputs === 'object' ? body.inputs : undefined
+      // inputs 须为字符串值对象:数组/嵌套值在种子展开中失真
+      let inputs
+      if (body.inputs !== undefined && body.inputs !== null) {
+        if (typeof body.inputs !== 'object' || Array.isArray(body.inputs) || Object.values(body.inputs).some((v) => typeof v !== 'string')) {
+          throw new Error('inputs 必须为字符串值对象(键→字符串)')
+        }
+        inputs = body.inputs
+      }
       const outcome = start(record, fromStepId, inputs)
       if (!outcome.ok) throw new Error(outcome.error)
       // 纠偏消息不跨 run:旧 run 受理未消费的纠偏不带入种子(controls 属旧 run 审计)
       sendJson(res, 200, { ok: true, runId: outcome.runId, hint: '旧 run 未消费的纠偏消息不带入新 run' })
     }), 'rsww resume-from route')
     route('/api/rsww/run-remove', guardedRoute.post(async (req, res) => {
-      const body = JSON.parse(await readJsonBody(req))
+      const body = JSON.parse(await readJsonBody(req, res))
       const runId = typeof body.runId === 'string' ? body.runId : ''
       const record = store.has(runId) ? store.get(runId) : undefined
       if (record && isRunActive(runId, record)) throw new Error('运行进行中,不可删除')
@@ -292,7 +306,7 @@ export function registerBoardRoutes(ctx) {
       sendJson(res, 200, { spec: SPEC_TEXT })
     }), 'rsww spec route')
     route('/api/rsww/template-save', guardedRoute.post(async (req, res) => {
-      const body = JSON.parse(await readJsonBody(req))
+      const body = JSON.parse(await readJsonBody(req, res))
       const id = typeof body.id === 'string' ? body.id.trim() : ''
       const { parsed, json } = parseTemplateEntry(id, body)
       if (body.dryRun === true) {
@@ -311,14 +325,14 @@ export function registerBoardRoutes(ctx) {
       sendJson(res, 200, { ok: true })
     }), 'rsww template-save route')
     route('/api/rsww/template-remove', guardedRoute.post(async (req, res) => {
-      const body = JSON.parse(await readJsonBody(req))
+      const body = JSON.parse(await readJsonBody(req, res))
       const id = typeof body.id === 'string' ? body.id.trim() : ''
       const outcome = removeTemplateById(id)
       if (!outcome.ok) throw new Error(outcome.error)
       sendJson(res, 200, { ok: true })
     }), 'rsww template-remove route')
     route('/api/rsww/release', guardedRoute.post(async (req, res) => {
-      const body = JSON.parse(await readJsonBody(req))
+      const body = JSON.parse(await readJsonBody(req, res))
       const id = typeof body.id === 'string' ? body.id.trim() : ''
       const entries = readTemplates()
       const entry = entries.find((t) => t.id === id)
@@ -334,7 +348,7 @@ export function registerBoardRoutes(ctx) {
       sendJson(res, 200, { ok: true, outcome })
     }), 'rsww release route')
     route('/api/rsww/unrelease', guardedRoute.post(async (req, res) => {
-      const body = JSON.parse(await readJsonBody(req))
+      const body = JSON.parse(await readJsonBody(req, res))
       const id = typeof body.id === 'string' ? body.id.trim() : ''
       const outcome = unreleaseFlowTemplate(id)
       sendJson(res, 200, { ok: true, outcome })
@@ -343,7 +357,7 @@ export function registerBoardRoutes(ctx) {
       sendJson(res, 200, { config: normalizeConfig(loadJson('config.json', undefined)) })
     }), 'rsww config route')
     route('/api/rsww/config-save', guardedRoute.post(async (req, res) => {
-      const body = JSON.parse(await readJsonBody(req))
+      const body = JSON.parse(await readJsonBody(req, res))
       const patch = configSavePatch(body ?? {})
       const current = normalizeConfig(loadJson('config.json', undefined))
       // config.json 权威节集 = slots/budgets(data-design);templates 属 templates.json 独立存储

package/lib/driver/approve.mjs

@@ -106,7 +106,7 @@ export function applyExternalVerdict(state, script, approveStep, { verdict, comm
 }
 
 // 段 settle 负载(waiting):待裁决摘要 + 口径上下文(feat/approve-bridge.md 字段集)
-export function waitingPayload({ runId, state, script, planStepOf, approveStep }) {
+export function waitingPayload({ runId, state, script, planStepOf, approveStep, autoApprove = false }) {
   const target = state.steps[approveStep.target]
   const planStep = planStepOf.get(approveStep.id)
   const brief = planStep?.done || planStep?.note || approveStep.prompt
@@ -121,6 +121,8 @@ export function waitingPayload({ runId, state, script, planStepOf, approveStep }
       brief,
       comments: ledger?.lastComments ?? '',
       rounds: ledger?.rounds ?? 0,
+      // 模板代审口径:主循环 persona 据此决定代审(by 缺省)或转呈真人(by=user)
+      autoApprove,
     },
   }
 }

package/lib/driver/index.mjs

@@ -1,5 +1,7 @@
 // RunDriver 聚合(v5):剧本驱动;runSegment 分段推进(审批到达/暂停/终态即返回 settle 负载);
 // 外部裁决回写(waiting_approval 即时应用,paused 入队 resume 生效);取消优先;推进责任在主循环 resume
+import { readFileSync } from 'node:fs'
+import { isAbsolute, join, resolve, sep } from 'node:path'
 import { reportStore } from '../store.mjs'
 import { templateDeps } from '../planner-gate.mjs'
 import { nextBatch, scriptViewOf } from './scheduler.mjs'
@@ -88,11 +90,13 @@ export function buildSeed(record, plan, fromStepId, inputs) {
     }
   }
   state.pendingApprovals = []
-  // 终态污染标志清零:续跑后旧账不得再次收口(blocked)或无耗尽即派发升级步
+  // 终态污染标志清零:续跑后旧账不得再次收口(blocked)或无耗尽即派发升级步;
+  // escalateReady 是步级标记(scheduler 消费),须逐步清零
   state.terminalBlocked = false
-  state.escalateReady = []
   state.escalateLimitReached = false
-  state.controlSeq = record.controls?.length ?? 0
+  for (const s of Object.values(state.steps)) s.escalateReady = false
+  // 控制序号对齐新记录:续跑生成全新 store 记录(controls 从空起),沿用旧计数会吞掉新记录前缀消息
+  state.controlSeq = 0
   return state
 }
 
@@ -123,27 +127,46 @@ export class RunDriver {
     this.subordinate = subordinate
     // 编排子代理的挂载父 agent(与 workflow 工具链对齐;undefined 时引擎派发行为未定义)
     this.parent = parent
+    // spec §8 doc:<相对路径>:读会话工作区文件,缺失不阻断(空串);resolve 限定在 workspace 内防路径逃逸
+    const base = resolve(workspace || process.cwd())
+    this.readDoc = (rel) => {
+      const target = resolve(base, rel)
+      if (!target.startsWith(base + sep) && target !== base) return ''
+      try { return readFileSync(target, 'utf8') } catch { return '' }
+    }
   }
 
   // 段推进唯一入口:跑到下一个段边界(审批到达/暂停/终态)返回 settle 负载;orchestrator 包装为 continuable job
   async runSegment() {
+    // 重入防护:在飞段由 settlePromise 承载(取消方 await 它收敛,而非重入第二个 loop)
+    if (this.active) return this.settlePromise ?? this.terminalPayload()
     if (this.finished || TERMINAL_STATES.has(this.state.status)) {
       return this.terminalPayload()
     }
     this.active = true
-    try {
-      this.drainPendingApprovals()
-      return await this.loop()
-    } catch (e) {
-      if (this.signal.aborted) {
-        this.finish('cancelled', CANCELLED_SUMMARY)
+    this.settlePromise = (async () => {
+      try {
+        this.drainPendingApprovals()
+        return await this.loop()
+      } catch (e) {
+        if (this.signal.aborted) {
+          this.finish('cancelled', CANCELLED_SUMMARY)
+          return this.terminalPayload()
+        }
+        this.finish('failed', `驱动器异常:${e?.message ?? e}`)
         return this.terminalPayload()
+      } finally {
+        this.active = false
+        this.settlePromise = undefined
       }
-      this.finish('failed', `驱动器异常:${e?.message ?? e}`)
-      return this.terminalPayload()
-    } finally {
-      this.active = false
-    }
+    })()
+    return this.settlePromise
+  }
+
+  /** 取消并等待在飞段收敛(无在飞段时即时收敛) */
+  async cancelAndSettle() {
+    this.cancel()
+    if (this.settlePromise !== undefined) await this.settlePromise.catch(() => {})
   }
 
   startPersist() {
@@ -159,6 +182,8 @@ export class RunDriver {
     if (this.finished || TERMINAL_STATES.has(this.state.status)) return
     // 统一转 paused(与 waiting_approval 互斥,paused 优先);活跃段在飞批次收敛后于段顶 settle
     this.state.status = 'paused'
+    // 暂停即撤销先前的恢复意图,否则陈旧标记会让守门持续催 resume
+    this.awaitingResume = false
     this.persistState()
   }
 
@@ -243,6 +268,8 @@ export class RunDriver {
         this.state.redoInfo = { [route.redoTarget]: { comments: route.comments, prevOutputs: route.prevOutputs } }
       }
     }
+    // 与 waiting 直裁路径同款收口:残留 waitingApproval 会让后续 pause 期裁决对非等待步幽灵生效
+    this.state.waitingApproval = undefined
     this.store.update({ runId: this.runId, waiting: null })
   }
 
@@ -266,6 +293,9 @@ export class RunDriver {
   }
 
   persistState() {
+    // 嵌套子流程与父共享同 runId 记录:子状态落盘会覆盖父的全局 state,崩溃后续跑种子即失真;
+    // 子流程中间态不落盘,flow 步结束后由父 persistState 兜底
+    if (this.subordinate) return
     this.store.update({ runId: this.runId, state: this.state, status: this.state.status })
   }
 
@@ -343,8 +373,10 @@ export class RunDriver {
         const step = batch.step
         this.state.status = 'waiting_approval'
         this.state.waitingApproval = step.id
+        // 模板代审口径落 state:进程重启后 status 工具仍可透出
+        this.state.waitingAutoApprove = this.template?.autoApprove === true
         this.persistState()
-        const payload = waitingPayload({ runId: this.runId, state: this.state, script: this.script, planStepOf: this.planStepOf, approveStep: step })
+        const payload = waitingPayload({ runId: this.runId, state: this.state, script: this.script, planStepOf: this.planStepOf, approveStep: step, autoApprove: this.template?.autoApprove === true })
         // 待裁决摘要落盘:页签 /run 路由据此渲染审批上下文
         this.store.update({ runId: this.runId, waiting: payload.waiting })
         return payload

package/lib/driver/runner.mjs

@@ -48,7 +48,7 @@ function rotateCursor(state, slotKey) {
   state.slotCursor[slotKey] = (state.slotCursor[slotKey] ?? 0) + 1
 }
 
-// 单批次:组 Batch → engine.start → 收敛逐 call 记账。返回 {results, cancelled}
+// 单批次:组 Batch → engine.start → 收敛逐 call 记账。返回 {settled, cancelled}
 export async function runBatch({ state, script, template, batch, ctx }) {
   const { store, runId, engine, parent, signal } = ctx
   const calls = []
@@ -87,8 +87,9 @@ export async function runBatch({ state, script, template, batch, ctx }) {
   }
 
   let outcome
+  let run
   try {
-    const run = engine.start({
+    run = engine.start({
       script: FLOW_EXEC_SOURCE,
       args: { calls },
       // 宿主 meta 契约:description 必填非空;phases 必须为 {title} 对象数组(dsh-workflow-worker-thread meta 校验)
@@ -104,15 +105,20 @@ export async function runBatch({ state, script, template, batch, ctx }) {
   } catch (e) {
     if (signal?.aborted) return { cancelled: true }
     outcome = { results: calls.map((c) => ({ callId: c.callId, ok: false, error: String(e?.message ?? e) })) }
+  } finally {
+    // 宿主契约:caller must dispose every run(否则 worker 线程泄漏);engine.start 同步抛时 run 为空
+    await run?.dispose?.().catch?.(() => {})
   }
   if (signal?.aborted) return { cancelled: true }
   // 引擎 run.result 契约:{ value(脚本返回值), stopReason, error?, agentsStarted }
-  // stopReason 非 completed(如 cancelled/error)时 value 不可信,全部调用按失败记账
+  // stopReason 非 completed(如 error)时 value 不可信,全部调用统一按失败记账
+  let results
   if (outcome?.stopReason !== undefined && outcome?.stopReason !== 'completed') {
     const reason = String(outcome?.error ?? outcome?.stopReason)
-    return { results: calls.map((c) => ({ callId: c.callId, ok: false, error: reason })) }
+    results = calls.map((c) => ({ callId: c.callId, ok: false, error: reason }))
+  } else {
+    results = outcome?.value?.results ?? outcome?.results ?? []
   }
-  const results = outcome?.value?.results ?? outcome?.results ?? []
   const settled = []
   for (const result of results) {
     const meta = callMeta.get(result.callId)

package/lib/driver/scheduler.mjs

@@ -45,7 +45,8 @@ function expandForEach(state, step) {
   const list = sourceList(state, step)
   if (list === null) return
   s.instances = list.map((item, index) => ({
-    key: `#${index + 1}`, index, item, status: 'pending', outputs: null, failCount: 0, carry: null,
+    // index 1 基(与 key #N 及 spec {item.index} 序号口径一致)
+    key: `#${index + 1}`, index: index + 1, item, status: 'pending', outputs: null, failCount: 0, carry: null,
   }))
 }
 

package/lib/guard.mjs

@@ -0,0 +1,67 @@
+// 会话守门:轮次将停时判定本会话编排是否欠动作(persona 判据 3 的机器化执行)
+// 判据来源:running 且无活跃段 job → 欠 resume;paused 且 awaitingResume → 欠 resume;
+// waiting_approval → 欠裁决。终态与无现役 run 不拦。
+// 拦截手段由调用方承担(agent.steer 投喂提醒消息,机器重读 inbox 后继续跑)。
+
+// 单个欠动作周期的提醒上限:弱模型可能忽略首次提醒,但无限提醒会烧 token 死循环。
+// 计数在轮次不欠动作时清零,故多步编排的每个欠动作周期各自享有上限,而非全 run 共享。
+export const MAX_NUDGE = 2
+
+const ACTION_OF_STATUS = {
+  waiting_approval: { need: '裁决', text: '等待裁决' },
+  paused: { need: 'resume', text: '已暂停' },
+}
+
+/** 判据:record 状态 + driver 活跃度 → 是否欠动作;无现役 run / 终态 / 段在飞均返回 undefined */
+export function pendingOf(record, driver) {
+  if (record === undefined) return undefined
+  if (record.status === 'running') {
+    // 段在飞即正常等待:段 job settle 会经完成通知唤醒主循环,此时轮次停是合理行为
+    return driver?.active === true ? undefined : { need: 'resume', text: '运行中待拉起' }
+  }
+  const known = ACTION_OF_STATUS[record.status]
+  if (known === undefined) return undefined
+  if (record.status === 'paused' && driver?.awaitingResume !== true) {
+    // paused 且页签未发恢复:裁决已入队的 resume 拉段仍欠——段首生效前欠动作不变
+    if ((record.state?.pendingApprovals?.length ?? 0) > 0) return { need: 'resume', text: '已暂停(待生效裁决)' }
+    return undefined
+  }
+  return known
+}
+
+/** 提醒计数闸:按欠动作周期独立计数,超上限返回 false(调用方改记告警,不再 steer) */
+export function createNudgeGate(maxNudge = MAX_NUDGE) {
+  const counts = new Map()
+  const warned = new Set()
+  return {
+    take(runId) {
+      const used = counts.get(runId) ?? 0
+      if (used >= maxNudge) return false
+      counts.set(runId, used + 1)
+      return true
+    },
+    clear(runId) {
+      counts.delete(runId)
+      warned.delete(runId)
+    },
+    used(runId) {
+      return counts.get(runId) ?? 0
+    },
+    /** 首次触顶返回 true,此后false(告警只一次;clear 重置) */
+    exhausted(runId) {
+      if ((counts.get(runId) ?? 0) < maxNudge) return false
+      if (warned.has(runId)) return false
+      warned.add(runId)
+      return true
+    },
+  }
+}
+
+/** 提醒文案:给出 runId / 状态 / 欠动作,并指向应调用的工具 */
+export function nudgeText(runId, pending) {
+  // waiting_approval 有合法终止路径(转呈真人后等输入),文案带豁免以免误伤已处置的轮次
+  const dispense = pending.need === '裁决'
+    ? '裁决按模板 autoApprove 决定代审或转呈真人;若已转呈真人并等待其输入,则本轮无需再动作,可直接结束轮次。'
+    : '欠 resume 调 rs_workflow_resume 补拉。'
+  return `[若水守门] 本会话编排 ${runId} 未终态(状态=${pending.text},欠动作=${pending.need})。请立即调用 rs_workflow_status 查看并按流程纪律处置:${dispense}处置完成后才可结束轮次。`
+}