插件配置：config_schema

插件配置用于让管理员填写 API 密钥、接口地址、模型名、开关、枚举选项或数值参数，并在运行时通过 Ting.config 注入插件。

插件配置：config_schema

插件需要让管理员填写 API 密钥、接口地址、模型名、开关、枚举选项或数值参数时，在 plugin.yml 里声明 config_schema。Ting Reader 会据此显示配置表单、提取默认值、保存配置、校验配置、加密敏感字段，并在插件运行时把解密后的配置注入 Ting.config。

config_schema:
  type: object
  properties:
    api_base_url:
      type: string
      title:
        zh: API 地址
        en: API endpoint
      description:
        zh: OpenAI 兼容接口地址，可以填写服务根地址或完整 /v1/chat/completions 地址。
        en: OpenAI-compatible endpoint. A service root or full /v1/chat/completions URL is accepted.
      placeholder:
        zh: https://api.example.com/v1/chat/completions
        en: https://api.example.com/v1/chat/completions
      default: https://api.openai.com/v1/chat/completions

    api_key:
      type: string
      format: secret
      x-encrypted: true
      title:
        zh: API 密钥
        en: API key
      description:
        zh: 后端会加密保存，插件运行时通过 Ting.config.api_key 读取明文值。
        en: Stored encrypted by the backend. The plugin reads the plaintext value from Ting.config.api_key at runtime.

    model:
      type: string
      title:
        zh: 模型
        en: Model
      default: gpt-4.1-mini

    mode:
      type: string
      title:
        zh: 处理模式
        en: Processing mode
      default: balanced
      enum:
        - fast
        - balanced
        - accurate
      enum_labels:
        fast:
          zh: 快速
          en: Fast
        balanced:
          zh: 平衡
          en: Balanced
        accurate:
          zh: 准确
          en: Accurate

    temperature:
      type: number
      title:
        zh: 温度
        en: Temperature
      default: 0.2
      minimum: 0
      maximum: 1

    max_candidates:
      type: integer
      title:
        zh: 最大候选数
        en: Max candidates
      default: 8
      minimum: 1
      maximum: 20

    enabled:
      type: boolean
      title:
        zh: 启用增强处理
        en: Enable enhanced processing
      default: true

后端也接受扁平简写，会自动包装成 type: object + properties。简单插件可以用这种写法：

config_schema:
  api_key:
    type: string
    format: secret
    x-encrypted: true
    title: API Key
  source_url:
    type: string
    title: Source URL
    default: https://example.com/plugins.json

schema	后台表单
type: string	文本输入框
type: string + enum	下拉选择框
type: number	数字输入框
type: integer	数字输入框，保存为数字
type: boolean	复选框
format: password / format: secret	密码输入框，并按敏感字段处理
x-encrypted: true / encrypted: true	密码输入框，并加密保存

title、description、placeholder 可以写字符串，也可以写中英文对象。enum_labels 可以按枚举值提供多语言显示名。敏感字段建议同时写 format: secret 和 x-encrypted: true。

后端识别 x-encrypted: true、encrypted: true、format: password 或 format: secret 后都会加密保存。插件管理页读取配置时不会把敏感字段明文回显给浏览器；用户保持密钥不变时，前端会用内部占位符保留旧值，插件作者不需要处理这个占位符。

function readConfig() {
  const config = Ting.config || {};
  return {
    apiBaseUrl: String(config.api_base_url || "https://api.openai.com/v1/chat/completions"),
    apiKey: String(config.api_key || ""),
    model: String(config.model || "gpt-4.1-mini"),
    enabled: config.enabled !== false,
    maxCandidates: Number(config.max_candidates || 8),
  };
}

async function search(args) {
  const config = readConfig();
  if (!config.apiKey) {
    Ting.log?.warn?.("api_key is empty; returning fallback result.");
  }
}

globalThis.search = search;

插件管理页通过以下接口读取和保存配置。保存后会校验 schema、加密敏感字段并通知插件管理器；排查配置问题时，保存后再重新加载插件。

GET /api/v1/plugins/:id/config
PUT /api/v1/plugins/:id/config
Content-Type: application/json

{
  "config": {
    "api_key": "sk-...",
    "model": "gpt-4.1-mini",
    "enabled": true
  }
}

config_schema 是插件自身配置，不是存储库 scraper_config。
default 只用于初始化和补齐缺失字段，不会覆盖用户已经保存过的值。
不要在日志或 description 中打印 API key。
当前插件管理页不渲染嵌套 object、array 和复杂表单；复杂配置建议拆成多个简单字段，或提供 ui_extension 自定义配置面板。
修改 plugin.yml 的 config_schema 后，需要重新打包/重装或重新加载插件。

← 上一篇插件能力声明下一篇 →HostGateway 能力调用