@teamix-evo/mcp 0.3.0 → 0.4.0

package/dist/data/adr/0004-cli-command-structure.md

@@ -0,0 +1,61 @@
+# 0004. CLI 命令结构:资源前置 `teamix-evo <package> <action> [variant]`
+
+- **Status**: Accepted
+- **Date**: 2026-05-13
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0010 design 默认+变体](0010-design-default-and-variants.md)(`design init --variant`)/ [0011 mcp 单包单 bin 多 group](0011-mcp-single-package-multi-group.md)(`teamix-evo-mcp` bin)/ [0013 Skills source-mirror](0013-skills-source-mirror.md)(`skills sync` / `skills doctor`)/ [0014 ui/biz-ui/templates 三层](0014-ui-biz-ui-templates-tier.md)(`biz-ui add --variant` / `templates add --variant`)
+
+## Context
+
+teamix-evo CLI 需要操作多种资产(design / skills / ui),每种资产有多种动作(init / update / add / list)。命令结构有几种风格:
+
+- `teamix-evo init`(动作前置,后续 prompt 选包)
+- `teamix-evo design init`(资源前置)
+- `teamix-evo init design opentrek`(动作前置 + 多参数)
+
+同时 design 包未来会有多 variant(opentrek / minimal / 等),命令结构需要为多 variant 留位。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| 动作前置 `teamix-evo <action> <package>` | 与传统 CLI(npm install / yarn add)风格一致 | 资源前置时让用户少打字时不直观 |
+| **资源前置 `teamix-evo <package> <action> [variant]`(本决策)** | 资源边界清晰,子命令组织好;variant 可扩展 | 与传统 CLI 风格略不同,首次接触有学习成本 |
+| 单一命令 + 子命令矩阵(`teamix-evo design:init`) | 全 flat | 命名长、变体多时混乱 |
+
+## Decision
+
+命令结构采用**资源前置**:
+
+```text
+teamix-evo <package> <action> [variant]
+```
+
+例:
+
+- `npx teamix-evo@latest design init opentrek`
+- `npx teamix-evo@latest design update`
+- `npx teamix-evo@latest skills add teamix-evo-manage`
+- `npx teamix-evo@latest ui add button`
+
+附属决策:
+
+- **多 variant 命名**:用包名作 key(`design: "opentrek"`),**不引入 brand 抽象**
+- **业务项目侧目录**:`packages/design/library/<variant>/`
+- **模板研发态目录**:`packages/design/_template/`(下划线前缀,避免被 variant 扫描器收录)
+
+## Consequences
+
+- **Positive**:
+  - 命令结构可预期(packageName 是第一参数)
+  - 多 variant 可扩展(无需新引入抽象)
+  - 子命令分布清晰,与 monorepo 包结构对齐
+- **Negative**:
+  - 子命令深度 +1(`teamix-evo design init opentrek` 而非 `teamix-evo init`)
+  - 与 `npm install` 等传统 CLI 风格不同,首次使用有学习成本
+- **Trade-off**:
+  - 用"+1 词的输入"换"资源边界清晰 + 多 variant 可扩展"
+
+## Source
+
+[`PLAN.md`](../../PLAN.md) §1.B

package/dist/data/adr/0005-ui-no-variant.md

