DuckKing

让用户在购买硬件之前，先在浏览器里了解 MicroDuck、体验灵矽语音交互。通过语音和按钮控制仿真小鸭，完成踢球、搬运、前滚翻、轮滑、四鸭演出，还能对比官方步态基线与 PPO 平衡策略。支持服务器离线识别优先、真实灵矽语音、独立房间、十三幕自动演示和十项互动工坊任务。

在线体验 · 演示场景 · 物理实验室 · 部署记录

本文功能截图与功能导览采自公网发布 62c6784（2026-11-01）。决赛主片结合本地候选版本的灵矽实连、离线识别实录，以及公网的转盘对照、PPO 训练记录和测试覆盖率，各章记录来源与版本；第 11 幕实录保留录制时的本地来源，当前发布状态以部署记录为准。录制、结果与版本 · 媒体来源。历史素材保留各自日期。

当前工作台使用官方模型外观，动作由本项目脚本驱动，属于动画预览。物理实验室与演示剧场使用真实 MuJoCo CPU + 官方 ONNX 策略；另有独立的官方 robotd / MuJoCo 适配。三条路径分别标识，连接失败会明确报错。项目目前是软件仿真，没有实体机器人验收。

赛后外观更新（2026-11-01）： 首页、物理实验室、演示剧场与互动工坊支持四种官方配色：奶油白 Cream、石墨灰 Graphite、薰衣草紫 Lavender、天空蓝 Sky。画面左下角可换色，多鸭场景先选择鸭子；默认 A/B/C/D 分别对应这四种颜色，走动、换位与重置不会交换身份。外壳、金属关节和镜头使用不同材质及环境反射；选择保存在当前浏览器，只影响外观，不改变运动策略或接触物理。四鸭共享模型网格，换色无需重新下载模型。

竞赛主演示： 灵矽实连决赛演示 · 章节、实测与复录说明。第 11 幕选择“灵矽实连 · 预录指令”与《两只老虎》，随后介绍真实离线识别、转盘 PPO 对照、CPU 训练记录、两页使用统计和绑定提交的后端测试覆盖率；音乐为浏览器本地合成。另有 功能导览 与 2026-10 竞赛视频存档。

商业价值与产品设计

先体验，再决定是否购买。 MicroDuck 官方预售价为 399 美元，未含税费和运费（2026-10-27 查阅官方商店）。DuckKing 为有兴趣但尚未购买硬件的用户提供体验窗口：不用先采购、组装或部署开发环境，就能尝试中文语音指挥、临场改令和多鸭演出，判断自己想用它做什么。

产品设计围绕“看一幕 → 亲口指挥 → 改变结果 → 了解能力边界”：自动演示负责引起兴趣，真实灵矽与物理场景负责让用户亲手尝试，源码和说明帮助开发者继续探索。官方已有仿真器；本项目增加语音接入、场景编排和体验统计，没有完成实体硬件复刻，也不表示官方购买后即可获得同样的全部玩法。

商业价值首先是降低了解与试用成本、减少购买预期偏差；对硬件和灵矽生态的转化贡献仍需用户验证，当前没有销售合作、支付或购买归因。完整的目标用户、体验路径、功能边界、验证指标和后续优先级见 商业价值与产品设计。

开始开发后，可继续复用部分语音与动作软件，再逐步接上实体硬件；模块复用、麦克风／扬声器边界与待实施的接入步骤见 从仿真到实体。目前没有实机验收，也不能将全部场景通过切换地址直接移植。

Related MCP server: AI Voice Assistant MCP Server

从哪里开始

页面只列出当前访客自己创建的房间，按匿名浏览器会话隔离，无需登录。同一浏览器的多个标签页可使用自己的房间；其他浏览器即使知道编号或链接，也不能读取状态、发送动作或连接语音。默认最多 10 个房间、4 个同时加载的 MuJoCo 世界；空闲 5 分钟后回收，再分配时清空上一位访客的动作、诊断和统计视图。每个房间一次只允许一个页面占用语音。新增房间的云端设备需由管理员预先独立绑定；显式 robotd 后端只开放房间 1。

软件架构

