@zhin.js/adapter-slack 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 4.1.0
+
+### Minor Changes
+
+- 872c583: Slack 适配器 Phase 1/2：mrkdwn 出站、长消息切分、斜杠/按钮 ephemeral 反馈、入站 mrkdwn→Markdown、editMessage 对齐 core。
+
+  Logger 表格日志与 string-width 列宽；Agent AI Handler 框线表格与 introspection/MCP 导出；Core side-event 归一化；Schedule 时区规划；多适配器 side-event 与 API surface 更新。
+
+### Patch Changes
+
+- 872c583: fix: 代码格式优化
+- Updated dependencies [872c583]
+- Updated dependencies [872c583]
+  - @zhin.js/agent@1.0.3
+  - @zhin.js/host-router@2.0.3
+  - @zhin.js/logger@1.0.74
+  - zhin.js@4.1.2
+
 ## 4.0.1
 
 ### Patch Changes

package/README.md

@@ -1,32 +1,27 @@
 # @zhin.js/adapter-slack
 
-Slack adapter for zhin.js framework.
+Zhin.js 的 Slack 适配器，支持消息收发、Block Kit 交互与 Assistant API。
 
-## Installation
+## 安装
 
 ```bash
 pnpm add @zhin.js/adapter-slack
 ```
 
-## Configuration
+## 配置
 
-通过 **`socketMode`** 选择连接方式（默认 `true` 时为 Socket Mode）。
+通过 **`socketMode`** 选择连接方式。
 
 ### 模式对比
 
 | 模式 | `socketMode` | 适用场景 | 额外字段 |
 |------|--------------|----------|----------|
 | **Socket Mode** | `true`（推荐本地/内网） | 无需公网 URL，WebSocket 长连接 | `appToken`（`xapp-...`） |
-| **HTTP Events** | `false` | 生产环境，有公网 HTTPS | `port`（Bolt 监听端口） |
+| **HTTP Events** | `false` | 生产环境，有公网 HTTPS | 共享 zhin router 端口 8086 |
 
-#### HTTP 模式前置条件
+### Socket Mode（推荐开发环境）
 
-- Slack App 中配置 **Event Subscriptions** 的 Request URL（须公网 HTTPS 可达）
-- 启用对应 Endpoint Events（`message.*`、`app_mention` 等）
-- 防火墙 / 反向代理放行 `port`
-- **不需要** `@zhin.js/host-router`（由 `@slack/bolt` 自行监听）
-
-### Socket Mode (Recommended for Development)
+可选 `clientPingTimeout`（毫秒，默认 `15000`）用于调整 Socket Mode 客户端心跳超时，减少误报 pong 警告。
 
 ```typescript
 import { defineConfig } from 'zhin.js'
@@ -45,7 +40,9 @@ export default defineConfig({
 })
 ```
 
-### HTTP Mode (For Production with Public URL)
+### HTTP 模式（生产环境，使用 zhin Router）
+
+HTTP 模式共享 zhin.js 内置的 Koa Router（默认端口 8086），无需额外监听端口。
 
 ```typescript
 import { defineConfig } from 'zhin.js'
@@ -57,60 +54,128 @@ export default defineConfig({
       context: 'slack',
       token: 'xoxb-your-bot-token',
       signingSecret: 'your-signing-secret',
-      socketMode: false,
-      port: 3000
+      socketMode: false
     }
   ]
 })
 ```
 
