@capybara-hq/plugin-slack 0.1.0-rc.1 → 0.1.0-rc.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.capybara-plugin/plugin.json +41 -6
- package/README.md +174 -33
- package/THIRD-PARTY-NOTICES.txt +2 -2
- package/connectors/slack.json +85 -0
- package/dist/index.mjs +1736 -620
- package/guides/slack-app.md +243 -0
- package/guides/slack-app.zh.md +237 -0
- package/guides/slack-connector.md +113 -0
- package/guides/slack-connector.zh.md +107 -0
- package/icon.svg +1 -0
- package/package.json +1 -1
- package/app-manifest.yaml +0 -46
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
# Create the Slack app
|
|
2
|
+
|
|
3
|
+
This connects one Slack workspace to Capybara as a bot. People message the bot directly, mention
|
|
4
|
+
it in channels and use the slash commands `/new`, `/env` and `/capybara`. You need permission to
|
|
5
|
+
create apps in the workspace (with "Only allow pre-approved apps", a workspace admin approves the
|
|
6
|
+
app after step 2).
|
|
7
|
+
|
|
8
|
+
## 1. Create the app from the manifest
|
|
9
|
+
|
|
10
|
+
Open <https://api.slack.com/apps>, choose **Create New App → From a manifest**, pick your
|
|
11
|
+
workspace and paste the manifest below.
|
|
12
|
+
|
|
13
|
+
::: mode long_connection
|
|
14
|
+
Socket Mode needs no public address: Slack keeps a connection open to Capybara. The manifest
|
|
15
|
+
registers the bot scopes, the events and the slash commands the plugin needs.
|
|
16
|
+
|
|
17
|
+
```yaml title="App manifest (Socket Mode)"
|
|
18
|
+
# Slack app manifest for the Capybara Slack plugin, Socket Mode (long connection).
|
|
19
|
+
# Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
|
|
20
|
+
display_information:
|
|
21
|
+
# Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
|
|
22
|
+
name: "{{connectionName}}"
|
|
23
|
+
description: Chat with your organization's Capybara agents.
|
|
24
|
+
background_color: "#3d2f24"
|
|
25
|
+
features:
|
|
26
|
+
app_home:
|
|
27
|
+
home_tab_enabled: false
|
|
28
|
+
messages_tab_enabled: true
|
|
29
|
+
messages_tab_read_only_enabled: false
|
|
30
|
+
bot_user:
|
|
31
|
+
display_name: Capybara
|
|
32
|
+
always_online: true
|
|
33
|
+
slash_commands:
|
|
34
|
+
- command: /new
|
|
35
|
+
description: Start a new conversation (direct message)
|
|
36
|
+
should_escape: false
|
|
37
|
+
- command: /env
|
|
38
|
+
description: List or set your default environment (direct message)
|
|
39
|
+
usage_hint: "[name]"
|
|
40
|
+
should_escape: false
|
|
41
|
+
- command: /capybara
|
|
42
|
+
description: Run a skill
|
|
43
|
+
usage_hint: "<skill> [args]"
|
|
44
|
+
should_escape: false
|
|
45
|
+
oauth_config:
|
|
46
|
+
# Sign in with Slack (identity-source@1).
|
|
47
|
+
redirect_urls:
|
|
48
|
+
- "{{signInCallbackUrl}}"
|
|
49
|
+
scopes:
|
|
50
|
+
bot:
|
|
51
|
+
- chat:write # post and update replies and cards
|
|
52
|
+
- commands # slash commands /new, /env, /capybara
|
|
53
|
+
- im:write # conversations.open: tell the bot's own DM from other DMs
|
|
54
|
+
- im:history # message.im: direct messages to the bot
|
|
55
|
+
- app_mentions:read # app_mention: @capybara in channels
|
|
56
|
+
- channels:history # message.channels: thread replies in public channels
|
|
57
|
+
- groups:history # message.groups: thread replies in private channels
|
|
58
|
+
- users:read # users.info; team_join / user_change; users.list
|
|
59
|
+
- users:read.email # directory@1: email addresses in users.list
|
|
60
|
+
settings:
|
|
61
|
+
event_subscriptions:
|
|
62
|
+
bot_events:
|
|
63
|
+
- message.im
|
|
64
|
+
- app_mention
|
|
65
|
+
- message.channels
|
|
66
|
+
- message.groups
|
|
67
|
+
- team_join
|
|
68
|
+
- user_change
|
|
69
|
+
interactivity:
|
|
70
|
+
is_enabled: true
|
|
71
|
+
socket_mode_enabled: true
|
|
72
|
+
org_deploy_enabled: false
|
|
73
|
+
token_rotation_enabled: false
|
|
74
|
+
```
|
|
75
|
+
:::
|
|
76
|
+
|
|
77
|
+
::: mode webhook
|
|
78
|
+
In webhook mode Slack posts events, card clicks and slash commands to this connection's address,
|
|
79
|
+
which exists only once the connection is saved. Start with this basic manifest: it registers the
|
|
80
|
+
bot and its scopes, without any address. Step 5 adds the addresses after saving.
|
|
81
|
+
|
|
82
|
+
```yaml title="Basic app manifest (webhook)"
|
|
83
|
+
# Slack app manifest for the Capybara Slack plugin, webhook inbound mode, first step: no
|
|
84
|
+
# addresses yet. Step 5 replaces it with the full manifest once the connection is saved.
|
|
85
|
+
# Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
|
|
86
|
+
display_information:
|
|
87
|
+
# Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
|
|
88
|
+
name: "{{connectionName}}"
|
|
89
|
+
description: Chat with your organization's Capybara agents.
|
|
90
|
+
background_color: "#3d2f24"
|
|
91
|
+
features:
|
|
92
|
+
app_home:
|
|
93
|
+
home_tab_enabled: false
|
|
94
|
+
messages_tab_enabled: true
|
|
95
|
+
messages_tab_read_only_enabled: false
|
|
96
|
+
bot_user:
|
|
97
|
+
display_name: Capybara
|
|
98
|
+
always_online: true
|
|
99
|
+
oauth_config:
|
|
100
|
+
# Sign in with Slack (identity-source@1).
|
|
101
|
+
redirect_urls:
|
|
102
|
+
- "{{signInCallbackUrl}}"
|
|
103
|
+
scopes:
|
|
104
|
+
bot:
|
|
105
|
+
- chat:write # post and update replies and cards
|
|
106
|
+
- commands # slash commands /new, /env, /capybara
|
|
107
|
+
- im:write # conversations.open: tell the bot's own DM from other DMs
|
|
108
|
+
- im:history # message.im: direct messages to the bot
|
|
109
|
+
- app_mentions:read # app_mention: @capybara in channels
|
|
110
|
+
- channels:history # message.channels: thread replies in public channels
|
|
111
|
+
- groups:history # message.groups: thread replies in private channels
|
|
112
|
+
- users:read # users.info; team_join / user_change; users.list
|
|
113
|
+
- users:read.email # directory@1: email addresses in users.list
|
|
114
|
+
settings:
|
|
115
|
+
socket_mode_enabled: false
|
|
116
|
+
org_deploy_enabled: false
|
|
117
|
+
token_rotation_enabled: false
|
|
118
|
+
```
|
|
119
|
+
:::
|
|
120
|
+
|
|
121
|
+
::: mode long_connection
|
|
122
|
+
## 2. Create the app-level token
|
|
123
|
+
|
|
124
|
+
Under **Basic Information → App-Level Tokens** choose **Generate Token and Scopes**, add the scope
|
|
125
|
+
`connections:write` and copy the `xapp-…` token into the **App-level token** field below.
|
|
126
|
+
|
|
127
|
+
::check app-token App-level token opens a Socket Mode connection
|
|
128
|
+
:::
|
|
129
|
+
|
|
130
|
+
::: mode webhook
|
|
131
|
+
## 2. Copy the signing secret
|
|
132
|
+
|
|
133
|
+
Copy **Basic Information → App Credentials → Signing Secret** into the **Signing secret** field
|
|
134
|
+
below. Every webhook request is verified with it; without it every request is refused.
|
|
135
|
+
:::
|
|
136
|
+
|
|
137
|
+
## 3. Install the app and copy the bot token
|
|
138
|
+
|
|
139
|
+
Choose **Install App → Install to Workspace** and copy the **Bot User OAuth Token** (`xoxb-…`)
|
|
140
|
+
into the **Bot token** field below.
|
|
141
|
+
|
|
142
|
+
::check bot-token Bot token works
|
|
143
|
+
::check bot-scopes The app has every scope in the manifest
|
|
144
|
+
|
|
145
|
+
## 4. Save the channel
|
|
146
|
+
|
|
147
|
+
Fill in the remaining fields on this page and save. Capybara verifies the bot token when you save.
|
|
148
|
+
With Socket Mode that is all: the bot connects and is ready for messages.
|
|
149
|
+
|
|
150
|
+
::: mode webhook
|
|
151
|
+
## 5. Point Slack at this connection
|
|
152
|
+
|
|
153
|
+
After saving, the manifest below carries this connection's address `{{webhookUrl}}` (before saving
|
|
154
|
+
it is shown as written). In the app open **App Manifest**, replace the manifest with this one and
|
|
155
|
+
save. It adds the slash commands, the event subscriptions and interactivity, all sent to this
|
|
156
|
+
address.
|
|
157
|
+
|
|
158
|
+
```yaml title="App manifest (webhook)"
|
|
159
|
+
# Slack app manifest for the Capybara Slack plugin, webhook inbound mode.
|
|
160
|
+
# Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
|
|
161
|
+
display_information:
|
|
162
|
+
# Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
|
|
163
|
+
name: "{{connectionName}}"
|
|
164
|
+
description: Chat with your organization's Capybara agents.
|
|
165
|
+
background_color: "#3d2f24"
|
|
166
|
+
features:
|
|
167
|
+
app_home:
|
|
168
|
+
home_tab_enabled: false
|
|
169
|
+
messages_tab_enabled: true
|
|
170
|
+
messages_tab_read_only_enabled: false
|
|
171
|
+
bot_user:
|
|
172
|
+
display_name: Capybara
|
|
173
|
+
always_online: true
|
|
174
|
+
slash_commands:
|
|
175
|
+
- command: /new
|
|
176
|
+
url: "{{webhookUrl}}"
|
|
177
|
+
description: Start a new conversation (direct message)
|
|
178
|
+
should_escape: false
|
|
179
|
+
- command: /env
|
|
180
|
+
url: "{{webhookUrl}}"
|
|
181
|
+
description: List or set your default environment (direct message)
|
|
182
|
+
usage_hint: "[name]"
|
|
183
|
+
should_escape: false
|
|
184
|
+
- command: /capybara
|
|
185
|
+
url: "{{webhookUrl}}"
|
|
186
|
+
description: Run a skill
|
|
187
|
+
usage_hint: "<skill> [args]"
|
|
188
|
+
should_escape: false
|
|
189
|
+
oauth_config:
|
|
190
|
+
# Sign in with Slack (identity-source@1).
|
|
191
|
+
redirect_urls:
|
|
192
|
+
- "{{signInCallbackUrl}}"
|
|
193
|
+
scopes:
|
|
194
|
+
bot:
|
|
195
|
+
- chat:write # post and update replies and cards
|
|
196
|
+
- commands # slash commands /new, /env, /capybara
|
|
197
|
+
- im:write # conversations.open: tell the bot's own DM from other DMs
|
|
198
|
+
- im:history # message.im: direct messages to the bot
|
|
199
|
+
- app_mentions:read # app_mention: @capybara in channels
|
|
200
|
+
- channels:history # message.channels: thread replies in public channels
|
|
201
|
+
- groups:history # message.groups: thread replies in private channels
|
|
202
|
+
- users:read # users.info; team_join / user_change; users.list
|
|
203
|
+
- users:read.email # directory@1: email addresses in users.list
|
|
204
|
+
settings:
|
|
205
|
+
event_subscriptions:
|
|
206
|
+
request_url: "{{webhookUrl}}"
|
|
207
|
+
bot_events:
|
|
208
|
+
- message.im
|
|
209
|
+
- app_mention
|
|
210
|
+
- message.channels
|
|
211
|
+
- message.groups
|
|
212
|
+
- team_join
|
|
213
|
+
- user_change
|
|
214
|
+
interactivity:
|
|
215
|
+
is_enabled: true
|
|
216
|
+
request_url: "{{webhookUrl}}"
|
|
217
|
+
socket_mode_enabled: false
|
|
218
|
+
org_deploy_enabled: false
|
|
219
|
+
token_rotation_enabled: false
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Slack verifies the Request URL when you save, and Capybara answers because the connection now
|
|
223
|
+
exists. Reinstall the app if Slack asks.
|
|
224
|
+
|
|
225
|
+
::check capybara:webhook-public Webhook address is reachable from the internet
|
|
226
|
+
::check capybara:webhook-received Slack has delivered a signed request
|
|
227
|
+
:::
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Sign in with Slack
|
|
232
|
+
|
|
233
|
+
The manifest's redirect URL `{{signInCallbackUrl}}` is for **Sign in with Slack**. It needs the
|
|
234
|
+
deployment's public URL; without it, delete the redirect URL from the manifest or ask your super
|
|
235
|
+
admin to set `http.publicUrl`.
|
|
236
|
+
|
|
237
|
+
::check capybara:public-url The platform has a public URL
|
|
238
|
+
|
|
239
|
+
## When the plugin changes this manifest
|
|
240
|
+
|
|
241
|
+
After a Slack plugin update that changes the manifest, Capybara shows a notice on this connection.
|
|
242
|
+
Open the app at <https://api.slack.com/apps>, go to **App Manifest**, paste the new manifest,
|
|
243
|
+
save, reinstall the app if Slack asks, then confirm here with **I have updated the Slack app**.
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
# 创建 Slack 应用
|
|
2
|
+
|
|
3
|
+
这会把一个 Slack 工作区以机器人的形式接入 Capybara。成员可以直接私信机器人、在频道里 @ 它,
|
|
4
|
+
并使用斜杠命令 `/new`、`/env` 和 `/capybara`。你需要有在该工作区创建应用的权限(工作区开启了
|
|
5
|
+
「Only allow pre-approved apps」时,第 2 步之后需要工作区管理员批准该应用)。
|
|
6
|
+
|
|
7
|
+
## 1. 用 manifest 创建应用
|
|
8
|
+
|
|
9
|
+
打开 <https://api.slack.com/apps>,选择 **Create New App → From a manifest**,选中你的工作区,
|
|
10
|
+
粘贴下面的 manifest。
|
|
11
|
+
|
|
12
|
+
::: mode long_connection
|
|
13
|
+
Socket Mode 不需要公网地址:由 Slack 与 Capybara 之间保持一条长连接。这份 manifest 会登记插件需要的
|
|
14
|
+
机器人权限、事件和斜杠命令。
|
|
15
|
+
|
|
16
|
+
```yaml title="应用 manifest(Socket Mode)"
|
|
17
|
+
# Slack app manifest for the Capybara Slack plugin, Socket Mode (long connection).
|
|
18
|
+
# Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
|
|
19
|
+
display_information:
|
|
20
|
+
# Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
|
|
21
|
+
name: "{{connectionName}}"
|
|
22
|
+
description: Chat with your organization's Capybara agents.
|
|
23
|
+
background_color: "#3d2f24"
|
|
24
|
+
features:
|
|
25
|
+
app_home:
|
|
26
|
+
home_tab_enabled: false
|
|
27
|
+
messages_tab_enabled: true
|
|
28
|
+
messages_tab_read_only_enabled: false
|
|
29
|
+
bot_user:
|
|
30
|
+
display_name: Capybara
|
|
31
|
+
always_online: true
|
|
32
|
+
slash_commands:
|
|
33
|
+
- command: /new
|
|
34
|
+
description: Start a new conversation (direct message)
|
|
35
|
+
should_escape: false
|
|
36
|
+
- command: /env
|
|
37
|
+
description: List or set your default environment (direct message)
|
|
38
|
+
usage_hint: "[name]"
|
|
39
|
+
should_escape: false
|
|
40
|
+
- command: /capybara
|
|
41
|
+
description: Run a skill
|
|
42
|
+
usage_hint: "<skill> [args]"
|
|
43
|
+
should_escape: false
|
|
44
|
+
oauth_config:
|
|
45
|
+
# Sign in with Slack (identity-source@1).
|
|
46
|
+
redirect_urls:
|
|
47
|
+
- "{{signInCallbackUrl}}"
|
|
48
|
+
scopes:
|
|
49
|
+
bot:
|
|
50
|
+
- chat:write # post and update replies and cards
|
|
51
|
+
- commands # slash commands /new, /env, /capybara
|
|
52
|
+
- im:write # conversations.open: tell the bot's own DM from other DMs
|
|
53
|
+
- im:history # message.im: direct messages to the bot
|
|
54
|
+
- app_mentions:read # app_mention: @capybara in channels
|
|
55
|
+
- channels:history # message.channels: thread replies in public channels
|
|
56
|
+
- groups:history # message.groups: thread replies in private channels
|
|
57
|
+
- users:read # users.info; team_join / user_change; users.list
|
|
58
|
+
- users:read.email # directory@1: email addresses in users.list
|
|
59
|
+
settings:
|
|
60
|
+
event_subscriptions:
|
|
61
|
+
bot_events:
|
|
62
|
+
- message.im
|
|
63
|
+
- app_mention
|
|
64
|
+
- message.channels
|
|
65
|
+
- message.groups
|
|
66
|
+
- team_join
|
|
67
|
+
- user_change
|
|
68
|
+
interactivity:
|
|
69
|
+
is_enabled: true
|
|
70
|
+
socket_mode_enabled: true
|
|
71
|
+
org_deploy_enabled: false
|
|
72
|
+
token_rotation_enabled: false
|
|
73
|
+
```
|
|
74
|
+
:::
|
|
75
|
+
|
|
76
|
+
::: mode webhook
|
|
77
|
+
Webhook 模式下,Slack 把事件、卡片点击和斜杠命令发到这个渠道连接的地址,而这个地址要等连接保存后
|
|
78
|
+
才存在。先用这份基础 manifest:它只登记机器人和权限,不含任何地址。保存之后,第 5 步再补上地址。
|
|
79
|
+
|
|
80
|
+
```yaml title="基础应用 manifest(Webhook)"
|
|
81
|
+
# Slack app manifest for the Capybara Slack plugin, webhook inbound mode, first step: no
|
|
82
|
+
# addresses yet. Step 5 replaces it with the full manifest once the connection is saved.
|
|
83
|
+
# Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
|
|
84
|
+
display_information:
|
|
85
|
+
# Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
|
|
86
|
+
name: "{{connectionName}}"
|
|
87
|
+
description: Chat with your organization's Capybara agents.
|
|
88
|
+
background_color: "#3d2f24"
|
|
89
|
+
features:
|
|
90
|
+
app_home:
|
|
91
|
+
home_tab_enabled: false
|
|
92
|
+
messages_tab_enabled: true
|
|
93
|
+
messages_tab_read_only_enabled: false
|
|
94
|
+
bot_user:
|
|
95
|
+
display_name: Capybara
|
|
96
|
+
always_online: true
|
|
97
|
+
oauth_config:
|
|
98
|
+
# Sign in with Slack (identity-source@1).
|
|
99
|
+
redirect_urls:
|
|
100
|
+
- "{{signInCallbackUrl}}"
|
|
101
|
+
scopes:
|
|
102
|
+
bot:
|
|
103
|
+
- chat:write # post and update replies and cards
|
|
104
|
+
- commands # slash commands /new, /env, /capybara
|
|
105
|
+
- im:write # conversations.open: tell the bot's own DM from other DMs
|
|
106
|
+
- im:history # message.im: direct messages to the bot
|
|
107
|
+
- app_mentions:read # app_mention: @capybara in channels
|
|
108
|
+
- channels:history # message.channels: thread replies in public channels
|
|
109
|
+
- groups:history # message.groups: thread replies in private channels
|
|
110
|
+
- users:read # users.info; team_join / user_change; users.list
|
|
111
|
+
- users:read.email # directory@1: email addresses in users.list
|
|
112
|
+
settings:
|
|
113
|
+
socket_mode_enabled: false
|
|
114
|
+
org_deploy_enabled: false
|
|
115
|
+
token_rotation_enabled: false
|
|
116
|
+
```
|
|
117
|
+
:::
|
|
118
|
+
|
|
119
|
+
::: mode long_connection
|
|
120
|
+
## 2. 创建应用级令牌
|
|
121
|
+
|
|
122
|
+
在 **Basic Information → App-Level Tokens** 选择 **Generate Token and Scopes**,添加权限
|
|
123
|
+
`connections:write`,把 `xapp-…` 令牌填进下方的 **应用令牌**。
|
|
124
|
+
|
|
125
|
+
::check app-token 应用令牌能建立 Socket Mode 连接
|
|
126
|
+
:::
|
|
127
|
+
|
|
128
|
+
::: mode webhook
|
|
129
|
+
## 2. 复制签名密钥
|
|
130
|
+
|
|
131
|
+
把 **Basic Information → App Credentials → Signing Secret** 填进下方的 **签名密钥**。每个 webhook
|
|
132
|
+
请求都用它校验;不填则所有请求都会被拒绝。
|
|
133
|
+
:::
|
|
134
|
+
|
|
135
|
+
## 3. 安装应用并复制机器人令牌
|
|
136
|
+
|
|
137
|
+
选择 **Install App → Install to Workspace**,把 **Bot User OAuth Token**(`xoxb-…`)填进下方的
|
|
138
|
+
**机器人令牌**。
|
|
139
|
+
|
|
140
|
+
::check bot-token 机器人令牌可用
|
|
141
|
+
::check bot-scopes 应用具备 manifest 中的全部权限
|
|
142
|
+
|
|
143
|
+
## 4. 保存渠道
|
|
144
|
+
|
|
145
|
+
填好本页其余字段并保存,保存时 Capybara 会校验机器人令牌。使用 Socket Mode 时到这里就完成了:机器人
|
|
146
|
+
会自动连上,可以开始收消息。
|
|
147
|
+
|
|
148
|
+
::: mode webhook
|
|
149
|
+
## 5. 让 Slack 指向这个连接
|
|
150
|
+
|
|
151
|
+
保存之后,下面的 manifest 会带上这个连接的地址 `{{webhookUrl}}`(保存前按原样显示)。在应用里打开
|
|
152
|
+
**App Manifest**,用这份 manifest 整体替换并保存。它会加上斜杠命令、事件订阅和交互,全部发往这个地址。
|
|
153
|
+
|
|
154
|
+
```yaml title="应用 manifest(Webhook)"
|
|
155
|
+
# Slack app manifest for the Capybara Slack plugin, webhook inbound mode.
|
|
156
|
+
# Reference: https://docs.slack.dev/reference/app-manifest (checked 2026-11-09).
|
|
157
|
+
display_information:
|
|
158
|
+
# Slack caps app names at 35 characters; shorten it in the app settings if it is longer.
|
|
159
|
+
name: "{{connectionName}}"
|
|
160
|
+
description: Chat with your organization's Capybara agents.
|
|
161
|
+
background_color: "#3d2f24"
|
|
162
|
+
features:
|
|
163
|
+
app_home:
|
|
164
|
+
home_tab_enabled: false
|
|
165
|
+
messages_tab_enabled: true
|
|
166
|
+
messages_tab_read_only_enabled: false
|
|
167
|
+
bot_user:
|
|
168
|
+
display_name: Capybara
|
|
169
|
+
always_online: true
|
|
170
|
+
slash_commands:
|
|
171
|
+
- command: /new
|
|
172
|
+
url: "{{webhookUrl}}"
|
|
173
|
+
description: Start a new conversation (direct message)
|
|
174
|
+
should_escape: false
|
|
175
|
+
- command: /env
|
|
176
|
+
url: "{{webhookUrl}}"
|
|
177
|
+
description: List or set your default environment (direct message)
|
|
178
|
+
usage_hint: "[name]"
|
|
179
|
+
should_escape: false
|
|
180
|
+
- command: /capybara
|
|
181
|
+
url: "{{webhookUrl}}"
|
|
182
|
+
description: Run a skill
|
|
183
|
+
usage_hint: "<skill> [args]"
|
|
184
|
+
should_escape: false
|
|
185
|
+
oauth_config:
|
|
186
|
+
# Sign in with Slack (identity-source@1).
|
|
187
|
+
redirect_urls:
|
|
188
|
+
- "{{signInCallbackUrl}}"
|
|
189
|
+
scopes:
|
|
190
|
+
bot:
|
|
191
|
+
- chat:write # post and update replies and cards
|
|
192
|
+
- commands # slash commands /new, /env, /capybara
|
|
193
|
+
- im:write # conversations.open: tell the bot's own DM from other DMs
|
|
194
|
+
- im:history # message.im: direct messages to the bot
|
|
195
|
+
- app_mentions:read # app_mention: @capybara in channels
|
|
196
|
+
- channels:history # message.channels: thread replies in public channels
|
|
197
|
+
- groups:history # message.groups: thread replies in private channels
|
|
198
|
+
- users:read # users.info; team_join / user_change; users.list
|
|
199
|
+
- users:read.email # directory@1: email addresses in users.list
|
|
200
|
+
settings:
|
|
201
|
+
event_subscriptions:
|
|
202
|
+
request_url: "{{webhookUrl}}"
|
|
203
|
+
bot_events:
|
|
204
|
+
- message.im
|
|
205
|
+
- app_mention
|
|
206
|
+
- message.channels
|
|
207
|
+
- message.groups
|
|
208
|
+
- team_join
|
|
209
|
+
- user_change
|
|
210
|
+
interactivity:
|
|
211
|
+
is_enabled: true
|
|
212
|
+
request_url: "{{webhookUrl}}"
|
|
213
|
+
socket_mode_enabled: false
|
|
214
|
+
org_deploy_enabled: false
|
|
215
|
+
token_rotation_enabled: false
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
保存时 Slack 会校验 Request URL;连接已经存在,Capybara 会应答校验。Slack 要求时重新安装应用。
|
|
219
|
+
|
|
220
|
+
::check capybara:webhook-public Webhook 地址可从公网访问
|
|
221
|
+
::check capybara:webhook-received Slack 已送达一个签名有效的请求
|
|
222
|
+
:::
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## Slack 登录
|
|
227
|
+
|
|
228
|
+
manifest 里的重定向地址 `{{signInCallbackUrl}}` 用于 **Sign in with Slack**(Slack 登录),需要部署
|
|
229
|
+
设置公网地址;未设置时,请从 manifest 中删掉该重定向地址,或请超级管理员设置 `http.publicUrl`。
|
|
230
|
+
|
|
231
|
+
::check capybara:public-url 平台已设置公网地址
|
|
232
|
+
|
|
233
|
+
## 插件更新了 manifest 时
|
|
234
|
+
|
|
235
|
+
Slack 插件更新并改动了 manifest 后,Capybara 会在这个渠道连接上显示提示。在
|
|
236
|
+
<https://api.slack.com/apps> 打开该应用,进入 **App Manifest**,粘贴新的 manifest 并保存,Slack
|
|
237
|
+
要求时重新安装应用,然后在这里点 **我已更新 Slack 应用** 确认。
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Set up the Slack connector
|
|
2
|
+
|
|
3
|
+
The Slack connector lets agents search, read and send Slack messages, canvases, lists and files
|
|
4
|
+
**as the person using them**, through Slack's MCP server. Each member connects their own Slack
|
|
5
|
+
account; there is no shared org token.
|
|
6
|
+
|
|
7
|
+
::: audience admin
|
|
8
|
+
An org admin sets it up once: create an internal Slack app (a separate app from the bot), then
|
|
9
|
+
enter its client id and secret here. Members connect afterwards.
|
|
10
|
+
|
|
11
|
+
## 1. Create the OAuth app
|
|
12
|
+
|
|
13
|
+
Open <https://api.slack.com/apps>, choose **Create New App → From a manifest** in the company
|
|
14
|
+
workspace and paste the manifest below. It turns on MCP and requests the user scopes the
|
|
15
|
+
{{templateName}} template asks for.
|
|
16
|
+
|
|
17
|
+
```yaml title="App manifest (Slack connector)"
|
|
18
|
+
# Slack app manifest for the "{{templateName}}" connector template ({{pluginName}} {{pluginVersion}}).
|
|
19
|
+
# A separate internal app: user scopes only, MCP on, no bot, no Socket Mode.
|
|
20
|
+
# Reference: https://docs.slack.dev/reference/app-manifest and
|
|
21
|
+
# https://docs.slack.dev/ai/slack-mcp-server/ (checked 2026-11-08).
|
|
22
|
+
display_information:
|
|
23
|
+
name: "Capybara connector"
|
|
24
|
+
description: Lets Capybara agents use Slack as you, with your permission.
|
|
25
|
+
background_color: "#3d2f24"
|
|
26
|
+
oauth_config:
|
|
27
|
+
redirect_urls:
|
|
28
|
+
- "{{oauthCallbackUrl}}"
|
|
29
|
+
scopes:
|
|
30
|
+
user:
|
|
31
|
+
- search:read.public
|
|
32
|
+
- search:read.private
|
|
33
|
+
- search:read.mpim
|
|
34
|
+
- search:read.im
|
|
35
|
+
- search:read.files
|
|
36
|
+
- search:read.users
|
|
37
|
+
- channels:history
|
|
38
|
+
- groups:history
|
|
39
|
+
- mpim:history
|
|
40
|
+
- im:history
|
|
41
|
+
- channels:read
|
|
42
|
+
- groups:read
|
|
43
|
+
- mpim:read
|
|
44
|
+
- im:read
|
|
45
|
+
- channels:write
|
|
46
|
+
- groups:write
|
|
47
|
+
- mpim:write
|
|
48
|
+
- im:write
|
|
49
|
+
- chat:write
|
|
50
|
+
- canvases:read
|
|
51
|
+
- canvases:write
|
|
52
|
+
- lists:read
|
|
53
|
+
- lists:write
|
|
54
|
+
- files:read
|
|
55
|
+
- files:write
|
|
56
|
+
- reactions:read
|
|
57
|
+
- reactions:write
|
|
58
|
+
- emoji:read
|
|
59
|
+
- users:read
|
|
60
|
+
- users:read.email
|
|
61
|
+
settings:
|
|
62
|
+
is_mcp_enabled: true
|
|
63
|
+
org_deploy_enabled: false # true for an Enterprise Grid org-wide install
|
|
64
|
+
socket_mode_enabled: false
|
|
65
|
+
token_rotation_enabled: false
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
::check capybara:public-url The platform has a public URL
|
|
69
|
+
|
|
70
|
+
## 2. Keep the app internal
|
|
71
|
+
|
|
72
|
+
- Leave **Manage Distribution** off. Slack's MCP server serves only internal apps and Marketplace
|
|
73
|
+
apps.
|
|
74
|
+
- Do **not** enable PKCE in the app settings: it turns the app into a public client for good.
|
|
75
|
+
Capybara stays a confidential client.
|
|
76
|
+
- Keep token rotation off (the manifest does); without it user tokens do not expire.
|
|
77
|
+
- Approve or install the app as your workspace requires (with "Only allow pre-approved apps", a
|
|
78
|
+
workspace admin approves it; on Enterprise Grid, an org admin).
|
|
79
|
+
|
|
80
|
+
## 3. Enter the client
|
|
81
|
+
|
|
82
|
+
Copy **Basic Information → App Credentials → Client ID** and **Client Secret** into the fields
|
|
83
|
+
below. The secret is stored encrypted and reads back only as "set".
|
|
84
|
+
|
|
85
|
+
::check capybara:oauth-client The client id and secret are entered
|
|
86
|
+
::check capybara:oauth-token-endpoint Slack accepts the client id and secret
|
|
87
|
+
::check capybara:connector-tools A member connected and the tool list was read
|
|
88
|
+
|
|
89
|
+
### Reusing the bot app instead
|
|
90
|
+
|
|
91
|
+
You can add the user scopes, turn on MCP and add the redirect URL `{{oauthCallbackUrl}}` to the
|
|
92
|
+
bot's app instead, as long as token rotation stays off (rotation is app-wide and would expire the
|
|
93
|
+
bot's `xoxb` token). Slack prefix-matches redirect URLs, so one entry `{{publicUrl}}/api/v1/`
|
|
94
|
+
covers this callback and the Sign in with Slack callback `{{signInCallbackUrl}}`.
|
|
95
|
+
|
|
96
|
+
## When the plugin changes this manifest
|
|
97
|
+
|
|
98
|
+
After an update that changes the scopes, Capybara shows a notice on the connector. Paste the new
|
|
99
|
+
manifest under **App Manifest**, save, and confirm here with **I have updated the Slack app**.
|
|
100
|
+
Members reconnect when Slack asks them to.
|
|
101
|
+
:::
|
|
102
|
+
|
|
103
|
+
::: audience member
|
|
104
|
+
## Connect your Slack account
|
|
105
|
+
|
|
106
|
+
Choose **Connect** and approve on Slack's consent screen. Agents then act in Slack as you, and
|
|
107
|
+
writes (sending, creating, reacting, uploading) ask you first unless your admin changed that.
|
|
108
|
+
|
|
109
|
+
**Disconnect** deletes the token in Capybara but does not revoke it at Slack: also remove the app
|
|
110
|
+
under your Slack profile's **Apps**, or ask a workspace admin.
|
|
111
|
+
|
|
112
|
+
::check capybara:connector-connected Your Slack account is connected
|
|
113
|
+
:::
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# 设置 Slack 连接器
|
|
2
|
+
|
|
3
|
+
Slack 连接器让智能体通过 Slack 的 MCP 服务器,**以使用者本人的身份**搜索、读取和发送 Slack 消息、
|
|
4
|
+
画布、列表和文件。每个成员连接自己的 Slack 账号,组织没有共用的令牌。
|
|
5
|
+
|
|
6
|
+
::: audience admin
|
|
7
|
+
由组织管理员设置一次:创建一个内部 Slack 应用(与机器人应用分开),再把它的 Client ID 和
|
|
8
|
+
Client Secret 填到这里。之后成员各自连接。
|
|
9
|
+
|
|
10
|
+
## 1. 创建 OAuth 应用
|
|
11
|
+
|
|
12
|
+
打开 <https://api.slack.com/apps>,在公司工作区选择 **Create New App → From a manifest**,粘贴
|
|
13
|
+
下面的 manifest。它会开启 MCP,并申请 {{templateName}} 模板需要的用户权限。
|
|
14
|
+
|
|
15
|
+
```yaml title="应用 manifest(Slack 连接器)"
|
|
16
|
+
# Slack app manifest for the "{{templateName}}" connector template ({{pluginName}} {{pluginVersion}}).
|
|
17
|
+
# A separate internal app: user scopes only, MCP on, no bot, no Socket Mode.
|
|
18
|
+
# Reference: https://docs.slack.dev/reference/app-manifest and
|
|
19
|
+
# https://docs.slack.dev/ai/slack-mcp-server/ (checked 2026-11-08).
|
|
20
|
+
display_information:
|
|
21
|
+
name: "Capybara connector"
|
|
22
|
+
description: Lets Capybara agents use Slack as you, with your permission.
|
|
23
|
+
background_color: "#3d2f24"
|
|
24
|
+
oauth_config:
|
|
25
|
+
redirect_urls:
|
|
26
|
+
- "{{oauthCallbackUrl}}"
|
|
27
|
+
scopes:
|
|
28
|
+
user:
|
|
29
|
+
- search:read.public
|
|
30
|
+
- search:read.private
|
|
31
|
+
- search:read.mpim
|
|
32
|
+
- search:read.im
|
|
33
|
+
- search:read.files
|
|
34
|
+
- search:read.users
|
|
35
|
+
- channels:history
|
|
36
|
+
- groups:history
|
|
37
|
+
- mpim:history
|
|
38
|
+
- im:history
|
|
39
|
+
- channels:read
|
|
40
|
+
- groups:read
|
|
41
|
+
- mpim:read
|
|
42
|
+
- im:read
|
|
43
|
+
- channels:write
|
|
44
|
+
- groups:write
|
|
45
|
+
- mpim:write
|
|
46
|
+
- im:write
|
|
47
|
+
- chat:write
|
|
48
|
+
- canvases:read
|
|
49
|
+
- canvases:write
|
|
50
|
+
- lists:read
|
|
51
|
+
- lists:write
|
|
52
|
+
- files:read
|
|
53
|
+
- files:write
|
|
54
|
+
- reactions:read
|
|
55
|
+
- reactions:write
|
|
56
|
+
- emoji:read
|
|
57
|
+
- users:read
|
|
58
|
+
- users:read.email
|
|
59
|
+
settings:
|
|
60
|
+
is_mcp_enabled: true
|
|
61
|
+
org_deploy_enabled: false # true for an Enterprise Grid org-wide install
|
|
62
|
+
socket_mode_enabled: false
|
|
63
|
+
token_rotation_enabled: false
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
::check capybara:public-url 平台已设置公网地址
|
|
67
|
+
|
|
68
|
+
## 2. 保持应用为内部应用
|
|
69
|
+
|
|
70
|
+
- 不要开启 **Manage Distribution**。Slack 的 MCP 服务器只服务内部应用和 Marketplace 应用。
|
|
71
|
+
- **不要**在应用设置里开启 PKCE:开启后应用会永久变成公开客户端。Capybara 始终是机密客户端。
|
|
72
|
+
- 保持令牌轮换关闭(manifest 已关闭);不轮换时用户令牌不会过期。
|
|
73
|
+
- 按工作区的要求批准或安装应用(开启了「Only allow pre-approved apps」时由工作区管理员批准;
|
|
74
|
+
Enterprise Grid 上由组织管理员批准)。
|
|
75
|
+
|
|
76
|
+
## 3. 填写客户端
|
|
77
|
+
|
|
78
|
+
把 **Basic Information → App Credentials → Client ID** 和 **Client Secret** 填进下方的字段。
|
|
79
|
+
密钥加密存储,读回时只显示「已设置」。
|
|
80
|
+
|
|
81
|
+
::check capybara:oauth-client 已填写 Client ID 和 Client Secret
|
|
82
|
+
::check capybara:oauth-token-endpoint Slack 接受该 Client ID 和 Client Secret
|
|
83
|
+
::check capybara:connector-tools 已有成员连接并读取到工具列表
|
|
84
|
+
|
|
85
|
+
### 改用机器人应用
|
|
86
|
+
|
|
87
|
+
也可以把这些用户权限、MCP 开关和重定向地址 `{{oauthCallbackUrl}}` 加到机器人应用上,前提是令牌
|
|
88
|
+
轮换保持关闭(轮换对整个应用生效,会让机器人的 `xoxb` 令牌过期)。Slack 按前缀匹配重定向地址,
|
|
89
|
+
所以一条 `{{publicUrl}}/api/v1/` 就能同时覆盖这个回调和 Slack 登录的回调 `{{signInCallbackUrl}}`。
|
|
90
|
+
|
|
91
|
+
## 插件更新了 manifest 时
|
|
92
|
+
|
|
93
|
+
插件更新并改动了权限后,Capybara 会在连接器上显示提示。在 **App Manifest** 粘贴新的 manifest
|
|
94
|
+
并保存,然后在这里点 **我已更新 Slack 应用** 确认。Slack 要求时,成员重新连接。
|
|
95
|
+
:::
|
|
96
|
+
|
|
97
|
+
::: audience member
|
|
98
|
+
## 连接你的 Slack 账号
|
|
99
|
+
|
|
100
|
+
点 **连接**,在 Slack 的授权页面上同意。之后智能体会以你的身份在 Slack 中操作;写操作(发送、
|
|
101
|
+
创建、回应、上传)会先征求你的同意,除非管理员改了设置。
|
|
102
|
+
|
|
103
|
+
**断开连接** 会删除 Capybara 中的令牌,但不会在 Slack 端撤销它:请同时在 Slack 个人资料的
|
|
104
|
+
**Apps** 中移除该应用,或请工作区管理员处理。
|
|
105
|
+
|
|
106
|
+
::check capybara:connector-connected 你的 Slack 账号已连接
|
|
107
|
+
:::
|