tantingwu/GPU_GUARD_MONOREPO
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
GPU_GUARD_MONOREPO/docs/superpowers/specs/2026-04-18-agent-tool-config-redesign-design.md
陈二狗 cc660d19d1 初始化提交
2026-05-20 21:39:12 +08:00

7.1 KiB
Raw Blame History

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

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