# OpenRouter Chatbot - Minecraft 插件
## 概述
OpenRouter Chatbot 是一个强大且高度可配置的 Spigot 插件，它将 OpenRouter AI API 集成到你的 Minecraft 服务器中。它允许玩家和服务器管理员直接在游戏中与各种 AI 模型进行交互，支持网络搜索、动态模型切换和广泛的自定义。该插件旨在成为任何服务器中无缝且身临其境的补充，既提供实用功能又提供娱乐。
## 核心功能
- **游戏内 AI 聊天**: 从服务器控制台和游戏内聊天中访问强大的 AI 聊天机器人。
- **动态模型切换**: 使用简单的命令随时更改活动 AI 模型。该插件支持模型名称的自动完成，使你可以轻松找到和选择适合你需求的完美模型。
- **通用网络搜索**: 通过在模型名称后附加 `:online`，你可以启用任何查询的网络搜索，允许 AI 提供有关任何主题的最新信息。
- **智能上下文扩展**: 该插件可以自动检测并使用模型的扩展上下文版本（例如：`:extended`），为更复杂的对话提供更大的上下文窗口。
- **高度可配置**: 插件的几乎每个方面都可以通过详细的 `config.yml` 文件进行自定义。你可以控制从消息格式和颜色到温度和令牌限制等高级 API 参数的一切。
- **细粒度的权限控制**: 你可以完全控制谁可以使用插件的命令。每个命令可以配置为需要操作员 (OP) 状态或特定的权限节点。
- **公共或私有消息**: 配置插件以将 AI 交互广播给整个服务器，或将它们保持在发起提示的用户私有。
## 命令和权限
插件的命令简单直观：
| 命令 | 描述 | 权限节点 | 默认 |
| --- | --- | --- | --- |
| `/ai ` | 将提示发送到配置的 AI 模型。 | `openrouterchatbot.use` | 所有玩家 |
| `/ai set ` | 设置所有后续请求的默认 AI 模型。 | `openrouterchatbot.set` | 操作员 |
| `/ai reloadmodels` | 从 OpenRouter API 刷新可用模型的缓存列表。 | `openrouterchatbot.reload` | 操作员 |
你可以在 `config.yml` 文件中更改默认的权限要求。
## 安装和设置
1. **下载**: 从项目的发布页面获取最新版本的 `OpenRouterChatbot.jar`。
2. **安装**: 将 `OpenRouterChatbot.jar` 文件放入服务器的 `plugins` 目录中。
3. **首次运行**: 启动你的服务器。该插件将在 `plugins/OpenRouterChatbot/config.yml` 生成其默认配置文件。
4. **配置**: 停止服务器并使用文本编辑器打开 `config.yml` 文件。
- **API 密钥**: 最重要的步骤是将你的 OpenRouter API 密钥粘贴到 `openrouter-api-key` 字段中。你可以在 [https://openrouter.ai/keys](https://openrouter.ai/keys) 获取密钥。
- **自定义**: 检查 `config.yml` 文件的其余部分并根据你的喜好进行自定义。该文件已 extensively 详细注释，以解释每个选项。
5. **重启**: 再次启动你的服务器。该插件现在已配置并准备好使用。
## 工作原理
该插件通过对 OpenRouter API 进行异步调用来运行。这意味着服务器的主线程永远不会被阻塞，从而防止任何延迟或性能问题。当用户发出命令时，插件会立即发送“正在思考……”消息（如果已启用），然后以后台方式将请求发送到 API。API 做出响应后，该插件将安排一个任务，以在服务器主线程中向用户发送 AI 的响应，以确保线程安全。
启动时，该插件还会从 OpenRouter API 检索和缓存所有可用模型的列表。这使得模型名称的快速自动完成成为可能，并实现了无需为每个命令调用 API 即可工作的智能扩展上下文功能。
## 配置文件 (`config.yml`) 说明
本节提供了 `config.yml` 文件中每个设置的详细、逐个解释。
### `Primary Settings`
- `openrouter-api-key`: 这是你必须粘贴来自 OpenRouter 的唯一 API 密钥的地方。如果没有它，该插件将无法工作。
- `model`: 此设置确定插件将使用的默认 AI 模型。你可以在 OpenRouter 网站上找到可用模型的列表。可以使用 `/ai set` 在游戏中更改此设置。
### `command-permissions`
此部分允许你控制谁可以使用插件的命令。
- `require-op-for-ai`: 如果设置为 `true`，只有服务器操作员 (OP) 或具有 `openrouterchatbot.use` 权限的玩家才能使用 `/ai ` 命令。如果 `false`，任何人都可以使用它。
- `require-op-for-set`: 如果设置为 `true`，只有 OP 或具有 `openrouterchatbot.set` 权限的玩家才能使用 `/ai set` 命令。如果 `false`，任何人都可以更改模型。
- `require-op-for-reload`: 如果设置为 `true`，只有 OP 或具有 `openrouterchatbot.reload` 权限的玩家才能使用 `/ai reloadmodels` 命令。如果 `false`，任何人都可以重新加载模型缓存。
### `features`
此部分包含各种插件行为的开关。
- `send-thinking-message`: 如果 `true`，当用户提交提示后，会将“正在思考……”消息发送给用户，为请求正在处理提供反馈。
- `enable-web-search`: 如果 `true`，该插件将自动在模型名称后添加 `:online` 后缀，从而启用 AI 为最新信息搜索网络。
- `enable-extended-context`: 如果 `true`，该插件将检查选定的模型是否具有 `:extended` 版本，并在可用时使用它。这为 AI 提供了更大的内存，以进行更长的对话。
- `display-user-prompt`: 如果 `true`，将在 AI 响应之前在聊天中显示用户的原始提示。这对于公共对话的上下文很有用。
- `include-player-name-in-prompt`: 如果 `true`，则将在发送到 AI 的消息前添加发送提示的玩家的名称（例如：“Notch: creeper 是什么？”）。这可以帮助 AI 调整其响应。
### `message-visibility`
- `broadcast-to-server`: 如果 `true`，所有与 AI 交互相关 (提示、"正在思考……" 消息和响应) 的消息都将广播给服务器上的所有玩家。如果 `false`，这些消息将仅对使用命令的玩家可见。
### `message-formatting`
此部分允许你自定义所有插件消息的外观。你可以使用标准的 Minecraft 颜色代码（例如 `&a` 表示绿色）以及以下占位符：
- `%player%`: 使用命令的玩家的名称。
- `%prompt%`: 玩家发送的提示。
- `%model%`: 使用的 AI 模型。
### `api-settings`
此部分允许你直接控制发送到 OpenRouter API 的参数。这建议针对高级用户。
- `instructions`: 一种系统提示，用于指导 AI 的个性和行为。
- `temperature`: 控制 AI 响应的随机性。更高的值（例如 1.2）将导致更具创造性但不太可预测的响应，而更低的值（例如 0.5）将使响应更集中和确定性。
- `max_tokens`: AI 响应的最大长度，以令牌（大约是单词）为单位。
- `top_p`: 控制随机性的温度的替代方法。建议仅使用 `temperature` 或 `top_p` 中的一个。
- `frequency_penalty` 和 `presence_penalty`: 可以使用这些设置来阻止 AI 重复本身。
- `stop`: 一系列将在 AI 立即停止生成文本时使用的单词或短语。
- `seed`: 提供了整数种子，AI 将为相同的提示每次产生相同的输出。这对于测试很有用。
- `transforms`: 应用于模型输出的转换列表。
- `route`: API 调用的路由策略。