用途:描述 quota-axi 仓库的自动化发布流水线、CI 工作流约束、贡献门禁架构与仓库维护规则。
发布流程:发布由合并进 main 的 Conventional Commits 消息(feat:、fix:、chore: 等)驱动。release-please 自动管理版本号提升、变更日志生成和发布 PR;.release-please-manifest.json 初始定为 0.1.0(release-please 接入前手动发布的版本),之后由 release-please 更新;release-please-config.json 将 bootstrap-sha 锁定为 9f5dc949c50ab8ac0a441be777e1c3693ee0b612(产出已发布 0.1.0 包的提交),除非修正已发布基线,否则不要更改该 SHA。禁止手工编辑 CHANGELOG.md 或 .release-please-manifest.json,守卫工作流(.github/workflows/guard-generated-files.yml)会自动拒绝触碰这些文件的 PR。
npm 发布:合并发布 PR 会触发 .github/workflows/release-please.yml 发布到 npm,使用 npm OIDC 可信发布流程(id-token: write 加 --provenance),无需存储令牌密钥;发布步骤仅以 steps.release.outputs.release_created 为条件,工作流本身没有仓库守卫,与包的绑定来自 npm 可信发布方 OIDC 配置。技能生成方面,skills/quota-axi/SKILL.md 由 src/skill.ts 生成,应通过 pnpm run build:skill 重新生成而非直接编辑,CI 用 pnpm run build:skill -- --check 校验一致性。
CI 与排除规则:每个 pull_request 工作流(ci.yml、guard-generated-files.yml)都必须包含覆盖发布输出集(.release-please-manifest.json、CHANGELOG.md、package.json)的 paths-ignore 过滤。唯一有意例外是 .github/workflows/no-mistakes-required.yml,因为门禁判定取决于 PR 正文而非变更文件,加路径过滤会漏掉仍需证明的 PR;两边规则均由 test/release-ci-exclusions.test.ts 守护。
贡献门禁:CONTRIBUTING.md 定义贡献者要求、PR 期望与豁免;.no-mistakes.yaml 定义 commands.prepare 与 commands.test(pnpm test)及基线后实时验证的 test.instructions;allow_repo_commands 保持禁用,防止不受信任的 PR 分支注入任意命令或代理,由 test/no-mistakes-config.test.ts 守护。.github/workflows/no-mistakes-required.yml 将执行委托给固定到不可变提交 SHA 的 kunchenguid/no-mistakes/.github/actions/require-no-mistakes,仅通过独立 PR 升级该 pin。
锁文件格式化:pnpm-lock.yaml 使用 Prettier 格式化,更新依赖后运行 pnpm exec prettier --write pnpm-lock.yaml,使依赖差异最小整洁;CI 的 pnpm install --frozen-lockfile 接受 Prettier 格式的 YAML。