规范模块目录和第三方依赖结构

CMakeLists.txt

@@ -24,7 +24,13 @@ set(SOURCES
 )
 
 # 头文件目录
-include_directories(src)
+include_directories(
+    include
+    third_party
+    third_party/kdl_parser/include
+    third_party/orocos_kdl/install_wasm/include
+    third_party/eigen3
+)
 
 # 创建可执行文件
 add_executable(smart_wasm ${SOURCES})

README.md

@@ -17,7 +17,7 @@
 ```text
 .
 |-- src/                    C++ 业务实现
-|-- inc/                    公共头文件
+|-- include/                公共头文件和业务接口定义
 |-- scripts/                构建、调试、回归测试脚本
 |-- tests/
 |   |-- testdata/           正式回归测试数据
@@ -25,9 +25,12 @@
 |-- docs/
 |   |-- notes/              功能说明和算法笔记
 |   `-- build-logs/         历史编译记录和调试日志
+|-- third_party/
+|   |-- eigen3/             第三方 Eigen 依赖
+|   |-- kdl_parser/         vendored URDF/KDL parser 源码
+|   |-- nlohmann/           JSON 头文件库
+|   `-- orocos_kdl/         第三方 KDL 依赖及安装产物
 |-- public/wasm/            WASM 构建输出
-|-- Eigen3/                 第三方 Eigen 依赖
-|-- KDL/                    第三方 KDL 依赖及安装产物
 |-- package.json            npm 入口
 |-- CMakeLists.txt          CMake 入口
 `-- Makefile                Make 入口
@@ -44,6 +47,8 @@ npm run build-serve
 ## 📁 目录约定
 
 - 根目录只保留项目入口文件和核心目录，避免测试样例、日志、草稿散落在顶层。
+- `include/` 只放本项目对外和模块间共享的头文件。
+- `third_party/` 统一收纳所有外部依赖和 vendored 源码，避免和业务代码混放。
 - `tests/testdata/` 放可重复执行的标准化测试数据。
 - `tests/fixtures/legacy/` 放历史调试输入输出，便于追溯，但默认不作为正式回归入口。
 - `docs/notes/` 放业务说明和算法记录。

include/FourBarMechanism/CrankRockingBlockMechanism_Forward.h

@@ -1,7 +1,7 @@
 #ifndef CRANK_ROCKING_BLOCK_MECHANISM_FORWARD_H
 #define CRANK_ROCKING_BLOCK_MECHANISM_FORWARD_H
 
-#include "CrankSliderMechanism.h"
+#include "FourBarMechanism/CrankSliderMechanism.h"
 #include <vector>
 #include <string>
 #include <map>

include/FourBarMechanism/CrankRockingBlockMechanism_Inverse.h

@@ -1,7 +1,7 @@
 #ifndef CRANK_ROCKING_BLOCK_MECHANISM_INVERSE_H
 #define CRANK_ROCKING_BLOCK_MECHANISM_INVERSE_H
 
-#include "CrankSliderMechanism.h"
+#include "FourBarMechanism/CrankSliderMechanism.h"
 #include <vector>
 #include <string>
 #include <map>

include/FourBarMechanism/CrankSliderMechanism.h

@@ -8,7 +8,7 @@
 #include <cmath>
 #include <chrono>
 #include <memory>
-#include "SharedGeometry.h" // 包含共享的几何类
+#include "SharedGeometry/SharedGeometry.h" // 包含共享的几何类
 // 定义常数
 #ifndef M_PI
 #define M_PI 3.14159265358979323846

include/FourBarMechanism/FourBarMechanism.h

@@ -1,14 +1,14 @@
 // FourBarMechanism.h
 #ifndef FOUR_BAR_MECHANISM_H
 #define FOUR_BAR_MECHANISM_H
-#include "CrankSliderMechanism.h"
+#include "FourBarMechanism/CrankSliderMechanism.h"
 #include <string>
 #include <vector>
 #include <map>
 #include <cmath>
 #include <chrono>
 #include <memory>
