Skip to content

README_zh.md

Latest commit

 

History

History
73 lines (55 loc) · 3.62 KB

README_zh.md

File metadata and controls

73 lines (55 loc) · 3.62 KB

工具引擎

该文档描述 /internal/engine 模块的职责、配置与使用方式，聚焦于工具调用的执行策略、人工审批（HITL）与事件播报。内容与当前目录中的实现保持一致。

1. 概览

  • 目标：在一次或多次循环中稳定执行模型产生的工具调用，提供并发/顺序策略、准入与审批、事件通知。
  • 核心文件：interface.go、executor.go、config.go、hitl/。
  • 上下游：上游为 Assets Registry 提供的工具；下游通过事件总线向监控/UI播报工具执行与审批事件。

2. 架构

┌──────────────────────────────────────────────┐
│ ToolEngine (executor.go)                    │
│  • Registry：按名称检索工具实例              │
│  • Gate + Approver（hitl/）：策略与人工审批  │
│  • Executor：安全分组 + 并发/顺序执行        │
│  • Event：工具调用与审批事件播报            │
└──────────────────────────────────────────────┘
           ▲                     ▲
           │                     │
┌──────────┴─────────┐   ┌───────┴─────────┐
│ Assets Registry     │   │ EventBus        │
│ tool.BaseTool       │   │ ToolCall/Approval│
└────────────────────┘   └──────────────────┘
  • 并发策略：根据 UnsafeToolNames 将调用序列切分为“安全（并发）/不安全（顺序）”的连续分组，保持结果顺序与输入一致。
  • 审批管线：启用 EnableToolGate 时，先进行 Gate 判定；需要审批时通过事件总线请求并等待决策。
  • 事件总线：工具生命周期事件会通过内部总线输出，供 UI、日志或监控订阅。

3. 配置

config.go 中定义：

  • UnsafeToolNames：需顺序执行的工具名称列表
  • MaxToolExecConcurrency：并发上限
  • MaxRetries：失败重试次数（总尝试次数 = MaxRetries + 1）
  • ToolExecTimeout：单次调用超时
  • RetryDelay：重试间隔
  • EnableToolGate：是否启用 Gate/审批

默认值可通过 DefaultConfig() 获取。

4. 执行与分组

  • 输入按顺序遍历并切分为多个分组：连续安全分组并发执行、连续不安全分组顺序执行。
  • 执行结果按原始输入顺序对齐返回。
  • 每次调用支持超时、重试与错误封装为 schema.ToolMessage。

5. HITL 审批

  • hitl/interface.go 定义 GateDecision 与 ToolGate/Approve 接口。
  • hitl/gate.go 的 DefaultToolGate 支持从 tool.Info().Extra 读取策略键：
    • gate.require_approval: true → 需要审批
    • gate.allow: true → 允许
    • gate.deny: true → 拒绝
  • hitl/approver.go 的 DefaultApprove 通过事件总线请求审批并阻塞等待用户决策。

6. 事件

  • 工具执行：在结束时向总线发送 ToolCallInvokeEvent，包含工具名、ID、状态、入参与尝试次数等。
  • 审批请求：发送 ToolApprovalRequestEvent，包含 requestID、工具调用标识与入参；审批结果通过总线回传。

7. 目录

  • interface.go：ToolEngine 接口
  • executor.go：DefaultToolEngine 实现、分组与并发逻辑、事件播报
  • config.go：ToolEngineConfig 配置与默认值
  • hitl/interface.go：Gate/Approve 接口与决策模型
  • hitl/gate.go：默认 Gate 策略
  • hitl/approver.go：默认审批器