@senguoyun/dsh-arkme 0.1.82 → 0.1.83

package/docs/ai-points-implementation.md

@@ -0,0 +1,43 @@
+# AI 积分接入
+
+基线：用户指定 origin/dev（114ad18），任务 worktree；不修改 DSH、根 README 或版本号。
+
+本次积分 API 只读取账户及已结算消费。会员发放与模型收费分别由 Backend 和 Intelligent 持有；插件不估算余额，不从 Token 遥测推导扣费。
+
+| 能力面 | 实现入口 | 验证状态 |
+| --- | --- | --- |
+| UI | 用量与额度 → AI 积分、扣费明细；充值保留人民币支付价格 | 已完成，相关单测及官方 DSH 正式 tgz 链路通过 |
+| Tools | 当前登录账号 AI 积分及消费查询，只读，不发放、不充值 | 已完成，相关单测及官方 DSH 正式 tgz 链路通过 |
+| SDK | aiPoints 能力探测、类型化账户与分页明细，支持 AbortSignal | 已完成，相关单测及官方 DSH 正式 tgz 链路通过 |
+| Host owner | AiPointsService：统一账号作用域、契约校验和错误语义 | 已完成，相关单测及官方 DSH 正式 tgz 链路通过 |
+
+不扣积分的后台业务不进入此页面。Token 只出现在已扣费请求的展开明细。存储、语音等独立额度沿用原 owner 与计量单位。
+
+验收使用官方 `dsh-v0.1.5-rc.2` / `fb2c4b9e`，源代码未修改；独立 profile 通过官方 CLI 安装 tgz。因官方 peer 范围 `>=0.1.5` 不匹配已发布 rc 包，测试 profile 按目标官方版本固定其同套依赖，未改插件版本/依赖或用户常驻环境。8 场景覆盖正常、异常、恢复；真实 UI、公共 SDK、注册 Tools 读取同一账本。余额不足文案统一为积分；同账号请求并发冲突提示等待，不自动重试扣费。
+
+更完整的测试矩阵与基线限制见 meta 的 `docs/analysis/2026-09-22-ai-points-verification.md`。
+
+## 2026-09-23 三端体验收口
+
+用户侧统一称“Arkme 3.0”，充值页说明与 APP 共用积分。现有充值流程不变；APP/旧 Flutter PC 只提供查询、消费与官网下载指引，不扩展支付渠道。
+
+| 能力面 | 本轮增量与验证 |
+| --- | --- |
+| UI | 模型菜单增加独立折叠计费说明，查看不改变选择；消费按可信 Agent operation_uid 聚合，展开仍显示调用级准确费用；无标识的 Arkme 请求保持独立 |
+| Tools | 原 arkme_ai_points / arkme_ai_points_consumption 保留共享 owner；正式包的注册 Tools 在真实会话作用域读取同一账本，未新增计费或写入工具 |
+| SDK | 公共 aiPointsConsumption 保留 operationUid；完整业务组可超过20个调用，仍最多20组；包外 SDK consumer 已经官方运行时验证，错误账号作用域仍拒绝 |
+| Host owner | AiPointsService 统一契约校验/账号边界；报价来自 Intelligent point_pricing，不按Token遥测、模型昵称或UI倍率重算价格 |
+
+747个测试文件、8828项测试通过（11文件/15项按原配置跳过），类型检查与构建通过。新增分组、报价及“查看不选中”回归。正式 `.tgz` 通过官方 CLI 安装至全新隔离 profile，官方 DSH `dsh-v0.1.5-rc.2` 源码未改，已通过含 UI/Tools/SDK/真实HTTP/真实MySQL 的跨仓链路；真实供应商和支付仍使用隔离边界，未作线上验收。
+
+完整本轮记录位于 meta：`docs/analysis/2026-09-23-ai-points-ux-delivery.md`。没有改插件版本、根 README 或发行配置。
+
+## 2026-09-24 消费月份交互修复
+
+对照 `origin/dev`（8b6be0d）及 `origin/master`（052ac40）的 `ArkmeTokenUsageBreakdown`，基线使用原生 `select`；积分页的 `input type="month"` 会把年月文字点击解释成分段编辑。现恢复基线下拉选择及同一套样式，文字和箭头区域均可展开。默认列出最近 24 个月，“更早月份”每次扩展 12 个月，不改变当前账期、不发查询，也不限制历史记录范围。月份按上海时区确定，切换后继续由原有请求 owner 取消旧请求、隔离旧月份结果。
+
+| 能力面 | 本轮范围与证据 |
+| --- | --- |
+| UI | 月份选择交互；42 项相关测试、类型检查和构建通过。隔离浏览器组件页面验证文字/箭头点击、键盘切换、取消及扩展历史；未替换用户常驻 DSH |
+| Tools / SDK | N/A：仅替换 UI 控件，未新增业务能力或修改公共接口 |
+| Host owner | AiPointsService 及账本查询契约不变 |

