@manohub/app-kit 0.2.0 → 0.2.3

package/CONTRACT.md

@@ -102,7 +102,7 @@ import { AppShell, AppPanel, AppTable, AppButton, notify } from '@manohub/app-ki
       <AppPanel
         title="值映射列表"
         toolbar={<><AppSearchBox … /><AppSelect … /></>}
-        actions={<><AppButton tone="primary">新建</AppButton><AppButton>刷新</AppButton></>}>
+        actions={<><AppButton tone="primary">新建</AppButton><AppButton tone="secondary">刷新</AppButton></>}>
         <AppTable framed rows={rows} columns={cols} rowKey="id" />
 
         {/* 分页跟**承载表格的容器**走：表格在本面板内 → AppPanel.Footer（不要提到 AppShell.Footer） */}
@@ -447,6 +447,112 @@ import { AppShell, AppPanel, AppTable, AppButton, notify } from '@manohub/app-ki
   右上角 ✕ / Esc 只关窗**不触发回调**（farris 行为），Promise 不落定 —— 调用方按"未确认"处理即可。
 - 轻量反馈（保存成功/失败）用 `notify`，长任务用 `loading`；两者都不带确认语义。
 
+### 4.14 页签（`AppTabs`）
+
+```tsx
+<AppTabs modelValue={activeTab}
+  items={[{ key: 'overview', label: '概览' }, { key: 'tools', label: '工具' }]}
+  v-slots={{ overview: () => <Overview />, tools: () => <Tools /> }}
+  onChange={(key) => (activeTab = key)} />
+```
+
+- `items` 是唯一的页签定义入口：`{ key, label }`（`key` 同时是**内容插槽名**）。
+- `modelValue` + `onChange(key)` 走上层统一词表；**点击只上报、消费方必须回写 `modelValue`**（受控语义，不回写界面不动）。
+- `fill` 缺省 `true`（撑满容器高度，抽屉/面板内需要）；不需要撑满时显式 `fill={false}`。
+- 页签条本身的视觉与滚动归组件；页面里不要自绘标签行，也不要用 `AppLayout` 拼一个「像页签」的按钮组。
+
+### 4.15 页面级筛选（`AppFilter` / `appFilterSelect` / `appFilterInput`）
+
+**位置**：只出现在 `AppShell.Filter`（§4.5：字段 > 3、跨区域、或已是组合查询方案）。区域级 ≤3 字段的筛选仍在
+`AppPanel.toolbar`，用普通表单控件。
+
+```tsx
+const fields: AppFilterField[] = [
+  { id: 'field-repoId', code: 'repoId', name: '所属仓库', editor: appFilterSelect(repoOptions) },
+  { id: 'field-state',  code: 'state',  name: '状态',     editor: appFilterSelect(stateOptions) },
+  { id: 'field-owner',  code: 'owner',  name: '负责人',   editor: appFilterInput('输入负责人') },
+]
+
+<AppShell.Filter>
+  <AppFilter fields={fields}
+    defaults={{ 'field-repoId': repoId, 'field-state': 'all' }}
+    searchFields="name" searchPlaceholder={t('filter.keywordPlaceholder')}
+    onChange={(values, meta) => applyFilter(values)}
+    onQuery={(values, meta) => applyFilter({ ...values, force: true })} />
+</AppShell.Filter>
+```
+
+- `fields` 必填，元素是 `{ id, code, labelCode?, name, controlType?, visible?, editor? }`。
+  `id` 是**字段标识**（默认值按它索引），`code` 是**业务条件名**（事件值与后端参数按它走）；两者不要混用。
+- **编辑器一律用两个工厂生成**，不要手写 farris 编辑器配置：
+  - `appFilterSelect([{ label, value }])` —— 下拉，应用侧只给标准选项；
+  - `appFilterInput(placeholder)` —— 单行文本（内部固定实时回传）。
+  工厂之外的 farris 字段（`valueField` / `enumValueType` / `combo-list` …）属于包内实现，应用侧写不出来。
+- `defaults` 用**字段 id → 业务值**；哨兵 `'all'` 表示「全部」，事件里会被翻译成空串（后端不传该条件即不过滤）。
+- 事件：`onChange(values, meta)` 条件变化（值已归一化为 `code → 字符串`）、`onQuery(values, meta)` 查询按钮/回车
+  （`meta.query === true`）、`onReady()` 条件区就绪。**默认值注入时机、payload 三形态归一、就绪轮询都由组件吃掉**，
+  应用侧不要再写 `solutionRef` 直调或 `setTimeout` 补时序。
+- `ignoreInitialEmpty`：按 key 重建条件区时挂载即触发一次空条件查询，传 `true` 忽略该次。
+- `keywordCodes` 决定哪些 code 算「关键字字段」（缺省 `fuzzysearch` / `keyword` / `name` / `displayname`）。
+
+### 4.16 树（`AppTree`）
+
+`AppTree` 为**自建件**（不封装底层树组件，理由见 §9.6），受控展开、三态内建。
+
+```tsx
+<AppTree nodes={nodes} rowKey="id" labelKey="name"
+  selected={selectedId} onSelect={(node) => (selectedId = node.id)}
+  expandedKeys={expandedKeys} onExpandChange={(keys) => (expandedKeys = keys)}
+  loading={loading} error={error} empty="暂无业务域"
+  renderNode={(node) => <AppBadge tone="info">{countOf(node.id)}</AppBadge>} />
+```
+
+| prop | 说明 |
+|---|---|
+| `nodes` / `rowKey` | **都必填**；`rowKey` 是字段名或 `(node) => key` |
+| `labelKey` / `childrenKey` | 标签字段名（默认 `label`）/ 子节点字段名（默认 `children`） |
+| `selected` + `onSelect(node)` | 选中是**行主键值**，回调给的是**节点对象**（不是 key），要 key 自己取 |
+| `expandedKeys` / `defaultExpandedKeys` / `onExpandChange(keys)` | 传了 `expandedKeys` 即完全受控；不传则内部自持，`defaultExpandedKeys` 给初值 |
+| `renderNode(node)` | 节点附加内容（计数徽标等），渲染在标签之后 |
+| `size` | `md`（行高 30，默认）/ `sm`（紧凑 28） |
+| `loading` / `error` / `empty` / `emptyActionText` + `onEmptyAction` / `errorTitle` / `errorActionText` + `onErrorAction` | 三态与动作，口径同 §4.6（**错误不要塞进 `empty`**） |
+| `treeKey` | 强制重挂逃生舱：正常数据刷新**不需要**它（展开态不会丢） |
+
+- **交互分工**：点箭头展开/收拢、**点行选中**（`onSelect`）—— 不要给行挂自绘点击展开逻辑。
+- **缩进步进由组件算**（`data-level` + CSS 变量），应用侧不要改行内 padding 或写死缩进像素（§9.6）。
+- 受控展开是「数据刷新不丢展开态」的实现前提：不要用「数据变了就换 `key` 重挂」的写法绕过。
+
+### 4.17 分页（`AppPagination` / `useClientPagination`）
+
+```tsx
+// 服务端分页：页面持有 page / pageSize
+<AppPagination page={page} pageSize={pageSize} total={total}
+  onPageChange={(p) => (page = p)}
+  onPageSizeChange={(s) => { pageSize = s; page = 0 }} />
+```
+
+- `page` / `pageSize` / `total` **必填**；`page` 是 **0 基**（与后端分页参数一致，1 基换算由组件内做）。
+- 事件是 **`onPageChange(page)` 与 `onPageSizeChange(pageSize)`** —— 没有 `onChange`；切页大小后回第几页属消费方语义
+  （现状惯例：回第 0 页）。
+- `pageSizeOptions`（缺省 `[10, 20, 50]`）、`showInfo`（缺省 `true`，总条数信息自带，**不要自绘「共 N 条」**）。
+- **位置**跟承载表格的容器走（§4.4）：表格在 `AppPanel` 内 → `AppPanel.Footer`；表格直接挂 `AppShell.Body` 下 →
+  `AppShell.Footer`；无数据 / 加载失败时不渲染分页。
+
+**客户端分页**（数据整批在前端）用 `useClientPagination`，不要自己写 `slice` + 越界处理：
+
+```tsx
+const list = useClientPagination(() => filteredRows.value)
+
+<AppTable framed rows={list.pageRows} columns={cols} rowKey="id" />
+<AppPagination page={list.page} pageSize={list.pageSize} total={list.total}
+  pageSizeOptions={list.pageSizeOptions}
+  onPageChange={list.setPage} onPageSizeChange={list.setPageSize} />
+```
+
+- 返回 `page` / `pageSize` / `total` / `pageCount` / `pageRows`（已切片，直接喂 `AppTable.rows`）/ `pageSizeOptions` /
+  `setPage` / `setPageSize`；页码同样是 0 基。
+- 数据变少（过滤 / 删除）导致当前页越界时**自动回退到最后一页**，不会出现「空白页但分页器显示有数据」。
+
 ---
 
 ## 5. 反例库（这些写法一律违规）
