# TolForge

**Repository Path**: jyxdyk/tol-forge

## Basic Information

- **Project Name**: TolForge
- **Description**: TolForge 是基于 open supOS 的开源公差工程与装配良率优化平台。它用 UNS 建模打通 MQTT→平台落库→尺寸链分析全链路，支持真实平台取数与快照回放。核心是在功能良率约束下用 SLSQP 优化公差分配与成本，并严格分离设计意图与制造现实：制造 μ/σ 只来自实测，优化图纸公差不会改善工厂波动，数据来源在界面逐项标注、可追溯。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

<img src="docs/screenshots/banner.png" alt="TolForge" width="620">

**面向 open supOS 的制造数据驱动公差工程与装配良率优化平台**

从平台取回真实测量，在功能良率约束下反解各零件公差怎么分配最省成本，<br>
并把 <strong>设计意图</strong> 与 <strong>制造现实</strong> 严格分开。

<sub>MIT License　·　Python 3.12 / NumPy / SciPy　·　183 项测试通过　·　Ollama AI 旁路建议　·　本机企业库　·　open supOS CE V1.5.0.0-M</sub>

</div>

---

## 它解决什么问题

工厂知道「零件测出来是多少」（制造现实），图纸知道「尺寸允许是多少」（设计意图），
但很少有系统能把两者**分开存储、合并计算**，并回答一个具体问题：

> **这个公差该收紧还是该放宽，才能既满足装配良率、又不为不必要的精度多付成本？**

TolForge 就是这个 Decision Engine。它把 open supOS 当作制造数据底座，
自己只做决策：取数、建模、算能力、算良率、反解公差、给成本结论。

---

## 架构

<img src="docs/screenshots/architecture.png" alt="TolForge 架构" width="100%">

测量值经 **MQTT → open supOS UNS 类型化节点 → TimescaleDB 落库**，
再由 `SuposDataSource` 通过平台 OpenAPI 读回，进入 TolForge 的分析管线：

```
MeasurementBatch(source_type=SUPOS)
  → ManufacturingSnapshot（不可变 + 指纹 + 原子发布）
  → Process Capability（μ / σ / Cp / Cpk）
  → Assembly Analysis（Worst Case / RSS / 解析良率 / Monte Carlo + Wilson 区间）
  → Tolerance Optimization（SLSQP + 相对成本模型）
  → App Shell（只渲染后端结果，不重算任何数值）
```

**平台适配是隔离的**：TolForge 保留自身 Canonical Model（`tolforge.measurements/1`），
不改成 open supOS 专属 schema，通过 Adapter 隔离，平台的 UNS 结构变化不会穿透到数学内核。

旁路能力（不改权威数值）：

```
AI 建议（本机 Ollama / qwen3）→ 一键采纳写入工作区公差 → 历史留痕
  ↘ 落库桌面 TolForge企业库\enterprise.db（与 open supOS 平台表隔离）
```

权威工程数值仍由 SciPy / 统计推断产出；LLM 只做顾问建议，不生成权威公差。

---

## 界面

<table>
<tr>
<td width="50%"><img src="docs/screenshots/app-overview.png" alt="总览"><br>
<b>Overview</b> — 今日 LIVE：<code>READY · OPEN SUPOS · SUPOS/CONNECTED</code>；装配 μ/σ、良率与图纸最坏情况；右侧 <b>快照收据</b>记录
Data source / Source ID / Measurement window / Snapshot ID / Batch ID / Algorithm</td>
<td width="50%"><img src="docs/screenshots/app-tolerance-engineering.png" alt="公差工程"><br>
<b>Tolerance Engineering</b> — 尺寸链、Monte Carlo 分布与
<b>敏感度分析</b>（按方差贡献排序，回答「钱该花在哪个尺寸」）</td>
</tr>
<tr>
<td><img src="docs/screenshots/app-uns-explorer.png" alt="UNS Explorer"><br>
<b>UNS Explorer</b> — Factory / Line / Product / Assembly / Dimension
逐级建模，每个尺寸节点带 canonical path、LSL/USL 与尺寸链系数</td>
<td><img src="docs/screenshots/app-freecad.png" alt="FreeCAD"><br>
<b>FreeCAD</b> — 读取标注尺寸链、原生网格预览、公差属性回写；
网页只解析 XML，<b>不执行文档内嵌的 Python 对象</b></td>
</tr>
<tr>
<td><img src="docs/screenshots/app-model-validation.png" alt="模型与验证"><br>
<b>Model & Validation</b> — 把假设与边界写进产品页面：
<code>σ = t/k</code> 中 k 是显式假设，Cp/Cpk 不宣称过程稳定</td>
<td><img src="docs/screenshots/repo-overview.png" alt="仓库"><br>
<b>开源仓库</b> — 提交历史覆盖需求基线、领域模型、平台适配、容器化打包与治理文档</td>
</tr>
</table>

