@teamix-evo/skills 0.10.2 → 0.11.1

package/src/teamix-evo-manage/SKILL.md

@@ -490,11 +490,11 @@ npx teamix-evo ui promote-to-biz --staging-dir <path>  # 指定 staging 目录
 
 **触发**:用户说"卸载 teamix-evo / remove the design system"。
 
-| 范围                                          | 命令                                                                |
-| --------------------------------------------- | ------------------------------------------------------------------- |
-| Tokens                                        | `npx teamix-evo tokens uninstall [-y] [--keep-files] [--purge]`     |
-| Skills                                        | `npx teamix-evo skills uninstall [-y]`                              |
-| (UI 不提供卸载,组件源码用户拥有 → 用户手动删) |                                                                     |
+| 范围                                          | 命令                                                            |
+| --------------------------------------------- | --------------------------------------------------------------- |
+| Tokens                                        | `npx teamix-evo tokens uninstall [-y] [--keep-files] [--purge]` |
+| Skills                                        | `npx teamix-evo skills uninstall [-y]`                          |
+| (UI 不提供卸载,组件源码用户拥有 → 用户手动删) |                                                                 |
 
 `tokens uninstall` 默认保留 `frozen` + `managed` 文件以保护用户编辑;`--keep-files` 完全保留物理文件只清 manifest;`--purge` 连 `frozen` 文件也删除。
 
@@ -508,11 +508,38 @@ npx teamix-evo ui promote-to-biz --staging-dir <path>  # 指定 staging 目录
 
 #### Phase A · 信息收集
 
-1. **询问旧项目路径** — 向用户索取旧项目的**绝对路径**（`<old-path>`）。可选附加：旧项目运行后的可访问 URL（用于后续截图 / 功能比对）。
+1. **询问三轨材料** — 一次性向用户索取迁移所需的三轨材料：
+
+   a. **旧项目源码路径** — 旧项目的**绝对路径**（`<old-path>`）
+   b. **Repo-wiki** — 旧项目的 repo-wiki（路径或确认已生成）
+   c. **页面截图目录** — 用户预先准备的页面截图目录路径
+
+   向用户提示截图准备建议话术：
+
+   > "请使用默认浏览器访问待迁移项目 URL，对所有页面以及页面的弹窗、抽屉进行截图，按页面路由为文件夹名字落地，并提供该截图位置目录。"
+
+   截图目录结构建议（用户通过 Qoder 工作区截图存放）：
+
+   ```
+   <screenshots-dir>/
+   ├── home/
+   │   ├── default.png
+   │   └── dialog-create.png
+   ├── list/
+   │   ├── default.png
+   │   ├── drawer-detail.png
+   │   └── dialog-delete.png
+   └── settings/
+       └── default.png
+   ```
+
+   > ⚠️ **AI 不执行截图操作**。截图由用户在 Qoder 工作区自行完成并提供目录路径。AI 仅使用用户提供的截图作为视觉参考。
+
 2. **检测 repo-wiki** — 检查 `<old-path>/.qoder/repowiki/` 是否存在且非空：
    - 存在 → 进入步骤 3。
    - 不存在 → 告知用户："旧项目尚未生成 repo-wiki，请先在旧项目目录使用 Qoder 生成 repo-wiki，完成后告诉我。"等待用户确认后重检。
 3. **读取 repo-wiki** — 增量读取 `<old-path>/.qoder/repowiki/` 目录内容。优先读中文版（`repowiki/zh/`），其次英文版（`repowiki/en/`）。按文件名语义识别：
+
    - 项目总览 / 概述
    - 目录结构 / 模块划分
    - 页面 / 路由清单
@@ -521,11 +548,15 @@ npx teamix-evo ui promote-to-biz --staging-dir <path>  # 指定 staging 目录
    - 依赖清单
 
    > 不一次性读完全部内容（token 预算有限）。先读概览 + 路由，后续按需深入。
-4. **补充读取**（若 repo-wiki 不完整）— 直接读旧项目的：
+
+4. **检测截图目录** — 检查用户提供的截图目录是否存在且非空：
+   - 存在且含截图 → 记录路径，进入步骤 5。
+   - 不存在或为空 → 告知用户截图目录不可用，请先按建议完成截图后再继续。
+5. **补充读取**（若 repo-wiki 不完整）— 直接读旧项目的：
    - `package.json`（依赖 / scripts）
    - 路由配置文件（`src/routes/`、`src/router/`、`pages/` 目录等）
    - 目录结构（`ls src/`）
-5. **识别旧项目技术栈** — 从依赖和代码判断，记录以下维度：
+6. **识别旧项目技术栈** — 从依赖和代码判断，记录以下维度：
    - UI 框架（antd / element-ui / arco-design / mui / naive-ui / 自研）
    - 路由方案（react-router / vue-router / next.js / umi）
    - 状态管理（redux / mobx / zustand / pinia / vuex）
@@ -536,84 +567,214 @@ npx teamix-evo ui promote-to-biz --staging-dir <path>  # 指定 staging 目录
 
 6. **生成迁移计划文件** — 写入 `.teamix-evo/migrate-plan.md`，格式如下：
 
