企业官网建设流程全解析

“元仔，查一下明天上海的天气。”一句很短的请求，程序却要回答几个具体问题：查哪座城市，哪一天，数据从哪里取，又怎样让机器人读出来？

启元官方公开的weather_forecast项目，把这件事拆成了一段可以读懂的程序。它适合用来认识机器人开发中的三个概念：Skill 组织一项任务，API 交换数据，设备接口把结果交给机器人。我们沿着这份代码走一遍，再用真实查询看看它做到了哪一步。

1. Skill 把“一件事”组织成可调用的程序

在 PrimeHub 中，天气预报与视频电话等应用以卡片形式展示。对使用者，卡片回答“有什么功能”；对开发者，还要进入项目，查看它接收什么输入、依赖什么服务、怎样调用设备。

图1｜启元 PrimeHub 的公开技能目录。天气预报是其中一项应用，页面还提供机型与功能分类。来源：PrimeHub。

这份官方天气项目的结构很小，却已经具备分工：

项目配置的版本是1.0.0，其中sdk_version写为v1.0.0。本文核对的提交是1584404d，文末配套程序会固定完整提交，避免后来代码更新导致结果对不上。官方配置文件

可以把 Skill 理解为围绕一项任务整理好的应用代码。天气查询不必负责所有机器人能力：它组织查询流程，语音能力则通过robot.play_tts()调用。这里的 TTS 是 Text-to-Speech，即把文字转换为语音。

图2｜启元官方天气项目的仓库说明，介绍了预报查询、默认城市和语音输出用途。来源：AtomGit 启元组织。

2. 一句查询，先变成城市和日期

这份示例从已经到达入口的文字开始处理。main.py读取环境变量ROBOT_SKILL_QUERY，再把内容交给天气函数；它本身没有实现录音、语音识别或自动选择技能的流程。入口里的robot对象也预期由外部运行环境提供。官方入口代码

接下来发生的事并不复杂。程序找到“明天”，记下日期偏移为1；删除“元仔”“查一下”“天气”等预设词和标点，剩下“上海”。如果城市部分为空，则使用默认城市上海。“今天、明天、后天”分别对应偏移0、1、2。官方处理代码

图3｜查询在 Skill、外部天气服务和运行环境之间流动。实线表示代码中可核对的处理与请求，右侧标出文本交给播报方法的位置。依据官方源码绘制。

这种规则容易理解，也有明确范围。本次运行中，“北京后天会不会下雨”被解析为北京、偏移2；“今天天气怎么样”采用默认城市上海。但多加几个词，说成“请帮我看看明天上海天气”，程序留下的城市却是“请帮我上海”。

这不是网络请求的问题，而是输入尚未被正确整理。示例使用的是预设规则，未在这一步调用大模型。继续开发时，可以先扩充解析规则，或者在上游把多样的表达转换成明确的城市和日期；无论用哪种方法，都应检查转换后的参数。

3. API 把城市名称换成有日期的数据

API 可以理解为程序之间约定好的问答方式：一方按格式提交参数，另一方按格式返回结果。在天气项目里，正常查询包含两次外部请求。

第一次向 Open-Meteo 的地理编码服务提交城市名称，取得经纬度。地理编码解决的是“这个名字在地图上的哪里”。代码设置count=1，取第一条结果；本次“上海”返回的坐标为北纬31.22222、东经121.45806。若用于更多城市，同名地名需要进一步辨认，不能把第一条匹配永远视为正确选择。Open-Meteo 地理编码文档

第二次用坐标查询天气。程序请求三天的数据，按城市所在时区确定日期，并取出天气代码、日最高气温、日最低气温和日内最高降水概率。代码中的forecast_days=3对应示例支持的今天、明天、后天；timezone=auto让服务根据坐标确定时区。官方预报接口文档

返回的数据采用 JSON 格式，可以看成按名字组织字段的文本。程序无需从一句长答案里猜气温在哪，而是直接读取指定字段。本次实际请求发生在北京时间2026年10月23日15:19，取出的“明天”为2026年10月24日：最低气温19.3℃、最高气温21.6℃，天气代码82，日内最高降水概率100%。

