@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/core/lib/flow-list.mjs

@@ -0,0 +1,138 @@
+/**
+ * `argent flow list` —— **注册表只读清单**（P1，2026-10-03）。
+ *
+ * 薄包：全部内容来自 `scripts/flow_registry.py --json`（**唯一真源**：引擎级 base + 各业务线的
+ * 合并/冲突检查/别名解析都由它做），本文件**不实现任何合并**，只做三件事：
+ *   ① 用**已选定的解释器**去调它（`core/lib/python.mjs`，D3：不赌 PATH）；
+ *   ② 把合并结果整理成宿主好用的形状（流程 → 业务线/能力/角色/技能/数据面/触发器）；
+ *   ③ **如实回显**：读不到注册表 ⇒ `2 + python_unavailable|missing_declaration`，**绝不**报"没有流程"。
+ *
+ * ## 暂停开关：只做**存在性探测**，不重算路径
+ * 每条流程的 `trigger.pauseSwitch`（相对数据目录）与 `pauseSwitchLegacy`（数据目录根下的裸名）
+ * 都是**注册表声明**；本 verb 只在声明的路径上探一次"在不在"。⚠️ 权威判据仍是
+ * `scripts/flow_config.py` / `scripts/flow-trigger.sh`（迁移期两条都查）—— 输出里用
+ * `authoritative` 字段点名，免得被当成第二份判据。
+ *
+ * ## A1/A2
+ *   · `0` 读到（流程 0 条 ⇒ `empty:true + no_match`，不是错误）；
+ *   · `2` 解释器不可用 / 注册表读不到 / 未知参数。
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveDataDir } from './argent-datadir.mjs'
+import { pickPython } from './python.mjs'
+import { loadRegistry, resolveFlow } from './flow-registry.mjs'
+
+/** 注册表文档 → 宿主友好的流程清单（纯函数，便于夹具）。 */
+export function summarizeFlows(doc, { dataDir = '', exists = existsSync } = {}) {
+  const flows = (doc && doc.flows) || {}
+  const aliases = (doc && doc.aliases) || {}
+  const aliasTo = {}
+  for (const [from, to] of Object.entries(aliases)) (aliasTo[to] ||= []).push(from)
+  const verticals = {}
+  const rows = []
+  for (const [id, f] of Object.entries(flows)) {
+    const vertical = id.includes('.') ? id.split('.')[0] : null
+    const local = id.includes('.') ? id.split('.').slice(1).join('.') : id
+    const t = f.trigger || {}
+    const declared = t.pauseSwitch ? join(String(dataDir), String(t.pauseSwitch)) : null
+    const legacy = t.pauseSwitchLegacy ? join(String(dataDir), String(t.pauseSwitchLegacy)) : null
+    const paused = Boolean((declared && exists(declared)) || (legacy && exists(legacy)))
+    rows.push({
+      id, localId: local, vertical,
+      title: f.title || null,
+      role: f.role || null,
+      capability: f.capability || null,
+      skill: f.skill || null,
+      sourceKind: (f.source && f.source.kind) || null,
+      sourceIdentity: (f.source && f.source.identity) || null,
+      trigger: {
+        wake: t.wake ?? null, mode: t.mode ?? null, intervalSec: t.intervalSec ?? null,
+        pauseSwitch: t.pauseSwitch ?? null, pauseSwitchLegacy: t.pauseSwitchLegacy ?? null,
+        promptTemplate: t.promptTemplate ?? null,
+        log: t.log ?? null,
+      },
+      pause: {
+        paused, declaredPath: declared, declaredExists: Boolean(declared && exists(declared)),
+        legacyPath: legacy, legacyExists: Boolean(legacy && exists(legacy)),
+        authoritative: 'scripts/flow_config.py / scripts/flow-trigger.sh（本 verb 只在注册表声明的路径上探存在性，不重算路径）',
+      },
+      concurrency: f.concurrency || null,
+      guards: f.guards || null,
+      failuresEnabled: Boolean(f.failures && f.failures.enabled),
+      aliases: aliasTo[id] || [],
+      requiredFields: Array.isArray(f.required) ? f.required.length : 0,
+    })
+    if (vertical) verticals[vertical] = true
+  }
+  rows.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  return { rows, verticalIds: Object.keys(verticals).sort(), aliases }
+}
+
+/**
+ * verb 入口：`argent flow list [--json]`。
+ * @param {string[]} argv 子命令之后的参数（`list` 已由组 verb 消费）
+ * @param {{repo?:string, env?:object, py?:string, pyFailure?:string|null, doc?:object}} [deps]
+ */
+export function runFlowListVerb(argv = [], deps = {}) {
+  for (const t of argv) {
+    if (t === '--json') continue
+    if (t === '--help' || t === '-h') return { json: { ok: true, empty: false, code: 0, reason: null, verb: 'flow', subcommand: 'list', usage: FLOW_LIST_USAGE }, human: FLOW_LIST_USAGE, stderr: '', exit: 0 }
+    if (t.startsWith('--')) return listFail(2, 'usage_error', `未知参数：${t}（用法：argent flow list [--json]）`)
+    return listFail(2, 'usage_error', `多余的位置参数：${t}（用法：argent flow list [--json]）`)
+  }
+  const repo = deps.repo || ''
+  const env = deps.env || process.env
+  const dataDir = deps.dataDir || resolveDataDir({ env }).dir
+  // 解释器：显式给了就用（夹具/已解析），否则探一次；探不到 ⇒ 下面的 loadRegistry 会走 py='' 并响亮失败
+  let py = deps.py !== undefined ? deps.py : null
+  let pyFailure = deps.pyFailure !== undefined ? deps.pyFailure : null
+  if (deps.doc === undefined && py === null) {
+    const p = pickPython({ env, dataDir, repo })
+    py = p.ok ? p.path : ''
+    pyFailure = p.ok ? null : p.diagnostics
+  }
+
+  let doc = deps.doc || null
+  if (!doc) {
+    if (pyFailure) return listFail(2, 'python_unavailable', pyFailure, { dataDir })
+    const reg = loadRegistry({ repo, py })
+    if (!reg.ok) {
+      return listFail(2, reg.reason === 'registry_script_missing' ? 'missing_declaration' : 'python_unavailable', reg.error, { dataDir })
+    }
+    doc = reg.doc
+  }
+  const { rows, verticalIds, aliases } = summarizeFlows(doc, { dataDir })
+  const json = {
+    ok: true, empty: rows.length === 0, code: 0, reason: rows.length ? null : 'no_match', verb: 'flow', subcommand: 'list',
+    source: 'scripts/flow_registry.py --json（合并 + 别名解析的唯一真源）',
+    dataDir,
+    count: rows.length,
+    verticals: verticalIds,
+    aliases,
+    flows: rows,
+    note: 'pause 只在注册表声明的路径上做存在性探测（权威判据见 pause.authoritative）；'
+      + 'guards/concurrency 为注册表原文照录，判据仍在引擎脚本里。',
+  }
+  const human = [
+    `📋 流程清单（${rows.length} 条 ｜ 业务线 ${verticalIds.join('、') || '（无）'}）`,
+    ...rows.map((r) => `   · ${r.id.padEnd(34)} ${(r.title || '').padEnd(18)} 角色=${r.role || '—'} 能力=${r.capability || '—'}`
+      + ` 唤醒=${r.trigger.wake || '—'}${r.pause.paused ? ' ⏸ 已暂停开关' : ''}`),
+    rows.length ? null : '   （注册表里 0 条流程 —— 这不是错误，但要确认注册表是否读对了）',
+  ].filter(Boolean).join('\n')
+  return { json, human, stderr: '', exit: 0 }
+}
+
+function listFail(code, reason, error, echo = {}) {
+  return { json: { ok: false, empty: false, code, reason, error, verb: 'flow', subcommand: 'list', ...echo }, human: `❌ ${reason}：${error}`, stderr: '', exit: code }
+}
+
+/** 供组 verb 复用：别名解析（不复制 `resolveFlow` 的实现）。 */
+export { resolveFlow }
+
+export const FLOW_LIST_USAGE = [
+  '用法：argent flow list [--json]',
+  '',
+  '只读清单：流程（规范 id / 标题 / 角色 / 能力 / 技能 / 数据面 / 触发器 / 并发 / 守卫 / 别名）。',
+  '真源 = scripts/flow_registry.py --json（本 verb 不实现合并）；暂停开关只做存在性探测。',
+].join('\n')

