Tool 系统

wesgine 的工具系统：六种来源、分类机制、执行流程与 JSON Schema 规范。

六种工具来源

来源	归属层	生命周期
Tier E 内置（read/write/exec/grep…）	Layer 2 Kernel	编译时固定
Tier C SDK 闭包（`cell.Tools().Register`）	Layer 3 Cell	随 Cell
MCP proxy（`cell.MCPs().Upsert`）	Layer 3 Cell	动态 Connect/Deregister
Adapter 派生（kb/email/cron/headless-browser/playwright/desktop）	Layer 3 Cell	随 CellSpec 对应字段
Sub-agent as Tool	Layer 3 Cell 内部自引用	随 Cell
Per-run 临时 Tool（`RunParams.Tools`）	Layer 4 Actor/Request	单次 Run

API

查询

方法	路径	说明
GET	`/tools`	工具列表（JSON Schema）
GET	`/tools/descriptions`	工具描述（纯文本）

SDK 注册

cell.Tools().Register(tool.Tool{
    Name:        "my_tool",
    Description: "自定义工具",
    Schema:      tool.Schema{...},
    Handler:     func(ctx tool.Context, args map[string]any) (string, error) { ... },
})

Tier E 内置工具

引擎二进制 embed 的核心工具，所有 Cell 默认可用：

工具	说明
`read`	读取文件内容
`write`	写入文件
`edit`	编辑文件（apply patch）
`apply_patch`	应用补丁
`exec`	执行命令
`grep` / `search_files`	搜索文件内容
`glob` / `find_files`	按模式查找文件
`memory`	记忆读写搜索
`plan`	计划管理
`delegate_task`	委派子任务
`ask_user`	HITL 交互
`browser_navigate`	浏览器导航
`web_search`	网络搜索

工具分类（CycleDetector 用）

分类	说明	典型工具
`categoryExploration`	只读探索	read、grep、search_files、plan
`categoryAction`	写操作（默认）	write、edit、exec

分类优先级（四级 fallback）

硬编码 map（wesgine 内置 ~20 个工具）
ExtraCategories（消费方声明）
ToolMeta 自动推断（ReadOnly=true → exploration）
默认 categoryAction

执行流程

Agent Loop 决定调用工具
  ↓
ToolRegistry 查找工具定义
  ↓
Governance 检查（Hardline → Sandbox → Zone）
  ↓
ToolContext 注入 Cell 边界信息
  ↓
Handler 执行
  ↓
结果返回 Agent Loop

ToolContext

工具执行时接收的上下文信息：

字段	说明
`CellID`	当前 Cell ID
`Actor`	当前请求主体
`RunID`	当前 Run ID
`SessionID`	当前 Session ID
`AgentID`	当前 Agent ID
`WorkDir`	工作目录
`AllowPaths`	允许访问的路径
`DenyPaths`	禁止访问的路径

Agent 工具白名单

Agent 可配置 Tools 字段过滤可用工具：

AgentConfig{
    Tools: []string{"read", "write", "exec", "grep"},
}

nil = 全量（不过滤）
[]string{} = 无工具

与 Cell DisabledEngineSkills AND 生效。

MCP 工具

通过 MCP 协议代理的外部工具自动注册到 Cell ToolRegistry：

cell.MCPs().Upsert(ctx, mcp.ServerConfig{
    Name:      "my-mcp",
    Command:   []string{"./mcp-server"},
    Transport: "stdio",
})

MCP 工具对 Agent 透明——与内置工具无差别。

Plugin 工具

Plugin 子进程通过 JSON-RPC 暴露工具，由 Manager 桥接到 ToolRegistry：

声明在 CellSpec.Plugins
boot 时自动发现并注册
Cell stop 时自动清理

Progress-Aware 工具

参数变化时 CycleDetector streak /= 2（减半）：

edit：同一文件多次修改是正常操作
write：内容不同的写入不是循环
apply_patch：不同补丁不是循环

消费方通过 ExtraProgressAware 声明额外的 progress-aware 工具。

JSON Schema 规范

工具定义使用 JSON Schema 描述参数：

{
  "name": "read",
  "description": "读取文件内容",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "文件路径"
      },
      "offset": {
        "type": "integer",
        "description": "起始行号"
      },
      "limit": {
        "type": "integer",
        "description": "读取行数"
      }
    },
    "required": ["path"]
  }
}