# 配置项全表 这份表覆盖插件配置里的**每一项**(共 137 项),键就是配置文件里的完整路径,默认值 = 什么都不配时的行为。设置页里每一项也有同样的中文名与说明,二者由 `test/load-check.mjs` 对账,改配置忘了同步会直接红。 - **怎么改**:DSH 设置页 →「OneBot 枢纽」(行编辑器能拼 JSON 字符串项),或直接改 profile 里本插件的配置。改完大多要重启 DSH / 重载插件才生效(设置页保存会重挂)。 - **表格里的 `—`**:这个键不配(等价留空);**`空`**:配了也是空字符串;**`开`/`关`**:布尔。 - **字符串型 JSON**:名单、白名单、源码范围这些在表里类型是「字符串」,因为配置里存的是 JSON 字符串(`[{"id":"123"}]`),设置页有行编辑器帮你拼。 - **命令能改的**:`chatCommands` 一族里有一部分能在聊天里临时改(人设、模型、权限),但那些是**会话级**的、只管本次唤醒,不是这里的持久配置。 ## 最少要看的四项 | 键 | 为什么先看它 | | --- | --- | | `upstreamListen` | 接哪台 QQ 实现端(二选一) | | `downstreamTargets` | 下游 bot 列表,不接就留空 | | `chatCommands.superUsers` | 谁能用聊天里的管理命令;**留空 = 整条命令链沉默** | | `agent.groups` | 哪些群才调模型;不写 = 全部静音 | ## 总开关 一个开关关掉整条链:不连上下游、不喂模型、不写盘。写 `false` 等于停用本插件。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `enabled` | 开关 | 开 | **总开关**:关掉后整条链静默:不连上下游、不喂模型。profile 里写 false 就等于停用本插件。 | ## 上游:接哪台 QQ 实现端 上游就是真正登录着 QQ 的那台实现端(LLOneBot / NapCat / go-cqhttp…)。**先选连接方式,再填一个地址**:`reverse` 是我们开着端口等它连进来(LLOneBot / NapCat 默认就是这个),`forward` 是我们连到它给的地址。上游账号一般留空让它自动认。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `upstreamMode` | `reverse` / `forward` | 自动 | **连接方式**:`reverse` = 我们监听、实现端拨进来;`forward` = 我们拨出去。留空时按旧配置(下面两个旧键)自动推断,启动日志会提示去确认一次。 | | `upstreamAddress` | 字符串 | 空 | **地址**。反向写 `host:port`(可带路径),如 `127.0.0.1:8765/onebot/v11/ws`;正向写完整地址,如 `ws://127.0.0.1:3001`。**不偷偷补默认路径**:反向写什么就只接受什么。 | | `upstreamUrl` | 字符串 | 空 | 旧键,**已由 `upstreamMode` + `upstreamAddress` 取代**;只在自动迁移时被读取,改它不再生效。 | | `upstreamListen` | 字符串 | — | 旧键,同上;反向的 `host:port/path` 会被迁移成地址。 | | `upstreamSelfId` | 字符串 | 空 | **上游账号**:上游实现端登录的 QQ 号;用来认出"哪条消息是我们自己发的"。留空 = 连上后自动认(握手头 / 事件 / get_login_info),下游"不写对方账号"的目标也会自动跟着它。 | | `upstreamNickname` | 字符串 | 空 | **上游昵称**:上游账号的昵称(备用,昵称识别时用)。 | | `upstreamAccessToken` | 字符串 | 空 | **上游 access token(凭据)**:留空 = 不校验;设了就要求 Bearer 或 ?access_token=。不回显明文。 | ## 上游换成 QQ 官方接口 `upstreamType: official` 之后,上游整个换成 QQ 机器人开放平台(REST + WebSocket),OneBot 实现端(LLBot 等)那一路不再使用;**下游的 OneBot 面照旧**,事件仍然规范成 OneBot v11 的形状往外发。缺凭据(配置里没有、也没扫过码)时按"没有上游"运行,不会半开着连。 上游只有一条,用「类型」表达而不是"官方开/关":早先后者是一个独立开关,扫码绑定只写凭据、不动开关,于是「绑定成功 + 开关没开」这个自相矛盾的状态是能配出来的。老配置里的 `official.enabled: true` 仍然按 official 处理,启动时日志里会提示改选。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `upstreamType` | `onebot` / `official` | `onebot` | **上游类型**:`onebot` = OneBot v11 实现端(LLBot / NapCat 这类);`official` = QQ 官方机器人开放平台。选官方后设置页会隐藏 `upstreamUrl` / `upstreamListen` 等 OneBot 专属项。 | | `official.appId` | 字符串 | 空 | **应用 appId**:QQ 机器人开放平台的 AppID(纯数字)。开放平台只支持接一个机器人,所以这里只填一个。 | | `official.appSecret` | 字符串 | 空 | **appSecret(凭据)**:开放平台的 AppSecret,用来换 access token(有效期约 2 小时,自动续)。不回显明文。 | | `official.sandbox` | 布尔 | false | **沙箱环境**:开 = 连 sandbox.api.sgroup.qq.com(只能在开放平台配置的沙箱群里测试);关 = 正式环境。 | | `official.intents` | 数字 | 0 | **订阅位(实验)**:0 = 用内置的「群与私聊」位(正常别动)。机器人后台开了新能力之后如果收不到群消息,可以填十进制订阅位试试;改完要重启宿主。 | | `official.crossShare` | 布尔 | false | **跨群共享活跃记忆**:官方模式下白名单不生效,所以默认只在同群共享「进行中的话题 / 我正在做的事」;打开才允许跨群可见。 | **不想手抄 appSecret?** 设置页「官方接口」那一组开头有「扫码连接」:用手机 QQ 扫码,枢纽自动拿回 `appId` / `appSecret` 并存进插件状态(`official/credentials.json`),扫完立刻用新凭据重连,不用重启。配置文件里显式写了 `appId` / `appSecret` 的话以配置为准——扫码存的那份只是兜底。 **`agent.groups` / `agent.privates` 这两张白名单在这里不生效**:能收到哪些群与 C2C 由开放平台决定(沙箱群、只允许的群与人),本地再叠一层只会制造"配了却收不到消息";而且本地写的是真 QQ 号、官方通道那边是派生的虚拟号,两边本来也对不上。切回 `onebot` 立刻恢复。上游是官方时,会话目录里私聊那一排改从**档案**取(见过谁就列谁),不依赖配置。 官方通道与 OneBot 上游的差别(接之前值得知道): - **没有 QQ 号**:过来的是 openid / group_openid 字符串,枢纽把它们派生成固定的虚拟数字号(`3e9 ~ 4e9` 段,同一个 openid 永远同一个号,重启也对得上),真身留在事件里的 `source`。群成员列表、群名、`get_msg`、群管理这些**官方不给**,相关工具会明确回"不支持"而不是超时。 - **被动回复有窗口**:收到消息后 5 分钟内、同一个 `msg_id` 最多回 4 次。超了不报错,枢纽会把它降级成主动消息照发(回执里带 `degraded: 'active'`),提示词里也写了这件事。 - **图片和语音要先上传**:官方不吃 OneBot 那种"直接给个地址",得先 `POST /v2/…/files` 换成 `file_info` 再发。枢纽会自动做这步:公网地址直接交上去让官方去拉,本地文件读成 base64。官方不支持图文混排,所以一条"带图的回复"会拆成**文本一条 + 图片一条**;被动回复只挂在第一条上(同一个 `msg_id` 只有 4 次额度,不能被附件吃掉)。**上传失败就整条不发**——不会出现文本发出去了、图丢了。 ## 下游:把事件交给哪些 bot 下游是别的 bot 程序(NoneBot 等)。一条 `downstreamTargets` = 一个下游连接,四种连接方式都支持,可写多条。不接下游就留空——只用 hub 自己聊天完全没问题。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `downstreamAccessToken` | 字符串 | 空 | **下游 access token(凭据)**:校验下游拨入/推事件时的 token,留空 = 不校验。不回显明文。 | | `downstreamTargets` | 字符串 | — | **下游目标(可多条)**:一条 = 一个下游连接。类型四种:ws-dial(我们拨过去)|ws-listen(我们监听、对方拨进来)|http-api(我们提供 HTTP API)|http-post(我们把事件 POST 给对方)。地址统一写 host:port/path(scheme 可省,按类型补 ws:// 或 http://);对方账号留空 = 与上游账号相同;取消勾选 = 这条先不连(配置留着)。空 = 没有下游。可选字段:probeSelfId = 这条目标**自己的探针账号**——写了它就等于一次声明两条链路:主链路照旧,另加一条 probeOnly 的探针链路(**地址与本条相同、只有对方账号不同**,共用本条的地址/口令/下游组,id 是 `~probe`),不用写两条必须互相对齐的条目;下游那侧要按这个账号再连一条(NoneBot 按 self_id 注册,同 id 第二条会被踢掉);probeOnly=true 表示这条链路只收 onebot_invoke 的注入、不收上游真人消息(配合探针隔离的 link 档);downstreamId 用来声明"哪几条链路是同一个下游"(缺省 = 对方账号),状态与时间线都带上它。 | ## 事件怎么投给下游 这一族决定"一条 QQ 消息到达之后,谁能看到、变成什么样"。默认 `relay` 是管理者 + 原样透传;想完全不惊动下游就切 `shadow`。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `preset` | 字符串 | relay | **策略预设**:决定谁管链路、事件怎么投:relay 管理者+透传 / solo(事件不给下游)|shadow(只观察:hub 不叫模型、不代答、不发消息)|bridge(下游 send_msg 真发上游,同时广播给其它下游)|fabric(下游 send_msg 只广播给其它下游,不惊动 QQ)。 | | `deliveryMode` | 字符串 | transparent | **投递模式**:事件投给下游的方式:transparent 原帧重签 / replay 按目标账号重放 / synthesize 合成事件。 | | `broadcast` | 开关 | 开 | **广播到所有下游**:一条入站消息是否投给每条下游链路(关掉只投给首个可用链路)。 | | `readonly` | 开关 | 关 | **只读(hub 不动作)**:打开后 hub 自己绝不动作:不唤醒 agent(不花 token)、不代答聊天命令、也不发消息;事件照旧广播给下游。shadow 预设自带打开;只能打开,关不掉预设自带的那份。 | | `deliverMessageSent` | 开关 | 关 | **也投递 message_sent**:打开后把"自己发的消息"也当事件投给下游(默认关,防回声)。 | | `virtualizeMessageId` | 开关 | 关 | **虚拟化消息 id**:透传时改写 message_id,避免上下游 id 空间撞车;部分下游依赖真实 id,慎开。 | ## 链路维护:超时、重连、防环 纯机械参数。默认值对本地网络都够用;跨机器部署再按链路质量调。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `reconnectInterval` | 数字 | 5000 | **重连间隔(ms)**:下游断线后多久重拨一次。 | | `requestTimeout` | 数字 | 30000 | **action 超时(ms)**:等实现端回 echo 的上限,超时返回 1200 错误。 | | `heartbeatTimeout` | 数字 | 120000 | **心跳超时(ms)**:监听端多久没收到任何帧就判定上游掉线并断开。 | | `downstreamHeartbeatMs` | 数字 | 30000 | **下游心跳间隔(ms)**:枢纽主动向下游发心跳的频率。 | | `echoWindowMs` | 数字 | 3000 | **echo 配对窗口(ms)**:回合配对时,在这段时间内找下游的应答。 | | `maxHop` | 数字 | 3 | **最大跳数**:防环:事件已带的跳数达到它就停止转发。 | ## 探针隔离(试探下游时别污染真人群) agent 用 `onebot_invoke` / `onebot_relay_probe` 试探下游命令时,注入的消息要不要和真人消息隔开。默认 `off`(不隔离);要隔离就在下游目标里补一个 `probeSelfId`。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `probe.isolation` | 字符串 | off | **探针隔离**:agent 用 onebot_invoke 试探下游时怎么和真人消息隔开。off(默认)=不隔离,注入与真人消息走同一条链路;time=探测窗口内该会话的上游消息暂缓投下游、窗口一到按原序补发(不需要额外配置);link=上游消息一条都不投给探针链路、注入只走那条——探针链路要在下游目标里填 **probeSelfId**(同一个下游的另一个 bot 账号,地址不用改),一个都没配时这一档会**自动回退到 off**。开了链路隔离后,探针结果**可能与用户触发时不同**(这条会写进给 agent 的指导段与每次注入的结果里)。 | | `probe.windowMs` | 数字 | 8000 | **探测窗口(ms)**:time 档:注入之后多久算这个会话的独占窗口。窗口内的真人消息只是晚到,不会丢。 | | `probe.maxQueued` | 数字 | 50 | **窗口排队上限**:安全阀:排到这个数就立刻按原序补发,绝不吞消息。 | | `probe.capture` | 开关 | 开 | **探针链路只捕获不转发**:link 档:探针链路的 send_* 只记进时间线/捕获账本,不真的发到 QQ——探针产物先给 agent 看,要不要说由它决定(默认开)。 | ## 证据与保留(能查到什么、能留多久) 收到的每条消息都会留原文与索引(默认 7 天),agent 排查时用 `onebot_raw` 自己取原文解析。这是"不靠猜"的地基。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `retention.days` | 数字 | 7 | **原始报文保留天数**:收到的每条消息都会缓存原文 + 索引(包括 hub 解析不了的段、以及**不展开**的聊天记录),agent 需要时自己取原文解析。超过这么多天自动清掉:落盘的原始报文日文件、索引里的旧行、以及媒体 blob。**0 = 不清理**。 | | `retention.cleanupIntervalMs` | 数字 | 21600000 | **清理间隔(ms)**:多久跑一次保留期清理(默认 6 小时)。 | | `retention.firstRunDelayMs` | 数字 | 20000 | **首次清理延迟(ms)**:启动后隔多久跑第一次。清理是 O(数据量) 的 IO(扫日文件、扫 blob、批量删索引行),所以它**不在启动路径上**——`m21653` 之前是同步跑的,真机启动耗时因此每天长一点(6 ms → 2.5 s)。调小只影响"多久之后开始清",不影响启动。 | | `persist` | 开关 | 开 | **落盘**:关掉后时间线/记忆/表情包都不写盘,重启即空(调试用)。 | | `storageDir` | 字符串 | 空 | **存储目录**:留空 = 用宿主 profile 下的默认目录;所有 jsonl 与媒体 blob 都在这里。 | | `logFrames` | 开关 | 关 | **打印帧日志**:打开后每个 OneBot 帧都写日志,排查用(量很大)。 | ## agent:什么时候醒、说什么、发几条 这一族是拟人化的行为面,也是最常调的一族。默认配置下它很安静:群里没人叫它就不插话。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `agent.mode` | 字符串 | assist | **代理模式**:assist 平时休眠、被叫到才醒(醒了就持续参与一会儿)/ observer 只看不说(不喂模型)/ active 休眠时每 5 分钟看一眼有没有新消息。 | | `agent.batchSize` | 数字 | 10 | **一批最多几条**:激活状态下攒够这么多条就唤醒一次;休眠时收到的话只是攒着(下次醒来一起看)。 | | `agent.batchMs` | 数字 | 20000 | **攒批等待(ms)**:激活状态下从第一条新消息算起,等这么久就把这一批交给模型。 | | `agent.maxActive` | 数字 | 8 | **同时活跃的会话数**:超过就按最近活跃淘汰,防会话池无限涨。 | | `agent.idleDisposeMs` | 数字 | 1800000 | **空闲回收(ms)**:会话多久没动静就释放它的 agent(下次再建)。 | | `agent.tickMs` | 数字 | 1000 | **调度节拍(ms)**:批量窗口、激活超时与社交能量的检查频率。 | | `agent.silenceWhenDownstreamResponded` | 开关 | 开 | **下游答过就闭嘴**:打开后下游 bot 已应答的消息不再喂模型(命令静默)。 | | `agent.wakeOnPrivate` | 开关 | 开 | **私聊也唤醒**:打开时私聊每条都算被叫到(立刻醒);关掉后私聊只转发、不叫模型。 | | `agent.wakeOnNotice` | 开关 | 关 | **通知类也唤醒**:戳一戳、群名片变更等 notice 是否也叫模型(默认关)。 | | `agent.speakAssistantText` | 开关 | 关 | **把回复文本当发言(老行为)**:默认关:发言一律走 onebot_reply 工具,模型写在回复里的文字只是内部草稿、不发进聊天;打开才恢复『文本兜底=发言』的老行为。 | | `agent.awakeMs` | 数字 | 300000 | **激活空转上限(ms)**:最后一次有人说话或它自己回话之后,这么久两边都没动静就回到休眠;0 = 不超时(一直挂着激活状态)。 | | `agent.activeTickMs` | 数字 | 300000 | **active 判断间隔(ms)**:active 档休眠时每隔这么久看一眼该会话有没有新消息,有就唤醒一次。 | | `agent.unattended` | 字符串 | deny | **没人看着时碰到确认怎么办**。非 `ask` 时,枢纽在建会话那一刻就把会话审批策略写成 `never`(`approval/policy` 事件)——模型**拿不到** `sandbox_permissions` 参数,沙箱被拒时也不会收到"可以重试提权"的提示,提权这条路从工具面上消失。`deny` / `auto` 只影响旧的审批监听兜底是拒绝还是自动同意;`ask` = 老行为,挂着等人。只对枢纽自己拉起的群/私聊会话生效,用户自己开的会话不动。 | | `agent.permissionPreset` | 字符串 | 空 | **枢纽会话的权限预设**。留空 = 用 DSH 的默认预设;填了(例如 `danger-full-access`)就在每次建会话时设给枢纽会话。它管的是"沙箱有多宽",与上面拆掉提权入口是两件事——沙箱太窄干不了活(起不了子进程、写不了别的目录)时改这一项,而不是放开审批。预设名认不出来只记日志,不影响建会话。 | | `agent.guidance` | 字符串 | 空 | **追加指导(每轮注入)**:写在这里的话每轮都作为系统段进模型,用来调语气、加规矩。 | | `agent.defaultModel` | 字符串 | 空 | **默认聊天模型**:留空跟 DSH 系统默认路由;从 DSH 的模型清单里选一个就以它为默认,会话里 /model default 也复位回它。清单取不到时退回手写。 | | `agent.defaultVisionModel` | 字符串 | 空 | **默认识图模型**:留空用系统默认模型;选一个就以它为看图默认,会话里 /vmodel 仍然可以覆盖。 | | `agent.defaultReasoningEffort` | 字符串 | 空 | **聊天思考强度**:跟上面那个模型配对;档位从该模型的 reasoning 里出(上游 DSH 没给它声明档位就不列)。留空 = 模型自己的默认。 | | `agent.defaultVisionReasoningEffort` | 字符串 | 空 | **识图思考强度**:跟默认识图模型配对,同上;留空 = 模型自己的默认。 | | `agent.groups` | 字符串 | [] | **群白名单**:只有列出的群才会调模型(没列的群 @ 也不理);每条可单独选模式,留「跟随全局」就用上面的代理模式。**上游是 `official` 时不生效**(见下)。 | | `agent.privates` | 字符串 | [] | **私聊白名单**:只有列出的 QQ 号才会调模型;同样可单独选模式。两张名单都是白名单制:清空 = 全部静音。**上游是 `official` 时不生效**(见下)。 | | `agent.steer` | 开关 | 开 | **激活期插话**:打开时,回合没跑完就来的新消息会直接插进正在进行的回合(模型下一步就能看到);关掉则排队等这一轮说完再看。 | | `agent.tasks.enabled` | 开关 | 开 | **定时任务**:打开后模型可以给自己排提醒(`onebot_task`),到点由枢纽叫醒那个会话,说什么由它自己定。宿主没有 `schedule` 服务时这项无效。 | | `agent.tasks.resetEvery` | 数字(次) | 0 | **总机会话轮换**:定时任务共用一个永不回收的总机会话,每次触发上下文都会增长。填 N 表示累计触发 N 次后换一条新会话并把所有排期搬过去;0 = 永不轮换。 | | `agent.replyGapMs` | 数字 | 400 | **多条消息的间隔(ms)**:一次 onebot_reply 拆成多条时,条与条之间等这么久(像人在一句句打字)。0 = 连发不带停顿。 | | `agent.replyMaxText` | 数字 | 3 | **一次回复最多几条文字**:只限文字消息的条数——图片不占额度(图另有上限)。超出部分不发送,并在工具回执里如实告知模型。 | | `agent.replyMaxImages` | 数字 | 9 | **一次回复最多几张图**:图片/表情包的条数上限(每张各自发一条消息)。0 = 不限。 | | `agent.workspace` | 字符串 | 空 | **会话工作区路径**(绝对路径)。留空=用宿主进程的 cwd、且**不挂进任何工作区**(默认:会话在 DSH Web 里落到「未分类」)。填了就把它当会话 cwd,并在建完会话后把这个 id 挂进该路径对应的**已登记**工作区;**没有对应工作区时自动建一个**(标题取路径末段)。路径会先规范化(`realpath`)再比对——尾分隔符、盘符大小写、junction/symlink 差一点,宿主就认不出是同一个目录,会话照样落到「未分类」。目录不存在/不是目录时**不报错也不挂**:退回宿主进程 cwd,原因写进 `onebot_hub_status` 的 `host.workspaceAttach.last`。注意 hub 每次激活都换一个新会话 id,所以每次激活都会重新挂一次。 | | `agent.archiveOnRetire` | 开关 | 开 | **激活结束时归档会话**。默认开(会话从活跃列表挪进归档)。关掉=不归档,会话留在 DSH 会话列表里(也因此能 pin);代价是**每次激活都会多留一条会话**(id 每次激活都换)。 | | `agent.hidePromptSections` | 文本 | 空 | **遮蔽别的插件塞进提示词的段落**。逗号分隔的段落名,默认空=谁都不遮蔽。宿主把提示词分成「全局层 + agent 层」,**同名时 agent 层盖掉全局层**,所以填进去的名字在枢纽会话里那一段会变成空文本(`renderPrompt` 会把空段整段过滤掉),别的会话不受影响。典型用例:`raw-html-v2:vcp`——那是给人看的 HTML 渲染协议,QQ 里只有纯文本,白占 token 还可能诱导模型吐标签。名字由对方插件定,它改名后这里会**静默失效**(没有任何报错)。 | | `agent.keepTools` | 文本 | 空 | **额外放行的全局工具**。逗号分隔的工具名,默认空=不改现有白名单。枢纽会话的全局工具是「白名单式」遮罩(`defaultToolDeny` 只留 11 个原生工具、`onebot_*`、插件生图/语音工具,其余全遮),填进来的名字会被放回工具面。两个前提:**拼错的名字会被静默忽略**(宿主 `restrict()` 对未知名字当场抛错,不能让整轮挂掉,所以只认当下真实存在的名字,并记一行日志;晚注册的工具下一轮重算时自己进来);**放行 ≠ 能用**——工具的 provider 服务得在 profile 里。把 `bash`/`write` 这类放进群聊场景前请想清楚:模型会在群消息的驱动下调用它。 | | `agent.replyOnSendFailure` | 开关 | 开 | **发送失败当场告知模型**。回复没发出去时立刻排一次唤醒把失败递回去(说清第几条没发、后面几条也没发),agent 能当场重试——不用等"下一轮",而群里没人再说话时那一轮可能永远不来。关掉=退回老行为(下一批开头告知)。 | | `agent.sendFailureNudgeMax` | 数字 | 2 | 同一会话在 `sendFailureNudgeWindowMs` 窗口内最多自动重开几次。撞上限退回"下一批开头告知",防止"重试→又失败→又收到回执"自我转圈。0=从不自动重开。 | | `agent.sendFailureNudgeWindowMs` | 毫秒 | 300000 | 上面那个次数的统计窗口(默认 5 分钟)。 | ### 分群额度(每个群/私聊各记各的) 额度**不再有全局块**,就在 `agent.groups` / `agent.privates` 白名单里**逐行配**:某行写了 `quota` 就按那行算,没写就是这个会话不限。设置页每行有张「额度」折叠面板(口径、单价、限额、报数口径都在里面),行标题旁还会挂个徽标写明"按 token · 每日 1000"之类。记账按本地自然日/自然月,`.quota` 命令随时能查(`.quota reset` 追加解限额度,`.quota reset 50000` 也可)。账本只存输入/缓存/输出三元组原值,**钱是读取时现算的**——改单价、换口径都自动重算历史账。 用尽之后(第二期,m13831):那一批**只进记忆、不调模型**(退成 observer,群里照常看得见发生过什么,不会丢档);同时被 @ 就替模型回一句固定话术(`onExhaust`)。攒下的消息不会烂在窗口里——恢复后下一轮会把**期间攒下的最近 20 条原话**补在开头(只补一次,超过 60 条丢最旧的并注明丢了多少),免得模型回来时对群里的事一无所知。报数行受 `noticeCooldownMs` 冷却防刷屏,但**快用完/已用完时不冷却**(那正是模型该知道的时候)。 行内字段(`quota` 对象,全部可选;**限额全是 `0` 或不写 = 不限**): | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `agent.groups[].quota.enabled` | 开关 | 关 | **这一行要不要记账**:关着就是不设额度(面板里的值会被收起来不写进 JSON)。 | | `agent.groups[].quota.unit` | 字符串 | token | **计算方法**:`token` = 输入+缓存+输出合算(不区分输入输出);`cost` = 按下面自填单价折钱。 | | `agent.groups[].quota.tokensPerDay` | 数字 | 0 | **每日 token 上限**:按本地自然日重置;0 = 不限。 | | `agent.groups[].quota.tokensPerMonth` | 数字 | 0 | **每月 token 上限**:按本地自然月重置;0 = 不限。日与月谁先到听谁的。 | | `agent.groups[].quota.costPerDay` | 数字 | 0 | **每日花费上限**:`unit:'cost'` 时才看,单位是 `currency` 那个币种;0 = 不限。 | | `agent.groups[].quota.costPerMonth` | 数字 | 0 | **每月花费上限**:同上,按本地自然月重置;0 = 不限。 | | `agent.groups[].quota.currency` | 字符串 | CNY | **币种**:只影响账本显示与文案,不做换算。 | | `agent.groups[].quota.price.input` | 数字 | 0 | **输入单价(每百万 token)**:群里自填;改了自动按新价重算历史账。 | | `agent.groups[].quota.price.cache` | 数字 | 0 | **缓存单价(每百万 token)**:命中缓存那部分的单价。 | | `agent.groups[].quota.price.output` | 数字 | 0 | **输出单价(每百万 token)**:通常最贵的一项。 | | `agent.groups[].quota.notice` | 字符串 | detail | **报数口径**:`detail` = 每批末尾给已用/限额/剩余;`percent` = 只给剩余百分比;`off` = 不出声。 | | `agent.groups[].quota.noticeHint` | 开关 | 开 | **顺带提醒模型省着点**:剩余不足时在给模型的指导里提一句,让它自己收着回话。 | | `agent.groups[].quota.onExhaust` | 字符串 | notice | **用尽后的行为**:`notice` = 被 @ 时回一句额度用完;`silent` = 一个字都不发。 | | `agent.groups[].quota.exhaustedReply` | 字符串 | 本群今天的额度已经用完了,我先歇会儿,明天 00:00 自动恢复。 | **用尽时的回话**:额度用完且有人 @ 时,替模型发出去的那句固定话术(受 `noticeCooldownMs` 限流)。**不填或留空 = 用上面那句默认**;想彻底闭嘴请把 `onExhaust` 设成 `silent`。 | | `agent.groups[].quota.noticeCooldownMs` | 数字 | 600000 | **报数冷却(ms)**:两次报数之间至少隔这么久,防话痨群刷屏;快用完/已用完时豁免。设置页里填的是**秒**。 | | `agent.groups[].quota.superuserBypass` | 开关 | 关 | **超管 @ 也照常记**:默认关——超管 @ 不绕过额度;打开后超管 @ 照常调模型(记账照旧)。 | `agent.privates` 里的 `quota` 结构一模一样。私聊同样支持额度(配在 `agent.privates` 行里)。 ## 能力闸门(谁能写、能不能探测) 安全面:写操作与危险 action 默认**拒绝**,工具不能绕过这里的闸门。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `actionPolicy` | 字符串 | {} | **action 策略(JSON)**:JSON:逐 action 的允许/拒绝规则(与 capability 白名单一起生效)。 | | `capability.writeAllow` | 字符串 | [] | **写操作白名单(JSON)**:JSON 数组:允许下调的写级 action(如 send_msg);空 = 全部拒绝。被拒时对发消息类动作会多指一句"跨会话递内容用 `onebot_session`,不必为此放行 write"。 | | `capability.dangerAllow` | 字符串 | [] | **危险操作白名单(JSON)**:JSON 数组:踢人/禁言/退群一类;空 = 全部拒绝。 | | `capability.exposeSensitive` | 开关 | 关 | **回显敏感字段**:打开后只读查询里带 token 之类字段(默认关,防泄漏)。 | | `capability.cache` | 开关 | 开 | **只读查询缓存**:打开后 get_group_info 之类有 TTL 缓存,返回里 source=cache。 | | `capability.probe` | 开关 | 开 | **主动探测能力**:启动后自测哪些 action 可用,结果进 onebot_caps。 | | `capability.downstreamReads` | 开关 | 开 | **下游只读查询**:允许把下游链路也当作实现端来查。 | | `capability.callTimeoutMs` | 数字 | 15000 | **只读查询超时(ms)**:单次 action 调用的等待上限。 | | `capability.probeTimeoutMs` | 数字 | 8000 | **探测超时(ms)**:能力自测里每个 action 的等待上限。 | ## 媒体落地(图片语音怎么存) 收到的图片/语音/文件会落成 durable 引用,上游给的 URL 会过期、引用不会。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `media.enabled` | 开关 | 开 | **媒体落地**:关掉后图片/语音/文件都不落地,也就没有 durable ref。 | | `media.keepBytes` | 开关 | 开 | **保留原始字节**:打开后 blob 存字节,上游 URL 过期也不影响引用。 | | `media.transcribe` | 开关 | 开 | **语音转写**:试实现端的转写能力;拿不到就如实说"听不了",不猜内容。 | | `media.maxBytes` | 数字 | 8388608 | **单文件字节上限**:超过就只记元信息不落地、不进宿主附件(语音/视频/文件走这条)。图片不受此限:大图总会落 blob(识图要原图,超大的图看图前会先压小),只是不进模型主请求。 | | `media.fetchTimeoutMs` | 数字 | 5000 | **取媒体超时(ms)**:下载图片/语音的等待上限。 | ## 回合配对(谁的消息引发了谁的回复) 纯协议层观测,用来回答"这条消息触发下游做了什么"。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `turns.windowMs` | 数字 | 8000 | **配对窗口(ms)**:入站消息之后多久内,下游的 send_* 才算它触发的。 | | `turns.retain` | 数字 | 400 | **保留回合数**:内存里最多留多少条回合记录。 | ## 用法学习(下游会吃什么命令) 机械观测:只有下游**真的响应过**的消息才算一次证据,够阈值才升 `active`。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `learn.threshold` | 数字 | 3 | **几次观测算数**:下游真响应过 N 次,才把这条用法升为 active。 | | `learn.staleAfter` | 数字 | 3 | **几次没复现降级**:连续 N 次未复现就标 stale、降置信。 | | `learn.forgetAfter` | 数字 | 6 | **几次没复现删除**:连续 N 次未复现才真正从表里删掉。 | | `learn.maxEvidence` | 数字 | 20 | **每条最多留几条证据**:证据是"哪条消息触发了什么",用于回看。 | ## 代码范围与群资料 `code.scopes` 只告诉 agent 源码在哪,不给它工具;`cards`/`members` 决定要不要把群资料和成员表抓下来备查。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `code.scopes` | 字符串 | [] | **下游源码范围(可多条)**:一条 = 一个下游的源码在哪(可能有多个下游)。备注可空。**这些路径不写进 prompt**:agent 需要时调 onebot_code_scopes 取位置,读文件用它自己带的工具(read/grep/glob)——枢纽不代读、也不需要配扫描器。权限由超管在会话里给(或 /perm)。空 = agent 问位置时如实说没配。 | | `cards.maxLines` | 数字 | 40 | **会话卡最多几行**:每张会话卡保留的行为条数。 | | `cards.maxSessions` | 数字 | 200 | **最多几张会话卡**:超过按最久没用的淘汰。 | | `members.enabled` | 开关 | 开 | **按需解析成员名**:at 到还没名字的人时问一次实现端(比一直叫"用户10002"强)。 | | `members.cooldownMs` | 数字 | 21600000 | **同一人冷却(ms)**:多久之内不再为同一个人问名字。 | | `members.maxPerMessage` | 数字 | 5 | **每条最多问几个**:一条消息里最多解析几个陌生人,防刷。 | | `members.maxQueue` | 数字 | 50 | **排队上限**:待解析队列满了就丢弃新的。 | ## 识图(图片怎么变成模型看得懂的话) 默认 `describe`:把图交给视觉模型写成人话再进上下文,图本身不进请求。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `vision.mode` | 字符串 | describe | **看图模式**:describe 让视觉模型给描述 / segment 只把图片段交给会话模型 / both / off。识图模型默认用系统默认模型,要按会话换就用 `vmodel` 命令(前缀见「聊天管理命令」那节)。 | | `vision.prompt` | 字符串 | 空 | **用户侧提示词**:给视觉模型的图描述要求;留空用内置中文提示。 | | `vision.system` | 字符串 | 空 | **系统提示**:视觉模型的 system 段。 | | `vision.maxTokens` | 数字 | 0 | **单次最多输出 token**:0 = 不传该参数(默认,描述不做长度控制);填 >0 才给单次生成加上限。 | | `vision.timeoutMs` | 数字 | 30000 | **超时(ms)**:等描述的上限,超时就放弃并如实说明。 | | `vision.cacheLimit` | 数字 | 500 | **缓存张数**:按 sha256 缓存描述,同一张图不重复问。 | | `vision.segmentWaitMs` | 数字 | 1500 | **`segment` 模式回合开始前最多等图片落地多久**(ms)。图和文字走两条路:文字立刻进时间线,图片要先下载、存 blob、回填 `entry.media`,通常晚几百毫秒。这一项让快照等它落地——否则装配 prompt 时拿不到图片段,模型只看得到占位。只开 `describe` 时不影响任何行为。 | | `vision.waitBeforeTurnMs` | 数字 | 4000 | **回合开始前最多等识图多久**(ms,0=不等)。图片消息进上下文时正文只能是「[图片(还在看)]」,这一项让回合在装配 prompt 之前等描述回来——否则模型看到占位就只会答"我看不到图"。超时后描述会在下一轮以【图片补描】补上,模型也可以调 `onebot_image_wait` 再等一次。等的时候只等**这一批**的图,失败立刻放行。 | ## 人设(agent 是谁) 名字、性格、说话风格。可以按群套不同预设。 **预设库不在这张表里**(`m24027` 起):它只有一份权威 —— `/persona/presets.json`。空库第一次启动时会自带两条:**「小助手」**(默认人设)和**「蓝色大肥鱼」**(一个完整成品人设,8 条知识)。自带的那几条只补缺的——你改过就按你改的、删掉就不会再被启动复活。改法三种: 1. **设置页「人设与预设」**那块面板(最省事):下拉选**默认人设**(没绑定过角色的会话都用它)、「编辑 JSON」改选中的那一条(`{name, role, knowledges}`),还能新建/删除。改完立即生效、重启还在。 2. 群里敲 `/set_preset <预设名>`:只把**当前会话**切过去(落 `bindings.json`)。 3. `/set_role` 或 `/preset_role`:给当前会话复制一份私有分叉 `@session/<会话>`,不影响共用预设。 > 以前有 `persona.defaultName` 与 `persona.presets` 两个配置项,已在 `0.11.0` 删掉。它们只在**第一次启动**有意义,之后一概被 `presets.json` 覆盖;而 `presets` 那个"种子"是每次启动重写一遍的,于是设置页里改过的同名预设会在重启后被打回去。旧配置里还留着这两项不会报错,启动日志会提示一句该去哪儿改。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `persona.enabled` | 开关 | 开 | **人设**:关掉后没有角色设定段,模型按默认风格说话(这时设置页那块面板也停用,但群里的 `/presets`、`/set_role` 仍可用——它们操作的是文件)。 | ## 聊天管理命令(人打的那几条) 这些命令只认消息文本、完全不经过模型,触发者必须是 `superUsers` 里的账号。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `chatCommands.enabled` | 开关 | 开 | **聊天管理命令**:关掉后 `status` 一类命令不再由枢纽处理(消息照常转发给下游)。 | | `chatCommands.prefix` | 字符串 | / | **命令前缀**:命令名本身固定,前缀换成什么都能用(配成 `!` 就敲 `!help`);只认**句首**前缀。它是公共前缀,下游有同名命令也照常触发,枢纽不抢。 | | `chatCommands.bypassPrefix` | 字符串 | !! | **让路前缀**:加在原命令前面,枢纽连那条回话都不要、当普通消息走(默认前缀下如 `!!/reset`)。 | | `chatCommands.superUsers` | 字符串 | [] | **超管名单(JSON)**:JSON 数组,如 ["10001"];空 = 整条链沉默(不猜谁是管理员)。 | | `chatCommands.maxReplyChars` | 数字 | 1500 | **回话长度上限**:超长就截断,防刷屏。 | ## 表情包库 收哪张由 agent 自己决定;这里管容量、每次最多发几张、进上下文列几个。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `memes.enabled` | 开关 | 开 | **表情包库**:关掉后不收集也不发送表情。 | | `memes.topK` | 数字 | 50 | **上下文里列几张**:装配 prompt 时最多列几个候选 id。 | | `memes.newShown` | 数字 | 10 | **新入库额外列几张**:新收录、还没用过的表情包(`uses` 为 0)在清单里额外列几个,`0` = 不列(回到旧行为)。它们单独排在最后并标【新入库】。没有这一段的话,新图永远排在「常用」后面——库满了 `topK` 之后它连一次都进不了清单,模型想不起来用。 | | `memes.maxSend` | 数字 | 3 | **一次最多发几张**:单条回复里的表情数量上限。 | | `memes.maxCount` | 数字 | 200 | **库容量上限(张)**:超过后自动淘汰最少用、最久未用的;最近用过的几张受保护。改动重启后生效。 | | `memes.autoCollect` | 开关 | 开 | **允许收录**:关掉后 agent 也不许收录表情包(库只读)。收集本身由 agent 判断,不自动收。 | | `memes.engine` | 文本 | `builtin` | **表情包来源**:`builtin` 用枢纽自带的库;`plugin` 整个交给第三方插件(自带库下线:清单不注入、`onebot_memes` 不注册、`reply` 的 `memes` 参数不可用);`both` 两套并存。 | | `memes.pluginTool` | 文本 | 空 | **第三方表情工具**:`plugin`/`both` 下要放行的工具名,逗号分隔。留空则按关键词(meme/sticker/表情)从实时工具表里自动探测全部命中的;探测不到就是“没有可用工具”,不降级。 | ## 番剧识别(图片补角色名) 接动漫识别后端给图片补一行角色名;默认关。认不出就说认不出,不编造。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `anime.backend` | 字符串 | off | **识番后端**:off 完全关 / anime-recognize 本地 / animetrace 线上 / both 本地优先。 | | `anime.recognizeUrl` | 字符串 | 空 | **本地识别接口**:anime-recognize 服务的地址。 | | `anime.recognizeToken` | 字符串 | 空 | **本地识别 token(凭据)**:留空 = 不带鉴权头。不回显明文。 | | `anime.animetraceUrl` | 字符串 | https://api.animetrace.com | **AnimeTrace 地址**:默认官方接口,可换自建。 | | `anime.minConfidence` | 数字 | 0.85 | **置信度下限**:低于它不报角色名(宁缺毋滥)。 | | `anime.maxCharacters` | 数字 | 1 | **最多报几个角色**:超出按置信度截断。 | | `anime.nsfwThreshold` | 数字 | 0.5 | **NSFW 阈值**:超过就不发识别结果(防翻车)。 | | `anime.timeoutMs` | 数字 | 15000 | **超时(ms)**:识别请求的等待上限。 | | `anime.cacheLimit` | 数字 | 500 | **缓存张数**:按 sha256 缓存识别结果。 | ## 生图(让 agent 自己画) 默认关,必须配 `model`/`baseUrl`/`apiKey` 才开;生成后**不自动发群**,由 agent 决定要不要发。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `imageGen.enabled` | 开关 | 关 | **生图**:默认关;开了还要配 model/baseUrl/apiKey,缺一个仍是关。 | | `imageGen.model` | 字符串 | 空 | **模型名**:OpenAI 兼容生图接口的模型 id。 | | `imageGen.baseUrl` | 字符串 | 空 | **接口地址**:形如 https://…/v1(不要带 /images/generations)。 | | `imageGen.apiKey` | 字符串 | 空 | **API Key(凭据)**:留空 = 不改。不回显明文。 | | `imageGen.maxSize` | 字符串 | 2560x1440 | **尺寸上限**:形如 2560x1440;请求的 size 会等比内缩到它以内。 | | `imageGen.minSize` | 字符串 | 空 | **尺寸下限**:留空 = 不设下限。 | | `imageGen.watermark` | 开关 | 关 | **加水印**:非 OpenAI 官方参数,默认不发;显式开启才透传 watermark 给支持它的中转接口。 | | `imageGen.timeoutMs` | 数字 | 120000 | **超时(ms)**:生图等待上限(图确实慢,默认给得很宽)。 | | `imageGen.maxPerTurn` | 数字 | 1 | **每轮最多几张**:一轮对话里的硬上限,超了明确说"这轮画完了"。 | | `imageGen.engine` | 字符串 | builtin | **生图引擎**:builtin=hub 自带的 OpenAI 兼容生图(默认);plugin=不自己生图,把第三方插件的生图工具放进 agent 工具面。 | | `imageGen.delivery` | 字符串 | agent | **生成后发送时机**:agent(默认)=生成后由 agent 决定发不发群;direct=生成完立刻直发到指定会话。 | | `imageGen.plugin.tool` | 字符串 | 空 | **第三方生图工具名**:engine=plugin 时用;逗号分隔或数组。留空=自动探测(generate_image 等已知名单)。 | | `imageGen.plugin.timeoutMs` | 数字 | 180000 | **探测/后处理超时(ms)**:预留的后处理等待上限,当前主要留作扩展。 | ## 语音合成(`tts.*`) 地址是**一整个 URL**、请求体形状可选:`onebot_reply` 里写 `{"type":"tts","text":"…"}` 就在发送前当场合成语音。音色不枚举(兼容服务的自定义音色直接填);要"照这个声音读",给一段参考音频即可(字段名可配,各家不一样)。 `provider` 是**服务商下拉**:选了哪家,**接口地址与请求形状**由它决定(这两格会藏起来,`tts.url` / `tts.shape` 只在 `custom` 下生效),**这一家不用的参数也不会显示**(`appId`/`cluster` 只在豆包、`groupId` 只在 MiniMax、`resourceId` 只在方舟)。**模型仍然可以换**:`tts.model` 每家都显示、手填,留空用预设默认——同一家常有多档(`speech-02-hd`/`turbo`、`voicedesign`/`tts`),不让人换等于把选择成本还回去。想连地址一起自己填(自建中转、同一家的另一区域)就把服务商切回 `custom`,那时填的才算数;旧值不会被清掉,切回来还在。`custom`=全自己填,`plugin`=枢纽不合成、把第三方插件的语音工具放进模型工具面(和生图的 `engine: plugin` 同一条纪律)。 | 服务商 | `provider` 取值 | 地址 | 形状 | 默认模型 | | --- | --- | --- | --- | --- | | OpenAI 官方 | openai | `https://api.openai.com/v1/audio/speech` | `speech` | (自己填 `tts-1` / `gpt-4o-mini-tts`) | | 小米 MiMo(Token Plan) | mimo | `https://token-plan-cn.xiaomimimo.com/v1/chat/completions` | `chat` | `mimo-v2.5-tts` | | 小米 MiMo(按量付费) | mimo-pay | `https://api.xiaomimimo.com/v1/chat/completions` | `chat` | `mimo-v2.5-tts` | | MiniMax(国内站) | minimax | `https://api.minimax.chat/v1/t2a_v2` | `minimax` | `speech-02-hd` | | MiniMax(海外站) | minimaxi | `https://api.minimaxi.com/v1/t2a_v2` | `minimax` | `speech-02-hd` | | 火山方舟(Agent Plan) | ark | `https://openspeech.bytedance.com/api/v3/plan/tts/unidirectional` | `ark` | —(`X-Api-Resource-Id` 默认 `seed-tts-2.0`) | | 火山引擎(豆包语音 V1) | doubao | `https://openspeech.bytedance.com/api/v1/tts` | `doubao` | —(填 `tts.appId` + `tts.cluster`) | | 第三方插件 | plugin | —(不打请求) | `plugin` | —(用 `tts.plugin.tool`) | 同一家的不同计费方式(小米的 Token Plan / 按量付费、MiniMax 的国内 / 海外站)**各是一个选项**:地址与 Key 都不通用,跨着用报的是鉴权错,看起来像 Key 失效。 `shape` 一共六档:`speech` 是 OpenAI `/audio/speech` 那一套(`input` + `voice` + `response_format`);`chat` 是把要读的话放进 `messages` 里一条 `assistant`(MiMo 那种,`instructions` 会作为一条 `system` 消息带过去);`minimax` 是 `text` + `voice_setting`/`audio_setting`,**返回 hex 编码的音频**(老账号要 `?GroupId=`,填 `tts.groupId` 即可);`doubao` 是 `app`/`user`/`audio`/`request` 四段,鉴权头写 `Authorization: Bearer; `(分号不是空格),`apiKey` 当 token、`tts.appId` 当 `app.appid`;`ark` 是方舟 Agent Plan 的 `req_params:{text,speaker,audio_params}`,头里认 `X-Api-Key` + `X-Api-Resource-Id`(**不用 Bearer**),返回是**分块 JSON 流**(每行一个对象,`data` 是 base64 片段,`code:20000000` 结束),音色字段叫 `speaker`;`plugin` 不打请求。**路径与请求体都要对上**——只改路径不改形状,只会从 404 变成 400;返回里没有音频时,错误会把实际收到的顶层字段列出来,照着改。 | 键 | 类型 | 默认 | 说明 | | --- | --- | --- | --- | | `tts.enabled` | 布尔 | false | **语音合成**:默认关;开了还要配 `url`/`apiKey`,缺一个仍然是关(`provider=plugin` 时不看地址)。 | | `tts.provider` | 字符串 | custom | **服务商**:`custom` / `openai` / `mimo`(Token Plan)/ `mimo-pay`(按量付费)/ `minimax` / `minimaxi`(海外站)/ `ark`(方舟 Agent Plan)/ `doubao`(豆包语音 V1)/ `plugin`。选了就按它定**地址与形状**(这两格由它决定、设置页会藏),**模型仍可换**;要连地址自己填就选 `custom`。 | | `tts.plugin.tool` | 字符串 | 空 | **插件工具名**(`provider=plugin` 时):多个用逗号分隔,如 `voice_tts`;留空=按已知名单 + 名字里带 tts/speech 自动探测。 | | `tts.url` | 字符串 | 空 | **完整接口地址**:不自动拼路径。**仅 `provider=custom` 时生效**。 | | `tts.shape` | 字符串 | speech | **请求形状**:`speech` / `chat` / `minimax` / `doubao` / `ark` / `plugin`。**仅 `provider=custom` 时生效**。 | | `tts.apiKey` | 字符串 | 空 | **API Key(凭据)**:留空=不改。只进 `Authorization` 头,绝不进请求体(豆包例外:它要求 body 里也放一份 token)。 | | `tts.appId` | 字符串 | 空 | **AppID**:只有豆包语音要(`app.appid`),缺了算没配全。 | | `tts.cluster` | 字符串 | 空 | **Cluster**:只有豆包语音要,留空按 `volcano_tts`。 | | `tts.groupId` | 字符串 | 空 | **GroupId**:只有老版 MiniMax 要,填了就拼成 `?GroupId=xxx`。 | | `tts.resourceId` | 字符串 | 空 | **Resource-Id**:只有方舟 Agent Plan 用(`X-Api-Resource-Id`),TTS 模型是 `seed-tts-2.0`;留空按预设。 | | `tts.model` | 字符串 | 空 | **模型名**:每家都生效、**手填**(不给下拉,各家模型名变化太快,选项表只会让它过期)。留空用预设默认。例:`speech-02-turbo`、`mimo-v2.5-tts`、`qwen-tts`、`gpt-4o-mini-tts`。方舟 / 豆包不吃模型名(那两家的「型号」是 `resourceId` 与接入点)。 | | `tts.voice` | 字符串 | 空 | **音色**:没有默认值,填了才进请求体;不做枚举校验。小米 MiMo 三种模型规矩不同(见下表):普通模型填内置音色,`voicedesign` 填一段音色描述(作为 `user` 消息发出),`voiceclone` 不用填(改填 `refAudio`,走 `audio.voice` 的裸 base64)。 | 小米 MiMo 的三个 TTS 模型走同一个 `chat/completions`,但规矩各不相同(官方文档:): | 模型 | 音色怎么给 | 发出去的消息 | 备注 | | --- | --- | --- | --- | | `mimo-v2.5-tts` | `tts.voice` 填内置音色(`mimo_default`、冰糖、茉莉、苏打、白桦、Mia、Chloe、Milo、Dean) | 一条 `assistant`(正文);音色在 `audio.voice` | 填一段描述会被当成无效音色,所以描述型内容会改走 `user` 消息 | | `mimo-v2.5-tts-voicedesign` | `tts.voice` 填**一段音色描述** | `user`(描述)+ `assistant`(正文) | **不能带 `audio.voice`**,否则报 `audio.voice is not supported for voice design model`;缺描述会在本地就拒 | | `mimo-v2.5-tts-voiceclone` | 不用填 `tts.voice`,改填 `tts.refAudio`(mp3/wav 文件或 data URL) | `assistant`(正文) | 参考音频的**裸 base64** 放 `audio.voice`;缺参考音频会在本地就拒 | | `tts.format` | 字符串 | mp3 | **音频格式**:`mp3\|opus\|aac\|flac\|wav\|pcm`(QQ 最稳)。只影响落盘扩展名与 `speech` 形状的 `response_format`。 | | `tts.speed` | 数字 | 1 | **语速**:1=原速;只在 ≠1 时才往请求体里带。 | | `tts.instructions` | 字符串 | 空 | **风格/音色提示**:`speech` 里作 `instructions` 字段,`chat` 里作一条 `system` 消息;留空=不发。 | | `tts.refAudio` | 字符串 | 空 | **参考音频**(仅 `speech` 形状):URL / 本地路径 / `base64://…` / `data:…`;留空=不做克隆。 | | `tts.refText` | 字符串 | 空 | **参考音频对应的文本**:多数克隆接口要求同时给。 | | `tts.refAudioField` | 字符串 | ref_audio | **参考音频的字段名**:`ref_audio` / `ref_audio_path` / `prompt_audio`…留空=不发。 | | `tts.refTextField` | 字符串 | ref_text | **参考文本的字段名**:`ref_text` / `prompt_text`…留空=不发。 | | `tts.timeoutMs` | 数字 | 30000 | **超时(ms)**:单次合成的等待上限。 | | `tts.maxChars` | 数字 | 1000 | **单次最多多少字**:超了明确说"太长,分几句",不偷偷截断。 | | `tts.cacheLimit` | 数字 | 200 | **缓存上限(条)**:同一句话同一音色复用本地文件,不重复花钱;0=不缓存。 | ## 记忆(记人、记群、记承诺) 它会记住人、群、承诺与话题;`isolation` 决定这些内容跨会话能不能互相看见。 | 键 | 类型 | 默认 | 作用 | | --- | --- | --- | --- | | `memory.limit` | 数字 | 5000 | **记忆总条数上限**:超过就按重要度与新旧淘汰。 | | `memory.peopleRoster` | 数字 | 20 | **本群认识的人(最多几个)**:上下文里列出本群我认识的人(按最近露面排序);0 = 不列。细节仍可用 onebot_person 现查。 | | `memory.personCards` | 数字 | 5 | **这次说话的人(最多几张精简卡)**:上下文里把这一批说过话的人逐个列出来,每人一张精简卡(名字+身份、印象、最近几条事实、最多一条未兑现承诺)。只有一个人说话时不受此限——那种情形给完整人物卡。0 = 回到只给当前说话人。 | | `memory.personFactsShown` | 数字 | 3 | **每张精简卡列几条事实**:按最近提到的排,超出在行尾标「还有 N 条没列出」;细节仍可用 `onebot_person` 现查。 | | `memory.reminders.enabled` | 开关 | 开 | **定时提醒**:打开后"答应过的事"到期会冒出来提醒。 | | `memory.reminders.windowHours` | 数字 | 24 | **提醒窗口(小时)**:到期前后多久内算"该提了"。 | | `memory.reminders.limit` | 数字 | 5 | **一次提几条**:单轮最多提醒几条。 | | `memory.reminders.max` | 数字 | 200 | **最多存几条提醒**:超过淘汰最旧的。 | | `memory.isolation.level` | 字符串 | balanced | **隔离级别**:strict 只在本会话 / scoped 按会话可见 / balanced 折中(默认:活跃层能在共享会话之间看见彼此进行中的话题)/ open 最松。**注意**:改松不只放活跃层,长期事实的跨群放行也会一起放松。 | | `memory.isolation.crossGroupIdentity` | 开关 | 开 | **跨群认同一个人**:打开后同一个人在不同群共用一个档案。 | | `memory.isolation.crossGroupFacts` | 字符串 | shareable | **跨群事实**:shareable 标记过的,以及点了名、人都在本群的,可跨群(默认)/ never 永不 / all 全部(连没点名的群内事实也跨)。 | | `memory.isolation.privateFacts` | 字符串 | sameActor | **私聊事实**:never 私聊内容不出私聊 / sameActor(默认)**那个人自己在场的会话**里可见——他私聊讲过的事,他在群里说话时能带进来;/ all 全部。敏感内容任何档位都不外传。 | | `memory.isolation.sensitivityAlwaysLocal` | 开关 | 开 | **敏感内容永远本地**:打开后敏感事实不参与跨会话装配(不看 level)。 | | `memory.isolation.overrides` | 字符串 | [] | **逐项覆盖(JSON)**:JSON 数组:给单条记忆指定可见范围。 | | `memory.isolation.trustedGroups` | 字符串 | [] | **可信群(JSON)**:JSON 数组:这些群之间可以互相看见(仍受 level 约束)。 | | `memory.isolation.trustedPrivates` | 字符串 | [] | **白名单私聊(JSON)**:这些人的私聊能读任何会话;留空则吃超管名单,超管也没配就谁都不能跨会话读。 | | `memory.isolation.recallEscape` | 开关 | 关 | **允许越界检索**:打开后 onebot_recall 能跨会话翻旧账(默认关)。 | | `memory.isolation.recallEscapeNeedsApproval` | 开关 | 开 | **越界要确认**:打开后越界检索要显式 confirm 才给。 | | `memory.isolation.audit` | 开关 | 开 | **留审计**:每次放行/拦截都记一条,可用 onebot_memory_audit 查。 | | `memory.isolation.auditRetain` | 数字 | 200 | **审计保留条数**:账本最多留多少条。 | | `memory.active.enabled` | 开关 | 开 | **活跃层**:记录"进行中的话题"和"agent 正在做的事",做完由 agent 结算;关闭则这一段整段不注入。 | | `memory.active.activeWindowDays` | 数字 | 30 | **活跃层保留天数**:多久没动过的条目就不进上下文;0 = 不过滤(会留下早就结束的僵尸条目)。 | | `memory.active.injectLimit` | 数字 | 8 | **一次注入几条**:最多列几条进行中的事(话题在前、任务在后;组内保持加入顺序,改正文不会让序号换位);0 = 不注入。 | | `memory.active.maxPerOrigin` | 数字 | 20 | **每个会话最多存几条**:防止某个群把活跃层塞满,超了淘汰该会话最旧的(只防跑偏,不代替结算)。 | | `memory.active.dailySettleReminder` | 开关 | 开 | **每天提醒结算**:超过一天没人再提的条目,会在下一次会话活动时被提一句(每天最多一次)。 | ### 会话间转达(`cross.*`) 让一个会话里的 agent 把值得搬的东西(图片、链接、小程序卡、合并聊天记录)递给**另一个会话的 agent**, 由那边自己决定发不发。**默认关**——它会把一个群里的内容带到另一个群,属于要人显式打开的能力。 工具是全局的(`onebot_session`),但未开启时调用直接被拒。 | 键 | 类型 | 默认 | 说明 | | --- | --- | --- | --- | | `cross.enabled` | 开关 | 关 | 总开关。关着时 `onebot_session.relay` 回一句"没有开启"。 | | `cross.allowFrom` | 字符串 | `hub` | 谁能发起:`hub`=只有枢纽自己拉起的会话(默认);`all`=任何会话都能调这个全局工具。认不出调用方身份的一律拒——开了也是一条没有回信地址的线。 | | `cross.allowTo` | JSON 数组 | `[]` | 目标白名单,如 `["group:123456789"]`。留空=枢纽的全部会话都能当目标。 | | `cross.allowPrivateRefs` | 开关 | 关 | 私聊里取到的**原文**能不能原封搬到别的会话(群和私聊一视同仁)。默认不能:私聊里说的话,用户期待它留在那个私聊里。关着时只能用 `text` 转述,转述会过隐私词表。 | | `cross.relayMaxPerWindow` | 数字 | 3 | 时间窗内最多发起几次(按"发起会话 + 目标会话"分别算)。 | | `cross.windowMs` | 数字 | 300000 | 上面那个次数的时间窗(毫秒)。 | | `cross.packageTtlMs` | 数字 | 1800000 | 递过去的包多久内有效(毫秒)。过期后再发会被告知"包不存在或已过期"。 | | `cross.maxBytes` | 数字 | 307200 | 单包内容上限(字节)。超了直接拒绝并说明,不会悄悄截断。 | | `cross.channelTtlMs` | 数字 | 1800000 | 一条会话间通道最长活多久(毫秒)。两头可以在这段时间里来回说几句,过期就断。 | | `cross.channelSilentMs` | 数字 | 600000 | 多久没人说话就把通道冷掉(毫秒)。比存活时间短,所以"沉默"比"过期"更早生效。 | | `cross.channelMaxPerSide` | 数字 | 6 | 通道里每一方最多说几句。防两个会话互相客气到天亮。 | | `cross.wakeGraceMs` | 数字 | 1200 | 递一条消息给别的会话时,最多等对面那一轮多久(毫秒);超时按“已送出”返回并在回执里标 `queued`。两个会话互相递话时,它是防死锁的那道闸 | | `cross.peerListLimit` | 数字 | 10 | `list` 里最多报几个**外部会话**(别的插件 / 别的工作区拉起的)。只报和这个插件来往过、且现在活着的 | | `cross.directory` | 字符串 | `names` | 会话目录:转达开着时把"这个插件接了哪些群和私聊"列进提示词。`off` 不列 / `names` 只给群号和人数(群里私聊只报几个,私聊里才列编号)/ `full` 再加一句群档案里的印象(只给本来就能看到那边的人:群会话与白名单私聊)。 | | `cross.rosterLimit` | 数字 | 30 | 目录最多列几行(0=不列)。按群号顺序排(固定顺序,避免每回合前缀都变),超出的写"还有 N 个没列"。 | 几条刻意的边界:**内容由枢纽搬、模型只写字条**(小程序卡和合并转发这类整段透传的东西, 模型只能引用枢纽打包的 `pkg_xxx`,不能自己构造,否则等于给了它伪造卡片的能力); **发起方身份只认宿主给的 `exec.agent.id`**,不采信调用参数里自报的 from; **递过去之后发不发由那边的 agent 决定**,枢纽不替它开口。 ### 活跃层怎么共享 活跃层**不套用**下面那张记忆放行表,单独一套(群档案不进共享): | 隔离级别 | 群来源的条目 | 私聊来源的条目 | | --- | --- | --- | | strict 严格 | 只在来源会话 | 只在那个私聊 | | scoped 按会话 | 只在来源群 | 按 `memory.isolation.privateFacts` | | balanced 折中(默认) | 白名单内 + 至少 1 个共同活跃群友 | 按 `memory.isolation.privateFacts` | | open 开放 | 白名单内全部 | 按 `memory.isolation.privateFacts` | - **白名单**=`agent.groups` ∪ `agent.privates`:来源与目标都得在名单里,任何档位先被它卡住(两张名单都没配=不限)。 - **共同活跃群友**:候选=人物档案里两边都见过的人 ∪ 两边新鲜成员表交集;再滤掉"只在名单里、从没说过话"的僵尸。取不到证据就不共享(fail-closed)。 - **敏感条目**任何档位都只在本会话;**群档案**(culture/观测字段)永远只在自己那个群。 写与读的三条边界: - **写哪儿**:活跃条目只写在**当前这一轮所在的会话**名下——模型不能替别的群开话题(长期记忆、人物档案不受此限,它们是"记住某个人"而不是"这个群正在聊什么")。 - **序号**:上下文里【进行中的话题】【我正在做的事】两段序号连着编(0 起),模型照号写 `update`/`settle`;同一类里新增只能往后排,改正文不换位。**每次写完回执里的 `active.list` 是最新序号**——结算掉一条,后面的号会前移,模型接着写之前先看一眼它。 - **过期**:超过 `memory.active.activeWindowDays` 没人再提的条目不再注入(会记进审计,理由 `window:expired`),但不会自动删。 ### 谁能看见什么(放行表) 跨会话装配记忆时,`isolation` 实际怎么判定。**同会话、同世界一律可见**,不看下面任何一档(敏感条目与"点的人已不在群"也一样)——它们连闸门都走不到,早退发生在那之前。 | 条目类型(跨群时) | strict | scoped | balanced | open | | --- | --- | --- | --- | --- | | 身份条目(`X 是 QQ Y`;现在只剩存量与导入数据) | 拦 | 放 | 放 | 放 | | 私聊事实(`visibility: private:*`) | 拦 | 拦 | 拦 | 拦 | | 可共享事实(`visibility: shareable`) | 拦 | 拦 | 放 | 放 | | 群内事实 · 点了名且人都在本群 | 拦 | 拦 | 放 | 放 | | 群内事实 · 没点名 | 拦 | 拦 | 拦 | 放 | | 敏感条目(任何 `visibility`) | 拦 | 拦 | 拦 | 拦 | | 点了名但有人不在本群 / 成员表不全 | 拦 | 拦 | 拦 | 拦 | 三点容易误解的地方: 1. **档位只切 `level`,不改四个子开关。** 上表是四个子开关取默认值(`crossGroupIdentity` 开、`crossGroupFacts` shareable、`privateFacts` sameActor、`sensitivityAlwaysLocal` 开)的结果。所以 `open` **也不放**私聊事实与敏感条目——想放得单独改那两个开关。 2. **`level` 不是"档位名越大越宽松"的单一旋钮**:`open` 与 `balanced` 的差别只有"没点名的群内事实"和"点了个不在群的人"这两类(后者在 open 下由闸门先拦,档位管不到)。 3. **点名闸门排在 `level:open` 之前**:只要「讲的是谁」里的人此刻不在本群,`open` 也放不出去。 ### `crossGroupFacts` 到底管哪几格 它只作用于两类条目(`shareable` 与 `group:x`),而且**要么完全无效、要么就是唯一决定因素**: | `level` · `crossGroupFacts` | 可共享事实 | 群内事实·点名·人在本群 | 群内事实·没点名 | 身份条目 | | --- | --- | --- | --- | --- | | `scoped` · 任意值 | 拦 | 拦 | 拦 | 放 | | `balanced` · `never` | 拦 | 拦 | 拦 | 放 | | `balanced` · `shareable`(默认) | 放 | 放 | 拦 | 放 | | `balanced` · `all` | 放 | 放 | 放 | 放 | | `open` · `never` | 拦 | 放 | 放 | 放 | | `open` · `shareable` / `all` | 放 | 放 | 放 | 放 | - **`scoped` 下它完全无效**(三种取值结果一模一样,那两类条目本来就不放);**只有 `balanced` 是它真正决定结果的档位**。 - **它不动身份条目与私聊事实**——那两类分别由 `crossGroupIdentity`、`privateFacts` 管。 - `all` 与 `shareable` 的**唯一差别**就是"没点名的群内事实"那一格:`all` 放开全部群内事实(实测一个群几百条),`shareable` 只放点了名、且人确实在本群的。 - 已知不自洽:`open · never` 那一行,可共享事实被 `never` 拦住、群内事实却照样放行——两条分支的返回顺序不同(可共享事实先查 `never` 再看档位,群内事实先看 `open` 再查 `never`)。 ## 排查用的落盘物 - `/startup.log`:启动逐阶段标记与失败堆栈,插件起不来先看它。 - `` 默认 `~/.dsh/onebot-hub`:时间线 jsonl、原始报文、媒体 blob、记忆与人物档案都在这里。 - 跑起来之后用 `onebot_hub_status` / `onebot_timeline` / `onebot_turns` / `onebot_raw` 查,不靠猜。 相关文档:[README](../README.md)(行为与工具概览)、[design-notes.md](design-notes.md)(每个决定的来龙去脉)。