1. 项目概述：为什么“Hermes 集成飞书”是当前最值得小白动手的第一个AI工程实践

如果你最近在技术社区、AI工具群或JetBrains插件市场里刷到过“Hermes”“飞书机器人”“config.yaml”这几个词反复出现，大概率已经感受到一股实操风正在取代空谈模型参数的旧节奏。我从去年底开始系统测试Hermes生态——不是作为概念验证者，而是以一个每天要给3个业务线写自动化脚本、同时还要给非技术同事做AI工具培训的“中间人”身份去落地。结果发现，Hermes + 飞书的组合，是目前全网对零基础用户最友好的AI智能体工程入口。它不依赖GPU服务器，不强制要求Docker编排经验，甚至不需要你理解LLM推理的token调度逻辑；你只需要会改YAML文件、能看懂命令行报错、知道飞书开放平台在哪点“创建机器人”按钮，就能在90分钟内让一个能读文档、写周报、自动归档会议纪要的AI助手，在你团队的飞书群聊里开口说话。

这个项目标题里的“小白手把手操作”，不是营销话术，而是真实可量化的门槛定义：我们把“小白”锚定在三类人身上——刚转行的初级开发（熟悉VS Code但没碰过CLI工具链）、带业务需求的运营/产品同学（会写SQL但没写过Python脚本）、以及需要快速验证AI工作流的中小团队负责人（关注“能不能用”，不关心“为什么这么设计”）。而Hermes之所以能承接这三类人，核心在于它把过去分散在OpenCLAW、Codex、Claude Agent等框架里的能力，做了三层收敛：第一层是配置收敛——所有接入逻辑收束到config.yaml一个文件里，连claude.md都只是它的补充说明文档；第二层是协议收敛——统一用飞书官方Bot API通信，不走Webhook中转、不绕OAuth2.0授权链路，避免了Zabbix告警推送飞书时常见的{"code":11232,"msg":"frequency limited"}频控报错；第三层是部署收敛——支持hermes desktop一键安装（Windows/macOS双平台），也支持hermes agent轻量级CLI模式，连Jenkins持续集成测试都能直接调用hermes run --config config.yaml完成端到端验证。我上周帮一家做跨境电商的客户部署时，主流程就是：下载Hermes Desktop → 打开飞书开放平台复制Bot Token → 粘贴进config.yaml的lark.bot_token字段 → 启动 → 在飞书群@机器人问“上月GMV是多少”，5秒后返回带图表的PDF摘要。整个过程没有一行代码，没有一次pip install，也没有任何“请检查Python环境版本”的弹窗警告。

你可能会疑惑：这和直接用飞书妙记、飞书多维表格的AI功能有什么区别？区别在于控制粒度。飞书原生AI是黑盒服务，你无法干预它的数据源（比如让它只读取指定知识库的PDF）、无法定制响应格式（比如强制输出Markdown表格而非自然语言段落）、更无法嵌入业务逻辑（比如“当检测到订单金额>5000元时，自动触发风控审核流程”）。而Hermes通过config.yaml暴露了全部决策路径：你可以用skills字段声明它具备哪些能力，用data_sources指定它能访问哪些本地文件或API，用prompt_templates精确控制每次回复的起始句式。这种“白盒化AI”的价值，在真实业务中会指数级放大——我见过最典型的案例，是一家做工业设备巡检的客户，他们把Hermes接入内部Zabbix告警系统后，机器人不再简单转发“CPU使用率超90%”，而是自动关联设备台账、调取历史维修记录、生成含建议操作步骤的工单，并推送到对应工程师的飞书单聊。这一切，都始于一个被我手把手教会修改config.yaml的运维专员。

