gimbal-release

开发和发布 Gimbal

请遵循仓库中的 AGENTS.md 和 docs/definition-of-done.md，明确范围、审查和完成标准。Justfile 和 .github/workflows/ 是可执行检查和发布流程的权威依据。本技能说明应采用哪种路径。

快速反馈

使用 just dev 进行编辑迭代。提出合并前，运行受影响的测试并观察所请求的行为。提交钩子会运行暂存文件检查和一组小型、未缓存的单元测试；目标耗时为 1 秒，预算为 3 秒。超时会发出警告并记录未完成的检查，但不会阻止发布。实际正确性问题仍需处理。just warm-hook 会在提交流程之外预热编译器缓存。生成器、安装、全仓库分析和浏览器构建都不在钩子中运行。

PR CI 会根据变更文件选择检查：文档变更运行指令和链接检查，自动化变更运行脚本和钩子检查，应用变更运行受影响的单元测试。主分支在分发前会通过一次完整的应用门禁检查。不要仅仅因为提交已创建、PR 已合并或标签已出现，就重复未发生变化的检查。现有证据必须注明来源并覆盖相应主张；出现新失败或输入发生变化时，应重新运行相关检查。

对于原生 UI 变更，请使用一次性目录观察实际应用和 macOS 系统菜单栏，绝不要使用 ~/.gimbal/desktop。请使用 gimbal upload-artifact 上传所需截图。仅有构建成功或 HTTP 响应不能证明像素显示正确。有关源码构建和应用生命周期，请阅读 development.md；只有刷新目录时才阅读 model-catalog.md。

自动交付

在用户授权范围内合并，然后从主分支跟进 Automatic release，直至其 Release 运行完成。非文档变更会在主分支检查一次、打标签、为受支持平台构建、完成签名和公证，并发布到更新源和 Homebrew tap。仅文档变更不会发布应用。请核实已发布的版本和渠道；PR 已合并或运行已排队都不代表交付已发布。合并或创建标签后，应复用流水线中针对确切源代码的检查，而不是再添加一次本地构建。

耗时策略定义在 scripts/release-performance.json 中：从主分支到发布的目标时间为 5 分钟，上限为 10 分钟。排队和重试时间也计入；活跃阶段的耗时也会单独报告，不会将并行任务耗时相加。Release performance 会监控运行情况，并在超时后创建问题。它不会让应用测试失败，也不会停止发布。请利用报告改进耗时较长的阶段；不要为了让报告显示为绿色而放宽预算。

发布失败时，请重新运行失败的已打标签 Release 作业，或在主分支上触发 Automatic release 以复用现有标签。重试前先检查失败阶段；避免重复已成功的应用检查。有关凭据、规则、手动主版本／次版本标签、签名恢复和插件兼容性，请阅读 distribution.md。常规交付不需要新增凭据或权限变更。

按请求进行本地安装

请使用公开的 Homebrew cask（gimbal 和 gimbal-app）；检查已安装的版本以及实际可执行文件／应用路径。直接运行 go install 会遗漏构建好的 Web 控制台。请使用其支持的参考资料刷新受影响的已发布技能，并与维护中的源版本进行比较。只有在收到请求时才需要本地安装和运行时验证；并非每次合并都要额外执行这些步骤。

请报告观察到的所需行为、源代码修订版本、相关检查、发布状态以及任何尚未补齐的验证缺口。区分源代码验证、分发产物验证和已安装 UI 验证。签名和凭据详情应保留在分发参考文档中，不要复制到常规流程中。