@ohtaman/washi 0.1.2 → 0.3.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 的数学规划与代数建模库" src="./assets/washi-header-light.png" width="420" />
+    <img alt="WaSHI - 面向 TypeScript 与 JavaScript 的数理优化代数建模器 (Modeler)" src="./assets/washi-header-light.png" width="420" />
   </picture>
-  <p><strong>面向 TypeScript 与 JavaScript 的直观数学规划与代数建模库</strong></p>
+  <p><strong>面向 TypeScript 与 JavaScript 的代数建模器</strong></p>
   <p>
     <em>线性规划 (LP) • 混合整数规划 (MIP) • 凸二次规划 (QP) • SMT逻辑约束与冲突诊断</em>
   </p>
@@ -14,56 +14,58 @@
     <a href="./README.zh-CN.md">简体中文</a>
   </p>
   <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/demo/"><img src="https://img.shields.io/badge/demo-playground-brightgreen" alt="live demo" /></a>
-    <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://bundlephobia.com/package/@ohtaman/washi"><img src="https://img.shields.io/badge/bundle%20size-7.2%20kB%20(gzip)-blue" alt="bundle size" /></a>
     <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license" /></a>
-    <img src="https://img.shields.io/badge/types-TypeScript-blue" alt="TypeScript types" />
-    <img src="https://img.shields.io/badge/tests-120%2B%20passing-brightgreen" alt="tests" />
   </p>
 </div>
 
 ---
 
-**WaSHI** 是一个高层代数建模库，将 Python **PuLP** 与 Julia **JuMP** 的优雅表现力引入现代 TypeScript / JavaScript 生态系统。你可以直接使用符合数学直觉的代数公式编写数学模型，并在 Node.js、现代浏览器、Bun、Deno 及 Next.js 中秒级求解——完全依托 WebAssembly 求解器（**HiGHS**、**Z3**、**GLPK**），无需任何本地 C++ 编译环境。
+**WaSHI** 是面向 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)
 
 ```ts
-import { Model, expr, c } from "@ohtaman/washi";
+import { Model, expr } from "@ohtaman/washi";
 
-const m = new Model({ sense: "Maximize" });
-const x = m.addVar({ type: "Integer", lb: 0 });
-const y = m.addVar({ type: "Integer", lb: 0 });
+const m = new Model("木工产品利润最大化");
+const x = m.integer("桌子", { lb: 0 });
+const y = m.integer("椅子", { lb: 0 });
 
 m.maximize(expr`30 * ${x} + 50 * ${y}`);
-m.addConstraint(c`${x} + 2 * ${y} <= 40`, "wood_limit");
-m.addConstraint(c`2 * ${x} + ${y} <= 50`, "labor_limit");
+m.constrain(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
+m.constrain(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
 
-await m.solve();
+await m.optimize();
 console.log(`生产计划: x=${x.value}, y=${y.value} (最大利润: $${m.objectiveValue})`);
 ```
 
 ---
 
-## 🎯 为什么选择 WaSHI？
+## 🎯 WaSHI 提供的功能
 
