docs: refine readme usage guide

README.md

@@ -2,35 +2,46 @@
 
 清理 Gitea NuGet 套件舊版本的 Docker Action。
 
-## 行為
+## 功能
 
-- 預設保留每個套件最新 `2` 個版本。
+- 依序嘗試取得 Gitea API token。
+- 預設每個套件保留最新 `2` 個版本。
 - 預設為 `dry_run=true`，只列出候選，不會真的刪除。
-- Gitea API token 的優先順序如下:
+- 輸出可搜尋的 log，包含 API status、request id 與 summary。
-  - `inputs.runner_token`
+
-  - `secrets.GITEA_TOKEN`
+## Token 來源順序
-  - `secrets.RUNNER_TOKEN`
+
+Action 會依序嘗試以下來源：
+
+1. `inputs.runner_token`
+2. `secrets.GITEA_TOKEN`
+3. `secrets.RUNNER_TOKEN`
+
+若三者都沒有值，Action 會以非零 exit code 結束。
 
 ## Inputs
 
-| 名稱 | 預設值 | 說明 |
+| 名稱 | 類型 | 預設值 | 說明 |
-| --- | --- | --- |
+| --- | --- | --- | --- |
-| `runner_token` | - | 優先使用的 Gitea API token |
+| `runner_token` | string | - | Gitea API token，優先順序最高 |
-| `keep_versions` | `2` | 每個套件要保留的最新版本數，必須是整數且 `>= 0` |
+| `keep_versions` | integer string | `2` | 每個套件要保留的最新版本數，必須是整數且 `>= 0` |
-| `dry_run` | `true` | `true` 只顯示刪除候選，`false` 才會呼叫 DELETE API |
+| `dry_run` | boolean string | `true` | `true` 只列出候選，`false` 才會呼叫 DELETE API |
 
-## Logs
+## Log 行為
 
-Action 會輸出可搜尋的 log，重點包括:
+執行時會輸出這類資訊：
 
-- Token 來源
+- `Trying token from ...`
-- `keep_versions` 與 `dry_run`
+- `Using token from ...`
-- 套件版本排序
+- `keep_versions=...`
-- 候選刪除清單
+- `dry_run=...`
-- HTTP status 與 request id
+- `GET /api/v1/... -> 200 OK`
-- Summary: `packages`、`versions`、`kept`、`candidates`、`deleted`、`skipped`、`errors`
+- `Candidate to delete: ...`
+- `[DRY-RUN] Would delete ...`
+- `Deleted package ... -> 204 No Content`
+- `Summary: packages=... versions=... kept=... candidates=... deleted=... skipped=... errors=...`
 
-## 使用範例
+## Workflow 範例
 
 ### Dry-run
 
@@ -62,5 +73,10 @@ jobs:
 
 ## 測試
 
-- Shell 測試腳本: [`tests/entrypoint.sh`](tests/entrypoint.sh)
+- Shell 測試: [`tests/entrypoint.sh`](tests/entrypoint.sh)
 - Gitea workflow: [`.gitea/workflows/ci.yaml`](.gitea/workflows/ci.yaml)
+
+## 相關檔案
+
+- Action 定義: [`action.yaml`](action.yaml)
+- 執行腳本: [`entrypoint.sh`](entrypoint.sh)