所以这篇博文不讲Hermes的源码架构，也不对比它和OpenCLAW、Coze工作流的技术优劣。我要带你做的，是从飞书开放平台后台截图开始，到你在自己电脑上看到第一个AI回复为止的完整闭环。过程中你会真正理解：为什么config.yaml里lark.app_id和lark.app_secret必须成对出现、为什么skills列表里加一个zabbix_alert就等于注册了一个新API路由、为什么hermes run命令后面跟的--log-level debug参数，能帮你3分钟定位“机器人不回信息”的根源。这不是教程，这是我在17个真实客户现场踩坑后，整理出的最小可行路径。

2. 核心设计思路拆解：Hermes如何用“配置即代码”降低AI工程门槛

Hermes的设计哲学，可以用一句话概括：把AI智能体的生命周期管理，降维成YAML文件的增删改查。这听起来像简化版的Kubernetes，但实际落地时，它比K8s更贴近业务场景——因为你的config.yaml里不会出现replicas: 3或affinity这种基础设施概念，取而代之的是max_conversation_length: 50（单次对话最大轮数）或fallback_skill: "summarize"（兜底技能名称）。这种设计不是为了炫技，而是直击当前AI落地的三个核心痛点：第一是技能复用难，传统方案里每个新需求都要重写Prompt模板、调试API调用逻辑、重新部署服务；第二是权限管控弱，飞书机器人默认拥有群聊全部消息读取权，但业务上你可能只想让它处理财务审批单，不能碰人事考勤数据；第三是调试成本高，当机器人回复错误时，开发者往往要在日志里翻找几十行HTTP请求头，才能定位是Token过期还是知识库加载失败。

Hermes的解法非常务实：它把整个智能体拆成四个可独立配置的模块，全部塞进config.yaml。第一个模块是连接器（Connectors），负责对接外部系统。比如你要接入Zabbix告警，就只需在connectors下添加一段：

zabbix: type: "zabbix_api" url: "https://zabbix.example.com/api_jsonrpc.php" username: "admin" password: "your_password"

这里没有SDK安装、没有证书配置、没有代理设置——Hermes内置了Zabbix API v5.4+的全量方法封装，你填的只是账号密码。同理，对接飞书多维表格时，你不用研究飞书OpenAPI的/bitable/v1/apps/{app_token}/tables/{table_id}/records路径规则，只需写：

feishu_bitable: type: "feishu_bitable" app_token: "your_app_token" table_id: "tbl_xxx" view_id: "vew_yyy"

第二个模块是技能集（Skills），这才是Hermes真正的价值中枢。每个Skill本质是一个带输入输出契约的函数，但你不用写函数体，只需声明它的能力边界。比如定义一个“自动归档会议纪要”的Skill：

meeting_summary: description: "根据飞书妙记转录文本，生成含行动项的摘要" triggers: - "会议纪要" - "总结一下刚才的讨论" input_schema: type: "object" properties: transcript_url: type: "string" description: "飞书妙记生成的文本URL" output_schema: type: "object" properties: summary: type: "string" action_items: type: "array" items: type: "string"

这段YAML的作用，是告诉Hermes：“当用户消息里出现‘会议纪要’关键词，且上下文包含一个URL时，请调用此Skill，并把URL作为transcript_url参数传入”。而Skill的具体实现，由Hermes内置的claude.md模板驱动——它会自动把URL内容抓取下来，用Claude模型做结构化提取，再按output_schema约定的JSON格式返回。你完全不用关心Claude的API密钥怎么传、温度系数怎么设，这些都在claude.md里预置好了。

第三个模块是数据源（Data Sources），解决AI“知识从哪来”的问题。传统方案要么把PDF扔进向量数据库，要么硬编码进Prompt，而Hermes用data_sources实现了动态挂载：

knowledge_bases: - name: "product_manuals" type: "local_pdf" path: "./docs/manuals/" chunk_size: 512 - name: "api_docs" type: "openapi_spec" url: "https://api.example.com/openapi.json"

关键在于chunk_size: 512这个参数——它不是随便写的。我实测过，当PDF文档平均页长为800词时，512字符的分块能保证每个chunk包含完整句子（英文平均词长5字符，512/5≈102词），避免语义断裂。如果设成1024，就会把一页PDF切成两半，导致模型读到“该参数用于”就断开，再也找不到“控制设备启停”这个后半句。这个细节，是我在帮某医疗设备厂商处理说明书时，连续3天调试才确定的最优值。

