@teamix-evo/skills 0.8.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 +3 -3
- package/package.json +1 -1
- package/src/teamix-evo-design-opentrek/boundaries.md +7 -1
- 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/rules/boundaries.rules.json +10 -0
- package/src/teamix-evo-manage/SKILL.md +78 -36
- package/src/teamix-evo-upgrade/SKILL.md +127 -6
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,8 +70,8 @@
|
|
|
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",
|
package/package.json
CHANGED
|
@@ -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 组件选型表
|
|
@@ -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 组件选型表
|
|
@@ -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
|
|
@@ -81,33 +92,38 @@ CLI 二进制名 `teamix-evo`（+ 脚手架独立二进制 `create-teamix-evo`
|
|
|
81
92
|
|
|
82
93
|
| Group | Verb | 用途 |
|
|
83
94
|
| ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
84
|
-
| **create** | `npm create teamix-evo [dir]`
|
|
95
|
+
| **create** | `npm create teamix-evo [dir] [-y]` | 一站式脚手架：scaffold + tokens + skills + ui + lint（`-y` 跳过交互走推荐默认） |
|
|
85
96
|
| **init** | `init [-y] [--dry-run] [--variant <v>] [--cwd <dir>]` | 普通版接入：把 teamix-evo 注入已有 npm 工程（三分支决策树 + 6 类冲突检测 + wizard） |
|
|
86
|
-
| **update** | `update [--dry-run] [--cwd <dir>]` | 套件级升级 orchestrator：tokens → skills（
|
|
97
|
+
| **update** | `update [--dry-run] [--cwd <dir>]` | 套件级升级 orchestrator：tokens → skills（ADR 0019） |
|
|
87
98
|
| **switch** | `switch <new-variant> [--apply] [-y] [--cwd <dir>]` | 切到目标 variant：dry-run 默认，`--apply` 才真写；自动 snapshot + token rename hint |
|
|
88
99
|
| **restore** | `restore [<ts>] [--list] [-y] [--cwd <dir>]` | 失败回滚：从 snapshot 还原 `.teamix-evo/`，pre-restore 自身可逆（ADR 0019 §2） |
|
|
89
100
|
| **tokens** | `init <variant>` | 初始化指定变体的 design tokens（`<variant>` 必填） |
|
|
90
101
|
| | `list-variants` | 列出所有可选变体 |
|
|
91
102
|
| | `list` | 列出已装 tokens 资源 |
|
|
92
|
-
| | `update` | 刷新 regenerable tokens（frozen 保留，
|
|
103
|
+
| | `update` | 刷新 regenerable tokens（frozen 保留，ADR 0003） |
|
|
93
104
|
| | `uninstall` | 卸载 tokens |
|
|
94
|
-
|
|
|
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 分工） |
|
|
95
111
|
| | `add <name...>` | 增量装指定 skill |
|
|
96
112
|
| | `list` (alias `ls`) | 列出全部 skill（`--installed` 仅已装） |
|
|
97
|
-
| | `update [name...]` | 升级已装 skill（
|
|
113
|
+
| | `update [name...]` | 升级已装 skill（ADR 0035 双闸 + `--scope` + `--dry-run`） |
|
|
98
114
|
| | `uninstall [ids...]` | 卸载 skill |
|
|
99
|
-
| | `doctor` | 检测 source ↔ IDE 镜像漂移（
|
|
115
|
+
| | `doctor` | 检测 source ↔ IDE 镜像漂移（ADR 0013） |
|
|
100
116
|
| | `sync [name...]` | 重新镜像到 IDE 路径（不升版本） |
|
|
101
117
|
| **ui** | `init` | 初始化 ui 配置（aliases / icon / tsx / rsc） |
|
|
102
118
|
| | `add <id...>` | 安装 UI 组件（auto-resolve registryDependencies，frozen） |
|
|
103
119
|
| | `list` | 列出 UI 组件（`--installed` / `--include-deprecated`） |
|
|
104
|
-
| | `upgrade [id...]` | 生成 ui 升级 staging（仅写 `.upgrade-staging/`，
|
|
120
|
+
| | `upgrade [id...]` | 生成 ui 升级 staging（仅写 `.upgrade-staging/`，ADR 0040；skill 应用） |
|
|
105
121
|
| | `promote-to-biz [ids...]` | 把 ui staging 条目按 8 模式（Coexist/Preset/Wrapper/Compose/Variant/Fork/TokenOnly/ManualReview）落地到 `src/components/business/` + manifest（Init 落地计划 §C.3） |
|
|
106
122
|
| **biz-ui** | `add <id...>` | 安装业务组件（`--variant` 必填） |
|
|
107
123
|
| | `list` | 列出变体下的业务组件 |
|
|
108
124
|
| | `list-variants` | 列出可用业务组件变体 |
|
|
109
|
-
| | `upgrade [id...]` | 生成 biz-ui 升级 staging（变体感知，
|
|
110
|
-
| **templates** | `add <id...>` | 安装页面模板（`--variant` 必填）⚠️ AI 默认不主动调用（
|
|
125
|
+
| | `upgrade [id...]` | 生成 biz-ui 升级 staging（变体感知，ADR 0040；skill 应用） |
|
|
126
|
+
| **templates** | `add <id...>` | 安装页面模板（`--variant` 必填）⚠️ AI 默认不主动调用（ADR 0031） |
|
|
111
127
|
| | `list` | 列出变体下的模板 |
|
|
112
128
|
| | `list-variants` | 列出可用模板变体 |
|
|
113
129
|
| **lint** | `init` | 初始化 ESLint + Stylelint token-discipline 规则 |
|
|
@@ -116,9 +132,9 @@ CLI 二进制名 `teamix-evo`（+ 脚手架独立二进制 `create-teamix-evo`
|
|
|
116
132
|
|
|
117
133
|
> **脚注**
|
|
118
134
|
>
|
|
119
|
-
> - `tokens` / `biz-ui` / `templates` 共享 variant 名空间（
|
|
120
|
-
> - `skills init` vs `add`：init 无 ids = 自举全部匹配 skill；add 必填 ids = 增量（
|
|
121
|
-
> - 源镜像模型（
|
|
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/`。
|
|
122
138
|
|
|
123
139
|
### 动态查询（详细选项 & 实时清单）
|
|
124
140
|
|
|
@@ -160,10 +176,12 @@ npx create-teamix-evo --help # 脚手架帮助
|
|
|
160
176
|
**唯一命令**:
|
|
161
177
|
|
|
162
178
|
```bash
|
|
163
|
-
npm create teamix-evo@latest <dir> --variant <name>
|
|
164
|
-
# 或 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
|
|
165
181
|
```
|
|
166
182
|
|
|
183
|
+
> `-y` 跳过包管理器 / git init 等交互，全部走推荐默认值（pm=auto、git=true）。
|
|
184
|
+
|
|
167
185
|
`create-teamix-evo` 的 `console` preset(默认且当前唯一)会自动一站式落地:
|
|
168
186
|
|
|
169
187
|
| 阶段 | 产物 |
|
|
@@ -247,26 +265,49 @@ CLI 在 partial 状态会打印“恢复指引”面板：失败步骤名、错
|
|
|
247
265
|
|
|
248
266
|
- 已落地的 step 列表 + variant / IDE / scope。
|
|
249
267
|
- `pendingConflictWork`（如有）：批次 4 上线后用 `teamix-evo conflict resolve` 收尾。
|
|
250
|
-
- 全局 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 步闭环）
|
|
251
271
|
|
|
252
|
-
|
|
272
|
+
> CLI `init` 完成后，末尾会打印 Next Steps 板块，并提示「让 AI 接力」。当用户在 IDE 内触发本 skill 接力时，按以下 6 步顺序走完闭环；每步执行前先告知用户即将做什么，执行后回报关键统计。
|
|
273
|
+
>
|
|
274
|
+
> **前置**：开始前先读 `.teamix-evo/init-checklist.md`（CLI init 自动生成），确认 Phase A（CLI 步骤）已全部 `[x]`，再开始 Phase B。
|
|
253
275
|
|
|
254
|
-
|
|
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 违规 |
|
|
255
284
|
|
|
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 |
|
|
285
|
+
> **GATE 列**：`⚠️` = HARD GATE 步骤（见顶部 HARD GATE 协议），必须逐步执行并征得用户确认后才能继续。`–` = 常规步骤，仍需告知用户但可按用户意愿跳过。
|
|
263
286
|
|
|
264
287
|
执行约定：
|
|
265
288
|
|
|
266
289
|
- **每步前**先用一句话告诉用户「即将做什么 + 命令是什么」，等用户回 `OK / 跳过` 再动手；不要批量静默连发。
|
|
267
|
-
-
|
|
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]`，附完成时间和关键统计。
|
|
268
293
|
- **遇 ManualReview / foreign / 推荐迁移**：列出来交给用户决策，不替用户改代码。
|
|
269
|
-
-
|
|
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`
|
|
270
311
|
|
|
271
312
|
## 场景 4 · 升级
|
|
272
313
|
|
|
@@ -387,7 +428,7 @@ snapshot 由 `init` / `update` / `variant switch` 在执行前**自动**生成,
|
|
|
387
428
|
- 仅当用户明确表达"恢复到执行前 / 撤销这次升级 / 全部退回"时才走 `restore`。
|
|
388
429
|
- 回滚后告知用户:已执行 `restore <ts>`,本次操作前的状态已存为新 `reason=restore` snapshot 备查。
|
|
389
430
|
|
|
390
|
-
### 4e · 组件源码升级（`teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` —
|
|
431
|
+
### 4e · 组件源码升级（`teamix-evo ui upgrade` / `teamix-evo biz-ui upgrade` — ADR 0040）
|
|
391
432
|
|
|
392
433
|
**触发**：用户表达“升级 ui / 升级业务组件 / 升级 button / 看看哪些组件有新版 / upgrade ui / upgrade biz-ui / stage ui upgrade”等关键词。
|
|
393
434
|
|
|
@@ -524,14 +565,15 @@ npx teamix-evo ui promote-to-biz --staging-dir <path> # 指定 staging 目录
|
|
|
524
565
|
|
|
525
566
|
## 常见错误与恢复路径(P8 — failures must be observable)
|
|
526
567
|
|
|
527
|
-
| 症状 | 原因
|
|
528
|
-
| -------------------------------------------------- |
|
|
529
|
-
| `Unknown tokens variant "..."` | 拼写错误或上游未发布该 variant
|
|
530
|
-
| `Target directory already contains a .teamix-evo/` | 误用 `npm create teamix-evo` 进已装目录
|
|
531
|
-
| `UI not initialized`(跑 `ui add` 时) | 未先跑 `ui init`
|
|
532
|
-
| Vite/Tailwind 跑起来没样式 | `src/index.css` 缺少 tokens / Tailwind 导入
|
|
533
|
-
| Skills 在 IDE 不触发 | `.qoder/skills/` 或 `.claude/skills/` 漂移
|
|
534
|
-
| 想完全回退 `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 界面用 `空格` 切换选项、`回车` 提交 |
|
|
535
577
|
|
|
536
578
|
<!-- teamix-evo:managed:end id="core" -->
|
|
537
579
|
|
|
@@ -2,7 +2,7 @@
|
|
|
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
|
---
|
|
@@ -17,7 +17,7 @@ description: |
|
|
|
17
17
|
npx teamix-evo skills add teamix-evo-upgrade --scope global
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
`skills init`（项目级自举）与 `npm create teamix-evo` **不会**自动装本 skill —— bulk 模式按 scope 自动跳过（
|
|
20
|
+
`skills init`（项目级自举）与 `npm create teamix-evo` **不会**自动装本 skill —— bulk 模式按 scope 自动跳过（ADR 0033）。如果用户在项目级显式 `skills add teamix-evo-upgrade --scope project`，CLI 给出「推荐 global」warning 但仍装入（用户自负责），代价是后续 IDE 会同时识别全局与项目两份副本。
|
|
21
21
|
|
|
22
22
|
与 [`teamix-evo-manage`](../teamix-evo-manage/SKILL.md) 同属 lifecycle 工具，分工：manage 负责 orchestration（init / update / switch / 触发 staging 生成），本 skill 负责 staging / hints 的逐文件 hard-gate apply。
|
|
23
23
|
|
|
@@ -257,12 +257,14 @@ Parse `meta.json`. Pick the opening message based on `lineage`:
|
|
|
257
257
|
|
|
258
258
|
Iterate `entries` and bucket by `riskLevel`:
|
|
259
259
|
|
|
260
|
-
- **`unchanged`** — just announce
|
|
261
|
-
- **`upgradable-low`** —
|
|
260
|
+
- **`unchanged`** — just announce "以下组件未变，跳过" (list ids on one line).
|
|
261
|
+
- **`upgradable-low`** — ⤵️ HARD GATE：仍然逐个展示 diff + y/n，禁止合并为一次性批量确认。速度优先时可缩短 diff 显示（只展示 hints 摘要），但每个组件必须独立确认。
|
|
262
262
|
- **`upgradable-medium`** — walk one-by-one with a short hint summary, ask y/n/per-file (see B4).
|
|
263
263
|
- **`risky`** — force per-component review; spell out every `hints[]` entry verbatim before showing the diff.
|
|
264
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`).
|
|
265
|
-
- **`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 分组逐个展示。
|
|
266
268
|
|
|
267
269
|
### B4 · Propose & ask (HARD GATE)
|
|
268
270
|
|
|
@@ -280,7 +282,9 @@ For each non-unchanged entry the user has agreed to consider, render the diff wi
|
|
|
280
282
|
|
|
281
283
|
Application = **copy `incoming.tsx` over the file at `current.target`**, atomically. Do not partial-merge — the staging is whole-file.
|
|
282
284
|
|
|
283
|
-
**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 合并展示或静默批量应用。
|
|
284
288
|
|
|
285
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.
|
|
286
290
|
|
|
@@ -308,3 +312,120 @@ If the user wants to **defer** the entire staging (not per-entry skip), leave it
|
|
|
308
312
|
| User says “全部接受” / “apply all” | Still show every diff before applying. Bulk-confirm is fine, **silent apply is not**. |
|
|
309
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. |
|
|
310
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. |
|