@teamix-evo/skills 0.12.1 → 0.13.0

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

@@ -0,0 +1,373 @@
+# Rearchitect (旧工程重构重建)
+
+## 触发
+
+用户在已初始化的 teamix-evo 项目中说"迁移旧项目 / 重建老工程 / 把旧项目搬过来 / 旧项目分析 / 旧系统翻新 / legacy migration / migrate old project / rebuild from existing project / refactor from old codebase / 从旧项目迁移过来 / 用旧项目做参考重建 / 分析旧项目并迁移"。
+
+> **前提**：当前目录已有 `.teamix-evo/config.json`（即已走完冷启动的初始化）。若当前目录未初始化，先引导用户完成初始化再回到本场景。
+
+## AI 行为协议（三阶段闭环）
+
+### Phase A · 信息收集
+
+1. **询问三轨材料** — 一次性向用户索取迁移所需的三轨材料（工具详情见 [rearchitect-capture-guide.md](rearchitect-capture-guide.md)）：
+
+   a. **旧项目源码路径** — 旧项目的**绝对路径**（`<old-path>`）
+   b. **Repo-wiki** — 旧项目的 repo-wiki（通过 **Qoder 客户端**内置 repowiki 功能生成，产物在 `<old-path>/.qoder/repowiki/`）
+   c. **页面截图目录** — 通过 **Qoderwork 客户端**完成批量截图，提供截图目录路径
+
+   向用户提示准备建议话术：
+
+   > "请在 **Qoder 客户端**中打开旧项目目录，使用内置 repowiki 功能生成项目文档。然后在 **Qoderwork 客户端**中打开待迁移项目 URL，对所有页面及页面内的弹窗、抽屉进行截图，按页面路由为文件夹名落地，完成后提供截图目录路径。详细操作见 [rearchitect-capture-guide.md](rearchitect-capture-guide.md)。"
+   >
+   > ⚠️ **AI 不执行截图操作**。截图由用户通过 Qoderwork 客户端完成并提供目录路径。AI 仅使用用户提供的截图作为视觉参考。
+
+2. **检测 repo-wiki** — 检查 `<old-path>/.qoder/repowiki/` 是否存在且非空：
+   - 存在 → 进入步骤 3。
+   - 不存在 → 告知用户："旧项目尚未生成 repo-wiki，请在 **Qoder 客户端**中打开旧项目目录，使用内置 repowiki 功能生成，完成后告诉我。"等待用户确认后重检。
+3. **读取 repo-wiki** — 增量读取 `<old-path>/.qoder/repowiki/` 目录内容。优先读中文版（`repowiki/zh/`），其次英文版（`repowiki/en/`）。按文件名语义识别：
+
+   - 项目总览 / 概述
+   - 目录结构 / 模块划分
+   - 页面 / 路由清单
+   - API 端点清单
+   - 数据模型 / 类型定义
+   - 依赖清单
+
+   > 不一次性读完全部内容（token 预算有限）。先读概览 + 路由，后续按需深入。
+
+4. **检测截图目录** — 检查用户提供的截图目录是否存在且非空：
+   - 存在且含截图 → 记录路径，进入步骤 5。
+   - 不存在或为空 → 告知用户截图目录不可用，请先按建议完成截图后再继续。
+5. **补充读取**（若 repo-wiki 不完整）— 直接读旧项目的：
+   - `package.json`（依赖 / scripts）
+   - 路由配置文件（`src/routes/`、`src/router/`、`pages/` 目录等）
+   - 目录结构（`ls src/`）
+6. **识别旧项目技术栈** — 从依赖和代码判断，记录以下维度：
+   - UI 框架（antd / element-ui / arco-design / mui / naive-ui / 自研）
+   - 路由方案（react-router / vue-router / next.js / umi）
+   - 状态管理（redux / mobx / zustand / pinia / vuex）
+   - HTTP 客户端（axios / fetch / umi-request / swr / react-query）
+   - 构建工具（webpack / vite / umi / next / create-react-app）
+
+### Phase B · 计划生成
+
+6. **读取目标 design skill 提取设计基线** — 从 `.teamix-evo/config.json` 读取当前 variant，然后读取对应 design skill 的关键文件：
+
+   | 文件 | 提取内容 |
+   | --- | --- |
+   | `foundations.md` | 字号表（各级 font-size → Tailwind class）、间距表（8 档）、色彩语义（primary / muted / accent / destructive 等）、圆角规范、阴影层级 |
+   | `patterns/page-types.md` | 标准页面类型定义（List / Detail / Form / Dashboard / Wizard 等）+ 每类标准结构 |
+   | `components.md` | 组件选型决策树 + 双层架构（ui 原子件 / biz-ui 业务件） |
+   | `boundaries.md` | 硬约束规则摘要（ERROR 级别） |
+
+   提取结果嵌入 `migrate-plan.md` 的 `Design Baseline` 区块（见下方模板），使后续 Token 映射表生成和页面分类有明确的目标参照系。
+
+7. **生成迁移计划文件** — 写入 `.teamix-evo/migrate-plan.md`。
+
+   > ⚠️ **前置检查**：若 `.teamix-evo/migrate-plan.md` 已存在，**必须先询问用户**三选一：
+   > - **(a) 恢复进度继续** — 不重新生成，直接进入 Phase C 从第一个 `[ ]` 条目继续
+   > - **(b) 重新生成（覆盖）** — 覆盖旧计划。覆盖前检查 `migrate-token-mapping.md` 是否存在，若存在则追问："Token 映射表已存在，是一并重建还是保留现有映射？"
+   > - **(c) 查看当前计划** — 只读展示现有计划摘要（进度 / 已完成数 / 剩余页面），不做任何修改
+   >
+   > **禁止跳过此检查直接覆盖。**
+
+   计划文件格式如下：
+
+````markdown
+# Migration Plan
+
+## ❗ 执行规则（每次读取本文件时必须重新确认）
+
+1. **Token 映射查表** — 每迁移一个页面前，必须先读取 `.teamix-evo/migrate-token-mapping.md`，所有旧项目 CSS 变量按实际像素值映射为新项目 Tailwind class。禁止根据变量名称"猜测"对应关系。
+2. **组件与代码规范**（摘自 design-{variant} + code-{variant} skill，完整规则见关键文件索引）
+   - **组件选用优先级（不得跳级）**：`./rules/` 已定义组件 → `@teamix-evo/ui` 原子组件拼装 → 自定义实现（需 `<!-- CUSTOM: 原因 -->` 标注）
+   - **组件尺寸**：无特殊说明时一律使用 default 尺寸，不主动用 sm
+   - **核心 UI 组件速查**：Card / Table / Badge / Separator / Tabs / ToggleGroup / Button / Tag / Dialog / Sheet / Select / Input / Empty / Spinner / Tooltip
+   - **Token 引用**：所有视觉属性必须引用 Token，禁止硬编码色值 / 间距 / 字号
+   - **代码分层**：pages（页面组件）→ hooks（数据逻辑）→ services（API 封装）→ types（类型定义）
+   - **reuse-first**：优先复用 `@teamix-evo/ui` 已有组件，禁止重复造轮子
+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 并提取页面级约束**（路径见下方「关键文件索引」）：
+   - 读取 **Design skill** → 重点关注 §6.1 组件选用优先级、§5 通用组件分层、§6.5 降级拼装规则
+   - 读取 **Code skill** → 重点关注 reuse-first.md、file-structure.md、api-layering.md
+   - 读取 **Manage skill** rearchitect.md → 获取迁移执行协议的逐条步骤
+   - **提取原则**：每个待迁移页面的每个 UI 元素，先在 `@teamix-evo/ui` 组件库（`src/components/ui/`）中查找对应组件，找到则直接使用；找不到才允许自定义实现
+   - 确认本文件 `Design Baseline` 区块已填充（字号表 / 间距表 / 色彩语义 / 页面类型）。若为空模板，按 Phase B 步骤 6 从 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`           | 迁移执行协议（rearchitect.md）   |
+| 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 客户端> + <状态管理>
+- **Screenshots dir**: <用户提供的截图目录绝对路径>
+
+## Design Baseline (AI 从 design-{variant} skill 动态提取)
+
+> 以下数据由 Phase B 步骤 6 从目标 variant 的 design skill 提取，作为 Token 映射表的目标参照系和页面分类依据。
+
+### 字号表
+
+| 级别 | 像素值 | Tailwind class | 语义用途 |
+| --- | --- | --- | --- |
+| ... | ... | ... | ... |
+
+### 间距表
+
+| 级别 | 像素值 | Tailwind class |
+| --- | --- | --- |
+| ... | ... | ... |
+
+### 色彩语义
+
+| 语义名 | CSS 变量 | Tailwind class | 用途 |
+| --- | --- | --- | --- |
+| primary | ... | text-primary / bg-primary | ... |
+| muted | ... | text-muted-foreground | ... |
+| ... | ... | ... | ... |
+
+### 圆角 & 阴影
+
+| 属性 | 值 | Tailwind class |
+| --- | --- | --- |
+| ... | ... | ... |
+
+### 页面类型定义 (摘自 patterns/page-types.md)
+
+| 类型 | 标准结构 | 典型场景 |
+| --- | --- | --- |
+| ListPage | ... | 资源列表 / CRUD |
+| DetailPage | ... | 资源详情 / 监控 |
+| FormPage | ... | 创建 / 编辑表单 |
+| Dashboard | ... | 概览 / 数据看板 |
+| ... | ... | ... |
+
+## Component Mapping (AI 通过 .teamix-evo/meta/ui/manifest.json 动态生成)
+
+| Old | New (teamix-evo) | Notes |
+| --- | ---------------- | ----- |
+| ... | ...              | ...   |
+
+## Phase 0: Global Infrastructure
+
+- [ ] **清理脚手架示例页面** — 删除 `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** — 鉴权流程
+- [ ] **Global state** — 全局状态管理
+- [ ] **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 名。
+  >
+  > **交叉校验**：映射表生成后，必须与上方 `Design Baseline` 区块的字号表 / 间距表 / 色彩语义进行逐项比对，确认每个映射目标都在目标 variant 的 token 体系内。若发现映射目标不在 baseline 中，标注「❗ 不在目标 token 体系」。
+
+## Phase 1: <页面名> (complexity: <simple|medium|complex>)
+
+> ⚠️ 执行前检查：① 已读取 `migrate-token-mapping.md` ② 已确认§2 组件与代码规范（组件优先级 / 尺寸 / reuse-first） ③ 三轨已采集
+
+- Route: `<路由路径>`
+- [ ] **<子任务>** — <描述> (<使用组件>)
+- [ ] **API integration** — <接口列表>
+
+## Phase N: ...
+````
+
+**组件映射生成规则**：通过读 `.teamix-evo/meta/ui/manifest.json` 查询 teamix-evo 注册表，逐个匹配旧项目使用的 UI 组件，动态填写映射表。
+
+8. **展示计划摘要** — 向用户复述：
+
+   - 总页面数
+   - 按复杂度分布（简单 / 中等 / 复杂）
+   - 建议执行顺序
+   - 询问用户是否调整顺序、跳过某些页面、或补充遗漏页面
+
+9. **确认迁移节奏** — 向用户提问：
+
+   > "您希望先迁移几个页面验证效果，还是直接开始全量迁移？"
+
+   - **先验证（推荐）**：用户选择 1–3 个代表性页面（建议包含一个简单页 + 一个复杂页），先做完这几个让用户检验代码质量、视觉还原度、组件映射质量后再继续剩余页面
+   - **全量迁移**：按计划顺序逐页执行，每完成一个 Phase 后向用户汇报
+
+   在 `migrate-plan.md` 顶部 Progress 区块记录用户选择：
+
+   - `Mode: pilot` + `Pilot pages: <页面名列表>` — 验证模式，仅执行指定页面
+   - `Mode: full` — 全量模式
+
+   > pilot 模式完成后，向用户确认："验证页面已完成，是否继续迁移剩余页面？"用户确认后将 Mode 改为 `full` 并继续。
+
+   > Phase B → Phase C 之间**必须**有用户的明确确认（go-ahead）。
+
+### Phase C · 执行
+
+10. **读取当前进度** — 读 `.teamix-evo/migrate-plan.md` 顶部 Progress 区块。若 Status 为 `done` → 告知用户迁移已全部完成。否则找到第一个未完成（`[ ]`）的条目。
+11. **三轨确认（每页开发前必做）** — 进入一个页面的开发前，必须确认三轨材料均已就绪：
+    a. **源码轨**：读旧项目该页面的全部源文件（页面组件 + 子组件 + 页面内弹窗 Dialog / 抽屉 Drawer / 确认框等）
+    b. **Wiki 轨**：读旧项目 repo-wiki 中该页面相关的描述（功能说明、业务规则、数据流）
+    c. **截图轨**：检查用户提供的截图目录中 `<screenshots-dir>/<page-route>/` 是否已有该页面截图。
+
+- **已有截图** → 直接读取作为视觉参考。
+- **截图缺失** → 暂停并告知用户："<页面名> 缺少截图，请补充后告诉我。"等待用户补充后继续。
+
+**截图存放约定**：用户通过 **Qoderwork 客户端**预先准备，按页面路由为文件夹名，存放在用户提供的截图目录下。文件命名约定和覆盖范围详见 [rearchitect-capture-guide.md](rearchitect-capture-guide.md)。
+
+> **AI 不执行截图**：截图由用户在迁移开始前通过 Qoderwork 客户端一次性完成，迁移过程中 AI 仅读取已有截图作为视觉参考。
+
+> ⚠️ **硬约束：三轨齐备方可动手。** AI 必须在源码、wiki、截图三轨全部确认就绪后，才能开始该页面的实现。**AI 不得自行跳过截图轨**——只有用户明确要求「跳过截图」时，才可降级为两轨模式，并标注"⚠️ 无截图参考，视觉还原需用户人工校对"。
+
+三轨确认后，向用户确认："<页面名> 的源码、repo-wiki、截图三轨已确认就绪，开始实现？"用户确认后才动手。
+
+12. **逐条实现** — 对每个 checklist 条目：
+    a. 通过读 `.teamix-evo/meta/ui/manifest.json` + `<id>.md` 查询可用组件
+    b. **读取 code/design skill 并确认关键约束** — 必须先读取 `teamix-evo-code-{variant}` 和 `teamix-evo-design-{variant}` 的 SKILL.md，提取组件选用优先级（§6.1）、尺寸规范、reuse-first 等关键规则。**禁止未读取就开始写代码**。若当前会话已读取过且上下文未丢失，可跳过重复读取
+    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 名>`
+13. **验证** — 每完成一个页面后：
+    - 列出该页面的功能检查点（从旧代码提取的关键交互：CRUD / 筛选 / 分页 / 权限 / 弹窗流程等）
+    - 若有截图，建议用户对比新旧页面视觉差异
+    - 跑 `pnpm typecheck` 确认零类型错误
+
+### Phase D · 全量 Review
+
+14. **全部页面完成后** — 当 Progress 中 Completed 等于总条目数时：
+    - 将 Status 更新为 `review`
+    - 向用户提示："所有页面已迁移完成，建议进行一轮整体 review。是否现在开始？"
+    - 用户确认后，逐页面列出 review 检查点：
+      - 功能完整性（对照旧项目关键流程）
+      - 视觉还原度（对照截图）
+      - 路由可达性（所有页面是否串通）
+      - 全局一致性（Layout / 导航 / 权限守卫是否统一）
+    - review 全部通过后，将 Status 更新为 `done`
+15. **会话恢复** — 若 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}`）**：页面级布局 / 视觉设计决策。迁移新页面时并行参考。
+- **用户**：提供旧项目路径 / 确认 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 且源码量大时一次性读完全部文件 — 分批按需读取。
+- **不要**跳过 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 依赖 — 仅迁移业务必需的第三方库（如图表库、富文本编辑器）。
+- **不要**在用户未确认计划前开始实现。
+- **不要**试图单次会话完成全部迁移 — 大项目分多次会话，每次完成若干页面后让用户验证。
+- **不要**破坏 `migrate-plan.md` 的 `- [ ]` / `- [x]` 格式 — 后续会话靠它恢复进度。
+- **不要**修改旧项目的任何文件 — 旧项目只读。

