当 Caffeine 应用需要向 Slack…

用户要让 Caffeine canister 应用向 Slack 频道发消息、通知频道，或按应用/指定用户身份发帖时使用。

适用场景

解决思路

1. 当用户、规格或前序任务提到 Slack、向频道发帖或通知 Slack workspace 时，加载本技能。
2. 优先使用生成的 `slack-client` 包；不要手写 `ic.http_request` 调 `https://slack.com/api/*`，否则需自己实现 bearer auth、percent-encoding 和 JSON parsing。
3. 生成代码前，向提示用户报告 token 选择（bot `xoxb-` vs user `xoxp-`）和获取位置；没有 token 无法继续，提前说明避免应用首次使用卡住。
4. 把“构建完成”定义为应用本身告诉 admin 如何获取 token 并提供粘贴位置，而不是后端编译通过。
5. 写代码前询问用户要消息以谁的身份出现并说明取舍；该选择不能在不重装的情况下替换。
6. 如果消息应显示为应用本身（帖子带 `APP` 徽章），用 `xoxb-` 且默认优先；它是一个 workspace-wide 凭证，独立于任何员工；bot 必须被邀请到每个发帖频道，否则 Slack 返回 `not_in_channel`；不能看未加入的私有频道或 DM。
7. 如果消息应显示为特定人（帖子显示该人的名字和头像），用 `xoxp-`；每个动作归属并审计为该人；可达其权限范围，无需频道邀请；该人离开 workspace 或撤销应用后失效；少数 user-only API（如 `search.messages`）必需。
8. 如果请求是「从我的应用发通知/告警」，选 `xoxb-`；只有用户明确要消息看起来来自人，或需要 user-only API 时才选 `xoxp-`；说明选择和原因。
9. 获取 bot token：打开 <https://api.slack.com/apps> → **Create New App** → *From scratch*，选择 workspace。
10. 获取 bot token：进入 **OAuth & Permissions** → *Scopes* → **Bot Token Scopes**，添加构建所需 scopes，至少 `chat:write`；一次性把列表弄对，之后添加会强制重装。
11. 获取 bot token：**Install to Workspace** → 授权 → 复制 **Bot User OAuth Token**，以 `xoxb-` 开头。
12. 获取 bot token：在 Slack 中把 app 邀请到每个目标频道：`/invite @YourApp`；跳过这是最常见的首次失败（`not_in_channel`）。
13. 根据构建实际使用的功能推导 scope 列表，并在设置 UI 只显示这些 scope；不要显示整张表。
14. Bot scope 映射：发到 bot 已加入的频道用 `chat:write`；发到任意公开频道且无需邀请用 `chat:write.public`；频道名解析为 ID、列出公开频道用 `channels:read`；列出 bot 所在的私有频道用 `groups:read`；读消息（`conversationsHistory`/`conversationsReplies`）用 `channels:history`，私有再加 `groups:history`；列出/查找用户用 `users:read`，`usersLookupByEmail` 加 `users:read.email`；DM 某人（`conversationsOpen` → `chatPostMessage`）用 `im:write`；添加 emoji reaction 用 `reactions:write`；置顶消息用 `pins:write`；上传/读文件用 `files:write`、`files:read`。
15. 注意：之后添加 scope 会使 token 失效；Slack 要求重装并发出新的 `xoxb-`；旧 token 不获得新 scope，应用会 `missing_scope` 直到 admin 粘贴新 token；设置页必须可重新粘贴，不是一次性。
16. 获取 user token：同一 app → **OAuth & Permissions** → *Scopes* → **User Token Scopes**（与 bot scopes 分开的列表），添加例如 `chat:write`、`search:read`。
17. 获取 user token：**Install to Workspace**（或已存在则 **Reinstall**）并授权；token 代表点击 Allow 的人。
18. 获取 user token：复制 **User OAuth Token**，以 `xoxp-` 开头。
19. 单个 admin 提供的 `xoxp-` 走同一 setter 和同一 `config.auth`；per-user OAuth（每个最终用户授权自己账号）超出范围，需要完整 redirect + code-exchange + refresh flow，且尚无 Slack helper，不要手写。
20. 无论 token 类型，admin 通过 **admin-gated** setter 粘贴到 canister，gate 在 `AccessControl.hasPermission(state, caller, #admin)`；token 只由 canister 持有，绝不返回前端。
21. 不要把 setter gate 在 first-caller-claims-ownership 方案上；IC 上每个未认证 caller 都是同一个 anonymous principal，匿名调用先声明所有权后，每个匿名 caller 都会通过 `caller == owner` 并可覆盖 workspace token；用 authorization 组件的 `#admin`。
22. canister 只通过 `config.auth = ?#bearer(token)` 把 token 交给 client；每个方法转成 `Authorization: Bearer …` header；没有方法接收 token 参数，也没有方法把凭证放进 URL，因此不会通过记录的 query string 泄露。
23. outcalls 默认已非复制：`defaultConfig` 带 `is_replicated = ?false`，用 record update 派生即正确；不要覆盖为 `?true` 或 `null`；复制 outcall 会从子网每个节点重复请求，Slack 消息每副本发一次（约 13 个重复），`Authorization: Bearer xoxb-…`/`xoxp-…` 离开每个节点，且因为 Slack 回复带每请求 `ts` 共识也会失败。
24. 后端添加依赖：`mops add slack-client@0.1.0`。
25. 后端添加依赖：`mops add caffeineai-authorization@1.0.1`，因为 admin gate 需要 authorization 组件。
26. 使用生成函数签名 `ChatApi.chatPostMessage(config, channel, asUser, attachments, blocks, iconEmoji, iconUrl, linkNames, mrkdwn, parse, replyBroadcast, text, threadTs, unfurlLinks, unfurlMedia, username)`；未用选项传空字符串/`false`；token 不是参数，只在 `config.auth`。
27. actor 中 include `MixinAuthorization(accessControlState, null)`、`MixinSlackConfig(accessControlState, slackConfig)`、`MixinSlackMessaging(slackConfig)`，并维护 admin 持有的 `slackConfig` token。
28. migration chain head 初始化 `accessControlState = AccessControl.initState()` 和 `slackConfig = { var token = "" }`。
29. 在 `slack-config.mo` mixin 实现 `isSlackConfigured()` query，返回 `slackConfig.token.size() > 0`。
30. 在 `slack-config.mo` mixin 实现 admin-only `setSlackToken(token : Text)`；检查 `AccessControl.hasPermission(accessControlState, caller, #admin)`，不通过则 `Runtime.trap("Unauthorized: Only admins can set the Slack token")`；接受任一 token flavor。
31. 在 `slack-messaging.mo` mixin 实现 `slackClientConfig(token)`：用 `{ defaultConfig with auth = ?#bearer(token); max_response_bytes = ?(1_000_000 : Nat64); }`。
32. 实现 `postSlackMessage(channel, text)`：若 `caller.isAnonymous()` 则 trap「Sign in to post to Slack」；若 token 为空则 trap「Slack is not configured (an admin must set the token)」；调用 `await* chatPostMessage(slackClientConfig(slackConfig.token), channel, "", "", "", "", "", false, true, "", false, text, "", false, false, "")` 并返回 `res.ts`。
33. `chatPostMessage` 第一参数是 channel ID：`C…` 表示公开或私有频道，`D…` 表示 DM，`G…` 表示 legacy group；`#general` 式名称只对公开频道仍可解析但已弃用且对私有频道无效；优先用 ID 并存储，不要硬编码名称。
34. 告诉人类哪里找 channel ID：打开频道 → 点 header 中频道名 → **About** tab → 面板底部有 ID（`C012AB3CD`）和复制按钮；或右键侧栏频道 → *Copy link* → ID 是 `…/archives/C012AB3CD` 最后一段。
35. canister 获取 channel ID：用 `ConversationsApi.conversationsList` 按 `name` 匹配（需 `channels:read`）；解析一次并缓存到 stable 变量，不要每次发帖都解析，否则 outcall 翻倍并消耗 cycles。
36. bot 必须是成员，否则 `chatPostMessage` 返回 `not_in_channel`；解决按偏好：1) admin 在目标频道运行 `/invite @YourApp`；2) 授予 `chat:write.public`，让 bot 不用邀请即可发到任意公开频道；3) 调 `conversationsJoin`（仅公开频道，需 `channels:join`）。
37. DM 某人：用 `usersLookupByEmail`（需 `users:read.email`）或 `usersList` 得到 user ID → `conversationsOpen` → 向返回的 `D…` channel 发帖；需 `im:write`。
38. API surface 是 10 个 API modules / 约 140 个操作；只有 `chatPostMessage` 经过 runtime 验证；其他从同一 spec 生成且能 typecheck，但 response decode 视为未证明。
39. 模块范围包括 `ChatApi`（`chatPostMessage`、`chatUpdate`、`chatDelete`、`chatPostEphemeral`、`chatScheduleMessage`、`chatGetPermalink`）、`ChatScheduledMessagesApi`（`chatScheduledMessagesList`）、`ConversationsApi`（`conversationsList`、`conversationsHistory`、`conversationsReplies`、`conversationsInfo`、`conversationsOpen`、`conversationsJoin`、`conversationsInvite`、`conversationsCreate`）、`UsersApi`（`usersList`、`usersInfo`、`usersLookupByEmail`、`usersConversations`、`usersGetPresence`）、`UsersProfileApi`、`ReactionsApi`、`PinsApi`、`FilesApi`、`FilesCommentsApi`、`FilesRemoteApi`。
40. 二进制上传/下载在该 client 不可用（multipart bodies 超出生成的 JSON/form surface）；需要文件可用 `filesRemoteAdd` 注册位于外部 URL 的文件。
41. Slack 不需要 OAuth callback：凭证是 admin 粘贴的长期 token，所以没有 redirect URI、没有 `/connect/slack` 路由、没有 per-user handshake；不要构建这些。
42. Slack build 必须发布让 admin 获取和输入 token 的页面，这些是验收标准不是建议；缺失则构建是 broken 而非 incomplete。
43. token 页面必须存在且可达：登录 admin 能从 nav 或未配置提示到达 `/settings/slack`；「post to Slack」功能没有 token 输入页不可用。
44. token 生成步骤必须放在 UI 中，不只放 agent 的 chat 回复；admin 数周后回来时 chat 已不存在。
45. 必须显示本 build 实际使用的精确 scope 列表；admin 无法推断需要哪些 scopes。
46. 需要登录流程：`setSlackToken` gate 在 `#admin`，所以应用需要非匿名 callers；从 `extension-authorization` 取 login、`useInternetIdentity`/`useActor` plumbing 和 admin-role gate。
47. 构建 admin settings 页 `/settings/slack`（admin-gated）；在输入框上方放「How to get your Slack bot token」面板，描述为一次性约 5 分钟设置，并包含编号步骤。
48. 该面板步骤：1) 打开 <https://api.slack.com/apps> → **Create New App** → *From scratch* → 命名并选择 workspace；2) **OAuth & Permissions** → *Scopes* → **Bot Token Scopes** → 添加本页列出的 scopes；3) **Install to Workspace** → *Allow* → 复制以 `xoxb-` 开头的 **Bot User OAuth Token**；4) 粘贴到下方并保存；5) 在 Slack 中每个应用发帖的频道运行 `/invite @YourApp`；包含打开 <https://api.slack.com/apps> 的便利链接。
49. 将 scope 列表渲染为可复制文本，恰好是本 build 使用的 scopes，不是整张表。
50. 提供一个 **password input** 绑定到 `setSlackToken(token)`；回车提交，成功后清空，并保持可重新粘贴；scope 变更会强制重装并产生新 token，所以不是一次性表单。
51. 状态由 `isSlackConfigured()`（`Bool`）驱动，显示「Configured」/「Not configured」；绝不把 token 渲染回来，即使 masked-with-suffix 也不。
52. 如果应用发到固定频道，把频道 ID 也放在该页：扩展 config mixin 到 `{ var token : Text; var channel : Text }`，加 admin-gated `setSlackChannel`，并在字段旁内联放「哪里找 channel ID」提示；不要让用户无解释地输入原始 ID。
53. 让页面可达：共享 Layout nav 在 `isCallerAdmin` 为 true 时必须链接到该页，否则隐藏；在 nav 定义处加链接，不要只放在该页内部。
54. 空状态：当 `isSlackConfigured()` 为 `false`，不要渲染死的「Send to Slack」按钮；admin 显示「Set up Slack」链接到 `/settings/slack`；非 admin 显示解释，例如「Slack 尚未设置——管理员需要在 Settings 中添加 workspace token」。
55. 翻译 Slack 错误：逻辑失败以 rejected calls 到达，message 携带 Slack 自己的 `error` 字符串；至少映射 `not_in_channel` → 「邀请应用加入频道：`/invite @YourApp`」；`invalid_auth`/`not_authed` → 「Slack token 无效——请在 Settings 粘贴新 token」（admin 给链接）；`channel_not_found` → 「检查 channel ID」（带上哪里找的提示）；`missing_scope` → 「应用需要另一个 Slack scope——添加、重装并粘贴新 token」。
56. 建议路由：`/` → 主 UI（任何已登录用户；未配置时显示空状态）；`/settings/slack` → admin token + 默认频道（仅 admin）；没有 `/connect/slack`，因为 Slack 使用粘贴的长期 token 而不是 redirect flow。
57. composer 的完成消息是交付物的一部分，不是总结；必须按顺序包含：1) 需要 token 以及谁输入——admin 在 `/settings/slack`，登录后从 nav 可达；2) 五步逐字步骤（在 <https://api.slack.com/apps> 创建 app、添加 bot scopes、Install to Workspace、复制 `xoxb-…` token、粘贴、然后在每个目标频道 `/invite @YourApp`）；3) 本 build 需要的精确 scope 列表，作为可复制文本；4) 用户需要命名频道时哪里找 channel ID；5) 失败映射每行一条：`not_in_channel` → 邀请应用；`invalid_auth` → 重新粘贴 token；`channel_not_found` → 检查 ID；`missing_scope` → 添加 scope、重装、粘贴新 token。
58. 不要把完成消息压缩成「在 Settings 中配置 Slack」，也不要只给 Slack 文档链接；用户正在 mid-build，很可能没见过 Slack app dashboard，composer 是他们看的地方；在 settings 页面板和 composer 中使用相同措辞，避免漂移。
59. 处理 `{ "ok": false }`：Slack 以 HTTP 200 返回 `{ "ok": false, "error": "…" }` 表示逻辑失败；0.1.0 客户端检测并路由到 error path，所以 reject message 命名 Slack 自己的 error 字符串，例如 `not_authed`、`invalid_auth`、`channel_not_found`；用 `try { … } catch (e) { Error.message(e) }` 处理 rejected call。
60. 不要写 `if (res.ok) …`：返回的值已经 decoded，那里 `ok` 总是 `true` 所以检查是死代码；把这些变成 `#ok`/`#err` 返回值会改变每个方法签名，需等 major。
61. IPv4 reachability 无需自建 proxy：`slack.com` 是 IPv4-only；自 **2025-08-04** IC 先尝试 direct (IPv6) 连接，失败时自动通过 IC-managed SOCKS proxy 重试，所以 IPv4-only host 可用；保持 `config.baseUrl` 为默认 `https://slack.com/api`。
62. 该代理路径 TLS 是 node 到 Slack 端到端，proxy 只看 ciphertext；fallback 路径会有额外延迟（非复制 outcall 也较慢）。
63. Auth 对每个方法都是 header-based：token 只走 `Authorization: Bearer` header，绝不放 URL，所以不会落入 logged query string，也绝不是方法参数。
64. 注意 partial runtime verification：请求 shape 已对 live Slack 验证（真实 post 会落地），成功 response decode 尚未 runtime-confirmed；`diagnostics` 开启，因此 decode failure 会暴露原始 Slack body；schema 还是从归档的约 2020 spec revision 生成。
65. 在**一次 live run 确认 decoded success reply** 之前，不要把 Slack 呈现为完全支持的平台功能；门槛是这次 live run，不是版本号。
66. 如果用户想要 per-user OAuth，不要尝试手写；需要完整 redirect + code-exchange + refresh flow，目前没有 Slack helper。
67. 如果用户需要二进制文件上传/下载，不要用该 client；改用 `filesRemoteAdd` 注册外部 URL 文件。

适用边界 · 注意事项

• 不要用于需要每个最终用户分别 OAuth 授权自己 Slack 账号的场景；当前无 Slack helper，需完整 redirect + code-exchange + refresh flow，不要手写。
• 不要用于需要二进制文件上传/下载（multipart bodies）的场景；该生成客户端不可用，只能 `filesRemoteAdd` 注册外部 URL 文件。
• 在未完成一次 live run 确认 decoded success reply 前，不要把 Slack 当作完全支持的平台功能；`slack-client@0.1.0` 实验性且成功响应解码未 runtime-confirmed。