NavBridge SDK 0.1.0 · 导航统一接入与完整手册

NavBridge SDK 0.1.0：统一 P2 / WATER 导航客户端、完整项目手册与 Cloudflare Pages 文档站。导航 baseline-v1 / baseline-v2 标签保持不变；本次不替换1006现场运行版。

• Python wheel、Node/TypeScript TGZ、OpenAPI 3.1、17页中文PDF与完整公开源码ZIP。
• P2 Console / WATER TCP / 合成夹具三类provider；WATER兼容入口实现单点、取消、状态订阅与普通点位CRUD，明确LF/CRLF profile。
• 任务受理、真实导航终态、介绍/等待、人工接管分别记录；持久幂等与未知派发不重放。HTTP500保持结果未知，不自动跟随重定向。
• 附加Console任务引用比较，旧任务不能取消/替换APP的新任务；原APP调用与E档、摇杆、取消语义保留。
• 文档站：navigation.bismih520.com，含手册、兼容矩阵、API、合成交互和真实下载。

验证：43项Python SDK合同测试、4项Node跨语言测试、485项原项目回归通过；wheel独立环境安装、TypeScript类型检查、PDF渲染、桌面/手机浏览器检查、公网下载SHA核对完成。精确源码：abaf18c740b5e0d5b416aab3f1e71dbd5bb9d5e3。精确提交的原项目/原生ROS/Nav2 CI 4/4通过；SDK CI 2/2通过（Python3.10/3.12）。

当前声明范围是已实现并离线验证的兼容子集，尚无同事实际SDK/云迹固件互通记录。公开WATER手册未定义请求结束符；原厂状态不保证带task_id。云端订单API、回充、乘梯、轮式自由急停及参数覆盖没有冒充实现；完整矩阵见兼容文档。本次没有执行真机运动或请求真实云迹云服务。

下载文件逐项SHA256见 SHA256SUMS.txt；私有地图、录包、厂家模型/驱动/策略和凭据不在包内。公开参考：云迹官方历史Open API，厂商署名WATER v1.8.7手册。

Navigation V2 · Release Baseline

Navigation V2 · Release Baseline

2026-11-05 按用户要求冻结为 baseline-v2，作为后续导航迭代、对比和回退的版本。V1 标签保持原样。功能源码基于 5fc9ae3e709b5781fb54c744c1ab4f9839072f44；发布补充说明、参考配置和清单，不替换已经实测的控制算法。

功能

• MID-360S 雷达惯性建图、地图保存/重载、定位和实时激光叠加；使用投影观测进行二维导航。
• 网页地图上增加、编辑、删除点位，设置名称、朝向、产品介绍、停留和等待继续；已保存点位先进入编辑状态再修改。
• 单点前往、一键返回、顺序路线、往返和有限循环；到点按配置讲解，再进入下一站。
• 禁行线、减速区、附近停靠、地图版本、续扫、局部更新，以及地图/点位/路线同包备份迁移。
• 实时障碍绕行；无法继续时停车并重规划，保留路线、控制输入和失败原因。地图变化低频收集、按日空闲融合，不每秒重画整图。
• G12 APP 的 E 左档允许导航并显示地图，选点后一次点击开始；中档暂停，操作员主动继续；右档或摇杆接管结束自动任务。取消有效，切回左档不自行续走。
• 机身喇叭优先的导航提示与到点介绍，可设置音量/静音；同类状态去重。
• 前向为主，允许边走边转和原地转向，侧向输入为零；前向增加使用 S 形渐进输入。

本次冻结的参数

可直接交给现有 apply_runtime_geometry 的参考配置见 baseline-v2.json。它表达这台已测安装的参数，不能替代另一台机器的身份、安装与实际步态配置。

项目	V2 基线
规划/碰撞机身方块	总边长 0.55 m，额外足迹 padding 为 0
全局、局部实时障碍合并	两侧均为 0：真实观测射线可以释放旧占用，新回波仍标记障碍
点位到达	介绍/位置点位 XY 半径 0.40 m；有指定朝向时允许 20°误差
D 前向、转向输入上限	0.75 / 1.0；弯行前向目标约 0.6；侧向为 0；本轮倍率 1.0
原始遥控样本过期时间	2.0 s；与健康、命令、RPC、速度反馈各自时效分别处理
前向增加	最大变化率 0.30 输入/s，变化率的变化率 0.40 输入/s²
减速、转向	保留原有下降和转向响应；完整归零尚未区分正常制动与保护停车

