@vfvrpq/dsh-search

DeepSeek 官方 Search / Fetch 接口的 DeepSeek Harness 插件：三个工具、一个配置项、零运行时依赖。

给 agent 的是结构化网页结果——rerank 分、权威度、发布时间、模型友好长摘要——而不是一坨 HTML。 比内置 web_search / web_fetch 多出来的东西：搜索语法、条数与正文可控、成本可推算。

装

# 从 npm（已发布版本）
dsh plugin --profile desktop add @vfvrpq/dsh-search@0.1.0

# 或从源码包（插件 import 了 @deepseek-ai/*，必须走 tgz，目录软链会让宿主包解析不到）
pnpm pack
dsh plugin --profile desktop add /绝对路径/vfvrpq-dsh-search-0.1.0.tgz

装完工具即出现在工具表里，不用重启（升级才需要重启）。

三个工具

工具	干什么	计费请求数
deepseek_search	搜索，返回标题/URL/snippet/summary/可选正文/日期/权威度/rerank 分	1
deepseek_fetch	单页转 Markdown（标题 + 正文）	1
deepseek_research	搜索 + 抓前 N 页正文，一次给结论	1 + N

deepseek_search 支持的操作符，写在 query 里或用参数：site:、-site:、-词、-"短语"、"精确"、lang:、after:、before:。

deepseek_search  query="llama.cpp 安装" site="github.com" after=2025 count=5
deepseek_fetch   url="https://api-docs.deepseek.com/zh-cn/guides/search"
deepseek_research query="DeepSeek V4 上下文长度" count=5 top=2

判读口径：rerankScore >= 1.5 为优质（渲染里标 ★），authority >= 3 为高权威。 summary 是二手摘要，版本号/日期/价格/API 字段一律 deepseek_fetch 原文核实；引用给原始 URL。

配置

键	默认	说明
apiKey	""	空则运行时按下面四层解析，不要把 key 写进 profile
baseUrl	https://api.deepseek.com	仅兼容代理时才改
defaultCount	5	调用没给 count 时的条数
maxContentChars	8000	deepseek_search 每条正文上限
fetchMaxChars	20000	deepseek_fetch 正文上限
timeoutMs	30000	单请求超时
maxRetries	2	408 / 429 / 5xx 重试次数
promptEnabled	true	是否向系统提示贡献用法章节
promptOrder	55	该章节排序

key 解析顺序（key 不落 profile）：

1. 插件配置 apiKey
2. $DEEPSEEK_API_KEY
3. ~/.secrets/keys.env 里的 DEEPSEEK_API_KEY=...
4. $DSH_HOME/.credentials.yaml 的 refs: DEEPSEEK_API_KEY: sk-...

成本

• 5 元 / 1000 次成功请求 ≈ 0.005 元 / 次；Search 与 Fetch 同价。
• 只有 HTTP 200 且产生结果才计费；空结果、失败、超时不计费。
• count 不影响单价——一次取够，别拆成多次小请求。
• 限速：Search 与 Fetch 各自 5 QPS（账号级）；超过抛 429，插件按退避重试。

结构

lib/index.js     入口：只接线（校验配置、持有 client、注册工具、贡献提示章节）
lib/config.js    Config schema + 代码侧默认值 + 加载期校验
lib/keys.js      四层 key 解析
lib/query.js     query 拼装与 site: 展开
lib/client.js    HTTP：超时 / 重试 / 错误翻译
lib/format.js    结果归一化与渲染
lib/prompt.js    系统提示章节
lib/tools/       一能力一文件（search / fetch / research / shared）

开发

node --test test/*.test.js     # 单测：mock fetch，不联网、不花钱
node scripts/live-selftest.js  # 真机自测：1 次搜索 + 1 次抓取（约 0.01 元）

已知边界

• 抓不了需要登录态、点击交互、或返回非 HTML 的页面 → 用浏览器自动化插件。
• SPA 文档站可能对不存在的路径返回 200 + 站点壳内容而不是 404；正文里出现首页标语即说明是 fallback。
• Fetch 返回的 Markdown 会把 \/、\.、\# 等标点反斜杠转义，属上游产物，按需 unescape。

License

MIT