dsh-card-dispatch 0.0.0-stage → 0.1.0

package/src/prompts-llm.js

@@ -0,0 +1,104 @@
+/**
+ * prompts-llm.js：让模型按需求给每张卡写「提示词开头」。
+ *
+ * 结构不由模型决定（拆几张、哪几条判据一组仍由 split.js 的规则算），模型只写
+ * 每张卡开头那段「目标 / 范围 / 明确不要做什么」。这样账单可预期，
+ * 而且「完成要交证据」这类硬要求仍由我们确定性地拼在后面，不会被模型写丢。
+ */
+
+import { callModel, extractJsonObject, MODEL_TIMEOUT_MS } from './model-call.js'
+
+/** 一段开头最少多少字（太短就是没写）。 */
+const MIN_INTRO = 12
+
+/** 一段开头最多多少字（长了会挤掉判据与交付要求）。 */
+const MAX_INTRO = 900
+
+export const PROMPTS_SYSTEM = [
+  '你给任务卡写「提示词」的开头段：执行者会在一张新会话里读这段话干活，它看不到任何其它上下文。',
+  '只输出一个 JSON 对象，不要解释：{"cards":[{"key":"root","intro":"..."}]}',
+  '',
+  '每段 intro 写 3 到 6 行，依次说清：',
+  '- 目标：这一步要交付什么；',
+  '- 范围：只碰哪些文件 / 模块 / 场景；',
+  '- 不要做什么：最容易顺手做错的那一两件事。',
+  '',
+  '规则：',
+  '- key 必须原样使用给你的那一个，不要自己新增卡、不要合并卡。',
+  '- 每段都要自包含：不写「同上」「参见前面」，不引用别张卡才能看懂的话。',
+  '- 保留需求里出现的具体数字、型号、接口名；不要补需求没提的功能。',
+  '- 只写开头段，不要重复判据列表、不要写交付证据的要求（那些会由系统拼在后面）。',
+  '- 用需求本来使用的语言写。',
+].join('\n')
+
+/**
+ * 把「需求原文 + 这张卡负责什么」整理成给模型的一次提问。
+ *
+ * @param {object} input
+ * @param {string} input.requirement 需求原文（标题 + 描述）
+ * @param {Array<{key:string,title:string,criteriaIds?:Array<string>,scope?:string}>} input.cards
+ * @returns {string}
+ */
+export function buildBriefing({ requirement = '', cards = [] }) {
+  const cardLines = cards.map((card) => {
+    const ids = (card.criteriaIds ?? []).join('、')
+    return [
+      `- key: ${card.key}`,
+      `  卡片标题：${card.title}`,
+      ids === '' ? '  负责判据：无（这是协调 / 验卡）' : `  负责判据：${ids}`,
+      card.scope === undefined ? '' : `  说的范围：${card.scope}`,
+    ].filter((line) => line !== '').join('\n')
+  })
+  return [`需求原文：\n${requirement.trim()}`, '要写开头段的卡：', cardLines.join('\n')].join('\n\n')
+}
+
+/**
+ * 解析模型回复：只要 key 认得、字数够的段落。
+ *
+ * @param {string} reply
+ * @param {Array<string>} [allowedKeys]
+ * @returns {Record<string,string>}
+ */
+export function parsePromptsReply(reply, allowedKeys) {
+  const payload = extractJsonObject(reply)
+  const raw = Array.isArray(payload?.cards) ? payload.cards : []
+  const allowed = Array.isArray(allowedKeys) && allowedKeys.length > 0 ? new Set(allowedKeys) : undefined
+  const out = {}
+  for (const item of raw) {
+    const key = String(item?.key ?? '').trim()
+    if (key === '') continue
+    if (allowed !== undefined && !allowed.has(key)) continue
+    if (Object.prototype.hasOwnProperty.call(out, key)) continue
+    const intro = String(item?.intro ?? '').replace(/\r/g, '').trim().slice(0, MAX_INTRO)
+    if (intro.length < MIN_INTRO) continue
+    out[key] = intro
+  }
+  return out
+}
+
+/**
+ * 给这些卡写开头段。
+ *
+ * @param {object} input
+ * @param {any} input.llm
+ * @param {{provider:string, model:string}} input.route
+ * @param {string} input.requirement
+ * @param {Array<{key:string,title:string,criteriaIds?:Array<string>,scope?:string}>} input.cards
+ * @param {number} [input.timeoutMs]
+ * @returns {Promise<{ok:boolean, intros:Record<string,string>, error:string|null}>}
+ */
+export async function writeCardIntros({ llm, route, requirement = '', cards = [], timeoutMs = MODEL_TIMEOUT_MS } = {}) {
+  if (cards.length === 0) return { ok: false, intros: {}, error: '没有要写提示词的卡' }
+  const reply = await callModel({
+    llm,
+    route,
+    system: PROMPTS_SYSTEM,
+    text: buildBriefing({ requirement, cards }),
+    timeoutMs,
+  })
+  if (!reply.ok) return { ok: false, intros: {}, error: reply.error }
+  const intros = parsePromptsReply(reply.reply, cards.map((card) => card.key))
+  const written = Object.keys(intros).length
+  if (written === 0) return { ok: false, intros: {}, error: '模型没写出可用的提示词（回复不是约定的 JSON 或太短）' }
+  return { ok: true, intros, error: written < cards.length ? `有 ${cards.length - written} 张卡的提示词没写成，按模板补` : null }
+}

