dsh-im-union 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 本项目版本号遵循语义化版本；发布面与宿主兼容矩阵见 `scripts/hosts.mjs`（README 管理块同源）。
 
+## 0.1.0（首个功能版，dist-tag=latest）
+
+M1–M3 代码侧全量：14 渠道协议层 + 跨版本窄腰 + 会话引擎 + 管理面。
+
+### Added
+
+- 渠道（P0）：微信 iLink（官方 ClawBot 协议 + 扫码绑定 UI）、飞书（WS 长连 + 流式卡片/逐步消息双档 + 语音档可选）、Telegram（长轮询 + 编辑流式）、Discord（Gateway v10 + 表格转竖排）、企微智能机器人（长连 + 思考中/工具进度原生显示）
+- 渠道（P1）：钉钉 stream + AI Card；QQ 官方 API v2（被动窗口）；Slack Socket Mode 零 SDK + thread 模型
+- 渠道（P2）：WhatsApp（Baileys，QR 配对 + auth 目录持久化）；Matrix（CS API，E2EE 两档诚实档位）；iMessage（仅 macOS，非 darwin 硬拒载）；企微自建应用（回调验签 + 加解密，webhook 白名单路由）
+- 能力：命令面板 24 命令（含 /fork /rename /delivery /export /speak /mute /goal）；审批与交互提问 IM 闭环（waterfall 返回即接管，fail-closed D5）；图片/文件输入（宿主元数据判视觉 E4）；产物文件回传；投递日志与断线补发（≤3 次，uncertain 绝不重发 D7）；超时迟到结果收割；主动投递目标库 + 双向同步；碎片续写（.. / !!）；引用上下文增强；会话标题渠道徽章
+- AI Office Connector：查实宿主无公开 connector 协议面 → 离线 Job 队列诚实档（https 强制/租约/审批/并发上限）
+
+### Fixed
+
+- Cordis ctx 代理未 inject 属性访问即抛（可选链拦不住）→ 窄腰全 try/catch 守卫
+- 静音判定吞掉 /mute 自身导致的永久静默死锁；/model 与投递链 selections 键不一致导致的视觉判定永命中 unknown
+
+### Changed
+
+- publishConfig.tag：next → latest；THIRD_PARTY_NOTICES 运行时依赖清单与实现对齐（纠未采纳的 SDK 列表）
+
 ## 0.0.1（首发占位，tag=next）
 
 预发布占位版本，非推荐安装线；语义为「协议层与跨版本骨架完成、真机验收进行中」。

package/README.en.md

@@ -8,14 +8,22 @@ A union IM bridge for DeepSeek Harness — a clean-room reimplementation merging
 
 ## Status
 
-Under development (M0 cross-version skeleton). See `tasks.md` for phasing.
+**0.1.0 feature release**: all 14 P0/P1/P2 channel protocol layers, the cross-version narrow waist, session engine, approval/question IM loop and multi-account management are delivered (574 unit tests; host-farm smoke green on 0.1.2 / 0.1.5 / 0.1.7 / 0.2.1 lines). Outstanding real-device acceptance items are registered in CHANGELOG.
 
-## Install (npm package available after M1)
+Highlights:
+
+- **Channels**: WeChat (official iLink QR bind), Feishu/Lark (long-connection, streaming cards, optional voice tier), Telegram, Discord, WeCom intelligent bot, DingTalk (stream + AI Card), QQ official bot, Slack (Socket Mode, zero SDK), WhatsApp (Baileys QR pairing), Matrix, iMessage (macOS only), WeCom self-built app (signed callback webhook), and more; unconfigured channels load nothing (lazy imports).
+- **In-chat loop**: 24 commands (`/help /status /new /stop /steer /model(s) /reasoning /preset(s) /session(s) /workspace(s) /fork /rename /queue /mute /unbind /goal /delivery /export /speak /menu`); tool approvals and agent questions answered in the originating chat (deny-by-default, 5-minute expiry, initiator only).
+- **Cross-version**: settings surface auto-adapts gen1/gen2/gen3; capability probing only, never version branches.
+
+## Install
 
 ```sh
 dsh plugin --profile web add dsh-im-union@latest --registry=https://registry.npmjs.org/
 ```
 
