npm - @teamix-evo/skills - Versions diffs - 0.6.0 → 0.7.0 - Mend

@teamix-evo/skills 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/manifest.json +23 -37
package/package.json +2 -2
package/src/teamix-evo-manage/SKILL.md +288 -121
package/src/teamix-evo-upgrade/SKILL.md +298 -0

package/manifest.json CHANGED Viewed

@@ -2,7 +2,7 @@
   "$schema": "https://teamix-evo.dev/schema/skills-package/v1.json",
   "schemaVersion": 1,
   "package": "skills",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "engines": {
     "teamix-evo": ">=0.1.0"
   },
@@ -10,17 +10,12 @@
     {
       "id": "teamix-evo-manage",
       "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`.\nTRIGGER 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`.\nSKIP: 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`.\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, 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`.\nTRIGGER 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`.\nSKIP: 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`.\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.2.0",
       "source": "src/teamix-evo-manage",
-      "ides": [
-        "qoder",
-        "claude"
-      ],
+      "ides": ["qoder", "claude"],
       "updateStrategy": "managed",
-      "managedRegions": [
-        "core"
-      ],
+      "managedRegions": ["core"],
       "template": false,
       "scope": "global"
     },
@@ -31,14 +26,9 @@
       "version": "0.2.0",
       "source": "src/teamix-evo-design-opentrek",
       "variant": "opentrek",
-      "ides": [
-        "qoder",
-        "claude"
-      ],
+      "ides": ["qoder", "claude"],
       "updateStrategy": "managed",
