镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/message-channels.md ↗
消息渠道与飞书应用机器人
飞书与 Web 共用 ManagementAgent、ManagementService、工具目录、统一授权、版本检查和审计。渠道适配器只证明来源,不能从消息正文、卡片参数、姓名、邮箱、群主身份或飞书管理员身份生成权限。外部身份键包含 provider、连接与 App ID、操作者 tenant_key 和 open_id;安装 tenant_key 独立保存并参与检查。
配置与权限
每个飞书应用连接(channel_connectors 的一行,同一 App ID 在同一安装企业只能登记一次)要么全平台共用,要么归属一个 GitHub 组织(#424)。全平台应用由超级管理员配置,未接入 GitHub 项目时也可先连接;组织的应用让不同飞书企业各自使用自建应用。连接不会为任何人增加项目权限。
升级前应停止写入并备份控制面数据库。启动迁移会移除旧组织字段及操作者企业白名单字段 actor_tenants;已有连接同步取消操作者企业限制。若回退到仍使用这些字段的版本,需在停写后恢复迁移前的数据库,不能只切换旧镜像。
应用的归属与可见范围
| 操作 | 全平台应用 | 组织的应用 |
|---|---|---|
| 新增 | 超级管理员 | 超级管理员;该组织的组织管理员(组织级 config.write);该组织任一仓库的管理员(该仓库的 config.write) |
| 查看、绑定身份、在其群中配置助手 | 所有用户 | 在该组织有任一有效授权的人,以及超级管理员 |
| 管理(改密钥、启停、向导、收发诊断、配置回执) | 超级管理员 | 创建人(仍能在该组织新增应用时)、该组织的组织管理员、超级管理员 |
- 所属组织(
owner_tenant,空值表示全平台)、创建人(created_by)在创建时写入;所属组织、App ID 和安装企业此后都不能修改,修改返回 400channel_application_immutable,避免经该应用绑定的身份和群失效。换用另一个应用时新增一个连接。 - 不是超级管理员的人新增或修改的应用只能是“企业自建 + SDK 长连接”,HTTP 回调和商店应用返回 403
channel_transport_forbidden:持有 Verification Token 和 Encrypt Key 的人可以伪造任意成员发来的消息。超级管理员可以为组织配置 HTTP 应用;之后组织管理员修改它时,也必须改为长连接。 - 没有权限时返回 403
channel_application_forbidden。既不能在任何组织新增应用、也不能管理任何应用的人,打开应用列表(GET /api/channels/setup、GET /api/channels/connectors)同样返回 403;其他人只列出自己能管理的应用,platform表示能否新增全平台应用,organizations列出能新增应用的组织。
组织的应用另有两条边界,全平台应用不受影响:
- 群只能使用本组织的仓库。 应用创建者握有 App Secret,可以用飞书接口读取机器人所在群的全部消息,包括助手回复。经组织应用接入的群,群聊助手的范围只能选该组织的仓库或整个组织,否则返回 403
channel_service_scope_outside_organization;它的私聊也只能登记为该组织项目的通知目的地(channel_application_scope_forbidden)。 - 经组织应用绑定的飞书身份只在该组织内生效。 该飞书企业的管理员可以接管企业内成员的账号,所以经这个应用发来的私聊和定时任务只使用此人在该组织内的授权:不使用平台级授权(超级管理员也按普通成员处理),也不能访问其他组织(
tenant_forbidden)。私聊的管理会话范围是该组织(tenant:<组织>);此人在该组织没有任何可访问的项目时,回复channel_application_tenant_forbidden的说明。实现上由confineActor把操作者限定在该组织,派生出的操作者都继承这一限制。
在 #424 之前创建的连接迁移为全平台应用,行为不变。本节取代了 #236 中“飞书应用只由超级管理员管理”的规则。
连接向导
超级管理员从「全局设置 → 飞书连接」(/#/settings/feishu)进入应用连接向导;组织管理员和仓库管理员从「个人设置 → 飞书绑定」的“连接或管理本组织的飞书应用”进入同一向导(/#/identity/feishu-apps),向导第 2 步选择应用所属(全平台或某个组织)。个人飞书绑定与群绑定统一在「个人设置 → 飞书绑定」(/#/identity/feishu)中以列表展示与管理。顶部不再单列「消息渠道」,旧 /#/channels 与 /#/identity/feishu/groups 地址会跳转到统一的飞书绑定入口,旧 /#/identity/feishu/conversations 跳转到飞书会话页,GitHub 绑定回调也直接返回飞书绑定入口。
连接列表优先显示应用名称和安装企业名称,同时保留 App ID、启用状态和接收方式。自建应用自动发现机器人和安装企业时一并保存名称;超级管理员打开连接列表时自动刷新应用信息并检查飞书权限(见下文「权限检查」),也可点击“刷新应用信息与权限”。除机器人接口外,服务端查询当前应用信息,优先使用中文应用名称,避免机器人接口仍返回改名前名称;该查询只接受当前连接的 App ID。缺少权限时提示开通 admin:app.info:readonly 并发布,也可使用已有的 application:application:self_manage 权限,系统不会自动修改飞书权限。企业名称查询需要应用身份权限 tenant:tenant:readonly;商店应用还需先收到有效票据。查询失败或飞书暂未返回名称时保留已缓存的名称,并提示缺失信息或失败原因。仅更新名称不改变配置版本;切换应用或安装企业时清除旧名称,避免显示前一个连接的企业信息。个人绑定页读取缓存,不因普通用户刷新而调用飞书管理接口。
向导分五步,可从已保存连接继续:
- 创建应用:打开飞书开发者后台,开启机器人能力,按应用类型复制完整权限 JSON,在飞书「权限管理 → 批量导入/导出」一次导入。两种类型均包含消息收发和卡片创建更新;企业自建另含应用身份权限“获取企业信息”(
tenant:tenant:readonly),需先发布包含机器人能力与该权限的初始版本、通过必要审核,再保存连接。企业自建可选择 SDK 长连接或 HTTP,商店应用只能使用 HTTP。 - 应用凭据:填写 App ID 和 App Secret。机器人 open_id 无需填写;自建应用保存时由服务端用有效凭据自动读取机器人身份和安装 tenant_key,读取失败则不保存改动,需先启用机器人能力并发布初始版本后重试。商店应用另需指定安装 tenant_key,才能换取该企业的访问令牌。两种应用均不限制操作者所属企业,无需填写企业白名单。HTTP 另需 Verification Token 和 Encrypt Key。编辑时空白凭据保留原值,填写其中一项只替换该项。保存时显式选择是否启用连接。
- 事件与回调:页面将操作集中为三个编号步骤:配置事件、配置新版卡片回调、保存并前往发布。先在“事件配置”设置接收方式并添加
im.message.receive_v1、应用生命周期、群成员变更及商店应用票据事件;再在“回调配置”单独设置接收方式,在“添加回调 → 卡片”选择推荐的新版“卡片回传交互”card.action.trigger;最后确认两个页签均已保存,再进入发布步骤。HTTP 在两个页签分别选择发送至开发者服务器,填写本部署公网入口下的同一个回调 URL,并分别通过地址验证;长连接等待连接建立后,在两个页签分别保存“使用长连接接收事件”和“使用长连接接收回调”。旧版“消息卡片回传交互(旧)”card.action.trigger_v1不支持长连接,本系统使用新版回调。 - 发布与检查:在飞书发布版本、设置可用范围并完成必要审核,再检查机器人信息;检查自动同步保存机器人身份。商店应用先保存连接配置、接收 app_ticket,再完成此检查,未获取机器人身份时拒绝处理消息和卡片。检查只证明凭据和机器人信息可读,不证明消息或卡片回调已经送达。
- 绑定与试用:每位用户完成个人双端绑定,在私聊直接发送“你好”或“我能管理哪些项目”,收到助手回复后才完成接入;此页可查看收件和发送状态。群聊的项目范围、权限档位与服务角色在「个人设置 → 飞书绑定」点击「创建群绑定」或对应群条目的「配置仓库与权限」单独设置。结果卡片只带“登录后台查看”链接,不再有回调按钮;较早版本发出的“刷新执行状态”按钮点击后提示已过期。
富文本与图片、文件是默认能力;交互卡片继续支持。所需权限只在服务端 FEISHU_SCOPES(src/channels/feishu.ts)维护一份,经 GET /api/channels/setup 的 feishu_scopes 下发:向导第 1 步和连接列表里的完整权限 JSON、连接的自动权限检查都由它生成。下表与它逐项一致,test/channel-setup.test.mjs 会核对。JSON 按当前应用类型生成,包含以下应用身份权限,个人身份权限为空;获取企业信息和包含机器人消息的权限仅加入企业自建应用的权限 JSON:
| 权限 | 用途 |
|---|---|
im:message.p2p_msg:readonly |
接收用户私聊消息 |
im:message.group_at_msg:readonly |
接收群内 @ 机器人的消息 |
im:message:send_as_bot |
以机器人身份发送消息、发送和更新交互卡片 |
im:resource |
获取与上传消息中的图片和文件;已有连接也需导入完整权限并发布生效 |
im:message.reactions:write_only |
在正在处理的原消息下添加表情,回复送达后删除 |
cardkit:card:write |
创建与更新卡片 |
im:message.group_msg |
接收群内用户消息,并满足群历史读取接口的额外权限要求;不包含其他机器人的实时消息 |
im:message.group_msg.include_bot:read |
企业自建应用接收群内用户及其他机器人的消息,不推送本机器人自己发送的消息;商店应用不申请 |
im:message:readonly |
读取机器人所在会话的可见历史及接收撤回事件 |
im:chat:read |
查看群信息,订阅群解散事件 im.chat.disbanded_v1 |
im:chat.members:bot_access |
接收机器人进群、移出事件 |
im:chat.members:read |
判断当前 bot 是否在群中并完整分页核验维护人及来源成员;保存群聊助手绑定时必需,缺少时保存返回 channel_audience_permission_required |
contact:contact.base:readonly |
调用通讯录用户资料接口;与姓名字段权限一起开通并发布,通讯录可见范围须包含本人 |
contact:user.base:readonly |
读取已绑定用户的飞书姓名;需发布生效,通讯录可见范围须包含本人 |
tenant:tenant:readonly |
企业自建应用自动获取安装 tenant_key;保存连接前需开通并发布生效 |
这两项群消息权限用途不同:根据接收消息事件,im:message.group_msg 只推送用户消息,include_bot:read 还推送其他机器人消息,且当前仅支持企业自建应用。企业自建连接同时申请两项,因为获取会话历史消息仍明确要求 im:message.group_msg 与消息读取权限;新增的事件权限不替代历史接口权限。机器人消息安静进入本地记录,后续用户 @ 时可作为上下文,消息来源仍保留为 bot/app;机器人消息本身不触发模型或业务操作。当前机器人的群回复通过本地发送记录保留,不能依赖接收事件回传。
权限检查:连接列表每次打开或刷新时,服务端用该连接的应用身份调用飞书查询租户授权状态(GET /open-apis/application/v6/scopes,不需要额外权限),把返回的应用身份权限与上表比对:grant_status 为 1 的算已开通,其他状态算已申请但未审核或未发布,用户身份的同名授权不算。全部开通时显示“所需的 N 项均已开通”;有缺少时逐项列出权限和用途,标出已申请待审核的项,并给出两种补齐方式:在飞书「权限管理 → 批量导入/导出」导入完整权限 JSON(已开通的不受影响),或打开飞书权限页 https://open.feishu.cn/app/<App ID>/auth?q=<缺少的权限>,一次申请缺少的全部权限。补齐后仍须创建并发布新版本、通过必要审核,再回到连接列表刷新。向导「应用凭据」和「发布与检查」两步的检查也显示同样结果。查询失败时只提示暂时无法自动检查,不影响凭据和机器人检查的结论。
导入权限不会自动订阅卡片操作回调。新应用和已有应用都必须补齐权限、分别配置事件与回调,再创建并发布新版本。卡片实体权限见创建卡片实体,回调结构见卡片回传交互。
连接列表、创建、修改、凭据检查、收发诊断及应用配置回执按上文「应用的归属与可见范围」授权;整个应用的本地会话列表、消息搜索和保留策略仍只对超级管理员开放。群聊助手绑定要求配置人对所选仓库(或整个组织)有 config.write;全平台应用的群可以包含不同 GitHub 组织的仓库。私聊消息和定时通知仍逐次校验操作者或接收者对目标项目的权限及来源;项目组织由目标项目决定。个人页面只读取自己的绑定和自己可见的已启用应用的公开标识(全平台应用对未获项目授权的人也可见、可绑定),不返回应用凭据或安装策略。凭据写入独立密封记录,后台不回显密钥。绑定和结果链接需要稳定的后台地址:使用统一入口,即接入向导验证的公网地址,未验证时使用部署的 BOT_PUBLIC_ORIGIN(旧名 BOT_ADMIN_ORIGIN);两者都没有时,使用保存 GitHub 登录配置时的控制台地址。
安装 tenant_key 必须是机器人实际安装的企业,用来匹配事件头,不限制消息发送者或卡片点击者所属企业。企业自建应用首次保存时自动调用获取企业信息,读取 data.tenant.tenant_key。该接口需要应用身份权限 tenant:tenant:readonly,必须先在飞书开通此权限并发布包含该权限的版本、通过必要审核,再保存连接;仅导入权限但尚未发布仍可能失败。后续编辑沿用已保存的安装企业;应用类型改变时重新读取,读到的安装企业必须与已保存的一致。商店应用从应用启用事件或登录授权信息取得对应企业的 tenant_key 后填写。企业名称、display_id、App ID 和 tenant_access_token 不能代替它。旧 API 客户端仍可显式提供安装 tenant_key;已废弃的 actor_tenants 输入兼容接收但不生效,连接读取结果不再包含该字段。
bot 不设操作者企业白名单。飞书侧的应用可用范围、对外共享能力及安装状态决定用户能否接触机器人;收到可信事件后,私聊仍要求个人双端身份绑定和目标项目授权,群聊由控制台为该群设置的群聊助手绑定决定可用范围。操作者 tenant_key 继续作为外部身份和会话校验的一部分:不同企业的相同 open_id 不共享绑定或会话,也不能互用卡片。
GET /api/channels/setup 返回管理员可见连接及当前入口地址;POST /api/channels/feishu/probe 用自建应用的 {app_id,app_secret} 临时检查,或用 {connector_id,expected_revision} 检查已保存连接。请求仅访问固定的飞书 API,不保存临时凭据、不修改个人身份和授权、不发送测试消息。成功返回机器人名称、open_id、state:verified 和 event_delivery_verified:false;已保存连接还返回 revision、tenant_name,企业名称查询失败时另含 tenant_error 并保留缓存名称,机器人身份变化时自动更新并递增连接版本。两种检查都附带权限检查结果 scopes: {required, missing, pending}(missing 含尚未开通的全部所需权限,pending 是其中已申请、待审核或发布的部分);授权状态读取失败时改为返回 scope_error: "channel_scope_check_unavailable",请求本身仍然成功。版本变化、鉴权失败和商店应用票据缺失分别返回稳定错误码;保存时获取安装企业失败返回 channel_tenant_unavailable,提示开通 tenant:tenant:readonly 并发布生效后重试,不保存部分连接或凭据。平台原始错误和访问令牌不返回客户端。
SaaS / 商店应用使用 HTTP 回调 /hooks/feishu/:connector_id;企业自建可选择官方 SDK 长连接。HTTP 原始请求体按飞书规则验签,校验五分钟时间窗、Verification Token、App ID 和安装 tenant_key,支持 Encrypt Key 的 AES-256-CBC 解密。长连接由服务端持有应用凭据认证,两种方式复用同一持久收件队列、来源检查和去重。
同一商店 App 可登记多个安装租户,使用其中一个连接的回调 URL;验签后按安装 tenant_key 路由到明确登记且独立信任该签名的连接。v1 app_ticket 事件在确认前加密持久化,并按事件时间防止旧票据覆盖新票据;发送走 app_access_token、安装租户 tenant_access_token 的商店应用流程。尚未收到有效票据时返回 channel_app_ticket_required,不尝试用自建应用端点代替。安装租户停用后,同一 App 的其他已登记租户仍可通过该 URL 收件。
订阅 im.message.receive_v1、im.message.recalled_v1、im.chat.member.bot.added_v1、im.chat.member.bot.deleted_v1、im.chat.disbanded_v1、card.action.trigger、v1 应用票据/卸载/状态变更和群成员增删事件。新增全量群消息及历史读取权限后必须由应用管理员审核、重新发布,不能只修改本地向导。应用生命周期变化先停用受影响连接,需管理员复核后显式重新启用。添加机器人或管理群不授予项目权限。自定义群 webhook 不提供管理入口。
连接配置写入要求 expected_revision(创建为 0),冲突返回 channel_revision_conflict。保存返回持久化 operation_id 与 state:succeeded,可通过 /api/channels/operations/:id 回读。连接健康显示启用状态、长连接状态、最近收件时间、稳定错误码、待处理量和发送失败量。停用连接立即阻断新消息、模型后续调用和发送队列;接收到卸载事件时先持久停用,再确认事件。
控制台的「飞书会话」(/#/conversations)按整个会话判断读取权限:普通用户可查看自己的有效绑定私聊和有权管理或读取的群会话;超级管理员可查看全部群聊和私聊,包括连接停用、群归档以及他人的私聊。会话列表先按权限过滤再分页;有权进入会话时,原始本地消息、历史回答、阶段消息、执行步骤和会话独立任务结论整体可读,不按每条消息或回合的来源、授权版本逐条隐藏。权限收回后整个会话拒绝读取,不返回部分可见内容。绑定范围改变或私聊管理会话轮换不会抹去控制台历史;私聊按本地消息、收件记录和专属管理会话的关联汇总历次会话,不混入别人的管理会话。超级管理员查看他人私聊只提供读取,不能由此冒用该用户继续管理助手或刷新其个人绑定。
消息、执行回合、步骤和派生项目任务分别分页。已记录的模型/工具步骤仅展示名称及结果状态,工具参数、工具结果和推理内容不返回;未记录的旧步骤无法补回。阶段消息、回答和实际飞书送达状态分别保留,群维护人可停止正在执行的群回答。撤回、敏感内容掩码和显式清理仍生效;关联项目任务的详情沿用项目资源授权。此处的历史读取不扩大助手工具、执行、恢复上下文或后续发送权限,它们仍按当前授权和来源检查。
「个人设置 → 飞书绑定」在同一页以清晰列表同时展示个人绑定与群绑定:顶栏提供「创建个人绑定」「创建群绑定」「刷新飞书绑定状态」「查看全部飞书会话」按钮,并汇总当前有效身份、本人私聊数与维护的群数量;点击已建立会话的个人或群绑定条目(或「查看聊天记录」)直接进入「飞书会话」(#/conversations/<chat_id>)查看聊天记录与本地消息检索。私聊按连接、身份和租户精确对应,解除绑定后的会话计入历史;停用的群单独标注,群绑定读取失败不阻止本人绑定;平台连接、服务角色等配置仍在「全局设置」(超级管理员可通过页面上的快捷入口直达)。
双端绑定
个人绑定列表默认展示已读取的飞书姓名、机器人名称和机器人所属企业,不以 open_id、App ID 或租户 key 作为用户称呼。飞书姓名尚不可读取时,明确显示“<平台用户名> 的飞书账号”和“关联平台账户”,不将平台用户名当作已核验的飞书姓名;待确认及已解绑记录也使用可读文案。机器人所属企业是应用安装企业,不代表操作者所属企业。
绑定页先展示本地缓存和可读替代信息,再异步读取缺失姓名;普通读取绑定列表不请求飞书。当前账户可通过 POST /api/channels/bindings/:id/name 刷新本人的有效绑定姓名。查询使用当前启用连接,仅针对该安装企业内已绑定的用户,复核返回 open_id 和请求对象一致,并在异步请求后重新检查会话、绑定和连接版本。姓名只更新 display_name,不改变身份键、验证时间、状态或授权;不返回或保存用户信息接口中的邮箱、电话等其他字段。机器人缺少用户信息读取权限、通讯录可见范围不足或姓名不可用时,仍可使用原绑定和已有姓名。
用户信息来源为获取单个用户信息。对外共享机器人不能通过外部用户 ID 查询其通讯录信息,因此外部账号显示关联的平台账户作为替代;此功能不会自动扩大飞书权限或访问其他企业的通讯录。
个人绑定页向超级管理员显示全局设置的应用管理入口,向能新增或管理组织应用的人显示“连接或管理本组织的飞书应用”。用户能看到自己可见的已启用应用(见「应用的归属与可见范围」)的企业名称、机器人名称和所属组织,并通过“打开机器人私聊”链接进入飞书会话;链接使用飞书 AppLink https://applink.feishu.cn/client/bot/open?appId=<App ID>,仍由飞书检查应用可用范围。组织的应用会注明经它绑定的身份只在该组织内生效。控制台签发的绑定串、私聊认证字符串和绑定链接都只能通过自己可见的应用完成绑定,否则返回 403 channel_application_forbidden;签发时和私聊兑换时各检查一次。没有可见的已启用连接时提示联系超级管理员或本组织的管理员,不展示可提交的绑定表单。
#/identity/feishu 是统一的飞书绑定页:上半部分为个人飞书绑定列表与「创建个人绑定」向导(未绑定时默认展开,已绑定时默认收起以突出绑定列表,点击「创建个人绑定」或「重新绑定」可随时展开;旧私聊认证字符串保留在默认折叠的兼容入口),下半部分为飞书群绑定列表与「创建群绑定 / 配置仓库与权限」编辑器(每个群条目直接展示仓库或组织范围、可达仓库、权限档位与负责人,点击条目即可进入 #/conversations/<chat_id> 查看聊天记录)。旧 #/identity/feishu/groups 自动跳转至 #/identity/feishu?section=groups,旧 #/identity/feishu/conversations 自动跳转至 #/conversations,均沿用原服务端权限;群管理读取失败不阻止本人绑定。原 #/identity 的身份、授权和绑定概览入口继续可用。
默认由控制台签发一次性绑定串,私聊里一条消息即完成:
- 登录控制台,在「个人设置 → 飞书绑定」选择机器人并点“生成绑定串”(已有绑定时先点“创建个人绑定”展开向导)。页面调用受会话和 CSRF 保护的
POST /api/channels/bindings/issue({connector_id}),成功返回 201{request_id, code, expires_at};连接不存在或已停用返回 404channel_connector_not_found,看不到的组织应用返回 403channel_application_forbidden,未登录或跨站请求被拒绝。 - 页面显示一条
绑定 FSB-…消息,通过GET /api/channels/bindings/requests/<request_id>只读查证这一次请求。只有该请求对应的身份已由服务端提交,才刷新并显示“已绑定”:重新激活旧身份无需增加记录,另一个机器人的绑定成功也不会完成本次请求。未完成、正在核验、过期、被替换、会话/应用失效和已解绑分别呈现;过期或失效后移除旧字符串与复制按钮,读取失败不假报成功。绑定串不进入 URL,请求编号本身不能授权操作;只有仍可见所选组织应用的发起账户的有效登录会话可读其状态,不返回字符串、会话凭据或来源密文。 - 在飞书中打开与该机器人的私聊,把那条消息原样发送一次。服务端核对连接、私聊、安装与操作者租户后一次完成关联并回执“双端身份绑定成功”。绑定串五分钟内有效、仅可使用一次;串不授予项目权限,是私聊持有证明,请勿转发。凭证索引保存摘要,来源记录按既有机制密封保存,普通日志与查询不返回绑定串。
同一账户对同一机器人再生成一条时,此前未使用的那条立即作废,再用返回 binding_superseded。新请求记录签发时的连接配置版本,停用再启用或修改配置也不会让旧串恢复可用。私聊消费在第一次异步核验前原子领取请求并固定发送者,两个发送者不能互相覆盖证明;核验期间重新生成会阻止旧请求提交。身份事务已提交而渠道回执尚未写完时,状态读取可从该请求自己的绑定证明查证结果,不重复消费或新建身份。已完成请求即使在凭证有效期后回读,也按实际身份状态显示;解除绑定后不能沿用旧成功结果。
兼容路径:在私聊发送不带串的 绑定 或 /bind 仍返回一条 FSB- 开头的认证字符串,可按第 3 步发送,或用受会话和 CSRF 保护的 POST /api/channels/bindings/confirm 接收 {code,connector_id}、只从可信私聊记录恢复来源并重新检查连接与会话后完成关联;超时、重复使用、选择其他应用、来源停用、会话撤销或身份属于其他账户均拒绝。这条旧路径保留但不再是默认。
已有绑定链接流程继续可用,其 challenge 与认证字符串分别随机生成。转发旧链接不能代替私聊认证字符串;链接已进入平台认领流程后,仍须回原私聊完成确认:
- 在飞书私聊发送
绑定或/bind。机器人创建五分钟、一次性的 challenge,并将链接发回发起私聊。 - 打开链接,使用本地账户或已配置的 GitHub 登录进入平台;已有会话可直接使用。飞书不要求先关联 GitHub,也不依赖 GitHub OAuth 配置。使用当前平台会话时,通过受 CSRF 保护的
POST /api/channels/bindings/claim明确确认绑定目标;绑定链接的 GET 请求只导航,不认领账户。主动选择 GitHub 登录时,使用既有浏览器绑定、S256 PKCE 和单次消费契约,回调为已验证的平台账户生成待确认信息;升级前已发起的 GitHub 回调继续兼容。两种方式都尚未完成飞书绑定,仍须在下一步核对平台账户并回原私聊确认。 - 后台「个人设置 → 飞书绑定」展示平台账户、飞书 App、安装/操作者租户及 open_id。核对后,复制页面显示的
确认绑定 <一次性值>发回原飞书私聊。 - 服务端验证同一应用、安装租户、操作者租户、open_id、私聊和线程,再通过身份模块的
ExternalBindings完成持久关联。
只打开链接、只登录平台、转发链接、错误飞书操作者、超时和重复确认均不能完成绑定。已有映射属于其他 principal 时返回 external_identity_conflict;撤销的映射仍归原 principal,不能通过重新绑定接管。绑定不写入 scoped_grants;没有仓库权限的平台账户也可以关联飞书,但项目查询、卡片和写操作仍按该账户实际有效的授权拒绝。本地账户的显式项目委派与 GitHub 登录后的有效派生授权使用同一套权限检查,登录方式本身不增加权限。
身份 / /identity 查询当前关联状态;解绑 / /unbind 撤销原身份服务中的映射;重新认证 / /reauth 重新走双端证明。个人绑定页面提供步骤说明、待确认身份与指令、刷新状态和解除飞书绑定;撤销后提示重新认证。验证失败使用明确错误码,不打印凭据、OAuth code、challenge 或个人聊天正文到日志和审计。
管理会话与结果
飞书会话、飞书绑定(个人绑定列表与群绑定列表)和绑定概览优先显示姓名或群名,并标明机器人及其安装企业;组织应用另显示应用所属平台组织。安装企业不代表私聊操作者或跨企业群成员所属企业。会话 ID 放在可展开的标识详情中,群选择器保留 ID 以区分同名群;会话搜索支持姓名、群名、企业、应用所属组织、机器人和会话 ID。
页面先展示本地名称,再异步补全缺失名称;群名通过 POST /api/channels/chats/:id/name 从飞书获取群信息读取,使用已有 im:chat:read 权限。仅有权查看该群或在飞书绑定页中选择该群的人可刷新,异步调用后重新检查授权、群状态及连接版本。私信姓名只取本人在当前连接下的有效绑定,可用原有刷新姓名接口更新。名称只用于展示,不改变会话、配置或权限版本;读取失败保留旧名称和原有功能,可手动刷新。权限不足时管理员应导入完整权限 JSON、发布生效,并核对通讯录可见范围。外部企业用户暂不可通过本安装企业的通讯录令牌读取姓名时,明确提示姓名暂未获取。
姓名读取使用获取单个用户信息:contact:contact.base:readonly 授权调用资料接口,contact:user.base:readonly 授权返回姓名字段,只有字段权限不足以调用接口。飞书返回权限错误 99991672 时,本地接口返回 HTTP 403 channel_user_name_permission_required,页面引导管理员在飞书连接导入完整权限并发布;其他暂时性读取失败仍保留已缓存姓名。
私聊和群聊都不需要先选项目,也没有命令写法(#312)。/project …(含 /query、/command、/link、/destination)和 /chat 前缀都不再触发特殊流程,原样作为自然语言交给助手:私聊交给管理助手,按本人当前权限查询和管理;已绑定的群交给群聊助手;未绑定的群在被 @ 时只回复如何绑定,不执行任何管理请求。只有绑定相关的 绑定、确认绑定、解绑、身份、重新认证 及其英文写法仍是固定指令。管理助手的查询和命令走原管理模型与相同工具,不在飞书 handler 内实现 SQL、Manager 配置或 GitHub 写入。
私聊会话由连接、安装租户、操作者租户、操作者、chat 和 principal 共同隔离。Web 可直接读取相同 conversation_id、管理消息、命令 operation_id、修改前后版本、状态、差异和审计。
queued 表示只落入渠道队列;submitted 表示管理消息已受理。管理消息 completed 表示模型/工具回合结束,业务命令必须另看回执的 succeeded、failed 或 unknown。IM 发送成功只表示送达卡片,不能证明管理/GitHub 操作成功。命令没有审批步骤,授权范围内直接执行;Web 对账恢复 IM 命令时也重新验证持久渠道来源、绑定和连接:私聊命令核对本人的飞书绑定,群聊命令核对群绑定、来源消息、绑定的权限项和授权者权限。
管理助手在私聊里建的任务(task.create)会把结果发回这个私聊(#844):创建时在 channel_personal_tasks 记下私聊、本人和发起的那条消息;任务完成、提交 PR、失败或取消时,结果卡片经同一个结果队列发到原私聊,写明仓库、任务、状态、摘要、PR 链接和失败原因。入队和每次发送前都复核本人在这个私聊仍有有效的飞书绑定、仍能读这个仓库(tasks.read);不满足就不发,任务历史的 channel_result_delivery 写明原因,例如「结果未投递:创建者的飞书绑定已解除或失效」「结果未投递:创建者已没有该仓库的读取权限」。私聊只是结果的去处,不是任务的权限来源:任务的来源仍和控制台建的一样(source_kind 为 operator,没有会话),执行时照旧只核对本人的任务权限,解绑飞书不会中止任务。在控制台管理助手里建的任务和私聊定时任务运行时建的任务没有发起消息,不发到飞书私聊;群里派的任务照旧发回原群。
结果卡片只带“登录后台查看”链接,不携带回调操作;较早版本卡片上的“刷新执行状态”按钮点击后按过期处理(channel_card_stale),不会触发任何写入。
群聊
群消息的提及文字会按飞书提供的映射保留为 @机器人名 或 @成员名,文本、富文本及新同步的历史使用相同处理。本地记录和模型请求都保留可读提及,以及目标 open_id、名称和是否指向当前机器人的结构化信息;不会把单独 @ 机器人的正文清空。是否真正提及机器人由飞书提及对象的 open_id 判断,普通文字 @名字 或同名成员不会据此获得触发资格。绑定命令另外使用去掉自身提及的正文解析,不影响原有私信绑定规则。
群助手上下文中的 bot_identity 提供当前机器人的 open_id 及群内名字,优先采用本条已核验提及中的名称,其次采用本群最近的提及名称和连接的应用名称;它与服务角色名称分别保存。current_message.is_direct_mention 表示本条消息是否直接呼叫机器人。单独 @ 是一次呼叫,助手应结合最近讨论回答明确相关的未答问题,无法判断时简短询问,而不是因为没有额外文字就断言没有问题。名称和消息都只是数据,不扩大授权,也不要求执行无关、引用或过时的请求。撤回、敏感消息和本地清理不展示提及元数据。
群聊助手绑定
群聊由服务角色回答,服务角色只提供提示词和模型(定义、模型与计费见服务角色):超级管理员维护的全局模板,或项目管理员为本项目建的项目群助手角色(只能用于范围只有这个项目的群)。群只能用对范围内每个项目都可用的模型,规则见群助手的模型。「个人设置 → 飞书绑定」为一个群保存一条绑定:一份项目范围(整个组织,或多选仓库)、本群的权限档位、一个服务角色和发言范围(仅回应 @/回应 @ 及以问号结尾的文字/读取每条新文字后判断是否发言),以及负责人、最近修改人和 revision。列表中每个可管理群条目均提供「配置仓库与权限」(已停用时为「重新启用并配置」)按钮,并直接展示本群的档位;超级管理员可从本节顶部的「管理助手角色」直达「全局设置 → 服务角色」。一个群只绑定一个角色,不切换;默认推荐内置的「仓库问答助手」。管理助手的权限继承当前用户,不能绑定到群。
权限档位决定群里的人能让助手做什么(#849),每档包含前一档:
| 档位 | level |
权限项 |
|---|---|---|
| 只读问答 | read |
GitHub 各资源只读、本群会话记录;不写 GitHub,不建任务 |
| 可评论和打标签 | comment |
另有 Issue 和 Pull Request 读写:用 github_write 评论、加删标签、指派人、新建 Issue;Pull Request 读写同时允许开 PR、发检视(包括批准和要求修改)、请求检视人和更新 PR 分支。不含 Contents 写,所以不能提交文件或合并。群内任何成员还可以让助手管理本群的定时任务(conversation_schedules,#851),见「会话定时任务」 |
| 可派活 | dispatch |
另有 delegation: allow 和 project_tasks: write:经 Manager 新建任务,查看、追加说明、修改约定、暂停、重试和取消范围内的任务 |
高级模式(custom)逐项设置统一权限目录(见 共用角色权限)里的每一项,例如打开虚拟电脑、项目知识或 Contents 读写。Contents 写(提交文件、推送分支、在群里合并 PR)只在高级模式里出现,三个档位都不含。逐项设置正好等于某一档时,绑定显示为那一档。保存时只能给档位或逐项设置之一;都不给时保持原档位,新绑定从只读问答开始。项目管理员(对范围有 config.write)自己就能为本项目的群选择任意档位,不需要超级管理员,同一项目的不同群可以各自不同。
第一个为群配置助手的人成为负责人(owner_id,先到先得),单独保存;configured_by 只表示最近修改人。首次配置的人必须已绑定飞书(经该群所在的应用)、当前在该群中(保存时用应用身份完整分页核验群成员;应用没有读取群成员的权限时,飞书返回 99991672,保存返回 403 channel_audience_permission_required,页面提示超级管理员到「全局设置 → 飞书连接」查看缺少的权限,开通 im:chat.members:read 并发布新版本),并对所选的每个仓库有 config.write;选整个组织时需要组织级 config.write。范围写入这条绑定专用 service principal 的 scoped_grants(每个仓库一条,或组织一条),授权者记为本次保存的人;这个 principal 只持有档位用到的能力(read、comment 为 tasks.read,dispatch 另有 tasks.write;高级模式打开项目知识、项目设置或定时计划时才有相应能力)。
已有绑定(包括已停用的)只能由三类人修改、重新启用或停用,其他人返回 403 channel_service_binding_forbidden:
- 负责人:仍须经该应用绑定飞书并在群中;
- 范围涉及的每个组织的组织管理员(组织级
config.write); - 超级管理员。
其他仓库的管理员即使在群里也不能修改,同一仓库的其他管理员也不能。组织管理员和超级管理员修改时不要求在群里,修改后负责人不变。修改时整份范围按本次保存的人重写,所选的每个仓库(或组织)都要求保存人有 config.write,负责人也不能把群扩到自己管不了的仓库。
组织管理员和超级管理员可以用 PUT /api/channels/chats/:id/service-binding/owner(owner_id、expected_revision)把负责人转交给对当前全部范围有 config.write 的启用账户,否则返回 channel_service_owner_ineligible;转交不改变群能做的事,因此不增加 revision,写审计 channel.service_binding.transferred。列表接口为可转交的绑定返回 can_transfer 和候选人 owner_candidates。#424 之前的绑定以 configured_by 回填负责人。
保存要求 expected_revision,冲突返回 channel_revision_conflict,每次修改写审计 channel.service_binding.*。页面提示:群内所有成员都能看到助手读取的所选仓库内容(包括私有仓库),由负责人控制范围;保存后群里的每个人(包括没有平台账号的人和其他企业的外部成员)都按这一档使用助手,不核对发言人。
群内有效权限 = 绑定的档位 ∩ 绑定范围 ∩ 授权者当前仍有效的授权(该仓库的 config.write 及工具所需能力)∩ 各项目的能力上限(comment 才能写 Issues 和 PR,develop 才能写 Contents 和建开发任务,见项目能力上限)∩ GitHub App 安装权限(写令牌按资源签发,安装没有的权限 GitHub 不会签发,写入在发出前拒绝)。服务角色的权限项不再作用于群。授权者失去某个仓库的权限时只暂停这个仓库;全部仓库都不可达时绑定显示暂停,群里 @ 助手会收到一条写明授权人和处理办法的说明(见何时核验 GitHub 权限)。授权人不需要为此保持控制台登录:后台刷新和群回合会续期他的 GitHub 派生授权。不校验群内发言人的绑定、权限或成员快照,未绑定的普通成员和外部成员也按绑定的档位使用助手;来源真实性仍由飞书事件签名、连接版本和本地消息账本校验。服务角色被停用时群内说明原因,不改用其他角色;仍有启用中绑定的服务角色不能删除(service_role_in_use)。
升级时(#849)每条已有绑定一次性得到它当时所用服务角色的权限项,原样复制,不扩大:仓库问答助手的群成为只读问答;自定义角色的群按其权限项显示为对应档位,对不上任何一档的显示为高级,其中旧派活附带的任务控制等过渡值保留原有操作,直到维护人改选。绑定的 revision 和授权围栏不变,进行中的回答和已有摘要不受影响;审计记 channel.service_binding.level_migrated。原来的服务角色继续作为提示词和模型使用。
群聊助手获得的工具都在服务端按绑定范围校验,一次请求可以跨多个仓库,不需要先选项目:
list_projects:当前可用的仓库全名和 GitHub 链接,不返回内部 ID;list_chat_members:本群成员的 open_id、已知姓名和是否外部成员,可按姓名或 open_id 过滤,不受权限项控制,见「回合中收到新消息」;- 当前会话(默认可用):本群本地记录的检索、摘要和分段读取(
search_conversation_history/read_conversation_summary/read_conversation_message),不回源飞书; - GitHub 各资源的读取权限:
github_read、github_search、read_job_log,复用任务的仓库只读工具并增加repository参数;范围外的仓库直接拒绝且不发出请求。每次回答按仓库换取只读安装令牌,回答结束即撤销;令牌不进入模型或日志; - GitHub 资源的读写权限(
comment及以上,或高级模式):github_write,同样带repository参数(#381)。只写绑定范围内、且配置绑定的人当前仍能写任务(tasks.write)的仓库,每次调用前后都重新核对;只读时不提供这个工具,模型硬调也被拒绝。key 在本轮回答内去重,写入以服务角色和本群会话记审计,细节见共享 Agent 后端; project_tasks: read:list_project_tasks、read_project_task;write另有manage_project_task(暂停、取消、重试、追加指令),经ManagementService的版本检查、幂等和审计,回执与控制台一致。命令以绑定的 principal 提交,执行和对账恢复时都重新核对绑定、来源消息、绑定的档位和授权者权限;delegation: allow(派活,dispatch档):create_project_task在范围内的仓库新建任务,参数为需求和交付约定(目标、范围、验收条件、终点)。其他角色的任务访问和修改由project_tasks控制;升级前旧派活配置附带的任务控制保留为待迁移的原操作集合。见下文「派活」;- 独立任务:
start_own_task、continue_own_task、list_own_tasks,不受权限项控制,见服务角色; - 阶段消息:
send_message,每轮最多 10 条,每并入一条新消息再多 1 条,不受权限项控制,见下文「阶段消息与停止回答」。
派活
群只能经项目的 Manager 间接派活:新建的任务与控制台创建的任务相同,交给项目团队、由 Manager 规划和分派,用目标项目自己的模型和设置执行;不能指定执行角色,也不能直接操作某个角色的运行。群里提交的任务命令按操作检查绑定的权限项(dispatch 档包含下表全部):
| 操作 | 需要 |
|---|---|
新建任务 task.create |
delegation: allow |
修改其他任务的约定 task.contract |
project_tasks: write(旧派活附带控制保留为待迁移) |
追加说明 task.instructions、取消 task.cancel |
project_tasks: write(旧派活附带控制保留为待迁移) |
暂停 task.pause、重试 task.retry |
project_tasks: write |
新建任务经 ManagementService.submit('task.create') 以绑定的 principal 提交:服务端读取当前项目版本作为 expected_revision,幂等键由群、来源消息和工具调用生成;授权者对该仓库须仍有 config.write 和 tasks.write;审计和回执与控制台一致。任务创建时记入 channel_service_tasks,关联到这条绑定和来源消息。任务完成、提交 PR、取消或失败时,结果发回原群;入队和发送前复核绑定仍启用、授权者仍能读该仓库以及任务的来源权限。结果消息记在本绑定的范围内,并带上当时的群围栏,之后的回答可以引用它;绑定或权限变化后不再进入上下文。
任务执行期间,任务引擎每次复核来源时也检查这条绑定:绑定仍是该群当前且启用的绑定、绑定的档位仍是 delegation: allow、授权者对该仓库仍有 config.write 和 tasks.write;任一不满足就停止后续步骤(channel_service_delegation_revoked 或 channel_service_scope_paused)。群里建的任务还以绑定的权限项为来源上限:例如任务里的 github_write 要求绑定对相应资源也有写权限。
群里没有审批或人工确认:群助手在绑定的档位、绑定范围和授权者权限之内的操作直接执行,与控制台和私聊一致,见统一管理服务与管理助手。
旧群员工的迁移
升级时,每个有已启用旧群员工的群自动转为一条「仓库问答助手」绑定:范围是原来启用的项目,各项目的授权者沿用原维护人,发言范围在各项目一致时沿用、否则改为仅回应 @。迁移只执行一次(设置项 channel_service_bindings_migrated)。旧群员工不再接收新消息,旧接口 PUT /api/channels/chats/:id/employee 只能停用(启用返回 channel_employee_retired);它们已创建的任务继续按原授权、成员核验和来源守卫执行并向原群通知结果,直到维护人在页面「旧群员工」中停用。只有仍有未结束任务的旧授权才会继续定时核验群成员。
维护绑定的人(负责人、范围所属组织的组织管理员、超级管理员,或对全部范围有配置权限者)可以查看连续会话、查询和分页搜索本地群记录、显式安排重新同步;这些读取只使用本地账本,不以历史或成员 API 回源。私信和其他群不因此开放。超级管理员继续管理全部本地诊断和保留策略。
群使用 provider + app_id + installation_tenant + chat_id 对应的稳定本地会话,换成员、thread、日期不另起会话。个人私聊使用绑定账户的共享 ManagementAgent,与控制台共用管理工具、有效权限、幂等、版本检查和审计。个人管理历史与群聊历史分别保存,个人授权不会扩展群聊助手的能力。
绑定后可以直接发送“你好”“我能管理哪些项目”“看看 bot 项目的任务”或“暂停刚才那个任务”。问候、帮助和跨项目查询不要求先选项目;助手通过真实项目查询发现名称,使用仓库全名和可读链接回答,同名或多候选写入先自然追问,用户可继续选择和切换项目。模型、预算和用量属于服务角色「管理助手」,与请求实际操作的项目分别处理,不会默认选中业务目标或授予权限。没有可访问项目时明确说明授权不足;缺少可用模型时提示检查配置,不虚报完成。
同一绑定账户在同一私聊跨项目与 thread 延续管理问答,历史按当前授权重建;历史消息编辑或撤回后沿用原 conversation_id,按账本当前正文重建派生上下文并通知助手;当前轮来源失效只停止该轮,显式历史清理仍作废旧上下文,发送前重新校验身份、来源及授权。解绑、换绑或撤权不恢复旧范围。以前 /project 指令留下的命令回执仍可在控制台按原会话追溯。个人绑定页展示共享管理问答与真实执行状态;失败和执行结果待确认均区别于已执行,未知结果先对账。
默认仅回应 @;负责人可让助手回应以问号结尾的文字,或读取每条新文字并由助手决定是否保持安静。系统提示词按当前设置告诉助手自己的工作模式:仅回应 @ 时,没 @ 的消息是群成员之间的交谈,除非明确是在接着当前请求补充、纠正或取消;问题和全部模式下,大多数消息并不是对助手说的,只在确实有帮助时回答,否则保持安静。所有合法可见消息仍独立落库,机器人消息、历史同步和超过实时窗口的旧消息不会触发模型工作。扩大发言范围会增加服务角色的用量,仍受服务角色预算限制。
群聊助手的主上下文使用最近 40 条本地消息、每批最多 100 条的滚动摘要与本地检索。摘要和最近 40 条之间的消息攒满 20 条才折叠进摘要,之前原样放进上下文。摘要只是辅助:摘要请求失败或模型没有返回文本时,保留旧摘要继续回答,上下文注明有多少条较早的消息尚未汇总、可用 search_conversation_history 检索,下一轮再折叠;停止、当前轮来源失效或授权变化仍会结束本轮。一次回答可以在同一步里对多个仓库各发一个工具调用,数量不设上限;同一批工具结果共享预算,请求变大时先省略较早的工具结果,规则见 Agent 运行时。上下文与搜索使用明确标记的文本摘录;read_conversation_message 可分段读取完整本地原文/资源引用,附件不会因此下载。摘要记录来源范围、水位、截断清单和授权围栏;历史消息编辑或撤回会清除旧摘要,助手收到变更通知后继续本轮,后续输入不再包含旧正文或可能引用旧正文的派生回答;当前问题被撤回或修改只停止该轮。成员进出和历史补读不改变授权围栏。显式清理历史、绑定(包括档位)或角色变化以及授权者真实失权仍会使旧上下文失效并停止本轮。助手的回复以 binding:<绑定 id> 范围记入本地账本,其他绑定或项目范围的机器人消息不会进入本群上下文。每轮回答记一条 channel_service_turns,请求/响应快照密封保存,用量在 model_requests 中按服务角色记录一次;范围只有一个仓库的群同时记在这个项目上(repository_id),其他群的 repository_id 为空。
旧群员工的任务结果按 task 与结果版本进入原渠道 outbox;游标与入队事务提交,发送前复核来源消息、当前授权与执行权限版本。任务执行仍只有原调度器。任务自身的源消息撤回、变更或清理后停止该任务的后续操作与披露,其他历史消息变更不作废整个会话;已经发出的群消息不能承诺全部收回。「查看连续会话」展示群聊助手当前获准的回答、覆盖与未知费用。任务审计事实仍保留在原受控任务页面,不被聊天记录清理静默删除。
官方协议见获取群成员列表、判断用户或机器人是否在群里。后者判断当前 access token 对应的主体,不能用 bot token 直接证明任意维护人还在群里。
回合中收到新消息
同一群聊或同一私聊管理会话的助手仍在思考或执行工具时,新鲜的用户消息会登记为 merged,关联当前回合,保存在 channel_turn_inputs。只有本回合自然进入下一次模型请求时,才把新消息按到达顺序追加到已有对话后;收到消息不会打断思考、工具执行或输出,也不会因此强行增加模型请求。处理中表情只回应明确的呼叫:私聊消息和群里 @ 助手的消息(任何工作模式)会加上,表示已收到,回合最终回答送达(或回合安静结束)时与原消息的表情一起清理;群里没 @ 的消息照样并入、交给助手判断,但不加表情,回应问题或全部消息的群也是如此,避免打扰群里的交谈。绑定指令仍由原渠道流程处理。
模型开始输出回复文本时暂停并入,新消息留在待处理队列。若输出随后实际返回工具调用,工具阶段恢复接收,并在自然的下一步模型请求前一并取入。若返回最终答案,就立即结束并入,期间尚未交给模型的问题交回待处理,不保留草稿来重算,也不为晚到的消息额外请求一轮。模型已经结束、平台仍在清理资源或尚未贴出结果时,同样不再并入;下一回合紧接着处理待回复的问题,参考讨论不另开回合。
并入以助手的执行状态为边界,没有累计接收时长或消息条数上限。每次注入遵守已有的模型上下文大小预算,放不下的消息仍持久保留;待处理消息不会提前混进当前回合的最近消息和滚动摘要。普通消息回合的最终回答回复到最后一条实际交给模型、确定是对助手说的消息下(私聊消息,或群里核验过的 @助手);没有这样的消息时按原消息的方式发送,不会挂到别人之间的对话下。群定时任务仍按定时任务的名称和投递方式发送。消息回合期间到点的定时任务沿用原等待规则。
平台只给事实,是否与助手有关、要不要回答由模型自己判断:新到的消息不一定是对助手说的,群里的人也会彼此交谈。每条并入消息提供 sender_id(发送者 open_id,唯一身份)、已知时的 sender_name、same_sender_as_request(是否与本回合提问人相同,定时任务回合没有这一项),群消息另有:is_direct_mention(仅表示通过当前飞书机器人账号核验的 @;同名用户或字面上的 @文本不算)、mentions(规范化后的目标 actor_id、名称和 is_self)、reply_to_message_id、in_request_thread(是否在本回合提问的话题里),以及 group_setting_invites_reply(这条消息单独到达时,群的参与模式是否会触发回答,仅作参考,不是义务)。可以安静结束的回合(群里没 @ 助手的消息、群定时任务)提供 stay_silent 工具,模型调用它即保持安静,平台不发送任何消息,详见服务角色;模型写出的任何文字都会作为回答发出。原消息或某条并入消息核验 @ 了助手后,stay_silent 返回 reply_required,必须给出非空回答,与这条消息单独到达时的规则一致。私聊中的新消息都来自本人且是对助手说的。参与模式会单独回答、但模型还没看到的消息,在回合结束后交回待处理并另开回合。
发送者姓名尽力解析,只用于展示和称呼,身份始终以 open_id 为准:安装企业内的用户先查通讯录(获取单个用户信息,使用已有的通讯录权限),通讯录没有取到时用群成员列表(获取群成员列表,使用已有的 im:chat.members:read)里的名字;外部企业成员不查通讯录,群成员列表也没有名字时只给 open_id。通讯录姓名缓存 24 小时(失败 1 小时后重试),群成员列表加密缓存 10 分钟,群成员变化、机器人被移出或群解散时标记过期,应用卸载时删除。群聊回合开始前最多等待约 2.5 秒补齐缺失的姓名,超时不影响回答,查询在后台继续写入缓存;并入的消息在收到时就在后台查询发送者姓名。最近消息、历史检索、并入消息和 context.current_message 都带上已知的 sender_name;群聊助手还可以调用 list_chat_members 按姓名或 open_id 查询本群成员(id、已知姓名、是否外部成员),缓存超过 10 分钟时重新读取。控制台回合详情里的并入消息也显示已知姓名。
注入前、后续工具调用前及交付前复核原消息和已注入消息的可见性、撤回、绑定与授权围栏。回合停止、中断或围栏变化后,已并入但未交付的问题交回待处理,由新回合在当前权限下接手;参考讨论不另开回合。已持久写入最终发送队列的回答由原 outbox 继续投递,重启不重复运行。初始请求和已经执行的业务命令仍遵循原中断及回执对账规则。重复 webhook 仍按原消息 ID 去重,已并入的消息不会再开一个回合。
阶段消息与停止回答
私聊的管理助手、群聊助手和会话定时任务在一轮回答中可以用 send_message 发送最多 10 条阶段消息,回合每并入一条新消息再多 1 条(#435、#458,模型侧规则见服务角色)。每条在调用时就写入 channel_outbox,在轮次运行期间发出:私聊和群聊作为普通 Markdown 消息发到原会话(群里在话题中提问时回复到同一话题),定时任务的阶段消息和结果一样以「定时任务「名称」」开头。阶段消息不带附件,附件只随最终回答发送。
写入队列前和每次发送前,阶段消息都要通过与最终回答相同的复核:私聊核对本人的飞书绑定、源消息未撤回或修改、授权修订和会话上下文未变;群聊核对绑定仍是当前版本且可用,轮次围栏未变(明确清理历史、绑定(包括它的档位或权限项)、所选角色或其启用状态、授权者真实失权会改变围栏,修改角色的提示词或模型不会;消息编辑、撤回、成员进出及历史补读不改变围栏,当前轮源消息仍须有效);定时任务另外核对定时任务未删除,私聊的定时任务还核对主人的授权修订未变。最终回答要求轮次已完成,阶段消息在轮次运行中或已完成时都可以发送;轮次被停止、失败或中断后,还没发出的阶段消息不再发送。围栏变化返回 conversation_source_changed,轮次已结束返回 conversation_turn_inactive。
群聊发出的阶段消息与最终回答一样以本绑定的范围记入本地账本,之后的回答可以引用。它们密封保存在 channel_service_turn_messages,「查看连续会话」把它们按顺序显示在该回答之前,有回答在进行时页面每 3 秒刷新一次。私聊和私聊定时任务的阶段消息是管理消息的 message 事件,控制台管理助手、私信连续会话和下一轮的续接历史(每条最多取 1000 字)都能看到。
停止群聊助手的回答:能管理这个群绑定的人,即负责人、范围所属组织的组织管理员和超级管理员(同 #424 的修改权限),可以在「查看连续会话」里对运行中的回答点「停止回答」,接口为 POST /api/channels/chats/:id/service-turns/:turn/stop(空请求体)。只对全部范围有配置权限的其他人可以查看会话,但不能停止(403 channel_service_binding_forbidden)。停止后,已经发出的阶段消息保留,不再发送最终回答和尚未发出的阶段消息,群里收到一条「本次回答已在控制台停止」的说明;轮次记为 stopped(conversation_stopped),审计 channel.service_turn.stopped,重复停止不再改变什么。群定时任务的运行被停止时,这次运行记为失败、不暂停定时任务,也不在群里发说明,与定时任务的其他失败一样。源消息撤回或绑定变化仍按原规则自动停止回答。
去重、恢复和发送队列
事件按连接与 event_id 持久去重,消息再按 message_id 去重。合法消息不因发送者、类型、是否 @ 或原发送时间而丢弃;HTTP 与 SDK 在同一事务提交 inbox、本地账本、资源元数据、同步发现和必要的安全失效,再返回成功,数据库失败返回失败。新鲜的用户文本、post、图片及文件在已绑定私聊或符合群助手发言范围时进入助手;不支持的类型明确提示。bot、未满足发言条件和过期消息安静入库,不重放旧命令。原管理入口仍拒绝逆序业务写入。模型和业务执行由独立 worker 执行,慢模型不阻塞回调。
重启不会重放已提交的管理消息:管理服务标记中断,需要查看原会话/回执;尚未提交的收件继续处理。发送 outbox 独立保存 queued、sending、retry、sent、failed、尝试次数和稳定错误码;每段文本及每个附件另有持久化进度、上传 key、固定 uuid、首次发送时间与远端 message_id。网络失败指数退避,重启只继续未成功的项,已送达文本与附件不重复。飞书发送接口的 uuid 只在一小时内去重:本系统留出五分钟余量,超过 55 分钟仍未知的项终止为 channel_delivery_unknown,须管理员对照原会话与连接诊断逐项核对,不能用新 uuid 自动重发。旧版本已开始发送的卡片保留原内容及原 uuid。连接/身份/范围失效为终止失败。所有发送内容和入站正文密封保存,SDK 原始日志关闭,访问令牌只在服务端调用期间使用。
任务结果通知的恢复
群聊派活、私聊里管理助手建的任务和旧个人角色会话的结果都由持久化结果队列关联发送 outbox,不创建新的执行任务。每条结果独立保存重试次数、下次尝试时间、错误码及 outbox 回执。入队失败、网络故障、服务端 5xx 和限流会退避重试;一条结果重试时后续结果仍可投递。结果游标只跨过已经确认送达或明确停止披露的结果,重启不会丢弃待发结果,也不会重复发送已确认卡片。
权限撤回、来源失效或目的地不可用时仍不披露结果内容。任务历史的 channel_result_delivery 记录任务、会话、连接、失败阶段及错误码;task_result_authority_changed 明确显示“结果未投递:权限已变化”。确认送达时同样记一条(state 为 delivered,「结果已发送到飞书群」或「结果已发送到飞书私聊」)。发送结果无法确认且已超过平台去重窗口时,保留 channel_delivery_unknown 诊断并停止自动重试,避免重复发送。
Markdown、图片与文件
普通回复使用原生 post 的 md 段落,保留标题、段落、粗体、斜体、删除线、行内与围栏代码、嵌套/有序/任务列表、引用、链接、表格和分隔线。带操作回调的旧卡片仍走交互卡片接口。依据消息内容结构,CommonMark/GFM 的 Setext 标题转换为 ATX 标题,缩进代码转围栏;原始 HTML 显示为文本,模型不能注入原生提及,Mermaid 显示源码并说明不能绘图。邮箱及其他非 HTTP(S) 链接显示文字。Markdown 图片 URL 显示普通链接,绝不由服务端抓取,也不接受模型伪造的飞书 image_key。以 / 开头的应用链接补上当前控制台入口,协议相对链接不采用。
富文本请求按 UTF-8 与双重 JSON 转义后的字节数保守分段,保持低于飞书 30 KB 请求体限制,不截断完整回复;普通块优先保持完整,单个超大代码/表格等块以原文纯文本分段。文本先发,选中的附件按工具选择顺序逐项发送;有话题 ID 时所有项回复原消息并设置 reply_in_thread。入站优先读取 content_v2,兼容原 content,保留 post 的段落、文本样式、链接、提及、代码、分隔线和图片占位。原始长消息留在账本,用 read_message_text 分页读取,私聊模型首段会明确提示内容未完整载入。
独立 image/file、audio/media 的文件资源及 post 内图片(包括 md 中的飞书图片 key)与来源消息一起持久化。list_message_resources 只列出本会话可见消息的资源 ID、来源 message_id、安全文件名、MIME、大小和状态,不暴露远端 key。read_message_resource 首次读取才调用获取消息资源,始终使用已认证消息的 message_id 与 key,不使用只能读取机器人自传图片的图片下载接口,也不接受 URL、宿主路径或另一个会话的资源替换。入站流式读取上限为本系统的 20 MiB,长度头与实际流都检查;空文件、权限缺失、超限和下载失败有稳定错误码。
UTF-8 文本可分页读取;PNG/JPEG/GIF/WebP 可通过 view_message_image 提供真实图片输入给支持图片的模型,每次最多一张、每张最多 512 KiB,以适配现有 2 MiB 模型请求上限。不支持图片输入的模型会明确报提供方错误,不声称看过图片。其他二进制及较大图片通过 import_message_resource 导入本群或本人的助手电脑(/tmp/... 临时处理,~/... 保存到 HOME,见服务角色 · 助手电脑),再由角色允许的电脑工具处理;attach_workspace_file 把电脑里的普通文件选为回复附件。没有电脑权限时明确说明不能解析,不把文件名当作已读内容。
attach_message_resource 选择本会话授权资源,create_reply_file 生成 UTF-8 附件,attach_workspace_file 从当前私有项目工作区快照一个常规文件并选择发送;后者按内容哈希读取固定字节,拒绝宿主路径、路径穿越和符号链接。选择只是待发送,不是送达回执。每次回复最多 20 个附件。图片经上传图片后作为原生 image 消息预览,其余文件经上传文件后作为可下载的 file 消息发送;图片采用本系统保守的 10 MiB 上限、文件 30 MiB,空文件拒绝。大于图片上限或非支持图片格式改用文件;尺寸/编码不被飞书接受时保留明确失败诊断,不承诺平台可预览任意文件。
资源字节加密保存在来源消息的账本中;撤回删除对应资源,延迟历史不能恢复,保留清理级联删除资源并清除衍生发送载荷。下载、复制、模型调用、上传和发送前后都复核连接、身份、来源消息、群绑定/受众和项目权限;失效立即阻断后续步骤。上传 key 仅存在加密发件箱内,工具和模型不接触应用密钥。部分发送失败在控制台显示已送达项数及逐项回执;权限缺失或最终失败会在仍有权回复时通知原会话,已经送达的项不撤销或重发。自动测试使用飞书与模型协议夹具和真实本地 runner;这不代表真实飞书应用或外部图片模型已完成联调。
收到需要处理的新用户文本后,独立 worker 在原消息下添加 Typing 表情,表示请求已收到并正在处理。只有私聊消息和群里 @ 机器人的消息会加,不论群的工作模式;群里没 @ 的消息不加,包括回应问题或全部消息的群里助手会读取的消息,以及并入运行中回合的消息(见「回合中收到新消息」)。模型完成但回复尚在发送或重试时继续保留,卡片实际送达后移除,并入的消息随回合的最终回答一起清理。群助手决定保持安静、处理终止或发送最终失败时也会清理。重复投递不重复添加,历史同步、机器人消息与卡片事件不添加。表情请求不阻塞回调、模型或发送队列;添加和清理状态按收件持久保存,重启或添加响应丢失后用获取消息表情回复查询本应用的 Typing 表情恢复,不删除其他人的表情。该查询使用已有的 im:message:readonly 权限,新增的写入权限须由飞书应用管理员开通并发布。缺权限或平台拒绝时保留 reaction_state / reaction_error 诊断,消息照常处理;网络故障和限流退避重试,平台永久拒绝时无法保证移除。接口依据:添加消息表情回复、删除消息表情回复、表情文案说明。
会话定时任务
每个飞书私聊和已绑定群聊助手的群都可以挂一个或多个定时任务(#330),在「个人设置 → 飞书绑定」对应个人或群绑定条目的「定时任务」抽屉中管理:名称、任务提示词、IANA 时区、五段 Cron 或固定间隔(5 分钟到 31 天),可以预览接下来的触发时间、立即运行一次、暂停或恢复、编辑和删除,并查看最近一次运行的状态与原因。私聊的定时任务只能由这个私聊的绑定主人管理;群的定时任务由能维护该群聊助手绑定的人管理(负责人、范围所属组织的组织管理员、超级管理员或对全部范围有配置权限者)。平台管理员还可以查看并停用私聊的定时任务。
也可以直接在会话里让助手管理(#851):管理助手和群聊助手有工具 conversation_schedules,对本会话的定时任务列出、新建、修改、暂停、恢复和删除,与控制台用同一套校验,只能操作它正在回答的这个会话。私聊里由本人管理自己的定时任务;群里在绑定档位为「可评论和打标签」(comment)或更高时,群内任何成员都可以让助手管理本群的定时任务,不核对发言人,记录的作者是群绑定的服务身份;档位为 read 时不提供这个工具。不写时区时按 Asia/Shanghai;建好或改过后,助手按返回的下次运行时间(next_at)回复。提示词里可以写明「没有异常就保持沉默」,这类运行在没有可报告的内容时不发消息,例如「每天 9 点检查 main 的 CI 和新 Issue,有失败就提 Issue 并告诉我们」。
到点或立即运行时,提示词交给这个会话自己的助手执行,结果和运行中的阶段消息(见「阶段消息与停止回答」)发回同一会话:私聊用管理助手,以绑定主人当前的有效权限在一个专属的管理会话里跨项目查询和处理;群聊用本群绑定的服务角色,工具和仓库范围与群里提问时完全相同,派出的任务完成后同样回到本群。提示词只是任务说明,不扩大工具或项目范围;范围外的仓库和未授权的操作照常被拒绝。触发时、每次工具调用前和发送前都会重新检查:定时任务未被修改或删除、私聊主人的飞书绑定仍有效且授权修订未变,或群绑定仍启用、服务角色可用且群围栏未变。私聊主人解绑、群聊助手停用或服务角色停用时,这次运行失败,定时任务暂停并记下原因;模型或网络故障只让这一次失败,之后照常触发。提示词允许没有内容就不通知、而且确实没有时,助手调用 stay_silent(见服务角色),本次记为“无需通知”,不发送消息;返回空回复同样按“无需通知”处理。私聊里只有定时任务的回合提供这个工具,本人发来的消息仍按原规则回答。
每个逻辑触发点只运行一次:channel_schedule_runs 以 (schedule_id, logical_key) 唯一,重启或并发不会重复执行;服务停止期间错过超过 10 分钟的触发点记为跳过,上一次运行尚未结束时的触发点也记为跳过。重启时运行中的记录标为中断,不自动重放。群里正在回答消息时,定时运行稍后开始;群定时运行一开始就占住会话,先补核验群授权人的 GitHub 授权(#846),这期间到达的群消息不另起回合,等定时回合开始时与回合运行期间的新消息一样按「回合中收到新消息」的规则并入。模型用量和预算属于对应的服务角色(管理助手或群绑定的服务角色),与在会话里提问相同。接口见 控制台 API,审计动作为 channel.schedule.*。
项目级「定时计划」和事件订阅仍按 持久化调度模块 运行,目的地不再需要先登记:项目面板的目的地列表直接列出可以选择的会话,即本人已绑定且能读取该项目的私聊,以及本人能管理、范围覆盖该项目的群;保存计划或订阅时按原规则自动登记,同一会话、项目和登记人只登记一次。已有登记继续有效。每次发送前重新检查:私聊目的地核对接收人的读取权限和飞书绑定,群聊目的地核对群绑定仍启用且范围仍覆盖该项目;登记不表示送达。
本地消息账本与历史同步
channel_chats 使用 provider + app_id + installation_tenant + chat_id 唯一标识群或私信;连接凭据轮换不创建新记录。它不直接拼接旧 channel_sessions 中的个人管理会话。原文和资源引用密封保存于 channel_messages,按会话和 message_id 合并实时/历史版本。较旧页面不覆盖较新内容,实时版本优先于同版本历史,撤回 tombstone 不被补读复活;消息变更使本地派生摘要失效。绑定串及可识别凭据在查询中隐藏;附件资源与消息一起保存,授权读取时下载并加密缓存,查询本身不触发下载。
机器人入群或首次接触会话时持久建立 channel_sync_jobs。入群只发送固定记录说明,不调用业务模型或生成项目授权。同步单页使用官方最大值 50,固定升序和 chat 查询时间上界,持续分页直到 has_more=false;没有产品总条数上限。普通对话群的 thread 回复需要单独分页,发现 thread 后建立同一主聊天下的作业。飞书 thread 查询不支持时间范围,因此诊断保留这一限制。每页内容、发现的 thread、游标、完成区间同事务提交;过期租约可恢复,活跃租约不可抢占,重复或循环游标停止并报诊断。
429 遵守 Retry-After,网络错误退避重试,缺权限、不在群、不可见话题等保持受阻状态,不标已同步完成。启动或 SDK 重连补读已完成范围的重叠增量;未完成作业保留原游标继续。撤回事件直接更新本地。官方 SDK 当前未提供通用消息编辑事件,编辑仅在同步读取时按 update_time 合并;管理员可显式全量重新同步,不能承诺编辑均被实时捕获。机器人被移出、群解散或应用停用停止后续同步和受保护发送。
「连接健康与收发记录」下的本地历史页支持消息 ID、时间、关键词、发送者、回复关系与分页。ChannelLedger 不持有 HTTP client,页面与 API 查询不触发飞书请求;未命中只代表本地已同步范围没有结果。返回 sync_state/coverage/gaps,其中 visible_range_complete 只表示本轮遍历了平台返回的可见分页,入群前历史、真实平台可见范围及消息编辑仍显式标为未核验。历史 API 与飞书会话页共用会话级读取权限;项目读取权限本身不自动开放群记录或他人私信。
默认保留策略明确为保留至管理员显式清理,retention_days=null;管理员可配置 1–3650 天,由同步维护周期按日清理,也可显式清理指定时间之前的记录。清理同时删除派生摘要并保留 retained_after 覆盖边界,旧历史补读不能恢复已清理内容。操作保留审计,客户端不能通过搜索触发清理或同步。
验证
npm ci、npm run check、npm test 是基础检查;test/channel-service-bindings.test.mjs 用本地 GitHub App 和飞书协议夹具覆盖群聊绑定的授权条件、飞书应用缺少成员权限时的拒绝、跨仓库问答与范围拒绝、权限档位(同一项目的两个群分别只读和可派活、无平台账号的成员派活、档位与逐项设置的校验)与升级迁移(档位和授权围栏不变)、任务读写与撤权、经 Manager 派活(新建、追加说明、修改约定、取消,不能指定角色)与结果回群、撤销派活后停止任务、群聊助手独立任务的运行时围栏检查、两个群的范围隔离、授权者失权、迁移和删除检查,test/channel-conversation.test.mjs 覆盖发言范围、长原文、滚动摘要和来源变化;test/channel-stage-messages.test.mjs 覆盖群聊、私聊、控制台和定时任务的阶段消息(运行中送达、顺序、每轮 10 条上限)、源消息撤回后不再发送、控制台停止的权限与结果,以及群聊助手、管理助手和独立任务不再有步数上限;e2e/stage-messages.spec.mjs 在页面上验证管理助手显示阶段消息、群聊助手会话显示阶段消息并由负责人停止;test/channel-schedules.test.mjs 覆盖私聊和群聊定时任务的管理权限、跨项目执行、范围与工具拒绝、撤权暂停、逻辑触发点去重和用量归属;test/channels.test.mjs 覆盖项目面板直接选择会话作为目的地、聊天文本不再触发 /project 流程、验签/解密、重投、慢模型、双端绑定、群字段范围、会话隔离、撤权、旧卡片、发送重试和重启恢复。test/channel-setup.test.mjs 覆盖向导和凭据检查的管理员边界、个人应用范围、敏感信息过滤、异步版本检查及部分凭据更新。
e2e/channels.spec.mjs 使用独立 SQLite、随机本地 HTTP 端口、官方事件结构的合法签名样本以及 GitHub/模型/飞书协议夹具验证用户路径。截图和结构化证据保存在 .tmp/channels-165/。测试中只使用测试凭据,不调用真实飞书租户,也不接触正在运行的部署。运行 Playwright 时,将 TMPDIR 和 PLAYWRIGHT_BROWSERS_PATH 设为工作树内目录。
e2e/feishu-setup.spec.mjs 经实际页面验证管理员创建/恢复连接、失败提示、版本冲突,以及用户从合法飞书绑定事件开始,经本地平台登录或可选 GitHub OAuth、原私聊确认到查看与解绑的完整路径。本地登录场景不配置 GitHub OAuth,并核对绑定不增加仓库授权。桌面和手机截图保存在 .tmp/feishu-setup-165/;同样使用本地协议夹具,不代表已连接真实飞书应用。
e2e/channel-service-bindings.spec.mjs 在桌面和手机宽度验证维护人选择仓库绑定仓库问答助手、查询本地群记录和停用,并验证应用缺少成员权限和入口返回网关错误页时保存给出可读提示;e2e/channel-conversation.spec.mjs 验证群聊助手与个人私聊的连续会话页面。截图保存在 .tmp/channel-service-bindings-312/ 和 .tmp/channel-conversation-312/。
test/channel-ledger.test.mjs 验证事务回滚、官方 SDK frame 的失败/成功 ACK、数据库重启、全部分页和 thread、过期租约、429、异常游标、撤回合并、敏感信息、本地零回源及保留边界。e2e/channel-history.spec.mjs 在桌面和手机验证超过 100 条、跨成员/thread/日期的本地消息分页、搜索、同步诊断和保留配置;均为本地协议夹具,不是飞书或 GitHub 真实集成。
实现依据:飞书回调验签与解密、官方 Node SDK、长连接接收事件。实际开通时仍需按应用类型核对权限与可用事件。
历史范围与协议依据:获取会话历史消息、接收消息、撤回消息、机器人进群。历史权限不能保证平台提供全部历史;普通群的根消息与话题回复分页、机器人在群状态、群历史可见设置均影响实际结果。
飞书群聊和私聊收到历史消息编辑或撤回后,保留原会话并向助手提供当前正文和变更通知;旧摘要删除,可能包含旧正文的模型回答与工具上下文在下一步重建。私聊继续使用原 channel_sessions.conversation_id。当前问题被撤回或修改只停止该轮,后续消息仍可继续;自有任务、私有记忆和电脑的归属键保持不变。只有绑定、角色能力、授权或机器人在群内状态真实失效才撤销整个会话;显式历史清理仍作废旧上下文。