teamix-evo 0.2.0 → 0.3.1

package/README.md

@@ -16,41 +16,37 @@ CLI 是 Teamix Evo 的**执行层**，用户通过 `npx teamix-evo` 或全局安
 ```
 packages/cli/
 ├── src/
-│   ├── index.ts                    # 入口：Commander 注册
+│   ├── 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              # 资源更新引擎（三策略处理）
+│   │   ├── design/                 # design init <variant> / list / list-variants
+│   │   │   │                       # / update(stub) / uninstall
+│   │   ├── skills/                 # source-mirror 模型见 ADR 0013
+│   │   │   │                       # add / list / update / sync / doctor / uninstall
+│   │   └── ui/                     # init / add / list
+│   ├── core/                       # 业务编排层(programmatic API,subpath 导出)
+│   │   ├── design-init.ts          # walk-and-merge 装机
+│   │   ├── design-pack-classify.ts # 路径分类(W1.4 tokens 提层)
+│   │   ├── 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 适配实现
-│   │   └── index.ts                # IDE 检测入口
+│   │   ├── QoderAdapter.ts         # Qoder 适配
+│   │   ├── ClaudeAdapter.ts        # Claude Code 适配
+│   │   └── index.ts                # detectIde / ALL_IDE_KINDS
 │   ├── utils/
-│   │   ├── fs.ts                   # 原子写入、备份、文件操作
-│   │   ├── hash.ts                 # SHA-256 哈希
+│   │   ├── fs.ts                   # 原子写入、备份
+│   │   ├── hash.ts                 # SHA-256
 │   │   ├── logger.ts               # 分级彩色日志
 │   │   ├── path.ts                 # 路径解析、目录遍历
-│   │   └── template.ts             # Handlebars 渲染（带缓存）
-│   └── __tests__/                  # 单元测试
-├── tsup.config.ts                  # 构建配置（单文件 ESM + shebang）
+│   │   ├── 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
 ```
@@ -74,7 +70,10 @@ pnpm --filter @teamix-evo/registry build
 pnpm --filter teamix-evo dev
 ```
 
-构建产物为单文件 `dist/index.js`（ESM，带 `#!/usr/bin/env node` banner）。
+构建产物双入口（见 `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. 新增命令
 
@@ -114,10 +113,11 @@ export const myCommand = new Command('my-cmd')
 
 ### 5. IDE 适配
 
-当前 MVP 仅支持 Qoder。扩展新 IDE：
+当前支持 Qoder 与 Claude Code(`QoderAdapter` / `ClaudeAdapter`),`detectIde()` 自动判断。扩展新 IDE:
 
-1. 在 `src/ide/` 下新建 `XxxAdapter.ts`，实现 `IdeAdapter` 接口
+1. 在 `src/ide/` 下新建 `XxxAdapter.ts`,实现 `IdeAdapter` 接口
 2. 在 `src/ide/index.ts` 的 `detectIde()` 中添加检测逻辑
+3. 在 `ALL_IDE_KINDS` 与 `SkillIde` 类型中加上新 IDE 名
 
 ### 6. 测试
 
@@ -129,12 +129,18 @@ pnpm --filter teamix-evo test
 pnpm --filter teamix-evo test:watch
 ```
 
-测试文件位于 `src/__tests__/`，覆盖：
+测试文件位于 `src/__tests__/`,覆盖:
 
-- `installer.test.ts` — 资源安装（plain / template / recursive）
-- `updater.test.ts` — 三种策略更新逻辑
-- `state.test.ts` — 配置文件读写
+- `core-api.test.ts` — programmatic core API(runDesignInit / runSkillsAdd / runUiAdd)
+- `design-init-skills-link.test.ts` — design init ↔ skills auto-install 联动
+- `installer.test.ts` — UI 资源安装(frozen / regenerable)
+- `ui-installer.test.ts` — UI 装机引擎(依赖图 / alias 转换)
+- `skills-installer.test.ts` — skills 装机(source-mirror)
+- `skills-sync-doctor.test.ts` — source ↔ mirror 漂移检测
+- `updater.test.ts` — 三策略更新逻辑(ADR 0003)
+- `state.test.ts` — `.teamix-evo/` 状态读写
 - `template.test.ts` — Handlebars 渲染
