# Arkme 插件后端协作统一交接

更新：2026-10-20。面向：即我项目大群。插件仓库：arkme-senx/arkme-dsh-plugin。

本文汇总本轮团队消息、消息交互及内置会话入口的后端协作要求，并附此前交接事项的核对索引。插件本轮功能提交截至 `a9f2359b`，计划先合 dev、再合 master；实际合并与版本以 PR 和发布记录为准。本文不表示后端已开发或已部署，不含个人消息、录音、生产候选 JSON、凭据或媒体授权链接。

## 一、先明确已经接通的内容

以下已有能力请复用，不要因为旧交接仍写“未接通”而重复开发：

- **团队整条延展回复已接通。** 后端 `reply_to` 已存在，本轮插件已贯穿引用草稿、持久发送队列、重启/重试、消息返回和原文定位。旧文档中“队列不保存整条引用”已过时。现在缺的是精确选区引用、反向相关快记及更高效的定位，不是基础整条回复。
- **团队问 DSH 已接通。** 使用现有 Team 原件授权读取，准备消息摘录及附件到 DSH 草稿；不自动向模型发送，不需要新增“问 DSH”后端接口。
- **团队成员/访客头像操作、个人备注、消息阅读侧栏、消息气泡及时间位置、输入框提示和本机输入计时已完成。** 私人备注仅对当前查看者生效；“看TA的快记”当前范围明确为该人在当前团队对话中的消息，不是其全部私人记录。
- **团队已读界面已复用群聊样式。** 使用已有 `read-receipts/query`；已读按返回时间在上，未读在下，无筛选 tab。本人消息侧边显示已读人数和外部已读颜色。需补的是下文的口径、时间及聚合协议。
- **团队顶部日历、搜索、活跃时间及导出已有前端分页读取兼容实现。** 有逐页进度，支持暂停/重试；不是进入聊天就全量扫描。词频仍需正式服务。个人身份通话复用已有私聊通话链路，不等同团队身份呼叫。
- **团队入口、通知、发给自己、Arko、DeepSeek Harness 的右键预览/置顶已可用。** 团队入口可本机移除；通知与三个内置入口不开放移除。预览只读，不推进已读。跨设备偏好尚需下文协议。
- **通话预览稳定性、宽屏紧凑布局、选区查找/精确替换、VIP/SVIP 悬浮说明、默认头像恢复**属于插件修复，本轮没有因此新增必需后端接口。

上述是插件实现和已有契约状态；自动测试、3102 页面验证不代替服务端生产部署和真实多人联调。

## 二、本轮优先对接清单

### P1-01 团队外部身份、会员与资料投影

**现状证据：** 10 月 19 日生产只读抽查中，团队会话 `visitor` 仅含昵称、头像，没有会员字段或稳定外部账号身份。后来插件增加了受权限校验的身份解析与私聊入口；它不能替代服务端稳定投影。本轮未重新确认生产是否已升级，请先回传实际版本。

请在 `conversations/list`、`open`、`timeline/page` 以及其他返回会话资料的入口统一：

- 可信外部访客身份（建议 `external_user_id`，最终字段由后端确认）；实际内部发送成员 `actor_user_id`；阅读名单身份同属 Chat 用户命名空间。明确人、机器人、系统、注销状态。
- `visitor.member_type`：`vip / svip / free / unknown`。现有插件兼容 `0/1/2` 对应 free/vip/svip；若使用其他枚举须先对齐。未提供不等于非会员。
- 会员按**当前有效权益**判断，不代表曾经付费。批量资料查询与短缓存失效不阻塞正文；会员变化不能依赖消息正文 revision 才刷新。
- 同一投影避免翻页或发送返回旧资料覆盖已知会员/头像。个人备注复用查看者自己的 Chat 备注，不维护团队共享备注，不泄露给访客或其他成员。
- 头像/昵称不能作为身份键，不能凭最后一条外部消息推断永远有效的访客身份。所有私聊、快记、原件读取重新验证成员资格及会话权限。

