cyrus-setup-slack

重要：绝不要使用 Read、Edit 或 Write 工具操作 ~/.cyrus/.env 或 ~/.cyrus/ 内的任何文件。只能使用 Bash 命令（grep、printf >> 等）与环境变量文件交互——绝不能将密钥读入对话上下文。绝不要从网页抓取、提取或读取密钥值——请引导用户手动复制。

设置 Slack

根据预先构建的清单创建 Slack 应用，以便 Cyrus 能够在 Slack 频道中回复消息。

步骤 1：检查现有配置

grep -E '^SLACK_BOT_TOKEN=' ~/.cyrus/.env 2>/dev/null

如果已设置 SLACK_BOT_TOKEN，请告知用户：

Slack 已配置。跳过此步骤。 如需重新配置，请从 ~/.cyrus/.env 中移除 SLACK_BOT_TOKEN 和 SLACK_SIGNING_SECRET，然后重新运行。

跳至完成步骤。

步骤 2：读取变量

读取基础 URL（由 setup-endpoint 设置）：

grep '^CYRUS_BASE_URL=' ~/.cyrus/.env | cut -d= -f2-

还需要 AGENT_NAME 和 AGENT_DESCRIPTION——这些变量已在编排器的步骤 0 中收集，应可从对话上下文中获取。

步骤 3：构建清单 JSON

将 <AGENT_NAME>、<AGENT_DESCRIPTION> 和 <CYRUS_BASE_URL> 替换为实际值，构建清单。

重要：必须严格按照以下内容使用清单模板。 事件订阅路径必须为 /slack-webhook（不能是 /slack/events 或其他路径）。该路径与 Cyrus 代码库中 SlackEventTransport 注册的路由一致。

注意：此处的权限范围列表必须与 Slack App 配置以及 https://github.com/cyrusagents/cyrus-hosted/blob/main/apps/app/src/lib/slack/constants.ts 中定义的权限范围列表保持同步。如果在此更改权限范围，请同时提议更改对应位置，并更新依赖此清单的任何线上 Slack App 配置。

{
    "display_information": {
        "name": "<AGENT_NAME>",
        "description": "<AGENT_DESCRIPTION>",
        "background_color": "#00240e"
    },
    "features": {
        "bot_user": {
            "display_name": "<AGENT_NAME>",
            "always_online": true
        }
    },
    "oauth_config": {
        "redirect_urls": [
            "<CYRUS_BASE_URL>/slack/oauth/callback"
        ],
        "scopes": {
            "user": [
                "canvases:read",
                "canvases:write",
                "channels:history",
                "chat:write",
                "groups:history",
                "im:history",
                "mpim:history",
                "users:read",
                "users:read.email",
                "reactions:write",
                "search:read.public",
                "search:read.private",
                "search:read.mpim",
                "search:read.im",
                "search:read.files",
                "search:read.users"
            ],
            "bot": [
                "groups:read",
                "app_mentions:read",
                "assistant:write",
                "canvases:write",
                "channels:history",
                "channels:read",
                "chat:write",
                "chat:write.customize",
                "groups:history",
                "im:history",
                "im:read",
                "files:read",
                "files:write",
                "mpim:history",
                "reactions:write",
                "search:read.files",
                "search:read.public",
                "search:read.users",
                "users:read",
                "users:read.email",
                "mpim:read"
            ]
        },
        "pkce_enabled": false
    },
    "settings": {
        "event_subscriptions": {
            "request_url": "<CYRUS_BASE_URL>/slack-webhook",
            "bot_events": [
                "app_mention",
                "member_joined_channel",
                "message.channels",
                "message.groups",
                "message.mpim",
                "message.im"
            ]
        },
        "org_deploy_enabled": false,
        "socket_mode_enabled": false,
        "token_rotation_enabled": false
    }
}

步骤 4：创建 Slack App

所有路径都必须使用“From a manifest”流程。 绝不要选择“From scratch”创建应用。

根据编排器规则，确定要使用哪种浏览器自动化模式：

1. 如果有 claude-in-chrome MCP 工具 → 使用 路径 A-1（claude-in-chrome）
2. 如果已安装 agent-browser 且已连接 Chrome 调试会话 → 使用 路径 A-2（agent-browser）
3. 否则 → 使用 路径 B（手动操作）

路径 A-1：使用 claude-in-chrome 自动化

使用 mcp__claude-in-chrome__* 工具导航并操作用户现有的 Chrome 浏览器。

1. 导航至 https://api.slack.com/apps
2. 点击 Create New App
3. 在模态框中选择 From a manifest
4. 选择工作区
5. 点击 Next
6. 选择 JSON 标签页，并粘贴步骤 3 中的清单（已替换为实际值）
7. 点击 Next，检查内容，然后点击 Create

创建后，应用会进入 Basic Information 页面。不要截取凭据页面的屏幕截图。 继续执行步骤 5（收集凭据）。

