dsh 設定教學：Profile、Patch 與 Agent Preset

一切都是一棵外掛樹

執行中的 dsh 不是一個「自帶一堆功能的程式」，而是一棵外掛樹——啟動時由層層設定組裝出來的 Cordis 外掛系統。每一項能力（工具、模型接入、儲存、沙箱、UI、主迴圈）都是樹上的一個外掛，而設定層決定了存在哪些外掛、以什麼順序存在。

這就是全部的心智模型。剩下的篇幅就是把每一層拆開講。

從底層到頂層的各層

設定按固定順序疊加，上層覆蓋下層：

┌─────────────────────────────┐
│  Patch（你的覆蓋層）            ← 優先級最高
├─────────────────────────────┤
│  Profile（你的具名組裝清單）
├─────────────────────────────┤
│  Bundle（官方外掛組合包）
└─────────────────────────────┘

• Bundle（組合包） —— 官方發佈的成套外掛。第一次啟動時的預設體驗就是一個 Bundle。
• Profile —— 你機器上的具名組裝清單，內容是「載入哪些 Bundle 和外掛、用什麼設定」。可以保留多套、隨時切換。
• Patch（覆蓋層） —— 你自己的修改層。可以精確定位到任意一個外掛條目並替換，不動它所屬的 Profile。

因為每一層都只是設定，分享一套環境就是分享幾個檔案——把 Profile / Patch 檔案發給你，就等於把「他的 dsh」交給你。

Patch 層：給 Agent 裝能力的裝扮系統

內建 Patch 層是 dsh 最不像其他 Agent 的部分。把它理解成一套裝扮系統——你決定代理「穿」上哪些能力，以及在什麼條件下生效：

• 把本機 Agent 掛成子 Agent。 你電腦上的 Codex 和 Claude Code 可以註冊為 Harness 調度的子 Agent，而不是被取代掉的競品。
• 接入各種能力。 安裝外掛來新增工具、接入外部的服務、調整執行權限、開啟全文搜尋。
• 替換 UI。 介面模組同樣是外掛——皮膚、面板甚至整個 UI 元件都能透過 Patch 換掉。
• 規則按條件生效。 規則用 JavaScript 表達式定義，讓能力只在你想要的地方生效：某個倉庫、某類檔案、某個時間段。

Patch 精確到單個外掛條目，所以上面每一項都是一個可加、可查、可移除的覆蓋，不動它下面的 Profile。

為什麼「裝外掛」其實是改設定

dsh 沒有那種「一鍵安裝、從此不管」的中央套件管理器。安裝外掛意味著往 Profile / Patch 層裡加一筆記錄，外掛倉庫的 README 會給出確切的那一行。下次啟動時外掛進入外掛樹；卸載時，它註冊過的一切自動撤銷——註冊必須是可逆的副作用，所以壞外掛也留不下殘餘（見外掛開發入門教學）。

內建外掛管理頁能做什麼、不能做什麼

0.1.6 alpha 線（alpha.2，發布於 2026-09-17）在 dsh 內新增了外掛管理頁：安裝外掛、修改外掛設定，並且支援執行期啟用／停用外掛——這個開關本身不必重新啟動。同一次發布也把外掛相依解析改為執行期解析、支援執行期卸載，發布說明點名要求外掛開發者檢視載入與卸載邏輯。穩定線（npm latest）目前仍是 0.1.5-rc.2，所以看不到這個頁面，代表你不在 alpha 通道上。

用之前值得把兩件事分開：

• 內建頁面管的是你已經裝了的東西——目前 profile 裡的外掛集合與每個外掛的 options。它並沒有換掉本頁在講的那一層，只是同一份 profile / patch 狀態換了個更好用的入口。
• 它不回答該裝什麼。沒有全網排序、沒有依場景分組、沒有「誰和誰搭配用」——那正是目錄站負責的部分。先去 外掛合集 或 十大必裝外掛 複製安裝指令，裝完之後開關與設定再交給內建頁面。

執行期解析帶來的一個副作用：今天能正常載入的外掛，在 harness 升級後可能因為作者還沒適配而失敗。真遇到了，疑難排解第八節 寫了怎麼鎖版本與回滾。

外掛到底裝在哪：磁碟路徑一覽

正因為「裝外掛」只是改設定，幾乎沒有東西會被複製進某個隱藏的系統目錄。安裝真正做的事，是往 Profile 裡寫一筆依賴記錄——而每個 Profile 就是一個你可以直接打開、檢視、備份的普通目錄：

