diff --git a/docs/agents/publish.md b/docs/agents/publish.md
index 7895595..75334d0 100644
--- a/docs/agents/publish.md
+++ b/docs/agents/publish.md
@@ -29,8 +29,9 @@
 1. 确保当前 release tooling 覆盖的包(`tools/release/lib/packages.mjs`)已升到目标版本且一致;当前基础集合为 `packages/core` / `packages/runtime` / `packages/commands` / `packages/cli`，`knowledge-studio-cli` 发布会额外包含 `packages/kscli`
 2. 在 GitHub 触发 Publish workflow，package 选目标包集合，mode 选 `stable`
 3. 需要 production environment 审批人批准
-4. CI 自动：自检 → 构建 → 发布到 latest → 打 git tag
-5. 对应脚本：`tools/release/publish-stable.mjs`
+4. CI 自动：自检 → 构建 → 检查 npm 已发布版本 → 发布到 latest → 打 git tag
+5. 如果所选发布集合的当前版本已全部存在于 npm，stable 发布会失败并提示先升级版本号；如果只有部分包已发布，CI 会继续补发缺失包
+6. 对应脚本：`tools/release/publish-stable.mjs`
 
 ## 自检（`tools/release/check.mjs`）
 
@@ -103,3 +104,4 @@ node tools/release/publish-channel.mjs --channel test --knowledge --dry-run
 | Node 徽章 `>=18`、engines `>=22.12` 不一致               | 用户在 Node 18 上 `npm i` 被 engine 警告或直接失败                                 |
 | npm Trusted Publisher 的 workflow filename 改了没同步    | OIDC 匹配不上，publish 报 404                                                      |
 | CI 用 Node 22（npm 10）跑 publish                        | npm 10 不支持 OIDC token 交换，publish 报 404                                      |
+| stable 发布前没有升级版本号                              | 所选发布集合的版本已全部存在于 npm，CI 明确报错并要求先升级版本号                  |
diff --git a/tools/release/publish-stable.mjs b/tools/release/publish-stable.mjs
index 16bb15a..69aaace 100644
--- a/tools/release/publish-stable.mjs
+++ b/tools/release/publish-stable.mjs
@@ -54,8 +54,9 @@ try {
     log(`${pkg.name}@${version}: ${exists ? "already published" : "to publish"}`);
   }
   if (packages.every((pkg) => published.get(pkg.key))) {
-    log("\nall packages already published; nothing to do.");
-    process.exit(0);
+    throw new Error(
+      `version ${version} is already published for all target packages; bump the package versions before retrying.`,
+    );
   }
 
   // Publish in dependency order (core → runtime → commands → cli [→ kscli]).