DenshoApp/densho-skill

Densho

Densho 是一個自託管的知識庫。一個工作區包含多個空間，每個空間內有頁面的樹狀結構，每個頁面都是一份即時協作文件，其他人可能正在與你同時編輯它。

你可以透過使用者連接的 MCP 伺服器存取它。你的權限與使用者完全相同：若某工具回傳空值，通常表示該空間不屬於使用者可讀取的範圍，而非工作區為空。

關於寫入的唯一規則

update_page 會完全取代整個主體。 它不是附加操作。未先讀取就寫入會摧毀原有內容。

較新的實例會強制執行此規則：替換內容需要 expectedVersion，這是 get_page 回傳的權杖。若頁面在你讀取後已被變更，或 ID 錯誤，寫入請求會被拒絕而非靜默套用。請依以下步驟：讀取、合併、寫入：

1. get_page 會給你 { version, title, content }
2. 從該內容建構完整的新主體
3. 使用 content 和 expectedVersion: <version> 呼叫 update_page

若收到頁面已變更的回應，請重新讀取並重新執行合併。切勿使用舊版本重試，也絕不能繞過保護機制而捨棄你未讀取的內容。

較舊的實例沒有此權杖：get_page 回傳一個 Markdown 文件，其中標題已以 # H1 形式前置，而主體本身不包含它。若直接將該內容傳回 update_page，會將標題寫入主體，導致頁面中顯示兩次。在寫入前請移除該第一個標題，並同樣謹慎處理其餘部分：舊實例沒有任何機制阻止錯誤寫入，因此請在寫入前立即讀取頁面，並保留所有你並非刻意要變更的內容。

在修改任何內容之前

• 建立前先搜尋。 先使用 search_pages。Wiki 會因重複頁面而死亡，而你即將建立的頁面通常已經以另一個標題存在。
• 在撰寫任何頁面主體之前，每個工作階段請呼叫一次 get_markdown_reference。它會回傳此實例所呈現的確切語法，由於直接取自實例本身，因此永遠不會過期。不要憑記憶猜測語法，也不要假設是 GitHub Flavored Markdown。若未提供此工具，表示該實例較舊：請遵守下方「無法運作的功能」中的限制，並引導使用者參閱其工作區中的**指南 > 編輯器 >「Markdown 進出」**以取得完整語法。
• 若非被要求修改，對頁面優先使用評論而非編輯。 add_comment 會將你的意見放置在文字旁並通知作者，這是針對他人作品時禮貌的做法。
• 在建立頁面前，使用 list_pages 找出頁面應歸屬的位置。Wiki 是樹狀結構，一個被放置在空間根目錄的頁面是沒有人找得到的。請傳入 parentPageId。
• 使用周圍頁面的語言寫作，而非你的預設語言。工作區通常全以一種語言撰寫，若出現另一種語言的頁面會顯得像外來者。

工具

讀取。 list_spaces（使用者所屬的空間）、list_pages（空間的頁面樹狀結構，以扁平列表搭配父層 ID 呈現）、search_pages（全文搜尋，可選擇限定範圍於某空間，最多 20 個結果且無分頁，因此請精煉查詢而非將列表當作完整真相）、get_page（以 Markdown 形式回傳標題和主體，以及版本權杖）、list_comments（討論串及其解決狀態）。

寫入。 create_page（在空間中建立，可選擇置於某父頁下，可選擇帶有主體）、update_page（更新標題及/或完整主體）、add_comment（新增討論串，或使用 parentCommentId 回覆）、resolve_comment。

頁面也以 densho://page/{id} 資源形式提供，因此客戶端可直接附加一個頁面。

並非每個實例都提供所有工具。寫入工具僅在使用者授權時授予了寫入權限才存在，而舊實例可能缺少評論列表、解決工具和 Markdown 參考。請根據客戶端實際顯示的工具來作業，並說明你無法執行的編輯操作。

撰寫人們會讀的頁面

將其結構化為文件形式，而非聊天回答。使用能說明章節內容的標題、簡短的段落，並在內容為列表時使用列表。

• 使用 :::info、:::warning 及其他提示框來標示真正會打斷讀者的內容。連續三個提示框等於沒有提示。
• 使用 :::toggle 來收納大多數讀者會跳過的細節，而非隱藏答案。
• 使用 :::subpages 來顯示子頁面的索引，而非手寫的連結列表——後者一旦有人新增頁面就會過時。
• 相比於用段落列舉成對項目，更推薦使用表格。

編輯器支援的所有功能都能透過 Markdown 進行雙向轉換，因此你撰寫的內容就是使用者看到的內容，也是他們日後匯出的內容。雙向轉換過程中會進行正規化：$$maths$$ 會以三行形式回傳，區塊之間會增加空白行。讀回時形狀與你傳送時略有不同是正常的，並非表示有任何錯誤。

無法運作的功能

• 原始 HTML 標籤會被跳脫並顯示為文字。使用 fenced 的 ```htmlrender 區塊才是渲染 HTML 的正確方式，且必須是自包含的：無網路、無外部資源。
• GitHub 提示框（> [!NOTE]）不屬於此語法：方括號會被跳脫，讀者會看到一般引用中的 \[!NOTE\]。請使用提示框。
• 腳註在這裡比無用更糟。text[^1] 搭配其 [^1]: note 定義會變成 [^1](note)，一個指向空白的連結。請將附註寫在行內或提示框中。
• ```math 圍欄無法渲染。 區塊數學公式應使用 $$ ... $$。
• 你無法上傳任何檔案。 沒有檔案或圖片工具，因此絕不能寫入指向本機路徑或你聲稱已新增的檔案的 Markdown 圖片。頁面中已存在的圖片會持續正常運作：當你重寫主體時，請保持其連結不變。
• 絕不要發明晶片 ID。 提及、頁面連結和同步區塊會編碼真實 ID（[@Name](mention:<userId>)、[label](page:<pageId>)、![[synced-blocks/...]]）。偽造的 ID 會渲染為無效晶片。請使用你從工具取得的真實 ID，否則請撰寫一般連結。

對團隊有影響的事項

• 透過你編輯的頁面會立即顯示在任何已開啟該頁面的編輯者游標下方。在他人正在編輯時重寫長頁面，即使技術上安全，仍然是干擾性的行為。
• 編輯標記為已驗證的頁面會將其狀態改回「待驗證」，這會為管理員增加工作量。當你這麼做時，請明確告知。
• 評論會通知他人。不要為了你可以順便修正的內容就開啟討論串，也不要解決你尚未處理的討論串。

回報結果

提供使用者頁面標題及其所在位置，而非原始 ID。清楚說明你變更了什麼：完整主體替換值得特別說明，如果你將文字合併到既有頁面中，請說明你保留了哪些內容。