pi-deepseek-web-search

一个 pi 扩展：为 pi 会话中的任意模型提供 DeepSeek 联网搜索 能力，桥接 DeepSeek /responses API 的服务端搜索。

English

功能特性

• 强制搜索——每次调用都真实执行搜索（tool_choice: { type: "web_search" }），模型无法跳过
• 综合回答 + 引用——由 DeepSeek 生成带引用的回答，同时返回执行的搜索动作记录
• 配置灵活——环境变量 / 项目配置文件 / 全局配置文件（优先级从高到低）
• TTL 结果缓存——TTL 内相同查询直接命中缓存，零成本
• 真实成本上报——token 单价可配置（美元/百万 tokens），默认启用官方峰谷定价；工具上报的 Usage.cost 为真实估算金额
• 模型可选——通过配置使用 deepseek-v4-flash（默认）、deepseek-v4-pro 或其他 Responses API 模型名
• 生成式 JSON Schema——配置文件定义单一来源（src/config-schema.ts），中/英两份 Schema 由它自动生成（见 Schema）

安装

已通过 OIDC Trusted Publishing 发布到 npm（带 SLSA provenance 证明）。在任意 pi 项目中：

pi install npm:pi-deepseek-web-search

然后在 pi 会话中执行 /reload。

本地开发本包时：pi install .，或将 src/index.ts 软链/复制到项目的 .pi/extensions/。

配置

配置按以下优先级读取（后者覆盖前者）：

1. 环境变量
2. 项目配置文件：.pi/deepseek-web-search.json
3. 全局配置文件：~/.pi/agent/deepseek-web-search.json

配置会在扩展进程内按工作目录缓存；修改配置文件或环境变量后，请重启 pi（或运行 /deepseek-search status 强制刷新）再继续搜索。如果这里未配置 API key，工具会回退使用 pi 中已经配置的 DeepSeek provider key。

示例（~/.pi/agent/deepseek-web-search.json）

{
  "$schema": "./npm/node_modules/pi-deepseek-web-search/schema/deepseek-web-search.config.schema.zh.json",
  "apiKey": "sk-...",
  "model": "deepseek-v4-flash",
  "reasoningEffort": "high",
  "prices": {
    "inputPerMillion": 0.22,
    "cachedInputPerMillion": 0.007,
    "outputPerMillion": 0.66
  }
}

$schema 仅供编辑器自动补全/校验，运行时忽略。上述路径适用于包安装在项目 node_modules（相对 .pi/ 目录）的场景；其他安装位置请自行调整。注释想要中文用 .zh.json，英文用 .en.json。

配置字段

字段	类型	默认值	说明
apiKey	string	—	DeepSeek API key（必填）。DEEPSEEK_API_KEY 可覆盖
baseUrl	string	https://api.deepseek.com	API 基础地址（自建代理时修改）
model	string	deepseek-v4-flash	自由字符串模型名。DEEPSEEK_MODEL 可覆盖
reasoningEffort	off/low/high/max	high	项目默认 high；未传 effort 时 DeepSeek 默认启用思考
maxOutputTokens	int 1–384000	4096	回答最大输出 token 数（官方上限 384K）
timeoutMs	int ≥ 1	30000	单次请求超时（毫秒）
cacheTtlMs	int ≥ 1	300000	结果缓存 TTL（毫秒）
maxResultChars	int ≥ 1	50000	返回给模型的回答最大字符数
prices.inputPerMillion	number > 0	0.22	输入单价，缓存未命中，空闲价（美元/百万 tokens）
prices.cachedInputPerMillion	number > 0	0.007	输入单价，缓存命中，空闲价（美元/百万 tokens）
prices.outputPerMillion	number > 0	0.66	输出单价，空闲价（美元/百万 tokens）
prices.peak	object	官方高峰时段	峰谷定价覆盖（默认遵循官方工作日/周末规则，见下）
prices.models	object	—	按模型覆盖的价格表（key = 模型名）

对应环境变量：DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL、DEEPSEEK_MODEL、DEEPSEEK_REASONING_EFFORT、DEEPSEEK_MAX_OUTPUT_TOKENS、DEEPSEEK_TIMEOUT_MS、DEEPSEEK_CACHE_TTL_MS、DEEPSEEK_MAX_RESULT_CHARS、DEEPSEEK_PRICE_INPUT、DEEPSEEK_PRICE_CACHED_INPUT、DEEPSEEK_PRICE_OUTPUT。

