defineTool 的 readOnly 到底管什么？业务工具接入的三个边界

把订单查询函数注册成智能体工具时readOnly 可以参与运行权限判断但它不是只读数据库连接也不是租户数据隔离。接入 Tansr 的 defineTool应该把参数契约、调用许可和业务授权分开理解。这三个边界分别回答传进来的参数是否符合声明这次工具调用是否允许执行当前用户是否有权访问目标数据。任何一个回答都不能自动替代另两个。参数契约模型看见什么handler 收到什么defineTool 将工具名称、说明、参数声明和业务 handler 组合起来注册结果加入 tools.custom。参数可通过 parameters 描述也可直接提供 schema两者不能同时指定。handler 接收到的参数经过 schema 校验这是把不确定的模型输入送入业务函数之前的一道约束。官方 API 入口但结构合法不等于业务合法。例如“订单编号是字符串”只描述数据形状没有证明这笔订单属于当前用户也没有证明订单还处于可修改状态。金额、枚举和时间等格式约束可以在契约中表达资源归属与实时业务条件仍应在可信执行端判断。查询工具应让模型提供关键词、筛选条件等任务参数。已验证的用户和租户身份由应用上下文绑定避免把任意 userId 或 tenantId 当成模型可自由选择的授权范围。readOnly效应声明不会约束函数实现Tansr 的工具声明允许设置 readOnly缺省为 false。该声明参与权限判定但不承诺默认免询也不承诺工具可以并发执行显式收紧的规则仍需遵守。假设某个 handler 名叫“查询订单”实际却会顺手修改订单状态。把它声明成只读并不会阻止那次写入。应先厘清函数真实副作用再据实声明如果查询必须伴随业务写入就应把这种影响纳入设计而不是通过命名或声明隐藏它。数据库账号、网络访问和操作系统权限属于另外的执行边界。readOnly 不会自动为这些资源创建隔离环境。平台能力开关同样不替代业务服务对数据范围的授权。工具选择与能力配置结果契约错误能回到会话不等于适合公开defineTool 会把 handler 返回值归一为工具结果handler 抛出的错误可以形成带 message 的结构化错误让运行链继续处理失败。这意味着业务实现需要关心“错误里写了什么”。数据库连接串、内部服务地址、完整查询语句或客户资料都不应因为异常被直接交给模型或显示给用户。对外工具错误宜只保留处理任务所需的信息内部诊断则留在有访问控制的日志中。结果字段也应有边界。查询没有记录、查询失败和无权访问应由业务层明确处理不能一律返回空数组让模型猜原因。写操作返回超时后也不能直接重试并假定前一次没有生效幂等和结果核对需要由业务系统承担。自定义工具之外还装配了什么只准备使用业务函数时别把“没有列内置工具”理解为“不提供内置工具”。Tansr 的工具装配区分省略 builtin 与显式空数组空数组选择零内置省略时会按能力配置装配可用范围。自定义工具及显式 MCP 材料需要分别判断空内置列表不是全局禁用开关。在已有 Node.js 服务或 Electron 主进程中需要把业务函数放进多轮工具调用链、复用会话与权限机制时可以评估 tansr/sdk。只做一次固定查询加文本改写或者已有运行链已经满足需求时不必为了注册一个函数而整体换栈。下一步应对照官方工具示例和应用装配说明逐项核对函数参数、真实副作用、授权上下文和错误输出再进入具体接入实现。