助手配置

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

目录结构

assistants/
├── player-helper/           # 助手 ID = player-helper
│   ├── config.yml           # 助手配置（必需）
│   ├── SOUL.md              # 助手灵魂/人格（必需）
│   ├── IDENTITY.md          # 助手身份信息（必需）
│   ├── PLAYER.md            # 玩家信息模板（可选）
│   ├── HEARTBEAT.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

yaml

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: ""
  type: ""
  npcGreeting: ""
  responseDelay: 500
  streaming: false

3. 创建引导文件

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

4. 重载配置

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

config.yml 完整字段

基本信息

字段	类型	必填	说明
`enabled`	bool	是	是否启用
`id`	string	否	唯一 ID（默认取目录名）
`name`	string	是	显示名称
`default`	bool	否	是否为默认助手（全局只能一个）
`internal`	bool	否	标记为内部助手（默认 `false`），详见内部助手
`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	`""`	绑定的 NPC ID
`type`	string	`""`	NPC 后端类型：`citizens` / `adyeshach`，留空自动匹配
`npcGreeting`	string	`""`	NPC 开场白，非空时直接发送而不触发 AI
`responseDelay`	int	`500`	回复延迟（毫秒）
`streaming`	bool	`false`	流式输出

NPC 绑定的完整说明参见 NPC 绑定。

heartbeat — 心跳配置

心跳助手不需要玩家触发，由调度器定时驱动。适用于全局事件主持、巡逻守卫等自主行为场景。

字段	类型	默认值	说明
`enabled`	bool	`false`	启用心跳
`intervalSeconds`	int	`1800`	心跳间隔（秒）
`maxTokens`	int	`2048`	心跳输出最大 token

心跳助手的特征：

chatTrigger: "" — 无聊天触发，仅由定时器驱动
每次心跳接收 "heartbeat" 作为输入，助手通过 HEARTBEAT.md 引导文件决定行为
可配合 HEARTBEAT.md 定义决策流程和行为菜单
工具中应包含 list-online-players、broadcast-message 等全局工具

yaml

heartbeat:
  enabled: true
  intervalSeconds: 300

内部助手

内部助手不直接与玩家交互，而是被其他助手通过 call-agent 工具调用。

在 config.yml 中设置 internal: true 将助手标记为内部助手：

yaml

enabled: true
id: my-internal-agent
name: "内部助手"
internal: true

标记为 internal: true 的助手：

不会出现在 GUI 菜单中 — 玩家在助手列表中看不到它
不能通过聊天触发 — 不参与 chatTrigger 匹配
不能开启私聊模式 — 不出现在 DM 模式可选列表中
不能设置别名 — 不出现在别名选择器中
不能成为默认助手 — 不参与默认助手选举
不能绑定 NPC — 不参与 NPC 路由匹配
管理员可见 — 在系统状态页标记 [内部]

内部助手的典型配置：

internal: true — 标记为内部助手
chatTrigger: "" — 无聊天触发
memory.enabled: false — 不需要记忆
session.maxContextTokens: 0 — 不需要会话历史
权限由调用方控制

仅通过 call-agent 调用

内部助手仍可通过 call-agent 工具按 ID 调用，internal 标记只隐藏面向玩家的交互入口。

配置优先级

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

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

助手配置 ​

目录结构 ​

创建新助手 ​

1. 创建目录 ​

2. 创建 config.yml ​

3. 创建引导文件 ​

4. 重载配置 ​

config.yml 完整字段 ​

基本信息 ​

model — 模型配置 ​

tools — 工具配置 ​

executeCommand — 命令执行 ​

skills — 技能配置 ​

memory — 记忆配置 ​

session — 会话配置 ​

permissions — 权限配置 ​

interaction — 交互配置 ​

heartbeat — 心跳配置 ​

内部助手 ​

配置优先级 ​

助手配置

目录结构

创建新助手

1. 创建目录

2. 创建 config.yml

3. 创建引导文件

4. 重载配置

config.yml 完整字段

基本信息

model — 模型配置

tools — 工具配置

executeCommand — 命令执行

skills — 技能配置

memory — 记忆配置

session — 会话配置

permissions — 权限配置

interaction — 交互配置

heartbeat — 心跳配置

内部助手

配置优先级