-      "managedRegions": [
-        "core"
-      ],
+      "managedRegions": ["core"],
       "template": false
     },
     {
@@ -48,14 +38,9 @@
       "version": "0.2.0",
       "source": "src/teamix-evo-code-opentrek",
       "variant": "opentrek",
-      "ides": [
-        "qoder",
-        "claude"
-      ],
+      "ides": ["qoder", "claude"],
       "updateStrategy": "managed",
-      "managedRegions": [
-        "core"
-      ],
+      "managedRegions": ["core"],
       "template": false
     },
     {
@@ -65,14 +50,9 @@
       "version": "0.2.0",
       "source": "src/teamix-evo-design-uni-manager",
       "variant": "uni-manager",
-      "ides": [
-        "qoder",
-        "claude"
-      ],
+      "ides": ["qoder", "claude"],
       "updateStrategy": "managed",
-      "managedRegions": [
-        "core"
-      ],
+      "managedRegions": ["core"],
       "template": false
     },
     {
@@ -82,14 +62,20 @@
       "version": "0.2.0",
       "source": "src/teamix-evo-code-uni-manager",
       "variant": "uni-manager",
-      "ides": [
-        "qoder",
-        "claude"
-      ],
+      "ides": ["qoder", "claude"],
       "updateStrategy": "managed",
-      "managedRegions": [
-        "core"
-      ],
+      "managedRegions": ["core"],
+      "template": false
+    },
+    {
+      "id": "teamix-evo-upgrade",
+      "name": "teamix-evo-upgrade",
+      "description": "Help the user adopt token renames in `.teamix-evo/.upgrade-hints/tokens-<ts>.json` AND component source upgrades in `.teamix-evo/.upgrade-staging/{ui,biz-ui}-<ts>/` after `teamix-evo update` / `teamix-evo tokens update` / `teamix-evo switch` / `teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade`. Read each hint or staging manifest, scan the project for usages or compare current vs incoming source, propose codemod / file-replace diffs, apply only after explicit user approval, then archive processed inputs.\nTRIGGER when: user references `.teamix-evo/.upgrade-hints/`、`.teamix-evo/.upgrade-staging/`、`tokens-*.json` hint files、`ui-*` or `biz-ui-*` staging directories、phrases like \"处理 token 改名\"、\"应用 codemod\"、\"扫一下 legacy token\"、\"升级 token 引用\"、\"更新 token 名\"、\"组件升级\"、\"ui-staging\"、\"biz-ui staging\"、\"apply ui staging\"、\"apply biz-ui staging\"、\"应用组件升级\"、\"apply token rename codemod\"、\"adopt token rename hints\"、\"scan for legacy tokens\"、\"token rename upgrade\"、\"component source upgrade\"、\"review ui staging diff\"; AI sees output of `teamix-evo update` / `teamix-evo tokens update` / `teamix-evo switch --apply` / `teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` mentioning `💡 token rename hint:` or `staging at .teamix-evo/.upgrade-staging/...` and the user wants to follow up; user opens any `.teamix-evo/.upgrade-hints/tokens-*.json` or any file under `.teamix-evo/.upgrade-staging/{ui,biz-ui}-*/`.\nSKIP: any other lifecycle work — `init` / `update` orchestration / variant switch itself / install / uninstall / generating staging (defer to teamix-evo-manage); pure visual or design changes (defer to teamix-evo-design-<variant>); any code authoring unrelated to the rename / staging window (defer to teamix-evo-code-<variant>); refuse to auto-apply — never write source code without explicit per-file user confirmation.\nCoordinates with: teamix-evo-manage (manage drives the upgrade flow that emits hints + staging; this skill consumes the resulting files).",
+      "version": "0.1.0",
+      "source": "src/teamix-evo-upgrade",
+      "ides": ["qoder", "claude"],
+      "updateStrategy": "managed",
+      "managedRegions": ["core"],
       "template": false
     }
   ]

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@teamix-evo/skills",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Skills (AI IDE capabilities) for Teamix Evo",
   "type": "module",
   "files": [
@@ -12,7 +12,7 @@
   "devDependencies": {
     "@clack/prompts": "^0.8.0",
     "tsx": "^4.0.0",
-    "@teamix-evo/registry": "0.7.0"
+    "@teamix-evo/registry": "0.8.0"
   },
   "publishConfig": {
     "access": "public",

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

@@ -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" -->

package/src/teamix-evo-upgrade/SKILL.md ADDED Viewed

@@ -0,0 +1,298 @@
+---
+name: teamix-evo-upgrade
+description: |
+  Help the user adopt token renames in `.teamix-evo/.upgrade-hints/tokens-<ts>.json` AND component source upgrades in `.teamix-evo/.upgrade-staging/{ui,biz-ui}-<ts>/` after `teamix-evo update` / `teamix-evo tokens update` / `teamix-evo switch` / `teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade`. Read each hint or staging manifest, scan the project for usages or compare current vs incoming source, propose codemod / file-replace diffs, apply only after explicit user approval, then archive processed inputs.
+  TRIGGER when: user references `.teamix-evo/.upgrade-hints/`、`.teamix-evo/.upgrade-staging/`、`tokens-*.json` hint files、`ui-*` or `biz-ui-*` staging directories、phrases like "处理 token 改名"、"应用 codemod"、"扫一下 legacy token"、"升级 token 引用"、"更新 token 名"、"组件升级"、"ui-staging"、"biz-ui staging"、"apply ui staging"、"apply biz-ui staging"、"应用组件升级"、"apply token rename codemod"、"adopt token rename hints"、"scan for legacy tokens"、"token rename upgrade"、"component source upgrade"、"review ui staging diff"; AI sees output of `teamix-evo update` / `teamix-evo tokens update` / `teamix-evo switch --apply` / `teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` mentioning `💡 token rename hint:` or `staging at .teamix-evo/.upgrade-staging/...` and the user wants to follow up; user opens any `.teamix-evo/.upgrade-hints/tokens-*.json` or any file under `.teamix-evo/.upgrade-staging/{ui,biz-ui}-*/`.
+  SKIP: any other lifecycle work — `init` / `update` orchestration / variant switch itself / install / uninstall / generating staging (defer to teamix-evo-manage); pure visual or design changes (defer to teamix-evo-design-<variant>); any code authoring unrelated to the rename / staging window (defer to teamix-evo-code-<variant>); refuse to auto-apply — never write source code without explicit per-file user confirmation.
+  Coordinates with: teamix-evo-manage (manage drives the upgrade flow that emits hints + staging; this skill consumes the resulting files).
+---
+# teamix-evo-upgrade
+This skill consumes two complementary upgrade artefacts the CLI produces during upgrades and the consumer must adopt by hand under the [ADR 0019](../../../../docs/adr/0019-project-upgrade-flow.md) **frozen-on-add boundary** (after first-time install via `npm create teamix-evo` / `teamix-evo init` / `ui add`, the CLI never overwrites existing files under `src/components/{ui,business}/**`; upgrades go through staging instead of in-place rewrites):
+1. **Token rename hints** — `.teamix-evo/.upgrade-hints/tokens-<ts>.json` (variable-level rewrites under `src/**` + `tokens/tokens.overrides.css`).
+2. **Component source staging** — `.teamix-evo/.upgrade-staging/{ui,biz-ui}-<ts>/` (per-component file replacements under `src/components/{ui,business}/**`, see [ADR 0040](../../../../docs/adr/0040-component-source-layer-upgrade-flow.md)).
+Both flows share the same shape (discover → read → propose → hard-gate confirm → archive); they only differ in the artefact they consume. Token-rename details are in part A, component-source details are in part B.
+# Part A — Token rename adoption
+## What is a hint file
+When `teamix-evo tokens update` bumps a variant version that ships a `renames` log, or `teamix-evo switch --apply` lands on a new variant whose history contains renames, the CLI writes a single JSON file:
+```
+.teamix-evo/
+└── .upgrade-hints/
+    └── tokens-2026-06-12T03-15-00-000Z.json
+```
+Schema v1 payload (every field is required except `description` per rename):
+```json
+{
+  "schemaVersion": 1,
+  "ts": "2026-06-12T03:15:00.000Z",
+  "package": "tokens",
+  "trigger": "update",
+  "fromVariant": "opentrek",
+  "toVariant": "opentrek",
+  "fromVersion": "0.5.0",
+  "toVersion": "0.6.5",
+  "renames": [
+    {
+      "sinceVersion": "0.6.0",
+      "from": "--color-old",
+      "to": "--color-new"
+    },
+    {
+      "sinceVersion": "0.6.5",
+      "from": "--space-x",
+      "to": "--space-h",
+      "description": "horizontal axis rename"
+    }
+  ]
+}
+```
+> `trigger` is `"update"` for version-bump hints and `"switch"` for variant-switch hints. Both consume the same way — only the framing line differs.
+## Workflow (5 steps, never skip step 4)
+### 1 · Discover
+List every hint file under `.teamix-evo/.upgrade-hints/`. Sort newest-first by filename (the `tokens-<fs-ts>.json` ts is filesystem-safe and lexically chronological).
+```bash
+ls -1 .teamix-evo/.upgrade-hints/tokens-*.json 2>/dev/null
+```
+If the directory is missing or empty, tell the user:
+> 当前没有待处理的 token rename hint。这通常意味着最近一次 `tokens update` / `switch` 没有跨过 rename 节点；你可以继续做你原本的事。
+### 2 · Aggregate
+Read each hint and aggregate the `renames` arrays into a single `from → to` map. When two hints rename the same token (rare — usually means a token was renamed twice across versions), the **newest hint wins** and the older mapping is discarded (treat the chain as resolved).
+Surface a one-line summary per hint to the user:
+> `tokens-…06-12T03-15-00-000Z.json` · update · opentrek 0.5.0 → 0.6.5 · 2 renames
+### 3 · Scan
+For each `from` token, run a project-wide search across the consumer-owned surface (never read `node_modules/` or `dist/`). The exact glob set depends on which token shape the rename targets:
+| `from` shape                                  | Where to search                                                            | Tooling          |
+| --------------------------------------------- | -------------------------------------------------------------------------- | ---------------- |
+| CSS variable (`--color-old`)                  | `src/**/*.{ts,tsx,js,jsx,css,scss,md,mdx}` + `tokens/tokens.overrides.css` | grep / Grep tool |
+| Tailwind class fragment (e.g. `bg-color-old`) | `src/**/*.{ts,tsx,jsx}` + `index.html`                                     | grep             |
+| Token JSON path (`color.old`)                 | `tokens/**/*.json` if any                                                  | grep             |
+Explicitly exclude:
+- `node_modules/**`、`dist/**`、`build/**`、`.next/**`
+- Anything under `.teamix-evo/snapshots/**` (those are restore points, not live code)
+- The hint file itself
+For each occurrence collect: file path, 1-based line number, the matched line.
+### 4 · Propose & ask (HARD GATE)
+For every `from → to` rename, show a diff hunk and **ask the user per file** before touching it. Use this template:
+```
+─── tokens/tokens.overrides.css (1 occurrence) ───
+- 12 |   color: var(--color-old);
++ 12 |   color: var(--color-new);
+─── src/components/Banner.tsx (3 occurrences) ───
+- 18 |   className="text-[var(--color-old)]"
++ 18 |   className="text-[var(--color-new)]"
+…
+应用这些修改？(y / n / per-file)
+```
+`per-file` lets the user pick file-by-file. Default to **no** if the user is silent. **Never auto-apply.** This is the entire reason the rename pipeline exists — ADR 0019 frozen boundary.
+If the user declines a particular file, record it in your reply (`保留：src/legacy/old-page.tsx — 用户选择不替换`) so they can come back to it later.
+### 5 · Archive processed hints
+After (and only after) the user has either accepted or explicitly skipped every rename in a hint file, **move the hint into the archive subdirectory** so subsequent runs don't re-prompt:
+```bash
+mkdir -p .teamix-evo/.upgrade-hints/.processed
+mv .teamix-evo/.upgrade-hints/tokens-<ts>.json .teamix-evo/.upgrade-hints/.processed/
+```
+Tell the user the file moved and that they can `git diff` to review the rewrites + the hint move in one shot.
+> If the user wants to **defer** an entire hint (not just per-file skip), leave it in place and tell them they can re-run this skill later.
+## Edge cases
+| Situation                                                       | Response                                                                                                                  |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Hint file fails JSON parse / wrong schemaVersion                | Print the file path + the parse error; **do not** delete it. Suggest the user inspect or run `teamix-evo restore --list`. |
+| `from` token literally not found in `src/**`                    | Tell the user the rename is "已经无影响" and ask whether to archive the hint anyway.                                      |
+| Multiple hint files pending                                     | Process newest-first one hint at a time — never batch across hints (keeps the diff small and the user in control).        |
+| User says "全部接受" / "apply all"                              | Still show every diff before applying. Bulk-confirm is fine, **silent apply is not**.                                     |
+| Project has no `src/` (library / monorepo root)                 | Ask the user which directory to scan; default to `packages/*/src` if a `pnpm-workspace.yaml` is present.                  |
+| User asks to handle an old hint that's already in `.processed/` | Read it from `.processed/`, re-run scan, and let the user decide whether to apply again or remove it permanently.         |
+## What this skill is NOT
+- **Not** a CLI command — there is no `teamix-evo upgrade`. The CLI emits hints + staging; this skill consumes them.
+- **Not** a token authority — only consumes the rename log declared by the upstream tokens pack (registry `TokensVariantEntry.renames`).
+- **Not** a refactor robot — diff-then-confirm is mandatory, the user owns every byte under `src/**`.
+- **Not** the place to discuss new token names or design decisions — those flow through the design skill.
+# Part B — Component source upgrade
+When `teamix-evo update` (auto-staging step), `teamix-evo ui upgrade [id]`, or `teamix-evo biz-ui upgrade [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, [ADR 0019](../../../../docs/adr/0019-project-upgrade-flow.md) + [ADR 0040](../../../../docs/adr/0040-component-source-layer-upgrade-flow.md). This skill 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` values (from [ADR 0040 §D3](../../../../docs/adr/0040-component-source-layer-upgrade-flow.md)):
+| level               | meaning                                                              | suggested handling                  |
+| ------------------- | -------------------------------------------------------------------- | ----------------------------------- |
+| `unchanged`         | hash identical — nothing to do                                       | skip silently                       |
+| `upgradable-low`    | single file, no new/removed exports or cva variants                  | batch confirm                       |
+| `upgradable-medium` | new exports / new cva variants / multi-file                          | per-file confirm                    |
+| `risky`             | removed exports / removed cva variants / props rename                | discuss each, surface hints         |
+| `breaking`          | upstream removed the entry entirely                                  | flag explicitly, never auto-replace |
+| `foreign`           | file exists in `src/` but no upstream / no installed manifest record | leave untouched, ask for intent     |
+## Workflow (5 steps, never skip step 4)
+### 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 update` / `teamix-evo ui upgrade [id]` / `teamix-evo biz-ui upgrade [id]` 生成。
+### B2 · Read manifest & frame the opening line
+Parse `meta.json`. Pick the opening message based on `lineage`:
+| lineage         | opening line template                                                                                                                                                                                                             |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `teamix-evo`    | `检测到 X 个组件，其中 Y 个有变化（unchanged=A, upgradable-low=B, medium=C, risky=D, breaking=E）。准备逐个 review。`                                                                                                             |
+| `mixed`         | `检测到 Z 个 teamix-evo 组件 + W 个未登记组件（foreign=F）。先处理可升级项，最后与你商量 foreign 组件去留。`                                                                                                                      |
+| `shadcn-native` | `你当前是 shadcn 原生安装（未使用 teamix-evo 的资产）。升级前建议先迁移到 teamix-evo 谱系（run 「teamix-evo ui init」重新安装），或者手动对齐调谐表。是否继续详细对比？` (CLI 这种情况不会生成 staging，但用户可能手工走到这一步) |
+| `custom-only`   | (CLI skip 了，不会出现在 staging 中 — 若出现是异常，请提示用户检查)                                                                                                                                                               |
+### B3 · Group by risk
+Iterate `entries` and bucket by `riskLevel`:
+- **`unchanged`** — just announce “以下组件未变，跳过” (list ids on one line).
+- **`upgradable-low`** — group all together, **one** confirmation prompt (“这些升级较安全，是否一起应用？”).
+- **`upgradable-medium`** — walk one-by-one with a short hint summary, ask y/n/per-file (see B4).
+- **`risky`** — force per-component review; spell out every `hints[]` entry verbatim before showing the diff.
+- **`breaking`** — do **not** offer auto-replace. Tell the user upstream removed the entry, ask if they want to delete the local file or keep it as a custom component (likely a re-naming — cross-check `removedExports`).
+- **`foreign`** — list separately (“以下组件不在 manifest 中，可能是你手工添加的”), ask whether to register, delete, or leave alone.
+### B4 · Propose & ask (HARD GATE)
+For each non-unchanged entry the user has agreed to consider, render the diff with **the same template as Part A step 4** but use file replacement instead of inline rewrite. Read `current.tsx` + `incoming.tsx` and compute the diff on the fly (v1 does not pre-render `diff.unified.patch` — if the entry's `diff.diffRelPath` is set in a future schema version, prefer that file as the source of truth).
+```
+─── src/components/ui/button.tsx · risk=upgradable-medium · hints: new export: ButtonGroup ───
+@@ -1,3 +1,5 @@
+ export const Button = (props: any) => null;
++
++export const ButtonGroup = (props: any) => null;
+应用？(y / n / per-file)
+```
+Application = **copy `incoming.tsx` over the file at `current.target`**, atomically. Do not partial-merge — the staging is whole-file.
+**Never auto-apply.** If the user is silent, default to no. If the user says “全部接受” / “apply all”, still show every diff (one screen each) before writing.
+If a file's `riskLevel` is `breaking` and the user opts to delete the file, do that explicitly with a confirmed `rm` command — not silently.
+### B5 · Archive staging
+After every entry has either been applied or explicitly skipped:
+```bash
+mkdir -p .teamix-evo/.upgrade-staging/.processed
+mv .teamix-evo/.upgrade-staging/<dir> .teamix-evo/.upgrade-staging/.processed/
+```
+Tell the user the directory was archived and that `git diff` will show every accepted file replacement plus the staging move in one shot.
+If the user wants to **defer** the entire staging (not per-entry skip), leave it in place — they can re-run this skill later.
+## Edge cases (component source)
+| Situation                                                              | Response                                                                                                                                                           |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `meta.json` parse error / wrong schemaVersion                          | Print the path + parse error; **do not** delete it. Suggest `teamix-evo ui upgrade` re-run or `teamix-evo restore --list`.                                         |
+| `current.tsx` differs from `entry.current.target` on disk              | The user edited locally since CLI generated staging. Show both diffs (your edits vs incoming), let them merge by hand; do not silently overwrite.                  |
+| User passes `--apply` to a CLI upgrade command                         | The CLI itself rejects with frozen-boundary guidance. Re-route them here.                                                                                          |
+| Multiple staging directories pending                                   | Process newest-first one staging at a time — never batch across staging dirs (different `fromVersion/toVersion`, different baseline).                              |
+| User says “全部接受” / “apply all”                                     | Still show every diff before applying. Bulk-confirm is fine, **silent apply is not**.                                                                              |
+| `lineage=mixed` with `foreign` entries                                 | After upgradable-\* are processed, walk foreign entries one-by-one and ask: register (out of scope here — redirect to `teamix-evo ui add <id>`), delete, or leave. |
+| User asks to handle an old staging dir that's already in `.processed/` | Read the manifest from `.processed/`, re-render diffs, decide whether to re-apply or remove permanently.                                                           |