@@ -500,10 +606,23 @@ import { AppShell, AppPanel, AppTable, AppButton, notify } from '@manohub/app-ki
 
 需要的能力本包没有时，**不要**在页面里自绘外观，也不要直接引底层组件库：
 
-1. 先查本文件已列能力与包导出面；
-2. 确实缺件 → 在本包内**新建封装件**（命名锚定通用规范名，props 查 §3 词表），补导出面与单测；
+1. 先查本文件已列能力（含 §7.1 缺件清单）与包导出面（`@manohub/app-kit` 的导出列表）；
+2. 仍缺 → 走**包维护侧建件**：在包内新建封装件（命名锚定通用规范名，props 查 §3 词表），补导出面与单测。
+   消费方**不要**在自己仓里仿制一个近似件（仿制品一建就与骨架层两套口径，后续还得拆）；
 3. 建件前先确认底层库是否已有对应件：有则封装（吃掉其坑），无则自建（原生元素 + `--ui-*` 令牌）；
-4. 页面侧只用建好的件；自建件的实现踩坑与取舍写进包内 `AGENTS.md`。
+4. 页面侧只用建好的件；缺件期间按 §7.1 给的替代口径顶住，不要改护栏放过违规。
+
+### 7.1 当前缺件清单（判断「是否漏改 / 能不能实现」时看这里）
+
+| 能力 | 现状 | 缺件期间的替代口径 |
+|---|---|---|
+| 日期 / 日期时间选择 | **无**（无 `AppDatePicker`） | 暂用 `AppInput` 并标明格式；需真日期控件走 §7 建件 |
+| 数字 / 步进输入 | **无**（无 `AppNumber`） | 暂用 `AppInput` + 提交侧校验；需步进控件走 §7 建件 |
+| 加载骨架屏 | **无**（`AppSkeleton` 属后续批次） | 用 §4.6 三态的 `loading`（表格/树内建，块级用 `AppQueryState`） |
+| 抽屉（Drawer） | **无** | 宽内容用 `AppDialog`（定高可滚）或页面级双栏 `AppShell.Split` |
+| 描述列表（Descriptions） | **不再需要** | 摘要 / 详情走 §4.7 的 `AppForm.Item text={…}` 只读文本行 |
+
+> 本清单随版本变动；**不存在的能力一律不要在应用侧自绘**，也不要用别的件"拼一个像的"当替代品长期留着。
 
 ---
 
