跳转到内容
Awaken

使用 Reminder 插件

当你希望 agent 在工具执行后，根据模式匹配自动收到上下文提示时，使用本页。例如：修改 .toml 后提醒执行 cargo check，或在危险命令后给出警告。

前置条件

Section titled “前置条件”
  • 已有可运行的 awaken runtime
  • awaken 启用了 reminder
[dependencies]
awaken = { git = "https://github.com/AwakenWorks/awaken", features = ["reminder"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"

步骤

Section titled “步骤”
  1. 注册 reminder 插件，并在 agent 配置里注入规则：
use std::sync::Arc;
use serde_json::json;
use awaken::engine::GenaiExecutor;
use awaken::ext_reminder::ReminderPlugin;
use awaken::registry_spec::ModelSpec;
use awaken::registry_spec::AgentSpec;
use awaken::{AgentRuntimeBuilder, Plugin};


let mut agent_spec = AgentSpec::new("my-agent")
    .with_model_id("claude-sonnet")
    .with_system_prompt("You are a helpful assistant.")
    .with_hook_filter("reminder")
    .with_section("reminder", json!({
        "rules": [
            {
                "tool": "Bash(command ~ 'rm *')",
                "output": { "status": "success" },
                "message": {
                    "target": "suffix_system",
                    "content": "A deletion command just succeeded. Verify the result."
                }
            }
        ]
    }));
agent_spec.plugin_ids.push("reminder".into());


let runtime = AgentRuntimeBuilder::new()
    .with_provider("anthropic", Arc::new(GenaiExecutor::new()))
    .with_model(ModelSpec::new("claude-sonnet", "anthropic", "claude-3-7-sonnet-latest"))
    .with_agent_spec(agent_spec)
    .with_plugin("reminder", Arc::new(ReminderPlugin::new(vec![])) as Arc<dyn Plugin>)
    .build()
    .expect("failed to build runtime");

该插件会在 AfterToolExecute 阶段检查工具名、参数和结果；一旦命中规则，就会调度 AddContextMessage 注入提示。 plugin_ids 负责加载插件，with_hook_filter("reminder") 只是在加载后过滤启用的 hook。reminder section 通过 ReminderConfigKey 校验，会出现在 /v1/capabilities 中，也是 admin console 页面保存的同一份数据。

  1. 用工具模式定义规则：
Pattern匹配
"Bash"精确工具名
"*"任意工具
"mcp__*"所有 MCP 工具
"Bash(command ~ 'rm *')"主参数 glob
"Edit(file_path ~ '*.toml')"命名字段 glob
  1. 配置 output 匹配：

output 可以是：

  • "any"
  • { "status": ..., "content": ... }

status 支持："success"、"error"、"pending"、"any"

content 支持两类：

  • 文本 glob
  • JSON 字段匹配
  1. 选择消息注入目标：
Target位置
"system"system prompt 前部
"suffix_system"system prompt 后部
"session"session 级 system message
"conversation"conversation 级 system message
  1. 用 cooldown 避免重复注入：
{
  "message": {
    "target": "system",
    "content": "Remember to be careful with file operations.",
    "cooldown_turns": 5
  }
}
  1. 也可以从文件加载默认规则：
use awaken::ext_reminder::{ReminderPlugin, ReminderRulesConfig};


let config = ReminderRulesConfig::from_file("reminders.json")
    .expect("failed to load reminder config");
let rules = config.into_rules().expect("invalid rules");
let plugin = ReminderPlugin::new(rules);

传给 ReminderPlugin::new(...) 的规则是插件默认值。agent 的 reminder section 会在运行时追加进去，因此同一个插件实例可以服务多个不同 reminder 配置的 agent。

  1. 在 agent spec 上激活插件：
let mut agent_spec = AgentSpec::new("my-agent")
    .with_model_id("claude-sonnet")
    .with_system_prompt("You are a helpful assistant.")
    .with_hook_filter("reminder");
agent_spec.plugin_ids.push("reminder".into());

plugin_ids 控制插件加载；with_hook_filter("reminder") 只在插件加载后过滤 hook。

验证

Section titled “验证”
  1. 配一个容易命中的规则，例如 "*" + "any"
  2. 运行 agent 并调用一个工具
  3. 打开 debug tracing，应该看到 reminder 命中的日志
  4. 确认下一轮推理 prompt 中出现了提醒消息

常见错误

Section titled “常见错误”
错误原因修复
InvalidPattern工具模式写错按 DSL 语法检查引号和通配规则
InvalidTarget消息目标无效只能用 system / suffix_system / session / conversation
InvalidOutputoutput 结构无效使用 "any" 或结构化对象
InvalidOp字段匹配操作符未知使用 glob / exact / regex / not_* 系列
规则从不触发插件未加载或 hook 被过滤在 plugin_ids 中加入 "reminder"，使用 hook filter 时再加 with_hook_filter("reminder")
规则触发太频繁没设置 cooldown设置正数 cooldown_turns

相关示例

Section titled “相关示例”
  • crates/awaken-ext-reminder/src/config.rs

关键文件

Section titled “关键文件”
路径作用
crates/awaken-ext-reminder/src/lib.rs模块根及公共再导出
crates/awaken-ext-reminder/src/config.rsReminderRulesConfig、JSON 加载、ReminderConfigKey
crates/awaken-ext-reminder/src/rule.rsReminderRule 结构定义
crates/awaken-ext-reminder/src/output_matcher.rsOutputMatcher、ContentMatcher、状态/内容匹配逻辑
crates/awaken-ext-reminder/src/plugin/plugin.rsReminderPlugin 注册（AfterToolExecute hook）
crates/awaken-ext-reminder/src/plugin/hook.rsReminderHook——每次工具调用的模式与输出评估
crates/awaken-tool-pattern/共享 glob/regex 模式匹配库

相关

Section titled “相关”