@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/lib/preset-sync.mjs

@@ -0,0 +1,59 @@
+/**
+ * 运行时 preset 清理（**唯一真源**，纯函数、可离线测试）。
+ *
+ * 由来（2026-09-28 客户机 P3）：客户机 `~/.dsh/.agent-presets/` 里留着 4 个**旧版残留**角色
+ * （argent-lktop-reviewer / argent-ml-seller / argent-vision / argent-whyshu-reviewer），
+ * 它们的 persona 行是 `text:`；0.1.5 的 `dsh-persona` 只认 `prefix:` ⇒ preset 挂载失败
+ * ⇒ **dsh web 起不来**（KeepAlive 下 crash loop）。升级必须顺手把这些残留清掉。
+ *
+ * 判定「这是我们的角色」= 目录里有 `format-version.txt`（安装器写入的标记）；
+ * **用户自建角色没有该文件，一律不碰**。
+ *
+ * ⚠️ 致命边界：若仓库侧清单为空（源目录缺失/为空），绝不能把全部角色当"残留"删光 ——
+ * 所以 `shipped` 为空时本函数**直接返回空结果**。
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 我们安装的角色标记文件。 */
+export const OURS_MARKER = 'format-version.txt'
+
+/**
+ * 列出运行时 preset 里的"自家角色"（带标记文件的目录）。
+ */
+export function ownPresets(presetRoot) {
+  if (!existsSync(presetRoot)) return []
+  return readdirSync(presetRoot).filter((name) => existsSync(join(presetRoot, name, OURS_MARKER)))
+}
+
+/**
+ * 清理「自家标记 + 不在仓库清单」的残留角色（先整体备份，再删）。
+ * @param {object} o
+ * @param {string} o.presetRoot  运行时 preset 根（~/.dsh/.agent-presets）
+ * @param {Iterable<string>} o.shipped 仓库当前提供的角色名（本次同步成功的那些）
+ * @param {string} o.backupDir   备份根（会创建 <backupDir>/stale-presets-<stamp>/）
+ * @param {string} [o.stamp]     备份目录时间戳（测试可注入，保证可断言）
+ * @param {(s: string) => void} [o.log]
+ * @returns {{ stale: string[], backup: string|null, skipped: boolean }}
+ */
+export function pruneStalePresets({ presetRoot, shipped, backupDir, stamp, log = () => {} }) {
+  const keep = new Set(shipped)
+  if (keep.size === 0) {
+    return { stale: [], backup: null, skipped: true } // 保险：清单为空 ⇒ 什么都不做
+  }
+  const stale = ownPresets(presetRoot).filter((name) => !keep.has(name))
+  if (stale.length === 0) return { stale: [], backup: null, skipped: false }
+
+  let backup = null
+  const ts = stamp || new Date().toISOString().replace(/[:.]/g, '-')
+  try {
+    backup = join(backupDir, `stale-presets-${ts}`)
+    mkdirSync(backup, { recursive: true })
+    for (const name of stale) cpSync(join(presetRoot, name), join(backup, name), { recursive: true })
+  } catch { backup = null } // 备份失败不阻断，但如实返回 null 供调用方告警
+  for (const name of stale) {
+    rmSync(join(presetRoot, name), { recursive: true, force: true })
+    log(`  旧版残留角色已删：${name}`)
+  }
+  return { stale, backup, skipped: false }
+}

package/engine/scripts/lib/profile-retire.mjs

