词元广场TOKPUB.COM - 欢迎您，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
"Plugin LLM 访问"
Plugin LLM 访问
ctx.llm 是 plugin 发起 LLM 调用的官方方式。对话补全、结构化提取、同步、异步、带或不带图像——
同一接口，同一信任门控，同一宿主持有的凭据。
例如：将工具报错改写成非工程师也能理解的语言的 hook；
在消息入队前进行翻译的 gateway 适配器；
对长段粘贴内容进行摘要的斜杠命令；
对前一天活动评分并向状态看板写一行记录的定时任务；
以及决定某条消息是否值得唤醒 agent 的预过滤器。
最简调用
更完整的对话示例
purpose 是一个自由格式的审计字符串——它会出现在 agent.log 和 result.audit 中，方便运营人员查看哪个 plugin 发起了哪次调用。可选，但对于频繁触发的场景建议填写。结构化输出
jsonschema 则对你的 schema 进行验证，最终在 result.parsed 上返回一个 Python 对象。如果模型无法生成有效 JSON，result.parsed 为 None，result.text 携带原始响应。此模式的优势
complete() 用于对话，complete_structured() 用于有类型的 JSON，acomplete() 和 acomplete_structured() 用于 asyncio。参数相同，结果对象相同。result.audit 将调用归因回溯。config.yaml 中按 plugin 逐一选择开启特定覆盖。快速开始
register(ctx) 函数中实现，无需任何外部配置即可针对用户当前激活的模型运行。对话补全——/tldr
result.text 是模型的响应；result.usage 携带 token 计数；result.provider 和 result.model 携带归因信息。结构化提取——/paste-to-tasks
hermes-example-plugins仓库（参考 plugin 的配套仓库——不随 hermes-agent 本体打包）。关于异步接口（
acomplete() / acomplete_structured() 与 asyncio.gather() 配合使用），请参见同一仓库中的plugin-llm-async-example。何时使用哪种方式
| 你需要…… | 使用 |
|---|---|
| 自由格式文本响应（翻译、摘要、改写、生成） | complete() |
| 多轮 prompt（system + few-shot 示例 + user） | complete() |
| 经 schema 验证的有类型 dict | complete_structured() |
| 图像或文本输入并返回有类型 dict | complete_structured() |
| 在异步代码中发起相同调用（gateway 适配器、异步 hook） | acomplete() / acomplete_structured() |
API 接口
ctx.llm 是 agent.plugin_llm.PluginLlm 的实例。complete()
messages 采用标准 OpenAI 格式——{"role": "...", "content": "..."} 字典列表。多轮 prompt（system + few-shot user/assistant 对 + 最终 user）的用法与 OpenAI SDK 完全一致。provider= 和 model= 相互独立，格式与宿主主配置（model.provider + model.model）相同。仅设置 model= 可在用户当前激活的 provider 上使用不同模型。同时设置两者则完全切换 provider。任一参数在未获运营人员授权时均会抛出 PluginLlmTrustError。complete_structured()
data: URL）。当提供 json_schema 或设置 json_mode=True 时，宿主通过 response_format 向 provider 请求 JSON 输出，在本地作为兜底进行解析，若安装了 jsonschema 则对你的 schema 进行验证。result.content_type == "json" — result.parsed 是符合你 schema 的 Python 对象。result.content_type == "text" — 解析或验证失败；检查 result.text 获取原始模型响应。异步
结果属性
usage 携带 input_tokens、output_tokens、total_tokens、cache_read_tokens、cache_write_tokens 和 cost_usd。信任门控
plugins.entries 配置块的情况下，plugin 可以：temperature、max_tokens、timeout、system_prompt、purpose、messages、instructions、input、json_schema），provider=、model=、agent_id= 和 profile= 参数在运营人员授权前均会抛出 PluginLlmTrustError。ctx.llm.complete(messages=...) 且不带任何覆盖的 plugin，会针对用户当前激活的内容运行，零配置即可工作。以下配置块仅在 plugin 明确需要固定到与用户不同的模型或 provider 时才有意义。name: 字段，对于嵌套 plugin 是路径派生的键（image_gen/openai、memory/honcho 等）。门控执行内容
| 覆盖项 | 默认 | 配置键 |
|---|---|---|
provider= | 拒绝 | allow_provider_override: true |
| ↳ 允许列表 | — | allowed_providers: [...] |
model= | 拒绝 | allow_model_override: true |
| ↳ 允许列表 | — | allowed_models: [...] |
agent_id= | 拒绝 | allow_agent_id_override: true |
profile= | 拒绝 | allow_profile_override: true |
allow_model_override 不会同时授予 allow_provider_override——被信任可选择模型的 plugin，在未获得 provider 门控授权前仍固定在用户当前激活的 provider 上。门控无需执行的内容
temperature、max_tokens、timeout、system_prompt、purpose、messages、instructions、input、json_schema、schema_name、json_mode——始终允许；它们不涉及凭据或路由选择。plugins.entries。宿主负责的内容
ctx.llm 为 plugin 代劳的完整列表，你无需自行处理：model.provider + model.model（或在受信任时读取显式覆盖值）。~/.hermes/auth.json / 环境变量中提取 API 密钥、OAuth token 或刷新 token，包括配置了凭据池时的处理。Plugin 永远看不到这些内容。timeout= 参数，回退到 auxiliary.<task>.timeout 配置或全局辅助默认值。response_format，若 provider 返回了代码围栏格式的响应则在本地重新解析。jsonschema 时对你的 json_schema 进行验证；否则记录一行 debug 日志并跳过严格验证。agent.log 写入一条 INFO 日志，包含 plugin id、provider/模型、purpose 和 token 总量。Plugin 负责的内容
messages，结构化用 instructions + input。Plugin 构建 prompt（提示词）；宿主执行它。complete_structured() 在输入为空或 schema 验证失败时抛出 ValueError。信任门控 拒绝覆盖时抛出 PluginLlmTrustError。其他情况（provider 5xx、未配置凭据、超时）抛出 auxiliary_client.call_llm() 本身抛出的异常。complete()。在 plugin 接口中的定位
ctx.* 方法各自扩展一个已有的 Hermes 子系统：ctx.register_tool | 添加 agent 可调用的工具 ||
ctx.register_platform | 接入新的 gateway 适配器 ||
ctx.register_image_gen_provider | 替换图像生成后端 ||
ctx.register_memory_provider | 替换记忆后端 ||
ctx.register_context_engine | 替换上下文压缩器 ||
ctx.register_hook | 监听生命周期事件 |ctx.llm 是第一个允许 plugin 在带外运行用户正在对话的同一模型的接口，无需上述任何注册。这是它唯一的职责。如果你的 plugin 需要注册一个由 agent 调用的工具，使用 register_tool。如果需要响应生命周期事件，使用 register_hook。如果需要发起自己的模型调用——无论出于何种原因，结构化与否——使用 ctx.llm。参考资料
plugin-llm-example — 带图像输入的同步结构化提取plugin-llm-async-example — 使用 asyncio.gather() 的异步示例Provider 运行时。