1. 项目缘起从“写报告”的重复劳动到“自动生成”的解放测试报告这玩意儿对于任何一个搞开发、做测试或者负责项目交付的同学来说都再熟悉不过了。每次版本迭代、功能上线或者仅仅是日常的回归测试最后都得产出这么一份文档。内容嘛大同小异测试概述、环境信息、执行结果、缺陷统计、风险与建议……格式固定但数据填充和文字组织却是个繁琐的体力活。尤其是当测试用例成百上千结果数据散落在不同平台比如Jira、TestRail、Jenkins的Allure报告时手动汇总、复制粘贴、再调整格式一两个小时就这么没了还容易出错。我最近就在琢磨这种高度结构化、数据驱动、流程固定的文档生成工作是不是可以彻底交给机器正好最近各种AI Agent和自动化工具比如OpenClaw、各类Skill框架炒得火热它们号称能理解意图、调用工具、执行复杂任务。那能不能自己动手打造一个专属的“自动写测试报告”的Skill呢这个Skill的核心目标很明确我给它一个指令比如“生成v2.1.0版本的测试报告”它就能自动去拉取测试数据、分析结果、组织内容最终生成一份格式规范、数据准确、甚至带有初步分析的Markdown或Word文档直接发到我的聊天窗口或者指定频道。这不仅仅是偷懒更是将测试人员从重复劳动中解放出来把精力聚焦在更有价值的测试设计、深度缺陷分析和质量风险评估上。下面我就把自己从零开始搭建这个“自动写测试报告Skill”的完整过程、技术选型、踩坑经验以及最终的实现方案毫无保留地分享出来。2. 核心架构设计让AI Agent成为你的报告助理要实现“自动写报告”我们不能把它想象成一个简单的脚本。脚本是死的流程是固定的。而一个真正的“Skill”应该具备一定的智能和灵活性能够理解相对模糊的指令并自主协调多个步骤来完成目标。这正符合当前AI Agent智能体的设计理念。因此我决定采用“AI Agent 工具调用Tool Calling”作为本项目的核心架构。简单来说这个Skill就是一个AI智能体它被赋予了“测试报告专家”的角色。它的工作流程可以分解为以下几个核心环节指令解析与任务规划用户说“生成上周的回归测试报告”。Agent需要理解这个指令并规划出完成任务所需的步骤例如确定时间范围、识别数据源、决定报告模板。数据获取与聚合根据规划Agent需要调用不同的“工具”Tools去获取原始数据。比如调用Jenkins API获取构建信息和Allure报告链接调用Jira API获取该周期内创建和关闭的缺陷调用测试管理工具API获取用例执行详情。数据分析与内容组织获取到原始数据通常是JSON格式后Agent需要进行分析和提炼。例如计算测试通过率、失败用例的分类统计、缺陷的严重等级分布、与上一版本的对比趋势等。然后按照预设的报告模板框架将分析结果组织成连贯的文字段落和图表描述。报告生成与交付将组织好的内容填充到最终的文档模板中如Markdown并可能调用文档生成工具如Pandoc转换为PDF或Word格式。最后将成品通过消息通道如飞书机器人、钉钉机器人、邮件发送给用户。在这个架构中AI Agent例如基于OpenAI GPT、Claude或开源模型如DeepSeek是大脑负责规划和决策而一系列封装好的工具函数是它的手脚负责执行具体的操作。我们所要做的就是为这个大脑定义清晰的职责并为它装备好所有必要的手脚。2.1 技术栈选型与思考市面上能构建AI Agent的框架和平台很多比如LangChain、LlamaIndex、CrewAI以及一些云服务商提供的AI应用开发平台。我的选型思路基于以下几点自主可控与成本希望部署在内部环境避免敏感测试数据外流同时控制长期使用成本。开发效率与灵活性框架要成熟社区活跃能快速集成各种工具和API。与现有生态结合我们内部使用飞书进行协作因此Skill最好能方便地接入飞书。基于这些考虑我选择了OpenClaw作为Agent运行框架。OpenClaw是一个开源的AI Agent框架它设计简洁专注于工具调用和任务规划非常适合构建这种单一职责但需要多步协作的Skill。它不像LangChain那样庞大学习曲线相对平缓且对国产模型如DeepSeek、GLM的支持也比较好。为什么是OpenClaw而不是直接写脚本如果只是固定流程写个Python脚本配合Cron定时任务当然可以。但“Skill”的想象空间更大。比如未来我可以对它说“对比一下v2.1.0和v2.0.0的测试稳定性重点分析接口响应时间的变化。”这种复杂的、需要理解对比维度和分析重点的指令纯脚本很难处理而基于LLM的Agent可以通过自然语言理解来拆解并尝试完成。OpenClaw提供了这种“规划-执行”的基础能力。其他关键组件大语言模型LLM作为Agent的“大脑”。我选择了DeepSeek-Coder的最新版本通过本地化部署的Ollama来调用。原因在于测试报告生成涉及一定的代码如处理JSON、逻辑推理如计算百分比、判断趋势和结构化输出DeepSeek-Coder在这方面的能力很强且对中文支持友好性价比高。工具库Tools用Python的FastAPI或Flask快速搭建一组API作为Agent可调用的工具。每个工具对应一个具体的获取或处理操作。消息平台集成使用飞书开放平台的机器人API让Skill能接收用户指令并发送报告。报告生成采用Jinja2模板引擎来定义Markdown报告模板数据填充后使用python-docx或WeasyPrint可转换为更正式的格式。3. 实战第一步搭建OpenClaw环境与定义核心工具理论说再多不如动手。第一步就是把OpenClaw跑起来并定义出第一个能用的工具。3.1 OpenClaw的本地部署与配置OpenClaw的安装其实很简单官方推荐使用Docker这对于保证环境一致性非常友好。# 1. 拉取OpenClaw的Docker镜像 docker pull openclaw/openclaw:latest # 2. 准备一个配置文件 config.yaml mkdir -p ~/openclaw-config cd ~/openclaw-config vim config.yamlconfig.yaml是OpenClaw的核心我们需要在这里配置LLM的接入点、工具列表以及Agent的基础设定。# config.yaml 示例 model: provider: ollama # 使用本地ollama服务 model: deepseek-coder:latest # 指定的模型名称 base_url: http://host.docker.internal:11434 # Docker容器内访问宿主机ollama的地址 # 技能Skill定义这里就是我们核心的“写报告”技能 skills: - name: generate_test_report description: 根据用户指定的版本或时间范围自动生成软件测试报告。 # 这个技能的触发指令用户输入中包含这些关键词即可触发 triggers: [生成测试报告, 写一份测试报告, test report] # 技能的具体执行流程由一系列步骤Step组成每个步骤可以调用工具或直接让LLM生成内容 steps: - type: llm prompt: | 你是一个专业的测试报告生成助手。用户要求生成测试报告。 请向用户询问清楚以下信息 1. 报告对应的项目或版本号例如v2.1.0。 2. 报告覆盖的时间范围例如2024-05-01至2024-05-10。如果用户未提供默认为最近7天。 3. 报告需要的详细程度概览/详细。 请以清晰、友好的方式一次性提出所有问题。 - type: tool tool_name: fetch_test_data # 上一步LLM收集到的参数会通过变量传递给工具 input_mapping: version: {{ version }} start_date: {{ start_date }} end_date: {{ end_date }} - type: tool tool_name: analyze_and_generate_report input_mapping: raw_data: {{ fetch_test_data.result }} - type: llm prompt: | 这是一份生成的测试报告草稿{{ analyze_and_generate_report.result }}。 请你以专业、简洁的口吻进行最终润色确保语句通顺重点突出如阻塞性问题、风险项。 输出格式为完整的Markdown文档。这个配置文件定义了一个名为generate_test_report的技能。当用户在飞书群里机器人并说“生成v2.1.0的测试报告”时就会触发这个技能。技能的执行分为四步1. 让LLM询问详情2. 调用工具获取数据3. 调用另一个工具分析并生成草稿4. 最后再让LLM润色输出。注意这里的host.docker.internal是Docker的一个特殊DNS指向宿主机。确保你的宿主机上已经运行了Ollama服务ollama run deepseek-coder:latest并且端口11434可访问。3.2 开发第一个核心工具获取测试数据工具Tool本质上是一个HTTP接口OpenClaw会向这个接口发送POST请求来调用它。我们需要用Python这里用FastAPI为例来实现fetch_test_data这个工具。首先创建一个工具服务项目mkdir test-report-tools cd test-report-tools python -m venv venv source venv/bin/activate pip install fastapi uvicorn requests pydantic创建tools_server.pyfrom fastapi import FastAPI, HTTPException from pydantic import BaseModel from datetime import datetime import requests import json app FastAPI(title测试报告工具服务) # 定义工具接收的参数模型 class FetchDataRequest(BaseModel): version: str start_date: str end_date: str # 模拟从Jenkins API获取Allure报告摘要 def get_jenkins_allure_summary(build_id): # 这里替换成你真实的Jenkins API URL和认证信息 jenkins_url fhttp://your-jenkins/job/your-project/{build_id}/allure/api/report auth (username, api_token) try: response requests.get(jenkins_url, authauth, timeout10) response.raise_for_status() return response.json() # 假设返回包含statistics, suites等信息的JSON except requests.RequestException as e: print(f获取Jenkins数据失败: {e}) return {statistics: {total: 0, passed: 0, failed: 0, skipped: 0}} # 模拟从Jira API获取缺陷数据 def get_jira_issues(version, start_date, end_date): jql fproject YOURPROJECT AND fixVersion {version} AND created {start_date} AND created {end_date} jira_url https://your-jira.atlassian.net/rest/api/3/search headers {Authorization: Bearer YOUR_JIRA_TOKEN} params {jql: jql, maxResults: 100} try: response requests.get(jira_url, headersheaders, paramsparams, timeout10) response.raise_for_status() issues response.json().get(issues, []) # 简化处理只提取关键信息 defect_list [] for issue in issues: key issue.get(key) summary issue.get(fields, {}).get(summary, ) status issue.get(fields, {}).get(status, {}).get(name, ) priority issue.get(fields, {}).get(priority, {}).get(name, ) defect_list.append({key: key, summary: summary, status: status, priority: priority}) return defect_list except requests.RequestException as e: print(f获取Jira数据失败: {e}) return [] # 工具端点/tools/fetch_test_data app.post(/tools/fetch_test_data) async def fetch_test_data(request: FetchDataRequest): 根据版本和时间范围从各个数据源获取测试原始数据。 print(f开始获取数据: version{request.version}, start{request.start_date}, end{request.end_date}) # 1. 获取构建信息和测试统计这里需要根据版本号映射到具体的Jenkins构建ID简化处理 # 假设我们有一个简单的映射关系或通过查询API获得 build_id resolve_build_id(request.version) # 这是一个需要你实现的函数 jenkins_data get_jenkins_allure_summary(build_id) # 2. 获取缺陷数据 jira_data get_jira_issues(request.version, request.start_date, request.end_date) # 3. 聚合数据 aggregated_data { version: request.version, period: f{request.start_date} 至 {request.end_date}, test_summary: jenkins_data.get(statistics, {}), defects: jira_data, fetch_time: datetime.now().isoformat() } return {status: success, result: aggregated_data} def resolve_build_id(version: str) - str: # 示例简单映射实际中可能需要查询Jenkins API或维护一个映射表 mapping {v2.1.0: 125, v2.0.0: 118} return mapping.get(version, lastSuccessfulBuild) # 默认返回最后一次成功构建 if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)这个工具服务启动在8000端口。它提供了一个/tools/fetch_test_data的API。当OpenClaw的Agent执行到相应步骤时就会向这个地址发送POST请求并附上版本号、起止日期等参数。工具服务负责与真实的Jenkins、Jira等系统交互将分散的数据聚合到一个JSON对象中返回。关键点与踩坑记录认证与安全所有对内部系统的API调用都需要妥善处理认证信息如API Token、用户名密码。绝对不要将硬编码的密钥提交到代码仓库。务必使用环境变量或配置文件来管理并在Docker运行时注入。错误处理网络请求可能失败API格式可能变化。工具函数中必须有完善的异常捕获和日志记录并返回一个结构化的错误信息或降级数据如返回空列表或零值避免因为一个数据源挂掉导致整个Skill崩溃。数据映射resolve_build_id函数是关键。在实际项目中版本号与Jenkins构建号往往不是简单映射。你可能需要调用Jenkins API根据构建描述或参数化构建的版本来动态查找对应的构建ID。这里简化处理了。4. 实现报告生成与内容编排逻辑拿到聚合的原始数据后下一步就是分析和生成报告草稿。我们创建第二个工具analyze_and_generate_report。4.1 数据分析与报告模板引擎这个工具的任务更偏重逻辑处理。它接收fetch_test_data返回的原始数据进行计算、分析并填充到Jinja2模板中。首先安装Jinja2pip install Jinja2。创建report_template.md.j2# {{ project_name }} 测试报告 ({{ data.version }}) **报告周期**: {{ data.period }} **生成时间**: {{ generated_time }} ## 一、测试概述 本次测试针对 **{{ data.version }}** 版本覆盖了{{ data.period }}期间的所有测试活动。主要进行了功能回归、接口自动化及核心场景的验证。 ## 二、测试环境 * **测试环境**: {{ env_info.test_env }} * **数据库**: {{ env_info.database }} * **构建号**: {{ env_info.build_number }} ## 三、测试执行情况 ### 3.1 用例执行统计 | 测试类型 | 用例总数 | 通过数 | 失败数 | 跳过数 | **通过率** | | :--- | :---: | :---: | :---: | :---: | :---: | | 功能测试 | {{ stats.functional.total }} | {{ stats.functional.passed }} | {{ stats.functional.failed }} | {{ stats.functional.skipped }} | **{{ stats.functional.pass_rate }}%** | | 接口测试 | {{ stats.api.total }} | {{ stats.api.passed }} | {{ stats.api.failed }} | {{ stats.api.skipped }} | **{{ stats.api.pass_rate }}%** | | UI自动化 | {{ stats.ui.total }} | {{ stats.ui.passed }} | {{ stats.ui.failed }} | {{ stats.ui.skipped }} | **{{ stats.ui.pass_rate }}%** | | **合计** | **{{ stats.total.total }}** | **{{ stats.total.passed }}** | **{{ stats.total.failed }}** | **{{ stats.total.skipped }}** | **{{ stats.total.pass_rate }}%** | ### 3.2 缺陷统计与分析 本期共发现缺陷 **{{ defects.summary.total }}** 个。 * **按状态分布** * 待处理 (Open): {{ defects.summary.by_status.open }} * 处理中 (In Progress): {{ defects.summary.by_status.in_progress }} * 已解决 (Resolved): {{ defects.summary.by_status.resolved }} * 已关闭 (Closed): {{ defects.summary.by_status.closed }} * **按优先级分布** * 致命 (Critical): {{ defects.summary.by_priority.critical }} * 严重 (Major): {{ defects.summary.by_priority.major }} * 一般 (Minor): {{ defects.summary.by_priority.minor }} **重点关注缺陷**: {% if defects.critical_items %} {% for item in defects.critical_items %} * **[{{ item.key }}]** {{ item.summary }} (状态: {{ item.status }}, 优先级: {{ item.priority }}) {% endfor %} {% else %} * 本期未发现致命(Critical)级别缺陷。 {% endif %} ## 四、测试结论与风险 1. **质量评估**: 整体通过率为 **{{ stats.total.pass_rate }}%**{% if stats.total.pass_rate 95 %}达到发布标准。{% else %}未达到95%的发布标准需重点关注失败用例。{% endif %} 2. **主要风险**: {{ risks_assessment }}。 3. **发布建议**: {{ release_recommendation }}。 ## 五、附录 * 详细测试用例执行记录: [链接] * Allure测试报告: [链接] * Jira缺陷列表: [链接]然后在工具服务中添加新的端点和处理逻辑# 在 tools_server.py 中添加 from jinja2 import Environment, FileSystemLoader import os # 初始化Jinja2环境 env Environment(loaderFileSystemLoader(.), trim_blocksTrue, lstrip_blocksTrue) report_template env.get_template(report_template.md.j2) class AnalyzeRequest(BaseModel): raw_data: dict def analyze_test_data(raw_data: dict): 分析原始数据生成用于模板填充的结构化数据 stats raw_data.get(test_summary, {}) # 计算通过率等衍生数据 total stats.get(total, 0) passed stats.get(passed, 0) pass_rate round((passed / total * 100), 2) if total 0 else 0.0 # 对缺陷数据进行分类统计 defects raw_data.get(defects, []) by_status {open: 0, in_progress: 0, resolved: 0, closed: 0} by_priority {critical: 0, major: 0, minor: 0} critical_items [] for d in defects: status_lower d.get(status, ).lower() priority_lower d.get(priority, ).lower() if open in status_lower: by_status[open] 1 elif progress in status_lower: by_status[in_progress] 1 elif resolve in status_lower: by_status[resolved] 1 elif close in status_lower: by_status[closed] 1 if critical in priority_lower: by_priority[critical] 1 critical_items.append(d) # 记录致命缺陷 elif major in priority_lower: by_priority[major] 1 elif minor in priority_lower: by_priority[minor] 1 # 这里可以添加更复杂的分析逻辑比如与上一版本对比 analysis_result { project_name: 你的项目名称, data: raw_data, generated_time: datetime.now().strftime(%Y-%m-%d %H:%M:%S), stats: { total: {total: total, passed: passed, failed: stats.get(failed, 0), skipped: stats.get(skipped, 0), pass_rate: pass_rate}, # 实际中需要根据原始数据拆分不同类型这里为示例简化 functional: {total: total, passed: passed, failed: stats.get(failed, 0), skipped: stats.get(skipped, 0), pass_rate: pass_rate}, api: {total: 0, passed: 0, failed: 0, skipped: 0, pass_rate: 0}, ui: {total: 0, passed: 0, failed: 0, skipped: 0, pass_rate: 0}, }, defects: { summary: { total: len(defects), by_status: by_status, by_priority: by_priority, }, critical_items: critical_items, }, env_info: { test_env: 测试环境-01, database: MySQL 8.0, build_number: 125, }, risks_assessment: 存在2个未解决的严重(Major)级别缺陷需在发布前确认修复方案。, release_recommendation: 建议在修复上述严重缺陷并完成验证后发布。 if by_priority[major] 0 else 当前未发现阻塞性问题建议按计划发布。 } return analysis_result app.post(/tools/analyze_and_generate_report) async def analyze_and_generate_report(request: AnalyzeRequest): 分析测试数据并生成报告Markdown草稿。 print(开始分析数据并生成报告草稿...) try: # 1. 数据分析 analyzed_data analyze_test_data(request.raw_data) # 2. 模板渲染 report_draft report_template.render(**analyzed_data) return {status: success, result: report_draft} except Exception as e: print(f报告生成失败: {e}) return {status: error, message: str(e)}4.2 让报告更智能LLM的润色与风险洞察在OpenClaw的技能配置中最后一步是让LLM对生成的报告草稿进行润色。这一步非常关键因为Jinja2模板生成的是结构化的“骨架”而LLM可以赋予它更流畅、更专业的语言甚至能基于数据做出一些简单的风险判断。OpenClaw在执行最后一步type: llm时会将上一步工具的结果{{ analyze_and_generate_report.result }}即报告草稿作为变量插入到Prompt中。LLM会根据我们设定的Prompt“请你以专业、简洁的口吻进行最终润色确保语句通顺重点突出...”来改写内容。这里的技巧在于Prompt设计角色设定明确告诉LLM“你是一个专业的测试报告生成助手”。任务明确不只是“润色”而是“确保语句通顺重点突出如阻塞性问题、风险项”。格式约束明确要求“输出格式为完整的Markdown文档”防止它输出无关内容。经过LLM润色后报告的可读性和专业性会大大提升。例如它可能会将模板中干巴巴的“本期共发现缺陷 5 个”改写为“在本测试周期内累计发现5个缺陷其中包含1个严重级别缺陷需予以关注。”5. 集成飞书让Skill在聊天场景中可用报告生成了最终要交付给用户。最自然的方式就是通过团队日常使用的协作工具比如飞书。我们需要让OpenClaw Skill能够接收飞书的指令并将最终报告发送回去。5.1 创建飞书机器人并配置事件订阅在飞书开放平台创建一个企业自建应用并添加“机器人”能力。配置“事件订阅”。重点配置两个事件im.message.receive_v1用于接收用户发给机器人的消息。请求地址Callback URL需要填写一个公网可访问的URL用于接收飞书的事件推送。开发阶段可以使用ngrok或localhost.run等工具将本地的服务暴露到公网。配置“权限管理”为机器人添加im:message接收与发送单聊、群组消息的权限。在OpenClaw的配置中我们需要一个额外的服务或在一个现有服务中增加端点来接收飞书的事件并转发给OpenClaw的Skill执行器。5.2 搭建消息转发网关我们在工具服务同级目录下创建一个新的FastAPI应用作为飞书消息网关 (feishu_gateway.py)from fastapi import FastAPI, Request, HTTPException import httpx import json import hashlib import base64 import hmac import os from datetime import datetime app FastAPI() # 飞书应用配置从环境变量读取 FEISHU_APP_ID os.getenv(FEISHU_APP_ID) FEISHU_APP_SECRET os.getenv(FEISHU_APP_SECRET) FEISHU_VERIFICATION_TOKEN os.getenv(FEISHU_VERIFICATION_TOKEN) # OpenClaw Skill执行器的内部地址假设和网关在同一网络 OPENCLAW_SKILL_URL http://openclaw:8001/api/run_skill # Docker容器间通信 # 获取飞书Tenant Access Token async def get_tenant_access_token(): url https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal payload {app_id: FEISHU_APP_ID, app_secret: FEISHU_APP_SECRET} async with httpx.AsyncClient() as client: resp await client.post(url, jsonpayload) resp.raise_for_status() data resp.json() return data.get(tenant_access_token) # 回复消息到飞书 async def reply_message(receive_id, msg_type, content): token await get_tenant_access_token() url https://open.feishu.cn/open-apis/im/v1/messages headers {Authorization: fBearer {token}, Content-Type: application/json} # 注意这里使用 receive_id 作为查询参数根据消息是私聊还是群聊receive_id可能是open_id, user_id, chat_id params {receive_id_type: open_id} # 根据实际情况调整 payload { receive_id: receive_id, msg_type: msg_type, content: json.dumps(content) } async with httpx.AsyncClient() as client: resp await client.post(url, headersheaders, paramsparams, jsonpayload) # 处理响应... # 验证飞书事件签名安全性必须 def verify_feishu_signature(timestamp, nonce, signature, body): key f{timestamp}\n{nonce}\n{body}.encode(utf-8) sign base64.b64encode(hmac.new(FEISHU_VERIFICATION_TOKEN.encode(utf-8), key, hashlib.sha256).digest()).decode(utf-8) return sign signature app.post(/feishu/event) async def handle_feishu_event(request: Request): # 1. 验证签名 timestamp request.headers.get(X-Lark-Request-Timestamp) nonce request.headers.get(X-Lark-Request-Nonce) signature request.headers.get(X-Lark-Signature) raw_body await request.body() if not verify_feishu_signature(timestamp, nonce, signature, raw_body.decode(utf-8)): raise HTTPException(status_code403, detailInvalid signature) event await request.json() # 2. 处理飞书验证请求首次配置Callback URL时 if event.get(type) url_verification: return {challenge: event.get(challenge)} # 3. 处理消息事件 if event.get(type) event_callback: e event.get(event, {}) if e.get(type) im.message.receive_v1: sender e.get(sender, {}) message e.get(message, {}) # 只处理文本消息并且是了机器人的消息或私聊 if message.get(message_type) text: content json.loads(message.get(content, {})) text content.get(text, ).strip() open_id sender.get(sender_id, {}).get(open_id) chat_id message.get(chat_id) # 判断是否触发生成报告的关键词 if any(keyword in text for keyword in [生成测试报告, test report]): # 先回复一个“正在处理”的提示 await reply_message(open_id, text, {text: 收到指令正在为您生成测试报告请稍候...}) # 4. 调用OpenClaw Skill # 这里需要解析用户消息中的版本/时间信息可以简单提取或让OpenClaw的LLM去问 # 简化处理直接将用户原话作为输入 async with httpx.AsyncClient() as client: skill_payload { skill_name: generate_test_report, user_input: text, context: {user_open_id: open_id, chat_id: chat_id} } try: skill_resp await client.post(OPENCLAW_SKILL_URL, jsonskill_payload, timeout60) skill_result skill_resp.json() final_report skill_result.get(output, 报告生成失败。) except Exception as e: final_report f调用报告生成技能时出错: {e} # 5. 将最终报告发回飞书 # 飞书消息有长度限制如果报告很长可以考虑先上传为文件再分享链接 if len(final_report) 20000: # 飞书文本消息长度限制 await reply_message(open_id, text, {text: final_report}) else: # 生成临时文件并上传的逻辑此处略 await reply_message(open_id, text, {text: 报告内容较长已生成文件请查收。}) return {ok: True}这个网关服务起到了“翻译官”的作用将飞书的消息协议“翻译”成OpenClaw能理解的Skill调用请求并将OpenClaw生成的结果“翻译”回飞书的消息格式。部署与联调要点将飞书网关、工具服务、OpenClaw核心服务都通过Docker Compose编排起来确保它们在同一网络内能相互通信。飞书的事件订阅URL填写网关服务的公网地址如https://your-ngrok-url.ngrok.io/feishu/event。在OpenClaw的配置中需要暴露一个API端点如/api/run_skill供网关调用。这通常需要修改或扩展OpenClaw的部署配置。6. 避坑指南与效能提升思考在整个搭建过程中我遇到了不少坑也总结出一些让这个Skill更稳定、更智能的经验。6.1 常见问题与解决方案OpenClaw调用工具超时或失败现象Skill执行卡在某个工具步骤最终报错。排查首先检查工具服务的日志看请求是否收到处理是否异常。其次检查OpenClaw配置中工具的URL是否正确网络是否连通。解决在工具函数中增加超时设置和重试机制。在OpenClaw的Skill步骤配置中也可以考虑增加timeout参数。确保所有服务在Docker Compose中定义了健康检查。LLM生成的内容格式混乱或偏离主题现象最终报告格式不是Markdown或者加入了大量无关的评论。排查检查Prompt的指令是否清晰。特别是最后一步润色的Prompt必须强调“输出格式为完整的Markdown文档”。解决使用更严格的系统提示词System Prompt来约束LLM的行为。例如在OpenClaw的模型配置或Skill的LLM步骤中可以加入“你是一个严谨的测试工程师只输出报告内容不要添加任何额外的解释或评论。”飞书消息无法触发或回复现象在飞书里机器人没反应。排查检查飞书开放平台应用是否发布机器人是否被添加到群里检查事件订阅的URL是否验证通过网关服务的日志是否有收到POST请求检查签名验证逻辑是否正确飞书服务器和你的网关服务器时间是否相差太大解决仔细核对飞书应用的App ID、Secret、Token。使用ngrok等工具时注意每次重启服务URL会变需要在飞书后台更新。在网关中详细打印接收到的头部和体信息用于调试。数据源API变更导致工具失效现象之前好用的Skill突然报“获取数据失败”。解决这是不可避免的。为每个工具函数编写完善的单元测试和集成测试定期运行。考虑在工具返回的数据结构中加入一个source_status字段标明每个数据源的获取状态成功、失败、部分成功让后续的分析步骤可以决定是降级处理还是直接报错。6.2 从“能用”到“好用”的进阶思路当前的Skill已经实现了基础功能但要真正融入工作流还可以从以下几个方面优化参数自动提取目前版本需要LLM主动询问版本和时间。可以更智能一点比如在飞书群里消息可能是“生成昨天上线那个版本的报告”。Skill可以结合对话上下文需要OpenClaw支持记忆或去查询最近的发布记录自动推断出版本号。支持多种输出格式除了Markdown可以集成python-docx库直接生成标准的Word (.docx) 报告或者用WeasyPrint生成PDF满足正式归档的需求。报告模板可配置化将Jinja2模板的路径甚至内容作为可配置项让不同项目组可以自定义自己的报告模板和数据分析逻辑。加入定时任务除了被动触发可以通过Cron Job定时比如每周五下午自动生成本周的测试报告并发送到指定群聊实现真正的自动化周报。与CI/CD流水线集成在Jenkins Pipeline的最后阶段调用这个Skill的API将本次构建的测试结果自动生成报告作为构建产物的一部分存档或发送给相关人员。搭建这样一个“自动写测试报告”的Skill初期投入确实需要一些时间但一旦跑通它带来的效率提升和体验改善是巨大的。它不仅仅是一个工具更是一个将AI能力与实际工作场景深度结合的实践。你会发现有了这个基础框架很多类似的文档自动化工作如生成发布说明、会议纪要整理、数据报表汇总都可以套用类似的思路来实现。
1. 项目缘起从“写报告”的重复劳动到“自动生成”的解放测试报告这玩意儿对于任何一个搞开发、做测试或者负责项目交付的同学来说都再熟悉不过了。每次版本迭代、功能上线或者仅仅是日常的回归测试最后都得产出这么一份文档。内容嘛大同小异测试概述、环境信息、执行结果、缺陷统计、风险与建议……格式固定但数据填充和文字组织却是个繁琐的体力活。尤其是当测试用例成百上千结果数据散落在不同平台比如Jira、TestRail、Jenkins的Allure报告时手动汇总、复制粘贴、再调整格式一两个小时就这么没了还容易出错。我最近就在琢磨这种高度结构化、数据驱动、流程固定的文档生成工作是不是可以彻底交给机器正好最近各种AI Agent和自动化工具比如OpenClaw、各类Skill框架炒得火热它们号称能理解意图、调用工具、执行复杂任务。那能不能自己动手打造一个专属的“自动写测试报告”的Skill呢这个Skill的核心目标很明确我给它一个指令比如“生成v2.1.0版本的测试报告”它就能自动去拉取测试数据、分析结果、组织内容最终生成一份格式规范、数据准确、甚至带有初步分析的Markdown或Word文档直接发到我的聊天窗口或者指定频道。这不仅仅是偷懒更是将测试人员从重复劳动中解放出来把精力聚焦在更有价值的测试设计、深度缺陷分析和质量风险评估上。下面我就把自己从零开始搭建这个“自动写测试报告Skill”的完整过程、技术选型、踩坑经验以及最终的实现方案毫无保留地分享出来。2. 核心架构设计让AI Agent成为你的报告助理要实现“自动写报告”我们不能把它想象成一个简单的脚本。脚本是死的流程是固定的。而一个真正的“Skill”应该具备一定的智能和灵活性能够理解相对模糊的指令并自主协调多个步骤来完成目标。这正符合当前AI Agent智能体的设计理念。因此我决定采用“AI Agent 工具调用Tool Calling”作为本项目的核心架构。简单来说这个Skill就是一个AI智能体它被赋予了“测试报告专家”的角色。它的工作流程可以分解为以下几个核心环节指令解析与任务规划用户说“生成上周的回归测试报告”。Agent需要理解这个指令并规划出完成任务所需的步骤例如确定时间范围、识别数据源、决定报告模板。数据获取与聚合根据规划Agent需要调用不同的“工具”Tools去获取原始数据。比如调用Jenkins API获取构建信息和Allure报告链接调用Jira API获取该周期内创建和关闭的缺陷调用测试管理工具API获取用例执行详情。数据分析与内容组织获取到原始数据通常是JSON格式后Agent需要进行分析和提炼。例如计算测试通过率、失败用例的分类统计、缺陷的严重等级分布、与上一版本的对比趋势等。然后按照预设的报告模板框架将分析结果组织成连贯的文字段落和图表描述。报告生成与交付将组织好的内容填充到最终的文档模板中如Markdown并可能调用文档生成工具如Pandoc转换为PDF或Word格式。最后将成品通过消息通道如飞书机器人、钉钉机器人、邮件发送给用户。在这个架构中AI Agent例如基于OpenAI GPT、Claude或开源模型如DeepSeek是大脑负责规划和决策而一系列封装好的工具函数是它的手脚负责执行具体的操作。我们所要做的就是为这个大脑定义清晰的职责并为它装备好所有必要的手脚。2.1 技术栈选型与思考市面上能构建AI Agent的框架和平台很多比如LangChain、LlamaIndex、CrewAI以及一些云服务商提供的AI应用开发平台。我的选型思路基于以下几点自主可控与成本希望部署在内部环境避免敏感测试数据外流同时控制长期使用成本。开发效率与灵活性框架要成熟社区活跃能快速集成各种工具和API。与现有生态结合我们内部使用飞书进行协作因此Skill最好能方便地接入飞书。基于这些考虑我选择了OpenClaw作为Agent运行框架。OpenClaw是一个开源的AI Agent框架它设计简洁专注于工具调用和任务规划非常适合构建这种单一职责但需要多步协作的Skill。它不像LangChain那样庞大学习曲线相对平缓且对国产模型如DeepSeek、GLM的支持也比较好。为什么是OpenClaw而不是直接写脚本如果只是固定流程写个Python脚本配合Cron定时任务当然可以。但“Skill”的想象空间更大。比如未来我可以对它说“对比一下v2.1.0和v2.0.0的测试稳定性重点分析接口响应时间的变化。”这种复杂的、需要理解对比维度和分析重点的指令纯脚本很难处理而基于LLM的Agent可以通过自然语言理解来拆解并尝试完成。OpenClaw提供了这种“规划-执行”的基础能力。其他关键组件大语言模型LLM作为Agent的“大脑”。我选择了DeepSeek-Coder的最新版本通过本地化部署的Ollama来调用。原因在于测试报告生成涉及一定的代码如处理JSON、逻辑推理如计算百分比、判断趋势和结构化输出DeepSeek-Coder在这方面的能力很强且对中文支持友好性价比高。工具库Tools用Python的FastAPI或Flask快速搭建一组API作为Agent可调用的工具。每个工具对应一个具体的获取或处理操作。消息平台集成使用飞书开放平台的机器人API让Skill能接收用户指令并发送报告。报告生成采用Jinja2模板引擎来定义Markdown报告模板数据填充后使用python-docx或WeasyPrint可转换为更正式的格式。3. 实战第一步搭建OpenClaw环境与定义核心工具理论说再多不如动手。第一步就是把OpenClaw跑起来并定义出第一个能用的工具。3.1 OpenClaw的本地部署与配置OpenClaw的安装其实很简单官方推荐使用Docker这对于保证环境一致性非常友好。# 1. 拉取OpenClaw的Docker镜像 docker pull openclaw/openclaw:latest # 2. 准备一个配置文件 config.yaml mkdir -p ~/openclaw-config cd ~/openclaw-config vim config.yamlconfig.yaml是OpenClaw的核心我们需要在这里配置LLM的接入点、工具列表以及Agent的基础设定。# config.yaml 示例 model: provider: ollama # 使用本地ollama服务 model: deepseek-coder:latest # 指定的模型名称 base_url: http://host.docker.internal:11434 # Docker容器内访问宿主机ollama的地址 # 技能Skill定义这里就是我们核心的“写报告”技能 skills: - name: generate_test_report description: 根据用户指定的版本或时间范围自动生成软件测试报告。 # 这个技能的触发指令用户输入中包含这些关键词即可触发 triggers: [生成测试报告, 写一份测试报告, test report] # 技能的具体执行流程由一系列步骤Step组成每个步骤可以调用工具或直接让LLM生成内容 steps: - type: llm prompt: | 你是一个专业的测试报告生成助手。用户要求生成测试报告。 请向用户询问清楚以下信息 1. 报告对应的项目或版本号例如v2.1.0。 2. 报告覆盖的时间范围例如2024-05-01至2024-05-10。如果用户未提供默认为最近7天。 3. 报告需要的详细程度概览/详细。 请以清晰、友好的方式一次性提出所有问题。 - type: tool tool_name: fetch_test_data # 上一步LLM收集到的参数会通过变量传递给工具 input_mapping: version: {{ version }} start_date: {{ start_date }} end_date: {{ end_date }} - type: tool tool_name: analyze_and_generate_report input_mapping: raw_data: {{ fetch_test_data.result }} - type: llm prompt: | 这是一份生成的测试报告草稿{{ analyze_and_generate_report.result }}。 请你以专业、简洁的口吻进行最终润色确保语句通顺重点突出如阻塞性问题、风险项。 输出格式为完整的Markdown文档。这个配置文件定义了一个名为generate_test_report的技能。当用户在飞书群里机器人并说“生成v2.1.0的测试报告”时就会触发这个技能。技能的执行分为四步1. 让LLM询问详情2. 调用工具获取数据3. 调用另一个工具分析并生成草稿4. 最后再让LLM润色输出。注意这里的host.docker.internal是Docker的一个特殊DNS指向宿主机。确保你的宿主机上已经运行了Ollama服务ollama run deepseek-coder:latest并且端口11434可访问。3.2 开发第一个核心工具获取测试数据工具Tool本质上是一个HTTP接口OpenClaw会向这个接口发送POST请求来调用它。我们需要用Python这里用FastAPI为例来实现fetch_test_data这个工具。首先创建一个工具服务项目mkdir test-report-tools cd test-report-tools python -m venv venv source venv/bin/activate pip install fastapi uvicorn requests pydantic创建tools_server.pyfrom fastapi import FastAPI, HTTPException from pydantic import BaseModel from datetime import datetime import requests import json app FastAPI(title测试报告工具服务) # 定义工具接收的参数模型 class FetchDataRequest(BaseModel): version: str start_date: str end_date: str # 模拟从Jenkins API获取Allure报告摘要 def get_jenkins_allure_summary(build_id): # 这里替换成你真实的Jenkins API URL和认证信息 jenkins_url fhttp://your-jenkins/job/your-project/{build_id}/allure/api/report auth (username, api_token) try: response requests.get(jenkins_url, authauth, timeout10) response.raise_for_status() return response.json() # 假设返回包含statistics, suites等信息的JSON except requests.RequestException as e: print(f获取Jenkins数据失败: {e}) return {statistics: {total: 0, passed: 0, failed: 0, skipped: 0}} # 模拟从Jira API获取缺陷数据 def get_jira_issues(version, start_date, end_date): jql fproject YOURPROJECT AND fixVersion {version} AND created {start_date} AND created {end_date} jira_url https://your-jira.atlassian.net/rest/api/3/search headers {Authorization: Bearer YOUR_JIRA_TOKEN} params {jql: jql, maxResults: 100} try: response requests.get(jira_url, headersheaders, paramsparams, timeout10) response.raise_for_status() issues response.json().get(issues, []) # 简化处理只提取关键信息 defect_list [] for issue in issues: key issue.get(key) summary issue.get(fields, {}).get(summary, ) status issue.get(fields, {}).get(status, {}).get(name, ) priority issue.get(fields, {}).get(priority, {}).get(name, ) defect_list.append({key: key, summary: summary, status: status, priority: priority}) return defect_list except requests.RequestException as e: print(f获取Jira数据失败: {e}) return [] # 工具端点/tools/fetch_test_data app.post(/tools/fetch_test_data) async def fetch_test_data(request: FetchDataRequest): 根据版本和时间范围从各个数据源获取测试原始数据。 print(f开始获取数据: version{request.version}, start{request.start_date}, end{request.end_date}) # 1. 获取构建信息和测试统计这里需要根据版本号映射到具体的Jenkins构建ID简化处理 # 假设我们有一个简单的映射关系或通过查询API获得 build_id resolve_build_id(request.version) # 这是一个需要你实现的函数 jenkins_data get_jenkins_allure_summary(build_id) # 2. 获取缺陷数据 jira_data get_jira_issues(request.version, request.start_date, request.end_date) # 3. 聚合数据 aggregated_data { version: request.version, period: f{request.start_date} 至 {request.end_date}, test_summary: jenkins_data.get(statistics, {}), defects: jira_data, fetch_time: datetime.now().isoformat() } return {status: success, result: aggregated_data} def resolve_build_id(version: str) - str: # 示例简单映射实际中可能需要查询Jenkins API或维护一个映射表 mapping {v2.1.0: 125, v2.0.0: 118} return mapping.get(version, lastSuccessfulBuild) # 默认返回最后一次成功构建 if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)这个工具服务启动在8000端口。它提供了一个/tools/fetch_test_data的API。当OpenClaw的Agent执行到相应步骤时就会向这个地址发送POST请求并附上版本号、起止日期等参数。工具服务负责与真实的Jenkins、Jira等系统交互将分散的数据聚合到一个JSON对象中返回。关键点与踩坑记录认证与安全所有对内部系统的API调用都需要妥善处理认证信息如API Token、用户名密码。绝对不要将硬编码的密钥提交到代码仓库。务必使用环境变量或配置文件来管理并在Docker运行时注入。错误处理网络请求可能失败API格式可能变化。工具函数中必须有完善的异常捕获和日志记录并返回一个结构化的错误信息或降级数据如返回空列表或零值避免因为一个数据源挂掉导致整个Skill崩溃。数据映射resolve_build_id函数是关键。在实际项目中版本号与Jenkins构建号往往不是简单映射。你可能需要调用Jenkins API根据构建描述或参数化构建的版本来动态查找对应的构建ID。这里简化处理了。4. 实现报告生成与内容编排逻辑拿到聚合的原始数据后下一步就是分析和生成报告草稿。我们创建第二个工具analyze_and_generate_report。4.1 数据分析与报告模板引擎这个工具的任务更偏重逻辑处理。它接收fetch_test_data返回的原始数据进行计算、分析并填充到Jinja2模板中。首先安装Jinja2pip install Jinja2。创建report_template.md.j2# {{ project_name }} 测试报告 ({{ data.version }}) **报告周期**: {{ data.period }} **生成时间**: {{ generated_time }} ## 一、测试概述 本次测试针对 **{{ data.version }}** 版本覆盖了{{ data.period }}期间的所有测试活动。主要进行了功能回归、接口自动化及核心场景的验证。 ## 二、测试环境 * **测试环境**: {{ env_info.test_env }} * **数据库**: {{ env_info.database }} * **构建号**: {{ env_info.build_number }} ## 三、测试执行情况 ### 3.1 用例执行统计 | 测试类型 | 用例总数 | 通过数 | 失败数 | 跳过数 | **通过率** | | :--- | :---: | :---: | :---: | :---: | :---: | | 功能测试 | {{ stats.functional.total }} | {{ stats.functional.passed }} | {{ stats.functional.failed }} | {{ stats.functional.skipped }} | **{{ stats.functional.pass_rate }}%** | | 接口测试 | {{ stats.api.total }} | {{ stats.api.passed }} | {{ stats.api.failed }} | {{ stats.api.skipped }} | **{{ stats.api.pass_rate }}%** | | UI自动化 | {{ stats.ui.total }} | {{ stats.ui.passed }} | {{ stats.ui.failed }} | {{ stats.ui.skipped }} | **{{ stats.ui.pass_rate }}%** | | **合计** | **{{ stats.total.total }}** | **{{ stats.total.passed }}** | **{{ stats.total.failed }}** | **{{ stats.total.skipped }}** | **{{ stats.total.pass_rate }}%** | ### 3.2 缺陷统计与分析 本期共发现缺陷 **{{ defects.summary.total }}** 个。 * **按状态分布** * 待处理 (Open): {{ defects.summary.by_status.open }} * 处理中 (In Progress): {{ defects.summary.by_status.in_progress }} * 已解决 (Resolved): {{ defects.summary.by_status.resolved }} * 已关闭 (Closed): {{ defects.summary.by_status.closed }} * **按优先级分布** * 致命 (Critical): {{ defects.summary.by_priority.critical }} * 严重 (Major): {{ defects.summary.by_priority.major }} * 一般 (Minor): {{ defects.summary.by_priority.minor }} **重点关注缺陷**: {% if defects.critical_items %} {% for item in defects.critical_items %} * **[{{ item.key }}]** {{ item.summary }} (状态: {{ item.status }}, 优先级: {{ item.priority }}) {% endfor %} {% else %} * 本期未发现致命(Critical)级别缺陷。 {% endif %} ## 四、测试结论与风险 1. **质量评估**: 整体通过率为 **{{ stats.total.pass_rate }}%**{% if stats.total.pass_rate 95 %}达到发布标准。{% else %}未达到95%的发布标准需重点关注失败用例。{% endif %} 2. **主要风险**: {{ risks_assessment }}。 3. **发布建议**: {{ release_recommendation }}。 ## 五、附录 * 详细测试用例执行记录: [链接] * Allure测试报告: [链接] * Jira缺陷列表: [链接]然后在工具服务中添加新的端点和处理逻辑# 在 tools_server.py 中添加 from jinja2 import Environment, FileSystemLoader import os # 初始化Jinja2环境 env Environment(loaderFileSystemLoader(.), trim_blocksTrue, lstrip_blocksTrue) report_template env.get_template(report_template.md.j2) class AnalyzeRequest(BaseModel): raw_data: dict def analyze_test_data(raw_data: dict): 分析原始数据生成用于模板填充的结构化数据 stats raw_data.get(test_summary, {}) # 计算通过率等衍生数据 total stats.get(total, 0) passed stats.get(passed, 0) pass_rate round((passed / total * 100), 2) if total 0 else 0.0 # 对缺陷数据进行分类统计 defects raw_data.get(defects, []) by_status {open: 0, in_progress: 0, resolved: 0, closed: 0} by_priority {critical: 0, major: 0, minor: 0} critical_items [] for d in defects: status_lower d.get(status, ).lower() priority_lower d.get(priority, ).lower() if open in status_lower: by_status[open] 1 elif progress in status_lower: by_status[in_progress] 1 elif resolve in status_lower: by_status[resolved] 1 elif close in status_lower: by_status[closed] 1 if critical in priority_lower: by_priority[critical] 1 critical_items.append(d) # 记录致命缺陷 elif major in priority_lower: by_priority[major] 1 elif minor in priority_lower: by_priority[minor] 1 # 这里可以添加更复杂的分析逻辑比如与上一版本对比 analysis_result { project_name: 你的项目名称, data: raw_data, generated_time: datetime.now().strftime(%Y-%m-%d %H:%M:%S), stats: { total: {total: total, passed: passed, failed: stats.get(failed, 0), skipped: stats.get(skipped, 0), pass_rate: pass_rate}, # 实际中需要根据原始数据拆分不同类型这里为示例简化 functional: {total: total, passed: passed, failed: stats.get(failed, 0), skipped: stats.get(skipped, 0), pass_rate: pass_rate}, api: {total: 0, passed: 0, failed: 0, skipped: 0, pass_rate: 0}, ui: {total: 0, passed: 0, failed: 0, skipped: 0, pass_rate: 0}, }, defects: { summary: { total: len(defects), by_status: by_status, by_priority: by_priority, }, critical_items: critical_items, }, env_info: { test_env: 测试环境-01, database: MySQL 8.0, build_number: 125, }, risks_assessment: 存在2个未解决的严重(Major)级别缺陷需在发布前确认修复方案。, release_recommendation: 建议在修复上述严重缺陷并完成验证后发布。 if by_priority[major] 0 else 当前未发现阻塞性问题建议按计划发布。 } return analysis_result app.post(/tools/analyze_and_generate_report) async def analyze_and_generate_report(request: AnalyzeRequest): 分析测试数据并生成报告Markdown草稿。 print(开始分析数据并生成报告草稿...) try: # 1. 数据分析 analyzed_data analyze_test_data(request.raw_data) # 2. 模板渲染 report_draft report_template.render(**analyzed_data) return {status: success, result: report_draft} except Exception as e: print(f报告生成失败: {e}) return {status: error, message: str(e)}4.2 让报告更智能LLM的润色与风险洞察在OpenClaw的技能配置中最后一步是让LLM对生成的报告草稿进行润色。这一步非常关键因为Jinja2模板生成的是结构化的“骨架”而LLM可以赋予它更流畅、更专业的语言甚至能基于数据做出一些简单的风险判断。OpenClaw在执行最后一步type: llm时会将上一步工具的结果{{ analyze_and_generate_report.result }}即报告草稿作为变量插入到Prompt中。LLM会根据我们设定的Prompt“请你以专业、简洁的口吻进行最终润色确保语句通顺重点突出...”来改写内容。这里的技巧在于Prompt设计角色设定明确告诉LLM“你是一个专业的测试报告生成助手”。任务明确不只是“润色”而是“确保语句通顺重点突出如阻塞性问题、风险项”。格式约束明确要求“输出格式为完整的Markdown文档”防止它输出无关内容。经过LLM润色后报告的可读性和专业性会大大提升。例如它可能会将模板中干巴巴的“本期共发现缺陷 5 个”改写为“在本测试周期内累计发现5个缺陷其中包含1个严重级别缺陷需予以关注。”5. 集成飞书让Skill在聊天场景中可用报告生成了最终要交付给用户。最自然的方式就是通过团队日常使用的协作工具比如飞书。我们需要让OpenClaw Skill能够接收飞书的指令并将最终报告发送回去。5.1 创建飞书机器人并配置事件订阅在飞书开放平台创建一个企业自建应用并添加“机器人”能力。配置“事件订阅”。重点配置两个事件im.message.receive_v1用于接收用户发给机器人的消息。请求地址Callback URL需要填写一个公网可访问的URL用于接收飞书的事件推送。开发阶段可以使用ngrok或localhost.run等工具将本地的服务暴露到公网。配置“权限管理”为机器人添加im:message接收与发送单聊、群组消息的权限。在OpenClaw的配置中我们需要一个额外的服务或在一个现有服务中增加端点来接收飞书的事件并转发给OpenClaw的Skill执行器。5.2 搭建消息转发网关我们在工具服务同级目录下创建一个新的FastAPI应用作为飞书消息网关 (feishu_gateway.py)from fastapi import FastAPI, Request, HTTPException import httpx import json import hashlib import base64 import hmac import os from datetime import datetime app FastAPI() # 飞书应用配置从环境变量读取 FEISHU_APP_ID os.getenv(FEISHU_APP_ID) FEISHU_APP_SECRET os.getenv(FEISHU_APP_SECRET) FEISHU_VERIFICATION_TOKEN os.getenv(FEISHU_VERIFICATION_TOKEN) # OpenClaw Skill执行器的内部地址假设和网关在同一网络 OPENCLAW_SKILL_URL http://openclaw:8001/api/run_skill # Docker容器间通信 # 获取飞书Tenant Access Token async def get_tenant_access_token(): url https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal payload {app_id: FEISHU_APP_ID, app_secret: FEISHU_APP_SECRET} async with httpx.AsyncClient() as client: resp await client.post(url, jsonpayload) resp.raise_for_status() data resp.json() return data.get(tenant_access_token) # 回复消息到飞书 async def reply_message(receive_id, msg_type, content): token await get_tenant_access_token() url https://open.feishu.cn/open-apis/im/v1/messages headers {Authorization: fBearer {token}, Content-Type: application/json} # 注意这里使用 receive_id 作为查询参数根据消息是私聊还是群聊receive_id可能是open_id, user_id, chat_id params {receive_id_type: open_id} # 根据实际情况调整 payload { receive_id: receive_id, msg_type: msg_type, content: json.dumps(content) } async with httpx.AsyncClient() as client: resp await client.post(url, headersheaders, paramsparams, jsonpayload) # 处理响应... # 验证飞书事件签名安全性必须 def verify_feishu_signature(timestamp, nonce, signature, body): key f{timestamp}\n{nonce}\n{body}.encode(utf-8) sign base64.b64encode(hmac.new(FEISHU_VERIFICATION_TOKEN.encode(utf-8), key, hashlib.sha256).digest()).decode(utf-8) return sign signature app.post(/feishu/event) async def handle_feishu_event(request: Request): # 1. 验证签名 timestamp request.headers.get(X-Lark-Request-Timestamp) nonce request.headers.get(X-Lark-Request-Nonce) signature request.headers.get(X-Lark-Signature) raw_body await request.body() if not verify_feishu_signature(timestamp, nonce, signature, raw_body.decode(utf-8)): raise HTTPException(status_code403, detailInvalid signature) event await request.json() # 2. 处理飞书验证请求首次配置Callback URL时 if event.get(type) url_verification: return {challenge: event.get(challenge)} # 3. 处理消息事件 if event.get(type) event_callback: e event.get(event, {}) if e.get(type) im.message.receive_v1: sender e.get(sender, {}) message e.get(message, {}) # 只处理文本消息并且是了机器人的消息或私聊 if message.get(message_type) text: content json.loads(message.get(content, {})) text content.get(text, ).strip() open_id sender.get(sender_id, {}).get(open_id) chat_id message.get(chat_id) # 判断是否触发生成报告的关键词 if any(keyword in text for keyword in [生成测试报告, test report]): # 先回复一个“正在处理”的提示 await reply_message(open_id, text, {text: 收到指令正在为您生成测试报告请稍候...}) # 4. 调用OpenClaw Skill # 这里需要解析用户消息中的版本/时间信息可以简单提取或让OpenClaw的LLM去问 # 简化处理直接将用户原话作为输入 async with httpx.AsyncClient() as client: skill_payload { skill_name: generate_test_report, user_input: text, context: {user_open_id: open_id, chat_id: chat_id} } try: skill_resp await client.post(OPENCLAW_SKILL_URL, jsonskill_payload, timeout60) skill_result skill_resp.json() final_report skill_result.get(output, 报告生成失败。) except Exception as e: final_report f调用报告生成技能时出错: {e} # 5. 将最终报告发回飞书 # 飞书消息有长度限制如果报告很长可以考虑先上传为文件再分享链接 if len(final_report) 20000: # 飞书文本消息长度限制 await reply_message(open_id, text, {text: final_report}) else: # 生成临时文件并上传的逻辑此处略 await reply_message(open_id, text, {text: 报告内容较长已生成文件请查收。}) return {ok: True}这个网关服务起到了“翻译官”的作用将飞书的消息协议“翻译”成OpenClaw能理解的Skill调用请求并将OpenClaw生成的结果“翻译”回飞书的消息格式。部署与联调要点将飞书网关、工具服务、OpenClaw核心服务都通过Docker Compose编排起来确保它们在同一网络内能相互通信。飞书的事件订阅URL填写网关服务的公网地址如https://your-ngrok-url.ngrok.io/feishu/event。在OpenClaw的配置中需要暴露一个API端点如/api/run_skill供网关调用。这通常需要修改或扩展OpenClaw的部署配置。6. 避坑指南与效能提升思考在整个搭建过程中我遇到了不少坑也总结出一些让这个Skill更稳定、更智能的经验。6.1 常见问题与解决方案OpenClaw调用工具超时或失败现象Skill执行卡在某个工具步骤最终报错。排查首先检查工具服务的日志看请求是否收到处理是否异常。其次检查OpenClaw配置中工具的URL是否正确网络是否连通。解决在工具函数中增加超时设置和重试机制。在OpenClaw的Skill步骤配置中也可以考虑增加timeout参数。确保所有服务在Docker Compose中定义了健康检查。LLM生成的内容格式混乱或偏离主题现象最终报告格式不是Markdown或者加入了大量无关的评论。排查检查Prompt的指令是否清晰。特别是最后一步润色的Prompt必须强调“输出格式为完整的Markdown文档”。解决使用更严格的系统提示词System Prompt来约束LLM的行为。例如在OpenClaw的模型配置或Skill的LLM步骤中可以加入“你是一个严谨的测试工程师只输出报告内容不要添加任何额外的解释或评论。”飞书消息无法触发或回复现象在飞书里机器人没反应。排查检查飞书开放平台应用是否发布机器人是否被添加到群里检查事件订阅的URL是否验证通过网关服务的日志是否有收到POST请求检查签名验证逻辑是否正确飞书服务器和你的网关服务器时间是否相差太大解决仔细核对飞书应用的App ID、Secret、Token。使用ngrok等工具时注意每次重启服务URL会变需要在飞书后台更新。在网关中详细打印接收到的头部和体信息用于调试。数据源API变更导致工具失效现象之前好用的Skill突然报“获取数据失败”。解决这是不可避免的。为每个工具函数编写完善的单元测试和集成测试定期运行。考虑在工具返回的数据结构中加入一个source_status字段标明每个数据源的获取状态成功、失败、部分成功让后续的分析步骤可以决定是降级处理还是直接报错。6.2 从“能用”到“好用”的进阶思路当前的Skill已经实现了基础功能但要真正融入工作流还可以从以下几个方面优化参数自动提取目前版本需要LLM主动询问版本和时间。可以更智能一点比如在飞书群里消息可能是“生成昨天上线那个版本的报告”。Skill可以结合对话上下文需要OpenClaw支持记忆或去查询最近的发布记录自动推断出版本号。支持多种输出格式除了Markdown可以集成python-docx库直接生成标准的Word (.docx) 报告或者用WeasyPrint生成PDF满足正式归档的需求。报告模板可配置化将Jinja2模板的路径甚至内容作为可配置项让不同项目组可以自定义自己的报告模板和数据分析逻辑。加入定时任务除了被动触发可以通过Cron Job定时比如每周五下午自动生成本周的测试报告并发送到指定群聊实现真正的自动化周报。与CI/CD流水线集成在Jenkins Pipeline的最后阶段调用这个Skill的API将本次构建的测试结果自动生成报告作为构建产物的一部分存档或发送给相关人员。搭建这样一个“自动写测试报告”的Skill初期投入确实需要一些时间但一旦跑通它带来的效率提升和体验改善是巨大的。它不仅仅是一个工具更是一个将AI能力与实际工作场景深度结合的实践。你会发现有了这个基础框架很多类似的文档自动化工作如生成发布说明、会议纪要整理、数据报表汇总都可以套用类似的思路来实现。