@@ -0,0 +1,97 @@
+/**
+ * profile 插件收敛（**唯一真源**：悬挂插件依赖 / 退役插件副本）。
+ *
+ * 由来（2026-09-28 客户机 P3 实测）：升级器的 syncPlugins 只**复制目标插件**，从不清理
+ * 已消失的 ⇒ 客户机 `~/.dsh/profiles/web/node_modules/` 里躺着 argent-files 等 9 个
+ * 旧副本，`package.json` 的 `file:` 依赖还指着**已从仓库删除**的插件目录 ⇒
+ * profile-doctor 报 `dep-missing-unfixable` ⇒ 重启前门禁不通过 ⇒ 升级卡死无法重启。
+ *
+ * ⚠️ 收敛判据是「**悬挂**」（依赖/副本指向的源码已不存在），**不是**「不在目标组合里」——
+ * 后者会把活着的插件误删（本机 `argent-flow` 不在 business 组合里但在用；客户机
+ * `argent-ml` 同理）。宁可少删，也不许把能跑的东西删掉。
+ *
+ * 规则：
+ *  - 只看 `argent-*`（dsh 官方包一概不碰）；
+ *  - `*-bak-*` 一律不动（人工排障留的现场）；
+ *  - 副本：不在目标组合 **且** 规范根里找不到源码 ⇒ 删；
+ *  - 依赖：`file:` 目标不存在 ⇒ 摘（这是 doctor 报 dep-missing 的直接原因）；
+ *  - 改前备份 package.json，无改动时**字节级不动**。
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { isAbsolute, join, resolve } from 'node:path'
+
+/** 判断某个插件名的源码是否还在（规范根之一里存在同名目录）。 */
+function sourceExists(name, canonicalRoots) {
+  return canonicalRoots.some((root) => {
+    try { return existsSync(join(root, name)) } catch { return false }
+  })
+}
+
+/** 解析依赖值里的本地路径（`file:` 前缀；相对路径按 profileDir 解析）。 */
+function localDepPath(value, profileDir) {
+  const v = String(value || '')
+  if (!v.startsWith('file:')) return null
+  const p = v.slice('file:'.length)
+  return isAbsolute(p) ? p : resolve(profileDir, p)
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.profileNm  profile 的 node_modules 目录
+ * @param {string} o.profileDir profile 根目录（含 package.json）
+ * @param {string[]} o.target   目标组合（保留名单）
+ * @param {string[]} o.canonicalRoots 规范插件根（默认含 <repo>/plugins 的调用方传入）
+ * @param {string} o.backupDir  package.json 备份目录
+ * @param {(s: string) => void} [o.log]
+ * @returns {{ removed: string[], depsDropped: string[], kept: string[], backup: string|null }}
+ */
+export function retirePlugins({ profileNm, profileDir, target, canonicalRoots = [], backupDir, log = () => {} }) {
+  const keep = new Set(target)
+  const removed = []
+  const kept = []
+
+  // ── 1) 悬挂副本：不在组合里，且源码已不存在
+  let entries = []
+  try { entries = readdirSync(profileNm) } catch { return { removed, depsDropped: [], kept, backup: null } }
+  for (const name of entries) {
+    if (!/^argent-/.test(name) || keep.has(name) || /-bak-/.test(name)) continue
+    if (sourceExists(name, canonicalRoots)) { kept.push(name); continue } // 活着的插件：不动
+    rmSync(join(profileNm, name), { recursive: true, force: true })
+    removed.push(name)
+    log(`  悬挂插件副本已删：${name}（规范根里已无源码）`)
+  }
+
+  // ── 2) 悬挂依赖：file: 目标不存在 ⇒ 摘（doctor 的 dep-missing 就报在这里）
+  const pkgPath = join(profileDir, 'package.json')
+  const depsDropped = []
+  let backup = null
+  let pkg = null
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) } catch { pkg = null }
+  if (pkg && pkg.dependencies && typeof pkg.dependencies === 'object') {
+    for (const [dep, value] of Object.entries(pkg.dependencies)) {
+      if (!/^argent-/.test(dep) || keep.has(dep)) continue
+      const local = localDepPath(value, profileDir)
+      const dangling = local ? !existsSync(local) : false
+      if (dangling || (local === null && !sourceExists(dep, canonicalRoots))) {
+        delete pkg.dependencies[dep]
+        depsDropped.push(dep)
+        log(`  悬挂依赖已摘：${dep} → ${value}（目标不存在）`)
+      } else {
+        kept.push(dep)
+      }
+    }
+    if (depsDropped.length) {
+      try {
+        mkdirSync(backupDir, { recursive: true })
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+        backup = join(backupDir, `profile-package.json.${stamp}`)
+        copyFileSync(pkgPath, backup)
+      } catch { backup = null } // 备份失败不阻断，但如实返回 null 供调用方告警
+      const ordered = {}
+      for (const k of Object.keys(pkg.dependencies).sort()) ordered[k] = pkg.dependencies[k]
+      pkg.dependencies = ordered
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8')
+    }
+  }
+  return { removed, depsDropped, kept, backup }
+}

