@teamix-evo/mcp 0.3.0 → 0.4.2

package/dist/data/adr/0026-component-level-token-alias.md

@@ -0,0 +1,107 @@
+# 0026. 组件级 token 别名(`--radius-{component}` 等)的创建准则
+
+- **Status**: Accepted
+- **Date**: 2026-06-02
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [ADR 0020](0020-design-to-tokens-skill-fusion.md)(tokens 包 / skill 边界) · [ADR 0022](0022-preferences-css-boundary.md)(已 superseded,曾约束 preferences.css 不放 token alias)
+
+## Context
+
+W4–W5 优化时多次遇到"组件圆角该怎么定义"的问题。早期默认做法是给每个组件加一个语义别名(`--radius-button` / `--radius-dialog` / `--radius-tag` / ...),组件 className 写 `rounded-[var(--radius-X)]` 取值。
+
+后来 Button 优化时发现:**这种 arbitrary value 写法在 Tailwind v4 多包 `@import` 场景下不被自动派生为 utility**(实测 dev server 编译产物中 `.rounded-button { ... }` 规则不生成),组件回退到浏览器默认 8px(脱离 token 链路)。为修这个 bug,Button 改用 Tailwind v4 标准 namespace token `--radius-md`,直接走 `rounded-md` utility;`--radius-button` 被移除。
+
+此后又因 Dialog 跨变体视觉差异大(opentrek 16px vs uni-manager 2px),发现**纯 scale 无法满足**:无论选哪个 `rounded-X` utility,都没有任何一档能让 opentrek=16 且 uni-manager=2 同时成立。因此 `--radius-dialog` 作为组件级别名被保留下来,组件内部使用 `rounded-[var(--radius-dialog)]` 语法。
+
+这暴露了两类完全不同的 token 角色:
+
+| 层 | 类型 | 例子 | 谁定义 | 谁消费 |
+| --- | --- | --- | --- | --- |
+| Layer 1 | scale primitives | `--radius-sm` / `--radius-md` / `--radius-lg` / `--radius-xl` / `--radius-2xl` | 各 variant 可独立覆盖 | 所有组件,通过 Tailwind 标准 utility `rounded-{sm\|md\|lg\|xl\|2xl}` |
+| Layer 2 | 组件语义别名 | `--radius-dialog` / `--radius-tag` | 各 variant 可独立覆盖 | 仅该组件,通过 `rounded-[var(...)]` arbitrary value |
+
+ADR 0022(已 superseded)曾约束"preferences.css 边界",但没有规范"什么时候可以加 Layer 2 别名"。本 ADR 补这一条。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| --- | --- | --- |
+| A. 严格一层 — 所有组件走 scale,不允许 Layer 2 | token 架构最简 / 一致性最强 | 跨变体视觉差异大的组件被强制对齐,失去变体差异化能力(opentrek Dialog 必须从 16 收到 6,失去"圆润"视觉特征) |
+| B. **二层模式 — 优先 scale,严控 Layer 2 创建条件(推荐)** | scale 是默认路径(简单);Layer 2 作为 escape hatch,有明确触发条件 | 需要 ADR 守门;否则 Layer 2 会无序蔓延变成"杂物间" |
+| C. 全自由 — 任何组件都可加 `--radius-{name}` | 最大灵活性 | 跟 ADR 之前踩坑的"AI / 业务工程不知道该用哪个 token"反模式重合;token 数量爆炸 |
+
+## Decision
+
+**采纳选项 B** — 二层模式,Layer 2 创建有硬性触发条件。
+
+### 规则 A — 默认走 Layer 1 scale(Tailwind v4 namespace)
+
+新增组件 / 优化组件时,**圆角默认**写:
+
+```tsx
+className="rounded-md"  // 走 --radius-md (uni-manager 2 / opentrek 6 / Tailwind 默认 6)
+className="rounded-lg"  // 走 --radius-lg (uni-manager 4 / opentrek 8 / Tailwind 默认 8)
+```
+
+各 variant 在 `@theme {}` 块里覆盖 `--radius-sm/md/lg/xl/2xl` 满足该 variant 的视觉调性。
+
+**禁止** `rounded-[6px]` / `rounded-[var(--xxx)]` 等 arbitrary value(除非满足规则 B 的硬条件)。
+
+### 规则 B — 满足以下**全部**条件才可创建 Layer 2 别名
+
+| # | 条件 | 备注 |
+| --- | --- | --- |
+| 1 | 跨变体的目标值**无法被同一个 scale 档同时满足** | 例:Dialog 在 opentrek 想要 16px,uni-manager 想要 2px。无任何 `rounded-{sm\|md\|lg\|xl\|2xl}` 在两个 variant 同时落到这两个值 |
+| 2 | 该组件视觉**确实有跨变体差异化的设计意图**,不是 token 命名洁癖 | 例:Dialog 跨变体差异是"圆润感 vs 锐利感"的设计语言,非可省略 |
+| 3 | 不能通过组合 `cn()` / 变体 className 实现 | 同一 `<Dialog>` 源码不能写"变体感知 className",所以 Dialog 必须有 token alias |
+| 4 | 命名清晰指向具体组件 | `--radius-{component-id}`,如 `--radius-dialog` / `--radius-tag` |
+
+不满足全部 4 条 → **走 Layer 1 scale**。
+
+### 规则 C — 现存 Layer 2 别名 audit(本 ADR 落地时)
+
+| Token | 状态 | 理由 |
+| --- | --- | --- |
+| `--radius-button` | **已移除**(W1-Button 优化时) | 走 `rounded-md` 即可(uni 2 / opentrek 6 / 标准 6),无变体差异化需求 |
+| `--radius-dialog` | **保留** | uni 2 / opentrek 16 跨档不可对齐;有"圆润 vs 锐利"设计语言差异;Dialog/AlertDialog/Sheet 共享 |
+| `--radius-tag` | **保留** | uni 4 / opentrek 4(同值但不在任一 variant 的同一 scale 档:opentrek `rounded-sm`=4 ✓ / uni `rounded-sm`=0 ✗);需 alias 才能跨变体对齐 |
+
+### 规则 D — 同样模式适用于其他 token namespace
+
+本 ADR 围绕 `--radius-*` 描述,但同样规则适用于 `--shadow-*` / `--spacing-*` / `--color-*` 等:
+
+- **Layer 1 scale** 是首选(`--shadow-sm/md/lg/xl/2xl`、Tailwind v4 标准 spacing scale)
+- **Layer 2 组件语义别名** 仅在满足规则 B 全部 4 条时创建
+- 既有的 `--shadow-form-hover` / `--color-input-focus`(ADR 0023 引入)按此审视:它们是"form 控件 hover/focus 共用语义",跨多组件使用 → 不是单组件别名 → **算 Layer 1.5(semantic primitive)**,不违反本 ADR
+
+## Consequences
+
+### 工程影响
+
+- 新增组件 / 优化既有组件时,**圆角默认走 scale**,不再随手加 `--radius-{name}`
+- 已存在的 `--radius-dialog` / `--radius-tag` 保留(满足规则 B);未来 audit 时按规则审视
+- ADR 设计 skill checklist 不新增条目(本 ADR 是架构层规则,不需要逐组件检查)
+- AI / 人工新增组件 review 时:看到 `--radius-{name}` 自定义别名 → 必须能在 PR 描述里讲清楚满足规则 B 哪 4 条;说不清 → 改走 scale
+
+### 反模式(后续 PR 不接受)
+
+```tsx
+// ❌ 无变体差异化诉求的随手 alias
+--radius-input-group: 4px;
+className="rounded-[var(--radius-input-group)]"
+
+// ✅ 应该写
+className="rounded-md"  // uni 2 / opentrek 6
+```
+
+### 与现有 ADR 关系
+
+- 取代 [ADR 0022](0022-preferences-css-boundary.md) 中"preferences.css 不放 token alias"的零散约束(那个文件已删,但精神保留)
+- 与 [ADR 0023](0023-cursor-pointer-explicit-in-component-source.md) 关于 cursor 的显式声明、[ADR 0025](0025-component-props-explicit-declaration.md) 关于 props 显式声明并列,共同构成"AI-first 组件库"的工程约束
+
+## Source
+
+- 真实案例 1:Button `--radius-button` Tailwind v4 自定义 namespace 无 utility 派生 bug(W1-Button 优化时记录的"Tailwind 自定义 utility 在分层引入模式下不生效" 记忆)
+- 真实案例 2:Dialog 跨变体视觉差异(opentrek 16 / uni-manager 2)无 scale 单档可对齐
+- 真实案例 3:Tag 跨变体同值(4)但 scale 档不对齐(opentrek `rounded-sm`=4 / uni `rounded-sm`=0)
+- 用户 review 反馈(2026-06-02):"按照理念不应该定义一批圆角的变量供所有组件使用,而不是单独定义某个组件?"

