Fix-System-Agent：Agent 工具注册元模型与插件热加载机制设计

背景痛点

当前项目中工具的注册、描述、参数定义大多硬编码在代码或静态 JSON 配置里，在实际运维场景下暴露不少问题：

1. 新增、修改、下线工具都需要修改代码、重启 Agent 服务，变更链路重、上线周期长；
2. 工具能力描述、参数约束、权限标签、风险等级分散在多处，没有统一的元信息规范，语义校验、降级、幂等模块很难统一读取规则；
3. 第三方脚本、自研运维工具、外部 API 接入格式不统一，有的是 Shell、有的是 HTTP、有的是自定义二进制，适配代码碎片化；
4. 工具版本无法管理，同一工具多版本并行测试、灰度切换困难；
5. LLM 拿到的工具描述文本由人工随意编写，容易出现描述歧义，导致模型误调用、传错参数。

我们希望把工具本身和 Agent 核心调度逻辑解耦：Agent 只负责读取标准化元模型，插件按需加载，做到不重启服务即可扩缩工具集。

核心设计思路

定义一套统一的工具元模型（Tool Meta Schema），所有工具以插件包形式组织，由独立的插件管理器负责扫描、校验、热加载、版本管理、生命周期管控。
Agent 调度层、语义校验层、幂等去重层、证据链模块全部消费这套标准元数据，不再单独写适配逻辑。

1. 工具元模型核心结构（简化 Schema）

tool_id: "service.restart"
version: "1.2.0"
name: "服务重启工具"
description: "重启指定命名空间下的目标服务，属于变更类高危操作"
category: "operation"
risk_level: "high" # low / medium / high / critical
operate_type: "write" # read / write / stream
author: "ops-team"
tags: ["k8s", "service", "restart"]
parameters:
  - name: "namespace"
    type: "string"
    required: true
    description: "K8s命名空间"
    semantic_rule: ["namespace-format"]
  - name: "service_name"
    type: "string"
    required: true
    description: "服务名称"
executor:
  type: "http" # http / shell / binary / grpc
  config:
    endpoint: "/api/ops/restart"
    method: "POST"
limits:
  max_timeout: 30
  concurrency: 2
  session_allow_once: true # 和幂等层联动，高风险工具单会话仅允许执行一次
depends_on: []
deprecated: false

元模型同时承载两类信息：

• 供 LLM 使用：name、description、参数说明，作为 Function Calling 的描述源；
• 供系统内部模块使用：风险等级、类型、超时、并发、语义校验规则、幂等约束。

2. 插件包规范

单个工具插件是一个独立目录包，结构：

plugins/
└── service_restart/
    ├── meta.yaml       # 上面的元模型定义（必填）
    ├── run.sh          # 执行脚本（executor=shell时使用，可选）
    ├── readme.md       # 开发者文档
    └── test_cases/     # 参数测试用例，用于插件加载时自检

支持本地目录插件、Git 远端插件包两种分发方式。

3. 热加载流程

插件管理器独立运行，和 Agent 主进程解耦，流程如下：

1. 定时扫描插件目录 / 监听配置中心变更事件；
2. 读取 meta.yaml，做 Schema 合法性校验；
3. 执行内置自检用例：参数校验、连通性探测、权限预检查；自检失败标记为不可用，不接入调度；
4. 成功后写入内存工具注册表，并同步到持久化存储；
5. 向 Agent 调度网关推送工具列表变更事件；网关自动刷新给 LLM 的 function 列表，无需重启 Agent；
6. 下线/版本切换：标记旧版本 deprecated，支持灰度流量逐步切到新版本。

热加载不是简单“覆盖”，而是版本并存。会话会绑定工具版本号，保证一次排障会话全程使用同一版本工具，避免中途元信息突变导致异常。

4. 和已有模块联动

1. 参数语义校验层：直接读取 semantic_rule 字段，自动绑定校验规则；
2. 幂等&去重层：读取 operate_type、session_allow_once 配置，自动启用对应去重策略；
3. 失败分类与自动降级：读取 risk_level，高危工具失败时触发更保守的降级策略（禁止自动重试）；
4. 证据链：每次工具调用记录 tool_version，方便事后审计、复现当时的工具定义；
5. 基线对比模块：工具元信息变更会打上标记，基线计算时区分“数据变化”和“工具定义变化”，减少误告警。

5. 权限与隔离设计

• 增加工具白名单：不同 Agent 实例、不同会话分组可以配置可访问工具集合；
• 高危工具（critical）额外增加人工确认钩子，元模型里可开启 need_confirm: true；
• Shell / binary 类型插件执行时做沙箱隔离，限制文件读写、系统调用范围。

工程权衡

1. 热加载一致性风险：正在运行中的旧会话不强制刷新工具定义，只在新建会话加载最新版本；
2. 插件膨胀：增加插件分组、懒加载，只在首次被会话调用时初始化执行器，减少内存占用；
3. 描述质量问题：后续可以引入轻量 Lint，自动检查 description 是否清晰、参数说明是否缺失；
4. 安全边界：插件执行器默认不开放高权限，禁止无限制执行本地脚本，防止恶意插件注入。

后续演进方向

• 插件市场：内置工具包仓库，支持一键导入社区运维插件；
• 插件依赖编排：支持组合工具（工作流插件），按顺序调用多个原子工具；
• A/B 测试：同一工具多个版本，按流量比例分配给不同会话，对比调用成功率。

小结

工具元模型 + 插件热加载，本质是把工具从“硬编码函数”升级成可治理、可分发、可版本化的能力单元。前面我们搭建了调用前校验、调用中幂等、失败后降级、结果可追溯的链路，而插件体系是这套链路的入口底座，让整个 Agent 的工具生态具备持续迭代能力。