技能準則新增目錄頁條列與內容頁圖表優先的區分，兩個目錄頁範本與六支技能同步 #67
No Assignees
Notifications
Due Date
No due date set.
Depends on
#52 wiki 目錄頁改成大標題加條列，舊表格讀到就自動轉檔
plugins/gitea
Reference: plugins/meta#67
Reference in New Issue
Block a user
摘要
*_CONTENTS）的呈現格式從 markdown 表格改成大標題加條列。一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵、寫成該筆對應內容頁的實際頁名，欄位是標題底下的一層條列- {欄位名}：{值}，目錄頁上不留任何 markdown 表格。內容頁維持原本的圖表優先，不在本輪範圍。本存取庫負責兩件事：把自己的兩個目錄頁範本轉成條列，並把這條版面區分寫進技能準則當成整組技能之後的判準。變更內容
templates/skillset-contents.mdSKILLSET_CONTENTS的版面從表格改成一筆一個 H2 區塊，標題寫成內容頁的實際頁名，欄位改成標題底下一層條列；寫入示例補上鍵這個引數並註明第四個引數是區塊檔templates/tooling-contents.md##區段併進>引言，正式頁上才不會被讀成一筆假紀錄templates/skillset-page.mdtemplates/tooling-page.mdreferences/guidelines.md<key-col>專節；對照表多一列「版面」；稽核檢查清單新增兩項；MAINTAIN與跨存取庫原子性兩段改用區塊的說法skills/skill-new/SKILL.mdskills/skill-update/SKILL.mdskills/skill-delete/SKILL.mdskills/skillset-update/SKILL.mdskills/skill-check/SKILL.mdskills/tooling-guide/SKILL.mdreferences/behaviors.mdREADME.mdTOOLING範本語意相反那一段補上「版面也相反」plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json設計重點
guidelines.md新增的第 5 條是本輪最要緊的產出，也是整組技能之後的判準。 全文重點四項：>引言、然後每一筆一個 H2 區塊；H2 標題就是那一筆的鍵、寫成對應內容頁的實際頁名，標題不放連結、不放網址、不加前後綴、不加日期；欄位在標題底下一行一條，格式- {欄位名}：{值}，全形冒號，順序照原欄位從左到右，鍵那一欄照樣留一條；區塊之間空一行。目錄頁不留任何 markdown 表格，也不放 mermaid。 舊頁還是表格時由工具讀到就自動轉成條列後寫回，不另跑批次搬移，也不得手工搬。<key-col>照線上那一頁實際的欄位排法填，不是照範本。 那個序號填的是舊表格裡持有「內容頁連結」那一欄的位置，只在舊頁還是表格、需要自動轉檔時才用得到：轉檔時工具從那一欄的連結網址取最後一段路徑當 H2 標題。序號一律先把線上那一頁讀回來、看連結實際落在第幾欄再填，不得照templates/裡的欄位排法推，因為範本的欄位順序與線上那一頁常常不一樣，而自動轉檔跑的是線上那一頁。templates/的目錄頁樣板是否照第 5 條，一項查<key-col>是否照線上欄位填。沒有這兩項，這條準則只剩內文約束，稽核時沒有把關。<key-col>原本填錯（問答、計畫、分析、交付、盤點、技能組異動），已逐頁對回線上實際欄位修正；另外三個範本除了示範區塊還留著說明用的##區段，會在正式頁上被讀成假紀錄，說明內容搬進>引言。wiki-contents.sh。測試結果
tools/ste100-lint.sh：對本存取庫全部改動檔案退出 0，無中國用語、中文句內半形標點、AI 套話、簡體字與中文並列斜線。jsc-hooks/hooks/comment-scope.sh sweep：退出 0，工作區沒有夾帶文件追蹤資訊的註解。前置 Push Request
wiki-contents.sh；那一支沒合就先部署本存取庫，本輪範本組出來的 H2 區塊會被舊版工具當成表格列直接附加到表格後面，線上目錄頁會變成半表格半條列。相依已用gitea.sh pr-depend掛上。What - `templates/skillset-contents.md`：`SKILLSET_CONTENTS` 的版面從 markdown 表格改成一筆一個 H2 區塊，標題寫成該筆對應內容頁的實際頁名，欄位改成標題底下的一層條列。 - `templates/tooling-contents.md`：同樣轉條列，原本說明用的 `## ` 區段併進 `>` 引言，正式頁上才不會被讀成一筆假紀錄。 - `templates/skillset-page.md`、`templates/tooling-page.md`：引言補上目錄頁與內容頁的版面差別，內容頁本身維持圖表優先、不改版面。 - `README.md`：兩份目錄頁範本的說明同步改寫，兩份 `TOOLING` 範本語意相反那一段補上「版面也相反」。 Why - 目錄頁是全部使用者共用的索引。表格一寬就得橫向捲、欄位一多就對不上表頭，而且併行寫入時只要有人少打一根豎線，整張表就散掉，別人那一筆跟著看不見。 - 條列式一筆一個區塊，寫入端只換自己那一塊，壞掉也只壞自己那一塊。 - 三個範本原本除了示範區塊之外還留著說明用的 `## ` 區段，轉條列後那種區段會在正式頁上被當成一筆紀錄讀進去。 How - 一頁固定三段：H1 頁名、`>` 引言、然後每一筆一個 H2 區塊；區塊之間空一行，H2 與第一條之間空一行。 - 欄位在標題底下一行一條，格式 `- {欄位名}：{值}`，全形冒號，順序照原本的欄位從左到右，鍵那一欄照樣留一條。 - 寫入示例改成 `wiki-contents.sh upsert {TYPE} {鍵欄} "{內容頁頁名}" {區塊檔}`，並註明鍵欄是舊表格裡持有內容頁連結那一欄的序號、只供自動轉檔用、要照線上那一頁實際的欄位排法填。 - 頁上不留任何 markdown 表格，也不放 mermaid。 Who - 影響照這兩個範本寫目錄頁的技能：`skill-new`、`skill-update`、`skill-delete`、`skillset-update`、`skill-check` 與 `tooling-guide`。 - 舊頁的轉檔與單一區塊 upsert 的實作不在本存取庫，本存取庫只提供範本與說明。What - 「目錄頁專用存取庫」從四條規則擴成五條，新增的第 5 條把版面判準定下來：目錄頁一律大標題加條列，內容頁才維持圖表優先。 - 第 5 條裡另立一段講 `<key-col>` 怎麼決定：那是舊表格裡持有內容頁連結那一欄的序號，只在自動轉檔時用得到，序號一律照線上那一頁實際的欄位排法填。 - 目錄頁與內容頁的對照表多一列「版面」。 - 稽核檢查清單新增兩項，一項查目錄頁版面與範本是否照第 5 條，一項查 `<key-col>` 的填法。 - `MAINTAIN` 沒有內容頁那一段，說法從「寫在表格裡」改成「寫在條列區塊上，一個專案一個 H2 區塊」。 - 跨存取庫沒有原子性那一段，回報對象從「未寫入的目錄列」改成「沒寫進去的目錄頁區塊」。 Why - 這條區分是整組技能之後寫 wiki 的判準。準則裡沒有正本，每支技能各自解讀，改完的範本過一輪又會長回表格。 - `<key-col>` 填錯的後果是靜默的：標題會轉成那一欄的純文字、跟鍵對不上，既有那一筆被當成新的附加到頁尾，同一筆變成兩個區塊，舊區塊從此再也更新不到，而且不會有任何錯誤訊息。這一輪稽核就抓到六個頁型填錯。 - 範本的欄位順序與線上那一頁常常不一樣，而自動轉檔跑的是線上那一頁，所以序號不能照範本推。 - 檢查清單沒有對應項，這條準則就只剩內文約束，沒有稽核時的把關。 How - 第 5 條寫明目錄頁的三段版面、H2 標題就是鍵且寫成內容頁頁名、欄位格式 `- {欄位名}：{值}`、頁上不留 markdown 表格也不放 mermaid，舊表格頁由工具讀到就自動轉寫回、不另跑批次搬移也不得手工搬。 - `<key-col>` 那一段要求先把線上那一頁讀回來確認連結落在第幾欄再填，並寫明填錯的靜默後果；線上是空頁、沒有舊表格要轉時照範本填即可。 - 補上「為什麼分兩種」的理由：目錄頁是索引，只給人挑一筆點進去，條列式壞也只壞一塊；內容頁一頁講一件事的全貌，流程與比較拿圖表最省讀者的力氣。 Who - 全部十四種頁型的目錄頁與寫這些頁的每支技能都受這條準則約束。 - 稽核技能多兩項要判的檢查項。What - `skills/skill-new`、`skills/skill-update`、`skills/skill-delete`、`skills/skillset-update`、`skills/skill-check`：目錄頁寫入步驟的呼叫從「單列 upsert」改成單一 H2 區塊 upsert，鍵補上內容頁頁名這個引數，並註明第四個引數是區塊檔而不是列檔。 - `skills/tooling-guide`：盤點結果寫回目錄頁的敘述照同一套改寫，並寫明鍵是內容頁頁名。 - `references/behaviors.md`：六支技能的關鍵步驟、外部呼叫與可驗證跡象三列同步，跡象從「留下自己那一列」改成留下自己那一個 H2 區塊，區塊內的連結寫成一條欄位。 Why - 範本與準則已經改成條列版面，技能內文還寫著「那一列」，執行時就會照舊敘述組出表格列，跟工具的區塊 upsert 對不上。 - 呼叫少帶鍵這個引數，工具無從判斷要換掉哪一個區塊，同一筆會被當成新的附加上去。 - 行為清單是稽核與驗證的比對基準，敘述沒跟上，稽核會拿舊描述判合規。 How - 六支技能的呼叫一律寫成 `wiki-contents.sh upsert {TYPE} {鍵欄} "{內容頁頁名}" {區塊檔} [{範本}]`，並在旁邊點明目錄頁一律大標題加條列。 - 完成條件與可驗證跡象改用區塊的說法，連結範例改成 `- {欄位名}：[{頁名}]({連結})` 的形態。 - 只改敘述，不動任何腳本；轉檔與 upsert 的實作在別的存取庫。 Who - 本存取庫六支會寫目錄頁的技能。 - 稽核與驗證流程改拿新的行為清單比對。