FlyShotHost/AGENTS.md

Flyshot Replacement 仓库规范

1. 仓库目标

本仓库用于重写并替代现有 RVBUST/FANUC 飞拍服务端链路。

第一版目标固定为：

• 使用 C# + .NET 8
• 提供跨平台独立服务端
• 以新的 ASP.NET Core HTTP API 作为唯一上层接口
• 重写轨迹生成、触发时序、FANUC 控制链路和状态监控
• Windows / Linux 都能运行完整服务端
• 只支持当前现场这套组合

明确不做：

• GUI 桌面程序
• 多机器人同时控制
• 面向多控制柜的通用平台化框架
• 恢复旧 50001/TCP+JSON 网关

2. 代码与资料边界

本仓库是新的独立实现仓库，不复用旧的 RVBUST 二进制作为运行时依赖。

允许依赖的内容：

• 旧仓库中的逆向分析文档
• 旧仓库中的协议样本、轨迹样本和配置样本
• 旧仓库中的 ControllerClient.h 公开接口

不允许把旧服务端实现直接包装成“新系统”。

3. 当前目录结构

flyshot-replacement/
  ├─ src/
  │  ├─ Flyshot.Server.Host/
  │  ├─ Flyshot.ControllerClientCompat/
  │  ├─ Flyshot.Core.Config/
  │  ├─ Flyshot.Core.Domain/
  │  ├─ Flyshot.Core.Planning/
  │  ├─ Flyshot.Core.Triggering/
  │  ├─ Flyshot.Runtime.Fanuc/
  │  └─ Flyshot.Runtime.Common/
  ├─ tests/
  │  ├─ Flyshot.Server.IntegrationTests/
  │  └─ Flyshot.Core.Tests/
  ├─ FlyshotReplacement.sln
  ├─ Directory.Build.props
  ├─ README.md
  └─ AGENTS.md

后续新增模块时，优先保持以下边界：

• Flyshot.Core.Domain
  • 纯领域对象
  • 不依赖网络、文件系统、HTTP、UI、操作系统
• Flyshot.Core.Config
  • 配置兼容
  • .robot 解析
  • 路径兼容
• Flyshot.Core.Planning
  • icsp
  • self-adapt-icsp
  • doubles
• Flyshot.Core.Triggering
  • TrajectoryDO 等价时间轴
  • shot_flags / offset_values / addr 解析
• Flyshot.ControllerClientCompat
  • HTTP 控制器后端兼容服务
  • 旧 ControllerClient 语义适配
  • 不启动 50001/TCP+JSON 监听
• Flyshot.Runtime.Fanuc
  • 10010 / 10012 / 60015
• Flyshot.Web.Status
  • 状态查看
  • 诊断页
  • 不直接处理底层协议细节

4. 开发规范

4.1 通用要求

• 正式文档默认使用中文。
• 不要把临时验证脚本直接塞进正式运行时代码。
• 兼容性优先级高于“重新发明接口”。
• 第一版默认围绕当前现场组合实现，不提前做泛化设计。

4.2 实现约束

• 旧 ControllerClient 资料只作为接口语义参考；运行时入口以新 HTTP API 为准，不恢复旧 50001/TCP+JSON 网关。
• 旧协议兼容以“语义兼容”为主，不追求二进制逐字节一致。
• 轨迹规划必须与底层 Socket / HTTP / Web UI 解耦。
• 领域层不允许引用 ASP.NET Core、Socket、文件系统 API。
• 网页只做状态监控，不把复杂控制流程放进前端。
• 多机型切换通过不同 .robot 文件加载，不在第一版做插件化机型框架。

4.3 测试要求

• 默认采用 TDD。
• 至少先写失败测试，再写最小实现。
• 每完成一个阶段，要补最小可运行验证，而不是只看代码编译是否“像是对的”。

4.4 注释要求

• 所有生成代码都必须带中文注释，不可缺漏。
• 所有类定义都必须在类头提供 XML 注释。
• 所有静态变量都必须提供 XML 注释。
• 关键代码块必须补充单行注释，说明该段逻辑为什么存在、在做什么，不允许只写空泛注释。

5. 构建与验证命令

在当前环境中，推荐使用下面两条命令：

/bin/bash -lc 'DOTNET_CLI_HOME=/tmp NUGET_PACKAGES=/tmp/nuget-packages dotnet test tests/Flyshot.Server.IntegrationTests/Flyshot.Server.IntegrationTests.csproj -v minimal'
/bin/bash -lc 'DOTNET_CLI_HOME=/tmp NUGET_PACKAGES=/tmp/nuget-packages dotnet build FlyshotReplacement.sln --no-restore -v minimal'

说明：

• 第一条命令当前已经验证通过，可用于检查最小宿主和 /healthz。
• 第二条命令当前已经验证通过，可用于检查解决方案骨架是否完整。

