slack

Slack Web API 工具

通过 Web API 与 Slack 交互：读取、写入、搜索、添加表情回应、置顶和管理对话。

重要：首次使用初始化

执行任何 Slack 操作之前，请检查模式配置文件是否存在：

cat ~/.agents/config/slack/config.env

如果文件不存在（或不包含 SLACK_MODE），必须询问用户想使用哪种模式。提供以下三个选项：

1. Token（仅限 macOS）：直接从 Chrome 提取会话令牌。速度最快。需要打开 Slack 的 Chrome、启用 AppleScript，并安装 uvx。
2. Browser（跨平台）：使用本地 Playwright 浏览器进行 API 调用。适用于 macOS、Linux 和 Windows。需要 Node.js 18+。支持 SSO 和双重身份验证登录。
3. Auto-detect（推荐）：如果存在 Playwright 会话，则自动使用浏览器模式；否则回退到令牌模式。兼具两种模式的优点。

用户选择模式后，立即保存：

mkdir -p ~/.agents/config/slack
echo 'SLACK_MODE=<selected_value>' > ~/.agents/config/slack/config.env

其中，<selected_value> 为 token、browser 或 auto。

保存后，切勿再次询问。 后续每次调用时，配置文件都会存在，工具将自动使用已保存的模式。

如果用户选择了 browser 模式，还要运行浏览器会话设置：

{SKILL_DIR}/scripts/slack-browser-session.sh login-manual

这会打开一个可见的浏览器供用户登录 Slack（支持 SSO/双重身份验证）。会话将被保存，并用于之后的所有 API 调用。

---

模式选择

此工具支持三种模式。通过 ~/.agents/config/slack/config.env 或 SLACK_MODE 环境变量设置：

模式	值	行为
Token	token	使用 Chrome 会话令牌直接调用 curl。速度快。仅限 macOS。
Browser	browser	通过本地 Playwright 浏览器会话进行 API 调用。跨平台。
Auto-detect	auto	存在会话时使用浏览器；身份验证失败时回退到令牌模式。（默认）

配置模式

选项 1：配置文件（持久生效）

echo 'SLACK_MODE=token' > ~/.agents/config/slack/config.env
# or
echo 'SLACK_MODE=browser' > ~/.agents/config/slack/config.env
# or
echo 'SLACK_MODE=auto' > ~/.agents/config/slack/config.env

选项 2：环境变量（按次覆盖）

SLACK_MODE=browser slack-api.sh conversations.history channel=C041RSY6DN2 limit=20

环境变量的优先级高于配置文件。

配置和状态目录

所有工具配置和状态均存放在 ~/.agents/config/slack/ 下：

文件	用途
config.env	模式选择（SLACK_MODE=auto|token|browser）
tokens.env	缓存的会话令牌（xoxc、xoxd、user-agent）
browser-session	活动浏览器会话 ID
sessions/<id>/storageState.json	Playwright 会话 Cookie 和 localStorage

首次使用时会自动创建此目录。

API 封装脚本

所有调用都通过一个统一脚本执行：

{SKILL_DIR}/scripts/slack-api.sh <method> [key=value ...]

其中 {SKILL_DIR} 是加载此工具时提供的基础目录（例如 ~/.agents/skills/slack）。

脚本会根据配置自动路由到相应模式。完整的方法参考请参阅 references/api-methods.md。

Token 模式（macOS）

Token 模式会从正在运行的 Chrome 浏览器中提取会话令牌，并直接通过 curl 调用 Slack Web API。

先决条件：

• 正在运行且已打开 app.slack.com 上 Slack 的 Chrome
• Chrome > View > Developer > Allow JavaScript from Apple Events
• 已安装 uvx（brew install uv）

无需手动设置。首次 API 调用时会自动提取令牌。

浏览器模式（跨平台）

浏览器模式使用本地 Playwright Chromium 实例来维持 Slack 会话。API 调用通过浏览器上下文中的 fetch() 发起，因此无需提取令牌。此模式适用于 macOS、Linux 和 Windows。

前置条件：

• 已安装 Node.js 18+
• Playwright 会在首次使用时自动安装（下载 Chromium，约 150 MB）

详细文档请参阅 references/browser-mode.md。

快速开始（浏览器模式）

# 1. 将模式设为 browser
echo 'SLACK_MODE=browser' > ~/.agents/config/slack/config.env

# 2. 启动浏览器会话并手动登录（支持 SSO/2FA）
{SKILL_DIR}/scripts/slack-browser-session.sh login-manual

# 或：使用邮箱和密码自动登录
{SKILL_DIR}/scripts/slack-browser-session.sh start
{SKILL_DIR}/scripts/slack-browser-session.sh login [email protected] mypassword

# 3. 验证登录是否成功
{SKILL_DIR}/scripts/slack-browser-session.sh status