数字类环境变量只接受规范十进制字符串，例如 30000 或 1.5；+1、.5、1e3、30_000、30s 等形式会被拒绝。价格类环境变量按美元/百万 tokens 解释。

价格与峰谷

北京时间 2026-08-17 00:00 起，DeepSeek 采用峰谷计价。默认值遵循官方定价页：

模型	时段	输入（缓存未命中）	输入（缓存命中）	输出
deepseek-v4-flash	空闲	$0.22	$0.007	$0.66
deepseek-v4-flash	高峰	$0.44	$0.014	$1.32
deepseek-v4-pro	空闲	$0.66	$0.022	$1.98
deepseek-v4-pro	高峰	$1.32	$0.044	$3.96

单位均为美元/百万 tokens。工作日高峰时段为北京时间 9:00–12:00 与 14:00–18:00，高峰价格 = 空闲价 × 2。北京时间 2026-08-23 00:00 起，周六、周日全天按平峰计价。官方峰谷规则默认启用；只有需要覆盖时才配置 prices.peak：

"prices": {
  "peak": {
    "multiplier": 2,
    "hours": [["09:00", "12:00"], ["14:00", "18:00"]],   // 半开区间 [start, end)
    "weekendOffPeak": true
  }
}

• pro 的上述价格已预置在 prices.models."deepseek-v4-pro"，model 切换后自动生效
• weekendOffPeak 默认为 true；自定义价格表需要保留周末高峰时才设置为 false
• 工具上报的 Usage.cost 为按配置单价和请求发起时间估算的金额；缓存命中不产生成本（无真实调用），details.usage 仍保留首次搜索的原始用量记录供查看

模型支持

deepseek-v4-flash 与 deepseek-v4-pro 均支持 Responses API。DeepSeek 还列出了实验性 vision 模型 deepseek-v4-flash-vision-exp；model 字段刻意保持自由字符串，因此无需更新 Schema 即可选择。本插件只发送文本查询，不支持图片输入。

两个主模型别名当前分别指向 DeepSeek-V4-Flash-0731 与 DeepSeek-V4-Pro-0813，调用名不变；默认使用 deepseek-v4-flash。pro 价格经 prices.models 自动联动；vision 模型的官方价格与 flash 相同，因此直接使用现有顶层价格回退，无需单独覆盖。

使用

向模型提出时效性或外部信息问题，它会自动调用 deepseek_web_search：

今天北京的天气怎么样？

工具返回 DeepSeek 的综合回答（含引用）与搜索动作记录。结果按工作目录、baseUrl 与 model:mode:query 缓存 cacheTtlMs。

/deepseek-search 命令可查看配置状态（key 是否配置、模型、缓存条目数）并清空缓存。

Schema

配置文件定义只在 src/config-schema.ts（TypeBox）维护一次，其余全部派生：

• ConfigFileShape 类型（Static<>）
• 运行时校验（Check/Errors）
• 两份生成式 JSON Schema：
  • schema/deepseek-web-search.config.schema.en.json（英文注释）
  • schema/deepseek-web-search.config.schema.zh.json（中文注释）

修改定义后重新生成：

pnpm gen:schema

生成文件随仓库提交，并有测试断言其与定义保持同步（防漂移）。

开发

pnpm check     # tsc --noEmit
pnpm lint      # eslint
pnpm test      # vitest
pnpm gen:schema

FAQ

• 为什么不用内置的 web search 工具？ 当你希望搜索由 DeepSeek API 支撑（例如复用已有 DeepSeek 账号/余额，或会话模型没有内置搜索）时，本工具更有用。
• 会返回来源列表吗？ DeepSeek 搜索在服务端执行，回答内含行内引用；工具同时把执行的搜索动作（searched:/opened: 行）记录在返回内容中。
• 费用怎么算？ DeepSeek 按 token 计费；工具按你配置的单价估算并上报 Usage.cost。参见官方定价页。
• 报错 "API key is not configured"？ 设置 DEEPSEEK_API_KEY 或在配置文件中填 apiKey。