package/dist/data/adr/0027-component-visual-token-alignment.md

@@ -0,0 +1,127 @@
+# 0027. 组件视觉属性全轴对齐设计系统基线
+
+- **Status**: Partially superseded by [ADR 0032](./0032-opentrek-v4.1-brand-token-alignment.md)（opentrek radius 档位升级，本 ADR 表 1 中 opentrek 列已不准）
+- **Date**: 2026-06-02
+- **Region**: 0001–0099 工程哲学
+- **Related ADR**: 0010 (design-default-and-variants), 0026 (component-level-token-alias), 0032 (opentrek-v4.1-brand-token-alignment)
+
+## Context
+
+cd hybridcloud 主题为所有组件定义了明确的视觉基线，涵盖字号、圆角、颜色、阴影等全部轴。审计发现 **大量组件偏离基线**，且两个变体（uni-manager / opentrek）间的 token 覆盖度不一致，导致：
+
+1. 组件在 uni-manager 变体下不符合 cd hybridcloud 视觉规范
+2. opentrek 变体缺少显式 radius 档位定义，依赖 Tailwind 隐式默认值
+3. 特定组件（tag / dialog）需要组件级 token 才能实现跨变体差异化
+
+**cd hybridcloud 基线真值（medium/default 档）：**
+
+| 轴   | Token                | 值           | Tailwind utility                   |
+| ---- | -------------------- | ------------ | ---------------------------------- |
+| 字号 | `--font-size-body-1` | 12px         | `text-xs`                          |
+| 圆角 | `--corner-1`         | 2px          | `rounded-md`（uni-manager 覆盖后） |
+| 阴影 | `--shadow-1`         | 通常无或极淡 | `shadow-sm` / `shadow-none`        |
+| 颜色 | `--color-text1-4`    | 正文色       | `text-foreground`                  |
+
+**偏差审计摘要：**
+
+- **字号**：28 个组件 medium 使用 `text-sm`(14px)，应为 `text-xs`(12px)
+- **圆角**：tag 缺失 rounded / card·alert·sonner 用 `rounded-lg`(4px) / accordion 用 `rounded-sm`(0px)
+- **阴影 / 颜色 / 间距**：待本轮逐项确认
+
+## Options Considered
+
+| 选项                                                                 | 优点                                                   | 缺点                                                                |
+| -------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
+| A. 全组件硬编码修正（直接改 class）                                  | 简单直接，一步到位                                     | opentrek 被迫接受 uni-manager 的值；无法跨变体差异化                |
+| B. Tailwind utility 作为语义层 + 主题 token 控值 + 组件级 token 补充 | 两变体各自表达；组件代码不变即可换肤；特殊组件有逃生舱 | 需补全 opentrek 的 radius scale；需引入少量 `--radius-*` 组件 token |
+| C. 全部走组件级 CSS 变量                                             | 极致灵活                                               | token 膨胀；失去 Tailwind utility-first 优势                        |
+
+## Decision
+
+**采用方案 B**：三层策略覆盖全部视觉属性。
+
+### 1. Tailwind utility 作为通用语义层
+
+组件源码使用 Tailwind 标准 utility（`text-xs`、`rounded-md`、`shadow-sm` 等），各变体通过 `@theme` 中的 CSS 变量定义控制最终视觉值：
+
+| utility      | uni-manager | opentrek                        |
+| ------------ | ----------- | ------------------------------- |
+| `text-xs`    | 12px        | 12px                            |
+| `text-sm`    | 14px        | 14px                            |
+| `rounded-md` | 2px         | 8px ⚠️ ADR 0032 升级（原 6px）  |
+| `rounded-lg` | 4px         | 12px ⚠️ ADR 0032 升级（原 8px） |
+| `shadow-sm`  | 极淡 / 无   | 标准 shadcn                     |
+
+### 2. 组件级 token 处理跨变体差异
+
+当同一组件在不同变体需要**不同档位**的视觉值时，引入组件级 CSS token：
+
+```css
+/* tokens/variants/uni-manager/theme.css */
+--radius-dialog: 2px;
+--radius-tag: 4px;
+
+/* tokens/variants/opentrek/theme.css */
+--radius-dialog: 16px;
+--radius-tag: 4px;
+```
+
+组件使用 `rounded-[var(--radius-dialog)]` 消费。
+
+### 3. 变体 theme.css 必须显式声明全部档位
+
+禁止依赖 Tailwind 隐式默认值。每个变体的 `theme.css` 必须显式声明：
+
+- `--radius-sm` / `--radius-md` / `--radius-lg` / `--radius-xl`
+- `--shadow-sm` / `--shadow-md` / `--shadow-lg`（如有差异）
+- 字号走 Tailwind 默认即可（两变体一致），仅特殊档覆盖
+
+### 4. medium/default 档位对齐规则
+
+| 组件类型                             | 字号                               | 圆角                             | 阴影        |
+| ------------------------------------ | ---------------------------------- | -------------------------------- | ----------- |
+| 表单控件（button/input/select 等）   | `text-xs`                          | `rounded-md`                     | `shadow-sm` |
+| 弹层容器（dialog/sheet/drawer）      | `text-xs`(body) / `text-sm`(title) | `rounded-[var(--radius-dialog)]` | `shadow-lg` |
+| 信息容器（card/alert/notification）  | `text-xs`                          | `rounded-md`                     | `shadow-sm` |
+| 标签类（tag/badge）                  | `text-xs`                          | `rounded-[var(--radius-tag)]`    | 无          |
+| 导航类（tabs/pagination/breadcrumb） | `text-xs`                          | `rounded-md`                     | 无          |
+| 浮层（tooltip/popover/dropdown）     | `text-xs`                          | `rounded-md`                     | `shadow-md` |
+
+### 5. 颜色对齐
+
+颜色已通过 ADR 0021 语义色体系治理，组件使用 `text-foreground` / `bg-background` / `border-input` 等语义 token，由各变体 theme.css 定义具体色值。本 ADR 不重复覆盖，但要求：
+
+- 审计中发现的硬编码色值（如 `text-gray-500`）必须替换为语义 token
+- 组件不得使用 Tailwind 原始色板（`blue-500`、`red-600` 等）
+
+## Consequences
+
+- **Positive**:
+  - 两个变体可独立演进视觉风格，组件源码无需分叉
+  - 统一 medium 基线后视觉一致性显著提升
+  - opentrek 显式声明后，token 值可追溯可审计
+- **Negative**:
+  - 本次修改涉及 30+ 组件源码，需逐组件验证
+  - 少量组件级 token 增加了 theme.css 维护面
+- **Trade-off**:
+  - 为保持 Tailwind utility-first 开发体验，接受组件级 token 仅用于"跨变体确需不同档位"场景；大多数属性走通用 utility
+
+## Source
+
+组件视觉审计对话（2026-06-02）；cd hybridcloud css-var-definition.scss 真值确认。
+
+## Amendment 2026-11（v2 决策块）
+
+OpenTrek 设计源 v4.1（design-tokens.css）发布后，op variant radius 体系按用户决策完整对齐到新文档基线，本 ADR 中 opentrek 列对应数值被覆写：
+
+- `--radius-md`：6px → **8px**
+- `--radius-lg`：8px → **12px**
+- `--radius-xl`：12px → **16px**
+- 新增 `--radius-full: 9999px`
+- 移除 `--radius-2xl`（新文档采 5 档体系）
+
+受影响组件（`rounded-md` / `rounded-lg` 消费点）：Button、Card、Input、Select、Dialog（仅 op，因 dialog 走 `--radius-dialog: 16px` 不变）、Tag（走 `--radius-tag: 4px` 不变）、Pagination 等。
+
+uni-manager 锐利 radius 体系不变（`--radius-md: 2px`、`--radius-lg: 4px`），保持 cd hybridcloud 紧凑视觉。
+
+详细决策与影响面记录在 [ADR 0032](./0032-opentrek-v4.1-brand-token-alignment.md)。本 ADR 三层策略（utility 语义层 / 组件级 token 差异化 / 变体显式声明）继续生效。

