DreamSoul研究
源码与架构 /

Doly 源码架构

固定源码 · 研究快照 2026-10-27Markdown 下载 ↓飞书阅读 ↗
本页为正式研究文档的网页阅读版。固定 GitHub 证据保留;本机研究底稿未发布,相关链接已改为文字说明。原文中的历史发布状态对应研究当时。

源码与访问日期:2026年10月27日。固定仓库 robotdoly/DOLY-DIY,提交 dc6f9c6bd25510710d23b215c553680d37cd8ded,2026-10-15T15:07:48Z。本轮复核默认分支仍指向该提交。研究对象是公开SDK、语言绑定、示例、接口声明及其设备依赖;标准Doly应用与核心控制库没有取得完整实现源文件,本文不替它们虚构内部架构。

架构结论与可见范围

Doly公开部分采用设备本地C++模块库、namespace式控制接口、异步Observer事件、逐功能Python绑定的组织方式。应用直接链接或加载这些库,分别调用轮子、手臂、眼睛、边缘传感器和音频等功能。它不是一个已公开完整实现的机器人Agent框架:仓库没有可供本轮重建默认人格、任务规划、记忆和对话编排的整套应用代码。

主要调用关系是Python应用→pybind11扩展→C++模块API→设备控制库。C++应用可以绕过Python直接调用同一套API。控制结果通过事件回到监听对象或函数指针,再由绑定转换成Python回调。公共接口与语言桥接可见,电机控制算法、事件分发内部容器、底层线程及实时调度策略在二进制边界之后。

这使架构分析必须分三层证据:绑定源码可以证明GIL、互斥锁、引用保活和调用映射;头文件说明API契约、状态枚举、参数和异步事件;共享库内部的锁、控制周期、传感融合与物理完成条件本轮不可见。下文分别使用“实现”“接口声明”“未知”表述,不能将第三层由第一层推导出来。仓库说明、驱动接口

仓库结构、构建与运行边界

目录/材料 实际职责与阅读范围 不能由目录名推出的结论
SDK/include/ 41份公开头文件,按Control、Event、EventListener及公共数据类型分组;本轮重点读Drive、Eye、Arm、Edge、Touch、Helper和音频/IMU/ToF接口 有声明不等于实现源文件在仓库;namespace API也不是每次调用构造一个独立控制器
SDK/lib/ 固定完整树中23个.so,提供设备侧实现 二进制存在不证明适用于任意CPU/系统镜像,也不证明可以独立重编译
SDK/examples/python/<功能>/source/ 每项功能各自的bindings.cpp、CMakeLists和pyproject;产生doly_drive、doly_eye、doly_edge等模块 没有一个已读到的统一Python机器人运行时;跨模块资源和线程协调由应用及库承担
SDK/examples/python/<功能>/example.py 展示停标准service、注册回调、初始化、发动作、查询和清理 示例应用不是默认Doly产品软件,示例的健壮性也不是整机运行保证
SDK/examples/cpp/ 直接链接C++API的示例;包含重复的include目录 不把重复头文件数量算成独立控制模块
SDK/docs/ API生成文档及AI集成FAQ;本轮没有把所有生成HTML视为全数深读 FAQ允许自建AI集成,不等于仓库已经实现指定云模型对话
Electronics/、Printables/等 电路与结构资源,是系统外设与制造上下文 不以硬件资源存在证明SDK二进制内部算法已开放

驱动Python包由scikit-build-core调用CMake;要求Python≥3.9,C++标准20,find_package取得pybind11与Threads,再编译单个bindings.cpp。头文件和库从设备绝对路径 /.doly/libs/sdk/include、/.doly/libs/sdk/lib查找。链接项包括DriveControl、MotorControl、Gpio、Helper、ImuControl、Threads。固定SDK/lib中未见libMotorControl.so,因此构建仍依赖设备系统提供相应材料,而不是只靠仓库头文件即可在普通电脑完成完整驱动构建。pyproject、CMake链接

组件视图

图中框是源码恢复的逻辑组件,扩展模块与SDK库通常在应用进程内装载,不表示分别运行了网络服务。标准Doly service是需要停止的另一个运行主体;它的内部实现没有画入。库内worker来源仅来自公开接口说明,具体线程数量未知。

Doly组件与二进制边界
Doly组件与二进制边界 · 点击查看原图
查看 Mermaid 图源
flowchart TB
  S[标准Doly service:内部未公开] -.停用以避免硬件竞争.-> A
  subgraph L[设备Linux上的开发者应用进程]
    A[Python示例应用]
    C[C++示例应用]
    P[pybind11扩展:doly_drive / doly_eye / doly_edge]
    H[公开Control / Event / Listener API]
    B[设备共享库.so:内部实现不可见]
    A -->|普通函数调用| P
    P -->|ABI调用| H
    C --> H
    H --> B
    B -->|异步事件:内部worker细节未知| P
    P -->|取得GIL后的回调| A
  end
  B --> D[轮子、显示、传感器、GPIO与设备驱动]
  A --> V[Linux相机与ALSA接口]