package/src/selfcheck.js

@@ -0,0 +1,117 @@
+/**
+ * selfcheck.js：开机体检，纯函数。
+ *
+ * 为什么要体检而不是「自动纠正」：插件改不了部署设置（委派深度、权限预设、计费），
+ * 偷偷改配置只会让人以为组织图能跑、实际跑到一半才炸。所以这里的产出是**结论 + 一句
+ * 该怎么办**，由面板和启动日志展示。
+ *
+ * 判据只有一条：**fatal 必须为零**。warn 是「能跑但会难受」，info 是「知道了就行」。
+ *
+ * facts 全部由调用方注入（不在这里读盘/读宿主），这样每条分支都能被单测锁住。
+ */
+
+/**
+ * @typedef {object} Facts
+ * @property {number|null} [subagentDepthMax] 部署允许的最大子智能体递归深度；未知传 null
+ * @property {boolean|null} [boardReachable] 任务看板 HTTP 是否可达；未知传 null
+ * @property {boolean|null} [boardTeamRun] 看板是否支持 teamRun 卡片（父卡起 Lead）
+ * @property {number|null} [workspaceCount] 已知工作区数量
+ */
+
+const FINDINGS = Object.freeze({
+  'ORG-DEPTH': {
+    severity: 'fatal',
+    title: '委派深度不足，主管带不了人',
+    hint: '设置 → 子智能体 → 最大递归深度 改成 2（0 = 禁用、1 = 只有主 Agent 能派生）',
+  },
+  'ORG-DEPTH-UNKNOWN': {
+    severity: 'warn',
+    title: '委派深度未知',
+    hint: '到 设置 → 子智能体 确认「最大递归深度」是否为 2；插件读不到这个部署设置，只能提示',
+  },
+  'BOARD-UNREACHABLE': {
+    severity: 'warn',
+    title: '执行层（任务看板）不可达',
+    hint: '插件只产出计划与卡片；看板不可达时卡片发不出去，确认 @linxin666/dsh-client-ui-task-board 已启用',
+  },
+  'BOARD-UNKNOWN': {
+    severity: 'info',
+    title: '执行层可达性未检测',
+    hint: '在面板点一次「体检」即可拿到结果（会发一个只读请求，不花钱）',
+  },
+  'TEAMRUN-UNSUPPORTED': {
+    severity: 'warn',
+    title: '看板不支持 teamRun',
+    hint: '关闭 execution.teamRun，退化为普通级联；否则父卡不会起 Lead，主管层不存在',
+  },
+  'NO-WORKSPACE': {
+    severity: 'warn',
+    title: '没有指定工作区',
+    hint: '卡片不钉工作区时会回退到「最近改动的那个」，对自动跑卡是隐患；在面板里显式选一个',
+  },
+  'PLAN-GATE-OFF': {
+    severity: 'warn',
+    title: '计划闸关着但总开关开着',
+    hint: '还没批准的计划也会直接开跑 = 直接花钱；建议保持 gates.requirePlanApproval = true',
+  },
+  'EVIDENCE-OFF': {
+    severity: 'warn',
+    title: '交付门槛关着',
+    hint: '没有 commit / 报告也算完成，自动跑卡时无法复核；建议保持 gates.requireEvidence = true',
+  },
+  DISABLED: {
+    severity: 'info',
+    title: '总开关关闭',
+    hint: '当前只做拆分与填卡，不会开任何会话、不产生费用',
+  },
+})
+
+/**
+ * 跑一遍体检。
+ *
+ * @param {object} input
+ * @param {object} input.config 归一化配置（决定「应该是什么样」）
+ * @param {Facts} [input.facts] 外部注入的事实（决定「实际是什么样」）
+ * @returns {{ok:boolean, findings:Array<object>}}
+ */
+export function runSelfCheck({ config, facts = {} } = {}) {
+  const findings = []
+  const add = (id, detail) => {
+    const base = FINDINGS[id]
+    if (!base) return
+    findings.push({ id, severity: base.severity, title: base.title, detail, hint: base.hint })
+  }
+
+  const requiredDepth = config.org?.depthRequired ?? 2
+  const depth = facts.subagentDepthMax
+  if (depth === null || depth === undefined) {
+    add('ORG-DEPTH-UNKNOWN', `插件读不到部署的子智能体深度，按需要 ${requiredDepth} 层处理`)
+  } else if (Number(depth) < requiredDepth) {
+    add('ORG-DEPTH', `当前最大递归深度 ${depth}，低于所需的 ${requiredDepth}：成员（主管）无法再派生部门人员`)
+  }
+
+  const board = facts.boardReachable
+  if (board === false) add('BOARD-UNREACHABLE', '调用 /api/task-board 失败')
+  else if (board === null || board === undefined) add('BOARD-UNKNOWN', '尚未探测')
+
+  if (facts.boardTeamRun === false && config.execution?.teamRun === true) {
+    add('TEAMRUN-UNSUPPORTED', '已要求 teamRun 卡片，但看板侧没有这个能力')
+  }
+
+  if (facts.workspaceCount === 0) {
+    add('NO-WORKSPACE', '工作区列表为空')
+  }
+
+  if (config.enabled === true && config.gates?.requirePlanApproval !== true) {
+    add('PLAN-GATE-OFF', 'enabled=true 且 requirePlanApproval=false')
+  }
+  if (config.enabled === true && config.gates?.requireEvidence !== true) {
+    add('EVIDENCE-OFF', 'enabled=true 且 requireEvidence=false')
+  }
+  if (config.enabled !== true) {
+    add('DISABLED', 'enabled=false')
+  }
+
+  const ok = findings.every((item) => item.severity !== 'fatal')
+  return { ok, findings }
+}

