pi-deepseek-web-search 0.1.0

package/src/format.ts

@@ -0,0 +1,159 @@
+// 结果格式化：组装给 LLM 的 content 与渲染用的 details，包含截断逻辑。
+// 纯函数，便于单元测试。UI 文本一律英文。
+import type { PriceConfig, SearchResult, SearchUsage, WebSearchAction } from "./provider.js";
+
+export interface ToolContentOptions {
+  mode: "answer" | "results";
+  maxChars: number;
+}
+
+export interface ToolDetails {
+  query: string;
+  mode: "answer" | "results";
+  searches: WebSearchAction[];
+  answer: string;
+  truncated: boolean;
+  cached: boolean;
+  durationMs: number;
+  model: string;
+  /** 本次搜索的 token 用量（缓存命中时沿用首次搜索的记录） */
+  usage?: SearchUsage;
+}
+
+/** 按字符截断文本，超出时在末尾追加截断标记 */
+export function truncate(text: string, maxChars: number): { text: string; truncated: boolean } {
+  if (text.length <= maxChars)
+    return { text, truncated: false };
+  return { text: `${text.slice(0, maxChars)}\n\n...[truncated]`, truncated: true };
+}
+
+/** 搜索动作的展示摘要（过滤掉无意义的空查询） */
+function formatActions(actions: WebSearchAction[]): string[] {
+  const lines: string[] = [];
+  for (const action of actions) {
+    if (action.type === "search" && action.queries != null && action.queries.length > 0) {
+      lines.push(`- searched: ${action.queries.join(" | ")}`);
+    } else if ((action.type === "open_page" || action.type === "find_in_page") && action.url != null) {
+      lines.push(`- ${action.type === "open_page" ? "opened" : "searched in"}: ${action.url}`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * 组装返回给 LLM 的 content 文本。
+ * answer 模式：完整回答 + 搜索动作记录；results 模式：仅压缩后的回答摘要。
+ */
+export function buildToolContent(result: SearchResult, options: ToolContentOptions): {
+  content: string;
+  truncated: boolean;
+} {
+  if (result.answer.trim() === "") {
+    return {
+      content: `The search returned no usable answer. The search actions executed:${
+        result.actions.length > 0 ? `\n${formatActions(result.actions).join("\n")}` : " none"}`,
+      truncated: false,
+    };
+  }
+
+  if (options.mode === "results") {
+    const { text, truncated } = truncate(result.answer, options.maxChars);
+    return { content: text, truncated };
+  }
+
+  const { text, truncated } = truncate(result.answer, options.maxChars);
+  const actionLines = formatActions(result.actions);
+  const content = actionLines.length > 0
+    ? `${text}\n\nSearch actions:\n${actionLines.join("\n")}`
+    : text;
+  return { content, truncated };
+}
+
+/** 组装 details（供 TUI 渲染层使用；answer 与 content 同源，均为截断后文本） */
+export function buildToolDetails(
+  result: SearchResult,
+  options: { query: string; mode: "answer" | "results"; cached: boolean; durationMs: number },
+  maxChars: number,
+): ToolDetails {
+  const { text, truncated } = truncate(result.answer, maxChars);
+  return {
+    query: options.query,
+    mode: options.mode,
+    searches: result.actions,
+    answer: text,
+    truncated,
+    cached: options.cached,
+    durationMs: options.durationMs,
+    model: result.model,
+    usage: result.usage,
+  };
+}
+
+/** 成本明细（元）：input/output/cacheRead 之和为 total */
+export interface CostBreakdown {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  total: number;
+}
+
+/**
+ * 判断 now 是否处于高峰时段（北京时间每日；与机器时区无关，官方按北京时间计费）。
+ * 半开区间 [start, end)：09:00 计高峰、12:00 不计，两个时段无缝衔接。
+ */
+export function isPeakTime(now: Date, hours: Array<[string, string]>): boolean {
+  // Intl 输出如 "09:30"（en-US hour12:false 可能有前导空格或 "24:00" 表示午夜），归一化为 HH:MM
+  let hhmm = new Intl.DateTimeFormat("en-US", {
+    timeZone: "Asia/Shanghai",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  }).format(now);
+  hhmm = hhmm.replace(/\s+/g, "").padStart(5, "0");
+  if (hhmm === "24:00")
+    hhmm = "00:00";
+  return hours.some(([start, end]) => hhmm >= start && hhmm < end);
+}
+
+/**
+ * 取当前模型生效的价格：models 表命中则返回"顶层为底 + 覆盖价叠加"的结果，否则返回顶层。
+ * 返回不含 models 字段（已解析），可直接传给 computeCost。
+ */
+export function resolvePrices(prices: PriceConfig, model: string): PriceConfig {
+  const override = prices.models?.[model];
+  if (override == null)
+    return prices;
+  return {
+    inputPerMillion: override.inputPerMillion ?? prices.inputPerMillion,
+    cachedInputPerMillion: override.cachedInputPerMillion ?? prices.cachedInputPerMillion,
+    outputPerMillion: override.outputPerMillion ?? prices.outputPerMillion,
+    peak: override.peak ?? prices.peak,
+  };
+}
+
+/**
+ * 按价格配置计算成本（元）。
+ * cachedTokens 是 inputTokens 的子集：未命中部分 = input - cached，命中部分按缓存单价。
+ * 配置了 peak 且 now 处于高峰时段时，所有单价 × multiplier。
+ */
+export function computeCost(usage: SearchUsage, prices: PriceConfig, now: Date = new Date()): CostBreakdown {
+  const peakMultiplier
+    = prices.peak != null && isPeakTime(now, prices.peak.hours) ? prices.peak.multiplier : 1;
+  const uncachedInput = Math.max(usage.inputTokens - usage.cachedTokens, 0);
+  const input = (uncachedInput / 1_000_000) * prices.inputPerMillion * peakMultiplier;
+  const cacheRead = (usage.cachedTokens / 1_000_000) * prices.cachedInputPerMillion * peakMultiplier;
+  const output = (usage.outputTokens / 1_000_000) * prices.outputPerMillion * peakMultiplier;
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite: 0,
+    total: input + output + cacheRead,
+  };
+}
+
+/** 工具入参归一化：query 去除首尾空白 */
+export function normalizeQuery(query: string): string {
+  return query.trim();
+}

package/src/index.ts

@@ -0,0 +1,193 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { SearchConfig } from "./config.js";
+import type { PriceConfig, SearchProvider, SearchResult, SearchUsage } from "./provider.js";
+// 入口文件：注册 deepseek_web_search 工具。
+// 依赖链：config（配置）→ provider（搜索后端端口）→ deepseek（DeepSeek 适配器）→ cache（TTL 缓存）→ format（结果组装）。
+// 组合点 createProvider 是本扩展唯一的后端接入位置：换/加搜索后端只改这里。
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import { TtlCache } from "./cache.js";
+import { CONFIG_FILE_NAME, ConfigProvider, GLOBAL_CONFIG_DIR, validateConfig } from "./config.js";
+import { DeepSeekClient } from "./deepseek.js";
+import { buildToolContent, buildToolDetails, computeCost, normalizeQuery, resolvePrices } from "./format.js";
+import { SearchError } from "./provider.js";
+import { renderCall, renderResult } from "./render.js";
+import { deepseekWebSearchSchema } from "./types.js";
+
+export type { ConfigFileShape, SearchConfig } from "./config.js";
+export type { SearchError, SearchErrorCode, SearchProvider, SearchResult, WebSearchAction } from "./provider.js";
+export type { DeepSeekWebSearchDetails, DeepSeekWebSearchInput } from "./types.js";
+
+/** 搜索缓存单例：模块级共享，reload 后随模块重置 */
+let sharedCache: TtlCache<SearchResult> | undefined;
+
+/** 组合点：把配置装配成 SearchProvider。换/加后端时只改这里（未来加 provider 配置字段后改为 switch + assertNever 分发） */
+function createProvider(config: SearchConfig): SearchProvider {
+  return new DeepSeekClient({
+    baseUrl: config.baseUrl,
+    apiKey: config.apiKey,
+    model: config.model,
+  });
+}
+
+/** SearchUsage → pi 的 Usage（成本按价格配置实时计算，默认官方平峰价） */
+function toPiUsage(usage: SearchUsage, prices: PriceConfig) {
+  return {
+    input: usage.inputTokens,
+    output: usage.outputTokens,
+    cacheRead: usage.cachedTokens,
+    cacheWrite: 0,
+    reasoning: usage.reasoningTokens,
+    totalTokens: usage.totalTokens,
+    cost: computeCost(usage, prices),
+  };
+}
+
+export default function (pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "deepseek_web_search",
+    label: "DeepSeek Web Search",
+    description:
+      "Search the web via the DeepSeek API. The search runs server-side and the response contains a synthesized answer with citations plus a record of the search actions. Use for up-to-date, time-sensitive, or external information.",
+    promptSnippet: "Search the web via DeepSeek for up-to-date or external information",
+    promptGuidelines: [
+      "Use deepseek_web_search when the user asks about time-sensitive or external information that is not available in the local context.",
+      "After a deepseek_web_search call, base your final answer on the returned content and cite the sources listed in it.",
+    ],
+    parameters: deepseekWebSearchSchema,
+    renderCall,
+    renderResult,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const startedAt = Date.now();
+      const query = normalizeQuery(params.query);
+      if (query === "") {
+        throw new Error("Query must not be empty.");
+      }
+      const mode = params.mode ?? "answer";
+
+      // 每次执行读取配置（ConfigProvider 内部有进程内缓存，读取开销小）
+      const configProvider = new ConfigProvider({ cwd: ctx.cwd });
+      const config = await configProvider.get();
+      const configError = validateConfig(config);
+      if (configError != null) {
+        throw new Error(configError);
+      }
+
+      // 首个使用点按配置的 TTL 创建缓存单例
+      sharedCache ??= new TtlCache<SearchResult>(config.cacheTtlMs);
+      const cache = sharedCache;
+
+      const cacheKey = `${config.model}:${mode}:${query}`;
+      const cachedResult = cache.get(cacheKey);
+      if (cachedResult != null) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: buildToolContent(cachedResult, { mode, maxChars: config.maxResultChars }).content,
+            },
+          ],
+          details: buildToolDetails(cachedResult, { query, mode, cached: true, durationMs: 0 }, config.maxResultChars),
+        };
+      }
+
+      const provider = createProvider(config);
+
+      onUpdate?.({
+        content: [{ type: "text", text: "Searching the web..." }],
+        details: { stage: "searching" },
+      });
+
+      try {
+        const result = await provider.search(query, {
+          reasoningEffort: config.reasoningEffort,
+          maxOutputTokens: config.maxOutputTokens,
+          timeoutMs: config.timeoutMs,
+          signal,
+        });
+
+        onUpdate?.({
+          content: [{ type: "text", text: "Synthesizing answer..." }],
+          details: { stage: "answering" },
+        });
+
+        cache.set(cacheKey, result);
+        const durationMs = Date.now() - startedAt;
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: buildToolContent(result, { mode, maxChars: config.maxResultChars }).content,
+            },
+          ],
+          details: buildToolDetails(result, { query, mode, cached: false, durationMs }, config.maxResultChars),
+          usage: result.usage ? toPiUsage(result.usage, resolvePrices(config.prices, config.model)) : undefined,
+        };
+      } catch (error) {
+        if (error instanceof SearchError && error.code === "aborted") {
+          // 用户取消：不标记为错误，返回说明文本
+          return {
+            content: [{ type: "text", text: "The web search was cancelled." }],
+            details: { query, mode, cancelled: true },
+          };
+        }
+        throw error;
+      }
+    },
+  });
+
+  // /deepseek-search 命令：查看配置状态 / 清空缓存。无 UI 模式（print/rpc）下仅依赖 notify，不调 dialog。
+  pi.registerCommand("deepseek-search", {
+    description: "Show config status or clear the search cache. Usage: /deepseek-search [status|clear-cache|config]",
+    getArgumentCompletions: prefix =>
+      ["status", "clear-cache", "config"]
+        .filter(action => action.startsWith(prefix))
+        .map(action => ({ value: action, label: action })),
+    handler: async (args, ctx) => {
+      const action = args.trim() || "status";
+
+      if (action === "clear-cache") {
+        sharedCache?.clear();
+        ctx.ui.notify("deepseek-search: cache cleared", "info");
+        return;
+      }
+      if (action === "config") {
+        const globalPath = join(homedir(), GLOBAL_CONFIG_DIR, CONFIG_FILE_NAME);
+        // 持久可见输出：状态查看类信息不适合 notify（会淡出且截断），按官方最佳实践走 sendMessage(display: true)
+        pi.sendMessage({
+          customType: "deepseek-search",
+          content: `Config files:\n  project: ${join(ctx.cwd, CONFIG_DIR_NAME, CONFIG_FILE_NAME)}\n  global: ${globalPath}`,
+          display: true,
+        });
+        return;
+      }
+      if (action !== "status") {
+        ctx.ui.notify(`Unknown action "${action}". Usage: /deepseek-search [status|clear-cache|config]`, "error");
+        return;
+      }
+
+      const configProvider = new ConfigProvider({ cwd: ctx.cwd });
+      const config = await configProvider.get();
+      const keyMasked = config.apiKey
+        ? `${config.apiKey.slice(0, 3)}...${config.apiKey.slice(-4)}`
+        : "not configured";
+      const priceSummary = `${config.prices.inputPerMillion}/${config.prices.cachedInputPerMillion}/${config.prices.outputPerMillion}`
+        + ` CNY per 1M tokens (input miss/hit/output)${
+          config.prices.peak != null ? ", peak pricing enabled" : ""}`;
+      pi.sendMessage({
+        customType: "deepseek-search",
+        content: [
+          `API key: ${keyMasked}`,
+          `Model: ${config.model}`,
+          `Base URL: ${config.baseUrl}`,
+          `Reasoning effort: ${config.reasoningEffort}`,
+          `Cache entries: ${sharedCache?.size() ?? 0}`,
+          `Prices: ${priceSummary}`,
+        ].join("\n"),
+        display: true,
+      });
+    },
+  });
+}

