@whyshu/argent-engine 0.7.3 → 0.7.5

package/engine/scripts/install-one-shot.mjs

@@ -1,665 +0,0 @@
-#!/usr/bin/env node
-/**
- * install-one-shot —— **干净机器一条命令**（D1 的编排入口；2026-10-05）
- *
- * ## 为什么是"新增一层薄编排"而不是塞进 `install-argent.mjs`
- * 判据文档 `docs/Argent-1.0-退出判据与版本规则.md` §6 Q6 已定 **B（新增一层编排入口）**，
- * 本文件就是该结论的落地，理由三条：
- *   ① **职责**：`install-argent.mjs`（1975 行）只承担"装配"一件事；许可（授权判定）与技能归类
- *      判据都在**内核侧**，把它们内联进安装器会让安装器承担内核判断（与《宿主适配契约》§1 的
- *      分层边界冲突）；
- *   ② **三段各有唯一实现**：装配 = `install-argent.mjs`｜技能同步 = `scripts/argent-upgrade.mjs`
- *      导出的 `classifySkills()`/`syncSkills()`（判据真源 `scripts/check-skill-classification.mjs#classify()`）｜
- *      许可 = `scripts/install-license.mjs`。编排只做「串联 + 逐步给结论」，
- *      ⛔ **绝不复制任何一段的判断**（本文件里没有第二份技能名单、第二份验签、第二份 patch 逻辑）；
- *   ③ **可单独重跑**：每段本身就是一条独立命令 ⇒ `--only <段>` 天然可重跑，不必"从头再来一遍"。
- *
- * ## 契约（一条命令，5 段）
- * ```
- * node scripts/install-one-shot.mjs [--profile <p>] [--dsh-home <h>] [--tree <dir>]
- *                                   [--from-packs <包目录/tgz/URL,…>]
- *                                   [--license-file <f>] [--license-secret-file <f>]
- *                                   [--only <段,…>] [--apply] [--json] [--report <f>]
- *                                   [--timeout <秒>] [--no-provider] [--no-venv]
- * ```
- * | 段 | 做什么 | 调用谁（唯一实现） | 判据（结论行） |
- * |---|---|---|---|
- * | `precheck` | 宿主/树前置检查 | 本文件（只做**存在性/版本**探测，不做业务判断）＋ `core/lib/argent-datadir.mjs#resolveDataDir` | 0 项失败 |
- * | `install`  | profile 装配 | `node <树>/install-argent.mjs …`（离线面 `--from-packs` / 在线面） | 退出码 0 ∧ 装机清单或 profile patch 在位 |
- * | `skills`   | 技能同步（**只发外发集**） | `scripts/argent-upgrade.mjs` 的 `classifySkills()`+`syncSkills()` | 外发集非空 ∧ 源缺件 0 |
- * | `license`  | 许可安装（＋可选**实例令牌**，机器自带凭证） | `node <树>/scripts/install-license.mjs --file … [--instance-token-file …]` | 退出码 0；**未给 `--license-file` ⇒ `skipped`，不算失败**（结论里标「未装许可」） |
- * | `verify`   | 收尾自检 | `install-argent.mjs --list-capabilities`／`plugin-bootcheck.mjs`／`check-role-mapping.mjs`／`core/cli/argent.mjs license status` | 逐条 `ok/fail/n-a`（`n-a` = 前置未满足，**点名前置 + 给单跑命令**，不冒充通过） |
- *
- * ## 四条语义（判据原话：幂等 / 默认 dry-run / 每步可单独重跑 / 失败即停且打印"下一步"）
- *   ① **默认 dry-run**：不带 `--apply` 只打印**将要执行的每一步的确切命令**与判据，**零写入**；
- *   ② **幂等**：每段都调既有幂等实现（`--from-packs` 逐文件 sha 跳过；`syncSkills` 内容一致即跳过；
- *      `install-license` 与现役逐字节相同 ⇒ `unchanged:true` 不重写）⇒ 同一条命令重跑结论一致、不产生 churn；
- *   ③ **每步可单独重跑**：`--only <段>`；失败时打印的"下一步"就是该段的单跑命令；
- *   ④ **失败即停**：任一段 `fail` ⇒ 立刻停，后续段标 `skipped`，并打印「下一步：<确切命令>」。
- *
- * ## 工具解析（"先目标树、后自身树"）
- * 每个被调用的脚本按 `<--tree>/<相对路径>` → 本脚本所在树的同名文件 依次解析
- * （`install-argent.mjs` 对 `argent-capabilities.mjs` 用的是同一口径）：
- * 干净机器上先跑一次 `--from-packs` 把目标树铺好，之后所有段都用**目标树自己那份**实现。
- *
- * ## 判据边界（诚实声明；⛔ 不为了让判据变绿而伪造自动化）
- *   · **许可文件必须人工带入**：服务端签发（`issue-license-file.mjs`，需账号/JWT）**不在本命令范围**；
- *     没带 `--license-file` ⇒ 本命令只把机器带到"**只差许可文件**"，且**明确**标"未装许可"。
- *   · **账号登录（OAuth 一键登录）**永远是人工步骤：本命令只做本机文件面，不代点授权。
- *   · **模型凭证真探针**（`check-model-auth.py --online`）要联网 + 真 Key ⇒ 离线演练用安装器既有的
- *     `ARGENT_SKIP_MODEL_PROBE=1` 逃逸阀（安装器自己会打警告，不静默）。
- *   · 在线装配面的第 7 步（插件装入 profile）需要包管理器；本命令**不替它做决定**，只把安装器的输出
- *     原样透传（含 `pnpm` 不可用时的回退与警告）。
- *
- * 退出码：0 各段均 ok（`skipped`/`n-a` 不算失败，但会在结论里点名计数）｜1 有段 `fail`｜2 用法/环境错误。
- */
-import { spawnSync } from 'node:child_process'
-import { createRequire } from 'node:module'
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { dirname, isAbsolute, join, resolve } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import { loadRegistryDoc } from './lib/registry.mjs'   // 注册表唯一入口（⛔ 不直读 base）
-
-const require_ = createRequire(import.meta.url)
-const HERE = dirname(fileURLToPath(import.meta.url))
-/** 本脚本所在树（仓库里 = 仓库根；装机后 = 安装克隆根）。 */
-const SELF_TREE = resolve(HERE, '..')
-
-// ── 参数 ─────────────────────────────────────────────────────────────
-const argv = process.argv.slice(2)
-const argOf = (n, d = null) => { const i = argv.indexOf(n); return i > -1 ? argv[i + 1] ?? d : null }
-const has = (n) => argv.includes(n)
-const STEPS = ['precheck', 'install', 'skills', 'license', 'verify']
-
-if (has('--help') || has('-h')) {
-  console.log(`Argent 干净机器一条命令（薄编排：只串联既有能力，不复制判断）
-
-用法：
-  node scripts/install-one-shot.mjs [选项]            # 默认 dry-run：只打印将执行的命令与判据
-  node scripts/install-one-shot.mjs --apply           # 真执行
-
-选项：
-  --profile <p>              目标 DSH profile（默认 web）
-  --dsh-home <h>             目标 DSH_HOME（默认 $DSH_HOME 或 ~/.dsh）
-  --tree <dir>               Argent 树（默认 $ARGENT_DISH_HOME 或 ~/.argent-dsh，与安装器同口径）
-  --from-packs <s,…>         离线包（目录/tgz/http(s) URL，逗号分隔）⇒ 装配走安装器离线面（不需要 git/网络）
-  --license-file <f>         许可文件（缺 ⇒ license 段 skipped，结论标「未装许可」，**不算失败**）
-  --license-secret-file <f>  许可密钥文件（可选；传给 install-license.mjs）
-  --instance-token-file <f>  实例令牌文件（可选；**机器自带凭证**，与许可一并装 ⇒ 不再依赖 30 天账号令牌）
-  --only <段,…>              只跑这些段（${STEPS.join(' / ')}）
-  --apply                    真执行（缺省 dry-run）
-  --no-provider              装配时跳过模型 provider 配置（透传 --skip-provider）
-  --no-venv                  装配时跳过 Python 运行时（透传 --skip-venv；离线/演练用）
-  --timeout <秒>             单段超时（默认 1800）
-  --json                     结论以 JSON 打印到 stdout（人话输出照常）
-  --report <f>               把结论 JSON 写到文件
-  --help                     本帮助
-
-退出码：0 各段均 ok ｜ 1 有段 fail ｜ 2 用法/环境错误
-`)
-  process.exit(0)
-}
-
-const profile = argOf('--profile') || process.env.DSH_PROFILE || 'web'
-const dshHome = resolve(argOf('--dsh-home') || process.env.DSH_HOME || join(homedir(), '.dsh'))
-const treeArg = argOf('--tree') || process.env.ARGENT_DISH_HOME || process.env.ARGENT_HOME || ''
-// ⚠ 默认值与安装器同口径（~/.argent-dsh）——**绝不**默认指到"本脚本所在树"：
-//   在线面第 2 步会对 <树> 做 `git pull`，若默认指到开发仓库，跑一次安装器就会 pull 开发树。
-const tree = resolve(treeArg || join(homedir(), '.argent-dsh'))
-const fromPacks = argOf('--from-packs') || ''
-const licenseFile = argOf('--license-file') ? resolve(argOf('--license-file')) : ''
-const licenseSecret = argOf('--license-secret-file') ? resolve(argOf('--license-secret-file')) : ''
-const instanceTokenFile = argOf('--instance-token-file') ? resolve(argOf('--instance-token-file')) : ''
-const apply = has('--apply')
-const asJson = has('--json')
-const reportPath = argOf('--report') ? resolve(argOf('--report')) : ''
-const timeoutS = Number(argOf('--timeout') || 1800)
-const noProvider = has('--no-provider')
-const noVenv = has('--no-venv')
-const onlyRaw = argOf('--only')
-const only = onlyRaw ? String(onlyRaw).split(',').map((x) => x.trim()).filter(Boolean) : STEPS.slice()
-for (const s of only) {
-  if (!STEPS.includes(s)) { console.error(`✗ 未知段「${s}」（可选：${STEPS.join(' / ')}）`); process.exit(2) }
-}
-if (!Number.isFinite(timeoutS) || timeoutS <= 0) { console.error('✗ --timeout 必须是正秒数'); process.exit(2) }
-if (licenseSecret && !licenseFile) { console.error('✗ --license-secret-file 必须与 --license-file 一起给'); process.exit(2) }
-if (instanceTokenFile && !licenseFile) { console.error('✗ --instance-token-file 必须与 --license-file 一起给（两者走同一条离线下发链路、且要互相核对归属/设备码）'); process.exit(2) }
-
-/** 工具解析：目标树优先，回落到本脚本所在树（两处都是同一条相对路径）。 */
-const tool = (rel) => {
-  const p = join(tree, rel)
-  return existsSync(p) ? p : join(SELF_TREE, rel)
-}
-/** 该工具是否来自**目标树**（用于结论里说清"用的是哪一份实现"）。 */
-const toolSource = (rel) => (existsSync(join(tree, rel)) ? 'tree' : 'self')
-
-const installer = tool('install-argent.mjs')
-const licenseInstaller = tool(join('scripts', 'install-license.mjs'))
-const upgradeScript = tool(join('scripts', 'argent-upgrade.mjs'))
-const classifierScript = tool(join('scripts', 'check-skill-classification.mjs'))
-const bootcheckScript = tool(join('scripts', 'plugin-bootcheck.mjs'))
-const roleMappingScript = tool(join('scripts', 'check-role-mapping.mjs'))
-const coreCli = tool(join('core', 'cli', 'argent.mjs'))
-
-const dataDir = join(dshHome, 'argent')
-const skillsDst = join(dshHome, 'skills')
-const profileDir = join(dshHome, 'profiles', profile)
-const installJson = join(dataDir, 'install.json')
-
-/** 子进程环境：**只钉 DSH_HOME**，其余继承（ARGENT_DATA_DIR 若在环境里按内核既有优先级链生效）。 */
-const childEnv = { ...process.env, DSH_HOME: dshHome }
-
-// ── 输出 ─────────────────────────────────────────────────────────────
-const useColor = process.stdout.isTTY && !process.env.NO_COLOR
-const c = (n, s) => (useColor ? `\x1b[${n}m${s}\x1b[0m` : s)
-const say = (...m) => console.log(...m)
-const head = (id, title) => say(`\n${c(1, `[${STEPS.indexOf(id) + 1}/${STEPS.length}] ${id}`)} ${title}`)
-const okLine = (t) => say(`  ${c(32, '✅')} ${t}`)
-const warnLine = (t) => say(`  ${c(33, '⚠️')} ${t}`)
-const badLine = (t) => say(`  ${c(31, '✗')} ${t}`)
-const infoLine = (t) => say(`  ${c(90, '·')} ${t}`)
-const cmdLine = (t) => say(`  ${c(36, '▶ 命令')} ${t}`)
-
-const startedAt = Date.now()
-const results = []
-const rec = (id, status, summary, extra = {}) => {
-  const r = { id, status, summary, checks: extra.checks || [], commands: extra.commands || [], error: extra.error || '' }
-  results.push(r)
-  return r
-}
-
-function runCmd(cmd, argsArr, { timeoutMs = timeoutS * 1000, env = childEnv } = {}) {
-  const shown = [cmd, ...argsArr].map((a) => (/[\s"']/.test(a) ? JSON.stringify(a) : a)).join(' ')
-  const r = spawnSync(cmd, argsArr, { env, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 })
-  const out = `${r.stdout || ''}${r.stderr || ''}`
-  const timedOut = r.status === null && !r.error ? true : /ETIMEDOUT/.test(String((r.error && r.error.code) || ''))
-  return { shown, code: r.status === null ? (timedOut ? 124 : 127) : r.status, out, signal: r.signal || '', err: String((r.error && r.error.message) || '') }
-}
-
-/** "下一步"：失败即停时点名该段的**单跑命令**。 */
-function stepNext(id, hint) {
-  say(`\n  ${c(1, '下一步')}：`)
-  say(`    ${c(36, singleRunCmd(id))}`)
-  say(`    ↳ ${hint}`)
-}
-function singleRunCmd(id, { withApply = true } = {}) {
-  const parts = [`node ${join(SELF_TREE, 'scripts', 'install-one-shot.mjs')}`, `--only ${id}`]
-  if (withApply) parts.push('--apply')
-  parts.push(`--profile ${profile}`, `--dsh-home ${dshHome}`)
-  if (treeArg) parts.push(`--tree ${tree}`)
-  if (id === 'install' && fromPacks) parts.push(`--from-packs ${fromPacks}`)
-  if (id === 'license' && licenseFile) parts.push(`--license-file ${licenseFile}`)
-  if (noProvider) parts.push('--no-provider')
-  if (noVenv) parts.push('--no-venv')
-  return parts.join(' ')
-}
-
-/** 数据目录：**唯一判据在内核里** ⇒ 只调 `core/lib/argent-datadir.mjs#resolveDataDir()`，绝不自己拼第二份。 */
-async function effectiveDataDir() {
-  try {
-    const p = tool(join('core', 'lib', 'argent-datadir.mjs'))
-    if (!existsSync(p)) return null
-    const mod = await import(pathToFileURL(p).href)
-    return typeof mod.resolveDataDir === 'function' ? mod.resolveDataDir() : null
-  } catch { return null }
-}
-
-// ── ① precheck ───────────────────────────────────────────────────────
-async function stepPrecheck() {
-  head('precheck', '宿主/树前置检查（只做存在性/版本探测，不做业务判断）')
-  const checks = []
-  const add = (ok, text, extra = {}) => { checks.push({ ok, text, ...extra }); (ok ? okLine : warnLine)(text) }
-  const which = (cmd) => spawnSync('which', [cmd], { encoding: 'utf8' }).status === 0
-
-  const nodeMajor = Number(process.versions.node.split('.')[0])
-  if (nodeMajor < 20) { badLine(`Node.js ${process.version} 过低（需要 ≥ 20）`); checks.push({ ok: false, text: `Node ${process.version} < 20` }) }
-  else add(true, `Node.js ${process.version}（≥ 20）`)
-
-  const hasGit = which('git')
-  add(hasGit, hasGit ? 'git 在位' : '未找到 git（离线装配面不需要；在线装配面需要）')
-  if (which('dsh')) {
-    const v = spawnSync('dsh', ['--version'], { encoding: 'utf8', env: childEnv })
-    add(true, `dsh 在位${v.status === 0 ? `（${String(v.stdout || '').trim().split('\n')[0]}）` : '（版本读不出）'}`)
-  } else {
-    warnLine('未找到宿主（dsh）—— 安装器会**拒绝安装并给指引**（宿主由客户自带；⛔ 不代装）：'
-      + '按 dsh **官方**运行方式准备窗口内版本的宿主后重跑（首选 `npx @deepseek-ai/dsh@<窗口内版本> web`；'
-      + '跑过一次后它的 npx 缓存会被识别为宿主）；⛔ 旧的 --install-host 代装开关已废弃，别再照抄')
-    checks.push({ ok: true, warn: true, text: 'dsh 不在 PATH' })
-  }
-  const pm = ['pnpm', 'npm', 'corepack'].filter(which)
-  infoLine(`包管理器：${pm.length ? pm.join(' / ') : '（都没有）'}——插件装入 profile 由安装器自行决定，本命令不替它做决定`)
-  checks.push({ ok: true, info: true, text: `包管理器 ${pm.join('/') || '无'}` })
-
-  const dd = await effectiveDataDir()
-  infoLine(`目标：profile=${profile}｜DSH_HOME=${dshHome}｜树=${tree}（工具来源：installer=${toolSource('install-argent.mjs')}）`)
-  infoLine(`数据目录：${dd ? `${dd.dir}（判据来源 ${dd.source}${dd.isolated ? '；隔离实例' : ''}）` : `${dataDir}（内核 datadir 模块读不到，按默认拼）`}`)
-
-  const packs = fromPacks.split(',').map((x) => x.trim()).filter(Boolean)
-  if (packs.length) {
-    let bad = 0
-    for (const spec of packs) {
-      if (/^https?:\/\//i.test(spec)) { infoLine(`离线包（URL，装配时下载）：${spec}`); continue }
-      const abs = isAbsolute(spec) ? spec : resolve(spec)
-      if (!existsSync(abs)) { bad++; badLine(`离线包不存在：${abs}`) }
-      else okLine(`离线包：${abs}${statSync(abs).isDirectory() ? '（目录）' : ''}`)
-    }
-    if (bad) checks.push({ ok: false, text: `${bad} 个离线包路径不存在` })
-    infoLine('装配面：**离线**（安装器 --from-packs 分支：不需要 git、不需要联网、不经过包管理器）')
-    if (packs.length > 1) {
-      // 2026-10-09：这里原先写着"多包同装会被 planPackInstall 拦下（缺口㉔）⇒ 建议一次装一个"——
-      // 那是**过期结论**：拦下它的是"计划阶段没豁免注册表投影"这个 bug（同批复核里修掉，判据与
-      // `installPackFiles` 的 ⑤ 共用同一个 `isRegistryProjection()`）。现在多包一起装是**推荐**路径：
-      // 同批发布的包本就该一起装（跨包共用引擎文件必须同版），一起装还能让注册表投影落成并集。
-      infoLine(`给了 ${packs.length} 个离线包：**一起装**（同批发布的包应当同装 —— 跨包共用引擎文件必须同版；`
-        + '`scripts/flow-requirements.json` 是逐能力过滤的投影，落到目标机时按"保留/合并"处理 ⇒ 结果是各投影的并集）')
-      checks.push({ ok: true, text: `多包一起装（${packs.length} 个包同批）` })
-    }
-  } else {
-    const treeOk = existsSync(join(tree, '.git')) || existsSync(installer)
-    add(treeOk, treeOk ? `在线装配面：树已在位（${tree}）` : `树不在位（${tree}）——在线面会 git clone`)
-    infoLine('装配面：**在线**（git clone/更新 → dsh → preset → provider → 插件装入 profile）')
-  }
-
-  if (!existsSync(installer)) { badLine(`找不到安装器：${installer}（--tree 指错了？）`); checks.push({ ok: false, text: `缺 ${installer}` }) }
-  else infoLine(`安装器：${installer}`)
-
-  // 目标可写：**不创建任何目录**（dry-run 必须零写入）——只探"最近的已存在祖先"
-  let writable = true
-  let probe = dshHome
-  while (!existsSync(probe) && dirname(probe) !== probe) probe = dirname(probe)
-  try {
-    const st = statSync(probe)
-    writable = (st.mode & 0o200) !== 0 && spawnSync('test', ['-w', probe]).status === 0
-  } catch { writable = false }
-  add(writable, writable ? `目标可写（最近已存在祖先 ${probe}）` : `目标不可写（最近已存在祖先 ${probe}）`)
-
-  const failed = checks.filter((x) => x.ok === false)
-  const status = failed.length ? 'fail' : 'ok'
-  rec('precheck', status, failed.length ? `${failed.length} 项前置失败` : '前置检查通过', {
-    checks,
-    error: failed.map((f) => f.text).join('；'),
-  })
-  if (failed.length) stepNext('precheck', '修掉上面点名的前置项后重跑本段')
-  return status === 'ok'
-}
-
-// ── ② install ────────────────────────────────────────────────────────
-function stepInstall() {
-  head('install', fromPacks ? 'profile 装配 —— 离线面（--from-packs：不需要 git/网络/包管理器）' : 'profile 装配 —— 在线面（现有 install 流程）')
-  const args = [installer, '--profile', profile, '--dsh-home', dshHome, '--home', tree]
-  if (fromPacks) args.push('--from-packs', fromPacks)
-  if (noProvider || fromPacks) args.push('--skip-provider')
-  if (noVenv || fromPacks) args.push('--skip-venv')
-  args.push('--telemetry-decline')
-  if (fromPacks && !noProvider) infoLine('离线面自动跳过 provider 配置（--skip-provider）与 Python 运行时（--skip-venv）：二者都要联网')
-  const shown = `node ${args.map((a) => (/[\s"']/.test(a) ? JSON.stringify(a) : a)).join(' ')}`
-  cmdLine(shown)
-  const artifact = fromPacks ? installJson : join(profileDir, 'cordis.patch.yml')
-  infoLine(`判据：退出码 0 ∧ ${artifact} 在位`)
-
-  if (!apply) {
-    infoLine('dry-run：未执行（加 --apply 真执行）')
-    rec('install', 'dry-run', 'dry-run：未执行装配', { commands: [shown] })
-    return true
-  }
-  const r = runCmd(process.execPath, args)
-  for (const l of r.out.trim().split('\n').slice(-6)) infoLine(l)
-  const artifactOk = existsSync(artifact)
-  if (r.code === 0 && artifactOk) {
-    okLine(`装配完成：${artifact}`)
-    rec('install', 'ok', fromPacks ? '离线包装配完成（装机清单已写）' : '在线装配完成（profile patch 在位）', { commands: [shown] })
-    return true
-  }
-  badLine(`装配失败：退出码 ${r.code}${r.signal ? `（${r.signal}）` : ''}${artifactOk ? '' : `；产物缺失 ${artifact}`}`)
-  rec('install', 'fail', `退出码 ${r.code}${artifactOk ? '' : ' 且产物缺失'}`, {
-    commands: [shown],
-    error: (r.err || r.out.trim().split('\n').slice(-3).join(' / ')),
-  })
-  stepNext('install', '看上面安装器的最后几行（它自己会点名缺什么、下一步做什么）')
-  return false
-}
-
-// ── ③ skills（只发外发集）─────────────────────────────────────────────
-/**
- * 目标树是「完整树」还是「能力包树（只装了部分能力）」—— 判据（2026-10-09 修）。
- *
- * ⛔ **不能再看 `verticals/<id>/flows.json` 在不在**：能力包 2026-10-09 起**必须**逐字带上它
- * （不带 ⇒ 纯包装机的 `flow_registry.py --json` exit 2，见回归 `tests/install-registry-loadable.test.mjs`），
- * 于是旧判据（"有 flows.json = 完整树"）会把能力包树**误判成完整树** ⇒ 把"未安装的能力"
- * 报成"仓库缺陷"（假红）。
- *
- * 现判据 = **业务线 manifest 声明的能力** 与 **树上注册表声明的能力** 之差：
- * `verticals/<id>/manifest.json` 逐字进包（声明该线**全部**能力），而 base 投影按能力过滤
- * ⇒ 只装了部分能力时，必有一批 manifest 声明的能力不在树上。读不出（无业务线/无注册表/python 不可用）
- * ⇒ 按"能力包树"处理（宁 warn 不 fail：那本来就是**不完整树**的形态）。
- */
-function isPartialPackTree(root) {
-  const vRoot = join(root, 'verticals')
-  const declared = new Set()
-  try {
-    for (const d of readdirSync(vRoot, { withFileTypes: true })) {
-      if (!d.isDirectory()) continue
-      const mf = join(vRoot, d.name, 'manifest.json')
-      if (!existsSync(mf)) continue
-      for (const c of (JSON.parse(readFileSync(mf, 'utf8')).capabilities || [])) {
-        if (c && c.id) declared.add(String(c.id))
-      }
-    }
-  } catch { return true }
-  if (!declared.size) return true
-  try {
-    const doc = loadRegistryDoc({ root })
-    const installed = new Set(Object.keys(doc.capabilities || {}).filter((k) => !k.startsWith('_')))
-    return [...declared].some((c) => !installed.has(c))
-  } catch { return true }
-}
-
-async function stepSkills() {
-  head('skills', '技能同步（只发外发集；内部技能不外发）')
-  if (!existsSync(upgradeScript)) {
-    badLine(`缺 ${upgradeScript}（技能同步的唯一实现在升级器里）`)
-    rec('skills', 'fail', '缺 scripts/argent-upgrade.mjs', { error: upgradeScript })
-    stepNext('skills', '先把树补齐（--from-packs 或 git pull）再重跑本段')
-    return false
-  }
-  infoLine(`判据真源：${classifierScript}（本段调用它的 classify()，⛔ 不写第二份名单）`)
-  const mod = await import(pathToFileURL(upgradeScript).href)
-  const cls = mod.classifySkills({ root: tree })
-  const external = cls.external || []
-  const internal = cls.internal || []
-  infoLine(`外发集：${external.length} 项${external.length ? `（${external.slice(0, 8).join('、')}${external.length > 8 ? ' …' : ''}）` : ''}`)
-  infoLine(`内部集：${internal.length} 项（按设计**不外发**）`)
-  if (!cls.ok) {
-    warnLine(`技能归类门禁不通过（${cls.errors.length} 条）⇒ 外发集仍严格等于业务线声明，照发；未归类目录一个都不发、不删`)
-    for (const e of (cls.errors || []).slice(0, 5)) infoLine(`[${e.rule}] ${e.message}`)
-  }
-  const clsChecks = (cls.errors || []).map((e) => ({ ok: false, warn: true, text: `[${e.rule}] ${e.message}` }))
-  if (!external.length) {
-    // dry-run 里"外发集为空"多半只是因为**装配没跑、目标树还是空的**（真执行时是硬失败）。
-    // ⇒ dry-run 下如实标"判不出"并点名前置，不假红（也不假绿）。
-    if (!apply) {
-      warnLine(`外发集读不出（目标树还没铺：${join(tree, 'verticals')} 不存在或没有 manifest#skills）⇒ dry-run 下判不出，先跑 install 段`)
-      rec('skills', 'n-a', '外发集读不出（dry-run：目标树未铺，先跑 install 段）', { checks: clsChecks, error: '目标树未铺' })
-      return true
-    }
-    badLine(`外发集为空（读不到 ${join(tree, 'verticals')}/*/manifest.json#skills？）—— 不猜名单、不同步`)
-    rec('skills', 'fail', '外发集为空', { error: 'verticals/*/manifest.json#skills 读不到', checks: clsChecks })
-    stepNext('skills', `先跑 node ${classifierScript} 看归类门禁为什么红`)
-    return false
-  }
-  if (!apply) {
-    infoLine(`dry-run：未执行。将把上面 ${external.length} 项从 ${join(tree, 'skills')} 同步到 ${skillsDst}`)
-    rec('skills', 'dry-run', `dry-run：外发集 ${external.length} 项未同步`, { checks: clsChecks })
-    return true
-  }
-  const res = mod.syncSkills({ srcRoot: join(tree, 'skills'), dstRoot: skillsDst, external, internal })
-  for (const name of res.written || []) okLine(`已写入 ${name}`)
-  for (const name of res.synced || []) if (!(res.written || []).includes(name)) infoLine(`内容已一致（幂等跳过）：${name}`)
-  const hostExtra = [...(res.hostInternal || []), ...(res.hostExtra || [])]
-  if (hostExtra.length) warnLine(`宿主技能根多出 ${hostExtra.length} 项（不在外发集；**只报告不删**）：${hostExtra.slice(0, 8).join('、')}`)
-
-  // 「外发集里有、本机树里没有」的判据**分两种树**（不是放宽，是按树的性质给不同结论）：
-  //   · **完整树**（业务线声明的能力**全在**树上）：业务线真源齐全 ⇒ 声明了却没有 SKILL.md
-  //     是**仓库缺陷** ⇒ 判 fail（与 `argent-upgrade.mjs` 同判据，不许在这里变松）；
-  //   · **能力包树**（`--from-packs` 铺的：只装了部分能力）：本机只装了
-  //     部分能力 ⇒ 别家能力的技能本来就该缺席 ⇒ 如实 **warn** 并点名"装对应能力包即可补齐"。
-  const missing = res.missing || []
-  const packTree = isPartialPackTree(tree)
-  let failed = false
-  if (missing.length && !packTree) {
-    failed = true
-    badLine(`源缺 SKILL.md（完整树：声明了却没有 = 仓库缺陷）：${missing.join('、')}`)
-  } else if (missing.length) {
-    warnLine(`外发集里 ${missing.length} 项本机树未提供（能力包树：属**未安装的能力**）：${missing.join('、')}`)
-    infoLine('⇒ 装对应能力包后重跑本段即可补齐；宿主里已有的不会被删')
-  }
-  const syncedOk = (res.synced || []).length - missing.length
-  rec('skills', failed ? 'fail' : 'ok',
-    failed
-      ? `外发集 ${res.synced.length} 项，源缺 ${missing.length} 项`
-      : `技能同步 ${syncedOk}/${external.length} 项已就位（宿主根现有 ${(res.synced || []).length - missing.length} 项；`
-        + `内部 ${internal.length} 项按设计不同步）`
-        + (missing.length ? `；${missing.length} 项属未安装的能力` : ''),
-    { checks: clsChecks, commands: [`node ${upgradeScript} run`], error: failed ? `源缺 ${missing.join('、')}` : '' })
-  if (failed) stepNext('skills', '补齐源技能目录（skills/<名>/SKILL.md）后重跑本段')
-  return !failed
-}
-
-// ── ④ license ────────────────────────────────────────────────────────
-function stepLicense() {
-  head('license', '许可安装')
-  const singleSeg = singleRunCmd('license', { withApply: true })
-  if (!licenseFile) {
-    warnLine('未提供 --license-file ⇒ **未装许可**（不是失败：许可需服务端签发后人工带入）')
-    cmdLine(`（拿到许可文件后单跑本段）${singleSeg.replace('--license-file', '--license-file <服务端签发的许可文件>')}`)
-    rec('license', 'skipped', '未装许可（未提供 --license-file）', {
-      commands: [`node ${licenseInstaller} --file <许可文件> --dsh-home ${dshHome}`],
-    })
-    return true
-  }
-  if (!existsSync(licenseFile)) {
-    badLine(`许可文件不存在：${licenseFile}`)
-    rec('license', 'fail', `许可文件不存在：${licenseFile}`, { error: licenseFile })
-    stepNext('license', '核对 --license-file 路径（服务端签发件）')
-    return false
-  }
-  if (!existsSync(licenseInstaller)) {
-    badLine(`缺 ${licenseInstaller}（许可安装的唯一实现）`)
-    rec('license', 'fail', '缺 scripts/install-license.mjs', { error: licenseInstaller })
-    stepNext('license', '先把树补齐（--from-packs 或 git pull）再重跑本段')
-    return false
-  }
-  const args = [licenseInstaller, '--file', licenseFile, '--json']
-  if (licenseSecret) args.push('--secret-file', licenseSecret)
-  if (instanceTokenFile) args.push('--instance-token-file', instanceTokenFile)
-  if (!apply) args.push('--dry-run')
-  const shown = `node ${args.map((a) => (/[\s"']/.test(a) ? JSON.stringify(a) : a)).join(' ')}`
-  cmdLine(shown)
-  infoLine('判据：退出码 0（＝已装 / 幂等未变）；`regression_refused`、`device_mismatch`、`bad_signature` 等拒绝面一律非零且**不落盘**')
-  const r = runCmd(process.execPath, args)
-  const doc = (() => { try { return JSON.parse(r.out.trim().split('\n').filter((l) => l.trim().startsWith('{')).pop() || '') } catch { return null } })()
-  if (r.code === 0) {
-    const what = !apply ? 'dry-run：验签通过、未落盘' : (doc && doc.unchanged ? '许可与现役一致（幂等未重写）' : '许可已安装')
-    okLine(`许可：${what}${doc && doc.signatureVersion ? `（sigV=${doc.signatureVersion}）` : ''}`)
-    rec('license', apply ? 'ok' : 'dry-run', what, { commands: [shown] })
-    return true
-  }
-  badLine(`许可安装被拒：退出码 ${r.code}${doc && doc.reason ? `（reason=${doc.reason}）` : ''}`)
-  for (const l of r.out.trim().split('\n').slice(-4)) infoLine(l)
-  rec('license', 'fail', `退出码 ${r.code}${doc && doc.reason ? `（${doc.reason}）` : ''}`, {
-    commands: [shown], error: doc && doc.reason ? String(doc.reason) : r.out.trim().split('\n').slice(-2).join(' / '),
-  })
-  stepNext('license', doc && doc.reason === 'device_mismatch'
-    ? '换机场景：加 --rebind（自助重绑，最多 3 次）或让服务端重新签发'
-    : '看上面 install-license 的最后几行（它自己会点名 reason 与修法）')
-  return false
-}
-
-// ── ⑤ verify ─────────────────────────────────────────────────────────
-async function stepVerify() {
-  head('verify', '收尾自检（逐条给判据；前置未满足的一律标 n-a 并点名）')
-  const checks = []
-  const add = (status, text, extra = {}) => {
-    checks.push({ status, text, ...extra })
-    if (status === 'ok') okLine(text); else if (status === 'fail') badLine(text); else warnLine(text)
-  }
-  const cmds = {
-    caps: `node ${installer} --list-capabilities --dsh-home ${dshHome}`,
-    lic: `node ${coreCli} license status`,
-    boot: `node ${bootcheckScript} --profile ${profile}`,
-    role: `node ${roleMappingScript}`,
-  }
-  const commands = Object.values(cmds)
-
-  // dry-run：只点名"将要跑的四条自检 + 各自前置"，不跑（自检里有一条会真起实例，dry-run 不该有副作用）
-  if (!apply) {
-    infoLine('自检四条（dry-run 不执行）：')
-    for (const [k, v] of Object.entries(cmds)) infoLine(`  · ${k}: ${v}`)
-    rec('verify', 'dry-run', 'dry-run：自检未执行', { commands })
-    return true
-  }
-
-  // a2) 装机清单**逐文件账实相符**（离线面唯一强判据；也是 D1 验收要的 install.json 证据）。
-  // 只调 `install-argent.mjs` 落盘时用的**同一个** sha16File 原语，不另写一份哈希口径。
-  if (existsSync(installJson)) {
-    try {
-      const capsLib = await (async () => {
-        const p = tool(join('scripts', 'argent-capabilities.mjs'))
-        return existsSync(p) ? import(pathToFileURL(p).href) : null
-      })()
-      const doc = JSON.parse(readFileSync(installJson, 'utf8'))
-      const caps = doc.capabilities || []
-      const recorded = caps.reduce((n, c) => n + Object.keys(c.files || {}).length, 0)
-      if (!capsLib) add('n-a', `装机清单账实相符未跑：读不到 ${join(tree, 'scripts', 'argent-capabilities.mjs')}`, { command: cmds.caps })
-      else {
-        const bad = []
-        for (const c of caps) {
-          for (const [rel, sha] of Object.entries(c.files || {})) {
-            const got = capsLib.sha16File(join(tree, rel))
-            if (got !== String(sha)) bad.push(`${rel}（${c.id}：记录 ${sha} 实际 ${got === null ? '缺失' : got}）`)
-          }
-        }
-        if (bad.length) { add('fail', `装机清单账实不符：${bad.length}/${recorded} 个文件`, { command: cmds.caps }); for (const b of bad.slice(0, 5)) infoLine(b) }
-        else add('ok', `装机清单账实相符：${caps.length} 个能力 / ${recorded} 个文件逐文件 sha 一致`)
-      }
-    } catch (e) { add('fail', `装机清单比对崩了：${String(e && e.message || e).slice(0, 120)}`, { command: cmds.caps }) }
-  } else {
-    add('n-a', `装机清单不存在：${installJson}`, { precondition: installJson, command: cmds.caps })
-  }
-
-  // b) license status（恒跑）
-  // ⚠️ 退出码语义（2026-10-05 实测）：**许可缺失也是 exit 1**（`denied(missing)`）⇒
-  // 判据必须看**reason**，不能只看退出码 —— 否则"还没装许可"会被误判成自检失败。
-  // 但其它 denied（expired / bad_signature / device_mismatch …）是真问题 ⇒ 判 fail。
-  if (existsSync(coreCli)) {
-    const r = runCmd(process.execPath, [coreCli, 'license', 'status'])
-    const lines = r.out.trim().split('\n')
-    const line = ((lines.find((l) => l.includes('许可状态')) || lines[0] || '').trim().split('许可状态：')[1] || '').trim()
-    const reason = (/denied[（(]([a-z_]+)/.exec(line) || [])[1] || ''
-    if (reason === 'missing') add('n-a', `许可状态：${line}（**未装许可**，不是自检失败 ⇒ 见 license 段）`, { command: cmds.lic })
-    else if (r.code !== 0) add('fail', `license status 退出码 ${r.code}${reason ? `（${reason}）` : ''}：${line}`, { command: cmds.lic })
-    else add('ok', `许可状态：${line}`)
-  } else {
-    add('n-a', `缺 ${coreCli}（树不完整）`, { precondition: coreCli, command: cmds.lic })
-  }
-
-  // c) plugin-bootcheck（前置：profile 能解析宿主依赖图）
-  const scopeInProfile = join(profileDir, 'node_modules', '@deepseek-ai')
-  if (!existsSync(bootcheckScript)) {
-    add('n-a', `缺 ${bootcheckScript}`, { precondition: bootcheckScript, command: cmds.boot })
-  } else if (!existsSync(scopeInProfile)) {
-    add('n-a', `plugin-bootcheck 未跑：profile 里没有 @deepseek-ai 依赖链（${scopeInProfile}）—— 需要包管理器/宿主初始化`, { precondition: scopeInProfile, command: cmds.boot })
-  } else {
-    // plugin-bootcheck 读 REAL_DSH_HOME（不是 DSH_HOME）⇒ 显式钉到目标 home，否则会去看真实 ~/.dsh
-    const r = runCmd(process.execPath, [bootcheckScript, '--profile', profile], {
-      timeoutMs: Math.max(timeoutS, 900) * 1000,
-      env: { ...childEnv, REAL_DSH_HOME: dshHome },
-    })
-    const tail = r.out.trim().split('\n').slice(-3)
-    if (r.code === 0 && /DONE fail=0/.test(r.out)) add('ok', 'plugin-bootcheck：启动冒烟通过（DONE fail=0）')
-    else { add('fail', `plugin-bootcheck 失败（退出码 ${r.code}）`, { command: cmds.boot }); for (const l of tail) infoLine(l) }
-  }
-
-  // d) check-role-mapping（前置：运行时已有 preset）
-  const presetRoot = join(dshHome, '.agent-presets')
-  const hasPresets = existsSync(presetRoot) && readdirSync(presetRoot).length > 0
-  if (!existsSync(roleMappingScript)) {
-    add('n-a', `缺 ${roleMappingScript}`, { precondition: roleMappingScript, command: cmds.role })
-  } else if (!hasPresets) {
-    add('n-a', `check-role-mapping 未跑：运行时还没有 preset（${presetRoot}）—— 角色未落位`, { precondition: presetRoot, command: cmds.role })
-  } else {
-    const r = runCmd(process.execPath, [roleMappingScript])
-    if (r.code === 0) add('ok', 'check-role-mapping：角色映射一致')
-    else { add('fail', `check-role-mapping 退出码 ${r.code}`, { command: cmds.role }); for (const l of r.out.trim().split('\n').slice(-4)) infoLine(l) }
-  }
-
-  const failed = checks.filter((x) => x.status === 'fail')
-  const na = checks.filter((x) => x.status === 'n-a')
-  const okN = checks.filter((x) => x.status === 'ok')
-  if (na.length) warnLine(`自检真跑通过 ${okN.length}/${checks.length}；${na.length} 条**前置未满足未跑**（上面已点名前置与单跑命令）—— 这条结论**不冒充通过**`)
-  rec('verify', failed.length ? 'fail' : 'ok',
-    failed.length ? `${failed.length} 条自检失败` : `自检真跑通过 ${okN.length}/${checks.length}${na.length ? `，${na.length} 条前置未满足未跑` : ''}`,
-    { checks, commands })
-  if (failed.length) stepNext('verify', '按上面点名的那条自检的单跑命令定位（自检红 = 机器还没到可用状态）')
-  return failed.length === 0
-}
-
-// ── 主流程 ───────────────────────────────────────────────────────────
-say('═══════════════════════════════════════════════════')
-say(`  Argent 干净机器一条命令（${STEPS.length} 段：${STEPS.join(' → ')}）`)
-say('═══════════════════════════════════════════════════')
-say(`  模式：${apply ? c(1, 'apply（真执行）') : 'dry-run（只打印将执行的命令与判据；加 --apply 真执行）'}`)
-say(`  目标：profile=${profile}｜DSH_HOME=${dshHome}｜树=${tree}`)
-say(`  装配面：${fromPacks ? `离线包（${fromPacks}；不需要 git/网络）` : '在线（git clone/更新 + dsh + provider + 插件）'}`)
-if (only.length !== STEPS.length) say(`  只跑：${only.join(' / ')}`)
-
-let stopped = false
-const skipped = []
-for (const id of STEPS) {
-  if (!only.includes(id) || stopped) { skipped.push({ id, why: stopped ? '失败即停' : '未选（--only）' }); continue }
-  let cont = true
-  if (id === 'precheck') cont = await stepPrecheck()
-  else if (id === 'install') cont = stepInstall()
-  else if (id === 'skills') cont = await stepSkills()
-  else if (id === 'license') cont = stepLicense()
-  else if (id === 'verify') cont = await stepVerify()
-  if (!cont) stopped = true
-}
-for (const s of skipped) {
-  rec(s.id, 'skipped', s.why === '失败即停' ? '因上段失败而停' : '未选（--only）', {})
-  say(`\n${c(90, `[${s.id}] ⏭ 跳过（${s.why}）`)}`)
-}
-
-// ── 结论 ─────────────────────────────────────────────────────────────
-const byId = Object.fromEntries(results.map((r) => [r.id, r]))
-const st = (id) => (byId[id] || {}).status || 'skipped'
-const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1)
-const verdict = {
-  ok: results.every((r) => r.status !== 'fail'),
-  mode: apply ? 'apply' : 'dry-run',
-  profile, dshHome, tree, dataDir,
-  treeToolsFrom: { installer: toolSource('install-argent.mjs'), license: toolSource(join('scripts', 'install-license.mjs')) },
-  fromPacks: fromPacks || null,
-  elapsedSeconds: Number(elapsed),
-  steps: results,
-  /** 三段判据行（D1 验收要的三行，单独抽出来便于对账）。 */
-  segments: {
-    install: (byId.install || {}).summary || '—',
-    skills: (byId.skills || {}).summary || '—',
-    license: (byId.license || {}).summary || '—',
-  },
-  licenseInstalled: st('license') === 'ok',
-  selfCheck: (byId.verify || {}).summary || '—',
-  humanSteps: [
-    '许可签发（服务端 issue-license-file.mjs，需账号/JWT）——本命令只装已签发的文件',
-    '问述账号 OAuth 一键登录（设置 → Argent）——必须人工点授权',
-  ],
-}
-const mark = (s) => ({ ok: '✅', fail: '✗ ', skipped: '⏭ ', 'n-a': '⚠️ ', 'dry-run': '▷  ' }[s] || '?  ')
-
-say('\n═══════════════════════════════════════════════════')
-say(`  结论（${verdict.mode}｜耗时 ${elapsed}s）`)
-say('═══════════════════════════════════════════════════')
-for (const r of results) say(`  ${mark(r.status)} ${r.id.padEnd(9)}：${r.summary}`)
-say(`\n  三段判据行（D1 验收要看的三行）：`)
-say(`    装配     ：${verdict.segments.install}`)
-say(`    技能同步 ：${verdict.segments.skills}`)
-say(`    许可     ：${verdict.segments.license}`)
-say(`\n  人工步骤（本命令**不代做**）：`)
-for (const h of verdict.humanSteps) say(`    · ${h}`)
-if (!apply) say(`\n  ▷ 这是 dry-run（零写入）。真执行：在同一命令上加 ${c(1, '--apply')}`)
-if (!verdict.ok) {
-  say(`\n  ${c(31, '✗ 没跑完 —— 先修上面点名的段，再按"下一步"里的单跑命令重试。')}`)
-} else if (apply && !verdict.licenseInstalled) {
-  say(`\n  ${c(33, '⚠️ 编排跑通，但结论是「只差人工步骤」：许可未装 + 账号未登录。')}`)
-  say(`     ${c(33, '⇒ 不要把这条结论读成"机器已经可用"。')}`)
-} else if (apply) {
-  say(`\n  ${c(32, '✅ 编排跑通（逐段判据见上）。')}`)
-}
-
-if (reportPath) {
-  try { writeFileSync(reportPath, `${JSON.stringify(verdict, null, 2)}\n`) } catch (e) { warnLine(`报告写不出（${e.message}）：${reportPath}`) }
-}
-if (asJson) console.log(JSON.stringify(verdict, null, 2))
-process.exit(verdict.ok ? 0 : 1)