前言¶

DeepSeek Harness（dsh）可以通過 MCP 把外部能力掛進智能體。Undermind 是面向研究場景的 AI 文獻檢索服務：用自然語言描述研究目標，返回按相關性排序的論文，並支持 PDF 閱讀與工作區整理。其遠程 MCP 端點爲 https://mcp.undermind.ai/mcp，但只接受 OAuth 授權碼 + PKCE 簽發的 Authorization: Bearer；訪問令牌約一小時過期，刷新令牌每次使用都會輪換。dsh 內置的 @deepseek-ai/dsh-mcp-client 只能轉發靜態請求頭，沒有續期邏輯，無法長期維持這條連接。

dsh-plugin-undermind（維護者 VANuVANuu，GitHub 倉庫 VANuVANuu/dsh-plugin-undermind，社區目錄 SkillHub 條目）在 dsh 進程內自行完成 OAuth/PKCE 登錄、令牌存儲與刷新，並把 Undermind MCP 工具註冊爲 mcp__undermind__*。分類爲聯網工具；當前 package 版本爲 0.1.0，許可證 MIT，要求 dsh >=0.2.1-rc.3 <0.3.0-0。

這是什麼¶

插件把 Undermind 的遠程 MCP 服務接入 dsh，使智能體可以檢索文獻、讀 PDF、整理論文。每個用戶用自己的 Undermind 賬號授權，沒有 API Key 或服務賬號模式。插件以 ESM 形式發佈，無構建步驟，通過 Cordis patch 與宿主共享 @deepseek-ai/cordis、@deepseek-ai/schemastery 等 peer 依賴。

爲什麼需要插件而不是隻配 MCP¶

Undermind 端點的認證模型與靜態 MCP 客戶端不匹配。插件負責：

1. OAuth/PKCE 登錄 — 一次性 loopback 回調服務 + 系統瀏覽器完成授權。
2. 令牌存儲與刷新 — 默認寫入 $DSH_HOME/storages/undermind-mcp-auth.json，權限 0600、原子替換；到期前 90 秒刷新；遇 401 強制刷新並重試一次；輪換後的 refresh token 立即落盤。
3. MCP 會話 — initialize → notifications/initialized，每次調用攜帶 mcp-session-id，支持 JSON 或 text/event-stream；服務端返回 404 時重建會話。
4. 工具註冊 — tools/list 返回的工具以 mcp__undermind__<name> 註冊；未授權時不註冊任何 Undermind 工具；換賬號或改 clientId 會丟棄上一代工具。
5. undermind_auth 工具 — 始終可用，動作爲 status、login、logout、refresh、retry，便於在對話裏修復會話。
6. 宿主 HTTP 路由 — /dsh-undermind/api/ 下提供瀏覽器側授權與診斷接口。

請勿同時爲該服務再添加 @deepseek-ai/dsh-mcp-client：它不能刷新令牌，且工具名會與插件衝突。

前置條件：賬號與 client id¶

1. 需要 Undermind 賬號。
2. 需要 client id。Undermind 不支持動態客戶端註冊，可選：
   - CIMD：在你控制的 HTTPS URL 上託管 Client ID Metadata Document（JSON），把該 URL 填入插件 clientId；
   - 預註冊 client id：向 support@undermind.ai 申請。

CIMD 自助路徑示例（client_id 必須與 URL 字節級一致，redirect_uris 須包含插件的 redirectUri）：

{
  "client_id": "https://example.com/undermind-client-metadata.json",
  "client_name": "DeepSeek Harness",
  "redirect_uris": ["http://127.0.0.1:8799/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "mcp"
}

文檔須以 application/json 提供。GitHub raw.githubusercontent.com 常爲 text/plain，Gist 可用 gist.githack.com 鏡像；GitHub Pages 可直接使用。修改 redirectUri 時須同步更新 CIMD。本地可訪問 GET /dsh-undermind/api/client-metadata 獲取帶當前 redirectUri 的模板。

安裝¶

CLI 安裝（將 web 換成你的 profile 名）：

dsh plugin --profile web add github:VANuVANuu/dsh-plugin-undermind

Electron 桌面客戶端保留 desktop profile，dsh plugin CLI 不能向其安裝；可從插件市場安裝，或將包放到 profiles/desktop/node_modules 並在 dsh.profile.bundles 中加入 dsh-plugin-undermind。

DSH 社區插件目錄在 SkillHub 等獨立站點維護，與 DeepSeek / 幻方無官方從屬關係；安裝前宜自行查看倉庫源碼與 MIT 許可證。插件以當前 dsh 進程權限運行，令牌僅寫在本地機器。

配置¶

字段在插件設置中保存後，下一次調用生效，無需重啓進程。

典型用法¶

首次登錄¶

在對話中讓智能體連接 Undermind，或調用：

undermind_auth action="login"

插件在 redirectUri 端口啓動一次性服務，用 PKCE 構造授權 URL 並打開默認瀏覽器。批准後瀏覽器回到 127.0.0.1:8799/callback，插件換碼、寫令牌並註冊工具。mcp__undermind__* 隨即對模型可見；undermind_auth action="status" 可查看 toolCount 與已註冊名稱。

日常使用¶

• 描述研究問題並指定時間範圍 → 可調用 mcp__undermind__launch_deep_search 啓動異步深度檢索（可能數分鐘），用 inspect_deep_searches 輪詢。
• 按摘要找相似論文 → mcp__undermind__search_papers。
• 批量讀 PDF 並歸納方法 → mcp__undermind__read_pdfs（每篇論文單獨子智能體，含圖表）。
• 整理到文件夾 → create_folder、add_papers_to_folder 等（註冊名均帶 mcp__undermind__ 前綴）。

display_deep_search_results、display_references、suggest_pdf_uploads 在支持 MCP Apps 的智能體裏是交互卡片；在 dsh 中僅返回文本與鏈接。

排錯¶

Loopback HTTP 路由（僅 localhost / 127.0.0.1 / [::1]，sec-fetch-site: cross-site 會被拒絕）包括 GET /dsh-undermind/api/status、POST /dsh-undermind/api/login 等；響應包絡爲 {"ok":true,"data":…} 或 {"ok":false,"error":{…}}。

適用場景與注意¶

適合需要在 dsh 智能體工作流裏做文獻檢索、讀 PDF、管理論文集合的研究與開發場景。不適合期望「只填一個靜態 MCP URL 就能用」的部署方式——認證必須由本插件或等價的 OAuth 續期邏輯承擔。

安裝與啓用前請閱讀倉庫 README 與源碼；令牌不離開本機，但仍依賴你對 Undermind 賬號與 OAuth 客戶端文檔的安全託管。

結尾¶

dsh-plugin-undermind 把 Undermind 的 OAuth MCP 連接做成 dsh 一等插件：登錄、續期、會話與 mcp__undermind__* 工具註冊一體化，避免與內置靜態 MCP 客戶端硬配。更多信息見 GitHub 倉庫 與 SkillHub 目錄頁。