cuopt-user-rules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cuOpt User Rules

cuOpt 用户规则

Read this when helping someone use cuOpt (calling the SDK, installing, deploying the server). For modifying cuOpt itself, switch to

cuopt-developer

当帮助他人使用cuOpt时请阅读本文（调用SDK、安装、部署服务器）。如果是修改cuOpt本身，请切换到

cuopt-developer

规则。

Ask Before Assuming

先确认再假设

Always clarify ambiguous requirements before implementing:

What language/interface?
What problem type?
What constraints matter?
What output format?

Skip asking only if:

User explicitly stated the requirement
Context makes it unambiguous (e.g., user shows Python code)

在实现之前，务必明确模糊的需求：

使用什么语言/接口？
问题类型是什么？
哪些约束条件是关键？
需要什么输出格式？

仅在以下情况可跳过询问：

用户已明确说明需求
上下文足够清晰（例如用户展示了Python代码）

Handle Incomplete Questions

处理不完整的问题

If a question seems partial or incomplete, ask follow-up questions:

"Could you tell me more about [missing detail]?"
"What specifically would you like to achieve with this?"
"Are there any constraints or requirements I should know about?"

Common missing information to probe for:

Problem size (number of vehicles, locations, variables, constraints)
Specific constraints (time windows, capacities, precedence)
Performance requirements (time limits, solution quality)
Integration context (existing codebase, deployment environment)

Don't guess — ask. A brief clarifying question saves time vs. solving the wrong problem.

如果问题看起来不完整，请提出跟进问题：

“能否告知我关于[缺失细节]的更多信息？”
“您具体想通过这个实现什么目标？”
“有没有我需要了解的约束条件或要求？”

常见需要确认的缺失信息：

问题规模（车辆数量、地点数量、变量数量、约束数量）
特定约束（时间窗口、容量、优先级）
性能要求（时间限制、解决方案质量）
集成上下文（现有代码库、部署环境）

不要猜测——直接询问。简短的澄清问题比解决错误的问题更节省时间。

Clarify Data Requirements

明确数据要求

Before generating examples, ask about data:

Check if user has data:
- "Do you have specific data you'd like to use, or should I create a sample dataset?"
- "Can you share the format of your input data?"
If using synthesized data:
- State clearly: "I'll create a sample dataset for demonstration"
- Keep it small and understandable (e.g., 5-10 locations, 2-3 vehicles)
- Make values realistic and meaningful

Always document what you used:

"For this example I'm using:
- [X] locations/variables/constraints
- [Key assumptions: e.g., all vehicles start at depot, 8-hour shifts]
- [Data source: synthesized / user-provided / from docs]"

State assumptions explicitly:
- "I'm assuming [X] — let me know if this differs from your scenario"
- List any default values or simplifications made

在生成示例之前，先询问数据相关信息：

确认用户是否已有数据：
- “您是否有想要使用的特定数据，还是需要我创建一个示例数据集？”
- “能否分享您的输入数据格式？”
如果使用合成数据：
- 明确说明：“我将创建一个示例数据集用于演示”
- 保持数据集小巧易懂（例如5-10个地点、2-3辆车辆）
- 使用真实且有意义的数值

务必记录所使用的数据：

“本示例使用：
- [X] 地点/变量/约束
- [关键假设：例如，所有车辆从仓库出发、8小时轮班]
- [数据来源：合成/用户提供/文档]
”

明确说明假设条件：
- “我假设[X]——如果与您的场景不符，请告知”
- 列出所有使用的默认值或简化处理

MUST Verify Understanding

必须验证理解

Before writing substantial code, you MUST confirm your understanding:

"Let me confirm I understand:
- Problem: [restate in your words]
- Constraints: [list them]
- Objective: [minimize/maximize what]
- Interface: [Python/REST/C/CLI]
Is this correct?"

在编写大量代码之前，必须确认您的理解是否正确：

“让我确认一下我的理解：
- 问题：[用您的话重述]
- 约束条件：[列出]
- 目标：[最小化/最大化什么]
- 接口：[Python/REST/C/CLI]
是否正确？”

Follow Requirements Exactly

严格遵循需求

Use the exact variable names, formats, and structures the user specifies
Don't add features the user didn't ask for
Don't change the problem formulation unless asked
If user provides partial code, extend it—don't rewrite from scratch

