@teamix-evo/skills 0.5.0 → 0.7.0

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, install the AI coding system into an existing repo, run / update / inspect / remove any teamix-evo package, and drive the placeholder→real UI migration loop after `npm create teamix-evo`.
-  TRIGGER when: (CLI) user runs or asks about `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo templates ...` / `teamix-evo lint ...` / `teamix-evo logs ...`, 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 研发系统"、"接入统一管理研发体系"; (更新检测) "升级 teamix-evo"、"看看哪些要升级"、"update teamix-evo"、"check what needs updating"、"refresh installed teamix-evo packages"; (卸载 / 清单) "卸载 teamix-evo"、"看看装了哪些 teamix-evo 资源"、"remove the design system"、"list installed"; (placeholder→real 升级) "升级 UI"、"接入真组件"、"替换 placeholder"、"upgrade UI"、"replace placeholders"、"swap in real components"、"make the UI real", or user opens / edits `src/components/_placeholder/**`, project contains `.teamix-evo/create/pending-ui.json`, literal `@teamix-evo:placeholder` tag in code; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`、`.teamix-evo/create/pending-ui.json`.
+  TRIGGER when: (CLI) user runs or asks about `teamix-evo init` / `teamix-evo update` / `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo templates ...` / `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 研发系统"、"接入统一管理研发体系"; (更新检测) "升级 teamix-evo"、"看看哪些要升级"、"update teamix-evo"、"check what needs updating"、"refresh installed teamix-evo packages"; (组件源码升级 — 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"; (placeholder→real 升级) "升级 UI"、"接入真组件"、"替换 placeholder"、"upgrade UI"、"replace placeholders"、"swap in real components"、"make the UI real", or user opens / edits `src/components/_placeholder/**`, project contains `.teamix-evo/create/pending-ui.json`, literal `@teamix-evo:placeholder` tag in code; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`、`.teamix-evo/create/pending-ui.json`.
   SKIP: any content task — generating components, pages, services, or reviewing screens; changes to `src/` files outside the migration loop, 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.
 ---
@@ -13,8 +13,8 @@ Single entry skill for the **teamix-evo** toolkit lifecycle. Covers six scenario
 
 1. Fuzzy init → ask user to pick a tokens variant.
 2. Named-variant init → infer variant from business name, run scaffold directly.
-3. AI coding install on existing repo (no scaffold step).
-4. Update detection — only refresh what's already installed.
+3. Adopt teamix-evo into an existing npm repo via `teamix-evo init` (普通版接入, no scaffold step).
+4. Update detection — only refresh what's already installed, including 4e component-source upgrade staging（`ui upgrade` / `biz-ui upgrade`）.
 5. Uninstall.
 6. Placeholder → real UI migration loop (post-`npm create teamix-evo`).
 
@@ -60,7 +60,7 @@ npx teamix-evo@latest skills update --dry-run             # 预览,不写盘
   │     否 ──▶ 继续
   ├── 目录是空的(或只有 .git / README.md)?
   │     是 ──▶ 1 (模糊初始化) — 询问 variant 后转 2
-  │     否 ──▶ 3 (AI coding 接入) — 跳过 scaffold,只跑 tokens/skills/ui init
+  │     否 ──▶ 3 (普通版接入) — `teamix-evo init` 一键检测 + wizard + 6 类冲突 + 静默落地
 ```
 
 ## 业务名 → variant 映射
@@ -75,91 +75,70 @@ npx teamix-evo@latest skills update --dry-run             # 预览,不写盘
 
 校验:`npx teamix-evo tokens list-variants` 列出当前 `@teamix-evo/tokens` 包内所有变体;若上表中的关键词指向尚未发布的变体,先告知用户该 variant 还未上线。
 
-## CLI 命令面(完整)
+## CLI 命令概览
+
+CLI 二进制名 `teamix-evo`（+ 脚手架独立二进制 `create-teamix-evo`）。概览表列出所有子命令与一句话用途；**完整选项请跑 `--help` 或调 MCP 工具动态获取**（见表后说明）。
+
+| Group         | Verb                                                  | 用途                                                                                    |
+| ------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| **create**    | `npm create teamix-evo [dir]`                         | 一站式脚手架：scaffold + tokens + skills + ui + lint                                    |
+| **init**      | `init [-y] [--dry-run] [--variant <v>] [--cwd <dir>]` | 普通版接入：把 teamix-evo 注入已有 npm 工程（三分支决策树 + 6 类冲突检测 + wizard）     |
+| **update**    | `update [--dry-run] [--cwd <dir>]`                    | 套件级升级 orchestrator：tokens → skills（[ADR 0019](docs/adr/0019)）                   |
+| **switch**    | `switch <new-variant> [--apply] [-y] [--cwd <dir>]`   | 切到目标 variant：dry-run 默认，`--apply` 才真写；自动 snapshot + token rename hint     |
+| **restore**   | `restore [<ts>] [--list] [-y] [--cwd <dir>]`          | 失败回滚：从 snapshot 还原 `.teamix-evo/`，pre-restore 自身可逆（ADR 0019 §2）          |
+| **tokens**    | `init <variant>`                                      | 初始化指定变体的 design tokens（`<variant>` 必填）                                      |
+|               | `list-variants`                                       | 列出所有可选变体                                                                        |
+|               | `list`                                                | 列出已装 tokens 资源                                                                    |
+|               | `update`                                              | 刷新 regenerable tokens（frozen 保留，[ADR 0003](docs/adr/0003)）                       |
+|               | `uninstall`                                           | 卸载 tokens                                                                             |
+| **skills**    | `init`                                                | 自举：按 variant + scope 装全部匹配 skill（[ADR 0034](docs/adr/0034) verb 分工）        |
+|               | `add <name...>`                                       | 增量装指定 skill                                                                        |
+|               | `list` (alias `ls`)                                   | 列出全部 skill（`--installed` 仅已装）                                                  |
+|               | `update [name...]`                                    | 升级已装 skill（[ADR 0035](docs/adr/0035) 双闸 + `--scope` + `--dry-run`）              |
+|               | `uninstall [ids...]`                                  | 卸载 skill                                                                              |
+|               | `doctor`                                              | 检测 source ↔ IDE 镜像漂移（[ADR 0013](docs/adr/0013)）                                 |
+|               | `sync [name...]`                                      | 重新镜像到 IDE 路径（不升版本）                                                         |
+| **ui**        | `init`                                                | 初始化 ui 配置（aliases / icon / tsx / rsc）                                            |
+|               | `add <id...>`                                         | 安装 UI 组件（auto-resolve registryDependencies，frozen）                               |
+|               | `list`                                                | 列出 UI 组件（`--installed` / `--include-deprecated`）                                  |
+|               | `upgrade [id...]`                                     | 生成 ui 升级 staging（仅写 `.upgrade-staging/`，[ADR 0040](docs/adr/0040)；skill 应用） |
+| **biz-ui**    | `add <id...>`                                         | 安装业务组件（`--variant` 必填）                                                        |
+|               | `list`                                                | 列出变体下的业务组件                                                                    |
+|               | `list-variants`                                       | 列出可用业务组件变体                                                                    |
+|               | `upgrade [id...]`                                     | 生成 biz-ui 升级 staging（变体感知，[ADR 0040](docs/adr/0040)；skill 应用）             |
+| **templates** | `add <id...>`                                         | 安装页面模板（`--variant` 必填）⚠️ AI 默认不主动调用（[ADR 0031](docs/adr/0031)）       |
+|               | `list`                                                | 列出变体下的模板                                                                        |
+|               | `list-variants`                                       | 列出可用模板变体                                                                        |
+| **lint**      | `init`                                                | 初始化 ESLint + Stylelint token-discipline 规则                                         |
+| **logs**      | `analyze`                                             | 汇总 vibe-logger JSONL（tool / tag / MCP 频次）                                         |
+|               | `trace`                                               | 会话级调用链回溯（按 prompt / session 过滤）                                            |
+
+> **脚注**
+>
+> - `tokens` / `biz-ui` / `templates` 共享 variant 名空间（[ADR 0014](docs/adr/0014)），与 `tokens init` 选定 variant 一致。
+> - `skills init` vs `add`：init 无 ids = 自举全部匹配 skill；add 必填 ids = 增量（[ADR 0034](docs/adr/0034)）。
+> - 源镜像模型（[ADR 0013](docs/adr/0013)）：规范副本在 `.teamix-evo/skills/`，IDE 镜像在 `.qoder/skills/` 与 `.claude/skills/`。
+
+### 动态查询（详细选项 & 实时清单）
+
+概览表只列命令名与用途。需要完整 flags / 选项时：
 
-CLI 二进制名 `teamix-evo`,所有命令都从这里发起。命令名以 `tokens`、`skills`、`ui`、`biz-ui`、`templates`、`logs` 六个 group 组织。
-
-### Tokens(`@teamix-evo/tokens`)
-
-| 目标         | 命令                                                                |
-| ------------ | ------------------------------------------------------------------- |
-| 初始化       | `npx teamix-evo tokens init <variant>`(`<variant>` 必填,无默认)     |
-| 列出可选变体 | `npx teamix-evo tokens list-variants`                               |
-| 列出已装资源 | `npx teamix-evo tokens list`                                        |
-| 升级         | `npx teamix-evo tokens update`(stub — 见 [ADR 0019](docs/adr/0019)) |
-| 卸载         | `npx teamix-evo tokens uninstall [-y] [--keep-files]`               |
-
-- **`<variant>` 必填**。`tokens init` 之前必须先确定 variant(决策树或业务名映射)。
-- `tokens update` 当前是 stub;权宜方案:删除 `.teamix-evo/tokens-lock.json` 与根 `tokens/`,重跑 `tokens init <variant>`。
-- 资源分类(frozen / regenerable / managed)详见 [ADR 0003](docs/adr/0003-update-strategy-tri-state.md):`tokens.overrides.css` 是 `frozen`,用户改写永不被覆盖;`tokens.theme.css` / `tokens/base.tokens.json` 是 `regenerable`,每次 `update` 完整重写。ADR 0020 之后,`tokens init` 不再向工程根落 `AGENTS.md` / `DESIGN.md` 等 `managed` 文件 —— 设计纲领由 `teamix-evo-design-<variant>` skill 自包含。
-
-### Skills(`@teamix-evo/skills`)
-
-| 目标     | 命令                                                 |
-| -------- | ---------------------------------------------------- |
-| 自举     | `npx teamix-evo skills init`                         |
-| 增量装   | `npx teamix-evo skills add <name...>`                |
-| 列出全部 | `npx teamix-evo skills list`(alias `ls`)             |
-| 列出已装 | `npx teamix-evo skills list --installed`             |
-| 升级     | `npx teamix-evo skills update [name...] [--dry-run]` |
-| 卸载     | `npx teamix-evo skills uninstall [-y]`               |
-| 漂移检测 | `npx teamix-evo skills doctor`                       |
-| 重新镜像 | `npx teamix-evo skills sync [name...]`               |
-
-> 升级语义见 ADR 0035 双闸:仅升级 lock 已装且 scope 匹配的 skill;version 完全一致时短路;新 skill 用 `skills add <id>` 显式加入。
-
-verb 分工(ADR 0034):
-
-- **`skills init`**(无 ids):自举 — 按当前 tokens variant + install scope 装 manifest 里全部符合条件的 skill。已装的工程再跑会返回 `already-initialized`。
-- **`skills add <name...>`**(必填 ids):增量 — 只装列出的 skill;已装的跳过(用 `update` 刷新)。不传 id 会被 commander 拒绝并输出 help。
-
-首次交互式(无既有配置且无 flag 时):
-
-1. 多选 IDE:**Qoder** / **Claude Code**(默认两者,至少一个)。等价 `--ide qoder,claude`。
-2. Scope:**project**(默认,`.qoder/.claude` 在 cwd)/ **global**(`~/.qoder/~/.claude`)。等价 `--scope project|global`。
-
-源镜像模型([ADR 0013](docs/adr/0013)):规范副本在 `.teamix-evo/skills/`,IDE 镜像在 `.qoder/skills/` 与 `.claude/skills/`。`doctor` 检测漂移,`sync` 重镜像(不升版本)。
-
-### UI 组件(`@teamix-evo/ui`)
-
-| 目标       | 命令                                   |
-| ---------- | -------------------------------------- |
-| 初始化     | `npx teamix-evo ui init [-y]`          |
-| 增加 entry | `npx teamix-evo ui add <id...>`        |
-| 列出 entry | `npx teamix-evo ui list [--installed]` |
-
-- `ui init` 写 `.teamix-evo/config.json` 的 `packages.ui`(aliases / iconLibrary / tsx / rsc)。可交互元素的 `cursor: pointer` 由组件源码内显式声明,不再有全局 `preferences.css` —— 见 [ADR 0023](docs/adr/0023-cursor-pointer-explicit-in-component-source.md)
-- `ui add` 自动解析 `registryDependencies`,组件源码写入 `src/components/ui/<id>.tsx`(frozen),并报告还需 `pnpm add` 的 npm 包。
-- 没有 `ui upgrade` 子命令 — 组件升级走 `ui add` 覆盖即可。
-
-### 业务组件(`@teamix-evo/biz-ui`)
-
-| 目标       | 命令                                                 |
-| ---------- | ---------------------------------------------------- |
-| 列出变体   | `npx teamix-evo biz-ui list-variants`                |
-| 增加 entry | `npx teamix-evo biz-ui add <id...> --variant <name>` |
-
-- `--variant <name>` 必填(没有 auto-detect)。
-- [ADR 0014](docs/adr/0014-ui-biz-ui-templates-tier.md):`tokens` / `biz-ui` / `templates` 共享 variant 名空间,与 `tokens init` 选定的 variant 一致。
-
-### 页面模板(`@teamix-evo/templates`)
-
-> ⚠️ **AI 默认不主动调用本 group**(见 [ADR 0031](docs/adr/0031-skill-templates-decoupling.md))。页面骨架由 `teamix-evo-design-<variant>` skill 的 `patterns/*.md` 驱动 ui + biz-ui 拼装;仅在用户**显式**说"用 templates 包装 frozen 骨架"时,才跳转本 group 命令。
-
-| 目标       | 命令                                                    |
-| ---------- | ------------------------------------------------------- |
-| 列出变体   | `npx teamix-evo templates list-variants`                |
-| 增加 entry | `npx teamix-evo templates add <id...> --variant <name>` |
-
-同 `biz-ui` 的变体规则。模板源码写入 `src/templates/<id>.tsx`(frozen)。
-
-### 日志(`@teamix-evo/logs`)
+```bash
+npx teamix-evo <group> --help              # group 级帮助
+npx teamix-evo <group> <verb> --help        # 子命令级帮助
+npx create-teamix-evo --help                # 脚手架帮助
+```
 
-| 目标       | 命令                                |
-| ---------- | ----------------------------------- |
-| 分析调用链 | `npx teamix-evo logs analyze [...]` |
+需要组件 / skill / token 实时清单时，优先调 MCP 工具（比 CLI 更快、可在对话中直接使用）：
 
-- 读 vibe-logger 输出 `.teamix-evo/logs/ai/**/*.jsonl`,做 AI 调用链可视化。诊断 `runTokensInit` / `runUiAdd` 等编排流程时用。
+| 查什么                   | MCP 工具                              |
+| ------------------------ | ------------------------------------- |
+| UI 组件列表 / 搜索       | `list_components` / `find_components` |
+| 组件详情（props / deps） | `get_component_meta`                  |
+| Skill 列表 / 搜索        | `skills_list` / `skills_find`         |
+| Skill 详情               | `skills_get`                          |
+| Design tokens            | `tokens_list` / `tokens_search`       |
+| ADR 决策记录             | `adr_list` / `adr_find` / `adr_get`   |
 
 ## 场景 1 · 模糊初始化
 
@@ -205,50 +184,237 @@ pnpm dev          # 立刻可跑
 pnpm typecheck    # 验证零类型错误
 ```
 
