2026/9/14 18:32:15
FEATURED · 精选文章 
GenericAgent 飞书机器人接入实战开放平台配置、mykey 凭证与长连接前端解析【免费下载链接】GenericAgentSelf-evolving agent: grows skill tree from 3.3K-line seed, achieving full system control with 6x less token consumption项目地址: https://gitcode.com/GitHub_Trending/pc/GenericAgent本文以仓库中的飞书配置指南docs/SETUP_FEISHU.md为主体完整讲解如何把 GenericAgent 接入飞书从开放平台应用创建、权限与凭证配置到mykey.py凭证文件、frontends/fsapp.py长连接前端的启动测试与聊天命令使用并结合源码剖析消息去重、白名单鉴权、任务卡片实时更新等底层机制读完后可以独立搭建一个“随时随地通过飞书对话控制自己电脑”的 Agent 机器人。方案总览与架构飞书接入的整体链路如下引自配置指南原文你的飞书 ←→ 飞书云 ←→ 长连接 ←→ frontends/fsapp.py ←→ Agent ←→ 你的电脑 ↑ 运行在你电脑上消息通过飞书云转发到你电脑上运行的 frontends/fsapp.pyAgent 处理请求后通过飞书 API 回复消息你的电脑必须保持运行frontends/fsapp.py才能响应消息。从源码看长连接的建立发生在 frontends/fsapp.py 的main()中先构造事件分发器并注册p2_im_message_receive_v1消息回调再创建lark.ws.Client启动 WebSocket 长连接。整个启动循环带有自动重连逻辑——长连接断开或启动失败后按 5 秒起步、指数递增、封顶 120 秒的间隔自动重连frontends/fsapp.py。这与文档中“一个应用只能有一个长连接连接到一台电脑”的说明相互印证长连接实例与你的本地电脑一一对应因此多人使用需要各自创建独立应用。前置条件必需环境Python 3.8本项目完整代码LLM API 密钥Claude/OpenAI 等已在mykey配置文件中配置安装依赖pip install lark-oapilark-oapi是飞书开放平台官方 SDKfrontends/fsapp.py 在文件头部直接import lark_oapi as lark缺少该依赖时前端无法启动。仓库的交互式配置向导 assets/configure_mykey.py 中同样将lark-oapi声明为飞书机器人集成项的依赖可作为依赖清单的交叉佐证。方案选择你的情况推荐方案预计耗时公司已有飞书企业版企业用户配置5-10分钟个人用户/学习测试个人用户配置10-15分钟企业用户配置适用于你的公司使用飞书你有权限创建应用或联系管理员审批步骤 1创建应用访问飞书开放平台open.feishu.cn登录你的企业飞书账号点击右上角「创建应用」→「企业自建应用」填写应用信息应用名称我的Agent助手可自定义应用描述个人AI助手应用图标可选步骤 2添加机器人能力进入应用详情页左侧菜单选择「添加应用能力」找到「机器人」点击「添加」配置机器人信息可保持默认步骤 3配置权限左侧菜单「权限管理」→「API 权限」搜索并开通以下权限im:message- 获取与发送单聊、群组消息im:message:send_as_bot- 以应用身份发送消息contact:user.id:readonly- 获取用户 ID步骤 4获取凭证左侧菜单「凭证与基础信息」记录以下信息App ID形如cli_xxxxxxxxApp Secret一串随机字符串步骤 5发布应用左侧菜单「版本管理与发布」点击「创建版本」填写版本信息提交审核联系企业管理员审批或自己是管理员直接审批步骤 6获取你的 Open ID应用审批通过后在飞书中搜索你的机器人给机器人发送任意消息运行以下代码获取你的 Open ID# 临时运行一次获取 open_id import lark_oapi as lark from lark_oapi.api.im.v1 import * client lark.Client.builder().app_id(你的APP_ID).app_secret(你的APP_SECRET).build() # 监听消息打印发送者的 open_id def handle(data): print(f你的 Open ID: {data.event.sender.sender_id.open_id}) # ... 或者查看 frontends/fsapp.py 运行时的日志输出实际使用中更省事的做法是直接启动frontends/fsapp.py后给机器人发消息frontends/fsapp.py 的handle_message会打印收到消息 [ou_xxx] ...方括号中即你的 Open ID。个人用户配置适用于没有企业飞书账号想个人测试使用步骤 1创建测试企业访问飞书开放平台open.feishu.cn使用个人手机号注册/登录点击右上角头像 →「创建测试企业」填写企业名称如我的测试工作区创建完成后你就是这个测试企业的管理员步骤 2创建应用与企业用户步骤相同点击「创建应用」→「企业自建应用」填写应用信息步骤 3添加机器人能力进入应用详情页「添加应用能力」→「机器人」→「添加」步骤 4配置权限「权限管理」→「API 权限」开通权限im:messageim:message:send_as_botcontact:user.id:readonly步骤 5获取凭证「凭证与基础信息」复制App ID和App Secret步骤 6发布应用测试企业可自审批「版本管理与发布」→「创建版本」提交后进入飞书管理后台「工作台」→「应用审核」→ 通过你的应用步骤 7在飞书客户端使用下载飞书客户端登录你的测试企业账号搜索你创建的机器人名称开始对话项目配置mykey 凭证文件配置飞书凭证编辑项目根目录的mykey.py添加# 飞书应用凭证 fs_app_id cli_xxxxxxxxxxxxxxxx # 替换为你的 App ID fs_app_secret xxxxxxxxxxxxxxxx # 替换为你的 App Secret # 允许使用的用户 Open ID 列表可选留空则允许所有人 fs_allowed_users [ ou_xxxxxxxxxxxxxxxxxxxxxxxx, # 你的 Open ID ]仓库自带的配置模板 mykey_template.py 中这三个字段位于「聊天平台集成可选未填写的平台不会启动对应 adapter」区域且明确注释了白名单语义fs_allowed_users留空或写[*]表示允许所有飞书用户。凭证解析与白名单的源码逻辑frontends/fsapp.py 的_feishu_config()从配置字典中读取fs_app_id、fs_app_secret、fs_allowed_users三个键并计算public_access (not allowed or * in allowed)。随后handle_message在入口处执行鉴权frontends/fsapp.pyopen_id sender.sender_id.open_id ... if not PUBLIC_ACCESS and open_id not in ALLOWED_USERS: print(f未授权用户: {open_id}) return也就是说白名单留空或含*时机器人对外开放否则只有列表内的 Open ID 能触发 Agent其余消息只会在终端留下未授权用户日志而被静默丢弃。这是把 Agent 接进企业群聊时的一道关键安全闸。从源码结构看凭证文件的查找并非只认项目根目录而是按候选列表依次探测frontends/fsapp.py 的_resolve_mykey_pathworkspace/ga_config/mykey.jsonworkspace/ga_config/mykey.pyworkspace/mykey.jsonworkspace/mykey.py项目根mykey.json项目根mykey.py其中 workspace 默认是项目根目录可通过环境变量GA_WORKSPACE_ROOT覆盖.py文件通过动态 import 取全部非下划线开头的变量.json文件则按 JSON 解析。同一套mykey加载逻辑在 llmcore.py 中也有对应实现sys.path内优先mykey.py回退到mykey.json并且 assets/configure_mykey.py 提供了交互式向导选择「飞书机器人」后填入 App ID / App Secret / 允许用户即可自动生成mykey.py适合不想手写配置文件的用户。另外frontends/desktop_bridge.py 的服务发现表把frontends/fsapp.py与(fs_app_id, fs_app_secret)绑定说明桌面端也会按同样两个键判断飞书服务是否已配置、并纳入统一服务管理。确认 LLM 配置飞书机器人只是“入口”真正干活的是 Agent 背后的 LLM。确保mykey配置中已配置 LLM API 密钥例如 Claude# 示例Claude API claude_config { apikey: sk-ant-xxxxx, apibase: https://api.anthropic.com, model: claude-sonnet-4-20250514 }需要注意的是当前仓库的 mykey_template.py 推荐的写法已经演进为mixin_config多渠道故障转移加native_claude_config*/native_oai_config*的结构变量名中含native与claude/oai的条目会分别实例化 Anthropic 原生协议或 OpenAI 协议的工具调用会话mixin_config[llm_nos]按名称引用并自动切换备用渠道。按当前模板格式填写后飞书侧无需任何改动因为 frontends/fsapp.py 只是通过agentmain.GeneraticAgent惰性创建并启动 Agent 主循环LLM 选择对前端完全透明。运行与测试启动服务cd /path/to/pc-agent-loop python frontends/fsapp.py说明把/path/to/pc-agent-loop换成本仓库GenericAgent的实际路径即可。frontends/fsapp.py 启动时会自行把项目根目录加入sys.path并os.chdir到根目录因此在仓库根目录下执行是最稳妥的方式。预期输出 飞书 Agent 已启动长连接模式 App ID: cli_xxxxxxxxxxxxxxxx 等待消息... 实际源码中启动横幅还会多打印一行当前使用的凭证文件路径frontends/fsapp.py配置: {CONFIG_PATH}当mykey找不到多个候选位置时这一行能帮助快速定位“到底读的是哪个配置文件”。启动前自检frontends/fsapp.py 支持两个诊断参数适合在正式启动长连接前先验证配置# 只检查飞书凭证App ID/Secret 是否存在、白名单内容、配置路径 python frontends/fsapp.py --check # 检查飞书配置并进一步初始化 Agent/LLM python frontends/fsapp.py --check-agent--check输出为 JSON其中app_secret会经_mask_secret脱敏frontends/fsapp.py终端日志不会泄露完整密钥ready字段为true才表示凭证齐备。若凭证缺失main()会直接报错并退出提示“请在 mykey 配置中填写 fs_app_id 和 fs_app_secret”并给出配置文件路径frontends/fsapp.py。测试对话打开飞书客户端找到你的机器人发送你好等待回复首次可能需要几秒消息处理链路从一条飞书消息到 Agent 任务启动后每一条飞书消息都会流经 frontends/fsapp.py 的handle_message回调链路如下重投递去重飞书长连接重连后可能重发同一消息_claim_message_once以message_id为键做尽力而为的跨平台去重缓存 TTL 为 10 分钟、上限 2000 条frontends/fsapp.py重复消息只打印忽略重复飞书消息后返回白名单鉴权见上文_feishu_config与handle_message的授权检查消息解析_build_user_message按message_type分流——text直接取文本image/audio/file/media通过飞书资源接口下载到本地temp/feishu_media目录并在提示词中注入[Image: source: ...]/[File: source: ...]标记让多模态模型能读取图片、让 Agent 能引用文件frontends/fsapp.pypost富文本按语言块抽取正文与内嵌图片share_chat/interactive等分享卡片也会被抽取成可读文本。不支持的类型会收到⚠️ 暂不支持处理此类飞书消息提示命令分流以/开头的文本消息交给AgentChatMixin.handle_command处理见下文命令章节其余消息进入run_agent单会话单任务run_agentfrontends/fsapp.py先检查self.user_tasks同一会话已有任务运行时直接提示“请等待完成或发送 /stop 后再试”避免并发踩踏同一个 Agent 主循环。任务卡片实时进度与最终回复飞书前端的run_agent重写了基类实现把 Agent 执行过程渲染成一张持续 patch 的交互式卡片_TaskCardfrontends/fsapp.py任务开始先发送interactive卡片状态显示 思考中...通过向 Agent 主循环注册_turn_end_hooksfrontends/fsapp.py每完成一轮 LLM 调用就追加一个可折叠面板Turn N · summary展开可见 Thinking / Tool Calls / Output 详情状态更新为⏳ 工作中 · Turn N并调用飞书patch接口原地更新同一条卡片消息任务结束时状态变为✅ 已完成卡片末尾以分割线附上最终回复文本卡片推送失败时降级为普通文本消息兜底。此外还有两条边界保护单轮卡片详情超过 8000 字符会被截断整个任务超过AGENT_TIMEOUT_SEC 900秒frontends/fsapp.py会调用agent.abort()并把卡片标记为「任务超时」。回复文本在发送前会经_display_text清洗剥离thinking/summary/tool_use等内部标签超长纯文本回复按split_limit 4000字符分段发送frontends/chatapp_common.py 的split_text。如果 Agent 在回复中生成了文件会以[FILE:filepath]标记的形式出现在输出里_send_generated_files会把这些文件上传飞书图片走 image 接口文档/音视频走 file 接口扩展名到消息类型的映射见 frontends/fsapp.py并逐条发回会话。可用命令在与机器人对话时可以使用以下特殊命令配置指南原文列表命令说明/new开始新对话清除当前上下文/stop中止当前正在执行的任务/restore 关键词恢复之前的对话上下文根据关键词搜索历史记录命令示例/new # 清空对话重新开始 /stop # 停止正在运行的任务 /restore 昨天的任务 # 恢复包含昨天的任务关键词的历史对话源码中的完整命令集飞书前端继承自 frontends/chatapp_common.py 的AgentChatMixinHELP_COMMANDS定义了比文档更多、各 IM 前端飞书/TG/QQ 等共用的命令集命令说明/help显示帮助/status查看状态运行中/空闲、当前 LLM/stop停止当前任务/new开启新对话并清空当前上下文/restore恢复上次对话历史/continue//continue [n]列出可恢复会话 / 恢复第 n 个会话/btw q临时插问主 agent 进展不打断主线/review [scope]in-session code review默认审当前 git diff/llm//llm [n]查看当前模型列表 / 切换到第 n 个模型从源码实现看frontends/chatapp_common.py/restore的实际行为是从temp/model_responses目录中最新的会话日志文件解析出历史轮次用户消息 Agent 回复摘要abort当前任务后把恢复内容追加进agent.history并回复「已恢复 N 轮对话」。发送/help或直接输入无法识别的命令都会返回完整的命令列表。消息显示说明⏳ 表示任务正在执行中消息会实时更新飞书卡片原地 patch无需等待完成超长回复会自动分段发送常见问题Q: 提示「应用未发布」或「无权限」A:确保应用已发布且管理员已审批。测试企业用户需要在管理后台手动审批。Q: 发送消息后没有回复A:检查frontends/fsapp.py是否在运行终端是否有错误日志注意未授权用户提示说明 Open ID 不在白名单内LLM API 密钥是否配置正确可用python frontends/fsapp.py --check-agent验证 Agent/LLM 是否成功初始化Q: 提示「invalid app_id」A:检查mykey.py中的fs_app_id是否正确复制包含cli_前缀。Q: 如何获取自己的 Open IDA:运行frontends/fsapp.py后给机器人发消息查看终端日志中的open_id即收到消息 [ou_xxx]日志行。Q: 能否多人同时使用A:不能。一个应用只能有一个长连接连接到一台电脑。每个人需要创建自己的应用。下一步自定义 Agent 行为编辑 assets/sys_prompt.txt添加新工具编辑 assets/tools_schema.json查看日志运行时观察终端输出如需图形化配置飞书凭证可运行 assets/configure_mykey.py 交互式向导桌面端服务管理参见 frontends/desktop_bridge.py【免费下载链接】GenericAgentSelf-evolving agent: grows skill tree from 3.3K-line seed, achieving full system control with 6x less token consumption项目地址: https://gitcode.com/GitHub_Trending/pc/GenericAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
GenericAgent 飞书机器人接入实战：开放平台配置、mykey 凭证与长连接前端解析
GenericAgent 飞书机器人接入实战开放平台配置、mykey 凭证与长连接前端解析【免费下载链接】GenericAgentSelf-evolving agent: grows skill tree from 3.3K-line seed, achieving full system control with 6x less token consumption项目地址: https://gitcode.com/GitHub_Trending/pc/GenericAgent本文以仓库中的飞书配置指南docs/SETUP_FEISHU.md为主体完整讲解如何把 GenericAgent 接入飞书从开放平台应用创建、权限与凭证配置到mykey.py凭证文件、frontends/fsapp.py长连接前端的启动测试与聊天命令使用并结合源码剖析消息去重、白名单鉴权、任务卡片实时更新等底层机制读完后可以独立搭建一个“随时随地通过飞书对话控制自己电脑”的 Agent 机器人。方案总览与架构飞书接入的整体链路如下引自配置指南原文你的飞书 ←→ 飞书云 ←→ 长连接 ←→ frontends/fsapp.py ←→ Agent ←→ 你的电脑 ↑ 运行在你电脑上消息通过飞书云转发到你电脑上运行的 frontends/fsapp.pyAgent 处理请求后通过飞书 API 回复消息你的电脑必须保持运行frontends/fsapp.py才能响应消息。从源码看长连接的建立发生在 frontends/fsapp.py 的main()中先构造事件分发器并注册p2_im_message_receive_v1消息回调再创建lark.ws.Client启动 WebSocket 长连接。整个启动循环带有自动重连逻辑——长连接断开或启动失败后按 5 秒起步、指数递增、封顶 120 秒的间隔自动重连frontends/fsapp.py。这与文档中“一个应用只能有一个长连接连接到一台电脑”的说明相互印证长连接实例与你的本地电脑一一对应因此多人使用需要各自创建独立应用。前置条件必需环境Python 3.8本项目完整代码LLM API 密钥Claude/OpenAI 等已在mykey配置文件中配置安装依赖pip install lark-oapilark-oapi是飞书开放平台官方 SDKfrontends/fsapp.py 在文件头部直接import lark_oapi as lark缺少该依赖时前端无法启动。仓库的交互式配置向导 assets/configure_mykey.py 中同样将lark-oapi声明为飞书机器人集成项的依赖可作为依赖清单的交叉佐证。方案选择你的情况推荐方案预计耗时公司已有飞书企业版企业用户配置5-10分钟个人用户/学习测试个人用户配置10-15分钟企业用户配置适用于你的公司使用飞书你有权限创建应用或联系管理员审批步骤 1创建应用访问飞书开放平台open.feishu.cn登录你的企业飞书账号点击右上角「创建应用」→「企业自建应用」填写应用信息应用名称我的Agent助手可自定义应用描述个人AI助手应用图标可选步骤 2添加机器人能力进入应用详情页左侧菜单选择「添加应用能力」找到「机器人」点击「添加」配置机器人信息可保持默认步骤 3配置权限左侧菜单「权限管理」→「API 权限」搜索并开通以下权限im:message- 获取与发送单聊、群组消息im:message:send_as_bot- 以应用身份发送消息contact:user.id:readonly- 获取用户 ID步骤 4获取凭证左侧菜单「凭证与基础信息」记录以下信息App ID形如cli_xxxxxxxxApp Secret一串随机字符串步骤 5发布应用左侧菜单「版本管理与发布」点击「创建版本」填写版本信息提交审核联系企业管理员审批或自己是管理员直接审批步骤 6获取你的 Open ID应用审批通过后在飞书中搜索你的机器人给机器人发送任意消息运行以下代码获取你的 Open ID# 临时运行一次获取 open_id import lark_oapi as lark from lark_oapi.api.im.v1 import * client lark.Client.builder().app_id(你的APP_ID).app_secret(你的APP_SECRET).build() # 监听消息打印发送者的 open_id def handle(data): print(f你的 Open ID: {data.event.sender.sender_id.open_id}) # ... 或者查看 frontends/fsapp.py 运行时的日志输出实际使用中更省事的做法是直接启动frontends/fsapp.py后给机器人发消息frontends/fsapp.py 的handle_message会打印收到消息 [ou_xxx] ...方括号中即你的 Open ID。个人用户配置适用于没有企业飞书账号想个人测试使用步骤 1创建测试企业访问飞书开放平台open.feishu.cn使用个人手机号注册/登录点击右上角头像 →「创建测试企业」填写企业名称如我的测试工作区创建完成后你就是这个测试企业的管理员步骤 2创建应用与企业用户步骤相同点击「创建应用」→「企业自建应用」填写应用信息步骤 3添加机器人能力进入应用详情页「添加应用能力」→「机器人」→「添加」步骤 4配置权限「权限管理」→「API 权限」开通权限im:messageim:message:send_as_botcontact:user.id:readonly步骤 5获取凭证「凭证与基础信息」复制App ID和App Secret步骤 6发布应用测试企业可自审批「版本管理与发布」→「创建版本」提交后进入飞书管理后台「工作台」→「应用审核」→ 通过你的应用步骤 7在飞书客户端使用下载飞书客户端登录你的测试企业账号搜索你创建的机器人名称开始对话项目配置mykey 凭证文件配置飞书凭证编辑项目根目录的mykey.py添加# 飞书应用凭证 fs_app_id cli_xxxxxxxxxxxxxxxx # 替换为你的 App ID fs_app_secret xxxxxxxxxxxxxxxx # 替换为你的 App Secret # 允许使用的用户 Open ID 列表可选留空则允许所有人 fs_allowed_users [ ou_xxxxxxxxxxxxxxxxxxxxxxxx, # 你的 Open ID ]仓库自带的配置模板 mykey_template.py 中这三个字段位于「聊天平台集成可选未填写的平台不会启动对应 adapter」区域且明确注释了白名单语义fs_allowed_users留空或写[*]表示允许所有飞书用户。凭证解析与白名单的源码逻辑frontends/fsapp.py 的_feishu_config()从配置字典中读取fs_app_id、fs_app_secret、fs_allowed_users三个键并计算public_access (not allowed or * in allowed)。随后handle_message在入口处执行鉴权frontends/fsapp.pyopen_id sender.sender_id.open_id ... if not PUBLIC_ACCESS and open_id not in ALLOWED_USERS: print(f未授权用户: {open_id}) return也就是说白名单留空或含*时机器人对外开放否则只有列表内的 Open ID 能触发 Agent其余消息只会在终端留下未授权用户日志而被静默丢弃。这是把 Agent 接进企业群聊时的一道关键安全闸。从源码结构看凭证文件的查找并非只认项目根目录而是按候选列表依次探测frontends/fsapp.py 的_resolve_mykey_pathworkspace/ga_config/mykey.jsonworkspace/ga_config/mykey.pyworkspace/mykey.jsonworkspace/mykey.py项目根mykey.json项目根mykey.py其中 workspace 默认是项目根目录可通过环境变量GA_WORKSPACE_ROOT覆盖.py文件通过动态 import 取全部非下划线开头的变量.json文件则按 JSON 解析。同一套mykey加载逻辑在 llmcore.py 中也有对应实现sys.path内优先mykey.py回退到mykey.json并且 assets/configure_mykey.py 提供了交互式向导选择「飞书机器人」后填入 App ID / App Secret / 允许用户即可自动生成mykey.py适合不想手写配置文件的用户。另外frontends/desktop_bridge.py 的服务发现表把frontends/fsapp.py与(fs_app_id, fs_app_secret)绑定说明桌面端也会按同样两个键判断飞书服务是否已配置、并纳入统一服务管理。确认 LLM 配置飞书机器人只是“入口”真正干活的是 Agent 背后的 LLM。确保mykey配置中已配置 LLM API 密钥例如 Claude# 示例Claude API claude_config { apikey: sk-ant-xxxxx, apibase: https://api.anthropic.com, model: claude-sonnet-4-20250514 }需要注意的是当前仓库的 mykey_template.py 推荐的写法已经演进为mixin_config多渠道故障转移加native_claude_config*/native_oai_config*的结构变量名中含native与claude/oai的条目会分别实例化 Anthropic 原生协议或 OpenAI 协议的工具调用会话mixin_config[llm_nos]按名称引用并自动切换备用渠道。按当前模板格式填写后飞书侧无需任何改动因为 frontends/fsapp.py 只是通过agentmain.GeneraticAgent惰性创建并启动 Agent 主循环LLM 选择对前端完全透明。运行与测试启动服务cd /path/to/pc-agent-loop python frontends/fsapp.py说明把/path/to/pc-agent-loop换成本仓库GenericAgent的实际路径即可。frontends/fsapp.py 启动时会自行把项目根目录加入sys.path并os.chdir到根目录因此在仓库根目录下执行是最稳妥的方式。预期输出 飞书 Agent 已启动长连接模式 App ID: cli_xxxxxxxxxxxxxxxx 等待消息... 实际源码中启动横幅还会多打印一行当前使用的凭证文件路径frontends/fsapp.py配置: {CONFIG_PATH}当mykey找不到多个候选位置时这一行能帮助快速定位“到底读的是哪个配置文件”。启动前自检frontends/fsapp.py 支持两个诊断参数适合在正式启动长连接前先验证配置# 只检查飞书凭证App ID/Secret 是否存在、白名单内容、配置路径 python frontends/fsapp.py --check # 检查飞书配置并进一步初始化 Agent/LLM python frontends/fsapp.py --check-agent--check输出为 JSON其中app_secret会经_mask_secret脱敏frontends/fsapp.py终端日志不会泄露完整密钥ready字段为true才表示凭证齐备。若凭证缺失main()会直接报错并退出提示“请在 mykey 配置中填写 fs_app_id 和 fs_app_secret”并给出配置文件路径frontends/fsapp.py。测试对话打开飞书客户端找到你的机器人发送你好等待回复首次可能需要几秒消息处理链路从一条飞书消息到 Agent 任务启动后每一条飞书消息都会流经 frontends/fsapp.py 的handle_message回调链路如下重投递去重飞书长连接重连后可能重发同一消息_claim_message_once以message_id为键做尽力而为的跨平台去重缓存 TTL 为 10 分钟、上限 2000 条frontends/fsapp.py重复消息只打印忽略重复飞书消息后返回白名单鉴权见上文_feishu_config与handle_message的授权检查消息解析_build_user_message按message_type分流——text直接取文本image/audio/file/media通过飞书资源接口下载到本地temp/feishu_media目录并在提示词中注入[Image: source: ...]/[File: source: ...]标记让多模态模型能读取图片、让 Agent 能引用文件frontends/fsapp.pypost富文本按语言块抽取正文与内嵌图片share_chat/interactive等分享卡片也会被抽取成可读文本。不支持的类型会收到⚠️ 暂不支持处理此类飞书消息提示命令分流以/开头的文本消息交给AgentChatMixin.handle_command处理见下文命令章节其余消息进入run_agent单会话单任务run_agentfrontends/fsapp.py先检查self.user_tasks同一会话已有任务运行时直接提示“请等待完成或发送 /stop 后再试”避免并发踩踏同一个 Agent 主循环。任务卡片实时进度与最终回复飞书前端的run_agent重写了基类实现把 Agent 执行过程渲染成一张持续 patch 的交互式卡片_TaskCardfrontends/fsapp.py任务开始先发送interactive卡片状态显示 思考中...通过向 Agent 主循环注册_turn_end_hooksfrontends/fsapp.py每完成一轮 LLM 调用就追加一个可折叠面板Turn N · summary展开可见 Thinking / Tool Calls / Output 详情状态更新为⏳ 工作中 · Turn N并调用飞书patch接口原地更新同一条卡片消息任务结束时状态变为✅ 已完成卡片末尾以分割线附上最终回复文本卡片推送失败时降级为普通文本消息兜底。此外还有两条边界保护单轮卡片详情超过 8000 字符会被截断整个任务超过AGENT_TIMEOUT_SEC 900秒frontends/fsapp.py会调用agent.abort()并把卡片标记为「任务超时」。回复文本在发送前会经_display_text清洗剥离thinking/summary/tool_use等内部标签超长纯文本回复按split_limit 4000字符分段发送frontends/chatapp_common.py 的split_text。如果 Agent 在回复中生成了文件会以[FILE:filepath]标记的形式出现在输出里_send_generated_files会把这些文件上传飞书图片走 image 接口文档/音视频走 file 接口扩展名到消息类型的映射见 frontends/fsapp.py并逐条发回会话。可用命令在与机器人对话时可以使用以下特殊命令配置指南原文列表命令说明/new开始新对话清除当前上下文/stop中止当前正在执行的任务/restore 关键词恢复之前的对话上下文根据关键词搜索历史记录命令示例/new # 清空对话重新开始 /stop # 停止正在运行的任务 /restore 昨天的任务 # 恢复包含昨天的任务关键词的历史对话源码中的完整命令集飞书前端继承自 frontends/chatapp_common.py 的AgentChatMixinHELP_COMMANDS定义了比文档更多、各 IM 前端飞书/TG/QQ 等共用的命令集命令说明/help显示帮助/status查看状态运行中/空闲、当前 LLM/stop停止当前任务/new开启新对话并清空当前上下文/restore恢复上次对话历史/continue//continue [n]列出可恢复会话 / 恢复第 n 个会话/btw q临时插问主 agent 进展不打断主线/review [scope]in-session code review默认审当前 git diff/llm//llm [n]查看当前模型列表 / 切换到第 n 个模型从源码实现看frontends/chatapp_common.py/restore的实际行为是从temp/model_responses目录中最新的会话日志文件解析出历史轮次用户消息 Agent 回复摘要abort当前任务后把恢复内容追加进agent.history并回复「已恢复 N 轮对话」。发送/help或直接输入无法识别的命令都会返回完整的命令列表。消息显示说明⏳ 表示任务正在执行中消息会实时更新飞书卡片原地 patch无需等待完成超长回复会自动分段发送常见问题Q: 提示「应用未发布」或「无权限」A:确保应用已发布且管理员已审批。测试企业用户需要在管理后台手动审批。Q: 发送消息后没有回复A:检查frontends/fsapp.py是否在运行终端是否有错误日志注意未授权用户提示说明 Open ID 不在白名单内LLM API 密钥是否配置正确可用python frontends/fsapp.py --check-agent验证 Agent/LLM 是否成功初始化Q: 提示「invalid app_id」A:检查mykey.py中的fs_app_id是否正确复制包含cli_前缀。Q: 如何获取自己的 Open IDA:运行frontends/fsapp.py后给机器人发消息查看终端日志中的open_id即收到消息 [ou_xxx]日志行。Q: 能否多人同时使用A:不能。一个应用只能有一个长连接连接到一台电脑。每个人需要创建自己的应用。下一步自定义 Agent 行为编辑 assets/sys_prompt.txt添加新工具编辑 assets/tools_schema.json查看日志运行时观察终端输出如需图形化配置飞书凭证可运行 assets/configure_mykey.py 交互式向导桌面端服务管理参见 frontends/desktop_bridge.py【免费下载链接】GenericAgentSelf-evolving agent: grows skill tree from 3.3K-line seed, achieving full system control with 6x less token consumption项目地址: https://gitcode.com/GitHub_Trending/pc/GenericAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