-## Features
-
-- ✅ Send and receive text messages
-- ✅ Support for rich media (images, files)
-- ✅ Message formatting (Slack mrkdwn)
-- ✅ Reply to messages and threads
-- ✅ Mentions (@user, #channel)
-- ✅ Links and attachments
-- ✅ Socket Mode and HTTP mode
-- ✅ Private messages and channels
-
-## Setting Up Your Slack App
-
-1. Go to [Slack API](https://api.slack.com/apps)
-2. Create a new app
-3. Add Endpoint Token Scopes:
-   - `chat:write` - Send messages
-   - `chat:write.public` - Send messages to public channels
-   - `channels:read` - View basic channel info
-   - `channels:history` - View messages in channels
-   - `groups:read` - View basic private channel info
-   - `groups:history` - View messages in private channels
-   - `im:read` - View basic direct message info
-   - `im:history` - View messages in direct messages
-   - `mpim:read` - View basic group direct message info
-   - `mpim:history` - View messages in group direct messages
-   - `users:read` - View user info
-   - `files:read` - View files
-   - `files:write` - Upload files
-4. Enable Socket Mode (if using Socket Mode):
-   - Go to Socket Mode settings
-   - Enable Socket Mode
-   - Generate an app-level token with `connections:write` scope
-5. Subscribe to events:
-   - `message.channels` - Messages in public channels
-   - `message.groups` - Messages in private channels
-   - `message.im` - Direct messages
-   - `message.mpim` - Group direct messages
-   - `app_mention` - When the bot is mentioned
-6. Install the app to your workspace
-7. Copy the Endpoint User OAuth Token (`xoxb-...`)
-8. Copy the Signing Secret
-9. Copy the App-Level Token (`xapp-...`) if using Socket Mode
-
-## Usage Examples
-
-### Basic Message Handling
+**HTTP 模式前置条件：**
+
+- Slack App 中配置 **Event Subscriptions** 的 Request URL 为 `https://your-domain:8086/slack/events`
+- 配置 **Interactivity & Shortcuts** 的 Request URL 为同一地址
+- 配置 **Slash Commands** 的 Request URL 为同一地址
+- 防火墙 / 反向代理放行端口
+
+## 功能特性
+
+- 收发文本消息
+- 富媒体（图片、文件），经 `files.uploadV2` 上传
+- 消息格式化（Slack mrkdwn + Block Kit）
+- 回复消息与线程（`thread_ts`）
+- 提及（@用户、#频道）
+- 链接与附件
+- Socket Mode 与 HTTP 模式（共享 zhin router）
+- 私信与频道消息
+- Block Kit 交互按钮（`keyboard` 片段 → 原生 Slack 按钮）
+- 斜杠命令 → zhin Command 映射
+- 消息编辑（`$editMessage` / `chat.update`）
+- Notice 事件映射（`member_joined`、`reaction_added`、`pin_added` 等）
+- Assistant API 支持（`assistant_thread_started` 事件）
+- 出站 Markdown → Slack mrkdwn 自动转换（`**粗体**` → `*粗体*`）
+- 长消息自动分段（超 2900 字符切 section；超 48 blocks 分多条发送）
+- 斜杠命令即时 ephemeral 反馈（「处理中…」）；最终回复仍 `chat.postMessage`
+- 按钮点击即时 ephemeral 反馈（「已收到」）
+- 入站 Slack mrkdwn → 通用 Markdown（粗体/斜体/删除线/代码/链接）
+
+## 消息格式
+
+### 出站（Markdown → mrkdwn）
+
+AI 或命令输出的通用 Markdown（如 `**粗体**`、`*斜体*`）会自动转换为 Slack mrkdwn，并通过 Block Kit `section` 块发送，确保在 Slack 客户端正确渲染。
+
+### 长消息
+
+- 单条 `section` 文本超过约 2900 字符时自动切分为多个 section
+- 单条消息 blocks 超过 48 个时自动拆分为多条 `chat.postMessage`
+
+### 入站（mrkdwn → Markdown）
+
+用户发送的 Slack mrkdwn 在解析为 `text` 段前会转换为通用 Markdown：
+
+| Slack mrkdwn | 通用 Markdown |
+|--------------|---------------|
+| `*bold*` | `**bold**` |
+| `_italic_` | `*italic*` |
+| `~strike~` | `~~strike~~` |
+| `` `code` `` | 保持 |
+| `<url\|text>` | `[text](url)` |
+
+`<@U>` / `<#C>` 等特殊段仍由专用解析器处理，不在此转换。该转换为启发式，复杂嵌套格式不保证完美往返。
+
+## 交互反馈
+
+### 斜杠命令
+
+收到斜杠命令后，适配器会立即向触发者发送 ephemeral「处理中…」（仅触发者可见）。命令处理完成后的最终回复仍通过 `chat.postMessage` 发送到频道，与现有 `$reply` 行为一致。
+
+### Block Kit 按钮
+
+用户点击 `block_actions` 按钮后，适配器会向点击者发送 ephemeral「已收到」。如需在线程中回复，仍通过 `sendMessage`（`thread_ts`）发送。
+
+## 创建 Slack App
+
+1. 前往 [Slack API](https://api.slack.com/apps)
+2. 创建新应用
+3. 添加 Bot Token Scopes：
+   - `chat:write` — 发送消息
+   - `chat:write.public` — 向公开频道发送消息
+   - `channels:read` — 查看频道基本信息
+   - `channels:history` — 查看频道消息历史
+   - `channels:manage` — 管理频道
+   - `groups:read` — 查看私有频道基本信息
+   - `groups:history` — 查看私有频道消息历史
+   - `im:read` — 查看私信基本信息
+   - `im:history` — 查看私信消息历史
+   - `mpim:read` — 查看群组私信基本信息
+   - `mpim:history` — 查看群组私信消息历史
+   - `users:read` — 查看用户信息
+   - `files:read` — 查看文件
+   - `files:write` — 上传文件
+   - `reactions:read` — 查看表情回应
+   - `reactions:write` — 添加/移除表情回应
+   - `pins:read` — 查看置顶项
+   - `pins:write` — 置顶/取消置顶消息
+   - `commands` — 添加斜杠命令
+   - `assistant:write` — Assistant API（若使用 AI 功能）
+4. 启用 Socket Mode（若使用 Socket Mode）：
+   - 进入 Socket Mode 设置
+   - 启用 Socket Mode
+   - 生成带 `connections:write` scope 的应用级 Token
+5. 订阅 Bot 事件：
+   - `message.channels` — 公开频道消息
+   - `message.groups` — 私有频道消息
+   - `message.im` — 私信
+   - `message.mpim` — 群组私信
+   - `app_mention` — Bot 被 @ 提及时
+   - `member_joined_channel` — 用户加入频道
+   - `member_left_channel` — 用户离开频道
+   - `reaction_added` — 添加表情回应
+   - `reaction_removed` — 移除表情回应
+   - `channel_archive` / `channel_unarchive`
+   - `channel_rename` / `channel_created` / `channel_deleted`
+   - `pin_added` / `pin_removed`
+   - `team_join` — 新用户加入工作区
+   - `assistant_thread_started`（若使用 Assistant API）
+   - `assistant_thread_context_changed`（若使用 Assistant API）
+6. 将应用安装到工作区
+7. 复制 Bot User OAuth Token（`xoxb-...`）
+8. 复制 Signing Secret
+9. 若使用 Socket Mode，复制 App-Level Token（`xapp-...`）
+
+## 使用示例
+
+### 基础消息处理
 
 ```typescript
 import { usePlugin, MessageCommand } from 'zhin.js'
@@ -124,69 +189,113 @@ addCommand(new MessageCommand('hello')
 )
 ```
 
-### Send Rich Messages
+### 发送带 Block Kit 按钮的富消息
 
 ```typescript
-addCommand(new MessageCommand('info')
+addCommand(new MessageCommand('vote')
   .action(async (message) => {
     return [
-      { type: 'text', data: { text: '*Bold* and _italic_ text\n' } },
-      { type: 'link', data: { url: 'https://slack.com', text: 'Visit Slack' } }
+      { type: 'text', data: { text: 'What do you think?' } },
+      {
+        type: 'keyboard',
+        data: {
+          rows: [[
+            { label: 'Approve', id: 'vote_yes', style: 'primary' },
+            { label: 'Reject', id: 'vote_no', style: 'danger' },
+          ]]
+        }
+      }
     ]
   })
 )
 ```
 
-### Mention Users
+### 在线程中回复
 
 ```typescript
-addCommand(new MessageCommand('mention <userId:text>')
-  .action(async (message, result) => {
-    return [
-      { type: 'at', data: { id: result.params.userId } },
-      { type: 'text', data: { text: ' Hello!' } }
-    ]
+addCommand(new MessageCommand('thread')
+  .action(async (message) => {
+    await message.$reply('This is a threaded reply!', true)
   })
 )
 ```
 
-### Reply in Thread
+### 编辑消息
+
+适配器支持 core `EditMessageOptions` 契约。`messageId` 优先使用 `channel:ts` 格式；若仅为 `ts`，则使用 `options.id` 作为 channel。
 
 ```typescript
-addCommand(new MessageCommand('thread')
-  .action(async (message) => {
-    // Reply in a thread by passing the message timestamp
-    await message.$reply('This is a threaded reply!', true)
-  })
-)
+const adapter = inject('slack')
+
+// 旧 API（薄封装，仍可用）
+await adapter.editMessage('my-slack-bot', 'C001', '1700000000.000000', [
+  { type: 'text', data: { text: 'Updated message content' } }
+])
+
+// core 契约（推荐）
+await adapter.editMessage({
+  messageId: 'C001:1700000000.000000',
+  context: 'slack',
+  endpoint: 'my-slack-bot',
+  id: 'C001',
+  type: 'group',
+  content: [{ type: 'text', data: { text: 'Updated message content' } }],
+})
 ```
 
-## Slack-Specific Features
+## Slack MCP Server 集成
+
+如果你的 zhin 实例使用了 `@zhin.js/agent`（AI 功能），可以将 Slack MCP Server 配置为 AI 的工具来源：
+
+```typescript
+export default defineConfig({
+  ai: {
+    mcpServers: {
+      slack: {
+        command: 'npx',
+        args: ['-y', '@anthropic/slack-mcp-server'],
+        env: {
+          SLACK_BOT_TOKEN: 'xoxb-your-bot-token',
+          SLACK_TEAM_ID: 'T0123456789'
+        }
+      }
+    }
+  }
+})
+```
 
-### Slack Formatting
+这将使 AI Agent 获得搜索 Slack 消息、管理频道等额外能力。
 
-Slack uses mrkdwn format:
-- `*bold*` for **bold**
-- `_italic_` for *italic*
-- `~strike~` for ~~strikethrough~~
-- `` `code` `` for `code`
-- `> quote` for blockquotes
+## Notice 事件映射
 
-### User and Channel Mentions
+| Slack 事件 | zhin Notice 类型 |
+|---|---|
+| `member_joined_channel` | `notice.group.member_increase` |
+| `member_left_channel` | `notice.group.member_decrease` |
+| `reaction_added` / `reaction_removed` | `notice.group.emoji_reaction` |
+| `message_deleted` | `notice.group.recall` |
+| `team_join` | `notice.friend.increase` |
+| `channel_archive` | `notice.slack.channel_archive` |
+| `pin_added` / `pin_removed` | `notice.slack.pin_added` / `notice.slack.pin_removed` |
 
-The adapter automatically converts:
-- `<@U12345678>` to user mentions
-- `<#C12345678>` to channel mentions
+## AI 工具
 
-### File Uploads
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 平台工具（11 个） | `agent/tools/`（`slack_*`：邀请、话题、反应、置顶等） |
+| 技能说明 | `agent/skills/slack.md` |
+| 群管标准工具 | `createSceneManagementTools()` |
 
-Upload files using the `file` segment type with a local file path.
 
-## Limitations
+## 限制
 
-- Message recall requires channel information (not available from message ID alone)
-- Some Slack features like interactive components require additional setup
+- 入站 mrkdwn → Markdown 为启发式转换，复杂嵌套格式不保证完美往返
+- Modals / `view_submission` / `view_closed` — 暂不支持
+- Select menus / options load — 暂不支持
+- File 事件全系列（`file_created` / `file_shared` 等）— 暂不支持
+- OAuth 安装流程 — 暂不支持
 
-## License
+## 许可证
 
 MIT

package/{skills/slack/SKILL.md → agent/skills/slack.md}

@@ -34,6 +34,7 @@ tools:
   - slack_user_info
   - slack_set_purpose
   - slack_unarchive
+  - slack_edit_message
   - slack_kick_member
   - slack_set_group_name
   - slack_list_members
@@ -83,6 +84,7 @@ Slack 频道有两个元信息字段：
 | `slack_unpin_message` | 取消置顶 | — |
 | `slack_add_reaction` | 添加表情反应 | — |
 | `slack_remove_reaction` | 移除表情反应 | — |
+| `slack_edit_message` | 编辑消息 | 通过 chat.update 修改已发消息 |
 
 ## 易错点
 

package/agent/tools/add_reaction.ts

@@ -0,0 +1,26 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getSlackAgentDeps } from '../../src/slack-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  channel: string;
+  timestamp: string;
+  emoji: string;
+}>({
+  description: '给 Slack 消息添加表情反应',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    channel: z.string().describe('频道 ID'),
+    timestamp: z.string().describe('消息时间戳'),
+    emoji: z.string().describe('表情名称（不含冒号）'),
+  }),
+  platforms: ['slack'],
+  tags: ['slack'],
+  async execute({ endpoint_id, channel, timestamp, emoji }) {
+    const { getEndpoint } = getSlackAgentDeps();
+    const endpoint = getEndpoint(endpoint_id);
+    const success = await endpoint.addReaction(channel, timestamp, emoji);
+    return { success, message: success ? `已添加反应 :${emoji}:` : '操作失败' };
+  },
+});

