apm-cli — Apt Package Manager CLI

一个用 Python + Bash 实现的极简包管理器，专为 dotfiles 和脚本分发 设计。

Python 只做薄壳（pip install 后给你 apd + apm 两个命令），运行时全靠 bash，不依赖 Python。

---

安装

git clone https://github.com/you/apm-cli.git
cd apm-cli
pip install -e .

安装后获得两个命令：

• apd — Apt Downloader（下载 / 安装 / 更新 / 搜索）
• apm — Apt Manager（管理 / 打包 / 发布 / 诊断）

---

快速开始

# 配置仓库（指向你的 index.json）
export APM_REPO="https://raw.githubusercontent.com/you/apm-repo/main/index.json"

# 更新索引
apd update

# 搜索 & 安装
apd search vim
apd install mydot-vim

# 管理
apm list
apm info mydot-vim
apm remove mydot-vim

---

多生态短命令

短命令	生态	示例
pg	pkg 索引	apd pg vim
ak	apk 索引	apd ak htop
pi	pip (Python)	apd pi requests
nm	npm (Node.js)	apd nm typescript
br	brew (macOS)	apd br wget
ap	apt (Debian/Ubuntu)	apd ap htop
yt	yay (Arch)	apd yt spotify
cr	cargo (Rust)	apd cr ripgrep
go	go install	apd go install ...
do	docker	apd do nginx:alpine
sn	snap	apd sn code
fl	flatpak	apd fl org.mozilla.firefox

每个短命令支持子操作：install(默认) / remove / search / update / download

apd eco                # 列出所有生态
apd pg search neovim   # 在 pkg 索引中搜索
apd pi update requests # pip install --upgrade requests

---

包格式

name-version.tar.gz
├── manifest.toml    # 文件映射、权限、依赖、钩子
├── rversion         # 作者、版本、更新日志
└── name/            # 实际脚本/配置文件
    ├── .config/...
    └── sripts/
        ├── post-install.sh
        └── pre-remove.sh

manifest.toml 示例

name = "mydot-vim"
version = "1.2.0"
description = "我的 Vim/Neovim 配置"

# 文件映射: 包内路径 → 目标路径
[files]
"mydot-vim/.vimrc"          = "~/.vimrc"
"mydot-vim/init.lua"        = "~/.config/nvim/init.lua"

# 权限设置
[permissions]
"~/.config/nvim/init.lua"   = "644"
"~/.local/bin/myhelper"      = "755"

# 依赖声明
[dependencies]
"mydot-bash" = ">=1.0.0"

# 钩子
[hooks]
post_install = "mydot-vim/scripts/post-install.sh"
pre_remove   = "mydot-vim/scripts/pre-remove.sh"

rversion 示例

AUTHOR: Your Name
EMAIL: you@example.com
WEBSITE: https://your-site.com
VERSION: 1.2.0
DATE: 2026-08-16

## [1.2.0] - 2026-08-16
### Added
- 新增 Neovim Lua 配置
- 支持 treesitter

### Fixed
- 修复插件管理器路径错误

---

完整命令列表

apd (下载器)

命令	说明
apd install <包> [版本]	安装包
apd update [包]	更新包（不指定=全部）
apd remove <包>	卸载包
apd search <关键词>	搜索包
apd download <包> [版本]	仅下载不安装
apd list	已安装列表
apd info <包>	包信息
apd eco	生态列表

apm (管理器)

命令	说明
apm list	已安装列表
apm info <包>	详细信息（含 rversion）
apm remove <包>	卸载（支持 pip:xxx 前缀）
apm pack	打包当前目录 → name-version.tar.gz
apm publish <file>	发布包（更新索引 + 上传）
apm version <包> <ver>	切换版本
apm freeze [file]	导出锁文件（默认 stdout）
apm restore <file>	从锁文件恢复全部包
apm verify	校验所有已装文件完整性
apm which <文件>	查询文件属于哪个包
apm doctor	系统诊断
apm log [today|1day|3days|stats]	操作审计日志
apm init [名] [版本] [描述]	创建新包脚手架
apm completion [bash|zsh]	Shell 补全脚本
apm clean-bak	清理 .bak 残留

