lan-low-code-cli 2.4.0 → 2.6.0

package/skills/lan-low-code-cli/references/operation-script-context.md

@@ -0,0 +1,220 @@
+# 业务操作脚本（JS 模式）context API 参考
+
+> 适用：表单业务操作 `fdType=3` + `fdViewType=5`（平台「脚本模式」）。
+> 结论来源：sys-modeling 前端源码（MK-PaaS，`frontend/sys-modeling`）。
+> **重要**：除 `fdOprId` / `fdIds` / `fdBtnCfg` / `destroyLoading` 是显式注入外，
+> 其余字段来自组件内部 props 的浅拷贝，**不是公开契约**，平台升级可能变化——使用前请做 `typeof` 兜底。
+
+## 1. 执行机制
+
+点击「脚本模式」按钮后，前端先调 `sysModelingOperation` 相关接口拿到操作配置，再执行脚本：
+
+```js
+// desktop/operation/other.ts（移动端 mobile/operation/other.ts 同构）
+new Function('context', model.fdCfg?.fdJavaScript)({
+  ...context,          // 列表页传入的上下文（浅拷贝，见第 3 节）
+  fdOprId: operation.id,
+  fdIds: params['fdIds'],
+  fdBtnCfg: model.fdCfg,
+  destroyLoading,      // 关闭「执行中...」提示
+})
+```
+
+关键点：
+
+1. 脚本在**全局作用域**求值，可直接用 `window.mk`、`window.MKXFORM`、`fetch` 等页面全局对象；
+2. 脚本抛错会被前端 `try/catch` 吞掉（仅 `console.error`），页面只关闭 loading——**错误不会提示用户**，
+   脚本内部必须自己 try/catch 并给出可见反馈；
+3. 平台**不会**在脚本执行后自动刷新列表（只有 AI 能力分支会 `refresh()`），需要刷新就自己调；
+4. 脚本里调用 `context.destroyLoading()` 后，前端检测到即不再重复关闭；不调用则由前端关闭（无参数执行完也关）。
+
+## 2. 显式注入字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `context.fdOprId` | `string` | 当前业务操作 id |
+| `context.fdIds` | `string[] \| undefined` | 选中/当前行 id。**仅** `operation.selected === true` 时赋值：行内按钮、标准行操作；工具栏按钮通常为 `undefined` |
+| `context.fdBtnCfg` | `object` | 操作配置（后端返回的 `fdCfg` 解析结果，含 `fdViewType` / `fdJavaScript` 等） |
+| `context.destroyLoading` | `() => void` | 关闭「执行中...」提示并复位按钮 loading |
+
+## 3. 列表页上下文（desktop）
+
+`context` 由列表页 `useListOperations` 组装（`components/list-core/hooks/useListOperations.ts`），
+是 `content.tsx` 传入 props 的浅拷贝 + 若干选中态字段。
+
+### 3.1 选中数据
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `selectedId` | `string[]` | 勾选行的 `fd_id` 数组（组件 state，工具栏按钮场景） |
+| `docId` | `string \| undefined` | 行内按钮：当前行 id（= `operation.selectedIds[0]`） |
+| `fdIds` | `string[] \| undefined` | 见第 2 节；行内按钮/标准行操作才有 |
+| `setSelectedId` | `(ids: string[]) => void` | 设置勾选行 |
+| `setSelectedDocs` | `(docs: any[]) => void` | 设置勾选行的完整数据 |
+
+**取值优先级建议**：`fdIds`（行内按钮）→ `selectedId`（工具栏勾选）→ `docId`（兜底）。
+
+> 坑：`selectedId: selectedId || selectedIds`，空数组 `[]` 是 truthy——行内按钮点击时
+> `selectedId` 往往就是 `[]`，此时必须用 `docId` / `fdIds`。
+
+### 3.2 列表数据
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `data` | `any[]` | 当前页数据数组（= `$$contentviewProps.data`，行字段 `fd_id`） |
+| `$$contentviewProps.data` | `any[]` | 同上；`$$contentviewProps` 还含 `refresh` / `query` / `queryChange` / `history` |
+| `xlistRuntimeRef.current.getData()` | `() => { content: any[] }` | 列表运行时数据（**类型未声明**，运行时存在，需兜底） |
+
+### 3.3 刷新与查询
+
+| 入口 | 说明 |
+|---|---|
+| `context.refresh(query?)` | 推荐。等价 `xlistRuntimeRef.current.loadData(query)` |
+| `context.$$contentviewProps.refresh(query?)` | 同上（列表页透传的同一个函数） |
+| `context.cacheListRef.current.refresh(query?)` | 列表页把 `refresh` 缓存在这里，供跨组件/iframe 使用 |
+| `context.xlistRuntimeRef.current.loadData(query?)` | 最底层；支持传对象或函数式 updater |
+| `context.$$contentviewProps.queryChange(newQuery)` | 在现有 query 上合并后重载：`loadData(q => ({...q, ...newQuery}))` |
+| `context.cacheListRef.current.queryChange` | 同上（缓存副本） |
+
+### 3.4 视图 / 权限 / 路由上下文
+
+| 字段 | 说明 |
+|---|---|
+| `formId` | 表单 id |
+| `listviewId` | 列表视图 id |
+| `fdRightGroupId` | 当前权限组 id |
+| `appId` / `appCode` | 应用 id / 编码 |
+| `fdCategoryModelCode` / `fdCategoryType` / `fdCategoryId` | 分类表单相关 |
+| `menuId` / `baseUrl` | 菜单与路由前缀 |
+| `fdOpenMode` / `drawerOptions` | 打开方式（`self`/`drawer`/`_blank`）与抽屉配置 |
+| `isInDrawer` | 当前是否在抽屉内 |
+| `templateId` / `commonIncParams` / `localQuery` / `mainTable` | 模板、公共入参、本地查询、主表标识 |
+| `params` | 外部调用 `operations.execute(op, params)` 时传入的第二个参数 |
+| `dispatch` | 通用弹窗 reducer：`dispatch({type:'modalProps', payload:{...}})`（内部状态，不建议依赖） |
+| `setDoingOperation` | `(v: boolean) => void`，切换按钮「执行中」状态 |
+
+### 3.5 工具栏按钮 vs 行内按钮
+
+| 场景 | `selected` | `fdIds` | `docId` | `selectedId` |
+|---|---|---|---|---|
+| 列表工具栏按钮 | 通常 `undefined` | `undefined` | `undefined` | 勾选行数组（可能 `[]`） |
+| 行内右侧按钮 | `true` | `[当前行 id]` | 当前行 id | 通常 `[]` |
+| 外部 `operations.execute` | 取决于调用方 | 需自己传 | 需自己传 | 取决于调用方 |
+
+> 平台配置的「勾选数据」（`fdConfig.fdListViewIdValid`）在脚本模式下**不会**转成 `selected`，
+> 也不会触发「请选择数据」校验——脚本必须自己判断并提示。
+
+## 4. 全局能力（window）
+
+| API | 说明 |
+|---|---|
+| `mk.openLink({ url, target, drawerOptions, forceTarget })` | 打开页面：`target` 取 `self` / `drawer` / `_blank` |
+| `mk.normalizeUrl('sys://user/sys-modeling/<path>')` | 内部路由转可访问地址（业务操作的 `goto` 用它） |
+| `mk.getSysConfig(key)` | `modulesUrlPrefix` / `apiUrlPrefix` / `currentUser` / `platform` / `standalone` 等 |
+| `mk.emit(event, payload)` / `mk.on` / `mk.off` | 事件总线（如 `mk.emit('CHANGETAGSS')`、`mk.emit(MkModelingEventTypes.PageListStateChange, {})`） |
+| `mk.userStore` | 全局 key-value（`mk.userStore.set({ key, value })` / `get`） |
+| `window.MKXFORM` | 列表页已初始化（`components/list-core/components/content-area.tsx`）：`tableModal` / `modal` / `HTMLModal`；表单上下文还有 `setValue`/`getValue` 等（见 `mkxform-api.md`） |
+| `fetch` / `Blob` / `navigator.clipboard` / `window.open` | 标准浏览器能力，可自行调接口、导出文件 |
+
+### 4.1 跨窗口 / iframe
+
+列表页监听 `message`（`window` 与 `window.parent`）：
+
+| 事件名 | 效果 |
+|---|---|
+| `mk-refresh-opener`（`ModelingDrawerViewEvents.RefreshPage`） | 触发列表刷新（`cacheListRef.current.refresh()`） |
+| `PageInfo` / `Clear` / `TurnPage` | 分页信息交换 / 清缓存 / 翻页（列表页与抽屉 iframe 之间） |
+
+```js
+window.parent.postMessage({ eventType: 'mk-refresh-opener' }, '*')
+```
+
+## 5. 常用片段
+
+### 5.1 读取选中数据 + 兜底
+
+```js
+function resolveRows(ctx) {
+  var ids = (Array.isArray(ctx.fdIds) && ctx.fdIds.length ? ctx.fdIds : null) ||
+            (Array.isArray(ctx.selectedId) && ctx.selectedId.length ? ctx.selectedId : null) ||
+            (ctx.docId ? [ctx.docId] : [])
+  var list = (ctx.$$contentviewProps && ctx.$$contentviewProps.data) || ctx.data || []
+  if (!list.length && ctx.xlistRuntimeRef && ctx.xlistRuntimeRef.current) {
+    try { list = (ctx.xlistRuntimeRef.current.getData() || {}).content || [] } catch (e) { list = [] }
+  }
+  return list.filter(function (row) { return ids.indexOf(row.fd_id || row.fdId) > -1 })
+}
+```
+
+### 5.2 刷新列表（多级兜底）
+
+```js
+function refreshList(query) {
+  var c = context
+  try {
+    if (typeof c.refresh === 'function') return c.refresh(query)
+    if (c.$$contentviewProps && typeof c.$$contentviewProps.refresh === 'function')
+      return c.$$contentviewProps.refresh(query)
+    if (c.cacheListRef && c.cacheListRef.current && typeof c.cacheListRef.current.refresh === 'function')
+      return c.cacheListRef.current.refresh(query)
+    if (c.xlistRuntimeRef && c.xlistRuntimeRef.current && typeof c.xlistRuntimeRef.current.loadData === 'function')
+      return c.xlistRuntimeRef.current.loadData(query)
+  } catch (e) {
+    console.warn('[script] refresh failed', e)
+  }
+}
+```
+
+### 5.3 打开页面 / 抽屉
+
+```js
+window.mk.openLink({
+  url: window.mk.normalizeUrl('sys://user/sys-modeling/add/' + context.formId),
+  target: context.fdOpenMode || '_blank',
+  drawerOptions: context.drawerOptions,
+})
+```
+
+### 5.4 批量调接口后刷新
+
+```js
+fetch(window.mk.getSysConfig('apiUrlPrefix') + '/sys-modeling/<接口路径>', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  credentials: 'include',
+  body: JSON.stringify({ fdIds: context.selectedId }),
+})
+  .then(function (r) { return r.json() })
+  .then(function () { refreshList(); context.setSelectedId([]); context.destroyLoading() })
+  .catch(function (e) { console.error(e); context.destroyLoading() })
+```
+
+## 6. 移动端差异
+
+`mobile/operation/other.ts` 同样是 `new Function('context', script)({ ...context, fdIds, destroyLoading })`：
+
+- 可靠可用的：`fdOprId`、`fdIds`、`fdBtnCfg`、`destroyLoading`、`refresh`（查看/编辑页传的是整页 `refreshPage`）；
+- **不要依赖** `xlistRuntimeRef` / `$$contentviewProps` / `cacheListRef`（PC 列表专有），移动端列表是 `m-list-view`；
+- 移动端 `refresh()` 是整页重渲染，不是 `loadData(query)`。
+
+## 7. 已知边界与坑
+
+1. **没有** `context.selectRow`、`context.requestData`、`context.showAddPopup`、`context.queryChange`（后者只在 `$$contentviewProps` 里）。
+2. `callback` / `lcodeIncParams` / `defaultTemplateData` / `detailDataRowFilterOrder` 在列表页点击场景为 `undefined`（列表页未传）。
+3. `getData()` 未出现在 `IXListRuntimeRef` 类型声明中，仅运行时存在。
+4. 脚本异常被静默吞掉，务必自己 try/catch + 提示 + `destroyLoading()`。
+5. 刷新后如需清空勾选：`context.setSelectedId([])`。
+6. 不要直接修改 `$$contentviewProps.data`（不持久化，且与组件 state 不一致），写操作走后端接口。
+7. 调试：脚本里 `console.log(context)` 后在浏览器控制台查看完整字段；`localStorage.getItem('mk-debugger') === 'true'` 时平台会打印部分调试信息。
+
+## 8. 源码索引（核对版本用）
+
+| 内容 | 位置（sys-modeling/src） |
+|---|---|
+| 脚本执行入口（PC） | `desktop/operation/other.ts` |
+| 脚本执行入口（移动） | `mobile/operation/other.ts` |
+| context 组装 | `components/list-core/hooks/useListOperations.ts` |
+| 列表页 props / refresh | `desktop/pages/list/index.ts` |
+| 列表内容区 / window.MKXFORM | `components/list-core/components/content.tsx`、`content-area.tsx` |
+| 按钮点击 / 行内按钮 | `components/view-config/utils/operationsFun.tsx` |
+| 统一执行入口 | `desktop/operation/execute.ts` |