@@ -513,20 +632,66 @@ import { AppShell, AppPanel, AppTable, AppButton, notify } from '@manohub/app-ki
 `package.json` 里**只挂两条**（三条护栏由统一入口并发跑，不要各挂一条）：
 
 ```json
-"lint": "node node_modules/@manohub/app-kit/lint/run-all.mjs",
-"lint:changed": "node node_modules/@manohub/app-kit/lint/run-all.mjs --changed"
+"lint": "appkit lint",
+"lint:changed": "appkit lint --changed",
+"lint:strict": "appkit lint --strict"
 ```
 
+（scripts 里可以省略 `pnpm exec`：npm/pnpm 会把 `node_modules/.bin` 加进 PATH。终端手动跑时写
+`pnpm exec appkit lint`，npm 消费方写 `npx appkit lint`。）
+
 - 统一入口并发跑三条：`style-audit.mjs`（样式：只允许布局属性 / 禁 `!important` / 禁自写 rem）、
   `component-audit.mjs`（组件使用：禁底层直连 / 禁底层风格写法）、
   `structure-audit.mjs`（页面结构：骨架必用 / 禁自绘页头面板头 / 字段数上限）。
-  **排查单条**时才直接跑它（`node node_modules/@manohub/app-kit/lint/style-audit.mjs`），不必挂成脚本。
+  **排查单条**时才直接跑它（`pnpm exec appkit lint:style`），不必挂成脚本。
 - `--changed` 只跑改动文件（pre-commit 用；非 git 环境不裁剪，宁可多查）。
 - 每条违规都会给出 `file:line` + 片段 + **唯一改法**（`correction.summary` / `.example`）与 **`doc` 锚点**
   （指回本文件对应章节）。**照 `correction` 改，不要自己另想一套。**
 - 存量文件的口径：先产基线 → 挂起（`pending` + 豁免登记）→ **新增与改动过的文件必须归零**。
 