---

环境变量

变量	说明	默认值
APM_REPO	默认索引 URL	GitHub raw
APM_REPO_PKG	pkg 索引 URL	GitHub raw
APM_REPO_APK	apk 索引 URL	GitHub raw
APM_DB	数据库路径	~/.local/share/apm/installed.json
APM_CACHE	缓存目录	~/.cache/apm
APM_INDEX_REPO	索引 Git 仓库地址	GitHub
APM_PACKAGE_BASE_URL	包下载基础 URL	GitHub releases
APM_S3_BUCKET	S3 上传桶	—
APM_RSYNC_HOST	rsync 目标	—
APM_FORCE	强制覆盖冲突文件	0
APM_OFFLINE	离线模式	0

---

项目结构

apm-cli/
├── setup.py                # pip 安装入口
├── README.md
├── apm/
│   ├── __init__.py
│   └── cli.py             # Python 薄壳，仅转发给 bash
├── sh/
│   ├── apd.sh             # 下载器（install/update/search/download/eco）
│   ├── apm.sh             # 管理器（list/info/remove/pack/publish/version/freeze/restore/verify/which/doctor/log/init/completion/clean-bak）
│   └── lib/
│       ├── detect.sh       # 工具链检测
│       ├── fetch.sh        # 下载（aria2c/curl/wget 降级 + file:// + 错误检测）
│       ├── verify.sh       # SHA256 + GPG 校验
│       ├── extract.sh      # 解包部署 + 权限 + 钩子 + 冲突检测
│       ├── deps.sh         # 依赖递归安装
│       ├── rollback.sh     # 事务快照 + 回滚
│       ├── version.sh      # 版本切换（symlink 管理）
│       ├── ecosystem.sh    # 12 个生态定义中心
│       ├── publish.sh      # 更新 index.json + S3/rsync 上传
│       ├── freeze.sh       # 锁文件导出/恢复 + 文件校验 + which 查询
│       ├── doctor.sh       # 系统诊断
│       ├── log.sh          # 操作审计日志
│       ├── init.sh         # 交互式脚手架生成
│       └── completion.sh   # bash/zsh 自动补全
├── examples/
│   └── mydot-demo/        # 示例包（manifest.toml + rversion + 目录结构）
└── index-repo/
    ├── README.md
    └── index.json         # 索引示例

---

典型工作流

开发者：创建并发布包

# 1. 创建脚手架
cd ~/projects
apm init mydot-vim 1.0.0 "我的 Vim 配置"

# 2. 编辑 manifest.toml，把实际文件放进 mydot-vim/
vim mydot-vim/manifest.toml
cp ~/.vimrc mydot-vim/.vimrc

# 3. 打包
apm pack
# → mydot-vim-1.0.0.tar.gz

# 4. 发布（自动更新 index.json + 上传）
apm publish mydot-vim-1.0.0.tar.gz

用户：一键恢复环境

# 在新机器上
pip install apm-cli
export APM_REPO="https://raw.githubusercontent.com/you/apm-repo/main/index.json"

# 从锁文件恢复全部包
apm restore my-lock-file

用户：导出当前环境

apm freeze > my-lock-file
# 提交到 Git，换机器时直接 restore

---

设计原则

1. Python 只是安装入口 — 运行时零 Python 依赖
2. Bash 做所有脏活 — 下载、解包、部署、校验全在 sh 里
3. 数据库是 JSON — 人类可读，jq 可查，git 可 diff
4. 包格式简单 — tar.gz + toml 元数据，不发明新格式
5. 生态可扩展 — 加新生态只改 ecosystem.sh 一个文件

---

License

MIT