Merge commit '0952958af7685646cdbf2a4907c6e2ae59d4d352'

AGENTS.md

@@ -8,7 +8,7 @@
 
 - 使用 `C# + .NET 8`
 - 提供跨平台独立服务端
-- 兼容现有 `50001/TCP+JSON` 上层接入语义
+- 以新的 ASP.NET Core HTTP API 作为唯一上层接口
 - 重写轨迹生成、触发时序、FANUC 控制链路和状态监控
 - Windows / Linux 都能运行完整服务端
 - 只支持当前现场这套组合
@@ -18,6 +18,7 @@
 - GUI 桌面程序
 - 多机器人同时控制
 - 面向多控制柜的通用平台化框架
+- 恢复旧 `50001/TCP+JSON` 网关
 
 ## 2. 代码与资料边界
 
@@ -37,7 +38,12 @@
 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/
@@ -64,8 +70,10 @@ flyshot-replacement/
 - `Flyshot.Core.Triggering`
   - `TrajectoryDO` 等价时间轴
   - `shot_flags / offset_values / addr` 解析
-- `Flyshot.LegacyGateway`
-  - `50001/TCP+JSON` 兼容接入
+- `Flyshot.ControllerClientCompat`
+  - HTTP 控制器后端兼容服务
+  - 旧 `ControllerClient` 语义适配
+  - 不启动 `50001/TCP+JSON` 监听
 - `Flyshot.Runtime.Fanuc`
   - `10010 / 10012 / 60015`
 - `Flyshot.Web.Status`
@@ -84,6 +92,7 @@ flyshot-replacement/
 
 ### 4.2 实现约束
 
+- 旧 `ControllerClient` 资料只作为接口语义参考；运行时入口以新 HTTP API 为准，不恢复旧 `50001/TCP+JSON` 网关。
 - 旧协议兼容以“语义兼容”为主，不追求二进制逐字节一致。
 - 轨迹规划必须与底层 Socket / HTTP / Web UI 解耦。
 - 领域层不允许引用 ASP.NET Core、Socket、文件系统 API。
@@ -103,6 +112,15 @@ flyshot-replacement/
 - 所有静态变量都必须提供 XML 注释。
 - 关键代码块必须补充单行注释，说明该段逻辑为什么存在、在做什么，不允许只写空泛注释。
 
+### 4.5 机器人模型字段约定
+
+- 当任务涉及六轴 `velocity / acceleration / jerk` 来源时，默认先查看机器人模型文件中的 `joint.limit`，不要先从抓包、导出轨迹或聊天记录反推。
+- 当前仓库约定：`velocity_eff = velocity_base`，`acceleration_eff = acceleration_base * acc_limit`，`jerk_eff = jerk_base * jerk_limit`。
+- `acc_limit / jerk_limit` 来自运行时 `RobotConfig.json`，它们是全局倍率，不是每轴单独配置。
+- 模型里的 `limit.effort` 目前只能当静态模型字段记录，不能直接当现场真实电流。
+- 如果用户问“电流是不是从这个模型文件提取的”，默认先明确区分：模型里的 `effort` 不等于 J519 反馈里的电机电流。
+- 相关固定表格文档见 `docs/robot-joint-limit-table-20260505.md`。
+
 ## 5. 构建与验证命令
 
 在当前环境中，推荐使用下面两条命令：
@@ -132,9 +150,24 @@ flyshot-replacement/
 - `../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 需要随着阶段推进同步更新。
@@ -148,3 +181,13 @@ flyshot-replacement/
 - `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`，不要把速度缩放只建模成单个机器人命令。J519 实发周期仍为 `t_send = k * 0.008`，原轨迹采样时间为 `t_traj = t_send * 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`，不再只是兼容层内存赋值。