这套边界的好处是C++能力只需实现一份,Python以薄绑定复用设备能力。代价是应用与SDK ABI、设备镜像和硬件占用方式绑定;Python层没有自动获得一个跨机器的网络协议,也没有通过进程隔离获得逐应用沙箱。AI集成FAQ、驱动绑定

模块API、数据类型与Observer模型

DriveControl不是持有实例字段的C++类,而是单例风格的namespace函数集合。init接收六个IMU偏移;goDistance、goXY、goRotate接收用户命令ID与动作参数;getState、getPosition读取当前模块结果。对应的DriveEvent namespace注册对象监听器或C函数指针,DriveEventListener才是真正可继承的虚函数类。

命令的bool返回表示是否接受;异步onDriveComplete/onDriveError携带uint16_t命令ID。onDriveStateChange只携带DriveType和DriveState,不携带该命令ID。因此应用不能把所有状态事件无条件归给某个并发动作,控制模块也没有在公开接口中暴露每条命令独立句柄。getState是模块状态查询,不是任意历史命令的可持久查询。DriveControl、事件接口

核心UML类/接口视图

带namespace标记的两个框表示API命名空间,不是实例类。继承箭头对应真实C++继承,依赖线表示调用或参数使用;DriveEvent内部保存方式和分发容器未公开,不画成已证实的组合所有权。

Doly核心接口与类
Doly核心接口与类 · 点击查看原图
查看 Mermaid 图源
classDiagram
  class DriveControl {
    <<namespace>>
    +init(offsets) int8
    +goDistance(id, mm, speed, direction) bool
    +getState() DriveState
    +getPosition() Position
    +Abort()
    +dispose(dispose_IMU) int8
  }
  class DriveEvent {
    <<namespace>>
    +AddListener(observer, priority)
    +RemoveListener(observer)
    +AddListenerOnComplete(callback)
    +AddListenerOnError(callback)
  }
  class DriveEventListener {
    +onDriveComplete(id)
    +onDriveError(id, side, type)
    +onDriveStateChange(type, state)
  }
  class PyDriveEventListener {
    +onDriveComplete(id)
    +onDriveError(id, side, type)
    +onDriveStateChange(type, state)
  }
  class Position {
    +float head
    +int x
    +int y
  }
  DriveEventListener <|-- PyDriveEventListener
  DriveEvent ..> DriveEventListener : 回调接口
  DriveControl ..> Position : 返回估计位置
  DriveControl ..> DriveEvent : 声明的异步事件协作

Python类式监听器由PyDriveEventListener桥接虚函数,它先取得GIL,再调用PYBIND11_OVERRIDE。绑定同时把这些方法暴露成snake_case名称,而宏中使用C++camelCase虚函数名;Python子类的具体重写名称需要按pybind查找行为确认。当前驱动示例采用静态函数回调,不是对类式重写路径的运行验证。真实继承与绑定

Eye模块沿用Control/Event/Listener分离,但对象内容更丰富。EyeControl以namespace函数选择虹膜、眼睑、背景、注视位置和预设动画;EyeEventListener提供开始、结束和中止。VContent是真实的数据容器类,持有多帧原始字节、尺寸、活动帧、源路径和循环/速率参数;Eye绑定把VContent引用的地址交给C++接口。绑定未在相应set_iris_image等入口添加可见的keep_alive策略,库内部是否复制图像或保留指针不可见,因此不能宣称Python临时对象释放后仍一定安全。VContent、图像传参

启动、动作与异步完成的时序

驱动example.py先尝试读取版本,再调用helper.stop_doly_service以避免同一硬件库被标准应用同时使用。停止失败直接返回;成功后注册三个回调,再drive.init。如果初始化成功,发送id=1、100mm、速度50的前进动作,随后每50ms查询DriveState,非Running后读取估计位置并dispose。它没有一个公开的统一RobotRuntime来承包以上生命周期;示例自身是流程拥有者。

值得注意的是,示例没有使用go_distance的bool返回值判断接受与否,也没有在整个动作过程外层使用try/finally。动作拒绝、回调异常、用户中断后是否完整清理,不能由正常示例流程推断。本文记录这些结构边界,未将其执行为真实设备故障测试。完整驱动示例

