feat(ask): 問詢目錄頁改條列式並修正 key-col 參數

What:
把問詢目錄頁 `QUESTION_CONTENTS` 的呈現格式從 markdown 表格改成條列式——每個存取庫一個 H2 區塊,H2 標題就是該存取庫問詢紀錄頁的頁名 `QUESTION_{HASH}`,欄位改成標題底下一層條列 `- {欄位名}:{值}`,順序維持存取庫名稱、問詢紀錄、最後更新,整頁不再留任何 markdown 表格。同一輪把 `wiki-contents.sh upsert QUESTION` 的呼叫參數從 `1 {owner}/{repo}` 改成 `2 QUESTION_{HASH}`。改動落在 `templates/question-contents.md` 的版面與參數語意、`skills/ask/SKILL.md` 與 `references/behaviors.md` 的步驟敘述與可驗證跡象,以及 `README.md` 的技能描述。

Why:
表格版面一列塞滿所有欄位,欄位一長就難讀,每一筆的鍵也埋在儲存格裡;改成一筆一個 H2 區塊之後,鍵就是標題文字,人與工具都直接看得出哪一筆對應哪一個內容頁。`key-col` 原本填 `1`,指到的是純文字的存取庫名稱欄:舊表格自動轉條列時,工具會拿那一欄的連結產生 H2 標題,填 `1` 只會做出 `## plugins/meta` 這種標題,比不到鍵 `QUESTION_{HASH}`,既有那一筆會被當成新的附加上去,同一個存取庫在頁面上出現兩個區塊,舊區塊從此再也更新不到。

How:
`templates/question-contents.md` 的範本主體從表頭加資料列換成 `## QUESTION_{HASH}` 加三條 bullet,引言補上版面段與參數語意段,寫明 `{key}` 是 H2 標題文字、第四個參數帶的是整個區塊的 markdown 而不是單列。`skills/ask/SKILL.md` 把目錄頁那幾條的 row 敘述全部改成 block,呼叫式改為 `upsert QUESTION 2 QUESTION_{HASH} {block-file} templates/question-contents.md`,並說明 `key-col` 為什麼固定是 `2`、填 `1` 會壞成什麼樣,另外在 `wiki-contents.sh` 退 1 的分支補上「頁面上還沒有自己那個區塊不算失敗,那是附加的情形」。`references/behaviors.md` 的關鍵步驟補上區塊檔的組法與參數語意,外部呼叫改成單一 H2 區塊的讀取、合併、寫回,可驗證跡象改成檢查該區塊三條 bullet 的齊全度、順序、全形冒號與整頁不留表格,並補上舊表格轉條列後 H1 與 `>` 引言原樣保留、原有資料一筆不少。`README.md` 的技能描述同步改成條列式的說法。實際的轉檔與 upsert 邏輯在另一個存取庫的 `gitea/tools/wiki-contents.sh`,本存取庫只調整敘述與範本。

