@xmanrui/dsh-im 4.0.1 → 4.1.0

package/PROACTIVE_DELIVERY.en.md

@@ -0,0 +1,321 @@
+# Proactive Delivery Guide
+
+[简体中文](PROACTIVE_DELIVERY.md) · **English**
+
+Proactive delivery lets an application send a text message through a bot connected to DSH-IM without waiting for a new user message. The caller stores only a stable `botId + targetId` pair—never a Harness `sessionId`, chat reference, message ID, or temporary webhook.
+
+All nine built-in channels support proactive delivery: Weixin, Feishu, DingTalk, WeCom, QQ, Slack, Telegram, Discord, and WhatsApp.
+
+## Quick start
+
+1. Open **Settings → IM Bot** and find the bot that should send the message.
+2. Select the gear icon in the bot card's upper-right corner.
+3. Copy the **Bot ID** under **Call identifiers**.
+4. Select **New target**, then choose a known conversation or select **Enter manually (advanced)** and enter the platform-native ID.
+5. Review or enter the **Target ID**, target type, and native platform ID.
+6. Select **Test**. After the target receives `DSH-IM 主动投递测试成功。`, select **Save target**.
+7. Select **Copy call parameters** on the saved target and store the resulting `{ botId, targetId }` in the calling application.
+8. Send messages through HTTP POST, same-Host `ctx.dshIm.send()`, or the Connection RPC `message.send` endpoint.
+
+## Configure a delivery target
+
+### 1. Get the Bot ID
+
+`botId` is the real call identifier of the currently connected bot. Copy it from the settings page and treat it as an opaque string. Do not infer the channel from its prefix, and do not substitute the bot name, a platform App ID, or a masked ID from a card.
+
+Targets belong to this bot record. Removing a bot also removes its delivery targets. After connecting it again, copy its `botId` again and recreate the required targets.
+
+### 2. Create a target
+
+After selecting **New target**, the page opens a **Choose from conversations** dropdown:
+
+- Suggestions come from conversation mappings already persisted for this bot. They are neither a platform address book nor a complete, strictly time-ordered recent-chat list.
+- A suggestion contains only the target type and native platform ID required for delivery. It does not contain a Harness `sessionId`, message text, message ID, conversation name, or last-active time.
+- A target already configured in the dropdown is marked **Added** and disabled.
+- When the dropdown is empty, send the bot a message on that platform and select **Refresh**. If it still does not appear, use **Enter manually (advanced)**.
+
+Choosing a conversation only pre-fills a draft. It does not save anything automatically.
+
+### 3. Understand Target ID
+
+`targetId` is the stable alias you define for callers. It is not a platform user, group, or channel ID.
+
+- It must be unique only within one bot. Different bots may use the same `targetId`.
+- It may contain uppercase and lowercase letters, numbers, dots, underscores, colons, `@`, or hyphens, with a length of 1–128 characters.
+- New targets default to `tgt_` plus 16 random hexadecimal characters, such as `tgt_7f3a91c8d2e64b10`.
+- You may change it before the first save—for example, to `daily-report` or `release-alerts`.
+- After saving, `targetId` is read-only. You may still edit the name, target type, and native route while callers keep using the same `botId + targetId` pair.
+
+### 4. Test, save, and copy
+
+The **Test** button appears in conversation-filled drafts, manually entered drafts, and edit forms:
+
+- It is enabled only while the bot is online and every native ID required by the current target type is present.
+- It tests the target type and native ID currently shown in the form. It does not create, update, or save the target first.
+- Changing a tested native ID clears the old success result; test the new value again.
+- The **Test** button on a saved target row tests that target's currently saved route.
+- A successful test means the platform accepted the send request or its SDK returned success. It does not mean the message was read.
+
+After saving, **Copy call parameters** copies JSON in this shape:
+
+```json
+{
+  "botId": "bot_9577c8572d454122a4ef7fb4d8420a91",
+  "targetId": "release-alerts"
+}
+```
+
+### Configuration example: a Feishu alert group
+
+Assume the Feishu bot has already received a message in the alert group:
+
+1. Open that bot's settings page and copy its **Bot ID**.
+2. Select **New target**, then choose the alert group from the dropdown.
+3. Change the generated **Target ID** to `release-alerts` and set the display name to `Release alerts`.
+4. Confirm that the target type is **Group** and the group Chat ID is filled in.
+5. Select **Test** and confirm the test message in the Feishu group.
+6. Select **Save target**, then **Copy call parameters**.
+
+If the group Chat ID is edited later, callers can continue using the same `botId + release-alerts` pair.
+
+## Native fields for all nine channels
+
+Choose a known conversation whenever possible. Obtain and enter a platform-native ID manually only when the target is missing from the suggestions.
+
+| Channel | Target type | Required field | Example or note |
+| --- | --- | --- | --- |
+| Weixin | `user` | Weixin user ID (`toUserId`) | Enter the user ID that should receive messages |
+| Feishu | `user` | Open ID (`openId`) | For example, `ou_xxx` |
+| Feishu | `group` | Group Chat ID (`chatId`) | For example, `oc_xxx` |
+| DingTalk | `user` | User ID (`userId`) | Enter the DingTalk user ID |
+| DingTalk | `group` | Group Open Conversation ID (`openConversationId`) | Proactive delivery never uses a temporary `sessionWebhook` |
+| WeCom | `user` | User ID (route field: `chatId`) | Enter the user ID for a direct message |
+| WeCom | `group` | Group Chat ID (`chatId`) | Enter the group's `chatid` |
+| QQ | `user` | User Open ID (`userOpenId`) | The platform's `user_openid` |
+| QQ | `group` | Group Open ID (`groupOpenId`) | The platform's `group_openid` |
+| Slack | `conversation` | Channel ID (`channelId`) | For example, `C0123456789` |
+| Slack | `thread` | Channel ID + thread timestamp (`channelId`, `threadTs`) | For example, `1712345678.123456` |
+| Telegram | `chat` | Chat ID (`chatId`) | A decimal string, such as `-1001234567890` |
+| Telegram | `topic` | Chat ID + Topic ID (`chatId`, `messageThreadId`) | Topic ID must be a positive integer |
+| Discord | `channel` | Channel ID (`channelId`) | DMs, channels, and Threads all use a messageable Channel ID |
+| WhatsApp | `user` | User JID (`jid`) | For example, `8613800000000@s.whatsapp.net` |
+| WhatsApp | `group` | Group JID (`jid`) | For example, `1234567890-123456@g.us` |
+
+Native ID strings must be nonempty and have no leading or trailing whitespace. A target accepts only the fields required by the selected channel and type; extra fields are rejected.
+
+## Send through HTTP POST
+
+An ordinary external application can call the Host's proactive-delivery endpoint directly:
+
+```bash
+curl --request POST \
+  http://127.0.0.1:3080/api/dsh-im/delivery/messages \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "botId": "bot_9577c8572d454122a4ef7fb4d8420a91",
+    "targetId": "release-alerts",
+    "text": "The build has completed."
+  }'
+```
+
+A successful request returns:
+
+```json
+{ "sent": true }
+```
+
+The body accepts exactly `botId`, `targetId`, and `text`, with a maximum total JSON size of 1 MiB. Do not add a native platform route, `sessionId`, `chatRef`, temporary webhook, or `idempotencyKey`.
+
+The fixed endpoint is `POST /api/dsh-im/delivery/messages`. It reuses the current DSH Host WebServer and does not open another port. Port `3080` is the default for the Web profile; use the address printed by the running Host when it differs.
+
+The HTTP endpoint currently has no authentication and does not provide CORS. Use it only on the local machine or a trusted network; never expose it directly to the public internet.
+
+## Send from a plugin in the same Host
+
+A consumer plugin can declare the `dshIm` injection and call the shared service directly without going through Connection RPC.
+
+This minimal example sends one message when the plugin loads:
+
+```js
+export const inject = ['dshIm'];
+
+export async function apply(ctx) {
+  const result = await ctx.dshIm.send(
+    'bot_9577c8572d454122a4ef7fb4d8420a91',
+    'release-alerts',
+    'The build has completed.',
+  );
+
+  if (result.sent !== true) {
+    throw new Error('Proactive delivery did not return success');
+  }
+}
+```
+
+In a real plugin, call `ctx.dshIm.send()` from your existing scheduled job, build callback, or business-event handler. Its optional fourth argument currently supports an abort signal:
+
+```js
+await ctx.dshIm.send(botId, targetId, text, { signal });
+```
+
+A same-Host plugin may also list the saved targets for one bot:
+
+```js
+const targets = await ctx.dshIm.listTargets(botId);
+// [{ targetId, name?, kind, route }, ...]
+```
+
+On failure, the Promise rejects with an Error whose `code` is one of the public error codes below.
+
+## Send through Connection RPC
+
+Connection RPC is for a caller that already holds a `connection` client for the current DSH Host. The settings page also uses it to manage targets. Ordinary external applications should prefer the HTTP POST endpoint above.
+
+First unwrap the RPC success and error envelopes:
+
+```js
+const DELIVERY_CHANNEL = '/dsh-im-delivery';
+
+async function callDelivery(connection, endpoint, payload, signal) {
+  const result = await connection.rpc.call(
+    DELIVERY_CHANNEL,
+    endpoint,
+    payload,
+    signal,
+  );
+
+  if (result?.ok !== true) {
+    const error = new Error(result?.error?.message || 'delivery-failed');
+    error.code = result?.error?.code || 'delivery-failed';
+    throw error;
+  }
+  return result.value;
+}
+```
+
+Then send text with the copied `botId + targetId` pair:
+
+```js
+const result = await callDelivery(connection, 'message.send', {
+  botId: 'bot_9577c8572d454122a4ef7fb4d8420a91',
+  targetId: 'release-alerts',
+  text: 'The build has completed.',
+});
+
+// result: { sent: true }
+```
+
+`message.send` accepts exactly `{ botId, targetId, text }`. Do not add a native route, `sessionId`, `chatRef`, temporary webhook, or `idempotencyKey`.
+
+### Example: deliver a daily report
+
+```js
+async function sendDailyReport(connection, summary) {
+  try {
+    await callDelivery(connection, 'message.send', {
+      botId: 'bot_9577c8572d454122a4ef7fb4d8420a91',
+      targetId: 'daily-report',
+      text: `Daily operations summary\n\n${summary}`,
+    });
+  } catch (error) {
+    if (error.code === 'bot-not-connected') {
+      // Let the application decide whether to retry after reconnection.
+      return { delivered: false, reason: 'offline' };
+    }
+    throw error;
+  }
+  return { delivered: true };
+}
+```
+
+## Management RPC reference
+
+The settings page manages targets through the same Connection RPC channel. Most callers need only `message.send`; use the other endpoints only when the caller must manage targets itself.
+
+Every response is either `{ ok: true, value }` or `{ ok: false, error: { code, message, details } }`.
+
+| Endpoint | Payload | Successful `value` |
+| --- | --- | --- |
+| `message.send` | `{ botId, targetId, text }` | `{ sent: true }` |
+| `target.list` | `{ botId }` | `{ botId, channel, targets }` |
+| `target.suggestion.list` | `{ botId }` | `{ botId, channel, suggestions }` |
+| `target.create` | `{ botId, target: { targetId, name?, kind, route } }` | The complete created target |
+| `target.update` | `{ botId, targetId, target: { name?, kind, route } }` | The complete updated target |
+| `target.delete` | `{ botId, targetId }` | `{ deleted: true }` |
+| `target.test` | `{ botId, targetId }` | `{ sent: true }` |
+| `target.test` | `{ botId, target: { kind, route } }` | `{ sent: true }`; tests a draft without saving it |
+
+Payloads are validated with exact fields. The inner `target` in `target.update` must not contain `targetId`; a draft test must not contain `targetId` or `name`.
+
+## Error handling
+
+An HTTP failure returns `{ "error": { "code", "message", "details" } }`. Same-Host and RPC calls use the same error codes without an HTTP status.
+
+| Error code | HTTP status | Meaning and suggested action |
+| --- | --- | --- |
+| `bad-request` | 400 | Invalid request shape, ID format, JSON, or text; check field names and remove extra fields |
+| `unknown-bot` | 404 | The current Host does not own this `botId`; copy it again from bot settings |
+| `unknown-target` | 404 | The bot has no such `targetId`; check the copied pair or whether the target was deleted |
+| `target-conflict` | 409 | The same bot already has this `targetId`; choose another alias |
+| `invalid-target` | 422 | The target type or native ID violates this channel's rules; select the correct type and verify the ID |
+| `bot-not-connected` | 503 | The bot is offline; let the caller decide whether to retry after reconnection |
+| `target-rejected` | 422 | The platform explicitly rejected the target or the bot lacks permission; check platform permissions and the target ID |
+| `delivery-failed` | 502 | A network, platform, or other safely redacted delivery failure; check bot state and Host logs |
+| `cancelled` | 408 | The call was cancelled; stop or start a new call as required by the application |
+
+The HTTP protocol layer may also return `method-not-allowed` (405), `unsupported-media-type` (415), or `payload-too-large` (413).
+
+## Delivery semantics and limits
+
+- Proactive delivery currently accepts nonempty text only. This API does not send images, files, cards, or rich content.
+- The maximum HTTP JSON request body is 1 MiB.
+- `{ sent: true }` means the platform accepted the send request or its SDK returned success. It does not guarantee final delivery or a read receipt.
+- DSH-IM stores no proactive-delivery history, generates no `deliveryHandle` or `idempotencyKey`, and performs no automatic retry.
+- Retrying after a caller timeout can create duplicate messages. When business idempotency matters, the caller must store its own event ID and processing result.
+- Normal delivery uses only a saved `botId + targetId`. Keep the native route in target configuration instead of sending it with every message.
+- One call sends to one target. Notify multiple targets with separate calls and handle each result separately.
+- Targets remain editable while a bot is offline, but testing and delivery require a connected bot.
+
+## HTTP and RPC reachability
+
+The HTTP endpoint is registered only when the current Host provides a WebServer, and it uses that server's existing listen address and port. A Web profile normally defaults to `127.0.0.1:3080`, which is reachable only from the same machine. To call it from another machine, bind the WebServer to a reachable address in that profile's `cordis.patch.yml`, then restart the Host. For example:
+
+```yaml
+- id: webserver
+  config:
+    host: '0.0.0.0'
+```
+
+This also expands network reachability for the other pages and routes on that WebServer. Because the proactive-delivery HTTP endpoint currently has no authentication, use it only with a trusted LAN, firewall, or reverse proxy, and never expose it directly to the public internet.
+
+Connection RPC accepts loopback callers by default. If a Web profile is deliberately served on a trusted LAN, it can reuse the existing Host authority in that profile's `cordis.patch.yml`:
+
+```yaml
+- id: xmanrui-dsh-im
+  config:
+    rpcAuthority: trusted-host
+```
+
+`trusted-host` is only a Host/Origin reachability boundary, not user authentication. Callers that can reach that trusted-network authority can also access bot-management endpoints. Enable it only on a trusted network.
+
+## Troubleshooting
+
+### The target conversation is missing from the dropdown
+
+Send that bot a message on the platform, return to settings, and refresh. Suggestions are not a complete platform conversation directory. Use **Enter manually (advanced)** if the target still does not appear.
+
+### The Test button is disabled
+
+Make sure the bot is online and every native ID required by the current target type is present. A Slack Thread and a Telegram Topic both require two fields.
+
+### Can Target ID be changed after saving?
+
+No. You can edit its name, type, and native route without changing call parameters. If the alias itself must change, create a new target, migrate callers, and then delete the old target.
+
+### Why not use sessionId?
+
+A `sessionId` identifies a Harness Session. It is not a uniform, stable message address across the nine platforms. Proactive delivery uses the stable bot and saved-target pair instead.
+
+### The test succeeded, but the recipient cannot see the message
+
+A successful test proves only that the platform accepted the send. Check bot permissions, platform restrictions, target accuracy, and client-side filtering or archive settings.

