b897bb4b17
- omos init [--fill]: create user mapping file, interactively resolve PLACEHOLDER classes by picking from models discovered in opencode.json(c) - omos setup: guided flow - show profile summary, create/fill missing mappings with explicit user choice, then render - README quickstart updated to the two-command path
169 lines
7.1 KiB
Markdown
169 lines
7.1 KiB
Markdown
# omos
|
||
|
||
Adapter zwischen APM-Packages mit Team-Profil und [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim).
|
||
|
||
`omos` liest eine `team-profile.yaml` aus einem APM-Package, löst abstrakte Modellklassen gegen deine lokale Mapping-Tabelle auf und generiert ein namespacetes oh-my-opencode-slim-Preset. Deterministisch – `omos` rät nicht.
|
||
|
||
```
|
||
APM-Package Nutzer Runtime
|
||
team-profile.yaml + model-mapping.yaml → omos render → .opencode/
|
||
(Rollen, Modell- (Modellklasse → oh-my-opencode-slim.json
|
||
klassen, MCPs/Skills) konkrete Modell-ID)
|
||
```
|
||
|
||
## Voraussetzungen
|
||
|
||
- Python 3.10+ mit PyYAML (`pip install pyyaml`)
|
||
- OpenCode mit installiertem Plugin [oh-my-opencode-slim](https://ohmyopencodeslim.com/)
|
||
- Ein APM-Package mit `team-profile.yaml`
|
||
|
||
## Schnellstart
|
||
|
||
```bash
|
||
# 1. Modell-Mapping anlegen – interaktiv, mit Auswahl aus deinen opencode-Modellen
|
||
python3 omos.py init --fill
|
||
|
||
# 2. Geführt: Team-Profil lesen, Mapping prüfen/auffüllen, rendern
|
||
cd <projekt>
|
||
python3 /pfad/zu/omos.py setup --package /pfad/zum/package
|
||
|
||
# 3. Aktivieren
|
||
opencode # Projekt-Config wird geladen
|
||
/preset acme-job-applications
|
||
# Reload OpenCode → Team aktiv (by Design: kein Hot-Swap)
|
||
```
|
||
|
||
Alternativ manuell:
|
||
|
||
```bash
|
||
# 1. Modell-Mapping einmalig anlegen
|
||
mkdir -p ~/.config/apm-team
|
||
cp examples/model-mapping.yaml ~/.config/apm-team/model-mapping.yaml
|
||
$EDITOR ~/.config/apm-team/model-mapping.yaml # an eigene Modelle anpassen
|
||
|
||
# 2. Validieren (Dry-Run)
|
||
python3 omos.py check --package examples/package
|
||
|
||
# 3. Rendern
|
||
cd <projekt>
|
||
python3 /pfad/zu/omos.py render --package /pfad/zum/package
|
||
```
|
||
|
||
## Die drei Dateien
|
||
|
||
| Datei | Gehört | Zweck | Manuell editieren? |
|
||
|---|---|---|---|
|
||
| `team-profile.yaml` | Package-Autor | Rollen, Modellklassen, MCP-/Skill-Allowlists pro Rolle | Ja (Autor) |
|
||
| `~/.config/apm-team/model-mapping.yaml` | Nutzer | Modellklasse → konkrete Modell-ID (+ optional variant/temperature) | Ja (Nutzer) |
|
||
| `.opencode/oh-my-opencode-slim.json` | generiert | OMOS-Preset mit konkreten Modell-IDs | **Nein** – immer neu rendern |
|
||
|
||
Dazu eine Provenance-Datei `.opencode/oh-my-opencode-slim.omos-provenance.json`, die dokumentiert, welche Rolle welches Modell erhalten hat.
|
||
|
||
## Kommandoreferenz
|
||
|
||
```bash
|
||
python3 omos.py init [--mapping FILE] [--fill] # Mapping anlegen/füllen
|
||
python3 omos.py setup --package DIR [--mapping F] ... # geführter Ablauf
|
||
python3 omos.py render --package DIR [--mapping F] [--output F] [--dry-run]
|
||
python3 omos.py check --package DIR [--mapping F] # Dry-Run-Validierung
|
||
```
|
||
|
||
### `init` – Mapping anlegen
|
||
|
||
Erstellt `~/.config/apm-team/model-mapping.yaml` (falls nicht vorhanden). Mit `--fill` werden alle `PLACEHOLDER`-Klassen interaktiv abgefragt: `omos` listet alle Modelle aus deiner `opencode.json(c)` auf, du wählst per Nummer oder gibst eine Modell-ID manuell ein.
|
||
|
||
### `setup` – Geführter Ablauf
|
||
|
||
Der Ein-Kommando-Weg: zeigt das Team-Profil verständlich an, legt fehlendes Mapping an, fragt fehlende Modellklassen interaktiv ab (gleiche Auswahl wie `init --fill`), rendert und gibt die Aktivierungsschritte aus. Entspricht dem Resolve–Validate–Render-Ablauf.
|
||
|
||
### `render` / `check`
|
||
|
||
| Option | Default | Bedeutung |
|
||
|---|---|---|
|
||
| `--package` | `.` | APM-Package-Verzeichnis mit `team-profile.yaml` |
|
||
| `--mapping` | `~/.config/apm-team/model-mapping.yaml` | Lokale Mapping-Tabelle |
|
||
| `--output` | `<package>/.opencode/oh-my-opencode-slim.json` | Zieldatei |
|
||
| `--team-file` | `team-profile.yaml` (alternativ `team.yaml`) | Alternativer Profilname |
|
||
|
||
**Merge-Verhalten:** Existierende Presets in der Zieldatei bleiben unberührt; nur das Preset der Team-ID wird ersetzt. Mehrere Packages koexistieren damit im selben Projekt. Aktiviert wird explizit per `/preset <name>`.
|
||
|
||
## Team-Profil-Schema (`corentic.team-profile/v1`)
|
||
|
||
```yaml
|
||
schema: corentic.team-profile/v1
|
||
id: acme.job-applications # wird zum Preset-Namen (namespaced)
|
||
description: ...
|
||
|
||
roles:
|
||
- id: researcher # fachliche Rolle
|
||
purpose: ... # wird zu Prompt/Description für Custom Agents
|
||
omos_agent: librarian # optional: OMOS-Builtin oder 'custom'
|
||
# (Default: role-id als Custom Agent)
|
||
model_class: fast-research # Pflicht, muss im Mapping existieren
|
||
capabilities:
|
||
mcps: [websearch, openviking] # MCP-Allowlist ([] = keine)
|
||
skills: [job-application] # Skill-Allowlist ([] = keine)
|
||
```
|
||
|
||
Erkannte OMOS-Builtins: `orchestrator`, `oracle`, `librarian`, `explorer`, `fixer`, `designer`, `council`, `observer`. Alles andere (oder `omos_agent: custom`) erzeugt einen Custom Agent inklusive `prompt` und `orchestratorPrompt` aus dem `purpose`-Feld.
|
||
|
||
### Mapping-Formate
|
||
|
||
```yaml
|
||
model_classes:
|
||
fast-research: ollama/qwen3.5:9b # einfach
|
||
high-reasoning: # erweitert
|
||
model: ollama/qwen3.6:35b-a3b-q4_K_M
|
||
variant: thinking
|
||
temperature: 0.3
|
||
```
|
||
|
||
Alle Zusatzfelder werden 1:1 in den Agent-Eintrag des Presets übernommen.
|
||
|
||
## Was omos prüft
|
||
|
||
1. Team-Profil vorhanden, Schema bekannt, `id` und `roles` vorhanden
|
||
2. Jede `model_class` hat einen Mapping-Eintrag (sonst Fehler mit Lösungshinweis)
|
||
3. MCPs gegen `~/.config/opencode/opencode.json(c)` abgleichen (**Warnung**, kein Abbruch)
|
||
4. Rollen ohne MCPs/Skills → Hinweis
|
||
|
||
`omos` nimmt keine Verfügbarkeit an und wählt keine Modelle automatisch aus. Fehlt ein Mapping, bricht das Rendern mit konkreter Ursache ab.
|
||
|
||
## Walkthrough mit dem Beispiel-Package
|
||
|
||
```bash
|
||
cd omos/examples
|
||
|
||
# Trockenlauf: was würde generiert?
|
||
python3 ../omos.py check --package package --mapping model-mapping.yaml
|
||
|
||
# Rendern in das Beispiel-Projekt
|
||
python3 ../omos.py render --package package \
|
||
--mapping model-mapping.yaml \
|
||
--output package/.opencode/oh-my-opencode-slim.json
|
||
```
|
||
|
||
Erwartetes Ergebnis: Preset `acme-job-applications` mit fünf Agenten – `orchestrator`, `librarian` (Alias `researcher`), Custom Agent `writer`, `oracle` (Alias `checker`), Custom Agent `notifier`. Der Researcher erhält keinen LaTeX-Zugang, der Writer keine Job-Suchtools, der Notifier gar keine externen Zugriffe.
|
||
|
||
Danach:
|
||
|
||
```bash
|
||
cd package && opencode
|
||
/preset acme-job-applications
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
| Problem | Ursache/Lösung |
|
||
|---|---|
|
||
| `Modellklasse X ist nicht gemappt` | Mapping ergänzen, erneut rendern |
|
||
| `Warnung: MCP ... nicht konfiguriert` | MCP in `opencode.jsonc` einrichten oder aus dem Profil entfernen |
|
||
| `/preset` zeigt nichts Neues | OpenCode nach dem Render neu laden; Preset greift nicht mid-session |
|
||
| Preset weg nach manuellem Editieren | Datei ist generiert – Änderungen gehören ins Mapping oder Team-Profil |
|
||
| YAML-Fehler | Zeilenangabe aus der Fehlermeldung folgen |
|
||
|
||
## Grenzen (bewusst)
|
||
|
||
- `omos` startet keine Agenten und orchestriert nichts zur Laufzeit – das macht oh-my-opencode-slim.
|
||
- MCP-/Skill-Allowlists sind Capability Scoping, keine Sandbox. Irreversible Aktionen brauchen serverseitige Autorisierung + Human Approval.
|
||
- Die Modellverfügbarkeit wird gegen die opencode.jsonc-Namen geprüft, nicht per API-Healthcheck.
|