+- `transform-imports.test.ts` — 假路径(@/)→ 用户 alias 转换
 
 ### 7. 类型检查 & 构建
 
@@ -162,22 +168,42 @@ 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）
+| 命令                                                | 说明                                              |
+| --------------------------------------------------- | ------------------------------------------------- |
+| `teamix-evo design init <variant>`                  | 初始化设计体系(variant 必填)                      |
+| `teamix-evo design list-variants`                   | 列出可用 variant                                  |
+| `teamix-evo design list`                            | 查看已装机的 variant                              |
+| `teamix-evo design update`                          | 更新已装资源(stub,v0.7 见 ADR 0019)               |
+| `teamix-evo design uninstall`                       | 卸载已装 design                                   |
+| `teamix-evo skills add [name...]`                   | 装 skills(写源 + 镜像 IDE);不传 = 全装            |
+| `teamix-evo skills list`                            | 列出所有 skill 的安装状态                         |
+| `teamix-evo skills update`                          | 升级 skills(保留 managed 改动)                    |
+| `teamix-evo skills sync [name...]`                  | 源 → IDE 镜像(漂移恢复用)                         |
+| `teamix-evo skills doctor`                          | 检测源/镜像漂移(ADR 0013)                         |
+| `teamix-evo skills uninstall`                       | 卸载 skills(源 + 镜像 + lock)                     |
+| `teamix-evo ui init`                                | 初始化 ui 配置(aliases / iconLibrary / tsx / rsc) |
+| `teamix-evo ui add <id...>`                         | 安装指定 ui 组件源码                              |
+| `teamix-evo ui list [--installed]`                  | 列出可用/已安装 ui 组件                           |
+| `teamix-evo biz-ui list-variants`                   | 列出 biz-ui 包内提供的业务变体                    |
+| `teamix-evo biz-ui add <id...> --variant <name>`    | 安装变体感知业务组件(`--variant` 必填)            |
+| `teamix-evo templates list-variants`                | 列出 templates 包内提供的页面模板变体             |
+| `teamix-evo templates add <id...> --variant <name>` | 安装变体感知页面模板(`--variant` 必填)            |
+
+> 占位组件 → 真组件的升级流程**不是** CLI 子命令，由
+> [`teamix-evo-ui-upgrade`](../../packages/skills/skills/teamix-evo-ui-upgrade/SKILL.md)
+> skill 在 IDE 内驱动,底层仍调用 `teamix-evo ui add`。
+
+### 全局装 skill(`--scope global`)
+
+`skills add` 支持 `--scope global` 装到 IDE 全局(`~/.qoder/skills/` + `~/.claude/skills/`)。当 cwd 不是 Teamix Evo 项目时,工具会自动把元数据写到 `~/.teamix-evo-global/`,不污染当前目录。
+
+```bash
+# Onboarding 推荐:全局装 manage skill
+npx teamix-evo@latest skills add teamix-evo-manage --scope global --ide claude,qoder -y
+
+# 后续维护(update / uninstall 等)需 cd 到全局元数据根
+cd ~/.teamix-evo-global && npx teamix-evo skills update
+```
 
 ## 关键约定
 

package/dist/core/index.d.ts

