@teamix-evo/registry

Teamix Evo 协议包 — 提供 Schema、类型、加载器、校验器和策略决策引擎。

定位

registry 是整个 Teamix Evo 架构的协议层，负责定义：

• 资源清单（VariantManifest）的结构约束
• 项目配置（ProjectConfig）的 Schema
• 安装状态（InstalledManifest）的追踪格式
• 三种更新策略（frozen / regenerable / managed）的决策逻辑
• Managed Regions 标记的解析与替换

CLI 包和 design 包都依赖本包的协议定义工作。

目录结构

packages/registry/
├── src/
│   ├── schema/
│   │   ├── index.ts          # Schema 统一导出
│   │   ├── manifest.ts       # VariantManifest Zod Schema
│   │   ├── config.ts         # ProjectConfig Zod Schema
│   │   └── installed.ts      # InstalledManifest Zod Schema
│   ├── types.ts              # 从 Schema 推导的 TypeScript 类型
│   ├── loader.ts             # 从文件系统加载 manifest
│   ├── validator.ts          # 校验封装 + 友好错误消息
│   ├── strategy.ts           # updateStrategy 决策函数
│   ├── managed-regions.ts    # HTML 标记区解析与替换
│   ├── index.ts              # 公共导出入口
│   └── __tests__/            # 单元测试
├── tsup.config.ts            # 构建配置（ESM + CJS + DTS）
├── tsconfig.json
└── package.json

研发流程

1. 环境准备

# 在仓库根目录
pnpm install

2. 开发

# 监听模式构建（修改即时编译）
pnpm --filter @teamix-evo/registry dev

3. 新增 / 修改 Schema

1. 在 src/schema/ 中使用 Zod 定义或修改 Schema
2. 在 src/types.ts 中通过 z.infer<typeof XxxSchema> 导出对应类型
3. 在 src/index.ts 中确保新增的 Schema 和类型被导出
4. 如需新增校验函数，在 src/validator.ts 中添加

4. 修改策略逻辑

• src/strategy.ts — 修改 shouldUpdate 或 getUpdateAction
• src/managed-regions.ts — 修改标记解析或替换逻辑

5. 测试

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

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

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

• manifest.test.ts — VariantManifest Schema 校验
• config.test.ts — ProjectConfig Schema 校验
• installed.test.ts — InstalledManifest Schema 校验
• validator.test.ts — 友好错误消息格式化
• strategy.test.ts — 三种策略决策逻辑
• managed-regions.test.ts — 标记解析、替换、错误检测

6. 类型检查

pnpm --filter @teamix-evo/registry typecheck

7. 构建

pnpm --filter @teamix-evo/registry build

产物输出到 dist/，包含：

• index.js — ESM 格式
• index.cjs — CommonJS 格式
• index.d.ts — TypeScript 声明

8. 发布前检查

• 确保所有测试通过
• 确保类型检查通过
• 本包与 teamix-evo（CLI）使用 linked 版本策略，需一起发布

关键约定

• 所有 Schema 使用 Zod 定义，运行时校验 + 编译时类型推导一体
• Result<T> 类型用于校验返回，避免 throw（除 loader 和 managed-regions 外）
• managed regions 标记格式：<!-- teamix-evo:managed:start id="xxx" -->...<!-- teamix-evo:managed:end id="xxx" -->
• 同一文件中 region id 不得重复

依赖关系

本包无内部包依赖
CLI 包 → 依赖本包
design 包 → devDependencies 引用本包（验证脚本）