release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Release Coordination Skill

版本发布协调技能

Run the full Paperclip maintainer release workflow, not just an npm publish.

This skill coordinates:

stable changelog drafting via
```
release-changelog
```
canary verification and publish status from
```
master
```
Docker smoke testing via
```
scripts/docker-onboard-smoke.sh
```
manual stable promotion from a chosen source ref
GitHub Release creation
website / announcement follow-up tasks

执行完整的Paperclip维护者发布工作流，而非仅进行npm发布。

此技能协调以下事项：

通过
```
release-changelog
```
生成稳定版本更新日志
来自
```
master
```
分支的预览版（canary）验证与发布状态跟踪
通过
```
scripts/docker-onboard-smoke.sh
```
进行Docker冒烟测试
从选定源引用手动升级为稳定版本
创建GitHub Release
网站更新与公告跟进任务

Trigger

触发条件

Use this skill when leadership asks for:

"do a release"
"ship the release"
"promote this canary to stable"
"cut the stable release"

当领导层提出以下需求时使用此技能：

"进行版本发布"
"推送版本上线"
"将此预览版升级为稳定版"
"发布稳定版本"

Preconditions

前置条件

Before proceeding, verify all of the following:

.agents/skills/release-changelog/SKILL.md

exists and is usable.

The repo working tree is clean, including untracked files.
There is at least one canary or candidate commit since the last stable tag.
The candidate SHA has passed the verification gate or is about to.
If manifests changed, the CI-owned
```
pnpm-lock.yaml
```
refresh is already merged on
```
master
```
.
npm publish rights are available through GitHub trusted publishing, or through local npm auth for emergency/manual use.
If running through Paperclip, you have issue context for status updates and follow-up task creation.

If any precondition fails, stop and report the blocker.

开始前，请验证以下所有条件：

.agents/skills/release-changelog/SKILL.md

文件存在且可用。

仓库工作树干净，包括无未跟踪文件。
自上一个稳定版本标签以来，至少有一个预览版或候选版本提交。
候选版本SHA已通过验证关卡或即将通过。
若清单文件有变更，CI维护的
```
pnpm-lock.yaml
```
更新已合并到
```
master
```
分支。
可通过GitHub可信发布获取npm发布权限，或在紧急/手动场景下使用本地npm认证。
若通过Paperclip执行，需具备用于状态更新和后续任务创建的议题上下文。

若任何前置条件不满足，请停止并报告阻塞问题。

Inputs

输入信息

Collect these inputs up front:

whether the target is a canary check or a stable promotion
the candidate
```
source_ref
```
for stable
whether the stable run is dry-run or live
release issue / company context for website and announcement follow-up

提前收集以下输入：

目标是预览版检查还是稳定版升级
稳定版的候选
```
source_ref
```
稳定版运行是模拟（dry-run）还是正式（live）
用于网站更新和公告跟进的发布议题/公司上下文

Step 0 — Release Model

步骤0 — 发布模型

Paperclip now uses a commit-driven release model:

every push to
```
master
```
publishes a canary automatically
canaries use
```
YYYY.MDD.P-canary.N
```
stable releases use
```
YYYY.MDD.P
```
the middle slot is
```
MDD
```
, where
```
M
```
is the UTC month and
```
DD
```
is the zero-padded UTC day
the stable patch slot increments when more than one stable ships on the same UTC date
stable releases are manually promoted from a chosen tested commit or canary source commit
only stable releases get
```
releases/vYYYY.MDD.P.md
```
, git tag
```
vYYYY.MDD.P
```
, and a GitHub Release

Critical consequences:

do not use release branches as the default path
do not derive major/minor/patch bumps
do not create canary changelog files
do not create canary GitHub Releases

Paperclip现采用提交驱动的发布模型：

每次推送到
```
master
```
分支都会自动发布一个预览版
预览版版本格式为
```
YYYY.MDD.P-canary.N
```
稳定版版本格式为
```
YYYY.MDD.P
```
中间段为
```
MDD
```
，其中
```
M
```
是UTC月份，
```
DD
```
是补零后的UTC日期
若同一UTC日期发布多个稳定版，稳定版补丁段（P）递增
稳定版从选定的已测试提交或预览版源提交手动升级
仅稳定版会生成
```
releases/vYYYY.MDD.P.md
```
、git标签
```
vYYYY.MDD.P
```
和GitHub Release

