工业紫文档门户 · Offline Ready · No Deploy Needed

## StandardScene 开发指南与快速开始

本页面已经把开发指南、模块地图、构建方式、快速开始案例和常见排错整合到一个 HTML 文件中。 你可以直接双击 `DocumentHub.html` 打开，无需部署、无需联网、无需额外资源。

.NET 8
工程目标框架 (net8.0-windows)
Plugin DLL
输出为 `StandardScene.dll`
Mission + CarType
两类核心扩展入口
中文 / EN / 😎
字体与编码已兼容
查看快速开始 打开 Markdown 开发指南 打开速查手册
On This Page
推荐第一步：先做 `HelloMission`，再做 `Region1=1` 的区域流控实验。前者帮助理解插件生命周期，后者帮助理解字段驱动与事件订阅。

### 01. 项目总览

`StandardScene` 是 AGV/AMR 场景插件库，不是独立 EXE。它依赖宿主 `SimpleLite.exe`（CycleGUI 应用）运行，能力覆盖搬运调度、环线任务、 交通互锁、区域流量控制、充电协同、门控联动，以及 HTTP / MQTT / Modbus 等外围接口。

项目定位 作为宿主插件被加载，核心职责是“场景逻辑”而不是“独立应用”。
最小理解单元 `Mission` 负责场景流程，`CarType` 负责车型与协议。
最先阅读文件 `Scheduler/HeartBeatMission.cs`、`Scheduler/RegionalTrafficControlMission.cs`
输出类型：Library 宿主：SimpleLite.exe 外部接口：Nancy / HTTP 典型协议：MQTT / Modbus

### 02. 运行架构

层级 | 角色 | 典型文件
--- | --- | ---
宿主层 | 启动程序、装载插件、展示配置与 Mission | `SimpleLite.exe`
场景逻辑层 | 任务调度、区域流控、充电、门禁等 | `Scheduler/`、`Chained/`、`Charge/`
车辆协议层 | 各车型接入与状态同步 | `CarTypes/`
基础能力层 | 路径规划、锁点、全局对象访问 | `SimpleCore`、`SimpleLib`

#### 宿主装载流程

1. 编译得到 `StandardScene.dll`
2. 构建事件将 DLL 复制到 `build/plugins`
3. 宿主启动后扫描插件目录
4. 通过特性反射识别 `MissionType` 与 `CarType`
5. 用户或 API 启动对应场景逻辑

### 03. 模块地图

目录 | 职责 | 建议起步文件
--- | --- | ---
`Scheduler/` | 心跳、安全信号、区域流控等轻量 Mission | `HeartBeatMission.cs`
`Chained/` | 搬运与环线任务主流程 | `TransportMission.cs`
`Charge/` | 充电站管理、策略控制、状态维护 | `StandardChargeMission.cs`
`InterLock/` | 区域互锁、交通控制 | `TrafficInterlockMission.cs`
`CarTypes/` | 车型与协议实现 | `VDA5050Car.cs`
`ExtendDevice/Door/` | 门禁联动 | `DoorMission.cs`
`WebApi.cs` | 外部系统接入入口 | `/car/*`、`/map/*`、`/mission_reflection/*`

### 04. 构建与运行

#### 本机依赖路径

    D:\MDCS\Dependencies\Commons\CommonUsage.dll
    D:\MDCS\Dependencies\Commons\MDCSToolBox.dll
    D:\MDCS\Dependencies\Commons\CycleGUI.dll
    ..\Simple\SimpleLite\bin\Debug\SimpleLite.dll
    ..\Simple\SimpleLite\bin\Debug\LessokajiWeaverUtilities.dll
    ..\Simple\SimpleCore\bin\Debug\netstandard2.0\SimpleCore.dll

#### 构建步骤

1. 先构建宿主依赖：`dotnet build Simple\SimpleLite\SimpleLite.csproj`（一并构建 SimpleCore）
2. 打开 `StandardScene.sln`
3. 编译 `Debug|x64` 或 `Release|x64`
4. 确认 `Directory.Build.targets` 已将 5 个插件 DLL 复制到 `build/plugins`
5. 将 `build/plugins` 部署到宿主 `plugins/`，运行 `SimpleLite.exe`

当前项目已是 SDK 风格工程（`net8.0-windows`），目录下 `.cs` 文件会被自动包含，无需手工加入 `.csproj`。注意：StandardScene 通过 `HintPath` 引用宿主产物，构建前必须先编译 Simple 解决方案，否则会报 `SimpleCore` 版本不匹配。

