XpertAI Plugin Repository

This is the source code repository for plugins on the XpertAI platform. The xpertai/ folder contains officially maintained plugin projects. Partners or community contributors can create independent project folders in the root directory according to their company or organization, and maintain their own plugin code within. For plugin development and release processes, please refer to the official documentation: https://xpertai.cn/docs/plugin/.

Repository Structure

• xpertai/: Official plugin projects, managed with the Nx build tool for multiple plugin packages.
• agent-plugins/: Portable Agent Plugins resource packages (Exa, Notion, Linear, Supabase, Sentry and Canva China), with their own packaging tools and upstream comparison. These use ZIP/Git import, not the native npm/Nest plugin lifecycle; see the quickstart.
• <your-org>/: Partner or community contributor plugin directories (example). Please create a top-level directory using your company or organization’s English name, and maintain plugin projects within.

Getting Started

1. Clone the repository and enter the root directory. The repository root and xpertai/ are separate pnpm workspaces; official plugin commands run from xpertai/.
2. To view or participate in official plugin development:
   • Enter xpertai/ and run corepack pnpm install to install dependencies.
   • Use corepack pnpm exec nx graph or corepack pnpm exec nx list to explore current plugins and tasks.
   • Common commands:
     • corepack pnpm exec nx build <project> to build a plugin.
     • corepack pnpm exec nx test <project> to run unit tests.
     • corepack pnpm exec nx lint <project> to perform code linting.
3. To create a new partner plugin:
   • Add a new <your-org>/ (your company/organization’s English name) directory in the repository root.
   • Refer to the official documentation or the sample projects in xpertai/ to initialize your project structure.
   • You can also use the plugin project template repository to get started quickly: https://github.com/xpert-ai/xpert-plugins-starter.
   • It is recommended to provide a README or documentation explaining the plugin’s purpose, dependencies, and usage.

Development and Contribution Process

• Please follow the coding, testing, and release standards in your project directory, and ensure local builds and tests pass before submitting.
• Before submitting a Pull Request, please ensure:
  • Your code passes necessary Lint, Test, and Build checks.
  • Relevant documentation is updated (such as plugin README, CHANGELOG, etc.).
  • You comply with your organization’s internal naming and branching conventions, as well as those of this repository.
• For changes to public files or official plugins, please communicate with the maintenance team first to ensure alignment.

Plugin Release and Registration

Reproducible dependencies

Each release workspace pins pnpm in its root package.json and commits its own pnpm-lock.yaml. Use the Corepack pnpm shim so commands select that version. After changing dependencies, regenerate the lockfile in the owning workspace:

pnpm -C xpertai install --lockfile-only --no-frozen-lockfile --ignore-scripts
# Use -C community for community packages.
node scripts/check-release-dependencies.mjs

Stage dependency declarations and their lockfile together. Enable the repository hooks with git config core.hooksPath .githooks. The pre-commit check validates the staged Git snapshot, so an unstaged lockfile fix or existing node_modules cannot hide a broken commit. It rejects dependencies pointing outside the repository or at untracked local files. Use published SDK/contracts versions; keep experiments against an adjacent platform checkout out of committed manifests.

The Release Dependencies workflow runs the same offline frozen-lockfile check, installs the locked dependencies, and builds the community plugins on PRs and merge-queue results. Configure both Frozen dependencies (xpertai) and Frozen dependencies (community) as required checks in the branch rules to prevent bypassing this gate. Release installs also stay frozen; Changesets version PRs regenerate the lockfile after updating package versions. This checks dependency reproducibility, not plugin build correctness or npm publish access.

Release Workflow (Validated)

This repository uses .github/workflows/release-plugin.yml to release plugins in each workspace (xpertai, community) with Changesets + OIDC trusted publishing.

1. Before release, run plugin tests first (follow plugin-dev-harness/README.md).
2. Enter the target workspace and create a changeset:
   • For xpertai: cd xpertai && pnpm exec changeset add
   • For community: cd community && pnpm exec changeset add
3. Check pending release plan locally:
   • pnpm exec changeset status
4. Submit PR with both code changes and .changeset/*.md, then merge into main.
5. Workflow will create or update the release PR (changeset-release/main) with version bumps.
6. Merge the release PR into main; workflow then publishes changed packages to npm.

Notes:

• If logs show No changesets found, the merged commit did not contain a valid .changeset/*.md for that workspace.
• If logs show ENEEDAUTH, verify npm Trusted Publisher settings for that package.

New Package Checklist (Required)

When creating a new publishable package, ensure package.json includes at least:

{
  "name": "@xpert-ai/plugin-xxx",
  "version": "0.0.1",
  "repository": {
    "type": "git",
    "url": "https://github.com/xpert-ai/xpert-plugins"
  }
}

Important:

• repository.url must match the GitHub repository used by provenance/OIDC (recommended exact value: https://github.com/xpert-ai/xpert-plugins).
• If this field is missing or empty, npm may reject publish with provenance error (E422).
• For Trusted Publisher, leave Environment name empty unless workflow explicitly adds environment: <name> in the release job.
• Trusted Publisher is configured per npm package. A brand-new package may require one bootstrap publish before switching to OIDC-only publishing.

After releasing your plugin, register/update plugin metadata in: https://github.com/xpert-ai/xpert-plugin-registry.

Support and Feedback

• For issues with the official platform: contact XpertAI support channels or your enterprise customer success contact.
• For repository maintenance issues: create an issue in the GitHub Issues section, describing the situation and steps to reproduce.

Thank you for contributing to the XpertAI plugin ecosystem!

• Connector authentication framework and migration matrix