> 网页发布副本：本机研究底稿未随站点发布；固定源码证据保持不变。

源码与访问日期：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契约、状态枚举、参数和异步事件；共享库内部的锁、控制周期、传感融合与物理完成条件本轮不可见。下文分别使用“实现”“接口声明”“未知”表述，不能将第三层由第一层推导出来。[仓库说明](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/README.md#L9)、[驱动接口](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/include/DriveControl.h#L7)

# 仓库结构、构建与运行边界

| **目录／材料** | **实际职责与阅读范围** | **不能由目录名推出的结论** |
|---|---|---|
| `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](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/source/pyproject.toml#L1)、[CMake链接](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/source/CMakeLists.txt#L1)

## 组件视图

图中框是源码恢复的逻辑组件，扩展模块与SDK库通常在应用进程内装载，不表示分别运行了网络服务。标准Doly service是需要停止的另一个运行主体；它的内部实现没有画入。库内worker来源仅来自公开接口说明，具体线程数量未知。

![Doly组件与二进制边界](<%E5%9B%BE/Doly%20%E7%BB%84%E4%BB%B6.png>)

```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](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/docs/AI_Integration_Developer_FAQ.md#L3)、[驱动绑定](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/source/bindings.cpp#L173)

# 模块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](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/include/DriveControl.h#L79)、[事件接口](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/include/DriveEventListener.h#L58)

## 核心UML类／接口视图

带`namespace`标记的两个框表示API命名空间，不是实例类。继承箭头对应真实C++继承，依赖线表示调用或参数使用；DriveEvent内部保存方式和分发容器未公开，不画成已证实的组合所有权。

![Doly核心接口与类](<%E5%9B%BE/Doly%20%E7%B1%BB%E5%9B%BE.png>)

```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查找行为确认。当前驱动示例采用静态函数回调，不是对类式重写路径的运行验证。[真实继承与绑定](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/source/bindings.cpp#L55)

Eye模块沿用Control/Event/Listener分离，但对象内容更丰富。EyeControl以namespace函数选择虹膜、眼睑、背景、注视位置和预设动画；EyeEventListener提供开始、结束和中止。VContent是真实的数据容器类，持有多帧原始字节、尺寸、活动帧、源路径和循环／速率参数；Eye绑定把VContent引用的地址交给C++接口。绑定未在相应set_iris_image等入口添加可见的keep_alive策略，库内部是否复制图像或保留指针不可见，因此不能宣称Python临时对象释放后仍一定安全。[VContent](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/include/VContent.h#L29)、[图像传参](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/EyeControl/source/bindings.cpp#L469)

# 启动、动作与异步完成的时序

驱动example.py先尝试读取版本，再调用helper.stop_doly_service以避免同一硬件库被标准应用同时使用。停止失败直接返回；成功后注册三个回调，再drive.init。如果初始化成功，发送id=1、100mm、速度50的前进动作，随后每50ms查询DriveState，非Running后读取估计位置并dispose。它没有一个公开的统一RobotRuntime来承包以上生命周期；示例自身是流程拥有者。

值得注意的是，示例没有使用go_distance的bool返回值判断接受与否，也没有在整个动作过程外层使用try/finally。动作拒绝、回调异常、用户中断后是否完整清理，不能由正常示例流程推断。本文记录这些结构边界，未将其执行为真实设备故障测试。[完整驱动示例](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/example.py#L29)

![Doly动作与回调时序](<%E5%9B%BE/Doly%20%E5%8A%A8%E4%BD%9C%E6%97%B6%E5%BA%8F.png>)

```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声明](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/include/Helper.h#L21)

# 绑定层的并发、引用与销毁

绑定真正承担的是跨语言生命周期问题。模块静态变量保存Python回调及注册标记，g_cb_mutex保护替换。静态函数回调被非Python线程触发时，trampoline先看atomic gate，再取得GIL，在锁内复制一个强引用，离开互斥锁后才调用Python。对象监听器的虚函数桥则直接取得GIL，没有同一个gate检查。静态函数回调可以重入API，而不会因始终持有注册表互斥锁立刻自锁；但GIL仍使Python段相互串行，不能把库异步等同于Python回调并行执行。

函数回调槽每个事件类型只有一个，后注册的函数替换之前的引用。对象监听器则保存在g_py_listeners强引用向量，直到显式remove或clear，防止Python回收对象而C++继续使用裸指针。这是模块全局注册表，并非每次init创建一套独立实例或为每个用户会话建立隔离。[全局状态与引用](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/source/bindings.cpp#L20)、[listener保活](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/source/bindings.cpp#L216)

safe_call捕获Python error_already_set并调用PyErr_Print，使静态函数回调的这类Python异常不继续穿过该catch边界。catch中未见先恢复被捕获异常，本轮未验证日志是否正确输出，不能保证打印了该异常。类式PYBIND11_OVERRIDE走另一条代码路径，不能把safe_call的捕获行为推广给所有监听方式。源码也没有提供Python事件失败向控制命令终态回传的统一封装。[trampoline与safe_call](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/source/bindings.cpp#L43)

clear_listeners_impl先关gate，移除静态回调并清引用，再将对象监听器向量移出锁外，逐一从C++注册表注销。drive.dispose随后才调用库dispose。可见代码没有证明此操作join了所有已经在途的库worker；gate检查也发生在获取GIL之前。因此其目标是减少迟到回调，不能写成已经形式化保证解释器销毁无竞态。[清理顺序](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/source/bindings.cpp#L129)

## 可见生命周期的差异

Drive绑定只在模块加载时把g_callbacks_enabled设true；本轮已读init和静态回调注册实现没有重新置true，clear或dispose会置false。Eye绑定则在init和注册回调时显式置true。因此clear/dispose后再次init并注册静态函数，不会重新打开Drive静态回调gate。该差异不表示Drive底层无法重新初始化，也不表示对象监听器受gate阻断。不能仅因为各模块都叫init/dispose，就假定静态回调恢复行为相同。这是固定源码的静态差异，未加载.so作运行验证。[Drive注册和初始化](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/DriveControl/source/bindings.cpp#L250)、[Eye重新启用](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/EyeControl/source/bindings.cpp#L223)

下图仅表示静态函数回调的生命周期，不覆盖对象监听器路径。

![Doly静态函数回调生命周期](<%E5%9B%BE/Doly%20%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F.png>)

```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](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/EyeControl/source/bindings.cpp#L517)、[Edge dispose](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/examples/python/EdgeControl/source/bindings.cpp#L274)

# 传感事件、显示与音频子系统

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](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/include/SoundControl.h#L35)、[TtsControl](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/include/TtsControl.h#L37)

FAQ说明麦克风可经ALSA读取，标准软件使用的软件AEC未通过SDK开放。相机示例读取图像帧，应用可以本地处理或自建网络管线；官方FAQ提出的“接OpenAI/Gemini”是扩展方案，本文没有把它当成现成应用类图，也没有把提及某服务画成仓库默认后端。[音频与AEC边界](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/docs/AI_Integration_Developer_FAQ.md#L70)

![Doly传感与应用回路](<%E5%9B%BE/Doly%20%E4%BC%A0%E6%84%9F%E6%97%B6%E5%BA%8F.png>)

```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契约](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/SDK/include/Helper.h#L63)

驱动错误枚举有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材料采用非商业条款，见 [固定许可](https://github.com/robotdoly/DOLY-DIY/blob/dc6f9c6bd25510710d23b215c553680d37cd8ded/LICENSE.txt#L8)。许可只在此记录，不替代上面的架构分析。
