@twinsearth/dsh-master 3.3.3 → 3.3.5

package/src/channel/ws.ts

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * 最小 RFC 6455 服务端实现（不引入 `ws` 依赖）。
+ *
+ * 只覆盖本通道需要的能力：
+ *   * 握手：`Sec-WebSocket-Accept` = base64(sha1(key + GUID))；
+ *   * 收帧：客户端帧必须带掩码（RFC 要求），支持 7/16/64 位长度、分片续帧、close/ping/pong；
+ *   * 发帧：服务端文本帧不加掩码，另发 ping/close。
+ *
+ * 不做：permessage-deflate、二进制 payload 处理（收到即忽略）、扩展协商。
+ */
+
+import crypto from 'node:crypto'
+
+export const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+export const WS_MAX_PAYLOAD = 256 * 1024
+
+export const OPCODE = Object.freeze({ continuation: 0x0, text: 0x1, binary: 0x2, close: 0x8, ping: 0x9, pong: 0xa })
+
+/** 计算握手 accept 值（RFC 6455 §1.3）。 */
+export function acceptKey(clientKey) {
+  return crypto.createHash('sha1').update(String(clientKey) + WS_GUID).digest('base64')
+}
+
+/** 是否是合法的 WebSocket 升级请求；返回具名原因以便拒绝时说明。 */
+export function validateUpgradeRequest(req) {
+  const headers = req?.headers ?? {}
+  const upgrade = String(headers.upgrade ?? '').toLowerCase()
+  const connection = String(headers.connection ?? '').toLowerCase()
+  const key = String(headers['sec-websocket-key'] ?? '').trim()
+  const version = String(headers['sec-websocket-version'] ?? '').trim()
+  if (upgrade !== 'websocket') return { ok: false, code: 'not-websocket-upgrade' }
+  if (!connection.split(',').map((part) => part.trim()).includes('upgrade')) return { ok: false, code: 'missing-connection-upgrade' }
+  if (!key || Buffer.from(key, 'base64').length !== 16) return { ok: false, code: 'invalid-websocket-key' }
+  if (version !== '13') return { ok: false, code: 'unsupported-websocket-version', version }
+  return { ok: true, key, accept: acceptKey(key) }
+}
+
+/** 生成 101 响应文本。 */
+export function upgradeResponse(accept) {
+  return [
+    'HTTP/1.1 101 Switching Protocols',
+    'Upgrade: websocket',
+    'Connection: Upgrade',
+    `Sec-WebSocket-Accept: ${accept}`,
+    '', '',
+  ].join('\r\n')
+}
+
+/** 生成拒绝响应（带状态码与具名原因）。 */
+export function rejectionResponse(status, code, message) {
+  const body = JSON.stringify({ ok: false, code, message })
+  return [
+    `HTTP/1.1 ${status} ${status === 401 ? 'Unauthorized' : status === 400 ? 'Bad Request' : 'Forbidden'}`,
+    'Content-Type: application/json; charset=utf-8',
+    `Content-Length: ${Buffer.byteLength(body)}`,
+    'Connection: close',
+    '', body,
+  ].join('\r\n')
+}
+
+function encodeFrame(opcode, payloadBuffer) {
+  const length = payloadBuffer.length
+  let header = null
+  if (length < 126) {
+    header = Buffer.alloc(2)
+    header[1] = length
+  } else if (length < 65536) {
+    header = Buffer.alloc(4)
+    header[1] = 126
+    header.writeUInt16BE(length, 2)
+  } else {
+    header = Buffer.alloc(10)
+    header[1] = 127
+    header.writeBigUInt64BE(BigInt(length), 2)
+  }
+  header[0] = 0x80 | opcode // FIN + opcode
+  return Buffer.concat([header, payloadBuffer])
+}
+
+export function encodeText(value) {
+  return encodeFrame(OPCODE.text, Buffer.from(String(value), 'utf8'))
+}
+
+export function encodeClose(code = 1000, reason = '') {
+  const reasonBuffer = Buffer.from(String(reason), 'utf8')
+  const payload = Buffer.alloc(2 + reasonBuffer.length)
+  payload.writeUInt16BE(Number(code) || 1000, 0)
+  reasonBuffer.copy(payload, 2)
+  return encodeFrame(OPCODE.close, payload)
+}
+
+export function encodePing() {
+  return encodeFrame(OPCODE.ping, Buffer.alloc(0))
+}
+
+export function encodePong(payload = Buffer.alloc(0)) {
+  return encodeFrame(OPCODE.pong, Buffer.from(payload))
+}
+
+/**
+ * 增量帧解析器。`push(buffer)` 返回本次解析出的完整消息与需要回应的控制帧。
+ * 超过 maxPayload 的帧返回 error 并停止后续解析（由调用方断开连接）。
+ */
+export function createFrameParser({ maxPayload = WS_MAX_PAYLOAD } = {}) {
+  let pending = Buffer.alloc(0)
+  let fragments = []
+  let fragmentOpcode = null
+
+  function takeMessage(opcode, payload) {
+    if (opcode === OPCODE.continuation) {
+      if (fragmentOpcode === null) return { error: 'unexpected-continuation' }
+      fragments.push(payload)
+      return null
+    }
+    fragments = [payload]
+    fragmentOpcode = opcode
+    return null
+  }
+
+  return {
+    push(chunk) {
+      pending = pending.length === 0 ? Buffer.from(chunk) : Buffer.concat([pending, chunk])
+      const messages = []
+      const controls = []
+      const errors = []
+      while (pending.length >= 2) {
+        const first = pending[0]
+        const second = pending[1]
+        const fin = (first & 0x80) !== 0
+        const opcode = first & 0x0f
+        const masked = (second & 0x80) !== 0
+        let length = second & 0x7f
+        let offset = 2
+        if (length === 126) {
+          if (pending.length < offset + 2) break
+          length = pending.readUInt16BE(offset)
+          offset += 2
+        } else if (length === 127) {
+          if (pending.length < offset + 8) break
+          const big = pending.readBigUInt64BE(offset)
+          if (big > BigInt(maxPayload)) { errors.push('payload-too-large'); return { messages, controls, errors } }
+          length = Number(big)
+          offset += 8
+        }
+        if (length > maxPayload) { errors.push('payload-too-large'); return { messages, controls, errors } }
+        if (!masked) { errors.push('client-frame-must-be-masked'); return { messages, controls, errors } }
+        if (pending.length < offset + 4 + length) break
+        const mask = pending.subarray(offset, offset + 4)
+        offset += 4
+        const payload = Buffer.from(pending.subarray(offset, offset + length))
+        for (let index = 0; index < payload.length; index += 1) payload[index] ^= mask[index % 4]
+        pending = pending.subarray(offset + length)
+
+        if (opcode === OPCODE.ping) { controls.push({ type: 'ping', payload }); continue }
+        if (opcode === OPCODE.pong) { controls.push({ type: 'pong', payload }); continue }
+        if (opcode === OPCODE.close) {
+          controls.push({ type: 'close', payload })
+          fragmentOpcode = null
+          fragments = []
+          continue
+        }
+        if (opcode === OPCODE.binary) { controls.push({ type: 'binary-ignored' }); continue }
+
+        const result = takeMessage(opcode, payload)
+        if (result && result.error) { errors.push(result.error); return { messages, controls, errors } }
+        if (fin) {
+          const merged = Buffer.concat(fragments)
+          const frameOpcode = fragmentOpcode
+          fragments = []
+          fragmentOpcode = null
+          if (frameOpcode === OPCODE.text) messages.push(merged.toString('utf8'))
+          else controls.push({ type: 'binary-ignored' })
+        }
+      }
+      return { messages, controls, errors }
+    },
+  }
+}

