teamix-evo (CLI)

Teamix Evo 命令行入口 — 管理设计体系资源的安装、更新和查询。

定位

CLI 是 Teamix Evo 的执行层，用户通过 npx teamix-evo 或全局安装后使用。核心职责：

• 从 npm 包加载 variant manifest 和模板数据
• 使用 Handlebars 渲染模板为目标文件
• 根据 updateStrategy（frozen / regenerable / managed）决定文件更新方式
• 维护 .teamix-evo/ 下的配置和状态文件

目录结构

packages/cli/
├── src/
│   ├── index.ts                    # 入口:Commander 注册
│   ├── commands/
│   │   ├── tokens/                 # tokens init <variant> / list / list-variants
│   │   │   │                       # / update(stub) / uninstall
│   │   ├── skills/                 # npm-source direct-mirror 模型见 ADR 0048
│   │   │   │                       # add / list / update / sync / doctor / uninstall
│   │   └── ui/                     # init / add / list
│   ├── core/                       # 业务编排层(programmatic API,subpath 导出)
│   │   ├── tokens-init.ts          # 变体自包含装机(ADR 0020)
│   │   ├── installer.ts            # UI 资源安装引擎
│   │   ├── updater.ts              # 三策略更新引擎(frozen/regenerable/managed)
│   │   ├── ui-{add,init,list,client,installer}.ts
│   │   ├── skills-{add,client,installer,sync,doctor}.ts
│   │   ├── registry-client.ts      # 从 npm 包解析 variant
│   │   └── state.ts                # .teamix-evo/ 状态读写
│   ├── ide/
│   │   ├── IdeAdapter.ts           # IDE 适配接口
│   │   ├── QoderAdapter.ts         # Qoder 适配
│   │   ├── ClaudeAdapter.ts        # Claude Code 适配
│   │   ├── CodexAdapter.ts         # Codex / ChatGPT 适配（.agents/skills）
│   │   └── index.ts                # detectIde / ALL_IDE_KINDS
│   ├── utils/
│   │   ├── fs.ts                   # 原子写入、备份
│   │   ├── hash.ts                 # SHA-256
│   │   ├── logger.ts               # 分级彩色日志
│   │   ├── path.ts                 # 路径解析、目录遍历
│   │   ├── template.ts             # Handlebars 渲染(带缓存)
│   │   ├── transform-imports.ts    # 假路径 @/ → 用户 alias
│   │   └── global-root.ts          # ~/.teamix-evo-global 解析(scope=global 用)
│   └── __tests__/                  # 10 份单测,见下方测试章节
├── tsup.config.ts                  # 构建配置(双入口:bin + core subpath)
├── tsconfig.json
└── package.json

研发流程

1. 环境准备

# 在仓库根目录
pnpm install

# 需要先构建依赖包
pnpm --filter @teamix-evo/registry build

2. 开发

# 监听模式构建
pnpm --filter teamix-evo dev

构建产物双入口（见 tsup.config.ts）：

• dist/index.js — CLI bin（ESM，带 #!/usr/bin/env node banner，对应 package.json#bin）
• dist/core/index.{js,d.ts} — programmatic API（ESM + 类型，对应 teamix-evo/core subpath 导出，不带 banner）

3. 新增命令

1. 在 src/commands/<group>/ 下新建命令文件
2. 使用 Commander 的 Command 类定义命令
3. 在对应 group 的 index.ts 中注册（addCommand）
4. 如果是新的命令组，在 src/index.ts 中注册

示例模式：

import { Command } from 'commander';
import { detectIde } from '../../ide/index.js';
import { logger } from '../../utils/logger.js';

export const myCommand = new Command('my-cmd')
  .description('命令描述')
  .action(async () => {
    try {
      const ide = detectIde();
      const projectRoot = ide.getProjectRoot();
      // ... 业务逻辑
      logger.success('完成');
    } catch (err) {
      logger.error(`Failed: ${(err as Error).message}`);
      process.exitCode = 1;
    }
  });