第四个模块是路由规则（Routing Rules），决定消息发给谁。这里Hermes放弃了复杂的意图识别模型，采用轻量级关键词匹配+正则表达式组合：

routing_rules: - pattern: "^\\d{4}-\\d{2}-\\d{2}.*销售报表$" skill: "sales_report" - pattern: ".*故障.*[0-9]{6}.*" skill: "troubleshoot" connector: "zabbix"

第一条规则的意思是：“如果消息以‘2024-01-01’这样的日期开头，结尾是‘销售报表’，就交给sales_reportSkill处理”。第二条则更精准：“只要消息里同时包含‘故障’和6位数字（设备编号），就调用troubleshootSkill，并强制使用Zabbix连接器获取实时状态”。这种设计的好处是，业务人员自己就能维护——销售总监想新增“Q3区域业绩对比”，只需在routing_rules里加一行正则，不用找开发改代码。

这种“配置即代码”的架构，让Hermes天然适配CI/CD流程。我们团队的标准做法是：把config.yaml放在Git仓库里，每次PR合并自动触发Jenkins任务，执行hermes validate --config config.yaml校验语法，再运行hermes test --config config.yaml --test-cases ./tests/跑回归用例。当测试通过，Jenkins就调用hermes deploy --env prod把新配置推送到生产环境。整个过程，开发、测试、运维各司其职，但所有人都在同一个YAML文件上协作。这比让前端写个React界面来配置机器人，再让后端写API存进MySQL，最后让SRE写Ansible脚本部署，效率高出至少5倍。

3. 核心配置与实操要点：config.yaml逐字段详解与避坑指南

现在我们进入最硬核的部分：config.yaml的每一个字段，到底该怎么填、为什么这么填、填错会怎样。这不是简单的参数罗列，而是基于我处理过的237个客户配置问题，提炼出的实战手册。我会按字段重要性排序，把最容易出错、影响最大的前10个字段拆开讲透，每个都附上真实报错日志和修复方案。

3.1lark.bot_token：飞书机器人的“身份证”，也是90%失败的起点

这是整个集成的生命线。很多小白卡在这一步，不是因为不会复制Token，而是不知道飞书开放平台里有两个完全不同的Token位置：一个是“机器人详情页”的Bot Token，另一个是“凭证密钥”页的App ID/App Secret。前者用于接收消息，后者用于主动调用API（比如发消息、查用户信息）。Hermes要求你填的是前者，但很多人误填了后者，导致启动时出现：

ERROR: Failed to initialize Lark connector: invalid bot token format

正确操作路径是：登录飞书开放平台 → 进入“机器人管理” → 找到你的机器人 → 点击“查看详情” → 在“机器人凭证”区域找到Bot Token（一串以zj_开头的32位字符串）→ 复制粘贴到config.yaml：

lark: bot_token: "zj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

提示：Bot Token有效期为1年，但飞书不会主动通知过期。我建议在Jenkins定时任务里加一条检查：每月1号执行curl -X GET "https://open.feishu.cn/open-apis/bot/v2/info?token=${BOT_TOKEN}"，如果返回{"code":11232}，就说明Token已失效，需人工更新。

3.2lark.encrypt_key与lark.verification_token：安全通信的“双保险”

这两个字段常被忽略，但它们决定了你的机器人能否通过飞书的安全校验。当你在飞书开放平台配置机器人时，必须开启“事件订阅”，并填写“加密密钥”和“验证令牌”。Hermes会用它们解密飞书推送的加密消息，并验证签名合法性。如果留空或填错，你会看到：

WARNING: Received unencrypted event from Lark, skipping...

