block-kit

Block Kit

帮助开发者构建丰富的 Block Kit 布局。如果 $0 恰好是 message、modal 或 home-tab，则将其视为目标界面。否则（包括为空或为其他值时），忽略它，并在步骤 1 中确定界面。

本技能将引导你完成界面选择、布局规划、JSON 生成和验证。区块类型、元素和字段均以实时文档为准（见下方的权威来源）——请查找并阅读每个组件的架构，切勿凭记忆编写。

常见的 Block Kit 错误（及其原因）： 有些错误反复出现，值得提前指出。大多数其他错误都能在步骤 5 中通过 blocks.validate 发现，因此应依靠验证，而不是死记规则。

• "type": "text" 并不是有效类型。 文本是一个组合对象：{ "type": "plain_text", "text": "..." } 或 { "type": "mrkdwn", "text": "..." }。
• markdown 是一种_区块_类型，而不是文本类型。 markdown 区块承载标准 Markdown；其他区块中的文本对象使用 mrkdwn（见步骤 4 中的 mrkdwn 与 markdown 区块）。Slack 的 mrkdwn 使用 *粗体* / _斜体_ / ~删除线~，而不是 **粗体**。
• 消息需要顶层 text 备用文本。 blocks.validate 不会标记缺少备用文本的情况，但通知和屏幕阅读器会显示它，而不是区块内容——因此应概括布局传达的信息，而不要留空。

---

权威来源：实时文档

每种区块、元素和组合对象都记录在 docs.slack.dev 上。在任何参考 URL 后追加 .md，即可通过 WebFetch 获取 Markdown 格式的文档（无需身份验证）。

• 主索引：列出了所有区块、区块元素和组合对象，并链接到各自的页面，是权威清单：https://docs.slack.dev/reference/block-kit.md。使用 WebFetch 获取该页面，确认类型存在并找到其文档链接。
• 各组件页面包含完整的字段架构（含必填／可选标记和约束的字段表，以及 JSON 示例）：
  • 区块：https://docs.slack.dev/reference/block-kit/blocks/<slug>-block.md
  • 区块元素：https://docs.slack.dev/reference/block-kit/block-elements/<slug>-element.md
  • 组合对象：https://docs.slack.dev/reference/block-kit/composition-objects/<slug>.md
• slug 并不总是类型名称。 例如，datepicker 对应 date-picker-element.md，而所有 *_select 菜单（static_select、users_select、multi_channels_select 等）都记录在 select-menu-element.md 中。如果不确定 slug，应从主索引点击链接，而不要手动拼接 URL。
• 界面载荷结构记录在界面指南中：消息见 https://docs.slack.dev/messaging/formatting-message-text.md，模态框见 https://docs.slack.dev/surfaces/modals.md，Home 标签页见 https://docs.slack.dev/surfaces/app-home.md。

切勿使用未在实时页面中查阅过的区块类型、元素或字段。

---

快速路径（适用于清晰、具体的请求）

如果开发者的请求足够具体，能够确定目标界面和所需布局，则可将步骤 1–4 合并为一个流程：

1. 根据 $0 或上下文确定界面
2. 仅获取所提及区块和元素的文档页面
3. 直接生成 JSON
4. 进入步骤 5（验证）

适用快速路径的情况（跳过完整工作流）：

• 开发者提供了要修改的现有 JSON → 改用修改模式
• 开发者指定了具体区块类型：“添加一个包含两个按钮的 actions 区块”
• 开发者描述了常见模式：“审批消息”“反馈表单”“设置模态框”
• 开发者在一条消息中提供了完整且足够详细的描述

适用完整工作流的情况（使用步骤 1–7）：

• 请求模糊：“做点有意思的”“构建一个仪表板”
• 探索性请求：“Block Kit 能做什么？”“给我看看有哪些选项”
• 复杂布局：10 个以上区块、嵌套模态框、条件逻辑
• 开发者希望获得构建建议

修改模式

如果开发者提供了现有的 Block Kit JSON（直接粘贴、放在文件中，或通过代码引用），则进入修改模式，而不是完整创建流程：

1. 解析现有结构：

   • 按索引、类型和内容简述列出每个区块
   • 推断展示位置："type": "modal" = 模态框，"type": "home" = Home 标签页，单独的 blocks 数组 = 消息

2. 询问他们想进行哪些更改：

   • 添加区块（放在序列中的什么位置？）
   • 移除区块（移除哪些？）
   • 修改区块（修改哪个区块，如何修改？）
   • 重新排序区块