package/skills/lan-low-code-cli/scripts/self-update.mjs

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * 技能自更新（零依赖，Node >= 18）。
+ *
+ * 对比「已安装 CLI 版本」与「本技能 frontmatter version」，大版本不一致时提示技能可能过期；
+ * `--apply` 时用本地技能发行包 / 目录 / 全局 CLI 包内的 skill 覆盖当前技能目录（先备份）。
+ *
+ * 用法：
+ *   node scripts/self-update.mjs                                   # 仅检查（默认）
+ *   node scripts/self-update.mjs --check                           # 同上
+ *   node scripts/self-update.mjs --apply --from <skill.tgz|目录>    # 用本地发行包更新
+ *   node scripts/self-update.mjs --apply --from-cli                # 从全局 CLI 包内的 skills/ 更新
+ *   node scripts/self-update.mjs --apply --from <...> --force      # 同版本也强制覆盖
+ *
+ * 环境变量：
+ *   LLC_CLI           llc 命令或 CLI 入口脚本路径（默认 `llc`）
+ *   LLC_SKILL_SOURCE  等同 --from
+ *   LLC_SKILL_DIR     目标技能目录（默认脚本所在目录的父目录）
+ *
+ * 退出码：0 一致 / 已更新；2 版本不一致（技能可能过期）；1 错误。
+ */
+import { cpSync, existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+const SELF = fileURLToPath(import.meta.url)
+const DEFAULT_SKILL_DIR = dirname(dirname(SELF))
+
+const HELP = `技能自更新
+
+用法：
+  node scripts/self-update.mjs [选项]
+
+  --check                仅对比版本（默认行为）
+  --apply                执行覆盖更新（需配合 --from 或 --from-cli）
+  --from <tgz|目录>       技能发行包（.tgz/.tar.gz）或已解压的技能目录
+  --from-cli             从全局 npm 包 lan-low-code-cli 内的 skills/ 取技能
+  --dest <目录>           目标技能目录（默认脚本所在技能目录）
+  --force                目标版本与来源版本相同时仍覆盖
+  --json                 以 JSON 输出检查结果
+  --help                 显示本帮助
+
+环境变量：LLC_CLI、LLC_SKILL_SOURCE、LLC_SKILL_DIR`
+
+function parseArgs(argv) {
+  const opts = { apply: false, force: false, json: false, from: process.env.LLC_SKILL_SOURCE, fromCli: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--check') continue
+    else if (arg === '--apply') opts.apply = true
+    else if (arg === '--force') opts.force = true
+    else if (arg === '--json') opts.json = true
+    else if (arg === '--from-cli') opts.fromCli = true
+    else if (arg === '--from') opts.from = argv[++i]
+    else if (arg === '--dest') opts.dest = argv[++i]
+    else if (arg === '--help' || arg === '-h') opts.help = true
+    else throw new Error(`未知参数：${arg}\n\n${HELP}`)
+  }
+  opts.dest = resolve(opts.dest || process.env.LLC_SKILL_DIR || DEFAULT_SKILL_DIR)
+  if (opts.apply && !opts.from && !opts.fromCli) {
+    throw new Error('--apply 需要指定来源：--from <tgz|目录> 或 --from-cli')
+  }
+  return opts
+}
+
+/** 读取 frontmatter 中的 name / version */
+function readSkillMeta(dir) {
+  const file = join(dir, 'SKILL.md')
+  if (!existsSync(file)) return null
+  const text = readFileSync(file, 'utf8')
+  const version = /^version:\s*(\S+)\s*$/m.exec(text)
+  const name = /^name:\s*(\S+)\s*$/m.exec(text)
+  if (!version) return null
+  return { name: name ? name[1] : basename(dir), version: version[1] }
+}
+
+function parseVersion(version) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(String(version).trim())
+  if (!m) return null
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre: m[4] }
+}
+
+/** 运行 llc -v，返回 { version, command } */
+function detectCliVersion() {
+  const raw = process.env.LLC_CLI || 'llc'
+  const isScript = /\.(?:c|m)?js$/i.test(raw)
+  const cmd = isScript ? process.execPath : raw
+  const args = isScript ? [raw, '-v'] : ['-v']
+  const res = spawnSync(cmd, args, {
+    encoding: 'utf8',
+    shell: !isScript && process.platform === 'win32',
+    timeout: 20000,
+  })
+  if (res.error || res.status !== 0) {
+    throw new Error(
+      `无法执行 \`${raw} -v\`：${res.error ? res.error.message : `exit=${res.status}`}\n` +
+        '请先安装 CLI（npm i -g lan-low-code-cli），或用 LLC_CLI 指定可执行文件路径。',
+    )
+  }
+  const out = `${res.stdout ?? ''}${res.stderr ?? ''}`
+  const m = /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/.exec(out)
+  if (!m) throw new Error(`无法从 \`${raw} -v\` 的输出中解析版本号：${out.trim()}`)
+  return { version: m[1], command: raw }
+}
+
+/** 推导已安装 CLI 的包根：优先用 LLC_CLI 指向的入口脚本，其次 npm root -g */
+function cliPackageRoot() {
+  const raw = process.env.LLC_CLI
+  if (raw && /\.(?:c|m)?js$/i.test(raw)) {
+    const root = dirname(dirname(resolve(raw)))
+    if (existsSync(join(root, 'package.json'))) return root
+  }
+  const res = spawnSync('npm root -g', { encoding: 'utf8', shell: true, timeout: 20000 })
+  if (res.error || res.status !== 0) return null
+  const root = (res.stdout ?? '').trim()
+  return root ? join(root, 'lan-low-code-cli') : null
+}
+
+/** CLI 包内随包分发的 skills/（npm 包 files 含 skills；未分发时返回 null） */
+function skillFromGlobalCli() {
+  const root = cliPackageRoot()
+  if (!root) return null
+  const dir = join(root, 'skills', 'lan-low-code-cli')
+  return existsSync(join(dir, 'SKILL.md')) ? dir : null
+}
+
+/** 解压 tgz 到临时目录并定位技能根目录（压缩包顶层为 lan-low-code-cli/） */
+function extractSkillPackage(file) {
+  const tmp = mkdtempSync(join(tmpdir(), 'llc-skill-'))
+  const res = spawnSync('tar', ['-xzf', file, '-C', tmp], { encoding: 'utf8', timeout: 60000 })
+  if (res.error || res.status !== 0) {
+    rmSync(tmp, { recursive: true, force: true })
+    throw new Error(
+      `解压失败：${file}（${res.error ? res.error.message : `exit=${res.status}`}）。` +
+        'Windows 10+ 自带 tar；zip 包请先手动解压后用 --from <目录>。',
+    )
+  }
+  const roots = [tmp, join(tmp, 'lan-low-code-cli')]
+  for (const entry of readdirSync(tmp)) roots.push(join(tmp, entry))
+  const found = roots.find((dir) => existsSync(join(dir, 'SKILL.md')))
+  if (!found) {
+    rmSync(tmp, { recursive: true, force: true })
+    throw new Error(`发行包内未找到 SKILL.md：${file}`)
+  }
+  return { dir: found, cleanup: () => rmSync(tmp, { recursive: true, force: true }) }
+}
+
+function resolveSource(opts) {
+  if (opts.fromCli) {
+    const dir = skillFromGlobalCli()
+    if (!dir) {
+      throw new Error(
+        '已安装的 lan-low-code-cli 包内没有 skills/ 目录（该版本未随包分发技能）。\n' +
+          '请先升级 CLI：npm i -g lan-low-code-cli@latest；仍失败时改用技能发行包：\n' +
+          '  node scripts/self-update.mjs --apply --from ./lan-low-code-cli-skill-<version>.tgz',
+      )
+    }
+    return { dir, cleanup: () => {} }
+  }
+  const source = resolve(opts.from)
+  if (!existsSync(source)) throw new Error(`来源不存在：${source}`)
+  if (statSync(source).isDirectory()) return { dir: source, cleanup: () => {} }
+  return extractSkillPackage(source)
+}
+
+function sameVersion(a, b) {
+  return parseVersion(a) && parseVersion(b) && a === b
+}
+
+function check(opts) {
+  const skill = readSkillMeta(opts.dest)
+  if (!skill) throw new Error(`目标目录不是技能目录（缺少 SKILL.md 或 version）：${opts.dest}`)
+  const cli = detectCliVersion()
+  const skillVer = parseVersion(skill.version)
+  const cliVer = parseVersion(cli.version)
+  if (!skillVer || !cliVer) throw new Error(`版本号无法解析：skill=${skill.version} cli=${cli.version}`)
+
+  const stale = cliVer.major > skillVer.major
+  const older = cliVer.major < skillVer.major
+  if (opts.json) {
+    console.log(JSON.stringify({ skill: skill.version, cli: cli.version, command: cli.command, stale, older }, null, 2))
+  } else {
+    console.log(`技能版本：${skill.version}（${opts.dest}）`)
+    console.log(`CLI 版本：${cli.version}（${cli.command}）`)
+    if (stale) {
+      console.error(
+        `\n⚠ 已跨大版本（skill ${skillVer.major}.x → CLI ${cliVer.major}.x）：本技能可能已过期。\n` +
+          '  请提示用户更新技能后再执行写操作：\n' +
+          '    npm i -g lan-low-code-cli@latest\n' +
+          `    node scripts/self-update.mjs --apply --from ./lan-low-code-cli-skill-${cli.version}.tgz`,
+      )
+    } else if (older) {
+      console.error(`\n⚠ CLI（${cli.version}）比技能（${skill.version}）旧，请先升级 CLI，不要降级技能。`)
+    } else if (skill.version === cli.version) {
+      console.log('\n✓ 版本一致')
+    } else {
+      console.log('\n✓ 同一大版本，可直接升级 CLI（技能仍适用）')
+    }
+  }
+  return stale || older ? 2 : 0
+}
+
+function apply(opts) {
+  const current = readSkillMeta(opts.dest)
+  if (!current) throw new Error(`目标目录不是技能目录（缺少 SKILL.md 或 version）：${opts.dest}`)
+  const source = resolveSource(opts)
+  try {
+    const incoming = readSkillMeta(source.dir)
+    if (!incoming) throw new Error(`来源目录不是技能目录（缺少 SKILL.md 或 version）：${source.dir}`)
+    if (incoming.name !== current.name) {
+      throw new Error(`技能名不一致（当前 ${current.name}，来源 ${incoming.name}），已中止`)
+    }
+    if (!opts.force && sameVersion(incoming.version, current.version)) {
+      console.log(`已是最新：${current.version}（如需强制覆盖加 --force）`)
+      return 0
+    }
+
+    const backup = `${opts.dest}.backup-${current.version}-${Date.now()}`
+    cpSync(opts.dest, backup, { recursive: true })
+    console.log(`已备份：${backup}`)
+
+    const entries = readdirSync(source.dir)
+    for (const entry of entries) {
+      cpSync(join(source.dir, entry), join(opts.dest, entry), { recursive: true, force: true })
+    }
+    const dropped = readdirSync(opts.dest).filter((entry) => !entries.includes(entry))
+    if (dropped.length) {
+      console.log(`提示：以下文件不在新版本中，已保留（可手动删除）：${dropped.join('、')}`)
+    }
+
+    const updated = readSkillMeta(opts.dest)
+    console.log(`✓ 技能已更新：${current.version} → ${updated ? updated.version : '（未知）'}`)
+    console.log('  请重新读取 SKILL.md，再继续后续操作。')
+    return 0
+  } finally {
+    source.cleanup()
+  }
+}
+
+try {
+  const opts = parseArgs(process.argv.slice(2))
+  if (opts.help) {
+    console.log(HELP)
+    process.exit(0)
+  }
+  process.exit(opts.apply ? apply(opts) : check(opts))
+} catch (error) {
+  console.error(`错误：${error.message}`)
+  process.exit(1)
+}