-### 8.1 提交前检查（可选，目标 < 3 秒）
+### 8.1 分阶段迁移：规则级豁免（`waivedRules`）
+
+只做**一部分**迁移是常态（最典型的是「**只迁骨架**」：先把页面结构换成 `AppShell` / `AppPanel`，组件与样式
+下一批次再收）。这一层用 `apps[].waivedRules` 表达：**已迁到的那一层即刻纳入门禁，没迁的登记豁免**。
+
+```jsonc
+// appkit-guardrails.config.json —— Shell-only 应用
+{
+  "apps": [{
+    "dir": ".", "name": "my-app", "prefixes": ["my-"], "pending": false,
+    "waivedRules": [
+      { "rule": "api/*",   "reason": "只迁骨架（Shell-only）：组件替换在下一批次", "since": "2026-09-18" },
+      { "rule": "style/*", "reason": "同上：样式收口等骨架稳定后再做",           "since": "2026-09-18" }
+    ]
+  }]
+}
+```
+
+- 规则名写 `域/规则`（如 `api/farris-import`）或整类通配（`api/*` / `style/*` / `structure/*`）；
+  **每条必须写 `reason`**（配置校验会拦），缺理由的豁免等于给护栏装静音键。
+- 豁免项**照常出现在报告里**（标成 `error/waived`），只是不计入退出码：
+  ```
+  component-audit（组件使用护栏）：0 个 error / 0 个 warn（其中 3 条属已登记豁免，不计入退出码）
+    [error/waived] src/views/x.tsx:2  api/farris-import
+        豁免：已登记（不参与门禁；用 --strict 可验证「收口后会怎样」）
+  ```
+  技术债必须可见 —— 这是「豁免」与「关掉规则」的区别。
+- 某条豁免**当前 0 条命中**时，报告会提示「可以撤销了」：迁移往前走了就该撤，否则它会静默地一直关着门。
+- **两条不拦断的机制**（应用级 `pending` = 整应用挂起产基线；规则级 `waivedRules` = 分阶段）都只是
+  「暂时不计入退出码」，不是「不检查」。
+
+### 8.2 收口验收：`--strict`
+
+```bash
+pnpm exec appkit lint --strict
+```
+
+`--strict` 下 **`pending` 与 `waivedRules` 一律失效**，退出码反映「真实剩下多少违规」。用于两个时点：
+
+1. **里程碑验收**：Shell-only 阶段收尾时跑一次，确认结构类确实归零（`structure/*` 本就没有豁免）；
+2. **全量收口**：所有豁免撤销、`pending` 置 `false` 后跑一次，全绿才算迁完。
+
+### 8.3 提交前检查（可选，目标 < 3 秒）
 
 包内提供钩子样本，放进默认 hooks 目录即可启用（**不需要改 git 配置**）：
 
@@ -539,7 +704,7 @@ export APPKIT_APP_DIR=apps/sub-app
 
 钩子只跑 `run-all.mjs --changed`（改动文件），所以秒级返回；`--changed` 在非 git 环境不裁剪（宁可多查）。
 
-### 8.2 包自身（`@manohub/app-kit`）的门禁
+### 8.4 包自身（`@manohub/app-kit`）的门禁
 
 ```bash
 pnpm --filter @manohub/app-kit type-check    # 包内 vue-tsc：0 错

package/README.md

@@ -9,8 +9,12 @@
 - **入口**：`@manohub/app-kit/entry` → `createSubApp`
 - **组件/服务**：`@manohub/app-kit` → `AppShell` / `AppPanel` / `AppTree` / `AppTable` / `AppButton` / `notify` …
 - **样式**：`@manohub/app-kit/reset.css` + `@manohub/app-kit/styles.css`（应用侧 `style.css` 固定三行，见 CONTRACT.md §1）
-- **护栏脚本**：`lint/style-audit.mjs` / `lint/component-audit.mjs` / `lint/structure-audit.mjs` / `lint/run-all.mjs`
-  （用法见 CONTRACT.md §8）
+- **命令入口**：`appkit`（`package.json` 的 `bin`，在应用包根执行）
+  - `pnpm exec appkit lint [--changed|--strict|--json]` —— 三条护栏；单条排查用 `appkit lint:style` / `lint:component` / `lint:structure`
+  - `pnpm exec appkit install [--also-claude|--dry-run]` —— 落 AI 技能到本工程
+  - npm 消费方把 `pnpm exec` 换成 `npx`；scripts 里可直接写 `appkit lint`（`.bin` 在 PATH 里）
+  - 等价写法（老脚本/钩子可用）：`node node_modules/@manohub/app-kit/lint/run-all.mjs`、`node node_modules/@manohub/app-kit/skills/install.mjs`
+  - 各护栏脚本仍单独可跑（用法见 CONTRACT.md §8）
 
 ## 分发形态
 
@@ -28,9 +32,9 @@
 在消费方工程根执行即可落到自己的技能目录（幂等，包升级后重跑即刷新）：
 
 ```bash
