@zhin.js/adapter-slack 4.1.1 → 5.0.1

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 5.0.1
+
+### Patch Changes
+
+- cdf64e7: 多方向审计修复批（8 面 30+ bug）：
+
+  - **安全**：钉钉 webhook 验签绕过修复（缺 timestamp/sign 一律 403 + ±1h 防重放）；exec-policy fail-closed（换行/`$(`/反引号拒绝、管道逐段过白名单、env dump 复合拆段）；wecom 验签改 timingSafeEqual；config:set 拒绝 `__proto__` 等魔术键、host 键优先防覆写。
+  - **P0 功能**：`zhin packages` scoped 包名解析为空导致 rm -rf 风险；命令数字参数解析失败炸断消息链路（dispatch 捕获 continue）；TaskQueue 监听器首个事件自摘除导致 assistant 队列挂死（+超时后完成不覆盖终态）；DatabaseHost 跨世代共享崩溃（define 幂等 + stop 改进程级）；rss 按不存在 id 列删除改业务键。
+  - **Runtime/HMR**：native watcher 过滤忽略目录（lib/.zhin 不再触发重载风暴）；host 段配置 patch（http.port 等）存在 installResources 时全量重建；capability 目录非 entry 支持文件升级进程重启；documentTransaction 失败回滚。
+  - **CLI 写侧**：config/setup 对 toml 静默假成功改统一 config-file（不支持格式报错）；doctor/onboard 默认配置改新形态 plugins 映射；schedule add 改 --prompt；migrate engines/中文模板误伤/覆盖前备份。
+  - **适配器生命周期**：napcat/milky start 失败竞态与僵尸连接、心跳 close 清理、stop-during-connect settle；slack webhook 二次 writeHead + messageChannelMap LRU。
+  - **Host/向导**：logs/stats 与 inbox 查询改 DB 侧 count/orderBy/limit 下推；save-yaml 写入前校验；zhipu/moonshot baseUrl 必填预填；.env 写入转义 + 幂等合并；setup 数据库密码不再明文落 config；60s fetch 超时与 JSON 守卫。
+
+- 9c997b2: 通用 endpoint 管理命令套件：`@zhin.js/adapter` 新增 `createEndpointCommands(spec, defineCommand)`——`<adapter> endpoint list / add <name> key=value... / remove <name>` 三件套，含 kv 解析、`.env` 凭据派生（`<ADAPTER>_<NAME>_<FIELD>`）、yaml 写回保留注释、master 权限门禁（通用 `isEndpointOperator`）、自定义 bindFlow 钩子。QQ 迁移至套件（行为与扫码绑定流程不变）；napcat / onebot11 / onebot12 / milky / slack / telegram 接入（字段对齐各自 schema，features 补 @zhin.js/command）。
+- 09d4f25: Console 社交读取面（management 语义端口）多平台落地：napcat/onebot11/onebot12/milky（好友+群+群成员，OneBot 标准动作）；discord/kook/satori（guild+频道+成员，分页聚合，id 保精度留字符串）；slack（workspace 成员+public channels+conversations.members）；line（群/room 成员分页+profile 回退）；wechat-mp（followers openid）；weixin-ilink（context_token 对端推导）；lark（chats+members 全分页）。`EndpointFriend.user_id`/`EndpointGroup.group_id` 放宽为 `number | string`（雪花 id 不丢精度）。telegram/wecom/dingtalk/github/email/sandbox 注明平台无列表面暂不接。
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/agent@1.0.6
+  - @zhin.js/plugin-runtime@1.1.1
+  - @zhin.js/host-http@1.0.3
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
+## 5.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 1ddcd70: Console/契约扫尾批：
+
+  - adapter：多 endpoint record name 改为 entry.name（Console 展示/resolve/inbox 按名唯一命中）；`expandEndpointConfigs` 增加缺名/非法字符/重名校验与告警；slack endpoint 补 `name` getter；inbox-installer / agent-host 解析 `slot~entry` 展开 id（activity-feedback 随之恢复）。
+  - host-http：`schema:get`/`config:get` 兼容 `data.plugin`；extended RPC 参数顶层与 `data` 合并（cron 写操作修复）；请求审批认 `requestId`、已读认单值 `id`；`endpoint:requests`/`inboxRequests`/`inboxNotices` 行补 camelCase/扁平别名；cron 列表补 `expression/running/plugin/nextExecution/createdAt/context`。
+  - cli：装配 `setOrchestrationRuntime`/`setSessionTreeRuntime`（agent-sessions/orchestration 页恢复）；`/api/stats` 补 commands/components 计数；console REST databaseHost.started 改动态 getter；`wrapModel` 支持 orderBy/limit 链式查询；接线 SystemLog 模型 + 日志 transport（logs 页有真实数据，带 7 天/1 万条清理）。
+  - plugin-runtime：`DatabaseHostModel.select` 升级为链式 `DatabaseHostSelection`；新增 `system-log`（SystemLog 表定义/写入助手）。
+  - agent：导出 `asPrivate`（Runtime Host 装配 session tree runtime 用）。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- f32c424: 适配器配置统一为 endpoints 数组格式：`plugins.<adapter>` 为该 adapter 所有 endpoint 的通用配置，`plugins.<adapter>.endpoints[i]` 为单个 endpoint 的特殊配置（逐项覆盖，`name` 必填）。slack / github schema 新增 `endpoints` 属性；icqq / qq / slack 顶层必填改为 `anyOf`（单 endpoint 字段或 `endpoints` 数组二选一，兼容 Ajv strictRequired）。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+
 ## 4.1.1
 
 ### Patch Changes

