@senguoyun/dsh-arkme 0.1.85 → 0.1.87

package/docs/recognized-speaker-directory-backend-handoff-2026-09-28.md

@@ -1,3 +1,5 @@
+> 2026-09-30：已按 2026-09-29 后端交付合同完成插件接入。本文保留为需求交接历史，当前前端实现与验证范围见 [统一目录对接](speaker-directory-integration-2026-09-30.md)。
+
 # 已识别说话人：统一目录、总数、新增提醒与跨端同步——后端交接
 
 日期：2026-09-28

package/docs/recognized-speaker-entry-and-visits.md

@@ -1,3 +1,5 @@
+> 2026-09-30：录音目录已迁移到后端 `speaker-directory/summary`、`list`、`seen`。下文的本机新增记录、全名单扫描及 2,000 人上限是旧版实现记录；当前实现与验证范围见 [统一目录对接](speaker-directory-integration-2026-09-30.md)。
+
 # 已识别说话人：入口统计、本机新增提醒与本人引导
 
 ## 本轮交互

package/docs/recognized-speaker-sorting.md

@@ -1,3 +1,5 @@
+> 2026-09-30：录音目录的搜索、排序及本人置顶已改为保持后端统一目录顺序，分页每次 50 人。下文前端全量扫描是旧版实现记录；当前实现与验证范围见 [统一目录对接](speaker-directory-integration-2026-09-30.md)。
+
 # 已识别说话人排序
 
 ## 交互

package/docs/self-role-avatar-cache.md

