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/
│   │   ├── design/
│   │   │   ├── index.ts            # design 命令组
│   │   │   ├── init.ts             # design init [variant]
│   │   │   ├── update.ts           # design update
│   │   │   └── list.ts             # design list
│   │   ├── skills/
│   │   │   ├── index.ts            # skills 命令组
│   │   │   ├── add.ts              # skills add [name...]
│   │   │   ├── list.ts             # skills list
│   │   │   ├── update.ts           # skills update
│   │   │   └── uninstall.ts        # skills uninstall
│   │   └── ui/
│   │       ├── index.ts            # ui 命令组
│   │       ├── init.ts             # ui init
│   │       ├── add.ts              # ui add <id...>
│   │       └── list.ts             # ui list
│   ├── core/
│   │   ├── installer.ts            # 资源安装引擎
│   │   ├── updater.ts              # 资源更新引擎（三策略处理）
│   │   ├── registry-client.ts      # 从 npm 包解析 variant
│   │   └── state.ts                # .teamix-evo/ 状态读写
│   ├── ide/
│   │   ├── IdeAdapter.ts           # IDE 适配接口
│   │   ├── QoderAdapter.ts         # Qoder 适配实现
│   │   └── index.ts                # IDE 检测入口
│   ├── utils/
│   │   ├── fs.ts                   # 原子写入、备份、文件操作
│   │   ├── hash.ts                 # SHA-256 哈希
│   │   ├── logger.ts               # 分级彩色日志
│   │   ├── path.ts                 # 路径解析、目录遍历
│   │   └── template.ts             # Handlebars 渲染（带缓存）
│   └── __tests__/                  # 单元测试
├── tsup.config.ts                  # 构建配置（单文件 ESM + shebang）
├── tsconfig.json
└── package.json

研发流程

1. 环境准备

# 在仓库根目录
pnpm install

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

2. 开发

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

构建产物为单文件 dist/index.js（ESM，带 #!/usr/bin/env node 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 适配

当前 MVP 仅支持 Qoder。扩展新 IDE：

1. 在 src/ide/ 下新建 XxxAdapter.ts，实现 IdeAdapter 接口
2. 在 src/ide/index.ts 的 detectIde() 中添加检测逻辑

6. 测试

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

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

测试文件位于 src/__tests__/，覆盖：

• installer.test.ts — 资源安装（plain / template / recursive）
• updater.test.ts — 三种策略更新逻辑
• state.test.ts — 配置文件读写
• template.test.ts — Handlebars 渲染

7. 类型检查 & 构建

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

8. 本地调试

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

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

开启调试日志：

TEAMIX_DEBUG=1 teamix-evo design init opentrek

命令参考

| 命令 | 说明 | | ---------------------------------- | ------------------------------- | | teamix-evo design init [variant] | 初始化设计体系（默认 opentrek） | | teamix-evo design update | 更新已安装的设计资源 | | teamix-evo design list | 查看已安装信息 | | teamix-evo skills add [name...] | 装入 skills（全量/增量） | | teamix-evo skills list | 列出所有 skill 的安装状态 | | teamix-evo skills update | 升级已安装 skills | | teamix-evo skills uninstall | 卸载 skills | | teamix-evo ui init | 初始化 ui 组件环境 | | teamix-evo ui add <id...> | 安装指定 ui 组件源码 | | teamix-evo ui list | 列出可用/已安装 ui 组件 |

选项：

• --tailwind <v3|v4> — 指定 Tailwind CSS 版本（默认 v3）

关键约定

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

依赖关系

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