web-search

Files (2)

• SKILL.md
• tools.ts

SKILL.md (first lines)

# Web Search Skill

通过 search-proxy 聚合多家搜索 provider，返回标题、URL 和摘要。

## 后端架构

`http://10.50.1.101:8890/search` — 自建多 provider 聚合服务

| Provider | 月配额 | 优先级 |
|---|---|---|
| Tavily | 1000 | 1 (优先) |
| Brave | 1000 | 2 |
| Jina | 1000 | 3 |
| SearXNG | ∞ | 99 (最后兜底) |

源码在 `services/search-proxy/`，部署在 pve `10.50.1.101:8890` Docker 容器。
排查命令：用当前 runtime 原生 shell 执行 `ssh pve "docker logs search-proxy --tail 30"`

## 工具

**`maxclaw_web_search`** — 搜索互联网

| 参数 | 类型 | 说明 |
|------|------|------|
| `query` | string | 搜索词（必填） |
| `count` | number | 返回结果数，默认 5，最多 10 |
| `country` | string | 地区，如 `CN`、`US` |
| `search_lang` | string | 语言，如 `zh`、`en` |
| `freshness` | enum | 时效：`pd`（24h）/ `pw`（周）/ `pm`（月）/ `py`（年）|

## 使用建议

- 中文内容搜索：加 `search_lang: "zh"`, `country: "CN"`
- 需要最新信息：加 `freshness: "pw"` 或 `"pd"`
- 返回结果包含 title / url / snippet，引用时注明来源

## ⚠️ 配额警告处理

`meta.warning` + `meta.warningLevel` 传达配额/频率告警，看到时**主动调整搜索行为**：

| warningLevel | 含义 | Claw 应做什么 |
|---|---|---|
| `warn`（频率） | 最近 1 分钟搜索 ≥ 10 次 | **立即停止连续搜索**，审视当前任务是否真需要这么多搜索 |
| `warn`（pacing） | 所有按月重置 provider 的总用量已超出月历进度（按当前速度月底会爆） | 减少非必要搜索，让消耗速度回落到 pacing 线下 |
| `critical` | 已降级到 SearXNG（付费 provider 全挂） | 搜索质量将严重下降，向 Max 报告并询问是否继续 |

`meta.fallbackChain` 显示本次实际尝试的 provider 序列，可用于排查为什么被降级。

## ⚠️ 时效性陷阱：不要在 query 里硬编码年份

模型训练数据有截止日期，下意识写"2024"/"2025"作为"最新"的标志，这会让搜索引擎把当前年份的最新结果挤出去。

**正确做法**：
- **优先用 `freshness` 参数**（`pd`/`pw`/`pm`/`py`）让搜索引擎自己按时间排序
- 必须带年份时，先用 `get_current_time` 确认当前年份
- 调研类查询（"state of the art"、"benchmark"、"latest"）一律加 `freshness: "pm"` 或 `"py"`

**反例**：query=`"agent memory 2025 state of the art"` → 漏掉所有 2026 内容
**正例**：query=`"agent memory state of the art benchmark"`, `freshness: "pm"` → 拿到最新

From maxesisn/maxclaw-oss, MIT.

More from maxesisn/maxclaw-oss