From 5fa6f72b1a3fdd5bd7db65f1f07a09d2574923c2 Mon Sep 17 00:00:00 2001 From: conanxu <1845830029@qq.com> Date: Wed, 2 Sep 2026 17:42:38 +0800 Subject: [PATCH] docs: add bilingual OptSkills walkthrough --- skills/optskills/README.md | 25 ++- skills/optskills/README.zh-CN.md | 22 ++- .../optskills/assignment-problem-example.md | 166 ++++++++++++++++++ .../assignment-problem-example.zh-CN.md | 153 ++++++++++++++++ 4 files changed, 348 insertions(+), 18 deletions(-) create mode 100644 skills/optskills/assignment-problem-example.md create mode 100644 skills/optskills/assignment-problem-example.zh-CN.md diff --git a/skills/optskills/README.md b/skills/optskills/README.md index 2ca2005..a573850 100644 --- a/skills/optskills/README.md +++ b/skills/optskills/README.md @@ -1,5 +1,7 @@ # OptSkills +[中文](README.zh-CN.md) + OptSkills is a standalone thin entrypoint to 103 released OptSkills problem-archetype cards. It helps an agent select a card, formulate the user's actual operations-research problem, solve it when the environment @@ -11,17 +13,19 @@ The library contains 93 NanoCO cards and 10 learned-only cards. It includes no cluster duplicate and no `ingredients.json`. The selected cards and their relative paths are listed in `skill_library/index.json`. -## Installation +## Install with a coding agent + +Give this prompt to your coding agent: -Clone `VeryMath/AI4Math-Optimization`, then link only `skills/optskills` into -the agent's skill directory: +> Install `skills/optskills` from the GitHub repository +> `VeryMath/AI4Math-Optimization`. Install only this standalone Skill. Detect +> the skill directory used by the current coding agent, link or copy the +> package there, and verify that `optskills` is discoverable. Report the +> installed path, whether a restart is needed, and one test prompt. -```bash -git clone https://github.com/VeryMath/AI4Math-Optimization.git -cd AI4Math-Optimization -mkdir -p ~/.codex/skills -ln -s "$PWD/skills/optskills" ~/.codex/skills/optskills -``` +The coding agent should clone or update the repository, locate the correct +skill directory for its environment, install the package, and verify +discovery. The user does not need to choose a local directory first. ## Quick start @@ -31,6 +35,9 @@ Use this prompt: > `skill_library/index.json`, formulate my problem, solve it if possible, and > check the key constraints. +See [Solving an assignment problem with OptSkills](assignment-problem-example.md) +for a complete walkthrough. + ## Updates Use this prompt only when an upstream update is wanted: diff --git a/skills/optskills/README.zh-CN.md b/skills/optskills/README.zh-CN.md index 3e1702c..2a83c2a 100644 --- a/skills/optskills/README.zh-CN.md +++ b/skills/optskills/README.zh-CN.md @@ -1,5 +1,7 @@ # OptSkills +[English](README.md) + OptSkills 是一个独立的薄入口，连接 103 张已发布的 OptSkills 问题原型卡片。它帮助智能体选择卡片、为用户的实际运筹问题建模、在环境允许时求解，并如实报告已检查的内容。 @@ -9,17 +11,17 @@ OptSkills 是一个独立的薄入口，连接 103 张已发布的 OptSkills cluster 卡片，也不包含 `ingredients.json`。选中的卡片及其相对路径列在 `skill_library/index.json` 中。 -## 安装 +## 让 Coding Agent 安装 + +把下面的提示词发给 Coding Agent： -克隆 `VeryMath/AI4Math-Optimization`，然后只把 `skills/optskills` -链接到智能体的技能目录： +> 请从 GitHub 仓库 `VeryMath/AI4Math-Optimization` 安装 +> `skills/optskills`。只安装这个独立 Skill，自动判断当前 Coding Agent +> 的技能目录，完成链接或复制并验证能否发现 `optskills`。最后告诉我安装 +> 路径、是否需要重启，并给出一个测试提示词。 -```bash -git clone https://github.com/VeryMath/AI4Math-Optimization.git -cd AI4Math-Optimization -mkdir -p ~/.codex/skills -ln -s "$PWD/skills/optskills" ~/.codex/skills/optskills -``` +Coding Agent 应负责克隆或更新仓库、找到当前环境的技能目录、完成安装并 +验证发现结果。用户不需要先判断应使用哪个本地目录。 ## 快速开始 @@ -28,6 +30,8 @@ ln -s "$PWD/skills/optskills" ~/.codex/skills/optskills > 阅读 `SKILL.md`，通过 `skill_library/index.json` 选择相关的 OptSkills > 卡片，为我的问题建模，在可以时求解，并检查关键约束。 +完整过程见[用 OptSkills 求解一个指派问题](assignment-problem-example.zh-CN.md)。 + ## 更新 只有需要上游更新时才使用下面的提示： diff --git a/skills/optskills/assignment-problem-example.md b/skills/optskills/assignment-problem-example.md new file mode 100644 index 0000000..af802fe --- /dev/null +++ b/skills/optskills/assignment-problem-example.md @@ -0,0 +1,166 @@ +# Solving an assignment problem with OptSkills + +[中文](assignment-problem-example.zh-CN.md) + +This walkthrough shows one complete OptSkills use: ask a coding agent to +install the standalone Skill, describe an optimization problem in natural +language, select a released archetype card, formulate and solve the model, and +check the returned objective and constraints. + +## Ask a coding agent to install it + +Give this prompt to Codex, Claude Code, OpenCode, or another coding agent that +supports Skills: + +```text +Install skills/optskills from the GitHub repository +VeryMath/AI4Math-Optimization. Install only this standalone Skill. Detect the +skill directory used by the current coding agent, link or copy the package, +and verify that a new session can discover optskills. Report: +1. where the repository is stored; +2. where the Skill is installed; +3. whether discovery was verified; +4. whether a restart or new conversation is needed; +5. one prompt I can use to test it. +If the destination already exists, do not overwrite it immediately. First +check whether it comes from the same repository and explain what should happen. +``` + +The coding agent chooses the installation location from the discovery rules of +its current environment. Installation means more than copying files: it should +also confirm that a new session can see a Skill named `optskills`. + +## Submit the problem + +After installation, start a new conversation and enter: + +```text +Use OptSkills to solve this assignment problem. + +Five virtual machines must be assigned to five physical servers. Every virtual +machine must use exactly one server, and every server must receive exactly one +virtual machine. Rows in this cost matrix are virtual machines and columns are +servers: + +[[28, 15, 51, 19, 72], + [46, 44, 24, 14, 55], + [14, 18, 35, 61, 30], + [34, 41, 26, 50, 37], + [40, 53, 15, 62, 15]] + +Minimize the total assignment cost. Report the selected Skill, mathematical +model, solver status, assignment, objective, and constraint checks. If no +solver is available, identify the missing dependency instead of claiming that +the problem was solved. +``` + +The data come from the public OptSkills record `AP_easy_1`. + +## How OptSkills handles it + +The agent first makes the package's lightweight upstream commit comparison. A +matching version is silent. A failed lookup or newer version produces one short +note and does not download the full upstream project during this task. + +The agent then reads `skill_library/index.json`. The one-to-one assignment, +linear cost objective, and two families of exact-one constraints lead it to: + +```text +skill_id: assignment_problem_solver +path: skill_library/assignment_problem_solver.md +``` + +It loads this relevant card rather than all 103 cards. + +## Formulate the model + +Let the virtual-machine and server sets be + +$$ +I=J=\{1,2,3,4,5\}. +$$ + +Set $x_{ij}=1$ when virtual machine $i$ is assigned to server $j$, and set it +to zero otherwise. Let $c_{ij}$ be the corresponding cost. The model is + +$$ +\min \sum_{i\in I}\sum_{j\in J}c_{ij}x_{ij}, +$$ + +subject to + +$$ +\sum_{j\in J}x_{ij}=1\qquad \forall i\in I, +$$ + +$$ +\sum_{i\in I}x_{ij}=1\qquad \forall j\in J, +$$ + +and + +$$ +x_{ij}\in\{0,1\}. +$$ + +The first constraints assign every virtual machine exactly once. The second +constraints use every server exactly once. + +## Solver result + +In the OR-Tools CP-SAT environment used for repository validation, the solver +returned `OPTIMAL` with this assignment: + +| Virtual machine | Server | Cost | +| --- | --- | ---: | +| 1 | 2 | 15 | +| 2 | 4 | 14 | +| 3 | 1 | 14 | +| 4 | 3 | 26 | +| 5 | 5 | 15 | + +The total cost is + +$$ +15+14+14+26+15=84. +$$ + +## Check the result + +The agent should independently check the returned assignment instead of only +repeating the solver's objective field: + +- solver status is `OPTIMAL`; +- all five virtual-machine assignment counts equal 1; +- all five server usage counts equal 1; +- the recomputed total cost is 84; +- the recomputed result equals the solver objective. + +Only after these checks can it report that this instance was solved and its +constraints were verified. + +## If no solver is available + +OptSkills does not bundle OR-Tools, Pyomo, HiGHS, or a commercial solver. If a +suitable solver is absent, the agent can still report the selected card, +mathematical model, and solver code. It must distinguish “model formulated” +from “solver executed” and ask before installing a new dependency. + +## Try another problem + +After one installation, a new conversation can use prompts such as: + +```text +Use OptSkills to formulate a minimum-cost flow problem with arc capacities and +unit transportation costs. After solving it, check every node balance and arc +capacity. +``` + +```text +Use OptSkills to formulate a flow-shop scheduling problem for multiple jobs and +machines. Minimize makespan and check operation order and machine non-overlap. +``` + +For each task, report the selected card, formulated model, whether a solver was +actually executed, objective check, constraint check, and remaining limitations +as separate results. diff --git a/skills/optskills/assignment-problem-example.zh-CN.md b/skills/optskills/assignment-problem-example.zh-CN.md new file mode 100644 index 0000000..912c38a --- /dev/null +++ b/skills/optskills/assignment-problem-example.zh-CN.md @@ -0,0 +1,153 @@ +# 用 OptSkills 求解一个指派问题 + +[English](assignment-problem-example.md) + +这里记录一次完整的 OptSkills 使用过程：让 Coding Agent 安装独立 Skill， +输入一个自然语言优化问题，选择论文发布的原型卡片，建立模型，调用求解器， +再检查目标值和约束。 + +## 让 Coding Agent 安装 + +把下面的提示词直接发给 Codex、Claude Code、OpenCode 或其他支持 Skills 的 +Coding Agent： + +```text +请从 GitHub 仓库 VeryMath/AI4Math-Optimization 安装 skills/optskills。 +只安装这个独立 Skill。请自动判断当前 Coding Agent 使用的技能目录，完成 +链接或复制，验证新会话能否发现 optskills，并告诉我： +1. 仓库保存在哪里； +2. Skill 安装在哪里； +3. 是否验证成功； +4. 是否需要重启或新建对话； +5. 一个可以直接测试的提示词。 +如果目标位置已经存在，不要直接覆盖，先检查它是否来自同一仓库并说明处理方式。 +``` + +Coding Agent 会根据当前工具的发现规则选择安装位置。安装完成不只意味着文件 +存在；它还应确认新会话可以看到名为 `optskills` 的 Skill。 + +## 发出问题 + +安装后，新建对话并输入下面的问题： + +```text +使用 OptSkills 求解下面的指派问题。 + +需要把 5 台虚拟机分别分配给 5 台物理服务器。每台虚拟机必须分配到一台 +服务器，每台服务器也只能接收一台虚拟机。成本矩阵如下，行表示虚拟机， +列表示服务器： + +[[28, 15, 51, 19, 72], + [46, 44, 24, 14, 55], + [14, 18, 35, 61, 30], + [34, 41, 26, 50, 37], + [40, 53, 15, 62, 15]] + +请最小化总分配成本。报告所选 Skill、数学模型、求解器状态、分配结果、 +目标值和约束检查。若环境缺少求解器，先说明缺少什么，不要假装已经求解。 +``` + +这组数据来自 OptSkills 的公开记录 `AP_easy_1`。 + +## OptSkills 如何处理 + +Agent 首先轻量比较本包记录的上游 commit。版本相同时静默继续；检查失败或 +发现新版本时只给出一句提示，不会在当前任务中下载整套上游内容。 + +随后 Agent 读取 `skill_library/index.json`，根据“一对一分配、线性成本最小化、 +两组恰好一次约束”选择： + +```text +skill_id: assignment_problem_solver +path: skill_library/assignment_problem_solver.md +``` + +它只加载这张相关卡片，而不是把 103 张卡片全部读入上下文。 + +## 建立数学模型 + +令虚拟机集合和服务器集合均为 + +$$ +I=J=\{1,2,3,4,5\}. +$$ + +若虚拟机 $i$ 分配给服务器 $j$，令 $x_{ij}=1$；否则 $x_{ij}=0$。 +成本记为 $c_{ij}$。模型为 + +$$ +\min \sum_{i\in I}\sum_{j\in J}c_{ij}x_{ij}, +$$ + +满足 + +$$ +\sum_{j\in J}x_{ij}=1\qquad \forall i\in I, +$$ + +$$ +\sum_{i\in I}x_{ij}=1\qquad \forall j\in J, +$$ + +以及 + +$$ +x_{ij}\in\{0,1\}. +$$ + +第一组约束保证每台虚拟机恰好分配一次，第二组约束保证每台服务器恰好使用 +一次。 + +## 求解结果 + +在仓库验证使用的 OR-Tools CP-SAT 环境中，求解器返回 `OPTIMAL`。得到一组 +最优分配： + +| 虚拟机 | 服务器 | 成本 | +| --- | --- | ---: | +| 1 | 2 | 15 | +| 2 | 4 | 14 | +| 3 | 1 | 14 | +| 4 | 3 | 26 | +| 5 | 5 | 15 | + +总成本为 + +$$ +15+14+14+26+15=84. +$$ + +## 检查结果 + +Agent 不应只转述求解器的目标值，还应根据返回的分配重新检查： + +- 求解状态为 `OPTIMAL`； +- 五台虚拟机的分配次数均为 1； +- 五台服务器的使用次数均为 1； +- 重新计算的总成本为 84； +- 重新计算结果与求解器目标值一致。 + +只有完成这些检查后，才能报告该实例已经求解并通过约束检查。 + +## 环境没有求解器时 + +OptSkills 本身不捆绑 OR-Tools、Pyomo、HiGHS 或商业求解器。如果当前环境没有 +适合的求解器，Agent 仍可给出所选卡片、数学模型和求解代码，但应把“模型已建立” +与“求解器已执行”分开报告，并在安装新依赖前征求用户同意。 + +## 继续尝试其他问题 + +安装一次后，可以在新对话中直接输入： + +```text +使用 OptSkills 为一个带容量和单位运输成本的网络设计最小费用流模型，求解后 +检查每个节点的流量平衡和每条边的容量限制。 +``` + +```text +使用 OptSkills 为多工件、多机器的流水车间调度问题建立模型，最小化完工时间， +并检查工序顺序和机器不重叠约束。 +``` + +每次任务都应分别报告：选中的卡片、建立的模型、是否实际执行求解器、目标值 +检查、约束检查和仍未解决的问题。