原文核对：2026-10-13 · 中文正文 · 英文提示词与演示
场景定位
在窗口、侧栏、命令或同步流程中添加少量有效 Logger 事件，运行应用后用 Console 或 log stream 证明操作确实发生。
- 难度
- 高级
- 时间跨度
- 30 分钟
适合用于
- 需要可靠追踪窗口、侧栏、菜单、同步里程碑或回退路径的功能。
- 需要依据日志持续修改和重跑的代理调试。
- 希望收集紧凑操作与生命周期序列、对比多次运行的本地会话。
相关工具
添加结构化 OSLog 埋点，启动并操作 UI，再通过 Console 或 log stream 验证事件。
Build macOS Apps ↗起步提示词
英文原文 · 可复制后按实际材料修改
Use the Build macOS Apps plugin to add lightweight unified logging around [name one Mac feature or action flow], then run the app and verify from logs that those events fire in the expected order.
Constraints:
- Prefer `Logger` from `OSLog`, not `print`, and create a clear subsystem/category pair for this feature so the logs are easy to filter.
- Log one concise line for each important action boundary or state transition: for example window opened, sidebar selection changed, menu command invoked, sync started, sync finished, or fallback path taken.
- Keep permanent `info` logs stable and high signal. Use `debug` only for noisy local details, and remove or demote temporary instrumentation before finishing.
- Do not log secrets, auth tokens, personal data, or raw document contents. If an identifier must be logged, choose the safest privacy annotation and explain why.
- Build and run the app, exercise the feature path yourself, and verify the events with Console or a focused `log stream` predicate.
- If the flow is long, intermittent, or easier to reproduce by hand, save the filtered log stream to a small local session trace file, let me manually exercise the app if needed, then read that file back and summarize the event timeline.
- If an expected event does not appear, move the log closer to the suspected control path, rerun the flow, and continue until the logs explain what happened.
Deliver:
- the new logger setup and the exact events you added
- the Console filter or `log stream` predicate you used
- a short before/after summary of what the logs now make observable
- the saved trace file and timeline summary if this became a longer capture session
- one or two representative log lines that prove the flow is instrumented correctly在难以判断的位置添加 Logger
仅从代码无法说明某个 Mac 流程发生了什么时，围绕一个行为加入少量统一日志，运行并触发它，再核实预期事件。
Build macOS Apps 的 telemetry 技能采用轻量方式：使用 Apple Logger、明确 subsystem/category、记录操作边界和状态转换、避开敏感内容，并在本地运行后验证。
遥测如何帮助代理开发
有效日志提供可重复反馈。Codex 可以自行运行应用、操作流程、检查筛选后的日志，再依据证据决定修改，减少逐个窗口和操作的人工检查。
尤其适合三种循环：
- 自动调试：埋点、启动、点击侧栏或触发命令、读取事件序列、修改状态路径，再运行直到日志与 UI 一致。
- 会话收集：记录启动、打开窗口、侧栏选择、导入开始、完成和失败，汇总本地会话时间线以发现缺失或乱序。
- 人工操作采集：启用日志后保持定向 log stream，由你复现复杂流程，结束后检查记录并提出修复。
保持埋点少而易筛选
每个功能区域使用一个 logger，不必为每次状态变化永久留日志。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，完成前可移除或降级。仅测量时间跨度时使用 signpost。
从日志证明事件
除了加入 Logger 调用，还应运行应用、触发流程，并提供实际使用的 Console 筛选或 log stream predicate，以及一两条代表性日志。
log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'预期事件未出现时，把日志移近可疑控制路径并重跑。若转为崩溃或回溯分析，则使用插件的构建运行调试流程，遥测继续聚焦操作边界。
保存会话供后续分析
对于长时间或间歇性问题，将定向日志保存到小型本地文件，概述时间线并留在工作区。后续 Codex 可复用证据，比较修复前后行为。
也适合需要人工操作的情况：启动便于记录的调试流程和筛选采集，等待你复现，再读取保存的文件。
实用建议
一次覆盖一个功能
从一个侧栏、窗口、命令或同步路径开始；可靠后再扩展到邻近流程。
把隐私要求写进提示词
解释每个被记录的标识符，避免写入密钥、个人数据或原始内容。少量事件类型通常已足够。
在最终摘要中保留示例
提供筛选条件、代表性日志和简短操作时间线，便于信任修改并在后续复用验证。
技术栈
| 需要 | 默认选项 | 用途 |
|---|---|---|
| 应用日志 | OSLog LoggerOSLog Logger ↗ | 结构化统一日志提供范围小、易筛选的反馈。 |
| 代理流程 | Build macOS Apps 插件Build macOS Apps plugin ↗ | 结合遥测和构建运行技能：埋点、启动、检查日志、完善事件集。 |
| 运行验证 | Console.app 与 log stream --predicate ... | 具体筛选条件和示例输出可供反复验证。 |
展开英文原文对照
Use Codex and the Build macOS Apps plugin to add a few high-signal Logger events around windows, sidebars, commands, or sync flows, then run the app and prove from Console or log stream that the right actions fired.
Add one Logger where debugging gets vague
This use case is for Mac app flows where “something happened” is too fuzzy to debug from code review alone. Ask Codex to add a few high-signal unified logs around one behavior, run the app, trigger that behavior, and verify from Console or log stream that the expected events fired.
Use the Build macOS Apps plugin for that loop. Its macOS telemetry skill is intentionally lightweight: use Apple’s Logger, choose a clear subsystem/category pair, log action boundaries and state transitions, avoid sensitive payloads, and verify the event after a local build/run instead of assuming the instrumentation is wired correctly.
Why telemetry is useful for agentic engineering
Good logs give Codex a repeatable feedback loop after each patch. Instead of asking you to manually inspect every window, menu action, or sync transition, the agent can run the app, exercise the flow, inspect filtered logs, and decide the next code change from evidence.
That is especially useful for three agentic loops:
- Hands-free debug loop: Codex instruments a suspicious flow, launches the app, clicks the sidebar or triggers a command, reads the emitted log sequence, patches the state update path, and reruns the same flow until the logs and UI behavior agree.
- App session collection loop: Codex adds one event for app launch, window open, sidebar selection, import started, import finished, and import failed, then runs a local session and summarizes the resulting timeline so missing or out-of-order transitions become obvious.
- Human-driven capture loop: Codex launches the app with logging enabled, keeps a focused log stream running while you manually exercise a tricky flow, then inspects the captured session afterward and proposes the next patch from that trace.
Keep the instrumentation small and filterable
Ask Codex for one logger per feature area, not one permanent log line for every state mutation. Feature categories such as Windowing, Commands, MenuBar, Sidebar, Sync, or Import make logs much easier to filter during the next debugging pass.
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
}Use info for concise action and lifecycle events that should remain useful over time, and debug for noisier local state details that may be removed or demoted before the task is done. Add signposts only when you are measuring a timing span, not by default.
Ask Codex to prove the event from logs
The useful part is not just adding Logger calls. Ask Codex to run the app, trigger the instrumented flow, and give you the exact Console filter or log stream predicate it used plus one or two representative log lines.
log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'If an expected event does not appear, ask Codex to move the log closer to the suspected control path, rerun the same flow, and keep iterating until the logs explain what happened. If the task turns into a crash or backtrace analysis, pivot to the plugin’s build/run debugging workflow and keep the telemetry focused on the action boundaries.
Save a session trace for a later Codex pass
For longer or intermittent bugs, ask Codex to save a focused log stream to a small local trace file, summarize the timeline, and leave that artifact in the workspace so a later Codex run can inspect the same evidence without replaying the whole session from memory. That makes multi-pass debugging easier when you want one agent run to collect a trace and another run to compare behavior before and after a patch.
This also works well when the human needs to drive part of the session. Ask Codex to launch the app in a logging-friendly debug loop, start a filtered capture, wait while you reproduce the issue manually, and then read the saved trace file once you are done.
Practical tips
Instrument one feature at a time
Start with one sidebar, window, command, or sync path so the log sequence stays easy to inspect. If that path becomes reliable, Codex can expand the same pattern to neighboring flows.
Make privacy part of the prompt
Ask Codex to explain every logged identifier and to avoid writing secrets, personal data, or raw content to unified logs. A tiny event vocabulary is usually enough for local debugging.
Keep sample output in the final summary
Representative log lines make the change much easier to trust than “telemetry was added.” Ask Codex to include the filter predicate and a short action timeline so the next agent run can reuse the same verification loop.