围绕“复刻 Micro Duck，并通过灵矽语音交互”的题目，当前交付了从浏览器语音到动作执行、物理反馈与体验统计的软件链路。实体硬件复刻、传感器接入与实机验收仍未完成。

flowchart TB
    User["浏览器 · 手机 / 电脑<br/>语音、动作、十三幕演示"]
    Gateway["HTTPS 入口 /duckking/<br/>ai_gateway 固定转发"]
    App["DuckKing · FastAPI<br/>动态房间、语音会话、任务编排"]
    Local["服务器离线识别<br/>SenseVoiceSmall + 整句规则"]
    Cloud["灵矽云端<br/>识别、对话、MCP 工具、语音回复"]
    Motion["有界动作控制<br/>限时、取消、去重、实际结果"]
    Preview["首页预览<br/>官方外观 + 脚本动画"]
    Physics["物理场景<br/>MuJoCo + 官方 ONNX 策略"]
    Robotd["可选官方 robotd<br/>Unix socket → MuJoCo body"]
    Evidence["可追溯数据<br/>使用体验、逐轮诊断、部署与覆盖率"]
    User <-->|"HTTPS API / 有序音频与状态帧"| Gateway
    Gateway <--> App
    App -->|"本地优先"| Local
    App <-->|"云端模式"| Cloud
    Local -->|"整句命中"| Motion
    Local -->|"未命中 / 识别失败，原录音转交一次"| Cloud
    Cloud <-->|"MCP 调用 / 执行结果"| Motion
    App -->|"按钮 / 剧本"| Motion
    Motion --> Preview
    Motion --> Physics
    Motion --> Robotd
    App --> Evidence
    User -->|"浏览器端计时"| Evidence

公网音频与状态帧经 HTTPS 长轮询转到真实后端 WebSocket，本地可直连 WebSocket。各房间隔离语音与动作；物理场景按需加载。三个动作后端显式区分，预览不计算接触，仿真也不等于实体硬件。灵矽回复、本地确认和预录音乐分别标记。

架构设计文档包含部署图、语音时序、模块输入输出、故障边界和接口规格；模块分工与验收对应负责人和测试入口。两者共同组成竞赛的“架构设计文档（包含模块规格、分工）”。

本地运行

需要 Python 3.12+、uv 和 Node.js 22.12+。默认 Python 3.12 由 uv 准备。

git clone git@github.com:zhoutingunl/DuckKing.git
cd DuckKing
scripts/setup_local.sh
scripts/run_local.sh

打开 http://127.0.0.1:8765/。初始化脚本按锁文件安装依赖、获取固定版本官方模型与策略并构建前端；不会创建灵矽账号或连接云端。模型缺失会明确报错。启动保持前台运行，Ctrl+C 退出；可传 --port 8766。

开发前端时，保持后端运行，在另一个终端执行 cd frontend && npm run dev，访问 http://127.0.0.1:5173/。Python 修改后重启后端；8765 页面需要重新构建才显示前端修改。完整步骤见 本地开发指南。

语音：本地优先与灵矽云端

首页和物理实验室都支持“本地优先 / 灵矽云端”。本地优先使用服务器上的 sherpa-onnx + SenseVoiceSmall INT8，手机浏览器无需安装模型。整句动作命中后直接执行并用短预录语音、文字确认；问句、未匹配或识别失败时，把本轮原始录音一次性交给真实灵矽。否定句和未知后缀不会先执行已认识的半句；本地动作一旦开始，失败后不会再交云端重复执行。

本地启用离线识别：

scripts/setup_local_asr.sh
# 终端一
uv run --frozen --no-sync duckking-asr
# 终端二
DUCKKING_LOCAL_ASR=1 scripts/run_local.sh

worker 只监听 127.0.0.1:8768。浏览器选择“本地优先”，点“启用语音”，按住说话、松开执行。物理实验室先加载对应场景，例如动作练习场中说“前滚翻，再打个哈欠”或“向后退，再向左挪，再向右挪”。本地命中无需先连接云端；回退仍需要配置好的灵矽设备与网络。最多六个动作、总时长 20 秒，不是通用自然语言规划器。

真实灵矽连接需要原生 Opus：macOS 使用 brew install opus；Ubuntu 使用 sudo apt-get install libopus0。已有平台 API Key 时，将原始 Key 单独放在仓库外 ~/.secrets/lingxi：

