curriculum-project-hub/docs/para-26071100-feishu-setup.md

Educraft 组织接入与飞书应用配置指南

本文供准备接入 Educraft Alpha Silo 的学校、教培机构和组织管理员使用。完成本文后，请把末尾的“部署信息交付单”交给 Educraft 部署人员；我们会为组织创建独立的服务账号、数据库、运行目录和域名入口。

安全提醒： App Secret、模型 Provider Token 属于密钥，禁止粘贴到飞书群、普通云文档、工单正文或截图中。请只通过双方约定的安全渠道传递。

1. 双方分别负责什么

角色	负责事项
组织管理员	创建企业自建应用、启用机器人、开通最小权限、配置事件、回调和 OAuth 重定向 URL、发布应用、提供 OWNER 身份
Educraft 部署人员	分配组织 slug 和域名、部署独立 Silo、加密保存应用及模型密钥、初始化 OWNER、联调和验收
试点 OWNER	把机器人加入试点群、创建或绑定项目、组织首轮验收

2. 创建企业自建应用

1. 打开飞书开放平台开发者后台。
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 后确认。导入只会新增本次列出的权限，不会删除或影响应用已经申请、开通的其他权限。

{
  "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：

https://<organization-slug>.educraft.paradigm-edu.net/auth/feishu/callback

例如组织 slug 为 example-school：

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. 打开飞书开放平台的“获取单个用户信息”接口页面。如果使用带 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 不是必填项，查不到可以留空。

最终向部署人员提供：

OWNER Open ID：ou_...
OWNER 显示名称：
OWNER Union ID：（可选）
用于查询的 App ID：cli_...

Open ID 和显示名称可以放在普通交付单中；不要把 App Secret 一起粘贴进去。

8. 部署信息交付单

请复制下面的模板填写。标注“安全渠道”的字段不要与普通字段放在同一条群消息或云文档中。

【组织信息】
组织正式名称：
组织简称：
期望 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 不提供开放注册、自助密钥管理或跨组织资源共享。