文献深搜 VANuVANuu/dsh-plugin-undermind

dsh-plugin-undermind

把 Undermind（学术文献检索与深度综述服务）接进 DeepSeek Harness（dsh）。你用自己的话描述研究目标，它返回按相关度排序的论文列表，并提供 PDF 精读与工作区归档。安装后模型可以直接调用 mcp__undermind__launch_deep_search、mcp__undermind__search_papers、 mcp__undermind__read_pdfs 等工具。

为什么需要插件

Undermind 的 MCP 端点 https://mcp.undermind.ai/mcp 只接受 Authorization: Bearer，令牌走授权码 + PKCE（公共客户端、无 secret）。access token 1 小时过期，refresh token 每次使用后轮换。dsh 自带的 @deepseek-ai/dsh-mcp-client 只透传静态 headers，没有续期能力，撑不住这条连接。所以本插件自己维护它：

- OAuth/PKCE 登录：一次性回环回调服务 + 系统默认浏览器。
- 令牌落盘与自动续期：写到 $DSH_HOME/storages/undermind-mcp-auth.json（0600、原子替换），到期前 90 秒刷新；遇到 401 强制刷新并重试一次；轮换后的 refresh token 立即覆盖旧值。
- MCP 会话：initialize → notifications/initialized，之后每次调用带 mcp-session-id；支持 JSON 与 text/event-stream 响应；服务端返回 404 时重建会话。
- 工具注册：tools/list 返回什么就注册什么，公开名带 mcp__undermind__ 前缀。
未授权时不注册任何工具；换账号或换 client id 会整体替换上一代工具。
- 常驻 undermind_auth 工具：status / login / logout / refresh / retry，模型可以在对话里直接修复连接。
- Host HTTP 接口：/dsh-undermind/api/，用于浏览器侧授权与排查。

前置条件

1. 一个 Undermind 账号。每家用户用自己的账号授权，没有 API key / 服务账号模式。
2. 一个 client id。Undermind 不支持动态客户端注册（DCR），只接受：

- CIMD：一个 HTTPS URL，指向 Client ID Metadata Document（JSON），Undermind 会去拉取它；或
- 预注册 client id：发邮件到 support@undermind.ai 申请。

CIMD 是自助路径。把下面这份 JSON 托管到任意你控制的 HTTPS 地址，再把该地址填进 clientId：

