工具管理 ★
一句话：工具是智能体在对话里能调用的一个个能力；本页两个页签——内置工具（平台代码声明，只能改展示与分组等运维旋钮）与自定义工具（把一个数据接口包装成工具）。
功能在哪
- 菜单路径：AI → AI 助手 → 工具管理
- 地址栏路由：
/ai/agent/tooldef - 主要权限：
agent:tool-def:query（维护 / 新增 / 删除等按钮另受对应写权限控制）
界面认识
内置工具页签：代码声明的能力清单
| 区域 | 作用 | 常用操作 |
|---|---|---|
| 筛选区 | 关键字 / 分组 / 状态 | 「搜索」「重置」「刷新」 |
| 列表 | 序号 / 展示名 / 工具名 / 分组 / 风险等级 / 所需权限（空 = 登录即可）/ 状态 / 维护 / 操作 | 行内「维护」「恢复默认」 |
- 「风险等级」列若带警告角标，表示这一项被租户维护过、与代码声明值不同；
- 「状态」列只是标签、没有快捷开关——内置工具的下线靠代码发布，不靠界面点选。
维护面板：改运维旋钮，每项下挂「代码默认」
行内「维护」打开页内面板（页头「返回」+ 标题「维护内置工具 · {工具名}」，页脚「取 消 / 保存并生效」）：
可维护项：展示名 / 说明 / 分组 / 风险等级 / 所需权限 / 启用 / 参数说明，每项下方都有「代码默认：…」对照行；改完「保存并生效」立即生效、无需重启。「恢复默认」= 删掉覆盖行、生效值退回代码声明。
风险等级改了只改界面标注——运行期各道闸读的是代码声明值
维护后的「启用状态」与「权限串」网关读生效值；但风险等级的全部运行期闸（工作流 DSL 校验、Planner 工具目录、只读限制、发布判定、沙箱 mock 判定、变更清单）读的都是代码里的声明值，生效风险值只剩界面在读。把风险调低不会让工具从确认流程里「消失」。
放松安全约束要二次确认，确认后落审计
把风险调低、把权限删少这类「放松」提交时，会再弹一层确认（标题「本次维护会放松安全约束」，页脚「再看看 / 我已知晓上述后果，确认放松并保存」）。不确认则一个字都不落库；确认后除覆盖行外还会插一行审计记录（谁在什么时候把什么从 X 改成 Y），并留 warn 日志。
自定义工具页签：把数据接口包装成工具
| 区域 | 作用 | 常用操作 |
|---|---|---|
| 筛选区 | 工具键 / 分组 / 状态 | 「搜索」「重置」「新增」 |
| 列表 | 序号 / 工具键 / 展示名 / 关联数据接口 / 执行方式（只读查询 / 全能力执行）/ 分组 / 风险等级 / 状态（开关）/ 创建时间 / 操作 | 行内「查看」「编辑」「删除」 |
自定义工具编辑面板
点「新增 / 编辑」进入页内面板（「返回 / 取 消 / 保 存」），面板顶部信息条原话：「自定义工具 = 把一个接口包装成 AI 能直接调用的工具。接口的地址/SQL/鉴权/租户隔离 在『基础设施 → 数据管理 → 接口管理』里维护，这里只决定用哪个接口、怎么执行、需要什么权限。」
| 字段 | 要点 |
|---|---|
| 工具键 | 报错时不可改，提示原话：「模型按它调用、流程节点按它引用，改键等于换一个工具，故报错时不可改。」 |
| 展示名 / 工具说明 | 说明留空时「模型就只能靠工具键猜用途，容易选错或反复试」 |
| 分组 | 候选池与列表的归类标签 |
| 风险等级 | 只读 / 中风险等；「中风险及以上会先走 Plan 让用户确认再执行」 |
| 关联数据接口 | 从接口管理已治理的接口里选（标注 SQL 查询 · 内部等） |
| 执行方式 | 「只读查询」：只能挑不含写操作的接口，安全默认；「全能力执行」：可写数据，需额外权限且默认进 Plan 确认 |
| 接口入参 | 子表展示参数名 / 含义 / 类型 / 必填 / 默认值；「模型会照这份定义拼参数；下面的『参数说明』留空时，后端按它自动生成。」 |
| 所需权限 | 权限串；「留空表示任何登录用户都能让 AI 调这把工具。」 |
| 参数说明 | JSON Schema 文本；「这段文字进模型提示词，是模型知道该传哪些键的唯一来源。自动生成后不会跟随接口变更。」 |
| 启用 | 开关；「停用后网关直接拒绝调用，但流程节点里的引用还在。」 |
常用操作
维护内置工具并生效
「维护」→ 改展示名 / 分组等 → 「保存并生效」。只想改个显示名字也走这条路径；改完列表即时反映，被改过的行风险列挂警告角标。
恢复默认
行内「恢复默认」删掉覆盖行，展示名 / 风险 / 权限等全部退回代码声明值；没有覆盖行时点了也静默成功。
新增 / 停用 / 删除自定义工具
「新增」进面板选接口、定执行方式后「保 存」即上架；列表「状态」开关可临时停用（网关拒绝调用，但工作流里已引用它的节点不会自动清理）；「删除」下架这把工具。
视角对照
| 视角 | 看到什么 |
|---|---|
租户管理员 docadmin | 两个页签全量 + 维护 / 恢复默认 / 自定义增删改 |
业务角色（如 salesman01） | 角色未授 agent:tool-def:query 时看不到本菜单；工具对他们透明地存在于助手对话里 |
进阶
- 内置与自定义的区别：内置是代码工具（执行体在代码里），界面只给运维旋钮；自定义是配置工具（执行体是数据接口），整份可在界面增删改；
- 「执行方式」决定安全姿态：只读查询进自主路径，全能力执行默认进 Plan 确认——给写接口包装工具时别图省事选只读；
- 参数说明是与模型的契约：接口加字段后记得同步这份 JSON，否则模型不知道新键存在；
- 智能体编辑器里能绑的只有只读工具；中风险以上的写能力要靠流程编排的工具节点或 Plan 确认路径。
常见问题
Q：内置工具为什么没有启用 / 停用开关？ A：内置工具的下线靠代码发布；界面只给展示名 / 分组等运维旋钮，状态列只是标签。
Q：维护里把风险等级调低，工具就会免确认执行吗？ A：不会。运行期各道闸读代码声明的风险等级，生效风险值只剩界面在读（见警告提示）。
Q：自定义工具选错接口 / 接口改了怎么办？ A：接口本身的地址 / SQL / 鉴权在接口管理里改；工具侧只需确认执行方式与参数说明是否仍匹配。
Q：停用一把自定义工具，引用它的工作流会怎样？ A：网关直接拒绝调用，但流程节点里的引用还在——跑到的节点会失败，停用前先看引用面。
Q：警告角标是什么意思？ A：该行存在租户覆盖、与代码声明值不同；「恢复默认」可消除。
相关页面
- 接口管理 ★：自定义工具的执行体来源；
- 智能体管理：工具的消费方（编辑器工具列）；
- 助手配置：已注册工具的只读总览；
- 让 AI 助手安全读写业务数据：风险等级与需确认标记在对话里的实际作用。