Lars
74cacdd41d
- 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.
515 lines
13 KiB
Markdown
515 lines
13 KiB
Markdown
# 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**
|