package/engine/core/lib/flow-registry.mjs

@@ -0,0 +1,48 @@
+/**
+ * 注册表读取（core 侧薄包装）—— **唯一真源仍是 `scripts/flow_registry.py`**
+ * （base + 业务线的合并、冲突即 fail、别名解析都由它做；Node 侧入口 `scripts/lib/registry.mjs`）。
+ *
+ * 本模块只加两件内核需要的事，**不复制任何合并逻辑**：
+ *   ① 用**已选定的解释器**去调它（不赌 PATH 上恰好有 python3）；
+ *   ② 把失败**分类**（脚本缺失 / 合并或解析失败）—— 2026-10-03 修 D3：此前 `core/lib/sop.mjs`
+ *      用空 `catch {}` 吞掉一切失败 ⇒ 注册表读不到时 `sop` 报"未命中"且 exit 0（假象）。
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { loadRegistryDoc, resolveFlowId } from '../../scripts/lib/registry.mjs'
+
+/**
+ * 读合并后的注册表（永不抛）。
+ * @returns {{ok: true, doc: object} | {ok: false, reason: string, error: string}}
+ *   reason：`registry_script_missing`（仓库不完整）/ `registry_failed`（合并或解析失败）
+ */
+export function loadRegistry({ repo, py }) {
+  const script = join(repo, 'scripts', 'flow_registry.py')
+  if (!existsSync(script)) {
+    return { ok: false, reason: 'registry_script_missing', error: `注册表加载器不存在：${script}（仓库不完整？）` }
+  }
+  try {
+    return { ok: true, doc: loadRegistryDoc({ root: repo, py }) }
+  } catch (e) {
+    const stderr = String((e && e.stderr) || '').trim()
+    const tail = stderr.split('\n').map((l) => l.trim()).filter(Boolean).slice(-3).join(' / ')
+    return {
+      ok: false,
+      reason: 'registry_failed',
+      error: `注册表合并/解析失败：${(tail || String((e && e.message) || e)).slice(0, 400)}`,
+    }
+  }
+}
+
+/**
+ * 别名 → 规范 id，并给出**局部 id**（台账 caseId 的前缀约定是 `<flow>__<票号>`，用的是局部 id）。
+ * 别名解析走 `resolveFlowId`（加载器的唯一实现），本函数不自己维护任何映射。
+ */
+export function resolveFlow({ input, doc }) {
+  const raw = String(input || '')
+  const canonical = resolveFlowId(raw, doc)
+  const flows = (doc && doc.flows) || {}
+  const known = Object.prototype.hasOwnProperty.call(flows, canonical)
+  const local = canonical.includes('.') ? canonical.split('.').slice(1).join('.') : canonical
+  return { input: raw, canonical, local, known }
+}

