接入飞书

在电脑上运行 Ghast 后，可以通过飞书单聊或群聊发起任务。入口是 设置 → 渠道 → 飞书。

先准备可用的 Provider、模型 和范围受限的本地 工作区。当前连接使用 open.feishu.cn 服务，客户端没有国际版 Lark 区域选择器，不要把国际版 Lark 凭据当作可直接互换的配置。

接入前确认

使用具备机器人能力的飞书企业自建应用，不是群自定义 webhook 机器人。Webhook URL 不能代替 App ID 或 App Secret。

先把应用可用范围限制到测试用户，只加入不含敏感数据的测试群。Ghast 当前没有飞书用户白名单、群白名单、配对审批或“仅提及”开关。把电脑接入之前，先在飞书限制谁能使用应用、机器人加入哪些群。

长连接需要联网，但不需要公网 IP、域名或隧道；它支持企业自建应用，内置传输鉴权和加密。同一应用的多个客户端会分配接收事件，不是每个都收到完整副本；首次测试只用一份 Ghast 连接。飞书长连接说明。

1. 创建应用并准备权限

1. 打开 飞书开发者后台。
2. 创建企业自建应用，设置名称和图标。
3. 添加或启用 机器人 能力。
4. 将应用可用范围设为目标测试用户，按组织要求完成审批。
5. 在 凭证与基础信息 复制同一应用的 App ID 和 App Secret。
6. 进入 权限管理，配置下方消息接收与回复权限。

客户端配置指引中的权限

当前客户端列出六项：

权限	配置用途
im:message	消息访问
im:message:send_as_bot	以机器人身份回复
im:resource	访问消息图片等资源及回复文件上传
im:message.group_msg	接收用户群消息，包含未提及机器人的普通消息
im:chat:readonly	读取聊天信息
cardkit:card:write	创建和更新流式 Markdown 卡片

还要检查事件专门要求的接收权限。 飞书把单聊和群聊权限分开：接收单聊需要 im:message.p2p_msg:readonly，或控制台提供的对应旧版 im:message.p2p_msg。群内用户提及消息对应 im:message.group_at_msg:readonly 或 im:message.group_at_msg；接收全部用户群消息使用 im:message.group_msg。不要仅凭一个名称宽泛的消息权限，就认定发布后的应用能收到所有事件。接收消息权限要求。

允许全部群消息会扩大进入 Ghast 的数据范围。若只需处理明确提及的群消息，请与管理员核对较窄的提及权限，不要机械地授予全部消息权限。没有普通消息交付时，Ghast 也就不能把这些消息用于群历史，或识别未 @ 时的 ghast 名称呼叫。

Ghast 会忽略发送者为其他应用的消息。不要为了本指南的普通用户消息测试，额外申请机器人之间的消息访问。

2. 填写凭据并启动本地连接

真实中文客户端，App ID 为未保存的虚构示例 cli_documentation_example；机器人保持停用，App Secret 遮蔽，可选字段为空。截图后已丢弃草稿。

设置项	如何填写或使用
App ID	填写真实应用 ID，通常以 cli_ 开头。不要填机器人用户 ID、聊天 ID 或 webhook 地址。
App Secret	填写同一应用的密钥；眼睛按钮可显示或遮蔽。
Verification Token（可选）	当前 Ghast 长连接流程不需要，按本指南接入时留空。
Encrypt Key（可选）	当前长连接流程不需要，按本指南接入时留空。
默认模型	为飞书任务选择优先使用的模型，先配置 Provider 并启用模型。
连接模式	只是说明文字：客户端使用 WebSocket，没有 HTTP/webhook 模式切换器。
启用飞书机器人	核对应用暴露范围和本地工作区后开启，再点击 保存。

两个可选回调字段虽然显示在界面上，但不会配置 HTTP 回调服务器，也不会给当前连接增加独立访问控制。它们是普通明文输入框，不像 App Secret 会遮蔽；截图时不要放入真实秘密。

从关闭状态启用时，App ID 和 App Secret 都必须非空。这只是输入条件，不是认证。页面没有“验证凭据”或“发送测试消息”按钮。

凭据、启用状态、模型和工作区绑定要 保存 才生效。切换平台标签不会保存。放弃草稿时，点击底部 关闭，确认不保存就关闭。保存作用于设置草稿，并非只保存当前可见的小节。

保存有变化的飞书设置会重启连接，单独修改模型或工作区映射也一样。重要任务应先完成再改；保存成功不证明认证、事件交付或模型生成成功。

先启动 Ghast，再保存订阅方式

飞书要求长连接客户端在线，才能保存该订阅方式。先在 Ghast 填好真实 App ID/Secret，选好模型和工作区，启用并保存；保持 Ghast 运行，再完成下一步。配置期间保持应用测试可用范围受限。

3. 订阅消息并发布

