# 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 局部关闭严格区分

这套模型能同时解决当前的回显歧义、保存无效、运行时不一致，以及后续工具规模扩张后的可维护性问题。