鸿蒙PC DevBox 应用开发指南

搬砖的kk2025-12-27 8:17

鸿蒙PC DevBox 应用开发指南

项目简介

什么是 DevBox？

DevBox 是一个适用于 HarmonyOS PC 平台的命令工具集合应用，为开发者提供常用的命令行工具和实用程序。

主要功能

  • 📁 文件和目录操作 ：提供 tree、ls、find 等文件管理命令
  • 🌐 网络工具：包含网络诊断和管理工具
  • 🔧 构建工具：集成常用的构建和编译工具
  • 📦 包管理：支持 HNP (HarmonyOS Native Package) 格式的命令包

适用场景

  • ✅ HarmonyOS PC 开发者日常开发
  • ✅ 命令行工具集成和分发
  • ✅ 系统管理和维护
  • ✅ 自动化脚本执行

项目地址

🔗 GitCode: https://gitcode.com/OpenHarmonyPCDeveloper/DevBox

核心特性

1. 统一命令管理

  • 所有命令通过统一的 HNP 包格式管理
  • 支持命令的安装、更新和卸载
  • 自动集成到 HarmonyOS PC 终端环境

2. 完善的文档支持

  • 每个命令都包含详细的使用手册
  • 支持 --help 和 --version 参数
  • 提供命令语法和示例说明

3. 开源合规

  • 完整的开源软件声明
  • 许可证信息展示
  • 源码链接追踪

4. 用户体验优化

  • 首次安装自动提示重启终端
  • 命令自动加载到系统 PATH
  • 统一的命令接口和错误处理

快速开始

前置要求

  1. 开发环境

    • HarmonyOS SDK
    • DevEco Studio
    • Node.js 和 npm

  2. HNP 包准备

    • 已编译好的 HNP 格式命令包
    • 命令包已通过测试验证

  3. 项目访问

    bash 复制代码 
    git clone https://gitcode.com/OpenHarmonyPCDeveloper/DevBox.git
cd DevBox

安装说明

⚠️ 重要提示：首次安装 DevBox 后，需要重启"终端命令行"应用才能使用新添加的命令。这是因为系统需要重新加载命令目录。

开发原则

代码结构规范

请遵从代码结构。如需更改，请给出充分理由。

目录结构约定
复制代码 
DevBox/
├── entry/
│   └── src/
│       └── main/
│           ├── module.json5          # 应用配置和HNP包列表
│           └── resources/
│               └── rawfile/
│                   ├── commonManualInfo/      # 命令手册目录
│                   │   ├── all_manual_list.json
│                   │   └── xxx_manual.json
│                   ├── software_list/         # 开源软件声明
│                   │   └── software_list.json
│                   └── licenseList/           # 许可证文件
│                       └── about_xxx_opensource.html
└── hnp/
    └── arm64-v8a/                    # HNP包存放目录
        └── xxx.hnp
命名规范
  • HNP 包文件 : 命令名.hnp（如 tree.hnp）
  • 手册文件 : 命令名_manual.json（如 tree_manual.json）
  • 许可证文件 : about_命令名_opensource.html（如 about_tree_opensource.html）

集成新命令完整流程

本文档以 tree 命令为例，详细说明如何将一个新的命令集成到 DevBox 中。

步骤概览

准备HNP包
添加包配置
创建命令手册
添加开源声明
创建许可证文件
测试验证
完成

步骤 1：准备 HNP 包

1.1 编译 HNP 包

使用 Lycium++ 构建系统编译命令：

bash 复制代码 
cd lycium
./build.sh tree
1.2 获取编译产物

编译完成后，在以下目录找到 HNP 包：

复制代码 
lycium/output/arm64-v8a/tree.hnp
1.3 复制到项目

将 HNP 包复制到 DevBox 项目的指定目录：

bash 复制代码 
# 创建目录（如果不存在）
mkdir -p DevBox/hnp/arm64-v8a

# 复制 HNP 包
cp lycium/output/arm64-v8a/tree.hnp DevBox/hnp/arm64-v8a/

目录结构：