复现这套参数时，把参考配置复制为所选运行目录的 planning_geometry.json，现有工作流会在生成 Nav2 参数时读取它。例如先把 P2_V2_RUNTIME 设为本机选定的运行目录，再执行：

install -m 600 navigation/profiles/baseline-v2.json "$P2_V2_RUNTIME/planning_geometry.json"

1006 已经使用这组实际参数，本次冻结不重启程序、不重复应用或改动现场设置。独立机器身份、外参、颈部位置和厂家策略配置不由此文件覆盖。

这些速度值是 D 策略的手动等效输入，不能解释成实测 m/s。40 cm 是距目标中心的总到达容差，不是定位误差精度，也不改变碰撞包络。障碍停车、E 开关、摇杆接管与取消保持既有行为，没有增加第二次开始确认或人工验收文件门。

实机结果与软件验证

20 个编号点位均有实际到达记录。最初 1、2 号完成后，3 号路段暴露全局/局部障碍合并不一致；修复后从 3 号续行。4 号介绍点又因约 34 cm 距离超出原 30 cm 范围而反复收尾，暂停任务，将上述到达容差改为 40 cm，再恢复同一任务。

从 4 号恢复至 20 号，导航程序自行选路、到点、按配置播报并进入下一站，未再由观察者选路、跳点或补点继续，最后自动停车。续行段记录到 6 次重规划，约 1.4–4.6 s，均自行恢复。此记录是中途修复后的连续完成，不是一次从 1 到 20 无干预通过，也没有独立真值证明定位精度或全部物理接触情况。

功能源码 5fc9ae3 的 478 项 Python 测试通过；GitHub push 41926395445 与 PR 41926406675 各 4/4 通过，含原生 ROS/Nav2 集成、地图工具、到点介绍、停留/继续、动态障碍和接管测试。原始失败、旧候选与中途暂停记录保留。仿真不冒充双足实机结果。

实机只读核对了实际 Python/页面、加载的 Nav2 库和独立 D 编译来源；D 编译使用的四个公开输入头文件与发布源码逐项 SHA 一致。Nav2 控制/规划包源码与实际复用的 1dd17a4 安装基底一致；仿真输入模型不是实机 D 程序。公开清单见 releases/baseline-v2.json，厂家驱动和策略不分发。

保留的后续优化

• 途中仍有短暂重规划停车，起步调头仍有停走衔接；下一轮应减少这些停顿，并验证从 1 号开始无需中途修复的整轮任务。
• S 形增加输入已经接入实际 D；正常到点完整归零的 S 形制动意图尚未接通，不能宣称所有停车都已使用 S 曲线。
• MID-360S 当前设备 time_type=0 未同步，ROS 头使用主机接收时间，不代表设备采样时间精度。
• 当前发布的导航工作流是二维；实际办公室三维 PCD/变换尚未绑定成已验证的三维导航流程。

备份和回退

baseline-v2 固定源码、参考参数、依赖版本与本次验证说明。1006 的实际安装配置、地图、点位、路线、二进制身份和服务启动信息另存私有快照，在机器人和开发机各保存一份并核对 SHA；这些材料不进入公开 Release。

V1 仍为 baseline-v1 → 6479e25f5825b5dbce9e6229a33ad5d564b0649a。今后的改动从 V2 之后继续，不移动两个基线标签、不覆盖历史失败。换机仍使用新机器身份和独立安装配置；本次冻结没有发送导航目标、重启 D/驱动/颈部或操作电池。

发布提交的额外CI记录

功能源码5fc9ae3的两次4/4结果保留。发布提交e0e6460仅增加文档、实际参数副本和清单，控制代码/构建脚本逐项相同；额外PR流水线41930564619的局部地图合成测试出现“障碍端点未标记为lethal”断言失败，原始日志保留。该失败尚未隔离原因，不能宣称修好；发布push流水线状态另见随包CI_RELEASE_STATUS.json。V2是用户选定的实机工作版本冻结，后续回归和停顿优化继续在新提交处理，不移动基线。

