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