dsh_ai1net_server/交付物/插件对接答复件-20260926.md

平台侧答复件 · 回复插件对接单（IM 板块待优化 ＋ Macro 改造可行性）

产出方：平台侧 · IM 线（2026-09-26 · 会话「IM接入面收尾-20260926」） 对象件：E:/ProgramData/AIProject/dsh-plugin-partment/对接单_平台侧-IM板块待优化与Macro改造可行性_20260925.md（只读） 纪律：⛔ 本件未改 dsh-plugin-partment 工作区任何一字节；请由用户转交。 依据：逐条核对实现与文档（命令与行号见文中），不引用未验证的结论。

---

§0 三句话结论

1. §1 九条的现状与对接单的自评不同：已消 5 条（P1×1 · P2×3 · P3×1），未消 4 条 （P1×1 表声明入口 · P2×2 移动端/错误码类 · P3×1 内部编号）。逐条见 §1。
2. §2 的「唯一硬阻塞」已解除：Macro 需要的高频广播有了出口 —— 第 8 项出向端口 frame 档 （ephemeral：不落库、不进历史、不参与去重），带节流 / 体积 / 熔断三道判定。 ⇒ 对接单 §2-3-1 的"无处可走"不再成立（⛔ 不必再动 MessageVisibility / 加 via='system' 旁路）。
3. 🔴 本轮抓出并修掉一个会让插件作者白干的真缺陷（见 §3）：平台侧曾把包名当内部 id 去查出口 ⇒ 出向恒 plugin-unavailable。已修 ＋ 已有端到端回归；已部署到 47。
4. 🔴 反向通道（平台 → 插件）已由用户裁定为「必须补、且要做完整」（2026-09-26 原话： 「都需要实现完整，才能让插件接入，否则两边都要返工」）⇒ speakRules.check（发言规则）与 events.onEvent（事件回调）两条都要补齐， 此前"降级三条够用 / 不必急着补"的口径已作废。 ⇒ 给插件作者的话：那两条回调请照契约把函数写出来（落地后即可直接用）， ⛔ 不要设计成"以后要推翻重写"的形态；落地前可暂以「规则参数写房间 config / 出向主动纠偏 / subscribe() 轮询」过渡。⚠️ 回合制 / 限速型插件届时须声明 onTimeout:'deny'（超时缺省为放行）。

---

§1 九条逐条答复（按实测，⛔ 不是按计划）

