pi-deepseek-web-search 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zzwtsy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# pi-deepseek-web-search
+
+A [pi](https://github.com/earendil-works/pi) extension that gives any model in your pi sessions a **DeepSeek-backed web search** tool, bridging the DeepSeek `/responses` API server-side web search.
+
+[中文说明](README.zh.md)
+
+## Features
+
+- **Forced search** — every call executes a real web search (`tool_choice: { type: "web_search" }`); the model cannot skip it
+- **Synthesized answer with citations** returned by DeepSeek, plus a record of the executed search actions
+- **Configurable** via env vars, project config file, or global config file (in that order of precedence)
+- **TTL result cache** — repeated identical queries within the TTL hit the cache and cost nothing
+- **Real cost reporting** — token prices are configurable (CNY per million tokens) with future peak-hour pricing support, and the reported `Usage.cost` reflects the actual estimated spend
+- **Model selectable** — `deepseek-v4-flash` (default) now; switch to `deepseek-v4-pro` by config once it supports the Responses API
+- **Generated JSON Schema** — the config file definition is a single source of truth (`src/config-schema.ts`); English and Chinese schemas are generated from it (see [Schema](#schema))
+
+## Install
+
+From the project root of this package:
+
+```bash
+pi install .
+```
+
+Or symlink/copy `src/index.ts` into your project's `.pi/extensions/` and run `/reload` in the pi session.
+
+## Configuration
+
+Config is read from, in order of precedence (later sources override earlier ones):
+
+1. Environment variables
+2. Project config file: `.pi/deepseek-web-search.json`
+3. Global config file: `~/.pi/agent/deepseek-web-search.json`
+
+### Example (`.pi/deepseek-web-search.json`)
+
+```jsonc
+{
+  "$schema": "../schema/deepseek-web-search.config.schema.en.json",
+  "apiKey": "sk-...",
+  "model": "deepseek-v4-flash",
+  "reasoningEffort": "low",
+  "prices": {
+    "inputPerMillion": 1,
+    "cachedInputPerMillion": 0.02,
+    "outputPerMillion": 2
+  }
+}
+```
+
+> `$schema` is only used by editors for autocomplete/validation and is ignored at runtime. Use the `.en.json` schema for English comments, or the `.zh.json` one for Chinese.
+
+### Config fields
+
+| Field | Type | Default | Description |
+| ----- | ---- | ------- | ----------- |
+| `apiKey` | string | — | DeepSeek API key (required). `DEEPSEEK_API_KEY` overrides |
+| `baseUrl` | string | `https://api.deepseek.com` | API base URL (change when using a proxy) |
+| `model` | string | `deepseek-v4-flash` | Model name. `DEEPSEEK_MODEL` overrides |
+| `reasoningEffort` | `off`/`low`/`high`/`auto` | `low` | `off` disables thinking to save tokens |
+| `maxOutputTokens` | int ≥ 1 | `4096` | Max output tokens |
+| `timeoutMs` | int ≥ 1 | `30000` | Request timeout in ms |
+| `cacheTtlMs` | int ≥ 1 | `300000` | Result cache TTL in ms |
+| `maxResultChars` | int ≥ 1 | `50000` | Max chars of the answer returned to the model |
+| `prices.inputPerMillion` | number > 0 | `1` | Input price, cache miss (CNY / 1M tokens) |
+| `prices.cachedInputPerMillion` | number > 0 | `0.02` | Input price, cache hit |
+| `prices.outputPerMillion` | number > 0 | `2` | Output price |
+| `prices.peak` | object | — | Peak-hour pricing override (optional, see below) |
+| `prices.models` | object | — | Per-model price overrides keyed by model name |
+
+Environment variable equivalents: `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`.
+
+### Pricing and peak hours
+
+Default prices follow the [official DeepSeek pricing page](https://api-docs.deepseek.com/zh-cn/quick_start/pricing) (deepseek-v4-flash: 1 / 0.02 / 2 CNY per million tokens). Pricing is configurable, and a peak-hour override is already supported:
+
+```jsonc
+"prices": {
+  "peak": {
+    "multiplier": 2,
+    "hours": [["09:00", "12:00"], ["14:00", "18:00"]]   // half-open [start, end)
+  }
+}
+```
+
+- Peak hours follow the official definition: **daily, Beijing time** 09:00–12:00 and 14:00–18:00 (the pricing scheme is *pending* official rollout — omit `peak` until then)
+- Peak price = base × `multiplier`, applied to all billing items
+- Per-model overrides: `prices.models."deepseek-v4-pro" = { "inputPerMillion": 3, "cachedInputPerMillion": 0.025, "outputPerMillion": 6 }` — used automatically when `model` is set to that model
+- The `Usage.cost` reported by the tool reflects the computed estimate; cached hits report no cost (no API call happened)
+
+### Model support
+
+The Responses API currently supports only `deepseek-v4-flash`; `deepseek-v4-pro` support is expected in early August 2026. Set `"model": "deepseek-v4-pro"` (or `DEEPSEEK_MODEL`) once it is available — prices switch automatically via `prices.models`.
+
+## Usage
+
+Ask the model a time-sensitive or external question; it will invoke `deepseek_web_search` automatically:
+
+> What is the weather in Beijing today?
+
+The tool returns DeepSeek's synthesized answer with citations plus the executed search actions. Results are cached per `model:mode:query` for `cacheTtlMs`.
+
+The `/deepseek-search` command shows config status (key configured, model, cache size) and can clear the cache.
+
+## Schema
+
+The config file definition is maintained **once** in `src/config-schema.ts` (TypeBox) and everything else is derived:
+
+- `ConfigFileShape` type (via `Static<>`)
+- Runtime validation (via `Check`/`Errors`)
+- Two generated JSON Schema files:
+  - `schema/deepseek-web-search.config.schema.en.json` (English comments)
+  - `schema/deepseek-web-search.config.schema.zh.json` (Chinese comments)
+
+Regenerate after changing the definition:
+
+```bash
+pnpm gen:schema
+```
+
+Generated files are committed and a test asserts they stay in sync with the definition.
+
+## Development
+
+```bash
+pnpm check     # tsc --noEmit
+pnpm lint      # eslint
+pnpm test      # vitest
+pnpm gen:schema
+```
+
+## FAQ
+
+- **Why not the built-in web search tool?** This tool is useful when you want search backed by the DeepSeek API (e.g., to reuse an existing DeepSeek account/balance, or when the session model lacks a built-in search).
+- **Does it return a list of sources?** DeepSeek's search runs server-side; the answer contains inline citations, and the tool additionally records the executed search actions (`searched:`/`opened:` lines) in the returned content.
+- **How much does it cost?** DeepSeek charges per token; the tool reports an estimated `Usage.cost` based on your configured prices. See the [official pricing page](https://api-docs.deepseek.com/zh-cn/quick_start/pricing).
+- **I get an "API key is not configured" error** — set `DEEPSEEK_API_KEY` or add `apiKey` to the config file.

package/README.zh.md

@@ -0,0 +1,137 @@
+# pi-deepseek-web-search
+
+一个 [pi](https://github.com/earendil-works/pi) 扩展：为 pi 会话中的任意模型提供 **DeepSeek 联网搜索** 能力，桥接 DeepSeek `/responses` API 的服务端搜索。
+
+[English](README.md)
+
+## 功能特性
+
+- **强制搜索**——每次调用都真实执行搜索（`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](#schema)）
+
+## 安装
+
+在包根目录：
+
+```bash
+pi install .
+```
+
+或将 `src/index.ts` 软链/复制到项目的 `.pi/extensions/`，在 pi 会话中执行 `/reload`。
+
+## 配置
+
+配置按以下优先级读取（后者覆盖前者）：
+
+1. 环境变量
+2. 项目配置文件：`.pi/deepseek-web-search.json`
+3. 全局配置文件：`~/.pi/agent/deepseek-web-search.json`
+
+### 示例（`.pi/deepseek-web-search.json`）
+
+```jsonc
+{
+  "$schema": "../schema/deepseek-web-search.config.schema.zh.json",
+  "apiKey": "sk-...",
+  "model": "deepseek-v4-flash",
+  "reasoningEffort": "low",
+  "prices": {
+    "inputPerMillion": 1,
+    "cachedInputPerMillion": 0.02,
+    "outputPerMillion": 2
+  }
+}
+```
+
+> `$schema` 仅供编辑器自动补全/校验，运行时忽略。注释想要中文用 `.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`/`auto` | `low` | `off` 关闭思考以省 token |
+| `maxOutputTokens` | int ≥ 1 | `4096` | 回答最大输出 token 数 |
+| `timeoutMs` | int ≥ 1 | `30000` | 单次请求超时（毫秒） |
+| `cacheTtlMs` | int ≥ 1 | `300000` | 结果缓存 TTL（毫秒） |
+| `maxResultChars` | int ≥ 1 | `50000` | 返回给模型的回答最大字符数 |
+| `prices.inputPerMillion` | number > 0 | `1` | 输入单价（缓存未命中，元/百万 tokens） |
+| `prices.cachedInputPerMillion` | number > 0 | `0.02` | 输入单价（缓存命中） |
+| `prices.outputPerMillion` | number > 0 | `2` | 输出单价 |
+| `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`。
+
+### 价格与峰谷
+
+默认价格遵循[官方定价页](https://api-docs.deepseek.com/zh-cn/quick_start/pricing)（deepseek-v4-flash：1 / 0.02 / 2 元/百万 tokens）。价格可配置，峰谷覆盖已就绪：
+
+```jsonc
+"prices": {
+  "peak": {
+    "multiplier": 2,
+    "hours": [["09:00", "12:00"], ["14:00", "18:00"]]   // 半开区间 [start, end)
+  }
+}
+```
+
+- 高峰时段按官方定义：**北京时间每日** 9:00–12:00 与 14:00–18:00（官方"即将执行"，正式通知前无需配置 `peak`）
+- 高峰价格 = 平峰 × `multiplier`，适用所有计费项
+- 按模型覆盖：`prices.models."deepseek-v4-pro" = { "inputPerMillion": 3, "cachedInputPerMillion": 0.025, "outputPerMillion": 6 }`——`model` 切换后自动生效
+- 工具上报的 `Usage.cost` 为按配置单价估算的金额；缓存命中不产生成本（无真实调用）
+
+### 模型支持
+
+Responses API 目前仅支持 `deepseek-v4-flash`；`deepseek-v4-pro` 预计 2026 年 8 月初支持。适配后设置 `"model": "deepseek-v4-pro"`（或 `DEEPSEEK_MODEL`）即可切换——价格经 `prices.models` 自动联动。
+
+## 使用
+
+向模型提出时效性或外部信息问题，它会自动调用 `deepseek_web_search`：
+
+> 今天北京的天气怎么样？
+
+工具返回 DeepSeek 的综合回答（含引用）与搜索动作记录。结果按 `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`（中文注释）
+
+修改定义后重新生成：
+
+```bash
+pnpm gen:schema
+```
+
+生成文件随仓库提交，并有测试断言其与定义保持同步（防漂移）。
+
+## 开发
+
+```bash
+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`。参见[官方定价页](https://api-docs.deepseek.com/zh-cn/quick_start/pricing)。
+- **报错 "API key is not configured"？** 设置 `DEEPSEEK_API_KEY` 或在配置文件中填 `apiKey`。

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "pi-deepseek-web-search",
+  "type": "module",
+  "version": "0.1.0",
+  "packageManager": "pnpm@11.18.0",
+  "description": "DeepSeek-backed web search tool for pi sessions",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zzwtsy/pi-deepseek-web-search.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "web-search",
+    "search"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README.zh.md",
+    "schema",
+    "src"
+  ],
+  "scripts": {
+    "clean": "rm -rf node_modules",
+    "check": "tsc --noEmit",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "gen:schema": "node scripts/generate-schema.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^9.2.0",
+    "@types/node": "^26.1.2",
+    "eslint": "^10.7.0",
+    "typescript": "6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schema/deepseek-web-search.config.schema.en.json

@@ -0,0 +1,186 @@
+{
+  "type": "object",
+  "properties": {
+    "apiKey": {
+      "type": "string",
+      "minLength": 1,
+      "description": "DeepSeek API key (required). Env DEEPSEEK_API_KEY takes precedence."
+    },
+    "baseUrl": {
+      "type": "string",
+      "default": "https://api.deepseek.com",
+      "description": "API base URL; change when using a proxy. Overridable via DEEPSEEK_BASE_URL."
+    },
+    "model": {
+      "type": "string",
+      "default": "deepseek-v4-flash",
+      "minLength": 1,
+      "pattern": "^(?!\\s*$)",
+      "description": "Model name; switch to deepseek-v4-pro once supported. Overridable via DEEPSEEK_MODEL."
+    },
+    "reasoningEffort": {
+      "type": "string",
+      "enum": [
+        "off",
+        "low",
+        "high",
+        "auto"
+      ],
+      "default": "low",
+      "description": "Reasoning effort: off disables thinking; auto uses model default. Overridable via DEEPSEEK_REASONING_EFFORT."
+    },
+    "maxOutputTokens": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 4096,
+      "description": "Max output tokens. Overridable via DEEPSEEK_MAX_OUTPUT_TOKENS."
+    },
+    "timeoutMs": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 30000,
+      "description": "Request timeout in ms. Overridable via DEEPSEEK_TIMEOUT_MS."
+    },
+    "cacheTtlMs": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 300000,
+      "description": "Search result cache TTL in ms. Overridable via DEEPSEEK_CACHE_TTL_MS."
+    },
+    "maxResultChars": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 50000,
+      "description": "Max result chars before truncation. Overridable via DEEPSEEK_MAX_RESULT_CHARS."
+    },
+    "prices": {
+      "type": "object",
+      "properties": {
+        "inputPerMillion": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "default": 1,
+          "description": "Input price, cache miss. Overridable via DEEPSEEK_PRICE_INPUT."
+        },
+        "cachedInputPerMillion": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "default": 0.02,
+          "description": "Input price, cache hit. Overridable via DEEPSEEK_PRICE_CACHED_INPUT."
+        },
+        "outputPerMillion": {
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "default": 2,
+          "description": "Output price. Overridable via DEEPSEEK_PRICE_OUTPUT."
+        },
+        "peak": {
+          "type": "object",
+          "required": [
+            "multiplier",
+            "hours"
+          ],
+          "properties": {
+            "multiplier": {
+              "type": "number",
+              "exclusiveMinimum": 0,
+              "description": "Peak multiplier; official value is 2."
+            },
+            "hours": {
+              "type": "array",
+              "items": {
+                "type": "array",
+                "additionalItems": false,
+                "items": [
+                  {
+                    "type": "string",
+                    "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$"
+                  },
+                  {
+                    "type": "string",
+                    "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$"
+                  }
+                ],
+                "minItems": 2
+              },
+              "minItems": 1,
+              "description": "Peak hour ranges, half-open [start, end)."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Peak pricing; official peak hours are daily 09:00-12:00 and 14:00-18:00 Beijing time."
+        },
+        "models": {
+          "type": "object",
+          "patternProperties": {
+            "^.*$": {
+              "type": "object",
+              "properties": {
+                "inputPerMillion": {
+                  "type": "number",
+                  "exclusiveMinimum": 0,
+                  "description": "Input price, cache miss."
+                },
+                "cachedInputPerMillion": {
+                  "type": "number",
+                  "exclusiveMinimum": 0,
+                  "description": "Input price, cache hit."
+                },
+                "outputPerMillion": {
+                  "type": "number",
+                  "exclusiveMinimum": 0,
+                  "description": "Output price."
+                },
+                "peak": {
+                  "type": "object",
+                  "required": [
+                    "multiplier",
+                    "hours"
+                  ],
+                  "properties": {
+                    "multiplier": {
+                      "type": "number",
+                      "exclusiveMinimum": 0,
+                      "description": "Peak multiplier; official value is 2."
+                    },
+                    "hours": {
+                      "type": "array",
+                      "items": {
+                        "type": "array",
+                        "additionalItems": false,
+                        "items": [
+                          {
+                            "type": "string",
+                            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$"
+                          },
+                          {
+                            "type": "string",
+                            "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$"
+                          }
+                        ],
+                        "minItems": 2
+                      },
+                      "minItems": 1,
+                      "description": "Peak hour ranges, half-open [start, end)."
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "Peak pricing; official peak hours are daily 09:00-12:00 and 14:00-18:00 Beijing time."
+                }
+              },
+              "additionalProperties": false,
+              "description": "Per-model price override; missing fields fall back to top-level prices."
+            }
+          },
+          "description": "Per-model price overrides, keyed by model name."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Pricing in CNY per million tokens; defaults are the official off-peak prices."
+    }
+  },
+  "additionalProperties": false,
+  "description": "Generated by pnpm gen:schema from src/config-schema.ts — do not edit. 由 src/config-schema.ts 自动生成，请勿手改。",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "deepseek-web-search config (en)"
+}