package/src/provider.ts

@@ -0,0 +1,109 @@
+// provider.ts —— 搜索后端抽象（消费者拥有：按业务需要设计，而非按厂商 API）。
+// 纯类型 + 错误类，零 IO、零 src 内 import；未来新增后端（如 Anthropic）只实现 SearchProvider。
+export type ReasoningEffort = "off" | "low" | "high" | "auto";
+
+/** 搜索选项：由调用方从配置映射而来，各后端按需使用 */
+export interface SearchOptions {
+  /** 推理强度（off 关闭思考以省 token） */
+  reasoningEffort?: ReasoningEffort;
+  /** 回答最大输出 token 数 */
+  maxOutputTokens?: number;
+  /** 单次请求超时（毫秒） */
+  timeoutMs?: number;
+  /** 外部取消信号（用户取消时透传） */
+  signal?: AbortSignal;
+}
+
+/** 服务端执行的一次搜索动作 */
+export interface WebSearchAction {
+  type: "search" | "open_page" | "find_in_page";
+  /** search 动作的查询词（已过滤 ws_call_id= 噪声条目） */
+  queries?: string[];
+  /** open_page 动作的 URL（已剥离 #ws_call_id= 后缀） */
+  url?: string;
+}
+
+/** token 用量统计（映射到 pi Usage 的输入） */
+export interface SearchUsage {
+  inputTokens: number;
+  outputTokens: number;
+  reasoningTokens: number;
+  cachedTokens: number;
+  totalTokens: number;
+}
+
+/** 一次搜索的产物：综合回答 + 动作记录 */
+export interface SearchResult {
+  /** final_answer message 的拼接文本（可能为空串，此时说明响应异常） */
+  answer: string;
+  /** 服务端执行的搜索动作序列 */
+  actions: WebSearchAction[];
+  usage?: SearchUsage;
+  model: string;
+  id?: string;
+}
+
+/** 峰谷定价覆盖（可选）。官方定义：高峰 = 平时 × multiplier，时段为北京时间每日 */
+export interface PeakPriceConfig {
+  /** 高峰单价 = 平峰单价 × multiplier */
+  multiplier: number;
+  /** 高峰时段列表（北京时间每日），半开区间 [start, end)，如 [["09:00", "12:00"], ["14:00", "18:00"]] */
+  hours: Array<[string, string]>;
+}
+
+/** 按模型覆盖的价格（models 表的值；字段可选 = 部分覆盖，缺省项回退顶层价格；禁止再嵌套 models） */
+export interface ModelPriceConfig {
+  /** 输入单价（缓存未命中） */
+  inputPerMillion?: number;
+  /** 输入单价（缓存命中） */
+  cachedInputPerMillion?: number;
+  /** 输出单价 */
+  outputPerMillion?: number;
+  /** 峰谷覆盖：不配置 = 回退顶层 peak */
+  peak?: PeakPriceConfig;
+}
+
+/** 价格配置：元/百万 tokens（依据官方定价页 2026-08，deepseek-v4-flash 为 1 / 0.02 / 2） */
+export interface PriceConfig {
+  /** 输入单价（缓存未命中） */
+  inputPerMillion: number;
+  /** 输入单价（缓存命中） */
+  cachedInputPerMillion: number;
+  /** 输出单价 */
+  outputPerMillion: number;
+  /** 峰谷覆盖：不配置 = 全时段平峰价（官方执行峰谷前的现状） */
+  peak?: PeakPriceConfig;
+  /** 按模型覆盖的价格表（key = 模型名，命中优先；整块覆盖，不逐 key 合并） */
+  models?: Record<string, ModelPriceConfig>;
+}
+
+/** 搜索失败原因（判别联合，供上层按类型处理） */
+export type SearchErrorCode
+  = | "invalid_api_key"
+    | "insufficient_balance"
+    | "rate_limited"
+    | "server_error"
+    | "network_error"
+    | "timeout"
+    | "aborted"
+    | "invalid_request"
+    | "unknown";
+
+/** 搜索失败的错误（code 为判别联合，上层据此区分取消/限流/余额等场景） */
+export class SearchError extends Error {
+  code: SearchErrorCode;
+
+  constructor(message: string, code: SearchErrorCode) {
+    super(message);
+    this.name = "SearchError";
+    this.code = code;
+  }
+}
+
+/** 搜索后端抽象：业务只依赖该接口，具体实现（如 DeepSeek /responses）是适配器 */
+export interface SearchProvider {
+  /** 稳定标识，写入 details 供用户区分后端，如 "deepseek-responses" */
+  readonly id: string;
+  /** 执行一次联网搜索，返回综合回答与搜索动作记录 */
+  search: (query: string, options: SearchOptions) => Promise<SearchResult>;
+}

