添加 Mac 遥测

在模糊处添加一个 Logger

这个场景适合 Mac app 中“某件事发生了”但只靠代码审查无法确定的流程。让 Codex 围绕一个行为添加少量高信号 unified logs，运行应用、触发行为，并从 Console 或 `log stream` 验证预期事件是否出现。

Build macOS Apps 插件的 telemetry skill 很轻量：使用 Apple `Logger`，选择明确 subsystem/category，记录 action boundaries 和 state transitions，避免敏感 payload，并在本地 build/run 后验证事件。

为什么遥测适合 agentic engineering

好日志能在每次 patch 后给 Codex 一个可重复反馈循环。它不用让你手工检查每个窗口、菜单动作或同步 transition，而是可以运行应用、操作流程、检查过滤后的日志，再基于证据决定下一次改动。

• Hands-free debug loop：instrument 可疑流程，启动应用，触发 sidebar 或 command，读取日志序列，patch 状态更新路径，再跑同一流程。
• App session collection loop：记录 app launch、window open、sidebar selection、import started/finished/failed 等关键事件，并总结 timeline。
• Regression evidence loop：在修复后保留同一 log predicate 和样例输出，作为后续验证入口。

保持 instrumentation 小而可过滤

让 Codex 为每个 feature area 建一个 logger，而不是为每次 state mutation 永久加日志。`Windowing`、`Commands`、`MenuBar`、`Sidebar`、`Sync`、`Import` 这类 category 更容易在下一轮调试中过滤。

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
}

要求 Codex 用日志证明事件

价值不只是添加 `Logger` 调用。让 Codex 运行应用、触发被 instrument 的流程，并给出它使用的 Console filter 或 `log stream` predicate，以及一两条代表性日志行。

如果预期事件没有出现，让 Codex 把日志移动到更接近可疑控制路径的位置，重新运行同一流程，并持续迭代到日志能解释发生了什么。

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

保存 session trace 供后续使用

对更长或间歇性 bug，让 Codex 把聚焦 log stream 保存到一个小型本地 trace 文件，概括 timeline，并把 artifact 留在 workspace。后续 Codex run 就能复用同一证据，而不必每次重放完整 session。

如果某部分需要人手动操作，也可以让 Codex 启动 logging-friendly debug loop，开始过滤捕获，等你复现完成后读取保存的 trace 文件。

实用提示

• 一次 instrument 一个 feature：sidebar、window、command 或 sync path，保持序列容易检查。
• 把隐私写进 prompt：要求 Codex 解释每个 logged identifier，并避免把 secrets、个人数据或原始内容写入 unified logs。
• 在最终总结里保留 predicate 和样例输出，让下一轮 agent 能复用同一个验证循环。