package/agent/tools/archive_channel.ts

@@ -0,0 +1,24 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+import { getSlackAgentDeps } from '../../src/slack-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  channel: string;
+}>({
+  description: '归档 Slack 频道',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    channel: z.string().describe('频道 ID'),
+  }),
+  platforms: ['slack'],
+  tags: ['slack'],
+  permissions: [platformPermit('workspace_admin')],
+  async execute({ endpoint_id, channel }) {
+    const { getEndpoint } = getSlackAgentDeps();
+    const endpoint = getEndpoint(endpoint_id);
+    const success = await endpoint.archiveChannel(channel);
+    return { success, message: success ? '已归档频道' : '操作失败' };
+  },
+});

package/agent/tools/edit_message.ts

@@ -0,0 +1,27 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getSlackAgentDeps } from '../../src/slack-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  channel: string;
+  message_ts: string;
+  text: string;
+}>({
+  description: '编辑 Slack 消息',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    channel: z.string().describe('频道 ID'),
+    message_ts: z.string().describe('消息时间戳'),
+    text: z.string().describe('新的消息文本'),
+  }),
+  platforms: ['slack'],
+  tags: ['slack'],
+  async execute({ endpoint_id, channel, message_ts, text }) {
+    const { getAdapter } = getSlackAgentDeps();
+    await getAdapter().editMessage(endpoint_id, channel, message_ts, [
+      { type: 'text', data: { text } },
+    ]);
+    return { success: true, message: '消息已编辑' };
+  },
+});