-```markdown
+````markdown
 # Migration Plan
 
+## ❗ 执行规则（每次读取本文件时必须重新确认）
+
+1. **Token 映射查表** — 每迁移一个页面前，必须先读取 `.teamix-evo/migrate-token-mapping.md`，所有旧项目 CSS 变量按实际像素值映射为新项目 Tailwind class。禁止根据变量名称“猜测”对应关系。
+2. **skill 门控** — 写代码前必须已加载 `teamix-evo-manage`、`teamix-evo-code-{variant}`、`teamix-evo-design-{variant}` 三个 skill（路径见关键文件索引）。
+3. **三轨齐备** — 进入任何页面实现前必须源码 + repo-wiki + 截图全部确认就绪（截图由用户预先准备，AI 只做确认）。
+4. **Token 合法性自检** — 写完代码后扫描所有 Tailwind class，确认在新项目有效。
+5. **新架构骨架层检查** — 迁移不仅是“翻译旧代码”，还必须“适配新架构的标准模式”。新架构有一套完整的页面骨架层级（`PageShell → OpPageContainer → PageHeader → 内容`），这些组件在旧项目中完全不存在（旧项目用自定义 `<h1>`、内联样式或散落 CSS 实现），三轨对照不会发现它们。必须主动查阅 design skill 和 biz-ui 组件的 JSDoc 获取标准骨架用法：
+   - **Layout 层**：检查 `src/components/biz-ui/` 是否存在页面容器组件（如 `OpPageContainer`），在 `<Outlet />` 外统一包裹，使所有页面自动获得容器效果
+   - **每页面层**：检查容器组件的 JSDoc / 源码中是否定义了标配的子组件模式（如 `header={<PageHeader>...</PageHeader>}` 是每页标配），必须按规范使用而非省略
+
+# ❄️ 冷启动恢复指南（上下文丢失 / 新会话接手时执行）
+
+如果你是一个新会话被要求"继续迁移"，按以下顺序恢复上下文：
+
+1. 读取本文件 `.teamix-evo/migrate-plan.md` — 获取进度、元数据、执行规则
+2. 读取 `.teamix-evo/migrate-token-mapping.md` — 加载 token 映射表
+3. 加载三个 skill（路径见下方「关键文件索引」）：
+   - **Manage skill** — 包含完整的迁移执行协议（三轨确认流程、逐条实现步骤、验证流程）
+   - **Code skill** — 代码规范门控（reuse-first / file-structure / api-layering）
+   - **Design skill** — 设计/布局规范（视觉还原、栅格、组件组合）
+4. 查看 Progress 区块 — 找到 **Current phase** 所指的 Phase，在该 Phase 中定位第一个未完成的 `[ ]` 条目（不要回头处理更早 Phase 中被 pilot 模式有意推迟的条目）
+5. 确认三轨材料 — 对当前页面确认源码 + repo-wiki + 截图三轨就绪（截图目录见 Metadata → Screenshots dir）
+6. 开始实现 — 从第一个未完成条目继续
+
+> 注：截图由用户预先准备完成，AI 无需执行截图操作。若截图目录中缺少当前页面截图，暂停并请用户补充。
+
+## 关键文件索引
+
+| 文件         | 路径                                                      | 用途                           |
+| ------------ | --------------------------------------------------------- | ------------------------------ |
+| 迁移计划     | `.teamix-evo/migrate-plan.md`                             | 进度跟踪 + 执行规则（本文件）  |
+| Token 映射表 | `.teamix-evo/migrate-token-mapping.md`                    | CSS 变量 → Tailwind class 映射 |
+| 截图目录     | 见 Metadata → Screenshots dir                             | 用户提供的页面截图目录         |
+| Manage skill | `.teamix-evo/skills/teamix-evo-manage/SKILL.md`           | 迁移执行协议（场景 6）         |
+| Code skill   | `.teamix-evo/skills/teamix-evo-code-{variant}/SKILL.md`   | 代码规范门控                   |
+| Design skill | `.teamix-evo/skills/teamix-evo-design-{variant}/SKILL.md` | 设计/布局规范                  |
+| 旧项目源码   | 见 Metadata → Source                                      | 源码轨参考                     |
+| 旧项目 Wiki  | 见 Metadata → Source 同级 `repo-wiki/`                    | Wiki 轨参考                    |
+
+> ℹ️ `{variant}` 请替换为 Metadata 中的 **Target variant** 值（如 `opentrek` 或 `uni-manager`）。实际生成时会自动填入真实值。
+
 ## Progress
+
 - **Status**: in-progress
+- **Mode**: <full | pilot>
+- **Pilot pages**: <页面名列表，仅 pilot 模式填写>
+- **Pilot 说明**: <pilot 模式下仅执行上述 Phase 涉及的条目。更早 Phase 中标 `[ ]` 的条目是有意推迟到 pilot 验证通过后再补的，当前不需要处理>
 - **Completed**: 0 / <总条目数>
 - **Current phase**: Phase 0 — Global Infrastructure
 - **Last updated**: <ISO 时间戳>
 
 ## Metadata
+
 - **Source**: <旧项目绝对路径>
 - **Target variant**: <当前项目 variant>
 - **Generated**: <ISO 时间戳>
 - **Old stack**: <框架> + <UI 库> + <路由> + <HTTP 客户端> + <状态管理>
-- **Source URL**: <用户提供的运行地址，可选>
+- **Screenshots dir**: <用户提供的截图目录绝对路径>
 
 ## Component Mapping (AI via MCP find_components 动态生成)
 
 | Old | New (teamix-evo) | Notes |
-|-----|-------------------|-------|
-| ... | ...               | ...   |
+| --- | ---------------- | ----- |
+| ... | ...              | ...   |
 
 ## Phase 0: Global Infrastructure
 
-- [ ] **Routing** — 路由结构搭建
+- [ ] **清理脚手架示例页面** — 删除 `create-teamix-evo` 生成的 demo 页面（`src/pages/home/`、`src/pages/list/`、`src/pages/detail/`、`src/pages/form/` 等）及关联的 services / hooks / types / routes 条目
+      [ ] **Layout（吸顶 + 左导 + 页面容器）** — ❗ 优先级最高。全局壳重构：吸顶 Header、左侧边栏 Sidebar、面包屑、内容区布局。先保证通用性内容正确，再进入具体页面。
+
+  > Layout 也需要截图参考：确认用户截图目录中 `layout/` 文件夹是否包含吸顶和左导截图（`header.png` + `sidebar.png`），作为视觉还原参考。若缺失，提示用户补充。
+
+  > ⚠️ **新架构骨架层检查**：新架构的页面骨架是 `PageShell → OpPageContainer → PageHeader → 内容`，旧项目不会有这些抽象。必须主动检查 biz-ui 组件源码和 JSDoc 获取标准用法：
+  >
+  > - Layout 层：`<Outlet />` 外套 `OpPageContainer`（灰底白卡）
+  > - 每页面层：`OpPageContainer` 的 `header` prop 传入 `<PageHeader>`（页面标题 + Tabs 等）
+  > - 这些信息三轨对照找不到，只能从 design skill 和 biz-ui 组件 JSDoc 中获取
+
+- [ ] **静态资源迁移** — 将旧项目的静态资源（图片 / 视频 / 动效 / 字体 / SVG / 音频等）拷贝到新项目对应目录（如 `public/` 或 `src/assets/`），保持相对引用路径一致
+- [ ] **Routing** — 路由结构搭建（基于旧项目路由表重建）
 - [ ] **API client** — HTTP 客户端 + 拦截器
 - [ ] **Auth** — 鉴权流程
-- [ ] **Layout** — 全局壳（导航 / 侧边栏 / 面包屑）
 - [ ] **Global state** — 全局状态管理
-- [ ] **Theme** — 主题对齐（tokens.overrides.css）
+- [ ] **Theme & 全局 CSS 基线** — 对比旧项目的全局样式（body / html / :root），将以下配置对齐到新项目：
+
+  - 字体族（font-family）— 若旧项目使用自定义字体（如 Geist / Inter），需引入字体文件并配置 @font-face
+  - 字体平滑（-webkit-font-smoothing: antialiased）
+  - 字体特性（font-feature-settings）
+  - 基础行高、字号、颜色
+  - 其他全局 reset 样式
+  - tokens.overrides.css 主题变量覆盖
+
+  > 这些全局 CSS 影响所有页面的视觉表现，必须在进入具体页面迁移前完成。直接沿用旧项目的配置，无需询问用户。完成后在进度汇报中简要记录已对齐的项目（如“已对齐字体族 Geist Variable、antialiased、font-feature-settings”），通知用户即可。
+
+- [ ] **Token 映射表** — 提取旧项目所有 CSS 变量 / design tokens，解析其实际值，建立与新项目 Tailwind class 的映射表，并写入 `.teamix-evo/migrate-token-mapping.md`。示例：
+
+  ```markdown
+  | 旧项目 Token     | 实际值  | 新项目 Tailwind Class     |
+  | ---------------- | ------- | ------------------------- |
+  | --font-size-base | 12px    | text-xs                   |
+  | --font-size-lg   | 14px    | text-sm                   |
+  | --font-size-xl   | 16px    | text-base                 |
+  | --font-size-2xl  | 18px    | text-lg                   |
+  | --color-primary  | #1677ff | text-primary / bg-primary |
+  | --border-radius  | 4px     | rounded                   |
+  | --spacing-sm     | 8px     | gap-2 / p-2               |
+  ```
+
+  映射表必须覆盖以下维度：
+
+  - **字号** — 所有 font-size 变量
+  - **间距** — spacing / padding / margin / gap 变量
+  - **圆角** — border-radius 变量
+  - **颜色** — 旧项目自定义色值变量（如 `--color-data-8`、`--color-brand-3`）→ 检查新项目 `tokens.theme.css` 中是否存在对应 utility。若不存在，标注为「❗ 无对应」并建议替代方案（如用最接近的语义色或 CSS 变量内联）
+  - **阴影** — box-shadow 变量
+
+  > ⚠️ **硬约束：禁止按名称猜测映射。** AI 必须解析旧项目 CSS 变量的实际像素值，再映射到新项目对应的 Tailwind class。例如 `--font-size-lg = 14px` 应映射为 `text-sm`（而不是名称相似的 `text-lg`）。
+  > 后续 Phase C 逐页实现时，所有涉及旧 token 的代码必须查询此表来确定正确的 Tailwind class，不得凭名称直觉映射。
+  > 对于映射表中标注为「❗ 无对应」的 token，在写代码时必须使用替代方案，不得直接复制旧项目的 class 名。
 
 ## Phase 1: <页面名> (complexity: <simple|medium|complex>)
 
+> ⚠️ 执行前检查：① 已读取 `migrate-token-mapping.md` ② 已加载 manage/code/design skill（见关键文件索引） ③ 三轨已采集
+
 - Route: `<路由路径>`
 - [ ] **<子任务>** — <描述> (<使用组件>)
 - [ ] **API integration** — <接口列表>
 
 ## Phase N: ...
-```
+````
 
