dsh-web-search

同时兼容 DSH 与 Pi 的网页搜索 / 网页抓取插件，一个仓库、一份内核、两套宿主适配。

能力	DSH	Pi
搜索	向 ctx.web 注册提供方 free-first	注册模型工具 web_search
抓取	向 ctx.web 注册提供方 local-first	注册模型工具 web_fetch
密钥菜单	—（配置来自 Cordis 配置）	/web-search-auth 命令

匿名顺序为 Exa → Tavily → Parallel → Firecrawl → TinyFish（keyless）；计费顺序为 Exa → Tavily → Parallel → Firecrawl → SerpApi。默认禁止计费，只有显式授权且在匿名通道全部失败后才会尝试密钥通道。TinyFish 只有零凭据匿名通道。

结构

src/
├── search/     # 搜索内核：路由、协议、MCP 解析、脱敏、正文落盘
├── quota/      # 额度预检、冷却状态、私有持久化
├── auth/       # 凭据解析与系统密钥库（macOS Keychain / Linux secret-tool）
├── fetch/      # 抓取内核：SSRF 校验、有界响应、HTML→Markdown
├── shared/     # 两个内核共用的有界响应体读取
└── hosts/
    ├── dsh.ts      # Cordis 插件：注册搜索与抓取提供方
    ├── pi.ts       # Pi：web_search 工具 + /web-search-auth
    └── pi-fetch.ts # Pi：web_fetch 工具

内核不 import 任何宿主 API，因此两个宿主共用同一套路由、额度、冷却与脱敏行为，也可以离线测试。

安装

DSH

dsh plugin --profile <profile> add link:<server_path>/dsh-web-search

cordis.patch.yml 会同时启用 free-first（搜索）与 local-first（抓取）。抓取提供方使用独立 id，因为官方插件已占用 http；若你已有自定义 fetchProvider，请保留你的选择。

Pi

pi install <server_path>/dsh-web-search

或在 settings.json 中按目录启用：

{
  "packages": [
    { "source": "git:github.com/Luca4Don3/dsh-web-search", "extensions": ["pi.ts"] }
  ]
}

从旧版 pi-extensions/extensions/web-search 迁移

旧版扩展同样注册 web_search，两者同时启用会工具重名冲突。迁移步骤：

# 1. 确认旧版位置（Pi 会自动加载该目录下的扩展）
ls ~/.pi/agent/extensions/web-search

# 2. 移走旧版（保留备份便于回滚；不要直接删除）
#    必须移出 ~/.pi/agent/extensions/ —— Pi 会加载该目录下的每个子目录，
#    改名成 web-search.bak 仍在自动发现范围内，重名冲突不会解除。
mv ~/.pi/agent/extensions/web-search ~/.pi/agent/web-search.bak

# 3. 安装新版
pi install <server_path>/dsh-web-search

# 4. 重启 Pi，确认只注册一份 web_search

若此前用 pi install 装过旧版，改用 pi remove ~/pi-extensions/extensions/web-search 卸载。 /web-search-auth 命令名保持不变，密钥配置与冷却状态无需迁移。

回滚：mv ~/.pi/agent/web-search.bak ~/.pi/agent/extensions/web-search。

备份目录只要仍在 ~/.pi/agent/extensions/ 之下就会被继续加载； 放到该目录的同级位置（如 ~/.pi/agent/）才能真正停用。

如果此前已按旧版说明放在 ~/.pi/agent/extensions/web-search.bak， 请补一步：mv ~/.pi/agent/extensions/web-search.bak ~/.pi/agent/web-search.bak。

安装后可用 /web-search-auth 管理密钥。环境变量优先于系统密钥库。

配置

DSH（Cordis 配置）

字段	默认值	含义
allowBillable	false	显式授权可能计费的通道
timeoutMs	25000	单请求预算，毫秒
totalTimeoutMs	90000	整次调用总预算，毫秒
maxResponseBytes	5242880	解压后响应体上限
maxChars	24000	模型可见正文字符预算
retries	1	网络或服务端错误重试次数
cooldownOverrideMs	未设置	冷却覆盖，0 禁用冷却
stateDirectory	$DSH_HOME/config/web-search	冷却状态目录
fetchTimeoutMs	20000	抓取总预算，毫秒
fetchMaxResponseBytes	5242880	抓取解压后响应体上限
fetchMaxChars	24000	抓取正文上限
fetchMaxRedirects	3	最大跳转次数

Pi（环境变量）

字段	默认值	含义
PI_WEB_SEARCH_ALLOW_BILLABLE	false	同 allowBillable，只接受 true / false
PI_WEB_SEARCH_ALLOW_PAID	未设置	旧开关别名，与上一项冲突时报错
PI_WEB_SEARCH_TIMEOUT_MS	25000	单请求预算
PI_WEB_SEARCH_TOTAL_TIMEOUT_MS	90000	整次调用预算
PI_WEB_SEARCH_MAX_RESPONSE_BYTES	5242880	响应体上限
PI_WEB_SEARCH_RETRIES	1	重试次数，0..3
PI_WEB_SEARCH_FREE_COOLDOWN_MS	未设置	固定冷却覆盖
PI_WEB_FETCH_TIMEOUT_MS	20000	抓取总预算
PI_WEB_FETCH_MAX_RESPONSE_BYTES	5242880	抓取响应体上限
PI_WEB_FETCH_MAX_CHARS	24000	抓取正文上限
PI_WEB_FETCH_MAX_REDIRECTS	3	最大跳转次数
PI_WEB_FETCH_REMOTE_FALLBACK	off	远程回退；当前只接受 off，设为 jina 会在任何请求前明确报错

密钥：EXA_API_KEY、TAVILY_API_KEY、PARALLEL_API_KEY、FIRECRAWL_API_KEY、SERPAPI_API_KEY。TinyFish 始终 keyless，不读取 TINYFISH_API_KEY。

安全与限制

• 未授权计费时不读取任何服务商密钥、凭据库或额度接口。
• 授权后一次性解析全部所需密钥，并在正文、来源、details 与落盘内容中统一脱敏。
• 只能通过环境变量或系统密钥库注入密钥；不提供明文文件回退。
• 响应体按解压后字节计数上限，超限立即中止请求，不返回部分结果。
• 冷却状态只保存 HMAC 作用域与冷却元数据，目录 0700、文件 0600。
• 额度预检只回答「当前是否付得起」，不能证明账户免费，也不提供跨进程账单硬上限。
• 抓取拒绝私有段、回环、链路本地与云元数据地址，不执行网页脚本，不携带 Cookie。
• 两个宿主的单元测试全部离线；这不等于真实桌面安装、真实密钥库写入或服务商网络验收。

开发验证

npm ci --ignore-scripts --no-audit --no-fund
npm run check          # 严格类型检查
npm test               # DSH 兼容层 + Pi + 抓取全部离线用例
npm run check:artifacts
npm pack --dry-run

Pi 用例通过 jiti 直接加载 src/ 下的源码，因此需要本机装有 Pi（提供 jiti 与 typebox）。CI 会先安装 @earendil-works/pi-coding-agent 再运行。

npm run smoke 是手动匿名网络检查，不进入持续集成，不使用密钥或计费通道。

License

MIT