dsh-card-dispatch 0.0.0-stage → 0.1.1

package/src/criteria-llm.js

@@ -0,0 +1,79 @@
+/**
+ * criteria-llm.js：让宿主已经配置好的模型写判据草稿。
+ *
+ * 调用的是官方 `llm` 服务（`ctx.get('llm')`），和任务看板「粘贴文本 → 解析成任务」
+ * 走同一条路；通道细节在 model-call.js，这里只负责提示词与回复解析。
+ * 不自己拼 HTTP、不碰 API Key——模型与密钥都由宿主管。
+ *
+ * 一次点击 = 一次很小的调用，会计费，所以页面必须把「用哪个模型」写出来。
+ */
+
+import { callModel, extractJsonObject, MODEL_TIMEOUT_MS } from './model-call.js'
+
+/** 一次草稿最多等多久。超过就当没答上来，退回规则提炼。 */
+export const DRAFT_TIMEOUT_MS = MODEL_TIMEOUT_MS
+
+/** 一条判据最长多少字（模型爱写长句，页面里读起来很累）。 */
+const ITEM_LIMIT = 120
+
+/** 最多要几条。 */
+const MAX_ITEMS = 8
+
+/** 系统提示词。导出给测试与 README 引用，免得文档和代码说两套。 */
+export const CRITERIA_SYSTEM = [
+  '你把一条需求改写成可验收的判据。',
+  '只输出一个 JSON 对象，不要任何解释：{"criteria":["...","..."]}',
+  '- criteria：3 到 8 条，每条一句话，是可判定真假的验收条件，不是任务步骤。',
+  '- 每条必须写清「什么情况下、看到什么」，能对上具体现象。',
+  '- 不要写「代码质量好」「测试通过」这种无法核对的话。',
+  '- 用需求本来的语言写。',
+].join('\n')
+
+/** 从模型回复里抠出判据（容忍代码围栏与前后废话）。 */
+export function parseCriteriaReply(reply) {
+  const payload = extractJsonObject(reply)
+  if (payload === undefined || payload === null) return []
+  const raw = Array.isArray(payload.criteria) ? payload.criteria : []
+  const seen = new Set()
+  const out = []
+  for (const item of raw) {
+    const line = String(typeof item === 'string' ? item : item?.text ?? '')
+      .replace(/\s+/g, ' ')
+      .replace(/^[-*+]\s+/, '')
+      .trim()
+      .slice(0, ITEM_LIMIT)
+    if (line === '') continue
+    const key = line.replace(/[\s。；;，,：:]/g, '')
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(line)
+    if (out.length >= MAX_ITEMS) break
+  }
+  return out
+}
+
+/**
+ * 让模型写判据草稿。
+ *
+ * @param {object} input
+ * @param {any} input.llm 宿主的 llm 服务（拿不到就传 null）
+ * @param {{provider:string, model:string}} input.route
+ * @param {string} input.title
+ * @param {string} input.description
+ * @param {number} [input.timeoutMs]
+ * @returns {Promise<{ok:boolean, criteria:Array<string>, error:string|null}>}
+ */
+export async function draftWithModel({ llm, route, title = '', description = '', timeoutMs = DRAFT_TIMEOUT_MS } = {}) {
+  const userText = [
+    title.trim() === '' ? '' : `需求标题：${title.trim()}`,
+    description.trim() === '' ? '' : `需求描述：\n${description.trim()}`,
+  ].filter((line) => line !== '').join('\n\n')
+  if (userText === '') return { ok: false, criteria: [], error: '没有可拆的内容' }
+
+  const reply = await callModel({ llm, route, system: CRITERIA_SYSTEM, text: userText, timeoutMs })
+  if (!reply.ok) return { ok: false, criteria: [], error: reply.error }
+
+  const criteria = parseCriteriaReply(reply.reply)
+  if (criteria.length === 0) return { ok: false, criteria: [], error: '模型没给出可用的判据（回复不是约定的 JSON）' }
+  return { ok: true, criteria, error: null }
+}

package/src/criteria.js

