Xpert Plugin: Zip

@xpert-ai/plugin-zip is a file compression/decompression toolset plugin for the Xpert AI agent platform. It equips agents with Zip and Unzip tools so they can package intermediate artifacts or inspect uploaded archives directly inside workflows.

Installation

pnpm add @xpert-ai/plugin-zip
# or
npm install @xpert-ai/plugin-zip

Note: This plugin depends on @xpert-ai/plugin-sdk, @nestjs/common@^11, @nestjs/config@^4, @langchain/[email protected], [email protected], and [email protected] as peer dependencies. Install these in the host project before enabling the plugin.

Quick Start

1. Install & Build
   Add the dependency to your host service and rebuild to make the plugin discoverable.

2. Register the Plugin
   Include the package in your plugin list (environment variable or configuration):

   PLUGINS=@xpert-ai/plugin-zip

   The plugin bootstraps the ZipPlugin NestJS module, registers the toolset, and emits lifecycle logs.

3. Provision Toolsets for Agents

   • Xpert Console: add a Built-in Toolset instance and choose Zip.
   • API: request toolset zip.

   No credentials or secrets are required, so any authorized agent can immediately create instances.

Zip Toolset

| Field | Value | | ------------ | --------------------------------------------------------------------- | | Name | zip | | Display Name | Zip / 压缩文件 | | Category | tools | | Description | Compress multiple files or extract archives inside agent workflows. | | Config | No configuration or external integrations are needed. |

The toolset wraps jszip to read/write archives fully in memory. Files are exchanged as base64 strings so they can travel safely through JSON payloads.

Tools

| Tool | Purpose | Input Highlights | Output | | --------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | | zip | Bundle multiple files into a .zip archive and return it as a base64 payload. | files[]: each entry accepts name/filename plus content (string, Buffer, or Uint8Array). Optional file_name controls the resulting archive name (defaults to files.zip). | JSON string with blob (base64 zip), mime_type, filename. | | unzip | Extract every file from a .zip archive, with MIME types inferred from extensions. | file: supply name/filename ending in .zip plus content/blob (Buffer, Uint8Array, or base64 string). Directories are skipped automatically. | JSON string containing files[] entries with blob, mime_type, filename. |

Example Payloads

// Zip
{
  "tool": "zip",
  "input": {
    "files": [
      { "name": "README.md", "content": "# intro" },
      { "name": "data/data.json", "content": "{\"value\": 1}" }
    ],
    "file_name": "bundle.zip"
  }
}

// Unzip
{
  "tool": "unzip",
  "input": {
    "file": {
      "name": "bundle.zip",
      "blob": "<base64-encoded zip>"
    }
  }
}

Each tool returns JSON text. Agents typically parse it (JSON.parse(result)) to access the binary data as base64 strings. Invalid inputs produce friendly error strings generated by getErrorMessage.

MIME Detection & Behavior

• Built-in mapping covers common document types (.md, .docx, .xlsx, .pptx), code files (.py, .ts, .json, etc.), images (.webp, .svg, .ico), and other formats (.csv, .env, .gitignore).
• Unknown extensions default to application/octet-stream.
• The Zip tool ignores empty file entries; the Unzip tool skips directories and returns an error if the archive is empty or invalid.

Permissions & Security

• No external network calls: All compression/decompression happens locally.
• Filesystem: Tools operate on memory buffers; granting file-system permissions is unnecessary unless your agent independently reads/writes files.
• Logging: Only lightweight lifecycle logs are emitted (register, onStart, onStop).

Development & Testing

npm install
npx nx build @xpert-ai/plugin-zip
npx nx test @xpert-ai/plugin-zip

Refer to packages/zip/README-TEST.md (and the Chinese variant) for manual testing instructions. Build artifacts land in packages/zip/dist; ensure compiled files, type declarations, and package metadata are aligned before publishing.

License

This project follows the AGPL-3.0 License located at the repository root.