复制代码 
DevBox/
└── hnp/
    └── arm64-v8a/
        └── tree.hnp  ✅

💡 提示：

  • 确保 HNP 包文件名与命令名一致
  • 只支持 arm64-v8a 架构
  • HNP 包必须是有效的 HarmonyOS Native Package 格式

步骤 2：添加包配置

2.1 编辑 module.json5

打开 entry/src/main/module.json5 文件，在 hnpPackages 数组中添加新包的配置：

文件位置 ：entry/src/main/module.json5

添加配置：

json5 复制代码 
{
  "hnpPackages": [
    // ... 其他包配置
      {
        "package": "tree.hnp",
        "type": "public"
    }
  ]
}

配置说明：

字段 类型 说明 示例
package string HNP 包文件名（必须与 hnp/arm64-v8a/ 目录中的文件名一致） "tree.hnp"
type string 包类型，"public" 表示公开命令 "public"

⚠️ 注意事项：

  • 包名必须与 HNP 文件名完全一致（包括大小写）
  • 确保 JSON 语法正确，注意逗号和括号
  • 建议按字母顺序排列包配置，便于维护

步骤 3：创建命令手册

3.1 创建手册文件

在 entry/src/main/resources/rawfile/commonManualInfo/ 目录下创建命令手册文件：

文件路径 ：entry/src/main/resources/rawfile/commonManualInfo/tree_manual.json

文件内容：

json 复制代码 
{
  "name": "tree",
  "description": "以树状结构列出目录内容，显示文件和目录的层次关系。",
  "syntax": "tree [-acdfghilnpqrstuvxACDFJQNSUX] [-L level [-R]] [-H [-]baseHREF] [-T title] [-o filename] [-P pattern] [-I pattern] [--gitignore] [--gitfile[=]file] [--matchdirs] [--metafirst] [--ignore-case] [--nolinks] [--hintro[=]file] [--houtro[=]file] [--inodes] [--device] [--sort[=]name] [--dirsfirst] [--filesfirst] [--filelimit[=]#] [--si] [--du] [--prune] [--charset[=]X] [--timefmt[=]format] [--fromfile] [--fromtabfile] [--fflinks] [--info] [--infofile[=]file] [--noreport] [--hyperlink] [--scheme[=]schema] [--authority[=]host] [--opt-toggle] [--version] [--help] [--] [directory ...]",
  "options": [
    {
      "paramName": "-a",
      "description": "All files are listed."
    },
    {
      "paramName": "-d",
      "description": "List directories only."
    },
    {
      "paramName": "-l",
      "description": "Follow symbolic links like directories."
    },
    {
      "paramName": "-f",
      "description": "Print the full path prefix for each file."
    },
    {
      "paramName": "-x",
      "description": "Stay on current filesystem only."
    },
    {
      "paramName": "-L level",
      "description": "Descend only level directories deep."
    },
    {
      "paramName": "-R",
      "description": "Rerun tree when max dir level reached."
    },
    {
      "paramName": "-P pattern",
      "description": "List only those files that match the pattern given."
    }
    // ... 更多选项
  ],
  "examples": [
    "tree",
    "tree -L 2",
    "tree -a -h -p",
    "tree -I \"node_modules|.git\"",
    "tree -o output.txt /path/to/directory",
    "tree --help"
  ],
  "showDetails": false
}

字段说明：

字段 类型 说明 必填
name string 命令名称，必须与 HNP 包名一致 ✅
description string 命令的简短描述 ✅
syntax string 命令的完整语法说明 ✅
options array 命令选项列表，每个选项包含参数名和描述 ✅
examples array 使用示例列表 ✅
showDetails boolean 是否显示详细信息（默认 false） ❌

选项对象结构：

json 复制代码 
{
  "paramName": "-L level",      // 参数名称（包含参数值占位符）
  "description": "描述文本"     // 参数说明
}
3.2 注册手册文件

编辑 entry/src/main/resources/rawfile/commonManualInfo/all_manual_list.json，将新创建的手册文件名添加到列表中：

