NekroAgent 文档

简体中文

English
日本語

简体中文

English
日本語

Appearance

插件激活调度 ​

插件激活调度（Plugin Activation Scheduling）是 Nekro Agent 为解决大量插件安装下上下文膨胀问题而设计的一套运行时动态披露机制。其核心思想借鉴自 Claude Code 的 Skill 机制：系统在每轮对话中只向 AI 披露当前需要的插件完整提示词，对暂时不需要的插件仅展示简短摘要，由 AI 在判断需要某插件时主动触发激活。

这是一个独立于提示词注入的能力，与 mount_prompt_inject_method 处于同等层级。提示词注入解决「注入什么内容」，激活调度解决「是否展示完整插件块」。

设计动机 ​

当用户安装的插件数量增多时，每个插件的能力声明（方法列表）会大量占用上下文窗口。若所有插件同时全量展示，将导致：

  • Token 消耗过高：每轮对话都携带大量插件声明，成本上升。
  • AI 注意力分散：无关插件的信息淹没真正有用的内容，影响响应质量。

激活调度通过让插件在「不活跃」时以摘要形式存在，AI 主动决策何时展开完整插件块，从而在「可用性」和「上下文效率」之间取得平衡。

插件可见状态 ​

每个插件在运行时处于以下三种状态之一：

状态含义AI 可见内容提示词注入是否调用
always_awake常驻，不参与调度完整能力声明 + 运行时上下文✅ 每轮调用
active激活中，倒计时剩余轮数完整能力声明 + 运行时上下文✅ 每轮调用
sleeping休眠中仅 sleep_brief 摘要❌ 不调用

处于 sleeping 状态的插件，AI 只能看到其简短描述（sleep_brief），看不到任何方法声明，也不会触发提示词注入。

配置休眠策略 ​

通过 NekroPlugin 实例上的 allow_sleep 和 sleep_brief 参数控制插件的休眠行为：

python
plugin = NekroPlugin(
    name="笔记插件",
    module_name="note",
    description="管理用户笔记",
    # ...
    allow_sleep=True,
    sleep_brief="管理用户笔记，当用户明确需要记录、查阅或修改笔记时激活。",
)

allow_sleep 三值语义 ​

值含义适用场景
None（默认）不参与调度，始终常驻工具类插件、基础能力插件；老插件未声明时的保守默认值
False强制禁止休眠，管理员无法覆盖任何对话都可能依赖的核心插件（如 basic 消息发送插件）
True允许休眠（须同时提供 sleep_brief）功能明确、按需使用的插件（笔记、天气、提醒等）

注意：仅设置 allow_sleep=True 而不提供 sleep_brief（或 sleep_brief 为空字符串）时，系统仍将视该插件为不可休眠，行为等同于 allow_sleep=None。两个条件缺一不可。

编写高质量的 sleep_brief ​

sleep_brief 是 AI 在插件休眠时唯一能看到的信息，直接决定 AI 能否正确判断「何时需要唤醒该插件」。

写作原则：

  • 明确说明插件用途和核心能力
  • 描述典型使用场景（用户通常在什么情况下会需要它）
  • 简洁，无需详细列出方法，几句话即可

示例：

python
# ❌ 过于简略，AI 难以判断激活时机
sleep_brief="笔记功能。"

# ✅ 清晰说明用途和激活场景
sleep_brief="管理用户笔记，支持创建、查阅、修改和删除笔记条目。当用户明确提到需要记笔记、查看笔记或整理信息时激活。"

AI 如何与调度机制交互 ​

系统内置 plugin_activation 插件提供两个方法，供 AI 主动控制激活状态：

activate_plugin（AGENT METHOD） ​

当 AI 判断需要使用某个休眠中的插件时调用。这是一个 AGENT METHOD——调用后立即停止当前执行，将该插件的完整提示词块作为 Agent 响应直接返回给 AI，AI 在下一步可基于完整能力继续操作。

python
# AI 在沙盒中调用：
activate_plugin("note")           # 唤醒笔记插件，默认激活 3 轮
activate_plugin("weather", rounds=5)  # 唤醒天气插件，指定激活 5 轮

