Apache Maka CLI npm 发布全流程Nightly 快照、npm Stage 与 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-agentnpm 安装渠道的官方运行手册runbook覆盖从定时 Nightly 快照、正式版本暂存Stage、npm 2FA 人工批准到 Finalize 定稿的完整受控流水线。读者将掌握 Maka 如何在 Apache 孵化器约束下以源发布为准、npm 为便利包的模型安全发布 CLI以及各环节的可验证命令、故障恢复策略与所有权边界。发布模型ASF 源发布是唯一权威npm 是便利包Maka 的发布体系建立在一个明确的分层模型上IPMC 批准的源码归档source archive才是 Apache Releasenpm 包、桌面安装包和 GitHub Release 资产都是从该已批准源构建的便利包convenience packages不构成额外的 ASF 发布产物。在这一模型下版本权威也保持单一根目录 package.json 是 Maka 产品的唯一版本权威当前为0.2.0packages/cli/package.json必须与之完全一致同样为0.2.0。每一次公开发布的 npm 版本都必须来自共享打包工作流校验过的精确 tarball不允许在验证、暂存、批准、定稿之间重建。正式的发布路径之前还有一道更早的检查源码 RC 的 npm 预检运行手册对应 .github/workflows/asf-npm-candidate.yml。该预检不需要任何发布凭据只从vversion-incubating-rcrc标注 tag 构建一个干净源的 npm tarball 并在全平台矩阵上验证安装能力作为源码 RC 的诊断证据。它的 tarball不会带入正式发布源码获批后Stage 从最终产品 tag同一获批 commit重建成为 npm 暂存与 registry 校验的字节权威。发布不变量Release invariants这些不变量是整个发布体系的底线约束任何操作都不得违反产品 Release 工作流只能从精确获批的 ASF 源候选 tag 触发npm Stage 与产品 Finalize 都从main触发Stage 只把由此产生的产品vversiontag 当作已校验的发布数据data而非可信代码。已批准的稳定版本发布到latest渠道开发快照发布到nightly渠道。不存在next渠道nightly永远不得改动latest。不创建 npm 专属的 Git tag 或 GitHub Release。Release工作流在 npm 暂存之前创建产品vversiontag 和 DraftFinalize 是该 Draft 的唯一发布者。GitHub Release 保持 Draft 状态直到 npm Finalize 和桌面端远程 Runtime Host 验收都成功。Draft 为 npm 提供产品身份其正式发布是产品的最终动作。正式发布只允许执行npm stage publish由人类包维护者使用 npm 2FA 批准暂存包。只有 Product Nightly 可以不经人工直接执行npm publish --tag nightly。验证、暂存、批准、定稿之间不得重建。绝不复用已公开的版本号。正式产品修复必须使用新的 patch/minor/major 版本。四条工作流边界整个发布流水线由四份工作流协作完成职责严格分离npm-publication.yml 是唯一的 Trusted Publisher 调用方。它只从main运行将正式发布路由到以精确产品 tag 为数据输入的 Stage 流程同时负责发布 npm Nightly。工作流提供channelnightly/formal与version两个手动输入并内置定时调度cron: 17 18 * * *UTC用于 Nightly。release-cli-stage.ymlStage CLI npm release解析已存在的产品 tag 与 GitHub Releaseauthorize、validate两个 job 不带 OIDC从产品 commit 构建并校验一个不可变 tarball带 OIDC 的stagejob 只执行经过评审的main发布者代码分别记录产品源与发布者双重身份并把校验过的字节提交到 npm 暂存区。**desktop-nightly.ymlDesktop Nightly**只在 npm Nightly 成功后启动只消费其不可变版本文件并通过经过认证的workflow_run事件取得源 commit 与上游 run 身份。**release-cli-finalize.ymlFinalize product release**只接受精确的、成功的 Stage run、Release build run 与自包含发布记录。main上经过评审的校验器检查公开 registry 字节、签名、provenance、dist-tag、不可变构建产物与实时 Draft 摘要随后在受保护的product-releaseEnvironment 等待桌面端独立验收通过后批准以受保护的工作流身份对精确便利包做 attestation、发布 GitHub Release并一步完成 Stable/Latest 分类。一次性控制平面配置GitHub Environment以.asf.yaml为权威检查入库的 .asf.yaml 是npm-publication、nightly、product-release三个 Environment 的唯一权威配置来源。该文件被合入main后需确认 ASF 协调reconciliation产生了npm-publication选中main分支规则无审批门保证定时 Nightly 可自动发布见.asf.yaml中required_reviewers: []nightly选中main分支规则无审批门保证 Desktop Nightly 可自动发布product-release选中main分支规则必需评审人M4n5ter且禁止自评prevent_self_review: true仓库策略允许时禁用管理员绕过。另外.asf.yaml中还定义了名为 Immutable release tags 的 tag ruleset对所有v*tag 禁止删除与强制推送从 Git 层面保证产品 tag 的不可变性。检查或修复协调需要仓库管理权限不要在 GitHub 上另建一套手动 Environment 策略。Finalize 使用 GitHub Actions OIDC 为精确便利包创建 Sigstore provenance并将离线校验 bundle 存放到资产旁边全程不需要仓库管理凭据、签名私钥或 npm token。npm Trusted Publisher在maka-agent包设置中配置一个GitHub Actions Trusted Publisher字段值Organization or userapacheRepositorymakaWorkflow filenamenpm-publication.ymlEnvironment namenpm-publicationAllowed actionsnpm publish和npm stage publish工作流文件名区分大小写且不含.github/workflows/前缀。正式暂存与直接 Nightly 发布共用同一个npm-publicationEnvironment其部署规则只放行main。它没有 GitHub 审批门因为定时 Nightly 是自动的正式发布仍需暂存后的人类 npm 2FA 批准。不要配置第二个发布者或 npm token。首次 OIDC Stage 成功后将包发布访问权限设置为Require two-factor authentication and disallow tokens然后吊销过期的发布 token此变更不得移除人类包所有者或恢复访问通道。仓库变量NPM_NIGHTLY_ENABLED在.asf.yaml完成 Environment 协调、Trusted Publisher 匹配之前保持未设置之后置为true并手动运行一次 Nightly再依赖定时调度。该变量只控制 npmDesktop 有自己独立的DESKTOP_NIGHTLY_ENABLED滚动门见 desktop-nightly.yml 中的vars.DESKTOP_NIGHTLY_ENABLED true判断。Product Nightly开发者快照渠道定时触发的 npm-publication.yml 从精确的定时maincommit 生成一个不可变版本校验四平台maka-agenttarball并发布到nightlytag。版本号的生成逻辑在 scripts/product-nightly.mjs 中格式为productVersion-dev.runNumber.YYYYMMDD例如0.2.0-dev.42.20260829其中 runNumber 来自GITHUB_RUN_NUMBER日期来自构建日。该脚本同时要求产品版本本身必须是稳定的正式版本不允许 prerelease 产品版本并通过 scripts/release-version.mjs 中的parseProductNightlyVersion/assertProductNightlyAdvances严格校验 Nightly 版本的三段式 prereleasedev 正整数 run 8 位日期以及新 run 必须严格大于当前nightlytag 的 run。只有当精确版本与 dist-tag 都已公开后成功的 Nightly 工作流才会触发 desktop-nightly.yml。Desktop 只消费该版本经过认证的上游事件提供精确源 commit。打包的 Desktop 记录精确的 Runtime Host 安装说明符例如maka-agent0.2.0-dev.42.20260829绝不安装可变的nightlytag。两个工作流按此顺序发布防止 Desktop 宣传 npm 尚不存在的 Runtime Host 版本同时保持 npm Nightly 独立于桌面打包要求候选 npm run 号比当前nightlytag 更新带 provenance 将精确 npm tarball 发布到nightly要求从公共 registry 能读到精确版本与nightlytag工作流内会轮询最多 45 分钟每次 20 秒见npm-publication.yml的 publish job构建、校验并 attest 精确的 Desktop 包与 GitHubdev元数据将受保护的vversiontag 绑定到精确源 commit并验证desktopNightlyReleaseAssetNames定义的精确 Draft 资产Draft 完整后才发布 GitHub prerelease 且禁用 Latest。一次失败的 npm 或 Desktop 运行绝不在原地重跑工作流的 identity job 会以github.run_attempt ! 1直接拒绝因为每次尝试都有不可变的 npm 版本。请启动一次全新的 npm Nightlygh workflow run npm-publication.yml --ref main -f channelnightlyNightly 是开发者快照不是 Apache 发布不得从终端用户下载页推广。开发者可显式安装移动渠道maka-agentnightly产品自动化必须使用 Desktop 记录的精确版本。准备一次正式发布将所有计划中的包、文档与发布变更合并到main准备 ASF 源候选并完成 podling 与 Incubator PMC 两轮投票。确认在获批源 commit 上根 package.json、apps/desktop/package.json 与 packages/cli/package.json 的稳定目标版本相同且未被占用。正式 npm 发布只推进latest。从精确获批的vversion-incubating-rcrctag 触发产品Release工作流.github/workflows/release.yml并以同一 tag 作为source_reference_tag输入确认其 DraftvversionRelease 指向获批 commit。npm 暂存消费这个身份且不能先于它发生。确认目标版本在公共与暂存状态中都不存在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从经过评审的main触发工作流提供精确产品版本version0.2.0 gh workflow run npm-publication.yml --ref main \ -f channelformal \ -f version$version确认产生的 run 使用main。工作流把vversion及其 Draft 当作数据解析要求该 tag commit 仍是main的祖先不带 OIDC构建候选并把 npm provenance 绑定到经评审的main发布者工作流与精确 run。等待可复用包校验 job.github/workflows/cli-package-validation.yml通过构建一个 tarball并在 Linux x64/arm64、macOS arm64、Windows x64 上安装校验 CLI同时在 Linux x64 上运行真实的 Harbor 与 Pier Docker 单元。从 run 摘要与cli-staged-release-attempt构件记录成功的 Stage 工作流 run ID、run attempt、源 commit、版本与暂存产物校验和。若 Stage 工作流未成功结束绝不在 npm 上批准任何东西。Stage 的产物身份记录在release.json由 scripts/release-cli-publication.mjs 的prepare-stage写入schemaVersion 4它同时携带source仓库与 commit和publisher工作流、commit、runId、runAttempt双重身份是后续 Finalize 验证的证据锚点。在 npm 上检查并批准检查与批准命令要求Node.js 22.14.0 或更新、npm 11.15.0 或更新。Stage 工作流使用自己的受评审工具链工作流中固定的 Node.js 版本22.19.0见 release-cli-stage.yml与仓库packageManager钉死的精确 npm 版本根 package.json 当前为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/批准前必须要求包名、版本、dist-tag、provenance 与源仓库和 Stage run 一致将下载的暂存 tarball 的 SHA-256 与工作流构件的.tgz.sha256比对检查文件清单与打包的README.md确认 tarball 属于记录的 Stage run 与源 commit。批准前一刻重新核对 Stage run 记录的实时产品权威set -eu source_commitreplace-with-stage-recorded-commit node scripts/product-release-authority.mjs verify-draft \ v$version $source_commit apache/maka校验器必须成功。若 tag 不存在、被移动、不再位于main上、对应 GitHub Release 不再是稳定 Draft 或已被标记为 prerelease立即停止。该verify-draft命令在 scripts/product-release-authority.mjs 中的实现会检查 tag 的远端 commit 精确匹配、commit 是main的祖先以及 Release 必须是 Draft 且非 prerelease。只批准这一个 stage ID。npm 要求 2FA并在批准过程中把包公开npm stage approve $stage_id --registry https://registry.npmjs.org/同样的评审与批准也可以从 npmjs.com 上包的Staged Packages页面进行。批准后检查公开 tagversion0.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。输入成功的 Stage run ID 与 attempt、成功的 Release build run ID 与 attempt、以及版本对应 release-cli-finalize.yml 的stage_run_id、stage_run_attempt、release_run_id、release_run_attempt、version五个输入。让 inspection job 校验公开 tarball 的字节、校验和、清单、npm 签名、Trusted Publishing provenance 与精确的latestdist-tag。该校验会重新下载 registry 字节见 release-cli-publication.mjs 的fetch-registry同时核对sha256、sha512integrity 与sha1shasum并执行npm audit signatures --json --include-attestations后解析 SLSA provenance v1 语句逐字段核对构建定义、工作流路径、run 身份与源码 commitmatchesReleaseProvenance。当 publication job 在product-releaseEnvironment 等待批准时完成产品清单要求的跨机器验收。批准 Environment。确认工作流把每个实时 Draft 摘要与精确 Release attempt 的发布记录匹配创建并上传Maka-version-attestation.sigstore.json由actions/attest生成 bundle 后重命名发布便利 Release并无需额外手动操作即把稳定 Release 置为 Latest。发布动作由 product-release-authority.mjs 的publish-draft完成先上传 attestation bundle、核对 Draft 资产精确匹配再通过 PATCHdraftfalseprereleasefalsemake_latesttrue一次性发布最后轮询确认 Latest 指向该 tag。检查最终 registry 状态version0.2.0 npm view maka-agent$version version dist.tarball dist.integrity --json npm view maka-agent dist-tags --json最后在每个发布平台安装精确公开版本并完成一次真实 TUI/模型回合在受支持的 Eval 主机上完成至少一个真实实验单元检查 score、usage、cost 与 artifacts。验收证据要求以 产品发布清单 为权威。故障恢复矩阵npm 暂存之前若npm stage publish之前发生瞬时失败可从同一产品 tag 重跑 Stage。若需要修改代码或工作流在main上修复、递增产品版本、创建新产品 tag 与 Draft再暂存新版本。此时尚无 npm 版本被消耗。Stage 工作流失败但 npm 中存在 stage提交是 Stage 工作流的最后一个业务步骤因此响应丢失可能在工作流不成功时仍留下一个 npm stage。不要批准该孤儿 stageFinalize 只接受成功的 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/绝不只凭版本文本拒绝 stage必须把动作绑定到已检查的 stage ID。Stage 成功但评审发现问题拒绝 stage在main上修复问题递增产品版本创建新产品 tag 与 Draft再暂存新版本。不要为了清空暂存区而批准候选。npm 批准成功但 Finalize 失败npm 版本已经不可变不要再次发布或批准它。保留 Stage run ID、attempt、版本以及 Release run ID、attempt、发布记录与构件。若这些字节与 provenance 有效在main上修复 Finalize 校验器并对同一不可变 Stage 与 Release 证据重跑。inspection job 是只读的只有受保护的 publication job 可以执行唯一的 Draft→已发布转换并 attest 其字节。若 npm 身份、构建证据或 Draft 不一致停止并调查不要修改产品 tag 或 GitHub Release 来让校验通过。若发布请求后报告失败先检查精确 Release成功的发布不得重复执行。公开发布版本有缺陷先把受影响的 dist-tag 移回先前已验证的版本known_good0.2.0 npm dist-tag add maka-agent$known_good latest然后只弃用deprecate有缺陷的版本并引导用户到已恢复的 dist-tag它已指向已验证版本bad_version0.2.1 recovery_taglatest npm deprecate maka-agent$bad_version Known issue; install maka-agent$recovery_tag.验证 tag修复缺陷并通过完整的 Stage Finalize 流程发布新版本。不要用npm unpublish作为常规回滚移除不可变的依赖字节可能破坏既有安装也不会恢复受评审的发布链。Nightly 有缺陷时发起一次全新 run 让新的不可变版本推进nightly。若需立即回滚人类包所有者可以把nightly移回先前验证过的 Nightly 版本并只弃用有缺陷的精确版本。绝不让latest指向 Nightly。所有权与紧急恢复GitHub 仓库管理员拥有npm-publicationEnvironment 配置发布维护者负责触发、暂存包检查、npm 2FA 批准与最终验收。npm 包所有者负责 Trusted Publisher、发布访问权限、维护者与 dist-tag 恢复。Trusted Publishing 生效期间至少保留一位启用 2FA 的人类所有者移除当前直接所有者前先加入计划的 npm 组织发布团队与另一位直接人类恢复维护者并验证两条路径。工作流不得获得长效 npm token。若 OIDC、Environment 或信任关系被破坏暂停发布并修复该控制平面而不是用npm publish绕过暂存。npm 账号丢失时使用其账号恢复方法或另一位已验证的包所有者。在建立第二位所有者之前恢复依赖当前所有者的 npm 恢复凭据把完成该所有权跟进视为运营负债。若仓库或 npm 发布者设置意外变更移除或禁用信任关系保留工作流与 npm 审计证据恢复已评审配置并对任何完整性存疑的候选使用新版本。仓库内相关文档npm 源码 RC 预检ASF_NPM_RELEASE.md发布前无需凭据的兼容性检查契约产品发布清单RELEASE_CHECKLIST.mdFinalize 前验收证据的权威要求Desktop Nightly 说明DESKTOP_NIGHTLY.md桌面端 nightly 渠道机制CLI npm 发布中文版本文档的简体中文对照ASF 源发布流程ASF_SOURCE_RELEASE.md源归档发布与投票流程关键实现与校验脚本集中在 scripts/product-nightly.mjs、scripts/release-version.mjs、scripts/release-cli-publication.mjs 与 scripts/product-release-authority.mjs发布控制平面则以 .asf.yaml 与.github/workflows/下四份工作流为权威可供进一步深入阅读。【免费下载链接】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），仅供参考