在调试变得模糊的地方添加一个 Logger

此用例适用于 Mac 应用流程中那种仅凭代码审查无法准确定位问题的模糊情况。要求 Codex 在某个行为周围添加几条高价值的统一日志，运行应用，触发该行为，并从 Console 或 log stream 验证预期的事件是否已触发。

使用 构建 macOS Apps 插件 用于该循环。它的 macOS 遥测技能被有意设计得很轻量：使用 Apple 的 Logger，请选择清晰的子系统/类别对，记录动作边界和状态转换，避免敏感的负载数据，并在本地构建/运行后验证事件，而不是假设插桩已被正确连接。

为什么遥测对智能体工程很有用

良好的日志为 Codex 在每次修补后提供了可重复的反馈循环。智能体无需要求你手动检查每个窗口、菜单操作或同步转换，而是可以运行应用、演练流程、检查过滤后的日志，并根据证据决定下一步的代码更改。

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

• 免干预调试循环： Codex 为可疑流程添加埋点，启动应用，点击侧边栏或触发命令，读取发出的日志序列，修补状态更新路径，并重新运行相同的流程，直到日志和 UI 行为一致。
• 应用会话收集循环： Codex 为应用启动、窗口打开、侧边栏选择、导入开始、导入结束和导入失败各添加一个事件，然后运行一个本地会话并总结生成的时间线，从而使缺失或顺序错乱的转换变得显而易见。
• 人工驱动捕获循环： Codex 在启用日志记录的情况下启动应用，在你手动演练棘手流程时保持聚焦的 log stream 运行，随后检查捕获的会话并基于该追踪提出下一个补丁。

保持埋点精简且可过滤

每个功能区域只向 Codex 索要一个 Logger，而不是为每一次状态变更都添加永久日志行。诸如以下的功能类别 Windowing, Commands, MenuBar, Sidebar, Sync, or 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 用于在任务完成前可能被移除或降级的、较为嘈杂的局部状态细节。仅在测量时间跨度时添加 signposts，不要默认添加。

要求 Codex 从日志中证明事件

有用的部分不仅仅是添加 Logger 调用。要求 Codex 运行应用，触发已埋点的流程，并向你提供它使用的精确 Console 过滤器或 log stream predicate，以及一到两行有代表性的日志记录。

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

如果预期的事件未出现，要求 Codex 将日志移至更接近可疑控制路径的位置，重新运行相同的流程，并不断迭代，直到日志解释了发生的情况。如果任务转变为崩溃或回溯分析，请切换到插件的构建/运行调试工作流，并保持遥测聚焦于操作边界。

为后续的 Codex 运行保存会话追踪

对于耗时较长或间歇性出现的 bug，要求 Codex 将聚焦的 log stream 保存到一个小的本地追踪文件中，总结时间线，并将该产物留在工作区，以便后续的 Codex 运行可以检查相同的证据，而无需从内存中重放整个会话。当你希望一个智能体运行收集追踪，而另一个运行比较修补前后的行为时，这会使多轮调试变得更容易。

当需要人工驱动部分会话时，这也非常有效。要求 Codex 在对日志友好的调试循环中启动应用，开始一次过滤捕获，在你手动重现问题时等待，然后在你完成后再读取保存的追踪文件。

实用技巧

一次只埋点一个功能

从单个侧边栏、窗口、命令或同步路径开始，这样日志序列会保持易于检查的状态。如果该路径变得可靠，Codex 可以将相同的模式扩展到相邻的流程。

在提示词中加入隐私要求

要求 Codex 解释每个记录的标识符，并避免将秘密、个人数据或原始内容写入统一日志。微小的事件词汇通常足以进行本地调试。

在最终总结中保留示例输出

有代表性的日志记录比“已添加遥测”更让人信赖。要求 Codex 包含过滤器 predicate 和简短的操作时间线，以便下一次智能体运行可以复用相同的验证循环。