Tool

工具定义:名称、模型可见描述、zod 参数 schema、只读 / 并发安全等静态声明与 execute 实现。 工具只产出结构化数据,渲染归表面层;权限判定由调度器在 execute 之前完成。

继承于

• DefinedTool

类型参数

Args

Args = unknown

属性

description

description: string;

模型可见描述(英文)

---

effects?

optional effects?: readonly ("irreversible" | "financial" | "external" | "affects-others")[];

效应声明(应用协议 v1):开发者对本工具副作用性质的 自述——irreversible(不可逆)/ financial(资金流动)/ external (触达外部系统或第三方)/ affects-others(影响其他用户或租户)。 信号不是闸门:只进裁决人语境(<tool> 段)与遥测标签,不参与任何 确定性判定,半径面(F9)定义与本位无关——误报漏报只影响裁决质量,不 制造放行路径。缺席 = 未声明(语境渲染 “(none declared)”)。

---

inputSchema

inputSchema: ZodType<Args>;

参数 schema(zod;经 zod-to-json-schema 或手写 JSON Schema 暴露给模型由网关层处理)

---

isConcurrencySafe

isConcurrencySafe: boolean;

并发安全(false 的工具调度器串行执行)

---

isReadOnly

isReadOnly: boolean;

只读工具可并发、可在 plan 模式放行(声明即契约,调度器强制)

---

name

name: string;

唯一名(进模型 prompt 与权限规则,如 “Read”/“Shell”)

---

selfConcurrency?

optional selfConcurrency?: number;

Q4-24 — 同名自并发组上限(可选):≥2 时,本工具的多个调用可彼此 并发(上限 = 本值,超出按输入序 FIFO 排队),与其他一切工具仍互斥 (组员启动前排空非组员 in-flight,非组员启动前排空组;「写工具执行 期间父侧无并发读写」的既有保证只在组内松动)。缺席/1/非法值 = 现状 独占串行,调度语义字节零漂移。仅对非 (isReadOnly && isConcurrencySafe) 的工具有意义(并发读路径不消费本位)。当前唯一消费方:Task(方案键 taskConcurrency ≥2 时经 TaskToolConfig.concurrency 注入;子代理彼此 隔离——独立 executor/registry/fileReadState,归属由 agent.* 与 cost 事件 的 agentId/toolUseId 键控判别,不依赖「一次一飞」顺序假设)。 Q4-24b:本位允许以 getter 落位(Task 函数配置)——调度器在每次调用 评估时点读取,方案热更新即时生效;静态数字声明语义不变。

---

shortDescription?

optional shortDescription?: string;

模型可见短态描述(英文;一句话 + 参数签名要点)。可选 资产位:装配层分段预算分配器(cli assembly/section-budget.ts)在工具 段预算压力下以短态替换 description 进请求;缺席/门关恒用 description (请求字节与现状逐字节一致)。执行语义与本字段无关。

---

supportsEscalation?

optional supportsEscalation?: boolean;

Q4-13 提权声明位:true = 本工具的调用可携带 escalate: true 请求 沙箱旁路提权(当前仅 Shell)。调度器据此对提权请求实施「同轮一次性 计数」与「gate 放行 → ask」兜底升档(permissions/escalation.ts 单一 事实源;红线 4:提权绝不静默放行)。缺省 undefined = 不参与提权语义。

---

timeoutMs?

optional timeoutMs?: number;

每调用硬超时覆盖(毫秒;缺省用调度器统一值 120s)。 POSITIVE_INFINITY = 免硬超时——仅限以用户注意力为界的交互工具 (AskUser:与权限询问同语义,等多久由用户定),取消链仍可随时终止。

方法

execute()

execute(args, ctx): Promise<ToolResult>;

参数

args

Args

ctx

ToolContext

返回

Promise<ToolResult>

---

mutatedPathsOf()?

optional mutatedPathsOf(args): string[];

文件写改声明位(OPT-13,doc/07 §4.8⑥):返回本次调用将改写的文件 绝对路径集,调度器据此在执行前采集 pre-image(file_checkpoint)。 约定:args 畸形或路径非法时返回 [](工具执行时自会报错);只声明 确定性可知的目标(Shell 等副作用不可静态预知的工具不声明)。

参数

args

unknown

返回

string[]

---

touchedPathsOf()?

optional touchedPathsOf(args): string[];

文件读取触达声明位(与 mutatedPathsOf 同构的只读侧):返回 本次调用将读取的文件绝对路径集。调度器在调用成功后采集(与 mutatedPathsOf 合并)进 ToolExecutionOutcome.touchedFiles,作查询环 压缩后文件重建的触达台账数据源。约定同 mutatedPathsOf:args 畸形或 路径非法返回 [];只声明确定性可知的单文件目标(Glob/Grep 等结果集 不定的工具不声明)。

参数

args

unknown

返回

string[]

이 페이지가 도움이 되었나요?

예아니요