first commit

2026-07-17 17:45:56 +08:00
commit 04c487823b
5873 changed files with 12227228 additions and 0 deletions
@@ -0,0 +1,343 @@
+# Agent4 查错流程边界总览
+
+本文只定义四类查错流程的边界、输入输出和相互引用关系，不替代各子模块的详细实现文档。
+
+四类查错必须分开维护：
+
+1. 三维零件查错。
+2. 三维装配体查错。
+3. 二维零件图查错。
+4. 二维装配图查错。
+
+不要把某一类流程中的中间产物当成另一类流程的默认输入，除非接口文档明确声明。例如：三维装配体接触功能语义可以服务于二维装配图公差判断，但二维零件图格式查错不应依赖三维装配体接触语义。
+
+## 1. 三维零件查错
+
+### 1.1 入口
+
+前端目标：`part`
+
+后端入口：
+
+```text
+POST /api/mechanical-diagnostics/diagnose/start
+GET  /api/mechanical-diagnostics/diagnose/status/{jobId}
+POST /api/mechanical-diagnostics/diagnose/finalize-existing
+POST /api/mechanical-diagnostics/diagnose/load-existing
+```
+
+请求核心输入：
+
+```text
+model_path                 单个 .SLDPRT 路径
+part_function_profile      零件功能画像，单零件查错必填
+output_dir                 可选
+```
+
+### 1.2 职责
+
+三维零件查错只判断单个零件自身结构设计问题。它不负责：
+
+- 判断装配体内多个零件之间的配合是否合理。
+- 判断二维图的公差、粗糙度或格式表达是否正确。
+- 生成二维线条归属信息。
+
+### 1.3 当前主流程
+
+当前前端进度步骤对应：
+
+1. 提取 B-rep 信息与特征分组。
+2. 提取特征高亮图片。
+3. 获取粗扫描信息。
+4. 检索动态知识表。
+5. 生成局部子图。
+6. 规则判定。
+
+后端主要由 `MechanicalDiagnostics.cs` 编排，底层证据主要来自 `SectionBrepExtractor` 和 `BrepFaultProbe`。
+
+详细契约见：
+
+- `tools/model-diagnostics/MECHANICAL_DIAGNOSTIC_CONTRACT.md`
+- `tools/model-diagnostics/MECHANICAL_DIAGNOSTIC_USAGE.md`
+
+### 1.4 输出
+
+典型输出包括：
+
+- B-rep/特征/图片证据。
+- 局部语义子图。
+- 检索到的规则候选。
+- 最终三维零件问题判定。
+
+这些输出可以作为三维装配体查错中“某个非标零件自身问题”的内部复用流程，但不能直接作为二维公差判定结论。
+
+## 2. 三维装配体查错
+
+### 2.1 入口
+
+前端目标：`assembly`
+
+后端入口同三维零件查错，仍由机械查错服务编排：
+
+```text
+POST /api/mechanical-diagnostics/diagnose/start
+GET  /api/mechanical-diagnostics/diagnose/status/{jobId}
+POST /api/mechanical-diagnostics/diagnose/finalize-existing
+POST /api/mechanical-diagnostics/diagnose/load-existing
+```
+
+请求核心输入：
+
+```text
+model_path                    .SLDASM 路径
+product_description           装配体/产品用途描述
+purchased_component_hints     外购件/标准件完整名称或实例名
+output_dir                    可选
+```
+
+### 2.2 职责
+
+三维装配体查错判断整机/装配体层面的设计问题，同时对需要检查的非标零件执行零件级查错。
+
+它负责：
+
+- 识别零件整体功能。
+- 识别零件之间的接触、配合、同轴、贴合、支承、定位、运动和可达性关系。
+- 对 B-rep 推导出的物理接触接口导出接触高亮图片，并让 VLM 结合图片、B-rep、配合关系和零件功能分析接口功能。
+- 区分外购件/标准件和需要检查的非标件。
+- 生成装配体接触功能语义。
+- 评估连接方式，包括是否存在螺钉、键、销、挡圈、肩部、胶接、焊接等固定方式，以及是否可能需要过盈。
+- 对功能组内非标零件复用三维零件查错流程。
+
+它不负责：
+
+- 直接判断二维图纸上的公差值是否表达正确。
+- 直接判断二维 DWG 图元格式。
+
+### 2.3 当前主流程
+
+当前前端进度步骤对应：
+
+1. 提取零件 B-rep 与装配关系。
+2. 提取零件高亮图。
+3. 导出物理接触接口高亮图。
+4. VLM 结合接触高亮图、B-rep、mate 和零件功能生成接触面/接口功能描述。
+5. LLM 生成各零件功能介绍。
+6. 形成多个功能组。
+7. 按功能组走零件查错过程。
+8. 检索功能组相关规则。
+9. 判定配合关系和零件自身问题。
+
+关键要求：
+
+- 零件功能和接触功能必须分开。
+- 外购件/标准件只作为装配上下文，默认不做内部结构查错。
+- 内部接触和外部接触的分析范围必须显式区分。
+- 接触不等于固定，连接方式判断要单独记录。
+
+### 2.4 输出给二维装配图使用的内容
+
+二维装配图公差查错可以复用三维装配体查错输出中的接触功能语义，但只能把它当作证据，不是最终二维判定。
+
+可复用内容包括：
+
+- `component_function_profiles`
+- `interface_function_profiles`
+- `connection_assessment`
+- `diagnostic_context/interface_function_descriptions.json`
+- B-rep face pair：`face_a/face_b`
+- 接触面几何：surface kind、diameter、axis、center、bbox、gap、overlap 等
+- 组件实例名和接触接口 ID
+
+## 3. 二维零件图查错
+
+### 3.1 入口
+
+前端目标：`drawing-part`
+
+后端入口：
+
+```text
+POST /api/drawing-part-diagnostics/run-full
+GET  /api/drawing-part-diagnostics/latest
+GET  /api/drawing-part-diagnostics/image
+```
+
+请求核心输入：
+
+```text
+student_dwg_path      学生二维零件图 DWG
+output_dir            可选
+```
+
+### 3.2 当前职责边界
+
+当前二维零件图查错已经接入的是格式查错，主要检查：
+
+- 线型。
+- 线宽。
+- 中心线/轴线。
+- 虚线。
+- 尺寸线。
+- 引出线。
+- 剖面线。
+- 齿轮分度圆线。
+- 螺纹牙底线。
+
+当前规则是后端程序化判定，不交给 AI。
+
+当前二维零件图查错不负责：
+
+- 装配体公差配合判断。
+- 三维 B-rep 接触接口绑定。
+- 二维装配图多视图汇总。
+
+后续如果扩展二维零件图的标注错误、绘制错误，可以新增独立阶段，但不能和二维装配图公差接口混用。
+
+### 3.3 当前主流程
+
+1. 读取学生零件 DWG。
+2. 调用 DWG 抽取器输出结构化 JSON。
+3. 根据 `entities-common.json`、`geometry.json`、`normalized-geometry.json`、`dimensions.json`、`unknown-entities.json` 等进行程序化格式规则检查。
+4. 输出 `format_issues.json`。
+5. 生成 `final_report.md`。
+6. 前端展示格式问题和证据图片。
+
+核心实现位置：
+
+- `backend-csharp/Agent4.Api/DrawingAssemblyDiagnostics.cs`
+  - `RunPartFormatAsync`
+  - `BuildLineStyleRuleCheck`
+  - `BuildFormatIssuesAsync`
+  - `BuildDrawingPartFormatReport`
+
+## 4. 二维装配图查错
+
+### 4.1 入口
+
+前端目标：`drawing-assembly`
+
+后端入口：
+
+```text
+POST /api/drawing-assembly-diagnostics/run-full
+POST /api/drawing-assembly-diagnostics/build-interface-drawing-context
+POST /api/drawing-assembly-diagnostics/build-tolerance-context
+GET  /api/drawing-assembly-diagnostics/latest
+GET  /api/drawing-assembly-diagnostics/image
+```
+
+当前 `run-full` 侧重完整二维装配图分析；`build-interface-drawing-context` / `build-tolerance-context` 侧重二维公差到三维接口的证据上下文构建。
+
+### 4.2 职责
+
+二维装配图查错负责判断装配工程图表达是否正确，包括：
+
+- 格式类问题。
+- 标注类问题。
+- 绘制表达类问题。
+- 公差/粗糙度与三维装配接触功能是否对应。
+
+其中公差/粗糙度判断必须复用三维装配体接触功能语义，但二维装配图流程仍然独立负责：
+
+- 学生 DWG 抽取。
+- 学生图多视图识别。
+- 标准工程图视图生成与对齐。
+- 上色二维图生成。
+- 线条归属提取。
+- 学生标注到二维线条的绑定。
+- 二维线条到三维 B-rep 接触面的绑定。
+- 多视图汇总。
+- 多标、漏标、错标候选生成。
+- 将闭合证据包交给 AI 判断。
+
+### 4.3 标准视图/线条归属子流程
+
+这个子流程已经有细节实现和文档，不应在公差查错文档里简化重写。
+
+权威细节见：
+
+- `tools/drawing-diagnostics/README.md`
+- `tools/drawing-diagnostics/SolidWorksViewCandidateGenerator/README.md`
+- `tools/drawing-diagnostics/DRAWING_GEOMETRY_NORMALIZATION.md`
+
+其中包括但不限于：
+
+- 学生 DWG 主视图签名提取。
+- 24 个 SolidWorks 候选视图生成。
+- 候选 DWG 串行抽取。
+- 候选排序。
+- 主视图放置。
+- 图框中心对齐。
+- 主视图原点对齐。
+- 剖视图/其他视图区域分析与对齐。
+- 上色二维图生成。
+- hover/grid 采样。
+- 所有视图线条归属汇总。
+
+上层公差查错只引用该子流程产物，不重新定义它。
+
+### 4.4 公差/粗糙度专项
+
+公差/粗糙度专项的权威规范见：
+
+- `tools/drawing-diagnostics/ASSEMBLY_TOLERANCE_DIAGNOSTIC_FLOW.md`
+
+该专项流程的核心判断是：
+
+- 二维有公差但匹配不到三维接触接口：疑似多标/无效标注。
+- 三维接触接口需要公差但多视图汇总后找不到二维公差：疑似漏标。
+- 二维公差与三维接触接口唯一对应：交给 AI 结合固定公差知识判断是否错标。
+
+### 4.5 和三维装配体查错的关系
+
+二维装配图公差判断依赖三维装配体接触语义，但不重新做三维装配体查错。
+
+正确关系是：
+
+```text
+三维装配体查错/接触语义输出
+        ↓ 作为输入证据
+二维装配图公差-B-rep 绑定
+        ↓
+二维图多标/漏标/错标候选
+        ↓
+AI + 固定公差知识最终判断
+```
+
+不能反过来让二维装配图流程修改三维接触语义，也不能让三维装配体流程直接输出二维公差结论。
+
+## 5. 共享产物和禁止混用规则
+
+### 5.1 可以共享的产物
+
+- 三维装配体接触功能语义可以给二维装配图公差/粗糙度判断使用。
+- 二维标准视图线条归属可以给二维装配图标注绑定使用。
+- DWG 抽取结构化 JSON 可以被二维零件图格式查错和二维装配图标注绑定分别使用。
+
+### 5.2 禁止混用
+
+- 二维零件图格式查错不得调用三维装配体接触语义。
+- 三维零件查错不得生成二维图纸公差结论。
+- 三维装配体查错不得把“接触存在”直接等价为“二维公差应为某具体代号”。
+- 二维装配图公差查错不得跳过二维线条归属和多视图汇总，直接用公差文本匹配三维直径。
+- 公差知识当前作为固定提示词进入 AI 判定，不在证据构建阶段做实时检索。
+
+## 6. 推荐目录和输出命名
+
+建议保持输出目录分开：
+
+```text
+runtime/section_brep/...
+runtime/brep_semantic_bridge/...
+runtime/drawing-part-diagnostics/...
+runtime/drawing-assembly-diagnostics/...
+runtime/current-standard-flow/...
+```
+
+其中：
+
+- `section_brep` / `brep_semantic_bridge` 属于三维查错。
+- `drawing-part-diagnostics` 属于二维零件图查错。
+- `drawing-assembly-diagnostics` 属于二维装配图查错。
+- `current-standard-flow` 可作为二维装配图标准视图/线条归属流水线输出，但其子目录含义必须由对应模块文档解释。