企业官网建设流程全解析

• 机器人
• 嵌入式
• 强化学习
• 人工智能
• 智能硬件
• 计算机视觉
• 音视频

本文是 microduck 开源仓库（一只运行强化学习策略的双足小鸭子机器人）官方文档体系（docs/）的完整地图，服务于两类读者：拿到实体机器人想立刻驾驶的用户，以及准备深入守护进程内部做改造的开发者。读完本文，你将掌握仓库文档的分区逻辑（使用手册 / 设计文档 / 项目记录 / 想法暂存区）、每份文档解决的具体问题、如何正确引用"机制归属"文档以避免文档间互相矛盾，并能顺着索引直达 docs/README.md 中列出的每一份可操作指南。

文档体系的总设计：多扇前门与单一事实来源

microduck 的 docs 目录不是一份文档的堆砌，而是一套经过刻意设计的知识路由系统。从 docs/README.md 本身可以看到它的三层原则：

第一层：多扇前门，按读者身份分流。

• 根 README.md 是项目的"正门"——它回答"microduck 是什么"：约 25 cm、800 g 的双足机器人，主板为 Rockchip RK3566，由一组 Rust 守护进程驱动，50 Hz 控制回路用神经网络策略带动 15 个舵机（README 中明确说明 "This repo is the duck's brain"）。手上已经有机器人的读者，README 直接指向速查表。
• docs/robot/cheatsheet.md 是"驾驶门"——机器人在你面前，想立刻驱动它，从这里开始。
• docs/faq.md 是另一扇前门，面向在鸭子之上做开发的人：模型太重跑不动怎么办、如何把摄像头接进自己的程序、为什么 Space 连不上。它的 FAQ 回答模式不是讲机制，而是指路——"设计文档说机制怎么运作；这里告诉你该伸手拿哪一块"（原文档原话）。

第二层：机制单一归属（One page owns a mechanism）。

这是整个 docs 体系最核心的写作契约：一份机制只有一页负责完整讲解，其余页面提到它时只说一句话并指过去。原文档用一个真实事故解释了为什么：

A fact written down in six places drifts in six directions……——正是这样，六份文档都承诺updaterd和btd会在下次重启前保留旧二进制，而实际两个发布之后它们早已不这么做了，包括正在排查这个问题的人会读的那两页。

因此文档间出现矛盾时，不拥有该机制的那一页才是 bug，而不是机制归属页。这个原则贯穿 docs/design/ 全部设计文档，也让开发者可以放心引用：architecture.md是服务拆分与 IPC 契约的归属页，updater-design.md是更新引擎的唯一权威。

第三层：按文档生命周期分区。

docs 目录被刻意分成四类，各自有明确的新鲜度预期：

• robot/—— 使用手册，随版本演进；
• design/—— 设计文档，很少改动；行为与设计文档不一致时，文档是 bug；
• project/—— 项目记录，有日期、故意过期，描述某个时刻的状态而非永久真理；
• ideas/—— 想法暂存区，还没设计成文的思考，先写下来以免丢失，也避免被误当成决策。

robot/——你有一台机器人：八份操作手册

入门路径：cheatsheet 是机器上最重要的文档

docs/robot/cheatsheet.md 的定位是"在机器人上运行的robotctl"，并且它遵守一条诚实原则：每条命令都取自发布分支的--help，而非记忆。它对权限划分有清晰约定：

• 只读命令不需要特权；
• 任何改变机器人的操作需要sudo（或configd的--allow-user/--allow-group、updater.toml里的allow_uids/allow_gids）。

它给出的第一个命令是robotctl version——对比"每个守护进程实际运行的是哪个版本"与"安装的是哪个版本"，因为更新后仍在服务旧代码的守护进程，看起来和刚修好的 bug 一模一样。其次是robotctl health，硬件与软件一份报告，机器人不健康或不可达时以非零退出码退出，因此可以被脚本当作门禁；--json用于生成支持工单。这两个命令恰好对应 src/robotctl 的实现以及各守护进程启动时写入/run/<service>/identity.json的运行版本机制（见 docs/design/architecture.md §8.3）。

模拟与开发：没有实体鸭子也能工作

scripts/duck-sim 让没有机器人在手边的开发者用真实守护进程对着 MuJoCo 中的刚体跑仿真——这是 docs/robot/simulation.md 的核心主题，而 docs/design/simulation.md 则从设计侧说明"守护进程与身体之间的接缝在哪、身体协议是什么、假无线电如何工作"。robot/与design/各有一份 simulation 文档，正是"使用手册 + 设计文档"双视角的典型组合。

design/——你在改守护进程：机制归属表