package/docs/interwoven-compact-summary-regression-2026-09-28.md

@@ -0,0 +1,35 @@
+# 私聊群互动：正文优先的轻量摘要行
+
+## 已确认的交互
+
+- 保持居中的透明单行提示，不改成普通消息左右头像气泡，不新增预览卡片。
+- 最新确认方案使用 20px 发送人头像代替「我／对方」，不再显示完整昵称；头像与正文垂直居中，不增加行高。
+- 顺序调整为：发送人小头像 → 正文摘要 → 弱化的群名 → 原群消息已读状态 → 详情箭头。
+- 复用现有发送人头像字段及共享图片缓存；缺图、加载中或图片加载失败时显示昵称首字，避免空白灰头像。头像来源变化或图片地址更新后可重新显示新头像。
+- 群名最多占行内 24% 且不超过 9em；正文超出时省略，群名也可省略。
+- 悬浮或键盘聚焦立即显示完整发送人、群名及已有摘要。提示不会为了补正文再联网。
+- 阅读角标使用独立的阅读者说明，不与整行说明重叠；未知状态仍不显示标记。
+- 点击或 Enter 打开原快记详情；不改变互动身份、时间顺序、原群已读语义及权限。
+
+## 实现范围
+
+仅修改 `ArkmeInterwovenMentionCard` 摘要呈现及对应中英文文字，详情仍保留原发送人头像和姓名。不新增后端接口。补充覆盖双方头像、缺图、损坏图片、切换发送人、悬浮、键盘、详情点击、长群名、省略和提示清理的测试。
+
+上一轮全量回归唯一失败是公开服务方法清单漏登记两个已实现的方法。本轮补齐明确的 `interwovenReadReceipts`、`sourceMessageExtensionParent`，保留严格全量相等检查，不删除或放宽断言。
+
+## 验证
+
+- 4 个相关测试文件、59 项通过。
+- 头像版最终全量：806 个文件通过、11 个文件跳过；9506 项通过、15 项跳过、0 项失败。
+- 类型检查、构建与 `git diff --check` 通过。
+- 3100 独立 Web 预览保留登录并使用头像版；现有私聊 18 条群互动中，双方头像全部正常加载，尺寸为 20×20px。
+- 默认 1153px 及 900 / 680 / 420px 验证，无横向溢出，摘要按钮仍为 28px 高，头像和文字垂直居中。
+- 900px 时长摘要可用宽约 313px，群名 99px；680px 时摘要约 248px；420px 极窄时群名约 40px、正文约 47px，省略更多，但不与状态重叠，可通过完整提示或详情查看。
+- 实际键盘聚焦可显示完整群名、发送人和摘要；Tab 到已读角标后切换为阅读状态说明；Escape 可关闭提示，Enter 可打开原消息详情。
+- 本轮只读导航，不创建测试消息、不移动或删除消息、不直接上报群已读；未修改已安装 Arkme 客户端。
+
+## 交付边界
+
+开发验收时未推送、未创建 PR。随后按用户要求准备合并：先完整备份本地增量及提交历史，再将 PR #702 之后的两个增量提交重放到最新 `origin/dev`（`ffb33cc7`），没有产生冲突。重放前后增量补丁的 SHA-256 完全一致，保留 dev 的 v0.1.82 版本信息和数据管理入口更新，不重复带入已合入的上一批功能。
+
+相关快记云端召回波动、跨端角色同步及双账号实时已读端到端验收仍沿用此前文档的边界，本次没有扩大为后端实现。