package/PROACTIVE_DELIVERY.md

@@ -0,0 +1,321 @@
+# 主动投递使用指南
+
+**简体中文** · [English](PROACTIVE_DELIVERY.en.md)
+
+主动投递让应用在没有用户新消息的情况下，通过已经接入 DSH-IM 的机器人发送文字消息。调用方只需保存一组稳定的 `botId + targetId`，不需要保存 Harness `sessionId`、聊天引用、消息 ID 或临时 Webhook。
+
+九个内置渠道均支持主动投递：微信、飞书、钉钉、企业微信、QQ、Slack、Telegram、Discord 和 WhatsApp。
+
+## 快速开始
+
+1. 打开「设置 → IM机器人」，找到需要发消息的机器人。
+2. 点击机器人卡片右上角的齿轮图标。
+3. 在「调用标识」中复制 `Bot ID`。
+4. 点击「新建目标」，从已聊会话中选择，或点击「手动填写（高级）」填写平台原生 ID。
+5. 填写或确认 `Target ID`、目标类型和平台原生 ID。
+6. 点击「测试」。目标收到 `DSH-IM 主动投递测试成功。` 后，再点击「保存目标」。
+7. 在已保存目标上点击「复制调用参数」，得到可供应用保存的 `{ botId, targetId }`。
+8. 使用 HTTP POST、同 Host 的 `ctx.dshIm.send()` 或 Connection RPC 的 `message.send` 发送消息。
+
+## 配置投递目标
+
+### 1. 获取 Bot ID
+
+`botId` 是当前已接入机器人的真实调用标识。请从设置页复制并将它视为不透明字符串，不要根据前缀推断渠道，也不要使用机器人名称、平台 App ID 或卡片中的脱敏 ID 代替。
+
+目标配置跟随当前机器人保存。移除机器人时，它的投递目标也会被清理；重新接入后应重新复制 `botId` 并配置目标。
+
+### 2. 新建目标
+
+点击「新建目标」后，默认显示「从已聊过的会话选择」下拉框：
+
+- 候选来自该机器人已经持久化的会话映射，不是平台通讯录，也不是严格按时间排序的完整最近会话列表。
+- 候选只包含投递所需的目标类型和平台原生 ID，不包含 Harness `sessionId`、消息正文、消息 ID、会话名称或最后活跃时间。
+- 已配置的相同目标会显示「已添加」并禁用。
+- 没有候选时，先在对应平台与机器人聊一条消息，再点击「刷新」。仍未出现时可使用「手动填写（高级）」。
+
+选择候选只会预填表单，不会自动保存。
+
+### 3. 理解 Target ID
+
+`targetId` 是你为调用方定义的稳定别名，不是平台用户 ID、群 ID 或频道 ID。
+
+- 它只需在同一个机器人下唯一；不同机器人可以使用相同的 `targetId`。
+- 可使用大小写字母、数字、点、下划线、冒号、`@` 或连字符，长度为 1–128 个字符。
+- 新建时页面默认生成 `tgt_` 加 16 位十六进制随机串，例如 `tgt_7f3a91c8d2e64b10`。
+- 首次保存前可以修改，例如改成 `daily-report` 或 `release-alerts`。
+- 保存后 `targetId` 不可修改，但名称、目标类型和平台原生路由可以修改；调用方仍使用原来的 `botId + targetId`。
+
+### 4. 测试、保存和复制
+
+从会话新建、手动新建和编辑目标时，表单底部都会显示「测试」按钮：
+
+- 机器人在线且当前目标所需的平台 ID 已填写完整时，测试按钮才可用。
+- 测试使用当前表单中的目标类型和平台 ID，不会先创建、更新或保存目标。
+- 修改测试过的平台 ID 后，旧的成功提示会清除，需要重新测试。
+- 已保存目标列表中的「测试」按钮测试该目标当前保存的路由。
+- 测试成功表示平台发送接口已接受请求或 SDK 成功返回，不代表消息已经被阅读。
+
+保存后点击「复制调用参数」，页面会复制如下 JSON：
+
+```json
+{
+  "botId": "bot_9577c8572d454122a4ef7fb4d8420a91",
+  "targetId": "release-alerts"
+}
+```
+
+### 配置示例：飞书告警群
+
+假设飞书机器人已经在告警群中收到过消息：
+
+1. 打开该机器人的设置页并复制 `Bot ID`。
+2. 点击「新建目标」，在下拉框中选择告警群。
+3. 将自动生成的 `Target ID` 改为 `release-alerts`，显示名称填为「发布告警群」。
+4. 确认目标类型为「群聊」，群 Chat ID 已自动填入。
+5. 点击「测试」，到飞书群中确认测试消息。
+6. 点击「保存目标」，再点击「复制调用参数」。
+
+以后即使编辑并更换群 Chat ID，调用方仍可继续使用同一组 `botId + release-alerts`。
+
+## 九渠道手动填写字段
+
+优先从已聊会话中选择。只有目标未出现在候选中时，才需要手动取得以下平台原生 ID。
+
+| 渠道 | 目标类型 | 需要填写的字段 | 示例或说明 |
+| --- | --- | --- | --- |
+| 微信 | `user` | 微信用户 ID（`toUserId`） | 填写接收消息的微信用户 ID |
+| 飞书 | `user` | Open ID（`openId`） | 例如 `ou_xxx` |
+| 飞书 | `group` | 群 Chat ID（`chatId`） | 例如 `oc_xxx` |
+| 钉钉 | `user` | 用户 ID（`userId`） | 填写钉钉用户 ID |
+| 钉钉 | `group` | 群 Open Conversation ID（`openConversationId`） | 主动投递不使用临时 `sessionWebhook` |
+| 企业微信 | `user` | 用户 ID（路由字段为 `chatId`） | 私聊填写用户 ID |
+| 企业微信 | `group` | 群 Chat ID（`chatId`） | 群聊填写群 `chatid` |
+| QQ | `user` | 用户 Open ID（`userOpenId`） | 平台提供的 `user_openid` |
+| QQ | `group` | 群 Open ID（`groupOpenId`） | 平台提供的 `group_openid` |
+| Slack | `conversation` | Channel ID（`channelId`） | 例如 `C0123456789` |
+| Slack | `thread` | Channel ID + Thread 时间戳（`channelId`, `threadTs`） | 例如 `1712345678.123456` |
+| Telegram | `chat` | Chat ID（`chatId`） | 十进制字符串，例如 `-1001234567890` |
+| Telegram | `topic` | Chat ID + Topic ID（`chatId`, `messageThreadId`） | Topic ID 必须是正整数 |
+| Discord | `channel` | Channel ID（`channelId`） | 私信、频道和 Thread 都使用可发消息的 Channel ID |
+| WhatsApp | `user` | 用户 JID（`jid`） | 例如 `8613800000000@s.whatsapp.net` |
+| WhatsApp | `group` | 群 JID（`jid`） | 例如 `1234567890-123456@g.us` |
+
+平台 ID 字符串不能为空或带首尾空格。一个目标只接受所选渠道和类型要求的字段，额外字段会被拒绝。
+
+## 通过 HTTP POST 发送
+
+普通外部应用可以直接调用 Host 的主动投递接口：
+
+```bash
+curl --request POST \
+  http://127.0.0.1:3080/api/dsh-im/delivery/messages \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "botId": "bot_9577c8572d454122a4ef7fb4d8420a91",
+    "targetId": "release-alerts",
+    "text": "构建已经完成。"
+  }'
+```
+
+成功返回：
+
+```json
+{ "sent": true }
+```
+
+请求体严格只接受 `botId`、`targetId` 和 `text`，JSON 总大小不能超过 1 MiB。不要附加平台原生路由、`sessionId`、`chatRef`、临时 Webhook 或 `idempotencyKey`。
+
+接口路径固定为 `POST /api/dsh-im/delivery/messages`，复用当前 DSH Host 的 WebServer，不会另开端口。示例中的 `3080` 是 Web profile 的默认端口；实际地址以 Host 启动时显示的地址为准。
+
+当前 HTTP 接口不包含鉴权，也不提供 CORS。只应在本机或可信网络中使用，不要直接暴露到公网。
+
+## 在同一 Host 的插件中发送
+
+消费插件声明 `dshIm` 注入后，可以直接调用共享服务，不经过 Connection RPC。
+
+下面是一个最小示例；插件加载时会发送一次消息：
+
+```js
+export const inject = ['dshIm'];
+
+export async function apply(ctx) {
+  const result = await ctx.dshIm.send(
+    'bot_9577c8572d454122a4ef7fb4d8420a91',
+    'release-alerts',
+    '构建已经完成。',
+  );
+
+  if (result.sent !== true) {
+    throw new Error('主动投递没有返回成功结果');
+  }
+}
+```
+
+实际使用时，把 `ctx.dshIm.send()` 放进你的定时任务、构建回调或业务事件处理函数中。可选的第四个参数当前支持取消信号：
+
+```js
+await ctx.dshIm.send(botId, targetId, text, { signal });
+```
+
+同 Host 插件也可以列出某个机器人的已保存目标：
+
+```js
+const targets = await ctx.dshIm.listTargets(botId);
+// [{ targetId, name?, kind, route }, ...]
+```
+
+调用失败时 Promise 会拒绝，`error.code` 使用本文后面的公共错误码。
+
+## 通过 Connection RPC 发送
+
+Connection RPC 适合已经持有当前 DSH Host `connection` 客户端的调用方，也是设置页管理目标所使用的接口。普通外部应用优先使用上面的 HTTP POST。
+
+先封装 RPC 成功与错误包络：
+
+```js
+const DELIVERY_CHANNEL = '/dsh-im-delivery';
+
+async function callDelivery(connection, endpoint, payload, signal) {
+  const result = await connection.rpc.call(
+    DELIVERY_CHANNEL,
+    endpoint,
+    payload,
+    signal,
+  );
+
+  if (result?.ok !== true) {
+    const error = new Error(result?.error?.message || 'delivery-failed');
+    error.code = result?.error?.code || 'delivery-failed';
+    throw error;
+  }
+  return result.value;
+}
+```
+
+然后使用已复制的 `botId + targetId` 发送文字：
+
+```js
+const result = await callDelivery(connection, 'message.send', {
+  botId: 'bot_9577c8572d454122a4ef7fb4d8420a91',
+  targetId: 'release-alerts',
+  text: '构建已经完成。',
+});
+
+// result: { sent: true }
+```
+
+`message.send` 只接受 `{ botId, targetId, text }`。不要附加平台路由、`sessionId`、`chatRef`、临时 Webhook 或 `idempotencyKey`。
+
+### 示例：投递每日报告
+
+```js
+async function sendDailyReport(connection, summary) {
+  try {
+    await callDelivery(connection, 'message.send', {
+      botId: 'bot_9577c8572d454122a4ef7fb4d8420a91',
+      targetId: 'daily-report',
+      text: `今日运行摘要\n\n${summary}`,
+    });
+  } catch (error) {
+    if (error.code === 'bot-not-connected') {
+      // 等待机器人恢复连接后，由业务决定是否重试。
+      return { delivered: false, reason: 'offline' };
+    }
+    throw error;
+  }
+  return { delivered: true };
+}
+```
+
+## 管理 RPC 参考
+
+设置页使用同一个 Connection RPC 通道管理目标。普通调用方通常只需要 `message.send`；需要自行管理目标时再使用其他端点。
+
+所有响应均为 `{ ok: true, value }` 或 `{ ok: false, error: { code, message, details } }`。
+
+| 端点 | Payload | 成功时的 `value` |
+| --- | --- | --- |
+| `message.send` | `{ botId, targetId, text }` | `{ sent: true }` |
+| `target.list` | `{ botId }` | `{ botId, channel, targets }` |
+| `target.suggestion.list` | `{ botId }` | `{ botId, channel, suggestions }` |
+| `target.create` | `{ botId, target: { targetId, name?, kind, route } }` | 已创建的完整目标 |
+| `target.update` | `{ botId, targetId, target: { name?, kind, route } }` | 更新后的完整目标 |
+| `target.delete` | `{ botId, targetId }` | `{ deleted: true }` |
+| `target.test` | `{ botId, targetId }` | `{ sent: true }` |
+| `target.test` | `{ botId, target: { kind, route } }` | `{ sent: true }`；测试草稿，不保存 |
+
+接口严格校验字段。`target.update` 的内部 `target` 不能包含 `targetId`；草稿测试不能包含 `targetId` 或 `name`。
+
+## 错误处理
+
+HTTP 失败响应格式为 `{ "error": { "code", "message", "details" } }`。同 Host 和 RPC 使用相同错误码，但没有 HTTP 状态码。
+
+| 错误码 | HTTP 状态 | 含义与处理建议 |
+| --- | --- | --- |
+| `bad-request` | 400 | 请求结构、ID 格式、JSON 或文字无效；检查字段名并移除额外字段 |
+| `unknown-bot` | 404 | `botId` 不属于当前 Host；重新从机器人设置页复制 |
+| `unknown-target` | 404 | 该机器人下不存在 `targetId`；检查是否复制错误或目标已被删除 |
+| `target-conflict` | 409 | 同一机器人下已经存在相同 `targetId`；更换别名 |
+| `invalid-target` | 422 | 目标类型或平台原生 ID 不符合当前渠道规则；重新选择类型并核对 ID |
+| `bot-not-connected` | 503 | 机器人当前离线；恢复连接后由调用方决定是否重试 |
+| `target-rejected` | 422 | 平台明确拒绝目标或机器人缺少发送权限；检查平台权限和目标 ID |
+| `delivery-failed` | 502 | 网络、平台或其他无法安全细分的发送失败；检查连接状态和 Host 日志 |
+| `cancelled` | 408 | 调用被取消；按业务需要结束或重新发起 |
+
+HTTP 协议层还可能返回 `method-not-allowed`（405）、`unsupported-media-type`（415）或 `payload-too-large`（413）。
+
+## 投递语义与限制
+
+- 当前主动投递只发送非空文字，不支持在该接口中发送图片、文件、卡片或富文本。
+- HTTP JSON 请求体上限为 1 MiB。
+- `{ sent: true }` 表示平台发送接口接受请求或 SDK 成功返回，不承诺最终送达或已读。
+- DSH-IM 不保存主动投递历史，不生成 `deliveryHandle` 或 `idempotencyKey`，也不自动重试。
+- 调用方超时后重试可能产生重复消息；需要业务幂等时，由调用方保存自己的业务事件 ID 和处理结果。
+- 正式发送只使用已保存的 `botId + targetId`。平台原生路由保存在目标配置中，不应随每次消息发送。
+- 一个调用只发送到一个目标。需要通知多个目标时，应分别调用并分别处理结果。
+- 机器人离线时仍可编辑目标，但不能测试或主动发送。
+
+## HTTP 与 RPC 可达范围
+
+HTTP 接口只在当前 Host 提供 WebServer 时注册，并使用同一个监听地址和端口。默认 Web profile 地址通常是 `127.0.0.1:3080`，只能由本机访问。若要从其他机器调用，需要在对应 profile 的 `cordis.patch.yml` 中把 WebServer 绑定到可达地址并重启 Host，例如：
+
+```yaml
+- id: webserver
+  config:
+    host: '0.0.0.0'
+```
+
+这会同时扩大该 WebServer 上其他页面和路由的网络可达范围。当前主动投递 HTTP 接口没有鉴权，因此只能配合可信局域网、防火墙或反向代理使用，不能直接暴露到公网。
+
+Connection RPC 默认只允许当前 Host 的回环调用。若 Web profile 明确运行在受信任局域网，可在该 profile 的 `cordis.patch.yml` 中复用现有 Host authority：
+
+```yaml
+- id: xmanrui-dsh-im
+  config:
+    rpcAuthority: trusted-host
+```
+
+`trusted-host` 只是 Host／Origin 可达性边界，不是用户认证。启用后，能访问该受信网络 authority 的调用方也能访问机器人管理接口；只应在可信网络中使用。
+
+## 常见问题
+
+### 下拉框找不到目标会话
+
+先在对应平台向该机器人发送一条消息，再返回设置页刷新。候选不是平台的完整会话目录；仍然找不到时使用「手动填写（高级）」。
+
+### 测试按钮不可点击
+
+确认机器人在线，并填写当前目标类型要求的全部平台原生 ID。Slack Thread 和 Telegram Topic 都需要两个字段。
+
+### 保存后能否修改 Target ID
+
+不能。你可以编辑名称、类型和平台路由而保持调用参数不变；若必须更换 `targetId`，请新建目标并让调用方切换后再删除旧目标。
+
+### 为什么不用 sessionId
+
+`sessionId` 标识 Harness 会话，不是九个平台统一、稳定的消息投递地址。主动投递只使用机器人和已保存目标的稳定组合。
+
+### 测试成功但对方没有看到消息
+
+测试成功只证明平台接口接受发送。请继续检查机器人权限、平台限制、目标是否正确，以及客户端侧的消息过滤或归档设置。