# agents-gcs

**Repository Path**: chuck_chee/agents-gcs

## Basic Information

- **Project Name**: agents-gcs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-25
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QGroundControl 地面站知识库

本目录保存 QGroundControl 定制地面站的项目规则和可复用功能文档，供开发人员与 AI 编码代理快速查找项目入口、稳定约束、迁移方法和验证要求。

- 更新日期：`2026-07-22`
- 文档语言：中文
- AGENTS 命名：`AGENTS.md` 或 `AGENTS_<项目名>.md`
- Feature 命名：`Feature_<功能名>.md`

## 目录

- [如何使用](#如何使用)
- [AGENTS 项目文档](#agents-项目文档)
- [Feature 功能文档](#feature-功能文档)
- [Qt Creator 发布配置](#qt-creator-发布配置)
- [按主题查找](#按主题查找)
- [文档维护](#文档维护)

## 如何使用

1. 第一次接触 QGC 定制工程时，先阅读 [AGENTS.md](project/AGENTS.md)。
2. 开始具体项目任务前，再阅读对应的 `AGENTS_<项目名>.md`。
3. 涉及可迁移功能时，继续阅读对应的 `Feature_<功能名>.md`。
4. 文档中的路径是快速入口，实际修改前仍应以目标仓库当前代码为准。

文档分工：

- `AGENTS.md`：大多数 QGroundControl 定制工程都适用的通用规则。
- `AGENTS_<项目名>.md`：某个项目特有的结构、产品约束、代码入口和验证要求。
- `Feature_<功能名>.md`：可跨工程参考或迁移的独立功能实现说明。

## AGENTS 项目文档

| 文档                                                   | 项目             | 大致内容                                         |
| ---------------------------------------------------- | -------------- | -------------------------------------------- |
| [AGENTS.md](project/AGENTS.md)                               | 通用 QGC         | QGroundControl 通用结构、代码规范、任务定位、构建测试和定制层开发原则。  |
| [AGENTS_ADBGCS.md](project/AGENTS_ADBGCS.md)                 | ADBGCS         | `xsrc` 接线、多路视频、TCP 脚本通信、吊舱控制及项目验证入口。         |
| [AGENTS_BASICPILOTGCS.md](project/AGENTS_BASICPILOTGCS.md)   | basicPilotGCS  | 自定义飞行界面、地图配置、本地媒体和云卓吊舱 UDP 控制。               |
| [AGENTS_GUARDSKY.md](project/AGENTS_GUARDSKY.md)             | guardsky       | 多机与雷达、雷达高度曲线、导引头、独立 UavSDK、主题系统、链路重连、Android G20 SDK、任务与参数加载。 |
| [AGENTS_QGROUNDCONTROL.md](project/AGENTS_QGROUNDCONTROL.md) | qgroundcontrol | 原位定制 QGC 的 UI、Android 打包、视频、地图、语言、语音和导出规则。   |
| [AGENTS_SGGCS.md](project/AGENTS_SGGCS.md)                   | SGGCS          | `STGCControl` 产品层、视频与云台叠加、地图、设置页面和构建版本信息。    |
| [AGENTS_USV-PILOT.md](project/AGENTS_USV-PILOT.md)           | usv-pilot      | 无人船业务、地图、NTRIP、Android 授权、OTA、语音和版本发布。       |
| [AGENTS_XH300GCS.md](project/AGENTS_XH300GCS.md)             | xh300gcs       | XUI、拍照录像、本地媒体、飞行前检查、传感器校准和 OTA。              |
| [AGENTS_XHNEXUS.md](project/AGENTS_XHNEXUS.md)       | xhnexusGCS     | Figma 驱动的 FlyView 顶栏、XUI 飞行界面、仪表、多机列表、PiP 外框、天地图、雷达 UI 与目标列表。 |

`backup-english/` 仅保存历史英文备份，不属于当前中文文档维护入口。

## Feature 功能文档

### Android 与发布

| 文档 | 大致内容 |
|---|---|
| [Feature_AndroidLicense.md](feature/Feature_AndroidLicense.md) | Android 设备绑定、离线授权和工厂发码流程。 |
| [Feature_G20RCSDK.md](feature/Feature_G20RCSDK.md) | 云卓/Skydroid G20 Android SDK、遥控通道和信号质量接入。 |
| [Feature_OTA.md](feature/Feature_OTA.md) | Android APK 与 Windows NSIS 安装包的远程升级流程。 |
| [Feature_WindowsInstaller.md](feature/Feature_WindowsInstaller.md) | QGC Windows NSIS 安装包构建、命名、资源和常见问题。 |
| [Feature_GitBuildVersion.md](feature/Feature_GitBuildVersion.md) | 将 Git 分支、提交、标签和构建时间写入应用版本信息。 |

### 视频、拍照与媒体

| 文档                                                                       | 大致内容                             |
| ------------------------------------------------------------------------ | -------------------------------- |
| [Feature_FFmpegVideoBackend.md](feature/Feature_FFmpegVideoBackend.md)           | FFmpeg 实时视频后端、线程模型、生命周期和平台迁移。    |
| [Feature_MultiVideo.md](feature/Feature_MultiVideo.md)                           | 最多五路 RTSP 视频、动态 Sink 绑定、启停和全屏显示。 |
| [Feature_PhotoVideoGimbalCapture.md](feature/Feature_PhotoVideoGimbalCapture.md) | 视频截图、录像、MAVLink 相机及云台拍照录像的统一控制。  |
| [Feature_LocalMediaBrowser.md](feature/Feature_LocalMediaBrowser.md)             | 应用本地照片和录像的浏览、排序、删除、预览与回放。        |

### 通信、定位与地图

| 文档 | 大致内容 |
|---|---|
| [Feature_LinkAutoConnect.md](feature/Feature_LinkAutoConnect.md) | 平台预设链路、启动自动连接、链路记忆和断线重连。 |
| [Feature_NTRIP.md](feature/Feature_NTRIP.md) | 内置 NTRIP Client、GGA、RTCM3 接收及 MAVLink 转发。 |
| [Feature_Mapbox.md](feature/Feature_Mapbox.md) | Mapbox token、地图源、地图类型切换和设置持久化。 |
| [Feature_TCPScriptPodControl.md](feature/Feature_TCPScriptPodControl.md) | TCP JSON 脚本控制与二进制吊舱控制的传输和协议分层。 |
| [Feature_RadarIntegration.md](feature/Feature_RadarIntegration.md) | 雷达 TCP 接入、二进制协议解析、设备控制、目标缓存、地图/列表联动和转发预留接口。 |
| [Feature_RadarMapOverlayUI.md](feature/Feature_RadarMapOverlayUI.md) | 剥离数据后的地图雷达态势 UI：独立距离环带、角度刻度、扫描扇区和中心图标绘制方案。 |
| [Feature_RadarAltitudeChart.md](feature/Feature_RadarAltitudeChart.md) | 平台 MQTT 雷达高度即时转发诊断、实时曲线、统计频率、断流识别和 Popup 置顶交互。 |
| [Feature_UavSDK.md](feature/Feature_UavSDK.md) | UavSDK 0.2.0 的独立 C ABI 架构、模拟飞控、自动/人工测试、QML 联调、编程指南和正式交付包。 |
| [Feature_YunZhuoGimbalUDP.md](feature/Feature_YunZhuoGimbalUDP.md) | 云卓吊舱/云台相机 UDP 指令、状态解析和 UI 接入。 |

### 飞行、任务与参数

| 文档 | 大致内容 |
|---|---|
| [Feature_MockLink.md](feature/Feature_MockLink.md) | APM Multirotor MockLink 航线、模式、返航和多机模拟。 |
| [Feature_TakeoffMissionDownload.md](feature/Feature_TakeoffMissionDownload.md) | 修复下载任务时 Takeoff 落到 `(0,0)` 和异常连线的问题。 |
| [Feature_ParameterLoading.md](feature/Feature_ParameterLoading.md) | 初始少量参数加载、按需获取全部参数和缺失参数容错。 |
| [Feature_PreFlightChecklist.md](feature/Feature_PreFlightChecklist.md) | 起飞前人工检查、遥测展示、状态保存和强制解锁门控。 |
| [Feature_SensorCalibration.md](feature/Feature_SensorCalibration.md) | 将 APM/PX4 传感器校准迁移到自定义 XUI 设置页面。 |

## Qt Creator 发布配置

Windows OTA、Git 版本信息和 NSIS 安装包迁移后，Qt Creator 侧建议统一做以下配置：

- 版本文件：`xsrc/XModule/XBuildInfo.generated.h` 由 `tools/update_build_info.ps1` 生成；qmake 工程应在 `xsrc/xui.pri` 的 `WindowsBuild` 中调用该脚本。发布前先打 `vX.XX.XX` 形式 Git tag，例如 `v1.02.03`，再执行版本生成步骤，确保版本页、`QCoreApplication::applicationVersion()` 和 OTA 请求使用同一版本。
- Qt Creator 手动版本生成：在 `Projects -> Build Settings -> Build Steps` 增加 `Custom Process Step`，并拖到 `qmake` 前执行。推荐拆分填写：
- `Command` 填 `powershell.exe`，
- `Arguments` 填 `-NoProfile -ExecutionPolicy Bypass -File "%{sourceDir}\tools\update_build_info.ps1" ，
- `Working directory` 填 `%{sourceDir}`。
- Qt Creator 单行写法：如果当前 Qt Creator 版本使用单行命令输入，也可直接填 `powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%{sourceDir}\tools\update_build_info.ps1" %{sourceDir}`，同样放在 `qmake` 前执行。
- Debug 构建：Qt Creator 的 Debug qmake arguments 建议使用 `CONFIG+=debug CONFIG+=QGC_DISABLE_INSTALLER_SETUP`，避免每次链接后触发 NSIS 打包。
- Release 出包：Release qmake arguments 使用 `CONFIG+=release`，不要加入 `QGC_DISABLE_INSTALLER_SETUP`；`QGCPostLinkInstaller.pri` 会在链接后调用 `tools/package_windows_installer.ps1`。
- NSIS 路径：优先安装到默认路径 `C:\Program Files (x86)\NSIS\makensis.exe`；非默认路径时，在 Qt Creator `Projects -> Build Settings -> Build Environment` 增加 `QGC_MAKENSIS=<makensis.exe 路径>`。
- 安装器资源：在项目 `.pro` 中确认 `QGC_INSTALLER_SCRIPT`、`QGC_INSTALLER_ICON`、`QGC_INSTALLER_HEADER_BITMAP`、`QGC_INSTALLER_DRIVER_MSI` 指向当前工程资源；APP 名和安装包名使用 `QGC_APP_NAME`/`TARGET`。
- 详细实现与迁移检查：见 [Feature_GitBuildVersion.md](feature/Feature_GitBuildVersion.md)、[Feature_WindowsInstaller.md](feature/Feature_WindowsInstaller.md)、[Feature_OTA.md](feature/Feature_OTA.md)。
## 按主题查找

| 需要处理的任务 | 建议先看 |
|---|---|
| QGC 通用开发、代码风格、资源接线 | [AGENTS.md](project/AGENTS.md) |
| 某个产品工程的入口和约束 | 对应的 `AGENTS_<项目名>.md` |
| Android 授权或遥控器 SDK | [Feature_AndroidLicense.md](feature/Feature_AndroidLicense.md)、[Feature_G20RCSDK.md](feature/Feature_G20RCSDK.md) |
| Windows/Android 在线升级与安装包 | [Feature_OTA.md](feature/Feature_OTA.md)、[Feature_WindowsInstaller.md](feature/Feature_WindowsInstaller.md) |
| 实时图传或多路视频 | [Feature_FFmpegVideoBackend.md](feature/Feature_FFmpegVideoBackend.md)、[Feature_MultiVideo.md](feature/Feature_MultiVideo.md) |
| 拍照录像和本地媒体 | [Feature_PhotoVideoGimbalCapture.md](feature/Feature_PhotoVideoGimbalCapture.md)、[Feature_LocalMediaBrowser.md](feature/Feature_LocalMediaBrowser.md) |
| NTRIP、链路重连、TCP 控制 | [Feature_NTRIP.md](feature/Feature_NTRIP.md)、[Feature_LinkAutoConnect.md](feature/Feature_LinkAutoConnect.md)、[Feature_TCPScriptPodControl.md](feature/Feature_TCPScriptPodControl.md) |
| 独立无人机 SDK、C ABI 或 SDK 集成测试 | [Feature_UavSDK.md](feature/Feature_UavSDK.md) |
| 雷达协议接入、地图雷达 UI 或转发高度诊断 | [Feature_RadarIntegration.md](feature/Feature_RadarIntegration.md)、[Feature_RadarMapOverlayUI.md](feature/Feature_RadarMapOverlayUI.md)、[Feature_RadarAltitudeChart.md](feature/Feature_RadarAltitudeChart.md) |
| 地图配置 | [Feature_Mapbox.md](feature/Feature_Mapbox.md) |
| 云台或吊舱 | [Feature_YunZhuoGimbalUDP.md](feature/Feature_YunZhuoGimbalUDP.md)、[Feature_PhotoVideoGimbalCapture.md](feature/Feature_PhotoVideoGimbalCapture.md) |
| 航线模拟或任务下载 | [Feature_MockLink.md](feature/Feature_MockLink.md)、[Feature_TakeoffMissionDownload.md](feature/Feature_TakeoffMissionDownload.md) |
| 参数加载、飞检、传感器校准 | [Feature_ParameterLoading.md](feature/Feature_ParameterLoading.md)、[Feature_PreFlightChecklist.md](feature/Feature_PreFlightChecklist.md)、[Feature_SensorCalibration.md](feature/Feature_SensorCalibration.md) |

## 文档维护

- 所有当前维护的 AGENTS 文档使用中文，文件名不添加“中文版”。
- 通用规则写入 `AGENTS.md`，项目私有规则写入对应的 `AGENTS_<项目名>.md`。
- 可跨工程复用的完整功能优先沉淀为 `Feature_<功能名>.md`。
- 每次同步 `project/AGENTS_<项目名>.md` 基线后，同步更新本 README 的“AGENTS 项目文档”总表、链接和简要说明。
- 新增、删除或重命名 AGENTS/Feature 文档时，同步更新本 README。
- README 只保留目录和简要介绍，详细实现、入口和验证步骤放在对应文档中。
- 建议每周检查一次目录，并更新顶部日期。