# YuziBot

**Repository Path**: dullwolf/yuzi-bot

## Basic Information

- **Project Name**: YuziBot
- **Description**: 香橙派机器人
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Yuzi Bot

桌面陪伴机器人：**香橙派设备端** + **Java 多租户 SaaS 平台**。

设备出厂不堆业务功能；能力以 **Skill（技能）** 形式在云端目录发布，租户在后台拖拽开通后，设备同步技能说明并按清单调用远程 API。

> 一句话：设备是稳定的感知与执行终端；技能与模型能力在 SaaS；定制按租户开通。

---

## 仓库结构（Monorepo）

```text
yuzi-bot/
├── README.md                 # 本文件
├── docs/                     # 总体架构与约定
├── device/                   # 香橙派设备端（Python，后续）
├── server/                   # Java SaaS 后台（后续）
└── skills-catalog/           # 技能目录：每个技能一份介绍型 skill.md（可同步到设备）
```

当前阶段以 **架构与文档** 为主，代码按路线图落地。

---

## 文档导航

| 文档 | 说明 |
|------|------|
| [docs/architecture.md](docs/architecture.md) | 总体架构：设备 / SaaS / 技能市场 |
| [docs/saas-platform.md](docs/saas-platform.md) | Java 多租户后台、拖拽开通、同步协议 |
| [docs/device-runtime.md](docs/device-runtime.md) | 设备运行时：只跑引擎，不内置业务技能 |
| [docs/skill-spec.md](docs/skill-spec.md) | Skill 规范：`skill.md` + 远程调用约定 |
| [docs/mvp.md](docs/mvp.md) | 第一阶段验证范围 |
| [docs/hardware-bom.md](docs/hardware-bom.md) | 硬件采购清单（无摄像头；转头必买） |
| [docs/roadmap.md](docs/roadmap.md) | 分阶段路线 |

---

## 核心模式

```text
用户看到技能介绍 (skill.md)
        │
        ▼
联系开通 → 运营在 SaaS 为该租户拖拽绑定 Skill
        │
        ▼
设备定期同步「已开通技能清单 + skill.md」
        │
        ▼
唤醒/口令命中技能 → 设备调 SaaS / 模型 HTTP API → 播报/展示结果
```

- **未开通**：设备上只有介绍文档（或技能商店只读列表），不能执行。  
- **已开通**：清单内技能可被路由调用；实现逻辑在服务端，设备侧是通用执行器。  
- **新功能上线**：先发目录里的 `skill.md`；租户开通后才同步为可用。

---

## 两端职责

| 端 | 技术 | 职责 |
|----|------|------|
| 设备 `device/` | Python on Orange Pi | 麦/摄/屏/舵机、唤醒、ASR/TTS 适配、技能清单同步、按 manifest 调 API、表情与二维码 |
| 后台 `server/` | **Java**（Spring Boot 等） | 多租户、设备鉴权、技能目录、租户技能编排（拖拽）、对话/解题/提醒等 API、模型网关、运营后台 |
| 目录 `skills-catalog/` | Markdown + YAML 头 | 每个技能的介绍与调用契约，供后台导入与设备展示 |

---

## 技能目录（示例）

见 [skills-catalog/](skills-catalog/)。每个技能目录含介绍型 `skill.md`，例如：

- `wake-chat` — 唤醒对话（当前）  
- `reminder` — 日程提醒（当前）  
- `homework` — 扫题讲解（**未来**，需摄像头）  

当前以 chat + reminder 为准；**非设备内置死代码**，以租户开通结果为准。

---

## 本地预览文档

克隆后直接阅读 `docs/` 与 `skills-catalog/`。  
设备与 Java 工程目录将在实现阶段填充。

```bash
git clone https://gitee.com/dullwolf/yuzi-bot.git
cd yuzi-bot
```

---

## 设计原则

1. **能力云端化**：业务技能以 SaaS 开通 + 远程 API 为准，避免固件绑死功能。  
2. **租户定制**：同一套设备固件，不同租户技能包不同。  
3. **文档即商品说明**：`skill.md` 既是人看的介绍，也是同步到设备的说明源。  
4. **设备保持瘦**：运行时 = 感知 + 同步 + 路由 + 展示；不塞租户定制逻辑。  
5. **Java 管后台**：账号、租户、权限、编排、计费扩展都放在 `server/`。

---

## 许可

[Apache License 2.0](./LICENSE)