工具全景

wescode 的 Agent 通过工具（Tool）与代码库交互。工具不是插件——它们是 Agent 的手和眼，决定了 Agent 能做什么、做得多好。

三层架构

wescode 的工具来自三个层次，由近到远：

Layer A：Device Agent（IDE 能力）

这些是 VS Code 编辑器自身提供的能力，通过 wescode 的 Device Agent 暴露给引擎。模型看不到它们的存在——它们透明地增强了标准工具。

零 tool schema footprint——这些能力不增加模型的工具列表，不消耗额外的 schema token。

Layer B：wesgine Tier E（引擎内置）

wesgine 引擎编译时内置的标准工具，所有 Cell 可用：

Layer C：wescode 专属工具

wescode 自己注册到 Cell 的工具，服务于编程特有的场景：

这些工具通过 cell.Tools().Register() 装配到 workspace Cell，不同工作区独立。

工具设计原则

wescode 的工具遵循几个不成文但重要的规则：

1. description 是给模型看的

工具的 description 字段不是文档注释——它是模型决定"用不用这个工具"的唯一依据。好的 description 应该：

• 说清楚什么时候用，不只是"能做什么"
• 包含一个典型用例
• 指出与相似工具的区别

2. 参数越少越好

每个参数都增加模型犯错的概率。能从上下文推断的信息不要让模型填。

3. 探索与行动分离

只读工具（read、grep、ckg_query）和写入工具（edit、write、exec）有不同的 CycleDetector 阈值。探索性调用允许更多次数，因为大仓里需要读很多文件才能定位问题。

exec 三分类路由

终端命令不是一视同仁。wescode 根据命令性质自动路由到不同执行方式：

路由自动判定：user_visible=true → 交互；isVerificationCommand() → 验证；默认 → 静默。你不需要手动指定。

下一步

• 编辑引擎 — edit 工具的三级匹配机制
• 代码知识图谱（CKG） — CKG 查询工具详解
• 渐进验证 — 验证工具的触发逻辑