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

運用技能加快開源專案維護

運用技能與 GitHub Actions,改善 OpenAI Agents SDK 程式碼庫中的 Codex 工作流程。

作者: Kazuhiro Sera

運用技能加快開源專案維護

我們用 Codex 改變了維護 OpenAI Agents SDK 程式碼庫的方式。透過程式碼庫內的技能、AGENTS.md 和 GitHub Actions,我們將驗證、發行準備、範例整合測試及 PR 審查等例行工程工作,整理成可重複執行的工作流程。即使設定相當簡單,也提高了這些活躍程式碼庫的開發吞吐量。2025 年 12 月 1 日至 2026 年 2 月 28 日,兩個程式碼庫共合併了 457 個 PR,高於前三個月(2025 年 9 月 1 日至 11 月 30 日)的 316 個。Python 從 182 個增至 226 個,TypeScript 從 134 個增至 231 個。

這套 SDK 提供 Python 和 TypeScript 版本,包含建構智慧體應用程式所需的核心元件。開發者也能用它在 Realtime API 上建構語音智慧體,以簡潔的方式整合多個智慧體、工具與人工介入控制機制。這套 SDK 的使用規模相當大。截至 2026 年 3 月 6 日,按兩個套件各自近期的 30 天統計,Python 套件在 PyPI 上約有 1,470 萬次下載,TypeScript 套件在 npm 上約有 150 萬次下載。

設定很簡單:

  • 在 AGENTS.md 中記錄程式碼庫規範
  • 在 .agents/skills/ 中存放程式碼庫專用的技能
  • 視需要在技能中加入指令碼與參考資料
  • 需要在 CI 中執行相同工作流程時,使用 Codex GitHub Action

這樣一來,Codex 就有穩定的上下文可用來了解程式碼庫的運作方式,能更快、更準確地完成例行工程工作。

如果你維護公開的開源專案,請參閱 Codex for OSS。符合資格的維護者可申請包含 Codex 的 ChatGPT Pro、API 點數,以及有條件的 Codex Security 存取權。

將工作流程保存在程式碼庫中

我們用技能記錄各個程式碼庫專屬的工作流程。每項技能都把一小套操作知識封裝在一起,包括一份 SKILL.md 資訊清單,以及可選的 scripts/、references/ 和 assets/。Codex 自訂文件說明了這種做法為何有效:技能可以為重複執行的工作流程提供更詳盡的指示、指令碼與參考資料,又不會在一開始就占用智慧體過多的上下文空間。

這正是技能採用的漸進式揭露方式:

  • 智慧體先看到 name 和 description 等中繼資料
  • 只有選用技能時,才載入 SKILL.md
  • 只有需要時,才讀取參考資料或執行指令碼

兩個 SDK 程式碼庫都將工作流程與程式碼放在一起:

Python 程式碼庫提供了一套較簡單的基本配置:

  • code-change-verification 在程式碼或建置行為有變更時,依規定執行格式化、lint 檢查、型別檢查和測試。
  • docs-sync 對照程式碼檢查文件,找出遺漏、錯誤或過時的內容。
  • examples-auto-run 以自動模式執行範例、記錄日誌,並提供重新執行範例的輔助工具。
  • final-release-review 比較上一個發行版本的標籤與目前的候選版本,確認是否可以發行。
  • implementation-strategy 在動手修改執行階段或 API 之前,先確定需要維持相容的範圍與實作方式。
  • openai-knowledge 透過官方 Docs MCP 工作流程取得最新的 OpenAI API 與平台文件。
  • pr-draft-summary 在交接時產生建議的分支名稱、PR 標題與說明草稿。
  • test-coverage-improver 執行測試涵蓋率分析,找出最大的缺口,並建議最值得新增的測試。

JavaScript 程式碼庫採用類似的做法,另外針對其 npm 單一程式碼庫與發行流程加入幾項專用技能:

  • changeset-validation 檢查變更集和版本號遞增層級是否確實符合套件的實際差異。
  • integration-tests 將套件發佈到本機 Verdaccio 套件登錄庫,並驗證能否在各個支援的執行階段中安裝與執行。
  • pnpm-upgrade 一併更新 pnpm 工具鏈和 CI 中鎖定的版本。

