From 5541a41ff72111ef4e2117ebbb01877b18944b63 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 2 Sep 2026 17:21:02 +0800 Subject: [PATCH] =?UTF-8?q?docs(guidelines):=20=E6=96=B0=E5=A2=9E=E7=9B=AE?= =?UTF-8?q?=E9=8C=84=E9=A0=81=E6=A2=9D=E5=88=97=E8=88=87=E5=85=A7=E5=AE=B9?= =?UTF-8?q?=E9=A0=81=E5=9C=96=E8=A1=A8=E5=84=AA=E5=85=88=E7=9A=84=E5=8D=80?= =?UTF-8?q?=E5=88=86=E6=BA=96=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What - 「目錄頁專用存取庫」從四條規則擴成五條，新增的第 5 條把版面判準定下來：目錄頁一律大標題加條列，內容頁才維持圖表優先。 - 第 5 條裡另立一段講 `` 怎麼決定：那是舊表格裡持有內容頁連結那一欄的序號，只在自動轉檔時用得到，序號一律照線上那一頁實際的欄位排法填。 - 目錄頁與內容頁的對照表多一列「版面」。 - 稽核檢查清單新增兩項，一項查目錄頁版面與範本是否照第 5 條，一項查 `` 的填法。 - `MAINTAIN` 沒有內容頁那一段，說法從「寫在表格裡」改成「寫在條列區塊上，一個專案一個 H2 區塊」。 - 跨存取庫沒有原子性那一段，回報對象從「未寫入的目錄列」改成「沒寫進去的目錄頁區塊」。 Why - 這條區分是整組技能之後寫 wiki 的判準。準則裡沒有正本，每支技能各自解讀，改完的範本過一輪又會長回表格。 - `` 填錯的後果是靜默的：標題會轉成那一欄的純文字、跟鍵對不上，既有那一筆被當成新的附加到頁尾，同一筆變成兩個區塊，舊區塊從此再也更新不到，而且不會有任何錯誤訊息。這一輪稽核就抓到六個頁型填錯。 - 範本的欄位順序與線上那一頁常常不一樣，而自動轉檔跑的是線上那一頁，所以序號不能照範本推。 - 檢查清單沒有對應項，這條準則就只剩內文約束，沒有稽核時的把關。 How - 第 5 條寫明目錄頁的三段版面、H2 標題就是鍵且寫成內容頁頁名、欄位格式 `- {欄位名}：{值}`、頁上不留 markdown 表格也不放 mermaid，舊表格頁由工具讀到就自動轉寫回、不另跑批次搬移也不得手工搬。 - `` 那一段要求先把線上那一頁讀回來確認連結落在第幾欄再填，並寫明填錯的靜默後果；線上是空頁、沒有舊表格要轉時照範本填即可。 - 補上「為什麼分兩種」的理由：目錄頁是索引，只給人挑一筆點進去，條列式壞也只壞一塊；內容頁一頁講一件事的全貌，流程與比較拿圖表最省讀者的力氣。 Who - 全部十四種頁型的目錄頁與寫這些頁的每支技能都受這條準則約束。 - 稽核技能多兩項要判的檢查項。 --- references/guidelines.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/references/guidelines.md b/references/guidelines.md index 4cdbda6..86470b8 100644 --- a/references/guidelines.md +++ b/references/guidelines.md @@ -397,7 +397,7 @@ kiro 是唯一真的擋不了的，verdict 據實寫 `degraded`，不寫 `wired` | `TOOLING` | `TOOLING_CONTENTS` | `TOOLING_{HASH}` | 技能盤點目錄、單機單 CLI 的技能盤點頁：一台機器上某一支 CLI 的已安裝 plugin 與版本、可用技能、hook 接線狀態 | jsc-meta | | `MONITOR` | `MONITOR_CONTENTS` | `MONITOR_{HASH}` | 助理巡檢的監控頁。技能與 hook 每跑一次就留下事件，助理把事件收攏、判斷健康狀態、寫進這裡 | jsc-assist | -`MAINTAIN` 沒有內容頁。維護登記全部寫在 `MAINTAIN_CONTENTS` 的表格裡：`jsc-sdlc:implement` 只往那一頁附加登記，`jsc-sdlc:maintain` 只讀那一頁再回寫「前次維護時間」，兩支都沒有產生 `MAINTAIN_{HASH}` 的步驟，`jsc-sdlc/templates/` 也沒有對應範本。總表以前列著這個內容頁，照著找只會找到一個不存在的頁。要補內容頁就先補技能步驟與範本，不能只在總表上寫著。 +`MAINTAIN` 沒有內容頁。維護登記全部寫在 `MAINTAIN_CONTENTS` 的條列區塊上，一個專案一個 H2 區塊：`jsc-sdlc:implement` 只往那一頁附加登記，`jsc-sdlc:maintain` 只讀那一頁再回寫「前次維護時間」，兩支都沒有產生 `MAINTAIN_{HASH}` 的步驟，`jsc-sdlc/templates/` 也沒有對應範本。總表以前列著這個內容頁，照著找只會找到一個不存在的頁。要補內容頁就先補技能步驟與範本，不能只在總表上寫著。 ### 目錄頁專用存取庫 @@ -408,12 +408,13 @@ kiro 是唯一真的擋不了的，verdict 據實寫 `degraded`，不寫 `wired` | 頁名 | `{TYPE}_CONTENTS` | `{TYPE}_{HASH}` | | 存取庫解析 | 一律解 `CONTENTS`：`JSC_WIKI_REPO_CONTENTS` → `JSC_WIKI_REPO` → exit 3 | 解自己的型別：`JSC_WIKI_REPO_{TYPE}` → `JSC_WIKI_REPO` → exit 3 | | 帶雜湊 | 否 | 是 | +| 版面 | 大標題加條列：一筆一個 H2 區塊，欄位一行一條，不留 markdown 表格 | 圖表優先：mermaid 與表格優於散文 | `CONTENTS` 因此是第十五種頁面類型，而且是唯一一種自己沒有頁的：沒有 `CONTENTS_CONTENTS`，也沒有 `CONTENTS_{HASH}`。 它只用來解存取庫，`gitea.sh wiki-repo CONTENTS` 是全部目錄頁的解析入口。 總表列的十四種是頁的分類，`CONTENTS` 是存取庫的分類，兩張清單長度不同是正常的。 -四條規則，寫入前逐條核對： +五條規則，寫入前逐條核對： 1. 任何 `*_CONTENTS` 頁都走 `gitea.sh wiki-repo CONTENTS`，十四種型別的目錄頁全部落在同一個存取庫。 2. 目錄頁的解析鏈**不退回型別變數**。設了 `JSC_WIKI_REPO_LOG` 不會讓 `LOG_CONTENTS` 跟著搬過去。 @@ -425,9 +426,19 @@ kiro 是唯一真的擋不了的，verdict 據實寫 `degraded`，不寫 `wired` **為什麼驗證走 API，不看網頁狀態碼。** 私有存取庫的網頁網址對未登入請求一律回 404。拿網頁狀態碼判斷，會把還在的頁判成死連結，接著整批被刪掉或改寫。金鑰失效那一種也要與死連結分開回報，理由一樣：一次金鑰過期就會把整批好頁判成壞的。 +5. **目錄頁一律「大標題加條列」，內容頁才維持圖表優先。** 這條區分是全技能組的判準，每支技能寫 wiki 前先看自己寫的是哪一種頁。 + + 目錄頁的版面固定三段：H1 頁名、`>` 引言、然後每一筆紀錄一個 H2 區塊。H2 標題就是那一筆的鍵，寫成對應的**內容頁頁名** `{TYPE}_{HASH}`，標題不放連結、不放網址、不加前後綴、不加日期。欄位在標題底下一行一條，格式 `- {欄位名}：{值}`，全形冒號，順序照原欄位從左到右，一欄一條，鍵那一欄照樣留一條，資料才不會少。區塊之間空一行，H2 與第一條之間空一行。**目錄頁不留任何 markdown 表格**，也不放 mermaid。舊頁還是表格時由 `jsc-gitea/tools/wiki-contents.sh` 讀到就自動轉成條列後寫回，不另跑批次搬移，也不得手工搬。 + + **`` 怎麼決定：照線上那一頁實際的欄位排法，不是照範本。** `wiki-contents.sh upsert [template-file]` 的 `` 填的是**舊表格裡持有「內容頁連結」那一欄的序號**，只在舊頁還是表格、需要自動轉檔時才用得到：轉檔時工具從那一欄的連結網址取最後一段路徑當 H2 標題。序號一律先把線上那一頁讀回來（`gitea.sh wiki-get {CONTENTS 存取庫} {TYPE}_CONTENTS`）、看連結實際落在第幾欄再填。**不得照 `templates/` 裡的欄位排法推**：範本的欄位順序與線上那一頁常常不一樣，自動轉檔跑的是線上那一頁。填錯欄的後果是靜默的——標題會轉成那一欄的純文字（例如 `plugins/ask`），跟鍵 `{TYPE}_{HASH}` 對不上，既有那一筆被當成新的附加到頁尾，同一筆變兩個區塊，舊區塊從此再也更新不到，而且不會有任何錯誤訊息。線上是空頁、沒有舊表格要轉時，這個參數影響不到結果，照範本填即可。 + + 內容頁反過來：**圖表優先，mermaid 與表格優於散文**，這一條只針對內容頁，繼續有效。 + + **為什麼分兩種。** 目錄頁是索引，每一筆的欄位一樣多、只給人挑一筆點進去；表格一寬就得橫向捲，欄位一多就對不上表頭，而且併行寫入時只要有人少打一根豎線，整張表就散掉，別人那一筆跟著看不見。條列式一筆一個區塊，寫入端只換自己那一塊，壞掉也只壞自己那一塊。內容頁要的是另一件事：一頁講一件事的全貌，流程與比較拿圖表最省讀者的力氣，所以圖表優先留在內容頁。 + **為什麼要分開。** 目錄頁是全部使用者共用的索引，內容頁按專案或機器分散在各自的存取庫。混在一起的話，換一個專案就換一份索引，「這台機器有哪些頁」永遠問不到完整答案。索引集中一處、內容各自落地，才查得到全貌。 -代價寫明：跨存取庫沒有原子性。內容頁寫成功、目錄頁寫失敗時，據實回報未寫入的目錄列與完整內容，不得反過來先寫目錄頁。 +代價寫明：跨存取庫沒有原子性。內容頁寫成功、目錄頁寫失敗時，據實回報那個沒寫進去的目錄頁區塊與完整內容，不得反過來先寫目錄頁。 `{HASH}` 一律為 `{owner}/{repo}`（必要時加上主題字串）的**完整 SHA-1**，40 碼十六進位，`a-f` 一律轉大寫。 不截短、不加前綴：截短過的舊頁名以 `jsc-gitea/tools/migrate-wiki.sh` 遷移。 @@ -485,6 +496,8 @@ kiro 是唯一真的擋不了的，verdict 據實寫 `degraded`，不寫 `wired` - [ ] gitea 操作透過 gitea.sh 或 tea - [ ] wiki repo 與 Gitea 認證先讀目前 shell 繼承的環境變數；只有缺值或無法解析時才詢問；頁面類型不得跨用其他 `JSC_WIKI_REPO_{TYPE}` - [ ] 目錄頁一律解 `CONTENTS` 存取庫（`gitea.sh wiki-repo CONTENTS`），內容頁解自己的型別；所有連結一律寫成 `[{文字}]({連結})`，網址取自 `gitea.sh wiki-url`，不用 `[[頁名]]` +- [ ] 目錄頁寫成「大標題加條列」：一筆一個 H2 區塊、標題是內容頁頁名 `{TYPE}_{HASH}`、欄位一行一條 `- {欄位名}：{值}`、頁上沒有 markdown 表格；內容頁維持圖表優先（mermaid 與表格優於散文）。技能內文與 `templates/` 的目錄頁樣板都照這一條，寫入一律走 `jsc-gitea/tools/wiki-contents.sh upsert`，不手工改頁。規則見「目錄頁專用存取庫」第 5 條 +- [ ] `wiki-contents.sh upsert` 的 `` 是「舊表格裡持有內容頁連結那一欄的序號」，只供自動轉檔用；序號照**線上那一頁實際的欄位排法**填，先把線上頁讀回來確認，不照 `templates/` 的欄位排法推。規則見「目錄頁專用存取庫」第 5 條的 `` 段 - [ ] 文件裡的連結都經過 `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 決策樹規則