z-cli

Agent-First CLI Toolkit for Extensible Automation

面向 AI Agent 的命令行工具集，集成各类自动化脚本。Skills 只需调用命令即可，无需维护复杂脚本。使用 TypeScript 开发，支持 Node.js 和 Bun。

🎯 设计理念

graph LR
    A[AI Agent] --> B[Skills]
    B --> C[z-cli Commands]
    C --> D[Image Compression]
    C --> E[i18n Management]
    C --> F[Future Scripts...]
    
    style A fill:#e1f5ff
    style B fill:#fff4e6
    style C fill:#f3e5f5
    style D fill:#e8f5e9
    style E fill:#e8f5e9
    style F fill:#e8f5e9

核心目标：将常用自动化脚本封装为 CLI 命令，Skills 描述调用方式即可，Agent 直接执行。

当前命令：

• tiny - 高性能图片压缩（基于 Sharp）

未来扩展：

• i18n 管理
• 代码生成
• 文件批处理
• ...更多 Agent 能力增强命令

✨ 特性

• 🤖 Agent 优先 - 专为 AI Agent 工作流设计
• 🔧 开箱即用 - 无需配置复杂脚本，直接调用命令
• 📦 持续扩展 - 后续命令聚焦 Agent 能力增强
• ⚙️ 灵活配置 - 支持持久化配置，命令行参数优先
• 💻 跨平台 - Windows, macOS, Linux 全平台支持
• 🔧 TypeScript - 完整类型支持，可用于 Skills 集成

📦 安装

使用 Bun（推荐）

Bun 是更快的 JavaScript 运行时，推荐使用。

# 安装 Bun
curl -fsSL https://bun.sh/install | bash  # macOS/Linux
# 或
powershell -c "irm bun.sh/install.ps1 | iex"  # Windows

# 全局安装 z-cli
bun install -g @zzclub/z-cli

使用 Node.js

# 要求 Node.js >= 18.18.0
npm install -g @zzclub/z-cli
# 或
pnpm add -g @zzclub/z-cli

🚀 快速开始

基础用法

# 压缩单个图片（默认质量 75）
z tiny -f ./image.jpg

# 指定压缩质量（1-100，数值越高质量越好）
z tiny -f ./image.jpg -q 80

# 压缩整个目录
z tiny -f ./images -r

# 覆盖原文件
z tiny -f ./image.jpg -o

# 指定输出目录
z tiny -f ./image.jpg --output ./compressed

命令别名

支持三种命令别名，完全等价：

z tiny -f ./image.jpg
zz tiny -f ./image.jpg
z-cli tiny -f ./image.jpg

📖 命令列表

tiny - 图片压缩

高性能图片压缩命令，基于 Sharp（libvips），比传统工具快 4-5 倍。

特性：

• 多格式支持：JPEG, PNG, WebP
• 智能算法：自动选择 mozjpeg（JPEG）和 pngquant（PNG）
• 批量处理：支持递归目录

压缩单个文件或整个目录的图片。

z tiny [options]

选项：

| 选项 | 别名 | 类型 | 默认值 | 说明 | |------|------|------|--------|------| | --file <path> | -f | string | - | 要压缩的文件或目录路径（必需） | | --quality <1-100> | -q | number | 75 | 压缩质量，1-100 之间 | | --recursive | -r | boolean | false | 递归处理目录 | | --overwrite | -o | boolean | false | 覆盖原文件 | | --output <dir> | - | string | - | 指定输出目录 | | --help | -h | - | - | 显示帮助信息 |

支持的图片格式：

• JPEG / JPG (mozjpeg 优化)
• PNG (pngquant 优化)
• WebP

示例：

# 压缩单个图片，质量 80
z tiny -f ./photo.jpg -q 80

# 递归压缩目录下所有图片
z tiny -f ./images -r

# 覆盖原文件
z tiny -f ./photo.jpg -o

# 输出到指定目录
z tiny -f ./images -r --output ./dist

# 组合使用
z tiny -f ./images -r -q 90 --output ./compressed

压缩效果示例：

✔ 压缩成功: 21.83 KB → 5.88 KB (减少 73.1%)

╭───────────────────╮
│                   │
│  压缩完成         │
│                   │
│  总文件数: 5      │
│  成功: 5          │
│  失败: 0          │
│  总原始大小: 2.1 MB │
│  总压缩后大小: 580 KB │
│  平均压缩率: 72.4% │
│                   │
╰───────────────────╯

set - 更新配置

设置默认配置，影响后续所有命令。

z set [options]

选项：

| 选项 | 别名 | 类型 | 说明 | |------|------|------|------| | --quality <1-100> | -q | number | 设置默认压缩质量 | | --recursive | -r | boolean | 设置默认是否递归 | | --overwrite | -o | boolean | 设置默认是否覆盖 | | --output <dir> | - | string | 设置默认输出目录 |

示例：

# 设置默认质量为 90
z set -q 90

# 设置默认递归处理
z set -r

# 设置默认覆盖原文件
z set -o

# 设置默认输出目录
z set --output ./compressed

# 一次设置多个
z set -q 85 -r --output ./dist

config - 查看/管理配置

查看当前配置或管理配置文件。

z config [options]

选项：

| 选项 | 说明 | |------|------| | --path | 显示配置文件路径 | | --reset | 重置配置为默认值 | | 无参数 | 显示当前配置（JSON 格式） |

示例：

# 查看当前配置
z config

# 查看配置文件路径
z config --path

# 重置为默认配置
z config --reset

配置文件位置：

