Tutorial/docs/RunAndDeploy.md

# 运行与部署说明

## 1. 依赖

所有 Tutorial 插件引用 `D:\MDCS\Release`：

| 组件 | 路径 |
|------|------|
| Medulla | `Release\Medulla\` |
| Clumsy | `Release\Clumsy\ClumsyLite.exe` |
| CommonUsage | `Release\CommonUsage.dll` |
| MDCSToolBox | `Release\MDCSToolBox.dll`（由 `Products\mdcstoolbox` 编译 PostBuild 输出） |

首次使用前编译 MDCSToolBox：

```powershell
dotnet build D:\MDCS\Source\Products\mdcstoolbox\MDCSToolBox.csproj -c Release
```

## 2. 编译 Tutorial

```powershell
cd D:\MDCS\Source\Tutorial
dotnet build Tutorial.sln
```

输出：

- M 插件 → `build\Medulla\plugins\`
- C 插件 → `build\Clumsy\` 与 `build\Clumsy_AGV2\`（PostBuild 复制运行时）
- S 插件 → `build\Simple\plugins\`（PostBuild 复制 SimpleComposer 宿主到 `build\Simple\`）

MultiWheelS 为旧式 net48 项目，需用 MSBuild 单独编译：

```powershell
msbuild D:\MDCS\Source\Tutorial\MultiWheel\MultiWheelS\MultiWheelS.csproj /p:Configuration=Debug
```

或在 Visual Studio 中打开 `Tutorial.sln` 编译 `MultiWheelS` 项目。

## 3. 目录结构

```text
Tutorial/
  DiffWheel/DiffWheelM/   DiffWheel/DiffWheelC/
  MultiWheel/MultiWheelM/ MultiWheel/MultiWheelC/ MultiWheel/MultiWheelS/
  deploy/                 # 配置模板（入库）
  build/                  # 运行目录（gitignore）
```

## 4. 单车验证（多舵轮）

1. 启动 Playground（若使用仿真）
2. 启动 Detour（`DetourLite`，`detour.json` 中 `shareObjectTag=Multi1`，端口 4321）
3. `build\Medulla\start_medulla_agv1.bat`
4. 使用 `deploy\start_clumsy_agv1.bat` 或手动复制：
   - `deploy\chassis.json` → `build\Clumsy\`
   - `deploy\clumsy_agv1\clumsy.json` → `build\Clumsy\clumsy.json`
   - `deploy\clumsy_agv1\clumsyconsole.json` → `build\Clumsy\clumsyconsole.json`
5. 在 `build\Clumsy\` 运行 `ClumsyLite.exe`

## 5. 双车手动联动（同机）

| 配置项 | AGV1（主车） | AGV2（从车） |
|--------|-------------|-------------|
| Medulla | `build\Medulla\` tag `Multi1`，web API **8007** | `build\Medulla_AGV2\` tag `Multi2`，web API **8108** |
| Detour | `detour.json` tag `Multi1`，HTTP **4321** / Web **4322** | `Detour_AGV2\detour.json` tag `Multi2`，HTTP **4421** / Web **4422** |
| `clumsyconsole.json` | `soTag=Multi1`, `port=8008`, `detourPort=4321` | `soTag=Multi2`, `port=8009`, `detourPort=4421` |
| `clumsy.json` msConf | `MultiVehicleMasterEndpoint="/"`, `CarNum=1` | `MultiVehicleMasterEndpoint="127.0.0.1:8008"`, `CarNum=2` |

**tag 一致性**：Detour `shareObjectTag` = Clumsy `soTag` = Medulla `SetShareObjectTag`（见 `startup.iocmd`）。

1. 启动 Playground + 两台 Detour + 两台 Medulla + 两台 ClumsyLite（工作目录 `build\Clumsy` / `build\Clumsy_AGV2`），或使用 `DetourLite\bin\Debug\net8.0\start_all_sim.bat` 一键启动全部 7 个进程
2. 主车 Medulla 遥控器按 **F** 开启「车队联动」
3. 用摇杆驱动：Y=纵向，X=编队转向

## 6. 双车自动联动

1. 完成上一节双车启动
2. 可选：`MultiVehicleSyncUseDetour=true` 开启**车队内姿态纠正**（SLAM 逐车 `PosBias*` 补偿）。注意它**不影响**整车队姿态计算——自动模式无论该开关如何，主车都用 Detour 反推车队中心，无有效定位时会阻塞停车（详见 `MultiVehicleConfig.md` §5）
3. 通过 Simple 调度触发自动联动（推荐）：
   - 编译 `MultiWheelS`（见第 2 节），确认 `build\Simple\plugins\MultiWheelS.dll` 存在
   - 在 `build\Simple\` 运行 `SimpleComposer.exe`（自动加载 `./plugins`）
   - 添加车型 **「多车联动AGV」**（`MultiVehicleCar`，`MultiVehicleSync=true`）
   - 主车设置 `cport:8008`、从车 `cport:8009`（可用 `SetCPort` 或 `conf` 字段）
   - 在该车上规划路径 → 编译为 `agv.BasicGo(..., multiVehicleSync:true)` → 主车 `ChassisController` 开启 `MultiVehicleAutoEnabled`，`PilotDefinition` 50ms 循环广播并驱动车队
4. 自动联动机制已知问题见 [MultiVehicleAutoSyncReview.md](./MultiVehicleAutoSyncReview.md)

## 7. 差速示例

使用 `deploy\clumsy_diff\clumsy.json`，工作目录 `build\Clumsy_diff\`。

## 8. 配置文件说明

| 文件 | 作用 |
|------|------|
| `detour.json` | `shareObjectTag`、`guru.DetourPort`、雷达 layout |
| `clumsyconsole.json` | `soTag`、`port`、`allowMultiple`、`detourHost`/`detourPort` |
| `clumsy.json` | `msConf` → `PilotConfig`（含 `TestCarSyncDistance`、主车端点） |
| `chassis.json` | 四轮舵轮几何 |
| `startup.iocmd` | `SetShareObjectTag Multi1/Multi2` |

详细算法见 [MultiVehicleSync.md](./MultiVehicleSync.md)，修复清单见 [BugFixes.md](./BugFixes.md)，自动联动机制问题分析见 [MultiVehicleAutoSyncReview.md](./MultiVehicleAutoSyncReview.md)。