forked from EduCraft/curriculum-project-hub
222 lines
11 KiB
Markdown
222 lines
11 KiB
Markdown
# Educraft 组织接入与飞书应用配置指南
|
||
|
||
本文供准备接入 Educraft Alpha Silo 的学校、教培机构和组织管理员使用。完成本文后，请把末尾的“部署信息交付单”交给 Educraft 部署人员；我们会为组织创建独立的服务账号、数据库、运行目录和域名入口。
|
||
|
||
> **安全提醒：** App Secret、模型 Provider Token 属于密钥，禁止粘贴到飞书群、普通云文档、工单正文或截图中。请只通过双方约定的安全渠道传递。
|
||
|
||
## 1. 双方分别负责什么
|
||
|
||
| 角色 | 负责事项 |
|
||
| --- | --- |
|
||
| 组织管理员 | 创建企业自建应用、启用机器人、开通最小权限、配置事件、回调和 OAuth 重定向 URL、发布应用、提供 OWNER 身份 |
|
||
| Educraft 部署人员 | 分配组织 slug 和域名、部署独立 Silo、加密保存应用及模型密钥、初始化 OWNER、联调和验收 |
|
||
| 试点 OWNER | 把机器人加入试点群、创建或绑定项目、组织首轮验收 |
|
||
|
||
## 2. 创建企业自建应用
|
||
|
||
1. 打开[飞书开放平台开发者后台](https://open.feishu.cn/app)。
|
||
2. 在目标企业下点击“创建企业自建应用”。应用名称建议填写“Educraft + 组织简称”。
|
||
3. 进入“凭证与基础信息”，记录 App ID 和 App Secret。
|
||
4. 进入“添加应用能力”，添加并启用“机器人”。
|
||
|
||
|
||
|
||
App ID 通常以 `cli_` 开头，可以写入交付单。App Secret 必须通过安全渠道单独发送。Bot Open ID 不需要管理员手工查找；部署程序会用 App ID/App Secret 调用 Bot Info API 获取并校验归属。
|
||
|
||
## 3. 开通最小权限
|
||
|
||
进入“权限管理”，点击“开通权限”，搜索并申请以下应用身份权限。控制台中文名称可能调整，请优先核对 scope。
|
||
|
||
| 用途 | Scope |
|
||
| --- | --- |
|
||
| 接收群聊中 @ 机器人的消息 | `im:message.group_at_msg:readonly` |
|
||
| 以应用身份发送消息 | `im:message:send_as_bot` |
|
||
| 读取触发消息和线程上下文 | `im:message:readonly` |
|
||
| 获取与上传图片或文件 | `im:resource` |
|
||
| 添加、删除消息表情回复 | `im:message.reactions:write_only` |
|
||
| 获取用户基本信息 | `contact:user.base:readonly` |
|
||
| 获取用户基本资料 | `contact:user.basic_profile:readonly` |
|
||
| 通过手机号或邮箱查询 OWNER Open ID | `contact:user.id:readonly` |
|
||
|
||
### 批量导入权限（推荐）
|
||
|
||
在“权限管理”页面点击“批量处理 → 导入”，粘贴以下 JSON 后确认。导入只会新增本次列出的权限，不会删除或影响应用已经申请、开通的其他权限。
|
||
|
||
```json
|
||
{
|
||
"scopes": {
|
||
"tenant": [
|
||
"im:message.group_at_msg:readonly",
|
||
"im:message:send_as_bot",
|
||
"im:message:readonly",
|
||
"im:resource",
|
||
"im:message.reactions:write_only",
|
||
"contact:user.base:readonly",
|
||
"contact:user.basic_profile:readonly",
|
||
"contact:user.id:readonly"
|
||
],
|
||
"user": []
|
||
}
|
||
}
|
||
```
|
||
|
||
Educraft 机器人以应用身份调用上述 API，因此这些 scope 全部放在 `tenant`，不要为了省事把相同权限重复放进 `user`。
|
||
|
||
|
||
|
||
如果 API 调试台提示缺少更细粒度权限，请把错误提示和发生时间截图给部署人员。不要自行开通通讯录全量读取等超出本表的权限。
|
||
|
||
## 4. 配置事件与卡片回调
|
||
|
||
进入“事件与回调”。
|
||
|
||
1. 在“事件配置”中将订阅方式设为“使用长连接接收事件”。
|
||
2. 添加事件“接收消息” `im.message.receive_v1`。
|
||
3. 添加事件“解散群” `im.chat.disbanded_v1`，用于立即归档该群的项目绑定。
|
||
4. 添加事件“机器人被移出群” `im.chat.member.bot.deleted_v1`，用于立即归档该群的项目绑定。
|
||
5. 在“回调配置”中同样选择长连接。
|
||
6. 添加回调“卡片回传交互” `card.action.trigger`，用于审批、运行中断和项目创建/绑定按钮。
|
||
|
||
|
||
|
||
|
||
|
||
这里不需要填写公网 Event Callback URL。Educraft Hub 使用飞书官方 SDK 的长连接模式。
|
||
|
||
## 5. 配置用户 OAuth 重定向 URL（必需）
|
||
|
||
普通群成员首次使用前，需要通过飞书 OAuth 建立其在本应用下的用户身份。进入“安全设置 → 重定向 URL”，添加组织专属 callback：
|
||
|
||
```text
|
||
https://<organization-slug>.educraft.paradigm-edu.net/auth/feishu/callback
|
||
```
|
||
|
||
例如组织 slug 为 `example-school`：
|
||
|
||
```text
|
||
https://example-school.educraft.paradigm-edu.net/auth/feishu/callback
|
||
```
|
||
|
||
|
||
|
||
必须使用 Educraft 部署人员最终确认的 slug；不要直接照抄示例。该 URL 用于 OAuth 返回并创建应用作用域下的飞书用户身份，不代表当前已经开放组织管理台。
|
||
|
||
组织专属 OAuth 同时完成身份建立和入组：首次成功登录的用户会自动成为当前 Organization 的 `MEMBER`，回到群聊即可使用。`OWNER` 和 `ADMIN` 仍只能由部署人员或管理员显式授予；曾被移除的成员重新登录不会自动恢复资格。
|
||
|
||
## 6. 发布并安装应用
|
||
|
||
1. 进入“版本管理与发布”，点击“创建版本”。
|
||
2. 将应用可用范围至少覆盖试点 OWNER 和试点群成员。
|
||
3. 提交企业管理员审核并发布。
|
||
4. 发布成功后，将机器人加入准备试用的群。
|
||
|
||
|
||
|
||
仅保存开发配置但未发布时，新增权限、事件和可用范围通常不会对试点用户生效。
|
||
|
||
## 7. 获取首位 OWNER 身份
|
||
|
||
首次部署必须指定一位组织 OWNER。OWNER 是 Educraft 组织内的初始管理员，不等同于飞书应用所有者；两者可以是同一个人，也可以不同。部署所需的 Open ID 必须由本次创建的企业自建应用查询，因为同一用户在不同应用下的 Open ID 不同，不能复用其他应用查到的值。
|
||
|
||
### 7.1 确认 OWNER
|
||
|
||
先确认哪一位企业成员将担任 OWNER。记录其飞书显示名称，并准备在飞书的成员选择器中按姓名找到本人。若企业内有同名成员，选择前须通过部门等信息核对身份。
|
||
|
||
### 7.2 开通查询权限和数据范围
|
||
|
||
确认应用已开通上文列出的用户基本信息和用户 ID 权限。如果使用上文的批量导入 JSON，这些权限已包含在内。
|
||
|
||
应用的通讯录数据范围还必须覆盖这位 OWNER。最小做法是把 OWNER 加入应用可用范围；不需要为此开放全企业通讯录。
|
||
|
||
### 7.3 在官方接口页面获取 Open ID
|
||
|
||
1. 打开飞书开放平台的[“获取单个用户信息”接口页面](https://open.feishu.cn/document/server-docs/contact-v3/user/get)。如果使用带 `appId` 参数的页面链接，可以直接进入对应应用；本文不提供固定 App ID，请在页面顶部选择本组织刚创建的企业自建应用，并核对 App ID 与交付单一致。
|
||
2. 找到路径参数 `user_id`，点击参数输入框旁的“获取”。
|
||
3. 在成员选择器中找到并选择 OWNER；如有同名成员，依据部门等信息确认本人。
|
||
4. ID 类型选择 `open_id`。将选择器返回的值填入 `user_id`，并保持查询参数 `user_id_type=open_id`。
|
||
5. 以应用身份（`tenant_access_token`）调用接口，核对成功响应中 `data.user.name` 与 OWNER 本人一致。
|
||
6. 复制完整的 `data.user.open_id` 交给 Educraft 部署人员。Open ID 通常以 `ou_` 开头。
|
||
|
||
参数旁的“获取”是飞书文档调试台提供的成员选择功能，不是要求管理员预先知道 Open ID。不要复用其他应用查到的 Open ID；同一用户在不同应用下的 Open ID 不同。若无法选择成员或接口调用失败，依次检查：页面当前选择的 App ID、应用可用范围和通讯录数据范围是否覆盖 OWNER、用户基本信息与用户 ID 权限是否已开通并随应用版本发布。
|
||
|
||
### 7.4 核对并交付
|
||
|
||
交付前完成以下检查：
|
||
|
||
- 返回用户的姓名与 OWNER 本人一致；
|
||
- Open ID 来自本次组织的这一个 App ID；
|
||
- Open ID 完整复制，没有空格或省略号；
|
||
- 显示名称使用组织希望在 Educraft 中展示的姓名；
|
||
- Union ID 不是必填项，查不到可以留空。
|
||
|
||
最终向部署人员提供：
|
||
|
||
```text
|
||
OWNER Open ID：ou_...
|
||
OWNER 显示名称：
|
||
OWNER Union ID：（可选）
|
||
用于查询的 App ID：cli_...
|
||
```
|
||
|
||
Open ID 和显示名称可以放在普通交付单中；不要把 App Secret 一起粘贴进去。
|
||
|
||
## 8. 部署信息交付单
|
||
|
||
请复制下面的模板填写。标注“安全渠道”的字段不要与普通字段放在同一条群消息或云文档中。
|
||
|
||
```text
|
||
【组织信息】
|
||
组织正式名称：
|
||
组织简称：
|
||
期望 organization slug：（小写字母、数字和连字符，例如 example-school）
|
||
期望机器人显示名称：
|
||
|
||
【飞书应用】
|
||
App ID：cli_...
|
||
App Secret：（通过安全渠道单独发送）
|
||
应用已发布：是 / 否
|
||
机器人能力已启用：是 / 否
|
||
消息事件（含解散群、机器人被移出群）和卡片回调已配置：是 / 否
|
||
OAuth 重定向 URL 已配置：是 / 否
|
||
|
||
【首位 OWNER】
|
||
OWNER Open ID：ou_...
|
||
OWNER 显示名称：
|
||
OWNER Union ID：（可选）
|
||
|
||
【试点范围】
|
||
试点群名称：（可选，用于验收定位）
|
||
初始 Team 名称：（可选；没有 Team 不影响首次部署）
|
||
预计试用人数：
|
||
|
||
【模型配置】
|
||
Provider 名称：（例如 OpenRouter）
|
||
Provider Base URL：
|
||
Provider Token：（通过安全渠道单独发送）
|
||
启用的模型 ID：
|
||
```
|
||
|
||
Educraft 部署人员收到信息后，会回传最终 organization slug、访问域名、部署窗口和验收时间。若期望 slug 已被占用或不符合命名规则，会在部署前协调调整。
|
||
|
||
## 9. 上线验收
|
||
|
||
部署人员通知服务就绪后，由 OWNER 完成：
|
||
|
||
1. OWNER 在试点群中 @机器人发送一条纯文本消息。
|
||
2. 如果群尚未绑定项目，确认机器人返回项目创建/绑定卡片。
|
||
3. 创建项目后再次 @机器人，确认出现处理状态、流式卡片和最终回答。
|
||
4. 选择一位非 OWNER 试点成员完成 OAuth 登录，确认其自动以 MEMBER 身份加入组织。
|
||
5. 该成员在同一群中 @机器人，确认能够进入已绑定项目。
|
||
6. 测试一个小文件附件、一次运行中断，以及一个需要生成文档的任务。
|
||
|
||
出现问题时，请保留发生时间、群名、消息截图和飞书 request/log ID。截图前确认其中不包含 App Secret、Provider Token 或其他密钥。
|
||
|
||
## 10. Alpha 阶段边界
|
||
|
||
- 每个组织运行在独立的系统用户、服务实例、数据库和持久化目录中。
|
||
- 组织的 role、system prompt、tools 和 skills 是运行时配置，不需要跟随版本发布。
|
||
- 同一项目同一时间只执行一个任务，避免并发修改同一个 workspace；组织级并发上限由部署配置决定。
|
||
- 当前由 Educraft 人工创建组织、OWNER、Provider Connection 和初始 Team，并通过服务器上的受控管理命令运维；组织管理台尚未开放。
|
||
- 非 OWNER 试点成员通过组织专属 OAuth 首次登录后自动成为 MEMBER；OWNER/ADMIN 提权和被移除成员的恢复仍需人工操作。
|
||
- Alpha 不提供开放注册、自助密钥管理或跨组织资源共享。
|