順著這個布局有兩個實用習慣。第一，找不到某個外掛時，先列出 Profile 再翻檔案系統：dsh plugin --profile web list 會告訴你這份 Profile 裡到底有哪些依賴條目、它又是從哪個目錄讀到的。第二，備份或分享一套環境就是複製檔案：一個 Profile 目錄加一個 Patch 檔案就是全部。反過來，想徹底清空也是刪這些路徑（見dsh 外掛移除與徹底清理）。

會話封存與清理

會話就是 harness 主目錄（~/.dsh，可用 DSH_HOME 改）底下的檔案。對它們常見的三種動作經常被混為一談：

• 封存只是改可見性：會話從活躍清單消失，但仍留在磁碟上。刪除這一側確實還很陽春——討論 #8344 問的正是封存會話怎麼刪除、能否集中顯示，官方至今沒有文件化按會話刪除的指令。
• 匯出是官方文件裡白紙黑字的「封存」：會話日誌匯出帶 ZIP 壓縮的封存策略（見設定目錄文件）。想要一份帶得走的對話副本？動手清理之前先匯出。
• 清理指的是刪掉 harness 主目錄下的會話檔案——和本頁其他操作共用同一條規矩：先備份。刪掉整個 ~/.dsh 是徹底重置（dsh 外掛移除與徹底清理有完整步驟）；升級 harness 之前，社群多重執行個體管理工具 dsh-lanes 會按安裝副本備份對話，升級失敗也不會把歷史紀錄一起帶走。

dsh 指令速查

dsh 指令是上面這一切的入口——而從 0.2.0-rc.2 起，它還成了桌面端的一等公民：macOS 和 Windows 桌面應用程式的選單列新增了 「Manage dsh command」，可以直接安裝和管理 dsh 指令、連外掛一起管，不需要另裝 Node.js 或 pnpm。如果你的終端機出現 dsh: command not found（找不到指令），這個選單項目就是官方新解法（另見疑難排解 §11）。

對其他人來說，日常要記的指令就這幾條：

兩個值得保留的習慣：動手排查前先看 dsh --version；安裝時用的 --profile 要和啟動時的一致——這是「我的外掛不見了」最常見的原因，其餘場景見疑難排解。 可列印版本見 dsh 命令列速查表，常用指令、flag 與啟動模式一頁打盡。

Agent Preset：一個會話的形狀

介面頂部的模式選擇器，選的是 Agent Preset（代理預設）——當前會話裡代理的完整定義：

• 擁有哪些工具；
• 什麼樣的系統提示詞；
• 載入哪些 Skills；
• 子代理與工作流的設定。

預設不是「外掛清單 + 一段提示詞」，而是整個會話賴以執行的契約。所以會話一旦產生內容就鎖定預設——中途切換會讓歷史裡的工具呼叫無法被新工具集解釋。

四個內建預設：

打造自己的預設

創造模式（Creation） 是設計新預設的正規途徑：直接描述需求（「一個唯讀的程式碼審查員，絕不改檔案，用中文回答」），Harness 會檢查當前執行時、在記憶體裡試驗外掛、起草設定、掛載驗證，最後儲存下來供複用。

想要實戰版？逐幀核對的圖文教學自訂 Agent 預設實戰完整走一遍——從創造模式到儲存可用預設，每一步都有截圖。

官方文件裡的兩句提醒值得重複：

• 創造模式會執行模型寫的程式碼並修改執行時——信任等級等同 shell；
• 預設就是設定，把它設為預設之前，先檢查它到底儲存了什麼。

什麼時候該停止折騰設定

最舒服的預設是：用標準模式，幾乎什麼都不改。 只有當你反覆需要同一套環境（團隊共用一個 Profile）、想給某類工作固定工具箱、或者只想換掉一個元件（換模型接入、收緊審批策略）時，才去動 Profile 和 Patch。上層覆蓋層的存在，就是為了讓你只改一處、不必推倒重來。

繼續閱讀

• 2026 必裝外掛排行榜 Top 10 與情境套件 —— 一鍵設定高頻外掛組合
• 2026 必裝外掛推薦清單（12 款首選）
• 按情境探索精選合集
• dsh 外掛安裝教學
• dsh 外掛移除與徹底清理 —— 移除單一外掛、解除安裝 harness 本體或清空 ~/.dsh
• 沙箱、審批與金鑰 —— 這些設定層接入的安全模型
• DeepSeek Harness 安裝教學：5 分鐘跑通 dsh
• dsh plugins 生態盤點