@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/dsh-snapshot.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * dsh 版本快照生成器（**唯一真源**，替代手工 dump）。
+ *
+ * 快照 = `dsh-version-lock/<目标版本>.json`，记录**该版本实际解析出的子包版本分布**，
+ * 供 `dsh-upgrade.mjs` 用 `overrides` 做确定性、可复现的安装（防 npm caret 漂移）。
+ *
+ * 约定（**照 0.1.1/0.1.5 两份既有快照的实测形态**，别自创）：
+ *   · `target` = 主包版本；`layout` = `flat-scope`（0.1.1+）或 `nested`（rc.6）；
+ *   · `resolved` 的键是**去 scope 的短名**（`dsh`、`dsh-acp`、`cordis`、`cordis-plugin-loader`…），
+ *     因为第 4 步的版本校验按 `node_modules/@deepseek-ai/<目录名>` 比对（目录名就是短名）；
+ *   · 顶层第三方（cordis / cosmokit / …）以同名键一并记录（同样是漂移风险）。
+ *   · ⚠️ **写 overrides 时必须排除主包**（键 `dsh` 或全名 `@deepseek-ai/dsh`）：它是
+ *     `file:<tgz>` 直接依赖，同时 override 会让 npm 报
+ *     `EOVERRIDE ... conflicts with direct dependency`（2026-09-29 实测：升级在"替换全局"
+ *     之前就失败，幸好没动到线上）。
+ *
+ * 用法：
+ *   node scripts/dsh-snapshot.mjs --from-dir /tmp/dsh-snapshot-017 --target 0.1.7-rc.2 [--write|--check]
+ *   node scripts/dsh-snapshot.mjs --from-dir <已装目录>      # 目标版本从主包 package.json 推断
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const REPO = join(dirname(fileURLToPath(import.meta.url)), '..')
+export const LOCK_DIR = join(REPO, 'dsh-version-lock')
+export const MAIN_PKG = '@deepseek-ai/dsh'
+
+/**
+ * 从一个已安装目录收集快照。
+ * @param {string} fromDir 含 `node_modules` 的目录
+ * @returns {{ target: string, layout: string, resolved: Record<string,string> }}
+ */
+export function collectSnapshot(fromDir) {
+  const scope = join(fromDir, 'node_modules', '@deepseek-ai')
+  if (!existsSync(scope)) throw new Error(`缺 node_modules/@deepseek-ai：${scope}`)
+  const resolved = {}
+  for (const dir of readdirSync(scope)) {
+    const pj = join(scope, dir, 'package.json')
+    if (!existsSync(pj)) continue
+    let meta
+    try { meta = JSON.parse(readFileSync(pj, 'utf8')) } catch { continue }
+    // ⚠️ 键用**目录名**（去 scope 短名），与既有快照/第 4 步校验一致；主包照 0.1.5 的形态保留
+    resolved[dir] = meta.version
+  }
+  // 顶层第三方（cordis / cosmokit / schemastery 等）也纳入：它们同样是版本漂移风险
+  const top = join(fromDir, 'node_modules')
+  for (const dir of readdirSync(top)) {
+    if (dir.startsWith('@')) continue
+    const pj = join(top, dir, 'package.json')
+    if (!existsSync(pj)) continue
+    try {
+      const meta = JSON.parse(readFileSync(pj, 'utf8'))
+      if (meta.name && meta.version) resolved[dir] = meta.version
+    } catch { /* 跳过 */ }
+  }
+  const mainPkg = JSON.parse(readFileSync(join(scope, 'dsh', 'package.json'), 'utf8'))
+  const sorted = {}
+  for (const k of Object.keys(resolved).sort()) sorted[k] = resolved[k]
+  return { target: mainPkg.version, layout: 'flat-scope', resolved: sorted }
+}
+
+/** 与既有快照对比（--check 用）：只比 resolved 键值集合。 */
+export function diffSnapshot(a, b) {
+  const keys = new Set([...Object.keys(a.resolved || {}), ...Object.keys(b.resolved || {})])
+  const added = []
+  const removed = []
+  const changed = []
+  for (const k of keys) {
+    const x = (a.resolved || {})[k]
+    const y = (b.resolved || {})[k]
+    if (x === undefined) added.push(`${k}@${y}`)
+    else if (y === undefined) removed.push(`${k}@${x}`)
+    else if (x !== y) changed.push(`${k}: ${x} → ${y}`)
+  }
+  return { added, removed, changed }
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────
+if (process.argv[1] && process.argv[1].endsWith('dsh-snapshot.mjs')) {
+  const argv = process.argv.slice(2)
+  const val = (n, d) => { const i = argv.indexOf(n); return i > -1 ? argv[i + 1] : d }
+  const fromDir = val('--from-dir', '')
+  if (!fromDir) {
+    console.error('用法: node scripts/dsh-snapshot.mjs --from-dir <已装目录> [--target <版本>] [--write|--check]')
+    process.exit(2)
+  }
+  let snap
+  try { snap = collectSnapshot(fromDir) } catch (e) { console.error(`✗ ${e.message}`); process.exit(2) }
+  if (val('--target', '')) snap.target = val('--target')
+  snap.generated = new Date().toISOString().slice(0, 10)
+  if (!('dsh' in snap.resolved)) { console.error('✗ resolved 里应有主包短名 `dsh`（既有快照形态）'); process.exit(2) }
+
+  const outPath = join(LOCK_DIR, 'candidate', `${snap.target}.json`)
+  const body = JSON.stringify(snap, null, 2) + '\n'
+  if (argv.includes('--check')) {
+    if (!existsSync(outPath)) { console.error(`✗ 快照不存在：${outPath}`); process.exit(1) }
+    const cur = JSON.parse(readFileSync(outPath, 'utf8'))
+    const d = diffSnapshot(cur, snap)
+    if (d.added.length || d.removed.length || d.changed.length) {
+      console.error(`✗ 快照与实测不一致：新增 ${d.added.length} / 消失 ${d.removed.length} / 变化 ${d.changed.length}`)
+      for (const x of [...d.added.slice(0, 5), ...d.removed.slice(0, 5), ...d.changed.slice(0, 5)]) console.error(`    · ${x}`)
+      process.exit(1)
+    }
+    console.log(`✅ 快照与实测一致（${snap.target}，${Object.keys(snap.resolved).length} 项）`)
+    process.exit(0)
+  }
+  if (argv.includes('--write')) {
+    mkdirSync(dirname(outPath), { recursive: true })
+    writeFileSync(outPath, body, 'utf8')
+    console.log(`✅ 快照已写 ${outPath.replace(REPO + '/', '')}（${Object.keys(snap.resolved).length} 项，主包 dsh=${snap.resolved.dsh || '?'}）`)
+    process.exit(0)
+  }
+  console.log(body)
+}

package/engine/scripts/dsh-upgrade-readiness.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * dsh-upgrade-readiness —— 升级前的**就绪检查（go / no-go）**（P5→P6，2026-09-29）
+ *
+ * 为什么要有它：升级要安全，靠的是一串**散落的部件**同时成立 ——
+ *   目标版本快照、当前整树备份、默认入口指针、熔断与还原脚本、以及在目标树上跑过的门禁。
+ *   少任何一件，"升级崩了"就退化成"只能找人修"（今天两次现场都是这个形态）。
+ *   本脚本只读地把这些部件串起来，给出**一条 go/no-go + 下一步命令**。
+ *
+ * 判据（每条都有出处，不猜）：
+ *   ① 目标版本有快照（`dsh-version-lock/` 或 `candidate/`）；
+ *   ② 当前运行的版本有**整树备份**（回滚的物理前提）；
+ *   ③ 默认入口指针工具可用（`scope-pointer` 能写能读）+ 熔断自测通过；
+ *   ④ 入口是否已切到包装脚本（未切则熔断**尚未生效** —— 属人工激活动作）；
+ *   ⑤ 候选树布局合规（必须在 `node_modules/` 下才跑得起来）；
+ *   ⑥ （可选 `--gates`）在**目标树**上跑 `dsh-upgrade --patches-only` 六项门禁。
+ *
+ * 用法：
+ *   node scripts/dsh-upgrade-readiness.mjs [--target 0.1.8] [--json] [--gates]
+ * 退出码：0 = go；1 = no-go（有 ❌）；2 = 参数/环境错误
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dshHome, looksLikeScope, pointerPath, readPointer } from './lib/scope-pointer.mjs'
+import { resolveDshScope } from './lib/dsh-scope.mjs'   // 安装位置唯一真源（禁止写死路径）
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+const argOf = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] ?? d : d }
+const TARGET = argOf('--target', '')
+const AS_JSON = process.argv.includes('--json')
+const RUN_GATES = process.argv.includes('--gates')
+
+const rows = []
+const add = (id, level, msg, fix = '') => rows.push({ id, level, msg, fix })
+
+// ── ① 目标版本快照 ─────────────────────────────────────────────
+const lockRoot = join(REPO, 'dsh-version-lock')
+const verified = existsSync(lockRoot)
+  ? readdirSync(lockRoot).filter((f) => f.endsWith('.json')).map((f) => f.replace(/\.json$/, ''))
+  : []
+const candidates = existsSync(join(lockRoot, 'candidate'))
+  ? readdirSync(join(lockRoot, 'candidate')).filter((f) => f.endsWith('.json')).map((f) => f.replace(/\.json$/, ''))
+  : []
+if (!TARGET) {
+  add('target', 'info', `未指定 --target；已验证快照：${verified.join(', ') || '(无)'}；候选：${candidates.join(', ') || '(无)'}`,
+    '升级演练请显式给 --target <版本>（例如 --target 0.1.8）')
+} else if (verified.includes(TARGET) || candidates.includes(TARGET)) {
+  add('target', 'ok', `目标 ${TARGET} 有快照（${verified.includes(TARGET) ? '已验证' : '候选'}）`)
+} else {
+  add('target', 'fail', `目标 ${TARGET} **没有快照** —— 升级脚本要求快照锁定（否则无法校验子包版本分布）`,
+    '先装一份目标版本到临时目录，再生成快照（接口是 --from-dir/--target/--write，' +
+      '**没有** --version —— 别照抄旧写法）：\n' +
+      `      node scripts/dsh-snapshot.mjs --from-dir <已装目录> --target ${TARGET} --write`)
+}
+
+// ── ② 当前版本的整树备份（回滚的物理前提）──────────────────────
+const backupRoot = join(dshHome(), 'argent', 'backup')
+const backups = existsSync(backupRoot)
+  ? readdirSync(backupRoot).filter((d) => existsSync(join(backupRoot, d, 'scope', 'dsh', 'lib', 'bin.js')))
+  : []
+let running = ''
+try {
+  running = execFileSync('dsh', ['--version'], { encoding: 'utf8' }).trim().split('\n').pop().trim()
+} catch { running = '' }
+add('running', running ? 'ok' : 'warn', running ? `当前默认入口版本：${running}` : '取不到当前 dsh 版本（dsh 不在 PATH？）',
+  running ? '' : '确认 PATH 或先修默认入口（scripts/dsh-restore.sh --list）')
+const runningBackup = backups.find((d) => d.includes(running.replace(/^v/, '')))
+if (runningBackup) add('backup', 'ok', `当前版本有整树备份：${runningBackup}（回滚可用）`)
+else if (backups.length) add('backup', 'warn', `有 ${backups.length} 份整树备份，但没有一份标注当前版本（${running || '未知'}）`,
+  `升级前先备份当前树：见 docs/客户机升级与生产切换-2026-09-28.md 的回滚章节`)
+else add('backup', 'fail', '**没有整树备份** —— 升级失败就没有物理回滚点',
+  `先备份：mkdir -p ${backupRoot}/dsh-<版本>-<日期> && cp -R <全局 scope> 该目录/scope`)
+
+// ── ③ 指针与熔断工具自测 ───────────────────────────────────────
+// 0.6.0 F1 修复批（2026-10-14）：scope 是**可选增强**（本步只加一条体检行）⇒ 探不到**降级但不静默**：
+// 把"探不到"如实报成 `warn` + **打印原因**（⛔ 不用假路径去跑 `looksLikeScope()` —— 那会报
+// "布局不合规"，把"没有宿主树"误诊成"树坏了"）。
+const _scopeHit = resolveDshScope()
+if (!_scopeHit || _scopeHit.stale) {
+  add('scope-layout', 'warn',
+    _scopeHit
+      ? `探到的 scope 是**空壳**（${_scopeHit.scope}：目录在、里面没有 dsh 包）—— 无法判布局`
+      : '⛔ 探不到任何宿主 scope（可能是 **npx 形态**：`npx @deepseek-ai/dsh web` 的树在 `~/.npm/_npx/<hash>/node_modules/@deepseek-ai`）',
+    '用 `--scope-dir <…/@deepseek-ai>` / `DSH_SCOPE=<…>` / `--global-bin <该 scope 自带的 dsh>` 之一显式指定')
+} else {
+  const globalScope = _scopeHit.scope
+  add('scope-layout', looksLikeScope(globalScope) ? 'ok' : 'fail',
+    looksLikeScope(globalScope) ? `当前默认入口树布局合规（node_modules 下；来源：${_scopeHit.how}）` : `默认入口树布局不合规：${globalScope}`,
+    looksLikeScope(globalScope) ? '' : '树必须在 <root>/lib/node_modules/@deepseek-ai 下才能跑（裸包名解析）')
+}
+const ptr = readPointer()
+add('pointer', ptr ? 'ok' : 'warn',
+  ptr ? `指针已设置：${ptr}` : `指针未设置（${pointerPath()}）—— 熔断与还原依赖它`,
+  ptr ? '' : '激活步骤（人工）：bash scripts/dsh-restore.sh --to <当前树> --no-reload')
+let fuseOk = false
+try {
+  const out = execFileSync('node', [join(HERE, 'tests', 'scope-pointer.test.mjs')], { encoding: 'utf8' })
+  fuseOk = /16 通过 \/ 0 失败/.test(out)
+} catch { fuseOk = false }
+add('fuse-selftest', fuseOk ? 'ok' : 'fail', fuseOk ? '熔断/指针自测通过（16 项）' : '熔断/指针自测**未通过**',
+  fuseOk ? '' : 'node scripts/tests/scope-pointer.test.mjs 看详情（升级前必须绿）')
+
+// ── ④ 入口是否已切到包装脚本（熔断生效的前提）───────────────────
+const plist = join(homedir(), 'Library', 'LaunchAgents', 'com.whyshu.dsh-web.plist')
+let plistPointsWrapper = false
+if (existsSync(plist)) {
+  const txt = readFileSync(plist, 'utf8')
+  plistPointsWrapper = txt.includes('dsh-web-launch')
+  add('launch-entry', plistPointsWrapper ? 'ok' : 'warn',
+    plistPointsWrapper ? 'LaunchAgent 已指向包装脚本（熔断生效）'
+      : 'LaunchAgent 仍直接指向 `dsh`（升级会重建该链接 ⇒ **熔断尚未生效**）',
+    plistPointsWrapper ? '' : '人工激活：把 plist 的 ProgramArguments[0] 改为 node scripts/dsh-web-launch.mjs（或包装 sh），再 launchctl 重载')
+} else {
+  add('launch-entry', 'info', `未找到 LaunchAgent：${plist}`, '客户机上按部署文档确认托管方式')
+}
+
+// ── ⑤ 候选树布局（备份树常犯）────────────────────────────────
+for (const b of backups) {
+  const scope = join(backupRoot, b, 'scope')
+  if (!looksLikeScope(scope)) {
+    add(`backup-layout:${b}`, 'warn', `备份 ${b} 的树**布局不可直接运行**（不在 node_modules 下）`,
+      `当默认入口前先搬家：<root>/lib/node_modules/@deepseek-ai（否则 ERR_MODULE_NOT_FOUND）`)
+  }
+}
+
+// ── ⑥ 可选：在目标树上跑门禁 ───────────────────────────────────
+if (RUN_GATES) {
+  try {
+    const out = execFileSync('node', [join(HERE, 'dsh-upgrade.mjs'), '--patches-only'], { encoding: 'utf8', timeout: 20 * 60 * 1000 })
+    const last = out.trim().split('\n').pop()
+    const green = /六项|全绿|ok=\d+ warn=0/.test(out) && !/⛔/.test(out)
+    add('gates', green ? 'ok' : 'fail', `目标树门禁：${last}`, green ? '' : '按输出逐项修（先别重启/先别激活）')
+  } catch (e) {
+    add('gates', 'fail', `门禁执行失败：${String(e.message).slice(0, 120)}`, 'node scripts/dsh-upgrade.mjs --patches-only')
+  }
+} else {
+  add('gates', 'info', '未跑门禁（加 --gates 会在当前树上跑 --patches-only 六项复核）', '')
+}
+
+// ── 输出 ───────────────────────────────────────────────────────
+const fails = rows.filter((r) => r.level === 'fail')
+const warns = rows.filter((r) => r.level === 'warn')
+const icon = { ok: '✅', warn: '⚠️ ', fail: '❌', info: 'ℹ️ ' }
+if (AS_JSON) {
+  console.log(JSON.stringify({ running, target: TARGET || null, verified, candidates, backups, pointer: ptr, rows, go: fails.length === 0 }, null, 2))
+} else {
+  console.log(`\n【dsh 升级就绪检查】当前 ${running || '?'}${TARGET ? ` → 目标 ${TARGET}` : ''}\n`)
+  for (const r of rows) {
+    console.log(`  ${icon[r.level]} [${r.id}] ${r.msg}`)
+    if (r.fix && r.level !== 'ok' && r.level !== 'info') console.log(`        ↳ ${r.fix}`)
+  }
+  console.log(`\n  结论：${fails.length ? `❌ NO-GO（${fails.length} 项必须先解决）` : warns.length ? `⚠️  GO（有 ${warns.length} 项提醒）` : '✅ GO（全部就绪）'}`)
+  if (!fails.length) {
+    console.log('\n  下一步（升级流程，见评审稿 §6）：')
+    console.log('    ① node scripts/dsh-upgrade.mjs <目标版本> --stage <旁路树>   # 装到旁路，不碰默认入口')
+    console.log('    ② node scripts/dsh-upgrade.mjs --verify <旁路树>            # 门禁 + 隔离冒烟')
+    console.log('    ③ node scripts/dsh-upgrade.mjs --activate <旁路树>          # 改指针（原子）+ 重启一次')
+    console.log('    ④ 验收：新/旧会话可开、13 角色挂载、唤醒链路；异常 ⇒ scripts/dsh-restore.sh --rollback')
+  }
+}
+process.exit(fails.length ? 1 : 0)