# 接入消息通道：企业微信 / 飞书 / Slack

> Vinez 支持企业微信智能机器人、飞书自建应用和 Slack app。聊天通道为可选项；不配置也可以使用 Web 或 App。

## 0. 开始前

| 通道 | 连接方式 | 配置完成后 |
|---|---|---|
| 企业微信 | API 模式 → **使用长连接** | 保存 Bot ID 和 Secret |
| 飞书 | 事件订阅 → **使用长连接接收事件** | **发布新版本并完成管理员审核** |
| Slack | **Socket Mode** | **Install / Reinstall to Workspace** |

不需要公网 IP、域名或回调地址。同一个机器人只连接一台运行 Vinez 的机器。

## 1. 写入配置

编辑 `~/.vinez/config.yaml`：

```yaml
wecom:
  bot_id: <企微智能机器人 Bot ID>
  secret: <企微智能机器人 Secret>
  bot_name: vinez
feishu:
  app_id: <飞书自建应用 App ID>
  app_secret: <飞书自建应用 App Secret>
slack:
  bot_token: xoxb-…
  app_token: xapp-…
```

也可以使用环境变量：

```text
VINEZ_WECOM_BOT_ID / _SECRET / _ENDPOINT / _BOT_NAME
VINEZ_FEISHU_APP_ID / _APP_SECRET
VINEZ_SLACK_BOT_TOKEN / _APP_TOKEN
```

不要把凭据提交到版本库。保存配置后重启 Vinez。

## 2. 企业微信

1. 打开**企业微信客户端** → **工作台** → **智能机器人**。
2. 选择**创建机器人** → **手动创建**。
3. 进入 **API 模式**，选择**使用长连接**。
4. 复制 **Bot ID** 和 **Secret**，填写 `wecom.bot_id` 和 `wecom.secret`。
5. 将 `wecom.bot_name` 设为机器人的实际名称，不包含 `@`。
6. 保存配置并重启 Vinez。

建议直接私聊机器人派活；需要群内协作时，在群聊中 @机器人。私有化部署时填写 `wecom.endpoint`，公有云环境留空。

## 3. 飞书

1. 打开[飞书开放平台](https://open.feishu.cn/app)，创建**企业自建应用**。
2. 添加**机器人**能力。
3. 在**凭证与基础信息**中复制 **App ID** 和 **App Secret**，填写 `feishu.app_id` 和 `feishu.app_secret`。
4. 在**事件订阅**中选择**使用长连接接收事件**，订阅消息接收事件。
5. 在**权限管理**中申请以下权限：

| 权限 | 用途 |
|---|---|
| `contact:user.employee_id:readonly` | 获取成员 `user_id` |
| `im:message.p2p_msg:readonly` | 接收私聊消息 |
| `im:message.group_at_msg.include_bot:readonly` | 接收群里 @机器人的消息 |
| `im:message:readonly` | 读取消息、附件和引用内容 |
| `im:message:send_as_bot` | 以应用身份发送与更新消息 |
| `im:resource:upload` | 发送图片（`/bind` 的配对二维码） |

也可以在**权限管理 → 批量导入/导出权限**中，清空输入框后整段粘贴以下 JSON 一次性开通：

```json
{
  "scopes": {
    "tenant": [
      "contact:user.employee_id:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg.include_bot:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource:upload"
    ],
    "user": []
  }
}
```

6. **发布新版本并等待企业管理员审核通过**。
7. 保存配置并重启 Vinez。

建议直接私聊机器人派活；需要群内协作时，在群聊中 @机器人。

## 4. Slack

1. 打开 [Slack App 管理页](https://api.slack.com/apps)。
2. 选择 **Create New App** → **From an app manifest**。
3. 选择 Workspace，粘贴以下 Manifest：

```yaml
display_information:
  name: vinez
  description: Team AI engineering execution center
features:
  bot_user:
    display_name: vinez
    always_online: true
  slash_commands:
    - command: /vinez
      description: "vinez: check tasks, list, stop, send feedback, pair app"
      usage_hint: "[help | list | status <id> | stop <id> | done <id> | fb <text> | bind]"
      should_escape: false
oauth_config:
  scopes:
    bot:
      - chat:write
      - im:write
      - im:history
      - channels:history
      - groups:history
      - files:read
      - files:write
settings:
  event_subscriptions:
    bot_events:
      - message.im
      - message.channels
      - message.groups
  socket_mode_enabled: true
```

4. 打开 **Basic Information → App-Level Tokens**，生成包含 `connections:write` 的 `xapp-…`，填写 `slack.app_token`。
5. 打开 **OAuth & Permissions → Install to Workspace**，复制 `xoxb-…`，填写 `slack.bot_token`。
6. 保存配置并重启 Vinez。
7. 修改权限或斜杠命令后，执行 **Reinstall to Workspace**。

建议直接私聊机器人派活；需要频道内协作时，先邀请机器人，再 @机器人。

常用命令：

```text
/vinez help
/vinez list
/vinez status 5
/vinez stop 5
/vinez fb 反馈内容
/vinez bind
```

## 5. 绑定用户身份

打开 **Web 后台 → 用户 → 绑定身份**，为每位使用者填写对应通道的成员 ID：

| 通道 | 填写内容 | 获取位置 |
|---|---|---|
| 企业微信 | userid，例如 `ZhangSan` | 企微管理后台的成员 UserID |
| 飞书 | `user_id`，不是 `open_id` | 管理后台的用户信息 |
| Slack | Member ID，以 `U` 开头 | 头像 → 个人资料 → `⋮` → Copy member ID |

## 6. 排障

| 症状 | 处理 |
|---|---|
| 完全没反应，日志里没有入站记录 | 在群聊中 @机器人；Slack 频道先邀请机器人；检查日志中是否出现“已连接” |
| 消息收到后只返回绑定提示 | 在 Web 后台绑定该用户的通道身份 |
| Slack 报 `missing_scope` | 执行 **Reinstall to Workspace**，再检查实际生效的权限 |
| Slack 无法下载或发送图片 | 确认已配置 `files:read` 和 `files:write`，然后重新安装到 Workspace |
| Slack 提示 `/vinez` 不是有效命令 | 重新导入 Manifest，并执行 **Reinstall to Workspace** |
| Slack 斜杠命令可用，普通消息无响应 | 检查 Manifest 中的 `message.*` 事件订阅 |
| 飞书报 `99991672`（收消息、下载附件时） | 添加 `im:message:readonly`，发布新版本并等待审核 |
| 飞书报 `99991672`（`/bind` 只回文本、没有二维码） | 添加 `im:resource:upload`，发布新版本并等待审核 |
| 飞书日志提示无法获取 `user_id` | 添加 `contact:user.employee_id:readonly`，发布新版本并等待审核 |
| 飞书权限未生效 | 发布新版本，并等待企业管理员审核通过 |
| 企业微信突然收不到消息 | 将 API 模式改回“使用长连接”，并确认没有其他 Vinez 实例连接同一机器人 |

日志位置：`~/.vinez/logs/vinezd.log`。