-## 场景 3 · AI coding 接入(现有仓库)
+## 场景 3 · 普通版接入（现有 npm 工程 → `teamix-evo init`）
 
-**触发**:用户已有 React/TS/Vite 仓库(已 `npm install` / 有 `package.json`),只想装 AI coding 体系。
+**触发**：用户已有 `package.json` 工程（常含 React/TS/Vite/Tailwind v4 / shadcn-style 源码），想接入 teamix-evo AI 套件而**不**重建工程。
 
-**关键判断**:
+**唯一命令**：
 
-- 跳过 scaffold(用户已有 `package.json`、`vite.config.ts`、`src/`)。
-- `npm create teamix-evo` 会拒绝非空目录(除非 `--force` 且不含 `.teamix-evo/`),所以这里改用单包 CLI。
+```bash
+npx teamix-evo init [-y] [--dry-run] [--variant <name>] [--cwd <dir>]
+```
 
-**步骤**:
+### 三分支决策树（init 自动判断）
+
+| 当前目录状态                          | init 反应                                           |
+| ------------------------------------- | --------------------------------------------------- |
+| 空目录 / 仅含 `.git` 等可忽略文件     | ⚠ 提示改用 `npm create teamix-evo@latest`（场景 2） |
+| 已有 `.teamix-evo/`                   | ⚠ 提示改用 `update` / `doctor`（场景 4）            |
+| 有 `package.json` 但无 `.teamix-evo/` | ✓ 走主路径                                          |
+
+### 主路径六步流水线
+
+| #   | 步骤      | 关键 | 行为                                                                                   |
+| --- | --------- | ---- | -------------------------------------------------------------------------------------- |
+| 1   | tokens    | ✓    | 写 `tokens/`，顺带装 design skill；旧路径单文件命中 `migrate` 策略时自动提层迁移       |
+| 2   | skills    | ✓    | 项目级装 `teamix-evo-code-<variant>`（manage 全局装一次，design 由 1 顺带 — ADR 0033） |
+| 3   | agents-md | –    | 生成根 `AGENTS.md`，managed-region 可重生（ADR 0038）                                  |
+| 4   | ui-init   | ✓    | 写 `components.json` + `packages.ui` 配置                                              |
+| 5   | ui-add    | –    | 装基线 13 个组件（`uiSelection='all'` 则装全集）                                       |
+| 6   | lint      | –    | `runLintInit`（ESLint + Stylelint）                                                    |
+
+> 关键步骤失败 → 后续关键步骤短路成 `skip(aborted)`；非关键步骤失败不阻断整体。
+
+### 6 类冲突（wizard 逐项询问策略）
+
+| 冲突键            | 已实现策略                                        |
+| ----------------- | ------------------------------------------------- |
+| `tokens`          | `migrate` / `overwrite` / `skip`                  |
+| `agents-md`       | `merge-managed` / `overwrite` / `skip`            |
+| `components-json` | `overwrite` / `skip`                              |
+| `shadcn-source`   | `overwrite` / `skip-existing` / `skip`            |
+| `tailwind-config` | 仅 `skip`（其它策略待批次 4 managed-region 引擎） |
+| `index-css`       | 仅 `skip`（其它策略待批次 4 managed-region 引擎） |
+
+> wizard 给每项一个推荐策略；`-y` 全走推荐默认值；`--dry-run` 只打印计划不写文件。
+
+#### tokens `migrate` 策略（W1.4 提层兼容）
+
+当工程里检测到旧版单文件 token（`src/design-tokens.css` / `src/styles/design-tokens.css` / `src/styles/tokens.css`）时，wizard 默认推荐 `migrate`：
+
+- 读取每个旧文件内容，按时间戳 banner append 到根 `tokens/tokens.overrides.css`（不存在则用空模板创建）；
+- 备份旧文件到 `.teamix-evo/.backups/<rel>.<ts>.bak`（与 snapshot/restore 同根，src/\*\* 不被污染）；
+- 删除旧文件。空文件 / 不存在的路径会进 `skipped` 列表，**不删原文件**。
+
+落地输出会写明 `migrated N file(s) → tokens/tokens.overrides.css`。`migrate` 失败仅记录在 step detail，不影响 tokens 主步骤的成功语义。
+
+### Partial（部分完成）状态恢复
+
+CLI 在 partial 状态会打印“恢复指引”面板：失败步骤名、错误信息、已完成步骤、建议命令。**修好原因后直接重跑 `teamix-evo init`** —— 每个 sub-step 幂等，已落地的会 `already-initialized` 短路，从断点处续接。
+
+### 结束时告诉用户
+
+- 已落地的 step 列表 + variant / IDE / scope。
+- `pendingConflictWork`（如有）：批次 4 上线后用 `teamix-evo conflict resolve` 收尾。
+- 全局 entry skill：若 `~/.qoder/skills/teamix-evo-manage` 不存在，补一句 `npx teamix-evo skills add teamix-evo-manage --scope global`（ADR 0033）。
+
+## 场景 4 · 升级
+
+> **概念区分**："升级 teamix-evo"= 升级**整个 AI 套件**（所有已装包）；"升级 manage skill / 升级某个 skill"= 只升级指定的 skill。根据用户表述判断走哪条路径。
+
+### 4a · 套件级升级（"升级 teamix-evo / update teamix-evo"）
+
+**触发**:用户说"升级 teamix-evo / 看看哪些要升级 / update teamix-evo / 升级套件 / refresh installed teamix-evo packages"。
+
+**一行命令**:
 
 ```bash
-# 1. 确定 variant(若用户未说,按映射表 / 询问)
-npx teamix-evo tokens list-variants
-npx teamix-evo tokens init <variant>          # 装 tokens(写 tokens/ 与 .teamix-evo/tokens-lock.json)
+npx teamix-evo@latest update            # 实际执行 tokens → skills 升级
+npx teamix-evo@latest update --dry-run   # 只看升级计划,不写任何文件
+```
 