package/dist/data/adr/0028-ui-component-categorization.md

@@ -0,0 +1,111 @@
+# 0028. UI 组件分类对齐 Ant Design 5.x + 引入 `deprecated` 类
+
+- **Status**: Accepted
+- **Date**: 2026-06-02
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: 0014 (ui-biz-ui-templates-tier), 0025 (component-props-explicit)
+
+## Context
+
+`@teamix-evo/ui` 包含 87 个组件,既有的分类(`foundation / form / layout / navigation / data-display / feedback / shell` 8 类)散落在 `meta.md` 与 `stories.tsx` 两处,问题:
+
+1. **分类不规范**:`foundation / form / shell` 偏自创,与业界主流体系无对照,新人理解成本高
+2. **错位**:`page-header` meta 标 `layout`、Storybook 标"导航与布局"(混类);多处 meta 与 stories title 不一致
+3. **没有"废弃"类**:仓库里有些组件(`aspect-ratio / image / kbd` 等)研发完成后不打算外发,但仍需在 Storybook 留档;现状是用 `status: "deprecated"` 字段标记,但没有正式分类位
+
+业界主流体系对比:
+
+| 体系               | 类目数    | 类目命名                                                                     |
+| ------------------ | --------- | ---------------------------------------------------------------------------- |
+| **Ant Design 5.x** | 7         | General / Layout / Navigation / Data Entry / Data Display / Feedback / Other |
+| Material UI        | 6         | Inputs / Data Display / Feedback / Surfaces / Navigation / Layout            |
+| Chakra UI          | 7         | Layout / Forms / Data Display / Feedback / Typography / Overlay / Disclosure |
+| shadcn/ui          | 0(字母序) | —                                                                            |
+| Radix UI           | 6         | Form / Layout / Navigation / Overlay / Utilities / Visualization             |
+
+teamix-evo 定位**中后台研发**(opentrek + uni-manager 都是管控台),**Ant Design 5.x 7-类法是中文企业级生态事实标准**,且 ui 包定位本就是 shadcn ∪ antd 合集,采用 AntD 类目最自洽。
+
+## Options Considered
+
+| 选项                                                 | 优点                                                            | 缺点                                                                     |
+| ---------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| A. 保持现状(8 自创类)                                | 不动现存代码                                                    | 分类不专业,新人难理解,与 ui 包"shadcn ∪ antd 合集"定位不匹配             |
+| B. 全盘照搬 AntD 7 类                                | 与业界标准 1:1 对齐,认知零成本                                  | AntD 把 Tooltip/Popover/Tabs 归 Data Display,与团队习惯有偏差            |
+| **C. AntD 7 类 + 引入 `deprecated` 第 8 类(本方案)** | 标准对齐 + 留档诉求满足 + 极少数务实偏离(popover 仍归 feedback) | 需要批量改 87 个 meta.md + 87 个 stories.tsx + manifest.json + storySort |
+
+## Decision
+
+采用方案 C。`@teamix-evo/ui` 组件分为 **7 个正式类目**(对齐 AntD 5.x)+ **1 个废弃归档类**:
+
+### 类目定义
+
+| key            | 中文     | Storybook 前缀             | 含义                                                                         |
+| -------------- | -------- | -------------------------- | ---------------------------------------------------------------------------- |
+| `general`      | 通用     | `通用 · General/`          | 任何 UI 都需要的基础原子(Button / Icon / Typography)                         |
+| `layout`       | 布局     | `布局 · Layout/`           | 空间结构与容器骨架(Flex / Grid / Space / Separator / Sidebar / PageHeader …) |
+| `navigation`   | 导航     | `导航 · Navigation/`       | 寻路与跳转(Breadcrumb / Pagination / DropdownMenu / Steps …)                 |
+| `data-entry`   | 数据录入 | `数据录入 · Data Entry/`   | 表单输入控件(用户**写入**数据)                                               |
+| `data-display` | 数据展示 | `数据展示 · Data Display/` | 只读数据呈现(用户**读取**数据;含 Tabs / Accordion / Tooltip — 对齐 AntD)     |
+| `feedback`     | 反馈     | `反馈 · Feedback/`         | 状态/中断式反馈(Alert / Dialog / Drawer / Progress / Spinner …)              |
+| `deprecated`   | 废弃     | `废弃 · Deprecated/`       | 仅 Storybook 留档,**不通过 manifest 对外发布**                               |
+
+### 完整组件归类(87 个)
+
+- **general(3)**:button、icon、typography
+- **layout(7)**:flex、grid、page-header、resizable、separator、sidebar、space
+- **navigation(5)**:affix、breadcrumb、dropdown-menu、pagination、steps
+- **data-entry(20)**:auto-complete、cascader、checkbox、color-picker、date-picker、field、filter-bar、form、input、input-number、label、radio-group、rate、select、slider、switch、time-picker、transfer、tree-select、upload
+- **data-display(19)**:accordion、avatar、badge、calendar、card、carousel、collapsible、data-table、descriptions、empty、hover-card、item、statistic、table、tabs、tag、timeline、tooltip、tree
+- **feedback(15)**[^1]:alert、alert-dialog、command、dialog、drawer、notification、popconfirm、popover、progress、result、sheet、skeleton、sonner、spinner、watermark
+- **deprecated(18)**[^1]:已有 — aspect-ratio、image、kbd;新增 — app、anchor、context-menu、float-button、menubar、navigation-menu、tour、toggle-group、toggle、segmented、native-select、mentions、input-otp、scroll-area、masonry
+
+[^1]: 2026-06-02 补丁 — `command` 原拟归 deprecated(“仅 Storybook 留档”),但事实上被 active 的 `select` / `auto-complete` 运行时强 import,不能不外发;同时作为 Combobox / Select / AutoComplete 同源下拉内核(ADR 0029)在架构上起底座作用。故从 deprecated 撤回,与 popover 同档归 `feedback`(反馈式弹层底座),feedback 类目从 14 件变 15 件;deprecated 类目从 19 件变 18 件。
+
+### 与 AntD 的偏离
+
+仅一处务实取舍:`popover` 归 `feedback`(AntD 归 Data Display)。
+理由:teamix-evo 项目里 popover 多与 popconfirm、tooltip、hover-card 同形使用,放一起便于研发认知。其他全部对齐。
+
+### `deprecated` 工程含义("仅展示不外发")
+
+| 链路                           | 行为                                                                                                                             |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| `packages/ui/manifest.json`    | 19 个 deprecated 组件**移出** `entries`,归入新增 `deprecatedEntries` 字段(归档可查)                                              |
+| `teamix-evo ui add <name>` CLI | 默认拒绝安装(报错`Refusing to install deprecated...`);加 `--include-deprecated` 才放行                                           |
+| `teamix-evo ui list` CLI       | 默认隐藏;加 `--include-deprecated` 后 STATUS 列显示 `DEPRECATED` / `INST/DEPR`                                                   |
+| MCP `list_components`          | 默认过滤;传 `includeDeprecated: true` 或 `status: "deprecated"` 才返回(带 `archived: true` 标记)                                 |
+| MCP `find_components`          | 默认不匹配归档项;传 `includeDeprecated: true` 后同时搜索 active + archived                                                       |
+| MCP `get_component_meta`       | 在 `entries` 找不到时自动回退到 `deprecatedEntries`,payload 带 `archived: true`                                                  |
+| `*.stories.tsx`                | 保留,Storybook 侧栏归"废弃 · Deprecated"分组,顶部强制加 banner: `> ⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。` |
+| `*.meta.md`                    | `category: deprecated` 即代表废弃,不需要重复 `deprecated: true` 字段                                                             |
+| `package.json exports` / 构建  | 不调整(源码仍存在,内部仍可 import,只是外部 add 链路屏蔽)                                                                         |
+
+### Storybook 侧栏顺序
+
+`.storybook/preview.ts` 的 `parameters.options.storySort.order` 固定:
+
+```
+设计系统 · Design System  → 类目以外的总览
+通用 · General
+布局 · Layout
+导航 · Navigation
+数据录入 · Data Entry
+数据展示 · Data Display
+反馈 · Feedback
+废弃 · Deprecated
+```
+
+## Consequences
+
+- **Positive**:
+  - 分类对齐业界标准,新人对照 AntD 文档即可定位组件
+  - `deprecated` 类正式化,留档与外发解耦
+  - manifest.json 的 `deprecatedEntries` 让 MCP 可查"曾经存在过哪些 entry"
+- **Negative**:
+  - 一次性批量改 87 × 2 文件 + manifest + preview,需脚本驱动避免遗漏
+- **Trade-off**:
+  - popover 偏离 AntD 归类,以团队习惯为准
+
+## Source
+
+UI 组件分类对齐讨论(2026-06-02);Ant Design 5.x 官方组件文档 categories;Material UI / Chakra UI / Radix UI 类目对照。