package/agent/tools/invite_to_channel.ts

@@ -0,0 +1,26 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+import { getSlackAgentDeps } from '../../src/slack-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  channel: string;
+  users: string;
+}>({
+  description: '邀请用户加入 Slack 频道',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    channel: z.string().describe('频道 ID'),
+    users: z.string().describe('用户 ID 列表（逗号分隔）'),
+  }),
+  platforms: ['slack'],
+  tags: ['slack'],
+  permissions: [platformPermit('channel_manager')],
+  async execute({ endpoint_id, channel, users }) {
+    const { getEndpoint } = getSlackAgentDeps();
+    const endpoint = getEndpoint(endpoint_id);
+    const success = await endpoint.inviteToChannel(channel, users.split(','));
+    return { success, message: success ? '已邀请用户加入频道' : '操作失败' };
+  },
+});

package/agent/tools/pin_message.ts

@@ -0,0 +1,26 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+import { getSlackAgentDeps } from '../../src/slack-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  channel: string;
+  timestamp: string;
+}>({
+  description: '置顶 Slack 消息',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    channel: z.string().describe('频道 ID'),
+    timestamp: z.string().describe('消息时间戳'),
+  }),
+  platforms: ['slack'],
+  tags: ['slack'],
+  permissions: [platformPermit('channel_manager')],
+  async execute({ endpoint_id, channel, timestamp }) {
+    const { getEndpoint } = getSlackAgentDeps();
+    const endpoint = getEndpoint(endpoint_id);
+    const success = await endpoint.pinMessage(channel, timestamp);
+    return { success, message: success ? '已置顶消息' : '操作失败' };
+  },
+});

