AGENTS.md

WICHTIG: opencode-models-discovery ist fehlerhaft

Das existierende Plugin opencode-models-discovery ist fehlfunktionell und wurde niemals erfolgreich getestet. Alle bisherigen Versuche, es zu installieren und zu nutzen, schlugen fehl (AggregateError, Module Resolution Errors, etc.).

Wir verwenden opencode-models-discovery NICHT. Es muss deinstalliert und nicht mehr referenziert werden (passiert: aus ~/.opencode entfernt, keine Config-Referenzen mehr).

Ziel

Wir bauen ein neues OpenCode v2 Plugin von Grund auf (opencode-openai-discovery), das:

Einen OpenAI-kompatiblen API-Endpunkt abfragt (GET /v1/models)
Entdeckte Modelle automatisch in OpenCode registriert
Sauber über die opencode v2 Plugin API (@opencode/plugin) funktioniert

Status: FUNKTIONIERT – alle 900 Gateway-Modelle erscheinen als OmniRoute/* in opencode models. Commit 511d2ea.

Projektstruktur

.
├── AGENTS.md                       # Diese Datei
├── README.md                       # Doku für Menschen (Installation, global vs. projektlokal)
├── opencode.jsonc                  # OpenCode Projekt-Konfiguration
└── .opencode/plugins/
    └── opencode-openai-discovery/
        ├── index.ts                # Plugin-Code (TypeScript, ESM)
        ├── package.json            # Plugin Package-Metadata
        └── tsconfig.json           # TypeScript-Konfiguration

Wichtige Infos

OpenCode Version: v2.0.32
Plugin API: @opencode/plugin (v2.x) — NICHT @opencode-ai/plugin (v1)
Plugin Discovery: Projektlokale Plugins in .opencode/plugins/ werden automatisch geladen; für globale Verfügbarkeit: ~/.opencode/plugins/ (gleiche Struktur) oder plugins-Array in der Config (v2-Schema: { "package": "..." } Strings)
Config Format: v2 verwendet providers (Plural), package: "aisdk:..."

API-Endpunkt

BASE_URL: http://localhost:20128/v1
API_KEY:  sk-e9ac58c0b78cd2bc-f17d3e-f6beea67
MODELS:   GET /v1/models   → 900 Modelle

Erkenntnisse aus dem Debugging (kritisch für künftige Agenten)

1. `modelsDiscovery` existiert NICHT im v2-Schema

Das Feld modelsDiscovery: { enabled: true } in der Provider-Config war eine Erfindung des defekten opencode-models-discovery-Plugins. OpenCode v2 kennt es nicht (verifiziert am @opencode/schema). Konfig-Provider erscheinen im Provider-Index nur mit einem nicht-leeren models-Record – daher wurde OmniRoute initial nie instanziiert.

2. Provider-Transform läuft VOR dem Config-Provider-Load

ctx.provider.transform(editor) sieht nur die ~230 Katalog-Provider von models.dev, nicht die Config-Provider. editor.models.set(providerID, ...) auf einen nicht existierenden Provider ist ein stilles No-Op. Lösung: Provider per editor.add({ info, models }) selbst erstellen, falls editor.get(providerID) nichts liefert.

3. Model.Info-Schema: alle Pflichtfelder setzen, sonst stiller Verlust

OpenCode verwirft Models OHNE Fehlermeldung aus dem Index, wenn Schema-Felder fehlen. Erforderlich pro Model:

{
  id, modelID, providerID, name,
  capabilities: { tools, input: [], output: [] },
  variants: [],
  cost: [{ input, output, cache: { read, write } }],
  limit: { context, output },
  time: { released },
  status: "active",
  enabled: true,
}

Beachte: limit (SINGULAR), nicht limits. Die Fehler tauchen erst client-seitig als InvalidRequestError: Missing key at ["data"][N][...] auf – Index-N zeigt das N. verarbeitete (fehlgeschlagene) Model an.

4. Plugin wird lazy geladen

Der Plugin-Load wird getriggert, sobald ein Client (CLI/TUI) das Projektverzeichnis öffnet ("location services booted"). opencode service restart reicht manchmal nicht – hängende Server-Prozesse cache alte Plugin-Stände: pkill -f "opencode serve" + neuer CLI-Aufruf.

5. Hot-Reload

OpenCode watcht die Plugin-index.ts – Änderungen werden sofort neu geladen, kein Neustart nötig. Syntaxfehler im TS zeigen als BuildMessage: Unexpected escape sequence o.ä. im Log.

6. `opencode models` CLI

Zeigt ALLE verfügbaren Modelle (nicht paginiert; die anfangs sichtbaren 10 opencode/*-Modelle kamen vom OpenCode-Zen-Katalog, nicht von uns). Der Server-Port steht in der Log-Datei; die API braucht Auth (nicht einfach curl-bar ohne Token).

Plugin API (v2) – bewährtes Muster

import { Plugin, Model } from "@opencode/plugin";

export default Plugin.define({
  id: "opencode.openai-discovery",
  async setup(ctx) {
    // 1. fetch GET /v1/models
    // 2. Modelle auf volles Model.Info-Schema mappen (siehe oben)
    // 3. Registrieren:
    ctx.provider.transform((editor) => {
      const source = editor.get("OmniRoute");
      if (source) {
        // mergen:
        editor.models.set("OmniRoute", [...existing, ...newModels]);
      } else {
        // erstellen (package MUSS "aisdk:@ai-sdk/openai-compatible" sein):
        editor.add({
          info: {
            id: "OmniRoute",
            name: "OmniRoute",
            activation: "enabled",
            package: "aisdk:@ai-sdk/openai-compatible",
            settings: { baseURL, apiKey },
          } as never,
          models,
        });
      }
    });
  },
});

Verifizierung

opencode models | grep -c "^OmniRoute/"   # → 900

AGENTS.md 5.3 KB Előzmények Nyers