@teamix-evo/mcp 0.3.0 → 0.4.0

package/dist/data/adr/0020-design-to-tokens-skill-fusion.md

@@ -0,0 +1,139 @@
+# 0020. Design 包降级为 Tokens 包，设计知识全面迁入 Skills
+
+- **Status**: Accepted
+- **Date**: 2026-05-27
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: 0010 (supersedes design default-and-variants), 0016 (supersedes DESIGN.md brand charter ownership), 0017 (supersedes MCP design group)
+
+## Context
+
+### 问题
+
+1. **design 包职责过重**：同时承载构建时资产（tokens）和 AI 知识（philosophy / patterns / scenarios），两类内容的消费者完全不同（CSS bundler vs AI assistant）。
+2. **内容重复**：design 包的 patterns/page-types.md 等内容与 skills 包的 design-rules skill 有概念重复，维护时需要双处同步。
+3. **装机产物臃肿**：`design init` 向消费者项目写入大量 `.teamix-evo/design/**` 文件，而这些文件只有 AI 在运行时才读取——业务开发者实际只需要 tokens。
+4. **设计师侧已有完整规则体系**（`teamix-evo-design` 独立仓库），需要融合吸收到我们的工程体系中。
+5. **Tailwind v4 的 CSS-native 配置**使得 `tailwind.preset.ts` 已不需要，token 传递只需一个 `theme.css`。
+
+### 约束
+
+- 消费者的 Tailwind CSS v4 构建工具链必须能 `@import` 到真实的 token CSS 文件
+- AI 技能（skills）是跨 IDE 工作的唯一知识载体（Qoder / Claude / Cursor 均支持）
+- 变体（opentrek / uni-manager）需要独立的完整技能包，不依赖"基线 + overlay"模式
+- 与设计师侧 `teamix-evo-design` 仓库的融合路径要明确
+
+## Options Considered
+
+| 选项                                                       | 优点               | 缺点                                     |
+| ---------------------------------------------------------- | ------------------ | ---------------------------------------- |
+| A. 保持 design 包现有架构，手动同步                        | 零改动             | 永远双处维护、新人困惑                   |
+| B. design 包保留但 "瘦身"（移除 patterns 等）              | 改动较小           | 包名暗示它承载"设计"，新人仍会在此找规则 |
+| **C. design 改名 tokens，设计知识全量迁入 skills（选定）** | 包名即职责、零歧义 | 改动面大、需废弃多个 ADR                 |
+
+## Decision
+
+### 1. 包重命名与精简
+
+- `packages/design/` → `packages/tokens/`，npm 包名 `@teamix-evo/design` → `@teamix-evo/tokens`
+- tokens 包只保留：
+  - `tokens/` — token 源文件（theme.css + overrides.css 模板），按变体分目录
+  - `manifest.json` — 变体列表（供 CLI 枚举）
+  - 各变体的 `pack.json`（身份标识）
+- 移除：`default/philosophy/`、`default/foundations/`（非 token 文件如 spacing.md）、`default/patterns/`、`default/scenarios/`、`variants/*/brand/`、所有 AGENTS.md/CLAUDE.md/DESIGN.md 模板
+
+### 2. Skills 目录重命名
+
+- `packages/skills/skills/` → `packages/skills/src/`，消除冗余嵌套
+
+### 3. 设计基线 Skill 废弃，变体 Skill 自包含
+
+- **删除** `teamix-evo-design-rules`（原基线 skill）
+- **删除** `teamix-evo-design-rules-uni-manager`（暂不研发）
+- `teamix-evo-design-rules-opentrek` 升级为**完整自包含技能**，含：
+  - SKILL.md（trigger + dispatcher）
+  - generation-flow.md（AI 行为流程）
+  - boundaries.md（硬约束）
+  - checklist.md（自检清单）
+  - rules/（页面类型、布局、组件规格、样式规则等）
+  - patterns/（列表页、详情页、表单页等具体模式）
+- Skill 中**不硬写 token 具体值**，统一写"参照 `tokens/theme.css` 中的 `--spacing` 等变量"——让 AI 运行时读 token 文件获取实际值
+
+### 4. DESIGN.md 归属变更
+
+- DESIGN.md 模板从 design 包移入 `packages/create/`，在 `npm create teamix-evo` 时生成到项目根目录
+- 内容：品牌身份 + 设计理念 + 工具链指引（skills / eslint / ui / tokens 索引）
+
+### 5. Token 装机位置
+
+- `teamix-evo design init <variant>` 改为 `teamix-evo tokens init <variant>`（或保留 design 作为 CLI alias）
+- 装机产物位于**业务项目根目录**：
+  ```
+  my-project/
+  ├── tokens/
+  │   ├── theme.css       ← @theme 声明（regenerable）
+  │   └── overrides.css   ← 用户覆盖（frozen）
+  └── ...
+  ```
+- 不再有 `.teamix-evo/design/` 和 `.teamix-evo/tokens/` 嵌套目录，tokens 直接在根 `tokens/`
+
+### 6. MCP 精简
+
+- **移除** `design_list_principles`、`design_list_patterns`、`design_get_pattern`、`design_get_brand`
+- **保留并重命名** `design_get_tokens` → `tokens_get`（从项目根 `tokens/` 读取）
+- 设计知识 AI 直接从 skill 文件读取，不绕 MCP
+
+### 7. 通用 vs 变体内容治理
+
+- 通过 ADR 文档约束研发时哪些内容是"通用知识"（可跨变体复用），哪些是"变体独有"
+- 通用知识（如"间距必须 4px 倍数""危险操作必须二次确认"）在 ADR 中定义，各变体 skill 引用 ADR 编号
+- 变体独有内容（如"OpenTrek 品牌色用法""AI 副驾驶场景"）仅在对应 skill 中维护
+- 新增变体时，从现有变体 skill 复制并修改，通过 ADR 引用确保通用规则一致
+
+### 8. preferences.css 归属
+
+- `preferences.css` 从 design 包迁入 `packages/ui/`，随 `ui init` 装机
+
+## Consequences
+
+- **Positive**:
+  - 包名即职责（tokens 包只有 tokens，skills 包只有 AI 知识）
+  - 消费者项目更干净（根 tokens/ + DESIGN.md，无 `.teamix-evo/design/` 树）
+  - AI 单次读取 skill 即获得完整上下文（无需先读 skill 再跳转 `.teamix-evo/design/` 读内容）
+  - 设计师侧内容融合路径明确（→ opentrek skill 的 rules/ 和 patterns/）
+  - Tailwind v4 对齐（只需 `@import "../../tokens/theme.css"`）
+- **Negative**:
+  - 改动面大（20+ 文件，多个 CLI/MCP 源码文件需修改）
+  - ADR 0010 / 0016 / 0017 废弃，需要时间收敛文档
+  - 旧版本消费者项目升级只需 `mv .teamix-evo/tokens tokens`
+- **Trade-off**:
+  - 为了包名语义清晰和 AI-first 体验，放弃了 design 包作为"设计体系知识中心"的传统定位
+  - 为了变体 skill 自包含，放弃了"基线 + overlay"的 DRY 复用，接受少量跨变体内容重复（通过 ADR 引用治理）
+
+## Migration Path
+
+### Phase 1: 结构变更（本次执行）
+
+1. `packages/design/` → `packages/tokens/`，更新 package.json name
+2. tokens 包精简内容（只留 token 文件 + manifest）
+3. `packages/skills/skills/` → `packages/skills/src/`
+4. 删除 `teamix-evo-design-rules` 和 `teamix-evo-design-rules-uni-manager`
+5. 重构 `teamix-evo-design-rules-opentrek` 为完整技能（吸收设计师规则）
+6. MCP design group 精简为 tokens_get
+7. CLI design-init 核心逻辑适配
+
+### Phase 2: 引用收敛
+
+8. 更新所有文档（AGENTS.md、architecture.md、ADR 索引）
+9. 更新 CLI 命令实现（design → tokens 或保持 design alias）
+10. 更新 registry schema（design-pack → tokens-pack）
+11. 更新 check-variant-sync 等脚本
+
+### Phase 3: 消费者侧迁移
+
+12. CLI 新增 `tokens migrate` 命令（`.teamix-evo/tokens/` → 根 `tokens/`，已实现核心路径变更）
+13. create 包 preset 模板直接使用根 `tokens/` 结构
+14. 文档站更新安装指引
+
+## Source
+
+对话决策（2026-05-27）— 设计师侧 `teamix-evo-design` 仓库与工程侧 design 包融合分析中，确认了"按消费者分包"原则：tokens 归构建工具链，设计知识归 AI skills。

