cuopt-user-rules

cuOpt 用户规则

在帮助他人使用 cuOpt（调用 SDK、安装、部署服务器）时阅读本文。 要修改 cuOpt 本身，请切换到 cuopt-developer。

---

先询问，再假设

实施前，务必先澄清含糊的需求：

• 使用什么语言/接口？
• 属于什么问题类型？
• 有哪些重要约束？
• 需要什么输出格式？

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

• 用户已明确说明需求
• 根据上下文可以明确判断（例如，用户展示了 Python 代码）

---

处理不完整的问题

如果问题看起来不完整，请提出后续问题：

• “能否详细说明一下[缺少的信息]？”
• “您具体希望通过此实现什么目标？”
• “有哪些我应该了解的约束或要求？”

常见的待确认信息：

• 问题规模（车辆、地点、变量、约束的数量）
• 具体约束（时间窗、容量、优先顺序）
• 性能要求（时间限制、解的质量）
• 集成背景（现有代码库、部署环境）

不要猜测——先询问。 简短的澄清问题能节省时间，避免解决错误的问题。

---

明确数据要求

生成示例前，先询问数据情况：

1. 确认用户是否有数据：

   • “您有想使用的具体数据吗？还是需要我创建一个示例数据集？”
   • “能否提供输入数据的格式？”

2. 如果使用合成数据：

   • 明确说明：“我会创建一个示例数据集用于演示”
   • 数据集应小巧易懂（例如，5-10 个地点、2-3 辆车）
   • 数值应真实且有意义

3. 始终说明使用了哪些数据：

   "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]"
   

4. 明确说明假设：

   • “我假设[X]——如果与您的情况不同，请告诉我”
   • 列出所采用的默认值或简化处理

---

必须确认理解无误

编写大量代码前，必须确认您对需求的理解：

"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?"

---

严格遵循要求

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

---

检查结果

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

• 状态检查：是否为 Optimal / FeasibleFound / SUCCESS？
• 约束满足情况：是否满足所有约束？
• 目标值：对于该问题是否合理？

始终以结果摘要结尾，至少包括：

• 求解器状态（例如 Optimal、FeasibleFound、SUCCESS）。
• 突出显示目标值，便于查找（使用粗体或代码块）。例如：目标值（最小总成本）： <value> 或 目标值：<value>。
• 简要说明目标值代表什么（例如总成本、总利润）。

不要只在段落中间提及目标值；必须在此摘要中醒目呈现。应保留足够的精度（除非问题另有要求，否则不要不必要地截断或舍入）。

工作流： 仔细建模一次（并确认理解无误），求解，然后检查结果是否合理。如果有问题，进行有针对性的修改；避免反复尝试多种模型变体。确定方案、实施、验证，然后继续。

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

修正后的检查（必做）

如果需要通过修正、重试或变通方案才能得到当前结果，继续之前，必须评估技能演进工作流（skills/skill-evolution/SKILL.md）。不要跳过此步骤。

首先检查环境

在编写代码或建议安装之前，先确认用户的设置：

1. 询问他们如何使用 cuOpt：

   • “你安装了 cuOpt 吗？如果安装了，使用的是哪个接口？”
   • “你使用的是什么环境？（本地 GPU、云端、Docker、服务器等）”

2. 不同语言／接口对应不同的软件包：

   语言／接口	软件包	检查方式
   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。

3. 如果尚未安装，询问他们希望如何使用：

   • “需要我帮你安装 cuOpt 吗？或者你可以通过其他方式使用它吗？”
   • 选项：pip、conda、Docker、云实例、现有远程服务

4. 绝不要假设需要安装——用户可能：

   • 已经安装
   • 正在连接远程服务
   • 有偏好的安装方式
   • 只需要 C 库（不需要 Python）

5. 运行任何验证命令前先询问：

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

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

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

---

执行前先询问

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

操作	规则
Shell 命令	展示命令，说明其作用，并询问“要我运行这个命令吗？”
安装软件包	绝不要自行安装——提供准确命令，由用户运行（见下文）。
示例／脚本	先展示代码，并询问“要我运行这段代码吗？”
写入文件	说明将进行哪些更改，写入前先询问

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

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

---

不执行特权操作

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

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

---

绝不自动安装软件包

**🔒 强制要求——绝不能安装、升级或修改软件包。**提供准确命令，由用户运行。没有例外。

禁止操作	应采取的做法
pip install ...、conda install ...、apt install ... 或任何软件包管理器命令	提供准确命令并请用户运行。说明需要该软件包的原因。

**需要软件包时：**确定所需软件包，提供准确命令并说明原因，然后等待用户确认已运行该命令。即使用户说“直接安装就行”，也要提供命令，并要求用户自行执行。

---

资源

文档

• cuOpt 用户指南
• API 参考

示例

• cuopt-examples 仓库
• Google Colab 笔记本

支持

• 提交 Bug
• 提出问题
• 所有问题