dsh-card-dispatch 0.0.0-stage → 0.1.1

package/src/split.js

@@ -0,0 +1,549 @@
+/**
+ * 需求 → 看板卡片（纯函数，无 IO、无宿主依赖）。
+ *
+ * ## 为什么只做这一件事
+ *
+ * 真机上插件自己开会话一路踩坑（`sessionController` 是网关客户端，缺 peer 就抛
+ * `throwIfAborted`/`truncatedAt`），而**任务看板插件已经把这套做通了**：它有 Host
+ * 权威台账、按卡片钉住工作区/预设/权限、自己开会话、跑完结算。所以本插件退到上游，
+ * 只负责两件事：
+ *
+ *   1. 把人写的需求 / 判据**拆**成若干张卡片；
+ *   2. 生成**看板的 HTTP action 信封**（`POST /api/task-board/action`），由页面直接投递。
+ *
+ * 执行、会话、计费、结算全部归看板。这里不碰会话、不碰网关、不碰调度。
+ *
+ * ## 拆分策略（规则式，可解释、可测）
+ *
+ * - 判据只有 1 条（或未要求并行）→ 只建**一张父卡**，prompt 里带全部判据；
+ * - 判据 ≥2 条且要求并行 → 父卡 + 每个判据组一张**子卡**（看板 `maxSubtaskDepth`
+ *   默认 1 层，所以不再往下拆）；
+ * - 每张卡的 prompt 都是**自包含**的：目标、范围、验收判据、交付要求。因为看板会在
+ *   一个新会话里跑这张卡，它读不到这里的任何上下文。
+ *
+ * 不做的：LLM 语义拆分。规则式拆分的好处是「拆成几张、每张干什么」当场可见，
+ * 不会出现「模型自己编了五个任务」这种不可解释的账单。
+ */
+
+import { createHash } from 'node:crypto'
+
+import { verdictPath } from './verdict.js'
+
+/** 单卡 prompt 里判据条目的前缀（子卡只列自己那组）。 */
+const CRITERIA_HEADING = '验收判据（完成后逐条自证）：'
+
+/** 判据条数上限：再多人也看不过来，prompt 也会被撑爆。 */
+export const MAX_CRITERIA = 30
+
+/** 单条判据字数上限：一条判据写成一段话，验收就没法逐条核对。 */
+export const MAX_CRITERIA_TEXT = 500
+
+/** 同一批卡的 id 幂等窗口：10 分钟内用同样输入再点一次，写的是同一批卡。 */
+const CREATE_IDEMPOTENCY_MS = 10 * 60 * 1000
+
+/** 运行信封的幂等窗口：短一些，避免「想重跑」被当成重复点击。 */
+const RUN_IDEMPOTENCY_MS = 5 * 60 * 1000
+
+/** 验收卡等报告的上限：开发卡迟迟不结束才有意义，正常交付时报告一出现就开始验收。 */
+export const VERIFY_WAIT_MINUTES = 120
+
+/** 等待期间的轮询间隔：太短烧上下文，太长验收反应慢。 */
+export const VERIFY_POLL_SECONDS = 60
+
+/** 交付要求：三类模型都会照做，不依赖具体仓库结构。 */
+const DELIVERY_RULES = [
+  '先读相关代码再动手，改动尽量小而且能用。',
+  '每条验收判据都要给出可复核的验证（测试、命令或截图路径），不要只说「已完成」。',
+  '只做本卡范围内的改动；发现范围外的问题，写进总结而不是顺手改。',
+  '最后用三五行总结：改了什么、怎么验证的、还有什么没做。不要贴大段代码。',
+]
+
+/** 证据要求：只有开了交付门槛才写进 prompt（关掉 = 省钱，也放弃了可复核性）。 */
+const EVIDENCE_RULES = [
+  '开工前先删掉这张卡上一轮的 `out/<本卡 id>/report.md`；报告只在最后一步写——复验时验收卡才不会把上一轮的旧报告当成本轮证据。',
+  '把交付报告写到 `out/<本卡 id>/report.md`（相对工作区根目录）。',
+  '报告里逐条写：判据 id、期望、实际、证据（命令输出 / 测试名 / 文件路径）。',
+  '带上本次改动的 commit sha；没有 commit 就写 `none` 并说明为什么。',
+  '没有报告或报告缺条目，这张卡就不算完成——验收卡会据此打回。',
+]
+
+function criteriaId(sequence) {
+  return `C-${sequence < 10 ? `0${sequence}` : sequence}`
+}
+
+/**
+ * 判据归一化（带警告）。
+ *
+ * 人只会写正文（「能算加减法」），但看板/台账的判据 id 有格式要求，
+ * 所以没写编号就按出现顺序补 `C-01`、`C-02`…；写了编号就沿用并接着往下编。
+ *
+ * 三道收敛（`/split` 可被直接 curl，服务端必须自己扛住）：
+ *   - 超过 `MAX_CRITERIA` 条只收前面的；
+ *   - 单条超过 `MAX_CRITERIA_TEXT` 字截断；
+ *   - 编号重复时重新编号，否则验收按 `criteriaId` 归卡会歧义。
+ *
+ * @param {Array<string|{id?:string,text:string}>} criteria
+ * @returns {{criteria:Array<{id:string,text:string}>, warnings:Array<string>}}
+ */
+export function normalizeCriteriaDetailed(criteria = []) {
+  let sequence = 0
+  const used = new Set()
+  const out = []
+  const warnings = []
+  let clipped = 0
+  let dropped = 0
+  let renumbered = 0
+
+  const nextId = () => {
+    sequence += 1
+    while (used.has(criteriaId(sequence))) sequence += 1
+    return criteriaId(sequence)
+  }
+
+  for (const raw of criteria) {
+    if (out.length >= MAX_CRITERIA) {
+      dropped += 1
+      continue
+    }
+    const isObject = raw !== null && typeof raw === 'object'
+    let text = String((isObject ? raw.text : raw) ?? '').trim()
+    if (text === '') continue
+    const rawId = isObject ? String(raw.id ?? '').trim() : ''
+    let id = /^C-\d{2,}$/.test(rawId) ? rawId : ''
+    if (id !== '') {
+      sequence = Math.max(sequence, Number.parseInt(id.slice(2), 10) || 0)
+    } else {
+      // 字符串形态里可能自带编号（「C-05 自定义编号」），解析出来并让后续编号接着走。
+      // 页面那边会先解析一遍，但 /split 是可直接 curl 的，服务端必须自己扛得住。
+      const explicit = /^(C-\d{2,})[\s:：、.\-—]*(.*)$/.exec(text)
+      if (explicit) {
+        id = explicit[1]
+        text = explicit[2].trim()
+        sequence = Math.max(sequence, Number.parseInt(id.slice(2), 10) || 0)
+      }
+    }
+    if (text === '') continue
+    if (id === '') {
+      id = nextId()
+    } else if (used.has(id)) {
+      id = nextId()
+      renumbered += 1
+    }
+    used.add(id)
+    if (text.length > MAX_CRITERIA_TEXT) {
+      text = `${text.slice(0, MAX_CRITERIA_TEXT - 1)}…`
+      clipped += 1
+    }
+    out.push({ id, text })
+  }
+
+  if (dropped > 0) warnings.push(`判据超过 ${MAX_CRITERIA} 条，后面的 ${dropped} 条没有收进来`)
+  if (clipped > 0) warnings.push(`有 ${clipped} 条判据超过 ${MAX_CRITERIA_TEXT} 字，已截断`)
+  if (renumbered > 0) warnings.push(`有 ${renumbered} 条判据编号重复，已重新编号`)
+  return { criteria: out, warnings }
+}
+
+/**
+ * 判据归一化（只要结果，不要警告）。
+ *
+ * @param {Array<string|{id?:string,text:string}>} criteria
+ * @returns {Array<{id:string, text:string}>}
+ */
+export function normalizeCriteria(criteria = []) {
+  return normalizeCriteriaDetailed(criteria).criteria
+}
+
+function clip(text, max) {
+  const value = String(text ?? '').replace(/\s+/g, ' ').trim()
+  return value.length <= max ? value : `${value.slice(0, max - 1)}…`
+}
+
+function criteriaLines(criteria) {
+  return criteria.map((item) => `- ${item.id} ${item.text}`).join('\n')
+}
+
+/**
+ * 拼一张卡的 prompt。做成纯函数是为了让「投给看板的东西」可审、可测。
+ *
+ * `intro` 是模型按需求写的那段「目标 / 范围 / 不要做什么」，插在最前面；
+ * 判据、交付要求、证据要求仍然由这里确定性拼上——模型可以改措辞，
+ * 但不能把「完成要交证据」这条契约写丢。
+ *
+ * @param {object} input
+ * @returns {string}
+ */
+export function buildPrompt({ title, description = '', criteria = [], scopeNote = '', cardId = null, intro = '' }) {
+  const parts = []
+  const written = String(intro ?? '').trim()
+  if (written !== '') {
+    parts.push(written)
+  } else {
+    parts.push(`目标：${title}`)
+    if (description.trim() !== '') parts.push(`背景：${description.trim()}`)
+    if (scopeNote.trim() !== '') parts.push(`范围：${scopeNote.trim()}`)
+  }
+  if (criteria.length > 0) parts.push(`${CRITERIA_HEADING}\n${criteriaLines(criteria)}`)
+  parts.push(`要求：\n${DELIVERY_RULES.map((rule, index) => `${index + 1}. ${rule}`).join('\n')}`)
+  if (cardId !== null) {
+    // 报告路径必须写死成这张卡自己的 id：执行会话读不到本插件的上下文，
+    // 只写「写到 out/」它会自己编一个目录，验收卡就找不到。
+    parts.push(
+      `交付证据：\n${EVIDENCE_RULES.map((rule, index) => `${index + 1}. ${rule.replace('<本卡 id>', cardId)}`).join('\n')}`,
+    )
+  }
+  return parts.join('\n\n')
+}
+
+/**
+ * 验收卡的 prompt。
+ *
+ * 这张卡的存在理由是基线 §3.3：**验证必须独立，不能和开发是同一张卡**。
+ * 它的产出只有两种（PASS / REJECT），REJECT 必须带 `criteriaId + expected + actual + evidencePath`——
+ * 没有定位的「不行」等于没验收，开发只能瞎改。
+ *
+ * @param {object} input
+ * @param {string} input.title
+ * @param {Array<{id:string,text:string}>} input.criteria
+ * @param {Array<{id:string,title:string}>} input.targets 待验收的卡
+ * @param {number} [input.maxReworkRounds] 打回上限（与配置同一来源，不能写死）
+ * @returns {string}
+ */
+export function buildVerifyPrompt({ title, criteria = [], targets = [], rootId = '', maxReworkRounds = 2 }) {
+  const limit = Math.max(0, Math.trunc(Number(maxReworkRounds) || 0))
+  const targetLines = targets
+    .map((target) => `- ${target.title}（卡 ${target.id}）→ 报告 out/${target.id}/report.md`)
+    .join('\n')
+  return [
+    `目标：独立验收「${title}」。只核对证据，不改实现。`,
+    '等待交付（你很可能和开发卡同时启动，报告还没写完）：',
+    [
+      `1. 开始后先等 30 秒再读第一遍报告：开发卡可能刚启动，正按自己的要求删掉上一轮的旧报告。`,
+      `2. 先看下面列出的报告是否都在；都在就进入验收。`,
+      `3. 报告必须比它所在卡最近一次执行的 startedAt 新（有任务看板工具就用 task_board_get 看 executions）：更旧的是上一轮报告，继续等，不要当本轮证据。`,
+      `4. 有缺失或报告陈旧时不要立刻 REJECT：每 ${VERIFY_POLL_SECONDS} 秒看一次（例如 PowerShell：Start-Sleep -Seconds ${VERIFY_POLL_SECONDS}）。`,
+      '5. 某张卡已经结束（executions 出现 endedAt）但仍缺本轮报告 → 立即 REJECT，summary 写「卡 <id> 已结束但报告缺失」。',
+      `6. 最多等 ${VERIFY_WAIT_MINUTES} 分钟；超时仍缺报告 → REJECT，summary 写「等待报告超时」。`,
+      '7. 报告缺失时的 REJECT 也要给出 {criteriaId, expected, actual, evidencePath}：expected 写「报告存在」，actual 写「缺失」，evidencePath 指向本应存在的 report.md。',
+    ].join('\n'),
+    '职责：',
+    [
+      '1. 逐张读上面等到的报告。',
+      '2. 对每条判据核对「期望 / 实际 / 证据」是否对得上；证据必须是能复核的东西（命令输出、测试名、文件路径、commit sha）。',
+      '3. 结论只能是 PASS 或 REJECT：',
+      '   - PASS：逐条给出判据 id 与证据位置；',
+      '   - REJECT：逐条写 {criteriaId, expected, actual, evidencePath}，缺一项都不算数。',
+      `4. 同一批最多打回 ${limit} 次；第 ${limit + 1} 次停下来把问题交给人，不要再让开发继续改（对应基线 R3）。`,
+    ].join('\n'),
+    [
+      '结论落盘（必须做，否则这次验收等于没发生）：',
+      `把结论写成 \`${verdictPath(rootId)}\`，形状：`,
+      '{"verdict":"PASS|REJECT","summary":"一句话","items":[{"criteriaId":"C-01","expected":"…","actual":"…","evidencePath":"…"}]}',
+      'REJECT 时 items 不能为空，四项都要有。插件与人只认这个文件，不认会话里的口头结论。',
+    ].join('\n'),
+    '禁止：自己动手改代码或「顺手修一下」——验证与开发合并就失去意义（基线 §3.3）；禁止凭「看起来没问题」放行。',
+    `待验收的卡：\n${targetLines}`,
+    `${CRITERIA_HEADING}\n${criteriaLines(criteria)}`,
+  ].join('\n\n')
+}
+
+/**
+ * 判据分组：把 n 条判据尽量均匀地分成若干组，组数不超过组内上限。
+ *
+ * @param {Array} criteria
+ * @param {number} maxGroups
+ * @returns {Array<Array>}
+ */
+function groupCriteria(criteria, maxGroups) {
+  const groups = Math.max(1, Math.min(maxGroups, criteria.length))
+  const out = []
+  let cursor = 0
+  for (let index = 0; index < groups; index += 1) {
+    const remaining = criteria.length - cursor
+    const size = Math.ceil(remaining / (groups - index))
+    out.push(criteria.slice(cursor, cursor + size))
+    cursor += size
+  }
+  return out.filter((group) => group.length > 0)
+}
+
+/**
+ * 只算结构，不生成信封：用来告诉模型「这次会拆成哪几张卡」。
+ *
+ * 和 splitRequirement 共用同一套分组与命名，所以模型按这些 key/title 写的提示词，
+ * 一定能落到对应的卡上（id 是随机的，key 是稳定的）。
+ *
+ * @param {object} input
+ * @returns {Array<{key:string, title:string, criteriaIds:Array<string>}>}
+ */
+export function outlineCards({
+  title,
+  description = '',
+  criteria = [],
+  parallel = true,
+  requireEvidence = false,
+} = {}) {
+  const cleanTitle = clip(String(title ?? ''), 120)
+  const normalized = normalizeCriteria(criteria)
+  const shouldSplit = parallel && normalized.length >= 2
+  const out = [{
+    key: 'root',
+    title: cleanTitle,
+    criteriaIds: shouldSplit ? [] : normalized.map((item) => item.id),
+  }]
+  if (shouldSplit) {
+    const groups = groupCriteria(normalized, 4)
+    groups.forEach((group, index) => {
+      out.push({
+        key: `part-${index + 1}`,
+        title: `${cleanTitle}（${index + 1}/${groups.length}）${clip(group[0].text, 28)}`,
+        criteriaIds: group.map((item) => item.id),
+      })
+    })
+  }
+  if (requireEvidence === true && normalized.length > 0) {
+    out.push({ key: 'verify', title: `${clip(cleanTitle, 60)}（验收）`, criteriaIds: [] })
+  }
+  void description
+  return out
+}
+
+/**
+ * 32 位十六进制 → 稳定的 UUID 形状 id。
+ *
+ * 为什么不用 randomUUID：卡片 id 稳定，同一批重试时看板能按 requestId 幂等重放，
+ * 不会「失败一次就多一棵重复的树」。看板只要求 id 是非空字符串，UUID 形状只是好认。
+ *
+ * @param {string} seed
+ * @returns {string}
+ */
+function stableId(seed) {
+  const chars = createHash('sha256').update(String(seed)).digest('hex').slice(0, 32).split('')
+  chars[12] = '4'
+  chars[16] = '89ab'[Number.parseInt(chars[16], 16) % 4]
+  const value = chars.join('')
+  return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20, 32)}`
+}
+
+/** 看板 action 信封：`{ requestId, action }`，形状由看板 `parseActionEnvelope` 校验。 */
+function envelope(action, requestId) {
+  if (typeof requestId !== 'string' || requestId === '') throw new Error('信封必须有 requestId')
+  return { requestId, action }
+}
+
+/**
+ * 把一个需求拆成「父卡 + 可选子卡」，并生成可直接投递给看板的信封。
+ *
+ * 幂等：同一份输入（标题 / 描述 / 判据 / 跑法 / 提示词，10 分钟窗口内）得到同一批
+ * 卡片 id 与 requestId。页面重试、用户连点两次，看板都会按 requestId 重放而不是再建一份。
+ *
+ * @param {object} input
+ * @param {string} input.title 需求标题
+ * @param {string} [input.description] 需求描述
+ * @param {Array} [input.criteria] 判据（字符串或 {id,text}）
+ * @param {boolean} [input.parallel] 是否按判据拆成并行子卡
+ * @param {string|null} [input.workspaceId] 钉住的工作区
+ * @param {string|null} [input.agentPreset] 钉住的 agent 预设（看板字段名是 mode）
+ * @param {string|null} [input.permission] 权限预设
+ * @param {boolean} [input.requireEvidence] 交付门槛
+ * @param {boolean} [input.teamRun] 用 teamRun 卡片
+ * @param {object} [input.intros] 模型写的开头段
+ * @param {number} [input.maxReworkRounds] 打回上限（写进验收 prompt，不能写死）
+ * @param {number} [input.now] 幂等窗口用的时间（测试可注入）
+ * @returns {{rootId:string, verifyId:string|null, cards:Array, envelopes:Array, run:object|null, warnings:Array<string>}}
+ */
+export function splitRequirement({
+  title,
+  description = '',
+  criteria = [],
+  parallel = true,
+  workspaceId = null,
+  agentPreset = null,
+  permission = 'workspace-write',
+  requireEvidence = false,
+  teamRun = false,
+  /** 模型按需求写好的开头段，按卡片 key（root / part-1 / verify）索引。 */
+  intros = {},
+  maxReworkRounds = 2,
+  now = Date.now(),
+} = {}) {
+  const cleanTitle = clip(String(title ?? ''), 120)
+  if (cleanTitle === '') throw new Error('需求标题不能为空')
+
+  const { criteria: normalized, warnings: criteriaWarnings } = normalizeCriteriaDetailed(criteria)
+  const warnings = [...criteriaWarnings]
+  const limit = Math.max(0, Math.trunc(Number(maxReworkRounds) || 0))
+  const evidenceOn = requireEvidence === true
+
+  /**
+   * 拆不拆子卡，取决于跑法：
+   * - 开了智能体团队：父卡是 Lead，子卡由它在**同一个**会话里派成 teammate，拆得越多越划算；
+   * - 没开：每张子卡都是**一条独立会话**，拆 4 条判据就是 4 次开会话，所以只建一张卡。
+   * 这条规则不放进开关表里让人二次确认：会话条数由跑法决定，不该由两个开关的组合决定。
+   */
+  const shouldSplit = teamRun === true && parallel && normalized.length >= 2
+
+  /**
+   * 父卡用不用 Lead 会话（teamRun）：
+   * - 勾了智能体团队：用，父卡当 Lead 派子卡；
+   * - 没勾但开了交付门槛：也用——只有「父卡 + 验收卡」两张，没必要各开一条会话；
+   *   父卡当 Lead 自己干活，验收卡是同一会话里的 teammate。
+   * 所以「智能体团队」仍然只决定拆不拆多张开发卡，不决定验收卡跑在哪。
+   */
+  const runAsTeam = teamRun === true || (evidenceOn && normalized.length > 0)
+
+  // 幂等种子：同一份输入 + 同一个 10 分钟窗口 = 同一批卡。
+  // 提示词也算进种子：重新让模型写过提示词就是新的一批，否则 requestId 会撞上不同 action。
+  const batchKey = createHash('sha256')
+    .update(JSON.stringify({
+      title: cleanTitle,
+      description: description.trim(),
+      criteria: normalized.map((item) => [item.id, item.text]),
+      parallel: parallel === true,
+      teamRun: teamRun === true,
+      runAsTeam: runAsTeam === true,
+      requireEvidence: evidenceOn,
+      workspaceId: workspaceId ?? null,
+      agentPreset: agentPreset ?? null,
+      permission: permission ?? null,
+      introsKey: createHash('sha256').update(JSON.stringify(intros ?? {})).digest('hex').slice(0, 16),
+      bucket: Math.floor(now / CREATE_IDEMPOTENCY_MS),
+    }))
+    .digest('hex')
+  const requestBase = `card-dispatch-${batchKey.slice(0, 20)}`
+  const rootId = stableId(`${batchKey}:root`)
+  let createIndex = 0
+  const createEnvelope = (id, input) =>
+    envelope({ kind: 'create', id, input }, `${requestBase}-create-${createIndex++}`)
+
+  // 卡片公共字段：null 表示「不指定」，绝不能写进去（看板按 exactKeys 校验，多余字段直接 400）
+  const shared = {
+    ...(workspaceId ? { workspaceId } : {}),
+    ...(agentPreset ? { mode: agentPreset } : {}),
+    ...(permission ? { permission } : {}),
+  }
+
+  const verifyWillExist = evidenceOn && normalized.length > 0
+  const rootInput = {
+    title: cleanTitle,
+    description: description.trim(),
+    prompt: buildPrompt({
+      title: cleanTitle,
+      description,
+      criteria: normalized,
+      intro: intros.root ?? '',
+      // 不拆时父卡就是干活的那张，要写报告；拆了之后父卡是协调者（teamRun 的 Lead），
+      // 它不产出报告——让验收卡去要它的报告只会误伤。
+      cardId: evidenceOn && !shouldSplit ? rootId : null,
+    }),
+    ...shared,
+    // 智能体团队只在父卡上开：看板见到根卡 teamRun=true 就只起一个 Lead 会话，
+    // 由它把每张子卡派成 teammate。子卡不能再写 teamRun，否则会被当成另一个 Lead。
+    // 交付门槛开着时即使没勾团队也走 Lead 会话：父卡 + 验收卡两张没必要开两条会话。
+    ...(runAsTeam ? { teamRun: true } : {}),
+  }
+
+  if (runAsTeam && shouldSplit) {
+    // 根卡在 teamRun 模式下就是 Lead：顺序只能写在 prompt 里——看板没有依赖字段，
+    // 靠平台排不出「先开发后验收」，只能让 Lead 自己守这个顺序。
+    // 验收卡已经和子卡一起启动并在等报告，所以这里说「等结论」，不再让它去「执行验收卡」，
+    // 否则同一张验收卡会被跑两次。
+    // 没生成验收卡时不能再提验收卡，否则执行者会去找一张不存在的卡。
+    rootInput.prompt += verifyWillExist
+      ? `\n\n流程：先派发子卡完成开发 → 等子卡交付 → 验收卡已在会话里等报告，报告齐全后会自动给出 PASS/REJECT；等它给结论再收尾。被打回最多 ${limit} 次，第 ${limit + 1} 次停下来交给人。`
+      : '\n\n流程：先派发子卡完成开发 → 等子卡交付 → 汇总结果。本次没有验收卡。'
+  } else if (runAsTeam) {
+    // 没拆子卡时根卡**就是干活的那张**（上面可能已经让它写报告），
+    // 这里不能再写「父卡不产出报告」——两句会互相打架，验收必打回。
+    rootInput.prompt += evidenceOn
+      ? '\n\n执行方式：这一轮由你自己（Lead）完成，不派子卡；按上面的交付要求产出报告。验收卡已经在同一会话里等这份报告，写完等它给出结论再收尾。'
+      : '\n\n执行方式：这一轮由你自己（Lead）完成，不派子卡。'
+  }
+
+  const cards = [{ id: rootId, key: 'root', title: cleanTitle, input: rootInput }]
+  const envelopes = [createEnvelope(rootId, rootInput)]
+
+  if (normalized.length === 0) {
+    warnings.push('这个需求没有验收判据，看板里的执行者不知道做到什么算完；建议补几条。')
+  }
+
+  if (shouldSplit) {
+    const groups = groupCriteria(normalized, 4)
+    groups.forEach((group, index) => {
+      const id = stableId(`${batchKey}:part-${index + 1}`)
+      const groupTitle = `${cleanTitle}（${index + 1}/${groups.length}）${clip(group[0].text, 28)}`
+      const input = {
+        title: groupTitle,
+        description: `需求「${cleanTitle}」的第 ${index + 1} 部分，判据：${group.map((item) => item.id).join('、')}`,
+        prompt: buildPrompt({
+          title: groupTitle,
+          description,
+          criteria: group,
+          scopeNote: `这是需求「${cleanTitle}」拆分后的第 ${index + 1}/${groups.length} 部分，只做这几条判据；其余部分由同级的其它卡负责，不要重复实现。`,
+          cardId: evidenceOn ? id : null,
+          intro: intros[`part-${index + 1}`] ?? '',
+        }),
+        parentId: rootId,
+        ...shared,
+      }
+      cards.push({ id, key: `part-${index + 1}`, title: groupTitle, input })
+      envelopes.push(createEnvelope(id, input))
+    })
+    warnings.push(
+      `拆成 ${cards.length} 张卡：父卡 1 张 + 子卡 ${groups.length} 张。子卡在看板里是并行的，所以每张都自带验收判据。`,
+    )
+  } else if (normalized.length >= 2 && teamRun !== true) {
+    warnings.push('没开智能体团队：不按判据拆子卡（每张子卡会各开一条会话），全部判据写进一张卡。')
+  } else if (normalized.length >= 2) {
+    warnings.push('没勾选并行拆分，全部判据都写进同一张卡，由一次执行完成。')
+  }
+
+  // 验收卡：只在开了交付门槛、且确实有判据可验时生成。
+  // 它是**另一张卡**而不是父卡的一部分，因为基线 §3.3 要求验证独立于开发；
+  // 同一张卡自己说「我做完了」不算验收。
+  // 和有没有开智能体团队无关：门槛是「必须有人独立核对」的意思，不能因为省一条会话就悄悄失效。
+  let verifyId = null
+  let verifyTitle = ''
+  if (evidenceOn && normalized.length > 0) {
+    verifyId = stableId(`${batchKey}:verify`)
+    // 拆过的需求逐张列子卡；单卡需求时待验收的就是父卡本身。
+    const targets = shouldSplit
+      ? cards.filter((card) => card.key !== 'root').map((card) => ({ id: card.id, title: card.title }))
+      : cards.map((card) => ({ id: card.id, title: card.title }))
+    verifyTitle = `${clip(cleanTitle, 60)}（验收）`
+    const input = {
+      title: verifyTitle,
+      description: `独立验收「${cleanTitle}」：只核对证据，不改实现。`,
+      prompt: buildVerifyPrompt({ title: cleanTitle, criteria: normalized, targets, rootId, maxReworkRounds: limit }),
+      parentId: rootId,
+      ...shared,
+    }
+    cards.push({ id: verifyId, key: 'verify', title: verifyTitle, input })
+    envelopes.push(createEnvelope(verifyId, input))
+    warnings.push('已附一张验收卡：它只读证据、只给 PASS/REJECT，和开发不是同一张卡（基线 §3.3）。')
+    // 验收卡是父卡的子卡，运行父卡时**同一次运行**就会把它带起来，不需要人再点一次。
+    // 代价是它可能比开发卡先启动，所以 prompt 里要求它等报告（见 buildVerifyPrompt）。
+    warnings.push('验收卡会随父卡一起启动并在报告齐全后自动验收，不需要手动运行；它可能比开发卡先启动，属于正常现象。')
+  }
+
+  // 会话条数：Lead 模式下所有卡都在**同一个** Lead 会话里跑（teammate 是这个会话里的下级），
+  // 所以卡多不等于会话多。这句话得说出来——否则人会以为 6 张卡就是 6 次计费。
+  if (runAsTeam && cards.length > 1) {
+    warnings.push(teamRun === true
+      ? `开智能体团队：这 ${cards.length} 张卡在同一个 Lead 会话里跑，只算 1 条会话。`
+      : `交付门槛：父卡 + 验收卡在同一个 Lead 会话里跑（验收卡是 teammate），只算 1 条会话；开发由父卡自己完成。`)
+  } else if (!runAsTeam && cards.length > 1) {
+    warnings.push(`没开智能体团队：各卡各开一条会话，这次一共 ${cards.length} 条；验收卡会等报告出现后自动验收。`)
+  }
+
+  return {
+    rootId,
+    verifyId,
+    cards,
+    envelopes,
+    run: envelope(
+      { kind: 'run', taskId: rootId },
+      `${requestBase}-run-${Math.floor(now / RUN_IDEMPOTENCY_MS)}`,
+    ),
+    warnings,
+  }
+}

package/src/verdict.js

@@ -0,0 +1,133 @@
+/**
+ * verdict.js：验收结论的**文件契约**。
+ *
+ * ## 为什么是文件，不是看板状态
+ *
+ * 「打回之后谁重跑」原本看起来只能靠读看板状态，但两条路都不通：
+ *
+ * 1. 插件读不到看板：`GET /api/task-board/state` 走的是看板自己的信任栅栏，
+ *    插件进程没有那张 cookie，实测 403；
+ * 2. 就算读到了也没用：`ExecutionRecord.result` 只记「这次执行成没成」，
+ *    不记「验收判 PASS 还是 REJECT」——验收结论只活在会话记录里。
+ *
+ * 所以把结论**写进文件**：验收卡产出 `out/<根卡 id>/verdict.json`。
+ * 文件的好处是三方都能读：人、看板里的下一次执行、以及插件（人点一下时）。
+ * 这也顺带满足基线 P3——会话状态不可重建即不存在，落盘的才存在。
+ *
+ * 这个模块只做解析与判定，不读盘、不联网，所以能逐条单测。
+ */
+
+/** verdict.json 里 REJECT 的每一项必须带齐这四个字段。 */
+const ITEM_KEYS = ['criteriaId', 'expected', 'actual', 'evidencePath']
+
+/**
+ * 解析 verdict.json。
+ *
+ * 故意严格：REJECT 不给定位信息 = 开发只能瞎改，所以「缺字段」本身就是错误，
+ * 而不是一条可以忽略的警告。
+ *
+ * @param {string|object} raw 文件内容或已解析对象
+ * @returns {{ok:boolean, verdict:string|null, items:Array, problems:Array<string>, summary:string, error:string|null}}
+ */
+export function parseVerdict(raw) {
+  const empty = { ok: false, verdict: null, items: [], problems: [], summary: '', error: null }
+  let data = raw
+  if (typeof raw === 'string') {
+    const text = raw.trim()
+    if (text === '') return { ...empty, error: 'verdict.json 是空文件' }
+    try {
+      data = JSON.parse(text)
+    } catch (error) {
+      return { ...empty, error: `verdict.json 不是合法 JSON：${error.message}` }
+    }
+  }
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    return { ...empty, error: 'verdict.json 的顶层必须是对象' }
+  }
+
+  const verdict = String(data.verdict ?? '').toUpperCase()
+  if (verdict !== 'PASS' && verdict !== 'REJECT') {
+    return { ...empty, error: `verdict 只能是 PASS 或 REJECT，收到 ${JSON.stringify(data.verdict)}` }
+  }
+
+  const items = Array.isArray(data.items) ? data.items : []
+  const problems = []
+  if (verdict === 'REJECT') {
+    if (items.length === 0) {
+      problems.push('REJECT 必须逐条列出 items：没有定位的「不行」等于没验收')
+    }
+    items.forEach((item, index) => {
+      const missing = ITEM_KEYS.filter((key) => String(item?.[key] ?? '').trim() === '')
+      if (missing.length > 0) problems.push(`items[${index}] 缺 ${missing.join('、')}`)
+    })
+  }
+
+  return {
+    ok: problems.length === 0,
+    verdict,
+    items,
+    problems,
+    summary: String(data.summary ?? '').trim(),
+    error: null,
+  }
+}
+
+/**
+ * 拿到 verdict 之后，下一步该干什么。
+ *
+ * 三种结局，正好对应基线的三条线：
+ *   - `pass`：验收通过 → 父卡可以收尾；
+ *   - `rework`：打回，且还没到上限 → 重跑开发卡（**这才是真正花钱的那一步**）；
+ *   - `escalate`：到上限 → 停下来交给人（基线 R3），不再让开发瞎改；
+ *   - `invalid`：verdict 本身不合格 → 让验收卡重做，不要拿它当依据。
+ *
+ * @param {object} input
+ * @param {object} input.parsed parseVerdict 的结果
+ * @param {object} input.config 归一化配置（用 gates.maxReworkRounds）
+ * @param {number} [input.rejectedCount] 这一批已经打回过的次数
+ * @returns {{action:'pass'|'rework'|'escalate'|'invalid', rejectedCount:number, message:string, items:Array}}
+ */
+export function decideNext({ parsed, config, rejectedCount = 0 } = {}) {
+  const previous = Math.max(0, Math.trunc(Number(rejectedCount) || 0))
+  if (parsed === undefined || parsed === null || parsed.error !== null || parsed.verdict === null) {
+    return {
+      action: 'invalid',
+      rejectedCount: previous,
+      message: `验收结论不可用：${parsed?.error ?? '没有读到结论'}；让验收卡重做一次，别拿它当依据`,
+      items: [],
+    }
+  }
+  if (!parsed.ok) {
+    return {
+      action: 'invalid',
+      rejectedCount: previous,
+      message: `验收结论不合格：${parsed.problems.join('；')}`,
+      items: parsed.items,
+    }
+  }
+  if (parsed.verdict === 'PASS') {
+    return { action: 'pass', rejectedCount: previous, message: '验收通过，这批可以收尾', items: [] }
+  }
+
+  const limit = config.gates.maxReworkRounds
+  const next = previous + 1
+  if (previous >= limit) {
+    return {
+      action: 'escalate',
+      rejectedCount: previous,
+      message: `这将是第 ${next} 次打回，超过上限 ${limit}：停下来交给人（基线 R3），不要再让开发改`,
+      items: parsed.items,
+    }
+  }
+  return {
+    action: 'rework',
+    rejectedCount: next,
+    message: `第 ${next} 次打回（上限 ${limit}）：把这几条带着证据退回开发`,
+    items: parsed.items,
+  }
+}
+
+/** 验收卡该把结论写到哪里（相对工作区根目录）。 */
+export function verdictPath(rootId) {
+  return `out/${rootId}/verdict.json`
+}