# 交付物 · 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 五单结论。