slack

Slack 运维

使用此技能通过 Slack Web API 读取 Slack 数据，并在获得明确确认后写入数据：频道、消息、线程、搜索、文件和 Webhook 签名验证。这是适用于 Slack 平台的工具技能。构建 Slack 应用和机器人属于应用开发；工作区管理（用户配置、组织级设置、SSO）则在 Slack 管理控制台中进行。此技能负责日常 Agent 工作流：了解说过什么、之后找到相关内容，并在人类确认后发布回复。

操作约定

1. 任何变更前先进行只读探索。 可自由列出频道、读取历史记录、查看线程、搜索和列出文件。随附的 slack-cli 脚本执行读取操作时不会写入任何内容。
2. 操作前确认目标、范围和回滚方案。 发送消息或在线程中回复会更改所有人都能看到的共享工作区状态：必须有明确的人类指令指定频道，并通过 slack-cli 使用 --dry-run 预览和 --yes 确认。团队成员已读消息后，无法撤回。
3. 遵守读取范围限制。 Slack 使用分页；切勿翻页超出任务所需范围。slack-cli --limit N 会限制每项列表操作的结果数量，响应会概述记录，而不会倾倒原始负载。
4. 验证 Webhook 后再信任其内容。 任何接收 Slack 事件的处理程序都必须使用应用签名密钥验证 X-Slack-Signature 和 X-Slack-Request-Timestamp，否则任何能访问该端点的人都可以伪造事件。slack-cli webhook verify 可执行此检查。
5. 控制证据范围。 引用简短的消息摘录和 ID；切勿在聊天中粘贴完整线程、令牌或文件内容。

slack-cli 脚本

scripts/slack-cli 是一个面向 Agent、仅使用标准库的 Slack Web API 命令行工具。它涵盖完整的问题范围：消息、频道、线程、搜索、文件和 Webhook 验证。

slack/scripts/slack-cli --help                          # no token or network needed
slack/scripts/slack-cli --json --limit 10 channels list
slack/scripts/slack-cli --json messages list --channel C12345
slack/scripts/slack-cli --json threads list --channel C12345 --ts 1712345678.000001
slack/scripts/slack-cli --json search messages --query "incident"
slack/scripts/slack-cli --json files list --limit 5
slack/scripts/slack-cli messages send --channel C12345 --text "on it" --dry-run   # preview
slack/scripts/slack-cli messages send --channel C12345 --text "on it" --yes       # confirmed
slack/scripts/slack-cli webhook verify --body-file body.json --signature "v0=..." --timestamp 1712345678

退出代码：0 表示成功，1 表示 API 错误或验证失败，2 表示用法错误。发送操作受到保护：如果没有 --dry-run 或 --yes，脚本会拒绝执行并以退出代码 1 结束，且不会调用 API。读取操作受 --limit 限制（默认值为 20，最大值为 100）。

操作流程

1. 界定工作区范围：确定相关频道、要回答的问题（说了什么、谁说的、何时说的），以及是否涉及任何变更操作。
2. 在范围内读取：使用 channels list 查找 ID，使用 messages list/threads list 查看历史记录，使用 search messages 跨频道查找内容。以上操作均为只读。
3. 整理答案：将问题对应到证据（通过线程回复了解上下文、搜索精确短语、通过文件列表查找共享内容）。
4. 确认后执行：只有在人类指示发送后，才能使用 --dry-run 预览并通过 --yes 确认。
5. 验证：确认响应中的已发布消息 ts/频道；对于 Webhook，则在信任事件之前确认签名检查结果。

消息、频道和线程

• 频道（conversations.list）：公开和私有频道、归档状态、成员数量。频道 ID（C...）是其他所有调用使用的稳定键；使用前先将名称解析为 ID。
• 消息（conversations.history）：频道中按时间从新到旧排列的历史记录，每次读取一页。消息记录包含 ts（ID）、user 和 text。使用响应元数据中的 --cursor 有序翻页。
• 线程（conversations.replies）：按父消息的 ts 获取回复；父消息是第一条结果。线程回复会将 thread_ts 设为父消息。
• 发送（chat.postMessage）：此技能范围内唯一的变更操作。始终使用 --dry-run 预览，通过 --yes 确认；要在线程中回复而不是发送新消息，请传入 --thread-ts。验证返回的 ts 和频道。