-   **组件映射生成规则**：通过 MCP `find_components` / `list_components` 查询 teamix-evo 注册表，逐个匹配旧项目使用的 UI 组件，动态填写映射表。
+**组件映射生成规则**：通过 MCP `find_components` / `list_components` 查询 teamix-evo 注册表，逐个匹配旧项目使用的 UI 组件，动态填写映射表。
 
 7. **展示计划摘要** — 向用户复述：
+
    - 总页面数
    - 按复杂度分布（简单 / 中等 / 复杂）
    - 建议执行顺序
    - 询问用户是否调整顺序、跳过某些页面、或补充遗漏页面
 
+8. **确认迁移节奏** — 向用户提问：
+
+   > “您希望先迁移几个页面验证效果，还是直接开始全量迁移？”
+
+   - **先验证（推荐）**：用户选择 1–3 个代表性页面（建议包含一个简单页 + 一个复杂页），先做完这几个让用户检验代码质量、视觉还原度、组件映射质量后再继续剩余页面
+   - **全量迁移**：按计划顺序逐页执行，每完成一个 Phase 后向用户汇报
+
+   在 `migrate-plan.md` 顶部 Progress 区块记录用户选择：
+
+   - `Mode: pilot` + `Pilot pages: <页面名列表>` — 验证模式，仅执行指定页面
+   - `Mode: full` — 全量模式
+
+   > pilot 模式完成后，向用户确认：“验证页面已完成，是否继续迁移剩余页面？”用户确认后将 Mode 改为 `full` 并继续。
+
    > Phase B → Phase C 之间**必须**有用户的明确确认（go-ahead）。
 
 #### Phase C · 执行
 
