Codex 使用說明（快速上手）
本文檔說明如何安裝與使用 Codex CLI 與 VS Code 擴充套件，並包含核心操作技巧、進階應用與注意事項。
1. 安裝與快速上手
- 環境需求：請先確認已安裝 Node.js（檢查指令
node -v）。 - CLI 安裝：在終端機輸入：
npm i -g @openai/codex
- 啟動：安裝完成後輸入：
codex
# 之後依指示登入你的 OpenAI 帳號或授權
- VS Code / Cursor：在 VS Code 擴充功能商店搜尋並安裝 Codex（或 Codex/相關官方外掛），安裝後重啟 VS Code 以啟用整合。
2. 核心操作技巧
-
模式切換：
- Auto 模式（預設）：允許 Codex 自動讀取、編輯檔案並執行命令。適合快速迭代。
- Read Only（唯讀模式）：輸入
/approvals切換到唯讀模式，適合先規劃、審查再執行的流程。
-
常用指令與快捷鍵：
/model：切換模型（例如gpt-5-codex）與推理速度設定。/export//load：匯出或載入會話與上下文，便於持久化工作流程。Alt+G：在 VS Code 中將選取程式碼送到 CLI（視外掛設定而定）。
-
精確提示詞範例：
- 不要只下「寫一個排序」，而應寫：「使用快速排序演算法對 JavaScript 陣列進行升序排序，請包含時間複雜度註解與單元測試範例。」
3. 進階應用
-
建議在專案根目錄建立
AGENTS.md（本檔案）以定義專案架構與使用規範，幫助 Codex 理解專案語境。 -
自動化工作流：可讓 Codex 自主執行「讀取檔案 -> 修改檔案 -> 執行測試 -> 回報結果」的循環，但務必先設定：
- 版本控制（git）分支保護與提交點。
- 測試指令（例如
npm test、pytest等）。
-
實務建議：將複雜或危險的變更（例如資料遷移、敏感憑證更新）標記為需人工批准，並在唯讀模式下先審查差異。
4. 注意事項
- 人工審查：Codex 是協作者，生成代碼後務必進行人工審查以避免邏輯或安全問題。
- 安全提示：不要在自動化流程中暴露或直接寫入敏感資訊（如 API 金鑰），請使用安全的機制（環境變數或機密管理）。
- 版本控制：在執行自動化修改前，確認程式碼已儲存在 Git 中，並且在獨立分支上運行。
5. 給非開發者的建議
- 若你不是開發者，建議直接使用 VS Code 的插件版本，操作介面更直觀且能保留人工審核步驟。
如需我把本檔案進一步擴充為專案專屬的操作守則（例如加入測試指令、常見任務範本、CI/CD 範例），請告訴我要包含的內容或專案慣例。
中文 UI/UX 指南
以下為針對中文使用者介面（繁體中文）常用的寫作與設計準則，方便前端與本地化團隊採用：
-
語言與風格：
- 使用繁體中文（zh-TW），語氣親切、簡潔、動詞優先（例如「建立專案」、「儲存變更」）。
- 避免冗長句子，按鈕與選單文案控制在 4〜10 字元內。
-
用語與翻譯原則：
- 優先使用一致詞彙（如「儲存」非「保存」），將常用詞彙列入術語表（Glossary）。
- 保留技術名詞的英文（必要時於括號註明），但操作文案以中文為主。
-
按鈕與訊息範例：
- 儲存 / 儲存並關閉：
儲存、儲存並關閉 - 取消：
取消 - 刪除（危險操作需二次確認）：
刪除→ 確認對話框文字：確定要刪除此項目？此操作無法復原。 - 提交：
送出
- 儲存 / 儲存並關閉：
-
文字長度與排版：
- 按鈕標籤建議 ≤ 6 字；表格欄位標題簡短（≤ 10 字）。
- 在受限空間（行動裝置）提供簡短標籤並在 tooltip 中補充說明。
-
日期、時間與數字格式：
- 日期格式建議
YYYY/MM/DD或YYYY-MM-DD（依專案慣例），時間採 24 小時制或明確標示 AM/PM。 - 千分位與小數點顯示依業務需求，本地化時使用
,與.的正確慣例。
- 日期格式建議
-
可及性（a11y）：
- 所有互動元件需有對應的可訪問標籤（aria-label、aria-describedby）。
- 提供清晰的焦點樣式，並確保高對比度文字與按鈕。
-
i18n 實作建議：
- 使用 key 為命名規範，例如
ui.btn.save,ui.alert.delete.confirm。 - 避免在翻譯字串中使用程式插入符號（如
%s），優先採用佔位符{name}並在翻譯上下文中說明用途。
- 使用 key 為命名規範，例如
-
測試與審查流程：
- 每次新增/修改 UI 字串，建立翻譯 PR 並註明上下文（截圖、使用場景）。
- 使用 Lint 或 i18n 檢查工具驗證缺失鍵與佔位符錯誤。
-
範例（i18n JSON 範本）：
{
"ui": {
"btn": {
"save": "儲存",
"cancel": "取消",
"delete": "刪除"
},
"alert": {
"delete": {
"confirm": "確定要刪除此項目？此操作無法復原。"
}
}
}
}
如需，我可以把此指南擴充為可複製到前端專案的 i18n 範本、術語表（CSV/JSON），或在 AGENTS.md 加入中文文案審查流程範例。