1. 保持 Ghast 运行，进入应用的 事件与回调。
2. 编辑事件订阅方式，选择 使用长连接接收事件。
3. 保存该方式。如果提示没有在线长连接，检查 Ghast 机器人日志及凭据；填写一个 webhook 地址不能解决这个问题。
4. 添加 接收消息，事件键为 im.message.receive_v1。
5. 核对对应单聊/群聊的接收权限，不能只检查事件名称。
6. 在 版本管理与发布 创建、提交应用版本，完成审批和发布；确认测试用户在发布版本的应用可用范围内。
7. 后续更改权限或订阅时，按照控制台要求发布更新版本，不要只测试尚未发布的草稿配置。

Ghast 已提供长连接实现，无需另写 SDK 程序，也不需要暴露开发服务器端口。先在线、再保存订阅方式的顺序见 飞书官方连接步骤。

4. 选择模型和工作区

模型优先级

明确设置的飞书默认模型优先于已有对话保存的模型。未设置时，使用已有对话模型，再回退到 Chat 默认模型。在这里选择模型不会自动启用它、充值或修复过期登录。

选择器为空时，先按 模型配置 检查 Provider 是否启用、认证是否可用。已保存模型失效时，先选择其他可用模型并保存，再重试飞书任务。

将聊天路由到本地工作区

在 工作区绑定：

1. 选择已知 聊天 ID，或手动填写。飞书聊天 ID 使用 oc_ 格式，不是 ou_ 发送者 Open ID，也不是 om_ 消息 ID。
2. 选择非临时的本地工作区。
3. 点击 添加，两项缺一不可。
4. 检查映射行，点击 保存。
5. 修改映射时，删除原行，再添加同一聊天 ID 与新工作区，最后保存。

已知聊天列表来自 Ghast 已经记录的会话，不是组织的全部群目录。缺少 ID 时，可请应用管理员检查接收事件的 message.chat_id，或在受控测试消息后查看相关机器人日志。不要根据群名称猜 ID，也不要粘贴整条群邀请链接。

有效的明确绑定优先，然后是 通用 → 默认工作区，最后是 Ghast 自动默认工作区。未绑定的聊天使用 一行可帮助核对回退。

与 Slack 不同，已有飞书对话会在下一条被接收的消息到来时，移动到当前解析出的工作区。修改绑定不只影响新对话。请求读取文件前核对工作区；更换工作区不会隔离或清除之前的对话上下文。

绑定只负责路由，不是白名单。没有绑定的聊天仍可能进入回退工作区。明确绑定和回退目录都应只包含你允许该机器人访问的数据。

工作区绑定需要聊天 ID 和工作区两项，未选择时“添加”禁用。下方配置指引可展开；完整的长连接先后顺序及单聊接收权限请按本文补充步骤核对。

5. 先测单聊，再测群聊

1. 确认应用已发布、测试用户可用，Ghast 仍运行。
2. 在飞书找到机器人，打开单聊。
3. 发送：“只回复 feishu-ready-47。”
4. 确认准确回复出现在飞书；仅 Ghast 本地有答案或显示“运行中”还不够。
5. 继续问刚才返回了什么字符串，确认单聊可以延续。
6. 通过群机器人管理功能，把它加入无敏感内容的测试群。
7. 用飞书 @选择器提及真实机器人，请它返回另一条唯一短回复。
8. 同时检查回复/话题视图和群主会话。文字通过后，再分别测试图片和输出文件。

这里没有额外的 Ghast 配对码或“批准用户”界面。收不到消息时，应从飞书应用可用范围、成员关系、权限和事件排查。

群聊触发与隐私

已交付给 Ghast 的消息	当前行为
用户单聊消息	进入普通任务流程
群聊中 @提及机器人	启动任务
群文字包含 ghast，不区分大小写	没有真正 @ 也会启动任务
两种触发都没有的群消息	先记录最近群历史，再跳过立即启动任务
应用发送的消息	不作为入站任务处理
回复旧群消息，但没有触发词或提及	仅回复不会绕过触发检查

请优先使用真正的 @提及，避免依赖名称匹配。Ghast 也会识别提及信息中的显示名称 Ghast，所以不要把该触发条件当作严格身份认证或授权机制。

群图片和富文本里的图片可能在触发判断之前被下载。普通群文字也可能随后进入某个被触发任务的上下文。“机器人没有回复”不等于“Ghast 没有接收或保留内容”。

敏感范围要在飞书控制：应用可用范围、群成员关系与事件权限。移除全部群消息权限可以减少飞书交付的内容；仅避免输入 ghast 不能保护已经交付给 Ghast 的消息。

对话、回复和命令

• 单聊按聊天和发送者映射；连续顶层私信通常延续同一个 Ghast 对话。
• 群成员共享群级 Ghast 对话。不同回复或话题不会形成独立任务/工作区边界。
• 对话还在生成时，新消息会促使 Ghast 创建分支，而不是简单等待队列。顺序重要时，等上一轮结束再继续。
• 最近本地历史里有对应消息时，可以补充被引用的文字；不要假设完整旧话题都已抓取。
• 文字或卡片可能回复到触发消息；交付回退也可能发送到主会话。消息显示位置不等于上下文隔离。
• 本地群历史和发送者资料可能补充已保存对话。重启或关闭连接不会删除这些已保存内容。

