03 工具上下文与权限询问

文档摘要

03 工具上下文与权限询问本节摘要:工具执行时不是「裸跑」的,它会拿到一个上下文(Context)——里面有当前会话、消息、Agent、中止信号,还有一个最重要的「权限询问函数」。本节讲清这个上下文携带了什么、它如何让工具与权限系统联动。理解了本节,你才明白第 4 章的权限三态是怎么「接到」工具执行链上的——原来每次工具执行前,是工具上下文里的询问函数在触发授权。一、工具不是裸跑的第 01 节我们说工具的执行函数「拿到参数干活」。但其实它拿到的不止参数,还有一个「上下文」对象。这个上下文提供了工具执行时需要的「环境信息」和「能力」: 工具函数可以不关心上下文(只看参数),但需要时它能从上下文拿到很多有用的东西。

03 工具上下文与权限询问

本节摘要:工具执行时不是「裸跑」的,它会拿到一个上下文(Context)——里面有当前会话、消息、Agent、中止信号,还有一个最重要的「权限询问函数」。本节讲清这个上下文携带了什么、它如何让工具与权限系统联动。理解了本节,你才明白第 4 章的权限三态是怎么「接到」工具执行链上的——原来每次工具执行前,是工具上下文里的询问函数在触发授权。

一、工具不是裸跑的

第 01 节我们说工具的执行函数「拿到参数干活」。但其实它拿到的不止参数,还有一个「上下文」对象。这个上下文提供了工具执行时需要的「环境信息」和「能力」:


工具执行 = 执行函数(参数, 上下文)
   │
   ├─ 参数:模型传的(如 path: "xxx")
   └─ 上下文:系统给的(会话、Agent、询问函数...)

工具函数可以不关心上下文(只看参数),但需要时它能从上下文拿到很多有用的东西。

二、上下文携带了什么

上下文大致携带这些:

字段	作用
`sessionID`	当前会话 ID(工具知道自己在哪个会话里)
`messageID`	当前消息 ID(定位这次调用)
`agent`	当前 Agent(工具知道是 build/plan/explore 谁在调它)
`abort`	中止信号(用户取消时,工具能感知并停下来)
`messages`	会话历史(某些工具需要看上下文,如 todo)
`metadata()`	取元信息的方法
`ask()`	权限询问函数(最重要,见下文)

💡 上下文的价值:它让工具「知道自己在哪、能做什么」。没有上下文,工具就是个无状态的纯函数;有了上下文,工具能与会话、权限、中止机制联动。

三、`ask()`:权限询问函数

上下文里最重要的就是 ask()——它是工具与第 4 章权限系统的连接点。

回忆第 4 章,权限三态(allow/ask/deny)。当一个工具即将执行,如果权限求解结果是 ask,工具执行链会调用上下文的 ask() 函数,暂停下来等用户授权:


模型请求执行 bash("rm -rf /tmp/old")
   │
   ▼ 权限求解:规则 = ask(bash 有风险)
   │
   ▼ 调用 context.ask("允许执行 rm -rf /tmp/old 吗?")
   │
   ▼ 暂停,界面显示询问
   │
   ├─ 用户允许 ──► ask 返回,继续执行
   └─ 用户拒绝 ──► ask 抛错,工具失败,模型收到反馈

所以「询问」不是凭空发生的——它是工具执行链在权限判定为 ask 时,通过上下文的 ask() 函数触发的。这个函数是工具与权限的桥梁。

四、abort:中止信号

另一个重要字段是 abort——中止信号。它让工具能感知「用户取消了」并优雅停下:


工具正在执行一个长任务(如读大文件)
   │
   ▼ 用户在界面点了「取消」
   │
   ▼ abort 信号触发
   │
   ▼ 工具检查到 abort,提前停止(不硬跑完)

没有 abort,工具会硬跑完(可能很久),用户取消也没用。有了 abort,工具能及时响应取消,提升体验。好的工具实现会定期检查 abort 信号。

五、agent:知道是谁在调

上下文里的 agent 字段让工具知道「是哪个 Agent 在调我」。这有几个用处:

某些工具对不同 Agent 行为不同(如对 explore 更严格只读)。
工具日志能记录「谁调了它」,便于审计。
子 Agent 委派(task 工具)需要知道当前 Agent 才能决定能委派谁。

六、messages:会话历史

某些工具需要看会话历史才能干活。最典型的是 todo 工具——它管理任务清单,需要看之前的对话才知道当前任务状态。上下文的 messages 字段提供了这个能力。

⚠️ 谨慎用 messages:虽然上下文给了会话历史,但工具不该滥用(比如把整个历史读一遍塞进自己的输出)。读历史是为了「理解上下文」,不是为了「复制到输出」——后者会撑爆上下文。

七、上下文与权限的协作:完整链路

把第 4 章权限和本节上下文串起来,看一次完整的「工具调用 + 权限询问」链路:


模型请求工具 X
   │
   ▼ 物化工具(第 02 节注册表)
   │
   ▼ 构造上下文(含 sessionID/agent/ask/abort/...)
   │
   ▼ 参数校验(第 01 节)
   │
   ▼ 权限求解(第 4 章)
   │    ├─ allow ──► 继续
   │    ├─ deny  ──► 阻止
   │    └─ ask   ──► 调 context.ask() 等用户
   │
   ▼ 执行工具函数(带参数 + 上下文)
   │    └─ 函数内可检查 abort、读 messages、记 agent
   │
   ▼ 输出截断(第 01 节)
   │
   ▼ 返回结果给模型

你看,上下文不是孤立的——它嵌在整条工具执行链里,把会话、权限、中止、Agent 信息都串了起来。

八、本节要点回顾

工具执行带上下文:不止参数,还有会话/消息/Agent/abort/ask 等。
上下文让工具有状态:能与会话、权限、中止联动,不是无状态纯函数。
ask() 是权限桥梁:权限判定为 ask 时,执行链调 context.ask() 触发授权。
abort 让工具可中止:用户取消时工具能感知并优雅停下,提升体验。
agent 让工具知来源:不同 Agent 调同一工具可不同行为,日志可审计。
messages 供需要时读:如 todo 读历史理解任务,但别滥用复制到输出。

工具执行链清楚了,下一节讲「输出边界」——工具输出太大时,运行时层怎么防止它撑爆模型上下文。

03 工具上下文与权限询问

文档摘要