QVeris · 产品实践很多工具演示站的问题不是页面不够漂亮而是只能看不能真正使用。用户看到一张精致的仪表盘却不知道数据从哪里来、工具如何选择、失败时又会发生什么。这次我们尝试把演示往前推进一步让 Codex Sites 负责网站生成让 QVeris 负责能力发现和工具调用做一个可以查询城市天气、空气质量和未来预报的交互式网站。页面只是结果真正值得展示的是一条完整的调用链路。本文当前为持续更新稿。演示网站生成后将补充实际访问地址、桌面端与移动端截图以及真实调用结果。01一、为什么要做这样一个演示站网站不只是工具说明书传统的 API 文档适合开发者查参数却很难让第一次接触产品的人迅速理解一种能力能解决什么问题。一个能直接操作的网站可以把搜索、调用、返回、异常处理和可视化放在同一条体验路径里。对 QVeris 来说这种演示尤其重要。QVeris 不是一个固定接口集合而是面向 Agent 的能力发现与工具调用引擎。用户提出需求后系统先找到适合的工具再根据工具的真实参数执行调用。演示站因此不能只写死一份假数据也不应该把某个 tool_id 永久固定在前端。为什么先从天气和空气质量开始天气类数据有几个天然优势任何人都能理解当前天气、逐小时趋势、未来预报和空气质量适合不同的可视化形式城市名称、经纬度、时区和多数据源又足以覆盖真实工具调用中常见的参数适配问题。用户在页面里输入北京看似只是一次搜索背后可能需要先做城市地理编码再调用当前天气、未来预报和空气质量工具。几个能力可以独立成功或失败这比只展示一个接口更接近 Agent 使用工具的真实情况。二、Codex Sites 与 QVeris 如何配合Codex Sites 负责把需求变成产品界面Codex Sites 接收的不是一句做个天气网站而是一份接近产品需求文档的指令。指令需要明确页面结构、交互状态、响应式布局、数据模型、安全边界、错误处理和验收条件。要求越具体最终生成的网站越接近一个可以继续开发的产品而不是只能展示的页面样稿。QVeris 负责动态发现和调用工具网站服务端先向 QVeris 描述所需能力例如 weather forecast current conditions API。QVeris 返回候选工具和参数定义服务端再根据成功率、参数完整度、执行耗时和数据结构选择合适的工具。选定工具后服务端携带 discover 返回的 search_id 执行工具并把不同来源的数据整理成网站统一的数据模型。浏览器只接收天气数据和脱敏后的调用摘要不接触 QVERIS_API_KEY也看不到 Authorization Header。这条链路解决了什么问题·网站不依赖一个写死的工具可以在候选工具异常时切换。·前端不需要理解每个供应商完全不同的字段结构。·用户能看到实际使用的工具、执行耗时和数据更新时间。·凭证只存在于服务端避免因演示站公开而泄露。·同一套模式可以继续扩展到金融、体育、新闻、科研、地图等其他工具类别。三、交给 Codex Sites 的完整 Prompt下面是本次网站生成使用的完整指令。它不仅描述视觉风格也规定了 QVeris 的接入方式、数据模型、缓存策略、错误状态和验收标准可以直接粘贴到 Codex Sites 插件中使用。Codex Sites 完整生成指令请生成一个完整、可运行、响应式的网站名称为「城市气象观察站 / City Weather Lab」网站用途演示如何使用 QVeris 发现并调用天气、空气质量、地理编码等工具。网站不是产品宣传页打开后直接进入可操作的数据看板。一、技术要求1.使用 React TypeScript。2.使用 Tailwind CSS。3.图标使用 Lucide不要手绘 SVG。4.图表使用 Recharts 或 ECharts。5.必须支持桌面端和移动端。6.不要把 QVERIS_API_KEY 写入前端代码或 Git 仓库。7.使用服务端 API Route 代理 QVeris 请求从环境变量读取 QVERIS_API_KEY。8.提供 .env.example其中只包含 QVERIS_API_KEY 。9.如果当前 Sites 环境不支持服务端 API Route保留完整的 API 客户端接口默认进入明确标记的 Demo 数据模式不允许在公开前端中硬编码真实 API Key。二、QVeris 接入方式QVeris API Base URLhttps://qveris.ai/api/v1所有服务端请求携带Authorization: Bearer ${QVERIS_API_KEY} 和 Content-Type: application/json。不要硬编码具体 tool_id。首次调用某项能力时通过 QVeris 动态发现工具并在本次服务端会话中缓存选中的 tool_id。工具发现接口POST /search需要分别发现以下能力当前天气、未来天气预报、空气质量、城市地理编码。发现后根据以下规则选择工具参数能支持城市名、经纬度或标准地点success_rate 优先高于 90%参数描述清楚且有样例参数平均响应时间较短返回结果包含结构化数据不要仅根据搜索结果排序盲目选择。执行工具接口POST /tools/execute?tool_idtool_id注意必须读取发现结果中的真实参数定义不要假设所有天气工具都使用 city 参数根据工具参数动态构造调用参数API 返回结构不一致时在服务端转换成统一数据模型请求失败时尝试修正参数仍失败则切换到下一个候选工具不得把完整 Authorization Header、API Key 或敏感错误信息返回浏览器。三、核心页面页面打开后直接显示数据看板不要制作营销落地页或巨大 Hero。整体布局顶部应用栏、左侧城市列表、中间天气数据区域、右侧空气质量和工具调用状态移动端改为单列布局城市列表使用抽屉。四、主要功能1.城市搜索支持北京、上海、新加坡、Tokyo、London、New York。如果天气工具不支持城市名称先调用地理编码工具。2.当前天气显示城市和当地时间、天气状况、当前温度、体感温度、最高最低温度、湿度、风速风向、降水概率、能见度、气压、紫外线指数、数据更新时间。3.未来预报显示未来 7 天数据同时提供卡片视图、温度趋势图和降水概率图。移动端图表宽度必须适配屏幕。4.24 小时趋势使用折线图展示温度、体感温度、降水概率可通过分段控件切换指标。5.空气质量显示 AQI、空气质量等级、PM2.5、PM10、CO、NO2、SO2、O3。根据 AQI 使用语义颜色并显示一句简洁的活动建议。6.城市对比最多选择 4 个城市进行温度和空气质量对比使用表格和柱状图展示。7.收藏城市默认提供北京、上海、新加坡、东京、伦敦允许添加、删除和拖动排序数据保存在 localStorage。五、QVeris 演示功能需要有一个工具调用抽屉展示用户请求的能力、英文 discover query、找到的候选工具数量、最终选中的 tool_id、工具名称、success_rate、平均执行时间、本次实际执行时间、调用状态、参数摘要、返回字段摘要、是否发生候选工具切换、是否使用 Demo 数据。不要显示API Key、Authorization Header、Cookie、完整敏感响应、用户唯一身份信息。六、统一数据模型服务端把不同工具的结果转换为统一 WeatherViewModel 结构缺失数据统一显示暂无数据。七、交互状态必须实现首次加载、搜索中、骨架屏、部分成功部分失败、城市不存在、认证失败、调用超时、数据缺失、工具不可用、Demo 模式提示、手动重试、最近成功数据保留等状态。不要把底层异常堆栈直接展示给用户。八、视觉设计风格定位为专业的数据观察工具清晰、克制、现代适合长时间查看。不做营销页不使用大面积紫色渐变不使用装饰性光球不在卡片中嵌套卡片卡片圆角不超过 8px保持较高的信息密度。配色页面背景浅灰白主文字深灰蓝色用于天气数据空气质量使用语义颜色。深色模式使用中性灰。九、数据与缓存服务端对工具发现结果缓存 24 小时天气结果缓存 10 分钟空气质量结果缓存 15 分钟。前端显示数据更新时间。用户点击刷新时允许绕过天气结果缓存但不要重复执行工具发现。防止同一城市并发请求。十、验收标准完成后的验证标准包括北京、新加坡、伦敦至少能够查询城市名不能直接调用时自动使用地理编码天气、预报和空气质量可以独立失败页面显示实际 tool_id 和执行耗时API Key 不出现在浏览器源码和构建产物中桌面端 1440px 和移动端 390px 显示完整明暗模式和中英文切换可用刷新后收藏城市保留运行 lint、类型检查和构建使用 Playwright 截取桌面端和移动端截图验证。请直接生成完整网站、API Route、环境变量样例、README 和必要测试不要只生成静态设计稿。四、网站生成后需要补齐的内容在线访问地址这个网站是由 Codex 的 Sites 插件生成的由 OpenAI Codex Sites 托管和管理需要在 Codex 中选择分享给互联网的所有人如下图所示这样别人才能看到。因为是对外可以访问的所以我没有配置真实的 QVERIS_API_KEY避免积分不足导致 demo 无法使用。目前使用的都是测试数据只需在服务端根目录的 .env 里配置好 QVERIS_API_KEY 即可真实的从 QVeris 获取数据。下面是这个网站的在线访问地址https://city-weather-lab-qveris.ax2675996.chatgpt.site网站截图桌面端首页截图工具调用抽屉截图展示实际 tool_id、耗时和调用状态城市对比页面截图真实调用验证验证项预期结果北京天气返回当前天气、逐小时趋势和未来预报待验证新加坡天气正确处理城市、国家和时区待验证伦敦空气质量空气质量失败时不影响天气数据待验证工具切换首选工具不可用时自动尝试候选工具待验证凭证保护浏览器和构建产物中不出现 API Key待验证移动端390 像素宽度下无溢出和遮挡待验证五、从一个演示站继续扩展天气只是一个容易理解的起点。保留能力描述、动态发现、参数适配、服务端调用、统一数据模型、结果可视化这条主线演示站可以很快换成其他主题。·体育赛事赛程、积分榜、球队状态和球员数据。·金融市场行情、公告、资金流向和公司基本面。·科研助手论文检索、引用关系、主题聚类和摘要。·城市生活天气、空气质量、地理编码、路线和周边服务。·内容处理网页提取、PDF 解析、OCR、翻译和语音合成。Codex Sites 降低了把想法做成网站的门槛QVeris 则让这个网站能够接入真实、可选择、可替换的外部能力。两者结合以后演示不再停留在这个工具能做什么而是让访问者亲手完成一次真实调用。页面负责让能力被看见工具调用负责让能力真正发生。