@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/core/lib/notify/webhook.mjs

@@ -0,0 +1,135 @@
+/**
+ * `webhook` 通道（P2 首发；§6.2 Q2 的建议选项 A：**零凭据、可离线桩测**）。
+ *
+ * 形态：一次 `POST <url>`，`application/json` 体，**不跟随重定向**（3xx 如实报失败 ——
+ * "被重定向到登录页"不是投递成功），`timeoutMs` 到点即失败（不挂住调用方）。
+ *
+ * ⛔ 本文件**不含任何"该不该发"的判据**（去重、开关、dry-run、审计全在 L1 的 verb 层）。
+ *   它只做一件事：把这份意图送出去，并如实回报**送到了/没送到、对方回了几多**。
+ *
+ * 为什么手写 `node:http(s)` 而不是 `fetch`：① 只依赖 Node 内置（无宿主、无第三方包）；
+ * ② 需要"不跟随重定向 + 明确超时 + 拿到状态码与响应片段"这三件事的可判行为；
+ * ③ 在**无宿主·极简 PATH** 的冒烟环境里行为一致（P4 的 S6 用它打本地桩）。
+ */
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+
+export const CHANNEL = 'webhook'
+export const IMPLEMENTED = true
+export const TARGET = {
+  required: true,
+  label: '--url',
+  schemes: ['http:', 'https:'],
+  note: '通用 HTTP POST（JSON 体；不跟随重定向）',
+}
+
+/** 默认超时（ms）。10s 是"本地桩秒回、真实端点也够"的保守值。 */
+export const DEFAULT_TIMEOUT_MS = 10000
+/** 响应片段最多回显多少字符（诊断够用，不会把 payload 灌进日志）。 */
+const RESPONSE_EXCERPT_CHARS = 400
+/** 允许的头部名（避免注入 CRLF / 覆盖 Host 之类）。 */
+const HEADER_NAME_RE = /^[A-Za-z0-9-]+$/
+
+/**
+ * 目标校验（**用法**层面，不是业务判断）：必须是绝对 http(s) URL。
+ * @returns {{ok:true, target:string} | {ok:false, reason:'target_required'|'bad_target', error:string}}
+ */
+export function validateTarget(target) {
+  const raw = String(target == null ? '' : target).trim()
+  if (!raw) return { ok: false, reason: 'target_required', error: `webhook 通道缺少目标：请给 ${TARGET.label} <http(s)://…>` }
+  let u = null
+  try { u = new URL(raw) } catch { return { ok: false, reason: 'bad_target', error: `目标不是合法 URL：${raw}` } }
+  if (!TARGET.schemes.includes(u.protocol)) {
+    return { ok: false, reason: 'bad_target', error: `webhook 只支持 ${TARGET.schemes.join(' / ')}，实得 ${u.protocol}` }
+  }
+  return { ok: true, target: u.toString() }
+}
+
+/** `--header 'K: V'` → 对象（坏头 ⇒ 明确报错，不静默丢）。 */
+export function parseHeaders(list) {
+  const out = {}
+  for (const h of list || []) {
+    const s = String(h)
+    const i = s.indexOf(':')
+    if (i < 1) return { ok: false, error: `--header 形态应为 'Name: value'，实得 ${JSON.stringify(s)}` }
+    const name = s.slice(0, i).trim()
+    const value = s.slice(i + 1).trim()
+    if (!HEADER_NAME_RE.test(name)) return { ok: false, error: `--header 头部名非法：${JSON.stringify(name)}` }
+    out[name] = value
+  }
+  return { ok: true, headers: out }
+}
+
+/** 去掉 URL 里的凭据与查询串（回显/审计用；**不改变实际投递目标**）。 */
+export function sanitizeTarget(target) {
+  try {
+    const u = new URL(String(target))
+    u.username = ''
+    u.password = ''
+    u.search = ''
+    return u.toString()
+  } catch { return String(target || '') }
+}
+
+/**
+ * 投递（唯一副作用点：一次 HTTP 请求）。
+ * @param {{target:string, text:string, kind:string, summary:string, idempotencyKey:string, headers?:object, sentAt?:string}} intent
+ * @param {{timeoutMs?:number, deps?:object}} [opts] `deps.request` 可注入（夹具用，不联网）
+ */
+export function send(intent, opts = {}) {
+  const v = validateTarget(intent && intent.target)
+  if (!v.ok) return { ok: false, reason: v.reason, error: v.error }
+  const url = new URL(v.target)
+  const timeoutMs = Number(opts.timeoutMs || DEFAULT_TIMEOUT_MS)
+  const payload = {
+    source: 'argent',
+    channel: CHANNEL,
+    kind: intent.kind || 'generic',
+    summary: intent.summary || '',
+    text: intent.text == null ? '' : String(intent.text),
+    idempotencyKey: intent.idempotencyKey || null,
+    sentAt: intent.sentAt || new Date().toISOString(),
+  }
+  const body = Buffer.from(JSON.stringify(payload), 'utf8')
+  const headers = { 'content-type': 'application/json; charset=utf-8', 'content-length': String(body.length), ...(intent.headers || {}) }
+  const doRequest = (opts.deps && opts.deps.request) || (url.protocol === 'https:' ? httpsRequest : httpRequest)
+
+  return new Promise((resolve) => {
+    let settled = false
+    const done = (r) => { if (!settled) { settled = true; resolve(r) } }
+    let req = null
+    try {
+      req = doRequest({
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: `${url.pathname}${url.search}`,
+        method: 'POST',
+        headers,
+        timeout: timeoutMs,
+      }, (res) => {
+        let text = ''
+        res.setEncoding('utf8')
+        res.on('data', (c) => { if (text.length < RESPONSE_EXCERPT_CHARS) text += c })
+        res.on('end', () => {
+          const status = Number(res.statusCode || 0)
+          const ok = status >= 200 && status < 300
+          done({
+            ok,
+            status,
+            responseExcerpt: text.slice(0, RESPONSE_EXCERPT_CHARS),
+            reason: ok ? null : 'delivery_failed',
+            error: ok ? null : `webhook 返回 ${status}（2xx 才算投递成功；**不跟随重定向**，3xx 如实算失败）`,
+            bytes: body.length,
+          })
+        })
+        res.on('error', (e) => done({ ok: false, status: null, reason: 'delivery_failed', error: `读取响应失败：${e && e.message}`, bytes: body.length }))
+      })
+    } catch (e) {
+      return done({ ok: false, status: null, reason: 'delivery_failed', error: `请求构造失败：${(e && e.message) || e}`, bytes: body.length })
+    }
+    req.on('timeout', () => { req.destroy(new Error(`超时（${timeoutMs}ms）`)) })
+    req.on('error', (e) => done({ ok: false, status: null, reason: 'delivery_failed', error: `请求失败：${(e && e.message) || e}`, bytes: body.length }))
+    req.end(body)
+  })
+}