然后机器人彻底静音。正确做法是：在飞书开放平台机器人设置页 → “事件订阅” → 开启开关 → 点击“生成密钥”，系统会自动生成encrypt_key（32位随机字符串）和verification_token（20位字符串）→ 分别填入：

lark: encrypt_key: "your_encrypt_key_here" verification_token: "your_verification_token_here"

注意：encrypt_key必须严格32位，少一位或多一位都会导致AES解密失败。我曾遇到一个客户，因为复制时多选了一个空格，导致连续2小时调试无果。建议用VS Code的“显示空白字符”功能检查。

3.3skills列表：定义机器人“能做什么”，不是“怎么做的”

这是新手最容易陷入的误区：试图在skills里写业务逻辑。比如想让机器人查Zabbix告警，就写：

# 错误示范！ zabbix_alert: code: | import requests response = requests.get("https://zabbix/api/...", auth=...) return response.json()

Hermes根本不执行Python代码。skills里只放声明式描述，具体实现由内置Skill或claude.md模板驱动。正确写法是：

zabbix_alert: description: "查询指定主机的最新告警" triggers: - "主机xxx告警了吗" - "xxx有没有故障" input_schema: type: "object" properties: host_name: type: "string" description: "Zabbix中配置的主机名" output_schema: type: "object" properties: status: type: "string" enum: ["OK", "PROBLEM"] last_event: type: "string"

这样写的好处是，Hermes能自动生成API文档、做输入校验、甚至用hermes test模拟测试。如果你真需要自定义逻辑，应该写一个独立的Python模块，然后在config.yaml里用custom_skills指向它：

custom_skills: - path: "./skills/zabbix_custom.py" module: "zabbix_custom"

3.4data_sources中的chunk_size：知识切片的“黄金分割点”

前面提到过，这个参数直接影响AI理解质量。但具体数值怎么定？我的经验公式是：chunk_size = (平均文档页字数 × 0.6) ÷ 2。为什么是0.6？因为飞书妙记转录的会议文本，平均每页约1200字，但有效信息密度只有60%，其余是“嗯”“啊”“这个那个”等填充词；为什么要再除以2？因为Hermes的RAG检索机制会取Top2相似chunk拼接成上下文，单个chunk太大会导致冗余，太小会丢失语境。实测数据如下（基于100份不同行业文档）：

所以，当你配置data_sources时，不要盲目套用示例值：

# 正确示范：根据你的文档类型调整 knowledge: - name: "tech_manuals" type: "local_pdf" path: "./docs/tech/" chunk_size: 450 # 技术手册用450 - name: "meeting_notes" type: "local_txt" path: "./docs/meeting/" chunk_size: 240 # 会议纪要用240

3.5prompt_templates：控制AI“说话风格”的隐形开关

很多人以为claude.md是唯一控制Prompt的地方，其实config.yaml里的prompt_templates才是最终生效层。它允许你为不同Skill覆盖全局Prompt。比如默认的claude.md可能让AI用正式书面语回复，但你想让会议纪要Skill用口语化表达，就加：

prompt_templates: meeting_summary: system: | 你是一个高效的会议助理，用简洁、带emoji的短句总结，重点标出行动项。 行动项格式：✅ [负责人] [任务] [截止时间] user: | 请基于以下会议记录，生成摘要： {{transcript}}

这里的{{transcript}}是Hermes的变量语法，会自动替换为实际内容。关键技巧是：永远在system模板里定义角色和约束，在user模板里提供原始数据。如果反过来，把约束写在user里（比如“请用emoji回复”），Claude模型可能忽略它，因为user消息权重低于system。

3.6routing_rules的正则陷阱：别让.匹配了不该匹配的字符

正则表达式是路由的灵魂，也是最易出错的地方。新手常犯的错误是用.*过度匹配。比如想匹配“查询北京服务器状态”，写了：

# 危险！ - pattern: ".*北京.*服务器.*状态.*" skill: "server_status"

这会导致“上海服务器状态异常”也被匹配，因为.*是贪婪匹配。正确写法是用单词边界\b：

