@teamix-evo/mcp 0.4.0 → 0.4.3

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

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

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/0036-ui-v2-shadcn-baseline-rebuild.md

@@ -0,0 +1,146 @@
+# 0036. UI 组件库 v2：以 shadcn v4 为基线全量重建
+
+- **Status**: Accepted
+- **Date**: 2026-06-05
+- **Region**: 0001–0099 工程哲学
+- **Related ADR**: Supersedes 0001, 0005, 0006, 0010, 0025, 0026, 0027, 0028, 0029
+
+## Context
+
+`@teamix-evo/ui` v1 从 shadcn v3 出发，叠加 antd 能力并集，积累了 87+ 组件。过程中出现以下问题：
+
+1. **双对标负担**：每个组件都要做"shadcn ∪ antd 并集"，决策成本高、更新难跟进
+2. **旧 shadcn 架构绑定**：forwardRef、`@layer base` border 兜底、hsl 色值等 v3 模式已过时
+3. **Token 分层不清**：全局 token 与组件级行为覆盖混在一个 theme.css 里（uni-manager 544 行）
+4. **文档多源漂移**：meta.md 手写、Storybook 描述手写、TSDoc 各写各的，三处信息不同步
+5. **能力增强方向模糊**：antd 为锚点导致"追赶 antd"而非"面向业务场景"
+
+同时，shadcn 已演进到 v4（radix-nova style、React 19 patterns、data-slot、oklch、Tailwind v4 @theme），架构显著优于 v3。
+
+## Decision
+
+### D1. 全量废弃 v1 组件源码，以 shadcn v4 (radix-nova) 为基线重建
+
+- 现有 `packages/ui/src/` 内容备份到 `packages/ui/src-v1-archive/`
+- 从 shadcn v4 最新版初始化全部基线组件
+- 超出 shadcn 的组件按 shadcn 工程风格自研
+
+### D2. Token 架构：`theme.css` + `overrides.css` 两文件制
+
+每个变体目录结构：
+
+```
+packages/tokens/variants/{variant}/
+  ├── theme.css           ← @theme token 声明（Tailwind v4 消费）
+  └── overrides.css       ← 变体组件行为覆盖（[data-theme] scoped CSS）
+```
+
+- `base.tokens.json` 删除（原为 AI 生成辅助文件，非运行时依赖）
+- `theme.css` 为全局 token 声明唯一源
+- `overrides.css` 处理跨变体的组件级行为差异（focus 机制、button shadow、dialog padding 等）
+
+### D3. `data-theme` 属性双变体统一声明
+
+所有消费方项目必须在 `<html>` 上声明 `data-theme`：
+
+```html
+<html data-theme="opentrek">
+  <!-- 或 "uni-manager" -->
+</html>
+```
+
+- 脚手架自动写入
+- `ui init` CLI 输出提示（AI coding 场景由 AI 添加）
+- 即使 opentrek 的 `overrides.css` 为空也要声明，防御未来升级
+
+### D4. 能力增强不再对齐 antd，由用户定义目标
+
+- 废弃"shadcn ∪ antd 并集"策略（旧 ADR 0001）
+- 组件能力需求由用户逐组件提供，以业务场景为导向
+- shadcn 组件作为基线，增强能力按 shadcn 工程风格实现
+
+### D5. TSDoc 为唯一文档手写源
+
+信息流：
+
+```
+TSDoc (唯一手写源)
+  ├──→ Storybook autodocs plugin  → 组件名、描述、何时使用、API 表
+  ├──→ gen:meta 脚本              → meta.md（自动生成，CI 守门）
+  └──→ MCP server                 → 读 meta.md 或直接 parse TSDoc
+```
+
+TSDoc 自定义标签：
+
+- `@when` — 何时使用（列表形式）
+- 首段 — 组件中文名 + 描述
+
+开发者只手写两个文件：
+
+1. `<id>.tsx`（含 TSDoc + Props interface JSDoc）
+2. `<id>.stories.tsx`（仅代码演示 Stories）
+
+### D6. Storybook 页面结构
+
+每个组件的 autodocs 页包含：
+
+1. **组件名 + 中文名**（`meta.title`）
+2. **描述**（从 TSDoc 首段提取）
+3. **何时使用**（从 TSDoc `@when` 提取）
+4. **代码演示**（手写 Stories）
+5. **API Props 表**（autodocs 从 TypeScript interface + JSDoc 自动生成）
+
+### D7. shadcn v4 工程模式对齐
+
+| 特性                               | 采用                    |
+| ---------------------------------- | ----------------------- |
+| `data-slot` 属性系统               | ✅ 所有组件标记         |
+| React 19 函数组件（无 forwardRef） | ✅ 默认不加，按需后补   |
+| cva（class-variance-authority）    | ✅ 有枚举 prop 的组件用 |
+| Tailwind v4 `@theme inline`        | ✅                      |
+| oklch 或 hex 色值                  | 按用户新 token design   |
+| `radix-ui` 单包导入                | ✅                      |
+| lucide-react 图标                  | ✅                      |
+| `cn()` = clsx + tailwind-merge     | ✅                      |
+
+### D8. React 18 兼容
+
+- 默认使用 shadcn v4 写法（无 forwardRef）
+- React 18 下 ref 不会转发，绝大多数场景无影响
+- 极少数需要 ref 的组件后续按需单独加 forwardRef
+
+### D9. 旧 ADR 归档
+
+以下 ADR 标记为 `Superseded by 0036`：
+
+| ADR  | 原决策                     | 被取代原因                        |
+| ---- | -------------------------- | --------------------------------- |
+| 0001 | 三层对齐（能力/理念/工程） | 不再做 antd 并集                  |
+| 0005 | UI 包不分 variant          | 现在用 data-theme + overrides.css |
+| 0006 | UI 升级机制无 baseline     | 全量重建，旧升级策略不适用        |
+| 0010 | design 默认+变体模型       | 纯变体，无 default 基线           |
+| 0025 | Props 显式声明规范         | TSDoc 新范式取代                  |
+| 0026 | 组件级 token alias         | overrides.css 取代组件内 token    |
+| 0027 | 组件视觉 token 对齐        | 全量重建，旧对齐规则不适用        |
+| 0028 | UI 组件分类                | 新组件清单由用户定义              |
+| 0029 | Input 拆分                 | 全量重建，旧拆分决策不适用        |
+
+## Consequences
+
+- **Positive**:
+  - 与 shadcn 社区完全同步，享受生态红利
+  - Token 分层清晰，新增变体仅需两个 CSS 文件
+  - 文档单源（TSDoc），消除多源漂移
+  - 组件源码精简（shadcn v4 比 v1 并集代码少 60%+）
+  - AI 生成/理解成本大幅降低（标准 shadcn 模式）
+- **Negative**:
+  - 需要全量重写所有组件（一次性大投入）
+  - 旧版本消费方无法平滑升级（breaking change）
+  - 放弃 antd 并集意味着部分能力需用户显式提需求
+- **Trade-off**:
+  - 用"一次性重建成本"换"长期维护效率 + AI 友好度"
+  - 用"用户主动提需求"换"不再盲目追赶 antd"
+
+## Source
+
+2026-06-05 架构分析讨论。基于对 shadcn v4 (radix-nova, shadcn@4.10.0) 源码的深度分析，对比现有 v1 架构的 7 个痛点，做出全量重建决策。