@lijian-ui/dsh-im-gateway 0.1.0 → 0.2.0

package/README.en.md

@@ -0,0 +1,297 @@
+# @lijian-ui/dsh-im-gateway
+
+English | [简体中文](./README.md)
+
+> A multi-channel IM gateway plugin for **DeepSeek Harness (dsh)** — connect DingTalk, QQ and WeChat (iLink) bots to your harness agent, with QR-scan binding, streaming replies, tool approval, interactive questions, long-text splitting, multi-segment merge, and bilingual UI.
+
+[![npm version](https://img.shields.io/npm/v/@lijian-ui/dsh-im-gateway)](https://www.npmjs.com/package/@lijian-ui/dsh-im-gateway)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+---
+
+## Features
+
+### Channels & Core
+
+- **Unified gateway service** — one plugin, three channels. Every channel routes through a single `ctx.imGateway` core: session management, slash commands, streaming, status broadcast.
+- **DingTalk** — outbound WebSocket stream connection, group + single chats, @-mention filtering, **AI card streaming** (real-time incremental replies), slash commands.
+- **QQ** — WebSocket gateway (official `qqbot-nodejs` SDK), private (c2c) + group chats, **QR-scan bot binding** (no manual console setup), **streaming messages** (c2c).
+- **WeChat (iLink)** — official iLink long-poll protocol, **QR-scan login + pairing code**, single-chat only, media (AES-128-ECB CDN) in/out.
+- **Multi-bot instances** — the same channel type can appear many times (e.g. two DingTalk bots), each with its own credentials.
+- **Settings UI** — a full web settings page ("IM 通道") rendered inside the official dsh web UI; QR-scan binding happens right there.
+- **Streaming replies** — DingTalk AI Card, QQ stream_messages; plain-text fallback when a channel doesn't support streaming.
+- **Instance lock** — file-based `DSH_HOME` lock prevents multiple instances from corrupting the session log.
+
+### Interaction Enhancements
+
+- **Tool approval bridge** — when the agent calls a tool requiring approval, reply "approve" or "reject" directly in IM; timeout falls back to dsh's native approval system.
+- **Interactive question bridge** — when the agent calls `ask_user_question`, the question is pushed to IM; reply with option numbers/text to answer. Races against the Web UI — first answer wins.
+- **Long reply splitting** — replies exceeding the channel's single-message limit are auto-split at sentence boundaries with `（1/3）` segment prefixes, sent as separate messages.
+- **Multi-segment input merge** — consecutive messages are auto-merged into one (configurable timeout window); use `..` to continue merging, `!!` to submit immediately.
+- **File-sending tool** — the agent can call `im_send_file` to send workspace files (images/videos/documents) directly to the current IM session.
+- **Bilingual UI** — set `language: 'zh' | 'en'` to switch all user-visible replies between Chinese and English.
+
+### Session Management
+
+- **Built-in slash commands** — `/help`, `/model`, `/status`, `/new`, `/reset`, `/stop`, `/sessions`, `/continue`, `/workspaces`, `/workspace` (see below).
+- **Session list & continue** — `/sessions` lists recent sessions (with titles); `/continue <id>` resumes a specific session.
+- **Workspace management** — `/workspaces` lists all workspaces with session counts; `/workspace <path>` switches workspace (resets the current session; next message creates a new session in the new workspace).
+- **User allowlist** — configure `allowAllUsers` or `allowedUserIds` to control who can use the bot.
+
+---
+
+## Installation
+
+Requires DeepSeek Harness (dsh) — the plugin is a standard **dsh bundle** and installs through the official plugin channel.
+
+### From npm (recommended)
+
+```bash
+dsh plugin --profile web add @lijian-ui/dsh-im-gateway
+```
+
+The npm package ships pre-built `lib/` — **no build authorization needed** (`allowBuilds` is not required).
+
+### From tarball
+
+```bash
+npm pack @lijian-ui/dsh-im-gateway
+dsh plugin --profile web add ./dsh-im-gateway-0.1.1.tgz
+```
+
+### From GitHub
+
+```bash
+dsh plugin --profile web add github:lijian-ui/dsh-im-gateway
+```
+
+> Git installs fetch **source**, so the first install requires approving the package's `prepare` build script (pnpm ≥ 10). Add the package key to the profile's `pnpm-workspace.yaml` → `allowBuilds` when prompted. Prefer npm/tarball to skip this.
+
+### Verify installation
+
+```bash
+dsh --profile web --dump-config     # should show a "# == @lijian-ui/dsh-im-gateway" config layer
+dsh --profile web                   # open Settings → "IM 通道" in the browser
+```
+
+---
+
+## Quick Start
+
+1. Open the dsh web UI → **Settings → IM 通道**.
+2. Click **添加通道** (Add channel).
+3. Pick a channel type:
+   - **QQ**: click **扫码登录** → scan with mobile QQ → credentials auto-fill → save.
+   - **个人微信** (WeChat): click **扫码登录** → scan with mobile WeChat → (enter the pairing code if asked) → credentials auto-fill → save.
+   - **钉钉** (DingTalk): fill in AppKey / AppSecret manually (or edit the config file) → save.
+4. Message your bot from the IM client — replies stream back in real time.
+
+> Config is stored under `~/.dsh/settings.yaml` (`im-gateway.channels`). Saving from the UI **hot-reloads** the channels (no restart needed).
+
+---
+
+## Slash Commands
+
+Sent to the bot in any IM channel:
+
+| Command | Description |
+| --- | --- |
+| `/help` | List available commands |
+| `/model` | List models with emoji numbers; `/model 1` or `/model <name>` to switch (no session yet → sets default for next conversation) |
+| `/status` | Channel / cwd / current model / agent state |
+| `/new` `/reset` `/clear` | Start a fresh conversation |
+| `/stop` | Abort the current reply |
+| `/sessions` | List the 10 most recent sessions (current session marked, with titles) |
+| `/continue <session-id>` | Continue a specific session (use `/sessions` for IDs) |
+| `/workspaces` | List all workspaces (sorted by recent activity, with session counts) |
+| `/workspace <path>` | Switch to the specified workspace (resets current session; next message creates a new session in the new workspace) |
+| `/workspace` | Without arguments, same as `/workspaces` |
+
+### Multi-segment Input Suffixes
+
+| Suffix | Effect |
+| --- | --- |
+| (none) | Enters the merge window, waits for more messages (auto-submits after 3s by default) |
+| `..` | Continue merging: add this message to the buffer, keep waiting |
+| `!!` | Submit now: merge the buffer + this message and send to the agent immediately |
+
+### Approval Replies
+
+When the agent calls a tool that requires approval, reply directly:
+
+| Reply | Effect |
+| --- | --- |
+| `approve` / `yes` / `y` / `allow` | Allow the tool execution |
+| `reject` / `no` / `n` / `deny` | Block the tool execution |
+
+(Chinese equivalents: `批准` / `同意` for approve, `拒绝` for reject.)
+
+After timeout, the request falls back to dsh's native approval system.
+
+---
+
+## Configuration
+
+Everything is editable from the settings UI; the underlying schema lives in `~/.dsh/settings.yaml`:
+
+```yaml
+im-gateway:
+  language: zh                    # UI language: zh (Chinese) | en (English)
+  approvalTimeoutSecs: 120        # Tool approval timeout (seconds)
+  questionTimeoutSecs: 600        # Interactive question timeout (seconds)
+  mergeTimeoutSecs: 3             # Multi-segment input merge window (seconds)
+  allowAllUsers: false            # Allow all users (dev only)
+  allowedUserIds:                 # Allowlist: { channelId: string[] } or use '*' for any channel
+    "*":
+      - user-abc
+  channels:
+    - id: dingtalk-main
+      type: dingtalk
+      name: 主机器人
+      enabled: true
+      config:
+        clientId: "..."
+        clientSecret: "..."
+        # callbackBaseUrl, appId, botAppId, baseUrl, botId, cdnBaseUrl, pollIntervalMs...
+```
+
+### Gateway-level Config
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `language` | `zh` | UI language (`zh` Chinese / `en` English); affects all user-visible replies |
+| `streamThrottleMs` | `800` | Throttle interval for streaming pushes (ms) |
+| `slashCommands` | `true` | Enable slash commands |
+| `approvalTimeoutSecs` | `120` | Tool approval IM wait timeout (seconds); falls back to dsh native approval on timeout |
+| `questionTimeoutSecs` | `600` | Interactive question IM wait timeout (seconds); falls back to Web UI on timeout |
+| `mergeTimeoutSecs` | `3` | Multi-segment input merge window (seconds); consecutive messages merged into one |
+| `allowAllUsers` | `false` | Allow all users (dev only; do not enable in production) |
+| `allowedUserIds` | `{}` | Allowlist; key is channelId (`*` matches any), value is array of user IDs |
+
+### Channel-level Config
+
+| Field | Applies to | Meaning |
+| --- | --- | --- |
+| `clientId` / `clientSecret` | dingtalk | DingTalk app key / secret (Stream mode) |
+| `appId` / `clientSecret` | qq | QQ Open Platform credentials (QR-bound) |
+| `token` / `botId` / `baseUrl` / `cdnBaseUrl` | weixin | iLink credentials (QR-bound) |
+| `enabled` | all | Whether this instance connects |
+
+---
+
+## Architecture
+
+```
+IM client ──► channel adapter (dingtalk / qq / weixin)
+                    │  ImInboundMessage
+                    ▼
+              ctx.imGateway (core)
+                    │  multi-segment merge → allowlist check → approval/question intercept → slash commands
+                    │  ensureSession → agent.followup
+                    ▼
+             dsh harness agent (LLM loop)
+                    │  session events (turn/start, assistant/chunk, tool/call, turn/end)
+                    ▼
+         EventDispatcher → streaming reply / splitting / tool hints
+                    │  (AI Card / stream_messages / plain text fallback)
+                    ▼
+                 IM client
+```
+
+### Module Structure
+
+| Module | Responsibility |
+| --- | --- |
+| `im-gateway.ts` | Core service ImGatewayService: session management, message routing, tool registration |
+| `events.ts` | EventDispatcher: SessionEvent → IM channel operations (streaming, splitting, tool hints) |
+| `commands.ts` | CommandHandler: slash commands (/help /reset /model /status /stop /sessions /continue /workspaces /workspace) |
+| `stream.ts` | StreamThrottle: batch text-delta and push at intervals |
+| `approval.ts` | ApprovalBroker: tool approval bridge, holds approval/request pending IM reply |
+| `questions.ts` | QuestionBroker: interactive question bridge, holds ask_user_question pending IM reply |
+| `split.ts` | splitText: long-text splitting at sentence boundaries with segment prefixes |
+| `merge.ts` | SessionMerger: multi-segment input merge, supports `..` / `!!` control suffixes |
+| `i18n.ts` | Translator: Chinese/English bilingual translation table |
+| `instance-lock.ts` | acquireInstanceLock: DSH_HOME file lock, prevents concurrent session log corruption |
+| `types.ts` | Interface definitions: ImChannelAdapter, ImGatewayConfig, ImGateway, etc. |
+
+- **Host half** (node): `src/index.ts` (apply), `src/gateway/` (core + above modules), `src/channels/` (dingtalk / qq / weixin + protocol helpers), `src/remote.ts` (Typert RPC for the settings UI), `src/sync.ts` (channel reload on config save).
+- **Client half** (browser): `src/client/` — settings page "IM 通道" (add/edit modal + QR-scan login + status dots).
+- **Multi-bot**: `channels` is an array; the same `type` may appear multiple times.
+
+### Extension Points
+
+Third parties can register their own channel without forking:
+
+```ts
+import { ImChannelAdapter } from '@lijian-ui/dsh-im-gateway'   // peerDependency on the core
+
+class MyChannelAdapter implements ImChannelAdapter { /* ... */ }
+ctx.imGateway.registerChannel(myAdapter)
+```
+
+`ImChannelAdapter` interface optional methods:
+
+| Method | Description |
+| --- | --- |
+| `sendText(convId, text)` | **Required**. Send a plain-text message |
+| `sendMedia(convId, filePath, caption?)` | Optional. Send a file/image/video (used by im_send_file tool) |
+| `beginStream(convId)` | Optional. Open a streaming reply (called on first text delta) |
+| `streamText(convId, text)` | Optional. Streaming overwrite update (throttled) |
+| `endStream(convId, fullText)` | Optional. Close a streaming reply (called on turn/end) |
+| `updateCard(convId, text)` | Optional. Legacy single-shot card update |
+| `authorizes(userId)` | Optional. Channel-local authorization check (return false to block) |
+| `maxMessageChars` | Optional. Max chars per message (default 4000, used for splitting) |
+| `label` | Optional. Channel display name (used in question receipts) |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/lijian-ui/dsh-im-gateway.git
+cd dsh-im-gateway
+npm install
+npm run build          # tsdown → lib/
+npm run watch          # rebuild on save
+npm run typecheck
+npm test               # node --test tests/*.test.mjs
+```
+
+Local link into a dsh profile:
+
+```bash
+dsh plugin --profile web add ./   # install from this directory (link)
+```
+
+> **Windows note**: the dsh subprocess loads `lib/index.js` from `package.json` `main` — after editing `src/`, always `npm run build` then restart the dsh process (its require cache keeps the old module).
+
+### Tests
+
+Tests use Node.js's built-in test runner (`node:test`), in the `tests/` directory:
+
+| Test file | Module covered | Tests |
+| --- | --- | --- |
+| `approval.test.mjs` | ApprovalBroker | 8 |
+| `questions.test.mjs` | QuestionBroker + parseQuestionReply + formatQuestionPrompt | 8 |
+| `split.test.mjs` | splitText | 8 |
+| `merge.test.mjs` | SessionMerger + stripControlSuffix | 9 |
+
+---
+
+## Troubleshooting
+
+- **No logs from the plugin** — cordis buffers `ctx.logger.*` in memory by default. The plugin registers a console exporter on apply, so logs appear in the dsh subprocess stderr (desktop shells prefix them with `[dsh]`).
+- **QQ client shows "连接中" (connecting) forever** — streaming was opened too early or never closed. This plugin opens the stream on the first assistant text delta and always closes it on `turn/end` (fixed in 0.1.x).
+- **Chat works but replies are not streaming** — the channel fell back to plain text (e.g. QQ group chats don't support `stream_messages`; WeChat has no streaming concept). This is by design.
+- **Replies split into multiple messages** — auto-splitting kicks in when text exceeds the channel's `maxMessageChars` limit, with `（1/3）` prefixes. This is by design, not a bug.
+- **Multiple messages got merged** — consecutive messages within the 3s merge window are combined into one. Send `!!` to submit immediately, or increase `mergeTimeoutSecs`.
+- **Approval/question timed out** — increase `approvalTimeoutSecs` / `questionTimeoutSecs`. On timeout, the request automatically falls back to the Web UI.
+- **Some text still in Chinese after switching to English** — separators in `formatAnswerSummary` (`、` `；`) and `（空）` are intentionally fixed as they are format symbols, not natural language.
+
+---
+
+## License
+
+MIT © lijian-ui
+
+Built for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — independent plugin, not affiliated with or endorsed by DeepSeek.