# 安装升级、配置迁移与回滚

本插件默认禁用，默认监听 `127.0.0.1:8898`，使用自己的设置、缓冲和暂存目录。人格、记忆和自主定时任务由 DSH 及相关插件管理，不属于本插件的升级范围。

## 升级步骤

1. 在设置页停止桥接，等待正在进行的操作收尾。备份插件的 `settings.json`、`state.json`、DSH profile 配置和凭据引用；实际凭据备份放在受保护位置，不要复制进源码仓库。
2. 安装目标版本的 Release tgz，或更新源码后执行 `npm ci --legacy-peer-deps` 与 `npm run build`。源码仓库不包含 `dist/`，发布 tgz 包含已构建文件。
3. 重载插件包，刷新设置页。开启 HMR 的宿主也可能自动加载代码更新；“保存并重载后端”只重建当前已加载代码的后端实例。
4. 检查 Bot UID、已有 Session ID、白名单、凭据引用和 Webhook 监听配置。保留原 Session ID 可继续使用同一会话的历史、人格与记忆，不需要新建替代会话。
5. 启动桥接并配置已验证的入口形式 `https://bridge.example.com/vocehook?secret=YOUR_WEBHOOK_TOKEN`，令牌需与插件中配置的凭据值一致。GET 返回 200 验证地址，POST 单独校验令牌；VoceChat 的可选 `set secret` 加密接口保持未设置。
6. 在授权的测试私聊或群聊发送文字和媒体，核对 DSH 入站、原目标回复、语音及白名单。使用独立测试实例时，为其指定不同的状态与暂存目录。

更换 Webhook 接收端时，保留配置备份，并确保同一 Bot 的相同事件只有一个有效处理入口；不同实例的本地去重不能阻止跨实例重复回复。

## 版本兼容

- **v0.2.0** 引入状态格式 v2、持久化防抖和批次边界。升级前先停止实例并备份状态。使用新的静默窗口参数时，将兼容项 `mergeWindowMs` 删除或设为 0。
- **v0.3.x** 沿用状态格式 v2，加入语音设置页、OpenAI/MiMo ASR 和 TTS，以及后端启停、重载和启动恢复。
- **v0.4.0** 增加同会话历史背景、最近 N 条历史工具和入站诊断。
- **v0.4.1** 修复内部记忆/时间上下文被误判为混合来源；历史查询独立校验身份和白名单，混合回合显式发送按主动发送策略处理。
- **v0.4.2** 整理公开文档和许可，源码不再跟踪 `dist/`；运行实现与状态格式保持兼容。
- **v0.4.3** 更正 Webhook 地址和令牌说明，沿用已验证的带 query 令牌接入方式；运行实现和默认值不变。
- **v0.4.8** 修复上下文压缩回合不自动回发：识别宿主的摘要检查点、指令和技能目录刷新，保留本轮回复归属。无需修改配置或状态格式；真实混合来源的回合仍关闭自动回发。
- **v0.4.9** 提供本机插件主动对话服务，可按调用方配置的固定 UID/GID 生成并发送消息，等待发送层确认。需要 `allowProactive:true`、白名单内目标，以及与桥接相同的 Session；既有配置和状态格式不变。

状态和防抖的升级、恢复规则见 [DEBOUNCE.md](DEBOUNCE.md)。已完成与结果不确定的批次不会在升级后自动补发。降级到不认识 v2 的版本前，应停止实例并恢复该版本对应的备份，不要把当前状态强行交给旧格式读取器。

## 配置注意事项

### 设置与凭据

插件页面保存到 `settings.json` 的字段优先于 profile 同名值。凭据字段填写的是 DSH credentials 或环境变量的**引用名**，实际 Key 不保存在插件设置文件中。

Webhook URL 的 `?secret=...` 用于插件的访问令牌认证，消息内容仍可为明文 JSON。VoceChat 可选的 `set/get secret` API 才控制 AES 内容加密；当前接入方式不启用该接口。Bot API Key 用于调用 Bot API，独立于这两个设置。

### 本地媒体读取（v0.4.5）

v0.4.5 起本地媒体发送直接使用 DSH 的文件读取服务，不再要求给工作区重复配置目录白名单。`allowedLocalRoots: []` 表示跟随宿主读取权限；已有非空列表继续作为额外限制，若不需要这层限制可在设置页清空。相对路径按工具执行会话的工作区解析，并支持 `~/`。不修改 DSH 的权限模式、工作区或凭据。

### 回复目标

v0.4.7 自动补齐 `senderName`，当前消息、历史、引用均保留 `senderId`，无需新增配置或升级状态文件版本。名称仅作显示，改名不会改变分批、去重和回复目标。资料查询失败时显示 `UID n`，不阻断消息。

v0.4.6 起，入站 Reply 自动补齐被引用原文与附件，并向 DSH 标明新消息对应的 `replyTo`，无需新增设置。状态文件仍为 v2，新增可选引用 ID，兼容原有状态；引用本身不产生新任务。找不到原文时仍提交当前新消息，并标明不可用原因。

自动回复绑定触发批次的 `destination`。主动工具发送必须明确 UID/GID，通过目标白名单并满足 `allowProactive` 配置。不要依赖“最近联系的人”来推定目标。

历史背景只是上下文，不应作为新消息重新提交。Bot 互通相关的上游行为和 SSE 方向见 [BOT-MESSAGES.md](BOT-MESSAGES.md)。

v0.4.8 的修复需要重载插件代码；仅“保存并重载后端”不保证更新已导入的模块。旧版已经处理完成但被误判而静默的消息不会自动重放，以免重复执行任务。

### 音频与语音

文件扩展名和 MIME 不能代替真实转码。压缩音频使用 FFprobe 探测；识别服务要求特定容器、采样率或声道时由 FFmpeg 归一化。MiMo 输入按当前适配器转为 16 kHz、单声道 PCM WAV，转写和原始文件独立保留。

ASR/TTS 的端点、模型、音色和风格配置见 [PROVIDERS.md](PROVIDERS.md)。识别失败会记录不可用原因，不伪造内容，也不丢弃原始文件。

## 回滚

1. 停止当前桥接并保留日志与状态备份，确认监听已释放。
2. 安装先前版本；源码方式需要使用对应版本重新构建，再重载插件包。
3. 按需要恢复与该版本匹配的设置和状态，核对 Bot UID、Session、白名单、凭据引用及 Webhook 地址。
4. 使用授权测试消息检查入站和回复目标，再恢复日常使用。

回滚插件不会撤销已经写入 DSH 的聊天记录、已经保存的宿主附件或已经发出的 VoceChat 消息。