@teamix-evo/skills 0.10.1 → 0.11.0

package/manifest.json

@@ -10,7 +10,7 @@
     {
       "id": "teamix-evo-manage",
       "name": "teamix-evo-manage",
-      "description": "Single entry point for the teamix-evo lifecycle: scaffold a new project skeleton, install the AI coding system into an existing repo via `teamix-evo init`, inspect / remove any teamix-evo package, manage component-source upgrades, and drive old-project migration/rebuild.\nTRIGGER when: (CLI) user runs or asks about `teamix-evo init` / `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo blocks ...` / `teamix-evo lint ...` / `teamix-evo logs ...` / `teamix-evo restore ...` / `teamix-evo switch ...`, or `npm create teamix-evo` / `pnpm create teamix-evo`; (模糊初始化) \"初始化一个项目\"、\"初始化一个工程\"、\"初始化一个 teamix-evo 工程\"、\"初始化一个 Teamix Evo 项目\"、\"create a teamix-evo project\"、\"set up teamix-evo from scratch\"、\"new teamix-evo app\"; (具名变体初始化) \"初始化一个 opentrek 工程 / op 工程 / OpenTrek 项目 / 探索者项目\"、\"初始化一个云管 / 云管控制台 / 云管项目 / uni-manager 工程 / 云管工程\"、\"new opentrek/uni-manager project\"; (AI coding 接入) \"给现有仓库装 teamix-evo\"、\"现有项目装一下 skills + ui\"、\"接入 AI coding 体系\"、\"装 teamix-evo 进这个项目\"、\"add teamix-evo to existing repo\"、\"install AI coding system\"、\"接入 opentrek 研发体系\"、\"接入 op 研发体系\"、\"接入 OpenTrek 研发体系\"、\"接入 opentrek 研发系统\"、\"接入 op 研发系统\"、\"接入云管研发体系\"、\"接入云管研发系统\"、\"接入 uni-manager 研发体系\"、\"接入 uni-manager 研发系统\"、\"接入统一管理研发体系\"; (组件源码升级 — ADR 0040) \"升级 ui\"、\"升级业务组件\"、\"升级 button\"、\"生成 ui staging\"、\"生成 biz-ui staging\"、\"upgrade ui\"、\"upgrade biz-ui\"、\"upgrade ui component\"、\"stage ui upgrade\"、\"teamix-evo ui upgrade\"、\"teamix-evo biz-ui upgrade\"; (卸载 / 清单) \"卸载 teamix-evo\"、\"看看装了哪些 teamix-evo 资源\"、\"remove the design system\"、\"list installed\"; (旧工程迁移) \"迁移旧项目\"、\"重建老工程\"、\"把旧项目搬过来\"、\"旧项目分析\"、\"旧系统翻新\"、\"legacy migration\"、\"migrate old project\"、\"rebuild from existing\"、\"refactor from old codebase\"、\"从旧项目迁移过来\"、\"用旧项目做参考重建\"、\"分析旧项目并迁移\"; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`.\nSKIP: any content task — generating components, pages, services, or reviewing screens; changes to `src/` files outside the component upgrade flow, design tokens, or business logic. Those go to teamix-evo-code-opentrek or teamix-evo-design-opentrek. SKIP if the user is mid-flow inside an already-initialized project asking to \"新增页面 / 加按钮 / 调接口\" — that's coding work, not lifecycle. SKIP pure styling / token tweaks — those go to ESLint + `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-opentrek (visual side after a screen is generated)、teamix-evo-code-opentrek (file placement / reuse rules) — manage is the entry point and precedes content skills, never co-triggers.",
+      "description": "Single entry point for the teamix-evo lifecycle: scaffold a new project skeleton, install the AI coding system into an existing repo via `teamix-evo init`, inspect / remove any teamix-evo package, manage component-source upgrades, and drive old-project migration/rebuild.\nTRIGGER when: (CLI) user runs or asks about `teamix-evo init` / `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo blocks ...` / `teamix-evo lint ...` / `teamix-evo logs ...` / `teamix-evo restore ...` / `teamix-evo switch ...`, or `npm create teamix-evo` / `pnpm create teamix-evo`; (模糊初始化) \"初始化一个项目\"、\"初始化一个工程\"、\"初始化一个 teamix-evo 工程\"、\"初始化一个 Teamix Evo 项目\"、\"create a teamix-evo project\"、\"set up teamix-evo from scratch\"、\"new teamix-evo app\"; (具名变体初始化) \"初始化一个 opentrek 工程 / op 工程 / OpenTrek 项目 / 探索者项目\"、\"初始化一个云管 / 云管控制台 / 云管项目 / uni-manager 工程 / 云管工程\"、\"new opentrek/uni-manager project\"; (AI coding 接入) \"给现有仓库装 teamix-evo\"、\"现有项目装一下 skills + ui\"、\"接入 AI coding 体系\"、\"装 teamix-evo 进这个项目\"、\"add teamix-evo to existing repo\"、\"install AI coding system\"、\"接入 opentrek 研发体系\"、\"接入 op 研发体系\"、\"接入 OpenTrek 研发体系\"、\"接入 opentrek 研发系统\"、\"接入 op 研发系统\"、\"接入云管研发体系\"、\"接入云管研发系统\"、\"接入 uni-manager 研发体系\"、\"接入 uni-manager 研发系统\"、\"接入统一管理研发体系\"; (组件源码升级 — ADR 0040) \"升级 ui\"、\"升级业务组件\"、\"升级 button\"、\"生成 ui staging\"、\"生成 biz-ui staging\"、\"upgrade ui\"、\"upgrade biz-ui\"、\"upgrade ui component\"、\"stage ui upgrade\"、\"teamix-evo ui upgrade\"、\"teamix-evo biz-ui upgrade\"; (卸载 / 清单) \"卸载 teamix-evo\"、\"看看装了哪些 teamix-evo 资源\"、\"remove the design system\"、\"list installed\"; (旧工程迁移) \"迁移旧项目\"、\"重建老工程\"、\"把旧项目搬过来\"、\"旧项目分析\"、\"旧系统翻新\"、\"legacy migration\"、\"migrate old project\"、\"rebuild from existing\"、\"refactor from old codebase\"、\"从旧项目迁移过来\"、\"用旧项目做参考重建\"、\"分析旧项目并迁移\"、\"代码迁移\"、\"执行代码迁移\"、\"执行迁移\"、\"开始迁移\"、\"项目迁移\"、\"code migration\"、\"run migration\"、\"start migration\"、\"迁移代码\"、\"迁移项目\"; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`.\nSKIP: any content task — generating components, pages, services, or reviewing screens; changes to `src/` files outside the component upgrade flow, design tokens, or business logic. Those go to teamix-evo-code-opentrek or teamix-evo-design-opentrek. SKIP if the user is mid-flow inside an already-initialized project asking to \"新增页面 / 加按钮 / 调接口\" — that's coding work, not lifecycle. SKIP pure styling / token tweaks — those go to ESLint + `tokens.overrides.css`.\nCoordinates with: teamix-evo-design-opentrek (visual side after a screen is generated)、teamix-evo-code-opentrek (file placement / reuse rules) — manage is the entry point and precedes content skills, never co-triggers.",
       "version": "0.4.0",
       "source": "src/teamix-evo-manage",
       "ides": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamix-evo/skills",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Skills (AI IDE capabilities) for Teamix Evo",
   "type": "module",
   "files": [

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

@@ -2,7 +2,7 @@
 name: teamix-evo-manage
 description: |
   Single entry point for the teamix-evo lifecycle: scaffold a new project skeleton, install the AI coding system into an existing repo via `teamix-evo init`, inspect / remove any teamix-evo package, manage component-source upgrades, and drive old-project migration/rebuild.
-  TRIGGER when: (CLI) user runs or asks about `teamix-evo init` / `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo blocks ...` / `teamix-evo lint ...` / `teamix-evo logs ...` / `teamix-evo restore ...` / `teamix-evo switch ...`, or `npm create teamix-evo` / `pnpm create teamix-evo`; (模糊初始化) "初始化一个项目"、"初始化一个工程"、"初始化一个 teamix-evo 工程"、"初始化一个 Teamix Evo 项目"、"create a teamix-evo project"、"set up teamix-evo from scratch"、"new teamix-evo app"; (具名变体初始化) "初始化一个 opentrek 工程 / op 工程 / OpenTrek 项目 / 探索者项目"、"初始化一个云管 / 云管控制台 / 云管项目 / uni-manager 工程 / 云管工程"、"new opentrek/uni-manager project"; (AI coding 接入) "给现有仓库装 teamix-evo"、"现有项目装一下 skills + ui"、"接入 AI coding 体系"、"装 teamix-evo 进这个项目"、"add teamix-evo to existing repo"、"install AI coding system"、"接入 opentrek 研发体系"、"接入 op 研发体系"、"接入 OpenTrek 研发体系"、"接入 opentrek 研发系统"、"接入 op 研发系统"、"接入云管研发体系"、"接入云管研发系统"、"接入 uni-manager 研发体系"、"接入 uni-manager 研发系统"、"接入统一管理研发体系"; (组件源码升级 — ADR 0040) "升级 ui"、"升级业务组件"、"升级 button"、"生成 ui staging"、"生成 biz-ui staging"、"upgrade ui"、"upgrade biz-ui"、"upgrade ui component"、"stage ui upgrade"、"teamix-evo ui upgrade"、"teamix-evo biz-ui upgrade"; (卸载 / 清单) "卸载 teamix-evo"、"看看装了哪些 teamix-evo 资源"、"remove the design system"、"list installed"; (旧工程迁移) "迁移旧项目"、"重建老工程"、"把旧项目搬过来"、"旧项目分析"、"旧系统翻新"、"legacy migration"、"migrate old project"、"rebuild from existing"、"refactor from old codebase"、"从旧项目迁移过来"、"用旧项目做参考重建"、"分析旧项目并迁移"; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`.
+  TRIGGER when: (CLI) user runs or asks about `teamix-evo init` / `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo blocks ...` / `teamix-evo lint ...` / `teamix-evo logs ...` / `teamix-evo restore ...` / `teamix-evo switch ...`, or `npm create teamix-evo` / `pnpm create teamix-evo`; (模糊初始化) "初始化一个项目"、"初始化一个工程"、"初始化一个 teamix-evo 工程"、"初始化一个 Teamix Evo 项目"、"create a teamix-evo project"、"set up teamix-evo from scratch"、"new teamix-evo app"; (具名变体初始化) "初始化一个 opentrek 工程 / op 工程 / OpenTrek 项目 / 探索者项目"、"初始化一个云管 / 云管控制台 / 云管项目 / uni-manager 工程 / 云管工程"、"new opentrek/uni-manager project"; (AI coding 接入) "给现有仓库装 teamix-evo"、"现有项目装一下 skills + ui"、"接入 AI coding 体系"、"装 teamix-evo 进这个项目"、"add teamix-evo to existing repo"、"install AI coding system"、"接入 opentrek 研发体系"、"接入 op 研发体系"、"接入 OpenTrek 研发体系"、"接入 opentrek 研发系统"、"接入 op 研发系统"、"接入云管研发体系"、"接入云管研发系统"、"接入 uni-manager 研发体系"、"接入 uni-manager 研发系统"、"接入统一管理研发体系"; (组件源码升级 — ADR 0040) "升级 ui"、"升级业务组件"、"升级 button"、"生成 ui staging"、"生成 biz-ui staging"、"upgrade ui"、"upgrade biz-ui"、"upgrade ui component"、"stage ui upgrade"、"teamix-evo ui upgrade"、"teamix-evo biz-ui upgrade"; (卸载 / 清单) "卸载 teamix-evo"、"看看装了哪些 teamix-evo 资源"、"remove the design system"、"list installed"; (旧工程迁移) "迁移旧项目"、"重建老工程"、"把旧项目搬过来"、"旧项目分析"、"旧系统翻新"、"legacy migration"、"migrate old project"、"rebuild from existing"、"refactor from old codebase"、"从旧项目迁移过来"、"用旧项目做参考重建"、"分析旧项目并迁移"、"代码迁移"、"执行代码迁移"、"执行迁移"、"开始迁移"、"项目迁移"、"code migration"、"run migration"、"start migration"、"迁移代码"、"迁移项目"; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`.
   SKIP: any content task — generating components, pages, services, or reviewing screens; changes to `src/` files outside the component upgrade flow, design tokens, or business logic. Those go to teamix-evo-code-opentrek or teamix-evo-design-opentrek. SKIP if the user is mid-flow inside an already-initialized project asking to "新增页面 / 加按钮 / 调接口" — that's coding work, not lifecycle. SKIP pure styling / token tweaks — those go to ESLint + `tokens.overrides.css`.
   Coordinates with: teamix-evo-design-opentrek (visual side after a screen is generated)、teamix-evo-code-opentrek (file placement / reuse rules) — manage is the entry point and precedes content skills, never co-triggers.
 ---
@@ -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` 文件也删除。
 
@@ -513,6 +513,7 @@ npx teamix-evo ui promote-to-biz --staging-dir <path>  # 指定 staging 目录
    - 存在 → 进入步骤 3。
    - 不存在 → 告知用户："旧项目尚未生成 repo-wiki，请先在旧项目目录使用 Qoder 生成 repo-wiki，完成后告诉我。"等待用户确认后重检。
 3. **读取 repo-wiki** — 增量读取 `<old-path>/.qoder/repowiki/` 目录内容。优先读中文版（`repowiki/zh/`），其次英文版（`repowiki/en/`）。按文件名语义识别：
+
    - 项目总览 / 概述
    - 目录结构 / 模块划分
    - 页面 / 路由清单
@@ -521,6 +522,7 @@ npx teamix-evo ui promote-to-biz --staging-dir <path>  # 指定 staging 目录
    - 依赖清单
 
    > 不一次性读完全部内容（token 预算有限）。先读概览 + 路由，后续按需深入。
+
 4. **补充读取**（若 repo-wiki 不完整）— 直接读旧项目的：
    - `package.json`（依赖 / scripts）
    - 路由配置文件（`src/routes/`、`src/router/`、`pages/` 目录等）
@@ -536,16 +538,62 @@ 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. **三轨齐备** — 进入任何页面实现前必须 wiki + 源码 + 截图全部就绪。
+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. 执行三轨采集 — 对当前页面补全 wiki + 源码 + 截图
+6. 开始实现 — 从第一个未完成条目继续
+
+> 注：若不确定旧项目是否仍在运行，先尝试访问 Source URL。超时则降级为两轨模式并标注。
+
+## 关键文件索引
+
+| 文件         | 路径                                                      | 用途                           |
+| ------------ | --------------------------------------------------------- | ------------------------------ |
+| 迁移计划     | `.teamix-evo/migrate-plan.md`                             | 进度跟踪 + 执行规则（本文件）  |
+| Token 映射表 | `.teamix-evo/migrate-token-mapping.md`                    | CSS 变量 → Tailwind class 映射 |
+| 截图目录     | `.teamix-evo/migrate-screenshots/`                        | 每页截图参考                   |
+| 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 时间戳>
@@ -555,65 +603,149 @@ npx teamix-evo ui promote-to-biz --staging-dir <path>  # 指定 staging 目录
 ## 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 也需要截图参考：使用 Source URL 对旧项目的吸顶和左导截图，存入 `.teamix-evo/migrate-screenshots/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. **Wiki 轨**：读旧项目 repo-wiki 中该页面相关的描述（功能说明、业务规则、数据流）
+    b. **源码轨**：读旧项目该页面的全部源文件（页面组件 + 子组件 + 页面内弹窗 Dialog / 抽屉 Drawer / 确认框等）
+    c. **截图轨**：检查 `.teamix-evo/migrate-screenshots/<page-name>/` 是否已有该页面截图。
+
+- **已有截图** → 直接读取作为视觉参考。
+- **无截图** → 使用 Phase A 中用户提供的 Source URL，通过浏览器访问该页面并截图存入固定路径。
+
+**截图存放约定**：所有截图存放在 `.teamix-evo/migrate-screenshots/<page-name>/` 目录下，文件名约定：
+
+- `default.png` — 页面默认态
+- `dialog-<名称>.png` — 弹窗打开态
+- `drawer-<名称>.png` — 抽屉打开态
+- `state-empty.png` / `state-loading.png` / `state-error.png` — 特殊状态
+
+截图范围须覆盖：
+
+- 页面默认态（列表 / 表单 / 详情等主视图）
+- 页面内所有弹窗（Dialog / Modal）的打开态
+- 页面内所有抽屉（Drawer / Sheet）的打开态
+- 关键交互状态（空态 / 加载态 / 错误态，若能触发）
+
+> **为什么固定路径**：因为迁移工作通常跨多个会话。截图存在固定位置，新会话可直接读取作为视觉参考，无需再次启动旧项目截图。
+
+> ⚠️ **硬约束：三轨齐备方可动手。** AI 必须在 wiki、源码、截图三轨全部采集完成后，才能开始该页面的实现。**AI 不得自行跳过截图轨**——只有用户明确要求「跳过截图」或旧项目确实无法访问（超时 / 报错）时，才可降级为两轨模式，并标注"⚠️ 无截图参考，视觉还原需用户人工校对"。
 
-   > 三轨齐备后，向用户确认："已采集完 <页面名> 的 wiki、源码、截图，开始实现？"用户确认后才动手。若截图不可用（旧项目未运行），告知用户并以 wiki + 源码两轨继续，标注"无截图参考，视觉还原需用户人工校对"。
+三轨齐备后，向用户确认："已采集完 <页面名> 的 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 +754,42 @@ 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 步顺序恢复上下文
+    - 读 `.teamix-evo/migrate-screenshots/` 目录，确认已有哪些页面的截图可作为视觉参考
+    - `in-progress` → 定位第一个 `[ ]` 条目，从断点处继续；若当前页面已有截图，直接读取作为参考，无需重新截图
     - `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 依赖 — 仅迁移业务必需的第三方库（如图表库、富文本编辑器）。
 - **不要**在用户未确认计划前开始实现。