提示词注入
提示词注入 (Prompt Injection) 是 Nekro Agent 插件向 AI 提供动态运行时上下文的核心机制。通过注册一个异步方法，插件可以在每次 AI 处理消息时将当前会话相关的状态、数据或指令注入到对话中。
什么是提示词注入？
在 AI 响应每条消息之前，系统会收集所有活跃插件的注入内容，将其附加到当前对话轮次的上下文中。插件可以借此向 AI 传递：
- 动态状态：当前角色状态、活跃任务、用户偏好等随时间变化的数据。
- 会话上下文：插件从数据库或外部服务实时查询到的与本次会话相关的信息。
- 行为约束：在特定场景下需要临时生效的规则或指引。
注入内容的实际位置
注意：注入内容不在系统消息（System Prompt）中。
插件在系统消息里只有静态的能力声明（方法列表）。inject_method 返回的动态内容以 <plugin_runtime_context> 标签的形式出现在每轮对话历史消息的头部（user 消息），AI 被要求将其视为当前会话权威的系统级上下文：
xml
<plugin_runtime_context name="插件名称" module_name="module_name">
这里是插件注入的运行时上下文内容
</plugin_runtime_context>注册提示词注入方法
使用 @plugin.mount_prompt_inject_method() 装饰器注册注入方法：
python
from nekro_agent.api.schemas import AgentCtx
@plugin.mount_prompt_inject_method(
name="status_prompt",
description="向 AI 注入当前角色状态信息"
)
async def inject_status_prompt(_ctx: AgentCtx) -> str:
"""生成并返回需要注入的字符串。"""
current_status = await plugin.store.get(
chat_key=_ctx.from_chat_key,
store_key="current_status"
)
if current_status:
return f"当前角色状态：{current_status}"
return "" # 返回空字符串表示本次不注入任何内容关键要求：
- 必须是
async def异步函数 - 接收
AgentCtx作为第一个参数 - 必须返回
str，返回空字符串表示本次不注入
何时执行？
每次用户消息触发 AI 处理时，系统都会调用所有活跃插件的注入方法，收集内容后一并附加到本轮上下文头部。
若插件处于休眠状态（参见插件激活调度），注入方法不会被调用。
设计有效的注入提示词
- 简洁：只提供 AI 真正需要的信息，避免冗长。注入内容每轮都会占用 token。
- 动态相关：充分利用
AgentCtx和插件存储，确保内容与当前会话强相关。 - 条件返回：无状态时返回
""，避免无意义的空块。 - 结构清晰：多条信息使用换行或固定前缀格式，便于 AI 解析。
示例：带条件返回的注入
python
@plugin.mount_prompt_inject_method(name="note_prompt")
async def inject_note_prompt(_ctx: AgentCtx) -> str:
notes = await plugin.store.get(chat_key=_ctx.from_chat_key, store_key="notes")
if not notes:
return ""
return f"用户当前有以下笔记：\n{notes}"性能注意事项
注入方法每轮对话都会被调用：
- 必须异步：涉及数据库或网络的操作务必使用
await，不得阻塞事件循环。 - 控制耗时：注入方法的延迟会直接影响 AI 响应速度，建议对重操作结果进行缓存。
- 结合休眠机制：若注入操作较耗时，考虑让插件支持休眠，在不需要时跳过注入调用（参见插件激活调度）。
通过精心设计的提示词注入，你可以让插件更智能地与 AI 协作，为用户提供更流畅、更个性化的体验。
注入方法的性能注意事项
注入方法在每轮对话触发时都会被调用，应注意以下几点：
- 避免阻塞操作：如必须进行网络请求或数据库查询，务必使用
async/await，不要使用同步阻塞调用。 - 控制执行时间：注入方法的执行会延迟 AI 响应，建议对耗时操作结果进行缓存。
- 合理使用休眠：如果你的插件注入方法较为耗时（如需要网络请求），考虑将
allow_sleep=True，让不需要时的轮次跳过注入调用。