package/docs/interwoven-original-read-receipt-regression-2026-09-28.md

@@ -0,0 +1,50 @@
+# 私聊中群互动行：原群消息已读状态
+
+## 需求与展示
+
+- 范围是私聊内容区穿插的群互动单行，不是第二栏联系人卡片。
+- 在摘要末尾、跳转箭头前显示状态，不新增卡片、不增加行高。
+- 未读为小蓝点；已读复用私聊消息及 @ 标识的圆圈对勾。
+- 鼠标悬浮或键盘聚焦立即显示说明，区分“对方已阅读群内原消息”和“你已阅读群内原消息”。仅有明确逐条阅读时间时显示时间。
+- 状态未知保持空白，不能当作未读。原行点击打开详情的行为保持不变。
+
+## 数据语义与接口
+
+新增插件宿主只读操作 `source.interwoven-read-receipts`，参数为 `sourceRef` 和最多 20 个宿主签名的 `momentRefs`。
+
+| 场景 | 状态依据 |
+| --- | --- |
+| 我在群里 @ 当前私聊联系人 | 原群消息 `/api/v1/chats/read-receipts/detail` 中该联系人唯一的成员回执，不使用全群已读数量 |
+| 对方在群里 @ 我 | 原群 `/api/v1/chats/detail` 中自己的有效 `current_cursor` / `unread_snapshot`，与原消息 `seq` 比较 |
+| 原消息不可定位、已撤销、失去权限、对应成员缺失或响应异常 | 未知，不显示蓝点或对勾 |
+
+不会根据私聊行是否可见来确认已读，不调用群已读上报接口，不修改未读数量。
+浏览器只传签名引用；账号、私聊对象、群、消息、发送者、阅读者均在宿主校验。退出/切换账号丢弃旧请求结果。
+
+## 旧服务副本兼容
+
+实际联调发现：World 交织列表的近期记录使用 `chat_legacy_receive_...` 副本 UID，不能直接交给 Chat 的原消息定位接口。直接调用 `/api/v1/chat/timeline/around` 会返回业务码 2001，导致近期互动全部未知。
+
+- 复用 `/api/v1/chats/interwoven/occurrences/query` 获得当前私聊双方互动的 canonical 群、消息、关系、owner 和 seq。
+- 按 Subject 源码 `buildLegacyReceiveRecordEdgeUID` 的既有规则核对副本身份：`chat_legacy_receive_` + `sha256(groupUid + ':' + relationUid)` 的前 32 个十六进制字符。
+- 必须同时匹配私聊、群、消息 owner、发送者及方向；重复身份对应不同原消息则拒绝。不是按正文、时间或名称猜测。
+- 兼容查询每次最多 3 页、每页 50 条，携带结果版本；版本变化/覆盖不完整则不接收映射。精确映射在签名引用有效期内复用。
+- 普通旧 UID 则通过 exact group + owner + record 的 `timeline/around` 校验并取得 seq。
+- 超出兼容窗口或仍无法准确对应的记录保持未知；不宣称所有历史互动均有回执。后续后端若直接返回 canonical locator，可移除这一兼容映射。
+
+## 请求控制
+
+- 只查询可视行（含 80px 预取范围），100ms 合并，每批最多 20 行，宿主上游最多 3 个并发。
+- 存在未读时每 15 秒检查；全未知时每 60 秒重试；网络错误退避至最多 60 秒。
+- 全部已读后停止轮询；实时失效事件、重新聚焦或重新进入可视区域时刷新。
+- 隐藏页面、切换会话/账号会取消请求并清理状态。没有已读状态的无浏览器测试环境安全跳过监听。
+
+## 验证结果
+
+- 10 个相关测试文件共 **713 项通过**，覆盖宿主权限边界、原群 cursor、指定成员回执、旧副本映射、版本变化、分页上限、取消/轮询、账号隔离、行末位置、提示及原点击行为。
+- `pnpm typecheck`、`pnpm build`、`git diff --check` 通过。
+- 3100 独立 Web 预览真实会话：抽查最近 10 条互动，9 条获得明确已读状态，1 条未知并保持空白。出站回执带对方阅读时间，入站 cursor 不伪造逐条阅读时间。
+- 浏览器实际看到摘要行末圆圈对勾，箭头位置保留；聚焦后立即出现正确阅读者提示，Escape 可关闭。当前窄/常规宽度未产生额外行高。
+- 没有为测试发送新消息或上报群已读。仅重新部署独立的 3100 预览，未更改安装的桌面客户端。
+- 控制台仍有运行时重启后的旧控制流断开记录及 TRTC 预加载 AbortError；本次未修改通话模块，不将这些记录描述为已修复。
+- 尚未做双账号实时收发的端到端人工验收，也未推送或合并分支。