-# 2. 自举 skills(同源 Qoder + Claude;manage 是 global-only,自举自动跳过 — ADR 0033 + 0034)
-npx teamix-evo skills init                    # 项目级装 design-<variant> + code-<variant>,默认两个 IDE 镜像
+**orchestrator 两步管线**（ADR 0003 三态 + ADR 0035 短路）:
 
-# 3. 装 ui 配置
-npx teamix-evo ui init -y
-npx teamix-evo ui add button                  # 可选:先装一个真组件验证
+| 步骤 | 包     | 语义                             | 失败后果                           |
+| ---- | ------ | -------------------------------- | ---------------------------------- |
+| 1    | tokens | regenerable 覆盖 + frozen 保留   | **关键步骤**：失败时中止后续       |
+| 2    | skills | lock ∩ scope ∩ version-diff 短路 | 非关键：记录失败但不中止已完成步骤 |
+
+> ui / biz-ui / templates 是 frozen（ADR 0019）— 不参与 bulk update。如用户想覆盖单个组件,引导用 `ui add <id> --overwrite`。
+
+**AI 引导决策树**:
+
+1. **先推荐 dry-run**：执行 `npx teamix-evo@latest update --dry-run`。
+2. 根据输出告知用户：
+   - `dry-run` 步骤全 `·` up-to-date → 「已是最新版本，无需升级」。
+   - 有版本 bump 计划 → 确认后去掉 `--dry-run` 执行。
+3. 执行后根据 CLI 输出的 STEP_ICON 反馈：
+   - 全 `✔` → 告知升级完成 + 版本变化。
+   - 含 `✖`（partial）→ CLI 已打印「恢复指引」面板，复述给用户：
+     - 哪个步骤失败 + 错误信息
+     - 建议修复后重跑 `teamix-evo update`（每步幂等，version-diff 短路自动跳过已完成步骤）
+   - 全 `⊘` skip → 告知相应包未安装,如需添加走场景 3。
+
+**不要**给未安装的包做 install — 那是场景 2/3 的事。
+**不要**手动拼 `tokens update` + `skills update` — 统一用 `teamix-evo update`。
+
+#### Token rename 收尾（可选，仅当 CLI 输出 `💡 token rename hint:` 时）
+
+`tokens update` / `switch --apply` 跳过了 rename 节点时，CLI 会在 `.teamix-evo/.upgrade-hints/tokens-<ts>.json` 写一份改名索引。这是**被动提示** — CLI 永远不会自动改写 `src/**`（frozen 边界，ADR 0019 §D4）。
+
+要项：
+
+- 告诉用户 hint 文件路径；
+- 引导用户调 [`teamix-evo-upgrade`](../teamix-evo-upgrade/SKILL.md) skill 处理 codemod（扫描 `src/**` + `tokens/tokens.overrides.css`，逐文件 diff 征同意后才修改）；
+- 未检测到 hint 时则安静跳过，不要装作有 codemod 要跑。
+
+### 4b · 单 skill 升级（"升级 manage skill / 升级 design skill"）
+
+**触发**:用户明确指定要升级某个 skill(如"升级 teamix-evo-manage / 更新 design skill / update manage skill")。
+
+**命令**:
+
+```bash
+npx teamix-evo@latest skills update <skill-id>           # 指定 skill
+npx teamix-evo@latest skills update <skill-id> --dry-run  # 先预览
 ```
 