-1. 🌐 **100% 客户端运行与零服务器成本**：直接在用户的浏览器、边缘节点（Edge Worker）或 Electron 桌面端运行工业级优化。后端服务器运维成本为零，支持离线运行，且机密业务数据（如排班表、成本数据）永不离开客户端。
-2. 📦 **零依赖・单一包分发**：告别 Python 环境配置与繁重的跨平台 C/C++ 原生求解器编译绑定。只需 `npm install @ohtaman/washi`，包括 WebAssembly 求解器在内的所有组件即可开箱即用。
-3. ✍️ **极简现代代数建模 DX（兼容 PuLP / python-mip）**：无需编写晦涩低级的矩阵索引。使用直观的模板字面量（`c`${x} + 2 * ${y} <= 40``）或熟悉的 Python 风格抽象（`LpProblem`, `lpSum`），像在草稿纸上写公式一样自然。
-4. 🔄 **统一多求解器接口（HiGHS / Z3 / GLPK）**：模型代码一次编写，即可通过统一 API 自由切换：擅长工业级 MIP/QP 的 **HiGHS**、擅长逻辑求解与冲突分析的 **Z3**，以及经典学术求解器 **GLPK**。
-5. 🔍 **不可行模型（Infeasible）冲突根因诊断**：当业务规则出现矛盾导致无解时，可通过 Z3 引擎快速定位并提取冲突约束子集（Unsat Core）。
-6. ⚡ **WebAssembly 原生工业级大规模性能**：搭载 $O(N)$ 线性时间高速表达式构建器，仅需约 100ms 即可构建 20,000+ 变量的大规模 MIP，并在浏览器 WebAssembly 中由 HiGHS 在约 15 秒内高效求解。
+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 调查冲突约束。返回的是一个冲突约束子集，不一定是最小子集。
+
+模型构建与转换由 WaSHI 负责。支持的问题类型、数值行为和求解时间取决于所选求解器、配置及具体问题。建模开销与求解器执行时间应分别测量；某个模型上的结果并不构成通用性能保证。
 
 ---
 
-## ⚡ 求解器矩阵
+## ⚙️ 求解器适配器与支持范围
 
-| 求解器 | 核心许可证 | 支持的问题类型 | 最佳应用场景 | 在 WaSHI 中的提供方式 |
+| 适配器 | 引擎许可证 | 支持的问题类型 | 引擎作用 | 集成方式 |
 | :--- | :--- | :--- | :--- | :--- |
-| **HiGHS** | **MIT** | **LP, MIP, 凸QP** | 工业级生产排程、运筹规划、金融组合优化 | **内置默认**（零配置） |
-| **Z3** | **MIT** | **SMT, SAT, 命题逻辑, MIP** | 业务规则验证、约束冲突诊断 (`unsatCore`)、规则引擎 | 可选插件 (`@ohtaman/washi/solvers/z3`) |
-| **GLPK** | **GPL-3.0** | **LP, MIP** | 学术基准测试、存量 GLPK 模型迁移 | 可选插件 (`@ohtaman/washi/solvers/glpk`) |
-| **Mock** | **MIT** | *任意* | CI/CD 环境下无需加载 WASM 的极速单元测试 | 内置 |
+| **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`) |
+| **Mock** | **MIT** | — | 为集成测试提供模拟响应 | 内置；不实际求解模型 |
 
 ---
 
@@ -99,49 +101,49 @@ npm install glpk.js      # 用于 GLPK 求解器 (GPL-3.0)
 在有限资源约束下实现利润最大化：
 
 ```ts
-import { Model, c, expr } from "@ohtaman/washi";
+import { Model, expr } from "@ohtaman/washi";
 
-const m = new Model({ name: "FactoryPlanning", sense: "Maximize" });
+const m = new Model("FactoryPlanning");
 
 // 决策变量（非负整数）
-const chairs = m.addVar({ name: "chairs", type: "Integer", lb: 0 });
-const tables = m.addVar({ name: "tables", type: "Integer", lb: 0 });
+const chairs = m.integer("chairs", { lb: 0 });
+const tables = m.integer("tables", { lb: 0 });
 
 // 借助标签模板字面量自然表达目标函数与约束
 m.maximize(expr`30 * ${chairs} + 50 * ${tables}`);
-m.addConstraint(c`${chairs} + 2 * ${tables} <= 40`, "wood_limit");
-m.addConstraint(c`2 * ${chairs} + ${tables} <= 50`, "labor_limit");
+m.constrain(expr`${chairs} + 2 * ${tables} <= 40`, "wood_limit");
+m.constrain(expr`2 * ${chairs} + ${tables} <= 50`, "labor_limit");
 
 // 使用默认的 HiGHS WASM 引擎求解