v0.5.3-recovery.1 · 封路等待与恢复

前方突然封路时，接入真实Nav2恢复等待回执，修复机器人已停车、工作台仍显示执行中的状态。每次目标按场地等待设置生成有界恢复树；默认短等4秒、最长25秒、连续清空1.5秒。等待中可人工接管；取消或超时后不会自动重启。

验证与部署：333源码SHA逐一匹配1006；本机328测试通过（2环境项跳过）、ARM328项全部通过。精确9dc837f的分支CI41407233467、main41409037573与tag41409060551各4/4通过，Pages41409036963成功。CI包含真实ROS/Nav2走廊：两张实际代价图横截面封闭且射线生效，覆盖封路后开放、持续封路及随后开放不重启、等待中人工接管，零模型占地侵入。

1006仅更新独立console服务，沿用74043e5已构建ARM原生插件；27共享工厂进程身份不变，原地图文件SHA不变。没有执行真机走路、真实导航目标、电机、脖子或电池动作。第一次切换时地图尚未收到就恢复定位而回滚，修正切换顺序后完成更新。

附件为公开通用源码及合成证据，不含办公室地图、录包、厂商策略或凭据。Baseline V1保持不变。此版不包含实验性精确几何、速度适配或急弯减速；这些候选仅在普通延迟冻结图回程通过，较大延迟仍失败，未部署。

P2导航 v0.5.2-pivot.2：平滑弯行与停稳到点

P2 导览接待导航：转向与弯行输入更新

主路径弯行会平滑降到约0.6前向输入，并保留转向输入；直行上限0.75、转向上限1.0和操作者选择的倍率保持原语义。带朝向目标停稳后再完成任务并进入介绍；普通途经点连续通过。E档位、摇杆接管、取消、障碍停车和55cm总方块均保持。

验证：204组实际Nav2转向组件组合（含48组半速）、8组组合跟踪、16组预瞄对比；中心及左右偏置障碍三组实际ROS任务流程，各完成6项检查，障碍确实触发且零包络侵入。1006原生ARM构建和322项测试通过。对应74043e5主分支与标签CI各4/4通过。

软件已切换到1006本聊天独立导航服务；未发送真机行走目标、电机、脖子或电池命令。当前仍为手动档、零导航输出，保留现有地图、点位、路线和倍率。软件组件/平面模型验证不能替代双足实机复测。

保留边界：冻结办公室地图的反向回程仍失败；一次取消额外选路偏好的候选出现包络侵入，已经拒绝采用。首次9c7b9e9旧时钟对比失败、75ca7fb主CI绕障失败及同SHA标签通过均保留，不用一次通过覆盖失败。Baseline V1标签不变。

附件仅含自有通用源码和合成证据；不含办公室地图、录包、机身音频、厂商驱动/策略/模型、Android私有源码或凭据。操作界面沿用G12 0.10.0与现有手册。

导览接待与地图工具 · v0.5.1-map-tools.6

在冻结的 baseline-v1 上扩展导览接待、地图工具与场地迁移。

提供常用点位与一键返回、可选到达方向与产品介绍、A→B→C规定路线及往返/有限循环/停留；实时激光和拖动定位校正、地图版本、SLAM Toolbox位姿图续扫与局部栅格更新；禁行线同时进入全局和局部代价图，减速区实际接入速度链路，目标占用时可选附近停靠；按源时间对齐的任务回放，以及带逐文件和整包SHA的地图＋点位＋路线场地包。话术保存后后台准备，机身喇叭优先。G12保留一次开始、E档位和摇杆接管，电脑提供精细编辑。

修复旧地图入口脚本全局声明冲突、小屏取消按钮不可见及跨地图旧响应残留。规划保留同目标的有效绕行方向，在每次复用前按最新地图重查完整55cm足迹；新的障碍会触发改道，通道重新直达时采用直达路线。修复门洞只见部分视野后恢复旧关闭门而反复掉头：门的实时状态仍为未知，派生地图保留实测门洞变化和原观测时间，关门回波、地图重载或几何变化撤销；不刷新开放证据寿命或传感器时间。

