第三章　工具体系

本章覆盖第 9–13 章：先总览工具体系，再分述智能编程工具与安全分析工具，随后是外部工具服务的接入方式，以及贯穿所有工具的权限与审批机制。

第九节 工具体系总览

工具（Tool）是 AI 在你电脑上"动手"的载体。

9.1 三类工具

• 智能编程工具：读写文件、跑命令、版本控制、查找等（详见第十节）。
• 安全分析工具：哈希、字符串、IOC、可执行格式解析、反汇编、规则匹配、流量元数据等（详见第十一节）。
• 外部工具服务：连接外部系统的工具，如 Notion、内部 API、私有知识库等（详见第十二节）。

9.2 工具开关

每个工具都可以设置为：

• 启用：直接放行。
• 询问：每次调用前弹窗审批。
• 禁用：直接拒绝。

入口在输入区模式滑块旁的齿轮（智能体管理器）→「配置工具」Tab，可按工作模式独立配置。三态真实约束运行：「禁用」在主代理与子代理两侧一并生效；「询问」接入实际确认流程，调用前暂停等你批准；卸载插件或外部工具服务时会一并清理残留的工具配置，盘上配置与实际可用工具保持一致。

工具列表更稳：工具列表拉取失败时自动退避重试，多次重试仍失败才提示；兜底工具表与内置工具同源生成，不会莫名少一截。

9.2.1 工具分类延迟加载（默认开启）

工具总数已过百，若每轮都把全部工具描述发给模型，既占上下文又拖慢响应。因此默认只携带常用的一小部分（二十余个），其余按分类在需要时才加载。

• 常驻分类：文件读写与搜索、命令执行、工具自省、子任务委派与待办规划 —— 这些几乎每轮都要用。
• 按需加载的分类（16 类）：代码理解、git、安全分析、威胁情报、SBOM、外部工具服务、联网检索、技能、测试、lint、SAST、插件市场、插件管理、GitHub、系统信息、时间。
• 两种加载方式：你的提问里出现相关词汇时自动预加载对应分类；助手也可以主动调用 tools.load 点名加载。中途新连上的外部工具服务会自动放行。
• 助手知道工具表是不全的：系统提示词里会说明这一点并给出分类目录，助手不会因为"表里没有"就认定某项能力不存在；查询自身可用工具时，返回结果也会提示"看不见 ≠ 不存在，可以先加载"。

开关：智能体管理器 →「配置工具」Tab →「工具分类延迟加载」。关掉后所有工具恒常驻。当可用工具本就不多（不超过 32 个）时，系统会直接整表放行，不做延迟加载。

若某个外部工具服务你用得很频繁，可以在同一面板里单独为它关闭延迟加载，让它的工具始终可用 — 见 §12.4。

9.3 工具命名空间

外部工具服务暴露的工具会被自动加上前缀（例如 notion.*），与内置工具区分，互不冲突。

9.4 工具调用的可视化

每一次工具调用都会以可折叠卡片形式显示在消息流中，包含：

• 工具名 + 入参摘要
• 执行耗时
• 结果（成功 / 失败 / 截断）

你可以独立查看每个工具调用的细节，便于审计与回溯。

9.4.1 Hook 执行过程可见

每次钩子（hook）执行都会在对话流里出现一条系统消息，渲染成类似工具调用的可折叠条（内容按 Markdown 显示），方便确认钩子到底跑没跑、跑了什么、是否影响了下一步动作 — 不再是黑盒。

9.4.1.1 工具执行空闲超时（默认 10 分钟）

给工具执行加了「空闲超时」兜底：某个工具或子任务长时间没有任何进展（没有 stream 输出 / 状态变化）时会被安全收尾，不再让整轮一直挂着干等。

• 触发条件：连续空闲 ≥ 默认 10 分钟。正常的长任务只要还在持续产出就不受影响。
• 豁免：子 Agent 家族单独走 §15.2.1 的空闲窗口 + 绝对兜底，不被这道 10 分钟空闲超时误杀。

9.4.1.2 重复调用提醒（疑似空转）

助手偶尔会陷入"用同样的参数把同一个工具反复调用"的循环 —— 它一直在动，所以空闲超时抓不到，但其实毫无进展，额度却在持续消耗。

• 连续 3 次同参调用同一工具即在工具结果里提示助手，请它换个思路；次数继续增加会逐级加重措辞。
• 会话列表上标记「疑似空转」，悬停可见已重复的次数与工具名；侧边栏与顶部标签页两种布局都会标记。同时发出通知，即使你切到别的会话也能第一时间发现。
• 重启应用后标记依然保留，不会因为重启而漏掉；等你在该会话发出新的一条消息后自动清除。
• 轮询类工具（等待子任务、拉取命令输出等）本就需要反复调用，不在此列。

9.4.2 轨迹面板（Trace）

会话顶部的统计气泡（StatsPopover）里和原「Stats」面板并列新增了 「轨迹」（Trace）面板：把 AI 一次运行里调用了哪些工具、按什么顺序、各自的输入输出与耗时摊开成时间线，方便回看它到底怎么一步步把活做完的，也方便排查「哪步走偏 / 烧在哪」。

每个步骤显示：

• 序号 / 角色 / 类型 / 来源 / 工具名
• 耗时、prompt / completion / total token 数、模型、finish reason
• 是否成功 / 错误信息 / 内容预览

顶部聚合卡显示这一次运行的：总步数、assistant 轮数、工具调用次数 / 失败数、错误数、门禁注入次数、token 用量、工具总耗时、墙钟时长、用到的模型清单；下面还有工具维度的统计表（每个工具的调用数 / 失败数 / P50 / P95 / 最长耗时）。

数据来自会话 JSONL 的服务端聚合（GetSessionTrace），按需打开 popover 时加载一次，不做实时轮询。

时间线步骤可点击跳转：点轨迹时间线上的某一步，会直接跳到消息流中对应的位置并定位过去，回看「哪步走偏 / 烧在哪」更方便。

9.5 让助手自己配置 MCP 服务

除了在设置面板里手动添加外部服务，助手还可以在对话里直接帮你配置 MCP server。AVL Code 提供 9 个 mcp.* 工具，常配合内置 mcp-admin 助手使用：

两步制（dry-run）：写类工具（add / remove / toggle / import）必须显式传 confirm=true 才会真正落配置；首次调用默认返回 dry-run 预览（完整命令行、路由、默认后端变更、冲突清单）让你审完再确认。这是没有 PreToolUse defer hook 时的兜底闸门 — LLM 单步不可直接做破坏。

密钥脱敏：所有读类工具返回的 authToken 一律只显示尾 4 位（其余字符以星号占位），环境变量值整体打码，避免在对话流里泄露凭证。

典型对话：

「帮我把 mcp-trends-hub@1.6.0 接进来。」

助手 → 调 mcp.add_server（dry-run）→ 返回预览 → 你确认 → 助手再调 mcp.add_server(confirm=true) → 落配置 → 用 mcp.test_server 真握手探活 → 报告 21 个 trending 工具可用。