package/docs/personal-detail-consistency-regression-2026-09-28.md

@@ -0,0 +1,40 @@
+# 发给自己：跨主题延展与详情一致性回归
+
+## 问题与根因
+
+场景：未分类快记 A 被延展为 B，之后仅将 B 放入主题。
+
+- 聚合个人列表带有 A 的引用，但主题分页中的同一 B 可能完全没有 `parent_record_uid`。
+- `records/detail` 和批量读取的基本记录也没有该关系；不能用“主题列表没给引用”判断“消息没有来源”。
+- 现有 `/api/v1/records/extensions/tree` 能返回 B 的顶层 `parent_record_uid`，以及 A 的记录，即使 `tree` 以 B 为中心、`edges` 和 B 的子回复都是空数组。
+- 原详情只消费列表附带的引用，因而不同入口显示不一致。
+- 相关快记原有读取已按记录身份查询，不按主题过滤；加载期间原来完全隐藏，易被误认为缺少内容。
+
+## 本次处理
+
+1. 复用既有云端延展树；独立解析当前消息的直接来源，不误用整棵树的根或兄弟节点。
+2. 新增插件内部只读操作 `source.message-extension.parent`。仍需有效来源和签名消息操作引用，不接受任意记录 UID 读取。
+3. 个人消息列表仅为可见区域及附近缺失引用的记录补读，最多并行 2 个；同一来源版本已完成的记录不重复读取，切换账号或来源取消旧请求。
+4. 完整详情从消息自己的延展关系补齐来源；主题外的来源可经“全部”定位打开，并支持返回原子消息。
+5. 详情始终显示消息所属主题；时间线气泡仍保持不重复展示当前主题的简约规则。
+6. 相关快记以轻量文字提示正在加载；成功刷新期间保留当前内容；错误可重试，真实空结果仍不占空间。
+7. 原有私聊、群聊引用定位方式不变；私密、不可访问或已删除的来源不泄露正文。
+
+## 验证
+
+- 类型检查、构建、差异空白检查通过。
+- 13 个相关测试文件，共 858 项通过，包含消息发送/目录、详情、角色头像、服务授权和插件操作分发。
+- 后续补充的跨主题气泡点击及取消信号分发测试通过。
+- 3100 独立预览更新，浏览器实际验证：
+  - “未分类 A → 延展 B → B 移入主题”：B 的主题气泡恢复引用；主题内外详情都显示 A、正文、所属主题；点击 A 打开详情，A 的回复列表含 B，可返回 B。
+  - 另一条已有内容的消息在全部与主题内均显示 1 条相关快记、2 条延展，包含正确的本我头像及本地角色表现。
+  - 无回复时不显示空的延展区域。
+- 验证仅使用已有消息读取和页面导航，未发送、移动或删除真实消息；未修改已安装桌面客户端，未推送代码。
+
+## 云端待排查：相关快记结果波动
+
+本次联调同一用户、同一记录、同一组参数的 `/api/v1/records/related/query`，先返回 20 条，随后返回 0 条，再次打开后又返回 20 条。直接请求云端也捕获到 HTTP 200、业务 code 0、`items: []`（另有 `recall_mode` 字段），不只是前端渲染现象。
+
+固定参数形状：`record_uid`、`record_owner_user_id`、`context_type: "record"`、`limit: 20`；不传主题条件。前端没有把空结果替换成历史结果，也没有合成相关内容。
+
+请后端排查同一记录的召回策略、索引就绪状态及空结果稳定性。如果空表示“索引/召回暂未就绪”而非“确实没有关联”，建议提供明确状态或可重试标记，使各端能区分暂不可用与真正为空。本次不能保证云端在不同时刻返回完全相同的相关条目。