# 4. 发起 API 调用（使用同一脚本，自动通过浏览器转发）
{SKILL_DIR}/scripts/slack-api.sh conversations.history channel=C041RSY6DN2 limit=20

# 5. 完成后关闭
{SKILL_DIR}/scripts/slack-browser-session.sh stop

UI 自动化（API 功能缺口）

浏览器模式还支持直接与 Slack 网页版 UI 交互，以使用缺少 API 支持的功能：

# 获取会话 ID
SESSION_ID=$({SKILL_DIR}/scripts/slack-browser-session.sh get)

# 前往指定频道
node {SKILL_DIR}/scripts/playwright-bridge.js --function interact --session $SESSION_ID \
  --input '{"action": "goto", "url": "https://app.slack.com/client/TEAM_ID/CHANNEL_ID"}'

# 获取快照以查看可交互元素
node {SKILL_DIR}/scripts/playwright-bridge.js --function snapshot --session $SESSION_ID --input '{}'

# 使用快照中的 @e 引用与 UI 元素交互
node {SKILL_DIR}/scripts/playwright-bridge.js --function interact --session $SESSION_ID \
  --input '{"action": "click", "ref": "@e5"}'

# 截取屏幕截图以进行视觉验证
node {SKILL_DIR}/scripts/playwright-bridge.js --function screenshot --session $SESSION_ID --input '{}'

UI 自动化的使用场景：

• 创建和编辑 Canvas（无公开 API）
• Huddle 交互（无 API）
• 配置 Workflow Builder
• 发送 Slack Connect 邀请
• 管理和设置页面
• 通过屏幕截图进行可视化消息验证

解析 Slack URL

从 Slack URL 中提取频道和时间戳：

https://{WORKSPACE}.slack.com/archives/{CHANNEL_ID}/p{TIMESTAMP_WITHOUT_DOT}

在时间戳的最后 6 位数字前插入一个点：

• URL：p1770725748342899 -> ts：1770725748.342899

对于线程消息，URL 中可能包含 ?thread_ts= 参数。

读取操作

读取线程

slack-api.sh conversations.replies channel=CHANNEL_ID ts=THREAD_TS limit=100

读取频道历史记录

slack-api.sh conversations.history channel=CHANNEL_ID limit=20

可选参数：oldest / latest（Unix 时间戳），用于限定时间范围。

搜索消息

slack-api.sh search.messages query="search terms" count=10

修饰符：in:#channel、from:@user、before:YYYY-MM-DD、after:YYYY-MM-DD、has:link、has:reaction、has:pin。

按名称查找频道

slack-api.sh conversations.list types=public_channel limit=200 | python3 -c "import sys,json; channels=json.load(sys.stdin).get('channels',[]); matches=[c for c in channels if 'TARGET' in c['name']]; [print(f\"{c['id']} #{c['name']}\") for c in matches]"

查找用户信息

slack-api.sh users.info user=USER_ID

名称：.user.real_name 或 .user.profile.display_name。

列出置顶项目

slack-api.sh pins.list channel=CHANNEL_ID

列出频道成员

slack-api.sh conversations.members channel=CHANNEL_ID limit=100

写入操作

重要：执行任何写入操作前都必须获得确认。

发送、编辑、删除消息，添加／移除表情回应，或置顶／取消置顶之前，务必先向用户展示预览并请求确认。预览格式如下：

收件人： #channel-name（或私信中的 @username） 消息： 完整的消息文本 操作： 发送／编辑／删除／回应／置顶（视情况而定）

发送此消息吗？（或：想修改什么吗？）

在用户明确确认之前，不要执行写入 API 调用。如果用户想修改内容，请更新预览并再次请求确认。

发送消息

对于简单的单行消息：

slack-api.sh chat.postMessage channel=CHANNEL_ID text="Hello world"

回复线程：添加 thread_ts=PARENT_TS。广播到频道：添加 reply_broadcast=true。

发送格式化的多行消息

对于包含换行、粗体、列表或其他 mrkdwn 格式的消息，请使用 blocks，而不是 text。在浏览器模式下，text 参数中的 URLSearchParams 会对换行符进行二次转义，因此使用 blocks 是发送格式化内容的可靠方式。

使用 python 构建 blocks JSON 并传递给 API：