-**结束时告诉用户**:
+### 4c · variant 切换（`teamix-evo switch` — ADR 0019 task #7）
 
-- 已装的 skill 列表(从 `skills list --installed`)、tokens variant、ui aliases。
-- 接下来怎么用:写新页面就触发 `teamix-evo-design-opentrek` / `teamix-evo-code-opentrek`。
-- 若全局尚未安装 entry skill,补一句:`npx teamix-evo skills add teamix-evo-manage --scope global`(ADR 0033)。
+**触发**：用户表达“切到 uni-manager / 切到云管 / 换个 variant / switch 到 opentrek / 迁到探索者体系 / variant migration”。
 
-## 场景 4 · 更新检测
+**一行命令**：
 
-**触发**:用户说"升级 / 看看哪些要升级 / update teamix-evo"。
+```bash
+npx teamix-evo@latest switch <new-variant>            # 默认 dry-run，只打印变更计划
+npx teamix-evo@latest switch <new-variant> --apply    # 二次确认后真写
+npx teamix-evo@latest switch <new-variant> --apply -y # 跳二次确认（destructive，谨慎）
+```
 
-**步骤**:
+**语义**（复用 strategy dispatch 模型）：
 
-1. 读 `.teamix-evo/config.json` 的 `packages` 字段,看哪些已装(tokens / skills / ui / biz-ui / templates)。
-2. 对每个已装包,跑对应 `list --installed`(若有该子命令)与上游 manifest 比对版本。
-3. 仅对**已装**的包做 update:
-   - `npx teamix-evo tokens update`(stub — 仍提示用户清 + 重装)
-   - `npx teamix-evo skills update [name...] [--dry-run]` — 双闸 + version 短路 + 可选限定 id(ADR 0035)。先 `--dry-run` 给用户看清单,确认后再无 flag 跑一遍真升级
-   - 没有 `ui update`(组件升级走 `ui add` 覆盖即可)
+| 变更类型         | 图标 | 资源处理                                                                                |
+| ---------------- | ---- | --------------------------------------------------------------------------------------- |
+| `rewrite`        | ✎    | regenerable 资源（tokens 主体 / brand css）— 被新 variant 覆写                          |
+| `managed-update` | ⊕    | managed 区段（AGENTS.md / 部分 config）— 仅重生 managed 区段，区段外保留                |
+| `preserve`       | ⊘    | frozen 资源（`tokens.overrides.css` / src/\*\* / biz-ui / templates）— 不动，需手动迁移 |
+| `unchanged`      | =    | 文件本就与新 variant 一致 — 跳过                                                        |
 
