docs/RELEASE_NOTES_v0.9.4.md

Rama main · réplica de lectura del repositorio original.

# v0.9.4：DOCX 依赖修复与通知持久化

[English](RELEASE_NOTES_v0.9.4.en.md)

版本日期：2026-10-15。相对公开 Core 0.9.3 的补丁更新。

一笔售后任务已经完成，Core 却在结果通知发出前被强制终止。只重启业务任务可能造成第二次退款；只依赖正常关闭排空也无法恢复这段空隙。百灵中枢（BailingHub）0.9.4 在内置仓储中同时保存任务终态和通知意图，重启后继续原通知，保留原业务结果。它同时移除 DOCX 解析未使用且存在已知漏洞的 CLI 依赖链，并在自带控制台提供通知处置入口。

## 修复了什么

### DOCX 保留解析库，移除 CLI 依赖链

Core 文件上下文和控制台知识库导入继续使用 Mammoth 1.12.0 的原始解析代码。带有明确修改标记的 `@bailinghub/mammoth-library@1.12.0-bailinghub.1` 保留上游库源码、类型、浏览器适配与 BSD-2-Clause 许可证，去掉未使用的命令行入口及 `argparse → sprintf-js` 链。

Core、控制台、源码导出和 Docker 使用同一份固定归档；npm 制品捆绑库及其运行依赖。原限时审计例外退役，门禁要求两棵依赖树原始审计均为零，并以 `mammoth@1.12.0` 原名另查直接公告。来源完整性和逐文件清单可公开重验。这是本项目分发依赖的处置，不是上游 `sprintf-js` 已修复或任意 DOCX 都安全的声明。见 [DOCX 依赖与校验](DOCX_DEPENDENCY.md)。

### 任务结果与通知意图一起保存

MySQL 状态库将任务终态与通知意图写入同一事务；审批创建及其提示保存在审批配置库的同一事务，两库可以独立。JSONL 用同一条同步落盘记录保存任务和意图，仍只支持单写者。

覆盖新任务终态产生的 callback、配置的结果送达、审批提示和失败通知子任务的死信留存。启动及维护周期恢复待处理通知，有限批次、租约、重试和旧 worker 确认隔离限制重复处理。不会把历史已完成任务或旧待审批单批量变成新通知，也不会为补消息重跑业务父任务。普通监控告警及未实现持久化端口的旧扩展仍为尽力发送。

Webhook 等待真实 HTTP 响应，以稳定的 `X-Bailing-Event-Id` 和签名正文 `notification_event_id` 标识原事件。确认丢失后可能重复送达，接收方必须去重；有界重试耗尽后保留失败记录，不能把“至少一次”理解为无限重试或必达。原生渠道出现部分、未知送达或过期在途领取时进入 `uncertain`，核对接收端后再人工处理。详情见[通知持久化](NOTIFICATION_DURABILITY.md)。

## 新增控制台与持久指标

自带控制台「任务 → 通知送达」支持类型/状态筛选、摘要和失败重试。查看需要 `runs:read`，重试需要 `runs:write`；未知送达需显式确认重复风险。管理 API 使用观察到的状态做并发校验，只处置通知，不重新执行业务。

可选受保护的 `/metrics` 增加固定 `jobs` / `approvals` 来源的 outbox 可用性、状态数量、最老待处理年龄和过期租约数。它读取持久聚合，不含正文、收件地址、事件或租户标签；缺少能力时不伪造零积压。当前没有自动清理和历史归档策略，部署者需要观察数据增长。

## 升级与边界

- **Core 管理员**：备份原制品、配置、状态/配置数据库和 JSONL，显式应用新增的 `068_notification_outbox.sql`。独立配置库和状态库都要迁移；`npm run db:init` 仅处理配置中的 MySQL 状态库，独立配置库需使用官方迁移 API 另行处理。
- **嵌入式与自定义仓储开发者**：使用配套内置仓储，或实现可选持久化端口的事务/租约语义；继续调用既有 `tick()` 和 `close(drainMs)`。第三方旧仓储兼容路径不获得持久性承诺。
- **通知接收方**：按稳定事件 ID 去重并核对外部结果；通知 `completed` 可能表示已交给持久执行器，不等于收件人已阅读。关联原生事件的死信统一从 outbox 补发，067 执行器原通知重投继续保留。
- **独立项目**：MCP / Agent Client SDK 0.7.0、DSH 0.7.0 不变。ACC、客户端、独立 Host 与具体部署各自发行和升级。

新增 068 建立 outbox 表并给死信增加可空事件关联及唯一索引；067 及以前迁移保持原样，不批量补造旧通知。回退旧代码不能继续处理新 outbox，也不能撤销已外发消息；保留事件、死信、回执和迁移账本，按一致备份及核对流程处理。见[升级指南](UPGRADE_v0.9.4.md)。

公开回归覆盖官方解析兼容、真实 npm 消费、控制台浏览器、JSONL 实际 SIGKILL、MySQL 事务与确认丢失、租约隔离、审批、旧 067 到 068 和原通知重投。使用合成数据及本地接收端；它们不代替真实渠道收件、目标部署验收或生产回滚演练，也不保证磁盘损坏或未经验证的外部副作用可恢复。

[升级指南](UPGRADE_v0.9.4.md) · [完整版本记录](CHANGELOG.md) · [能力与证据索引](IMPLEMENTATION_STATUS.md) · [上一版本](RELEASE_NOTES_v0.9.3.md)