Trigger.dev SDK 公共包修改规范：Changesets 发布流程、版本策略与 @trigger.dev/core 子路径导入指南

AI Agent后端任务调度开发工具可观测性AI 应用【免费下载链接】trigger.devTrigger.dev – build and deploy durable AI agents and workflows项目地址https://gitcode.com/gh_mirrors/tr/trigger.dev点击查看免费下载本篇指南围绕仓库内的 .claude/rules/sdk-packages.md 规则展开它约束着 Trigger.dev 所有packages/目录下公开 SDK 包的每次改动从何时必须写 changeset、版本号默认与升级边界到trigger.dev/core必须使用子路径导入、rules/与skills/目录的治理边界再到用hello-world项目验证改动的实操流程。读完本文你将掌握在 Trigger.dev monorepo 中安全修改并发布公共包的完整工作流以及这些规则背后的源码与配置依据。规则适用范围一切面向用户的packages/**改动该规则通过 frontmatter 中的paths字段声明了自己的作用域--- paths: - packages/** ---也就是说只要改动落在packages/目录下规则就会在 Claude Code 等 Agent 工作流中自动加载。当前仓库中该目录包含以下公开包见 packages/包目录说明cli-v3trigger.devCLI开发、部署、环境变量、登录等命令core横跨 SDK 与平台的核心代码trigger.dev/coreplugins插件包trigger.dev/plugins已加入 changesets 的 ignore 列表pythonPython SDK 相关工具包react-hooksReact Hooks 包redis-workerRedis Worker 包内部消费不独立发布rsc、schema-to-json、trigger-sdk其他公开/辅助包这些包会发布到 npm 并被用户直接npm install引用因此规则的第一句话就点明了核心立场Changes topackages/are customer-facing面向客户。任何改动都可能影响线上用户的 SDK 行为所以不能用内部重构的心态对待。强制 Changesetpnpm run changeset:add规则要求对packages/的任何改动都必须添加 changeset命令为pnpm run changeset:add该命令是仓库根 package.json 中对changesetCLI 的脚本封装changeset:add: changeset运行后会以交互方式引导你选择受影响的包、确定版本升级类型并撰写发布说明。关于什么时候加 changeset仓库的 CHANGESETS.md 给出了更细的补充changeset 是面向用户的发布说明user-facing release notes而不是每一次改动的流水账。仅当改动是用户能感知、会据此行动的变化时才需要添加纯内部重构refactors、事务性改动chores以及不被独立消费的包例如trigger.dev/redis-worker可以跳过。想查看精确历史的人应该去读 commit。配套的配置.changeset/config.json根目录的 .changeset/config.json 定义了整个发布机制的骨架几个关键字段值得注意fixed: [[trigger.dev/*, trigger.dev]]所有trigger.dev/*包与trigger.devCLI 被固定为一组版本号必须同步升级避免 SDK 内部互相依赖时出现版本错位access: public发布到公开 npm registrybaseBranch: main基于main分支计算版本与生成发布 PRignore: [webapp, supervisor, trigger.dev/plugins]apps/下的服务端应用不参与 changesets 版本管理trigger.dev/plugins也被显式忽略changelog使用remix-run/changelog-github生成 changelog 并关联到triggerdotdev/trigger.dev仓库。发布流水线如何被触发按照 CHANGESETS.md 的说明整个发布链路是自动化的在main分支的提交中新增 changeset 后changesets-pr.ymlworkflow 会自动运行创建一个执行pnpm run changeset:version的版本发布 PR该发布 PR 的正文会被自动增强合并去重后的包变更与.server-changes/条目摘要版本 PR 合并进main后release.ymlworkflow 会自动构建、把包发布到 npm并生成统一的 GitHub Release。因此规则强调在包含改动的同一个 commit 里就加上 changeset这是让 CI 流水线正常工作的最佳实践。版本号策略默认 patch升级必须走审批规则的版本边界非常清晰默认选patch修复性变更如 bugfixminor新增向后兼容功能必须获得 maintainer 批准major破坏性变更绝不可以在没有明确批准的情况下选择。这背后的原因不难从 changesets 的机制理解由于fixed配置把所有trigger.dev/*包绑定在一起任何一个包选择major都会让整个 SDK 家族发生一次破坏性大版本跳跃直接影响所有下游用户。所以版本号选择本质上是影响面审批改动虽小但发布边界必须由维护者把关。在运行pnpm run changeset:add时若不确定该选哪个等级先向维护者确认而不是自行决定。trigger.dev/core永远不要导入根入口规则中最具技术含量的一条是trigger.dev/coreNever import the root. Always use subpath imports (e.g.,trigger.dev/core/v3).也就是说在 SDK 或平台代码中禁止写// ❌ 禁止导入根入口 import { something } from trigger.dev/core;必须写成子路径形式// ✅ 正确子路径导入 import { task } from trigger.dev/core/v3; import { tracer } from trigger.dev/core/v3/tracer; import { retry } from trigger.dev/core/v3/utils/retries;为什么exports 映射给出了答案看 packages/core/package.json 的exports字段即可理解trigger.dev/core根入口只导出极少的内容——src/index.ts 仅转发types.js、utils.js、schemas/json.js与version.js四个模块而真正的 SDK 能力全部以具名子路径形式暴露trigger.dev/core/v3→src/v3/index.tsSDK 主入口trigger.dev/core/v3/tracer→src/v3/tracer.tstrigger.dev/core/v3/build、trigger.dev/core/v3/appstrigger.dev/core/v3/errors、trigger.dev/core/v3/logger-apitrigger.dev/core/v3/otel、trigger.dev/core/v3/schemastrigger.dev/core/v3/utils/durations、trigger.dev/core/v3/utils/retries、trigger.dev/core/v3/utils/gitBranch、trigger.dev/core/v3/utils/ioSerialization等工具子路径trigger.dev/core/v3/workers、trigger.dev/core/v3/machines、trigger.dev/core/v3/runEngineWorker、trigger.dev/core/v3/serverOnly、trigger.dev/core/v3/isomorphictrigger.dev/core/v3/test测试辅助同一份清单也以typesVersions形式为 TypeScript 提供了对应的类型映射。这种根最小化 子路径具名化的设计至少带来三个收益按需加载、减小打包体积使用方只打包自己真正 import 的模块避免把整个 core 拖进 bundle显式的环境边界/v3/serverOnly与/v3/isomorphic等子路径明确区分了只能在服务端使用与可在多端复用的代码混用根入口容易破坏这一边界面向未来的稳定契约子路径是包对外承诺的公共 API改动它们会被exports与typesVersions双重约束防止隐式破坏。因此在修改trigger.dev/core时新增或调整功能应当落在对应的src/v3/...子模块中并通过在package.json的tshy.exports中登记新子路径来正式公开它。受保护区rules/与.claude/skills/trigger-dev-tasks/规则还划定了两块禁区Do NOT updaterules/or.claude/skills/trigger-dev-tasks/unless explicitly asked. These are maintained in separate dedicated passes.这两处目录根目录的 rules/ 与 .claude/skills/trigger-dev-tasks/分别承载着 SDK 的版本化迁移规则和 Agent 开发任务技能库属于由专门流程单独维护的资产。即使你的 PR 涉及 packages 改动也不应顺手修改这些文件——除非任务被明确要求。这保证了规则与技能库的变更可审计、可追溯不会因为日常开发被悄悄改动。用 hello-world 项目验证每次改动规则对测试给出了明确指令Test changes using thehello-worldproject in thetriggerdotdev/referencesrepo.即任何对 SDK 包的行为改动最终都要在一个独立的references仓库中的hello-world项目上做真实验证。这与仓库内使用测试项目验证的做法一致例如根目录的 internal-test-projects.mts。实操建议在本地 monorepo 完成包修改后通过pnpmworkspace 或file:依赖把改动指向hello-world项目运行trigger.dev dev或直接执行任务确认 SDK 在真实运行时环境含构建、打包、任务注册与执行下行为正确尤其要关注trigger.dev/core子路径改动是否影响现有 import 方。从源码结构看这种方式能覆盖单测难以触达的发布后集成场景——因为包的 exports 契约、打包产物与运行时行为只有通过外部消费项目才能得到完整验证。相关约定纯服务端改动走.server-changes/这条 SDK 规则还有一条重要的姊妹约定。当 PR只改服务端apps/webapp/、apps/supervisor/等且不涉及需要 changeset 的包改动时按 .claude/rules/server-apps.md 的说明应添加一个.server-changes/文件而非 changesetcat .server-changes/descriptive-name.md EOF --- area: webapp type: fix --- Fix pages occasionally loading unstyled during deploys. The dashboard now recovers automatically. EOF其中area只能是webapp或supervisortype只能是feature、fix、improvement、breaking。而对于同时改动包与服务端的混合 PR规则约定只要包改动需要 changeset就由 changeset 一并覆盖无需再写.server-changes/反之若包改动是内部性的、不需要 changeset而服务端改动面向用户则仍要补一个.server-changes/文件。完整决策可参考 CHANGESETS.md 中的对照表。总结一条规则三层保障.claude/rules/sdk-packages.md虽然只有六行却把 Trigger.dev 公共 SDK 的开发纪律压缩成了三层保障发布纪律packages/的任何改动都强制写 changeset配合fixed版本组与 CI 流水线保证 npm 发布可追溯、版本一致版本边界默认 patch、minor 需批准、major 绝不擅自动把破坏性变更的决策权收回到维护者手中工程约束trigger.dev/core只允许子路径导入、rules/与skills/受保护、改动必须经hello-world项目实测从代码边界到测试验证全方位保护消费者。对希望在 Trigger.dev monorepo 中贡献代码的开发者而言遵守这条规则就是对自己改动的用户影响面负责。赞分享AI Agent后端任务调度开发工具可观测性AI 应用【免费下载链接】trigger.devTrigger.dev – build and deploy durable AI agents and workflows项目地址https://gitcode.com/gh_mirrors/tr/trigger.dev点击查看免费下载相关推荐Perfetto SDK 发布流程全解版本策略、发布分支、Tag 规范与预编译产物打包Perfetto SDK 发布流程全解版本策略、发布分支、Tag 规范与预编译产物打包 本文基于 Perfetto 仓库中的官方贡献指南 docs/contr可观测性后端开发工具前端数据可视化Open edX 平台 sys.path 修改移除决策导入路径规范化与旧式导入迁移指南Open edX 平台 sys.path 修改移除决策导入路径规范化与旧式导入迁移指南 导读 本篇文章围绕 Open edX 核心仓库 openedx pla后端教育BFS-Best-Face-Swap版本对比V1到V5哪个最适合你的换脸需求BFS Best Face Swap版本对比V1到V5哪个最适合你的换脸需求 BFSBest Face Swap是一系列专为Qwen Image Edi计算机视觉AI 应用大模型上一篇终极指南Weaviate向量数据库的数据序列化与反序列化技术下一篇ZLUDA指令选择目标架构适配创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考