# Pi：DeepSeek Search（`web_search`）

> 本文件为 **@suwenguang/pi-kb 自有口径**。本包已 bundled [`pi-deepseek-search`](https://www.npmjs.com/package/pi-deepseek-search)，安装后注册工具 `web_search`（DeepSeek 服务端 `web_search_20260209`）。由 SKILL.md「DeepSeek Search」一节引用。

## 1. 能力边界

| 项 | 说明 |
|----|------|
| 工具名 | `web_search` |
| 用途 | 实时/外部事实：官方文档、API 变更、版本说明、行业惯例、竞品公开信息 |
| 不替代 | CodeGraph（代码事实）、知识库（业务真相）、用户确认（产品意图） |
| 鉴权 | 复用 Pi 已配置的 DeepSeek API Key；**无额外**搜索厂商 Key |
| 模型 | 搜索请求走 DeepSeek Anthropic 兼容端；默认 `deepseek-v4-flash` |

**与 CodeGraph / 知识库分工**

1. **仓内代码现状** → CodeGraph（硬门禁阶段）  
2. **本仓业务语义** → `knowledge/`  
3. **仓外/时效信息** → `web_search`  
4. 三者冲突时：代码与知识库优先；外网结论须带出处链接，不得冒充已落地实现。

## 2. 配置引导（必做一次）

装好 `@suwenguang/pi-kb` 后，若会话里**没有** `web_search` 工具，按下列顺序排查：

### 2.1 凭证（必需）

任选其一：

1. Pi 内执行 `/login`，选择 **DeepSeek**，完成登录；或  
2. 环境变量：`export DEEPSEEK_API_KEY=sk-...`（[申请地址](https://platform.deepseek.com/api_keys)）

扩展在 `session_start` 时探测 Key；**无 Key 则不注册** `web_search`（静默跳过）。

### 2.2 生效

```bash
pi update npm:@suwenguang/pi-kb   # 或本地 -l 重装
# 然后 /reload 或新开会话
```

确认工具列表出现 `web_search`。也可执行斜杠命令 `/kb-deepseek-search-setup` 查看本机引导摘要。

### 2.3 可选环境变量

| 变量 | 默认 | 说明 |
|------|------|------|
| `DEEPSEEK_SEARCH_MODEL` | `deepseek-v4-flash` | 搜索侧模型；可改为 `deepseek-v4-pro`（更强、更贵） |
| `DEEPSEEK_API_KEY` | — | 未走 `/login` 时的 Key |
| `ANTHROPIC_AUTH_TOKEN` | — | 兼容 Claude Code 风格转发时的备用 Key |

### 2.4 常见失败

| 现象 | 处理 |
|------|------|
| 无 `web_search` | 补 Key → `/reload`；确认本包已 bundled 扩展（勿只装旧版） |
| `Search failed: … API …` | 检查余额/网络；代理超时可加大本机出口或稍后重试 |
| 结果无链接 | 回复用户时仍须用 markdown 链接列出工具返回的 Sources；禁止丢出处 |
| 与仓内实现矛盾 | 以 CodeGraph + 知识库为准，外网仅作参考并标注 |

## 3. 最佳实践（主 Agent / 子 Agent 必遵）

### 3.1 何时调用

**应该搜**

- 官方文档、changelog、迁移指南、弃用说明  
- 第三方 SDK/协议的**当前**推荐用法（版本敏感）  
- 公开竞品/行业模式（写入 PRD/设计时须标注「外部参考」）  
- `/kb-evolve` 对照外部 Agent/工具惯例（不替代 Gitee Issue / EvoMap）

**不要搜**

- 本仓库符号、调用链、影响面（用 CodeGraph）  
- 已在 `knowledge/` 写清的业务规则（先读索引）  
- 用户未确认的产品口径（先问用户）  
- 密钥、内网 URL、未公开规格

### 3.2 查询写法

1. **具体**：含产品名 + 主题 + 版本/年份关键词（如 `DeepSeek API web_search_20260209 anthropic 2026`）。  
2. **拆角度**：同一议题 2–4 次搜索（官方文档 / 迁移 / 实践坑），勿一次超宽 query。  
3. **域名收敛**（可选参数）：  
   - `allowed_domains`：只信官方站（如 `api-docs.deepseek.com`、`docs.github.com`）  
   - `blocked_domains`：排除 SEO/聚合垃圾站  
   - 二者**不可同用**  
4. **时效**：版本/价格/限额类问题在 query 中带年份或 `changelog`。

### 3.3 结果使用

1. **必须引用**：对用户或变更文档转述时，用 markdown 超链接保留 Sources；禁止只写「网上说」。  
2. **交叉验证**：关键结论至少对照 1 个官方/一手来源；冲突则并列并标明不确定。  
3. **落盘口径**：  
   - `01-proposal`：外部参考单独小节，不写成已定产品需求  
   - `02-design`：外网 API 约束写入「外部依赖/假设」，并与 CodeGraph 现状对照  
   - 知识库：仅在用户确认或 archive 同步后写入业务域正文  
4. **失败降级**：`web_search` 不可用或报错 → 声明「未完成外网核对」，继续用知识库/CodeGraph；**不阻断**硬门禁（除非该步骤明确依赖外网且用户要求）。

### 3.4 子 Agent 派发

| 工种 | `tools` 须含 | 典型场景 |
|------|--------------|----------|
| **kb-scribe** | `web_search` | propose/design 需行业/官方产品约束时 |
| **kb-inspector** | `web_search` | explore/evolve 对照外部惯例 |
| **kb-builder** | `web_search` | 实现时查官方 API/SDK 细节（仍以任务块为准） |
| **kb-reviewer** | `web_search` | 核对弃用 API、安全公告（可选） |
| **kb-librarian** | `web_search` | sync 需核实公开文档表述时（慎用，优先仓内） |

派发 prompt 应写明：

```text
需要仓外/时效信息时调用 web_search；query 要具体；优先 allowed_domains 指向官方站；
回复与落盘须带 Sources 链接；仓内事实仍用 CodeGraph + knowledge。
细则：skills/kb-workflow/references/kb-deepseek-search.md
```

主会话若工具不可用：先引导用户完成本文 §2，再重派子 Agent；禁止用臆测填充外网事实。

## 4. 与其他网络能力

| 能力 | 用途 |
|------|------|
| DeepSeek `web_search`（本文件） | 通用外网检索 + 带源摘要 |
| EvoMap（`kb-evomap.md`） | Agent 网络 Gene/Capsule，**默认关闭** |
| CodeGraph MCP | 仓内代码图，非外网 |

三者互补，勿混用名称或互相替代。