docs: 补齐小智硬件与固件平台介绍

.project-docs/30-worklog/tasks/20260924-merge-agent-rendering-ml-4efb196c.md

@@ -12,6 +12,8 @@
 
 ## Scope
 
+- 产品介绍补充（2026-09-26）：用户指出遗漏小智硬件固件平台；在同一介绍中补入小智固件、设备服务、智控台、构建/OTA 及与麦洛的关系，修正总览与使用流程。其他工程仅作只读参考。
+
 - 产品介绍扩展（2026-09-26）：依据用户要求，将已确认的老师 Agent 定位扩展为三项目客观产品介绍，交付 `docs/product-introduction.md`。覆盖客户端四模块、平台作品/运营服务、Yuxi 能力平台、老师能力定义与当前交付边界；仅文档。
 
 - 产品定位后续（2026-09-26）：依据用户确认及进一步澄清，在 Makelore 产品文档记录“老师 Agent 是某一领域杰出人物的能力转化而成的智能体，供平台学生使用”。定义以人的领域能力为中心，蒸馏归入实现方法；仅更新文档。
@@ -20,6 +22,8 @@
 
 ## Intent And Constraints
 
+- 小智补充的官方 check/start/status 与同一任务 Identity 匹配，Concurrent/Planning Gates Passed。重读入口、自身记录、Robot ADR-002/003，复用上一轮 canonical 上下文和未变化的 117 个 peer 范围。依据固件 README/audio/ota/MCP/builder、GoProjects 小智主服务路由及管理实现、WS xiaozhi_hardware_client/ai_hardware 核对职责；HardwareProjects 下旧服务副本只作参照，以已接入的外部 API 和当前主服务为准。只补产品介绍，不初始化或修改参考工程，不宣称老师已接入机器人或所有板型能力一致。
+
 - 产品介绍后续：官方 check/start/status 与 Identity 和 integration 所有权匹配，Concurrent/Planning Gates Passed。重读三仓入口、自身记录、定位、状态、决定、架构、领域与相关产品说明；复用此前未变 peer 范围，刷新近期 20 份注册记录，当前三仓分别有 117/271/48 个 peer。头像同步和加权定价另有隔离任务，不作为已实现主线能力。历史模板记录仍未知只读，无本次具体依赖。计划：按真实入口核对功能，编写独立 Markdown，检查事实、结构、差异及文档写边界后交付；保留已 adopted 文档，不创建子智能体、不执行模型/线上调用。
 
 - 用户进一步明确重点是老师 Agent 的定义“某领域杰出的人的能力变成一个 agent”。官方同任务续接核验与 Concurrent/Planning/Integration Gates 再次通过，重读本轮六份产品记录，复用未变的 116 个 peer 范围。计划：统一定义、能力内涵、学生价值和方法层次；核对文档差异、边界门禁后提交，不把蒸馏流程作为产品核心，也不收窄为单一聊天或判断技巧。
@@ -32,6 +36,8 @@
 
 ## Outcome
 
+- 已将产品组成补为四个主要部分，小智单列设备固件与设备服务两层；新增第六节（固件、语音、智控台、构建/升级、跨系统关系），增加机器人使用流程，同步 Robot 与 WS 对接说明。保留用户已确认的老师能力定义，区分 Yuxi 老师与小智机器人角色。
+
 - 产品介绍交付：Makelore `docs/product-introduction.md` 包含整体分工、四个客户端模块、老师 Agent 定义与学生价值、三个只读工具、Works Square 网页及运营模块、Yuxi 资源/执行功能和典型流程。理念严格采用用户最新定义；蒸馏属于方法。核对后未将网页历史 AI 讲解文案、旧周额度、独立桌面 Learning 入口、待合入头像/计价和默认关闭的移动 Feed 写为现有常规能力。没有产品行为、部署或计费变更。
 
 - 产品定位后续（2026-09-26）：按用户进一步澄清，project-positioning、README、老师 ADR、决定索引和 current-state 已统一为“某一领域杰出人物的能力转化而成的智能体，供平台学生使用”。重点回到能力来源、所承载的领域能力及学生价值，蒸馏移到实现方法层；学生仍可获得领域理解、判断和解决问题的方法。既有交互和云端能力边界保持，未修改任何运行代码或线上定义。
@@ -42,6 +48,8 @@
 
 ## Verification
 