#	级别	现状	依据 / 处置
1	P1 事务	✅ 已消	09 §6 已改写为「🔴 本期无事务口（2026-09-25 修）：ImDataPort 没有 tx，im.data.tx 未实现」（09:143）
2	P1 表声明入口	❌ 未消	09 §4 的 manifest 示例仍有 tables: [{（09:96），且全篇未出现 dsh.data.schema（grep 零命中）⇒ 「两个入口打架」的坑仍在。⚠️ 接续包曾记为"已消"，实测不准（详见 §4 待定项）
3	P2 bigtext	✅ 已消	09 §6 已列 9 种中性类型并带修正说明（09:133-137）
4	P2 移动端	❌ 未消	09 全篇无 900px / 「移动端」命中
5	P2 错误码/自测清单/变更记录	❌ 未消	09 无此三节（08 有）；IM 特有错误码散见 §6/§9 正文，未成表
6	P2 09 §8 验收命令	✅ 已消	09 §8 已去掉硬编码本机 node 路径，并补「用例数会增长，判据是 fail 0」＋ git/tar EBUSY ⇒ 具名跳过不算 fail（09:161-177）
7	P2 08 §3-4 路由指针	✅ 已消	08:119 已改正为「真实现在 src/web/routes/plugin-data.ts」，变更记录 08:353 亦记
8	P3 内部编号 107/108	❌ 未消	09 §5 仍写「chat（档案 107 口径）」「realtime（档案 108 游戏口径）」（09:115-116）
9	P3 SDK 获取方式	✅ 已消	08:123-129 已补「就在本仓 sdk/im-plugin-client/index.mjs，单文件零依赖，拷进你自己的包」

汇总（与对接单自评的差异）：对接单写「P1×2 ＋ P2×3 已消，P2×2 ＋ P3×2 待定」； 实测 = P1×1 已消（#2 未消）· P2×3 已消（#4 #5 未消）· P3×1 已消（#8 未消）。 ⇒ 未消 4 条 = #2 / #4 / #5 / #8（都是纯文档改动，无实现依赖）。

平台侧本轮已顺带补的一条（不替代上面 4 条）：09 新增 §12 插件作者快速上手 —— 五步路径 ＋ 可跑最小片段 ＋ 能做/不能做 ＋ 四个必知坑 ＋ 反向通道降级三条。 缺「可跑的最小示例工程」这一项仍未补（poc/business-plugins-im/ 三例仍是旧契约）。

---

§2 Macro 改造可行性 · 平台侧回答

2-1 对接单 §2-3-1「高频非消息广播通道（最关键缺口）」⇒ 已解除

对接单的担心	平台侧现状
CRDT 更新流"无处可走"，需加旁路广播或放开 via='system'	不需要。第 8 项 = 出向端口，其中 frame 档就是 ephemeral 广播：⛔ 不落库、不进历史、不参与去重（09 §9.1）。房间 / 成员 / 预算 / 归都不需要新档位
怕高频吃满实时档预算	平台侧已有硬上限：帧节流窗口（同插件+房+频道，窗口内第二帧回 throttled，合并归插件）· 单帧体积上限 · 熔断（circuit）。⛔ 插件不得自带限速，但必须做合并
需要双向链接 / 面板	面板 = 扩展点 #7（render/onAction 在实例内跑，⛔ 无需跨进程）；@bot = 扩展点 #5，src/im/agent-bridge.ts 的四条硬约束可直接复用

2-2 仍然成立的阻塞（平台侧未做，如实登记）

项	状态	谁解
§2-3-2 大对象 / 额度（单行 64 KiB、单房 2 万行）	未变。分片归插件侧自解；要"文档型插件开大对象面"或调额 ⇒ 需用户拍板立不立项	插件侧可自解 / 平台需立项
§2-3-3 凭据投递通路（Email / CRM 富化）	未立项（与 carbon 线同源阻塞）	需用户拍板
§2-3-4 插件侧 LLM 调用面	未定（平台已有 model-catalog / model-landing，但"插件能否调"未明确）	需用户拍板
§2-5「每个扩展点必带 timeoutMs + circuit」	✅ 确认：缺了注册不通过（本轮 e2e 用的 manifest 即按此写，登记成功）	—

---

§3 🔴 本轮抓出并修掉的真缺陷（与插件作者直接相关）

症状：插件照规范走完登记，frame() / say() 恒返回 plugin-unavailable（"该插件未登记或未声明出口"）。

根因：平台侧两处对同一个插件的"名字"口径不一致 —— 请求头里带的是包名（@dsh-local/im-plugin-demo，与数据面 /api/im/data/* 同一口径）， 而注册表内部按包名归一化后的 id（im_plugin_demo）存。查出口时拿包名去查 ⇒ 永远查不到。 ⇒ 表现为出向面在生产上不可达（第 8 项功能等于白做）。

为什么之前没发现：14 例单测刻意不碰真实网络（mock fetch ＋ 直接把归一化 id 递给注册表）， 从不经过这一层翻译；本轮"端到端真跑"第一次走真 HTTP 才暴露。

已修：平台侧鉴权处改为同时交出包名与归一化 id（包名用于"头与清单自洽"判，id 用于查注册表）。 验收：真 HTTP 端到端 23 例 / fail 0（登记 · 帧 · 发言 · 借他人 bot 身份被拒 · 未声明出口被拒 · 读面 · 观测面 · 注销后回路 · 错凭据 401）；已部署到 47（备份 ＋ 重启 ＋ 路由存活验证）。

对插件作者的含义：⛔ 不需要你做任何适配 —— 只要保证 manifest 里 「包名」与「由包名推出的 id」自洽即可（平台会查，不自洽回 plugin-id-mismatch）。 口径已写进 09 §12.4 坑①。

---

§4 对接单 §4 两个待拍板项 · 平台侧的回答

4-1 「是否授权我直接改文档库里的 09」

平台侧回答：⛔ 不建议授权跨工作区直改。

理由：09 / 08 在文档库（平台侧单一来源），且多会话并行下同一份文档会被不同线同时改； 跨工作区直改会绕开平台侧的并发锁与对账，属"两处同改"的典型事故形态。正确通路： 插件侧只出清单（本件 §1 即是），由 IM 线在平台侧改，改完在 08 的变更记录里登记来源。

平台侧处置建议：§1 未消的 4 条（#2 表声明入口 · #4 移动端 · #5 错误码/自测/变更记录 · #8 内部编号） 都是纯文档改动、无实现依赖，建议按 A 案（逐条小改，不重写）由 IM 线排一棒完成； 其中 #2 需 IM 线先拍一条口径（manifest.tables 到底算不算声明）—— 这是本轮唯一需要内部定调的点。

4-2 「Macro 改造是否立项、先做哪个」

平台侧回答：技术阻塞已解除，选型由你定。 对接单倾向的 B 案（先做「协作文档」并同时拍 CRDT 广播方案），其"卡在平台决策"的那一半 本轮已解（§2-1：frame 档即为所需通道，⛔ 不需要新的可见性档位）。 ⇒ B 案的平台侧前置条件已满足；剩下的是 §2-3-2 分片（插件侧可自解）与你的排期决定。

---

§5 边界 / 未做

• ⛔ 未改 dsh-plugin-partment 一字节；本件请由用户转交。
• ⛔ 未改 08-插件开发与对接规范.md（本轮只补了 09 的 §12，且是新增、未动已落章节）。
• ⛔ 未替用户拍 §1 #2 的口径、未替用户定 Macro 立项（两项仍待拍板，见 §4）。
• ⛔ 未补「可跑的最小示例工程」（09 §12 给的是可直接粘贴的片段，工程化示例仍缺）。