chmod 600 ~/.secrets/lingxi
uv run duckking-setup --key-file ~/.secrets/lingxi
# 需要第二路独立语音时，另行绑定房间 2
uv run duckking-setup --room 2

初始化显式创建或复用专用 DuckKing 智能体并绑定设备，不在页面加载时执行。也可按页面激活码在灵矽控制台绑定。手工设备凭证填写到 ~/.secrets/duckking.env，参考 .env.example，权限设为 600；设备 token 不等于平台管理 Key。新增工具后重新连接语音；已有中文智能体可用 uv run duckking-setup --sync-prompt 备份并同步工具提示词。多语言配置和同步使用下方的 --language-profile，同时验证语种、音色和自动识别语言开关。

按地区默认语言：美国/英国→英语，欧洲（非英国）→法语，其他→中文。 地区查询使用服务器本地 IP 库，代理头仅在来源命中 DUCKKING_GEO_TRUSTED_PROXIES 时受信任；未核实代理时回退中文。十个页面共用中英法界面，覆盖动态状态、提示、动作标签与训练说明；用户转写和真实云端回复保留原文。顶部最右「语言」同时选择界面与下一次灵矽会话的默认回答语言，选择后原地更新界面，保留房间、模型和视角；若正在使用真人语音面板，会取消当前录音、停止旧回复并释放旧会话，用户重新连接后使用新语言；手机上固定在品牌右侧第一行；「源代码」随第二行导航横向滚动，不单独固定。所有页面顶部都有「首页」入口；导航顺序为首页、动作训练场、演示场景、现场互动、训练新动作、交互统计、使用体验、部署记录、源代码、语言。?lang=zh|en|fr 可覆盖默认并保存选择。英法语仅支持灵矽云端，面板会说明本地动作识别仅支持中文；切回中文时恢复用户的识别方式偏好。连接等待时显示真实通道阶段及已等待秒数，可随时断开取消；这不是云端内部处理进度。

首次启用多语言，在服务的数据目录下执行一次：

uv run duckking-setup --language-profile --lang-code zh
uv run duckking-setup --language-profile --lang-code en
uv run duckking-setup --language-profile --lang-code fr

语言智能体存于私有 voice-profiles.json 的 language_zh/en/fr 白名单。英法语配置使用 transport: bound_device：每个房间在 languages/en、languages/fr 下保留独立私有设备身份，预先绑定对应语言智能体；重连仍发送 X-Agent-ID，原房间设备、场景及所有权保持不变。仅切换 Header 的旧配置不能保证云端告别遵循语言；升级时须重跑语言配置，并为已启用房间执行下面的设备准备命令。页面不会创建或重新绑定设备；缺失或不匹配的绑定记录明确报错，不回退原中文设备。已有 DUCKKING_FRENCH_ROOMS / DUCKKING_ENGLISH_ROOMS 仍可作为分房偏好，但不能代替语言智能体配置。缺少目标语言配置时明确报错，不偷偷用中文回复。当前离线命令链仅支持中文；英语/法语直接使用灵矽云端。预录剧场音轨仍为中文，界面明确标注；不会将它们称为法语实连回复。

为每个已启用房间准备两种语言（以下以房间 1 为例，最多按 DUCKKING_MAX_ROOMS 重复）：

uv run duckking-setup --room 1 --language-device --lang-code fr
uv run duckking-setup --room 1 --language-device --lang-code en

已用系统合成的法语/英语口令验证真实灵矽 STT → 点头工具完成 → 对应语言语音回复及自动告别，见 验证记录。这不等于 iPhone 真机、真人口音或噪声环境已验收。

回答或思考时按住“打断并说话”，立即清空旧播放并录制新命令；每次最多录音 15 秒。无进展的回答有超时保护、一次重连及手动“重置语音”，不会重放旧录音。iPhone 的 Chrome / 企业微信首次使用先点“启用 / 测试声音”；麦克风权限与声音播放权限不同。详情见 声音排查 和 日志与恢复。

连接后会先准备麦克风，按钮可用后再按住说话。麦克风在连接期间保持静音待命，仅按住时发送声音，松开静音、断开释放，减少每轮重新启动麦克风造成的句首遗漏。

