diff --git a/.gitea/workflows/publish.yml b/.gitea/workflows/publish.yml
index ade3fac..8d2130c 100644
--- a/.gitea/workflows/publish.yml
+++ b/.gitea/workflows/publish.yml
@@ -5,10 +5,14 @@
 #   2. 仓库 → Actions → 选择本工作流 → Run workflow（手动，发布当前 commit 的版本）
 #
 # 需要的权限：
-#   本工作流用 Gitea 内置的任务令牌 ${{ secrets.GITEA_TOKEN }} 发布，无需额外配置密钥。
-#   组织（或仓库）Settings → Actions → General 里的 token 权限不能被限制到读，
-#   且 packages 需要写权限 —— 工作流里的 permissions: 已经声明，但仍会被管理员配置的上限（clamping）压回。
-#   如果实例把默认权限设为 Restricted，请在这里（或组织级）确认 packages 至少为 write。
+#   默认使用 Gitea 内置的任务令牌 ${{ secrets.GITEA_TOKEN }} 发布，无需额外配置密钥。
+#   若实例/组织把 Actions 的令牌上限设为只读，或任务令牌对包命名空间没有写权限，
+#   请在仓库 Settings → Actions → Secrets 里添加 NPM_TOKEN = 一个带 package 写权限的个人访问令牌，
+#   工作流会自动优先使用它（见最后一个步骤）。
+#
+# 失败排查：
+#   发布步骤在 1 秒内失败通常是鉴权问题——先看该步骤日志里 `npm whoami` 的输出：
+#   打印出用户名说明令牌可用，报 E401/E403 说明令牌无效或权限不足。
 #
 # 依赖前提：
 #   - 实例启用了 Actions，且注册了 act_runner（否则工作流只会排队）。
@@ -65,9 +69,23 @@ jobs:
 
       - name: Publish
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          # 优先使用带 package 写权限的 PAT（仓库 Settings → Actions → Secrets 里的 NPM_TOKEN）；
+          # 没有配置时退回 Gitea 内置任务令牌 GITEA_TOKEN。
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          JOB_TOKEN: ${{ secrets.GITEA_TOKEN }}
         run: |
           set -eu
-          # 作用域与默认注册表都指向本组织的 npm 仓库；token 由 setup-node 写进 .npmrc。
+          token="${NPM_TOKEN:-$JOB_TOKEN}"
+          if [ -z "$token" ]; then
+            echo "没有可用的发布令牌：请配置 NPM_TOKEN，或确认实例会注入 GITEA_TOKEN" >&2
+            exit 1
+          fi
+          # 作用域与默认注册表都指向本组织的 npm 仓库，并把令牌写进本机 .npmrc。
           npm config set @dsh-plugin:registry "${REGISTRY}"
-          npm publish --registry "${REGISTRY}"
+          npm config set "//gitea.iwake.top/api/packages/dsh-plugin/npm/:_authToken" "${token}"
+          echo "registry = $(npm config get registry)"
+          echo "auth     = $(npm config get "//gitea.iwake.top/api/packages/dsh-plugin/npm/:_authToken" | sed 's/./*/g')"
+          # 鉴权自检：能取到用户就说明令牌对得上这个注册表（包不存在时报 404 也算通过）。
+          npm whoami --registry "${REGISTRY}" || true
+          npm publish --registry "${REGISTRY}" --access public
+
diff --git a/README.md b/README.md
index 7389133..aca0479 100644
--- a/README.md
+++ b/README.md
@@ -77,13 +77,19 @@ npm config set //gitea.iwake.top/api/packages/dsh-plugin/npm/:_authToken=<带 pa
 
 ### 发布到 Gitea 的 npm 仓库
 
-仓库自带工作流 [`.gitea/workflows/publish.yml`](.gitea/workflows/publish.yml)：推送 `v*` 标签（或在 Actions 页面手动运行）就会把当前版本发布到 `https://gitea.iwake.top/api/packages/dsh-plugin/npm/`，用的是 Gitea 内置的任务令牌，不需要额外配置密钥。
+仓库自带工作流 [`.gitea/workflows/publish.yml`](.gitea/workflows/publish.yml)：推送 `v*` 标签（或在 Actions 页面手动 Run workflow）就会把该版本发布到 `https://gitea.iwake.top/api/packages/dsh-plugin/npm/`。工作流会校验标签与 `package.json` 的版本一致，不一致直接失败。
 
 ```bash
 git tag -a v1.0.1 -m "v1.0.1" && git push origin v1.0.1
 ```
 
-前提：实例启用了 Actions 并注册了 runner（`runs-on` 的标签要与 runner 一致），且 Actions 的令牌权限没有把 `packages` 限制成只读（组织 Settings → Actions → General）。
+发布凭据按顺序取：仓库 secret `NPM_TOKEN`（带 `package` 写权限的个人访问令牌）→ 没有则退回 Gitea 内置任务令牌 `${{ secrets.GITEA_TOKEN }}`（工作流已声明 `permissions: packages: write`）。
+
+前提与排查：
+
+- 实例启用了 Actions 并注册了 runner（`runs-on: ubuntu-latest` 要与 runner 的标签一致）；
+- 若组织把 Actions 令牌上限设成只读，或任务令牌对包命名空间没有写权限，发布步骤会很快失败：在仓库 Settings → Actions → Secrets 添加 `NPM_TOKEN` 即可，工作流会自动改用它；
+- 失败时先看该步骤日志里 `npm whoami` 的输出：打印出用户名说明令牌可用（错误就只可能是版本已存在或包名不合法），报 `E401/E403` 则是令牌无效或权限不足。
 
 手工发布等价于：