quackd:给 Microduck 一个 LLM 大脑——任意大模型,一个 .duck 文件

项目定位：给小型机器人装上 LLM 大脑

quackd 是一个开源的机器人"大脑守护进程"，把 Pollen Robotics 的 Microduck（25cm、800g 的鸭子造型双足机器人，约 $399）连接到任意大语言模型——Claude、OpenAI、Gemini、Grok，或通过 llama.cpp / vLLM / Ollama / LM Studio 本地运行的开源模型。用户用自然语言下达目标（"找到球并踢它"），LLM 把目标拆解为机器人已有技能（行走、转向、踢球、用喙捡拾、环顾、嘎嘎叫）的正确序列，观察执行结果，持续推进直到任务完成或明确不可能。

项目名字源自机器人自身的守护进程家族（robotd、mediad、padd、tofd），quackd 补上的是缺失的"大脑"层。关键定位是：低层技能与高层目标是两个不同的层——机器人已经知道每个词怎么说，但它不会"对话"；quackd 用 LLM 做规划、机器人自身控制器做执行，把两层连起来。

工作机制：观察-决策-执行闭环 + 硬约束契约

核心循环是：LLM 看相机画面、机器人状态与上一步结果 → 选一个动词（verb）及其参数 → quackd 校验规则（是否允许、预算是否充足、是否需要人工确认）→ 机器人/仿真器用自己的控制器执行技能（走路不是 LLM 的工作）→ quackd 观察新画面与新状态 → 回到 LLM，直到完成或不可能。

可选动词严格限定为真实存在的能力，分三类：

类别	动词	说明
内置	walk sit stand stand_up stop kick grab gaze quack get_frame	机器人出厂自带行为各一个，每个都是机器人控制器执行的"意图"
复合	search_scan walk_to approach_and	纯 Python 写的小闭环；walk_to 以 10Hz 朝相机看到的目标转向，LLM 只说"去球那里"，永远不用说"左转4度"
学习型	（暂无）	v2 路线：用 LLM 编写的奖励训练策略（Eureka/DrEureka 式），注册为普通动词

特别值得学习的是它的安全设计：LLM 无法"说服"系统绕过契约——哪些动词允许、最多多少步、何时必须人工确认、何时中止，全部由 .duck 任务文件强制执行。每次运行都留下 GIF 与完整 transcript（runs/<timestamp>/transcript.jsonl），全程可审计。

.duck 文件：任务即契约

任务文件刻意模仿 SKILL.md 的形态：YAML frontmatter 由 quackd 强制执行（允许动词清单、预算上限、成功判据、中止条件、人格设定），Markdown 正文由模型阅读（任务说明与策略提示）。仓库自带六个起步任务：hello-world（冒烟测试）、find-and-kick（旗舰任务，测试中有 ground truth 校验）、patrol-and-quack、follow-me、fetch（实验性，捡拾开环约 40% 失败率，文件里诚实标注）、flock-kick（多鸭协作）。

Flock 模式：多机器人协作的第一次编排

v0.3 引入多只仿真 Microduck 协作：鸭子们通过进程内消息总线（TASK/BID/CLAIM/ROLE/HB/RESULT 消息，全部记录在 flock.jsonl）通信，用确定性的 Contract Net 拍卖决定由哪只鸭子行动（基于各自相机测距）。首个编排是踢球：群体分片搜索 → 拍卖 → 最近者射门。设计要点：LLM 每次运行最多贡献一次规划调用，每只鸭子仍对自己执行 .duck 契约，结果用仿真 ground truth 而非模型声明来判定——协调机制是任务无关的，鸭群能做什么受技能集合限制，而不是受"球"限制。

工程与诚实度

60 秒即可体验：uvx quackd run find-and-kick --provider fake（无需 API key 的脚本化 pilot）。项目还提供 MCP server（quackd serve-mcp），让 Claude Code / Claude Desktop 交互式驾驶鸭子；quackd doctor 自检环境，quackd validate 校验任务文件。只需 Python 3.11+ 与 uv，默认安装约 250MB，无需 GPU。

README 的诚实度值得称道：明确说明"没有任何东西在真实 Microduck 上跑过"（真机 2026 年圣诞发货）、hero GIF 用的是脚本化 pilot 而非 LLM、本地模型质量未测量、grab 开环不可靠是刻意为之。Roadmap 清晰：真机验证传输层 → 更多 flock 编排 + MQTT 局域网总线 → v1 真机五个任务视频 → v2 学习型动词。

点评

quackd 是"LLM agent harness 落地到物理机器人"的教科书级小样本：动词白名单 + 预算 + 确认门的硬约束契约、任务文件即 SKILL.md 的形态、transcript 全记录、ground truth 判定而非模型自述——这些模式对任何想做机器人对话/目标级控制的团队都有直接参考价值。它同时是 agent harness 与机器人对话两个白名单方向的交叉点。Apache 2.0 协议，欢迎向 ducks/ 目录提交任务文件。