随后，代码把82映射为“强阵雨”，对气温取整，生成：“上海明天强阵雨，19到22度，最高降雨概率100%。”这是当时服务返回的预报，经程序加工得到的待播报文本；它不是机器人自身测量的天气，也不是预报准确率测试。原始响应与时间记录保存在配套项目中，稍后重新查询可能变化。

这个例子也说明了字段解释的重要性。19到22度来自一天的最低和最高预报气温，不能当作当前温度；最高降水概率是概率字段，不代表雨量或一天下雨的时间占比。机器人能读出一个数字之前，应用作者先要读懂这个数字。

4. 有了文字，还要把任务交给语音接口

天气函数最后执行robot.play_tts()，把生成的文字交出去。它使用了设备能力，却没有在天气程序里重新编写语音合成系统。SDK 是软件开发工具包，为应用提供调用设备能力所需的接口和配套资料。Skill 决定这项任务怎么做，SDK 则帮助开发者使用机器人已有的能力。

启元 Q1 SDK 的接口说明中，公开了PlayTts语音服务。其响应包含成功状态和错误信息，文档明确写到：成功状态表示请求进入调度队列，不代表整段语音已经播放完毕。这类区别在机器人开发中很常见：请求已经提交、设备已经接受、动作已经完成，是不同阶段。

天气仓库使用的robot.play_tts()与 SDK 服务之间的具体适配实现，没有在这两个项目中展开，不能仅凭名称就断定内部调用细节。能够直接核对的是：天气程序交付文本，SDK提供语音能力的接口说明，实际设备效果还需要相应运行环境确认。

图4｜启元官方对 PrimeConsole 的功能介绍，包括连接与日志、语音与运动控制等调试入口。来源：启元开发资料页。

排查时也可以沿着任务顺序走：城市是否提取正确，天气服务有没有返回，文本是否生成，最后再检查播报请求和设备状态。天气程序对异常提供了“天气服务暂时不可用，请稍后再试”的提示，但提示本身仍需经过语音接口，不能保证任何故障下都有声音。

5. 在电脑上验证查询，先看清数据怎样流动

配套项目提供了一个独立核验程序，实际验证环境为Python 3.12.14、Git 2.50.1、macOS。程序只使用 Python 标准库，自动取得固定版本的官方天气文件并校验其摘要，不需要安装机器人 SDK。

准备好 Python 3.10及以上版本和 Git 后，在终端完整执行下面三条命令：

gitclone https://atomgit.com/xiongwenhao888/primebot-weather-skill-explained.gitcdprimebot-weather-skill-explained python3 inspect_weather.py--live--outevidence/live-run

这次核验先跑四条输入：前三条观察常用表达，第四条复现前文的解析局限。接着，它沿用官方程序的请求参数访问真实天气服务，保存两次响应、目标日期与最终文本。本次两次请求均返回 HTTP 200，程序退出码为0。

图5｜本次执行结果。可以对应查看输入解析、两次 HTTP 200、预报日期和待播报文字；第四条输入显示了规则解析的边界。

本次验证到的是输入解析、真实查询和文本生成，没有连接机器人或调用播报方法。读者运行后，可在evidence/live-run/report.json查看汇总，在两个http-*.json文件中查看服务原始返回。这样能够分别判断“数据查对了没有”和“文本整理对了没有”；接入设备后，再继续确认播报环节。

天气 Skill 展示了一种清楚的开发方法：先把任务拆成有输入、有输出的步骤，再通过接口连接外部数据和机器人能力。开发者可以从这些范围明确的小功能开始，留下版本和运行记录，逐步扩展自己的应用。

本文的核验代码、原创图源文件和运行证据均在配套 AtomGit 项目中。更多官方资源与社区项目，可从启元机器人开发者社区及其开发资料页继续查阅。

AtomGitx启元机器人具身智能原创内容征文活动#