本机与1006 ARM各318项测试通过。实际ROS2/Nav2/SLAM隔离回归包括3轮联合巡游/开门改道/动态障碍/暂停/接管、双代价图禁行和减速区进出、续扫局部更新；另有5种重复规划变化、8组延迟跟踪及4组合成位置规划。失败的旧CI和无效候选保留，未通过的纯转向实验没有进入此版本。

此版本没有新增真实双足落地行走验收。旧私有冻结图反向回程、6/12较大延迟转向模型仍有失败；3D为点云预览，不能冒充完整高度避障或跨层导航。D策略减速区域倍率仍需现场联调，策略输入不是已标定m/s。公开包只含自有通用源码、合成样例及去隐私结果，不包含办公室地图、现场音频、厂商模型或凭据。

交付补充：1006独立导航/音频服务已更新，317份源码SHA逐个匹配；实际静止场地副本导入、地图载入、位姿图续扫、局部栅格更新和版本恢复通过，原始地图四文件未变并恢复原上下文。27个共享工厂进程身份记录不变，30秒120次健康检查均为零导航输出，地图/内容/音频私有备份已在本地和机器两端核对SHA。此项是静止软件工作流验证，仍无新增实体行走验收。

v0.5.1-handset.2 · G12 operator workflow and guide

G12 导航执行体验与手册配套更新，保留 Baseline V1 与既有现场成功及失败记录。

• 横屏地图与任务操作分栏；目的地、路线巡游分开选择，开始、暂停优先显示，讲解和完整原因可展开。
• 自由点地图生成临时目标，一次开始进入原任务链；不写入常用点位，不要求额外终点转向。
• 原有 E 左档允许、中档暂停、右档或摇杆接管、取消语义不变。
• 同源网关直接进入新版执行页，保留文件和跨域访问限制；双指缩放与长走廊横屏适应。

验证：320 项 Python 测试，本地和实际 1006 ARM 各通过；准确主提交 CI 4/4 通过。配套私有 G12 APP 0.10.0 的 37 项 JVM 测试及真实手柄登录、地图加载、按钮可见性和帮助页测试通过。1006 只更新独立导航界面服务，27 个原整机进程身份未变，无真实行走、脖子、电池或总线动作。

此包仅含自有通用源码、通用操作说明和合成测试。G12 厂商应用源码、安装包、私有地图、产品音频及配图手册分别私有保存，不在公开包内。界面与静态或模型测试不表示新实机行走通过；旧反向返回和大延迟转身失败仍未消除。

后续修复：电脑直接管理入口可返回原导航地图；实时档位提示区分手动、中档、允许、未知及未核验状态，新增7种实际脚本验证；长原因可在行程详情展开。对应配图操作手册14页与G12界面截图私有交付。

v0.5.1-handset.1 · G12 navigation operator workflow

G12 导航执行体验更新，保留 Baseline V1 与既有现场成功及失败记录。

• 横屏地图与任务操作分栏；目的地、路线巡游分开选择，开始、暂停优先显示，讲解和完整原因可展开。
• 自由点地图生成临时目标，一次开始进入原任务链；不写入常用点位，不要求额外终点转向。
• 原有 E 左档允许、中档暂停、右档或摇杆接管、取消语义不变。
• 同源网关直接进入新版执行页，保留文件和跨域访问限制；双指缩放与长走廊横屏适应。

验证：320 项 Python 测试，本地和实际 1006 ARM 各通过；准确主提交 CI 4/4 通过。配套私有 G12 APP 0.10.0 的 37 项 JVM 测试及真实手柄登录、地图加载、按钮可见性和帮助页测试通过。1006 只更新独立导航界面服务，27 个原整机进程身份未变，无真实行走、脖子、电池或总线动作。

此包仅含自有通用源码、通用操作说明和合成测试。G12 厂商应用源码、安装包、私有地图、产品音频及配图手册分别私有保存，不在公开包内。界面与静态或模型测试不表示新实机行走通过；旧反向返回和大延迟转身失败仍未消除。

v0.5.0-reception.1 · 导览接待工作台

