用途:帮助开发者发现合适的 Slack Web API 方法、阅读其接口契约并正确调用。Slack 方法采用 family.method 点号命名(如 chat.postMessage、conversations.history),端点为 https://slack.com/api/<method>。
主要能力:
- 发现方法:抓取实时方法索引 https://docs.slack.dev/reference/methods.md,按意图映射到方法族与候选方法;也可用 Slack CLI 搜索文档。
- 读取契约:方法文档页 URL 为 https://docs.slack.dev/reference/methods/<method-lowercased>.md,包含 HTTP 方法、所需 OAuth 权限范围与令牌类型、参数、示例、错误表与限流层级。
- 认证与授权:确认令牌类型(bot xoxb- 与 user xoxp- 不可混用),admin.* 需 Enterprise Grid 组织级令牌;api.test、auth.test、blocks.validate 无需认证。
- 调用方式:可通过 Slack CLI(SLACK_CMD api <method> key=value)、curl 原始 HTTP 或 SDK 调用。
- 分页:使用不透明游标,读取 response_metadata.next_cursor,非空则带 cursor 再次调用,直至为空。
- 错误与限流:先检查顶层 ok 布尔值;ok 为 false 时读取 error 字符串。遇 HTTP 429 或 ratelimited 时按 Retry-After 头等待后重试。
使用方式:明确方法名时可直接读取契约并调用;不确定时先查索引。只读方法可直接运行,写操作(chat.postMessage/update/delete、.delete/.remove/.kick/.archive、admin.*)需先向开发者确认。
限制:不得臆造方法名或权限范围,须以实时文档为准;不要假设方法为 GET,许多是 POST;不要硬编码或明文共享令牌;不要使用已弃用方法(files.upload、dialog.open、rtm.、oauth.access、search.、stars.、reminders.)而不查替代方案;不要用页码分页。Slack Lists 方法使用 slackLists.* 前缀,不存在裸 lists.*。本技能负责方法层,CLI 认证与调用委托给 slack:slack-cli,Block Kit 载荷委托给 slack:block-kit。