Content Studio Release Workflow

Content Studio 通用发版流程

边界

• 本 skill 只处理仓库版本发布：版本号、发布说明、本地门禁、桌面包构建、commit / tag / push 确认和 Release workflow 跟进。
• 发版涉及 Lime App Server sidecar、resources/app-server/、runtime provider store、Agents 工作台继续对话、AI Agent 对话未启动 或 Agents UI 回归时，先使用 .codex/skills/content-studio-app-server/ 并读取 docs/aiprompts/app-server-workflow.md。
• bugu / seenx 的 stable、latest、R2、download-manifest、官网下载卡片和控制面 latest 继续使用 .codex/skills/content-studio-oem-release/。
• 发版属于高风险流程。git commit、git tag、git push、GitHub Release 创建 / 更新、删除文件、覆盖 tag、真实调用生产 API 前，必须按 AGENTS.md 的中文危险操作格式确认。
• 如果工作区已有大量未提交改动，先声明本轮写集；只修改发版事实源，不回滚、不覆盖用户改动。

启动检查

1. 先读：
   • AGENTS.md
   • .codex/skills/README.md
   • docs/aiprompts/app-server-workflow.md（仅当本次发布涉及 App Server / Agents runtime）
   • package.json
   • RELEASE_NOTES.md
2. 盘点现状：

   git status --short
   git log --oneline --decorate --max-count=20
   git tag --list "vX.Y.Z"
   

3. 明确目标版本：
   • 用户给出 vX.Y.Z 或 X.Y.Z 时，规范化为版本 X.Y.Z 和 tag vX.Y.Z。
   • 用户未给版本时，只能读取当前版本并建议 bump；不能擅自发版。
4. 如果上一轮命令仍在跑，只处理自己启动且已被用户中断的进程；不要终止明显属于用户的 dev server / Electron / 测试进程。

版本事实源

版本改动必须同步：

• package.json
• package-lock.json
• RELEASE_NOTES.md

检查项：

rg -n '旧版本|目标版本' "package.json" "package-lock.json" "RELEASE_NOTES.md" "electron-builder.yml" "forge.config.mjs" ".github/workflows"

说明：

• electron-builder.yml 和 forge.config.mjs 目前不硬编码应用版本；只在发布相关配置变更时修改。
• resources/app-server/app-server.release.json 默认是本地 sidecar manifest，不等同桌面应用版本；只有发布任务明确涉及 App Server sidecar 资源时才修改。
• 修改 resources/app-server/ 或 App Server manifest 时，必须按 docs/aiprompts/app-server-workflow.md 记录 manifest / binary 来源、sha256、--data-dir 与 modelProvider/list 预检结果。
• 锁文件优先用 npm version --no-git-tag-version X.Y.Z 或结构化 JSON 更新，避免手工漏改。

Release Notes

事实源是根目录 RELEASE_NOTES.md，中文为 primary。

生成内容时参考：

git describe --tags --abbrev=0
git log <last-tag>..HEAD --pretty=format:"%s (%h)" --no-merges
git diff --stat

格式保持现有风格：

## vX.Y.Z - YYYY-MM-DD

### 主题

- 面向发布对象描述变更，不逐条照搬内部 commit message。

### 验证

- `npm run verify:local`

如只做 release note 或文档更新，可降级验证，但最终汇报必须说明降级理由。

验证矩阵

版本发布前默认执行：

npm run verify:local

根据变更范围补充：

npm run dist:mac
npm run dist:win
npm run dist:linux
npm run smoke:app-server
npm run app-server:prepare:test
npm run app-server:backend:test

规则：

• 普通代码变更至少跑 npm run typecheck。
• 可交付功能变更跑 npm run build。
• 主工作台 / preload / IPC 主链改动优先补跑 npm run smoke:electron。
• 打包、图标、release 配置改动跑对应 npm run dist:*；macOS 本地优先 npm run dist:mac。
• App Server sidecar / resources / runtime provider store 改动必须补跑 npm run app-server:prepare:test、npm run app-server:backend:test、npm run smoke:app-server；真实 provider store 或平台宿主链路按场景补跑 npm run app-server:runtime:live 或 npm run platform-host:runtime:live。
• Agents 工作台状态机或 UI 改动必须补跑 node scripts/run-functional-tests.mjs --test-name-pattern "等待用户补充的 agents 普通对话可以继续" 和 npm run test:e2e -- --grep "agents 寒暄对话保持普通回复"；不得发布会把第二轮普通对话误判为 AI Agent 对话未启动 的版本。
• GUI / E2E 失败必须修真实用户路径；不能通过跳过测试、放宽断言或无意义等待绕过。

Commit / Tag / Push

执行任何 git 写操作前，先汇总：

• 目标版本与 tag。
• 将纳入提交的文件列表。
• 已通过、失败、未执行的验证。
• 是否存在未提交的非发版改动。
• 是否会触发 GitHub Release / Actions。

然后按 AGENTS.md 危险操作格式请求确认。确认后才执行：

git add <release-files-and-intended-changes>
git commit -m "Release vX.Y.Z"
git tag -a vX.Y.Z -m "布谷AI vX.Y.Z"
git push origin main
git push origin vX.Y.Z

如果 tag 已存在，不要覆盖；先说明本地与远端 tag 状态，并单独确认删除或重建策略。

Release / CI 跟进

推送后按仓库事实源跟进：

gh run list --workflow "Release Desktop Packages"
gh run watch <run-id>

如 CI 或 release workflow 失败，先读取日志、复现或对齐失败，再修复并重新跑本地相关验证；不要只依赖远端 CI 试错。

收尾输出

最终汇报必须包含：

• 本轮完成度百分比。
• 版本号、tag、release note 路径。
• 实际修改的发版事实源。
• 验证命令结果与任何环境限制。
• 是否已经 commit / tag / push。
• 如需要用户可见下载更新，明确下一步转入 content-studio-oem-release。