如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Codex

Codex 應用案例

為 Mac 應用程式加入遙測

用 Codex 為一項 Mac 功能加入 Logger 事件記錄,再執行應用程式,從統一日誌確認操作是否如預期觸發。

難度 Advanced
任務時間跨度 30m

用 Codex 和 Build macOS Apps 外掛程式,在視窗、側邊欄、指令或同步流程中,用 Logger 記錄幾個關鍵事件。接著執行應用程式,透過「主控台」或 log stream 確認預期的動作確實已觸發。

最適合的對象

  • 開發 Mac 應用程式功能時,Codex 需要可靠的記錄來追蹤視窗何時開啟、側邊欄選了哪個項目、執行了哪些選單指令或選單列操作,以及同步到了哪個階段或何時改走備援路徑
  • 由智慧體反覆偵錯時,Codex 需要修改程式碼、重新執行應用程式並檢查日誌,根據實際記錄決定下一步該修正什麼,避免猜測
  • 多次在本機執行應用程式時,需要為每次工作階段保留一份精簡記錄,以便比對使用者操作與應用程式生命週期事件的先後順序

目錄

    ← 所有應用案例

    為 Mac 應用程式加入遙測

    用 Codex 為一項 Mac 功能加入 Logger 事件記錄,再執行應用程式,從統一日誌確認操作是否如預期觸發。

    用 Codex 和 Build macOS Apps 外掛程式,在視窗、側邊欄、指令或同步流程中,用 Logger 記錄幾個關鍵事件。接著執行應用程式,透過「主控台」或 log stream 確認預期的動作確實已觸發。

    Advanced
    30m

    用 Codex 和 Build macOS Apps 外掛程式,在視窗、側邊欄、指令或同步流程中,用 Logger 記錄幾個關鍵事件。接著執行應用程式,透過「主控台」或 log stream 確認預期的動作確實已觸發。

    Advanced
    30m

    最適合的對象

    • 開發 Mac 應用程式功能時,Codex 需要可靠的記錄來追蹤視窗何時開啟、側邊欄選了哪個項目、執行了哪些選單指令或選單列操作,以及同步到了哪個階段或何時改走備援路徑
    • 由智慧體反覆偵錯時,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 確認預期的事件確實發生。

    這套流程可以使用 Build macOS Apps 外掛程式。其中的 macOS 遙測技能刻意保持簡單:使用 Apple 的 Logger,選擇容易辨識的子系統與類別組合,記錄動作的起訖與狀態轉換,並避免記錄敏感的資料內容。在本機建置並執行應用程式後,實際確認事件是否出現,別只憑程式碼判斷記錄機制是否正常運作。

    遙測如何協助智慧體開發軟體

    有了清楚的日誌,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,這些記錄可以在任務完成前移除或調低層級。只有在需要測量某段操作的耗時時才加入 signpost,平時不必預設加入。

    請 Codex 用日誌確認事件確實發生

    加入 Logger 呼叫後,還需要實際驗證。請 Codex 執行應用程式,觸發已加入記錄的流程,並提供它在「主控台」實際使用的篩選條件或 log stream 述詞,以及一兩行具代表性的日誌。

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

    如果預期的事件沒有出現,請 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 ... 交接時附上實際使用的日誌篩選條件與輸出範例,智慧體就能在每次執行時用相同方式驗證新增的事件記錄。

    相關應用案例