chore(plugin 版本): 三家 manifest 升版 0.1.4

This commit is contained in:
2026-08-14 18:25:41 +08:00
parent f59a6865ae
commit 0ce8979de4
4 changed files with 47 additions and 54 deletions
+4 -3
View File
@@ -86,7 +86,7 @@ description: JSC plugins 共用「Gitea 工具規範」:tea 或 Gitea REST API
- API base:`https://<host>/api/v1`(repo 層:`https://<host>/api/v1/repos/<owner>/<repo>`)。
- 標頭:`Authorization: token $GITEA_TOKEN`。
- **分頁必須完整讀取**:持續累加 `page` 直到回傳筆數 `< limit`(或回空陣列)為止,不可只取第一頁。
- 寫入(議題描述/留言/PR body)以 **UTF-8 JSON 檔**帶入(如 `--data @body.json`);換行必須是**實際換行**,不可讓內容顯示字面 `\n`(編碼細節見 `/jsc-shared:spec-output`)。
- 寫入(議題描述/留言/PR body)以 **UTF-8 JSON body** 帶入;wiki 寫入則使用 `content_base64`,值必須是 wiki Markdown 內容先以 UTF-8 編碼再 base64 編碼的結果,不能用 `content`、不能用 `@file` 形式。換行必須是**實際換行**,不可讓內容顯示字面 `\n`(編碼細節見 `/jsc-shared:spec-output`)。
- API 失敗(401/403/網路錯誤)→ 回報錯誤(**遮蔽 token**)並停止;401/403 多半是 token 失效或權限不足。
- 版本相依端點(project/column/dependency 等)先以 GET 探測(404/501 視為不支援),**不得對未確認存在的端點做寫入**。
@@ -107,11 +107,12 @@ Gitea wiki 的「title」與實際存放用的「sub_url/檔名」不是同一
sub_url 使用(新頁尚未建立時的合理退路)。
3. **建立新頁不必自行轉義**:`POST /wiki/new` 直接帶完整、人類可讀的 title 字串即可
(含空白與符號皆可),轉義是 Gitea 伺服器端完成的,呼叫端不用預先處理。
4. 若寫入策略是透過 **git clone/push** 直接操作 wiki repo 產生 `.md` 檔(而非呼叫
4. **wiki 讀回驗證以正文為準**:寫入後一律再呼叫 `GET /repos/<owner>/<repo>/wiki/page/<sub_url>` 讀回內容驗證,不可只確認建立成功;若回應含 `content_base64`,以 base64 解碼後的 Markdown 做比對;若回應格式不同,依官方 API 文件與實際回應欄位抽取正文後再比對。
5. 若寫入策略是透過 **git clone/push** 直接操作 wiki repo 產生 `.md` 檔(而非呼叫
REST API),則不必還原 Gitea 的內部轉義:改由呼叫端自建一份「工作路徑 → 儲存
檔名」manifest(例如 `_paths.json`),寫入時查 manifest 決定檔名、讀回時查 manifest
還原原始路徑,全程不依賴、也不猜測 Gitea 從檔名反推 title 的規則。
5. 兩種寫入策略(REST API 查表 vs git clone/push + 自建 manifest)各有各的理由,
6. 兩種寫入策略(REST API 查表 vs git clone/push + 自建 manifest)各有各的理由,
不合併;但上述查表優先、不猜測轉義的原則對兩者都適用。
參考實作:`doc/scripts/worklog/wiki_api.py` 的 `resolve_sub_url()` 走 REST API 查表