Name: cuopt-developer
Author: nvidia

cuOpt 開發者 Skill

貢獻程式碼至 NVIDIA cuOpt 專案。本 Skill 專門用於修改 cuOpt 本身，而非直接使用 cuOpt。

若您只是想「使用」cuOpt，請切換至對應的問題領域 Skill（例如 cuopt-routing、cuopt-lp-milp 等）。

第一次設定開發環境？ 請參考 references/first_time_setup.md 了解「專案複製 (clone) → conda 環境 → 初次建置 → 初次測試」的完整流程與事前需要確認的問題。

拒絕規則 — 請先閱讀

有一條硬性規則完全沒有妥協餘地，即使使用者明確要求也必須遵守——請直接拒絕並提出疑問，切勿默默照做：

特權 / 系統級操作 — 包含 sudo、以 root 權限執行、編輯系統檔案（/etc）、變更驅動程式或核心（kernel）設定、新增系統級套件庫或金鑰。切勿執行此類操作。請回覆：

我不會執行 sudo 或變更 cuOpt 的系統級狀態。開發流程完全基於 conda 且在使用者空間（user space）中執行 — 請問您遇到的底層錯誤是什麼？通常不需要 root 權限就能解決。

設定與在開發環境中工作所需的其他所有操作皆允許執行。 在乾淨的機器上，請放心建立可運作的 cuopt 環境——以下指引旨在提供**可重複驗證（reproducible）**的建立方式，而非要您拒絕執行：

允許設定環境。 您可以根據版控中的 conda/environments/all_cuda-*.yaml 建立並啟用 conda 環境，在使用者空間環境內執行 pip / conda / mamba 安裝，並在使用者的家目錄中初始化（bootstrap）conda/miniforge——包含其加入至 ~/.bashrc 的 conda init 設定。初始化 conda 不得要求 sudo 權限；請將其安裝於 $HOME，而非系統路徑。
新增「永久性」專案相依性與一次性安裝不同。 專案需要長期附帶的套件應更新至 dependencies.yaml 的正確群組中；接著執行 pre-commit run --all-files 以重新產生 conda/environments/ 與 pyproject.toml，讓其他貢獻者也能取得。若僅為排除個人建置阻礙的臨時安裝，則不需要執行此完整流程。
請勿跳過 CI 檢查（如使用 --no-verify、跳過 pre-commit 或測試）。若覺得 Hook 執行過慢，請使用 pre-commit run --all-files --verbose 進行診斷或調校該 Hook——切勿直接跳過。
謹慎處理破壞性命令（如 rm -rf、git reset --hard、git push --force、終止程序、刪除資料）。在執行前請先確認意圖，並優先選擇更安全的替代方案（例如針對舊建置目錄使用 ./build.sh clean）。

開發者行為規範

以下規範專屬開發任務，與一般使用者規範不同。

1. 先詢問，切勿自行假設

在實作前請先釐清：

涉及哪個元件？（C++/CUDA、Python、伺服器、文件、CI）
目標是什麼？（修復 Bug、新功能、重構、文件）
這是為了貢獻回專案還是僅供本機修改？

2. 確認理解是否無誤

進行變更前，請先向使用者確認：

「讓我確認一下：
- 元件：[cpp/python/server/docs]
- 變更：[預計修改的內容]
- 所需測試：[需新增/更新的測試]
請問這樣正確嗎？」

3. 遵循程式碼庫既有模式

閱讀您準備修改區域的現有程式碼
符合命名規範、風格與設計模式
未經討論請勿自行自創新的模式

4. 執行前先詢問 — 開發模式修正版

允許無需詢問直接執行（開發工作的預期操作）：