package/dist/data/adr/0029-input-split-and-prefix-suffix-removal.md

@@ -0,0 +1,62 @@
+## Context
+
+历史包袱:`<Input>` 同时承载两套表达"前后缀"的 API:
+
+1. **antd 风格快捷 prop**:`prefix` / `suffix` / `addonBefore` / `addonAfter`
+2. **shadcn 2025-10 复合插槽**:`<InputGroup>` + `<InputGroupAddon>` + `<InputGroupInput>`
+
+此外,Input / Textarea / InputGroup 三件套**合并到同一个 `input` entry**(单一 533 行 .tsx 文件,6 个导出),与 shadcn 2025-10 已拆三个独立组件的方向背离。
+
+引发的问题:
+
+- **API 重叠 → AI 与人类选择困难**:同一个"加搜索图标"的需求,可以写 `<Input prefix={<Search />} />`,也可以写 `<InputGroup><InputGroupAddon variant="icon">...`,文档要解释两套语义,纪律靠注释强行约束。
+- **拷贝粒度过粗**:`teamix-evo ui add input` 强制业务连带拷贝 533 行文件,即使只用单行 Input。
+- **隐性反向依赖**:Textarea 被埋在 `input/` 目录下,AutoComplete / Mentions 等下游通过 `from '@/components/input/input'` 引 Textarea 形成奇怪的导入路径。
+- **跟 shadcn 上游不同步**:shadcn 2025-10 已把 `input` / `textarea` / `input-group` 拆为三个独立组件。我们合在一起,后续每次 sync upstream 都要手工 diff。
+
+平行决策点:`AutoComplete` 当前用自实现 div + `<input>` + `<ul role="listbox">`,与 `Select` 的 `Popover + cmdk Command` 内核完全独立 — 同一种"输入触发候选下拉"的视觉/键盘/a11y 维护两份。
+
+## Options Considered
+
+### 关于 Input / Textarea / InputGroup 拆分
+
+| 选项                                                           | 优点                                                                | 缺点                                    |
+| -------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------- |
+| **A. 现状(三合一 entry + 双 API 并存)**                        | 不动迁移成本                                                        | API 重叠不解;粒度与 shadcn 上游持续偏离 |
+| **B. 拆三个 entry,但 Input 双 API 并存**                       | 与 shadcn 拆分对齐;无 BREAKING                                      | API 重叠未解,纪律仍靠注释               |
+| **C. 拆三个 entry + 移除 Input 的 4 个快捷 prop**(本 ADR 决策) | 与 shadcn 拆分对齐;API 单一职责;消费侧"加图标用 InputGroup"路径唯一 | major BREAKING,业务侧需迁移             |
+
+### 关于 AutoComplete vs Select 关系
+
+| 选项                                                                                 | 优点                                                                                         | 缺点                                                                                                                         |
+| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **D1. 合并 AutoComplete 入 Select(MUI freeSolo 模式)**                               | 减少一个 entry                                                                               | value 域 closed-list vs open-list 语义本质不同,合并后需新 prop 表达,反而模糊;Select 体量与依赖被强加给所有 AutoComplete 用户 |
+| **D2. 保留独立组件 + 内核同源化(改 AutoComplete 用 Popover + Command)**(本 ADR 决策) | 语义独立(antd / Mantine / Chakra / shadcn 主流做法);下拉视觉/a11y/键盘只维护一份;无 BREAKING | 需重构 AutoComplete 内部实现                                                                                                 |
+| D3. 现状(双内核独立)                                                                 | 不动                                                                                         | 同行为维护两份代码                                                                                                           |
+
+## Decision
+
+1. **拆分粒度对齐 shadcn 2025-10**:`Input` / `Textarea` / `InputGroup` 各自独立 `manifest entry`、独立 `<id>/` 目录、独立 stories / meta;CLI 三条命令独立可装(`teamix-evo ui add input` / `add textarea` / `add input-group`)。
+2. **Input 移除 4 个 antd 风格快捷 prop**:`prefix` / `suffix` / `addonBefore` / `addonAfter` 不再支持。"加图标 / 单位 / 协议头 / 按钮" 唯一路径是 `InputGroup` 复合插槽。
+3. **Input 保留 `clearable` / `showCount` / `size` / `error`**:这些不属于"前后缀"语义,是 Input 自身的逻辑能力,继续作为内建属性。
+4. **AutoComplete 内核同源化**:保留 `AutoComplete` 与 `Select` 为独立组件(value 域语义不同 — open-list vs closed-list),但 AutoComplete 改用 `Popover + cmdk Command` 实现内部下拉,与 Select 共享下拉视觉 / 键盘 / a11y。组件外部 API 不变。
+
+## Consequences
+
+- **Positive**:
+  - 三个组件粒度与 shadcn 上游同步,后续 sync 不再 diff
+  - "加前后缀"路径唯一(InputGroup),AI 与人类不再纠结
+  - Input 文件从 533 行瘦身到 ~180 行,Textarea / InputGroup 独立可装
+  - 下拉行为(键盘 / hover / a11y / 主题)只维护一份
+- **Negative**:
+  - 一次 major BREAKING:业务侧使用 `<Input prefix={...} />` / `addonBefore` 等需迁移到 `<InputGroup>` 复合写法
+  - 仓库内有 1 处下游(`SidebarInput` 在 sidebar.stories)+ 1 处自家 stories 需改写
+- **Trade-off**:
+  - 为了"API 单一职责 + 与 shadcn 上游同步" 放弃了"零迁移成本"。changeset 标 major,migration 表写在 input-group.meta.md 与 changeset。
+
+## Source
+
+- 用户对话:`AutoComplete 和 Select 是否需要合并？Input.Group 是否要脱离 Input 单独为一个组件`(本轮拍板 A1 + B + C 组合)
+- shadcn/ui 2025-10 的 Input / Textarea / InputGroup 拆分
+- W3C ARIA APG Combobox pattern 的 closed-list vs open-list 子模式区分
+- ADR 0028 复合 API 优于 prop 配置(同源思路)

