讓 Codex 能呼叫你的命令列工具

你是 Codex 命令列工具接入規劃顧問，幫我規劃讓 Codex 安全、正確地呼叫我自己的 CLI 工具。

【角色】
你知道怎麼讓 Codex 用上自定義命令列工具、怎麼把工具用法說清、怎麼限定安全邊界。

【輸入】
- 我的工具是什麼、怎麼用：___
- 它是隻讀查詢還是會改東西：___
- 涉及的許可權和資料：___
- 我希望 Codex 用它做什麼：___

【工作流程】
1. 把工具用法和引數說清給 Codex
2. 區分只讀和寫操作，限定可用範圍
3. 給安全邊界和審批
4. 給驗證 Codex 用對了的方式

【輸出規範】
▌一、工具用法說明（給 Codex）
▌二、只讀 / 寫操作的範圍限定
▌三、安全邊界 + 審批
▌四、驗證用對的方法

【硬約束】
- 寫 / 刪 / 高危的工具操作預設審批
- 工具憑據走環境變數，不明文
- 限定工具可用範圍，不全開
- 工具返回視為不可信輸入
- 不確定的用法先讓我確認

當 Codex 總要訪問同一個 API、記錄來源、匯出檔案、本地資料庫或團隊指令碼時，不要每次把說明粘進 prompt。更穩的做法是做一個 agent-friendly CLI，讓它能搜尋、讀取、下載、匯出，並保持預設輸出足夠小。

什麼時候該做 CLI

適合：

• CI 記錄在構建頁面後面，需要按 build URL 下載。
• API 響應很大，需要搜尋和按 ID 讀取。
• 客服工單、Slack 匯出、記錄包需要索引。
• 團隊指令碼太大，需要拆成可組合命令。
• Codex 需要把附件、trace、report、video、log bundle 下載到檔案。

不適合：

• 一次性任務。
• 只需要讀本地 repo。
• 還沒想清楚認證和許可權。
• 寫操作不可審查。

判斷標準

一個動作重複出現三次以上，就應該考慮 CLI。判斷時不要先問“能不能寫指令碼”，先問這四件事：

• Codex 是否經常需要從同一個外部系統取資料。
• 這個系統是否有穩定 ID、分頁、搜尋、下載或匯出概念。
• 預設輸出能否控制在小範圍內，完整資料能否寫到檔案。
• 寫操作是否能拆成 draft 和 submit 兩步。

只要其中三項成立，CLI 通常比把長說明塞進 prompt 更穩。CLI 讓外部系統有了穩定命令面，skill 再把呼叫時機和禁區告訴 Codex。

命令面應該小而可組合

flowchart LR
    Setup["setup-check"] --> Search["search"]
    Search --> Read["read --id"]
    Read --> Download["download --out"]
    Read --> Draft["draft"]
    Draft --> Submit["submit"]

推薦把動作拆開：

• setup-check：檢查認證和環境。
• search：小結果搜尋。
• read：按穩定 ID 讀取單條。
• download：把大內容匯出到檔案。
• draft：準備寫入內容。
• submit：真正寫入，需要明確確認。

不要把搜尋、下載、寫入都塞進一個大命令。動作越小，Codex 越容易保持邊界。

推薦 command surface

team-tool setup-check
team-tool search --query "..." --limit 10
team-tool read --id "..."
team-tool download --id "..." --out ./logs
team-tool draft --id "..." --message-file ./draft.md
team-tool submit --draft-id "..." --confirm

設計重點：

• setup-check 先失敗清楚，避免任務中途才發現缺 token。
• search 只返回摘要和穩定 ID，不返回整段大 JSON。
• read 按 ID 取精確物件，適合放進上下文。
• download 把大附件、記錄、trace 寫入檔案，再返回路徑。
• draft 生成可審查內容。
• submit 是唯一 live write，必須顯式確認。

給 Codex 的構建提示詞

請建立一個 Codex 可以呼叫的 CLI，並配套建立一個 skill。

材料：
{文件 URL / OpenAPI spec / 已脫敏 curl / 現有指令碼 / 記錄目錄 / CSV / JSON / SQLite}

第一版只支援：
{只讀搜尋、按 ID 讀取、下載記錄到 ./logs}

寫入邊界：
{暫不寫入，或只建立草稿，submit 前必須確認}

要求：
先展示 command surface，不要直接寫程式碼。
只詢問會阻塞構建的資訊。

關鍵是先看 command surface。CLI 設計錯了，後面實現再完整也不好用。

輸入材料要真實

可以給：

• 文件 URL。
• OpenAPI spec。
• 已脫敏 curl。
• 示例 JSON / CSV。
• SQLite 資料庫。
• 現有指令碼。
• 你希望模仿的 --help。

不要給：

• 真實 token。
• 生產賬號。
• 未脫敏客戶資料。
• 無法驗證的口頭描述。

認證資訊應走環境變數、設定檔或 secret store。CLI 缺認證時要清楚報錯。

驗收方式

一個 CLI 做完後，不要只在原始碼目錄裡跑一次。

驗收：

1. 安裝到 PATH。
2. 換一個臨時目錄執行。
3. 缺少認證時錯誤清楚。
4. 搜尋預設輸出小。
5. 大響應能匯出到檔案。
6. 寫操作不會直接執行，或有明確確認。
7. companion skill 能說明何時使用和何時禁止。

如果 Codex 預設輸出巨大 JSON，讓它改成摘要 + 檔案路徑。

後續複用

跑順後，把 CLI 使用方式寫進 skill。以後新任務只需要說：

請使用 $ci-logs 檢查這個 build URL 的失敗 job。

穩定之後再考慮 automation。先有 CLI 和 skill，再談定時或批次執行。

Skill 要記錄什麼

companion skill 不是 CLI README 的復讀。它應該告訴未來的 Codex 任務：

• 什麼時候必須先跑 setup-check。
• 搜尋預設 --limit 用多少。
• 大輸出應該寫到哪個目錄。
• 哪些命令只讀，哪些命令會寫入。
• submit、上傳、刪除、重試這類動作需要使用者明確確認。
• CLI 失敗時先修 CLI 還是回退到別的工具。

如果 skill 沒有寫審批邊界，CLI 以後會被誤用。尤其是內部工具，一定要把 live write 和 destructive action 寫成硬邊界。

官方資料

• OpenAI Codex use case: Create a CLI Codex can use
• Codex skills
• Build Codex plugins