package/engine/core/lib/notify/wecom.mjs

@@ -0,0 +1,36 @@
+/**
+ * `wecom`（企业微信）通道 —— **预留位**（P2 第二批；本批不实现）。
+ *
+ * 为什么不首发（§6.2 Q2 的选项 C 被否）：它需要**企业微信应用凭据 + 客户配合**，
+ * 排期不可控；而 `webhook` 零凭据、可离线桩测（P4 的 S6 就靠它）。故本批 webhook 首发。
+ *
+ * 落地时的最小可用形态（写在这里，免得实现时再拍一次）：
+ *   · 群机器人 webhook：一次 POST `{"msgtype":"text","text":{"content":"…"}}` —— **零凭据**，
+ *     与 `webhook.mjs` 的差异只在**请求体形态**（故实现可直接复用 webhook 的传输层，只换 payload）。
+ *   · 应用消息：需 `corpid/corpsecret/agentid`（走既有凭据槽位，⛔ 不新开明文文件、不进仓库）。
+ *   · 目标形态、错误映射同上（`failureClasses` 为唯一权威）。
+ */
+export const CHANNEL = 'wecom'
+export const IMPLEMENTED = false
+export const NOTE = '企业微信（P2 第二批）：群机器人 webhook 可零凭据起步，应用消息需凭据'
+export const TARGET = {
+  required: true,
+  label: '--target',
+  schemes: ['http:', 'https:'],
+  note: '群机器人 webhook / 应用消息（待实现）',
+}
+
+export function validateTarget(target) {
+  const raw = String(target == null ? '' : target).trim()
+  if (!raw) return { ok: false, reason: 'target_required', error: 'wecom 通道缺少目标（群机器人 webhook）' }
+  return { ok: true, target: raw }
+}
+
+/** 预留位：**永不**返回成功。 */
+export function send() {
+  return {
+    ok: false,
+    reason: 'channel_not_implemented',
+    error: 'wecom 通道尚未实现（预留位）⇒ 本批请用 --channel webhook；实现落点见本文件头注释',
+  }
+}

package/engine/core/lib/python.mjs