-8. **读取当前进度** — 读 `.teamix-evo/migrate-plan.md` 顶部 Progress 区块。若 Status 为 `done` → 告知用户迁移已全部完成。否则找到第一个未完成（`[ ]`）的条目。
-9. **三轨采集（每页开发前必做）** — 进入一个页面的开发前，必须先收集三轨信息：
-   a. **Wiki 轨**：读旧项目 repo-wiki 中该页面相关的描述（功能说明、业务规则、数据流）
-   b. **源码轨**：读旧项目该页面的全部源文件（页面组件 + 子组件 + 页面内弹窗 Dialog / 抽屉 Drawer / 确认框等）
-   c. **截图轨**：通过浏览器访问旧项目运行地址，对该页面进行截图。截图范围须覆盖：
-      - 页面默认态（列表 / 表单 / 详情等主视图）
-      - 页面内所有弹窗（Dialog / Modal）的打开态
-      - 页面内所有抽屉（Drawer / Sheet）的打开态
-      - 关键交互状态（空态 / 加载态 / 错误态，若能触发）
+9. **读取当前进度** — 读 `.teamix-evo/migrate-plan.md` 顶部 Progress 区块。若 Status 为 `done` → 告知用户迁移已全部完成。否则找到第一个未完成（`[ ]`）的条目。
+10. **三轨确认（每页开发前必做）** — 进入一个页面的开发前，必须确认三轨材料均已就绪：
+    a. **源码轨**：读旧项目该页面的全部源文件（页面组件 + 子组件 + 页面内弹窗 Dialog / 抽屉 Drawer / 确认框等）
+    b. **Wiki 轨**：读旧项目 repo-wiki 中该页面相关的描述（功能说明、业务规则、数据流）
+    c. **截图轨**：检查用户提供的截图目录中 `<screenshots-dir>/<page-route>/` 是否已有该页面截图。
+
+- **已有截图** → 直接读取作为视觉参考。
+- **截图缺失** → 暂停并告知用户："<页面名> 缺少截图，请补充后告诉我。"等待用户补充后继续。
+
+**截图存放约定**：用户在 Qoder 工作区预先准备，按页面路由为文件夹名，存放在用户提供的截图目录下。文件名约定：
+
+- `default.png` — 页面默认态
+- `dialog-<名称>.png` — 弹窗打开态
+- `drawer-<名称>.png` — 抽屉打开态
+- `state-empty.png` / `state-loading.png` / `state-error.png` — 特殊状态
+
+截图范围须覆盖：
+
+- 页面默认态（列表 / 表单 / 详情等主视图）
+- 页面内所有弹窗（Dialog / Modal）的打开态
+- 页面内所有抽屉（Drawer / Sheet）的打开态
+- 关键交互状态（空态 / 加载态 / 错误态，若能触发）
+
+> **AI 不执行截图**：截图由用户在迁移开始前通过 Qoder 工作区一次性完成（访问旧项目所有页面、弹窗、抽屉截图），迁移过程中 AI 仅读取已有截图作为视觉参考。
+
+> ⚠️ **硬约束：三轨齐备方可动手。** AI 必须在源码、wiki、截图三轨全部确认就绪后，才能开始该页面的实现。**AI 不得自行跳过截图轨**——只有用户明确要求「跳过截图」时，才可降级为两轨模式，并标注"⚠️ 无截图参考，视觉还原需用户人工校对"。
 
