# MetaSoul EPU4：AI 智能体接入指南（简体中文）

**API 地址：** `https://emohuman.com`  
**中英文交互文档：** https://emohuman.com/docs/EPU4/  
**OpenAPI JSON：** https://emohuman.com/docs/EPU4/openapi.json  
**MDAD 通道映射：** https://emohuman.com/docs/EPU4/mdad-channels.json

本指南依据 **2026 年 10 月 19 日**的《EPU SDK - API Integration Guide》。下文的情绪 APEX 通道说明来自更早的《EPU-III Brochure》第 14–15 页，与 EPU4 集成指南对 **120 个数值**的定义应分别理解。

## 最简单的使用步骤

如果尚不知道 EPUID，账户管理员可调用单独部署的 `POST /epuid_list`，在 HTTPS
请求体中提交一个 MetaSoul **账户密钥**（`{"secret":"YOUR_ACCOUNT_SECRET"}`）。
此操作只读取账户设备清单，不会登录、占用或操作 EPU。响应仅包含 `reply`、`total`、
`available`（可用）、`in_use`（使用中）和 `availability_unknown`（状态未知）中的完整
EPUID 列表，不返回上游原始响应或密钥。旧的扁平响应无法确认可用状态，因此归类为
`availability_unknown`。服务器必须先注册并启用该功能，否则返回 503。
设备清单状态不等于已验证的独占占用或休息就绪状态。不得记录密钥或原始账户响应。

1. 调用 `POST https://emohuman.com/user_login`，提供 `{"secret":"...","epuid":"..."}`，读取返回的 `token` 和 `epuid`。
2. 如果需要实时更新，先使用 Socket.IO 连接 `https://emohuman.com/<epuid>`，监听 `mdad` 事件，事件内容为 `{epuid, mdad: number[]}`。
3. 调用 `POST https://emohuman.com/derive`，添加 `Authorization: Bearer <token>`，请求体只需要 `{"text":"You have an amazing voice"}`。**不必选择 `reasoning` 或 `action`，即可触发 MDAD 更新。**
4. 纯文本请求通常返回 `{"reply":"ok"}`，更新的 MDAD 从 Socket.IO 接收。也可以调用带 Bearer token 的 `GET /mdad`，但此操作会等待**下一帧**（约 5 秒以内），不保证读取已经发送的那一帧。
5. MDAD 数组从 **0 开始编号**。2026 年 10 月 19 日集成指南描述 **120 个数值**，但 2026 年 10 月 31 日实际观测到一次 **123 个数值**的响应；请检测真实长度。

## 会话期限与可选保活

**当前网关实现**默认在 **60 分钟没有经过身份验证的 REST API 请求**后使会话过期。登录时可选的 `duration` 参数（单位：分钟）可以修改该期限。每次成功通过身份验证的 REST 请求都会更新最后使用时间；**仅接收 Socket.IO MDAD 帧不会延长 REST 会话**。服务器定期检查并清理空闲会话，因此释放时间可能略晚于超时点。

Bearer 令牌还有独立的 **24 小时最长有效期**。会话过期或失效后，REST API 可能返回 HTTP `401`，例如 `SESSION_EXPIRED`、`SESSION_NOT_FOUND` 或 `TOKEN_INVALIDATED`。此时应重新登录获取新令牌，不要反复使用失效令牌。浏览器显示 Socket.IO 已连接，并不代表 REST 会话仍有效；请检查**最后一帧实际 MDAD 数据的时间戳**。

对于确需长期运行的客户端，可以在 **55 分钟没有其他经过身份验证的 REST 请求**后，选择性调用一次带 Bearer 令牌的 `GET /mdad`。这会续期默认空闲计时，不会发送文本或触发新的情绪。该请求会消耗一个可用的 HTTP MDAD 缓存帧，或等待下一帧约五秒；没有新帧时可能返回 `503 EPU_NOT_CONNECTED`，但会话仍可能已成功续期。**不要把 503 视为令牌过期。** 该请求不消耗 Socket.IO 实时订阅。