package/engine/core/lib/init.mjs

@@ -0,0 +1,247 @@
+/**
+ * `argent init` —— **数据目录画像**（P1，2026-10-03）。
+ *
+ * 客户 agent 装完 CLI 后的第一个问题永远是"我该写哪儿、我这台机器现在能跑什么"。
+ * 本 verb 把这件事**一次答完**，且**只读**（除 `--apply` 建目录那一步）。
+ *
+ * ## 它答什么（每一项都指向唯一判据，本文件不复制判据）
+ * | 画像块 | 唯一判据 |
+ * |---|---|
+ * | 数据目录（含来源/是否隔离/存在性/可写性） | `core/lib/argent-datadir.mjs#resolveDataDir`（判断⑧） |
+ * | 解释器候选 | `core/lib/python.mjs#pickPython`（D3 的多候选 + 响亮失败，与 `flow-trigger.sh` 的 `pick_py()` 同源） |
+ * | 已装技能 | 技能根的**存在性计数**（`<数据目录>/skills`、`<dsh home>/skills`、仓库 `skills/`）；格式判据在 `scripts/fix-skill-frontmatter.py` |
+ * | 许可状态 | `core/lib/license-verdict.mjs#licenseVerdict`（判定点唯一在 CLI 进程内，§3.5①） |
+ * | 通道可用性 | `core/lib/notify/index.mjs#listChannels`（P2 端口；预留位如实标 `implemented:false`） |
+ * | 宿主档事实（dsh 在不在 / 定时器 / 补丁） | **只探测、如实上报**；缺宿主是**设计**不是 FAIL（§4.2 M1 判据③） |
+ *
+ * ## A1/A2/A3
+ *   · A1：`0` 画像成功（**缺 dsh / 缺解释器 / 无许可都不算失败** —— 它们是"事实"，画像的职责是如实报出来）；
+ *     `2` 用法错误（未知参数 / `--apply` 时目录建不出来 `${datadir_unwritable}`）。
+ *   · A2：`ok/empty/code/reason` 恒在；回显**实际生效**的数据目录、来源、以及 `--apply` 的 `applied`。
+ *   · A3：**默认 dry-run**（只画像，**不建目录**）；`--apply` 才 `mkdir -p`。dry-run 零副作用。
+ *
+ * ## ⛔ 它绝不做什么（写进代码与输出，两头都声明）
+ *   ① 不写 `~/.dsh/settings.yaml`（宿主配置归宿主；改它会让 dsh 自身 schema 重写时丢段）；
+ *   ② 不写/不碰 credentials（`~/.dsh/.credentials.yaml`）；
+ *   ③ **不发明数据目录** —— 只落 `resolveDataDir()` 给出的那一个（另建目录 = 第二份判据，
+ *      那正是 `core/lib/argent-datadir.mjs:1-23` 记录过的事故形态：隔离实例写进生产）。
+ *
+ * ## 默认目录已定（真源在 `core/lib/argent-datadir.mjs`，本文件只**如实呈现**）
+ * 实施方案 §P1③ / §6.2 **Q6 选项 B**（2026-10-03 批准、**已落地（两步）**）：
+ *   · **存在即沿用**：`~/.dsh/argent` 已存在 ⇒ 它就是默认目录（老机器**不**被误判隔离）；
+ *   · 否则（新装、无宿主）⇒ `~/.argent`。
+ * 本 verb 把两个候选路径 + 谁在用 + 老位置在不在**一次打全**（`dataDir.legacyDir` /
+ * `legacyDirExists` / `noHostDefault`）—— 因为判据是"老位置在不在"，所以**先在 `~/.argent`
+ * 落过数据、之后才出现 `~/.dsh/argent`** 的机器会切回老位置（可能读到空台账）；
+ * 要钉死目录就用 `ARGENT_DATA_DIR`（或 `DSH_HOME`）显式指定。判据**不在这里**，只在核心里。
+ */
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { NO_HOST_DATA_DIR_SEGMENTS, defaultDataDir, describeDataDir, dshHomeOf, legacyDataDir, legacyDataDirExists, osHome, resolveDataDir } from './argent-datadir.mjs'
+import { pickPython } from './python.mjs'
+import { licenseVerdict } from './license-verdict.mjs'
+import { listChannels } from './notify/index.mjs'
+
+/** 可写性探测：dry-run **不建目录**，所以用"最近的已存在祖先"判断（只读）。 */
+function nearestExisting(dir) {
+  let cur = String(dir)
+  const seen = []
+  while (cur && cur !== '/' && !existsSync(cur)) { seen.push(cur); cur = join(cur, '..') }
+  return { ancestor: existsSync(cur) ? cur : null, missing: seen.length }
+}
+
+/** 一个技能根画像（存在性 + 直接子目录里带 SKILL.md 的计数）。 */
+export function skillRootProfile(dir) {
+  const out = { dir, exists: false, skills: [], count: 0, skipped: [] }
+  if (!existsSync(dir)) return out
+  out.exists = true
+  let entries = []
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return out }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue
+    const has = existsSync(join(dir, e.name, 'SKILL.md'))
+    if (has) out.skills.push(e.name)
+    else out.skipped.push(e.name)
+  }
+  out.skills.sort()
+  out.count = out.skills.length
+  return out
+}
+
+/** 许可画像（**不复制判据**：调 licenseVerdict；它自己读 `$ARGENT_DATA_DIR/license.json`）。 */
+export function licenseProfile({ env = process.env, now = Date.now(), verdict = null } = {}) {
+  const v = verdict || licenseVerdict({ env, now })
+  return {
+    state: v.state, exit: v.exit, reason: v.reason || null,
+    file: v.path || null, exists: Boolean(v.path && existsSync(v.path)),
+    expiresAt: v.expiresAt || null, graceDays: v.graceDays ?? null, graceUntil: v.graceUntil || null,
+    allowed: v.allowed ?? null,
+    device: v.device ? { present: v.device.present, signed: v.device.signed, state: v.device.state, rebindsLeft: v.device.rebindsLeft ?? null } : null,
+    note: v.state === 'denied' ? '许可被拒 ⇒ 写类 verb 在 enforce 下会被拦（默认 observe 只留证据）' : null,
+  }
+}
+
+/**
+ * 数据目录画像（含三级链逐级的命中情况）。
+ * @returns {object} 形状与 `resolveDataDir()` 同源 + 画像字段
+ */
+export function dataDirProfile({ env = process.env, home = null } = {}) {
+  const r = resolveDataDir(home ? { env, home } : { env })
+  const noHostDefault = defaultDataDir(env, home || undefined)
+  const legacyDir = legacyDataDir(env, home || undefined)
+  const legacyExists = legacyDataDirExists(env, home || undefined)
+  const newInstallDir = join(osHome(env), ...NO_HOST_DATA_DIR_SEGMENTS)
+  const probe = nearestExisting(r.dir)
+  return {
+    dir: r.dir,
+    raw: r.raw,
+    source: r.source,
+    isolated: r.isolated,
+    defaultDir: r.defaultDir,
+    dshHome: r.dshHome,
+    exists: existsSync(r.dir),
+    isDirectory: existsSync(r.dir) && statSync(r.dir).isDirectory(),
+    nearestExistingAncestor: probe.ancestor,
+    missingLevels: probe.missing,
+    // 默认目录的两个候选（判据 = "老位置在不在"，真源在 core/lib/argent-datadir.mjs）
+    noHostDefault,
+    noHostDefaultExists: existsSync(noHostDefault),
+    legacyDir,
+    legacyDirExists: legacyExists,
+    newInstallDir,
+    chain: [
+      { level: 'ARGENT_DATA_DIR', hit: r.source === 'ARGENT_DATA_DIR', value: env.ARGENT_DATA_DIR ?? null },
+      { level: 'DSH_HOME', hit: r.source === 'DSH_HOME', value: env.DSH_HOME ? join(dshHomeOf(env), 'argent') : null },
+      { level: 'default', hit: r.source === 'default', value: r.defaultDir },
+    ],
+    // Q6 已定（选项 B，两步都落地）⇒ 不再是"待拍板"，但把两个候选与"谁在用"如实打出来
+    defaultDirDecision: {
+      id: 'Q6',
+      option: 'B',
+      landed: true,
+      rule: '存在即沿用：`~/.dsh/argent` 已存在 ⇒ 默认就是它；否则新装默认 `~/.argent`',
+      using: legacyExists ? 'legacy' : 'new-install',
+      legacyDir,
+      legacyDirExists: legacyExists,
+      newInstallDir,
+      note: legacyExists
+        ? '老位置存在 ⇒ 沿用（老机器不会被误判隔离；失败回路照常运行）'
+        : '老位置不存在 ⇒ 走新装默认 `~/.argent`（宿主无关位置）',
+      hazard: '判据是"老位置在不在" ⇒ 先在 `~/.argent` 落过数据、之后才出现 `~/.dsh/argent` 的机器会切回老位置（可能读到空台账）；'
+        + '要钉死目录用 ARGENT_DATA_DIR / DSH_HOME 显式指定',
+    },
+    describe: describeDataDir(r),
+  }
+}
+
+/** 宿主档事实（只探测；缺宿主 = 设计，不是 FAIL）。 */
+export function hostProfile({ env = process.env, repo = '', which = null } = {}) {
+  const dshHome = dshHomeOf(env)
+  const dshBin = which ? which('dsh') : null
+  return {
+    dshHome,
+    dshHomeExists: existsSync(dshHome),
+    dshBin: dshBin || null,
+    note: '宿主档事实：缺 dsh **不是 FAIL**（M1 的判据③明写"无 dsh 不报 FAIL"）；'
+      + '定时器/补丁的权威判据在宿主侧生成器（`bash scripts/flow-timers.sh status`、`node scripts/dsh-upgrade.mjs --patches-only`），本 verb 不重算。',
+  }
+}
+
+/**
+ * verb 入口：`argent init [--apply] [--json]`。
+ * @param {string[]} argv
+ * @param {{repo?:string, env?:object, apply?:boolean, deps?:object}} [deps]
+ */
+export function runInitVerb(argv = [], deps = {}) {
+  const bool = []
+  for (const t of argv) {
+    if (t === '--json') continue
+    if (t === '--apply' || t === '--dry-run' || t === '--help' || t === '-h') { bool.push(t); continue }
+    return initFail(2, 'usage_error', `未知参数：${t}（用法：argent init [--apply] [--json]）`)
+  }
+  if (bool.includes('--help') || bool.includes('-h')) {
+    return { json: { ok: true, empty: false, code: 0, reason: null, verb: 'init', usage: INIT_USAGE }, human: INIT_USAGE, stderr: '', exit: 0 }
+  }
+  const apply = bool.includes('--apply') && !bool.includes('--dry-run')
+  const env = deps.env || process.env
+  const repo = deps.repo || ''
+  const dryRun = !apply
+
+  const dd = dataDirProfile({ env })
+  const py = pickPython({ env, dataDir: dd.dir, repo })
+  const lic = licenseProfile({ env, now: deps.now ? deps.now.getTime() : Date.now(), verdict: deps.verdict || null })
+  const channels = listChannels()
+  const host = hostProfile({ env, repo, which: deps.which || null })
+
+  const roots = [
+    { id: 'data', dir: join(dd.dir, 'skills') },
+    { id: 'dsh', dir: join(dd.dshHome, 'skills') },
+    ...(repo ? [{ id: 'repo', dir: join(repo, 'skills') }] : []),
+  ].map((r) => ({ id: r.id, ...skillRootProfile(r.dir) }))
+
+  let applied = false
+  let created = false
+  let writeError = null
+  if (apply) {
+    try {
+      const existed = existsSync(dd.dir)
+      mkdirSync(dd.dir, { recursive: true })
+      applied = true
+      created = !existed
+    } catch (e) {
+      return initFail(2, 'datadir_unwritable', `数据目录建不出来：${dd.dir}（${(e && e.message) || e}）`, { dataDir: dd.dir, dryRun })
+    }
+  }
+
+  const json = {
+    ok: true, empty: false, code: 0, reason: null, verb: 'init',
+    dryRun, applied, created,
+    dataDir: { ...dd, existsAfter: existsSync(dd.dir), wouldCreate: !existsSync(dd.dir) },
+    interpreter: {
+      ok: py.ok, path: py.ok ? py.path : null, source: py.source || null, version: py.version || null,
+      candidates: (py.tried || []).map((t) => ({ path: t.path, source: t.source, ok: t.ok, reason: t.reason, version: t.version || null })),
+      diagnostics: py.ok ? null : py.diagnostics,
+    },
+    skills: { roots, total: roots.reduce((n, r) => n + r.count, 0) },
+    license: lic,
+    channels: { available: channels.filter((c) => c.implemented).map((c) => c.channel), reserved: channels.filter((c) => !c.implemented).map((c) => c.channel), all: channels },
+    host,
+    // 如实声明"没写什么"（不是客套：这三条是本次交付的红线，写进输出才可被调用方核验）
+    writes: {
+      settings: false, credentials: false, files: created ? [dd.dir] : [],
+      note: '本 verb 只创建数据目录本身（--apply 时）；**不写** ~/.dsh/settings.yaml、**不碰** credentials、不改任何宿主配置。',
+    },
+    // Q6（默认目录）**已定并落地**：不再是"待拍板"，把判据与两个候选如实打出来（真源在核心里）
+    defaultDirDecision: dd.defaultDirDecision,
+    pendingDecisions: [],
+    writeError,
+    note: dryRun ? 'dry-run（默认）：只画像，**未创建任何目录**；要建目录加 --apply' : `已 --apply：数据目录 ${created ? '新建' : '已存在'}（${dd.dir}）`,
+  }
+  const human = [
+    `📇 Argent 画像（${dryRun ? 'dry-run，未建目录' : '已 --apply'}）`,
+    `   数据目录：${dd.describe}`,
+    `             存在=${dd.existsAfter ?? dd.exists} 来源=${dd.source} 隔离=${dd.isolated} 默认=${dd.defaultDir}`,
+    `   默认目录判据（§6.2 Q6 选项 B，已落地）：老位置 ${dd.legacyDir} ${dd.legacyDirExists ? '**在**⇒沿用' : '不在⇒新装用 ' + dd.newInstallDir}`
+      + `（${dd.defaultDirDecision.using}）`,
+    `   解释器：${py.ok ? `${py.path}（${(py.version || []).join('.')}，来源 ${py.source}）` : '❌ 不可用'}`,
+    py.ok ? null : (py.diagnostics || '').split('\n').map((l) => `      ${l}`).join('\n'),
+    `   技能：${roots.map((r) => `${r.id}=${r.count}${r.exists ? '' : '(缺)'}`).join(' ')}`,
+    `   许可：${lic.state}（${lic.reason || 'ok'}）${lic.expiresAt ? ` 到期 ${lic.expiresAt}` : ''}`,
+    `   通道：可用 ${json.channels.available.join('、') || '（无）'}｜预留位 ${json.channels.reserved.join('、') || '（无）'}`,
+    `   宿主：dsh home ${host.dshHome}${host.dshHomeExists ? '' : '（不存在）'}（缺宿主不是 FAIL）`,
+    `   ⛔ 未写 settings.yaml / credentials；本 verb 只动数据目录本身`,
+  ].filter(Boolean).join('\n')
+  return { json, human, stderr: '', exit: 0 }
+}
+
+function initFail(code, reason, error, echo = {}) {
+  return { json: { ok: false, empty: false, code, reason, error, verb: 'init', ...echo }, human: `❌ ${reason}：${error}`, stderr: '', exit: code }
+}
+
+export const INIT_USAGE = [
+  '用法：argent init [--apply] [--json]',
+  '',
+  '数据目录画像（只读）：数据目录（来源/隔离/存在性）、解释器候选、已装技能、许可状态、通道可用性、宿主档事实。',
+  '默认 **dry-run**（不建目录）；--apply 才创建数据目录本身。',
+  '⛔ 不写 ~/.dsh/settings.yaml、不碰 credentials、不改宿主配置。',
+].join('\n')