-   > 三轨齐备后，向用户确认："已采集完 <页面名> 的 wiki、源码、截图，开始实现？"用户确认后才动手。若截图不可用（旧项目未运行），告知用户并以 wiki + 源码两轨继续，标注"无截图参考，视觉还原需用户人工校对"。
+三轨确认后，向用户确认："<页面名> 的源码、repo-wiki、截图三轨已确认就绪，开始实现？"用户确认后才动手。
 
-10. **逐条实现** — 对每个 checklist 条目：
+11. **逐条实现** — 对每个 checklist 条目：
     a. 通过 MCP `find_components` / `get_component_meta` 查询可用组件
-    b. 遵循 `teamix-evo-code-<variant>` skill 规范生成代码（reuse-first / file-structure / api-layering）
-    c. 遵循 `teamix-evo-design-<variant>` skill 规范处理页面布局，参照截图还原视觉
-    d. 完成后更新 `.teamix-evo/migrate-plan.md`：将对应条目标记为 `[x]`，同步更新顶部 Progress（Completed 计数 + Current phase + Last updated）
-    e. 向用户汇报进度，格式：`✅ <条目名> 完成（<已完成数>/<总数>）| 当前阶段：<Phase 名>`
-11. **验证** — 每完成一个页面后：
+    b. **加载 code/design skill** — 必须先读取 `teamix-evo-code-{variant}` 和 `teamix-evo-design-{variant}` 的 SKILL.md 全文，激活其门控流程。**禁止未读取就开始写代码**。若当前会话已经读取过且上下文未丢失，可跳过重复读取
+    c. 遵循 `teamix-evo-code-{variant}` skill 规范生成代码（reuse-first / file-structure / api-layering）
+    d. 遵循 `teamix-evo-design-{variant}` skill 规范处理页面布局，参照截图还原视觉
+    e. **Token 映射查表** — 写代码时遇到旧项目的 CSS 变量 / class，必须查询 `.teamix-evo/migrate-token-mapping.md` 确定正确的 Tailwind class，禁止凭名称直觉映射
+    f. **静态资源处理** — 实现过程中若发现页面引用了图片 / 视频 / 动效 / 字体等资源，必须从旧项目对应路径拷贝到新项目，**禁止仅报告“缺少资源”而不动手拷贝**
+    g. **Token 合法性自检** — 写完代码后，扫描本次生成的所有 Tailwind class，确认每个都在新项目 `tokens.theme.css` 中有对应变量或是 Tailwind 标准 utility。若发现无效 class（如 `bg-data-8` 在新项目不存在），必须立即替换为有效的替代方案
+    h. 完成后更新 `.teamix-evo/migrate-plan.md`：将对应条目标记为 `[x]`，同步更新顶部 Progress（Completed 计数 + Current phase + Last updated）
+    i. 向用户汇报进度，格式：`✅ <条目名> 完成（<已完成数>/<总数>）| 当前阶段：<Phase 名>`
+12. **验证** — 每完成一个页面后：
     - 列出该页面的功能检查点（从旧代码提取的关键交互：CRUD / 筛选 / 分页 / 权限 / 弹窗流程等）
     - 若有截图，建议用户对比新旧页面视觉差异
     - 跑 `pnpm typecheck` 确认零类型错误
 
 #### Phase D · 全量 Review
 
-12. **全部页面完成后** — 当 Progress 中 Completed 等于总条目数时：
+13. **全部页面完成后** — 当 Progress 中 Completed 等于总条目数时：
     - 将 Status 更新为 `review`
     - 向用户提示："所有页面已迁移完成，建议进行一轮整体 review。是否现在开始？"
     - 用户确认后，逐页面列出 review 检查点：
@@ -622,38 +783,43 @@ npx teamix-evo ui promote-to-biz --staging-dir <path>  # 指定 staging 目录
       - 路由可达性（所有页面是否串通）
       - 全局一致性（Layout / 导航 / 权限守卫是否统一）
     - review 全部通过后，将 Status 更新为 `done`
-13. **会话恢复** — 若 AI 进入新会话：
-    - 读 `.teamix-evo/migrate-plan.md` 顶部 Progress 区块快速获取整体进度（Status / Completed / Current phase）
-    - `in-progress` → 定位第一个 `[ ]` 条目，从断点处继续
+14. **会话恢复** — 若 AI 进入新会话：
+    - 读 `.teamix-evo/migrate-plan.md` — 文件顶部包含「冷启动恢复指南」，按其 6 步顺序恢复上下文
+    - 读截图目录（Metadata → Screenshots dir），确认已有哪些页面的截图可作为视觉参考
+    - `in-progress` → 定位第一个 `[ ]` 条目，确认三轨材料（源码 + wiki + 截图）就绪后从断点处继续
     - `review` → 进入 Phase D review 流程
     - `done` → 告知用户迁移已完成
 
 ### 身份划分清单
 
 - **AI（本 skill — manage）**：询问路径 → 检测 repo-wiki → 生成/管理 `migrate-plan.md` → 进度追踪 → 会话恢复定位。
