Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
- `src/workspace.ts` — artifact workspace: per-main-session `<project>/.switchman/<yyyy-mm-dd>/<sessionId>-<title>/` folders (SESSION.md / dispatches.jsonl / media/; config `workspace.*`).
- `src/provider-config.ts`, `src/types.ts` — provider/model metadata, routing config, option types.
- `src/lang-config.ts` — project language preference (settings.json + AGENTS.md marker, ask directive, [LANG] line, question capture).
- `src/setup-gate.ts` — setup completion predicate + gate copy (all 6 task pools + capability rank must be configured; task dispatch denied until then); wired in index.ts (task deny, [SETUP] directive, banner segment), guided wizard in tui.tsx.
- `scripts/` — codegen (`gen-shells`, `gen-capability-default`, `gen-version`), build helpers, mode switcher.
- `test/` — bun test suites; treat as the behavioral contract (update together with behavior changes).

Expand Down
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,20 @@

This project follows [Semantic Versioning](https://semver.org/). Release notes describe user-visible behavior; implementation details remain in the technical specification and commit history.

## [1.2.0] - 2026-09-19

### Added

- **Setup hard gate + guided wizard (`/switchman-setup` / `/switchman-setup-chat`)** — unconfigured task pools no longer fall back to "all models": task dispatch is denied in main sessions until every one of the six task pools (`economy`/`mechanical`/`main`/`hard`/`vision`/`review`) has at least one selected model **and** the capability ranking has at least one entry. The guided wizard covers the whole matrix in one pass: **TUI (`/switchman-setup`)** — a resumable intro (Start jumps to the first unfinished step), one multi-select dialog per pool in lane order (Enter toggles, capability tier per row, select-all/clear-all/back; the per-pool confirm persists immediately, minimum one model), a sequential strongest-first ranking pick over exactly the union of the selected models (minimum one), and a done screen with the per-pool summary, ranking order, and any providers still flagged restartRequired; **conversational fallback (`/switchman-setup-chat`)** — the same flow in chat (state overview → per-pool multi-select questions → ranking → CLI persist → verify), for when the TUI plugin surface is unavailable. While setup is incomplete, main sessions carry a `[SETUP]` directive each turn and every task denial relays the remedy; dispatched shells and internal sessions are exempt and there is no waiver flag. The gate rides on the language gate — until the project language preference is configured, the language ask stays the single blocking voice. The wizard writes the same hot-reloaded `pool-config.json`/`capability-rank.json` as the manual overrides, so the gate opens the moment the last file is saved — no restart (a restart only registers brand-new providers). New module `src/setup-gate.ts`; sidebar notice and `[LIMITS]` banner segment report the missing state.
- **Render-time i18n (11 locales)** — sidebar chrome, pool/rank/handover dialogs, status-log notices, and config-CLI copy now localize at render time via a new i18n core (`src/i18n.ts`); locale chain: project language → global `ui.lang` → terminal env (`LC_ALL`/`LANG`) → English, with an English/key fallback that never throws. The six-lane sidebar labels localize display-only (runtime `LANE_ORDER`, pool-config keys, and protocol stay English) with CJK-aware column padding; model-facing protocol copy stays byte-stable English so capture anchors (`[ROUTES]`/`[WATERMARK]`/`[LANG]` lines) never drift.

### Changed

- **Real-fail isolation window shortened 30 min → 5 min** — a shell whose probe passes but whose actual delegation fails (in-memory, per-combo isolation) now auto-unlocks after 5 minutes instead of 30: these states are usually transient vendor blips, and a 30-minute head-of-chain lockout starved lanes far longer than the failure warranted. Rate-limit self-heal keeps its dedicated 10-min TTL; endpoint-class config errors keep the 6h TTL; restart still clears everything.
- **Model rank scoped to the task-pool universe with pool-lane priority ordering** — `/modelRank` now ranks exactly the pool-selected universe: rankable rows are scoped to it, an empty universe gates set/add with guidance (the TUI offers a jump to `/poolConfig`), and non-pool entries (with their anchored scores) are auto-pruned on every rank write. The manual rank becomes the absolute ordering key on pool lanes — it beats tier grouping, effort partitions, and family preference — and pool members are exempt from capability-level floors. The `[LIMITS]` banner surfaces the rankable universe.
- **Economy lane effort preference raised to medium→high→low→minimal** — a medium-less flash model (e.g. glm-5.3-flash) now takes its high face as the economy chain head instead of being pinned to low; `off` stays the lane-tail fallback partition.
- **Self-read budget defragmented (tolerance band, headroom grants, continuation merge)** — reads within R* + deny-retry overhead (~400 tok) now pass outright (denying them costs more than the overshoot saved); per-call grants are sized from the remaining turn headroom (max 2× R*) so demonstrated-range reads land one-shot; bounded continuations of the last granted window merge into one completion shot even past the spent turn budget. Protocol §5, config comments, and dispatch-gate tests are synced to the new semantics.

## [1.1.0] - 2026-09-15

### Added
Expand Down
130 changes: 130 additions & 0 deletions README.de.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# opencode-switchman

[English](./README.md) | [简体中文](./README.zh.md) | [繁體中文](./README.zh-TW.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [Español](./README.es.md) | [Français](./README.fr.md) | **Deutsch** | [Italiano](./README.it.md) | [Português](./README.pt.md) | [Русский](./README.ru.md)

> **Du nutzt auch zcode?** Wirf einen Blick auf [zcode-switchman](https://github.com/mrzturn/zcode-switchman) — ein Schwesterprojekt desselben Autors, das dieselbe Orchestrierung für zcode-Nutzer bereitstellt.

> Kontext auf dem Tacho. Aufgaben verteilen sich von selbst.

![opencode-switchman — the context water level drives the switchman and throws the route](docs/assets/hero.svg)

> Interaktive Demo-Präsentation: [opencode-switchman in Aktion](https://mrzturn.github.io/opencode-switchman/)

Ein Orchestrierungs-Plugin für [OpenCode](https://opencode.ai). Es tut zwei Dinge — und tut sie richtig gut:

**1. Kontext-Pegelstandskontrolle.** Der Kontext deiner Session wird in jeder Runde gemessen. Lesevorgänge laufen gegen ein Budget pro Runde, sodass das Modell nicht im Stillen das ganze Repo schlürfen kann; Soft-/Hard-/Force-Wassermarken lösen erst Hinweise aus, dann Aufräumen, dann eine automatische Übergabe mit Backup und Komprimierung; jeder abgeschickte Subagent trägt sein eigenes hartes Limit. Der Kontext hört auf, sich wie ein Schneeball aufzublähen — eine Session kann den ganzen Tag laufen, ohne dass Tokens von der eigenen History aufgefressen werden.

**2. Automatisierte Entscheidungs-Delegation.** Dein primäres Modell wird zum Dispatcher: Es profiliert jede Aufgabe und delegiert sie an Subagent-Shells über sechs kognitive Spuren (economy / mechanical / main / hard / vision / review). Das Plugin erzwingt deterministische Gates, gewichtetes Modell-Scoring und selbstheilende Fehlerisolierung und protokolliert jede Routing-Entscheidung.

Darüber hinaus:

- **Mehrere Modelle oder Abos? Dieses Plugin wurde genau dafür gebaut.** GitHub Copilot, GLM Coding Plan, DeepSeek — oder jeder andere opencode-Provider — werden als ein einziger Pool orchestriert: kontingentbewusste Reihenfolge, Vermeidung von Spitzenfenstern, erzwungenes Review über Modellfamilien hinweg.
- **Nur ein Modell? Trotzdem lohnt es sich.** Die Kontextkontrolle und das smarte Dispatching allein halten ein einzelnes Modell unbegrenzt nutzbar — egal wie lange die Session läuft, der Kontext bläht sich nie auf.

## Installation

Ein Befehl — deckt die Erstinstallation und spätere Updates ab. Danach opencode neu starten.

```bash
curl -fsSL https://raw.githubusercontent.com/mrzturn/opencode-switchman/main/scripts/setup.sh | bash
```

oder

```bash
npx -y opencode-switchman@latest
```

oder

```bash
bunx opencode-switchman@latest
```

Beide Wege schreiben den `plugin`-Eintrag in deiner opencode-Konfiguration auf die exakte neueste Version um und räumen veraltete Caches weg. Manuelle npm-Installation, Build aus dem Quellcode und der Hinweis „Warum exakte Versionen": [Installationsdetails](./docs/reference.md#installation).

Lieber alles delegieren? Lass deine KI die Installation erledigen — füge diesen Prompt in die KI deiner Wahl ein:

<details open>
<summary><strong>KI-gestützter Installations-Prompt</strong></summary>

```text
Bitte installiere und konfiguriere das opencode-switchman-Plugin für mein opencode, strikt nach seinen offiziellen Anweisungen.

Offizielle Quellen (maßgeblich, nicht aus dem Gedächtnis raten):
- GitHub-Repo: https://github.com/mrzturn/opencode-switchman
- npm-Paket: https://www.npmjs.com/package/opencode-switchman
Lies den Abschnitt „Installation" in der README des Repos und befolge ihn exakt.

Schritte:
1. Installiere die auf npm veröffentlichte neueste Version: führe `npx -y opencode-switchman@latest` aus (oder `bunx opencode-switchman@latest`) — es schreibt den `plugin`-Eintrag in meiner opencode-Konfiguration auf die exakte neueste Version um (es funktioniert auch in der `opencode.json` auf Projektebene, falls ich diese verwende).
2. Vervollständige die funktionale Konfiguration: alle Plugin-Einstellungen liegen in der eigenständigen `opencode-switchman.jsonc` in meinem opencode-Konfigurationsverzeichnis, die beim ersten Start automatisch mit Standardwerten und Inline-Kommentaren erzeugt wird; prüfe sie gegen meine Provider (z. B. `zhipuai-coding-plan` / `deepseek` / `github-copilot`) und passe sie bei Bedarf an.
3. Verifiziere, dass opencode das Plugin lädt, startet und ausführt: führe `/switchman-doctor` in opencode aus für einen lokalen Diagnosebericht ohne Zugangsdaten und behebe jeden gemeldeten Fehler; starte opencode dann neu und bestätige, dass das Plugin tatsächlich geladen wurde — das Log sollte `[opencode-switchman] injected N model shells (agents)` enthalten und der System-Prompt meines primären Modells sollte den aktuellen `[ROUTES]/[WATERMARK]/[LIMITS]`-Bannerblock tragen.

Erkläre keinen Erfolg, bevor alle drei Schritte bestanden sind; berichte, was du geändert hast, und zeige die Verifikationsnachweise.
```

</details>

**Voraussetzungen**: [opencode](https://opencode.ai), CLI/TUI empfohlen (Dialoge, Seitenleiste und Banner sind dort am umfangreichsten; die Desktop-App teilt dieselbe Konfiguration und denselben Zustand). Jeder Provider funktioniert; Copilot / GLM / DeepSeek erhalten zusätzlich kontingentbewusstes Routing. Zugangsdaten werden ausschließlich lesend aus opencodes eigener Auth gelesen — das Plugin speichert niemals Secrets.

## Schnellstart

Sechs Schritte. Komplette Anleitung mit Screenshots: **[docs/quick-start.md](./docs/quick-start.md)** / [中文](./docs/quick-start.zh.md).

1. **Provider verbinden** — `/connect` in der TUI: Copilot-OAuth, DeepSeek-API-Key; GLM Coding Plan landet als benutzerdefinierter Provider `zhipuai-coding-plan` in der `opencode.json`.
2. **Modelle auswählen, die an der Orchestrierung teilnehmen** — `/models`, dann `ctrl+f` zum Favorisieren (Desktop-App: Schalter unter „Modelle verwalten").
3. **`/switchman-setup`** *(einmalig erforderlich)* — der geführte Assistent deckt die gesamte Matrix in einem Durchgang ab: wähle für jeden der sechs Task-Pools mindestens ein Modell aus (economy / mechanical / main / hard / vision / review) und ordne die gewählten Modelle dann vom stärksten zum schwächsten. Keine TUI? `/switchman-setup-chat` führt denselben geführten Ablauf im Chat aus. Bis zum Abschluss des Setups ist Task-Dispatching hart blockiert — unkonfigurierte Pools fallen nicht mehr auf „alle Modelle" zurück. Gespeicherte Konfiguration wird per Hot-Reload übernommen; ein Neustart ist nur nötig, um völlig neue Provider zu registrieren.
4. **Feintuning** *(optional)* — **`/modelRank`** stimmt das Fähigkeits-Ranking von Hand ab und **`/poolConfig`** kuratiert die Kandidatenlisten pro Pool in TUI-Dialogen (`-chat`-Varianten im Chat); manuelle Einträge überschreiben überall die anfänglichen Standardwerte.
5. **Kontext-Befehle**
- **`/handover`** — sichert die Session und komprimiert sie selbst. Nutze sie, wenn die `[WATERMARK:SESSION]`-Zeile groß wird oder die Aufgabe einen guten Stopp-Punkt erreicht, statt auf die automatische Übergabe zu warten.
- **`/ctx-pause`** — schaltet die Lese-Limits dieser Session und die Auto-Übergabe aus. Nutze sie, wenn du viele große Dateien auf einmal lesen musst und Tokens auszugeben dir nichts ausmacht; die Messung läuft weiter.
- **`/ctx-resume`** — schaltet die Limits wieder ein. Nutze sie, sobald das intensive Lesen erledigt ist; ein Neustart von opencode hat denselben Effekt.
6. **Neu starten und prüfen** — kontrolliere das `[ROUTES]`/`[LIMITS]`-Banner und das `switchman`-Panel in der Seitenleiste; führe `/switchman-doctor` aus, falls etwas ungewöhnlich wirkt. Danach nutze opencode einfach wie gewohnt.

## Was du bekommst

**Kernfunktionen**

- **Kontext-Pegelstandskontrolle** — Live-Messung der Session (`[WATERMARK:SESSION]`), Soft-/Hard-/Force-Schwellenwerte, ein Lese-Budget pro Runde, das übermäßige Lesevorgänge automatisch begrenzt, ein hartes Limit mit Zusammenfassung und Abbruch für jeden Subagenten sowie eine automatische Übergabe (vollständiges Backup-Fork + Komprimierung) auf Force-Level.
- **Automatisierte Entscheidungs-Delegation** — ein mitgeliefertes Dispatcher-Protokoll macht dein primäres Modell zum Dispatcher; sechs kognitive Spuren leiten Arbeit an das richtige Modell mit dem richtigen Aufwand; sechs deterministische Gates prüfen jede Delegation; Ausfälle lösen Circuit-Breaker und Isolierung aus, und das System heilt sich selbst.

**Extras**

- **Multi-Abo-Orchestrierung** — kontingentbewusstes Routing über Copilot / GLM / DeepSeek hinweg (jeder Provider nimmt teil), Ausweichen bei Spitzenfenstern, abrechnungsbewusstes Scoring, erzwungenes Review über Modellfamilien hinweg.
- **Manuelle Steuerung** — `/switchman-setup`, `/poolConfig`, `/modelRank`, `/expert`, `/handover`, `/ctx-pause`, `/ctx-resume`, `/switchman-doctor`, `/switchman-update`.
- **Sichtbarkeit** — Live-Banner mit vier Zeilen in jedem System-Prompt, TUI-Seitenleisten-Panel, tmux-Pane-Spiegelung, ein Artefakt-Arbeitsbereich pro Session und ein Audit-Log jeder Routing-Entscheidung.

Vollständige Optionstabelle, Architektur und Interna: [docs/reference.md](./docs/reference.md) (中文: [docs/reference.zh.md](./docs/reference.zh.md)).

## Dokumentation

- Schnellstart (illustriert): [English](./docs/quick-start.md) · [中文](./docs/quick-start.zh.md)
- Vollständiges Handbuch (Konfiguration, Befehle, Architektur): [English](./docs/reference.md) · [中文](./docs/reference.zh.md)
- Technische Spezifikation (Verträge / Algorithmen / Praxistest-Notizen): [docs/2026-08-28-opencode-switchman-technical-design.md](./docs/2026-08-28-opencode-switchman-technical-design.md)
- Versionshinweise: [CHANGELOG.md](./CHANGELOG.md)

## Roadmap

Kurzfristig: Kontingent-Unterstützung für weitere Provider — mehr Abo-Pläne und Pay-as-you-go-Pools über Copilot / GLM / DeepSeek hinaus. Falls dein Provider noch nicht abgedeckt ist, [öffne ein Issue](https://github.com/mrzturn/opencode-switchman/issues): Die reale Nutzung entscheidet, was als Nächstes gebaut wird. Vorschläge und Fehlerberichte sind gleichermaßen willkommen.

## Unterstütze den Autor

Dieses Plugin ist Open Source und kostenlos nutzbar — und das bleibt auch so. Am Leben zu halten ist es trotzdem nicht gratis: Die Pflege und das Testen der Adapter-Kompatibilität über Provider hinweg bedeuten, mehrere Abos zu halten und sie einzeln durchzudebuggen — jede Runde kostet echtes Geld.

Wenn das Plugin dir wirklich geholfen hat und dein Budget es erlaubt, spendiere mir einen Kaffee. Danke — von Herzen.

👇

<details>
<summary>☕ Hier klicken 【Dem Autor einen Kaffee ausgeben】</summary>

| Alipay | WeChat Pay | Mit WeChat scannen und ihm ein Like geben |
|:---:|:---:|:---:|
| <img src="docs/pay/alipay.png" width="150" alt="Alipay QR code" /> | <img src="docs/pay/wechat_pay.jpg" width="150" alt="WeChat Pay QR code" /> | <img src="docs/pay/wechat_pay_2.jpg" width="150" alt="WeChat scan-to-like QR code" /> |

</details>

## Lizenz

[MIT](./LICENSE)
Loading
Loading