这份表格是 docs 体系的权威分配表：一个事实属于哪一页，其他页面就只能一句话带过并指向它。

架构事实：七守护进程与"三类生存者"

结合 docs/design/architecture.md 可以理解这份表的重量级内容：单板上七个守护进程通过Unix socket 上的 JSON-RPC 2.0（NDJSON，一行一个对象）通信，robotd是唯一碰机器人的进程——15 个舵机和 IMU 共享一条串行总线，50 Hz 控制回路独占它，客户端只能发送intent（"以这个速度走"、"看向那里"），安全层由robotd决定什么可以执行。源码侧，robotd/src、configd/src、updater/src、btd/src、mediad/src、tof/src、padd/src 与架构中的服务一一对应。

架构中一条反复出现的不变量是：btd、configd、updaterd在robotd死亡时仍须存活——它们是恢复路径，因为"控制回路起不来的机器人，恰恰是最需要被重新配置、更新或回滚的那台"。这也是为什么配置放在configd而非robotd：给坏掉的机器人配 wifi，正是它坏了时最需要的事。这一设计在文档表中体现为app-path-design.md与boot-recovery-net.md各自负责的机制边界。

更新与策略：两个独立机制的所有权页

• docs/design/updater-design.md 是更新引擎唯一权威：发布以整目录落到/opt/robot/daemon/releases/<version>/，updaterd校验签名、移动current符号链接、重启单元、然后向robotd询问健康；不健康就把旧发布放回去。该设计被 deploy/ 与 updater/ 的源码（updater/src/verify.rs、updater/src/engine.rs）实现。
• docs/design/policy-channel-design.md 是策略通道的唯一权威，其实操契约则在 docs/policy-manifest.md：一份位于.onnx旁边的manifest.json的每个字段都由它定义（kind决定谁结束策略——episodic/perpetual/scripted；command.encoding决定守护进程喂给它什么——constant/phase/posture_flag）。索引文档特意指出："设计文档给出理由并指向它"，这正是"一页归属机制、其他页一句话指过去"的实例。

project/——你在运行这个项目：有日期的现场记录

这些是有日期的记录而非参考资料，描述的是某个时刻的状态，故意过时。

这类文档的价值在于它们是真实发生过的工程决策记录，比如install-path-gap.md明确指向它教会的规则（updater-design.md§9.1），形成"事故 → 规则"的闭环，而不是停留在口号层面。

ideas/——还没设计完：思考的蓄水池

它存在的理由正如索引原文所述："一件即将需要设计文档的事，在拥有它之前先写下来，这样思考不会丢失，也不会被误当成决策。"这份文档与仓库里 robotd/src/chorale.rs、robotd/src/theremin.rs 以及 sounds/src 的合唱/特雷门实现相互呼应，是可以追踪"想法如何沉淀为机制"的起点。

Elsewhere：文档体系之外的三处补充

其中 deploy/README.md 值得单独说明：它描述的是属于镜像而非单个服务的 OS 级配置——updater.toml（客户端机器人携带的配置，安装到/etc/robot/updater.toml）、trusted_keys/（发布公钥，即信任锚）、journald.conf.d/10-robot.conf（日志持久化与容量上限）。它还记录了一个实测发现：该镜像的/var/log是 zram 设备，Storage=persistent实际是内存中的目录，断电会丢失最近日志——因此/var/lib下的更新历史是唯一持久记录，这正是 docs/design/architecture.md §8.2 如此设计的原因。

如何正确使用这份文档地图

综合原索引文档的组织意图，实际使用可以遵循三条经验法则：

1. 按身份找门：有机器在手 → docs/robot/cheatsheet.md（机器上第一条命令永远是robotctl version）；构建自己的程序接入鸭子 → docs/faq.md；要改守护进程 → 查 docs/design/ 的机制归属表。
2. 按机制引用：引用一个机制时，永远指向它的归属页——更新相关引 docs/design/updater-design.md，策略通道引 docs/design/policy-channel-design.md 与 docs/policy-manifest.md，服务架构引 docs/design/architecture.md。
3. 区分新鲜度：project/的文档有日期、可能已过时；行为与设计文档冲突时，是文档错了而不是代码错了；ideas/是想法不是决策。

这套"多门分流 + 单一机制归属 + 生命周期分区"的文档架构，让一个同时承载实体硬件操作手册、系统设计文档、工程复盘记录和想法沉淀的仓库，保持了可导航、可引用、可纠错的一致性——这正是从 docs/README.md 出发能够掌握的最大价值。

• 机器人
• 嵌入式
• 强化学习
• 人工智能
• 智能硬件
• 计算机视觉
• 音视频