data-structure-protocol

data-structure-protocol 技能總覽

這個技能是做什麼的

data-structure-protocol 技能能協助 agent 建立並瀏覽 DSP，也就是一種用於 codebase 的圖譜式記憶層。它會記錄模組、函式、imports、exports，以及連結存在的原因，讓模型能回答「有哪些東西、它依賴什麼、為什麼會有這條關係」，而不是只靠檔名猜測。

適合誰安裝

如果你的專案已經有 .dsp/ 目錄、你需要在 repo 中啟動 DSP，或你希望 agent 先檢查結構脈絡再進行更安全的程式修改，就很適合安裝 data-structure-protocol 技能。這個技能特別適合維護者、agentic coding workflow，以及依賴邊界比文字說明文件更重要的 repo。

為什麼它不一樣

這不是一般的 prompt 包裝器。data-structure-protocol 技能是圍繞著具體的儲存模型、CLI，以及把真實檔案轉成 entity graph 的 bootstrap workflow 設計的。這讓它比單純的「幫我理解這個 repo」提示更有決策價值，因為它會告訴 agent 該讀什麼、該驗證什麼，以及什麼時候不該註冊已失效的 imports。

如何使用 data-structure-protocol 技能

安裝並確認 repo 結構

使用以下指令安裝 data-structure-protocol 技能：
npx skills add k-kolomeitsev/data-structure-protocol --skill data-structure-protocol

安裝後，請確認 repo 內有 SKILL.md、references/ 和 scripts/dsp-cli.py。這個 repository 的實用工作流程是圍繞 bootstrap、operations 與 storage-format 建立的，所以這些檔案的重要性遠高於一般專案中快速掃過 README。

給技能一個具體任務

這個技能在你明確說出 repo 狀態與要完成的工作時表現最好。好的輸入應包含專案根目錄、.dsp/ 是否已存在，以及你打算做的變更類型。例如：「這個 repo 使用 DSP，我需要新增一個模組；請先找出受影響的 entities，再告訴我哪些檔案和 UID 需要更新。」

對於 data-structure-protocol usage，請避免像「幫我處理 DSP」這種模糊請求。應該明確指定你需要的是 bootstrap、導覽、更新還是清理。這個技能是針對結構性決策設計的，不是泛用架構建議。

先讀對的檔案

先讀 SKILL.md，了解 agent prompt 和核心規則。接著閱讀 references/bootstrap.md 以掌握 DFS bootstrap 流程，讀 references/operations.md 了解 create/update/read 指令，再看 references/storage-format.md 理解 UID 與資料夾結構。如果你要直接使用 CLI，請檢查 scripts/dsp-cli.py，看實際的指令行為與邊界情況處理。

能產生更好結果的工作流程

可靠的 data-structure-protocol guide 流程是：先確認 root entrypoints，接著讀受影響的 entities，驗證檔案內容中的 imports 是否真的被使用，然後再建立或更新 DSP records。當你要求模型執行任務時，請提供足夠的來源脈絡，以辨識 entrypoint、export surface，以及哪些模組之間的關係正在改變。這正是該協定用來維持圖譜準確性的資訊。

data-structure-protocol 技能 FAQ

這只適用於已經在用 DSP 的專案嗎？

不是。這個技能同時適用於已存在 .dsp/ 的專案，以及需要 bootstrap 的工作。如果 repo 還沒有圖譜，data-structure-protocol 仍然可以引導你把 root files 和 dependencies 正確映射進 DSP。

這比一般 prompt 更好嗎？

通常是，尤其在結構很重要的時候。一般 prompt 也許能摘要程式碼，但 data-structure-protocol 的設計目標是保留長期的結構記憶：entities、imports、exports，以及它們成立的原因。如果你的任務依賴準確的跨檔案關係，這個技能會比一次性的說明型 prompt 更合適。

新手可以用嗎？

可以，只要他們能辨識專案根目錄，並描述自己要做的變更。主要的學習曲線在於理解 DSP 記錄的是程式結構，而不是面向人的文件說明。如果你看不出哪些檔案是 entrypoints，或哪些 imports 真的有被使用，這個技能在幫上忙之前，可能還需要更多 repo 脈絡。

什麼情況下不該用它？

如果你的任務主要是文案編修、UI copy，或只是單檔的小型腳本，而且圖譜記憶幾乎沒有幫助，就可以跳過 data-structure-protocol。當你沒有 source access、無法檢查 repo tree，或不打算在第一次處理後持續維護 DSP metadata 時，它也不是好選擇。

如何改善 data-structure-protocol 技能

提供圖譜真正需要的輸入

data-structure-protocol skill 要得到最佳結果，關鍵在於精準的來源參照：entrypoint 檔案、變更的模組，以及正在新增或移除的特定 symbol 或 import。若可以，請直接點名 root file 與受影響的路徑，例如 src/app.py、lib/index.ts 或 cmd/main.go，讓 agent 能把更新對應到正確的 entity。

注意常見失敗模式

最大的失敗模式是把 DSP 當成一般文件來用，卻跳過驗證。另一個常見問題是，只因 import block 裡有某個 import，就把它註冊進去，但實際上該檔案內容根本沒有用到。bootstrap 與 operations 文件都顯示 data-structure-protocol 在意的是經過驗證的關係，所以在記錄連結之前，應要求模型先確認實際使用情況。

第一次處理後再迭代

如果第一次輸出太廣泛，就把 prompt 收斂到單一階段：bootstrap、search、read 或 update。對於 data-structure-protocol for Skill Authoring，通常做法是：先請它找出受影響的 entities 與邊界檢查，再請它給出具體的 DSP operations 或檔案修改。最有效的迭代方式，是讓每一步都只有一個明確的結構目標，以及一個 repo 範圍。