oh-my-codex 0.7.6 → 0.8.1

package/README.vi.md

@@ -1,10 +1,60 @@
-# oh-my-codex (OMX) README tiếng Việt
+# oh-my-codex (OMX)
 
-> Tài liệu đầy đủ bằng tiếng Anh: [English README](./README.md).
+<p align="center">
+  <img src="https://yeachan-heo.github.io/oh-my-codex-website/omx-character-nobg.png" alt="oh-my-codex character" width="280">
+  <br>
+  <em>Codex của bạn không đơn độc.</em>
+</p>
 
-OMX là lớp điều phối đa tác nhân cho OpenAI Codex CLI.
+[![npm version](https://img.shields.io/npm/v/oh-my-codex)](https://www.npmjs.com/package/oh-my-codex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
 
-## Bắt đầu nhanh
+> **[Website](https://yeachan-heo.github.io/oh-my-codex-website/)** | **[Documentation](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** | **[CLI Reference](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** | **[Workflows](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** | **[GitHub](https://github.com/Yeachan-Heo/oh-my-codex)** | **[npm](https://www.npmjs.com/package/oh-my-codex)**
+
+Lớp điều phối đa tác nhân cho [OpenAI Codex CLI](https://github.com/openai/codex).
+
+## Ngôn ngữ
+
+- [English](./README.md)
+- [한국어 (Korean)](./README.ko.md)
+- [日本語 (Japanese)](./README.ja.md)
+- [简体中文 (Chinese Simplified)](./README.zh.md)
+- [繁體中文 (Chinese Traditional)](./README.zh-TW.md)
+- [Tiếng Việt (Vietnamese)](./README.vi.md)
+- [Español (Spanish)](./README.es.md)
+- [Português (Portuguese)](./README.pt.md)
+- [Русский (Russian)](./README.ru.md)
+- [Türkçe (Turkish)](./README.tr.md)
+- [Deutsch (German)](./README.de.md)
+- [Français (French)](./README.fr.md)
+- [Italiano (Italian)](./README.it.md)
+
+
+OMX biến Codex từ một tác nhân phiên đơn thành một hệ thống phối hợp với:
+- Role prompts (`/prompts:name`) cho các tác nhân chuyên biệt
+- Workflow skills (`$name`) cho các chế độ thực thi lặp lại
+- Điều phối đội ngũ trong tmux (`omx team`, `$team`)
+- Trạng thái bền vững và bộ nhớ qua máy chủ MCP
+
+## Tại sao chọn OMX
+
+Codex CLI mạnh mẽ cho các tác vụ trực tiếp. OMX thêm cấu trúc cho công việc lớn hơn:
+- Phân tách và thực thi theo giai đoạn (`team-plan -> team-prd -> team-exec -> team-verify -> team-fix`)
+- Trạng thái vòng đời chế độ bền vững (`.omx/state/`)
+- Bề mặt bộ nhớ và sổ ghi chú cho phiên làm việc dài
+- Điều khiển vận hành cho khởi chạy, xác minh và hủy bỏ
+
+OMX là một tiện ích bổ sung, không phải fork. Nó sử dụng các điểm mở rộng gốc của Codex.
+
+## Yêu cầu hệ thống
+
+- macOS hoặc Linux (Windows qua WSL2)
+- Node.js >= 20
+- Codex CLI đã cài đặt (`npm install -g @openai/codex`)
+- Xác thực Codex đã cấu hình
+
+## Bắt đầu nhanh (3 phút)
 
 ```bash
 npm install -g oh-my-codex
@@ -12,25 +62,254 @@ omx setup
 omx doctor
 ```
 
-## Tính năng chính
+Cấu hình khởi chạy khuyến nghị cho môi trường tin cậy:
 
-- Chạy tác nhân chuyên biệt với role prompt (`/prompts:name`)
-- Tự động hóa workflow lặp lại bằng skill (`$name`)
-- Điều phối đội ngũ trong tmux (`omx team`, `$team`)
-- Lưu trạng thái + bộ nhớ lâu dài qua MCP servers
+```bash
+omx --xhigh --madmax
+```
+
+## Mới trong v0.5.0
+
+- **Thiết lập nhận biết phạm vi** qua `omx setup --scope user|project` cho các chế độ cài đặt linh hoạt.
+- **Định tuyến Spark worker** qua `--spark` / `--madmax-spark` — worker của đội có thể sử dụng `gpt-5.3-codex-spark` mà không ép buộc model lãnh đạo.
+- **Hợp nhất danh mục** — loại bỏ các prompt không dùng nữa (`deep-executor`, `scientist`) và 9 skill không dùng nữa để có bề mặt gọn hơn.
+- **Mức độ chi tiết thông báo** cho kiểm soát chi tiết đầu ra CCNotifier.
+
+## Phiên đầu tiên
 
-## Lệnh thường dùng
+Trong Codex:
+
+```text
+/prompts:architect "analyze current auth boundaries"
+/prompts:executor "implement input validation in login"
+$plan "ship OAuth callback safely"
+$team 3:executor "fix all TypeScript errors"
+```
+
+Từ terminal:
+
+```bash
+omx team 4:executor "parallelize a multi-module refactor"
+omx team status <team-name>
+omx team shutdown <team-name>
+```
+
+## Mô hình cốt lõi
+
+OMX cài đặt và kết nối các lớp sau:
+
+```text
+User
+  -> Codex CLI
+    -> AGENTS.md (bộ não điều phối)
+    -> ~/.codex/prompts/*.md (danh mục prompt tác nhân)
+    -> ~/.agents/skills/*/SKILL.md (danh mục skill)
+    -> ~/.codex/config.toml (tính năng, thông báo, MCP)
+    -> .omx/ (trạng thái runtime, bộ nhớ, kế hoạch, nhật ký)
+```
+
+## Các lệnh chính
+
+```bash
+omx                # Khởi chạy Codex (+ HUD trong tmux khi có sẵn)
+omx setup          # Cài đặt prompt/skill/config theo phạm vi + dự án AGENTS.md/.omx
+omx doctor         # Chẩn đoán cài đặt/runtime
+omx doctor --team  # Chẩn đoán Team/swarm
+omx team ...       # Khởi động/trạng thái/tiếp tục/tắt worker tmux của đội
+omx status         # Hiển thị các chế độ đang hoạt động
+omx cancel         # Hủy các chế độ thực thi đang hoạt động
+omx reasoning <mode> # low|medium|high|xhigh
+omx tmux-hook ...  # init|status|validate|test
+omx hooks ...      # init|status|validate|test (quy trình mở rộng plugin)
+omx hud ...        # --watch|--json|--preset
+omx help
+```
+
+## Mở rộng Hooks (Bề mặt bổ sung)
+
+OMX hiện bao gồm `omx hooks` cho scaffolding và xác thực plugin.
+
+- `omx tmux-hook` vẫn được hỗ trợ và không thay đổi.
+- `omx hooks` là bổ sung và không thay thế quy trình tmux-hook.
+- Tệp plugin nằm tại `.omx/hooks/*.mjs`.
+- Plugin tắt theo mặc định; kích hoạt bằng `OMX_HOOK_PLUGINS=1`.
+
+Xem `docs/hooks-extension.md` cho quy trình mở rộng đầy đủ và mô hình sự kiện.
+
+## Cờ khởi chạy
+
+```bash
+--yolo
+--high
+--xhigh
+--madmax
+--force
+--dry-run
+--verbose
+--scope <user|project>  # chỉ dành cho setup
+```
+
+`--madmax` ánh xạ đến Codex `--dangerously-bypass-approvals-and-sandbox`.
+Chỉ sử dụng trong môi trường sandbox tin cậy hoặc bên ngoài.
+
+### Chính sách workingDirectory MCP (tăng cường tùy chọn)
+
+Theo mặc định, các công cụ MCP state/memory/trace chấp nhận `workingDirectory` do người gọi cung cấp.
+Để hạn chế điều này, đặt danh sách gốc được phép:
+
+```bash
+export OMX_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another-root"
+```
+
+Khi được đặt, các giá trị `workingDirectory` ngoài các gốc này sẽ bị từ chối.
+
+## Kiểm soát Prompt Codex-First
+
+Theo mặc định, OMX tiêm:
+
+```text
+-c model_instructions_file="<cwd>/AGENTS.md"
+```
+
+Điều này thêm hướng dẫn `AGENTS.md` của dự án vào lệnh khởi chạy Codex.
+Mở rộng hành vi Codex, nhưng không thay thế/bỏ qua các chính sách hệ thống cốt lõi của Codex.
+
+Điều khiển:
+
+```bash
+OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx     # tắt tiêm AGENTS.md
+OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx
+```
+
+## Chế độ đội
+
+Sử dụng chế độ đội cho công việc lớn được hưởng lợi từ worker song song.
+
+Vòng đời:
+
+```text
+start -> assign scoped lanes -> monitor -> verify terminal tasks -> shutdown
+```
+
+Các lệnh vận hành:
 
 ```bash
-omx
-omx setup
-omx doctor
 omx team <args>
-omx status
-omx cancel
+omx team status <team-name>
+omx team resume <team-name>
+omx team shutdown <team-name>
+```
+
+Quy tắc quan trọng: không tắt khi các tác vụ vẫn đang ở trạng thái `in_progress` trừ khi đang hủy bỏ.
+
+### Chính sách dọn dẹp Ralph
+
+Khi đội chạy trong chế độ ralph (`omx team ralph ...`), việc dọn dẹp khi tắt
+áp dụng chính sách chuyên dụng khác với đường dẫn thông thường:
+
+| Hành vi | Đội thông thường | Đội Ralph |
+|---|---|---|
+| Tắt cưỡng bức khi lỗi | Ném `shutdown_gate_blocked` | Bỏ qua cổng, ghi nhật ký sự kiện `ralph_cleanup_policy` |
+| Xóa nhánh tự động | Xóa nhánh worktree khi rollback | Giữ lại nhánh (`skipBranchDeletion`) |
+| Ghi nhật ký hoàn thành | Sự kiện `shutdown_gate` tiêu chuẩn | Sự kiện `ralph_cleanup_summary` bổ sung với phân tích tác vụ |
+
+Chính sách Ralph được phát hiện tự động từ trạng thái chế độ đội (`linked_ralph`) hoặc
+có thể được truyền rõ ràng qua `omx team shutdown <name> --ralph`.
+
+Chọn Worker CLI cho worker của đội:
+
+```bash
+OMX_TEAM_WORKER_CLI=auto    # mặc định; sử dụng claude khi worker --model chứa "claude"
+OMX_TEAM_WORKER_CLI=codex   # ép buộc worker Codex CLI
+OMX_TEAM_WORKER_CLI=claude  # ép buộc worker Claude CLI
+OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude  # hỗn hợp CLI theo worker (độ dài=1 hoặc số worker)
+OMX_TEAM_AUTO_INTERRUPT_RETRY=0  # tùy chọn: tắt fallback thích ứng queue->resend
 ```
 
-## Tìm hiểu thêm
+Lưu ý:
+- Tham số khởi chạy worker vẫn được chia sẻ qua `OMX_TEAM_WORKER_LAUNCH_ARGS`.
+- `OMX_TEAM_WORKER_CLI_MAP` ghi đè `OMX_TEAM_WORKER_CLI` cho lựa chọn theo worker.
+- Gửi trigger sử dụng thử lại thích ứng theo mặc định (queue/submit, sau đó fallback an toàn clear-line+resend khi cần).
+- Trong chế độ Claude worker, OMX khởi chạy worker dưới dạng `claude` thuần túy (không có tham số khởi chạy thêm) và bỏ qua các ghi đè rõ ràng `--model` / `--config` / `--effort` để Claude sử dụng `settings.json` mặc định.
+
+## `omx setup` ghi những gì
+
+- `.omx/setup-scope.json` (phạm vi cài đặt được lưu trữ)
+- Cài đặt phụ thuộc phạm vi:
+  - `user`: `~/.codex/prompts/`, `~/.agents/skills/`, `~/.codex/config.toml`, `~/.omx/agents/`
+  - `project`: `./.codex/prompts/`, `./.agents/skills/`, `./.codex/config.toml`, `./.omx/agents/`
+- Hành vi khởi chạy: nếu phạm vi được lưu trữ là `project`, khởi chạy `omx` tự động sử dụng `CODEX_HOME=./.codex` (trừ khi `CODEX_HOME` đã được đặt).
+- `AGENTS.md` hiện có được giữ nguyên theo mặc định. Trong các lần chạy TTY tương tác, setup hỏi trước khi ghi đè; `--force` ghi đè không hỏi (kiểm tra an toàn phiên hoạt động vẫn áp dụng).
+- Cập nhật `config.toml` (cho cả hai phạm vi):
+  - `notify = ["node", "..."]`
+  - `model_reasoning_effort = "high"`
+  - `developer_instructions = "..."`
+  - `[features] multi_agent = true, child_agents_md = true`
+  - Mục máy chủ MCP (`omx_state`, `omx_memory`, `omx_code_intel`, `omx_trace`)
+  - `[tui] status_line`
+- `AGENTS.md` của dự án
+- Thư mục `.omx/` runtime và cấu hình HUD
+
+## Tác nhân và skill
+
+- Prompt: `prompts/*.md` (cài vào `~/.codex/prompts/` cho `user`, `./.codex/prompts/` cho `project`)
+- Skill: `skills/*/SKILL.md` (cài vào `~/.agents/skills/` cho `user`, `./.agents/skills/` cho `project`)
+
+Ví dụ:
+- Tác nhân: `architect`, `planner`, `executor`, `debugger`, `verifier`, `security-reviewer`
+- Skill: `autopilot`, `plan`, `team`, `ralph`, `ultrawork`, `cancel`
+
+## Cấu trúc dự án
+
+```text
+oh-my-codex/
+  bin/omx.js
+  src/
+    cli/
+    team/
+    mcp/
+    hooks/
+    hud/
+    config/
+    modes/
+    notifications/
+    verification/
+  prompts/
+  skills/
+  templates/
+  scripts/
+```
+
+## Phát triển
+
+```bash
+git clone https://github.com/Yeachan-Heo/oh-my-codex.git
+cd oh-my-codex
+npm install
+npm run build
+npm test
+```
+
+## Tài liệu
+
+- **[Tài liệu đầy đủ](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** — Hướng dẫn hoàn chỉnh
+- **[Tham chiếu CLI](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** — Tất cả lệnh `omx`, cờ và công cụ
+- **[Hướng dẫn thông báo](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#notifications)** — Cài đặt Discord, Telegram, Slack và webhook
+- **[Quy trình công việc khuyến nghị](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** — Chuỗi skill đã thử nghiệm thực chiến cho các tác vụ phổ biến
+- **[Ghi chú phát hành](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#release-notes)** — Tính năng mới trong mỗi phiên bản
+
+## Ghi chú
+
+- Nhật ký thay đổi đầy đủ: `CHANGELOG.md`
+- Hướng dẫn di chuyển (sau v0.4.4 mainline): `docs/migration-mainline-post-v0.4.4.md`
+- Ghi chú về độ bao phủ và tương đương: `COVERAGE.md`
+- Quy trình mở rộng hook: `docs/hooks-extension.md`
+- Chi tiết cài đặt và đóng góp: `CONTRIBUTING.md`
+
+## Lời cảm ơn
+
+Lấy cảm hứng từ [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), được điều chỉnh cho Codex CLI.
+
+## Giấy phép
 
-- Tài liệu chính: [README.md](./README.md)
-- Website: https://yeachan-heo.github.io/oh-my-codex-website/
+MIT

package/README.zh-TW.md

@@ -0,0 +1,362 @@
+# oh-my-codex (OMX)
+
+<p align="center">
+  <img src="https://yeachan-heo.github.io/oh-my-codex-website/omx-character-nobg.png" alt="oh-my-codex character" width="280">
+  <br>
+  <em>你的 Codex，從不孤行。</em>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/oh-my-codex)](https://www.npmjs.com/package/oh-my-codex)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+
+> **[官方網站](https://yeachan-heo.github.io/oh-my-codex-website/)** | **[說明文件](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** | **[CLI 參考手冊](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** | **[工作流程](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** | **[GitHub](https://github.com/Yeachan-Heo/oh-my-codex)** | **[npm](https://www.npmjs.com/package/oh-my-codex)**
+
+[OpenAI Codex CLI](https://github.com/openai/codex) 的多智能體編排層。
+
+## 語言
+
+- [English](./README.md)
+- [한국어 (Korean)](./README.ko.md)
+- [日本語 (Japanese)](./README.ja.md)
+- [简体中文 (Chinese Simplified)](./README.zh.md)
+- [繁體中文 (Chinese Traditional)](./README.zh-TW.md)
+- [Tiếng Việt (Vietnamese)](./README.vi.md)
+- [Español (Spanish)](./README.es.md)
+- [Português (Portuguese)](./README.pt.md)
+- [Русский (Russian)](./README.ru.md)
+- [Türkçe (Turkish)](./README.tr.md)
+- [Deutsch (German)](./README.de.md)
+- [Français (French)](./README.fr.md)
+- [Italiano (Italian)](./README.it.md)
+
+
+OMX 讓 Codex 從單一會話代理進化為協同運作的系統，具備以下能力：
+- 角色提示詞 (`/prompts:name`)，賦予代理各司其職的專業特質
+- 工作流程技能 (`$name`)，實現可重複執行的作業模式
+- 透過 tmux 互動模式（預設）或非 tmux 提示模式進行團隊編排 (`omx team`、`$team`)
+- 透過 MCP 伺服器實現持久化狀態與記憶
+
+## 為何選擇 OMX
+
+Codex CLI 擅長處理直接明確的任務。OMX 為更大規模的工作注入結構：
+- 分解任務並分階段執行 (`team-plan -> team-prd -> team-exec -> team-verify -> team-fix`)
+- 持久化的模式生命週期狀態 (`.omx/state/`)
+- 長時間運行會話所需的記憶與備忘錄介面
+- 啟動、驗證與取消的作業控制
+
+OMX 是插件，而非分支版本。它完全運用 Codex 的原生擴充點。
+
+## 定位：CLI 優先的編排層，MCP 支援的狀態管理
+
+OMX 最適合作為**外層 CLI 編排層**使用：
+- **控制平面（CLI/執行期）：** `omx team`、tmux 工作進程、生命週期指令
+- **能力/狀態平面（MCP）：** 任務狀態、信箱、記憶、診斷工具
+
+實際模式分工：
+- **`$team` / `omx team`**：耐久、可檢視、可恢復的多工作進程執行
+- **`$ultrawork`**：針對獨立任務的輕量平行扇出（元件模式）
+
+低 Token 消耗的團隊設定範例：
+
+```bash
+OMX_TEAM_WORKER_CLI=codex \
+OMX_TEAM_WORKER_LAUNCH_ARGS='--model gpt-5.3-codex-spark -c model_reasoning_effort="low"' \
+omx team 2:explore "短暫有界的分析任務"
+```
+
+## 系統需求
+
+- macOS 或 Linux（Windows 可透過 WSL2 使用）
+- Node.js >= 20（CI 驗證 Node 20 及目前 LTS，目前為 Node 22）
+- 已安裝 Codex CLI（`npm install -g @openai/codex`）
+- 已完成 Codex 身份驗證設定
+
+## 快速入門（3 分鐘）
+
+```bash
+npm install -g oh-my-codex
+omx setup
+omx doctor
+```
+
+推薦的信任環境啟動設定：
+
+```bash
+omx --xhigh --madmax
+```
+
+## v0.5.0 新功能
+
+- 透過 `omx setup --scope user|project` 實現**範圍感知設定** — 彈性的安裝模式。
+- 透過 `--spark` / `--madmax-spark` 實現 **Spark 工作進程路由** — 團隊工作進程可使用 `gpt-5.3-codex-spark`，無需強制套用領導者模型。
+- **目錄整合** — 移除已棄用的提示詞（`deep-executor`、`scientist`）及 9 個已棄用的技能，讓介面更為精簡。
+- **通知詳細程度等級** — 對 CCNotifier 輸出進行精細控制。
+
+## 首次會話
+
+在 Codex 內部：
+
+```text
+/prompts:architect "analyze current auth boundaries"
+/prompts:executor "implement input validation in login"
+$plan "ship OAuth callback safely"
+$team 3:executor "fix all TypeScript errors"
+```
+
+從終端機：
+
+```bash
+omx team 4:executor "parallelize a multi-module refactor"
+omx team status <team-name>
+omx team shutdown <team-name>
+```
+
+## 核心模型
+
+OMX 安裝並串接以下各層：
+
+```text
+使用者
+  -> Codex CLI
+    -> AGENTS.md（編排大腦）
+    -> ~/.codex/prompts/*.md（代理提示詞目錄）
+    -> ~/.agents/skills/*/SKILL.md（技能目錄）
+    -> ~/.codex/config.toml（功能、通知、MCP）
+    -> .omx/（執行期狀態、記憶、計畫、日誌）
+```
+
+## 主要指令
+
+```bash
+omx                  # 啟動 Codex（可用時在 tmux 中附帶 HUD）
+omx setup            # 依範圍安裝提示詞/技能/設定 + 專案 AGENTS.md/.omx
+omx doctor           # 安裝/執行期診斷
+omx doctor --team    # 團隊/群集診斷
+omx ask ...          # 詢問本地供應商顧問（claude|gemini），結果寫入 .omx/artifacts/*
+omx team ...         # 啟動/狀態/恢復/關閉團隊工作進程（預設為互動式 tmux）
+omx status           # 顯示目前活動模式
+omx cancel           # 取消活動中的執行模式
+omx reasoning <mode> # low|medium|high|xhigh
+omx tmux-hook ...    # init|status|validate|test
+omx hooks ...        # init|status|validate|test（插件擴充工作流程）
+omx hud ...          # --watch|--json|--preset
+omx help
+```
+
+Ask 指令範例：
+
+```bash
+omx ask claude "review this diff"
+omx ask gemini "brainstorm alternatives"
+omx ask claude --agent-prompt executor "implement feature X with tests"
+omx ask gemini --agent-prompt=planner --prompt "draft a rollout plan"
+# 底層供應商 CLI 說明中的旗標：
+# claude -p|--print "<prompt>"
+# gemini -p|--prompt "<prompt>"
+```
+
+非 tmux 團隊啟動（進階）：
+
+```bash
+OMX_TEAM_WORKER_LAUNCH_MODE=prompt omx team 2:executor "task"
+```
+
+## Hooks 擴充（附加介面）
+
+OMX 現已包含 `omx hooks`，用於插件鷹架建立與驗證。
+
+- `omx tmux-hook` 持續受支援，行為不變。
+- `omx hooks` 屬於附加功能，不會取代 tmux-hook 工作流程。
+- 插件檔案位於 `.omx/hooks/*.mjs`。
+- 插件預設關閉；使用 `OMX_HOOK_PLUGINS=1` 啟用。
+
+完整的擴充工作流程與事件模型，請參閱 `docs/hooks-extension.md`。
+
+## 啟動旗標
+
+```bash
+--yolo
+--high
+--xhigh
+--madmax
+--force
+--dry-run
+--verbose
+--scope <user|project>  # 僅用於 setup
+```
+
+`--madmax` 對應 Codex 的 `--dangerously-bypass-approvals-and-sandbox`。
+僅在信任環境或外部沙箱環境中使用。
+
+### MCP workingDirectory 策略（選用強化）
+
+預設情況下，MCP 狀態/記憶/追蹤工具接受呼叫方提供的 `workingDirectory`。
+若要限制此行為，請設定允許的根目錄清單：
+
+```bash
+export OMX_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another-root"
+```
+
+設定後，超出這些根目錄的 `workingDirectory` 值將被拒絕。
+
+## Codex 優先的提示詞控制
+
+預設情況下，OMX 注入：
+
+```text
+-c model_instructions_file="<cwd>/AGENTS.md"
+```
+
+這會將專案的 `AGENTS.md` 指引加入 Codex 啟動指令中。
+此舉擴充了 Codex 的行為，但不會取代或繞過 Codex 核心系統策略。
+
+控制方式：
+
+```bash
+OMX_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omx     # 停用 AGENTS.md 注入
+OMX_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omx
+```
+
+## 團隊模式
+
+對於能從平行工作進程獲益的大規模工作，請使用團隊模式。
+
+生命週期：
+
+```text
+啟動 -> 分配有界通道 -> 監控 -> 驗證終端任務 -> 關閉
+```
+
+作業指令：
+
+```bash
+omx team <args>
+omx team status <team-name>
+omx team resume <team-name>
+omx team shutdown <team-name>
+```
+
+重要規則：除非要中止，否則請勿在任務仍處於 `in_progress` 狀態時關閉。
+
+### Ralph 清理策略
+
+當團隊以 ralph 模式執行（`omx team ralph ...`）時，關閉清理
+會套用與一般路徑不同的專屬策略：
+
+| 行為 | 一般團隊 | Ralph 團隊 |
+|---|---|---|
+| 失敗時強制關閉 | 拋出 `shutdown_gate_blocked` | 略過閘門，記錄 `ralph_cleanup_policy` 事件 |
+| 自動刪除分支 | 復原時刪除 worktree 分支 | 保留分支（`skipBranchDeletion`） |
+| 完成日誌 | 標準 `shutdown_gate` 事件 | 附帶任務分解的 `ralph_cleanup_summary` 事件 |
+
+Ralph 策略會從團隊模式狀態（`linked_ralph`）自動偵測，
+也可透過 `omx team shutdown <name> --ralph` 明確傳遞。
+
+團隊工作進程的 Worker CLI 選擇：
+
+```bash
+OMX_TEAM_WORKER_CLI=auto    # 預設；當 worker --model 包含 "claude" 時使用 claude
+OMX_TEAM_WORKER_CLI=codex   # 強制使用 Codex CLI 工作進程
+OMX_TEAM_WORKER_CLI=claude  # 強制使用 Claude CLI 工作進程
+OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude  # 每個工作進程的 CLI 混合（長度為 1 或等於工作進程數量）
+OMX_TEAM_AUTO_INTERRUPT_RETRY=0  # 選用：停用自適應 queue->resend 回退機制
+```
+
+注意事項：
+- 工作進程啟動參數仍透過 `OMX_TEAM_WORKER_LAUNCH_ARGS` 共享。
+- `OMX_TEAM_WORKER_CLI_MAP` 會覆寫 `OMX_TEAM_WORKER_CLI`，以實現每個工作進程的個別選擇。
+- 觸發提交預設使用自適應重試（queue/submit，必要時採用安全的清除行 + 重傳回退）。
+- 在 Claude 工作進程模式下，OMX 以純 `claude` 啟動工作進程（無額外啟動參數），並忽略明確的 `--model` / `--config` / `--effort` 覆寫，讓 Claude 使用預設的 `settings.json`。
+
+## `omx setup` 寫入的內容
+
+- `.omx/setup-scope.json`（持久化的設定範圍）
+- 依範圍的安裝內容：
+  - `user`：`~/.codex/prompts/`、`~/.agents/skills/`、`~/.codex/config.toml`、`~/.omx/agents/`
+  - `project`：`./.codex/prompts/`、`./.agents/skills/`、`./.codex/config.toml`、`./.omx/agents/`
+- 啟動行為：若持久化範圍為 `project`，`omx` 啟動時自動使用 `CODEX_HOME=./.codex`（除非已設定 `CODEX_HOME`）。
+- 現有的 `AGENTS.md` 預設會保留。在互動式 TTY 執行時，setup 會在覆寫前詢問確認；`--force` 則不詢問直接覆寫（仍適用活動會話安全檢查）。
+- `config.toml` 更新（兩種範圍均適用）：
+  - `notify = ["node", "..."]`
+  - `model_reasoning_effort = "high"`
+  - `developer_instructions = "..."`
+  - `[features] multi_agent = true, child_agents_md = true`
+  - MCP 伺服器項目（`omx_state`、`omx_memory`、`omx_code_intel`、`omx_trace`）
+  - `[tui] status_line`
+- 專案 `AGENTS.md`
+- `.omx/` 執行期目錄與 HUD 設定
+
+## 代理與技能
+
+- 提示詞：`prompts/*.md`（`user` 安裝至 `~/.codex/prompts/`，`project` 安裝至 `./.codex/prompts/`）
+- 技能：`skills/*/SKILL.md`（`user` 安裝至 `~/.agents/skills/`，`project` 安裝至 `./.agents/skills/`）
+
+範例：
+- 代理：`architect`、`planner`、`executor`、`debugger`、`verifier`、`security-reviewer`
+- 技能：`autopilot`、`plan`、`team`、`ralph`、`ultrawork`、`cancel`
+
+### 視覺品管迴圈（`$visual-verdict`）
+
+當任務需要視覺保真度驗證（參考圖片 + 生成截圖）時，請使用 `$visual-verdict`。
+
+- 回傳結構化 JSON：`score`、`verdict`、`category_match`、`differences[]`、`suggestions[]`、`reasoning`
+- 建議通過門檻：**90 分以上**
+- 對於視覺任務，在每次下一輪編輯前先執行 `$visual-verdict`
+- 使用像素差異 / pixelmatch 疊加圖作為**輔助除錯工具**（而非主要通過/失敗判斷依據）
+
+## 專案結構
+
+```text
+oh-my-codex/
+  bin/omx.js
+  src/
+    cli/
+    team/
+    mcp/
+    hooks/
+    hud/
+    config/
+    modes/
+    notifications/
+    verification/
+  prompts/
+  skills/
+  templates/
+  scripts/
+```
+
+## 開發
+
+```bash
+git clone https://github.com/Yeachan-Heo/oh-my-codex.git
+cd oh-my-codex
+npm install
+npm run lint
+npm run build
+npm test
+```
+
+## 說明文件
+
+- **[完整說明文件](https://yeachan-heo.github.io/oh-my-codex-website/docs.html)** — 完整指南
+- **[CLI 參考手冊](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#cli-reference)** — 所有 `omx` 指令、旗標與工具
+- **[通知設定指南](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#notifications)** — Discord、Telegram、Slack 及 Webhook 設定
+- **[推薦工作流程](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#workflows)** — 實戰驗證的技能鏈，適用常見任務
+- **[版本發行說明](https://yeachan-heo.github.io/oh-my-codex-website/docs.html#release-notes)** — 每個版本的新功能
+
+## 附註
+
+- 完整變更日誌：`CHANGELOG.md`
+- 遷移指南（v0.4.4 後的主線版本）：`docs/migration-mainline-post-v0.4.4.md`
+- 覆蓋率與同等性說明：`COVERAGE.md`
+- Hook 擴充工作流程：`docs/hooks-extension.md`
+- 設定與貢獻詳情：`CONTRIBUTING.md`
+
+## 致謝
+
+靈感來自 [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)，為 Codex CLI 量身改編。
+
+## 授權條款
+
+MIT