package/engine/scripts/lib/python-runtime.mjs

@@ -0,0 +1,190 @@
+/**
+ * Python 解释器选择（**唯一真源**，纯函数 + 依赖注入 → 可离线测试）。
+ *
+ * 事故（2026-09-28 客户机 P4/P9）：`install-argent.mjs` 的 base python 默认取 PATH 上的
+ * `python3`，**不做版本门禁** ⇒ 客户机（系统 python 3.9.6，而机器上另有 uv 装的 3.11.15）
+ * 上建出 3.9.6 的 venv；更糟的是"就绪"判定只看 `import openpyxl, yaml, PIL, playwright`
+ * 能否通过 —— 3.9.6 装得动这些包 ⇒ 被判"就绪"，**版本不足被完全掩盖**，
+ * 直到客户机预检才以「流程脚本需要 ≥3.10」的形式暴露出来。
+ *
+ * 因此两件事都要修：① 多候选 + 版本门禁地选解释器；② venv"就绪"必须**含版本**。
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+/** 流程引擎要求的最低版本（3.10 起有 match / 结构化模式匹配等）。 */
+export const MIN_PYTHON = [3, 10]
+
+/** "3.9.6" / "3.11.15" → [3,9,6]；解析失败返回 null。 */
+export function parseVersion(text) {
+  const m = /(\d+)\.(\d+)(?:\.(\d+))?/.exec(String(text || ''))
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3] || 0)] : null
+}
+
+/** a ≥ b（逐段比较）。 */
+export function versionAtLeast(a, b) {
+  if (!a || !b) return false
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const x = a[i] || 0
+    const y = b[i] || 0
+    if (x > y) return true
+    if (x < y) return false
+  }
+  return true
+}
+
+/**
+ * venv 的**平台布局**（唯一真源，P0-③ 2026-10-08）。
+ *
+ * POSIX：`<venv>/bin/python3` + `<venv>/bin/pip`；Windows：`<venv>\Scripts\python.exe` + `<venv>\Scripts\pip.exe`。
+ * 此前安装器把 `venv/bin/python3` 写死在四处 ⇒ Windows 上 `spawnSync` 直接 ENOENT
+ * ⇒ `✗ 装 Python 依赖失败` ⇒ `exit 1` **中断整个安装**（provider/插件/装机清单全跑不到），
+ * 而它给用户的手动补救命令 `…\venv\bin\pip install …` 在 Windows 上**根本不存在**（实测现场见
+ * docs/Argent-Windows-安装与HR能力验证-2026-10-08.md §3.3）。
+ *
+ * @param {string} venvDir venv 根目录
+ * @param {{ platform?: string }} [opts] 平台（默认 process.platform；显式传入便于三平台回归）
+ * @returns {{ isWin: boolean, binDir: string, python: string, pip: string, activate: string }}
+ */
+export function venvLayout(venvDir, { platform = process.platform } = {}) {
+  const isWin = platform === 'win32'
+  const binDir = join(venvDir, isWin ? 'Scripts' : 'bin')
+  return {
+    isWin,
+    binDir,
+    python: join(binDir, isWin ? 'python.exe' : 'python3'),
+    pip: join(binDir, isWin ? 'pip.exe' : 'pip'),
+    activate: join(binDir, isWin ? 'activate.bat' : 'activate'),
+  }
+}
+
+/**
+ * 探测某个解释器路径的版本；不可用返回 null。
+ */
+export function probeVersion(bin, run = realRun) {
+  const r = run(bin, ['-c', 'import sys; print("%d.%d.%d" % sys.version_info[:3])'])
+  if (r.status !== 0) return null
+  return parseVersion(r.stdout)
+}
+
+/**
+ * 候选解释器（**按优先级**）：
+ *   显式指定 → PATH 上的版本化名字（3.13…3.10）→ uv 管理的 cpython → PATH 的 python3
+ *   → homebrew / usr-local 常见位置 → 最后才是裸 python3（可能 <3.10，会被门禁拒）。
+ *
+ * Windows（P0-⑦ 2026-10-08）：POSIX 的名字在 Windows 上基本不存在（`python3.12` 没有、
+ *   `python3` 往往是 **Microsoft Store 占位符**，运行即失败/弹商店）⇒ 单列 win32 口径：
+ *   `python`（python.org 安装器的真身）→ C:\Python3xx\ → %LOCALAPPDATA%\Programs\Python\Python3xx\。
+ *   （`py` 启动器需要 `-3` 之类参数，不能用同一个 run(bin, args) 形态，故不收。）
+ */
+export function candidateInterpreters({ explicit = '', env = process.env, home = homedir(), exists = existsSync, listDir = readdirSync, isWin = process.platform === 'win32' } = {}) {
+  const out = []
+  const push = (p) => { if (p && !out.includes(p)) out.push(p) }
+  push(explicit)
+  if (isWin) {
+    push('python')
+    // python.org 安装器的两个默认落点（PATH 里没有 python 时靠它们兜底）
+    const roots = ['C:\\', join(env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'Programs', 'Python')]
+    for (const root of roots) {
+      try {
+        for (const d of listDir(root)) {
+          if (!/^Python3(1[0-9]|[2-9][0-9])/.test(d)) continue
+          const p = join(root, d, 'python.exe')
+          if (exists(p)) push(p)
+        }
+      } catch { /* 没有该目录 */ }
+    }
+    // 少数玩家把 python3.exe 也装了（本机曾手工放一个）——仍作为候选，但排在真身之后
+    push('python3')
+    return out
+  }
+  for (const v of ['3.13', '3.12', '3.11', '3.10']) push(`python${v}`)
+  // uv 管理的解释器（客户机就是这种：~/.local/share/uv/python/cpython-3.11-*/bin/python3.11）
+  const uvRoot = join(home, '.local', 'share', 'uv', 'python')
+  try {
+    for (const d of listDir(uvRoot)) {
+      if (!/^cpython-3\.(1[0-9]|[2-9][0-9])/.test(d)) continue
+      for (const name of ['python3', 'python3.11', 'python3.12', 'python3.13']) {
+        const p = join(uvRoot, d, 'bin', name)
+        if (exists(p)) { push(p); break }
+      }
+    }
+  } catch { /* 没有 uv 目录 */ }
+  push(join(home, 'node', 'bin', 'python3'))
+  push('/opt/homebrew/bin/python3')
+  push('/usr/local/bin/python3')
+  push('python3')
+  return out
+}
+
+/**
+ * 选出**第一个满足 ≥ MIN_PYTHON** 的解释器。
+ * @returns {{ bin: string, version: number[], tried: {bin: string, version: number[]|null}[] } | { bin: null, tried: [] }}
+ */
+export function selectInterpreter({ candidates, run = realRun, min = MIN_PYTHON, explicit = '' }) {
+  const tried = []
+  for (const bin of candidates) {
+    const version = probeVersion(bin, run)
+    tried.push({ bin, version })
+    if (explicit && bin === explicit) {
+      // 显式指定（--python-bin / ARGENT_BASE_PYTHON）必须**要么用上、要么响亮失败** ——
+      // 悄悄换一个别的解释器会让"我明明指定了"变成谎话（2026-09-28 修）。
+      if (version && versionAtLeast(version, min)) return { bin, version, tried }
+      return { bin: null, version, tried, explicitFailed: true }
+    }
+    if (version && versionAtLeast(version, min)) return { bin, version, tried }
+  }
+  return { bin: null, version: null, tried }
+}
+
+/**
+ * 「只需要一个能跑标准库脚本的解释器」时的唯一入口（P0-⑦ 2026-10-08）。
+ *
+ * 用途：安装器/体检脚本要跑 `scripts/capability_pack.py --describe` 这类**纯标准库**脚本 ——
+ * 此前它们硬编码 `python3`，而 Windows 上 `python3` 常是 **Microsoft Store 占位符**（无输出、
+ * 不可用）⇒ 所有能力 `integrity: unverified`、`files` 空（实测现场见
+ * docs/Argent-Windows-安装与HR能力验证-2026-10-08.md §3.5）。仓库**早已有**这套多候选口径，
+ * 只是这几处没用上。
+ *
+ * 语义：① 优先 ≥ MIN_PYTHON 的第一个；② 都达不到版本门禁时，退而取**第一个能跑**的
+ * （只跑标准库脚本的调用方，老解释器也比"占位符"强）；③ 显式指定（ARGENT_PY）不达标 ⇒
+ * 返回空串（"我明明指定了"必须响亮失败，不许悄悄换一个）。
+ * @returns {string} 解释器路径/命令名；找不到返回 ''
+ */
+export function resolveInterpreterPath({ explicit = '', run = realRun, min = MIN_PYTHON, ...candidatesOpts } = {}) {
+  const picked = selectInterpreter({ candidates: candidateInterpreters({ explicit, ...candidatesOpts }), run, min, explicit })
+  if (picked.bin) return picked.bin
+  if (picked.explicitFailed) return ''
+  const runnable = picked.tried.find((t) => t.version)
+  return runnable ? runnable.bin : ''
+}
+
+/** 真实 runner。 */
+export function realRun(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: 30000 })
+  return { status: r.status ?? 1, stdout: `${r.stdout || ''}${r.stderr || ''}` }
+}
+
+/**
+ * venv 是否**真的**可用：版本 ≥ 3.10 **且** 关键依赖可 import。
+ * （只看 import 会把 3.9.6 的 venv 判成就绪 —— 客户机就是这么漏过去的。）
+ *
+ * ⚠️ `pkgs` 必须与安装器的 `pythonRuntimePlan().pkgs` **同一份清单**：这里是
+ * `install-argent.mjs --venv-only`（= `python-runtime.sh ensure`）判"要不要补装"的入口 ——
+ * 清单少了 `selenium`（P0-1，2026-10-08）时，老 venv 会被判"就绪"⇒ ensure 空转 ⇒
+ * 官方推荐的 selenium 档位永远装不上（"开关撒谎"的根因之一）。
+ */
+export function venvUsable(venvPython, { run = realRun, min = MIN_PYTHON, exists = existsSync,
+  pkgs = ['openpyxl', 'yaml', 'PIL', 'playwright', 'selenium'] } = {}) {
+  if (!exists(venvPython)) return { ok: false, reason: 'venv 不存在', version: null }
+  const version = probeVersion(venvPython, run)
+  if (!version) return { ok: false, reason: '解释器不可用', version: null }
+  if (!versionAtLeast(version, min)) {
+    return { ok: false, reason: `版本 ${version.join('.')} < ${min.join('.')}`, version }
+  }
+  const r = run(venvPython, ['-c', `import ${pkgs.join(', ')}`])
+  if (r.status !== 0) return { ok: false, reason: `缺依赖（${pkgs.join('/')}）`, version }
+  return { ok: true, reason: 'ok', version }
+}

