npm package: @lingyao037/openclaw-lingyao-cli
Description: Lingyao Channel Plugin for OpenClaw - bidirectional sync via lingyao.live server relay
Author: OpenClaw
Latest version: 1.1.1

# 灵爻 (Lingyao) - OpenClaw 与鸿蒙 App 通信桥梁

灵爻是一个完整的双端通信系统，实现 OpenClaw Gateway 和鸿蒙 App 之间的实时双向消息同步，通过 lingyao.live 服务器中转。

> 当前仓库仅保留“服务器中转 + 双端主动 WebSocket 连接”实现。

## 快速开始

### 🚀 完整部署指南

查看 **[完整部署指南](DEPLOYMENT_GUIDE.md)** 获取三端完整部署流程：
1. Lingyao Live 服务器部署
2. OpenClaw Gateway 插件安装
3. 鸿蒙 App 部署

## 系统架构

```
┌─────────────────────┐                    ┌─────────────────────┐
│   OpenClaw Gateway   │                    │   HarmonyOS App      │
│   (WebSocket Client) │                    │   (WebSocket Client) │
│                      │                    │                      │
│ 代码: src/           │                    │ 代码: harmonyos-app/ │
│ 部署: 作为插件运行   │                    │ 部署: 鸿蒙设备       │
└──────────┬───────────┘                    └──────────┬───────────┘
           │                                            │
           │ WebSocket                                  │ WebSocket
           │ wss://api.lingyao.live/v1/gateway/ws      │ wss://api.lingyao.live/v1/app/ws
           │                                            │
           ▼                                            ▼
┌─────────────────────────────────────────────────────────────┐
│               Lingyao Live Server (lingyao.live)            │
│               (WebSocket Relay Server)                     │
│                                                               │
│ 代码: server/src/server.ts                                  │
│ 部署: 云服务器 (需要公网 IP 和域名)                          │
│ WebSocket: /v1/gateway/ws, /v1/app/ws                       │
│ HTTP API: /v1/gateway/*, /v1/app/*                          │
└─────────────────────────────────────────────────────────────┘
```

## 三端组件

### 1. Lingyao Live 服务器 (server/)

WebSocket 中转服务器，实现 Gateway 和 App 之间的消息转发。

**关键文件:**
- `server/src/server.ts` - 主服务器实现
- `server/package.json` - 依赖配置
- `server/README.md` - 服务器文档

**功能:**
- 双 WebSocket 服务器处理 Gateway 和 App 连接
- HTTP REST API 提供注册、心跳、消息发送
- 离线消息队列（每设备最多 100 条）
- 心跳监控和超时检测

### 2. OpenClaw Gateway 端 (src/)

OpenClaw 插件，作为 WebSocket 客户端连接到服务器。

**关键文件:**
- `src/channel.ts` - 主频道类
- `src/websocket-client.ts` - WebSocket 客户端
- `src/server-client.ts` - HTTP API 客户端
- `src/metrics.ts` - 监控指标
- `src/errors.ts` - 错误处理

**功能:**
- 自动连接到 lingyao.live 服务器
- 接收来自鸿蒙 App 的同步消息
- 发送通知到鸿蒙 App
- 自动重连和心跳保活

### 3. 鸿蒙 App 端 (harmonyos-app/)

鸿蒙应用，作为 WebSocket 客户端连接到服务器。

**关键文件:**
- `harmonyos-app/src/websocket/LingyaoWSClient.ts` - WebSocket 客户端
- `harmonyos-app/src/sync/DataSyncManager.ts` - 数据同步管理器
- `harmonyos-app/src/models/Message.ts` - 消息模型
- `harmonyos-app/src/utils/Logger.ts` - 日志工具
- `harmonyos-app/entry/src/main/ets/entryability/EntryAbility.ts` - 应用入口
- `harmonyos-app/README.md` - App 文档

**功能:**
- 连接到 lingyao.live 服务器
- 发送日记和记忆数据到 Gateway
- 接收来自 Gateway 的通知
- 离线消息队列和自动同步

## 核心功能

| 功能 | 描述 |
|------|------|
| **双向实时通信** | WebSocket 双向消息传递 |
| **服务器中转** | 双方作为客户端连接，无需公网 IP |
| **离线消息** | 服务器缓存，上线自动推送 |
| **自动重连** | 指数退避策略，最多 10 次重试 |
| **心跳保活** | 30 秒心跳，60 秒超时检测 |
| **消息类型** | 日记、记忆、通知同步 |

## 消息类型

| 类型 | 方向 | 描述 |
|------|------|------|
| `sync_diary` | App → Gateway | 同步日记数据 |
| `sync_memory` | App → Gateway | 同步记忆数据 |
| `notify_text` | Gateway → App | 文本通知 |
| `notify_action` | Gateway → App | 动作通知 |
| `heartbeat` | 双向 | 心跳保活 |

