@manohub/app-kit 0.2.1 → 0.2.4

package/skills/app-kit-migrate/references/migration-playbook.md

@@ -81,14 +81,14 @@
 ## 四、阶段 3 单文件循环
 
 ```bash
-node node_modules/@manohub/app-kit/lint/run-all.mjs --changed   # 直到本文件 0 违规
+pnpm exec appkit lint --changed   # 直到本文件 0 违规
 pnpm exec vue-tsc --noEmit                                      # 直到 0 错
 ```
 
 - 护栏每条违规自带 `file:line` + `correction.summary` / `.example` + `doc`（契约章节锚点）：
   **照 `correction` 改，不要另想一套**。
 - 需要单独排查某条规则时才直接跑单条脚本：
-  `node node_modules/@manohub/app-kit/lint/style-audit.mjs`（component / structure 同理）。
+  `pnpm exec appkit lint:style`（component / structure 同理）。
 - 样式类违规的处理次序：能删就删（迁移后不再需要的覆盖段）→ 需要保留的改成布局属性 →
   视觉语义改用组件的 `tone` / `shape` / `size`。
 
@@ -120,7 +120,7 @@ pnpm exec vue-tsc --noEmit                                      # 直到 0 错
 
 | 项 | 命令 / 做法 | 通过标准 |
 |---|---|---|
-| 护栏 | `node node_modules/@manohub/app-kit/lint/run-all.mjs` | 三条全绿；改动文件为 0；总数不高于基线 |
+| 护栏 | `pnpm exec appkit lint` | 三条全绿；改动文件为 0；总数不高于基线 |
 | 类型 | `pnpm exec vue-tsc --noEmit` | 0 错 |
 | 构建 | `pnpm build` | 成功；产物大小与阶段 0 量级一致（差异需能解释） |
 | 页面 | 浏览器逐个打开路由页与弹窗 | 渲染、交互、样式、弹层落点与改造前等价 |
@@ -163,5 +163,54 @@ export APPKIT_APP_DIR=apps/<x>
 | 缺口 | 影响 | 处理 |
 |---|---|---|
 | 结构护栏只扫 `.ts` / `.tsx`，不扫 `.vue` | 未纳入骨架的 `.vue` 页面不会报 `structure/no-shell` | 属已知范围，不要以为漏了；要覆盖需先有页面级豁免能力 |
-| 骨架层尚未提供的件 | 某些位置只能用现有件近似 | 走契约缺件处置流程，不在应用侧自绘；缺件清单见契约 §7 与包内 `AGENTS.md` 的「待建件」 |
+| 骨架层尚未提供的件 | 某些位置只能用现有件近似 | 走契约缺件处置流程，不在应用侧自绘；缺件清单与替代口径见契约 §7.1 |
 | 底层组件库版本跃迁带来的视觉差异 | 个别间距/圆角可能与改造前有细微不同 | 先确认是否骨架层规范使然；确属缺陷则记为骨架层待修项，不在应用侧写覆盖样式 |
