Local Tools Guide

Local Tools Guide

本技能是本地与内置工具的总入口。目标是先判断任务类型，再选择最小、可靠、可复现的工具路径。

参考文件导航

兼容性

• 环境假设: macOS（Homebrew）、已安装 uv 和 bun、用户 shell 为 zsh
• 限制: 非三工具链（uv/bun/brew）来源的 CLI 只能使用已有入口，禁止通过 curl \| sh、pip --user、npm -g、cargo install 等方式新增安装

触发边界

工具路由

工作流

1. 先分类

• 本地命令先确认工具是否已存在；不要为了试探而安装新包。
• 需要用户 shell 环境、全局工具或 PATH 时，优先使用 zsh -lc 或明确记录 shell 假设。
• 一次性 Python/Node 工具优先用 uvx / bunx，长期复用才考虑全局安装。
• 安装工具只能走 uv tool install、bun add -g 或 brew install；禁止用 curl | sh、npm -g、pip --user、cargo install 等方式绕过这三条工具链。
• 非 uv / bun / brew 来源的已有 CLI 可以使用，但只能按现有入口调用，不负责安装、升级或迁移。
• 本地文档先用可复现转换工具，不要手工复制粘贴内容作为提取结果。
• 信息发现先搜索，不用 web_fetch 代替搜索。
• 如果用户意图命中已配置的 OpenCLI 或 Agent Reach 专用 skill，优先转交对应 skill；本指南只负责识别意图和确认本地入口，不复制其具体操作说明。
• 已有 URL 先核验或提取，不重新搜索，除非用户要求找更多来源。
• 需要登录态、点击、截图、动态加载或真实页面状态时，用 browser-use。
• 编程库/API 文档先走 ctx7，找不到再用定向网页搜索。

2. 再执行

• 独立搜索或多个 URL 核验可以并行。
• 每次降级都要有原因：工具不可用、返回空内容、少于 100 字符、明显是导航/错误页、需要交互或登录态。
• 本地工具命令尽量短、可单独复现；需要中间输出时分步执行。
• 使用浏览器打开网页时，先用 browser-use open <URL>，再读取 state；需要登录态、cookies 或指定 Chrome profile 时，先用 browser-use profile list 确认可用 profile，必要时询问用户选择。
• URL 正文提取中，web_fetch 失败、内容不足或主体缺失后直接使用 browser-use；不要再插入本地 HTML 清洗 CLI 作为中间降级。
• 不把搜索结果伪装成正文；完整正文提取必须走正文提取流程。

工具降级决策树

正文提取降级链

用户提供一个 URL
│
├─→ 步骤 1: web_fetch(url)
│   ├─ 成功（内容完整 ≥100 字符）→ 输出结果 ✓
│   └─ 失败或内容不足 ───────────────┐
│                                    │
└─→ 步骤 2: browser-use eval        │
    ├─ 成功 → 输出结果 ✓
    └─ 失败 → 报告失败原因及已尝试工具 ✗

搜索降级链

用户需要搜索信息
│
├─→ 步骤 1: web_search(query) [Agent 内置]
│   ├─ 成功 → 输出结果 ✓
│   └─ 不可用或结果不足 ──────────────┐
│                                    │
├─→ 步骤 2: ddgs text -q <query>     │
│   ├─ 成功 → 输出结果 ✓
│   └─ 超时/限流/结果不足 ───────────┤
│                                    │
└─→ 步骤 3: browser-use 打开搜索页    │
    ├─ 成功 → 输出结果 ✓
    └─ 失败 → 报告失败原因 ✗

技术文档查询降级链

用户查询编程库/框架/API 文档
│
├─→ 步骤 1: ctx7 library <name> <query>
│   ├─ 成功 → 输出结果 ✓
│   └─ 未找到库或文档 ────────────────┐
│                                    │
├─→ 步骤 2: ctx7 docs <libraryId>    │
│   ├─ 成功 → 输出结果 ✓
│   └─ 失败（最多 3 次尝试）──────────┤
│                                    │
└─→ 步骤 3: web_search 定向官方文档   │
    ├─ 成功 → 提取正文并输出 ✓
    └─ 失败 → 报告失败原因 ✗

3. 最后输出

• 搜索任务：按主题合并结果，标注来源链接和可靠性限制。
• 正文提取：输出标题、URL、提取工具、状态和干净 Markdown 正文。
• 浏览器任务：输出页面状态、完成的交互、截图路径或提取到的数据。
• 失败时：列出已尝试工具、失败原因和下一步可选路径。
• 使用过工具时，最终回复末尾追加工具使用记录。

工具使用记录

如果本轮使用了工具，最终回复末尾按调用顺序追加：

**工具使用记录**

| 顺序 | 工具 | 用途 | 结果 |
| --- | --- | --- | --- |
| 1 | `exec` | 盘点 uv tools | 成功，列出 12 个工具 |
| 2 | `exec` | 检查 Bun 全局包 | 失败：sandbox 限制无法读取 ~/.bun |
| 3 | `web_fetch` | 提取文章正文 | 部分成功：返回 1500 字符，可能缺失代码块 |
| 4 | `browser-use` | 重新提取完整内容 | 成功：返回完整正文 |

结果列填写规范:

• 成功：简要概括获得的结果（如"列出 12 个工具""返回 3200 字符"）
• 部分成功：说明获取到什么，以及缺失什么（如"返回 1500 字符，可能缺失代码块"）
• 失败：说明失败原因（如"sandbox 限制无法读取 ~/.bun""页面返回 403""超时"）

规则:

• 只记录真实调用过的工具。
• 不粘贴冗长输出；必要时概括关键结果。
• 失败要写明失败原因。
• 没有调用工具时，不输出该区块。

可扩展规则

新增工具时优先更新参考文件中的路由表，记录：

• 适用场景
• 优先级位置
• 示例命令或调用方式
• 成功/失败判定
• 降级目标

只有触发边界、核心优先链或输出职责变化时，才修改本文件。