@teamix-evo/mcp 0.3.0 → 0.4.2

package/dist/data/adr/0032-opentrek-v4.1-brand-token-alignment.md

@@ -0,0 +1,129 @@
+# 0032. OpenTrek v4.1 brand token alignment
+
+- **Status**: Accepted
+- **Date**: 2026-11
+- **Region**: 0001–0099 工程哲学（信源轨）
+- **Related ADR**: 0010 (design-default-and-variants), 0020 (design-tokens-skill-fusion), 0021 (semantic-color-api-unification), 0023 (cursor-explicit-declaration), 0026 (component-level-token-alias), 0027 (component-visual-token-alignment)
+
+## Context
+
+OpenTrek 主题（`packages/tokens/variants/opentrek/`）在 v0.5.0 之前实际只是 shadcn slate 默认调色板的别名：
+
+- `--color-primary` 一直停在 `hsl(222.2 47.4% 11.2%)`（接近黑），从未真正品牌化为 `#0055EE`
+- 状态色仅有单档（`--color-success` / `-destructive` / `-warning` / `-info`），缺 hover/bg/border 衍生
+- 缺乏 OpenTrek 设计源中的 accent-10、chart-10、gray 8 级语义层
+- sidebar / topbar 业务色不完整
+- 字体族沿用 Inter，与产品实际使用的 PingFang SC 不符
+- radius 档位停在 shadcn 默认（4/6/8/12px），与 OpenTrek 设计源 v4.1 的 4/8/12/16/9999 不一致
+
+用户提供 v4.1 设计源（`design-tokens.css` 432 行 + `design-tokens.json` 1196 行 W3C 格式），要求全量翻译进仓库并联动 ui 组件 + um 同步。
+
+## Decision
+
+op variant 全量对齐 OpenTrek 设计源 v4.1，分三轨执行（信源轨 → 组件轨 → 知识轨），符合 ADR 0020。
+
+### 1. 信源轨：op tokens 全量品牌化
+
+**主色品牌化（最重要变化点）**：
+
+```css
+--color-primary: hsl(218.6 100% 46.7%); /* #0055EE */
+--color-primary-hover: hsl(218.6 100% 42%);
+--color-primary-pressed: hsl(218.6 100% 37.5%);
+--color-primary-glow: hsl(226.9 100% 68.6%);
+--color-ring: hsl(218.6 100% 46.7%);
+```
+
+所有 `bg-primary` / `border-primary` / `ring-primary` / `text-primary` 消费点自动从 slate 黑变 OpenTrek 蓝，影响 Button default、Checkbox/Switch checked、Pagination active 等。
+
+**状态色 5 档化**：success/warning/destructive/info 各自补齐 `-foreground` / `-hover` / `-pressed` / `-bg` / `-border`，warning 色相由蜜糖橙调整到 40° 与 destructive 0° 拉开。
+
+**扩展层**：
+
+- `--color-gray-*` 8 级语义（primary/primary-foreground/secondary-foreground/disabled/line/sidebar-accent/muted/white）
+- `--color-accent-{blue,violet,apricot,indigo,green,magenta,turquoise,orange,berry,olive}` 10 色调色板
+- `--color-chart-1..10`（覆盖原 5 色，扩到 10 色给数据可视化）
+- sidebar / topbar 业务色完整覆盖
+
+**radius 体系升级**（覆写 ADR 0027 opentrek 列）：
+
+| Token             | 旧值 | 新值 | 备注                 |
+| ----------------- | ---- | ---- | -------------------- |
+| `--radius`        | -    | 16px | base = 1rem          |
+| `--radius-sm`     | 4px  | 4px  | 不变                 |
+| `--radius-md`     | 6px  | 8px  | ↑ ADR 0027 v2        |
+| `--radius-lg`     | 8px  | 12px | ↑ ADR 0027 v2        |
+| `--radius-xl`     | 12px | 16px | ↑                    |
+| `--radius-full`   | -    | 9999 | 新增                 |
+| `--radius-2xl`    | 14px | -    | 移除（5 档体系）     |
+| `--radius-dialog` | 16px | 16px | 不变（组件级 token） |
+| `--radius-tag`    | 4px  | 4px  | 不变（组件级 token） |
+
+**字体族**：`--font-sans` 切到 `'PingFang SC', -apple-system, BlinkMacSystemFont, ...`，新增 `--font-weight-black: 900`、`--font-size-page-header: 18px`。
+
+**业务尺寸 token**：layout（sidebar/topbar/page-header/breadcrumb）、spacing（btn-padding-x/-sm、button-gap、card-gap、page-container-\_）、card-grid（compact/standard/comfortable/feature）、table、form、input、dialog、drawer、pagination、stepper 全套显式声明，给 ui 组件按需消费。
+
+**shadow / animation / z-index**：shadow 9 档（none/sm/DEFAULT/md/lg/xl/2xl/dialog/select-content）、duration 5 档、easing 5 档、z-index 6 档全部显式声明。
+
+**暗色模式**：保持 `.dark { ... }` 块结构，主色 `--color-primary` 提亮为 `hsl(218.6 100% 60%)`。
+
+base.tokens.json（W3C 格式）同步同等变更，`pnpm --filter @teamix-evo/tokens validate` 必须通过。
+
+### 2. um 同步声明（不改值）
+
+op 引入的"业务尺寸 token"在 um theme.css 同名声明并独立持值（cd hybridcloud 风格），保证 ui 组件在 um 主题下不丢值。关键差异：
+
+| Token                      | op 取值     | um 取值                     |
+| -------------------------- | ----------- | --------------------------- |
+| `--btn-padding-x`          | 16px        | 12px（cd 紧凑保持）         |
+| `--radius-md/lg/xl`        | 8/12/16px   | **2/4/8px**（锐利保持）     |
+| `--font-sans`              | PingFang SC | 已是 PingFang SC（不改）    |
+| `--shadow-{sm..2xl}`       | 新文档 5 档 | 保持已有 hybridcloud 5 档   |
+| `--accent-*` / `--chart-*` | 10 色       | 5 色（保持现有 chart-1..5） |
+
+um 既有特色 token（`--color-input-focus`、`--shadow-form-hover`、`--radius-dialog: 2px`、`--radius-tag`、scoped CSS focus/hover/dialog 块）全部保留不动。
+
+### 3. 组件轨：ui 第一批 token 化
+
+| 组件         | 改造点                                                                |
+| ------------ | --------------------------------------------------------------------- |
+| `PageHeader` | `min-h-[var(--page-header-height)]`；Actions gap 走 `--button-gap`    |
+| `Card`       | md/default size padding 走 `--card-padding-x`（20px）                 |
+| `Button`     | `px-3` → `px-[var(--btn-padding-x-sm)]`；lg 走 `--btn-padding-x`      |
+| `Pagination` | sm/md `min-w-7/8` → `--button-sm-height` / `--pagination-button-size` |
+
+第二批（ActionToolbar/DataTable/Sidebar/Stepper/BulkActionBar/Form\*）按需后续 PR；第三批 Dialog/Input padding 改动涉及视觉变化，单独执行确认。
+
+### 4. 知识轨：ADR 与 design skill
+
+- ADR 0027 追加 v2 决策块，标记 Partially superseded
+- 本 ADR（0032）记录决策
+- design skill 文档（OpenTrek-only AI 可读规则：sidebarRules / componentSpacing / colorMapping 等）按 ADR 0020 下沉到 `packages/skills/src/teamix-evo-design-opentrek/`，**不重复 token 数值**
+
+## Consequences
+
+- **Positive**:
+
+  - op 主题首次真正"品牌化"，与 OpenTrek 产品实际视觉一致
+  - 状态色 5 档 + 扩展色 10 色给后续表单态、可视化组件留好接入点
+  - 业务尺寸 token 化后，ui 组件在 op 与 um 主题下视觉一致由 token 控制，避免硬编码
+  - radius 升级让卡片/对话框/输入框圆角与 OpenTrek 设计源严格对齐
+
+- **Negative / BREAKING**:
+
+  - **品牌色变蓝是不可逆的全局视觉变化**：所有 `bg-primary` / `border-primary` 消费点（约 30+ 组件）自动变蓝，需 Storybook 视觉回归
+  - radius 升级（md 6→8、lg 8→12）影响 Card/Button/Input 等卡片态视觉，圆角更柔和
+  - Card md/default size padding 由 24px 收紧到 20px（-4px）
+  - Button lg 档水平 padding 由 12px 增至 16px（+4px）
+  - 部分 ADR 0027 数据表项被覆写（见 ADR 0027 Amendment）
+
+- **Neutral**:
+  - um 完全无视觉影响（独立持值）
+  - tokens 包 BREAKING 仅限 op variant token 名集合（移除 `--radius-2xl`）；ui 组件层未消费 `--radius-2xl`，外部使用方升级时仅需关心是否引用
+
+## Source
+
+- `/Users/lyca/Downloads/design-tokens.css` v4.1（432 行 shadcn v3 风格，由用户提供）
+- `/Users/lyca/Downloads/design-tokens.json` v7.8.4（1196 行 W3C 格式 + AI 可读规则块，由用户提供）
+- 已确认决策：全量翻译 / JSON 同步 / 联动 ui 组件 + um / radius 完整升级 / 字体切 PingFang SC
+- 实施 commits：op tokens（信源）→ um 同步 → 版本升级 → ui 第一批 → ADR

