安装指南

环境要求

要求	最低版本
Minecraft 服务端	Paper 1.20.4+（或其 Fork，如 Purpur）
Java	Java 8+（推荐 Java 17+）
AI 模型 API Key	至少一个（Anthropic / OpenAI / Google / DeepSeek / MiniMax 等）

可选依赖

插件	用途
Citizens	NPC 绑定助手，玩家右键 NPC 即可对话
Vault	经济系统集成（扩展包使用）

安装步骤

1. 下载插件

从 Releases 下载最新的 ArkPilot-x.x.x.jar。

2. 放入服务器

将 JAR 文件放入服务器的 plugins/ 目录：

server/
└── plugins/
    └── ArkPilot-x.x.x.jar

3. 首次启动

启动服务器，插件会自动生成默认配置文件：

plugins/ArkPilot/
├── config.yml           # 核心配置
├── models.yml           # 模型配置
├── storage.yml          # 存储配置
├── SERVER.md            # 服务器信息（需要编辑）
├── assistants/          # 助手定义
│   ├── player-helper/   # 默认助手 — 小墨
│   ├── builder/         # 建筑助手 — 小匠
│   └── blueprint-generator/  # 蓝图生成器（内部）
└── skills/              # 技能文档

4. 配置 API Key

编辑 plugins/ArkPilot/models.yml，填入你的 AI 模型 API Key：

api-keys:
  # 至少配置一个。支持直接填写或引用环境变量。
  anthropic: "sk-ant-xxx"         # Anthropic (Claude)
  openai: "sk-xxx"                # OpenAI (GPT)
  google: "AIzaSy..."             # Google (Gemini)
  deepseek: "sk-xxx"              # DeepSeek
  minimax: "eyJ..."               # MiniMax

推荐方式

使用环境变量，避免密钥写入配置文件：

api-keys:
  anthropic: "${ANTHROPIC_API_KEY}"

然后在服务器启动脚本中设置环境变量：

export ANTHROPIC_API_KEY="sk-ant-xxx"
java -jar paper.jar

5. 选择默认模型

在 models.yml 中设置默认模型：

defaults:
  model:
    primary: "anthropic:claude-sonnet-4-5"   # 推荐
    # 或其他选择：
    # primary: "openai:gpt-4.1"
    # primary: "google:gemini-2.5-flash"
    # primary: "deepseek:deepseek-chat"      # 性价比之选
    # primary: "minimax:minimax-m2.5"

6. 编辑服务器信息

编辑 plugins/ArkPilot/SERVER.md，填入你的服务器介绍、规则、经济系统、关键地点等信息。这些内容会被所有 AI 助手共享，用于准确回答玩家问题。

7. 重载配置

在游戏内执行 /ark reload 或重启服务器。

8. 开始使用

在聊天栏输入 @helper 你好 即可开始与 AI 助手对话！

验证安装

1. 进入服务器
2. 输入 /ark 打开助手管理菜单
3. 在聊天栏输入 @helper 你好
4. 如果 AI 正常回复，说明安装成功 ✅

常见安装问题

API Key 未配置

[ArkPilot] 未配置 API Key: anthropic

→ 检查 models.yml 中对应提供商的 API Key 是否正确填写。

模型不可用

[ArkPilot] 主模型不可用，已切换备选模型

→ 检查 API Key 是否有效，以及模型名称是否正确。建议在 defaults.model.fallbacks 中配置备选模型。

插件加载失败

→ 确认使用 Paper 或其 Fork（不支持 Spigot/CraftBukkit），Java 版本 ≥ 8。