Who:
屬於 wiki 目錄頁一律改條列式呈現的需求,`ask` 這一支負責 `QUESTION_CONTENTS` 的範本與敘述。`key-col` 修正是同一個需求能正確落地的必要條件,且與版面敘述改在同一段文字上,無法拆成獨立提交。
This commit is contained in:
2026-09-02 17:24:49 +08:00
parent fd690aa46e
commit e8294f3891
4 changed files with 24 additions and 18 deletions
+13 -7
View File
@@ -1,13 +1,19 @@
# 問詢目錄
> 由 `jsc-ask:ask` 維護。這是問詢目錄頁 `QUESTION_CONTENTS`,落在 `JSC_WIKI_REPO_CONTENTS` 解出的專用存取庫,和問詢紀錄頁不同庫。每個存取庫一列;`QUESTION_{HASH}` 的 `{HASH}` 執行 `jsc-gitea/tools/hash-id {owner}/{repo}` 取得,原樣採用它印出的完整 40 碼大寫十六進位,不截短、不加前綴(共用 wiki hash 規則,演算法見 `jsc-meta` 的 `references/guidelines.md`)。
> 由 `jsc-ask:ask` 維護。這是問詢目錄頁 `QUESTION_CONTENTS`,落在 `JSC_WIKI_REPO_CONTENTS` 解出的專用存取庫,和問詢紀錄頁不同庫。每個存取庫一個區塊;`QUESTION_{HASH}` 的 `{HASH}` 執行 `jsc-gitea/tools/hash-id {owner}/{repo}` 取得,原樣採用它印出的完整 40 碼大寫十六進位,不截短、不加前綴(共用 wiki hash 規則,演算法見 `jsc-meta` 的 `references/guidelines.md`)。
>
> 寫入語意:一列代表一個存取庫。一律用 `jsc-gitea/tools/wiki-contents.sh upsert` 寫入:它讀回整頁,該存取庫已經有列就更新那一列,沒有才在文末附加一列,最後整頁寫回。只動自己那一列,禁止整頁覆蓋,也不得改動別人的列。
> 版面:H1 頁名、這段 `>` 引言,然後每個存取庫一個 H2 區塊。H2 標題就是該存取庫的問詢紀錄頁頁名 `QUESTION_{HASH}`,標題不放連結、不放網址、不加前後綴。欄位一條一行,格式 `- {欄位名}:{值}`,全形冒號,順序是存取庫名稱、問詢紀錄、最後更新。標題與第一條之間空一行,區塊之間空一行。頁面上不留 markdown 表格。
>
> 連結寫法:問詢紀錄那一欄一律寫成 `[{文字}]({連結})`,連結取自 `jsc-gitea/tools/gitea.sh wiki-url` 印出的絕對網址,不自行組路徑。兩頁分屬不同存取庫,只有絕對網址連得過去。
> 寫入語意:一個區塊代表一個存取庫。一律用 `jsc-gitea/tools/wiki-contents.sh upsert` 寫入:它讀回整頁,該存取庫已經有區塊就整塊換掉,沒有才在文末附加一個區塊,最後整頁寫回。只動自己那個區塊,禁止整頁覆蓋,也不得改動別人的區塊。
>
> 連結驗證:這一列寫進頁面前,先把該列的每一個連結交給 `jsc-gitea/tools/link-check.sh`,結束碼 0 才寫入。有任一筆 DEAD 就整列不寫,把連不到的清單回報給呼叫端。結束碼 3 代表 `GITEA_HOST` 沒設定,先設定再驗證,不得跳過;結束碼 7 代表金鑰失效,停下來回報,別把還在的頁當成死連結。
> 參數語意:`upsert QUESTION 2 {key} {區塊檔} {範本}`。第二個參數是 `{key-col}`,指舊表格裡持有內容頁連結那一欄的欄位序號(1 起算);本頁舊表格的欄序是存取庫名稱、問詢紀錄、最後更新,帶連結的是第 2 欄「問詢紀錄」,所以這裡固定帶 `2`。它只在舊頁還是 markdown 表格、要自動轉成條列時才用得到,頁面已經是條列格式就完全忽略它;但它不是死參數,也不能隨便填:轉檔時工具會拿那一欄的連結產生 H2 標題,填成 `1` 就取到純文字的 `{owner}/{repo}`,標題變成 `## plugins/meta`,比不到鍵 `QUESTION_{HASH}`,既有那一筆會被當成新的附加上去,同一個存取庫在頁面上出現兩次,舊區塊從此再也更新不到。`{key}` 是 H2 標題文字,也就是內容頁頁名 `QUESTION_{HASH}`,用來找既有區塊。第四個參數是區塊檔,內容是整個 H2 區塊的 markdown,不是單列。
>
> 連結寫法:問詢紀錄那一條一律寫成 `[{文字}]({連結})`,連結取自 `jsc-gitea/tools/gitea.sh wiki-url` 印出的絕對網址,不自行組路徑。兩頁分屬不同存取庫,只有絕對網址連得過去。
>
> 連結驗證:這個區塊寫進頁面前,先把區塊裡的每一個連結交給 `jsc-gitea/tools/link-check.sh`,結束碼 0 才寫入。有任一筆 DEAD 就整個區塊不寫,把連不到的清單回報給呼叫端。結束碼 3 代表 `GITEA_HOST` 沒設定,先設定再驗證,不得跳過;結束碼 7 代表金鑰失效,停下來回報,別把還在的頁當成死連結。
| 存取庫名稱 | 問詢紀錄 | 最後更新 |
| --- | --- | --- |
| {owner}/{repo} | [QUESTION_{HASH}]({wiki-url 印出的絕對網址}) | {yyyy-MM-dd HH:mm} |
## QUESTION_{HASH}
- 存取庫名稱:{owner}/{repo}
- 問詢紀錄:[QUESTION_{HASH}]({wiki-url 印出的絕對網址})
- 最後更新:{yyyy-MM-dd HH:mm}