+
+---
+
+## 九、变体路径：只迁骨架（Shell-only）
+
+适用：应用这批**只想要页面骨架**（`AppShell` / `AppPanel` / `Split` 的结构、滚动归属、高度链），
+组件替换与样式收口留到下一批次。这是受支持的路径（靠 `CONTRACT.md` §8.1 的规则级豁免），
+但**有三条硬前置**，缺一条就会出现「迁完更丑」：
+
+1. **接样式三行**（`reset.css` → `styles.css` → `./app.css`）。`AppShell` 的高度链、页头规格、两侧分隔线
+   全在包内 CSS 与 `--ui-*` 令牌上，只换组件不接样式等于把骨架挂空。
+2. **去掉自绘根容器的 `100vh` / `h-screen`**（结构护栏 S5）：`AppShell` 用 `height: 100%` 撑宿主容器，
+   外面套一个 `100vh` 的自绘壳会溢出。
+3. **拆旧页头 / 面板头**（结构护栏 S6）：`*page-header*` / `*panel-head*` 这类类名要删，页头交给
+   `AppShell.Header`；留着旧页头再叠新页头会同时命中 S2（未传 title）与 S6。
+
+配置（`appkit-guardrails.config.json`）：
+
+```jsonc
+{
+  "apps": [{
+    "dir": ".", "name": "<app>", "prefixes": ["<你的前缀>"], "pending": false,
+    "waivedRules": [
+      { "rule": "api/*",   "reason": "只迁骨架（Shell-only）：组件替换在下一批次", "since": "<日期>" },
+      { "rule": "style/*", "reason": "同上：样式收口等骨架稳定后再做",           "since": "<日期>" }
+    ]
+  }]
+}
+```
+
+范围：阶段 2 的推荐顺序里**只做第 2 步**（页面骨架），第 1 步只取其中的样式三行与入口，第 3、4 步停手。
+
+### 里程碑 A 验收
+
+| 项 | 命令 | 通过标准 |
+|---|---|---|
+| 结构 | `pnpm exec appkit lint:structure` | **0 error** —— 结构类没有豁免，这是本里程碑的硬指标 |
+| 全量（含豁免） | `pnpm exec appkit lint` | 退出码 0；`api/*` / `style/*` 的违规标 `waived`，条数入基线供后续「只减不增」比对 |
+| 收口预演 | `pnpm exec appkit lint --strict` | 记录剩余违规总数 —— 这就是下一批次的起点 |
+| 类型 / 构建 | `pnpm exec vue-tsc --noEmit` / `pnpm build` | 0 错 / 成功 |
+| 页面 | 浏览器逐个过路由页与弹窗 | 滚动归属、表体滚动 + 分页常驻、弹层落点与改造前等价 |
+
+### 下一批次怎么收
+
+按 `api/*` → `style/*` 的顺序**逐条撤销豁免**：撤销一条 → 跑一次该条规则 → 确认能归零就继续下一条
+（撤不掉的说明还缺件，走 `CONTRACT.md` §7 建件，而不是回退豁免）。全部撤完跑 `--strict` 复核。
+报告里出现「以下豁免当前 0 条命中，可以撤销了」就是在提醒你做这件事。
+
+登记：在应用文档里写清里程碑 A 的日期、结构违规数（0）、`--strict` 下的剩余违规数与撤销计划。

package/skills/install.mjs

