@lijian-ui/dsh-im-gateway 0.1.0

package/lib/index-2mMnMMFx.d.ts

@@ -0,0 +1,304 @@
+import { Context, Context as Context$1, Service } from "@deepseek-ai/cordis";
+import Schema from "@deepseek-ai/schemastery";
+import * as _deepseek_ai_cosmokit0 from "@deepseek-ai/cosmokit";
+
+//#region src/gateway/types.d.ts
+/** An attached image. `data` is raw base64 WITHOUT the `data:` prefix. */
+interface ImImage {
+  mediaType: string;
+  data: string;
+}
+/** A normalized inbound message coming from any channel. */
+interface ImInboundMessage {
+  /** Channel id, e.g. 'dingtalk'. Must match the adapter's `id`. */
+  channelId: string;
+  /** Channel-specific conversation / chat id. */
+  conversationId: string;
+  /** End-user id inside the channel. */
+  userId: string;
+  /** Text body (slash-command prefixes are still present here; the gateway strips them). */
+  text: string;
+  /** Attached images, if any. */
+  images?: ImImage[];
+  /** Display name of the sender (group chats) — used to attribute who spoke. */
+  senderNick?: string;
+  /** Whether the inbound arrived in a group conversation. */
+  isGroup?: boolean;
+}
+/** Runtime status of a channel connection, surfaced to the settings UI. */
+interface ChannelStatus {
+  /** Connection state. */
+  status: 'online' | 'offline' | 'error';
+  /** Present when `status === 'error'`. */
+  error?: string;
+  /** Epoch ms of the last state change. */
+  lastChange: number;
+}
+/**
+ * A channel adapter. Each IM backend (DingTalk / QQ / Weixin) implements this
+ * and registers itself via `ctx.imGateway.registerChannel(adapter)`.
+ *
+ * Lifecycle: the gateway calls `start()` once the core service is active and
+ * `stop()` on teardown. The adapter pushes inbound messages back through
+ * `ctx.imGateway.handleInbound(message)`.
+ */
+interface ImChannelAdapter {
+  /** Stable channel id (e.g. 'dingtalk'). Used as the registry key and in session mapping. */
+  readonly id: string;
+  /** Human-readable label for logs / settings UI. */
+  readonly label: string;
+  /** Connect to the backend (open WS / start polling). */
+  start(): Promise<void> | void;
+  /** Disconnect and release resources. */
+  stop(): Promise<void> | void;
+  /** Push a text reply to a conversation. */
+  sendText(conversationId: string, text: string): Promise<void>;
+  /** Push an image reply. Optional — channels without media support may omit. */
+  sendImage?(conversationId: string, image: ImImage): Promise<void>;
+  /** Whether the adapter is currently connected. */
+  isActive(): boolean;
+  /**
+   * Optional streaming hook. The gateway calls this with incremental text
+   * (throttled by `streamThrottleMs`) so card-based channels (DingTalk) can
+   * update an AI card instead of sending discrete messages. Channels without
+   * this hook receive the full reply via `sendText` on `turn/end`.
+   */
+  updateCard?(conversationId: string, partialText: string): Promise<void>;
+  /**
+   * Optional AI-card streaming lifecycle — the richer sibling of `updateCard`.
+   * A channel that implements these three methods gets a full streaming card:
+   *   beginStream (create + deliver the card, once per reply cycle)
+   *   streamText  (incremental content updates, throttled by the gateway)
+   *   endStream   (finalize FINISHED; must be called even with no text)
+   * Channels without them fall back to a single `sendText` at `turn/end`.
+   */
+  beginStream?(conversationId: string): Promise<void>;
+  streamText?(conversationId: string, text: string, finished?: boolean): Promise<void>;
+  endStream?(conversationId: string, text: string): Promise<void>;
+  /**
+   * Optional pre-filter. Called by the gateway for every inbound message
+   * BEFORE it is forwarded to the agent. Return `true` to suppress forwarding
+   * (e.g. the message was a slash command handled locally).
+   */
+  onInbound?(message: ImInboundMessage): boolean | Promise<boolean>;
+  /**
+   * Optional status sink. The gateway assigns this on registration; the adapter
+   * must call it whenever its connection state changes (connected / closed /
+   * error) so the settings page can render online / offline / error badges.
+   */
+  statusListener?(status: ChannelStatus): void;
+}
+/** DingTalk channel credentials (per instance). */
+interface DingtalkChannelConfig {
+  clientId: string;
+  clientSecret: string;
+  callbackBaseUrl: string;
+}
+/** QQ channel credentials (per instance). */
+interface QqChannelConfig {
+  appId: string;
+  clientSecret: string;
+  botAppId: string;
+}
+/** 微信(iLink) channel credentials (per instance). */
+interface WeixinChannelConfig {
+  /** iLink bot token — obtained via QR scan login (weixin-login.ts). */
+  token: string;
+  /** iLink bot id — obtained via QR scan login (weixin-login.ts). */
+  botId: string;
+  /** API base URL (defaults to https://ilinkai.weixin.qq.com). */
+  baseUrl: string;
+  /** CDN base URL for media download/upload (defaults to https://cdn.ilinkai.weixin.qq.com). */
+  cdnBaseUrl: string;
+  pollIntervalMs: number;
+}
+/**
+ * One IM robot instance. The same channel TYPE may appear many times — e.g.
+ * two DingTalk bots with different credentials — each with its own unique
+ * `id` (e.g. `dingtalk-main`, `qq-7f3a`). `id` MUST NOT contain ':' because
+ * the gateway builds `convKey = channelId:conversationId`.
+ */
+type ChannelType = 'dingtalk' | 'qq' | 'weixin';
+interface ImChannelInstance {
+  /** Unique instance id, `<type>-<slug>` — used as the adapter registry key. */
+  id: string;
+  /** Channel type (drives which adapter class + which credential fields). */
+  type: ChannelType;
+  /** Human-readable display name (e.g. '主机器人'). */
+  name: string;
+  enabled: boolean;
+  /** Credential fields for this instance (shape depends on `type`). */
+  config: DingtalkChannelConfig & Partial<QqChannelConfig> & Partial<WeixinChannelConfig>;
+}
+interface ImGatewayConfig {
+  /** Working directory passed to host sessions created for IM conversations. */
+  cwd: string;
+  /** Throttle (ms) for incremental `updateCard` pushes. Ignored when a channel has no `updateCard`. */
+  streamThrottleMs: number;
+  /** Enable built-in slash commands (/help, /reset, /clear). */
+  slashCommands: boolean;
+  /** All channel instances. Only `enabled` ones connect out. Empty by default. */
+  channels: ImChannelInstance[];
+}
+/** Public surface of the gateway service, exposed as `ctx.imGateway`. */
+interface ImGateway {
+  registerChannel(adapter: ImChannelAdapter): void;
+  getChannel(id: string): ImChannelAdapter | undefined;
+  listChannels(): string[];
+  /** Entry point channel adapters call for every inbound user message. */
+  handleInbound(message: ImInboundMessage): Promise<void>;
+  /** Snapshot of every channel's runtime status (for the settings UI). */
+  getChannelStatuses(): Record<string, ChannelStatus>;
+}
+sideEffect();
+
+//#endregion
+//#region src/gateway/im-gateway.d.ts
+declare const Config: Schema<Schemastery.ObjectS<{
+  cwd: Schema<string, string>;
+  streamThrottleMs: Schema<number, number>;
+  slashCommands: Schema<boolean, boolean>;
+  channels: Schema<({
+    id?: string | null | undefined;
+    type?: "dingtalk" | "qq" | "weixin" | null | undefined;
+    name?: string | null | undefined;
+    enabled?: boolean | null | undefined;
+    config?: ({
+      clientId?: string | null | undefined;
+      clientSecret?: string | null | undefined;
+      callbackBaseUrl?: string | null | undefined;
+      appId?: string | null | undefined;
+      botAppId?: string | null | undefined;
+      baseUrl?: string | null | undefined;
+      token?: string | null | undefined;
+      botId?: string | null | undefined;
+      cdnBaseUrl?: string | null | undefined;
+      pollIntervalMs?: number | null | undefined;
+    } & _deepseek_ai_cosmokit0.Dict) | null | undefined;
+  } & _deepseek_ai_cosmokit0.Dict)[], Schemastery.ObjectT<{
+    id: Schema<string, string>;
+    type: Schema<"dingtalk" | "qq" | "weixin", "dingtalk" | "qq" | "weixin">;
+    name: Schema<string, string>;
+    enabled: Schema<boolean, boolean>;
+    config: Schema<Schemastery.ObjectS<{
+      clientId: Schema<string, string>;
+      clientSecret: Schema<string, string>;
+      callbackBaseUrl: Schema<string, string>;
+      appId: Schema<string, string>;
+      botAppId: Schema<string, string>;
+      baseUrl: Schema<string, string>;
+      token: Schema<string, string>;
+      botId: Schema<string, string>;
+      cdnBaseUrl: Schema<string, string>;
+      pollIntervalMs: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+      clientId: Schema<string, string>;
+      clientSecret: Schema<string, string>;
+      callbackBaseUrl: Schema<string, string>;
+      appId: Schema<string, string>;
+      botAppId: Schema<string, string>;
+      baseUrl: Schema<string, string>;
+      token: Schema<string, string>;
+      botId: Schema<string, string>;
+      cdnBaseUrl: Schema<string, string>;
+      pollIntervalMs: Schema<number, number>;
+    }>>;
+  }>[]>;
+}>, Schemastery.ObjectT<{
+  cwd: Schema<string, string>;
+  streamThrottleMs: Schema<number, number>;
+  slashCommands: Schema<boolean, boolean>;
+  channels: Schema<({
+    id?: string | null | undefined;
+    type?: "dingtalk" | "qq" | "weixin" | null | undefined;
+    name?: string | null | undefined;
+    enabled?: boolean | null | undefined;
+    config?: ({
+      clientId?: string | null | undefined;
+      clientSecret?: string | null | undefined;
+      callbackBaseUrl?: string | null | undefined;
+      appId?: string | null | undefined;
+      botAppId?: string | null | undefined;
+      baseUrl?: string | null | undefined;
+      token?: string | null | undefined;
+      botId?: string | null | undefined;
+      cdnBaseUrl?: string | null | undefined;
+      pollIntervalMs?: number | null | undefined;
+    } & _deepseek_ai_cosmokit0.Dict) | null | undefined;
+  } & _deepseek_ai_cosmokit0.Dict)[], Schemastery.ObjectT<{
+    id: Schema<string, string>;
+    type: Schema<"dingtalk" | "qq" | "weixin", "dingtalk" | "qq" | "weixin">;
+    name: Schema<string, string>;
+    enabled: Schema<boolean, boolean>;
+    config: Schema<Schemastery.ObjectS<{
+      clientId: Schema<string, string>;
+      clientSecret: Schema<string, string>;
+      callbackBaseUrl: Schema<string, string>;
+      appId: Schema<string, string>;
+      botAppId: Schema<string, string>;
+      baseUrl: Schema<string, string>;
+      token: Schema<string, string>;
+      botId: Schema<string, string>;
+      cdnBaseUrl: Schema<string, string>;
+      pollIntervalMs: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+      clientId: Schema<string, string>;
+      clientSecret: Schema<string, string>;
+      callbackBaseUrl: Schema<string, string>;
+      appId: Schema<string, string>;
+      botAppId: Schema<string, string>;
+      baseUrl: Schema<string, string>;
+      token: Schema<string, string>;
+      botId: Schema<string, string>;
+      cdnBaseUrl: Schema<string, string>;
+      pollIntervalMs: Schema<number, number>;
+    }>>;
+  }>[]>;
+}>>;
+/**
+ * Core IM gateway service.
+ *
+ * Responsibilities (ported from pi-desk-top/src/main/im/im-gateway.ts):
+ *  - channel registry (`registerChannel`)
+ *  - conversation → host session mapping
+ *  - per-conversation serial queue (one agent turn at a time)
+ *  - slash-command handling (/help, /reset, /clear)
+ *  - agent-event → channel reply routing (streaming, tool notifications, flush)
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * HOST API CONTRACT (verified against deepseek-harness source):
+ *  - Sessions:  `ctx.sessions` is the `SessionStore` (from @deepseek-ai/dsh-session).
+ *               `create(id, { meta: { cwd } })` builds an event-sourced Session.
+ *               The Session object has NO `.prompt()` / `.on()` — it is a log.
+ *  - Agents:    `ctx.agents` is the `AgentRegistry` (from @deepseek-ai/dsh-agent).
+ *               `get(sessionId)` → Agent | undefined; `createAgent(ownerCtx, opts)`
+ *               starts the agent loop on a session. Drive a turn with
+ *               `agent.followup(userMessage)` (see host/apiproxy/src/api-proxy.ts:2461).
+ *  - Events:    subscribe at the CONTEXT level: `ctx.on('session/event', (session, event) => …)`.
+ *               Typed events (packages/core/session/src/types.ts):
+ *                 'turn/start'        { turn }
+ *                 'assistant/chunk'   { turn, step, chunk: StreamChunk }  // chunk.type==='text-delta' → text
+ *                 'assistant/message' { turn, step, message: AssistantMessage }
+ *                 'tool/call'         { turn, step, callId, name, arguments }
+ *                 'turn/end'          { turn, reason }
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+//#endregion
+//#region src/index.d.ts
+/**
+ * Plugin-level dependency declaration: the bundle waits for these host
+ * services before apply runs (mirrors the official dsh-skill-viewer host:
+ * `export const inject = ["typert", ...]`). `imGateway` (our own core
+ * service) is created inside apply and waited on via ctx.inject below.
+ */
+declare const inject: string[];
+/**
+ * Single-entry IM gateway bundle. One plugin (`@lijian-ui/dsh-im-gateway`) provides the
+ * core gateway service AND every channel (DingTalk / QQ / 个人微信) as
+ * INSTANCES: `config.channels` is an array, and the same channel type may
+ * appear multiple times (multi-bot support, mirroring pi-desk-top). Only
+ * `enabled` instances connect out.
+ */
+declare function apply(ctx: Context$1, config: ImGatewayConfig): void;
+//#endregion
+export { ChannelStatus, ChannelType, Config, type Context, DingtalkChannelConfig, ImChannelAdapter, ImChannelInstance, ImGateway, ImGatewayConfig, ImImage, ImInboundMessage, QqChannelConfig, WeixinChannelConfig, apply, inject };