ArkPilot

主题

常见问题 ​

安装与启动 ​

插件加载失败 ​

检查以下几点：

  1. 使用 Paper 或其 Fork（Purpur 等），不支持 Spigot / CraftBukkit
  2. Java 版本 ≥ 8（推荐 17+）
  3. 查看控制台报错信息

提示"未配置 API Key" ​

编辑 models.yml，在 api-keys 中填入对应提供商的密钥。至少需要配置一个提供商的 API Key。

三种方式：

yaml
# 直接填写
anthropic: "sk-ant-xxx"
# 引用环境变量（推荐）
anthropic: "${ANTHROPIC_API_KEY}"
# 留空，自动查找环境变量 ANTHROPIC_API_KEY
anthropic: ""

提示"主模型不可用" ​

可能原因：

  1. API Key 无效或过期
  2. 模型名称错误（检查 models.yml 的 defaults.model.primary）
  3. API 配额用尽
  4. 网络无法访问模型提供商

建议在 defaults.model.fallbacks 中配置备选模型。

使用相关 ​

助手不回复 / 回复很慢 ​

  1. 检查行动条是否显示"正在思考..."——如果有，说明正在等待 AI 回复
  2. AI 模型的响应时间通常为 2-10 秒，复杂问题可能更久
  3. 检查 config.yml 的 execution.timeoutSeconds 是否设置过短
  4. 查看控制台是否有错误日志

怎么和助手对话？ ​

三种方式：

  1. 聊天触发：@helper 你好（使用助手的 chatTrigger）
  2. 私聊模式：/ark → 点击助手 → 私聊模式，之后直接打字
  3. GUI 菜单：/ark 打开管理菜单

怎么切换助手？ ​

使用不同的触发词：

@helper 你好      → 小墨（玩家助手）
@builder 建个屋   → 小匠（建筑助手）

或在 GUI 中切换私聊模式的目标助手。

助手的回复包含乱码符号 ​

AI 偶尔会输出 Markdown 格式（**、##、``` 等）。处理方法：

  1. 检查 SOUL.md 中是否有输出格式规范
  2. 尝试换一个更遵循指令的模型
  3. 在 SOUL.md 中加强格式限制的提示

怎么让助手忘记我？ ​

在 GUI 中操作：

  • 新建会话：清空对话历史，保留记忆
  • 重置：清空对话历史 + 清空记忆（彻底遗忘）

私聊模式下怎么和其他玩家说话？ ​

用 ! 前缀（可在 config.yml 的 interaction.dmMode.publicChatPrefix 中修改）：

!大家好     → 发到公共聊天
大家好       → 发给助手

配置相关 ​

怎么控制 AI 的费用？ ​

  1. 选择性价比高的模型（如 DeepSeek、MiniMax）
  2. 减小 session.maxContextTokens（减少历史消息 token）
  3. 减小 defaults.maxTokens（限制回复长度）
  4. 设置 rateLimit.defaultMaxDailyUses（限制每日使用次数）
  5. 开启 billing 追踪用量

怎么限制某些玩家使用？ ​

在助手配置中使用权限组：

yaml
permissions:
  allowedGroups: ["vip", "admin"]     # 只允许这些组
  deniedGroups: ["banned"]            # 禁止这些组

或使用权限节点 arkpilot.assistant.<id>。

怎么接入中转站 / 私有 API？ ​

在 models.yml 的 providers 中配置自定义提供商：

yaml
providers:
  my-proxy:
    baseUrl: "https://api.my-proxy.com/v1"
    apiKey: "${MY_PROXY_KEY}"
    api: "openai-completions"
    models:
      - id: "claude-3-opus"
        name: "Claude 3 Opus"
        contextWindow: 200000
        maxTokens: 4096

然后在模型配置中引用：primary: "my-proxy:claude-3-opus"

详见模型配置。

修改配置后需要重启服务器吗？ ​

大部分配置支持 /ark reload 热重载，例外：

  • storage.yml 修改存储类型后需重启
  • 新增/删除助手目录后需重载

怎么添加自定义命令到白名单？ ​

在助手配置的 executeCommand.whitelist 中添加：

yaml
executeCommand:
  whitelist:
    - "tp"
    - "give"
    - "warp"           # 新增
    - "home"           # 新增

白名单中的命令以 console 权限执行。不在白名单的命令以玩家权限执行。

跨服相关 ​

多个服务器怎么共享数据？ ​

在 storage.yml 中将 type 改为 mysql 或 postgresql，所有服务器连接同一数据库即可。会话历史和记忆会自动跨服同步。

跨服后助手"忘记"了之前的工具？ ​

不同服务器可能有不同的工具集。插件会自动处理历史中不可用的工具调用记录，不影响正常对话。

性能相关 ​

AI 请求对服务器性能有影响吗？ ​

AI 请求在独立 IO 线程池中处理，不阻塞主线程。但需要注意：

  1. 调整 execution.threadPoolSize 和 maxConcurrent 匹配服务器规模
  2. 蓝图建造的 maxBlocksPerTick 影响 TPS

大量玩家同时使用会怎样？ ​

超过并发限制的请求会排队等待，队列满后拒绝新请求。调整 execution 配置控制并发：

yaml
execution:
  threadPoolSize: 20    # 增大线程池
  maxConcurrent: 20     # 增大并发数
  queueSize: 100        # 增大队列

ArkPilot — Minecraft AI Assistant Plugin