-const status = await m.solve();
+const status = await m.optimize();
 
 console.log(`求解状态: ${status}`); // "Optimal"
 console.log(`最大利润: $${m.objectiveValue}`); // 1100
 console.log(`生产量: 椅子=${chairs.value}, 桌子=${tables.value}`); // 椅子 20, 桌子 10
 ```
 
-#### 🗂 多维变量网格 (`addVars`)
+#### 🗂 多维变量网格
 
-一行代码声明变量字典或多维变量矩阵（类似于 PuLP 的 `LpVariable.dicts`）：
+一行代码声明变量字典或多维变量矩阵：
 
 ```ts
 // 1D 字典形式的布尔变量
-const openCity = m.addVars(["Tokyo", "Osaka", "Nagoya"], { type: "Binary" });
+const openCity = m.binary(["Tokyo", "Osaka", "Nagoya"]);
 
 // 2D 运输量矩阵: [工厂] x [门店]
-const flow = m.addVars(["F1", "F2"], ["StoreA", "StoreB"], { lb: 0 });
+const flow = m.continuous(["F1", "F2"], ["StoreA", "StoreB"], { lb: 0 });
 
 // 2D 网格坐标 (例如 8x8 棋盘)
-const board = m.addVars(8, 8, { type: "Binary", prefix: "queen" });
+const board = m.binary(8, 8, { prefix: "queen" });
 ```
 
-#### 🔀 Big-M 指示约束 (`addIndicator`)
+#### 🔀 Big-M 条件指示约束 (`m.indicator`)
 
-直接表达条件激活与固定成本逻辑，无需手动进行繁琐的 Big-M 代数推导：
+轻松建模条件触发规则与固定成本启动，无需繁琐的手工 Big-M 代数推导：
 
 ```ts
 // "若工厂关闭 (openCity['Tokyo'] == 0)，则产量 flow 必须为 0"