@@ -0,0 +1,59 @@
+# 角色头像本地优先
+
+角色与历史消息保存稳定 `file_asset://` 引用。MediaService 现在先读进程内缓存与既有 SQLite 头像缓存，再按上传回执查找本机原图；只有本地不存在或文件不可用时才解析资产并下载。缓存身份包含环境、账号和资产 ID，签名 URL 过期不会淘汰文件；既有容量淘汰规则仍适用。
+
+同资产的磁盘查找、解析及下载共用一个在途请求。不同缺失资产在 8 毫秒窗口内合并，按最多 50 个 UID 调用既有文件查询接口。上传回执继续负责原图与资产 ID 的对应关系，角色删除后仍可供冻结消息读取。缓存写失败不阻断展示；查询失败清除在途状态以便重试；切换账号或销毁服务后不返回旧账号结果。
+
+| 消费面 | 路径与范围 |
+|---|---|
+| UI | 消息和角色选择器继续通过 `image.read` 读取，继承持久缓存；没有新增设置或加载操作 |
+| SDK | 现有 `readImage` 使用同一 Host owner，签名、返回数据和能力版本不变 |
+| Tools | 现有 `arkme_image_read` 使用同一 `MediaService.readImage`，不新增工具或授权 |
+| Host | 缓存属于既有图片读取能力；复用头像表、角色上传回执与文件查询接口，无新业务 endpoint 或表 |
+
+回归覆盖 SQLite 关闭/重开后的离线读取、上传原图复用、删除角色后的历史头像、同资产合并、不同资产分批、查询失败重试、环境/账号隔离、账号切换和损坏缓存恢复。头像资产沿用 8 MiB 头像上限，调用者指定的更小上限仍生效。
+
+## 本次验证记录
+
+- Node 24：完整测试 9,646 项通过、15 项跳过；typecheck、build、打包清单检查通过。
+- 不可变 tgz 通过官方 CLI 安装到全新临时 Profile；目标官方 DSH 为 0.1.5-rc.2 / fb2c4b9e，源码保持干净。
+- 已安装包在真实 Host 中通过外部 SDK `readImage`、真实会话 `arkme_image_read` 读取预置持久 PNG；资产查询接口刻意不可用，查询次数为 0。
+- 通过浏览器在实际插件的“发给自己 → 发言角色”打开选择器；头像元素成功解码为图片，刷新页面后同样成功，查询次数仍为 0。该验收使用隔离账号和固定图片，无生产数据写入。
+- 测试在 macOS 完成，未替换常驻插件，也未声称完成 Windows/Linux 实机验收。
+
+## 分支审核补充
+
+- 已复现：磁盘读取挂起期间 dispose，旧任务恢复后仍发起资产查询；结果虽最终被拒绝，但查询发生得太早。
+- 修复：读取开始时捕获生命周期代数，异步账号检查完成后再次比对；查资产、逐批查询、取得下载配额后都验证当前代数。dispose 不影响之后的新读取，旧任务不能继续启动网络请求。
+- 新增磁盘读取期间重置、第一批查询期间重置后不再查询第二批的回归。扩大验证：9,649 项通过、15 项跳过；typecheck 和 build 通过。
+- 同一资产仍共用在途读取，单个调用者取消不会中断其他读者；账号/环境隔离、离线缓存读取与上传原图复用保持通过。
+
+本轮审核安装包复验：新 tgz 在隔离 Profile 的官方 Host、SDK 和会话 Tool 中读取持久 PNG 成功，资产查询 0 次；未修改 DSH 源码，未重跑浏览器视觉验收。
+
+
+## 最终审核修复：本地探测与损坏图片
+
+- 浏览器持久缓存未命中时，先使用独立配额调用 `image.read { imageRef, cacheOnly: true }`。只探测当前账号的 Host 内存、SQLite 和上传原图，不加入正在下载的请求，也不发起资产查询；未命中才进入原有下载队列。不同头像的两个慢下载不再挡住 Host 已缓存的第三张头像。
+- Host 对持久缓存、上传原图和新下载内容执行实际图片解码，拒绝只有文件头的截断图片。继续使用现有 8 MiB 字节上限，解码首帧额外限制为 64 MP；损坏缓存按未命中处理，下载成功后覆盖，损坏下载不持久化。
+- 浏览器 CacheStorage 的读写也执行解码校验；旧的合法 base64、非法图片内容会被删除并回源。不可变文件仍无时间过期，容量淘汰、清理站点数据和损坏内容均视为缓存未命中。
+- 保持现有账号、环境、生命周期隔离和同图在途去重。无需数据库迁移、后端部署、新增配置或依赖升级。
+
+| 消费面 | 新增合同 |
+|---|---|
+| UI | 浏览器缓存 → 独立 Host 本地探测 → 原有下载；默认头像、角色选择与刷新继续使用原有界面 |
+| SDK | `features.imageCacheRead` 能力探测；公开 `readCachedImage`，本地未命中返回 `undefined`，不支持的 Host 明确报错 |
+| Tools | 既有 `arkme_image_read` 增加可选 `cache_only`，沿用原 grant；未命中返回 `image-cache-miss`，不偷偷下载 |
+| Host | `MediaService.readImage({ cacheOnly: true })` 是共同 owner，探测仅支持稳定 `file_asset://`，普通读取的默认行为不变 |
+
+
+本轮验证：完整测试 9,672 项通过、15 项跳过；随后补充解码清理与 Tool 错误标识测试，相关 44 项通过，typecheck/build 通过。最终 tgz 通过官方 CLI 安装至全新 Profile，仓外 SDK consumer 编译和调用通过。未修改的 DSH 0.1.5-rc.2 / fb2c4b9e 中，SDK 和真实会话 Tool 均验证本地命中及未命中，损坏 SQLite 记录被拒绝，上游资产查询为 0。实际 UI 首次只发出一次本地探测，刷新后图片仍成功解码，Host 读取计数保持为 1；切换默认角色无旧图残留。macOS 已验收，Windows/Linux 原生解码路径仍需对应平台验收。
+
+
+## 最后一轮分支审查：存储限制降级
+
+确认并修复一处 P2 问题：受限浏览器上下文访问 `caches` getter 本身可同步抛出 `SecurityError`。原实现仅捕获异步存储错误，写缓存时的同步异常会拒绝已经取得 Host 图片的加载任务。现在缓存可用性探测也受异常保护，持久存储不可用时继续显示 Host 返回的图片。
+
+证据：修复前回归失败、修复后相关 55 项通过；真实浏览器的 sandbox iframe 中，旧代码 getter 被拒绝且加载失败，新代码在相同限制下正常解码显示图片。新 tgz 经官方 CLI 安装到隔离 DSH Profile，Host/SDK/真实会话 Tool 验收通过，资产查询为 0；实际 UI 刷新前后 Host 读取总数保持为 1。最新 `dev`（b630034b）与本分支合并模拟无冲突，录音与主题样式改动没有覆盖头像生命周期或能力声明。
+
+
+本轮 typecheck/build 通过。两轮全量分别为 9,675 项通过、1 项失败、15 项跳过，失败均在本分支未修改的 `recording-presence-writer.test.ts`：一轮在固定等待 5 ms 后读取尚未创建的 timer，另一轮在初次请求落盘尚未结束时注入下一次落盘失败，导致请求计数断言波动。该文件单独复测 15 项通过；不能将本轮全量写成全部通过。未为本次头像任务修改录音业务或其测试。