@@ -0,0 +1,67 @@
+# 0005. UI 包不分 variant,所有视觉差异通过 design tokens 实现
+
+- **Status**: Accepted
+- **Date**: 2026-05-14
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0001 三层对齐](0001-three-layer-alignment.md) / [0006 UI 升级机制无 baseline](0006-ui-upgrade-no-baseline.md) / [0010 design 默认+变体](0010-design-default-and-variants.md) / [0014 ui/biz-ui/templates 三层](0014-ui-biz-ui-templates-tier.md)
+- **Scope**: 本 ADR 决策**仅适用于 `@teamix-evo/ui` 包**(纯能力 / generic component + block)。同仓的 `@teamix-evo/biz-ui` 与 `@teamix-evo/templates` 因为绑业务规则 / 变体专属合成,**必须分 variant** — 见 [ADR 0014](0014-ui-biz-ui-templates-tier.md)。这是"ui 不绑 / biz-ui 必绑 / templates 必绑"三种边界对称表达,不是矛盾。
+
+## Context
+
+`@teamix-evo/design` 已经按 variant 切分(`opentrek` 是首个,未来会有 `minimal` 等)。一个自然的问题是:`@teamix-evo/ui` 是否也要按 variant 切分?
+
+如果切分:
+
+- 每个 variant 一套组件源码;
+- 业务侧装组件时要先选 variant;
+- 多 variant 增加时,组件维护成本线性增长。
+
+如果不切分:
+
+- 一套组件源码吃所有 variant;
+- 视觉差异全部走 design tokens(CSS vars);
+- 风险点:variant 间的语义命名必须严格对齐(`primary` / `foreground` 等)。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| UI 按 variant 切分 | 单 variant 内组件可深度定制视觉 | 维护成本随 variant 数量线性增长;同步问题 |
+| **UI 不分 variant,靠 token(本决策)** | 一套组件吃所有 variant;切换 variant 仅改 design 包 | 强依赖 semantic 命名稳定;variant 间语义集合必须严格对齐 |
+
+## Decision
+
+`@teamix-evo/ui` **不分 variant**:
+
+- 一套组件源码服务所有 design variant
+- 组件 className 走 **shadcn semantic 集**:`bg-primary` / `text-primary-foreground` / `border-border` / `text-destructive` / `text-muted-foreground` 等
+- 底层 CSS vars(`--primary` / `--foreground` 等)由 design 包注入到 `globals.css` / `@theme` 块
+- design 包的 semantic 层命名**必须严格对齐 shadcn 集**——这是跨 variant 的不变量,UI 包源码依赖它
+- 业务侧切换 variant = 切 design 包,组件零改动
+
+className 与 token 的两层关系:
+
+```text
+组件源码  className="bg-primary"
+            ↓ Tailwind 编译
+编译产物  background-color: hsl(var(--primary))
+            ↓ 浏览器读取
+Token 层  --primary: oklch(...)    ← design 包注入
+```
+
+## Consequences
+
+- **Positive**:
+  - 组件维护成本不随 variant 增加
+  - 业务侧切换 variant 仅需切 design 包,组件零改动
+  - 升级 ui 包对所有 variant 用户同时生效
+- **Negative**:
+  - **semantic 命名不再可改**:design 必须严格对齐 shadcn 集,任何 variant 引入新 semantic 都需所有上游同步
+  - 业务侧自定义业务 token(如 `revenue-up`)需要二步走:`tokens.overrides.css` 加 CSS var + `tailwind.config` 加 utility 映射
+- **Trade-off**:
+  - 用"semantic 命名稳定性约束"换"组件维护成本不增长"
+  - 这条决策对组件研发顺序至关重要:design 必须先稳定 semantic 集,UI 才能基于它写组件
+
+## Source
+
+[`PLAN.md`](../../PLAN.md) §10.1 / §10.3

package/dist/data/adr/0006-ui-upgrade-no-baseline.md

