更新日志

版本 1.0.32 (2026-09-08)

不兼容变更

  • 🚫 find_roi 的 template_image_path 改为 template_image_name`（`_lowlevel_skills 与 MCP 工具入参）： 该参数现在接收**模板图名称**（不含扩展名），服务端拼接为 /root/data/daystar_api/ptz_templates/<名称>.jpeg`（口径同 `capture_image）。 底层 api_msgs srv 字段名仍为 template_image_path，只是语义变为名称。 调用方需从传 "/root/data/templates/xx.png" 改为传 "xx"。

  • 🚫 load_map 新增建图会话守门：建图进行中切图会被拒绝（切图意味着丢弃 正在建的图，且若导航侧接受切图、SDK 建图会话状态会与实际 SLAM 上下文脱节）。 须先 stop_mapping 保存或放弃本次建图，再加载目标地图。至此四条生命周期 操作（StartMapping/StopMapping/SetLocalizationMode/LoadMap）状态机闭环： 建图中仅允许停图或显式切模式放弃。

  • 🔄 set_obstacle_detection_limit 扩参为停障全量设置：底层服务类型由 daystar_navigation_msgs/srv/SetCloudZBoundary 更换为 SetObstacleDetectionRegion``（服务名 ``/nav/set_obstacle_detection_limit 不变），新增前/后停障距离与宽度 4 个参数，高度参数更名为 min_height/max_height``（原 ``cloud_min_z/cloud_max_z）。 6 个业务参数全量必填、同时生效（底层为全量设置接口，无法只改部分维度， 只调高度带时前后停障参数须给全量值，典型值 0.30/0.50/0.30/0.30）。 校验判据扩展：4 个停障参数必须为正有限值 + min_height < max_height， SDK 与导航端双重校验。调用方影响：老脚本 set_obstacle_detection_limit(-0.10, 0.10) 这类两参调用不再合法（6 个业务参数全必填），且原高度语义挪到了第 5/6 位， 位置参数调用须整体改写；MCP 工具入参 cloud_min_z/cloud_max_z 更名为 min_height/max_height 并新增 4 个必填停障参数， /sdk/nav/set_obstacle_detection_limit 服务请求字段同步更名扩容。

版本 1.0.31 (2026-09-07)

