slack-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Slack Platform Documentation

Slack平台文档

Help the developer find the right page on the official Slack documentation site (

https://docs.slack.dev

) and read it as clean markdown, so answers come from the live docs rather than memory. The site exposes three machine-readable surfaces an agent can use directly, with no authentication and no Slack workspace:

A search API method:
```
GET https://docs.slack.dev/api/v1/search?query=<q>&category=<c>
```
returns ranked page hits as JSON. Scope every search with a
```
category
```
(guides, reference, a specific SDK, etc.); an uncategorized search skews heavily toward SDK pages.
Per-page markdown: every page is available at its URL +
.md
(e.g.
```
/quickstart.md
```
).
Index files:
```
/llms.txt
```
(a curated overview) and
```
/llms-sitemap.md
```
(a list of every markdown page).

$0

is provided, it is either a

docs.slack.dev

URL (jump to the Fast Path) or a topic to search (start at Step 1). For a broad "how do I build X on Slack?" question rather than one specific page, read

https://docs.slack.dev/llms.txt

first; it is a curated, LLM-oriented overview of the platform and the recommended build path.

Critical rules:
The docs are the source of truth. Do not answer a factual question about the Slack platform from memory; discover the page, fetch it, then answer from what it says.
Prefer the .md
version of any page over the HTML version. It is cleaner for reading and quoting.
Every fetched markdown page begins with a
Source: <url>
line. Keep that URL so you can cite the page back to the developer.

DO NOT rules:
DO NOT invent documentation URLs. Get them from the search API, the sitemap, or a link the developer gave you then verify by fetching.

DO NOT paraphrase a page you have not actually fetched. If a fetch fails, say so rather than filling the gap from memory.
DO NOT assume every URL has a
.md
version. If a fetch returns an error, fall back to the search API or the sitemap (Step 1) rather than guessing another URL.

帮助开发者查找官方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。

Fast Path (the developer already has a URL)

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

If the developer pasted a

https://docs.slack.dev/...

link, skip discovery and go straight to Step 2 to fetch and read it.

若开发者粘贴了

https://docs.slack.dev/...

链接，请跳过查找步骤，直接进入步骤2获取并读取内容。

Step 1: Discover the Page (search)

步骤1：查找页面（搜索）

Use the docs search API to find candidate pages. WebFetch this URL, with the query URL-encoded and a

category

to scope the results:

text

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

Always start with a
category
. An uncategorized search is dominated by SDK reference pages (a query like

socket mode

oauth

can return a top 10 that is entirely Bolt/Node pages), which buries the conceptual and reference content most questions are actually about. Pick the starting category from the developer's intent:

guides
— the default for "how do I…", "what is…", and conceptual platform questions (Events API, OAuth, Socket Mode, manifests, modals, App Home). Start here when in doubt.
reference
— for a specific method, event, scope, object, or Block Kit element, especially an exact name like
```
chat.postMessage
```
.
A tool/SDK category (
```
python
```
,
```
javascript
```
,
```
java
```
,
```
slack_cli
```
,
```
slack_github_action
```
,
```
deno_slack_sdk
```
) — only once you know the developer's tool. See Step 3.

socket mode

as a concept →

https://docs.slack.dev/api/v1/search?query=socket%20mode&category=guides&limit=5

The response is JSON:

json

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

Scan

results

for the best

title

url

match, then read it in Step 2. A query is required; calling the endpoint with no

query

returns a

with an

error

field.

Full set of categories:

Category	Scopes results to
`guides`	Conceptual and how-to guides
`reference`	API reference: methods, events, scopes, objects, Block Kit
`changelog`	Changelog and release notes
`python`	Python tools (Bolt for Python, Python Slack SDK)
`javascript`	JavaScript tools (Bolt for JS, Node Slack SDK)
`java`	Java tools (Bolt for Java, Java Slack SDK)
`slack_cli`	Slack CLI docs
`slack_github_action`	Slack Send GitHub Action docs
`deno_slack_sdk`	Deno Slack SDK docs

If a categorized search returns no good hit, widen it: try the other likely category (

guides

⇄

reference

), then drop

category

entirely as a last resort. An unrecognized value returns a

with an

error

field listing the valid categories, so re-run with one of those or with no category.

Fallbacks when search does not surface a good hit, or returns a

/temporary error (the endpoint is rate-limited and cached ~5 minutes):

WebFetch
```
https://docs.slack.dev/llms-sitemap.md
```
, a flat list of every documentation page's
```
.md
```
URL, and scan it for the relevant path.
For API reference lookups, the enriched index pages are often faster:
```
https://docs.slack.dev/reference/methods.md
```
,
```
.../events.md
```
,
```
.../scopes.md
```
,
```
.../objects.md
```
, and
```
.../block-kit.md
```
each list every item with a one-line description and a
```
.md
```
link.
If the developer has the Slack CLI,
```
slack docs search "<query>"
```
does the same discovery from the terminal (see the
```
slack:slack-cli
```
skill).

