Tools API

列出可用工具

GET /api/tools

POST /api/tools/:name/execute

{
  "parameters": {
    "url": "https://example.com"
  }
}

工具	说明
`browser`	网页浏览与抓取
`file_system`	文件读写
`terminal`	Shell 命令执行
`code_execute`	沙箱内代码执行
`grep_tool`	Ripgrep 正则内容搜索（三档：ripgrep → mmap → Python），路径分组密集化输出（≥5 匹配时自动去冗余路径，省 18-39% Token），ReDoS 防护，非代码文件自动截断
`glob_tool`	工作区内文件路径模式搜索
`@codebase` mention	轻量工作区文件/扩展名概览，注入用户消息（配合 grep/glob 探索代码）
`web_search`	多引擎搜索 + BM25/Reranker 过滤 — 返回清洗、去重片段
`render_ui`	对话内声明式 UI（23 种 A2UI 组件）。Turn1 ~223 tok；完整 props 见 `.agent/docs/A2UI_REFERENCE.md`（启用时自动 seed）。未知 type fail-closed
`update_ui_data`	增量 `data_update` SSE，用于进度条/指标/任务列表等长生命周期面板。`data` 模型深合并——嵌套字段更新不 wipe 兄弟键。与 `render_ui` 同组挂载（开启交互式 UI 时可用）
`todo_write`	多步骤目标的结构化任务规划。硬性约束 MAX_TODOS=20 防止过度规划；单一 `in_progress` 并发限制保持执行聚焦。违规自动纠正并反馈 LLM。通过 Planning 开关按需启用，或在续聊时检测到已有 todos 自动启用

场景	默认启用	按需开启
普通对话	`web_search` + `memory`	—
编码 / 文件	勾选 file_ops → `glob_tool` + `grep_tool` + file_* 立即挂载（与 Claude Code 同款 eager，非 discover）	`code_execute`（bash）
MCP / 已绑定技能	—	`discover_capability_tool` → `skill_select_tool` 搜已绑定库（`<BoundSkills>`）
外部技能市场	—	`skill_discovery_tool` 从 GitHub/skills.sh 安装新技能；Settings「发现」Tab 亦可浏览
Skill 质量清理	WebUI Curator 一键 sweep	—

通过 MCP 连接的外部工具与内置工具一并注册。MCP 工具名内部前缀为 mcp__{server}__{tool} 以隔离命名空间 — API 接受前缀名与原始名。

POST /api/tools/mcp__github__search_repos/execute

连接工具数量多的 MCP 服务时，系统自动选择最优路由策略以最小化 token 消耗，同时保留完整的工具访问能力：

路由	条件	行为	用户体验
Direct	服务工具数 ≤ 阈值且在总预算内	完整 schema 预加载	零延迟调用
PTC / Skill	服务工具数 > 阈值或超出总预算	封装为 Skill（`skill_search` → `skill_select` → PTC）	通过技能搜索按需发现

连接 50+ 工具的 MCP 服务不会撑大 Turn1 prompt — 大服务降级为 Skill 按需发现。Direct 工具在 UI 显示真实工具名。

安全规则（ALLOW/ASK/DENY）对 Direct 与 Skill/PTC 路径均生效。针对 mcp__gmail__send_email 的 DENY 规则无法通过 Skill 路径绕过。

可在 MCP 服务配置中用 tool_include / tool_exclude 按 Agent 过滤：

{
  "tool_include": ["search_repos", "get_issue"],
  "tool_exclude": ["delete_repo"]
}