前言¶
DeepSeek Harness（DSH）通過插件拼裝能力和界面，但當需求落在「多一個浮窗」「改輸入區旁邊的 chip」「給對話頁綁一套快捷鍵」這類細碎交互時，往往要動宿主或寫完整客戶端插件，改動面大、回滾也麻煩。社區裏也有用腳本或補丁改 UI 的做法，不過缺少統一的啓停邊界和與會話生命週期對齊的掛載點。
dsh-shape（npm 包名 @belowthetree/dsh-shape）由 belowthetree 維護，歸類爲客戶端插件。它把擴展單元抽象成 shape（形態）：一份清單加可選腳本，裝好後可以瀏覽、單獨啓停，並在 DSH 的固定槽位裏掛界面或註冊頁面級行爲。內置對話搜索與工作區切換兩種形態，並暴露 10 組內置能力供自定義形態聲明依賴。以下按「是什麼 → 能做什麼 → 安裝 → 用法要點 → 適用與注意」說明。
這是什麼¶
形態即插件包內或用戶目錄下的一棵目錄：package.json 描述元數據與能力依賴，views/ 可放頁面，客戶端模塊按需註冊面板、頁籤、邊緣窗和槽位內容。宿主負責加載、校驗依賴版本、把條目投進會話 UI，並在關閉形態時一併卸掉其視圖與邏輯。
與「整包 fork 客戶端」相比，形態粒度更輕：改文件後刷新頁面即可讓已有文件生效；增刪文件需在形態面板點刷新（或調用 POST /dsh-shape/api/refresh）後重載。
核心功能¶
Shape 瀏覽器與獨立視圖¶
對話頂欄有 Shapes 入口；也可用 Ctrl + . 打開應用網格，瀏覽全部形態。點擊卡片可在第二個窗口展示該形態自己的界面。
會話槽位與浮動 UI¶
形態可把內容掛到 10 類槽位，例如輸入框上方的卡片棧、下方信息條、可吸附浮窗、輸入條與頂欄的 chip、New Session 選項、View 菜單行，以及全屏覆蓋層。客戶端模塊在受支持槽位可用 api.mount() 渲染 DOM。
此外還有三類常見 API：
api.panel()：註冊浮動面板，open()後在輸入區上方出現，可拖動、吸附邊緣並記住位置。api.tab()：在右側欄增加頁籤，open()打開；同一頁重複打開只聚焦。api.edge()：從上/右/下/左邊緣居中滑入的窗口，內容來自views/；可綁快捷鍵，Esc關閉（可用esc: false關掉），width/height爲'full'時可佔滿一側。
每個形態可獨立啓停；關閉後其視圖、槽位條目與客戶端邏輯失效。卡片右上角可刪除形態目錄（需確認）。
能力依賴與內置能力¶
形態在 package.json 的 shape.requires 裏聲明能力，用 api.require('dsh-shape', '<能力名>') 取用；缺少依賴或版本不匹配時形態不啓動，也不顯示槽位條目。包內提供 10 個內置能力（工作區、界面、快捷鍵、槽位、事件、存儲、輸入框、對話讀取、MCP 服務器管理等），版本均爲 1.0.0。可通過 shape_capabilities 工具查看當前可用能力及 API 方法名。
示例（摘自 README）：
const ui = api.require('dsh-shape', 'ui')
const shortcuts = api.require('dsh-shape', 'shortcuts')
const store = api.require('dsh-shape', 'storage')
shortcuts.register({ id: 'summary', label: '顯示 MCP 摘要', keys: 'Ctrl+Alt+M', run: () => ui.notify('3 個服務器') })
await store.set('collapsed', true) // → <shape>/data/collapsed.json
內置形態¶
| 形態 | 觸發 | 作用 |
|---|---|---|
chat-search |
Ctrl + F 或頂欄搜索 |
對話內查找、高亮、展開摺疊思考塊、F3 / Shift+F3 跳轉 |
workspace-tab-switch |
按住 Ctrl 連按 Tab |
工作區預覽條，鬆手切換；Ctrl + Shift + Tab 反向 |
兩者位於包內 shapes/，可在 Shapes 面板啓停或刪除。將同名 id 複製到用戶目錄可覆蓋內置版本，升級插件不會覆蓋你的改動。
Shape Studio 預設¶
安裝後會增加 Shape Studio 預設：用 shape_list、shape_scaffold、shape_validate、shape_read、shape_write 等工具限定在形態目錄內讀寫與校驗，並附帶 shape-development、shape-playbook 兩份 skill。該預設沒有 bash/pwsh 與通用 tool-fs，形態外文件需通過其他預設或宿主能力處理。
安裝與啓用¶
要求 DSH 版本 >= 0.2.2-rc.1。當前包版本爲 0.4.39（MIT）。
在目標 profile 上執行（將 <profile> 換成例如 desktop、web）：
dsh plugin --profile <profile> add @belowthetree/dsh-shape
安裝後重啓該 profile。也可用插件管理器按包名 @belowthetree/dsh-shape 安裝，或 add github:belowthetree/dsh-shape、add link:/path/to/dsh-shape 做倉庫/本地聯調。
從舊的無作用域包名 dsh-shape 升級時：先 remove dsh-shape，再安裝作用域包，並把 profile 的 dsh.profile.bundles 裏條目改爲 @belowthetree/dsh-shape。
啓用後點擊頂欄 Shapes 或 Ctrl + . 即可管理形態。
典型用法¶
- 安裝並重啓 profile 後，在 Shapes 面板打開內置
chat-search、workspace-tab-switch體驗槽位與快捷鍵。 - 新建形態時，在
package.json填寫shape.requires，客戶端裏api.require取能力，按需調用panel/tab/edge/mount。 - 開發迭代：改已有文件後刷新頁面；新增或刪除文件後先在面板刷新或
POST /dsh-shape/api/refresh。 - 查契約與踩坑：倉庫
docs/（架構、形態目錄、能力參考、已知問題）及包內 skill；Shape Studio 下用shape_spec（含 playbook 主題）查規範。
更完整的交互演示見倉庫 demo/ 目錄（含 MP4 與復現步驟）。
適用場景與注意¶
適合：需要在 DSH 客戶端上快速加浮窗、側欄頁、邊緣命令面板、輸入區旁狀態 chip，或綁定頁面級快捷鍵的開發者；希望用清單 + 輕量腳本迭代 UI、而不是每次改整包客戶端的場景。
注意：
- 插件及形態客戶端邏輯以當前 DSH 進程權限運行，安裝與自定義形態前應查看 GitHub 源碼 與 MIT 許可證，僅安裝信任來源。
- 能力版本不匹配時形態不會啓動，開發時需對照
shape_capabilities與docs/capabilities.md。 - 社區插件目錄 SkillHub 條目 與 GitHub 倉庫由維護者與社區提供，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-shape 把 DSH 客戶端擴展收成「可啓停的形態」：固定槽位、浮動面板、側欄頁籤與邊緣窗一套 API，再加 10 組內置能力與兩個開箱形態。若要自己寫形態，裝上包後切 Shape Studio 預設，按 docs/shape-development 與 scaffold 工具從清單起步即可。
- 目錄頁：https://www.skillhub.cn/plugins/belowthetree/dsh-shape
- 倉庫：https://github.com/belowthetree/dsh-shape
