@manohub/kit 0.7.1 → 0.8.1

package/skills/{kit-dev → manohub-kit-dev}/SKILL.md

@@ -1,117 +1,117 @@
----
-name: kit-dev
-version: 1.0.0
-description: 按 @manohub/kit 骨架层规范做日常页面与组件开发：选页面模板、选组件与 prop、守样式纪律、处置缺件、收工前自检。触发条件：用户要求写或改子应用页面、要求按骨架层规范实现列表页/表单/弹窗/树/分页/加载空错三态、指定用 Page/Panel/Table/Form 等组件库件、或询问某个页面写法是否正确时使用。
----
-
-# kit-dev：日常开发辅助
-
-面向**已接入**骨架层的应用。任务是把需求落到「契约允许的写法」上，而不是边写边试。
-
-组件本身有哪些 prop —— 查 `node_modules/@manohub/ui/README.md` 与类型声明；
-本技能管的是**页面怎么搭**。**合规判据在契约里，本技能不复述条款。**
-
-## 一、开工前必做
-
-1. 读 `node_modules/@manohub/kit/CONTRACT.md` 的相关章节（用 `../kit/references/contract-index.md` 按主题定位）。
-   **优先级**：契约 > `@manohub/ui` 的 README 与 `@example`（`node_modules/@manohub/ui/dist/**/*.d.ts`）
-   > 消费仓 `AGENTS.md` > 其它文档；冲突时按此优先级执行。
-2. 先定四件事，再动手写：**页面模板**、**两级滚动归属**、**操作位**、**分页归属**（都在契约 §5）。
-   这四件错了，组件用得再对也要返工。
-3. 组件不存在时先查契约 §8 缺件处置流程（那里给了替代口径与登记方式），
-   **不在应用侧自绘近似件，也不回去直连底层组件库**。
-
-## 二、按意图取配方
-
-配方文件给的是**可直接抄的形状**；判据仍在契约。
-
-| 需求 | 取用 |
-|---|---|
-| 新页面（列表 / 表单 / 双栏） | `references/page-recipes.md`「页面模板」；起手式见契约 §5 末「三种页面模板」 |
-| 表格、筛选、分页、多选 | `references/page-recipes.md`「表格」；操作位与滚动归属见契约 §5「组 4 · 区域」 |
-| 表单、校验、只读摘要行 | `references/page-recipes.md`「表单」；契约 §5「组 5 · 版式」 |
-| 弹窗 / 抽屉 / 命令式提示 | `references/page-recipes.md`「浮层与提示」；契约 §6 |
-| 树、导航、卡片单选、步骤条 | `references/page-recipes.md`「树 / 卡片单选 / 步骤条」；契约 §6 |
-| 加载 / 空 / 错三态 | `references/page-recipes.md`「三态」；契约 §5「组 5」 |
-| 行 / 列怎么排、间距档 | `references/page-recipes.md`「布局」；契约 §5「组 5」 |
-| 样式怎么写、哪些禁止 | 契约 §3 L1（含属性白名单与局部换肤）；`references/style-rules.md` 给替代写法 |
-| 图标怎么用 | 契约 §4 L1.5 |
-| 某个写法是不是违规 | 读契约对应层的「正误对照」段，不要凭经验判断 |
-
-## 三、改代码前先读（判据都在契约里）
-
-| 你要动什么 | 先读 |
-|---|---|
-| 页面结构（加 / 挪成员、改页头、调滚动归属、放筛选与分页、表单分栏） | 契约 §5 L2 |
-| 任何 CSS 属性（含「只是想微调一下外观」的念头） | 契约 §3 L1（判据）+ `references/style-rules.md`（替代写法） |
-| 挑件、传 prop、换外观档位 | 契约 §6 L3；件名与成员以 `.d.ts` 为准 |
-| 加图标 | 契约 §4 L1.5 |
-| 入口 / 容器锚 / 依赖来源 | 契约 §2 L0 —— **这一层不可豁免**：漏了它，上面三层写得再对也不生效 |
-
-三件最容易出错的**事实**（判据见契约，这里只提醒它们存在）：
-
-1. **受控口径**：表单与选择族「传 `modelValue` 即受控，不传即由 `defaultValue` 起」——
-   别把值藏在组件内部再通过 ref 读（细节见契约 §6）。
-2. **骨架职责不在应用侧**：入口编排、pinia、路由、微前端协议、宿主语言监听都由工厂装配；
-   自己再写一份会和工厂的协议打架（细节见契约 §2）。
-3. **浮层有对应的件与服务**：模态 / 抽屉 / 命令式提示各有归属，自己写遮罩拿不到令牌，
-   也逃不过微前端的 `scopecss`（细节见契约 §6）。
-
-## 四、本包不管的三件事（别在这里找写法）
-
-1. **数据获取**：走消费仓既有方式（`@tanstack/vue-query` / 自建 api 层）。本包只**收结果** ——
-   把 `isLoading` / `error` / `data` 映射到 `QueryState` 的 `loading` / `error` / `empty`
-   与 `Table` 的 `data`，不要为「加载中」自绘遮罩或骨架，也不要引入新的请求库。
-2. **文案与 i18n**：`createSubApp({ i18n: { messages } })` 是 **vue-i18n** 语义，文案用 `useI18n()` 的 `t()`；
-   实例由骨架层唯一创建并注册，应用侧**不要自己 `createI18n`**（契约 §9）。
-   组件内建的中文只是兜底，页面文案一律自己传。
-3. **路由与权限**：路由表由应用维护并交给 `createSubApp({ routes })`；权限判断、菜单、面包屑属消费仓。
-
-## 五、`.vue`（SFC）项目怎么用这些配方
-
-配方以 TSX 书写（消费方主流形态）。SFC 项目按等价转写：
-
-| TSX 配方 | SFC 写法 |
-|---|---|
-| `modelValue={x} onChange={(v) => (x = v)}` | `:model-value="x" @change="x = $event"`（或 `v-model`） |
-| `extra={() => <span/>}` | `<template #extra><span/></template>` |
-| `footer={() => <>…</>}` | `<template #footer>…</template>` |
-| `columns={cols}` + `#cell` 插槽 | 列定义放 `setup` 的常量；单元格内容走 `<template #cell="{ row, column, value }">` |
-| `Layout.Row` / `Layout.Column` | `<Layout.Row>` / `<Layout.Column>`（点号成员在模板里直接可用） |
-
-⚠️ **结构合规靠自检，不靠工具** —— 0.6.0 起没有机器规则兜底，SFC 与 TSX 一视同仁：
-收工前必须**人工过一遍契约 §7 自检清单**，并按 §5 的骨架条款核对页面结构
-（尤其「成员必须是 `Page` 直接子节点」这一条：`<template v-if>` 包一层就认不出成员）。
-
-## 六、收工前自检（必做）
-
-```bash
-pnpm exec vue-tsc --noEmit        # 类型
-pnpm build                        # 构建
-```
-
-然后是**人工过契约 §7 自检清单**（全是能直接回答的问句，逐条答，不要跳过）：
-
-- L0 / L1 / L1.5 / L2 / L3 五组问句，每组对应一层；答不上来的就回去读该层条款。
-- 「本条答不出」＝ 你自己也不知道这段代码在做什么，先搞清再提交，不要靠猜。
-- 新增文件**必须整份合规**；改动文件至少保证**本次改动没有引入新的违规**。
-
-## 七、失败处理
-
-| 现象 | 处理 |
-|---|---|
-| 想要的组件 / 能力不存在 | 先查契约 §8（替代口径与登记方式），仍不够就提缺件；应用侧不自绘 |
-| 表单里要日期 / 数字控件 | 组件库暂无这两件；按契约 §8 用 `Input` 顶住并标注格式，或提缺件 |
-| 组件渲染了但样式不对 | 检查 `src/style.css` 三行的导入与顺序（契约 §1.2，本包已不转发样式）；不要在页面里补视觉样式 |
-| 视觉想「微调一下」 | 走契约 §3 的**局部换肤**（在更深容器重设**已有**令牌的值）或用语义 prop；**不得**发明新令牌名 |
-| 命令式提示样式全丢 | 提示没落回应用容器：确认入口走的是 `createSubApp`，别自己手写 `createApp` |
-| `showLoading` 关不掉 | 引用计数没配平：用返回的句柄在 `finally` 里关，别用「开始显示 / 结束隐藏」的一对布尔 |
-| 页面结构对不对拿不准 | 读契约 §5 的骨架条款 + 「三种页面模板」，别猜；SFC 没有工具兜底 |
-
-## 八、参考
-
-- `../kit/references/contract-index.md`：按主题定位契约章节
-- `references/page-recipes.md`：页面模板与高频场景配方
-- `references/style-rules.md`：样式纪律的替代写法（判据以契约 §3 为准）
-- `node_modules/@manohub/ui/README.md`：组件清单与 API 入口
-- `node_modules/@manohub/kit/CONTRACT.md`：规范唯一事实源（§7 是收工自检清单）
+---
+name: manohub-kit-dev
+version: 1.0.0
+description: 按 @manohub/kit 骨架层规范做日常页面与组件开发：选页面模板、选组件与 prop、守样式纪律、处置缺件、收工前自检。触发条件：用户要求写或改子应用页面、要求按骨架层规范实现列表页/表单/弹窗/树/分页/加载空错三态、指定用 Page/Panel/Table/Form 等组件库件、或询问某个页面写法是否正确时使用。
+---
+
+# manohub-kit-dev：日常开发辅助
+
+面向**已接入**骨架层的应用。任务是把需求落到「契约允许的写法」上，而不是边写边试。
+
+组件本身有哪些 prop —— 查 `node_modules/@manohub/ui/README.md` 与类型声明；
+本技能管的是**页面怎么搭**。**合规判据在契约里，本技能不复述条款。**
+
+## 一、开工前必做
+
+1. 读 `node_modules/@manohub/kit/CONTRACT.md` 的相关章节（用 `../manohub-kit/references/contract-index.md` 按主题定位）。
+   **优先级**：契约 > `@manohub/ui` 的 README 与 `@example`（`node_modules/@manohub/ui/dist/**/*.d.ts`）
+   > 消费仓 `AGENTS.md` > 其它文档；冲突时按此优先级执行。
+2. 先定四件事，再动手写：**页面模板**、**两级滚动归属**、**操作位**、**分页归属**（都在契约 §5）。
+   这四件错了，组件用得再对也要返工。
+3. 组件不存在时先查契约 §8 缺件处置流程（那里给了替代口径与登记方式），
+   **不在应用侧自绘近似件，也不回去直连底层组件库**。
+
+## 二、按意图取配方
+
+配方文件给的是**可直接抄的形状**；判据仍在契约。
+
+| 需求 | 取用 |
+|---|---|
+| 新页面（列表 / 表单 / 双栏） | `references/page-recipes.md`「页面模板」；起手式见契约 §5 末「三种页面模板」 |
+| 表格、筛选、分页、多选 | `references/page-recipes.md`「表格」；操作位与滚动归属见契约 §5「组 4 · 区域」 |
+| 表单、校验、只读摘要行 | `references/page-recipes.md`「表单」；契约 §5「组 5 · 版式」 |
+| 弹窗 / 抽屉 / 命令式提示 | `references/page-recipes.md`「浮层与提示」；契约 §6 |
+| 树、导航、卡片单选、步骤条 | `references/page-recipes.md`「树 / 卡片单选 / 步骤条」；契约 §6 |
+| 加载 / 空 / 错三态 | `references/page-recipes.md`「三态」；契约 §5「组 5」 |
+| 行 / 列怎么排、间距档 | `references/page-recipes.md`「布局」；契约 §5「组 5」 |
+| 样式怎么写、哪些禁止 | 契约 §3 L1（含属性白名单与局部换肤）；`references/style-rules.md` 给替代写法 |
+| 图标怎么用 | 契约 §4 L1.5 |
+| 某个写法是不是违规 | 读契约对应层的「正误对照」段，不要凭经验判断 |
+
+## 三、改代码前先读（判据都在契约里）
+
+| 你要动什么 | 先读 |
+|---|---|
+| 页面结构（加 / 挪成员、改页头、调滚动归属、放筛选与分页、表单分栏） | 契约 §5 L2 |
+| 任何 CSS 属性（含「只是想微调一下外观」的念头） | 契约 §3 L1（判据）+ `references/style-rules.md`（替代写法） |
+| 挑件、传 prop、换外观档位 | 契约 §6 L3；件名与成员以 `.d.ts` 为准 |
+| 加图标 | 契约 §4 L1.5 |
+| 入口 / 容器锚 / 依赖来源 | 契约 §2 L0 —— **这一层不可豁免**：漏了它，上面三层写得再对也不生效 |
+
+三件最容易出错的**事实**（判据见契约，这里只提醒它们存在）：
+
+1. **受控口径**：表单与选择族「传 `modelValue` 即受控，不传即由 `defaultValue` 起」——
+   别把值藏在组件内部再通过 ref 读（细节见契约 §6）。
+2. **骨架职责不在应用侧**：入口编排、pinia、路由、微前端协议、宿主语言监听都由工厂装配；
+   自己再写一份会和工厂的协议打架（细节见契约 §2）。
+3. **浮层有对应的件与服务**：模态 / 抽屉 / 命令式提示各有归属，自己写遮罩拿不到令牌，
+   也逃不过微前端的 `scopecss`（细节见契约 §6）。
+
+## 四、本包不管的三件事（别在这里找写法）
+
+1. **数据获取**：走消费仓既有方式（`@tanstack/vue-query` / 自建 api 层）。本包只**收结果** ——
+   把 `isLoading` / `error` / `data` 映射到 `QueryState` 的 `loading` / `error` / `empty`
+   与 `Table` 的 `data`，不要为「加载中」自绘遮罩或骨架，也不要引入新的请求库。
+2. **文案与 i18n**：`createSubApp({ i18n: { messages } })` 是 **vue-i18n** 语义，文案用 `useI18n()` 的 `t()`；
+   实例由骨架层唯一创建并注册，应用侧**不要自己 `createI18n`**（契约 §9）。
+   组件内建的中文只是兜底，页面文案一律自己传。
+3. **路由与权限**：路由表由应用维护并交给 `createSubApp({ routes })`；权限判断、菜单、面包屑属消费仓。
+
+## 五、`.vue`（SFC）项目怎么用这些配方
+
+配方以 TSX 书写（消费方主流形态）。SFC 项目按等价转写：
+
+| TSX 配方 | SFC 写法 |
+|---|---|
+| `modelValue={x} onChange={(v) => (x = v)}` | `:model-value="x" @change="x = $event"`（或 `v-model`） |
+| `extra={() => <span/>}` | `<template #extra><span/></template>` |
+| `footer={() => <>…</>}` | `<template #footer>…</template>` |
+| `columns={cols}` + `#cell` 插槽 | 列定义放 `setup` 的常量；单元格内容走 `<template #cell="{ row, column, value }">` |
+| `Layout.Row` / `Layout.Column` | `<Layout.Row>` / `<Layout.Column>`（点号成员在模板里直接可用） |
+
+⚠️ **结构合规靠自检，不靠工具** —— 0.6.0 起没有机器规则兜底，SFC 与 TSX 一视同仁：
+收工前必须**人工过一遍契约 §7 自检清单**，并按 §5 的骨架条款核对页面结构
+（尤其「成员必须是 `Page` 直接子节点」这一条：`<template v-if>` 包一层就认不出成员）。
+
+## 六、收工前自检（必做）
+
+```bash
+pnpm exec vue-tsc --noEmit        # 类型
+pnpm build                        # 构建
+```
+
+然后是**人工过契约 §7 自检清单**（全是能直接回答的问句，逐条答，不要跳过）：
+
+- L0 / L1 / L1.5 / L2 / L3 五组问句，每组对应一层；答不上来的就回去读该层条款。
+- 「本条答不出」＝ 你自己也不知道这段代码在做什么，先搞清再提交，不要靠猜。
+- 新增文件**必须整份合规**；改动文件至少保证**本次改动没有引入新的违规**。
+
+## 七、失败处理
+
+| 现象 | 处理 |
+|---|---|
+| 想要的组件 / 能力不存在 | 先查契约 §8（替代口径与登记方式），仍不够就提缺件；应用侧不自绘 |
+| 表单里要日期 / 数字控件 | 组件库暂无这两件；按契约 §8 用 `Input` 顶住并标注格式，或提缺件 |
+| 组件渲染了但样式不对 | 检查 `src/style.css` 三行的导入与顺序（契约 §1.2，本包已不转发样式）；不要在页面里补视觉样式 |
+| 视觉想「微调一下」 | 走契约 §3 的**局部换肤**（在更深容器重设**已有**令牌的值）或用语义 prop；**不得**发明新令牌名 |
+| 命令式提示样式全丢 | 提示没落回应用容器：确认入口走的是 `createSubApp`，别自己手写 `createApp` |
+| `showLoading` 关不掉 | 引用计数没配平：用返回的句柄在 `finally` 里关，别用「开始显示 / 结束隐藏」的一对布尔 |
+| 页面结构对不对拿不准 | 读契约 §5 的骨架条款 + 「三种页面模板」，别猜；SFC 没有工具兜底 |
+
+## 八、参考
+
+- `../manohub-kit/references/contract-index.md`：按主题定位契约章节
+- `references/page-recipes.md`：页面模板与高频场景配方
+- `references/style-rules.md`：样式纪律的替代写法（判据以契约 §3 为准）
+- `node_modules/@manohub/ui/README.md`：组件清单与 API 入口
+- `node_modules/@manohub/kit/CONTRACT.md`：规范唯一事实源（§7 是收工自检清单）

