@teamix-evo/skills 0.7.0 → 0.8.1
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 +5 -4
- 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/boundaries.md +7 -1
- package/src/teamix-evo-design-opentrek/checklist.md +19 -21
- package/src/teamix-evo-design-opentrek/rules/boundaries.rules.json +10 -0
- package/src/teamix-evo-design-uni-manager/boundaries.md +7 -1
- package/src/teamix-evo-design-uni-manager/checklist.md +18 -23
- package/src/teamix-evo-design-uni-manager/rules/boundaries.rules.json +10 -0
- package/src/teamix-evo-manage/SKILL.md +175 -49
- package/src/teamix-evo-upgrade/SKILL.md +142 -9
package/manifest.json
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"id": "teamix-evo-manage",
|
|
12
12
|
"name": "teamix-evo-manage",
|
|
13
13
|
"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.",
|
|
14
|
-
"version": "0.
|
|
14
|
+
"version": "0.3.0",
|
|
15
15
|
"source": "src/teamix-evo-manage",
|
|
16
16
|
"ides": ["qoder", "claude"],
|
|
17
17
|
"updateStrategy": "managed",
|
|
@@ -70,13 +70,14 @@
|
|
|
70
70
|
{
|
|
71
71
|
"id": "teamix-evo-upgrade",
|
|
72
72
|
"name": "teamix-evo-upgrade",
|
|
73
|
-
"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}
|
|
74
|
-
"version": "0.
|
|
73
|
+
"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\"、\"token 治理\"、\"tokens diagnose\"、\"tokens treat\"、\"治理计划\"、\".treatment-plan.md\"、\"baseline 锁定\"、\"token 反哺\"、\"清理 token 违规\"、\"token cleanup\"、\"lint baseline\"、\"降违规\"、\"全部治理\"; 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; AI sees output of `teamix-evo init` showing token-discipline ESLint warnings and the user wants to clean up; user opens any `.teamix-evo/.upgrade-hints/tokens-*.json` or any file under `.teamix-evo/.upgrade-staging/{ui,biz-ui}-*/` or `.teamix-evo/.treatment-plan.md`.\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).",
|
|
74
|
+
"version": "0.2.0",
|
|
75
75
|
"source": "src/teamix-evo-upgrade",
|
|
76
76
|
"ides": ["qoder", "claude"],
|
|
77
77
|
"updateStrategy": "managed",
|
|
78
78
|
"managedRegions": ["core"],
|
|
79
|
-
"template": false
|
|
79
|
+
"template": false,
|
|
80
|
+
"scope": "global"
|
|
80
81
|
}
|
|
81
82
|
]
|
|
82
83
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@teamix-evo/skills",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.1",
|
|
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
|
---
|
|
@@ -467,7 +467,7 @@ CSS 变量已在 dark 模式下自动切换。手动 `dark:` 会绕过主题系
|
|
|
467
467
|
|
|
468
468
|
---
|
|
469
469
|
|
|
470
|
-
## I1-
|
|
470
|
+
## I1-I5 · 图标 & 导入规则
|
|
471
471
|
|
|
472
472
|
### [ERROR] I1 · 按钮内图标用 data-icon 属性定位
|
|
473
473
|
|
|
@@ -507,6 +507,12 @@ CSS 变量已在 dark 模式下自动切换。手动 `dark:` 会绕过主题系
|
|
|
507
507
|
|
|
508
508
|
> 检查: eslint `teamix-evo/icon-from-lucide` (拦截 import 自非配置图标库)
|
|
509
509
|
|
|
510
|
+
### [WARN] I5 · 禁止从 shadcn-ui/ 遗留目录导入组件
|
|
511
|
+
|
|
512
|
+
`teamix-evo init` 在存量项目中将原有 `ui/` 目录搬迁至 `shadcn-ui/` 后，新组件统一从 `@/components/ui/` 导入。遗留的 `@/components/shadcn-ui/` 引用应逐步迁移。
|
|
513
|
+
|
|
514
|
+
> 检查: eslint `teamix-evo/no-legacy-shadcn-import` (warn 级别，渐进迁移)
|
|
515
|
+
|
|
510
516
|
---
|
|
511
517
|
|
|
512
518
|
## Overlay 组件选型表
|
|
@@ -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
|
|
|
@@ -386,6 +386,16 @@
|
|
|
386
386
|
"lintRule": "teamix-evo/icon-from-lucide",
|
|
387
387
|
"boundaryAnchor": "boundaries.md#error-i4--按项目配置的-iconlibrary-导入",
|
|
388
388
|
"status": "active"
|
|
389
|
+
},
|
|
390
|
+
{
|
|
391
|
+
"id": "I5",
|
|
392
|
+
"group": "component",
|
|
393
|
+
"rule": "禁止从 shadcn-ui/ 遗留目录导入组件",
|
|
394
|
+
"severity": "WARN",
|
|
395
|
+
"scope": "global",
|
|
396
|
+
"lintRule": "teamix-evo/no-legacy-shadcn-import",
|
|
397
|
+
"boundaryAnchor": "boundaries.md#warn-i5--禁止从-shadcn-ui-遗留目录导入组件",
|
|
398
|
+
"status": "active"
|
|
389
399
|
}
|
|
390
400
|
]
|
|
391
401
|
}
|
|
@@ -460,7 +460,7 @@ CSS 变量已在 dark 模式下自动切换（uni-manager `theme.css` 内置）
|
|
|
460
460
|
|
|
461
461
|
---
|
|
462
462
|
|
|
463
|
-
## UM1-
|
|
463
|
+
## UM1-UM4 · Uni-Manager 专有云一致性硬约束
|
|
464
464
|
|
|
465
465
|
> 来自 ADR 0030 / Teamix-UI 规范 doc 15-16-20。这三条是 uni-manager 区别于 opentrek 的核心硬约束，与"一致性是云管平台生命线"的哲学主张呼应（philosophy.md §1）。
|
|
466
466
|
|
|
@@ -541,6 +541,12 @@ CSS 变量已在 dark 模式下自动切换（uni-manager `theme.css` 内置）
|
|
|
541
541
|
|
|
542
542
|
> 检查: 无 lint (人工评审 / scenario-instantiator subagent)
|
|
543
543
|
|
|
544
|
+
### [WARN] UM4 · 禁止从 shadcn-ui/ 遗留目录导入组件
|
|
545
|
+
|
|
546
|
+
`teamix-evo init` 在存量项目中将原有 `ui/` 目录搬迁至 `shadcn-ui/` 后，新组件统一从 `@/components/ui/` 导入。遗留的 `@/components/shadcn-ui/` 引用应逐步迁移。
|
|
547
|
+
|
|
548
|
+
> 检查: eslint `teamix-evo/no-legacy-shadcn-import` (warn 级别，渐进迁移)
|
|
549
|
+
|
|
544
550
|
---
|
|
545
551
|
|
|
546
552
|
## Overlay 组件选型表
|
|
@@ -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
|
|
|
@@ -413,6 +413,16 @@
|
|
|
413
413
|
"lintRule": null,
|
|
414
414
|
"boundaryAnchor": "boundaries.md#error-um3--跨云资源列表与详情必须标注-cloudbadge--scope-uni-manager",
|
|
415
415
|
"status": "active"
|
|
416
|
+
},
|
|
417
|
+
{
|
|
418
|
+
"id": "UM4",
|
|
419
|
+
"group": "component",
|
|
420
|
+
"rule": "禁止从 shadcn-ui/ 遗留目录导入组件",
|
|
421
|
+
"severity": "WARN",
|
|
422
|
+
"scope": "global",
|
|
423
|
+
"lintRule": "teamix-evo/no-legacy-shadcn-import",
|
|
424
|
+
"boundaryAnchor": "boundaries.md#warn-um4--禁止从-shadcn-ui-遗留目录导入组件",
|
|
425
|
+
"status": "active"
|
|
416
426
|
}
|
|
417
427
|
]
|
|
418
428
|
}
|
|
@@ -9,6 +9,8 @@ description: |
|
|
|
9
9
|
|
|
10
10
|
# teamix-evo-manage
|
|
11
11
|
|
|
12
|
+
> **📋 重要提示**：若项目已跑过 `teamix-evo init`，请先读 `.teamix-evo/init-checklist.md`（CLI 自动生成）。该文件记录了 Phase A（CLI 步骤）和 Phase B（6 步 AI 串场）的完成状态。按 checklist 顺序继续执行，不要跳步。
|
|
13
|
+
|
|
12
14
|
Single entry skill for the **teamix-evo** toolkit lifecycle. Covers six scenarios:
|
|
13
15
|
|
|
14
16
|
1. Fuzzy init → ask user to pick a tokens variant.
|
|
@@ -23,7 +25,7 @@ Single entry skill for the **teamix-evo** toolkit lifecycle. Covers six scenario
|
|
|
23
25
|
本 skill 是 **entry skill**(lifecycle orchestrator),manifest 里声明 `scope: "global"`。**推荐全局安装一次**:
|
|
24
26
|
|
|
25
27
|
```bash
|
|
26
|
-
npx teamix-evo skills add teamix-evo-manage --scope global
|
|
28
|
+
npx teamix-evo skills add teamix-evo-manage --scope global -y
|
|
27
29
|
```
|
|
28
30
|
|
|
29
31
|
`skills add`(默认 project scope)与 `npm create teamix-evo` **不会**自动装本 skill —— bulk 模式按 scope 自动跳过(ADR 0033)。如果用户在项目级显式 `skills add teamix-evo-manage --scope project`,CLI 给出"推荐 global"warning 但仍装入(用户自负责),代价是后续 IDE 会同时识别全局与项目两份副本。
|
|
@@ -48,6 +50,15 @@ npx teamix-evo@latest skills update --dry-run # 预览,不写盘
|
|
|
48
50
|
|
|
49
51
|
<!-- teamix-evo:managed:start id="core" -->
|
|
50
52
|
|
|
53
|
+
## HARD GATE 协议
|
|
54
|
+
|
|
55
|
+
> 本 skill 中标注 `⚠️ HARD GATE` 的步骤是**强制执行点**，客户侧 AI **必须**在该步骤执行完毕并得到用户确认后才能继续。
|
|
56
|
+
>
|
|
57
|
+
> - **不得跳过**：即使用户说"全部跳过"，也必须逐项告知 HARD GATE 步骤的存在并征得显式确认
|
|
58
|
+
> - **不得合并**：多个 HARD GATE 步骤不得合并为一次性批量执行
|
|
59
|
+
> - **不得软化**：不能将"必须"改述为"建议"或"按需"
|
|
60
|
+
> - **事实留痕**：每个 HARD GATE 步骤完成后，必须更新 `.teamix-evo/init-checklist.md` 对应项的状态
|
|
61
|
+
|
|
51
62
|
## 决策树(动手前必看)
|
|
52
63
|
|
|
53
64
|
```text
|
|
@@ -79,45 +90,51 @@ npx teamix-evo@latest skills update --dry-run # 预览,不写盘
|
|
|
79
90
|
|
|
80
91
|
CLI 二进制名 `teamix-evo`（+ 脚手架独立二进制 `create-teamix-evo`）。概览表列出所有子命令与一句话用途；**完整选项请跑 `--help` 或调 MCP 工具动态获取**（见表后说明）。
|
|
81
92
|
|
|
82
|
-
| Group | Verb | 用途
|
|
83
|
-
| ------------- | ----------------------------------------------------- |
|
|
84
|
-
| **create** | `npm create teamix-evo [dir]`
|
|
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（
|
|
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 保留，
|
|
93
|
-
| | `uninstall` | 卸载 tokens
|
|
94
|
-
|
|
|
95
|
-
| | `
|
|
96
|
-
| | `
|
|
97
|
-
| | `
|
|
98
|
-
| | `
|
|
99
|
-
|
|
|
100
|
-
| | `
|
|
101
|
-
|
|
|
102
|
-
| | `
|
|
103
|
-
| | `
|
|
104
|
-
| | `
|
|
105
|
-
|
|
|
106
|
-
|
|
|
107
|
-
| | `
|
|
108
|
-
| | `
|
|
109
|
-
|
|
|
110
|
-
| | `
|
|
111
|
-
|
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
| | `
|
|
93
|
+
| Group | Verb | 用途 |
|
|
94
|
+
| ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
95
|
+
| **create** | `npm create teamix-evo [dir] [-y]` | 一站式脚手架：scaffold + tokens + skills + ui + lint（`-y` 跳过交互走推荐默认） |
|
|
96
|
+
| **init** | `init [-y] [--dry-run] [--variant <v>] [--cwd <dir>]` | 普通版接入：把 teamix-evo 注入已有 npm 工程（三分支决策树 + 6 类冲突检测 + wizard） |
|
|
97
|
+
| **update** | `update [--dry-run] [--cwd <dir>]` | 套件级升级 orchestrator：tokens → skills（ADR 0019） |
|
|
98
|
+
| **switch** | `switch <new-variant> [--apply] [-y] [--cwd <dir>]` | 切到目标 variant：dry-run 默认，`--apply` 才真写；自动 snapshot + token rename hint |
|
|
99
|
+
| **restore** | `restore [<ts>] [--list] [-y] [--cwd <dir>]` | 失败回滚：从 snapshot 还原 `.teamix-evo/`，pre-restore 自身可逆（ADR 0019 §2） |
|
|
100
|
+
| **tokens** | `init <variant>` | 初始化指定变体的 design tokens（`<variant>` 必填） |
|
|
101
|
+
| | `list-variants` | 列出所有可选变体 |
|
|
102
|
+
| | `list` | 列出已装 tokens 资源 |
|
|
103
|
+
| | `update` | 刷新 regenerable tokens（frozen 保留，ADR 0003） |
|
|
104
|
+
| | `uninstall` | 卸载 tokens |
|
|
105
|
+
| | `audit` | 审计 `tokens.overrides.css`：冗余 / 有效 / 推荐迁移 / 项目特有（v3↔v4 语义比较） |
|
|
106
|
+
| | `diagnose` | 分级治理报告：跑 lint → 按 L1/L2/L3 分类 → 产出 `.treatment-plan.md`（ADR 0042） |
|
|
107
|
+
| | `treat` | 一键流水线：按 diagnose 顺序执行 codemod → 前后基线对比 → 降幅报告（ADR 0042） |
|
|
108
|
+
| | `reflect` | Token 反哺：检测频次 ≥ 3 的业务色值 → 提议命名 → 写入 overrides（ADR 0042） |
|
|
109
|
+
| | `codemod <name>` | 单独跑指定 codemod（hsl-to-v4 / hex-to-token / tw-scale-to-semantic / space-to-gap / arbitrary-to-token） |
|
|
110
|
+
| **skills** | `init` | 自举：按 variant + scope 装全部匹配 skill（ADR 0034 verb 分工） |
|
|
111
|
+
| | `add <name...>` | 增量装指定 skill |
|
|
112
|
+
| | `list` (alias `ls`) | 列出全部 skill（`--installed` 仅已装） |
|
|
113
|
+
| | `update [name...]` | 升级已装 skill（ADR 0035 双闸 + `--scope` + `--dry-run`） |
|
|
114
|
+
| | `uninstall [ids...]` | 卸载 skill |
|
|
115
|
+
| | `doctor` | 检测 source ↔ IDE 镜像漂移（ADR 0013） |
|
|
116
|
+
| | `sync [name...]` | 重新镜像到 IDE 路径（不升版本） |
|
|
117
|
+
| **ui** | `init` | 初始化 ui 配置（aliases / icon / tsx / rsc） |
|
|
118
|
+
| | `add <id...>` | 安装 UI 组件（auto-resolve registryDependencies，frozen） |
|
|
119
|
+
| | `list` | 列出 UI 组件（`--installed` / `--include-deprecated`） |
|
|
120
|
+
| | `upgrade [id...]` | 生成 ui 升级 staging（仅写 `.upgrade-staging/`，ADR 0040；skill 应用） |
|
|
121
|
+
| | `promote-to-biz [ids...]` | 把 ui staging 条目按 8 模式（Coexist/Preset/Wrapper/Compose/Variant/Fork/TokenOnly/ManualReview）落地到 `src/components/business/` + manifest（Init 落地计划 §C.3） |
|
|
122
|
+
| **biz-ui** | `add <id...>` | 安装业务组件（`--variant` 必填） |
|
|
123
|
+
| | `list` | 列出变体下的业务组件 |
|
|
124
|
+
| | `list-variants` | 列出可用业务组件变体 |
|
|
125
|
+
| | `upgrade [id...]` | 生成 biz-ui 升级 staging（变体感知，ADR 0040；skill 应用） |
|
|
126
|
+
| **templates** | `add <id...>` | 安装页面模板（`--variant` 必填）⚠️ AI 默认不主动调用（ADR 0031） |
|
|
127
|
+
| | `list` | 列出变体下的模板 |
|
|
128
|
+
| | `list-variants` | 列出可用模板变体 |
|
|
129
|
+
| **lint** | `init` | 初始化 ESLint + Stylelint token-discipline 规则 |
|
|
130
|
+
| **logs** | `analyze` | 汇总 vibe-logger JSONL（tool / tag / MCP 频次） |
|
|
131
|
+
| | `trace` | 会话级调用链回溯（按 prompt / session 过滤） |
|
|
115
132
|
|
|
116
133
|
> **脚注**
|
|
117
134
|
>
|
|
118
|
-
> - `tokens` / `biz-ui` / `templates` 共享 variant 名空间（
|
|
119
|
-
> - `skills init` vs `add`：init 无 ids = 自举全部匹配 skill；add 必填 ids = 增量（
|
|
120
|
-
> - 源镜像模型（
|
|
135
|
+
> - `tokens` / `biz-ui` / `templates` 共享 variant 名空间（ADR 0014），与 `tokens init` 选定 variant 一致。
|
|
136
|
+
> - `skills init` vs `add`：init 无 ids = 自举全部匹配 skill；add 必填 ids = 增量（ADR 0034）。
|
|
137
|
+
> - 源镜像模型（ADR 0013）：规范副本在 `.teamix-evo/skills-source/`，IDE 镜像在 `.qoder/skills/` 与 `.claude/skills/`。
|
|
121
138
|
|
|
122
139
|
### 动态查询（详细选项 & 实时清单）
|
|
123
140
|
|
|
@@ -159,10 +176,12 @@ npx create-teamix-evo --help # 脚手架帮助
|
|
|
159
176
|
**唯一命令**:
|
|
160
177
|
|
|
161
178
|
```bash
|
|
162
|
-
npm create teamix-evo@latest <dir> --variant <name>
|
|
163
|
-
# 或 pnpm create teamix-evo <dir> --variant <name>
|
|
179
|
+
npm create teamix-evo@latest <dir> --variant <name> -y
|
|
180
|
+
# 或 pnpm create teamix-evo <dir> --variant <name> -y
|
|
164
181
|
```
|
|
165
182
|
|
|
183
|
+
> `-y` 跳过包管理器 / git init 等交互，全部走推荐默认值（pm=auto、git=true）。
|
|
184
|
+
|
|
166
185
|
`create-teamix-evo` 的 `console` preset(默认且当前唯一)会自动一站式落地:
|
|
167
186
|
|
|
168
187
|
| 阶段 | 产物 |
|
|
@@ -246,7 +265,49 @@ CLI 在 partial 状态会打印“恢复指引”面板：失败步骤名、错
|
|
|
246
265
|
|
|
247
266
|
- 已落地的 step 列表 + variant / IDE / scope。
|
|
248
267
|
- `pendingConflictWork`（如有）：批次 4 上线后用 `teamix-evo conflict resolve` 收尾。
|
|
249
|
-
- 全局 entry skill：若 `~/.qoder/skills/teamix-evo-manage` 不存在，补一句 `npx teamix-evo skills add teamix-evo-manage --scope global`（ADR 0033）。
|
|
268
|
+
- 全局 entry skill：若 `~/.qoder/skills/teamix-evo-manage` 不存在，补一句 `npx teamix-evo skills add teamix-evo-manage --scope global -y`（ADR 0033）。
|
|
269
|
+
|
|
270
|
+
### Post-init AI 串场（6 步闭环）
|
|
271
|
+
|
|
272
|
+
> CLI `init` 完成后，末尾会打印 Next Steps 板块，并提示「让 AI 接力」。当用户在 IDE 内触发本 skill 接力时，按以下 6 步顺序走完闭环；每步执行前先告知用户即将做什么，执行后回报关键统计。
|
|
273
|
+
>
|
|
274
|
+
> **前置**：开始前先读 `.teamix-evo/init-checklist.md`（CLI init 自动生成），确认 Phase A（CLI 步骤）已全部 `[x]`，再开始 Phase B。
|
|
275
|
+
|
|
276
|
+
| # | 步骤 | GATE | 命令 / 操作 | 目的 | 何时跳过 |
|
|
277
|
+
| --- | --------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
|
|
278
|
+
| 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/` |
|
|
279
|
+
| 2 | upgrade staging | ⚠️ | `npx teamix-evo ui upgrade`（再 `biz-ui upgrade`） | 生成 `.upgrade-staging/`，每条目带 `featureVector` + `recommendedModes` + `confidence`（ADR 0040） | adopt 0 件 / 全部 frozen 一致 |
|
|
280
|
+
| 3 | tokens audit | ⚠️ | `npx teamix-evo tokens audit` | 4 类输出：冗余删除 / 有效保留 / 推荐迁移 / 项目特有；与 `theme.css` 做 v3↔v4 语义比较 | overrides 0 变量 |
|
|
281
|
+
| 4 | AGENTS.md 回填 | – | 读根 `AGENTS.md` managed 区域之外的内容，按 heading 归类（UI 设计 / 代码研发 / 项目特有），把项目特有规则塞回 managed 区域之前 | 让用户私有规范与 Skills 注入区共存，不被 `init --merge-managed` 覆盖 | 用户文件全为 managed-only |
|
|
282
|
+
| 5 | lint | – | `npx teamix-evo lint init -y`（如未跑）+ `pnpm lint` | token-discipline 兜底；error 数内嵌报告 | 已跑过且 0 error |
|
|
283
|
+
| 6 | token 治理 | ⚠️ | 触发 [`teamix-evo-upgrade`](../teamix-evo-upgrade/SKILL.md) skill Part C（Token treatment pipeline） | 跑 `tokens diagnose` → 按 treatment-plan 逐批 `tokens treat` → 锁基线 | diagnose 报告 0 违规 |
|
|
284
|
+
|
|
285
|
+
> **GATE 列**：`⚠️` = HARD GATE 步骤（见顶部 HARD GATE 协议），必须逐步执行并征得用户确认后才能继续。`–` = 常规步骤，仍需告知用户但可按用户意愿跳过。
|
|
286
|
+
|
|
287
|
+
执行约定：
|
|
288
|
+
|
|
289
|
+
- **每步前**先用一句话告诉用户「即将做什么 + 命令是什么」，等用户回 `OK / 跳过` 再动手；不要批量静默连发。
|
|
290
|
+
- ⚠️ HARD GATE：**HARD GATE 步骤不接受「跳过」**——必须执行或由用户明确说「本步不适用（并说明原因）」。
|
|
291
|
+
- **每步后**汇总数字：`adopted=N foreign=M / staged=K / overrides 删 X 留 Y / AGENTS.md 增 Z 段 / lint error=E / token violations=V`。
|
|
292
|
+
- **每步后必须更新 `.teamix-evo/init-checklist.md`**：把对应步骤从 `[ ]` 改为 `[x]`，附完成时间和关键统计。
|
|
293
|
+
- **遇 ManualReview / foreign / 推荐迁移**：列出来交给用户决策，不替用户改代码。
|
|
294
|
+
- 6 步走完，输出一段 `done` 总结 + 后续可走的命令（`ui promote-to-biz` / `restore` / `update` / `tokens treat`）。
|
|
295
|
+
|
|
296
|
+
#### 第 4 步 AGENTS.md 回填 — 三类分类标准
|
|
297
|
+
|
|
298
|
+
读根 `AGENTS.md` 中 managed 区段 **之外** 的用户手写内容（heading + body），逐段按以下三类归类：
|
|
299
|
+
|
|
300
|
+
| 类别 | 判定条件 | 处理 |
|
|
301
|
+
| -------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
302
|
+
| **A · skill 已覆盖** | 内容与 managed 区段中 skill 注入的段落语义重复（如 UI 组件领地约束、lint 规则说明、触发兜底规则等） | 告知用户「此段已被 skill 覆盖，建议移除以避免冲突」，**需用户确认后才删除** |
|
|
303
|
+
| **B · 业务特有** | 与 skill 无重叠的项目私有规范（如业务命名约定、API 规范、目录结构约束、团队 code review 规则等） | 保留在 managed 区段 **之前**，确保 `init --merge-managed` 不会覆盖 |
|
|
304
|
+
| **C · 不确定** | 无法判断归属，或内容与 skill 部分重叠但有额外信息 | 列出给用户，让用户选择：保留（归 B）/ 移除（归 A）/ 合并进 managed |
|
|
305
|
+
|
|
306
|
+
**操作原则**：
|
|
307
|
+
|
|
308
|
+
- 只移动段落位置（managed 前 vs 后），**不改写用户段落内容**
|
|
309
|
+
- 分类结果逐段告知用户，不要批量静默处理
|
|
310
|
+
- 最终输出统计：`skill 已覆盖=N（已移除 M）/ 业务特有=K（已保留）/ 待决策=J`
|
|
250
311
|
|
|
251
312
|
## 场景 4 · 升级
|
|
252
313
|
|
|
@@ -367,7 +428,7 @@ snapshot 由 `init` / `update` / `variant switch` 在执行前**自动**生成,
|
|
|
367
428
|
- 仅当用户明确表达"恢复到执行前 / 撤销这次升级 / 全部退回"时才走 `restore`。
|
|
368
429
|
- 回滚后告知用户:已执行 `restore <ts>`,本次操作前的状态已存为新 `reason=restore` snapshot 备查。
|
|
369
430
|
|
|
370
|
-
### 4e · 组件源码升级（`teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` —
|
|
431
|
+
### 4e · 组件源码升级（`teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` — ADR 0040）
|
|
371
432
|
|
|
372
433
|
**触发**：用户表达“升级 ui / 升级业务组件 / 升级 button / 看看哪些组件有新版 / upgrade ui / upgrade biz-ui / stage ui upgrade”等关键词。
|
|
373
434
|
|
|
@@ -416,6 +477,70 @@ npx teamix-evo biz-ui upgrade --apply # 错误：CLI 不写 src，guidance
|
|
|
416
477
|
- 不要听到“升级 ui”就打 `ui add` — `add` 是装进去，`upgrade` 是已装后追上上游。
|
|
417
478
|
- 不要在 `shadcn-native` lineage 强行跳 staging；CLI 跳过是预期行为。
|
|
418
479
|
|
|
480
|
+
### 4f · 组件源码 promotion（`teamix-evo ui promote-to-biz` — Init 落地计划 §C.3 / §C.4）
|
|
481
|
+
|
|
482
|
+
**触发**：用户表达“把 ui 组件融进 biz-ui / 把 button 提级成业务组件 / promote ui to business / 把 staging 里的差异融合到 business 层 / 多模式融合 / wrapper + preset 叠加 / 双轨 coexist / 把上游版和自家版同时保留”等关键词；或在场景 4e 走完 staging 后用户问“能不能直接生成业务包装组件”。
|
|
483
|
+
|
|
484
|
+
> 这是 §4e 的**下游**：4e 只生成 `.upgrade-staging/`，4f 才把条目按 AI 推荐的 `recommendedModes` 真正落地到 `src/components/business/` 并维护 manifest。**条目的 8 模式判定全部由 staging meta 给出**，本 skill 只做分组、确认、转发命令。
|
|
485
|
+
|
|
486
|
+
**一行命令**：
|
|
487
|
+
|
|
488
|
+
```bash
|
|
489
|
+
npx teamix-evo ui promote-to-biz # 默认融合最新 ui-* staging 中所有可自动模式条目
|
|
490
|
+
npx teamix-evo ui promote-to-biz button card # 只融合指定 id
|
|
491
|
+
npx teamix-evo ui promote-to-biz --modes Wrapper,Preset # 强制覆盖 staging 推荐模式
|
|
492
|
+
npx teamix-evo ui promote-to-biz --migrate-imports # Coexist 模式时连带 src/** 改 import 到 legacy-<id>
|
|
493
|
+
npx teamix-evo ui promote-to-biz --keep-original-names # Coexist 模式 export 不前缀化 Legacy
|
|
494
|
+
npx teamix-evo ui promote-to-biz --dry-run # 计划态：列模式分组 + 文件变更预览，不写盘
|
|
495
|
+
npx teamix-evo ui promote-to-biz --staging-dir <path> # 指定 staging 目录（不指定则取最新 ui-* 目录）
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
**8 模式分组语义**（对应 §C.3）：
|
|
499
|
+
|
|
500
|
+
| Mode | 终结？ | 产物 |
|
|
501
|
+
| -------------- | ------ | -------------------------------------------------------------------------------- |
|
|
502
|
+
| `Coexist` | 是 | `business/legacy-<id>.tsx`（用户版改名 `Legacy<Foo>`）+ `ui/<id>.tsx` 回填上游版 |
|
|
503
|
+
| `Fork` | 是 | `business/<id>.tsx`（直接搬用户版，无上游对应） |
|
|
504
|
+
| `TokenOnly` | 是 | **不创建文件**，引导用户改 `tokens/tokens.overrides.css` |
|
|
505
|
+
| `ManualReview` | 是 | **不创建文件**，列入待办交用户决策 |
|
|
506
|
+
| `Preset` | 可叠加 | `business/<id>.tsx` import 上游 + `defaultProps` |
|
|
507
|
+
| `Wrapper` | 可叠加 | `business/<id>.tsx` 包装上游 + 业务 state/effect |
|
|
508
|
+
| `Variant` | 可叠加 | `business/<id>.tsx` 扩展上游 cva（上游未 export → 触发 ManualReview） |
|
|
509
|
+
| `Compose` | 可叠加 | `business/<id>.tsx` 拼装多个上游原子 |
|
|
510
|
+
|
|
511
|
+
> 叠加规则：`Coexist` / `Fork` / `TokenOnly` / `ManualReview` 互斥（终结）；`Preset + Wrapper + Variant + Compose` 任意组合，叠加顺序内 → 外为 `variant > wrapper > preset`。
|
|
512
|
+
|
|
513
|
+
**AI 引导决策树（5 步闭环）**：
|
|
514
|
+
|
|
515
|
+
1. **读 staging meta** —— 让 CLI 帮拿（`teamix-evo ui upgrade` 输出 staging 路径），打开 `.teamix-evo/.upgrade-staging/<latest-ui-*>/meta.json` 阅读所有 entries 的 `id` / `recommendedModes` / `confidence` / `reasons` / `featureVector`。
|
|
516
|
+
2. **按主模式分组展示** —— 取每个 entry 的第一个 mode 作为分组键；列表给用户：
|
|
517
|
+
- `Coexist (3): button, dialog, dropdown-menu` → 双轨并存，会改 import 路径
|
|
518
|
+
- `Wrapper+Preset (2): card, badge` → 业务包装 + 默认值
|
|
519
|
+
- `TokenOnly (4): separator, label, ...` → 只需改 tokens.overrides.css
|
|
520
|
+
- `ManualReview (1): table` → 置信度 < 0.6，需要用户先看 diff
|
|
521
|
+
3. **每组逐一询问** —— 对每组先展示 `current.tsx` ↔ `incoming.tsx` 关键 diff（用户要看才展），再问“是否按推荐模式 promote？yes/no/调整模式”。
|
|
522
|
+
- 用户改模式时复述新 mode list，再调 `--modes` 参数。
|
|
523
|
+
- `Coexist` 分组要明确告诉用户：默认**不**重写既有 `import .../ui/<id>` 引用，加 `--migrate-imports` 才统改为 `legacy-<id>`。
|
|
524
|
+
4. **逐组调 promote-to-biz** —— 每组一次命令调用，传该组所有 id；先 `--dry-run` 看 FileChange 四桶（new/modified/deleted/backed-up），用户 OK 后去 dry-run 真写。
|
|
525
|
+
5. **收尾输出未处理 + import skipped 清单** —— 命令结束后复述：
|
|
526
|
+
- `manualReview: [...]` 让用户人工抉择（看 diff 或拆 family）
|
|
527
|
+
- `tokenOnly: [...]` 引导走场景 6 / `tokens audit`
|
|
528
|
+
- `importRewrite.skipped: [{file, line, reason}]` 列出动态 import / 别名 export / 模板字符串这些 regex 重写不到的位置，让用户人工处理
|
|
529
|
+
- `failed: [...]`（如果有）逐条说明失败原因
|
|
530
|
+
|
|
531
|
+
**身份划分清单**：
|
|
532
|
+
|
|
533
|
+
- **CLI（`ui promote-to-biz`）**：执行备份、写 `business/`、回填 `ui/`、按 spec 重写 `src/**` 静态 import、改 manifest（promoted 资源记入虚拟包 `@teamix-evo/biz-ui-promoted`）。
|
|
534
|
+
- **AI（本 skill）**：读 meta、分组、展示 diff、征用户同意、转命令；**不**自己写文件、**不**自己改 import。
|
|
535
|
+
- **`teamix-evo-upgrade` skill**：管 §4e staging → src 的 1:1 替换；**不**做模式分流，本场景才做。
|
|
536
|
+
|
|
537
|
+
**不要**：
|
|
538
|
+
|
|
539
|
+
- 不要绕过 staging 直接调 `promote-to-biz`：CLI 拒收（命令依赖 staging meta）。
|
|
540
|
+
- 不要把 `Coexist` 当 `Replace` 用：默认双轨，旧 import **不**自动迁移，要 `--migrate-imports`；并且 export 默认前缀 `Legacy`，要 `--keep-original-names` 才保留原名。
|
|
541
|
+
- 不要忽略 `importRewrite.skipped`：那批位置 CLI 故意放弃，必须告诉用户人工处理（dynamic-import / 别名 re-export / 模板字符串）。
|
|
542
|
+
- 不要建议用户手改 `manifest.json`：promoted 登记由 CLI 写，污染了走 `restore`。
|
|
543
|
+
|
|
419
544
|
## 场景 5 · 卸载
|
|
420
545
|
|
|
421
546
|
**触发**:用户说"卸载 teamix-evo / remove the design system"。
|
|
@@ -440,14 +565,15 @@ npx teamix-evo biz-ui upgrade --apply # 错误：CLI 不写 src，guidance
|
|
|
440
565
|
|
|
441
566
|
## 常见错误与恢复路径(P8 — failures must be observable)
|
|
442
567
|
|
|
443
|
-
| 症状 | 原因
|
|
444
|
-
| -------------------------------------------------- |
|
|
445
|
-
| `Unknown tokens variant "..."` | 拼写错误或上游未发布该 variant
|
|
446
|
-
| `Target directory already contains a .teamix-evo/` | 误用 `npm create teamix-evo` 进已装目录
|
|
447
|
-
| `UI not initialized`(跑 `ui add` 时) | 未先跑 `ui init`
|
|
448
|
-
| Vite/Tailwind 跑起来没样式 | `src/index.css` 缺少 tokens / Tailwind 导入
|
|
449
|
-
| Skills 在 IDE 不触发 | `.qoder/skills/` 或 `.claude/skills/` 漂移
|
|
450
|
-
| 想完全回退 `init` / `update` 这次执行 | partial / 升级后想撤销到执行前状态
|
|
568
|
+
| 症状 | 原因 | 恢复路径 |
|
|
569
|
+
| -------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
570
|
+
| `Unknown tokens variant "..."` | 拼写错误或上游未发布该 variant | `npx teamix-evo tokens list-variants` 列出当前可用 |
|
|
571
|
+
| `Target directory already contains a .teamix-evo/` | 误用 `npm create teamix-evo` 进已装目录 | 改走场景 4(更新)或场景 3(增量装) |
|
|
572
|
+
| `UI not initialized`(跑 `ui add` 时) | 未先跑 `ui init` | `npx teamix-evo ui init -y` 然后再 `ui add` |
|
|
573
|
+
| Vite/Tailwind 跑起来没样式 | `src/index.css` 缺少 tokens / Tailwind 导入 | 检查 `src/index.css` 的 `@import` 顺序 |
|
|
574
|
+
| Skills 在 IDE 不触发 | `.qoder/skills/` 或 `.claude/skills/` 漂移 | `npx teamix-evo skills doctor` 然后 `skills sync` |
|
|
575
|
+
| 想完全回退 `init` / `update` 这次执行 | partial / 升级后想撤销到执行前状态 | `teamix-evo restore --list` 看可用 snapshot,然后 `teamix-evo restore <ts>`(回滚自身可逆 — ADR 0019 §2) |
|
|
576
|
+
| `init` 卡在多选 IDE / wizard 环节 | @clack multiselect 交互不熟悉(空格=切换选中,回车=提交) | 命令加 `-y` 跳过全部交互（推荐）；或在 multiselect 界面用 `空格` 切换选项、`回车` 提交 |
|
|
451
577
|
|
|
452
578
|
<!-- teamix-evo:managed:end id="core" -->
|
|
453
579
|
|
|
@@ -2,17 +2,29 @@
|
|
|
2
2
|
name: teamix-evo-upgrade
|
|
3
3
|
description: |
|
|
4
4
|
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.
|
|
5
|
-
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}
|
|
5
|
+
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"、"token 治理"、"tokens diagnose"、"tokens treat"、"治理计划"、".treatment-plan.md"、"baseline 锁定"、"token 反哺"、"清理 token 违规"、"token cleanup"、"lint baseline"、"降违规"、"全部治理"; 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; AI sees output of `teamix-evo init` showing token-discipline ESLint warnings and the user wants to clean up; user opens any `.teamix-evo/.upgrade-hints/tokens-*.json` or any file under `.teamix-evo/.upgrade-staging/{ui,biz-ui}-*/` or `.teamix-evo/.treatment-plan.md`.
|
|
6
6
|
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.
|
|
7
7
|
Coordinates with: teamix-evo-manage (manage drives the upgrade flow that emits hints + staging; this skill consumes the resulting files).
|
|
8
8
|
---
|
|
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）。如果用户在项目级显式 `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
|
| ------------------- | -------------------------------------------------------------------- | ----------------------------------- |
|
|
@@ -245,12 +257,14 @@ Parse `meta.json`. Pick the opening message based on `lineage`:
|
|
|
245
257
|
|
|
246
258
|
Iterate `entries` and bucket by `riskLevel`:
|
|
247
259
|
|
|
248
|
-
- **`unchanged`** — just announce
|
|
249
|
-
- **`upgradable-low`** —
|
|
260
|
+
- **`unchanged`** — just announce "以下组件未变，跳过" (list ids on one line).
|
|
261
|
+
- **`upgradable-low`** — ⤵️ HARD GATE：仍然逐个展示 diff + y/n，禁止合并为一次性批量确认。速度优先时可缩短 diff 显示（只展示 hints 摘要），但每个组件必须独立确认。
|
|
250
262
|
- **`upgradable-medium`** — walk one-by-one with a short hint summary, ask y/n/per-file (see B4).
|
|
251
263
|
- **`risky`** — force per-component review; spell out every `hints[]` entry verbatim before showing the diff.
|
|
252
264
|
- **`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`).
|
|
253
|
-
- **`foreign`** — list separately (
|
|
265
|
+
- **`foreign`** — list separately ("以下组件不在 manifest 中，可能是你手工添加的"), ask whether to register, delete, or leave alone.
|
|
266
|
+
|
|
267
|
+
> **分级原则（B0）**：每个 risk level 必须独立分组展示，不得将不同 risk level 的组件混在同一批次提问。即使用户要求「全部应用」，也必须按 risk level 分组逐个展示。
|
|
254
268
|
|
|
255
269
|
### B4 · Propose & ask (HARD GATE)
|
|
256
270
|
|
|
@@ -268,7 +282,9 @@ For each non-unchanged entry the user has agreed to consider, render the diff wi
|
|
|
268
282
|
|
|
269
283
|
Application = **copy `incoming.tsx` over the file at `current.target`**, atomically. Do not partial-merge — the staging is whole-file.
|
|
270
284
|
|
|
271
|
-
**Never auto-apply.** If the user is silent, default to no.
|
|
285
|
+
**Never auto-apply.** If the user is silent, default to no.
|
|
286
|
+
|
|
287
|
+
⚠️ HARD GATE：即使用户说 "全部接受" / "apply all"，**仍然必须逐文件展示 diff**（每个组件一屏），用户看完后才写入。禁止将多个组件的 diff 合并展示或静默批量应用。
|
|
272
288
|
|
|
273
289
|
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.
|
|
274
290
|
|
|
@@ -296,3 +312,120 @@ If the user wants to **defer** the entire staging (not per-entry skip), leave it
|
|
|
296
312
|
| User says “全部接受” / “apply all” | Still show every diff before applying. Bulk-confirm is fine, **silent apply is not**. |
|
|
297
313
|
| `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. |
|
|
298
314
|
| 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. |
|
|
315
|
+
|
|
316
|
+
# Part C — Token treatment pipeline
|
|
317
|
+
|
|
318
|
+
After `teamix-evo init` lands tokens + ESLint rules, the project often has pre-existing token violations (hardcoded colors, raw Tailwind scales, etc.). The CLI provides a **diagnose → treat → reflect → baseline-lock** pipeline to systematically clean them up. This skill guides the user through it.
|
|
319
|
+
|
|
320
|
+
> **Coordinates with**: Part A (token rename adoption) handles _rename_ hints from upstream version bumps; Part C handles _project-internal_ violations detected by ESLint rules.
|
|
321
|
+
|
|
322
|
+
## When to trigger
|
|
323
|
+
|
|
324
|
+
TRIGGER when: user references "token 治理"、"tokens diagnose"、"tokens treat"、"治理计划"、".treatment-plan.md"、"baseline 锁定"、"token 反哺"、"清理 token 违规"、"token cleanup"、"lint baseline"、"降违规"、AI sees output of `teamix-evo init` showing token-discipline ESLint warnings and the user wants to follow up.
|
|
325
|
+
|
|
326
|
+
SKIP: rename hints (Part A), component source upgrades (Part B), design decisions (defer to design skill).
|
|
327
|
+
|
|
328
|
+
## C1 · Diagnose
|
|
329
|
+
|
|
330
|
+
Run the diagnosis to understand the current violation landscape:
|
|
331
|
+
|
|
332
|
+
```bash
|
|
333
|
+
npx teamix-evo tokens diagnose
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
This produces `.teamix-evo/.treatment-plan.md` — a tiered treatment plan classifying violations into:
|
|
337
|
+
|
|
338
|
+
| Phase | Description | Automation |
|
|
339
|
+
| ---------------- | -------------------------------------------------------------- | ---------- |
|
|
340
|
+
| L1-structure | Token file structure issues (via `tokens audit`) | audit |
|
|
341
|
+
| L2-format | Color format normalisation (`hsl()` → CSS v4) | full-auto |
|
|
342
|
+
| L3-semantic-auto | Tailwind scale → semantic tokens | full-auto |
|
|
343
|
+
| L3-semantic-semi | Arbitrary values → tokens (AI-guided) | semi-auto |
|
|
344
|
+
| L3-manual | Requires human judgment (radius, border, dark mode) | manual |
|
|
345
|
+
| reflect | High-frequency color literals → project-level token candidates | analysis |
|
|
346
|
+
|
|
347
|
+
Present the plan overview to the user and ask which phases they want to tackle now.
|
|
348
|
+
|
|
349
|
+
## C2 · Treat (automated codemods)
|
|
350
|
+
|
|
351
|
+
For full-auto phases (L2 + L3-auto), run the treatment pipeline:
|
|
352
|
+
|
|
353
|
+
```bash
|
|
354
|
+
# Dry-run first (recommended)
|
|
355
|
+
npx teamix-evo tokens treat
|
|
356
|
+
|
|
357
|
+
# Apply changes
|
|
358
|
+
npx teamix-evo tokens treat --apply
|
|
359
|
+
|
|
360
|
+
# Apply + lock baseline
|
|
361
|
+
npx teamix-evo tokens treat --apply --lock-baseline
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
The pipeline executes 4 codemods in order:
|
|
365
|
+
|
|
366
|
+
1. `hsl-to-v4` — HSL function → CSS v4 color syntax
|
|
367
|
+
2. `hex-to-token` — hardcoded hex → semantic token reference
|
|
368
|
+
3. `tw-scale-to-semantic` — raw Tailwind color scale → semantic class
|
|
369
|
+
4. `space-to-gap` — space utility → gap utility
|
|
370
|
+
|
|
371
|
+
After execution, a treatment report is generated at `.teamix-evo/.treatment-reports/<timestamp>.md` showing per-rule before/after deltas.
|
|
372
|
+
|
|
373
|
+
### Workflow
|
|
374
|
+
|
|
375
|
+
1. **Always dry-run first** — show the user the match counts and ask for confirmation
|
|
376
|
+
2. Show the delta table from the report
|
|
377
|
+
3. If the user approves, re-run with `--apply`
|
|
378
|
+
4. Ask whether to lock the baseline (`--lock-baseline`)
|
|
379
|
+
|
|
380
|
+
## C3 · Semi-auto treatment (AI-guided)
|
|
381
|
+
|
|
382
|
+
For `L3-semantic-semi` violations (`no-arbitrary-tw-value`):
|
|
383
|
+
|
|
384
|
+
1. Read the treatment plan's L3-semi section for the list of violations
|
|
385
|
+
2. For each violation, read the file context and suggest the closest semantic token
|
|
386
|
+
3. Present a diff hunk per file (same template as Part A step 4)
|
|
387
|
+
4. **HARD GATE** — never auto-apply; get per-file confirmation
|
|
388
|
+
|
|
389
|
+
## C4 · Reflect (token 反哺)
|
|
390
|
+
|
|
391
|
+
After automated treatment, remaining `no-color-literal` violations often reveal project-specific colors not covered by the design system. Suggest the user run reflect analysis:
|
|
392
|
+
|
|
393
|
+
1. Scan remaining violations and cluster by color value + frequency
|
|
394
|
+
2. Present a table of candidates (color → suggested token name → occurrence count → files)
|
|
395
|
+
3. Colors appearing ≥ 3 times are candidates for project-level tokens
|
|
396
|
+
4. Guide the user to add chosen tokens to `tokens/tokens.overrides.css`
|
|
397
|
+
5. After adding tokens, re-run `tokens treat` to pick up the new mappings
|
|
398
|
+
|
|
399
|
+
## C5 · Baseline lock
|
|
400
|
+
|
|
401
|
+
Once the user is satisfied with the treatment level:
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
npx teamix-evo tokens treat --apply --lock-baseline
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
This writes `.teamix-evo/tokens-baseline.json` — a snapshot of current violation counts. Future `tokens treat` runs will compare against this baseline.
|
|
408
|
+
|
|
409
|
+
**CI integration**: add to `package.json` scripts:
|
|
410
|
+
|
|
411
|
+
```json
|
|
412
|
+
{
|
|
413
|
+
"scripts": {
|
|
414
|
+
"lint:baseline": "teamix-evo tokens treat --lock-baseline && git diff --exit-code .teamix-evo/tokens-baseline.json"
|
|
415
|
+
}
|
|
416
|
+
}
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
If violations exceed the locked baseline, CI fails — preventing regression.
|
|
420
|
+
|
|
421
|
+
## C6 · Edge cases
|
|
422
|
+
|
|
423
|
+
| Situation | Response |
|
|
424
|
+
| ------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
425
|
+
| No ESLint config / teamix-evo rules not installed | Tell the user to run `teamix-evo init` first to set up the lint rules. |
|
|
426
|
+
| No `src/` directory | Ask which directory to scan; default to `packages/*/src` in monorepo. |
|
|
427
|
+
| Codemod not found | Skip gracefully; the pipeline only runs available codemods. |
|
|
428
|
+
| User wants to skip a phase | Respect the choice; only run requested phases. |
|
|
429
|
+
| Baseline already exists | Show current vs baseline comparison before re-locking. |
|
|
430
|
+
| Treatment report shows 0 delta | All violations are either semi-auto or manual; guide user to C3/C4. |
|
|
431
|
+
| User says "全部治理" | Run diagnose → treat --apply → reflect in sequence, but confirm each step. |
|