### 05. 快速开始案例

#### 案例 A：新增 HelloMission

这是推荐的新手第一练。它直接沿用 `Scheduler/HeartBeatMission.cs` 的结构，只保留最小生命周期：`Create()`、`Execute()`、`Stop()`。

    using System.Threading;
    using Newtonsoft.Json;
    using SimpleLite.RCS;
    using SimpleCore;

    namespace StandardScene.Scheduler
    {
        [MissionType(Name = "Hello Mission", editor = typeof(HelloMission))]
        [I18N.DocumentTranslation(Name = "Hello Mission", locale = "en")]
        public class HelloMission : Mission
        {
            [JsonIgnore] private bool _started;
            [JsonIgnore] private Thread _thread;

            public static Mission Create()
            {
                return new HelloMission();
            }

            public override void Execute()
            {
                if (_started) return;
                _started = true;
                status.status = "已启动";

                _thread = new Thread(() =>
                {
                    int count = 0;
                    while (_started)
                    {
                        Thread.Sleep(1000);
                        count++;
                        status.status = $"tick:{count}";
                    }
                });
                _thread.Start();
            }

            public void Stop()
            {
                _started = false;
                status.status = "已停止";
            }
        }
    }

1. 新建 `Scheduler/HelloMission.cs`（SDK 工程自动包含）
2. 补上 `[MissionType]` 特性与静态 `Create()`
3. 编译后部署到宿主 `plugins/`，运行 `SimpleLite.exe`
4. 启动后观察 `status.status` 是否按秒递增

#### 案例 B：区域流控实验

该案例对应 `Scheduler/RegionalTrafficControlMission.cs`。给同一区域的站点加字段 `Region1=1`，即可限制该区域最多同时只有 1 台车。

    Region1 = 1

1. 给目标区域内多个站点都加上相同的 `Region1` 字段
2. 启动“区域流量监控” Mission
3. 让两台车依次申请进入该区域
4. 观察第二台车是否被阻止，日志和状态里会记录拦截次数

### 06. 配置文件

文件 | 用途
--- | ---
`Config/traffic.json` | 交通互锁与区域控制
`Config/ChargeStations.json` | 充电桩定义
`Config/ChargeStrategyConfig.json` | 充电策略
`Config/AlarmConfigs.json` | 充电报警配置
`DoorConfig.json` | 门禁设备配置
`tasklist.json` | 环线任务列表
`simple.json` | 宿主基础配置

除了 JSON 文件，很多逻辑还大量依赖站点、车辆和轨道的 `fields` 与 `tags`。例如区域流控依赖以 `Region` 开头的字段，许多调度逻辑依赖 `group`、`giveWay`、`standby` 等字段。

### 07. API 入口

`WebApi.cs` 是外部系统最重要的进入点，仓库中已可看到这些典型路由：

`/car/createTask` 创建任务
`/car/getAllCars` 查询车辆列表
`/car/goSite` 指派车辆去站点
`/map/getMap` 获取地图
`/task/getTask` 查询任务
`/mission_reflection/*` 反射调用 Mission 方法

### 08. 开发工作流

1. 先定位功能属于哪个目录
2. 找最接近的现有类作为模板
3. 明确它依赖 JSON 配置还是 `fields` / `tags`
4. 补齐日志、状态和停止逻辑
5. 确认新文件已加入工程
6. 编译后在宿主中验证是否被识别

新增 Mission：先看 HeartBeatMission 新增区域逻辑：先看 RegionalTrafficControlMission 新增接口：先看 WebApi.cs 新增配置：先写默认值与生效时机

### 09. 常见排错

现象 | 优先检查
--- | ---
新增 Mission 在宿主里看不到 | 特性是否正确、`Create()` 是否存在、文件是否已加入 `.csproj`、插件是否复制到 `build/plugins`
区域流控不生效 | 站点字段名是否以 `Region` 开头、字段值是否为整数、Mission 是否已启动
车不动或任务不走 | 车辆在线状态、路径是否可达、是否被锁点 / 互锁 / 门控拦截
API 调不通 | 路由是否正确、宿主端口是否打开、请求是否真的命中 `WebApi.cs`

编码说明：本页使用 `UTF-8` 和兼容中文 / English / emoji 的字体栈，本地双击打开不依赖任何外部资源，因此不会因为部署或 CDN 缺失导致乱码。