package/README.md

@@ -44,10 +44,25 @@ pnpm add @zhin.js/adapter-slack
 # zhin.config.yml（Plugin Runtime）
 plugins:
   slack:
-    name: my-slack-bot
-    token: ${SLACK_BOT_TOKEN}
-    appToken: ${SLACK_APP_TOKEN}
     socketMode: true          # 默认 true，可省略
+    endpoints:
+      - name: my-slack-bot
+        token: ${SLACK_BOT_TOKEN}
+        appToken: ${SLACK_APP_TOKEN}
+```
+
+多 workspace：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
+
+```yaml
+plugins:
+  slack:
+    endpoints:
+      - name: team-a
+        token: ${SLACK_BOT_TOKEN_A}
+        appToken: ${SLACK_APP_TOKEN_A}
+      - name: team-b
+        token: ${SLACK_BOT_TOKEN_B}
+        appToken: ${SLACK_APP_TOKEN_B}
 ```
 
 ## HTTP Events 配置
@@ -55,11 +70,12 @@ plugins:
 ```yaml
 plugins:
   slack:
-    name: my-slack-bot
-    token: ${SLACK_BOT_TOKEN}
-    signingSecret: ${SLACK_SIGNING_SECRET}
     socketMode: false
     webhookPath: /slack/events   # 可选，默认 /slack/events
+    endpoints:
+      - name: my-slack-bot
+        token: ${SLACK_BOT_TOKEN}
+        signingSecret: ${SLACK_SIGNING_SECRET}
 ```
 
 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-slack`（`instanceKey: slack`）。  

package/adapters/slack.ts

@@ -9,14 +9,26 @@ import {
   resolveSlackConfig,
   type SlackAdapterConfig,
 } from '../src/protocol.js';
+import { slackRuntimeStateToken } from '../src/slack-runtime-state.js';
 
 export { SlackEndpoint } from '../src/endpoint.js';
 export type { SlackEndpointOptions, SlackSocketLike, SlackWebClientLike } from '../src/endpoint.js';
 
 export default defineAdapter<SlackAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // 媒体由端点物化（url 拉取 / 本地读取）经 files.uploadV2 上传；
