Kun 开发协作与自动化发布工作流实战指南
Kun 开发协作与自动化发布工作流实战指南
本篇指南基于 Kun 仓库的 docs/DEVELOPMENT.md 展开,系统梳理 Kun 的分支策略(develop 日常集成、master 稳定发布)、从提交到合并的 PR 协作规范、提交前必须通过的验证门禁,以及由 GitHub Actions 驱动的跨平台稳定版发布流水线。读完本文,你将掌握在 Kun 仓库中正确起分支、提 PR、通过质量门禁,并理解 vX.Y.Z 版本标签计算、R2 发布渠道与签名发布背后的完整机制。
开发基线:develop 与 master 双分支策略
Kun 仓库采用清晰的双分支协作模型,这一点在 docs/DEVELOPMENT.md 中明确定义,并从 .github/workflows/release.yml 的触发条件中得到印证:
develop:日常协作与每日集成的主分支,所有常规功能与修复工作都应从这里开始;master:稳定发布分支,由维护者从develop更新,普通贡献者不在其上直接开发;- 非常规改动鼓励使用短生命周期特性分支(short-lived feature branches),避免长期分叉带来的合并冲突。
从源码结构看,这套分支模型与发布流水线深度绑定:release.yml 只接受"从 develop 合入 master 的同仓库 PR"作为自动发布触发事件(pull_request.head.ref == 'develop' 且 base.ref == 'master'),也就是说,合入 master 的 PR 本身就是一次发布候选。
推荐工作流:从同步到合并的七个步骤
文档给出的标准工作流如下:
- 更新本地仓库;
- 切换到
develop; - 拉取
develop最新变更; - 可选:从
develop创建特性分支; - 本地实现并验证改动;
- 向
develop提交 PR; - 通过评审与检查后合并。
同步 develop
git checkout develop
git pull origin develop
从 develop 创建特性分支
git checkout develop
git pull origin develop
git checkout -b feat/short-description
推送分支
git push origin feat/short-description
分支命名建议
文档给出的命名示例体现了"类型/简短描述"的规范,与仓库实际的 openspec 变更目录(如 openspec/changes/add-local-model-routing-gateway、openspec/changes/fix-thread-busy-stability)命名风格一致:
feat/runtime-settingsfix/connection-probedocs/bilingual-readmerefactor/chat-store
Pull Request 流程与默认目标分支
PR 的默认目标分支是 develop。典型路径:
- 在从
develop创建的特性分支上开发; - 推送分支到远端;
- 向
develop提交 PR; - 处理评审反馈;
- 通过审批与检查后合并。
仓库自带的 .github/pull_request_template.md 为 PR 描述提供了结构化的模板,包含"概要 / 背景 / 变更 / 截图或录屏 / 测试 / 验证"等区块,并要求在提交前勾选 npm run test、npm run typecheck、npm run build 等验证项,同时声明贡献遵循 CLA。
提交前必须执行的验证
文档要求最低限度运行以下三个命令:
npm run typecheck
npm run build
npm run test
如果改动影响运行时行为或 UI,还需运行:
npm run dev
并在开 PR 前手动验证受影响的流程。结合 package.json 可以深入理解这些命令实际做了什么:
typecheck:先构建扩展与 Kun 内核(npm run build:extensions+typecheck:kun),再对 Web 与 Node 两个工程分别执行tsc --noEmit -p tsconfig.web.json与tsc --noEmit -p tsconfig.node.json,是整个仓库的类型安全门禁;build:依次构建扩展、Kun 内核(build:kun,含@kun/provider-catalog与@kun/extension-api两个 workspace 及ensure-kun-install)、校验内置技能、打包内置扩展,最后执行 electron-vite 构建并校验打包运行时依赖;test:聚合扩展测试(test:extensions)、Kun 内核测试(test:kun)、打包契约测试(test:packaging)、发布工作流测试(test:release-workflows)以及 vitest 全量测试;dev:经由scripts/run-with-kun-flavor.cjs以 development 风味启动 Electron 开发环境(内部串联ensure:electron、扩展构建与electron-vite dev);lint:执行check:file-lines与 ESLint 全量检查;audit:production:运行 scripts/check-production-audit.mjs,在生产依赖审计层面把关。
值得一提的是,CI 中的质量门禁与这些命令一一对应:PR 检查工作流 .github/workflows/pr-checks.yml 的 quality job 依次运行 npm run typecheck、npm run lint、npm test 与 npm run audit:production,并在其后的 package / package-linux-arm64 / package-macos / package-windows job 中实际构建各平台安装包。也就是说,本地验证是 CI 的"预演",两者使用同一套命令契约。
PR 质量标准
文档开宗明义:"Code is easy. Good taste is rare. Review should protect the product experience, not only the implementation."(代码容易写,品味难得;评审应保护产品体验,而不只是实现本身。)
一个合格的 PR 应当:
- 聚焦单一主要目的;
- 易于评审;
- 有验证结果支撑;
- 行为发生变化时有文档说明。
PR 描述应包含:
- 改了什么(what changed);
- 为什么改(why it changed);
- 如何验证(how you verified it);
- UI 行为变化时附视频或 GIF;
- 项目逻辑变化时新增或更新单元测试。
这些要求在 .github/pull_request_template.md 的"Media / 截图或录屏"与"Tests / 测试"区块中被固化为必填项,并在 CI 的 pr-gate job 中被强制:任何质量或打包 job 失败都会导致 PR 门禁不通过。
变更范围标准
优先:
- 一个 PR 只解决一个主题;
- 最小化无关的格式改动;
- 不做机会主义的重构,除非该重构对当前变更是必要的。
避免:
- 无解释地混入文档、重构与功能改动;
- 大规模且无文档的行为变更;
- 绕过常规评审流程处理高风险改动。
从仓库的 openspec 变更目录(如 openspec/changes 下的每个变更都是一个独立议题目录)可以看出,仓库本身就在践行"一次变更一个主题、伴随说明文档"的组织方式。
本地化与文档标准
- 本地化:改动用户可见文案时,尽量同时更新中英文文案,保持文档与 UI 措辞一致。仓库中存在大量成对的中英文文档(如 docs/DEVELOPMENT.md 与 docs/DEVELOPMENT.zh-CN.md、README.md 与 README.zh-CN.md),以及
docs/extensions/下成对出现的.md与.en.md文档,是这一标准的直接体现。 - 文档:当改动影响以下方面时必须更新文档——安装/搭建方式、命令、运行时要求、分支策略、发布行为、贡献者工作流。
合并指引
贡献改动只有在以下条件全部满足后才可合入 develop:
- 评审反馈已处理;
- 检查通过;
- 变更被认为对日常集成分支足够稳定。
master 仅用于稳定发布:当维护者认定当前 develop 状态达到可发布水平后,将 develop 合并进 master。
发布自动化:GitHub Actions 驱动的稳定版流水线
稳定版由 GitHub Actions 在同仓库"从 develop 合入 master"的 PR 被合并时自动发布。结合 .github/workflows/release.yml,发布流水线的完整链路如下:
- 质量门禁(quality):对合并提交运行
typecheck、lint、npm test、audit:production; - 版本计算(prepare):运行 scripts/compute-ci-release-version.cjs 计算下一个
vX.Y.Zpatch 标签。其核心逻辑是:- 若 HEAD 已指向某个
v*semver 标签,则直接复用该标签(existingTag); - 否则从仓库全部
v*标签中取最新的三段式 semver,patch 位加一; - 若
package.json的 version 高于所有已有标签,则视为显式升版(例如0.2.37 -> 0.3.0),直接采用该版本号,从而支持 minor/major 发布;
- 若 HEAD 已指向某个
- 跨平台构建:并行构建并产出:
- macOS:签名并公证的 arm64 / x64 的 DMG 与 ZIP;
- Windows:x64 NSIS 安装器(
npm run dist:win); - Linux:x64 与 arm64 的 AppImage 与 deb 包;
- 各平台构建后均执行打包更新交接(
smoke:packaged-update-handoff)与安装器冒烟测试;
- 发布与上传(publish):
- 校验
vX.Y.Z标签是否已指向合并提交(重跑时复用指向合并提交的既有标签,否则拒绝执行); - 生成发布说明,创建/更新 GitHub Release 草稿并上传全部资产;
- 调用 scripts/publish-r2.mjs 将 mac / win / linux 三平台资产上传到 R2
stable渠道的releases/{tag}/归档,并写入release-{platform}.json平台清单;
- 校验
- 验收与发布(accept-and-publish):复用 .github/workflows/release-gui-acceptance.yml,先验证候选标签与草稿、校验各平台清单完整性与字节一致性,再通过
publish-r2.mjs promote --require-all-platforms将stable/latest指向新版本——只有在全部平台上传与验收成功后才提升stable/latest,最后将 GitHub Release 从草稿转为正式发布。
需要配置的 GitHub Actions Secrets
首次自动化发布前,维护者必须配置以下 Secrets(见 .github/workflows/release.yml 的引用):
| 用途 | 变量名 |
|---|---|
| R2 对象存储 | R2_BUCKET、R2_ACCESS_KEY_ID、R2_SECRET_ACCESS_KEY、R2_PUBLIC_BASE_URL,以及 R2_ACCOUNT_ID 或 R2_ENDPOINT 之一 |
| R2 可选前缀覆盖 | R2_RELEASE_PREFIX(默认前缀为 deepseek-gui,见 scripts/publish-r2-support.mjs) |
| macOS 签名与公证 | MAC_CODESIGN_P12_BASE64、CSC_KEY_PASSWORD、APPLE_API_KEY_BASE64、APPLE_API_KEY_ID、APPLE_API_ISSUER |
同时,仓库的 Actions 设置必须允许 GITHUB_TOKEN 写入仓库内容,工作流才能创建标签并发布 Release(release.yml 声明了 permissions: contents: write)。
本地手动发布的兜底命令
自动化之外,文档明确保留了本地手动发布的兜底工具:
npm run release:mac # 对应 scripts/release-mac.sh
npm run release:win # 对应 scripts/release-win.ps1
如需在本地构建各平台安装包,package.json 还提供了 npm run dist:mac、npm run dist:win、npm run dist:linux 等底层构建命令,以及 npm run r2:upload / npm run r2:promote(对应 publish-r2.mjs 的 upload / promote 子命令,支持 --channel frontier|stable 与 --dry-run)。
补充:每日开发预发布
除稳定版外,仓库还通过 .github/workflows/daily-dev-prerelease.yml 与 .github/workflows/daily-dev-prerelease-schedule.yml 每天两次(UTC 04:00 / 16:00,即北京时间 12:00 与次日 00:00)基于 develop 构建 frontier 渠道的预发布版本,版本形如 0.0.0-dev-YYYYMMDD-HHMM、标签形如 dev-YYYYMMDD.HHMM。这与稳定版 stable 渠道通过 --require-all-platforms 严格验收形成对照:日常集成分支的产物始终先进入 frontier 渠道,经稳定化后才进入 stable。
维护者注意事项
文档最后提醒:如果维护者后续调整受保护分支、必审人员或更严格的自动化门禁,本开发文档应同步更新以匹配仓库规则。这也意味着,任何协作或发布策略的变更,都应同时反映在文档与对应工作流配置中,保持二者契约一致。
小结
Kun 的开发协作体系可以概括为一条清晰的链路:develop 承担每日集成,短生命周期特性分支承载具体改动,PR 经质量门禁(typecheck / lint / test / audit)与三平台打包验证后合入 develop;当 develop 稳定到可发布时,维护者将其合入 master,触发 GitHub Actions 自动计算 vX.Y.Z 标签、构建签名安装包、上传 R2 stable 渠道并在全平台验收通过后提升 stable/latest。这套"文档定义规范、CI 强制契约、脚本落实细节"的配合方式,正是 Kun 能够在多平台持续交付的关键所在。
如需进一步阅读,可参考 .github/workflows/release.yml、.github/workflows/pr-checks.yml、scripts/compute-ci-release-version.cjs、scripts/publish-r2.mjs 以及 docs/CONTRIBUTING.md。