@@ -0,0 +1,145 @@
+/**
+ * Python 解释器解析（0.3 P1，2026-10-03）—— **多候选 + 响亮失败**（修 D3）。
+ *
+ * 为什么有它（D3 实测）：`core/cli/argent.mjs` 与 `core/mcp/server.mjs` 都只有**一个**候选
+ * （`ARGENT_PY || <数据目录>/venv/bin/python3`），候选不存在时 exec 失败，而 `core/lib/sop.mjs`
+ * 的空 `catch {}` 把它吞掉 ⇒ `sop` 返回 `matchedBy:"none"` 且 **exit 0**：机器上"看起来没有流程"，
+ * 实际是解释器不在。**静默降级比崩溃贵**（与 2026-09-22 触发器那次"每 5 分钟正常空转"同类）。
+ *
+ * 判据与 `scripts/flow-trigger.sh` 的 `pick_py()` **同源**（不另立第二套）：
+ *   · 候选顺序：ARGENT_PY → ARGENT_PYTHON → venv（数据目录 / 仓库）→ PATH 的 python3、python3.11
+ *   · 可用 = 能启动 ∧ 版本 ≥ `scripts/lib/python-runtime.mjs#MIN_PYTHON` ∧ 能 `import openpyxl, yaml`
+ *     （后两项逐字对齐 pick_py 的 `import openpyxl, yaml` 与 python-runtime 的版本门禁 ——
+ *      2026-09-28 客户机事故就是"只看 import 不看版本"，把 3.9.6 的 venv 判成就绪）
+ *   · 全不可用 ⇒ 调用方**响亮失败**（CLI exit 2 + 诊断），不得静默降级
+ *
+ * venv 只认**数据目录**（`resolveDataDir` 三级链 = 内核唯一判据：ARGENT_DATA_DIR → $DSH_HOME/argent
+ * → ~/.dsh/argent；`$DSH_HOME` 那一级已经折进它）—— 不再另加一条 `$HOME/.dsh/argent/venv` 同义候选：
+ * `ARGENT_DATA_DIR` 显式隔离时，宁可响亮失败，也不悄悄换用另一棵树的解释器（那正是 D3 要消灭的
+ * "看起来跑了、其实读的不是你以为的那份环境"）。
+ *
+ * 纪律：候选只来自"显式指定 / 已知安装位置 / PATH"，**不写死 `/usr/bin/python3` 这类绝对路径**。
+ * 这样"没有解释器的环境"（隔离冒烟、极简 PATH）会真的走到 fail-loud 分支，
+ * 而不是被某个恰好合格的系统解释器救活 —— 否则隔离用例会变成环境相关的假绿/假红。
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { delimiter, isAbsolute, join } from 'node:path'
+import { MIN_PYTHON, parseVersion, versionAtLeast } from '../../scripts/lib/python-runtime.mjs'
+
+/** 解释器必须能 import 的模块（硬要求，与 `scripts/flow-trigger.sh` 的 pick_py() 一致）。 */
+export const REQUIRED_MODULES = ['openpyxl', 'yaml']
+
+/** PATH 上按名探测的解释器（顺序即优先级）。 */
+export const PATH_NAMES = ['python3', 'python3.11']
+
+/** 探测失败的原因码 → 给人看的中文（诊断信息里逐条打印）。 */
+export const REASON_TEXT = {
+  not_found: '文件不存在',
+  not_executable: '不可执行',
+  start_failed: '启动失败',
+  version_unreadable: '版本读不出来',
+  version_too_old: '版本过低',
+  missing_modules: '缺依赖模块',
+  ok: '可用',
+}
+
+/** 真实探测（可注入，便于纯夹具测试）：跑一次解释器，返回状态与输出。 */
+export function realRun(bin, args) {
+  const r = spawnSync(bin, args, { encoding: 'utf8', timeout: 20000 })
+  return {
+    status: r.status,
+    out: `${r.stdout || ''}${r.stderr || ''}`.trim(),
+    spawnError: r.error ? String(r.error.code || r.error.message || 'error') : '',
+  }
+}
+
+/** PATH 里的候选（自己扫目录，**不** shell out 到 `which`：极简 PATH 下更可靠、零子进程）。 */
+export function pathCandidates({ env = process.env, names = PATH_NAMES, exists = existsSync } = {}) {
+  const out = []
+  for (const dir of String(env.PATH || '').split(delimiter)) {
+    if (!dir) continue
+    for (const n of names) {
+      const p = join(dir, n)
+      if (exists(p)) out.push({ path: p, source: `PATH:${n}` })
+    }
+  }
+  return out
+}
+
+/** 候选解释器（按优先级；同路径去重、保留首次出现的来源标签）。 */
+export function pythonCandidates({ env = process.env, dataDir = '', repo = '' } = {}) {
+  const raw = []
+  const push = (path, source) => { if (path) raw.push({ path: String(path), source }) }
+  push(env.ARGENT_PY, 'ARGENT_PY')
+  push(env.ARGENT_PYTHON, 'ARGENT_PYTHON')
+  if (dataDir) push(join(dataDir, 'venv', 'bin', 'python3'), 'venv(data_dir)')
+  if (repo) push(join(repo, '.venv', 'bin', 'python3'), 'venv(repo)')
+  raw.push(...pathCandidates({ env }))
+  const seen = new Set()
+  return raw.filter((c) => (seen.has(c.path) ? false : (seen.add(c.path), true)))
+}
+
+/**
+ * 探测一个候选：能启动 + 版本达标 + 依赖可 import。
+ * 返回 `{ ok, reason, detail, version }` —— 失败原因**分类**（"文件不存在"与"解析/依赖失败"不同）。
+ */
+export function probePython(bin, { run = realRun, min = MIN_PYTHON, requires = REQUIRED_MODULES, exists = existsSync } = {}) {
+  const p = String(bin || '')
+  if (!p) return { ok: false, reason: 'not_found', detail: '未指定' }
+  // 绝对/相对路径先看存在性：省一次 spawn，也让诊断更准（"不存在" ≠ "启动失败"）
+  if (isAbsolute(p) && !exists(p)) return { ok: false, reason: 'not_found', detail: p }
+
+  const v = run(p, ['-c', 'import sys; print("%d.%d.%d" % sys.version_info[:3])'])
+  if (v.spawnError) return { ok: false, reason: 'not_executable', detail: v.spawnError }
+  if (v.status !== 0) return { ok: false, reason: 'start_failed', detail: (v.out || `exit ${v.status}`).slice(0, 200) }
+  const version = parseVersion(v.out)
+  if (!version) return { ok: false, reason: 'version_unreadable', detail: v.out.slice(0, 120) }
+  if (!versionAtLeast(version, min)) {
+    return { ok: false, reason: 'version_too_old', detail: `${version.join('.')} < ${min.join('.')}`, version }
+  }
+  if ((requires || []).length) {
+    const m = run(p, ['-c', `import ${requires.join(', ')}`])
+    if (m.status !== 0) {
+      const last = (m.out || '').split('\n').filter(Boolean).pop() || `exit ${m.status}`
+      return { ok: false, reason: 'missing_modules', detail: `${requires.join('/')}：${last.slice(0, 160)}`, version }
+    }
+  }
+  return { ok: true, reason: 'ok', detail: '', version }
+}
+
+/** 全不可用时的诊断（给人/给 agent：候选、拒绝原因、修复指引）。 */
+export function pythonDiagnostics({ tried = [], min = MIN_PYTHON, requires = REQUIRED_MODULES, dataDir = '' } = {}) {
+  const lines = [
+    `找不到可用的 Python 解释器（要求 ≥ ${min.join('.')} 且能 import ${requires.join(', ')}）——已探测 ${tried.length} 个候选：`,
+  ]
+  for (const t of tried) {
+    const why = REASON_TEXT[t.reason] || t.reason
+    lines.push(`  · ${t.source}=${t.path}：${why}${t.detail ? `（${t.detail}）` : ''}`)
+  }
+  lines.push(`修复：① python3 -m venv ${dataDir ? `${dataDir}/venv` : '<数据目录>/venv'} && `
+    + `${dataDir ? `${dataDir}/venv` : '<数据目录>/venv'}/bin/pip install openpyxl pyyaml；`)
+  lines.push(`      ② 或显式指定：ARGENT_PY=/path/to/python3（须 ≥ ${min.join('.')} 且含 openpyxl + pyyaml）。`)
+  return lines.join('\n')
+}
+
+/**
+ * 按顺序探测，返回第一个可用者。
+ * @returns {{ok: boolean, path: string, source: string, version: number[]|null,
+ *            tried: Array<{path: string, source: string, ok: boolean, reason: string, detail: string}>,
+ *            diagnostics: string}}
+ */
+export function pickPython({ env = process.env, dataDir = '', repo = '',
+  candidates = null, run = realRun, min = MIN_PYTHON, requires = REQUIRED_MODULES } = {}) {
+  const list = candidates || pythonCandidates({ env, dataDir, repo })
+  const tried = []
+  for (const c of list) {
+    const p = probePython(c.path, { run, min, requires })
+    tried.push({ path: c.path, source: c.source, ok: p.ok, reason: p.reason, detail: p.detail, version: p.version || null })
+    if (p.ok) return { ok: true, path: c.path, source: c.source, version: p.version, tried, diagnostics: '' }
+  }
+  return {
+    ok: false, path: '', source: '', version: null, tried,
+    diagnostics: pythonDiagnostics({ tried, min, requires, dataDir }),
+  }
+}