4. 修改核心引擎

• core/installer.ts — 资源首次安装逻辑
• core/updater.ts — 资源更新逻辑（处理三种策略 + managed regions）
• core/registry-client.ts — 从 node_modules 解析 variant 包路径
• core/state.ts — .teamix-evo/config.json 和 manifest.json 的读写

5. IDE 适配

当前支持 Qoder、Claude Code 与 Codex / ChatGPT(QoderAdapter / ClaudeAdapter / CodexAdapter),detectIde() 自动判断。扩展新 IDE:

1. 在 src/ide/ 下新建 XxxAdapter.ts,实现 IdeAdapter 接口
2. 在 src/ide/index.ts 的 detectIde() 中添加检测逻辑
3. 在 ALL_IDE_KINDS 与 SkillIde 类型中加上新 IDE 名

6. 测试

# 运行全部测试
pnpm --filter teamix-evo test

# 监听模式
pnpm --filter teamix-evo test:watch

测试文件位于 src/__tests__/,覆盖:

• core-api.test.ts — programmatic core API(runTokensInit / runSkillsAdd / runUiAdd)
• tokens-init-skills-link.test.ts — tokens init ↔ skills auto-install 联动
• installer.test.ts — UI 资源安装(frozen / regenerable)
• ui-installer.test.ts — UI 装机引擎(依赖图 / alias 转换)
• skills-installer.test.ts — skills 从 npm 包渲染到 IDE mirror
• skills-sync-doctor.test.ts — IDE mirror 缺失 / 漂移检测
• updater.test.ts — 三策略更新逻辑(ADR 0003)
• state.test.ts — .teamix-evo/ 状态读写
• template.test.ts — Handlebars 渲染
• transform-imports.test.ts — 假路径(@/)→ 用户 alias 转换

7. 类型检查 & 构建

pnpm --filter teamix-evo typecheck
pnpm --filter teamix-evo build

8. 本地调试

# 构建后在任意目录执行
node /path/to/packages/cli/dist/index.js tokens init opentrek

# 或通过 pnpm 链接
cd packages/cli && pnpm link --global
teamix-evo tokens init opentrek

开启调试日志：

TEAMIX_DEBUG=1 teamix-evo tokens init opentrek

命令参考

