@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/local-usage.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+// local-usage.mjs —— 本机**会话级 token 计量**（成本锚点，走官方直连也能测）。
+//
+// ## 为什么需要它
+// 服务端只在**走问述代理**时才有 token 记账。本机（以及"自带 key"的客户机）走官方直连
+// ⇒ 那部分模型成本在服务端**完全不可见**。但 dsh 会把每次模型调用的用量写进会话日志的
+// `assistant/message.data.usage`（`{inputTokens, outputTokens, cacheReadTokens, reasoningTokens}`，
+// 其中 inputTokens 已按适配器约定**扣除**缓存命中）⇒ 直接从磁盘就能算出真实成本。
+//
+// ## 会话日志格式（踩坑记录，别再用现成库重蹈）
+// `~/.dsh/sessions/<workspace-slug>/<session-id>/session.jsonl.zstd` 是**多帧 zstd 顺序拼接**、
+// **没有长度前缀**（实测 frame2 的 magic 紧跟在 frame1 末尾）。
+//   · `zlib.zstdDecompressSync(整个文件)` 只解出**第一帧**（首行 header）⇒ 看起来"没有 usage"；
+//   · `createZstdDecompress()` 流式解码到第二帧直接报 `Unknown frame descriptor`。
+// 正确做法：**扫描 magic(28 b5 2f fd) 切帧，逐帧解压再按行 JSON.parse**（本文件 multizstd()）。
+//
+// ## 输出
+// `~/.dsh/argent/usage/local-requests.jsonl`：`{session, kind, seq, ts, model, input, cacheRead, output,
+// reasoning, total}`，按 `session+seq` 去重、增量追加（状态存 `local-usage-state.json`）。
+// **只记用量，不算钱**——计价统一在 `scripts/usage_report.py`（一份费率表，避免两处漂移）。
+//
+// 用法：
+//   node scripts/local-usage.mjs                 # 增量扫描全部会话
+//   node scripts/local-usage.mjs --all           # 忽略状态，全量重扫
+//   node scripts/local-usage.mjs --json          # 机器可读汇总
+//   node scripts/local-usage.mjs --sessions-root <dir> --out <file> --state <file> --model <name>
+// 退出码：0 正常；1 读盘失败
+
+import { zstdDecompressSync } from 'node:zlib'
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, readdirSync, statSync, existsSync, renameSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { homedir } from 'node:os'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+
+const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd])
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`)
+  return i === -1 ? fallback : process.argv[i + 1]
+}
+const has = (name) => process.argv.includes(`--${name}`)
+
+const DATA = resolveDataDir({ env: process.env }).dir   // 内核三级链（唯一判据）
+const SESSIONS_ROOT = arg('sessions-root', process.env.DSH_SESSIONS_DIR || join(homedir(), '.dsh', 'sessions'))
+const OUT = arg('out', join(DATA, 'usage', 'local-requests.jsonl'))
+const STATE = arg('state', join(DATA, 'usage', 'local-usage-state.json'))
+const MODEL = arg('model', process.env.ARGENT_USAGE_MODEL || 'deepseek-v4-flash')
+const ALL = has('all')
+const JSON_OUT = has('json')
+
+/** 多帧 zstd 顺序拼接 → 逐帧解压 → 行数组。解不开的帧跳过（可能是正在写入的尾帧）。 */
+function multizstd(buf) {
+  const offs = []
+  let i = buf.indexOf(MAGIC)
+  while (i !== -1) { offs.push(i); i = buf.indexOf(MAGIC, i + 1) }
+  offs.push(buf.length)
+  const lines = []
+  let bad = 0
+  for (let k = 0; k < offs.length - 1; k++) {
+    let txt
+    try { txt = zstdDecompressSync(buf.subarray(offs[k], offs[k + 1])).toString('utf8') } catch { bad++; continue }
+    for (const l of txt.split('\n')) if (l.trim()) lines.push(l)
+  }
+  return { lines, frames: offs.length - 1, badFrames: bad }
+}
+
+/**
+ * 流程会话白名单（权威来源，别猜）：
+ *  ① `~/.dsh/argent/flow-dispatch-<flow>.json` 里落盘的 sessionId —— 2026-09-16 起
+ *     `flow-trigger-wake.mjs` 复用同一个会话跑某个流程（不再每轮建会话）；
+ *  ② 旧架构的角色会话 `gw-*`（含其子代理 `<root>~0040<uuid>`）。
+ * 注意：flow 会话是**普通 uuid**，只看"目录名像不像角色"会把全部流程用量误判成对话开销
+ * （2026-09-22 实测：修之前流程侧只剩 09-10 之前的旧数据，本机每票成本算成 0）。
+ */
+function loadFlowSessions() {
+  const ids = new Set()
+  try {
+    for (const f of readdirSync(DATA)) {
+      if (!/^flow-dispatch-.*\.json$/.test(f)) continue
+      try {
+        const j = JSON.parse(readFileSync(join(DATA, f), 'utf8'))
+        if (j?.sessionId) ids.add(String(j.sessionId))
+      } catch { /* 坏文件跳过 */ }
+    }
+  } catch { /* 目录不存在 */ }
+  return ids
+}
+
+const FLOW_SESSIONS = loadFlowSessions()
+
+function kindOf(sessionId, flowIds = FLOW_SESSIONS) {
+  const root = sessionId.split('~0040')[0]
+  if (root.startsWith('gw-')) return 'flow'
+  if (flowIds.has(root)) return 'flow'
+  return 'chat'
+}
+
+function listSessionFiles(root) {
+  const out = []
+  if (!existsSync(root)) return out
+  for (const ws of readdirSync(root)) {
+    const wsDir = join(root, ws)
+    let entries
+    try { entries = readdirSync(wsDir) } catch { continue }
+    for (const sid of entries) {
+      // 会话日志命名随格式版本变化（2026-09 实测）：旧 `session.jsonl.zstd`、
+      // 新 `session.v3.jsonl.zstd`（格式 v3）。写死文件名会让整段用量**静默消失**。
+      let sfiles
+      try { sfiles = readdirSync(join(wsDir, sid)) } catch { continue }
+      for (const name of sfiles) {
+        if (!/^session.*\.jsonl\.zstd$/.test(name)) continue
+        const f = join(wsDir, sid, name)
+        try { if (statSync(f).isFile()) out.push({ session: sid, file: name, path: f, size: statSync(f).size }) } catch { /* 跳过 */ }
+      }
+    }
+  }
+  return out
+}
+
+function loadState() {
+  try { return JSON.parse(readFileSync(STATE, 'utf8')) } catch { return { sessions: {} } }
+}
+
+/**
+ * 已记账键集合（`session#seq`）。
+ * 为什么要它：会话日志**可能同目录两份**（v0→v3 迁移后 `session.jsonl.zstd` 与
+ * `session.v3.jsonl.zstd` 并存，实测 17 个会话如此），而"上次读到哪个 seq"是**按会话**记的
+ * ⇒ 两份文件互相覆盖状态、每轮各读一遍，实测产生 17462 行重复、把成本虚增。
+ * 迁移前后两份日志里的同一事件 seq 相同 ⇒ 按 `session#seq` 去重才是正确语义。
+ */
+function loadSeen(path) {
+  const seen = new Set()
+  try {
+    for (const l of readFileSync(path, 'utf8').split('\n')) {
+      if (!l.trim()) continue
+      try { const r = JSON.parse(l); seen.add(`${r.session}#${r.seq}`) } catch { /* 跳过坏行 */ }
+    }
+  } catch { /* 首次运行没有文件 */ }
+  return seen
+}
+
+function main() {
+  const state = ALL ? { sessions: {} } : loadState()
+  const seen = ALL ? new Set() : loadSeen(OUT)
+  const files = listSessionFiles(SESSIONS_ROOT)
+  if (!files.length) {
+    console.log(`  ⚠️ 未找到会话日志：${SESSIONS_ROOT}`)
+    return 0
+  }
+  mkdirSync(dirname(OUT), { recursive: true })
+  const rows = []
+  let scanned = 0, skipped = 0, badFrames = 0
+  for (const f of files) {
+    const key = `${f.session}::${f.file}`        // 状态按**文件**记（同会话可能两份日志）
+    const last = state.sessions[key] ?? -1
+    // 文件变小 ⇒ 被轮转/重建，从头读
+    const prevSize = state.sessions[`${key}#size`]
+    const from = (prevSize !== undefined && f.size < prevSize) ? -1 : last
+    let buf
+    try { buf = readFileSync(f.path) } catch { skipped++; continue }
+    scanned++
+    let decoded
+    try { decoded = multizstd(buf) } catch { skipped++; continue }
+    badFrames += decoded.badFrames
+    let maxSeq = from
+    for (const line of decoded.lines) {
+      if (!line.includes('"usage"')) continue
+      let e
+      try { e = JSON.parse(line) } catch { continue }
+      if (e?.type !== 'assistant/message' || !e.data?.usage) continue
+      const seq = Number(e.seq ?? -1)
+      if (seq > maxSeq) maxSeq = seq
+      if (seq <= from) continue
+      const skey = `${f.session}#${seq}`
+      if (seen.has(skey)) continue          // 幂等：迁移/重建/重扫都不会重复计费
+      seen.add(skey)
+      const u = e.data.usage
+      const input = Number(u.inputTokens || 0), cacheRead = Number(u.cacheReadTokens || 0)
+      const output = Number(u.outputTokens || 0), reasoning = Number(u.reasoningTokens || 0)
+      rows.push({
+        session: f.session, kind: kindOf(f.session), seq, ts: Math.round(Number(e.time || 0)),
+        model: MODEL, input, cacheRead, output, reasoning,
+        total: input + cacheRead + output + (u.totalTokens !== undefined ? 0 : 0),
+      })
+    }
+    state.sessions[key] = maxSeq
+    state.sessions[`${key}#size`] = f.size
+  }
+  if (rows.length) appendFileSync(OUT, rows.map((r) => JSON.stringify(r)).join('\n') + '\n')
+  mkdirSync(dirname(STATE), { recursive: true })
+  const tmp = `${STATE}.tmp`
+  writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n')
+  renameSync(tmp, STATE)
+
+  const byKind = {}
+  for (const r of rows) {
+    const k = (byKind[r.kind] ||= { requests: 0, input: 0, cacheRead: 0, output: 0 })
+    k.requests++; k.input += r.input; k.cacheRead += r.cacheRead; k.output += r.output
+  }
+  const summary = { sessionsScanned: scanned, sessionsSkipped: skipped, files: files.length,
+    newRequests: rows.length, badFrames, out: OUT, state: STATE, byKind }
+  if (JSON_OUT) console.log(JSON.stringify(summary, null, 2))
+  else {
+    console.log(`  本机计量：新增 ${rows.length} 次请求（扫描 ${scanned}/${files.length} 个会话，坏帧 ${badFrames}）`)
+    for (const [k, v] of Object.entries(byKind)) {
+      console.log(`    ${k === 'flow' ? '流程角色' : '对话会话'}：${v.requests} 次｜输入(未命中) ${v.input.toLocaleString()}`
+        + `｜缓存命中 ${v.cacheRead.toLocaleString()}｜输出 ${v.output.toLocaleString()}`)
+    }
+    console.log(`    → ${OUT}`)
+  }
+  return 0
+}
+
+process.exit(main())