package/agent/tools/remove_reaction.ts

@@ -0,0 +1,26 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getSlackAgentDeps } from '../../src/slack-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  channel_id: string;
+  timestamp: string;
+  name: string;
+}>({
+  description: '移除 Slack 消息上的表情反应',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    channel_id: z.string().describe('频道 ID'),
+    timestamp: z.string().describe('消息时间戳'),
+    name: z.string().describe('表情名称（如 thumbsup、heart）'),
+  }),
+  platforms: ['slack'],
+  tags: ['slack'],
+  async execute({ endpoint_id, channel_id, timestamp, name }) {
+    const { getEndpoint } = getSlackAgentDeps();
+    const endpoint = getEndpoint(endpoint_id);
+    const success = await endpoint.removeReaction(channel_id, timestamp, name);
+    return { success, message: success ? `已移除反应 :${name}:` : '操作失败' };
+  },
+});

package/agent/tools/set_purpose.ts

@@ -0,0 +1,26 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+import { getSlackAgentDeps } from '../../src/slack-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  channel_id: string;
+  purpose: string;
+}>({
+  description: '设置 Slack 频道的用途/目的',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    channel_id: z.string().describe('频道 ID'),
+    purpose: z.string().describe('频道用途描述'),
+  }),
+  platforms: ['slack'],
+  tags: ['slack'],
+  permissions: [platformPermit('channel_manager')],
+  async execute({ endpoint_id, channel_id, purpose }) {
+    const { getEndpoint } = getSlackAgentDeps();
+    const endpoint = getEndpoint(endpoint_id);
+    const success = await endpoint.setChannelPurpose(channel_id, purpose);
+    return { success, message: success ? '频道用途已更新' : '操作失败' };
+  },
+});

