@zhin.js/adapter-slack 6.0.2 → 6.0.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 6.0.3
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - @zhin.js/agent@1.1.3
+  - zhin.js@6.0.2
+
 ## 6.0.2
 
 ### Patch Changes

package/README.md

@@ -24,8 +24,8 @@ pnpm add @zhin.js/adapter-slack
 - `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-入站：`gateway.receive({ adapter, target: channelId, content: text, sender, metadata })`  
-出站：`send({ target, payload })` → Web API（`target` 可为 `channel` 或 `channel:thread_ts`）
+入站：`gateway.receive({ conversation, message: { conversation, id }, content: text, sender, metadata })`（`conversation` 为 ConversationRef：`channel_type: im` → kind `private`，其余 → kind `group`；线程根 ts 进 `threadId`）  
+出站：`send({ conversation, payload })` → Web API（`conversation.id` 为 channel，`conversation.threadId` 为 thread_ts）
 
 ### 平台权限（platform permit）
 

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -138,10 +138,7 @@ export declare class SlackEndpoint implements EndpointInstance, SlackWebhookHand
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a message event when open. */
     admit(event: SlackMessageEvent | SlackEvent): void;
     admitInteraction(payload: SlackInteractionPayload): void;

package/lib/endpoint.js

@@ -4,7 +4,7 @@
 import { SocketModeClient } from '@slack/socket-mode';
 import { WebClient } from '@slack/web-api';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { formatInboundContent, formatInteractionContent, formatSlashContent, inboundMessageId, resolveSlackChannelType, } from './protocol.js';
+import { formatInboundContent, formatInteractionContent, formatSlashContent, resolveSlackChannelType, slackInboundConversation, } from './protocol.js';
 import { registerSlackAgentEndpoint } from './slack-agent-deps.js';
 import { createSlackInboundFilterState, shouldDropSlackInboundMessage, } from './slack-inbound-filter.js';
 import { formatSlackMessageRef, parseSlackMessageRef } from './slack-message-ref.js';
@@ -106,10 +106,11 @@ export class SlackEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         if (!this.#client)
             throw new Error('Slack client not connected');
-        const { channel, threadTs } = parseSendTarget(target);
+        const channel = conversation.id;
+        const threadTs = conversation.threadId;
         const result = await sendSlackContent(this.#client, payload, { channel, threadTs }, logger);
         if (result.ts)
             this.trackMessageChannel(result.ts, channel);
@@ -127,17 +128,22 @@ export class SlackEndpoint {
         if (!msg.channel || !msg.ts)
             return;
         this.trackMessageChannel(msg.ts, msg.channel);
+        const threadTs = msg.thread_ts && msg.thread_ts !== msg.ts ? msg.thread_ts : undefined;
+        const conversation = slackInboundConversation(String(this.#options.id), {
+            channelId: msg.channel,
+            channelType: msg.channel_type,
+            threadId: threadTs,
+        });
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: msg.channel,
+            conversation,
+            message: { conversation, id: msg.ts },
             content: formatInboundContent(msg),
             sender: msg.user ?? msg.channel,
-            id: inboundMessageId(msg),
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 channelType: resolveSlackChannelType(msg),
                 userId: msg.user,
-                threadTs: msg.thread_ts && msg.thread_ts !== msg.ts ? msg.thread_ts : undefined,
+                threadTs,
                 ts: msg.ts,
                 // app_mention 事件本身即 @ 机器人；新 Runtime 纯文本 content 需经 metadata 传递
                 ...(msg.type === 'app_mention' ? { mentioned: true } : {}),
@@ -145,7 +151,7 @@ export class SlackEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'slack_gateway_receive_failed',
-                target: msg.channel,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -161,12 +167,17 @@ export class SlackEndpoint {
         if (payload.response_url) {
             postSlackEphemeral(payload.response_url, '已收到', logger);
         }
+        const actionTs = payload.actions[0]?.action_ts ?? messageTs ?? `action-${Date.now()}`;
+        const conversation = slackInboundConversation(String(this.#options.id), {
+            channelId: channelId || userId,
+            // block_actions 无 channel_type；无 channel 时按与发起用户的 DM 处理
+            channelType: channelId ? undefined : 'im',
+        });
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: channelId || userId,
+            conversation,
+            message: { conversation, id: actionTs },
             content: formatInteractionContent(payload),
             sender: userId,
-            id: payload.actions[0]?.action_ts ?? messageTs ?? `action-${Date.now()}`,
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 eventType: 'block_actions',
@@ -176,7 +187,7 @@ export class SlackEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'slack_gateway_receive_failed',
-                target: channelId,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -185,12 +196,14 @@ export class SlackEndpoint {
         if (!this.#open)
             return;
         postSlackEphemeral(cmd.response_url, '处理中…', logger);
+        const conversation = slackInboundConversation(String(this.#options.id), {
+            channelId: cmd.channel_id,
+        });
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: cmd.channel_id,
+            conversation,
+            message: { conversation, id: cmd.trigger_id },
             content: formatSlashContent(cmd),
             sender: cmd.user_id,
-            id: cmd.trigger_id,
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 eventType: 'slash_command',
@@ -199,7 +212,7 @@ export class SlackEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'slack_gateway_receive_failed',
-                target: cmd.channel_id,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -352,13 +365,6 @@ export class SlackEndpoint {
         await this.#socket.start();
     }
 }
-function parseSendTarget(target) {
-    const parsed = parseSlackMessageRef(target);
-    if (parsed && /^\d+\.\d+$/.test(parsed.ts)) {
-        return { channel: parsed.channel, threadTs: parsed.ts };
-    }
-    return { channel: target };
-}
 /** Slack Web API 分页上限（每页 1000，cursor 翻页直到 next_cursor 为空）。 */
 const SLACK_LIST_PAGE_SIZE = 1000;
 function createSlackEndpointManagement(endpoint) {

package/lib/index.d.ts

@@ -1,9 +1,8 @@
-export { formatInboundContent, formatInteractionContent, formatOutboundWire, formatSlashContent, headerValue, inboundMessageId, keyboardToBlockKitBlocks, normalizeWebhookPath, readTextBody, resolveSlackChannelType, resolveSlackConfig, verifySlackSignature, type ResolvedSlackConfig, type SlackAdapterConfig, type SlackBlockAction, type SlackEvent, type SlackEventEnvelope, type SlackInteractionPayload, type SlackMessageEvent, type SlackSlashCommand, type SlackUrlVerification, type SlackWireSegment, } from './protocol.js';
+export { formatInboundContent, formatInteractionContent, formatOutboundWire, formatSlashContent, headerValue, keyboardToBlockKitBlocks, normalizeWebhookPath, readTextBody, resolveSlackChannelType, resolveSlackConfig, slackInboundConversation, verifySlackSignature, type ResolvedSlackConfig, type SlackAdapterConfig, type SlackBlockAction, type SlackEvent, type SlackEventEnvelope, type SlackInteractionPayload, type SlackMessageEvent, type SlackSlashCommand, type SlackUrlVerification, type SlackWireSegment, } from './protocol.js';
 export { SlackEndpoint, type SlackEndpointOptions, type SlackSocketLike, type SlackWebClientLike, } from './endpoint.js';
 export { registerSlackWebhookRoutes, handleSlackWebhookRequest, type SlackWebhookHandler, } from './webhook.js';
 export { getSlackAgentDeps, registerSlackAgentEndpoint, setSlackAgentDeps, type SlackAgentDeps, type SlackAgentEndpoint, } from './slack-agent-deps.js';
 export { checkSlackPlatformPermit, normalizeSlackSenderForPermit, platformPermit, registerSlackPlatformPermitChecker, slackGroupPermitResolver, } from './platform-permit.js';
-export { formatSlackMessageRef, parseSlackMessageRef, slackMessageTs, } from './slack-message-ref.js';
 export { normalizeSlackReactionName } from './slack-reaction.js';
 export { markdownToMrkdwn, mrkdwnToPlainFallback, splitMrkdwnText } from './markdown-to-mrkdwn.js';
 export { mrkdwnToMarkdown } from './mrkdwn-to-markdown.js';

package/lib/index.js

@@ -1,9 +1,8 @@
-export { formatInboundContent, formatInteractionContent, formatOutboundWire, formatSlashContent, headerValue, inboundMessageId, keyboardToBlockKitBlocks, normalizeWebhookPath, readTextBody, resolveSlackChannelType, resolveSlackConfig, verifySlackSignature, } from './protocol.js';
+export { formatInboundContent, formatInteractionContent, formatOutboundWire, formatSlashContent, headerValue, keyboardToBlockKitBlocks, normalizeWebhookPath, readTextBody, resolveSlackChannelType, resolveSlackConfig, slackInboundConversation, verifySlackSignature, } from './protocol.js';
 export { SlackEndpoint, } from './endpoint.js';
 export { registerSlackWebhookRoutes, handleSlackWebhookRequest, } from './webhook.js';
 export { getSlackAgentDeps, registerSlackAgentEndpoint, setSlackAgentDeps, } from './slack-agent-deps.js';
 export { checkSlackPlatformPermit, normalizeSlackSenderForPermit, platformPermit, registerSlackPlatformPermitChecker, slackGroupPermitResolver, } from './platform-permit.js';
-export { formatSlackMessageRef, parseSlackMessageRef, slackMessageTs, } from './slack-message-ref.js';
 export { normalizeSlackReactionName } from './slack-reaction.js';
 export { markdownToMrkdwn, mrkdwnToPlainFallback, splitMrkdwnText } from './markdown-to-mrkdwn.js';
 export { mrkdwnToMarkdown } from './mrkdwn-to-markdown.js';

package/lib/protocol.d.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage } from 'node:http';
+import type { ConversationRef } from '@zhin.js/im-contract';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface SlackAdapterConfig {
     readonly name?: string;
@@ -115,11 +116,20 @@ export interface SlackWireSegment {
 export declare function resolveSlackConfig(config?: SlackAdapterConfig): ResolvedSlackConfig;
 export declare function normalizeWebhookPath(path: string): string;
 export declare function resolveSlackChannelType(event: Pick<SlackEvent, 'channel_type'>): 'private' | 'group';
+/**
+ * 入站归一化 → ConversationRef：channel_type `im` → private，其余（channel/group/mpim）
+ * → group；交互/斜杠命令无 channel_type 时按平台 id 前缀推断（D* 为 DM）。Slack 无
+ * guild 容器概念（team 为 workspace 级，不进 parent）；线程根 ts 进 `threadId`。
+ */
+export declare function slackInboundConversation(endpointId: string, opts: {
+    readonly channelId: string;
+    readonly channelType?: string;
+    readonly threadId?: string;
+}): ConversationRef;
 /** Build inbound text for MessageGateway.receive. */
 export declare function formatInboundContent(event: SlackMessageEvent | SlackEvent): string;
 export declare function formatInteractionContent(payload: SlackInteractionPayload): string;
 export declare function formatSlashContent(cmd: SlackSlashCommand): string;
-export declare function inboundMessageId(event: SlackMessageEvent): string;
 /**
  * Wire-encode an already-rendered outbound payload into Slack text + Block Kit blocks.
  * Segment canonicalization is intentionally not done here.

package/lib/protocol.js

@@ -63,6 +63,22 @@ export function normalizeWebhookPath(path) {
 export function resolveSlackChannelType(event) {
     return event.channel_type === 'im' ? 'private' : 'group';
 }
+/**
+ * 入站归一化 → ConversationRef：channel_type `im` → private，其余（channel/group/mpim）
+ * → group；交互/斜杠命令无 channel_type 时按平台 id 前缀推断（D* 为 DM）。Slack 无
+ * guild 容器概念（team 为 workspace 级，不进 parent）；线程根 ts 进 `threadId`。
+ */
+export function slackInboundConversation(endpointId, opts) {
+    const kind = opts.channelType != null
+        ? (opts.channelType === 'im' ? 'private' : 'group')
+        : (opts.channelId.startsWith('D') ? 'private' : 'group');
+    return {
+        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        kind,
+        id: opts.channelId,
+        ...(opts.threadId ? { threadId: opts.threadId } : {}),
+    };
+}
 /** Build inbound text for MessageGateway.receive. */
 export function formatInboundContent(event) {
     const text = typeof event.text === 'string' ? event.text : '';
@@ -83,9 +99,6 @@ export function formatInteractionContent(payload) {
 export function formatSlashContent(cmd) {
     return `${cmd.command} ${cmd.text}`.trim();
 }
-export function inboundMessageId(event) {
-    return `${event.channel}:${event.ts}`;
-}
 /**
  * Wire-encode an already-rendered outbound payload into Slack text + Block Kit blocks.
  * Segment canonicalization is intentionally not done here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-slack",
-  "version": "6.0.2",
+  "version": "6.0.3",
   "description": "Zhin.js Slack adapter for Plugin Runtime (Socket Mode / HTTP Events)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,21 +34,22 @@
   "dependencies": {
     "@slack/socket-mode": "^2.0.7",
     "@slack/web-api": "^7.19.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -66,8 +67,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/agent": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -8,6 +8,7 @@ import type {
   EndpointGroup,
   EndpointInstance,
   EndpointManagement,
+  EndpointSendRequest,
 } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
@@ -17,8 +18,8 @@ import {
   formatInboundContent,
   formatInteractionContent,
   formatSlashContent,
-  inboundMessageId,
   resolveSlackChannelType,
+  slackInboundConversation,
   type ResolvedSlackConfig,
   type SlackEvent,
   type SlackEventEnvelope,
@@ -202,9 +203,10 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     if (!this.#client) throw new Error('Slack client not connected');
-    const { channel, threadTs } = parseSendTarget(target);
+    const channel = conversation.id;
+    const threadTs = conversation.threadId;
     const result = await sendSlackContent(
       this.#client,
       payload,
@@ -224,17 +226,22 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
     if (!msg.channel || !msg.ts) return;
 
     this.trackMessageChannel(msg.ts, msg.channel);
+    const threadTs = msg.thread_ts && msg.thread_ts !== msg.ts ? msg.thread_ts : undefined;
+    const conversation = slackInboundConversation(String(this.#options.id), {
+      channelId: msg.channel,
+      channelType: msg.channel_type,
+      threadId: threadTs,
+    });
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: msg.channel,
+      conversation,
+      message: { conversation, id: msg.ts },
       content: formatInboundContent(msg),
       sender: msg.user ?? msg.channel,
-      id: inboundMessageId(msg),
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         channelType: resolveSlackChannelType(msg),
         userId: msg.user,
-        threadTs: msg.thread_ts && msg.thread_ts !== msg.ts ? msg.thread_ts : undefined,
+        threadTs,
         ts: msg.ts,
         // app_mention 事件本身即 @ 机器人；新 Runtime 纯文本 content 需经 metadata 传递
         ...(msg.type === 'app_mention' ? { mentioned: true } : {}),
@@ -242,7 +249,7 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'slack_gateway_receive_failed',
-        target: msg.channel,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -257,12 +264,17 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
     if (payload.response_url) {
       postSlackEphemeral(payload.response_url, '已收到', logger);
     }
+    const actionTs = payload.actions[0]?.action_ts ?? messageTs ?? `action-${Date.now()}`;
+    const conversation = slackInboundConversation(String(this.#options.id), {
+      channelId: channelId || userId,
+      // block_actions 无 channel_type；无 channel 时按与发起用户的 DM 处理
+      channelType: channelId ? undefined : 'im',
+    });
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: channelId || userId,
+      conversation,
+      message: { conversation, id: actionTs },
       content: formatInteractionContent(payload),
       sender: userId,
-      id: payload.actions[0]?.action_ts ?? messageTs ?? `action-${Date.now()}`,
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         eventType: 'block_actions',
@@ -272,7 +284,7 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'slack_gateway_receive_failed',
-        target: channelId,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -281,12 +293,14 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
   admitSlashCommand(cmd: SlackSlashCommand): void {
     if (!this.#open) return;
     postSlackEphemeral(cmd.response_url, '处理中…', logger);
+    const conversation = slackInboundConversation(String(this.#options.id), {
+      channelId: cmd.channel_id,
+    });
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: cmd.channel_id,
+      conversation,
+      message: { conversation, id: cmd.trigger_id },
       content: formatSlashContent(cmd),
       sender: cmd.user_id,
-      id: cmd.trigger_id,
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         eventType: 'slash_command',
@@ -295,7 +309,7 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'slack_gateway_receive_failed',
-        target: cmd.channel_id,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -461,14 +475,6 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
   }
 }
 
-function parseSendTarget(target: string): { channel: string; threadTs?: string } {
-  const parsed = parseSlackMessageRef(target);
-  if (parsed && /^\d+\.\d+$/.test(parsed.ts)) {
-    return { channel: parsed.channel, threadTs: parsed.ts };
-  }
-  return { channel: target };
-}
-
 /** Slack Web API 分页上限（每页 1000，cursor 翻页直到 next_cursor 为空）。 */
 const SLACK_LIST_PAGE_SIZE = 1000;
 

package/src/index.ts

@@ -4,12 +4,12 @@ export {
   formatOutboundWire,
   formatSlashContent,
   headerValue,
-  inboundMessageId,
   keyboardToBlockKitBlocks,
   normalizeWebhookPath,
   readTextBody,
   resolveSlackChannelType,
   resolveSlackConfig,
+  slackInboundConversation,
   verifySlackSignature,
   type ResolvedSlackConfig,
   type SlackAdapterConfig,
@@ -52,12 +52,6 @@ export {
   slackGroupPermitResolver,
 } from './platform-permit.js';
 
-export {
-  formatSlackMessageRef,
-  parseSlackMessageRef,
-  slackMessageTs,
-} from './slack-message-ref.js';
-
 export { normalizeSlackReactionName } from './slack-reaction.js';
 export { markdownToMrkdwn, mrkdwnToPlainFallback, splitMrkdwnText } from './markdown-to-mrkdwn.js';
 export { mrkdwnToMarkdown } from './mrkdwn-to-markdown.js';

package/src/protocol.ts

@@ -5,6 +5,7 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
 import { isMediaRef, type MediaRef } from '@zhin.js/core';
+import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { mrkdwnToMarkdown } from './mrkdwn-to-markdown.js';
 
@@ -192,6 +193,30 @@ export function resolveSlackChannelType(event: Pick<SlackEvent, 'channel_type'>)
   return event.channel_type === 'im' ? 'private' : 'group';
 }
 
+/**
+ * 入站归一化 → ConversationRef：channel_type `im` → private，其余（channel/group/mpim）
+ * → group；交互/斜杠命令无 channel_type 时按平台 id 前缀推断（D* 为 DM）。Slack 无
+ * guild 容器概念（team 为 workspace 级，不进 parent）；线程根 ts 进 `threadId`。
+ */
+export function slackInboundConversation(
+  endpointId: string,
+  opts: {
+    readonly channelId: string;
+    readonly channelType?: string;
+    readonly threadId?: string;
+  },
+): ConversationRef {
+  const kind: ConversationKind = opts.channelType != null
+    ? (opts.channelType === 'im' ? 'private' : 'group')
+    : (opts.channelId.startsWith('D') ? 'private' : 'group');
+  return {
+    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+    kind,
+    id: opts.channelId,
+    ...(opts.threadId ? { threadId: opts.threadId } : {}),
+  };
+}
+
 /** Build inbound text for MessageGateway.receive. */
 export function formatInboundContent(event: SlackMessageEvent | SlackEvent): string {
   const text = typeof event.text === 'string' ? event.text : '';
@@ -213,10 +238,6 @@ export function formatSlashContent(cmd: SlackSlashCommand): string {
   return `${cmd.command} ${cmd.text}`.trim();
 }
 
-export function inboundMessageId(event: SlackMessageEvent): string {
-  return `${event.channel}:${event.ts}`;
-}
-
 /**
  * Wire-encode an already-rendered outbound payload into Slack text + Block Kit blocks.
  * Segment canonicalization is intentionally not done here.