package/engine/scripts/migrate-providers.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * migrate-providers —— 把「劫持官方 provider」的旧配置迁移成**双 provider 并存**（2026-09-30，Argent 0.3）
+ *
+ * ## 迁移什么
+ * 旧形态：`llm-deepseek` 实例（provider id 固定 `deepseek-official`）被配成 `WHYSHU_API_KEY` +
+ * `baseURL: https://whyshu.com/api/argent/v1` ⇒ **官方直连被劫持**。
+ * 新形态：`llm-deepseek` = 真·官方（api.deepseek.com / DEEPSEEK_API_KEY）；
+ *         `llm-whyshu`   = 问述代理（whyshu.com/api/argent/v1 / WHYSHU_API_KEY，provider id `whyshu`）。
+ *
+ * ## 两条路径（**互斥且各自最小改动**）
+ *   ① 劫持 → 重写两段：官方段还原 + 问述段接手；
+ *   ② 未劫持但缺 `llm-whyshu` → **原样保留整份文件**，仅在末尾追加问述段（**绝不重建/剥离任何段**）。
+ *   （早先版本在 ② 里剥段后未回填 ⇒ 会**删掉用户的官方段**，实测夹具抓到；已废弃该写法。）
+ *
+ * ## 幂等 + 安全
+ *   已就绪 ⇒ 什么都不做；改前备份（带时间戳）；改后回读校验非空，失败即从备份恢复。
+ *
+ * 用法：node scripts/migrate-providers.mjs [--dsh-home ~/.dsh] [--profile web] [--dry-run]
+ */
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const arg = (n, d) => { const i = process.argv.indexOf(n); return i > -1 ? process.argv[i + 1] : d }
+const DRY = process.argv.includes('--dry-run')
+// ⛔ 2026-09-30 用户明确要求：**不要动官方 provider**（含它的 baseURL/models）⇒ 本脚本默认**绝不改写
+// `llm-deepseek` 段**，也不重建 settings.yaml；只有显式 `--allow-official-rewrite`（人工确认后）才允许。
+const ALLOW_OFFICIAL = process.argv.includes('--allow-official-rewrite')
+const DSH_HOME = arg('--dsh-home', process.env.DSH_HOME || join(homedir(), '.dsh'))
+const PROFILE = arg('--profile', process.env.DSH_PROFILE || 'web')
+const SETTINGS = join(DSH_HOME, 'settings.yaml')
+const PATCH = join(DSH_HOME, 'profiles', PROFILE, 'cordis.patch.yml')
+const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+const log = (s) => console.log(`  ${s}`)
+
+const OFFICIAL = { baseURL: 'https://api.deepseek.com', apiKeyEnv: 'DEEPSEEK_API_KEY' }
+const WHYS = { baseURL: 'https://whyshu.com/api/argent/v1', apiKeyEnv: 'WHYSHU_API_KEY' }
+// 上下文窗口声明（2026-10-02 修正）：两个 provider **各有各的真实窗口**，不可共用一个数字。
+//   · 问述代理 `WHYSHU_CONTEXT_WINDOW = 131072` —— 上游真实窗口。曾声明 1000000（0.3.0 那次
+//     131072→1000000）⇒ dsh 判定"上下文还很空"、迟迟不压缩 ⇒ 每回合重发的上下文越滚越大 ⇒
+//     回合更长 ⇒ 更容易撞上传输层抖动（`DeepSeek Messages transport failed` / TRANSPORT）。
+//   · 官方直连 —— 取 dsh 官方目录的默认值（`dsh-llm-deepseek` 的 `DEFAULT_CONTEXT_WINDOW = 1e6`），
+//     与"不声明 models 时"的行为保持一致，避免我们自己引入偏差。
+const WHYSHU_CONTEXT_WINDOW = 131072
+const OFFICIAL_CONTEXT_WINDOW = 1000000
+// ⚠️ `maxTokens` 必须与 `contextWindow` **成对**看（2026-10-02 硬约束，别把两者写成同值）：
+// `dsh-compaction-basic` 的 `resolveCompactSpec` 要求
+//   contextWindow - maxTokens > 0  且  上式 - headroomTokens(默认 65536) > 0，
+// 否则抛 TargetPressureConfigError，而它在 `agent/pre-step` 里被 catch ⇒ **只 warn 一次、
+// 此后每步静默跳过压缩**（比不压缩更难发现）。适配器默认 maxTokens = 256000。
+//   · 问述代理：131072 窗 ⇒ maxTokens 必须 < 65536，取 32768（阈值 = 32768）。
+//   · 官方直连：1e6 窗 ⇒ 131072 绰绰有余（阈值 = 800000）。
+const WHYSHU_MAX_TOKENS = 32768
+const OFFICIAL_MAX_TOKENS = 131072
+if (WHYSHU_MAX_TOKENS + 65536 >= WHYSHU_CONTEXT_WINDOW) {
+  throw new Error(`migrate-providers: WHYSHU_MAX_TOKENS(${WHYSHU_MAX_TOKENS}) + headroom(65536) 必须小于 WHYSHU_CONTEXT_WINDOW(${WHYSHU_CONTEXT_WINDOW})，否则 compaction-basic 会静默禁用压缩`)
+}
+const names = { official: { 'deepseek-flash': 'DeepSeek-V4.1-Flash（官方直连）', 'deepseek-v4-pro': 'DeepSeek-V4-Pro（官方直连）' },
+                whyshu: { 'deepseek-flash': 'DeepSeek V4.1 Flash（问述代理）', 'deepseek-v4-pro': 'DeepSeek V4 Pro（问述代理）' } }
+const block = (ids, nameMap, contextWindow = WHYSHU_CONTEXT_WINDOW, maxTokens = WHYSHU_MAX_TOKENS) => ids.map((id) => `    - id: ${id}\n      name: ${nameMap[id]}\n      contextWindow: ${contextWindow}\n      maxTokens: ${maxTokens}`).join('\n')
+
+/** 取顶层段 [start,end)（段 = 一个 `key:` 行 + 其后所有缩进行/空行）。 */
+function section(lines, key) {
+  const start = lines.findIndex((l) => l.trimEnd() === `${key}:`)
+  if (start < 0) return null
+  let end = start + 1
+  while (end < lines.length && /^\s{2,}/.test(lines[end])) end += 1
+  return { start, end, text: lines.slice(start, end).join('\n') }
+}
+
+let text = ''
+try { text = readFileSync(SETTINGS, 'utf8') } catch { text = '' }
+const lines = text.split('\n')
+const off = section(lines, 'llm-deepseek')
+const whys = section(lines, 'llm-whyshu')
+// 劫持判定：**只看 llm-deepseek 段内部**（跨段正则会误判，实测踩过）
+const hijacked = !!off && /whyshu\.com/.test(off.text)
+const offModels = off ? (off.text.match(/  models:\n(?:    [^\n]*\n?)*/) || [''])[0].replace(/^  models:\n/, '') : ''
+
+const wants = []
+if (hijacked && !ALLOW_OFFICIAL) {
+  log('⛔ 检测到 llm-deepseek 指向问述（曾被劫持），但用户要求**不得自动改写官方段** ⇒ 仅报告、不改动。')
+  log('   如需迁移：确认后加 --allow-official-rewrite（会重写官方段为 api.deepseek.com）；否则请手工处理。')
+} else if (hijacked) {
+  const rest = [...lines.slice(0, off.start), ...(whys ? lines.slice(whys.end) : lines.slice(off.end))]
+  const next = `llm-deepseek:\n  baseURL: ${OFFICIAL.baseURL}\n  apiKeyEnv: ${OFFICIAL.apiKeyEnv}\n  models:\n${block(['deepseek-flash', 'deepseek-v4-pro'], names.official, OFFICIAL_CONTEXT_WINDOW, OFFICIAL_MAX_TOKENS)}\n\nllm-whyshu:\n  baseURL: ${WHYS.baseURL}\n  apiKeyEnv: ${WHYS.apiKeyEnv}\n  models:\n${offModels.trimEnd() || block(['deepseek-flash', 'deepseek-v4-pro'], names.whyshu)}\n${rest.join('\n').trim() ? '\n' + rest.join('\n').replace(/^\n+/, '') : ''}`
+  wants.push({ file: SETTINGS, next: next.trimEnd() + '\n', what: '迁移：llm-deepseek 还原官方 + 问述段接手（保留其余键）' })
+} else if (!whys && ALLOW_OFFICIAL) {
+  // settings.yaml 里的问述段现在是**可选**（provider 配置已在组合条目内）⇒ 默认也不写这个文件
+  const add = `\nllm-whyshu:\n  baseURL: ${WHYS.baseURL}\n  apiKeyEnv: ${WHYS.apiKeyEnv}\n  models:\n${block(['deepseek-flash', 'deepseek-v4-pro'], names.whyshu)}\n`
+  wants.push({ file: SETTINGS, next: text.trimEnd() + '\n' + add, what: '补建：末尾追加 llm-whyshu 段（原文件其余内容逐字不动）' })
+}
+
+if (existsSync(PATCH)) {
+  const pt = readFileSync(PATCH, 'utf8')
+  if (!/^\s*- id: llm-whyshu\s*$/m.test(pt)) {
+    // ⚠️ **必须包在 `- insert:` 里**：补丁文件里的**普通条目是按 id 覆盖已有条目**，
+    // 写成普通条目会报 `patch: entry "llm-whyshu" not found` 并被**静默跳过**（实测：
+    // 设置页始终只有一个 provider，且 dump-config 才看得到告警）。
+    const block = [
+      '', '# ── 问述代理 provider（migrate-providers 写入）：与官方 deepseek-official 并存 ──',
+      '- insert:',
+      '    - id: llm-whyshu',
+      "      name: 'argent-core/llm-whyshu'",
+      '      config:',
+      '        apiKeyEnv: WHYSHU_API_KEY', '',
+    ].join('\n')
+    wants.push({ file: PATCH, next: pt.trimEnd() + '\n' + block, what: '装配：insert llm-whyshu 实例' })
+  }
+}   // ← 闭合 `if (existsSync(PATCH)) {`（2026-09-30 修复：此前被误删 ⇒ SyntaxError）
+
+if (!wants.length) { log('✅ 已是双 provider 形态（无需迁移）'); process.exit(0) }
+for (const w of wants) {
+  if (DRY) { log(`[dry-run] ${w.what} → ${w.file}`); continue }
+  if (existsSync(w.file)) copyFileSync(w.file, `${w.file}.bak-providers-${stamp}`)
+  writeFileSync(w.file, w.next)
+  const back = readFileSync(w.file, 'utf8')
+  const expect = w.file.endsWith('cordis.patch.yml') ? /- id: llm-whyshu/ : /llm-whyshu:/
+  if (!back.trim() || !expect.test(back)) {
+    const bak = `${w.file}.bak-providers-${stamp}`
+    if (existsSync(bak)) copyFileSync(bak, w.file)
+    log(`✗ 回读校验失败（缺少 llm-whyshu 段）⇒ 已从备份恢复：${w.file}`); process.exit(1)
+  }
+  log(`✅ ${w.what}`)
+}
+log('完成；重启 dsh 后两个 provider 并存生效：bash scripts/dsh-restart.sh')

