agent-slackbot

Agent SlackBot

一个 TypeScript 命令行工具，可让 AI Agent 和用户使用 Bot 令牌（xoxb-）与 Slack 工作区交互。与从桌面应用提取用户令牌的 agent-slack 不同，agent-slackbot 使用标准 Slack Bot 令牌进行服务端和 CI/CD 集成。

关键概念

在深入了解之前，先了解一些 Slack Bot 集成相关事项：

• Bot 令牌（xoxb-） — 从 Slack App 配置（api.slack.com/apps）中获取。Bot 以 Bot 用户身份操作，而非以你的身份操作。名称、权限和身份都不同。
• 工作区 + Bot 层级结构 — 每个工作区可以有多个 Bot 令牌（每个 Slack App 对应一个）。CLI 会将 Bot 存储在所属工作区下，并允许你在它们之间切换。
• 访问频道需要邀请 — 必须先使用 /invite @YourBotName 邀请 Bot 加入私密频道，它才能读取或发送消息。
• Bot 作用域按令牌固定 — 令牌的能力在创建 App 时就已确定。添加新作用域需要重新安装 App 并刷新令牌。
• 编辑/删除受 Bot 身份限制 — Bot 只能编辑或删除自己发送的消息，不能修改其他用户的消息。
• 实时事件 — 可通过 SDK 的 Socket Mode 监听器获取（需要单独的 xapp- App 级令牌），CLI 不提供此功能。

快速开始

# Set your bot token
agent-slackbot auth set xoxb-your-bot-token

# Or set with a custom bot identifier for multi-bot setups
agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"

# Verify authentication
agent-slackbot auth status

# Send a message
agent-slackbot message send C0ACZKTDDC0 "Hello from bot!"

# List channels
agent-slackbot channel list

身份验证

Bot 令牌设置

agent-slackbot 使用 Slack Bot 令牌（xoxb-），可从 Slack App 配置中获取：

# Set bot token (validates against Slack API before saving)
agent-slackbot auth set xoxb-your-bot-token

# Set with a custom bot identifier
agent-slackbot auth set xoxb-your-bot-token --bot deploy --name "Deploy Bot"

# Check auth status
agent-slackbot auth status

# Clear stored credentials
agent-slackbot auth clear

多 Bot 管理

存储多个 Bot 令牌并在它们之间切换：

# Add multiple bots
agent-slackbot auth set xoxb-deploy-token --bot deploy --name "Deploy Bot"
agent-slackbot auth set xoxb-alert-token --bot alert --name "Alert Bot"

# List all stored bots
agent-slackbot auth list

# Switch active bot
agent-slackbot auth use deploy

# Use a specific bot for one command (without switching)
agent-slackbot message send C0ACZKTDDC0 "Alert!" --bot alert

# Remove a stored bot
agent-slackbot auth remove deploy

# Disambiguate bots with same ID across workspaces
agent-slackbot auth use T123456/deploy

所有命令都支持 --bot <id> 标志，可在单次调用时覆盖当前激活的 Bot。

有关 Bot 令牌设置（Slack App 创建、所需作用域、App 清单）和 CI/CD 环境变量的信息，请参阅 references/authentication.md。

记忆

Agent 会将 ~/.config/agent-messenger/MEMORY.md 文件用作跨会话的持久记忆。此文件由 Agent 管理，CLI 不会读取或写入该文件。使用 Read 和 Write 工具管理记忆文件。

读取记忆

在每项任务开始时，使用 Read 工具读取 ~/.config/agent-messenger/MEMORY.md，加载之前发现的工作区 ID、频道 ID、用户 ID 和偏好设置。

• 如果文件尚不存在，也没关系——继续操作，不使用该文件；首次有有用信息需要保存时再创建。
• 如果无法读取文件（权限问题、目录不存在），则不使用记忆继续操作，不要报错退出。

写入记忆

发现有用信息后，使用 Write 工具更新 ~/.config/agent-messenger/MEMORY.md。以下情况应触发写入：

• 发现工作区 ID 后（通过 auth status）
• 发现有用的频道 ID 和名称后（通过 channel list 等）
• 发现用户 ID 和名称后（通过 user list 等）
• 用户提供别名或偏好后（“把这个称为 alerts bot”“我的主工作区是 X”）
• 设置好 Bot 标识符后（通过 auth list）