+- 小智补充核对通过：当前固件构建说明与 ota/audio/MCP 实现、GoProjects 小智管理端路由和 WS 外部设备接口支持新增职责描述；八个章节、表格列数、原老师定义及总览范围检查通过，git diff --check 和官方 task-aware drift 通过。本轮没有硬件烧录、语音测试、构建或部署，不据此声明真机兼容；3 份 adopted 文档保持。
+
 - 产品介绍文档检查已通过：三仓官方 task-aware drift 与 git diff --check 均通过，既有 adopted 文档保持原状态。Markdown 的 UTF-8、表格列数、七个主章节、末尾换行和老师 Agent 定义核对通过；本轮仅新增介绍文件及三份自身记录，无运行代码变化。未执行产品测试、站点构建或生产验收；Yuxi 只变更私有任务记录，不改公开文档站。
 
 - 本轮依据：Makelore README、`src/lib/ai-modules.ts`、AIHardware/CloudAgents 页面、项目提交入口和老师 ADR；Works Square Operations 菜单、CodingTeacherOperations/ObservationAgentOperations、Education 当前视图及平台已接受决定；Yuxi ARCHITECTURE、路由、AgentManage/Extensions 页面与原生老师决定。验证限定于本地主线文档/源码事实，不代表线上功能或领域能力验收。正式文档门禁、空白与本轮精确提交范围检查在交付前执行；不重复运行与纯介绍文档无关的模型或产品回归。

docs/product-introduction.md

@@ -1,6 +1,6 @@
 # 麦洛产品介绍
 
-> 整理日期：2026 年 9 月 26 日。本文介绍 Makelore、Works Square 与 Yuxi 组成的产品体系，按当前主分支的功能与已确认的产品定位整理。具体可用功能取决于账号权限、客户端版本和配套服务配置。
+> 整理日期：2026 年 9 月 26 日。本文介绍 Makelore、Works Square、Yuxi 与小智硬件及固件平台组成的产品体系，依据当前项目源码、功能说明与已确认的产品定位整理。具体可用功能取决于账号权限、客户端和固件版本、硬件配置及配套服务。
 
 ## 一、产品概述
 
@@ -8,15 +8,16 @@
 
 产品围绕具体的项目、作品和问题展开：用户提出想法，借助 AI 完成制作和修改，在需要专业判断时引入老师 Agent，并通过作品平台展示符合发布条件的成果。
 
-整个产品体系由三个项目共同组成：
+整个产品体系由四个主要部分组成，其中小智部分包含设备固件与设备服务两个层次：
 
 | 项目 | 产品职责 | 主要使用者 |
 | --- | --- | --- |
 | **Makelore 桌面客户端** | 提供 AI 编程、视觉创作、机器人管理、个人云智能体和项目内咨询的操作界面 | 学生、创作者、个人智能体使用者 |
 | **Works Square 平台** | 提供网页作品展示、账号与点数服务、作品审核发布、资源管理及智能体下发 | 学生、作品浏览者、家长、平台运营人员 |
 | **Yuxi 智能体平台** | 管理智能体及其模型、提示词、知识库和扩展能力，承担云端智能体的对话与执行 | 智能体配置人员、能力建设者、平台管理员 |
+| **小智硬件与固件平台** | 提供设备端固件、语音交互服务、机器人配置、设备管理及固件构建与升级能力 | 机器人使用者、硬件开发者、设备运营与维护人员 |
 
-对学生而言，Makelore 是主要的创作入口。Works Square 承担平台服务与运营管理，Yuxi 提供可配置、可运行的云端智能体能力。
+对学生而言，Makelore 是主要的创作入口。Works Square 承担平台服务与运营管理，Yuxi 提供可配置、可运行的云端智能体能力，小智体系承担实体机器人上的交互和设备运行。
 
 ## 二、Makelore 桌面客户端
 
@@ -67,7 +68,7 @@ Robot 用于管理接入平台的机器人设备及其对话配置。
 - **语言与声音配置**：设置对话语言、声音音色及聊天记录方式。
 - **设备与配置查看**：围绕所选智能体查看绑定设备和当前配置。
 
-当前模块主要服务于已接入的机器人体系，设备行为与可选能力受对应硬件和设备服务支持范围约束。
+Robot 是小智硬件体系在 Makelore 中的管理入口。设备上的固件、实时语音对话及固件升级由小智体系承担，完整职责见第六节。设备行为与可选能力受对应硬件和设备服务支持范围约束。
 
 ### 2.4 Makelore Agents：个人云智能体
 
@@ -180,6 +181,7 @@ Works Square 提供学生作品的展示与访问入口，支持浏览已发布
 - **插件服务**：管理官方插件目录、发布资源和账号获取记录，配合客户端完成项目使用。
 - **客户端分发**：管理安装包和更新信息。
 - **老师 Agent 下发**：将运营选定的 Yuxi 智能体提供给有资格的学生账号使用。
