@teamix-evo/skills 0.12.1 → 0.13.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.
- package/README.md +1 -1
- package/manifest.json +11 -28
- package/package.json +2 -2
- package/src/teamix-evo-code-opentrek/SKILL.md +13 -13
- package/src/teamix-evo-code-opentrek/api-layering.md +53 -44
- package/src/teamix-evo-code-opentrek/checklist.md +24 -24
- package/src/teamix-evo-code-opentrek/file-structure.md +55 -36
- package/src/teamix-evo-code-opentrek/forms-and-validation.md +17 -16
- package/src/teamix-evo-code-opentrek/reuse-first.md +6 -9
- package/src/teamix-evo-code-opentrek/testing.md +14 -14
- package/src/teamix-evo-code-uni-manager/SKILL.md +15 -15
- package/src/teamix-evo-code-uni-manager/api-layering.md +74 -58
- package/src/teamix-evo-code-uni-manager/checklist.md +28 -28
- package/src/teamix-evo-code-uni-manager/error-and-loading.md +2 -2
- package/src/teamix-evo-code-uni-manager/file-structure.md +77 -62
- package/src/teamix-evo-code-uni-manager/forms-and-validation.md +17 -15
- package/src/teamix-evo-code-uni-manager/reuse-first.md +7 -10
- package/src/teamix-evo-code-uni-manager/routing-and-codesplit.md +1 -1
- package/src/teamix-evo-code-uni-manager/testing.md +37 -37
- package/src/teamix-evo-design-opentrek/SKILL.md +17 -20
- package/src/teamix-evo-design-opentrek/boundaries.md +1 -1
- package/src/teamix-evo-design-opentrek/checklist.md +5 -5
- package/src/teamix-evo-design-opentrek/components.md +19 -19
- package/src/teamix-evo-design-opentrek/examples/standard-card-list.html +1 -1
- package/src/teamix-evo-design-opentrek/examples/standard-table-list.html +1 -1
- package/src/teamix-evo-design-opentrek/foundations.md +6 -6
- package/src/teamix-evo-design-opentrek/pages/dashboard-page/SKILL.md +18 -19
- package/src/teamix-evo-design-opentrek/pages/dashboard-page/patterns/dashboard-opentrek.md +6 -6
- package/src/teamix-evo-design-opentrek/pages/detail-page/SKILL.md +24 -25
- package/src/teamix-evo-design-opentrek/pages/detail-page/patterns/api-doc-detail.md +3 -7
- package/src/teamix-evo-design-opentrek/pages/detail-page/patterns/comparison-detail.md +3 -7
- package/src/teamix-evo-design-opentrek/pages/detail-page/patterns/monitor-detail.md +3 -7
- package/src/teamix-evo-design-opentrek/pages/detail-page/patterns/resource-detail.md +10 -10
- package/src/teamix-evo-design-opentrek/pages/form-page/SKILL.md +26 -27
- package/src/teamix-evo-design-opentrek/pages/list-page/SKILL.md +35 -36
- package/src/teamix-evo-design-opentrek/pages/list-page/_shared/item-card-spec.md +41 -32
- package/src/teamix-evo-design-opentrek/pages/list-page/patterns/card-list-opentrek.md +10 -10
- package/src/teamix-evo-design-opentrek/pages/list-page/patterns/card-list.md +23 -23
- package/src/teamix-evo-design-opentrek/pages/list-page/patterns/standard-list-opentrek.md +8 -8
- package/src/teamix-evo-design-opentrek/pages/list-page/patterns/standard-list.md +8 -8
- package/src/teamix-evo-design-opentrek/patterns/color-mapping.md +2 -2
- package/src/teamix-evo-design-opentrek/patterns/dashboard.md +1 -1
- package/src/teamix-evo-design-opentrek/patterns/detail-page.md +9 -9
- package/src/teamix-evo-design-opentrek/patterns/form-page.md +6 -6
- package/src/teamix-evo-design-opentrek/patterns/list-page.md +9 -9
- package/src/teamix-evo-design-opentrek/patterns/page-types.md +3 -3
- package/src/teamix-evo-design-opentrek/principles.md +541 -0
- package/src/teamix-evo-design-opentrek/rules/common-components.json +206 -76
- package/src/teamix-evo-design-opentrek/rules/component-specs.json +2 -2
- package/src/teamix-evo-design-opentrek/rules/page-frame.json +197 -193
- package/src/teamix-evo-design-opentrek/{generation-flow.md → workflow.md} +141 -22
- package/src/teamix-evo-design-uni-manager/SKILL.md +5 -5
- package/src/teamix-evo-design-uni-manager/boundaries.md +2 -2
- package/src/teamix-evo-design-uni-manager/brand.md +1 -1
- package/src/teamix-evo-design-uni-manager/checklist.md +2 -2
- package/src/teamix-evo-design-uni-manager/components.md +11 -11
- package/src/teamix-evo-design-uni-manager/foundations.md +7 -7
- package/src/teamix-evo-design-uni-manager/generation-flow.md +3 -3
- package/src/teamix-evo-manage/SKILL.md +111 -709
- package/src/teamix-evo-manage/init.md +98 -0
- package/src/teamix-evo-manage/migrate.md +100 -0
- package/src/teamix-evo-manage/rearchitect-capture-guide.md +174 -0
- package/src/teamix-evo-manage/rearchitect.md +373 -0
- package/src/teamix-evo-manage/update-component-staging.md +188 -0
- package/src/teamix-evo-manage/update-token-rename.md +126 -0
- package/src/teamix-evo-manage/update-token-treatment.md +116 -0
- package/src/teamix-evo-manage/update.md +213 -0
- package/src/teamix-evo-design-opentrek/brand.md +0 -154
- package/src/teamix-evo-design-opentrek/pages/list-page/_shared/search-combo-spec.md +0 -194
- package/src/teamix-evo-design-opentrek/philosophy.md +0 -98
- package/src/teamix-evo-design-opentrek/rules/README.md +0 -39
- package/src/teamix-evo-design-opentrek/rules/_assets/OP_AGENT RUNTIME.svg +0 -1
- package/src/teamix-evo-design-opentrek/rules/_assets/OP_AI GATEWAY.svg +0 -1
- package/src/teamix-evo-design-opentrek/rules/_assets/OP_AI STUDIO.svg +0 -1
- package/src/teamix-evo-design-opentrek/rules/_assets/OP_DEV-2.svg +0 -1
- package/src/teamix-evo-design-opentrek/rules/_assets/OP_LOGO.svg +0 -1
- package/src/teamix-evo-design-opentrek/rules/_assets/OP_OPS.svg +0 -1
- package/src/teamix-evo-design-opentrek/rules/layout-rules.json +0 -218
- package/src/teamix-evo-design-opentrek/rules/page-header-spec.md +0 -123
- package/src/teamix-evo-design-opentrek/rules/sidebar-spec.md +0 -217
- package/src/teamix-evo-upgrade/SKILL.md +0 -431
- /package/src/teamix-evo-design-opentrek/{rules/boundaries.rules.json → boundaries.json} +0 -0
|
@@ -1,34 +1,38 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: teamix-evo-manage
|
|
3
3
|
description: |
|
|
4
|
-
Single entry point for the teamix-evo lifecycle:
|
|
5
|
-
TRIGGER when:
|
|
6
|
-
SKIP:
|
|
7
|
-
Coordinates with: teamix-evo-design
|
|
4
|
+
Single entry point for the teamix-evo lifecycle: init, update, migrate, switch, restore, uninstall.
|
|
5
|
+
TRIGGER when: user runs or asks about `teamix-evo init` / `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo blocks ...` / `teamix-evo lint ...` / `teamix-evo migrate` / `teamix-evo restore ...` / `teamix-evo switch ...`; mentions 初始化/接入/更新/升级/迁移/卸载/staging/codemod/token 治理/baseline; touches `.teamix-evo/config.json` or `manifest.json`.
|
|
6
|
+
SKIP: content tasks — components, pages, services (→ code-*); visual design review (→ design-*); pure styling / token tweaks (→ ESLint).
|
|
7
|
+
Coordinates with: teamix-evo-design-* / teamix-evo-code-* — manage precedes content skills, never co-triggers.
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# teamix-evo-manage
|
|
11
11
|
|
|
12
|
-
Single entry skill for the **teamix-evo** toolkit lifecycle.
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
12
|
+
Single entry skill for the **teamix-evo** toolkit lifecycle. Three-command model: **init → update → migrate**。
|
|
13
|
+
|
|
14
|
+
| Sub-file | 覆盖范围 |
|
|
15
|
+
| --- | --- |
|
|
16
|
+
| [init.md](init.md) | 初始化 Teamix Evo 套件 — 空目录 → 脚手架 + init pipeline |
|
|
17
|
+
| [update.md](update.md) | 套件更新 — skill 升级 / 组件源码升级 staging / promotion |
|
|
18
|
+
| [migrate.md](migrate.md) | shadcn → Teamix Evo 迁移 — 前置检查 + AI 引导转换 |
|
|
19
|
+
| *(本文件 inline)* | variant 切换（switch）/ 失败回滚（restore） |
|
|
20
|
+
| [update-token-rename.md](update-token-rename.md) | 更新应用 Part A — token rename hint 消费流程（5 步 workflow） |
|
|
21
|
+
| [update-component-staging.md](update-component-staging.md) | 更新应用 Part B — 组件源码 staging apply 流程（5 步 workflow） |
|
|
22
|
+
| [update-token-treatment.md](update-token-treatment.md) | 更新应用 Part C — token 治理 pipeline（diagnose → treat → reflect → baseline） |
|
|
23
|
+
| [rearchitect.md](rearchitect.md) | 旧工程重构重建 — 旧工程分析 + 计划 + AI 驱动逐页重建 |
|
|
24
|
+
| [rearchitect-capture-guide.md](rearchitect-capture-guide.md) | 重构三轨材料准备 — Qoder repowiki + Qoderwork 截图 + Playwright 进阶 |
|
|
25
|
+
| *(本文件 inline)* | 卸载 / CLI 概览 / 配置 / 常见错误 |
|
|
22
26
|
|
|
23
27
|
## 安装方式
|
|
24
28
|
|
|
25
29
|
本 skill 是 **entry skill**(lifecycle orchestrator),manifest 里声明 `scope: "global"`。**推荐全局安装一次**:
|
|
26
30
|
|
|
27
31
|
```bash
|
|
28
|
-
npx teamix-evo skills add teamix-evo-manage --scope global -y
|
|
32
|
+
npx teamix-evo@latest skills add teamix-evo-manage --scope global -y
|
|
29
33
|
```
|
|
30
34
|
|
|
31
|
-
`skills add`(默认 project scope)与 `npm create teamix-evo` **不会**自动装本 skill —— bulk 模式按 scope
|
|
35
|
+
`skills add`(默认 project scope)与 `npm create teamix-evo` **不会**自动装本 skill —— bulk 模式按 scope 自动跳过。如果用户在项目级显式 `skills add teamix-evo-manage --scope project`,CLI 给出"推荐 global"warning 但仍装入(用户自负责),代价是后续 IDE 会同时识别全局与项目两份副本。
|
|
32
36
|
|
|
33
37
|
## 自助升级
|
|
34
38
|
|
|
@@ -42,7 +46,7 @@ npx teamix-evo@latest skills update --dry-run # 预览,不写盘
|
|
|
42
46
|
|
|
43
47
|
`@latest` 让 npx 拉最新 CLI + 最新 `@teamix-evo/skills` 包。命令头部会打印 CLI 版本与 skills 包版本,方便排查 npx cache 与包不同步的问题。
|
|
44
48
|
|
|
45
|
-
|
|
49
|
+
升级范围（双闸机制：只升已装 + scope 匹配）:
|
|
46
50
|
|
|
47
51
|
- 只更新 lock 里**已装**的 skill — 新 skill 用 `skills add <id>` 显式加入,不会被 update 自动装上
|
|
48
52
|
- 只更新 scope 与当前 install scope 一致的 skill — 项目级 update 不会动全局 manage,反之亦然
|
|
@@ -54,17 +58,31 @@ npx teamix-evo@latest skills update --dry-run # 预览,不写盘
|
|
|
54
58
|
|
|
55
59
|
```text
|
|
56
60
|
用户的指令命中本 skill
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
│
|
|
60
|
-
|
|
61
|
-
│
|
|
62
|
-
|
|
63
|
-
│
|
|
64
|
-
│
|
|
65
|
-
|
|
66
|
-
│
|
|
67
|
-
│
|
|
61
|
+
│
|
|
62
|
+
├─ detectProjectState(cwd)
|
|
63
|
+
│
|
|
64
|
+
├─ state = 'teamix-evo'（有 .teamix-evo/）
|
|
65
|
+
│ ├── 提到「重构 / 重建 / rearchitect / 旧项目 / legacy」?
|
|
66
|
+
│ │ 是 ──▶ 读 rearchitect.md
|
|
67
|
+
│ ├── 提到「更新 / update / 升级 / staging / apply / promote
|
|
68
|
+
│ │ / token 改名 / codemod / 治理 / diagnose / treat / baseline」?
|
|
69
|
+
│ │ 是 ──▶ 读 update.md
|
|
70
|
+
│ ├── 提到「switch / 切变体」?
|
|
71
|
+
│ │ 是 ──▶ 见本文件「variant 切换」章节
|
|
72
|
+
│ ├── 提到「restore / 回滚」?
|
|
73
|
+
│ │ 是 ──▶ 见本文件「失败回滚」章节
|
|
74
|
+
│ └── 其他 ──▶ 卸载 / 各子命令按需调用(见本文件)
|
|
75
|
+
│
|
|
76
|
+
├─ state = 'shadcn'（有 components.json + package.json）
|
|
77
|
+
│ └── 读 migrate.md（shadcn → Teamix Evo）
|
|
78
|
+
│
|
|
79
|
+
├─ state = 'empty'（空目录）
|
|
80
|
+
│ └── 读 init.md（脚手架 + init pipeline）
|
|
81
|
+
│
|
|
82
|
+
└─ state = 'other'
|
|
83
|
+
└── 提示暂不支持，建议：
|
|
84
|
+
1. 用 teamix-evo init 初始化新空目录
|
|
85
|
+
2. 对旧项目进行 AI 引导的重构
|
|
68
86
|
```
|
|
69
87
|
|
|
70
88
|
## 业务名 → variant 映射
|
|
@@ -75,249 +93,82 @@ npx teamix-evo@latest skills update --dry-run # 预览,不写盘
|
|
|
75
93
|
| ----------------------------------------------------------------------------- | ------------- |
|
|
76
94
|
| 云管 / 云管控制台 / 云管项目 / 云管工程 / uni-manager / unimanager / 统一管理 | `uni-manager` |
|
|
77
95
|
| op / opentrek / OpenTrek / 探索者 | `opentrek` |
|
|
78
|
-
|
|
|
96
|
+
| *未提及业务,只说"做一个工程"* | **询问** |
|
|
79
97
|
|
|
80
|
-
校验:`npx teamix-evo tokens list-variants` 列出当前 `@teamix-evo/tokens` 包内所有变体;若上表中的关键词指向尚未发布的变体,先告知用户该 variant 还未上线。
|
|
98
|
+
校验:`npx teamix-evo@latest tokens list-variants` 列出当前 `@teamix-evo/tokens` 包内所有变体;若上表中的关键词指向尚未发布的变体,先告知用户该 variant 还未上线。
|
|
81
99
|
|
|
82
100
|
## CLI 命令概览
|
|
83
101
|
|
|
84
|
-
CLI 二进制名 `teamix-evo
|
|
102
|
+
CLI 二进制名 `teamix-evo`。概览表列出所有子命令与一句话用途；**完整选项请跑 `--help`**。
|
|
85
103
|
|
|
86
104
|
| Group | Verb | 用途 |
|
|
87
105
|
| ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
88
|
-
| **
|
|
89
|
-
| **
|
|
106
|
+
| **init** | `init [-y] [--variant <v>] [--pm <pm>] [--no-git] [--no-install] [--cwd <dir>]` | 初始化 Teamix Evo 套件：空目录 → 脚手架 + 8 步 init pipeline |
|
|
107
|
+
| **update** | `update [--json] [--cwd <dir>]` | 套件更新入口：检测已安装资产 + lint 包版本 + AGENTS.md 状态，引导 AI skill 执行更新计划 |
|
|
108
|
+
| **migrate** | `migrate [--json] [--cwd <dir>]` | shadcn → Teamix Evo 迁移：前置检查 + AI skill 引导转换 |
|
|
90
109
|
| **switch** | `switch <new-variant> [--apply] [-y] [--cwd <dir>]` | 切到目标 variant：dry-run 默认，`--apply` 才真写；自动 snapshot + token rename hint |
|
|
91
|
-
| **restore** | `restore [<ts>] [--list] [-y] [--cwd <dir>]` | 失败回滚：从 snapshot 还原 `.teamix-evo/`，pre-restore
|
|
110
|
+
| **restore** | `restore [<ts>] [--list] [-y] [--cwd <dir>]` | 失败回滚：从 snapshot 还原 `.teamix-evo/`，pre-restore 自身可逆 |
|
|
92
111
|
| **tokens** | `init <variant>` | 初始化指定变体的 design tokens（`<variant>` 必填） |
|
|
93
112
|
| | `list-variants` | 列出所有可选变体 |
|
|
94
113
|
| | `list` | 列出已装 tokens 资源 |
|
|
95
|
-
| | `update` | 刷新 regenerable tokens（frozen
|
|
114
|
+
| | `update` | 刷新 regenerable tokens（frozen 保留） |
|
|
96
115
|
| | `uninstall` | 卸载 tokens |
|
|
97
116
|
| | `audit` | 审计 `tokens.overrides.css`：冗余 / 有效 / 推荐迁移 / 项目特有（v3↔v4 语义比较） |
|
|
98
|
-
| | `diagnose` | 分级治理报告：跑 lint → 按 L1/L2/L3 分类 → 产出 `.treatment-plan.md
|
|
99
|
-
| | `treat` | 一键流水线：按 diagnose 顺序执行 codemod → 前后基线对比 →
|
|
100
|
-
| | `reflect` | Token 反哺：检测频次 ≥ 3 的业务色值 → 提议命名 → 写入 overrides
|
|
117
|
+
| | `diagnose` | 分级治理报告：跑 lint → 按 L1/L2/L3 分类 → 产出 `.treatment-plan.md` |
|
|
118
|
+
| | `treat` | 一键流水线：按 diagnose 顺序执行 codemod → 前后基线对比 → 降幅报告 |
|
|
119
|
+
| | `reflect` | Token 反哺：检测频次 ≥ 3 的业务色值 → 提议命名 → 写入 overrides |
|
|
101
120
|
| | `codemod <name>` | 单独跑指定 codemod（hsl-to-v4 / hex-to-token / tw-scale-to-semantic / space-to-gap / arbitrary-to-token） |
|
|
102
121
|
| | `baseline-check` | 对比当前 lint 违规与锁定基线，CI 友好 |
|
|
103
|
-
| **skills** | `init` | 自举：按 variant + scope 装全部匹配 skill（
|
|
122
|
+
| **skills** | `init` | 自举：按 variant + scope 装全部匹配 skill（init 无 ids = 自举全部；add 必填 ids = 增量） |
|
|
104
123
|
| | `add <name...>` | 增量装指定 skill |
|
|
105
124
|
| | `list` (alias `ls`) | 列出全部 skill（`--installed` 仅已装） |
|
|
106
|
-
| | `update [name...]` | 升级已装 skill
|
|
125
|
+
| | `update [name...]` | 升级已装 skill（双闸：只升已装 + scope 匹配；支持 `--scope` + `--dry-run`） |
|
|
107
126
|
| | `uninstall [ids...]` | 卸载 skill |
|
|
108
|
-
| | `doctor` | 检测 source ↔ IDE
|
|
127
|
+
| | `doctor` | 检测 source ↔ IDE 镜像漂移 |
|
|
109
128
|
| | `sync [name...]` | 重新镜像到 IDE 路径（不升版本） |
|
|
110
129
|
| **ui** | `init` | 初始化 ui 配置（aliases / icon / tsx / rsc） |
|
|
111
130
|
| | `add <id...>` | 安装 UI 组件（auto-resolve registryDependencies，frozen） |
|
|
112
131
|
| | `list` | 列出 UI 组件（`--installed` / `--include-deprecated`） |
|
|
113
|
-
| | `
|
|
132
|
+
| | `update [id...]` | 生成 ui 升级 staging（仅写 `.upgrade-staging/`；通过本 skill update.md 流程应用） |
|
|
114
133
|
| | `promote-to-biz [ids...]` | 把 ui staging 条目按 8 模式（Coexist/Preset/Wrapper/Compose/Variant/Fork/TokenOnly/ManualReview）落地到 `src/components/business/` + manifest（Init 落地计划 §C.3） |
|
|
115
134
|
| **biz-ui** | `add <id...>` | 安装业务组件（`--variant` 必填） |
|
|
116
135
|
| | `list` | 列出变体下的业务组件 |
|
|
117
136
|
| | `list-variants` | 列出可用业务组件变体 |
|
|
118
|
-
| | `
|
|
119
|
-
| **blocks** | `add <id...>` | 安装 marketing block（Hero / Features / CTA
|
|
137
|
+
| | `update [id...]` | 生成 biz-ui 升级 staging（变体感知；通过本 skill update.md 流程应用） |
|
|
138
|
+
| **blocks** | `add <id...>` | 安装 marketing block（Hero / Features / CTA 等落地页区块） |
|
|
120
139
|
| | `list` | 列出可用 blocks（`--installed` 仅已装；`--json` 机器可读） |
|
|
121
|
-
| | `
|
|
122
|
-
| **templates** | ~~`add` / `list` / `list-variants`~~ | ⚠️ 已废弃，请改用 `teamix-evo blocks`（ADR 0044） |
|
|
140
|
+
| | `update [id...]` | 生成 blocks 升级 staging（通过本 skill update.md 流程应用） |
|
|
123
141
|
| **lint** | `init` | 初始化 ESLint + Stylelint token-discipline 规则 |
|
|
124
|
-
| **logs** | `analyze` | 汇总 vibe-logger JSONL（tool / tag / MCP 频次） |
|
|
125
|
-
| | `trace` | 会话级调用链回溯（按 prompt / session 过滤） |
|
|
126
142
|
|
|
127
143
|
> **脚注**
|
|
128
144
|
>
|
|
129
|
-
> - `tokens` / `biz-ui` 共享 variant
|
|
130
|
-
> - `skills init` vs `add`：init 无 ids = 自举全部匹配 skill；add 必填 ids =
|
|
131
|
-
> -
|
|
145
|
+
> - `tokens` / `biz-ui` 共享 variant 名空间，与 `tokens init` 选定 variant 一致。`blocks` 是 token-driven、variant 无关的独立包。
|
|
146
|
+
> - `skills init` vs `add`：init 无 ids = 自举全部匹配 skill；add 必填 ids = 增量。
|
|
147
|
+
> - Skills 从 npm 包直接渲染到 IDE 镜像路径（`.qoder/skills/`、`.claude/skills/`），lock 文件位于 `.teamix-evo/skills-lock.json`。
|
|
132
148
|
|
|
133
149
|
### 动态查询（详细选项 & 实时清单）
|
|
134
150
|
|
|
135
151
|
概览表只列命令名与用途。需要完整 flags / 选项时：
|
|
136
152
|
|
|
137
153
|
```bash
|
|
138
|
-
npx teamix-evo <group> --help # group 级帮助
|
|
139
|
-
npx teamix-evo <group> <verb> --help # 子命令级帮助
|
|
154
|
+
npx teamix-evo@latest <group> --help # group 级帮助
|
|
155
|
+
npx teamix-evo@latest <group> <verb> --help # 子命令级帮助
|
|
140
156
|
npx create-teamix-evo --help # 脚手架帮助
|
|
141
157
|
```
|
|
142
158
|
|
|
143
|
-
需要组件 / skill / token
|
|
144
|
-
|
|
145
|
-
| 查什么 | MCP 工具 |
|
|
146
|
-
| ------------------------ | ------------------------------------- |
|
|
147
|
-
| UI 组件列表 / 搜索 | `list_components` / `find_components` |
|
|
148
|
-
| 组件详情（props / deps） | `get_component_meta` |
|
|
149
|
-
| Blocks 列表 / 搜索 | `blocks_list` / `blocks_find` |
|
|
150
|
-
| Block 详情 | `blocks_get` |
|
|
151
|
-
| Skill 列表 / 搜索 | `skills_list` / `skills_find` |
|
|
152
|
-
| Skill 详情 | `skills_get` |
|
|
153
|
-
| Design tokens | `tokens_list` / `tokens_search` |
|
|
154
|
-
| ADR 决策记录 | `adr_list` / `adr_find` / `adr_get` |
|
|
155
|
-
|
|
156
|
-
## 场景 1 · 模糊初始化
|
|
157
|
-
|
|
158
|
-
**触发**:用户说"初始化一个项目 / 工程",未指明 variant。
|
|
159
|
-
|
|
160
|
-
**步骤**:
|
|
161
|
-
|
|
162
|
-
1. 确认目录(默认 `./<project-name>`,可由用户改)。
|
|
163
|
-
2. 列出 variants(`tokens list-variants` 的输出),让用户选(`AskUserQuestion`):
|
|
164
|
-
- OpenTrek(opentrek):AI 副驾驶 / 通用中后台
|
|
165
|
-
- Uni-Manager(uni-manager):云资源管理(大屏 / 拓扑 / 7 类 AI 场景)
|
|
166
|
-
3. 转场景 2,带上选定 variant 直跑。
|
|
167
|
-
|
|
168
|
-
## 场景 2 · 具名变体初始化(空目录 → 完整工程)
|
|
169
|
-
|
|
170
|
-
**触发**:用户在「业务名 → variant 映射」中能锁定 variant,或场景 1 询问后得到答复。
|
|
171
|
-
|
|
172
|
-
### 第一步：生成骨架
|
|
173
|
-
|
|
174
|
-
```bash
|
|
175
|
-
# 在父目录创建新项目子目录（常规方式）
|
|
176
|
-
npm create teamix-evo@latest <dir> --variant <name>
|
|
177
|
-
# 在当前空目录原地初始化（用户已 cd 进空目标目录 / IDE 已打开空目录）
|
|
178
|
-
npm create teamix-evo@latest . --variant <name>
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
> **选择 `<dir>` 还是 `.`**：若用户说"为当前目录初始化"且当前目录为空（或仅含 .git / README），用 `.`；若用户给出项目名或要新建目录，用项目名。
|
|
182
|
-
> **⚠️ 当前目录已有代码文件**：不要用 `create-teamix-evo`（`--force` 会清空目录），直接走**场景 3**（`teamix-evo init`）在现有工程上装套件。
|
|
183
|
-
> 传 `--variant` 后 CLI 自动跳过所有交互（无需额外 `-y`；`-y` 经 npx 时会被 npx 自身消费，不会传给 create-teamix-evo）。
|
|
184
|
-
|
|
185
|
-
`create-teamix-evo` 有两个 preset（`opentrek` / `uni-manager`），由 `--variant` 自动推断。骨架生成流程：
|
|
186
|
-
|
|
187
|
-
| 阶段 | 产物 |
|
|
188
|
-
| ---- | ------------------------------------------------ |
|
|
189
|
-
| 1 | 目标目录校验 / 创建 |
|
|
190
|
-
| 2 | Vite + React + TS scaffold（base template 复制） |
|
|
191
|
-
| 3 | variant overlay（变体专属配置覆盖） |
|
|
192
|
-
| 4 | package.json merge（合并依赖） |
|
|
193
|
-
| 5 | `.mcp.json` 写入 |
|
|
194
|
-
| 6 | 依赖安装（`pnpm install` / `npm install`） |
|
|
195
|
-
| 7 | git init |
|
|
196
|
-
|
|
197
|
-
> **注意**：`create` 不再调用 `teamix-evo/core` 的任何函数（ADR 0043），它只生成纯静态骨架。
|
|
198
|
-
|
|
199
|
-
### 第二步：装入 AI 套件
|
|
200
|
-
|
|
201
|
-
骨架完成后，`create` 的 next-steps 会提示用户跑：
|
|
202
|
-
|
|
203
|
-
```bash
|
|
204
|
-
cd <dir>
|
|
205
|
-
npx teamix-evo init --variant <name> -y
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
该命令走场景 3 的 8 步流水线，装入 tokens / skills / ui 组件 / lint 等全套资产。
|
|
209
|
-
|
|
210
|
-
> 提示:`teamix-evo-manage` 是 entry skill,推荐**全局**装一次(`npx teamix-evo skills add teamix-evo-manage --scope global`)。create CLI 不会装它到 project,scaffold 完成后的 next-steps 会提示用户。
|
|
211
|
-
|
|
212
|
-
### 第三步：提交 init 产出（必做）
|
|
213
|
-
|
|
214
|
-
`teamix-evo init` 会生成大量文件（tokens / skills / ui 组件 / lint 配置等），**必须立刻 commit**，否则 IDE 会显示满屏 untracked 文件，后续协作极易冲突：
|
|
215
|
-
|
|
216
|
-
```bash
|
|
217
|
-
git add .
|
|
218
|
-
git commit -m "chore: init teamix-evo (<variant>)"
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
### 第四步：验证
|
|
222
|
-
|
|
223
|
-
```bash
|
|
224
|
-
pnpm dev # 立刻可跑
|
|
225
|
-
pnpm typecheck # 验证零类型错误
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
## 场景 3 · 普通版接入（现有 npm 工程 → `teamix-evo init`）
|
|
229
|
-
|
|
230
|
-
**触发**：用户已有 `package.json` 工程（常含 React/TS/Vite/Tailwind v4 / shadcn-style 源码），想接入 teamix-evo AI 套件而**不**重建工程。
|
|
231
|
-
|
|
232
|
-
**唯一命令**：
|
|
233
|
-
|
|
234
|
-
```bash
|
|
235
|
-
npx teamix-evo init [-y] [--dry-run] [--variant <name>] [--cwd <dir>]
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
### 三分支决策树（init 自动判断）
|
|
239
|
-
|
|
240
|
-
| 当前目录状态 | init 反应 |
|
|
241
|
-
| ------------------------------------- | --------------------------------------------------- |
|
|
242
|
-
| 空目录 / 仅含 `.git` 等可忽略文件 | ⚠ 提示改用 `npm create teamix-evo@latest`（场景 2） |
|
|
243
|
-
| 已有 `.teamix-evo/` | ✓ 已初始化，每步幂等短路自动跳过已完成步骤 |
|
|
244
|
-
| 有 `package.json` 但无 `.teamix-evo/` | ✓ 走主路径 |
|
|
245
|
-
|
|
246
|
-
### 主路径八步流水线
|
|
247
|
-
|
|
248
|
-
| # | 步骤 | 关键 | 行为 |
|
|
249
|
-
| --- | ---------- | ---- | -------------------------------------------------------------------------------------- |
|
|
250
|
-
| 1 | tokens | ✓ | 写 `tokens/`，顺带装 design skill；旧路径单文件命中 `migrate` 策略时自动提层迁移 |
|
|
251
|
-
| 2 | skills | ✓ | 项目级装 `teamix-evo-code-<variant>`（manage 全局装一次，design 由 1 顺带 — ADR 0033） |
|
|
252
|
-
| 3 | agents-md | – | 生成根 `AGENTS.md`，managed-region 可重生（ADR 0038） |
|
|
253
|
-
| 4 | ui-init | ✓ | 写 `components.json` + `packages.ui` 配置 |
|
|
254
|
-
| 5 | ui-add | – | 装全量 UI 组件源码（overwrite 模式） |
|
|
255
|
-
| 6 | biz-ui-add | – | 装当前 variant 下全量业务组件（无可用则 skip） |
|
|
256
|
-
| 7 | lint | – | `runLintInit`（ESLint + Stylelint） |
|
|
257
|
-
| 8 | gitignore | – | 追加 teamix-evo runtime 规则到 `.gitignore` |
|
|
258
|
-
|
|
259
|
-
> 关键步骤失败 → 后续关键步骤短路成 `skip(aborted)`；非关键步骤失败不阻断整体。
|
|
260
|
-
|
|
261
|
-
### 8 类冲突（薄版检测 — ADR 0043 §3）
|
|
262
|
-
|
|
263
|
-
init 前自动 `detectConflicts(cwd)` 扫描，产出结构化报告；发现冲突时终止并输出，由 AI 层决策下一步。`--force` 跳过全部检测。
|
|
264
|
-
|
|
265
|
-
| 冲突键 | 检测对象 |
|
|
266
|
-
| ------------------ | --------------------------------------- |
|
|
267
|
-
| `tokens` | `tokens/` 目录已存在 |
|
|
268
|
-
| `agents-md` | 根 `AGENTS.md` 已存在 |
|
|
269
|
-
| `components-json` | 根目录 `components.json` 已存在 |
|
|
270
|
-
| `shadcn-source` | `src/components/ui/` 下已有组件文件 |
|
|
271
|
-
| `tailwind-config` | `tailwind.config.*` 已存在 |
|
|
272
|
-
| `index-css` | `src/index.css` 含现有 token import |
|
|
273
|
-
| `eslint-config` | `.eslintrc*` / `eslint.config.*` 已存在 |
|
|
274
|
-
| `stylelint-config` | `.stylelintrc*` 已存在 |
|
|
275
|
-
|
|
276
|
-
> `--force` 跳过全部冲突检测，overwrite 所有已有文件；`--dry-run` 只打印计划不写文件。
|
|
277
|
-
|
|
278
|
-
#### tokens `migrate` 策略（W1.4 提层兼容）
|
|
279
|
-
|
|
280
|
-
当工程里检测到旧版单文件 token（`src/design-tokens.css` / `src/styles/design-tokens.css` / `src/styles/tokens.css`）时，wizard 默认推荐 `migrate`：
|
|
281
|
-
|
|
282
|
-
- 读取每个旧文件内容，按时间戳 banner append 到根 `tokens/tokens.overrides.css`（不存在则用空模板创建）；
|
|
283
|
-
- 备份旧文件到 `.teamix-evo/.backups/<rel>.<ts>.bak`（与 snapshot/restore 同根，src/\*\* 不被污染）；
|
|
284
|
-
- 删除旧文件。空文件 / 不存在的路径会进 `skipped` 列表，**不删原文件**。
|
|
285
|
-
|
|
286
|
-
落地输出会写明 `migrated N file(s) → tokens/tokens.overrides.css`。`migrate` 失败仅记录在 step detail，不影响 tokens 主步骤的成功语义。
|
|
287
|
-
|
|
288
|
-
### Partial（部分完成）状态恢复
|
|
289
|
-
|
|
290
|
-
CLI 在 partial 状态会打印“恢复指引”面板：失败步骤名、错误信息、已完成步骤、建议命令。**修好原因后直接重跑 `teamix-evo init`** —— 每个 sub-step 幂等，已落地的会 `already-initialized` 短路，从断点处续接。
|
|
291
|
-
|
|
292
|
-
### 结束时告诉用户
|
|
293
|
-
|
|
294
|
-
- 已落地的 step 列表 + variant / IDE / scope。
|
|
295
|
-
- 全局 entry skill：若 `~/.qoder/skills/teamix-evo-manage` 不存在，补一句 `npx teamix-evo skills add teamix-evo-manage --scope global -y`（ADR 0033）。
|
|
296
|
-
- **必须 commit init 产出**：init 会生成 tokens / skills / agents-md / ui / lint 等大量文件，不提交会导致 IDE 满屏 untracked 文件。AI 必须在 init 成功后立即执行：
|
|
297
|
-
|
|
298
|
-
```bash
|
|
299
|
-
git add .
|
|
300
|
-
git commit -m "chore: init teamix-evo (<variant>)"
|
|
301
|
-
```
|
|
302
|
-
|
|
303
|
-
## 场景 4 · 升级
|
|
304
|
-
|
|
305
|
-
> **注意**：顶层 `teamix-evo update` 命令已移除（ADR 0043）。tokens / skills 升级请直接使用对应子命令（`tokens update` / `skills update`）。组件源码升级走 `ui upgrade` / `biz-ui upgrade`。
|
|
159
|
+
需要组件 / skill / token 实时清单时，读 `.teamix-evo/meta/` 本地文件（`teamix-evo init/upgrade` 自动同步）：
|
|
306
160
|
|
|
307
|
-
|
|
161
|
+
| 查什么 | 本地路径 |
|
|
162
|
+
| --- | --- |
|
|
163
|
+
| UI 组件列表 / 搜索 | `.teamix-evo/meta/ui/manifest.json` + `grep` |
|
|
164
|
+
| 组件详情（props / deps） | `.teamix-evo/meta/ui/<id>.md` |
|
|
165
|
+
| biz-ui 组件列表 | `.teamix-evo/meta/biz-ui/manifest.json` |
|
|
166
|
+
| biz-ui 组件详情 | `.teamix-evo/meta/biz-ui/<id>.md` |
|
|
167
|
+
| Design tokens | `.teamix-evo/tokens/` 目录 |
|
|
308
168
|
|
|
309
|
-
|
|
169
|
+
## variant 切换（`teamix-evo switch`）
|
|
310
170
|
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
```bash
|
|
314
|
-
npx teamix-evo@latest skills update <skill-id> # 指定 skill
|
|
315
|
-
npx teamix-evo@latest skills update <skill-id> --dry-run # 先预览
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
### 4b · variant 切换（`teamix-evo switch` — ADR 0019 task #7）
|
|
319
|
-
|
|
320
|
-
**触发**：用户表达“切到 uni-manager / 切到云管 / 换个 variant / switch 到 opentrek / 迁到探索者体系 / variant migration”。
|
|
171
|
+
**触发**：用户表达"切到 uni-manager / 切到云管 / 换个 variant / switch 到 opentrek / 迁到探索者体系 / variant migration"。
|
|
321
172
|
|
|
322
173
|
**一行命令**：
|
|
323
174
|
|
|
@@ -333,507 +184,58 @@ npx teamix-evo@latest switch <new-variant> --apply -y # 跳二次确认（destru
|
|
|
333
184
|
| ---------------- | ---- | --------------------------------------------------------------------------------------- |
|
|
334
185
|
| `rewrite` | ✎ | regenerable 资源（tokens 主体 / brand css）— 被新 variant 覆写 |
|
|
335
186
|
| `managed-update` | ⊕ | managed 区段（AGENTS.md / 部分 config）— 仅重生 managed 区段，区段外保留 |
|
|
336
|
-
| `preserve` | ⊘ | frozen 资源（`tokens.overrides.css` / src/\*\* / biz-ui
|
|
187
|
+
| `preserve` | ⊘ | frozen 资源（`tokens.overrides.css` / src/\*\* / biz-ui）— 不动，需手动迁移 |
|
|
337
188
|
| `unchanged` | = | 文件本就与新 variant 一致 — 跳过 |
|
|
338
189
|
|
|
339
190
|
**AI 引导决策树**：
|
|
340
191
|
|
|
341
192
|
1. **先跑 dry-run**（默认就是 dry-run，允许不加任何 flag）。全量变更计划会以表格 + per-file diff 列出。
|
|
342
|
-
2. **说明清楚 `preserve` 变量**：告诉用户 frozen 文件不会被 `--apply` 覆写，它们只会被
|
|
193
|
+
2. **说明清楚 `preserve` 变量**：告诉用户 frozen 文件不会被 `--apply` 覆写，它们只会被 "token rename hint + [update-token-rename.md](update-token-rename.md) codemod 流程" 迁过去。
|
|
343
194
|
3. 用户确认后，跑 `--apply`（默认带二次确认；non-TTY 环境 / AI agent 调用需加 `-y`）。
|
|
344
195
|
4. 成功后：
|
|
345
196
|
- CLI 输出 `priorVariant: <old>` / `variant: <new>`，`config.json` 已记录备查；
|
|
346
|
-
- 若 CLI 输出 `💡 token rename hint:` —
|
|
347
|
-
5. 失败：switch 执行前会自动 `reason="switch"` snapshot，`partial`
|
|
197
|
+
- 若 CLI 输出 `💡 token rename hint:` — 继续 [update-token-rename.md](update-token-rename.md) 流程，扫 `src/**` 与 `tokens.overrides.css`。
|
|
198
|
+
5. 失败：switch 执行前会自动 `reason="switch"` snapshot，`partial` 状态可走 restore。
|
|
348
199
|
|
|
349
200
|
**不要**：
|
|
350
201
|
|
|
351
|
-
- 不要跳过 dry-run 直接 `--apply
|
|
352
|
-
-
|
|
353
|
-
- 不要把 `switch`
|
|
202
|
+
- 不要跳过 dry-run 直接 `--apply`，除非用户明确告诉你"已看过变更列表"。
|
|
203
|
+
- 不要为了"保留用户业务代码"去手动改 `src/**`：frozen 资源完全交给 codemod 流程，CLI 仓抱不越界。
|
|
204
|
+
- 不要把 `switch` 当作"调个 token 样式"的快捷手段 — 它是跨 variant 迁移，仅在业务名变更 / 双 variant 互迁时使用。
|
|
354
205
|
|
|
355
|
-
|
|
206
|
+
## 失败回滚（`teamix-evo restore`）
|
|
356
207
|
|
|
357
|
-
|
|
208
|
+
**触发**：`init` / `switch` 出现 `partial` 状态后用户希望**完全回退**到执行前的 `.teamix-evo/` 状态（而不是修原因后续跑）。
|
|
358
209
|
|
|
359
|
-
|
|
210
|
+
**两步**：
|
|
360
211
|
|
|
361
212
|
```bash
|
|
362
|
-
npx teamix-evo restore --list # 列出可用 snapshot
|
|
363
|
-
npx teamix-evo restore <ts> # 回滚到指定 snapshot
|
|
213
|
+
npx teamix-evo@latest restore --list # 列出可用 snapshot（最新在前）
|
|
214
|
+
npx teamix-evo@latest restore <ts> # 回滚到指定 snapshot（默认带二次确认，-y 跳过）
|
|
364
215
|
```
|
|
365
216
|
|
|
366
|
-
snapshot 由 `init` / `switch`
|
|
217
|
+
snapshot 由 `init` / `switch` 在执行前**自动**生成，默认保留最近 5 个；reason 字段标识来源（`init` / `switch` / `restore` / `manual`）。
|
|
367
218
|
|
|
368
|
-
**关键性质 — restore
|
|
219
|
+
**关键性质 — restore 自身可逆**：`restore <ts>` 在覆盖前会再做一次 `reason="restore"` 的安全 snapshot，所以即便回滚错版本也可以再 `restore --list` 找回前一个状态。
|
|
369
220
|
|
|
370
|
-
**AI
|
|
221
|
+
**AI 引导**：
|
|
371
222
|
|
|
372
|
-
- 优先推荐 `修因 + 重跑 init
|
|
223
|
+
- 优先推荐 `修因 + 重跑 init`（`partial` 状态恢复的常规路径）— 每步幂等，version-diff 短路。
|
|
373
224
|
- 仅当用户明确表达"恢复到执行前 / 撤销这次升级 / 全部退回"时才走 `restore`。
|
|
374
|
-
-
|
|
375
|
-
|
|
376
|
-
### 4d · 组件源码升级（`teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` — ADR 0040）
|
|
377
|
-
|
|
378
|
-
**触发**：用户表达“升级 ui / 升级业务组件 / 升级 button / 看看哪些组件有新版 / upgrade ui / upgrade biz-ui / stage ui upgrade”等关键词。
|
|
379
|
-
|
|
380
|
-
> 这里是**版本演进**（installed 资源 → 上游新版 → staging → 逐个 apply），是安装完成后跟随上游发布的升级流程。
|
|
381
|
-
|
|
382
|
-
**一行命令**：
|
|
383
|
-
|
|
384
|
-
```bash
|
|
385
|
-
npx teamix-evo ui upgrade # 全量 staging。仅在 `teamix-evo` / `mixed` lineage 产出
|
|
386
|
-
npx teamix-evo ui upgrade button input # 只 stage 指定组件
|
|
387
|
-
npx teamix-evo biz-ui upgrade # 变体感知的 biz-ui staging
|
|
388
|
-
npx teamix-evo biz-ui upgrade --apply # 错误：CLI 不写 src，guidance 走 teamix-evo-upgrade skill
|
|
389
|
-
```
|
|
390
|
-
|
|
391
|
-
运行 `teamix-evo ui upgrade` 时，也会自动跳过一次 `ui:planned` / `biz-ui:planned`，产出同样的 staging 目录。
|
|
392
|
-
|
|
393
|
-
**lineage 分三档**（CLI 只在前两者上产出 staging）：
|
|
394
|
-
|
|
395
|
-
| lineage | CLI 会产出 staging？ | AI 开场白 |
|
|
396
|
-
| --------------- | -------------------- | -------------------------------------------------------------------------- |
|
|
397
|
-
| `teamix-evo` | 是 | 走 staging → teamix-evo-upgrade skill 逐件 review |
|
|
398
|
-
| `mixed` | 是 | 升级项优先，末了与用户商量 foreign 组件（未登记）去留 |
|
|
399
|
-
| `shadcn-native` | 否 | 告诉用户他是 shadcn 原生，建议先 `teamix-evo ui init` 对齐谱系（手动迁移） |
|
|
400
|
-
| `custom-only` | 否 | 跳过。告诉用户“现有组件不在 manifest 中，升级只针对 teamix-evo 安装资产” |
|
|
225
|
+
- 回滚后告知用户：已执行 `restore <ts>`，本次操作前的状态已存为新 `reason=restore` snapshot 备查。
|
|
401
226
|
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
1. **先识别 lineage**：`ui upgrade` 的输出会带 `lineage=...`。根据表选开场白。
|
|
405
|
-
2. **路径 A（`teamix-evo` / `mixed`）**：
|
|
406
|
-
- CLI 生成 staging 后会输出 `staging at .teamix-evo/.upgrade-staging/<dir>` + risk 汇总。复述给用户。
|
|
407
|
-
- **应用 staging 交给 [`teamix-evo-upgrade`](../teamix-evo-upgrade/SKILL.md) skill** — 它会逐个展示 diff，按 risk 分批让用户确认后才复制 incoming.tsx 到 src（逐文件 hard gate）。
|
|
408
|
-
- **不要手工复制！**`incoming.tsx` 已是 alias 重写过的、可直接覆盖。但走 skill 能带 archive 动作 + risk-aware UX。
|
|
409
|
-
3. **路径 B（`shadcn-native`）**：告知用户 “CLI 不会为 shadcn 原生仓生成 staging”，提示他走 `teamix-evo ui init` 对齐谱系（参考 ADR 0040 §D1）后再升级。
|
|
410
|
-
4. **路径 C（用户误走 `--apply`）**：CLI 会拒绝 + 打印 “请走 teamix-evo-upgrade skill”。重复该提示，引导走路径 A。
|
|
411
|
-
5. **路径 D（foreign 组件）**：staging 中的 `riskLevel: foreign` 是未登记文件（`mixed` lineage）— 不要表达为“要升级”；作为联动信息告诉用户，让他决定是否 `teamix-evo ui add <id>` 收纳、删掉、或保留。
|
|
412
|
-
|
|
413
|
-
**身份划分清单**：
|
|
414
|
-
|
|
415
|
-
- **CLI**：检测 lineage / 生成 staging / 算 risk 。**从不写 `src/components/{ui,business}`**。
|
|
416
|
-
- **AI （本 skill）**：识别意图、跳起 CLI 命令、复述结果、在路径 A 上交接给 `teamix-evo-upgrade` skill。
|
|
417
|
-
- **`teamix-evo-upgrade` skill**：读 staging 、逐文件 diff 征同意、apply、archive。
|
|
418
|
-
|
|
419
|
-
**不要**：
|
|
420
|
-
|
|
421
|
-
- 不要自己在本 skill 里复制 staging 文件到 `src` — 那是 `teamix-evo-upgrade` skill 的职责。
|
|
422
|
-
- 不要听到“升级 ui”就打 `ui add` — `add` 是装进去，`upgrade` 是已装后追上上游。
|
|
423
|
-
- 不要在 `shadcn-native` lineage 强行跳 staging；CLI 跳过是预期行为。
|
|
424
|
-
|
|
425
|
-
### 4e · 组件源码 promotion（`teamix-evo ui promote-to-biz` — Init 落地计划 §C.3 / §C.4）
|
|
426
|
-
|
|
427
|
-
**触发**：用户表达“把 ui 组件融进 biz-ui / 把 button 提级成业务组件 / promote ui to business / 把 staging 里的差异融合到 business 层 / 多模式融合 / wrapper + preset 叠加 / 双轨 coexist / 把上游版和自家版同时保留”等关键词；或在场景 4d 走完 staging 后用户问“能不能直接生成业务包装组件”。
|
|
428
|
-
|
|
429
|
-
> 这是 §4d 的**下游**：4d 只生成 `.upgrade-staging/`，4e 才把条目按 AI 推荐的 `recommendedModes` 真正落地到 `src/components/business/` 并维护 manifest。**条目的 8 模式判定全部由 staging meta 给出**，本 skill 只做分组、确认、转发命令。
|
|
430
|
-
|
|
431
|
-
**一行命令**：
|
|
432
|
-
|
|
433
|
-
```bash
|
|
434
|
-
npx teamix-evo ui promote-to-biz # 默认融合最新 ui-* staging 中所有可自动模式条目
|
|
435
|
-
npx teamix-evo ui promote-to-biz button card # 只融合指定 id
|
|
436
|
-
npx teamix-evo ui promote-to-biz --modes Wrapper,Preset # 强制覆盖 staging 推荐模式
|
|
437
|
-
npx teamix-evo ui promote-to-biz --migrate-imports # Coexist 模式时连带 src/** 改 import 到 legacy-<id>
|
|
438
|
-
npx teamix-evo ui promote-to-biz --keep-original-names # Coexist 模式 export 不前缀化 Legacy
|
|
439
|
-
npx teamix-evo ui promote-to-biz --dry-run # 计划态：列模式分组 + 文件变更预览，不写盘
|
|
440
|
-
npx teamix-evo ui promote-to-biz --staging-dir <path> # 指定 staging 目录（不指定则取最新 ui-* 目录）
|
|
441
|
-
```
|
|
442
|
-
|
|
443
|
-
**8 模式分组语义**（对应 §C.3）：
|
|
444
|
-
|
|
445
|
-
| Mode | 终结？ | 产物 |
|
|
446
|
-
| -------------- | ------ | -------------------------------------------------------------------------------- |
|
|
447
|
-
| `Coexist` | 是 | `business/legacy-<id>.tsx`（用户版改名 `Legacy<Foo>`）+ `ui/<id>.tsx` 回填上游版 |
|
|
448
|
-
| `Fork` | 是 | `business/<id>.tsx`（直接搬用户版，无上游对应） |
|
|
449
|
-
| `TokenOnly` | 是 | **不创建文件**，引导用户改 `tokens/tokens.overrides.css` |
|
|
450
|
-
| `ManualReview` | 是 | **不创建文件**，列入待办交用户决策 |
|
|
451
|
-
| `Preset` | 可叠加 | `business/<id>.tsx` import 上游 + `defaultProps` |
|
|
452
|
-
| `Wrapper` | 可叠加 | `business/<id>.tsx` 包装上游 + 业务 state/effect |
|
|
453
|
-
| `Variant` | 可叠加 | `business/<id>.tsx` 扩展上游 cva（上游未 export → 触发 ManualReview） |
|
|
454
|
-
| `Compose` | 可叠加 | `business/<id>.tsx` 拼装多个上游原子 |
|
|
455
|
-
|
|
456
|
-
> 叠加规则：`Coexist` / `Fork` / `TokenOnly` / `ManualReview` 互斥（终结）；`Preset + Wrapper + Variant + Compose` 任意组合，叠加顺序内 → 外为 `variant > wrapper > preset`。
|
|
457
|
-
|
|
458
|
-
**AI 引导决策树（5 步闭环）**：
|
|
459
|
-
|
|
460
|
-
1. **读 staging meta** —— 让 CLI 帮拿（`teamix-evo ui upgrade` 输出 staging 路径），打开 `.teamix-evo/.upgrade-staging/<latest-ui-*>/meta.json` 阅读所有 entries 的 `id` / `recommendedModes` / `confidence` / `reasons` / `featureVector`。
|
|
461
|
-
2. **按主模式分组展示** —— 取每个 entry 的第一个 mode 作为分组键；列表给用户：
|
|
462
|
-
- `Coexist (3): button, dialog, dropdown-menu` → 双轨并存，会改 import 路径
|
|
463
|
-
- `Wrapper+Preset (2): card, badge` → 业务包装 + 默认值
|
|
464
|
-
- `TokenOnly (4): separator, label, ...` → 只需改 tokens.overrides.css
|
|
465
|
-
- `ManualReview (1): table` → 置信度 < 0.6，需要用户先看 diff
|
|
466
|
-
3. **每组逐一询问** —— 对每组先展示 `current.tsx` ↔ `incoming.tsx` 关键 diff（用户要看才展），再问“是否按推荐模式 promote？yes/no/调整模式”。
|
|
467
|
-
- 用户改模式时复述新 mode list，再调 `--modes` 参数。
|
|
468
|
-
- `Coexist` 分组要明确告诉用户：默认**不**重写既有 `import .../ui/<id>` 引用，加 `--migrate-imports` 才统改为 `legacy-<id>`。
|
|
469
|
-
4. **逐组调 promote-to-biz** —— 每组一次命令调用，传该组所有 id；先 `--dry-run` 看 FileChange 四桶（new/modified/deleted/backed-up），用户 OK 后去 dry-run 真写。
|
|
470
|
-
5. **收尾输出未处理 + import skipped 清单** —— 命令结束后复述：
|
|
471
|
-
- `manualReview: [...]` 让用户人工抉择（看 diff 或拆 family）
|
|
472
|
-
- `tokenOnly: [...]` 引导走 `tokens audit`
|
|
473
|
-
- `importRewrite.skipped: [{file, line, reason}]` 列出动态 import / 别名 export / 模板字符串这些 regex 重写不到的位置，让用户人工处理
|
|
474
|
-
- `failed: [...]`（如果有）逐条说明失败原因
|
|
475
|
-
|
|
476
|
-
**身份划分清单**：
|
|
477
|
-
|
|
478
|
-
- **CLI（`ui promote-to-biz`）**：执行备份、写 `business/`、回填 `ui/`、按 spec 重写 `src/**` 静态 import、改 manifest（promoted 资源记入虚拟包 `@teamix-evo/biz-ui-promoted`）。
|
|
479
|
-
- **AI（本 skill）**：读 meta、分组、展示 diff、征用户同意、转命令；**不**自己写文件、**不**自己改 import。
|
|
480
|
-
- **`teamix-evo-upgrade` skill**：管 §4d staging → src 的 1:1 替换；**不**做模式分流，本场景才做。
|
|
481
|
-
|
|
482
|
-
**不要**：
|
|
483
|
-
|
|
484
|
-
- 不要绕过 staging 直接调 `promote-to-biz`：CLI 拒收（命令依赖 staging meta）。
|
|
485
|
-
- 不要把 `Coexist` 当 `Replace` 用：默认双轨，旧 import **不**自动迁移，要 `--migrate-imports`；并且 export 默认前缀 `Legacy`，要 `--keep-original-names` 才保留原名。
|
|
486
|
-
- 不要忽略 `importRewrite.skipped`：那批位置 CLI 故意放弃，必须告诉用户人工处理（dynamic-import / 别名 re-export / 模板字符串）。
|
|
487
|
-
- 不要建议用户手改 `manifest.json`：promoted 登记由 CLI 写，污染了走 `restore`。
|
|
488
|
-
|
|
489
|
-
## 场景 5 · 卸载
|
|
227
|
+
## 卸载
|
|
490
228
|
|
|
491
229
|
**触发**:用户说"卸载 teamix-evo / remove the design system"。
|
|
492
230
|
|
|
493
|
-
| 范围 | 命令
|
|
494
|
-
| --------------------------------------------- |
|
|
495
|
-
| Tokens | `npx teamix-evo tokens uninstall [-y] [--keep-files] [--purge]`
|
|
496
|
-
| Skills | `npx teamix-evo skills uninstall [-y]`
|
|
497
|
-
| (UI 不提供卸载,组件源码用户拥有 → 用户手动删) |
|
|
231
|
+
| 范围 | 命令 |
|
|
232
|
+
| --------------------------------------------- | ----------------------------------------------------------------------- |
|
|
233
|
+
| Tokens | `npx teamix-evo@latest tokens uninstall [-y] [--keep-files] [--purge]` |
|
|
234
|
+
| Skills | `npx teamix-evo@latest skills uninstall [-y]` |
|
|
235
|
+
| (UI 不提供卸载,组件源码用户拥有 → 用户手动删) | |
|
|
498
236
|
|
|
499
237
|
`tokens uninstall` 默认保留 `frozen` + `managed` 文件以保护用户编辑;`--keep-files` 完全保留物理文件只清 manifest;`--purge` 连 `frozen` 文件也删除。
|
|
500
238
|
|
|
501
|
-
## 场景 6 · 旧工程迁移重建（Old-Project Migration）
|
|
502
|
-
|
|
503
|
-
**触发**：用户在已初始化的 teamix-evo 项目中说"迁移旧项目 / 重建老工程 / 把旧项目搬过来 / 旧项目分析 / 旧系统翻新 / legacy migration / migrate old project / rebuild from existing project / refactor from old codebase / 从旧项目迁移过来 / 用旧项目做参考重建 / 分析旧项目并迁移"。
|
|
504
|
-
|
|
505
|
-
> **前提**：当前目录已有 `.teamix-evo/config.json`（即已走完场景 1/2/3 的初始化）。若当前目录未初始化，先引导用户完成初始化再回到本场景。
|
|
506
|
-
|
|
507
|
-
### AI 行为协议（三阶段闭环）
|
|
508
|
-
|
|
509
|
-
#### Phase A · 信息收集
|
|
510
|
-
|
|
511
|
-
1. **询问三轨材料** — 一次性向用户索取迁移所需的三轨材料：
|
|
512
|
-
|
|
513
|
-
a. **旧项目源码路径** — 旧项目的**绝对路径**（`<old-path>`）
|
|
514
|
-
b. **Repo-wiki** — 旧项目的 repo-wiki（路径或确认已生成）
|
|
515
|
-
c. **页面截图目录** — 用户预先准备的页面截图目录路径
|
|
516
|
-
|
|
517
|
-
向用户提示截图准备建议话术：
|
|
518
|
-
|
|
519
|
-
> "请使用默认浏览器访问待迁移项目 URL，对所有页面以及页面的弹窗、抽屉进行截图，按页面路由为文件夹名字落地，并提供该截图位置目录。"
|
|
520
|
-
|
|
521
|
-
截图目录结构建议（用户通过 Qoder 工作区截图存放）：
|
|
522
|
-
|
|
523
|
-
```
|
|
524
|
-
<screenshots-dir>/
|
|
525
|
-
├── home/
|
|
526
|
-
│ ├── default.png
|
|
527
|
-
│ └── dialog-create.png
|
|
528
|
-
├── list/
|
|
529
|
-
│ ├── default.png
|
|
530
|
-
│ ├── drawer-detail.png
|
|
531
|
-
│ └── dialog-delete.png
|
|
532
|
-
└── settings/
|
|
533
|
-
└── default.png
|
|
534
|
-
```
|
|
535
|
-
|
|
536
|
-
> ⚠️ **AI 不执行截图操作**。截图由用户在 Qoder 工作区自行完成并提供目录路径。AI 仅使用用户提供的截图作为视觉参考。
|
|
537
|
-
|
|
538
|
-
2. **检测 repo-wiki** — 检查 `<old-path>/.qoder/repowiki/` 是否存在且非空：
|
|
539
|
-
- 存在 → 进入步骤 3。
|
|
540
|
-
- 不存在 → 告知用户："旧项目尚未生成 repo-wiki，请先在旧项目目录使用 Qoder 生成 repo-wiki，完成后告诉我。"等待用户确认后重检。
|
|
541
|
-
3. **读取 repo-wiki** — 增量读取 `<old-path>/.qoder/repowiki/` 目录内容。优先读中文版（`repowiki/zh/`），其次英文版（`repowiki/en/`）。按文件名语义识别：
|
|
542
|
-
|
|
543
|
-
- 项目总览 / 概述
|
|
544
|
-
- 目录结构 / 模块划分
|
|
545
|
-
- 页面 / 路由清单
|
|
546
|
-
- API 端点清单
|
|
547
|
-
- 数据模型 / 类型定义
|
|
548
|
-
- 依赖清单
|
|
549
|
-
|
|
550
|
-
> 不一次性读完全部内容（token 预算有限）。先读概览 + 路由，后续按需深入。
|
|
551
|
-
|
|
552
|
-
4. **检测截图目录** — 检查用户提供的截图目录是否存在且非空：
|
|
553
|
-
- 存在且含截图 → 记录路径，进入步骤 5。
|
|
554
|
-
- 不存在或为空 → 告知用户截图目录不可用，请先按建议完成截图后再继续。
|
|
555
|
-
5. **补充读取**（若 repo-wiki 不完整）— 直接读旧项目的：
|
|
556
|
-
- `package.json`（依赖 / scripts）
|
|
557
|
-
- 路由配置文件（`src/routes/`、`src/router/`、`pages/` 目录等）
|
|
558
|
-
- 目录结构（`ls src/`）
|
|
559
|
-
6. **识别旧项目技术栈** — 从依赖和代码判断，记录以下维度：
|
|
560
|
-
- UI 框架（antd / element-ui / arco-design / mui / naive-ui / 自研）
|
|
561
|
-
- 路由方案（react-router / vue-router / next.js / umi）
|
|
562
|
-
- 状态管理（redux / mobx / zustand / pinia / vuex）
|
|
563
|
-
- HTTP 客户端（axios / fetch / umi-request / swr / react-query）
|
|
564
|
-
- 构建工具（webpack / vite / umi / next / create-react-app）
|
|
565
|
-
|
|
566
|
-
#### Phase B · 计划生成
|
|
567
|
-
|
|
568
|
-
6. **生成迁移计划文件** — 写入 `.teamix-evo/migrate-plan.md`，格式如下：
|
|
569
|
-
|
|
570
|
-
````markdown
|
|
571
|
-
# Migration Plan
|
|
572
|
-
|
|
573
|
-
## ❗ 执行规则（每次读取本文件时必须重新确认）
|
|
574
|
-
|
|
575
|
-
1. **Token 映射查表** — 每迁移一个页面前，必须先读取 `.teamix-evo/migrate-token-mapping.md`，所有旧项目 CSS 变量按实际像素值映射为新项目 Tailwind class。禁止根据变量名称“猜测”对应关系。
|
|
576
|
-
2. **组件与代码规范**（摘自 design-{variant} + code-{variant} skill，完整规则见关键文件索引）
|
|
577
|
-
- **组件选用优先级（不得跳级）**：`./rules/` 已定义组件 → `@teamix-evo/ui` 原子组件拼装 → 自定义实现（需 `<!-- CUSTOM: 原因 -->` 标注）
|
|
578
|
-
- **组件尺寸**：无特殊说明时一律使用 default 尺寸，不主动用 sm
|
|
579
|
-
- **核心 UI 组件速查**：Card / Table / Badge / Separator / Tabs / ToggleGroup / Button / Tag / Dialog / Sheet / Select / Input / Empty / Spinner / Tooltip
|
|
580
|
-
- **Token 引用**：所有视觉属性必须引用 Token，禁止硬编码色值 / 间距 / 字号
|
|
581
|
-
- **代码分层**：pages（页面组件）→ hooks（数据逻辑）→ services（API 封装）→ types（类型定义）
|
|
582
|
-
- **reuse-first**：优先复用 `@teamix-evo/ui` 已有组件，禁止重复造轮子
|
|
583
|
-
3. **三轨齐备** — 进入任何页面实现前必须源码 + repo-wiki + 截图全部确认就绪（截图由用户预先准备，AI 只做确认）。
|
|
584
|
-
4. **Token 合法性自检** — 写完代码后扫描所有 Tailwind class，确认在新项目有效。
|
|
585
|
-
5. **新架构骨架层检查** — 迁移不仅是“翻译旧代码”，还必须“适配新架构的标准模式”。新架构有一套完整的页面骨架层级（`PageShell → OpPageContainer → PageHeader → 内容`），这些组件在旧项目中完全不存在（旧项目用自定义 `<h1>`、内联样式或散落 CSS 实现），三轨对照不会发现它们。必须主动查阅 design skill 和 biz-ui 组件的 JSDoc 获取标准骨架用法：
|
|
586
|
-
- **Layout 层**：检查 `src/components/biz-ui/` 是否存在页面容器组件（如 `OpPageContainer`），在 `<Outlet />` 外统一包裹，使所有页面自动获得容器效果
|
|
587
|
-
- **每页面层**：检查容器组件的 JSDoc / 源码中是否定义了标配的子组件模式（如 `header={<PageHeader>...</PageHeader>}` 是每页标配），必须按规范使用而非省略
|
|
588
|
-
|
|
589
|
-
# ❄️ 冷启动恢复指南（上下文丢失 / 新会话接手时执行）
|
|
590
|
-
|
|
591
|
-
如果你是一个新会话被要求"继续迁移"，按以下顺序恢复上下文：
|
|
592
|
-
|
|
593
|
-
1. 读取本文件 `.teamix-evo/migrate-plan.md` — 获取进度、元数据、执行规则
|
|
594
|
-
2. 读取 `.teamix-evo/migrate-token-mapping.md` — 加载 token 映射表
|
|
595
|
-
3. **读取 skill 并提取页面级约束**（路径见下方「关键文件索引」）：
|
|
596
|
-
- 读取 **Design skill** → 重点关注 §6.1 组件选用优先级、§5 通用组件分层、§6.5 降级拼装规则
|
|
597
|
-
- 读取 **Code skill** → 重点关注 reuse-first.md、file-structure.md、api-layering.md
|
|
598
|
-
- 读取 **Manage skill** §场景 6 → 获取迁移执行协议的逐条步骤
|
|
599
|
-
- **提取原则**：每个待迁移页面的每个 UI 元素，先在 `@teamix-evo/ui` 组件库（`src/components/ui/`）中查找对应组件，找到则直接使用；找不到才允许自定义实现
|
|
600
|
-
4. 查看 Progress 区块 — 找到 **Current phase** 所指的 Phase，在该 Phase 中定位第一个未完成的 `[ ]` 条目（不要回头处理更早 Phase 中被 pilot 模式有意推迟的条目）
|
|
601
|
-
5. 确认三轨材料 — 对当前页面确认源码 + repo-wiki + 截图三轨就绪（截图目录见 Metadata → Screenshots dir）
|
|
602
|
-
6. 开始实现 — 从第一个未完成条目继续
|
|
603
|
-
|
|
604
|
-
> 注：截图由用户预先准备完成，AI 无需执行截图操作。若截图目录中缺少当前页面截图，暂停并请用户补充。
|
|
605
|
-
|
|
606
|
-
## 关键文件索引
|
|
607
|
-
|
|
608
|
-
| 文件 | 路径 | 用途 |
|
|
609
|
-
| ------------ | --------------------------------------------------------- | ------------------------------ |
|
|
610
|
-
| 迁移计划 | `.teamix-evo/migrate-plan.md` | 进度跟踪 + 执行规则（本文件） |
|
|
611
|
-
| Token 映射表 | `.teamix-evo/migrate-token-mapping.md` | CSS 变量 → Tailwind class 映射 |
|
|
612
|
-
| 截图目录 | 见 Metadata → Screenshots dir | 用户提供的页面截图目录 |
|
|
613
|
-
| Manage skill | `.teamix-evo/skills/teamix-evo-manage/SKILL.md` | 迁移执行协议（场景 6） |
|
|
614
|
-
| Code skill | `.teamix-evo/skills/teamix-evo-code-{variant}/SKILL.md` | 代码规范门控 |
|
|
615
|
-
| Design skill | `.teamix-evo/skills/teamix-evo-design-{variant}/SKILL.md` | 设计/布局规范 |
|
|
616
|
-
| 旧项目源码 | 见 Metadata → Source | 源码轨参考 |
|
|
617
|
-
| 旧项目 Wiki | 见 Metadata → Source 同级 `repo-wiki/` | Wiki 轨参考 |
|
|
618
|
-
|
|
619
|
-
> ℹ️ `{variant}` 请替换为 Metadata 中的 **Target variant** 值（如 `opentrek` 或 `uni-manager`）。实际生成时会自动填入真实值。
|
|
620
|
-
|
|
621
|
-
## Progress
|
|
622
|
-
|
|
623
|
-
- **Status**: in-progress
|
|
624
|
-
- **Mode**: <full | pilot>
|
|
625
|
-
- **Pilot pages**: <页面名列表，仅 pilot 模式填写>
|
|
626
|
-
- **Pilot 说明**: <pilot 模式下仅执行上述 Phase 涉及的条目。更早 Phase 中标 `[ ]` 的条目是有意推迟到 pilot 验证通过后再补的，当前不需要处理>
|
|
627
|
-
- **Completed**: 0 / <总条目数>
|
|
628
|
-
- **Current phase**: Phase 0 — Global Infrastructure
|
|
629
|
-
- **Last updated**: <ISO 时间戳>
|
|
630
|
-
|
|
631
|
-
## Metadata
|
|
632
|
-
|
|
633
|
-
- **Source**: <旧项目绝对路径>
|
|
634
|
-
- **Target variant**: <当前项目 variant>
|
|
635
|
-
- **Generated**: <ISO 时间戳>
|
|
636
|
-
- **Old stack**: <框架> + <UI 库> + <路由> + <HTTP 客户端> + <状态管理>
|
|
637
|
-
- **Screenshots dir**: <用户提供的截图目录绝对路径>
|
|
638
|
-
|
|
639
|
-
## Component Mapping (AI via MCP find_components 动态生成)
|
|
640
|
-
|
|
641
|
-
| Old | New (teamix-evo) | Notes |
|
|
642
|
-
| --- | ---------------- | ----- |
|
|
643
|
-
| ... | ... | ... |
|
|
644
|
-
|
|
645
|
-
## Phase 0: Global Infrastructure
|
|
646
|
-
|
|
647
|
-
- [ ] **清理脚手架示例页面** — 删除 `create-teamix-evo` 生成的 demo 页面（`src/pages/home/`、`src/pages/list/`、`src/pages/detail/`、`src/pages/form/` 等）及关联的 services / hooks / types / routes 条目
|
|
648
|
-
[ ] **Layout（吸顶 + 左导 + 页面容器）** — ❗ 优先级最高。全局壳重构：吸顶 Header、左侧边栏 Sidebar、面包屑、内容区布局。先保证通用性内容正确，再进入具体页面。
|
|
649
|
-
|
|
650
|
-
> Layout 也需要截图参考：确认用户截图目录中 `layout/` 文件夹是否包含吸顶和左导截图（`header.png` + `sidebar.png`），作为视觉还原参考。若缺失，提示用户补充。
|
|
651
|
-
|
|
652
|
-
> ⚠️ **新架构骨架层检查**：新架构的页面骨架是 `PageShell → OpPageContainer → PageHeader → 内容`，旧项目不会有这些抽象。必须主动检查 biz-ui 组件源码和 JSDoc 获取标准用法：
|
|
653
|
-
>
|
|
654
|
-
> - Layout 层：`<Outlet />` 外套 `OpPageContainer`（灰底白卡）
|
|
655
|
-
> - 每页面层：`OpPageContainer` 的 `header` prop 传入 `<PageHeader>`（页面标题 + Tabs 等）
|
|
656
|
-
> - 这些信息三轨对照找不到，只能从 design skill 和 biz-ui 组件 JSDoc 中获取
|
|
657
|
-
|
|
658
|
-
- [ ] **静态资源迁移** — 将旧项目的静态资源（图片 / 视频 / 动效 / 字体 / SVG / 音频等）拷贝到新项目对应目录（如 `public/` 或 `src/assets/`），保持相对引用路径一致
|
|
659
|
-
- [ ] **Routing** — 路由结构搭建（基于旧项目路由表重建）
|
|
660
|
-
- [ ] **API client** — HTTP 客户端 + 拦截器
|
|
661
|
-
- [ ] **Auth** — 鉴权流程
|
|
662
|
-
- [ ] **Global state** — 全局状态管理
|
|
663
|
-
- [ ] **Theme & 全局 CSS 基线** — 对比旧项目的全局样式（body / html / :root），将以下配置对齐到新项目：
|
|
664
|
-
|
|
665
|
-
- 字体族（font-family）— 若旧项目使用自定义字体（如 Geist / Inter），需引入字体文件并配置 @font-face
|
|
666
|
-
- 字体平滑（-webkit-font-smoothing: antialiased）
|
|
667
|
-
- 字体特性（font-feature-settings）
|
|
668
|
-
- 基础行高、字号、颜色
|
|
669
|
-
- 其他全局 reset 样式
|
|
670
|
-
- tokens.overrides.css 主题变量覆盖
|
|
671
|
-
|
|
672
|
-
> 这些全局 CSS 影响所有页面的视觉表现，必须在进入具体页面迁移前完成。直接沿用旧项目的配置，无需询问用户。完成后在进度汇报中简要记录已对齐的项目（如“已对齐字体族 Geist Variable、antialiased、font-feature-settings”），通知用户即可。
|
|
673
|
-
|
|
674
|
-
- [ ] **Token 映射表** — 提取旧项目所有 CSS 变量 / design tokens，解析其实际值，建立与新项目 Tailwind class 的映射表，并写入 `.teamix-evo/migrate-token-mapping.md`。示例：
|
|
675
|
-
|
|
676
|
-
```markdown
|
|
677
|
-
| 旧项目 Token | 实际值 | 新项目 Tailwind Class |
|
|
678
|
-
| ---------------- | ------- | ------------------------- |
|
|
679
|
-
| --font-size-base | 12px | text-xs |
|
|
680
|
-
| --font-size-lg | 14px | text-sm |
|
|
681
|
-
| --font-size-xl | 16px | text-base |
|
|
682
|
-
| --font-size-2xl | 18px | text-lg |
|
|
683
|
-
| --color-primary | #1677ff | text-primary / bg-primary |
|
|
684
|
-
| --border-radius | 4px | rounded |
|
|
685
|
-
| --spacing-sm | 8px | gap-2 / p-2 |
|
|
686
|
-
```
|
|
687
|
-
|
|
688
|
-
映射表必须覆盖以下维度：
|
|
689
|
-
|
|
690
|
-
- **字号** — 所有 font-size 变量
|
|
691
|
-
- **间距** — spacing / padding / margin / gap 变量
|
|
692
|
-
- **圆角** — border-radius 变量
|
|
693
|
-
- **颜色** — 旧项目自定义色值变量（如 `--color-data-8`、`--color-brand-3`）→ 检查新项目 `tokens.theme.css` 中是否存在对应 utility。若不存在，标注为「❗ 无对应」并建议替代方案（如用最接近的语义色或 CSS 变量内联）
|
|
694
|
-
- **阴影** — box-shadow 变量
|
|
695
|
-
|
|
696
|
-
> ⚠️ **硬约束：禁止按名称猜测映射。** AI 必须解析旧项目 CSS 变量的实际像素值，再映射到新项目对应的 Tailwind class。例如 `--font-size-lg = 14px` 应映射为 `text-sm`（而不是名称相似的 `text-lg`）。
|
|
697
|
-
> 后续 Phase C 逐页实现时，所有涉及旧 token 的代码必须查询此表来确定正确的 Tailwind class，不得凭名称直觉映射。
|
|
698
|
-
> 对于映射表中标注为「❗ 无对应」的 token，在写代码时必须使用替代方案，不得直接复制旧项目的 class 名。
|
|
699
|
-
|
|
700
|
-
## Phase 1: <页面名> (complexity: <simple|medium|complex>)
|
|
701
|
-
|
|
702
|
-
> ⚠️ 执行前检查：① 已读取 `migrate-token-mapping.md` ② 已确认§2 组件与代码规范（组件优先级 / 尺寸 / reuse-first） ③ 三轨已采集
|
|
703
|
-
|
|
704
|
-
- Route: `<路由路径>`
|
|
705
|
-
- [ ] **<子任务>** — <描述> (<使用组件>)
|
|
706
|
-
- [ ] **API integration** — <接口列表>
|
|
707
|
-
|
|
708
|
-
## Phase N: ...
|
|
709
|
-
````
|
|
710
|
-
|
|
711
|
-
**组件映射生成规则**：通过 MCP `find_components` / `list_components` 查询 teamix-evo 注册表，逐个匹配旧项目使用的 UI 组件，动态填写映射表。
|
|
712
|
-
|
|
713
|
-
7. **展示计划摘要** — 向用户复述：
|
|
714
|
-
|
|
715
|
-
- 总页面数
|
|
716
|
-
- 按复杂度分布（简单 / 中等 / 复杂）
|
|
717
|
-
- 建议执行顺序
|
|
718
|
-
- 询问用户是否调整顺序、跳过某些页面、或补充遗漏页面
|
|
719
|
-
|
|
720
|
-
8. **确认迁移节奏** — 向用户提问：
|
|
721
|
-
|
|
722
|
-
> “您希望先迁移几个页面验证效果，还是直接开始全量迁移？”
|
|
723
|
-
|
|
724
|
-
- **先验证（推荐）**：用户选择 1–3 个代表性页面（建议包含一个简单页 + 一个复杂页），先做完这几个让用户检验代码质量、视觉还原度、组件映射质量后再继续剩余页面
|
|
725
|
-
- **全量迁移**：按计划顺序逐页执行，每完成一个 Phase 后向用户汇报
|
|
726
|
-
|
|
727
|
-
在 `migrate-plan.md` 顶部 Progress 区块记录用户选择：
|
|
728
|
-
|
|
729
|
-
- `Mode: pilot` + `Pilot pages: <页面名列表>` — 验证模式，仅执行指定页面
|
|
730
|
-
- `Mode: full` — 全量模式
|
|
731
|
-
|
|
732
|
-
> pilot 模式完成后，向用户确认：“验证页面已完成，是否继续迁移剩余页面？”用户确认后将 Mode 改为 `full` 并继续。
|
|
733
|
-
|
|
734
|
-
> Phase B → Phase C 之间**必须**有用户的明确确认（go-ahead）。
|
|
735
|
-
|
|
736
|
-
#### Phase C · 执行
|
|
737
|
-
|
|
738
|
-
9. **读取当前进度** — 读 `.teamix-evo/migrate-plan.md` 顶部 Progress 区块。若 Status 为 `done` → 告知用户迁移已全部完成。否则找到第一个未完成（`[ ]`）的条目。
|
|
739
|
-
10. **三轨确认（每页开发前必做）** — 进入一个页面的开发前，必须确认三轨材料均已就绪：
|
|
740
|
-
a. **源码轨**：读旧项目该页面的全部源文件（页面组件 + 子组件 + 页面内弹窗 Dialog / 抽屉 Drawer / 确认框等）
|
|
741
|
-
b. **Wiki 轨**：读旧项目 repo-wiki 中该页面相关的描述（功能说明、业务规则、数据流）
|
|
742
|
-
c. **截图轨**：检查用户提供的截图目录中 `<screenshots-dir>/<page-route>/` 是否已有该页面截图。
|
|
743
|
-
|
|
744
|
-
- **已有截图** → 直接读取作为视觉参考。
|
|
745
|
-
- **截图缺失** → 暂停并告知用户："<页面名> 缺少截图，请补充后告诉我。"等待用户补充后继续。
|
|
746
|
-
|
|
747
|
-
**截图存放约定**：用户在 Qoder 工作区预先准备，按页面路由为文件夹名，存放在用户提供的截图目录下。文件名约定：
|
|
748
|
-
|
|
749
|
-
- `default.png` — 页面默认态
|
|
750
|
-
- `dialog-<名称>.png` — 弹窗打开态
|
|
751
|
-
- `drawer-<名称>.png` — 抽屉打开态
|
|
752
|
-
- `state-empty.png` / `state-loading.png` / `state-error.png` — 特殊状态
|
|
753
|
-
|
|
754
|
-
截图范围须覆盖：
|
|
755
|
-
|
|
756
|
-
- 页面默认态（列表 / 表单 / 详情等主视图）
|
|
757
|
-
- 页面内所有弹窗（Dialog / Modal）的打开态
|
|
758
|
-
- 页面内所有抽屉（Drawer / Sheet）的打开态
|
|
759
|
-
- 关键交互状态（空态 / 加载态 / 错误态，若能触发）
|
|
760
|
-
|
|
761
|
-
> **AI 不执行截图**：截图由用户在迁移开始前通过 Qoder 工作区一次性完成（访问旧项目所有页面、弹窗、抽屉截图），迁移过程中 AI 仅读取已有截图作为视觉参考。
|
|
762
|
-
|
|
763
|
-
> ⚠️ **硬约束：三轨齐备方可动手。** AI 必须在源码、wiki、截图三轨全部确认就绪后，才能开始该页面的实现。**AI 不得自行跳过截图轨**——只有用户明确要求「跳过截图」时，才可降级为两轨模式，并标注"⚠️ 无截图参考，视觉还原需用户人工校对"。
|
|
764
|
-
|
|
765
|
-
三轨确认后，向用户确认："<页面名> 的源码、repo-wiki、截图三轨已确认就绪，开始实现？"用户确认后才动手。
|
|
766
|
-
|
|
767
|
-
11. **逐条实现** — 对每个 checklist 条目：
|
|
768
|
-
a. 通过 MCP `find_components` / `get_component_meta` 查询可用组件
|
|
769
|
-
b. **读取 code/design skill 并确认关键约束** — 必须先读取 `teamix-evo-code-{variant}` 和 `teamix-evo-design-{variant}` 的 SKILL.md，提取组件选用优先级（§6.1）、尺寸规范、reuse-first 等关键规则。**禁止未读取就开始写代码**。若当前会话已读取过且上下文未丢失，可跳过重复读取
|
|
770
|
-
c. 遵循 `teamix-evo-code-{variant}` skill 规范生成代码（reuse-first / file-structure / api-layering）
|
|
771
|
-
d. 遵循 `teamix-evo-design-{variant}` skill 规范处理页面布局，参照截图还原视觉
|
|
772
|
-
e. **Token 映射查表** — 写代码时遇到旧项目的 CSS 变量 / class，必须查询 `.teamix-evo/migrate-token-mapping.md` 确定正确的 Tailwind class，禁止凭名称直觉映射
|
|
773
|
-
f. **静态资源处理** — 实现过程中若发现页面引用了图片 / 视频 / 动效 / 字体等资源，必须从旧项目对应路径拷贝到新项目，**禁止仅报告“缺少资源”而不动手拷贝**
|
|
774
|
-
g. **Token 合法性自检** — 写完代码后，扫描本次生成的所有 Tailwind class，确认每个都在新项目 `tokens.theme.css` 中有对应变量或是 Tailwind 标准 utility。若发现无效 class（如 `bg-data-8` 在新项目不存在），必须立即替换为有效的替代方案
|
|
775
|
-
h. 完成后更新 `.teamix-evo/migrate-plan.md`：将对应条目标记为 `[x]`，同步更新顶部 Progress（Completed 计数 + Current phase + Last updated）
|
|
776
|
-
i. 向用户汇报进度，格式：`✅ <条目名> 完成（<已完成数>/<总数>）| 当前阶段：<Phase 名>`
|
|
777
|
-
12. **验证** — 每完成一个页面后：
|
|
778
|
-
- 列出该页面的功能检查点（从旧代码提取的关键交互：CRUD / 筛选 / 分页 / 权限 / 弹窗流程等）
|
|
779
|
-
- 若有截图，建议用户对比新旧页面视觉差异
|
|
780
|
-
- 跑 `pnpm typecheck` 确认零类型错误
|
|
781
|
-
|
|
782
|
-
#### Phase D · 全量 Review
|
|
783
|
-
|
|
784
|
-
13. **全部页面完成后** — 当 Progress 中 Completed 等于总条目数时：
|
|
785
|
-
- 将 Status 更新为 `review`
|
|
786
|
-
- 向用户提示："所有页面已迁移完成，建议进行一轮整体 review。是否现在开始？"
|
|
787
|
-
- 用户确认后，逐页面列出 review 检查点：
|
|
788
|
-
- 功能完整性（对照旧项目关键流程）
|
|
789
|
-
- 视觉还原度（对照截图）
|
|
790
|
-
- 路由可达性（所有页面是否串通）
|
|
791
|
-
- 全局一致性（Layout / 导航 / 权限守卫是否统一）
|
|
792
|
-
- review 全部通过后，将 Status 更新为 `done`
|
|
793
|
-
14. **会话恢复** — 若 AI 进入新会话：
|
|
794
|
-
- 读 `.teamix-evo/migrate-plan.md` — 文件顶部包含「冷启动恢复指南」，按其 6 步顺序恢复上下文
|
|
795
|
-
- 读截图目录（Metadata → Screenshots dir），确认已有哪些页面的截图可作为视觉参考
|
|
796
|
-
- `in-progress` → 定位第一个 `[ ]` 条目，确认三轨材料（源码 + wiki + 截图）就绪后从断点处继续
|
|
797
|
-
- `review` → 进入 Phase D review 流程
|
|
798
|
-
- `done` → 告知用户迁移已完成
|
|
799
|
-
|
|
800
|
-
### 身份划分清单
|
|
801
|
-
|
|
802
|
-
- **AI（本 skill — manage）**：询问路径 → 检测 repo-wiki → 生成/管理 `migrate-plan.md` → 进度追踪 → 会话恢复定位。
|
|
803
|
-
- **AI（`teamix-evo-code-{variant}`）**：生成每页实际代码时遵循 reuse-first / file-structure / api-layering 规范。Phase C 执行时自动应用。
|
|
804
|
-
- **AI（`teamix-evo-design-{variant}`）**：页面级布局 / 视觉设计决策。迁移新页面时并行参考。
|
|
805
|
-
- **用户**：提供旧项目路径 / 确认 repo-wiki 已生成 / 审核迁移计划 / 可选提供运行 URL / 确认每页实现结果。
|
|
806
|
-
- **CLI**：无新命令。执行阶段复用 `teamix-evo ui add <id>`（若发现有未安装的 UI 组件需要补装）。
|
|
807
|
-
|
|
808
|
-
### 边缘情况
|
|
809
|
-
|
|
810
|
-
| 情况 | 处理 |
|
|
811
|
-
| ------------------------------------ | ------------------------------------------------------------------------------ |
|
|
812
|
-
| repo-wiki 不存在 | 提示用户先在旧项目执行 repo-wiki 生成命令 |
|
|
813
|
-
| 截图目录为空或缺少页面截图 | 暂停并提示用户补充截图，不得跳过或自行执行截图 |
|
|
814
|
-
| repo-wiki 不完整（缺路由/API 等） | 直接读旧项目源码补充（路由配置 / package.json / 目录结构） |
|
|
815
|
-
| 旧项目是 Vue / Angular（非 React） | 正常分析，概念映射无框架壁垒（路由 → 路由、组件 → 组件），新项目统一生成 React |
|
|
816
|
-
| 旧项目是 monorepo | 让用户指定具体 package 路径作为 `<old-path>` |
|
|
817
|
-
| 页面极复杂（>500 行、多子路由） | 拆为多个 checklist 子条目，标记 complexity: complex |
|
|
818
|
-
| `.teamix-evo/migrate-plan.md` 已存在 | 询问用户三选一：(a) 恢复进度继续、(b) 重新生成（覆盖）、(c) 查看当前计划 |
|
|
819
|
-
| 新项目已有部分页面 | 跳过已存在的页面，或标记为 verify-only |
|
|
820
|
-
| token 预算不足以完成全部分析 | 停止读取，基于已有信息生成部分计划，标注"后续会话补充" |
|
|
821
|
-
|
|
822
|
-
### 不要
|
|
823
|
-
|
|
824
|
-
- **不要**在无 repo-wiki 且源码量大时一次性读完全部文件 — 分批按需读取。
|
|
825
|
-
- **不要**跳过 Phase B 直接写代码 — 必须先生成 `migrate-plan.md` 让用户审核确认。
|
|
826
|
-
- **不要**复制旧项目的组件源码到新项目 — 走 reuse-first 查 `@teamix-evo/ui` 注册表匹配。
|
|
827
|
-
- **但可以修改业务组件（biz-ui）** — `src/components/biz-ui/` 下的组件（如 `op-sidebar`、`page-header`、`op-layout` 等）是 `frozen` 策略，用户拥有所有权。当现有业务组件无法满足迁移需求（缺少 slot、不支持某布局、缺少交互能力）时，AI **应当直接修改 biz-ui 组件源码**，而不是在页面层面 hack。修改前告知用户“当前 biz-ui 组件 <X> 不支持 <能力>，我将直接增强它”。
|
|
828
|
-
- ✅ 可修改：`src/components/biz-ui/**`（用户拥有，frozen）
|
|
829
|
-
- ❌ 不可修改：`src/components/ui/**`（teamix-evo 接管，需走 `ui upgrade`）
|
|
830
|
-
- **不要**搬迁旧项目的样式体系（CSS-in-JS / less / sass / antd theme） — 新项目用 design tokens + Tailwind v4。
|
|
831
|
-
- **不要**原样搬入旧 node_modules 依赖 — 仅迁移业务必需的第三方库（如图表库、富文本编辑器）。
|
|
832
|
-
- **不要**在用户未确认计划前开始实现。
|
|
833
|
-
- **不要**试图单次会话完成全部迁移 — 大项目分多次会话，每次完成若干页面后让用户验证。
|
|
834
|
-
- **不要**破坏 `migrate-plan.md` 的 `- [ ]` / `- [x]` 格式 — 后续会话靠它恢复进度。
|
|
835
|
-
- **不要**修改旧项目的任何文件 — 旧项目只读。
|
|
836
|
-
|
|
837
239
|
## 配置文件(信息性)
|
|
838
240
|
|
|
839
241
|
| 路径 | 所有者 | 说明 |
|
|
@@ -846,15 +248,15 @@ npx teamix-evo ui promote-to-biz --staging-dir <path> # 指定 staging 目录
|
|
|
846
248
|
|
|
847
249
|
## 常见错误与恢复路径(P8 — failures must be observable)
|
|
848
250
|
|
|
849
|
-
| 症状 | 原因 | 恢复路径
|
|
850
|
-
| -------------------------------------------------- | ------------------------------------------------------ |
|
|
851
|
-
| `Unknown tokens variant "..."` | 拼写错误或上游未发布该 variant | `npx teamix-evo tokens list-variants` 列出当前可用
|
|
852
|
-
| `Target directory already contains a .teamix-evo/` |
|
|
853
|
-
| `UI not initialized`(跑 `ui add` 时) | 未先跑 `ui init` | `npx teamix-evo ui init -y` 然后再 `ui add`
|
|
854
|
-
| Vite/Tailwind 跑起来没样式 | `src/index.css` 缺少 tokens / Tailwind 导入 | 检查 `src/index.css` 的 `@import` 顺序
|
|
855
|
-
| Skills 在 IDE 不触发 | `.qoder/skills/` 或 `.claude/skills/` 漂移 | `npx teamix-evo skills doctor` 然后 `skills sync`
|
|
856
|
-
| 想完全回退 `init` / `switch` 这次执行 | partial / 升级后想撤销到执行前状态 | `teamix-evo restore --list`
|
|
857
|
-
| `init` 卡在多选 IDE / wizard 环节 | @clack multiselect 交互不熟悉(空格=切换选中,回车=提交) | 命令加 `-y` 跳过全部交互（推荐）；或在 multiselect 界面用 `空格` 切换选项、`回车` 提交
|
|
251
|
+
| 症状 | 原因 | 恢复路径 |
|
|
252
|
+
| -------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
|
|
253
|
+
| `Unknown tokens variant "..."` | 拼写错误或上游未发布该 variant | `npx teamix-evo@latest tokens list-variants` 列出当前可用 |
|
|
254
|
+
| `Target directory already contains a .teamix-evo/` | 在已装目录再跑 `init` | init 每步幂等短路，直接重跑 `teamix-evo@latest init` 即可；或使用 `teamix-evo update` |
|
|
255
|
+
| `UI not initialized`(跑 `ui add` 时) | 未先跑 `ui init` | `npx teamix-evo@latest ui init -y` 然后再 `ui add` |
|
|
256
|
+
| Vite/Tailwind 跑起来没样式 | `src/index.css` 缺少 tokens / Tailwind 导入 | 检查 `src/index.css` 的 `@import` 顺序 |
|
|
257
|
+
| Skills 在 IDE 不触发 | `.qoder/skills/` 或 `.claude/skills/` 漂移 | `npx teamix-evo@latest skills doctor` 然后 `skills sync` |
|
|
258
|
+
| 想完全回退 `init` / `switch` 这次执行 | partial / 升级后想撤销到执行前状态 | `npx teamix-evo@latest restore --list` 看 snapshot,然后 `restore <ts>`（回滚自身可逆） |
|
|
259
|
+
| `init` 卡在多选 IDE / wizard 环节 | @clack multiselect 交互不熟悉(空格=切换选中,回车=提交) | 命令加 `-y` 跳过全部交互（推荐）；或在 multiselect 界面用 `空格` 切换选项、`回车` 提交 |
|
|
858
260
|
|
|
859
261
|
<!-- teamix-evo:managed:end id="core" -->
|
|
860
262
|
|