-**不要**给未安装的包做 install — 那是场景 2/3 的事。
+**AI 引导决策树**：
+
+1. **先跑 dry-run**（默认就是 dry-run，允许不加任何 flag）。全量变更计划会以表格 + per-file diff 列出。
+2. **说明清楚 `preserve` 变量**：告诉用户 frozen 文件不会被 `--apply` 覆写，它们只会被 “token rename hint + `teamix-evo-upgrade` skill codemod” 迁过去。
+3. 用户确认后，跑 `--apply`（默认带二次确认；non-TTY 环境 / AI agent 调用需加 `-y`）。
+4. 成功后：
+   - CLI 输出 `priorVariant: <old>` / `variant: <new>`，`config.json` 已记录备查；
+   - 若 CLI 输出 `💡 token rename hint:` — 引导用户走 [`teamix-evo-upgrade`](../teamix-evo-upgrade/SKILL.md) skill 扫 `src/**` 与 `tokens.overrides.css`。
+5. 失败：switch 执行前会自动 `reason="switch"` snapshot，`partial` 状态可走场景 4d `restore`。
+
+**不要**：
+
+- 不要跳过 dry-run 直接 `--apply`，除非用户明确告诉你“已看过变更列表”。
+- 不要为了“保留用户业务代码”去手动改 `src/**`：frozen 资源完全交给 codemod skill，CLI 仓抱不越界。
+- 不要把 `switch` 当作“调个 token 样式”的快捷手段 — 它是跨 variant 迁移，仅在业务名变更 / 双 variant 互迁时使用。
+
+### 4d · 失败回滚（`teamix-evo restore` — ADR 0019 §2）
+
+**触发**:`init` / `update` 出现 `partial` 状态后用户希望**完全回退**到执行前的 `.teamix-evo/` 状态(而不是修原因后续跑)。
+
+**两步**:
+
+```bash
+npx teamix-evo restore --list           # 列出可用 snapshot(最新在前)
+npx teamix-evo restore <ts>             # 回滚到指定 snapshot(默认带二次确认,-y 跳过)
+```
+
+snapshot 由 `init` / `update` / `variant switch` 在执行前**自动**生成,默认保留最近 5 个;reason 字段标识来源(`init` / `update` / `switch` / `restore` / `manual`)。
+
+**关键性质 — restore 自身可逆**:`restore <ts>` 在覆盖前会再做一次 `reason="restore"` 的安全 snapshot,所以即便回滚错版本也可以再 `restore --list` 找回前一个状态。
+
+**AI 引导**:
+
+- 优先推荐 `修因 + 重跑 init/update`(`partial` 状态恢复的常规路径) — 每步幂等,version-diff 短路。
+- 仅当用户明确表达"恢复到执行前 / 撤销这次升级 / 全部退回"时才走 `restore`。
+- 回滚后告知用户:已执行 `restore <ts>`,本次操作前的状态已存为新 `reason=restore` snapshot 备查。
+
+### 4e · 组件源码升级（`teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` — [ADR 0040](docs/adr/0040)）
+
+**触发**：用户表达“升级 ui / 升级业务组件 / 升级 button / 看看哪些组件有新版 / upgrade ui / upgrade biz-ui / stage ui upgrade”等关键词。
+
+> 这里是**版本演进**（installed 资源 → 上游新版 → staging → 逐个 apply），与场景 6 “placeholder→real 首次填充”是两条路：场景 6 是初体验起点（`pending-ui.json`），这里是安装完成后跟随上游发布。
+
+**一行命令**：
+
+```bash
+npx teamix-evo ui upgrade                  # 全量 staging。仅在 `teamix-evo` / `mixed` lineage 产出
+npx teamix-evo ui upgrade button input     # 只 stage 指定组件
+npx teamix-evo biz-ui upgrade              # 变体感知的 biz-ui staging
+npx teamix-evo biz-ui upgrade --apply      # 错误：CLI 不写 src，guidance 走 teamix-evo-upgrade skill
+```
+
+运行 `teamix-evo update` 时，orchestrator 中也会自动跳过一次 `ui:planned` / `biz-ui:planned`，产出同样的 staging 目录。
+
+**lineage 分三档**（CLI 只在前两者上产出 staging）：
+
+| lineage         | CLI 会产出 staging？ | AI 开场白                                                                  |
+| --------------- | -------------------- | -------------------------------------------------------------------------- |
+| `teamix-evo`    | 是                   | 走 staging → teamix-evo-upgrade skill 逐件 review                          |
+| `mixed`         | 是                   | 升级项优先，末了与用户商量 foreign 组件（未登记）去留                      |
+| `shadcn-native` | 否                   | 告诉用户他是 shadcn 原生，建议先 `teamix-evo ui init` 对齐谱系（手动迁移） |
+| `custom-only`   | 否                   | 跳过。告诉用户“现有组件不在 manifest 中，升级只针对 teamix-evo 安装资产”   |
+
+**AI 引导决策树**：
+
+1. **先识别 lineage**：`teamix-evo update` 的 step detail / `ui upgrade` 的输出都会带 `lineage=...`。根据表选开场白。
+2. **路径 A（`teamix-evo` / `mixed`）**：
+   - CLI 生成 staging 后会输出 `staging at .teamix-evo/.upgrade-staging/<dir>` + risk 汇总。复述给用户。
+   - **应用 staging 交给 [`teamix-evo-upgrade`](../teamix-evo-upgrade/SKILL.md) skill** — 它会逐个展示 diff，按 risk 分批让用户确认后才复制 incoming.tsx 到 src（逐文件 hard gate）。
+   - **不要手工复制！**`incoming.tsx` 已是 alias 重写过的、可直接覆盖。但走 skill 能带 archive 动作 + risk-aware UX。
+3. **路径 B（`shadcn-native`）**：告知用户 “CLI 不会为 shadcn 原生仓生成 staging”，提示他走 `teamix-evo ui init` 对齐谱系（参考 ADR 0040 §D1）后再升级。
+4. **路径 C（用户误走 `--apply`）**：CLI 会拒绝 + 打印 “请走 teamix-evo-upgrade skill”。重复该提示，引导走路径 A。
+5. **路径 D（foreign 组件）**：staging 中的 `riskLevel: foreign` 是未登记文件（`mixed` lineage）— 不要表达为“要升级”；作为联动信息告诉用户，让他决定是否 `teamix-evo ui add <id>` 收纳、删掉、或保留。
+
+**身份划分清单**：
+
+- **CLI**：检测 lineage / 生成 staging / 算 risk 。**从不写 `src/components/{ui,business}`**。
+- **AI （本 skill）**：识别意图、跳起 CLI 命令、复述结果、在路径 A 上交接给 `teamix-evo-upgrade` skill。
+- **`teamix-evo-upgrade` skill**：读 staging 、逐文件 diff 征同意、apply、archive。
+
+**不要**：
+
+- 不要自己在本 skill 里复制 staging 文件到 `src` — 那是 `teamix-evo-upgrade` skill 的职责。
+- 不要听到“升级 ui”就打 `ui add` — `add` 是装进去，`upgrade` 是已装后追上上游。
+- 不要在 `shadcn-native` lineage 强行跳 staging；CLI 跳过是预期行为。
 
 ## 场景 5 · 卸载
 