package/docs/speaker-directory-integration-2026-09-30.md

@@ -0,0 +1,53 @@
+# 录音说话人统一目录对接
+
+基线：2026-09-30 刷新的 `origin/dev`，提交 `bc33e583`（0.1.86）。
+后端合同：用户提供的 2026-09-29 `frontend-integration.md`，jotmo-audio 提交 `45478168880082f4cc8243d2086e0fccbdaff080`。
+
+## 当前行为
+
+- 录音入口只读统一 summary，人数与新增数完全由后端提供。首次 building/null 显示整理中；有完整空快照才显示零。
+- 目录以 `all/marked/unmarked + frequent/recent + query` 查询全局列表，每页 50 人，保持服务端顺序和本人置顶。查询按 300ms 防抖，不再扫描所有旧名单，不再用前端 2,000 人上限限制目录。
+- 改变查询重新取首屏；翻页固定原 snapshot_version 和查询。重复人物去重，版本变化、循环游标拒绝追加，snapshot_expired 重取摘要及首屏。缓存按账号、查询和快照隔离，最多缓存 12 个查询。
+- 仅“全部、无搜索”目录首屏实际渲染且页面可见时提交 list.through_cursor。完整空目录也可确认。预取、入口展示、搜索、筛选、未知快照、隐藏页面不确认。
+- seen 成功后重新读取 summary，不自行清零新增数。离线待确认凭据仅保留于当前运行的原账号；失效凭据停止重试，重新展示首屏后才确认新凭据。跨端以 summary 同步。
+- 可见期间约 30 秒检查摘要，building/stale/failed 遵从 retry_after_ms。后台停止；在线、重新可见和窗口激活时检查。并发请求合并；HTTP 429 同时尊重 Retry-After 和 retry_after_ms 的较长值，手动刷新不绕过等待。
+- failed/stale 保留可用内容，disabled 保留入口、停止目录轮询和确认。未知状态不伪装为空；待处理诊断字段不加入人数。
+- 列表 detail_ref 由 Host 封装为账号及环境绑定的引用。选中人物时再接入现有详情；未标记先通过既有 detail 获取候选信息，再复用 mark-options、候选版本、标记和签名音频链路。已标记保留 presence expected_version，不使用目录版本替代。失效候选和 stale presence 刷新目录引用后恢复。
+- 已标记人物按当前页的稳定 speaker ID，通过既有说话人绑定及公开资料补齐头像；头像异步加载，不阻塞目录、排序或分页。无图片时使用名称首字头像及按 personKey 固定的浅色背景，空名称才使用默认人形。首字按完整字素取值，忽略前后空格，不截断 emoji。未标记人物保留编号头像，编号为零时不制造“说话人 0”。后端当前空 avatar_ref 不拼接为 URL。
+- 本人引导只依据无搜索主目录的可用首屏；搜索页缺少本人不触发引导。声纹状态读取失败显示不可用。
+
+新增 Host 操作：`speaker-directory.summary/list/seen/open/avatars`。沿用 ServiceRuntime 的当前环境地址、登录恢复和业务成功码 200 校验，不硬编码测试服务地址。seen 需要同源页面 Origin。
+
+## 初次验证与边界（后续进展见下文）
+
+- 15 个相关测试文件、209 项测试通过，覆盖目录状态机、页面、Host 分发、真实 HTTP 包装、候选详情及原有录音说话人流程；包括 2,050 人分页、跨账号迟到响应、查询竞争、查看期间新增保留、限流退避、首屏呈现前不确认。
+- 类型检查和生产构建链（凭据助手校验、声明生成、tsdown 打包、入口校验）通过。使用既有依赖执行等价脚本，未改动主工作区依赖。
+- 独立 3102 预览使用本分支构建的 tgz、独立 DSH_HOME/Arkme 状态目录及已有账号会话；未替换 3100 预览或已安装桌面客户端。
+- 生产目录首次返回 building/unknown、人数 null、retry_after_ms=3000，之后成功发布完整快照：9,712 人（已标记 68、未标记 9,644），新增数 0。两种排序各读取前两页（每页 50），版本一致、跨页无重复，本人首屏置顶；名称/编号查询与 marked/unmarked 筛选、已标记 presence 详情成功。没有遍历全部 9,712 人来声称全量验收。
+- 两个未标记候选的既有 `/unmarked-speakers/detail` 读取均触发 Host 30 秒请求超时；前端有错误及重试入口，但这条真实详情链路尚未验收。尚无服务端日志，不能断定超时根因。真实非零新增、跨端确认与播放未验证；未直接调用生产 seen，因为本轮没有实际展示目录页面。
+- 浏览器工具打开本地地址失败，本机 UI 控制连续超时。页面交互已通过组件测试，但浏览器视觉、真实音频播放和真实标记写入未验收；没有为测试修改真实说话人或声纹。
+
+本地接口验证记录：`/Users/tison/arkme/.codex-artifacts/recording-directory-0930/live-verification.json`。不含账号凭据、人物姓名或音频正文。
+
+## 继续验收（2026-09-30 21:43）
+
+- 直接对生产接口做同候选串行对照：mark-options 6,581 ms、segments(limit=1) 6,330 ms 成功；detail 使用 90 s 诊断上限，60,073 ms 收到上游 HTTP 504。插件超时配置未改动，延长它不能解决此样本的服务端失败。
+- 合同后端提交的 getSpeakerDirectoryCandidateDetail 会先 buildSpeakerDirectoryCandidateCatalog；后者对账号 Source.Walk / ReadChildren 并聚合、聚类，然后才定位选中候选。此全账号重建路径是最可能的主要耗时原因，尚缺服务端 trace，不能确认为唯一瓶颈。相关源文件与本轮刷新后的 origin/master 无差异。
+- 现有 Host 试听链路的一个旧目录样本成功取得音频 HTTP 206（FLAC，Range 0–63，共 64 字节）。这是媒体授权/读取证据，未覆盖新目录入口、解码或真实播放。
+- CUA 能发现 Edge，打开页面和读取 UI 状态仍各 30 s 超时；未完成视觉验收。未调用生产 seen，未修改真实人物/声纹/录音。
+- 完整验收仍未通过。本轮不修改问题代码，待用户确认根因与修复方向。详细对照、影响范围及后端源文件快照见 `/Users/tison/arkme/.codex-artifacts/recording-directory-0930/acceptance-2026-09-30.md`。
+
+## 头像回归修复与浏览器验收（2026-09-30 22:39）
+
+- 根因：后端列表的 avatar_ref 当前为空，新目录组件又遗漏了旧流程的 avatarRef，导致有真实头像的已标记人物统一显示默认图。实测旧说话人选项中 70 人有 30 人携带头像引用，本人也有；新目录已标记首屏 50 人的 avatar_ref 全为空。
+- 头像补齐仅接受 Host 封装、账号及环境绑定的已标记人物 detailRef，每批至多 50 个。按 speaker ID 匹配绑定用户，不按同名匹配，不扫描联系人、转写或出现统计。沿用公开资料与图片缓存；失败重试不重载目录，账号切换取消并丢弃旧响应。
+- 修复相关 9 个测试文件、175 项测试通过，覆盖同名人物、翻页只补新人物、延迟加载、失败重试、跨账号迟到响应、密封引用校验及已有头像缓存。类型检查、生产构建链和 git diff --check 通过。
+- 独立 3102 预览已安装修复构建，沿用原有生产账号登录。浏览器工具恢复后实际进入录音及说话人目录；主目录正常展示 9,712 人、已标记 68 人、未标记 9,644 人。真实首屏共 50 行，其中 5 张人物头像全部解码成功（naturalWidth > 0），包括本人；未标记编号头像正常。截图：`/Users/tison/arkme/.codex-artifacts/recording-directory-0930/avatar-fix/avatars-restored.png`。
+- 主目录在可见浏览器中实际呈现，允许正常的首屏 seen 流程；此前“未展示页面/未触发 seen”仅描述早期诊断阶段。未为测试修改人物、声纹或录音。
+- 本次完成头像显示验收。未标记详情的服务端超时、真实音频播放、真实非零新增和跨端确认仍未完成验收；本次未修改后端。
+
+## 名称首字头像（2026-09-30 22:43）
+
+- 按确认的样式，将无图片的已命名人物改为 38px 圆形首字头像，复用录音人物色板，与主题底色混合后显示深浅适配的文字。颜色绑定稳定 personKey，真实头像加载后优先显示图片；仅说话人目录启用这一可选占位内容。
+- 4 个现有头像及目录相关测试文件、34 项测试通过，类型检查、生产构建和 git diff --check 通过。
+- 3102 预览已更新并在浏览器确认：首屏 6 位已标记人物中 5 位正常显示真实头像，1 位显示名称首字“安”，未标记编号显示正常。截图及 DOM 验证记录位于 `/Users/tison/arkme/.codex-artifacts/recording-directory-0930/initial-avatars/`。