五类物理场景

球场、双鸭和动作练习场支持坐下、站起；坐着可以点头，移动或踢球前要站起。前滚翻等新策略只接入进程内 MuJoCo，不直接扩展原生 robotd 的策略切换。没有翅膀／手部自由度，没有接入跳跃、摄像头／ToF 识别或空气琴。

停止和 Esc 会取消动作并清零运动意图，物理重力继续；搬运停止保留已建立的夹持，放下需显式操作。动作失败显示实际原因，不以预设动画代替成功。接触计数是物理步中接触点的累计，不是独立碰撞次数。

十三幕自动演示

点选节目即可自动准备场景、播放预录指令／角色对白并执行动作，无需真人讲话。两种演出方式分别是“自动演示 · 预录对白”和“灵矽实连 · 预录指令”；后者实际调用云端 STT、工具和 TTS。人类指令与小鸭台词使用不同系统合成音色。任何失败都会停止并显示原因。

1. 你是哪只鸭？

2. 反向招聘人类

3. 闭嘴，换我说

4. 甲方又改需求了

5. 鸭界世界杯记者会

6. 嘴硬快递员

7. 一屏双魂，舞林争霸

8. 孤独鸭的寻友记

9. 社恐鸭组团出道

10. 四声部谢幕：官方 wistful 乐谱节选；四只物理仿真鸭对应四个固定声部，依次入唱。

11. 桌上不掉拍：四鸭踏步和声，鸭 D 真实离桌、落地、站稳后续舞；可选《欢乐颂》《两只老虎》及用户提供的《夜空中最亮的星》片段。

12. 轮到我开唱：四鸭坐着合唱《欢乐颂》，A—D 轮流站稳独唱、唱完坐回。

13. 黄仁勋的四只小鸭：随机散落、集结排队后坐下、点名前滚翻就地坐下、选中鸭同拍齐舞；另有真人语音、指挥棒点选与物理轻戳。

第 10、12 幕在两种模式下均明确标为本地音乐与物理编排；第 11 幕在灵矽实连模式下由云端工具调用开演，浏览器播放已选音乐，不是灵矽生成歌声或官方 BLE 合唱。桌上跌落是预设剧情，结果由 MuJoCo 决定；个别跌落姿态可能无法恢复，届时会报失败。第 7 幕需要两个空闲房间。节目来源、音源处理与效果说明见 演示剧场。

现场互动与平衡学习实验

studio.html 的十项任务可先点本地排练，再连接灵矽说话：受限动作编排、搬运暂停续送、四鸭改序演唱、声音身份、动作暗号、分步踢球教练、口令游戏、橡皮鸭追问、专注计时和角色切换。排练按钮不会调用云端；声音试听也不代表已经完成声音克隆。任务能力与例外见 互动工坊。

平衡页三关分别为随盘站稳、保持朝向、偏心回中心。左右两侧使用相同关卡、种子、时长与盘面目标，动态状态独立；左侧未经过本项任务训练，但仍使用已训练的官方步态。右侧可切换已评估 PPO、训练第 0 步网络或同一基线。PPO 只学习三个反馈力度，底层复用冻结的官方 velstand.onnx；没有从零训练走路或接入实体圆盘。

以上为 2026-11-01 原训练环境的离线测试，不是在线观众成功率。现场演示按关卡目标验收：第一关站稳，第二关保持朝向（无回中心要求），第三关回到盘面红色目标区（半径8 cm）并连续保持1秒到结束。原训练曲线保留三关都需回中心、第2、3关都需保持朝向的严格标准。在线试跑支持 6–33 秒；改变时长不会重新训练，也不能沿用 13 秒成功率。失败侧保留判分成绩，继续展示最多 4 秒实际跌落／接触过程，再定格；另一侧可以继续。停盘属于人为干预，不计通关。

页面提供真实训练曲线、奖励分量、PPO 参数说明和原始记录；公网展示已有记录，默认不接受新训练任务。完整配置、哈希、种子和限制见 平衡教练 与 CPU 实测。本次视频的单轮结果单独记录，不混入上述 100 种子统计。

官方 robotd 与 Linux 部署