package/engine/core/lib/ledger.mjs

@@ -0,0 +1,124 @@
+/**
+ * 台账查询（0.3 P1，2026-10-03）—— **CLI 与 MCP 用同一套**（修 D1）。
+ *
+ * D1 实测（复现原文）：`node core/cli/argent.mjs ledger --tail 3` 在 289849 字节的真实台账上返回
+ *     {"ok": true, "count": 0, "rows": []}
+ * —— "唯一真相"说谎。两处根因：
+ *   ① `args[args.indexOf('--flow') + 1]`：`--flow` 不存在时 `indexOf` = −1 ⇒ 取到 `args[0]`（`--tail`）当流程名过滤；
+ *   ② **先 `slice(-tail)` 再 `filter`** ⇒ 即使给了 `--flow`，也只在该尾部窗口内筛。
+ * 本模块把顺序钉死：**读全量 → 过滤 → 再取末尾 N 行**；并把"实际生效的过滤条件"
+ * （`flow` / `flowPrefix` / `tail` / `matched`）一并回显 —— 空结果必须能一眼分辨
+ * "真没有" 与 "被过滤/被截断掉了"（这正是 D1 最贵的形态：看起来空、其实是过滤）。
+ *
+ * 匹配口径与 `scripts/flow_ledger.py --status --flow` 一致：`caseId` 前缀 `<flow>__`
+ * （台账里写的是**局部 id**：`full__…`/`wenyao-invoice__…`；同时容忍规范 id 前缀，防假空）。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { loadRegistry, resolveFlow } from './flow-registry.mjs'
+
+export const DEFAULT_TAIL = 5
+
+/** `--tail` 解析：非 ≥1 的整数 ⇒ 回落到缺省，并**说明**（不静默用 `slice(-0)` 把全量当"末尾 0 行"）。 */
+export function parseTail(input, dflt = DEFAULT_TAIL) {
+  if (input === undefined || input === null || String(input).trim() === '') return { tail: dflt, note: '' }
+  const n = Number(String(input).trim())
+  if (!Number.isFinite(n) || n < 1) {
+    return { tail: dflt, note: `--tail ${JSON.stringify(String(input))} 不是 ≥1 的整数 ⇒ 用默认 ${dflt}` }
+  }
+  return { tail: Math.floor(n), note: '' }
+}
+
+/** 台账文本 → 事件行（坏行保留为 `{raw}`，绝不丢掉证据）。 */
+export function parseLedger(text) {
+  return String(text || '').split('\n').map((l) => l.trim()).filter(Boolean)
+    .map((l) => { try { return JSON.parse(l) } catch { return { raw: l } } })
+}
+
+/** caseId 是否属于该流程：`<prefix>__…`（或恰好等于 prefix）。 */
+export function caseIdMatches(caseId, filter) {
+  const cid = String(caseId || '')
+  if (!cid || !filter) return false
+  return (filter.prefixes || []).some((p) => p && (cid === p || cid.startsWith(`${p}__`)))
+}
+
+/**
+ * 把 `--flow` 解析成"实际生效的过滤条件"。
+ *
+ * **best-effort**：台账是只读的"唯一真相"，不能因为解释器缺失/注册表坏了就整个查不了；
+ * 但失败原因会写进 `note` 回显（**不是**空 catch 吞掉）—— 这是 D3 ③ 的口径。
+ */
+export function resolveLedgerFlow(input, { repo, py, pyFailure = null } = {}) {
+  const literal = String(input || '')
+  const literalFilter = (why) => ({
+    flow: literal,
+    prefixes: [literal],
+    known: false,
+    note: `--flow ${literal} 未经注册表解析（${why}）⇒ 只按字面 caseId 前缀 \`${literal}__\` 匹配；`
+      + '可用流程 id 见 python3 scripts/flow_registry.py --list',
+  })
+  if (pyFailure) return literalFilter('解释器不可用')
+  const reg = loadRegistry({ repo, py })
+  if (!reg.ok) return literalFilter(reg.reason)
+  const r = resolveFlow({ input: literal, doc: reg.doc })
+  if (!r.known) {
+    return {
+      flow: r.canonical,
+      prefixes: [r.local, r.canonical],
+      known: false,
+      note: `流程 \`${literal}\` 不在注册表里（规范 id \`${r.canonical}\`）⇒ 按前缀匹配；`
+        + '可能是拼写错误或该流程未安装，见 python3 scripts/flow_registry.py --list',
+    }
+  }
+  return { flow: r.canonical, prefixes: [r.local, r.canonical], known: true, note: '' }
+}
+
+/**
+ * 台账查询（纯逻辑 + 注入式读文件；CLI/MCP 共用）。
+ * 顺序：**读全量 → 过滤 → 取末尾 N 行**（D1 的根因②）。
+ *
+ * 2026-10-03（P1 前置④）：补 `empty` / `code` / `reason`，让 A2 的真值表在 ledger 上也**判得出来** ——
+ * `count === 0 ⇒ empty:true`（`reason:"no_match"`）；台账文件不在 ⇒ `ok:false, code:1, reason:"no_ledger"`
+ * （**不**降级成 empty：那正是 D1 最贵的形态，把"数据目录不对"伪装成"没有事件"）。
+ */
+export function queryLedger({ file, flow = '', tailInput = '', resolveFilter = null,
+  readFile = (p) => readFileSync(p, 'utf8') } = {}) {
+  const t = parseTail(tailInput)
+  if (!existsSync(file)) {
+    return {
+      ok: false, empty: false, code: 1, reason: 'no_ledger',
+      error: `台账不存在：${file}`,
+      flow: null, flowPrefix: null, flowKnown: null, tail: t.tail, matched: 0, count: 0, rows: [],
+    }
+  }
+  const notes = []
+  if (t.note) notes.push(t.note)
+
+  const flowInput = String(flow || '').trim()
+  let filter = null
+  if (flowInput) {
+    filter = resolveFilter
+      ? resolveFilter(flowInput)
+      : { flow: flowInput, prefixes: [flowInput], known: false, note: '' }
+    if (filter.note) notes.push(filter.note)
+  }
+
+  const rows = parseLedger(readFile(file))
+  const matched = filter ? rows.filter((r) => caseIdMatches(r.caseId, filter)) : rows
+  const out = matched.slice(-t.tail)      // ← 过滤**之后**才截断
+  const empty = out.length === 0
+  return {
+    ok: true,
+    empty,
+    code: 0,
+    // 空结果也必须能判：`no_match` = 真没有（或被过滤/被截断 —— 靠 matched/tail 分辨）
+    reason: empty ? 'no_match' : null,
+    flow: filter ? filter.flow : null,
+    flowPrefix: filter ? (filter.prefixes || [])[0] || null : null,
+    flowKnown: filter ? Boolean(filter.known) : null,
+    tail: t.tail,
+    matched: matched.length,               // 过滤后、截断前的行数（分辨"真没有"与"被截断"）
+    count: out.length,
+    rows: out,
+    ...(notes.length ? { note: notes.join('；') } : {}),
+  }
+}