路径 A-2：使用 agent-browser 自动化

如果 agent-browser 已连接到 Chrome 调试会话：

4a. 导航至 Slack 应用创建页面

agent-browser navigate "https://api.slack.com/apps"

截取屏幕截图，确认页面已加载且用户已登录。

4b. 点击“Create New App”

agent-browser click "button:text('Create New App')"

4c. 在模态框中选择“From a manifest”

agent-browser click "button:text('From a manifest')"

4d. 选择工作区

截取屏幕截图查看工作区选择器。点击相应的工作区。如果列出了多个工作区，请询问用户要选择哪一个。

agent-browser click "button:text('Next')"

4e. 选择 JSON 格式并粘贴清单

如果尚未选中，请点击 JSON 标签页：

agent-browser click "button:text('JSON')"

使用 JavaScript 粘贴清单：

agent-browser eval "var editor = document.querySelector('textarea, [role=\"textbox\"], .ace_editor textarea, .CodeMirror textarea'); if (editor) { var nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set; nativeInputValueSetter.call(editor, JSON.stringify(<MANIFEST_JSON>, null, 2)); editor.dispatchEvent(new Event('input', { bubbles: true })); 'pasted'; } else { 'editor not found'; }"

如果不起作用，请尝试：

agent-browser click "textarea"
agent-browser keyboard "Control+a"
agent-browser type '<MANIFEST_JSON_STRING>'

截取屏幕截图进行确认，然后点击 Next：

agent-browser click "button:text('Next')"

4f. 检查并创建

截取屏幕截图确认摘要，然后点击 Create：

agent-browser click "button:text('Create')"

创建后，不要截取凭据页面的屏幕截图，也不要尝试抓取密钥。 继续执行步骤 5。

路径 B：手动引导式设置

引导用户完成清单流程：

创建 Slack 应用

1. 前往 https://api.slack.com/apps
2. 点击 Create New App
3. 在弹窗中选择 From a manifest
4. 选择要关联此应用的工作区
5. 点击 Next
6. 选择 JSON 格式，并粘贴以下清单：

打印已完全替换变量的清单 JSON，供用户复制。

7. 点击 Next，查看摘要，然后点击 Create

继续执行步骤 5。

步骤 5：安装应用并收集凭据

创建应用后（无论采用哪种方式），引导用户完成安装并收集凭据。**Agent 绝不能从页面抓取、读取或提取机密信息。**用户需手动复制。

5a. 安装到工作区

告知用户：

1. 在 Slack 应用设置中，点击左侧边栏里的 Install App
2. 点击 Install to Workspace
3. 点击 Allow

如果使用浏览器自动化（A-1 或 A-2），Agent 可以前往 Install App 页面并点击按钮，但必须在安装完成后停止操作，且不得截取结果页面。

5b. 添加凭据占位符

在 env 文件中添加占位行，供用户填写：

grep -q '^SLACK_BOT_TOKEN=' ~/.cyrus/.env || echo 'SLACK_BOT_TOKEN=' >> ~/.cyrus/.env
grep -q '^SLACK_SIGNING_SECRET=' ~/.cyrus/.env || echo 'SLACK_SIGNING_SECRET=' >> ~/.cyrus/.env

5c. 打开 env 文件进行编辑

# macOS
code --new-window ~/.cyrus/.env 2>/dev/null || open -a TextEdit ~/.cyrus/.env
# Linux
code --new-window ~/.cyrus/.env 2>/dev/null || xdg-open ~/.cyrus/.env

5d. 引导用户复制凭据

告知用户：

我已打开 ~/.cyrus/.env。你需要粘贴两个值：

1. Bot User OAuth Token — 前往应用的 OAuth & Permissions 页面，复制 Bot User OAuth Token（以 xoxb- 开头），并将其粘贴到 SLACK_BOT_TOKEN= 后面

2. Signing Secret — 前往应用的 Basic Information 页面，向下滚动到 App Credentials，点击 Signing Secret 旁边的 Show，复制该值，并将其粘贴到 SLACK_SIGNING_SECRET= 后面

完成后保存并关闭文件。

5e. 等待并验证

用户确认已保存后，进行验证：

grep -c '^SLACK_BOT_TOKEN=.' ~/.cyrus/.env
grep -c '^SLACK_SIGNING_SECRET=.' ~/.cyrus/.env

两项都必须返回 1（= 后面的 . 可确保值不为空）。如果任一项返回 0，请让用户检查文件。

完成

✓ 已从清单创建并安装 Slack 应用 ✓ Bot token 和 signing secret 已保存到 ~/.cyrus/.env

**注意：**在 Cyrus 实际运行之前，事件订阅中的 request_url 将无法通过 Slack 的验证质询。Cyrus 启动后，请前往应用的 Event Subscriptions 页面并重新输入 URL，以触发验证；否则 Slack 会自动重试。