AI-Scarlett/build-dsh-plugin

建構 DSH 外掛程式

使用此工作流程將 DSH 外掛程式想法轉換為標準套件，無需修改或覆蓋 Harness 本身。

標準化使用者簡報

對於每個新的外掛請求，請閱讀 intake.md。接受一般語言、簡短的中文簡報或位於 plugin-brief.template.json 的結構化 JSON 範本。

在原始碼生成之前，只需三個語義事實：

1. 目前的使用者問題；
2. 預期的使用者結果；
3. 至少一個可觀察的驗收標準。

推斷名稱、套件 ID、架構候選方案、風險類別、專案結構、測試和安全預設值。除非使用者有偏好，否則不要要求使用者設計主機 API、Cordis 條目、模式、建構工具或測試策略。

當選填欄位缺失時，預設僅進行原始碼生成、標準 DSH 套件、唯讀行為、無實際 Profile 變更、無重新啟動、無外部網路/程序/帳戶/裝置、無憑證、僅限本機暴露、不發佈，以及 E3 可拋棄式驗收。預設建置具有市場相容套件結構的可重複使用 DSH 套件，但不要推斷提交或更改 DSH STORE 的權限。將每個預設值陳述為一個假設。不發佈 是一項權限預設值，並非永久禁止：一個經過明確授權、適當許可、內部一致且固定的版本可以從網站分發或提交給市場。

僅詢問那些會實質改變產品成果或風險邊界的問題。缺少問題、結果或驗收標準會阻礙生成。缺少目標 Profile、變更範圍、憑證擁有者、LAN/Internet 安全性或實際裝置/帳戶，只會阻擋對應的實際操作；當介面可以保持抽象時，它不會阻擋安全的原始碼支架。

當 JSON 簡報可用時，執行確定性標準化器：

node scripts/normalize-brief.mjs /absolute/path/to/plugin-brief.json
node scripts/normalize-brief.mjs /absolute/path/to/plugin-brief.json --json

如果標準化狀態為 READY 或 READY_WITH_ASSUMPTIONS 且請求的模式為 build-source，則無需再次進行廣泛澄清即可進行階段 0-6。除非另有授權且完全指定，否則在發佈、實際 Profile 變更、重新啟動、憑證、裝置或公開暴露之前停止。

建立合約

以唯讀模式開始。檢查儲存庫說明、目標 DSH 版本、官方外掛文件、僅在相關時檢查活躍 Profile，以及一個目前的標準外掛範例。不要假設來自較舊專案的 API 或套件合約。

始終強制執行這些規則：