package/src/dual/documents.ts

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+import { ASSESSMENT_CATEGORIES, planProgress } from './schema.ts'
+
+const lines = (items, render) => items.length ? items.map(render).join('\n') : '- （无）'
+const bullets = (items) => lines(items, (item) => `- ${item}`)
+const cell = (value) => String(value ?? '—').replaceAll('|', '\\|').replaceAll('\n', ' ')
+
+const CATEGORY_TITLES = {
+  completed: '1. 已完成（进度与证据）',
+  unfinished: '2. 未完成（原因与后续）',
+  blocked: '3. 无法实现 / 受阻（卡点）',
+  planned: '4. 已计划待开发',
+  conflicts: '5. 相互矛盾 / 冲突（待重新判断）',
+  ambiguities: '6. 理解歧义（待确认）',
+}
+
+export function renderPrdDocument(prd, assessment = null) {
+  return [
+    `# PRD · ${prd.title}`, '',
+    `- 文档 ID：\`${prd.id}\``,
+    `- 状态：${prd.status}`,
+    `- 优先级：${prd.priority}`,
+    `- 请求方：${prd.requester}`, '',
+    '## WHY · 解决什么问题、达成什么目标', '',
+    prd.why || prd.goal, '',
+    `**目标**：${prd.goal}`, '',
+    '## WHAT · 功能、模块、架构与结果', '',
+    bullets(prd.what), '',
+    '### 架构', '', prd.architecture || '（待补充）', '',
+    '### 模块', '',
+    lines(prd.modules, (item) => `- **${item.name}**（${item.status}）：${item.result || item.architecture || '待补充'}`), '',
+    '### 预期结果', '', bullets(prd.outcomes), '',
+    '## 约束与非目标', '',
+    '### 约束', '', bullets(prd.constraints), '',
+    '### 非目标', '', bullets(prd.nonGoals), '',
+    '## 验收标准', '', bullets(prd.acceptance), '',
+    '## 假设与待澄清问题', '',
+    '### 假设', '', bullets(prd.assumptions), '',
+    '### 待澄清', '', bullets(prd.openQuestions), '',
+    assessment ? `\n---\n\n${renderAssessmentDocument(assessment)}` : '',
+  ].join('\n').trim() + '\n'
+}
+
+export function renderAssessmentDocument(assessment) {
+  const out = [`# 产品现状盘点 · ${assessment.title}`, '', `- 盘点 ID：\`${assessment.id}\``, `- 关联 PRD：${assessment.prdId ?? '未关联'}`, '']
+  if (assessment.why) out.push('## WHY', '', assessment.why, '')
+  if (assessment.what.length) out.push('## WHAT', '', bullets(assessment.what), '')
+  for (const category of ASSESSMENT_CATEGORIES) {
+    out.push(`## ${CATEGORY_TITLES[category]}`, '')
+    const items = assessment[category]
+    out.push(lines(items, (item) => {
+      if (category === 'completed') return `- **${item.title}**（${item.progress}%）${item.detail ? `：${item.detail}` : ''}\n  - 证据：${item.evidence.join('；')}`
+      if (category === 'unfinished') return `- **${item.title}**：${item.reason}\n  - 后续：${item.nextStep || '待计划'}`
+      if (category === 'blocked') return `- **${item.title}**：${item.reason}\n  - 卡点：${item.blocker}\n  - 下一步：${item.nextStep || '待决策'}`
+      if (category === 'planned') return `- **${item.title}**（${item.priority}）：${item.plan || '待拆解'}${item.estimateMinutes ? `\n  - 估时：${item.estimateMinutes} 分钟` : ''}`
+      if (category === 'conflicts') return `- **${item.title}**：${item.question}\n  - 选项：${item.options.map((option) => `${option.value}=${option.label}`).join('；') || '待补充'}`
+      return `- **${item.title}**：${item.question}\n  - 当前理解：${item.currentInterpretation || '未形成结论'}`
+    }), '')
+  }
+  return out.join('\n').trim() + '\n'
+}
+
+export function renderProjectDocument(plan) {
+  const progress = planProgress(plan)
+  return [
+    `# 项目计划 · ${plan.title}`, '',
+    `- 计划 ID：\`${plan.id}\``,
+    `- 关联 PRD：\`${plan.prdId}\``,
+    `- 状态：${plan.status}`,
+    `- 进度：${progress.done}/${progress.total}（${progress.percent}%）`,
+    `- 总估时：${progress.estimatedMinutes} 分钟（估算，不是承诺工期）`, '',
+    '## 1. 项目会审', '', bullets(plan.projectReview), '',
+    '## 2. 项目计划（HOW / WHERE）', '', plan.how || '（待补充）', '', `**场景**：${plan.where}`, '',
+    '### WBS', '',
+    '| 步骤 | 内容 | Owner | 场景 | 估时(分钟) | 依赖 | 状态 |',
+    '|---|---|---|---|---:|---|---|',
+    ...plan.steps.map((step) => `| ${cell(step.id)} | ${cell(step.title)} | ${cell(step.owner)} | ${cell(step.where)} | ${step.estimateMinutes} | ${cell(step.dependsOn.join(', '))} | ${cell(step.status)} |`), '',
+    '## 3. 项目需求与内容', '', bullets(plan.requirements), '',
+    '## 4. 项目时间', '',
+    `- 开始时间：${plan.schedule.startAt ?? '待定'}`,
+    `- 总估时：${plan.schedule.totalEstimateMinutes} 分钟`, '',
+    lines(plan.schedule.milestones, (item) => `- **${item.title}**：${item.estimateMinutes} 分钟 · ${item.owner} · 依赖 ${item.dependsOn.join(', ') || '无'}`), '',
+    '## 5. 项目人员', '',
+    lines(plan.team, (item) => `- **${item.role}** · ${item.owner}：${item.responsibility || '待分配'}`), '',
+    '## 6. 测试、部署、交付与验收', '',
+    '### 测试', '', bullets(plan.quality.tests), '',
+    '### 部署', '', bullets(plan.quality.deployment), '',
+    '### 验收', '', bullets(plan.quality.acceptance), '',
+    '## 7. 项目结案', '',
+    plan.closure.status === 'closed' ? renderClosureDocument(plan) : '- 尚未结案；必须全部步骤完成后才能结案。',
+  ].join('\n').trim() + '\n'
+}
+
+export function renderClosureDocument(plan) {
+  const closure = plan.closure
+  return [
+    `### 结案状态：${closure.status}`, '',
+    `- 结案时间：${closure.closedAt ?? '未结案'}`,
+    `- 总结：${closure.summary || '未填写'}`, '',
+    '#### 评审报告', '', closure.reviewReport || '（待补充）', '',
+    '#### 验收记录', '', bullets(closure.acceptance), '',
+    '#### 项目资料汇总', '', bullets(closure.artifacts), '',
+  ].join('\n')
+}
+
+/** PM 的复核 + 复盘 + 总结（闭环第三步）。 */
+export function renderReviewDocument(review, { feedback = null, handoff = null } = {}) {
+  const checks = review.acceptanceChecks
+  const failed = checks.filter((check) => check.met !== true)
+  const out = [
+    `# 复核与复盘 · ${review.id}`, '',
+    `- 结论：**${review.verdict === 'accepted' ? '通过' : '退回修改'}**`,
+    `- 关联计划：${review.planId}`,
+    `- 关联 PRD：${review.prdId ?? '未关联'}`,
+    `- 反馈 ID：${review.feedbackId}`, '',
+    '## 一、复核：验收逐条核对', '',
+    '| 验收标准 | 结果 | 证据 | 备注 |',
+    '|---|---|---|---|',
+    ...checks.map((check) => `| ${cell(check.criterion)} | ${check.met ? '通过' : '未通过'} | ${cell(check.evidence.join('；') || '—')} | ${cell(check.note || '—')} |`), '',
+    failed.length > 0 ? `**未通过项**：${failed.map((check) => check.criterion).join('；')}` : '**全部验收项通过。**', '',
+  ]
+  if (feedback) {
+    out.push('## 二、执行回执（PJM 自反馈）', '', feedback.summary, '')
+    out.push(`- 步骤：${feedback.metrics.done}/${feedback.metrics.steps}（${feedback.metrics.percent}%）`)
+    out.push(`- 估时/实际：${feedback.metrics.estimatedMinutes} / ${feedback.metrics.actualMinutes} 分钟`)
+    if (feedback.deviations.length) out.push('- 偏差：', bullets(feedback.deviations))
+    if (feedback.openIssues.length) out.push('- 遗留问题：', bullets(feedback.openIssues))
+    out.push('')
+  }
+  if (handoff) {
+    out.push('## 三、交接对照', '', `- 交接包：${handoff.id}（${handoff.status}）`, `- 验收标准数：${handoff.acceptance.length}`, '')
+  }
+  out.push('## 四、复盘', '')
+  out.push('### 保持（做对了什么）', '', bullets(review.retrospective.kept), '')
+  out.push('### 改进（哪里不顺）', '', bullets(review.retrospective.improve), '')
+  out.push('### 经验（下次怎么做）', '', bullets(review.retrospective.lessons), '')
+  out.push('## 五、总结', '', review.summary, '')
+  return out.join('\n').trim() + '\n'
+}