@@ -1,26 +1,50 @@
-import { TailwindVersion, InstalledResource, SkillIde, SkillScope, UiAliases, UiEntry, VariantManifest, SkillsPackageManifest, UiPackageManifest, InstalledManifest, ProjectConfig } from '@teamix-evo/registry';
+import { InstalledResource, SkillIde, SkillScope, UiAliases, UiEntry, VariantManifest, SkillsPackageManifest, SkillEntry, UiPackageManifest, InstalledManifest, ProjectConfig } from '@teamix-evo/registry';
 export { InstalledManifest, InstalledResource, ProjectConfig, SkillIde, SkillScope, TailwindVersion, UiAliases } from '@teamix-evo/registry';
 
 interface RunDesignInitOptions {
     /** Absolute project root directory. */
     projectRoot: string;
-    /** Design variant id, e.g. "opentrek". */
+    /** Design variant id (e.g. `"opentrek"`, `"uni-manager"`). */
     variant: string;
-    /** Tailwind major version of the consuming project. */
-    tailwind: TailwindVersion;
-    /** IDE identifier written into config.json (e.g. "qoder", "claude"). */
+    /** IDE identifier written into config.json (e.g. `"qoder"`, `"claude"`). */
     ide: string;
-    /** Override the design package name (defaults to "@teamix-evo/design"). */
+    /** Override the design package name (defaults to `"@teamix-evo/design"`). */
     packageName?: string;
+    /**
+     * Override resolution of the design package root. When provided, skips
+     * `require.resolve("<packageName>/package.json")`. Useful for tests that
+     * want to point at a fixture tree, and for embedding inside `create`
+     * where the package may not yet be installed in the consumer.
+     */
+    packageRoot?: string;
+}
+/**
+ * Outcome of the post-init skill auto-install step. `attempted` lists the skill
+ * ids we tried to install (baseline + variant overlay); `addedSkillIds` is what
+ * was actually installed (the rest were already present); `missing` lists skill
+ * ids that aren't in the manifest (warned, not fatal).
+ */
+interface SkillsAutoInstallResult {
+    attempted: string[];
+    addedSkillIds: string[];
+    skippedSkillIds: string[];
+    missing: string[];
 }
 type RunDesignInitResult = {
     status: 'installed';
     packageName: string;
     variant: string;
     version: string;
-    tailwind: TailwindVersion;
     count: number;
     resources: InstalledResource[];
+    /** Per ADR 0010 §4 diagnostics. */
+    merge: {
+        overrides: string[];
+        variantAdds: string[];
+        defaultPassThrough: string[];
+    };
+    /** Result of the auto-install of baseline + variant design-rules skills. */
+    skills?: SkillsAutoInstallResult;
 } | {
     status: 'already-initialized';
     existingVariant: string;
@@ -30,10 +54,11 @@ type RunDesignInitResult = {
  *
  * Side effects:
  * - Creates `<projectRoot>/.teamix-evo/`
- * - Writes `config.json` and `manifest.json`
- * - Installs design resources from the variant manifest into the project
+ * - Walks `default/` + `variants/<variant>/`, classifies each file by path
+ *   convention, writes to consumer (skipping `frozen` files that already exist)
+ * - Writes `pack.lock.json`, `config.json`, `manifest.json` (installed)
  *
- * No interactive prompts, no `process.exit`. Throws on hard failure.
+ * No interactive prompts, no `process.exit`. Throws on hard failure (P8).
  */
 declare function runDesignInit(options: RunDesignInitOptions): Promise<RunDesignInitResult>;
 
@@ -213,6 +238,21 @@ interface InstallResult {
  */
 declare function installResources(options: InstallOptions): Promise<InstallResult>;
 
+/**
+ * Source-mirror skills installer (per ADR 0013).
+ *
+ * Two-stage flow:
+ *   1. **writeSkillSources** — render upstream `<packageRoot>/<skill.source>` and
+ *      write to `<projectRoot>/.teamix-evo/skills/<id>/` (the consumer-side
+ *      source of truth, regenerable, in git).
+ *   2. **syncSkillsToIdes** — pure byte-for-byte copy from source dir to each
+ *      requested IDE mirror path (`.qoder/skills/<id>/`, `.claude/skills/<id>/`).
+ *      Mirrors are 100% derived; not subject to managed-region preservation.
+ *
+ * `installSkills` orchestrates both. `updateSkills` re-renders the source with
+ * managed-region preservation against the existing source (NOT the mirrors),
+ * then re-syncs.
+ */
 interface SkillInstallOptions {
     /** Project root directory */
     projectRoot: string;
@@ -234,13 +274,19 @@ interface SkillInstallResult {
     count: number;
 }
 /**
- * Install (or reinstall) all skills declared in the manifest, fanning out to the
- * intersection of requested IDEs and each skill's declared `ides`.
+ * Install (or reinstall) all skills declared in the manifest using the
+ * source-mirror flow. Returns InstalledResource records for both source files
+ * and IDE mirror files.
  */
 declare function installSkills(options: SkillInstallOptions): Promise<SkillInstallResult>;
 interface SkillUpdateOptions extends SkillInstallOptions {
-    /** Existing installed records for the skills package */
-    installed: InstalledResource[];
+    /**
+     * Optional: existing installed records (legacy parameter kept for callers that
+     * still pass it). The refactored updater consults the file-system source under
+     * `.teamix-evo/skills/<id>/` for managed-region preservation, so this is
+     * unused by the new flow. Callers should stop passing it.
+     */
+    installed?: InstalledResource[];
 }
 interface SkillUpdateResult {
     resources: InstalledResource[];
@@ -252,9 +298,41 @@ interface SkillUpdateResult {
     };
 }
 /**
- * Update skills according to their updateStrategy.
+ * Update skills with managed-region preservation applied at the SOURCE layer
+ * (not the mirrors). After source is rewritten, mirrors are re-synced cleanly.
  */
 declare function updateSkills(options: SkillUpdateOptions): Promise<SkillUpdateResult>;
+/**
+ * Sync existing skill sources to the requested IDE mirror paths.
+ *
+ * Used by:
+ *   - `skills add` (immediate mirror after source write — handled by installSkills)
+ *   - `skills sync` (re-mirror after the user adds an IDE or moves machines)
+ *   - `skills update` (re-mirror after source is rewritten)
+ *
+ * `onlyIds` lets the caller limit which skills are synced.
+ */
+interface SkillSyncOptions {
+    projectRoot: string;
+    /** Skills present in the source dir to mirror (caller derives from lock). */
+    skills: ReadonlyArray<{
+        id: string;
+        name: string;
+        updateStrategy: SkillEntry['updateStrategy'];
+    }>;
+    ides: readonly SkillIde[];
+    scope: SkillScope;
+    onlyIds?: string[];
+}
+interface SkillSyncResult {
+    resources: InstalledResource[];
+    count: number;
+}
+/**
+ * Mirror existing source dirs (`.teamix-evo/skills/<id>/`) to the given IDE
+ * paths. Pure byte-for-byte copy — no rendering, no merge.
+ */
+declare function syncSkillsToIdes(options: SkillSyncOptions): Promise<SkillSyncResult>;
 /**
  * Remove all installed skill files. Returns the absolute paths removed.
  */
@@ -361,4 +439,4 @@ declare function readInstalledManifest(projectRoot: string): Promise<InstalledMa
  */
 declare function writeInstalledManifest(projectRoot: string, manifest: InstalledManifest): Promise<void>;
 
-export { DEFAULT_UI_ALIASES, DEFAULT_UI_ICON_LIBRARY, type InstallOptions, type InstallResult, type RunDesignInitOptions, type RunDesignInitResult, type RunSkillsAddOptions, type RunSkillsAddResult, type RunUiAddOptions, type RunUiAddResult, type RunUiInitOptions, type RunUiInitResult, type RunUiListOptions, type RunUiListResult, type SkillInstallOptions, type SkillInstallResult, type SkillUpdateOptions, type SkillUpdateResult, type UiEntryListItem, type UiInstallOptions, type UiInstallResult, ensureTeamixDir, getTeamixDir, installResources, installSkills, installUiEntries, loadSkillsData, loadUiData, loadVariantData, readInstalledManifest, readProjectConfig, removeSkillFiles, removeUiFiles, runDesignInit, runSkillsAdd, runUiAdd, runUiInit, runUiList, updateSkills, writeInstalledManifest, writeProjectConfig };
+export { DEFAULT_UI_ALIASES, DEFAULT_UI_ICON_LIBRARY, type InstallOptions, type InstallResult, type RunDesignInitOptions, type RunDesignInitResult, type RunSkillsAddOptions, type RunSkillsAddResult, type RunUiAddOptions, type RunUiAddResult, type RunUiInitOptions, type RunUiInitResult, type RunUiListOptions, type RunUiListResult, type SkillInstallOptions, type SkillInstallResult, type SkillSyncOptions, type SkillSyncResult, type SkillUpdateOptions, type SkillUpdateResult, type UiEntryListItem, type UiInstallOptions, type UiInstallResult, ensureTeamixDir, getTeamixDir, installResources, installSkills, installUiEntries, loadSkillsData, loadUiData, loadVariantData, readInstalledManifest, readProjectConfig, removeSkillFiles, removeUiFiles, runDesignInit, runSkillsAdd, runUiAdd, runUiInit, runUiList, syncSkillsToIdes, updateSkills, writeInstalledManifest, writeProjectConfig };