Kun 开发协作与自动化发布工作流实战指南

原创2026-10-08 23:16:071,381 阅读
文章标签:AI 应用人工智能AI Agent代码智能体交互助手桌面应用多智能体Agent 编排Agent 工作流工具调用Agent 记忆本地部署LLM 网关MCP Clients前端CLI

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 本身就是一次发布候选。

推荐工作流:从同步到合并的七个步骤

文档给出的标准工作流如下:

  1. 更新本地仓库;
  2. 切换到 develop;
  3. 拉取 develop 最新变更;
  4. 可选:从 develop 创建特性分支;
  5. 本地实现并验证改动;
  6. 向 develop 提交 PR;
  7. 通过评审与检查后合并。

同步 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-settings
  • fix/connection-probe
  • docs/bilingual-readme
  • refactor/chat-store

Pull Request 流程与默认目标分支

PR 的默认目标分支是 develop。典型路径:

  1. 在从 develop 创建的特性分支上开发;
  2. 推送分支到远端;
  3. 向 develop 提交 PR;
  4. 处理评审反馈;
  5. 通过审批与检查后合并。

仓库自带的 .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,发布流水线的完整链路如下:

  1. 质量门禁(quality):对合并提交运行 typecheck、lint、npm test、audit:production;
  2. 版本计算(prepare):运行 scripts/compute-ci-release-version.cjs 计算下一个 vX.Y.Z patch 标签。其核心逻辑是:
    • 若 HEAD 已指向某个 v* semver 标签,则直接复用该标签(existingTag);
    • 否则从仓库全部 v* 标签中取最新的三段式 semver,patch 位加一;
    • 若 package.json 的 version 高于所有已有标签,则视为显式升版(例如 0.2.37 -> 0.3.0),直接采用该版本号,从而支持 minor/major 发布;
  3. 跨平台构建:并行构建并产出:
    • macOS:签名并公证的 arm64 / x64 的 DMG 与 ZIP;
    • Windows:x64 NSIS 安装器(npm run dist:win);
    • Linux:x64 与 arm64 的 AppImage 与 deb 包;
    • 各平台构建后均执行打包更新交接(smoke:packaged-update-handoff)与安装器冒烟测试;
  4. 发布与上传(publish):
    • 校验 vX.Y.Z 标签是否已指向合并提交(重跑时复用指向合并提交的既有标签,否则拒绝执行);
    • 生成发布说明,创建/更新 GitHub Release 草稿并上传全部资产;
    • 调用 scripts/publish-r2.mjs 将 mac / win / linux 三平台资产上传到 R2 stable 渠道的 releases/{tag}/ 归档,并写入 release-{platform}.json 平台清单;
  5. 验收与发布(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。

登录后查看全文
Kun