# xiaozhi-echo

**Repository Path**: fa0/xiaozhi-echo

## Basic Information

- **Project Name**: xiaozhi-echo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xiaozhi.echo

EchoBraid echoapp — 管理 [xiaozhi.me](https://xiaozhi.me) 的智能体、设备、音色、对话历史和 MCP 接入点。

## 文件（v2 schema）

```
xiaozhi.echo/                # 源目录（working dir）
├── manifest.json            # v2 manifest (schema_version: 2)
├── index.html               # 入口必须叫 index.html 且在根目录（Desktop 硬编码）
├── assistant.html           # 小智助手面板模板，由 index.html 隐藏 iframe 导入
├── app.css                  # 样式
├── app.js                   # 业务脚本
├── icons/
│   └── icon.svg             # 24x24 currentColor 图标
└── README.md
```

打包产物：`~/Desktop/xiaozhi-app.echo`（v2 ZIP，约 23 KB）。

## 能力（capabilities）

- `ui` — WebContentsView 加载 `index.html`
- `network` — 直连 `https://xiaozhi.me` REST API
- `storage` — JWT token 存 `localStorage`

## API 全覆盖

Tab 只有 3 个（智能体 / 设备 / 历史对话）；模型与音色不单独成 tab，仅在智能体编辑弹窗内作为下拉来源。

| 位置 | API | 方法 |
|------|-----|------|
| 智能体 tab（创建/编辑） | `POST /api/agents` `POST /api/agents/<id>/config` | 1, 2 |
| 智能体 tab（列表） | `GET /api/agents` | 4 |
| 编辑弹窗：LLM 下拉 | `GET /api/roles/model-list` | 3 |
| 设备 tab | `GET /api/developers/devices` | 5 |
| 智能体行操作：加设备 | `POST /api/agents/<id>/devices` | 6 |
| 编辑弹窗：音色下拉 | `GET /api/user/tts-list` | 7 |
| 历史对话 tab | `GET /api/chats/list` | 8 |
| 智能体行操作：MCP | `POST /api/agents/<id>/generate-mcp-endpoint-token` | 9 |
| 编辑弹窗：MCP 工具勾选 | `GET /api/agents/common-mcp-tool/list` | 10 |

## 用法

### 浏览器直接调试
```bash
open ~/Desktop/xiaozhi.echo/index.html
```
首次会自动弹"设置"。手机登录走 echobraid bridge（绕 CORS），浏览器模式不可用，需要直接粘贴已用 CLI 拿到的 JWT Bearer token。

### EchoBraid 桌面加载

```bash
# 打包（用全局 echobraid CLI；本目录不是 pnpm workspace，别加 --filter）
rm -f ~/Desktop/xiaozhi-app.echo
echobraid pack-v2 ~/Desktop/xiaozhi.echo -o ~/Desktop/xiaozhi-app.echo
```

安装：把 `~/Desktop/xiaozhi-app.echo` **拖进 EchoBraid Desktop 窗口**。

> ⚠️ `echobraid install` 命令在 v0.4.0 后加了官方应用校验，对非官方 echoapp 报
> `E_INVALID: 当前不支持非官方应用,请使用官方 CLI 或 Director 创建`，
> 所以非官方 echoapp 必须走 Desktop UI 拖入安装。

## JWT 安全

- 仅写本地 `localStorage`（key: `xiaozhi.jwt`、`xiaozhi.base`）
- 不上传任何第三方
- 弹窗中始终掩码显示，复制 token 需点"复制"按钮
- 切机器需在新机重新粘贴

## 已知限制 & v2 规划

- 当前为纯 UI；EchoAgent 通过 `exports[]` 调用的 MCP 工具入口 v2 再补
- MCP bridge（Python websocket）不在本 echoapp 范围内 —— bridge 启动指引在 MCP 弹窗里给命令，由用户在 shell 跑
- 历史对话支持点会话进入消息明细弹窗（按消息时间分组、角色头像、首条 100 条；超长会话再分页 v2）

## 参考

- 接口文档：来自 [xiaozhi-creator-skill](https://github.com/Pesifar/xiaozhi-creator-skill) 的 `references/主要接口_ai适配.md`