- pattern: "\b北京\b.*\b服务器\b.*\b状态\b" skill: "server_status"

更稳妥的做法是用命名捕获组，把关键参数抽出来：

- pattern: "查询(?P<location>\w+?)服务器状态" skill: "server_status" input_mapping: location: "{{location}}"

这样input_mapping会把“北京”赋值给location参数，直接传给Skill，避免在Skill里再做字符串解析。

3.7log_level：调试时的“显微镜”，上线后的“消音器”

这个参数决定了你能看到多少内部细节。开发阶段务必设为debug：

logging: level: "debug"

你会看到每条消息的完整处理链路：

DEBUG: Routing message '北京服务器状态' → matched rule #3 → skill 'server_status' DEBUG: Loading data source 'zabbix_hosts' → found 12 hosts DEBUG: Calling Zabbix API → got 3 alerts for 'beijing-server-01'

但上线后必须改成warning或error，否则日志会爆炸式增长。我曾有个客户，log_level: debug跑了3天，日志文件涨到47GB，直接撑爆服务器磁盘。建议在Jenkins部署脚本里加一道检查：

# 部署前校验 if grep -q "log_level:.*debug" config.yaml; then echo "ERROR: debug log level detected in production config!" exit 1 fi

3.8max_conversation_length：防止AI“话痨”的安全阀

这个参数限制单次对话的最大轮数，默认是20。表面看是性能优化，实则是防呆设计。当AI陷入循环（比如用户连续问“为什么”“那又为什么”），它会自动终止并触发fallback_skill。但如果设得太小，比如5，会导致正常多轮对话被截断。我的建议是：根据业务场景设定。客服场景用15（用户平均提问3-5轮），技术问答用25（可能涉及代码片段交互），而会议纪要这种单次任务型，用5就足够。

3.9timeout_seconds：网络不稳时的“救命稻草”

Hermes默认HTTP超时是30秒，但在国内访问某些API（如海外Zabbix实例）时，经常超时。这时不要盲目调大，而是分层设置：

connectors: zabbix: timeout_seconds: 60 # Zabbix API慢，单独加大 feishu_bitable: timeout_seconds: 15 # 飞书API快，保持默认

全局timeout_seconds只影响未单独配置的Connector。这样既保证稳定性，又不拖慢整体响应。

3.10custom_env：注入敏感信息的“保险箱”

API密钥、数据库密码等绝不能硬编码在config.yaml里。Hermes支持环境变量注入：

custom_env: ZABBIX_PASSWORD: "${ZABBIX_PASSWORD}" FEISHU_APP_SECRET: "${FEISHU_APP_SECRET}"

然后启动时用：

ZABBIX_PASSWORD="xxx" FEISHU_APP_SECRET="yyy" hermes run --config config.yaml

实操心得：在Jenkins里，把这些变量存在“凭据管理”中，用${credentials('zabbix_pwd')}引用，避免明文泄露。

4. 完整实操流程：从零开始，90分钟内让飞书机器人开口说话

现在我们把前面所有知识点串起来，走一遍真实部署流程。我会以“为销售团队搭建一个自动查询周报数据的飞书机器人”为例，全程记录每一步操作、预期结果、常见卡点及解决方案。这不是理想化的演示，而是我上周在客户现场的真实复刻，连终端报错截图都还原了。

4.1 环境准备：三步搞定本地运行环境

第一步：下载Hermes Desktop。访问 Hermes官网下载页 ，选择对应系统版本（Windows/macOS/Linux）。注意：不要下载源码包，新手用Desktop版最稳。安装时勾选“添加到PATH”，这样后续命令行才能直接调用hermes。

第二步：确认Python环境。Hermes Desktop自带Python 3.10运行时，但你需要确保系统没有冲突的Python版本。打开终端，执行：

hermes --version

如果返回Hermes CLI v1.2.3，说明环境OK。如果报错command not found，说明PATH没配好，重启终端或手动添加：

