teamix-evo (CLI)

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

定位

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

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

关键生命周期契约

• fresh init 在写入 CLI-owned pending 后建立 0-commit .git/，再完成 scaffold、suite 资源生成、唯一一次依赖安装与 typecheck/lint/lint:css/build；全部成功后创建唯一 chore: init teamix-evo 提交。产品硬性验收是首次建仓只有这一条完整初始化提交。
• --no-git 仍执行安装和四项验证；--no-install 必须同时使用 --no-git，结果是 “已生成但未验证”，不会建立仓库。
• CLI 为 fresh scaffold 写入受 .gitignore 管理的 .teamix-evo/.init-pending.json，记录 variant、IDE、Git 与 package manager；失败重跑无需再传 --variant，且会复用原始输入恢复完整验证与 Git 策略。默认 Git 路径可保留无 HEAD 的 .git/，已有提交则 fail-closed。普通已有 Teamix Evo 工程会由 init 只读短路，不修改文件；升级使用 teamix-evo update。.teamix-evo/meta/{ui,biz-ui,project-ui}/ 都进入 Git，clone 后可离线查询。
• 消费工程 token 唯一布局是 src/tokens/。旧根布局只能通过默认 dry-run 的 tokens repair-layout 事务化修复；正常 tokens/skills/UI/Biz-UI/staging 升级入口 fail closed，不做双路径 fallback。

npx teamix-evo@latest tokens repair-layout
npx teamix-evo@latest tokens repair-layout --apply -y
npx teamix-evo@latest tokens repair-layout --restore <transaction-id>

目录结构

packages/cli/
├── src/
│   ├── index.ts                    # 入口:Commander 注册
│   ├── commands/
│   │   ├── tokens/                 # init / list / update / repair-layout / uninstall / 治理命令
│   │   ├── skills/                 # npm-source direct-mirror 模型见 ADR 0048
│   │   │   │                       # add / list / update / sync / doctor / uninstall
│   │   ├── ui/                     # init / add / list / update
│   │   └── staging/                # reviewed decisions apply / restore
│   ├── 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>] [--no-git] [--no-install] | fresh 工程：生成 → 一次安装 → 四项验证 → 最终唯一提交；partial 仅凭 CLI-owned pending 恢复；--no-install 必须配合 --no-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>] | 暂不支持：仅保留实验实现，不得作为可用能力推荐或执行；ADR 0047 仍为 Proposed | | teamix-evo restore | Deprecated compatibility stub：能力已移除；失败恢复使用 Git | | teamix-evo switch | Deprecated compatibility stub：能力已移除；当前没有现役 variant 切换 CLI | | 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 repair-layout [--apply -y] [--restore <transaction-id>] | 默认 dry-run；把旧根布局事务化修复为唯一 src/tokens/；自动回滚失败时用事务 ID 显式恢复 | | 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 文件 | | 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 短路；显式 name 可更新 lock 中同 scope override — ADR 0035/0059) | | teamix-evo skills sync [name...] | npm 包 → IDE 镜像；恢复漂移并清理 manifest 记录的过期文件，保留未知文件；--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 entry 的全部 files[]；每个文件独立 frozen | | teamix-evo ui list [--installed] | 列出可用/已安装 ui 组件 | | teamix-evo ui update [id...] | 展开传递依赖并生成 schema v3 staging；同版本无变化跳过、同版本内容漂移 fail-closed；generator 不写组件源码 | | 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 biz-ui list --project [--json] | 列出消费工程显式注册的 Project UI 组件（与 list --variant 互斥） | | teamix-evo biz-ui register <source> [options] | 静态分析工程内 .ts/.tsx，生成或刷新 .teamix-evo/meta/project-ui/ | | teamix-evo biz-ui unregister <id> [--json] | 取消 Project UI 注册并删除生成 metadata，不删除源码 | | teamix-evo biz-ui doctor --project [--json] | 只读检查 manifest、metadata、源码、依赖、Git ignore/可提交性与写锁 | | teamix-evo biz-ui update [id...] | 跨 Biz-UI/UI 展开依赖并生成 schema v3 staging；同版本无变化跳过、内容或闭包漂移 fail-closed；generator 不写组件源码 | | teamix-evo staging apply --staging <dir> --decisions <file> [--dry-run] | 校验并应用一个已审核 decisions v1；验证后更新 ledger 并归档，失败恢复已知文件 | | teamix-evo staging apply --staging <dir> --restore | 显式恢复该 staging 的 pending / restore-failed transaction | | teamix-evo blocks add <id...> | 不活跃兼容占位；返回无可安装内容，不读写消费工程 | | teamix-evo blocks list [--installed] [--json] | 不活跃兼容占位；返回空 catalog，并报告既有 frozen Block 数量 | | teamix-evo lint init [-y] | 一键安装 ESLint + Stylelint token-discipline 规则集 |

