dsh-card-dispatch 0.1.0 → 0.1.1

package/src/split.js

@@ -25,13 +25,31 @@
  * 不会出现「模型自己编了五个任务」这种不可解释的账单。
  */
 
-import { randomUUID } from 'node:crypto'
+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 = [
   '先读相关代码再动手，改动尽量小而且能用。',
@@ -42,51 +60,97 @@ 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 {Array<{id:string, text:string}>}
+ * @returns {{criteria:Array<{id:string,text:string}>, warnings:Array<string>}}
  */
-export function normalizeCriteria(criteria = []) {
+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'
-    const text = String((isObject ? raw.text : raw) ?? '').trim()
+    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 : ''
-    let body = text
     if (id !== '') {
-      sequence = Number.parseInt(id.slice(2), 10) || sequence
+      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]
-        body = explicit[2].trim()
-        sequence = Number.parseInt(id.slice(2), 10) || sequence
+        text = explicit[2].trim()
+        sequence = Math.max(sequence, Number.parseInt(id.slice(2), 10) || 0)
       }
     }
-    if (body === '') continue
+    if (text === '') continue
     if (id === '') {
-      sequence += 1
-      id = `C-${sequence < 10 ? `0${sequence}` : sequence}`
+      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: body })
+    out.push({ id, text })
   }
