@lingyao037/openclaw-lingyao-cli 0.3.0-alpha.1

package/README.md

@@ -0,0 +1,325 @@
+# 灵爻 (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)