From aaa14064f70dfc20f8e327ddbe4bc62b4e831740 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 12:54:37 +0800 Subject: [PATCH] =?UTF-8?q?refactor(spec-wiki-contents):=20=E7=9B=AE?= =?UTF-8?q?=E9=8C=84=E9=A0=81=E6=94=B9=E4=BE=9D=E7=B3=BB=E7=B5=B1=E5=88=86?= =?UTF-8?q?=E6=AE=B5=E5=85=AD=E6=AC=84=E8=A1=A8=E6=A0=BC=EF=BC=8C=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=E7=B3=BB=E7=B5=B1=E5=90=8D=E7=A8=B1=E6=B1=BA=E5=AE=9A?= =?UTF-8?q?=E8=88=87=20OTHER=20=E9=99=84=E5=B1=AC=E9=A0=81=E8=A6=8F?= =?UTF-8?q?=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit plan-wiki／todo-wiki 新增系統名稱決定流程（需求指定或推論候選／挑工作目錄與程式碼中文名）， spec-wiki-contents 目錄頁維持單一 CONTENTS 頁但依系統分成 `## 英文 中文` 段落，段落內用 計畫／代辦六欄表格取代原本四欄單一表格，並支援不屬於計畫代辦的附屬內容另建 OTHER_ 頁、 用 footnote 從對應列連過去；do-wiki 開工前挑代辦改為掃描全部系統段落。 Co-Authored-By: Claude Sonnet 5 --- skills/do-wiki/SKILL.md | 11 +++-- skills/plan-wiki/SKILL.md | 47 ++++++++++-------- skills/spec-wiki-contents/SKILL.md | 76 ++++++++++++++++++++---------- skills/todo-wiki/SKILL.md | 67 ++++++++++++++------------ 4 files changed, 122 insertions(+), 79 deletions(-) diff --git a/skills/do-wiki/SKILL.md b/skills/do-wiki/SKILL.md index de7b5df..908ef17 100644 --- a/skills/do-wiki/SKILL.md +++ b/skills/do-wiki/SKILL.md @@ -1,7 +1,7 @@ --- name: do-wiki description: 讀取 `todo-wiki` 產生、帶鎖定模型 frontmatter 的 Gitea wiki TODO 頁並逐項執行：開工前先讀目錄頁挑一份「已完成」為未勾選的代辦（沒有就直接結束）；檢查頁面 `## 0.` 的六條強制規則並比對當前模型，不符就停止；讀取需求彙整與既有 checklist（已勾選視為完成不重做）；逐項執行——完成一項就地把 `- [ ]` 改 `- [x]` 並補上完成時間，立即回寫該 wiki 頁並讀回確認成功才能繼續下一項，任一步失敗立刻停止；全部項目完成後回目錄頁把該代辦列「已完成」改為 `[x]`。當使用者說要執行 wiki TODO、跑 do-wiki、依 wiki 清單實作、接手某份 Gitea wiki 代辦、或提到 do-wiki skill 時觸發。不適用於：把需求分析並產生 TODO 清單同步到 wiki（用 `/jsc-shared:todo-wiki`）、逐步建立計畫並同步 wiki（用 `/jsc-shared:plan-wiki`）。 -argument-hint: "[--wiki-repo ] [--wiki-page <既有 TODO 頁 title>] [--yes]" +argument-hint: "[--wiki-repo ] [--wiki-index CONTENTS] [--wiki-page <既有 TODO 頁 title>] [--yes]" --- # do-wiki — 讀取並執行指定模型 Gitea wiki TODO 頁 @@ -25,11 +25,12 @@ argument-hint: "[--wiki-repo ] [--wiki-page <既有 TODO 頁 title>] ## 參數 -`[--wiki-repo ] [--wiki-page <既有 TODO 頁 title>] [--yes]` +`[--wiki-repo ] [--wiki-index CONTENTS] [--wiki-page <既有 TODO 頁 title>] [--yes]` | 參數 | 說明 | | --- | --- | | `--wiki-repo` | 指定要讀取的 Gitea wiki repo，例如 `knowledges/Plan`。未帶時依 `spec-ask-user` 詢問，不臆測。 | +| `--wiki-index` | 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 | | `--wiki-page` | 直接指定既有 TODO 頁 title；有帶時跳過階段 0 的挑選詢問，直接查表取得對應 `path` 進入階段 1。 | | `--yes` | 略過一般性確認；不得略過模型不符、目標 wiki 不明、或 wiki 回寫／讀回失敗後的停止。 | @@ -37,9 +38,9 @@ argument-hint: "[--wiki-repo ] [--wiki-page <既有 TODO 頁 title>] 1. 依 `spec-gitea` 決定 host 與 token；確認 `--wiki-repo`，缺少就詢問使用者，不臆測。 2. `--wiki-page` 已帶（或使用者已於對話明確指定頁面）時，依 `spec-ask-user`「已知答案時跳過詢問」直接查表取得該 title 對應的 `path`，跳過本階段其餘步驟進入階段 1；只有查表找不到該 title 時，才回頭走本階段清單並提示原指定值無效，不得臆測頁面。 -3. 依 `spec-gitea` 分頁查表讀取目錄頁（預設 title `CONTENTS`），依 `spec-wiki-contents`〔列型別判定〕取出所有「已完成」為 `[ ]` 的 TODO 列。 -4. **沒有未完成代辦就直接結束**：目錄頁不存在、目錄頁沒有任何 TODO 列、或所有 TODO 列「已完成」皆為 `[x]` 這三種情境，一律輸出 `[yyyy/MM/dd HH:mm:ss][代辦盤點][INF]: 目錄頁沒有未完成的代辦，本次不進行任何修改。` 後結束，不讀取任何 TODO 頁、不修改任何檔案或 wiki。 -5. 有未完成代辦時，依 `spec-ask-user` 以**單選**呈現（候選 ≤4 用 `AskUserQuestion` 並含「其他」，>4 改文字編號列出）；選定列連結的 `path` 直接作為階段 1 的讀取目標，不得再自行推導轉義。 +3. 依 `spec-gitea` 分頁查表讀取目錄頁（title 預設 `CONTENTS`，或 `--wiki-index` 指定值），依 `spec-wiki-contents`〔目錄頁格式〕掃描**所有系統的 `## ` 段落**，取出每個段落中所有「`代辦`欄非空、`是否已完成`為 `[ ]`」的列，記下其所屬系統（該段落標題）供候選標示用。 +4. **沒有未完成代辦就直接結束**：目錄頁不存在、目錄頁沒有任何系統段落、或所有段落的候選列皆為空，一律輸出 `[yyyy/MM/dd HH:mm:ss][代辦盤點][INF]: 目錄頁沒有未完成的代辦，本次不進行任何修改。` 後結束，不讀取任何 TODO 頁、不修改任何檔案或 wiki。 +5. 有未完成代辦時，依 `spec-ask-user` 以**單選**呈現，候選標示為「{系統名稱}：{代辦內容摘要}」（候選 ≤4 用 `AskUserQuestion` 並含「其他」，>4 改文字編號列出）；選定列`代辦`欄連結的 `path` 直接作為階段 1 的讀取目標，不得再自行推導轉義。 ## 階段 1：讀取目標 TODO 頁 diff --git a/skills/plan-wiki/SKILL.md b/skills/plan-wiki/SKILL.md index 3b2f2bc..e9238a2 100644 --- a/skills/plan-wiki/SKILL.md +++ b/skills/plan-wiki/SKILL.md @@ -1,7 +1,7 @@ --- name: plan-wiki description: 逐步詢問使用者計畫內容，並把每一輪已確認的計畫草稿直接同步到指定 Gitea wiki 的目錄頁與計畫頁，全程不建立本機計畫檔、草稿檔、暫存 JSON body 或 wiki clone。使用者要建立計畫、把計畫加入 wiki 目錄、指定 Gitea wiki repo／目錄頁／計畫頁、要求邊問邊同步 wiki、要求計畫檔案不落地、或提到 plan-wiki、計畫 wiki、wiki 目錄頁時觸發。適用於：需求尚未完整、需要逐題釐清並保存到 wiki 的計畫文件。不適用於：產生本機 plan.md／todo.md、拆 Gitea issue（用 /jsc-doc:issues-analyze）、或非 Gitea wiki。 -argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN__] [--host ] [--yes]" +argument-hint: "[--wiki-repo ] [--index <英文系統名稱>_<中文系統名稱>] [--project <英文系統名稱>_<中文系統名稱>] [--page PLAN__] [--host ] [--yes]" --- # plan-wiki — 逐步建立計畫並同步到 Gitea wiki @@ -25,10 +25,19 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 本 skill 特有補充： - 本 skill 會寫入外部 Gitea wiki；目標 wiki repo 不明時必須詢問，不得臆測。 -- 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--index` 時才覆蓋預設值。 -- 計畫頁 title 預設固定為 `PLAN_{yyyyMMdd}_{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由已確認的計畫內容、計畫名稱或需求摘要產生穩定短雜湊並轉成全大寫。 -- 加入目錄頁時，先從計畫內容尋找系統名稱；若無明確系統名稱，依計畫目標產生一個精簡系統名稱。目錄標題使用 `{系統名稱}-計畫`，並連結到計畫頁。 -- 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本計畫既有列或在既有表格附加新列。 +- 目錄頁是單一共用頁面，title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--index` 時才覆蓋預設值。 +- 計畫頁 title 預設固定為 `PLAN_{yyyyMMdd}_{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由已確認的計畫內容、系統名稱或需求摘要產生穩定短雜湊並轉成全大寫。 +- 加入目錄頁時，依下方〔系統名稱決定〕得到英文＋中文系統名稱；目錄頁裡該系統對應的 `## {英文系統名稱} {中文系統名稱}` 段落使用這組名稱，計畫頁連結填進該段落表格的`計畫`欄（依 `spec-wiki-contents`〔新增列前先找可合併的既有列〕決定填入既有列、新增列，或新增整個段落）。 +- 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容與其他系統的段落，只 upsert 本系統段落內對應的既有列、在該段落表格附加新列，或該系統尚無段落時新增一個段落。 + +### 系統名稱決定 + +- **需求中已明確指定系統名稱**（使用者於對話中講出、或 `--project` 已帶）：直接採用；若只給了英文或只給了中文其中一種，另一種依需求內容推論後，依 `/jsc-shared:spec-ask-user` 請使用者確認（單選：採用推論值／自行輸入）。 +- **未指定時**：依已收集到的需求內容，推論 **5 組**候選，每組為「大駝峰英文系統名稱＋中文名稱」配對（例如 `KokoroneCore 心核`）；依 `/jsc-shared:spec-ask-user`（候選數 5 > 4，改文字編號列出）請使用者從 5 組中選一組，選項另外固定包含「重新產生 5 組」與「自行輸入」： + - 使用者選「重新產生 5 組」：重新推論另外 5 組**不同於前次**的候選，再次詢問；可反覆重新產生，不設次數上限。 + - 使用者選「自行輸入」：請使用者直接提供英文＋中文系統名稱，兩者皆須提供。 + - 使用者選其中一組候選：採用該組英文＋中文名稱。 +- 決定出的系統名稱在本次 plan-wiki 執行全程固定不變，供目錄頁對應段落標題、計畫頁 H1 等引用系統名稱處使用。 - **不落地絕對規則**：不得建立本機 `plan.md`、`todo.md`、`.md` 草稿、暫存 JSON body、wiki clone、或任何用來傳遞中間成果的檔案；中間成果只存在於對話內容與 Gitea wiki API request body。不得使用 `curl --data @file`。 - 使用者已用參數指定 `--wiki-repo`、`--index`、`--project`、`--page` 時跳過對應詢問。 - 每一輪使用者回答後都要同步 wiki；一輪一同步、一輪一確認，不可累積多輪回答後一次送出。同步失敗、讀回失敗或比對不一致時，停止下一輪詢問，先回報錯誤與待使用者處理的點。 @@ -37,24 +46,24 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 ## 參數 -`[--wiki-repo ] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN__] [--host ] [--yes]` +`[--wiki-repo ] [--index <英文系統名稱>_<中文系統名稱>] [--project <英文系統名稱>_<中文系統名稱>] [--page PLAN__] [--host ] [--yes]` | 參數 | 說明 | | --- | --- | | `--wiki-repo` | Gitea wiki 所屬 repo，例如 `knowledges/Plan`。未帶且無法從目前 repo 推得時詢問使用者。 | | `--index` | 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 | -| `--project` | 計畫名稱；未帶時從計畫內容尋找或產生系統名稱，用於目錄列標題與摘要。 | +| `--project` | 系統名稱（英文＋中文）；未帶時依〔系統名稱決定〕流程推論候選並請使用者選定，用於目錄頁對應段落標題與摘要。 | | `--page` | 計畫頁 title；未帶時固定使用 `PLAN_{yyyyMMdd}_{HASH}`，不詢問。 | | `--host` | Gitea 主機，依 `spec-gitea` host 決定順序處理。 | -| `--yes` | 略過一般性確認；不得略過目標 wiki 不明、寫入衝突、同步失敗後的停止，或使用者尚未確認的計畫完成判斷。 | +| `--yes` | 略過一般性確認；不得略過目標 wiki 不明、系統名稱選定、寫入衝突、同步失敗後的停止，或使用者尚未確認的計畫完成判斷。 | ## 階段 A：前置設定 1. 依 `spec-gitea` 決定 host 與 token，只輸出 token「已設定／未設定」。 2. 確認 `--wiki-repo` 是否為 `owner/repo` 格式；不符合時詢問使用者修正。 -3. 確認目錄頁 title：未帶 `--index` 時固定使用 `CONTENTS`。 -4. 確認計畫頁 title：未帶 `--page` 時固定使用 `PLAN_{yyyyMMdd}_{HASH}`。雜湊輸入優先使用已確認的計畫內容；內容不足時使用計畫名稱、來源摘要與當輪時間組合，輸出全大寫短雜湊。 -5. 確認系統名稱：先從 `--project`、計畫內容、需求來源或使用者回答尋找明確系統名稱；找不到時產生精簡系統名稱，不為此單獨詢問。 +3. 確認系統名稱：`--project` 已帶時直接採用；未帶時依〔系統名稱決定〕流程推論 5 組候選請使用者選定（或使用者要求重新產生／自行輸入）。 +4. 確認目錄頁 title：未帶 `--index` 時固定使用 `CONTENTS`。 +5. 確認計畫頁 title：未帶 `--page` 時固定使用 `PLAN_{yyyyMMdd}_{HASH}`。雜湊輸入優先使用已確認的計畫內容；內容不足時使用系統名稱、來源摘要與當輪時間組合，輸出全大寫短雜湊。 6. 用 `GET /repos//` 驗證 token 對 repo 有權限；失敗時遮蔽機密後回報並停止。 ## 階段 B：讀取 wiki 現況 @@ -62,20 +71,20 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 1. 依 `spec-gitea` 分頁讀取 `GET /repos///wiki/pages`。 2. 以 title 查表取得目錄頁與計畫頁的 `sub_url`，不得自行猜測轉義規則。 3. 讀取頁面：`GET /repos///wiki/page/`，將 `content_base64` 解成 UTF-8 Markdown。 -4. 目錄頁不存在時在記憶中組出符合「目錄頁格式」的新頁內容；目錄頁存在時不得用預設格式覆蓋整頁，只能保留原內容後修改或附加本計畫目錄列。計畫頁不存在時在記憶中組出目前計畫草稿。不得先寫成本機檔案。 +4. 目錄頁不存在時在記憶中組出符合「目錄頁格式」的新頁內容；目錄頁存在時不得用預設格式覆蓋整頁，只能保留原內容後修改或附加本計畫對應的列。計畫頁不存在時在記憶中組出目前計畫草稿。不得先寫成本機檔案。 ## 目錄頁格式 -目錄頁的四欄表格格式、「已產生」欄初始值、列型別判定、以及連結來源（查表取得的 `sub_url`／`path`，不使用 percent-encode 的 title）一律依 `/jsc-shared:spec-wiki-contents`，本 skill 不重複定義。 +目錄頁是單一共用頁面依系統分段、段落標題與六欄表格格式、列合併規則、以及連結來源（查表取得的 `sub_url`／`path`，不使用 percent-encode 的 title）一律依 `/jsc-shared:spec-wiki-contents`，本 skill 不重複定義。 -目錄頁不存在時，依 `spec-wiki-contents`〔目錄頁格式〕建立新頁，並在計畫列「已產生」欄填 `[ ]`（表示尚未產生對應 TODO）、「已完成」欄留空；目錄頁已存在時禁止整頁覆蓋，只能 upsert 既有的 `<系統名稱>-計畫` 列或在既有表格附加新列，保留其餘標題、說明與內容。 +目錄頁不存在時，依 `spec-wiki-contents`〔目錄頁格式〕建立新頁（title `CONTENTS`），並建立本系統對應的 `## {英文系統名稱} {中文系統名稱}` 段落，`計畫`欄填本計畫頁連結、`是否已產生代辦`欄填 `[ ]`、`代辦`與`是否已完成`欄留空；目錄頁已存在時禁止整頁覆蓋，只能依 `spec-wiki-contents`〔新增列前先找可合併的既有列〕upsert 本系統段落內對應的列、在該段落附加新列，或該系統尚無段落時新增段落，保留其他系統的段落與其餘內容。 ## 計畫頁格式 -計畫頁使用 Markdown，至少包含： +計畫頁使用 Markdown，H1 固定為 `{英文系統名稱} {中文系統名稱} 計畫`（使用〔系統名稱決定〕得到的系統名稱，與 wiki 頁 title `PLAN_{yyyyMMdd}_{HASH}` 是兩件事，不得把雜湊 title 直接當 H1）；至少包含： ```markdown -# +# <英文系統名稱> <中文系統名稱> 計畫 ## 目標 @@ -118,7 +127,7 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 每輪同步順序固定： 1. 更新計畫頁。 -2. 更新目錄頁：不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<系統名稱>-計畫` 列，或在既有表格／頁末附加新列，確保有本計畫頁連結與摘要。 +2. 更新目錄頁：不存在才建立；存在時禁止整頁覆蓋，依 `spec-wiki-contents`〔新增列前先找可合併的既有列〕在本系統對應的 `## ` 段落修改既有列的`計畫`欄、附加新列，或該系統尚無段落時新增段落，確保有本計畫頁連結與摘要。 3. 再次讀回兩個頁面確認內容已更新。讀回時若回應含 `content_base64`，必須 base64 解碼後比對正文 Markdown 是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。 4. 每輪只允許一輪同步結果對應下一輪提問；若 wiki 寫入失敗、讀回失敗或內容比對不一致，必須停止下一輪詢問，先回報錯誤與待處理點。 @@ -152,6 +161,6 @@ API 寫入方式： | 助理 | 呼叫 | | --- | --- | -| Claude Code / Antigravity | `/jsc-shared:plan-wiki --wiki-repo knowledges/Plan --project Kokorone` | -| Codex | `$plan-wiki --wiki-repo knowledges/Plan --project Kokorone` | +| Claude Code / Antigravity | `/jsc-shared:plan-wiki --wiki-repo knowledges/Plan --project Kokorone_心音` | +| Codex | `$plan-wiki --wiki-repo knowledges/Plan --project Kokorone_心音` | | OpenCode | 描述需求（如「逐步問我計畫內容，並同步到 Gitea wiki 目錄與頁面」）自動觸發 | diff --git a/skills/spec-wiki-contents/SKILL.md b/skills/spec-wiki-contents/SKILL.md index 3f44f13..c0340fe 100644 --- a/skills/spec-wiki-contents/SKILL.md +++ b/skills/spec-wiki-contents/SKILL.md @@ -1,39 +1,65 @@ --- name: spec-wiki-contents -description: JSC plugins 共用「wiki 目錄頁四欄格式與列型別判定規範」：目錄頁固定 `| 頁面 | 已產生 | 已完成 | 內容 |` 四欄表格與 `| --- | :-: | :-: | --- |` 對齊列、依「已產生」「已完成」欄位判定計畫列／TODO 列／略過並輸出 WRN、目錄列連結一律用查表取得的 sub_url／path 而非 percent-encode 的 title、目錄頁不存在才新建、存在時禁止整頁覆蓋只能 upsert 既有列。當其他 skill 內文引用 spec-wiki-contents 或 /jsc-shared:spec-wiki-contents、或需要讀取／更新 plan-wiki／todo-wiki／do-wiki 共用的四欄目錄頁時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +description: JSC plugins 共用「wiki 目錄頁格式與列合併規範」：目錄頁維持單一共用頁面（title 固定為 `CONTENTS`），依系統分段，每個系統一個 `## {英文系統名稱} {中文系統名稱}` 段落，段落內先系統描述、再接 `| 計畫 | 是否已產生代辦 | 內容 | 代辦 | 是否已完成 | 內容 |` 六欄表格，一列代表一組「計畫＋其對應代辦」的配對關係、缺其中一邊時對應欄位留空、新增計畫或代辦時先找可合併的既有列才新增列、目錄頁不存在才新建、存在時禁止整頁覆蓋只能 upsert 既有段落或列、不屬於計畫或代辦的附屬參考內容改建 `OTHER_{yyyyMMdd}_{HASH}` 頁，從對應列原連結後加 Markdown footnote 標記（`[^label]` ＋段落末 `[^label]: 連結`）連過去，不覆蓋原本的計畫／代辦連結。當其他 skill 內文引用 spec-wiki-contents 或 /jsc-shared:spec-wiki-contents、或需要讀取／更新 plan-wiki／todo-wiki／do-wiki 共用的目錄頁時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 --- -# spec-wiki-contents — 共用 wiki 目錄頁四欄格式與列型別判定規範 +# spec-wiki-contents — 共用 wiki 目錄頁格式與列合併規範 -`plan-wiki`、`todo-wiki`、`do-wiki` 三個 skill 共用同一份 Gitea wiki 目錄頁（預設 title `CONTENTS`），一律遵守以下規範，不得各自複製一份格式或判定邏輯。 +`plan-wiki`、`todo-wiki`、`do-wiki` 三個 skill 共用同一份 Gitea wiki 目錄頁（預設 title `CONTENTS`），依系統分段管理，不得各自複製一份格式或判定邏輯。 -## 目錄頁格式（固定四欄） +## 目錄頁的定位：單一共用頁面，依系統分段 + +目錄頁是**單一共用頁面**（title 固定為 `CONTENTS`，只有使用者明確提供 `--index`／`--wiki-index` 時才覆蓋），**不是**每個系統各自一頁。頁面內依系統分段：每個系統一個 `## {英文系統名稱} {中文系統名稱}` 段落（系統名稱決定方式見 `/jsc-shared:plan-wiki`〔系統名稱決定〕與 `/jsc-shared:todo-wiki`〔系統名稱決定〕，本規範不重複定義），該系統的所有計畫、代辦都 upsert 進自己的段落；不同系統不共用同一個段落，也不混進同一張表格。 + +## 目錄頁格式（固定：H1 CONTENTS＋逐系統 H2 段落） ```markdown # CONTENTS -| 頁面 | 已產生 | 已完成 | 內容 | -| --- | :-: | :-: | --- | -| [<系統名稱>-計畫](<查表取得的 path>) | [ ] | | plan wiki：<系統名稱> 計畫 | -| [<系統名稱>-代辦](<查表取得的 path>) | | [ ] | todo wiki：<系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 | +## <英文系統名稱> <中文系統名稱> + +<系統描述：一段文字，說明這個系統做什麼、範圍與目的> + +| 計畫 | 是否已產生代辦 | 內容 | 代辦 | 是否已完成 | 內容 | +| --- | :-: | --- | --- | :-: | --- | +| [<計畫頁連結文字>](<查表取得的 path>) | [ ] | <計畫摘要> | [<代辦頁連結文字>](<查表取得的 path>) | [ ] | <代辦摘要> | + +## <另一個英文系統名稱> <另一個中文系統名稱> + +...（格式同上，各系統各自一段） ``` -- 欄位固定四個：`頁面`／`已產生`／`已完成`／`內容`，對齊列固定 `| --- | :-: | :-: | --- |`，不得增減欄位或改變順序。 -- **計畫列**：由 `plan-wiki` 建立，「已產生」欄填 `[ ]`（表示尚未產生對應 TODO），「已完成」欄留空。 -- **TODO 列**：由 `todo-wiki` 建立，「已完成」欄填 `[ ]`，「已產生」欄留空。 -- 目錄頁不存在時才依上述格式新建；已存在時**禁止整頁覆蓋**，只能 upsert 既有列或在既有表格附加新列，保留其餘標題、說明與內容。 +- 頁面 H1 固定為 `CONTENTS`；每個系統各自一個 H2 段落，標題固定為 `<英文系統名稱> <中文系統名稱>`，與該系統其他頁面（計畫頁、代辦頁）H1 用的是同一組系統名稱。 +- 段落 H2 之後先放一段「系統描述」，說明系統目的與範圍；來源為需求彙整或計畫目標摘要，不得留空。 +- 表格欄位固定六個：`計畫`／`是否已產生代辦`／`內容`／`代辦`／`是否已完成`／`內容`，對齊列固定 `| --- | :-: | --- | --- | :-: | --- |`，不得增減欄位或改變順序。 +- **一列代表一組「計畫＋其對應代辦」的配對關係**，不是「一列一種頁面型別」。同一系統可以有多列，例如：同系統先後有多個計畫、同一計畫衍生多個代辦、或代辦先於計畫存在。 +- 只有計畫、還沒代辦：`代辦`欄與`是否已完成`欄留空（不得填 `[ ]`，因為根本不適用），`是否已產生代辦`欄填 `[ ]`。 +- 只有代辦、沒有對應計畫（例如需求直接進 `todo-wiki` 沒有經過 `plan-wiki`）：`計畫`欄與`是否已產生代辦`欄留空，`代辦`欄填連結，`是否已完成`欄填 `[ ]`／`[x]`。 +- 兩邊都有：`是否已產生代辦`填 `[x]`，`是否已完成`依代辦頁完成狀態填 `[ ]`／`[x]`。 +- 目錄頁不存在時才依上述格式新建（先建一個系統的段落）；已存在時**禁止整頁覆蓋**，只能 upsert 既有段落內的列、在既有段落表格附加新列，或（該系統尚無段落時）在頁尾附加一個新的 `## ` 段落，保留其餘系統的段落與內容。 -## 列型別判定 +## 新增列前先找可合併的既有列 -讀取既有目錄頁表格時，依每列「已產生」「已完成」兩欄判定列型別： +新建立計畫或代辦時，**先定位到該系統的 `## ` 段落**（找不到就視為該系統尚無段落，需新增段落），**在段落內的表格找有沒有可以合併進去的列**，找不到才新增列： -| 判定 | 條件 | -| --- | --- | -| 計畫列 | 「已產生」欄含 `[ ]` 或 `[x]`（不論勾選與否），「已完成」欄留空 | -| TODO 列 | 「已完成」欄含 `[ ]` 或 `[x]`，「已產生」欄留空 | -| 略過 | 兩欄皆空、或兩欄格式皆無法解析 | +| 情境 | 判斷 | 動作 | +| --- | --- | --- | +| 目錄頁裡沒有該系統的 `## ` 段落 | — | 在頁尾附加新段落（系統描述＋空表格），再依下列規則新增列 | +| 新建代辦，且使用者於開工前選定要關聯的計畫列 | 該計畫列的`代辦`欄目前是空的 | 直接把代辦欄、是否已完成欄、內容欄填進**同一列**，`是否已產生代辦`改為 `[x]`；不新增列 | +| 新建代辦，且使用者於開工前選定的計畫列`代辦`欄已有內容 | 該列已被佔用 | 不得覆蓋既有代辦，改在同一段落表格附加**新列**，`計畫`欄留空或重複連結同一計畫（依 `todo-wiki` 詢問使用者結果決定），並依 `spec-ask-user` 詢問使用者是否要重複關聯同一計畫 | +| 新建代辦，未關聯任何計畫 | — | 在該系統段落表格附加新列，`計畫`欄與`是否已產生代辦`欄留空 | +| 新建計畫 | 該系統段落表格已有某列`計畫`欄為空、且內容明顯屬於同一需求脈絡（需使用者確認，不得臆測） | 依使用者確認結果，填入該列`計畫`欄；未獲確認一律新增列 | +| 新建計畫，無可合併列 | — | 在該系統段落表格附加新列，`代辦`欄與`是否已完成`欄留空 | -略過的列一律輸出 `[yyyy/MM/dd HH:mm:ss][目錄盤點][WRN]: <該列「頁面」欄內容> 兩個 check 欄皆無法判定列型別，已略過`，並繼續處理其餘列，不得中止整個流程、也不得自行臆測型別。 +## 附屬參考頁（`OTHER_` 頁）與註腳連結 + +計畫或代辦有需要附掛的補充內容（例如視覺資產、命名規範、外部素材說明），但該內容本身**不是計畫也不是代辦**、塞不進六欄表格時： + +- 另建一頁，title 固定為 `OTHER_{yyyyMMdd}_{HASH}`（`yyyyMMdd`／`HASH` 規則與 `PLAN_`／`TODO_` 相同）；`OTHER_` 頁內容不受計畫頁／代辦頁格式（frontmatter、固定 H1）約束，維持原有內容型態即可。 +- 目錄頁對應列的`計畫`或`代辦`欄**保留原本指向計畫頁／代辦頁的連結不變**，只在連結後面加一個 Markdown footnote 標記：`[原連結文字](原 path)[^