wiki-smith — 管理儲存庫的 .wiki/ 知識庫

知識庫 是做什麼的？

wiki 是儲存庫的記憶，專為代理編寫：它們在這裡找到規則，而不是重複詢問。日記記錄了發生過什麼；主題頁面記錄了目前的狀態。只存在於日記中的經驗教訓會遺失。wiki-smith 決定工作階段需要哪一種，按照 wiki 自身規則的方式撰寫，並進行檢查。

完整方法（檔案類型、筆記格式、歸納、連結、日期、提交）：references/method.md。設定鍵：references/config.md。貢獻者：ATTRIBUTION.md。變更：CHANGELOG.md。自身的記憶：.wiki/。

<skill> 是此技能的資料夾（例如 ~/.claude/skills/wiki-smith）。每個腳本都使用 -w <wiki 目錄>（預設為 ./.wiki）和 -c <設定檔>（預設為 <wiki>/wiki.config）。

步驟 0 — 找到 wiki 及其規則

1. wiki 位於儲存庫根目錄的 .wiki/。如果沒有，就說明情況，並提供從 templates/ 建立一個的選項（先從 wiki.config.example 開始）；未經要求絕不擅自建立。
2. 如果存在則讀取 .wiki/wiki.config（鍵值：日記資料夾、收件匣、索引、頁尾標籤、日期鍵、主要分支）。若無，則預設為通用英文設定：journal/、inbox.md、index.md、Map:、## History、created/updated。
3. wiki 自身的規則優先。 如果儲存庫有關於如何維護它的頁面（使用 rg -n -i 'maintain|manter' .wiki -l 檢查），或 AGENTS.md 中有關 wiki 的規則，則讀取該部分並遵循，若與此技能不同則以其為準。
4. 如果使用者要求「wiki update」且 wiki（通常是索引）要求先確認，則僅將步驟 1 和步驟 2 作為計劃提出：每個頁面一行說明變更，新筆記的標題，然後詢問「是否套用？」並在得到肯定答覆後才編輯。否則直接執行。

步驟 1 — 檢視發生了什麼，然後決定行動

讀取工作階段（以及 git diff、git log 以了解完成的工作）。選取所有適用的列，且只選取這些：

工作階段的內容	應採取的行動
決策、交付、方向變更、事件或研究	建立每日筆記：scripts/note.sh -b "說明改變標題" 並將段落內容透過管線輸入。然後將該天記錄加入收件匣。
超越當日的規則、經驗教訓或事實	同時修正主題頁面：寫下當前有效的規則，不包含歷史（歷史保留在筆記和頁面的 History 部分）。修正頁面先前的陳述；絕不堆疊「以前是這樣」。
具有多個面向的新主題（它會再次出現，且一個頁面會混雜不同類別）	建立內容地圖 moc-<主題>.md 加上頁面 <主題>-<面向>.md（速查表、安裝、整合、與目前工具的比較……）。參閱下方的「新主題」。
沒有值得記錄的內容（僅有中間步驟，或提交訊息已說明的內容）	用一行說明，不建立任何內容。填充日記只會讓它難以閱讀。

每日筆記永遠是新建立的；絕不重寫其他代理的筆記。

步驟 2 — 撰寫

每日筆記。 scripts/note.sh "<標題>" 在 UTC 時間下建立 <DIARY_DIR>/<今天日期>/<HHMM>-<slug>.md 並輸出路徑（slug 規則和衝突時的 -2 處理在腳本中）。僅在使用 -b 時才從標準輸入讀取：代理 shell 和 CI 會讓 stdin 保持開啟，因此沒有 -b 的話腳本會永遠等待。透過管線傳入內容主體：printf '%s\n' "<段落>" | scripts/note.sh -b "<標題>"；-b 會在標題和主體之間剛好放一個空行。不使用 -b 時，檔案僅有標題行；之後要新增段落時，以空行開頭：printf '\n%s\n' "<段落>" >> "$path"。主體是一個寫得好的段落：發生什麼事、為什麼重要、證據在哪裡（提交、PR、問題），並附上主題頁面的連結。連結相對於日記資料夾（../../page.md）。模板：templates/note.md。

當天的第一則筆記： scripts/day-index.sh 建立該天的索引；然後將該天加到收件匣中「最近幾天」的頂端。如果筆記改變了儲存庫的運作方式，則也在收件匣的 highlights 中加一行。收件匣永遠不保存筆記本身。

主題頁面（歸納）。 找到它（rg -n -i '<關鍵字>' .wiki）；如果不存在且該主題會再次出現，則建立它（模板：templates/page.md）；如果內容很小，則放入相鄰頁面的某個章節。撰寫當前有效的規則。如果變更改變了頁面的主張，則在 History 章節頂端加一行。筆記中連結到該主題頁面。

新主題。

1. 先撰寫頁面，每個面向一個，每個都從第一句話開始自成一體。典型的面向：速查表（最開始用的：地址、命令、快捷鍵）、安裝、整合、與目前使用工具的比較。
2. 建立 moc-<主題>.md（templates/moc.md）：開場段落、「頁面列表」（每頁一行，速查表優先）、「需知要點」（少數關鍵規則）。
3. 為每個頁面加上頁尾（Map: [moc-<主題>](moc-<主題>.md) · Related: ...），將地圖和每個頁面加入索引，並從至少一個其他地圖連結此內容地圖。
4. 日記中的一則筆記說明建立了什麼並連結該內容地圖。

步驟 3 — 關閉（務必按此順序）

