logfire-ui

打开 Logfire UI

遇到直接打开 Logfire UI、浏览器、实时视图、链接或 Explore 页面相关请求时，使用此技能。

面向用户的进度更新

尽量不打扰用户地更新进度。不要说明选择此技能的原因、复述路由规则、引用本地指令、解释令牌范围，也不要通报常规的辅助调用。如需更新，请用一句简短的话说明操作，例如“正在打开带错误筛选条件的 Logfire。”

打开 Logfire 后，不要额外检查页面状态，也不要对此进行说明，除非浏览器似乎卡住、要求登录，或用户明确要求验证页面。

浏览器目标

在 Codex Desktop 中，尽可能使用 Browser 插件的 Codex 内置浏览器（iab）和当前选中的标签页。

浏览器访问是间接的：不要期待有名为 browser 的 MCP 工具。如果 Browser 插件显示为可用，请加载 browser:browser 技能，并使用其 Node REPL 的 js / mcp__node_repl__js 引导程序绑定 agent.browsers.get("iab")。如果看不到 js，请先通过工具发现查找 node_repl js，再判断内置浏览器不可用。

除非用户明确要求使用外部浏览器，否则不要使用 agent-browser、chrome-devtools、mcp__chrome_devtools__*、mcp__playwright__*、macOS open、xdg-open、独立版 Playwright/Chromium、通过 shell 启动的浏览器、网页预览卡片，或新建的外部浏览器窗口。如果已选中 Logfire 实时视图且可以原位更新，请勿新建内置浏览器标签页。

只有在 Browser 插件未列出或无法加载其技能、工具发现后仍无法使用 Node REPL 的 js 执行工具，或 Browser 技能的引导程序在开始导航前失败时，才报告内置浏览器不可用。此时请返回简洁的 Logfire URL，并说明无法控制内置浏览器。将 chrome-devtools、Playwright MCP、独立版 Playwright 和网页预览卡片视为“浏览器不可用”，不得将其作为备用方案。不要悄悄改用任何外部或专用浏览器窗口。

核心规则

对于项目级或汇总级 UI 请求，直接打开 Logfire 或返回其 URL。

不要先查询遥测数据：

• 不要调用 query_run。
• 不要说你将先查询 Logfire 或获取 spans。

只有当用户要求打开必须先查找的特定未知项目时，才先进行查询，例如“打开最慢的 trace”或“打开最新的错误 trace”。

如果请求含糊不清，例如“显示最近的错误”或“查看日志”，请询问用户是希望在 UI 中打开 Logfire，还是在聊天中进行查询分析。除非用户明确要求两者都做，否则不要两者兼做。

项目发现

对于未明确指定组织/项目的 UI 请求，先尝试通过 Logfire MCP 身份验证/当前项目信息解析规范项目 URL。若可用的 MCP 服务提供项目链接或当前项目辅助工具，请使用它。这属于项目发现，不是遥测查询。

如果 MCP 能解析出唯一的当前项目，请使用该项目 URL。如果无法解析项目、解析出多个候选项，或返回身份验证/错误状态，请询问用户组织/项目名称或完整的 Logfire 项目 URL。

不要根据 LOGFIRE_BASE_URL、LOGFIRE_URL、导出器配置、仓库名称或 localhost 是否可访问来推断项目 URL。环境变量/配置值可以标识 Logfire 平台/API 基础地址，但本身不能标识目标组织/项目。

URL 工作流

1. 如果已知完整的项目 URL，请直接使用。
2. 如果用户未指定项目，请按照上述说明，通过 MCP 解析当前项目。
3. 如果用户给出了项目名称，但未提供组织或基础 URL，请调用 project_logfire_ui_link(project=project)，使用默认的清理链接行为来推导规范项目 URL。这是用于发现 URL 的辅助工具，不是遥测查询。
4. 对于项目实时视图／筛选器 URL，如果要立即在 Codex Browser 中打开链接，请调用 project_logfire_ui_link(project=project, query=query, since=since, until=until, handoff=True)。返回持久或可分享的 URL 时，使用默认的清理链接行为。如果用户提供了现有的清理版 Logfire 项目 URL 并要求移交，请解析其中的项目、q、since 和 until 值，并通过此工具传入。
5. 如果用户提供了真实的 trace_id，或者查询工作流已找到真实的 trace_id，要立即在 Codex Browser 中打开链接时，请调用 project_logfire_link(trace_id=trace_id, project=project, handoff=True)。返回持久或可分享的 URL 时，使用默认的清理链接行为。
6. 在适用时，通过 project_logfire_ui_link 添加 query、since 和 until。如果手动组装清理版 URL，请对 q、since 和 until 进行 URL 编码。
7. 如果用户要求打开 URL 且 Browser 可用，请在 Codex 内置浏览器中打开。否则，返回 URL，不要启动外部浏览器。

已打开的实时视图控制

如果 Logfire 项目实时视图已在 Codex Browser 中打开，请使用 JSON 命令桥。这是唯一受支持的应用内交互方式，因为它无需完整重新加载文档即可更新视图，并能让用户看到 Agent 正在主动更改页面。

不要尝试在 Codex Browser 中使用页面全局 JavaScript API。唯一受支持的 Agent 控制界面是 JSON 命令输入框。

对于 Codex Browser / iab，请在 Logfire live view agent command 输入框中填入类似 {"q":"level='error'","last":"1h","since":null,"until":null} 的 JSON 补丁，然后按 Enter。隐藏的提交按钮仅用作表单目标；不要仅仅因为该按钮不可见或无法点击，就跳过此操作流程。

只有在桥接表单输入框不存在或无法提交时，才使用直接 URL／搜索参数更新。桥接表单可用时，不要直接更新 URL。

使用直接 URL 回退方案且浏览器控制界面允许通过页面脚本更新 URL 时，请更新 window.history 并派发 popstate 事件。对于有意义的用户可见导航，使用 pushState；对于清理或重试，使用 replaceState。如果无法在页面内更新 URL，则回退为打开清理版 URL。

不要修改 /api/auth/handoff?ticket=... URL。移交 URL 仅是一次性入口；重定向后，请控制最终的清理版项目 URL。

实时视图搜索参数：

• q：类似 SQL 的 Logfire 筛选表达式，例如 level='error'、kind='span' 或 service_name='api'。构造 URL 字符串时，请对其进行 URL 编码。
• last：滚动实时窗口，例如 5m、1h、14d 或毫秒数值。实时模式下使用此参数，并移除 since／until。
• since 和 until：采用 ISO 8601 时间戳的固定历史时间窗口。指定有限时间范围时使用这两个参数，并移除 last。
• env：部署环境筛选器。多个环境请重复使用 env 参数。适用于所有环境时省略此参数。
• traceId 和 spanId：已知时，用于聚焦特定 trace／span。更改主查询或时间范围时，请清除 traceId、spanId、focusTraceId 和 focusTraceTimestamp 等过时的聚焦参数，除非用户要求保留聚焦记录。

浏览器交接 URL

当 MCP 链接工具支持 handoff: bool = False 时，仅对需要立即在浏览器中打开的 URL 使用 handoff=True。交接 URL 有效期短、只能使用一次，并绑定到平台生成的目标地址。

• 如果交接结果是字符串，请尽快打开该确切 URL。它可能是 /api/auth/handoff?ticket=... URL。不要向其中添加查询参数、改写、持久化、在文档中引用，或将其视为可分享的 URL。
• 如果交接结果是带有 handoff: false 的对象，请使用其 url 值作为干净的备用 URL。仅在有助于用户理解浏览器可能仍会要求登录时，才提及 reason，例如使用 API 密钥进行身份验证或需要重新进行身份验证。
• 如果原因指出需要重新验证 Logfire MCP 连接，请说明 MCP OAuth 刷新令牌缺少生成 UI 会话所需的元数据。不要将其描述为刷新浏览器会话；用户需要重新连接／重新验证 Logfire MCP 身份验证流程。
• 如果可用的 MCP 服务未提供 handoff，请正常调用链接工具并使用干净 URL。
• 不要手动向交接 URL 追加筛选条件或时间参数。将最终项目筛选条件目标地址放入 project_logfire_ui_link，让平台为该目标地址生成票据。

Codex 浏览器打开稳定性

在 Codex 浏览器中打开 Logfire 交接 URL 时，请保留相同目标地址对应的持久干净 URL 作为备用地址。如有需要，在报告浏览器打开失败前，使用 handoff=False 调用相同的链接工具。

使用浏览器技能的应用内浏览器工作流，并限制导航尝试的等待时间。不要等待 networkidle、WebSocket 完成或实时视图页面完全静止。导航后如需等待，只等待 URL 提交、最终干净项目 URL，或可见的 Logfire 页面信号。

如果浏览器仍停留在灰色的 about:blank 页面，或浏览器导航调用超时，请停止等待并返回干净 URL。应描述为浏览器在导航前卡住，而不是 Logfire 身份验证失败。不要泄露已使用或已过期的交接 URL。

不要通过启动单独的浏览器窗口来解决 Codex 浏览器卡顿问题。除非用户明确要求尝试外部浏览器，否则请返回干净 URL。

常用筛选条件

• Spans：q=kind%3D%27span%27
• Logs：q=kind%3D%27log%27
• Exceptions：q=is_exception%3Dtrue
• Errors：q=level%3D%27error%27
• Service：对类似 service_name='api' 的筛选条件进行 URL 编码

示例

对于“在 Codex 中打开 starter-project 最近一小时的 Logfire 实时视图，并显示 spans”：

1. 直接打开已知或推导出的 starter-project Logfire URL。
2. 添加 q=kind%3D%27span%27。
3. 添加 since=<one-hour-ago> 和 until=<now>。
4. 在 Codex 浏览器中打开该 URL。
5. 不要先运行 SQL。

对于“找到耗时最长的 trace 并打开它”，仅使用查询工作流来识别 trace，然后使用 project_logfire_link(trace_id=trace_id, project=project, handoff=True) 并打开该链接。

对于“将已打开的实时视图更改为最近一小时的错误”，请通过 Logfire live view agent command 输入提交 {"q":"level='error'","last":"1h","since":null,"until":null}；不要生成新的交接 URL。

身份验证边界

不要尝试将 MCP 身份验证令牌传入浏览器或 Logfire UI。绝不要将 bearer、API、读取或写入令牌放入 URL 查询参数、片段、粘贴到浏览器的说明、日志或备注中。MCP／工具身份验证与浏览器 Web 会话属于不同的安全上下文。

对于需要立即打开的 UI 链接，优先使用上述平台交接方式。如果交接不可用，则回退到干净 URL，并在有帮助时说明具体的回退原因。缺少浏览器 Cookie 可能需要正常登录浏览器；MCP OAuth 连接过期则需要重新进行 MCP 身份验证。