写入时，请包含完整文件内容——Write 工具会覆盖整个文件。

应存储的内容

• 带名称的工作区 ID
• 带名称和用途的频道 ID
• 带显示名称的用户 ID
• Bot 标识符及其用途
• 用户提供的别名（“alerts bot”“deploys channel”）
• 交互过程中表达的任何用户偏好

不应存储的内容

切勿存储 Bot 令牌、凭据或任何敏感数据。切勿存储完整消息内容（仅存储 ID 和频道上下文）。切勿存储文件上传内容。

处理过期数据

如果记忆中的 ID 返回错误（找不到频道、找不到用户），请将其从 MEMORY.md 中删除。不要盲目信任记忆中的数据——发现异常时应进行验证。优先重新列出数据，而不是使用可能已过期的记忆 ID。

格式 / 示例

# Agent Messenger Memory

## Slack Workspaces (Bot)

- `T0ABC1234` — Acme Corp

## Bots (Acme Corp)

- `deploy` — Deploy Bot (active)
- `alert` — Alert Bot

## Channels (Acme Corp)

- `C012ABC` — #general (company-wide announcements)
- `C034DEF` — #engineering (team discussion)
- `C056GHI` — #deploys (CI/CD notifications)

## Users (Acme Corp)

- `U0ABC123` — Alice (engineering lead)
- `U0DEF456` — Bob (backend)

## Aliases