package/dist/data/adr/0033-entry-skill-global-only-scope.md

@@ -0,0 +1,64 @@
+# 0033. Entry skill 默认全局安装,bulk add 按 scope 过滤
+
+- **Status**: Accepted
+- **Date**: 2026-06-04
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0011](0011-mcp-single-package-multi-group.md)、[0013](0013-skills-source-mirror.md)、[0014](0014-ui-biz-ui-templates-tier.md)、[0030](0030-skill-uni-manager-uplift.md)
+
+## Context
+
+`@teamix-evo/skills` 当前混了两类性质完全不同的 skill,放在同一个 `manifest.skills` 数组里:
+
+| 类型 | 例子 | 安装语义 |
+| ---- | ---- | ---- |
+| **lifecycle skill / orchestrator** | `teamix-evo-manage` | 工具型。作为生命周期入口被调用(初始化、升级、卸载、placeholder→real 迁移)。**装一次即可**,不需要跟项目走。 |
+| **content skill / variant 内容** | `teamix-evo-design-<variant>`、`teamix-evo-code-<variant>` | 跟 variant 绑定。装在哪个项目就影响哪个项目的页面 / 文件生成规则。**必须随项目走**。 |
+
+实际用户路径:
+
+1. 用户先全局装 `teamix-evo-manage` 到 `~/.claude/skills/` —— 因为只有装了它,IDE 才能识别"初始化一个工程"这类自然语言指令、并触发 CLI。
+2. 该 skill 的「场景 2 / 3」会驱动 `npm create teamix-evo` 或 `npx teamix-evo skills add`,bulk 模式把 manifest 里全部 5 个 skill 一律装到 project scope —— 包含 `teamix-evo-manage` 自己。
+3. 结果:`~/.claude/skills/teamix-evo-manage/` 与 `<project>/.claude/skills/teamix-evo-manage/` 同时存在,IDE 同时识别两份。版本漂移、`skills doctor` 误报、用户不知道改哪份才能生效。
+
+约束:
+
+- 不希望强行禁止 manage 装到项目级(用户自有 override 需求,如离线分发场景)
+- 不希望破坏 skills package 的"单包多 entry"协议([ADR 0011](0011-mcp-single-package-multi-group.md))
+- 现存项目的 `skills-lock.json` 不能因此 schema 变更失效
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| A. SkillEntry 加 `scope` 字段,bulk init 按 scope 过滤(本决策) | 声明式;符合 manifest 契约;新增 lifecycle skill 只需打一个标签;现存 manifest 不写该字段也兼容 | 引入一个语义字段,需要 schema bump;CLI 增加分支 |
+| B. 运行时去重(`skills init` 检测 `~/.claude/skills/<id>` 已存在则跳过) | 不动 manifest | 依赖外部状态;同名不同版本时反而锁死;语义不显式 |
+| C. 在 `teamix-evo-manage` 自身的 SKILL.md 决策树里手动让 AI 排除 manage | 不动 CLI / manifest | 每次新增 lifecycle skill 都要改 markdown;契约不机器可读;AI 偏离指令时无法兜底 |
+| D. 把 `teamix-evo-manage` 拆成独立 npm 包 | 物理隔离 | 破坏单包多 group 原则;用户安装路径变复杂;需要 CI 改造 |
+
+## Decision
+
+1. `SkillEntrySchema`(`packages/registry/src/schema/manifest.ts`)新增可选字段 `scope: SkillScopeSchema.optional()`,复用已有的 `SkillScopeSchema = z.enum(['project', 'global'])`。`undefined` 视为隐式 `"project"`。
+2. `packages/skills/manifest.json` 中 `teamix-evo-manage` 标 `"scope": "global"`,其余 4 个 entry 不动。
+3. `runSkillsInit`(`packages/cli/src/core/skills-add.ts`,自举路径)candidate 过滤:若 `(s.scope ?? 'project') !== <current install scope>`,跳过(debug 日志说明)。**verb 命名见 [ADR 0034](0034-skills-cli-verb-alignment.md)**。
+4. `runSkillsAdd`(增量,显式指名)**不**过滤,但若指名的 skill 声明的 scope 与当前 scope 不一致,emit 一条 `logger.warn`,提示推荐 scope。**用户显式指令优先,自负责。**
+5. `create-teamix-evo` 的两个 preset(`opentrek` / `uni-manager`)从 `skills.entries` 移除 `teamix-evo-manage`。`skills.entries` 只剩 `design-${variant}` + `code-${variant}` 两条 variant 内容。orchestrator 末尾 next-steps 输出多一行,提示用户独立全局装 manage。
+6. `teamix-evo-manage` 自身的 SKILL.md 增加「安装方式」段落,声明 entry skill 语义、推荐 `--scope global`、说明 `skills init` 自动跳过的契约。
+
+## Consequences
+
+- **Positive**:
+  - Lifecycle skill 与 content skill 在 manifest 里有显式语义区分,AI / 工具 / 用户都能机器可读地理解
+  - 用户在任何项目里跑 `npx teamix-evo skills init` 都不会再得到一份多余的 manage 副本
+  - 后续若新增其它 lifecycle skill(例如 `teamix-evo-incident` / `teamix-evo-release`),只需在 manifest 标 `"scope": "global"`,无须改 CLI 代码
+  - schema 字段可选,旧 manifest 无 `scope` 字段时仍按 project 处理 —— 完全向后兼容
+- **Negative**:
+  - 用户首次使用 teamix-evo 时多了一步:在 `npm create teamix-evo` 之前,要独立运行 `skills add teamix-evo-manage --scope global`。文档与 create CLI 的 next-steps 已显式提示,但仍是一次"必须读说明"的额外门槛
+  - 已装项目的存量 `teamix-evo-manage` 副本不会自动清理。文档建议用户手动 `rm -rf .claude/skills/teamix-evo-manage`,我们不写迁移脚本(避免误删用户改过的 SKILL.md)
+- **Trade-off**:
+  - 为了语义清晰与契约机器可读,接受了 manifest schema 多一个可选字段、CLI 多两条分支(`runSkillsInit` 过滤 + `runSkillsAdd` warning)。比方案 B(运行时去重)略复杂,但避免了 B 的隐式行为与状态依赖
+  - verb 命名分工见 [ADR 0034](0034-skills-cli-verb-alignment.md)
+
+## Source
+
+- 用户反馈:「用户使用时会先全局安装 teamix-evo-manage 这个技能,然后使用该技能初始化工程,但是初始化过程中又会在项目级安装本技能,导致用户侧会有两个该技能」
+- 实施 plan:`/Users/lyca/.claude/plans/refactored-roaming-grove.md`