更多分辨率见 `docs/screenshots/`。

---

## 三种数据来源，互不冒充

界面上的来源标注是**从快照的 `source_type` 派生**的，不是写死的 ——
演示数据不可能被冒充成平台数据。

| 模式 | 界面标注 | 数据来源 | 需要平台 |
|---|---|---|---|
| 实机 | `OPEN SUPOS UNS` / `CONNECTED` | 平台 UNS 历史值实时读取 | 是 |
| 快照重放 | `OPEN SUPOS UNS (SNAPSHOT)` / `EXPORT` | 之前从平台导出的测量快照 | 否 |
| 内置仿真 | `DEMO SOURCE` / `LOCAL` | 仓库内置的可复现合成剖面 | 否 |

**实机模式在平台不可达时明确报错并拒绝退回合成数据**，而不是悄悄换成仿真值。

---

## 示例：A-102 电驱单元轴向尺寸链

| 尺寸 | 名义值 | 公差 | 系数 | LSL / USL |
|---|---|---|---|---|
| Housing Depth | 100.0 | ±0.04 | +1 | 99.96 / 100.04 |
| Shaft Length | 70.0 | ±0.03 | −1 | 69.97 / 70.03 |
| Bearing Width | 15.0 | ±0.02 | −1 | 14.98 / 15.02 |
| Spacer Thickness | 10.0 | ±0.025 | −1 | 9.975 / 10.025 |
| Cover Step | 4.25 | ±0.03 | −1 | 4.22 / 4.28 |

封闭环 `0.75 mm`，功能要求 `[0.5, 1.0] mm`，目标良率 `99.7%`。

**核心不变量**（实测，三场景对照）：

| 场景 | 装配 σ (mm) | 图纸 Worst Case (mm) | 图纸 RSS 半宽 (mm) |
|---|---|---|---|
| NORMAL | 0.013645 | **0.605 – 0.895** | **0.066521** |
| MEAN_SHIFT | 0.013868 | **0.605 – 0.895** | **0.066521** |
| HIGH_VARIATION | 0.023564 | **0.605 – 0.895** | **0.066521** |

制造现实的波动**不会反向污染设计意图** —— 这是整个项目的设计原则。

---

## 启动

需要 Python 3.12+。在项目目录执行：

```powershell
python -m pip install -r requirements.txt
```

然后按模式选择入口（均打开 http://127.0.0.1:8765 ；端口占用时加 `--port`）：

| 入口 | 用途 | 说明 |
|---|---|---|
| `start-live.cmd` / `start_live.py`（桌面 **`TolForge正式版`**） | **正式版 LIVE**（非 Demo） | 强制 `TOLFORGE_DATA_SOURCE=supos`，平台不可达时**拒绝降级**到合成数据 |
| `start-live-with-seed.cmd` | Docker / 冷平台刚起 | LIVE + 种子探测，便于首启 |
| `start-demo.cmd` / `start.cmd` | 本地演示 | 可用内置仿真；界面标注 `DEMO SOURCE / LOCAL` |
| `python server.py` | 前台调试 | 关闭终端即停服 |

