Pi Agent 实践指南

给 Pi 增加一个 deep_search 工具。

它接收：
- query：用户要研究的问题
- depth：检索深度
- maxResults：最多返回多少条候选资料

它输出：
- 结构化搜索结果
- 每条结果的标题、URL、摘要、相关性
- 给模型使用的证据提示

Pi 拿到这些证据后，再由当前模型生成最终结论。

.pi/extensions/deepsearch/
  package.json
  index.ts

export TAVILY_API_KEY=tvly-...

mkdir -p .pi/extensions/deepsearch

{
  "name": "pi-deepsearch-extension",
  "private": true,
  "dependencies": {
    "typebox": "*",
    "@earendil-works/pi-ai": "*",
    "@earendil-works/pi-coding-agent": "*"
  },
  "pi": {
    "extensions": ["./index.ts"]
  }
}

cd .pi/extensions/deepsearch
npm install

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { StringEnum } from "@earendil-works/pi-ai";
import { Type } from "typebox";

type SearchResult = {
  title: string;
  url: string;
  snippet: string;
  score?: number;
};

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "deep_search",
    label: "DeepSearch",
    description: "Search the web for source-backed evidence about a question.",
    promptSnippet: "Research a question with web search and return source-backed evidence.",
    promptGuidelines: [
      "Use deep_search when the user asks for current facts, external sources, comparison, investigation, or source-backed research.",
      "After deep_search returns results, synthesize an answer with citations and clearly separate facts, inference, and uncertainty.",
      "Do not treat deep_search results as final truth; inspect source quality and mention gaps."
    ],
    parameters: Type.Object({
      query: Type.String({
        description: "The research question or search query."
      }),
      depth: Type.Optional(StringEnum(["quick", "normal", "deep"] as const)),
      maxResults: Type.Optional(Type.Number({
        minimum: 3,
        maximum: 10,
        default: 6
      }))
    }),
    async execute(_toolCallId, params, signal) {
      const depth = params.depth ?? "normal";
      const maxResults = params.maxResults ?? 6;
      const results = await searchWeb(params.query, depth, maxResults, signal);

      return {
        content: [
          {
            type: "text",
            text: formatResultsForModel(params.query, results)
          }
        ],
        details: {
          query: params.query,
          depth,
          results
        }
      };
    }
  });
}

async function searchWeb(
  query: string,
  depth: "quick" | "normal" | "deep",
  maxResults: number,
  signal: AbortSignal
): Promise<SearchResult[]> {
  const apiKey = process.env.TAVILY_API_KEY;
  if (!apiKey) {
    throw new Error("Missing TAVILY_API_KEY. Set it before starting pi.");
  }

  const response = await fetch("https://api.tavily.com/search", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: apiKey,
      query,
      search_depth: depth === "quick" ? "basic" : "advanced",
      max_results: maxResults,
      include_answer: false,
      include_raw_content: depth === "deep"
    }),
    signal
  });

  if (!response.ok) {
    throw new Error(`Search failed: ${response.status} ${response.statusText}`);
  }

  const data = await response.json() as {
    results?: Array<{
      title?: string;
      url?: string;
      content?: string;
      score?: number;
    }>;
  };

  return dedupeByUrl((data.results ?? []).map((item) => ({
    title: item.title ?? "Untitled",
    url: item.url ?? "",
    snippet: item.content ?? "",
    score: item.score
  }))).filter((item) => item.url);
}

function dedupeByUrl(results: SearchResult[]): SearchResult[] {
  const seen = new Set<string>();
  const deduped: SearchResult[] = [];

  for (const result of results) {
    const key = normalizeUrl(result.url);
    if (seen.has(key)) continue;
    seen.add(key);
    deduped.push(result);
  }

  return deduped;
}

function normalizeUrl(url: string): string {
  try {
    const parsed = new URL(url);
    parsed.hash = "";
    parsed.searchParams.delete("utm_source");
    parsed.searchParams.delete("utm_medium");
    parsed.searchParams.delete("utm_campaign");
    return parsed.toString();
  } catch {
    return url;
  }
}

function formatResultsForModel(query: string, results: SearchResult[]): string {
  if (results.length === 0) {
    return `DeepSearch found no results for: ${query}`;
  }

  const lines = results.map((result, index) => {
    return [
      `## Source ${index + 1}`,
      `Title: ${result.title}`,
      `URL: ${result.url}`,
      result.score === undefined ? undefined : `Score: ${result.score}`,
      `Snippet: ${result.snippet}`
    ].filter(Boolean).join("\n");
  });

  return [
    `DeepSearch query: ${query}`,
    "",
    "Use these sources as evidence. Cite URLs when making factual claims.",
    "Separate confirmed facts from inference and uncertainty.",
    "",
    ...lines
  ].join("\n\n");
}

export default function (pi: ExtensionAPI) {
  pi.registerCommand("deepsearch", {
    description: "Run a source-backed DeepSearch task",
    handler: async (args, ctx) => {
      const query = String(args ?? "").trim();

      if (!query) {
        ctx.ui.notify("Usage: /deepsearch <question>", "warning");
        return;
      }

      pi.sendUserMessage(
        [
          "请对下面的问题做 DeepSearch。",
          "",
          `问题：${query}`,
          "",
          "要求：",
          "1. 先判断是否需要调用 deep_search。",
          "2. 如果问题较复杂，先拆成 2-4 个子问题分别检索。",
          "3. 最终答案必须包含来源链接。",
          "4. 区分事实、推断和仍不确定的部分。",
          "5. 不要把搜索结果原样堆出来，要给出综合判断。"
        ].join("\n"),
        { deliverAs: "followUp" }
      );
    }
  });

  pi.registerTool({
    // deep_search tool definition...
  });
}

/deepsearch Pi Coding Agent 的 extension 机制适合做哪些能力？

TAVILY_API_KEY=tvly-... pi

TAVILY_API_KEY=tvly-... pi -e ./.pi/extensions/deepsearch/index.ts

/deepsearch Pi Coding Agent 最新版本的 extension 系统支持哪些能力？

promptGuidelines: [
  "Use deep_search to gather evidence, not to produce the final answer.",
  "After deep_search, write a concise research brief with citations.",
  "Prefer official documentation, source code, release notes, and primary sources.",
  "Mention when sources disagree or when the evidence is incomplete."
]

Pi Agent 能不能替代 Claude Code？

function classifySource(url: string): "official" | "source" | "community" | "other" {
  const host = new URL(url).hostname;
  if (host === "pi.dev") return "official";
  if (host === "github.com") return "source";
  if (host.includes("reddit.com")) return "community";
  return "other";
}

fetch_source(url)