不要依赖远程斜杠命令

当前版本中，普通入站飞书消息不能可靠进入内置命令处理。请把 /new、/stop、/model、/help 视为不可用于控制本集成；它们可能被当成普通模型输入。

请在 Ghast 桌面端查看、停止实际任务，在设置里修改飞书默认模型。模型说“已停止”或“新对话已创建”不证明控制动作发生。尤其不要用“新建飞书话题”代替清空群共享上下文。

图片、文件、音频与回复卡片

输入或输出	当前效果
收到文字	传入对话
收到图片	尝试下载后附加到模型请求，理解能力仍取决于模型
收到富文本消息	提取文字和嵌入图片
收到普通文件	当前只形成 [文件: report.pdf] 这样的文件名提示，不会自动下载正文到模型请求
收到音频、视频等其他类型	当前形成消息类型提示，不要假设已转写或理解媒体
发出生成的文件/图片	可以上传并发送到聊天；这不代表入站文件有相同支持

需要 Ghast 读取文档时，请通过支持的桌面附件入口，或目标工作区内可访问的文件提供。回复中出现文件名不证明正文已读。

CardKit 可提供流式 Markdown 卡片。卡片创建不可用时，Ghast 可回退到持续编辑的普通文字，因此“文字能回”不证明卡片已配置好。缺少卡片时检查 cardkit:card:write 和已发布的应用版本。

流式卡片正文约有 90,000 字符上限，普通文字流式路径约有 4,000 字符上限；这些路径可能截断内容，并非保证完整长文送达。较大结果请要求短回复加结果文件，并单独验证文件。

输出文件和图片发送到聊天，不保证留在文字回复的话题内。上传失败还可能退回文件名提示。请确认存在真正可下载的附件，不只是“📎 文件名”。

Ghast 也可能在完成任务前添加表情回应。表情或正在更新的卡片都不证明任务完成或最终交付成功。

运行状态与日志

飞书启用设置打开且有运行时信息时，才显示 运行状态。因此本指南停用状态的截图中没有该区块。

项目	含义
运行中	本地运行时已启动；飞书目前提供运行健康信息，不是验证过的“已连接”状态。
启动时间	本次运行时开始时间
最近事件	最近收到消息事件的活动；消息随后被忽略也可能更新时间。
机器人日志	凭据/认证、长连接、入站事件、资源及发送错误
桥接日志	对话/工作区/模型路由和回复生成处理

最近事件较旧不一定故障；反过来，“运行中”也不证明已发布应用能送达消息。请执行首条回复测试。

可用日志在页面内展开，默认读取最后 200 行；点击 刷新 再读，× 关闭。切换机器人/桥接日志会替换当前面板。按钮禁用表示运行时没有对应日志路径。

日志可能暴露正文、消息/聊天/用户 ID、资源名及本地路径。只分享相关且已脱敏的片段，保护 App Secret 和可选回调值。

排查问题

现象	下一步
无法启用	填好 App ID 和 App Secret；非空不等于认证有效。
飞书不能保存长连接方式	先启动并保存 Ghast 连接，保存订阅方式时保持在线。
运行中但没有事件	检查 im.message.receive_v1、发布/审批、用户可用范围及群成员关系；测试时避免同一应用运行多个客户端。
群聊可用但单聊无效	单独检查单聊接收权限，不能只看群权限。
单聊可用但群聊无效	把机器人加入该群，授予对应群事件权限，发布后用真正的 @提及。
未提及的群消息进入上下文	全部群消息权限会交付它们，Ghast 在决定是否回复前记录。缩小飞书权限或把机器人移出该群。
填 Verification Token/Encrypt Key 仍连不上	当前长连接流程不使用这两项；检查 App ID/Secret、应用类型和网络。
只有国际版 Lark 凭据	当前是飞书服务地址且没有区域选择器，不要假设支持该接入。
模型错误或没有可用项	检查 Provider 启用、认证、模型和余额，再选择并保存可用飞书默认模型。
新绑定改变了已有对话工作区	这是当前行为：下一条接收的消息重新应用飞书工作区路由；旧上下文需要单独检查。
/stop 或 /new 得到普通回答	此版本不要依赖远程命令；使用桌面任务控件并核对实际状态。
文件有名字但没有读到/无法下载	普通入站文件只有文件名；发出文件的名称也可能是上传失败的回退提示。核对真实内容和访问。
没有卡片或回复不完整	检查 CardKit 权限与发布，区分卡片/文字回退以及流式长度上限。
Ghast 已完成，但飞书没有最终回复	检查原回复和主会话，再看机器人/桥接日志中的发送错误；不要反复发送可能仍在执行的任务。

断开或停用应用

关闭 启用飞书机器人 并 保存，停止连接。这不会撤销应用的飞书权限、删除旧消息、本地对话或已保留的群历史。

永久停用时，还应把机器人移出群，并通过飞书管理流程停用/移除应用或撤销凭据。本地对话和记忆要单独处理。