slack-docs

Slack 平台文档

帮助开发者在官方 Slack 文档网站（https://docs.slack.dev）上找到合适的页面，并以清晰的 Markdown 格式阅读，确保答案来自实时文档，而非记忆。该网站提供三个 Agent 可直接使用的机器可读界面，无需身份验证，也无需 Slack 工作区：

• 搜索 API 方法：GET https://docs.slack.dev/api/v1/search?query=<q>&category=<c> 以 JSON 格式返回按排名排序的页面结果。每次搜索都要限定 category（指南、参考资料、特定 SDK 等）；未分类的搜索结果会严重偏向 SDK 页面。
• 单页 Markdown：每个页面都可通过其 URL 加上 .md 访问（例如 /quickstart.md）。
• 索引文件：/llms.txt（精选概览）和 /llms-sitemap.md（所有 Markdown 页面的列表）。

如果提供了 $0，它可能是 docs.slack.dev URL（直接跳转到快速路径），也可能是要搜索的主题（从步骤 1 开始）。如果问题比较宽泛，例如“如何在 Slack 上构建 X？”，而不是针对某个特定页面，请先阅读 https://docs.slack.dev/llms.txt；这是一个面向 LLM 的平台精选概览，并介绍了推荐的构建路径。

关键规则：

• 文档是唯一事实来源。不要凭记忆回答有关 Slack 平台的事实性问题；先找到页面并获取内容，再根据文档作答。
• 优先使用任意页面的 .md 版本，而不是 HTML 版本。该版本更便于阅读和引用。
• 每个获取的 Markdown 页面都以 Source: <url> 行开头。保留该 URL，以便在回答中向开发者引用页面。

禁止事项：

• 不要编造文档 URL。请从搜索 API、站点地图或开发者提供的链接中获取 URL，然后通过获取内容进行验证。
• 不要转述实际未获取的页面。如果获取失败，请如实说明，不要凭记忆补充内容。
• 不要假定每个 URL 都有对应的 .md 版本。如果获取时出错，请改用搜索 API 或站点地图（步骤 1），不要猜测其他 URL。

---

快速路径（开发者已提供 URL）

如果开发者粘贴了 https://docs.slack.dev/... 链接，请跳过查找步骤，直接进入步骤 2获取并阅读页面。

---

第 1 步：发现页面（搜索）

使用文档的搜索 API查找候选页面。通过 WebFetch 请求此 URL，查询内容需进行 URL 编码，并使用 category 限定结果范围：

https://docs.slack.dev/api/v1/search?query=<url-encoded query>&category=<category>&limit=5

始终从 category 开始。 不限定类别的搜索结果会被 SDK 参考页面占据（例如，搜索 socket mode 或 oauth 时，前 10 条结果可能全是 Bolt/Node 页面），导致大多数问题真正需要的概念性内容和参考内容被埋没。根据开发者的意图选择起始类别：

• guides — 适用于“如何……”“什么是……”以及平台概念相关问题（Events API、OAuth、Socket Mode、清单、模态框、App Home）。不确定时从这里开始。
• reference — 适用于特定方法、事件、范围、对象或 Block Kit 元素，尤其是 chat.postMessage 这类确切名称。
• 工具/SDK 类别（python、javascript、java、slack_cli、slack_github_action、deno_slack_sdk）— 仅在确定开发者使用的工具后选择。请参阅第 3 步。

例如，搜索概念“socket mode” → https://docs.slack.dev/api/v1/search?query=socket%20mode&category=guides&limit=5。

响应为 JSON：

{
  "total_results": 12,
  "results": [
    { "url": "/apis/events-api/using-socket-mode", "title": "Using Socket Mode" }
  ],
  "limit": 5
}

在 results 中查找 title/url 最匹配的结果，然后在第 2 步中读取。必须提供查询内容；不带 query 调用端点会返回包含 error 字段的 400 响应。

完整类别列表：

类别	结果范围
guides	概念性指南和操作指南
reference	API 参考：方法、事件、范围、对象、Block Kit
changelog	变更日志和发行说明
python	Python 工具（Bolt for Python、Python Slack SDK）
javascript	JavaScript 工具（Bolt for JS、Node Slack SDK）
java	Java 工具（Bolt for Java、Java Slack SDK）
slack_cli	Slack CLI 文档
slack_github_action	Slack Send GitHub Action 文档
deno_slack_sdk	Deno Slack SDK 文档

