Tool 与 Plugin 的边界

Awaken 明确区分“给 LLM 使用的能力”（tools）和“运行时生命周期扩展”（plugins）。本页解释两者的边界、适用场景以及交互方式。

Tools

tool 是暴露给 LLM 的能力：

pub trait Tool: Send + Sync {
    fn descriptor(&self) -> ToolDescriptor;
    fn validate_args(&self, args: &Value) -> Result<(), ToolError> { Ok(()) }
    async fn execute(&self, args: Value, ctx: &ToolCallContext) -> Result<ToolOutput, ToolError>;
}

特征：

用 ID 注册
对 LLM 可见
会经过 ToolGate、BeforeToolExecute、真正执行以及 AfterToolExecute
只能访问参数和 ToolCallContext
适合文件操作、API 调用、数据库查询等业务能力

Plugins

plugin 是运行时级扩展，不会出现在 LLM 工具列表中：

pub trait Plugin: Send + Sync + 'static {
    fn descriptor(&self) -> PluginDescriptor;
    fn register(&self, registrar: &mut PluginRegistrar) -> Result<(), StateError>;
    fn config_schemas(&self) -> Vec<ConfigSchema> { vec![] }
}

特征：

用插件 ID 注册
对 LLM 不可见
在 phase 边界运行
可以访问更完整的 PhaseContext
适合权限、观察、提醒、请求变换、状态同步等横切逻辑

PluginRegistrar

Plugin::register() 中，插件通过 PluginRegistrar 声明自己需要的能力：

注册方法	用途
`register_key::<K>(options)`	注册状态键(options 携带 scope)
`register_profile_key::<K>()`	注册跨线程持久化的 agent profile typed key
`register_tool_gate_hook()`	注册纯判定的工具拦截钩子
`register_tool_policy_hook()`	注册类型化 `ToolPolicyHook`(走同一个 `ToolGate` phase)
`register_phase_hook()`	在指定 phase 添加 hook
`register_tool()`	向运行时注入插件提供的工具
`register_effect()`	处理 hook 发出的命名 effect(由 `EffectSpec` 类型化)
`register_scheduled_action()`	处理 scheduled actions
`register_request_transform()`	在请求到达 LLM 前变换推理请求

插件也可以注册 tool，例如 AgentTool、MCP 工具、skills 工具。对于 LLM 来说，这些和用户手写 tool 没有区别。

何时使用 Tool

适合以下情况：

需要被 LLM 显式按名字调用
是领域能力，如搜索、计算、文件 I/O、API 调用
有结构化输入和可供 LLM 推理的结果

何时使用 Plugin