-  return out
+
+  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) {
@@ -141,22 +205,34 @@ export function buildPrompt({ title, description = '', criteria = [], scopeNote
  * @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 = '' }) {
+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. 逐张读下面列出的报告；报告不存在 = 那张卡没交付，直接 REJECT。',
+      '1. 逐张读上面等到的报告。',
       '2. 对每条判据核对「期望 / 实际 / 证据」是否对得上；证据必须是能复核的东西（命令输出、测试名、文件路径、commit sha）。',
       '3. 结论只能是 PASS 或 REJECT：',
       '   - PASS：逐条给出判据 id 与证据位置；',
       '   - REJECT：逐条写 {criteriaId, expected, actual, evidencePath}，缺一项都不算数。',
-      '4. 同一批最多打回两次；第三次停下来把问题交给人，不要再让开发继续改（对应基线 R3）。',
+      `4. 同一批最多打回 ${limit} 次；第 ${limit + 1} 次停下来把问题交给人，不要再让开发继续改（对应基线 R3）。`,
     ].join('\n'),
     [
       '结论落盘（必须做，否则这次验收等于没发生）：',
@@ -231,14 +307,35 @@ export function outlineCards({
   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) {
-  return { requestId: requestId ?? `card-dispatch-${randomUUID()}`, action }
+  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] 需求描述
@@ -247,7 +344,12 @@ function envelope(action, requestId) {
  * @param {string|null} [input.workspaceId] 钉住的工作区
  * @param {string|null} [input.agentPreset] 钉住的 agent 预设（看板字段名是 mode）
  * @param {string|null} [input.permission] 权限预设
- * @returns {{rootId:string, cards:Array, envelopes:Array, run:object|null, warnings:Array<string>}}
+ * @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,
@@ -261,22 +363,17 @@ export function splitRequirement({
   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 normalized = normalizeCriteria(criteria)
-  const warnings = []
-  const rootId = randomUUID()
-
-  // 卡片公共字段：null 表示「不指定」，绝不能写进去（看板按 exactKeys 校验，多余字段直接 400）
-  const shared = {
-    ...(workspaceId ? { workspaceId } : {}),
-    ...(agentPreset ? { mode: agentPreset } : {}),
-    ...(permission ? { permission } : {}),
-  }
-
+  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，拆得越多越划算；
@@ -285,6 +382,47 @@ export function splitRequirement({
    */
   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(),
@@ -300,20 +438,29 @@ export function splitRequirement({
     ...shared,
     // 智能体团队只在父卡上开：看板见到根卡 teamRun=true 就只起一个 Lead 会话，
     // 由它把每张子卡派成 teammate。子卡不能再写 teamRun，否则会被当成另一个 Lead。
-    ...(teamRun ? { teamRun: true } : {}),
+    // 交付门槛开着时即使没勾团队也走 Lead 会话：父卡 + 验收卡两张没必要开两条会话。
+    ...(runAsTeam ? { teamRun: true } : {}),
   }
 
-  if (teamRun && shouldSplit) {
+  if (runAsTeam && shouldSplit) {
     // 根卡在 teamRun 模式下就是 Lead：顺序只能写在 prompt 里——看板没有依赖字段，
     // 靠平台排不出「先开发后验收」，只能让 Lead 自己守这个顺序。
-    rootInput.prompt +=
-      '\n\n流程：先派发子卡完成开发 → 等子卡交付 → 再让验收卡执行 → 被打回最多两次，第三次停下来交给人。'
-  } else if (teamRun) {
-    rootInput.prompt += '\n\n执行方式：这一轮由你自己开团队完成（Lead 起 teammate），父卡不产出报告。'
+    // 验收卡已经和子卡一起启动并在等报告，所以这里说「等结论」，不再让它去「执行验收卡」，
+    // 否则同一张验收卡会被跑两次。
+    // 没生成验收卡时不能再提验收卡，否则执行者会去找一张不存在的卡。
+    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 = [envelope({ kind: 'create', id: rootId, input: rootInput })]
+  const envelopes = [createEnvelope(rootId, rootInput)]
 
   if (normalized.length === 0) {
     warnings.push('这个需求没有验收判据，看板里的执行者不知道做到什么算完；建议补几条。')
@@ -321,11 +468,8 @@ export function splitRequirement({
 
   if (shouldSplit) {
     const groups = groupCriteria(normalized, 4)
-    if (groups.length < normalized.length) {
-      // 一条判据一张卡只在判据不多时才有意义，否则一天开八张卡全是计费
-    }
     groups.forEach((group, index) => {
-      const id = randomUUID()
+      const id = stableId(`${batchKey}:part-${index + 1}`)
       const groupTitle = `${cleanTitle}（${index + 1}/${groups.length}）${clip(group[0].text, 28)}`
       const input = {
         title: groupTitle,
@@ -342,7 +486,7 @@ export function splitRequirement({
         ...shared,
       }
       cards.push({ id, key: `part-${index + 1}`, title: groupTitle, input })
-      envelopes.push(envelope({ kind: 'create', id, input }))
+      envelopes.push(createEnvelope(id, input))
     })
     warnings.push(
       `拆成 ${cards.length} 张卡：父卡 1 张 + 子卡 ${groups.length} 张。子卡在看板里是并行的，所以每张都自带验收判据。`,
@@ -357,33 +501,38 @@ export function splitRequirement({
   // 它是**另一张卡**而不是父卡的一部分，因为基线 §3.3 要求验证独立于开发；
   // 同一张卡自己说「我做完了」不算验收。
   // 和有没有开智能体团队无关：门槛是「必须有人独立核对」的意思，不能因为省一条会话就悄悄失效。
-  // 代价是没开团队时它就是第 2 条会话，所以要提前把条数说清楚（见下）。
   let verifyId = null
+  let verifyTitle = ''
   if (evidenceOn && normalized.length > 0) {
-    verifyId = randomUUID()
+    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 }))
-    const verifyTitle = `${clip(cleanTitle, 60)}（验收）`
+    verifyTitle = `${clip(cleanTitle, 60)}（验收）`
     const input = {
       title: verifyTitle,
       description: `独立验收「${cleanTitle}」：只核对证据，不改实现。`,
-      prompt: buildVerifyPrompt({ title: cleanTitle, criteria: normalized, targets, rootId }),
+      prompt: buildVerifyPrompt({ title: cleanTitle, criteria: normalized, targets, rootId, maxReworkRounds: limit }),
       parentId: rootId,
       ...shared,
     }
     cards.push({ id: verifyId, key: 'verify', title: verifyTitle, input })
-    envelopes.push(envelope({ kind: 'create', id: verifyId, input }))
+    envelopes.push(createEnvelope(verifyId, input))
     warnings.push('已附一张验收卡：它只读证据、只给 PASS/REJECT，和开发不是同一张卡（基线 §3.3）。')
+    // 验收卡是父卡的子卡，运行父卡时**同一次运行**就会把它带起来，不需要人再点一次。
+    // 代价是它可能比开发卡先启动，所以 prompt 里要求它等报告（见 buildVerifyPrompt）。
+    warnings.push('验收卡会随父卡一起启动并在报告齐全后自动验收，不需要手动运行；它可能比开发卡先启动，属于正常现象。')
   }
 
-  // 会话条数：团队模式下所有卡都在**同一个** Lead 会话里跑（teammate 是这个会话里的下级），
+  // 会话条数：Lead 模式下所有卡都在**同一个** Lead 会话里跑（teammate 是这个会话里的下级），
   // 所以卡多不等于会话多。这句话得说出来——否则人会以为 6 张卡就是 6 次计费。
-  if (teamRun === true && cards.length > 1) {
-    warnings.push(`开智能体团队：这 ${cards.length} 张卡在同一个 Lead 会话里跑，只算 1 条会话。`)
-  } else if (teamRun !== true && cards.length > 1) {
-    warnings.push(`没开智能体团队：各卡各开一条会话，这次一共 ${cards.length} 条。`)
+  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 {
@@ -391,7 +540,10 @@ export function splitRequirement({
     verifyId,
     cards,
     envelopes,
-    run: envelope({ kind: 'run', taskId: rootId }),
+    run: envelope(
+      { kind: 'run', taskId: rootId },
+      `${requestBase}-run-${Math.floor(now / RUN_IDEMPOTENCY_MS)}`,
+    ),
     warnings,
   }
 }