新功能

  • ✨ 新增 payload 载荷模块与自动门控制接口：C++ API（Payload::DoorControl，rms_msgs action 包装）→ pybind door_control → /sdk/payload/door_control`（api_msgs 新增 `DoorControl.srv）→ feedback topic /sdk/payload/door_control_feedback`（api_msgs 新增 `DoorControlFeedback.msg）

  • ✨ payload 新增报警灯控制接口：C++ API（Payload::AlarmLedControl，rms_msgs LedControl service）→ pybind alarm_led_control → /sdk/payload/alarm_led_control`（api_msgs 新增 `AlarmLedControl.srv）→ 底层 `/led_ctrl/control`（type=1 爆闪灯，mode 0=关/1=常亮/2~16=闪烁）

  • ✨ 新增操作技能三件套 lowlevel 接口（操作团队 /umi/*_skill 整体技能， 一次调用走完识别→执行全流程）：grasp_skill``（整体抓取，``std_srvs/Trigger）、 place_skill``（整体放置，``umi_msgs/PlaceInput，按台面高度）、 push_skill``（按压按钮，``umi_msgs/PushButton，预压/按压偏移可调）； 三者均带 block 参数（默认 True 同步），block=False 异步发出立即 返回，结果经 resp.wait_for/get(timeout) 统一手势取回（等价 resp.future.wait_for/get；同步调用 get 直接返回已有结果，下游无需区分 block 模式。上游 srv 无 block 字段，异步由 SDK 侧 async_send_request 回调 兑现，新增 GraspSkillFuture/PlaceSkillFuture/PushSkillFuture 句柄类型； speech 的 EnableServiceResponse 同步补齐同名 wait_for/get 透传，新旧域 同一手势）； 经 /sdk/umi/grasp_skill|place_skill|push_skill 薄转发（MCP 链路恒同步）。

  • ✨ 新增 bot_sense 感知定位域（感知定位）：prompt_move 物体定位（/bot_sense/prompt_move，daystar_perception_msgs/PromptMove）， prompt 描述目标 + front/depth 相机选择；srv 响应无 success/message，SDK 侧按 error_code == 0 折算 state.code，坐标经 response.point3d / state.describe 回吐；对外暴露 /sdk/bot_sense/prompt_move。

  • ✨ navigation_to_pose 新增 frame_id 参数（默认 map）：指点导航 传 base_link 即机体相对坐标（x 前 y 左），空串兜底 map，历史调用 行为不变；/sdk/nav/navigate_to_position 现透传请求里的 ``target_pose.header.frame_id``（此前被丢弃、服务端硬编码 map）。

  • ✨ MCP 新增工具：place_object``（放置）/ ``push_button``（按压）/ ``locate_object``（物体定位，无能力开关）/ ``navigate_to_point``（指点导航， base_link 相对坐标）；``grasp 工具改走 /sdk/umi/grasp_skill 全链路 （替换旧 demo 直连 /grasp），三件套均补 slow_action 标记。

改进

  • 🔧 硬件能力标签 grasp 语义升级为操作技能总开关（覆盖 grasp/place_object/push_button 三件套），与 ``arm``（27 个微操工具）解耦。

版本 1.0.30 (2026-09-07)

改进

  • 🔧 enable_voice_service``（F1）**语义升级为 agent 总开关**（接口名/参数/ 报文结构不变）：关闭后 agent **先停止正在执行的任务**再整体下线——决策不 受理（语音/文字/remote 全通道，文字输入返回 409 明确反馈）、后台流量全停 （语音引擎、视觉场景刷新与重探、机器人状态轮询、LLM 预热），仅保留停止类 控制（``stop/热词停止/取消）与其余开关服务；重开后恢复。适合纯遥控、 展示机等不需要 agent 服务的部署（daystar_agent 侧 voice_service 默认 改为关闭，经接口/面板开启）

  • 📝 同步 docs/sdk_exposed_interfaces.md``（F1 节语义/总说明/一览表）与 ``docs/sphinx/api/system.rst；MCP 工具 enable_voice_service 描述与 pybind docstring 同步升级

版本 1.0.29 (2026-09-07)

改进

  • 🔧 建图会话生命周期守门三条（判据统一 IsMappingSession）：start_mapping 已在建图时**拒绝**（fail + 响应新增 already_mapping，与 stop_mapping 未建图 拒绝对称；不再重切 SLAM——重切会误清当前会话暂存点、覆盖闭环配置）； stop_mapping 未在建图时**拒绝**——不再把 MAP 模式下的旧图另存为新名字， 响应新增 not_mapping；存图失败时**放弃会话并切回 MAP**——统一收尾 AbandonMappingSession（清孤儿暂存点 → 复位标志 → raw 切回 MAP）， 响应新增 mode_reverted 标记是否切回成功，异常兜底走同一路径

  • 📝 同步 /sdk/nav/start_mapping / /sdk/nav/stop_mapping srv 响应字段、 pybind docstring、MCP handler 失败/幂等话术（已在建图 / 未在建图 / 失败已切回需重新定位）、 stub 后端与 docs/modules/points-and-maps.md、docs/sdk_exposed_interfaces.md

版本 1.0.28 (2026-09-02)

新功能

  • ✨ set_gait 新增**字符串重载** set_gait(str, timeout)：步态命令字直接透传 /nav/robot_command，客户端不做机型/值域白名单（由服务端判定，不支持返回失败）。 上游后续新增步态命令字 SDK 零改动跟随；枚举版 set_gait(GaitType) 保留兼容历史 任务脚本。JOY 与导航模式均可用

  • ✨ 步态枚举补齐：C++ GaitType::SLOPE 此前有枚举无 switch 分支（传入即报 Invalid gait type），现映射 "SlopeGait"；MCP set_gait 工具新增

  • ✨ 新增 compute_ptz 空间引导接口：C++ API（PTZ::ComputePtz，校验 zoom [1.0, 25.0]）→ pybind compute_ptz → /sdk/cam/compute_ptz`（api_msgs 新增 `ComputePtz.srv）→ MCP 无（PTZ 底层硬件接口，非 agent 工具）

    ``slope``（斜坡步态）/``high_step``（高台步态，M20）两个枚举值

  • ✨ /nav/robot_command 消息包双兼容：Unimotion 迁移 ysc_robot_msgs → saturn_msgs 期间，SDK（C++ 与 mcp_server）双 client 就绪探测自动选路； 站立/趴下在新固件改用显式 StandUp/LieDown，旧固件维持 StandUpDown （显式语义由姿态前置检查保证）

版本 1.0.27 (2026-08-29)

新功能

  • ✨ 新增 set_obstacle_detection_limit(cloud_min_z, cloud_max_z, block=True, timeout=30)：动态设置 障碍物检测的点云 Z 轴高度范围（米），更新后立即作用于里程计、原始速度指令和辅助遥控三条感知路径， 无需重启节点。SDK 侧与导航端双重校验（有限值且 min < max），失败不修改当前范围。 全栈贯通：C++ API（Navigation::SetObstacleDetectionLimit）→ pybind → /sdk/nav/set_obstacle_detection_limit（api_msgs 新增 SetObstacleDetectionLimit.srv）→ MCP 新工具 ``set_obstacle_detection_limit``（含 action_phrase「调整障碍物检测范围」）

  • ✨ 导航速度模式新增 ULTRA_HIGH=4（超高）：common.hpp NavSpeedMode 枚举、 MsgTravelParams.speed_mode docstring（4=ULTRA_HIGH）、MCP travel_params.speed_mode 新增 ultra_fast 枚举值同步支持

版本 1.0.26 (2026-08-20)

修正

  • 🐛 PTZ 服务调用”一次超时后全部永久超时” —— 一次 capture_image 超时（默认仅 5 秒， 相机拍照+清晰对焦忙时会超过）后，同任务内所有 PTZ 服务调用（set_ptzf 等）永久 service_request_timeout：相机侧正常收到并处理请求，但 sdk 侧再也不消费回包 （rmw_zenoh client 回包队列堆满深度 10 后开始丢弃）。修复：

    • PTZ 的 10 个服务 client 原先全部共用一个 MutuallyExclusive 回调组（专为 capture 建的 capture_image_cb_group_ 建而未用），capture 一出事整组陪葬。现 capture 系列 （capture_image / capture_raw_image / capture_video）挂回专用组， 两组均改 Reentrant——client 响应回调只做 promise 填值，无并发副作用

    • 全部 10 条请求路径超时弃单后补 remove_pending_request()，迟到回包不再滞留 client 队列、pending 表不再泄漏

    • executor 线程改为在全部 client 创建完之后再启动，消除”实体后添加进已运行 executor” 的收集竞态（口径同 Motion / Navigation 既有修复）

  • 🐛 同型隐患全量排查修复（navigation / motion / agent / manipulation） —— 按 PTZ 事故的 三个判据（多 client 共用 MutuallyExclusive 组 / 超时不撤单 / client 在 executor 已运行后 才创建）体检其余模块并修复：

    • navigation：default 组（9 个 client）改 Reentrant；组里唯一的订阅 current_map_sub_ 挪到状态订阅组（MutuallyExclusive）保持回调串行——default 组 从此只挂纯 client。send_goal action 组**保持不动**（action 有用户回调，翻 Reentrant 会引入并发语义变化）。11 处服务调用超时路径补 remove_pending_request()

    • motion：command 组（3 个纯 client）改 Reentrant；6 处超时路径补撤单

    • agent：executor 线程挪到全部实体创建之后（原先线程先起、client 后建， PTZ 同款启动顺序竞态）；2 处超时路径补撤单

    • manipulation：请求模板超时路径补撤单（覆盖全部机械臂服务）。client 懒加载 （首次调用才创建进已运行 executor）的收集竞态窗口**保留未改**，后续另行处理

    • speech 按要求本次不动（存在同型问题：6 组全 MutuallyExclusive、线程先于 client 启动、6 处不撤单、运行期重建 client），此处留档

    • 改 Reentrant 的原则：只翻”纯 service client”的组——client 响应回调是 rclcpp 内部 promise 填值（自带 pending_requests_mutex_），无用户代码，无并发副作用； 订阅/action/timer 一律不放进 Reentrant 组

变更

  • 🔧 capture_image 默认 timeout 由 5 秒调整为 15 秒——相机拍照+清晰对焦常态 约 2 秒，繁忙/重新对焦时会超过 5 秒，原默认值过短易误报超时

版本 1.0.25 (2026-08-09)

修正

  • 🐛 任务子进程状态订阅断流的跨进程兜底（补齐 1.0.24 只覆盖到一条路径的定位兜底） —— 任务子进程的 ROS topic 订阅在暂停恢复后会整体断流（transport 层缺陷：topic 数据停送而 服务/action 通道正常）。此前只有 Navigation::GetLocalizationState 接了 /sdk/nav/get_localization_state 兜底，而运动域十来个状态读取全无兜底，断流后一律 静默退化为 UNKNOWN_* / false——其中 emergency / guardian / is_charging 的假值与真实状态完全同形，调用方无从分辨。

    • Navigation::SnapshotLocalizationStateWithFallback：robot_status 热路径此前走的是 SnapshotLocalizationState，绕开了 1.0.24 已有的兜底，等于修复在这条聚合口上没生效。 新增带节流（最短 1 秒重试、成功结果 5 秒复用）的兜底版本并由 GetRobotStatus 调用

    • Motion::GetRobotStatus 接 /sdk/get_robot_status 兜底：本进程字段失效时向主进程取 权威快照**逐字段填补**，保留仍然新鲜的本地值。仅在有等待预算的调用路径（任务脚本 / 按需服务）触发，周期发布器的纯快照路径不发 RPC；主进程自身不建 client（服务端是自己）

    • GetRobotStatusResponse 新增 fresh / from_fallback 两个标志位。fresh=False 表示兜底也没取到，此时所有字段都只代表”读不到”——这是此前整个结构体缺失的信息

    • GetRobotStatus 的九个字段改为**共享同一条等待截止线**而非各等满 wait_timeout： 断流时所有字段一起不就绪，逐字段串行等待会把 1 秒放大成 9 秒

  • 🐛 go_to_location 前置检查收口为单次聚合查询 —— 原先逐项调 get_emergency_state / get_driver_state / get_dock_state / get_control_mode / get_robot_state，每个 getter 在数据未就绪时各自阻塞 3~5 秒，断流下五项累计白等十几秒 （真机恢复任务卡顿的来源之一）。改为一次 get_robot_status_full() 取齐，并按 fresh 分流：

    • 状态不可读时**幂等命令照发**（解急停 / 上使能 / 切导航模式 / 站立）。此前 if get_emergency_state().emergency: 在读不到时拿到 False，会**漏掉真急停**

    • 状态不可读时**跳过有副作用的动作**（leave_dock），不盲发

    • loc_state 复用同一次查询（已带 /sdk 兜底），不再额外阻塞一次

变更

  • ✨ get_robot_status_full 新增 wait_timeout 参数（默认 1.0，传 0 为纯读缓存 不等待），并不再在绑定层另调 get_localization_state / get_lidar_state 覆盖 ——那两次调用会在订阅断流时额外阻塞近 8 秒，而这两个字段 GetRobotStatus 内部已填好

版本 1.0.24 (2026-08-08)

变更

  • ✨ 单点导航 ``path_following_mode`` 兜底 + 便捷参数（前向兼容） —— 导航 0731 起单点导航 行为完全由 travel_params.path_following_mode 决定（1=直线循线、2=关闭循线即绕障）， 而 TravelParams.msg 该字段无默认值声明、ROS 默认初始化为 0（PATH_MODE_UNKNOWN）， 不在单点行为表的合法取值内。此前 SDK 全链路无兜底（C++ 直接透传、go_to_location 用空 MsgTravelParams()、MCP 不传即不设），任何未显式赋值的导航调用下发的都是 0，行为不确定。

    • C++ 在**唯一的 goal 下发口** Navigation::RequestNavigationAct 统一兜底： exec_waypoints 长度为 1 且该字段为 0 时按 1（PATH_MODE_DEFAULT）下发并打 INFO。 一处收口即覆盖任务脚本、/sdk/nav/* ROS 服务、MCP 工具与导航恢复重发四条路径

    • 判据取 exec_waypoints 长度而非调用了哪个 API —— go_to_location 的单点情形底层 是长度为 1 的多点导航，在导航栈眼中同样是单点，同样受兜底覆盖；多点（长度 > 1）该字段 不参与分支，不做改写

    • navigation_to_pose / navigation_to_location 新增 path_following_mode 便捷参数，免去为改一个字段而构造整个 MsgTravelParams；显式传入时覆盖 travel_params 同名字段（口径同 go_to_location 的 ignore_final_yaw）

    • 前向兼容：旧脚本不传该参数即得到确定的单点直线导航；显式设置的有效值一律不被改写

  • 📝 数据结构 修正 MsgTravelParams.path_following_mode 的默认值错误 —— 原写作 「默认 1」，实际字段默认 0（与同页 note 及 changelog 1.0.18 的口径自相矛盾）。同时补全 path_following_mode / direction_constraint 的完整取值含义表

  • 📝 导航控制 的两个单点接口补 path_following_mode 参数映射与兜底说明

修正

  • 🐛 set_localization 恢复 ``auto_relocation`` 参数（兼容旧任务脚本） —— 1.0.20 把该参数 从 pybind 绑定整个删掉，导致导航 0731 之前编写的旧脚本一调用就 TypeError: incompatible function arguments 直接崩，真机现场表现为定位丢失后重定位 从未执行、随后持续刷 Localization is not accurate。现以**可选参数**形式加回， 排在参数表**末尾**（不影响 set_localization("point_name") 这类既有位置参数调用）：

    • 不传（默认）—— 当前正常行为，无额外日志

    • 传 False —— 等价于不传（旧语义本就是「用调用方给的初值」），仅打一条弃用 WARN 提示迁移，旧脚本因此零修改即可运行

    • 传 True —— 自动重定位能力已下线，直接返回失败（state.code=fail）， 口径与 /sdk/nav/set_localization 服务端的拒绝分支一致

    用 std::optional<bool> 而非 bool 实现，以区分「未传」与「显式传 False」—— 否则默认值会让每一次正常调用都打出弃用 WARN

  • 📝 docs/generate_api_docs.py 修正 set_localization 的示例与参数表 —— 示例仍在教 auto_relocation=True（0731 起必定失败的用法），且参数表缺 block / candidate_poses。 该脚本是 docs/global_functions_api.md 的生成源，正文虽已更新，但只要重跑一次生成器 错误示例就会被写回，属旧调用写法的复现源头

  • 📝 同步 set_localization 的 pybind docstring、_lowlevel_skills.pyi 存根与 定位与位姿 的「底层 ROS2 接口」说明（措辞由「参数已移除」改为「能力已下线、 参数仅兼容保留且不下发」）

版本 1.0.23 (2026-08-07)

修正

  • 🐛 stop_mapping 恢复 ``auto_reload=false`` 的支持 —— 此前误判「导航 0731 起 存图后必定加载新图」，在 C++ Navigation::StopMapping 入口加了硬拒绝分支， 任务脚本与 /sdk/nav/stop_mapping 两条路径传 false 都直接返回失败。经确认该 限制不成立，现移除该分支，恢复原有语义：true=存图后加载新图（并按停图位姿快速 重定位）；false=只保存地图并切回 MAP 模式，导航栈继续用原地图、不做快速重定位， 新图上的点位需显式 load_map 后才可见。本条**取代** 1.0.22 中「stop_mapping 的 auto_reload=false 直接返回失败」的表述

  • 📝 同步修正 stop_mapping 的 pybind docstring、MCP 工具 schema 说明、 docs/sdk_exposed_interfaces.md 与本文档的「底层 ROS2 接口」说明

  • 📝 修正 docs/global_functions_api.md 中 stop_mapping 的 auto_reload 默认值笔误（写作 False，实际绑定默认为 True）

版本 1.0.22 (2026-08-03)

版本 1.0.21 (2026-07-30)

变更（适配 umi_msgs / umi_planning 更新）

  • ✨ plan_trajectory 新增 velocity / acceleration 参数 —— 对应 umi_msgs/PlanTrajectory.srv 新增的时间参数化缩放字段，决定规划出的轨迹时序 （即该轨迹后续交给 execute_path 执行时的快慢）；传 0 用服务端节点默认 <group>.velocity_scaling / <group>.acceleration_scaling。轨迹快慢在**规划期** 写入轨迹点 time_from_start 定死，execute_path 无法再调速。C++ Manipulation::PlanTrajectory 与 ROS 服务 /sdk/umi/plan_trajectory 两条路径同步透传

  • ✨ list_trajectories 响应新增 descriptions 字段 —— 与 trajectory_names 一一对应（同索引），内容是录制时 start_recording 传入的 description；MCP 工具 arm_list_trajectories 的返回文本同步带上每条轨迹的描述（golden catalog 已更新）

  • 📝 play_trajectory 参数语义纠正 —— velocity 为 0 表示按录制时的原始时序回放， 有效范围 (0, 1.0]，传 >1.0 被服务端压到 1.0（只允许放慢，加速回放控制器跟不上录制路径）； acceleration 当前为空操作（no-op），回放会剥掉录制点上的 velocity/acceleration， 该参数保留仅为接口兼容。此前 docstring 与 MCP schema 均写作「加速度比例，0=默认」，属误导

  • 📝 get_current_joints 作用域澄清 —— 只返回当前规划组的关节**（Piper 为 ``joint1``~``joint6``， **不含夹爪 joint7；LX 双臂为左右臂共 14 个），单位为**度**，joint_names 可直接回传给 move_joint / plan_trajectory。与原始 /joint_states（全部硬件关节、弧度）不是一回事。 此前 docstring 写作「当前所有关节」，属误导

  • 📝 补齐 /sdk/umi/joint_command 的对外文档（此前该 relay topic 完全未记录）—— umi_msgs/JointCommand 字段表、advertise/publish 示例与**流式 deadman 语义**：断流超过 duration（0=默认 0.3 秒，实际生效 min(duration, 0.3)）即停；该 watchdog 对 MODE_RELATIVE 与 MODE_ABSOLUTE **同样生效**（早期版本只对相对模式生效，绝对模式下 停发指令后仍会把剩余行程走完，已按缺陷修复统一）

版本 1.0.20 (2026-07-30)

变更（适配导航 0731 版本接口）

  • 💥 set_localization 移除 ``auto_relocation`` 参数（不兼容变更） —— 导航 0731 版本起 自动定位初始化接口 /nav/trigger_relo 不再对外，定位初始化必须显式提供初值， 按优先级择一：candidate_poses（多候选自动选优）> location_name（已注册点位名）> pose（手动位姿）。ROS 服务 /sdk/nav/set_localization 的 auto_relocation 字段仅为线上兼容保留，置 true 时直接返回失败

  • 💥 多点导航（navigation_via_poses / navigation_via_locations）**仅支持 exec_type=0（MANUALROUTE）** —— 导航 0731 起其余执行类型 （AUTONOMOUS/STRICTTRACK/FITTING_*）弃用，SDK 侧直接返回失败（不再下发后被 Goal Rejected）

  • 💥 go_to_location 定位自愈链改造 —— 定位异常时不再隐式自动重定位，新增 reloc_candidate_poses / reloc_location_name / reloc_location_pose 参数 （按此优先级择一作为重定位初值）；均未提供且定位异常时报 NAV_RELOCALIZE_FAILED， 提示先完成定位初始化

  • 🔧 单点导航（navigation_to_location / navigation_to_pose）适配导航 0731 goal 字段 变更 —— 目标改填 goal.exec_waypoints（长度 1，行为由 travel_params.path_following_mode 决定直线/绕障），弃用的 goal.pose 字段不再填写； 对调用方 API 无感

  • 🔧 MCP 工具 navigate_via_poses / navigate_via_locations 的 exec_type 枚举收窄为 manualroute（golden catalog 同步更新）；MCP set_localization 工具的自动重定位 改经内部通道实现，工具参数面不变

  • 💥 stop_mapping 的 auto_reload 仅支持 true —— 导航 0731 起存图后默认加载新地图， 显式置 false 直接返回失败。校验位于 C++ StopMapping 本体，任务脚本（pybind）与 ROS 服务 /sdk/nav/stop_mapping 两条路径口径一致；srv 默认值由 false 改为 true（省略该字段的调用方不受影响）

版本 1.0.19 (2026-07-23)

新功能

  • ✨ 任务脚本指南（task_script_guide.md）每个函数条目自动附「↳ 返回:」字段提示 —— 由 _lowlevel_skills.pyi 类结构生成响应对象的全部可用字段（嵌套展开一层、标量字段带 : 类型 标注、枚举标注类型名），并新增「返回对象字段（重要）」规范章节（含命令类响应 bool 回执 ≠ 错误码的判断口径），杜绝脚本生成 LLM 猜测字段名或把 bool 当错误码比较（此前指南只含签名与一句话说明，get_battery_state().percentage 类字段幻觉在真机炸 AttributeError）

  • ✨ 任务脚本指南自动内嵌 docstring 的已验证示例 —— 查询类函数（载荷非平凡判定，47 处）的 Examples 节随生成注入对应分节，正确访问路径直接作为 few-shot 教材

  • ✨ 新增指南示例静态校验 tests/test_guide_examples.py —— 抽取指南全部 python 代码块，AST 遍历属性访问链逐级对照 pyi 类结构（含变量重赋的顺序敏感类型追踪），文档与实现漂移在测试期即暴露

  • ✨ 新增 daystar_api.script_lint 脚本属性链静态校验模块 —— execute_task 提交引擎前 fail-fast 守门（结构化错误 script_lint_failed）,agent 侧生成后回喂重试同源复用;类型结构由构建期 script_lint_types.json 快照供给（与指南同源生成,防漂移）

  • ✨ 任务脚本指南分层供给 —— 核心 API 分节打 <!-- core --> 标记（agent 恒注入,~20 函数覆盖顺序动作/条件分支/循环巡逻场景）,分节末尾新增类型闭包附注表（Pose/JointTrajectory 等嵌套结构引用式展开到叶子,无深度截断）

改进

  • 📝 修正 8 个函数 docstring 示例的错误属性访问（由上述校验发现）：get_gait（枚举名 STAIRS_GAIT/NORMAL_GAIT → NORMAL_STAIR/TROT）、cancel_navigation / pause_navigation / resume_navigation（.success → state.code == 0，Returns 类型名同步纠正）、wait_for_navigation（.message → .error_msg）、get_current_pose（.success/.pose → .response.success/.response.location_pose）、get_ptzf（去掉不存在的嵌套 .response 层，字段实为平铺）、stop_mapping（.success/.map_path → state.code/.response.map_saved）

版本 1.0.18 (2026-07-21)

新功能

  • ✨ 自动路网避障图数据源升级为可行域点云 —— 地图目录存在 ground.pcd（建图栈产出，有点=可走地面）时优先由其栅格化生成避障图（无 PNG 黑像素歧义，建图旁观者残影等问题根治），缺失/损坏回退 map.png 老路径；配置新增 pcd_resolution_m / pcd_free_dilation_m

  • ✨ 自动路网建边判据三级化 —— 直线可通 → 管内小幅擦挡可绕 → 可行域栅格 A* 可达（仅 pcd 数据源启用，防 png 灰色未知区误连）：无直线视线但可行域可达的点对（如 L 形走廊两端）自动连边，边权写实际路程、绕行拐点挂边（metadata.path_points），执行时自动注入为中间位姿；三级全败保持断连报错口径不变。配置新增 astar_max_expand

  • ✨ go_to_location 新增 optimize_order 参数 —— 多点路线 ATSP（PyLKH）自动重排求最短总路程（末点固定为终点，仅重排中间点）；PyLKH 不可用/目标不足自动回落保序执行

  • ✨ 虚拟接入边升级 —— 当前位置/目标接入路网时视线筛选空则扩 K 重试（6→12→全量），仍不可达再走 A* 兜底并注入出入口拐点（仅 pcd 数据源）

  • ✨ 新增路网可视化工具 python -m daystar_api.lowlevel_skills.path_planner.render —— 可行域底图 + 节点/边（A* 边画拐点折线）+ 断连组件着色 + 规划路径/实际下发路径叠画

  • ✨ 导航路径诊断自动出图 —— 每次 go_to_location 把最终下发序列落盘 graph/<map>/path/nav_path_latest.yaml 并后台渲染时间戳 png（保留最近 10 张），不占导航关键路径；env DAYSTAR_NAV_PATH_RENDER=0 关闭

改进

  • 🔧 路网发现口径收紧 —— 手动路网只认 default.yaml / default.yml（自动路网 = auto_generated.yaml），不再把目录内任意非保留名 yaml 当手动路网

  • 🔧 规划边权优先读路网 yaml 的 weight（实距），缺失回退欧氏直线距离；邻接矩阵改为纯有向（单向边不再被误对称）

  • 🔧 PathPlanner 性能 —— pp_core 传统结构懒构建（fallback 首次用到才建）+ 按文件指纹的进程内规划器缓存（路网重建自动失效）

  • 🔧 go-to-location 技能模板支持多点 —— locations 参数渲染为 JSON 并在模板内解析分支（修复旧模板只渲单点、给 locations 会生成空点位调用的问题），optimize_order 同步透传（配合 daystar_agent 侧 render_script 列表参数 JSON 化）

  • 📚 highlevel_skills.rst 的 go_to_location 条目补齐 auto_graph_planning / avoid_obstacles / optimize_order 参数与三级建边/拐点注入行为说明，执行路径表重写

  • 📚 graph_planner.rst 新增 get_cached_planner 条目、「自动路网生成与可视化」章节（三级建边机制 / 生成配置 / render_road_network 与 CLI / 导航路径诊断出图）、edges 字段的 path_points 说明

版本 1.0.17 (2026-07-17)

改进

  • 📚 全部 lowlevel 接口文档新增「底层 ROS2 接口」标注（12 个 category 页、145 处）—— 每个接口给出其实际调用的 ROS2 Service / Action / Topic 名称、完整消息类型（包名/srv|action|msg/类型名）与封装参数 ↔ 原生字段映射表；只读订阅缓存的查询接口标注来源 topic；纯本地实现（文件操作 / socket / 进程内机制）明确标注「不经 ROS2 通道」

  • 📝 修正 docstring 与实现不一致：driver_enable / emergency_stop / resume_estop / set_guardian_switch 实际走 /nav/sdk_command``（原误写 ``/nav/robot_command）；adjust_body_height 补充说明 percent 仅客户端范围校验、不随请求下发

  • 🔧 修正 system.rst「Agent 控制面」导语的服务路径口径 —— Python 封装经 C++ Agent API 直连 /agent/*，/sdk/agent/* 为 daystar_service_node 供外部 ROS 客户端的转发层

  • 📚 补齐 ptz 页 7 个此前缺失的函数条目 —— auto_focus / set_focus_mode / calibrate_ptz / set_aux_device / set_3d_location / capture_raw_image / capture_video``（均含底层 ROS2 接口标注），新增「相关数据类型」小节；data.rst 补收 ``Trigger_Response / SetAuxDevice_Response / Set3dLocation_Response / CaptureRawImage_Response / CaptureVideo_Response

  • 📝 修正 set_3d_location docstring 与错误提示 —— type 实际白名单为 0（RGB）/ 2（INFRARED），原文误写 1=RGB（按原文传 1 会被拒绝）；capture_image 示例的无效 type="depth" 改为 "infra"；auto_focus 的 focus_mode 说明对齐 srv 定义（1=半自动）

  • 📚 补齐最后两个缺失条目 —— Speech.wait_for_generate_audio（speech 页）与 get_speech_api_instance（system 页，docstring 由单行补写为完整规范格式），至此 pybind 全部对外接口在文档中无遗漏

  • 📝 治理 api 模块薄弱 docstring —— daystar_ready（原先完全缺失；如实说明当前仅校验 ROS 上下文存活、FSM 检查未启用）、daystar_shutdown（补幂等语义与 exit 参数实况：不再调用 exit()，退出码归调用方）、get_api_instance（补完整初始化链说明与单例语义：仅首次调用参数生效）

版本 1.0.16 (2026-07-09)

新功能

  • ✨ 新增 get_guardian_states —— 获取 Guardian 感知的四方向（前/后/左/右）速度衰减状态（订阅 /nav/guardian，非阻塞缓存读取，附停障开关缓存值）

  • ✨ send_cmd_vel 系运动（send_cmd_vel(dt>0) / move_by_distance / move_lateral / rotate_by_angle）内置 Guardian 避障：运动方向处于停车区自动暂停并播报方向，障碍离开后继续走完剩余量，持续阻塞超时则取消运动并上抛原因；减速区速度按衰减比缩放（保距离语义）；旋转与侧移受机身两侧停车区约束；停障开关关闭或数据过期时不守门（fail-open）

  • 📚 新增 GetGuardianStatesResponse 响应类型；策略配置见 config/guardian_avoidance.yaml

  • ✨ 支持边建图边打点 —— SLAM 建图期间 add_location 打的点先暂存 points/.mapping_session/``（建图中新图名字尚不存在，不再误绑旧地图），``stop_mapping 保存地图后自动整体迁移归属到新地图（重名覆盖，迁移数量随结果播报）；再次 start_mapping 时清除上次未保存会话的残留点位

  • 🔧 自动路网点位来源改为 map-aware —— 与点位枚举同口径（当前地图子目录 ∪ 一级目录通用点位），修复点位绑定地图后子目录点位不参与 go_to_location 自动路网规划的问题

  • ✨ 新增 set_localization_mode —— 单独切换定位模式（0=MAP 地图定位 / 1=SLAM 建图 / 2=REFLECTOR 反光柱定位），暴露为 /sdk/nav/set_localization_mode 服务、lowlevel 接口与 MCP 工具；常规建图仍应走 start_mapping / stop_mapping

  • 🔧 stop_mapping 感知闭环配置 —— 建图会话以 enable_loop_closure=False 启动（纯里程计、不积累地图数据）时不再尝试保存地图，只切回定位模式；响应新增 map_saved 字段标记本次是否真正存图，建图期间的暂存打点按孤儿清除

  • 🔧 get_robot_status 新增 mapping_loop_closure 字段 —— 本次建图会话是否开启闭环检测（False=纯里程计、stop_mapping 不会存图）；agent 据此在闭环关闭的建图结束时不再追问地图名

  • 🔧 路网文件按地图区分 —— 自动缓存写入 graph/<map>/auto_generated.yaml``（多图切换互不覆盖、各图缓存常驻）；手动路网当前地图已知时只认 ``graph/<map>/ 子目录（default 优先），不再回退一级目录旧手动图（跨图坐标系错误）；取不到当前地图时保持一级目录老行为

版本 1.0.15 (2026-06-25)

新功能

  • ✨ 新增 delete_map —— 删除指定名称的已保存地图（移除 /root/data/daystar_api/maps/<map_name>/ 整个目录），走 /sdk/nav/delete_map

  • ✨ 新增 delete_image —— 删除指定名称的已抓拍云台照片（移除 /root/data/daystar_api/images/ 下文件），走 /sdk/cam/delete_image

  • ✨ 新增批量删除对外接口 delete_maps / delete_images / delete_locations``（lowlevel + ``/sdk/nav/delete_maps / /sdk/cam/delete_images / /sdk/nav/delete_locations）与任务批量删除 /sdk/delete_tasks``（引擎节点）—— 接受名称列表（单元素=指定，多元素=批量），``delete_all=true 时服务端枚举该域全部条目快速删除，返回成功/失败名称清单。同名 4 个 MCP 工具改为直调批量服务（不再 MCP 层循环）

  • ✨ delete_maps(delete_all=True) 默认保留当前正在使用的地图不删（skipped_names 返回，并打 WARN 日志提醒）

  • ✨ 新增 MCP 批量删除工具 delete_maps / delete_images / delete_locations / delete_tasks``（均支持 ``delete_all）；原 delete_location / delete_task 单删工具保持不变（前向兼容）

  • 📚 新增 DeleteMapResponse / DeleteImageResponse / DeleteMapsResponse / DeleteImagesResponse / DeleteLocationsResponse 响应类型

版本 1.0.14 (2026-06-22)

新功能

  • ✨ 新增 switch_llm_group —— 切换 agent 的 LLM 模型组（cloud/local/hybrid），经 C++ Agent API 直连 /agent/switch_llm_group

  • ✨ 新增 enable_voice_service / enable_continuous_dialog / enable_sound_orientation / enable_safety_mode —— agent 四运行态开关（F1-F4），经 C++ Agent API 直连 /agent/enable_*

  • ✨ 新增 set_back_light —— 切换后尾灯样式（后灯板 LED，仅 MX DVT 机型），走 /nav/sdk_action 的 command_name="back_light_style"，放行 54 标准闪 / 55 快闪 / 56 慢呼吸 / 57 标准呼吸（其余电量/充电/转向/急停等为系统默认行为，不开放）

  • 📚 新增 SwitchLlmGroupResponse / AgentSwitchResponse 响应类型文档与 system.rst「Agent 控制面」小节

改进

  • 🔧 Agent 控制面改为标准分层（C++ Agent API → /sdk/agent/* 服务节点 → agent 对内 /agent/*），sdk 前缀的对外接口统一由 daystar_api 封装；新增 latched 运行态话题 /sdk/agent/runtime_state

  • 🔧 set_expression 表情序号集扩展至 4/5/6/7/8/13/14/19/20/21/22/23（新增 7 跟随 / 19 躺下 / 22 皱眉 / 23 害怕），并修正此前 19/21 序号错位（更正为 19=躺下、21=不屑）

  • 📝 新增 agent.cpp/hpp 绑定 docstring 与类型存根

  • 📝 新增 set_back_light 类型存根 docstring 与 motion.rst「后尾灯样式」小节

版本 1.0.13 (2026-06-18)

新功能

  • ✨ 新增 get_current_localization_mode —— 查询当前定位模式（返回 LocalizationMode 枚举：MAP/SLAM/REFLECTOR/UNKNOWN_LOC_MODE，来源 /nav/current_localization_mode 话题，5 秒时效）

  • 📚 新增 GetCurrentLocalizationModeResponse / LocalizationMode 响应类型与枚举文档

改进

  • 🔧 set_localization 新增 candidate_poses 参数 —— 提供多候选初始位姿时优先走自动选点重定位（/nav/autoselect_initialpose），忽略 auto_relocation/location_name

  • 🔧 start_mapping 新增 enable_loop_closure 参数 —— 是否开启闭环检测（默认开启；关闭退化为纯里程计，适合长时运行）

  • 🔧 GetRobotStatusResponse 新增 localization_mode 聚合字段（当前定位模式）

  • 🔧 robot_status 的 loc_state / lidar_state 改读 Navigation 无日志快照（修复此前恒为 UNKNOWN 的缺陷）；数据超时（>5 秒）时返回 UNKNOWN``（此前会保留最后一次旧值），消费方（如定位前置检查 ``loc_state == NORMAL）需注意此语义变化

  • 📝 同步更新 localization.rst / data.rst 与类型存根 docstring

版本 1.0.12 (2026-06-01)

新功能

  • ✨ 新增 get_lidar_state —— 查询雷达整机健康状态（返回 LidarState 枚举：UNKNOWN/NORMAL/HIGHFREQ/LOWFREQ/DISCONNECT）

  • 📚 新增 GetLidarStateResponse / LidarState 响应类型与枚举文档

  • 🔧 GetRobotStatusResponse 新增 lidar_state 聚合字段（雷达健康状态）

  • 📝 同步更新 motion.rst / data.rst 与任务脚本指南

版本 1.0.11 (2026-06-01)

新功能

  • ✨ 新增 get_driver_state —— 查询驱动器使能状态（返回 DriverEnableState 枚举）

  • ✨ 新增 get_emergency_state —— 查询软急停状态

  • ✨ 新增 get_guardian_state —— 查询停障开关状态

  • ✨ 新增 get_robot_status_full —— 一次性获取机器人聚合总状态（姿态/控制模式/步态/充电桩/电池/充电/定位/位姿/使能/急停/停障）

  • ✨ 新增 driver_enable —— 上/下使能驱动器

  • ✨ 新增 emergency_stop —— 触发软件急停

  • ✨ 新增 resume_estop —— 恢复软件急停

  • ✨ 新增 set_guardian_switch —— 开/关停障功能

  • ✨ 新增 demo_control —— 触发演示动作（摇头 / 摆尾 / 打招呼）

  • 📚 新增 GetDriverStateResponse / GetEmergencyStateResponse / GetGuardianStateResponse / GetRobotStatusResponse 响应类型文档

  • 📚 新增 DriverEnableState 枚举文档

  • 📝 同步更新 motion.rst / data.rst 与任务脚本指南

版本 1.0.10 (2026-05-31)

新功能

  • ✨ 新增 request_mode —— 切换机械臂模式（IDLE / MOTION / SERVO，SERVO 再分 CARTESIAN / JOINT），替代旧的 set_state。

  • ✨ 新增 raise_fault / clear_fault —— 主动进入 FAULT（软急停 / 异常上报） 与清除故障恢复 IDLE。

  • ✨ 新增 /sdk/umi/joint_command 话题转发（SERVO/JOINT 关节伺服流， umi_msgs/JointCommand），与既有 /sdk/umi/servo_jog 对称。

变更

  • 🔧 移除 set_state / switch_controller / list_controllers / start_guidance / stop_guidance：set_state 由 request_mode 取代； 控制器切换改由 umi_planning 在 request_mode 内部仲裁，不再对外暴露裸切； guidance 由 request_mode + servo 取代。

  • 📝 同步更新 manipulation.rst / data.rst 与 _lowlevel_skills.pyi 存根。

版本 1.0.9 (2026-05-25)

改进

  • 📝 修正 plan_trajectory 的 tolerance_orientation / tolerance_joint_position 单位：由”弧度”更正为”角度（单位：度）”，与 joint_positions / rpy 等其余 Umi 角度量统一为度（tolerance_position 仍为米）。

  • 🔧 上述两个容差在 umi_planning 服务端新增度→弧度转换后再下发 MoveIt；默认值由 0.001 改为 0.0，表示”用服务端默认”（约 0.057°，即 0.001 rad），省略时 规划行为与此前完全一致。

版本 1.0.8 (2026-05-18)

新功能

  • ✨ 新增 25 个机械臂/双臂 manipulation 接口：move_joint / move_tool / move_to_pose / stop_motion / compute_fk / compute_ik / plan_trajectory / execute_path / save_pose / record_pose / get_pose / list_poses / delete_pose / start_recording / stop_recording / list_trajectories / get_trajectory / delete_trajectory / play_trajectory / read_tcp_pose / read_tcp_rpy / get_current_joints / set_state / switch_controller / list_controllers。覆盖关节/笛卡尔运动、运动学 解算、轨迹规划与执行、位姿库与轨迹库管理、轨迹录制回放、控制器切换等。

  • ✨ 新增 ALL_JOINTS 常量（等价 []），作为 move_joint 的 joint_names 默认值，不指定即作用于全部关节。

改进

  • 📝 将 manipulation_py.cpp 中 25 个接口的 pbdoc 由一句话升级为完整 Google 风格（功能说明 + Args + Returns + Examples），并补充 CartesianTarget / JointTrajectory / JointTrajectoryPoint 类型 存根 docstring；重建后自动再生 _lowlevel_skills.pyi。

  • 🔧 5 个可阻塞接口（move_joint / move_tool / move_to_pose / execute_path / play_trajectory）在 docstring 中明确 block 同步/ 异步语义与 timeout 等待语义，以及与 stop_motion 的协作取消关系。

  • 📚 新增 机械臂操作 文档页，并挂接到 lowlevel_skills 模块 的模块概览与 toctree。

  • 📝 数据结构 新增 25 个 XxxResponse 接口层响应、25 个 UmiXxxResponse ROS 层响应，以及 CartesianTarget / JointTrajectory / JointTrajectoryPoint 消息类型说明。

  • 📝 修正关节角（target_positions / joint_positions / JointTrajectoryPoint.positions）与 CartesianTarget.rpy 的单位 说明：由”弧度”更正为”角度（单位：度）”，对齐 Umi 对外接口实际约定 （x / y / z 仍为米）。

  • 🔧 move_joint 的 joint_names 改为可选（默认 ALL_JOINTS）， 仅传 target_positions 即可作用于全部关节，不再因缺省报 TypeError。

  • 🔧 修复通用任务多行异常消息（如 pybind11 incompatible function arguments 重载报错）仅首行带用户错误前缀的问题，现每物理行均带 [DAYSTAR_USER_ERROR] 前缀，避免下游按前缀转发时签名/Invoked with 行被截断丢弃。

版本 1.0.7 (2026-05-14)

新功能

  • ✨ navigation_via_poses / navigation_via_locations 新增 per-call 回调参数 complete_callback / failed_callback / progress_callback，与 navigation_to_pose 风格对齐。底层通过新增的 NavCallbackGuard RAII 临时安装， 调用结束自动还原成调用前的全局回调（不污染其它模块注册的回调）。

  • 🛡️ C++ 层新增**回调死锁防御**：navigation_client_ 绑在 send_goal_cb_group_ （MutuallyExclusive），在 complete/failed/progress 回调内部再调阻塞型 nav API 会自锁。 通过 thread_local 标志 + RAII 在用户 callback 入口置位；RequestNavigationAct(block=true) / WaitForNavigation / RequestCancelNav 入口检测到立刻抛 std::runtime_error （Python 端见为 RuntimeError），错误消息说明替代方案。

改进

  • 🔧 highlevel skill go_to_location 重构（不兼容变更）：

    • 移除 waypoints 参数；新增 locations: List[str] / poses: List[Pose] 显式多点列表参数。”先经过 A、B 再到 C” 现在直接写 locations=["A", "B", "C"]。

    • 四个目标参数互斥：location / pose / locations / poses，必须且只能给一个。

    • 底层统一走多点导航 API：名字目标 → navigation_via_locations， 位姿目标 → navigation_via_poses。不再单独调 ``navigation_to_pose``——单点情形等价于 长度为 1 的多点导航。

    • 单 location / pose 配合路网时，最短路径展开为完整节点序列（含起点）后**一次性下发**， 不再分”中间段 + 最终段”两次调用。是否 skip 已到达 waypoint 由底层控制器判定。

    • 修复旧版 path_ids[:-1] 切片把”起点”塞进 transit、把”终点”从 transit 中剥离的语义错误； 现在路径列表原样下发，与显式 locations 入参在底层眼中完全等价。

    • travel_params 不再被高层改写 ignore_final_yaw=True：现在列表最后一个就是真正的终点， travel_params 直接透传，终点 yaw 对齐按用户配置生效。

    • 回调改为底层 per-call 安装，不再使用 register_event_callbacks 全局注册的 hack； 完成 / 失败 / 进度三类回调对整条多点导航都生效（旧版仅最终段触发）。

    • 返回类型：_lowlevel_skills.IntelligentNavigationResponse → _lowlevel_skills.NavigationViaPosesResponse。两者都有 state.code / state.cn， 调用方代码通常无需改动。

  • 📝 同步 _lowlevel_skills.pyi：navigation_via_poses / navigation_via_locations 签名追加 3 个 callback 参数 + docstring 说明 per-call 安装机制。

  • 📚 highlevel_skills 模块 章节按新签名重写：参数表、执行路径表、回调死锁防御说明、示例代码全部更新。

  • 📚 skills/go-to-location/SKILL.md 同步：移除 waypoints，新增 locations 抽取提示； script_template 更新；版本号 2.0。

  • 🔧 navigation 回调改为 per-goal 闭包绑定（替代 NavCallbackGuard 栈作用域 RAII）。 修复在 failed_callback 内调 navigation_*(block=False) 跳到下一个目标点时， 新 goal 的 complete/failed/progress 回调链断裂的问题。block=True 在回调内仍抛 RuntimeError。

  • 🔧 修复 launch ctrl+c 后导航 goal 残留、task 子进程变孤儿。StopExecution 改为 SIGINT → 等 3s → SIGKILL 两阶段；TaskEngineNode::onConfigure 通过节点 context 注册 on_shutdown 回调，在 rclcpp::shutdown() 早期主动调 TaskManager::Shutdown， 绕开 component 析构时序。

  • 📝 _lowlevel_skills.pyi 中 navigation_via_* 的 callback 字段说明同步到 per-goal 语义； go_to_location.py 的 callback note 段落同步。

版本 1.0.6 (2026-05-13)

新功能

  • ✨ 新增 navigation_via_locations —— 按已注册点位名序列做多点导航，内部循环 LoadSingleLocation 读取 /root/data/daystar_api/points/<name>.yaml 的 nav_pose 拼成 PoseStamped 列表后委托给底层 NavigationViaPoses，任一点位 yaml 加载失败时不会发起底层调用并在错误描述中带出具体哪个点位无法解析。返回类型复用 _lowlevel_skills.NavigationViaPosesResponse。

  • ✨ 新增 ROS2 服务 /sdk/nav/navigation_via_locations``（srv 类型 ``api_msgs::srv::NavigationViaLocations）作为该接口的对外暴露通道。

  • ✨ 新增绑定类型 _lowlevel_skills.SrvAPINavigationViaLocations_Response`（字段语义与 :class:`_lowlevel_skills.SrvAPINavigationViaPoses_Response 一致）。

改进

  • 🔧 highlevel skill go_to_location 重构：新增 waypoints: Optional[List[str]] 参数，可在不依赖路网文件的前提下显式指定必经中间点列表；中间段统一改为调用 navigation_via_locations``（取代原先客户端拼 PoseStamped 列表的写法）；最终段统一改为 ``navigation_to_pose，complete_callback / failed_callback / progress_callback 始终挂在最终段（中间段不触发回调）。

  • 📝 _lowlevel_skills.pyi 同步 navigation_via_locations 函数 stub 与 SrvAPINavigationViaLocations_Response 类 stub，__all__ 同步更新。

  • 📚 新增 highlevel_skills 模块 章节，首批收录 go_to_location；采用手写 py:function 指令（与 逻辑流控制 同风格），不依赖 daystar_api 顶层包的 autodoc 链。

版本 1.0.5 (2026-05-11)

改进

  • 🔧 api_msgs 中含 timeout 字段的 srv 文件统一补充默认值，与 daystar_api 对应函数签名对齐：

    • LoadMap.srv — auto_reload=true, block=false, timeout=30

    • StopMapping.srv — auto_reload=false, need_2d_map=true, block=true, timeout=30

    • AddLocation.srv — timeout=5, use_virtual_pose=false

    • NavigateToPosition.srv / NavigateToLocation.srv — timeout=600

  • 🔧 DaystarServiceNode::LoadMapCallback 此前漏传 req->timeout，现已传入；block=false 时 timeout 真正生效，<=0 时回退到 daystar_api 默认值 30。

  • 🔧 DaystarServiceNode::StopMappingCallback 同样漏传 req->timeout，按相同模式修正。

  • 📝 stop_mapping / load_map docstring 修正 block 与 timeout 的语义说明：block=True 时使用内部最大等待（kBlockMaxTimeoutSeconds = 30 分钟），timeout 参数仅在 block=False 时生效。

  • 🔧 navigation_via_poses 默认 exec_type 由 1=AUTONOMOUS 改为 0=MANUALROUTE``（巡检点位路线，折线无邻点过滤），符合多点导航的常见使用模式；``NavigationViaPoses.srv 同步补充 MANUALROUTE=0 常量与默认值。

  • 🔧 NavigationViaPoses 实现内显式置空 goal.pose.header.frame_id（多点导航下该单点目标位姿不使用），避免上游残留 frame_id 干扰下游解析。

版本 1.0.4 (2026-04-29)

新功能

  • ✨ pybind11 几何/基础数据类型构造糖：16 个类（Point/Vector3/Quaternion/Pose/PoseStamped/Twist/PoseWithCovariance/TwistWithCovariance/PoseWithCovarianceStamped/Header/Time/State/MsgTravelParams/BatteryState/FileInfo/MapFileInfo）新增**位置参数 + kwargs 构造**支持，例如 Point(1.0, 2.0, 3.0) / Pose(position=Point(0.5, 0, 0))。

  • ✨ Quaternion 新构造时 w 默认 1.0（identity rotation），Quaternion(0.5, 0, 0) 直接得到合法旋转。

  • ✨ Pose / PoseStamped / PoseWithCovariance / PoseWithCovarianceStamped 新构造时若不显式给 orientation，自动取 identity Quaternion。

兼容性

  • 所有空构造（Pose() / Quaternion() / PoseStamped() 等）行为完全保持，仍返回 ROS C++ 消息默认值（Quaternion → identity w=1.0；Pose → identity-orientation；Vector3/Twist/Header/Time/State/MsgTravelParams/BatteryState/FileInfo/MapFileInfo → 各字段全 0/false/空字符串/空列表）。

  • def_readwrite 链式赋值 pose.position.x = 1.0 不变。

  • MsgTravelParams 新构造的枚举字段（speed_mode/gait/path_following_mode/direction_constraint）默认 0（UNKNOWN），与现状空构造完全一致；调用方仍需显式赋有效值。

文档

  • 📚 data.rst 16 个数据类型章节示例补充新构造姿势；新增 PoseWithCovariance/TwistWithCovariance/PoseWithCovarianceStamped 章节。

版本 1.0.3 (2026-03-23)

新功能

  • ✨ 新增逻辑流控制接口（任务引擎运行时注入）：

    • run_script(source, parameters) — 串行执行子脚本

    • run_parallel_script(source, parameters) — 后台线程异步执行子脚本，返回 ThreadHandle

    • pause_application() — 在当前位置暂停任务，等待外部 resume 信号

    • resume_application() — 写入 resume 信号，从后台唤醒暂停中的主脚本

    • stop_application() — 取消所有后台线程并立即终止任务

  • ✨ 新增 ThreadHandle 类（join / is_done / cancel）

  • ✨ 新增 ScriptError 异常类（包装子脚本原始异常）

改进

  • 🔧 sleep / pause_application / resume_application / stop_application 加入步骤白名单，确保按脚本书写顺序执行

  • 📚 新增逻辑流控制文档页面（api/flow_control.rst）

  • 📝 lowlevel_skills/__init__.pyi 加入流控制函数类型存根，IDE 可通过 TYPE_CHECKING 获得提示

版本 1.0.2 (2026-02-27)

新功能

  • ✨ 添加运动控制模块 (motion) - 包含站立、躺下、步态控制、充电管理、电池状态查询等功能

  • ✨ 添加 stand_up - 控制机器人站立

  • ✨ 添加 lie_down - 控制机器人躺下

  • ✨ 添加 get_robot_state - 获取机器人当前状态

  • ✨ 添加 adjust_body_height - 调节机器人身体高度

  • ✨ 添加 set_gait / get_gait - 步态类型设置与查询

  • ✨ 添加 set_control_mode / get_control_mode - 控制模式切换

  • ✨ 添加 go_to_dock / leave_dock - 充电座管理

  • ✨ 添加 get_dock_state - 获取充电座状态

  • ✨ 添加 get_battery_state - 获取完整电池信息

  • ✨ 添加 is_charge - 检查充电状态

  • ✨ 添加 send_cmd_vel - 全向运动速度控制

改进

  • 🔧 移除文档示例中不必要的 from ... import 语句（因 task_template.py 已预导入）

  • 📝 完善运动控制接口 docstring（Sphinx 格式）

  • 📚 新增运动模块文档并加入 lowlevel_skills 目录

版本 1.0.1 (2026-02-09)

新文档

  • 📝 完善语音接口 docstring（Sphinx 格式）

  • 📝 新增语音模块文档并加入 lowlevel_skills 目录

  • 📚 更新文档构建指南示例与目录说明

版本 1.0.0 (2025-01-20)

新功能

  • ✨ 添加 navigation_via_poses - 多点导航功能

  • ✨ add_location 支持虚拟打点模式

  • 📝 完整的 Sphinx 文档

改进

  • 🔧 优化导航参数默认值

  • 📚 所有函数添加详细 docstring

  • 🎨 改进 Python 绑定的文档

版本 0.9.0 (2025-01-15)

初始版本

  • 基础导航功能

  • 定位管理

  • 地图管理

  • 云台控制