如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
Codex

Codex 使用场景

为 Mac 应用添加遥测日志

让 Codex 使用 Logger 为 Mac 应用的一项功能添加日志,再运行应用,通过统一日志确认相关操作已执行。

难度 Advanced
时间跨度 30m

使用 Codex 和 Build macOS Apps 插件,为窗口、侧边栏、命令或同步流程添加少量 Logger 事件,记录关键操作。然后运行应用,通过“控制台”或 log stream 确认实际触发的操作符合预期。

最适合

  • 需要 Codex 可靠追踪操作过程的 Mac 应用功能,例如打开窗口、更改侧边栏选中项、调用菜单命令、执行菜单栏操作、完成同步流程中的关键步骤,或进入回退路径
  • 需要 Codex 反复修改代码、重新运行应用并检查日志,根据实际记录判断下一步该修复什么的智能体调试流程
  • 您需要在本地多次运行应用,每次都按时间顺序简要记录用户操作和应用生命周期事件,以便对比各次运行的情况

目录

    ← 所有使用场景

    为 Mac 应用添加遥测日志

    让 Codex 使用 Logger 为 Mac 应用的一项功能添加日志,再运行应用,通过统一日志确认相关操作已执行。

    使用 Codex 和 Build macOS Apps 插件,为窗口、侧边栏、命令或同步流程添加少量 Logger 事件,记录关键操作。然后运行应用,通过“控制台”或 log stream 确认实际触发的操作符合预期。

    Advanced
    30m

    使用 Codex 和 Build macOS Apps 插件,为窗口、侧边栏、命令或同步流程添加少量 Logger 事件,记录关键操作。然后运行应用,通过“控制台”或 log stream 确认实际触发的操作符合预期。

    Advanced
    30m

    最适合

    • 需要 Codex 可靠追踪操作过程的 Mac 应用功能,例如打开窗口、更改侧边栏选中项、调用菜单命令、执行菜单栏操作、完成同步流程中的关键步骤,或进入回退路径
    • 需要 Codex 反复修改代码、重新运行应用并检查日志,根据实际记录判断下一步该修复什么的智能体调试流程
    • 您需要在本地多次运行应用,每次都按时间顺序简要记录用户操作和应用生命周期事件,以便对比各次运行的情况

    技能与插件

    • 使用 macOS 遥测技能和构建与运行技能,通过 `OSLog` 添加结构化日志。启动应用,在界面中走一遍相关流程,再通过“控制台”或 `log stream` 核对实际记录的事件。
    技能 使用理由
    Build macOS Apps 使用 macOS 遥测技能和构建与运行技能,通过 `OSLog` 添加结构化日志。启动应用,在界面中走一遍相关流程,再通过“控制台”或 `log stream` 核对实际记录的事件。

    起始提示词

    请使用 Build macOS Apps 插件,为 [name one Mac feature or action flow] 添加轻量级统一日志,然后运行应用,通过日志确认这些事件按预期顺序触发。 要求: - 优先使用 `OSLog` 的 `Logger`,避免使用 `print`。为这项功能设置一组含义明确的子系统和类别,方便筛选日志。 - 每到一个重要的操作节点或发生一次状态转换,就记录一行简洁的日志,例如窗口已打开、侧边栏选中项已更改、菜单命令已调用、同步已开始、同步已结束或已进入回退路径。 - 长期保留的 `info` 日志应保持稳定,只记录关键信息。仅对容易产生大量日志的本地细节使用 `debug`。完成前,请移除临时日志记录代码,或调低其日志级别。 - 不要记录机密信息、身份验证令牌、个人数据或文档原文。如果必须记录标识符,请选用最安全的隐私标注,并说明原因。 - 构建并运行应用,亲自走一遍该功能的操作流程,再使用“控制台”或针对该流程编写的 `log stream` 谓词验证事件。 - 如果流程较长、只能偶尔复现,或更容易手动复现,请将筛选后的日志流保存为一个小型本地会话跟踪文件。必要时,让我手动操作应用,然后读取该文件,按时间顺序概述发生的事件。 - 如果预期事件没有出现,请将日志记录语句移到更接近疑似执行路径的位置,再次运行流程。重复这一过程,直到日志能说明实际发生了什么。 请提供: - 新增的日志记录器配置,以及所添加的具体事件 - 实际使用的“控制台”筛选条件或 `log stream` 谓词 - 添加日志前后的简要对比,说明现在可以观察到哪些行为 - 如果采集过程较长,请附上保存的跟踪文件,并按时间顺序概述事件 - 一两行有代表性的日志,证明该流程中的日志记录点设置正确
    请使用 Build macOS Apps 插件,为 [name one Mac feature or action flow] 添加轻量级统一日志,然后运行应用,通过日志确认这些事件按预期顺序触发。 要求: - 优先使用 `OSLog` 的 `Logger`,避免使用 `print`。为这项功能设置一组含义明确的子系统和类别,方便筛选日志。 - 每到一个重要的操作节点或发生一次状态转换,就记录一行简洁的日志,例如窗口已打开、侧边栏选中项已更改、菜单命令已调用、同步已开始、同步已结束或已进入回退路径。 - 长期保留的 `info` 日志应保持稳定,只记录关键信息。仅对容易产生大量日志的本地细节使用 `debug`。完成前,请移除临时日志记录代码,或调低其日志级别。 - 不要记录机密信息、身份验证令牌、个人数据或文档原文。如果必须记录标识符,请选用最安全的隐私标注,并说明原因。 - 构建并运行应用,亲自走一遍该功能的操作流程,再使用“控制台”或针对该流程编写的 `log stream` 谓词验证事件。 - 如果流程较长、只能偶尔复现,或更容易手动复现,请将筛选后的日志流保存为一个小型本地会话跟踪文件。必要时,让我手动操作应用,然后读取该文件,按时间顺序概述发生的事件。 - 如果预期事件没有出现,请将日志记录语句移到更接近疑似执行路径的位置,再次运行流程。重复这一过程,直到日志能说明实际发生了什么。 请提供: - 新增的日志记录器配置,以及所添加的具体事件 - 实际使用的“控制台”筛选条件或 `log stream` 谓词 - 添加日志前后的简要对比,说明现在可以观察到哪些行为 - 如果采集过程较长,请附上保存的跟踪文件,并按时间顺序概述事件 - 一两行有代表性的日志,证明该流程中的日志记录点设置正确

    在难以判断实际行为的地方添加一个 Logger

    在 Mac 应用的某些流程中,您只知道“有个操作发生了”,仅靠审查代码很难判断具体发生了什么。这时,可以让 Codex 针对某个行为添加几条能反映关键步骤的统一日志,运行应用并触发该行为,然后通过“控制台”或 log stream 验证预期事件是否发生。

    使用构建 macOS 应用插件完成这一轮调试。插件的 macOS 遥测技能只需几个步骤:使用 Apple 的 Logger,选择含义明确的子系统和类别,记录操作的起止点和状态转换,避免记录敏感数据。随后在本地构建并运行应用,通过日志确认预期事件确实发生。

    遥测如何帮助智能体开展工程工作

    有了清晰的日志,Codex 每次修改代码后都可以用同样的步骤验证效果。无需您手动检查每个窗口、菜单操作或同步状态变化,智能体就能运行应用、执行相应流程、查看筛选后的日志,并据此决定下一步如何修改代码。

    遥测尤其适合以下三种由智能体参与的调试流程:

    • 自动调试: Codex 在可能出问题的流程中添加日志,启动应用,点击侧边栏或触发命令,按顺序查看输出的日志,修正更新状态的代码,然后重复执行同一流程,直到日志与界面行为一致。
    • 采集应用会话: Codex 为应用启动、窗口打开、侧边栏选择、导入开始、导入完成和导入失败各添加一个事件,然后在本地运行一次应用,并按时间顺序汇总事件。这样就很容易看出哪些状态转换缺失或顺序有误。
    • 手动操作并采集日志: Codex 启用日志记录并启动应用。在您手动执行较为复杂的流程时,Codex 持续采集相关日志,随后检查这次会话的记录,并根据跟踪结果提出下一步修改方案。

    只记录关键事件,方便筛选日志

    让 Codex 为每个功能模块设置一个日志记录器,避免为每次状态变化都添加一条永久保留的日志。使用 Windowing、Commands、MenuBar、Sidebar、Sync 或 Import 等功能类别,下次调试时就能轻松筛选相关日志。

    import SwiftUI
    
    struct SidebarItem { let id: String }
    @MainActor private var selection: String?
    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 说明日志中记录的每个标识符的含义,并避免将机密信息、个人数据或原始内容写入统一日志。本地调试通常只需记录少数几种事件。

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

    与一句“已添加遥测”相比,几条有代表性的日志更能让您确认改动确实生效。让 Codex 附上筛选谓词,并按时间顺序简要列出操作,以便智能体在下一轮运行时沿用相同的验证步骤。

    技术栈

    需求

    应用日志记录

    默认选项

    OSLog Logger

    为什么需要

    使用结构化统一日志,Codex 可以筛选出与当前流程相关的事件,核对运行结果,无需在代码中到处添加 print 语句。

    需求

    智能体工作流

    为什么需要

    插件中的遥测技能和构建与运行技能可配合使用。先为一个流程添加日志,再启动应用、检查日志,并根据结果精简记录的事件。

    需求

    运行时验证

    默认选项

    Console.app 和 log stream --predicate ...

    为什么需要

    交接时提供具体的日志筛选条件和输出样例,智能体就能在后续运行中重复相同的检查,验证新增的日志记录点。

    需求 默认选项 为什么需要
    应用日志记录 OSLog Logger 使用结构化统一日志,Codex 可以筛选出与当前流程相关的事件,核对运行结果,无需在代码中到处添加 print 语句。
    智能体工作流 Build macOS Apps 插件 插件中的遥测技能和构建与运行技能可配合使用。先为一个流程添加日志,再启动应用、检查日志,并根据结果精简记录的事件。
    运行时验证 Console.app 和 log stream --predicate ... 交接时提供具体的日志筛选条件和输出样例,智能体就能在后续运行中重复相同的检查,验证新增的日志记录点。

    相关使用场景