package/dist/data/adr/README.md

@@ -0,0 +1,70 @@
+# Architecture Decision Records
+
+> 本目录沉淀 Teamix Evo 的"为什么这么做"——决策的上下文、选项、取舍与后果。
+> 设计参照 [Michael Nygard. *Documenting Architecture Decisions*. 2011](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions)。
+
+## 为什么需要 ADR
+
+[`PLAN.md`](../../PLAN.md) 是 71KB 的路线图,记录"做什么 / 怎么做 / 何时做"。但当问"为什么当初选了 A 而不是 B"时,PLAN.md 给不出答案——它的附录 B 变更记录只有"做了什么",没有"为什么是这个选项"。
+
+ADR 补这一层。每条 ADR 是一份**单决策档案**:在某一时刻、某一上下文下、为什么我们选了这个选项、付出了什么代价。
+
+## 编号区段约定
+
+ADR 按编号区段对应 [PLAN §12](../../PLAN.md#12-五层模型驱动的演进规划v05) 的抽象层:
+
+| 编号区段 | 抽象层 | 内容 |
+| --- | --- | --- |
+| 0001–0099 | 工程哲学（Philosophy） | 跨工种共享、几乎不变的工程理念 |
+| 0100–0999 | 协议与工具（Foundations + Patterns） | CLI 命令、Schema、组件、Skills、MCP 等具体协议决策 |
+| 1000+ | 业务消费方决策（Scenarios） | 真实业务团队装机后的领域决策 |
+
+> **种子 ADR 的特殊处理**:0001–0006 是 P0-1 任务从 PLAN.md §1 / §10 / §11 / 附录 B 反向沉淀的"已发生决策",作为种子条目使用顺序号,不严格按区段分配。从 0007 起按区段约定执行。
+
+## 当前 ADR 索引
+
+| # | 标题 | 状态 | 日期 |
+| --- | --- | --- | --- |
+| 0001 | [三层对齐(能力/理念/工程)](0001-three-layer-alignment.md) | Accepted | 2026-05-15 |
+| 0002 | [包命名方案](0002-package-naming.md) | Accepted | 2026-05-13 |
+| 0003 | [资源升级三态语义](0003-update-strategy-tri-state.md) | Accepted | 2026-05-13 |
+| 0004 | [CLI 命令结构](0004-cli-command-structure.md) | Accepted | 2026-05-13 |
+| 0005 | [UI 包不分 variant](0005-ui-no-variant.md) | Accepted | 2026-05-14 |
+| 0006 | [UI 升级机制无 baseline](0006-ui-upgrade-no-baseline.md) | Accepted | 2026-05-14 |
+| 0007 | [治理文档放根目录,与 packages/docs/ 分离](0007-governance-docs-at-root.md) | Accepted | 2026-05-17 |
+| 0008 | [ESLint 视觉规则暂为 warn 级,等待 design 补 token](0008-eslint-visual-rules-warn-baseline.md) | Accepted | 2026-05-17 |
+| 0009 | [registry-mcp 作为 AI 协议层的第一个 MCP server](0009-registry-mcp-protocol-layer.md) | Superseded in part by 0011 | 2026-05-17 |
+| 0010 | [design 默认+变体模型(default + variants/ + extends,文件级覆盖)](0010-design-default-and-variants.md) | Proposed | 2026-05-18 |
+| 0011 | [MCP 单包单 bin 多 group + registry-mcp 改名 mcp](0011-mcp-single-package-multi-group.md) | Proposed | 2026-05-18 |
+| 0012 | [ESLint/Stylelint 双包共享 lint-core 内核](0012-lint-shared-core.md) | Proposed | 2026-05-18 |
+| 0013 | [Skills source-mirror 模型(.teamix-evo/skills/ 为源)](0013-skills-source-mirror.md) | Proposed | 2026-05-18 |
+| 0014 | [ui / biz-ui / templates 三层包分层(三包共享变体名空间)](0014-ui-biz-ui-templates-tier.md) | Proposed | 2026-05-18 |
+| 0019 | [已有工程升级 Teamix Evo 流程(语义合并 / 变体迁移 / cva codemod)](0019-project-upgrade-flow.md) | Proposed | 2026-05-21 |
+
+## 写新 ADR 的流程
+
+1. **触发**:遇到"两条以上路都能跑通,需要选一条且代价不可逆"的决策
+2. **复制模板**:`cp _template.md NNNN-<short-slug>.md`(NNNN 按所属区段递增)
+3. **填写五段**:Status / Context / Decision / Consequences / Source
+4. **PR**:同 PR 内修改对应代码 + 此 ADR
+5. **登记**:更新本 README 索引表
+6. **生命周期**:Accepted → Superseded(被新 ADR 替代时不删,标 Superseded by NNNN)/ Deprecated(决策不再适用但无替代方案)
+
+## 状态值
+
+| 状态 | 含义 |
+| ---- | ---- |
+| Proposed | 草案,等待评审 |
+| Accepted | 已采纳并执行 |
+| Superseded by NNNN | 被另一条 ADR 替代 |
+| Deprecated | 决策不再适用,但无新替代 |
+
+## 反向约束
+
+reviewer subagent(规划于 [v0.7](../../PLAN.md#126-v07--协议层升级15-22-人日))会在 PR 时主动引用相关 ADR,检测变更是否违反某条已 Accepted 的决策。当代码改动需要绕开某条 ADR 时,正确流程是:
+
+1. 写一条新 ADR(状态 Proposed)说明为什么要修改
+2. 评审通过后将旧 ADR 标 Superseded by 新 ADR
+3. 再修改代码
+
+不允许"改代码绕开已有 ADR 而不留任何 ADR 痕迹"。

package/dist/data/adr/_template.md

@@ -0,0 +1,36 @@
+# NNNN. <一句话决策标题>
+
+- **Status**: Proposed | Accepted | Superseded by NNNN | Deprecated
+- **Date**: YYYY-MM-DD
+- **Region**: 0001–0099 工程哲学 | 0100–0999 协议与工具 | 1000+ 业务消费方
+- **Related ADR**: (引用相关 ADR 编号,可空)
+
+## Context
+
+<决策的背景:面对什么问题、有哪些约束、为什么不能不做。>
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| A    |      |      |
+| B    |      |      |
+
+(若决策本身只有一个明显选项,可省略本节)
+
+## Decision
+
+<决策内容,陈述句。能用一句话概括最好,否则用编号 list。>
+
+## Consequences
+
+- **Positive**:
+  - <好的后果>
+- **Negative**:
+  - <代价、风险>
+- **Trade-off**:
+  - <为了得到 X 我们放弃了 Y>
+
+## Source
+
+<决策的原始出处:PLAN.md §X / 某次对话 / 某个 issue / 某份外部资料>

package/dist/index.d.ts

@@ -100,9 +100,11 @@ interface LoadedAdrs {
  * Resolves the ADR directory using a layered strategy:
  *
  *   1. `TEAMIX_EVO_ADR_ROOT` env var (absolute path)
- *   2. Walk up from cwd looking for `docs/adr/` (monorepo layout)
- *   3. Walk up from cwd looking for `.teamix-evo/adr/` (consumer layout — future)
- *   4. Throws with a clear error
+ *   2. Bundled snapshot at `<mcp-pkg>/dist/data/adr/` (works in consumer projects
+ *      after `pnpm add @teamix-evo/mcp` — see tsup.config.ts onSuccess copy)
+ *   3. Walk up from cwd looking for `docs/adr/` (monorepo layout)
+ *   4. Walk up from cwd looking for `.teamix-evo/adr/` (consumer override)
+ *   5. Throws with a clear error
  */
 declare function resolveAdrRoot(startDir?: string): string;
 declare function loadAdrIndex(rootDir?: string): LoadedAdrs;
@@ -151,34 +153,17 @@ interface SkillsGroupOptions {
 }
 declare function createSkillsGroup(opts?: SkillsGroupOptions): ToolGroup;
 
-interface LoadedDesign {
-    /** Absolute path to `.teamix-evo/design/` in the consumer project. */
+interface LoadedTokens {
+    /** Absolute path to `.teamix-evo/` in the consumer project. */
     rootDir: string;
-    /** Variant name read from `pack.lock.json`, or null if missing. */
+    /** Variant name read from `tokens-lock.json`, or null if missing. */
     variant: string | null;
 }
-declare function resolveDesignRoot(startDir?: string): string | null;
-declare function loadDesign(rootDir?: string): LoadedDesign | null;
-interface PrincipleEntry {
-    id: string;
-    name: string;
-    oneLineDef: string;
-}
-/**
- * Parse `philosophy/principles.md` for headings of the form `## P1 · Name`.
- * Returns the principle id, display name, and the first non-blank line below
- * the heading as a one-line definition.
- */
-declare function readPrinciples(loaded: LoadedDesign): {
-    principles: PrincipleEntry[];
-    sourcePath: string | null;
-    note?: string;
-};
+declare function resolveTokensRoot(startDir?: string): string | null;
+declare function loadTokens(rootDir?: string): LoadedTokens | null;
 interface TokenSnapshot {
     /** Parsed contents of `base.tokens.json` if present. */
     base?: unknown;
-    /** Parsed contents of `semantic.tokens.json` if present. */
-    semantic?: unknown;
     /** Raw text of `tokens.theme.css` if present. */
     themeCss?: string;
     /** Raw text of `tokens.overrides.css` if present (user-owned overrides). */
@@ -187,50 +172,70 @@ interface TokenSnapshot {
     sources: string[];
     note?: string;
 }
-declare function readTokens(loaded: LoadedDesign): TokenSnapshot;
-interface PatternIndexEntry {
-    id: string;
-    title: string;
-    sourcePath: string;
-    variantSpecific: boolean;
+declare function readTokens(loaded: LoadedTokens): TokenSnapshot;
+interface TokenEntry {
+    /** Top-level group from base.tokens.json, e.g. "color" / "radius" / "spacing". */
+    category: string;
+    /** Token leaf name within the category, e.g. "primary" / "card-foreground". */
+    name: string;
+    /** W3C `$type` declared on the token, when present. */
+    type?: string;
+    /**
+     * Resolved values keyed by mode. For W3C tokens with `light` / `dark`
+     * sub-objects we emit both; for flat tokens (single `$value`) we emit
+     * `default`.
+     */
+    values: Record<string, string>;
+    /** First non-empty `$description` found on the token or its modes. */
+    description?: string;
 }
-declare function readPatternIndex(loaded: LoadedDesign): PatternIndexEntry[];
-declare function readPatternContent(loaded: LoadedDesign, id: string): {
-    id: string;
-    sourcePath: string;
-    content: string;
-} | null;
-interface BrandSnapshot {
-    tone?: {
-        sourcePath: string;
-        content: string;
-    };
-    voice?: {
-        sourcePath: string;
-        content: string;
-    };
-    examples?: {
-        sourcePath: string;
-        content: string;
-    };
+/**
+ * Flatten a W3C-format design-token JSON tree into a list of token entries.
+ *
+ * The format we ingest is the one shipped by `@teamix-evo/tokens`:
+ *
+ *   { color: { primary: { $type, light: { $value, $description }, dark: { ... } } } }
+ *
+ * For tokens with `$value` directly under the leaf (no light/dark split) we
+ * emit `values = { default: <value> }`.
+ *
+ * Top-level keys starting with `$` (e.g. `$schema`, `$version`) are skipped.
+ */
+declare function flattenTokens(base: unknown): TokenEntry[];
+interface TokenListResult {
+    variant: string | null;
+    tokens: TokenEntry[];
+    sources: string[];
     note?: string;
 }
-declare function readBrand(loaded: LoadedDesign): BrandSnapshot;
+declare function listTokens(loaded: LoadedTokens): TokenListResult;
+interface TokenSearchResult {
+    variant: string | null;
+    query: string;
+    matches: TokenEntry[];
+    sources: string[];
+    note?: string;
+}
+/**
+ * Substring match across category / name / description / values. Case-insensitive.
+ * Returns up to `limit` (default 20) matches ordered by category > name.
+ */
+declare function searchTokens(loaded: LoadedTokens, query: string, limit?: number): TokenSearchResult;
 
-interface DesignGroupOptions {
-    /** Pre-loaded design snapshot (used by tests). When omitted, the loader walks cwd. */
-    loaded?: LoadedDesign | null;
+interface TokensGroupOptions {
+    /** Pre-loaded tokens snapshot (used by tests). When omitted, the loader walks cwd. */
+    loaded?: LoadedTokens | null;
     /** Override the start directory for cwd-relative resolution (used by tests). */
     rootDir?: string;
 }
-declare function createDesignGroup(opts?: DesignGroupOptions): ToolGroup;
+declare function createTokensGroup(opts?: TokensGroupOptions): ToolGroup;
 
 /**
  * Main MCP server — composes multiple tool groups into one stdio process.
  *
  * Architecture per [ADR 0011](../../../docs/adr/0011-mcp-single-package-multi-group.md):
  * single package / single bin / multiple tool groups. Groups added in later
- * milestones (design v0.6, adr v0.7, scenario v0.8) plug in here without
+ * milestones (tokens v0.6, adr v0.7, scenario v0.8) plug in here without
  * touching the transport or ListTools/CallTool handler logic.
  *
  * Tool dispatch:
@@ -249,9 +254,9 @@ interface ServerOptions {
     adr?: AdrGroupOptions;
     /** Options forwarded to the skills group. Pass `loaded` in tests. */
     skills?: SkillsGroupOptions;
-    /** Options forwarded to the design group. Pass `loaded` in tests. */
-    design?: DesignGroupOptions;
+    /** Options forwarded to the tokens group. Pass `loaded` in tests. */
+    tokens?: TokensGroupOptions;
 }
 declare function createServer(opts?: ServerOptions): Server;
 
-export { type AdrEntry, type AdrGroupOptions, type BrandSnapshot, type DesignGroupOptions, type LoadedAdrs, type LoadedDesign, type LoadedManifest, type LoadedSkills, type ParsedMeta, type PatternIndexEntry, type PrincipleEntry, type RegistryGroupOptions, type ServerOptions, type SkillContent, type SkillsGroupOptions, type TokenSnapshot, type ToolGroup, type ToolResult, createAdrGroup, createDesignGroup, createRegistryGroup, createServer, createSkillsGroup, findAdr, findSkill, loadAdrContent, loadAdrIndex, loadDesign, loadManifest, loadMeta, loadSkillContent, loadSkillsManifest, readBrand, readPatternContent, readPatternIndex, readPrinciples, readTokens, resolveAdrRoot, resolveDesignRoot, resolveManifestPath, resolveSkillsRoot };
+export { type AdrEntry, type AdrGroupOptions, type LoadedAdrs, type LoadedManifest, type LoadedSkills, type LoadedTokens, type ParsedMeta, type RegistryGroupOptions, type ServerOptions, type SkillContent, type SkillsGroupOptions, type TokenEntry, type TokenListResult, type TokenSearchResult, type TokenSnapshot, type TokensGroupOptions, type ToolGroup, type ToolResult, createAdrGroup, createRegistryGroup, createServer, createSkillsGroup, createTokensGroup, findAdr, findSkill, flattenTokens, listTokens, loadAdrContent, loadAdrIndex, loadManifest, loadMeta, loadSkillContent, loadSkillsManifest, loadTokens, readTokens, resolveAdrRoot, resolveManifestPath, resolveSkillsRoot, resolveTokensRoot, searchTokens };