Lars/mindnet_obsidian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
3be7d617fe
mindnet_obsidian/docs/02_Administratorhandbuch.md
Lars 74cacdd41d
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
Update documentation and enhance chain inspection logic 
- Revamped the README to provide comprehensive documentation for the Mindnet Causal Assistant plugin, including user, administrator, developer, and architect guides.
- Added specialized documentation sections for installation, deployment, and troubleshooting.
- Enhanced the chain inspection logic to determine effective required links based on template definitions, profiles, and defaults, improving the accuracy of findings related to link completeness.
2026-01-20 11:34:58 +01:00

515 lines
13 KiB
Markdown
Raw Blame History

# Mindnet Causal Assistant - Administratorhandbuch
> **Version:** 1.0.0
> **Stand:** 2025-01-XX
> **Zielgruppe:** Administratoren, Config-Manager, Vault-Verwalter
---
## Inhaltsverzeichnis
1. [Überblick](#überblick)
2. [Plugin-Konfiguration](#plugin-konfiguration)
3. [Konfigurationsdateien](#konfigurationsdateien)
4. [Pfad-Management](#pfad-management)
5. [Live-Reload](#live-reload)
6. [Wartung & Troubleshooting](#wartung--troubleshooting)
---
## Überblick
Das Mindnet Causal Assistant Plugin benötigt mehrere Konfigurationsdateien, die im Vault gespeichert werden. Diese Dateien definieren:
- **Edge-Vokabular:** Kanonische Edge-Typen und Aliases
- **Graph-Schema:** Empfehlungen für Edge-Typen basierend auf Note-Typen
- **Interview-Config:** Profile, Steps, Loops für Note-Erstellung
- **Chain Roles:** Mapping von Edge-Typen zu kausalen Rollen
- **Chain Templates:** Vordefinierte Kettenmuster für Template Matching
---
## Plugin-Konfiguration
### Settings-Zugriff
**Settings → Community Plugins → Mindnet Causal Assistant**
### Wichtige Settings
#### Pfad-Settings
| Setting | Standard | Beschreibung |
|---------|----------|--------------|
| `edgeVocabularyPath` | `_system/dictionary/edge_vocabulary.md` | Pfad zum Edge-Vokabular |
| `graphSchemaPath` | `_system/dictionary/graph_schema.md` | Pfad zum Graph-Schema |
| `interviewConfigPath` | `_system/dictionary/interview_config.yaml` | Pfad zur Interview-Config |
| `chainRolesPath` | `_system/dictionary/chain_roles.yaml` | Pfad zu Chain Roles |
| `chainTemplatesPath` | `_system/dictionary/chain_templates.yaml` | Pfad zu Chain Templates |
| `analysisPoliciesPath` | `_system/dictionary/analysis_policies.yaml` | Pfad zu Analysis Policies |
#### Feature-Settings
| Setting | Standard | Beschreibung |
|---------|----------|--------------|
| `interceptUnresolvedLinkClicks` | `true` | Unresolved Links abfangen |
| `autoStartInterviewOnCreate` | `false` | Wizard automatisch starten |
| `adoptNewNotesInEditor` | `true` | Neue Notes automatisch adoptieren |
| `chainInspectorIncludeCandidates` | `false` | Candidate-Edges in Chain Inspector einbeziehen |
| `templateMatchingProfile` | `"discovery"` | Template-Matching-Profil (`discovery` / `decisioning`) |
#### Fix-Actions-Settings
| Setting | Standard | Beschreibung |
|---------|----------|--------------|
| `fixActions.createMissingNote.mode` | `"skeleton_only"` | Modus für fehlende Notes |
| `fixActions.createMissingHeading.level` | `2` | Heading-Level für neue Headings |
| `fixActions.promoteCandidate.keepOriginal` | `true` | Original bei Candidate-Promotion behalten |
---
## Konfigurationsdateien
> **Detaillierte Referenz:** Siehe [06_Konfigurationsdateien_Referenz.md](./06_Konfigurationsdateien_Referenz.md) für vollständige Format-Beschreibungen.
### 1. Edge Vocabulary (`edge_vocabulary.md`)
**Zweck:** Definiert kanonische Edge-Typen und Aliases.
**Format:** Markdown mit Callout-Struktur
**Beispiel:**
```markdown
# Edge Vocabulary
> [!edge-type] causes
> Canonical: causes
> Aliases: ausgelöst_durch, verursacht
> [!edge-type] influences
> Canonical: influences
> Aliases: beeinflusst, wirkt_auf
```
**Struktur:**
- `[!edge-type]` Callout mit kanonischem Namen
- `Canonical:` Zeile mit kanonischem Typ
- `Aliases:` Zeile mit komma-separierten Aliases
**Wartung:**
- Neue Edge-Types hinzufügen: Neuen Callout-Block hinzufügen
- Aliases hinzufügen: Komma-separiert zur `Aliases:` Zeile
- Live-Reload: Automatisch nach Dateiänderung (debounced)
---
### 2. Graph Schema (`graph_schema.md`)
**Zweck:** Empfehlungen für Edge-Typen basierend auf Source-Note-Typen.
**Format:** Markdown mit Callout-Struktur
**Beispiel:**
```markdown
# Graph Schema
> [!schema] experience
> Typical: causes, influences
> Prohibited: part_of, instance_of
```
**Struktur:**
- `[!schema]` Callout mit Note-Type als Titel
- `Typical:` Komma-separierte typische Edge-Types
- `Prohibited:` Komma-separierte verbotene Edge-Types
**Verwendung:**
- Edge-Type-Selector zeigt Empfehlungen basierend auf Source-Note-Type
- Warnungen bei prohibited Types
**Wartung:**
- Neue Note-Types hinzufügen: Neuen Callout-Block hinzufügen
- Empfehlungen anpassen: `Typical:` / `Prohibited:` Zeilen ändern
- Live-Reload: Automatisch nach Dateiänderung (debounced)
---
### 3. Interview Config (`interview_config.yaml`)
**Zweck:** Definiert Profile, Steps, Loops für Note-Erstellung und Interviews.
**Format:** YAML
**Struktur:**
```yaml
version: "1.0"
frontmatter_whitelist:
- tags
- status
profiles:
- key: experience_basic
note_type: experience
description: "Basic experience profile"
defaults:
folder: "experiences"
steps:
- id: context
prompt: "Beschreibe den Kontext"
input_type: textarea
post_run:
edger: true
```
**Wichtige Felder:**
- **`version`:** Config-Version
- **`frontmatter_whitelist`:** Erlaubte Frontmatter-Keys (zusätzlich zu Standard)
- **`profiles`:** Liste von Profilen
- **`key`:** Eindeutiger Profil-Schlüssel
- **`note_type`:** Note-Type (z.B. `experience`, `insight`, `decision`)
- **`defaults`:** Standardwerte (z.B. `folder`)
- **`steps`:** Interview-Steps
- **`post_run`:** Post-Run-Actions (z.B. `edger: true`)
**Wartung:**
- Neue Profile hinzufügen: Neuen Eintrag unter `profiles` hinzufügen
- Steps anpassen: `steps` Array modifizieren
- Loops hinzufügen: `loop` Feld in Steps verwenden
- Live-Reload: Automatisch nach Dateiänderung (debounced)
**Validierung:**
- YAML-Syntax wird beim Laden geprüft
- Fehler werden in Console geloggt
- Last-Known-Good wird verwendet bei Fehlern
---
### 4. Chain Roles (`chain_roles.yaml`)
**Zweck:** Mapping von Edge-Typen zu kausalen Rollen für Template Matching.
**Format:** YAML
**Struktur:**
```yaml
version: "1.0"
roles:
causal:
edge_types:
- causes
- caused_by
- resulted_in
influences:
edge_types:
- influences
- affects
enables_constraints:
edge_types:
- enables
- constrains
```
**Rollen:**
- **`causal`:** Direkte kausale Beziehungen
- **`influences`:** Einfluss-Beziehungen
- **`enables_constraints`:** Ermöglicht/Beschränkt-Beziehungen
- **`provenance`:** Herkunfts-Beziehungen
**Wartung:**
- Neue Rollen hinzufügen: Neuen Eintrag unter `roles` hinzufügen
- Edge-Types zuordnen: `edge_types` Array erweitern
- Live-Reload: Automatisch nach Dateiänderung (debounced)
**Validierung:**
- YAML-Syntax wird beim Laden geprüft
- Fehler werden in Console geloggt
- Last-Known-Good wird verwendet bei Fehlern
---
### 5. Chain Templates (`chain_templates.yaml`)
**Zweck:** Vordefinierte Kettenmuster für Template Matching.
**Format:** YAML
**Struktur:**
```yaml
version: "1.0"
defaults:
matching:
required_links: false
templates:
- name: trigger_transformation_outcome
description: "Causal chain template"
slots:
- id: trigger
allowed_node_types: ["experience"]
- id: transformation
allowed_node_types: ["insight"]
- id: outcome
allowed_node_types: ["decision"]
links:
- from: trigger
to: transformation
allowed_edge_roles: ["causal"]
- from: transformation
to: outcome
allowed_edge_roles: ["causal"]
matching:
required_links: true
```
**Wichtige Felder:**
- **`defaults.matching.required_links`:** Standard für required_links (strict/soft)
- **`templates`:** Liste von Templates
- **`name`:** Template-Name
- **`slots`:** Slot-Definitionen mit `allowed_node_types`
- **`links`:** Link-Constraints mit `allowed_edge_roles`
- **`matching`:** Matching-Parameter (überschreibt Defaults)
**Wartung:**
- Neue Templates hinzufügen: Neuen Eintrag unter `templates` hinzufügen
- Slots anpassen: `slots` Array modifizieren
- Link-Constraints anpassen: `links` Array modifizieren
- Live-Reload: Automatisch nach Dateiänderung (debounced)
**Validierung:**
- YAML-Syntax wird beim Laden geprüft
- Fehler werden in Console geloggt
- Last-Known-Good wird verwendet bei Fehlern
---
### 6. Analysis Policies (`analysis_policies.yaml`)
**Zweck:** Policies für Findings (Severity, Unterdrückung, etc.).
**Format:** YAML (geplant)
**Status:** Noch nicht vollständig implementiert
**Geplante Struktur:**
```yaml
version: "1.0"
findings:
missing_slot_*:
default_severity: warn
profiles:
discovery:
severity: info
decisioning:
severity: warn
dangling_target:
default_severity: error
suppress_if: []
```
---
## Pfad-Management
### Standard-Pfade
Alle Konfigurationsdateien werden standardmäßig unter `_system/dictionary/` erwartet:
```
_system/
dictionary/
edge_vocabulary.md
graph_schema.md
interview_config.yaml
chain_roles.yaml
chain_templates.yaml
analysis_policies.yaml
```
### Pfad-Änderung
**Vorgehen:**
1. Settings öffnen: **Settings → Community Plugins → Mindnet Causal Assistant**
2. Pfad-Setting ändern (z.B. `edgeVocabularyPath`)
3. Settings speichern
4. Plugin lädt Config automatisch neu
**Hinweise:**
- Pfade sind vault-relativ (beginnen mit `/` oder ohne)
- Forward-Slashes werden normalisiert
- Dateien müssen existieren (sonst Fehler beim Laden)
---
## Live-Reload
### Automatisches Reload
**Funktionsweise:**
- Plugin überwacht Konfigurationsdateien auf Änderungen
- Bei Änderung: Debounced Reload (200ms Delay)
- Last-Known-Good wird verwendet bei Fehlern
**Überwachte Dateien:**
- `edge_vocabulary.md`
- `graph_schema.md`
- `interview_config.yaml`
- `chain_roles.yaml`
- `chain_templates.yaml`
### Manuelles Reload
**Commands:**
- **"Mindnet: Reload edge vocabulary"** - Lädt Edge-Vokabular neu
**Verwendung:**
- Nach größeren Änderungen
- Wenn automatisches Reload nicht funktioniert
- Für Debugging
### Reload-Status prüfen
**Console-Logs:**
- Öffnen Sie DevTools (F12)
- Prüfen Sie Console-Logs nach Reload-Events
- Fehler werden geloggt
**Beispiel-Logs:**
```
Vocabulary loaded { canonicalCount: 10, aliasCount: 5 }
Interview config reloaded: 3 profile(s)
Chain roles reloaded: 4 roles
Chain templates reloaded: 2 templates
```
---
## Wartung & Troubleshooting
### Konfigurationsdateien prüfen
**YAML-Syntax prüfen:**
```bash
# Mit yamllint (falls installiert)
yamllint _system/dictionary/interview_config.yaml
```
**Markdown-Syntax prüfen:**
- Manuelle Prüfung der Callout-Struktur
- Prüfen auf korrekte Formatierung
### Häufige Probleme
#### 1. Config wird nicht geladen
**Symptom:** Plugin zeigt Fehler "Config not found".
**Lösung:**
1. Prüfen Sie Pfad in Settings
2. Prüfen Sie, ob Datei existiert
3. Prüfen Sie Datei-Berechtigungen
4. Prüfen Sie Console-Logs für Details
#### 2. YAML-Syntax-Fehler
**Symptom:** Config wird mit Fehlern geladen.
**Lösung:**
1. Prüfen Sie YAML-Syntax (z.B. mit yamllint)
2. Prüfen Sie Console-Logs für Fehlerdetails
3. Last-Known-Good wird verwendet (prüfen Sie Logs)
4. Korrigieren Sie Syntax-Fehler
#### 3. Live-Reload funktioniert nicht
**Symptom:** Änderungen werden nicht übernommen.
**Lösung:**
1. Prüfen Sie, ob Datei-Pfad korrekt ist
2. Warten Sie auf Debounce (200ms)
3. Manuelles Reload über Command
4. Plugin neu laden (disable/enable)
#### 4. Last-Known-Good wird verwendet
**Symptom:** Console zeigt "using-last-known-good".
**Lösung:**
1. Prüfen Sie YAML-Syntax-Fehler
2. Korrigieren Sie Fehler
3. Reload wird automatisch versucht
4. Oder manuelles Reload über Command
### Best Practices
#### 1. Versionierung
**Empfehlung:**
- Verwenden Sie Versionsnummern in Config-Dateien
- Dokumentieren Sie Änderungen
- Testen Sie Änderungen in Test-Vault
#### 2. Backup
**Empfehlung:**
- Regelmäßige Backups der Config-Dateien
- Git-Versionierung empfohlen
- Vor größeren Änderungen Backup erstellen
#### 3. Testing
**Empfehlung:**
- Testen Sie Änderungen in Test-Vault
- Prüfen Sie Console-Logs nach Änderungen
- Validieren Sie YAML-Syntax vor Commit
#### 4. Dokumentation
**Empfehlung:**
- Dokumentieren Sie Custom-Profile
- Dokumentieren Sie Custom-Templates
- Kommentare in YAML-Dateien verwenden
---
## Debug-Commands
### Chain Roles Debug
**Command:** "Mindnet: Debug Chain Roles (Loaded)"
**Output:** Console-Log mit:
- Resolved Path
- Status (loaded/error/using-last-known-good)
- Loaded At (Timestamp)
- Errors/Warnings
- Roles-Übersicht
### Chain Templates Debug
**Command:** "Mindnet: Debug Chain Templates (Loaded)"
**Output:** Console-Log mit:
- Resolved Path
- Status (loaded/error/using-last-known-good)
- Loaded At (Timestamp)
- Errors/Warnings
- Templates-Übersicht
---
## Weitere Ressourcen
- **Benutzerhandbuch:** Endnutzer-Workflows
- **Entwicklerhandbuch:** Code-Struktur und Erweiterungen
- **Architektur-Dokumentation:** System-Übersicht
- **Installation & Deployment:** Setup-Anleitung
---
**Ende des Administratorhandbuchs**
Reference in New Issue View Git Blame Copy Permalink