From c842cd01183611558f246071977d29a853214cc7 Mon Sep 17 00:00:00 2001
From: pyh <pyhos@foxmail.com>
Date: Wed, 30 Sep 2026 14:14:55 +0800
Subject: [PATCH] docs(ci): describe the job token honestly instead of
 promising it

The first run failed with E401 while using the built-in token and before the workflow declared permissions, so nothing here proves the job token cannot publish. The header now says a write:package token is what makes publishing reliable, that the job token depends on the instance's Actions token settings, and that permissions: packages: write is what keeps a restricted token from being read-only.
---
 .gitea/workflows/publish.yml | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

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 一致。