124 lines
9.5 KiB
Markdown
124 lines
9.5 KiB
Markdown
|
# 平台侧答复件 · 回复插件对接单（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 给的是可直接粘贴的片段，工程化示例仍缺）。
|