docs(omos): user guide with quickstart, walkthrough and troubleshooting
This commit is contained in:
Tobias J. Endres
parent
f0f1915251
commit
f035902f20
1 changed files with 146 additions and 0 deletions
146
omos/README.md
Normal file
146
omos/README.md
Normal file
|
|
@ -0,0 +1,146 @@
|
||||||
|
# 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 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
|
||||||
|
|
||||||
|
# 4. Aktivieren
|
||||||
|
opencode # Projekt-Config wird geladen
|
||||||
|
/preset acme-job-applications
|
||||||
|
# Reload OpenCode → Team aktiv (by Design: kein Hot-Swap)
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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 render --package DIR [--mapping FILE] [--output FILE] [--dry-run]
|
||||||
|
python3 omos.py check --package DIR [--mapping FILE]
|
||||||
|
```
|
||||||
|
|
||||||
|
| 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.
|
||||||
Loading…
Add table
Reference in a new issue