298 lines
7.1 KiB
Markdown
298 lines
7.1 KiB
Markdown
# Agent Tool Config Redesign
|
||
|
||
> 日期: 2026-04-18
|
||
> 范围: `packages/frontend/src/modules/agent/views/agent-edit.vue`、`packages/backend/src/modules/netaclaw/service/tool_resolver.ts`、Agent 工具配置数据模型
|
||
|
||
## 1. 背景
|
||
|
||
当前 Agent 工具配置以 `toolsets + disabled` 为核心模型，存在三个直接问题：
|
||
|
||
1. 分类勾选具有“整类全选”语义，不符合实际使用心智。
|
||
2. “禁用”一词容易被误解成全局停用，而不是仅对当前 Agent 关闭。
|
||
3. 前端回显、Prompt 预览、运行时实际工具集并不总是一致。
|
||
|
||
用户的实际诉求是：
|
||
|
||
- 以单个工具勾选为主。
|
||
- 分类只做分组展示，不承担授权语义。
|
||
- 核心工具默认勾选。
|
||
- 工具开关只影响当前 Agent，不影响其他 Agent，也不影响全局工具管理。
|
||
|
||
## 2. 设计目标
|
||
|
||
本次重设计的目标是：
|
||
|
||
1. 将 Agent 工具授权模型改为“单工具授权”。
|
||
2. 保持核心工具默认启用，但允许对当前 Agent 单独关闭。
|
||
3. 明确区分“全局停用”和“当前 Agent 关闭”。
|
||
4. 保证编辑页回显、Prompt 预览、运行时 resolver 使用同一套数据语义。
|
||
5. 为后续 vision/document/browser 等更多工具扩展保留稳定交互模型。
|
||
|
||
## 3. 非目标
|
||
|
||
本次不做：
|
||
|
||
1. 分类级授权。
|
||
2. 工具模板市场或工具组合模板。
|
||
3. 多 Agent 批量复制授权。
|
||
4. 拖拽排序工具。
|
||
5. 前端单页之外的 Tool 管理页大改版。
|
||
|
||
## 4. 核心交互模型
|
||
|
||
### 4.1 授权单位
|
||
|
||
授权单位为“单个工具”。
|
||
|
||
分类只用于：
|
||
|
||
- 分组展示
|
||
- 搜索过滤
|
||
- 数量统计
|
||
- 折叠浏览
|
||
|
||
分类不再支持勾选，不再表示“选择该类下全部工具”。
|
||
|
||
### 4.2 状态模型
|
||
|
||
每个工具在 Agent 编辑页只展示以下 4 种状态之一：
|
||
|
||
1. `默认启用`
|
||
2. `已为当前 Agent 启用`
|
||
3. `已为当前 Agent 关闭`
|
||
4. `全局停用`
|
||
|
||
含义如下：
|
||
|
||
- `默认启用`: 来自核心工具默认策略，不是用户手工显式开启。
|
||
- `已为当前 Agent 启用`: 非核心工具，被当前 Agent 显式加入。
|
||
- `已为当前 Agent 关闭`: 默认可用工具，被当前 Agent 显式关闭。
|
||
- `全局停用`: 来自 Tool 管理页的系统级停用，在 Agent 编辑页只读显示，不可开启。
|
||
|
||
### 4.3 核心工具策略
|
||
|
||
核心工具默认启用。
|
||
|
||
默认启用不代表不可关闭。对当前 Agent 而言：
|
||
|
||
- 新建 Agent 时，核心工具默认显示为启用状态。
|
||
- 编辑 Agent 时，如果未显式覆盖，则显示为 `默认启用`。
|
||
- 用户手动关闭后，状态变为 `已为当前 Agent 关闭`。
|
||
- 用户重新开启后，恢复为 `默认启用`，而不是写入显式 enabled。
|
||
|
||
## 5. 数据模型设计
|
||
|
||
## 5.1 Agent 工具配置结构
|
||
|
||
将 Agent 级工具配置收敛为：
|
||
|
||
```json
|
||
{
|
||
"inheritCoreTools": true,
|
||
"enabled": [],
|
||
"disabled": []
|
||
}
|
||
```
|
||
|
||
字段语义：
|
||
|
||
- `inheritCoreTools`
|
||
- 类型: boolean
|
||
- 默认: true
|
||
- 表示是否继承系统定义的核心工具默认启用集合
|
||
|
||
- `enabled`
|
||
- 类型: string[]
|
||
- 含义: 当前 Agent 显式启用的非默认工具
|
||
|
||
- `disabled`
|
||
- 类型: string[]
|
||
- 含义: 当前 Agent 显式关闭的默认工具或核心工具
|
||
|
||
## 5.2 与现有字段关系
|
||
|
||
现有 `toolsets + tools.disabled` 不再作为主模型使用。
|
||
|
||
兼容策略：
|
||
|
||
1. 读取时：
|
||
- 若新结构存在，则优先使用新结构。
|
||
- 若新结构不存在，则根据旧结构迁移生成前端视图态。
|
||
|
||
2. 保存时：
|
||
- 前端只提交新结构。
|
||
- 后端可在兼容期保留旧字段，但不再将其作为主要运行时输入。
|
||
|
||
## 5.3 旧数据迁移规则
|
||
|
||
旧 Agent 若只有 `toolsets + tools.disabled`：
|
||
|
||
1. 核心工具映射到 `inheritCoreTools=true`
|
||
2. 由旧 `toolsets` 额外带出的非核心工具转为 `enabled`
|
||
3. 原 `tools.disabled` 保留到 `disabled`
|
||
|
||
注意：
|
||
|
||
- 分类级语义只在迁移时使用一次
|
||
- 迁移后页面与运行时都只面向单工具授权模型
|
||
|
||
## 6. 运行时规则
|
||
|
||
resolver 最终工具集计算顺序固定为：
|
||
|
||
1. 取全局启用工具
|
||
2. 若 `inheritCoreTools=true`，加入核心工具集合
|
||
3. 加入 Agent `enabled`
|
||
4. 移除 Agent `disabled`
|
||
5. 再做 capability / scene 过滤
|
||
|
||
这样能保证：
|
||
|
||
- 编辑页展示的状态来源可被解释
|
||
- Prompt 预览可稳定显示最终工具
|
||
- 对话运行时实际工具集与编辑页一致
|
||
|
||
## 7. 前端页面设计
|
||
|
||
## 7.1 页面结构
|
||
|
||
Agent 编辑页中的“工具配置”Tab 拆成三层：
|
||
|
||
### 1. 摘要层
|
||
|
||
展示：
|
||
|
||
- 当前 Agent 最终启用工具数
|
||
- 核心工具数量
|
||
- “仅影响当前 Agent”的说明
|
||
|
||
### 2. 已启用区
|
||
|
||
放在页面上部，用于快速核对当前 Agent 实际可用工具。
|
||
|
||
排序建议：
|
||
|
||
1. 核心工具优先
|
||
2. 显式启用工具其次
|
||
3. 按分类与名称稳定排序
|
||
|
||
### 3. 分类浏览区
|
||
|
||
按分类展示所有工具：
|
||
|
||
- `base`
|
||
- `planning`
|
||
- `interaction`
|
||
- `memory`
|
||
- `skill`
|
||
- `crew`
|
||
- `vision`
|
||
- `document`
|
||
|
||
分类标题仅展示：
|
||
|
||
- 分类名
|
||
- 工具数量
|
||
- 当前已启用数量
|
||
|
||
分类标题不提供授权操作。
|
||
|
||
## 7.2 单工具卡片
|
||
|
||
每个工具卡片展示：
|
||
|
||
- 工具名称
|
||
- 简要描述
|
||
- 分类 tag
|
||
- capability tag
|
||
- `核心` tag（若适用）
|
||
- 状态说明
|
||
- 单个开关
|
||
|
||
开关语义固定为：
|
||
|
||
> 当前 Agent 是否可用该工具
|
||
|
||
不再显示“禁用”按钮。
|
||
|
||
## 7.3 筛选和辅助功能
|
||
|
||
顶部提供轻量筛选：
|
||
|
||
- 搜索
|
||
- 状态筛选：全部 / 已启用 / 已关闭 / 全局停用
|
||
- 仅看核心工具
|
||
|
||
批量操作保留极少量、无歧义功能：
|
||
|
||
- 恢复核心默认
|
||
- 清空额外启用
|
||
- 清空关闭覆盖
|
||
|
||
## 7.4 文案规范
|
||
|
||
避免使用“禁用”作为 Agent 局部动作文案。
|
||
|
||
统一改为：
|
||
|
||
- `对当前 Agent 启用`
|
||
- `对当前 Agent 关闭`
|
||
- `全局停用`
|
||
|
||
这样可以避免与 Tool 管理页的系统级停用混淆。
|
||
|
||
## 8. 后端改造点
|
||
|
||
需要改造的核心点：
|
||
|
||
1. Agent 实体或配置结构中引入新的工具授权字段
|
||
2. `tool_resolver.ts` 改为优先读取新结构
|
||
3. Prompt 预览接口改为返回基于新结构的最终工具集
|
||
4. Agent 保存接口接受新结构并兼容旧数据
|
||
|
||
## 9. 风险与控制
|
||
|
||
### 风险 1: 旧数据与新 UI 不一致
|
||
|
||
控制方式：
|
||
|
||
- 读取时做兼容转换
|
||
- 保存后只落新结构
|
||
|
||
### 风险 2: 前端展示正确但运行时仍按旧逻辑
|
||
|
||
控制方式：
|
||
|
||
- resolver 成为唯一运行时工具集入口
|
||
- 预览接口与运行时共用同一 resolver
|
||
|
||
### 风险 3: 核心工具默认策略再次“前端假勾选、后端不生效”
|
||
|
||
控制方式：
|
||
|
||
- 将“默认启用”写成显式状态语义
|
||
- 后端通过 `inheritCoreTools` 真正表达
|
||
|
||
## 10. 实施顺序
|
||
|
||
建议按以下顺序实现：
|
||
|
||
1. 后端数据模型和 resolver 改造
|
||
2. Prompt 预览与 Agent 保存接口改造
|
||
3. 前端工具配置 UI 重做
|
||
4. 迁移与兼容逻辑验证
|
||
|
||
## 11. 结论
|
||
|
||
本次工具配置重设计不再围绕 `toolset` 展开，而是围绕“单工具授权”展开。
|
||
|
||
最终原则是：
|
||
|
||
- 分类只负责展示
|
||
- 工具才是授权单位
|
||
- 核心工具默认启用
|
||
- 关闭只作用于当前 Agent
|
||
- 全局停用与 Agent 局部关闭严格区分
|
||
|
||
这套模型能同时解决当前的回显歧义、保存无效、运行时不一致，以及后续工具规模扩张后的可维护性问题。
|