diff --git a/.gitea/workflows/publish.yml b/.gitea/workflows/publish.yml
index 87aed95..7460ea3 100644
--- a/.gitea/workflows/publish.yml
+++ b/.gitea/workflows/publish.yml
@@ -11,11 +11,14 @@
 # 已发布的版本不会让工作流失败：注册表返回 409（version already exists）时这一步记为
 # “已存在，本次跳过”，所以手动重跑同一个版本是安全的。
 #
-# 需要的权限：
-#   默认使用 Gitea 内置的任务令牌 ${{ secrets.GITEA_TOKEN }} 发布。
-#   若实例/组织把 Actions 的令牌上限设为只读，或任务令牌对包命名空间没有写权限，
-#   就配置一个带 write:package 权限的个人访问令牌（组织或仓库级 secret NPM_TOKEN），
-#   工作流会自动优先使用它。
+# 需要的凭据：
+#   发包需要一个「对目标包命名空间有写权限」的令牌。工作流优先用 secret NPM_TOKEN
+#   （个人访问令牌，权限勾 write:package；仓库级或组织级 secret 均可），没配才退回
+#   内置任务令牌 ${{ secrets.GITEA_TOKEN }}。
+#   内置任务令牌能否发包，取决于实例/组织 Settings → Actions 的令牌权限（permissive 还是
+#   restricted，以及上限），以及该令牌是否覆盖目标的包命名空间；Gitea 文档只承诺它访问
+#   “本仓库”。因此**想稳定发布就配 NPM_TOKEN**，除非你实测过本实例的内置令牌可用。
+#   工作流已声明 permissions: packages: write —— 没有这行时，restricted 模式下令牌是只读的。
 #
 # 依赖前提：
 #   - 实例启用了 Actions 并注册了 act_runner；runs-on 的标签要与 runner 一致。