plugins/ask
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

問詢目錄頁改成大標題加條列，鍵改用問詢紀錄頁頁名 #28

Merged
admin merged 2 commits from feat/contents-list/main into develop 2026-09-02 10:00:27 +00:00
Conversation 0 Commits 2 Files Changed 7
+27 -21
jiantw83 commented 2026-09-02 09:25:25 +00:00
Member
Copy Link
Copy Source

摘要

  • 需求描述：所有 wiki 目錄頁（*_CONTENTS）的呈現格式從 markdown 表格改成「大標題加條列式」——一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵（該筆對應內容頁的實際頁名），欄位是標題底下的一層條列 - {欄位名}：{值}，目錄頁上不留任何 markdown 表格。本存取庫負責問詢目錄頁 QUESTION_CONTENTS 的範本與敘述，實際的轉檔與 upsert 邏輯全部在 gitea/tools/wiki-contents.sh。內容頁維持原本的圖表優先，不在這一輪的範圍。
  • 計畫名稱：無
  • 計畫頁：無
  • 分析頁：無

變更內容

檔案 為什麼改
templates/question-contents.md 版面從三欄 markdown 表格改成一個存取庫一個 H2 區塊，標題是內容頁頁名 QUESTION_{HASH}，欄位改成 - {欄位名}：{值} 的一層條列；引言補上版面規則、參數語意與 {key-col} 填錯的後果
skills/ask/SKILL.md 目錄頁寫入從「列」改成「區塊」：呼叫改成 upsert QUESTION 2 QUESTION_{HASH} {block-file} templates/question-contents.md，wiki-url、link-check.sh、wiki-contents.sh 三段結束碼分流的措辭同步成區塊語意，並補上 wiki-contents.sh 退 1 的新語意
references/behaviors.md 關鍵步驟、外部呼叫、完成條件、可驗證跡象四項同步成條列式目錄頁，可驗證跡象改成驗 H2 區塊、三條 bullet 的順序與格式、整頁不留表格，並加上舊表格頁轉檔後 H1 與引言原樣保留、資料一筆不少的檢查
README.md ask 技能的敘述同步成條列式目錄頁與新的 upsert 呼叫形式
plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 目錄頁格式是破壞性的行為改變，三份 manifest 的版本號一起推進，讓版本守門看得出機器上的副本是舊的

設計重點

  • 鍵改成 H2 標題文字，也就是內容頁頁名 QUESTION_{HASH}：頁名只由 {owner}/{repo} 決定，GITEA_HOST 換掉、JSC_WIKI_REPO_QUESTION 換過存取庫、Gitea 對頁名的網址編碼有差，頁名一個字都不動，鍵永遠比得中既有區塊。標題不放連結、不放網址、不加前後綴。
  • {key-col} 修正為 2。這個參數指舊表格裡持有內容頁連結那一欄的欄位序號，QUESTION_CONTENTS 的舊表格欄序是存取庫名稱、問詢紀錄、最後更新，帶連結的是第 2 欄「問詢紀錄」。原本填成 1 會在自動轉檔時取到純文字的 {owner}/{repo}，標題變成 ## plugins/meta，比不到鍵 QUESTION_{HASH}，既有那一筆被當成新的附加上去，同一個存取庫在頁面上出現兩次，舊區塊從此再也更新不到。
  • 這個參數只在舊頁還是 markdown 表格、要自動轉成條列時才有作用，頁面已經是條列格式就完全忽略它；但它不是死參數，敘述與範本都寫明填錯的後果，避免下一個人隨便填。
  • 第四個參數從「列檔」改成「區塊檔」：內容是整個 H2 區塊的 markdown，包含 ## QUESTION_{HASH} 那一行、一個空行，再接三條欄位 bullet。
  • 只動敘述與範本，不新增任何腳本。讀回整頁、比對鍵、整塊換掉或附加、整頁寫回這一串邏輯全部留在 gitea/tools/wiki-contents.sh 一處。

測試結果

  • 未跑自動化測試：本次變更全部是 markdown 敘述與範本，這個存取庫沒有可執行程式碼，也沒有對應的測試套件。
  • git status --porcelain 在提交後無輸出，git log --oneline origin/develop..HEAD 只有本輪的 commit，工作區乾淨。
  • 註解掃描 jsc-hooks/hooks/comment-scope.sh sweep 在提交前執行，結束碼 0，無命中。變更檔案全是 markdown 與 json，本來就不在該規則的掃描範圍內。
  • 條列格式的實際產出行為由 gitea 那一支的離線驗證 check-contents-format.sh 負責，本存取庫沒有可獨立驗證的執行路徑。

前置 Push Request