**保活应由用户主动启用**，避免无人使用的程序持续占用 EPUID，妨碍另一台服务器连接。Swagger 页面的自动保活默认关闭，并且仅在标签页可见时运行。页面上的 Disconnect 按钮只清除本地令牌并停止浏览器 Socket.IO 客户端，目前不会立即释放服务器端的 EPU 预留。即使启用保活，24 小时令牌有效期仍然适用。

## 12 种情绪的 APEX 通道

计算公式：`4 + 10 * emotionIndex`，其中 `emotionIndex` 从 0 到 11。

| 情绪 | 英文 | APEX 通道 |
|---|---|---:|
| 兴奋 | Excite | 4 |
| 自信 | Confident | 14 |
| 快乐 | Happy | 24 |
| 信任 | Trust | 34 |
| 渴望 | Desire | 44 |
| 恐惧 | Fear | 54 |
| 惊讶 | Surprise | 64 |
| 注意力分散 | Inattention | 74 |
| 悲伤 | Sad | 84 |
| 怀旧 | Nostalgia | 94 |
| 厌恶 | Disgust | 104 |
| 愤怒 | Anger | 114 |

**乐观感觉（Optimistic）**在 `mdad[9]`，不同于 `mdad[4]` 的兴奋峰值。此映射来自 EPU-III 产品手册。

## 历史版本的其他通道

早期 EPU-III 手册还描述一个 **124 通道**缓冲区：

- `mdad[120]`：脉搏速度（0 慢，50 正常，100 快）。
- `mdad[121]`：挫败 / 满意（**0 最大满意／缓解挫败，50 中性，100 最大挫败**）。低于 50 表示挫败得到缓解。旧版 EPU-III 手册对该通道标示了相反的方向；此处采用操作人员对当前 EPU4 的测试解释，仍需结合固件确认。
- `mdad[122]`：痛苦 / 愉悦（**0 最大愉悦／缓解痛苦，50 中性，100 最大痛苦**）。低于 50 表示缓解痛苦。
- `mdad[123]`：温度（旧版说明 −40 至 +85 °C）。

**注意：**2026 年 EPU4 集成指南仅明确写出 **120 个数值**，因此实际只返回 120 个数值时，通道 120–123 **不存在**。请不要假设一定能读取上述四项。APEX 和乐观通道的索引取自较早手册及当前 Swagger 展示方式，2026 年 10 月 31 日的一次真实 `GET /mdad` 返回 **123 个数值**（索引 0–122）；单独读取的 120–122 通道值均为 `50`，与历史资料中的中性值相符，但尚不能证明 EPU4 的通道语义完全相同。索引 123 在本次响应中不可用。请根据每次实际返回的数组长度进行验证，并确认固件兼容性。

**数值检查：**12 个 APEX 通道、乐观通道 9，以及存在时的通道 121 和 122，都应将超出 0–100 的数值（包括 255）标记为无效。保留原始 MDAD 数组以便排查，不要默默截断、转换为 0 或作为有效情绪值传给人格决策逻辑。温度通道 123 有不同的取值范围，不能对全部 MDAD 索引一律套用此规则。

## 示例文件

- [OpenAPI JSON](openapi.json)：机器可读的 API 操作与数据结构。
- [MDAD 通道数据](mdad-channels.json)：供 AI 工具读取的索引表。
- [Node.js 代码](javascript-example.mjs)：Socket.IO 实时订阅、纯文本更新及解码。
- [Python 代码](python-example.py)：登录、`/derive`、`/mdad` 及解码。
- [English agent guide](agent-guide.md)：包含完整代码片段和操作注意事项。

请用环境变量传递密钥与设备 ID，不要在日志或公开文件中暴露凭据。原始 API 集成指南没有列出全部错误码、CORS 策略和 Socket.IO 身份验证方案；上述会话期限依据当前网关实现，而非旧版指南的明确规定。