package/src/dual/orchestrator.ts

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * PM/PJM 编排策略（3.3.5）。
+ *
+ * 解决的问题：模型知道工具清单，但不知道“现在这一步该用哪个”。让它在 7 个工具里猜，
+ * 就会出现「PRD 还没写就交接」「还有未决问题就派发」这类错误。
+ *
+ * 这里把闭环状态机写成确定性函数：给定结构化状态，返回**唯一推荐动作**与理由。
+ * 模型仍然负责内容（写 PRD、拆 WBS、判定验收），编排不替它做判断，也不产生副作用。
+ *
+ * 约束：
+ *   * 纯函数，不读全局、不写数据；
+ *   * 每个 action 都必须对应真实存在的工具名（测试会校验，防止漂移）；
+ *   * 无法推进时返回 `blocked` + 具名原因，而不是编一个动作。
+ */
+
+export const PM_ACTIONS = Object.freeze([
+  'create_prd', 'create_assessment', 'clarify', 'handoff', 'review', 'done', 'blocked',
+])
+
+export const PJM_ACTIONS = Object.freeze([
+  'take_handoff', 'return_to_pm', 'create_plan', 'dispatch', 'report', 'complete_feedback', 'close', 'done', 'blocked',
+])
+
+/** action → 真实工具名（agent preset 里注册过；测试比对）。 */
+export const ACTION_TOOL = Object.freeze({
+  create_prd: 'pm_create_prd',
+  create_assessment: 'pm_create_assessment',
+  clarify: 'pm_create_prd',
+  handoff: 'pm_handoff_to_pjm',
+  review: 'pm_review_feedback',
+  take_handoff: 'pjm_take_handoff',
+  return_to_pm: 'pjm_take_handoff',
+  create_plan: 'pjm_create_plan',
+  dispatch: 'pjm_dispatch_step',
+  report: 'pjm_report',
+  complete_feedback: 'pjm_submit_feedback',
+  close: 'pjm_close_project',
+  done: null,
+  blocked: null,
+})
+
+/**
+ * PM 的下一步：PRD → 盘点 → 澄清 → 交接 → 复核。
+ * @param {{prd?: object|null, assessment?: object|null, handoff?: object|null, feedback?: object|null, review?: object|null}} state
+ */
+export function nextPmAction(state = {}) {
+  const prd = state.prd ?? null
+  const assessment = state.assessment ?? null
+  const handoff = state.handoff ?? null
+  const feedback = state.feedback ?? null
+  const review = state.review ?? null
+
+  if (!prd) {
+    return { action: 'create_prd', tool: ACTION_TOOL.create_prd, reason: 'no-prd-yet', detail: '先写结构化 PRD（title + goal）' }
+  }
+  if (!assessment) {
+    return { action: 'create_assessment', tool: ACTION_TOOL.create_assessment, reason: 'no-assessment-yet', detail: '六类盘点必须先落库，completed 项要有证据' }
+  }
+  const openQuestions = Array.isArray(prd.openQuestions) ? prd.openQuestions.length : 0
+  const conflicts = Array.isArray(assessment.conflicts) ? assessment.conflicts.length : 0
+  if (openQuestions > 0 || conflicts > 0) {
+    return {
+      action: 'clarify',
+      tool: null,
+      reason: openQuestions > 0 ? 'open-questions-unresolved' : 'conflicts-unresolved',
+      detail: openQuestions > 0
+        ? `PRD 还有 ${openQuestions} 个未决问题，必须用 ask_user_question 一次问一个决策点`
+        : `盘点里有 ${conflicts} 个冲突，必须让用户重新判断（回复：新需求新方案）`,
+      blocking: true,
+    }
+  }
+  if (!handoff) {
+    return {
+      action: 'handoff',
+      tool: ACTION_TOOL.handoff,
+      reason: 'ready-to-handoff',
+      detail: '验收标准齐全且无未决项，打交接包给 PJM',
+      argsHint: { prdId: prd.id, assessmentId: assessment.id },
+    }
+  }
+  if (handoff.status === 'needs-clarification') {
+    return {
+      action: 'blocked',
+      tool: null,
+      reason: handoff.reason || 'handoff-not-ready',
+      detail: '交接包未就绪，先解决未决问题再重新交接',
+      blocking: true,
+    }
+  }
+  if (feedback && !review) {
+    return {
+      action: 'review',
+      tool: ACTION_TOOL.review,
+      reason: 'feedback-awaiting-review',
+      detail: 'PJM 已交反馈：逐条核对验收（met + 证据），写复盘与总结；结论必须与验收一致',
+      argsHint: { feedbackId: feedback.id },
+    }
+  }
+  if (review) {
+    return {
+      action: 'done',
+      tool: null,
+      reason: review.verdict === 'accepted' ? 'loop-accepted' : 'loop-changes-requested',
+      detail: review.verdict === 'accepted' ? '本轮闭环已通过' : 'PJM 需按复核意见重做',
+    }
+  }
+  return {
+    action: 'blocked',
+    tool: null,
+    reason: 'waiting-for-pjm',
+    detail: '等 PJM 接单并提交反馈；PM 不替它派发',
+    blocking: false,
+  }
+}
+
+/**
+ * PJM 的下一步：接单 → 计划 → 派发 → 反馈 → 结案。
+ * @param {{handoff?: object|null, plan?: object|null, feedback?: object|null}} state
+ */
+export function nextPjmAction(state = {}) {
+  const handoff = state.handoff ?? null
+  const plan = state.plan ?? null
+  const feedback = state.feedback ?? null
+
+  if (handoff && handoff.status === 'needs-clarification') {
+    return {
+      action: 'return_to_pm',
+      tool: null,
+      reason: 'handoff-needs-clarification',
+      detail: '交接包未就绪：退回 PM 澄清，不得硬开工',
+      blocking: true,
+    }
+  }
+  if (handoff && handoff.status === 'ready' && !plan) {
+    return {
+      action: 'take_handoff',
+      tool: ACTION_TOOL.take_handoff,
+      reason: 'handoff-ready',
+      detail: '接单后再拆 WBS',
+      argsHint: { handoffId: handoff.id },
+    }
+  }
+  if (!plan) {
+    return {
+      action: 'create_plan',
+      tool: ACTION_TOOL.create_plan,
+      reason: 'no-plan-yet',
+      detail: '用 pjm_create_plan 写七类项目内容，步骤必须自己拆（交接包不含 WBS）',
+    }
+  }
+  const steps = Array.isArray(plan.steps) ? plan.steps : []
+  const failed = steps.filter((step) => step.status === 'failed')
+  const running = steps.filter((step) => step.status === 'running' || step.status === 'dispatching')
+  const pending = steps.filter((step) => step.status === 'pending')
+  const blockedReport = Array.isArray(plan.reports) ? [...plan.reports].reverse().find((report) => report.status === 'blocked') : null
+
+  if (blockedReport && (blockedReport.blocker || blockedReport.summary)) {
+    return {
+      action: 'report',
+      tool: ACTION_TOOL.report,
+      reason: 'blocked-reported',
+      detail: `最近一次节点报告为阻塞：${blockedReport.blocker || blockedReport.summary}；需要 PM/用户决策后才能继续`,
+      blocking: true,
+    }
+  }
+  if (failed.length > 0) {
+    return {
+      action: 'report',
+      tool: ACTION_TOOL.report,
+      reason: 'step-failed',
+      detail: `${failed.length} 个步骤失败：如实汇报失败原因，不得写成完成`,
+      argsHint: { planId: plan.id, status: 'blocked' },
+    }
+  }
+  if (running.length > 0) {
+    return {
+      action: 'report',
+      tool: ACTION_TOOL.report,
+      reason: 'step-running',
+      detail: '有步骤在隔离执行体中运行：等结果并汇报节点，不重复派发',
+      argsHint: { planId: plan.id, status: 'progress' },
+    }
+  }
+  if (pending.length > 0) {
+    const next = pending[0]
+    return {
+      action: 'dispatch',
+      tool: ACTION_TOOL.dispatch,
+      reason: 'step-pending',
+      detail: '派发下一个待办步骤（走 fangForker.spawn；不可用即 fail-closed）',
+      argsHint: { planId: plan.id, stepId: next.id },
+    }
+  }
+  if (feedback) {
+    if (plan.status === 'closed') {
+      return { action: 'done', tool: null, reason: 'project-closed', detail: '项目已结案，等 PM 复核结论' }
+    }
+    return {
+      action: 'close',
+      tool: ACTION_TOOL.close,
+      reason: 'all-steps-done',
+      detail: '全部步骤完成且已提交反馈：结案需要总结、评审报告、验收与资料清单',
+      argsHint: { planId: plan.id },
+    }
+  }
+  return {
+    action: 'complete_feedback',
+    tool: ACTION_TOOL.complete_feedback,
+    reason: 'all-steps-done-no-feedback',
+    detail: '全部步骤完成：提交交付、偏差、遗留问题与测试证据，交给 PM 复核',
+    argsHint: { planId: plan.id },
+  }
+}
+
+/** 给 UI/测试用的紧凑摘要。 */
+export function describeAction(result) {
+  if (!result || !result.action) return 'blocked: unknown state'
+  return [result.action, result.reason, result.detail].filter(Boolean).join(' · ')
+}