package/engine/core/lib/sop.mjs

@@ -0,0 +1,116 @@
+/**
+ * SOP 解析（0.3 共享实现，2026-09-29；技能判据 2026-10-03 修 D2/D3）—— **CLI 与 MCP 用同一套**，
+ * 宿主不必知道文件布局。
+ *
+ * 提示词选择顺序（实测修正）：主提示词优先于失败/分支提示词 —— 曾因模糊匹配选中
+ * `daily-report.failure.md`（不是主提示词），会误导宿主。
+ *
+ * 技能目录（**D2**）：只认注册表声明 `flows.<id>.skill`（单一真源，须 ∈ 业务线 manifest#skills）。
+ * 此前用 **role** 拼路径（`~/.dsh/skills/<role>`）⇒ 文鳐流程报 `ml-invoice-wy`（角色名）而真实技能
+ * 目录是 `ml-invoice` ⇒ 宿主被明确告知"没有踩坑文档"，跳过最该读的知识（反向价值）。
+ * **没有声明就报错，绝不回退到 role**（角色名 ≠ 技能名，实测就是两个名字）。
+ *
+ * 失败口径（**D3**）：注册表读不到（脚本缺失 / 合并失败 / 解释器不可用）**不再空 catch 吞掉**，
+ * 而是分类后 `ok:false` + `code:2`（CLI 非零退出 + 诊断）—— 静默降级会把"解释器不在"伪装成
+ * "这台机器上没有流程"。
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { loadRegistry, resolveFlow } from './flow-registry.mjs'
+
+/** 数据目录无关的"没声明技能"错误文案（把该改哪一行说清楚）。 */
+function skillNotDeclaredError(canonical, vertical) {
+  const where = vertical ? `verticals/${vertical}/flows.json` : 'verticals/<业务线>/flows.json'
+  return `流程 ${canonical} 未声明技能：请在 ${where} 的该流程里加 "skill": "<技能名>"`
+    + '（须与 manifest.json#skills 一致，如 "ml-invoice"）—— 技能目录的单一真源是这条声明，'
+    + '不用角色名兜底（角色名与技能名是两个名字，实测 ml-invoice-wy ≠ ml-invoice）'
+}
+
+/**
+ * 解析某流程的 SOP（提示词 + 技能目录 + 踩坑清单）。
+ *
+ * @param {string} flow 流程 id 或别名（旧 id 经注册表别名解析）
+ * @param {{repo: string, py: string, pyFailure?: string|null}} opts
+ *   `py`：**已选定的**解释器（`core/lib/python.mjs#pickPython` 的结果）；
+ *   `pyFailure`：解释器解析失败的诊断文本（给了就直接响亮失败，不再尝试 exec）。
+ */
+export function resolveSop(flow, { repo, py, pyFailure = null } = {}) {
+  const flowInput = String(flow || 'full')
+  if (pyFailure) {
+    return { ok: false, code: 2, flow: flowInput, reason: 'python_unavailable', error: pyFailure }
+  }
+
+  const reg = loadRegistry({ repo, py })
+  if (!reg.ok) {
+    return { ok: false, code: 2, flow: flowInput, reason: reg.reason, error: reg.error }
+  }
+  const doc = reg.doc
+  const r = resolveFlow({ input: flowInput, doc })
+  if (!r.known) {
+    return {
+      ok: false, code: 2, flow: r.canonical, reason: 'unknown_flow',
+      error: `未知流程 \`${flowInput}\`（规范 id \`${r.canonical}\` 不在注册表里）；`
+        + '可用：python3 scripts/flow_registry.py --list',
+    }
+  }
+  const f = doc.flows[r.canonical] || {}
+  const key = r.canonical
+  const vertical = key.includes('.') ? key.split('.')[0] : ''
+  const cap = String(f.capability || '')
+
+  const dir = join(repo, 'verticals', vertical, 'prompts')
+  let names = []
+  try { names = readdirSync(dir) } catch { /* 该业务线还没有提示词目录 ⇒ 下面的 pick 全部未命中，走 availablePrompts */ }
+  // 匹配顺序（每个候选：<x>.md > <x>.*.md（排除 .failure）> <x>*）：
+  // 能力 → 流程局部 id → 角色。**找不到就明确未命中**（此前会回退成目录第一个文件，
+  // 实测把 `daily-report.failure.md` 当成了文鳐发票的 SOP —— 误导宿主，必须禁止）。
+  const pick = (x) => {
+    if (!x) return ''
+    return names.find((n) => n === `${x}.md`)
+      || names.find((n) => n.startsWith(`${x}.`) && n.endsWith('.md') && !n.includes('failure'))
+      || names.find((n) => n.startsWith(x))
+      || ''
+  }
+  const chosen = pick(cap) || pick(r.local) || pick(String(f.role || '')) || ''
+  const matchedBy = pick(cap) ? 'capability' : (pick(r.local) ? 'localId' : (pick(String(f.role || '')) ? 'role' : 'none'))
+  const promptPath = chosen ? join(dir, chosen) : ''
+  const promptTail = promptPath && existsSync(promptPath) ? readFileSync(promptPath, 'utf8').slice(-1200) : ''
+
+  // ── 技能目录（D2）：**只认声明** ─────────────────────────────────────────
+  const skill = String(f.skill || '')
+  if (!skill) {
+    return {
+      ok: false, code: 2, flow: key, role: String(f.role || ''), capability: cap, vertical,
+      reason: 'skill_not_declared', error: skillNotDeclaredError(key, vertical),
+    }
+  }
+  const home = process.env.HOME || ''
+  // 候选：① 已安装（宿主技能目录，agent 真正加载的那份）② 仓库 L0 源（没装宿主也要能给出判据）。
+  const skillCands = []
+  if (home) skillCands.push({ dir: join(home, '.dsh', 'skills', skill), source: 'installed' })
+  skillCands.push({ dir: join(repo, 'skills', skill), source: 'repo' })
+  const hasSkillMd = (c) => existsSync(join(c.dir, 'SKILL.md'))
+  const hit = skillCands.find(hasSkillMd) || skillCands.find((c) => existsSync(c.dir)) || null
+  const shown = (c) => (c.source === 'repo'
+    ? join('skills', skill)
+    : (home && c.dir.startsWith(home) ? `~${c.dir.slice(home.length)}` : c.dir))
+
+  return {
+    ok: true,
+    flow: key,
+    role: String(f.role || ''),
+    capability: cap,
+    vertical,
+    matchedBy,
+    availablePrompts: chosen ? undefined : names,
+    note: chosen ? undefined : 'no_prompt_for_capability：该能力在业务线 prompts 里没有对应提示词（未回退到无关文件）',
+    promptPath: promptPath.replace(`${repo}/`, ''),
+    promptTail,
+    skill,
+    skillDir: shown(hit || skillCands[0]),
+    skillDirSource: hit ? hit.source : null,
+    skillDirResolved: Boolean(hit),
+    skillDirCandidates: skillCands.map(shown),
+    pitfalls: hit ? existsSync(join(hit.dir, 'references', 'pitfalls.md')) : false,
+  }
+}

