存储配置 storage.yml

storage.yml 配置 ArkPilot 的数据存储后端。会话历史、记忆、反馈等数据都通过此配置存储。

注意

修改存储类型后需重启服务器生效（不支持热重载）。

存储类型

类型	适用场景	说明
file	单服务器（默认）	数据存储在本地文件，零依赖
mysql	多服 / 跨服	共享 MySQL 数据库，会话和记忆自动跨服同步
postgresql	多服 / 跨服	共享 PostgreSQL，支持更多高级特性

type: file

文件存储（默认）

使用 type: file 时，数据保存在 plugins/ArkPilot/data/ 目录下：

data/
├── sessions/{assistantId}/{playerUUID}.jsonl    # 会话历史
└── memory/{assistantId}/{playerUUID}/           # 记忆文件
    ├── identity.md
    ├── preferences.md
    ├── events.md
    └── todos.md

优点：零配置，无需数据库。

缺点：不支持跨服共享。

MySQL 配置

type: mysql

mysql:
  host: localhost
  port: 3306
  database: arkpilot
  username: root
  password: "your_password"
  params:
    useSSL: false
    characterEncoding: utf8mb4

字段	说明
host	数据库地址
port	端口号
database	数据库名（需提前创建）
username	用户名
password	密码
params	额外连接参数

准备工作

1. 创建数据库：

CREATE DATABASE arkpilot CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. 创建用户并授权（可选）：

CREATE USER 'arkpilot'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON arkpilot.* TO 'arkpilot'@'%';
FLUSH PRIVILEGES;

3. 表结构由插件自动创建，无需手动建表。

PostgreSQL 配置

type: postgresql

postgresql:
  host: localhost
  port: 5432
  database: arkpilot
  username: postgres
  password: "your_password"
  params:
    sslmode: disable

准备工作

CREATE DATABASE arkpilot;

跨服共享

使用 MySQL 或 PostgreSQL 时，多个服务器连接同一数据库即可自动共享数据：

• 会话历史：玩家切服后对话自动延续
• 长期记忆：所有服务器共享同一份记忆
• 数据隔离：仍按 assistantId × playerUUID 隔离

跨服注意事项

1. 所有服务器的 storage.yml 连接同一数据库
2. 助手配置（assistants/）建议各服保持一致
3. 不同服务器的工具可能不同，插件会自动处理历史中不可用的工具调用

数据库表结构

插件自动创建以下表（无需手动操作）：

表名	用途
ark_sessions	会话消息
ark_compactions	会话压缩摘要
ark_memories	长期记忆
ark_feedback	回复反馈评分