Doly动作与回调时序
Doly动作与回调时序 · 点击查看原图
查看 Mermaid 图源
sequenceDiagram
  participant A as Python示例应用
  participant H as doly_helper
  participant P as doly_drive绑定
  participant C as C++Control/Event库
  participant T as trampoline
  A->>H: stop_doly_service()
  H-->>A: 状态码
  A->>P: on_complete/on_error/on_state_change
  P->>C: 注册函数指针
  A->>P: init(IMU偏移)
  P->>C: DriveControl::init
  C-->>A: 初始化结果
  A->>P: go_distance(id=1, 100mm, speed=50)
  P->>C: goDistance(...)
  C-->>A: 是否接受(非完成)
  Note over C: 内部执行器和worker实现不可见
  C-->>T: 完成或错误事件(id)
  T->>T: gate检查、GIL、锁内复制回调
  T-->>A: 锁外调用Python函数
  loop 示例轮询状态
    A->>P: get_state()
    P->>C: getState()
    C-->>A: DriveState
  end
  A->>P: dispose(True)
  P->>C: 移除监听器,再dispose

异步事件的位置来自API契约,实际worker怎样检测完成不公开;图不表示回调一定在轮询退出之前或之后。Position头文件仅明确head为角度,XY及部分符号方向留给实现,不能把任意XY值均解释为已经测准的毫米坐标。Position声明

绑定层的并发、引用与销毁

绑定真正承担的是跨语言生命周期问题。模块静态变量保存Python回调及注册标记,g_cb_mutex保护替换。静态函数回调被非Python线程触发时,trampoline先看atomic gate,再取得GIL,在锁内复制一个强引用,离开互斥锁后才调用Python。对象监听器的虚函数桥则直接取得GIL,没有同一个gate检查。静态函数回调可以重入API,而不会因始终持有注册表互斥锁立刻自锁;但GIL仍使Python段相互串行,不能把库异步等同于Python回调并行执行。

函数回调槽每个事件类型只有一个,后注册的函数替换之前的引用。对象监听器则保存在g_py_listeners强引用向量,直到显式remove或clear,防止Python回收对象而C++继续使用裸指针。这是模块全局注册表,并非每次init创建一套独立实例或为每个用户会话建立隔离。全局状态与引用、listener保活

safe_call捕获Python error_already_set并调用PyErr_Print,使静态函数回调的这类Python异常不继续穿过该catch边界。catch中未见先恢复被捕获异常,本轮未验证日志是否正确输出,不能保证打印了该异常。类式PYBIND11_OVERRIDE走另一条代码路径,不能把safe_call的捕获行为推广给所有监听方式。源码也没有提供Python事件失败向控制命令终态回传的统一封装。trampoline与safe_call

clear_listeners_impl先关gate,移除静态回调并清引用,再将对象监听器向量移出锁外,逐一从C++注册表注销。drive.dispose随后才调用库dispose。可见代码没有证明此操作join了所有已经在途的库worker;gate检查也发生在获取GIL之前。因此其目标是减少迟到回调,不能写成已经形式化保证解释器销毁无竞态。清理顺序

可见生命周期的差异

Drive绑定只在模块加载时把g_callbacks_enabled设true;本轮已读init和静态回调注册实现没有重新置true,clear或dispose会置false。Eye绑定则在init和注册回调时显式置true。因此clear/dispose后再次init并注册静态函数,不会重新打开Drive静态回调gate。该差异不表示Drive底层无法重新初始化,也不表示对象监听器受gate阻断。不能仅因为各模块都叫init/dispose,就假定静态回调恢复行为相同。这是固定源码的静态差异,未加载.so作运行验证。Drive注册和初始化、Eye重新启用

下图仅表示静态函数回调的生命周期,不覆盖对象监听器路径。

Doly静态函数回调生命周期
Doly静态函数回调生命周期 · 点击查看原图
查看 Mermaid 图源
stateDiagram-v2
  [*] --> GateOn: 扩展模块加载时true
  GateOn --> Registered: 注册静态函数回调
  Registered --> Callback: 库事件进入trampoline
  Callback --> Registered: 锁外调用Python后返回
  GateOn --> Detached: clear_listeners
  Registered --> Detached: gate=false及注销
  Detached --> Disposed: drive.dispose调用底层dispose
  note right of Detached
    这是绑定代码恢复的分析状态
    不是SDK原生状态枚举
    Drive未见重新置true分支
    Eye的init和注册可以置true
  end note

另一个不对称点是EyeControl头文件没有底层dispose;Python暴露的eye.dispose只清回调和对象监听器,注释明确如此。它不等于停止显示渲染器或释放全部LCD资源。Drive dispose则确实继续调用DriveControl::dispose,Edge dispose继续调用EdgeControl::dispose。生命周期方法同名,但作用域不同。Eye dispose、Edge dispose

传感事件、显示与音频子系统

