Imported from keaipeng123/gb-client (AGENTS.md). Install upstream with npx skills add keaipeng123/gb-client. Copyright stays with the author.

gb-client Agent Guide

本项目内的沟通、说明和提交信息默认使用中文。

先看这里

• 详细构建环境、依赖版本和页面结构说明见 CLAUDE.md。
• 本地环境补充说明见 build.md。
• VS Code 任务入口见 .vscode/tasks.json。

项目概览

• 这是一个基于 Qt Widgets 的桌面客户端，使用 CMake + Ninja 构建。
• 源文件位于 src，头文件位于 include，Qt Designer 的 .ui 文件位于 ui。
• src/main.cpp 负责初始化 Qt、FFmpeg、SDL 和 JsonCpp，然后启动 src/mainwindow.cpp。
• src/mainwindow.cpp 是主要协调层：负责页面切换、发送协议命令、接收 TCP 数据并按 JSON 内容分发给目录页。
• src/entrypage.cpp 只负责采集服务器 IP 和端口，不承载业务逻辑。
• src/catalogpage.cpp 负责目录树展示、点击行为和播放区状态展示。
• src/tcpclient.cpp 只负责 QTcpSocket 封装、收发数据和断线重连。

开发约定

• 优先把页面逻辑留在页面类里，把连接、协议发送和跨页面协调留在 src/mainwindow.cpp。
• 修改界面时优先更新对应的 .ui 文件，不要手改 build 目录下生成的 ui_.h 或 moc_ 文件。
• 不要编辑 build 下的产物，包括 HelloQt_autogen、compile_commands.json 和可执行文件。
• 如果调整协议或命令字，检查 include/sipdef.h、include/streamdef.h 与 src/mainwindow.cpp 的发送/分发逻辑是否同步。
• src/catalogpage.cpp 里使用 updatingTree_ 防止树更新时触发递归信号；改动树刷新逻辑时保留这一约束。

构建与验证

• 配置：cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=/Users/sxr/Qt/6.11.0/macos -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
• 构建：cmake --build build
• 运行：./build/HelloQt
• 仓库当前有 streamdispatcher_tests 和 h264recorder_tests 两个测试目标；改动后至少执行一次构建并运行一次 ctest --test-dir build --output-on-failure。
• 需要验证 TCP 连接或断线重连时，可运行：python3 test_server.py

依赖与环境

• Qt 6.11.0 路径固定为 /Users/sxr/Qt/6.11.0/macos。
• FFmpeg、SDL2、JsonCpp 通过 CMake 和 pkg-config 接入；如果构建失败，先确认本机依赖是否完整。