搜索和文件

• 搜索（search.messages）：使用 Slack 搜索语法（from:、in:、引号括起的短语、before:/after:）对可见历史记录进行全文搜索。结果包含匹配的频道；total 表示匹配项总数，matches 则会受 --limit 限制。
• 文件（files.list）：列出工作区中共享的文件，可按频道或用户筛选，并提供永久链接和大小。CLI 不支持下载文件内容（读取受限）；使用它查找文件，然后在有人请求文件内容时，通过经过身份验证的请求获取永久链接。

Webhook 验证

Slack 会对发往事件、命令和交互端点的每个 HTTP 请求进行签名。验证步骤如下：

1. 获取原始请求正文（与接收时完全一致，不要重新编码）。
2. 检查 X-Slack-Request-Timestamp 是否在当前时间约 5 分钟内（防止重放攻击）。
3. 计算 v0=HMAC_SHA256(signing_secret, "v0:" + timestamp + ":" + body)，并使用恒定时间比较与 X-Slack-Signature 比对。
4. 如果时间戳已过期或签名不匹配，则拒绝请求并返回 401。

slack-cli webhook verify --body-file body.json --signature "v0=..." --timestamp <unix> 会使用 SLACK_WEBHOOK_SECRET（或 --secret）执行完全相同的检查，并报告经恒定时间验证的结果。始终先验证再信任事件载荷——未经验证的 webhook 端点会接受伪造事件。

参考资料路由

何时加载	参考资料
来源、范围表、刷新流程	references/00-source-index.md
API 方法范围、分页、范围和 webhook 验证详情	references/01-web-api-operations.md

包含的产物

• scripts/slack-cli：受限、仅使用标准库的 CLI（消息、频道、线程、搜索、文件、webhook 验证；--json；--limit；发送操作受 --dry-run/--yes 控制）。
• tests/test_slack_cli.py：针对 Slack API 存根的 16 项确定性测试，包括变更操作门控和只读契约。
• references/：带日期的来源索引和 Web API 操作参考资料。
• evals/evals.json：用于评估 Agent 运行输出质量的 6 个案例。

验证边界

声明	最低证据要求
某频道存在且名称已知	slack-cli channels list --json 返回该频道及其 C... ID
某条消息已发送	slack-cli messages send --yes 返回新的 ts 和频道，且 messages list 能显示该消息
搜索找到了匹配项	slack-cli search messages --query "..." --json 返回 total_matches 和受限的匹配项
某个 webhook 是真实的	对于完全一致的正文、签名和时间戳，slack-cli webhook verify 以退出码 0 结束并返回 verified: true
某个文件存在	slack-cli files list --json 返回其 F... ID 和永久链接

严格边界

• 未经人工指示、--dry-run 预览和 --yes 确认，绝不发送消息或在线程中回复——Slack 帖子公开、持久且无法撤回。
• 未经签名和时间戳验证，绝不信任收到的 webhook。
• 绝不将读取分页到 --limit 之外；绝不将完整线程、令牌或文件内容倾倒到聊天中。
• 此技能用于操作 Slack Web API。它不用于构建 Slack 应用（应用开发）、管理用户或组织设置（管理控制台），也不涵盖其他频道平台（它们有各自的工具）。

不适用场景

• 构建 Slack 应用或机器人（Block Kit、Bolt、斜杠命令应用、OAuth 流程设计）——这属于应用开发；服务设计请参阅 backend-engineering。
• 工作区管理（用户配置、停用用户、组织级设置、SSO/SAML、组织级数据导出）——这属于 Slack 管理控制台，而非 Web API。
• 其他团队聊天平台（Discord、Mattermost、Teams）——每个平台都有自己的工具；此技能仅涵盖 Slack。
• 公司范围的消息或频道管理政策——这属于组织政策，而非 API 操作。