+Then add accounts in the "IM union bridge" panel: most channels use credential binding (secrets are one-way into the vault and never echoed back); WeChat/WhatsApp use QR pairing; the WeCom self-built app channel requires pointing your callback URL (`/api/dsh-im-union/wecom-app/callback`) in its console. See `SECURITY.md` for the non-negotiable privacy red lines and `THIRD_PARTY_NOTICES.md` for the clean-room provenance.
+
 ## Development
 
 ```sh

package/README.md

@@ -8,14 +8,22 @@ DeepSeek Harness 的 IM 联合桥——净室重写，能力合集来自社区
 
 ## 状态
 
-开发中（M0 跨版本骨架）。能力分期见根目录 `tasks.md`。
+**0.1.0 功能版**：P0/P1/P2 十四渠道协议层、跨版本窄腰、会话引擎、审批/提问 IM 闭环、多账号管理面均已交付（单测 574 项；宿主农场 0.1.2/0.1.5/0.1.7/0.2.1 四线冒烟全绿）。真机验收项逐项登记在 CHANGELOG；能力分期见开发仓计划台账。
 
-## 安装（M1 后提供 npm 包）
+能力总览：
+
+- **渠道**：微信（官方 iLink 扫码）、飞书（长连/流式卡片/语音档可选）、Telegram、Discord、企微智能机器人（长连）、钉钉（stream+AI Card）、QQ 官方机器人、Slack（Socket Mode）、WhatsApp（Baileys 扫码）、Matrix、iMessage（仅 macOS）、企微自建应用（回调）等；未配置渠道零依赖零加载（懒 import）。
+- **IM 内闭环**：24 命令面板（/help /status /new /stop /steer /model(s) /reasoning /preset(s) /session(s) /workspace(s) /fork /rename /queue /mute /unbind /goal /delivery /export /speak /menu）；工具审批与交互提问原聊天回答（默认拒绝、5 分钟超时、发起者限定）。
+- **跨版本**：设置面 gen1/gen2/gen3 三态自适配；能力探测优先，禁版本号分支。
+
+## 安装
 
 ```sh
 dsh plugin --profile web add dsh-im-union@latest --registry=https://registry.npmjs.org/
 ```
 
+装好后在宿主侧栏/设置页的「IM 联合桥」面板添加账号：大部分渠道走凭据绑定（Bot Token/App 凭据，secret 字段只单向入库不回显）；微信/WhatsApp 走扫码绑定；企微自建应用需将本插件管理面回调 URL（`/api/dsh-im-union/wecom-app/callback`）配入后台接收服务器。隐私与凭据红线见 `SECURITY.md`；第三方依赖声明见 `THIRD_PARTY_NOTICES.md`（净室重实现，不复制任何上游源码）。
+
 ## 开发
 
 ```sh

package/THIRD_PARTY_NOTICES.md

@@ -16,12 +16,22 @@ dependencies only.
 
 ## Runtime npm dependencies (consumed as-is, licenses per their packages)
 
-- @larksuiteoapi/node-sdk (MIT) — Feishu/Lark bot long-connection SDK
-- dingtalk-stream (MIT) — DingTalk Stream mode SDK
-- @wecom/aibot-node-sdk — WeCom intelligent-bot WebSocket SDK
-- @tencent-connect/qqbot-connector — QQ bot QR pairing helper (declared
-  UNLICENSED upstream; used as an external dependency only, never vendored)
-- qrcode (MIT) — QR rendering for scan-to-bind flows
+- @larksuiteoapi/node-sdk (MIT) — Feishu/Lark bot long-connection SDK (its WS
+  handshake/signature surface is a private protocol, so the official SDK is used
+  instead of a clean-room reimplementation; lazily imported)
+- @whiskeysockets/baileys (MPL-2.0) — WhatsApp Web multi-device protocol library
+  (lazily imported; only the WhatsApp channel touches it)
+- qrcode (MIT) — QR PNG data-URL rendering for the WeChat iLink / WhatsApp
+  scan-to-bind flows (lazily imported)
 
