# zdxlz-ai-plugin

**Repository Path**: devonkey/zdxlz-ai-plugin

## Basic Information

- **Project Name**: zdxlz-ai-plugin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-01
- **Last Updated**: 2026-05-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zdxlz-ai-plugin

`zdxlz-ai-plugin` is a cross-platform CLI for installing, updating, and uninstalling AI plugin bundles from `zdxlz-ai-tools`.

## Purpose

Allow users with repository access to install standardized AI assets from a central catalog.

## Repositories

- Plugin repo: `https://gitlab.zdxlz.com/common/zdxlz-ai-plugin`
- Tools repo (default clone URL): `git@gitee.com:devonkey/zdxlz-ai-tools.git`

Override with `ZDXLZ_AI_TOOLS_REPO_URL` if needed.

## Features

- Default sync from `main` branch of `zdxlz-ai-tools`
- `install`, `update`, and `uninstall` for one plugin or `all`
- **IDE targets**: **cursor** (default), **qoder**, **trae** via `--ide` / trailing argument / `ZDXLZ_IDE`
- `--scope user|project` (default **user**): skills/MCP under user or project; **rules always under cwd** in `./.<ide>/rules/`
- Manifest under cwd: `./.<ide>/zdxlz-ai-plugin/<plugin>.json`
- `**--help` / `-h`**: Chinese usage (`node src/cli.js --help`)
- Backward-compatible `/add-plugin` entry (`ZDXLZ_IDE` respected)
- Single-platform build script: default macOS; choose linux-amd64 / linux-arm64 / windows via --platform

## Quick Start (Node)

Install:

```bash
npm --prefix /path/to/zdxlz-ai-plugin run install-plugin -- engineering-core
```

Install everything listed in `index.json`:

```bash
npm --prefix /path/to/zdxlz-ai-plugin run install-all -- --scope user
```

Update:

```bash
npm --prefix /path/to/zdxlz-ai-plugin run update-plugin -- engineering-core
```

Uninstall:

```bash
npm --prefix /path/to/zdxlz-ai-plugin run uninstall-plugin -- engineering-core
```

Uninstall all plugins from the catalog:

```bash
npm --prefix /path/to/zdxlz-ai-plugin run uninstall-all
```

Project-scoped skills/MCP (rules still use cwd):

```bash
node /path/to/zdxlz-ai-plugin/src/cli.js install engineering-core --scope project
```

Qoder / Trae (paths map `.cursor/...` in the catalog to `.qoder/` or `.trae/`):

```bash
node /path/to/zdxlz-ai-plugin/src/cli.js install hello qoder
node /path/to/zdxlz-ai-plugin/src/cli.js install hello --ide trae
```

Chinese CLI help:

```bash
node /path/to/zdxlz-ai-plugin/src/cli.js --help
```

Backward-compatible slash command:

```bash
npm --prefix /path/to/zdxlz-ai-plugin run add-plugin -- engineering-core
```

## Build Executable

Default build (macOS x64 only):

```bash
cd /path/to/zdxlz-ai-plugin
npm install
npm run build
```

Other platforms (one at a time):

```bash
npm run build:linux-amd64
npm run build:linux-arm64
npm run build:windows
npm run build:mac
```

Show build help:

```bash
bash scripts/build.sh --help
```

Proxy examples:

```bash
# local build (mac/linux-amd64/windows)
HTTPS_PROXY=http://127.0.0.1:7890 npm run build:windows

# Docker linux-arm64
HTTPS_PROXY=http://host.docker.internal:7890 HTTP_PROXY=http://host.docker.internal:7890 npm run build:linux-arm64
```

Expected artifacts under `dist/`:

- `zdxlz-ai-plugin-macos` (Intel macOS)
- `zdxlz-ai-plugin-linux` (amd64)
- `zdxlz-ai-plugin-win.exe`
- `zdxlz-ai-plugin-linux-arm64` (aarch64, from Docker script when successful)

Run executable:

```bash
./dist/zdxlz-ai-plugin-macos install engineering-core
./dist/zdxlz-ai-plugin-macos install all --scope user
./dist/zdxlz-ai-plugin-macos uninstall all
```

## Environment Variables

- `ZDXLZ_IDE`: default IDE `cursor` | `qoder` | `trae`
- `ZDXLZ_AI_TOOLS_REPO_URL`: tools repository URL (default: Gitee SSH URL above)
- `ZDXLZ_AI_TOOLS_BRANCH`: tools branch name (default: `main`)
- `ZDXLZ_AI_TOOLS_PATH`: local cache path for cloned tools repository
- `ZDXLZ_INSTALL_ROOT`: project root for **project-scoped** skills/MCP (default: cwd)
- `ZDXLZ_SCOPE`: default scope `user` | `project`
- `ZDXLZ_USER_CURSOR_HOME`: Cursor user dir (default `~/.cursor`)
- `ZDXLZ_USER_QODER_HOME`: Qoder user dir (default `~/.qoder`)
- `ZDXLZ_USER_TRAE_HOME`: Trae user dir (default `~/.trae`)
- `ZDXLZ_AI_TOOLS_OFFLINE`: set to `1` to skip `git fetch/pull` when using a local checkout

## How It Works

- The installer clones `zdxlz-ai-tools` from `main` into `~/.cache/zdxlz-ai/zdxlz-ai-tools` unless `ZDXLZ_AI_TOOLS_PATH` is set.
- Catalog paths use `.cursor/...`; for `**--ide qoder`** or `**trae**`, files map to `./.qoder/...` or `./.trae/...` (and matching user home dirs).
- **Rules** (`.mdc`) are workspace-bound: install from the **project root** into `./.<ide>/rules/`.
- `**--scope user`** (default): skills → `~/.<ide>/skills/`, MCP → `~/.<ide>/mcp/`.
- `**--scope project**`: skills/MCP → `./.<ide>/skills|mcp` under `ZDXLZ_INSTALL_ROOT`.
- Manifest: `./.<ide>/zdxlz-ai-plugin/<plugin>.json` (legacy `.cursor/zdxlz-ai-plugin/` still supported for cursor uninstall).

## Slash Command Mapping

In Cursor workflows, map `/add-plugin <name>` to:

```bash
npm --prefix /path/to/zdxlz-ai-plugin run add-plugin -- <name>
```

Executable mapping:

```bash
/path/to/zdxlz-ai-plugin/dist/zdxlz-ai-plugin-macos install <name>
```