BLOCKS=$(python3 -c "
import json
blocks = [
    {'type': 'section', 'text': {'type': 'mrkdwn', 'text': '*Bold heading*'}},
    {'type': 'section', 'text': {'type': 'mrkdwn', 'text': 'Line 1\nLine 2\nLine 3'}},
    {'type': 'section', 'text': {'type': 'mrkdwn', 'text': '1. First item\n2. Second item'}}
]
print(json.dumps(blocks))
")
slack-api.sh chat.postMessage channel=CHANNEL_ID blocks="$BLOCKS" text="Fallback text"

text 参数用于向通知以及无法呈现 blocks 的客户端提供后备文本。务必填写，并提供纯文本摘要。

每个 block 的 text 字段最多可包含 3000 个字符。对于更长的消息，请拆分为多个 section block。

编辑消息

slack-api.sh chat.update channel=CHANNEL_ID ts=MESSAGE_TS text="Updated text"

删除消息

slack-api.sh chat.delete channel=CHANNEL_ID ts=MESSAGE_TS

添加表情回应

slack-api.sh reactions.add channel=CHANNEL_ID timestamp=MESSAGE_TS name=thumbsup

表情名称不带冒号。支持肤色：thumbsup::skin-tone-3。

移除表情回应

slack-api.sh reactions.remove channel=CHANNEL_ID timestamp=MESSAGE_TS name=thumbsup

置顶消息

slack-api.sh pins.add channel=CHANNEL_ID timestamp=MESSAGE_TS

取消置顶消息

slack-api.sh pins.remove channel=CHANNEL_ID timestamp=MESSAGE_TS

图片和文件处理

消息可能包含文件。在 token 模式下：

source ~/.agents/config/slack/tokens.env
curl -s "FILE_URL_PRIVATE" \
  -H "Authorization: Bearer ${SLACK_XOXC}" \
  -H "Cookie: d=${SLACK_XOXD}" \
  -o /tmp/slack-image-N.png

在浏览器模式下，导航到文件 URL 并截图：

node {SKILL_DIR}/scripts/playwright-bridge.js --function interact --session $SESSION_ID \
  --input '{"action": "goto", "url": "FILE_URL_PRIVATE"}'
node {SKILL_DIR}/scripts/playwright-bridge.js --function screenshot --session $SESSION_ID --input '{}'

然后使用 Read 工具查看下载的图片。

输出格式

1. 使用 python3 -c "import sys,json; ..." 解析 JSON
2. 通过 users.info 将用户 ID（U...）解析为真实姓名（缓存查询结果）
3. 展示消息，并附上时间戳和姓名
4. 将 <@U...> 提及替换为解析出的真实姓名
5. 将 Slack 标记（实体、链接语法、频道引用）转换为纯文本

速率限制

• 连续 API 调用之间添加 sleep 1
• 切勿对大型数据集进行批量分页（users.list），这会导致会话终止
• 优先使用定向查询，而不是批量获取
• 浏览器模式下每次调用的延迟更高；尽可能批量处理

令牌刷新（令牌模式，自动）

令牌刷新完全自动。API 包装器会：

1. 如果缺少 ~/.agents/config/slack/tokens.env，则自动刷新
2. 遇到 invalid_auth 错误时自动刷新并重试调用

令牌从正在运行的 Chrome 浏览器中提取：

• xoxc：通过 AppleScript 从 Slack 的 localStorage 中提取
• xoxd：通过 lsof + pycookiecheat 从 Chrome 的 Cookie 数据库中提取

设置

令牌模式（macOS）

1. 打开 Chrome，并访问 app.slack.com 上的 Slack

2. 启用 Chrome > 查看 > 开发者 > 允许来自 Apple Events 的 JavaScript

3. 安装 uv：brew install uv

4. 设置模式（可选，默认会自动检测）：

   echo 'SLACK_MODE=token' > ~/.agents/config/slack/config.env
   

浏览器模式（跨平台）

1. 从 https://nodejs.org 安装 Node.js 18+

2. 设置模式并启动会话：

   echo 'SLACK_MODE=browser' > ~/.agents/config/slack/config.env
   {SKILL_DIR}/scripts/slack-browser-session.sh login-manual
   

   首次使用时会自动安装 Playwright 和 Chromium。

自动检测（默认）

无需配置。该技能会先检查是否存在活动的浏览器会话，并通过 Playwright 调用 API。如果浏览器调用返回身份验证错误（invalid_auth、not_authed 或 no_teams_found），则会自动回退到令牌模式。当浏览器会话过期时，可借此无缝恢复。

完整 API 参考

如需了解其他方法（书签、用户组、提醒、表情符号、文件、用户资料等），请参阅 references/api-methods.md。

错误处理

• not_in_channel：用户无权访问此频道
• channel_not_found：频道 ID 无效
• invalid_auth：令牌已过期，已尝试自动刷新（令牌模式）
• ratelimited：等待后重试，并使用 sleep 5
• cant_update_message / cant_delete_message：只能修改自己的消息
• no_browser_session：没有活动的浏览器会话；运行 slack-browser-session.sh start
• node_not_found：未安装 Node.js；从 https://nodejs.org 安装
• no_teams_found：Slack 尚未在浏览器中加载工作区数据；等待后重试
• 自动回退：在自动模式下，如果浏览器调用返回 invalid_auth、not_authed 或 no_teams_found，该技能会自动通过令牌模式重试。无需手动干预。