Optimus UI是一个社区维护的 MIT 协议 Angular 组件库（80+ 可访问组件），采用pnpm Monorepo管理多个包。本文带你从零走通贡献流程：安装依赖、本地构建、运行测试、Lint 检查，直到用Conventional Commits规范提交代码并发起 PR，是新手参与 Optimus UI 开发的完整指南。

1. 认识 Monorepo 项目结构 🧩

Optimus UI 用 pnpm-workspace.yaml 把工作区划分为三部分：

几个值得了解的工作区特性：

• 依赖 Catalog：pnpm-workspace.yaml中定义了angular22目录（Angular 22 + TypeScript 6.0），各包通过"catalog:angular22"复用同一版本，避免依赖漂移；
• shamefullyHoist: true：依赖提升行为，方便工具链直接解析；
• packageManager 锁定：根 package.json 指定pnpm@11.13.1，建议用 Corepack 保证版本一致。

2. 环境准备：一键安装依赖与 Git Hooks

先克隆仓库：

git clone https://gitcode.com/gh_mirrors/op/optimus-ui cd optimus-ui

然后执行：

pnpm install

这一步会同时完成两件事：安装所有 workspace 依赖，并通过lefthook注册 Git 钩子（配置见 lefthook.yml）。钩子会在你提交时自动运行 Prettier 格式化暂存文件，并对提交信息执行 commitlint 校验——也就是说，后续很多"规矩"会被工具自动强制执行。

3. 本地运行文档站

pnpm run dev

文档站基于 Angular SSR，跑起来后所有组件 Demo 都会以优化后的 Optimus UI 渲染，方便你改完组件立刻看到效果。

如需验证服务端渲染，可用pnpm run dev:ssr。

4. 构建命令详解：从组件库到文档站

根目录的构建脚本是一条流水线，理解它有助于你定位失败环节：

主包构建前后还有钩子脚本：packages/optimus-ui/scripts/prebuild.mjs 会生成供 ng-packagr 使用的package.json，postbuild.mjs处理产物。日常开发改完组件，优先用pnpm run build:lib快速验证即可。

5. 测试流程：单元测试与覆盖率

测试配置见 packages/optimus-ui/vitest.config.mts。贡献组件改动时，务必为受影响的组件补充或更新单元测试——这是 CONTRIBUTING.md 的明确要求，也是 PR 能顺利被合并的关键。

6. Lint 与格式化：提交前最后两道关 🔍

手动检查命令：

pnpm run lint # ESLint（含 Angular 模板规则） pnpm run format:check # Prettier 格式检查 pnpm run lint:fix # ESLint 自动修复

而 lefthook 会在git commit时自动对暂存文件跑 Prettier 并把修复重新加入暂存区，所以只要提交前跑过pnpm run lint和pnpm run test:unit，本地提交基本不会再被钩子打断。

7. Conventional Commits：提交信息的硬性规则

项目通过 commitlint.config.ts 继承@commitlint/config-conventional，主要约束：

• type 白名单：feat、fix、docs、style、refactor、test、chore，其他类型直接报错；
• subject 大小写：要求 sentence-case 或 lower-case（首字母小写的句子风格）；
• 鼓励引用 Issue：支持Fixes #/Fixed #前缀，带 Issue 引用的提交信息更利于追溯；
• Merge开头的提交自动忽略校验；
• 特色规则no-ai-co-author：禁止在提交信息中添加 AI 工具的Co-authored-by尾注，规则实现见 scripts/commitlint/no-ai-co-author.ts。

✅ 推荐写法：fix: correct table row height when using sticky header❌ 避免写法：Fix: Fixed the table bug!!（type 需小写、subject 不应大写开头）

8. 提交 PR 的完整工作流 🚀

1. 从main拉新分支，保持改动聚焦——小而清晰的 PR 更容易被评审合并；
2. 实现改动，并为受影响的组件补充单元测试；
3. 本地验证：pnpm run lint+pnpm run test:unit（主题引擎相关则加pnpm run test:styled）；
4. 按 Conventional Commits 规范提交，commitlint 钩子会在提交时把关；
5. 发起 PR，描述清楚改动动机；修 Bug 时附上复现步骤和版本信息（Optimus UI 版本、Angular 版本、浏览器）。

💡 特别提示：如果你在 PrimeNG 官方仓库有未合并的 PR，可以下载.patch文件后用git am原样迁移到本项目，保留原有提交历史，详见 CONTRIBUTING.md。

9. 常见问题速查

• 钩子不生效？确认使用pnpm install（而非 npm）安装，lefthook 会自动注册钩子；
• 构建失败在build:check？先跑pnpm run format和pnpm audit --prod --audit-level high排查格式与安全告警；
• 不确定该改哪个包？组件与指令在 packages/optimus-ui/src/；主题预设在 packages/optimus-ui-themes/src/presets/；文档与 Demo 在 apps/docs/doc/；
• 工作流有疑问？项目欢迎提 Issue 或讨论，改进贡献指南本身也算一份贡献。

按以上流程走完，你的第一个 PR 就已经走完了 Optimus UI 社区维护的完整质量闭环：Monorepo 统一构建、自动化测试、钩子强制的代码规范与提交规范。祝贡献顺利！