@ohtaman/washi 0.4.0 → 0.6.0

package/README.zh-CN.md

@@ -2,9 +2,9 @@
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="./assets/washi-header-dark.png">
     <source media="(prefers-color-scheme: light)" srcset="./assets/washi-header-light.png">
-    <img alt="WaSHI - 面向 TypeScript 与 JavaScript 的数理优化代数建模器 (Modeler)" src="./assets/washi-header-light.png" width="420" />
+    <img alt="WaSHI - 适用于数理优化与约束编程的代数建模器 (TypeScript &amp; JavaScript)" src="./assets/washi-header-light.png" width="420" />
   </picture>
-  <p><strong>面向 TypeScript 与 JavaScript 的代数建模器</strong></p>
+  <p><strong>适用于数理优化与约束编程的代数建模器</strong></p>
   <p>
     <em>线性规划 (LP) • 混合整数规划 (MIP) • 凸二次规划 (QP) • SMT逻辑约束与冲突诊断</em>
   </p>
@@ -16,7 +16,7 @@
   <p>
     <a href="https://www.npmjs.com/package/@ohtaman/washi"><img src="https://img.shields.io/npm/v/@ohtaman/washi?color=crimson&label=npm" alt="npm version" /></a>
     <a href="https://github.com/ohtaman/washi/actions/workflows/distribution.yml"><img src="https://github.com/ohtaman/washi/actions/workflows/distribution.yml/badge.svg" alt="CI Status" /></a>
-    <a href="https://ohtaman.github.io/washi/"><img src="https://img.shields.io/badge/docs-online-blue" alt="docs" /></a>
+    <a href="https://ohtaman.github.io/washi/zh/"><img src="https://img.shields.io/badge/docs-online-blue" alt="docs" /></a>
     <a href="https://ohtaman.github.io/washi/demo/"><img src="https://img.shields.io/badge/demo-playground-brightgreen" alt="live demo" /></a>
     <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license" /></a>
   </p>
@@ -24,24 +24,24 @@
 
 ---
 
