@whyshu/argent-engine 0.6.0 → 0.6.1

package/engine/scripts/retire-inventory.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// 0.7.0 W8 只读盘点：把"待退役面"逐类定位（⛔ 只读；不改文件、不动生产、不重启）。
+import { readdirSync, readFileSync, statSync, existsSync, writeFileSync } from 'node:fs'
+import { join, relative, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+const REPO = join(dirname(fileURLToPath(import.meta.url)), '..')
+const SKIP = new Set(['.git', 'node_modules', 'dist', '__pycache__', 'attic', '.venv'])
+function walk(dir, out = []) {
+  for (const e of readdirSync(dir)) {
+    if (SKIP.has(e)) continue
+    const p = join(dir, e); const st = statSync(p)
+    if (st.isDirectory()) walk(p, out)
+    else if (/\.(mjs|js|cjs|py|sh|json|md|plist|ts)$/.test(e) && st.size < 2_000_000) out.push(p)
+  }
+  return out
+}
+const files = walk(REPO)
+const hits = (re, filter = () => true) => files.filter(filter).map((f) => ({ f: relative(REPO, f), n: (readFileSync(f, 'utf8').match(re) || []).length })).filter((x) => x.n > 0).sort((a, b) => b.n - a.n)
+const patches = existsSync(join(REPO, 'scripts/patches')) ? readdirSync(join(REPO, 'scripts/patches')).filter((f) => f.endsWith('.patch')) : []
+const doc = {
+  generatedAt: new Date().toISOString(),
+  面: {
+    '内核补丁（patch 数 / 引用点）': { patches: patches.length, files: hits(/scripts\/patches\//).slice(0, 10) },
+    '旧单文件分发 install-argent.mjs': { files: hits(/install-argent\.mjs/).slice(0, 10) },
+    '写死 ~/.dsh 路径': { files: hits(/~\/\.dsh|\.dsh\/argent/, (f) => !f.includes('/docs/') && !f.includes('/patches/')).slice(0, 15) },
+    'launchd 双线（flow-trigger / plist / launchctl）': { files: hits(/flow-trigger|launchctl|LaunchAgents|\.plist/).slice(0, 15) },
+  },
+}
+console.log(JSON.stringify(doc, null, 2))
+if (process.argv.includes('--write')) {
+  const p = join(REPO, 'docs/Argent-0.7.0-退役面盘点.md')
+  const L = ['# Argent 0.7.0 待退役面盘点（只读生成）', '', `生成时间：${doc.generatedAt}`, '', '> 本文件由 `node scripts/retire-inventory.mjs --write` 生成；⛔ 只读盘点，未改动任何被点名的面。', '']
+  for (const [k, v] of Object.entries(doc.面)) {
+    L.push(`## ${k}`, '')
+    if (v.patches !== undefined) L.push(`- patch 文件数：**${v.patches}**`)
+    for (const x of v.files) L.push(`- \`${x.f}\`（${x.n} 处）`)
+    L.push('')
+  }
+  writeFileSync(p, L.join('\n')); console.log(`\n✅ 已写 ${relative(REPO, p)}`)
+}

package/engine/scripts/run-tests.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据（⛔ 不再写死 ~/.dsh/argent）
 # 全量测试入口（2026-09-30 补：本仓库此前有 123 个测试却无总入口 ⇒ 门禁无法一键复验）
 #
 # 用法：
@@ -20,7 +21,7 @@
 set -uo pipefail
 REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$REPO"
-PY="$HOME/.dsh/argent/venv/bin/python3"; [ -x "$PY" ] || PY=python3
+PY="$ARGENT_DATA_DIR_RESOLVED/venv/bin/python3"; [ -x "$PY" ] || PY=python3
 # 测试期间**绝不发遥测**（2026-09-30：夹具流程 flowA 的失败事件曾被推到生产告警）
 export ARGENT_TELEMETRY_OFF=1
 export ARGENT_TESTS_OFFLINE=1   # 测试期**零网络**（2026-10-11）：监听类用例（dsh-release-watch 等）见到它就**拒绝**真发请求 ⇒ "夹具回归零网络"由开关兜住，不靠自觉

package/engine/scripts/s1-audit.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// 0.7.0 W8/S1 **精确分类器**（只读）：把 `~/.dsh` 字面量分成
+//   A 写入点（改它才影响"数据落哪"，必须改）｜ B 回退候选（只读候选链，按分类保留）｜ C 注释（不动）。
+// 用法：node scripts/s1-audit.mjs [--json] [--only A]
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+const REPO = join(dirname(fileURLToPath(import.meta.url)), '..')
+const SKIP = new Set(['.git', 'node_modules', 'dist', '__pycache__', 'attic', '.venv', 'docs', 'patches', 'tests'])
+const RE = /\.dsh\/argent|~\/\.dsh|\$HOME\/\.dsh|\$\{HOME\}\/\.dsh/
+function walk(dir, out = []) {
+  for (const e of readdirSync(dir)) {
+    if (SKIP.has(e)) continue
+    const p = join(dir, e); const st = statSync(p)
+    if (st.isDirectory()) walk(p, out)
+    else if (/\.(mjs|js|cjs|py|sh)$/.test(e) && st.size < 2_000_000) out.push(p)
+  }
+  return out
+}
+// 去注释：整块块注释、行首 # 或 // 、以及行尾 // 之后的片段（⚠️ 本文件注释里别写那对定界符，会提前闭合）
+function stripComments(src, ext) {
+  let s = src.replace(/\/\*[\s\S]*?\*\//g, '')
+  return s.split('\n').map((line) => {
+    const t = line.trimStart()
+    if (t.startsWith('#') || t.startsWith('*') || t.startsWith('//')) return ''
+    if (ext === '.py' || ext === '.sh') return line.replace(/(^|\s)#.*$/, '')
+    return line.replace(/\/\/.*$/, '')
+  })
+}
+const WRITE = /(=|>>?|mkdir|touch|tee|appendFile|writeFile|Path\(|open\(|log|LOG_DIR|LOGDIR|DATA_DIR|DATA_HOME|PAUSE)/i
+const FALLBACK = /(for\s+\w+\s+in|\|\||-f\s|\$\(.*\|\||candidates?|fallback|候选)/i
+const files = walk(REPO).map((f) => ({ f, ext: f.slice(f.lastIndexOf('.')) }))
+const rows = []
+for (const { f, ext } of files) {
+  const lines = stripComments(readFileSync(f, 'utf8'), ext)
+  const hits = []
+  lines.forEach((line, i) => {
+    if (!RE.test(line)) return
+    const kind = WRITE.test(line) && !FALLBACK.test(line) ? 'A' : FALLBACK.test(line) ? 'B' : 'A?'
+    hits.push({ n: i + 1, kind, text: line.trim().slice(0, 100) })
+  })
+  if (hits.length) rows.push({ file: relative(REPO, f), hits })
+}
+const count = (k) => rows.reduce((n, r) => n + r.hits.filter((h) => h.kind === k).length, 0)
+const doc = { files: rows.length, A: count('A'), 'A?': count('A?'), B: count('B'), rows: rows.sort((a, b) => b.hits.length - a.hits.length) }
+if (process.argv.includes('--writes')) {
+  // 「非赋值写入」口径：redirect / mkdir / touch / `-f` 测试 / 内嵌 open —— 这些同样决定"数据落哪"
+  const W = /(>>?\s*\S*\.dsh\/argent|mkdir[^\n]*\.dsh\/argent|touch[^\n]*\.dsh\/argent|-f\s+"?\S*\.dsh\/argent|open\([^\n]*\.dsh\/argent|\btee\b[^\n]*\.dsh\/argent)/
+  const MSG = /(echo |scp |note\(|\$FIX)/          // 提示语/夹具路径 ⇒ 不算写入
+  const hits = []
+  for (const r of rows) for (const h of r.hits) if (W.test(h.text) && !MSG.test(h.text)) hits.push({ file: r.file, line: h.n, text: h.text })
+  if (process.argv.includes('--json')) { console.log(JSON.stringify({ total: hits.length, hits }, null, 2)); process.exit(0) }
+  console.log(`非赋值写入残留：**${hits.length} 处**（目标 0；白名单外的都算红）`)
+  for (const h of hits.slice(0, 10)) console.log(`  ${h.file}:${h.line}  ${h.text.slice(0, 88)}`)
+  process.exit(0)
+}
+if (process.argv.includes('--assignments')) {
+  // 「只认赋值行」口径：真正决定"数据落哪"的写法（⛔ 不含候选链/提示语/注释）
+  const ASSIGN = /^\s*(export\s+)?[A-Za-z_][A-Za-z0-9_]*=(.*)$/
+  const out = []
+  for (const r of rows) for (const h of r.hits) if (ASSIGN.test(h.text) && RE.test(h.text)) out.push({ file: r.file, line: h.n, text: h.text })
+  const argentHits = out.filter((h) => /\.dsh\/argent/.test(h.text))
+  const hostHits = out.filter((h) => !/\.dsh\/argent/.test(h.text))
+  if (process.argv.includes('--json')) {
+    console.log(JSON.stringify({ total: out.length, argentDataDir: argentHits.length, hostOwnedDsh: hostHits.length, hits: out }, null, 2))
+    process.exit(0)
+  }
+  // ⚠️ 必须拆分：`~/.dsh/argent`（= **Argent 数据目录**，W8 要退役的）vs 其它 `.dsh`（dsh 自己的 home：
+  //    settings.yaml / profiles/ / .agent-presets ⇒ 属宿主，不归 Argent 管）
+  const argent = argentHits, hostOwn = hostHits   // 与 --json 同源，⛔ 不写两遍拆分
+  if (process.argv.includes('--json')) { console.log(JSON.stringify({ total: out.length, argentDataDir: argent.length, hostOwnedDsh: hostOwn.length, hits: out }, null, 2)); process.exit(0) }
+  console.log(`赋值行字面量残留：**${out.length} 处**，其中 Argent 数据目录 \`~/.dsh/argent\` **${argent.length} 处**（W8 目标 = 0）`)
+  console.log(`  另 ${hostOwn.length} 处是 **dsh 自己的 home**（settings/profiles/presets）⇒ 属宿主面，不归 Argent`)
+  for (const h of argent.slice(0, 12)) console.log(`  [argent] ${h.file}:${h.line}  ${h.text.slice(0, 84)}`)
+  process.exit(0)
+}
+if (process.argv.includes('--json')) { console.log(JSON.stringify(doc, null, 2)); process.exit(0) }
+console.log(`非注释字面量：${doc.files} 个文件 ｜ A 写入点 ${doc.A} ｜ A? 待判 ${doc['A?']} ｜ B 回退候选 ${doc.B}`)
+const onlyA = process.argv.includes('--only') && process.argv[process.argv.indexOf('--only') + 1] === 'A'
+for (const r of doc.rows.slice(0, 12)) {
+  const hs = onlyA ? r.hits.filter((h) => h.kind.startsWith('A')) : r.hits
+  if (!hs.length) continue
+  console.log(`  ${r.file}  (${hs.length})`)
+  for (const h of hs.slice(0, 3)) console.log(`      [${h.kind}] L${h.n}: ${h.text}`)
+}

package/engine/scripts/usage-anchor.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据（⛔ 不再写死 ~/.dsh/argent）
 # usage-anchor —— 成本锚点定时器（每天跑一次，把真实模型成本逐日累积下来）。
 #
 # 为什么要有它：定价要以**实跑一段时间的成本**为锚，而不是某一次抽样。这个定时器每天
@@ -22,7 +23,7 @@ pick_py() {
   local c
   # 候选（2026-09-22）：ARGENT_PY → DSH_HOME/argent/venv → ~/.dsh/argent/venv → 仓库 .venv → PATH
   for c in "${ARGENT_PY:-}" "${DSH_HOME:-$HOME/.dsh}/argent/venv/bin/python3" \
-           "$HOME/.dsh/argent/venv/bin/python3" "${REPO:-}/.venv/bin/python3" \
+           "$ARGENT_DATA_DIR_RESOLVED/venv/bin/python3" "${REPO:-}/.venv/bin/python3" \
            "$(command -v python3 2>/dev/null || true)"; do
     [ -n "$c" ] || continue
     [ -x "$c" ] || continue
@@ -42,7 +43,7 @@ LABEL="com.whyshu.usage-anchor"
 AGENTS="$HOME/Library/LaunchAgents"
 PLIST="$AGENTS/$LABEL.plist"
 LOGDIR="${ARGENT_LOG_DIR:-$HOME/Library/Logs/argent}"
-[ -f "$HOME/.dsh/argent/logdir" ] && LOGDIR="$(cat "$HOME/.dsh/argent/logdir")"
+[ -f "$ARGENT_DATA_DIR_RESOLVED/logdir" ] && LOGDIR="$(cat "$ARGENT_DATA_DIR_RESOLVED/logdir")"
 UID_N="$(id -u)"
 
 gen_plist() {

package/engine/scripts/wenyao-browser.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据（⛔ 不再写死 ~/.dsh/argent）
 set -euo pipefail
 # wenyao-browser.sh — 长驻文鳐门户浏览器（登录态可复用，供人工过一次验证 + 自动化复用）
 #
@@ -15,12 +16,12 @@ set -euo pipefail
 # 只读侦察：不导入订单、不导出文件、不改对方任何业务数据。
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-DATA="$HOME/.dsh/argent"
+DATA="$ARGENT_DATA_DIR_RESOLVED"
 PROFILE="$DATA/wenyao-profile"
 PORT="${WENYAO_CDP_PORT:-9333}"
 CHROME="${WENYAO_CHROME:-/Applications/Google Chrome.app/Contents/MacOS/Google Chrome}"
 PROBE="$DATA/wenyao-probe"
-PY="${WENYAO_PY:-$HOME/.dsh/argent/venv/bin/python3}"
+PY="${WENYAO_PY:-$ARGENT_DATA_DIR_RESOLVED/venv/bin/python3}"
 [ -x "$PY" ] || PY="$(command -v python3 || true)"
 URL="$( [ -f "$DATA/wenyao.env" ] && grep -E '^WENYAO_URL=' "$DATA/wenyao.env" | cut -d= -f2- || echo https://my.ffl-tech.com )"
 

package/engine/scripts/wenyao-login.sh

@@ -1,4 +1,5 @@
 #!/bin/bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据
 set -euo pipefail
 # 上海文鳐门户「人工过验证 + 保存登录态」入口（2026-09-10）
 #
@@ -13,7 +14,7 @@ set -euo pipefail
 # 凭据来自 ~/.dsh/argent/wenyao.env（600，不进仓库）。
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PY="${WENYAO_PY:-~/.dsh/argent/venv/bin/python3}"
+PY="${WENYAO_PY:-$ARGENT_DATA_DIR_RESOLVED/venv/bin/python3}"
 if [ ! -x "$PY" ]; then
   PY="$(command -v python3 || true)"
 fi
@@ -26,7 +27,7 @@ if ! "$PY" -c "import playwright" >/dev/null 2>&1; then
   echo "               （可用 WENYAO_PY=/path/to/python3 指定）" >&2
   exit 1
 fi
-if [ ! -f "$HOME/.dsh/argent/wenyao.env" ]; then
+if [ ! -f "$ARGENT_DATA_DIR_RESOLVED/wenyao.env" ]; then
   echo "[wenyao-login] 缺凭据文件 ~/.dsh/argent/wenyao.env（需含 WENYAO_URL/WENYAO_PHONE/WENYAO_PASSWORD，600 权限）" >&2
   exit 1
 fi

package/engine/scripts/ziniao-keepalive.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据（⛔ 不再写死 ~/.dsh/argent）
 # ziniao-keepalive.sh —— 紫鸟**常驻 WebDriver 模式**的守护（W2 部署件）
 #
 # ## 为什么需要
@@ -38,7 +39,7 @@ INTERVAL_SEC="${ZINIAO_KEEPALIVE_INTERVAL_SEC:-180}"
 log() { echo "[$(date '+%F %T')] $*"; }
 pick_py() {
   local c
-  for c in "${ARGENT_PY:-}" "$HOME/.dsh/argent/venv/bin/python3" "$REPO/.venv/bin/python3" \
+  for c in "${ARGENT_PY:-}" "$ARGENT_DATA_DIR_RESOLVED/venv/bin/python3" "$REPO/.venv/bin/python3" \
            "$(command -v python3 2>/dev/null || true)"; do
     [ -n "$c" ] && [ -x "$c" ] && { printf '%s' "$c"; return 0; }
   done

package/engine/scripts/ziniao-post-upgrade-check.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据
 # ziniao-post-upgrade-check.sh —— 紫鸟客户端**升级后**的一键复核（只读 + 幂等；不改业务数据）
 #
 # 背景：2026-09-24 排查"30 天人工登录"，定位到根因 = 客户端 6.26.6.6 太旧（Bridge 没有 /login 路由
@@ -19,7 +20,7 @@ REPO="$(argent_repo_root "${BASH_SOURCE[0]}")"
 # ARGENT_PY → PATH 的 python3 → 默认位置的 venv。
 _DATA_PY="${ARGENT_PY:-$(command -v python3 2>/dev/null || true)}"
 if [ -z "$_DATA_PY" ] || [ ! -x "$_DATA_PY" ]; then
-  _DATA_PY="$HOME/.dsh/argent/venv/bin/python3"
+  _DATA_PY="$ARGENT_DATA_DIR_RESOLVED/venv/bin/python3"
 fi
 DATA="$("$_DATA_PY" "$REPO/scripts/argent-datadir.py" 2>/dev/null || true)"
 if [ -z "$DATA" ]; then

package/engine/scripts/ziniao-windows.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+. "$(dirname "$0")/lib/argent-datadir.sh"   # 0.7.0 W8/S1：数据根唯一判据（⛔ 不再写死 ~/.dsh/argent）
 # ziniao-windows.sh —— 紫鸟**窗口**运维小工具（W5：窗口回收由人显式决定，不自动关）
 #
 # 为什么不做"跑完自动关店"（W5 的原始设想被否）：我们刚修好"每轮 startBrowser = 重启窗口"
@@ -24,7 +25,7 @@ set -uo pipefail
 # （克隆在 ~/.argent-dsh）上找不到本仓文件（2026-09-28 实测）
 . "$(dirname "${BASH_SOURCE[0]}")/lib/repo-root.sh"
 REPO="$(argent_repo_root "${BASH_SOURCE[0]}")"
-PY="${ARGENT_PY:-$HOME/.dsh/argent/venv/bin/python3}"
+PY="${ARGENT_PY:-$ARGENT_DATA_DIR_RESOLVED/venv/bin/python3}"
 [ -x "$PY" ] || PY="$(command -v python3)"
 
 cmd="${1:-list}"; shift || true

package/engine/skills/README.md

@@ -0,0 +1,86 @@
+# Argent 技能目录
+
+本目录存放 Argent 的 DSH 技能（SKILL.md 格式）。运行时落位到 `<dshHome>/skills`
+（preset 零配置挂载 `skill-filesystem` 的默认根，扫描直接子目录）。
+
+## 技能目录谁在管（2026-10-04 按现行代码订正）
+
+**升级器有角色过滤了（= 外发白名单）。** 三个环节的行为各不相同：
+
+| 环节 | 行为 | 证据 |
+|---|---|---|
+| **安装**（`install-argent.mjs`） | **完全不碰技能目录**：只 `mkdirSync` 保证存在，不清理、不新增 | `install-argent.mjs:584-590`（注释「KB-061：不再按角色隔离」「已存在的 `<dshHome>/skills` 与仓库技能目录一律不碰」） |
+| **安装**（`install-dsh.sh`） | 旧 bash 安装器，角色只支持 `general` / `hr-office`；`ml-seller` 分支直接 die（企业级订阅专享） | `install-dsh.sh:26-40` |
+| **升级**（`scripts/argent-upgrade.mjs`） | **只同步外发集**（= `verticals/*/manifest.json#skills` 并集，判据复用 `check-skill-classification.mjs#classify()`）；**内部角色技能（`skills/internal.json`）不同步**；宿主里既有的内部/旧技能**只报告不删**；内容 sha 一致 ⇒ 幂等跳过 | `argent-upgrade.mjs#syncSkills`（2026-10-04 修：客户机实测旧版 `✓ 技能同步: 11 项` = 5 外发 + 6 内部，违反 D5）；回归 `scripts/tests/upgrade-skill-whitelist.test.mjs` |
+| **清理**（`scripts/skill-install.mjs --prune-orphans`） | **人工决策**的收敛动词（默认 dry-run）：只列"将删除（点名）/ 未点名 / 拒绝清理"，真删要 `--apply` **且逐个 `--allow <name>` 点名**；只删四条件同时满足的目录（不在外发集 / 不在 `internal.json` / 不在安装器清单 / 含 `SKILL.md`），**先备份再删** | 见下「收敛宿主里的旧残留」；回归 `scripts/tests/skill-subset.test.mjs`【F】 |
+
+**收敛宿主里的旧残留（客户机实测：6 个内部角色技能 + 12 个旧 hermes 期技能）** —— 升级器**故意不删**，
+所以清理是**人的决定**，命令分两步（`--dir` 写死目标最稳；`~/.dsh/skills` 就是 dsh 宿主的技能根）：
+
+```bash
+# ① 先看清单（缺省 dry-run，零副作用）：哪些会被删、哪些拒绝、为什么
+node ~/Code/argent-dsh/scripts/skill-install.mjs --host dsh --prune-orphans --allow-host-dsh-prune
+# ② 逐个核对名字后**逐个点名**真删（备份到 <dir>/.argent-skills-pruned-<ts>/，审计见 .argent-skills-prune-audit.jsonl）
+node ~/Code/argent-dsh/scripts/skill-install.mjs --host dsh --prune-orphans --allow-host-dsh-prune \
+  --apply --allow hermes-era-skill-01 --allow hermes-era-skill-02
+```
+⚠️ **不该自动清的**：`skills/internal.json` 里的 6 个内部角色技能（宿主上它们是**角色包「已装」的判据**，
+清了角色包状态就对不上）、外发集里那 5 个（归升级器/安装器管）、安装器清单里的（用 `--uninstall`）、
+任何**用户自建**（非技能形态一律拒绝；手写技能与旧残留形态无法区分 ⇒ 只能靠逐个点名 + 人眼核对）。
+
+**结论**：技能一旦在仓库 `skills/` 下，**必须先在两处声明里归类**（外发 or 内部）——外发的会被同步给
+每一个 agent 的技能目录，内部的**不会**；**未归类的目录不会被同步**，但门禁会判红（`G2`）。
+角色级的技能可见性由**网关群级** `chats[<chatId>].skills` 决定
+（`plugins/argent-gateway/src/index.js:628-629` 拼成「【本群启用技能】…」进 prompt），
+角色级 `skills` 字段只是权益回显。**不要把 `ml-daily` / `ml-fulfillment` 当技能目录名**——
+它们是套餐装配档标识，实际目录是 `ml-store-daily-report` / `ml-fulfillment-sop`。
+
+> 历史说明：旧文档写的「角色 → 技能集合（`install-argent.mjs` 的 `ROLE_SKILLS`）」**已无实现**——
+> 该符号在全仓库只剩两处注释提及（`plugins/argent-core/src/index.js:195` 与本文），没有任何代码路径。
+
+## 当前技能清单（11 个目录）—— 并且**分成外发 / 内部两半**
+
+> ⚠️ 2026-10-03（P3）更正：本节原写「9 个目录」，实际 **11**（漏了 `ml-invoice-xzh` / `ml-config-guide`）。
+> 清单**不再手抄**，判据在两处声明里：外发 = `verticals/<id>/manifest.json#skills`（**唯一真源**），
+> 内部 = `skills/internal.json`（逐条带理由）。跑 `node scripts/check-skill-classification.mjs` 看当前分类。
+
+**外发（客户可用的流程技能，5 个）** —— 真源：`verticals/mercadolibre/manifest.json#skills`
+
+- `ml-fulfillment-sop/` —— FULL 货件管理（含 references / scripts / template）
+- `ml-store-daily-report/` —— 美客多店铺日报
+- `ml-invoice/` —— 上海文鳐发票全链路
+- `ml-invoice-xzh/` —— 鑫中航发票全链路（同引擎、不同门户）
+- `ml-config-guide/` —— 配置缺口诊断与引导（替代写死 schema 快照的旧校验）
+
+**内部（不外发的角色技能，6 个）** —— 真源：`skills/internal.json`（含逐条理由）
+
+- `argent-dev/` `pet-dev/` `whyshu-web-dev/` `whyshu-pm/` `lktop-pm/` `lktopapp-dev/`
+  （角色包「已装」的硬判据：`plugins/argent-packs/src/index.js` 以 `~/.dsh/skills/<skill>` 是否存在为准）
+
+⚠️ **往 `skills/` 丢一个新目录 = 必须先归类**：外发（写进业务线声明）才会同步给客户，
+未归类的目录**不会**被同步，但门禁 `G2` 会判红（升级器只发外发集，见上表）⇒ 必须先做一次决定：
+写进业务线声明（外发）或写进 `skills/internal.json`（内部）。
+安装到非 dsh 宿主用 `node scripts/skill-install.mjs --host <dsh|claude-code|codex|cursor> --apply`（只装外发 5 个；**缺省只预演**，真装要 `--apply`）。
+
+## 技能格式
+
+```markdown
+---
+name: <skill-id>
+description: <一句话说明，用于技能目录展示与匹配>
+---
+<技能正文指令>
+```
+
+硬约束（`dsh-skill-filesystem` 的 `parseSkillFile()`）：首行 `---` 且**有闭合 `---`**；
+`name` 必须是**严格小写 kebab-case**且等于目录名（**中文名一律非法**，会被静默丢弃）；
+frontmatter 必须**同时含 `name` 与 `description`**。
+
+改完技能后跑门禁：
+
+```bash
+python3 scripts/fix-skill-frontmatter.py --check          # 格式（闭合 + kebab name + description）
+node scripts/tests/skills-frontmatter.test.mjs
+node scripts/check-skill-classification.mjs               # 归类（外发/内部/未归类即红）
+node scripts/tests/skill-subset.test.mjs                  # 归类 + 外发安装器回归
+```

package/engine/skills/argent-dev/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: argent-dev
+description: Argent开发者角色技能：Argent on DSH 开发知识（安装器/插件/preset/脚本）与 dsh 插件三种角色能力设计。接 whyshu-pm 任务，完成后飞书群 @ 汇报。
+version: 1.0.0
+author: 问述科技 (Whyshu)
+license: MIT
+metadata:
+  argent:
+    role: argent-dev
+    tags: [argent, dsh, cordis, plugin]
+---
+
+# Argent开发者（argent-dev）
+
+## 角色定位
+
+Argent 产品开发者，负责 argent-dsh 仓库（安装器/插件/preset/脚本/skills）与策划文档的落地。
+
+## 核心知识入口
+
+- **Argent 仓库**：`/Users/chester/Code/argent-dsh`（本机开发仓库，远端 whyshu 裸仓库镜像）
+  - `install-argent.mjs`：跨平台安装器（`--role / --dsh-home / --port` 等）
+  - `plugins/`：argent-core / argent-skin / argent-files / argent-ml（cordis 插件）
+  - `presets/`：各角色 Agent Preset（agent.cordis.yml 组合）
+  - `scripts/`：daily-report.mjs / orchestrator.py / feishu-bridge.js 等
+- **策划文档**：`/Users/chester/Code/whyshu/docs/products/argent-*`（含
+  `argent-edition-multi-instance-plan.md` 多实例生态策划案 v0.9）
+- **dsh 插件开发**：三种角色能力设计（Service Definition / Provider / Consumer，
+  参考 deepseek-harness 官方 practice 文档）。
+
+## 协作流
+
+1. whyshu-pm 在飞书群 @ 开发者分配任务并附验收标准（旧看板已退场；新任务机制上线前以此为准）；
+2. 在飞书群/会话中确认验收标准；
+3. 完成后在飞书群 @whyshu-pm 汇报。
+
+## 红线（仓库全局规则）
+
+- **严禁重启本机 dsh web 服务**（LaunchAgent com.whyshu.dsh-web，自杀式重启）；
+- **严禁擅自升级/重装全局 dsh**（锁定 0.1.1-rc.1，快照安装流程）；
+- 客户端插件改动浏览器硬刷新生效；host 端插件改动需用户手动重启服务。

package/engine/skills/internal.json

@@ -0,0 +1,37 @@
+{
+  "_doc": "技能归类清单（P3 / §6.1 D5，2026-10-03）。本文件只列**内部角色技能（不外发）**并逐条写理由。",
+  "_rule": [
+    "① **外发半边不在这里**：外发集 = 所有 `verticals/*/manifest.json#skills` 的并集（今天 = 5 个流程技能）。照抄到这里就是第二份名单 ⇒ 必然漂移，故刻意不抄。",
+    "② 判据（门禁 `scripts/check-skill-classification.mjs`）：`skills/` 下每个含 SKILL.md 的目录必须 ∈ 外发集 ∪ 本清单；**两边都没有 ⇒ 红**（往 skills/ 丢目录 = 默认发给每个客户，因为升级器无角色过滤）。",
+    "③ 本清单的每一条也必须真实存在（过期条目 ⇒ 红），且必须带非空 `reason`。",
+    "④ 只有 `reason`（+ 可选的 `since`）是判据字段；其它键是给人看的。"
+  ],
+  "_why": "客户机形态是『陪跑式』：客户已有自己的 agent，我们只交付**流程技能**。内部角色技能讲的是我方研发/PM/项目知识（安装器、插件、preset、问述官网、云宠乐园、LKTOP 需求分发），发给客户既无用又泄露我方工作方式。",
+  "_source": "docs/Argent-陪跑式交付-实施方案.md §6.1 D5（用户 2026-10-03 批准：外发 5 / 内部 6）",
+  "internal": {
+    "argent-dev": {
+      "reason": "Argent 自身开发知识：安装器 / 插件 / preset / 脚本内部结构 —— 我方研发知识，客户既不需要也涉及实现细节",
+      "since": "2026-09-11"
+    },
+    "whyshu-pm": {
+      "reason": "问述科技 PM 角色流程（策划案接单、飞书群 @ 分发、验收闭环）—— 我方内部工作流",
+      "since": "2026-09-11"
+    },
+    "whyshu-web-dev": {
+      "reason": "问述官网（whyshu.com / Next.js）开发与部署 —— 我方自有资产，与客户业务无关",
+      "since": "2026-09-11"
+    },
+    "pet-dev": {
+      "reason": "云宠乐园项目开发知识 —— 另一个客户/项目的内部资产，与美客多陪跑交付无关",
+      "since": "2026-09-11"
+    },
+    "lktop-pm": {
+      "reason": "LKTOP 需求掌握与任务分发 —— 另一个客户线的内部角色流程",
+      "since": "2026-09-11"
+    },
+    "lktopapp-dev": {
+      "reason": "LKTOP APP（uni-app / 微信小游戏）开发知识 —— 另一个客户线的内部角色流程",
+      "since": "2026-09-11"
+    }
+  }
+}

package/engine/skills/lktop-pm/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: lktop-pm
+description: LKTOPPM角色技能：LKTOP 需求掌握与任务分发（飞书群 @ + 会话），验收闭环。
+version: 1.0.0
+author: 问述科技 (Whyshu)
+license: MIT
+metadata:
+  argent:
+    role: lktop-pm
+    tags: [lktop, pm, task]
+---
+
+# LKTOPPM（lktop-pm）
+
+## 角色定位
+
+LKTOP 项目产品经理：掌握 LKTOP 需求，拆解并分发任务给 LKTOPAPP开发者（lktopapp-dev），验收闭环。
+
+## 核心知识入口
+
+- **LKTOP 需求**：website-next 站点（`/Users/chester/Code/website-next`，LKTOP careers 站，
+  部署技能 website-next-deploy）与 LKTOP 产品文档
+- **任务分发**：lark-task / lark-doc / lark-im
+
+## 协作流
+
+1. 需求拆解 → 在飞书群 @ 开发者派单（必须含：标题、描述、验收标准、优先级、截止时间；旧看板已退场，新任务机制上线前以此为准）；
+2. 分配给 LKTOPAPP开发者（lktopapp-dev）；
+3. 分配完成后飞书群 @lktopapp-dev Bot 通知；
+4. 开发者完成 @ 汇报 → 查看改动与验证 → 在飞书群/会话中确认验收或打回并说明原因；
+5. 用户会在群中直接指正，及时响应。
+
+## 约定
+
+- 任务信息在会话与飞书群保持同步；派单信息完整，避免开发者猜测。

package/engine/skills/lktopapp-dev/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: lktopapp-dev
+description: LKTOPAPP开发者角色技能：LKTOP APP 开发（uni-app / wechat-minigame）+ LKTOP 需求文档。接 lktop-pm 任务，完成后飞书群 @ 汇报。
+version: 1.0.0
+author: 问述科技 (Whyshu)
+license: MIT
+metadata:
+  argent:
+    role: lktopapp-dev
+    tags: [lktop, app, uni-app, minigame]
+---
+
+# LKTOPAPP开发者（lktopapp-dev）
+
+## 角色定位
+
+LKTOP APP 开发者：需求实现、缺陷修复、版本发布。
+
+## 核心知识入口
+
+- **技能**：`uni-app`（跨端应用开发）、`wechat-minigame`（微信小游戏）等
+  （位于本机 `~/.agents/skills/`，由 preset 的 customSkillDirs 装载）
+- **LKTOP 需求文档**：website-next 站点与 LKTOP 产品文档（与 lktop-pm 同源）
+
+## 协作流
+
+1. lktop-pm 在飞书群 @ 开发者分配任务并附验收标准（旧看板已退场；新任务机制上线前以此为准）；
+2. 在飞书群/会话中确认需求与验收标准；
+3. 完成后在飞书群 @lktop-pm 汇报（改动摘要 + 验证结果）。
+
+## 红线
+
+- 发布前核对目标环境与回滚预案；
+- 涉及生产数据/凭据的操作先与用户确认。

package/engine/skills/ml-config-guide/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ml-config-guide
+description: "ML 流程的**配置缺口诊断与引导**：读数据源的实际字段（live schema），对照流程声明的必需字段集，找出缺口并一步步提醒用户补录；替代原先写死 schema 快照的 init-ml.sh 校验。触发：配置缺口、字段缺失、数据源不满足流程、init-ml 校验失败、新客户接入。"
+tags: [配置, 缺口, 分诊, 数据源, schema, 文鳐, 发票]
+---
+
+# ML 流程配置缺口诊断与引导
+
+> 适用：接入新客户 / 新流程，或数据源被运营改动后，**判断某个流程能不能跑、缺什么**。
+> 设计依据：`docs/ml-agent-architecture.md` §5.6（源注册表）、§5.8（live schema + 字段缺口）。
+
+## 为什么不用 `init-ml.sh` 那套写死的校验
+
+旧做法把**某次表结构的快照**（2026-08-13，12 字段）当成期望值，失败时还指引
+`base-bootstrap.sh --force`（**删表重建**）。表结构一演进（如 lip 表已 +6 系统字段），
+它就必然报 diff 并**把用户引向危险操作**。⇒ 改为：**流程声明必需字段** + **每次读 live schema**。
+
+## 三步法（不要跳步）
+
+### 1) 拿事实（薄脚本，不做判断）
+
+```bash
+python3 scripts/ml_schema_check.py --flow wenyao-invoice --profile lip-customer
+#   退出码 0 = 字段齐备 ; 1 = 有缺口 ; 2 = 读不到源/参数错（与"有缺口"区分）
+#   加 --json 供程序消费；离线可用 --fields-from-json <字段名数组>
+```
+
+输出会给出**每个缺口字段的用途**与**应由谁补**（运营 / 我方）。
+
+### 2) 判断与引导（你做）
+
+- **缺运营字段**（品名/材质/重量/尺寸/产品图…）⇒ 告诉用户"**请在表里补 X、Y**"，并说明**为什么需要**；
+  一次只提醒**必要的几项**，不要一次丢 20 条。
+- **缺我方字段**（系统字段清单以 `argent gap` 的输出为准，**别在这里背字段名**）⇒ 走**建字段**流程，
+  但**先经用户确认**（改客户生产表结构属敏感操作）。
+- **⚠️ HS 编码例外**：属**报关敏感 + 人工维护**（决策 2026-08-19）——
+  **系统不预填、不写候选、不自动确认**；缺 HS 只**提示运营补**，且**不得据此推进开票**。
+- **读不到源（退出码 2）** ⇒ **落"源不可读"告警卡**（如 91403 权限不足），**绝不静默跳过**。
+
+### 3) 复验
+
+补完后**再跑一次第 1 步**；齐备（退出码 0）才把该流程的待办交给对应角色
+（文鳐 ⇒ `ml-invoice-wy`），并**在派单/会话里附上本次检查输出**（作为"当时为什么能跑"的证据）。
+
+## 硬性红线
+
+- **不改客户表结构**（建字段必须用户确认）；**不动**运营业务字段（SKU/店铺/数量/装箱数/材质/HS）。
+- **不要**用"旧快照 diff"或 `--force` 重建表；字段口径真源是 `scripts/flow-requirements.json`
+  （由 `scripts/wenyao-template-map.json` 等生成，勿手改生成物）。
+- 新增流程 = **加一条 `flow-requirements.json` 条目** + （如需）源注册表条目，**不改本 SKILL 的判断逻辑**。