## 摘要 - 需求描述：所有 wiki 目錄頁（`*_CONTENTS`）的呈現格式從 markdown 表格改成「大標題加條列式」——一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵（該筆對應內容頁的實際頁名），欄位是標題底下的一層條列 `- {欄位名}：{值}`，目錄頁上不留任何 markdown 表格。本存取庫負責問詢目錄頁 `QUESTION_CONTENTS` 的範本與敘述，實際的轉檔與 upsert 邏輯全部在 `gitea/tools/wiki-contents.sh`。內容頁維持原本的圖表優先，不在這一輪的範圍。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `templates/question-contents.md` | 版面從三欄 markdown 表格改成一個存取庫一個 H2 區塊，標題是內容頁頁名 `QUESTION_{HASH}`，欄位改成 `- {欄位名}：{值}` 的一層條列；引言補上版面規則、參數語意與 `{key-col}` 填錯的後果 | | `skills/ask/SKILL.md` | 目錄頁寫入從「列」改成「區塊」：呼叫改成 `upsert QUESTION 2 QUESTION_{HASH} {block-file} templates/question-contents.md`，`wiki-url`、`link-check.sh`、`wiki-contents.sh` 三段結束碼分流的措辭同步成區塊語意，並補上 `wiki-contents.sh` 退 1 的新語意 | | `references/behaviors.md` | 關鍵步驟、外部呼叫、完成條件、可驗證跡象四項同步成條列式目錄頁，可驗證跡象改成驗 H2 區塊、三條 bullet 的順序與格式、整頁不留表格，並加上舊表格頁轉檔後 H1 與引言原樣保留、資料一筆不少的檢查 | | `README.md` | `ask` 技能的敘述同步成條列式目錄頁與新的 upsert 呼叫形式 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 目錄頁格式是破壞性的行為改變，三份 manifest 的版本號一起推進，讓版本守門看得出機器上的副本是舊的 | ## 設計重點 - 鍵改成 H2 標題文字，也就是內容頁頁名 `QUESTION_{HASH}`：頁名只由 `{owner}/{repo}` 決定，`GITEA_HOST` 換掉、`JSC_WIKI_REPO_QUESTION` 換過存取庫、Gitea 對頁名的網址編碼有差，頁名一個字都不動，鍵永遠比得中既有區塊。標題不放連結、不放網址、不加前後綴。 - `{key-col}` 修正為 `2`。這個參數指舊表格裡持有內容頁連結那一欄的欄位序號，`QUESTION_CONTENTS` 的舊表格欄序是存取庫名稱、問詢紀錄、最後更新，帶連結的是第 2 欄「問詢紀錄」。原本填成 `1` 會在自動轉檔時取到純文字的 `{owner}/{repo}`，標題變成 `## plugins/meta`，比不到鍵 `QUESTION_{HASH}`，既有那一筆被當成新的附加上去，同一個存取庫在頁面上出現兩次，舊區塊從此再也更新不到。 - 這個參數只在舊頁還是 markdown 表格、要自動轉成條列時才有作用，頁面已經是條列格式就完全忽略它；但它不是死參數，敘述與範本都寫明填錯的後果，避免下一個人隨便填。 - 第四個參數從「列檔」改成「區塊檔」：內容是整個 H2 區塊的 markdown，包含 `## QUESTION_{HASH}` 那一行、一個空行，再接三條欄位 bullet。 - 只動敘述與範本，不新增任何腳本。讀回整頁、比對鍵、整塊換掉或附加、整頁寫回這一串邏輯全部留在 `gitea/tools/wiki-contents.sh` 一處。 ## 測試結果 - 未跑自動化測試：本次變更全部是 markdown 敘述與範本，這個存取庫沒有可執行程式碼，也沒有對應的測試套件。 - `git status --porcelain` 在提交後無輸出，`git log --oneline origin/develop..HEAD` 只有本輪的 commit，工作區乾淨。 - 註解掃描 `jsc-hooks/hooks/comment-scope.sh sweep` 在提交前執行，結束碼 0，無命中。變更檔案全是 markdown 與 json，本來就不在該規則的掃描範圍內。 - 條列格式的實際產出行為由 `gitea` 那一支的離線驗證 `check-contents-format.sh` 負責，本存取庫沒有可獨立驗證的執行路徑。 ## 前置 Push Request - [plugins/gitea：wiki 目錄頁改成大標題加條列，舊表格讀到就自動轉檔](https://gitea.jsc.idv.tw/plugins/gitea/pulls/52)——必須先合。實際的轉檔與 upsert 邏輯全部在該存取庫的 `gitea/tools/wiki-contents.sh`，本存取庫只改敘述與範本。前置未合就先部署本存取庫，範本組出來的 H2 區塊會被舊版工具當成表格列附加到表格後面。
jiantw83 added 2 commits 2026-09-02 09:25:26 +00:00
feat(ask): 問詢目錄頁改條列式並修正 key-col 參數 e8294f3891 
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` 修正是同一個需求能正確落地的必要條件，且與版面敘述改在同一段文字上，無法拆成獨立提交。
chore(ask): 插件版本號更新為 0.1.3 9b4100060e 
What：
把 `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 三份 manifest 的 `version` 從 `0.1.2` 改成 `0.1.3`，三份檔案的其餘欄位一字不動。

Why：
本輪技能敘述與範本有行為變更，安裝端是靠 manifest 的 `version` 判斷要不要更新，版本號不動的話已經安裝的機器不會拉到新版。三份 manifest 分別給不同的 CLI 讀取，必須一起前進，只改其中一份會讓各 CLI 認到的版本不一致。

How：
只改三份 manifest 的 `version` 欄位，內容與敘述、範本無關，因此不與需求本身的變更混在一起，獨立成一個提交，讓發版動作在歷史上單獨可追、需要時也能單獨回退。

Who：
屬於插件發版維護，隨本輪目錄頁條列式需求一起放行，本身不改任何技能行為。
admin merged commit 4ff426ca95 into develop 2026-09-02 10:00:27 +00:00
admin deleted branch feat/contents-list/main 2026-09-02 10:00:27 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin (系統管理員) jiantw83 (Jeffery)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Depends on
#52 wiki 目錄頁改成大標題加條列，舊表格讀到就自動轉檔
plugins/gitea
Reference: plugins/ask#28