关键注意事项：

不要将发布分支作为默认路径
不要推导主版本/次版本/补丁版本的升级
不要创建预览版更新日志文件
不要创建预览版GitHub Release

Step 1 — Choose the Candidate

步骤1 — 选择候选版本

For canary validation:

inspect the latest successful canary run on
```
master
```
record the canary version and source SHA

For stable promotion:

choose the tested source ref
confirm it is the exact SHA you want to promote

resolve the target stable version with

./scripts/release.sh stable --date YYYY-MM-DD --print-version

Useful commands:

bash

git tag --list 'v*' --sort=-version:refname | head -1
git log --oneline --no-merges
npm view paperclipai@canary version

对于预览版验证：

检查
```
master
```
分支上最新的成功预览版运行记录
记录预览版版本号和源SHA

对于稳定版升级：

选择已测试的源引用
确认其为要升级的精确SHA

使用

./scripts/release.sh stable --date YYYY-MM-DD --print-version

确定目标稳定版版本号

实用命令：

bash

git tag --list 'v*' --sort=-version:refname | head -1
git log --oneline --no-merges
npm view paperclipai@canary version

Step 2 — Draft the Stable Changelog

步骤2 — 生成稳定版更新日志

Stable changelog files live at:

```
releases/vYYYY.MDD.P.md
```

Invoke

release-changelog

and generate or update the stable notes only.

Rules:

review the draft with a human before publish
preserve manual edits if the file already exists
keep the filename stable-only
do not create a canary changelog file

稳定版更新日志文件路径：

```
releases/vYYYY.MDD.P.md
```

调用

release-changelog

，仅生成或更新稳定版说明。

规则：

发布前需由人工审核草稿
若文件已存在，保留手动编辑内容
文件名仅用于稳定版
不要创建预览版更新日志文件

Step 3 — Verify the Candidate SHA

步骤3 — 验证候选版本SHA

Run the standard gate:

bash

pnpm -r typecheck
pnpm test:run
pnpm build

If the GitHub release workflow will run the publish, it can rerun this gate. Still report local status if you checked it.

For PRs that touch release logic, the repo also runs a canary release dry-run in CI. That is a release-specific guard, not a substitute for the standard gate.

运行标准验证关卡：

bash

pnpm -r typecheck
pnpm test:run
pnpm build

若GitHub发布工作流会执行发布，它会重新运行此关卡。但仍需报告本地检查状态。

对于涉及发布逻辑的PR，仓库还会在CI中运行预览版发布模拟。这是发布特定的防护措施，不能替代标准验证关卡。

Step 4 — Validate the Canary

步骤4 — 验证预览版

The normal canary path is automatic from

master

via:

```
.github/workflows/release.yml
```

Confirm:

verification passed
npm canary publish succeeded
git tag
```
canary/vYYYY.MDD.P-canary.N
```
exists

Useful checks:

bash

npm view paperclipai@canary version
git tag --list 'canary/v*' --sort=-version:refname | head -5

常规预览版路径通过以下方式从

master

分支自动执行：

```
.github/workflows/release.yml
```

确认：

验证已通过
npm预览版发布成功
git标签
```
canary/vYYYY.MDD.P-canary.N
```
已存在

实用检查命令：

bash

npm view paperclipai@canary version
git tag --list 'canary/v*' --sort=-version:refname | head -5

Step 5 — Smoke Test the Canary

步骤5 — 预览版冒烟测试

Run:

bash

PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh

Useful isolated variant:

bash

HOST_PORT=3232 DATA_DIR=./data/release-smoke-canary PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh

Confirm:

install succeeds
onboarding completes without crashes
the server boots
the UI loads
basic company creation and dashboard load work

If smoke testing fails:

stop the stable release
fix the issue on
```
master
```
wait for the next automatic canary
rerun smoke testing

运行：

bash

PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh

实用的隔离变体：

bash

HOST_PORT=3232 DATA_DIR=./data/release-smoke-canary PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh

