@teamix-evo/mcp 0.3.0 → 0.4.2

package/dist/data/adr/0012-lint-shared-core.md

@@ -0,0 +1,215 @@
+# 0012. ESLint / Stylelint 双发布包共享 workspace 内部内核 `@teamix-evo/lint-core`
+
+- **Status**: Accepted (2026-05-18) → **完整落地 2026-05-19**(eslint-config + stylelint-config 双消费方接入完成,共享内核闭环成立;详见文末 §Implementation 落地记录)
+- **Date**: 2026-05-18
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0008 ESLint 视觉规则 warn 基线](0008-eslint-visual-rules-warn-baseline.md)
+
+## Context
+
+[ADR 0008](0008-eslint-visual-rules-warn-baseline.md) 落地 6 条 ESLint 规则({% raw %}`no-color-literal` / `no-arbitrary-tw-value` / `no-raw-color-scale` / `no-large-radius` / `no-relative-ui-import` / `icon-from-lucide`{% endraw %})后,[PLAN §12.5 v0.6](../../PLAN.md#125-v06--闸层补强--协议层雏形12-18-人日) 规划新建 `packages/stylelint-config/` 把同样的 token-discipline 推到 CSS 层。
+
+两侧规则的**领域知识 80% 重合**:
+
+| 共享的"原料" | ESLint 用法 | Stylelint 用法 |
+| --- | --- | --- |
+| 颜色字面量正则(hex / rgb / hsl / oklch / oklab / hwb) | 扫 JSX `className`、`style` 属性、模板字符串 | 扫 CSS `Declaration` 的 `value` |
+| 语义 token 白名单 | 排除 `bg-background` / `text-foreground` 等合法 className | 排除 `var(--background)` 等合法 var() 引用 |
+| 圆角档位(`['none','sm','md','lg','full']`) | 检查 Tailwind 类 `rounded-3xl` 越界 | 检查 CSS `border-radius: 24px` 越界 |
+| Tailwind arbitrary value 解析(`bg-[#fff]` / `mt-[7px]`) | 直接禁用 | n/a(CSS 侧由 `no-color-literal` 等覆盖) |
+| 错误文案 / 恢复指南 | 通过 ESLint `messages` 输出 | 通过 Stylelint `messages` 输出 |
+
+如果各自在两个包里**复制粘贴维护**,后果是确定的:
+
+1. **token 白名单**(语义 token 名)改一处,另一边漏改 → JSX 通过、CSS 报错(或反之)
+2. 报错文案不一致 → 同一类违规在 IDE 红波浪 / lint 报告里看到两套话术
+3. 测试 fixtures 重复 → 改算法时维护两份用例
+4. **P2 single source 实质塌陷** —— 这是仓内最容易漂移的点
+
+但如果合成一个包同时输出 ESLint preset + Stylelint preset:
+
+1. peer dep 冲突:eslint v9 与 stylelint v16 / postcss 的依赖链交错
+2. 业务侧装机时被迫装入不需要的另一边(只用 React 不写 CSS 的项目也要拖 stylelint 进来)
+3. 违反行业惯例:`eslint-config-airbnb` / `stylelint-config-standard` 业界都是分包,业务侧 `extends` 一眼能看出工具
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| --- | --- | --- |
+| ① 两包零共享(各自维护规则) | 简单;peer 解耦 | token 白名单 / 文案 / 算法跨包漂移,违反 P2 |
+| ② 单包同时发 ESLint + Stylelint preset | 单点维护 | peer 冲突;业务侧装机被迫绑双工具;违反行业惯例 |
+| **③ 双发布包 + workspace 内部 `@teamix-evo/lint-core`(本决策)** | token 白名单 / matcher / 文案单点维护;peer 解耦;符合行业惯例;消费方仅装需要的那一侧 | 需要工程约束:lint-core **不发布** + tsup `bundle: true` 把 lint-core 内联进发布产物 |
+
+## Decision
+
+### 1. 包形态(三个包)
+
+```
+packages/lint-core/                     # workspace internal,不发布 npm
+└── src/
+    ├── matchers/
+    │   ├── color-literals.ts           # 纯函数:matchHex(s) / matchRgb(s) / matchOklch(s) ...
+    │   ├── tailwind-arbitrary.ts       # 解析 bg-[#fff] / mt-[7px] / rounded-[12px]
+    │   ├── radius-class.ts             # rounded-{none|sm|md|lg|full|<arbitrary>}
+    │   └── icon-import.ts              # 从 import source 判断是否 lucide-react
+    ├── data/
+    │   ├── token-allowlist.ts          # 允许的语义 token 名(--background / --foreground / ...)
+    │   ├── radius-tiers.ts             # ['none','sm','md','lg','full']
+    │   └── motion-tiers.ts
+    ├── docs/
+    │   └── error-templates.ts          # 共享报错文案与恢复指南(两侧一致)
+    └── index.ts                        # 统一导出 matcher / data / docs
+
+packages/eslint-config/                 # 发布:@teamix-evo/eslint-config
+├── deps: @teamix-evo/lint-core (workspace:*)
+└── src/rules/
+    ├── no-color-literal.ts             # 包成 ESLint rule(读 lint-core 的 matcher)
+    ├── no-raw-color-scale.ts
+    └── ...
+
+packages/stylelint-config/              # v0.7 落地:@teamix-evo/stylelint-config
+├── deps: @teamix-evo/lint-core (workspace:*)
+└── src/rules/
+    ├── no-color-literal.ts             # 包成 Stylelint rule(读 lint-core 的 matcher)
+    └── ...
+```
+
+### 2. 发布形态:lint-core **不发布**,内联打包进两个 config 包
+
+`lint-core` 的所有导出**仅纯函数 + 数据 + 文案**,无 ESLint / Stylelint 运行时依赖。两个 config 包通过 tsup `bundle: true` 把 lint-core 代码内联进发布产物:
+
+| 包 | npm 看得见 | 业务侧装机时 |
+| --- | --- | --- |
+| `@teamix-evo/eslint-config` | ✅ 公开发布 | `npm install -D` |
+| `@teamix-evo/stylelint-config` | ✅ 公开发布(v0.7) | `npm install -D` |
+| `@teamix-evo/lint-core` | ❌ `private: true`,不发 | 业务侧看不见,代码已内联 |
+
+业务侧 `node_modules` 里**只看到** `@teamix-evo/eslint-config` 与 `@teamix-evo/stylelint-config`;`@teamix-evo/lint-core` 不出现 —— 避免"那是什么?"的认知负担。
+
+### 3. lint-core 的 API 形态(纯函数 + 数据)
+
+```ts
+// packages/lint-core/src/matchers/color-literals.ts
+export function matchHex(value: string): { match: string; index: number } | null { /* ... */ }
+export function matchRgb(value: string): { match: string; index: number } | null { /* ... */ }
+export function matchOklch(value: string): { match: string; index: number } | null { /* ... */ }
+export function matchAnyColorLiteral(value: string): MatchResult | null {
+  return matchHex(value) ?? matchRgb(value) ?? matchHsl(value) ?? matchOklch(value) ?? matchOklab(value) ?? matchHwb(value);
+}
+
+// packages/lint-core/src/data/token-allowlist.ts
+export const SEMANTIC_TOKEN_ALLOWLIST: ReadonlyArray<string> = [
+  'background', 'foreground', 'primary', 'primary-foreground',
+  'secondary', 'secondary-foreground', 'muted', 'muted-foreground',
+  'accent', 'accent-foreground', 'destructive', 'destructive-foreground',
+  'border', 'input', 'ring',
+  // v0.6 ADR 0008 还款新增:
+  'success', 'warning', 'info',
+  // ...
+];
+
+// packages/lint-core/src/docs/error-templates.ts
+export const errorColorLiteral = (literal: string, suggestion?: string) => ({
+  zh: `禁止颜色字面量 \`${literal}\`。请改用语义 token...${suggestion ? '建议:' + suggestion : ''}`,
+  en: `Color literal \`${literal}\` is forbidden. Use semantic tokens...`,
+});
+```
+
+ESLint / Stylelint rule 各自包装:
+
+```ts
+// packages/eslint-config/src/rules/no-color-literal.ts
+import { matchAnyColorLiteral } from '@teamix-evo/lint-core';
+import { errorColorLiteral } from '@teamix-evo/lint-core';
+
+export default createRule({
+  name: 'no-color-literal',
+  meta: { type: 'problem', messages: { violation: errorColorLiteral('').zh } },
+  create(context) {
+    return {
+      Literal(node) {
+        const m = matchAnyColorLiteral(String(node.value));
+        if (m) context.report({ node, messageId: 'violation' });
+      },
+      // ...
+    };
+  },
+});
+
+// packages/stylelint-config/src/rules/no-color-literal.ts
+import stylelint from 'stylelint';
+import { matchAnyColorLiteral, errorColorLiteral } from '@teamix-evo/lint-core';
+
+export default stylelint.createPlugin('@teamix-evo/no-color-literal', () => (root, result) => {
+  root.walkDecls((decl) => {
+    const m = matchAnyColorLiteral(decl.value);
+    if (m) stylelint.utils.report({ message: errorColorLiteral(m.match).zh, node: decl, result });
+  });
+});
+```
+
+### 4. 测试策略
+
+| 层 | 测试位置 | 内容 |
+| --- | --- | --- |
+| matcher 纯函数 | `packages/lint-core/tests/` | 单元测试覆盖每个 matcher 的正反例(不依赖 ESLint / Stylelint rule-tester) |
+| ESLint rule 包装 | `packages/eslint-config/tests/` | 用 `@typescript-eslint/rule-tester`(已就位) |
+| Stylelint rule 包装 | `packages/stylelint-config/tests/`(v0.7) | 用 `jest-preset-stylelint` 或 stylelint 内置 testRule |
+
+### 5. v0.6 与 v0.7 的实施切分
+
+- **v0.6**:抽 `lint-core`、改造 `eslint-config` 改用 lint-core,**Stylelint 不在 v0.6 上线**(避免本次重构面太大)
+- **v0.7**:落地 `stylelint-config`(v0.7 协议层升级阶段做)
+
+## Consequences
+
+- **Positive**:
+  - **token 白名单单点维护** —— 改 `data/token-allowlist.ts` 一行,ESLint / Stylelint 同步生效;ADR 0008 v0.6 还款新增的 success / warning / info 白名单在此唯一登记
+  - **报错文案两侧一致** —— `bg-[#fff]` 在 JSX 和 CSS 里报的都是同一段恢复指南
+  - **测试用例可在 lint-core 单测纯函数** —— 不依赖任何 lint 框架的 rule-tester,启动快
+  - **行业惯例符合** —— 业务侧 `extends: '@teamix-evo/eslint-config'` 一眼可读,与 airbnb / standard 同形
+  - **业务侧解耦** —— 只用 React 不写 CSS 的项目仅装 eslint-config,不被迫拖 stylelint
+- **Negative**:
+  - 需要工程约束:lint-core 必须 `private: true`,且两个 config 的 tsup config 必须开启 `bundle: true`(否则发布产物会出现 `@teamix-evo/lint-core` 找不到)—— 用 CI 脚本校验
+  - workspace 内部包数量 +1 —— pnpm-workspace.yaml 多一行,但视觉成本可忽略
+- **Trade-off**:
+  - 用"工程约束(private + bundle)"换"双侧规则共享原料 + 业界惯例符合 + 装机解耦"
+
+## Implementation note
+
+落地工作量(v0.6,共 ~2 人日,Stylelint 实际规则推到 v0.7):
+
+1. 写本 ADR(0.2)
+2. `packages/lint-core/` workspace 包基建 + 抽出 matcher / data / docs(0.8)
+3. 改造 `packages/eslint-config/` 改用 lint-core(0.5)
+4. tsup config 加 `bundle: true` + CI 校验脚本(0.3)
+5. ADR 0008 v0.6 还款的 token 新增同步登记到 `lint-core/data/token-allowlist.ts`(0.2)
+
+### v0.7 stylelint-config 落地记录(2026-05-19)
+
+`packages/stylelint-config/` 上线,镜像 eslint-config 结构。
+
+**3 条规则**:
+
+- `no-color-literal` — CSS Declaration 值禁 hex / rgb / hsl / oklch / oklab / hwb;复用 lint-core `matchHex` + `matchColorFunction`,**与 ESLint 同源同正则**。
+- `prefer-token-radius` — `border-radius` 系列属性必须用 `var(--radius*)` token / `0` / 关键字 / `calc(var(...))`;原 px / rem / em / 百分比阻塞;新增 lint-core `analyseBorderRadiusValue` matcher 处理 composite values。
+- `no-unknown-token` — `var(--xxx)` 引用必须在 `SEMANTIC_TOKEN_ALLOWLIST` 内;自动 strip Tailwind v4 `--color-*` 前缀;built-in `--radix-*` 透传;secondary option `allowedPrefixes` 让消费方加项目级前缀(如 `['my-app-']`)。新增 lint-core `extractVarReferences` matcher。
+
+**lint-core 同步**:加 2 个 CSS matcher 文件(`css-var-refs.ts` + `css-radius.ts`)+ 11 单测(总 43);`index.ts` export 扩展;build 后 dist 体积无显著膨胀。
+
+**双 preset**:`presets/ui` + `presets/consumer`,同等规则;均带 `ignoreFiles` 排除 `tokens.{generated,theme,overrides}.css`(token 定义文件本身就是写 raw 值的合法位置)。
+
+**bundle 验证**:`pnpm --filter @teamix-evo/stylelint-config check:bundled` ✅ 通过 — `@teamix-evo/lint-core` 完全内联进 dist/,消费方 node_modules 不可见。
+
+**测试**:24 个 stylelint-config 单测(`runRule(code, ruleName, options)` helper 包装 `stylelint.lint` API 直跑);385 全仓 tests / 13 包 typecheck 全绿。
+
+**lint-core 闭环成立**:eslint-config + stylelint-config 共享 5 matcher(matchHex / matchColorFunction / extractVarReferences / analyseBorderRadiusValue / SEMANTIC_TOKEN_ALLOWLIST)+ 4 数据集。任何后续新增 token 只需改 `lint-core/data/token-allowlist.ts` 一处,**两侧规则同步生效**。
+
+**遗留**:消费方装机后真实跑一次 stylelint 看噪音,留 v0.8 业务接入时跑通(packages/docs 暂未试装)。
+
+## Source
+
+- [ADR 0008](0008-eslint-visual-rules-warn-baseline.md):6 条 ESLint 规则的现状,本 ADR 抽其内核
+- [PLAN §12.5 v0.6](../../PLAN.md#125-v06--闸层补强--协议层雏形12-18-人日):"新建 `packages/stylelint-config/` + token 字面量禁用规则"
+- 2026-05-18 用户讨论:["lint-core 输出 eslint 和 stylelint 是怎么输出的?"](rules-as-data 内核 + 双发布点)
+- [`docs/principles.md` P2 / P5](../principles.md):P2 single source / P5 machine knowledge > retrievable

package/dist/data/adr/0013-skills-source-mirror.md

@@ -0,0 +1,154 @@
+# 0013. Skills 采用 source-mirror 模型:`.teamix-evo/skills/` 为源,IDE 路径为工具镜像
+
+- **Status**: Proposed
+- **Date**: 2026-05-18
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0003 资源升级三态语义](0003-update-strategy-tri-state.md)
+
+## Context
+
+[Phase 7](../../PLAN.md#phase-7--teamix-evoskills-包--双-ide-适配23-人日) 的 IdeAdapter 把 SKILL.md 安装到业务侧两个 IDE 路径:
+
+```
+.qoder/skills/<id>/SKILL.md      # Qoder 强制读这个路径
+.claude/skills/<id>/SKILL.md     # Claude Code 强制读这个路径
+```
+
+[v0.7 路线图](../../PLAN.md#126-v07--协议层升级15-22-人日)还要加:
+
+```
+.cursor/rules/<id>.mdc           # Cursor 强制读这个路径(且 frontmatter 格式略不同)
+```
+
+IDE 的入口路径**是写死的协议**,不可以在工具侧改成"统一一个位置"。如果只往 IDE 路径写文件 —— 这是当前实际行为 —— **P2 single source 立刻塌陷**:
+
+| 痛点 | 后果 |
+| --- | --- |
+| 同 SKILL.md 物理重复 2-N 份 | 用户改 `.qoder/skills/foo/SKILL.md` 一份,`.claude` 那份还是旧的,行为漂移 |
+| `teamix-evo skills upgrade` 无法判断"哪份是工具最近一次产出 / 哪份是用户改过" | 升级算法无锚点 |
+| 卸载流程要遍历每个 IDE 路径删 | 漏一个 IDE 就遗留垃圾 |
+| `.cursor/rules/*.mdc` 与 `.claude/skills/*/SKILL.md` 是两种格式 | 没有唯一可信"原文",frontmatter 转译只能靠 ad-hoc 比较 |
+| AI 上下文 / MCP server / AGENTS.md 引用谁? | 选 `.qoder` 不公平,选 `.claude` 也不公平,选哪个都绑死 IDE |
+
+ADR 0003 的三态语义里 `regenerable` 表达的是"工具拥有,用户不应直接改";IDE 路径下的文件**应当全部是 regenerable**——它们是工具产出的镜像。**真正的源,应该在工具自己控制的目录里**。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| --- | --- | --- |
+| ① 直接写 IDE 路径,无源(当前行为) | 实现最简 | 副本物理重复;升级 / 卸载 / AI 引用 / 漂移检测全都缺锚点;违反 P2 |
+| ② 用 OS 符号链接(symlink)统一指向单源 | 单点可控 | Windows symlink 不稳;权限 / 跨盘 / 反斜杠路径多个角点;大多数 git / IDE 对 symlink 行为不一致 |
+| ③ Hard link | 物理一致 | git 不跟踪 hard link;跨盘失败;实际效果不可预期 |
+| **④ source-mirror:`.teamix-evo/skills/` 为唯一源,工具按需镜像到 IDE 路径(本决策)** | 跨平台稳定;工具自己掌控镜像生命周期;升级 / 卸载 / 漂移检测都有锚点;AI 上下文引用源 | 物理上文件仍是 N+1 份(1 源 + N IDE 镜像),但**逻辑上单一来源** |
+
+## Decision
+
+### 1. 路径拓扑
+
+```
+packages/skills/<id>/SKILL.md
+       │ teamix-evo skills add <id>
+       ▼
+.teamix-evo/skills/<id>/SKILL.md         ← 源(consumer 拥有的工具产出,regenerable)
+       │ teamix-evo skills sync(隐式 / 装机时 / IDE 切换时)
+       ▼
+.qoder/skills/<id>/SKILL.md              ← IDE 镜像 1(regenerable)
+.claude/skills/<id>/SKILL.md             ← IDE 镜像 2(regenerable)
+.cursor/rules/<id>.mdc                   ← IDE 镜像 3(transformed,frontmatter 适配)
+```
+
+### 2. 路径语义对照表
+
+| 路径 | 谁拥有 | updateStrategy | 用户可改吗 | git 是否跟踪 |
+| --- | --- | --- | --- | --- |
+| `.teamix-evo/skills/<id>/SKILL.md` | 工具(consumer 侧的源) | regenerable | ❌(改了被覆盖) | ✅(让团队成员同步装机) |
+| `.qoder/skills/<id>/SKILL.md` | 工具(IDE 镜像) | regenerable | ❌ | ⚠️ 由消费方决定;推荐 .gitignore(从源 sync 即可) |
+| `.claude/skills/<id>/SKILL.md` | 工具(IDE 镜像) | regenerable | ❌ | ⚠️ 同上 |
+| `.cursor/rules/<id>.mdc` | 工具(IDE 镜像 + frontmatter 转译) | regenerable | ❌ | ⚠️ 同上 |
+
+> `.teamix-evo/skills/` 进 git;IDE 路径推荐放 `.gitignore`(因为可从源完全重建)。这一推荐写入 `create-teamix-evo` 的 base 模板的 `.gitignore`(v0.6 落地)。
+
+### 3. `.teamix-evo/skills/` 的实质价值
+
+1. **diff 基准**:升级时对比 `packages/skills/<id>/`(上游) 与 `.teamix-evo/skills/<id>/`(consumer 侧已装版本),判断有无变化(IDE 镜像可能已被异步更新或被某 IDE 写工具误改,不可靠)
+2. **lock 信息**:`.teamix-evo/skills/manifest.lock.json` 记录"装了哪些 skill / 哪个版本 / 装到哪些 IDE"
+3. **统一卸载**:`teamix-evo skills remove <id>` 知道要从哪几个 IDE 路径删干净
+4. **AI 上下文锚点**:MCP server / AGENTS.md / `teamix-evo skills` 子命令引用一个稳定路径,不绑定特定 IDE
+5. **无 IDE 装机也合法**:消费方装了 skill 但还没接 IDE,源仍存在于 `.teamix-evo/skills/`
+
+### 4. 命令族
+
+| 命令 | 行为 |
+| --- | --- |
+| `teamix-evo skills add <id>` | 1) 复制 `packages/skills/<id>/` → `.teamix-evo/skills/<id>/`;2) 调用 `sync` 镜像到 IDE |
+| `teamix-evo skills sync` | 把 `.teamix-evo/skills/<id>/` 重新镜像到所有已配置的 IDE 路径(检测 `.qoder/` `.claude/` `.cursor/` 是否存在) |
+| `teamix-evo skills upgrade <id>` | diff 上游 vs consumer 源,语义合并(无 baseline,见 ADR 0006 同源思想),写回源 + sync |
+| `teamix-evo skills remove <id>` | 从源 + 所有 IDE 镜像删干净 |
+| `teamix-evo skills list` | 读 `.teamix-evo/skills/manifest.lock.json` 输出 |
+| `teamix-evo skills doctor` | 检测 IDE 镜像与源是否漂移(被人手改);提示 `sync` 恢复 |
+
+### 5. `manifest.lock.json` Schema
+
+```jsonc
+// .teamix-evo/skills/manifest.lock.json
+{
+  "skills": {
+    "teamix-evo-manage": {
+      "version": "0.5.0",
+      "from": "@teamix-evo/skills",
+      "installedAt": "2026-05-18T...",
+      "mirroredTo": [
+        ".qoder/skills/teamix-evo-manage/",
+        ".claude/skills/teamix-evo-manage/"
+        // 若装机时检测到 .cursor 也存在则加 ".cursor/rules/teamix-evo-manage.mdc"
+      ]
+    }
+  }
+}
+```
+
+### 6. Cursor frontmatter 转译(无固定版本号,业务需要时再做 — 2026-05-19 用户决策)
+
+`.cursor/rules/<id>.mdc` 与 SKILL.md 格式不同:Cursor 的 `.mdc` 格式有特定 frontmatter(`description` / `globs` / `alwaysApply`)。**当 teamix-evo 决定支持 Cursor 时**,`sync` 命令对 `.cursor/` 镜像走转译流程:
+
+```
+SKILL.md (source, 通用 frontmatter) → MDC transformer → .cursor/rules/<id>.mdc
+```
+
+**当前状态(2026-05-19)**:teamix-evo 所有包**仅支持 Claude + Qoder 双 IDE**;Cursor 适配**无固定版本号**,推迟到业务真有 Cursor 用户提需求时再起新 ADR 演进(届时落地的内容:① `SkillIdeSchema` 加 `'cursor'` 枚举 ② `SkillsLockSchema` 的 `mirroredTo` 自然支持 ③ MDC transformer 设计 ④ Cursor IdeAdapter ⑤ `create-teamix-evo` `.gitignore` 加 `.cursor/rules/`)。
+
+本 ADR 仅锁定"Cursor 镜像由 sync 命令以转译形式产出,不是 raw copy"这一**预留原则** —— 真要落地时按本节模式扩展即可,不需要重新设计源-镜像架构。
+
+## Consequences
+
+- **Positive**:
+  - **P2 single source 真正成立** —— `.teamix-evo/skills/` 是唯一可信源,所有 IDE 镜像皆派生
+  - **跨平台稳定** —— 不依赖 symlink / hard link,纯文件复制,Windows / mac / Linux 行为一致
+  - **升级 / 卸载 / 漂移检测都有锚点** —— 工具侧拥有完整生命周期信息
+  - **AI 引用稳定路径** —— AGENTS.md / MCP server / skill MD 互引时,引用 `.teamix-evo/skills/`,不绑 IDE
+  - **Cursor 装机零额外成本** —— 同一源转译出 `.mdc`,新增 IDE 加一个 transformer 即可
+- **Negative**:
+  - 物理上文件 N+1 份 —— 但**逻辑上单一**,通过 `sync` / `doctor` 维护一致性
+  - 业务侧 git 策略需明示 —— `.teamix-evo/skills/` 入库 + IDE 路径 .gitignore;`create-teamix-evo` 生成的 `.gitignore` 模板默认已配
+  - 增加 `sync` / `doctor` 两个命令 —— CLI 命令族略胖,但语义清晰
+- **Trade-off**:
+  - 用"sync 显式调用 + git 策略约定"换"P2 真正成立 + 跨平台稳定 + 工具掌控生命周期 + Cursor 等新 IDE 接入零基础设施代价"
+
+## Implementation note
+
+落地工作量(v0.6,共 ~1.5 人日;`.cursor/` 镜像转译推到 v0.7):
+
+1. 写本 ADR(0.2)
+2. `packages/cli/` 修改 `runSkillsAdd`:写入 `.teamix-evo/skills/` 后调 `sync`(0.3)
+3. 新增 `teamix-evo skills sync` 命令(0.3)
+4. 新增 `teamix-evo skills doctor` 命令(漂移检测)(0.3)
+5. `manifest.lock.json` schema + Zod + 单测(0.2)
+6. `create-teamix-evo` base 模板 `.gitignore` 加 `.qoder/skills/` / `.claude/skills/` /(预留)`.cursor/rules/`(0.1)
+7. 文档:`packages/skills/AGENTS.md` + `packages/cli/README.md`(0.1)
+
+## Source
+
+- [PLAN §7 Phase 7](../../PLAN.md#phase-7--teamix-evoskills-包--双-ide-适配23-人日):skills 包 + 双 IDE IdeAdapter
+- 2026-05-18 用户讨论:[".teamix-evo/skills 跟 .qoder/skills 等是什么区别?"](source-mirror 模型推演)
+- [`docs/principles.md` P2](../principles.md#p2--single-source-of-truth--no-copies-no-caches):副本是漂移之源;本 ADR 是该原则在 skills 装机层的具象
+- [ADR 0006](0006-ui-upgrade-no-baseline.md):"无 baseline 语义合并"是 ui 侧的同型动作;skill upgrade 借鉴

package/dist/data/adr/0014-ui-biz-ui-templates-tier.md

@@ -0,0 +1,274 @@
+# 0014. UI 包分三层:`@teamix-evo/ui` / `@teamix-evo/biz-ui` / `@teamix-evo/templates`
+
+- **Status**: Proposed
+- **Date**: 2026-05-18
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0001 三层对齐](0001-three-layer-alignment.md) / [0005 UI 不分 variant](0005-ui-no-variant.md)(本 ADR 与之对照:ui 不分 variant,但 biz-ui 必须分) / [0010 design 默认+变体](0010-design-default-and-variants.md)
+
+## Context
+
+当前 [`packages/ui/`](../../packages/ui/) 集中了 89 个组件,边界是 [P4 / ADR 0001](0001-three-layer-alignment.md) 锁定的"shadcn ∪ antd 合集"。但有两类需求逐步浮现:
+
+### a) 业务组件(business components)
+
+例如 `OrgPicker`、`ApprovalCard`、`AuditLogTable`、`TenantSwitcher`。它们看起来"通用"(几乎所有 B 端产品都需要),但**实现都绑业务规则**:
+
+- 租户列表 API / 用户对象结构 / 登出流程 / 审批状态机定义
+- 字段语义、提交格式、权限边界
+
+把这些塞进 `packages/ui/` 会破坏 [ADR 0005 "UI 不分 variant"](0005-ui-no-variant.md) 的前提 —— ui 之所以不分 variant,是因为它**纯 UI、纯能力、品牌通过 token 注入**;业务组件不满足"品牌通过 token 注入即可"。
+
+### b) 页面模板(page templates)
+
+例如 `DashboardLayout`、`ListDetailPage`、`SettingsPage`、`FormWizardPage`。它们的特征:
+
+- 多 component 组合 + 路由 + 状态(引入 react-router 等 peer dep)
+- 业务侧装机后通常**改成自家的**;`frozen` 默认会阻碍这种用法
+- 其 manifest 含"用了哪些 component"的合成依赖图,是 L3 Patterns 知识的载体
+
+塞进 `packages/ui/` 会:
+
+- 污染 ui 的依赖盘(reactor-router 等不该是 ui 的 peer)
+- 弱化 ui "shadcn ∪ antd 合集"边界
+- 装机语义混乱(template add 一次装一页面 + 改路由,而 component add 一次装一组件)
+
+### 可选边界 — 上一轮讨论中曾考虑
+
+> 上一轮曾考虑把业务组件塞进 [ADR 0010](0010-design-default-and-variants.md) 的 `packages/design/variants/<name>/business/`,后被用户在 2026-05-18 讨论中否决:
+>
+> 1. **包的输出类型应该单一** —— design 永远只输出静态知识(MD / JSON / token),代码包(ui / biz-ui / templates)只输出 TSX。一旦 design 输出 TSX,build pipeline / lint / 测试范围 / 发布流程都要分两套
+> 2. **ESLint preset 应用边界** —— `@teamix-evo/eslint-config/presets/ui` 的规则对 biz 组件完全适用(都是 cva / lucide / 语义 token / 无相对路径 import);若 biz 组件在 design 子目录,preset glob 要扩到 design,**design 内部 lint 配置变得不一致**
+> 3. **CLI 命令对称** —— `teamix-evo ui add` / `teamix-evo biz-ui add` / `teamix-evo templates add` 是同形动作,共享源码注入实现;塞 design 会让"design business add" 变成 ui 安装器在 design 命令空间下的伪装
+> 4. **变体语义不混乱** —— design 的变体是"知识变体"(差异在文档/token);biz-ui 的变体是"组件变体"(差异在 TSX 实现)。两者通过名字关联,不应物理同位置
+
+## Options Considered
+
+| 选项 | 评价 |
+| --- | --- |
+| A. 全部塞 `packages/ui/`(component / block / template / business 不分) | 包定义崩塌(P4 边界破坏 + 业务依赖污染);ADR 0005 不分 variant 的前提失效 |
+| B. business 塞 `packages/design/variants/<name>/business/` + templates 塞 ui | design 输出类型不单一(知识 + TSX);ESLint preset 边界崩;CLI 命令不对称 |
+| **C. 三层独立分包(本决策)**:ui(generic)+ biz-ui(variant-aware,业务)+ templates(generic 页面模板) | 包输出类型单一;ESLint preset glob 自然扩展;CLI 命令对称;变体语义清晰 |
+| D. 全部细分(component / block / template / business 各自独立包) | 4 包过度工程;block 与 component 同样 generic 同样规则,无理由分包 |
+
+## Decision
+
+### 1. 三层四类的最终归属
+
+| 粒度 | 例子 | 是否绑业务 | 是否绑变体 | 包归属 |
+| --- | --- | --- | --- | --- |
+| **component** | Button / Input / Dialog / Select | ❌ | ❌ | `@teamix-evo/ui` |
+| **block** | FilterBar / EmptyState / PageHeader / CommandBar | ❌ | ❌ | `@teamix-evo/ui` |
+| **template** | DashboardLayout / ListDetailPage / SettingsPage / FormWizardPage | ❌(layout 不绑业务流程) | ✅(必绑 variant,2026-05-18 用户改动) | `@teamix-evo/templates`(新) |
+| **business** | OrgPicker / ApprovalCard / AuditLogTable / TenantSwitcher | ✅ | ✅(必绑 variant) | `@teamix-evo/biz-ui`(新) |
+
+### 2. 包结构
+
+```text
+packages/ui/                           # @teamix-evo/ui — 现状,扩 entry type 到 component+block
+└── src/components/...
+
+packages/biz-ui/                       # 🆕 @teamix-evo/biz-ui — 业务 ui,变体感知
+└── variants/                          #   仅有 variants/(无 default)
+    ├── _template/                     #   minimal 模板(同 ADR 0010 风格)
+    ├── opentrek/
+    │   ├── org-picker/
+    │   ├── approval-card/
+    │   └── manifest.json
+    └── uni-manager/                   #   空骨架,展示多变体接入路径
+        └── manifest.json
+
+packages/templates/                    # 🆕 @teamix-evo/templates — 页面模板,变体感知(2026-05-18 用户改动)
+└── variants/                          #   镜像 biz-ui 形态:仅有 variants/(无 default)
+    ├── _template/                     #   minimal 起点
+    │   ├── _empty-shell/              #   通用占位页(新变体 fork 时拷过来改)
+    │   └── manifest.json
+    ├── opentrek/
+    │   ├── dashboard-layout/
+    │   ├── list-detail-page/
+    │   ├── form-wizard-page/
+    │   ├── settings-page/
+    │   └── manifest.json
+    └── uni-manager/                   #   空骨架
+        └── manifest.json
+```
+
+### 3. biz-ui **没有 default/**(关键决策)
+
+> 上一轮曾考虑给 biz-ui 加 `default/`(放 TenantSwitcher / UserAvatar 等"几乎所有 B 端都有"的组件),用户 2026-05-18 反推:**这违反了边界 — block 已经覆盖了"通用 UI 抽象",带业务的就该绑变体。**
+
+- 真正不绑业务的部分(下拉选择 + 头像渲染) → 升级为 `ui` 的 block
+- 带业务规则的部分(租户列表来源 / 切换 API / 登出流程) → 必绑 variant
+
+**biz-ui 仅有 `variants/`**;没有 default 时,CLI 装 biz 必须指定变体:
+
+```bash
+teamix-evo biz-ui add org-picker --variant opentrek
+# 若 .teamix-evo/design/pack.lock.json 已锁定变体,可省略 --variant
+```
+
+边界从而清晰:
+
+| 包 | 边界 | 装机时选变体? |
+| --- | --- | --- |
+| `ui` | 纯 UI 能力(component + block),不绑业务,不绑变体(品牌通过 token 注入) | ❌ |
+| `biz-ui` | 业务 UI 实现,**绑业务 + 绑变体** | ✅ |
+| `templates` | 页面骨架,**绑变体**(2026-05-18 改动);slot 模式仍可在变体内使用 | ✅ |
+
+### 4. templates 与 biz-ui 同形:variant-aware,镜像 `variants/<name>/` 结构(2026-05-18 用户改动)
+
+> 旧版本曾论证"templates 变体无关 + 通过 slot 接 biz-ui"。2026-05-18 用户决定:**templates 也按 variant 产出**,与 biz-ui 同形(`variants/` 仅,无 default)。
+
+**理由**:
+
+- **变体语义对称**:design / biz-ui / templates 三包通过同一变体名(`opentrek` / `uni-manager`)关联;装机选定变体后,三包**统一按该变体输出**,装机产物一目了然
+- **页面专属合成**:某些 page 在不同变体下是**完全不同的合成**(opentrek 的 `AdminConsoleLayout` 内嵌了变体专属 widget;uni-manager 同名 layout 长完全不一样),变体无关无法表达这种差异
+- **slot 模式仍兼容**:在变体内 page 仍可保留 slot/prop 接 biz-ui — 这是变体内部的实现选择,不影响包级变体感知
+
+**取舍**:
+
+- 代价:真正"通用"的 page shape(如 `EmptyAppShell` / `BlankAuthLayout`)在多个 variant 间会**物理重复**(各 variant 独立维护一份)
+- 缓解:`_template/` 起 minimal 模板,新变体 fork 时几乎零成本拿到一组通用 page shape 起点;若未来通用 templates 真的负担过重,再考虑加 `default/`(对照 design 形态)
+- 这与 ADR 0005 的"ui 不分 variant"形成对称表达:**ui 纯能力 = 不绑;biz-ui 业务 = 必绑;templates 页面合成 = 必绑**
+
+slot 模式示意(在变体内仍可用):
+
+```tsx
+// packages/templates/variants/opentrek/list-detail-page/index.tsx
+<ListDetailPage
+  filterBar={<MyOrgFilter />}        // 业务侧自填 or biz-ui#opentrek 提供
+  detail={<MyOrgDetail />}
+  list={<MyOrgList />}
+/>
+```
+
+### 5. UiEntryType 不加 'business'
+
+业务通过**包归属**表达,不需要在 entry type 上区分:
+
+```ts
+// packages/registry/src/schema/manifest.ts
+export const UiEntryTypeSchema = z.enum([
+  'component',  // ui 包
+  'block',      // 🆕 ui 包(扩)
+  'template',   // 🆕 templates 包
+]);
+```
+
+biz-ui 的 entry 直接用 `component` 或 `block`(技术上和 ui 同质),只是**包归属不同 + manifest 含 variant 字段**。
+
+### 6. biz-ui / templates manifest 增量 — `variant` 字段(2026-05-18 改动:templates 也加)
+
+biz-ui 与 templates 的 entry 都必须声明 variant:
+
+```jsonc
+// biz-ui 示例
+{
+  "name": "org-picker",
+  "type": "component",
+  "variant": "opentrek",          // 必填,与 design 变体名同步
+  "files": [/* ... */],
+  "dependencies": ["@radix-ui/react-popover"],
+  "registryDependencies": ["popover", "input"]  // 引用 ui 包的 entries
+}
+
+// templates 示例(2026-05-18 改动)
+{
+  "name": "list-detail-page",
+  "type": "template",
+  "variant": "opentrek",          // 必填,与 design / biz-ui 变体名同步
+  "files": [/* ... */],
+  "dependencies": ["react-router-dom"],
+  "registryDependencies": ["table", "card", "filter-bar"]
+}
+```
+
+### 7. 软关联 — design `pack.json` 的 `linked.biz-ui` / `linked.templates`(2026-05-18 改动:templates 也加)
+
+design `pack.json` 含 `linked.biz-ui` 与 `linked.templates` 字段,装机时校验存在(见 [ADR 0010](0010-design-default-and-variants.md) §7 schema):
+
+```jsonc
+// packages/design/variants/opentrek/pack.json
+{
+  "name": "opentrek",
+  "displayName": "OpenTrek",
+  "extends": "default",
+  "linked": {
+    "biz-ui": "@teamix-evo/biz-ui#opentrek",     // 装 design opentrek 时提示同步装
+    "templates": "@teamix-evo/templates#opentrek" // 同上
+  }
+}
+```
+
+### 8. CLI 命令族(2026-05-18 改动:templates 加 --variant)
+
+| 命令 | 装哪类 | 装到哪 |
+| --- | --- | --- |
+| `teamix-evo ui add <id>` | component / block | `src/components/ui/<id>.tsx`(frozen) |
+| `teamix-evo biz-ui add <id> --variant <name>` | component(包归属 biz-ui) | `src/components/business/<id>.tsx`(frozen) |
+| `teamix-evo templates add <id> --variant <name>` | template(包归属 templates) | `src/pages/<id>/` 或 `src/templates/<id>/`(frozen) |
+
+> 若 `.teamix-evo/design/pack.lock.json` 已锁定变体,biz-ui add / templates add 可省略 `--variant`。
+
+### 9. ESLint preset 扩展
+
+`@teamix-evo/eslint-config/presets/ui` 与 `presets/consumer` 的 glob 自然扩展到 biz-ui / templates:
+
+```js
+// 工程仓:packages/biz-ui/eslint.config.js + packages/templates/eslint.config.js
+import uiPreset from '@teamix-evo/eslint-config/presets/ui';
+export default [
+  { ignores: [/* ... */] },
+  ...uiPreset,
+];
+
+// consumer 侧:src/components/{ui,business}/**, src/{pages,templates}/** 都进 consumer preset
+```
+
+### 10. 变体一致性的反熵(2026-05-18 改动:校验范围扩到三包)
+
+design / biz-ui / templates **三包共享同一变体名空间**(协议级 ID,新增 / 重命名 走 ADR)。v0.9 [drift-scan](../../PLAN.md#128-v09--反熵层落地18-28-人日) 加校验:
+
+- 所有出现在 `packages/design/variants/<name>/` 的 name,必须在 `packages/biz-ui/variants/<name>/` 与 `packages/templates/variants/<name>/` 都有对应目录(可空)
+- 反向同理(任何一包独有的变体名都视为漂移)
+- 不一致时 `teamix-evo doctor` 报告 + CI 失败
+
+v0.6 阶段先用手工 check 脚本(`scripts/check-variant-sync.ts`)兜底,扫三包变体目录交集 / 差集。
+
+## Consequences
+
+- **Positive**:
+  - **包输出类型单一** —— ui / biz-ui / templates 都输出 TSX;design 永远只输出静态知识。每个包的 build / lint / 测试 / 发布流程一致
+  - **ESLint preset 全包覆盖零成本** —— `@teamix-evo/eslint-config/presets/ui` 一份配置,glob 自然扩到 biz-ui / templates
+  - **CLI 命令对称** —— ui add / biz-ui add / templates add 共享源码注入实现,行为一致
+  - **变体语义对称** —— design / biz-ui / templates 三包共享同一变体名空间(opentrek / uni-manager / ...),装机选定变体后三包统一按该变体输出 — 装机产物可预期(2026-05-18 改动后)
+  - **业务消费方可裁剪** —— 只用通用 ui + 自家手写业务组件 + design 知识的项目,完全不装 biz-ui / templates
+  - **ADR 0005 边界保留并对称表达** —— ui 不绑(纯能力);biz-ui 必绑(业务);templates 必绑(页面合成),三种粒度对应三种边界
+- **Negative**:
+  - 包数 +2(biz-ui / templates),pnpm-workspace.yaml 多两行,装机文档多两个命令
+  - 变体名跨**三包**同步成本 —— v0.6 手工 check 三包变体目录;v0.9 doctor 落地
+  - 通用 page shape(`EmptyAppShell` 等)在多变体间物理重复 —— `_template/` minimal 起点缓解,但仍不如单一 default 优雅
+- **Trade-off**:
+  - 用"+2 包 + 三包变体名同步成本 + 通用 page 物理重复"换"包输出类型单一 + lint 全覆盖 + CLI 对称 + 三包变体语义统一 + 业务可裁剪"
+  - 用"templates 必绑变体的物理重复"换"变体专属页面合成的表达力 + 三包变体语义对称 + 装机产物可预期"
+
+## Implementation note
+
+落地工作量(v0.6,共 ~2.2 人日;2026-05-18 改动后较原方案 +0.2):
+
+1. 写本 ADR(0.3)
+2. `packages/biz-ui/` 包基建 + manifest schema(`variant` 字段)+ 1-2 个示例(从现 OpenTrek `business/` 抽出)(0.7)
+3. `packages/templates/` 包基建 + `variants/{_template, opentrek, uni-manager}/` 三目录 + opentrek 下 1 个示例(`list-detail-page` 空骨架)(0.7,2026-05-18 改动:+0.2)
+4. `packages/registry/src/schema/manifest.ts` 加 'block' / 'template' 到 `UiEntryTypeSchema` + biz-ui/templates entry 加 `variant` 字段(0.2)
+5. CLI 加 `biz-ui add` / `templates add --variant` 子命令(0.5,复用 ui 安装器逻辑)
+6. ESLint preset glob 自然扩展(配置层只需 `eslint.config.js` 引用 preset)(0.1)
+7. `scripts/check-variant-sync.ts` 手工兜底脚本,扫 design / biz-ui / templates 三包变体目录交集 / 差集(0.2)
+8. 文档:`packages/biz-ui/AGENTS.md` + `packages/templates/AGENTS.md`(0.5)
+
+## Source
+
+- [ADR 0001](0001-three-layer-alignment.md):三层对齐;本 ADR 落实"工程 = shadcn"在三个粒度的具体形态
+- [ADR 0005](0005-ui-no-variant.md):ui 不分 variant 的前提保留;biz-ui / templates 必须分 variant 形成对照
+- [ADR 0010](0010-design-default-and-variants.md):design 变体模型;本 ADR 共用变体名空间;`linked.biz-ui` / `linked.templates` 字段对接 design pack manifest
+- 2026-05-18 用户讨论(轮 1):["业务组件和页面模板,放到 ui 下还是新建包?"](biz-ui 独立包论证 + biz-ui 不需要 default/ 反推)
+- 2026-05-18 用户改动(轮 2):**templates 改为 variant-aware**,与 biz-ui 同形(仅 variants/,无 default);三包共享同一变体名空间;manifest 加 `variant` 字段;CLI `templates add` 加 `--variant`;变体一致性反熵校验范围由两包扩到三包
+- [`packages/design/library/opentrek/business/`](../../packages/design/library/opentrek/business/):现 OpenTrek 业务上下文目录,本 ADR 决策迁出至 biz-ui