**验收：** 同名不同人、VIP/SVIP/免费/未知、权益到期与升级、成员退出、账号切换；列表、标题、预览、详情和阅读名单一致。文档：`团队消息访客会员状态-后端交接-20261019.md`、`团队成员身份与消息详情统一-后端补充交接-20261019.md`。

### P1-02 团队阅读状态的准确口径与增量更新

已用 `POST /api/v1/team/conversations/read-receipts/query`，字段含 `members[].user_id/identity/read/read_at`、`visitor_read`、`has_more/next_cursor`。

需要明确或补齐：

1. `read_at` 是本条首次已读，还是最近阅读游标更新时间？注明单位；前端不能擅自改称首次阅读。
2. 外部联系人阅读时间：当前插件仅收到 `visitor_read` 布尔值，建议增加语义明确的独立时间字段；未知时间留空。
3. 接收者集合采用发送时成员还是当前成员；加入、退出、停用如何计数，排除发送者，未知与未读分开。
4. 稳定分页快照，及可见消息的批量/聚合查询：总接收人数、已读、未读、未知。不要要求每条消息拉全成员才能显示一个数。
5. 阅读变化事件只更新回执缓存，不重载正文、打断滚动或输入。当前轮询仅为兜底。
6. 外部视图只能读取获准的聚合状态，不暴露内部名单。

**验收：** 外部来信部分内部已读；内部发送后外部未读→已读；多人分页和成员变动；刷新不改变阅读位置。详见 `团队消息通道后端协作汇总-20261019.md` 第 4 节，旧三 tab 界面说明已废弃。

### P1-03 团队表态、链接、转发、举报、撤回

本次核对 jotmo-team master `21cfe2019ae23b6f00c64c1bed0003c27812029b`，这是源码证据，**不证明生产运行该 SHA**。若其他分支或服务已有实现，请提供契约与部署版本，优先复用。

| 能力 | 请后端提供或确认 | 验收要求 |
| --- | --- | --- |
| 表态 | 消息级快照、增加/取消、作者身份、幂等、版本及变化事件；内外部可见范围 | 两端同步、重复请求不叠加、退出/删消息后不越权 |
| 消息链接 | 稳定消息定位/分享协议、访问范围与删除/失权状态 | 跨设备定位原消息；不能把团队总入口链接或本机加密引用当消息链接 |
| 转发 | 优先核对已存在的 `record_ref/source`、`RecordClient.AuthorizeReference`；明确 Team→私聊/群聊/自己/Team 的可用方向 | 原件重新授权、逐条结果、超时核对、不可泄露临时媒体地址；当前 Chat 转发不能直接吃 Team 引用 |
| 举报 | 原消息身份与正文版本、原因、证据、去重、处理结果 | 作者由服务端关系解析，不能按昵称判断 |
| 撤回 | 独立权限、时限、占位与事件 | `cancel` 取消发送、`delete` 删除 Record 均不能直接冒充撤回 |

前端暂不可用项不能仅移除 disabled 就算对接。整条延展与问 DSH 已接通，不在本缺口表内。详见 `团队消息右键操作接通与剩余协议-后端交接-20261020.md`。

### P1-04 精确选区回复、共享文字标记与相关快记

- **部分引用**需保留原会话/消息、版本与规范化文本锚点。现有选区表示：`version=1, projection=arkme-text-v1, sourceDigest, recordVersion, start, end, text, prefix, suffix`；偏移按规范文本 UTF-16，不是 Markdown 源码。最终 HTTP 字段应与现有 Record/Chat 模型对齐。
- 锚点贯穿发送持久队列、幂等重试、读取投影和原文定位；同一词多次出现要定位被选那一处。编辑后不静默挪到近似文本；删除/失权有明确状态，不泄露原文。
- **文字标记**现在是选中文字背景强化，可点击取消；本机保存不代表多人共享。需要能力协商、快照/增量、增删、作者权限、版本冲突与幂等，明确团队内部可见和外部可见范围。已有本机私人标记不能自动上传变共享。
- **相关快记/反向延展**需受权分页、关系类型、数量、作者、时间、来源及定位；无数据、不支持、无权限、失败分开。当前加载页不能冒充全部关联。
- Team 身份不可直接套普通 Chat actionRef；如果 Team 底层 Record 已有可复用映射，应由服务端验证后提供，不另建一套关系。