package/docs/send-to-self-roles-cross-client-api-handoff-2026-09-27.md

@@ -102,6 +102,14 @@ DELETE /me/self-roles/{roleId}                -> { revision }
 
 本机角色资料的备份/迁移要与消息正文区分：现有正文在云端，本机角色展示元数据若卸载或清空对应本机数据可能丢失。跨端接口落地前不要将“登录同账号”宣传成能恢复角色资料。
 
+### 5.1 角色尚未同步时的头像兼容规则（2026-09-28）
+
+- 当前端有该消息的本机角色快照：继续显示该角色头像（未设图片时使用角色文字头像），保留左侧角色排布。
+- 普通「我」，或另一台设备尚未获得该消息的角色信息：优先使用**当前账号头像**，保留右侧排布。即使消息携带旧头像资产、失效图片地址或其他设备的本机头像引用，也不能让这些引用优先于可用的当前账号头像。
+- 上述规则统一覆盖「发给自己」、个人主题内的消息列表、消息详情及本人延展回复；不替换其他作者或私聊群聊的头像。不增加“当前资料”等提示文案。
+- 这是显示层回退，不是角色同步。不得把回退得到的账号头像写成角色历史快照，不得清除本机角色绑定。未来云端角色快照回填成功后，其他端再按真实角色信息展示。
+- 当前账号资料尚未加载时可暂用记录已有头像；资料到达后自动切到账号头像。账号本身没有设置头像或网络无法读取头像时，仍使用既有默认显示，不能伪造头像。
+
 ## 6. 联调验收
 
 1. A 端建角色并设头像，B 端在线时及时出现；B 端断网后重连也能补齐，账号 C 绝不可读。
@@ -112,6 +120,7 @@ DELETE /me/self-roles/{roleId}                -> { revision }
 6. 列表、详情、搜索、分页、刷新和重新登录的展示一致；角色消息仍由真实账号拥有，不生成自发未读/通知。
 7. 本机旧数据迁移后的消息条数不变，逐条核对快照及头像；冲突有可审计结果。
 8. 迁移前已删除的角色、直接在详情页发送的延展、多个独立本机目录分别导入后，其他端均按各条消息发送时的角色显示；断网重试和重复导入不改写快照。
+9. 同步接口上线前：A 的本我消息显示当前账号头像，A 的角色消息保留角色头像；B 无对应角色信息时统一显示当前账号头像。列表、详情、延展回复一致；回退前后本机角色绑定及历史快照保持不变。
 
 ## 7. 请后端同事优先确认