package/skills/{kit-migrate → manohub-kit-migrate}/SKILL.md

@@ -1,125 +1,125 @@
----
-name: kit-migrate
-version: 1.0.0
-description: 把存量子应用改造到 @manohub/ui + @manohub/kit 骨架层（含清理 App* 旧组件名、.ak-* 样式与直连底层组件库的写法）：按契约分层盘点违规、划批次、逐文件替换、逐层收口、验收；也支持只迁一部分（典型是「只迁页面骨架」，其余层分批收口）。触发条件：用户要求迁移/改造/接入子应用、要求盘点或降低违规存量、要求先只迁页面骨架或分阶段迁移、或代码里出现 App* 组件名 / .ak-* 样式 / 直连 farris 需要清理时使用。
----
-
-# kit-migrate：存量应用改造
-
-把存量页面从「旧组件名 + `.ak-*` 样式 + 直连底层组件库」迁到「`@manohub/ui` 组件 +
-`@manohub/theme` 令牌」。
-
-分六阶段，每阶段都有可核对的产出。
-**替换对照表见 `references/migration-map.md`**；阶段细则、盘点登记格式与验收清单见 `references/migration-playbook.md`。
-
-> **0.6.0 起本包不再发布消费侧机器规则**（`kit lint` 三条护栏已下线）。
-> 改造的判据变成「契约条款 + §7 自检清单」，违规的**盘点与归零由人/代理按契约逐条过**，
-> 不再有自动拦断。这决定了两件事：① 阶段 1 的基线靠人工按层盘；② 阶段 3/4 的「归零」
-> 以**人工过 §7 清单**为证据，而不是一张 lint 退出码。
-
-## 阶段 0 · 摸清现状
-
-记下改造前的四个事实（写进应用文档，后面验收要用）：
-
-| 记录项 | 怎么取 |
-|---|---|
-| 基线版本 | 现装 `@manohub/kit`、`@manohub/ui`、`@manohub/theme` 的版本号 |
-| 页面清单 | `src/views/` 下的路由页，与页面内 `components/` 子目录的可复用件分开数 |
-| 组件用量 | 搜索 `App` 前缀组件名 / `.ak-` 样式 / `@farris/ui-vue` 的出现次数（三个数分开记） |
-| 构建与体积 | 一次生产构建的产物大小量级（验收时对比） |
-
-## 阶段 1 · 按契约分层盘点违规
-
-没有自动扫描了，所以这一步是**人工按层过**：打开 `CONTRACT.md`，逐层逐条对着代码盘。
-
-1. 装依赖：
-
-   ```bash
-   pnpm add @manohub/ui @manohub/theme
-   pnpm add @manohub/kit     # 若尚未接入
-   ```
-
-2. 建本仓的**命名空间表** `docs/kit-namespaces.md`（哪个应用占哪个类名前缀），
-   格式见 `references/migration-playbook.md`。这张表取代了旧配置里的 `prefixes`。
-3. 按契约的五层盘一遍，把命中记成条款级清单（`L0-3 / L1-5 / L2-12 …` 这个样子），
-   登记格式见 `references/migration-playbook.md`。**盘点是「改造前的事实」，不是「要修掉的清单」**。
-
-> 首次盘必然很多命中（`App*` 名字、`.ak-*` 样式、缺 `data-manohub-ui` 都会中），这是预期的。
-
-## 阶段 2 · 划定层级与批次
-
-**层序就是收口顺序**：L0 入口（漏了什么都没有）→ L1 值 → L1.5 图标 → L2 结构 → L3 件。
-
-但**存量的最优施工顺序**与层序相反 —— 先动结构、后动件、最后收样式，因为：
-
-1. **页面骨架**（`AppShell.*` → `Page.*`）：L2 立刻能整体收口，收益最大、风险最低。
-2. **组件逐件替换**（按 `references/migration-map.md`）：表格 / 分页 / 表单 / 弹窗优先，
-   它们的 prop 差异最大，改完能把大部分页面的阻塞解掉。
-3. **命令式服务替换**：`notify` / `messageBox` / `loading` / `modalService` → 服务层的
-   `toast()` / `confirm()` / `alert()` / `showLoading()`（**API 是重新设计的，逐处改写调用点**）。
-4. **样式收口**：删 `.ak-*` 覆写，残留的视觉意图翻成主题令牌。
-
-**只迁一部分时用「承诺层」表达**（不是豁免）：每批只承诺某几层全合规，其余层**不承诺**，
-并在应用文档里写明「本批承诺 L2；L1/L3 待第 N 批」。没有配置文件要改 —— 承诺写入应用文档即可。
-
-## 阶段 3 · 逐文件替换
-
-每个文件一轮：
-
-1. 按 `migration-map.md` 换组件名与 prop；
-2. **对照契约条款逐条改**：该文件涉及哪几层，就打开那几层的条款对着改；
-3. 跑类型检查，确保没有「两种同名类型不兼容」（那是装了两份依赖的信号）。
-
-- 契约的「正误对照」段是改法的直接依据；样式违规的处理原则：**能删就删**（迁移后不需要的覆盖段），
-  需要保留的改为布局属性或组件的 prop。
-
-## 阶段 4 · 逐层收口与验收
-
-| 检查 | 通过标准 |
-|---|---|
-| 已承诺的层 | 该层条款**逐条**对照代码过一遍，无命中（证据：清单里该层打勾，附文件清单） |
-| 未承诺的层 | 照常记录、数量不高于阶段 1 的盘点（写进应用文档） |
-| 类型 | `pnpm exec vue-tsc --noEmit` 0 错 |
-| 构建 | `pnpm build` 成功；产物大小与阶段 0 记录值量级一致（差异要能解释） |
-
-- **归零没有退出码了**，所以证据必须落在文档上：**每条打勾的条款都要能指出「哪些文件里没有它」**。
-  做不到就说明没真过一遍。
-- 下一批的起点 = 本轮未承诺层的盘点结果；收口顺序 = 层序（L0 → L1 → L1.5 → L2 → L3）。
-
-## 阶段 5 · 验收（缺一不可）
-
-1. 浏览器逐个过页面与弹窗：渲染、交互、样式、**弹层落点**。
-2. **命令式提示必须单独验**：`toast('success', 'ok')` 之后检查 DOM 里 `[data-manohub-ui]` 内有 `.mh-toast`
-   （不在容器内 = 样式会全丢）；`showLoading()` 之后必须能关掉（引用计数配平）。
-3. **特殊入口必须单独验**：以 `index.html?xxx=1` 直开的入口要在 `createSubApp` 的 `rootPathAliases`
-   里登记，否则首屏守卫会清空 query。
-4. 已知缺口如实判断是否属本次范围，不要误判为「漏改」：
-   - **没有任何工具会替你检查结构** —— SFC 与 TSX 一律人工过契约 §7 自检清单。
-   - 组件库尚未提供的件（契约 §8）只能按替代口径顶住，不得自绘。
-5. 结论记录到应用文档：改了什么、验收证据、遗留项。
-
-## 阶段 6 · 收尾登记
-
-- 基线文档更新为「迁移后：0」并写明日期；未承诺层的清单留作下一批起点。
-- 在应用 `AGENTS.md` 里补充「本应用已接入骨架层」与本次改造的关键结论。
-- 命名空间表落 `docs/kit-namespaces.md`（若本仓有多个子应用，逐个登记前缀）。
-
-## 失败处理
-
-| 现象 | 处理 |
-|---|---|
-| 改动文件仍不合规 | 读契约该层的条款与「正误对照」段；仍不解就在应用文档里记为待定，不要自创等价写法 |
-| 组件疑似缺失 | 走契约 §8 缺件处置流程；不要在应用侧自绘，也不要回去直连底层组件库 |
-| 替换后视觉与改造前不一致 | 先确认是不是「旧写法本来就在覆写组件内部类」（那种覆写删掉即可）；确属缺能力 → 记录待建件 |
-| 类型出现「两种同名类型不兼容」 | 检查是否装了两份 vue / 依赖重复；按 `../kit/references/adoption.md` 的单例收敛处理 |
-| 命令式提示样式全丢 | 提示没落回应用容器：确认入口走的是 `createSubApp`（写 `data-manohub-ui`），或显式 `configureHost(el)` |
-| 分页页码整体差 1 | 旧 `page` 是 0 基、新 `Pagination.modelValue` 是 1 基（`migration-map.md` 的 Pagination 一节） |
-| 想找「跑一条命令看还剩多少违规」 | 没有了 —— 按阶段 4 的分层盘点口径人工过，成果记在应用文档 |
-
-## 参考
-
-- `references/migration-map.md`：替换映射表（旧写法 → 新写法 → 注意事项），按类目查
-- `references/migration-playbook.md`：阶段细则、命名空间表与盘点登记格式、收口口径、验收清单、**「只迁骨架」变体路径**
-- `../kit/references/adoption.md`：接入 SOP
-- `node_modules/@manohub/ui/README.md`：组件清单与服务层 API
-- `node_modules/@manohub/kit/CONTRACT.md`：规范唯一事实源（§7 是自检清单，§12 是升级说明）
+---
+name: manohub-kit-migrate
+version: 1.0.0
+description: 把存量子应用改造到 @manohub/ui + @manohub/kit 骨架层（含清理 App* 旧组件名、.ak-* 样式与直连底层组件库的写法）：按契约分层盘点违规、划批次、逐文件替换、逐层收口、验收；也支持只迁一部分（典型是「只迁页面骨架」，其余层分批收口）。触发条件：用户要求迁移/改造/接入子应用、要求盘点或降低违规存量、要求先只迁页面骨架或分阶段迁移、或代码里出现 App* 组件名 / .ak-* 样式 / 直连 farris 需要清理时使用。
+---
+
+# manohub-kit-migrate：存量应用改造
+
+把存量页面从「旧组件名 + `.ak-*` 样式 + 直连底层组件库」迁到「`@manohub/ui` 组件 +
+`@manohub/theme` 令牌」。
+
+分六阶段，每阶段都有可核对的产出。
+**替换对照表见 `references/migration-map.md`**；阶段细则、盘点登记格式与验收清单见 `references/migration-playbook.md`。
+
+> **0.6.0 起本包不再发布消费侧机器规则**（`kit lint` 三条护栏已下线）。
+> 改造的判据变成「契约条款 + §7 自检清单」，违规的**盘点与归零由人/代理按契约逐条过**，
+> 不再有自动拦断。这决定了两件事：① 阶段 1 的基线靠人工按层盘；② 阶段 3/4 的「归零」
+> 以**人工过 §7 清单**为证据，而不是一张 lint 退出码。
+
+## 阶段 0 · 摸清现状
+
+记下改造前的四个事实（写进应用文档，后面验收要用）：
+
+| 记录项 | 怎么取 |
+|---|---|
+| 基线版本 | 现装 `@manohub/kit`、`@manohub/ui`、`@manohub/theme` 的版本号 |
+| 页面清单 | `src/views/` 下的路由页，与页面内 `components/` 子目录的可复用件分开数 |
+| 组件用量 | 搜索 `App` 前缀组件名 / `.ak-` 样式 / `@farris/ui-vue` 的出现次数（三个数分开记） |
+| 构建与体积 | 一次生产构建的产物大小量级（验收时对比） |
+
+## 阶段 1 · 按契约分层盘点违规
+
+没有自动扫描了，所以这一步是**人工按层过**：打开 `CONTRACT.md`，逐层逐条对着代码盘。
+
+1. 装依赖：
+
+   ```bash
+   pnpm add @manohub/ui @manohub/theme
+   pnpm add @manohub/kit     # 若尚未接入
+   ```
+
+2. 建本仓的**命名空间表** `docs/kit-namespaces.md`（哪个应用占哪个类名前缀），
+   格式见 `references/migration-playbook.md`。这张表取代了旧配置里的 `prefixes`。
+3. 按契约的五层盘一遍，把命中记成条款级清单（`L0-3 / L1-5 / L2-12 …` 这个样子），
+   登记格式见 `references/migration-playbook.md`。**盘点是「改造前的事实」，不是「要修掉的清单」**。
+
+> 首次盘必然很多命中（`App*` 名字、`.ak-*` 样式、缺 `data-manohub-ui` 都会中），这是预期的。
+
+## 阶段 2 · 划定层级与批次
+
+**层序就是收口顺序**：L0 入口（漏了什么都没有）→ L1 值 → L1.5 图标 → L2 结构 → L3 件。
+
+但**存量的最优施工顺序**与层序相反 —— 先动结构、后动件、最后收样式，因为：
+
+1. **页面骨架**（`AppShell.*` → `Page.*`）：L2 立刻能整体收口，收益最大、风险最低。
+2. **组件逐件替换**（按 `references/migration-map.md`）：表格 / 分页 / 表单 / 弹窗优先，
+   它们的 prop 差异最大，改完能把大部分页面的阻塞解掉。
+3. **命令式服务替换**：`notify` / `messageBox` / `loading` / `modalService` → 服务层的
+   `toast()` / `confirm()` / `alert()` / `showLoading()`（**API 是重新设计的，逐处改写调用点**）。
+4. **样式收口**：删 `.ak-*` 覆写，残留的视觉意图翻成主题令牌。
+
+**只迁一部分时用「承诺层」表达**（不是豁免）：每批只承诺某几层全合规，其余层**不承诺**，
+并在应用文档里写明「本批承诺 L2；L1/L3 待第 N 批」。没有配置文件要改 —— 承诺写入应用文档即可。
+
+## 阶段 3 · 逐文件替换
+
+每个文件一轮：
+
+1. 按 `migration-map.md` 换组件名与 prop；
+2. **对照契约条款逐条改**：该文件涉及哪几层，就打开那几层的条款对着改；
+3. 跑类型检查，确保没有「两种同名类型不兼容」（那是装了两份依赖的信号）。
+
+- 契约的「正误对照」段是改法的直接依据；样式违规的处理原则：**能删就删**（迁移后不需要的覆盖段），
+  需要保留的改为布局属性或组件的 prop。
+
+## 阶段 4 · 逐层收口与验收
+
+| 检查 | 通过标准 |
+|---|---|
+| 已承诺的层 | 该层条款**逐条**对照代码过一遍，无命中（证据：清单里该层打勾，附文件清单） |
+| 未承诺的层 | 照常记录、数量不高于阶段 1 的盘点（写进应用文档） |
+| 类型 | `pnpm exec vue-tsc --noEmit` 0 错 |
+| 构建 | `pnpm build` 成功；产物大小与阶段 0 记录值量级一致（差异要能解释） |
+
+- **归零没有退出码了**，所以证据必须落在文档上：**每条打勾的条款都要能指出「哪些文件里没有它」**。
+  做不到就说明没真过一遍。
+- 下一批的起点 = 本轮未承诺层的盘点结果；收口顺序 = 层序（L0 → L1 → L1.5 → L2 → L3）。
+
+## 阶段 5 · 验收（缺一不可）
+
+1. 浏览器逐个过页面与弹窗：渲染、交互、样式、**弹层落点**。
+2. **命令式提示必须单独验**：`toast('success', 'ok')` 之后检查 DOM 里 `[data-manohub-ui]` 内有 `.mh-toast`
+   （不在容器内 = 样式会全丢）；`showLoading()` 之后必须能关掉（引用计数配平）。
+3. **特殊入口必须单独验**：以 `index.html?xxx=1` 直开的入口要在 `createSubApp` 的 `rootPathAliases`
+   里登记，否则首屏守卫会清空 query。
+4. 已知缺口如实判断是否属本次范围，不要误判为「漏改」：
+   - **没有任何工具会替你检查结构** —— SFC 与 TSX 一律人工过契约 §7 自检清单。
+   - 组件库尚未提供的件（契约 §8）只能按替代口径顶住，不得自绘。
+5. 结论记录到应用文档：改了什么、验收证据、遗留项。
+
+## 阶段 6 · 收尾登记
+
+- 基线文档更新为「迁移后：0」并写明日期；未承诺层的清单留作下一批起点。
+- 在应用 `AGENTS.md` 里补充「本应用已接入骨架层」与本次改造的关键结论。
+- 命名空间表落 `docs/kit-namespaces.md`（若本仓有多个子应用，逐个登记前缀）。
+
+## 失败处理
+
+| 现象 | 处理 |
+|---|---|
+| 改动文件仍不合规 | 读契约该层的条款与「正误对照」段；仍不解就在应用文档里记为待定，不要自创等价写法 |
+| 组件疑似缺失 | 走契约 §8 缺件处置流程；不要在应用侧自绘，也不要回去直连底层组件库 |
+| 替换后视觉与改造前不一致 | 先确认是不是「旧写法本来就在覆写组件内部类」（那种覆写删掉即可）；确属缺能力 → 记录待建件 |
+| 类型出现「两种同名类型不兼容」 | 检查是否装了两份 vue / 依赖重复；按 `../manohub-kit/references/adoption.md` 的单例收敛处理 |
+| 命令式提示样式全丢 | 提示没落回应用容器：确认入口走的是 `createSubApp`（写 `data-manohub-ui`），或显式 `configureHost(el)` |
+| 分页页码整体差 1 | 旧 `page` 是 0 基、新 `Pagination.modelValue` 是 1 基（`migration-map.md` 的 Pagination 一节） |
+| 想找「跑一条命令看还剩多少违规」 | 没有了 —— 按阶段 4 的分层盘点口径人工过，成果记在应用文档 |
+
+## 参考
+
+- `references/migration-map.md`：替换映射表（旧写法 → 新写法 → 注意事项），按类目查
+- `references/migration-playbook.md`：阶段细则、命名空间表与盘点登记格式、收口口径、验收清单、**「只迁骨架」变体路径**
+- `../manohub-kit/references/adoption.md`：接入 SOP
+- `node_modules/@manohub/ui/README.md`：组件清单与服务层 API
+- `node_modules/@manohub/kit/CONTRACT.md`：规范唯一事实源（§7 是自检清单，§12 是升级说明）