package/dist/data/adr/0034-skills-cli-verb-alignment.md

@@ -0,0 +1,61 @@
+# 0034. skills CLI verb 对齐:`init` 自举 + `add <ids>` 增量
+
+- **Status**: Accepted
+- **Date**: 2026-06-04
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0004 CLI 命令结构](0004-cli-command-structure.md)、[0013 skills source-mirror](0013-skills-source-mirror.md)、[0014 ui-biz-ui-templates 三层](0014-ui-biz-ui-templates-tier.md)、[0033 entry skill global-only scope](0033-entry-skill-global-only-scope.md)
+
+## Context
+
+仓库 CLI 各 group 的动词模型在 0.2.0 之前是统一的(`init` 自举 / `add` 增量),0.2.0 commit 38723ca 把 `skills init` 改名为 `skills add`,理由是"在一个动词下兼容无参与有参两种模式"。这次合并制造了不一致:
+
+| Group    | bootstrap         | 增量装             | 是否一致              |
+| -------- | ----------------- | ------------------ | --------------------- |
+| `tokens` | `init <variant>`  | (无,单 variant)    | ✅                    |
+| `ui`     | `init [-y]`       | `add <id...>`      | ✅                    |
+| `skills` | `add`(无参)       | `add <ids...>`     | ❌ verb 兼任两职      |
+| `biz-ui` | (无,跟 ui config) | `add <id...>`      | ✅                    |
+| `templates` | (无,跟 ui)     | `add <id...>`      | ✅                    |
+
+`add` 在 npm / git / cargo 等业界 CLI 里几乎都需要显式名称(`npm add lodash` / `git add file` / `cargo add serde`),"装一整个集合"通常用 `install` / `init` / `setup`。0.2.0 的合并违背了这个惯例,也让"无参 add 等价 add 全部"成为一个不易发现的隐式规则。
+
+仓库尚未对外发布,无需保留向后兼容。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| A. 保留 0.2.0 现状,文档说明清楚 | 不动代码 | verb 不一致问题留在用户视野;新人易踩坑 |
+| **B. 拆 `skills init`(自举)+ `skills add <ids>`(增量必填)(本决策)** | 与 tokens / ui 横向对齐;符合 npm/git/cargo 惯例;不传 ids 报错 + help 兜底,意图明确 | 与 0.2.0 决策反转,需更新所有文档 / SKILL.md / 测试 |
+| C. 让 `skills add` 不传 ids 时强制 `--all` flag | 比 B 改动小 | "add --all" 仍是一个 verb 兼两职的别扭表达;不解决根本问题 |
+
+## Decision
+
+1. 新增 CLI 子命令 **`teamix-evo skills init`**(无 ids):自举 — 按当前 tokens variant + install scope 装 manifest 里全部符合条件的 skill。已装的项目再跑返回 `'already-initialized'`。
+2. **`teamix-evo skills add <names...>`** 改为 `<names...>` 必填(commander `<>` 强制至少 1 个)。不传 ids → commander 在 [ADR 0033 的 `showHelpAfterError(true)` 兜底下自动报错 + 输出 help](0033-entry-skill-global-only-scope.md)。
+3. Programmatic API:
+   - 新增 `runSkillsInit(opts)` / `RunSkillsInitOptions` / `RunSkillsInitResult`(`'installed' | 'already-initialized'`)
+   - `runSkillsAdd(opts)` 改为 `names: readonly string[]` 必填,空 names 抛错;返回类型不再含 `'already-added'`
+   - 内部抽 `finalizeSkillsInstall()` 共享尾部(写 config / manifest / lock / mcp.json)
+4. 共享底层 `installSkills()` 不变 — 这是 ADR 0013 source-mirror 协议的实现层。
+5. 业务调用点(`runTokensInit` 自动装 variant skill、`create-teamix-evo` orchestrator 装 preset.skills)**已经是 incremental(传入 names)**,继续使用 `runSkillsAdd`,不需迁移。
+6. 文档与 SKILL.md 中"`skills add`"指代 bulk 路径处全部改为 `skills init`;带名引用(`skills add teamix-evo-manage --scope global`)保持不变。
+
+## Consequences
+
+- **Positive**:
+  - skills 与 tokens / ui / biz-ui / templates 五个 group 的 verb 模型横向对齐
+  - 符合 npm / git / cargo 等业界 CLI 惯例,新人理解成本降低
+  - `skills add` 不传 ids 时 commander 自动报错 + 输出 help(ADR 0033 兜底配合),降低误用
+  - Programmatic API 类型更精确(`runSkillsAdd` 的 `names` 不再可选,types 即合约)
+- **Negative**:
+  - 与 0.2.0 时 commit 38723ca 决策反转,需更新所有文档 / SKILL.md / ADR 引用 / 测试
+  - 任何已写下"`skills add`(无参)"的对外材料(如演讲稿、教程、issue 历史)都会过期 —— 但仓库尚未对外发布,影响面在内部
+- **Trade-off**:
+  - 用"两个对外动词"换"verb 模型一致性 + 类型精确"。比 0.2.0 的"一个动词兼两职"略复杂,但用户实际多输入的字符仅是 `init` vs `add`,代价很小
+
+## Source
+
+- 用户反馈(2026-06-04):「tokens 是 init,skills 是 add 是不是不统一?add 应该是需要指定某个技能的,这里是不是不允许 add 后边为空,要根据 variant 指明要安装的多个技能?」
+- 实施 plan:`/Users/lyca/.claude/plans/refactored-roaming-grove.md`
+- 历史决策:`packages/cli/CHANGELOG.md` 0.2.0 (commit 38723ca) — 本 ADR 反转该决策