使用文档搜索API查找候选页面。调用以下URL，需对查询内容进行URL编码，并指定

category

来限定结果范围：

text

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、清单、模态框、应用主页）的默认分类。不确定时请从这里开始。
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格式：

json

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

扫描

results

找到最匹配的

title

url

，然后进入步骤2读取内容。查询参数是必填项；调用无

query

的接口会返回

错误及包含

error

字段的响应。

完整分类列表：

分类	结果范围
`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

字段，请重新运行时使用其中一个有效分类或不指定分类。

备选方案：当搜索未找到合适结果，或返回

/临时错误（接口有速率限制，缓存时间约5分钟）时：

调用
```
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
```
技能）。

Step 2: Read the Page (fetch markdown)

步骤2：读取页面（获取markdown内容）

Given a page reference (a

url

from Step 1, or a link the developer pasted), read its markdown:

Normalize the reference to its
```
.md
```
URL:
- A site-relative path from Step 1 (e.g.
```
/apis/events-api/using-socket-mode
```
  ): prepend
```
https://docs.slack.dev
```
  .
- A full URL the developer pasted: drop any
```
#anchor
```
  first.
- Append
```
.md
```
  , e.g.
```
…/using-socket-mode
```
  →
```
https://docs.slack.dev/apis/events-api/using-socket-mode.md
```
  . The server lowercases
```
.md
```
  requests, so casing does not matter:
```
chat.postMessage.md
```
  and
```
chat.postmessage.md
```
  both resolve.
WebFetch it. The page opens with
```
Source: <original-url>
```
; the rest is the page body in markdown.
Answer the developer from the fetched content, and cite the
```
Source
```
URL.

If a page is long and the developer asked something narrow, fetch it and quote only the relevant section rather than dumping the whole page.

给定页面引用（步骤1得到的

url

，或开发者粘贴的链接），读取其markdown内容：

将引用标准化为
```
.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
```
  都可正常访问。
调用WebFetch获取内容。页面开头会显示
```
Source: <original-url>
```
；其余部分为页面主体的markdown内容。
基于获取的内容回答开发者，并引用
```
Source
```
中的URL。

若页面内容较长且开发者的问题较为具体，获取内容后仅引用相关部分，无需输出整个页面。

Step 3: Tool and SDK Documentation

步骤3：工具与SDK文档

Implementation details differ significantly between the official tools, so establish which one the developer is using first, then scope your reading to that tool's doc subtree. Each lives under

https://docs.slack.dev/tools/<name>

and its pages are fetchable as

.md

like any other (e.g.

https://docs.slack.dev/tools/bolt-js/concepts.md

). If the developer has not said, ask before assuming.

Tool	Docs path	Search `category`	Use when the developer…
Slack CLI	`/tools/slack-cli`	`slack_cli`	scaffolds, runs, or manages an app from the terminal; mentions `slack` commands or app manifests
Bolt for JavaScript	`/tools/bolt-js`	`javascript`	builds an app in Node/TypeScript with the Bolt framework
Bolt for Python	`/tools/bolt-python`	`python`	builds an app in Python with the Bolt framework
Bolt for Java	`/tools/java-slack-sdk`	`java`	builds an app in Java with Bolt (Bolt for Java lives in the Java SDK docs)
Node Slack SDK	`/tools/node-slack-sdk`	`javascript`	wants lower-level Node clients ( `@slack/web-api` , `@slack/socket-mode` ) without the full Bolt framework
Python Slack SDK	`/tools/python-slack-sdk`	`python`	wants the lower-level Python client without Bolt
Java Slack SDK	`/tools/java-slack-sdk`	`java`	wants Java clients, or is using Bolt for Java
Slack Send GitHub Action	`/tools/slack-github-action`	`slack_github_action`	sends data to Slack from a GitHub Actions workflow

Once you know the tool, narrow discovery with the matching

category

from Step 1, e.g.

…?query=middleware&category=javascript

. Note the languages group: both Bolt for JavaScript and the Node Slack SDK fall under

javascript

(likewise

python

and

java

each cover their Bolt framework plus lower-level SDK), so the category scopes to the language family, not a single subtree.

Bolt is the framework built upon the matching language SDK. When unsure which subtree a topic lives in, fall back to the search API (Step 1) as it indexes all of these.

不同官方工具的实现细节差异很大，因此请先确定开发者使用的工具，再将阅读范围限定在该工具的文档子目录下。每个工具的文档都位于

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`	需要不依赖完整Bolt框架的底层Node客户端（ `@slack/web-api` 、 `@slack/socket-mode` ）
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），因此分类是按语言族限定范围，而非单个子目录。

Bolt是基于对应语言SDK构建的框架。若不确定主题属于哪个子目录，请回到搜索API（步骤1），因为它会索引所有这些内容。