-- **AI（`teamix-evo-code-<variant>`）**：生成每页实际代码时遵循 reuse-first / file-structure / api-layering 规范。Phase C 执行时自动应用。
-- **AI（`teamix-evo-design-<variant>`）**：页面级布局 / 视觉设计决策。迁移新页面时并行参考。
+- **AI（`teamix-evo-code-{variant}`）**：生成每页实际代码时遵循 reuse-first / file-structure / api-layering 规范。Phase C 执行时自动应用。
+- **AI（`teamix-evo-design-{variant}`）**：页面级布局 / 视觉设计决策。迁移新页面时并行参考。
 - **用户**：提供旧项目路径 / 确认 repo-wiki 已生成 / 审核迁移计划 / 可选提供运行 URL / 确认每页实现结果。
 - **CLI**：无新命令。执行阶段复用 `teamix-evo ui add <id>`（若发现有未安装的 UI 组件需要补装）。
 
 ### 边缘情况
 
-| 情况 | 处理 |
-| ---- | ---- |
-| repo-wiki 不存在 | 提示用户先在旧项目执行 repo-wiki 生成命令 |
-| repo-wiki 不完整（缺路由/API 等） | 直接读旧项目源码补充（路由配置 / package.json / 目录结构） |
-| 旧项目是 Vue / Angular（非 React） | 正常分析，概念映射无框架壁垒（路由→路由、组件→组件），新项目统一生成 React |
-| 旧项目是 monorepo | 让用户指定具体 package 路径作为 `<old-path>` |
-| 页面极复杂（>500 行、多子路由） | 拆为多个 checklist 子条目，标记 complexity: complex |
-| `.teamix-evo/migrate-plan.md` 已存在 | 询问用户三选一：(a) 恢复进度继续、(b) 重新生成（覆盖）、(c) 查看当前计划 |
-| 新项目已有部分页面 | 跳过已存在的页面，或标记为 verify-only |
-| token 预算不足以完成全部分析 | 停止读取，基于已有信息生成部分计划，标注"后续会话补充" |
+| 情况                                 | 处理                                                                           |
+| ------------------------------------ | ------------------------------------------------------------------------------ |
+| repo-wiki 不存在                     | 提示用户先在旧项目执行 repo-wiki 生成命令                                      |
+| 截图目录为空或缺少页面截图           | 暂停并提示用户补充截图，不得跳过或自行执行截图                                 |
+| repo-wiki 不完整（缺路由/API 等）    | 直接读旧项目源码补充（路由配置 / package.json / 目录结构）                     |
+| 旧项目是 Vue / Angular（非 React）   | 正常分析，概念映射无框架壁垒（路由 → 路由、组件 → 组件），新项目统一生成 React |
+| 旧项目是 monorepo                    | 让用户指定具体 package 路径作为 `<old-path>`                                   |
+| 页面极复杂（>500 行、多子路由）      | 拆为多个 checklist 子条目，标记 complexity: complex                            |
+| `.teamix-evo/migrate-plan.md` 已存在 | 询问用户三选一：(a) 恢复进度继续、(b) 重新生成（覆盖）、(c) 查看当前计划       |
+| 新项目已有部分页面                   | 跳过已存在的页面，或标记为 verify-only                                         |
+| token 预算不足以完成全部分析         | 停止读取，基于已有信息生成部分计划，标注"后续会话补充"                         |
 
 ### 不要
 
 - **不要**在无 repo-wiki 且源码量大时一次性读完全部文件 — 分批按需读取。
 - **不要**跳过 Phase B 直接写代码 — 必须先生成 `migrate-plan.md` 让用户审核确认。
 - **不要**复制旧项目的组件源码到新项目 — 走 reuse-first 查 `@teamix-evo/ui` 注册表匹配。
+- **但可以修改业务组件（biz-ui）** — `src/components/biz-ui/` 下的组件（如 `op-sidebar`、`page-header`、`op-layout` 等）是 `frozen` 策略，用户拥有所有权。当现有业务组件无法满足迁移需求（缺少 slot、不支持某布局、缺少交互能力）时，AI **应当直接修改 biz-ui 组件源码**，而不是在页面层面 hack。修改前告知用户“当前 biz-ui 组件 <X> 不支持 <能力>，我将直接增强它”。
+  - ✅ 可修改：`src/components/biz-ui/**`（用户拥有，frozen）
+  - ❌ 不可修改：`src/components/ui/**`（teamix-evo 接管，需走 `ui upgrade`）
 - **不要**搬迁旧项目的样式体系（CSS-in-JS / less / sass / antd theme） — 新项目用 design tokens + Tailwind v4。
 - **不要**原样搬入旧 node_modules 依赖 — 仅迁移业务必需的第三方库（如图表库、富文本编辑器）。
 - **不要**在用户未确认计划前开始实现。

package/src/teamix-evo-design-opentrek/pages/list-page/_shared/action-column-spec.md