@@ -274,13 +440,14 @@ npx teamix-evo ui add button                  # 可选:先装一个真组件验
 
 ## 常见错误与恢复路径(P8 — failures must be observable)
 
-| 症状                                               | 原因                                        | 恢复路径                                           |
-| -------------------------------------------------- | ------------------------------------------- | -------------------------------------------------- |
-| `Unknown tokens variant "..."`                     | 拼写错误或上游未发布该 variant              | `npx teamix-evo tokens list-variants` 列出当前可用 |
-| `Target directory already contains a .teamix-evo/` | 误用 `npm create teamix-evo` 进已装目录     | 改走场景 4(更新)或场景 3(增量装)                   |
-| `UI not initialized`(跑 `ui add` 时)               | 未先跑 `ui init`                            | `npx teamix-evo ui init -y` 然后再 `ui add`        |
-| Vite/Tailwind 跑起来没样式                         | `src/index.css` 缺少 tokens / Tailwind 导入 | 检查 `src/index.css` 的 `@import` 顺序             |
-| Skills 在 IDE 不触发                               | `.qoder/skills/` 或 `.claude/skills/` 漂移  | `npx teamix-evo skills doctor` 然后 `skills sync`  |
+| 症状                                               | 原因                                        | 恢复路径                                                                                               |
+| -------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `Unknown tokens variant "..."`                     | 拼写错误或上游未发布该 variant              | `npx teamix-evo tokens list-variants` 列出当前可用                                                     |
+| `Target directory already contains a .teamix-evo/` | 误用 `npm create teamix-evo` 进已装目录     | 改走场景 4(更新)或场景 3(增量装)                                                                       |
+| `UI not initialized`(跑 `ui add` 时)               | 未先跑 `ui init`                            | `npx teamix-evo ui init -y` 然后再 `ui add`                                                            |
+| Vite/Tailwind 跑起来没样式                         | `src/index.css` 缺少 tokens / Tailwind 导入 | 检查 `src/index.css` 的 `@import` 顺序                                                                 |
+| Skills 在 IDE 不触发                               | `.qoder/skills/` 或 `.claude/skills/` 漂移  | `npx teamix-evo skills doctor` 然后 `skills sync`                                                      |
+| 想完全回退 `init` / `update` 这次执行              | partial / 升级后想撤销到执行前状态          | `teamix-evo restore --list` 看可用 snapshot,然后 `teamix-evo restore <ts>`(回滚自身可逆 — ADR 0019 §2) |
 
 <!-- teamix-evo:managed:end id="core" -->