feat(link): 連結一律寫成 [文字](絕對網址),寫入前先驗證連得到

取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法,不再分「同存取庫」與
「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析,寫錯不報錯,畫面上
看起來像普通文字或死連結,巡不到也修不了。

連結寫進頁面前先過 jsc-gitea 的 link-check.sh,結束碼 0 才寫。驗證一律走 API,
不看網頁狀態碼:私有存取庫的網頁網址對未登入請求一律回 404,拿狀態碼判會把
好連結判成壞的。認證失敗回 7,與死連結的 1 分開,免得金鑰一過期就把還在的頁
整批判死。
This commit is contained in:
2026-09-02 14:27:18 +08:00
parent 3c9137a81d
commit 651ddb3a6f
11 changed files with 154 additions and 44 deletions
+10 -3
View File
@@ -377,11 +377,17 @@ kiro 是唯一真的擋不了的,verdict 據實寫 `degraded`,不寫 `wired`
它只用來解存取庫,`gitea.sh wiki-repo CONTENTS` 是全部目錄頁的解析入口。
總表列的十四種是頁的分類,`CONTENTS` 是存取庫的分類,兩張清單長度不同是正常的。
三條規則,寫入前逐條核對:
四條規則,寫入前逐條核對:
1. 任何 `*_CONTENTS` 頁都走 `gitea.sh wiki-repo CONTENTS`,十四種型別的目錄頁全部落在同一個存取庫。
2. 目錄頁的解析鏈**不退回型別變數**。設了 `JSC_WIKI_REPO_LOG` 不會讓 `LOG_CONTENTS` 跟著搬過去。
3. 目錄頁指向內容頁的連結**一律用絕對網址**(`{GITEA_HOST}/{owner}/{repo}/wiki/{頁名}`),不用 `[[頁名]]` 這種同 wiki 連結。兩頁跨存取庫,同 wiki 連結會指到目錄頁自己那個存取庫裡不存在的頁,點下去是 404,而且看起來像頁沒寫成功。
3. **文字加連結一律寫成 `[{文字}]({連結})`。** 不分目錄頁或內容頁,也不分同存取庫或跨存取庫,全部只有這一種寫法。`[[頁名]]` 與 `[[顯示文字|頁名]]` 兩種同 wiki 連結全面取消。網址取自 `jsc-gitea/tools/gitea.sh wiki-url`,不自行組路徑。
**為什麼只留一種寫法。** `[[...]]` 只在目前這個 wiki 內解析。寫錯不會報錯,畫面上看起來像正常文字或死連結,巡不到也修不了。兩種寫法並存就得逐處判斷兩端各自解到哪個存取庫;統一成一種,這個判斷消失。
4. **連結先驗證連得到,才可以寫進文件。** 寫入任何文件前,把要放進去的每一個連結交給 `jsc-gitea/tools/link-check.sh`,結束碼 0 才寫入。有任何一筆連不到就不寫入,把連不到的清單回報給呼叫端。結束碼分流以那支腳本的檔頭為準:0 才寫入,1 不得寫入並回報死連結那幾筆,2 與 3 補齊參數或 `GITEA_HOST` 再呼叫,7 停下來回報金鑰問題。
**為什麼驗證走 API,不看網頁狀態碼。** 私有存取庫的網頁網址對未登入請求一律回 404。拿網頁狀態碼判斷,會把還在的頁判成死連結,接著整批被刪掉或改寫。金鑰失效那一種也要與死連結分開回報,理由一樣:一次金鑰過期就會把整批好頁判成壞的。
**為什麼要分開。** 目錄頁是全部使用者共用的索引,內容頁按專案或機器分散在各自的存取庫。混在一起的話,換一個專案就換一份索引,「這台機器有哪些頁」永遠問不到完整答案。索引集中一處、內容各自落地,才查得到全貌。
@@ -442,7 +448,8 @@ kiro 是唯一真的擋不了的,verdict 據實寫 `degraded`,不寫 `wired`
- [ ] 細節流程已標示 MUST run as a sub agent
- [ ] gitea 操作透過 gitea.sh 或 tea
- [ ] wiki repo 與 Gitea 認證先讀目前 shell 繼承的環境變數;只有缺值或無法解析時才詢問;頁面類型不得跨用其他 `JSC_WIKI_REPO_{TYPE}`
- [ ] 目錄頁一律解 `CONTENTS` 存取庫(`gitea.sh wiki-repo CONTENTS`),內容頁解自己的型別;目錄頁指向內容頁的連結用絕對網址
- [ ] 目錄頁一律解 `CONTENTS` 存取庫(`gitea.sh wiki-repo CONTENTS`),內容頁解自己的型別;所有連結一律寫成 `[{文字}]({連結})`,網址取自 `gitea.sh wiki-url`,不用 `[[頁名]]`
- [ ] 文件裡的連結都經過 `jsc-gitea/tools/link-check.sh` 驗證(結束碼 0 才寫入)且格式為 `[{文字}]({連結})`;`tools/check-link-format.sh {domain-path}` 對該 domain 退出 0,退出 3 是「什麼都沒掃」,不算通過
- [ ] 頁名樣式三處一致:`jsc-gitea/tools/page-name.sh`(正本)、`jsc-hooks/hooks/comment-scope.sh`、`jsc-log/tools/worklog-pending.sh`,`tools/check-page-name.sh {root}` 退出 0;退出 3 是「什麼都沒查」,不算通過。三處刻意不共用函式,因為 hook 必須自足,不得在執行期相依別的 plugin 路徑
- [ ] 問詢透過 jsc-ask 決策樹規則
- [ ] `tools/` 與 `hooks/` 內的 shell 腳本都通過 `sh -n`;技能直接呼叫的腳本都存在、可執行,且退出碼有分流