1. scripts/dates.sh — 從 git 更新 created/updated 前置元數據。冪等。
2. scripts/day-index.sh — 重新產生每日索引。絕不手動編輯。
3. python3 -I scripts/lint.py — 修復它列印出的每個 file:line: type: message，直到返回 0（返回 2 表示有問題）。不要帶著紅燈（lint 錯誤）提交。
4. 僅提交你自己的檔案，按路徑指定，絕不使用 git add -A：scripts/sync.sh -m "wiki: <說明>" <路徑>...。當 checkout 在 <main> 分支上、為最新狀態且你的路徑之外無其他變更時，它會原地提交；否則它會從 origin/<main> 建立一個全新的 git worktree 來搬運你的路徑。兩種方式都會對將提交的內容進行 lint，並拒絕紅燈（返回 1，checkout 保持不變，搬運用的 worktree 被移除）。在搬運模式中，產生的每日索引不會被複製：它在 worktree 中重新產生，因此只列出包含在提交中的筆記。將儲存庫或你的主機要求的歸屬行加到提交訊息中。
   • 可能也被其他工作階段編輯過的共享檔案（索引、收件匣）： 不要將它們傳遞給搬運模式。scripts/sync.sh -W 會從 origin/<main> 列印一個新的 worktree；在該 worktree 中進行你的編輯（wiki 在相同的相對路徑下），執行 dates.sh、day-index.sh、lint.py，然後在該 worktree 內執行 scripts/sync.sh -m ... [-p] <路徑>。它會在那裡提交，並在有 -p 時進行 rebase、推送、快轉主要的 checkout（如果可能），然後移除 worktree。一個攜帶了其他工作階段行（例如，指向僅存在於 checkout 中的頁面的連結）的搬運會導致 lint 失敗，並在提交任何內容之前停止；這個失敗就是應該使用 -W 的信號。
5. 僅在使用者要求同步時才推送： 使用 -p 的相同調用（fetch、rebase、push HEAD:<main>、快轉 checkout、移除 worktree）。絕不強制推送，絕不觸碰其他人修改的檔案：如果一個檔案與你推送的內容不同且可能包含其他工作階段的編輯（索引、收件匣），則保留原樣。如果 checkout 無法快轉（本地 <main> 分歧，或本地編輯衝突），它會說明原因並仍然返回 0，因為推送成功了。僅在要求時才建立 PR。

在同一工作階段中提交你撰寫的內容，無需等待要求；發佈是用戶的決定。

查閱 wiki

rg -n -i '<關鍵字>' .wiki（或瀏覽索引），然後只讀取匹配的頁面或章節，絕不讀取整個 wiki。對於發生過什麼：收件匣（簡短），然後只讀取重要的日期；一個日期 = 它的索引及其列出的筆記。如果儲存庫有規格，它們說明了系統的承諾：rg -n -i '<關鍵字>' <規格目錄>。

陷阱

• 日記不是頁面。 只寫在筆記中的規則會遺失；在同一工作階段中將其歸納到主題頁面。
• 規則不帶歷史。 「建立卡片前，先搜尋現有卡片」，而不是「我們過去常常重複建立卡片」。故事保留在筆記中。
• 一則筆記一個檔案。 多個代理可能同一天寫入；它們絕不能編輯同一個檔案。每日索引是產生的；那裡的衝突透過重新執行 day-index.sh 解決。
• 跨工作階段的共享檔案。 每日索引、index.md 和收件匣在同一個 checkout 中保存了每個工作階段的未提交編輯。sync.sh 從不搬運每日索引（它在 worktree 中重新產生）並在提交前執行 lint，但它無法判斷手動編輯的 index.md 或收件匣中的哪些區塊是你的：搬運會帶走整個差異。當其他工作階段可能觸碰過這些檔案時，使用 sync.sh -W 並在 worktree 中編輯。一條恰好不破壞 lint 的外部行仍然會被搬運；這是搬運模式的已知限制。
• 永遠不要等待標準輸入。 note.sh 僅在使用 -b 時讀取主體；在代理 shell 中，單純的讀取會永遠阻塞。你添加的任何腳本也是如此。
• 不要記錄短暫事件： 一次失敗但重試就成功的命令、環境故障、一次性任務。在主體頁面上記錄有效的修正，而不是「X 壞了」（這會在原因消失後固化為拒絕）。
• 連結： 相對路徑，每個章節僅第一次提及；錨點是 GitHub 對標題的 slug（小寫、無標點、保留重音符號、空格變連字符）。重新命名標題會破壞其錨點；lint 會發出警告。將連結範例放在反引號內，這樣 lint 就不會讀取它。
• 重新命名或刪除頁面： rg -l '舊名稱' .wiki 並修復每個連結，包括錨點；只有在內容移動後才刪除。
• 頁面大小： 超過約 150 行，或當規則、程序、參考資料和歷史混合時，按類別拆分。
• 私密資料不得進入。 Wiki 頁面會被提交；將金鑰、令牌和個人資料排除在外，改為引用秘密的存放位置。
• Lint 的限制： 它無法捕獲頁面之間的矛盾或過時的陳述；這需要代理在時間允許時進行審查。
• day-index.sh 的限制： 包含手寫舊格式筆記的日期檔案是錯誤（file:line），不會被遷移；使用 note.sh 將每則筆記移動到自己的檔案，然後重新執行。

步驟 4 — 維護你自己的 wiki

如果這次執行學到了關於運行 wiki-smith 本身的經驗教訓（路由錯誤、腳本怪癖），則在 .wiki/lessons.md 中加一行：- YYYY-MM-DD — <規則 + 原因>。編輯原始 clone (biliboss/wiki-smith) 並重新安裝（npx skills add biliboss/wiki-smith -g --copy -a claude-code -y），而不是編輯已安裝的副本，因為後者會在重新安裝時被覆蓋。設計決策記錄在 .wiki/design.md 中。