调用后，系统返回类似如下内容（直接作为 Agent 响应）：

xml
Plugin `note` is now activated for the next 3 runs.
The full plugin block is returned below and is now the source of truth for this capability.
Stop here and continue in the next agent step.

<plugin name="笔记插件" module_name="note" state="active" rounds_left="3">
  <injected_prompt>...</injected_prompt>
  ... (完整方法列表)
</plugin>

可能的返回情况：

  • 激活成功：返回完整插件块，AI 在下一步可使用该插件
  • 插件已激活：提示当前剩余轮数，建议改用 extend_plugin_activation
  • 插件常驻：提示该插件无需激活，可直接使用
  • 插件不存在或已禁用：返回错误提示

extend_plugin_activation（BEHAVIOR METHOD） ​

在插件即将到达激活轮数上限时调用，为其追加剩余轮数。

python
# AI 在沙盒中调用（通常在某插件只剩 1 轮时）：
extend_plugin_activation("note", rounds=3)  # 为笔记插件追加 3 轮

系统会自动在插件剩余 1 轮时附加激活提示（activation_hint），提醒 AI 考虑是否需要续期：

Last visible run. Call extend_plugin_activation('note') now if you still need it next run.

轮数计数机制 ​

  • 默认激活轮数：DEFAULT_ACTIVE_ROUNDS = 3
  • 最大激活轮数：MAX_ACTIVE_ROUNDS = 20
  • 每轮递减：每次对话触发（有实际激活的插件）时，所有激活中插件的剩余轮数减 1
  • 减至 0：插件自动进入休眠状态

说明：「一轮」对应一次完整的 Agent 执行（从用户消息到 AI 最终响应），包括多次沙盒迭代。

管理员策略覆盖 ​

系统管理员可通过配置 PLUGIN_ACTIVATION_STRATEGIES 在运行时覆盖插件的休眠行为：

策略值含义
auto（默认）遵循插件自身声明（allow_sleep + sleep_brief）
allow_sleep强制允许休眠（需 sleep_brief 存在，且插件未设 allow_sleep=False）
forbid_sleep强制禁止休眠，插件始终常驻

注意：若插件设置了 allow_sleep=False（受保护），管理员策略无法将其设为可休眠。allow_sleep=False 是插件开发者的强制保护，高于管理员配置。

优先级顺序（从高到低） ​

  1. 插件声明 allow_sleep=False → 永远不休眠（开发者强制保护）
  2. 管理员策略 forbid_sleep → 不休眠
  3. 管理员策略 allow_sleep → 若 sleep_brief 存在则可休眠
  4. 管理员策略 auto / 默认 → 以插件自身的 allow_sleep=True + sleep_brief 为准

与提示词注入的关系 ​

提示词注入和插件激活调度是两个正交的能力：

  • 提示词注入：控制「注入什么动态内容」——每轮将运行时状态写入对话上下文
  • 插件激活调度：控制「是否展示完整插件块」——管理上下文中插件能力声明的可见性

两者可以组合使用：

  • 一个插件可以同时有注入方法和休眠支持，休眠时两者都不触发
  • 一个插件可以只有注入方法而不支持休眠（allow_sleep=None），始终常驻
  • 一个插件可以支持休眠但没有注入方法，激活时只展示方法列表

最佳实践 ​

何时应支持休眠？ ​

适合休眠（设 allow_sleep=True）：

  • 功能独立、明确触发场景的插件（笔记、日历、天气等）
  • 方法声明较多、占用上下文明显的插件
  • 非每次对话都需要使用的插件

不适合休眠（保持 allow_sleep=None 或设 allow_sleep=False）：

  • 所有对话都可能用到的基础功能（消息发送、表情回复等）
  • 插件提供的提示词注入内容对 AI 行为有持续性影响的插件
  • 激活调度器本身（plugin_activation 插件固定设 allow_sleep=False）

注入方法较耗时时 ​

若插件的提示词注入方法涉及数据库查询或外部 API 调用，建议同时支持休眠。休眠状态下注入方法不会被调用，可以避免在不必要时产生额外延迟和费用。

发现文档问题？报告问题