pi-deepseek-web-search 0.1.0

package/src/config.ts

@@ -0,0 +1,289 @@
+import type { ConfigFileShape } from "./config-schema.js";
+import type { PriceConfig, ReasoningEffort } from "./provider.js";
+import { readFile as defaultReadFile } from "node:fs/promises";
+import { homedir as defaultHomedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+// 配置层：读取顺序 环境变量 → 项目 .pi/ 配置文件 → 全局配置文件 → 默认值。
+// 字段级 merge：高优先级来源只覆盖其提供的字段。
+// 文件结构定义与校验的单一来源在 config-schema.ts（TypeBox），此处只做合并与错误包装。
+// 设计为纯函数（注入 env / readFile / 路径），便于单元测试。
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import { Check, Errors } from "typebox/value";
+import { configFileSchema } from "./config-schema.js";
+
+export const CONFIG_FILE_NAME = "deepseek-web-search.json";
+export const GLOBAL_CONFIG_DIR = join(".pi", "agent");
+
+export interface SearchConfig {
+  /** DeepSeek API key（来自环境变量或配置文件） */
+  apiKey: string;
+  /** API 基础地址（自建代理时修改） */
+  baseUrl: string;
+  /** 模型名（Responses API 目前仅 deepseek-v4-flash；v4-pro 适配后改这里即切换） */
+  model: string;
+  /** 推理强度（off 关闭思考以省 token） */
+  reasoningEffort: ReasoningEffort;
+  /** 回答最大输出 token 数 */
+  maxOutputTokens: number;
+  /** 单次请求超时（毫秒） */
+  timeoutMs: number;
+  /** 搜索结果缓存 TTL（毫秒） */
+  cacheTtlMs: number;
+  /** 返回给 LLM 的文本最大字符数（超出截断） */
+  maxResultChars: number;
+  /** 价格配置（元/百万 tokens，默认官方平峰价） */
+  prices: PriceConfig;
+}
+
+/** 配置文件结构（所有字段可选，按优先级与默认值合并） */
+export type { ConfigFileShape } from "./config-schema.js";
+
+/** 除 apiKey 外的默认值 */
+export const DEFAULT_CONFIG: Omit<SearchConfig, "apiKey"> = {
+  baseUrl: "https://api.deepseek.com",
+  model: "deepseek-v4-flash",
+  reasoningEffort: "low",
+  maxOutputTokens: 4096,
+  timeoutMs: 30_000,
+  cacheTtlMs: 300_000,
+  maxResultChars: 50_000,
+  prices: {
+    inputPerMillion: 1,
+    cachedInputPerMillion: 0.02,
+    outputPerMillion: 2,
+    // v4-pro 官方价预置：Responses API 适配后切 model 即用
+    models: {
+      "deepseek-v4-pro": {
+        inputPerMillion: 3,
+        cachedInputPerMillion: 0.025,
+        outputPerMillion: 6,
+      },
+    },
+  },
+};
+
+/** 配置缺失/非法时抛出的错误（消息为英文 UI 文本） */
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+export interface LoadConfigOptions {
+  /** 项目工作目录（用于定位 .pi/deepseek-web-search.json），缺省时跳过项目配置 */
+  cwd?: string;
+  /** 环境变量表，默认 process.env */
+  env?: NodeJS.ProcessEnv;
+  /** 文件读取函数（可注入 mock），默认 node:fs/promises readFile（utf8） */
+  readFile?: (path: string) => Promise<string>;
+  /** 用户主目录，默认 os.homedir() */
+  homeDir?: string;
+}
+
+const REASONING_EFFORTS: readonly ReasoningEffort[] = ["off", "low", "high", "auto"];
+
+/** 数字字段的环境变量名 → 配置字段名映射 */
+const NUMBER_FIELD_ENV_NAMES: Record<string, keyof Pick<SearchConfig, "maxOutputTokens" | "timeoutMs" | "cacheTtlMs" | "maxResultChars">> = {
+  DEEPSEEK_MAX_OUTPUT_TOKENS: "maxOutputTokens",
+  DEEPSEEK_TIMEOUT_MS: "timeoutMs",
+  DEEPSEEK_CACHE_TTL_MS: "cacheTtlMs",
+  DEEPSEEK_MAX_RESULT_CHARS: "maxResultChars",
+};
+
+/** 校验 schema 表达力之外的字段间约束（JSON Schema 无法表达的例外）：peak.hours 的 start < end、models 空 key */
+function validateBeyondSchema(body: Record<string, unknown>, source: string): void {
+  const prices = body.prices;
+  if (prices == null || typeof prices !== "object")
+    return;
+  const record = prices as Record<string, unknown>;
+  const peak = record.peak;
+  if (peak != null && typeof peak === "object") {
+    const hours = (peak as Record<string, unknown>).hours;
+    if (Array.isArray(hours)) {
+      for (const item of hours) {
+        if (!Array.isArray(item) || item.length !== 2)
+          continue;
+        const [start, end] = item as [string, string];
+        if (start >= end) {
+          throw new ConfigError(`Invalid prices.peak.hours in ${source}: start must be before end`);
+        }
+      }
+    }
+  }
+  const models = record.models;
+  if (models != null && typeof models === "object" && !Array.isArray(models)) {
+    for (const key of Object.keys(models)) {
+      if (key.trim() === "") {
+        throw new ConfigError(`Invalid prices.models in ${source}: empty model name`);
+      }
+    }
+  }
+}
+
+/** 把 TypeBox 校验错误格式化为可读消息：instancePath 的 /a/b 转 a.b */
+export function formatSchemaError(errors: Array<{ instancePath: string; message?: string }>): string {
+  const first = errors[0];
+  if (first == null)
+    return "Invalid config";
+  const path = first.instancePath.split("/").filter(Boolean).join(".") || "/";
+  return `Invalid ${path}: ${first.message ?? "invalid value"}`;
+}
+
+/** 从 JSON 字符串解析配置文件：语法检查 + TypeBox 校验（$schema 仅供编辑器关联，运行时剥离） */
+export function parseConfigFile(raw: string, source: string): ConfigFileShape {
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    throw new ConfigError(`Invalid JSON in ${source}`);
+  }
+  if (json == null || typeof json !== "object" || Array.isArray(json)) {
+    throw new ConfigError(`Invalid config file ${source}: expected a JSON object`);
+  }
+  const record = json as Record<string, unknown>;
+  const { $schema: _ignored, ...body } = record;
+  if (!Check(configFileSchema, body)) {
+    throw new ConfigError(formatSchemaError(Errors(configFileSchema, body)));
+  }
+  validateBeyondSchema(body, source);
+  return body;
+}
+
+/** 尝试读取配置文件，文件不存在时返回 undefined（其他读取错误抛出） */
+async function tryReadConfigFile(
+  path: string,
+  readFile: (path: string) => Promise<string>,
+): Promise<ConfigFileShape | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT")
+      return undefined;
+    throw error;
+  }
+  return parseConfigFile(raw, path);
+}
+
+/** 价格类环境变量名 → PriceConfig 字段名映射 */
+const PRICE_ENV_NAMES: Record<string, keyof Pick<PriceConfig, "inputPerMillion" | "cachedInputPerMillion" | "outputPerMillion">> = {
+  DEEPSEEK_PRICE_INPUT: "inputPerMillion",
+  DEEPSEEK_PRICE_CACHED_INPUT: "cachedInputPerMillion",
+  DEEPSEEK_PRICE_OUTPUT: "outputPerMillion",
+};
+
+/** 从环境变量读取配置（非法值抛错，未设置返回 undefined 字段） */
+function configFromEnv(env: NodeJS.ProcessEnv): ConfigFileShape {
+  const shape: ConfigFileShape = {};
+  if (env.DEEPSEEK_API_KEY !== undefined)
+    shape.apiKey = env.DEEPSEEK_API_KEY;
+  if (env.DEEPSEEK_BASE_URL !== undefined)
+    shape.baseUrl = env.DEEPSEEK_BASE_URL;
+  if (env.DEEPSEEK_MODEL !== undefined) {
+    if (env.DEEPSEEK_MODEL.trim() === "") {
+      throw new ConfigError("Invalid DEEPSEEK_MODEL: expected a non-empty model name");
+    }
+    shape.model = env.DEEPSEEK_MODEL;
+  }
+  if (env.DEEPSEEK_REASONING_EFFORT !== undefined) {
+    if (!REASONING_EFFORTS.includes(env.DEEPSEEK_REASONING_EFFORT as ReasoningEffort)) {
+      throw new ConfigError(`Invalid DEEPSEEK_REASONING_EFFORT: expected ${REASONING_EFFORTS.join("/")}`);
+    }
+    shape.reasoningEffort = env.DEEPSEEK_REASONING_EFFORT as ReasoningEffort;
+  }
+  for (const [envName, field] of Object.entries(NUMBER_FIELD_ENV_NAMES)) {
+    const value = env[envName];
+    if (value === undefined)
+      continue;
+    const num = Number.parseInt(value, 10);
+    if (!Number.isInteger(num) || num <= 0) {
+      throw new ConfigError(`Invalid ${envName}: expected a positive integer`);
+    }
+    shape[field] = num;
+  }
+  const envPrices: Partial<PriceConfig> = {};
+  for (const [envName, field] of Object.entries(PRICE_ENV_NAMES)) {
+    const value = env[envName];
+    if (value === undefined)
+      continue;
+    const num = Number.parseFloat(value);
+    if (!Number.isFinite(num) || num <= 0) {
+      throw new ConfigError(`Invalid ${envName}: expected a positive number`);
+    }
+    envPrices[field] = num;
+  }
+  if (Object.keys(envPrices).length > 0) {
+    shape.prices = envPrices;
+  }
+  return shape;
+}
+
+/** 字段级合并（prices 需一层深合并：先从 shape 中解构出 prices，避免 Object.assign 整块覆盖默认/其他来源） */
+function mergeShape(merged: SearchConfig, shape: ConfigFileShape): void {
+  const { prices: shapePrices, ...rest } = shape;
+  Object.assign(merged, rest);
+  if (shapePrices != null) {
+    merged.prices = { ...merged.prices, ...shapePrices };
+  }
+}
+
+/**
+ * 合并多来源配置：默认值 < 全局文件 < 项目文件 < 环境变量。
+ * 不校验 apiKey（调用方按需调用 validateConfig）。
+ */
+export async function loadConfig(options: LoadConfigOptions = {}): Promise<SearchConfig> {
+  const env = options.env ?? process.env;
+  const readFile = options.readFile ?? (async (path: string) => defaultReadFile(path, "utf8"));
+  const homeDir = options.homeDir ?? defaultHomedir();
+
+  const merged: SearchConfig = { apiKey: "", ...DEFAULT_CONFIG };
+
+  // 全局配置文件：~/.pi/agent/deepseek-web-search.json
+  const globalFile = await tryReadConfigFile(join(homeDir, GLOBAL_CONFIG_DIR, CONFIG_FILE_NAME), readFile);
+  if (globalFile != null)
+    mergeShape(merged, globalFile);
+
+  // 项目配置文件：<cwd>/.pi/deepseek-web-search.json
+  if (options.cwd != null) {
+    const projectFile = await tryReadConfigFile(join(options.cwd, CONFIG_DIR_NAME, CONFIG_FILE_NAME), readFile);
+    if (projectFile != null)
+      mergeShape(merged, projectFile);
+  }
+
+  // 环境变量：字段级最高优先级
+  mergeShape(merged, configFromEnv(env));
+
+  return merged;
+}
+
+/** 校验配置是否可用（目前仅要求 apiKey 非空），返回可读错误信息 */
+export function validateConfig(config: SearchConfig): string | undefined {
+  if (config.apiKey.trim() === "") {
+    return "DeepSeek API key is not configured. Set DEEPSEEK_API_KEY or add apiKey to the config file.";
+  }
+  return undefined;
+}
+
+/** 带进程内缓存的配置提供者（扩展内复用；reload 用于 /deepseek-search 命令刷新） */
+export class ConfigProvider {
+  private cached: SearchConfig | undefined;
+  private readonly options: LoadConfigOptions;
+
+  constructor(options: LoadConfigOptions = {}) {
+    this.options = options;
+  }
+
+  async get(): Promise<SearchConfig> {
+    if (this.cached === undefined) {
+      this.cached = await loadConfig(this.options);
+    }
+    return this.cached;
+  }
+
+  async reload(): Promise<SearchConfig> {
+    this.cached = await loadConfig(this.options);
+    return this.cached;
+  }
+}