## API 端点

### Gateway 端点

| 端点 | 方法 | 功能 |
|------|------|------|
| `/v1/gateway/register` | POST | 注册 Gateway |
| `/v1/gateway/heartbeat` | POST | 发送心跳 |
| `/v1/gateway/messages` | POST | 发送消息到 App |
| `/v1/gateway/ws` | WS | WebSocket 连接 |

### App 端点

| 端点 | 方法 | 功能 |
|------|------|------|
| `/v1/app/register` | POST | 注册 App 设备 |
| `/v1/app/heartbeat` | POST | 发送心跳 |
| `/v1/app/sync` | POST | 上传数据到 Gateway |
| `/v1/app/messages` | GET | 拉取消息 |
| `/v1/app/ws` | WS | WebSocket 连接 |

详细 API 规范查看 [server-api-spec.yaml](server-api-spec.yaml)

## 开发

### 构建

```bash
# 构建 OpenClaw 端
npm run build

# 构建服务器端
cd server && npm run build

# 构建鸿蒙 App
# 使用 DevEco Studio 打开 harmonyos-app 并构建
```

### 测试

```bash
# OpenClaw 端测试
npm test

# 服务器端测试
cd server && npm test
```

### 开发模式

```bash
# OpenClaw 端开发模式
npm run dev

# 服务器端开发模式
cd server && npm run dev

# 鸿蒙 App 开发
# 使用 DevEco Studio 的调试功能
```

## 文档

| 文档 | 描述 |
|------|------|
| [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | 完整部署指南 |
| [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) | 实现总结 |
| [server/README.md](server/README.md) | 服务器文档 |
| [harmonyos-app/README.md](harmonyos-app/README.md) | App 文档 |
| [server-api-spec.yaml](server-api-spec.yaml) | OpenAPI 规范 |

## 项目结构

```
lingyao/
├── src/                      # OpenClaw Gateway 端代码
│   ├── channel.ts            # 主频道类
│   ├── websocket-client.ts   # WebSocket 客户端
│   ├── server-client.ts      # HTTP 客户端
│   ├── metrics.ts            # 监控指标
│   ├── errors.ts             # 错误处理
│   └── ...
├── server/                   # Lingyao Live 服务器
│   ├── src/
│   │   └── server.ts         # 主服务器
│   ├── package.json
│   ├── tsconfig.json
│   └── README.md
├── harmonyos-app/           # 鸿蒙 App 端
│   ├── src/
│   │   ├── websocket/        # WebSocket 客户端
│   │   ├── sync/             # 数据同步
│   │   ├── models/           # 数据模型
│   │   └── utils/            # 工具类
│   ├── entry/                # 应用入口
│   └── README.md
├── test/                     # 测试文件
├── DEPLOYMENT_GUIDE.md       # 部署指南
├── IMPLEMENTATION_SUMMARY.md # 实现总结
├── server-api-spec.yaml      # API 规范
├── README.md                 # 本文件
└── package.json
```

## 配置

### OpenClaw Gateway 配置

```json
{
  "plugins": {
    "entries": {
      "lingyao": {
        "enabled": true
      }
    }
  }
}
```

### 服务器配置

```bash
# server/.env
PORT=3000
HOST=0.0.0.0
HEARTBEAT_INTERVAL=30000
HEARTBEAT_TIMEOUT=60000
MAX_OFFLINE_MESSAGES=100
```

### 鸿蒙 App 配置

```typescript
// EntryAbility.ts
const wsClient = new LingyaoWSClient({
  url: 'wss://api.lingyao.live/v1/app/ws',
  deviceId: deviceId,
  appToken: appToken,
});
```

## 监控和调试

### 查看日志

| 组件 | 命令 |
|------|------|
| **服务器** | `sudo journalctl -u lingyao-live -f` |
| **Gateway** | `openclaw logs` |
| **App** | DevEco Studio 日志窗口 |

### 健康检查

```bash
# 服务器健康检查
curl https://api.lingyao.live/health

# Gateway 状态
openclaw channels status --channel lingyao

# App 连接状态
# 查看 App 界面中的连接状态显示
```

## 故障排查

### 服务器端

```bash
# 检查服务状态
sudo systemctl status lingyao-live

# 查看错误日志
sudo journalctl -u lingyao-live -n 50 --no-pager

# 重启服务
sudo systemctl restart lingyao-live
```

### Gateway 端

```bash
# 检查插件状态
openclaw plugins list

# 查看日志
openclaw logs

# 重启 Gateway
openclaw gateway restart
```

### App 端

- 检查设备网络连接
- 确认服务器 URL 正确
- 查看应用日志

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License

## 联系方式

- 项目主页: [https://github.com/your-org/lingyao](https://github.com/your-org/lingyao)
- 问题反馈: [https://github.com/your-org/lingyao/issues](https://github.com/your-org/lingyao/issues)