-**WaSHI** (WebAssembly-backed, Solver-independent, High-level modeling Interface) 是面向 TypeScript / JavaScript 的代数建模器，受到 Python **PuLP** 和 Julia **JuMP** 的启发。你可以在应用代码中定义变量、目标函数、算术约束和逻辑约束。WaSHI 负责构建模型、转换为求解器输入，并将结果映射回变量；优化与可满足性检查由 **HiGHS**、**Z3** 和 **GLPK** 完成。
+**WaSHI** (WebAssembly-backed, Solver-independent, High-level modeling Interface) 是面向 TypeScript / JavaScript 的数理优化与约束编程代数建模器，受到 Python **PuLP** 和 Julia **JuMP** 的启发。你可以在应用代码中定义变量、目标函数、算术约束和逻辑约束。WaSHI 负责构建模型、转换为求解器输入，并将结果映射回变量；优化与可满足性检查由 **HiGHS**、**Z3** 和 **GLPK** 完成。
 
 HiGHS 是默认求解器；Z3 和 GLPK 是可选插件。软件包提供 Node.js 和浏览器分发版本，并包含 WebAssembly 资源。部署要求请参阅[浏览器使用说明](#-浏览器与-web-worker-使用指南)。
 
-[试用浏览器演示](https://ohtaman.github.io/washi/demo/) · [示例源码与运行方法](https://github.com/ohtaman/washi/blob/main/examples/README.md) · [ESM / script / CodePen 示例](https://github.com/ohtaman/washi/blob/main/examples/distribution/README.md)
+[在线文档](https://ohtaman.github.io/washi/zh/) · [试用浏览器演示](https://ohtaman.github.io/washi/demo/) · [AI 编程助手快速参考](docs/zh/getting-started/ai-agents.md) · [Agent Skill (`SKILL.md`)](skills/washi/SKILL.md) · [示例源码与运行方法](https://github.com/ohtaman/washi/blob/main/examples/README.md) · [ESM / script / CodePen 示例](https://github.com/ohtaman/washi/blob/main/examples/distribution/README.md)
 
 ```ts
-import { Model, expr } from "@ohtaman/washi";
+import { Model, expr, maximize } from "@ohtaman/washi";
 
 const m = new Model("木工产品利润最大化");
 const x = m.integer("桌子", { lb: 0 });
 const y = m.integer("椅子", { lb: 0 });
 
-m.maximize(expr`30 * ${x} + 50 * ${y}`);
-m.constrain(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
-m.constrain(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
+m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
+m.constraint(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
 
-await m.optimize();
+await m.solve();
 console.log(`生产计划: x=${x.value}, y=${y.value} (最大利润: $${m.objectiveValue})`);
 ```
 
@@ -49,10 +49,11 @@ console.log(`生产计划: x=${x.value}, y=${y.value} (最大利润: $${m.object
 
 ## 🎯 WaSHI 提供的功能
 
-1. **代数模型构建**：使用领域变量构造函数（`m.binary`、`m.integer`、`m.continuous`）、标签模板字面量（`expr`）、向量聚合函数（`dot`、`sum`）以及首选的 `m.constrain()` 约束方法，精确且优雅地描述数学模型。
-2. **求解器适配器**：通过共同的建模 API 使用 HiGHS、Z3 或 GLPK，也可以[注册自己的适配器](https://github.com/ohtaman/washi/blob/main/docs/custom-solver-guide.md)。需要选择支持相应问题类型的求解器；不同求解器的能力并不相同。
-3. **本地执行与 WebAssembly 分发**：使用本地求解器适配器时，可在应用内求解，无需单独的 Python 服务或本地 C/C++ 编译。浏览器部署需要包含生成的 JS、Worker 和 WASM 资源。离线使用还需要这些资源可在本地访问或已缓存。Z3 有额外的浏览器隔离要求。
-4. **命名约束与 SMT 结果**：显式使用 Z3 检查可满足性，并通过 Unsat Core 调查冲突约束。返回的是一个冲突约束子集，不一定是最小子集。
+1. **代数模型构建**：使用领域变量构造函数（`m.binary`、`m.integer`、`m.continuous`）、标签模板字面量（`expr`）、向量聚合函数（`dot`、`sum`）以及一等约束（`m.constraint`）构建优化模型。由于 JavaScript 不支持运算符重载，`` expr`...` `` 采用类似参数化 SQL 模板的方式，在解析中缀数学运算符（`+`、`-`、`*`、`^2`、`<=`、`>=`、`==`）的同时，将 `${...}` 插值直接绑定为强类型的 `Var` 或表达式对象引用，从而保留静态类型检查、IDE 重命名支持以及多维索引访问（`${flow[i][j]}`）。
+2. **求解器适配器**：通过共同的建模 API 使用 HiGHS、Z3 或 GLPK，也可以[注册自己的适配器](https://github.com/ohtaman/washi/blob/main/docs/zh/solvers/custom-solver.md)。需要选择支持相应问题类型的求解器；不同求解器的能力并不相同。
+3. **本地执行与 WebAssembly 分发**：使用本地求解器适配器时，可在应用内直接求解，无需单独的 Python 服务或本地 C/C++ 编译——这消除了在快速开发和交付交互式工具时的后端基础设施瓶颈，也便于在客户端直接与浏览器内 LLM（如 WebGPU / WebLLM）协同工作。浏览器部署需要包含生成的 JS、Worker 和 WASM 资源。离线使用还需要这些资源可在本地访问或已缓存。Z3 有额外的浏览器隔离要求。
+4. **命名约束与冲突诊断**：通过可满足性检查（`m.check()`），可调查矛盾约束（`conflicts` / `unsatCore`）以排查不可行性原因：内置 HiGHS 分离出**弹性修复集合**（`conflicts`，恢复可行性所需松弛的约束集合），而 Z3 提取 **SMT 不可满足核心**（`unsatCore` / `conflicts`，相互矛盾的约束子集；不保证最小性）。
+5. **高级分解方法编排**：利用一等分解算法（`master.solveColumnGeneration`、`master.solveBenders`），突破单体 MIP 在特定结构（下料问题、车辆路径/VRP、旅行商/TSP、两阶段设施选址规划等）上的搜索树爆炸瓶颈。结合定价子问题（Pricing）与链接约束（`sub.link(...)`）的清晰回调编排，协同对偶定价、割平面生成与整数解复原。
 
 模型构建与转换由 WaSHI 负责。支持的问题类型、数值行为和求解时间取决于所选求解器、配置及具体问题。建模开销与求解器执行时间应分别测量；某个模型上的结果并不构成通用性能保证。
 
@@ -62,9 +63,9 @@ console.log(`生产计划: x=${x.value}, y=${y.value} (最大利润: $${m.object
 
 | 适配器 | 引擎许可证 | 支持的问题类型 | 引擎作用 | 集成方式 |
 | :--- | :--- | :--- | :--- | :--- |
-| **HiGHS** | **MIT** | **LP, MIP, 凸QP** | 数值优化 | 默认内置 |
-| **Z3** | **MIT** | **SMT, SAT, 逻辑, MIP** | 可满足性检查、Unsat Core、优化 | 可选插件 (`@ohtaman/washi/solvers/z3`) |
-| **GLPK** | **GPL-3.0** | **LP, MIP** | 线性与混合整数优化 | 可选插件 (`@ohtaman/washi/solvers/glpk`) |
+| **[HiGHS](https://github.com/ERGO-Code/HiGHS)** | **MIT** | **LP, MIP, 凸QP** | 数值优化 | 默认内置 |
+| **[Z3](https://github.com/Z3Prover/z3)** (via [`z3-solver`](https://www.npmjs.com/package/z3-solver)) | **MIT** | **SMT, SAT, 逻辑, MIP** | 可满足性检查、Unsat Core、优化 | 可选插件 (`@ohtaman/washi/solvers/z3`) |
+| **[GLPK](https://www.gnu.org/software/glpk/)** (via [`glpk.js`](https://www.npmjs.com/package/glpk.js)) | **GPL-3.0** | **LP, MIP** | 线性与混合整数优化 | 可选插件 (`@ohtaman/washi/solvers/glpk`) |
 | **Mock** | **MIT** | — | 为集成测试提供模拟响应 | 内置；不实际求解模型 |
 
 ---
@@ -92,61 +93,58 @@ npm install z3-solver    # 用于 SMT 与冲突诊断
 npm install glpk.js      # 用于 GLPK 求解器 (GPL-3.0)
 ```
 
+*(可选)* 面向 AI 编程助手（Claude Code、Antigravity、Cursor、Codex 等），可以通过 `skills` CLI 或随包附带的 [`skills/washi/SKILL.md`](skills/washi/SKILL.md) 引入建模与校验技能：
+
+```bash
+# 通过 skills CLI (skills.sh / vercel-labs/skills) 安装
+npx skills add ohtaman/washi
+
+# 或将随包附带的技能手动复制到项目中
+mkdir -p .agents/skills/washi
+cp node_modules/@ohtaman/washi/skills/washi/SKILL.md .agents/skills/washi/SKILL.md
+```
+
 ---
 
 ## 🚀 快速上手指南
 
-### 1. 混合整数线性规划 (MIP: 生产计划问题)
+### 1. 多维变量、条件指示约束 (`m.indicator`) 与解验证 (`m.validateSolution`)
 
-在有限资源约束下实现利润最大化：
+一行代码声明一维字典或二维变量矩阵，通过 `m.indicator()` 表达 Big-M 条件规则，结合 `onProgress` / `AbortSignal` 控制求解过程，并通过 `m.validateSolution()` 独立校验解的合法性：
 
 ```ts
 import { Model, expr } from "@ohtaman/washi";
 
-const m = new Model("FactoryPlanning");
-
-// 决策变量（非负整数）
-const chairs = m.integer("chairs", { lb: 0 });
-const tables = m.integer("tables", { lb: 0 });
-
-// 借助标签模板字面量自然表达目标函数与约束
-m.maximize(expr`30 * ${chairs} + 50 * ${tables}`);
-m.constrain(expr`${chairs} + 2 * ${tables} <= 40`, "wood_limit");
-m.constrain(expr`2 * ${chairs} + ${tables} <= 50`, "labor_limit");
-
-// 使用默认的 HiGHS WASM 引擎求解
-const status = await m.optimize();
-
-console.log(`求解状态: ${status}`); // "Optimal"
-console.log(`最大利润: $${m.objectiveValue}`); // 1100
-console.log(`生产量: 椅子=${chairs.value}, 桌子=${tables.value}`); // 椅子 20, 桌子 10
-```
-
-#### 🗂 多维变量网格
+const m = new Model("FacilityPlanning");
 
-一行代码声明变量字典或多维变量矩阵：
-
-```ts
-// 1D 字典形式的布尔变量
+// 1D 字典形式的二元变量
 const openCity = m.binary(["Tokyo", "Osaka", "Nagoya"]);
 
 // 2D 运输量矩阵: [工厂] x [门店]
-const flow = m.continuous(["F1", "F2"], ["StoreA", "StoreB"], { lb: 0 });
+const flow = m.continuous(["F1", "F2"], ["StoreA", "StoreB"], { lb: 0, ub: 1000 });
 
 // 2D 网格坐标 (例如 8x8 棋盘)
 const board = m.binary(8, 8, { prefix: "queen" });
-```
 
-#### 🔀 Big-M 条件指示约束 (`m.indicator`)
-
-轻松建模条件触发规则与固定成本启动，无需繁琐的手工 Big-M 代数推导：
-
-```ts
-// "若工厂关闭 (openCity['Tokyo'] == 0)，则产量 flow 必须为 0"
+// Big-M 条件约束: 若工厂关闭 (openCity['Tokyo'] == 0)，则 flow <= 0
+// (省略 M 时，WaSHI 会根据变量的有限上下界自动推导紧凑安全的 Big-M)
 m.indicator(openCity["Tokyo"], expr`${flow["F1"]["StoreA"]} <= 0`, {
   activeValue: 0,
-  M: 1000,
+  name: "tokyo_closed_no_flow",
 });
+
+// 支持实时进度回调 (onProgress) 与 AbortSignal 取消
+const controller = new AbortController();
+await m.solve({
+  signal: controller.signal,
+  onProgress: (ev) => {
+    // 实时指标: ev.elapsedTime, ev.objectiveValue, ev.objectiveBound, ev.mipGap
+  },
+});
+
+// 独立校验变量边界、整数性以及线性/逻辑约束
+const report = m.validateSolution();
+console.log("解验证通过？", report.valid);
 ```
 
 ---
@@ -156,7 +154,7 @@ m.indicator(openCity["Tokyo"], expr`${flow["F1"]["StoreA"]} <= 0`, {
 在满足预期收益与预算约束的前提下，基于协方差矩阵最小化投资组合风险：
 
 ```ts
-import { Model, QuadExpr, sum, dot, expr } from "@ohtaman/washi";
+import { Model, QuadExpr, sum, dot, minimize, expr } from "@ohtaman/washi";
 
 const m = new Model("MarkowitzPortfolio");
 const assets = ["Tech", "Bonds", "RealEstate"];
@@ -166,11 +164,11 @@ const returns = [0.14, 0.04, 0.08];
 const w = m.continuous(assets, { lb: 0, ub: 1 });
 
 // 1. 预算约束: 资金分配总额 100%
-m.constrain(expr`${sum(assets, (a) => w[a])} == 1.0`, "budget");
+m.constraint(expr`${sum(assets, (a) => w[a])} == 1.0`, "budget");
 
 // 2. 目标回报率: 组合最低回报率 >= 8.5%
 const retMap = Object.fromEntries(assets.map((a, i) => [a, returns[i]]));
-m.constrain(expr`${dot(retMap, w)} >= 0.085`, "min_return");
+m.constraint(expr`${dot(retMap, w)} >= 0.085`, "min_return");
 
 // 3. 资产协方差矩阵 (风险与相关性)
 const cov = [
@@ -186,9 +184,9 @@ for (let i = 0; i < assets.length; i++) {
     risk = risk.add(w[assets[i]].mul(w[assets[j]]).mul(cov[i][j]));
   }
 }
-m.minimize(risk);
+m.objective(minimize(risk));
 
-await m.optimize();
+await m.solve();
 console.log(`最小方差: ${m.objectiveValue?.toFixed(6)}`);
 assets.forEach((name) => {
   console.log(`  ${name}: ${((w[name].value || 0) * 100).toFixed(2)}%`);
@@ -214,13 +212,13 @@ const siren = m.bool("siren");
 const lux = m.integer("lux", { lb: 0 });
 
 // 规则定义
-m.constrain(lux.le(50).implies(isNight), "dark_implies_night");
-m.constrain(motion.and(isNight).and(alarm).implies(siren), "alarm_rule");
+m.constraint(lux.le(50).implies(isNight), "dark_implies_night");
+m.constraint(motion.and(isNight).and(alarm).implies(siren), "alarm_rule");
 
 // 传感器当前输入数据
-m.constrain(expr`${lux} <= 10`, "sensor_dark");
-m.constrain(motion, "sensor_motion");
-m.constrain(alarm, "alarm_on");
+m.constraint(expr`${lux} <= 10`, "sensor_dark");
+m.constraint(motion, "sensor_motion");
+m.constraint(alarm, "alarm_on");
 
 // 无目标函数直接判定可满足性 (SAT)
 const res = await m.check({ solver: "z3" });
@@ -231,40 +229,47 @@ console.log(`警报响起？ ${m.values.get("siren")}`); // true
 
 ---
 
-### 4. 约束冲突根因诊断 (`unsatCore`)
+### 4. 冲突诊断 (`conflicts` / `unsatCore`)
 
-当规则或约束之间存在矛盾时，Z3 能够提取引发冲突的**矛盾约束子集**（Unsat Core，不保证最小性；需使用 Z3）：
+当规则或约束之间存在矛盾时，可定位不可行根因以采取干预措施：
+- **内置 HiGHS 与 GLPK**：`await m.check()` 采用单次求解弹性松弛模型（$\min \sum s_i$），无需安装外部求解器即可定位 `res.conflicts`——即恢复可行性所需松弛的**修复集合**。
+- **Z3**：`await m.check({ solver: "z3" })` 提供精确的 SMT **不可满足核心（Unsat Core）** 提取（`res.unsatCore` 与 `res.conflicts`），返回相互矛盾的约束子集。
 
 ```ts
 import { Model, expr } from "@ohtaman/washi";
-import "@ohtaman/washi/solvers/z3";
 
-const m = new Model({ name: "ConflictDiagnosis", solver: "z3" });
+const m = new Model("ConflictDiagnosis");
 const engineers = m.integer("engineers", { lb: 0, ub: 20 });
 const budget = m.continuous("budget", { lb: 0, ub: 100000 });
 const rushDelivery = m.bool("rushDelivery");
 
 // 规则 1: 每位工程师成本 $8,000
-m.constrain(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
+m.constraint(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
 
 // 规则 2: 客户要求加急交付
-m.constrain(rushDelivery, "rush_required");
+m.constraint(rushDelivery, "rush_required");
 
 // 规则 3: 加急交付需至少配备 8 名工程师
-m.constrain(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
+m.constraint(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
 
 // 规则 4: 董事会严格预算上限 $50,000 (冲突点: 8人 * $8,000 = $64,000 > $50,000!)
-m.constrain(expr`${budget} <= 50000`, "strict_board_budget_cap");
+m.constraint(expr`${budget} <= 50000`, "strict_board_budget_cap");
 
 // 规则 5: 最低 1 名员工用工底线（无关规则）
-m.constrain(expr`${engineers} >= 1`, "minimum_one_employee");
+m.constraint(expr`${engineers} >= 1`, "minimum_one_employee");
 
-const res = await m.check({ solver: "z3" });
+// 1. 使用默认 HiGHS 进行弹性修复诊断
+const res = await m.check();
 
 console.log(`求解状态: ${res.status}`); // "Unsat"
-console.log("冲突约束子集:", res.unsatCore);
-// 输出: ["budget_limit", "rush_required", "rush_staffing_rule", "strict_board_budget_cap"]
-// 注：无关的 "minimum_one_employee" 被准确排除在外！
+console.log("修复约束集合（需松弛的约束）:", res.conflicts);
+// HiGHS 输出: ["rush_required"]
+// （松弛 rush_required 即可恢复可行性；无关的 minimum_one_employee 不受影响）
+
+// 2. 或使用 Z3 提取精确 SMT 不可满足核心（需导入 "@ohtaman/washi/solvers/z3"）
+// const z3Res = await m.check({ solver: "z3" });
+// console.log("相互矛盾核心:", z3Res.unsatCore);
+// Z3 输出: ["budget_limit", "rush_required", "rush_staffing_rule", "strict_board_budget_cap"]
 ```
 
 ---
@@ -274,18 +279,18 @@ console.log("冲突约束子集:", res.unsatCore);
 使用 GNU Linear Programming Kit (GLPK) 求解器插件：
 
 ```ts
-import { Model, expr } from "@ohtaman/washi";
+import { Model, expr, maximize } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/glpk";
 
 const m = new Model({ solver: "glpk" });
 const x = m.integer("x", { lb: 0 });
 const y = m.integer("y", { lb: 0 });
 
-m.maximize(expr`30 * ${x} + 50 * ${y}`);
-m.constrain(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
-m.constrain(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
+m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
+m.constraint(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
 
-const status = await m.optimize();
+const status = await m.solve();
 console.log(`求解状态: ${status}`); // "Optimal"
 console.log(`目标函数值: ${m.objectiveValue}`); // 1100
 ```
@@ -297,7 +302,7 @@ console.log(`目标函数值: ${m.objectiveValue}`); // 1100
 无需嵌套循环，一行代码完成一维和二维变量的线性组合：
 
 ```ts
-import { Model, dot } from "@ohtaman/washi";
+import { Model, dot, minimize } from "@ohtaman/washi";
 
 const m = new Model();
 const factories = ["Tokyo", "Osaka"];
@@ -311,8 +316,8 @@ const costs = {
 const ship = m.continuous(factories, stores);
 
 // 一行代码最小化总运输成本:
-m.minimize(dot(costs, ship));
-await m.optimize();
+m.objective(minimize(dot(costs, ship)));
+await m.solve();
 
 // 获取所有变量的最优取值结构
 const solution = m.getValues(ship);
@@ -362,23 +367,23 @@ await model.solve();
 </script>
 ```
 
-若通过 CDN 加载，可使用 `https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.1.2/dist/browser/washi.min.js`（请固定 `0.1.2` 及以上版本号）。ESM 使用同版本的 `dist/browser/washi.js`。选择 CDN URL 就是显式使用 CDN；本地部署不会自动改用外部 CDN。
+若通过 CDN 加载，可使用 `https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.min.js`（待包含相应 API 的版本发布后指定该版本号）。ESM 使用同版本的 `dist/browser/washi.js`。选择 CDN URL 就是显式使用 CDN；本地部署不会自动改用外部 CDN。
 
 ### 浏览器环境中的求解器插件（GLPK & Z3）
 
-浏览器发布包在 `dist/browser/solvers/` 下提供了开箱即用的独立求解器插件（通过 CDN 引入时适用于 `>= 0.2.0` 或 `@latest`）：
+浏览器发布包在 `dist/browser/solvers/` 下提供了开箱即用的独立求解器插件：
 - **GLPK**: `dist/browser/solvers/glpk.js` (ESM) 与 `dist/browser/solvers/glpk.min.js` (IIFE，挂载全局 `WashiGLPK`)
 - **Z3**: `dist/browser/solvers/z3.js` (ESM) 与 `dist/browser/solvers/z3.min.js` (IIFE，挂载全局 `WashiZ3`)，附带 `z3-built.js` 和 `z3-built.wasm`
 
 #### 浏览器 ESM 使用 GLPK
 ```html
 <script type="module">
-  import { Model } from "./washi/washi.js";
+  import { Model, maximize } from "./washi/washi.js";
   import "./washi/solvers/glpk.js";
 
   const model = new Model({ solver: "glpk" });
   const x = model.continuous("x", { lb: 0, ub: 10 });
-  model.maximize(x);
+  model.objective(maximize(x));
   await model.solve();
   console.log("GLPK 求解状态:", model.status);
 </script>
@@ -391,52 +396,34 @@ await model.solve();
 <script>
   const model = new Washi.Model({ solver: "glpk" });
   const x = model.continuous("x", { lb: 0, ub: 10 });
-  model.maximize(x);
+  model.objective(Washi.maximize(x));
   model.solve().then(status => console.log("GLPK 求解状态:", status));
 </script>
 ```
 
 > [!NOTE]
 > **浏览器环境中使用 Z3 的配置要求与跨源隔离**：
-> 由于 Z3 的 WebAssembly 引擎依托多线程 (`SharedArrayBuffer`)，现代浏览器强制要求 Cross-Origin Isolation。文档响应头必须包含：
-> ```http
-> Cross-Origin-Opener-Policy: same-origin
-> Cross-Origin-Embedder-Policy: require-corp
-> ```
-> 并且跨源资源必须包含 `Cross-Origin-Resource-Policy: cross-origin` 标头。
-> 
-> 无法自定义响应标头的常见静态托管（如标准 GitHub Pages 或 CodePen 等 iframe 预览环境）在缺少额外配置时无法直接满足条件。引入 `@ohtaman/washi` 核心库绝不会自动向用户项目中注入或注册 Service Worker。
-> 
-> 在 GitHub Pages 部署的 WaSHI 官方 Web Demo 中，通过在同源独立部署作用域严格限定为 `/washi/` 的 `coi-serviceworker.js`，在首次访问时安全自动重载一次以建立 `window.crossOriginIsolated === true` 环境。在不支持 Service Worker 或隔离失败的环境中，Z3 会清晰展示诊断原因并中止执行，防止无限重载或无响应挂起。
-
-完整独立的 ESM、Script 标签与 CodePen 示例请参阅 `examples/distribution/`。
-
-### 工厂内网、离线部署、Worker 与自定义 URL
-
-将应用构建产物或整个 `dist/browser` 目录部署到本地 HTTP / 内网服务器。所有资源可在本地访问时，即使浏览器缓存为空也不需要外部网络。仅保存 HTML 或第一个 JS 文件是不够的。不保证 `file://` 执行，也不自动提供 PWA 缓存。
+> 由于 Z3 的 WebAssembly 引擎依托多线程 (`SharedArrayBuffer`)，现代浏览器强制要求跨源隔离（`Cross-Origin-Opener-Policy: same-origin` 与 `Cross-Origin-Embedder-Policy: require-corp`）。关于静态托管（`coi-serviceworker.js`）、离线/内网部署、CSP（`worker-src blob:`）与自定义 WASM URL（`setHighsWasmUrl`）的完整说明，请参阅 [跨源隔离指南](docs/zh/getting-started/cross-origin.md) 与 [运行时环境配置](docs/zh/getting-started/runtimes.md)。
 
-ESM 根据模块 URL 解析资源；script 构建在加载时保存自身的 URL。CDN Worker 使用 Blob 模块启动，需要服务端的跨域资源许可及相应 CSP。CDN Worker 还需允许 `worker-src blob:`。不支持时可使用 `useWorker: false`。Worker 加载或消息处理失败会拒绝求解 Promise。
+完整独立的 ESM、Script 标签与 CodePen 示例请参阅 [`examples/distribution/`](examples/distribution/README.md)。
 
-自定义地址仍可通过 `setHighsWasmUrl(url)` 或 `options.wasmUrl` 指定。显式选择现有 HiGHS CDN：
-
-```typescript
-import { setHighsWasmUrl, OFFICIAL_HIGHS_CDN_WASM_URL } from "@ohtaman/washi";
-setHighsWasmUrl(OFFICIAL_HIGHS_CDN_WASM_URL);
-```
+---
 
-初始化失败会返回包含请求地址的错误，不会尝试其他主机。依赖旧的域名根目录 / CDN 自动回退的应用需部署生成资源或显式配置 URL。
+## 🛠️ 自定义求解器开发与架构扩展
 
-### 验证发布产物
+WaSHI 采用完全解耦的插件式求解器架构。你可以轻松编写并注册自定义求解器适配器（如云端 REST 求解服务、定制 WebAssembly 引擎或商业求解器）：
 
-`npm run test:distribution` 安装实际 npm tarball，在没有可选依赖时构建 Vite / webpack 应用，并通过 VM 执行生成的 JS 和真实 WASM。这不等同于浏览器 / CORS 验证。安装 `npx playwright install chromium` 后，运行 `RUN_DISTRIBUTION_BROWSER=1 npm run test:distribution` 以验证 Chromium。CI 使用该模式，验证跨域部署及外部网络请求阻断。
+- 完整开发指南、接口契约（`Solver`, `SolveModelData`, `CheckModelData`, `SolverResult`）与测试实践详见 [自定义求解器开发指南](docs/zh/solvers/custom-solver.md)。
 
 ---
 
-## 🛠️ 自定义求解器开发与架构扩展
+## 📚 文档指南
 
-WaSHI 采用完全解耦的插件式求解器架构。你可以轻松编写并注册自定义求解器适配器（如云端 REST 求解服务、定制 WebAssembly 引擎或商业求解器）：
+完整文档可在 **[ohtaman.github.io/washi/zh/](https://ohtaman.github.io/washi/zh/)** 及仓库的 [`docs/zh/`](docs/zh/)（[英文版 `docs/`](docs/)）中查阅：
 
-- 完整开发指南、接口契约（`Solver`, `LpModelData`, `SolverResult`）与测试实践详见 [Custom Solver Developer Guide](docs/custom-solver-guide.md)。
+- **快速上手**: [快速开始](docs/zh/getting-started/index.md) · [AI 编程助手快速参考](docs/zh/getting-started/ai-agents.md) · [运行时环境配置](docs/zh/getting-started/runtimes.md) · [跨源隔离指南 (Z3)](docs/zh/getting-started/cross-origin.md)
+- **建模指南**: [决策变量 (`Var`, `BoolVar`)](docs/zh/guide/variables.md) · [表达式与聚合 (`expr`, `sum`, `dot`)](docs/zh/guide/expressions.md) · [约束与逻辑条件 (`indicator`, SMT)](docs/zh/guide/constraints.md) · [目标函数与求解 (`solve`, `validateSolution`)](docs/zh/guide/objectives.md) · [可满足性与 Unsat Core (`check`)](docs/zh/guide/unsat-core.md) · [分解法 (`solveColumnGeneration`, `solveBenders`)](docs/zh/guide/decomposition.md)
+- **求解器**: [求解器概览](docs/zh/solvers/index.md) · [HiGHS](docs/zh/solvers/highs.md) · [Z3](docs/zh/solvers/z3.md) · [GLPK](docs/zh/solvers/glpk.md) · [自定义求解器](docs/zh/solvers/custom-solver.md)
 
 ---
 
@@ -446,11 +433,13 @@ WaSHI 采用完全解耦的插件式求解器架构。你可以轻松编写并
 
 | 类别 | 示例 | 展示内容 | 求解器 |
 | :--- | :--- | :--- | :--- |
-| **基础模型** | [生产计划](https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts) | 整数变量、利润目标与资源约束 (`expr`, `c`) | HiGHS |
+| **基础模型** | [生产计划](https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts) | 整数变量、利润目标与资源约束 (`expr`) | HiGHS |
 | **基础模型** | [运输与分配网络](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) | 二维矩阵变量 (`continuous(rows, cols)`) 与供需平衡 | HiGHS |
 | **基础模型** | [营养问题与灵敏度分析](https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts) | 影子价格 (`constr.dual`)、松弛量 (`constr.slack`) 与缩减成本 (`var.reducedCost`) | HiGHS |
 | **实战应用** | [员工排班与冲突诊断](https://github.com/ohtaman/washi/blob/main/examples/node/11-shift-scheduling.ts) | 周排班优化与周六休假冲突诊断 | HiGHS + Z3 |
 | **实战应用** | [购物车优惠券最优组合](https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts) | 满减门槛条件约束 (`indicator`)、互斥规则与凑单推荐 | HiGHS |
+| **大规模分解** | [车辆路径规划 (CVRP)](https://github.com/ohtaman/washi/blob/main/examples/node/13-vehicle-routing-column-generation.ts) | 列生成法 (Dantzig-Wolfe): 基于对偶影子价格动态定价可行配送路线 | HiGHS |
+| **大规模分解** | [旅行商问题 (TSP)](https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts) | Benders 分解 (DFJ 法): 通过可行性割平面延迟生成子回路消除约束 | HiGHS |
 | **实战应用** | [投资组合分配](https://github.com/ohtaman/washi/blob/main/examples/node/03-portfolio-qp.ts) | 凸二次目标函数 (`QuadExpr`) 与分配约束 | HiGHS |
 | **逻辑 / SMT** | [业务规则检查](https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts) | 算术与逻辑约束 (`bool`, `implies`) 的可满足性检查 | Z3 |
 | **逻辑 / SMT** | [冲突诊断](https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts) | 命名约束与 Unsat Core (`unsatCore`) | Z3 |
@@ -468,6 +457,8 @@ npx tsx examples/node/09-transportation-problem.ts
 npx tsx examples/node/10-diet-sensitivity.ts
 npx tsx examples/node/11-shift-scheduling.ts
 npx tsx examples/node/12-ecommerce-coupon-optimizer.ts
+npx tsx examples/node/13-vehicle-routing-column-generation.ts
+npx tsx examples/node/14-traveling-salesperson-benders.ts
 
 # 本地浏览器演示: http://localhost:5173/demo/
 npm run dev
@@ -477,7 +468,7 @@ npm run dev
 
 ---
 
-## 🧪 自动化测试
+## 🧪 自动化测试与可复现基准测试
 
 运行仓库的单元测试与集成测试，并构建分发版本：
 
@@ -489,11 +480,48 @@ npm test
 npm run build
 ```
 
+### 可选的可复现基准测试
+
+在不将耗时阈值混入正确性测试断言的前提下，对确定性的 `small-lp`（24 个变量、18 条约束）和 `scheduling-mip`（315 个变量、231 条约束，含重建模型的 `initialValue` 热启动）进行分阶段性能测量：
+
+```bash
+# 运行 Node.js 进程内 WASM 基准测试（HiGHS 与 GLPK，默认 5 次热重复）
+npm run bench
+
+# 自定义重复次数或输出 JSON
+node scripts/run-benchmarks.mjs --iterations=10 --json
+
+# 同时测量无头 Chromium Web Worker 执行（需要安装 Playwright Chromium）
+node scripts/run-benchmarks.mjs --browser
+```
+
+- **明确的测量边界**：将冷启动初始化（`coldRuntimeInitMs`、`coldFirstSolveMs`）与复用运行时的重复测量（`modelBuildMs`、`validationMs`、LP 字符串适配器的 `lpSerializationMs` 或结构化适配器的 `symbolMapMs`、基于 `MockSolver` 的 `resultMappingMs`、`adapterSolveMs` 以及 `endToEndSolveMs`）分开直接测量，不通过相减来臆造“原生求解器时间”。
+- **区分不同执行环境**：Node.js 进程内 WASM（`usesBrowserWorker: false`）与浏览器 Web Worker 执行（`usesBrowserWorker: true`，包含 Worker 生命周期与 `postMessage` 结构化克隆传输）作为不同执行环境分别报告，不可直接互换作基线。
+
+### HiGHS WebAssembly 重新构建与发布流程
+
+1. **更新 / 重新构建 HiGHS WebAssembly 资源（`highs.config.json`）**：
+   ```bash
+   # 从 ERGO-Code/HiGHS 编译 public/highs.wasm 与 runtime.js，并更新 highs.config.json 中的 SHA-256 哈希
+   npm run build:highs-wasm
+
+   # 合并到 main 后，将更新后的资源覆盖上传至对应的 highs-<version> GitHub Release 标签，
+   # 确保按需下载（scripts/ensure-highs-wasm.mjs）与 highs.config.json 的 SHA-256 校验一致：
+   gh release upload highs-v1.15.1 public/highs.wasm src/modeler/solvers/highs/runtime.js --clobber
+   ```
+   （也可在 GitHub Actions 中手动触发 `.github/workflows/build-wasm.yml` 并启用 `create_release: true`，随后下载工作流产物 `highs-wasm-assets`（含 `public/highs.wasm`、`src/modeler/solvers/highs/runtime.js` 与 `highs.config.json`）并提交至仓库，以确保仓库校验和与已发布的 Release 资产保持同步。）
+
+2. **发布 `@ohtaman/washi` 至 npm**：
+   - 合并至 `main` 会自动通过 `.github/workflows/deploy-demo.yml` 部署文档与在线演示到 GitHub Pages，但**不会**自动发布至 npm。
+   - 如需发布新版本至 npm，请先在 `main` 上更新 `package.json` 的 `"version"`，然后创建并发布 GitHub Release（例如 `gh release create v0.5.1 --generate-notes`）。发布 Release 会触发 `.github/workflows/publish-npm.yml`，在通过单元测试与 Playwright 分发验证后通过 OIDC Trusted Publishing 自动发布至 npm。
+
 ---
 
 ## 📄 许可证
 
 - **`@ohtaman/washi`**: [MIT 许可证](./LICENSE)
-- **HiGHS**（默认求解器）: MIT 许可证
-- **Z3**（可选插件）: MIT 许可证
-- **GLPK**（可选插件）: GPL-3.0 许可证
+- **HiGHS**（默认求解器，[ERGO-Code/HiGHS](https://github.com/ERGO-Code/HiGHS)）: MIT 许可证
+- **Z3**（可选插件，通过 [`z3-solver`](https://www.npmjs.com/package/z3-solver)）: MIT 许可证
+- **GLPK**（可选插件，通过 [`glpk.js`](https://www.npmjs.com/package/glpk.js)）: GPL-3.0 许可证
+
+有关内置及外部求解器的完整版权声明和许可信息，请参阅 [THIRD_PARTY_LICENSES.md](./THIRD_PARTY_LICENSES.md)。

package/THIRD_PARTY_LICENSES.md

@@ -9,15 +9,14 @@ Depending on the solver you choose at runtime, WaSHI interacts with the followin
 ## 1. HiGHS (Default Solver)
 
 - **Role**: Default Linear & Mixed-Integer Programming Engine (WebAssembly)
-- **Package**: [`highs`](https://www.npmjs.com/package/highs)
 - **License**: **MIT License**
-- **Upstream Repository**: [ERGO-Code/HiGHS](https://github.com/ERGO-Code/HiGHS) / [lovasoa/highs-js](https://github.com/lovasoa/highs-js)
+- **Upstream Repository**: [ERGO-Code/HiGHS](https://github.com/ERGO-Code/HiGHS)
+- **Compilation**: Directly compiled from official upstream source to WebAssembly via native C API (`highs_c_api.h`)
 
 ```text
 MIT License
 
-Copyright (c) 2023 highs-js
-Copyright (c) 2026 HiGHS
+Copyright (c) 2026 ERGO-Code / HiGHS developers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal