在调试线索模糊处添加一个 Logger

此用例适用于仅靠代码审查难以查明“发生了某些情况”的 Mac 应用流程。请让 Codex 围绕某个行为添加少量高信噪比的统一日志，运行应用并触发该行为，然后通过“控制台”或 log stream 验证预期事件是否已触发。

请在该循环中使用 Build macOS Apps 插件。其 macOS 遥测技能刻意保持轻量：使用 Apple 的 Logger，选择清晰的子系统/类别组合，在操作边界和状态转换处记录日志，避免写入敏感数据，并在本地构建/运行后验证事件，而不是想当然地认为日志埋点已正确接入。

遥测为何有助于智能体工程

高质量的日志能让 Codex 在每次修补代码后形成可重复的反馈循环。智能体无需让您手动检查每个窗口、菜单操作或同步转换，而是可以运行应用、走一遍流程、检查筛选后的日志，并根据证据决定下一项代码改动。

这对以下三种智能体循环尤其有用：

• 无需手动干预的调试循环： Codex 为疑似有问题的流程添加日志埋点，启动应用，点击侧边栏或触发命令，读取生成的日志序列，修补状态更新路径，然后重复运行同一流程，直至日志与 UI 行为一致。
• 应用会话采集循环： Codex 分别添加事件来记录应用启动、窗口打开、侧边栏选择、导入开始、导入完成和导入失败，然后运行本地会话并总结所得时间线，使缺失或顺序错误的状态转换一目了然。
• 人工驱动的采集循环： Codex 启用日志记录并启动应用，在您手动走一遍棘手流程期间持续运行针对性的日志流，之后检查捕获的会话，并根据该跟踪记录提出下一项补丁。

保持日志埋点精简且便于筛选

请让 Codex 为每个功能领域设置一个日志记录器，而不是为每次状态变更都永久保留一行日志。使用 Windowing、Commands、MenuBar、Sidebar、Sync 或 Import 这类功能类别，可让下一轮调试更轻松地筛选日志。

import OSLog

private let logger = Logger(
  subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
  category: "Sidebar"
)

@MainActor
func selectItem(_ item: SidebarItem) {
  logger.info("Selected sidebar item: \(item.id, privacy: .public)")
  selection = item.id
}

对于应长期发挥作用的简洁操作事件和生命周期事件，请使用 info；对于较为冗杂、可能在任务完成前被移除或降低级别的本地状态详情，请使用 debug。仅在测量某段操作的耗时时添加标记点，不要默认添加。

让 Codex 用日志证明事件已触发

有价值的不只是添加 Logger 调用。请让 Codex 运行应用，触发已添加日志埋点的流程，并提供它使用的确切“控制台”筛选条件或 log stream 谓词，以及一两行代表性日志。

log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'

如果预期事件未出现，请让 Codex 将日志埋点移到更靠近疑似控制路径的位置，重新运行同一流程，并持续迭代，直到日志能解释发生了什么。如果任务转为崩溃或回溯分析，请切换到该插件的构建/运行调试工作流，并让遥测继续聚焦于操作边界。

保存会话跟踪记录，供 Codex 后续分析

对于持续时间较长或间歇出现的错误，请让 Codex 将针对性的日志流保存到一个小型本地跟踪文件中，总结时间线，并将该产物留在工作空间内，这样 Codex 后续运行时即可检查相同证据，无需凭记忆重新还原整个会话。这样更便于进行多轮调试，例如让一次智能体运行采集跟踪记录，再让另一次运行比较补丁应用前后的行为。

当需要人工操作会话的一部分时，这种方式也很合适。请让 Codex 在便于记录日志的调试循环中启动应用，开始筛选采集并等待您手动复现问题，完成后再读取已保存的跟踪文件。

实用技巧

每次只为一项功能添加日志埋点

先从一个侧边栏、窗口、命令或同步路径开始，确保日志序列易于检查。该路径稳定可靠后，Codex 可将同一模式扩展到相邻流程。

在提示中加入隐私要求

请让 Codex 说明记录的每个标识符，并避免将机密、个人数据或原始内容写入统一日志。对于本地调试，使用一小组事件类型通常就足够了。

在最终摘要中保留示例输出

与“已添加遥测”相比，代表性日志行更能让人确信改动有效。请让 Codex 提供筛选谓词和简短的操作时间线，以便下一次智能体运行复用同一验证循环。