-m.addIndicator(openCity["Tokyo"], flow["F1"]["StoreA"].le(0), {
+m.indicator(openCity["Tokyo"], expr`${flow["F1"]["StoreA"]} <= 0`, {
   activeValue: 0,
   M: 1000,
 });
@@ -154,20 +156,21 @@ m.addIndicator(openCity["Tokyo"], flow["F1"]["StoreA"].le(0), {
 在满足预期收益与预算约束的前提下，基于协方差矩阵最小化投资组合风险：
 
 ```ts
-import { Model, QuadExpr, sum } from "@ohtaman/washi";
+import { Model, QuadExpr, sum, dot, expr } from "@ohtaman/washi";
 
-const m = new Model({ name: "MarkowitzPortfolio", sense: "Minimize" });
+const m = new Model("MarkowitzPortfolio");
 const assets = ["Tech", "Bonds", "RealEstate"];
 const returns = [0.14, 0.04, 0.08];
 
 // 决策变量: 各资产投资权重 (0.0 ~ 1.0)
-const w = assets.map((a) => m.addVar({ name: `w_${a}`, lb: 0, ub: 1 }));
+const w = m.continuous(assets, { lb: 0, ub: 1 });
 
 // 1. 预算约束: 资金分配总额 100%
-m.addConstraint(sum(w).eq(1.0), "budget");
+m.constrain(expr`${sum(assets, (a) => w[a])} == 1.0`, "budget");
 
 // 2. 目标回报率: 组合最低回报率 >= 8.5%
-m.addConstraint(sum(w.map((v, i) => v.mul(returns[i]))).ge(0.085), "min_return");
+const retMap = Object.fromEntries(assets.map((a, i) => [a, returns[i]]));
+m.constrain(expr`${dot(retMap, w)} >= 0.085`, "min_return");
 
 // 3. 资产协方差矩阵 (风险与相关性)
 const cov = [
@@ -180,15 +183,15 @@ const cov = [
 let risk = new QuadExpr();
 for (let i = 0; i < assets.length; i++) {
   for (let j = 0; j < assets.length; j++) {
-    risk = risk.add(w[i].mul(w[j]).mul(cov[i][j]));
+    risk = risk.add(w[assets[i]].mul(w[assets[j]]).mul(cov[i][j]));
   }
 }
 m.minimize(risk);
 
-await m.solve();
+await m.optimize();
 console.log(`最小方差: ${m.objectiveValue?.toFixed(6)}`);
-assets.forEach((name, i) => {
-  console.log(`  ${name}: ${((w[i].value || 0) * 100).toFixed(2)}%`);
+assets.forEach((name) => {
+  console.log(`  ${name}: ${((w[name].value || 0) * 100).toFixed(2)}%`);
 });
 ```
 
@@ -199,7 +202,8 @@ assets.forEach((name, i) => {
 原生支持布尔命题变量（`BoolVar`）、逻辑连接词（`and`, `or`, `implies`, `not`, `xor`）与数值算术约束的混合表达：
 
 ```ts
-import { Model, not } from "@ohtaman/washi";
+import { Model, not, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
 
 const m = new Model({ name: "SmartSecurityRules" });
 
@@ -207,16 +211,16 @@ const isNight = m.addBoolVar("isNight");
 const motion = m.addBoolVar("motion");
 const alarm = m.addBoolVar("alarm");
 const siren = m.addBoolVar("siren");
-const lux = m.addVar({ name: "lux", type: "Integer", lb: 0 });
+const lux = m.integer("lux", { lb: 0 });
 
 // 规则定义
-m.addConstraint(lux.le(50).implies(isNight), "dark_implies_night");
-m.addConstraint(motion.and(isNight).and(alarm).implies(siren), "alarm_rule");
+m.constrain(lux.le(50).implies(isNight), "dark_implies_night");
+m.constrain(motion.and(isNight).and(alarm).implies(siren), "alarm_rule");
 
 // 传感器当前输入数据
-m.addConstraint(lux.le(10), "sensor_dark");
-m.addConstraint(motion, "sensor_motion");
-m.addConstraint(alarm, "alarm_on");
+m.constrain(expr`${lux} <= 10`, "sensor_dark");
+m.constrain(motion, "sensor_motion");
+m.constrain(alarm, "alarm_on");
 
 // 无目标函数直接判定可满足性 (SAT)
 const res = await m.check({ solver: "z3" });
@@ -232,28 +236,28 @@ console.log(`警报响起？ ${m.values.get("siren")}`); // true
 当规则或约束之间存在矛盾时，Z3 能够提取引发冲突的**矛盾约束子集**（Unsat Core，不保证最小性；需使用 Z3）：
 
 ```ts
-import { Model } from "@ohtaman/washi";
+import { Model, expr } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/z3";
 
 const m = new Model({ name: "ConflictDiagnosis", solver: "z3" });
-const engineers = m.addVar({ name: "engineers", type: "Integer", lb: 0, ub: 20 });
-const budget = m.addVar({ name: "budget", type: "Continuous", lb: 0, ub: 100000 });
+const engineers = m.integer("engineers", { lb: 0, ub: 20 });
+const budget = m.continuous("budget", { lb: 0, ub: 100000 });
 const rushDelivery = m.addBoolVar("rushDelivery");
 
 // 规则 1: 每位工程师成本 $8,000
-m.addConstraint(engineers.mul(8000).le(budget), "budget_limit");
+m.constrain(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
 
 // 规则 2: 客户要求加急交付
-m.addConstraint(rushDelivery, "rush_required");
+m.constrain(rushDelivery, "rush_required");
 
 // 规则 3: 加急交付需至少配备 8 名工程师
-m.addConstraint(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
+m.constrain(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
 
 // 规则 4: 董事会严格预算上限 $50,000 (冲突点: 8人 * $8,000 = $64,000 > $50,000!)
-m.addConstraint(budget.le(50000), "strict_board_budget_cap");
+m.constrain(expr`${budget} <= 50000`, "strict_board_budget_cap");
 
 // 规则 5: 最低 1 名员工用工底线（无关规则）
-m.addConstraint(engineers.ge(1), "minimum_one_employee");
+m.constrain(expr`${engineers} >= 1`, "minimum_one_employee");
 
 const res = await m.check({ solver: "z3" });
 
@@ -265,35 +269,54 @@ console.log("冲突约束子集:", res.unsatCore);
 
 ---
 
-### 5. Python PuLP 兼容层
+### 5. 使用 GLPK 求解器 (GPL-3.0)
+
+使用 GNU Linear Programming Kit (GLPK) 求解器插件：
+
+```ts
+import { Model, expr } 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");
+
+const status = await m.optimize();
+console.log(`求解状态: ${status}`); // "Optimal"
+console.log(`目标函数值: ${m.objectiveValue}`); // 1100
+```
+
+---
+
+### 6. 向量运算与高效点积 (`dot`)
 
-若你已有 Python PuLP 代码资产，可零摩擦迁移：
+无需嵌套循环，一行代码完成一维和二维变量的线性组合：
 
 ```ts
-import {
-  LpProblem,
-  LpVariable,
-  LpMaximize,
-  LpInteger,
-  HiGHS,
-  value,
-} from "@ohtaman/washi";
-
-const prob = new LpProblem("PuLPDemo", LpMaximize);
-
-const x = new LpVariable("x", 0, undefined, LpInteger);
-const y = new LpVariable("y", 0, undefined, LpInteger);
-
-// 等同于 PuLP 中的 += 语法
-prob.add(x.mul(30).add(y.mul(50)));
-prob.add(x.add(y.mul(2)).le(40));
-prob.add(x.mul(2).add(y).le(50));
-
-await prob.solve(new HiGHS());
-
-console.log(`状态: ${prob.status}`);
-console.log(`目标函数值: ${value(prob.objective)}`);
-console.log(`x = ${value(x)}, y = ${value(y)}`);
+import { Model, dot } from "@ohtaman/washi";
+
+const m = new Model();
+const factories = ["Tokyo", "Osaka"];
+const stores = ["StoreA", "StoreB"];
+
+const costs = {
+  Tokyo: { StoreA: 4, StoreB: 7 },
+  Osaka: { StoreA: 8, StoreB: 3 },
+};
+
+const ship = m.continuous(factories, stores);
+
+// 一行代码最小化总运输成本:
+m.minimize(dot(costs, ship));
+await m.optimize();
+
+// 获取所有变量的最优取值结构
+const solution = m.getValues(ship);
+console.log(solution);
 ```
 
 ---
@@ -341,7 +364,52 @@ await model.solve();
 
 若通过 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。
 
-浏览器构建包含 HiGHS 引擎，不包含可选的 GLPK / Z3 引擎。其他引擎集成请使用 npm 包及可选依赖。完整示例位于 `examples/distribution/`。
+### 浏览器环境中的求解器插件（GLPK & Z3）
+
+浏览器发布包在 `dist/browser/solvers/` 下提供了开箱即用的独立求解器插件（通过 CDN 引入时适用于 `>= 0.2.0` 或 `@latest`）：
+- **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 "./washi/solvers/glpk.js";
+
+  const model = new Model({ solver: "glpk" });
+  const x = model.addVar({ lb: 0, ub: 10 });
+  model.maximize(x);
+  await model.solve();
+  console.log("GLPK 求解状态:", model.status);
+</script>
+```
+
+#### 原生脚本标签使用 GLPK
+```html
+<script src="./washi/washi.min.js"></script>
+<script src="./washi/solvers/glpk.min.js"></script>
+<script>
+  const model = new Washi.Model({ solver: "glpk" });
+  const x = model.addVar({ lb: 0, ub: 10 });
+  model.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
 
@@ -364,32 +432,54 @@ setHighsWasmUrl(OFFICIAL_HIGHS_CDN_WASM_URL);
 
 ---
 
-## 💻 本地脚本与交互式 Web 演示
+## 🛠️ 自定义求解器开发与架构扩展
 
-在 `examples/node/` 中提供了即开即用的独立脚本：
+WaSHI 采用完全解耦的插件式求解器架构。你可以轻松编写并注册自定义求解器适配器（如云端 REST 求解服务、定制 WebAssembly 引擎或商业求解器）：
 
-```bash
-npx tsx examples/node/01-production-planning.ts
-npx tsx examples/node/02-knapsack-problem.ts
-npx tsx examples/node/03-portfolio-qp.ts
-npx tsx examples/node/04-smt-security-rules.ts
-npx tsx examples/node/05-unsat-core-diagnosis.ts
-npx tsx examples/node/06-pulp-compatibility.ts
-```
+- 完整开发指南、接口契约（`Solver`, `LpModelData`, `SolverResult`）与测试实践详见 [Custom Solver Developer Guide](docs/custom-solver-guide.md)。
+
+---
+
+## 💻 示例与浏览器演示
 
-启动浏览器端交互式可视化演示 (`examples/web-demo`)：
+[示例目录](https://github.com/ohtaman/washi/blob/main/examples/README.md)与[在线案例与 API 索引](https://ohtaman.github.io/washi/zh/examples/)按问题类别和 WaSHI API 功能汇总了源码链接及本地运行方法。
+
+| 类别 | 示例 | 展示内容 | 求解器 |
+| :--- | :--- | :--- | :--- |
+| **基础模型** | [生产计划](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/09-transportation-problem.ts) | 二维矩阵变量 (`addVars(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) | 满减门槛条件约束 (`addIndicator`)、互斥规则与凑单推荐 | 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) | 算术与逻辑约束 (`addBoolVar`, `implies`) 的可满足性检查 | Z3 |
+| **逻辑 / SMT** | [冲突诊断](https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts) | 命名约束与 Unsat Core (`unsatCore`) | Z3 |
+
+在[在线浏览器演示](https://ohtaman.github.io/washi/demo/)中可以编辑并运行模型。浏览器 ESM、script 标签和 CodePen 的用法请参阅[分发示例](https://github.com/ohtaman/washi/blob/main/examples/distribution/README.md)。Z3 需要跨源隔离；具体要求见上方浏览器说明。
+
+本地运行前，请克隆仓库并安装开发依赖：
 
 ```bash
+git clone https://github.com/ohtaman/washi.git
+cd washi
+npm ci
+npx tsx examples/node/01-production-planning.ts
+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
+
+# 本地浏览器演示: http://localhost:5173/demo/
 npm run dev
-# 文档主页: http://localhost:5173/
-# 交互式 Demo: http://localhost:5173/demo/
 ```
 
+示例导入仓库的 `src/` 模块。使用已发布软件包的应用应改为导入 `@ohtaman/washi` 及所需的求解器插件。
+
 ---
 
 ## 🧪 自动化测试
 
-项目全面贯彻测试驱动开发 (TDD)，涵盖 120+ 单元测试、集成测试与大规模基准测试：
+运行仓库的单元测试与集成测试，并构建分发版本：
 
 ```bash
 # 运行全部单元与集成测试

package/dist/browser/highs-worker.js

@@ -1,5 +1,5 @@
-import { c as e } from "./highs-loader-T47YOyos.js";
-//#region src/highs-worker.ts
+import { c as e } from "./loader-CVt4CloI.js";
+//#region src/modeler/solvers/highs/worker.ts
 self.onmessage = async (t) => {
 	let { type: n, id: r, lpString: i, options: a } = t.data;
 	if (n === "SOLVE") try {

package/dist/browser/{highs-loader-T47YOyos.js → loader-CVt4CloI.js}

@@ -8,7 +8,7 @@ function n() {
 	return t("highs.wasm");
 }
 //#endregion
-//#region src/highs-loader.ts
+//#region src/modeler/solvers/highs/loader.ts
 var r = "https://cdn.jsdelivr.net/npm/highs@1.15.3/build/highs.wasm", i = null, a = null, o = null;
 function s(e) {
 	o = e, i = null, a = null;
@@ -38,7 +38,7 @@ async function f(e = {}) {
 	if (i && a === n) return i;
 	a = n;
 	let r = (async () => {
-		let e = (await import("./highs-browser-runtime-D13gHOT5.js")).default;
+		let e = (await import("./browser-runtime-D13gHOT5.js")).default;
 		return await e({ locateFile: (e) => e.endsWith(".wasm") ? t : e });
 	})().catch((e) => {
 		i === r && (i = null, a = null);