范围覆盖普通私聊/群聊、发给自己、Arko、团队，各来源能力独立声明。参考 `消息局部引用回复-后端交接-20261018.md`、`消息标记共享同步-后端交接-20261018.md`；旧“划线”文案以背景标记方案为准。

### P1-05 团队记忆快照与采集数据持久化

右键本人消息已使用普通对话的记忆快照弹窗；目前仅有 Team `created_at` 和正文可算字数，缺失值显示未记录。**本机输入时长尚未随团队发送保存到云端。**

请先确认 Team 是否生成底层 Record、稳定映射和作者权限；已有记录详情/发送字段能够复用则直接提供示例。需要定义：

- 实际开始编辑时间、确认发送的完成时间、自然经过/活跃编辑时长（明确口径）、服务端创建时间、最终同步时间，不互相冒充。
- 当次用户已授权采集的设备/位置/精度/采集时点及已有快照字段；无采集、无权限、不可用、历史缺失、真实 0 分开。不得用当前设备或当前位置补历史。
- 同一发送 UID 冻结完成时点，贯穿落盘、附件上传、重启恢复、结果查询与重试；编辑记录不覆盖首次采集上下文。
- 详情读取验证查看者、作者、团队会话和消息状态。作者设备/位置不是全团队可见的回执信息，不给其他成员/访客泄露。
- 能力与字段状态可查询；旧客户端不传新字段仍可正常发消息。

服务约定后插件需补 Host 投影、队列元数据和详情读取，不能宣称前端弹窗出现就已经保存。详见 `团队消息输入统计与记忆快照-后端补充交接-20261020.md`。

### P2-01 入口偏好统一跨端同步

团队、通知、发给自己、Arko、Harness 的置顶目前是**当前账号的本机偏好**。需要同一用户的云端入口偏好协议，不是修改团队公共配置：

- 稳定入口类型/身份、pinned、可移除入口的 dismissed、版本与幂等操作 ID；内置入口和通知不可移除。
- 读取、设置、变更事件和断线补偿；即时本地反馈，后台失败可重试；本机空值不能覆盖另一设备云端偏好。
- 团队总入口移除需要服务端原子的新消息活动水位，覆盖未加载访客及未来新访客。编辑、已读、资料更新不能误使入口恢复。
- 只读预览不推进阅读水位，不更改当前会话、不创建任务。

详见 `团队消息入口偏好同步-后端交接-20261019.md`；本轮新增内置入口复用该协议方向，无需三个独立接口。

### P2-02 团队大历史查询、分析与导出

- 词频：授权范围显式包含 `team_conversation`，默认所有消息，支持 all/self/稳定成员、日期范围、时区。响应提供实际范围、快照、水位、任务进度与覆盖情况；`count` 出现次数与 `message_count` 命中消息数分开；词云可回到精确原文。
- 日期索引：每日消息数与首条锚点；搜索：关键词/作者/日期/稳定分页；定位：按 UID/seq 返回邻近消息；个人快记筛选：服务端按实际发送者筛选。
- 活跃时间：24/168 桶，计入全部可见消息类型，不只文字。稳定作者去重、缺失时间披露，原文分页对应同一统计快照。
- 导出：固定快照/水位、权限复核，必要时异步任务与进度。`before_seq` 本身不是对并发编辑/删除的原子快照。
- 不让每个客户端长期扫描全部历史；现有按需分页作为兼容路径。当前生产 Chat 统计接口不当然适用于 Team。