{
"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 需要一个会带 JSON 类型的镜像（gist.githack.com 的 raw 地址可以）；GitHub Pages 直接可用。client_id 必须与 URL 逐字一致，redirect_uris 必须包含插件的 redirectUri——以后挪动文档位置时，两者要一起改。

GET /dsh-undermind/api/client-metadata 会打印带上当前 redirectUri 的模板。

安装

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

把 web 换成你的 profile 名。本包是纯 ESM、无构建步骤，并把 @deepseek-ai/cordis / @deepseek-ai/schemastery 声明为 peer 依赖，与宿主共用同一份，不额外打包。

Desktop 客户端持有的 profile 特殊：desktop 这个名字由 Electron 保留，dsh plugin CLI 会拒绝它。这种情况下从插件市场安装，或把包放进 profiles/desktop/node_modules 并把 dsh-plugin-undermind 加进 dsh.profile.bundles。

不要再为这个 server 添加 @deepseek-ai/dsh-mcp-client：它无法续期令牌，而且它的工具名会与本插件重名。

配置项

每个字段都是活引用，设置页保存后下一次调用即生效，不用重启。

| 字段 | 默认值 | 说明 |
| clientId | 空 | 必填。CIMD 的 HTTPS URL 或预注册 client id。 |
| mcpUrl | https://mcp.undermind.ai/mcp | MCP 端点，同时作为 OAuth resource。 |
| scope | mcp | 申请的范围。 |
| redirectUri | http://127.0.0.1:8799/callback | 回环回调地址，必须在 client 文档里登记。 |
| authorizeEndpoint | https://api.undermind.ai/o/authorize/ | 授权端点。 |
| tokenEndpoint | https://api.undermind.ai/o/token/ | 令牌端点。 |
| revocationEndpoint | https://api.undermind.ai/o/revoke_token/ | 撤销端点，登出时调用。 |
| tokenFile | 空 | 空表示 $DSH_HOME/storages/undermind-mcp-auth.json。 |
| requestTimeoutMs | 30000 | 单次 MCP 请求超时。 |
| toolTimeoutMs | 180000 | 单次工具调用超时；深度检索与 PDF 精读都很慢。 |
| loginTimeoutMs | 600000 | 等待浏览器授权的上限。 |
| toolPrefix | mcp__undermind__ | 注册到 dsh 的工具名前缀。 |
| disabledTools | [] | 要隐藏的 Undermind 原始工具名，例如 ["write_file"]。 |

使用

第一次授权

对模型说「把 Undermind 连上」，或直接调用：

undermind_auth action="login"

插件会在 redirectUri 的端口上启动一次性回调服务，用 state 与 PKCE 拼出授权 URL， 在系统默认浏览器里打开。你同意后浏览器跳到 127.0.0.1:8799/callback，插件用授权码换令牌、落盘，然后拉取并注册全部工具。mcp__undermind__ 对模型立即可见； undermind_auth action="status" 会给出 toolCount 与已注册的工具名。

日常使用

- 「查一下 2024 年以来镁离子电池电解液的进展」→ launch_deep_search（异步深度检索，跑几分钟，用 inspect_deep_searches 轮询）。
- 「找和这段摘要相似的论文」→ search_papers。
- 「读这几篇 PDF，说说它们用了什么方法」→ read_pdfs（每篇一个子代理读全文，含图表）。
- 「把这些论文归到一个新文件夹」→ create_folder / add_papers_to_folder。

display_deep_search_results、display_references、suggest_pdf_uploads 这三个在支持 MCP Apps 的 agent 里是交互卡片；在 dsh 里只返回文本和链接。

排查

| 现象 | 处理 |
| missing_client_id | 填 clientId，见上面的 CIMD 文档模板。 |
| 授权后仍无工具 | undermind_auth action="retry"，再看 lastError。 |
| port_in_use | 8799 被占用：释放它，或把 redirectUri 与 client 文档一起改。 |
| 401 / not_authorized | 授权被撤销或已过刷新期：undermind_auth action="login"。 |
| 换了 clientId | 旧 client 的令牌不会被复用，需要重新授权。 |

HTTP 接口

只接受回环来源：Host 必须是 localhost / 127.0.0.1 / [::1]，带
sec-fetch-site: cross-site 的请求一律拒绝。

| 路由 | 作用 |
| GET /dsh-undermind/api/status | 授权状态、令牌剩余时间、工具数、最近错误。 |
| GET\|POST /dsh-undermind/api/tools | 重新拉取并注册工具。 |
| POST /dsh-undermind/api/login | 发起授权，返回 authorizeUrl。 |
| POST /dsh-undermind/api/logout | 撤销并删除本地令牌。 |
| GET /dsh-undermind/api/client-metadata | 带当前 redirectUri 的 CIMD 模板。 |

统一信封：成功 {"ok":true,"data":…}，失败 {"ok":false,"error":{"code","message"}}。

安全与隐私

- 令牌不出本机：写在 $DSH_HOME/storages/ 下，0600 权限、原子替换。
- 令牌只会发往 api.undermind.ai 与 mcp.undermind.ai。
- 回调服务只监听回环地址，只接受一次授权码，用完立即关闭。
- 你随时可以在 Undermind 账号设置里撤销该连接。

目录结构

lib/index.js 插件入口：Config、apply、登录编排、auth 工具、路由挂载 lib/settings.js 运行期设置（volatile 读取器） lib/store.js 令牌文件读写（原子 + 0600） lib/auth.js TokenManager：续期、轮换、撤销、状态 lib/oauth.js PKCE、授权 URL、授权码交换、回调服务、开浏览器 lib/mcp.js MCP Streamable HTTP 客户端（initialize/会话/SSE/401 自愈） lib/bridge.js MCP 工具 → dsh 工具注册（分代替换、schema 降级） lib/router.js /dsh-undermind/api/* 路由与 CIMD 模板