dsh-im-ops/docs/adr/0001-semantic-core-native-channel-adapters.md

status	date	updated
accepted	2026-08-21	2026-08-23

统一语义核心与渠道原生适配

dsh-im 采用“横向建设统一语义，纵向逐个渠道打磨；按用户价值推进，按渠道特性落地”的架构与产品策略。核心层表达消息、引用、会话、交互、产物和进度等业务语义；渠道适配器依据机器人实例的实际能力进行原生呈现，不支持时执行明确降级。迁移采用增量包裹和等价接管：现有渠道行为构成最低基线，新路径可以改善体验，但不得通过删除、降级或转移既有能力来换取新能力。项目不再以 content + images + sendText 作为长期公共边界，也不为每个渠道复制 Harness 业务流程。

Considered Options

• 最低公分母模型：扩展快，但持续丢失按钮、引用、文件、语音、线程和富呈现等高价值能力。
• 每个渠道独立实现：单点体验可控，但会复制会话、审批、安全和错误处理逻辑，长期无法保持一致性。
• 按渠道用户量排序：看似容易生成开发顺序，但本地开源项目缺少可靠且必要的跨用户统计；现有使用量也无法代表尚未被满足的用户价值，容易让长尾渠道和高价值能力长期得不到验证。
• 直接替换旧桥接层：代码收敛更快，但容易同时改变命令、会话、权限、队列、流式和异常处理等已经可用的行为，且发生回归时难以定位和回滚。
• 统一语义 + 原生适配：公共业务规则只实现一次，渠道差异保留在边界内；需要维护能力矩阵和适配器契约，但最符合产品差异化目标。

Consequences

• 新能力必须先定义用户语义、降级规则和验收标准，再进入渠道 SDK 实现。
• 真实 Issue 作为能力切片的需求入口；每个 Issue 只落地其闭环所需的最小公共语义，同时完成对应渠道的原生实现、降级和验收，不先建设整套大一统框架，也不留下脱离公共语义的临时补丁。
• 能力切片依据用户核心任务价值排序，不依据渠道用户量排序。
• 每项能力选择渠道适配性最高的平台作为标杆渠道，用于验证统一语义和状态机；其他渠道再依据自身原生机制、权限和稳定性决定原生实现或明确降级。
• 渠道能力按机器人实例和权限动态判断，不能仅凭平台名称宣称支持。
• 出站产物必须由受信工具显式登记并绑定 Session/Turn；现有文件和新建文件语义相同，不要求当前 Turn 创建。助手回答中的路径、Markdown 本地链接和工作区扫描结果不能自动触发文件发送。
• 每个渠道必须先建立可追溯的行为基线；新路径达到语义等价或更优、全量回归通过且可以回滚后，才能接管生产消息。
• 明确降级只适用于原本不具备的新能力或运行时临时故障，不能作为迁移时撤掉既有原生能力的理由。
• 可以在等价接管稳定后删除重复实现，但不得删除用户可观察功能、控制命令、状态语义或安全边界。
• 在高优先级能力完成前，不以继续增加渠道数量作为主要目标。
• 当前共享桥接器、九渠道命令与会话能力、飞书专属卡片能力以及 AI Office Connector 都是迁移资产；新语义路径只能增量包裹并等价接管，不能把成熟实现当作可直接替换的早期原型。