hansjone/dsh-im-ops
1
0
Fork 0
mirror of https://github.com/hansjone/dsh-im-ops.git synced 2026-10-09 00:33:20 +08:00
Code Issues Projects Releases Packages Wiki Activity Actions

update md

Browse source
This commit is contained in:
xmanrui 2026-08-24 02:18:24 +08:00
parent 1d7f6a5a0a
commit 6fcb12c90f
1 changed files with 179 additions and 88 deletions
Download patch file Download diff file Expand all files Collapse all files

267
docs/方案/渠道原生能力建设方案.md
View file

@ -4,9 +4,9 @@
| 项目 | 内容 |
| --- | --- |
| 状态 | 执行版 v2；PR 链 1 已完成九渠道原生结果文件发送、自动化与本机发布验收，随本提交交付 |
| 更新日期 | 2026-08-23 |
| 代码基线 | 方案初次盘点基于 `@xmanrui/dsh-im@1.0.2`、`main@59ed364`，实施提交的父基线为 `main@2803bbc`；本机 `npm run check` 975/975 通过 |
| 状态 | 执行版 v3；PR 链 1 已随 v1.1.0 发布，九渠道普通文件入站已随 v1.3.0 发布；PR 链 2、3 尚未实现，基线与测试清单已刷新 |
| 更新日期 | 2026-08-24 |
| 代码基线 | `@xmanrui/dsh-im@1.4.0`、`main@1d7f6a5`；本机 `npm run check` 1036/1036 通过，构建与发布包校验通过 |
| 适用范围 | 九个 IM 渠道；AI Office Connector 作为相邻消费者纳入回归边界，但不算第十个 IM 渠道 |
| 需求入口 | [#16 发送文件](https://github.com/xmanrui/dsh-im/issues/16)、[#27 Discord 自动创建 Thread](https://github.com/xmanrui/dsh-im/issues/27)、[#28 Telegram Rich Message](https://github.com/xmanrui/dsh-im/issues/28) |
| 领域语言 | [CONTEXT.md](../../CONTEXT.md) |
@ -27,10 +27,10 @@ dsh-im 已经是一个具有九渠道多机器人管理、工作区与 Session
当前首批能力直接由三个真实 Issue 驱动，并根据已确认的用户价值和当前交付承诺排序：
1. **#16 结果文件回传**：最初由 DSH → 飞书 HTML/文件场景驱动；目前全局回传工具、Session/Turn 路由、文件快照完整性、九渠道原生发送路径和本机逐渠道验收均已完成，作为无需项目配置的默认能力提供。
1. **#16 结果文件回传**：最初由 DSH → 飞书 HTML/文件场景驱动；全局回传工具、Session/Turn 路由、文件快照完整性和九渠道原生发送已经随 v1.1.0 发布，作为无需项目配置的默认能力提供。
2. **#27 Discord 会话落点与 Thread 隔离**：解决服务器频道多人共享同一 Harness Session 的正确性风险。
3. **#28 Telegram 原生 Rich Message**：保留 Markdown/结构化呈现意图，接入 Telegram Rich Message 与 Rich Message Draft。
4. 在前三个切片验证语义脊柱后，再推进原生审批/选择、引用内容、普通文件输入、语音和其他渠道富呈现。
4. 九渠道普通文件输入已经作为独立能力随 v1.3.0 发布；前三个切片之后继续推进原生审批/选择、引用内容、语音和其他渠道富呈现。
三个 Issue 分别验证统一方案的三个关键边界：#27 验证会话路由和渠道原生动作，#16 验证文件快照、Session/Turn 路由与交付编排，#28 验证呈现意图和渠道原生渲染。它们必须形成三个独立 PR/提交链，不能捆绑成一次高风险重构。
@ -59,20 +59,21 @@ dsh-im 已经是一个具有九渠道多机器人管理、工作区与 Session
## 3. 当前基线与问题定义
### 3.1 1.0.2 已经具备的公共产品能力
### 3.1 v1.4.0 当前发布产品能力
以下能力是当前发布产品的基线，不是未来路线图：
| 基线类别 | 1.0.2 已有行为 |
| 基线类别 | v1.4.0 当前行为 |
| --- | --- |
| 渠道与账号 | 一个设置入口管理九个 IM 渠道；每个渠道支持多个机器人，凭据、连接状态、工作区、Agent Preset 和会话映射彼此隔离 |
| 安全接入 | 扫码、Manifest 或手工凭据接入；Secret/Token 只进入 Host 凭据存储，浏览器和状态 RPC 只获得脱敏投影 |
| 消息输入 | 九渠道均支持文字和受控图片输入；JPEG、PNG、WebP 及图片形式 GIF 支持可选说明，单图 5 MB、单消息合计 20 MB |
| 消息输入 | 九渠道均支持文字、受控图片和普通文件输入；图片维持既有格式与大小规则，普通文件由渠道原生下载后原样写入当前 Session 工作区，由 Harness 决定是否读取和如何处理 |
| 文件交付 | 九渠道均可接收用户普通文件并在同一 Turn 保持文件名与顺序；Harness 可通过全局 `dsh_im_return_file` 将现有或新建普通文件作为渠道原生附件回传 |
| Harness 会话 | 按机器人与聊天持久绑定 Session；支持工作区切换、Session 列表与绑定、模型查询与切换、停止、纠偏和上下文压缩 |
| Agent Preset | 每机器人独立选择或跟随 Host 默认；只影响之后新建 Session，不改变已有会话和在途回复 |
| 控制命令 | `/help`、`/new`、`/status`、`/models`、`/model`、`/presetlist`、`/preset`、`/stop`、`/steer`、`/compact`、`/workspace`、`/workspacelist`、`/sessionlist`、`/session` |
| Harness 交互 | 九渠道已经能够用文字完成问题与审批；Actor/Route 所有权、FIFO、重放去重、跨端解决、取消和失败重试已有大量自动化覆盖 |
| 回复体验 | 飞书/钉钉卡片流、企业微信/QQ/Slack 原生或准原生流、Telegram/Discord 编辑消息、WhatsApp typing + 最终消息；失败时已有安全恢复路径 |
| 回复体验 | 飞书/钉钉卡片流、企业微信/Slack 原生或准原生流、QQ Markdown 与按渠道收敛的 Turn Feed、Telegram/Discord 编辑消息、WhatsApp typing + 最终消息；失败时已有安全恢复路径 |
| 运维可靠性 | 连接测试、自动重连、状态持久化、多机器人生命周期、并发竞态、工作区代际隔离、删除清理和敏感错误脱敏均已有测试资产 |
AI Office Connector 也已实现 `office-harness.v1`、Heartbeat/SSE、任务租约、独立 Harness Session、进度回传以及问题/审批闭环。它不是第十个聊天渠道，但证明了问题、审批、任务状态和终态幂等已经存在可复用的领域行为；后续语义演进不能破坏 Office。
@ -81,22 +82,22 @@ AI Office Connector 也已实现 `office-harness.v1`、Heartbeat/SSE、任务租
- Discord、Slack、Telegram、WhatsApp 复用 [`TextHarnessBridge`](../../src/channels/shared/text-harness-bridge.mjs)。
- 飞书、钉钉、企业微信、QQ、微信保留独立 Bridge，以承载不同的流式、卡片、扫码协议和交互时序。
- 公共目录已经包含工作区/Session、模型、Agent Preset、问题、审批、图片安全、任务控制和可编辑消息流等成熟服务。
- 公共目录已经包含工作区/Session、模型、Agent Preset、问题、审批、图片安全、普通文件入站、出站产物、交付回执、任务控制和可编辑消息流等成熟服务。
- 飞书已经拥有交互式菜单、Session/Workspace 卡片、Watch/完成推送、归档显示控制、回调修复、群响应模式和权限授权等明显超出“文字机器人”的渠道专属能力。
因此，当前问题不是“没有公共层”，而是**公共层在内容与交付边界仍偏文字化，渠道专属 Bridge 又没有共享完整的语义交付契约**。新方案必须复用成熟的会话、命令、交互和安全实现，只在三个 Issue 需要的位置增加语义接缝。
因此，当前问题不是“没有公共层”，也不再是“没有文件能力”，而是 **Discord 会话路由仍没有原生 Thread 落点，Harness 输出仍没有保留可供 Telegram 富渲染的呈现意图**。后续必须复用成熟的会话、命令、交互、文件和安全实现，只在 #27、#28 需要的位置增加最小语义接缝。
### 3.3 0.14 之后的迭代已经改变迁移前提
### 3.3 从 0.14 到 v1.4.0 的迭代已经改变迁移前提
旧方案形成时使用的是 0.14 附近的代码认知。本次方案初次盘点使用 `main@59ed364`，实施前父基线更新至 `main@2803bbc`：它们包含 1.0.2 发布版，以及发布后的微信接入错误分类、UI 和图像资产更新。到这一基线，项目已经历多个稳定版本，至少新增或强化了：
旧方案形成时使用的是 0.14 附近的代码认知；本方案初次盘点使用 `main@59ed364`，PR 链 1 开始前的父基线为 `main@2803bbc`。这些提交只作为历史起点保留，**当前实施基线已经更新为 `v1.4.0@1d7f6a5`**。此后至少完成了：
- 飞书原生交互卡片、Session/Workspace 列表、会话 Watch 与完成推送、归档筛选、回调与群消息权限修复。
- 每机器人 Agent Preset 的设置页与聊天命令完整生命周期。
- Telegram 原生命令菜单与机器人级兼容/安全访问模式。
- 九渠道图片输入、工作区/Session/模型/控制命令和多机器人隔离的大量竞态与失败恢复测试。
- AI Office Connector 的外连协议、租约、问题审批和终态一致性。
- v1.1.0：全局结果文件工具、Session/Turn 快照完整性和九渠道原生结果文件发送。
- v1.2.0：WhatsApp 访问模式等渠道能力继续演进。
- v1.3.0：九渠道普通文件原生接收、当前 Session 工作区交接和真实客户端验收。
- v1.4.0：QQ Markdown 与 Turn Feed 收敛，并继续强化交付消息去重。
- 既有飞书专属能力、每机器人 Agent Preset、Telegram 命令菜单与访问模式、AI Office Connector，以及工作区/Session/命令/问题审批的竞态与失败恢复测试全部继续保留。
这意味着 `TextHarnessBridge` 和各渠道独立 Bridge 都是生产资产。迁移不再以“新增一套新目录后替换旧类”为目标，而以**能力切片内的增量包裹、双路径验证和等价接管**为目标。
这意味着 `TextHarnessBridge`、各渠道独立 Bridge、普通文件管线和产物交付管线都是生产资产。迁移不以“新增一套新目录后替换旧类”为目标，而以 **能力切片内的增量包裹、明确回退和等价接管** 为目标。
### 3.4 方案起点识别的真正有损边界
@ -104,7 +105,7 @@ AI Office Connector 也已实现 `office-harness.v1`、Heartbeat/SSE、任务租
1. **呈现意图变窄**：当前 `HarnessReplyTracker` 只从 `assistant/chunk` 和 `assistant/message` 保留文本，并故意不渲染 `tool/result`；这保护了工具结果中的敏感内容，但也使普通最终回答收敛为字符串。Telegram 因此无法使用 2026 年新增的 Rich Message/Rich Message Draft。
2. **会话路由过粗**：Discord 在父频道中被 @ 时直接使用父 `channel_id`，没有创建原生 Thread 的会话落点策略；已有 Thread 内消息可以按 Thread Channel ID 隔离，但父频道多人仍可能共享 Session。
3. **出站产物缺位（已补齐）**：方案起点只有图片输入安全链路和渠道 SDK 文件接口，没有 `OutboundArtifact → 渠道附件` 闭环。PR 链 1 已增加默认全局可用的 `dsh_im_return_file` 工具、Session/Turn 绑定、不可变文件快照和九渠道原生发送适配，并完成自动化与逐渠道本机证据留存；后续工作是提交和发布，而不是重新设计出站文件准入策略。
3. **出站产物缺位（已补齐并发布）**：方案起点只有图片输入安全链路和渠道 SDK 文件接口，没有 `OutboundArtifact → 渠道附件` 闭环。PR 链 1 已增加默认全局可用的 `dsh_im_return_file` 工具、Session/Turn 绑定、不可变文件快照和九渠道原生发送适配，并随 v1.1.0 发布；后续只做回归和平台兼容，不重新设计出站文件准入策略。
4. **能力声明不完整**：平台文档、锁定 SDK、当前代码和真实客户端之间仍缺少统一证据链，容易把“平台有 API”误写成“本项目可用”。
这些缺口不能笼统归因于“过度封装”：#28 主要暴露文字边界上限，#27 主要是 Discord 专属产品策略尚未实现，#16 则需要公共文件快照与各渠道上传适配。方案必须按原因分别处理。
@ -113,11 +114,11 @@ AI Office Connector 也已实现 `office-harness.v1`、Heartbeat/SSE、任务租
| Issue | 用户任务 | 统一语义最小增量 | 渠道原生实现 | 优先级 |
| --- | --- | --- | --- | --- |
| [#16 发送文件](https://github.com/xmanrui/dsh-im/issues/16) | 在当前聊天直接收到 Harness 要交付的现有或新建文件；首个确认场景是 DSH → 飞书的 HTML/文件回传 | 全局 `dsh_im_return_file`、Session/Turn 路由、`OutboundArtifact` 快照完整性和逐产物回执 | 已从飞书闭环扩展到默认可用的九渠道原生文件发送；格式、大小、权限和配额由渠道 API 决定 | P0：实现与本机验收已完成，随本提交交付 |
| [#27 Discord 自动创建 Thread](https://github.com/xmanrui/dsh-im/issues/27) | 在服务器频道 @ 一次开启独立对话，避免多人上下文串线和主频道刷屏 | `ConversationRoute.threadId`、最终会话落点和幂等路由；原始父消息 ID 只留在 Discord 动作上下文 | 查询 Channel 类型、从消息创建 Public Thread、在线程内回复；权限失败回到父频道现有路径 | P0：正确性与隔离 |
| [#16 发送文件](https://github.com/xmanrui/dsh-im/issues/16) | 在当前聊天直接收到 Harness 要交付的现有或新建文件；首个确认场景是 DSH → 飞书的 HTML/文件回传 | 全局 `dsh_im_return_file`、Session/Turn 路由、`OutboundArtifact` 快照完整性和逐产物回执 | 已从飞书闭环扩展到默认可用的九渠道原生文件发送；格式、大小、权限和配额由渠道 API 决定 | P0：已随 v1.1.0 发布并纳入当前回归基线 |
| [#27 Discord 自动创建 Thread](https://github.com/xmanrui/dsh-im/issues/27) | 在服务器频道 @ 一次开启独立对话，避免多人上下文串线和主频道刷屏 | `ConversationRoute.threadId`、最终会话落点和幂等路由；原始父消息 ID 只留在 Discord 动作上下文 | 查询 Channel 类型，按父频道创建 Public/Announcement Thread 并在线程内回复；建路由前的确定性失败回到父频道现有路径 | P0：正确性与隔离 |
| [#28 Telegram Rich Message](https://github.com/xmanrui/dsh-im/issues/28) | 在 Telegram 中正确阅读标题、列表、代码、表格、公式和流式 AI 回答 | `DeliveryBlock(text.format)` 与呈现意图；不引入 Telegram 专属 Block 到核心 | `sendRichMessageDraft`、`sendRichMessage`，再降级到普通格式消息和纯文本 | P1：结果可读性 |
#16 正文只有 `todo`，但 2026-08-20 至 2026-08-21 的 Issue 讨论已明确确认 DSH → 飞书 HTML/文件回传是本 Issue 的目标场景。本方案因此将其限定为**出站结果产物回传**；用户向 Harness 发送普通文件属于后续独立切片。飞书作为首个闭环验证了公共产物契约，随后已扩展到其余八个渠道的原生发送路径。#27 和 #28 同样只增加闭环所需的最小语义，不要求其他八个渠道复制 Discord Thread 或 Telegram Rich Message UI。
#16 正文只有 `todo`，但 2026-08-20 至 2026-08-21 的 Issue 讨论已明确确认 DSH → 飞书 HTML/文件回传是本 Issue 的目标场景。本方案因此将其限定为 **出站结果产物回传**；用户向 Harness 发送普通文件不属于 #16，但该独立能力也已经随 v1.3.0 在九渠道发布。#27 和 #28 只增加闭环所需的最小语义，不要求其他八个渠道复制 Discord Thread 或 Telegram Rich Message UI。
### 3.6 当前功能是迁移资产，不是重构成本
@ -135,7 +136,7 @@ AI Office Connector 也已实现 `office-harness.v1`、Heartbeat/SSE、任务租
矩阵中的每一项都必须关联现有自动化测试、事件 Fixture 或真实客户端清单。不同渠道原本不具备的能力不凭空列为基线，但某渠道已经拥有的原生体验不能因为其他渠道没有而降为最低公分母。
### 3.7 PR 链 1 当前实现状态
### 3.7 PR 链 1 已发布状态
九渠道已经共享同一套结果文件回传语义：Host 启动时全局注册 `dsh_im_return_file`，首个 IM Turn 就可调用，不存在机器人级或请求级开关。工具接受绝对路径，或相对于当前 Harness 工作区的路径；现有文件和当前 Turn 新建的文件都可直接回传，不需要为交付而重新创建、改名或移入工作区。
@ -216,7 +217,7 @@ AI Office Connector 也已实现 `office-harness.v1`、Heartbeat/SSE、任务租
### 4.5 入站安全与出站完整性分开收口
远程下载、回调身份、交互重放、入站大小限制和日志脱敏必须由公共安全策略约束；渠道适配器不能绕过。出站本地文件是另一条边界：公共层只保证目标是存在、可读的普通文件，绑定 Session/Turn 并保证快照完整性；不把入站下载的域名、格式、大小和内容扫描规则套到出站。
远程下载来源、工作区路径与清理、回调身份、交互重放和日志脱敏必须由公共策略约束；渠道适配器不能绕过。普通文件入站不增加插件级类型、大小、数量或内容判断，出站本地文件则只保证目标是存在、可读的普通文件，绑定 Session/Turn 并保证快照完整性；两条边界都不替 Harness 处理文件内容。
### 4.6 以渠道行为基线为发布下限
@ -413,7 +414,7 @@ interface InboundArtifact {
mediaType?: string;
declaredSize?: number;
source: 'channel';
open(options: { signal: AbortSignal; maxBytes: number }): Promise<Readable>;
open(options: { signal: AbortSignal }): Promise<Readable>;
}
interface OutboundArtifact {
@ -440,6 +441,8 @@ interface OutboundArtifact {
}
```
`InboundArtifact.mediaType` 和 `declaredSize` 只记录渠道元数据，不是普通文件准入条件；普通文件读取只服从当前 Turn 的取消信号，不接受插件级 `maxBytes`。既有图片输入继续使用独立的图片安全链路和既有图片上限，不能把图片规则反向套到普通文件。
`dsh_im_return_file` 的入参是本地路径，但交给渠道适配器的产物不再是该路径，而是调用时创建的受管快照。`mediaType`、`size`、`source` 和 `createdAt` 是传输元数据，不是准入条件；快照没有产物 TTL。只有工具成功结果会提交到调用时的 Session/Turn，适配器通过快照读取文件，不向远端用户暴露 Host 绝对路径。
### 6.5 语义输出与进度
@ -463,6 +466,8 @@ interface DeliveryReceipt {
deliveryId: string;
presentation: string;
providerMessageIds: string[];
deliveryOutcome?: 'sent' | 'failed' | 'unknown';
reason?: string;
artifacts?: Array<{
artifactId: string;
outcome: 'sent' | 'rejected' | 'failed' | 'unknown';
@ -471,6 +476,8 @@ interface DeliveryReceipt {
}
```
v1.4.0 的文字回执只在确认发送后创建，因此旧回执缺少 `deliveryOutcome` 时按现有成功语义读取。PR 链 3 如遇最终消息调用后的不确定结果，以向后兼容的可选字段记录 `unknown`，不能为了填满字段改写其他渠道，也不能用补发制造第二份最终消息。
Harness 输出的 Markdown 作为语义文本保存，渠道适配器负责转换到 MarkdownV2、mrkdwn、卡片 Markdown、Discord Markdown、WhatsApp 格式或纯文本。禁止在核心层提前转换成某个平台语法。
## 7. 渠道能力模型
@ -574,24 +581,24 @@ interface ChannelAdapter {
降级不应改变安全边界。例如平台不能发文件时，不能临时把本地文件上传到未授权公共图床；这一原则不等于在调用原生 API 前增加插件格式或大小限制。
只有转换失败、能力明确不支持或平台返回确定性拒绝时才能进入下一层降级。请求发出后发生超时、断线、5xx 或取消时，结果可能已经被平台接受：此时先记录 `unknown`，能按稳定 ID 查询就查询收敛，不能确认时不得再发送另一份最终消息。调用前取消不发送；调用后取消按不确定结果处理。
明确降级也不能被用来掩盖迁移回归：如果某渠道当前已经提供原生流式、卡片、typing、图片输入、语音识别、Thread 或其他能力，新语义路径必须保留或改善该能力，不能永久退回文字方案。只有该能力原本不存在，或平台接口在运行时暂时不可用时，才能按本表降级；临时降级恢复后仍应自动回到原生路径。
## 9. 入站下载安全与出站文件回传
### 9.1 入站产物下载安全
统一复用并泛化现有图片安全机制：
v1.4.0 的普通文件入站遵循“渠道原生下载、公共层原样落盘、Harness 决定是否读取”的职责边界：
1. 渠道适配器只提供受控下载句柄，不直接把平台 URL交给 Harness。
2. 仅允许 HTTPS 和平台白名单域名；默认拒绝重定向。
3. 同时检查声明大小和流式实际大小。
4. 对文件签名、MIME 和扩展名进行一致性检查；不信任用户文件名。
5. 文件名移除路径、控制字符和超长内容。
6. 下载受超时、AbortSignal、单文件上限和单消息总量限制。
7. 临时文件使用受控目录和随机名称，任务结束或 TTL 到期后清理。
8. 默认不把音视频上传第三方转写服务；需要时必须形成单独产品和隐私决策。
1. 渠道适配器只提供 SDK/API 下载结果或受控下载句柄，不把平台 URL 直接交给 Harness。
2. 通用 URL 下载器只接受 HTTPS 和明确的渠道文件 Host，并阻止未校验重定向；必须跟随临时地址的渠道在自身适配器中验证并测试该流程。
3. 公共层保留渠道返回的原始字节、文件顺序和显示文件名；存储名称移除路径和控制字符，确保不能逃出当前 Session 工作区。
4. 文件写入当前 Session 的 `.dsh-im/inbound/turn-*` 目录，目录和文件分别使用 `0700`、`0600`；下载失败清理整个未完成批次，Turn 得到确定终态后清理本批文件。
5. 下载和写入服从当前 Turn 的 `AbortSignal`，但插件不另设文件类型、扩展名、MIME、签名、大小、数量、TTL 或独立下载超时准入规则，也不解析、转码、摘要或解压文件。
6. 默认不把音视频上传第三方转写服务；需要时必须形成单独产品和隐私决策。
本节只适用于“从渠道服务器下载用户输入到本机”的入站边界。HTTPS、域名白名单、重定向、声明/实际大小、MIME/签名/扩展名、文件名、下载超时和临时文件 TTL 都是入站下载规则，**不得用来限制 `dsh_im_return_file` 回传的本地文件**。
这些规则只保证下载来源、工作区路径和生命周期正确，不判断文件内容是否“适合大模型”。Harness 负责决定是否读取和如何处理；渠道自身的格式、大小、权限、配额和时效限制由对应平台 API 决定。本节同样不得用来限制 `dsh_im_return_file` 回传的本地文件。
### 9.2 出站工具与路由
@ -646,8 +653,9 @@ interface ChannelAdapter {
- Slack Thread、Telegram Topic、Discord Thread/Channel 和飞书回复链必须映射到稳定 `threadId`。
- 平台没有 Thread 时保持聊天级 Session，不创造伪线程。
- Discord 父频道消息创建 Thread 的动作必须发生在 Session 查找之前；Discord 官方接口使创建后的 Thread ID 与源消息 ID 相同，应利用这一性质收敛 Gateway 重放和并发创建。
- 对 Discord DM 和已在 Thread 中的消息不执行新建动作；新建 Thread 不继承父频道历史 Session，创建或发送失败则整体回到当前父频道路径，不保留半绑定状态。
- 会话键迁移时保留旧绑定读取兼容：优先查新键，未命中且无 `threadId` 时读取旧键并原子迁移。
- 对 Discord DM 和已在 Thread 中的消息不执行新建动作；新建 Thread 不继承父频道历史 Session。只有最终 Thread Route 建立前的确定性失败可以整体回到父频道旧路径；Route 已建立后的发送失败留在该 Route 记录交付失败，不把完整回答补发到父频道。
- 由当前机器人从父消息创建并持久识别的受管 Thread，后续普通消息、命令、图片和文件无需重复 @；无关的既有 Thread 保留当前明确 @ 门槛，不能顺带扩大服务器监听范围。
- 会话键迁移时优先查新键；DM/父频道回退路径继续兼容旧聊天键，已有 Discord Thread 还必须兼容当前 `group:<threadChannelId>` 绑定并原子迁移。新建 Thread 不得回读父频道旧 Session。
- 对飞书等当前按群 Chat ID 绑定的渠道，带 `root_id` 的新消息启用新键后，不自动把整个群旧 Session 复制到所有话题。
### 10.3 并发与所有权
@ -727,10 +735,10 @@ interface ChannelAdapter {
### 12.2 普通文件输入
- v1 优先支持文本、代码、PDF、常见办公文档和压缩包的安全传递，不承诺 Harness 一定能理解所有格式。
- 渠道负责下载，公共层负责安全注册，Harness 负责决定是否读取。
- v1.3.0 起九渠道均已支持普通文件输入：渠道负责原生下载，公共层将原始字节写入当前 Session 的 `.dsh-im/inbound/turn-*`，再通过中性文件清单把相对路径交给 Harness。
- 插件不解析、转码、摘要或判断文件类型，不承诺 Harness 一定能理解某种格式；Harness 负责决定是否读取和如何处理。
- UI 文案区分“机器人成功接收文件”和“Harness 已成功解析文件”。
- 多文件消息保持顺序和文件名，不把每个附件拆成独立 Session Turn。
- 多文件消息保持顺序和文件名并进入同一个 Session Turn，不拆成多个 Prompt，也不增加插件级类型、大小或数量限制。
### 12.3 富文本输入
@ -767,19 +775,19 @@ thinking → tool-running* → answer-updating* → completed | stopped | failed
## 14. 当前九渠道能力基线
下表保留 1.0.2 的行为基线，并移除 PR 链 1 已补齐的出站结果文件缺口；九渠道当前结果文件发送路径及限制见 3.7。平台能力仍可能变化，表中“文字”表示 Harness 交互目前依赖现有安全文字状态机，不表示功能缺失。
下表以 `v1.4.0@1d7f6a5` 为当前发布行为基线。九渠道均已具备普通文件输入和结果文件原生回传；具体发送路径及平台限制见 3.7，入站职责边界见 9.1 和 12.2。平台能力仍可能变化，表中“文字”表示 Harness 交互目前依赖现有安全文字状态机，不表示功能缺失。
| 渠道 | 当前输入基线 | 会话与路由基线 | 当前原生/专属呈现 | Harness 交互 | 剩余重点 |
| --- | --- | --- | --- | --- | --- |
| 飞书 | 文字、图片、Post 图文；群聊支持仅提及或经授权接收全部消息 | 私聊/群聊隔离；回复链用于待处理问题关联，尚未形成统一 Thread Session 语义 | CardKit 流式、Reaction；原生菜单、Session/Workspace 卡片、Watch 完成推送、归档筛选、回调与群权限修复 | 问题/审批文字闭环；管理卡片按钮已可用，但 Harness 问题尚未原生化 | 引用/回复链语义；Harness 原生选择；语音 |
| 微信 | 文字、图片、平台语音识别文本；账号所有者隔离 | 账号/聊天级 Session；`ref_msg` 尚未进入 Prompt | 最终文字；协议能力受腾讯 iLink 限制 | 文字闭环 | 引用；typing；普通文件输入 |
| 钉钉 | 文字、Picture、RichText 图文 | 私聊/群聊隔离 | AI Card 流式与失败恢复 | 文字闭环 | 平台 `recognition` 恢复；卡片回调；普通文件输入 |
| 企业微信 | 文字、图片、Mixed、平台语音识别文本 | 私聊/群聊隔离；`quote` 尚未进入 Prompt | 原生思考/工具进度和 Markdown 流式 | 文字闭环 | 引用；模板卡片单/多选；普通文件输入 |
| QQ | 文字、图片；群聊要求 @ | C2C/群聊隔离 | C2C typing 与流式 | 文字闭环；SDK `interaction` 尚未接入 | Keyboard；Markdown；引用 |
| Slack | 文字、图片；私聊或 App Mention | Channel + `thread_ts` 已隔离 | 官方流式 API，失败时文字恢复 | 文字闭环；Block Kit 交互尚未接入 | 富 Blocks；原生选择；结构化引用 |
| Telegram | 文字、图片；兼容模式或机器人级私聊白名单安全模式 | Chat + Topic `message_thread_id` 已隔离 | 编辑消息流；原生命令菜单 | 文字闭环；Callback Query 尚未接入 | #28 Rich Message；Inline Keyboard；引用与普通媒体输入 |
| Discord | 文字、图片；私聊或服务器频道 @ | 已有 Thread Channel 按其 `channel_id` 隔离；父频道 @ 仍共享父 Channel Session | 原生 Markdown + 编辑消息流 | 文字闭环；Components 尚未接入 | #27 自动创建 Thread；Components；引用与 Voice |
| WhatsApp | 文字、图片；群聊 @/回复；支持账号自聊 | JID 级 Session；引用外观保留但引用内容未进入 Prompt | 已读、typing、最终文字 | 文字闭环；Poll 更新未聚合 | Poll 收发闭环；引用、语音、格式转换 |
| 飞书 | 文字、图片、普通文件、Post 图文；群聊支持仅提及或经授权接收全部消息 | 私聊/群聊隔离；回复链用于待处理问题关联，尚未形成统一 Thread Session 语义 | CardKit 流式、Reaction；原生菜单、Session/Workspace 卡片、Watch 完成推送、归档筛选、回调与群权限修复 | 问题/审批文字闭环；管理卡片按钮已可用，但 Harness 问题尚未原生化 | 引用/回复链语义；Harness 原生选择；语音 |
| 微信 | 文字、图片、普通文件、平台语音识别文本；账号所有者隔离 | 账号/聊天级 Session；`ref_msg` 尚未进入 Prompt | 最终文字；协议能力受腾讯 iLink 限制 | 文字闭环 | 引用；typing |
| 钉钉 | 文字、Picture、RichText 图文、普通文件 | 私聊/群聊隔离 | AI Card 流式与失败恢复 | 文字闭环 | 平台 `recognition` 恢复；卡片回调 |
| 企业微信 | 文字、图片、普通文件、Mixed、平台语音识别文本 | 私聊/群聊隔离；`quote` 尚未进入 Prompt | 原生思考/工具进度和 Markdown 流式 | 文字闭环 | 引用；模板卡片单/多选 |
| QQ | 文字、图片、普通文件；群聊要求 @ | C2C/群聊隔离 | C2C typing；Markdown 与按渠道收敛的 Turn Feed | 文字闭环；SDK `interaction` 尚未接入 | Keyboard；引用 |
| Slack | 文字、图片、普通文件；私聊或 App Mention | Channel + `thread_ts` 已隔离 | 官方流式 API，失败时文字恢复 | 文字闭环；Block Kit 交互尚未接入 | 富 Blocks；原生选择；结构化引用 |
| Telegram | 文字、图片、普通文件；兼容模式或机器人级私聊白名单安全模式 | Chat + Topic `message_thread_id` 已隔离 | 编辑消息流；原生命令菜单 | 文字闭环；Callback Query 尚未接入 | #28 Rich Message；Inline Keyboard；引用与语音/视频输入 |
| Discord | 文字、图片、普通文件；私聊或服务器频道 @ | 已有 Thread Channel 按其 `channel_id` 隔离；父频道 @ 仍共享父 Channel Session | 原生 Markdown + 编辑消息流 | 文字闭环；Components 尚未接入 | #27 自动创建 Thread；Components；引用与 Voice |
| WhatsApp | 文字、图片、普通文件；群聊 @/回复；支持账号自聊 | JID 级 Session；引用外观保留但引用内容未进入 Prompt | 已读、typing、最终文字 | 文字闭环；Poll 更新未聚合 | Poll 收发闭环；引用、语音、格式转换 |
AI Office Connector 另行维护设备、Job、租约和 SSE 路由，不进入上述 IM 会话矩阵。所有公共问题/审批、进度和未来产物类型的改动，都必须执行 Office 回归，避免聊天渠道优化破坏远程 Office 任务。
@ -799,12 +807,12 @@ AI Office Connector 另行维护设备、Job、租约和 SSE 路由，不进入
| 优先级 | 用户价值 | 当前能力 |
| --- | --- | --- |
| P0：正确性与任务闭环 | 缺失会造成上下文串线，或用户无法取回任务结果 | #16 结果文件回传；#27 Discord 独立 Thread 会话；引用内容准确性 |
| P1：结果可用与显著降本 | 任务勉强可完成，但阅读、选择或输入成本明显过高 | #28 Telegram Rich Message；原生审批/选择；平台已有语音识别结果接入；普通文件输入 |
| P0：正确性与任务闭环 | 缺失会造成上下文串线，或用户无法取回任务结果 | #16 结果文件回传（已发布）；#27 Discord 独立 Thread 会话（待实现）；引用内容准确性 |
| P1：结果可用与显著降本 | 任务勉强可完成，但阅读、选择或输入成本明显过高 | #28 Telegram Rich Message（待实现）；原生审批/选择；平台已有语音识别结果接入 |
| P2：渠道体验完善 | 核心任务可完成，继续恢复或强化渠道专属体验 | 其他渠道 Markdown/代码块、输入状态、结构化进度、引用外观 |
| P3：暂不建设 | 与 Harness 核心任务关系弱，收益尚未成立 | 贴纸、位置、联系人、通用投票等 |
优先级评审记录判断依据和用户后果，不使用缺乏可靠数据支撑的伪精确分数。真实 Issue 是需求证据：#16 已有明确用户场景和优先交付承诺，因此先做飞书闭环；#27 的会话正确性高于 #28 的显示体验。#16 与 #27 都属于 P0，但拆成独立切片，避免同时改动交付和路由两条主链路。
优先级评审记录判断依据和用户后果，不使用缺乏可靠数据支撑的伪精确分数。真实 Issue 是需求证据：#16 已按明确用户场景完成并发布；接下来 #27 的会话正确性高于 #28 的显示体验，因此推荐先完成 PR 链 2，再独立推进 PR 链 3。两者不是技术依赖，仍保持独立切片和发布节奏。
### 15.2 用渠道适配性选择标杆渠道
@ -840,17 +848,18 @@ AI Office Connector 另行维护设备、Job、租约和 SSE 路由，不进入
## 16. 分阶段实施路线
### 切片 0：1.0.2 基线门禁
### 切片 0：v1.4.0 基线门禁（2026-08-24 已刷新）
目标：为前三个 Issue 建立足够的回归证据，不把“建立完整新架构”变成长周期前置项目。
目标：以当前已发布产品为 PR 链 2、3 建立足够的回归证据，不把“建立完整新架构”变成长周期前置项目，也不重复实施已经发布的文件能力。
- 固定当前 `npm run check` 结果和发布包校验为全局门禁。
- 分别为 Discord 路由、出站文件、Telegram 输出建立受影响行为表；只为这三个范围补缺失的 Fixture/特征测试。
- 保存当前 Discord DM、父频道 @、已有 Thread、Telegram 私聊/群聊/Topic/编辑流，以及九渠道图片/命令/交互的基线用例。
- 固定 `@xmanrui/dsh-im@1.4.0`、`main@1d7f6a5` 为本轮代码基线；2026-08-24 实跑 `npm run check` 为 1036/1036，通过构建和发布包校验。
- 当前渠道定向测试为 Discord 14/14、Telegram 30/30；这些数字只证明现有测试通过，不代表 Thread 或 Rich Message 已实现。
- 按 18.6 锁定 Discord DM/父频道 @/已有 Thread 和 Telegram 私聊/群聊/Topic/普通编辑流的已有证据，先补现有行为缺失的 Fixture，再写新能力。
- 九渠道文字、图片、普通文件输入、结果文件回传、全部命令、问题审批和 AI Office 均作为不可降低的发布基线。
- 新语义对象先包裹现有参数；不移动 Bridge，不改变当前凭据、配置或 Session 文件。
- 对扫码、Discord Thread、Telegram Rich Message 和各渠道附件建立真机记录模板。
- Discord Thread 和 Telegram Rich Message 分别建立真机记录，不能用一个渠道或一次桌面测试替代。
完成标准：三个切片都有“保留/改善/新增”清单和回滚路径；`npm run check` 通过。切片 0 应与 #16 的首个测试提交一起完成，不单独形成长期项目。
完成标准：18.6 的当前证据均可重复运行，标为“实施前必须补”的测试已经进入对应 PR 链的第一个提交；每条链都有“保留/改善/新增”清单和回滚路径。基线刷新不是独立架构项目，不能阻塞小步实施。
### 切片 1：#16 结果文件回传（九渠道发送与本机验收已完成）
@ -872,13 +881,13 @@ AI Office Connector 另行维护设备、Job、租约和 SSE 路由，不进入
- 文字先发、文件后发或分条发送都必须共享一个交付回执；上传成功但消息发送失败时不能宣称用户已收到。
- 文件回传对所有已连接机器人默认可用，无项目、机器人或请求开关；不变更飞书 CardKit/文字回复、菜单、Watch、Session/Workspace 卡片和群权限逻辑。
**必须保留**：九渠道现有文字/图片输入，飞书 CardKit 流、Reaction、菜单、Watch、Session/Workspace 卡片、群权限与回调修复，全部命令和问题/审批状态机。普通文件入站不捆绑进 #16。
**必须保留**：九渠道现有文字、图片、普通文件输入和结果文件回传，飞书 CardKit 流、Reaction、菜单、Watch、Session/Workspace 卡片、群权限与回调修复，全部命令和问题/审批状态机。普通文件入站不属于 #16，但已经是发布基线。
完成标准：全局工具从首个 IM Turn 可用；现有/新建文件、绝对/相对路径、可读普通文件校验、Session/Turn 路由、快照完整性、平台权限/格式/大小/配额真实错误映射、部分失败、取消和重复重试均有自动化覆盖；九渠道各选一个机器人完成原生附件和既有能力回归验收。不以敏感内容、工作区边界、符号链接、格式、大小、数量、TTL 或独立读取超时的本地拒绝用例作为 DoD；只有完成对应渠道证据后，才对外声明该渠道可用。
### 切片 2：#27 Discord 会话落点与原生 Thread
目标：服务器文字频道中一次 @ 创建一个独立的公开 Thread，本次及后续对话绑定到 Thread Session；DM 和已有 Thread 行为不变。
目标：服务器文字频道中一次 @ 创建一个独立的公开 Thread，本次及后续对话绑定到 Thread Session；DM 和无关既有 Thread 的当前寻址规则不变，由本机器人创建的受管 Thread 内后续消息无需重复 @。
**最小横向建设**：
@ -888,13 +897,13 @@ AI Office Connector 另行维护设备、Job、租约和 SSE 路由，不进入
**Discord 纵向实现**：
- 在被提及的 Guild 消息上查询 Channel 类型；已有 Public/Private/Announcement Thread 直接沿用，不嵌套创建。
- 通过官方“Start Thread from Message”路由从原始消息创建 Public Thread，并把 `conversationId`、回复目标、typing 和编辑流切换到 Thread ID。
- 在被提及的 Guild 消息上查询 Channel 类型；`GUILD_TEXT` 从原消息创建 Public Thread，`GUILD_ANNOUNCEMENT` 创建 Announcement Thread，已有 Public/Private/Announcement Thread 直接沿用，不嵌套创建；Forum、Media 和其他不支持该接口的类型保持当前路由并明确说明。
- 通过官方“Start Thread from Message”路由创建与父频道类型匹配的 Thread，并把 `conversationId`、回复目标、typing 和编辑流切换到 Thread ID。
- 利用“Thread ID 与源 Message ID 相同，一条消息只能创建一个 Thread”的平台契约实现幂等；Gateway 重放、并发处理和进程内重试不得触发第二个 Turn。
- 检测 `CREATE_PUBLIC_THREADS`、`SEND_MESSAGES_IN_THREADS` 等实际权限；403、限流、线程上限或 API 故障时继续使用当前父频道路径，并给出一次明确提示。
- 在最终 Route 建立前检测创建对应 Thread 和可预判的发送权限；403、429 经平台退避仍失败、线程上限或不支持的频道类型等确定性创建失败继续使用当前父频道路径，并给出一次明确提示。创建请求超时、断线、5xx 或调用后取消必须先按源 Message ID 查询 Thread 是否已创建，再决定进入 Thread 或回退。已有/新建 Thread Route 一旦确定，归档、锁定、发送权限或消息发送失败都不得把完整回答发到父频道；只记录该 Route 的交付失败，必要时在确认安全的父消息下发送不含任务内容的通用提示。
- 不增加机器人级、请求级或用户可见配置项；用小提交完成路由语义、Discord 动作和回退路径，通过自动化与真实 Discord 客户端后随版本生效，异常时回滚上一发布版本。
**必须保留**：DM、已有 Thread、图片、全部命令、问题/审批快车道、流式编辑、多机器人与工作区/Session 隔离。
**必须保留**：DM、无关既有 Thread 的 @ 门槛、文字、图片、普通文件、结果文件、全部命令、问题/审批快车道、流式编辑、多机器人与工作区/Session 隔离。
完成标准：父频道双用户并发不再共享新 Session；Thread 内继续消息和命令命中同一 Session；重复事件、缺权限、归档/限流、无新增配置项和回滚上一发布版本均有自动化及 Discord 客户端证据。
@ -905,21 +914,22 @@ AI Office Connector 另行维护设备、Job、租约和 SSE 路由，不进入
**最小横向建设**：
- 最终回答和增量更新保留 `plain | markdown` 呈现意图；不再把所有输出无条件解释为纯文本。
- Harness `assistant/chunk` 和 `assistant/message` 明确标记为 `markdown`；工具状态、错误、控制命令和插件自生成提示为 `plain`。裸旧字符串兼容入口默认 `plain`，新 Harness 回答路径必须显式携带 `markdown`，不能靠内容猜测格式。
- `DeliveryReceipt` 记录实际采用 `telegram-rich-draft`、`telegram-rich-final`、`telegram-regular` 或 `text-fallback`。
- 公共层不引入 Telegram `InputRichBlock*` 类型；Markdown 到 Rich Markdown/Block 的转换留在 Telegram 边界。
**Telegram 纵向实现**：
- `sendRichMessageDraft` 只用于私聊，同一非零 `draft_id` 更新 30 秒临时预览；Turn 完成时必须调用 `sendRichMessage` 持久化唯一最终消息。
- `sendRichMessage` 支持私聊、超级群/频道及 `message_thread_id`；群聊和 Topic 不调用只限私聊的 Draft，流程中保留当前 `sendMessage/editMessageText` 反馈，最终发送 Rich Message。
- 需要原位更新时验证 `editMessageText` 的 `rich_message` 参数；无论选择最终发送还是编辑，都只能留下一个权威结果。
- `sendRichMessage` 支持私聊、超级群/频道及 `message_thread_id`；私聊 Draft 没有持久占位时用它发送最终结果。群聊和 Topic 不调用 Draft：已有持久占位时必须通过 `editMessageText.rich_message` 原位收敛，只有未创建持久占位时才调用 `sendRichMessage`。
- 若 `editMessageText.rich_message` 被平台明确拒绝，同一占位消息按 Telegram HTML → 纯文本继续原位编辑，不另发第二份最终消息；所有路径保留原始 `reply_parameters`/Topic 归属，不留下永久“处理中”。
- 转换器覆盖代码围栏、列表、表格、链接、Unicode 和超长内容；不把未经处理的任意 HTML 直接交给 Telegram。
- 降级顺序固定为 Rich Message → 普通 Markdown/HTML Message → 当前纯文本；任一级失败都不能重复 Prompt 或留下永久“处理中”。
- 确定性降级顺序固定为 Rich Message → Telegram HTML Message → 当前纯文本；转换失败、能力不支持或确定性 API 拒绝才能进入下一层。最终发送在调用后出现超时、断线、5xx 或取消时记录不确定回执，不再补发另一份最终消息。
- 不增加机器人级、请求级或用户可见配置项；用小提交分离呈现语义、Telegram 转换与 API 适配，自动化和真实客户端验收通过后随版本生效，异常时回滚上一发布版本。
**必须保留**：兼容/安全访问模式、私聊白名单、群聊提及/回复、Topic Session、命令菜单、图片输入、长消息拆分、编辑流失败恢复和全部控制命令。
**必须保留**：兼容/安全访问模式、私聊白名单、群聊提及/回复、Topic Session、命令菜单、图片和普通文件输入、结果文件回传、长消息拆分、编辑流失败恢复、问题审批和全部控制命令。
完成标准：官方客户端完成私聊、群聊和 Topic 真机验证；Rich API 不可用、语法转换失败、超长回答、停止 Turn 和网络重试均能落入安全降级；不新增配置项，上一发布版本可安全读取状态并恢复当前 `sendMessage/editMessageText` 路径。
完成标准：官方客户端完成私聊、群聊和 Topic 真机验证；Rich API 明确不可用、语法转换失败和超长回答能进入确定性降级，停止 Turn 与网络不确定结果能收敛为唯一终态且不重复发送；不新增配置项，上一发布版本可安全读取状态并恢复当前 `sendMessage/editMessageText` 路径。
### 后续切片 4：原生审批与选择
@ -927,15 +937,15 @@ AI Office Connector 另行维护设备、Job、租约和 SSE 路由，不进入
- 完成 11.2 的九渠道十八条单选/多选证据记录，再选择标杆渠道接入原生控件。
- 原生、组合与文字路径共享一份状态；危险审批不得使用可修改、公开或无法确认 Actor 的投票控件。
### 后续切片 5：引用、普通文件与语音输入
### 后续切片 5：引用与语音输入（普通文件已交付）
- 实现 `ReplyReference`，先处理事件已携带完整快照的渠道；继续完善 Slack/Telegram/Discord Thread 契约和飞书回复链 Session 语义。
- 普通文件输入复用 `InboundArtifact`，明确“已接收”和“Harness 已解析”的区别。
- 九渠道普通文件输入继续作为回归基线，明确“已接收”和“Harness 已解析”的区别；本切片不重新设计文件准入或处理逻辑。
- 先恢复钉钉现成 `recognition`；企业微信和微信现有语音文本迁移后必须等价或更完整，其他渠道按实际需求决定本地转写。
### 后续切片 6：其他渠道富呈现与消息生命周期
- 基于 #28 验证后的呈现意图继续补 QQ Markdown、WhatsApp 格式、微信 typing 和其他高价值渠道方言。
- 基于 #28 验证后的呈现意图继续补 WhatsApp 格式、微信 typing 和其他高价值渠道方言；QQ v1.4.0 已有 Markdown/Turn Feed 只能保留或改善，不能重新降级。
- 消息仍在队列且 Turn 未开始时，编辑可替换、撤回可取消；Turn 已开始后不自动改变已授权任务。
- Reaction 只作为明确反馈或取消手势时接入，不把任意 Emoji 当命令。
- 后续切片不能降低飞书/钉钉/企业微信/QQ/Slack/Telegram/Discord 已有流式、卡片、编辑或 typing 体验。
@ -985,16 +995,18 @@ flowchart TD
- 典型平台事件能转换成正确语义。
- 未支持事件不会静默丢弃。
- 能力快照与实际调用路径一致。
- 原生发送失败会按规则降级，不会重复回复。
- 原生发送确定性失败会按规则降级；调用后结果不确定时查询或记录 `unknown`，不会为了降级重复回复。
- 渠道原生动作重复执行必须幂等；Discord Gateway 重放不能创建第二个 Thread。
- Telegram Rich Message 失败只能沿固定顺序降级，并保持一个权威最终消息。
- Telegram Rich Message 的确定性失败只能沿固定顺序降级；调用后不确定结果不得补发，并保持一个权威最终消息状态。
- 文件上传成功但发送失败、发送成功但本地超时等不确定结果必须通过回执和幂等键收敛。
- 平台格式、大小、权限、配额和限流错误来自真实 API 调用，并转成稳定原因码；出站适配器不在调用前以插件上限代替平台判定。
- 原始 Token、URL 查询参数和敏感 payload 不进入日志。
### 18.3 安全与完整性测试
- **入站下载**：SSRF、非 HTTPS、重定向、白名单绕过、DNS/Host 混淆、声明长度与流式长度不一致、MIME/扩展名/文件签名不一致、下载超时和临时文件清理，均按 9.1 验证。
- **入站来源与路径**：通用 URL 下载器拒绝非 HTTPS、非渠道 Host 和未校验重定向；SDK/API 型渠道按适配器契约测试临时地址与鉴权，平台 URL 不进入 Harness。
- **入站字节与生命周期**：零字节、Buffer、异步流和多文件顺序均保持原始字节；显示文件名不能逃出工作区，单文件失败清理整个未完成批次，Turn 终态和取消遵循当前 Session 生命周期。
- **入站无额外准入**：契约测试锁定不因扩展名、MIME、签名、声明大小、实际大小、文件数量、TTL 或插件独立下载超时而本地拒绝；插件不解析、转码、摘要或自动解压文件。
- **出站本地契约**：现有文件与新建文件、工作区内外普通文件、绝对与相对路径、解析到普通文件的符号链接均可快照；不存在、不可读、目录和其他非普通文件明确失败。
- **出站无额外准入**：契约测试锁定不因来源、创建时间、工作区边界、符号链接、敏感内容、扩展名/MIME、大小、数量、TTL 或插件独立读取超时而本地拒绝；测试替身的平台拒绝仍需映射真实错误。
- **出站路由与快照**：快照建立后修改/删除原文件不改变交付字节；快照被替换或损坏必须失败；跨 Session/Turn 取件、失败工具结果、取消后交付和重复附件发送不得发生。
@ -1037,6 +1049,79 @@ flowchart TD
| --- | --- | --- | --- | --- | --- | --- | --- |
| 例：DELIVERY-STREAM-FEISHU | 飞书 | CardKit 原生流式并有单一最终状态 | 保留 | 接入统一进度语义，流式体验不降低 | 测试文件与用例名 | 客户端清单编号 | 回滚上一发布版本，恢复已发布流式实现 |
### 18.6 PR 链 2、3 当前测试基线与待补清单（2026-08-24）
本节记录 `v1.4.0@1d7f6a5` 的实际证据，不把“平台 API 存在”或“共享测试大致覆盖”写成项目已经支持。2026-08-24 实跑结果：`npm run check` 1036/1036、Discord 渠道目录 14/14、Telegram 渠道目录 30/30，构建和发布包校验均通过。PR 链 2 的 `ConversationRoute`、Discord 查询/创建 Thread，以及 PR 链 3 的 `DeliveryBlock`、Telegram Rich API 和转换器均尚未实现。
#### PR 链 2：Discord Thread
当前可复用的基线证据：
| 基线 ID | 必须保留的 v1.4.0 行为 | 当前自动化证据 | 覆盖结论 |
| --- | --- | --- | --- |
| D2-BASE-01 | DM 自动寻址；Guild 消息只有明确 @ 才进入 Harness | `test/channels/discord/discord.test.mjs`：`Discord normalizes DMs and only addressed server messages` | 已覆盖 DM、父频道 @ 和未 @ 忽略；未区分 Thread 类型 |
| D2-BASE-02 | 图片与普通文件分类、渠道文件下载 | `test/channels/discord/discord.test.mjs`：`Discord keeps image attachments in images and exposes ordinary attachments as files` | 已覆盖 |
| D2-BASE-03 | Gateway v10 建连、事件派发错误隔离和停止 | `test/channels/discord/discord.test.mjs`：`Discord runtime identifies on Gateway v10 and becomes ready` | 基础覆盖；没有 Thread 重放/并发 |
| D2-BASE-04 | 普通文字、长消息分片、编辑流和消息 ID 回执 | `test/channels/shared/delivery-message-ids.test.mjs` 的普通/流式 Discord 用例 | 共享路径已覆盖；未断言 Thread 目标 |
| D2-BASE-05 | `/compact`、模型、Preset、`/stop`、问题审批、Actor/会话隔离与重放去重 | `test/channels/shared/text-harness-bridge.test.mjs` 的命令、停止和交互用例 | 共享状态机已覆盖；全部命令和 Thread 路由仍需显式 Fixture |
| D2-BASE-06 | 结果文件作为原生 Attachment 发送并保留回复关系 | `test/channels/discord/discord.test.mjs`：`Discord API uploads a result file as a native attachment and preserves the reply` | 已覆盖父目标；未断言自动创建 Thread 后的目标 |
| D2-BASE-07 | 普通文件入站没有机器人/项目/请求 Gate，也没有类型、大小、数量、TTL 或独立下载超时准入；结果文件无 Gate，配置/RPC 不暴露凭据 | `test/inbound-file.test.mjs`、`test/channels/discord/production.test.mjs`、Discord Controller/RPC 用例 | 公共无额外准入和出站装配已覆盖；Discord 入站装配仍需显式锁定 |
PR 链 2 第一个提交必须先补齐以下测试，之后才实现 Thread：
- [ ] `D2-PRE-01`：分别锁定 DM、父文字频道 @、未 @、已有 Public/Private/Announcement Thread 的当前事件 Fixture；明确无关既有 Thread 保留 @ 门槛。
- [ ] `D2-PRE-02`：用两个用户在同一父频道复现当前共享 `group:<channelId>` Session 键，作为 #27 修复前的失败特征。
- [ ] `D2-PRE-03`：锁定文字、图片、普通文件、file-only、结果文件、typing、长消息余段和编辑流的当前发送目标。
- [ ] `D2-PRE-04`：用数据驱动覆盖全部控制命令，以及问题、审批、`/stop`、`/steer`、多机器人、Workspace 和 Session 隔离，避免只以少数共享用例代替 Discord 证据。
- [ ] `D2-PRE-05`：锁定 Discord 普通文件接收不依赖机器人、项目或请求配置，不以扩展名、MIME、声明/实际大小、数量、TTL 或插件独立下载超时拒绝。
PR 链 2 的新增能力测试：
- [ ] `D2-ROUTE-01`：`ConversationRoute` 对 DM、父频道、已有 Thread、新建 Thread 生成稳定且互不冲突的键；新 Thread 不继承父 Session。
- [ ] `D2-ROUTE-02`：DM/父频道兼容旧聊天键；已有 Thread 兼容当前 `group:<threadChannelId>` 并原子迁移；并发迁移只保留一个 Session。
- [ ] `D2-API-01`：锁定 Channel 类型矩阵：`GUILD_TEXT → PUBLIC_THREAD`、`GUILD_ANNOUNCEMENT → ANNOUNCEMENT_THREAD`、Public/Private/Announcement Thread 直接沿用、Forum/Media/其他不调用 Start Thread from Message；覆盖请求、返回、限流与错误映射。
- [ ] `D2-IDEMP-01`：相同 Gateway 事件的并发、重放和重启恢复只创建一个 Thread、执行一个 Turn、产生一个最终回复；受管 Thread 的持久识别不只依赖进程内状态。
- [ ] `D2-TARGET-01`：创建成功后 `sendText`、typing、编辑/余段、图片、普通文件、结果文件及问题审批全部落到 Thread。
- [ ] `D2-MANAGED-01`：受管 Thread 内后续普通消息、命令、图片和文件无需再次 @，仍命中同一 Session；无关 Thread 不被放开。
- [ ] `D2-FALLBACK-01`：最终 Route 建立前的 403、429 经平台退避仍失败、线程上限和不支持类型等确定性创建失败才回父频道旧路径；创建超时、断线、5xx 和调用后 Abort 先按源 Message ID 查询并收敛，调用前 Abort 不发送。
- [ ] `D2-DELIVERY-01`：已有/新建 Thread Route 确定后的归档、锁定、发送权限、网络或消息发送失败留在该 Route 记录失败，不重跑 Prompt、不把完整回答发到父频道；所有路径只产生一个安全提示且不留半绑定。
- [ ] `D2-COMPAT-01`：没有新增项目/机器人/请求配置项；v1.4.0 状态可升级读取，上一发布版本可安全忽略新增状态。
- [ ] `D2-LIVE-01`：真实 Discord 客户端覆盖 DM、父频道、受管 Thread 后续消息、已有三类 Thread、两用户并发、重放/重启、缺权限以及完整文字/文件/命令/交互链路。
#### PR 链 3：Telegram Rich Message
当前可复用的基线证据：
| 基线 ID | 必须保留的 v1.4.0 行为 | 当前自动化证据 | 覆盖结论 |
| --- | --- | --- | --- |
| T3-BASE-01 | 私聊、群聊提及和 Topic `message_thread_id` Session 隔离 | `test/channels/telegram/telegram.test.mjs`：`Telegram normalizes private messages and requires an explicit group address` | 已覆盖入站路由；未完整断言所有出站调用目标 |
| T3-BASE-02 | 兼容模式、私聊白名单及运行时执行 | Telegram access policy、allowlist runtime 用例 | 已覆盖 |
| T3-BASE-03 | 命令菜单注册，菜单失败不阻塞连接 | Telegram command menu、runtime startup 用例 | 已覆盖 |
| T3-BASE-04 | 图片、图片文档和普通文件输入 | `Telegram keeps native photos and image documents as images and exposes ordinary documents as files` | 已覆盖 |
| T3-BASE-05 | 当前 `sendMessage/editMessageText` 编辑流和普通文字恢复 | `Telegram bridge ignores unaddressed groups and streams direct replies`、共享消息 ID 用例 | 基础覆盖；失败恢复和完整 API Payload 不足 |
| T3-BASE-06 | 轮询在 Harness 问题等待期间继续，答案走交互快车道 | `Telegram runtime keeps polling while a Harness question waits for its answer` | 已覆盖 |
| T3-BASE-07 | 结果文件保持 Topic 和回复链，流完成后再发送文件 | Telegram `sendDocument` 用例、共享文字 Bridge 产物用例 | 已覆盖普通路径；Rich 混合回复待补 |
| T3-BASE-08 | 普通文件入站没有机器人/项目/请求 Gate，也没有类型、大小、数量、TTL 或独立下载超时准入；结果文件无 Gate，旧配置和凭据投影兼容 | `test/inbound-file.test.mjs`、`test/channels/telegram/production.test.mjs`、Controller/RPC 用例 | 公共无额外准入和出站装配已覆盖；Telegram 入站装配仍需显式锁定 |
PR 链 3 第一个提交必须先补齐以下测试，之后才实现 Rich Message：
- [ ] `T3-PRE-01`：直接锁定 `sendMessage/editMessageText` 在私聊、群聊、Topic 中的 `reply_parameters`、`message_thread_id`、禁用链接预览和当前无 `parse_mode` 的 Payload。
- [ ] `T3-PRE-02`：锁定 4000/4001 边界、只有首段引用、所有余段留在同一 Topic，以及中文、Emoji、代码围栏和长链接不丢字符。
- [ ] `T3-PRE-03`：补齐占位创建失败、中途编辑失败、最终编辑失败、余段失败、网络取消和 `/stop`；每条路径只运行一次 Prompt、只有一个权威终态且不永久残留“处理中”。
- [ ] `T3-PRE-04`：锁定当前文字先完成、结果文件后发送及统一回执，并覆盖全部命令、问题审批、图片/普通文件和两种访问模式。
- [ ] `T3-PRE-05`：锁定 Telegram 普通文件接收不依赖机器人、项目或请求配置，不以扩展名、MIME、声明/实际大小、数量、TTL 或插件独立下载超时拒绝。
PR 链 3 的新增能力测试：
- [ ] `T3-SEM-01`：`DeliveryBlock` 校验并冻结 `plain | markdown`；Harness assistant 增量/最终明确为 `markdown`，工具状态、错误、命令和插件提示为 `plain`，裸旧字符串默认 `plain`；其他八渠道零行为变化。
- [ ] `T3-RECEIPT-01`：回执准确记录 `telegram-rich-draft`、`telegram-rich-final`、`telegram-regular` 或 `text-fallback`；用向后兼容的可选 `deliveryOutcome` 表达最终文字的 `sent | failed | unknown`，并保留全部消息 ID 和结果文件状态。
- [ ] `T3-CONVERT-01`：转换器覆盖标题、列表、嵌套列表、围栏代码、表格、公式、链接、中文/Unicode/Emoji 和超长边界；不透传任意 HTML，转换失败仍保留可读原文。
- [ ] `T3-API-01`：私聊用稳定非零 `draft_id` 更新同一 Draft 并最终持久化；群聊/Topic 不调用 Draft，有持久占位时通过 `editMessageText.rich_message` 原位完成，无占位时才 `sendRichMessage`；全程保留正确聊天、引用和 `message_thread_id`。
- [ ] `T3-FALLBACK-01`：Rich → Telegram HTML → 纯文本三级降级覆盖转换异常及确定性 400/403/429；有持久占位时始终原位编辑，无占位才发送一次最终消息；超时、断线、5xx 和调用后 Abort 记录 `unknown` 且不补发，调用前 Abort 不发送；全程不重复 Prompt、不残留“处理中”、不双最终消息。
- [ ] `T3-MIXED-01`：Rich 文字与结果文件混合、file-only、停止 Turn 和最终发送失败仍保持一份权威回执，失败的富文本不吞掉已登记文件。
- [ ] `T3-COMPAT-01`：不新增项目/机器人/请求配置项；访问模式、Topic、命令菜单、图片、普通文件、问题审批和旧状态全量回归，上一发布版本可安全回滚。
- [ ] `T3-LIVE-01`：真实 Telegram 客户端覆盖私聊 Draft→Final、超级群、Topic、长代码/表格/公式/链接、三级降级、弱网/停止以及入站/结果文件混合回复。
## 19. 可观测性与产品指标
### 19.1 技术指标
@ -1112,14 +1197,14 @@ flowchart TD
| 渠道逻辑重新复制核心业务 | 适配器只负责翻译和发送；Session、审批、产物和降级状态机留在公共层 |
| 平台能力或权限变化 | 使用当前机器人能力快照、真实 API 错误、契约 Fixture 和定期真机复验；不把一次平台上限固化为出站插件限制 |
| 原生交互带来安全越权 | 令牌本地映射、Actor/Route/Expiry 绑定、幂等和审计 |
| 文件能力扩大攻击面 | 入站下载严格执行 9.1；出站只接受存在、可读的普通文件，绑定 Session/Turn 并校验不可变快照完整性，格式/大小/权限交给平台 API |
| 文件能力扩大攻击面 | 入站按 9.1 约束渠道来源、工作区路径和生命周期，不替 Harness 判断内容；出站只接受存在、可读的普通文件，绑定 Session/Turn 并校验不可变快照完整性；格式、大小、权限和配额交给平台 API |
| 流式和回调导致重复回复 | 统一 DeliveryReceipt、幂等键和单一最终状态 |
| 新架构接管时丢失既有功能 | 先建立渠道行为基线；按能力拆成小提交，每步通过自动化与真机验收；基线失败即阻止合并，并保留上一发布版本回滚 |
| 为完成新能力而降低其他渠道体验 | 每个切片声明受影响范围；未纳入范围的渠道必须零行为变化，已纳入渠道只能保留、改善或新增 |
| 渠道差异被再次抹平 | 每项能力记录渠道原生机制、限制和验收证据；没有稳定原生能力时明确降级，不伪装成同等支持 |
| 路线图被易统计的数据绑架 | 不建设用户量排序遥测；依据任务后果、用户反馈、移动端验证和渠道适配性复审优先级 |
| 方案再次落后于快速迭代的代码 | 文档顶部固定包版本、基线提交和更新日期；每个切片开始前重跑能力盘点，不直接继承本文的旧判断 |
| 渠道原生动作产生半完成状态 | 创建 Thread、上传文件和发送消息都必须有幂等键与回执；只在动作成功后切换 Session/交付状态，不确定结果先查询再重试 |
| 渠道原生动作产生半完成状态 | 创建 Thread、上传文件和发送消息都必须有幂等键与回执；只在动作成功后切换 Session/交付状态；不确定结果能按稳定 ID 查询则查询收敛，无法确认则记录 `unknown` 且不得补发 |
| 新平台 API 宣传与实际客户端不一致 | Rich Message、Thread 和附件均不增加用户配置开关；以小提交、自动化、固定降级顺序、真机证据和版本回滚控制风险，文档和 UI 只宣称已验证范围 |
## 22. 每项能力的 Definition of Done
@ -1140,28 +1225,28 @@ flowchart TD
## 23. 第一批可执行工作包
### PR 链 1：#16 结果文件回传
### PR 链 1：#16 结果文件回传（已随 v1.1.0 发布）
1. **已落地——全局工具与路由**：Host 启动时默认注册 `dsh_im_return_file`，不设项目、机器人或请求开关；工具成功结果显式绑定调用时的 Session/Turn。
2. **已落地——文件快照完整性**：现有/新建文件均可；只校验存在、可读和普通文件，建立不可变快照及摘要，不增加来源、工作区、内容、类型、大小、数量、TTL 或独立读取超时准入规则。
3. **已落地——九渠道原生发送**：飞书首个闭环后，已按 3.7 扩展到其余八个渠道；格式、大小、权限、配额和限流交给平台 API 决定，适配器映射真实错误。
4. **已完成——自动化与逐渠道验收**：每渠道一个机器人完成原生附件、内容一致性、平台权限/错误提示和既有能力回归；README 已同步真实覆盖范围。
1. **已发布——全局工具与路由**：Host 启动时默认注册 `dsh_im_return_file`，不设项目、机器人或请求开关；工具成功结果显式绑定调用时的 Session/Turn。
2. **已发布——文件快照完整性**：现有/新建文件均可；只校验存在、可读和普通文件，建立不可变快照及摘要，不增加来源、工作区、内容、类型、大小、数量、TTL 或独立读取超时准入规则。
3. **已发布——九渠道原生发送**：飞书首个闭环后，已按 3.7 扩展到其余八个渠道；格式、大小、权限、配额和限流交给平台 API 决定，适配器映射真实错误。
4. **已发布——自动化与逐渠道验收**：每渠道一个机器人完成原生附件、内容一致性、平台权限/错误提示和既有能力回归；README 已同步真实覆盖范围，当前 v1.4.0 门禁继续执行回归。
### PR 链 2：#27 Discord Thread
1. **基线测试提交**：父频道 @、DM、已有 Thread、两用户并发、全部命令和编辑流。
1. **基线测试提交**：先完成 18.6 的 `D2-PRE-*`，锁定父频道 @、DM、三类已有 Thread、受管/非受管 Thread 寻址边界、两用户并发、全部命令、文件和编辑流。
2. **最小语义提交**：`ConversationRoute` 生成与旧 Discord `conversationId` 兼容测试。
3. **Discord 原生提交**：查询 Channel、按源 Message ID 幂等创建 Thread、切换回复目标和权限降级；不新增项目、机器人或请求配置项。
4. **验收提交**：自动化、Discord 客户端证据、README 行为说明和上一发布版本回滚验证；在 Issue #27 记录最终行为与限制。
### PR 链 3：#28 Telegram Rich Message
1. **基线测试提交**：当前 `sendMessage/editMessageText`、Topic、访问模式、命令菜单、图片和流式失败恢复。
1. **基线测试提交**：先完成 18.6 的 `T3-PRE-*`，锁定当前 `sendMessage/editMessageText` Payload、Topic、访问模式、命令菜单、图片/普通文件、结果文件和流式失败恢复。
2. **最小语义提交**：`DeliveryBlock(text.format)`、呈现回执和旧字符串兼容。
3. **Telegram 原生提交**：Rich Message Draft、Rich Message、转换器、唯一最终消息和三级降级；不新增项目、机器人或请求配置项。
4. **验收提交**：自动化、私聊/群聊/Topic 真机记录、README 限制和上一发布版本回滚验证；在 Issue #28 记录支持的 Rich 结构。
三个 PR 链共享同一发布门禁，但不共享发布节奏：#16 已按九渠道原生发送范围完成本机验收，提交后可独立发布；#27 与 #28 仍在各自验收后独立发布。任何 PR 都不能先合并脱离公共语义的临时渠道补丁，也不能为了公共类型整齐而改动未纳入范围的渠道。
三个 PR 链共享同一发布门禁，但不共享发布节奏：#16 已随 v1.1.0 独立发布，九渠道普通文件入站也已作为另一能力随 v1.3.0 发布；#27 与 #28 仍须分别完成基线、语义、渠道实现和真机验收后独立发布。任何 PR 都不能先合并脱离公共语义的临时渠道补丁，也不能为了公共类型整齐而改动未纳入范围的渠道。
## 24. 参考资料
@ -1192,8 +1277,14 @@ flowchart TD
- [当前依赖与检查命令](../../package.json)
- [公共 Harness 客户端](../../src/channels/shared/harness-client.mjs)
- [公共文字 Bridge](../../src/channels/shared/text-harness-bridge.mjs)
- [公共普通文件入站](../../src/channels/shared/inbound-file.mjs)
- [公共交付回执](../../src/channels/shared/semantic/delivery.mjs)
- [Discord Runtime](../../src/channels/discord/discord-runtime.mjs)
- [Telegram API](../../src/channels/telegram/telegram-api.mjs)
- [Discord 自动化基线](../../test/channels/discord/discord.test.mjs)
- [Telegram 自动化基线](../../test/channels/telegram/telegram.test.mjs)
- [共享文字 Bridge 自动化](../../test/channels/shared/text-harness-bridge.test.mjs)
- [共享消息 ID 回执自动化](../../test/channels/shared/delivery-message-ids.test.mjs)
- [飞书 Bridge](../../src/channels/feishu/bridge.mjs)
- [AI Office Job Executor](../../src/channels/office/office-job-executor.mjs)