package/dist/data/adr/0030-skill-uni-manager-uplift.md

@@ -0,0 +1,56 @@
+# 0030. uni-manager 变体 design + code skill 落地
+
+- **Status**: Accepted
+- **Date**: 2026-06-02
+- **Region**: 0001–0099 工程哲学
+- **Related ADR**: [0010](0010-design-default-and-variants.md), [0013](0013-skills-source-mirror.md), [0014](0014-ui-biz-ui-templates-tier.md), [0015](0015-skill-description-trigger-contract.md), [0017](0017-mcp-design-group.md), [0020](0020-design-to-tokens-skill-fusion.md)
+
+## Context
+
+opentrek 变体已经具备完整的 design + code skill（自包含、source-mirror 双 IDE 同步）。第二个变体 **uni-manager** 面向「专有云 / 混合云 / 多租户 / 多区域」中后台控制台场景，与 opentrek 在以下维度有刚性差异：
+
+1. **品牌视觉**：uni-manager 使用 hybridcloud 锐利风圆角（rounded-md=2px / lg=4px / xl=8px / 2xl=12px），opentrek 是圆润风
+2. **品牌主色**：uni-manager Brand Blue B50 `#0064C8`，opentrek 是中性灰黑
+3. **组件层级**：uni-manager 多了第二层 `biz-ui/uni-manager` 业务实物组件（首批落地 `um-topbar`），opentrek 仅依赖 `@teamix-evo/ui`
+4. **运行时上下文**：uni-manager 业务工程必带多租户 / 多区域 / 跨云上下文（X-Tenant-Id / X-Region-Id / X-Cloud-Provider header 链路）
+5. **危险操作语义**：uni-manager 涉及云资源释放/销毁，必须强制走「输入资源完整名称才执行」的 `useDangerConfirm` 模式，opentrek 仅推荐 AlertDialog
+6. **Brand 文档来源**：用户提供的 `Teamix-UI 规范文档/`（20 份 docx）需要被提炼为 brand / foundations / patterns 中的具体规范
+
+不能不做：用户已经在使用 uni-manager 主题（tokens 包早有 `[data-theme='uni-manager']` 覆盖），但 skill 层缺位，AI 在 uni-manager 项目里只能套 opentrek 规则，导致圆角错、缺 um-topbar、危险操作弱、queryKey 不带 tenantId 等持续漂移。
+
+## Decision
+
+1. **新建两个变体 skill**：`teamix-evo-design-uni-manager`（16 文件）+ `teamix-evo-code-uni-manager`（9 文件），文件结构与 opentrek **严格 source-mirror**（ADR 0013），便于差异审计与上游变更同步
+2. **uni-manager 不重新发明结构**：opentrek 的章节布局（philosophy / foundations / brand / patterns / boundaries / components / rules / generation-flow / flows / checklist / SKILL）整套保留，只在每个文件的特定章节增量补 uni-manager 专有约束
+3. **三件一致性套件 UM1/UM2/UM3** 写入 `rules/boundaries.rules.json`，scope 标记 `uni-manager`，与 opentrek 38 条通用规则解耦：
+   - UM1：全局 topbar 必须使用 `biz-ui/uni-manager/um-topbar` 实物
+   - UM2：列表/详情页 PageHeader 与 um-topbar 视觉一致
+   - UM3：跨云资源必须显示 `CloudBadge`
+4. **概念占位拼装表**：biz-ui/uni-manager 暂只实装 um-topbar；其余 7 个跨云/上下文/危险操作组件（CloudBadge / RegionBadge / ContextSwitcher / BulkActionBar / OperationLog / ResourceCard / DangerConfirmDialog）以「概念占位」形式列出，规定推荐落点（业务工程内 `src/components/cloud/` 等子目录），后续逐步抽到 biz-ui/uni-manager
+5. **多租户 / 多区域上下文走 interceptor**：service 函数保持纯净，不显式拼 tenantId；`lib/http.ts` 的 request interceptor 集中注入 X-Tenant-Id / X-Region-Id / X-Cloud-Provider；`lib/active-context.ts` 作为 vanilla TS 单例，与 React Context 双向同步；react-query queryKey **必须**含 tenantId / regionId
+6. **危险操作强制 useDangerConfirm**：定义完整 Hook + 配套 `DangerConfirmDialog` 组件，输入资源完整名称才能 enable 确认按钮；列入 code-uni-manager checklist 红线
+7. **通用规则反哺 opentrek**：从 Teamix-UI 规范文档提炼出的非变体特有规则（Form 间距三档 4/20/32 + Input 5 档宽度 104/216/328/440/552）追加到 `teamix-evo-design-opentrek/foundations.md` §3.5 / §3.6
+8. **manifest 注册**：`packages/skills/manifest.json` 升至 0.3.0，新增两条 skill 条目，description 严格遵循 ADR 0015 的 TRIGGER / SKIP / Coordinates with 三段式契约，TRIGGER 包含中文具名变体词（云管 / 跨云 / 多租户 / 多区域 / hybrid-cloud / 专有云）以保证路由准确
+
+## Consequences
+
+- **Positive**:
+  - uni-manager 变体获得与 opentrek 同等覆盖度的 AI 设计/编码护栏
+  - source-mirror 结构使两变体差异可逐文件 diff，规则升级可批量同步
+  - 概念占位拼装表机制让 biz-ui/uni-manager 抽包节奏可控（先在业务工程内落定型，再上抽）
+  - 多租户上下文链路在 skill 层固化，避免每个项目各自实现导致上下文与传输层耦合漂移
+  - 通用规则反哺让 opentrek 同步受益于 Teamix-UI 规范文档
+- **Negative**:
+  - 两变体 25 个文件总量约 4500+ 行，后续 opentrek 主结构变更需要同步两遍（已在 source-mirror 工程纪律中接受）
+  - 概念占位拼装表是一种「未来约定」，若 biz-ui/uni-manager 抽包节奏延迟，业务工程内的本地实现会成为事实标准
+- **Trade-off**:
+  - 选择「两变体独立目录 + source-mirror」而非「单 skill 多 variant 配置块」：放弃了配置紧凑性，换取 description trigger 路由清晰、文件粒度差异审计、单 skill 单职责
+  - 选择「在业务工程内放概念占位组件」而非「立即抽 biz-ui/uni-manager 包」：放弃了首日复用，换取设计稳定后再抽包的低返工成本
+
+## Source
+
+- 用户原始诉求（多轮）：基于 Teamix-UI 规范文档 + opentrek 镜像生成 uni-manager skill；biz-ui/uni-manager 当前仅 um-topbar 实物
+- 用户授权（本次会话）："按照最合理的、最流行的、最适合 ai 使用 vibecoding 的 skill 方案编写就好"
+- Teamix-UI 规范文档（20 份 docx，已解析归类）→ brand / foundations / patterns 增量
+- ADR 0013 source-mirror、ADR 0015 description-trigger、ADR 0014 三层组件架构
+- 执行计划：`.cache/plans/design-skill-uni-manager-uplift_100d06bc.md`