新建工程默认初始化为 main 分支；完整首次初始化仅产生一条 chore: init teamix-evo 提交，不保留脚手架中间提交。

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

UI / Biz-UI 多文件生命周期

• registry entry 可以把 TSX、附属 JSON 和共享 util 作为同一 files[] 安装；
• 文件账本身份为 (entryId, targetAlias, normalizedTargetName)；旧 ${entryId}:${targetName} 记录仍可读，并在下一次成功写账本时安全迁移； 如果同一 entry 在不同 alias 使用相同 targetName，旧记录因无法唯一解析会原样 保留并要求人工确认；
• nested targetName 始终限制在对应 alias 根内，禁止 ../ 逃逸；
• 任一上游文件缺失或依赖预检失败时，本次 entry 不写入任何文件；
• 含 JSON catalog 的 entry 要求消费工程的有效 TypeScript 配置启用 compilerOptions.resolveJsonModule=true，否则在写入前给出修复提示；
• upgrade writer 只生成 dependency-aware staging schema v3；reader 仍接受历史 v1/v2；
• update [id...] 的 ids 只选择已安装 roots，当前 manifest 的传递 registryDependencies 自动进入 dependency-first closure；旧 reader 遇到 v3 必须 fail-closed，不能只应用 root；
• JSON catalog 的升级由 manage skill 按 language/key/placeholder 语义合并，不默认 整文件覆盖；合并结果保存为 staging artifact，review 结果保存为 decisions v1；
• staging apply 只支持单个 schema v3 staging，dry-run 零写入；真实 apply 使用项目级锁、 transaction backup/tombstone、验证 script 和后验 hash/owner/schema 校验，统一 upsert/remove 对应 file resource，避免下一次升级重复报告；
• 中断事务只允许显式 restore 后从头重跑，不提供任意阶段 resume；验证脚本的 cache、 build 目录和外部副作用不在自动恢复范围内。

Project UI：消费工程组件发现目录

业务项目可以把已稳定、跨页面复用的自定义业务组件注册给 Design / Code Skill：

npx teamix-evo@latest biz-ui register src/components/business/profile-card.tsx
npx teamix-evo@latest biz-ui list --project
npx teamix-evo@latest biz-ui doctor --project
npx teamix-evo@latest biz-ui unregister profile-card

主导出必须有 description 和至少一个 @when TSDoc；多导出文件使用 --export <name>，多个 tsconfig alias 命中时使用 --import-path <path>。 其他选项：--id、--status experimental|stable|deprecated、 --deprecated-reason、--replaced-by、--json；其中 --deprecated-reason、--replaced-by 只适用于 deprecated 状态。

输出目录固定为 .teamix-evo/meta/project-ui/{manifest.json,<id>.md}。 它不复用上游 .teamix-evo/meta/biz-ui/manifest.json，不写根安装账本， 不进入 snapshot；源码/TSDoc 是 authoring truth，目录需随源码提交 Git。

全局装 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 + 源码）