@@ -0,0 +1,67 @@
+# 0006. UI 升级机制不预埋 baseline,依靠 AI + skill 做语义合并
+
+- **Status**: Accepted
+- **Date**: 2026-05-14
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0003 资源升级三态语义](0003-update-strategy-tri-state.md) / [0005 UI 包不分 variant](0005-ui-no-variant.md) / [0013 Skills source-mirror 模型](0013-skills-source-mirror.md)(skills upgrade 同型动作:同样无 baseline,靠语义合并 + skill 引导)
+
+## Context
+
+UI 包采用源码注入分发(`teamix-evo ui add <id>` 把组件源码写到业务项目 `src/components/ui/`),组件源码归用户。这就引出一个核心问题:**当上游 ui 包升级时,如何处理用户已修改的组件?**
+
+业界已有几种范式:
+
+- 三方合并(git-merge 风格):需要 baseline(上次安装的原始版本)→ 比较 baseline / current / incoming
+- 完全覆盖:简单粗暴,丢失所有定制
+- 不覆盖:升级失效
+- 静默生成 patch 文件给用户解决:用户负担重
+
+`updateStrategy: frozen`(ADR 0003)只解决了"不主动覆盖",没解决"如何主动同步上游修复 / 新功能到用户已修改的代码"。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| 三方合并 + baseline | 精确 | baseline 必须随 ui add 一起落地到业务项目(污染),且需历史快照管理 |
+| 完全覆盖 | 简单 | 丢用户定制 |
+| **AI 语义合并 + skill 引导(本决策)** | 不污染、简化、AI 兜底语义判断 | 比三方合并精确度差,大改时仍需人介入 |
+
+## Decision
+
+不预埋 baseline,靠 **AI + skill** 做"两方语义合并":
+
+### 流程
+
+1. `teamix-evo ui upgrade <id>` 触发
+2. CLI 把上游最新版组件源码下载到 `.teamix-evo/ui/incoming/<id>.tsx`(临时缓存)
+3. CLI 输出指引,提示业务侧 AI 调用 skill `teamix-evo-ui-upgrade`
+4. AI 通过 skill 读两个文件:
+   - 用户当前的 `src/components/ui/<id>.tsx`(可能含定制)
+   - `.teamix-evo/ui/incoming/<id>.tsx`(上游最新)
+5. AI 做"两方语义合并":
+   - 判断 incoming 改动属于:bug 修复 / 新功能 / 重构
+   - 判断 current 改动属于:业务定制 / 覆盖 upstream
+   - 在 current 上移植 incoming 的新行为,**保留用户的所有显式定制**
+6. AI 完成 merge,**删除 `.teamix-evo/ui/incoming/<id>.tsx` 缓存**
+
+### Skill 关键引导词
+
+> 你拿到的是两个文件:用户当前版本(可能含业务定制)和上游最新版本(刚下载,还没合并)。**没有基线**,所以你要靠语义判断:上游的改动看起来是 bug 修复 / 新功能 / 重构哪一类?用户的改动看起来是业务定制还是覆盖了上游?**保留用户的所有显式定制,移植上游的新行为**。合并完成后删除 `.teamix-evo/ui/incoming/<id>.tsx` 缓存。
+
+## Consequences
+
+- **Positive**:
+  - 不污染用户项目(无历史快照在业务侧)
+  - 简化(无 baseline 同步问题)
+  - AI 的语义理解适合"小改 + 上游修复"场景
+- **Negative**:
+  - 比三方合并精确性差(无 baseline,只有两方文件)
+  - 上游大改时 AI 容易出错,仍需人介入审查
+  - 依赖业务侧 IDE 装了对应 skill(`teamix-evo-manage` 引导)
+- **Trade-off**:
+  - 用"AI 语义判断的精确度损失"换"工程简化(无 baseline)"
+  - 大改本来就需要人介入,baseline 帮助有限——这是放弃 baseline 的核心论证
+
+## Source
+
+[`PLAN.md`](../../PLAN.md) §10.9

package/dist/data/adr/0007-governance-docs-at-root.md