package/agent/tools/set_topic.ts

@@ -0,0 +1,26 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+import { getSlackAgentDeps } from '../../src/slack-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  channel: string;
+  topic: string;
+}>({
+  description: '设置 Slack 频道话题',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    channel: z.string().describe('频道 ID'),
+    topic: z.string().describe('新话题'),
+  }),
+  platforms: ['slack'],
+  tags: ['slack'],
+  permissions: [platformPermit('channel_manager')],
+  async execute({ endpoint_id, channel, topic }) {
+    const { getEndpoint } = getSlackAgentDeps();
+    const endpoint = getEndpoint(endpoint_id);
+    const success = await endpoint.setChannelTopic(channel, topic);
+    return { success, message: success ? '已设置频道话题' : '操作失败' };
+  },
+});

package/agent/tools/unarchive.ts

@@ -0,0 +1,24 @@
+import { defineTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+import { getSlackAgentDeps } from '../../src/slack-agent-deps.js';
+
+export default defineTool<{
+  endpoint_id: string;
+  channel_id: string;
+}>({
+  description: '恢复已归档的 Slack 频道',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    channel_id: z.string().describe('频道 ID'),
+  }),
+  platforms: ['slack'],
+  tags: ['slack'],
+  permissions: [platformPermit('workspace_admin')],
+  async execute({ endpoint_id, channel_id }) {
+    const { getEndpoint } = getSlackAgentDeps();
+    const endpoint = getEndpoint(endpoint_id);
+    const success = await endpoint.unarchiveChannel(channel_id);
+    return { success, message: success ? '频道已恢复' : '操作失败' };
+  },
+});