feat(host)!: Add thread setup support to advanced options

[qzhhhi]

• Introduce thread_setup in agent::AdvancedOptions so callers can configure the transport event thread before it starts handling USB I/O.
• Add bind_advanced_options() to bind stateful nothrow callables without introducing std::function into the binary interface. The transport now waits until thread_setup returns before continuing construction, so any bound temporary state remains alive during the callback.
• Also document the lifetime and slicing constraints of bound advanced options, and clarify that thread_setup is only for per-thread OS-level setup such as priority or CPU affinity.

BREAKING CHANGE: agent::AdvancedOptions is now non-copyable and non-movable, and no longer preserves the previous aggregate-style usage. The USB transport connection options alias now reuses agent::AdvancedOptions.

拉取请求摘要

概述

本PR为 agent::AdvancedOptions 配置添加了线程设置支持，允许调用者在USB I/O操作开始前配置传输事件线程。这是一个破坏性变更，涉及多个组件的API调整。

核心变更

1. agent::AdvancedOptions 结构升级（host/include/librmcs/agent/common.hpp）

• 将 AdvancedOptions 从简单的struct转换为class，现在不支持拷贝和移动
• 删除了拷贝/移动构造函数和赋值操作符
• 添加了新的 thread_setup 回调函数指针：void (*)(const AdvancedOptions&) noexcept
• 新增链式setter方法：
  • set_dangerously_skip_version_checks(bool)
  • set_thread_setup(void (*)(const AdvancedOptions&) noexcept)

2. 绑定高级选项函数（host/include/librmcs/agent/common.hpp）

• 引入模板函数 bind_advanced_options(FunctorT&& thread_setup_impl)
• 支持绑定有状态的可调用对象（闭包、仿函数等）到函数指针
• 内部通过创建派生类 OptionsImpl 来保存传入的实现，使用 std::invoke 适配
• 避免了在二进制接口中引入 std::function，保持API的轻量性
• 文档说明了绑定对象生命周期的约束和使用方式

3. 传输层选项统一（host/src/transport/transport.hpp）

• transport::usb::ConnectionOptions 从独立的struct变更为 agent::AdvancedOptions 的类型别名
• transport.hpp 包含了 librmcs/agent/common.hpp 头文件

4. Handler构造函数更新（host/src/protocol/handler.cpp）

• 现在将完整的 options 对象传递给 transport::usb::create_transport()，而非仅映射 dangerously_skip_version_checks 字段

5. USB事件线程启动同步（host/src/transport/usb/usb.cpp）

• 事件处理线程启动逻辑新增了对 thread_setup 回调的条件化处理
• 当提供 thread_setup 时，在新线程内先执行该回调，使用 std::atomic<bool> 和等待/通知机制同步
• 确保 thread_setup 完成后主线程才继续构造，防止绑定回调所依赖的临时状态失效

使用指导

• thread_setup 回调仅用于每线程操作系统级别的配置（如线程优先级、CPU亲和度设置）
• 调用者需注意 bind_advanced_options() 返回的对象生命周期约束，确保绑定的可调用对象在回调执行期间保持有效
• 文档警告不要在 thread_setup 中访问正在构造的agent对象或传输/协议API

破坏性变更

由于 AdvancedOptions 不再支持拷贝和移动，现有代码使用聚合初始化模式（如 AdvancedOptions{...} 或赋值）需要改为使用setter方法或 bind_advanced_options() 函数。

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a85cae53-75d6-4816-aeb8-46d0162fc3b2

📥 Commits

Reviewing files that changed from the base of the PR and between aaaface and 5f246ae.

📒 Files selected for processing (4)

• host/include/librmcs/agent/common.hpp
• host/src/protocol/handler.cpp
• host/src/transport/transport.hpp
• host/src/transport/usb/usb.cpp

---

Walkthrough

将 AdvancedOptions 从简单 struct 升级为带生命周期约束的 class，新增 thread_setup 回调函数指针及 bind_advanced_options 模板函数；将 transport::usb::ConnectionOptions 改为 agent::AdvancedOptions 的类型别名，并在 Usb 构造函数中通过原子标志同步等待 thread_setup 回调完成。

Changes

AdvancedOptions 线程回调扩展

Layer / File(s)	Summary
AdvancedOptions 类定义与 bind_advanced_options 模板 host/include/librmcs/agent/common.hpp	将 AdvancedOptions 从仅含版本跳过开关的 struct 重构为删除拷贝/移动语义的 class，新增 thread_setup 函数指针与链式 setter；并新增 bind_advanced_options 模板，通过内部派生类 OptionsImpl 保存 callable 并通过 std::invoke 适配为函数指针，同时引入所需标准库头文件。
ConnectionOptions 类型别名替换与选项透传 host/src/transport/transport.hpp, host/src/protocol/handler.cpp	transport.hpp 引入 common.hpp 并将 ConnectionOptions 替换为 agent::AdvancedOptions 的类型别名；handler.cpp 中 create_transport 调用改为直接透传完整 options 对象，替换原先仅映射单字段的显式构造方式。
Usb 构造函数中 thread_setup 同步执行 host/src/transport/usb/usb.cpp	事件线程启动逻辑改为条件化：当 thread_setup 存在时，在新线程内先执行回调，通过 std::atomic<bool> + wait/notify_one 同步，确保主线程在回调完成后再继续；无回调时保留原有直接启动逻辑。

Sequence Diagram(s)

sequenceDiagram
  participant 调用方
  participant AdvancedOptions
  participant Usb构造函数
  participant event_thread_

  调用方->>AdvancedOptions: bind_advanced_options(functor) 返回 OptionsImpl
  调用方->>Usb构造函数: create_transport(..., options)
  Usb构造函数->>event_thread_: 创建线程
  event_thread_->>AdvancedOptions: options.thread_setup(options)（调用 OptionsImpl::invoke）
  event_thread_->>Usb构造函数: thread_setup_done.store(true) + notify_one()
  Usb构造函数->>Usb构造函数: wait 解除阻塞，继续初始化
  event_thread_->>event_thread_: handle_events()

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Alliance-Algorithm/librmcs#36: 同样修改了 librmcs::agent::AdvancedOptions 及其在 handler.cpp 与 USB transport 创建路径中的传递方式，与本 PR 在相同的选项传递节点上存在重叠。

Poem

🐇 小兔子跑进线程里，
先把回调唤醒一次，
原子旗帜轻轻一摆，
主线程安心往前跑。
thread_setup 绑好再出发，
生命周期不再是谜！✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	标题清晰准确地反映了这个 PR 的核心改动——为 agent::AdvancedOptions 增加了线程设置支持功能。
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev/thread-setup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[qzhhhi]

新版本的 clang-tidy 会崩掉，旧版本是正常的，先合并。