Apache Maka CLI 的 npm 发布操作手册：从 ASF source RC 到 npm staging、2FA 批准与 Finalize 的完整流水线

Apache Maka CLI 的 npm 发布操作手册从 ASF source RC 到 npm staging、2FA 批准与 Finalize 的完整流水线【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka导读本文是 Apache MakaIncubating项目中maka-agent命令行工具通过 npm 渠道发布的操作权威对应仓库文档 docs/cli-npm-release.zh-CN.md。它以 ASF source release 为唯一版本身份通过 GitHub Actions 的 Trusted Publisher、npm staged publishing 与人工 2FA 批准把已批准的源码 commit安全转化为 npm 上的正式版本与 Nightly 快照。读完本文你将掌握发布不变量与 workflow 边界划分、一次性控制面配置Environment 与 Trusted Publisher、Nightly 自动发布机制、从 Stage 候选到 npm 审批再到 Finalize 的完整操作序列以及各类失败场景的恢复策略。版本权威与发布身份模型Maka 的版本权威是唯一的根目录 package.json 是 Maka 产品版本的唯一权威packages/cli/package.json中的maka-agent版本必须与其严格一致当前仓库三者均为0.2.0。因此每个公开的 npm 版本都必须来自共享 package workflow 验证过的精确 tarball不允许在发布链之外手工打包ASF 分发基础设施上经 IPMC 批准的源码归档才是 Apache releasenpm 包、Desktop 安装包与 GitHub Release assets 都是从该源码身份构建的便利包convenience artifacts不是额外的 ASF release artifacts因此不需要独立的 ASF 签名、SHA-512 sidecar 或dist/dev、dist/release归档字节身份。source RC 阶段执行的 npm 预检asf-npm-candidate.yml是更早执行、且不持有发布凭据的兼容性检查——它构建并验证候选 tarball但不会进入正式发布。source release 获批后Stage 从位于同一获批 commit 的最终产品 tag 重新构建并成为 npm staging 与 registry 验证所使用的字节权威。这一实践与 Apache OpenDAL 孵化期的做法一致其 Node.js workflow 在评审期间只验证 RC tag、不发布获批后在同一 commit 的最终 tag 触发发布同时保留了 Maka 更严格的受保护 Environment、staged publishing、2FA 与 Finalize 控制。发布不变量无论发布多少次以下不变量必须始终成立产品发布工作流只能从已批准的 ASF source candidate tagdispatchnpm Stage 与 npm Finalize 都只能从maindispatchStage 仅把随后创建的产品vversiontag 作为已验证数据获批的稳定版本使用latestdist-tag开发快照使用nightly不再存在next渠道且nightly永远不得修改latest不创建 npm 专属 Git tag 或 GitHub ReleaseReleaseworkflow 在 npm staging 前创建产品vversiontag 与 DraftFinalize 是该 Draft 唯一的发布者在 npm Finalize 与 Desktop 远程 Runtime Host 验收成功前GitHub Release 必须保持 DraftDraft 为 npm 提供产品身份发布 Draft 是最终的产品发布动作正式发布只能运行npm stage publish由人工 package maintainer 使用 npm 2FA 批准只有 Product Nightly 可以直接运行npm publish --tag nightlyvalidation、staging、approval 与 finalization 之间不得重新构建保证字节一致已公开的版本不得复用正式产品修复必须使用新的 patch、minor 或 major 版本。这些不变量在源码层面被强校验例如 release-cli-stage.yml 的authorizejob 使用 scripts/product-release-authority.mjs 的verify-draft检查 tag 与 Draft 身份并用 scripts/product-release-identity.mjs 校验三个 manifest 的产品版本一致。四个 workflow 的边界划分发布链由四个 workflow 各司其职职责边界如下npm-publication.yml 是唯一的 Trusted Publisher caller它只能从main运行把精确产品 tag 作为待验证数据路由正式发布channelformal并发布 npm Nightlychannelnightly或 schedulerelease-cli-stage.yml 解析已有的产品 tag 与 GitHub Release无 OIDC 的 job 从产品 commit 构建并验证一个 immutable tarballOIDC job 只执行main上已审查的 publisher 代码分别记录产品 source 与 publisher 身份再把验证过的字节提交到 npm stagingdesktop-nightly.yml 只在 npm Nightly 成功后启动只消费 immutable version filesource commit 与上游 run 身份直接取自已认证的workflow_runeventrelease-cli-finalize.yml 只接受精确的成功 Stage run、Release build run 及其自包含 publication recordmain上当前已审查的 verifier 验证公共 registry 字节、signature、provenance、dist-tag、不可变 build artifacts 与 live Draft digest然后等待受保护的product-releaseEnvironment独立 Desktop 验收完成并批准后用受保护 workflow 的身份证明精确便利包并在同一个操作中发布 GitHub Release 及其 Stable/Latest 分类。从源码可以确认这些边界的落点npm-publication.yml 的formaljob 直接uses: ./.github/workflows/release-cli-stage.ymlworkflow_callpublishjob 声明environment: npm-publication并通过npm publish --tag nightly --registry https://registry.npmjs.org/ --provenance发布release-cli-finalize.yml 的publishjob 声明environment: product-release使用actions/attest生成 provenance并把离线验证 bundle 命名为Maka-version-attestation.sigstore.json最后调用product-release-authority.mjs publish-draft完成 Draft→published 转换。一次性控制面配置GitHub Environment仓库中的 .asf.yaml 是 Environment 配置的权威其中定义了release、npm-publication、nightly、product-release四个 Environment。配置进入main后需确认 ASF 同步出的 live 配置满足npm-publication只允许 selectedmainbranch为保证 Nightly 自动运行不设置 approval gatenightly只允许 selectedmainbranch为保证 Desktop Nightly 自动运行不设置 approval gateproduct-release只允许 selectedmainbranchrequired reviewer 为M4n5ter并禁止 self-review对应 .asf.yaml 中prevent_self_review: true仓库策略允许时禁用 administrator bypass。检查或修复同步结果需要仓库 administration 权限不要再在 GitHub UI 中维护第二套手工 Environment policy.asf.yaml 中注释明确naming an environment replaces its settings wholesale所有保护规则必须保留在声明式权威中。Finalize 使用 GitHub Actions OIDC 为精确便利包生成 Sigstore provenance并把离线验证 bundle 与便利包放在一起——全程不需要仓库 administration credential、签名私钥或 npm token。npm Trusted Publisher在maka-agentpackage settings 中配置一个 GitHub Actions trusted publisher字段值Organization or userapacheRepositorymakaWorkflow filenamenpm-publication.ymlEnvironment namenpm-publicationAllowed actionsnpm publish与npm stage publish注意Workflow filename 区分大小写且不包含.github/workflows/前缀。正式 staging 与 Nightly direct publish 都使用npm-publicationEnvironment它只允许main。因为 Nightly 需要自动运行所以不设置 GitHub approval gate正式发布在 staging 后仍须由人工使用 npm 2FA 批准。不要配置第二个 publisher 或 npm token。第一次 OIDC Stage 成功后将 package publishing access 设置为Require two-factor authentication and disallow tokens然后撤销不再使用的 publish token不要在这一步移除人工 package owner 或恢复权限。在 .asf.yaml 完成 Environment 同步且 Trusted Publisher 与其匹配前不要设置仓库变量NPM_NIGHTLY_ENABLED。之后将它设为true先手动运行一次 Nightly再依赖 schedule。该变量只控制 npm——在 npm-publication.yml 中可以看到identityjob 的if: vars.NPM_NIGHTLY_ENABLED true (...)条件Desktop 使用独立的DESKTOP_NIGHTLY_ENABLEDrollout gate见 desktop-nightly.yml 的identityjob 条件。Product Nightly开发快照的自动发布定时触发的npm-publication.ymlrunschedule 为cron: 17 18 * * *会从精确的maincommit 生成一个 immutable 版本格式类似0.2.0-dev.42.20260829由 scripts/product-nightly.mjs 的identity子命令解析验证四平台maka-agenttarball 后发布到nightlydist-tag。只有精确版本和 dist-tag 都已公开后成功的 workflow 才会触发desktop-nightly.yml。Desktop 只消费该 immutable 版本号精确 source commit 来自已认证的上游workflow_runevent。打包后的 Desktop 记录精确的 Runtime Host setup specifier例如maka-agent0.2.0-dev.42.20260829绝不安装会漂移的nightlytag。两个 workflow 按以下顺序发布要求候选 npm run number 大于当前nightlytagproduct-nightly.mjs assert-channel-advance使用 provenance 将精确 npm tarball 发布到nightlynpm publish --tag nightly --provenance要求公共 registry 中的精确版本和nightlytag 都已可读——源码中该步骤会轮询最多 45 分钟135 次 × 20 秒因为 npm 在版本发布后需先扫描才能被读取且每次都使用--prefer-online避免缓存 packument 掩盖新版本构建、验证并 attest 精确的 Desktop 安装包和 GitHubdevmetadata将受保护的vversiontag 绑定到精确 source commit并验证 Draft 中恰好是desktopNightlyReleaseAssetNames定义的那些资产仅在 Draft 完整后发布 Latest 关闭的 GitHub prerelease。这个顺序既避免 Desktop 指向 npm 中不存在的 Runtime Host也让 npm Nightly 与 Desktop 打包彼此独立。npm 或 Desktop run 失败后都不得原地 rerun两个 workflow 均在首步检查github.run_attempt ! 1并直接失败应启动新的 npm Nightlygh workflow run npm-publication.yml --ref main -f channelnightlyNightly 是开发快照不是 Apache Release不得从面向最终用户的下载页推广。开发者可以明确使用maka-agentnightly产品自动化必须使用 Desktop 记录的精确版本。准备正式发布正式发布channelformal前按以下顺序准备将本次包、文档和发布变更全部合并到main准备 ASF source candidate并完成podling 和 Incubator PMC 两轮投票确认已批准 source commit 上的根产品版本、apps/desktop/package.json 与 packages/cli/package.json 是同一个尚未使用的稳定目标版本例如当前仓库均为0.2.0。正式 npm 发布只推进latest从精确的已批准vversion-incubating-rcrctag dispatch 产品Releaseworkflow并将同一个 tag 作为source_reference_tag。确认其 DraftvversionRelease 指向已批准 commitnpm staging 消费这个身份不能先于它运行确认目标版本既不在公共 registry也不在 staged package 中version0.2.0 npm view maka-agent$version version --registry https://registry.npmjs.org/ npm stage list maka-agent --registry https://registry.npmjs.org/第一个命令应报告目标版本不存在。如果已经存在同版本 stage先处理它不要再次提交确认npm-publicationEnvironment 和 Trusted Publisher 仍与上面的值一致并确认负责批准的 npm 账号已经启用 2FA。Stage 候选包从已审查的maindispatch workflow并提供精确产品版本version0.2.0 gh workflow run npm-publication.yml --ref main \ -f channelformal \ -f version$version确认新建的 run 使用main。workflow 把vversion与 Draft 作为数据解析要求 tag commit 仍是main的 ancestor在无 OIDC 的 job 构建候选包并把 npm provenance 绑定到已审查的mainpublisher workflow 与精确 run等待可复用 package validation jobs 全部通过。从 cli-package-validation.yml 的矩阵可以看到它只构建一个tarball并在 Linux x64/arm64ubuntu-24.04/ubuntu-24.04-arm、macOS arm64macos-15、Windows x64windows-2025上运行安装态 CLI 冒烟测试scripts/smoke-release-cli-package.mjs在 Linux x64 上运行真实 Harbor 与 Pier Docker cellrelease:cli:eval并执行 released State Root 资格检查release:cli:qualify-state-root通过bubblewrap沙箱验证跨 epoch 的 State Root 迁移此外还会用cargo-deny与audit-shipped-dependencies.mjs做依赖审计从 run summary 和cli-staged-release-attemptartifact 记录成功 Stage workflow 的run ID、run attempt、source commit、version 和 staged artifact checksumartifact 包含.tgz、.tgz.sha256、.tgz.files.json与release.json。Stage workflow 没有成功结束时不得在 npm 上批准任何内容。在 npm 上检查并批准执行下面的检查和审批命令需使用Node.js 22.14.0 或更高版本和 npm 11.15.0 或更高版本。Stage workflow 使用自身经过审查的工具链workflow 固定的 Node.js 版本如 stage 使用22.19.0、publish 使用24以及仓库packageManager固定的精确 npm 版本当前仓库为npm11.19.0。npm stage list maka-agent --registry https://registry.npmjs.org/ stage_idreplace-with-reviewed-stage-id npm stage view $stage_id --registry https://registry.npmjs.org/ npm stage download $stage_id --registry https://registry.npmjs.org/批准前必须完成确认 package name、version、dist-tag、provenance 和 source repository 与 Stage run 一致将下载的 staged tarball SHA-256 与 workflow artifact 的.tgz.sha256比较检查文件清单和包内README.md确认 tarball 属于所记录的 Stage run 和 source commit。批准前的最后一步重新检查 Stage run 记录的 live 产品权威set -eu source_commitreplace-with-stage-recorded-commit node scripts/product-release-authority.mjs verify-draft \ v$version $source_commit apache/makaverifier 必须成功。tag 不存在、已移动、不再位于main匹配的 GitHub Release 不再是 Draft或被标记为 prerelease 时都必须停止。这也正是 release-cli-stage.yml 的authorizejob 与stagejob 在npm stage publish前所执行的同一校验最终提交命令为npm stage publish $RELEASE_TARBALL \ --tag $RELEASE_DIST_TAG \ --registry https://registry.npmjs.org/ \ --provenance只批准这个 stage ID。npm 会要求 2FA并在批准时将 package 公开npm stage approve $stage_id --registry https://registry.npmjs.org/也可以在 npmjs.com package 的Staged Packages页面完成相同的检查和批准。获得批准后检查公共 dist-tagsversion0.1.0 npm view maka-agent dist-tags --json --registry https://registry.npmjs.org/latest必须指向获批版本nightly如果存在保持独立。Finalize 产品发布npm 显示该版本已经公开后在main上打开Actions → Finalize product release → Run workflow对应 release-cli-finalize.yml它强制refs/heads/main输入成功 Stage 的 run ID 与精确 attempt、成功 Release build 的 run ID 与精确 attempt以及 versionworkflow 会校验这两个 ID 都是正整数并通过gh api拉取精确 attempt 的 run 记录让 inspection job 验证公共 tarball 字节、checksum、inventory、npm signature、Trusted Publishing provenance 与精确的latestdist-tag——包括npm audit signatures --include-attestations签名审计与fetch-registry的公共字节核对publication job 等待product-release批准期间针对 Draft 完成产品检查清单中的跨机器验收批准 Environment并确认 workflow 将每个 live Draft digest 与精确 Release attempt 的 publication record 对比生成并上传Maka-version-attestation.sigstore.json发布便利包 Releasestable release 会同时成为 Latest不再需要单独人工操作。检查最终 registry 状态version0.2.0 npm view maka-agent$version version dist.tarball dist.integrity --json npm view maka-agent dist-tags --json最后在每个发布平台安装精确的公共版本并完成一次真实的 TUI/model turn。在支持的 Eval host 上完成至少一个真实 experiment cell检查 score、usage、cost 和 artifacts。产品发布检查清单仍是批准发布前所需验收证据的权威其中还覆盖了 macOS 签名公证Apple Team ID 固定为FABM2QUA8Q、Windows 未签名政策、CLI ZIP 内容清单必须含bin/maka、RELEASE.json、DISCLAIMER-WIP、LICENSE、NOTICE、THIRD_PARTY_NOTICES.txt且无bin/maka-agent等细节。失败恢复npm staging 之前失败如果在npm stage publish前发生瞬时失败从同一个产品 tag 重新运行 Stage。如果必须修改代码或 workflow则在main修复、递增产品版本、创建新的产品 tag 和 Draft再 Stage 新版本。此时没有消耗 npm 版本。Stage workflow 失败但 npm 中存在 stage提交是 Stage workflow 的最后一个业务步骤因此响应丢失可能导致 workflow 未成功但 npm 已经存在 stage。不要批准这个 orphanFinalize 只接受成功的 Stage run attempt。检查后先用 2FA 拒绝精确的 stage ID再启动新的 Stage runstage_idreplace-with-reviewed-stage-id npm stage view $stage_id --registry https://registry.npmjs.org/ npm stage reject $stage_id --registry https://registry.npmjs.org/不要只根据 version 文本拒绝 stage操作必须绑定到已经检查的 stage ID。Stage 成功但人工检查发现问题拒绝该 stage在main修复、递增产品版本、创建新的产品 tag 和 Draft再 Stage 新版本。不要为了清空 staging area 而批准有问题的候选。npm approval 成功但 Finalize 失败npm 版本此时已经 immutable不要再次 publish 或 approve。保留 Stage run ID、attempt、version以及 Release run ID、attempt、publication record 和 artifacts。如果这些字节与 provenance 有效在main修复 Finalize verifier然后针对同一组不可变 Stage 与 Release 证据重新运行。inspection job 只读只有受保护的 publication job 可以执行一次 Draft-to-published 转换并证明其字节对应product-release-authority.mjs publish-draft。如果 npm identity、build evidence 或 Draft 不一致立即停止并调查不要修改产品 tag 或 GitHub Release 来让验证通过。如果错误发生在 publication request 之后先检查精确 Release已经成功完成的发布不得重复执行。公共版本存在缺陷先把受影响的 dist-tag 指回先前验证过的版本known_good0.2.0 npm dist-tag add maka-agent$known_good latest然后只 deprecate 有缺陷的版本并引导用户使用已经指向验证版本的恢复 dist-tagbad_version0.2.1 recovery_taglatest npm deprecate maka-agent$bad_version Known issue; install maka-agent$recovery_tag.验证 dist-tags、修复缺陷然后通过完整 Stage 和 Finalize 流程发布新版本。不要把npm unpublish当作常规回滚删除 immutable dependency bytes 会破坏现有安装也不能恢复经过审查的发布链。Nightly 存在缺陷时dispatch 新 run让新的 immutable 版本推进nightly。如果必须立即回滚人工 package owner 可以把nightly指回之前验证过的 Nightly并只 deprecate 有缺陷的精确版本。绝不能让latest指向 Nightly。所有权与紧急恢复GitHub repository admin 负责npm-publicationEnvironment 配置release maintainer 负责 dispatch、staged-package 检查、npm 2FA approval 和最终验收npm package owner 负责 Trusted Publisher、publishing access、maintainer 和 dist-tag 恢复trusted publishing 启用期间至少保留一个启用 2FA 的人工 owner。移除当前 direct owner 前先加入预期的 npm organization publishing team 和另一名人工 direct recovery maintainer并验证两条恢复路径workflow 不得获得长期 npm token。OIDC、Environment 或 trust relationship 损坏时暂停发布并修复控制面不要使用npm publish绕过 stagingnpm 账号丢失时使用该账号的恢复方式或另一名已经验证的 package owner。在建立第二名 owner 之前恢复依赖当前 owner 的 npm recovery credential完成所有权 follow-up 属于明确的运维债务repository 或 npm publisher 设置出现意外变更时移除或禁用 trust relationship保留 workflow 与 npm audit 证据恢复经过审查的配置并为 integrity 存疑的候选使用新版本。参考资料CLI npm release 英文原版ASF npm source-RC 预检说明 与 asf-npm-candidate.yml产品发布检查清单发布链 workflownpm-publication.yml、release-cli-stage.yml、release-cli-finalize.yml、cli-package-validation.yml、desktop-nightly.yml控制面权威配置.asf.yaml版本身份与发布脚本scripts/product-release-authority.mjs、scripts/product-release-identity.mjs、scripts/product-nightly.mjs、scripts/release-cli-publication.mjs、scripts/smoke-release-cli-package.mjs版本 manifestpackage.json、packages/cli/package.json、apps/desktop/package.json【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考