dsh-plugin-deepseek-search
作为 DeepSeek Harness (DSH) 中的 deepseek_search 和 deepseek_fetch 工具提供官方 DeepSeek 搜索和获取 API。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:lxyztmds/dsh-plugin-deepseek-search#2e568716920e8a9f95b3ea490d895c108324b569Plugin Deepseek Search 以 dsh-plugin-deepseek-search 发布，当前版本为 0.1.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
点击下方 Badge 复制 Markdown，粘贴到 README 即可。
验证 package.json 声明的 GitHub 仓库，即可管理这个公开页面。认领后，Hub 会优先安排当前版本的安全扫描，并在通过后公开展示结果。
认领这个 Plugin →把 DeepSeek 官方 Search / Fetch API 接入 DeepSeek Harness（DSH）的插件。安装后模型获得两个工具：
| 工具 | 底层接口 | 作用 |
|---|---|---|
deepseek_search | POST https://api.deepseek.com/v1/tools/search | 用 DeepSeek 自研搜索引擎检索网页，返回标题、URL、摘要、发布时间、权威性、排序分；可选返回网页正文 |
deepseek_fetch | POST https://api.deepseek.com/v1/tools/fetch | 抓取单个网页，返回标题与 Markdown 正文 |
接口文档：https://api-docs.deepseek.com/zh-cn/guides/search/
web_search / web_fetch 互不冲突：本插件注册独立工具名，不接管 ctx.web 的 provider 选择，也不改动内置设置。DEEPSEEK_API_KEY），每次调用实时解析，换 Key 不需要重启；显式配置 apiKey 字面值时会优先使用它。dsh-plugin-deepseek-search/
├── package.json # 包清单：dsh.bundle.patch 声明 + peerDependencies
├── cordis.patch.yml # bundle patch 层：插入插件行 deepseek-search
├── lib/
│ ├── index.js # 插件入口：Config schema、apply、两个 defineTool 定义
│ ├── client.js # Search/Fetch HTTP 客户端：鉴权、超时、重试、错误映射、响应校验
│ └── format.js # 模型侧渲染 + Web 结果卡片（presentationMeta / presentResult）
├── locale/{zh,en}.json # 插件列表里的标题与描述
├── scripts/
│ └── install-bundle-entry.mjs # 手工安装辅助：安全地把 bundle 名写进 profile 清单
├── test/
│ ├── client.test.mjs # 单元测试：请求/重试/错误/校验（25 个用例）
│ ├── format.test.mjs # 单元测试：渲染、截断、presentation（15 个用例）
│ └── live-smoke.mjs # 真实 API 冒烟测试（需要 Key）
├── icon.svg
└── LICENSE
DSH 的插件是 profile 的一个 bundle：profile 的 package.json 的 dsh.profile.bundles 引入它，它的 cordis.patch.yml 把插件行插进加载树。
最省事的方式：装好后在 插件 → 发现 里搜索本插件，或在命令行执行（非 desktop profile）：
# GitHub 源码安装
dsh plugin --profile <profile-name> add github:lxyztmds/dsh-plugin-deepseek-search
# npm 安装（发布 npm 后可用；预构建、免 allowBuilds 授权）
dsh plugin --profile <profile-name> add dsh-plugin-deepseek-search
下面是本地/手工安装的三种方式。
C:\Users\Administrator\Desktop\开发相关\dsh-plugin-deepseek-search；dsh plugin --profile <profile-name> add "file:C:\path\to\dsh-plugin-deepseek-search"
# 然后重启该 profile
desktop 这个 profile 名被 Electron 独占：独立 dsh CLI 会拒绝，请用方式一或方式三；Desktop 自带的 dsh 命令可管理该 profile（例如 dsh plugin --profile desktop why <pkg>），但跨版本行为不一致，手工路径最稳。
# 1) 拷一份到 ASCII 路径（避免中文路径在 pnpm/命令行链路上被错误转码）
robocopy "<插件源码目录>" "C:\Users\Administrator\.dsh\plugins-local\dsh-plugin-deepseek-search" /E /XD node_modules .git
# 2) 在 profile 目录安装依赖
pnpm --dir "C:\Users\Administrator\.dsh\profiles\desktop" add "file:C:\Users\Administrator\.dsh\plugins-local\dsh-plugin-deepseek-search"
# 3) 把 bundle 名追加进 dsh.profile.bundles（node 脚本，避免手工改 JSON 出错）
node "<插件目录>\scripts\install-bundle-entry.mjs" "C:\Users\Administrator\.dsh\profiles\desktop\package.json"
1、2 步也可用一条 dsh plugin --profile <name> add <path> 交给 CLI（仅限非 Electron 托管的 profile；独立 CLI 会拒绝 desktop），CLI 成功后第 3 步的 bundles 追加会自动完成。
手工改过 profile 后一般需要重启 DSH Desktop 才会生效；若该 DSH 版本运行在 HMR 模式，运行时也可能检测到 profile 变化并热加载（本机安装时即自动生效）。
配置项定义在 lib/index.js 的 Config（schemastery schema），默认值由 schema 提供（bundle patch 只显式写了 apiKeyEnv），可在 profile 的 cordis.patch.yml 用 id 定向覆盖：
- id: deepseek-search
config:
apiKeyEnv: DEEPSEEK_API_KEY
count: 5
needContent: false
timeoutMs: 60000
retries: 2
maxOutputChars: 60000
| 字段 | 默认值 | 含义 |
|---|---|---|
apiKey | 空 | 直接写入的 API Key（secret role；不推荐，优先用凭据引用） |
apiKeyEnv | DEEPSEEK_API_KEY | 凭据引用名，按调用经 ctx.credentials 解析；没有凭据服务时回退到启动进程的环境变量 |
baseURL | https://api.deepseek.com/v1/tools | Search/Fetch API 基础地址（含 /v1/tools，不含 /search、/fetch）；必须是带 host 的 http(s) URL，且不能包含用户名/密码，非 https 会明文传输 Key |
count | 10 | deepseek_search 未显式传 count 时的默认条数（1–50） |
needContent | false | deepseek_search 未显式传 need_content 时的默认值 |
timeoutMs | 60000 | 一次工具调用的总预算（含重试退避），到点返回 TIMEOUT |
retries | 2 | 遇到 408 / 429 / 5xx / 网络错误时的重试次数（0–5），429 会优先遵守 Retry-After |
maxOutputChars | 60000 | 单次调用返回给模型的最大字符数；超出会截断并注明 |
sendOriginalQuestion | true | 把触发本轮的用户问题（折叠空白、截断 128 字符）作为 ori_question 发送 |
apiKey 字面值（若配置）；ctx.credentials.resolve(apiKeyEnv)：Desktop/Web 的凭据服务会读 ~/.dsh/.credentials.yaml 的 refs:，或 Web 模型页保存的 Key；process.env[apiKeyEnv]（例如 dsh 前 set DEEPSEEK_API_KEY=sk-...）。三处都没有时，工具仍会显示在工具列表里，执行时返回带修复指引的 MISSING_CREDENTIAL 错误。
deepseek_search| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
query | string | 是 | 1–128 个 Unicode 字符，不能全为空白；支持搜索语法（见下） |
count | integer | 否 | 1–50，缺省用部署配置；越界会返回参数错误 |
need_content | boolean | 否 | 是否同时返回网页正文（更大、更慢） |
query 支持的搜索语法（原样传给搜索服务）：
| 操作符 | 示例 |
|---|---|
site: | DeepSeek site:github.com OR site:huggingface.co |
-site: | DeepSeek -site:example.com |
- / -"..." | DeepSeek -广告、DeepSeek -"release notes" |
"..." | DeepSeek "精确短语" |
lang: | DeepSeek lang:zh,en |
after: / before: | DeepSeek after:2025-01-01 before:2026-06-01 |
结果包含 title、url、snippet、summary、date、authority（0–4，-1 未知）、rerankScore（0–3，≥1.5 为优质），need_content 时还有 content。
deepseek_fetch| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 是 | 绝对 http(s) URL，≤8192 字符，必须带 host，不能携带用户名/密码 |
返回 { url, title, content }：title 被限制在 300 字符（防止畸形 <title> 冲爆输出），content 为 Markdown 正文，插件对单页保留上限为 200,000 字符（MAX_FETCH_CONTENT_CHARS），超出会截断并标注。
插件把文档里的状态码映射成模型可执行的错误文本，并附带 endpoint 与排查建议：
| 状态码 | 行为 |
|---|---|
| 400 | 不重试，提示 query/count/JSON 约束 |
| 401 | 不重试，提示配置 Key 的三种途径 |
| 402 | 不重试，提示充值 |
| 403 / 404 | 不重试（Fetch 被安全策略拒绝 / 页面无可提取正文） |
| 408 / 429 | 按 Retry-After 或指数退避重试，超过次数后报错 |
| 413 | 不重试，提示请求体超过 API 大小限制 |
| 任意 5xx（500/502/503/504/501/505…） | 按 Retry-After 或指数退避重试，超过次数后报错；502/503 有专门的排障提示 |
| 网络失败 | 重试后报错，提示检查网络与 baseURL |
本地错误码会以 [CODE] 前缀出现在错误文本里，便于模型和日志路由：MISSING_CREDENTIAL（未配置 Key）、ABORTED（用户取消）、TIMEOUT（总预算耗尽）、INVALID_RESPONSE（返回体不符合文档结构）、INVALID_BASE_URL（baseURL 不合法）。
Search 与 Fetch 都是只读请求，重试安全。
按 DeepSeek 文档：
count 不影响单次价格。本插件是显式工具调用，属于按次计费路径，请按需控制 count 与调用频率。
Authorization: Bearer <key> 发给配置的 baseURL；Key 不写入消息、日志或模型上下文，上游错误体里若回显了 Key 会被替换为 [redacted]。baseURL 必须是有 host 的 http(s) URL，且拒绝携带用户名/密码的 URL；非 https 地址会明文发送 Key，只应指向信任的本地网关。query、url 会发给 DeepSeek API；sendOriginalQuestion 开启时还会发送本轮用户问题的前 128 字符，关闭它即可不发送。[/] 会被转义，避免伪造 Markdown 链接。redirect: 'error'），避免凭据被带到别的地址。# 单元测试（不联网；40 个用例：25 client + 15 format）
node --test test/client.test.mjs test/format.test.mjs
# 真实 API 冒烟测试（读取 DEEPSEEK_API_KEY 或 ~/.dsh/.credentials.yaml）
node test/live-smoke.mjs
实现要点：
lib/client.js 不依赖 DSH 运行时，可独立测试；createDeepSeekApi 通过 fetchImpl / sleep(ms, signal, operation) 注入网络与时钟。timeoutMs 总预算（AbortSignal.timeout），等待期间也会响应取消/超时；取消使用调用方 exec.signal，两者用 AbortSignal.any 合并。deepseek_search / deepseek_fetch 都声明了 isConcurrencySafe: () => true（只读，可并行），并声明 timeoutMs 供 DSH 的超时策略做兜底。presentResult 的 truncated 与渲染文本共用同一次计算。presentationMeta 把结构化来源/抓取摘要持久化（字段亦有长度上限），presentResult 让 Web 客户端渲染成 web 结果卡片，且对错误结果返回 undefined。MISSING_CREDENTIAL/TIMEOUT/…）会以 [CODE] 前缀进入错误文本，模型和日志可以直接路由。dsh.profile.bundles 删掉 dsh-plugin-deepseek-search，再 pnpm --dir <profile> remove dsh-plugin-deepseek-search，重启。MIT