• Linux: ~/.config/zzclub-z-cli/config.json（或 $XDG_CONFIG_HOME/zzclub-z-cli/config.json）
• macOS: ~/Library/Application Support/zzclub-z-cli/config.json
• Windows: %APPDATA%\zzclub-z-cli\config.json

默认配置：

{
  "tiny": {
    "quality": 80,
    "recursive": false,
    "overwrite": false,
    "outputDir": null,
    "verbose": false
  }
}

🔌 在 Skills 中使用

z-cli 专为 Agent + Skills 工作流设计。Skills 只需描述命令调用方式，Agent 即可执行。

架构说明

Agent（决策层）
  ↓ 调用
Skill（描述层）
  ↓ 执行
z-cli（工具层）
  ↓ 集成
各类 Scripts（实现层）

优势：

• Skills 无需维护复杂脚本逻辑
• 命令版本统一管理
• Agent 可直接调用，无额外依赖

前置要求

确保已安装 Bun 或 Node.js:

# 检查 Bun 是否安装
bun --version

# 如果未安装,安装 Bun(推荐)
curl -fsSL https://bun.sh/install | bash  # macOS/Linux
# 或
powershell -c "irm bun.sh/install.ps1 | iex"  # Windows

基础用法

# 使用 bunx(推荐)
bunx @zzclub/z-cli tiny -f ./images -r -q 85

# 或使用 npx(Node.js)
npx @zzclub/z-cli tiny -f ./images -r -q 85

在 Skill 的 skill.md 中使用

直接在你的 Skill 说明中添加压缩命令即可:

## 图片处理流程

1. 下载图片到 `./downloads` 目录
2. 压缩图片:
   ```bash
   bunx @zzclub/z-cli tiny -f ./downloads -r -q 85 --output ./compressed

3. 上传压缩后的图片

### 常用命令

```bash
# 压缩单个文件
bunx @zzclub/z-cli tiny -f ./image.jpg -q 80

# 递归压缩目录
bunx @zzclub/z-cli tiny -f ./images -r -q 85

# 压缩并覆盖原文件
bunx @zzclub/z-cli tiny -f ./images -r -o

# 压缩到指定目录
bunx @zzclub/z-cli tiny -f ./images -r --output ./compressed

# 查看帮助
bunx @zzclub/z-cli --help

优势

• ✅ 自动安装依赖 - bunx/npx 会自动下载 z-cli 及其依赖(包括 Sharp)
• ✅ 无需全局安装 - 每次运行时自动使用最新版本
• ✅ 简单直接 - 一行命令完成压缩

🛠️ 开发

克隆仓库

git clone https://github.com/aatrooox/z-cli.git
cd z-cli

安装依赖

# 使用 Bun（推荐）
bun install

# 或使用 pnpm
pnpm install

开发模式

# 直接运行 TypeScript 源码
bun run dev

# 或
bun run src/index.ts tiny -f ./demo/demo3.jpeg -q 80

构建

# 编译 TypeScript
bun run build

# 类型检查
bun run type-check

本地测试

# 链接到全局
npm link  # 或 bun link

# 测试命令
z tiny -f ./demo/demo3.jpeg -q 80

发布

# 发布补丁版本 (1.0.0 -> 1.0.1)
bun run release:patch

# 发布次要版本 (1.0.0 -> 1.1.0)
bun run release:minor

# 发布主要版本 (1.0.0 -> 2.0.0)
bun run release:major

📊 性能对比

基于 Sharp (libvips) 的性能优势：

| 工具 | 处理 100 张图片 (平均) | 内存占用 | |------|------------------------|----------| | z-cli (Sharp) | ~2.5s | ~50MB | | ImageMagick | ~12s | ~200MB | | GraphicsMagick | ~10s | ~180MB |

🤝 贡献

欢迎提出新需求或贡献代码！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

📝 更新日志

v1.0.0 (2026-01-20)

🎉 重大重构 - TypeScript 重写

• ✅ 完全使用 TypeScript 重写
• ✅ 简化功能，专注于图片压缩
• ✅ 移除 Commander.js，使用原生 CLI 实现
• ✅ 使用 Consola 统一日志输出
• ✅ 支持 Bun 运行时
• ✅ 完整的类型定义
• ❌ 移除 translate 命令（i18n 翻译）
• ❌ 移除 picgo 命令（图床上传）
• ❌ 移除 i18n 命令（Vue i18n 提取）

迁移指南：

如果你需要旧版本的翻译功能，请使用 v0.8.0：

npm install -g @zzclub/[email protected]

或切换到备份分支：

git checkout backup/v0.8.0

📄 许可证

MIT License © 2026 aatrox

📮 联系方式

• 作者：aatrox
• GitHub：@aatrooox
• 项目地址：github.com/aatrooox/z-cli
• 微信：523748995（定制需求或技术支持）

⚠️ 免责声明

任何用户在使用 z-cli 前，请您仔细阅读并透彻理解本声明。您可以选择不使用 z-cli，若您一旦使用 z-cli，您的使用行为即被视为对本声明全部内容的认可和接受。

1. 任何单位或个人因下载使用 z-cli 而产生的任何意外、疏忽、合约毁坏、诽谤、版权或知识产权侵犯及其造成的损失（包括但不限于直接、间接、附带或衍生的损失等），本人不承担任何法律责任。

2. 任何单位或个人不得在未经本团队书面授权的情况下对 z-cli 工具本身申请相关的知识产权。

3. 如果本声明的任何部分被认为无效或不可执行，则该部分将被解释为反映本人的初衷，其余部分仍具有完全效力。不可执行的部分声明，并不构成我放弃执行该声明的权利。

⭐ 如果这个工具对你有帮助，欢迎给个 Star！