@@ -1,60 +0,0 @@
-# 操作列规范
-
-> 适用于 standard-list, l2-sidebar-list, expandable-list, drawer-list 子类型。
-
-## 操作列结构
-
-操作列包含 3 个主要操作 + 1 个"更多"入口, 以分隔线区分:
-
-| 元素 | 样式 | 条件 | 禁用样式 |
-|------|------|------|---------|
-| 主操作(管理/查看) | 链接样式 | 始终可用 | — |
-| 分隔线 | \| | — | — |
-| 次要操作(远程连接等) | 文字按钮 | 特定状态时 disabled | `opacity: 0.45; pointer-events: none` |
-| 分隔线 | \| | — | — |
-| 状态操作(实例状态▾) | 下拉按钮 | 特定状态时 disabled | `opacity: 0.45; pointer-events: none` |
-| 分隔线 | \| | — | — |
-| 更多操作 | "..."下拉菜单 | 始终可用 | — |
-
-## 操作列行为
-
-| 操作 | 触发方式 | 前置条件 | 二次确认 | 目标页面/组件 | 返回行为 |
-|------|----------|---------|---------|-------------|----------|
-| 查看/管理 | 点击链接 | 无 | 否 | DetailPage (引用 pages/detail-page/) | 返回列表页, 保持筛选+分页状态 |
-| 编辑 | 点击按钮 | 无 | 否 | FormPage (引用 pages/form-page/) 或 Sheet | 保存成功后返回列表页, Sonner "保存成功" |
-| 删除 | 点击按钮 | 实例已停止 | 是 (Dialog确认) | Dialog确认弹窗 | 确认后刷新列表, Sonner "删除成功" |
-| 更多 | Dropdown | 无 | 否 | 下拉菜单 | 选择操作 |
-
-## 禁用样式
-
-所有 disabled 元素统一样式：
-```css
-opacity: 0.45;
-pointer-events: none;
-```
-
-## 水平对齐【硬约束】
-
-操作列位于表格末列，**表头与表体均需显式 `text-align: left`**，使「操作」标题与操作列左侧第一个字段（如「详情」链接）左边缘对齐：
-
-```css
-.data-table .col-action {
-  width: 140px;
-  text-align: left;
-  position: sticky; right: 0;
-  background: hsl(var(--card));
-}
-/* 显式兑底，避免浏览器默认样式覆盖 */
-.data-table thead th.col-action { background: hsl(var(--gray-bg)); text-align: left; }
-.data-table tbody td.col-action { text-align: left; }
-```
-
-### 禁止项
-
-- ❌ 禁止只在 `.col-action` 上设 `text-align: left` 而不在 `thead th.col-action` / `tbody td.col-action` 重复声明（部分浏览器下会被覆盖）
-- ❌ 禁止表头「操作」与表体操作内容对齐方式不一致
-- ❌ 禁止操作列内容居中
-
-### 验证
-
-表头「操作」左边缘 X = 表体「详情」链接左边缘 X。

package/src/teamix-evo-design-opentrek/pages/list-page/_shared/state-action-pattern.md

@@ -1,51 +0,0 @@
-# 状态-操作模式规范
-
-> 适用于所有产品线的列表页。
-> 本产品特有状态机定义见 `products/{产品}/states.json`。
-
-## 元规则
-
-| 规则 | 说明 |
-|------|------|
-| 每个状态必须定义操作可用性 | 明确标注每个操作在该状态下是否可用 |
-| 禁用操作必须使用统一样式 | `opacity: 0.45; pointer-events: none` |
-| 混合状态时批量操作按钮禁用 | 不同状态的行选中时，hover 提示不可用原因 |
-| 异步操作必须提供反馈 | Sonner 提示 + 列表刷新机制 |
-| 操作确认按影响级别分级 | 一级(可逆直接执行) / 二级(影响状态Dialog确认) / 三级(不可逆输入确认) |
-
-## 异步操作处理（通用）
-
-| 操作类型 | 触发后行为 | 反馈方式 | 列表刷新 |
-|---------|-----------|---------|---------|
-| 状态变更操作 | 异步任务, 不阻塞 | Sonner "操作已提交" | 轮询状态或任务完成通知 |
-| 删除操作 | 异步任务 | Sonner "删除已提交" | 移除对应行或刷新列表 |
-| 批量操作 | 异步任务 | Sonner "批量操作已提交, 共N条" | 轮询状态 |
-| 创建操作 | 同步跳转 | 跳转 FormPage | 创建成功后返回列表 |
-
-## 操作确认规范（通用）
-
-| 确认级别 | 确认方式 | 适用操作 |
-|---------|---------|---------|
-| 一级 (可逆) | 无确认, 直接执行 | 查看、编辑、远程连接 |
-| 二级 (影响状态) | Dialog确认弹窗 | 启动、停止、重启等状态变更 |
-| 三级 (不可逆) | Dialog + 输入确认文本 | 删除 (需输入确认文本) |
-
-## 页面间导航交互（通用）
-
-| 来源操作 | 目标页面 | 导航方式 | 返回/交互约定 |
-|---------|---------|---------|-------------|
-| 操作列"管理/查看" | 详情页 (DetailPage) | 页面跳转 | Breadcrumb+PageHeader提供返回入口; 返回后保持列表筛选+分页 |
-| 操作列"编辑" | 表单页 (FormPage) 或 Sheet | 页面跳转/侧滑 | 保存后返回列表, Sonner 提示结果; 取消返回列表 |
-| 创建操作 | 创建页 (FormPage) | 页面跳转 | 创建成功/取消后返回列表 |
-| 搜索执行 | 当前列表页(刷新数据) | 数据刷新 | 保持分页在第1页 |
-| 筛选条件变更 | 当前列表页(刷新数据) | 数据刷新 | 重置到第1页, 保持筛选条件 |
-
-## 反馈机制（通用）
-
-| 场景 | 反馈类型 | 持续时间 | 说明 |
-|------|---------|---------|------|
-| 操作成功 | Sonner 成功提示 | 3s | "操作成功" |
-| 操作失败 | Sonner 错误提示 | 5s | 含错误原因 |
-| 异步任务 | 通知中心 + Sonner | 持久 | 任务完成时通知 |
-| 加载中 | 表格行 Skeleton / Spinner | 至加载完成 | 首次加载/筛选加载 |
-| 空数据 | Empty | 持久 | 含创建引导按钮 |

