发布 Kairos

English

本清单将仓库准备与不可轻易撤回的公开操作分开。只有在干净环境中验证发布产物和安装路径后,发布才算完成。

仓库一次性设置

建议的 GitHub 仓库元数据:

验证发布候选版本

  1. 确认 README 的实现状态与 Roadmap 仍然符合代码现状,并检查未发布变更。
  2. 搜索中英文文档中的旧工具数量、生命周期状态、配置和计划功能。
  3. 执行完整仓库检查:

    make test
    make go-vet
    git diff --check
    
  4. 在干净 Checkout 中运行 quickstart,并通过 MCP 完成至少一个 Task。执行 make daemon-e2e,验证隔离的无模型 Workflow/Blackboard 及生命周期二进制测试。首个公开目标为 v0.1.0-alpha.1,在发布说明中明确试用范围,不把 Snapshot 当作已发布版本。
  5. 安装 GoReleaser 2.17.1 后构建本地 Release Snapshot。使用与 Release workflow 相同的禁用 Lifecycle Script 的依赖安装方式,并在打包前生成 Notices:

    cd web
    npm ci --ignore-scripts
    npm run build
    cd ..
    make release-notices
    goreleaser release --snapshot --clean --skip=publish
    
  6. 执行 python3 scripts/verify-release.py --assets dist --version VERSION,版本使用 dist/metadata.json 中不含 v 前缀的准确值。脚本核对四个 Archive、checksum、quickstart/Skill/MCP 必需文件和入口文档链接,再验证本机双二进制版本、Core 启动和控制台资源类型(拒绝首页 HTML 回退)。脚本从包外目录启动包内 quickstart,检查打印的端点和 MCP 可见的两个 Task,并验证两个 Daemon 示例的 setup 模式;全程使用隔离数据,不调用模型。业务生命周期继续由 make daemon-e2e 覆盖。手动启动见包内安装指南。对于 Release workflow 产物,还需确认经过校验的合并 SBOM 覆盖两个程序并已列入 checksums.txt。
  7. 检查完整 Git 历史中的凭据,并确认作者姓名和邮箱适合公开。

Release workflow 在相关 PR 和手动触发时构建 Snapshot,分别在 Linux 与 macOS 验证本机发布包;另外两种架构只检查打包内容,不冒充本机执行。仅版本 Tag 推送会在两个本机验收通过后继续证明与发布;手动触发始终构建 Snapshot,即使选择版本 Tag 也不会发布。各平台真实模型、生产恢复和跨版本升级仍需独立验证。

公开发布

公开发布会改变外部状态。只有 Release Candidate Commit 合并,且 CI 和 Security workflow 全部通过后,才执行以下步骤。

  1. 将仓库改为 Public,确认 License、贡献指南、安全策略、Issues 和 Actions 均可见。
  2. 创建并推送带说明的语义化版本 Tag:

    git tag -a v0.1.0-alpha.1 -m "Release v0.1.0-alpha.1"
    git push origin v0.1.0-alpha.1
    
  3. Release workflow 会在不持有 Write Token 的情况下构建 macOS 与 Linux 的 amd64、arm64 Archive。每个包包含 Core 和 Daemon,Notices 覆盖两个程序在四个平台的 Go Module 并集及 npm 生产依赖,八份 Go 二进制清单与控制台清单合并为一个经过校验的 CycloneDX SBOM。独立的构建后 Job 随后为最终 Archive、SBOM 和 Checksum 创建 Attestation,再将产物交给最小 contents: write Publish Job。使用 Release 时应通过 GitHub Attestation 工具验证 Archive 来源。Codex 和模型凭据不打包。
  4. 对外发布前检查自动生成的 Release Notes。破坏性 API 或 Schema 变更及其 Migration 要求必须明确说明。
  5. 从 GitHub 下载一个发布产物到干净环境,重新验证版本输出、启动、健康检查和 Checksum。

不得移动或替换已经发布的 Tag。错误发布应使用新的 Patch 版本修正。如果 Migration 缺陷可能破坏持久化数据,应先明确标记受影响版本并发布恢复指南,再发布替代版本。