@ashdev/codex-plugin-sdk (英语)

用于构建 Codex 插件的官方 SDK. 提供类型安全接口,公用设施,并提供一个服务器框架,通过JSON-RPC在stdio上与Codex通信.

安装

npm install @ashdev/codex-plugin-sdk

快速启动

import {
  createMetadataPlugin,
  type MetadataContentType,
  type MetadataProvider,
  type PluginManifest,
} from "@ashdev/codex-plugin-sdk";

// Define your plugin manifest
const manifest = {
  name: "metadata-my-plugin",
  displayName: "My Plugin",
  version: "1.0.0",
  description: "A custom metadata provider",
  author: "Your Name",
  protocolVersion: "1.0",
  capabilities: {
    metadataProvider: ["series"] as MetadataContentType[],
  },
} as const satisfies PluginManifest & {
  capabilities: { metadataProvider: MetadataContentType[] };
};

// Implement the MetadataProvider interface
const provider: MetadataProvider = {
  async search(params) {
    // Search your data source
    return {
      results: [
        {
          externalId: "123",
          title: "Example Series",
          alternateTitles: [],
          relevanceScore: 0.95,
          preview: {
            status: "ongoing",
            genres: ["Action", "Adventure"],
          },
        },
      ],
    };
  },

  async get(params) {
    // Fetch full metadata
    return {
      externalId: params.externalId,
      externalUrl: `https://example.com/series/${params.externalId}`,
      title: "Example Series",
      alternateTitles: [],
      summary: "An exciting series...",
      status: "ongoing",
      year: 2024,
      genres: ["Action", "Adventure"],
      tags: [],
      authors: ["Author Name"],
      artists: [],
      externalLinks: [],
    };
  },

  // Optional: implement match for auto-matching during library scans
  async match(params) {
    const result = await this.search({
      query: params.title,
    });

    return {
      match: result.results[0] ?? null,
      confidence: result.results[0] ? 0.8 : 0,
    };
  },
};

// Start the plugin
createMetadataPlugin({ manifest, provider });

特征

• 类型安全: 有接口合同的完整类型脚本支持
• 议定书遵守情况: 类型完全符合 Codex JSON- RPC 协议
• 简单 API: 执行 MetadataProvider 界面, SDK 处理其余部分
• 处理错误: 内建错误类, 映射到 JSON- RPC 错误
• 日志: 安全记录到 stderr( stdout 保留用于协议)

概念

能力

插件在其清单中声明能力。 每个能力都有相应的接口:

这个 metadataProvider 能力是您插件支持的一系列内容类型:

capabilities: {
  metadataProvider: ["series"] as MetadataContentType[],
}

支持的内容类型 : "series" (未来: "book"(中文(简体) )

协议类型

SDK提供了完全符合"代码JSON-RPC"协议的TypeScript类型:

• MetadataSearchParams 编号 : MetadataSearchResponse - 搜索参数和结果
• MetadataGetParams 编号 : PluginSeriesMetadata - 获取完整的元数据
• MetadataMatchParams 编号 : MetadataMatchResponse - 自动匹配内容
• SearchResult - 个人搜索结果 relevanceScore

相关性分数

搜索结果必须包括 relevanceScore 0.0至1.0之间:

• 1.0 = 完美匹配 (中文(简体) )
• 0.7-0.9 = 匹配不错
• 0.5-0.7 = 部分匹配数
• < 0.5 = 较弱

API 参考

createMetadataPlugin(options)

创建并启动元数据提供者插件 .

interface MetadataPluginOptions {
  manifest: PluginManifest & { capabilities: { metadataProvider: MetadataContentType[] } };
  provider: MetadataProvider;
  onInitialize?: (params: InitializeParams) => void | Promise<void>;
  logLevel?: "debug" | "info" | "warn" | "error";
}

MetadataProvider

元数据提供者插件接口 :

interface MetadataProvider {
  search(params: MetadataSearchParams): Promise<MetadataSearchResponse>;
  get(params: MetadataGetParams): Promise<PluginSeriesMetadata>;
  match?(params: MetadataMatchParams): Promise<MetadataMatchResponse>;
}

处理错误

使用内置错误类进行正确的错误响应 :

import { NotFoundError, RateLimitError, AuthError, ApiError } from "@ashdev/codex-plugin-sdk";

// In your provider:
async get(params) {
  const data = await fetchFromApi(params.externalId);

  if (!data) {
    throw new NotFoundError(`Series ${params.externalId} not found`);
  }

  return data;
}

日志

插件应登录为 stderr( stdout 保留给 JSON- RPC) :

import { createLogger } from "@ashdev/codex-plugin-sdk";

const logger = createLogger({ name: "my-plugin", level: "debug" });
logger.info("Plugin started");
logger.debug("Processing request", { query: "..." });
logger.error("Failed to fetch", error);

全权证书

插件可以通过 onInitialize 回调 :

let apiKey: string | undefined;

createMetadataPlugin({
  manifest,
  provider,
  onInitialize(params) {
    apiKey = params.credentials?.api_key;
  },
});

身份证明由 Codex 中的管理员配置,并安全地发送给插件.

议定书

插件通过 JSON-RPC 2. 0 与 Codex 通信 :

• 静态:接收JSON-RPC请求(每行1个)
• 静态:发送JSON-RPC的回复(每行1个)
• 标准: 日志输出( 在 Codex 日志中可见)

构建您的插件

1. 创建新 npm 软件包
2. 安装 SDK : npm install @ashdev/codex-plugin-sdk
3. 执行您的提供者
4. 装入建置( 包括 shebang 用于 npx 支持) :

{
  "name": "@your-org/plugin-metadata-example",
  "version": "1.0.0",
  "main": "dist/index.js",
  "bin": "dist/index.js",
  "type": "module",
  "files": ["dist", "README.md"],
  "engines": {
    "node": ">=22.0.0"
  },
  "scripts": {
    "build": "esbuild src/index.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/index.js --sourcemap --banner:js='#!/usr/bin/env node'",
    "prepublishOnly": "npm run lint && npm run build"
  }
}

Npx 支持的关键字段 :

• bin: 指向条目文件, 告诉 npx 执行什么
• --banner:js='#!/usr/bin/env node': 添加 shebang 以直接执行文件
• files: 只发布 dist 和 README 到 npm

示例插件

• @ashdev/codex-plugin-metadata-echo - 测试回放查询的元数据插件
• @ashdev/codex-plugin-metadata-mangabaka - 曼加巴卡元数据供应商

许可证

麻省理工学院