yike-gunshi 文档落地路径：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见
~/.claude/skills/forge-doc-policy/doc-paths.md。 当前文档加载顺序：涉及文档更新时，先读项目CLAUDE.md、docs/README.md、docs/INDEX.md和相关根级当前真相源；archive/raw只作历史证据。 详细规则见~/.claude/skills/_shared/current-doc-loading.md。
/forge-ship：发布上线
核心原则
ship 不是“创建 PR 就结束”。它有两个模式：
- PR only：提交、推送、创建或更新 PR，然后停止。
- Full ship：提交、推送、创建或更新 PR，检查 PR 状态，合并 PR 到远程基础分支，再把本地基础分支 worktree 同步到
origin/<基础分支>。
当用户明确说“ship / 发布 / 合并 / 通过 PR / 更新远程和本地 main”时，默认使用 Full ship。当用户只说“创建 PR / 提交 PR / 先发 PR”时，使用 PR only。
永远区分这些状态：代码已提交、分支已推送、PR 已创建、PR 已合并、远程 main 已更新、本地 main 已同步、ECS 已部署。除非真的执行部署并验证运行态，否则不要说线上已更新。
前置脚本
每次先运行：
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "当前分支: $_BRANCH"
git status --short
git remote -v
如果当前分支就是基础分支（通常是 main），不要直接 ship。先询问用户是要：
- A) 新建功能分支再 ship（推荐）
- B) 只同步本地 main
- C) 停止
提问格式与批量策略见 ~/.claude/skills/_shared/interaction-protocol.md。
第0步：确定 Ship 模式和基础分支
先根据用户措辞判断模式（PR only / Full ship），不确定时询问。
确定基础分支：
gh pr view --json baseRefName -q .baseRefName 2>/dev/null # 1. 已有 PR 则读 PR base
gh repo view --json defaultBranchRef -q .defaultBranchRef.name 2>/dev/null # 2. 否则读仓库默认分支；都失败回退 main
记录：当前分支、基础分支、ship 模式、当前 HEAD、origin/<基础分支> HEAD。
第0.5步：生产写面授权门
账本"权限.生产操作点名授权清单"复发 5 次后的固化（2026-07-17）。
开工前枚举本轮全部仓库外写面。判断标准：动作对象不在本仓库工作区内，就是写面。常见：
- self-PR merge / 删远程分支
- 部署（ssh / scp / 重启服务 / 改服务器 .env）
- 数据库写（迁移、pg_cron、生产数据修改）
- 第三方账号写（X List、飞书、发布平台）
把清单一次性列给用户请求点名授权，不要逐次撞权限门。同时给出用户可预置进 .claude/settings.local.json 的 allow 规则（如 Bash(ssh root@HOST *)、Bash(./scripts/deploy.sh*)），并说明：AI 代改 settings 会被反自授权设计拦截，这几条只能用户亲手加。
本轮没有仓库外写面就记录"无写面"跳过。中途被拦时按账本"被拦即换路勿重试"处理，禁止原样重试同一命令。
第1步：安全检查
检查当前 worktree：
git status --short --branch
git fetch origin <基础分支> --quiet
git diff origin/<基础分支> --stat
git log origin/<基础分支>..HEAD --oneline
如果有未提交更改，询问：
- A) 将本次相关更改加入暂存区并提交（推荐）
- B) 交互式选择文件
- C) 停下来，让我处理
不要自动加入无关文件。特别注意构建产物和缓存文件（如 tsbuildinfo、__pycache__）。
如果是 Full ship，提前定位本地基础分支 worktree（定位命令见 references/merge-and-sync.md 第11步），但此时不要修改它。找不到就记录“未找到”，不要自动创建，除非用户明确要求。
第2步：同步基础分支到当前功能分支
git fetch origin <基础分支> --quiet
git merge origin/<基础分支> --no-edit
如果项目约定使用 rebase，需先确认，不要擅自 rebase 已共享分支。
如果有冲突：
- 列出冲突文件。
- 解释冲突发生在当前功能分支合并基础分支阶段。
- 帮助解决冲突。
- 解决后重新运行关键测试。
- 冲突未解决前停止 ship。
第3步：运行项目验证
不要使用 npm test || yarn test || ... || echo "未找到测试命令" 这种链式命令，它会吞掉真实失败。
优先运行项目 CLAUDE.md 或项目验证脚本中已记录的测试命令；没有记录时按项目类型探测（npm test / pytest / go test 等），优先运行与本次改动相关的测试。
如果测试失败：
- 分析是否与本次改动相关。
- 相关则修复后重跑。
- 不相关则列出证据并询问是否继续。
- 未经确认不要跳过失败测试。
如果没有可用测试，询问：
- A) 为本次改动补基础测试（推荐）
- B) 只做静态检查和人工验证
- C) 停止
第4步：发布前 diff 审查
git diff origin/<基础分支> --stat
git diff origin/<基础分支>
检查：
- 是否有调试代码：
console.log、debugger、临时print - 是否有密钥、token、私有配置
- 是否有
TODO: 上线前删除 - 是否误提交构建产物、缓存、tsbuildinfo
- 是否包含无关文件
- 是否修改了数据库、prompt、skill、部署脚本等高风险区域
发现问题先修复或询问，不要带病 push。
第5步：更新 CHANGELOG
如果仓库存在 CHANGELOG.md，且本次变更值得未来追溯，则更新。CHANGELOG 只记录发布事实和历史账本；不要把它当作 PRD/DESIGN/ENGINEERING 的当前事实源。
git log origin/<基础分支>..HEAD --oneline --no-merges
如果只是纯机械变更，或用户明确不需要文档，允许跳过，但发布总结要写明“CHANGELOG 未更新”。
如果存在 VERSION 文件，询问是否升级版本：
- A) patch
- B) minor
- C) major
- D) 不升级
第6步：最终提交
git add <本次相关文件>
git status --short # 确认无关文件未暂存
git commit -m "<type>: <summary>"
如果已经有提交且只有 CHANGELOG/VERSION 变更，可单独提交一条 chore: update changelog。提交后记录 commit SHA。
第7步：推送当前分支
git push -u origin <当前分支>
如果推送被拒绝，不要直接 git pull --rebase。先查看远端差异：
git fetch origin <当前分支> --quiet
git log --left-right --graph --oneline HEAD...origin/<当前分支>
询问：
- A) rebase 到远端分支后再推送（推荐，若只是远端新增提交）
- B) merge 远端分支后再推送
- C) 停止，让我处理
不要 force push，除非用户明确要求且确认影响范围。
第8步：创建或更新 PR
先检查是否已有 PR：
gh pr view --json number,url,state,baseRefName,headRefName 2>/dev/null
如果没有 PR，创建：
gh pr create --title "<PR标题>" --body "<PR描述>" --base <基础分支> --head <当前分支>
PR 描述必须包含：
- 变更摘要
- 测试情况
- 注意事项
- 是否需要部署
- 是否有 migration / 数据修正 / prompt 变更
PR 创建后记录 PR URL。
如果模式是 PR only，到这里停止，并输出当前状态。
第9步：PR 合并前检查
目的：Full ship 合并前确认 PR 状态可合并（OPEN、非 draft、无冲突、checks 通过、review 满足）。
红线：
statusCheckRollup为空时只能说“无远程 checks”，不能说“CI 已通过”。- 有 failed check 或冲突时停止；不绕过 review 和保护规则。
执行细节必读 references/merge-and-sync.md。
第10步：合并 PR 以更新远程基础分支
目的：按仓库约定的 merge 方式合并 PR，更新远程基础分支并记录新 SHA。
红线：
- 合并失败时停在 PR 合并阶段，不绕过 review、CI、权限或保护规则。
- 不 force push。
执行细节必读 references/merge-and-sync.md。
第11步：同步本地基础分支 worktree
目的：把本地基础分支 worktree 快进到 origin/<基础分支>。
红线：
- 只从
origin/<基础分支>同步，不要用功能分支直接覆盖本地 main。 - 禁止
git reset --hard、git checkout --、静默覆盖用户未提交文件；脏工作区或分叉时停止询问。 - worktree 找不到时报告，不自动创建。
- 本地 HEAD 与
origin/<基础分支>一致后，才能说“本地基础分支已同步”。
执行细节必读 references/merge-and-sync.md。
第12步：发布完成总结
总结必须拆状态：
+====================================================+
| Ship Summary |
+====================================================+
| 模式：PR only / Full ship |
| 功能分支：<branch> |
| 基础分支：<base> |
| 提交：<commit sha> |
| PR：<url> |
| PR 状态：已创建 / 已合并 / 未合并 |
| 远程基础分支：<origin/base sha> |
| 本地基础分支 worktree：<路径 / 未找到> |
| 本地基础分支状态：已同步 / 未同步 / 因脏工作区暂停 |
| 测试：通过 / 跳过 / 失败 |
| CHANGELOG：已更新 / 未更新 |
| 部署：未执行 / 已执行并验证 |
+====================================================+
如果没有执行 ECS 部署，必须写：
ECS/线上部署未执行。本次 ship 只表示代码进入远程基础分支，并同步了本地基础分支。
重要规则
- 先 review，后 ship：
forge-ship默认用于 review 后的发布，不替代完整 code review。 - PR 是远程 main 的入口：需要进入远程 main 的代码必须通过 PR merge。