按需调用:`/v3/tools/list` 与 `/v3/tools/call`

文档摘要

按需调用: 与本节摘要:Wiki 和 CodeGraph 即使有几千个页面/符号,也不会撑爆上下文——因为它们不「整库注入」,而是作为「工具」被 Agent 按需调用。本节讲清这套「自发现 + 按需调用」机制:Agent 先用发现有哪些能力,再用读取真正需要的片段。这是「知识不整库注入而是按需调用」这条命题的实现,也是把无限增长的资料塞进有限窗口的唯一解法。一、为什么是「按需调用」而非「整库注入」先理解一个硬约束:知识库(Wiki/CodeGraph)会持续增长,但上下文窗口有限。

按需调用:`/v3/tools/list` 与 `/v3/tools/call`

本节摘要:Wiki 和 CodeGraph 即使有几千个页面/符号,也不会撑爆上下文——因为它们不「整库注入」,而是作为「工具」被 Agent 按需调用。本节讲清这套「自发现 + 按需调用」机制:Agent 先用 /v3/tools/list 发现有哪些能力,再用 /v3/tools/call 读取真正需要的片段。这是「知识不整库注入而是按需调用」这条命题的实现,也是把无限增长的资料塞进有限窗口的唯一解法。

一、为什么是「按需调用」而非「整库注入」

先理解一个硬约束:知识库(Wiki/CodeGraph)会持续增长,但上下文窗口有限。这两个事实冲突,「整库注入」不可行:


整库注入的问题
  Wiki 有 1000 页,CodeGraph 索引 10 万符号
    → 全塞进上下文? 窗口根本装不下
    → 即使装下,99% 与当前问题无关,全是噪音
    
按需调用的解法
  知识库作为「工具」存在,平时不进上下文
    → Agent 遇到具体问题,调用工具取「刚好需要」的那一片
    → 上下文里只有「当下相关的」知识

方式	上下文占用	相关性	可扩展性
整库注入	极高(撑爆)	低(大量无关)	不可扩展
按需调用	极低(只取所需)	高(刚好相关)	无限扩展

关键概念:按需调用本质上是「延迟加载」——知识平时以「工具」形态待命,只有 Agent 判断「现在需要」时才调用取回。这让知识库可以无限增长,而上下文占用始终可控。这是软件工程里「懒加载」思想在记忆系统的应用。

二、两步机制:list 发现,call 取用

按需调用分两步,对应两个接口:


两步机制
  步骤1: /v3/tools/list(发现能力)
    Agent 问:「我有哪些知识工具可用?」
    返回:工具清单
      ├─ wiki_search(搜 Wiki 页面)
      ├─ wiki_read(读某页详情)
      ├─ code_search(搜代码符号)
      ├─ code_callers(查调用关系)
      └─ code_impact(查影响路径)
    
  步骤2: /v3/tools/call(取用片段)
    Agent 判断需要,调用具体工具
    例:code_impact(symbol="authMiddleware")
    返回:该符号的影响范围数据

接口	作用	何时用
`/v3/tools/list`	发现有哪些工具	Agent 进入任务,先了解能力
`/v3/tools/call`	调用某工具取片段	Agent 判断需要某类知识时

这两步的设计逻辑:list 是「自发现」,让 Agent 不必预先知道有什么知识;call 是「按需取」,只取当下需要的一片。合起来实现「知识无限,占用可控」。

三、自发现的价值:Agent 不必预知知识结构

/v3/tools/list 的「自发现」特性很重要——它让 Agent 不必预先知道知识库有什么:


没有自发现(传统方式)
  开发者要预先告诉 Agent:「有 Wiki,要搜就调 wiki_search」
  → 每加一类知识,要改 Agent 的提示/代码
  → 知识类型增长 = Agent 改造成本增长

有自发现(list 接口)
  Agent 自己调 list,看返回的工具清单
  → 新增知识工具(如新 CodeGraph),Agent 自动发现
  → 知识类型增长,Agent 不用改

💡 技巧:自发现让系统「可扩展而不改 Agent」。当你在知识引擎里加了新的知识类型(比如未来加个「API 规范库」),只要把它注册成工具,Agent 通过 list 自动发现并会用——不必改 Agent 代码。这是「开闭原则」在记忆系统的体现:对扩展开放(加工具),对修改关闭(不改 Agent)。

四、按需调用的典型工作流

把两步机制放到一个真实任务里,看 Agent 如何用知识工具工作:


任务:帮用户改 authMiddleware(加一个日志)
  │
  ├─ Agent 先 list,看到有 code_impact 工具
  │
  ├─ Agent 判断:改之前该看影响
  │   → call code_impact(symbol="authMiddleware")
  │   → 返回:影响 12 处,含登录/API/移动端
  │
  ├─ Agent 评估:影响面大,需谨慎
  │   → 告知用户风险,建议加测试
  │
  ├─ 用户同意后,Agent 改代码
  │   → 可能 call code_callers 确认调用点
  │   → 可能 call wiki_read 查编码规范
  │
  └─ 整个过程:上下文里只有「当下查的片段」,不是整个知识库

注意 Agent 不是「一次性把所有工具都 call 一遍」——它根据任务进展,在需要时才 call 对应工具。这种「任务驱动的按需调用」让上下文始终保持「刚好相关」。

五、按需调用与代理层 toolize 策略

按需调用机制与第 8 章代理层的 toolize 注入策略直接相关——toolize 就是「把知识作为工具暴露,让 Agent 按需调用」:


按需调用与 toolize 的关系
  知识引擎:把 Wiki/CodeGraph 注册成 /v3/tools
    ↓
  代理层 injection 的 toolize 策略:
    把这些工具暴露给 Agent(不塞进 system prompt)
    ↓
  Agent 通过 list 发现、call 取用
    
  → toolize 是「按需调用」在代理层的实现

这就是第 8 章会讲的「inject vs toolize」里 toolize 的本质:稳定的、每次都要的(Skill、团队约定)走 inject 塞进 system prompt;易变的、量大的(Wiki、CodeGraph)走 toolize 作为工具按需调用。两者的区分,正是基于「按需调用」更适合易变大量知识的判断。

⚠️ 注意:按需调用不是「免费」——每次 call 都是一次工具调用,有延迟。所以「该 inject 的别 toolize」(如每次都要的团队约定,inject 进 system prompt 更快)。两者的选择是性能与可控性的权衡,第 8 章会详解。

本节要点回顾

按需调用本质:延迟加载——知识平时是工具,用到才取,上下文始终可控。
两步机制:list(自发现有)+ call(按需取),合起来实现「知识无限,占用可控」。
自发现价值:Agent 不必预知知识结构,加新知识类型不用改 Agent——开闭原则。
任务驱动调用:Agent 按任务进展在需要时 call,不是一次全 call——上下文「刚好相关」。
与 toolize 的关系:toolize 是按需调用在代理层的实现,与 inject(稳定内容)分工——第 8 章详解。

下一节看知识如何保持新鲜——Auto-Sync 的 FIFO 队列与 worker pool 机制。

按需调用:`/v3/tools/list` 与 `/v3/tools/call`

文档摘要