StandardSence/Doc/QUICK_REFERENCE.md

StandardScene 快速参考

1. 一眼看懂这个仓库

项目项	说明
工程类型	插件库（基座 StandardScene.dll + 4 卫星，共 5 个 DLL）
运行方式	由 SimpleLite.exe（CycleGUI 宿主）从 plugins\ 加载
目标框架	net8.0-windows
核心入口	MissionType、CarType、WebApi.cs
新手起步文件	Scheduler\HeartBeatMission.cs
进阶起步文件	Scheduler\RegionalTrafficControlMission.cs

2. 关键目录速记

路径	你通常在这里做什么
CarTypes\	新车型、协议接入、状态同步
Chained\	搬运任务、环线任务、调度逻辑
Charge\	充电策略、充电桩管理
InterLock\	互锁与交通控制
Scheduler\	心跳、安全、区域流控等后台 Mission
ExtendDevice\Door\	门控联动
Model\	配置与数据模型
WebApi.cs	HTTP API
Commons.cs	标签、字段、选车、路径辅助

3. 构建运行速记

1. 先构建宿主依赖：dotnet build Simple\SimpleLite\SimpleLite.csproj
2. 打开 StandardScene.sln，确保本机依赖路径存在
3. 编译解决方案（Debug|x64 / Release|x64）
4. 将 build\plugins 部署到宿主 plugins\，运行 SimpleLite.exe
5. 确认插件已从 plugins\ 加载

注意

当前工程已是 SDK 风格 .csproj（net8.0-windows），目录下 .cs 文件会被自动包含，无需手工添加 <Compile Include>。卫星插件需在 active-scenes.json 中启用对应场景才会被宿主加载。

4. 新增功能时先看谁

目标	优先参考
新增最小 Mission	Scheduler\HeartBeatMission.cs
做区域限流	Scheduler\RegionalTrafficControlMission.cs
做运输调度	Chained\TransportMission.cs
做环线	Chained\AbstractLoopMission.cs
做充电	Charge\StandardChargeMission.cs
做充电桩管理	Charge\ChargeStationManagementExample.cs
做 Web 接口	WebApi.cs

5. 高频代码片段

获取车辆与站点

var car = SimpleLib.GetCar(carId);
var allCars = SimpleLib.GetAllCars();
var site = SimpleLib.GetSite(siteId);
var allSites = SimpleLib.GetAllSites();
var currentSiteId = car.GetLastSite();

更新标签与字段

Commons.AddOrUpdateTag(car.tags, "occupied", "yes");
Commons.AddOrUpdateCarField(car, "group", "A");
Commons.AddOrUpdateSiteField(site, "giveWay", "true");

规划并执行路径

var plan = new SegmentPlan { usingCar = car };
plan.fields["action"] = "move";
plan.fields["allow_destination_on_route"] = "true";
plan.FindRoute(SimpleLib.GetSite(srcId), SimpleLib.GetSite(dstId));
await plan.Compile("move").Queue();

输出日志

Diagnosis.Post("任务已启动", "demo", true);
Diagnosis.Log("详细调试信息", "demo", true);
car.AppendDebug("车辆状态变化");

6. 常见配置文件

文件	用途
Config\traffic.json	交通 / 互锁配置
Config\ChargeStations.json	充电桩数据
Config\ChargeStrategyConfig.json	充电策略
Config\AlarmConfigs.json	充电报警
DoorConfig.json	门控配置
tasklist.json	环线任务列表
simple.json	宿主基础配置

7. 常见 API 路由

路由	作用
/car/createTask	创建任务
/car/getAllCars	获取车辆列表
/car/goSite	让车辆前往站点
/map/getMap	获取地图
/task/getTask	查询任务
/mission_reflection/get_mission_list	获取 Mission 列表
/mission_reflection/execute/{id}/{method}	反射执行 Mission 方法

8. 调试优先级

出现问题时，建议按这个顺序排查：

1. 插件是否被宿主加载
2. Mission / CarType 是否被识别
3. 配置文件和 fields 是否正确
4. 车辆是否在线、是否被标签占用
5. 路径规划是否成功
6. 是否被交通控制或区域流控拦截
7. 外部接口是否真的打到了 WebApi.cs

9. 常见故障速查

现象	优先检查
新增 Mission 看不到	特性、Create()、.csproj 引用、插件复制
任务一直不执行	车辆在线状态、路径、标签占用、前置条件
区域限流无效	站点字段是否以 Region 开头，值是否为整数
API 调不通	路由路径、宿主端口、Nancy 是否已启动
车辆不动	路径失败、程序未下发、协议未连通

10. 推荐上手案例

HelloMission

• 目标：理解最小插件生命周期
• 参考：Scheduler\HeartBeatMission.cs
• 验证：启动后 status.status 每秒递增

区域流控

• 目标：理解字段驱动 + 事件订阅
• 参考：Scheduler\RegionalTrafficControlMission.cs
• 验证：给站点添加 Region1=1 后，第二台车进入同区域会被阻止