3. 应用更改，同时保留：

   • 所有现有的 block_id 值（应用交互处理程序会引用这些值）
   • 所有现有的 action_id 值（这些值会映射到事件监听器）
   • 未更改区块的现有样式、文本内容和结构

4. 验证修改后的 JSON：继续执行第 5 步（验证）

检测： 如果开发者的消息包含以 [{"type": 开头的 JSON 数组，或包含 "blocks": 的视图对象，则自动进入修改模式。如果他们提到与现有区块相关的“编辑”“更新”“修改”或“更改”，则请他们提供当前 JSON。

---

第 1 步：确定目标展示位置

如果提供了 $0，且其值为 message、modal 或 home-tab 之一，则直接使用。

否则，使用 AskUserQuestion 询问开发者：

• 消息：发布到频道或私信中的对话内容。最多 50 个区块。
• 模态框：由用户操作打开的对话框或表单。最多 100 个区块。
• Home 标签页：App Home 中面向每位用户的持久化仪表板。最多 100 个区块。

确定展示位置后，使用相应的负载结构：

• 消息：通过 chat.postMessage（及相关接口）发布的 { "text": "Fallback text", "blocks": [...] } 对象。text 字段是通知/无障碍备用文本。有关消息文本格式（mrkdwn、提及、日期），请参阅 https://docs.slack.dev/messaging/formatting-message-text.md。
• 模态框：视图对象（{ "type": "modal", "title": ..., "blocks": [...] }）。有关完整的视图对象结构、生命周期，以及视图包含任何 input 区块时必须提供 submit 的规则，请参阅 https://docs.slack.dev/surfaces/modals.md。
• Home 标签页：通过 views.publish 发布的视图对象（{ "type": "home", "blocks": [...] }）。有关结构和行为，请参阅 https://docs.slack.dev/surfaces/app-home.md。

---

第 2 步：了解要构建的内容

请开发者描述他们希望布局呈现的样子或实现的目标。

如果他们需要灵感，可以推荐一些示例——其中多个示例都能直接对应到 references/common-patterns.md 中的现成模板（括号内为模板名称），你可以在第 3 步中以此为基础开始构建：

• “包含文本输入框和类别选择器的反馈表单”（简单表单模态框）
• “包含描述和后续操作按钮的部署失败通知”（通知警报），或“包含批准/拒绝按钮的审批请求”（审批消息）
• “包含欢迎标题、关键指标字段和快捷操作按钮的仪表板 Home 标签页”（仪表板 Home 标签页）
• “包含下拉菜单、复选框和时间选择器的设置模态框”（包含多种输入类型的设置模态框）
• “包含状态和点数的冲刺任务表格”（数据表格）
• “包含粗体文本、链接和项目符号列表的部署摘要”（富文本区块）
• “用于编辑/复制/删除操作的行级‘⋯’菜单”（带溢出菜单的行操作）
• “包含图片、价格和添加到购物车按钮的商品卡片”（卡片预览）

生成任何 JSON 前，先收集足够的细节来规划布局。

---

第 3 步：规划区块布局

根据开发者的描述：

1. 仅获取所需内容，从在线文档中查阅：

   • 使用 WebFetch 获取主索引（https://docs.slack.dev/reference/block-kit.md），确认计划使用的区块和元素类型确实存在，并获取其页面链接。
   • 查阅 references/design-principles.md，判断设计是否合适：哪种区块适合内容形态（表格与堆叠分区、卡片与松散区块）、重点强调、阅读顺序和无障碍性。该文档旨在指导如何构建易读的布局，而非验证有效性。根据布局，还应查阅：
     • references/modal-design.md，了解模态框和表单：标题和提交标签、输入标签和提示、多步流程、验证错误，以及加载或成功状态。
     • references/home-tab-design.md，了解 Home 标签页：顶部内容、空状态和首次运行状态、保持视图最新、针对不同角色的不同视图，以及 Agent 的审核界面。
     • references/data-display-design.md，了解数字和记录：如何在 section 字段、table、data_table 和 data_visualization 图表之间进行选择，并清晰地呈现每种内容。
     • references/agent-progress-design.md，了解如何使用 plan 和 task_card 区块或流式任务更新来展示 Agent 的工作。
     • references/human-in-the-loop.md，了解审批关卡、在一条消息中审批多个提议的操作、澄清选项，以及发送前编辑。
   • 如果请求符合常见模式，请查看 references/common-patterns.md；从模板开始，而不是从头构建。
   • 暂缓阅读各组件页面，等到第 4 步构建每个区块的字段时再阅读。

2. 提出带编号的区块大纲。例如：

   1. header: "Weekly Report"
   2. section: Summary text with a datepicker accessory
   3. divider
   4. section: Status fields (Name, Role, Team)
   5. actions: "Approve Report" button (primary) and "Reject" button (unstyled)
   

3. 将大纲提供给开发者，并在生成 JSON 之前征求其批准或修改意见。

需要检查的界面限制：

• 区块数量上限：消息为 50 个，模态框/Home 标签页为 100 个
• 模态框专属：如果使用 input 区块，模态框载荷必须包含 submit 字段
• 表格：每条消息只能有一个 table 区块
• 图表：每条消息最多可有两个 data_visualization 区块
• 提醒：alert 区块仅可用于模态框。在消息中，应在 header 或 section 中用文字说明严重程度。
• 并非所有组件文档页面都会明确说明界面兼容性（某个区块是否适用于所选界面）和元素兼容性（某个元素是否可置于给定区块中）。请查看 references/design-principles.md 中的界面和限制表。第 5 步的 blocks.validate 不会检查这些内容——它只检查区块和元素的结构，若区块用于错误的界面或超出数量上限，仍会返回 ok: true。不要将验证通过视为符合界面或数量限制的确认。

---

第 4 步：生成 Block Kit JSON

布局获批后，根据每个区块对应的实时文档页面构建区块，并使用 WebFetch 获取每个页面的字段表（必填与可选字段、约束）和 JSON 示例。URL 格式见上文的 Source of Truth；需要记住的唯一特殊 slug 是：所有 *_select 菜单（static_select、users_select、multi_channels_select 等）都位于 select-menu-element.md 页面。按需获取页面，并复用已获取的内容——同一类型的区块不要重复获取同一个页面。然后逐个构建载荷区块，并按第 1 步中的界面结构封装。

指南：

• 使用描述性的 action_id 值（例如，"approve_report_btn"，而不是 "action_1"）——它们用于在交互处理程序中标识元素
• 在开发者需要通过交互处理来使用的地方，添加 block_id 值
• 对于模态，添加 title、submit、close 和 callback_id；对于主页标签页，添加 type: "home" 封装
• 使用 mrkdwn 文本实现丰富格式；需要使用 plain_text 的地方（标题、标签、模态标题）则使用 plain_text

mrkdwn 与 markdown 区块： section 和 context 区块使用 Slack 的 mrkdwn 格式文本（*粗体*，而不是 **粗体**）。单独的 markdown 区块（仅限消息）会渲染标准 Markdown，适用于 AI/大模型生成的内容，或已经采用标准 Markdown 格式的长篇内容。references/design-principles.md 中的 Text: rich_text, mrkdwn, and the markdown block 说明了何时使用各类格式，包括在代码中构建格式化文本时使用 rich_text。

无障碍性很容易被忽略，事后也很难补上，因此现在就应纳入设计。编写每个区块时，请应用 references/design-principles.md 中的 Accessibility and fallback：其中涵盖 text 回退内容、alt_text、颜色和表情符号、按钮标签，以及表格和图表的文本替代内容。

按照第 1 步中的界面结构，向开发者提供完整载荷。

---

第 5 步：验证

务必进行验证。 blocks.validate 是一个公开的 Web API 方法，无需身份验证令牌。

有关此方法（包括其参数、身份验证要求以及响应/错误结构）的权威参考资料是实时文档。在依赖此处的任何细节前，请先使用 WebFetch 获取该文档：https://docs.slack.dev/reference/methods/blocks.validate.md。文档说明了接受的参数（消息区块数组使用 blocks，模态/主页标签页视图使用 view，完整消息载荷使用 message；必须且只能发送其中一个）以及响应结构。

5a. 构建验证请求

如果 Slack CLI 可用，优先使用它，因为它会复用 slack-cli 技能中的 CLI 检测功能，而且无需处理令牌。如果未安装 CLI，则改用 curl。两者调用的是同一个公开方法，返回的响应也相同，因此无论采用哪种方式，都适用第 5b 步。

路径 A：Slack CLI（首选）。

使用 slack:slack-cli 技能中的 第 1 步：检测 Slack CLI，检查是否已安装公开 CLI，并确定其命令（SLACK_CMD）。

如果 CLI 可用，使用 slack:slack-cli 技能中的 第 4 步：调用 Web API 方法（slack api） 来调用它。该步骤介绍了 SLACK_CMD api <method> key=value … 语法。先运行 SLACK_CMD api --help，确认语法以及跳过身份验证的标志。blocks.validate 无需令牌，因此调用时不要进行身份验证。不要凭记忆硬编码该标志；请从帮助输出中读取，以确保即使将来标志重命名也能正确执行。将载荷作为位置参数 key=value 传入：消息使用 blocks=<JSON array>，模态和主页标签页使用 view=<JSON view object>。

路径 B：curl（回退方案，适用于未安装 CLI 的情况）。

使用 Bash 工具向端点发送 POST 请求。API 使用表单 URL 编码，因此将 JSON 直接作为参数值传入。

对于消息，将 blocks 数组作为表单编码参数发送：

curl -s -X POST 'https://slack.com/api/blocks.validate' \
  -d 'blocks=[ ... the blocks array ... ]'

对于模态和主页标签页，在 view 字段中发送完整的视图对象：

curl -s -X POST 'https://slack.com/api/blocks.validate' \
  -d 'view={ "type": "modal", "title": ..., "blocks": [...] }'

5b. 处理响应

成功：

{ "ok": true }

告知开发者，他们的区块有效。

失败：

{
  "ok": false,
  "error": "invalid_blocks",
  "errors": [
    {
      "code": "missing_field",
      "message": "missing required field: type",
      "field": "type",
      "pointer": "/0"
    }
  ]
}

验证失败时：

1. 阅读每条错误。pointer 是指向出错节点的 JSON 指针（例如，/0 = 第一个区块，/2/elements/1 = 第三个区块的第二个元素，/0/text/type = 第一个区块的文本对象中的 type 字段）。message 描述问题；如果有 constraint，则会指出未通过的规则及其预期值。
2. 修复 JSON。要了解错误代码的权威含义以及相关字段要求，请查阅实时方法文档（https://docs.slack.dev/reference/methods/blocks.validate.md）以及你在步骤 3-4 中获取的相关区块、元素或组合对象文档页面。
3. 重新验证。重复此过程，直到 "ok": true。

---

第 6 步：交付最终输出

先展示已验证的载荷，然后帮助开发者将其投入使用。

发送

构建载荷是此技能的职责；发送载荷（chat.postMessage、views.open、views.publish，以及相关的令牌和作用域处理）属于 Web API 层。要调用正确的方法——通过 Slack CLI、原始 curl 或 Bolt SDK——请使用 slack:slack-api 技能中的 第 4 步：调用方法（管理），并将此载荷作为方法的 blocks 参数（消息）或 view 参数（模态和主页标签）。该技能会将参数名称对应到 SDK 或 HTTP 调用，因此我们无需在此重复。

预览

帮助开发者使用 Block Kit Builder 查看布局。优先使用 Slack CLI（如果已安装）。CLI 会自动加载区块，开发者无需复制粘贴。如果 CLI 不可用，请提供标准 Builder 链接。

路径 A：Slack CLI（首选）。

使用 slack:slack-cli 技能中的 第 1 步：检测 Slack CLI，检查是否已安装公开 CLI 并确定其命令（SLACK_CMD）。

如果 CLI 可用，运行 SLACK_CMD blocks preview --help，查看如何传入区块并打开预览。该命令会在开发者的浏览器中将区块加载到 Block Kit Builder。

由于你以非交互方式运行 CLI，此命令还需要 --team 标志。请使用 slack:slack-cli 技能中的 第 2 步：通过帮助信息发现命令解析团队 ID。该技能中“解析 --app 和 --team 的值”的指南介绍了如何运行 SLACK_CMD auth list；如果有多个已认证的工作区，任何一个都可用于预览，请任选一个，并告知开发者你使用的是哪个工作区，而不要因选择问题而停滞。

路径 B：Block Kit Builder 链接（CLI 未安装时的备用方案）。

提供 Block Kit Builder 链接，供开发者粘贴 JSON 并进行可视化调整：https://app.slack.com/block-kit-builder。Builder 需要的是一个对象（{ "blocks": [...] } 或完整的 view 对象），而不是一个裸数组。

---

第 7 步：迭代

询问开发者是否要添加、修改、移除或重新排列区块，或者为其他界面构建布局。如果他们想更改刚才生成的布局，请重新进入 修改模式（这样可以保留其 block_id/action_id 值）；如果要创建全新布局，请返回第 3 步。

---

说明

• **范围：**此技能负责构建和验证 Block Kit 载荷，包括选择界面、根据实时文档编写 JSON，以及使用 blocks.validate 确认载荷。发送载荷属于 Web API 层（slack:slack-api）；CLI 检测和身份验证属于 slack:slack-cli。
• blocks.validate 无需身份验证——这是一个公开方法，因此无论通过 CLI 还是 curl 调用，都无需令牌即可使用。最终确定前务必验证（第 5 步）。