本手册用于将飞书企业自建应用机器人接入9cWork，完成本人私聊、连续对话及本地历史记录测试。当前聊天渠道为受限文本问答；图片、语音、群聊、电脑控制和CRM工具不属于当前已交付能力。电脑上的9cWork需要保持运行和联网，退出、休眠或断网时不会即时回复。
1. 创建专用应用
打开飞书开发者后台，用具有应用开发权限的账号登录，选择正确企业。点击“创建企业自建应用”，名称建议填写“9cWork测试助手”，描述填写“用于本人私聊测试9cWork文本问答、连续对话、本地历史记录与重启恢复”。按页面要求设置图标，创建应用。
创建后应看到应用名称、待上线状态，以及“凭证与基础信息”“添加应用能力”“权限管理”“事件与回调”“版本管理与发布”等入口。没有创建权限时，需要飞书企业管理员协助；不要使用群里的自定义Webhook机器人代替企业自建应用。
2. 添加机器人能力
进入“添加应用能力”，在“机器人”卡片点击“添加”。进入机器人配置页后，可设置使用说明。本期测试不启用“允许被其他机器人邀请进群”，也不配置机器人菜单和卡片审批。
3. 开通两项应用身份权限
在“权限管理”点击“开通权限”，选择“应用身份权限 tenant_access_token”，分别搜索并选中：
- im:message.p2p_msg:readonly：读取用户发给机器人的单聊消息。
- im:message:send_as_bot：以应用的身份发消息。
核对已选权限后确认开通。不要为了测试单聊额外开通通讯录、全部群消息读取或用户身份权限。权限名称与是否需要审核以飞书后台当前显示为准；开通权限不等于应用已发布，后续还需检查版本生效状态。
4. 保存凭据并登记九宸归属
在“凭证与基础信息”获取同一应用的两项凭据：
App ID（通常以 cli_ 开头）→ 设置 → 聊天平台 → 飞书 → App ID。
App Secret → 设置 → 聊天平台 → 飞书 → 应用 Secret。
阅读并勾选第三方处理、电脑离线和记录保留说明，点击“保存专用应用凭据”。Secret仅输入本机工作台，不发送到聊天、工单、截图或公开文档；保存后不会回显，不需要反复重填。
将工作台显示的App ID及不含密钥的登记信息提供给九宸平台管理员。管理员把该机器人登记给当前九宸租户和用户，再连接渠道。飞书企业管理员负责应用权限和发布，九宸平台管理员负责归属登记，两者职责不同。未登记、归属不符或工作台登录账号不符时，重新填写Secret不能解决问题。
5. 配置长连接和接收事件
建议按下面的顺序操作，避免在工作台尚未连接时反复保存失败：
1. 先完成第4节的凭据保存与九宸归属登记，保持电脑联网，在9cWork飞书页点击“连接渠道”。
2. 打开飞书后台“事件与回调→事件配置”，将订阅方式设为“使用长连接接收事件”；如果当前已选中，也要检查连接状态。
3. 点击“验证”或“重新验证”，看到绿色“连接成功”后点击“保存”。此处验证的是SDK连接，不是本人身份绑定。
4. 点击“添加事件”，选择应用身份的“接收消息 v2.0”，核对事件类型为im.message.receive_v1，确认添加。
5. 在“已添加事件”表核对这条事件存在，所需“读取用户发给机器人的单聊消息”为“已开通”，再进入版本发布。
如果验证失败，先检查工作台是否运行、凭据是否属于同一应用、归属登记是否正确和电脑网络，再重新验证。本插件使用官方SDK长连接，不需要填写公网Webhook回调地址，也不需要另外启动SDK示例程序。
事件订阅、机器人能力、权限和应用版本需要同时正确，只有SDK连接成功不能证明消息已能收发。
6. 发布本人测试版本
进入“版本管理与发布”创建版本，首次版本号可填“1.0.0”，版本说明填写“首次本人私聊文本问答测试”。应用可用或可见范围只加入本人测试账号，按企业流程完成发布或管理员审核。最终核对版本已上线或已生效，不是草稿或待审核。
修改权限或事件后，如果页面提示需要新版本发布，需按相同范围再次发布，配置才会对客户端生效。企业自建应用发布不等于公开上架飞书应用商店。
7. 在页面完成本人绑定
打开9cWork“设置→聊天平台→飞书”，点击“连接渠道”。页面标题下方会显示“下一步：在手机私聊发送绑定口令”。
1. 在飞书切换到应用所属企业，搜索“9cWork测试助手”，打开机器人私聊。
2. 在工作台点击“复制绑定口令”，将完整一行内容粘贴到该机器人私聊并发送。口令不是App Secret，不填写到飞书开发者后台。
3. 回到工作台，核对收到的外部身份确实属于本人，点击“确认绑定本人”。
4. 看见“身份绑定完成，请发送一条文本问题验证”后，再发送测试问题。
口令5分钟有效；过期时在同一页面点击“重新获取绑定口令”，再发送新口令。无需重新扫码、创建应用或重填Secret。为了避免聊天往返消耗有效期，直接使用页面当前口令完成上述步骤，不复制旧截图或他人发来的口令。
8. 验证问答、历史和重启
- 普通问答：绑定完成后发送“1+1等于多少？请用中文回答。”，应收到2，而非只有“已收到”或“连接成功”。
- 本地记录：在工作台左侧“未分组”打开对应IM安全会话，核对问题和答案一致。
- 重启续聊：正常退出9cWork，再打开；绑定和历史应保留。回到同一飞书私聊发送“把刚才算出的结果乘以3，等于多少？”，应收到6，且电脑仍是同一会话的第二轮。
- 手动停止：点击“停止连接”后不应继续接收任务；正常重启也不应自行恢复用户已停止的渠道，需手动重新连接。
只有飞书实际收到正确结果、本地会话记录一致，才视为业务闭环。绑定完成前发送的问题不应自动补执行，绑定成功后重新发送测试问题。
9. 数据保存和使用边界
会话正文保存在电脑的正常持久数据目录，可在工作台查看；解绑默认保留历史，可自行删除。去重记录和待补发文本最多保留7天，这不等于全部会话正文7天后自动删除。应用Secret由Host凭据服务持有，不放入普通页面状态或会话台账。
消息还经过飞书和所选模型服务；通过九宸平台模型网关时，平台调用日志会记录请求、回答和用量，因此不能理解为数据仅存本机。电脑离线时不提供云端代收或实时回复，过期积压任务不会在恢复后突然执行。一个机器人只允许确定的执行主机，不要同时启动多台桌面抢用相同应用凭据。
10. 常见问题
- 搜不到机器人：核对所属企业、机器人能力、版本状态，以及本人是否在应用可见范围。
- 长连接保存失败：先完成本机凭据和九宸归属登记，保持工作台运行并点击连接，再回飞书后台保存。
- 已连接但没有绑定提示：检查工作台账号、租约和状态；确认选择的是飞书，而非微信或钉钉页。
- 发消息完全没有回复：先完成事件订阅和版本发布，再检查本人确认、消息权限、模型账号与工作台任务状态。
- 绑定口令无反应：使用本人机器人私聊；群聊、旧口令、过期口令不参与绑定。
- 收到“本轮未完成”：保留问题、时间和截图，先查模型与平台状态，不反复扫码或解绑。
- 回复中断：可私聊发送“重发结果”，只补发仍保留的已完成结果，不重新执行任务。
官方参考：长连接接收事件；接收消息事件；回复消息接口。