# macOS/Linux export PATH="/Applications/Hermes Desktop.app/Contents/MacOS:$PATH" # Windows PowerShell $env:Path += ";C:\Program Files\Hermes Desktop"

第三步：创建项目目录。新建文件夹sales-report-bot，进入后初始化：

mkdir sales-report-bot && cd sales-report-bot hermes init

hermes init会自动生成标准目录结构：

sales-report-bot/ ├── config.yaml # 主配置文件 ├── skills/ # 自定义Skill存放处 ├── docs/ # 知识库文档 └── tests/ # 测试用例

注意：hermes init生成的config.yaml是通用模板，里面有很多注释掉的示例。新手务必先删掉所有#开头的注释行，只保留必需字段，避免被干扰。

4.2 飞书开放平台配置：5分钟完成机器人创建

登录 飞书开放平台 → 右上角“开发者后台” → “机器人管理” → “创建机器人”。填写信息时注意三点：第一，“机器人名称”建议用业务名，如“销售周报助手”，方便团队识别；第二，“应用图标”上传公司LOGO，增加信任感；第三，权限范围一定要勾选“群消息”和“用户信息”，否则机器人收不到群聊消息。创建完成后，立即进入“机器人详情”页，复制Bot Token、Encrypt Key、Verification Token三个值，粘贴到config.yaml对应位置。

关键动作：在“事件订阅”页，开启开关，并在“订阅事件”里勾选message（接收消息）和url_verification（首次验证）。保存后，飞书会向你的Hermes服务发送验证请求。此时先别急着启动，因为config.yaml还没填完。

4.3 编写config.yaml：聚焦销售场景的最小可行配置

打开config.yaml，删除所有注释，按以下结构填写（我已过滤掉无关字段，只保留销售周报必需的）：

# === 基础配置 === name: "sales-report-bot" version: "1.0.0" # === 飞书连接器 === lark: bot_token: "zj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # 替换为你复制的Token encrypt_key: "your_encrypt_key_here" # 替换为你生成的密钥 verification_token: "your_verification_token_here" # 替换为你生成的令牌 # === 技能定义 === skills: weekly_report: description: "生成指定日期范围的销售周报" triggers: - "本周销售数据" - "上上周业绩" - "查看[0-9]{4}-[0-9]{2}-[0-9]{2}到[0-9]{4}-[0-9]{2}-[0-9]{2}销售报表" input_schema: type: "object" properties: start_date: type: "string" format: "date" end_date: type: "string" format: "date" output_schema: type: "object" properties: total_revenue: type: "number" new_customers: type: "integer" top_product: type: "string" # === 数据源（模拟销售数据）=== data_sources: - name: "sales_data" type: "csv_file" path: "./docs/sales_data.csv" date_column: "order_date" revenue_column: "revenue" # === 路由规则 === routing_rules: - pattern: "本周销售数据" skill: "weekly_report" input_mapping: start_date: "{{now - 7 days}}" end_date: "{{now}}" - pattern: "上上周业绩" skill: "weekly_report" input_mapping: start_date: "{{now - 14 days}}" end_date: "{{now - 7 days}}" - pattern: "查看(?P<start>\d{4}-\d{2}-\d{2})到(?P<end>\d{4}-\d{2}-\d{2})销售报表" skill: "weekly_report" input_mapping: start_date: "{{start}}" end_date: "{{end}}" # === 日志与安全 === logging: level: "debug" # === 其他 === max_conversation_length: 5

这里的关键细节：input_mapping里的{{now - 7 days}}是Hermes内置的时间表达式，会自动计算为2024-01-01这样的格式；csv_file数据源指定了date_column和revenue_column，Hermes会自动按日期聚合销售额。

4.4 准备销售数据：用CSV模拟真实业务库

在docs/目录下创建sales_data.csv，内容如下（用Excel生成后另存为CSV UTF-8）：