package/engine/scripts/migrate-skills.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# migrate-skills.sh — 将 hermes 版 ML 技能迁移为 DSH skills 格式
+# 源: ../argent-ml-seller/skills/mercadolibre/*（同工作区）
+# 目标: ./skills/<id>/
+#
+# 转换规则:
+#   1. frontmatter: 保留 name/tags，新增 description（供 DSH 技能目录匹配）
+#   2. references/ scripts/ templates/ 原样复制（skill bundle 资源）
+#   3. 单一事实源: ml-fulfillment-sop 的 scripts/fulfillment_orchestrator.py 不复制
+#      （其真身在 scripts/ 根，见 README）；SKILL.md 中引用脚本路径改为 ../../scripts/
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SRC="${ARGENT_ML_SRC:-$REPO_ROOT/../argent-ml-seller/skills/mercadolibre}"
+DEST="$REPO_ROOT/skills"
+
+[[ -d "$SRC" ]] || { echo "源技能目录不存在: $SRC" >&2; exit 1; }
+mkdir -p "$DEST"
+
+migrate_one() {
+  local dir="$1" id version name tags
+  id=$(basename "$dir")
+  # 解析 frontmatter
+  name=$(awk '/^name:/{sub(/^name:[ ]*/,""); print; exit}' "$dir/SKILL.md" | tr -d '"')
+  version=$(awk '/^version:/{sub(/^version:[ ]*/,""); print; exit}' "$dir/SKILL.md" | tr -d '"')
+  tags=$(awk '/^tags:/{sub(/^tags:[ ]*\[/,""); sub(/\].*/,""); print; exit}' "$dir/SKILL.md" | tr -d ' ')
+  [[ -n "$name" ]] || name="$id"
+  [[ -n "$version" ]] || version="1.0.0"
+
+  local dest="$DEST/$id"
+  mkdir -p "$dest"
+  # 复制资源目录（排除脚本副本，单一事实源）
+  for sub in references templates; do
+    [[ -d "$dir/$sub" ]] && cp -R "$dir/$sub" "$dest/"
+  done
+  # scripts: ml-fulfillment-sop 的编排器副本不复制（单一事实源在 ../../scripts/）
+  if [[ -d "$dir/scripts" ]]; then
+    mkdir -p "$dest/scripts"
+    for f in "$dir/scripts"/*; do
+      b=$(basename "$f")
+      case "$b" in
+        fulfillment_orchestrator.py) echo "  ↦ 跳过 ${id}/scripts/${b}（单一事实源在 scripts/）" ;;
+        *) cp -R "$f" "$dest/scripts/" ;;
+      esac
+    done
+  fi
+  # SKILL.md: frontmatter 注入 description，正文脚本路径重写
+  local desc="美客多${name}技能（Argent on DSH）——${tags:-ML 运营}。原 hermes 版 v${version}。"
+  awk -v desc="$desc" '
+    BEGIN { infm=1 }
+    infm && /^---$/ { n++; if (n==2) { infm=0; print "description: \"" desc "\""; next } }
+    { print }
+  ' "$dir/SKILL.md" > "$dest/SKILL.md"
+  # 正文中引用编排器副本的路径改指仓库根 scripts/ 单一事实源（orchestrator.py）
+  sed -i '' 's|scripts/fulfillment_orchestrator.py|../../scripts/orchestrator.py|g' "$dest/SKILL.md" 2>/dev/null || true
+  echo "✓ ${id}（${name} v${version}）"
+}
+
+for d in "$SRC"/*/; do
+  migrate_one "$d"
+done
+
+echo
+echo "迁移完成 → $DEST"
+echo "提示: 若 ml-fulfillment-sop 需要旧编排器（开发对照），手动从 hermes 版复制。"