@@ -0,0 +1,62 @@
+# 0007. 仓库治理文档放在根目录,与 `packages/docs/`(产品文档)分离
+
+- **Status**: Accepted
+- **Date**: 2026-05-17
+- **Region**: 0001–0099 工程哲学(目录布局即 identity 决策)
+- **Related ADR**: [0002 包命名方案](0002-package-naming.md)
+
+## Context
+
+仓库已有 `packages/docs/`(VitePress 产品文档站,装机后给业务消费方看的"怎么用")。在 P0-1 启动 ADR 流程时,新建了根目录 `docs/adr/`。这引出疑问:**为什么 ADR 不放进 `packages/docs/adr/`,与产品文档统一管理?根目录多一个 `docs/` 是否破坏 monorepo 集中性?**
+
+这个疑问会反复出现(每个新 maintainer / AI agent 看到都会问),如果不显式锁定,会在未来某次"清理"中被错误地搬走。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| A. 治理文档全部进 `packages/docs/` | monorepo 字面统一 | ADR 会被 VitePress 打包发布(本不应该);PLAN.md / AGENTS.md / CLAUDE.md 也得同步搬,扰动巨大 |
+| **B. 治理文档放根目录,产品文档放 `packages/docs/`(本决策)** | 边界清晰;符合业界惯例(adr-tools / Spotify / Microsoft / ThoughtWorks);ADR 不被发布 | 根目录有 `docs/` 与 `packages/docs/` 字面相似,首次接触者会问 |
+| C. 治理文档改名 `meta/` 或 `governance/` 避免与 `packages/docs/` 同名 | 字面无歧义 | 与业界惯例(`docs/adr/`)割裂;adr-tools 等工具默认路径失效 |
+| D. ADR 移到 `.adr/`(类似 `.changeset/`) | 暗示"工具元数据" | 点开头被多数 IDE 默认隐藏;ADR 是给人读的,不该藏 |
+
+## Decision
+
+**仓库治理文档(governance docs)放在仓库根目录;产品文档(product docs)放在 `packages/docs/`。**
+
+边界清单(可扩展):
+
+| 类别 | 位置 | 读者 | 发布吗? |
+| ---- | ---- | ---- | -------- |
+| ADR(架构决策记录) | `docs/adr/` | maintainer + reviewer subagent | ❌ 不发布 |
+| PLAN.md(路线图) | 根目录 | maintainer | ❌ 不发布 |
+| AGENTS.md(AI 协作入口) | 根目录 + `packages/*/AGENTS.md` | AI 编码助手 | ❌ 不发布 |
+| CLAUDE.md(Claude Code 指针) | 根目录 + `packages/*/CLAUDE.md` | Claude Code | ❌ 不发布 |
+| CONTRIBUTING.md(贡献指南) | 根目录 | 外部贡献者 | ❌ 不发布(GitHub 自动渲染) |
+| README.md | 根目录 + 各 package | 所有人 | ✅ 随包发布(各包自己的 README) |
+| VitePress 产品文档 | `packages/docs/` | 业务消费方(装机后) | ✅ 部署到文档站 |
+| API 参考(未来) | `packages/docs/api/` | 业务消费方 | ✅ 部署到文档站 |
+
+`packages/docs/` 的 VitePress sidebar 可以**链接**到根目录 ADR(`../../docs/adr/`),让消费方点链接进入查看;但 ADR 文件本身不被 VitePress 编译/打包/部署。
+
+## Consequences
+
+- **Positive**:
+  - 治理 vs 产品边界清晰,每类文档读者明确
+  - ADR 不会被错误地随产品文档发布
+  - 与 [adr.github.io](https://adr.github.io/) 列出的 ~15 个 ADR 工具默认路径兼容(adr-tools / log4brains / madr / dendron-adr 等)
+  - 未来加 [`docs/principles.md`](../principles.md) / [`docs/architecture.md`](../architecture.md) / `docs/slo/` 时位置一致
+- **Negative**:
+  - 根目录有 `docs/`(治理)与 `packages/docs/`(产品)字面相似,新人首次接触会问
+  - 需要在 README / AGENTS.md 显式说明边界
+- **Trade-off**:
+  - 用"字面相似带来的解释成本"换"语义清晰 + 业界惯例一致 + 不污染发布产物"
+
+## Implementation note
+
+- 根 `AGENTS.md` 的"快速导航"表已含"架构与决策记录 → PLAN.md";v0.5 阶段一并入演进时会同步加一条"决策记录(ADR)→ docs/adr/"
+- `packages/docs/` 的 VitePress 配置在 v1.0 升级时,sidebar 加一条"决策档案"指向 `../../docs/adr/README.md`,**只读链接,不复制**
+
+## Source
+
+2026-05-17 用户对 P0-1 产物的目录布局质疑;本 ADR 把当时讨论的判断锁定为可引用决策。

package/dist/data/adr/0008-eslint-visual-rules-warn-baseline.md

@@ -0,0 +1,110 @@
+# 0008. ESLint 视觉规则暂为 `warn` 级,等待 `@teamix-evo/design` 补齐状态色与布局尺寸 token
+
+- **Status**: Accepted (2026-05-17) → **还款已完成 2026-05-19**(三规则升至 `error`,见文末 §Implementation note 落地记录)
+- **Date**: 2026-05-17
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0001 三层对齐](0001-three-layer-alignment.md) / [0005 UI 包不分 variant](0005-ui-no-variant.md) / [0010 design 默认+变体](0010-design-default-and-variants.md)(token 补全落 `default/foundations/tokens/`)/ [0012 lint-core 共享内核](0012-lint-shared-core.md)(token-allowlist 单点维护;v0.6 ratchet 一并落地)
+
+## Context
+
+P0-2 在 [`@teamix-evo/eslint-config`](../../packages/eslint-config/) 中实现了 6 条 token-discipline 规则,接入 `packages/ui/` 后**首次**对全量 ~50 个组件源码执行 lint,得到:
+
+| 规则 | 违规数 | 性质 |
+| --- | ---: | --- |
+| `no-relative-ui-import` | 40 → **0**(本轮已机械修) | 工程契约 |
+| `icon-from-lucide` | 0 | 工程契约 |
+| `no-large-radius` | 0 | 视觉刻度 |
+| `no-arbitrary-tw-value` | 68 | 视觉/布局 |
+| `no-raw-color-scale` | 59 | 视觉/状态色 |
+| `no-color-literal` | 23 | 视觉/遮罩 |
+
+后三条规则的违规**不是开发者随手写**,而是 [`@teamix-evo/design`](../../packages/design/library/opentrek/tokens/semantic.tokens.json) 当前的语义 token 集合**没有覆盖**这些用例:
+
+| 缺失维度 | 现状 | 真实违规来源 |
+| --- | --- | --- |
+| 状态色(success / warning / info) | 只有 `destructive` / `error` | `bg-emerald-500` / `bg-amber-500` / `text-blue-700` 等 ~59 处(timeline、typography、tag、badge、alert 等) |
+| 布局尺寸(dialog-md、min-w-menu、 max-w-prose 等) | 无 | `w-[600px]` / `w-[720px]` / `min-w-[8rem]` 等 ~30 处(dialog、drawer、menu、command 等) |
+| 辅助字号(`text-xxs`、相对 em) | 无 | `text-[10px]` × 6 / `text-[0.875em]` × 2(kbd、typography) |
+| 半透明遮罩(overlay-bg) | 无 | `rgba(0,0,0,0.5)` 等 ~15 处(watermark、tour) |
+
+如果把这三条规则强制为 `error`,150+ 违规会**立刻把 CI 卡死**——但根因在 design,不在代码作者;粗暴 fail 等于把责任错置。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| --- | --- | --- |
+| A. 把三条规则保持 `error`,强制立即修代码 | 短期严格 | 把"design 系统不完整"伪装成"组件作者疏忽";代码作者只能继续 hack(改回 emerald)或加大量 `eslint-disable` 注释,知识进一步隐匿 |
+| B. 把三条规则置 `off`,等 v0.6 再开 | 简单 | 失去违规可见性;新增违规也无人察觉,熵增不可控 |
+| **C. 三条规则降为 `warn`,显式 ADR 锁定 + v0.6 补 token 计划(本决策)** | CI 不阻塞,但违规可见在 PR diff / 编辑器红波浪;新增违规走 `warn` 也提示作者;v0.6 ratchet 升回 `error` | 短期内 CI 不能阻挡新视觉违规;依赖 reviewer 看 lint 报告 |
+| D. 给现存 150 处加 `// eslint-disable-next-line + TODO(v0.6: ...)` | 显式豁免 | 150 处注释污染代码;每处需要 reviewer 判断 TODO 文本;实际上无新增可见性收益 |
+
+## Decision
+
+采用**方案 C**:
+
+1. **`@teamix-evo/eslint-config/presets/ui`** 与 `presets/consumer` 中:
+   - **error 级(立即阻塞)**:`no-relative-ui-import` / `icon-from-lucide` / `no-large-radius`
+   - **warn 级(暂时不阻塞)**:`no-color-literal` / `no-raw-color-scale` / `no-arbitrary-tw-value`
+2. **v0.6(根据 PLAN §12.5)的工作内容必须包含**:
+   - design 包加状态色 semantic token:`feedback.success` / `feedback.warning` / `feedback.info` 与对应 `*-foreground` / `*-subtle` / `*-border`
+   - design 包加布局尺寸 semantic token:`layout.dialog-sm/md/lg/xl`、`layout.menu-min-width`、`layout.popover-max-width` 等
+   - design 包加辅助字号:`typography.size-xxs`、`typography.size-sm-em`(相对父元素)
+   - design 包加遮罩 token:`overlay.scrim`、`overlay.watermark`(允许半透明黑/白)
+3. **v0.6 收尾**:三条规则 ratchet 升回 `error`;一并清理掉这一阶段堆积的 `warn`(预计 150 处全部修)。
+4. **v0.6 之前的新代码**:仍走 `warn`,不阻塞 CI,但 reviewer subagent(规划于 v0.7)在 PR 时可以引用本 ADR 拒绝"再增加新违规"。
+
+## Consequences
+
+- **Positive**:
+  - P0-2 ESLint 接入完整(6 条规则 + 包 + 测试),不在"完不成"和"暴力修"之间二选一
+  - 现存 150 处违规可见(IDE 红波浪 + lint 报告),不被忽略
+  - design 系统的真实 gap 被显式记录,v0.6 有明确的"补哪些 token"清单
+  - `no-relative-ui-import` 已经 ratchet 起作用——任何新跨组件 import 必须用 `@/` 别名,违反阻塞 CI
+- **Negative**:
+  - v0.5 阶段 CI 不会因新视觉违规失败,依赖 reviewer 警觉 / 编辑器红波浪
+  - v0.6 落地前 design tokens 不完整,业务消费方装 `@teamix-evo/design` 后做"成功状态"也没 token 可用(同样问题,但消费方先发现)
+- **Trade-off**:
+  - 用"短期 visual CI 兜底缺口"换"design 系统正确补完整 + 不污染代码 150 处 disable 注释 + 不让作者继续 hack"
+  - 这是有意识的债务,有明确还款计划(v0.6),不是默认遮蔽
+
+## Implementation note (本 ADR 落地的具体动作)
+
+- [`packages/eslint-config/src/presets/ui.ts`](../../packages/eslint-config/src/presets/ui.ts):三条规则改为 `warn`,文件级注释引用本 ADR
+- [`packages/eslint-config/src/presets/consumer.ts`](../../packages/eslint-config/src/presets/consumer.ts):同上
+- [`packages/ui/eslint.config.js`](../../packages/ui/eslint.config.js):接入 `presets/ui`(已完成)
+- [`PLAN.md §12.5 v0.6 任务清单`](../../PLAN.md#125-v06--闸层补强--协议层雏形12-18-人日):需补一行"design 状态色 / 布局尺寸 / 遮罩 token + 视觉规则 ratchet 升回 error"
+- 本 ADR 在 v0.6 完成时改 `Status: Superseded by NNNN`,新 ADR 记录 ratchet 之后的状态
+
+### 还款落地记录(2026-05-19)
+
+**design token 补全**(`packages/design/default/foundations/tokens/`):
+
+- 状态色 × 4 变体:`success` / `warning` / `info` × `{base, foreground, subtle, border}` = 12 颗 color token
+- 布局尺寸:`layout-dialog-{sm,md,lg,xl}` / `layout-panel-{sm,md}` / `layout-submenu` / `layout-menu-{min,md}` / `layout-popover-max` / `layout-listbox-max` / `layout-counter` / `layout-notification` / `layout-textarea-min` / `layout-image-preview-max-{w,h}` 共 16 颗 dimension token
+- 遮罩:`overlay-scrim`(rgba(0,0,0,0.5)) / `overlay-watermark`(rgba(0,0,0,0.15))
+- 辅助字号:`text-xxs`(0.625rem) / `text-xs-cal`(0.8rem)
+- Radix passthrough:`{w,h}-radix-nav-viewport` / `{h,min-w}-radix-select-trigger`
+- 同步落到 `base.tokens.json` / `semantic.tokens.json` / `tokens.generated.css` / `tokens.theme.css` / `tailwind.preset.ts` 五处。
+
+**lint-core 同步**(`packages/lint-core/src/data/token-allowlist.ts`):取消 v0.6 注释占位 + 加 16 个 layout token 名,共 33 个新 token 入 allowlist。
+
+**packages/ui/ 修代码**(115 处违规):
+
+- 11 类机械替换:`bg-emerald-*` → `bg-success-*` / `bg-amber-*` → `bg-warning-*` / `bg-blue-*` → `bg-info-*`(成功 / 警告 / 提示三色 × subtle / border / foreground 等变体 = ~70 处);`w-[600px]` 等 → `w-dialog-md` 等(layout dimension = ~30 处);`text-[10px]` → `text-xxs` 等(typography = ~8 处);`left-[50%]` → `left-1/2`(Tailwind 内置)。
+- 4 处合法一次性 `eslint-disable-next-line` + 原因注释:`color-picker.tsx` defaultValue API 需 hex 字面量;`watermark.tsx` 渲染走 canvas API 不支持 CSS var();`drawer.tsx` 拖拽手柄宽 100px 是视觉常量;`kbd.tsx` 键帽内阴影 / `masonry.tsx` 运行时 var / `navigation-menu.tsx` indicator 60% 锚点 / `timeline.tsx` calc() 连接线 / `typography.tsx` em-relative inline code 同理。
+- 1 处 SVG attr 改用 `var(--overlay-scrim)`:`tour.tsx` SVG `<rect fill>`。
+
+**ratchet**(`packages/eslint-config/src/presets/`):
+
+- `ui.ts` + `consumer.ts` 三条视觉规则:`warn` → `error`。
+- `ui.ts` 内 stories / tests override 块**保留** `warn`(per ADR 0008 §Implementation note "research artifacts" 立场;demo 用临时尺寸 / 演示色板不阻塞 CI)。
+
+**最终状态**:`pnpm --filter @teamix-evo/ui lint` = 0 errors / 47 warnings(全部在 stories 内,符合 design intent)。全仓 350 测试 / 11 包 typecheck 全绿。
+
+**ADR 状态**:本 ADR 无需 Supersede(还款已是预定动作,落地后债务清零;留作 v0.6 历史记录)。后续视觉规则若再发现 gap,按 ADR 模板再起新条目即可。
+
+## Source
+
+- 2026-05-17 P0-2 (b) 接入 ESLint 后首次 lint 输出(`pnpm --filter @teamix-evo/ui lint`)
+- [`PLAN.md §12.11 风险与不该做的事`](../../PLAN.md#1211-风险与不该做的事) 第一条预案:"第一批只上 6 条**红线级**规则;'建议级'用 `warn` 不阻塞 CI"——本 ADR 是该预案的具体应用
+- [`packages/design/library/opentrek/tokens/semantic.tokens.json`](../../packages/design/library/opentrek/tokens/semantic.tokens.json):当前语义 token 集合,无 success / warning / info / 布局尺寸 / 遮罩

package/dist/data/adr/0009-registry-mcp-protocol-layer.md

@@ -0,0 +1,87 @@
+# 0009. `@teamix-evo/registry-mcp` 作为 AI 协议层的第一个 MCP server
+
+- **Status**: Superseded in part by [0011](0011-mcp-single-package-multi-group.md)(2026-05-18)— 原"包形态 / bin 名 / `.mcp.json` 条目名"被 0011 取代;**核心决策(MCP 作为协议层 / stdio / 三个 registry tool)依然有效**
+- **Date**: 2026-05-17
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0001 三层对齐](0001-three-layer-alignment.md) / [0005 UI 不分 variant](0005-ui-no-variant.md) / [0011 mcp 单包单 bin 多 group](0011-mcp-single-package-multi-group.md)
+
+## Context
+
+teamix-evo MVP 阶段 ([Phase 0–10](../../PLAN.md#5-研发计划分阶段)) 把 `@teamix-evo/ui` 的 `manifest.json` 设计为静态 JSON(56KB,89 entries),业务侧 AI 编辑器(Cursor / Claude Code / Cline)通过 RAG 把它分块塞进上下文。这个机制有三个问题:
+
+1. **副本漂移**——每个消费方拿一份 snapshot,与上游 `@teamix-evo/ui` 升级后必然脱节
+2. **AI 处理 56KB 困难**——chunking + RAG 的召回率差,模型经常报"组件不存在"或挑错版本
+3. **缺乏受控查询面**——无法表达"找一个支持异步搜索 + 分页的组件",只能被动读
+
+这是 [PLAN §12.3 P0-4](../../PLAN.md#123-p0-紧急清单下个-sprint--12-人日) 要解决的核心问题:把静态 JSON 升级为可被 AI 主动调用的 Model Context Protocol (MCP) server。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| --- | --- | --- |
+| A. 维持静态 manifest.json + 在 AGENTS.md 引导 AI 用 grep | 零工程成本 | 副本漂移、56KB 处理低效、查询表达力差(本节 Context 已述) |
+| B. 自定义 HTTP 接口 + 让 AI 调 `fetch()` | 灵活 | 不是任何 IDE 的事实标准;Cursor / Claude Code / Cline 各有自家"工具调用"协议,需写 4 套适配 |
+| **C. MCP server(本决策)** | Anthropic 推、OpenAI 跟、Cursor / Claude Code / Cline / Aider 均原生支持;一份代码,所有 AI 编辑器可用;运行时直接读 manifest 单一来源 | 引入 `@modelcontextprotocol/sdk` 依赖;协议本身仍在演进(当前 1.x);需要每个消费方在 IDE 配置中接入 |
+
+## Decision
+
+新建 [`@teamix-evo/registry-mcp`](../../packages/registry-mcp/) 包,作为 teamix-evo 的**第一个**协议层 MCP server。
+
+### 形态
+
+- **stdio transport**(MCP 默认):零网络配置,每次 IDE 启动 server 子进程,通信通过 stdin/stdout 的 JSON-RPC 2.0 帧
+- **零静态副本**——server 直接读 `@teamix-evo/ui/manifest.json` 的物理文件(用 `require.resolve` 解析,fallback 到环境变量与父目录回溯)
+- **bin 入口**:`teamix-evo-registry-mcp`(消费方通过 `npx @teamix-evo/registry-mcp` 调用)
+
+### 暴露的 Tools(MVP,3 个)
+
+| Tool | 输入 | 输出 |
+| --- | --- | --- |
+| `list_components` | `status?: 'stable' \| 'experimental' \| 'deprecated'` | 全量组件简表(id / name / description / status / registryDependencies) |
+| `get_component_meta` | `id: string` | 完整 `UiEntry` + 解析后的 `meta.md`(frontmatter + body) |
+| `find_components` | `query: string`, `limit?: number` | 子串匹配 id / name / description 的命中列表 |
+
+### v0.7 升级路径
+
+`find_components` 当前是**子串匹配**——直白、可调试、零额外依赖。v0.7 升级为**语义搜索**(向量化 description + meta.md,余弦相似度 top-k),但**不引入新工具名**——同一个 `find_components` 工具,实现替换;客户端代码零改动。
+
+### IDE 配置(消费方侧)
+
+提供根目录 [`.mcp.json`](../../.mcp.json) 模板,业务侧装机后由 `create-teamix-evo` preset 复制并填入。Cursor / Claude Code / Cline 各自的 MCP 配置位置不同,但 server 命令一致。
+
+### 单元测试
+
+`packages/registry-mcp/tests/`(将随 [ADR 0011](0011-mcp-single-package-multi-group.md) 改名 → `packages/mcp/tests/groups/registry/`):
+
+- `manifest-loader.test.ts` — 校验 manifest 解析、frontmatter 解析、env / 父目录回溯三层路径解析
+- `server.test.ts` — 直接 invoke MCP `tools/call` 处理函数,跨 fixture 验证 3 个工具的正确性
+
+## Consequences
+
+- **Positive**:
+  - **副本漂移消除** —— server 每次响应都直接读上游 manifest,与 [`@teamix-evo/ui`](../../packages/ui/) 同步
+  - **AI 协同体验跃升** —— 模型从"扫 56KB 寻找"变成"主动调用 `find_components`",上下文消耗下降一个数量级
+  - **跨 IDE 复用** —— 一份 server 代码,Cursor / Claude Code / Cline / Aider / 未来所有 MCP 客户端都用得上,不需要按 IDE 写适配
+  - **协议层可扩展** —— 后续 `tokens-mcp` / `scenario-mcp` / `adr-mcp` 可复用本包的 manifest-loader / fixture / test 模式(见 [PLAN §12.5/12.6/12.7](../../PLAN.md#12-五层模型驱动的演进规划v05))
+  - **status 字段(ADR 0003 续)立即变现** —— `list_components` 已支持按 `status` 过滤,deprecation 信号通过 `replacedBy` 字段直接传给 AI
+- **Negative**:
+  - 消费方需在 IDE 的 MCP 配置中加一段(每个 IDE 配置位置不同,需要文档明示)
+  - `@modelcontextprotocol/sdk` 处于 1.x 早期阶段,可能在 2026 年内出现破坏性变更
+  - stdio transport 启动时延 ~50–200ms(每次 IDE 启动 server 子进程),对超大 manifest 不算瓶颈,但需注意
+  - 子串搜索的召回率有限(中英文混合查询、同义词不命中),v0.7 才解决
+- **Trade-off**:
+  - 用"协议依赖 + IDE 配置成本"换"副本漂移消失 + 跨 IDE 复用 + AI 上下文效率"
+  - 用"v0.1 子串搜索的有限召回"换"零向量库依赖 + 实现简单 + 接入快"
+
+## Implementation note
+
+- `packages/registry-mcp/src/cli.ts` 是 bin 入口;直接通过 `node ./dist/cli.js` 启动 stdio server
+- Manifest 解析顺序在 [`manifest-loader.ts`](../../packages/registry-mcp/src/manifest-loader.ts) 中:`TEAMIX_EVO_UI_MANIFEST` env > `<cwd>/node_modules/@teamix-evo/ui/manifest.json` > 父目录回溯
+- 测试通过 MCP 内部 `_requestHandlers` map 直接调用工具处理函数,绕过 transport 层(单元测试不需要 stdio 真启动)
+- Smoke 测试已验证:`echo '{...}' | node ./dist/cli.js` 三轮 JSON-RPC 调用(initialize / tools/list / tools/call find_components)在真实 packages/ui/manifest.json 上正确返回 `table` + `data-table`
+
+## Source
+
+- [PLAN.md §12.3 P0-4](../../PLAN.md#123-p0-紧急清单下个-sprint--12-人日):"第一版 registry-mcp,暴露 list_components / get_component_meta / find_similar 三个工具"
+- [`packages/eslint-config` ADR 0008](0008-eslint-visual-rules-warn-baseline.md) 已展示"把约束从文字下沉为机器规则"的同型动作;本 ADR 是协议层的同型动作("把 56KB JSON 下沉为可调用工具")
+- [Model Context Protocol 官方规范](https://modelcontextprotocol.io)