- "deploys" → `C056GHI` (#deploys in Acme Corp)

## Notes

- Deploy Bot is used for CI/CD notifications
- Alert Bot is used for error monitoring

使用记忆可跳过重复调用 channel list 和 auth list。如果你已在之前的会话中获知某个 ID，可直接使用。

命令

Whoami 命令

# Show current authenticated bot
agent-slackbot whoami
agent-slackbot whoami --pretty
agent-slackbot whoami --bot <bot-id>

消息命令

# Send a message
agent-slackbot message send <channel> <text>
agent-slackbot message send C0ACZKTDDC0 "Hello world"

# Send a threaded reply
agent-slackbot message send C0ACZKTDDC0 "Reply" --thread <ts>

# List messages
agent-slackbot message list <channel>
agent-slackbot message list C0ACZKTDDC0 --limit 50

# Get a single message by timestamp
agent-slackbot message get <channel> <ts>

# Get thread replies (includes parent message)
agent-slackbot message replies <channel> <thread_ts>
agent-slackbot message replies C0ACZKTDDC0 1234567890.123456 --limit 50

# Integration posts (alerting webhooks, CI bots) often have an empty "text";
# list/get/replies then include their content in "attachments" and "blocks"

# Edit a message (bot's own messages only)
agent-slackbot message edit <channel> <ts> <new-text>

# Delete a message (bot's own messages only)
agent-slackbot message delete <channel> <ts> --force

# Show typing/status indicator in an AI Assistant thread
agent-slackbot message typing <channel> <thread_ts>
agent-slackbot message typing <channel> <thread_ts> "is analyzing..."
agent-slackbot message typing <channel> <thread_ts> ""   # clear status

输入指示器：message typing 会调用 Slack 的 assistant.threads.setStatus API。它仅适用于 AI 助手线程（不适用于常规频道/私信），并且需要 chat:write bot 权限范围。机器人发送下一条消息时，状态会自动清除；如果没有发送消息，则会在 2 分钟后自动清除。传入空字符串 "" 可手动清除状态。

频道命令

# List channels the bot can see
agent-slackbot channel list
agent-slackbot channel list --limit 50

# Get channel info
agent-slackbot channel info <channel>
agent-slackbot channel info C0ACZKTDDC0

用户命令

# List users
agent-slackbot user list
agent-slackbot user list --limit 50

# Get user info
agent-slackbot user info <user-id>

表情回应命令

# Add reaction
agent-slackbot reaction add <channel> <ts> <emoji>
agent-slackbot reaction add C0ACZKTDDC0 1234567890.123456 thumbsup

# Remove reaction
agent-slackbot reaction remove <channel> <ts> <emoji>

文件命令

# Upload a file to a channel (requires files:write scope)
agent-slackbot file upload <channel> <path>
agent-slackbot file upload C0ACZKTDDC0 ./report.pdf
agent-slackbot file upload C0ACZKTDDC0 ./log.txt --filename build-log.txt
agent-slackbot file upload C0ACZKTDDC0 ./screenshot.png --thread 1234567890.123456 --comment "FYI"

# List files visible to the bot (requires files:read scope)
agent-slackbot file list
agent-slackbot file list --channel C0ACZKTDDC0
agent-slackbot file list --user U123 --limit 50

# Show file details
agent-slackbot file info <file-id>

# Download a file by ID (saves to current dir or given path)
agent-slackbot file download <file-id>
agent-slackbot file download F0123ABC ./downloads/

# Delete a file (bot's own files only)
agent-slackbot file delete <file-id> --force

文件权限范围：file upload 需要 files:write；file list、file info 和 file download 需要 files:read。将这些权限范围添加到 Slack App 的 bot token 权限范围中，然后重新安装应用。机器人只能删除自己上传的文件。

输出格式

JSON（默认）

所有命令默认输出 JSON，供 AI 使用：

{
  "ts": "1234567890.123456",
  "channel": "C0ACZKTDDC0",
  "text": "Hello world"
}

Pretty（便于阅读）

使用 --pretty 标志输出格式化内容：

agent-slackbot channel list --pretty

全局选项

选项	描述
--pretty	输出便于阅读的内容，而非紧凑的 JSON
--bot <id>	为此命令指定一个 bot（工作区/bot）

常见模式

有关典型的 AI Agent 工作流，请参阅 references/common-patterns.md。

模板

可运行示例请参阅 templates/ 目录：

• post-message.sh - 发送消息并处理错误
• monitor-channel.sh - 监控频道中的新消息
• workspace-summary.sh - 生成工作区摘要

错误处理

所有命令均返回统一的错误格式：

{
  "error": "No credentials. Run \"auth set\" first."
}

常见错误：

• missing_token：未配置凭据
• invalid_token_type：令牌不是 bot token（必须以 xoxb- 开头）
• not_in_channel：机器人需要先加入频道
• slack_webapi_rate_limited_error：触发速率限制（会自动进行退避重试）

配置

凭据存储在 ~/.config/agent-messenger/slackbot-credentials.json（权限为 0600）。有关格式和安全详情，请参阅 references/authentication.md。

与 agent-slack 的主要区别

功能	agent-slack	agent-slackbot
令牌类型	用户令牌（xoxc-）	Bot 令牌（xoxb-）
令牌来源	从桌面应用自动提取	从 Slack App 配置手动获取
消息搜索	是	否（需要用户令牌）
文件操作	是	上传/列出/查看信息/下载/删除（需要权限范围）
快照	是	否
编辑/删除消息	任意消息	仅限机器人自己的消息
工作区管理	多工作区	多 bot、多工作区
适用于 CI/CD	需要桌面应用	是（只需设置令牌）

限制

• CLI 中没有实时事件（可通过 SDK 使用实时 Socket Mode 事件——请参阅 README 中的“实时事件（Slack Bot）”部分）
• 不支持消息搜索（需要用户令牌权限范围）
• 文件操作需要 files:read / files:write 权限范围；机器人只能删除自己上传的文件
• 不支持工作区快照
• 机器人只能编辑/删除自己的消息
• 必须邀请机器人加入私密频道
• 不支持定时消息

故障排除

agent-slackbot: command not found

agent-slackbot 不是 npm 包名。 npm 包名是 agent-messenger。

如果已全局安装该包，请直接使用 agent-slackbot：

agent-slackbot message send general "Hello"

如果未安装该包，默认使用 npx -y。不要询问用户要使用哪个包运行器——直接运行：

npx -y agent-messenger slackbot message send general "Hello"
bunx agent-messenger slackbot message send general "Hello"
pnpm dlx agent-messenger slackbot message send general "Hello"

如果你已知用户偏好的包运行器（例如 bunx、pnpm dlx），则改用该运行器。

绝不要运行 npx agent-slackbot、bunx agent-slackbot 或 pnpm dlx agent-slackbot——由于 agent-slackbot 不是 npm 包名，这些命令会失败或安装错误的包。

如需排查其他问题（令牌问题、作用域、权限），请参阅 references/authentication.md。

参考资料

• 身份验证指南
• 常见模式