+  // Block Kit 原生按钮承载交互段。
+  segments: {
+    outboundMedia: ['url', 'upload'],
+    interactive: 'native',
+  },
   create(context) {
     const config = resolveSlackConfig(context.config);
+    // 注册到插件运行时状态（slack endpoint list 的"运行中"数据源）
+    context.use(slackRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.mode,
+    });
     if (config.mode === 'http') {
       return new SlackEndpoint({
         id: context.id,

package/commands/endpoint/add/[name:string].ts

@@ -0,0 +1,3 @@
+import { slackEndpointCommands } from '../../../src/slack-endpoint-commands.js';
+
+export default slackEndpointCommands.add;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { slackEndpointCommands } from '../../src/slack-endpoint-commands.js';
+
+export default slackEndpointCommands.list;

package/commands/endpoint/remove/[name:string].ts

@@ -0,0 +1,3 @@
+import { slackEndpointCommands } from '../../../src/slack-endpoint-commands.js';
+
+export default slackEndpointCommands.remove;

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } 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';
@@ -57,6 +57,17 @@ export interface SlackWebClientLike extends SlackChatClient {
         }): Promise<{
             channel?: unknown;
         }>;
+        list(opts?: {
+            types?: string;
+            limit?: number;
+            cursor?: string;
+            exclude_archived?: boolean;
+        }): Promise<{
+            channels?: unknown[];
+            response_metadata?: {
+                next_cursor?: string;
+            };
+        }>;
     };
     users: {
         info(opts: {
@@ -64,6 +75,15 @@ export interface SlackWebClientLike extends SlackChatClient {
         }): Promise<{
             user?: unknown;
         }>;
+        list(opts?: {
+            limit?: number;
+            cursor?: string;
+        }): Promise<{
+            members?: unknown[];
+            response_metadata?: {
+                next_cursor?: string;
+            };
+        }>;
     };
     reactions: {
         add(opts: {
@@ -107,7 +127,10 @@ export interface SlackEndpointOptions {
 }
 export declare class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: SlackEndpointOptions);
+    /** Console 展示 / AdapterIndex live name（多 endpoint 时与 entry name 一致）。 */
+    get name(): string;
     get client(): SlackWebClientLike | undefined;
     get platformUserId(): string | undefined;
     get config(): ResolvedSlackConfig;

package/lib/endpoint.js

@@ -24,9 +24,14 @@ export class SlackEndpoint {
     #open = false;
     #started = false;
     #unregisterAgent;
+    management = createSlackEndpointManagement(this);
     constructor(options) {
         this.#options = options;
     }
+    /** Console 展示 / AdapterIndex live name（多 endpoint 时与 entry name 一致）。 */
+    get name() {
+        return this.#options.config.name;
+    }
     get client() {
         return this.#client;
     }
@@ -206,8 +211,17 @@ export class SlackEndpoint {
         }
     }
     trackMessageChannel(ts, channel) {
-        if (ts && channel)
-            this.#messageChannelMap.set(ts, channel);
+        if (!ts || !channel)
+            return;
+        // LRU：超 1024 条淘汰最久未更新的记录，避免无界增长。
+        if (this.#messageChannelMap.has(ts))
+            this.#messageChannelMap.delete(ts);
+        this.#messageChannelMap.set(ts, channel);
+        if (this.#messageChannelMap.size > 1024) {
+            const oldest = this.#messageChannelMap.keys().next().value;
+            if (oldest != null)
+                this.#messageChannelMap.delete(oldest);
+        }
     }
     resolveMessageRef(messageId, channelHint) {
         const parsed = parseSlackMessageRef(messageId);
@@ -302,8 +316,12 @@ export class SlackEndpoint {
     }
     async #startSocket() {
         const { config } = this.#options;
-        if (!config.appToken)
-            throw new Error('Socket Mode requires appToken');
+        if (!config.appToken) {
+            throw new Error('Slack Socket Mode 需要 appToken（xapp- 前缀的 App-Level Token）；注意 bot token 填 token 字段（xoxb- 前缀），两者不可混用');
+        }
+        if (!config.appToken.startsWith('xapp-')) {
+            throw new Error(`Slack appToken 格式不正确：Socket Mode 需要 xapp- 前缀的 App-Level Token（当前看起来是 ${config.appToken.slice(0, 5)}…，xoxb- 是 bot token，请填到 token 字段）`);
+        }
         this.#socket = this.#options.createSocket?.({
             appToken: config.appToken,
             clientPingTimeout: config.clientPingTimeout,
@@ -333,3 +351,76 @@ function parseSendTarget(target) {
     }
     return { channel: target };
 }
+/** Slack Web API 分页上限（每页 1000，cursor 翻页直到 next_cursor 为空）。 */
+const SLACK_LIST_PAGE_SIZE = 1000;
+function createSlackEndpointManagement(endpoint) {
+    const requireClient = () => {
+        const client = endpoint.client;
+        if (!client)
+            throw new Error('Slack client not connected');
+        return client;
+    };
+    return Object.freeze({
+        // Slack 无"群"概念：public channel 归一为 group（channel 语义由 listChannels 之外省略，
+        // Slack channel 本身就是会话载体，避免同一批数据在两个列表里重复）。
+        async listGroups() {
+            const client = requireClient();
+            const groups = [];
+            let cursor;
+            do {
+                const page = await client.conversations.list({
+                    types: 'public_channel',
+                    exclude_archived: true,
+                    limit: SLACK_LIST_PAGE_SIZE,
+                    ...(cursor ? { cursor } : {}),
+                });
+                for (const value of page.channels ?? []) {
+                    const channel = asRecord(value);
+                    const id = typeof channel.id === 'string' ? channel.id : '';
+                    if (!id)
+                        continue;
+                    groups.push({ group_id: id, name: String(channel.name ?? id) });
+                }
+                cursor = page.response_metadata?.next_cursor || undefined;
+            } while (cursor);
+            return groups;
+        },
+        // Slack 无"好友"概念：workspace 成员归一为 friend；nickname 取 real_name 回退 name。
+        async listFriends() {
+            const client = requireClient();
+            const friends = [];
+            let cursor;
+            do {
+                const page = await client.users.list({
+                    limit: SLACK_LIST_PAGE_SIZE,
+                    ...(cursor ? { cursor } : {}),
+                });
+                for (const value of page.members ?? []) {
+                    const user = asRecord(value);
+                    const id = typeof user.id === 'string' ? user.id : '';
+                    if (!id || user.deleted === true)
+                        continue;
+                    const profile = asRecord(user.profile);
+                    friends.push({
+                        user_id: id,
+                        nickname: String(profile.real_name ?? user.real_name ?? user.name ?? id),
+                        remark: '',
+                    });
+                }
+                cursor = page.response_metadata?.next_cursor || undefined;
+            } while (cursor);
+            return friends;
+        },
+        // conversations.members 只回 user id 列表（平台形状），逐 user 拉 profile 成本由调用方决定。
+        async listGroupMembers(groupId) {
+            const client = requireClient();
+            const result = await client.conversations.members({ channel: groupId });
+            return result.members ?? [];
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}

package/lib/slack-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const slackEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

package/lib/slack-endpoint-commands.js

@@ -0,0 +1,18 @@
+/**
+ * `slack endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { slackRuntimeStateToken } from './slack-runtime-state.js';
+export const slackEndpointCommands = createEndpointCommands({
+    adapterKey: 'slack',
+    adapterDisplayName: 'Slack',
+    fields: [
+        { key: 'token', required: true, env: true, description: 'Bot User OAuth Token（xoxb-...）' },
+        { key: 'signingSecret', env: true, description: '签名密钥（HTTP Events，socketMode: false 必填）' },
+        { key: 'appToken', env: true, description: 'App-Level Token（xapp-...，Socket Mode）' },
+    ],
+    running: (use) => use(slackRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/lib/slack-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const slackRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/slack-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * Slack 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `slack endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
+export const slackRuntimeStateToken = defineEndpointRuntimeStateToken('slack');

package/lib/webhook.js

@@ -24,9 +24,10 @@ export async function handleSlackWebhookRequest(request, response, handler) {
             const params = new URLSearchParams(rawBody);
             const payloadStr = params.get('payload');
             if (payloadStr) {
+                const payload = JSON.parse(payloadStr);
                 response.writeHead(200);
                 response.end('');
-                handler.admitInteraction(JSON.parse(payloadStr));
+                handler.admitInteraction(payload);
                 return;
             }
             const body = Object.fromEntries(params);
@@ -63,7 +64,9 @@ export async function handleSlackWebhookRequest(request, response, handler) {
     }
     catch (error) {
         logger.error('Slack webhook error:', error);
-        response.writeHead(200);
-        response.end('');
+        if (!response.headersSent) {
+            response.writeHead(200);
+            response.end('');
+        }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-slack",
-  "version": "4.1.1",
+  "version": "5.0.1",
   "description": "Zhin.js Slack adapter for Plugin Runtime (Socket Mode / HTTP Events)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,20 +34,21 @@
   "dependencies": {
     "@slack/socket-mode": "^2.0.3",
     "@slack/web-api": "^7.17.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -65,11 +66,12 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.4",
-    "zhin.js": "4.1.3"
+    "@zhin.js/agent": "1.0.6",
+    "zhin.js": "5.0.1"
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -95,6 +97,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,12 +1,16 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
 import { registerSlackPlatformPermitChecker } from './src/platform-permit.js';
+import { slackRuntimeStateToken } from './src/slack-runtime-state.js';
 
 export default definePlugin({
   name: 'slack',
   metadata: {
     displayName: 'Slack Adapter',
   },
-  setup() {
+  setup(context) {
+    // 运行中 endpoint 注册表（slack endpoint list 的"运行中"数据源）
+    context.resources.provide(slackRuntimeStateToken, createEndpointRuntimeState());
     // 平台权限门禁：workspace_owner / channel_manager 等（agent 工具 platformPermit）
     return registerSlackPlatformPermitChecker();
   },

package/schema.json

@@ -3,22 +3,6 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "default": "slack-bot"
-    },
-    "token": {
-      "type": "string",
-      "description": "Bot User OAuth Token (xoxb-...)"
-    },
-    "signingSecret": {
-      "type": "string",
-      "description": "Required for HTTP Events API (socketMode: false)"
-    },
-    "appToken": {
-      "type": "string",
-      "description": "App-Level Token (xapp-...) for Socket Mode"
-    },
     "socketMode": {
       "type": "boolean",
       "default": true,
@@ -32,7 +16,44 @@
       "type": "number",
       "default": 15000,
       "description": "Socket Mode client ping timeout (ms)"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Slack bot name"
+          },
+          "token": {
+            "type": "string",
+            "description": "Bot User OAuth Token (xoxb-...)"
+          },
+          "signingSecret": {
+            "type": "string",
+            "description": "Required for HTTP Events API (socketMode: false)"
+          },
+          "appToken": {
+            "type": "string",
+            "description": "App-Level Token (xapp-...) for Socket Mode"
+          }
+        },
+        "required": [
+          "name",
+          "token"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
   },
-  "required": ["token"]
+  "required": [
+    "endpoints"
+  ]
 }

package/src/endpoint.ts

@@ -3,7 +3,12 @@
  */
 import { SocketModeClient } from '@slack/socket-mode';
 import { WebClient } from '@slack/web-api';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type {
+  EndpointFriend,
+  EndpointGroup,
+  EndpointInstance,
+  EndpointManagement,
+} from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -57,9 +62,19 @@ export interface SlackWebClientLike extends SlackChatClient {
     rename(opts: { channel: string; name: string }): Promise<unknown>;
     members(opts: { channel: string }): Promise<{ members?: string[] }>;
     info(opts: { channel: string }): Promise<{ channel?: unknown }>;
+    list(opts?: {
+      types?: string;
+      limit?: number;
+      cursor?: string;
+      exclude_archived?: boolean;
+    }): Promise<{ channels?: unknown[]; response_metadata?: { next_cursor?: string } }>;
   };
   users: {
     info(opts: { user: string }): Promise<{ user?: unknown }>;
+    list(opts?: {
+      limit?: number;
+      cursor?: string;
+    }): Promise<{ members?: unknown[]; response_metadata?: { next_cursor?: string } }>;
   };
   reactions: {
     add(opts: { channel: string; timestamp: string; name: string }): Promise<unknown>;
@@ -97,11 +112,17 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
   #open = false;
   #started = false;
   #unregisterAgent?: () => void;
+  readonly management: EndpointManagement = createSlackEndpointManagement(this);
 
   constructor(options: SlackEndpointOptions) {
     this.#options = options;
   }
 
+  /** Console 展示 / AdapterIndex live name（多 endpoint 时与 entry name 一致）。 */
+  get name(): string {
+    return this.#options.config.name;
+  }
+
   get client(): SlackWebClientLike | undefined {
     return this.#client;
   }
@@ -288,7 +309,14 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
   }
 
   trackMessageChannel(ts: string, channel: string): void {
-    if (ts && channel) this.#messageChannelMap.set(ts, channel);
+    if (!ts || !channel) return;
+    // LRU：超 1024 条淘汰最久未更新的记录，避免无界增长。
+    if (this.#messageChannelMap.has(ts)) this.#messageChannelMap.delete(ts);
+    this.#messageChannelMap.set(ts, channel);
+    if (this.#messageChannelMap.size > 1024) {
+      const oldest = this.#messageChannelMap.keys().next().value;
+      if (oldest != null) this.#messageChannelMap.delete(oldest);
+    }
   }
 
   resolveMessageRef(messageId: string, channelHint?: string): { channel: string; ts: string } | null {
@@ -395,7 +423,12 @@ export class SlackEndpoint implements EndpointInstance, SlackWebhookHandler {
 
   async #startSocket(): Promise<void> {
     const { config } = this.#options;
-    if (!config.appToken) throw new Error('Socket Mode requires appToken');
+    if (!config.appToken) {
+      throw new Error('Slack Socket Mode 需要 appToken（xapp- 前缀的 App-Level Token）；注意 bot token 填 token 字段（xoxb- 前缀），两者不可混用');
+    }
+    if (!config.appToken.startsWith('xapp-')) {
+      throw new Error(`Slack appToken 格式不正确：Socket Mode 需要 xapp- 前缀的 App-Level Token（当前看起来是 ${config.appToken.slice(0, 5)}…，xoxb- 是 bot token，请填到 token 字段）`);
+    }
     this.#socket = this.#options.createSocket?.({
       appToken: config.appToken,
       clientPingTimeout: config.clientPingTimeout,
@@ -428,3 +461,76 @@ function parseSendTarget(target: string): { channel: string; threadTs?: string }
   }
   return { channel: target };
 }
+
+/** Slack Web API 分页上限（每页 1000，cursor 翻页直到 next_cursor 为空）。 */
+const SLACK_LIST_PAGE_SIZE = 1000;
+
+function createSlackEndpointManagement(endpoint: SlackEndpoint): EndpointManagement {
+  const requireClient = (): SlackWebClientLike => {
+    const client = endpoint.client;
+    if (!client) throw new Error('Slack client not connected');
+    return client;
+  };
+  return Object.freeze<EndpointManagement>({
+    // Slack 无"群"概念：public channel 归一为 group（channel 语义由 listChannels 之外省略，
+    // Slack channel 本身就是会话载体，避免同一批数据在两个列表里重复）。
+    async listGroups(): Promise<readonly EndpointGroup[]> {
+      const client = requireClient();
+      const groups: EndpointGroup[] = [];
+      let cursor: string | undefined;
+      do {
+        const page = await client.conversations.list({
+          types: 'public_channel',
+          exclude_archived: true,
+          limit: SLACK_LIST_PAGE_SIZE,
+          ...(cursor ? { cursor } : {}),
+        });
+        for (const value of page.channels ?? []) {
+          const channel = asRecord(value);
+          const id = typeof channel.id === 'string' ? channel.id : '';
+          if (!id) continue;
+          groups.push({ group_id: id, name: String(channel.name ?? id) });
+        }
+        cursor = page.response_metadata?.next_cursor || undefined;
+      } while (cursor);
+      return groups;
+    },
+    // Slack 无"好友"概念：workspace 成员归一为 friend；nickname 取 real_name 回退 name。
+    async listFriends(): Promise<readonly EndpointFriend[]> {
+      const client = requireClient();
+      const friends: EndpointFriend[] = [];
+      let cursor: string | undefined;
+      do {
+        const page = await client.users.list({
+          limit: SLACK_LIST_PAGE_SIZE,
+          ...(cursor ? { cursor } : {}),
+        });
+        for (const value of page.members ?? []) {
+          const user = asRecord(value);
+          const id = typeof user.id === 'string' ? user.id : '';
+          if (!id || user.deleted === true) continue;
+          const profile = asRecord(user.profile);
+          friends.push({
+            user_id: id,
+            nickname: String(profile.real_name ?? user.real_name ?? user.name ?? id),
+            remark: '',
+          });
+        }
+        cursor = page.response_metadata?.next_cursor || undefined;
+      } while (cursor);
+      return friends;
+    },
+    // conversations.members 只回 user id 列表（平台形状），逐 user 拉 profile 成本由调用方决定。
+    async listGroupMembers(groupId: string): Promise<readonly string[]> {
+      const client = requireClient();
+      const result = await client.conversations.members({ channel: groupId });
+      return result.members ?? [];
+    },
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? value as Record<string, unknown>
+    : {};
+}

package/src/slack-endpoint-commands.ts

@@ -0,0 +1,19 @@
+/**
+ * `slack endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { slackRuntimeStateToken } from './slack-runtime-state.js';
+
+export const slackEndpointCommands = createEndpointCommands({
+  adapterKey: 'slack',
+  adapterDisplayName: 'Slack',
+  fields: [
+    { key: 'token', required: true, env: true, description: 'Bot User OAuth Token（xoxb-...）' },
+    { key: 'signingSecret', env: true, description: '签名密钥（HTTP Events，socketMode: false 必填）' },
+    { key: 'appToken', env: true, description: 'App-Level Token（xapp-...，Socket Mode）' },
+  ],
+  running: (use) => use(slackRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/src/slack-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * Slack 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `slack endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
+
+export const slackRuntimeStateToken = defineEndpointRuntimeStateToken('slack');

package/src/webhook.ts

@@ -56,9 +56,10 @@ export async function handleSlackWebhookRequest(
       const params = new URLSearchParams(rawBody);
       const payloadStr = params.get('payload');
       if (payloadStr) {
+        const payload = JSON.parse(payloadStr) as SlackInteractionPayload;
         response.writeHead(200);
         response.end('');
-        handler.admitInteraction(JSON.parse(payloadStr) as SlackInteractionPayload);
+        handler.admitInteraction(payload);
         return;
       }
       const body = Object.fromEntries(params) as unknown as SlackSlashCommand;
@@ -97,7 +98,9 @@ export async function handleSlackWebhookRequest(
     response.end('');
   } catch (error) {
     logger.error('Slack webhook error:', error);
-    response.writeHead(200);
-    response.end('');
+    if (!response.headersSent) {
+      response.writeHead(200);
+      response.end('');
+    }
   }
 }