GPU_GUARD_MONOREPO/docs/superpowers/specs/2026-04-18-agent-tool-config-redesign-design.md

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 级工具配置收敛为：

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

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