Edge模块将IR传感器状态与GapDirection事件暴露给应用,enable_control与disable_control用于启停传感监听。Touch、ToF、IMU也各自给状态或事件接口。公共目录体现的是横向硬件能力分组,而不是一个公开行为树将所有传感器统一变成机器人情绪。边缘事件与DriveControl属于不同API;不能从它们同时存在推出每次gap都会在固定时限内自动制动。

Eye的图像与预设动画共享显示模块,SoundControl提供异步文件播放和Abort,TtsControl声明基于Piper并以produce生成输出。TTS与播放不是同一生命周期:produce阻塞完成文件生成,SoundControl.play负责后续播放,声音模型、AEC、唤醒及对话轮次没有在这些API中自动组合。SoundControl、TtsControl

FAQ说明麦克风可经ALSA读取,标准软件使用的软件AEC未通过SDK开放。相机示例读取图像帧,应用可以本地处理或自建网络管线;官方FAQ提出的“接OpenAI/Gemini”是扩展方案,本文没有把它当成现成应用类图,也没有把提及某服务画成仓库默认后端。音频与AEC边界

Doly传感与应用回路
Doly传感与应用回路 · 点击查看原图
查看 Mermaid 图源
sequenceDiagram
  participant A as Python传感示例
  participant E as doly_edge绑定
  participant L as EdgeControl/Event库
  participant H as IR硬件
  A->>E: 注册on_gap_detect
  A->>E: init与enable_control
  E->>L: 调用公开API
  Note over L,H: 库内读取线程与采样实现未公开
  H-->>L: 传感输入
  L-->>E: on_gap_detect_trampoline(direction)
  E->>E: gate、GIL、复制callback
  E-->>A: Python回调(direction)
  Note over A: 是否进一步发轮子动作属于应用逻辑
  A->>E: dispose
  E->>L: 注销事件并dispose

配置、持久化与异常语义

Helper公开readSettings与getImuOffsets,表明平台有设置文件和校准值来源。头文件给出设置文件不存在、XML解析失败和读取偏移失败的返回码;路径、写入协议、原子性、版本迁移和损坏恢复实现没有公开。不能由“有Helper”推导完整可恢复配置系统。Helper契约

驱动错误枚举有ABORT、FORCE、ROTATE、MOTOR,状态枚举是RUNNING、COMPLETED、ERROR。Abort接口说明允许终止并可能继续发事件,但底层何时制动、是否等待电机停止、错误后的当前位置估计是否可信,均不能从头文件保证。这里可恢复的是公开状态合同,而不是控制器内部完整状态机。

同样,没有公开的跨子系统事务:一次“转头同时前进并说话”需要上层自行处理各模块的接受/拒绝与部分失败。事件ID帮助关联单个模块动作,不自动提供跨模块取消、回滚或断电恢复。主线程若收到KeyboardInterrupt,正常示例未展示统一清理控制器;Python绑定的dispose也只是各模块边界上的资源处理。

基本架构方案与取舍

从公开代码可以归纳出三种基础结构:namespace式硬件模块API提供稳定门面;Control与Event/Listener形成命令/反馈分离的Observer协作;pybind11承担外观适配及跨语言对象生命周期。它们共同让同一设备能用C++或Python开发,也把系统镜像和ABI依赖留在设备端。

这套方案的透明度集中在边界,不在算法内部。应用能够控制动作并订阅事件,但对底层控制周期、阻力检测、线程优先级与传感融合只能依赖文档或黑盒验证。图中的二进制框必须保留,不能为了让架构看起来完整而补上猜测的PID、任务调度器、人格系统或模型路由器。

跨语言层有可读的工程细节,也有不统一的生命周期:static函数回调与类监听器分两路;Drive、Eye、Edge的清理和重新启用并不一致;异步ID和同步返回码需要应用共同解释。这些决定使用者怎样组织可靠应用,但不构成本文要为其他公司设计的新架构。

阅读深度、图示与References

本轮保存并针对性阅读31份新增/复核源码和文档:Drive控制/事件/监听器及绑定、Eye内容/事件/绑定、Edge绑定、Touch事件、Helper、Arm、IMU/ToF/Sound/TTS接口、Python/C++示例和构建配置。还核对固定完整仓库树,区分920个文件中的API生成文档、二进制、制造资料和源文件;未将生成HTML逐页计为深读。

图示是依据固定代码重建的组件、类、时序和生命周期视图。类图中的namespace和推导状态已标注;二进制内部未画。Mermaid源与渲染图在同目录“图”中,源码路径/blob及获取结果见 源码清单(研究底稿,未随本专区发布)。该清单另记录一个未取得的通用CMake路径,未拿它作证据。

未加载库、未运行标准service、未编译绑定、未连接硬件或模型;回调关停差异和异常分支是静态源码发现,不是已经复现的设备故障。当前自有SDK材料采用非商业条款,见 固定许可。许可只在此记录,不替代上面的架构分析。