正式版冷启动今日量级：首启 warm ≈20.6 s，热机 ≈2.7 s（以本机实测为准）。服务只监听本机；
启动错误日志在 `logs/server.log`。

### AI 旁路（可选）

本机安装 [Ollama](https://ollama.com/) 并拉取模型后即可用：

```powershell
ollama pull qwen3:latest
# 服务启动后：公差优化页 →「AI 建议」→ 采纳 → 历史角标「已采纳」
```

建议与采纳记录写入桌面 `TolForge企业库\enterprise.db`（默认路径），**不改写** open
supOS 平台表。无 Ollama 时 SciPy 优化与平台链路仍可独立使用。

### 接入真实 open supOS 平台

平台模式通过环境变量或 `supos.config.json` 配置，**凭据不写入仓库**：

```powershell
$env:TOLFORGE_DATA_SOURCE     = "supos"          # 实机；platform_export 为快照重放
$env:TOLFORGE_SUPOS_URL       = "http://<平台地址>:8088"
$env:TOLFORGE_SUPOS_API_KEY   = "<平台 API key>"
$env:TOLFORGE_SUPOS_MQTT_HOST = "<平台地址>"
# 推荐直接用 start-live.cmd，避免漏设 DATA_SOURCE
```

WSL 部署时 `ENTRANCE_DOMAIN` 请使用 WSL 地址（如 `172.31.x.x`）而不是回环地址，
平台的 nginx 对 Host 有白名单。UNS 读写契约的实测记录见
[`docs/open-supos-uns-contract.md`](docs/open-supos-uns-contract.md)。

> **已知上游问题**：open supOS CE `V1.5.0.0-M` 存在两处缺陷会影响数据通路 ——
> 入口 nginx 的 `proxy_pass` 路径截断，以及后端冷启动时历史子系统初始化失败且不重试。
> 复现步骤与修复已在
> [`docs/open-supos-openapi-datapath-issue.md`](docs/open-supos-openapi-datapath-issue.md)。

---

## 三分钟演示

1. 打开内置的 A-102 总成，间隙名义值为 0.75 mm，要求 0.5–1.0 mm，目标良率 99.7%。
2. 顶部切换场景 `NORMAL → MEAN_SHIFT → HIGH_VARIATION`：每次都重新采样并重算。
   装配 σ 从约 0.0136 变到约 0.0236，**而图纸最坏情况三个场景完全一致**。
3. 在 **Tolerance Engineering** 看敏感度分析：壳体内腔 36.2%、轴肩长度 20.3%、
   端盖台阶 20.3%、垫片 14.1%、轴承 9.0% —— 这决定了钱该花在哪个尺寸。
4. 锁定某个尺寸，点击「优化公差分配」；查看优化前后的成本、理论良率及独立仿真的置信下限。
5. （可选）点「AI 建议」→ 采纳：历史列表角标变为「已采纳」，记录落入桌面企业库。
6. 导出项目 JSON 保存设计，导出计算报告保存建议与验证结果。
7. 在「制造检测数据」导入 CSV（列名为各尺寸 ID，单位 mm）。仓库包含明确标记为合成数据的
   `examples/synthetic-measurements.csv`。

当前页面不会自动保存。刷新会重新加载内置示例；请用导出项目保存自己的工作。

---

## 数学模型

封闭环 `Y = Σ cᵢ Xᵢ`。设计模式中 `Xᵢ ~ N(nominalᵢ + offsetᵢ, (tᵢ/kᵢ)²)`，各尺寸独立，分布未截断。
`t` 为图纸对称公差半宽；`k = t/σ` 是**用户可编辑的工艺假设**，而非图纸公差的必然含义。

- 最坏情况：`Σ cᵢ nominalᵢ ± Σ |cᵢ|tᵢ`，条件为各零件均在图纸限值内。
- RSS 公差半宽：`sqrt(Σ(cᵢtᵢ)²)`。只有各 k 相同才等于该 k 倍装配标准差。
- 解析良率：封闭环正态分布落入功能区间的概率。
- Monte Carlo：每个尺寸独立抽样，支持 1,000–1,000,000 个样本，种子可通过项目 JSON 设置。
- 验证：双侧 95% Wilson 区间；置信下限不低于目标才显示「置信下限达标」。该区间仅针对抽样误差，
  不包含模型或制造过程估计误差。

连续成本模型：`base_cost + precision_cost * (reference / tolerance) ** exponent`，单位为示例人民币/套。
该模型**无实际报价标定**，也不含报废、筛选和装配成本。默认参数及节省比例仅用于说明方法。

优化先计算允许的最大方差，再以 SLSQP 最小化成本；加工上下限、锁定维度作为约束。
目标预留 `min(0.0005, (1-target)/4)` 的绝对概率余量；这不是固定制造裕量，也不是成功保证。
优化结果用不同种子独立仿真。较小样本数或极高目标仍可能导致置信下限未达标。
无可行解、均值超出区间、求解失败时明确报错。连续结果映射到实际加工档位后需重新验证。

实测模式由每列样本均值和无偏样本标准差拟合正态分布。<strong>更改公差不改变已估计的制造波动，
因而禁止在该模式优化公差。</strong> CSV 至少 10 行，最多 100,000 行；不静默跳过缺失或无效值。
各列视为独立装配的零件样本，不保留行间配对关系。
<strong>Cp/Cpk 使用总体样本标准差作探索性估计，未经稳定性、正态性或组内变差验证，
不应当作过程能力认证。</strong>

---

## FreeCAD 数据闭环

「FreeCAD 装配」工作区支持读取采用 TolForge v1 标注契约的原生 `.FCStd` 文件、预览
FreeCAD 导出的实体网格、优化公差并导出回写包。随附 `examples/A102.FCStd` 和完成真实
回写的 `examples/A102-optimized.FCStd`；两份文件均由 FreeCAD 1.1.3 创建/保存，包含五个
有效实体和原生参数表达式。

快速体验：<strong>FreeCAD 装配 → 加载 CAD 示例 → 前往尺寸链分析 → 优化 → 应用 →
FreeCAD 装配 → 导出公差回写包</strong>。用 FreeCAD 打开原文件，运行 `cad/TolForge.FCMacro`
应用方案并另存。完整操作与契约说明见 [CAD_GUIDE.md](CAD_GUIDE.md)。

网页解析 FCStd 中的 XML 属性与已缓存网格，**不加载或执行文档中的 Python 对象**；
读文件不需要安装 FreeCAD。生成实体、参数重算和回写使用真实 FreeCAD。

---

## 数据交换

项目 JSON 的结构参见 `examples/assembly.json`；界面可添加或删除尺寸（1–12 个）。
`POST /api/analyze` 和 `POST /api/optimize` 接受项目 JSON。
`POST /api/measurements` 接受 `{ "project": <项目>, "csv": "CSV文本" }`。
所有数值均需有限；接口对尺寸范围、良率、样本量和请求大小做校验。

---

## 部署为 open supOS 应用

```powershell
docker build -t tolforge/app:0.3.0 .
docker save tolforge/app:0.3.0 -o dist/images/tolforge_app_0.3.0.tar
python tools/build_supos_app_package.py --image tar --image-dir dist/images
python tools/validate_app_package.py dist/TolForge-0.3.0-supos-app.zip   # PASS
```

在平台「应用管理 → 上传应用」选择生成的 ZIP。打包契约与校验规则见
[`playbooks/open-supos-app-package.md`](playbooks/open-supos-app-package.md)。

---

## 验证

```powershell
$env:PYTHONPATH="tests;."
python -m unittest discover -s tests -t tests          # 183 tests
node tests/test_app_state.cjs http://127.0.0.1:8765     # 前端真实 HTTP 契约
node tests/test_shell.cjs     http://127.0.0.1:8765     # 浏览器端到端（需 Edge + Playwright）
```

测试覆盖已知正态概率、正负尺寸链、最坏情况、蒙特卡洛复现、零失败置信区间、优化成本下降、
加工范围与锁定、不可行约束、实测数据、无效输入，以及 open supOS 适配器契约（19 项）。

平台侧的真实往返验证（需可用的 open supOS 实例）：

```powershell
python tools/supos_probe.py --publish-probe --load     # 能力探测
python tools/a102_platform_roundtrip.py --samples 12   # 五维 × 三场景真实往返
```

---

## 文档

- [`docs/competition/TolForge-项目介绍.pdf`](docs/competition/TolForge-项目介绍.pdf) — 参赛项目介绍书（可打印）
- [`docs/competition/project-intro.html`](docs/competition/project-intro.html) — 介绍书源稿（可重印 PDF）
- [`docs/enterprise-db.md`](docs/enterprise-db.md) — 本机企业库说明
- [`docs/open-supos-uns-contract.md`](docs/open-supos-uns-contract.md) — 实测得到的 UNS 读写契约
- [`docs/open-supos-openapi-datapath-issue.md`](docs/open-supos-openapi-datapath-issue.md) — 在上游定位的两个真实缺陷
- [`docs/COMPETITION_PROGRESS.md`](docs/COMPETITION_PROGRESS.md) — 分阶段开发记录
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — 贡献方式与提交规范
- [`SECURITY.md`](SECURITY.md) — 安全策略与漏洞报告
- [`THIRD_PARTY.md`](THIRD_PARTY.md) — 第三方依赖与许可证清单
- [`CHANGELOG.md`](CHANGELOG.md) — 版本变更

仓库地址：[https://gitee.com/jyxdyk/tol-forge](https://gitee.com/jyxdyk/tol-forge)

---

## 当前范围与后续开发

**已实现**：真实数值计算、可交互工作台、成本约束优化、测量数据导入、JSON 保存与计算报告、
显式标注的 FreeCAD 文件导入/网格预览/公差属性回写、open supOS 的 UNS 数据接入与应用包打包、
**正式版 LIVE 入口**（桌面 `TolForge正式版` / `start-live.cmd`，无配置拒绝降级）、**本机 Ollama AI 旁路建议**
（`qwen3:latest`：suggest → 采纳 → 历史，**不替换** SciPy SLSQP）、以及**桌面企业库** `enterprise.db` 审计留痕。

**尚未实现**：任意装配的自动尺寸链识别、工程图标注写回、GD&T、三维非线性误差、相关尺寸、
筛选/配组、离散工艺档位。
分析页的装配图为固定结构轴向剖面示意；FreeCAD 页的网格来自真实模型，但不提供 CAD 精密测量
或 B-rep 编辑。权威工程数值仍由 SciPy / 统计推断产出；LLM 只做顾问，不生成权威公差。

**后续优先**：离散工艺档位与成本标定；在已上线的 AI 顾问之上加深约束结构化与可追溯报告
（仍不改权威数值边界）。

---

## 诚实性边界

| 项 | 说明 |
|---|---|
| 通道 | **真实** —— MQTT → open supOS UNS → TimescaleDB → OpenAPI 读回，多次端到端验证 |
| 数值 | **合成** —— 由显式剖面参数生成，**不含任何真实工厂数据** |
| 成本 | 示例成本模型，**未用真实报价标定** |
| Cp/Cpk | 只描述过程能力，**不作为稳定性结论** |
| 优化 | 属设计场景，**不会自动改善工厂实测的 μ/σ** |
| AI 建议 | 本机 Ollama 旁路顾问；**不生成权威公差**；采纳链落企业库可审计 |
| 企业库 | 桌面 `TolForge企业库\enterprise.db`，与平台 schema 隔离 |

---

## 参考

- [NIST: Process Capability](https://www.itl.nist.gov/div898/handbook/pmc/section1/pmc16.htm)
- [SciPy: SLSQP](https://docs.scipy.org/doc/scipy/reference/optimize.minimize-slsqp.html)
- [open supOS](https://www.supos.com/) — 本项目的制造数据底座

---

<div align="center">
<sub>MIT License · NumPy / SciPy (BSD-3-Clause) · 2026 上海开源软件应用创新大赛 · AI + 工业软件赛道</sub>
</div>