-#include "SharedGeometry.h"
+#include "SharedGeometry/SharedGeometry.h"
 
 // 前向声明
 struct MechanismParameters;

include/FourBarMechanism/SliderCrankMechanism.h

@@ -1,12 +1,12 @@
 // SliderCrankMechanism.h
 #ifndef SLIDER_CRANK_MECHANISM_H
 #define SLIDER_CRANK_MECHANISM_H
-#include "CrankSliderMechanism.h"
+#include "FourBarMechanism/CrankSliderMechanism.h"
 #include <string>
 #include <vector>
 #include <map>
 #include <cmath>
-#include "SharedGeometry.h"
+#include "SharedGeometry/SharedGeometry.h"
 // 解模式枚举
 enum class SolutionMode
 {

include/QuadrupedRobotSimulation/BaseClass.h

@@ -16,10 +16,10 @@
 #include <functional>
 #include <sstream>
 #include <iomanip>
-#include "../inc/nlohmann/json.hpp"
-#include "OPERATION.h"
-#include "SharedGeometry.h" // 包含共享的几何类
-#include "RobotConfig.hpp"
+#include <nlohmann/json.hpp>
+#include "QuadrupedRobotSimulation/OPERATION.h"
+#include "SharedGeometry/SharedGeometry.h"
+#include "QuadrupedRobotSimulation/RobotConfig.hpp"
 
 using json = nlohmann::json;
 

include/QuadrupedRobotSimulation/CompleteJsonExporter.h

@@ -2,8 +2,8 @@
 #ifndef COMPLETE_JSON_EXPORTER_H
 #define COMPLETE_JSON_EXPORTER_H
 
-#include "BaseClass.h"
-#include "KinematicsSimulation.h"
+#include "QuadrupedRobotSimulation/BaseClass.h"
+#include "QuadrupedRobotSimulation/KinematicsSimulation.h"
 #include <algorithm>
 #include <cmath>
 #include <vector>

include/QuadrupedRobotSimulation/KinematicsHelper.h

@@ -2,10 +2,10 @@
 #ifndef KINEMATICS_HELPER_H
 #define KINEMATICS_HELPER_H
 
-#include "BaseClass.h"
-#include "KinematicsSimulation.h"
-#include "KinematicsReverse.h"
-#include "CompleteJsonExporter.h"
+#include "QuadrupedRobotSimulation/BaseClass.h"
+#include "QuadrupedRobotSimulation/KinematicsSimulation.h"
+#include "QuadrupedRobotSimulation/KinematicsReverse.h"
+#include "QuadrupedRobotSimulation/CompleteJsonExporter.h"
 #include <string>
 #include <memory>
 #include <chrono>

include/QuadrupedRobotSimulation/KinematicsReverse.h

@@ -12,9 +12,9 @@
 #include <optional>
 
 #include "utils.h"
-#include "BaseClass.h"
-#include "OPERATION.h"
-#include "SharedGeometry.h"
+#include "QuadrupedRobotSimulation/BaseClass.h"
+#include "QuadrupedRobotSimulation/OPERATION.h"
+#include "SharedGeometry/SharedGeometry.h"
 
 class ReverseKinematicsCalculator
 {

include/QuadrupedRobotSimulation/KinematicsSimulation.h

@@ -2,7 +2,7 @@
 #ifndef KINEMATICS_SIMULATION_H
 #define KINEMATICS_SIMULATION_H
 
-#include "BaseClass.h"
+#include "QuadrupedRobotSimulation/BaseClass.h"
 #include <vector>
 #include <string>
 #include <cmath>

include/QuadrupedRobotSimulation/OPERATION.h

@@ -5,7 +5,7 @@
 #include <string>
 #include <vector>
 #include <cmath>
-#include "../inc/nlohmann/json.hpp"
+#include <nlohmann/json.hpp>
 using json = nlohmann::json;
 
 // 毫米转米函数

include/SharedGeometry/SharedGeometry.h

@@ -7,7 +7,7 @@
 #include <cmath>
 #include <sstream>
 #include <iomanip>
-#include "OPERATION.h"
+#include "QuadrupedRobotSimulation/OPERATION.h"
 // 2D向量类
 class Vector2D
 {

scripts/build.ps1

@@ -94,27 +94,24 @@ $compileResult = emcc `
     src/utils.cpp `
     src/math_utils.cpp `
     src/smart_json_wrapper.cpp `
-    src/kdl_parser/src/kdl_parser.cpp `
-    src/kdl_parser/src/joint.cpp `
-    src/kdl_parser/src/link.cpp `
-    src/kdl_parser/src/model.cpp `
-    src/kdl_parser/src/pose.cpp `
-    src/kdl_parser/src/tinystr.cpp `
-    src/kdl_parser/src/tinyxml.cpp `
-    src/kdl_parser/src/tinyxml2.cpp `
-    src/kdl_parser/src/tinyxmlerror.cpp `
-    src/kdl_parser/src/tinyxmlparser.cpp `
-    src/kdl_parser/src/twist.cpp `
-    src/kdl_parser/src/world.cpp `
-    -I./inc `
-    -I./inc/QuadrupedRobotSimulation `
-    -I./inc/FourBarMechanism `
-    -I./inc/SharedGeometry `
-    -I./src/kdl_parser/include `
-    -I./KDL/install_wasm/include `
-    -I./Eigen3 `
-    -I./Eigen3/eigen3 `
-    -L./KDL/install_wasm/lib `
+    third_party/kdl_parser/src/kdl_parser.cpp `
+    third_party/kdl_parser/src/joint.cpp `
+    third_party/kdl_parser/src/link.cpp `
+    third_party/kdl_parser/src/model.cpp `
+    third_party/kdl_parser/src/pose.cpp `
+    third_party/kdl_parser/src/tinystr.cpp `
+    third_party/kdl_parser/src/tinyxml.cpp `
+    third_party/kdl_parser/src/tinyxml2.cpp `
+    third_party/kdl_parser/src/tinyxmlerror.cpp `
+    third_party/kdl_parser/src/tinyxmlparser.cpp `
+    third_party/kdl_parser/src/twist.cpp `
+    third_party/kdl_parser/src/world.cpp `
+    -I./include `
+    -I./third_party `
+    -I./third_party/kdl_parser/include `
+    -I./third_party/orocos_kdl/install_wasm/include `
+    -I./third_party/eigen3 `
+    -L./third_party/orocos_kdl/install_wasm/lib `
     -lorocos-kdl `
     -std=c++17 `
     -s WASM=1 `

scripts/rebuild_with_fixes.ps1

@@ -3,8 +3,42 @@
 Write-Host "=== 重新构建 WASM 模块 ===" -ForegroundColor Cyan
 
 # 设置环境
-$EmsdkPath = "E:\emsdk"
-if (-not (Test-Path $EmsdkPath)) {
+$emsdkCandidates = @()
+
+if ($env:EMSDK) {
+    $emsdkCandidates += $env:EMSDK
+}
+
+$emsdkCandidates += "E:\emsdk"
+$emsdkCandidates += (Join-Path (Split-Path $PSScriptRoot -Parent) "..\emsdk")
+$emsdkCandidates += (Join-Path (Split-Path $PSScriptRoot -Parent) "emsdk")
+
+$emccCommand = Get-Command emcc -ErrorAction SilentlyContinue
+if ($emccCommand -and $emccCommand.Source) {
+    $emccSourceDir = Split-Path $emccCommand.Source -Parent
+    if (Test-Path (Join-Path $emccSourceDir "emcc.ps1")) {
+        $emsdkCandidates += (Split-Path (Split-Path $emccSourceDir -Parent) -Parent)
+    }
+}
+
+$EmsdkPath = $null
+foreach ($candidate in $emsdkCandidates | Select-Object -Unique) {
+    if (-not [string]::IsNullOrWhiteSpace($candidate)) {
+        try {
+            if (Test-Path $candidate) {
+                $resolvedCandidate = [System.IO.Path]::GetFullPath($candidate)
+                if (Test-Path (Join-Path $resolvedCandidate "upstream\emscripten\emcc.ps1")) {
+                    $EmsdkPath = $resolvedCandidate
+                    break
+                }
+            }
+        } catch {
+            continue
+        }
+    }
+}
+
+if (-not $EmsdkPath) {
     Write-Host "[错误] 未找到 Emscripten" -ForegroundColor Red
     exit 1
 }
@@ -18,7 +52,7 @@ Write-Host "[ ] 编译 WASM 模块（包含完整的运行时方法）..." -Fore
 
 # 完整的编译命令
 $compileCmd = @'
-emcc src/math_utils.cpp src/smart_json_wrapper.cpp src/main.cpp -I./src -std=c++17 -s WASM=1 -s EXPORTED_FUNCTIONS='["_smart_process_json","_smart_get_function_list","_smart_get_function_info","_smart_test_match","_smart_get_version","_smart_free_string","_main"]' -s EXPORTED_RUNTIME_METHODS='["ccall","cwrap","UTF8ToString","stringToUTF8","lengthBytesUTF8","allocateUTF8","allocate","ALLOC_NORMAL","getValue","setValue"]' -s MODULARIZE=1 -s EXPORT_NAME="createSmartMathModule" -s ALLOW_MEMORY_GROWTH=1 -s ASSERTIONS=1 -O3 -o public/wasm/smart_math.js
+emcc src/math_utils.cpp src/smart_json_wrapper.cpp src/main.cpp -I./include -I./third_party -I./third_party/kdl_parser/include -I./third_party/orocos_kdl/install_wasm/include -I./third_party/eigen3 -std=c++17 -s WASM=1 -s EXPORTED_FUNCTIONS='["_smart_process_json","_smart_get_function_list","_smart_get_function_info","_smart_test_match","_smart_get_version","_smart_free_string","_main"]' -s EXPORTED_RUNTIME_METHODS='["ccall","cwrap","UTF8ToString","stringToUTF8","lengthBytesUTF8","allocateUTF8","allocate","ALLOC_NORMAL","getValue","setValue"]' -s MODULARIZE=1 -s EXPORT_NAME="createSmartMathModule" -s ALLOW_MEMORY_GROWTH=1 -s ASSERTIONS=1 -O3 -o public/wasm/smart_math.js
 '@
 
 Write-Host "执行命令: $compileCmd" -ForegroundColor Gray

scripts/test_compile.ps1

@@ -3,17 +3,60 @@
 Write-Host "=== 测试编译 ===" -ForegroundColor Cyan
 
 # 设置环境
-$EmsdkPath = "E:\emsdk"
-if (-not (Test-Path $EmsdkPath)) {
+$emsdkCandidates = @()
+
+if ($env:EMSDK) {
+    $emsdkCandidates += $env:EMSDK
+}
+
+$emsdkCandidates += "E:\emsdk"
+$emsdkCandidates += (Join-Path (Split-Path $PSScriptRoot -Parent) "..\emsdk")
+$emsdkCandidates += (Join-Path (Split-Path $PSScriptRoot -Parent) "emsdk")
+
+$emccCommand = Get-Command emcc -ErrorAction SilentlyContinue
+if ($emccCommand -and $emccCommand.Source) {
+    $emccSourceDir = Split-Path $emccCommand.Source -Parent
+    if (Test-Path (Join-Path $emccSourceDir "emcc.ps1")) {
+        $emsdkCandidates += (Split-Path (Split-Path $emccSourceDir -Parent) -Parent)
+    }
+}
+
+$EmsdkPath = $null
+foreach ($candidate in $emsdkCandidates | Select-Object -Unique) {
+    if (-not [string]::IsNullOrWhiteSpace($candidate)) {
+        try {
+            if (Test-Path $candidate) {
+                $resolvedCandidate = [System.IO.Path]::GetFullPath($candidate)
+                if (Test-Path (Join-Path $resolvedCandidate "upstream\emscripten\emcc.ps1")) {
+                    $EmsdkPath = $resolvedCandidate
+                    break
+                }
+            }
+        } catch {
+            continue
+        }
+    }
+}
+
+if (-not $EmsdkPath) {
     Write-Host "[错误] 未找到 Emscripten" -ForegroundColor Red
     exit 1
 }
 
 $env:PATH = "$EmsdkPath\upstream\emscripten;$env:PATH"
 
+# 公共包含目录
+$includeArgs = @(
+    '-I./include',
+    '-I./third_party',
+    '-I./third_party/kdl_parser/include',
+    '-I./third_party/orocos_kdl/install_wasm/include',
+    '-I./third_party/eigen3'
+)
+
 # 测试 1: 编译 math_utils.cpp
 Write-Host "[ ] 测试编译 math_utils.cpp..." -ForegroundColor Cyan
-emcc src/math_utils.cpp -I./src -s WASM=1 -c -o test_math.o 2>&1
+emcc src/math_utils.cpp @includeArgs -s WASM=1 -c -o test_math.o 2>&1
 if ($LASTEXITCODE -eq 0) {
     Write-Host "[✓] math_utils.cpp 编译成功" -ForegroundColor Green
 } else {
@@ -22,7 +65,7 @@ if ($LASTEXITCODE -eq 0) {
 
 # 测试 2: 编译 smart_json_wrapper.cpp
 Write-Host "[ ] 测试编译 smart_json_wrapper.cpp..." -ForegroundColor Cyan
-emcc src/smart_json_wrapper.cpp -I./src -s WASM=1 -c -o test_wrapper.o 2>&1
+emcc src/smart_json_wrapper.cpp @includeArgs -s WASM=1 -c -o test_wrapper.o 2>&1
 if ($LASTEXITCODE -eq 0) {
     Write-Host "[✓] smart_json_wrapper.cpp 编译成功" -ForegroundColor Green
 } else {
@@ -31,7 +74,7 @@ if ($LASTEXITCODE -eq 0) {
 
 # 测试 3: 编译 main.cpp
 Write-Host "[ ] 测试编译 main.cpp..." -ForegroundColor Cyan
-emcc src/main.cpp -I./src -s WASM=1 -c -o test_main.o 2>&1
+emcc src/main.cpp @includeArgs -s WASM=1 -c -o test_main.o 2>&1
 if ($LASTEXITCODE -eq 0) {
     Write-Host "[✓] main.cpp 编译成功" -ForegroundColor Green
 } else {

src/FourBarMechanism/CrankRockingBlockMechanism_Forward.cpp

@@ -1,4 +1,4 @@
-#include "CrankRockingBlockMechanism_Forward.h"
+#include "FourBarMechanism/CrankRockingBlockMechanism_Forward.h"
 #include <cmath>
 #include <algorithm>
 #include <stdexcept>

src/FourBarMechanism/CrankRockingBlockMechanism_Inverse.cpp

@@ -1,4 +1,4 @@
-#include "CrankRockingBlockMechanism_Inverse.h"
+#include "FourBarMechanism/CrankRockingBlockMechanism_Inverse.h"
 #include <cmath>
 #include <algorithm>
 #include <stdexcept>

src/FourBarMechanism/CrankSliderMechanism.cpp

@@ -1,5 +1,5 @@
 // mechanism_simulation.cpp
-#include "CrankSliderMechanism.h"
+#include "FourBarMechanism/CrankSliderMechanism.h"
 #include <stdexcept>
 #include <algorithm>
 #include <cstdio>

src/FourBarMechanism/FourBarMechanism.cpp

@@ -1,5 +1,5 @@
 // FourBarMechanism.cpp
-#include "FourBarMechanism.h"
+#include "FourBarMechanism/FourBarMechanism.h"
 #include <stdexcept>
 #include <algorithm>
 #include <cstdio>

src/FourBarMechanism/SliderCrankMechanism.cpp

@@ -1,5 +1,5 @@
 // SliderCrankMechanism.cpp
-#include "SliderCrankMechanism.h"
+#include "FourBarMechanism/SliderCrankMechanism.h"
 #include <stdexcept>
 #include <algorithm>
 #include <cstdio>

src/KinematicsWebAPI.cpp

@@ -1,7 +1,7 @@
 
-#include "KinematicsHelper.h"
+#include "QuadrupedRobotSimulation/KinematicsHelper.h"
 #include "KinematicsWebAPI.h"
-#include "CrankSliderMechanism.h"
+#include "FourBarMechanism/CrankSliderMechanism.h"
 #include "URDFStrings.h"
 
 #include <iostream>

src/QuadrupedRobotSimulation/BaseClass.cpp

@@ -1,5 +1,5 @@
 // BaseClass.cpp - 修复type_error::create错误
-#include "BaseClass.h"
+#include "QuadrupedRobotSimulation/BaseClass.h"
 
 // 为nlohmann/json添加std::optional支持
 namespace nlohmann

src/QuadrupedRobotSimulation/CompleteJsonExporter.cpp

@@ -1,7 +1,7 @@
 // CompleteJsonExporter.cpp
-#include "CompleteJsonExporter.h"
-#include "BaseClass.h"
-#include "KinematicsSimulation.h"
+#include "QuadrupedRobotSimulation/CompleteJsonExporter.h"
+#include "QuadrupedRobotSimulation/BaseClass.h"
+#include "QuadrupedRobotSimulation/KinematicsSimulation.h"
 #include <algorithm>
 #include <cmath>
 #include <functional>

src/QuadrupedRobotSimulation/KinematicsHelper.cpp

@@ -1,6 +1,6 @@
 // KinematicsHelper.cpp
-#include "KinematicsHelper.h"
-#include "RobotConfig.hpp"
+#include "QuadrupedRobotSimulation/KinematicsHelper.h"
+#include "QuadrupedRobotSimulation/RobotConfig.hpp"
 #include <iostream>
 #include <sstream>
 #include <iomanip>

src/QuadrupedRobotSimulation/KinematicsReverse.cpp

@@ -1,7 +1,7 @@
 // KinematicsReverse.cpp
-#include "KinematicsReverse.h"
-#include "graph_utils.hpp"
-#include "RobotConfig.hpp"
+#include "QuadrupedRobotSimulation/KinematicsReverse.h"
+#include "QuadrupedRobotSimulation/graph_utils.hpp"
+#include "QuadrupedRobotSimulation/RobotConfig.hpp"
 
 #include <iostream>
 #include <sstream>

src/QuadrupedRobotSimulation/KinematicsSimulation.cpp

@@ -1,6 +1,6 @@
 // KinematicsSimulation.cpp
-#include "CompleteJsonExporter.h"
-#include "KinematicsSimulation.h"
+#include "QuadrupedRobotSimulation/CompleteJsonExporter.h"
+#include "QuadrupedRobotSimulation/KinematicsSimulation.h"
 #include <functional>
 #include <numeric>
 #include <iomanip>

src/QuadrupedRobotSimulation/RobotConfig.cpp

@@ -1,4 +1,4 @@
-#include "RobotConfig.hpp"
+#include "QuadrupedRobotSimulation/RobotConfig.hpp"
 // 统一的更新函数：手动从JSON更新现有对象
 RequestParameters &RequestParameters::updateFromJson(const nlohmann::json &j, RequestParameters &req_param)
 {

src/QuadrupedRobotSimulation/SharedGeometry.cpp

@@ -1,5 +1,5 @@
 // SharedGeometry.cpp
-#include "SharedGeometry.h"
+#include "SharedGeometry/SharedGeometry.h"
 #include <stdexcept>
 #include <cmath>
 #include <algorithm>

tests/test_smart_json.cpp

@@ -1,4 +1,4 @@
-#include "../src/smart_json_wrapper.h"
+#include "../include/smart_json_wrapper.h"
 #include <iostream>
 #include <string>