【免费下载链接】trueforgeThe open-source agent harness - the runtime layer that turns an LLM into a working agent.项目地址https://gitcode.com/gh_mirrors/tr/trueforge点击查看免费下载TrueForge开源 Agent Harness运行时层的发布不止打一个 npm tag那么简单同一套流程要同时产出 4 个 npm 包、1 个 PyPI SDK、2 个容器镜像、1 个 Helm Chart 和 1 个沙箱镜像。本文以仓库根目录的 RELEASING.md 为主体结合 release.yml、release-chart.yml 两个核心工作流以及scripts/prepare-release.mjs、scripts/version.mjs等脚本源码完整还原 TrueForge 的发布拓扑、版本号决策规则、changesets 分支策略与可信发布机制。读完本文你将掌握如何理解并复现一次 dispatch、一次 run、一个结论的发布模型为什么main分支永远停留在0.0.0以及如何手动发布一个 Chart、如何处理403、OIDC fail、chart missing等高频故障。发布矩阵仓库究竟发布哪些产物TrueForge 仓库的发布面覆盖五类产物每一类都有独立的触发器与工作流见下表产物触发器工作流npm 包由父级 Chart 发布时workflow_dispatch触发运行在release-vX.Y.Z分支上main分支只收集 changesets不发布release.ymlPyPItrueforge-sdk与 npm 同一次运行并行 OIDC jobrelease.yml生产镜像Prod image与 npm 同一次运行独立于 pack smoke 阶段release.ymlHelm Chart由release.yml在镜像构建完成后调用或手动 dispatchrelease-chart.yml沙箱镜像 pin PR当scripts/sandbox/**变更时推送到main或手动 dispatchpush-sandbox-image.ymlPR 检查Pull request / merge groupci.yml关键结论main分支只负责聚合 changesets变更集任何发布动作都不发生在main上。真正承载发布的是release-vX.Y.Z分支这一设计保证了未发布的开发内容永远进不了已发布的版本线。版本号体系每个产物都有自己的身份标识发布工程最容易踩的坑就是一个版本号打天下。TrueForge 对每个产物的版本号做了严格划分各字段拥有者互不重叠产物身份标识说明npmtruefoundry/trueforgeSemVerX.Y.Z已发布包的版本真相来源source of truthPyPItrueforge-sdk与truefoundry/trueforge-sdk相同的 SemVer在 Version Packages 步骤同步写入pyproject.tomlChartappVersion构建提交时packages/trueforge/package.json的版本跟随 npm 主包生产镜像根目录 Dockerfile基于源码的 workspace 构建无独立版本号生产镜像 tag{packageVersion}-{shortSha}如0.3.0-abcdef1Chartversiontfy_chart_version输入值原样写入仓库内没有任何代码计算它沙箱镜像sandbox.Dockerfiletag 完整 commit SHA其中Chartversion由调用方决定、仓库原样照写是理解整个发布体系的关键发布方在发布开始前就已经知道oci://tfy.jfrog.io/tfy-helm/trueforge:V与charts/trueforgeV的最终形态不需要在运行中猜测。安装一个已发布的 Chart 只需helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge --version chart-semvernpm 包4 个公开包与 1 个私有包仓库通过 pnpm workspace 管理多个包其中 4 个会发布到 npm1 个只作为构建产物被吞并包源码目录说明truefoundry/trueforge-corepackages/trueforge-core核心库truefoundry/trueforgepackages/trueforge应用 CLItarball 内含dist/_frontend/truefoundry/trueforge-sdkpackages/trueforge-sdkFern 生成禁止手改truefoundry/trueforge-uipackages/trueforge-ui可嵌入的聊天 UIpackages/frontend不发布它的构建产物通过 copy-frontend.mjs 复制进truefoundry/trueforge的 tarball同时workspace:*依赖在发布时会被改写为精确版本号。发布主流程六步走release.yml 同时承载包发布 源码镜像 Chart 发布运行在release-vX.Y.Z分支上。完整流程如下提交 changeset在代码变更的同一个 PR 里添加 changesetpnpm changeset或pnpm change --bump patch --summary … pkg。SDK 重生成会自动通过pnpm changeset:sdk-regen添加truefoundry/trueforge-sdk的 patch changeset——该脚本由 changeset-sdk-regen.sh 实现它会先检查是否存在已指向 SDK 的 pending changeset避免重复堆积文件。合并到mainmain仅累积 changesets。派发分支派发工作流选定要发布的版本VX.Y.Z或X.Y.Z-rc.N创建release-vX.Y.Z分支X.Y.Z为去掉-rc.N后的版本并以tfy_chart_versionV派发本工作流。V完全由调用方决定不必与父级 Chart 自身的版本一致。新 minor 线的首个 cut 从main切出hotfix 线则从refs/tags/vbase切出确保main上未发布的内容不会混入 patch。已存在的分支保持不变、绝不把main合并进来只有 minor 线的第一个 RC会在分支缺失main提交时报错因为从rc.2起分支合法地携带了main没有的版本与 changeset 提交比较结果永远是divergedhotfix 线本来就应当落后于main。版本化并直接提交该次 dispatch 运行scripts/prepare-release.mjs随后执行pnpm run version并把结果直接提交到release-vX.Y.Z分支。pre 模式跟随Vrc进入、稳定版退出。仍停留在0.0.0的公开包会被提升为X.Y.0或X.Y.0-rc.0packages/frontend保持0.0.0。当truefoundry/trueforge-sdk版本移动时scripts/version.mjs 会把该版本镜像写入python/trueforge_sdk/pyproject.toml并重新生成两个 SDK。没有 Version Packages PR一次 dispatch、一次 run、一个结论。同一次运行完成其余一切全部检出第 4 步的提交pack构建/测试与Windows npx smoke作为npm和PyPI的发布闸门。二者仅在changesets/action/select-mode报告publish时运行若该版本线自上次发布以来没有新 changesetselect-mode 报告none这是正常情况而非错误。Resolve image identity读取packages/trueforge/package.json得到appVersion并检查charts/trueforgeVtag 是否已存在。若不存在两个服务端镜像按{appVersion}-{shortSha}构建release-chart.yml 以精确的V发布 Chart若 tag 已存在说明这是一次重跑镜像直接复用Chart 任务补完上次遗留的工作。这条路径完全不咨询 npm。最终 minorX.Y.0无-rc.会开启并合并一个回到main的 back-merge PR删除本版本线已消费的.changeset/*.md并把packages/*/CHANGELOG.md复制回main。没有任何版本字段会移动main永远停在0.0.0。RC 与 hotfix 不做 back-merge。源码透视prepare-release.mjs 做了什么从 scripts/prepare-release.mjs 的实现可以看到步骤 4 的三件事都有明确的脚本支撑校验输入TFY_CHART_VERSION必须匹配^(\d)\.(\d)\.\d(?:-rc\.\d)?$RELEASE_BRANCH必须匹配^release-v\d\.\d\.\d$任一不满足直接抛错。切换 changesets baseBranch把.changeset/config.json的baseBranch改写为发布分支使changeset version计算 CHANGELOG 时以该分支为基准main不被改写。应用 pre 模式依据V是否含-rc.与.changeset/pre.json的当前状态执行pnpm changeset pre enter rc或pnpm changeset pre exit状态一致时保持不动keep。0.0.0 引导bootstrap遍历packages/*把仍为0.0.0的非私有包提升为X.Y.0或X.Y.0-rc.0只替换version字段避免 JSON 重排刷屏 diffpackages/frontend因private: true被跳过。而scripts/version.mjs是pnpm run version的实际入口它先执行pnpm changeset version随后比较 TS SDK 与 Pythonpyproject.toml的版本——只要 SDK 版本移动或 Python 版本与 TS 分叉就同步pyproject.toml、执行pnpm sdk:generateFern 会重新烘焙版本字面量并把生成的 SDK、OpenAPI 快照与pnpm-lock.yaml一并 git add。预发布模式RC 版本的进出仓库通过.changeset/pre.json全局控制预发布模式文件不存在 发布到latestdist-tag目标命令后续进入 RCpnpm changeset pre enter rc提交pre.json并合并版本形如x.y.z-rc.Nrcdist-tag退出 RCpnpm changeset pre exit提交删除并合并下一次发布即发布latest注意pre enter/pre exit本身不会bump 版本或触发发布同一份changeset version中不要把稳定版与 RC 包混在一起。可信发布npm 与 PyPI 的 OIDC 认证发布安全采用 GitHub OIDC 可信发布trusted publishing不设置任何长期令牌。每个公开 npm 包都必须在 npmjs.com 上把本仓库 工作流登记为可信发布者Repositorytruefoundry/trueforgeWorkflowrelease.yml必须精确匹配文件名不绑定 GitHub Environment不要重命名该文件否则 npmjs.com 与 PyPI 上登记的每个包都会失效OIDC 直接 403。同时禁止在 npm 发布 job 上设置NPM_TOKEN/_authToken——它会使 OIDC 失效。只有publish/publish-python两个 job 使用 npm/PyPI OIDCid-token: write镜像 job 也使用id-token: write用于 JFrog 登录。发布时附加 npm provenance发布 job 上的NPM_CONFIG_PROVENANCE且每个公开包的publishConfig.provenance: true在 npmjs.com 上公开证明源码仓库与提交。PyPI的trueforge-sdk复用同一工作流文件Repository 与 Workflow 相同、无 Environment 名首次需在 PyPI 创建项目或发布首个版本然后在第一次 OIDC 上传成功前登记 pending/trusted publisher。导入名与pyproject.toml中的名字保持trueforge_sdk上传所用安装用pip install trueforge-sdk。release.yml 中publish与publish-python两个 job 的注释直接印证了这一策略PyPI 是版本一旦占用永不复用的仓库所以两个不可逆的发布 job 都挂在resolve-image上作为否决项veto避免出现npm 已发、镜像和 Chart 却没有对应版本的错位。本地验证不发布也能跑通整条链路pnpm clean pnpm build pnpm standalone:start # 或在 packages/trueforge-core / packages/trueforge 内执行 pnpm pack对应脚本可在根 package.json 中查到standalone:start以STANDALONEtrue NODE_ENVproduction启动truefoundry/trueforge的生产构建。若想在不触碰远端的情况下演练流水线release.yml还提供了dry_run输入跳过 npm、PyPI、镜像、git tag、OCI push 与 back-merge但仍会向发布分支提交版本下游 job 需要检出该提交因此需派发到愿意丢弃的临时release-v*分支上。故障排查手册RELEASING.md 给出了发布中最常遇到的故障及定位Nothing was versioned——发布分支上没有.changeset/*.md。这不是错误Chart 仍会按tfy_chart_version发布。应在下一次切线前在main上补充 changeset。Publish wants a tag——RC 需要rcdist-tagpre.json存在时自动设置。403——版本已在 npm 上或可信发布者配置不匹配文件名必须是release.yml。OIDC fail——需要 pnpm ≥ 11.0.7移除 registry 的_authToken。Missingdist/_frontend/index.html——根目录pnpm build必须先构建frontend否则打出的 tarball 只有 API 没有 UIrelease.yml 的 pack job 用test -f packages/trueforge/dist/_frontend/index.html强制校验。SDK not regenerated——仅在truefoundry/trueforge-sdk版本移动时触发scripts/version.mjs需要 Docker该路径同时把版本镜像进python/trueforge_sdk。PyPI 403 / invalid-publisher——为trueforge-sdk登记绑定release.yml的可信发布者项目不存在时先创建。Prod image / chart missing after package publish——在发布分支上以相同的tfy_chart_version重跑Version or publish packages每一步都是幂等的或为已存在于镜像仓库的镜像补发 Chartgh workflow run release-chart.yml --ref release-vX.Y.Z \ -f branchrelease-vX.Y.Z \ -f chart_versionX.Y.Z \ -f app_versionX.Y.Z \ -f image_tagX.Y.Z-sha镜像与 Helm Chart 的发布拓扑RELEASING.md 用一张 ASCII 图完整刻画了从父级 Chart 发布到 back-merge 的调用链这里保留原文拓扑并对照两个工作流源码展开parent chart release V → branch release-vX.Y.Z (from main for a new minor; from refs/tags/vbase for a hotfix; fail only on the FIRST rc if an existing minor branch is missing commits from main) → workflow_dispatch release.yml --ref release-vX.Y.Z -f tfy_chart_versionV → prepare pre mode 0.0.0 bootstrap → changeset version, commit straight to release-vX.Y.Z → select-mode: publish | none → (publish) pack smoke → npm | PyPI → resolve image identity; charts/trueforgeV missing? yes → build both images X.Y.Z-shortSha no → re-run: reuse the tagged commits image → release-chart.yml (branch, chart_versionV, app_version, image_tag) → helm lint / package → commit Chart.yaml values.yaml to that branch (skip if unchanged) → tag charts/trueforgeV (annotated) vV (lightweight) on that commit (no-op if already present at the same sha) → helm push OCI (skip if V is already in the registry) → (V is X.Y.0 and not an rc) back-merge PR into main: delete the consumed .changeset/*.md, take packages/*/CHANGELOG.md manual chart-only (image already in the registry) → workflow_dispatch release-chart.yml --ref release-branch -f branchrelease-branch -f chart_versionX.Y.Z (empty app_version / image_tag keep Chart.yaml / values.yaml)对照源码可以看到几个值得注意的实现细节resolve-imagejob 用gh api repos/…/git/matching-refs/tags/TAG判断charts/trueforgeV是否存在精确过滤.ref字段而不是git ls-remote——因为 checkout 使用了persist-credentials: false返回0则输出imagebuild否则输出imageskip并清空app_version/image_tag让 Chart 工作流沿用分支上已有的值。双镜像同 tag 不同仓库公开镜像基于 Dockerfile 的公开 base保持可再分发加固镜像使用 Chainguard 私有 base许可禁止公开只推送 TrueFoundry SaaS 消费的私有仓库见 release.yml。release-chartjob 通过needs: [resolve-image, build-image-public, build-image-private]且显式接受skipped结果保证镜像 job 合法跳过时 Chart 仍能发布。两个 Dockerfile 的分工文件角色Dockerfile基于源码构建。用于生产 Helm、docker-compose.yml、RailwayDockerfile.npm旧的 npm-install 镜像APP_VERSION取自镜像仓库镜像内容 包发布提交时的整个 workspace。ChartappVersion取自该提交的packages/trueforge/package.json版本镜像 tag 使用peeled commit SHAgit rev-parse HEAD而非 annotated tag 对象。Dockerfile 是一个 6 阶段的多阶段构建其设计意图值得展开store阶段用pnpm fetch仅凭 lockfile 填充/pnpm/store并删除虚拟 store使依赖下载层在只改package.json/脚本时保持缓存命中workspace阶段复制所有包 manifest 与根构建脚本builder与frontend-builder两个并行阶段分别构建服务端与前端UI 构建产物最终落在packages/trueforge/dist/_frontend与 npm tarball 路径一致prod-deps阶段以--offline --prod生成无开发工具的纯生产依赖树runner阶段FROM ${RUNTIME_BASE_IMAGE}重新起底避免把构建工具链带进运行镜像以 uid 10001 非 root 运行兼容node:24-slimgroupadd与加固 baseBusyBoxaddgroup两种环境并清空 ENTRYPOINT 使 CMD 作为完整命令执行。镜像 base 均为构建参数BUILD_BASE_IMAGE/RUNTIME_BASE_IMAGE本地/贡献者构建停留在公开的node:24-slim发布工作流则用私有加固镜像覆盖builder:node:24-devruntime:node:24。发布 Helm Chart输入与幂等语义release-chart.yml 是纯workflow_callworkflow_dispatch双入口工作流由release.yml在镜像构建后调用也可手动派发。--ref决定 GitHub 运行哪个工作流文件branch是接收Chart.yaml/values.yaml提交的 git 分支。手动派发的输入如下输入默认值仅手动派发时含义branchmain接收 Chart 提交的分支chart_version无——必填原样写入 Chart.yaml 的versionapp_version该分支 Chart.yaml 的appVersion写入 Chart.yamlappVersionimage_tag该分支values.yaml的image.tag已存在的镜像仓库 tag写入image.tag执行顺序固定先把version/appVersion/image.tag写到当前origin/branch然后 lint、package、检查镜像仓库、提交这些文件到该分支、在提交上打charts/trueforgechartVersiontag最后推送到 OCI。分支移动时提交会重放到origin/branch上。每一步都是幂等的元数据无变化则跳过提交tag 已指向同一提交是 no-opChart 版本已在镜像仓库则跳过 push。唯一的硬失败是 tag 已存在于不同的提交——同一个 Chart 版本不能携带两份不同的内容。手动发布的两种典型命令gh workflow run release-chart.yml --ref main -f branchmain -f chart_version0.3.1 gh workflow run release-chart.yml --ref main \ -f branchmain \ -f chart_version0.3.0-rc.0 \ -f app_version0.3.0-rc.0 \ -f image_tag0.3.0-rc.0-abcdef1Chart 版本就是chart_version输入的原样照抄仓库内没有任何派生逻辑appVersion跟随truefoundry/trueforge与镜像 tag 前缀——它们三个字段、三个所有者。值得注意的是 tag 体系本身也是双轨的charts/trueforgeV是 annotated tag其唯一消费方在解析 ref 时会解引用 tag 对象vV是 lightweight tag发布线的通用标记供兄弟仓库按git/matching-refs/tags/vmajor.minor.泛化解析避免每个仓库写死代码。代码注释还提醒仓库遗留的v0.1.x死 tag 不会与新发布线冲突但绝不要在 0.1 线上派发chart_version。Devtest 与持续部署deploy-devtest.yml 把当前mainSHA 固定到truefoundry/trueforge-devtest-deployment环境该环境基于源码构建。密钥只通过secretKeyRef注入明文永不进 git。内置 Chart 依赖Postgres / Redis 与镜像镜像Chart 可选捆绑 Bitnami 的 Postgres/Redis 子 chart由Chart.lock固定版本发布时执行helm dependency build。可在 Chart.yaml 中看到依赖声明postgresql.enabled/redis.enabled作为 condition关闭方式为postgresql.enabledfalse/redis.enabledfalse改用externalPostgres/externalRedis。由于 Bitnami 把带版本号的镜像迁移到了docker.io/bitnamilegacy子 chart 的镜像需要镜像到 TrueFoundry 的 JFrog 仓库values.yaml 指向镜像每次 pin 一次for img in \ postgresql:17.6.0-debian-12-r4 \ redis:8.2.1-debian-12-r0; do crane copy docker.io/bitnamilegacy/${img} tfy.jfrog.io/tfy-mirror/bitnamilegacy/${img} done升级流程修改Chart.yaml依赖 →pnpm chart:deps→ 更新values.yaml镜像 tag → 执行镜像镜像。本地验证 Chart仓库根 package.json 提供了完整的本地验证脚本链与 release-chart.yml 中的 CI 步骤一一对应pnpm chart:deps # helm dependency build charts/trueforge pnpm chart:lint # helm lint charts/trueforge --values charts/trueforge/ci/lint-values.yaml pnpm chart:template # helm template trueforge charts/trueforge --values charts/trueforge/ci/lint-values.yaml pnpm chart:package # helm package charts/trueforge --destination dist其中lint与template都使用了 ci/lint-values.yaml含global.security.allowInsecureImages: true等 CI 专用值用于规避 Bitnami 子 chart 的镜像守卫保证本地验证与 CI 行为一致。结语一套可复用的仓库即流水线发布模式TrueForge 的发布工程把版本决策权与发布执行权彻底分离调用方决定V仓库照写 Chart 版本并自证镜像身份main只收集 changesets、永远0.0.0发布线release-vX.Y.Z上的一切步骤幂等可重跑npm/PyPI 全部走 OIDC 可信发布无任何长期令牌。这套设计不仅服务于 TrueForge 自身的多产物协同发布也为包 SDK 镜像 Chart四类产物同源发布的项目提供了一个完整、可对照源码逐行核验的工程范本——从 release.yml、release-chart.yml 到 prepare-release.mjs、version.mjs每一步都有脚本与注释佐证可以直接迁移到同类仓库。赞分享【免费下载链接】trueforgeThe open-source agent harness - the runtime layer that turns an LLM into a working agent.项目地址https://gitcode.com/gh_mirrors/tr/trueforge点击查看免费下载相关推荐ExternalDNS 发布流程全指南镜像发布、版本规范与 Helm Chart 发布ExternalDNS 发布流程全指南镜像发布、版本规范与 Helm Chart 发布 本篇技术指南以 ExternalDNS 项目官方发布文档为主体结合仓云原生FastUI包管理npm与PyPI的发布流程FastUI包管理npm与PyPI的发布流程 引言多包协同的发布挑战 在现代前端开发中包管理是项目成功的关键环节。FastUI作为一个创新的Python后端前端Web框架UI组件使用Helm Chart Releaser Action自动化Helm图表发布流程使用Helm Chart Releaser Action自动化Helm图表发布流程 项目介绍 Helm Chart Releaser Action https:上一篇Nix 二进制缓存签名密钥对生成指南nix-store --generate-binary-cache-key 详解下一篇突破平面限制howler.js音频空间定位与距离衰减算法深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考