# 工智审图

工业建设项目多专业 AI 辅助审图 MVP。当前版本聚焦工业厂房建筑、结构、电气三类二维图纸，提供上传解析、对象抽取、确定性规则检查、证据切片、人工复核、模型辅助解释，以及 HTML/PDF/DOCX 报告导出。

> AI 识别只作为设计校核和人工审图辅助；正式结论仍需具备资质的专业人员确认。

## 快速开始

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
npm ci
npm run build
python scripts/start_web.py
```

默认 Web 入口：

```text
http://127.0.0.1:8000
```

## 常用验证

```powershell
python -m pytest
python scripts/smoke_test.py
npm run test
npm run build
npm run verify:browser
python scripts/test_ocr_providers.py
python scripts/vision_model_install_plan.py --model moondream
python scripts/check_ollama_vision_capability.py
python scripts/test_unlimited_ocr_compat.py
python scripts/acceptance_audit.py
```

当前已验证：

- `pytest`: 39 passed
- `smoke_test`: precision 1.0 / recall 1.0
- `npm run test`: TypeScript 通过
- `npm run build`: Vite 构建通过
- `npm run verify:browser`: 证据框、运行证据栏、验收状态和模型边界展示验证通过，并写入 `artifacts/browser_verification.json`
- `scripts/test_ocr_providers.py`: 生成 `artifacts/ocr_comparison.json/html`
- `scripts/check_ollama_vision_capability.py`: 生成 `artifacts/ollama_vision_inventory.json`，盘点本机 Ollama 模型图像能力
- `scripts/test_unlimited_ocr_compat.py`: 不下载模型，只记录 Unlimited-OCR 兼容性状态
- `scripts/acceptance_audit.py`: 汇总当前验收证据，未满足项会返回非零
- `/api/acceptance/status`: 为前端工作台提供当前验收摘要

视觉模型安装与验收说明见 `docs/vision-model-setup.md`。

## 前端工作台

工作台采用三栏工业控制台布局：

- 左侧：项目台账、上传入口、文本/视觉模型设置、OCR Provider 状态与切换、图纸清单
- 中间：图纸视窗、定位框、证据快照、问题详情、模型解释与视觉核验
- 右侧：问题清单、等级/状态筛选、人工复核操作

界面文案为中文本地化，状态标签会区分 Mock、Ollama、OpenAI-Compatible、OCR Provider、降级状态和是否发送图片。
顶部运行证据栏会集中显示规则引擎、OCR、文本模型、视觉模型、外部图纸和数据处理位置；问题详情会显示生成来源、OCR 来源、证据说明和模型参与边界，便于答辩时说明正式问题并非由 LLM 凭空生成。

## Text-to-CAD 集成

项目已提供对 [`earthtojake/text-to-cad`](https://github.com/earthtojake/text-to-cad) 的可选桥接。它使用独立 Python 3.12 环境生成 STEP，并调用上游确定性检查工具提取尺寸、平面和定位事实；现有 Python 3.11 审图环境不受影响。

Windows 一键安装：

```powershell
powershell -ExecutionPolicy Bypass -File scripts/setup_text_to_cad.ps1
Copy-Item .env.example .env  # 仅在尚无 .env 时执行
# 编辑 .env，将 CAD_ENABLED 改为 true
python scripts/start_web.py
```

安装脚本会跳过 Git LFS 大型演示资源，将上游仓库浅克隆到 `.tools/text-to-cad`，并在 `.venv-cad` 安装 `build123d`、`cadquery-ocp` 和 `cadpy`。两者均已加入 `.gitignore`。当前 Windows 安装会固定 `cadquery-ocp==7.9.3.1`，以规避 `7.9.3.1.1` 拆分包在本机出现的 OCP DLL 加载问题；脚本最后会执行真实导入和两个 CLI 的启动验证，失败时返回非零状态。更新上游版本时执行：

```powershell
powershell -ExecutionPolicy Bypass -File scripts/setup_text_to_cad.ps1 -Update
```

CAD 源文件及产物默认放在 `models/cad/`。生成器必须是定义了 `gen_step()` 的 Python 文件，例如 `models/cad/bracket.py`。API 示例：

```powershell
# 能力和环境检查
Invoke-RestMethod http://127.0.0.1:8000/api/cad/status

# 从受控生成器产生 STEP，并自动执行 facts/planes/positioning 检查
$body = @{ source = "bracket.py"; output = "bracket.step"; exports = @("stl", "glb") } | ConvertTo-Json
Invoke-RestMethod http://127.0.0.1:8000/api/cad/generate -Method Post -ContentType "application/json" -Body $body

