# DSH 录音导入统一与历史批次补救

日期：2026 年 10 月 21 日。供插件和 Audio 后端同事联调使用。

## 结论

DSH 录音导入缺少通知和自动日总结、时间轴的原因，是上传创建会话时没有携带 `import_batch`，走了普通 `/api/v1/audio/new-session`，没有进入已有的批次处理流程。

插件已补齐新导入的批次协议。本次没有修改、部署后端，没有重新上传历史录音。旧录音补救需要后端提供受权限校验、可幂等执行的已有会话关联能力。

## 已有协议及插件改动

| 入口 | 处理方式 |
| --- | --- |
| 录音页面上传 | 保留现有批次逻辑及通知界面 |
| DSH 目录导入 `arkme_recording_import_folder` | 已确认的待上传文件共用批次；已存在的上传和旧任务不占新批次名额 |
| DSH 附件导入 `arkme_recording_import` | 新增 `files` 数组，一次请求的多个附件一次提交；单文件兼容原参数 |
| 重试及恢复 | 本机账号目录持久保存批次成员及 `clientTaskId`；重试、乱序或仅重试子集时沿用原编号、成员序号、总数、时区 |

批次能力通过 `/api/v1/audio/import-batches/capabilities` 核验，协议版本为 2。新会话沿用 `/api/v1/audio/import-batches/new-session`，由后端原子写入录音会话和批次成员。

显式不支持时允许普通上传并返回未接通状态。网络、鉴权或格式异常停止本次提交，不静默降级。已经保存的批次如果暂时不被服务支持，也不改成普通上传。

`phase=accepted` 仅表示上传完成。转写完成通知、自动总结和时间轴及其结果通知仍由后端批次流程产生，客户端不重复启动 AI 生成。日期采用录音发生时间及批次冻结时区，不用上传日期。

DSH 的批次清单保存支持再次执行同一目录或相同附件请求恢复；已经交给上传协调器的任务沿用其后台恢复机制。尚未交给协调器的目录文件需要保留原文件，并再次执行原目录导入，不代表整个目录已被复制到插件本地。

## 历史数据的边界

本机只读检查发现，账号 11 在 2026 年 10 月 21 日留存的 15 个上传任务均为 `accepted`，没有批次信息。这证明这些本地任务没有进入批次工作流；不能仅凭缺少批次字段将所有旧任务的来源认定为 DSH。

这些录音已经存在，不应再次上传来补通知。当前 Audio 路由只有新建批次会话、能力查询、通知查询和已读接口，没有为已有会话追加批次的公开接口。单纯查通知或刷新页面不能补回缺失的批次关联。

旧任务如果仍在上传，插件保留原任务恢复，不改变它的批次归属。工具返回 `untracked` 或目录结果的 `untracked_uploads`，明确这类任务不会因本次更新自动拥有通知。`matched_uploaded` 仅表示元数据和上传收尾匹配，不代表已进行内容哈希核验。

## 需要后端配合的能力

建议提供“已有录音组建补救批次”的预检与提交接口，名称由后端确定，以下不是已上线的协议：

1. 预检输入：由用户明确选定的一组录音会话引用及目标时区。服务端校验当前账号权限、会话是否存在、是否上传收尾、是否已有批次、处理进度、涉及日期及已有总结版本。返回逐项结果和确认摘要。
2. 提交输入：预检确认凭证和固定幂等键。使用同一事务保存批次清单、成员及已有会话关联；重复提交返回原批次，不能重复发通知或生成总结。
3. 已完成转写的会话直接按当前事实进入汇总阶段；尚未完成的等待原任务，失败的保留真实失败状态。不得用“已接收上传”代替“已完成处理”。
4. 自动生成复用现有日级输入、模型、提示词和版本去重规则；对已有结果不无条件重算。返回会生成、复用、等待、失败的日期及原因。
5. 通知使用原批次工作流的两阶段结果，补救批次注明历史补救。后续重试更新原记录，不重复发送同一结果。

另一个边界是：清单冻结后，某个文件被另一个入口同时上传，或永久移除、取消。当前插件会保留原批次和不完整结果，不谎报全部成功；后端若希望批次及时结束，需要支持成员终态或经过核验的已有会话关联，不能由客户端任意减少 `item_count`。

## 联调验收

- 新目录中 3 个文件跨 2 天：一个批次、三个固定成员；处理完成通知一次，生成或复用两个日期的日总结和时间轴，结果可从通知跳转。
- 两个 DSH 附件：一次 `files` 调用，一个批次；不能每个附件分别触发整天生成。
- 一新一旧：旧录音不重复上传；新批次总数为 1；旧无批次录音不冒充已加入。
- 第二个文件失败后重启、重试：原批次 ID 和总数不变，不重复创建已上传成员；失败未解决时不能报整批完成。
- 能力查询超时或登录失效：上传尚未开始，不走普通上传降级。
- 历史补救重复提交及多设备并发：同一会话关联、通知和日级生成保持幂等；越权、删除或参数变更需明确拒绝。

## 代码位置与验证范围

- `src/recording-tool-import.ts`：DSH 附件分组、预检、去重和上传。
- `src/recording-directory-import.ts`：目录清单与批次绑定。
- `src/recording-tool-batch.ts`、`src/services/recording-tool-workflow.ts`：批次身份、能力边界与账号核验。
- `src/state-store.ts`、`src/local-database.ts`：稳定本机批次清单。
- `src/services/recording-import-gateway.ts`：复用已有批次会话接口。

本次以临时文件、隔离存储、真实 DSH 工具运行时和模拟网络进行回归测试，17 个测试文件共 478 项通过，并通过 TypeScript 与插件构建。3102 已装入本地新构建；2026 年 10 月 21 日 16:20 只读核验线上能力返回 `supported: true`，通知查询成功。没有用生产录音执行新上传；生产“两阶段通知与生成结果”仍需用下一批用户本来就要导入的录音验收。正式客户端尚未发布本次更新。