package/src/teamix-evo-manage/update-component-staging.md

@@ -0,0 +1,188 @@
+# Part B — Component source upgrade
+
+When `teamix-evo ui update [id]` or `teamix-evo biz-ui update [id]` runs, the CLI compares the consumer's installed component source against the latest upstream package contents and writes a **staging directory**:
+
+```
+.teamix-evo/.upgrade-staging/
+└── ui-2026-06-12T12-00-00-000Z/
+    ├── meta.json                       # UpgradeStagingManifest
+    ├── button/
+    │   ├── current.tsx                  # what is on disk now
+    │   └── incoming.tsx                 # alias-rewritten upstream source
+    └── …
+```
+
+> **v1 note** — CLI does **not** pre-render `diff.unified.patch`. The schema's `diffRelPath` field is reserved for a future v2 emitter; today this skill diffs `current.tsx` against `incoming.tsx` on the fly (B4).
+
+The CLI **never writes** into `src/components/{ui,business}/**` — frozen boundary (组件源码属于用户，CLI 只写 staging 目录). This flow is the only path to land staged changes.
+
+## Staging manifest payload (schema v1)
+
+```json
+{
+  "schemaVersion": 1,
+  "ts": "2026-06-12T12:00:00.000Z",
+  "package": "ui",
+  "trigger": "ui-upgrade",
+  "fromVersion": "0.7.0",
+  "toVersion": "0.8.0",
+  "lineage": "teamix-evo",
+  "summary": {
+    "total": 4,
+    "byRisk": { "unchanged": 1, "upgradable-medium": 2, "risky": 1 }
+  },
+  "entries": [
+    {
+      "id": "button",
+      "category": "ui",
+      "current": {
+        "target": "src/components/ui/button.tsx",
+        "hash": "sha256:…",
+        "sourceLineage": "teamix-evo"
+      },
+      "incoming": {
+        "sourceVersion": "0.8.0",
+        "hash": "sha256:…",
+        "relPath": "button/incoming.tsx"
+      },
+      "diff": {
+        "riskLevel": "upgradable-medium",
+        "hints": ["new export: ButtonGroup"],
+        "filesChangedCount": 1
+      }
+    }
+  ]
+}
+```
+
+`riskLevel` 风险等级：
+
+| level | 含义 | 建议处理方式 |
+| --- | --- | --- |
+| `unchanged` 无变化 | hash 一致，无需处理 | 自动跳过 |
+| `upgradable-low` 低风险 | 单文件变动，无新增/移除导出或 cva 变体 | 逐个确认 |
+| `upgradable-medium` 中风险 | 新增导出 / 新增 cva 变体 / 多文件变动 | 逐文件确认 |
+| `risky` 高风险 | 移除了导出 / 移除了 cva 变体 / props 重命名 | 逐个讨论，展示变更提示 |
+| `breaking` 破坏性变更 | 上游整个移除了该组件 | 明确标记，禁止自动替换 |
+| `foreign` 未登记 | 文件存在于 `src/` 但无上游来源 / 不在 manifest 中 | 保持不动，询问用户意图 |
+
+## Workflow (6 steps, never skip step 5)
+
+### B1 · Discover
+
+```bash
+ls -1d .teamix-evo/.upgrade-staging/{ui,biz-ui}-*/ 2>/dev/null | sort -r
+```
+
+If the directory is missing or empty:
+
+> 当前没有待应用的组件升级 staging。请先跑 `teamix-evo ui update [id]` / `teamix-evo biz-ui update [id]` 生成。
+
+### B2 · 读取 manifest 并输出总览
+
+解析 `meta.json`，根据 `lineage`（组件来源谱系）选择开场消息：
+
+| lineage | 开场消息模板 |
+| --- | --- |
+| `teamix-evo` | `检测到 X 个组件，其中 Y 个有变化（无变化=A、低风险=B、中风险=C、高风险=D、破坏性=E）。准备逐个 review。` |
+| `mixed` 混合来源 | `检测到 Z 个 teamix-evo 组件 + W 个未登记组件。先处理可升级项，最后与你商量未登记组件去留。` |
+| `shadcn-native` | `你当前是 shadcn 原生安装（未使用 teamix-evo 的资产）。升级前建议先迁移到 teamix-evo 谱系（执行「teamix-evo ui init」重新安装），或者手动对齐调谐表。是否继续详细对比？`（CLI 这种情况不会生成 staging，但用户可能手工走到这一步） |
+| `custom-only` 纯自定义 | （CLI 已跳过，不会出现在 staging 中 — 若出现是异常，请提示用户检查） |
+
+### B3 · 升级计划与分流
+
+70+ 组件逐个过 review 工作量大，先给用户一个全局总览再动手。
+
+**1. 汇总表** — 按风险等级统计，展示如下格式：
+
+```
+┌──────────────────────────┬──────┬──────────────────────────────┐
+│ 风险等级                  │ 数量 │ 代表组件                      │
+├──────────────────────────┼──────┼──────────────────────────────┤
+│ 无变化 (unchanged)        │ 55   │ (跳过，无需处理)              │
+│ 低风险 (upgradable-low)   │ 8    │ badge, separator, spinner … │
+│ 中风险 (upgradable-medium)│ 4    │ button, select, table …     │
+│ 高风险 (risky)            │ 1    │ data-table                   │
+│ 破坏性 (breaking)         │ 0    │ —                            │
+│ 未登记 (foreign)          │ 2    │ custom-chart, legacy-modal   │
+├──────────────────────────┼──────┼──────────────────────────────┤
+│ 需 review 总计            │ 15   │                              │
+└──────────────────────────┴──────┴──────────────────────────────┘
+```
+
+**2. 让用户选择 review 策略**：
+
+> 本次升级共 X 个组件有变化，建议选择 review 策略：
+>
+> 1. **全部 review**（默认）— 按风险从高到低逐个过
+> 2. **只看高风险以上** — 先处理高风险 + 破坏性变更，低/中风险自动接受
+> 3. **按组件类型分批** — 先过 ui 组件，再过 biz-ui 组件，可以分多次会话完成
+> 4. **暂不处理** — 保留 staging 目录，下次再来
+
+用户选择后记录策略，后续 B4–B5 按策略执行：
+
+- 策略 1/3：所有有变化的组件都走 B5 的逐个 diff + 确认
+- 策略 2：高风险/破坏性走 B5 逐个确认；低/中风险仍然**逐个展示 diff**（硬性门控不可绕过），但提示用户"此组件风险较低，建议接受"
+- 策略 4：跳过 B4–B6，保留 staging 目录不动
+
+**3. 如果有多个 staging 目录**（跨版本累积），在汇总表前先列出所有 staging 及其版本跨度，让用户选择先处理哪个（默认最新）。
+
+### B4 · 按风险等级分组
+
+遍历 `entries`，按 `riskLevel` 分桶处理：
+
+- **无变化 `unchanged`** — 一行列出组件名，告知"以下组件未变，跳过"。
+- **低风险 `upgradable-low`** — ⤵️ 硬性门控：仍然逐个展示 diff + y/n，禁止合并为一次性批量确认。速度优先时可缩短 diff 显示（只展示变更提示摘要），但每个组件必须独立确认。
+- **中风险 `upgradable-medium`** — 逐个展示变更提示摘要，让用户选择 y/n/逐文件（见 B5）。
+- **高风险 `risky`** — 强制逐组件 review；先完整列出所有变更提示（`hints[]`），再展示 diff。
+- **破坏性 `breaking`** — **禁止**提供自动替换选项。告知用户上游已移除该组件，询问是删除本地文件还是保留为自定义组件（可能是重命名 — 交叉检查已移除的导出）。
+- **未登记 `foreign`** — 单独列出（"以下组件不在 manifest 中，可能是你手工添加的"），询问是否注册、删除或保留。
+
+> **分级原则（B0）**：每个风险等级必须独立分组展示，不得将不同风险等级的组件混在同一批次提问。即使用户要求「全部应用」，也必须按风险等级分组逐个展示。
+
+### B5 · 展示差异并确认（硬性门控）
+
+对每个有变化且用户同意 review 的组件，使用与 [update-token-rename.md](update-token-rename.md) 步骤 A4 相同的模板展示 diff，但采用整文件替换而非行内改写。读取 `current.tsx`（当前版本）+ `incoming.tsx`（新版本）实时计算差异（v1 不预生成 `diff.unified.patch` — 若未来 schema 版本的 `diff.diffRelPath` 有值，优先使用该文件）。
+
+```
+─── src/components/ui/button.tsx · 风险=中风险 · 变更提示: 新增导出 ButtonGroup ───
+@@ -1,3 +1,5 @@
+ export const Button = (props: any) => null;
++
++export const ButtonGroup = (props: any) => null;
+
+应用？(y=是 / n=否 / per-file=逐文件选择)
+```
+
+应用方式 = 将 `incoming.tsx` **整文件覆盖**到 `current.target` 路径，原子操作。不做部分合并 — staging 产物是整文件。
+
+**禁止自动应用。** 用户未回应时默认不应用。
+
+⚠️ 硬性门控：即使用户说"全部接受"/"apply all"，**仍然必须逐文件展示 diff**（每个组件一屏），用户看完后才写入。禁止将多个组件的 diff 合并展示或静默批量应用。
+
+若组件风险等级为破坏性（`breaking`）且用户选择删除文件，必须用明确的 `rm` 命令执行，不可静默删除。
+
+### B6 · 归档 staging
+
+所有组件都已应用或明确跳过后：
+
+```bash
+mkdir -p .teamix-evo/.upgrade-staging/.processed
+mv .teamix-evo/.upgrade-staging/<dir> .teamix-evo/.upgrade-staging/.processed/
+```
+
+告知用户 staging 目录已归档，可以用 `git diff` 一次性查看所有已接受的文件替换和 staging 目录移动。
+
+如果用户想**整体推迟**（不是跳过单个组件），保留 staging 目录不动 — 下次可以重新运行本流程。
+
+## 边缘情况
+
+| 情况 | 处理方式 |
+| --- | --- |
+| `meta.json` 解析失败 / schemaVersion 不匹配 | 打印路径 + 解析错误；**不要**删除文件。建议用户重跑 `teamix-evo ui update` 或 `teamix-evo restore --list` |
+| `current.tsx` 与磁盘上的实际文件内容不一致 | 说明用户在 CLI 生成 staging 后本地做了修改。同时展示两份 diff（用户的修改 vs 新版本），让用户手动合并；禁止静默覆盖 |
+| 用户给 CLI upgrade 命令传了 `--apply` | CLI 本身会拒绝并提示 frozen boundary 规则。引导用户走本流程 |
+| 有多个 staging 目录待处理 | 按时间从新到旧逐个处理 — 禁止跨 staging 目录批量操作（不同版本跨度、不同基线） |
+| 用户说"全部接受"/"apply all" | 仍然必须逐个展示 diff 后再应用。批量确认可以，**静默应用不行** |
+| 混合来源（`lineage=mixed`）含未登记组件 | 先处理完可升级组件，再逐个处理未登记组件：注册（引导到 `teamix-evo ui add <id>`）、删除或保留 |
+| 用户要求处理已归档的旧 staging 目录 | 从 `.processed/` 读取 manifest，重新展示 diff，让用户决定是重新应用还是永久移除 |