# Codex 使用說明（快速上手）

本文檔說明如何安裝與使用 Codex CLI 與 VS Code 擴充套件，並包含核心操作技巧、進階應用與注意事項。

## 1. 安裝與快速上手

- 環境需求：請先確認已安裝 Node.js（檢查指令 `node -v`）。
- CLI 安裝：在終端機輸入：

```bash
npm i -g @openai/codex
```

- 啟動：安裝完成後輸入：

```bash
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}` 並在翻譯上下文中說明用途。

- 測試與審查流程：
  - 每次新增/修改 UI 字串，建立翻譯 PR 並註明上下文（截圖、使用場景）。
  - 使用 Lint 或 i18n 檢查工具驗證缺失鍵與佔位符錯誤。

- 範例（i18n JSON 範本）：

```json
{
  "ui": {
    "btn": {
      "save": "儲存",
      "cancel": "取消",
      "delete": "刪除"
    },
    "alert": {
      "delete": {
        "confirm": "確定要刪除此項目？此操作無法復原。"
      }
    }
  }
}
```

如需，我可以把此指南擴充為可複製到前端專案的 `i18n` 範本、術語表（CSV/JSON），或在 `AGENTS.md` 加入中文文案審查流程範例。