| 命令 | 说明 | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | teamix-evo init [-y] [--dry-run] [--variant <n>] | 普通版接入：检测冲突 → wizard → 静默落地 → 自动提交，并校验默认 Git 工作区干净 | | teamix-evo update [--dry-run] [--cwd <dir>] | 一键升级已装资源（tokens + skills，ADR 0003 三态 + ADR 0035 短路） | | teamix-evo migrate [--cwd <dir>] [--json] | shadcn 项目迁移前置检查（AI skill 引导实际迁移） | | teamix-evo graft [--variant <v>] [--json] [--cwd <dir>] | 叠加 Teamix Evo 到传统组件库项目（双栈共存，ADR 0047） | | teamix-evo restore [ts] [--list] [-y] | 回滚 .teamix-evo/ 到指定 snapshot（ADR 0019 §2 — 自身可逆） | | teamix-evo switch <new-variant> [--apply] [-y] | variant 切换：默认 dry-run 展示 file-level diff，--apply 才真写（ADR 0019 §D3） | | teamix-evo tokens init <variant> | 初始化 tokens | | teamix-evo tokens list-variants | 列出可用 variant | | teamix-evo tokens list | 查看已装机的 variant | | teamix-evo tokens update | 更新已装资源(stub,v0.7 见 ADR 0019) | | teamix-evo tokens uninstall | 卸载已装 tokens | | teamix-evo tokens audit | 审计 tokens 引用（4 类：redundant / kept / migrate / custom，v3↔v4 语义比较） | | teamix-evo tokens diagnose | 诊断 tokens 使用情况，生成分级报告（L1-L3）+ .treatment-plan.md | | teamix-evo tokens treat [--lock-baseline] [--apply] | 一键 token 治理流水线：lint → codemod → lint → 报告 → 可选锁定 baseline | | teamix-evo tokens codemod [name] [--apply] [--list] | 执行指定 token codemod（5 个可用：hsl-to-v4 / hex-to-token / tw-scale-to-semantic / space-to-gap / arbitrary-to-token） | | teamix-evo tokens reflect [--min-frequency <n>] | 扫描重复色值，推荐新增项目级 token（反哺 overrides.css） | | teamix-evo tokens baseline-check | 对比 baseline 检查 token 违规是否超标（CI 友好，exitCode=1 on fail） | | teamix-evo skills init | 自举 skills(按 variant + scope 全装 — ADR 0034) | | teamix-evo skills add <name...> | 增量装指定 skill(<name...> 必填) | | teamix-evo skills list | 列出所有 skill 的安装状态 | | teamix-evo skills update [name...] [--dry-run] | 升级 skills(双闸 + version 短路 — ADR 0035) | | teamix-evo skills sync [name...] | npm 包 → IDE 镜像(漂移恢复；--ide 持久重配全部 skill) | | teamix-evo skills doctor | 检测 IDE 镜像缺失 / 漂移(ADR 0048) | | teamix-evo skills uninstall | 卸载已知 IDE 镜像 + lock 记录 | | teamix-evo ui init | 初始化 ui 配置(aliases / iconLibrary / tsx / rsc) | | teamix-evo ui add <id...> | 安装指定 ui 组件源码 | | teamix-evo ui list [--installed] | 列出可用/已安装 ui 组件 | | teamix-evo ui promote-to-biz <id...> | 把 ui 组件提升为业务组件（8 模式：Coexist/Preset/Wrapper/Compose/Variant/Fork/TokenOnly/ManualReview） | | teamix-evo biz-ui list-variants | 列出 biz-ui 包内提供的业务变体 | | teamix-evo biz-ui add <id...> --variant <name> | 安装变体感知业务组件(--variant 必填) | | teamix-evo blocks add <id...> | 安装营销页区块（保留目录结构） | | teamix-evo blocks list [--installed] [--json] | 列出可用/已安装区块 | | teamix-evo blocks upgrade [<id...>] | 升级已安装的区块源码 | | teamix-evo lint init [-y] | 一键安装 ESLint + Stylelint token-discipline 规则集 |

占位组件 → 真组件的升级流程不是 CLI 子命令，由 teamix-evo-manage skill 在 IDE 内驱动「场景 6」,底层仍调用 teamix-evo ui add。

全局装 skill(--scope global)

skills init 与 skills add 都支持 --scope global 装到 IDE 全局(~/.qoder/skills/ + ~/.claude/skills/ + ~/.agents/skills/)。当 cwd 不是 Teamix Evo 项目时,工具会自动把元数据写到 ~/.teamix-evo-global/,不污染当前目录。

# Onboarding 推荐:全局装 manage skill
npx teamix-evo@latest skills add teamix-evo-manage --scope global --ide qoder,claude,codex -y

# 后续维护(update / uninstall 等)需 cd 到全局元数据根
cd ~/.teamix-evo-global && npx teamix-evo skills update

已有项目新增 Codex mirror（同时持久更新 config + lock）：

npx teamix-evo@latest skills sync --ide qoder,claude,codex

关键约定

• 使用 process.exitCode = 1 而非 process.exit(1)，确保异步操作完成
• 文件写入使用 writeFileSafe（tmp + rename 原子写入）
• 更新前自动备份到 .teamix-evo/.backups/
• 版本号从 package.json 动态读取，不硬编码

依赖关系

本包 → @teamix-evo/registry（协议层）
本包 → @teamix-evo/tokens（设计 tokens，运行时解析）
本包 → @teamix-evo/skills（技能资源，运行时解析）
本包 → @teamix-evo/ui（UI 资源，manifest + 源码）