如果按类别搜索没有找到合适结果，请扩大搜索范围：先尝试另一个可能的类别（guides ⇄ reference），最后再完全移除 category。无法识别的值会返回包含 error 字段的 400 响应，并列出有效类别；请使用其中一个类别或不指定类别重新搜索。

搜索未找到合适结果，或返回 500/临时错误时的备用方案（此端点受速率限制，缓存时间约为 5 分钟）：

• 使用 WebFetch 获取 https://docs.slack.dev/llms-sitemap.md。这是包含每个文档页面 .md URL 的列表，请在其中查找相关路径。
• 查询 API 参考时，使用扩展索引页面通常更快：https://docs.slack.dev/reference/methods.md、.../events.md、.../scopes.md、.../objects.md 和 .../block-kit.md 均列出了每个条目及其单行说明和 .md 链接。
• 如果开发者安装了 Slack CLI，可在终端运行 slack docs search "<query>" 进行同样的搜索（请参阅 slack:slack-cli 技能）。

---

第 2 步：读取页面（获取 Markdown）

获取页面引用（第 1 步中的 url，或开发者粘贴的链接）后，读取其 Markdown：

1. 将引用规范化为 .md URL：
   • 第 1 步中的站点相对路径（例如 /apis/events-api/using-socket-mode）：在前面加上 https://docs.slack.dev。
   • 开发者粘贴的完整 URL：先移除所有 #anchor。
   • 追加 .md，例如 …/using-socket-mode → https://docs.slack.dev/apis/events-api/using-socket-mode.md。 服务器会将 .md 请求中的路径转换为小写，因此大小写无关紧要：chat.postMessage.md 和 chat.postmessage.md 都能正确解析。
2. 使用 WebFetch 获取页面。页面开头为 Source: <original-url>；其余部分是页面正文的 Markdown。
3. 根据获取的内容回答开发者，并引用 Source URL。

如果页面较长，而开发者只询问了一个具体问题，请获取页面并仅引用相关部分，不要直接贴出整页内容。

---

第 3 步：工具和 SDK 文档

官方工具之间的实现细节差异很大，因此请先确认开发者使用的是哪款工具，然后将阅读范围限定在该工具的文档子目录中。每款工具的文档都位于 https://docs.slack.dev/tools/<name> 下，其页面均可像其他页面一样通过 .md 获取（例如 https://docs.slack.dev/tools/bolt-js/concepts.md）。如果开发者没有说明，请先询问，不要擅自假设。

工具	文档路径	搜索 category	适用场景
Slack CLI	/tools/slack-cli	slack_cli	开发者从终端搭建、运行或管理应用；提到 slack 命令或应用清单
Bolt for JavaScript	/tools/bolt-js	javascript	开发者使用 Bolt 框架通过 Node/TypeScript 构建应用
Bolt for Python	/tools/bolt-python	python	开发者使用 Bolt 框架通过 Python 构建应用
Bolt for Java	/tools/java-slack-sdk	java	开发者使用 Bolt 通过 Java 构建应用（Bolt for Java 的文档位于 Java SDK 文档中）
Node Slack SDK	/tools/node-slack-sdk	javascript	开发者需要较底层的 Node 客户端（@slack/web-api、@slack/socket-mode），而不使用完整的 Bolt 框架
Python Slack SDK	/tools/python-slack-sdk	python	开发者需要不使用 Bolt 的较底层 Python 客户端
Java Slack SDK	/tools/java-slack-sdk	java	开发者需要 Java 客户端，或正在使用 Bolt for Java
Slack Send GitHub Action	/tools/slack-github-action	slack_github_action	开发者通过 GitHub Actions 工作流向 Slack 发送数据

确认工具后，使用第 1 步中对应的 category 缩小搜索范围，例如 …?query=middleware&category=javascript。请注意语言分组：Bolt for JavaScript 和 Node Slack SDK 都归入 javascript（同理，python 和 java 各自涵盖对应的 Bolt 框架及较底层的 SDK），因此 category 限定的是整个语言系列，而不是单个子目录。

Bolt 是构建于对应语言 SDK 之上的框架。如果不确定某个主题位于哪个子目录，请改用搜索 API（第 1 步），因为它会索引所有这些文档。