详见 `团队对话顶部工具与分析-后端交接-20261020.md`。如果以后要团队身份通话，还须明确外显身份、接听分配、记录归属及录音权限；本轮的个人身份通话不等待该升级。

## 三、此前需求的统一核对索引

以下事项已有交接或独立开发工作，**本轮未重新审计其生产完成度**。请负责人回传“已上线/待联调/未完成”及版本，不能直接按旧文档认定还没开发：

| 方向 | 对接重点 / 已有文档 |
| --- | --- |
| Arko 图片与历史 | 图片能力声明、模型实际看图、资产权限/顺序、幂等运行与历史；关键词/日期定位到完整消息、稳定导出。`Arko图片输入-后端对接-20261018.md`、`Arko对话统一-后端对接-20261018.md`。已有同事开发分支，先对齐再补做 |
| 说话人学习、证据及归并 | 持续学习、否定事实、完整组一致性、真实距离/次近差距、相似候选、原子拆分/归并/撤销和计数。对应 10 月 16 日说话人三份交接；已有接口 PR #864，仍须明确部署及页面接线边界 |
| 录音实体与探索五板块 | 实体身份合并、本人提及优先同时保留所有参与者、播放内容区分、ASR 原音证据、任务恢复、来源跳转与人工纠正。10 月 15 日实体/探索文档；历史 14/17 卡点不能当作当前实时任务状态 |
| 多源日总结/时间轴 | 精准区分主体/来源/时间，复用分层压缩，提示词版本与实际应用回执、任务恢复、来源可定位。10 月 16 日多源交接；已有 SDK/工具 PR #865，不等同生产所有入口已验收 |
| 线下录音与线上聊天关联 | 候选召回、语义复核、精确时间回插、个人可见与主动共享、回听定位。原 10 月 15 日文档的“仅本机预览”已被 dev #891 的正式确认/纠错/分享接线更新；优先核验新实现，不重复开发 |
| 词频与口头禅/活跃分析 | 个人快记关键词、私聊群聊按人、录音仅本人原音校验；次数与消息数分开，完整覆盖和精确来源。10 月 16 日各专项交接；不同数据源能力不能互相冒充 |
| 关系与统一人物 | 联系人、手标说话人、人物档案的可靠身份关联；分页、按需详情、同来源去重。`统一人物档案与跨系统身份关联-后端交接-20261017.md`、`关系加载分页与原文聚合后端交接-20261018.md` |
| 安排来源 | 已上线 source/read 能力继续复用；区分原来源可访问与引用原句匹配结果，稳定 ID/版本与准确历史回填。`安排来源链路对接进展-20261016.md`；个人候选数据不是全用户迁移输入 |
| 录音存储/历史计量、批次通知 | 真实仍存 OSS 产物去重与历史 ASR 执行凭据；批次两阶段通知、跨日生成和失败恢复已有协议，按异常闭环核验。10 月 15 日存储计量及 10 月 13 日导入交接 |

此前总索引：`后端需求交接总览-20261016.md`。本节只归集跟踪，不扩大本次后端开发或部署权限。

## 四、回交给插件的最小信息

请按事项编号回复：负责人、已有/新增能力、正式请求和脱敏响应、错误状态、权限与时间/计数口径、能力版本、部署环境和提交、事件定义、联调方式。

写操作需给幂等及结果查询、版本冲突、重试/撤销规则；读取需给稳定分页、删除/失权状态与来源定位。建议先交付 P1-01/02 的资料与回执合同，再并行处理消息操作、共享标记及快照；统计/跨端偏好可独立迭代。

验收必须覆盖账号切换、团队退出、同名人物、旧消息编辑/删除、离线与重启、超时不重复提交。后端字段缺失不能伪装成 0、免费、未读或无结果。前端继续沿用现有共享交互；本次不改后端代码、不部署后端、不执行个人历史回填。