package/src/deepseek.ts

@@ -0,0 +1,272 @@
+import type { ReasoningEffort, SearchErrorCode, SearchOptions, SearchProvider, SearchResult, SearchUsage, WebSearchAction } from "./provider.js";
+import { SearchError } from "./provider.js";
+// deepseek.ts —— DeepSeek /responses API 适配器：实现 SearchProvider 端口。
+// 唯一知道 DeepSeek 协议/HTTP 细节的文件；领域类型与错误定义见 provider.ts。
+// 实测要点（2026-08-01，见 docs/api/Search.md）：
+//   - web_search_call.action.queries 是数组且混入 "ws_call_id=..." 内部参数，需过滤
+//   - open_page 的 url 带 "#ws_call_id=..." 后缀，需剥离
+//   - message 有 phase 字段：只取 "final_answer"，跳过 "commentary"（思考外显文本）
+
+export interface DeepSeekClientOptions {
+  /** 默认 https://api.deepseek.com */
+  baseUrl?: string;
+  apiKey: string;
+  /** 注入 fetch 实现以便测试（默认全局 fetch） */
+  fetchFn?: typeof fetch;
+  /** 默认模型，仅 deepseek-v4-flash 支持 /responses */
+  model?: string;
+}
+
+const DEFAULT_BASE_URL = "https://api.deepseek.com";
+const DEFAULT_MODEL = "deepseek-v4-flash";
+const DEFAULT_MAX_OUTPUT_TOKENS = 4096;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_RETRIES = 2;
+const RETRY_BASE_DELAY_MS = 500;
+
+/** 过滤查询数组中的 ws_call_id= 噪声条目 */
+function cleanQueries(queries: unknown): string[] | undefined {
+  if (!Array.isArray(queries))
+    return undefined;
+  const cleaned = queries
+    .filter((q): q is string => typeof q === "string")
+    .filter(q => !q.startsWith("ws_call_id="));
+  return cleaned.length > 0 ? cleaned : undefined;
+}
+
+/** 剥离 URL 上的 #ws_call_id= 后缀 */
+function cleanUrl(url: unknown): string | undefined {
+  if (typeof url !== "string")
+    return undefined;
+  return url.split("#ws_call_id=")[0] ?? undefined;
+}
+
+/** reasoningEffort → 请求体 reasoning 字段（auto 时返回 undefined，不传该字段） */
+export function buildReasoningField(effort?: ReasoningEffort): { effort: string } | undefined {
+  switch (effort) {
+    case "off":
+      return { effort: "none" };
+    case "low":
+      return { effort: "low" };
+    case "high":
+      return { effort: "high" };
+    case "auto":
+    case undefined:
+      return undefined;
+  }
+}
+
+/** 解析 web_search_call item（容错：字段缺失不抛错） */
+function parseWebSearchCall(item: { action?: unknown }): WebSearchAction | undefined {
+  if (item.action == null || typeof item.action !== "object")
+    return undefined;
+  const action = item.action as { type?: unknown; queries?: unknown; url?: unknown };
+  if (typeof action.type !== "string")
+    return undefined;
+  if (action.type === "search") {
+    return { type: "search", queries: cleanQueries(action.queries) };
+  }
+  if (action.type === "open_page" || action.type === "find_in_page") {
+    return { type: action.type, url: cleanUrl(action.url) };
+  }
+  return undefined;
+}
+
+/** 从响应 output 中提取最终回答（只取 phase=final_answer 的 message） */
+function extractFinalAnswer(output: unknown[]): string {
+  const parts: string[] = [];
+  for (const item of output) {
+    if (item == null || typeof item !== "object")
+      continue;
+    const it = item as { type?: unknown; phase?: unknown; content?: unknown };
+    if (it.type !== "message" || it.phase !== "final_answer")
+      continue;
+    if (!Array.isArray(it.content))
+      continue;
+    for (const part of it.content) {
+      if (part == null || typeof part !== "object")
+        continue;
+      const p = part as { type?: unknown; text?: unknown };
+      if (p.type === "output_text" && typeof p.text === "string") {
+        parts.push(p.text);
+      }
+    }
+  }
+  return parts.join("");
+}
+
+/** 解析 usage（容错：字段缺失时返回 undefined） */
+function parseUsage(usage: unknown): SearchUsage | undefined {
+  if (usage == null || typeof usage !== "object")
+    return undefined;
+  const u = usage as {
+    input_tokens?: unknown;
+    output_tokens?: unknown;
+    total_tokens?: unknown;
+    input_tokens_details?: { cached_tokens?: unknown };
+    output_tokens_details?: { reasoning_tokens?: unknown };
+  };
+  if (typeof u.input_tokens !== "number" || typeof u.output_tokens !== "number") {
+    return undefined;
+  }
+  return {
+    inputTokens: u.input_tokens,
+    outputTokens: u.output_tokens,
+    reasoningTokens: typeof u.output_tokens_details?.reasoning_tokens === "number" ? u.output_tokens_details.reasoning_tokens : 0,
+    cachedTokens: typeof u.input_tokens_details?.cached_tokens === "number" ? u.input_tokens_details.cached_tokens : 0,
+    totalTokens: typeof u.total_tokens === "number" ? u.total_tokens : u.input_tokens + u.output_tokens,
+  };
+}
+
+/** HTTP 状态码 → 错误码映射 */
+function mapHttpError(status: number): SearchErrorCode {
+  switch (status) {
+    case 401:
+      return "invalid_api_key";
+    case 402:
+      return "insufficient_balance";
+    case 429:
+      return "rate_limited";
+    case 400:
+    case 422:
+      return "invalid_request";
+    default:
+      return status >= 500 ? "server_error" : "unknown";
+  }
+}
+
+/** 从错误响应 body 提取 message（DeepSeek 格式 {"error": {"message": ...}}） */
+function extractErrorMessage(body: unknown): string | undefined {
+  if (body == null || typeof body !== "object")
+    return undefined;
+  const err = (body as { error?: unknown }).error;
+  if (err == null || typeof err !== "object")
+    return undefined;
+  const msg = (err as { message?: unknown }).message;
+  return typeof msg === "string" ? msg : undefined;
+}
+
+/** 可取消的延时（用于重试退避） */
+async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      reject(new SearchError("Request aborted", "aborted"));
+    }, { once: true });
+  });
+}
+
+export class DeepSeekClient implements SearchProvider {
+  readonly id = "deepseek-responses";
+
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly fetchFn: typeof fetch;
+  private readonly model: string;
+
+  constructor(options: DeepSeekClientOptions) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.fetchFn = options.fetchFn ?? fetch;
+    this.model = options.model ?? DEFAULT_MODEL;
+  }
+
+  /**
+   * 执行一次联网搜索。
+   * 服务端执行 search/open_page 等动作并生成综合回答，返回回答文本与动作记录。
+   */
+  async search(query: string, options: SearchOptions = {}): Promise<SearchResult> {
+    const body = this.buildRequestBody(query, options);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+    // 合并外部 signal 与内部超时，并区分取消来源
+    const controller = new AbortController();
+    const onExternalAbort = () => controller.abort();
+    options.signal?.addEventListener("abort", onExternalAbort);
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      for (let attempt = 0; ; attempt++) {
+        try {
+          const response = await this.fetchFn(`${this.baseUrl}/responses`, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "Authorization": `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+          });
+
+          if (response.status === 200) {
+            const json = (await response.json()) as Record<string, unknown>;
+            return this.parseResponse(json);
+          }
+
+          // 5xx 且未用尽重试次数时退避重试；其余状态直接映射错误
+          if (response.status >= 500 && attempt < MAX_RETRIES) {
+            await sleep(RETRY_BASE_DELAY_MS * 2 ** attempt, controller.signal);
+            continue;
+          }
+
+          let rawBody: unknown;
+          try {
+            rawBody = await response.json();
+          } catch {
+            rawBody = undefined;
+          }
+          const message = extractErrorMessage(rawBody) ?? `HTTP ${response.status}`;
+          throw new SearchError(message, mapHttpError(response.status));
+        } catch (error) {
+          if (error instanceof SearchError)
+            throw error;
+          // 区分取消来源：外部 signal → aborted；内部超时 → timeout
+          if (options.signal?.aborted)
+            throw new SearchError("Request aborted", "aborted");
+          if (controller.signal.aborted)
+            throw new SearchError(`Request timed out after ${timeoutMs}ms`, "timeout");
+          throw new SearchError(`Network error: ${(error as Error).message}`, "network_error");
+        }
+      }
+    } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onExternalAbort);
+    }
+  }
+
+  /** 构造 /responses 请求体：搜索恒为强制（插件职责即搜索，不让模型跳过） */
+  private buildRequestBody(query: string, options: SearchOptions): Record<string, unknown> {
+    const body: Record<string, unknown> = {
+      model: this.model,
+      input: query,
+      tools: [{ type: "web_search" }],
+      tool_choice: { type: "web_search" },
+      max_output_tokens: options.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
+    };
+    const reasoning = buildReasoningField(options.reasoningEffort);
+    if (reasoning)
+      body.reasoning = reasoning;
+    return body;
+  }
+
+  /** 解析 /responses 成功响应 */
+  private parseResponse(json: Record<string, unknown>): SearchResult {
+    const output = Array.isArray(json.output) ? json.output : [];
+    const actions: WebSearchAction[] = [];
+    for (const item of output) {
+      if (item == null || typeof item !== "object")
+        continue;
+      const action = parseWebSearchCall(item as { action?: unknown });
+      if (action != null)
+        actions.push(action);
+    }
+    return {
+      answer: extractFinalAnswer(output),
+      actions,
+      usage: parseUsage(json.usage),
+      model: typeof json.model === "string" ? json.model : this.model,
+      id: typeof json.id === "string" ? json.id : undefined,
+    };
+  }
+}