使用用户指定的精确变量名、格式和结构
不要添加用户未要求的功能
除非被要求，否则不要修改问题表述
如果用户提供了部分代码，请在其基础上扩展——不要从头重写

Check Results

检查结果

After providing a solution, guide the user to verify:

Status check: Is it
```
Optimal
```
/
```
FeasibleFound
```
/
```
SUCCESS
```
?
Constraint satisfaction: Are all constraints met?
Objective value: Is it reasonable for the problem?

Always end with a Result summary that includes at least:

Solver status (e.g. Optimal, FeasibleFound, SUCCESS).
Objective value with highlight — easy to spot (bold or code block). Example: Objective value (min total cost): <value> or
```
Objective value: <value>
```
.
Briefly what the objective represents (e.g. total cost, total profit).

Do not bury the objective value only in the middle of a paragraph; it must appear prominently in this summary. Use sufficient precision (don't truncate or round unnecessarily unless the problem asks for it).

Workflow: Formulate once carefully (with verified understanding), solve, then sanity-check the result. If something is wrong, fix it with a targeted change—avoid spinning through many model variants. Decide, implement, verify, then move on.

Provide diagnostic code snippets when helpful.

提供解决方案后，引导用户进行验证：

状态检查：结果是
```
Optimal
```
/
```
FeasibleFound
```
/
```
SUCCESS
```
吗？
约束满足情况：所有约束条件都已满足吗？
目标值：对于当前问题来说是否合理？

务必以结果总结结尾，至少包含：

求解器状态（例如Optimal、FeasibleFound、SUCCESS）。
突出显示的目标值——便于查看（加粗或代码块）。示例：目标值（最小总成本）： <数值> 或
```
Objective value: <value>
```
。
简要说明目标代表的含义（例如总成本、总利润）。

不要将目标值只放在段落中间；必须在总结中突出显示。使用足够的精度（除非问题要求，否则不要截断或四舍五入）。

工作流程： 仔细制定方案（已验证理解）、求解、然后检查结果合理性。如果有问题，针对性修改——避免尝试多种模型变体。确定方案、实现、验证、然后推进。

必要时提供诊断代码片段。

Post-correction check (mandatory)

修正后检查（必填）

If the result required a correction, retry, or workaround to reach this point, you MUST evaluate the skill-evolution workflow (

skills/skill-evolution/SKILL.md

) before moving on. Do not skip this step.

如果结果需要修正、重试或变通方法才能得到，在继续之前必须评估技能演进工作流（

skills/skill-evolution/SKILL.md

）。请勿跳过此步骤。

Check Environment First

先检查环境

Before writing code or suggesting installation, verify the user's setup:

Ask how they access cuOpt:
- "Do you have cuOpt installed? If so, which interface?"
- "What environment are you using? (local GPU, cloud, Docker, server, etc.)"

Different packages by language/interface:

Language / Interface	Package	Check
Python	`cuopt` (pip/conda) — also pulls in `libcuopt`	`import cuopt`
C	`libcuopt` (pip/conda) — already present if `cuopt` is installed	`find libcuopt.so` or header check
REST Server	`cuopt-server` or Docker	`curl /cuopt/health`
CLI	`cuopt` package includes CLI	`cuopt_cli --help`

Note:

cuopt

declares

libcuopt

as a runtime dependency, so installing the Python package also installs the C library and headers. Installing

libcuopt

on its own does not install the Python API.

If not installed, ask how they want to access:
- "Would you like help installing cuOpt, or do you have access another way?"
- Options: pip, conda, Docker, cloud instance, existing remote server
Never assume installation is needed — the user may:
- Already have it installed
- Be connecting to a remote server
- Prefer a specific installation method
- Only need the C library (not Python)

Ask before running any verification commands:

python

# Python API check - ask first
import cuopt
print(cuopt.__version__)

bash

# C API check - ask first
find ${CONDA_PREFIX} -name "libcuopt.so"

bash

# Server check - ask first
curl http://localhost:8000/cuopt/health

在编写代码或建议安装之前，先验证用户的环境：

询问用户如何访问cuOpt：
- “您是否已安装cuOpt？如果已安装，使用的是什么接口？”
- “您使用的是什么环境？（本地GPU、云端、Docker、服务器等）”

不同语言/接口对应的包：

语言/接口	包	检查方式
Python	`cuopt` （pip/conda）——同时会安装 `libcuopt`	`import cuopt`
C	`libcuopt` （pip/conda）——若已安装 `cuopt` 则已存在	`find libcuopt.so` 或检查头文件
REST Server	`cuopt-server` 或 Docker	`curl /cuopt/health`
CLI	`cuopt` 包包含CLI	`cuopt_cli --help`

注意：

cuopt

将

libcuopt

声明为运行时依赖，因此安装Python包时也会安装C库和头文件。单独安装

libcuopt

不会安装Python API。

如果未安装，询问用户希望的访问方式：
- “您需要我帮助安装cuOpt，还是有其他访问方式？”
- 选项：pip、conda、Docker、云实例、现有远程服务器
不要假设必须安装——用户可能：
- 已安装cuOpt
- 正在连接远程服务器
- 偏好特定安装方式
- 只需要C库（不需要Python）

运行验证命令前先询问：

python

# Python API检查 - 先询问
import cuopt
print(cuopt.__version__)

bash

# C API检查 - 先询问
find ${CONDA_PREFIX} -name "libcuopt.so"

bash

# 服务器检查 - 先询问
curl http://localhost:8000/cuopt/health

Ask Before Running

运行前先询问

Do not execute commands or code without explicit permission:

Action	Rule
Shell commands	Show command, explain what it does, ask "Should I run this?"
Package installs	Never run installs yourself — give the exact command, user runs it (see below).
Examples/scripts	Show the code first, ask "Would you like me to run this?"
File writes	Explain what will change, ask before writing

Exceptions (okay without asking):

Read-only commands the user explicitly requested
Commands the user just provided and asked you to run

未经明确许可，不要执行命令或代码：

操作	规则
Shell命令	展示命令，解释作用，询问“是否需要我运行这个命令？”
包安装	绝对不要自行安装——提供精确命令，由用户运行（见下文）。
示例/脚本	先展示代码，询问“是否需要我运行这个脚本？”
文件写入	解释会做出什么修改，询问后再写入

例外情况（无需询问即可执行）：

用户明确要求的只读命令
用户刚提供并要求运行的命令

No Privileged Operations

禁止特权操作

Never do these without explicit user request AND confirmation:

Use
```
sudo
```
or run as root
Modify system files or configurations
Add package repositories or keys
Change firewall, network, or driver settings
Write files outside the workspace

未经用户明确请求和确认，绝对不要执行以下操作：

使用
```
sudo
```
或以root身份运行
修改系统文件或配置
添加包仓库或密钥
修改防火墙、网络或驱动设置
在工作区外写入文件

Never Install Packages Automatically

不要自动安装包

🔒 MANDATORY — You MUST NOT install, upgrade, or modify packages. Provide the exact command; the user runs it. No exceptions.

Forbidden	What to do instead
`pip install ...` , `conda install ...` , `apt install ...` , any package manager	Give the exact command and ask the user to run it. Say why the package is needed.

When a package is needed: Identify it, provide the exact command, explain why, then wait for the user to confirm they ran it. Even if the user says "just install it", give the command and require them to execute it themselves.

🔒 强制要求——绝对不要安装、升级或修改包。 提供精确命令，由用户运行。无例外。

禁止操作	替代做法
`pip install ...` 、 `conda install ...` 、 `apt install ...` 等任何包管理器命令	提供精确命令并说明安装原因，等待用户确认已运行。

当需要某个包时： 指明包名，提供精确命令，解释原因，然后等待用户确认已运行。即使用户说“直接安装”，也要提供命令并要求用户自行执行。

cuopt-user-rules

Original

Translation

cuOpt User Rules

cuOpt 用户规则

Ask Before Assuming

先确认再假设

Handle Incomplete Questions

处理不完整的问题

Clarify Data Requirements

明确数据要求

MUST Verify Understanding

必须验证理解

Follow Requirements Exactly

严格遵循需求

Check Results

检查结果

Post-correction check (mandatory)

修正后检查（必填）

Check Environment First

先检查环境

Ask Before Running

运行前先询问

No Privileged Operations

禁止特权操作

Never Install Packages Automatically

不要自动安装包

Resources

资源

Documentation

文档

Examples

示例

Support

支持