确认：

安装成功
引导流程完成且无崩溃
服务器启动正常
UI加载正常
基础公司创建和仪表盘加载功能正常

若冒烟测试失败：

停止稳定版发布
在
```
master
```
分支修复问题
等待下一个自动预览版
重新运行冒烟测试

Step 6 — Preview or Publish Stable

步骤6 — 预览或发布稳定版

The normal stable path is manual

workflow_dispatch

on:

```
.github/workflows/release.yml
```

Inputs:

```
source_ref
```
```
stable_date
```
```
dry_run
```

Before live stable:

resolve the target stable version with

./scripts/release.sh stable --date YYYY-MM-DD --print-version

ensure
```
releases/vYYYY.MDD.P.md
```
exists on the source ref
run the stable workflow in dry-run mode first when practical
then run the real stable publish

The stable workflow:

re-verifies the exact source ref
computes the next stable patch slot for the chosen UTC date
publishes
```
YYYY.MDD.P
```
under dist-tag
```
latest
```
creates git tag
```
vYYYY.MDD.P
```
creates or updates the GitHub Release from
```
releases/vYYYY.MDD.P.md
```

Local emergency/manual commands:

bash

./scripts/release.sh stable --dry-run
./scripts/release.sh stable
git push public-gh refs/tags/vYYYY.MDD.P
./scripts/create-github-release.sh YYYY.MDD.P

常规稳定版路径通过以下方式手动触发

workflow_dispatch

：

```
.github/workflows/release.yml
```

输入信息：

```
source_ref
```
```
stable_date
```
```
dry_run
```

正式发布稳定版前：

使用

./scripts/release.sh stable --date YYYY-MM-DD --print-version

确定目标稳定版版本号

确保源引用上存在
```
releases/vYYYY.MDD.P.md
```
文件
若可行，先以模拟模式运行稳定版工作流
然后执行正式稳定版发布

稳定版工作流：

重新验证精确的源引用
计算选定UTC日期的下一个稳定版补丁段
以
```
latest
```
为分发标签发布
```
YYYY.MDD.P
```
版本
创建git标签
```
vYYYY.MDD.P
```
从
```
releases/vYYYY.MDD.P.md
```
创建或更新GitHub Release

本地紧急/手动命令：

bash

./scripts/release.sh stable --dry-run
./scripts/release.sh stable
git push public-gh refs/tags/vYYYY.MDD.P
./scripts/create-github-release.sh YYYY.MDD.P

Step 7 — Finish the Other Surfaces

步骤7 — 完成其他相关事项

Create or verify follow-up work for:

website changelog publishing
launch post / social announcement
release summary in Paperclip issue context

These should reference the stable release, not the canary.

创建或验证以下后续工作：

网站更新日志发布
发布文章/社交平台公告
在Paperclip议题上下文中添加发布摘要

这些内容应引用稳定版，而非预览版。

Failure Handling

故障处理

If the canary is bad:

publish another canary, do not ship stable

If stable npm publish succeeds but tag push or GitHub release creation fails:

fix the git/GitHub issue immediately from the same release result
do not republish the same version

latest

is bad after stable publish:

bash

./scripts/rollback-latest.sh <last-good-version>

Then fix forward with a new stable release.

若预览版存在问题：

发布另一个预览版，不要推送稳定版

若稳定版npm发布成功，但标签推送或GitHub Release创建失败：

立即从同一发布结果修复git/GitHub问题
不要重新发布相同版本

若稳定版发布后

latest

版本存在问题：

bash

./scripts/rollback-latest.sh <last-good-version>

然后通过新的稳定版发布向前修复问题。

Output

输出结果

When the skill completes, provide:

candidate SHA and tested canary version, if relevant
stable version, if promoted
verification status
npm status
smoke-test status
git tag / GitHub Release status
website / announcement follow-up status
rollback recommendation if anything is still partially complete

技能完成后，提供以下信息：

候选版本SHA和已测试的预览版版本号（如相关）
升级后的稳定版版本号（如适用）
验证状态
npm发布状态
冒烟测试状态
git标签/GitHub Release状态
网站/公告跟进状态
若仍有部分未完成，提供回滚建议