+- **机器人服务对接**：连接麦洛账号与小智设备服务，提供机器人智能体创建、配置、设备绑定和设备分配所需的接口。
 
 ### 4.4 运营后台模块
 
@@ -228,9 +230,77 @@ Yuxi 为产品体系提供智能体的配置、知识资源与运行能力，同
 
 在老师 Agent 的协作链路中，Yuxi 负责能力定义和云端运行，Works Square 负责选择与下发。运营端可选择平台原生主智能体目录中的智能体，目录覆盖符合条件的内置及其他用户创建项，不局限于当前运营账号名下。
 
-## 六、典型使用流程
+## 六、小智硬件与固件平台
 
-### 6.1 学生制作一个交互式作品
+小智体系让 AI 通过实体设备与用户交互。它包括运行在设备上的 ESP32 固件，以及处理语音对话、管理设备和配置的服务端。固件工程提供板型适配和构建能力，服务平台提供智控台及 OTA 升级管理。
+
+### 6.1 设备端固件
+
+设备固件负责连接具体硬件，把麦克风、扬声器、屏幕和可用执行部件组织成可交互的终端。
+
+主要能力包括：
+
+- **硬件适配**：按芯片和板型配置音频、显示、按键及其他外设，构建对应的设备固件。
+- **网络与配网**：连接设备网络，通过支持的配网方式设置连接信息，并与小智服务通信。
+- **语音输入与播放**：处理麦克风采集、语音唤醒、音频传输和扬声器播放。
+- **交互反馈**：在配有屏幕、灯光等部件的设备上显示状态、文字或表情。
+- **设备控制**：通过设备实际提供的工具控制音量、显示、灯光、GPIO 或电机等能力。
+- **激活与升级**：获取激活信息，检查适用固件版本并执行 OTA 更新。
+
+带摄像头的设备可提供视觉输入，具备相应音频条件的设备可支持更完整的回声消除和语音交互。具体能力取决于板型、外设、固件构建选项和服务配置，不能把所有板型视为具有相同功能。
+
+### 6.2 语音与智能交互服务
+
+小智服务端接收设备的音频和消息，组织语音识别、模型回答、工具调用与语音合成，再把结果返回设备。
+
+主要能力包括：
+
+- **语音对话**：提供语音活动检测、语音识别、语言模型对话和语音合成，支持流式交互。
+- **角色配置**：为机器人配置角色提示、语言、模型和声音。
+- **模型接入**：对接不同的语音、语言和视觉模型服务，按配置使用对应能力。
+- **记忆与知识**：提供可选的记忆、知识检索等能力，辅助连续对话和领域问答。
+- **声纹与视觉**：在相应服务与设备启用后，支持说话人识别及视觉理解相关功能。
+- **工具和设备指令**：通过工具、插件或 MCP 等方式扩展行为，并向支持的设备下发控制指令。
+
+这些属于小智体系的可配置能力，是否对某台机器人开放取决于其配置与实际接入的服务。
+
+### 6.3 智控台与设备运营
+
+小智提供网页智控台，并包含移动管理端，用于管理机器人服务本身。主要模块包括：
+
+| 模块 | 主要功能 |
+| --- | --- |
+| 智能体与角色配置 | 管理机器人角色、模型、声音及相关对话配置 |
+| 设备管理 | 管理设备绑定、归属及与机器人智能体的关联 |
+| 用户与接入管理 | 管理用户，以及外部平台使用设备服务的接入凭据 |
+| 模型与供应商管理 | 配置语音识别、语言模型、语音合成等服务 |
+| 声音与声纹 | 管理音色资源、声纹及已接入的声音扩展能力 |
+| 知识库 | 管理机器人使用的知识资源及检索配置 |
+| 固件与 OTA | 管理固件类型、版本、文件及升级分发 |
+| 系统配置 | 管理服务参数、功能配置和相关运行设置 |
+
+Makelore Robot 面向日常设备使用，小智智控台承担更完整的设备服务配置与维护；两者的界面和功能范围有所不同。
+
+### 6.4 固件构建与交付
+
+固件工程支持按板型及发布变体构建，可选择界面语言和支持的唤醒词模型。构建产物包含用于设备升级的固件、用于完整烧录的镜像，以及构建日志和版本来源信息。
+
+设备维护人员可以将适用固件交付给设备烧录，或通过固件与 OTA 管理流程提供升级。板型与固件必须匹配；构建成功并不等于对应实物设备已经完成音频、屏幕、网络和升级验证。
+
+### 6.5 与麦洛其他部分的关系
+
+| 部分 | 在机器人链路中的职责 |
+| --- | --- |
+| Makelore Robot | 向用户提供创建角色、引导配网、激活绑定、设置声音和分配设备的操作入口 |
+| Works Square | 处理麦洛账号侧的授权、关联记录与小智设备服务对接 |
+| 小智服务平台 | 保存和使用机器人配置，处理设备通信、语音对话与设备管理 |
+| 小智设备固件 | 在实物设备上采集输入、播放声音、显示反馈及执行支持的设备操作 |
+
+当前机器人智能体沿用小智体系，平台下发的老师 Agent 由 Yuxi 运行。现有产品介绍不将“在 Yuxi 配置一位老师”表述为“该老师已自动进入所有机器人”；把同一领域能力用于实体设备，需要另外确认能力接入、语音交互和设备支持情况。
+
+## 七、典型使用流程
+
+### 7.1 学生制作一个交互式作品
 
 1. 在 Code 中创建或打开项目，描述想做的作品。
 2. 与编程智能体协作完成代码和运行预览。
