Xpert Plugin Registry

The Xpert Plugin Registry aggregates plugin metadata submitted by Xpert official team, partners, and community contributors, and publishes a unified plugin list automatically via GitHub Pages. The XpertAI Plugin Marketplace fetches the generated list from https://xpert-ai.github.io/xpert-plugin-registry/plugins/index.json to display various plugins in the product.

Directory Structure

• official/: Plugins maintained by the Xpert official team. Once merged, they are marked as verified (verified: true).
• partner/: Plugins submitted by Xpert certified partners. Default verified: false, managed through the partnership program.
• community/: Plugins submitted by community developers. Default verified: false, open to any compliant contributions.
• plugins/index.json: Aggregated file automatically generated by scripts and CI (do not edit manually).
• scripts/build-registry.mjs: Aggregation script that reads the above directories and outputs the unified list.

Plugin List Structure

The top-level index.json file contains the following fields:

Field	Type	Description
updatedAt	string	Last build time of the list (ISO 8601).
total	number	Total number of plugins.
official	string[]	List of name for all official plugins.
community	string[]	List of name for all community plugins.
plugins	object[]	Full metadata object for each plugin.

Fields in a single plugin object within plugins:

Field	Type	Required	Description
name	string	✅	Unique plugin identifier, recommended to use npm package name or @scope/name.
displayName	string	✅	Display name.
description	string	✅	Brief description of functionality.
version	string	✅	Current version, semantic versioning (semver).
category	string	⭕️	Plugin category, for marketplace display.
keywords	string[]	⭕️	Keyword tags.
author.name / author.url	string	⭕️	Author information.
repository	string	⭕️	Plugin source repository URL.
icon.type / icon.value	string	⭕️	Icon type and content (e.g., svg).
source.type / source.url	string	⭕️	Distribution channel info, such as npm, git, etc.
readme	string	⭕️	Link to detailed plugin documentation.
updatedAt	string	⭕️	Metadata update time; if omitted, current time will be written during build.
verified	boolean	Auto	Automatically assigned based on directory; do not set manually.

✅: Required; ⭕️: Optional but recommended.

How to Submit a Plugin

1. Fork this repository and create a new branch.
2. Choose the directory based on your role:

• Official team: official/
• Partner: partner/
• Community developer: community/

3. Create a new .json file named after your plugin identifier (e.g., my-plugin.json) and fill in the metadata.
4. Run local validation (optional, see next section) to ensure the list can be built successfully.
5. Submit a Pull Request and fill out the plugin information and compliance confirmation as per the repository template.

Example metadata file:

{
  "name": "@xpert-ai/plugin-sample",
  "displayName": "Sample Connector",
  "description": "Connects Sample API to Xpert.",
  "version": "1.0.0",
  "category": "Integration",
  "keywords": ["sample", "connector"],
  "author": {
    "name": "XpertAI Community",
    "url": "https://xpert.ai"
  },
  "repository": "https://github.com/xpert-ai/plugin-sample",
  "icon": {
    "type": "svg",
    "value": "<svg>...</svg>"
  },
  "source": {
    "type": "npm",
    "url": "https://www.npmjs.com/package/@xpert-ai/plugin-sample"
  },
  "readme": "https://github.com/xpert-ai/plugin-sample#readme",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Tip: Please keep the SVG in icon.value as a single line or use escaping to avoid breaking the JSON structure.

Local Build & Validation

This repository uses Node.js 20 (same as CI) to build the registry:

npm install
npm run build:registry

The command generates the aggregated file under plugins/index.json. If there are syntax errors in new metadata files, the script will output failure information in the terminal—please fix according to the prompts.

Automation Workflow

• GitHub Actions workflow: .github/workflows/deploy-registry.yml
• Triggers: Push to main or manual execution, and changes involving official/, partner/, community/, scripts/ directories or workflow files.
• Workflow steps: Install dependencies → run npm run build:registry → publish the plugins/ directory to the gh-pages branch → generate GitHub Pages.

Contribution Notes

• Please read and follow the release and privacy requirements in the Pull Request template.
• Ensure your plugin is compatible with both Xpert Community and Cloud editions, and has been thoroughly tested.
• After your PR is merged, GitHub Pages will update automatically and the plugin marketplace will fetch the latest registry.

If you have questions or need to add new fields, feel free to open an Issue. Thank you for contributing to the XpertAI plugin ecosystem!