New API Official Plugins

Official task-plugin marketplace for new-api. Each plugin is a single self-contained JavaScript module consumed by the new-api JS task-plugin runtime.

Layout

plugins/<kind>/<key>/<version>/plugin.js     # immutable once published
plugins/<kind>/<key>/<version>/CHANGELOG.md  # required for every new version
index.json                                 # generated — never edit by hand

• <kind> — plugin kind directory. Currently only tasks (async task plugins: video/music generation). The directory is organization; the compiled plugin meta is the declaration.
• <key> — the plugin's meta.key. Must match the directory name.
• <version> — the plugin's meta.version. Must match the directory name. Published version directories are immutable: to ship a change, add a new version directory.

index.json is a derived artifact

index.json is generated by the pluginindex tool in this repository (tools/pluginindex, a small Go program that depends on new-api's pkg/jsplugin compiler via a sibling checkout). Every display field (name, channelTypes, models) is extracted from the compiled plugin meta, so the index can never drift from the source. The index exists for the three things a single plugin file cannot carry:

1. the repository catalog (raw hosting has no directory listing),
2. the cross-version table (latest, installable versions),
3. the source sha256 (integrity check at install time — a hash cannot live inside the file it hashes).

Gateways installing from this repository verify the sha256 and then re-validate everything from the compiled meta. The index is a cache, never a trust anchor.

Regenerate after adding a plugin:

# requires a new-api checkout as a sibling directory (../new-api)
cd tools/pluginindex && go run . generate ../..

CI runs pluginindex check on every PR and fails if index.json is stale, any plugin fails to compile, or a directory name disagrees with the compiled meta.

Documentation

• Task plugin API v1 — synchronized from new-api/docs/plugin-api/, including the API reference, TypeScript declarations, and JSON Schema.
• Marketplace index format — repository layout, version catalog, and installation integrity checks.

Contributing a plugin

1. Add plugins/tasks/<key>/<version>/plugin.js (single file, synchronous, no imports — see the plugin API contract).
2. Write an English CHANGELOG.md beside that version's plugin.js, including for an initial release. Follow the release notes format: YAML metadata, a matching version heading, and fixed English change categories. Optional translations use separate locale files linked from the English changelog. Use plain, natural language to explain what users can do after upgrading and what behavior changes. Use Migration only for actions users need to take, with required pricing changes first. Omit test reports, generic release instructions, unchanged behavior, and statements about actions users do not need to perform. When syncing a plugin, sync its changelog too, or write one from verified changes. This applies to new and unpublished versions; do not backfill immutable published directories.
3. Regenerate index.json (command above), run go run . check ../.. from tools/pluginindex, and commit the plugin, its changelog, and the index together.
4. Open a PR. Review = code review of the plugin source. Note that installed plugins run with administrator-level trust on the gateway (they can see channel credentials and construct upstream requests), so reviews are strict about allowedHosts, credential handling, and request construction.

Installing

From the new-api admin panel: 任务插件 → 插件市场 (marketplace panel), or paste the raw plugin.js URL into the upload dialog. The gateway pre-flights conflicts (channel types, routes, protocol model bindings) against the live plugin generation before saving.