4.5 KiB
项目发布策略
策略优先级
按以下顺序确定规则，并在来源冲突时停止说明，不要静默覆盖：
- 用户本次请求中明确给出的目标和授权范围。
- 项目
AGENTS.md、CLAUDE.md、发布文档和可选的.release-policy.yaml。 - 构建脚本、包清单、CI 工作流和历史发布使用的实际入口。
- 代码托管平台当前的默认分支、保护规则、检查和允许的合并方式。
- 本 Skill 的默认值。
用户请求若与项目硬规则或平台保护冲突，展示冲突并请求处理方式。不要借用户的一句 “直接发布”绕过仓库声明的检查或保护。
开始流程时记录 base commit，并读取该提交对应的项目策略。本次发布分支对策略文件的 修改不应改变正在执行的流程；新策略从下一次发布开始生效。
项目策略不能授予外部写权限。即使配置声明创建 Forge Release 或删除远端分支，也必须 由用户本次请求明确授权相应动作。
可选配置
项目反复出现同一种歧义时，用户可以要求创建 .release-policy.yaml。从
templates/release-policy.template.yaml 复制后，只保留项目真正需要固定的字段。
配置只保存可提交的项目策略：
schema：配置结构版本，当前为1。base_branch：发布 PR/MR 的目标分支。branch_pattern：需要准备仓库修改时使用的版本分支格式，支持无展示前缀的规范{version}；直接发布不因此创建分支。version.scheme：semver或项目已经使用的其他方案。version.sources：构建和运行实际读取的权威版本文件；项目明确从 Git tag 派生版本时 可以省略，不要为了发布新增无消费方的版本文件。tag_pattern：release tag 格式，支持无展示前缀的规范{version}。merge_method：squash、merge或rebase。forge_release：项目是否建议在 tag 后创建 Forge Release；它不授予创建权限。tag_signing：off、optional或required。delete_remote_branch：发布完成后是否建议清理远端源分支；它只是计划偏好，不是删除 权限或自动执行指令，仍需用户在本次请求中明确授权。
不要在配置中保存 token、账号、私钥路径、个人工作目录或一次性发布状态。不要加入任意 shell 命令字段；本地验证继续从项目文档、CI 和构建入口发现。
读取配置后校验字段集合、类型和枚举值，遇到未知字段时停止。branch_pattern 和
tag_pattern 展开后分别用 Git branch/tag ref 规则校验；不要把配置值拼进 shell 字符串。
version.sources 中每一项必须是仓库相对路径，拒绝绝对路径和 ..。规范化并解析
symlink 后，目标必须仍在当前 worktree 内；权威来源通常还应由 Git 跟踪。
先按版本方案把用户输入规范化。默认 SemVer 接受 1.6.0 或作为用户输入的 v1.6.0，
但内部 {version} 固定为 1.6.0；版本文件写入规范值，branch/tag pattern 分别负责添加
展示前缀。自定义版本方案按项目文档定义规范值，不能从 pattern 猜测后重复添加前缀。
无配置时的发现顺序
- 从 remote HEAD 和平台信息确定默认 base，不能确定时询问。
- 从项目文档、CI 和构建入口找版本文件及更新方式。
- 仅当发布需要修改仓库内容时，从已有分支和已合并 PR/MR 识别命名与合并方式。
- 从稳定 tag 识别前缀、版本方案和更新说明范围；项目由 tag 派生版本时，把实际构建 入口和 tag 历史共同作为版本来源证据，否则只把 tag 当作交叉验证。
- 无项目约定时使用 SemVer 和
v<version>annotated tag；需要准备仓库修改时再使用release/v<version>和 squash merge。默认不创建 Forge Release，不删除远端分支。
每次执行的计划快照
在第一次写操作前列出以下事实：
- base 分支、远端 commit 和 tag 将指向的目标 commit。
- 当前版本、目标版本、版本来源和升级依据。
- 更新说明的提交范围、来源和拟发布内容。
- 是否需要修改仓库内容；需要时再列出 worktree 路径与分支名。
- PR/MR 托管平台和合并方式。
- tag 与 Forge Release 计划。
- 用户授权的最远阶段和清理范围。
任何事实在执行中改变时刷新计划。改变会影响已授权的远端写目标时，再次获得确认。