package/engine/scripts/lib/registry.mjs

@@ -0,0 +1,72 @@
+/**
+ * registry.mjs —— Node 侧读注册表的**唯一入口**（P2a，2026-09-29）。
+ *
+ * 为什么要有它：注册表已拆成「引擎级 base + 每条业务线一份」，合并/冲突/别名解析都是
+ * `scripts/flow_registry.py` 的职责（唯一真源）。Node 侧**不要自己实现合并**，也不要
+ * 直接读 `scripts/flow-requirements.json`（那会漏掉业务线流程 —— 2026-09-29 P2a 实测：
+ * 分诊/打包/预检多处直读 base，业务线落位后集体"未知流程"）。
+ *
+ * 用法：
+ *   import { loadRegistryDoc, resolveFlowId } from './lib/registry.mjs'
+ *   const doc = loadRegistryDoc()          // 合并后的完整注册表
+ *   resolveFlowId(shortName, doc)          // 短名 → 规范 id `<vertical>.<flow>`
+ */
+import { execFileSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolveInterpreterPath } from './python-runtime.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+export const REPO = join(HERE, '..', '..')
+
+/**
+ * 读合并后的注册表文档。
+ * @param {{root?: string, env?: Record<string,string>, registry?: string, py?: string}} [opts]
+ *   root：仓库根（默认本仓库；测试可指向夹具）
+ *   registry：显式单文件（保持"传注册表路径"的历史语义）
+ *   py：解释器路径。**内核侧（`core/`）必须传已选定的解释器** ——
+ *       否则"没有 PATH python3、但有 venv"的机器读不到注册表（2026-10-03 D3 同源问题）。
+ *       缺省走共享多候选（见下）；`ARGENT_PY` 显式指定时最优先。
+ */
+export function loadRegistryDoc(opts = {}) {
+  const root = opts.root || REPO
+  // P0-⑦ 同源（2026-10-08 实机）：裸 `python3` 在 Windows 上通常是 **Microsoft Store 占位符**
+  // （exit 9009）⇒ `execFileSync` 抛错 ⇒ 读不到注册表 ⇒ `argent-catalog.mjs` / 能力页 / 任何
+  // `JSON.parse(stdout)` 的调用方全挂。这里与 describeCapability 同一口径：多候选 + 版本门禁
+  // （`ARGENT_PY` 仍最优先，最后才退到旧的裸 `python3`）。
+  const py = opts.py || process.env.ARGENT_PY || resolveInterpreterPath({}) || 'python3'
+  const args = [join(root, 'scripts', 'flow_registry.py'), '--json']
+  if (opts.registry) args.push('--registry', opts.registry)
+  const out = execFileSync(py, args, {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    env: { ...process.env, ARGENT_REGISTRY_ROOT: root, ...(opts.env || {}) },
+  })
+  return JSON.parse(out)
+}
+
+/** 别名 → 规范 flow id（无别名时原样返回）。 */
+export function resolveFlowId(flowId, doc) {
+  return ((doc && doc.aliases) || {})[flowId] || flowId
+}
+
+/** 取单条 flow（自动做别名解析）；不存在返回 undefined。 */
+export function flowSpec(flowId, doc) {
+  const d = doc || loadRegistryDoc()
+  return (d.flows || {})[resolveFlowId(flowId, d)]
+}
+
+/**
+ * 取某条流程的**宿主排程声明**（`trigger.schedule`，P1-A 2026-10-12）；未声明返回 `null`。
+ *
+ * 为什么单独给一个取值函数：排程声明的读取方有三个（`scripts/argent-schedule.mjs`、
+ * `scripts/check-production-home.mjs` 的排程面体检、`scripts/argent-doctor.mjs`），
+ * 而"声明在哪儿"（`trigger.schedule`，别名解析后）是**一件**事实 ⇒ 只在这一个地方说一次。
+ * ⚠️ 本函数**不做任何合并/校验**：合并仍是 `flow_registry.py` 的职责；校验是
+ * `vertical-lint.mjs`（装配期）与 `flow_config.py`（运行期）的职责（两边同一套判据）。
+ */
+export function flowSchedule(flowId, doc) {
+  const spec = flowSpec(flowId, doc)
+  const s = spec && spec.trigger && spec.trigger.schedule
+  return s && typeof s === 'object' ? s : null
+}

