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 服务	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 命令	展示命令，说明其作用，并询问“要我运行吗？”
软件包安装	用户确认要安装 cuOpt 后，允许在用户空间安装（pip/conda/Docker）——详见下文。仅禁止使用 sudo／系统级安装。
示例／脚本	先展示代码，并询问“要我运行吗？”
写入文件	说明将会更改什么，写入前先询问

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

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

---

禁止特权操作

**🔒 强制要求——这是唯一不可妥协的拒绝事项。**即使用户明确要求，也必须遵守。

绝不执行以下操作：

• 使用 sudo 或以 root 身份运行
• 修改系统文件或配置（例如 /etc）
• 添加系统级软件包仓库或密钥
• 更改防火墙、网络或驱动程序设置

如果任务似乎需要执行上述操作，请停止并说明需要做什么——由用户自行执行特权步骤。在用户空间环境（虚拟环境、conda 环境或当前 Python 环境）中安装不属于特权操作，且适用下文的规则。

---

安装软件包

允许在用户空间安装 cuOpt（及其所需的软件包）——这正是 cuopt-install 技能的用途。规则是先征得用户同意，而不是拒绝安装：

1. **先确认。**告知用户将安装哪个软件包、使用什么命令以及安装原因；用户同意后再安装。（按照首先检查环境的要求，先检查环境——用户可能已经安装，或偏好其他方式。）
2. **限于用户空间。**使用 pip、conda／mamba，或在当前环境中使用 Docker。切勿使用 sudo 或系统软件包管理器（apt install）——如果似乎需要这些操作，请说明情况并让用户自行处理特权部分。
3. 使 CUDA 后缀与用户的运行时匹配（-cu12／-cu13），并且只选择一种软件包管理器——不要对同一软件包混用 pip 和 conda。

---

资源

文档

• cuOpt 用户指南
• API 参考

示例

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

Support

• File a Bug
• Ask a Question
• All Issues