order_id,order_date,product,amount,customer_id ORD-001,2024-01-01,Product A,12000,CUST-001 ORD-002,2024-01-02,Product B,8500,CUST-002 ORD-003,2024-01-03,Product A,15000,CUST-003 ORD-004,2024-01-04,Product C,6200,CUST-001

提示：CSV必须用英文逗号分隔，日期格式必须为YYYY-MM-DD，否则Hermes解析会失败，报错ValueError: time data '01/01/2024' does not match format '%Y-%m-%d'。

4.5 启动与验证：第一次看到AI回复的时刻

一切就绪，执行启动命令：

hermes run --config config.yaml

你会看到类似输出：

INFO: Hermes v1.2.3 starting... INFO: Loading config from config.yaml INFO: Initializing Lark connector... INFO: Lark connector initialized successfully INFO: Loading data sources... INFO: Loaded 4 records from ./docs/sales_data.csv INFO: Starting HTTP server on http://localhost:8000 INFO: Server is ready. Listening for events...

此时，打开飞书客户端，进入任意群聊，@你的机器人，发送“本周销售数据”。3秒后，你应该收到一条消息：

📊 本周销售数据（2024-01-01 至 2024-01-07） • 总营收：31700 元 • 新增客户：3 位 • 畅销产品：Product A

如果没收到，立刻看终端日志。最常见的问题是：

• 日志卡在Starting HTTP server...不动：说明飞书没连上你的本地服务。检查是否开了防火墙，或尝试用hermes run --host 0.0.0.0 --port 8000绑定所有IP。
• 日志出现Failed to parse CSV: expected 5 fields, saw 6：CSV里有隐藏的BOM头或多余逗号。用VS Code打开，右下角切换编码为UTF-8，删除首行BOM。
• 收到{"code":11232,"msg":"frequency limited"}：飞书频控，说明机器人被高频调用。检查是否在测试时连续发了10条消息，暂停1分钟再试。

4.6 进阶调试：用hermes test做离线验证

不想每次都发消息测试？用内置测试工具：

hermes test --config config.yaml --test-cases ./tests/weekly_report_test.yaml

先在tests/目录下创建weekly_report_test.yaml：

- name: "测试本周销售数据" input: "本周销售数据" expected_skill: "weekly_report" expected_output: total_revenue: 31700 new_customers: 3

运行后，Hermes会模拟消息处理，输出：

PASS: 测试本周销售数据 → total_revenue=31700, new_customers=3

这比手动测试快10倍，而且能集成到CI流程里。

5. 常见问题与排查技巧实录：那些让我熬夜到凌晨的Bug

在交付23个Hermes项目的过程中，我整理了一份“血泪清单”，记录了最常出现、最让人抓狂的问题。这些问题不来自文档，而是来自真实世界的网络抖动、配置疏忽和认知偏差。我把它们按发生频率排序，并给出可立即执行的解决方案。

5.1 问题：机器人完全不响应，终端日志只有Server is ready，无任何错误

发生频率：38%（最高频）

根本原因：飞书开放平台的“事件订阅”URL没填对，或你的本地服务没暴露到公网。

排查步骤：

1. 登录飞书开放平台 → 进入机器人 → “事件订阅” → 检查“请求网址”是否为http://localhost:8000（开发时）或你的公网地址（生产时）。
2. 如果是localhost，确认你的电脑防火墙没拦截8000端口。Windows用户可执行netsh advfirewall firewall add rule name="Hermes Port" dir=in action=allow protocol=TCP localport=8000。
3. 如果是公网地址，确认Nginx/Apache反向代理配置正确。Hermes要求/路径必须透传，不能重写为/hermes/。

独家技巧：用curl手动模拟飞书验证请求，快速定位：

# 模拟飞书首次验证 curl -X POST "http://localhost:8000" \ -H "Content-Type: application/json" \ -d '{"type":"url_verification","challenge":"test_challenge"}'

如果返回{"challenge":"test_challenge"}，说明服务OK；如果返回404，说明路由配置错误。

5.2 问题：机器人回复了，但内容是乱