@@ -239,14 +309,14 @@ Yuxi 为产品体系提供智能体的配置、知识资源与运行能力，同
 5. 学生选择采用的建议，继续制作和验证。
 6. 对符合发布条件的作品提交审核，通过平台流程对外展示。
 
-### 6.2 用户制作图片或视频
+### 7.2 用户制作图片或视频
 
 1. 在 Canvas 创建设计项目，描述内容并提供参考素材。
 2. 通过对话和参数编辑确认制作方案。
 3. 查看费用并确认生成。
 4. 在历史作品中预览、下载结果，或继续用于后续制作。
 
-### 6.3 平台提供一位领域老师
+### 7.3 平台提供一位领域老师
 
 1. 明确某位领域杰出人物的能力来源、擅长范围和要提供给学生的帮助。
 2. 在 Yuxi 中通过提示词、Skill、案例、知识及工具配置承载这些能力，并检查实际表现。
@@ -254,15 +324,24 @@ Yuxi 为产品体系提供智能体的配置、知识资源与运行能力，同
 4. 学生在 Makelore 中看到入口，并在自己的项目情境中使用。
 5. 能力配置调整后，由运营显式同步新版本，供后续新话题使用。
 
-## 七、当前产品范围说明
+### 7.4 用户配置一台机器人
+
+1. 为支持的设备准备匹配的固件，并完成必要的烧录或升级。
+2. 在 Makelore Robot 创建机器人智能体，设置角色、模型和声音。
+3. 按引导为设备配网，使用设备提供的激活码完成绑定。
+4. 将设备分配给对应智能体，通过设备实际测试语音与交互表现。
+5. 日常在客户端调整公开配置，由设备维护人员通过小智平台管理适用的固件和服务配置。
+
+## 八、当前产品范围说明
 
 - Makelore 当前提供四个模块入口。学习项目目录属于平台服务和运营能力，当前不作为客户端的第五个独立模块。
 - 客户端支持项目内提交审核；独立作品广场主要由网页平台承担。
 - 学习项目以运营整理的内容和项目文件为主。自动课程生成、完整教学进度系统和课堂管理不属于本文所述现有功能。
 - 老师 Agent 的专业能力定位适用于后续能力建设；当前主要使用入口位于 Code 项目咨询，并不表示所有模块都已接入同样的项目读取能力。
 - 个人云智能体、编程操作智能体、平台下发的咨询智能体和机器人配置各有当前职责与使用入口，本文不将它们视为已经完全互通的配置对象。
+- 小智固件及服务能力按硬件和配置启用；设备绑定成功不等于在线、语音链路或全部外设已通过验证。Yuxi 老师 Agent 与机器人角色目前也不自动同步。
 - 手机端混合信息流等仍有独立启用和验收条件的能力，未列为本介绍中的常规可用功能。本文也不将尚未合入主分支的改动列为现状。
 
 ---
 
-本文依据三个项目的当前模块入口、页面、已接受产品决策及功能说明整理。老师 Agent 定义采用 2026 年 9 月 26 日确认的定位。本文用于产品介绍，不作为特定部署环境的功能验收报告。
+本文依据 Makelore、Works Square、Yuxi、小智服务端和小智固件工程的模块入口、源码、已接受产品决策及功能说明整理。老师 Agent 定义采用 2026 年 9 月 26 日确认的定位。本文用于产品介绍，不作为特定部署环境或实物设备的功能验收报告。