package/engine/core/lib/versions.mjs

@@ -0,0 +1,205 @@
+/**
+ * `argent versions` —— **版本对账**（P1；策划案⑮、M2 判据③：`versions` 对账无差异）。只读。
+ *
+ * 回答一个问题：**"这台机器上跑的到底是哪一版"** —— 一次把五个面摊开，且每一面都点名它的来源文件：
+ *
+ * | 面 | 来源（唯一真源） | 为什么是它 |
+ * |---|---|---|
+ * | `cli.argent` | 仓库 `VERSION` | 版本线的唯一出口（`scripts/tests/argent-contracts.test.mjs` 已钉住它与契约一致） |
+ * | `contracts` | `core/contracts/{argent.contracts.json,verbs.schema.json}` 的 `argentVersion` + sha256(12) | 宿主只依赖契约 ⇒ 契约的**逐字节身份**必须可核（"读到的契约是哪一份"） |
+ * | `kernel` | `core/**` 的 `路径:sha12` 排序后取 sha256（**整树指纹**） | 内核是"换个宿主也不变"的那层 ⇒ 它的身份 = 整棵树的摘要，而不是某个文件 |
+ * | `capabilities` | 注册表 `capabilities.<c>.pack.version`（走 `scripts/flow_registry.py`，**唯一真源**） | 能力包版本被 `scripts/capability_pack.py --validate` 与锁文件绑死 |
+ * | `patches` | `scripts/patches/*.patch` 的清单（**宿主档事实**） | 判断"补丁在不在位"是**宿主侧检查**的职责；本 verb 只如实列清单，缺 dsh/缺目录 **不算 FAIL** |
+ * | `host.dsh` | `dsh --version`（可选探测，有则报、无则空串） | 无宿主是**设计**（§4.2 M1 判据③） |
+ *
+ * ## A1/A2
+ *   · `0` 对账完成（**缺 dsh / 缺补丁目录都不算失败** —— 它们是事实）。
+ *   · `2` **解释器不可用** ⇒ `python_unavailable`：能力包版本读不到时**不能**给"没有差异"的假绿
+ *     （D3 的口径：不得静默 0）；此时 JSON 仍给出能读到的那几面。
+ *   · 回显实际生效的过滤条件（`--only`），空结果不可能与"没查"混淆。
+ *
+ * 纪律：本文件**不重新实现**任何合并/版本推导 —— 注册表走 `core/lib/flow-registry.mjs`，
+ * 解释器走 `core/lib/python.mjs`，数据目录走 `core/lib/argent-datadir.mjs`。
+ */
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import { resolveDataDir } from './argent-datadir.mjs'
+import { pickPython } from './python.mjs'
+import { loadRegistry } from './flow-registry.mjs'
+
+/** 参与对账的面（`--only` 的取值域）。 */
+export const VERSION_FACES = ['cli', 'contracts', 'kernel', 'capabilities', 'patches', 'host']
+
+const toPosix = (p) => p.split(sep).join('/')
+const sha12 = (buf) => createHash('sha256').update(buf).digest('hex').slice(0, 12)
+
+/** 递归列文件（跳过 `.DS_Store`；**不**跳过 `node_modules` 之外的任何东西 —— core/ 下不该有）。 */
+function walk(dir, base = dir, out = []) {
+  let entries = []
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return out }
+  for (const e of entries) {
+    if (e.name === '.DS_Store' || e.name === '.git') continue
+    const p = join(dir, e.name)
+    let st = null
+    try { st = statSync(p) } catch { continue }
+    if (st.isDirectory()) walk(p, base, out)
+    else if (st.isFile()) out.push(toPosix(relative(base, p)))
+  }
+  return out
+}
+
+/**
+ * 内核整树指纹：`路径:sha12` 排序后求 sha256（与 `capability_pack.py#pack_digest` 同形态）。
+ * 为什么不是"版本号"：`core/` 没有独立版本号，而它每天都在变 ⇒ 只有内容摘要能回答
+ * "客户机上的 core 与仓库那一份是不是同一棵"。
+ */
+export function kernelFingerprint(repo) {
+  const dir = join(repo, 'core')
+  if (!existsSync(dir)) return { ok: false, reason: 'core_missing', files: 0, digest: null, note: `仓库缺 core/：${dir}` }
+  const files = walk(dir).sort()
+  const lines = files.map((rel) => `${rel}:${sha12(readFileSync(join(dir, rel)))}`)
+  return {
+    ok: true, files: files.length,
+    digest: createHash('sha256').update(lines.join('\n')).digest('hex'),
+    digestShort: createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 16),
+    cliEntry: files.includes('cli/argent.mjs'),
+    mcpEntry: files.includes('mcp/server.mjs'),
+  }
+}
+
+/** 契约面：版本号 + 两份契约文件的 sha12（"读到的契约是哪一份"）。 */
+export function contractsProfile(repo) {
+  const out = { dir: 'core/contracts', argentVersion: null, files: {}, ok: false, error: null }
+  for (const f of ['argent.contracts.json', 'verbs.schema.json']) {
+    const p = join(repo, 'core', 'contracts', f)
+    if (!existsSync(p)) { out.error = `契约文件缺失：core/contracts/${f}`; continue }
+    const buf = readFileSync(p)
+    out.files[f] = { bytes: buf.length, sha256_12: sha12(buf) }
+    if (f === 'argent.contracts.json') {
+      try { out.argentVersion = JSON.parse(buf.toString('utf8')).argentVersion || null } catch (e) { out.error = `argent.contracts.json 不可解析：${e.message}` }
+    }
+  }
+  out.ok = out.error === null && Object.keys(out.files).length === 2
+  return out
+}
+
+/** CLI 面：仓库 `VERSION`。 */
+export function cliProfile(repo) {
+  const p = join(repo, 'VERSION')
+  if (!existsSync(p)) return { argent: null, file: 'VERSION', error: '缺 VERSION 文件（仓库不完整）' }
+  return { argent: readFileSync(p, 'utf8').trim(), file: 'VERSION' }
+}
+
+/** 宿主补丁面（**只列清单**；在不在位由宿主侧检查判）。 */
+export function patchesProfile(repo) {
+  const dir = join(repo, 'scripts', 'patches')
+  if (!existsSync(dir)) return { dir: 'scripts/patches', present: false, count: 0, patches: [], note: '缺补丁目录（非 dsh 交付形态？）—— 缺它**不算 FAIL**' }
+  const patches = readdirSync(dir).filter((f) => f.endsWith('.patch')).sort()
+  const verifiers = readdirSync(dir).filter((f) => /^verify-.*\.mjs$/.test(f)).sort()
+  return {
+    dir: 'scripts/patches', present: true, count: patches.length, patches, verifiers,
+    note: '**宿主档事实**：本 verb 只列清单；"补丁在不在位"的权威判据在宿主侧检查'
+      + '（`node scripts/dsh-upgrade.mjs --patches-only`），本 verb 不重算。',
+  }
+}
+
+/** 能力包面（走注册表 = 唯一真源；解释器不可用 ⇒ 如实标 unavailable）。 */
+export function capabilitiesProfile({ repo, py, pyFailure }) {
+  if (pyFailure || !py) return { ok: false, reason: 'python_unavailable', error: pyFailure || '解释器不可用', capabilities: {} }
+  const reg = loadRegistry({ repo, py })
+  if (!reg.ok) return { ok: false, reason: reg.reason, error: reg.error, capabilities: {} }
+  const caps = (reg.doc && reg.doc.capabilities) || {}
+  const out = {}
+  for (const [id, c] of Object.entries(caps)) {
+    if (id.startsWith('_')) continue
+    out[id] = { version: (c.pack && c.pack.version) || null, minPlan: c.minPlan || null, files: (c.pack && c.pack.scripts ? c.pack.scripts.length : 0) }
+  }
+  return { ok: true, reason: null, error: null, capabilities: out, source: 'scripts/flow_registry.py（合并后）' }
+}
+
+/**
+ * verb 入口：`argent versions [--only <face>]… [--json]`。
+ * @param {string[]} argv
+ * @param {{repo?:string, env?:object, deps?:object}} [deps]
+ */
+export function runVersionsVerb(argv = [], deps = {}) {
+  const only = []
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i]
+    if (t === '--json') continue
+    if (t === '--only') {
+      const v = argv[i + 1]
+      if (v === undefined || String(v).startsWith('--')) return versionsFail(2, 'usage_error', '--only 缺值')
+      if (!VERSION_FACES.includes(v)) return versionsFail(2, 'usage_error', `--only 取值非法：${v}（可用：${VERSION_FACES.join('、')}）`)
+      only.push(v); i++
+      continue
+    }
+    if (t === '--help' || t === '-h') return { json: { ok: true, empty: false, code: 0, reason: null, verb: 'versions', usage: VERSIONS_USAGE }, human: VERSIONS_USAGE, stderr: '', exit: 0 }
+    return versionsFail(2, 'usage_error', `未知参数：${t}（用法：argent versions [--only <${VERSION_FACES.join('|')}>]… [--json]）`)
+  }
+  const env = deps.env || process.env
+  const repo = deps.repo || ''
+  const wanted = only.length ? only : VERSION_FACES
+  const has = (f) => wanted.includes(f)
+
+  const dataDir = resolveDataDir({ env })
+  const pyProbe = (has('capabilities') ? pickPython({ env, dataDir: dataDir.dir, repo }) : { ok: false, path: '', diagnostics: '未请求该面（--only）' })
+  const caps = has('capabilities') ? capabilitiesProfile({ repo, py: pyProbe.ok ? pyProbe.path : '', pyFailure: pyProbe.ok ? null : pyProbe.diagnostics }) : null
+
+  const json = {
+    ok: true, empty: false, code: 0, reason: null, verb: 'versions',
+    only: only.length ? only : null,
+    dataDir: { dir: dataDir.dir, source: dataDir.source, isolated: dataDir.isolated },
+    cli: has('cli') ? cliProfile(repo) : null,
+    contracts: has('contracts') ? contractsProfile(repo) : null,
+    kernel: has('kernel') ? kernelFingerprint(repo) : null,
+    capabilities: caps,
+    patches: has('patches') ? patchesProfile(repo) : null,
+    host: has('host') ? {
+      dsh: deps.dshVersion !== undefined ? deps.dshVersion : probeDsh(),
+      note: '缺 dsh = 设计（陪跑式档位），不是 FAIL',
+    } : null,
+    interpreter: { ok: pyProbe.ok, path: pyProbe.ok ? pyProbe.path : null, version: pyProbe.version || null },
+    note: '只读对账：每一面都点名来源文件；"补丁在不在位"与"定时器在不在册"是宿主档事实，权威判据在宿主侧检查。',
+  }
+  // A1：能力包版本读不到 ⇒ **不得**给"没有差异"的假绿（但保留已能读到的面）
+  if (caps && !caps.ok) {
+    json.ok = false
+    json.code = 2
+    json.reason = caps.reason === 'python_unavailable' ? 'python_unavailable' : (caps.reason || 'internal_error')
+    json.error = `能力包版本读不到：${caps.error}`
+    json.note = '解释器/注册表不可用 ⇒ 能力包面**未对账**（这不是"无差异"，是"没查成"）；其余面照常给出。'
+  }
+  const human = [
+    `🧾 Argent 版本对账（${json.ok ? '完成' : `未完成：${json.reason}`}）`,
+    json.cli ? `   CLI        ${json.cli.argent || '(缺 VERSION)'}` : null,
+    json.contracts ? `   契约       argentVersion=${json.contracts.argentVersion} ｜ ${Object.entries(json.contracts.files).map(([f, v]) => `${f} sha256:${v.sha256_12}`).join(' ｜ ')}` : null,
+    json.kernel ? `   内核       core/ ${json.kernel.files} 文件 ｜ 整树 sha256:${json.kernel.digestShort || '—'}` : null,
+    json.capabilities ? `   能力包     ${Object.entries(json.capabilities.capabilities).map(([k, v]) => `${k}@${v.version}`).join(' ｜ ') || `（未对账：${json.capabilities.error}）`}` : null,
+    json.patches ? `   宿主补丁   ${json.patches.count} 个${json.patches.present ? '' : '（缺目录）'}（只列清单；在不在位由宿主侧检查判）` : null,
+    json.host ? `   宿主       dsh=${json.host.dsh || '（不在 PATH）'}` : null,
+    `   数据目录   ${json.dataDir.dir}（来源=${json.dataDir.source}${json.dataDir.isolated ? '，隔离' : ''}）`,
+    json.error ? `   ❌ ${json.error}` : null,
+  ].filter(Boolean).join('\n')
+  return { json, human, stderr: '', exit: Number(json.code) }
+}
+
+/** `dsh --version`（可选探测；宿主缺失 ⇒ 空串而非报错，§P1 验收判据）。 */
+export function probeDsh() {
+  // 与 `core/cli/argent.mjs#version` 同口径的**可选**探测：有则报、无则空串（裸 `dsh` 不算宿主依赖）
+  try { return String(execFileSync('dsh', ['--version'], { encoding: 'utf8', timeout: 15000 })).trim() } catch { return '' }
+}
+
+function versionsFail(code, reason, error, echo = {}) {
+  return { json: { ok: false, empty: false, code, reason, error, verb: 'versions', ...echo }, human: `❌ ${reason}：${error}`, stderr: '', exit: code }
+}
+
+export const VERSIONS_USAGE = [
+  '用法：argent versions [--only <face>]… [--json]',
+  `面：${VERSION_FACES.join('、')}`,
+  '',
+  '只读对账：CLI(VERSION) / 契约(版本号+sha) / 内核(core 整树 sha) / 能力包版本 / 宿主补丁清单 / 宿主版本。',
+  '⛔ 缺 dsh 或缺补丁目录**不算 FAIL**；解释器不可用 ⇒ exit 2 + python_unavailable（能力包面未对账，不是"无差异"）。',
+].join('\n')