比起清單上有哪些技能,更重要的是它們的設計方式。每項技能都有明確而有限的職責、清楚的觸發條件,以及具體的輸出。

有些特別實用的技能不必設成強制關卡。docs-sync 和 test-coverage-improver 都會先提出報告:檢查目前的變更差異或測試涵蓋率報告,排出處理的優先順序,再於修改前要求核准。在 Python 程式碼庫中,docs-sync 也會以原始碼中的文件字串與註解為準,據此維護自動產生的參考文件,避免手動修補產生的內容。JavaScript 專用的 pnpm-upgrade 技能也是職責明確的維護流程:它會一併更新本機 pnpm 版本、packageManager 與工作流程中鎖定的版本,無須大範圍搜尋與取代。

規定何時必須執行工作流程

當程式碼庫明定在什麼情況下必須使用技能,技能就更能發揮作用。這正是 AGENTS.md 的用途。

根據 AGENTS.md 指南,這些檔案存放的是程式碼庫層級的指示,隨程式碼一同維護,在智慧體開始工作前就已適用。指南也建議保持檔案精簡。在 Agents SDK 程式碼庫中,我們用這個位置記錄 Codex 每次都應遵守的規則,並將最重要的幾條放在開頭。

實務上,兩個程式碼庫都用簡短的條件規則來指定何時必須使用哪些技能。修改執行階段或 API 之前,先呼叫 $implementation-strategy,確定需要維持相容的範圍與實作方式。如果變更影響 SDK 程式碼、測試、範例或建置行為,就呼叫 $code-change-verification。如果 JavaScript 套件的變更影響發行中繼資料,就呼叫 $changeset-validation。工作涉及 OpenAI API 或平台整合時,呼叫 $openai-knowledge。工作完成、可以交接時,呼叫 $pr-draft-summary。

這種結構也符合 agents.md 的建議:將專案概覽、建置與測試指令、程式碼風格、測試指引、安全考量及其他程式碼庫專屬規則集中在一處。Agents SDK 程式碼庫遵循這種結構,並將日常工作中最重要的觸發條件放在前面。精簡版如下:

# AGENTS.md

## Project overview

- Core SDK code lives under `src/agents/` or `packages/*/src/`.
- Tests live under `tests/` or `packages/*/test/`.
- Sample apps and integration surfaces live under `examples/`.

## Mandatory skill usage

- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.
- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.
- Use `$openai-knowledge` for OpenAI API or platform work.
- Use `$pr-draft-summary` when substantial code work is ready for review.

## Build and test commands

- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`

## Compatibility rules

- Preserve positional compatibility for public constructors and dataclass fields.

實際檔案會在這套基本配置上補充各程式碼庫的細節,例如 JavaScript 程式碼庫中的 $changeset-validation,以及兩份檔案中更詳細的執行階段、文件與發行指引。完整範例請參閱 openai-agents-python 的 AGENTS.md 和 openai-agents-js 的 AGENTS.md。

AGENTS.md 除了指定技能的觸發條件,還有其他用途。Python 程式碼庫也在這裡記錄了一條公開 API 相容性規則:維持匯出的建構函式參數與資料類別欄位在各位置上的原有意義,盡可能將新增的選用參數或欄位放在最後。如果無法避免調整順序,就新增相容性測試。這也是值得採用的做法:將攸關發行的相容性規則與技能觸發條件放在同一處。

驗證規則

以 $code-change-verification 為例。

兩個程式碼庫的規則都不是「每次都要執行一長串驗證」,而是「執行階段程式碼、測試、範例或建置/測試行為有變更時,就必須執行驗證,而且通過後才能將工作標示為完成」。

限定觸發條件,可以讓只修改文件的工作保持簡單。符合條件就強制執行,則能確保 SDK 程式碼變更都經過程式碼庫的標準驗證步驟。

實際的驗證步驟直接寫在技能裡。

在 Python 程式碼庫中,必須執行:

make format
make lint
make typecheck
make tests

在 JavaScript 程式碼庫中,技能要求嚴格依照以下順序執行:

pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test

技能定義了程式碼庫所謂「已驗證」的標準,而 AGENTS.md 讓這項標準成為必須遵守的規則。

驗證變更集

JavaScript 程式碼庫對套件變更還有一道必要步驟:執行 $changeset-validation。這項技能以 Changesets 為基礎。

只要 packages/ 下的任何內容有變更,或 .changeset/ 有變更,模型除了執行測試,還必須建立或更新對應的變更集、驗證版本號遞增層級,並確認變更集確實符合實際差異。

這項技能不只檢查檔案是否存在,也要求 Codex 判讀 Git 差異。驗證規則存放在共用提示詞中,讓本機執行與 GitHub Actions 採用相同邏輯。技能也記錄了程式碼庫專屬的規範,例如:

  • 如果分支已有變更集,就沿用現有變更集,無須另建一份
  • 依 Conventional Commit 格式將摘要寫成一行,讓它也能用作提交標題
  • 在 1.0 版之前,一般功能開發應避免遞增主版本號。若新增內容已明確標示為僅供預覽,且未改變既有行為,則視為修補版本變更
  • 根據套件的實際變更,驗證應遞增哪一層版本號

因此,Codex 必須先驗證自己產生的發行中繼資料,才能宣告工作完成。

查閱最新文件

在這兩個程式碼庫中,只要工作涉及 OpenAI API 或平台整合,也都必須使用 $openai-knowledge。

這項技能簡單封裝了官方的 OpenAI Docs MCP。它會指示 Codex 使用 OpenAI 開發者文件 MCP 伺服器,查閱 Responses API、工具、串流、Realtime 與 MCP 等功能的最新文件,避免模型憑記憶回答。

如果本機 Codex 環境尚未設定 MCP 伺服器,技能會引導維護者參閱 Docs MCP 快速入門與官方 MCP 伺服器端點。

準備 PR 交接資料

完成實質工作後,兩個程式碼庫都會使用 $pr-draft-summary。

只有當任務大致完成或已可送審,而且變更涉及實質的程式碼、測試、範例、會影響行為的文件,或建置/測試設定時,才會觸發這項技能。接著,它會自動收集分支名稱、工作樹狀態、變更的檔案、差異統計與近期提交,並產生:

  • 建議的分支名稱
  • PR 標題
  • PR 說明草稿

我們刻意固定了輸出格式。典型結果如下:

# Pull Request Draft

## Branch name suggestion

git checkout -b fix/tracing-lazy-init-fork-safety

## Title

fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards

## Description

This pull request fixes import-time tracing side effects that could break fork-based process models by moving tracing bootstrap to lazy, first-use initialization.

It updates tracing setup so initialization happens once on first access while preserving the existing public tracing APIs.

It also adds regression tests for import-time behavior, one-time bootstrap, and custom provider handling.

This pull request resolves #2489.

當你已經信任模型能驗證並整理自己的工作成果,讓它在最後產生 PR 草稿就很自然。這能讓交接資料保持一致,也能減少程式碼寫完後重複撰寫說明的時間。

把技能說明寫得更明確

技能的 description 欄位位於 SKILL.md 的前置中繼資料中,也是決定如何選用技能的依據之一。

這牽涉到技能的結構,而不只是寫作風格。智慧體技能規格規定 name 和 description 是 SKILL.md 前置中繼資料的必要欄位。依其漸進式揭露方式,系統啟動時會為所有技能載入這些欄位。直到實際啟用某項技能,才會載入完整的 SKILL.md 內文,以及該技能的 scripts/、references/ 或 assets/。

關於 Codex 如何選用技能,Codex 技能文件與自訂文件說明了相同的行為:Codex 先透過各項技能的中繼資料找出可用技能,選定技能後才載入 SKILL.md,並只在需要時讀取參考資料或執行指令碼。OpenAI API Cookbook 的技能指南也清楚說明了託管 Shell 環境的運作方式:OpenAI 會先讀取各項技能的 name、description 與路徑,模型再根據這些資訊判斷何時讀取完整的 SKILL.md。其中的 SKILL.md 前置中繼資料一節說得更直接:name 和 description 對於發現與選用技能都很重要。

因此,在 Agents SDK 程式碼庫中,Codex 還沒讀取技能的其餘內容時,description 就已經是判斷該選用哪項技能的主要依據之一。

以 code-change-verification 為例。

過於籠統的寫法:

description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.

更明確的寫法(實際使用的說明):

description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.

較短的版本已經告訴 Codex 這項技能有什麼用途,卻沒有交代何時適用、哪些變更應觸發技能,以及在什麼情況下檢查是必要的。較具體的版本把這三點都說清楚了。

同樣的寫法也用在 pr-draft-summary 上。

過於籠統的寫法:

description: Create a PR title and draft description for a pull request.

更明確的寫法(實際使用的說明):

description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.

同樣地,實際使用的說明是用來選擇技能的中繼資料。它告訴 Codex:

  • 這項技能應在任務收尾時使用
  • 有實質變更時才適用,無須在每輪對話中使用
  • 輸出必須是可直接用於 PR 的完整區塊,只有一段文字摘要並不足夠

這些程式碼庫帶給我們一項實務經驗:值得花時間寫好 description。如果 Codex 經常選錯技能,先調整中繼資料,再考慮增加程式碼。

將固定操作寫成指令碼

接下來要決定的是,哪些工作該交給模型,哪些該寫進指令碼。

一種可靠的分工方式是:

  • 由模型負責解讀、比較及撰寫報告
  • 將步驟固定且重複執行的 shell 操作放進 scripts/

這也符合公開指引。Codex 自訂文件指出,技能能為可重複執行的工作流程提供更詳盡的指示、指令碼與參考資料,不必一開始就占用大量上下文空間。這很適合以模型為主的配置:讓 Codex 處理需要依上下文判斷的部分,只有在需要執行固定步驟時才使用指令碼。OpenAI API Cookbook 的技能指南也建議將技能指令碼設計成小型 CLI:可從指令列執行,對相同輸入產生一致的標準輸出,失敗時明確顯示用法或錯誤訊息,並視需要將結果寫入指定的檔案路徑。

在 Agents SDK 程式碼庫中,我們盡量將模型用在真正需要判斷力的地方,例如:

  • 閱讀原始碼,推斷預期行為
  • 將日誌與預期行為比對
  • 判斷發行版本間的差異是否真的帶來相容性風險
  • 撰寫說明,讓維護者知道如何採取行動

指令碼則負責配合這些工作的固定操作,例如:

  • 依固定順序執行程式碼庫要求的驗證指令
  • 啟動範例、分別收集各範例的日誌,並為執行失敗的範例產生重跑用檔案
  • 在審查是否可以發行之前,取得上一個發行版本的標籤
  • 提供 start、stop、status、logs、tail、collect 和 rerun 等輔助指令,方便重複執行同一個工作流程

如果模型每次都得重新摸索同一套 shell 操作,通常就該把這套操作寫成指令碼。需要考量上下文、權衡取捨或解釋結果的部分,則應留給模型。

自動執行整合測試

在兩個程式碼庫中,自動化整合測試都是特別實用的工作流程。這裡有兩個相關層次:兩個程式碼庫都會自動驗證庫內的範例,而 JavaScript 程式碼庫還會另外驗證已發佈的套件,確認使用者依平常的方式安裝後,套件仍能正常運作。

採用這套配置之前,範例驗證仍有一部分得手動完成。範例可以直接執行,但最後往往得靠人逐一查看日誌,判斷輸出是否合理。只驗證一個範例時還能應付,面對持續成長的 SDK 程式碼庫就很難跟上。

第一層是 examples-auto-run,不過我們先有執行器,後來才有技能。為了自動驗證範例,我們必須先讓兩個程式碼庫都支援非互動式執行。這表示範例指令碼必須能以自動模式執行,即使是平常會提示使用者輸入或要求核准的範例也一樣。

這些前置工作包括:

  • 自動回應常見的互動式提示
  • 在執行器支援的情況下,自動核准 HITL、MCP、apply_patch 和 shell 操作
  • 將仍不適合自動執行的範例列入自動略過清單,例如需要額外設定執行環境的即時互動範例或 Next.js 應用程式範例
  • 為每次範例執行寫入結構化日誌
  • 產生重跑用檔案,讓失敗的範例能單獨重試,無須全部重新執行

基礎功能就緒後,我們將它整理成技能,讓工作流程可以重複使用,也方便呼叫。在 Python 程式碼庫中,examples-auto-run 封裝了 uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir ...。在 JavaScript 程式碼庫中,它會先執行封裝好的建置檢查,再以自動模式執行 pnpm examples:start-all,分別記錄各範例的日誌,並支援重新執行。

為了提高驗證品質,執行器負責執行範例,並將各範例的標準輸出與標準錯誤輸出保存在對應的日誌中。接著,技能會讓 Codex 逐一檢查日誌,並與原始碼比對:

  • 閱讀範例的原始碼與註解
  • 推斷預期的執行流程
  • 開啟對應的日誌
  • 將預期行為與實際的標準輸出及標準錯誤輸出比對
  • 對每個成功執行的範例都完成上述步驟,而非只抽查一個

比起在指令碼中用固定的斷言判定結果是否正確,這種做法更準確,也更有彈性。代表執行成功的結束狀態碼很有用,但對於會呼叫實際 API、使用工具或產生結構化輸出的範例,光看狀態碼還不夠。我們先記錄實際輸出,再仔細對照原始碼,就能依每個範例原本要示範的行為進行驗證。

JavaScript 程式碼庫還有第二層驗證,由獨立的 integration-tests 技能負責。這個工作流程會將套件發佈到本機 Verdaccio 套件登錄庫,再測試能否在 Node.js、Bun、Deno、Cloudflare Workers 與 Vite React 應用程式等多種環境中安裝與執行。這能找出只在程式碼庫內執行原始碼範例時難以發現的問題:第一層檢查「範例能否在程式碼庫中執行」,第二層則確認「套件經過發佈、安裝並整合到執行環境後,行為是否仍然正確」。

這些工作流程說明了結合技能、指令碼與模型判斷力的好處。指令碼讓測試能以相同方式重複執行,留下驗證所需的證據,也能涵蓋手動檢查起來很繁瑣的安裝方式。Codex 再利用這些證據仔細比對,比起只靠指令碼判定通過或失敗,能檢查得更深入。

加入發行檢查

這種做法也適用於發行準備。

兩個程式碼庫的發行審查流程都會先找出上一個發行版本的標籤,與最新的 main 比對,再請 Codex 檢查差異中是否有以下問題:

  • 公開 API 或使用者可觀察到的 SDK 行為出現回溯相容性問題
  • 既有功能退化,包括預期行為的細微變化
  • 需要說明的變更缺少遷移注意事項,或尚未更新發行說明

技能會根據檢查結果,綜合判斷是否可以發行。

具體例子可見 openai/openai-agents-python#2480。這次審查的整體結論是可以發行,同時也指出新版將停止支援 Python 3.9,以及發行說明必須補充哪些內容:

Release readiness review (excerpt)

Release call:
🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change
(Python 3.9 drop) with no concrete regressions found.

Scope summary:

- 38 files changed (+1450/-789); key areas touched: `src/agents/tool.py`,
  `src/agents/extensions/`, `src/agents/realtime/`, `tests/`,
  `pyproject.toml`, `uv.lock`.

Python 3.9 support removed

- Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install the
  0.9.0 release.
- Evidence: `pyproject.toml` now sets `requires-python = ">=3.10"` and drops
  the Python 3.9 classifier; CI skip logic for 3.9 was removed.
- Action: Ensure release notes clearly call out the Python 3.9 drop and that
  packaging metadata remains `>=3.10`.

技能也定義了如何決定是否放行。審查以「可安全發行」為起點,只有當差異中出現具體證據,顯示確實存在問題時,才會判定暫緩發行。每次暫緩發行,都必須列出解除阻礙所需的具體事項。這讓維護者更容易依結果行動:綠燈表示差異中未發現足以阻礙發行的問題,暫緩發行則表示確實有問題,而且下一步很明確。

這比籠統地要求「請審查這次發行」更有用。模型必須根據具體差異推理,並說明結果對發行有何影響。可以安全發行,就明確說明。如果不能,就指出確切證據,以及接下來必須完成的事項。

在 CI 中執行工作流程

一項技能在本機用起來有效之後,就能透過 Codex GitHub Action 在 CI 中自動執行相同工作流程。最好等本機工作流程穩定後再這麼做,因為手動使用的過程正好能幫助你找出指示中的問題、改進指令碼,並發現實際會遇到的邊界情況。

對公開程式碼庫而言,觸發條件的設計和技能本身同樣重要。GitHub Action 安全檢查清單建議限制能啟動工作流程的人員,優先採用受信任的事件或明確核准機制,清理來自 PR、提交、議題或留言的提示詞輸入。為保護 OPENAI_API_KEY,請使用 drop-sudo 或以無特權使用者身分執行,並將執行 Codex 排在作業的最後一步。

如果工作流程具有寫入權限,又接受不受信任的公開輸入,風險通常來自技能周邊的觸發條件設計、輸入處理方式,以及執行時的權限。

在 PR 審查中使用 Codex

技能是我們提高這些程式碼庫開發效率的一種方式,另一種則是 Codex GitHub PR 自動審查。

自從 Codex GitHub PR 自動審查推出以來,這些程式碼庫中大多數的程式碼變更都有 Codex 協助審查。我們將它納入例行審查,而非只在特殊情況下使用。

對於單純的程式錯誤、功能退化和遺漏的測試,實務經驗顯示,現在已能放心將 Codex 審查設為必要流程。它能反覆依相同準則檢查常見的正確性問題,消除了小幅修正和例行改進的一大瓶頸。

同儕審查仍然重要,尤其是在處理另一類變更時。

當主要問題從「這段程式碼是否正確」變成「幾種可行方案中應選哪一種,又該如何推出」時,人工審查仍然不可或缺。這類情況包括:

  • API 或架構變更有多種合理設計,需要維護者明確選擇
  • 行為變更會影響使用者對產品的預期、回溯相容性承諾或推出政策
  • 需要決定命名、遷移方式或如何傳達發行資訊,而難處在於判斷怎麼做才能讓使用者與貢獻者最容易理解
  • 需要維護者或團隊協調的變更,例如界定工作範圍、安排先後順序,或決定哪些內容現在推出、哪些留待之後

Codex 在這些情況下都能提供協助,但仍需要有人直接討論並做決定。

AGENTS.md 也可以記錄這樣的分工:程式碼庫可以指明審查正確性時應注意哪些重點,讓 Codex 一致地套用這些指引。

這項分工也顯著提高了開發吞吐量。每次低風險變更所需的例行審查與驗證,不必再等審查者騰出時間。維護者則能專注在需要掌握更多背景、也更仰賴自身判斷的審查工作上。這讓我們能更快修正積壓的錯誤,並完成小幅功能改進。

結語

在 OpenAI Agents SDK 程式碼庫中,將技能納入日常開發流程最能發揮其作用。

AGENTS.md 告訴 Codex 哪些工作流程必須執行,description 說明何時該選用這些流程。scripts/ 負責步驟固定的部分,模型則負責需要依上下文判斷的部分。等工作流程在本機穩定運作後,就能透過 Codex GitHub Action 在 CI 中執行相同流程。

這些做法讓程式碼庫的日常工程工作更明確,也更可靠。驗證、發行審查與 PR 交接如今都有可重複執行的一致流程,因此我們也更容易快速推出小幅改進。

資源