-P1/P2 additions will be listed here as they land (Baileys, @matrix-org/olm,
-imapflow/nodemailer, sharp — none are dependencies at M0).
+Everything else (Telegram, Discord, Slack, QQ, DingTalk, WeCom bot long-connection,
+WeCom self-built app callback crypto, WeChat iLink transport, Matrix CS API) is
+implemented directly against public protocol documents with ZERO runtime
+dependencies (Node >= 22 global fetch/WebSocket + node:crypto/node:zlib only).
+Earlier drafts of this file listed dingtalk-stream, @wecom/aibot-node-sdk and
+@tencent-connect/qqbot-connector; those SDKs were never adopted — the respective
+channels are zero-dependency clean-room implementations (corrected at 0.1.0).
+
+Optional external tools: ffmpeg (system binary, spawned only when the Feishu
+voice tier is explicitly enabled; never bundled, never assumed present — the
+feature degrades honestly when missing).

package/client.js

@@ -37,6 +37,20 @@ window.__ModuleLoader__.load({
         'accounts.title': '账号管理',
         'accounts.empty': '暂无账号，在下方添加。',
         'accounts.add': '添加账号',
+        'accounts.qr.get': '获取登录二维码',
+        'accounts.qr.refresh': '重新获取二维码',
+        'accounts.qr.cancel': '取消扫码',
+        'accounts.qr.needid': '请先填写账号 ID 再获取二维码',
+        'accounts.qr.wait': '等待扫码…（用微信扫上方二维码）',
+        'accounts.qr.scaned': '已扫码，请在手机上确认授权',
+        'accounts.qr.expired': '二维码已过期，请重新获取',
+        'accounts.qr.need_verifycode': '请输入手机上显示的验证码',
+        'accounts.qr.verify_code_blocked': '验证码错误次数过多，请重新获取二维码',
+        'accounts.qr.binded_redirect': '该 Bot 已绑定其它实例',
+        'accounts.qr.scaned_but_redirect': '已扫码，正在重定向等待确认',
+        'accounts.qr.code.submit': '提交验证码',
+        'accounts.qr.confirmed': '扫码绑定完成，凭据已保存并连接',
+        'accounts.saved.bindhint': '已保存（未连接）：请用「获取登录二维码」完成扫码授权后自动连接',
         'accounts.save': '保存',
         'accounts.cancel': '取消',
         'accounts.check': '检查连接',
@@ -73,6 +87,20 @@ window.__ModuleLoader__.load({
         'accounts.title': 'Accounts',
         'accounts.empty': 'No accounts yet. Add one below.',
         'accounts.add': 'Add account',
+                'accounts.qr.get': 'Get login QR code',
+                'accounts.qr.refresh': 'Refresh QR code',
+                'accounts.qr.cancel': 'Cancel',
+                'accounts.qr.needid': 'Fill the account ID first, then get the QR code',
+                'accounts.qr.wait': 'Waiting for scan… (scan with WeChat)',
+                'accounts.qr.scaned': 'Scanned — confirm on your phone',
+                'accounts.qr.expired': 'QR expired, fetch a new one',
+                'accounts.qr.need_verifycode': 'Enter the code shown on your phone',
+                'accounts.qr.verify_code_blocked': 'Too many wrong codes, fetch a new QR',
+                'accounts.qr.binded_redirect': 'This bot is already bound to another instance',
+                'accounts.qr.scaned_but_redirect': 'Scanned — redirecting, waiting for confirm',
+                'accounts.qr.code.submit': 'Submit code',
+                'accounts.qr.confirmed': 'QR binding done — credentials saved and connected',
+        'accounts.saved.bindhint': 'Saved (disconnected): use "Get login QR code" to bind, it connects automatically',
         'accounts.save': 'Save',
         'accounts.cancel': 'Cancel',
         'accounts.check': 'Check connection',
@@ -176,6 +204,10 @@ window.__ModuleLoader__.load({
       var allowHook = useState({});
       var allowDrafts = allowHook[0];
       var setAllowDrafts = allowHook[1];
+      // 微信扫码绑定态（T1.2）：null | {qrcode, qrDataUrl, accountId, status, verifyCode?}
+      var qrHook = useState(null);
+      var qr = qrHook[0];
+      var setQr = qrHook[1];
 
       var load = function () {
         getJSON('/accounts').then(function (result) {
@@ -202,10 +234,14 @@ window.__ModuleLoader__.load({
       }
 
       var submitNew = function () {
+        // 微信扫码账号：表单存而连——凭据由扫码流程写入，保存时必须跳过
+        // 适配器构建（否则 botToken 缺失工厂即抛 → 被当校验错 400，UI 假报）。
+        var payload = { record: form, secrets: form.secrets };
+        if (form.channel === 'weixin' && (form.secrets.botToken || '') === '') payload.skipConnect = true;
         withBusy(function () {
-          return postJSON('/accounts/save', { record: form, secrets: form.secrets }).then(function (result) {
+          return postJSON('/accounts/save', payload).then(function (result) {
             if (result.status === 200) {
-              setNotice(t('accounts.saved'));
+              setNotice(form.channel === 'weixin' && payload.skipConnect ? t('accounts.saved.bindhint') : t('accounts.saved'));
               setAddOpen(false);
               setForm({ channel: form.channel, accountId: '', alias: '', secrets: {} });
               load();
@@ -243,6 +279,51 @@ window.__ModuleLoader__.load({
         });
       };
 
+      var startQr = function () {
+        if (form.accountId === '') {
+          setNotice(t('accounts.qr.needid'));
+          return;
+        }
+        withBusy(function () {
+          return postJSON('/weixin/qr/start', {}).then(function (result) {
+            if (result.status === 200 && result.json && result.json.ok) {
+              setQr({ qrcode: result.json.qrcode, qrDataUrl: result.json.qrDataUrl, accountId: form.accountId, status: 'wait' });
+            } else {
+              setNotice((result.json && result.json.error) || 'HTTP ' + result.status);
+            }
+          });
+        });
+      };
+
+      // 状态驱动串行轮询：每次 setQr 产生新对象触发 effect 重跑下一拍；
+      // 服务端每请求 hold 最长 ~35s，前端不并发叠轮（cleanup 置活旗防串台）。
+      useEffect(function () {
+        if (qr === null) return undefined;
+        if (qr.status === 'confirmed' || qr.status === 'expired' || qr.status === 'need_verifycode' || qr.status === 'verify_code_blocked') return undefined;
+        var alive = true;
+        var payload = { qrcode: qr.qrcode, accountId: qr.accountId };
+        if (typeof qr.verifyCode === 'string' && qr.verifyCode !== '') payload.verifyCode = qr.verifyCode;
+        postJSON('/weixin/qr/status', payload).then(function (result) {
+          if (!alive) return;
+          if (result.status === 200 && result.json && result.json.ok) {
+            var status = result.json.status;
+            if (status === 'confirmed') {
+              setQr(Object.assign({}, qr, { status: 'confirmed' }));
+              setNotice(t('accounts.qr.confirmed'));
+              setAddOpen(false);
+              load();
+            } else {
+              setQr(Object.assign({}, qr, { status: status }));
+            }
+          } else if (alive) {
+            setQr(Object.assign({}, qr, { status: 'expired' })); // 请求异常保守收轮：引导重新取码而非假进度
+          }
+        }).catch(function () {
+          if (alive) setQr(Object.assign({}, qr, { status: 'expired' }));
+        });
+        return function () { alive = false; };
+      }, [qr]);
+
       var body = [];
       body.push(createElement('h4', null, t('accounts.title')));
       if (notice !== '') body.push(createElement('p', { style: { color: '#a33' } }, notice));
@@ -350,6 +431,48 @@ window.__ModuleLoader__.load({
             )
           );
         });
+        var qrBlock = null;
+        if (form.channel === 'weixin') {
+          if (qr === null || qr.status === 'expired') {
+            qrBlock = createElement(
+              'div',
+              { key: 'qr-idle', style: { marginTop: 8 } },
+              createElement('button', { onClick: startQr, disabled: busy }, t(qr === null ? 'accounts.qr.get' : 'accounts.qr.refresh'))
+            );
+          } else if (qr.status === 'confirmed') {
+            qrBlock = createElement('p', { key: 'qr-done', style: { color: '#2a6' } }, t('accounts.qr.confirmed'));
+          } else {
+            var qrChildren = [
+              createElement('img', { key: 'img', src: qr.qrDataUrl, width: 200, height: 200, alt: 'login qr', style: { display: 'block' } }),
+              createElement('p', { key: 'st', style: { marginTop: 4 } }, t('accounts.qr.' + qr.status)),
+            ];
+            if (qr.status === 'need_verifycode') {
+              qrChildren.push(
+                createElement(
+                  'div',
+                  { key: 'vc' },
+                  createElement('input', {
+                    value: qr.verifyCode || '',
+                    onChange: function (event) { setQr(Object.assign({}, qr, { verifyCode: event.target.value })); },
+                  }),
+                  createElement(
+                    'button',
+                    { style: { marginLeft: 6 }, onClick: function () { setQr(Object.assign({}, qr, { status: 'wait' })); } },
+                    t('accounts.qr.code.submit')
+                  )
+                )
+              );
+            }
+            qrChildren.push(
+              createElement(
+                'button',
+                { key: 'cancel', style: { marginTop: 4 }, onClick: function () { setQr(null); } },
+                t('accounts.qr.cancel')
+              )
+            );
+            qrBlock = createElement('div', { key: 'qr-live', style: { marginTop: 8, padding: 8, border: '1px solid #ddd', borderRadius: 8 } }, qrChildren);
+          }
+        }
         body.push(
           createElement(
             'div',
@@ -393,6 +516,7 @@ window.__ModuleLoader__.load({
               })
             ),
             fieldInputs,
+            qrBlock,
             createElement(
               'div',
               { style: { marginTop: 8 } },

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-im-union",
   "name": "dsh-im-union",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": {
     "en": "Union IM bridge for DeepSeek Harness: multi-account bots across messaging platforms, each chat bound to its own session, with cross-host-version compatibility (0.1.2-rc.1 .. 0.2.1-alpha.3).",
     "zh": "DeepSeek Harness 的 IM 联合桥：多平台多账号机器人、每个聊天绑定独立会话，跨宿主版本兼容（0.1.2-rc.1 至 0.2.1-alpha.3）。"

package/lib/admin/api.d.ts

@@ -22,6 +22,10 @@ export interface AdminRequest {
     url: URL;
     body: unknown;
     respond: AdminResponder;
+    /** raw 路由（第三方回调）专用：原文 body 文本 + 查询参数表 + 非 JSON 应答面。 */
+    rawBody?: string;
+    query?: Record<string, string>;
+    respondText?: (status: number, text: string) => void;
 }
 export type AdminHandler = (request: AdminRequest) => void | Promise<void>;
 /** 写请求前置检查；返回错误状态码或 undefined。 */
@@ -29,9 +33,23 @@ export declare function validateMutation(req: IncomingMessage): number | undefin
 export interface AdminApiHandle {
     dispose(): void;
 }
+/**
+ * 第三方回调路由白名单（T3.4 企微自建应用等 inbound webhook）。
+ * 口径登记：D2/D3 的 requestRejection/JSON 闸适用于**管理面**（浏览器/本机调用）；
+ * 平台回调来自厂商服务器、无登录 Cookie，其认证就是签名验证（SHA1+AES，
+ * fail-closed）——因此命中的路径跳过 requestRejection 与 JSON 前置闸，
+ * 改由 handler 自身验签；仍走同一前缀注册、no-store、体积上限与错误零回显纪律。
+ */
+export interface RawRoute {
+    path: string;
+    /** 允许 GET 回明文（echostr 验证面原样输出，不包 JSON）。 */
+    plainText?: boolean;
+}
 /**
  * 注册管理面。routes 用精确路径匹配（M0 只挂 /ping 与 /state 两个只读探针，
  * 账号 CRUD 随 M1 渠道层落地）。webServer 缺失（非 web profile）→ 不注册，
  * 记日志不抛错——CLI/TUI 宿主上插件其余部分照常。
  */
-export declare function registerAdminApi(ctx: CordisLike, routes: Record<string, AdminHandler>): AdminApiHandle;
+export declare function registerAdminApi(ctx: CordisLike, routes: Record<string, AdminHandler>, opts?: {
+    rawRoutes?: RawRoute[];
+}): AdminApiHandle;

package/lib/admin/api.js

@@ -43,7 +43,8 @@ export function validateMutation(req) {
  * 账号 CRUD 随 M1 渠道层落地）。webServer 缺失（非 web profile）→ 不注册，
  * 记日志不抛错——CLI/TUI 宿主上插件其余部分照常。
  */
-export function registerAdminApi(ctx, routes) {
+export function registerAdminApi(ctx, routes, opts) {
+    const rawPaths = new Map((opts?.rawRoutes ?? []).map((r) => [r.path, r]));
     const log = ctx.logger('dsh-im-union');
     const webServer = optionalService(ctx, 'webServer');
     if (webServer === undefined || typeof webServer.register !== 'function') {
@@ -55,7 +56,67 @@ export function registerAdminApi(ctx, routes) {
         path: BASE_PATH,
         handler: async (req, res) => {
             try {
-                // 动态读取，不缓存认证实例（HMR/重启后实例会变）。
+                const url = new URL(req.url ?? '/', 'http://localhost');
+                const method = (req.method ?? 'GET').toUpperCase();
+                if (url.pathname !== BASE_PATH && !url.pathname.startsWith(BASE_PATH + '/')) {
+                    send(res, 404, { ok: false, error: 'not found' });
+                    return;
+                }
+                const path = url.pathname.slice(BASE_PATH.length) || '/';
+                const handler = routes[path];
+                if (handler === undefined) {
+                    send(res, 404, { ok: false, error: 'not found' });
+                    return;
+                }
+                const rawRoute = rawPaths.get(path);
+                if (rawRoute !== undefined) {
+                    // 第三方回调面：验签即认证，读原文 body（≤1 MiB）后交 handler 处置。
+                    let rawBody = '';
+                    if (method !== 'GET' && method !== 'HEAD') {
+                        const chunks = [];
+                        let total = 0;
+                        for await (const chunk of req) {
+                            const buf = chunk;
+                            total += buf.length;
+                            if (total > MAX_BODY_BYTES) {
+                                send(res, 413, { ok: false, error: '请求体超限' });
+                                return;
+                            }
+                            chunks.push(buf);
+                        }
+                        rawBody = Buffer.concat(chunks).toString('utf8');
+                    }
+                    const query = {};
+                    url.searchParams.forEach((value, key) => {
+                        query[key] = value;
+                    });
+                    let settled = false;
+                    await handler({
+                        method,
+                        path,
+                        url,
+                        body: query,
+                        rawBody,
+                        query,
+                        respond: (status, payload) => {
+                            settled = true;
+                            send(res, status, payload);
+                        },
+                        respondText: rawRoute.plainText
+                            ? (status, text) => {
+                                settled = true;
+                                res.statusCode = status;
+                                res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+                                res.setHeader('Cache-Control', 'no-store');
+                                res.end(text);
+                            }
+                            : undefined,
+                    });
+                    if (!settled)
+                        send(res, 200, { ok: true });
+                    return;
+                }
+                // 以下 requestRejection/JSON 闸只约束管理面（动态读取，不缓存认证实例）。
                 const connection = optionalService(ctx, 'connection');
                 if (typeof connection?.requestRejection !== 'function') {
                     send(res, 503, { ok: false, error: '宿主认证服务未就绪或版本不支持；请重启 DSH 或升级宿主。' });
@@ -74,19 +135,7 @@ export function registerAdminApi(ctx, routes) {
                     send(res, mutationError, { ok: false, error: '写请求需 application/json 与客户端标识头' });
                     return;
                 }
-                const url = new URL(req.url ?? '/', 'http://localhost');
-                if (url.pathname !== BASE_PATH && !url.pathname.startsWith(BASE_PATH + '/')) {
-                    send(res, 404, { ok: false, error: 'not found' });
-                    return;
-                }
-                const path = url.pathname.slice(BASE_PATH.length) || '/';
-                const handler = routes[path];
-                if (handler === undefined) {
-                    send(res, 404, { ok: false, error: 'not found' });
-                    return;
-                }
                 let body = {};
-                const method = (req.method ?? 'GET').toUpperCase();
                 if (method !== 'GET' && method !== 'HEAD') {
                     try {
                         body = await readJson(req);

package/lib/channels/dingtalk.d.ts

@@ -0,0 +1,186 @@
+import type { ChatAddress } from '../engine/router.js';
+import type { ChannelAdapter, ChannelCaps, ChannelDiagnosisCheck, MessageListener, OutboundFile, Receipt, ReplyStream, SemanticMessage } from './types.js';
+interface WSLike {
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: string, cb: (event: any) => void): void;
+    readyState: number;
+}
+type WSFactory = (url: string) => WSLike;
+type FetchResponseLike = {
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    arrayBuffer?(): Promise<ArrayBuffer>;
+};
+type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+    signal?: AbortSignal;
+}) => Promise<FetchResponseLike>;
+export interface DingtalkAdapterOptions {
+    clientId: string;
+    clientSecret: string;
+    /** 覆盖 REST 基址（测试注入/专有云代理）。 */
+    apiBase?: string;
+    /** 覆盖 oapi 基址（素材上传面，测试注入用）。 */
+    oapiBase?: string;
+    /** AI 卡片模板 ID；缺位=不启卡片档（文本档）。 */
+    cardTemplateId?: string;
+    /** 卡片流式变量名（以模板定义为准，默认 content）。 */
+    cardTemplateKey?: string;
+    /** 流式档位：card=AI Card 优先（默认，需 cardTemplateId）/text=纯文本。 */
+    cardMode?: 'card' | 'text';
+    /** 机器人编码；文档口径企业内部应用即 AppKey（=clientId）。 */
+    robotCode?: string;
+    WebSocketImpl?: WSFactory;
+    fetchImpl?: FetchLike;
+    requestTimeoutMs?: number;
+    idleReconnectMs?: number;
+    /** 卡片流式帧间隔（默认 1100ms，避开群 webhook ~20 条/分钟量级；测试可置 0）。 */
+    streamThrottleMs?: number;
+    logger?: (msg: string) => void;
+}
+/** HTTP 4xx / errcode·code 明确拒绝 = 确定性失败（服务端未投递，可安全告知）。 */
+export declare class DingTalkApiError extends Error {
+    /** 平台错误码或 HTTP 状态字符串（判型/日志用，不进用户可见文案）。 */
+    readonly code: string;
+    constructor(message: string, 
+    /** 平台错误码或 HTTP 状态字符串（判型/日志用，不进用户可见文案）。 */
+    code: string);
+}
+/** 结果不明（网络错/超时/5xx/断连）——D7：禁自动重发。 */
+export declare class DingTalkUncertainError extends Error {
+}
+export declare class DingtalkAdapter implements ChannelAdapter {
+    readonly id = "dingtalk";
+    readonly label = "\u9489\u9489";
+    readonly caps: ChannelCaps;
+    connected: boolean;
+    /** 卡片面确定性失败后置位：本实例不再尝试卡片（内部退化文本档）。 */
+    cardDisabled: boolean;
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly apiBase;
+    private readonly oapiBase;
+    private readonly cardTemplateId;
+    private readonly cardTemplateKey;
+    private readonly cardMode;
+    private readonly robotCodeConfigured;
+    private readonly wsFactory;
+    private readonly fetchImpl;
+    private readonly requestTimeoutMs;
+    private readonly idleReconnectMs;
+    private readonly streamThrottleMs;
+    private readonly log;
+    private ws;
+    private listeners;
+    private tokenCache;
+    private observedRobotCode;
+    /** msgId 排重（事件面可能重放）。 */
+    private readonly seenMsgIds;
+    /** kind:chatId → 回调自带 sessionWebhook（回复首选面，带过期时间）。 */
+    private readonly webhookByChat;
+    /** kind:chatId → 发送者 userId（batchSend 主动推送用）。 */
+    private readonly userIdByChat;
+    /** kind:chatId → conversationId（群侧推送 openConversationId 候选）。 */
+    private readonly conversationIdByChat;
+    private idleTimer;
+    private reconnectTimer;
+    private lastInboundAt;
+    private backoffMs;
+    private stopping;
+    constructor(options: DingtalkAdapterOptions);
+    /** 卡片档是否可用（未配模板/显式 text 档/已确定性失败 → 否）。 */
+    private get cardEnabled();
+    private get robotCode();
+    connect(signal?: AbortSignal): Promise<void>;
+    /** 注册 ticket→建连。ticket 90s 单次有效，故每次建连都重新注册。 */
+    private openOnce;
+    /** POST /v1.0/gateway/connections/open → {endpoint, ticket}。 */
+    private openGatewayTicket;
+    disconnect(): Promise<void>;
+    /** close 后自动重连（指数退避）；主动 disconnect/拆除期不重连。 */
+    private scheduleReconnect;
+    private startIdleWatchdog;
+    private stopIdleWatchdog;
+    onMessage(listener: MessageListener): () => void;
+    private handleFrame;
+    /** 回一帧 ACK（messageId 必须与推送一致；发送失败只记日志，不改判业务）。 */
+    private ack;
+    private parseData;
+    /** 回调 payload → 上下文登记 + 排重 + 归一（导出 normalize 供单测直验）。 */
+    private handleCallback;
+    /**
+     * 机器人回调 payload → SemanticMessage。
+     * conversationType '2'→group（chatId=conversationId）/'1'→dm（chatId=senderStaffId）；
+     * 机器人自发回声丢弃；非文本类型给占位文案不丢事件（与飞书同纪律）。
+     */
+    normalize(payload: Record<string, any>): SemanticMessage | undefined;
+    /** 富文本片段 → 线性文本（图片位以占位标注，不丢事件）。 */
+    private richTextToText;
+    /**
+     * 回复：回调自带 sessionWebhook 优先（无需 token）；无上下文/已过期 →
+     * 机器人主动推送面（batchSend / groupMessages.send）。
+     * markdown 优先，格式类拒绝回退纯文本（回退链同 telegram 思路）。
+     */
+    reply(address: ChatAddress, text: string, signal?: AbortSignal): Promise<Receipt>;
+    private replyViaWebhook;
+    /** webhook POST：响应 {errcode,errmsg}；errcode=0 即成功。 */
+    private postWebhook;
+    /** 主动推送面（v1.0 机器人接口，需 accessToken）。 */
+    private replyViaRobotSend;
+    private robotSend;
+    /**
+     * 出站文件（公开面两步，均已核实）：
+     * 1) POST {oapiBase}/media/upload?access_token=…&type=file，multipart/form-data
+     *    字段名固定 media → { media_id }（普通文件 ≤20MB、3 天有效）
+     * 2) 机器人推送 msgKey='sampleFile'，msgParam=JSON {mediaId, fileName, fileType}
+     *    ——文档：机器人发送消息类型 types-of-messages-sent-by-robots
+     * 注：协议只支持企业内部应用/第三方企业应用机器人（本适配器即此档）；
+     * webhook 自定义机器人无文件外发公开面。
+     * 判型沿用文本面：errcode≠0/4xx = 确定性 DingTalkApiError；超时/传输失败 = DingTalkUncertainError（D7）。
+     */
+    sendFile(address: ChatAddress, file: OutboundFile, signal?: AbortSignal): Promise<Receipt>;
+    /** 素材上传 multipart：oapi 口径 errcode≠0 / 非 2xx = 确定性；传输失败 = uncertain（不重传）。 */
+    private uploadMedia;
+    /**
+     * 下载码 → 临时链接 → 取字节。
+     * 文档：下载机器人接收消息的文件内容
+     * https://open.dingtalk.com/document/development/download-the-file-content-of-the-robot-receiving-message
+     * 任何失败均降级：保留占位文案加说明，不抛不丢消息（入站面无 Receipt 语义）。
+     */
+    private fillFile;
+    /**
+     * AI Card 流式：createAndDeliver 起卡 → PUT /v1.0/card/streaming 逐帧全量
+     * （isFull=true，markdown 变量硬性要求；guid 每帧唯一做幂等标志）→
+     * finish 帧 isFinalize=true（卡片状态机自动切「完成」档）。
+     */
+    beginStream(address: ChatAddress, signal?: AbortSignal): Promise<ReplyStream>;
+    /** 文本档流式：中间快照无可编辑承载面，只缓存；收轮一次性 reply。 */
+    private textStream;
+    private createAndDeliverCard;
+    private streamUpdate;
+    /** accessToken 自管（expireIn 7200s，提前 60s 刷新；文档要求按应用维度缓存）。 */
+    private accessToken;
+    /** v1.0 接口调用：token 头 + 错误分级（4xx/code 确定性，5xx/网络 uncertain）。 */
+    private restV1;
+    /**
+     * POST JSON 底座：返回 {status, body}。
+     * 网络异常/超时/HTTP 5xx → DingTalkUncertainError（D7 禁重发）；
+     * HTTP 4xx 与业务码由调用方判确定性拒绝。
+     */
+    private send;
+    /** 渠道内不裁决准入：白名单在网关（红线 D6），恒交全局。 */
+    authorize(): boolean | undefined;
+    /** 诊断三态：credentials 实探（换 token）；roundtrip 恒 unverified；零 secret 回显。 */
+    diagnose(signal?: AbortSignal): Promise<ChannelDiagnosisCheck[]>;
+}
+/** 工厂挂 registry（secrets 取 meta 里的钉钉字段名 clientId/clientSecret；config 可含 apiBase 覆盖）。 */
+export declare function createDingtalkAdapter(options: {
+    accountId: string;
+    config: Record<string, string>;
+    secrets: Record<string, string | undefined>;
+}): DingtalkAdapter;
+export {};