dsh-butler-console

配置

配置由管理器按实例 plugin.json 生成；字段全部有默认值，未配置时按默认运行。

字段	默认	说明
accessMode	authenticated	standalone 仅用于本机调试
publicOrigin	空	认证模式必填，HTTP(S) origin，不带路径
routePrefix	/butler	页面与接口前缀。改它不用改前端源码：页面骨架 web-react/index.html 里的 /butler 字面量是替换标记，服务 index.html 时按配置整体 replaceAll 成实际前缀（src/web.ts）；JS 产物内部一律走注入的 __BUTLER_CONFIG__.routePrefix，不写死
subtaskTimeoutMs	300000	单个子任务超时，超时中止并释放成员
waitingTimeoutMs	600000	等用户回话的最长时间；到点按超时收尾，材料保留
turnTimeoutMs	600000	单轮上限
maxMessageChars	8000	单条消息字符数上限
maxResultChars	8000	单个子任务结果写回页面的字符数上限
maxSubtasks	6	一次计划允许的子任务数
maxAvatarBytes	262144	成员头像大小上限
maxAttachmentBytes	16777216	单个附件大小上限（16 MiB）。URL 抓取也按它卡
maxAttachmentsPerMessage	5	一条消息最多带几个附件；也是"待发附件"最多攒几个——攒了发不出去没有意义
attachmentParseChars	120000	一次解析最多收多少字符（落库的那一份）
attachmentBriefChars	20000	附件正文进提示词与派单简报的字符上限（按文件数平分，是硬预算）
visionModel	空	读图用哪条模型路由，写成 provider/model；留空表示在官方模型目录里自动挑第一个支持图片的
attachmentFetchTimeoutMs	15000	抓取 URL 的超时
maxRequestBodyBytes	65536	请求体上限
maxActiveConversations	32	同时保留的会话数
maxHistoryPageSize	30	历史每页条数上限
maxConversationEvents	2000	每个会话最多保留的事件条数，供断线续传与第二个入口回放
idempotencyTtlMs	600000	写请求的幂等记录保留多久；记录与任务同库落盘（butler_requests 表），重启后仍能识别同一次提交

业务存储配置与迁移

PostgreSQL 配置（三路来源，按优先级）

1. 环境变量 BUTLER_PG_DSN：直接给连接串（开发/测试最方便）。
2. 私有配置文件 + 环境变量 BUTLER_PG_CONFIG 指向它：文件内容形如 {"dsn":"postgresql://用户:密码@主机:5432/库名"}，模板见 config/storage.example.json （复制后填写，不要提交 Git）。
3. 都没设时的缺省路径：/plugins/butler/storage.json（存在才读，格式同上）。

凭据只走环境变量与私有文件，绝不写进 cordis 配置或 plugin.json（管理器 patch 会整体 替换配置，凭据不能跟着进 Git）。三路都没配置时插件装载失败、不激活。

初始化 SQL 的执行方式

对空库执行一次 private-deploy/db/0001_init.sql（psql -f 或部署脚本完成），版本行随建表一起 写入。之后插件启动只做校验；将来结构变化会以新的编号 SQL 提供，版本不符时拒绝读写。不要用 插件自带的 migrations/postgres/0001_init.sql 建新库——那是旧形状，管家启动时会因版本不符而失败。

存量迁移（SQLite → PostgreSQL）

旧 butler.sqlite（默认路径 /plugins/butler/butler.sqlite）用一次性工具 dist/migrate-storage.mjs 迁移（pg 驱动已打进产物，归档内可直接 node 运行）：

node dist/migrate-storage.mjs --source  --dsn  [--dry-run]

### PostgreSQL 配置（三路来源，按优先级）

1. 环境变量 `BUTLER_PG_DSN`：直接给连接串（开发/测试最方便）。
2. 私有配置文件 + 环境变量 `BUTLER_PG_CONFIG` 指向它：文件内容形如
   `{"dsn":"postgresql://用户:密码@主机:5432/库名"}`，模板见 `config/storage.example.json`
   （复制后填写，不要提交 Git）。
3. 都没设时的缺省路径：`/plugins/butler/storage.json`（存在才读，格式同上）。

凭据只走环境变量与私有文件，**绝不写进 cordis 配置或 `plugin.json`**（管理器 patch 会整体
替换配置，凭据不能跟着进 Git）。三路都没配置时插件装载失败、不激活。