官方 robotd 路径另需 Rust/Cargo、pkg-config 和较大的上游依赖：

scripts/setup_simulator.sh
scripts/run_simulator.sh
# 另一个终端
uv run duckking --backend robotd --socket ~/.cache/duck-sim/duck-a.sock

DUCKKING_SIM_DIR 可指定外部资源目录，DUCK_SIM_VIEWER=0 可无窗口运行。首页此时仍是动画示意，真实物理画面查看官方 MuJoCo 窗口；不在适配失败时切回预览。适配器已做仿真联调，未做实体机器人测试。

Linux 在 YZH737 上使用独立 DuckKing / ASR systemd 服务，现通过 https://duck.qbox.net/ 的前置 OpenResty 直连 8765，提供页面、API 与原生 WebSocket，不经过 ai_gateway。直连配置在升级后保留，浏览器麦克风使用该域名的 HTTPS 安全上下文。原有 ztmonitor.qbox.net 网关接入方式保留在部署指南中。发布包带固定模型、来源与 SHA-256；安装自检、公网检查、真实语音验收分别记录，暂存不等于验收成功。步骤见 部署指南。

现场容量、100连接与真实云语音并发结果见 汇报容量实测。当前主机可分配32个轻量房间；建议每批20–24人语音体验，重物理演示限定1–2个房间，100人首次同时加载仍需错峰或预热。

开发检查与文档

体验评审核验与修复记录加载进度、房间恢复、单实例预热、统计恢复及720p首屏的修改与边界。

scripts/setup_local.sh
scripts/setup_local_asr.sh
uv run ruff check src tests
uv run pytest --cov --cov-report=json --cov-report=html
uv run python scripts/check_coverage.py
cd frontend
npm run test:unit
npx playwright install chromium
npm run test:e2e
npm run test:e2e:dev

CI 要求后端总体行覆盖率 ≥90%、分支覆盖率 ≥85%。后端、前端和 14 个浏览器任务使用独立 runner 并行；浏览器分别验证生产／开发构建；演示旅程和舞台交互各两片，其余检查三片，清单保证不遗漏、不重复。全部成功后 quality 才通过，共 17 个任务；同一 PR 的新提交自动取消旧运行。历史首轮并行实测从约 34 分钟缩短到 9 分 21 秒，不代表当前十三幕完整套件的固定耗时，见 CI 分析。

验证记录 提供绑定具体提交的测试数量和覆盖率；前端当前覆盖门槛只统计 audio-codec.js，不能作为全前端覆盖率。部署页展示的是对应发布提交的 Python 后端覆盖率。安装器将 CI 报告独立保存在 /var/lib/duckking/release-coverage.json，自动汇入历史发布包的报告，升级或清理旧发布目录后仍保留；没有真实报告的版本继续显示“未记录”。

• 商业价值与产品设计、架构与模块规格、本地开发与排障

• AI 协作说明、工程经验与回归检查、持续使用体验口径

• 演示复现与历史视频、舞步编排、媒体来源

• 贡献指南、团队与分工、原创贡献、安全说明

v0 保留空仓库基线；后续变更使用功能分支与 Pull Request。原创代码采用 MIT，官方模型、策略、谱面与歌曲分别遵循其原许可，详见 第三方来源。

项目成员与分工

本项目由 周霆（@zhoutingunl） 和 陶纯堂（@evanwooo） 合作完成。

协作记录包括陶纯堂在 PR #30 的审阅评论、PR #36 的审阅，以及语音连接按钮样式提交。完整模块责任与协作边界见 团队分工。

AI 协作说明

DuckKing 采用两位成员协作、AI 辅助开发的方式：人负责需求、方案选择、代码审阅和实际体验反馈，AI 辅助实现、排障、测试与文档。本轮维护使用 Codex；AI 不计作额外参赛成员，代码生成比例未经统计。实际修改与审阅通过功能分支、PR、CI 和发布验收追溯。

后续协作者先读 AGENTS.md 与 贡献指南，再按 AI 协作说明定位代码与验证方式。可复用的教训统一整理在 LESSONS_LEARNED.md；具体版本的测试证据留在 VALIDATION.md、PR、CI 和 Release 中。私有日志留在数据目录，不提交录音、凭证或设备身份。