@teamix-evo/skills 0.7.0 → 0.8.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/manifest.json +2 -1
- package/package.json +2 -2
- package/src/teamix-evo-code-opentrek/reuse-first.md +2 -2
- package/src/teamix-evo-code-uni-manager/reuse-first.md +2 -2
- package/src/teamix-evo-design-opentrek/checklist.md +19 -21
- package/src/teamix-evo-design-uni-manager/checklist.md +18 -23
- package/src/teamix-evo-manage/SKILL.md +118 -34
- package/src/teamix-evo-upgrade/SKILL.md +16 -4
package/manifest.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@teamix-evo/skills",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"description": "Skills (AI IDE capabilities) for Teamix Evo",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
"devDependencies": {
|
|
13
13
|
"@clack/prompts": "^0.8.0",
|
|
14
14
|
"tsx": "^4.0.0",
|
|
15
|
-
"@teamix-evo/registry": "0.
|
|
15
|
+
"@teamix-evo/registry": "0.9.0"
|
|
16
16
|
},
|
|
17
17
|
"publishConfig": {
|
|
18
18
|
"access": "public",
|
|
@@ -64,7 +64,7 @@
|
|
|
64
64
|
|
|
65
65
|
### 页面骨架来源(列表 / 详情 / 表单 / 仪表盘)
|
|
66
66
|
|
|
67
|
-
> ⚠️ **AI 默认不调用 `@teamix-evo/templates`
|
|
67
|
+
> ⚠️ **AI 默认不调用 `@teamix-evo/templates` 包**（见 ADR 0031 skill-templates-decoupling）。页面骨架按下列优先级生成：
|
|
68
68
|
|
|
69
69
|
1. **首选** —— 读 `teamix-evo-design-opentrek` skill 的 [`patterns/{list|detail|form|dashboard}-page.md`](../teamix-evo-design-opentrek/patterns/),按 Zone Map 与决策树用 ui 原子件 + biz-ui 业务件**直接拼装**到 `src/pages/<id>/`
|
|
70
70
|
2. **patterns/ 未覆盖时** —— 按业界流行的中后台页面架构(antd Pro / shadcn Examples 等)与用户描述自由实现,**不要回退到 templates 包**
|
|
@@ -112,7 +112,7 @@
|
|
|
112
112
|
1. **命名要能让下次复用查得到** —— 起 `OrderStatusBadge` 而不是 `MyBadge`;`useOrderList` 而不是 `useList`。
|
|
113
113
|
2. **抽象层级别低于一次性页面** —— 跨页面会用的才放 `src/components/`,只在一个页面用的写在 `src/pages/<id>/_components/`。
|
|
114
114
|
3. **暴露面尽量窄** —— 默认只 `export` 这次需要的 API,别一次性 `export *`。
|
|
115
|
-
4. **写完登记** —— 在 PR
|
|
115
|
+
4. **写完登记** —— 在 PR 描述里明确“新增 `<path>`，因为 ui / biz-ui / patterns / 本项目均未提供 X 能力”（注：不再以 `templates` 包作为兑底依据，见 ADR 0031 skill-templates-decoupling）。
|
|
116
116
|
|
|
117
117
|
---
|
|
118
118
|
|
|
@@ -111,7 +111,7 @@
|
|
|
111
111
|
|
|
112
112
|
### 页面骨架来源（列表 / 详情 / 表单 / Console Home）
|
|
113
113
|
|
|
114
|
-
> ⚠️ **AI 默认不调用 `@teamix-evo/templates` 包**（见
|
|
114
|
+
> ⚠️ **AI 默认不调用 `@teamix-evo/templates` 包**（见 ADR 0031 skill-templates-decoupling）。页面骨架按下列优先级生成：
|
|
115
115
|
|
|
116
116
|
1. **首选** —— 读 `teamix-evo-design-uni-manager` skill 的 [`patterns/{list|detail|form|dashboard}-page.md`](../teamix-evo-design-uni-manager/patterns/)，按 Zone Map 与决策树用 ui 原子件 + biz-ui/uni-manager 实物件（`um-topbar`） + 概念占位拼装表**直接拼装**到 `src/pages/<id>/`
|
|
117
117
|
2. **patterns/ 未覆盖时** —— 按业界流行的云管 / 控制台页面架构（antd Pro / aliyun-console / shadcn Examples 等）与用户描述自由实现，**不要回退到 templates 包**
|
|
@@ -167,7 +167,7 @@
|
|
|
167
167
|
1. **命名要能让下次复用查得到** —— 起 `InstanceStatusBadge` 而不是 `MyBadge`；`useInstanceList` 而不是 `useList`
|
|
168
168
|
2. **抽象层级别低于一次性页面** —— 跨页面会用的才放 `src/components/`，只在一个页面用的写在 `src/pages/<id>/_components/`
|
|
169
169
|
3. **暴露面尽量窄** —— 默认只 `export` 这次需要的 API，别一次性 `export *`
|
|
170
|
-
4. **写完登记** —— 在 PR 描述里明确“新增 `<path>`，因为 ui / biz-ui / patterns / 本项目均未提供 X 能力”（注：不再以 `templates`
|
|
170
|
+
4. **写完登记** —— 在 PR 描述里明确“新增 `<path>`，因为 ui / biz-ui / patterns / 本项目均未提供 X 能力”（注：不再以 `templates` 包作为兑底依据，见 ADR 0031 skill-templates-decoupling）
|
|
171
171
|
5. **uni-manager 专属**：跨云 / 跨租户的 component 必须放 `src/components/cloud/` 或 `src/components/<domain>/`，方便后续抽到 biz-ui/uni-manager
|
|
172
172
|
|
|
173
173
|
---
|
|
@@ -8,28 +8,24 @@
|
|
|
8
8
|
|
|
9
9
|
## 强制项（12）
|
|
10
10
|
|
|
11
|
-
| #
|
|
12
|
-
| --- |
|
|
13
|
-
| 1
|
|
14
|
-
| 2
|
|
15
|
-
| 3
|
|
16
|
-
| 4
|
|
17
|
-
| 4.1 | Button 不传 size
|
|
18
|
-
| 5
|
|
19
|
-
| 6
|
|
20
|
-
| 7
|
|
21
|
-
| 8
|
|
22
|
-
| 9
|
|
23
|
-
| 10
|
|
24
|
-
| 11
|
|
25
|
-
|
|
26
|
-
> **强制项 #12
|
|
27
|
-
>
|
|
28
|
-
> **强制项 #13([ADR 0025](../../../../../docs/adr/0025-component-props-explicit-declaration.md))**:组件 `Props` interface 必须**显式声明所有可配置 prop**,带中文 JSDoc(由 `pnpm gen:meta` 提取生成 meta.md props 表)。**禁止**空 extends 透传(如 `interface FooProps extends ComponentPropsWithoutRef<typeof Primitive.Root> {}`)— 会导致 meta props 表为空、Storybook controls 缺数据源、AI 生成代码无法读取支持的 prop。**数据录入类组件**(Checkbox/Switch/Select/Input/Slider 等)必须暴露至少一对受控套:`value` + `onChange`(或 Radix 命名 `onCheckedChange` / `onValueChange`)+ `defaultValue` / `defaultChecked`,业务侧能用受控模式跑通。
|
|
11
|
+
| # | 检查点 | 失败示例 | 通过条件 | 规则 |
|
|
12
|
+
| --- | ------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
|
|
13
|
+
| 1 | 无硬编码色值 | `bg-[#fff]` / `style={{color:'red'}}` | 走语义 token:`bg-background` / `text-foreground` | [F1] |
|
|
14
|
+
| 2 | 状态不用原始色 | `text-green-500` / `bg-red-100` | `<Badge variant="secondary">` / `text-destructive` | [S8] |
|
|
15
|
+
| 3 | 间距用 gap | `space-y-4` | `flex flex-col gap-4` | [S2] |
|
|
16
|
+
| 4 | className 不覆盖组件颜色 / 字体 | `<Button className="bg-blue-500">` | `<Button variant="default">` | [S1] |
|
|
17
|
+
| 4.1 | Button 不传 size | `<Button size="sm">` / `<Button size="sm" className="h-9 w-9 p-0">` | `<Button>...</Button>`(default = `h-8` + `text-xs` 12px,ADR 0027 对齐 cd hybridcloud form-element-medium);icon-only 用 `size="icon"` | ADR 0027 |
|
|
18
|
+
| 5 | 复合组件结构完整 | `<Dialog>` 缺 DialogTitle / `<Tabs>` 直接放 Trigger | Dialog ≥ Title;Card ≥ Header+Content;Tabs 含 List;详见 C 组 | [C1-C12] |
|
|
19
|
+
| 6 | 状态 / 占位 / 分隔走专用组件 | 自定义 styled span 当 Badge / animate-pulse div | Badge / Skeleton / Empty / Separator / Alert / `toast()` | [C7-C12] |
|
|
20
|
+
| 7 | 图标用 data-icon,不设尺寸类 | `<SearchIcon className="size-4 mr-2" />` | `<SearchIcon data-icon="inline-start" />` | [I1-I2] |
|
|
21
|
+
| 8 | 不手动 z-index / dark: 覆盖 | `className="z-50"` / `dark:bg-gray-950` | 删除 z-index(组件自管);用语义 token | [S5] [S7] |
|
|
22
|
+
| 9 | 条件类名用 cn() | `` `${active ? 'a' : 'b'}` `` | `cn('base', active ? 'a' : 'b')` | [S6] |
|
|
23
|
+
| 10 | 危险操作二次确认 | `<Button onClick={delete}>删除</Button>` | `<AlertDialog>` + 陈述句标题 + 影响列表 + 重复动词按钮 | P4 [philosophy] |
|
|
24
|
+
| 11 | 可交互元素显式带手型 | `<button onClick={...}>` 不带 `cursor-pointer` | `cursor-pointer` + `disabled:cursor-not-allowed` | ADR 0023 |
|
|
25
|
+
|
|
26
|
+
> **强制项 #12（并入 #11 的纪律范围，与 ADR 0024 scoped-css-radix-state-conflict 同步）**：hover / focus 视觉反馈（border / bg / shadow）写在组件源码 className 时**必须**用 `enabled:` 前缀，disabled 态不触发样式变化。失败示例 `hover:border-primary`（disabled 仍响应）；通过示例 `enabled:hover:border-primary`。Radix `data-state="checked"` / `"indeterminate"` / `"on"` 激活态视觉由组件自管，uni-manager scoped CSS 已统一在 `:not()` 链里排除这三个态值，新组件接入 `border-input` 类时务必核对。
|
|
29
27
|
|
|
30
28
|
[F1]: ./boundaries.md
|
|
31
|
-
[ADR0023]: ../../../../../docs/adr/0023-cursor-pointer-explicit-in-component-source.md
|
|
32
|
-
[ADR0027]: ../../../../../docs/adr/0027-component-visual-token-alignment.md
|
|
33
29
|
[S1]: ./boundaries.md
|
|
34
30
|
[S2]: ./boundaries.md
|
|
35
31
|
[S5]: ./boundaries.md
|
|
@@ -58,7 +54,7 @@
|
|
|
58
54
|
```markdown
|
|
59
55
|
## 自检报告 — <页面名>
|
|
60
56
|
|
|
61
|
-
### 强制项（
|
|
57
|
+
### 强制项（12/12 通过）✅
|
|
62
58
|
|
|
63
59
|
- [x] 1. 无硬编码色值
|
|
64
60
|
- [x] 2. 状态用 Badge / 语义 token
|
|
@@ -70,6 +66,8 @@
|
|
|
70
66
|
- [x] 8. 无 z-index / dark: 覆盖
|
|
71
67
|
- [x] 9. 条件类名用 cn()
|
|
72
68
|
- [x] 10. 危险操作二次确认
|
|
69
|
+
- [x] 11. cursor-pointer 显式
|
|
70
|
+
- [x] 12. enabled: 前缀
|
|
73
71
|
|
|
74
72
|
### 建议项（4/5 通过）✅
|
|
75
73
|
|
|
@@ -2,32 +2,28 @@
|
|
|
2
2
|
|
|
3
3
|
> AI 生成 / 翻新页面后**必须**逐项对照本清单。规则细节看 [boundaries.md](./boundaries.md)，本文件只列"要检查什么"。
|
|
4
4
|
>
|
|
5
|
-
> **强制项（
|
|
5
|
+
> **强制项（12）必须 100% 通过**；**建议项（7）至少 5 项通过**。
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
## 强制项（
|
|
10
|
-
|
|
11
|
-
| # | 检查点 | 失败示例
|
|
12
|
-
| --- | ------------------------------------------- |
|
|
13
|
-
| 1 | 无硬编码色值 | `bg-[#0064C8]` / `style={{color:'red'}}`
|
|
14
|
-
| 2 | 状态不用原始色 | `text-green-500` / `bg-red-100`
|
|
15
|
-
| 3 | 间距用 gap + 8 档刻度 | `space-y-4` / `gap-7` / `p-2.5`
|
|
16
|
-
| 4 | className 不覆盖组件颜色 / 字体 | `<Button className="bg-blue-500">`
|
|
17
|
-
| 5 | 复合组件结构完整 | `<Dialog>` 缺 DialogTitle / `<Tabs>` 直接放 Trigger
|
|
18
|
-
| 6 | 状态 / 占位 / 分隔走专用组件 | 自定义 styled span 当 Badge / animate-pulse div
|
|
19
|
-
| 7 | 图标用 data-icon，不设尺寸类 | `<SearchIcon className="size-4 mr-2" />`
|
|
20
|
-
| 8 | 不手动 z-index / dark: 覆盖 / focus:ring-\* | `className="z-50"` / `focus:ring-2 ring-primary`
|
|
21
|
-
| 9 | 条件类名用 cn() | `` `${active ? 'a' : 'b'}` ``
|
|
22
|
-
| 10 | 危险操作二次确认（含输入资源名称） | `<Button onClick={delete}>删除</Button>`
|
|
23
|
-
| 11 | 可交互元素显式带手型 | `<button onClick={...}>` 不带 `cursor-pointer`
|
|
24
|
-
| 12 | hover/focus 视觉反馈用 `enabled:` 前缀 | `hover:border-primary`（disabled 仍响应）
|
|
25
|
-
| 13 | 组件 Props 显式声明 + 中文 JSDoc | `interface FooProps extends ComponentPropsWithoutRef<...>` 空透传 | 显式列出每个 prop + JSDoc | [ADR0025] |
|
|
9
|
+
## 强制项（12）
|
|
10
|
+
|
|
11
|
+
| # | 检查点 | 失败示例 | 通过条件 | 规则 |
|
|
12
|
+
| --- | ------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------- | --------------- |
|
|
13
|
+
| 1 | 无硬编码色值 | `bg-[#0064C8]` / `style={{color:'red'}}` | 走语义 token：`bg-primary` / `text-foreground` | [F1] |
|
|
14
|
+
| 2 | 状态不用原始色 | `text-green-500` / `bg-red-100` | `<Badge variant="success">` / `text-destructive` | [S8] |
|
|
15
|
+
| 3 | 间距用 gap + 8 档刻度 | `space-y-4` / `gap-7` / `p-2.5` | `flex flex-col gap-4`；只用 1/2/3/4/5/6/8/12 | [S2] |
|
|
16
|
+
| 4 | className 不覆盖组件颜色 / 字体 | `<Button className="bg-blue-500">` | `<Button variant="default">` | [S1] |
|
|
17
|
+
| 5 | 复合组件结构完整 | `<Dialog>` 缺 DialogTitle / `<Tabs>` 直接放 Trigger | Dialog ≥ Title；Card ≥ Header+Content；Tabs 含 List；详见 C 组 | [C1-C12] |
|
|
18
|
+
| 6 | 状态 / 占位 / 分隔走专用组件 | 自定义 styled span 当 Badge / animate-pulse div | Badge / Skeleton / Empty / Separator / Alert / `toast()` | [C7-C12] |
|
|
19
|
+
| 7 | 图标用 data-icon，不设尺寸类 | `<SearchIcon className="size-4 mr-2" />` | `<SearchIcon data-icon="inline-start" />` | [I1-I2] |
|
|
20
|
+
| 8 | 不手动 z-index / dark: 覆盖 / focus:ring-\* | `className="z-50"` / `focus:ring-2 ring-primary` | 让 scoped CSS 接管，不重复声明 | [S5][S7] |
|
|
21
|
+
| 9 | 条件类名用 cn() | `` `${active ? 'a' : 'b'}` `` | `cn('base', active ? 'a' : 'b')` | [S6] |
|
|
22
|
+
| 10 | 危险操作二次确认（含输入资源名称） | `<Button onClick={delete}>删除</Button>` | `<AlertDialog>` + 陈述句标题 + 影响列表（含云/区域）+ 输入名称 | P4 [philosophy] |
|
|
23
|
+
| 11 | 可交互元素显式带手型 | `<button onClick={...}>` 不带 `cursor-pointer` | `cursor-pointer` + `disabled:cursor-not-allowed` | ADR 0023 |
|
|
24
|
+
| 12 | hover/focus 视觉反馈用 `enabled:` 前缀 | `hover:border-primary`（disabled 仍响应） | `enabled:hover:border-primary` | ADR 0024 |
|
|
26
25
|
|
|
27
26
|
[F1]: ./boundaries.md
|
|
28
|
-
[ADR0023]: ../../../../../docs/adr/0023-cursor-pointer-explicit-in-component-source.md
|
|
29
|
-
[ADR0024]: ../../../../../docs/adr/0024-scoped-css-radix-state-conflict.md
|
|
30
|
-
[ADR0025]: ../../../../../docs/adr/0025-component-props-explicit-declaration.md
|
|
31
27
|
[S1]: ./boundaries.md
|
|
32
28
|
[S2]: ./boundaries.md
|
|
33
29
|
[S5]: ./boundaries.md
|
|
@@ -74,7 +70,7 @@
|
|
|
74
70
|
```markdown
|
|
75
71
|
## 自检报告 — <页面名>
|
|
76
72
|
|
|
77
|
-
### 强制项（
|
|
73
|
+
### 强制项（12/12 通过）✅
|
|
78
74
|
|
|
79
75
|
- [x] 1. 无硬编码色值
|
|
80
76
|
- [x] 2. 状态用 Badge / 语义 token
|
|
@@ -88,7 +84,6 @@
|
|
|
88
84
|
- [x] 10. 危险操作二次确认
|
|
89
85
|
- [x] 11. cursor-pointer 显式
|
|
90
86
|
- [x] 12. enabled: 前缀
|
|
91
|
-
- [x] 13. Props 显式声明
|
|
92
87
|
|
|
93
88
|
### 一致性三件套（5/5 通过）✅
|
|
94
89
|
|
|
@@ -79,45 +79,46 @@ npx teamix-evo@latest skills update --dry-run # 预览,不写盘
|
|
|
79
79
|
|
|
80
80
|
CLI 二进制名 `teamix-evo`（+ 脚手架独立二进制 `create-teamix-evo`）。概览表列出所有子命令与一句话用途；**完整选项请跑 `--help` 或调 MCP 工具动态获取**（见表后说明）。
|
|
81
81
|
|
|
82
|
-
| Group | Verb | 用途
|
|
83
|
-
| ------------- | ----------------------------------------------------- |
|
|
84
|
-
| **create** | `npm create teamix-evo [dir]` | 一站式脚手架：scaffold + tokens + skills + ui + lint
|
|
85
|
-
| **init** | `init [-y] [--dry-run] [--variant <v>] [--cwd <dir>]` | 普通版接入：把 teamix-evo 注入已有 npm 工程（三分支决策树 + 6 类冲突检测 + wizard）
|
|
86
|
-
| **update** | `update [--dry-run] [--cwd <dir>]` | 套件级升级 orchestrator：tokens → skills（[ADR 0019](docs/adr/0019)）
|
|
87
|
-
| **switch** | `switch <new-variant> [--apply] [-y] [--cwd <dir>]` | 切到目标 variant：dry-run 默认，`--apply` 才真写；自动 snapshot + token rename hint
|
|
88
|
-
| **restore** | `restore [<ts>] [--list] [-y] [--cwd <dir>]` | 失败回滚：从 snapshot 还原 `.teamix-evo/`，pre-restore 自身可逆（ADR 0019 §2）
|
|
89
|
-
| **tokens** | `init <variant>` | 初始化指定变体的 design tokens（`<variant>` 必填）
|
|
90
|
-
| | `list-variants` | 列出所有可选变体
|
|
91
|
-
| | `list` | 列出已装 tokens 资源
|
|
92
|
-
| | `update` | 刷新 regenerable tokens（frozen 保留，[ADR 0003](docs/adr/0003)）
|
|
93
|
-
| | `uninstall` | 卸载 tokens
|
|
94
|
-
| **skills** | `init` | 自举：按 variant + scope 装全部匹配 skill（[ADR 0034](docs/adr/0034) verb 分工）
|
|
95
|
-
| | `add <name...>` | 增量装指定 skill
|
|
96
|
-
| | `list` (alias `ls`) | 列出全部 skill（`--installed` 仅已装）
|
|
97
|
-
| | `update [name...]` | 升级已装 skill（[ADR 0035](docs/adr/0035) 双闸 + `--scope` + `--dry-run`）
|
|
98
|
-
| | `uninstall [ids...]` | 卸载 skill
|
|
99
|
-
| | `doctor` | 检测 source ↔ IDE 镜像漂移（[ADR 0013](docs/adr/0013)）
|
|
100
|
-
| | `sync [name...]` | 重新镜像到 IDE 路径（不升版本）
|
|
101
|
-
| **ui** | `init` | 初始化 ui 配置（aliases / icon / tsx / rsc）
|
|
102
|
-
| | `add <id...>` | 安装 UI 组件（auto-resolve registryDependencies，frozen）
|
|
103
|
-
| | `list` | 列出 UI 组件（`--installed` / `--include-deprecated`）
|
|
104
|
-
| | `upgrade [id...]` | 生成 ui 升级 staging（仅写 `.upgrade-staging/`，[ADR 0040](docs/adr/0040)；skill 应用）
|
|
105
|
-
|
|
|
106
|
-
|
|
|
107
|
-
| | `list
|
|
108
|
-
| | `
|
|
109
|
-
|
|
|
110
|
-
|
|
|
111
|
-
| | `list
|
|
112
|
-
|
|
|
113
|
-
| **
|
|
114
|
-
|
|
|
82
|
+
| Group | Verb | 用途 |
|
|
83
|
+
| ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
84
|
+
| **create** | `npm create teamix-evo [dir]` | 一站式脚手架：scaffold + tokens + skills + ui + lint |
|
|
85
|
+
| **init** | `init [-y] [--dry-run] [--variant <v>] [--cwd <dir>]` | 普通版接入：把 teamix-evo 注入已有 npm 工程（三分支决策树 + 6 类冲突检测 + wizard） |
|
|
86
|
+
| **update** | `update [--dry-run] [--cwd <dir>]` | 套件级升级 orchestrator：tokens → skills（[ADR 0019](docs/adr/0019)） |
|
|
87
|
+
| **switch** | `switch <new-variant> [--apply] [-y] [--cwd <dir>]` | 切到目标 variant：dry-run 默认，`--apply` 才真写；自动 snapshot + token rename hint |
|
|
88
|
+
| **restore** | `restore [<ts>] [--list] [-y] [--cwd <dir>]` | 失败回滚：从 snapshot 还原 `.teamix-evo/`，pre-restore 自身可逆（ADR 0019 §2） |
|
|
89
|
+
| **tokens** | `init <variant>` | 初始化指定变体的 design tokens（`<variant>` 必填） |
|
|
90
|
+
| | `list-variants` | 列出所有可选变体 |
|
|
91
|
+
| | `list` | 列出已装 tokens 资源 |
|
|
92
|
+
| | `update` | 刷新 regenerable tokens（frozen 保留，[ADR 0003](docs/adr/0003)） |
|
|
93
|
+
| | `uninstall` | 卸载 tokens |
|
|
94
|
+
| **skills** | `init` | 自举：按 variant + scope 装全部匹配 skill（[ADR 0034](docs/adr/0034) verb 分工） |
|
|
95
|
+
| | `add <name...>` | 增量装指定 skill |
|
|
96
|
+
| | `list` (alias `ls`) | 列出全部 skill（`--installed` 仅已装） |
|
|
97
|
+
| | `update [name...]` | 升级已装 skill（[ADR 0035](docs/adr/0035) 双闸 + `--scope` + `--dry-run`） |
|
|
98
|
+
| | `uninstall [ids...]` | 卸载 skill |
|
|
99
|
+
| | `doctor` | 检测 source ↔ IDE 镜像漂移（[ADR 0013](docs/adr/0013)） |
|
|
100
|
+
| | `sync [name...]` | 重新镜像到 IDE 路径（不升版本） |
|
|
101
|
+
| **ui** | `init` | 初始化 ui 配置（aliases / icon / tsx / rsc） |
|
|
102
|
+
| | `add <id...>` | 安装 UI 组件（auto-resolve registryDependencies，frozen） |
|
|
103
|
+
| | `list` | 列出 UI 组件（`--installed` / `--include-deprecated`） |
|
|
104
|
+
| | `upgrade [id...]` | 生成 ui 升级 staging（仅写 `.upgrade-staging/`，[ADR 0040](docs/adr/0040)；skill 应用） |
|
|
105
|
+
| | `promote-to-biz [ids...]` | 把 ui staging 条目按 8 模式（Coexist/Preset/Wrapper/Compose/Variant/Fork/TokenOnly/ManualReview）落地到 `src/components/business/` + manifest（Init 落地计划 §C.3） |
|
|
106
|
+
| **biz-ui** | `add <id...>` | 安装业务组件（`--variant` 必填） |
|
|
107
|
+
| | `list` | 列出变体下的业务组件 |
|
|
108
|
+
| | `list-variants` | 列出可用业务组件变体 |
|
|
109
|
+
| | `upgrade [id...]` | 生成 biz-ui 升级 staging（变体感知，[ADR 0040](docs/adr/0040)；skill 应用） |
|
|
110
|
+
| **templates** | `add <id...>` | 安装页面模板（`--variant` 必填）⚠️ AI 默认不主动调用（[ADR 0031](docs/adr/0031)） |
|
|
111
|
+
| | `list` | 列出变体下的模板 |
|
|
112
|
+
| | `list-variants` | 列出可用模板变体 |
|
|
113
|
+
| **lint** | `init` | 初始化 ESLint + Stylelint token-discipline 规则 |
|
|
114
|
+
| **logs** | `analyze` | 汇总 vibe-logger JSONL（tool / tag / MCP 频次） |
|
|
115
|
+
| | `trace` | 会话级调用链回溯（按 prompt / session 过滤） |
|
|
115
116
|
|
|
116
117
|
> **脚注**
|
|
117
118
|
>
|
|
118
119
|
> - `tokens` / `biz-ui` / `templates` 共享 variant 名空间（[ADR 0014](docs/adr/0014)），与 `tokens init` 选定 variant 一致。
|
|
119
120
|
> - `skills init` vs `add`：init 无 ids = 自举全部匹配 skill；add 必填 ids = 增量（[ADR 0034](docs/adr/0034)）。
|
|
120
|
-
> - 源镜像模型（[ADR 0013](docs/adr/0013)）：规范副本在 `.teamix-evo/skills/`，IDE 镜像在 `.qoder/skills/` 与 `.claude/skills/`。
|
|
121
|
+
> - 源镜像模型（[ADR 0013](docs/adr/0013)）：规范副本在 `.teamix-evo/skills-source/`，IDE 镜像在 `.qoder/skills/` 与 `.claude/skills/`。
|
|
121
122
|
|
|
122
123
|
### 动态查询（详细选项 & 实时清单）
|
|
123
124
|
|
|
@@ -248,6 +249,25 @@ CLI 在 partial 状态会打印“恢复指引”面板：失败步骤名、错
|
|
|
248
249
|
- `pendingConflictWork`（如有）：批次 4 上线后用 `teamix-evo conflict resolve` 收尾。
|
|
249
250
|
- 全局 entry skill：若 `~/.qoder/skills/teamix-evo-manage` 不存在，补一句 `npx teamix-evo skills add teamix-evo-manage --scope global`（ADR 0033）。
|
|
250
251
|
|
|
252
|
+
### Post-init AI 串场（5 步闭环）
|
|
253
|
+
|
|
254
|
+
> CLI `init` 完成后，末尾会打印 Next Steps 板块，并提示「让 AI 接力」。当用户在 IDE 内触发本 skill 接力时，按以下 5 步顺序走完闭环；每步执行前先告知用户即将做什么，执行后回报关键统计。
|
|
255
|
+
|
|
256
|
+
| # | 步骤 | 命令 / 操作 | 目的 | 何时跳过 |
|
|
257
|
+
| --- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
|
|
258
|
+
| 1 | adopt | `npx teamix-evo ui add --adopt --dry-run` → 确认后去 dry-run | 把项目里现有的 `src/components/{ui,business}/**` + hooks/utils 全量纳管到 manifest（strategy=frozen，标 `sourceLineage=detected`），不动文件内容 | 项目无 `src/components/` |
|
|
259
|
+
| 2 | upgrade staging | `npx teamix-evo ui upgrade`（再 `biz-ui upgrade`） | 生成 `.upgrade-staging/`，每条目带 `featureVector` + `recommendedModes` + `confidence`（ADR 0040） | adopt 0 件 / 全部 frozen 一致 |
|
|
260
|
+
| 3 | tokens audit | `npx teamix-evo tokens audit`（C.5 上线后）/ 暂用人工读 `tokens/tokens.overrides.css` | 4 类输出：冗余删除 / 有效保留 / 推荐迁移 / 项目特有；与 `theme.css` 做 v3↔v4 语义比较 | overrides 0 变量 |
|
|
261
|
+
| 4 | AGENTS.md 回填 | 读根 `AGENTS.md` managed 区域之外的内容，按 heading 归类（UI 设计 / 代码研发 / 项目特有），把项目特有规则塞回 managed 区域之前 | 让用户私有规范与 Skills 注入区共存，不被 `init --merge-managed` 覆盖 | 用户文件全为 managed-only |
|
|
262
|
+
| 5 | lint | `npx teamix-evo lint init`（如未跑）+ `pnpm lint` | token-discipline 兜底；error 数内嵌报告 | 已跑过且 0 error |
|
|
263
|
+
|
|
264
|
+
执行约定：
|
|
265
|
+
|
|
266
|
+
- **每步前**先用一句话告诉用户「即将做什么 + 命令是什么」，等用户回 `OK / 跳过` 再动手；不要批量静默连发。
|
|
267
|
+
- **每步后**汇总数字：`adopted=N foreign=M / staged=K / overrides 删 X 留 Y / AGENTS.md 增 Z 段 / lint error=E`。
|
|
268
|
+
- **遇 ManualReview / foreign / 推荐迁移**：列出来交给用户决策，不替用户改代码。
|
|
269
|
+
- 5 步走完，输出一段 `done` 总结 + 后续可走的命令（`ui promote-to-biz` / `restore` / `update`）。
|
|
270
|
+
|
|
251
271
|
## 场景 4 · 升级
|
|
252
272
|
|
|
253
273
|
> **概念区分**："升级 teamix-evo"= 升级**整个 AI 套件**（所有已装包）；"升级 manage skill / 升级某个 skill"= 只升级指定的 skill。根据用户表述判断走哪条路径。
|
|
@@ -416,6 +436,70 @@ npx teamix-evo biz-ui upgrade --apply # 错误：CLI 不写 src，guidance
|
|
|
416
436
|
- 不要听到“升级 ui”就打 `ui add` — `add` 是装进去，`upgrade` 是已装后追上上游。
|
|
417
437
|
- 不要在 `shadcn-native` lineage 强行跳 staging；CLI 跳过是预期行为。
|
|
418
438
|
|
|
439
|
+
### 4f · 组件源码 promotion（`teamix-evo ui promote-to-biz` — Init 落地计划 §C.3 / §C.4）
|
|
440
|
+
|
|
441
|
+
**触发**：用户表达“把 ui 组件融进 biz-ui / 把 button 提级成业务组件 / promote ui to business / 把 staging 里的差异融合到 business 层 / 多模式融合 / wrapper + preset 叠加 / 双轨 coexist / 把上游版和自家版同时保留”等关键词；或在场景 4e 走完 staging 后用户问“能不能直接生成业务包装组件”。
|
|
442
|
+
|
|
443
|
+
> 这是 §4e 的**下游**：4e 只生成 `.upgrade-staging/`，4f 才把条目按 AI 推荐的 `recommendedModes` 真正落地到 `src/components/business/` 并维护 manifest。**条目的 8 模式判定全部由 staging meta 给出**，本 skill 只做分组、确认、转发命令。
|
|
444
|
+
|
|
445
|
+
**一行命令**：
|
|
446
|
+
|
|
447
|
+
```bash
|
|
448
|
+
npx teamix-evo ui promote-to-biz # 默认融合最新 ui-* staging 中所有可自动模式条目
|
|
449
|
+
npx teamix-evo ui promote-to-biz button card # 只融合指定 id
|
|
450
|
+
npx teamix-evo ui promote-to-biz --modes Wrapper,Preset # 强制覆盖 staging 推荐模式
|
|
451
|
+
npx teamix-evo ui promote-to-biz --migrate-imports # Coexist 模式时连带 src/** 改 import 到 legacy-<id>
|
|
452
|
+
npx teamix-evo ui promote-to-biz --keep-original-names # Coexist 模式 export 不前缀化 Legacy
|
|
453
|
+
npx teamix-evo ui promote-to-biz --dry-run # 计划态：列模式分组 + 文件变更预览，不写盘
|
|
454
|
+
npx teamix-evo ui promote-to-biz --staging-dir <path> # 指定 staging 目录（不指定则取最新 ui-* 目录）
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
**8 模式分组语义**（对应 §C.3）：
|
|
458
|
+
|
|
459
|
+
| Mode | 终结？ | 产物 |
|
|
460
|
+
| -------------- | ------ | -------------------------------------------------------------------------------- |
|
|
461
|
+
| `Coexist` | 是 | `business/legacy-<id>.tsx`（用户版改名 `Legacy<Foo>`）+ `ui/<id>.tsx` 回填上游版 |
|
|
462
|
+
| `Fork` | 是 | `business/<id>.tsx`（直接搬用户版，无上游对应） |
|
|
463
|
+
| `TokenOnly` | 是 | **不创建文件**，引导用户改 `tokens/tokens.overrides.css` |
|
|
464
|
+
| `ManualReview` | 是 | **不创建文件**，列入待办交用户决策 |
|
|
465
|
+
| `Preset` | 可叠加 | `business/<id>.tsx` import 上游 + `defaultProps` |
|
|
466
|
+
| `Wrapper` | 可叠加 | `business/<id>.tsx` 包装上游 + 业务 state/effect |
|
|
467
|
+
| `Variant` | 可叠加 | `business/<id>.tsx` 扩展上游 cva（上游未 export → 触发 ManualReview） |
|
|
468
|
+
| `Compose` | 可叠加 | `business/<id>.tsx` 拼装多个上游原子 |
|
|
469
|
+
|
|
470
|
+
> 叠加规则：`Coexist` / `Fork` / `TokenOnly` / `ManualReview` 互斥（终结）；`Preset + Wrapper + Variant + Compose` 任意组合，叠加顺序内 → 外为 `variant > wrapper > preset`。
|
|
471
|
+
|
|
472
|
+
**AI 引导决策树（5 步闭环）**：
|
|
473
|
+
|
|
474
|
+
1. **读 staging meta** —— 让 CLI 帮拿（`teamix-evo ui upgrade` 输出 staging 路径），打开 `.teamix-evo/.upgrade-staging/<latest-ui-*>/meta.json` 阅读所有 entries 的 `id` / `recommendedModes` / `confidence` / `reasons` / `featureVector`。
|
|
475
|
+
2. **按主模式分组展示** —— 取每个 entry 的第一个 mode 作为分组键；列表给用户：
|
|
476
|
+
- `Coexist (3): button, dialog, dropdown-menu` → 双轨并存，会改 import 路径
|
|
477
|
+
- `Wrapper+Preset (2): card, badge` → 业务包装 + 默认值
|
|
478
|
+
- `TokenOnly (4): separator, label, ...` → 只需改 tokens.overrides.css
|
|
479
|
+
- `ManualReview (1): table` → 置信度 < 0.6，需要用户先看 diff
|
|
480
|
+
3. **每组逐一询问** —— 对每组先展示 `current.tsx` ↔ `incoming.tsx` 关键 diff（用户要看才展），再问“是否按推荐模式 promote？yes/no/调整模式”。
|
|
481
|
+
- 用户改模式时复述新 mode list，再调 `--modes` 参数。
|
|
482
|
+
- `Coexist` 分组要明确告诉用户：默认**不**重写既有 `import .../ui/<id>` 引用，加 `--migrate-imports` 才统改为 `legacy-<id>`。
|
|
483
|
+
4. **逐组调 promote-to-biz** —— 每组一次命令调用，传该组所有 id；先 `--dry-run` 看 FileChange 四桶（new/modified/deleted/backed-up），用户 OK 后去 dry-run 真写。
|
|
484
|
+
5. **收尾输出未处理 + import skipped 清单** —— 命令结束后复述：
|
|
485
|
+
- `manualReview: [...]` 让用户人工抉择（看 diff 或拆 family）
|
|
486
|
+
- `tokenOnly: [...]` 引导走场景 6 / `tokens audit`
|
|
487
|
+
- `importRewrite.skipped: [{file, line, reason}]` 列出动态 import / 别名 export / 模板字符串这些 regex 重写不到的位置，让用户人工处理
|
|
488
|
+
- `failed: [...]`（如果有）逐条说明失败原因
|
|
489
|
+
|
|
490
|
+
**身份划分清单**：
|
|
491
|
+
|
|
492
|
+
- **CLI（`ui promote-to-biz`）**：执行备份、写 `business/`、回填 `ui/`、按 spec 重写 `src/**` 静态 import、改 manifest（promoted 资源记入虚拟包 `@teamix-evo/biz-ui-promoted`）。
|
|
493
|
+
- **AI（本 skill）**：读 meta、分组、展示 diff、征用户同意、转命令；**不**自己写文件、**不**自己改 import。
|
|
494
|
+
- **`teamix-evo-upgrade` skill**：管 §4e staging → src 的 1:1 替换；**不**做模式分流，本场景才做。
|
|
495
|
+
|
|
496
|
+
**不要**：
|
|
497
|
+
|
|
498
|
+
- 不要绕过 staging 直接调 `promote-to-biz`：CLI 拒收（命令依赖 staging meta）。
|
|
499
|
+
- 不要把 `Coexist` 当 `Replace` 用：默认双轨，旧 import **不**自动迁移，要 `--migrate-imports`；并且 export 默认前缀 `Legacy`，要 `--keep-original-names` 才保留原名。
|
|
500
|
+
- 不要忽略 `importRewrite.skipped`：那批位置 CLI 故意放弃，必须告诉用户人工处理（dynamic-import / 别名 re-export / 模板字符串）。
|
|
501
|
+
- 不要建议用户手改 `manifest.json`：promoted 登记由 CLI 写，污染了走 `restore`。
|
|
502
|
+
|
|
419
503
|
## 场景 5 · 卸载
|
|
420
504
|
|
|
421
505
|
**触发**:用户说"卸载 teamix-evo / remove the design system"。
|
|
@@ -9,10 +9,22 @@ description: |
|
|
|
9
9
|
|
|
10
10
|
# teamix-evo-upgrade
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
## 安装方式
|
|
13
|
+
|
|
14
|
+
本 skill 是 **lifecycle 工具型 skill**（消费 `.upgrade-hints/` + `.upgrade-staging/` 的通用工作流，跨 variant 共用，不携带任何业务内容），manifest 里声明 `scope: "global"`。**推荐全局安装一次**：
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npx teamix-evo skills add teamix-evo-upgrade --scope global
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`skills init`（项目级自举）与 `npm create teamix-evo` **不会**自动装本 skill —— bulk 模式按 scope 自动跳过（[ADR 0033](../../docs/adr/0033-entry-skill-global-only-scope.md)）。如果用户在项目级显式 `skills add teamix-evo-upgrade --scope project`，CLI 给出「推荐 global」warning 但仍装入（用户自负责），代价是后续 IDE 会同时识别全局与项目两份副本。
|
|
21
|
+
|
|
22
|
+
与 [`teamix-evo-manage`](../teamix-evo-manage/SKILL.md) 同属 lifecycle 工具，分工：manage 负责 orchestration（init / update / switch / 触发 staging 生成），本 skill 负责 staging / hints 的逐文件 hard-gate apply。
|
|
23
|
+
|
|
24
|
+
This skill consumes two complementary upgrade artefacts the CLI produces during upgrades and the consumer must adopt by hand under the ADR 0019 (project-upgrade-flow) **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):
|
|
13
25
|
|
|
14
26
|
1. **Token rename hints** — `.teamix-evo/.upgrade-hints/tokens-<ts>.json` (variable-level rewrites under `src/**` + `tokens/tokens.overrides.css`).
|
|
15
|
-
2. **Component source staging** — `.teamix-evo/.upgrade-staging/{ui,biz-ui}-<ts>/` (per-component file replacements under `src/components/{ui,business}/**`, see
|
|
27
|
+
2. **Component source staging** — `.teamix-evo/.upgrade-staging/{ui,biz-ui}-<ts>/` (per-component file replacements under `src/components/{ui,business}/**`, see ADR 0040 component-source-layer-upgrade-flow).
|
|
16
28
|
|
|
17
29
|
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.
|
|
18
30
|
|
|
@@ -166,7 +178,7 @@ When `teamix-evo update` (auto-staging step), `teamix-evo ui upgrade [id]`, or `
|
|
|
166
178
|
|
|
167
179
|
> **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).
|
|
168
180
|
|
|
169
|
-
The CLI **never writes** into `src/components/{ui,business}/**` — frozen boundary,
|
|
181
|
+
The CLI **never writes** into `src/components/{ui,business}/**` — frozen boundary, ADR 0019 (project-upgrade-flow) + ADR 0040 (component-source-layer-upgrade-flow). This skill is the only path to land staged changes.
|
|
170
182
|
|
|
171
183
|
## Staging manifest payload (schema v1)
|
|
172
184
|
|
|
@@ -207,7 +219,7 @@ The CLI **never writes** into `src/components/{ui,business}/**` — frozen bound
|
|
|
207
219
|
}
|
|
208
220
|
```
|
|
209
221
|
|
|
210
|
-
`riskLevel` values (from
|
|
222
|
+
`riskLevel` values (from ADR 0040 §D3 component-source-layer-upgrade-flow):
|
|
211
223
|
|
|
212
224
|
| level | meaning | suggested handling |
|
|
213
225
|
| ------------------- | -------------------------------------------------------------------- | ----------------------------------- |
|