文件路径 ：entry/src/main/resources/rawfile/commonManualInfo/all_manual_list.json

添加内容：

json 复制代码 
[
  "tree_manual.json",
  // ... 其他手册文件
]

💡 提示：

  • 手册文件名格式：命令名_manual.json
  • 建议按字母顺序排列，便于查找和维护
  • 确保 JSON 数组格式正确

步骤 4：添加开源软件声明

4.1 编辑 software_list.json

打开 entry/src/main/resources/rawfile/software_list/software_list.json，添加新命令的开源声明：

文件路径 ：entry/src/main/resources/rawfile/software_list/software_list.json

添加配置：

json 复制代码 
[
  // ... 其他软件声明
  {
    "name": "tree",
    "license": "LicenseType.GPL_V2L",
    "source": "https://github.com/hongtaoh/tree-1.8.0",
    "licenseFile": "about_tree_opensource.html",
    "showLicense": false
  }
]

字段说明：

字段 类型 说明 示例
name string 软件名称，通常与命令名一致 "tree"
license string 许可证类型，使用 LicenseType 枚举值 "LicenseType.GPL_V2L"
source string 源码仓库 URL "https://github.com/..."
licenseFile string 许可证 HTML 文件名 "about_tree_opensource.html"
showLicense boolean 是否在应用中显示许可证信息 false

常见许可证类型：

  • LicenseType.GPL_V2L - GPL v2 许可证
  • LicenseType.APACHE_V2 - Apache 2.0 许可证
  • LicenseType.MIT - MIT 许可证
  • LicenseType.BSD - BSD 许可证

⚠️ 重要：

  • 必须准确填写许可证类型，确保合规
  • 源码链接必须可访问
  • 许可证文件名必须与步骤 5 中创建的文件名一致

步骤 5：创建许可证文件

5.1 创建 HTML 文件

在 entry/src/main/resources/rawfile/licenseList/ 目录下创建许可证 HTML 文件：

文件路径 ：entry/src/main/resources/rawfile/licenseList/about_tree_opensource.html

文件命名规则 ：about_命令名_opensource.html

文件内容示例：

html 复制代码 
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>tree - 开源软件声明</title>
</head>
<body>
    <h1>tree</h1>
    <h2>许可证</h2>
    <p>GPL v2</p>
    <h2>源码</h2>
    <p><a href="https://github.com/hongtaoh/tree-1.8.0">https://github.com/hongtaoh/tree-1.8.0</a></p>
    <h2>许可证全文</h2>
    <pre>
        [在此处粘贴完整的许可证文本]
    </pre>
</body>
</html>

内容要求：

  1. 软件信息

    • 软件名称
    • 版本号（如适用）

  2. 许可证信息

    • 许可证类型
    • 许可证全文

  3. 源码链接

    • 可访问的源码仓库地址
    • 版本标签或提交哈希（如适用）

  4. 版权声明

    • 原作者信息
    • 版权年份

💡 提示：

  • HTML 文件应使用 UTF-8 编码
  • 确保所有链接可访问
  • 许可证文本应完整准确
  • 建议使用标准的 HTML5 结构

步骤 6：测试验证

6.1 编译项目

在 DevEco Studio 中编译 DevBox 项目：

bash 复制代码 
# 或使用命令行
npm run build
6.2 安装应用

将编译好的应用安装到 HarmonyOS PC 设备或模拟器上。

6.3 重启终端

⚠️ 重要：首次安装或添加新命令后，必须重启"终端命令行"应用才能使用新命令。

6.4 测试命令

在终端中测试新添加的命令：

bash 复制代码 
# 基本测试
tree

# 查看帮助信息
tree --help

# 查看版本信息
tree --version

# 测试常用选项
tree -L 2
tree -a -h -p

验证清单：

  • 命令可以正常执行
  • --help 显示正确的帮助信息
  • --version 显示正确的版本号
  • 命令手册在应用中正确显示
  • 开源声明信息正确
  • 许可证文件可以正常打开

文件结构说明

完整目录结构

