助手配置

每个 AI 助手对应 assistants/ 目录下的一个子目录。

目录结构

assistants/
├── player-helper/           # 助手 ID = player-helper
│   ├── config.yml           # 助手配置（必需）
│   ├── SOUL.md              # 助手灵魂/人格（必需）
│   ├── IDENTITY.md          # 助手身份信息（必需）
│   ├── PLAYER.md            # 玩家信息模板（可选）
│   └── skills/              # 助手专属技能（可选）
│       └── my-skill/
│           └── SKILL.md
├── builder/
│   ├── config.yml
│   ├── SOUL.md
│   └── IDENTITY.md
└── my-custom-assistant/     # 你的自定义助手
    ├── config.yml
    ├── SOUL.md
    └── IDENTITY.md

创建新助手

1. 创建目录

assistants/my-guide/

2. 创建 config.yml

enabled: true
id: my-guide
name: "小导"
default: false
description: "服务器导游，带你了解服务器的方方面面。"

model:
  primary: ""          # 留空用全局默认
  fallbacks: []
  temperature: 0.7
  maxTokens: 2048
  thinkingLevel: "off"

tools:
  load:
    - execute-command

executeCommand:
  whitelist:
    - "tp"
    - "warp"
  blockChaining: true

skills:
  load:
    - server-wiki

memory:
  enabled: true
  autoUpdate: true

session:
  maxContextTokens: 8000
  compaction:
    enabled: true
    reserveTokens: 4000
    summaryModel: ""

permissions:
  allowedGroups: []
  deniedGroups: []
  cooldownSeconds: 5
  maxDailyUses: 100

interaction:
  chatTrigger: "@guide"
  npcId: ""
  responseDelay: 500
  streaming: false

3. 创建引导文件

创建 SOUL.md 和 IDENTITY.md，参见引导文件。

4. 重载配置

执行 /ark reload，新助手会立即可用。

config.yml 完整字段

基本信息

字段	类型	必填	说明
enabled	bool	是	是否启用
id	string	否	唯一 ID（默认取目录名）
name	string	是	显示名称
default	bool	否	是否为默认助手（全局只能一个）
description	string	否	助手描述

model — 模型配置

覆盖 models.yml 中的全局默认值。

字段	类型	默认值	说明
primary	string	""	主模型（留空用全局默认）
fallbacks	list	[]	备选模型
temperature	float	0.7	采样温度
maxTokens	int	2048	最大输出 token
thinkingLevel	string	"off"	思维链级别

tools — 工具配置

字段	类型	说明
load	list	需要加载的工具 key 列表

自动加载

skill-read 始终自动加载；memory-read / memory-write 由 memory.enabled 控制。此处只需列出额外需要的工具。

内置工具列表参见工具系统。

executeCommand — 命令执行

仅对 execute-command 工具生效。

字段	类型	默认值	说明
whitelist	list	[]	console 权限命令白名单
blockChaining	bool	true	阻止链式操作符

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

skills — 技能配置

字段	类型	说明
load	list	需要加载的技能名称列表

技能对应 skills/ 目录下的文档，参见技能系统。

memory — 记忆配置

字段	类型	默认值	说明
enabled	bool	true	启用长期记忆
autoUpdate	bool	true	允许 AI 自动记录

session — 会话配置

字段	类型	默认值	说明
maxContextTokens	int	8000	历史最大 token（0 = 用全局默认）
compaction.enabled	bool	true	启用压缩
compaction.reserveTokens	int	4000	压缩保留 token
compaction.summaryModel	string	""	压缩用模型（留空用主模型）

permissions — 权限配置

字段	类型	默认值	说明
allowedGroups	list	[]	允许使用的权限组（空 = 所有人）
deniedGroups	list	[]	禁止使用的权限组（优先于 allowed）
cooldownSeconds	int	5	冷却时间（秒）
maxDailyUses	int	100	每日限额（0 = 无限）

interaction — 交互配置

字段	类型	默认值	说明
chatTrigger	string	—	聊天触发前缀（如 @helper）
npcId	string	""	绑定的 Citizens NPC ID
responseDelay	int	500	回复延迟（毫秒）
streaming	bool	false	流式输出

内部助手

蓝图生成器是一个内部助手的示例——它不直接与玩家交互，而是被其他助手通过 call-agent 工具调用。

内部助手的特征：

• chatTrigger: "" — 无聊天触发
• memory.enabled: false — 不需要记忆
• session.maxContextTokens: 0 — 不需要会话历史
• 权限由调用方控制

配置优先级

助手 config.yml > models.yml defaults > config.yml 全局 > 代码默认值

配置	覆盖来源
模型	助手 → models.yml
会话 token	助手 → config.yml
记忆开关	助手 → config.yml
命令白名单	助手 → config.yml
冷却/限额	助手 → config.yml rateLimit