workerd 基于 OpenCode 的 changelog 生成工作流从分支提交到 PR 描述与发布说明【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerdworkerdCloudflare Workers 的 JavaScript/Wasm 运行时在其仓库中通过 .opencode/commands/changelog.md 定义了一个面向 AI 编码 Agent 的changelog子任务命令用于把当前分支的提交历史自动归纳为可供 PR 描述或发布说明直接粘贴的 changelog。本文以该命令文档为骨架逐条拆解其六个执行步骤、两类必载技能commit-categories与markdown-drafts、输出模板并结合仓库中的兼容性标志compat flags、自动门autogates与发布机制源码说明这套工作流为何能产出事实准确、分类清晰、可直接复用的变更总结。命令定位一个子任务式的分支变更总结器changelog命令在仓库的 OpenCode 配置中声明为--- description: Summarize current branch changes for a PR description or release note subtask: true ---subtask: true表示它是被编排在更大任务如帮我开个 PR准备发布说明中的子任务输出会被复制到 PR 或发布说明中命令支持$ARGUMENTS参数例如指定基准分支base、指定输出风格for release notes、for PR。它解决的核心问题很实际workerd 是一个大型 C/Rust/TypeScript 混合仓库单次合并可能横跨 src/workerd/api、src/rust、types 等多个子系统靠人眼扫git log归纳既慢又容易漏掉破坏性变更。该命令把读提交 → 分门别类 → 起草 → 按格式输出固化成可重复的 Agent 流程。六步工作流全解第 1 步确定分支与基准base命令首先运行git log --oneline origin/main..HEAD语义是列出origin/main之后、当前HEAD之上的所有提交即当前分支独有的变更若该范围没有任何提交回退尝试main..HEAD若用户在$ARGUMENTS中指定了其他基准如baserelease/2026-09则使用用户指定的基准。这一先决步骤决定了 changelog 的边界只总结分支真正引入的改动避免把上游历史混入。第 2 步读取完整 diff 了解实际改动git diff origin/main...HEAD --stat注意这里是三点式origin/main...HEAD三点 diff 以两个分支的合并基为起点与第 1 步的两点式origin/main..HEAD提交范围配合使用。--stat给出每个文件的增删行统计Agent 借此判断改动规模与影响面——例如某个改动只碰了 types/defines 下的.d.ts那它大概率是类型层变更而非运行时行为变更。第 3 步读取提交信息获取上下文git log origin/main..HEAD --format%h %s%n%n%b该格式逐条输出短哈希、主题行subject与正文body用于理解每个提交的意图。命令文档特别强调按逻辑变更logical change合并条目而不是按提交commit逐条罗列——一个功能的实现提交与其后的修复提交fixup应合并为一条。第 4 步按路径模式分类提交这是整个工作流的规则核心。命令要求必须先加载commit-categories技能定义于 .opencode/skills/commit-categories/SKILL.md再依据其路径模式表为每个提交归类。该表基于 workerd 的真实目录结构制定类别路径模式APIsrc/workerd/api/排除node/与pyodide/Node.js compatsrc/workerd/api/node/、src/node/Pythonsrc/workerd/api/pyodide/、src/pyodide/Rustsrc/rust/Cloudflare APIssrc/cloudflare/I/Osrc/workerd/io/JSGsrc/workerd/jsg/Serversrc/workerd/server/Buildbuild/、MODULE.bazel、BUILD.bazelTypestypes/Docs / Config文档、Agent/工具配置、.md文件Tests仅改动测试文件Other上述未覆盖的其余内容分类的具体操作是对每个提交执行git diff-tree --no-commit-id --name-only -r hash列出其改动文件与上表匹配将提交归入改动占比最大的主类别跨越多个类别的提交归入主类别不重复列。横切标注Cross-cutting calloutscompat flags 与 autogates除主类别外该技能还定义了两个额外标注区不是主类别而是伴随出现的高可见性章节一旦提交触及相关文件就必须单独列出标注区触发条件New/Updated Compat Flags改动 src/workerd/io/compatibility-date.capnp或代码中新增compatibilityFlags引用New/Updated Autogates改动 src/workerd/util/autogate.h 中的WORKERD_AUTOGATES宏或新增 autogate 注册这些标注绝不能被埋在普通类别条目里——它们是评审者和发布说明读者需要第一眼看到的高风险项。这一设计直接呼应 workerd 的运行时特性新增兼容性标志会改变线上行为而 autogate 是灰度开关漏报会造成发布事故。第 5 步起草总结对每个有变更的类别每个逻辑变更一条 bullet按逻辑合并不按提交数每条 bullet 以动词开头Add、Fix、Update、Remove、Refactor附上最重要的文件引用使用仓库相对路径显著标注破坏性变更breaking changes、新增 compat flags、新增 autogates。第 6 步按固定模板输出命令定义了标准输出结构## Summary 1-2 句分支目的概述 ## Changes ### Category - change description ## Breaking Changes 如有则保留该节否则整节省略 ## Testing 简要说明新增或修改了哪些测试模板的要点Breaking Changes节无内容即整节省略避免空壳节Testing节要求给出测试改动概览——这与仓库的测试文化一致参见 samples/unit-tests、src/workerd/api 下大量.wd-test文件若用户参数要求特定风格则调整语气PR 描述更详细发布说明面向用户更简洁。必须加载的配套技能commit-categories分类规则的事实来源该技能.opencode/skills/commit-categories/SKILL.md本身是changelog 与 whats new 总结的分类规范其路径模式表保证了不同 Agent 会话产出一致且可复现的分类结果。它还给出了分类操作的顺序逐提交列文件 → 匹配路径 → 归主类别 → 检查横切标注 → 输出时省略空类别。也就是说输出模板里的Category节并非固定五个而是有内容才出现。markdown-drafts原样保留 Markdown 源码命令强调输出将被复制进 PR 或发布说明因此必须加载markdown-drafts技能.opencode/skills/markdown-drafts/SKILL.md遵循其渲染规则。该技能的核心约束是面向外部系统GitHub PR、Jira、Wiki、RFC、设计文档等的草稿一律使用标准 Markdown 语法#/##标题、-/*列表、围栏代码块、行内代码、表格、引用块、---分隔线、任务清单由于聊天界面会渲染并吞掉原始 Markdown 符号整个草稿必须包在无语言标签的三反引号代码围栏内确保用户复制到的是原始 Markdown 源码而非被 UI 处理后的纯文本明确禁止全大写标题、下划线式人工排版、HTML 标签除非目标系统必需、未经要求添加 emoji、以及三连词式 AI 套话和空洞开头结尾——要求直击要点。这一点解释了 changelog 命令最后一行IMPORTANT提示的由来它是为了保证 Agent 输出在复制粘贴过程中格式不丢失。源码佐证为什么这些规则如此设计compat flags 与compatibility-date.capnp分类技能把 src/workerd/io/compatibility-date.capnp 视为新增兼容性标志的触发文件并非偶然。该 capnp 文件以annotation compatEnableFlag$compatEnableFlag(...)形式逐条登记运行时特性开关例如$compatEnableFlag(formdata_parser_supports_files)、$compatEnableFlag(fetch_refuses_unknown_protocols)、$compatEnableFlag(streams_enable_constructors)等src/workerd/io/compatibility-date.capnp#L81-L120。每个 flag 的启用日期、disable 名、experimental 标注都集中在此因此改动该文件是识别新 flag 的最可靠信号。仓库还配套了 .opencode/commands/compat-flag.md 命令它借助compat-date-at工具按启用日期反查某天的 flags 集合并在 C 中搜索 getter如getTextDecoderReplaceSurrogates()定位使用点、在.wd-test与测试.js中定位测试用例。autogates 与autogate.h宏同样分类技能把 src/workerd/util/autogate.h 作为新增 autogate的触发文件。从源码看所有 autogate 都由WORKERD_AUTOGATES(V)宏统一登记src/workerd/util/autogate.h#L69当前注册项包括TEST_WORKERD、V8_FAST_API、STREAMING_TAIL_WORKER、PER_ISOLATE_JAVASCRIPT_BOOTSTRAP、DURABLE_OBJECT_RETRIES_FETCH、NODEJS_URL_RUST、NODEJS_EXCEPTIONS_RUST、RPC_EXTERNALS_HYDRATION等每个条目旁都有/* ... */注释说明用途与回滚策略。配套的 .opencode/commands/autogate.md 命令进一步说明AutogateKey枚举、配置字符串与getAutogateKeys()迭代列表都由该宏生成、不会失同步配置字符串由枚举名自动推导——SCREAMING_SNAKE_CASE转小写 kebab-case 并加workerd-autogate-前缀例如AutogateKey::MY_NEW_FEATURE对应workerd-autogate-my-new-feature运行时通过util::Autogate::isEnabled(AutogateKey::NAME)检查测试则在.wd-test的autogates [workerd-autogate-kebab-name]配置中启用。autogate 是临时性灰度开关按 src/workerd/util/autogate.h#L33-L57 的注释功能全面铺开后应从宏中移除并只保留新代码路径——因此 changelog 必须把 autogate 的新增/修改作为高可见性标注。发布机制changelog 的最终消费场景changelog 输出之所以分为PR 描述与发布说明两种语气是因为 workerd 的发布流程高度自动化。RELEASE.md 说明workerd与workers-types的主版本号分别为1与4次版本号取 src/workerd/io/release-version.txt 中记录的日期当前为2026-09-08每当该日期变更CI 自动产出 linux-64、linux-arm64、darwin-64、darwin-arm64、windows-64 五个平台的二进制并自动发布类型包。也就是说一个 for release notes 风格的 changelog 会直接服务于下一轮自动化发布其面向用户、简明扼要、突出破坏性变更的约束是发布实际需求而非形式要求。与相邻命令的分工changelog 并非仓库中唯一的提交总结命令理解它与兄弟命令的边界有助于正确使用whats-new.opencode/commands/whats-new.md面向远端 main 分支按数量10、日期since 2026-02-01、时间范围today、this week、this month拉取近期提交同样强制加载commit-categories技能分类但输出为每条提交一行的新闻式摘要hash summary — author并单独检查当前分支与 main 的冲突面changelog面向当前分支按逻辑变更合并条目输出为可粘贴的 PR/发布说明模板。两者共用同一套分类技能保证了仓库内所有 Agent 生成的变更摘要口径一致。实战示例把工作流串起来假设当前分支新增了一个 I/O 层能力并附带 compat flag按命令的完整流程产出如下确定范围git log --oneline origin/main..HEAD返回 3 个提交实现 修复 测试读 diffgit diff origin/main...HEAD --stat显示主要改动集中在src/workerd/io/读提交信息确认意图分类加载commit-categories技能匹配路径表归入I/O同时检出compatibility-date.capnp被修改 → 命中New/Updated Compat Flags横切标注起草按动词开头写 bullet附文件引用输出套用模板并在主类别之后追加横切标注节最后整个草稿包进无语言标签的三反引号代码围栏保证原始 Markdown 可被原样复制。最终产出形态## Summary 在 I/O 层新增 X 能力并引入配套的 compatibility flag。 ## Changes ### I/O - Add X 能力支持src/workerd/io/... ### Tests - Add X 相关 .wd-test 用例 ## Compat Flags - x_feature: 新增启用日期 2026-10-01src/workerd/io/compatibility-date.capnp ## Testing 新增/修改 N 个 .wd-test 用例覆盖默认行为与 flag 启用后的行为。小结workerd 仓库的changelog命令把分支变更 → 结构化 changelog定义为可复现的 Agent 子任务git命令负责取数与定界commit-categories技能以真实目录结构为纲提供分类规则并强制标注 compat flags 与 autogatesmarkdown-drafts技能保证输出以原始 Markdown 形态交付最终落到 PR 描述或自动化发布使用的发布说明。对希望在大型混合语言仓库中用 AI 维护变更记录的开发者而言这套命令 强制技能 固定模板的组合本身就是一份可移植的工作流范式。【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 workerd 基于 OpenCode 的 changelog 生成工作流：从分支提交到 PR 描述与发布说明
workerd 基于 OpenCode 的 changelog 生成工作流从分支提交到 PR 描述与发布说明【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerdworkerdCloudflare Workers 的 JavaScript/Wasm 运行时在其仓库中通过 .opencode/commands/changelog.md 定义了一个面向 AI 编码 Agent 的changelog子任务命令用于把当前分支的提交历史自动归纳为可供 PR 描述或发布说明直接粘贴的 changelog。本文以该命令文档为骨架逐条拆解其六个执行步骤、两类必载技能commit-categories与markdown-drafts、输出模板并结合仓库中的兼容性标志compat flags、自动门autogates与发布机制源码说明这套工作流为何能产出事实准确、分类清晰、可直接复用的变更总结。命令定位一个子任务式的分支变更总结器changelog命令在仓库的 OpenCode 配置中声明为--- description: Summarize current branch changes for a PR description or release note subtask: true ---subtask: true表示它是被编排在更大任务如帮我开个 PR准备发布说明中的子任务输出会被复制到 PR 或发布说明中命令支持$ARGUMENTS参数例如指定基准分支base、指定输出风格for release notes、for PR。它解决的核心问题很实际workerd 是一个大型 C/Rust/TypeScript 混合仓库单次合并可能横跨 src/workerd/api、src/rust、types 等多个子系统靠人眼扫git log归纳既慢又容易漏掉破坏性变更。该命令把读提交 → 分门别类 → 起草 → 按格式输出固化成可重复的 Agent 流程。六步工作流全解第 1 步确定分支与基准base命令首先运行git log --oneline origin/main..HEAD语义是列出origin/main之后、当前HEAD之上的所有提交即当前分支独有的变更若该范围没有任何提交回退尝试main..HEAD若用户在$ARGUMENTS中指定了其他基准如baserelease/2026-09则使用用户指定的基准。这一先决步骤决定了 changelog 的边界只总结分支真正引入的改动避免把上游历史混入。第 2 步读取完整 diff 了解实际改动git diff origin/main...HEAD --stat注意这里是三点式origin/main...HEAD三点 diff 以两个分支的合并基为起点与第 1 步的两点式origin/main..HEAD提交范围配合使用。--stat给出每个文件的增删行统计Agent 借此判断改动规模与影响面——例如某个改动只碰了 types/defines 下的.d.ts那它大概率是类型层变更而非运行时行为变更。第 3 步读取提交信息获取上下文git log origin/main..HEAD --format%h %s%n%n%b该格式逐条输出短哈希、主题行subject与正文body用于理解每个提交的意图。命令文档特别强调按逻辑变更logical change合并条目而不是按提交commit逐条罗列——一个功能的实现提交与其后的修复提交fixup应合并为一条。第 4 步按路径模式分类提交这是整个工作流的规则核心。命令要求必须先加载commit-categories技能定义于 .opencode/skills/commit-categories/SKILL.md再依据其路径模式表为每个提交归类。该表基于 workerd 的真实目录结构制定类别路径模式APIsrc/workerd/api/排除node/与pyodide/Node.js compatsrc/workerd/api/node/、src/node/Pythonsrc/workerd/api/pyodide/、src/pyodide/Rustsrc/rust/Cloudflare APIssrc/cloudflare/I/Osrc/workerd/io/JSGsrc/workerd/jsg/Serversrc/workerd/server/Buildbuild/、MODULE.bazel、BUILD.bazelTypestypes/Docs / Config文档、Agent/工具配置、.md文件Tests仅改动测试文件Other上述未覆盖的其余内容分类的具体操作是对每个提交执行git diff-tree --no-commit-id --name-only -r hash列出其改动文件与上表匹配将提交归入改动占比最大的主类别跨越多个类别的提交归入主类别不重复列。横切标注Cross-cutting calloutscompat flags 与 autogates除主类别外该技能还定义了两个额外标注区不是主类别而是伴随出现的高可见性章节一旦提交触及相关文件就必须单独列出标注区触发条件New/Updated Compat Flags改动 src/workerd/io/compatibility-date.capnp或代码中新增compatibilityFlags引用New/Updated Autogates改动 src/workerd/util/autogate.h 中的WORKERD_AUTOGATES宏或新增 autogate 注册这些标注绝不能被埋在普通类别条目里——它们是评审者和发布说明读者需要第一眼看到的高风险项。这一设计直接呼应 workerd 的运行时特性新增兼容性标志会改变线上行为而 autogate 是灰度开关漏报会造成发布事故。第 5 步起草总结对每个有变更的类别每个逻辑变更一条 bullet按逻辑合并不按提交数每条 bullet 以动词开头Add、Fix、Update、Remove、Refactor附上最重要的文件引用使用仓库相对路径显著标注破坏性变更breaking changes、新增 compat flags、新增 autogates。第 6 步按固定模板输出命令定义了标准输出结构## Summary 1-2 句分支目的概述 ## Changes ### Category - change description ## Breaking Changes 如有则保留该节否则整节省略 ## Testing 简要说明新增或修改了哪些测试模板的要点Breaking Changes节无内容即整节省略避免空壳节Testing节要求给出测试改动概览——这与仓库的测试文化一致参见 samples/unit-tests、src/workerd/api 下大量.wd-test文件若用户参数要求特定风格则调整语气PR 描述更详细发布说明面向用户更简洁。必须加载的配套技能commit-categories分类规则的事实来源该技能.opencode/skills/commit-categories/SKILL.md本身是changelog 与 whats new 总结的分类规范其路径模式表保证了不同 Agent 会话产出一致且可复现的分类结果。它还给出了分类操作的顺序逐提交列文件 → 匹配路径 → 归主类别 → 检查横切标注 → 输出时省略空类别。也就是说输出模板里的Category节并非固定五个而是有内容才出现。markdown-drafts原样保留 Markdown 源码命令强调输出将被复制进 PR 或发布说明因此必须加载markdown-drafts技能.opencode/skills/markdown-drafts/SKILL.md遵循其渲染规则。该技能的核心约束是面向外部系统GitHub PR、Jira、Wiki、RFC、设计文档等的草稿一律使用标准 Markdown 语法#/##标题、-/*列表、围栏代码块、行内代码、表格、引用块、---分隔线、任务清单由于聊天界面会渲染并吞掉原始 Markdown 符号整个草稿必须包在无语言标签的三反引号代码围栏内确保用户复制到的是原始 Markdown 源码而非被 UI 处理后的纯文本明确禁止全大写标题、下划线式人工排版、HTML 标签除非目标系统必需、未经要求添加 emoji、以及三连词式 AI 套话和空洞开头结尾——要求直击要点。这一点解释了 changelog 命令最后一行IMPORTANT提示的由来它是为了保证 Agent 输出在复制粘贴过程中格式不丢失。源码佐证为什么这些规则如此设计compat flags 与compatibility-date.capnp分类技能把 src/workerd/io/compatibility-date.capnp 视为新增兼容性标志的触发文件并非偶然。该 capnp 文件以annotation compatEnableFlag$compatEnableFlag(...)形式逐条登记运行时特性开关例如$compatEnableFlag(formdata_parser_supports_files)、$compatEnableFlag(fetch_refuses_unknown_protocols)、$compatEnableFlag(streams_enable_constructors)等src/workerd/io/compatibility-date.capnp#L81-L120。每个 flag 的启用日期、disable 名、experimental 标注都集中在此因此改动该文件是识别新 flag 的最可靠信号。仓库还配套了 .opencode/commands/compat-flag.md 命令它借助compat-date-at工具按启用日期反查某天的 flags 集合并在 C 中搜索 getter如getTextDecoderReplaceSurrogates()定位使用点、在.wd-test与测试.js中定位测试用例。autogates 与autogate.h宏同样分类技能把 src/workerd/util/autogate.h 作为新增 autogate的触发文件。从源码看所有 autogate 都由WORKERD_AUTOGATES(V)宏统一登记src/workerd/util/autogate.h#L69当前注册项包括TEST_WORKERD、V8_FAST_API、STREAMING_TAIL_WORKER、PER_ISOLATE_JAVASCRIPT_BOOTSTRAP、DURABLE_OBJECT_RETRIES_FETCH、NODEJS_URL_RUST、NODEJS_EXCEPTIONS_RUST、RPC_EXTERNALS_HYDRATION等每个条目旁都有/* ... */注释说明用途与回滚策略。配套的 .opencode/commands/autogate.md 命令进一步说明AutogateKey枚举、配置字符串与getAutogateKeys()迭代列表都由该宏生成、不会失同步配置字符串由枚举名自动推导——SCREAMING_SNAKE_CASE转小写 kebab-case 并加workerd-autogate-前缀例如AutogateKey::MY_NEW_FEATURE对应workerd-autogate-my-new-feature运行时通过util::Autogate::isEnabled(AutogateKey::NAME)检查测试则在.wd-test的autogates [workerd-autogate-kebab-name]配置中启用。autogate 是临时性灰度开关按 src/workerd/util/autogate.h#L33-L57 的注释功能全面铺开后应从宏中移除并只保留新代码路径——因此 changelog 必须把 autogate 的新增/修改作为高可见性标注。发布机制changelog 的最终消费场景changelog 输出之所以分为PR 描述与发布说明两种语气是因为 workerd 的发布流程高度自动化。RELEASE.md 说明workerd与workers-types的主版本号分别为1与4次版本号取 src/workerd/io/release-version.txt 中记录的日期当前为2026-09-08每当该日期变更CI 自动产出 linux-64、linux-arm64、darwin-64、darwin-arm64、windows-64 五个平台的二进制并自动发布类型包。也就是说一个 for release notes 风格的 changelog 会直接服务于下一轮自动化发布其面向用户、简明扼要、突出破坏性变更的约束是发布实际需求而非形式要求。与相邻命令的分工changelog 并非仓库中唯一的提交总结命令理解它与兄弟命令的边界有助于正确使用whats-new.opencode/commands/whats-new.md面向远端 main 分支按数量10、日期since 2026-02-01、时间范围today、this week、this month拉取近期提交同样强制加载commit-categories技能分类但输出为每条提交一行的新闻式摘要hash summary — author并单独检查当前分支与 main 的冲突面changelog面向当前分支按逻辑变更合并条目输出为可粘贴的 PR/发布说明模板。两者共用同一套分类技能保证了仓库内所有 Agent 生成的变更摘要口径一致。实战示例把工作流串起来假设当前分支新增了一个 I/O 层能力并附带 compat flag按命令的完整流程产出如下确定范围git log --oneline origin/main..HEAD返回 3 个提交实现 修复 测试读 diffgit diff origin/main...HEAD --stat显示主要改动集中在src/workerd/io/读提交信息确认意图分类加载commit-categories技能匹配路径表归入I/O同时检出compatibility-date.capnp被修改 → 命中New/Updated Compat Flags横切标注起草按动词开头写 bullet附文件引用输出套用模板并在主类别之后追加横切标注节最后整个草稿包进无语言标签的三反引号代码围栏保证原始 Markdown 可被原样复制。最终产出形态## Summary 在 I/O 层新增 X 能力并引入配套的 compatibility flag。 ## Changes ### I/O - Add X 能力支持src/workerd/io/... ### Tests - Add X 相关 .wd-test 用例 ## Compat Flags - x_feature: 新增启用日期 2026-10-01src/workerd/io/compatibility-date.capnp ## Testing 新增/修改 N 个 .wd-test 用例覆盖默认行为与 flag 启用后的行为。小结workerd 仓库的changelog命令把分支变更 → 结构化 changelog定义为可复现的 Agent 子任务git命令负责取数与定界commit-categories技能以真实目录结构为纲提供分类规则并强制标注 compat flags 与 autogatesmarkdown-drafts技能保证输出以原始 Markdown 形态交付最终落到 PR 描述或自动化发布使用的发布说明。对希望在大型混合语言仓库中用 AI 维护变更记录的开发者而言这套命令 强制技能 固定模板的组合本身就是一份可移植的工作流范式。【免费下载链接】workerdThe JavaScript / Wasm runtime that powers Cloudflare Workers项目地址: https://gitcode.com/GitHub_Trending/wo/workerd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考