釋出：五個目錄頁範本改條列式、技能敘述同步、收尾事件回報與連結驗證 #61
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: plugins/sdlc#61
Reference in New Issue
Block a user
摘要
deploy.shclone 的是預設分支，沒進 master 的東西部署不到。這一批的內容
skill-end事件版號 0.2.9 到 0.3.2。
這一批的邊界
程式碼與文件都是既有的，這張只做釋出，一個字都沒改。
前置 Push Request
What - `templates/plan-contents.md`、`templates/analyze-contents.md`、`templates/repo-contents.md`、`templates/deliver-contents.md`、`templates/maintain-contents.md` 的版面從 markdown 表格改成一筆一個 H2 區塊，欄位改成標題底下的一層條列。 - 四個有內容頁的型別，H2 標題寫成該筆對應內容頁的實際頁名；`MAINTAIN` 沒有內容頁，標題改用該存取庫的 `{owner}/{repo}`。 - 各範本的引言補上版面段，並把寫入語意從「單列 upsert」改寫成單一區塊 upsert，末端的示範資料改成一個完整的 H2 區塊。 - 引言裡寫明鍵欄的語意與各頁的正確序號，並點出填錯的靜默後果。 Why - 目錄頁是全部使用者共用的索引。表格一寬就得橫向捲、欄位一多就對不上表頭，而且併行寫入時只要有人少打一根豎線，整張表就散掉，別人那一筆跟著看不見。 - 條列式一筆一個區塊，寫入端只換自己那一塊，壞掉也只壞自己那一塊。 - `MAINTAIN` 整個型別只有目錄頁，硬套內容頁頁名當標題會指向一個不存在的頁；存取庫名不會漂移，當鍵一樣穩。 - 鍵欄填錯時工具不會報錯，既有那一筆會被當成新的附加到頁尾，同一筆變兩個區塊，舊區塊從此再也更新不到，所以範本要把序號寫死。 How - 一頁固定三段：H1 頁名、`>` 引言、然後每一筆一個 H2 區塊；欄位格式 `- {欄位名}：{值}`，全形冒號，順序照原本的欄位從左到右，鍵那一欄照樣留一條。 - 寫入示例統一成 `wiki-contents.sh upsert {TYPE} {鍵欄} "{鍵}" {區塊檔} [{本範本}]`，並註明第四個引數是整個 H2 區塊的 markdown，不是列檔。 - 頁上不留任何 markdown 表格；內容頁範本不在本輪範圍，維持圖表優先。 Who - 影響照這五個範本寫目錄頁的四支階段技能。 - 舊表格頁的自動轉檔與單一區塊 upsert 的實作不在本存取庫，本存取庫只提供範本與敘述。What - `skills/plan`、`skills/analyze`、`skills/implement`、`skills/maintain`：目錄頁的讀取敘述改成從 H2 區塊取值，寫入敘述從「單列 upsert」改成單一 H2 區塊 upsert，鍵補上內容頁頁名這個引數，並註明第四個引數是區塊檔。 - `skills/maintain`：讀寫的鍵改成該存取庫的 `{owner}/{repo}`，因為這個型別沒有內容頁。 - `references/behaviors.md`：四支技能的關鍵步驟、外部呼叫與可驗證跡象同步，跡象從「留下那一列」改成留下那一個 H2 區塊。 - `references/consensus.md`：查已答問題那一條補上問答目錄頁也是條列式版面、要從區塊取值而不是表格列。 - `references/stage-report.md`：目錄頁也算寫入那一段補上「改動一個區塊也算寫過那一頁」，並統一用 `CONTENTS` 這個型別餵進去。 - `README.md`：四支技能的流程敘述與 wiki 規則段同步，並補上五個目錄頁的版面規則、鍵的落點與各頁鍵欄的正確序號。 Why - 範本已經改成條列版面，技能內文還寫著「那一列」，執行時就會照舊敘述組出表格列，跟工具的單一區塊 upsert 對不上。 - 讀取端的敘述沒跟著改，技能會拿表格的解析方式去讀一頁條列，既有紀錄一筆都認不出來。 - 呼叫少帶鍵這個引數，工具無從判斷要換掉哪一個區塊，同一筆會被當成新的附加上去。 - 行為清單是稽核與驗證的比對基準，敘述沒跟上，稽核會拿舊描述判合規。 How - 四支技能的呼叫一律寫成 `wiki-contents.sh upsert {TYPE} {鍵欄} "{鍵}" {區塊檔} [{範本}]`，各頁的鍵欄序號照線上那一頁實際的欄位排法寫定。 - 完成條件與可驗證跡象改用區塊的說法，連結範例改成 `- {欄位名}：[{頁名}]({連結})` 的形態。 - 只改敘述與說明，不動任何腳本；轉檔與 upsert 的實作在別的存取庫。 Who - 本存取庫四支階段技能，以及讀這幾份說明檔決定共識判定與階段回報寫法的流程。 - 稽核與驗證流程改拿新的行為清單比對。