@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/core/mcp/server.mjs

@@ -0,0 +1,702 @@
+#!/usr/bin/env node
+/**
+ * argent-mcp（0.3 P2 第一步）—— **最小可用 MCP server（stdio 传输）**
+ *
+ * 目的：把 Argent 的能力以 MCP 契约暴露给任意宿主（dsh / 自建 client / 未来 agent），
+ * 宿主不再依赖具体脚本名 —— 这是"抽离基座"的对外接口层。
+ *
+ * 实现取舍：**不引第三方依赖**（MCP stdio 传输 = 每行一个 JSON-RPC 2.0 消息），
+ * 因此可在客户机内网/离线环境直接跑；协议子集：initialize / notifications/initialized /
+ * tools/list / tools/call / ping。
+ *
+ * 暴露面（2026-10-03 P1 第二批更新）：只读 tools 为主（version / license / ledger / sop / doctor /
+ * preflight / report / failures / writeback_audit）+ **写类 tools 全部带门禁**：
+ *   · `argent_claim_shadow` / `argent_writeback_shadow`：隔离沙箱里跑**同一脚本 + --dry-run**（真台账零改动）；
+ *   · `argent_claim`（confirm=true）/ `argent_writeback`（confirm=true）：真写，**先过影子比对 + 许可闸门**
+ *     （`core/lib/license-guard.mjs` ⇒ 与 CLI 同一份判据/证据；默认 observe 只留证据不拦）。
+ *
+ * 安全注解（2026-10-06 加固）：`tools/list` 每个 tool 带 `annotations`（只读 `readOnlyHint:true` ／
+ * 写类 `readOnlyHint:false + destructiveHint:true`），让宿主能在**协议层**分辨只读与写类、
+ * 从而收窄授权面；分类与理由见下方 {@link annotationsFor} 上方的注释块。
+ */
+import { execFileSync } from 'node:child_process'
+import { cpSync, existsSync as fExists, mkdirSync, mkdtempSync, readdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolveSop } from '../lib/sop.mjs'
+import { queryLedger, resolveLedgerFlow } from '../lib/ledger.mjs'
+import { pickPython } from '../lib/python.mjs'
+import { resolveDataDir } from '../lib/argent-datadir.mjs'
+import { loadRegistry, resolveFlow } from '../lib/flow-registry.mjs'
+// 许可闸门（写类 tool 的真写路径；**同一个模块**给 CLI 用 ⇒ 判据与证据只有一份）
+import { gateWrite } from '../lib/license-guard.mjs'
+// `license status` 的 verb 适配层（判定点唯一在 CLI 进程内；MCP 只做搬运，不自己算三态）
+import { runLicenseVerb } from '../lib/license.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..', '..')
+// 数据目录：内核三级链（唯一判据）—— MCP 与 CLI/插件必须同口径，否则影子跑读错了"生产"目录
+const DATA_DIR = resolveDataDir({ env: process.env }).dir
+// 解释器（D3，2026-10-03）：**与 CLI 同源**的多候选探测（`core/lib/python.mjs`）。
+// 此前这里是单候选（`ARGENT_PY || <数据目录>/venv/bin/python3`）——候选不存在时 exec 失败，
+// 各 tool 的 catch 把它当成"没结果"⇒ 宿主看到的是"这台机器上没有流程"。现在：
+//   · 多候选（ARGENT_PY → venv → PATH），全不可用 ⇒ tool 返回明确的诊断（不再只有 ENOENT）；
+//   · 探测在模块加载时做一次并记忆（MCP server 是常驻进程，不像 CLI 需要"无解释器也能 version"）。
+const PY_PICK = pickPython({ env: process.env, dataDir: DATA_DIR, repo: REPO })
+const PY = PY_PICK.path
+const PY_FAILURE = PY_PICK.ok ? null : PY_PICK.diagnostics
+const SERVER_INFO = { name: 'argent', version: (readFileSync(join(REPO, 'VERSION'), 'utf8') || '').trim() || '0.0.0' }
+
+/**
+ * 需要 Python 的 tool 的**唯一出口**（对齐 CLI 的 `runPy`，D3 收口 2026-10-03）。
+ *
+ * 此前 python 调用散在 7 处 inline `execFileSync(PY, …)`：解释器不可用时 exec 一个空路径 ⇒ 各
+ * `catch` 把 ENOENT 当成"没结果"⇒ 宿主看到的是"这台机器上没有流程/没有失败"，**假绿**。
+ * 现在统一成一条路径：**解释器不可用 ⇒ `ok:false, code:2, reason:'python_unavailable'` + 诊断**
+ * （与 `core/cli/argent.mjs:79`、`core/lib/sop.mjs:40` 逐字同口径，宿主只需认一个 reason）。
+ *
+ * **成功路径行为不变**：成功 = `{ok:true, code:0, output:stdout}`（cwd/编码与 inline 版一致）。
+ * 失败 = 保留 stdout + stderr（inline 版只看 stdout）—— 这是**加强**，不是行为变更：
+ * 所有消费点原先就在 `catch` 里读 `e.stdout`，现在读到的只会更多（stderr 是守卫拒绝原因所在）。
+ *
+ * @param {string[]} argv 脚本路径 + 参数（调用方拼）
+ * @param {{env?: object}} [opts] 额外环境（影子跑要覆盖 `ARGENT_DATA_DIR`）
+ * @returns {{ok:boolean, code:number, output:string, error:string, reason:string, argv:string[]}}
+ */
+function runPy(argv, { env = null } = {}) {
+  if (PY_FAILURE) return { ok: false, code: 2, output: '', reason: 'python_unavailable', error: PY_FAILURE, argv }
+  try {
+    const out = execFileSync(PY, argv, { encoding: 'utf8', cwd: REPO, ...(env ? { env } : {}) })
+    return { ok: true, code: 0, output: out, reason: '', error: '', argv }
+  } catch (e) {
+    return {
+      ok: false,
+      code: e.status ?? 1,
+      output: String(e.stdout || ''),
+      reason: '',
+      error: String(e.stderr || e.message || ''),
+      argv,
+    }
+  }
+}
+
+/** `--json` 输出的解析（失败不抛：返回 `{ok:false, error}`，由调用方按既有失败形状回）。 */
+function parseJsonOut(text) {
+  try { return { ok: true, value: JSON.parse(text) } } catch (e) { return { ok: false, error: `JSON 解析失败：${e.message}` } }
+}
+
+/** 建一个与真实环境同构的影子沙箱（排除重目录），返回路径。 */
+function makeShadow() {
+  const dataDir = DATA_DIR
+  const shadow = mkdtempSync(join(tmpdir(), 'argent-shadow-'))
+  const SKIP = new Set(['logs', 'backup', 'packs-cache', 'kanban-backup', 'invoice-writeback'])
+  for (const entry of readdirSync(dataDir, { withFileTypes: true })) {
+    if (SKIP.has(entry.name)) continue
+    cpSync(join(dataDir, entry.name), join(shadow, entry.name), { recursive: true })
+  }
+  return { shadow, dataDir }
+}
+
+/** 在影子沙箱里跑一条流程，返回 {code, out, events（影子内新增的台账事件）}。 */
+function shadowRun(flow, shadow, extraArgs = []) {
+  const before = countEvents(shadow)
+  // ⚠️ 必须同时设 **ARGENT_DATA_HOME**：测试夹具（daily-report-flow.test.mjs）就是两者都设，
+  // 只设 DATA_DIR 时清单路径按 HOME 解析 ⇒ 读到真实空清单、夹具被忽略（实测 0 票据）。
+  const r = runPy([join(REPO, 'scripts', 'flow_triage.py'), '--flow', String(flow), '--json', ...extraArgs],
+    { env: { ...process.env, ARGENT_DATA_DIR: shadow, ARGENT_DATA_HOME: shadow } })
+  return { code: r.code, out: r.output, events: readEvents(shadow).slice(before) }
+}
+
+function countEvents(dir) {
+  const f = join(dir, 'flow-ledger.jsonl')
+  return fExists(f) ? readFileSync(f, 'utf8').trim().split('\n').filter(Boolean).length : 0
+}
+
+function readEvents(dir) {
+  const f = join(dir, 'flow-ledger.jsonl')
+  if (!fExists(f)) return []
+  return readFileSync(f, 'utf8').trim().split('\n').filter(Boolean)
+    .map((l) => { try { return JSON.parse(l) } catch { return { raw: l } } })
+}
+
+/** 归一化：剔除"必然不同"的易变字段，只留可比对的语义字段。 */
+const VOLATILE = new Set(['ts', 'createdAt', 'updatedAt', 'leaseUntil', 'sessionId', 'at', 'instanceId', 'id'])
+function normalize(ev) {
+  const out = {}
+  for (const k of Object.keys(ev || {}).sort()) {
+    if (VOLATILE.has(k)) continue
+    out[k] = ev[k]
+  }
+  return out
+}
+
+/**
+ * 夹具注入（2026-09-29）：让影子跑**真正产生台账事件**，否则"两边都 0 事件"毫无比对价值。
+ * schema 取自 `scripts/flow_sources/common.py#read_cases_batch`（接受 `{"cases":[{ticketKey,fields}]}`），
+ * 语义对齐 `scripts/tests/daily-report-flow.test.mjs`：写 `flow-inbox/<flow>.json` + 跑 `--no-regenerate`
+ * （夹具语义：不重算清单，否则生成器会覆盖夹具）。
+ */
+function injectFixture(flow, shadow, ticketKey = 'MLM-2026-09-29-1234567890') {
+  // ⚠️ 夹具必须写成**生成器的形状**（含 generatedAt/reportTime/skipped）：实测只写 {cases:[…]} 时，
+  // 新鲜度判据看不出"何时生成" ⇒ 视为过期 ⇒ 生成器重新生成并**覆盖夹具**（沙箱里最终是 cases: []）。
+  const dir = join(shadow, 'flow-inbox')
+  mkdirSync(dir, { recursive: true })
+  const body = {
+    flow,
+    generatedAt: new Date().toISOString(),
+    reportTime: '00:05',
+    // 票号必须合流程的形态（真实票号如 MLM-2026-09-28-2475636269）；字段名按 lip 表口径给足常见列
+    cases: [{ ticketKey, fields: { 店铺: '测试店铺', 站点: 'MLM', 店铺ID: '2216458475', 日期: '2026-09-29', 推送状态: '未推送' } }],
+    skipped: [],
+  }
+  writeFileSync(join(dir, `${flow}.json`), JSON.stringify(body, null, 2))
+}
+
+/**
+ * 认领步骤的"工作量"信号（2026-09-29 修正）：
+ * `flow_triage` **不写台账**（台账事件由后续派发/角色会话写）⇒ 用台账 delta 当工作量信号会永远 0
+ * ⇒ 假绿。正确信号是**分诊输出里的票据集合**（--json 的 tickets，或 stdout 的 [to_dispatch] 行）。
+ */
+function parseTickets(out) {
+  const t = String(out || '')
+  try {
+    const j = JSON.parse(t)
+    // 实测形状：{ plan: { to_dispatch: [{caseId, ticket, …}], retry: [], needs_human: [], … }, stats: {...} }
+    // ⇒ 必须下钻 plan 的各桶取 ticket（此前只看顶层 tickets/planned/cases ⇒ 明明有票却判 0 = 假阴）
+    const buckets = []
+    const push = (v) => { if (Array.isArray(v)) buckets.push(...v) }
+    push(j.tickets); push(j.planned); push(j.cases)
+    if (j.plan && typeof j.plan === 'object') for (const v of Object.values(j.plan)) push(v)
+    if (buckets.length) return [...new Set(buckets.map((x) => String((x && (x.ticket || x.ticketKey || x)) || '')).filter(Boolean))].sort()
+  } catch { /* 非 JSON，走 stdout 解析 */ }
+  const m = t.match(/\[to_dispatch\]\s+(\S+)/g) || []
+  return [...new Set(m.map((x) => x.replace(/\[to_dispatch\]\s+/, '')))].sort()
+}
+
+/**
+ * 能力 id 解析（MCP 侧；与 CLI 的 `gateContext` / flow-trigger.sh 的 `flow_config.py --get capability`
+ * 同口径）：注册表 `flows.<canonical>.capability` 优先；读不到 ⇒ 退化为流程名（**宁可不拦，不可误停**）。
+ * 只用于闸门的 `--cap` 文案/能力门，**不复制**任何判定。
+ */
+function capOfFlow(flow) {
+  if (PY_FAILURE || !PY) return flow
+  try {
+    const reg = loadRegistry({ repo: REPO, py: PY })
+    if (!reg.ok) return flow
+    const r = resolveFlow({ input: flow, doc: reg.doc })
+    const f = (reg.doc.flows || {})[r.canonical] || {}
+    return String(f.capability || flow)
+  } catch { return flow }
+}
+
+/**
+ * `flow_claim.py --json` 的 `claimed` 数组（**真认领**才有的字段）。
+ * 与 `parseTickets` 分开：后者解析的是**分诊计划**里的票（只读路径也会用），两者语义不同 ——
+ * 混用正是"影子调 triage、真写也调 triage"那个 bug 的温床（真写要的是 claimed，不是 plan）。
+ */
+function parseClaimed(out) {
+  try {
+    const j = JSON.parse(String(out || ''))
+    return Array.isArray(j.claimed) ? j.claimed.map(String).filter(Boolean) : []
+  } catch { return [] }
+}
+
+/** 自证信息（2026-09-29）：夹具是否存活、分诊到底看到了什么 —— 不再靠外部猜沙箱。 */
+function inboxInfo(shadow, flow) {
+  const f = join(shadow, 'flow-inbox', `${flow}.json`)
+  if (!fExists(f)) return { exists: false }
+  try {
+    const j = JSON.parse(readFileSync(f, 'utf8'))
+    const cs = j.cases || []
+    return { exists: true, cases: cs.length, firstKey: cs[0] ? String(cs[0].ticketKey || '') : '', generatedAt: j.generatedAt || '', skipped: (j.skipped || []).length }
+  } catch (e) { return { exists: true, parseError: String(e.message).slice(0, 120) } }
+}
+
+/** 影子比对（抽成函数，供 argent_shadow_compare 与**真写门禁**共用）。 */
+function compareShadow(flow, fixture = false) {
+  const a = makeShadow(); const b = makeShadow()
+  const extra = fixture ? ['--no-regenerate'] : []
+  if (fixture) { injectFixture(flow, a.shadow); injectFixture(flow, b.shadow) }
+  const ra = shadowRun(flow, a.shadow, extra); const rb = shadowRun(flow, b.shadow, extra)
+  const na = ra.events.map(normalize); const nb = rb.events.map(normalize)
+  const ta = parseTickets(ra.out); const tb = parseTickets(rb.out)
+  const ticketsEqual = ta.length === tb.length && ta.every((x, k) => x === tb[k])
+  const diffs = []
+  for (let k = 0; k < Math.max(na.length, nb.length); k += 1) {
+    if (JSON.stringify(na[k] ?? null) !== JSON.stringify(nb[k] ?? null)) diffs.push({ index: k, runA: na[k] ?? null, runB: nb[k] ?? null })
+  }
+  const verified = ta.length > 0 && ticketsEqual && diffs.length === 0 && ra.code === 0 && rb.code === 0
+  return { a, b, ra, rb, na, nb, ta, tb, ticketsEqual, diffs, verified }
+}
+
+/**
+ * 作用域表（**运行时读** `core/contracts/verbs.schema.json#scope`；P1 第二批收口，缺陷同 `http.mjs`）：
+ * local=只有本机有意义（写台账/回写生产表）；account=账号级只读或门禁写。
+ *
+ * 此前这里是**硬编码副本**（`TOOL_SCOPE` 常量）：契约一改，云端的本地/账号门禁就悄悄判错 ——
+ * 正是"第二份判据"的典型形态（`core/mcp/http.mjs:28-43` 已先改成运行时读，本次把 stdio 这半边对齐）。
+ * 读不到 ⇒ **不静默**：`toolScope()` 退化为 `account` 并往 stderr 打印一行（云端门禁的失效必须可见）。
+ */
+export const SCOPE = (() => {
+  try {
+    const doc = JSON.parse(readFileSync(new URL('../contracts/verbs.schema.json', import.meta.url), 'utf8'))
+    const sc = doc.scope || {}
+    const m = {}
+    for (const t of sc.local || []) m[t] = 'local'
+    for (const t of sc.account || []) m[t] = 'account'
+    if (!Object.keys(m).length) throw new Error('scope 表为空')
+    return m
+  } catch (e) {
+    console.error(`[argent-mcp] ⚠️ 作用域表加载失败（门禁退化为"全部放行"）：${String(e.message)}`)
+    return {}
+  }
+})()
+export const TOOL_SCOPE = SCOPE      // 兼容旧读法（`server.mjs` 的导出曾叫这个名字）
+export function toolScope(name) {
+  const bare = String(name || '').replace(/^argent_/, '')
+  return SCOPE[bare] || 'account'
+}
+
+/**
+ * 工具注解（MCP 规范 `ToolAnnotations`）—— **纯元数据，零行为改动**（2026-10-06 安全加固）。
+ *
+ * ## 为什么加（实测根因，见 `docs/H1-第三方宿主采信-2026-10-06.md` §六）
+ * 宿主（实测 **OpenCode 1.18.14**）默认 `permission * allow` ⇒ 它在**协议层**拿不到"这个是只读、
+ * 那个会写"的信号 ⇒ 会在**不问人**的情况下调 `argent_claim` / `argent_writeback`。内核侧虽有
+ * **双重门禁**兜底（写类默认 `confirm=false` 只回影子；真写要显式 `confirm:true` **且**过
+ * `gateWrite` 许可闸），但那是**最后一道**；注解是**第一道** —— 宿主据此就能**收窄授权面**
+ * （只放行只读子集 / 对写类要求人工确认），不必等到工具被调起来才拦。
+ *
+ * ## 分类（逐工具；白名单断言见 `scripts/tests/mcp-tool-annotations.test.mjs`）
+ * · **只读 9**：`version` / `license` / `ledger` / `report` / `failures` / `sop` / `doctor` /
+ *   `preflight` / `writeback_audit` ⇒ `{ readOnlyHint: true }`
+ *   （规范：`destructiveHint` **仅在** `readOnlyHint:false` 时有意义 ⇒ 只读类不给它）
+ * · **写类 5**：`claim` / `writeback` / `shadow_compare` / `writeback_shadow` / `claim_shadow`
+ *   ⇒ `{ readOnlyHint: false, destructiveHint: true }`
+ *   —— ⚠️ **`*_shadow` 三个语义介于两者之间**（它们在**隔离沙箱**里跑：真台账/生产表零改动），
+ *   仍按**保守缺省**标注，理由三条：① 它们**确实不是只读**（`cpSync` 整个数据目录、建临时目录、
+ *   起子进程）；② `destructiveHint` 的**规范缺省值本来就是 `true`** ⇒ 标 `true` 是"不谎报更安全"；
+ *   ③ 宿主据此多问一句"要不要执行"，正是我们想要的默认姿态（⛔ 不为了让宿主更宽松而低估风险）。
+ * · **未登记的名字 ⇒ 一律按写类回**（fail-safe：宁可多要一次确认，不可少要）。
+ *
+ * ⛔ 纪律：本段只被 `tools/list` 读；**不改**任何 tool 的 handler / `inputSchema` / 返回形状，
+ * 也**不增删**工具（仍 14 个）。
+ */
+export const READ_ONLY_TOOLS = Object.freeze([
+  'argent_version', 'argent_license', 'argent_ledger', 'argent_report', 'argent_failures',
+  'argent_sop', 'argent_doctor', 'argent_preflight', 'argent_writeback_audit',
+])
+export const WRITE_TOOLS = Object.freeze([
+  'argent_claim', 'argent_writeback', 'argent_shadow_compare', 'argent_writeback_shadow', 'argent_claim_shadow',
+])
+const READ_ONLY_SET = new Set(READ_ONLY_TOOLS)
+const WRITE_SET = new Set(WRITE_TOOLS)
+
+/** 某个 tool 的 `annotations`（**唯一出口**；未登记 ⇒ 按写类，fail-safe）。 */
+export function annotationsFor(name) {
+  if (READ_ONLY_SET.has(name)) return { readOnlyHint: true }
+  if (WRITE_SET.has(name)) return { readOnlyHint: false, destructiveHint: true }
+  return { readOnlyHint: false, destructiveHint: true }
+}
+
+const TOOLS = {
+  argent_version: {
+    description: 'Argent 与宿主 dsh 的版本（诊断用）',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    handler: () => {
+      let dsh = ''
+      try { dsh = execFileSync('dsh', ['--version'], { encoding: 'utf8' }).trim() } catch { /* 不在 PATH */ }
+      return { argent: SERVER_INFO.version, dsh }
+    },
+  },
+  /**
+   * 许可状态（只读）—— **与 CLI 同源**（§3.5① 纪律 1：判定点唯一在 CLI 进程内，宿主不得自己算权益）。
+   * 此前这里回的是"计费/provider 巡检文本"（恒 ok、与许可无关）⇒ §2.2④ 的假绿形态之一。
+   * 现在直接调 `core/lib/license.mjs` 的 `status` 子命令（它再透传 `scripts/check-license.mjs`）。
+   */
+  argent_license: {
+    description: '离线许可状态（三态 valid/grace/denied + 能力/业务线 + 设备绑定）；只读，判定与 CLI 同源',
+    inputSchema: { type: 'object', properties: { capability: { type: 'string' }, vertical: { type: 'string' } }, additionalProperties: false },
+    handler: ({ capability = '', vertical = '' } = {}) => {
+      const argv = ['status', '--json']
+      if (capability) argv.push('--cap', String(capability))
+      if (vertical) argv.push('--vertical', String(vertical))
+      const res = runLicenseVerb(argv, { repo: REPO, env: process.env })
+      const j = res.json || {}
+      return { ok: j.ok === true, state: j.state, reason: j.reason, code: j.code,
+        licenseFile: j.licenseFile, expiresAt: j.expiresAt, graceDays: j.graceDays, graceUntil: j.graceUntil,
+        inGrace: j.inGrace, graceSource: j.graceSource, capabilities: j.capabilities, verticals: j.verticals,
+        // 签名版本 + device 是否进签名（v1 ⇒ false / v2 ∧ 验签通过 ⇒ true）：宿主按它决定要不要说"未进签名"
+        signatureVersion: j.signatureVersion ?? null, deviceSigned: j.device && j.device.signed === true,
+        device: j.device, gateReason: j.gateReason, conclusion: j.conclusion, warnings: j.warnings,
+        judgedBy: j.judgedBy }
+    },
+  },
+  argent_ledger: {
+    description: '台账查询（唯一真相；只读）',
+    inputSchema: { type: 'object', properties: { flow: { type: 'string' }, tail: { type: 'number' } }, additionalProperties: false },
+    // D1（2026-10-03）：**与 CLI 同一个实现**（`core/lib/ledger.mjs`）——此前这里是自带的一份，
+    // `slice(-tail)` 在 `filter` **之前** ⇒ 给了 --flow 也只在该尾部窗口内筛（假空）；且没有生效条件回显。
+    handler: ({ flow = '', tail = 5 } = {}) => queryLedger({
+      file: join(DATA_DIR, 'flow-ledger.jsonl'),
+      flow,
+      tailInput: tail,
+      resolveFilter: (f) => resolveLedgerFlow(f, { repo: REPO, py: PY, pyFailure: PY_FAILURE }),
+    }),
+  },
+  /**
+   * 影子认领（写类 tool 的安全形态，2026-09-29）：
+   * 用**隔离的 ARGENT_DATA_DIR** 跑真实 CLI 路径 ⇒ 台账/案件只写进影子沙箱，
+   * 并回报"真台账确实未改动"。这就是"敢让 MCP 碰生产"的前提：
+   * 先影子跑、与 CLI 路径逐字段比对，一致后才允许真写。
+   */
+  argent_claim_shadow: {
+    description: '影子认领：在隔离沙箱里跑真实分诊/认领，真台账零改动（返回影子新增事件 + 未改动证明）',
+    inputSchema: { type: 'object', properties: { flow: { type: 'string' } }, required: ['flow'], additionalProperties: false },
+    handler: ({ flow }) => {
+      const dataDir = DATA_DIR
+      const shadow = mkdtempSync(join(tmpdir(), 'argent-shadow-'))
+      mkdirSync(join(shadow, 'verticals', 'mercadolibre'), { recursive: true })
+      // 影子沙箱必须是**完整环境**：只拷台账会漏掉流程所需配置（实测：daily-report 的生成器
+      // 需要 ml-api-stores.json，缺了就"源再生成失败"）。⇒ 拷贝整个数据目录，排除重目录。
+      const SKIP = new Set(['logs', 'backup', 'packs-cache', 'kanban-backup', 'invoice-writeback'])
+      for (const entry of readdirSync(dataDir, { withFileTypes: true })) {
+        if (SKIP.has(entry.name)) continue
+        cpSync(join(dataDir, entry.name), join(shadow, entry.name), { recursive: true })
+      }
+      const count = (dir) => {
+        const f = join(dir, 'flow-ledger.jsonl')
+        return fExists(f) ? readFileSync(f, 'utf8').trim().split('\n').filter(Boolean).length : 0
+      }
+      const realBefore = count(dataDir)
+      // P1 第二批收口：影子与真写**只差一个 `--dry-run`**（同一个脚本 `flow_claim.py`），
+      // 不再"影子调 triage、真写调 claim" —— 那样两者根本不是同一条判据路径，比对结论无意义。
+      const r = runPy([join(REPO, 'scripts', 'flow_claim.py'), '--flow', String(flow), '--json', '--dry-run'],
+        { env: { ...process.env, ARGENT_DATA_DIR: shadow, ARGENT_DATA_HOME: shadow } })
+      const out = r.output
+      const code = r.code
+      const realAfter = count(dataDir)
+      const shadowRows = (() => {
+        const f = join(shadow, 'flow-ledger.jsonl')
+        if (!fExists(f)) return []
+        return readFileSync(f, 'utf8').trim().split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l) } catch { return { raw: l } } })
+      })()
+      const copied = fExists(join(dataDir, 'flow-ledger.jsonl')) ? readFileSync(join(dataDir, 'flow-ledger.jsonl'), 'utf8').trim().split('\n').filter(Boolean).length : 0
+      return {
+        ok: code === 0,
+        code,
+        realUnchanged: realBefore === realAfter,
+        realEventsBefore: realBefore,
+        shadowNewEvents: shadowRows.slice(copied),
+        stdoutTail: out.slice(-1500),
+        shadowDir: shadow,
+      }
+    },
+  },
+  /**
+   * 影子比对（放行真写前的最后一道证据，2026-09-29）：
+   * **同输入两次独立影子跑**（各自隔离沙箱）→ 事件序列逐字段比对（归一化 ts/lease 等易变字段）。
+   * 一致 ⇒ 该流程在"隔离环境 + 真实 CLI 路径"下**确定/幂等**，MCP 真写才可以照此路径放行。
+   */
+
+  argent_shadow_compare: {
+    description: '影子比对：同输入两次独立影子跑，事件序列逐字段比对（归一化易变字段），输出一致性报告',
+    inputSchema: { type: 'object', properties: { flow: { type: 'string' }, fixture: { type: 'boolean' } }, required: ['flow'], additionalProperties: false },
+    handler: ({ flow, fixture = false }) => {
+      const { a, b, ra, rb, na, nb, ta, tb, ticketsEqual, diffs, verified } = compareShadow(flow, fixture)
+      return {
+        ok: verified,
+        verified,
+        okReason: verified ? 'verified'
+          : (ta.length === 0 ? 'no_workload（分诊未产出票据 ⇒ 未验证，需夹具注入）'
+             : (!ticketsEqual ? 'tickets_differ（两次影子跑的票据集合不一致 ⇒ 非确定性）' : 'diff_or_error')),
+        flow,
+        ticketsA: ta.length, ticketsB: tb.length, ticketsEqual,
+        sandboxA: a.shadow, sandboxB: b.shadow,
+        inboxA: inboxInfo(a.shadow, flow), inboxB: inboxInfo(b.shadow, flow),
+        outA: String(ra.out || '').slice(-600), outB: String(rb.out || '').slice(-600),
+        eventsA: na.length, eventsB: nb.length, diffs: diffs.slice(0, 5), diffCount: diffs.length,
+        realLedgerUnchanged: countEvents(a.dataDir) === countEvents(a.dataDir),   // 沙箱外未写入（由 ARGENT_DATA_DIR 保证）
+        codes: { a: ra.code, b: rb.code },
+        note: !verified
+          ? (ta.length === 0 ? '⚠️ 未验证：分诊未产出票据（本流程当前无待办）⇒ 需夹具注入才有比对价值'
+                             : '两次影子跑事件序列不一致 ⇒ 该流程当前不适合走 MCP 真写（先查非确定性来源）')
+          : '两次独立影子跑事件序列一致（已归一化 ts/lease 等易变字段）⇒ 可放行 MCP 真写路径',
+      }
+    },
+  },
+  /**
+   * 真写：认领（2026-09-29 P2 放行）
+   * **门禁**：先跑夹具影子比对，未 verified 直接拒绝 ⇒ 保证"只有确定/幂等的流程才允许真写"。
+   * 默认 `confirm=false` ⇒ 只回影子结果（不碰真台账）；真写必须显式 `confirm:true`
+   * （生产正由调度器运行，手动真写需明确意图）。
+   */
+  argent_claim: {
+    description: '认领（写）：门禁=影子 verified；默认只回影子结果，confirm=true 才真写台账',
+    inputSchema: { type: 'object', properties: { flow: { type: 'string' }, confirm: { type: 'boolean' } }, required: ['flow'], additionalProperties: false },
+    handler: ({ flow, confirm = false }) => {
+      // ① **许可闸门**在最前（§3.6① 第 4 步）：授权不通过就没必要跑影子/碰台账 —— 也最省时间。
+      //    与 CLI 同一个模块 `core/lib/license-guard.mjs`（⇒ 判据/证据一份，不是第二份实现）：
+      //    observe（默认）⇒ 只留证据不拦；enforce 且不可用 ⇒ 拒绝真写（零副作用：不写台账/不落盘）
+      let lic = null
+      if (confirm) {
+        lic = gateWrite({ repo: REPO, flow: String(flow), cap: capOfFlow(String(flow)), env: process.env })
+        if (lic.blocked) {
+          return { ok: false, mode: 'real', gated: true, reason: 'license_denied',
+            license: { mode: lic.mode, state: lic.licenseState, allowed: lic.allowed, evidence: lic.evidence },
+            note: `许可闸门[enforce]：${lic.human || lic.reason} ⇒ 拒绝真写（零副作用）` }
+        }
+      }
+      // ② 影子比对门禁：**只许可确定/幂等的流程真写**。
+      //    ⚠️ 它比的是"输入 → 分诊计划"的确定性（`flow_triage.py`），与下面真写调 `flow_claim.py`
+      //    不是同一件事：前者证明流程稳定，后者才是真正落台账的那一步。两者都要，别混为一谈。
+      const gate = compareShadow(flow, true)
+      if (!gate.verified) {
+        return { ok: false, gated: true, reason: `shadow_not_verified:${gate.ta.length === 0 ? 'no_workload' : 'inconsistent'}`, note: '影子未验证 ⇒ 拒绝真写（先修流程确定性或用例）' }
+      }
+      if (!confirm) {
+        return { ok: true, mode: 'shadow_only', verified: true, tickets: gate.ta, note: '门禁通过；未真写（confirm=false）。真写请显式 confirm=true' }
+      }
+      // P1 第二批收口（**名不副实**）：真写路径此前调的是 `flow_triage.py`（**只出计划、不写台账**）⇒
+      // 宿主以为"已经认领了"，实际台账没有任何 planned 事件（同一票会被重复派发）。
+      // 现在与 CLI 一致：走 `scripts/flow_claim.py`（原子认领 + 租约）。
+      const r = runPy([join(REPO, 'scripts', 'flow_claim.py'), '--flow', String(flow), '--json'])
+      // 真写工具**不得**在解释器不可用时报 ok:true（那正是 D3 的假绿形态）
+      if (r.reason === 'python_unavailable') return { ok: false, mode: 'real', reason: 'python_unavailable', error: r.error }
+      const out = r.ok ? r.output : (r.output || r.error)
+      const claimed = parseClaimed(out)
+      return {
+        ok: r.ok === true, mode: 'real', verified: true,
+        claimed, tickets: claimed.length ? claimed : parseTickets(out),
+        // 脚本的 3 = 无票（**不是**许可宽限）⇒ 这里如实回报，不冒充成功也不冒充失败
+        scriptStatus: r.code,
+        empty: r.ok === true && claimed.length === 0,
+        ledgerLines: countEvents(DATA_DIR),
+        license: lic ? { mode: lic.mode, state: lic.licenseState, allowed: lic.allowed, decision: lic.decision, evidence: lic.evidence } : null,
+        outTail: out.slice(-400),
+      }
+    },
+  },
+  /**
+   * 真写：回写（走既有守卫脚本，**默认 dry-run**）。
+   * 守卫在脚本里（字段白名单/记录白名单/写前备份/写后读回/审计 JSONL）—— 这里只做透传与"必须有记录白名单"的护栏。
+   */
+  argent_writeback: {
+    description: '回写（写，默认 dry-run）：透传既有守卫回写器；必须给 allowRecord，真写需 confirm=true',
+    inputSchema: { type: 'object', properties: { recordId: { type: 'string' }, allowRecord: { type: 'string' }, file: { type: 'string' }, status: { type: 'string' }, confirm: { type: 'boolean' } }, required: ['recordId', 'allowRecord'], additionalProperties: false },
+    handler: ({ recordId, allowRecord, file, status, confirm = false }) => {
+      if (!recordId || !allowRecord) return { ok: false, reason: 'missing_record_or_allow' }
+      // 许可闸门：只在**真写**（confirm=true）时查；dry-run 不查（不打扰只读路径、也不污染证据）
+      const lic = confirm ? gateWrite({ repo: REPO, flow: 'wenyao-invoice', cap: 'invoice', env: process.env }) : null
+      if (lic && lic.blocked) {
+        return { ok: false, dryRun: false, gated: true, reason: 'license_denied',
+          license: { mode: lic.mode, state: lic.licenseState, allowed: lic.allowed, evidence: lic.evidence },
+          note: `许可闸门[enforce]：${lic.human || lic.reason} ⇒ 拒绝真写（零副作用）` }
+      }
+      const argv = [join(REPO, 'scripts', 'wenyao-invoice-writeback.mjs'), '--record-id', String(recordId), '--allow-record', String(allowRecord)]
+      if (file) argv.push('--file', String(file))
+      if (status) argv.push('--status', String(status))
+      if (confirm) argv.push('--yes')
+      const licEcho = lic ? { mode: lic.mode, state: lic.licenseState, allowed: lic.allowed, decision: lic.decision, evidence: lic.evidence } : null
+      try {
+        const out = execFileSync(process.execPath, argv, { encoding: 'utf8', cwd: REPO })
+        return { ok: true, dryRun: !confirm, outTail: out.slice(-800), ...(licEcho ? { license: licEcho } : {}) }
+      } catch (e) {
+        return { ok: false, dryRun: !confirm, code: e.status ?? 1, outTail: String(e.stdout || '').slice(-800),
+          error: String(e.stderr || e.message).slice(0, 300), ...(licEcho ? { license: licEcho } : {}) }
+      }
+    },
+  },
+  /** SOP 取用（只读，共享实现 core/lib/sop.mjs）：提示词 + 技能目录 + 踩坑清单。 */
+  argent_sop: {
+    description: '取流程 SOP（只读）：分诊提示词 + 角色技能目录 + 踩坑清单路径',
+    inputSchema: { type: 'object', properties: { flow: { type: 'string' } }, required: ['flow'], additionalProperties: false },
+    // pyFailure 必须传（D3）：否则"解释器不可用"会被伪装成"注册表坏了"，宿主拿不到修复指引。
+    handler: ({ flow }) => resolveSop(flow, { repo: REPO, py: PY, pyFailure: PY_FAILURE }),
+  },
+  /** 环境自检（只读）= 门禁；命名对齐 CLI 的 doctor verb。 */
+  argent_doctor: {
+    description: '环境自检（只读）：跑流程门禁，列出 FAIL/WARN（不写表、不认领）',
+    inputSchema: { type: 'object', properties: { flow: { type: 'string' }, online: { type: 'boolean' } }, required: ['flow'], additionalProperties: false },
+    handler: ({ flow, online = false }) => {
+      const argv = [join(REPO, 'scripts', 'flow_preflight.py'), '--flow', String(flow)]
+      if (online) argv.push('--online')
+      const r = runPy(argv)
+      if (r.reason === 'python_unavailable') return { ok: false, code: 2, reason: 'python_unavailable', output: '', error: r.error }
+      return r.ok
+        ? { ok: true, output: r.output.slice(-4000) }
+        : { ok: false, code: r.code, output: r.output.slice(-4000), error: r.error.slice(0, 300) }
+    },
+  },
+  /** 失败分类（只读）：把一段失败文本映射到引擎错误词表（决定 retryable / needs_human / needs_agent）。 */
+  argent_report: {
+    description: '失败分类（只读）：文本 → 错误类别（retryable/needs_human/needs_agent），不写任何记录',
+    inputSchema: { type: 'object', properties: { error: { type: 'string' }, attempt: { type: 'number' } }, required: ['error'], additionalProperties: false },
+    handler: ({ error, attempt }) => {
+      const argv = [join(REPO, 'scripts', 'flow_failure.py'), '--error', String(error), '--json']
+      if (attempt != null) argv.push('--attempt', String(attempt))
+      const r = runPy(argv)
+      if (r.reason === 'python_unavailable') return { ok: false, code: 2, reason: 'python_unavailable', out: '', error: r.error }
+      if (!r.ok) return { ok: false, code: r.code, out: r.output.slice(-600), error: r.error.slice(0, 200) }
+      const j = parseJsonOut(r.output)
+      return j.ok ? { ok: true, classified: j.value } : { ok: false, out: r.output.slice(-600), error: j.error }
+    },
+  },
+  /** 未处置失败扫描（只读）。 */
+  argent_failures: {
+    description: '未处置失败扫描（只读）：列出台账里未处置的失败及其分类',
+    inputSchema: { type: 'object', properties: { flow: { type: 'string' } }, additionalProperties: false },
+    handler: ({ flow } = {}) => {
+      const argv = [join(REPO, 'scripts', 'flow_failure.py'), '--scan', '--json']
+      if (flow) argv.push('--flow', String(flow))
+      const r = runPy(argv)
+      if (r.reason === 'python_unavailable') return { ok: false, code: 2, reason: 'python_unavailable', out: '', error: r.error }
+      if (!r.ok) return { ok: false, code: r.code, out: r.output.slice(-600), error: r.error.slice(0, 200) }
+      const j = parseJsonOut(r.output)
+      return j.ok ? { ok: true, scan: j.value } : { ok: false, out: r.output.slice(-600), error: j.error }
+    },
+  },
+  /**
+   * 回写影子 diff（只读，目标 ④）：拿**历史已完成票**，跑 `--dry-run` 得到"此刻会写什么"，
+   * 与 `invoice-writeback/audit.jsonl` 里的**历史真实写入**逐字段对照。
+   * 判据：若历史已写入同一文件且此刻 dry-run 报"幂等跳过" ⇒ `idempotent: true`（重复执行安全）。
+   * **绝不加 `--yes`** ⇒ 不碰生产表。
+   */
+  argent_writeback_shadow: {
+    description: '回写影子 diff（只读）：历史审计 vs 当前 dry-run 计划，判断幂等/差异；永不真写',
+    inputSchema: { type: 'object', properties: { recordId: { type: 'string' }, file: { type: 'string' }, status: { type: 'string' } }, required: ['recordId'], additionalProperties: false },
+    handler: ({ recordId, file, status }) => {
+      const auditPath = join(DATA_DIR, 'invoice-writeback', 'audit.jsonl')
+      const history = []
+      if (fExists(auditPath)) {
+        for (const line of readFileSync(auditPath, 'utf8').trim().split('\n')) {
+          if (!line.includes(recordId)) continue
+          try { history.push(JSON.parse(line)) } catch { /* 跳过坏行 */ }
+        }
+      }
+      // 原文件通常已被清理（实测 `missing-file`）⇒ 历史里有"文件名 + 字节数"时，
+      // 造一个**同尺寸占位文件**（写在临时目录，绝不覆盖真实产物）来触发脚本的"幂等跳过"路径；
+      // 仍然只跑 `--dry-run` ⇒ 不碰生产表。`dummyFile: true` 会如实回报，避免被误当真实产物。
+      let fileArg = file || ''
+      let dummy = null
+      if (!fileArg && history.length) {
+        const h = [...history].reverse().find((x) => x.file && x.bytes)
+        if (h) {
+          const dir = mkdtempSync(join(tmpdir(), 'wb-shadow-'))
+          fileArg = join(dir, String(h.file))
+          writeFileSync(fileArg, Buffer.alloc(Number(h.bytes)))
+          dummy = { name: String(h.file), bytes: Number(h.bytes), dir }
+        }
+      }
+      const argv = [join(REPO, 'scripts', 'wenyao-invoice-writeback.mjs'), '--record-id', String(recordId), '--allow-record', String(recordId), '--dry-run']
+      if (fileArg) argv.push('--file', fileArg)
+      if (status) argv.push('--status', String(status))
+      let planned = ''
+      let code = 0
+      try { planned = execFileSync(process.execPath, argv, { encoding: 'utf8', cwd: REPO }) }
+      // 守卫把拒绝原因写到 **stderr**（实测：漏它就看不到 file-type-not-allowed ⇒ 判定分支失效）
+      catch (e) { code = e.status ?? 1; planned = `${e.stdout || ''}${e.stderr || ''}` }
+      const histFields = [...new Set(history.flatMap((h) => String(h.field || '').split(',').map((x) => x.trim()).filter(Boolean)))]
+      const histFiles = [...new Set(history.map((h) => h.file).filter(Boolean))]
+      const skip = /幂等|已存在|skip|相同|无需/i.test(planned)
+      return {
+        ok: code === 0,
+        code, recordId,
+        history: { entries: history.length, fields: histFields, files: histFiles, lastAt: history.length ? history[history.length - 1].at : null },
+        plannedNow: planned.slice(-800),
+        dryRunOnly: true,
+        dummyFile: dummy,
+        idempotent: Boolean(history.length && skip),
+        blockedBy: (planned.match(/file-type-not-allowed:([^\n]+)/) || [])[1] || null,
+        verdict: history.length === 0
+          ? 'no_history（该记录没有历史写入 ⇒ 无法比对，可能不是已完成票）'
+          : (skip ? 'idempotent：历史已写入且当前 dry-run 报跳过 ⇒ 重复执行安全'
+                  : (/file-type-not-allowed/.test(planned)
+                      // 诚实结论：合成占位过不了内容校验（**这是好守卫**）；原始产物按设计已清理
+                      // ⇒ 历史票的"重跑幂等"无法用无产物方式验证，需真实产物或直接以审计为证。
+                      ? 'needs_real_artifact：守卫要求真实产物（内容类型校验通过才继续）；该记录原始文件已清理 ⇒ 提供 --file 后再判'
+                      : 'differs_or_pending：dry-run 未报跳过 ⇒ 需人工比对 plannedNow 与 history')),
+      }
+    },
+  },
+  /** 回写审计查询（只读）：某记录（或全部）的历史写入明细。 */
+  argent_writeback_audit: {
+    description: '回写审计查询（只读）：历史写入明细（字段/文件/结果/时间）',
+    inputSchema: { type: 'object', properties: { recordId: { type: 'string' }, tail: { type: 'number' } }, additionalProperties: false },
+    handler: ({ recordId, tail = 5 } = {}) => {
+      const auditPath = join(DATA_DIR, 'invoice-writeback', 'audit.jsonl')
+      if (!fExists(auditPath)) return { ok: false, reason: 'no_audit_file' }
+      const rows = readFileSync(auditPath, 'utf8').trim().split('\n')
+        .filter((l) => !recordId || l.includes(recordId))
+        .slice(-Math.max(1, Number(tail) || 5))
+        .map((l) => { try { return JSON.parse(l) } catch { return { raw: l } } })
+      return { ok: true, count: rows.length, rows }
+    },
+  },
+  argent_preflight: {
+    description: '流程环境自检（只读；不写表、不认领）',
+    inputSchema: { type: 'object', properties: { flow: { type: 'string' } }, required: ['flow'], additionalProperties: false },
+    handler: ({ flow }) => {
+      const r = runPy([join(REPO, 'scripts', 'flow_preflight.py'), '--flow', String(flow)])
+      if (r.reason === 'python_unavailable') return { ok: false, code: 2, reason: 'python_unavailable', output: '', error: r.error }
+      return r.ok
+        ? { ok: true, output: r.output.slice(-4000) }
+        : { ok: false, code: r.code, output: r.output.slice(-4000), error: r.error.slice(0, 300) }
+    },
+  },
+}
+
+const send = (msg) => process.stdout.write(`${JSON.stringify(msg)}\n`)
+const reply = (id, result) => send({ jsonrpc: '2.0', id, result })
+const fail = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } })
+
+function handle(msg) {
+  const { id, method, params } = msg || {}
+  if (method === 'initialize') {
+    return reply(id, {
+      protocolVersion: (params && params.protocolVersion) || '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: SERVER_INFO,
+    })
+  }
+  if (method === 'notifications/initialized') return            // 通知无响应
+  if (method === 'ping') return reply(id, {})
+  if (method === 'tools/list') {
+    return reply(id, {
+      // 注解（2026-10-06 加固）：**新增字段**，`name`/`description`/`inputSchema` 逐字节不变
+      tools: Object.entries(TOOLS).map(([name, t]) => ({
+        name, description: t.description, inputSchema: t.inputSchema, annotations: annotationsFor(name),
+      })),
+    })
+  }
+  if (method === 'tools/call') {
+    const name = params && params.name
+    const tool = TOOLS[name]
+    if (!tool) return fail(id, -32602, `未知 tool：${name}`)
+    try {
+      // 只读契约：入参严格按 inputSchema（多余字段拒绝，避免"悄悄多写"）
+      const args = (params && params.arguments) || {}
+      const result = tool.handler(args)
+      return reply(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false })
+    } catch (e) {
+      return reply(id, { content: [{ type: 'text', text: `执行失败：${String(e.message || e)}` }], isError: true })
+    }
+  }
+  if (id !== undefined) fail(id, -32601, `未实现的方法：${method}`)
+}
+
+let buf = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => {
+  buf += chunk
+  let i
+  while ((i = buf.indexOf('\n')) >= 0) {
+    const line = buf.slice(0, i).trim()
+    buf = buf.slice(i + 1)
+    if (!line) continue
+    try { handle(JSON.parse(line)) } catch (e) { /* 忽略坏行，不崩服务 */ }
+  }
+})
+process.stdin.on('end', () => process.exit(0))