-node node_modules/@manohub/app-kit/skills/install.mjs                 # → .codebuddy/skills/
-node node_modules/@manohub/app-kit/skills/install.mjs --also-claude   # 同时 → .claude/skills/
-node node_modules/@manohub/app-kit/skills/install.mjs --dry-run       # 只预览
+pnpm exec appkit install                 # → .codebuddy/skills/
+pnpm exec appkit install --also-claude   # 同时 → .claude/skills/
+pnpm exec appkit install --dry-run       # 只预览
 ```
 
 装了之后，代理在做接入、迁移或页面开发时会命中本包规范与流程；技能职责边界与维护约定见 `skills/README.md`。

package/bin/appkit.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * `appkit` —— 接入方（消费方）命令行入口。
+ *
+ * 存在的理由：接入方不该被要求记住 `node node_modules/@manohub/app-kit/lint/run-all.mjs --changed`
+ * 这类路径。本命令是**薄壳**：把子命令映射到包内既有脚本，透传参数与退出码 —— 所以
+ * `appkit lint` 与「直接跑那个脚本」是同一件事，脚本仍可单独执行（已有钩子 / 脚本不用改）。
+ *
+ * 用法（在**应用包根**执行）：
+ *   pnpm exec appkit install             # 把随包分发的 AI 技能落到本工程
+ *   pnpm exec appkit install --also-claude
+ *   pnpm exec appkit lint                # 三条护栏（style / component / structure）
+ *   pnpm exec appkit lint --changed      # 只查改动文件（提交前，含未 git add 的新增）
+ *   pnpm exec appkit lint --strict       # 收口验收：存量挂起与规则豁免一律失效
+ *   pnpm exec appkit lint:style          # 单条排查：style / component / structure
+ *   pnpm exec appkit help
+ *
+ * npm 消费方把 `pnpm exec` 换成 `npx`（两者都解析本地 node_modules/.bin）。
+ * package.json 的 scripts 里可以省略前缀（npm/pnpm 会把 .bin 加进 PATH）：
+ *   "lint": "appkit lint", "lint:changed": "appkit lint --changed"
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+// 复用安装器里已测过的「是否被直接执行」判定：pnpm 把包放在 .pnpm 下、消费方引用的是软链，
+// 直接比较 argv[1] 与 import.meta.url 会字面不等 → CLI 静默不执行（同一个坑踩过两次不值得）。
+import { isDirectRun } from '../skills/install.mjs'
+
+/** 包根（本文件在 <pkg>/bin/ 下，发布物里 lint/ 与 skills/ 都是它的兄弟目录） */
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
+
+/** 子命令表：命令名 → 包内脚本与说明（新增子命令只需在这里加一行） */
+export const COMMANDS = {
+  install: {
+    script: 'skills/install.mjs',
+    summary: '把随包分发的三个 AI 技能落到本工程（--also-claude / --target <dir> / --dry-run）',
+  },
+  lint: { script: 'lint/run-all.mjs', summary: '三条护栏一起跑（--changed / --strict / --json / --app=<name> / --cwd=<dir>）' },
+  'lint:style': { script: 'lint/style-audit.mjs', summary: '只跑样式护栏（排查单条规则时用）' },
+  'lint:component': { script: 'lint/component-audit.mjs', summary: '只跑组件使用护栏' },
+  'lint:structure': { script: 'lint/structure-audit.mjs', summary: '只跑页面结构护栏' },
+}
+
+/**
+ * 解析命令行：只认 `COMMANDS` 里的子命令，未知子命令**显式报错**
+ * （静默忽略会让人以为命令生效了，而护栏其实没跑）。
+ */
+export function parseCommand(argv = []) {
+  const [first = '', ...rest] = argv
+  if (!first || first === 'help' || first === '--help' || first === '-h') return { kind: 'help' }
+  if (first === '--version' || first === '-v') return { kind: 'version' }
+  const command = COMMANDS[first]
+  if (!command) return { kind: 'unknown', command: first }
+  return { kind: 'run', name: first, script: command.script, args: rest }
+}
+
+export function usage(version = readVersion()) {
+  const lines = [
+    `appkit ${version} —— @manohub/app-kit 命令入口（在应用包根执行；npm 消费方用 npx 代替 pnpm exec）`,
+    '',
+    '用法：',
+    '  pnpm exec appkit <命令> [参数]',
+    '',
+    '命令：',
+  ]
+  for (const [name, command] of Object.entries(COMMANDS)) {
+    lines.push(`  ${name.padEnd(16)}${command.summary}`)
+  }
+  lines.push('  help            显示本帮助')
+  lines.push('  --version       显示版本号')
+  lines.push('')
+  lines.push('参数会原样透传给对应脚本（如 `appkit lint --changed --strict`）；退出码同样是脚本的退出码。')
+  return lines.join('\n')
+}
+
+/** 读包自身版本（`appkit --version` 用） */
+export function readVersion() {
+  try {
+    return JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version ?? 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+function main() {
+  const parsed = parseCommand(process.argv.slice(2))
+
+  if (parsed.kind === 'help') {
+    console.log(usage())
+    return
+  }
+  if (parsed.kind === 'version') {
+    console.log(readVersion())
+    return
+  }
+  if (parsed.kind === 'unknown') {
+    console.error(`[appkit] 未知命令：${parsed.command}\n\n${usage()}`)
+    process.exitCode = 1
+    return
+  }
+
+  const script = join(PKG_ROOT, parsed.script)
+  if (!existsSync(script)) {
+    console.error(`[appkit] 包内缺少脚本 ${parsed.script}（安装不完整？请重新安装 @manohub/app-kit）`)
+    process.exitCode = 1
+    return
+  }
+
+  // stdio 继承：护栏是给人看的（含彩色/实时输出），不要在这里再包一层缓冲
+  const result = spawnSync(process.execPath, [script, ...parsed.args], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+  })
+  process.exitCode = result.status ?? 1
+}
+
+// 仅在被直接执行时跑；被测试 import 时只取纯函数
+if (isDirectRun(process.argv[1], import.meta.url)) {
+  main()
+}

package/lint/__tests__/guardrails.spec.mjs

@@ -41,6 +41,28 @@ function runAudit(script, cwd) {
   return { code: res.status, out: (res.stdout ?? '') + (res.stderr ?? '') }
 }
 
+/** 同上，但可追加参数（如 --strict / --json） */
+function runAuditWith(script, cwd, extraArgs = []) {
+  const res = spawnSync(process.execPath, [join(LINT, script), '--cwd=' + cwd, ...extraArgs], {
+    encoding: 'utf8',
+  })
+  return { code: res.status, out: (res.stdout ?? '') + (res.stderr ?? '') }
+}
+
+/** 改写临时消费仓的护栏配置（其余字段保持默认） */
+function writeConfig(root, apps, extra = {}) {
+  writeFileSync(
+    join(root, 'appkit-guardrails.config.json'),
+    JSON.stringify({
+      apps,
+      srcGlobs: ['src/**/*.ts', 'src/**/*.tsx'],
+      styleGlobs: ['src/**/*.css'],
+      ignore: ['node_modules', 'dist'],
+      ...extra,
+    }),
+  )
+}
+
 test('glob：嵌套路径必须匹配（防「只扫顶层文件」的静默漏扫）', async () => {
   const { globToRegExp } = await import('../shared.mjs')
   const src = globToRegExp('src/**/*.tsx')
@@ -52,6 +74,33 @@ test('glob：嵌套路径必须匹配（防「只扫顶层文件」的静默漏
   assert.ok(css.test('src/features/x/y.css'), '深层 css 应匹配')
 })
 
+test('changedFiles：未暂存的新增文件必须纳入（否则「新增文件必须归零」会假绿）', async () => {
+  const { changedFiles } = await import('../shared.mjs')
+  const root = mkdtempSync(join(tmpdir(), 'appkit-changed-'))
+  const git = (...args) => spawnSync('git', args, { cwd: root, encoding: 'utf8' })
+  try {
+    if (git('init', '-q', '.').status !== 0) return // 无 git：跳过（本机的护栏自测仍覆盖其余规则）
+    git('config', 'user.email', 'guardrails@test')
+    git('config', 'user.name', 'guardrails')
+    writeFileSync(join(root, 'tracked.ts'), 'export const a = 1\n')
+    assert.equal(git('add', 'tracked.ts').status, 0)
+    if (git('commit', '-qm', 'init').status !== 0) return // 提交失败（无身份/无 hooks 环境）：跳过
+
+    writeFileSync(join(root, 'untracked-new.ts'), 'export const b = 2\n')
+    const changed = changedFiles(root)
+    assert.ok(changed, '仓库内应返回改动集合（null 表示非 git 环境）')
+    assert.ok(
+      changed.has('untracked-new.ts'),
+      `未 git add 的新增文件必须进集合，实际：${[...changed].join(', ')}`,
+    )
+
+    writeFileSync(join(root, 'tracked.ts'), 'export const a = 2\n')
+    assert.ok(changedFiles(root).has('tracked.ts'), '已跟踪文件的改动仍须进集合')
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
 test('违规样本：三条护栏都必须报错，且每条违规都带 correction', () => {
   const root = makeConsumer('violations-src')
   try {
@@ -133,6 +182,111 @@ test('pending 应用：照常报告但不计入退出码', () => {
   }
 })
 
+test('规则级豁免：只迁骨架（Shell-only）时，结构类纳入门禁、组件与样式类登记豁免', () => {
+  const root = makeConsumer('violations-src')
+  try {
+    // 只迁骨架：结构类立刻要合规（本 fixture 结构违规很多 → 必须仍拦断），
+    // 组件直连与样式类先登记豁免。
+    writeConfig(root, [
+      {
+        dir: 'app',
+        name: 'fixture-app',
+        prefixes: ['other-'],
+        pending: false,
+        waivedRules: [
+          { rule: 'api/*', reason: 'Shell-only：组件替换在下一批次', since: '2026-09-18' },
+          { rule: 'style/*', reason: '同上：样式收口等骨架稳定后', since: '2026-09-18' },
+        ],
+      },
+    ])
+
+    // component-audit：违规只剩豁免项 → 退出码 0，但**照常报告**（技术债必须可见）
+    const component = runAudit('component-audit.mjs', root)
+    assert.equal(component.code, 0, '豁免后不应拦断')
+    assert.ok(component.out.includes('api/farris-import'), '豁免项仍必须出现在报告里')
+    assert.ok(component.out.includes('豁免：已登记'), '豁免项要标明「已登记」')
+    assert.ok(component.out.includes('条属已登记豁免'), '汇总行要给出豁免条数')
+
+    // style-audit：同理（样式类整类豁免）
+    const style = runAudit('style-audit.mjs', root)
+    assert.equal(style.code, 0)
+    assert.ok(style.out.includes('style/visual'))
+
+    // structure-audit：没有豁免 → 结构类违规仍拦断（这才是「只迁骨架」的门禁）
+    const structure = runAudit('structure-audit.mjs', root)
+    assert.equal(structure.code, 1, '结构类规则未豁免，必须仍然拦断')
+    assert.ok(structure.out.includes('structure/no-shell'))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('规则级豁免：--strict 时豁免一律失效（收口验收口径）', () => {
+  const root = makeConsumer('violations-src')
+  try {
+    writeConfig(root, [
+      {
+        dir: 'app',
+        name: 'fixture-app',
+        prefixes: ['other-'],
+        pending: true,
+        waivedRules: [{ rule: 'style/*', reason: '分阶段迁移', since: '2026-09-18' }],
+      },
+    ])
+    assert.equal(runAudit('style-audit.mjs', root).code, 0, '平时：豁免 + 挂起 → 不拦断')
+    assert.equal(runAuditWith('style-audit.mjs', root, ['--strict']).code, 1, '--strict：豁免与挂起都失效')
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('规则级豁免：0 条命中时提示可撤销（豁免只该在「还没迁到那层」期间存在）', () => {
+  const root = makeConsumer('clean-src')
+  try {
+    writeConfig(root, [
+      {
+        dir: 'app',
+        name: 'fixture-app',
+        prefixes: ['other-'],
+        pending: false,
+        waivedRules: [{ rule: 'api/*', reason: '上一批次留下的', since: '2026-09-01' }],
+      },
+    ])
+    const { code, out } = runAudit('component-audit.mjs', root)
+    assert.equal(code, 0)
+    assert.ok(out.includes('可以撤销'), `0 条命中应提示撤销，实际输出：${out}`)
+    assert.ok(out.includes('api/*'))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('规则级豁免：配置缺 reason 时直接报错（不留静音键）', () => {
+  const root = makeConsumer('clean-src')
+  try {
+    writeConfig(root, [
+      { dir: 'app', name: 'fixture-app', prefixes: ['other-'], waivedRules: [{ rule: 'api/*' }] },
+    ])
+    const { code, out } = runAudit('component-audit.mjs', root)
+    assert.equal(code, 2, '配置错误应走「环境问题」退出码，而不是静默通过')
+    assert.ok(out.includes('缺少 reason'))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('matchRule：精确名与整类通配各按各的匹配，不做中间通配', async () => {
+  const { matchRule } = await import('../shared.mjs')
+  assert.equal(matchRule('api/farris-import', 'api/farris-import'), true)
+  assert.equal(matchRule('api/*', 'api/legacy-prop'), true)
+  assert.equal(matchRule('api/*', 'style/visual'), false)
+  assert.equal(matchRule('structure/*', 'structure/no-shell'), true)
+  // 中间通配不实现：写出来会让人以为能精确匹配
+  assert.equal(matchRule('style/*-element', 'style/bare-element'), false)
+  assert.equal(matchRule('', 'api/legacy-prop'), false)
+  assert.equal(matchRule(undefined, 'api/legacy-prop'), false)
+})
+
 test('--changed：非 git 环境下不裁剪（宁可多检查）', () => {
   const root = makeConsumer('violations-src')
   try {

package/lint/component-audit.mjs

@@ -13,7 +13,7 @@
  *     `selection={{…}}` 是 app-kit 自己的结构化契约，**合法**；
  *     而 `rowOption` / `columnOption` / `enableSelectRow` / `enabelSelectRow` 等属于底层，一律禁止。
  *
- * 用法：node node_modules/@manohub/app-kit/lint/component-audit.mjs [--json] [--changed]
+ * 用法：pnpm exec appkit lint:component [--json] [--changed]
  */
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'

package/lint/guardrails.config.schema.json

@@ -30,6 +30,34 @@
             "type": "boolean",
             "default": false,
             "description": "存量挂起：为 true 时该应用仅产出基线报告，不计入退出码（迁移完成后置 false 即自动纳入门禁）。"
+          },
+          "waivedRules": {
+            "type": "array",
+            "description": "规则级豁免（**分阶段迁移**用，典型是「只迁骨架 / Shell-only」）：登记的规则照常报告但不计入退出码。要收口时跑 `--strict` 验证，并在撤销豁免后纳入门禁。规则名支持 `域/*` 整类通配（如 structure/*）；每条必须写 reason。",
+            "items": {
+              "oneOf": [
+                { "type": "string", "description": "简写形式（不推荐：没有理由，无法审计）" },
+                {
+                  "type": "object",
+                  "required": ["rule", "reason"],
+                  "properties": {
+                    "rule": {
+                      "type": "string",
+                      "description": "规则名（如 api/farris-import）或整类通配（如 style/*）。"
+                    },
+                    "reason": {
+                      "type": "string",
+                      "description": "为什么暂时不查 + 什么时候收口（如「只迁骨架，组件替换在下一批次」）。必填。"
+                    },
+                    "since": {
+                      "type": "string",
+                      "description": "登记日期（ISO 8601，如 2026-09-18）。"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ]
+            }
           }
         }
       }
@@ -69,6 +97,20 @@
       "exemptionRegistry": "docs/appkit-exemptions.md",
       "contractDoc": "node_modules/@manohub/app-kit/CONTRACT.md",
       "ignore": ["node_modules", "dist"]
+    },
+    {
+      "apps": [
+        {
+          "dir": ".",
+          "name": "shell-only-app",
+          "prefixes": ["so-"],
+          "pending": false,
+          "waivedRules": [
+            { "rule": "api/*", "reason": "只迁骨架（Shell-only）：组件替换在下一批次", "since": "2026-09-18" },
+            { "rule": "style/*", "reason": "同上：样式收口等骨架稳定后再做", "since": "2026-09-18" }
+          ]
+        }
+      ]
     }
   ]
 }