复制代码 
DevBox/
├── entry/                          # 应用入口模块
│   └── src/
│       └── main/
│           ├── module.json5        # 应用配置和HNP包列表
│           └── resources/
│               └── rawfile/
│                   ├── commonManualInfo/      # 命令手册目录
│                   │   ├── all_manual_list.json      # 手册文件列表
│                   │   ├── tree_manual.json         # tree命令手册
│                   │   └── ...                      # 其他命令手册
│                   ├── software_list/         # 开源软件声明目录
│                   │   └── software_list.json # 软件列表配置
│                   └── licenseList/           # 许可证文件目录
│                       ├── about_tree_opensource.html
│                       └── ...                # 其他许可证文件
└── hnp/                            # HNP包存放目录
    └── arm64-v8a/                  # arm64架构包目录
        ├── tree.hnp                 # tree命令包
        └── ...                      # 其他命令包

关键文件说明

文件路径 作用 修改频率
hnp/arm64-v8a/*.hnp 存放 HNP 格式的命令包 每次添加新命令
entry/src/main/module.json5 应用配置和包列表 每次添加新命令
commonManualInfo/xxx_manual.json 命令使用手册 每次添加新命令
commonManualInfo/all_manual_list.json 手册文件注册列表 每次添加新命令
software_list/software_list.json 开源软件声明列表 每次添加新命令
licenseList/about_xxx_opensource.html 许可证文件 每次添加新命令

配置详解

module.json5 配置

json5 复制代码 
{
  "module": {
    "name": "entry",
    "hnpPackages": [
      {
        "package": "tree.hnp",      // HNP包文件名
        "type": "public"            // 包类型：public/public_sandbox/isolated
      }
    ]
  }
}

包类型说明：

  • "public": 公开命令，所有应用可访问
  • "public_sandbox": 公开沙箱命令
  • "isolated": 隔离命令，仅当前应用可访问

手册文件配置

json 复制代码 
{
  "name": "tree",                    // 命令名
  "description": "命令描述",         // 简短描述
  "syntax": "tree [options]",        // 语法说明
  "options": [                       // 选项列表
    {
      "paramName": "-L level",      // 参数名
      "description": "参数说明"      // 参数描述
    }
  ],
  "examples": [                      // 使用示例
    "tree",
    "tree -L 2"
  ],
  "showDetails": false              // 是否显示详细信息
}

开源声明配置

json 复制代码 
{
  "name": "tree",                    // 软件名称
  "license": "LicenseType.GPL_V2L", // 许可证类型
  "source": "https://...",          // 源码地址
  "licenseFile": "about_tree_opensource.html",  // 许可证文件
  "showLicense": false              // 是否显示许可证
}

最佳实践

1. 命名规范

  • ✅ HNP 包名 ：使用小写字母，与命令名一致（如 tree.hnp）
  • ✅ 手册文件名 ：使用 命令名_manual.json 格式
  • ✅ 许可证文件名 ：使用 about_命令名_opensource.html 格式
  • ✅ 配置中的名称：保持一致性，避免大小写混用

2. 文档编写

  • ✅ 描述清晰：使用简洁明了的语言描述命令功能
  • ✅ 语法完整：提供完整的命令语法说明
  • ✅ 示例实用：提供真实可用的使用示例
  • ✅ 选项详细：为每个重要选项提供说明

3. 开源合规

  • ✅ 许可证准确：确保许可证类型正确
  • ✅ 源码可访问：确保源码链接有效
  • ✅ 信息完整：包含完整的版权和许可证信息
  • ✅ 及时更新：当软件更新时同步更新声明

4. 测试验证

  • ✅ 功能测试：确保命令基本功能正常
  • ✅ 帮助测试 ：验证 --help 和 --version 输出
  • ✅ 手册测试：检查手册显示是否正确
  • ✅ 兼容性测试：在不同场景下测试命令

5. 代码维护

  • ✅ 版本控制：使用 Git 管理代码变更
  • ✅ 提交信息：编写清晰的提交信息
  • ✅ 代码审查：提交前进行自我审查
  • ✅ 文档同步：代码变更时同步更新文档

常见问题

Q1: 添加命令后，终端中找不到命令？

A: 请确保：

  1. 已重启"终端命令行"应用
  2. HNP 包文件名与 module.json5 中的配置一致
  3. HNP 包已正确放置在 hnp/arm64-v8a/ 目录
  4. 应用已正确安装到设备

Q2: 命令手册不显示？

A: 请检查：

  1. 手册文件是否创建在正确目录
  2. 手册文件名是否添加到 all_manual_list.json
  3. JSON 格式是否正确（无语法错误）
  4. 手册文件中的 name 字段是否与命令名一致

Q3: 开源声明不显示？

A: 请验证：

  1. software_list.json 中是否添加了声明
  2. 许可证文件是否创建在 licenseList/ 目录
  3. licenseFile 字段是否与文件名一致
  4. HTML 文件格式是否正确

Q4: HNP 包编译失败？

A: 请参考：

  1. 检查编译日志中的错误信息
  2. 确认依赖库已正确编译

Q5: 如何更新已添加的命令？

A: 更新流程：

  1. 重新编译 HNP 包（使用新版本）
  2. 替换 hnp/arm64-v8a/ 目录中的旧包
  3. 更新手册文件（如有变更）
  4. 重新编译和安装应用
  5. 重启终端应用

Q6: 可以添加多个架构的包吗？

A : 目前 DevBox 仅支持 arm64-v8a 架构。如需支持其他架构，需要：

  1. 修改项目结构支持多架构
  2. 更新 module.json5 配置
  3. 修改应用代码以处理多架构

参考资源

官方文档

相关项目

开发工具

社区支持

贡献指南

如何贡献

  1. Fork 项目：Fork DevBox 仓库到你的账户
  2. 创建分支：创建功能分支进行开发
  3. 提交代码：按照规范提交代码
  4. 创建 PR：提交 Pull Request 并描述变更

代码规范

  • 遵循项目现有的代码风格
  • 添加必要的注释和文档
  • 确保代码通过编译和测试
  • 更新相关文档

问题反馈

如遇到问题或有改进建议，请：

  1. 在 GitCode 上创建 Issue
  2. 提供详细的问题描述和复现步骤
  3. 附上相关的日志和截图

欢迎大家加入跨平台开发者社区

相关推荐
周胡杰2 小时前
AudioPlayerManager 音视频单例播放管理类操作文档附加案例
华为·音视频·harmonyos·数据持久化·鸿蒙音视频
xianjixiance_11 小时前
Flutter跨平台三方库鸿蒙化适配指南
flutter·华为·harmonyos
夏小鱼的blog12 小时前
【HarmonyOS应用开发入门】第四期：ArkTS语言基础（二）
harmonyos·openharmony
wtrees_松阳12 小时前
【弦断九章·CPU篇】鸿蒙应用性能优化心法
华为·性能优化·harmonyos
2501_9462243113 小时前
旅行记录应用统计分析 - Cordova & OpenHarmony 混合开发实战
javascript·harmonyos·harvester
2501_9462243114 小时前
旅行记录应用外观设置 - Cordova & OpenHarmony 混合开发实战
javascript·harmonyos·harvester
TAEHENGV14 小时前
回收站模块 Cordova 与 OpenHarmony 混合开发实战
android·java·harmonyos
Nick不懂16 小时前
鸿蒙分布式KVStore冲突解决机制：原理、实现与工程化实践
harmonyos
FrameNotWork16 小时前
深入浅出 HarmonyOS NEXT (迈向 6.0 架构)：攻克 ArkTS 高性能状态管理与 NAPI 底层交互难题
架构·交互·harmonyos
热门推荐
01从快手“12·22”直播攻击事件看：一次教科书式的业务层饱和攻击02GitHub 镜像站点033D 圣诞树网页代码04Linux下V2Ray安装配置指南05UV安装并设置国内源06在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）07电脑检测软件—图吧工具箱08Gemini3 生成的基于手势控制3D粒子圣诞树09jdk21下载、安装（Windows、Linux、macOS）10Claude Code Skills 实用使用手册