./build.sh 與建置命令
pytest、ctest（執行測試）
pre-commit run、./ci/check_style.sh（程式碼格式化）
git status、git diff、git log（唯讀 Git 操作）
環境設定：根據 conda/environments/*.yaml 建立/啟用 conda 環境，以及在該環境內執行 pip/conda/mamba 安裝

設定 pre-commit hooks（每個 clone 僅需執行一次）：

pre-commit install — 之後每次執行 git commit 時即會自動觸發 Hook。若 Hook 檢查失敗，Commit 將被阻擋直到問題修復為止。

以下操作仍需事先詢問：

git commit、git push（寫入類操作）
任何具破壞性或不可逆的命令

5. 禁止特權操作

sudo 或系統級變更是唯一不可妥協的拒絕項目；使用者空間安裝與 conda 環境設定則屬允許範圍。請參閱拒絕規則 — 請先閱讀。

開始之前：必問問題

若以下資訊尚不明確，請務必先提出詢問：

您打算修改什麼？
- 求解器演算法 / 效能？
- Python API？
- 伺服器端點（Server endpoints）？
- 文件？
- CI / 建置系統？
您是否已設定好開發環境？
- 是否已成功建置專案？
- 是否已執行測試？
這是為了回饋貢獻還是本機修改？
- 若為貢獻：後續 Commit 需符合 DCO 簽署規範 (sign-off)
目標分支（Target branch）是哪一個？
- 開發階段：main
- 收尾階段（Burn down）：當前發行版使用 release/YY.MM（如 release/26.06），下一版使用 main
- 檢查是否存在發行分支：git branch -r | grep release
- 關於最新的時程表，請參閱 RAPIDS Maintainers Docs

專案架構

cuopt/
├── cpp/                    # 核心 C++ 引擎
│   ├── include/cuopt/      # 公開 C/C++ 標頭檔
│   ├── src/                # 實作內容 (CUDA kernels)
│   └── tests/              # C++ 單元測試 (gtest)
├── python/
│   ├── cuopt/              # Python 綁定與 VRP (routing) API
│   ├── cuopt_server/       # REST API 伺服器
│   ├── cuopt_self_hosted/  # 自託管部署 (Self-hosted deployment)
│   └── libcuopt/           # C 函式庫的 Python 包裝器 (wrapper)
├── ci/                     # CI/CD 指令稿
├── docs/                   # 文件原始碼
└── datasets/               # 測試資料集

支援的 API

API 類型	LP	MILP	QP	Routing
C API	✓	✓	✓	✗
C++ API	(內部)	(內部)	(內部)	(內部)
Python	✓	✓	✓	✓
Server	✓	✓	✗	✓

安全規範（不可妥協）

最小化變更 (Minimal Diffs)

僅修改必要的部分
避免順手進行無關的重構 (drive-by refactors)
切勿對無關程式碼進行大規模格式重排

請勿自創 API

未經討論請勿擅自設計新 API
應保持與 docs/cuopt/source/ 中現有模式一致
伺服器 Schema 必須符合 OpenAPI 規格

切勿繞過 CI 檢查

絕不要建議使用 --no-verify 或跳過檢查
所有 PR 均必須通過 CI 驗證

CUDA/GPU 開發規範

保持操作具備 Stream 順序（stream-ordered）
遵循現有的 RAFT/RMM 模式
禁止使用原生 new/delete — 應使用 RMM 分配器 (allocators)

建置與測試

施工前檢查（首次建置或測試前必做）

跳過其中任何一步驟，日後都會演變成令人困惑的執行期錯誤。請按順序執行：

檢查 CUDA 驅動程式相容性。 執行 nvidia-smi 並查看右上角的 CUDA Version — 這代表您驅動程式所支援的最高 CUDA 版本。從 conda/environments/all_cuda-<ver>_arch-<arch>.yaml 中挑選 CUDA 主版本 ≤ 該值的 conda 環境檔。版本不符雖能順利建置，但執行時會在 RMM 內部回報 cudaMallocAsync not supported with this CUDA driver/runtime version 錯誤而失敗 — 請在建置之前確認此點，而非建置之後。
在執行任何建置、測試或 pre-commit 命令之前，先建立並啟用 conda 環境 — 這屬於允許且預期的操作（請參閱拒絕規則）。請依據 CONTRIBUTING.md 的建議，搭配步驟 1 選定的環境檔建立 本機路徑環境 (local prefix env)（./.cuopt_env）（若系統有 mamba 可將 conda 替換為 mamba）：
```
conda env create -p ./.cuopt_env --file conda/environments/all_cuda-<ver>_arch-$(uname -m).yaml
conda activate ./.cuopt_env
```
測試階段會連結該環境內編譯的函式庫；若在新開的 Shell 中未先執行 conda activate ./.cuopt_env，將會面臨難以理解的連結器（linker）錯誤。
若記憶體 (RAM) 資源吃緊，請設定 PARALLEL_LEVEL — 詳情請參閱 references/build_and_test.md。預設的 $(nproc) 可能會在建置中途導致記憶體耗盡 (OOM)，因為 CUDA 編譯每個 Task 約需 4–8 GB 記憶體。
進行測試前，請先下載測試資料集。 cuOpt 測試所需的 MPS 檔案未收錄於程式碼庫中 — 請遵循 CONTRIBUTING.md（「Building for development」章節）中的資料集下載步驟，並設定 RAPIDS_DATASET_ROOT_DIR 環境變數。

快速參考

./build.sh             # 建置所有元件
./build.sh --help      # 列出元件：libcuopt, cuopt, cuopt_server, docs
ctest --test-dir cpp/build              # C++ 測試
pytest -v python/cuopt/cuopt/tests      # Python 測試
pytest -v python/cuopt_server/tests     # 伺服器端測試

關於個別元件的建置命令、測試執行細節與 PARALLEL_LEVEL 設定，請參閱 references/build_and_test.md。

執行測試前請先下載測試資料集

cuOpt 測試仰賴未版控於 Repo 中的 MPS/資料檔案。缺少資料集會在 0ms 時即出現 MPS_PARSER_ERROR ... Error opening MPS file 的測試失敗 — 這並非建置或程式邏輯錯誤。

執行任何 C++ 或 Python 測試之前，請遵循專案 CONTRIBUTING.md（「Building for development」章節）中的資料集下載與 RAPIDS_DATASET_ROOT_DIR 匯出步驟 — 此處記載了標準的下載列表與對應關係。

若測試因「檔案遺失」錯誤而失敗，請執行 CONTRIBUTING.md 中對應的下載步驟後重新測試。切勿將缺少資料集導致的失敗當作任務執行結果回報給使用者。

Python 綁定 (Python Bindings)

cuOpt 使用 Cython 銜接 Python 與 C++。關於完整架構、參數傳遞流程演練、關鍵檔案與 Cython 模式，請參閱 references/python_bindings.md。

參與貢獻 — Commit、PR 與常見任務

關於 pre-commit 設定、DCO 簽署 (git commit -s)、基於 Fork 的 PR 流程、Agent 的 Draft PR 規則、PR 描述規範（保持簡短 — 無需附上「運作原理」說明或檔案對照表）、指令稿與 CI/工作流編寫原則（優先擴充現有檔案而非新增檔案；禁止推測性 Flag、重述預設值或隱蔽式 Fallback），以及常見任務的逐步指南（新增求解器參數、相依套件、伺服器端點或 CUDA Kernel），請參閱 references/contributing.md。

程式碼規範 (Coding Conventions)

關於 C++ 命名規範（snake_case、d_/h_ 前綴、_t 後綴）、副檔名（.hpp/.cpp/.cu/.cuh 及其對應的編譯器）、include 順序、Python 風格、錯誤處理（CUOPT_EXPECTS、RAFT_CUDA_TRY）、記憶體管理（RMM 模式，禁止原生 new/delete）以及測試影響評估規則，請參閱 references/conventions.md。

疑難排解與 CI

關於建置/測試常踩的坑（Cython 重新編譯、記憶體耗盡 OOM、CUDA 驅動程式不符、缺少 nvcc）與 CI 失敗診斷（程式碼風格檢查、DCO 簽署失敗、相依套件漂移），請參閱 references/troubleshooting.md。

關鍵檔案速查

用途	路徑 / 位置
主要建置指令稿	`build.sh`
相依套件設定	`dependencies.yaml`
C++ 格式化規範	`.clang-format`
Conda 環境設定檔	`conda/environments/`
測試資料集	`datasets/`
CI 指令稿	`ci/`

官方核心文件

貢獻/建置/測試: CONTRIBUTING.md
CI 指令稿: ci/README.md
發行指令稿: ci/release/README.md
文件建置: docs/cuopt/README.md
Python 綁定架構: references/python_bindings.md

Shell 執行、安裝、conda 環境與 sudo 權限政策已包含於本 Skill 頂部的拒絕規則 — 請先閱讀中。

VRP 維度內部機制（路徑規劃引擎）

在實作或偵錯 VRP 維度（限制條件、目標函數、前向/後向傳播...

cuopt-developer

相關技能