66 lines
4.7 KiB
Markdown
66 lines
4.7 KiB
Markdown
|
# 交付物 · IM 插件接入面（2026-09-25）
|
|||
|
|
|
|||
|
|
> **工作区**：`E:/ProgramData/AIProject/aliyun-dsh-server`（⛔ 未改任何别的工作区文件）
|
|||
|
|
> **起点**：群组插件对接单 `E:/ProgramData/AIProject/dsh-plugin-partment/对接单_平台侧-IM板块待优化与Macro改造可行性_20260925.md`（**只读**）
|
|||
|
|
> **代码基线**：`D:/github/dsh_shenxian`（生产口径 `dshs`）｜域锁 3 域，收口后已反序释放
|
|||
|
|
> **上位**：`01-规范/09-IM插件SDK与扩展点契约.md`（本次已同步）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 一句话
|
|||
|
|
|
|||
|
|
把「IM 基础」改造成**双向可接入**：此前插件只能被宿主调用（入向），**没有任何写入口**；
|
|||
|
|
现在补上**出向端口**（广播 / 落库发言）、**面板动作**、**运行时接线器**，
|
|||
|
|
⇒ 对接单里那三类插件（协作文档 / 任务卡 / 团队记忆 bot）与后续各类功能插件都能接进来。
|
|||
|
|
|
|||
|
|
## 2. 查出的总根（比对接单更靠前）
|
|||
|
|
|
|||
|
|
| # | 实证 | 后果 |
|
|||
|
|
|---|---|---|
|
|||
|
|
| G0 | `new ImSdkHost(...)` 在 `src/**` **零命中**；插件 `check` / `onEvent` / `render` **零调用点** | 「**有契约、无载体**」：插件注册成功，跑起来一片安静 |
|
|||
|
|
| G1 | 无任何出向出口（`hub.deliverFrame` 只在宿主内部用） | 交互型插件**做不了**（无写入口） |
|
|||
|
|
| G2 | `PanelContract` 只有 `render`（只读），无 `onAction` | "从面板一键建卡"做不了 |
|
|||
|
|
| G3 | `ColumnType` / `COLUMN_SQL` 漏 `bigtext`（底层与 08/DB-03 一直是 **9 种**） | 按规范写 `bigtext` 会被**注册校验拒** |
|
|||
|
|
| G4 | `08 §3-4` 路由指针错（真在 `plugin-data.ts`） | 作者按文档找不到取数实现 |
|
|||
|
|
|
|||
|
|
## 3. 交付（本机代码面 · 7 文件 · 内核改动均为**纯插入**）
|
|||
|
|
|
|||
|
|
| 文件 | 加了什么 |
|
|||
|
|
|---|---|
|
|||
|
|
| `src/im/sdk/types.ts` | **扩展点 8 · 出向端口**（`OutboundContract` / `ImOutboundPort`：`frame` 不落库广播 · `message` 落库发言）· **面板动作** `PanelActionInput` / `onAction` · 事件补 `panel.opened|closed` · `bigtext` · 分片纯函数 `chunkText` / `assembleText` |
|
|||
|
|
| `src/im/sdk/host.ts` | 出向注册校验 · 归属闸（**缺省 fail-closed**）· `FrameThrottle` 硬上限 · `dispatchPanelAction` · `panelsFor` · `hasPlugins()` 短路 · `COLUMN_SQL` 补 `bigtext` |
|
|||
|
|
| **`src/im/sdk/binding.ts`（新）** | **接线器**：`beforeWrite`（写前问发言规则）· `afterAppend`（**后台**派发；`private` 不派发）· 面板动作（成员校验）· 四项 fail-closed |
|
|||
|
|
| `src/im/sdk/index.ts` | 门面导出 |
|
|||
|
|
| `src/im/ws.ts`（+41/−0） | `send` 分支两处接线 |
|
|||
|
|
| `src/web/routes/im.ts`（+155/−0） | 装配 ＋ 两处钩子 ＋ **两个插件面端点**（`GET /panels` · `POST /panels/:panelId/actions`） |
|
|||
|
|
| `test/im-sdk.test.mjs` | ＋12 用例（⇒ 78 例） |
|
|||
|
|
|
|||
|
|
🔴 **关键设计取舍（可推翻）**：对接单建议"给 `MessageVisibility` 加 `system` / `hidden` 档"，
|
|||
|
|
**未采纳** —— 改内核枚举会连带改 `messages` 的 `CHECK` 约束与迁移。本次改用**通道分离**：
|
|||
|
|
高频 ephemeral 走 `frame`（**不落库**、不进历史、不走去重），要历史就走 `message`（落库）。
|
|||
|
|
⇒ 一行内核枚举没动，且语义比"加档位"更干净。
|
|||
|
|
|
|||
|
|
## 4. 判据读数
|
|||
|
|
|
|||
|
|
- `npm run build` **rc=0**
|
|||
|
|
- `node --test test/im-sdk.test.mjs` = **78 / 75 过 / 0 败 / 3 跳过**
|
|||
|
|
- `npm test` = **604 / 594 过 / 5 败 / 5 跳过**
|
|||
|
|
- `npm run check:layering` **rc=0 ✅ 无新增违规**
|
|||
|
|
- 内核改动形态：`store.ts` / `hub.ts` **零改动**；`ws.ts` / `routes/im.ts` **纯插入**（`numstat` 删除列 = 0）
|
|||
|
|
|
|||
|
|
⚠️ **两处失败/跳过都是本机环境问题，⛔ 与本改造无关**：IM 侧 3 例 `spawnSync git EBUSY`；
|
|||
|
|
投放线 `shared-layer-sync.test.mjs` 5 例 `spawnSync tar EBUSY`。已把 IM 侧改成**具名跳过**。
|
|||
|
|
|
|||
|
|
## 5. 文档同步（对接单 §1 的 P1×2 ＋ P2×3 已消）
|
|||
|
|
|
|||
|
|
- `01-规范/09-IM插件SDK与扩展点契约.md`：§2 加第 8 项 · 新增 **§3.5 接线器** · §6 修「事务仅限同前缀多表」→ **本期无事务口** · 补 `bigtext` / 分片 · §8 判据与 EBUSY 说明 · 新增 **§9 出向端口与面板动作**
|
|||
|
|
- `01-规范/08-插件开发与对接规范.md`：修 §3-4 路由指针 · 补 SDK 获取方式 · 顶部加 09 指针 · §11 变更记录
|
|||
|
|
|
|||
|
|
## 6. 未做（点名归属 · ⛔ 本棒不越界）
|
|||
|
|
|
|||
|
|
① **插件清单来源**（谁调 `binding.host.register(...)`）＝**投放线**（本棒只装插座与接线）
|
|||
|
|
② 宿主侧 `ImDataPort` 按 pluginId 装配（面板 `reads` 取数依赖它）
|
|||
|
|
③ `approvedRoomTypes` 来源 ＝ admin 审核面
|
|||
|
|
④ 插件侧 LLM 调用面（对接单 §2-3-4）—— 涉费用，待用户定
|
|||
|
|
|
|||
|
|
⛔ 未部署 · ⛔ 未动 47/106 · ⛔ 未 commit / push · ⛔ 未投放插件 · ⛔ 未改 A–E 五单结论。
|