package/src/teamix-evo-design-opentrek/pages/list-page/patterns/advanced-filter-list.md

@@ -1,94 +0,0 @@
-# 高级筛选列表页 (advanced-filter)
-
-> 路由自 `../SKILL.md`
-> 布局模式: 模式D+ (高级筛选)
-> 核心差异: 可展开的高级筛选面板 + 多条件组合
-
-## 1. 布局骨架
-
-```
-┌──────────┬──────────────────────────────────────────────┤
-│  Sidebar │  PageHeader: 标题(18px/medium) [描述*]            │
-│          │  ─────────────────────────                   │
-│          │  ActionToolbar: [创建] + [全部▼][输入...]🔍 [高级筛选▾]│
-│          │  ─────────────────────────                   │
-│          │  ┌─── AdvancedFilterPanel ───────────────┐   │
-│          │  │ 条件1: [Select] [Input]               │   │
-│          │  │ 条件2: [Select] [Input]               │   │
-│          │  │ 条件3: [Select] [Input]               │   │
-│          │  │              [确认] [清空]              │   │
-│          │  └───────────────────────────────────────┘   │
-│          │  ─────────────────────────                   │
-│          │  DataTable (固定列: 左选择框+ID, 右操作)       │
-│          │  ─────────────────────────                   │
-│          │  BulkActionBar (选中时内嵌显示)               │
-│          │  ─────────────────────────                   │
-│          │  Pagination                                  │
-└──────────┴──────────────────────────────────────────────┘
-```
-
-## 2. 核心差异
-
-| 维度 | 标准列表 | 高级筛选列表 |
-|------|----------|-------------|
-| 筛选方式 | SearchCombo | **SearchCombo + AdvancedFilterPanel** |
-| 筛选条件数 | 1个维度 | **多条件组合（通常2-5个）** |
-| AdvancedFilterPanel | 无 | **必需** |
-| FilterTag | 可选 | **必需**（展示已选条件） |
-
-## 3. AdvancedFilterPanel 交互规范
-
-| 交互 | 行为 |
-|------|------|
-| 打开面板 | 点击"高级筛选"按钮，展开面板 |
-| 关闭面板 | 收起面板，恢复基础 SearchCombo |
-| 添加条件 | 点击"添加条件"，新增一行筛选条件 |
-| 删除条件 | 点击条件行右侧 ×，移除该条件 |
-| 条件间关系 | **AND 关系**（所有条件同时生效） |
-| 确认筛选 | 点击"确认"，应用所有条件，刷新列表 |
-| 清空筛选 | 点击"清空"，清除所有条件 |
-| 面板位置 | ActionToolbar 下方，DataTable 上方 |
-
-## 4. FilterTag 管理
-
-- 已选筛选项以 **FilterTag** 形式展示在 ActionToolbar 区域
-- 每个 FilterTag 可单独移除（点击 ×）
-- 筛选条件清空后，FilterTag 区域隐藏（display: none）
-- 高级筛选条件的 FilterTag 支持"清空全部"操作
-
-## 5. 引用共享规则
-
-| 共享规则 | 路径 | 说明 |
-|----------|------|------|
-| 表格列元规则 | `../_shared/column-meta-rules.md` | 列元规则（显隐/拖拽/排序）
-| 产品列定义 | `products/{产品}/columns.json` | 具体列名/宽度/类型 |
-| 操作列规范 | `../_shared/action-column-spec.md` | 操作列结构、行为 |
-| 状态-操作模式 | `../_shared/state-action-pattern.md` | 状态驱动操作元规则
-| 产品状态机 | `products/{产品}/states.json` | 具体状态/操作可用性 |
-
-> DataTable、BulkActionBar、Pagination、ActionToolbar（不含高级筛选按钮）等组件及交互行为与标准列表页一致，不再重复。
-
-## 6. 与 PageContainer 模式对照
-
-> 布局模式定义见 `../../../rules/layout-rules.json`
-
-高级筛选列表使用 **模式D+**：
-```
-PageContainer → ContentWrapper → PageHeader + ActionToolbar + AdvancedFilterPanel(可展开) + DataTable + BulkActionBar + Pagination
-```
-
-- "高级筛选"按钮位于 ActionToolbar 右侧
-- 展开后显示多条件组合面板（条件1/2/3 + 确认/清空）
-- 收起后恢复基础 SearchCombo
-
-## 7. 验证清单
-
-> 通用检查项见 `../../../docs/validation-workflow.md` 验证清单。此处仅列出本模式差异项。
-
-| 验证项 | 检查点 | 目标 |
-|--------|--------|------|
-| AdvancedFilterPanel | 展开/收起正常 | 正确 |
-| 多条件组合 | AND 关系 | 正确 |
-| 条件添加/删除 | 增删条件行正常 | 正确 |
-| 确认/清空 | 确认后刷新，清空后恢复 | 正确 |
-| FilterTag | 展示已选条件，可单独移除 | 正确 |