@@ -1,222 +1,298 @@
-/**
- * 技能安装器：把随本包分发的 AI 技能落到消费方的技能目录。
- *
- * 用法（消费方工程根执行）：
- *   node node_modules/@manohub/app-kit/skills/install.mjs
- *   node node_modules/@manohub/app-kit/skills/install.mjs --also-claude
- *   node node_modules/@manohub/app-kit/skills/install.mjs --target .x/skills
- *   node node_modules/@manohub/app-kit/skills/install.mjs --dry-run
- *
- * 设计取舍：
- *
- * 1. **幂等**：每个技能「先删同名目录再整体复制」。包升级后重跑一次即刷新到新版内容，
- *    不存在「旧文件残留」或「同名合并」的中间态。
- * 2. **越界保护**：只允许操作 `SKILL_NAMES` 白名单内的目录名，且目标必须是白名单目录的**直接子路径**。
- *    删除动作因此永远不可能落到用户自己的技能或其它文件上。
- * 3. **零依赖 + 纯函数**：判定与计划部分抽成纯函数并由 `__tests__/skills-install.test.mjs`
- *    做故障注入测试（一个对坏输入不报警的安装器等于没有安装器），落盘动作只在直接执行时发生。
- * 4. 只复制**技能目录**，跳过本文件与 `README.md`（那是给包维护者看的），也不复制 `__tests__`。
- */
-import { cpSync, existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs'
-import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-
-/** 本技能包管理的技能目录名（白名单：只有这些名字允许被创建或清理） */
-export const SKILL_NAMES = ['app-kit', 'app-kit-migrate', 'app-kit-dev']
-
-/** 缺省的技能目录（相对消费方工程根） */
-export const TARGET_CODEXBUDDY = ['.codebuddy', 'skills']
-export const TARGET_CLAUDE = ['.claude', 'skills']
-
-/** 把源目录里「名字在白名单内、且含 SKILL.md」的目录识别为可安装技能 */
-export function listSourceSkills(sourceDir) {
-  return SKILL_NAMES.filter((name) => {
-    const dir = join(sourceDir, name)
-    return existsSync(dir) && statSync(dir).isDirectory() && existsSync(join(dir, 'SKILL.md'))
-  })
-}
-
-/** 目标目录安全校验：不允许写到文件系统根（`/`、`C:\`） */
-export function assertSafeTarget(targetDir) {
-  const resolved = resolve(targetDir)
-  if (resolved === dirname(resolved)) {
-    throw new Error(`拒绝写入文件系统根目录：${resolved}`)
-  }
-  return resolved
-}
-
-/** 越界保护：`path` 必须是 `targetDir` 的直接子路径，且名字在白名单内 */
-export function assertManagedPath(targetDir, path) {
-  const target = assertSafeTarget(targetDir)
-  const name = basename(path)
-  if (!SKILL_NAMES.includes(name)) {
-    throw new Error(`拒绝操作白名单外的目录：${path}`)
-  }
-  if (dirname(resolve(path)) !== target) {
-    throw new Error(`拒绝操作目标目录之外的路径：${path}`)
-  }
-  return join(target, name)
-}
-
-/**
- * 解析命令行参数。未知参数直接报错 —— 静默忽略会让人以为选项生效了。
- * （不参与单测的 IO，纯字符串处理）
- */
-export function parseArgs(argv) {
-  const opts = { target: null, alsoClaude: false, dryRun: false, help: false }
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i]
-    if (arg === '--target') {
-      const value = argv[i + 1]
-      if (!value || value.startsWith('--')) throw new Error('--target 需要一个目录参数')
-      opts.target = value
-      i += 1
-    } else if (arg === '--also-claude') {
-      opts.alsoClaude = true
-    } else if (arg === '--dry-run') {
-      opts.dryRun = true
-    } else if (arg === '--help' || arg === '-h') {
-      opts.help = true
-    } else {
-      throw new Error(`未知参数：${arg}（用 --help 看用法）`)
-    }
-  }
-  return opts
-}
-
-/** 计算落盘目标目录：默认 `.codebuddy/skills`，`--target` 优先，`--also-claude` 追加 */
-export function resolveTargets({ cwd, target = null, alsoClaude = false }) {
-  if (target) {
-    const resolved = isAbsolute(target) ? target : join(cwd, target)
-    return [assertSafeTarget(resolved)]
-  }
-  const targets = [assertSafeTarget(join(cwd, ...TARGET_CODEXBUDDY))]
-  if (alsoClaude) targets.push(assertSafeTarget(join(cwd, ...TARGET_CLAUDE)))
-  return targets
-}
-
-/** 统计目录下的文件数（用于落盘摘要） */
-export function countFiles(dir) {
-  let total = 0
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    total += entry.isDirectory() ? countFiles(join(dir, entry.name)) : 1
-  }
-  return total
-}
-
-/** 生成安装计划（不落盘）；源目录里一个技能都没有时直接报错 */
-export function planInstall({ sourceDir, targetDirs }) {
-  if (!existsSync(sourceDir)) throw new Error(`技能源目录不存在：${sourceDir}`)
-  const skills = listSourceSkills(sourceDir)
-  if (skills.length === 0) {
-    throw new Error(`技能源目录里没有可安装的技能（期望 ${SKILL_NAMES.join(' / ')}）：${sourceDir}`)
-  }
-  if (targetDirs.length === 0) throw new Error('没有解析出任何目标目录')
-
-  const actions = []
-  for (const target of targetDirs) {
-    for (const skill of skills) {
-      const from = join(sourceDir, skill)
-      const to = join(assertSafeTarget(target), skill)
-      assertManagedPath(target, to)
-      actions.push({ skill, from, to, files: countFiles(from) })
-    }
-  }
-  return { sourceDir, targetDirs, skills, actions }
-}
-
-/** 落盘（`dryRun` 时只返回计划结果，不写文件系统） */
-export function applyInstall(plan, { dryRun = false } = {}) {
-  const results = []
-  for (const action of plan.actions) {
-    if (!dryRun) {
-      mkdirSync(dirname(action.to), { recursive: true })
-      // 先清理再复制：保证与包内内容完全一致（幂等）
-      rmSync(action.to, { recursive: true, force: true })
-      cpSync(action.from, action.to, { recursive: true })
-    }
-    results.push({ ...action, dryRun })
-  }
-  return results
-}
-
-/**
- * 是否「被直接执行」（而非被 `import`）。
- *
- * **必须比对 realpath**：pnpm 把包实体放在 `node_modules/.pnpm/<pkg>@<ver>/...`，
- * 消费方引用的是软链路径 `node_modules/@manohub/app-kit/...`；Node 解析 ESM 时会取真实路径，
- * 于是 `import.meta.url` 与 `process.argv[1]` 字面不等 —— 直接比较会让安装器**静默不执行**
- * （真实踩过：在 pnpm 消费方里跑安装器零输出、技能也没落盘，而这正是最主要的使用场景）。
- *
- * `realpath` 可注入，便于单测覆盖「软链」「路径不存在」两种输入。
- */
-export function isDirectRun(argv1, moduleUrl, realpath = (p) => realpathSync(p)) {
-  if (!argv1) return false
-  if (moduleUrl === pathToFileURL(argv1).href) return true
-  try {
-    return moduleUrl === pathToFileURL(realpath(argv1)).href
-  } catch {
-    return false
-  }
-}
-
-export function usage() {
-  return [
-    '把 @manohub/app-kit 随包的 AI 技能安装到本工程的技能目录。',
-    '',
-    '用法：',
-    '  node node_modules/@manohub/app-kit/skills/install.mjs [选项]',
-    '',
-    '选项：',
-    '  --target <dir>    指定目标目录（缺省 <cwd>/.codebuddy/skills）',
-    '  --also-claude     同时安装到 <cwd>/.claude/skills',
-    '  --dry-run         只打印将要落盘的内容，不写文件系统',
-    '  --help, -h        显示本帮助',
-    '',
-    `管理的技能：${SKILL_NAMES.join(' / ')}（安装时先清理同名目录再复制，可反复执行）`,
-  ].join('\n')
-}
-
-function printSummary(results, plan, dryRun) {
-  const lines = ['[app-kit 技能安装]', `  源：${plan.sourceDir}`, `  技能：${plan.skills.join('、')}`]
-  for (const target of plan.targetDirs) {
-    lines.push(`  目标：${target}`)
-  }
-  for (const item of results) {
-    lines.push(`    ${dryRun ? '将写入' : '已写入'} ${item.to}（${item.files} 个文件）`)
-  }
-  if (dryRun) {
-    lines.push('  dry-run：未落盘，去掉 --dry-run 执行实际安装')
-  } else {
-    lines.push('  完成：技能目录已与包内内容对齐（包升级后重跑本命令即刷新）')
-  }
-  console.log(lines.join('\n'))
-}
-
-async function main() {
-  const opts = parseArgs(process.argv.slice(2))
-  if (opts.help) {
-    console.log(usage())
-    return
-  }
-
-  const sourceDir = dirname(fileURLToPath(import.meta.url))
-  const targetDirs = resolveTargets({ cwd: process.cwd(), target: opts.target, alsoClaude: opts.alsoClaude })
-
-  let plan
-  try {
-    plan = planInstall({ sourceDir, targetDirs })
-  } catch (error) {
-    console.error(`[app-kit 技能安装] 失败：${error.message}`)
-    process.exitCode = 1
-    return
-  }
-
-  const results = applyInstall(plan, { dryRun: opts.dryRun })
-  printSummary(results, plan, opts.dryRun)
-}
-
-// 仅在被直接执行时落盘；被测试 import 时只取纯函数
-if (isDirectRun(process.argv[1], import.meta.url)) {
-  await main()
-}
+/**
+ * 技能安装器：把随本包分发的 AI 技能落到消费方的技能目录。
+ *
+ * 用法（消费方工程根执行）：
+ *   pnpm exec appkit install
+ *   pnpm exec appkit install --also-claude
+ *   pnpm exec appkit install --target .x/skills
+ *   pnpm exec appkit install --dry-run
+ *
+ * 设计取舍：
+ *
+ * 1. **幂等**：每个技能「先删同名目录再整体复制」。包升级后重跑一次即刷新到新版内容，
+ *    不存在「旧文件残留」或「同名合并」的中间态。
+ * 2. **越界保护**：只允许操作 `SKILL_NAMES` 白名单内的目录名，且目标必须是白名单目录的**直接子路径**。
+ *    删除动作因此永远不可能落到用户自己的技能或其它文件上。
+ * 3. **零依赖 + 纯函数**：判定与计划部分抽成纯函数并由 `__tests__/skills-install.test.mjs`
+ *    做故障注入测试（一个对坏输入不报警的安装器等于没有安装器），落盘动作只在直接执行时发生。
+ * 4. 只复制**技能目录**，跳过本文件与 `README.md`（那是给包维护者看的），也不复制 `__tests__`。
+ * 5. **落盘前先算差异**：告诉消费方「这次刷新了什么」——包升级后技能内容有没有变，光看命令输出
+ *    是看不出来的；没有差异就是「已是最新」，有差异则列出新增 / 更新 / 删除的文件数。
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+/** 本技能包管理的技能目录名（白名单：只有这些名字允许被创建或清理） */
+export const SKILL_NAMES = ['app-kit', 'app-kit-migrate', 'app-kit-dev']
+
+/** 缺省的技能目录（相对消费方工程根） */
+export const TARGET_CODEXBUDDY = ['.codebuddy', 'skills']
+export const TARGET_CLAUDE = ['.claude', 'skills']
+
+/** 把源目录里「名字在白名单内、且含 SKILL.md」的目录识别为可安装技能 */
+export function listSourceSkills(sourceDir) {
+  return SKILL_NAMES.filter((name) => {
+    const dir = join(sourceDir, name)
+    return existsSync(dir) && statSync(dir).isDirectory() && existsSync(join(dir, 'SKILL.md'))
+  })
+}
+
+/** 目标目录安全校验：不允许写到文件系统根（`/`、`C:\`） */
+export function assertSafeTarget(targetDir) {
+  const resolved = resolve(targetDir)
+  if (resolved === dirname(resolved)) {
+    throw new Error(`拒绝写入文件系统根目录：${resolved}`)
+  }
+  return resolved
+}
+
+/** 越界保护：`path` 必须是 `targetDir` 的直接子路径，且名字在白名单内 */
+export function assertManagedPath(targetDir, path) {
+  const target = assertSafeTarget(targetDir)
+  const name = basename(path)
+  if (!SKILL_NAMES.includes(name)) {
+    throw new Error(`拒绝操作白名单外的目录：${path}`)
+  }
+  if (dirname(resolve(path)) !== target) {
+    throw new Error(`拒绝操作目标目录之外的路径：${path}`)
+  }
+  return join(target, name)
+}
+
+/**
+ * 解析命令行参数。未知参数直接报错 —— 静默忽略会让人以为选项生效了。
+ * （不参与单测的 IO，纯字符串处理）
+ */
+export function parseArgs(argv) {
+  const opts = { target: null, alsoClaude: false, dryRun: false, help: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--target') {
+      const value = argv[i + 1]
+      if (!value || value.startsWith('--')) throw new Error('--target 需要一个目录参数')
+      opts.target = value
+      i += 1
+    } else if (arg === '--also-claude') {
+      opts.alsoClaude = true
+    } else if (arg === '--dry-run') {
+      opts.dryRun = true
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true
+    } else {
+      throw new Error(`未知参数：${arg}（用 --help 看用法）`)
+    }
+  }
+  return opts
+}
+
+/** 计算落盘目标目录：默认 `.codebuddy/skills`，`--target` 优先，`--also-claude` 追加 */
+export function resolveTargets({ cwd, target = null, alsoClaude = false }) {
+  if (target) {
+    const resolved = isAbsolute(target) ? target : join(cwd, target)
+    return [assertSafeTarget(resolved)]
+  }
+  const targets = [assertSafeTarget(join(cwd, ...TARGET_CODEXBUDDY))]
+  if (alsoClaude) targets.push(assertSafeTarget(join(cwd, ...TARGET_CLAUDE)))
+  return targets
+}
+
+/** 统计目录下的文件数（用于落盘摘要） */
+export function countFiles(dir) {
+  let total = 0
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    total += entry.isDirectory() ? countFiles(join(dir, entry.name)) : 1
+  }
+  return total
+}
+
+/** 递归列出目录下的文件（绝对路径） */
+function walkFiles(dir) {
+  const out = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...walkFiles(full))
+    else out.push(full)
+  }
+  return out
+}
+
+/**
+ * 读一份目录快照：`相对路径（posix）→ 文件内容`；目录不存在时返回 `null`
+ * （`null` 表示「环境里还没有这份技能」，与「有目录但内容全空」区分开）。
+ */
+export function readDirSnapshot(dir) {
+  if (!existsSync(dir)) return null
+  const snapshot = new Map()
+  for (const file of walkFiles(dir)) {
+    snapshot.set(relative(dir, file).split('\\').join('/'), readFileSync(file, 'utf8'))
+  }
+  return snapshot
+}
+
+/**
+ * 比较「包内技能」与「已落盘技能」的内容差异，用于告诉消费方这次刷新了什么。
+ *
+ * 比"版本号比对"更直接：技能的版本号与包版本没有绑定关系，而内容一变就是要重跑的信号。
+ */
+export function diffSkillDirs(from, to) {
+  const after = readDirSnapshot(from)
+  const before = readDirSnapshot(to)
+  if (after === null) throw new Error(`技能源目录不存在：${from}`)
+  if (before === null) {
+    return { firstInstall: true, added: [...after.keys()].sort(), changed: [], removed: [] }
+  }
+  const added = []
+  const changed = []
+  for (const [rel, content] of after) {
+    if (!before.has(rel)) added.push(rel)
+    else if (before.get(rel) !== content) changed.push(rel)
+  }
+  const removed = [...before.keys()].filter((rel) => !after.has(rel))
+  return { firstInstall: false, added: added.sort(), changed: changed.sort(), removed: removed.sort() }
+}
+
+/** 生成安装计划（不落盘）；源目录里一个技能都没有时直接报错 */
+export function planInstall({ sourceDir, targetDirs }) {
+  if (!existsSync(sourceDir)) throw new Error(`技能源目录不存在：${sourceDir}`)
+  const skills = listSourceSkills(sourceDir)
+  if (skills.length === 0) {
+    throw new Error(`技能源目录里没有可安装的技能（期望 ${SKILL_NAMES.join(' / ')}）：${sourceDir}`)
+  }
+  if (targetDirs.length === 0) throw new Error('没有解析出任何目标目录')
+
+  const actions = []
+  for (const target of targetDirs) {
+    for (const skill of skills) {
+      const from = join(sourceDir, skill)
+      const to = join(assertSafeTarget(target), skill)
+      assertManagedPath(target, to)
+      actions.push({ skill, from, to, files: countFiles(from) })
+    }
+  }
+  return { sourceDir, targetDirs, skills, actions }
+}
+
+/**
+ * 落盘（`dryRun` 时只返回计划结果，不写文件系统）。
+ *
+ * 差异必须**在删除之前**读出来（删完就比对不出来了），所以先快照再清理。
+ */
+export function applyInstall(plan, { dryRun = false } = {}) {
+  const results = []
+  for (const action of plan.actions) {
+    const diff = diffSkillDirs(action.from, action.to)
+    if (!dryRun) {
+      mkdirSync(dirname(action.to), { recursive: true })
+      // 先清理再复制：保证与包内内容完全一致（幂等）
+      rmSync(action.to, { recursive: true, force: true })
+      cpSync(action.from, action.to, { recursive: true })
+    }
+    results.push({ ...action, diff, dryRun })
+  }
+  return results
+}
+
+/**
+ * 是否「被直接执行」（而非被 `import`）。
+ *
+ * **必须比对 realpath**：pnpm 把包实体放在 `node_modules/.pnpm/<pkg>@<ver>/...`，
+ * 消费方引用的是软链路径 `node_modules/@manohub/app-kit/...`；Node 解析 ESM 时会取真实路径，
+ * 于是 `import.meta.url` 与 `process.argv[1]` 字面不等 —— 直接比较会让安装器**静默不执行**
+ * （真实踩过：在 pnpm 消费方里跑安装器零输出、技能也没落盘，而这正是最主要的使用场景）。
+ *
+ * `realpath` 可注入，便于单测覆盖「软链」「路径不存在」两种输入。
+ */
+export function isDirectRun(argv1, moduleUrl, realpath = (p) => realpathSync(p)) {
+  if (!argv1) return false
+  if (moduleUrl === pathToFileURL(argv1).href) return true
+  try {
+    return moduleUrl === pathToFileURL(realpath(argv1)).href
+  } catch {
+    return false
+  }
+}
+
+export function usage() {
+  return [
+    '把 @manohub/app-kit 随包的 AI 技能安装到本工程的技能目录。',
+    '',
+    '用法：',
+    '  pnpm exec appkit install [选项]     （npm 消费方：npx appkit install）',
+    '  node node_modules/@manohub/app-kit/skills/install.mjs [选项]   等价写法（老脚本/钩子里可用）',
+    '',
+    '选项：',
+    '  --target <dir>    指定目标目录（缺省 <cwd>/.codebuddy/skills）',
+    '  --also-claude     同时安装到 <cwd>/.claude/skills',
+    '  --dry-run         只打印将要落盘的内容，不写文件系统',
+    '  --help, -h        显示本帮助',
+    '',
+    `管理的技能：${SKILL_NAMES.join(' / ')}（安装时先清理同名目录再复制，可反复执行）`,
+    '每次执行都会报告技能内容有没有变化：显示「已是包内最新」说明不必重跑，',
+    '显示「更新 N」说明这次升级改了技能内容、本次刷新已生效。',
+  ].join('\n')
+}
+
+/** 把一次安装的差异描述成一句人话；无差异时明确说「已是最新」 */
+export function describeDiff(diff, files = 0) {
+  if (!diff) return ''
+  if (diff.firstInstall) return `首次安装（${files} 个文件）`
+  const parts = []
+  if (diff.changed.length > 0) parts.push(`更新 ${diff.changed.length}`)
+  if (diff.added.length > 0) parts.push(`新增 ${diff.added.length}`)
+  if (diff.removed.length > 0) parts.push(`删除 ${diff.removed.length}`)
+  if (parts.length === 0) return `已是包内最新（内容无变化，共 ${files} 个文件）`
+  return `${parts.join(' / ')}（共 ${files} 个文件）`
+}
+
+/** 一次安装是否什么都没变（用于把「无需刷新」说清楚） */
+function isUnchanged(diff) {
+  return Boolean(diff) && !diff.firstInstall && diff.changed.length + diff.added.length + diff.removed.length === 0
+}
+
+function printSummary(results, plan, dryRun) {
+  const lines = ['[app-kit 技能安装]', `  源：${plan.sourceDir}`, `  技能：${plan.skills.join('、')}`]
+  for (const target of plan.targetDirs) {
+    lines.push(`  目标：${target}`)
+  }
+  if (dryRun) lines.push('  dry-run：以下为将落盘的结果（未写文件系统）')
+  for (const item of results) {
+    lines.push(`    ${item.to} —— ${describeDiff(item.diff, item.files)}`)
+  }
+  if (dryRun) {
+    lines.push('  去掉 --dry-run 执行实际安装')
+  } else if (results.length > 0 && results.every((item) => isUnchanged(item.diff))) {
+    lines.push('  完成：技能内容与包内一致，无需刷新（说明本包这次升级没有改动技能包）')
+  } else {
+    lines.push('  完成：技能目录已与包内内容对齐（包升级后重跑本命令即刷新）')
+  }
+  console.log(lines.join('\n'))
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2))
+  if (opts.help) {
+    console.log(usage())
+    return
+  }
+
+  const sourceDir = dirname(fileURLToPath(import.meta.url))
+  const targetDirs = resolveTargets({ cwd: process.cwd(), target: opts.target, alsoClaude: opts.alsoClaude })
+
+  let plan
+  try {
+    plan = planInstall({ sourceDir, targetDirs })
+  } catch (error) {
+    console.error(`[app-kit 技能安装] 失败：${error.message}`)
+    process.exitCode = 1
+    return
+  }
+
+  const results = applyInstall(plan, { dryRun: opts.dryRun })
+  printSummary(results, plan, opts.dryRun)
+}
+
+// 仅在被直接执行时落盘；被测试 import 时只取纯函数
+if (isDirectRun(process.argv[1], import.meta.url)) {
+  await main()
+}