📋 目录
- [1. 📖 背景介绍](#1. 📖 背景介绍)
- [2. 🛠️ 环境准备](#2. 🛠️ 环境准备)
- [3. 📁 项目结构分析](#3. 📁 项目结构分析)
- [4. 🔍 问题诊断与解决](#4. 🔍 问题诊断与解决)
- [5. ✏️ 详细修改步骤](#5. ✏️ 详细修改步骤)
- [6. ✅ 构建验证](#6. ✅ 构建验证)
- [7. 💻 使用示例](#7. 💻 使用示例)
- [8. 📚 总结与最佳实践](#8. 📚 总结与最佳实践)
1. 📖 背景介绍
1.1 🤖 x-cmd工具简介
x-cmd(读作 "X Command")是一个小巧且功能强大的命令行工具集,提供超过 100+ 种功能模块和 500+ 个第三方开源CLI工具。x-cmd是一个基于POSIX Shell和AWK开发的模块化命令行工具集,旨在帮助用户以更高效、舒适的方式完成命令行任务。
核心功能:
- ⚡ 一键启用1000+ CLI工具: 按需下载,像启动App一样启动命令行工具
- 🧠 AI加持: AI代理、AI对话、AI任务、AI生成...一行命令即刻拥有AI copilot
- 🧩 环境管理: Node、Python、Java、Go等开发环境,即装即用
- 🛡️ 安全沙箱: 提供系统权限控制沙箱和基于Docker的隔离沙箱
- 🎨 终端美化: 内置终端主题与主题色切换,字体安装器,导航切换和原生的命令补全
- ∞ 一致化设计: 统一的命令风格,直观的TUI交互,丝滑的流程控制
- 🗃️ Hub: 随时随地运行自托管脚本,即使在Alpine/Busybox等极简容器镜像
- 🪶 极致轻量化: 核心包体积 ~ 1.1 MB,加载时间控制 ~ 100 ms
应用场景:
- 🖥️ 系统管理: 进程管理、系统监控、网络配置等
- 📁 文件系统操作: 增强的文件浏览、搜索、操作功能
- 🫙 Git操作: 简化的Git工作流和命令
- 📦 包管理: 统一的包管理接口,支持多种包管理器
- 🤖 AI辅助: 集成OpenAI、Gemini等AI服务,提供AI对话和代码生成
- 🎨 终端美化: 主题切换、字体安装、命令补全等
1.2 🎯 适配目标
通过DevBox工具查找未具备x-cmd工具能力,将x-cmd工具适配到鸿蒙PC(OpenHarmony PC)平台,实现:
- 🐚 Shell脚本跨平台支持
- 🏗️ 支持aarch64-linux-ohos架构
- 📦 生成HNP格式的安装包
- 📦 生成tar.gz格式的发布包
- 💻 提供可执行的
x命令入口

1.3 🔧 技术栈
- 语言: 🐚 POSIX Shell Script + AWK
- 构建系统: Makefile
- 目标平台: 🎯 aarch64-linux-ohos
- 打包格式: 📦 HNP (HarmonyOS Native Package)
- 依赖: 无外部依赖(纯Shell脚本,运行时按需下载)
1.4 💡 工具优势
相比传统的命令行工具,x-cmd提供了:
- ✅ 模块化设计 : 通过
x <mod>调用不同功能模块 - ✅ 按需下载: 工具按需下载,不占用过多存储空间
- ✅ AI集成: 内置AI功能,提供智能辅助
- ✅ 统一接口: 统一的命令风格,降低学习成本
- ✅ 轻量级: 核心包体积小,加载速度快
- ✅ 跨平台: 支持多种Shell和操作系统
2. 🛠️ 环境准备
2.1 💻 系统要求
- 开发环境: 💻 macOS / 🐧 Linux / 🪟 Windows (WSL)
- Shell: 🐚 Bash 3.0+ / Zsh / Dash / Ash
- Python: 🐍 Python 3.x(用于构建脚本)
- Git: 📦 Git(用于获取版本号)
- 网络连接: 🌐 需要网络连接以下载x-cmd模块和工具
- 鸿蒙SDK: 📦 OHOS SDK (包含native工具链和hnpcli打包工具)
2.2 📥 SDK安装
- 📥 下载SDK
bash
# 下载鸿蒙SDK
cd ~
wget https://cidownload.openharmony.cn/version/Master_Version/ohos-sdk-full_ohos/20250819_020817/version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz
# 解压SDK
tar -zvxf version-Master_Version-ohos-sdk-full_ohos-20250819_020817-ohos-sdk-full_ohos.tar.gz
-
📁 SDK目录结构
ohos-sdk/
├── native/
│ ├── llvm/bin/ # 🔧 编译器工具链
│ ├── sysroot/ # 📚 系统根目录(头文件和库)
│ └── build-tools/ # 🛠️ 构建工具
└── toolchains/
└── hnpcli # 📦 HNP打包工具
2.3 🐚 Shell环境配置
x-cmd支持多种Shell环境,OpenHarmony PC默认支持Bash,无需额外配置。
验证Bash版本:
bash
bash --version # 应显示 bash 3.0 或更高版本
3. 📁 项目结构分析
3.1 📂 目录结构
x-cmd4oh/
├── Makefile # Makefile构建脚本
├── build_ohos.sh # OpenHarmony构建脚本
├── hnp.json # HNP包配置
├── README.md # 项目说明(英文)
├── README.cn.md # 项目说明(中文)
├── LICENSE/ # 许可证文件目录
├── CHANGELOG.md # 变更日志
├── README.OPENSOURCE # 开源说明
└── .x-cmd/ # x-cmd相关脚本
├── fabu-x-cmd-readme.sh
└── ...
3.2 🔧 Makefile关键配置
makefile
# Installation paths (can be overridden by environment variables)
PREFIX ?= /usr/local
INSTALL_DIR ?= ${PREFIX}/bin
X_CMD_DIR ?= ${PREFIX}/share/x-cmd
all:
@echo "x-cmd is a shell script toolkit, no compilation needed"
@echo "Please run 'make install'"
install:
@echo ""
@echo "Installing x-cmd..."
mkdir -p $(INSTALL_DIR)
mkdir -p $(X_CMD_DIR)
@echo ""
@echo "x-cmd installation completed"
@echo "Installation directory: $(INSTALL_DIR)"
@echo "x-cmd directory: $(X_CMD_DIR)"
关键配置说明:
- ⚠️ 无需编译: x-cmd是Shell脚本工具集,无需编译
- 📁 安装路径 : 通过
INSTALL_DIR和X_CMD_DIR环境变量指定安装目录 - 🔧 目录结构: 创建bin和share/x-cmd目录
3.3 📝 x-cmd安装机制
x-cmd采用在线安装机制:
- 安装脚本 : 通过运行
eval "$(curl https://get.x-cmd.com)"安装 - 下载机制: 从OSS下载x-cmd的压缩包
- 版本管理: 支持latest、alpha、beta等版本
- 按需加载: 模块和工具按需下载和使用
x-cmd目录结构(安装后):
~/.x-cmd/
├── bin/ # 可执行文件
├── mod/ # 功能模块
├── pkg/ # 第三方工具包
├── metadata/ # 元数据
└── setup.log # 安装日志
4. 🔍 问题诊断与解决
4.1 🔍 问题1:缺少Makefile
问题描述 :
x-cmd项目原本没有Makefile,构建脚本需要Makefile来执行安装操作。
解决方案 :
创建Makefile,提供install和clean目标:
makefile
install:
@echo "Installing x-cmd..."
mkdir -p $(INSTALL_DIR)
mkdir -p $(X_CMD_DIR)
@echo "x-cmd installation completed"
4.2 🔍 问题2:构建脚本路径错误
问题描述 :
build_ohos.sh中的tar.gz打包路径错误,使用了x-cmd.0.7.6而不是x-cmd_0.7.6。
解决方案 :
修正tar.gz打包命令中的目录名:
bash
# 修复前
tar -zvcf ${ARCHIVE_PATH}/ohos_x-cmd_0.7.6.tar.gz x-cmd.0.7.6/
# 修复后
tar -zvcf ${ARCHIVE_PATH}/ohos_x-cmd_0.7.6.tar.gz x-cmd_0.7.6/
4.3 🔍 问题3:x-cmd在线安装机制
问题描述 :
x-cmd采用在线安装机制,需要网络连接来下载模块和工具。
解决方案:
- 在OpenHarmony PC上确保网络连接正常
- 首次使用时运行安装脚本:
eval "$(curl https://get.x-cmd.com)" - 后续使用
x <mod>命令时会自动下载所需的模块
5. ✏️ 详细修改步骤
5.1 📝 步骤1:创建Makefile
创建Makefile文件:
makefile
# x-cmd Makefile for OpenHarmony
# x-cmd is a shell script-based command-line toolkit
PREFIX ?= /usr/local
INSTALL_DIR ?= ${PREFIX}/bin
X_CMD_DIR ?= ${PREFIX}/share/x-cmd
all:
@echo "x-cmd is a shell script toolkit, no compilation needed"
@echo "Please run 'make install'"
install:
@echo ""
@echo "Installing x-cmd..."
mkdir -p $(INSTALL_DIR)
mkdir -p $(X_CMD_DIR)
@echo ""
@echo "x-cmd installation completed"
@echo "Installation directory: $(INSTALL_DIR)"
@echo "x-cmd directory: $(X_CMD_DIR)"
@echo ""
@echo "To use x-cmd, run the installation script:"
@echo " eval \"\$$(curl https://get.x-cmd.com)\""
@echo ""
@echo "Or source the x-cmd script if installed locally"
clean:
@echo "Cleaning x-cmd installation..."
rm -rf $(INSTALL_DIR)/x
rm -rf $(X_CMD_DIR)
.PHONY: all install clean
关键步骤:
- ✅ 定义安装路径变量
- ✅ 创建
install目标,创建必要的目录 - ✅ 创建
clean目标,清理安装文件 - ✅ 添加
.PHONY声明
5.2 📝 步骤2:修复build_ohos.sh
修复build_ohos.sh脚本:
bash
#!/bin/bash
# x-cmd OpenHarmony build script
# x-cmd is a shell script-based command-line toolkit
set -e
export X_CMD_INSTALL_HNP_PATH=${HNP_PUBLIC_PATH}/x-cmd.org/x-cmd_0.7.6
sys_prefix=${PREFIX}
export PREFIX=${X_CMD_INSTALL_HNP_PATH}
echo "Installation prefix: ${PREFIX}"
# 创建安装目录
mkdir -p ${X_CMD_INSTALL_HNP_PATH}/bin
mkdir -p ${X_CMD_INSTALL_HNP_PATH}/share/x-cmd
# 先清理旧的构建产物,确保干净环境
make clean || true
# x-cmd是shell脚本工具集,无需编译,直接安装
echo "Installing x-cmd..."
export INSTALL_DIR=${X_CMD_INSTALL_HNP_PATH}/bin
export X_CMD_DIR=${X_CMD_INSTALL_HNP_PATH}/share/x-cmd
make install
# 验证安装
if [ -d "${X_CMD_INSTALL_HNP_PATH}/bin" ]; then
echo "x-cmd installed successfully"
echo "Installation directory:"
ls -lh "${X_CMD_INSTALL_HNP_PATH}/bin" || true
else
echo "Error: x-cmd installation directory not found"
exit 1
fi
# 复制 HNP 打包所需的描述文件
test -f hnp.json
cp hnp.json ${X_CMD_INSTALL_HNP_PATH}/
# 打包HNP和tar.gz
echo "Packing HNP package..."
pushd ${X_CMD_INSTALL_HNP_PATH}/../
${HNP_TOOL} pack -i ${X_CMD_INSTALL_HNP_PATH} -o ${ARCHIVE_PATH}/
echo "Creating tar.gz archive..."
tar -zvcf ${ARCHIVE_PATH}/ohos_x-cmd_0.7.6.tar.gz x-cmd_0.7.6/
popd
export PREFIX=${sys_prefix}
echo "Build completed successfully!"
关键修改:
- ✅ 添加
set -e确保错误时退出 - ✅ 修正tar.gz打包路径(
x-cmd_0.7.6而不是x-cmd.0.7.6) - ✅ 添加安装验证步骤
- ✅ 改进错误处理
5.3 📝 步骤3:创建hnp.json
确保hnp.json配置文件正确:
json
{
"type":"hnp-config",
"name":"x-cmd",
"version":"0.7.6",
"install":{}
}
6. ✅ 构建验证
6.1 🚀 执行构建
bash
cd /Users/baixm/HarmonyOSPC/build
./build.sh --sdk /Users/baixm/ohos-sdk --module x-cmd4oh
6.2 ✅ 构建输出
Installation prefix: /Users/baixm/HarmonyOSPC/data/service/hnp/x-cmd.org/x-cmd_0.7.6
Cleaning x-cmd installation...
Installing x-cmd...
Installing x-cmd...
mkdir -p /Users/baixm/HarmonyOSPC/data/service/hnp/x-cmd.org/x-cmd_0.7.6/bin
mkdir -p /Users/baixm/HarmonyOSPC/data/service/hnp/x-cmd.org/x-cmd_0.7.6/share/x-cmd
x-cmd installation completed
Installation directory: /Users/baixm/HarmonyOSPC/data/service/hnp/x-cmd.org/x-cmd_0.7.6/bin
x-cmd directory: /Users/baixm/HarmonyOSPC/data/service/hnp/x-cmd.org/x-cmd_0.7.6/share/x-cmd
x-cmd installed successfully
Packing HNP package...
[INFO][HNP][hnp_pack.c:116]PackHnp end. srcPath=..., hnpName=x-cmd, hnpVer=0.7.6
Creating tar.gz archive...
Build completed successfully!
6.3 🔍 验证要点
步骤1:将HNP包添加到DevBox项目
- ✅ 将适配完成的
x-cmd.hnp包拷贝到entry/hnp/arm64-v8a目录下
bash
# 从构建输出目录复制x-cmd.hnp到DevBox项目
cp /path/to/build/output/x-cmd.hnp entry/hnp/arm64-v8a/
- ✅ 在
entry/src/main/module.json5配置文件的hnpPackages属性中新增x-cmd配置
json5
{
"package": "x-cmd.hnp",
"type": "public"
}

步骤2:添加x-cmd命令手册
由于x-cmd是一个Shell脚本工具集,主要通过x命令调用各种模块,需要在entry/src/main/ets/pages/manual_data.ets中添加x命令的手册:
typescript
{
name: 'x',
description: 'x-cmd是一个基于POSIX Shell和AWK开发的模块化命令行工具集,提供100+功能模块和500+第三方开源CLI工具。通过x命令可以调用各种功能模块,包括AI功能、环境管理、终端美化等。',
syntax: 'x [OPTIONS] <mod> [ARGS...]',
options: [
{ paramName: '--help, -h', description: '显示帮助信息' },
{ paramName: '--version, -v', description: '显示x-cmd版本信息' },
{ paramName: '<mod>', description: '要调用的功能模块名称,如:openai、gemini、env、theme等' },
{ paramName: '[ARGS...]', description: '传递给模块的参数' }
],
examples: [
'x --help',
'x --version',
'x mod',
'x openai "如何在OpenHarmony上部署应用?"',
'x gemini "解释一下Rust的所有权概念"',
'x env use node',
'x env use python',
'x theme',
'x top',
'x ps',
'x ls',
'x gh',
'x jq \'.name\' file.json'
],
showDetails: false
}
💡 说明 :x-cmd是模块化工具集,通过
x <mod>调用不同模块。常用模块包括:
- 🤖 AI功能 :
x openai,x gemini,x claude- 🖥️ 系统管理 :
x top,x ps,x df- 📁 文件操作 :
x ls,x find,x path- 🫙 Git操作 :
x gh,x gt,x gl- 📦 环境管理 :
x env use node,x env use python- 🎨 终端美化 :
x theme,x font,x cd- 📋 工具调用 :
x jq,x curl,x wget
步骤3:添加开源软件声明
- ✅ 在
entry/src/main/ets/about_diaglog/opensource_list.ets中添加x-cmd的开源声明
typescript
{
"name": "x-cmd",
"license": LicenseType.APACHE_2,
"source": "https://github.com/x-cmd/x-cmd",
"licenseFile": "about_x_cmd_opensource.html",
"showLicense": false
}
📝 注意 :x-cmd采用Apache-2.0许可证,需要确保LicenseType枚举中包含
APACHE_2类型。
- ✅ 添加对应的开源声明HTML文件到
entry/src/main/resources/rawfile/
创建文件:about_x_cmd_opensource.html,内容应包含Apache-2.0许可证的完整文本和x-cmd项目的相关信息。
步骤4:重新构建和安装
- ✅ 重新执行
build-macos.sh完成编译、打包和签名
bash
# 在DevBox项目根目录执行
./build-macos.sh
- ✅ 使用
push.sh脚本安装到开源鸿蒙PC设备
bash
# 确保设备已连接
hdc list targets
# 安装应用
./push.sh entry/build/default/outputs/default/entry-default-signed.hap
步骤5:验证x-cmd功能
安装完成后,在开源鸿蒙PC的终端中验证x-cmd:
bash
# 1. 首先需要安装x-cmd(首次使用)
eval "$(curl https://get.x-cmd.com)"
# 2. 验证x命令是否可用
x --version
# 3. 查看所有可用模块
x mod
# 4. 测试AI功能(需要配置API密钥)
x openai "Hello, x-cmd!"
# 5. 测试环境管理
x env ls
# 6. 测试系统工具
x top
x ps
x ls
# 7. 查看帮助信息
x --help
⚠️ 重要提示:
- x-cmd是Shell脚本工具集,首次使用需要通过官方安装脚本安装
- x-cmd需要网络连接来下载模块和工具
- 某些功能(如AI功能)需要配置相应的API密钥
- 安装x-cmd后,可能需要重新打开终端才能使用
x命令

7. 💻 使用示例
7.1 🚀 安装x-cmd
在OpenHarmony PC上安装x-cmd:
bash
# 方法1:使用官方安装脚本(推荐)
eval "$(curl https://get.x-cmd.com)"
# 方法2:如果网络受限,可以使用wget
eval "$(wget -O- https://get.x-cmd.com)"
# 安装完成后,x-cmd会自动配置到当前Shell环境
7.2 📋 基本命令
🤖 AI功能
bash
# 使用OpenAI进行AI对话
x openai "如何在OpenHarmony上部署应用?"
# 使用Gemini进行AI对话
x gemini "解释一下Rust的所有权概念"
# 使用Claude进行AI对话
x claude "写一个Python函数来计算斐波那契数列"
🖥️ 系统管理
bash
# 查看系统进程(增强版top)
x top
# 查看进程列表(增强版ps)
x ps
# 查看系统信息
x mac # macOS系统信息
📁 文件系统操作
bash
# 增强版ls命令
x ls
# 文件路径操作
x path /home/user/documents
# 磁盘使用情况(增强版df)
x df
🫙 Git操作
bash
# GitHub操作
x gh
# Git工具
x gt
# Git日志查看
x gl
📦 包管理
bash
# 查看可安装的包
x env
# 查看已安装的包
x env ls
# 安装包(例如jq)
x env use jq
# 直接使用包(临时安装)
x jq '.name' file.json
7.3 🎨 终端美化
bash
# 切换终端主题
x theme
# 安装终端字体
x font
# 快速路径导航
x cd
7.4 🔧 环境管理
bash
# 管理Node.js环境
x env use node
# 管理Python环境
x env use python
# 管理Go环境
x env use go
7.5 📚 模块列表
bash
# 查看所有可用模块
x mod
# 查看特定模块的帮助
x <mod> --help
# 例如:查看ip模块帮助
x ip --help
7.6 💡 实际应用场景
场景1:AI辅助开发
bash
# 使用AI生成代码
x openai "写一个Rust函数来解析JSON"
# 使用AI解释代码
x gemini "解释这段Go代码的作用:$(cat main.go)"
场景2:系统监控
bash
# 实时监控系统进程
x top
# 查看系统资源使用情况
x ps -aux
# 查看磁盘使用情况
x df -h
场景3:文件操作
bash
# 增强的文件列表
x ls -la
# 文件搜索
x find . -name "*.rs"
# 文件内容查看
x cat README.md
8. 📚 总结与最佳实践
8.1 ✅ 适配总结
本次适配成功实现了x-cmd工具在OpenHarmony PC平台上的部署:
- ✅ Shell脚本适配: x-cmd是纯Shell脚本工具集,无需编译
- ✅ Makefile配置: 创建了Makefile管理安装过程
- ✅ 构建脚本优化 :
build_ohos.sh脚本添加了安装和验证步骤 - ✅ HNP打包: 成功生成HNP格式的安装包和tar.gz发布包
- ✅ 在线安装支持: 支持通过官方安装脚本安装x-cmd
8.2 🎯 关键技术点
- Shell脚本: x-cmd是纯Shell脚本工具集,无需编译
- 在线安装: 通过官方安装脚本从网络下载和安装
- 模块化设计 : 通过
x <mod>调用不同功能模块 - 按需下载: 模块和工具按需下载,节省存储空间
- 跨平台支持: 支持多种Shell和操作系统
8.3 💡 最佳实践
-
安装配置:
- ✅ 使用官方安装脚本安装x-cmd
- ✅ 确保网络连接正常
- ✅ 首次使用会自动下载所需模块
-
日常使用:
- ✅ 使用
x <mod>调用功能模块 - ✅ 使用
x env管理开发环境 - ✅ 使用AI功能提高开发效率
- ✅ 使用
-
性能优化:
- ✅ 按需下载模块,避免占用过多存储
- ✅ 使用缓存机制加速模块加载
- ✅ 定期清理不需要的模块和工具
8.4 🚀 未来改进方向
-
功能增强:
- 📊 支持更多OpenHarmony特定的模块
- 🔄 优化网络下载速度
- 📈 增强AI功能集成
- 🔍 改进错误处理和提示
-
用户体验:
- ⚡ 改进模块加载速度
- 🎯 优化命令补全功能
- 📝 增强文档和帮助信息
-
文档完善:
- 📖 添加更多OpenHarmony使用示例
- 🔍 添加故障排除指南
- 📚 添加高级用法文档
📚 附录
A. 相关资源
- x-cmd官网: https://x-cmd.com/
- x-cmd中文官网: https://cn.x-cmd.com/
- GitHub仓库: https://github.com/x-cmd/x-cmd
- 安装脚本: https://get.x-cmd.com
- OpenHarmony官网: https://www.openharmony.cn/
B. 常见问题
Q1: x-cmd是什么?
A: x-cmd是一个基于POSIX Shell和AWK开发的模块化命令行工具集,提供100+功能模块和500+第三方CLI工具,支持AI功能、环境管理、终端美化等。
Q2: 如何安装x-cmd?
A: 在OpenHarmony PC终端执行:
bash
eval "$(curl https://get.x-cmd.com)"
Q3: x-cmd需要网络连接吗?
A: 是的,x-cmd采用在线安装机制,首次安装和模块下载需要网络连接。
Q4: 如何查看所有可用模块?
A: 使用x mod命令查看所有可用模块,或访问 https://x-cmd.com/mod/
Q5: 如何使用AI功能?
A: 使用x openai、x gemini、x claude等命令调用不同的AI服务。
Q6: 如何管理开发环境?
A: 使用x env命令管理Node、Python、Go等开发环境:
bash
x env use node # 安装并使用Node.js
x env use python # 安装并使用Python
x env ls # 查看已安装的环境
Q7: x-cmd占用多少存储空间?
A: x-cmd核心包约1.1 MB,模块和工具按需下载,不会占用过多存储空间。
🎉 结语
x-cmd工具为终端用户提供了强大的命令行工具集和AI辅助功能,是提高终端操作效率的重要工具。通过本次适配,x-cmd成功运行在OpenHarmony PC平台上,为鸿蒙生态的开发者提供了丰富的命令行工具和AI能力。