后续新增模块时，继续补充：

• Flyshot.Core.Tests
• 协议回放测试
• golden sample 对拍测试
• 端到端集成测试

6. 修改前优先查看的资料

本仓库上层是独立实现，但上下文仍然依赖父目录中的逆向资料。开始重要改动前，优先阅读：

• ../analysis/ControllerServer_analysis.md
• ../analysis/ICSP_algorithm_reverse_analysis.md
• ../analysis/CommonMsg_protocol_analysis.md
• ../analysis/J519_stream_motion_analysis.md
• ../analysis/UTTC_20260428_packet_validation.md
• ../analysis/FANUC_realtime_comm_analysis.md
• ../FlyingShot/FlyingShot/Include/ControllerClient/ControllerClient.h

6.1 父目录资料引用约定

• 日常开发、测试和 Codex 会话默认从 flyshot-replacement/ 根目录启动。
• 当前仓库内的 @ 引用默认只覆盖本仓库文件，不要假设它能索引父目录资料。
• 引用父目录资料时，统一直接写明确路径，优先使用相对路径，例如：
  • ../analysis/ICSP_algorithm_reverse_analysis.md
  • ../analysis/ControllerServer_analysis.md
  • ../FlyingShot/FlyingShot/Include/ControllerClient/ControllerClient.h
• 当路径较长或跨工具复制时，可以使用绝对路径，但在文档和注释中优先保留相对路径写法，便于仓库整体搬迁。
• 父目录中的 analysis/、FlyingShot/、RobotController/、RPS/ 默认视为参考资料区，不在这些目录中继续落地新实现。
• 新实现、测试、兼容层代码、设计文档和运行说明，都应优先写入 flyshot-replacement/ 内部。
• 如果父目录资料中的某段结论会长期影响本仓库实现，应在本仓库 docs/ 中补充归纳说明，并标明来源路径，而不是要求后续开发反复回看聊天记录。
• 如果需要引用父目录样本文件做测试输入，优先通过只读方式加载；只有在测试需要固化样本且样本已明确收敛时，才复制到本仓库测试数据目录。

7. 任务推进方式

• README.md 中的 Todo 需要随着阶段推进同步更新。
• 如果实现范围发生收敛或扩展，先更新设计或计划，再继续改代码。
• 如果发现计划漏了关键对象或模块，直接补到文档里，不要把缺口留到后面。

8. 当前已验证状态

• 独立仓库已初始化。
• dotnet 8 解决方案骨架已建立。
• Flyshot.Server.Host 已提供最小 /healthz。
• 最小集成测试已通过。
• 解决方案构建已通过。
• 新 HTTP API / HTTP-only ControllerClientCompat 已覆盖旧 HTTP 控制器后端的主要兼容语义。
• Flyshot.Core.Planning 已落地 icsp 与 self-adapt-icsp，并已完成旧系统导出轨迹对齐。
• Flyshot.Core.Triggering 已能从 shot_flags / offset_values / addr 生成触发时间轴。
• Flyshot.Runtime.Fanuc 已固化 10010 / 10012 / 60015 基础协议帧编解码，10010 状态帧以 j519 协议.pcap 和 Rvbust/uttc-20260428/20260428.pcap 真机抓包确认为 90B。
• Flyshot.Runtime.Fanuc 已将 TCP 10010 的 pose[6]、joint[6]、external_axes[3] 和 raw_tail_words[4] 映射为明确状态帧字段，并在状态快照中保留尾部状态字诊断信息。
• Rvbust/uttc-20260428 抓包确认 J519 命令目标为关节角 deg，而导出 JointDetialTraj.txt 为 rad；执行链路必须做单位转换。
• Rvbust/uttc-20260428 抓包确认 speed_ratio=0.7 体现为 UDP 下发时间轴约 1.427730x 拉伸；本抓包机器人侧 TCP 10012 未出现 0x2207 SetSpeedRatio，不要把速度缩放只建模成单个机器人命令。实发按 t_traj = k * 0.008 * speed_ratio 重采样，UTTC_MS11 的 464 行导出轨迹对应 1322 个主运行 J519 包。
• Rvbust/uttc-20260428 抓包确认 UTTC_MS11 的 17 个 shot_flags=true 对应 17 个 UDP IO 脉冲，io_keep_cycles=2 对应约两周期清零。
• Flyshot.Runtime.Fanuc 已具备基础 Socket 客户端、速度倍率/TCP/IO 参数命令和 J519 周期发送链路；稠密轨迹下发已按 speed_ratio 推进轨迹时间，J519 闭环状态判断与现场联调仍需补齐。
• ExecuteTrajectory / ExecuteFlyShotTraj 已接入 Planning + Triggering + Runtime，不再只是兼容层内存赋值。