• 建置 DSH 套件，而非桌面應用程式或 DSH 的分支。
• 永遠不要修改 DSH 原始碼樹或任何 @deepseek-ai/* 套件。
• 永遠不要停用、取代或覆蓋官方外掛庫存。
• 永遠不要呼叫 Loader/Fiber 變更 API。使用公共 Host 服務和套件組合。
• 使用官方 DSH CLI 進行套件更改。傳遞固定的引數陣列；永遠不要建構 shell 命令字串。
• 將測試保留在可拋棄的家目錄/profile 中。永遠不要針對實際的 ~/.dsh 寫入測試。
• 不要透過日誌或用戶端暴露憑證、完整使用者檔案、注入的系統/外掛上下文、模型推理或私有路徑。
• 將規劃、程式碼完成、套件版本發佈、Profile 安裝、執行時期驗收以及外部/裝置驗收保持為分離的狀態。
• 將外掛就緒狀態、目錄候選就緒狀態、Registry PR/CI、已合併的目錄、公開市場能見度以及 Profile 安裝保持為分離的狀態。
• 將規範的 Tool 輸出、模型面對的渲染、提供者中立的卡片意圖以及可選的自訂用戶端渲染保持為分離的合約。

在實作或安裝之前閱讀 boundaries.md。該文件中的硬性阻擋者會覆蓋其他所有評分。 在實作模型 Tool、presentCall、presentResult、presentationMeta 或自訂 Tool 卡片之前閱讀 card-contract.md。

解釋每個有影響力的決策

不要發出一份規則清單而不附上其決策邏輯。對於每個架構、權限、變更、版本發佈或驗收決策，記錄：

1. 目標：該決策所控制的失敗或結果。
2. 理由：為什麼 DSH 機制或當前威脅模型需要它。
3. 效益：什麼變得更安全、更簡單、更相容或更容易驗證。
4. 成本：實作負擔、UX 摩擦、效能成本、能力損失或操作延遲。
5. 適用性：該決策適用的條件。
6. 替代方案：可行的選項、為什麼被拒絕，以及何時重新考慮它們。
7. 程序：具體步驟、擁有者、輸入、輸出和回滾行為。
8. 證據關卡：推進所需的可觀察證明以及停止工作的條件。

在規劃、審查或解釋外掛程式時閱讀 decision-guide.md。使用其決策卡片，而非未經分析就複製偏好的模式。

執行工作流程

遵循 workflow.md 以了解完整的階段關卡流程和所需工件。不要僅僅因為類似的外掛之前通過了就跳過某個階段；DSH 版本、Profile 組合、相依性和外部服務可能會發生變化。

1. 證明主機適用性

識別目標主機、擴展接縫、請求的使用者結果、狀態變更、外部相依性和驗收表面。

當專案目標是 Obsidian、VS Code、瀏覽器擴展、僅 MCP 或其他沒有經過驗證的 DSH 套件合約的執行時期時，停止並報告主機不匹配。提供相容的主機或刻意限定範圍的轉接器。不要轉向相關的專案。

產出主機合約記錄和架構比較。關卡：compatible、adapter-required 或 incompatible；切勿將其留作隱晦的散文。

2. 分類風險

從 scorecard.md 指派一個類別：

• R0：唯讀元資料/UI。
• R1：主機工具/服務或使用者擁有的外掛狀態，無 Profile 生命週期寫入。
• R2：外部程序、網路、憑證或裝置橋接。
• R3：Profile 生命週期、重新啟動、遠端控制或廣泛管理。

當不確定時使用較高的類別。在編碼之前記錄非目標和禁止的表面。

產出一份風險登錄表，命名資產、參與者、信任邊界、寫入表面、失敗影響、最低證據等級以及選擇該類別的原因。

3. 選擇標準模式

• 僅主機套件：公開一個公共 Cordis 服務/工具並貢獻一個或多個唯一的修補行。
• 主機 + 用戶端：將 Browser 程式碼分開；使用 window.__ModuleLoader__.load() 和插槽註冊。Browser 程式碼不得匯入主機/Node 模組。
• 可選 Web 路由：使用 ctx.inject(['webServer'], ...) 延遲註冊；無頭/無 Web 的 Profile 仍然必須啟動。
• 技能轉接器：掛載隔離的技能檔案；不要靜默安裝外部執行時期、擴展或憑證。
• ApiProxy 橋接：使用允許清單、編輯、身份驗證、有界解析和故障關閉傳輸安全性來適配狹窄的公共遠端表面。
• 生命週期管理器：將每個 Profile 更改視為 R3 交易，並使用下面的變更協議。
• 工具卡片合約：偏好提供者中立的 presentCall/presentResult 渲染意圖；僅在檢查過的內建詞彙無法表達結果時，才為外掛擁有的 Tool 使用自訂用戶端插槽卡片。

使用 dsh.bundle.patch、一個可套件解析的 cordis.patch.yml、唯一的條目 ID、明確的檔案、版本、許可證和建構合約來建立套件清單。請記住，後續的修補層會取代一整行的完整 config；它們不會深度合併它。

當選擇會影響權限、程序邊界、安裝行為或使用者體驗時，比較至少兩個合理的模式。記錄效益和成本；不要僅僅因為早期專案使用過某個架構就選擇它。

4. 實施最小權限

使用已檢查過的 DSH 版本提供的公共服務。如果所需的接縫不存在，則停止並提議轉接器或上游更改，而不是修補核心。

偏好唯讀發現和乾執行/預覽 API。使寫入功能分開啟用。在業務邏輯之前驗證模式和大小的限制。拒絕格式錯誤的 Profile、不明確的路徑、未知的官方元件、過時的狀態、重播、並發更改和缺失的證據。

對於每個模型 Tool，記錄規範的輸出、模型面對的渲染器、待處理卡片、已完成卡片、持久的呈現元資料、邊界/編輯、通用回退以及即時/重播證據。呈現器必須是確定性的，並且不執行 I/O、時鐘/隨機存取、工作階段讀取或額外的權限相關工作。永遠不要將憑證、完整的私有檔案、模型推理或無界引數放入卡片中。

對於重複出現的失敗模式，請閱讀 problem-playbook.md。

產出一份權限矩陣，包含每個資料來源/動作、擁有方、允許的呼叫者、編輯、大小/速率限制、失敗模式以及測試。任何沒有使用者結果和測試的權限都將被移除。

5. 應用變更協議

對於 Profile/套件/重新啟動變更，為恰好一個操作建立一個全新的類型化計畫，其中包含：

1. 操作和目標 Profile；
2. 不可變的套件/原始碼身份；
3. 精確的檔案範圍和預期的前提條件雜湊值；
4. 命令 argv 和工作目錄；
5. 備份位置和回滾程序；
6. 後置條件和健康檢查；
7. 一個精確的確認短語；
8. 過期時間和一次性使用身份。

顯示計畫並等待精確的每個操作確認。在不匹配、過期、並發更改或先前使用時使其失效。在寫入之前進行備份，原子提交，執行配置和執行時期健康檢查，並在失敗時回滾。儲存庫版本發佈永遠不會授權本地 Profile 更新。

將確認摩擦和交易機制視為顯式成本。接受這些成本作為 R3，因為替代方案是用戶狀態的靜默、難以恢復的損壞。不要將變更協議強加於純粹的 R0 讀取。

6. 攀登證據階梯

僅使用當前證據推進：

• E0：想法或計畫。
• E1：靜態結構/原始碼審查。
• E2：自動化單元/合約/錯誤測試。
• E3：可拋棄 Profile 安裝、--dump-config、啟動和 API 煙霧測試。
• E4：分別確認的實際 Profile 版本、程序/連接埠、官方庫存/API 和可見的 UI 回讀。
• E5：外部/公開/裝置驗收以及故障復原或回滾證據。

永遠不要從較低等級推斷出較高等級。UI 螢幕截圖不能證明回滾；HTTP 200 不能證明可見的 UI；安裝成功不能證明重新啟動健康；模擬器輸出不能證明真實裝置。

對於 Tool 卡片，E2 包括確定性呈現器、格式錯誤的重播、編輯、邊界、截斷和通用回退測試。E3 包括在隔離的 DSH 執行時期中的即時加持久重播一致性。使用者 Profile 中可見的卡片行為仍然是 E4。

為每個能力產出一份證據矩陣。包括負面證據和復原證據，而不僅僅是快樂路徑。評分表示就緒程度；它永遠不會授予權限或取代硬性關卡。

7. 分開釋出與安裝

在儲存庫版本釋出之前，同步套件版本、README、目錄條目、不可變的安裝錨點、測試和固定的原始碼元資料。對於 Git 原始碼，要么發布建構的工件，要么宣告一個自包含的 prepare 腳本並揭露 pnpm allowBuilds；鎖定一個完整的 commit SHA。

執行儲存庫檢查、原始碼驗證和打包乾執行。合併後驗證遠端 commit 和公共資產。然後停止。僅在新的已確認變更計畫下更新實際 Profile，透過批准的機制重新啟動它，並回讀解析的版本和執行時期狀態。

產出兩份獨立的報告：儲存庫版本釋出證據和 Profile/執行時期驗收證據。當第二份報告缺失時，請說明 Profile unchanged 或 Profile unverified。

8. 使可重複使用的外掛為 DSH STORE 做好準備

每當建置可重複使用的第三方 DSH 外掛、評估現有儲存庫是否符合 DSH STORE 要求，或準備目錄條目時，請閱讀 marketplace.md。

不要等到提交時才發現清單不相容。從第一個支架開始，保留唯一的套件/目錄/條目 ID；宣告儲存庫、版本、許可證、安全的 dsh.bundle.patch、相對於套件的 Patch、執行時期/建構檔案、生命週期腳本、權限、相依性和相容性證據。在每次 STORE 評估開始時，執行 node scripts/official-dsh-releases.mjs 並使用其官方最新的三個版本視窗；不要重用記住的視窗。解析器遵循最高的活躍 npm latest/alpha/beta/rc 頻道，排除僅 next 和已棄用的版本，並在無效權限時故障關閉。觀察到的 2026-09-02 視窗是 0.1.2-alpha.2、0.1.2-alpha.3 和 0.1.2-alpha.4，但這是一個證據而非永久常數。在已解析視窗中的每個版本上，保留精確的 compatibility.dshReleases 和匹配的 compatibility.dshOperations 記錄，用於安裝、啟動、解除安裝和回滾。歷史金鑰可能會保留，但未知的元資料應保持未知，而不是被猜測。

保持 STORE 的發現和信任安裝在物理和邏輯上分離。registry/candidates.json 中的記錄僅供發現，不附帶任何套件/安裝/權限合約，並且必須標準化為 installable: false 且不允許任何操作。它只有經過單獨的固定來源、套件、許可證、權限、相容性和證據審查後，才能移動到 registry/catalog.json。推廣、推薦、贊助、星標或螢幕截圖是單獨的品質訊號；它們不會取代或覆蓋這些審查。

{
  "compatibility": {
    "dshReleases": ["0.1.2-alpha.2", "0.1.2-alpha.3", "0.1.2-alpha.4"],
    "dshOperations": {
      "install": "...",
      "start": "...",
      "uninstall": "...",
      "rollback": "..."
    }
  }
}

9. 範例

假設一位使用者要求「一個幫助我對大型 JSON 檔案執行語義搜尋的外掛程式」。標準化器會提取：問題（在大量 JSON 中尋找內容很困難）、結果（快速語義搜尋）和驗收標準（"找到與 'unused fields' 相關的所有物件"）。它會預設為 R1（讀取文件，無變更），使用主機工具模式，並在規格中記錄假設，例如僅本機暴露、使用向量嵌入進行搜尋、無網路呼叫。然後，它會引導使用者通過工作流程，從建立合約開始，最終生成一個可重複使用的 DSH 套件。

這就是建構 DSH 外掛程式的完整指南。