@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/core/lib/claim.mjs

@@ -0,0 +1,258 @@
+/**
+ * `argent flow claim` / `argent flow triage` 适配层（P1 首批，2026-10-03）
+ * —— 把被包脚本（`scripts/flow_claim.py` / `scripts/flow_triage.py`）的**退出码与输出**
+ * 翻译成 P0-A 的机器可判口径（A1 退出码 / A2 JSON / A3 dry-run）。
+ *
+ * ## 为什么必须有这一层（D4 裁定，2026-10-03）
+ * `scripts/flow_claim.py:14` 的 `3` 表示**无票可认领**，而 P0-A A1 把 `3` **唯一**留给"许可宽限放行"
+ * （`scripts/check-license.mjs:15-19` 与 `scripts/lease.py:15-21` 已是那个语义）。同一个码两个意思，
+ * 客户 agent 就没法用 `$?` 分支 —— 但**不能改脚本**（`scripts/flow-trigger.sh` 的 headless 分支
+ * 依赖它）⇒ 翻译放在这一层：
+ *
+ * | 脚本 `$?` | verb `code` | 条件 | 结论 |
+ * |---|---|---|---|
+ * | `0` | `0` | 有认领 | `ok:true, empty:false` |
+ * | `3` | **`0`** | 无票 | `ok:true, empty:true, reason:"no_ticket"`（"没票要跑"不是错误） |
+ * | `2` | `1` | stderr 是 `triage 失败/超时` | **源读取失败 = 运行失败**（网络、飞书半开连接） |
+ * | `2` | `2` | 其余（未知流程/缺 env/参数） | `reason:"missing_declaration"` / `"usage_error"` |
+ * | 其它 | `1` | — | `reason:"internal_error"`；输出不可解析 ⇒ `"bad_output"` |
+ *
+ * ## A3 dry-run
+ * **默认即 dry-run**（真写要显式 `--apply`/`--confirm`）；`--dry-run` 出现即恒 dry-run
+ * （调用方说了算 —— 能靠参数绕过判据就是红）。零副作用由 `scripts/flow_claim.py` 的 dry-run 分支保证，
+ * 判据 = 跑两次 dry-run 后数据目录逐字节不变（`scripts/tests/flow-claim-verb.test.mjs`）。
+ *
+ * 纪律：本文件是**薄适配层**——不复制认领/分诊的任何判据（幂等键、租约、并发、店铺闸门都在脚本里），
+ * 只做"参数搬运 + 退出码翻译 + 回显"。
+ */
+import { spawnSync } from 'node:child_process'
+import { join } from 'node:path'
+import { loadRegistry, resolveFlow } from './flow-registry.mjs'
+
+/** 需要带值的参数（搬运）。 */
+export const VALUE_FLAGS = ['--flow', '--max', '--lease-min', '--batch', '--per-ip', '--ledger', '--lock', '--cases-from-dir', '--limit']
+/** 布尔参数（搬运）。 */
+export const BOOL_FLAGS = ['--json', '--dry-run', '--no-regenerate']
+/** 本层**自己消费**的参数（不往脚本传）。 */
+export const CONSUMED_FLAGS = ['--apply', '--confirm', '--yes', '--plan-only']
+/** 显式确权（真写）参数。 */
+export const CONFIRM_FLAGS = ['--apply', '--confirm', '--yes']
+
+/** 分诊脚本支持的参数子集（`--plan-only` 走这条路）。 */
+const TRIAGE_FLAGS = ['--flow', '--cases-from-dir', '--ledger', '--limit', '--no-regenerate', '--json']
+
+/**
+ * 解析 argv → 调用计划（纯函数）。
+ * @returns {{ok:true, route:'claim'|'triage', childArgs:string[], echo:object, dryRun:boolean, json:boolean}
+ *          | {ok:false, code:number, reason:string, error:string}}
+ */
+export function buildInvocation(argv = []) {
+  const args = [...argv]
+  const has = (f) => args.includes(f)
+  const valOf = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined }
+
+  const flow = valOf('--flow')
+  if (!flow) return { ok: false, code: 2, reason: 'usage_error', error: '缺必填参数 --flow（用法：argent flow claim --flow <流程> [--max N] [--cases-from-dir <目录>] [--apply]）' }
+
+  // 单值参数必须带值（否则会把下一个 `--xxx` 当值吃进去，错误会推迟到脚本里才暴露）
+  for (const f of VALUE_FLAGS) {
+    const i = args.indexOf(f)
+    if (i >= 0 && (i + 1 >= args.length || String(args[i + 1]).startsWith('--'))) {
+      return { ok: false, code: 2, reason: 'usage_error', error: `参数 ${f} 缺值` }
+    }
+  }
+  const json = has('--json')
+  const planOnly = has('--plan-only')
+  const dryFlag = has('--dry-run')
+  const confirmed = CONFIRM_FLAGS.some((f) => has(f))
+  const dryRun = dryFlag || !confirmed          // A3：默认 dry-run；--dry-run 恒优先（fail-safe）
+  const route = planOnly ? 'triage' : 'claim'
+
+  const keep = new Set(route === 'triage' ? TRIAGE_FLAGS : [...VALUE_FLAGS, ...BOOL_FLAGS])
+  const childArgs = []
+  for (let i = 0; i < args.length; i++) {
+    const t = args[i]
+    if (CONSUMED_FLAGS.includes(t)) continue
+    if (!keep.has(t)) {
+      if (t.startsWith('--')) childArgs.push(t)      // 未知参数照传：脚本的 argparse 才是它自己参数的权威（exit 2）
+      continue
+    }
+    childArgs.push(t)
+    if (VALUE_FLAGS.includes(t)) { childArgs.push(args[i + 1]); i++ }
+  }
+  if (route === 'claim' && dryRun) childArgs.push('--dry-run')
+
+  const echo = {
+    flow,
+    max: valOf('--max') !== undefined ? Number(valOf('--max')) : null,
+    leaseMin: valOf('--lease-min') !== undefined ? Number(valOf('--lease-min')) : null,
+    batch: valOf('--batch') !== undefined ? Number(valOf('--batch')) : null,
+    perIp: valOf('--per-ip') !== undefined ? Number(valOf('--per-ip')) : null,
+    casesFromDir: valOf('--cases-from-dir') ?? null,
+    limit: valOf('--limit') !== undefined ? Number(valOf('--limit')) : null,
+    ledger: valOf('--ledger') ?? null,
+    lock: valOf('--lock') ?? null,
+    dryRun,
+    planOnly,
+    json,
+  }
+  return { ok: true, route, childArgs, echo, dryRun, json }
+}
+
+/** `--flow` 的实际生效值：规范 id + 局部 id 前缀（回显用；解析不了就如实退化为字面值）。 */
+export function flowEcho(flow, { repo, py, pyFailure = null } = {}) {
+  if (pyFailure || !py) {
+    return { flow, flowPrefix: null, flowKnown: false, note: '解释器不可用 ⇒ 未做注册表解析，flow 为字面值' }
+  }
+  const reg = loadRegistry({ repo, py })
+  if (!reg.ok) {
+    return { flow, flowPrefix: null, flowKnown: false, note: `注册表读不到（${reg.reason}）⇒ flow 为字面值` }
+  }
+  const r = resolveFlow({ input: flow, doc: reg.doc })
+  return { flow: r.canonical, flowPrefix: r.local, flowKnown: r.known }
+}
+
+/** 解析脚本 stdout 的 JSON（脚本的 `--json` 输出；失败返回 null）。 */
+export function parseChildJson(stdout) {
+  const s = String(stdout || '')
+  const i = s.indexOf('{')
+  if (i < 0) return null
+  try { return JSON.parse(s.slice(i)) } catch { return null }
+}
+
+/**
+ * 退出码翻译（A1；唯一实现，claim/triage 共用）。
+ * @param {{status:number|null, stdout:string, stderr:string, signal?:string}} child
+ */
+export function classifyChild(child) {
+  const status = child.status === null || child.status === undefined ? 1 : Number(child.status)
+  const stderr = String(child.stderr || '')
+  if (status === 0 || status === 3) return { ok: true, code: 0, scriptStatus: status }
+  if (status === 2) {
+    // ⚠️ 脚本把"源读取失败/超时"也归在 2 里 —— 按 A1 它属**运行失败**（1），不是用法错误
+    if (/triage\s*(失败|超时)/.test(stderr)) return { ok: false, code: 1, reason: 'source_failed', error: stderr.trim().slice(0, 400) }
+    if (/flow_source 失败/.test(stderr)) return { ok: false, code: 1, reason: 'source_failed', error: stderr.trim().slice(0, 400) }
+    if (/未知流程/.test(stderr)) return { ok: false, code: 2, reason: 'missing_declaration', error: stderr.trim().slice(0, 400) }
+    return { ok: false, code: 2, reason: 'usage_error', error: stderr.trim().slice(0, 400) }
+  }
+  return { ok: false, code: 1, reason: 'internal_error', error: (stderr.trim() || `被包脚本退出码 ${status}`).slice(0, 400) }
+}
+
+/** 认领结果 → A2 JSON（纯函数）。 */
+export function shapeClaim(child, { echo, registryEcho }) {
+  // ⚠️ base 里**不含** max/leaseMin：那两个要由"命令行给的 ⇒ 脚本回显的生效值"决定（见下方 pick），
+  // 先铺 base 再覆盖会让生效值被 echo 的 null 盖掉（实测踩过：max 恒 null）。
+  const base = { ...registryEcho, dryRun: echo.dryRun, casesFromDir: echo.casesFromDir }
+  const cls = classifyChild(child)
+  if (!cls.ok) return { ok: false, empty: false, code: cls.code, reason: cls.reason, error: cls.error, ...base }
+  const parsed = parseChildJson(child.stdout)
+  if (!parsed) {
+    return { ok: false, empty: false, code: 1, reason: 'bad_output',
+      error: `被包脚本输出不可解析：${String(child.stdout || child.stderr || '').trim().slice(0, 300)}`, ...base }
+  }
+  const claimed = Array.isArray(parsed.claimed) ? parsed.claimed.map(String) : []
+  const empty = claimed.length === 0
+  const pick = (cliVal, childVal) => (cliVal !== null && cliVal !== undefined ? cliVal : (childVal ?? null))
+  return {
+    ok: true,
+    empty,
+    code: 0,
+    reason: empty ? 'no_ticket' : null,
+    claimed,
+    count: claimed.length,
+    // 实际生效值：命令行给的优先，否则取**脚本回显的生效值**（可能来自流程配置）
+    max: pick(echo.max, parsed.max),
+    leaseMin: pick(echo.leaseMin, parsed.leaseMin),
+    batch: pick(echo.batch, parsed.batch),
+    perIp: pick(echo.perIp, parsed.perIp),
+    ledger: echo.ledger || parsed.ledger || null,
+    lock: echo.lock || parsed.lock || null,
+    planOnly: echo.planOnly,
+    ...base,
+    ...(empty && parsed.reason ? { note: String(parsed.reason).slice(0, 500) } : {}),
+  }
+}
+
+/** 分诊结果 → A2 JSON（纯函数）。 */
+export function shapeTriage(child, { echo, registryEcho }) {
+  const base = { ...registryEcho, limit: echo.limit, casesFromDir: echo.casesFromDir }
+  const cls = classifyChild(child)
+  if (!cls.ok) return { ok: false, empty: false, code: cls.code, reason: cls.reason, error: cls.error, ...base }
+  const parsed = parseChildJson(child.stdout)
+  if (!parsed) {
+    return { ok: false, empty: false, code: 1, reason: 'bad_output',
+      error: `被包脚本输出不可解析：${String(child.stdout || child.stderr || '').trim().slice(0, 300)}`, ...base }
+  }
+  const plan = parsed.plan || {}
+  const ids = (arr) => (arr || []).map((x) => String((x && x.caseId) || '')).filter(Boolean)
+  const toDispatch = ids(plan.to_dispatch)
+  const empty = toDispatch.length === 0
+  const s = parsed.summary || {}
+  return {
+    ok: true,
+    empty,
+    code: 0,
+    reason: empty ? 'no_ticket' : null,
+    counts: {
+      toDispatch: s.to_dispatch ?? toDispatch.length,
+      awaitRelease: s.await_release ?? (plan.await_release || []).length,
+      needFields: s.need_fields ?? (plan.need_fields || []).length,
+      inFlight: s.in_flight ?? (plan.in_flight || []).length,
+      stale: s.stale ?? (plan.stale || []).length,
+      needsHuman: s.needs_human ?? (plan.needs_human || []).length,
+    },
+    plan: {
+      toDispatch,
+      stale: ids(plan.stale),
+      inFlight: ids(plan.in_flight),
+      needFields: ids(plan.need_fields),
+      awaitRelease: ids(plan.await_release),
+    },
+    ...base,
+    ...((parsed.notes || []).length ? { notes: (parsed.notes || []).map(String).slice(0, 6) } : {}),
+  }
+}
+
+/** 人类可读的一行结论（与 JSON 载荷分离；`--json` 时 stdout 只有 JSON）。 */
+export function humanOf(json) {
+  if (!json.ok) return `❌ ${json.reason}：${json.error || ''}`.trim()
+  if (json.claimed) {
+    if (json.empty) return `本轮无票可认领（no_ticket）${json.note ? `：${json.note}` : ''}`
+    return json.dryRun
+      ? `[dry-run] 将认领 ${json.count} 张（未落台账）：${json.claimed.join(', ')}`
+      : `✅ 已认领 ${json.count} 张（租约 ${json.leaseMin ?? '?'} 分钟）：${json.claimed.join(', ')}`
+  }
+  const c = json.counts || {}
+  if (json.empty) return `本轮无可派发单元（no_ticket）｜待放行 ${c.awaitRelease ?? 0}｜等人补字段 ${c.needFields ?? 0}｜在飞 ${c.inFlight ?? 0}｜停滞 ${c.stale ?? 0}`
+  return `可派发 ${c.toDispatch ?? 0} 张：${(json.plan?.toDispatch || []).join(', ')}`
+}
+
+/** 跑脚本（可注入 spawn 便于夹具）。 */
+export function runChild({ py, script, args, env = process.env, spawn = spawnSync, timeout = 0 }) {
+  const r = spawn(py, [script, ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, env, timeout: timeout || undefined })
+  return { status: r.status, stdout: r.stdout || '', stderr: r.stderr || '', signal: r.signal || null }
+}
+
+/**
+ * verb 入口：`flow claim` / `flow triage`（route 由 argv 决定）。
+ * @returns {{json:object, human:string, stderr:string, exit:number}} 信封（CLI 负责打印与退出码）
+ */
+export function runFlowVerb(argv, { repo, py, pyFailure = null, env = process.env, spawn = spawnSync } = {}) {
+  const built = buildInvocation(argv)
+  if (!built.ok) {
+    const json = { ok: false, empty: false, code: built.code, reason: built.reason, error: built.error, flow: null, flowPrefix: null, flowKnown: false, dryRun: null, casesFromDir: null }
+    return { json, human: humanOf(json), stderr: '', exit: built.code }
+  }
+  if (pyFailure || !py) {
+    const json = { ok: false, empty: false, code: 2, reason: 'python_unavailable', error: String(pyFailure || '解释器不可用'),
+      flow: built.echo.flow, flowPrefix: null, flowKnown: false, dryRun: built.dryRun, casesFromDir: built.echo.casesFromDir }
+    return { json, human: humanOf(json), stderr: '', exit: 2 }
+  }
+  const script = join(repo, 'scripts', built.route === 'claim' ? 'flow_claim.py' : 'flow_triage.py')
+  const child = runChild({ py, script, args: built.childArgs, env, spawn })
+  const registryEcho = flowEcho(built.echo.flow, { repo, py })
+  const json = built.route === 'claim'
+    ? shapeClaim(child, { echo: built.echo, registryEcho })
+    : shapeTriage(child, { echo: built.echo, registryEcho })
+  return { json, human: humanOf(json), stderr: String(child.stderr || ''), exit: Number(json.code) }
+}