package/src/split.js

@@ -0,0 +1,397 @@
+/**
+ * 需求 → 看板卡片（纯函数，无 IO、无宿主依赖）。
+ *
+ * ## 为什么只做这一件事
+ *
+ * 真机上插件自己开会话一路踩坑（`sessionController` 是网关客户端，缺 peer 就抛
+ * `throwIfAborted`/`truncatedAt`），而**任务看板插件已经把这套做通了**：它有 Host
+ * 权威台账、按卡片钉住工作区/预设/权限、自己开会话、跑完结算。所以本插件退到上游，
+ * 只负责两件事：
+ *
+ *   1. 把人写的需求 / 判据**拆**成若干张卡片；
+ *   2. 生成**看板的 HTTP action 信封**（`POST /api/task-board/action`），由页面直接投递。
+ *
+ * 执行、会话、计费、结算全部归看板。这里不碰会话、不碰网关、不碰调度。
+ *
+ * ## 拆分策略（规则式，可解释、可测）
+ *
+ * - 判据只有 1 条（或未要求并行）→ 只建**一张父卡**，prompt 里带全部判据；
+ * - 判据 ≥2 条且要求并行 → 父卡 + 每个判据组一张**子卡**（看板 `maxSubtaskDepth`
+ *   默认 1 层，所以不再往下拆）；
+ * - 每张卡的 prompt 都是**自包含**的：目标、范围、验收判据、交付要求。因为看板会在
+ *   一个新会话里跑这张卡，它读不到这里的任何上下文。
+ *
+ * 不做的：LLM 语义拆分。规则式拆分的好处是「拆成几张、每张干什么」当场可见，
+ * 不会出现「模型自己编了五个任务」这种不可解释的账单。
+ */
+
+import { randomUUID } from 'node:crypto'
+
+import { verdictPath } from './verdict.js'
+
+/** 单卡 prompt 里判据条目的前缀（子卡只列自己那组）。 */
+const CRITERIA_HEADING = '验收判据（完成后逐条自证）：'
+
+/** 交付要求：三类模型都会照做，不依赖具体仓库结构。 */
+const DELIVERY_RULES = [
+  '先读相关代码再动手，改动尽量小而且能用。',
+  '每条验收判据都要给出可复核的验证（测试、命令或截图路径），不要只说「已完成」。',
+  '只做本卡范围内的改动；发现范围外的问题，写进总结而不是顺手改。',
+  '最后用三五行总结：改了什么、怎么验证的、还有什么没做。不要贴大段代码。',
+]
+
+/** 证据要求：只有开了交付门槛才写进 prompt（关掉 = 省钱，也放弃了可复核性）。 */
+const EVIDENCE_RULES = [
+  '把交付报告写到 `out/<本卡 id>/report.md`（相对工作区根目录）。',
+  '报告里逐条写：判据 id、期望、实际、证据（命令输出 / 测试名 / 文件路径）。',
+  '带上本次改动的 commit sha；没有 commit 就写 `none` 并说明为什么。',
+  '没有报告或报告缺条目，这张卡就不算完成——验收卡会据此打回。',
+]
+
+/**
+ * 判据归一化。
+ *
+ * 人只会写正文（「能算加减法」），但看板/台账的判据 id 有格式要求，
+ * 所以没写编号就按出现顺序补 `C-01`、`C-02`…；写了编号就沿用并接着往下编。
+ *
+ * @param {Array<string|{id?:string,text:string}>} criteria
+ * @returns {Array<{id:string, text:string}>}
+ */
+export function normalizeCriteria(criteria = []) {
+  let sequence = 0
+  const out = []
+  for (const raw of criteria) {
+    const isObject = raw !== null && typeof raw === 'object'
+    const 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
+    } 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
+      }
+    }
+    if (body === '') continue
+    if (id === '') {
+      sequence += 1
+      id = `C-${sequence < 10 ? `0${sequence}` : sequence}`
+    }
+    out.push({ id, text: body })
+  }
+  return out
+}
+
+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 待验收的卡
+ * @returns {string}
+ */
+export function buildVerifyPrompt({ title, criteria = [], targets = [], rootId = '' }) {
+  const targetLines = targets
+    .map((target) => `- ${target.title}（卡 ${target.id}）→ 报告 out/${target.id}/report.md`)
+    .join('\n')
+  return [
+    `目标：独立验收「${title}」。只核对证据，不改实现。`,
+    '职责：',
+    [
+      '1. 逐张读下面列出的报告；报告不存在 = 那张卡没交付，直接 REJECT。',
+      '2. 对每条判据核对「期望 / 实际 / 证据」是否对得上；证据必须是能复核的东西（命令输出、测试名、文件路径、commit sha）。',
+      '3. 结论只能是 PASS 或 REJECT：',
+      '   - PASS：逐条给出判据 id 与证据位置；',
+      '   - REJECT：逐条写 {criteriaId, expected, actual, evidencePath}，缺一项都不算数。',
+      '4. 同一批最多打回两次；第三次停下来把问题交给人，不要再让开发继续改（对应基线 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
+}
+
+/** 看板 action 信封：`{ requestId, action }`，形状由看板 `parseActionEnvelope` 校验。 */
+function envelope(action, requestId) {
+  return { requestId: requestId ?? `card-dispatch-${randomUUID()}`, action }
+}
+
+/**
+ * 把一个需求拆成「父卡 + 可选子卡」，并生成可直接投递给看板的信封。
+ *
+ * @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] 权限预设
+ * @returns {{rootId:string, 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 = {},
+} = {}) {
+  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 evidenceOn = requireEvidence === true
+  /**
+   * 拆不拆子卡，取决于跑法：
+   * - 开了智能体团队：父卡是 Lead，子卡由它在**同一个**会话里派成 teammate，拆得越多越划算；
+   * - 没开：每张子卡都是**一条独立会话**，拆 4 条判据就是 4 次开会话，所以只建一张卡。
+   * 这条规则不放进开关表里让人二次确认：会话条数由跑法决定，不该由两个开关的组合决定。
+   */
+  const shouldSplit = teamRun === true && parallel && normalized.length >= 2
+
+  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。
+    ...(teamRun ? { teamRun: true } : {}),
+  }
+
+  if (teamRun && shouldSplit) {
+    // 根卡在 teamRun 模式下就是 Lead：顺序只能写在 prompt 里——看板没有依赖字段，
+    // 靠平台排不出「先开发后验收」，只能让 Lead 自己守这个顺序。
+    rootInput.prompt +=
+      '\n\n流程：先派发子卡完成开发 → 等子卡交付 → 再让验收卡执行 → 被打回最多两次，第三次停下来交给人。'
+  } else if (teamRun) {
+    rootInput.prompt += '\n\n执行方式：这一轮由你自己开团队完成（Lead 起 teammate），父卡不产出报告。'
+  }
+
+  const cards = [{ id: rootId, key: 'root', title: cleanTitle, input: rootInput }]
+  const envelopes = [envelope({ kind: 'create', id: rootId, input: rootInput })]
+
+  if (normalized.length === 0) {
+    warnings.push('这个需求没有验收判据，看板里的执行者不知道做到什么算完；建议补几条。')
+  }
+
+  if (shouldSplit) {
+    const groups = groupCriteria(normalized, 4)
+    if (groups.length < normalized.length) {
+      // 一条判据一张卡只在判据不多时才有意义，否则一天开八张卡全是计费
+    }
+    groups.forEach((group, index) => {
+      const id = randomUUID()
+      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(envelope({ kind: 'create', 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 要求验证独立于开发；
+  // 同一张卡自己说「我做完了」不算验收。
+  // 和有没有开智能体团队无关：门槛是「必须有人独立核对」的意思，不能因为省一条会话就悄悄失效。
+  // 代价是没开团队时它就是第 2 条会话，所以要提前把条数说清楚（见下）。
+  let verifyId = null
+  if (evidenceOn && normalized.length > 0) {
+    verifyId = randomUUID()
+    // 拆过的需求逐张列子卡；单卡需求时待验收的就是父卡本身。
+    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)}（验收）`
+    const input = {
+      title: verifyTitle,
+      description: `独立验收「${cleanTitle}」：只核对证据，不改实现。`,
+      prompt: buildVerifyPrompt({ title: cleanTitle, criteria: normalized, targets, rootId }),
+      parentId: rootId,
+      ...shared,
+    }
+    cards.push({ id: verifyId, key: 'verify', title: verifyTitle, input })
+    envelopes.push(envelope({ kind: 'create', id: verifyId, input }))
+    warnings.push('已附一张验收卡：它只读证据、只给 PASS/REJECT，和开发不是同一张卡（基线 §3.3）。')
+  }
+
+  // 会话条数：团队模式下所有卡都在**同一个** 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} 条。`)
+  }
+
+  return {
+    rootId,
+    verifyId,
+    cards,
+    envelopes,
+    run: envelope({ kind: 'run', taskId: rootId }),
+    warnings,
+  }
+}