# 检查已有 STEP
$body = @{ artifact = "bracket.step" } | ConvertTo-Json
Invoke-RestMethod http://127.0.0.1:8000/api/cad/inspect -Method Post -ContentType "application/json" -Body $body
```

相关接口：

- `GET /api/cad/status`：检查仓库、Python 3.12 与 CAD 依赖。
- `GET /api/cad/artifacts`：列出 STEP/STP/STL/3MF/GLB/DXF 产物。
- `GET /api/cad/artifacts/{path}`：下载指定产物。
- `POST /api/cad/generate`：运行受限于 `CAD_ARTIFACT_DIR` 的生成器，并自动检查 STEP。
- `POST /api/cad/inspect`：检查已有 STEP/STP。

安全边界：API 只接受 `CAD_ARTIFACT_DIR` 下的相对路径，拒绝目录穿越和任意绝对路径。生成器本质上是本地 Python 代码，因此只应放入经过评审的项目源文件；不要将该接口直接暴露到公网。CAD 检查提供几何事实，不代表结构安全、制造认证或规范合规结论，正式结论仍需规则引擎与专业人员复核。

可选环境变量：

```env
CAD_ENABLED=true
CAD_SKILL_DIR=.tools/text-to-cad/skills/cad
CAD_PYTHON_EXECUTABLE=.venv-cad/Scripts/python.exe
CAD_ARTIFACT_DIR=models/cad
CAD_TIMEOUT_SECONDS=600
CAD_VIEWER_URL=
```

如需浏览器三维预览，按上游 CAD Viewer 的启动命令运行 Viewer，并把输出 URL 写入 `CAD_VIEWER_URL`；产物列表和生成结果会返回对应的 `file=` 链接。

## OCR Provider

OCR 现在通过 `src/gongzhi_review/ocr/` 独立路由。

支持：

- `sidecar`: 读取同名 `.ocr.json` / `.ocr.txt`
- `windows-ocr`: Windows 本机 OCR API，不额外下载模型，适合本地中文/英文文本识别
- `paddle`: 可选 PaddleOCR，本地传统 OCR，默认不强制安装
- `unlimited-ocr`: Unlimited-OCR-GGUF 实验适配
- `vision`: 视觉模型语义降级，不作为可信 bbox OCR
- `auto`: sidecar -> Windows OCR -> PaddleOCR -> Unlimited-OCR -> vision

安装传统 OCR 可选依赖：

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

没有安装 PaddleOCR 时系统不会崩溃；在 Windows 上会优先尝试系统 OCR，并在 UI 和 `artifacts/ocr_comparison.json` 中显示每个 Provider 的可用性、bbox 能力和降级原因。

## Ollama

推荐使用目标文件要求的分离环境变量：

```env
TEXT_PROVIDER=ollama
TEXT_BASE_URL=http://127.0.0.1:11434
TEXT_MODEL=
TEXT_TIMEOUT_SECONDS=180
TEXT_MAX_RETRIES=1

VISION_PROVIDER=ollama
VISION_BASE_URL=http://127.0.0.1:11434
VISION_MODEL=
VISION_TIMEOUT_SECONDS=240
VISION_MAX_RETRIES=1
VISION_MAX_IMAGE_EDGE=2048
```

真实链路测试：

```powershell
$env:TEXT_MODEL="your-text-model"
$env:VISION_MODEL="your-vision-model"
python scripts/test_ollama_pipeline.py
```

本机已证明 Ollama 文本模型可真实返回 JSON。视觉链路已证明图片 payload 被发送，但当前测试模型拒绝图片输入，需要安装支持图像输入的 Ollama 视觉模型或带 mmproj 的专用服务。

## 外部公开图纸盲测

下载公开图纸并记录来源、URL、时间、Content-Type、大小、SHA-256：

```powershell
python scripts/download_external_test_drawing.py
```

运行盲测：

```powershell
python scripts/run_external_drawing_test.py
```

产物位置：

```text
data/external_test/
artifacts/external_test/
```

下载的 PDF、模型权重和外部测试产物不提交 Git，不作为训练集，不重新分发。

## 重要边界

- 正式问题只能由确定性规则或几何证据生成，LLM/VLM 只能解释、辅助分类或核验。
- OCR 文本不能直接变成正式违规结论。
- 国外公开图纸不得套用中国规范给出合规/违规结论。
- Unlimited-OCR-GGUF 仍是实验能力，未跑通前不能宣传为稳定支持。
- DWG/RVT 仍是识别和转换提示，未做原生深度解析。