@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/npm-publish-argent.mjs

@@ -0,0 +1,499 @@
+#!/usr/bin/env node
+/**
+ * `@whyshu/argent-*` 六包发布器（W9，2026-10-12）—— **默认 dry-run**。
+ *
+ * 入口是 `scripts/npm-publish-argent.sh`（薄包装，只做 `exec node <本文件> "$@"`）。
+ * 为什么实现放在 `.mjs` 而入口留 `.sh`：本脚本干的全是 **JSON / 内容摘要 / 退避** 这类事
+ * （`npm pack --json` 的解析、`files` 闭合双向比对、`dist.integrity` 回读），
+ * 用 shell 拼 JSON 的失败方式是"静默取到 undefined" —— 正是本仓库反复吃亏的那一类形态。
+ * ⇒ 判据与 IO 全在 JS 里，shell 只当入口（名字仍按批次要求的 `npm-publish-argent.sh`）。
+ *
+ * ## 为什么默认 dry-run（⛔ 不是懒）
+ * `npm publish` 是**不可撤销**的对外动作（同名同版本不可覆盖）。默认档只做**只读**判据：
+ * 文件闭合、版本纪律、注册表现状，并打印"会发哪些 / 会跳过哪些 / 会判哪些红"。
+ * 要真发必须显式 `--apply`。
+ *
+ * ## 判据（每条都有稳定判据码，红 ⇒ 非零退出）
+ * | 码 | 判据 | 红条件 |
+ * |---|---|---|
+ * | `PUB-J0` | 凭据预检：`<token-file>` 存在且 **mode = 600**；`npm whoami` == `whyshu` | 任一不满足 |
+ * | `PUB-J1` | **文件闭合**：`npm pack --dry-run --json` 的清单 ↔ `package.json#files` **双向**自洽（含 `main`/`exports`/`dsh.bundle.patch` 引用面） | 缺件 / 多件 / 死条目 |
+ * | `PUB-J2` | **版本纪律（本地台账）**：审计 JSONL 里该 `(包名, 版本)` 最近一条记录的 `integrity` 必须等于本次本地 pack 的 integrity | 不等 ⇒ "内容变了、版本没变"（⛔ 不发、⛔ 不覆盖） |
+ * | `PUB-J3` | **幂等**：注册表上该版本的 `dist.integrity` == 本地 ⇒ **跳过**（打印 SKIP），调用方可以放心重跑 | 不是红（红的是下面 J4） |
+ * | `PUB-J4` | 注册表上**已存在**该版本，但 `dist.integrity` **不等于**本地 ⇒ 判红（⛔ 绝不覆盖） | 不等 |
+ * | `PUB-J5` | **回读退避**：发布后回读 `dist.integrity`；实测注册表**复制延迟 ~3 分钟** ⇒ 一次 404/空/非零**都不算失败**，按 `--retry-interval-ms`（默认 15s）退避重试至多 `--retry-max` 次（默认 20 ⇒ ~5 分钟） | `--apply` 下用尽仍读不到；或回读到的 integrity ≠ 刚发布的字节 |
+ * | `PUB-J6` | **审计**：`--apply` 下每个包落一行 JSONL（包名/版本/integrity/时间/来源提交 hash/动作/账号） | 写不进 ⇒ 红（审计是"发过什么"的唯一凭证） |
+ *
+ * ## 幂等语义（一句话）
+ * "已发布且 integrity 一致 ⇒ 跳过；已发布但不一致 ⇒ 判红；本地内容变了而版本没变 ⇒ 判红。"
+ * ⇒ **可以无脑重跑**：重跑要么跳过、要么把没发成功的补上，⛔ 永远不会覆盖已发布的字节。
+ *
+ * ## 纪律
+ *   · token **只**经临时 `.npmrc`（0600，`trap` 清理）传给 npm，⛔ 不进命令行/日志/审计；
+ *   · ⛔ 不写 `~/.npmrc`；⛔ 不动仓库工作树（`npm pack --dry-run` 不落 tgz）；
+ *   · 审计按需 `mkdir -p` 父目录，0600。
+ *
+ * 用法：`bash scripts/npm-publish-argent.sh [--apply] [--only <id[,id…]>] …`（见 `--help`）。
+ */
+import { execFileSync, spawnSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, appendFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { PLUGIN_PACKAGES, pluginIdOf, isAgentBundleId } from './lib/plugin-packages.mjs'
+// 数据目录**唯一判据**：本文件的默认令牌/审计路径**必须**经它算，⛔ 不许自己拼 `.dsh/argent`
+// （`scripts/tests/argent-datadir.test.mjs`【3】按机器判据点名任何硬编码的第二份链；
+//  同族写法先例：`scripts/argent-catalog.mjs#DATA_DIR`）。
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+
+/** 默认数据目录（`ARGENT_DATA_DIR` → `$DSH_HOME/argent` → 老位置/新装兜底）。 */
+function defaultDataDir() {
+  return resolveDataDir({ env: process.env }).dir
+}
+
+/** npm 账号名（**用户名 scope**，⛔ 不是组织）。 */
+const EXPECTED_USER = 'whyshu'
+
+/**
+ * npm 自动纳入包内、因而**不需要**出现在 `files` 里的路径（逐条给理由）。
+ * 依据 = npm 官方 `files` 语义（这几个是历史约定 + `package.json` 永远在内）。
+ */
+const AUTO_INCLUDE = [
+  'package.json',   // npm 强制纳入（否则包装不起来）
+  'README', 'README.md', 'README.markdown', 'README.txt',
+  'LICENSE', 'LICENSE.md', 'LICENSE.txt', 'LICENCE', 'LICENCE.md', 'LICENCE.txt',
+  'CHANGELOG', 'CHANGELOG.md', 'CHANGELOG.txt',
+  'NOTICE', 'NOTICE.md', 'NOTICE.txt',
+]
+/** 自动纳入的**前缀**形态（`README.zh.md` 这类）。 */
+const AUTO_INCLUDE_RE = /^(?:README|LICEN[CS]E|CHANGELOG|NOTICE|HISTORY|AUTHORS)(?:[.\w-]*)$/
+
+const USAGE = `用法：bash scripts/npm-publish-argent.sh [选项]
+  （不带 --apply ⇒ **dry-run**：只做只读判据并打印计划，⛔ 不发布、⛔ 不写审计、⛔ 不动注册表）
+
+  --apply                     真发布（⛔ 不可撤销：同名同版本的字节不能覆盖）
+  --only <id[,id…]>           只处理这些插件 id（默认 = 6 个全量，顺序取真源）
+  --npm-bin <path>            用哪个 npm（默认 PATH 上的 \`npm\`）
+  --registry <url>            registry（默认 https://registry.npmjs.org）
+  --token-file <path>         npm granular token（默认 ~/.dsh/argent/npm-token，必须 600）
+  --audit <path>              审计 JSONL（默认 ~/.dsh/argent/npm-publish-audit.jsonl）
+  --retry-interval-ms <n>     回读退避间隔毫秒（默认 15000；实测注册表复制延迟 ~3 分钟）
+  --retry-max <n>             回读最大次数（默认 20 ⇒ 约 5 分钟）
+  --repo <dir>                仓库根（默认由本文件位置推）
+  -h | --help                 本帮助
+
+退出码：0 = 全绿（含"全部跳过"）；1 = 有判据判红；2 = 用法错误。
+重跑安全：**幂等**（已发布且 integrity 一致 ⇒ 跳过；不一致 ⇒ 判红，⛔ 不覆盖）。
+`
+
+function die(code, msg) {
+  if (msg) console.error(msg)
+  process.exit(code)
+}
+
+/** 极简参数解析（⛔ 未知 flag 一律用法错误 —— 静默忽略参数是本仓库反复吃亏的形态）。 */
+function parseArgs(argv) {
+  const o = {
+    apply: false, only: null, npmBin: 'npm', registry: 'https://registry.npmjs.org',
+    tokenFile: join(defaultDataDir(), 'npm-token'),
+    audit: join(defaultDataDir(), 'npm-publish-audit.jsonl'),
+    retryIntervalMs: 15000, retryMax: 20, repo: REPO,
+  }
+  const need = (i, name) => {
+    if (i + 1 >= argv.length) die(2, `✗ ${name} 需要一个取值（见 --help）`)
+    return argv[i + 1]
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    switch (a) {
+      case '--apply': o.apply = true; break
+      case '--only': o.only = String(need(i, a)).split(',').map((s) => s.trim()).filter(Boolean); i += 1; break
+      case '--npm-bin': o.npmBin = need(i, a); i += 1; break
+      case '--registry': o.registry = need(i, a); i += 1; break
+      case '--token-file': o.tokenFile = need(i, a); i += 1; break
+      case '--audit': o.audit = need(i, a); i += 1; break
+      case '--repo': o.repo = resolve(need(i, a)); i += 1; break
+      case '--retry-interval-ms': {
+        const v = Number(need(i, a)); i += 1
+        if (!Number.isFinite(v) || v < 0) die(2, `✗ --retry-interval-ms 需要一个 ≥ 0 的数，实得 ${JSON.stringify(argv[i])}`)
+        o.retryIntervalMs = v; break
+      }
+      case '--retry-max': {
+        const v = Number(need(i, a)); i += 1
+        if (!Number.isInteger(v) || v < 1) die(2, `✗ --retry-max 需要一个 ≥ 1 的整数，实得 ${JSON.stringify(argv[i])}`)
+        o.retryMax = v; break
+      }
+      case '-h': case '--help': console.log(USAGE); process.exit(0); break
+      default: die(2, `✗ 未知参数 ${a}（⛔ 不静默忽略；见 --help）`)
+    }
+  }
+  if (o.only) {
+    // ⚠️ W3（0.6.0）：智能体 bundle（`argent-agent-<id>`）**也**是合法取值 —— 它们**不在** `PLUGIN_PACKAGES`
+    // 的静态表里（名字带业务线词，列进引擎面会脏了 engine-words 判据）⇒ 认的是**前缀规则**
+    // （`isAgentBundleId`），与 `pluginIdOf` 同一个真源。
+    const unknown = o.only.filter((x) => !pluginIdOf(x))
+    if (unknown.length) {
+      die(2, `✗ --only 里有未知插件 id：${unknown.join('、')}\n  合法取值：${PLUGIN_PACKAGES.map((p) => p.id).join('、')}`
+        + ` ＋ 任意智能体 bundle（\`plugins/argent-agent-<id>\`，由 agents/catalog.json 生成）`)
+    }
+  }
+  return o
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 判据（纯函数；可注入 IO ⇒ 自带夹具回归里能逐条注入违规证明"有牙"）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** npm `files` 语义的**最小**实现：条目是文件 ⇒ 精确匹配；是目录 ⇒ 前缀匹配。 */
+export function isCoveredByFiles(rel, files) {
+  const r = String(rel).replace(/^\.\//, '')
+  return (files || []).some((f) => {
+    const e = String(f).replace(/^\.\//, '').replace(/\/+$/, '')
+    return e !== '' && (r === e || r.startsWith(`${e}/`))
+  })
+}
+
+/** manifest 里"运行时会被读到"的文件引用面（`main` / `exports` / `dsh.bundle.patch`）。 */
+export function collectRuntimeRefs(m) {
+  const out = []
+  const push = (x) => { if (typeof x === 'string' && x.startsWith('./')) out.push(x.replace(/^\.\//, '')) }
+  push(m.main)
+  const walk = (e) => {
+    if (typeof e === 'string') push(e)
+    else if (e && typeof e === 'object') for (const v of Object.values(e)) walk(v)
+  }
+  walk(m.exports)
+  walk(m.dsh?.bundle?.patch)
+  return [...new Set(out)]
+}
+
+/** 自动纳入判定（`package.json` ⇒ true；`README*` 等前缀形态也只对**顶层**文件生效）。 */
+export function isAutoIncluded(rel) {
+  const r = String(rel).replace(/^\.\//, '')
+  if (AUTO_INCLUDE.includes(r)) return true
+  // npm 只自动纳入**包根**下的这几个名字，不含子目录里的同名文件
+  return !r.includes('/') && AUTO_INCLUDE_RE.test(r)
+}
+
+/**
+ * **PUB-J1 文件闭合**（双向）。
+ *
+ * 为什么双向（单向后患无穷）：
+ *   · 只查"声明了但没进包" ⇒ 漏掉"**没声明却进包**"（= 把不该发的发出去，比如测试夹具/内网地址）；
+ *   · 只查"包里没有多余" ⇒ 漏掉"**声明是死的**"（`files` 里写了盘上不存在的路径，npm 静默忽略）。
+ * ⛔ 不把"多件"一律判红：npm 会自动纳入 `package.json`/`README`/`LICENSE`… ⇒ 那组进 `AUTO_INCLUDE`。
+ * @returns {{problems: Array<{code:string,where:string,detail:string}>}}
+ */
+export function checkFilesClosure({ manifest, packFiles, exists = existsSync, dir = '' }) {
+  const problems = []
+  const add = (where, detail) => problems.push({ code: 'PUB-J1', where, detail })
+  const declared = Array.isArray(manifest.files) ? manifest.files.map((x) => String(x)) : []
+  if (!declared.length) add('package.json#files', '缺 files（npm 发布时必须显式声明；不写 ⇒ 全仓进包）')
+  const paths = packFiles.map((f) => String(f).replace(/^\.\//, ''))
+  for (const d of declared) {
+    const rel = d.replace(/^\.\//, '').replace(/\/+$/, '')
+    if (!rel) continue
+    if (dir && !exists(join(dir, rel))) add('package.json#files', `files 里的 ${JSON.stringify(d)} 在盘上不存在（死条目）`)
+    // W9-D3 修正（2026-10-13）：原写法 `!isCoveredByFiles(rel, [rel]) && …` 的第一个操作数**恒 false** ⇒
+    // 短路 ⇒ "files 声明了但没进包"这一支**不可达**（缺件的包会被静默发出去）。只保留真正有义的那半。
+    if (!paths.some((p) => p === rel || p.startsWith(`${rel}/`))) {
+      add('package.json#files', `files 声明的 ${JSON.stringify(d)} **没有进包**（装出来的包缺件）`)
+    }
+  }
+  for (const p of paths) {
+    if (isCoveredByFiles(p, declared) || isAutoIncluded(p)) continue
+    add('package.json#files', `包里有 ${JSON.stringify(p)}，但它既不在 files 的覆盖范围内、也不是 npm 自动纳入的那几个 ⇒ 要么补 files、要么别发它`)
+  }
+  for (const ref of collectRuntimeRefs(manifest)) {
+    if (ref === 'package.json') continue
+    if (!paths.includes(ref)) add('package.json', `manifest 引用了运行时文件 ${JSON.stringify(ref)}，但它不在包里（装完必崩）`)
+  }
+  return { problems }
+}
+
+/** 解析 `npm pack --dry-run --json` 的输出（数组；坏形状 ⇒ 抛）。 */
+export function parsePackJson(text) {
+  const doc = JSON.parse(String(text))
+  const one = Array.isArray(doc) ? doc[0] : doc
+  if (!one || typeof one !== 'object') throw new Error('npm pack 的 JSON 里没有包对象')
+  return {
+    name: String(one.name || ''),
+    version: String(one.version || ''),
+    integrity: String(one.integrity || ''),
+    filename: String(one.filename || ''),
+    files: (one.files || []).map((f) => String(f.path || '')),
+  }
+}
+
+/** 审计 JSONL 里该 `(包名, 版本)` 的**最近一条**记录（读不到/坏行 ⇒ null）。 */
+export function lastLedgerRecord(auditPath, pkg, version) {
+  let text = ''
+  try { text = readFileSync(auditPath, 'utf8') } catch { return null }
+  let hit = null
+  for (const line of text.split('\n')) {
+    const s = line.trim()
+    if (!s) continue
+    let rec = null
+    try { rec = JSON.parse(s) } catch { continue }
+    if (rec && rec.pkg === pkg && String(rec.version) === String(version)) hit = rec
+  }
+  return hit
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// IO 层
+// ─────────────────────────────────────────────────────────────────────────────
+
+function npmRun(o, args, { cwd = '', allowFail = false } = {}) {
+  const r = spawnSync(o.npmBin, args, {
+    cwd: cwd || undefined,
+    encoding: 'utf8',
+    env: { ...process.env, NPM_CONFIG_USERCONFIG: o.userconfig, NPM_CONFIG_LOGLEVEL: 'error' },
+  })
+  const out = `${r.stdout || ''}`
+  const err = `${r.stderr || ''}`
+  if (r.status !== 0 && !allowFail) {
+    throw new Error(`\`${o.npmBin} ${args.join(' ')}\` 退出 ${r.status}：${(err || out).trim().split('\n').slice(0, 4).join(' / ')}`)
+  }
+  return { status: r.status, out, err }
+}
+
+/** 注册表回读：`{'found',integrity}` / `{'missing'}`（E404 ⇒ 明确"没有"）/ `{'unknown'}`。 */
+function probeRegistry(o, pkg, version) {
+  const r = npmRun(o, ['view', `${pkg}@${version}`, 'dist.integrity', '--json', '--registry', o.registry], { allowFail: true })
+  const text = `${r.out}${r.err}`
+  if (/E404|404 Not Found|is not in this registry/i.test(text)) return { status: 'missing' }
+  if (r.status !== 0) return { status: 'unknown', why: text.trim().split('\n').slice(0, 3).join(' / ') }
+  let v = ''
+  try { v = JSON.parse(r.out.trim()) } catch { v = r.out.trim().replace(/^"|"$/g, '') }
+  if (!v || typeof v !== 'string') return { status: 'unknown', why: `回读不是字符串：${JSON.stringify(r.out.slice(0, 120))}` }
+  return { status: 'found', integrity: v }
+}
+
+const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms))
+
+/**
+ * 退避回读（**PUB-J5**）：一次 404/空/非零**都不算失败**（实测注册表复制延迟 ~3 分钟）。
+ * @param {{probe:Function, max:number, intervalMs:number, want:'found'|'answer'}} o
+ *   `want:'found'`（发布后）⇒ 只有拿到 integrity 才停；`want:'answer'`（发布前探测）⇒ 拿到
+ *   "found 或明确 missing"即停（都不必等满预算）。
+ */
+async function readback({ probe, max, intervalMs, want }) {
+  let last = { status: 'unknown' }
+  const attempts = []
+  for (let i = 1; i <= max; i += 1) {
+    last = probe()
+    attempts.push(last.status)
+    if (last.status === 'found') return { ...last, attempts: i }
+    if (want === 'answer' && last.status === 'missing') return { ...last, attempts: i }
+    if (i < max && intervalMs > 0) await sleepMs(intervalMs)
+  }
+  return { ...last, attempts: max, exhausted: true, attemptLog: attempts }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const o = parseArgs(process.argv.slice(2))
+  o.repo = o.repo || REPO
+
+  // ── PUB-J0 凭据预检 ────────────────────────────────────────────────────────
+  const reds = []
+  const red = (code, where, detail) => { reds.push({ code, where, detail }); console.error(`  \x1b[1;31m✗\x1b[0m [${code}] ${where} —— ${detail}`) }
+  // W9-D1b 修正（2026-10-13）：先算清凭据**文件本身**是否合规；不合规 ⇒ ⛔ 不读它、不建 .npmrc、不跑 whoami。
+  // （旧实现"判红之后照用"，夹具实证：mode=644 时仍把令牌真的送进了一次 `npm whoami`。）
+  let credFileOk = false
+  if (!existsSync(o.tokenFile)) {
+    red('PUB-J0', o.tokenFile, '凭据文件不存在（npm granular access token；见 docs/Argent-插件化评估与实施计划.md §6 决策点 4）')
+  } else {
+    const mode = statSync(o.tokenFile).mode & 0o777
+    if (mode !== 0o600) red('PUB-J0', o.tokenFile, `权限是 ${mode.toString(8)}（必须 600：\`chmod 600 ${o.tokenFile}\`）`)
+    else credFileOk = true
+  }
+
+  // 临时 userconfig（token 只经它传给 npm；⛔ 不写 ~/.npmrc、⛔ 不进命令行）
+  // W9-D1b：只有凭据**文件合规**（存在 + 600）才读它 —— 否则一个 644 的令牌会被真的送进 `npm whoami`。
+  let tmp = ''
+  let token = ''
+  if (credFileOk) { try { token = readFileSync(o.tokenFile, 'utf8').trim() } catch { token = '' } }
+  if (token) {
+    tmp = mkdtempSync(join(tmpdir(), 'argent-npm-publish-'))
+    o.userconfig = join(tmp, 'npmrc')
+    const host = (() => { try { return new URL(o.registry).host } catch { return 'registry.npmjs.org' } })()
+    writeFileSync(o.userconfig, `//${host}/:_authToken=${token}\n`, { mode: 0o600 })
+    chmodSync(o.userconfig, 0o600)
+  }
+  const cleanup = () => { if (tmp) { try { rmSync(tmp, { recursive: true, force: true }) } catch { /* 忽略 */ } } }
+  process.on('exit', cleanup)
+  for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => { cleanup(); process.exit(1) })
+
+  if (token) {
+    const w = npmRun(o, ['whoami', '--registry', o.registry], { allowFail: true })
+    const got = `${w.out}`.trim()
+    if (w.status !== 0 || got !== EXPECTED_USER) {
+      red('PUB-J0', 'npm whoami', `必须是 \`${EXPECTED_USER}\`，实得 \`${got || '(空)'}\`（exit ${w.status}）—— 令牌无效/过期，或 registry 不对`)
+    } else {
+      console.log(`  \x1b[32m✓\x1b[0m 凭据预检：\`npm whoami\` = ${got}（token ${o.tokenFile}，mode 600）`)
+    }
+  }
+
+  // ── 安全闸门（W9-D1 修正，2026-10-13）：凭据预检**判红 ⇒ 禁止 `--apply` 发布** ──────────────
+  // 夹具实证：旧实现里 `red()` 只入 `reds`，主循环在 `publish` 前**从不检查** ⇒ `whoami` 报别人 /
+  // 令牌 mode=644 时，`--apply` 仍会把包发出去（可能"发到一半"，人工得反查哪些真出去了）。
+  // 判据：J0 段结束时 `reds` 为空 = 预检干净（更早的用法面判红会 exit 2，不会走到这里）。
+  const credOk = reds.length === 0
+
+  // 发布面
+  // ⚠️ W3（0.6.0）：**智能体 bundle 由盘上现扫**（`plugins/argent-agent-*`，前缀规则）——
+  // 它们的名字来自 L0 货架声明（含业务线词）⇒ ⛔ 不进 `plugin-packages.mjs` 的静态表（engine-words 判据），
+  // 但**必须**能被本发布器认出来（否则 Lead 发不出 W3 的 6 个包）。id ↔ npm 名仍由**同一个**真源推导。
+  const agentRows = (() => {
+    try {
+      return readdirSync(join(o.repo, 'plugins'))
+        .filter((d) => isAgentBundleId(d) && existsSync(join(o.repo, 'plugins', d, 'package.json')))
+        .sort()
+        .map((id) => ({ id, npm: `@whyshu/${id}` }))
+    } catch { return [] }
+  })()
+  const registryRows = [...PLUGIN_PACKAGES, ...agentRows]
+  const wanted = o.only ? o.only.map((x) => pluginIdOf(x)).filter(Boolean) : registryRows.map((p) => p.id)
+  const rows = registryRows.filter((p) => wanted.includes(p.id))
+  const mode = o.apply ? '\x1b[1;31mAPPLY（真发布）\x1b[0m' : '\x1b[1;33mDRY-RUN（默认；只读判据 + 计划，⛔ 不发布）\x1b[0m'
+  console.log(`\nArgent 插件发布器 —— ${mode}`)
+  console.log(`  registry：${o.registry}｜registry 复制延迟实测 ~3 分钟 ⇒ 回读退避 ${o.retryIntervalMs}ms × 最多 ${o.retryMax} 次`)
+  console.log(`  发布面（${rows.length}）：${rows.map((r) => r.npm).join('、')}`)
+  if (!o.apply) console.log('  \x1b[2m↳ dry-run 的回读只探一次（"尚未可见"就是计划发布；⛔ 不必为空包等 5 分钟；给 --retry-max 可覆盖）\x1b[0m')
+
+  const plan = []
+  const audit = []
+  for (const p of rows) {
+    const dir = join(o.repo, 'plugins', p.id)
+    console.log(`\n── ${p.npm}（plugins/${p.id}）`)
+    let manifest = null
+    try { manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) } catch (e) {
+      red('PUB-J1', `plugins/${p.id}/package.json`, `读不出/不是 JSON：${e.message}`); continue
+    }
+    if (manifest.name !== p.npm) red('PUB-J1', `plugins/${p.id}/package.json#name`, `包名是 ${JSON.stringify(manifest.name)}，真源期望 ${JSON.stringify(p.npm)}`)
+    // 本地内容字样（`npm pack --dry-run` ⇒ 零写、可离线、integrity = 会写进注册表的那个）
+    let pack = null
+    try {
+      const r = npmRun(o, ['pack', '--dry-run', '--json'], { cwd: dir })
+      pack = parsePackJson(r.out)
+    } catch (e) {
+      red('PUB-J1', `plugins/${p.id}`, `\`npm pack --dry-run --json\` 失败：${e.message}`); continue
+    }
+    const clos = checkFilesClosure({ manifest, packFiles: pack.files, dir })
+    for (const x of clos.problems) red(x.code, `${x.where}`, x.detail)
+    if (clos.problems.length) continue
+    console.log(`  \x1b[32m✓\x1b[0m [PUB-J1] 文件闭合：${pack.files.length} 个文件 ↔ files ${JSON.stringify(manifest.files)}`)
+    console.log(`  \x1b[2m↳ ${pack.name}@${pack.version}　integrity ${pack.integrity}\x1b[0m`)
+
+    // ── PUB-J2 版本纪律（本地台账）────────────────────────────────────────────
+    const rec = lastLedgerRecord(o.audit, pack.name, pack.version)
+    if (rec && rec.integrity && rec.integrity !== pack.integrity) {
+      red('PUB-J2', `${pack.name}@${pack.version}`, `本地台账记的 integrity 是 ${rec.integrity}，本次 pack 是 ${pack.integrity}`
+        + ' ⇒ **内容变了、版本没变**（审计 JSONL 是"发过什么"的唯一凭证）⇒ 提版本再发，⛔ 绝不覆盖')
+      continue
+    }
+    if (rec) console.log(`  \x1b[32m✓\x1b[0m [PUB-J2] 版本纪律：台账里 ${pack.name}@${pack.version} 的 integrity 与本机一致`)
+
+    // ── PUB-J3 / J4：注册表现状 ───────────────────────────────────────────────
+    const probeMax = o.apply ? Math.min(3, o.retryMax) : 1
+    const pre = await readback({ probe: () => probeRegistry(o, pack.name, pack.version), max: probeMax, intervalMs: o.retryIntervalMs, want: 'answer' })
+    if (pre.status === 'found') {
+      if (pre.integrity === pack.integrity) {
+        console.log(`  \x1b[32m✓\x1b[0m [PUB-J3] SKIP ${pack.name}@${pack.version}（注册表 integrity 与本地一致；幂等 ⇒ 无需重发）`)
+        plan.push({ pkg: pack.name, version: pack.version, integrity: pack.integrity, action: 'skip' })
+        audit.push({ pkg: pack.name, version: pack.version, integrity: pack.integrity, action: 'skipped' })
+        continue
+      }
+      red('PUB-J4', `${pack.name}@${pack.version}`, `注册表上已有该版本，但 dist.integrity = ${pre.integrity}，本机 pack = ${pack.integrity}`
+        + ' ⇒ **已发布但不一致**（⛔ 绝不覆盖：同名同版本的字节不可变）⇒ 提版本再发')
+      continue
+    }
+    if (pre.status === 'unknown') {
+      red('PUB-J5', `${pack.name}@${pack.version}`, `注册表探测失败（不是 404，是读不到）：${pre.why || '（无细节）'}`
+        + ' ⇒ 先确认 `--registry` / 网络 / 凭据，再重跑（本脚本幂等）')
+      continue
+    }
+    // 明确"注册表上还没有这个版本" ⇒ 计划发布
+    console.log(`  \x1b[33m•\x1b[0m ${pack.name}@${pack.version} 尚未在注册表可见 ⇒ ${o.apply ? '发布' : '**计划发布**'}`)
+    if (!o.apply) { plan.push({ pkg: pack.name, version: pack.version, integrity: pack.integrity, action: 'publish(plan)' }); continue }
+
+    // W9-D1 安全闸门：预检不干净 ⇒ **拒绝发布**（⛔ 不允许"边判红边发"）
+    if (!credOk) {
+      red('PUB-J0', `${pack.name}@${pack.version}`, '凭据预检未通过（见上）⇒ **拒绝发布**：⛔ 不允许"边判红边发"（否则可能发到一半，人工得反查哪些真出去了）')
+      continue
+    }
+
+    // ── 真发布 + PUB-J5 回读退避 ─────────────────────────────────────────────
+    let pubOk = false
+    try {
+      const r = npmRun(o, ['publish', '--access', 'public', '--registry', o.registry], { cwd: dir })
+      pubOk = true
+      const line = `${r.out}${r.err}`.trim().split('\n').filter(Boolean).slice(-2).join(' / ')
+      if (line) console.log(`  \x1b[2m↳ npm: ${line}\x1b[0m`)
+    } catch (e) {
+      red('PUB-J6', pack.name, `\`npm publish\` 失败：${e.message}`)
+      continue
+    }
+    if (!pubOk) continue
+    console.log(`  \x1b[32m✓\x1b[0m 已发布 ${pack.name}@${pack.version} ⇒ 回读 dist.integrity（退避 ${o.retryIntervalMs}ms × ${o.retryMax}）`)
+    const post = await readback({ probe: () => probeRegistry(o, pack.name, pack.version), max: o.retryMax, intervalMs: o.retryIntervalMs, want: 'found' })
+    if (post.status !== 'found') {
+      red('PUB-J5', `${pack.name}@${pack.version}`, `回读用尽 ${post.attempts} 次仍读不到 dist.integrity`
+        + `（状态序列 ${JSON.stringify(post.attemptLog || [])}）—— 注册表复制可能还在路上（实测 ~3 分钟）`
+        + '；**发布本身已成功**，稍后重跑本脚本会走"幂等跳过"这条路（⛔ 不要重复手工发布）')
+      // W9-D2 修正（2026-10-13）：发布**已经发生** ⇒ 必须留痕（原实现 `continue` 在 `audit.push` 之前，
+      // 恰恰在最需要凭据的"发了但验不了"场景下不留任何记录，与文件头 J6 冲突）。
+      audit.push({ pkg: pack.name, version: pack.version, integrity: '(unverified)', action: 'published-unverified' })
+      continue
+    }
+    if (post.integrity !== pack.integrity) {
+      red('PUB-J5', `${pack.name}@${pack.version}`, `回读到的 integrity 是 ${post.integrity}，本机 pack 是 ${pack.integrity}`
+        + ' ⇒ 注册表上的字节**不是**我们刚发布的那些（可疑：有人在并发发布同名版本）')
+      audit.push({ pkg: pack.name, version: pack.version, integrity: String(post.integrity || '(unverified)'), action: 'published-unverified' })
+      continue
+    }
+    console.log(`  \x1b[32m✓\x1b[0m [PUB-J5] 回读一致（第 ${post.attempts} 次）：${post.integrity}`)
+    plan.push({ pkg: pack.name, version: pack.version, integrity: pack.integrity, action: 'published' })
+    audit.push({ pkg: pack.name, version: pack.version, integrity: pack.integrity, action: 'published' })
+  }
+
+  // ── PUB-J6 审计 ────────────────────────────────────────────────────────────
+  if (o.apply && audit.length) {
+    try {
+      mkdirSync(dirname(o.audit), { recursive: true })
+      let source = 'unknown'
+      try { source = execFileSync('git', ['-C', o.repo, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf8' }).trim() || 'unknown' } catch { source = 'unknown' }
+      const at = new Date().toISOString()
+      const lines = audit.map((a) => `${JSON.stringify({ at, pkg: a.pkg, version: a.version, integrity: a.integrity, action: a.action, source, by: EXPECTED_USER })}\n`).join('')
+      appendFileSync(o.audit, lines, { mode: 0o600 })
+      console.log(`\n  \x1b[32m✓\x1b[0m [PUB-J6] 审计已追加 ${audit.length} 行 → ${o.audit}（来源提交 ${source}；⛔ 不含令牌）`)
+    } catch (e) {
+      red('PUB-J6', o.audit, `审计写入失败：${e.message}`)
+    }
+  }
+
+  // ── 汇总 ───────────────────────────────────────────────────────────────────
+  console.log('\n── 计划/结果')
+  for (const x of plan) console.log(`   ${x.action === 'published' ? '\x1b[32m已发布\x1b[0m' : x.action === 'skip' ? '\x1b[36m跳过\x1b[0m' : '\x1b[33m待发布\x1b[0m'}  ${x.pkg}@${x.version}`)
+  if (!plan.length && !reds.length) console.log('   （无）')
+  if (reds.length) {
+    console.error(`\n\x1b[1;31m✗ ${reds.length} 条判据判红（分布：${[...new Set(reds.map((r) => r.code))].join('、')}）\x1b[0m`)
+    console.error('  ⛔ 本脚本**不会**覆盖已发布的同名同版本；红的含义是"停下来提版本/修文件/修凭据"。')
+    process.exit(1)
+  }
+  console.log(`\n\x1b[32m✅ 全绿\x1b[0m（${plan.filter((x) => x.action === 'published').length} 已发布 / ${plan.filter((x) => x.action === 'skip').length} 跳过 / `
+    + `${plan.filter((x) => String(x.action).startsWith('publish')).length - plan.filter((x) => x.action === 'published').length} 待发布）`)
+  if (o.apply) console.log(`  真发布用的一条命令就是刚才这条：--apply（重跑安全：已发布且一致 ⇒ 跳过）`)
+}
+
+// 只有直接执行才跑 main（允许本文件被回归用例 import 复用纯函数）
+const isDirect = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isDirect) {
+  main().catch((e) => { console.error(`\n\x1b[1;31m✗ 发布器异常：${e && e.message ? e.message : e}\x1b[0m`); process.exit(1) })
+}

package/engine/scripts/npm-publish-argent.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# `@whyshu/argent-*` 六包发布器 —— **入口**（W9，2026-10-12）。默认 **dry-run**。
+#
+# 为什么只是一层薄包装：真正的判据与 IO（`npm pack --json` 解析、`files` 闭合双向比对、
+# `dist.integrity` 退避回读、审计 JSONL）全在 `scripts/npm-publish-argent.mjs` 里 ——
+# 用 shell 拼 JSON 的失败方式是"静默取到 undefined"，正是本仓库反复吃亏的那一类形态。
+# 名字留 `.sh` 是因为交付物与运维惯例都按它来；行为口径见 .mjs 的文件头（判据表 PUB-J0…J6）。
+#
+# 用法：
+#   bash scripts/npm-publish-argent.sh                 # dry-run（只读判据 + 计划）
+#   bash scripts/npm-publish-argent.sh --apply         # 真发布（⛔ 不可撤销；重跑安全=幂等）
+#   bash scripts/npm-publish-argent.sh --help
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+NODE_BIN="${ARGENT_NODE_BIN:-node}"
+command -v "$NODE_BIN" >/dev/null 2>&1 || {
+  echo "✗ 找不到 node（\$ARGENT_NODE_BIN=${ARGENT_NODE_BIN:-<空>}）—— 发布器需要 node ≥ 20" >&2
+  exit 2
+}
+exec "$NODE_BIN" "$HERE/npm-publish-argent.mjs" "$@"