# HarmonyOS无线调试工具 **Repository Path**: luomutsuki/harmonyoshdc ## Basic Information - **Project Name**: HarmonyOS无线调试工具 - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-01 - **Last Updated**: 2026-09-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README I'll help you create a comprehensive README.md for this HarmonyOS HDC project. Based on the code map, I can see this is an on-device HDC (HarmonyOS Device Connector) client application. Let me compile the documentation: ```markdown # HarmonyOS HDC 客户端 (HarmonyOS Device Connector) [Chinese Version](README_CN.md) ## 项目简介 本项目是一个运行在 HarmonyOS 设备内部的 HDC 客户端实现，使用 ArkTS 语言开发。它提供了在 HarmonyOS 设备上直接连接、管理和调试其他 HarmonyOS 设备的能力，无需依赖外部命令行工具。 ## 主要功能 ### 核心功能 - **设备连接管理** - 支持 USB 和网络两种连接方式 - **Shell 命令执行** - 远程执行 Shell 命令 - **文件传输** - 支持本地设备与远程设备间的文件上传下载 - **应用管理** - 安装、卸载和调试应用 - **端口扫描** - 发现局域网内的 HarmonyOS 设备 ### 技术特性 - 命令串行队列机制 - 确保命令有序执行 - 三重结束判定 - 可靠的任务完成检测 - 流式输出 - 实时获取命令执行结果 - 分片文件传输 - 大文件高效传输 ## 项目结构 ``` entry/src/main/ets/ ├── common/ # 公共工具模块 │ ├── Clip.ets # 剪贴板操作 │ ├── Conn.ets # 连接管理 │ ├── LocalFs.ets # 本地文件系统 │ ├── PortScanner.ets # 端口扫描器 │ ├── Responsive.ets # 响应式布局 │ ├── Store.ets # 本地存储 │ ├── Theme.ets # 主题管理 │ └── Types.ets # 类型定义 ├── hdc/ # HDC 核心模块 │ ├── HdcAuth.ets # 认证模块 │ ├── HdcBmTool.ets # 应用管理工具 │ ├── HdcClient.ets # HDC 客户端主类 │ ├── HdcCommands.ets # 命令实现 │ ├── HdcProtocol.ets # 协议处理 │ ├── HdcSession.ets # 会话管理 │ └── HdcTypes.ets # 类型定义 ├── pages/ # 页面模块 │ ├── AppPage.ets # 应用管理页面 │ ├── ConnectPage.ets # 连接页面 │ ├── FilePage.ets # 文件管理页面 │ ├── Index.ets # 首页 │ ├── MorePage.ets # 更多功能页面 │ └── ShellPage.ets # Shell 命令页面 ├── view/ # 公共视图组件 │ └── Common.ets # 通用组件 └── entryability/ └── EntryAbility.ets # 应用入口 ``` ## 快速开始 ### 环境要求 - HarmonyOS SDK 4.0+ - DevEco Studio 4.0+ - ArkTS 语言 ### 安装步骤 1. **克隆项目** ```bash git clone https://gitee.com/luomutsuki/harmonyoshdc.git ``` 2. **使用 DevEco Studio 打开** - 打开 DevEco Studio - 选择 "Open Project" - 选择项目根目录 3. **配置签名** - 在 "Project Structure" -> "Signing Configs" 中配置签名信息 4. **构建运行** - 连接 HarmonyOS 设备 - 点击 "Run" 按钮或按 `Shift + F10` ## 使用指南 ### 设备连接 1. **USB 连接** - 通过 USB 数据线连接两台 HarmonyOS 设备 - 在目标设备上启用 "开发者模式" 和 "USB 调试" - 在应用中选择 USB 连接模式 2. **网络连接** - 确保设备在同一局域网 - 扫描可用设备或手动输入 IP 地址 - 输入端口号（默认 5555） ### 常用功能 #### 执行 Shell 命令 ```typescript // 示例：在远程设备上执行命令 const client = new HdcClient(); await client.connect('192.168.1.100', 5555); const result = await client.runCommand('ls -l'); console.log(result); ``` #### 文件传输 ```typescript // 上传文件到远程设备 await client.sendFile('/local/path/file.txt', '/remote/path/'); // 从远程设备下载文件 await client.recvFile('/remote/path/file.txt', '/local/path/'); ``` #### 应用管理 ```typescript // 安装应用 await client.installApp('/path/to/app.hap'); // 卸载应用 await client.uninstallApp('com.example.myapp'); // 运行应用 await client.runApp('com.example.myapp'); ``` ## API 参考 ### HdcClient 类 #### 连接管理 ```typescript // 连接到设备 connect(addr: string, port: number): Promise // 断开连接 disconnect(): void // 获取连接状态 getState(): ConnectionState ``` #### 命令执行 ```typescript // 执行 Shell 命令 runCommand(cmd: string): Promise // 执行命令并获取流式输出 runCommandWithStream(cmd: string, callback: (data: string) => void): void ``` #### 文件传输 ```typescript // 发送文件到设备 sendFile(localPath: string, remotePath: string): Promise // 从设备接收文件 recvFile(remotePath: string, localPath: string): Promise ``` #### 应用管理 ```typescript // 安装应用 installApp(hapPath: string): Promise // 卸载应用 uninstallApp(bundleName: string): Promise // 启动应用 startApp(bundleName: string): Promise // 停止应用 stopApp(bundleName: string): Promise ``` ### Conn 模块 ```typescript // 获取可用设备列表 getDevices(): Promise // 通过 USB 连接设备 connectUsb(deviceId: string): Promise // 通过网络连接设备 connectTcp(ip: string, port: number): Promise // 断开指定设备 disconnect(deviceId: string): Promise ``` ## 核心设计 ### 命令串行队列 HCF 采用命令串行队列机制，确保每条命令都能按顺序执行，避免并发冲突： ```typescript class CommandQueue { private queue: Command[] = []; private executing: boolean = false; async execute(cmd: Command): Promise { this.queue.push(cmd); return this.processQueue(); } private async processQueue(): Promise { if (this.executing || this.queue.length === 0) return; this.executing = true; const cmd = this.queue.shift(); try { return await cmd.execute(); } finally { this.executing = false; this.processQueue(); } } } ``` ### 三重结束判定 为确保命令执行的可靠性，采用三重结束判定机制： 1. **标准输出检测** - 检查命令的标准输出结束标志 2. **退出码验证** - 通过退出码确认命令是否正常结束 3. **超时保护** - 设置最大执行时间防止命令无限挂起 ### 流式输出 支持实时获取命令执行过程中的输出： ```typescript const stream = client.startShell('logcat'); stream.on('data', (chunk) => { console.log('实时日志:', chunk); }); ``` ### 分片文件传输 大文件采用分片传输，提高传输效率和可靠性： ```typescript class FileTransfer { async sendFile(filePath: string): Promise { const fileSize = await this.getFileSize(filePath); const chunkSize = 64 * 1024; // 64KB 每片 const chunks = Math.ceil(fileSize / chunkSize); for (let i = 0; i < chunks; i++) { const data = await this.readChunk(filePath, i, chunkSize); await this.sendChunk(data, i, chunks); } } } ``` ## 已知限制 1. **设备兼容性** - 仅支持 HarmonyOS 4.0 及以上版本 - 需要设备开启开发者模式 2. **功能限制** - 部分系统级命令可能受限 - 高权限操作需要 root 权限 3. **性能限制** - 大文件传输受设备存储性能影响 - 网络模式受网络环境影响 4. **安全限制** - 需要设备间建立信任关系 - 部分敏感操作需要用户确认 ## 贡献指南 1. Fork 本仓库 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 发起 Pull Request ## 许可证 本项目遵循 [MIT License](LICENSE)。 ## 联系方式 - 项目地址: https://gitee.com/luomutsuki/harmonyoshdc - 问题反馈: https://gitee.com/luomutsuki/harmonyoshdc/issues ## 感谢 感谢所有为这个项目做出贡献的开发者！ ```