基于冻结的 baseline-v1 增加可编辑的导购接待工作流，保留原有实机导航与失败记录。新版本支持电脑管理点位、方向、产品话术和多条展示路线；操作端选择单点或路线后一次开始，到点讲解、等访客、暂停主动继续与取消。

• 无到点动作的途经点使用实际 Nav2 NavigateThroughPoses 连续通过；规定展示路线与自适应通道选路分别可用。
• 有限真实激光射线确认门开闭，门叶范围使用可撤销覆盖；途中能利用新开放捷径、绕行或有界等待。原始地图保留，未知不作为开放证据。
• 修复位置路径沿用旧目标请求时间、障碍恢复的异步回执丢失；绕行优先选择有跟踪余量的路线，仍保留原完整55cm包络的窄通道可行判断。
• 私有产品介绍本地音频缓存、机身喇叭播放回执与平和的事件提示；管理和操作界面分开，减少手柄输入。
• 场地隔离内容、修订冲突处理、历史内容恢复、持久任务事件；3D场景叠加点位/路线/位置，支持ASCII/binary PCD离线转换和私有导入。

验证：307项Python测试；ARM上307项测试与自有原生扩展编译；本地及独立CI中的连续途经、开门途中改道、持续动态障碍、暂停继续和人工接管共五组实际ROS2/Nav2场景通过，合成模型包络碰撞为零。实际机身输出通道已有自定义介绍音频信号验证；没有进行本版本的真实双足行走测试。

范围：三维展示和二维射线证据不等于全高度三维通行、跨楼层或已识别人群。G12现场交互、整机长期并行负载与新的实机行走结果另行记录；旧反向起步/延迟转向等失败未被本次测试替代。公开包仅含自有通用代码、合成样例和去隐私结果，不含办公室地图录包、厂商私有模型/策略/驱动或凭据。

Baseline V1

Baseline V1：双足 MID-360S 前向导航开发基线

冻结提交：6479e25f5825b5dbce9e6229a33ad5d564b0649a（2026-11-01）。声音及后续产品功能在此基线之后迭代。

已具备：MID-360S/FAST-LIO感知、地图保存与重载、Nav2前向规划、G12 APP实时地图/缩放/选点、一次点击开始、默认位置到达与可选终点朝向、速度调节、E左导航允许/E中暂停/E右及摇杆人工接管、取消、动态障碍绕行与无法绕行停车、诊断与录包。

P2-1006此前有现场监护下的办公室往返及真人阻挡绕行记录。冻结提交包含最新终点与途中规划修复：229项Python测试、实际Nav2合成组件/模型回归和GitHub CI4/4通过，1006实际加载新ARM库、2293点路径预览和25次原生零输出已核验；这个最新修订尚未进行新的真机运动复测。

已知边界保留：反向起步冻结地图回程仍有重规划失败；6/12较大角度长延迟转向模型仍超调；旧终点在当时快照中无完整包络可行朝向。此版本为可追溯的开发基线，不将仿真、预览或零速回执写成全场景真机验收。

公开内容仅为自有通用代码、合成数据及去隐私结论，不包含厂家私有驱动/策略/模型、办公室地图录包或凭据。

v0.4.5-handoff.2 — readiness and continuous pivot checks

Includes the generic readiness-evidence reader and replaced-IMU-mapping guard from PR #5, plus the continuous pivot translation check from PR #6.

When measured translation rises above the existing threshold during a pivot, yaw output now goes to zero and waits for a fresh settling interval before resuming. The new regression fails on the prior code. Seven buffer/adapter tests pass locally and on ARM. A deidentified diagnostic replay reports 30 offending pivot samples before the change and zero afterward; targets were synthesized and no actuator commands were sent.

The 0.15 m/s forward cap, zero lateral navigation request, complete footprint, ground, calibration and source freshness checks remain unchanged. This is a software prerelease. Full biped narrow-door/turn tracking and real autonomous navigation remain unaccepted. After the human confirmed mechanical support and stopped the old gait, the candidate was started through the original startup API. A 233-sample actual standby check passed with zero requests, rejected unready arm and no reconnect auto-arm; full D-policy and autonomous navigation remain unaccepted. The first dependency-start failure is retained, and all normal protection checks remain active. No vendor models, policies, office maps, sensor recordings or credentials are included.