前言¶
在 DeepSeek Harness（DSH）裏通過 Magpie 的 MCP Hub 接入瀏覽器、網頁搜索、GitHub、DBX 數據庫、SSH、TapTap 等能力時，原生 MCP 客戶端會在註冊階段把全部工具 schema 一次性放進每次請求。Magpie 側工具數量可達 150 以上，對上下文和模型側工具列表都是實打實的負擔。
社區插件 dsh-magpie-discovery（維護者 donhac，分類：工作流）提供的是「按需發現」層：只增加一個小型查找工具 magpie_tools，在會話裏選中某個 Magpie 工具後，才把對應的原始工具定義暴露給模型。選中後的工具仍走 DSH 原生執行管線，不是第二個 MCP 客戶端，也不是調用代理。
這是什麼¶
dsh-magpie-discovery 是掛載在 DSH Host 或 Agent Preset 上的插件包（當前 package 版本 1.2.0，許可證 MIT）。它不改變 Magpie 連接方式：若 profile 裏未配置 Magpie MCP 服務器，magpie_tools 會報告空目錄，其它工具不受影響。插件本身也不定義編碼模式、人設、模型路由或圖像工作流，可與任意需要 Magpie 的 preset 組合使用。
核心功能¶
資料中明確列出的能力如下。
magpie_tools：按關鍵詞搜索、按精確名稱加載、查看當前狀態，或reset清空當前選擇。- 會話級選擇：從原生 session log 恢復；resume、compaction、fork 後仍可對齊狀態。
- deny-mask 可見性層：對未選中的
mcp__magpie__*工具隱藏 schema 展示，不復制、不包裝、不重新註冊真實 Magpie 工具。 - 無額外 MCP 連接：不新增賬號存儲、OAuth 或遠程調用包裝；圖像、結構化返回值、錯誤、審批與結果元數據保持 DSH 原生行爲。
- 1.2.0：發現結果返回相對上一輪的
added、evicted、unchanged；可用names配合replace: true在一次調用中原子替換爲最多 12 個工具的完整集合（任一名稱不可用則保留舊選擇）。
運行時最多保留最近選中的 12 個工具；再次選中會刷新排序，超出上限時淘汰較早項。成功提交 magpie_tools 結果後，所選工具在緊接着的下一次模型請求中可見；同一步 assistant 內已規劃的工具無法 retroactive 獲得定義，需先 lookup，下一步再調用原始 Magpie 工具名。
環境與依賴¶
安裝與運行前請覈對版本約束（來自 README 與 package.json）：
- DeepSeek Harness：
>=0.2.1-rc.5且<0.3.0（文檔註明在0.2.1-rc.5上測試）。 - Node.js：
>=22.19.0。 - Host 需具備服務：
tools、systemPrompt、sessionProjections、agentPresets、agents。 - Magpie 已運行 MCP Hub，且 DSH 側 已有 指向 Magpie 的 MCP 客戶端連接。
本插件不會創建 Magpie 連接。
安裝與啓用¶
在 Plugin Manager 中選擇 Install bundle，輸入：
github:donhac/dsh-magpie-discovery
或在 DSH CLI 中（將 <profile> 換成你的 profile 名）：
dsh plugin --profile <profile> add github:donhac/dsh-magpie-discovery
固定版本示例：
github:donhac/dsh-magpie-discovery#v1.2.0
安裝後 bundle 與插件行顯示爲 dsh-magpie-discovery；bundle 還會插入一條默認 disabled 的 Host 行 magpie-tool-discovery。下面兩種用法二選一，不要同時啓用 Host 行又在 preset 裏掛載同一包，否則會註冊兩個同名 magpie_tools 與 projection key。
方式 A：掛到 preset（推薦）¶
在 @deepseek-ai/dsh-agent-preset 的 plugins 列表增加：
- id: magpie-tool-discovery
name: dsh-magpie-discovery
config:
presetId: my-preset
presetId 必須是包含該行的 preset 的 id，以便 agent 切換 preset 時插件能卸掉對應限制。僅使用該 preset 的 agent 會走按需發現；其它 preset 仍可保留完整 Magpie 工具集。
方式 B：啓用 Host 行（全局）¶
在 Plugin Manager 中啓用已安裝的 magpie-tool-discovery 行，則當前 profile 下所有 agent 都會應用發現層。
| 配置項 | 是否必填 | 含義 |
|---|---|---|
presetId |
preset 掛載時建議填寫 | 擁有該插件實例的 preset id；切換 preset 時用於 detach |
Host 行無需配置，行爲爲全局。
典型用法：magpie_tools¶
README 中的調用示例可直接復現：
magpie_tools({ query: 'browser tabs', limit: 2 })
magpie_tools({ query: '數據庫表結構' })
magpie_tools({ query: 'dbx list connections sessions read only query', limit: 6 })
magpie_tools({ query: 'nyatermSsh connection_list session_open terminal_execute', limit: 6 })
magpie_tools({ names: ['mcp__magpie__playwright__browser_tabs'] })
magpie_tools({})
magpie_tools({ reset: true })
參數要點（與文檔一致）：
query：搜索工具名與描述；英文 API 詞與常見中文能力詞均可。識別到服務名時結果限定在該服務內；無 scope 的多關鍵詞仍爲 AND。完整精確工具名排序靠前。+爲分隔符而非運算符。names：按 1–6 個精確的mcp__magpie__...名稱增量加載；配合replace: true可原子替換爲 1–12 個名稱的完整集合，且不能與query、reset或分頁同時使用。limit：1–6，默認 3；offset分頁。- 空參數調用返回當前選擇與各 service 計數；
reset: true清空選擇。
成功結果中會包含相對上一輪的 added、evicted、unchanged；已在可見集合中的工具可直接調用，無需再次 lookup。
工作原理（簡述）¶
插件掃描以 mcp__magpie__ 開頭的全局工具名，對每個 agent 施加一條限制：deny = 當前 Magpie 目錄 − 本會話已選工具。該限制同時作用於 schema 展示、lookup 與 dispatch。選擇狀態由 magpie_tools 在 tool result 的 presentationMeta 中寫入版本化標記與完整列表；Host 側的 session projection 在校驗來源事件、turn/step、成功 append 及元數據版本後纔會接受狀態。成功 commit 後，同步的 session/event 監聽器會在下一次工具 schema 組裝前刷新 mask。卸載時按序釋放 agent 策略、監聽器與工具，最後移除 projection。
適用場景與注意¶
適合已經在 DSH 中連接 Magpie、但希望把「150+ 工具 schema 常載」改爲「按任務階段加載少量工具」的工作流場景；需要全局 Magpie 全量暴露的 preset 可繼續不掛載本插件。
插件在 當前 DSH 進程權限 下運行，安裝前請自行審閱 GitHub 倉庫 源碼與 MIT 許可證。DSH 生態強調「一切皆插件」；SkillHub 目錄頁 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-magpie-discovery 用單個 magpie_tools 把 Magpie 大目錄 defer 到按需 reveal，同時保留 DSH 原生 MCP 執行與審批鏈路。需要安裝說明與變更細節時，以倉庫 README 與 CHANGELOG 爲準。
- 目錄頁：https://www.skillhub.cn/plugins/donhac/dsh-magpie-discovery
- GitHub：https://github.com/donhac/dsh-magpie-discovery