package/engine/scripts/lib/repo-root.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# 仓库根解析（**唯一真源**，供各脚本 source）。
+#
+# 由来（2026-09-28 客户机实测）：一批脚本把仓库路径默认写成 `$HOME/Code/argent-dsh`
+# （开发机的克隆位置），而客户机的克隆在 `~/.argent-dsh` ⇒ plist 指向不存在的脚本、
+# agent 每 180s 静默 127，探测脚本也找不到 `$REPO/scripts/*.py`。
+#
+# 判据顺序：ARGENT_DSH_REPO → **脚本自身位置**（谁装的就在哪，最可靠）→ 常见克隆位置。
+# 用法：
+#   . "$(dirname "${BASH_SOURCE[0]}")/lib/repo-root.sh"
+#   REPO="$(argent_repo_root "${BASH_SOURCE[0]}")"
+argent_repo_root() {
+  local self="${1:-${BASH_SOURCE[0]}}"
+  local self_dir=""
+  [ -n "$self" ] && self_dir="$(cd "$(dirname "$self")/.." 2>/dev/null && pwd)"
+  local c
+  for c in "${ARGENT_DSH_REPO:-}" "$self_dir" "$HOME/.argent-dsh" "$HOME/Code/argent-dsh"; do
+    [ -n "$c" ] || continue
+    # 认一个稳定的仓内文件，避免误认半个目录
+    [ -f "$c/scripts/flow_config.py" ] && { printf '%s' "$c"; return 0; }
+  done
+  printf '%s' "${ARGENT_DSH_REPO:-${self_dir:-$HOME/.argent-dsh}}"
+}
+
+# 生成 launchd 用的 PATH：优先本机真实的 node / lark-cli 目录（launchd 的 PATH 极简）。
+argent_agent_path() {
+  local out="" d p c
+  # ⚠️ 不能写 `dirname "$(command -v node || echo /nonexistent)"` —— 找不到时
+  # dirname 会给出 `/`，而 `/` 存在 ⇒ PATH 里多一个垃圾根目录（2026-09-28 门禁实测）。
+  for c in node lark-cli; do
+    p="$(command -v "$c" 2>/dev/null || true)"
+    [ -n "$p" ] || continue
+    d="$(dirname "$p")"
+    case ":$out:" in *":$d:"*) continue ;; esac
+    [ -d "$d" ] && out="${out:+$out:}$d"
+  done
+  # 硬编码兜底候选（`command -v` 在 launchd 的极简 PATH 下通常找不到 node，走这里）。
+  #
+  # ⚠️ 2026-10-02（客户机 Huangwei 生产）：这里原本第一项是 `"$HOME/node/bin"` —— 那是
+  # **旧遗留 node 前缀**（客户机 `~/node` = node v24.19.0 + dsh 0.1.5-rc.1），它与现役
+  # `~/.local/node`（v24.21.0 + dsh 0.1.7-rc.2）并存时，生成的 plist PATH 会把**旧 node 排第一**
+  # ⇒ `dsh-web.plist` 与本函数生成 PATH 的**另一个常驻守护 plist** 双双中招，且**只改 plist 会被下次重生成写回**。
+  # 该前缀已移除，并换成**现役前缀 `"$HOME/.local/node/bin"`**（不是简单删掉：删掉后 launchd 下
+  # node 完全不可达 —— 其余候选只剩 ~/.local/bin、/opt/homebrew/bin、系统目录）。
+  # 判据顺序与理由：
+  #   ① PATH 上真实可达的 node / lark-cli 目录（最可靠：谁装的用谁，天然跟着现役前缀走）；
+  #   ② `"$HOME/.local/node/bin"`（现役 node 前缀；与 flow-timers.sh 生成的 4 个 flow-trigger
+  #      plist 首位一致 —— 那 4 个的 PATH 就是 `/Users/huangwei/.local/node/bin:…`）；
+  #   ③ `"$HOME/.local/bin"`（lark-cli 所在；launchd 下 lark-cli 必须可达）；
+  #   ④ `/opt/homebrew/bin`（开发机的 Homebrew node/npm）。
+  for d in "$HOME/.local/node/bin" "$HOME/.local/bin" /opt/homebrew/bin; do
+    case ":$out:" in *":$d:"*) continue ;; esac
+    [ -d "$d" ] && out="${out:+$out:}$d"
+  done
+  printf '%s' "${out:+$out:}/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+}