@@ -0,0 +1,102 @@
+/**
+ * criteria.js：从标题与描述里提炼**判据草稿**（无模型时的退路）。
+ *
+ * ## 为什么这里不调模型
+ *
+ * 模型通道在 `criteria-llm.js`（`ctx.get('llm')`）。这一层刻意只用规则：
+ * 模型不可用、开关关着、或者一次点击不值得多花一次调用时，仍然要能给出可编辑的草稿。
+ *
+ * 所以这里只做**提炼**：把描述里本来就写成要求的话捞出来，变成一行一条。
+ * 提炼不出来就说提炼不出来，并告诉人怎么写才好提炼——不编造判据。
+ */
+
+/** 像「要求」的句子：出现这些词才值得当判据。 */
+const BEHAVIOR = /(要|需要|必须|支持|能|可以|不要|不能|不得|应该|允许|禁止|自动|提示|校验|保存|导出|显示|登录|上传|下载|计算|校验|报错)/
+
+/** 列表项：`- x`、`* x`、`1. x`、`1) x`、`- [ ] x`。 */
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?(.+?)\s*$/
+
+const MAX_ITEMS = 8
+/** 中文判据常常只有三四个字（「能登录」），门槛设 3 而不是 4。 */
+const MIN_LENGTH = 3
+const MAX_LENGTH = 80
+
+function clean(text) {
+  return String(text ?? '')
+    .replace(/^#+\s*/, '')
+    .replace(/\*\*/g, '')
+    .replace(/`/g, '')
+    .replace(/^[-*+]\s+/, '')
+    .replace(/\s+/g, ' ')
+    .replace(/[。；;，,：:]+$/, '')
+    .trim()
+}
+
+/** 归一化后去重（同一句话写两遍只留一条）。 */
+function unique(items) {
+  const seen = new Set()
+  const out = []
+  for (const item of items) {
+    const key = item.replace(/[\s。；;，,：:]/g, '')
+    if (key === '' || seen.has(key)) continue
+    seen.add(key)
+    out.push(item)
+  }
+  return out
+}
+
+/**
+ * 提炼判据草稿。
+ *
+ * @param {object} input
+ * @param {string} [input.title] 需求标题（描述为空时给一句兜底说明用，不进判据）
+ * @param {string} [input.description] 需求描述
+ * @returns {{criteria:Array<string>, notes:Array<string>}}
+ */
+export function suggestCriteria({ title = '', description = '' } = {}) {
+  const notes = []
+  const text = String(description ?? '').replace(/\r\n?/g, '\n')
+  if (text.trim() === '') {
+    return {
+      criteria: [],
+      notes: [`描述是空的，没法提炼判据。写两三句「要什么、不要什么」，或用文档导入。`],
+    }
+  }
+
+  // 1) 描述里的列表项：本来就是一条条要求，直接当判据
+  const listed = text
+    .split('\n')
+    .map((line) => LIST_ITEM.exec(line))
+    .filter((match) => match !== null)
+    .map((match) => clean(match[1]))
+    .filter((item) => item.length >= MIN_LENGTH)
+
+  if (listed.length > 0) {
+    const criteria = unique(listed).slice(0, MAX_ITEMS)
+    notes.push(`从描述里的列表取了 ${criteria.length} 条；这是草稿，按需要改。`)
+    if (listed.length > criteria.length) notes.push(`另有 ${listed.length - criteria.length} 条没放进来（一次最多 ${MAX_ITEMS} 条）`)
+    return { criteria, notes }
+  }
+
+  // 2) 没有列表：按句子切，只留「像要求」的
+  const sentences = text
+    .split(/[。！？!?；;\n]+/)
+    .map((line) => clean(line))
+    .filter((line) => line.length >= MIN_LENGTH && line.length <= MAX_LENGTH)
+    .filter((line) => BEHAVIOR.test(line))
+
+  if (sentences.length > 0) {
+    const criteria = unique(sentences).slice(0, MAX_ITEMS)
+    notes.push(`从描述里提炼了 ${criteria.length} 条；这是草稿，按需要改。`)
+    if (sentences.length > criteria.length) notes.push(`另有 ${sentences.length - criteria.length} 句没放进来（一次最多 ${MAX_ITEMS} 条）`)
+    return { criteria, notes }
+  }
+
+  // 3) 什么都没有：说清楚怎么写
+  notes.push(
+    '描述里没有能提炼成判据的句子（要含「要 / 支持 / 不能 / 提示」这类词）。' +
+      '换成一行一条的写法最稳，例如「- 除数为 0 要提示」。',
+  )
+  if (String(title ?? '').trim() !== '') notes.push('标题只说明做什么，判据得写清「怎样算做完」。')
+  return { criteria: [], notes }
+}

package/src/gates.js

@@ -0,0 +1,134 @@
+/**
+ * gates.js：插件**唯一的拦截点**，全部是纯函数。
+ *
+ * 为什么是纯函数：闸门的价值在于「同样的输入永远给同样的答案」，这样它可测、可回放、
+ * 也能在面板上先算一遍给人看（dry-run）。这里不读盘、不看时间、不调宿主。
+ *
+ * 只拦平台拦不住的三种东西：
+ *   1. **钱**——每日运行数（每次运行 = 一条会话 = 一次计费）；
+ *   2. **并发**——同时在跑的会话数（写冲突、限流、人也看不过来）；
+ *   3. **交付质量**——没有证据的「完成」不算完成。
+ *
+ * 明确不管的（平台已保证，写在这里只会误导）：
+ *   - 谁能给谁发消息（人员没有团队地址，发不出去）；
+ *   - 谁能指挥谁（lead 点名不到成员的下属）；
+ *   - 委派深度、权限预设、模型计费（部署设置与宿主行为）。
+ */
+
+/** 拒绝时的错误码：面板按它给中文提示，测试按它断言。 */
+export const GATE_CODES = Object.freeze({
+  DISABLED: 'E_DISABLED',
+  PLAN_NOT_APPROVED: 'E_PLAN_NOT_APPROVED',
+  STATE_UNKNOWN: 'E_STATE_UNKNOWN',
+  BUDGET: 'E_BUDGET_EXCEEDED',
+  PARALLEL: 'E_PARALLEL_LIMIT',
+  EVIDENCE: 'E_EVIDENCE_MISSING',
+})
+
+/**
+ * 能不能开一轮（= 能不能花钱）。
+ *
+ * 顺序是刻意的：先看总开关，再看计划闸，然后运行态、预算和并发。
+ * 因为「没打开」和「没批准」是配置/流程问题，人应该先看到它们；
+ * 运行态与预算是运行态问题，排在后面；运行态拿不到就直接拒绝，不拿 0 冒充。
+ *
+ * @param {object} input
+ * @param {object} input.config 归一化后的配置
+ * @param {object} [input.state] 运行态快照 `{runsToday, runningSessions}`
+ * @param {object} [input.request] 本次请求 `{planApproved}`
+ * @param {boolean} [input.stateKnown] 调用方是否真的拿到了运行态；false = 不许拿 0 冒充
+ * @returns {{allow:boolean, code:string|null, message:string, checks:Array}}
+ */
+export function evaluateStart({ config, state = {}, request = {}, stateKnown } = {}) {
+  const checks = []
+  const push = (id, ok, detail) => {
+    checks.push({ id, ok, detail })
+    return ok
+  }
+  const deny = (code, message) => ({ allow: false, code, message, checks })
+  const allow = () => ({ allow: true, code: null, message: '可以开工', checks })
+
+  if (!push('enabled', config.enabled === true, config.enabled ? '总开关已打开' : '总开关关闭')) {
+    return deny(GATE_CODES.DISABLED, '插件总开关没打开：现在只会拆需求、填卡片，不会开任何会话')
+  }
+
+  const planOk = request.planApproved === true || config.gates.requirePlanApproval !== true
+  if (!push('plan', planOk, planOk ? '计划已批准（或计划闸关闭）' : '计划未批准')) {
+    return deny(GATE_CODES.PLAN_NOT_APPROVED, '计划闸：DAG 还没有经过人确认，先让人看一遍拆得对不对再开跑')
+  }
+
+  const runsToday = Number(state.runsToday ?? 0)
+  const running = Number(state.runningSessions ?? 0)
+  // 调用方没明说时：给了非空 state 就当知道，空对象/没给就是「不知道」。
+  const known = stateKnown ?? (state !== null && typeof state === 'object' && Object.keys(state).length > 0)
+
+  // 运行态缺失时**不许按 0 放行**：预算/并发闸的全部价值就是「拿真实数字做决定」。
+  // 以前调用方传 state:{}，这里永远是 0，两个闸形同虚设；现在缺数据就明说。
+  if (!push('state', known, known ? `运行态：今天 ${runsToday} 次 / 在跑 ${running} 个` : '没有运行态快照')) {
+    return deny(GATE_CODES.STATE_UNKNOWN, '预算/并发闸拿不到运行态（今天跑了几次、几个会话在跑）：先刷新看板状态再开跑，不要拿 0 冒充')
+  }
+
+  if (!push('budget', runsToday < config.gates.budgetPerDay, `今天已跑 ${runsToday} / ${config.gates.budgetPerDay}`)) {
+    return deny(GATE_CODES.BUDGET, `预算闸：今天已经跑了 ${runsToday} 次，达到上限 ${config.gates.budgetPerDay}；清零后才能继续`)
+  }
+
+  if (!push('parallel', running < config.gates.maxParallelRuns, `当前在跑 ${running} / ${config.gates.maxParallelRuns}`)) {
+    return deny(GATE_CODES.PARALLEL, `并发闸：已有 ${running} 个会话在跑，上限 ${config.gates.maxParallelRuns}`)
+  }
+
+  return allow()
+}
+
+/**
+ * 交付能不能进「已提交」。
+ *
+ * 证据的定义故意很窄：**能复核的东西**。一张嘴说「我完成了」不算，因为基线 P4 要求
+ * 「完成 = 完成 + 证据」，而自动跑卡最贵的错误就是把没证据的完成当完成。
+ *
+ * @param {object} input
+ * @param {object} input.config
+ * @param {object} [input.evidence] `{commitSha, reportPath, testOutput}`
+ * @returns {{allow:boolean, code:string|null, missing:Array<string>, message:string}}
+ */
+export function evaluateEvidence({ config, evidence = {} } = {}) {
+  if (config.gates.requireEvidence !== true) {
+    return { allow: true, code: null, missing: [], message: '交付门槛已关闭（不建议：没有证据的完成无法复核）' }
+  }
+  const missing = []
+  if (!String(evidence.commitSha ?? '').trim()) missing.push('commit')
+  const hasReport = String(evidence.reportPath ?? '').trim() || String(evidence.testOutput ?? '').trim()
+  if (!hasReport) missing.push('report')
+  if (missing.length === 0) return { allow: true, code: null, missing, message: '证据齐全' }
+  return {
+    allow: false,
+    code: GATE_CODES.EVIDENCE,
+    missing,
+    message: `交付门槛：缺少 ${missing.join(' 和 ')}，不能算完成`,
+  }
+}
+
+/**
+ * 第 N 次打回该不该继续返工。
+ *
+ * 语义对齐基线 R3：`rejectedCount` 是**这次判决之前**已经打回的次数。
+ * 上限 2 表示「允许打回两次」，第 3 次必须升级给人（派生澄清任务），否则就是死循环。
+ *
+ * @param {object} input
+ * @param {object} input.config
+ * @param {number} [input.rejectedCount]
+ * @returns {{allow:boolean, escalate:boolean, nextCount:number, message:string}}
+ */
+export function evaluateRework({ config, rejectedCount = 0 } = {}) {
+  const previous = Math.max(0, Math.trunc(Number(rejectedCount) || 0))
+  const limit = config.gates.maxReworkRounds
+  const escalate = previous >= limit
+  const nextCount = previous + 1
+  return {
+    allow: !escalate,
+    escalate,
+    nextCount,
+    message: escalate
+      ? `这将是第 ${nextCount} 次打回，超过上限 ${limit}：停止让开发继续改，升级给人（对应基线 R3）`
+      : `第 ${nextCount} 次打回，仍在上限 ${limit} 内，可以返工`,
+  }
+}