package/dist/data/adr/0035-skills-update-scope-and-lock-gates.md

@@ -0,0 +1,69 @@
+# 0035. skills update 双闸:`keys(lock) ∩ scope-match` + version 短路
+
+- **Status**: Accepted
+- **Date**: 2026-06-04
+- **Region**: 0100–0999 协议与工具
+- **Related ADR**: [0013 skills source-mirror](0013-skills-source-mirror.md)、[0033 entry skill global-only scope](0033-entry-skill-global-only-scope.md)、[0034 skills CLI verb 对齐](0034-skills-cli-verb-alignment.md)
+
+## Context
+
+`teamix-evo-manage` 是用户主操作点(全局装一份,后续所有研发流程的 AI 入口)。如果其它包(tokens / ui / biz-ui / templates / lint)的升级链尚未完善,只要 manage 自身能可靠升级,manage 就能引导 AI 把整个体系拉齐。
+
+但 0.5.x 之前的 `teamix-evo skills update`(实现在 [packages/cli/src/commands/skills/update.ts](../../packages/cli/src/commands/skills/update.ts) + [skills-installer.ts:333 updateSkills()](../../packages/cli/src/core/skills-installer.ts#L333))有 3 个真 bug + 3 个 UX 缺口:
+
+**Bug**:
+
+1. **scope 闸丢失** — `updateSkills` 只过滤 `ides`,不看 `s.scope`。在全局根跑 update 会把 4 个 project-scope 的 design / code skill 也装到全局;在项目根跑 update 会把 manage(`scope: "global"`,见 ADR 0033)装到项目级 — 与 ADR 0033 决策完全反转。
+2. **lock 闸丢失** — update 不按现存 `lock.skills` 已装清单过滤。manifest 后续若新增第 6 个 skill(例如未来的 `teamix-evo-incident`),所有跑 update 的用户**自动装**它,违背"只刷新已装"的预期。
+3. **lock 写回也是 manifest 全集** — 把根本没装的 skill 也写进 lock,后续 `skills doctor` 报"源缺失/镜像缺失"误报洪水。
+
+**UX 缺口**:
+
+4. version 完全相同时仍重写源 — managed 区域用户改动每次都要走「读 → 合并 → 备份 → 写」一遍,产生噪音
+5. 没有 `<names...>` 限定 — 想只升 manage 一个、不动其它 skill,办不到
+6. 没有 `--dry-run` — 看不到会改什么就要全量执行
+
+**架构副问题**:无 `runSkillsUpdate` core API,逻辑全在 cli command 里 inline,与 ADR 0034 引入的 `runSkillsInit` / `runSkillsAdd` 不对称。
+
+## Options Considered
+
+| 选项 | 优点 | 缺点 |
+| ---- | ---- | ---- |
+| A. 接受现状,文档建议用户清 lock 重装 | 不动代码 | 不可靠;manage 升级链脆弱;主操作点不能崩 |
+| B. 在 update CLI command 内补过滤(单点修复) | 改动小 | 与 init / add 仍不对称;programmatic API 仍残缺 |
+| **C. 抽 `runSkillsUpdate` core API,用三道闸 + version 短路 + dry-run + names(本决策)** | 与 ADR 0034 verb 三件套对齐;types 即合约;`updateSkills` 加 `onlyIds` 不破坏外部约定 | 改动量略大,需要测试覆盖三个闸 × 三个 UX |
+
+## Decision
+
+1. **`runSkillsUpdate` 的升级范围 = `keys(lock.skills) ∩ scope-match ∩ (names if given)`**:
+   - 起点 = 当前 lock 已记录的 skill ids(不再以 manifest 为起点)
+   - 减去 `(s.scope ?? 'project') !== currentInstallScope` 的(scope 闸,与 ADR 0033 在 init 中的过滤对齐)
+   - 与命令行传入的 `[names...]` 取交集(若有)
+   - = 真要更新的 `targetIds`
+2. **version 完全一致时短路**:`targetIds` 中所有 id 的 `lock.skills[id].version === manifest.skills[id].version` → 返回 `'no-changes'`,不写盘。
+3. **新 skill 不能被 update 自动引入**,只通过 `skills add <id>` 显式装。
+4. **`updateSkills` 接受可选 `onlyIds: string[]`**,与 `SkillSyncOptions.onlyIds` 类型对齐;不传保持旧行为(向后兼容,不破坏 `core` 子路径外部约定)。
+5. **lock 写回只触碰 `targetIds`**;未升级的条目原样保留。`installedManifest.installed[skills].resources` 同理 — 保留未触碰的 resource records。
+6. **CLI 表面**:`teamix-evo skills update [names...] [--dry-run]`。命令头打印 `teamix-evo CLI v0.x.y · skills package v0.a.b`,便于排查 CLI 与包版本是否同步。
+7. **新增 core API**:`runSkillsUpdate` / `RunSkillsUpdateOptions` / `RunSkillsUpdateResult` / `UpdatePlanItem`,与 `runSkillsInit` / `runSkillsAdd` 三件套对齐(ADR 0034)。
+
+## Consequences
+
+- **Positive**:
+  - manage(主操作点)的全局升级路径可靠 — 不会装错 scope,不会引入未装 skill
+  - 版本未变时短路,managed 区域用户改动不再被来回备份
+  - `--dry-run` 让用户能预检,降低升级心智负担
+  - `[names...]` 让 manage 自身能精确升级而不动其它 skill
+  - CLI banner 让"哪个版本在跑"可见,排查 npx cache / 包不同步的问题更容易
+  - programmatic API 三件套对齐,types 即合约
+- **Negative**:
+  - 用户原本期望"update 一并把新 skill 装上"会落空 — 但这本就是 `add` 的职责,文档已对齐
+  - `updateSkills` 的 `onlyIds` 参数让函数签名更长一点;不传时旧行为不变,影响面在内部
+- **Trade-off**:
+  - 用三道闸 + 一个新 core API 的复杂度,换 manage 升级链路的可靠性。manage 是用户主操作点,这个权衡明显值得
+
+## Source
+
+- 用户反馈(2026-06-04):「帮我关注下 teamix-evo-manage 安装后的升级吧。因为后续其他包的升级可能还没怎么完善,teamix-evo-manage 是用户主操作点,我如果可以更新 teamix-evo-manage,那就能保证后所有研发迭代都能处理」
+- 实施 plan:`/Users/lyca/.claude/plans/refactored-roaming-grove.md`
+- 测试覆盖:`packages/cli/src/__tests__/skills-update.test.ts`(Bug 1/2/3 + UX 4/5/6 + 3 个 edge case,共 10 个 it)

package/dist/data/adr/README.md

@@ -0,0 +1,75 @@
+# 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 |
+| 0021 | [语义色 API 统一治理(`tone`/`status`/`variant` 三分 + 字面值对齐 token)](0021-semantic-color-api-unification.md)           | Accepted                   | 2026-05-29 |
+| 0022 | [preferences.css 边界约束(仅装机偏好,禁止组件级 utility / token alias)](0022-preferences-css-boundary.md)                  | Accepted                   | 2026-05-31 |
+| 0029 | [Input 拆分 + 移除 prefix/suffix/addon 快捷 prop + AutoComplete 内核同源化](0029-input-split-and-prefix-suffix-removal.md) | Accepted                   | 2026-06-02 |
+| 0030 | [uni-manager 变体 design + code skill 落地 + 通用规则反哺 opentrek](0030-skill-uni-manager-uplift.md)                      | Accepted                   | 2026-06-02 |
+| 0031 | [AI Skill 链路解耦 `@teamix-evo/templates` 包（patterns/ 单一默认来源）](0031-skill-templates-decoupling.md)               | Accepted                   | 2026-06-02 |
+
+## 写新 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 };