package/src/render.ts

@@ -0,0 +1,67 @@
+// render.ts —— TUI 渲染层：renderCall/renderResult（纯展示，不参与核心逻辑；主题一律取自 theme 回调）。
+// 注意：不直接依赖 @earendil-works/pi-agent-core（非直接依赖，pnpm 下解析不到）；
+// 用本地结构化类型描述工具结果，参数逆变保证与 ToolDefinition 的签名兼容。
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import type { DeepSeekWebSearchDetails, DeepSeekWebSearchInput } from "./types.js";
+import { Text } from "@earendil-works/pi-tui";
+
+/** 工具结果的结构化视图（与 AgentToolResult 兼容的最小面） */
+interface RenderableToolResult<T> {
+  content: Array<{ type: string; text?: string }>;
+  details: T;
+  isError?: boolean;
+}
+
+/** 展开态回答的最大显示字符数（渲染层限长，不影响返回给模型的内容） */
+const EXPANDED_ANSWER_CHARS = 2000;
+
+/** 工具行：标题 + 引号 query */
+export function renderCall(args: DeepSeekWebSearchInput, theme: Theme): Component {
+  const title = theme.fg("toolTitle", theme.bold("deepseek_web_search "));
+  const query = theme.fg("dim", `"${args.query}"`);
+  return new Text(`${title}${query}`);
+}
+
+/** 工具结果行：执行中（partial）→ 错误态 → 完成（折叠摘要 / 展开详情） */
+export function renderResult(
+  result: RenderableToolResult<Partial<DeepSeekWebSearchDetails> | { stage?: string }>,
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+): Component {
+  const contentText = result.content[0]?.type === "text" ? (result.content[0].text ?? "") : "";
+  const details = result.details as Partial<DeepSeekWebSearchDetails> | undefined;
+
+  // 执行中：onUpdate 推送的阶段文本（"Searching the web..." / "Synthesizing answer..."）
+  if (options.isPartial) {
+    return new Text(theme.fg("dim", contentText));
+  }
+
+  // 错误态：details.error 优先，其次 content 文本
+  if (result.isError) {
+    const error = (result.details as { error?: unknown } | undefined)?.error;
+    const message = typeof error === "string" ? error : (contentText || "Search failed");
+    return new Text(theme.fg("error", `✗ ${message}`));
+  }
+
+  // 折叠态：成功标记 + 摘要（搜索次数、回答字符数、截断标记）
+  if (!options.expanded) {
+    const searches = details?.searches?.length ?? 0;
+    const chars = details?.answer?.length ?? 0;
+    const truncated = details?.truncated ? " [truncated]" : "";
+    return new Text(theme.fg("success", `✓ ${searches} searches · ${chars} chars${truncated}`));
+  }
+
+  // 展开态：回答全文（渲染限长）+ 搜索动作列表（dim）
+  const answer = (details?.answer ?? "").slice(0, EXPANDED_ANSWER_CHARS);
+  const actionLines: string[] = [];
+  for (const action of details?.searches ?? []) {
+    if (action.type === "search" && action.queries != null && action.queries.length > 0) {
+      actionLines.push(theme.fg("dim", `- searched: ${action.queries.join(" | ")}`));
+    } else if ((action.type === "open_page" || action.type === "find_in_page") && action.url != null) {
+      actionLines.push(theme.fg("dim", `- ${action.type === "open_page" ? "opened" : "searched in"}: ${action.url}`));
+    }
+  }
+  const actionsText = actionLines.length > 0 ? `\n${actionLines.join("\n")}` : "";
+  return new Text(`${answer}${actionsText}`);
+}

package/src/types.ts

@@ -0,0 +1,21 @@
+import type { Static } from "typebox";
+// 工具输入/输出类型：导出 schema 与输入类型，供 isToolCallEventType 类型化与渲染层使用。
+import type { ToolDetails } from "./format.js";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+/** deepseek_web_search 工具参数 schema */
+export const deepseekWebSearchSchema = Type.Object({
+  query: Type.String({ description: "The search query." }),
+  mode: Type.Optional(
+    StringEnum(["answer", "results"] as const, { description: "answer: full synthesized answer with citations; results: compact answer only." }),
+  ),
+  maxResults: Type.Optional(
+    Type.Number({ description: "Hint for the number of sources to cite (informational only)." }),
+  ),
+});
+
+export type DeepSeekWebSearchInput = Static<typeof deepseekWebSearchSchema>;
+
+/** 工具返回的 details 结构（供 TUI 渲染与调试）——由 format.ToolDetails 承担，此处保留别名以维持公共 API */
+export type DeepSeekWebSearchDetails = ToolDetails;