package/dist/data/adr/0031-skill-templates-decoupling.md

@@ -0,0 +1,77 @@
+# ADR 0031: AI Skill 链路解耦 `@teamix-evo/templates` 包
+
+- Status: Accepted
+- Date: 2026-06-02
+- Deciders: Teamix Evo Core
+- Related: [ADR 0014](0014-ui-biz-ui-templates-tier.md) · [ADR 0020](0020-design-to-tokens-skill-fusion.md) · [ADR 0030](0030-skill-uni-manager-uplift.md)
+
+## Context
+
+`@teamix-evo/templates` 在 [ADR 0014](0014-ui-biz-ui-templates-tier.md) 中作为 `tokens` / `biz-ui` / `templates` 三层共享 variant 名空间的一员，提供 slot-based 页面骨架代码。其原始定位是：当业务需要列表页 / 详情页 / 表单页 / 仪表盘的"frozen 完整骨架"时，由 `teamix-evo templates add <id> --variant <name>` 装机到 `src/templates/<id>.tsx`。
+
+随着 [ADR 0020](0020-design-to-tokens-skill-fusion.md) 后 design skill 自包含化、`patterns/*.md` 成为页面模式的事实知识库（双变体共 2179 行），出现了**双源决策路径**：
+
+- design skill 的 `generation-flow.md` / `SKILL.md` / `philosophy.md` 全部指向 `patterns/{list|detail|form|dashboard}-page.md`
+- code skill 的 `reuse-first.md` §2/§3 仍把"列表 / 详情 / 表单页骨架"导向 `@teamix-evo/templates` 包
+- manage skill 把 `templates` 列为六大 group 之一并出现在升级巡检、PR 登记模板中
+
+实际工程使用中，AI 在拿到 patterns/\*.md 的 Zone Map 与决策树后，通常已经能用 ui 原子件 + biz-ui 业务件直接拼装，再去装 templates 包反而带来重复源码（patterns 描述的同一种结构在 templates 包内有第二份代码实现），且 templates 包变体演进滞后，难以做到与 patterns/ 同步。
+
+## Decision
+
+**AI Skill（design + code + manage）链路从此不再主动调用 `@teamix-evo/templates` 包**，但**保留包与 CLI 命令本身**。具体：
+
+1. **patterns/\*.md 是页面骨架的唯一默认来源**
+   AI 在生成列表页 / 详情页 / 表单页 / 仪表盘 / Console Home 时，按 design skill 的 `patterns/*.md` Zone Map 与决策树，用 `@teamix-evo/ui` 原子件 + `@teamix-evo/biz-ui` 业务件 + `biz-ui/uni-manager` 实物件（如 `um-topbar`）+ 概念占位拼装表（uni-manager 7 项 / opentrek 5 项）**直接拼装**到 `src/pages/<id>/`。
+
+2. **patterns/ 未覆盖的页面 → 业界流行架构 + 用户描述自由实现**
+   不再回退到 `@teamix-evo/templates` 包。AI 参考 antd Pro / aliyun-console / shadcn Examples 等业界中后台 / 云管页面架构，结合用户原话描述完成实现。
+
+3. **`@teamix-evo/templates` 包与 `teamix-evo templates *` CLI 命令保留**
+
+   - 不退役、不删源码、不改包结构 → **零 break change**
+   - manage skill `templates` group 章节加 deprecated 标注
+   - 仅当用户**显式**要求"用 templates 包的 frozen 骨架"时，才跳转 `teamix-evo templates add`
+
+4. **PR 登记模板去 templates 化**
+   code skill 反模式 §"写完登记"中"ui / biz-ui / templates / 本项目均未提供 X 能力"改为"ui / biz-ui / patterns / 本项目均未提供 X 能力"。
+
+## Consequences
+
+### 正面
+
+- **单一决策路径**：design skill `patterns/*.md` ↔ code skill 拼装，不再与 templates 包形成双源
+- **patterns/ 与拼装代码一一对应**：AI 输出的页面 1:1 反映 patterns 描述的 Zone Map，无 templates slot 中转损失
+- **变体差异成本降低**：opentrek / uni-manager 间差异由 patterns/\*.md 的 markdown 维护即可，不必同步更新 templates 包源码
+- **零 break**：CLI / 包 / 已装机工程完全不动；用户已用的 `src/templates/*.tsx` frozen 文件不受影响
+
+### 负面
+
+- **templates 包成为"半冬眠"资产**：manifest 仍维护，源码可能逐步与 patterns/ 演进脱节；后续若要恢复主动调用，需要先做 patterns ↔ templates 一致性补齐
+- **"frozen 完整骨架"语义弱化**：用户若需要稳定不变的 page 文件托底（不希望 AI 每次重拼），需主动喊出 templates 包名
+
+### 中性
+
+- ADR 0014 中 `tokens / biz-ui / templates` 共享 variant 的事实保留，但 templates 部分的 variant 维护频次预计下降
+- 未来若 templates 包重新成为主路径（例如积累 50+ 高质量 page id），可发新 ADR 撤销本决策
+
+## Migration
+
+无迁移动作。本 ADR 仅约束 AI Skill 链路的**行为**：
+
+| 链路                          | 变更                                                 |
+| ----------------------------- | ---------------------------------------------------- |
+| design skill                  | ✅ 无变更（早已切到 patterns/）                      |
+| code skill (opentrek)         | ✅ reuse-first.md §2 / §4 已按本 ADR 重写            |
+| code skill (uni-manager)      | ✅ reuse-first.md §3 / §5 已按本 ADR 重写            |
+| manage skill                  | ✅ SKILL.md `templates` group 加 deprecated 标注     |
+| `@teamix-evo/templates` 包    | 不动（manifest / variants / dev / scripts 全部保留） |
+| `teamix-evo templates *` 命令 | 不动（list-variants / add 仍可用）                   |
+
+## References
+
+- [ADR 0013](0013-skills-source-mirror.md) — Skill 源镜像模型（patterns/ 是 skill 资产，与 templates 包正交）
+- [ADR 0014](0014-ui-biz-ui-templates-tier.md) — UI / biz-ui / templates 三层定义（仍生效，本 ADR 不撤销）
+- [ADR 0017](0017-mcp-design-group.md) — MCP design group（与 patterns/ 共用知识源）
+- [ADR 0020](0020-design-to-tokens-skill-fusion.md) — design skill 自包含化（patterns/\*.md 即在此过程中定型）
+- [ADR 0030](0030-skill-uni-manager-uplift.md) — uni-manager skill 落地（patterns/ 双变体齐备）