hicmd 0.1.0

基于 Conan 2.x 的鸿蒙 PC 系统包管理器 — 制品投影层

hicmd

基于 Conan 2.x 二次开发的命令行包管理器，面向鸿蒙 PC（OpenHarmony PC）系统软件的安装、投影与生命周期管理。

定位

hicmd 不取代 Conan，而是 Conan 制品仓之上的系统投影层（projection layer）：

• Conan 负责：依赖解析、graph 构建、package_id 计算、远端协议、本地 cache 拉取
• hicmd 负责：把 cache 里的预编译制品暴露成可运行/可链接的系统入口，处理冲突、反向依赖、版本切换
• 包索引：hicmd 维护独立的包索引（index/packages.json），用户通过包名安装，不感知 Conan ref 格式

对标 Homebrew 的用户体验，但底层依赖解析复用 Conan，不重复造轮子。

核心设计思想

1. 统一 prefix + symlink 汇聚 —— 所有包投影到同一个 <prefix>/，bin/lib/include 各自汇聚。用户只需配置一次 PATH/LD_LIBRARY_PATH/CMAKE_PREFIX_PATH，装任何包后自动生效。
2. 三层元数据策略 —— 标准 conan 包不可改，投影元数据从包内 cpp_info 自动推断（80%）+ 文件启发式（10%）+ 外部 override 仓库（10%）。
3. Manifest DB 为唯一事实来源 —— SQLite 单文件，记录"装了什么、装在哪、谁依赖谁、暴露了什么"。
4. 默认拒绝冲突 —— 不做自动决策，路径冲突默认报错，用户显式 --force 覆盖。
5. 包索引驱动 —— hicmd 维护 index/packages.json 作为可用包目录，hicmd update 通过纯 HTTP 下载索引，hicmd search 基于本地索引，不依赖 Conan search API。

快速上手

hicmd init                  # 初始化 prefix + 写 shell 配置
hicmd update                # 更新包索引（纯 HTTP 下载）
hicmd install <pkg>         # 安装（下载 + 投影）
hicmd search [keyword]      # 搜索本地包索引（无参数列出全部）
hicmd list                  # 列出已装包
hicmd info <pkg>            # 包详情 + 依赖链
hicmd uninstall <pkg>       # 卸载（反向依赖检查 + 精确回收）
hicmd autoremove            # 清理不再被需要的依赖包
hicmd upgrade <pkg>         # 升级到最新版本
hicmd switch <pkg> <ver>    # 切换已安装包的 link 版本
hicmd link <pkg>            # 将 unlinked 的包暴露到汇聚区
hicmd unlink <pkg>          # 将包从汇聚区移除（保留 Cellar）
hicmd doctor                # 环境诊断

安装命令支持多种语法：

hicmd install zlib                    # 包名（自动选最新版本）
hicmd install zlib==1.3.1             # pip 风格（包名==版本）
hicmd install zlib/1.3.1              # Conan 风格兼容
hicmd install zlib/1.3.1 # 完整 ref

文档索引

文档	内容
架构设计	四层模型、组件职责、与 Conan 的边界
目录布局	hicmd 与 Conan 各自的目录边界，鸿蒙 PC 差异点标注
Manifest DB	SQLite 表结构、事务模型、查询样例
安装流程与冲突仲裁	投影流程、冲突类型、仲裁策略、统一 env
元数据策略	三层推断、override 仓库结构、schema 契约
Conan API 适配	Conan 2.x Python API 用法、PoC 验证结论
MVP 开发路线	分阶段实现顺序与验收标准

制品仓

• 仓库地址：https://cnb.cool/OpenHarmonyPCDeveloper/Conan
• 远端配置：conan remote add ohpcd https://conan.cnb.cool/OpenHarmonyPCDeveloper/Conan/-/packages/
• 制品为标准 Conan 2.x 包，由专门团队按 conan 协议上传，不可修改
• 包索引远端：https://gitcode.com/api/v5/repos/OpenHarmonyPCDeveloper/hicmd/raw/index/packages.json?ref=main，纯 HTTP 下载（urllib），无 git 依赖

安装

# 从源码安装（开发模式）
pip install -e .

# 从 sdist 安装
pip install dist/hicmd-0.1.0.tar.gz

# 开发依赖（含 pytest、build）
pip install -e ".[dev]"

开发

# 运行全部测试（94 个：87 单元 + 7 集成）
python -m pytest tests/ -v

# 构建 sdist
python -m build --sdist

技术栈

• 语言：Python 3.11+（直接复用 Conan API，无跨语言开销）
• CLI 框架：Click / Typer
• 存储：SQLite（标准库自带）
• 输出：Rich（彩色、进度条、表格）
• 依赖：conan >= 2.0

鸿蒙 PC 适配说明

本文档已基于鸿蒙 PC 真机环境（HongMeng Kernel 1.12.0, aarch64, OHOS）完成验证。所有涉及文件系统路径、环境变量、动态库加载的差异点均已确认并修正为鸿蒙实际值。

已确认的关键环境事实

项目	鸿蒙实际值
可写根路径	$HOME（/storage/Users/currentUser），/opt 不存在、/data 不可写、/tmp 只读
交互 Shell	zsh（/usr/bin/zsh），rc 文件为 ~/.zshrc；系统 shell 为 /system/bin/sh
Conan home	$HOME/.conan2，可持久化写入
Conan profile	os=OHOS（非 Linux），arch=armv8，compiler=clang/15
LD_LIBRARY_PATH	标准名称，已生效，无需 ldconfig（鸿蒙无 ldconfig）
symlink	完整支持，在 $HOME 下正常创建和解析
可执行文件格式	ELF（ARM64），magic number 判断不受影响
无 SELinux	无额外执行限制

与用户现有环境的隔离

用户 .zshrc 已配置 $HOME/usr/local 作为手动安装前缀（bin/lib/include + PATH + LD_LIBRARY_PATH + CMAKE_PREFIX_PATH）。hicmd 使用独立的 $HOME/.hicmd 作为 prefix，两者物理隔离、互不干扰。

开源协议

hicmd 使用 Apache License 2.0 开源协议。

第三方依赖及其协议声明见 NOTICE 文件。

• Conan 2.x — MIT License
• Click — BSD-3-Clause License
• Rich — MIT License
• PyYAML — MIT License
• portalocker — BSD-3-Clause License