Lars/mindnet_obsidian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
3be7d617fe
mindnet_obsidian/docs/01_Benutzerhandbuch.md
Lars a9b3e2f0e2
Some checks are pending
Node.js build / build (20.x) (push) Waiting to run
Details
Node.js build / build (22.x) (push) Waiting to run
Details
Implement Chain Workbench and Vault Triage features in Mindnet plugin 
- Introduced new workflows for Chain Workbench and Vault Triage, enhancing user capabilities for managing template matches and identifying chain gaps.
- Added commands for opening the Chain Workbench and scanning the vault for chain gaps, improving the overall functionality of the plugin.
- Updated documentation to include detailed instructions for the new workflows, ensuring users can effectively utilize the features.
- Enhanced the UI for both the Chain Workbench and Vault Triage Scan, providing a more intuitive user experience.
- Implemented tests for the new functionalities to ensure reliability and accuracy in various scenarios.
2026-01-26 10:51:12 +01:00

463 lines
14 KiB
Markdown
Raw Blame History

# Mindnet Causal Assistant - Benutzerhandbuch
> **Version:** 1.0.0
> **Stand:** 2025-01-XX
> **Zielgruppe:** Endnutzer des Mindnet Obsidian Plugins
---
## Inhaltsverzeichnis
1. [Einführung](#einführung)
2. [Schnellstart](#schnellstart)
3. [Hauptfunktionen](#hauptfunktionen)
4. [Workflows](#workflows)
5. [Commands im Detail](#commands-im-detail)
6. [Troubleshooting](#troubleshooting)
---
## Einführung
Das **Mindnet Causal Assistant** Plugin ist ein Authoring-Tool für Obsidian, das Sie dabei unterstützt:
- **Strukturierte Notes** anzulegen mit Frontmatter, IDs und Typen
- **Inhalte über konfigurierbare Interviews** zu erfassen
- **Semantische Kanten (Edges)** zu pflegen und zu validieren
- **Links und Edge-Zuordnungen** section-basiert zu gruppieren (Semantic Mapping)
- **Kausale Ketten** zu analysieren und zu validieren
### Hauptkonzepte
- **Profile**: Auswahl eines "Erstell-Profils" (kann mehrere Interviews pro Note-Typ geben)
- **Interview Config (YAML)**: Definiert Steps, Loops, Defaults, Frontmatter-Whitelist
- **ID-first**: Mindnet-Graph arbeitet über Frontmatter `id` als Schlüssel
- **Semantic Mapping**: Links in einer Section werden Edge-Typen zugeordnet und als Callouts strukturiert
- **Chain Templates**: Vordefinierte Muster für kausale Ketten (z.B. `trigger → transformation → outcome`)
---
## Schnellstart
### 1. Plugin aktivieren
1. Öffnen Sie **Settings → Community Plugins**
2. Stellen Sie sicher, dass "Restricted mode" ausgeschaltet ist
3. Aktivieren Sie das Plugin "Mindnet Causal Assistant"
### 2. Erste Konfiguration
Das Plugin benötigt Konfigurationsdateien im Vault. Diese sollten bereits vorhanden sein (siehe Administratorhandbuch). Standardpfade:
- `_system/dictionary/edge_vocabulary.md` - Edge-Typen-Vokabular
- `_system/dictionary/graph_schema.md` - Graph-Schema
- `_system/dictionary/interview_config.yaml` - Interview-Konfiguration
- `_system/dictionary/chain_roles.yaml` - Chain-Rollen-Mapping
- `_system/dictionary/chain_templates.yaml` - Chain-Templates
### 3. Erste Note erstellen
1. Öffnen Sie den Command Palette (`Ctrl+P` / `Cmd+P`)
2. Wählen Sie **"Mindnet: Create note from profile"**
3. Wählen Sie ein Profil aus
4. Geben Sie einen Titel ein
5. Wählen Sie einen Ordner (optional)
6. Die Note wird erstellt und geöffnet
7. Optional: Wizard startet automatisch (wenn konfiguriert)
---
## Hauptfunktionen
### 1. Note-Erstellung mit Profilen
**Zweck:** Erstellen strukturierter Mindnet-Notes mit korrektem Frontmatter.
**Verwendung:**
- Command: **"Mindnet: Create note from profile"**
- Profil wählen (z.B. "experience", "insight", "decision")
- Titel und Ordner festlegen
- Note wird mit Frontmatter erstellt (ID, Typ, Profil)
**Frontmatter-Beispiel:**
```yaml
---
id: note_1234567890_abc123
title: "Meine Erfahrung"
type: experience
interview_profile: experience_basic
---
```
### 2. Interview-Wizard
**Zweck:** Strukturierte Erfassung von Inhalten über konfigurierbare Interviews.
**Verwendung:**
- Startet automatisch nach Note-Erstellung (wenn aktiviert)
- Oder manuell über Command (geplant)
- Steps ausfüllen (Loops/Nested Loops möglich)
- Review → Apply & Finish
- Output wird in die Note geschrieben
**Features:**
- Verschachtelte Loops
- Section-basierte Ausgabe
- Frontmatter-Whitelist-Unterstützung
### 3. Semantic Mapping (Edger)
**Zweck:** Automatische Gruppierung von Links nach Edge-Typen in Mapping-Blöcken.
**Verwendung:**
- **Manuell:** Command **"Mindnet: Build semantic mapping blocks (by section)"**
- **Automatisch:** Nach Interview Finish (falls im Profil aktiviert)
**Output:**
- Pro Section ein Mapping-Block am Ende der Section:
- Wrapper Callout (Default: `abstract`)
- Gruppiert nach Edge-Typ
- Gruppen getrennt durch Leerzeile
**Beispiel:**
```markdown
## Meine Section
Inhalt mit Links: [[Note1]] und [[Note2]]
> [!abstract] 🕸️ Semantic Mapping
>
> > [!edge] causes
> > [[Note1]]
> >
> > [!edge] influences
> > [[Note2]]
```
### 4. Chain Inspector
**Zweck:** Analyse kausaler Ketten um die aktuelle Section.
**Verwendung:**
- Command: **"Mindnet: Inspect Chains (Current Section)"**
- Analysiert lokale Nachbarschaft + Pfade im Graphen
- Template Matching gegen vordefinierte Kettenmuster
- Findings (Gap-Heuristiken) werden generiert
**Report enthält:**
- Context (aktuelle Datei/Section)
- Neighbors (incoming/outgoing)
- Paths (vorwärts/rückwärts)
- Template Matches
- Findings (fehlende Slots, Links, etc.)
**Findings-Beispiele:**
- `missing_slot_*` - Wichtige Slots fehlen
- `dangling_target` - Edge verweist auf nicht-existierende Datei
- `dangling_target_heading` - Edge verweist auf nicht-existierendes Heading
- `missing_link_constraints` - Erwartete Links fehlen
- `no_causal_roles` - Keine kausalen Rollen gefunden
### 5. Fix Findings
**Zweck:** Automatische Behebung von Findings.
**Verwendung:**
- Command: **"Mindnet: Fix Findings (Current Section)"**
- Zeigt verfügbare Fix-Actions für Findings
- Wählt Action aus → wird ausgeführt
**Verfügbare Actions:**
- **Create Missing Note** - Erstellt fehlende Note (skeleton oder mit Wizard)
- **Retarget Link** - Ersetzt Link zu existierender Note
- **Create Missing Heading** - Erstellt Heading in Target-Datei
- **Retarget to Existing Heading** - Ersetzt Link zu existierendem Heading
- **Promote Candidate Edge** - Befördert Candidate-Edge zu explizitem Edge
### 6. Unresolved Link Handling
**Zweck:** Automatische Note-Erstellung beim Klick auf nicht-existierende Links.
**Verwendung:**
- Klick auf `[[Neue Note]]` in Reading View oder Editor
- Plugin übernimmt Flow (wenn aktiviert)
- Profil-Auswahl → Note wird erstellt
- Optional: Wizard startet automatisch
**Modifier-Keys:**
- **Reading View:** Bypass-Modifier (Standard: `Alt`) - umgeht Plugin-Intercept
- **Editor:** Follow-Modifier (Standard: `Ctrl`) - aktiviert Plugin-Intercept
### 7. Edge-Type-Änderung
**Zweck:** Ändern des Edge-Typs für Links.
**Verwendung:**
- Command: **"Mindnet: Edge-Type ändern"**
- Kontext wird automatisch erkannt:
- Cursor in Link → ändert diesen Link
- Auswahl mit Links → ändert alle Links in Auswahl
- Keine Auswahl → zeigt Edge-Type-Selector für neue Links
**Features:**
- Graph-Schema-basierte Empfehlungen
- Inline Micro-Suggester (wenn aktiviert)
- Typische/Prohibited Edge-Types
### 8. Note Adoption
**Zweck:** Automatische Konvertierung neu erstellter Notes zu Mindnet-Format.
**Verwendung:**
- Automatisch aktiviert (wenn konfiguriert)
- Erkennt neu erstellte Notes (klein, ohne ID)
- Zeigt Adoption-Modal (abhängig von Confidence)
- Profil-Auswahl → Frontmatter wird hinzugefügt
- Optional: Wizard startet
**Confidence-Levels:**
- **High:** Innerhalb Zeitfenster nach Link-Klick
- **Low:** Andere Fälle
---
## Workflows
### Workflow 1: Neue Note erstellen und ausfüllen
1. **Note erstellen:**
- Command: "Mindnet: Create note from profile"
- Profil wählen (z.B. "experience")
- Titel: "Meine Erfahrung"
- Ordner wählen
2. **Wizard ausfüllen:**
- Wizard startet automatisch (wenn aktiviert)
- Steps durchgehen
- Review → Apply & Finish
3. **Semantic Mapping:**
- Edger läuft automatisch (falls im Profil aktiviert)
- Oder manuell: "Mindnet: Build semantic mapping blocks"
4. **Validierung:**
- Command: "Mindnet: Validate current note"
- Prüft Lint-Regeln
- Zeigt Findings in Console
### Workflow 2: Kausale Kette analysieren
1. **Section öffnen:**
- Cursor in relevante Section positionieren
2. **Chain Inspector ausführen:**
- Command: "Mindnet: Inspect Chains (Current Section)"
- Report wird in Console ausgegeben
3. **Findings prüfen:**
- Console öffnen (F12)
- Findings analysieren
- Template Matches prüfen
4. **Findings beheben:**
- Command: "Mindnet: Fix Findings (Current Section)"
- Verfügbare Actions auswählen
- Automatische Behebung
### Workflow 5: Chain Workbench verwenden (Neu in 0.5.x)
1. **Section öffnen:**
- Cursor in relevante Section positionieren
2. **Chain Workbench öffnen:**
- Command: "Mindnet: Chain Workbench (Current Section)"
- Modal zeigt alle Template Matches
3. **Matches analysieren:**
- Filter nach Status (complete, near_complete, partial, weak)
- Suche nach Template-Name
- Match auswählen → Details anzeigen
4. **Todos bearbeiten:**
- Todo auswählen
- Action wählen (z.B. "Insert Edge", "Create Note", "Promote Candidate")
- Apply → Workbench aktualisiert sich automatisch
5. **Wiederholen:**
- Weitere Todos bearbeiten
- Status verbessert sich nach jedem Apply
### Workflow 6: Vault Triage Scan (Neu in 0.5.x)
1. **Scan starten:**
- Command: "Mindnet: Scan Vault for Chain Gaps"
- Modal öffnet sich
2. **Scan durchführen:**
- Klicke "Start Scan"
- Progress wird angezeigt
- Scan kann unterbrochen werden
3. **Backlog durchsuchen:**
- Filter nach Status, Gap-Typen
- Suche nach File, Heading, Template
- Sortierung: near_complete zuerst
4. **Items bearbeiten:**
- "Open Workbench" → öffnet Datei und Workbench
- "Deprioritize" → markiert als nicht fokussiert
- Items bleiben im Backlog (werden gefiltert)
5. **Resume:**
- Scan kann fortgesetzt werden (wenn unterbrochen)
- State wird gespeichert
### Workflow 3: Unresolved Link → Note erstellen
1. **Link erstellen:**
- `[[Neue Note]]` in Note schreiben
2. **Link anklicken:**
- Reading View: Normaler Klick
- Editor: `Ctrl` + Klick (wenn Follow-Modifier aktiviert)
3. **Profil wählen:**
- Profile-Selection-Modal öffnet sich
- Profil auswählen
4. **Note wird erstellt:**
- Frontmatter wird hinzugefügt
- Wizard startet (wenn aktiviert)
### Workflow 4: Edge-Type ändern
1. **Link markieren:**
- Cursor in Link positionieren
- Oder mehrere Links auswählen
2. **Command ausführen:**
- "Mindnet: Edge-Type ändern"
3. **Edge-Type wählen:**
- Modal zeigt verfügbare Types
- Empfehlungen basierend auf Graph-Schema
- Type auswählen
4. **Änderung wird angewendet:**
- Link wird aktualisiert
- Semantic Mapping wird aktualisiert (falls vorhanden)
---
## Commands im Detail
### Note-Erstellung & Interview
| Command | Beschreibung | Wann verwenden |
|---------|--------------|----------------|
| **Mindnet: Create note from profile** | Erstellt neue Note mit Profil | Neue Note von Grund auf erstellen |
| *(Geplant)* **Mindnet: Start interview wizard** | Startet Wizard für aktuelle Note | Interview manuell starten |
### Mapping & Edges
| Command | Beschreibung | Wann verwenden |
|---------|--------------|----------------|
| **Mindnet: Build semantic mapping blocks (by section)** | Baut Semantic Mapping Blöcke | Links nach Edge-Typen gruppieren |
| **Mindnet: Edge-Type ändern** | Ändert Edge-Type für Links | Edge-Typ korrigieren/zuordnen |
| **Mindnet: Reload edge vocabulary** | Lädt Edge-Vokabular neu | Nach Änderung an edge_vocabulary.md |
### Analyse & Validierung
| Command | Beschreibung | Wann verwenden |
|---------|--------------|----------------|
| **Mindnet: Inspect Chains (Current Section)** | Analysiert kausale Ketten | Chain-Analyse durchführen |
| **Mindnet: Chain Workbench (Current Section)** | Workbench für alle Template Matches mit Todos | Chain-Gaps identifizieren und beheben |
| **Mindnet: Scan Vault for Chain Gaps** | Scannt gesamten Vault nach Chain-Gaps | Vault-weites Backlog erstellen |
| **Mindnet: Fix Findings (Current Section)** | Behebt Findings automatisch | Findings automatisch beheben |
| **Mindnet: Validate current note** | Validiert aktuelle Note (Lint) | Note auf Fehler prüfen |
### Export & Debug
| Command | Beschreibung | Wann verwenden |
|---------|--------------|----------------|
| **Mindnet: Export graph** | Exportiert Graph als JSON | Graph exportieren |
| **Mindnet: Show chains from current note** | Zeigt Ketten von aktueller Note | Ketten-Exploration |
| **Mindnet: Debug Chain Roles (Loaded)** | Debug-Info für Chain Roles | Debugging |
| **Mindnet: Debug Chain Templates (Loaded)** | Debug-Info für Chain Templates | Debugging |
> **Detaillierte Referenz:** Siehe [07_Event_Handler_Commands.md](./07_Event_Handler_Commands.md) für vollständige Beschreibung aller Commands, Event Handler und Settings.
---
## Troubleshooting
### Wizard startet nicht
**Symptom:** Wizard startet nicht nach Note-Erstellung.
**Lösung:**
1. Prüfen Sie Settings: `autoStartInterviewOnCreate`
2. Prüfen Sie DevTools Console (F12) auf Fehler
3. Prüfen Sie Interview-Config-Pfad in Settings
### Edger schreibt Blöcke an falscher Stelle
**Symptom:** Semantic Mapping Blöcke erscheinen an falscher Position.
**Lösung:**
1. Prüfen Sie Heading-Parsing (Section-Erkennung)
2. Prüfen Sie, ob Wrapper-Block korrekt erkannt/ersetzt wird
3. Prüfen Sie Console-Logs für Details
### Schema-Empfehlungen fehlen
**Symptom:** Keine Empfehlungen beim Edge-Type-Ändern.
**Lösung:**
1. Prüfen Sie `graph_schema_path` in Settings
2. Prüfen Sie Schema-Loader Stats/Logging in Console
3. Prüfen Sie, ob Schema-Datei existiert und gültig ist
### Chain Inspector findet keine Matches
**Symptom:** Template Matches sind leer.
**Lösung:**
1. Prüfen Sie Chain-Templates-Pfad in Settings
2. Prüfen Sie Console-Logs für Template-Loading
3. Prüfen Sie, ob Note-Types korrekt im Frontmatter sind
4. Prüfen Sie, ob Edges korrekt gemappt sind (chain_roles.yaml)
### Unresolved Link wird nicht abgefangen
**Symptom:** Klick auf `[[Neue Note]]` öffnet Obsidian-Dialog statt Plugin-Flow.
**Lösung:**
1. Prüfen Sie Settings: `interceptUnresolvedLinkClicks`
2. **Reading View:** Bypass-Modifier nicht drücken
3. **Editor:** Follow-Modifier (`Ctrl`) drücken beim Klick
4. Prüfen Sie Console-Logs für Details
### Note Adoption funktioniert nicht
**Symptom:** Neu erstellte Notes werden nicht adoptiert.
**Lösung:**
1. Prüfen Sie Settings: `adoptNewNotesInEditor`
2. Prüfen Sie, ob Note klein genug ist (`adoptMaxChars`)
3. Prüfen Sie, ob Note bereits Frontmatter-ID hat (wird nicht adoptiert)
4. Prüfen Sie Console-Logs für Adoption-Confidence
---
## Weitere Ressourcen
- **Administratorhandbuch:** Konfiguration und Wartung
- **Entwicklerhandbuch:** Code-Struktur und Erweiterungen
- **Architektur-Dokumentation:** System-Übersicht
- **Installation & Deployment:** Setup-Anleitung
---
**Ende des Benutzerhandbuchs**
Reference in New Issue View Git Blame Copy Permalink