Implement Phase 3 Agentic Edge Validation and Chunk-Aware Multigraph-System
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Deploy mindnet to llm-node / deploy (push) Successful in 4s
- Introduced final validation gate for edges with candidate: prefix. - Enabled automatic generation of mirror edges for explicit connections. - Added support for Note-Scope zones to facilitate global connections. - Enhanced section-based links in the multigraph system for improved edge handling. - Updated documentation and added new ENV variables for configuration. - Ensured no breaking changes for end users, maintaining full backward compatibility.
This commit is contained in:
1 parent
273c4c6919
commit
39a6998123
4 files changed
+608
No files matched your search
@@ -0,0 +1,250 @@
|
||||
<!-- DOCUMENT 1: pflichtenheft_obsidian_plugin_mindnet_assistant.md -->
|
||||
---
|
||||
id: pflichtenheft_obsidian_plugin_mindnet_assistant
|
||||
title: Pflichtenheft – Obsidian Plugin „Mindnet Causal Assistant“
|
||||
type: specification
|
||||
status: draft
|
||||
created: 2026-01-13
|
||||
lang: de
|
||||
---
|
||||
|
||||
# Pflichtenheft – Obsidian Plugin „Mindnet Causal Assistant“
|
||||
|
||||
## 1. Zielsetzung
|
||||
Das Plugin unterstützt den Nutzer beim Erstellen und Pflegen eines narrativ-kausalen Wissensgraphen in Obsidian (Mindnet).
|
||||
|
||||
Es bietet:
|
||||
- **Aktive Authoring-Unterstützung** (Guided Note Creation / Interview Flow)
|
||||
- **Kausalketten-Prüfung** (Chain Explorer, Vorwärts/Rückwärts)
|
||||
- **Linting + Auto-Fixes** (Graph-Hygiene, konsistente Kanten, Namensnormalisierung)
|
||||
- **Export/Integration** der strukturierten Graph-Daten für ein Retrieval-System (Qdrant + Graph-Index)
|
||||
|
||||
## 2. Kontext & Randbedingungen
|
||||
- Obsidian Vault enthält Notes als Markdown, jede Entität eine Datei.
|
||||
- Notes enthalten Frontmatter (`id,title,type,status,...`) und Edges in Callout-Blöcken.
|
||||
- Edge-Vokabular inklusive Aliasse & Inversen ist verfügbar (z.B. `edge_vocabulary.md`).
|
||||
- Der Graph soll später von Mindnet traversierbar sein (Vorwärts/Rückwärts über inverse Relationen).
|
||||
- Plugin muss offline nutzbar sein; optionale Backend/LLM-Integration ist konfigurierbar.
|
||||
|
||||
## 3. Begriffsdefinitionen
|
||||
- **Node**: eine Obsidian Markdown-Datei (Entität).
|
||||
- **Edge**: gerichtete Beziehung zwischen zwei Nodes (canonical edge type).
|
||||
- **Alias**: alternative Edge-Bezeichnung in Notes, die auf canonical mapped wird.
|
||||
- **Inverse**: Gegenkante zu einer Edge, laut Vokabular (z.B. `resulted_in` ⇄ `caused_by`).
|
||||
- **Hub/Index**: Note, die primär navigiert (typisch `type: insight`), keine Kausalursache.
|
||||
|
||||
## 4. Scope
|
||||
### In Scope (MVP → V2)
|
||||
**MVP**
|
||||
- Parser für Frontmatter + Edge-Callouts
|
||||
- Normalizer: Alias → Canonical; optional Inversen-Erkennung
|
||||
- Linter: Regelset (Error/Warn/Info) + Report
|
||||
- Chain Explorer: forward/backward traversal (1–4 hops) ab aktueller Note
|
||||
- Quickfixes: Edge-Typ ersetzen, Links normalisieren, Missing Note Stub erzeugen
|
||||
|
||||
**V2**
|
||||
- Guided Authoring (Interview Flow) für `experience/decision/principle/state/strategy`
|
||||
- Refactor Mode: Text → Node/Edge-Kandidaten + Review UI
|
||||
- Export/Sync: JSON Graph Export + optional Qdrant Sync (separater Service)
|
||||
|
||||
### Out of Scope (initial)
|
||||
- Vollautomatische Kausalitäts-Interpretation ohne User-Bestätigung
|
||||
- Vollständige UI-Graph-Visualisierung (Obsidian Graph View bleibt nutzbar)
|
||||
- Direkte medizinische/psychologische Beratung
|
||||
|
||||
## 5. Nutzerrollen & Use Cases
|
||||
### Rolle: Nutzer (Author)
|
||||
- UC1: „Ich schreibe eine Note und will Kanten prüfen“
|
||||
- UC2: „Ich will von einem Ereignis aus die Kausalkette sehen“
|
||||
- UC3: „Ich will eine neue Experience/Decision Note sauber anlegen“
|
||||
- UC4: „Ich habe Text und will daraus Kandidaten extrahieren“
|
||||
- UC5: „Ich will leere Links als open_question sauber erzeugen“
|
||||
|
||||
### Rolle: System/Indexer (Mindnet)
|
||||
- UC6: „Ich brauche exportierbare adjacency lists + canonical edges“
|
||||
|
||||
## 6. Funktionale Anforderungen (FR)
|
||||
|
||||
### FR1: Vault Parsing
|
||||
- FR1.1 Parse Frontmatter (YAML): `id,title,type,status,date,tags,...`
|
||||
- FR1.2 Parse Edge-Callouts im Format:
|
||||
- `> [!abstract]- 🕸️ Semantic Mapping`
|
||||
- `>> [!edge] <relation>`
|
||||
- `>> [[target]]`
|
||||
- FR1.3 Extrahiere alle WikiLinks `[[...]]` aus Edge-Blocks
|
||||
- FR1.4 Erkenne Datei-Pfade, Dateinamen und canonical node identifiers (Dateiname ohne `.md`)
|
||||
|
||||
**Output (intern)**
|
||||
```ts
|
||||
type Node = { id?: string; title?: string; type?: string; status?: string; path: string; slug: string };
|
||||
type Edge = { srcSlug: string; dstSlug: string; rawType: string; canonicalType?: string; line?: number; blockId?: string };
|
||||
```
|
||||
|
||||
### FR2: Edge Normalization
|
||||
- FR2.1 Map rawType/Alias auf canonical edge type via Edge Vocabulary
|
||||
- FR2.2 Speichere Mapping-Entscheidungen (raw → canonical) pro Edge
|
||||
- FR2.3 Liefere inverse edge type (`inverseType`) pro canonical edge type (sofern definiert)
|
||||
|
||||
### FR3: Linting
|
||||
- FR3.1 Führe Checkliste von Regeln aus (siehe separates Dokument)
|
||||
- FR3.2 Liefere LintReport mit Severity (ERROR/WARN/INFO), Location (file, line), Fix-Vorschlägen
|
||||
- FR3.3 Quickfix: wende Fix auf Note an (Text edit), mit Preview/Diff
|
||||
|
||||
### FR4: Chain Explorer (Traversal)
|
||||
- FR4.1 Startpunkt: aktuelle Note im Editor
|
||||
- FR4.2 Forward traversal: `resulted_in`, `followed_by`, `impacts`, `source_of`, optional `related_to`
|
||||
- FR4.3 Backward traversal: `caused_by`, `preceeded_by`, `derived_from`, `impacted_by`
|
||||
- FR4.4 Konfigurierbare maxHops (Default 3)
|
||||
- FR4.5 Ergebnis als Liste von Pfaden + kompaktes Subgraph-Summary (Nodes/Edges)
|
||||
|
||||
### FR5: Missing Notes / Stubs
|
||||
- FR5.1 Erkenne, wenn Edge-Target nicht existiert
|
||||
- FR5.2 Biete „Create Stub Note“ an:
|
||||
- Template basierend auf Typ (default `open_question` wenn unbekannt)
|
||||
- Einhaltung Naming-Rules: `a-z0-9_`
|
||||
- FR5.3 Optional: convert TODO-Link → open_question note
|
||||
|
||||
### FR6: Guided Authoring (V2)
|
||||
- FR6.1 Wizard für neue Notes: Auswahl Typ → Fragen (eine nach der anderen)
|
||||
- FR6.2 Wizard erstellt Datei mit Template + initialen Edge-Blocks
|
||||
- FR6.3 Jede automatische Edge-Vermutung ist „review-required“
|
||||
|
||||
### FR7: Refactor Mode (V2)
|
||||
- FR7.1 Extrahiere aus aktuellem Note-Text Kandidaten:
|
||||
- Event-Kandidaten (Datum/Ort/Verben)
|
||||
- Decision-Kandidaten („entschied“, „nahm an“, „wechselte“)
|
||||
- Principle-Kandidaten („ich glaube“, „ich habe gelernt“)
|
||||
- Relation-Kandidaten („dadurch“, „führte zu“, „weil“)
|
||||
- FR7.2 UI-Review: Checkbox-Liste zum Erstellen/Verwerfen
|
||||
- FR7.3 Generiere Notes + Edges nur nach Bestätigung
|
||||
|
||||
### FR8: Export (MVP optional / V2 empfohlen)
|
||||
- FR8.1 Export JSON: Nodes + canonical edges + inverses
|
||||
- FR8.2 Export adjacency list pro node slug
|
||||
- FR8.3 Optional: webhook/CLI hook für Indexer (Qdrant)
|
||||
|
||||
## 7. Nicht-funktionale Anforderungen (NFR)
|
||||
- NFR1: Performant bei 10k Notes (incremental parse, caching)
|
||||
- NFR2: Offline-first; LLM/Backend optional
|
||||
- NFR3: Deterministische Normalisierung (gleiches Input → gleiches Output)
|
||||
- NFR4: Kein Erfinden von Fakten: Auto-Edge nur als Vorschlag
|
||||
- NFR5: Sicheres Editieren (Diff/Undo via Obsidian APIs)
|
||||
- NFR6: Konfigurierbarkeit (YAML/Settings Tab): maxHops, allowed edges, strict mode
|
||||
|
||||
## 8. Technisches Lösungsdesign
|
||||
|
||||
### 8.1 Obsidian Plugin Struktur (TypeScript)
|
||||
- `main.ts` – Plugin lifecycle, commands, views
|
||||
- `settings.ts` – Einstellungen
|
||||
- `parser/` – Markdown + callout parser
|
||||
- `graph/` – Node/Edge model, normalization, traversal
|
||||
- `lint/` – Rules engine, reports, quickfixes
|
||||
- `ui/` – Sidebar view, modals, diff preview
|
||||
|
||||
### 8.2 Speicherung / Cache
|
||||
- In-memory cache: map `path → parsed Node + edges + hash`
|
||||
- Incremental update: on file change events re-parse only changed file
|
||||
- Optional persisted cache in `.obsidian/plugins/.../cache.json`
|
||||
|
||||
### 8.3 Edge Vocabulary Integration
|
||||
- Input: `edge_vocabulary.md` im Vault ODER eingebettete JSON Ressource
|
||||
- Parsing:
|
||||
- canonical edge types
|
||||
- alias list
|
||||
- inverse mapping
|
||||
- Fallback: minimal builtin vocabulary, wenn Datei fehlt
|
||||
|
||||
### 8.4 Traversal Engine
|
||||
- Graph Index: adjacency lists aus canonical edges
|
||||
- Traversal:
|
||||
- BFS mit hop limit
|
||||
- optional weighted expansion (für Chain Explorer „relevant paths first“)
|
||||
|
||||
### 8.5 Quickfix Engine
|
||||
- Applies patches auf Markdown:
|
||||
- Replace edge type token im Callout (`>> [!edge] ...`)
|
||||
- Rename link targets (replace `[[old]]` → `[[new]]`)
|
||||
- Insert stub note file from template
|
||||
- Safety:
|
||||
- Show diff modal
|
||||
- Use Obsidian editor transactions / file API
|
||||
|
||||
### 8.6 Optional Backend / LLM (V2)
|
||||
- Backend (local node service) für:
|
||||
- text extraction (Refactor Mode)
|
||||
- suggestion generation
|
||||
- Communication:
|
||||
- HTTP local (`127.0.0.1`) oder WebSocket
|
||||
- API key storage via Obsidian settings (encrypted if possible)
|
||||
- Claude-code/Cursor: nutzt Code-Agent für Implementierung, nicht zur Runtime.
|
||||
|
||||
## 9. UI/UX Anforderungen
|
||||
|
||||
### 9.1 Sidebar View „Mindnet Assistant“
|
||||
Tabs:
|
||||
- **Validate**: Lint Report + Fix Buttons
|
||||
- **Chains**: Forward/Backward Chain Explorer + Copy as text
|
||||
- **Create** (V2): Wizard new note
|
||||
- **Refactor** (V2): Extract candidates
|
||||
|
||||
### 9.2 Commands (Command Palette)
|
||||
- `Mindnet: Validate current note`
|
||||
- `Mindnet: Validate vault (selected folders)`
|
||||
- `Mindnet: Show chains from current note`
|
||||
- `Mindnet: Normalize edges in current note`
|
||||
- `Mindnet: Create stub for missing links`
|
||||
- (V2) `Mindnet: Start guided authoring`
|
||||
- (V2) `Mindnet: Refactor current note to graph`
|
||||
|
||||
## 10. Akzeptanzkriterien
|
||||
- AK1: Plugin erkennt Edge-Callouts und normalisiert Aliasse deterministisch
|
||||
- AK2: Linter findet Node-Splitting (mindestens Levenshtein/ähnliche Slugs) und Missing Notes
|
||||
- AK3: Chain Explorer liefert identische Pfade vorwärts/rückwärts bei inversen Edge-Paaren
|
||||
- AK4: Quickfix ersetzt Edge-Typen ohne Markdown zu zerstören; Undo funktioniert
|
||||
- AK5: Export JSON enthält canonical edges + inverse types
|
||||
|
||||
## 11. Deliverables
|
||||
- Obsidian Plugin (TS) mit MVP Features
|
||||
- Dokumentation:
|
||||
- Install/Build
|
||||
- Settings
|
||||
- Rule reference
|
||||
- Example vault sample
|
||||
- Optional: JSON Export Format Spec (nodes/edges)
|
||||
|
||||
---
|
||||
|
||||
## 12. Prompts für Code-Agenten (Cursor / Claude-code)
|
||||
|
||||
### Prompt A (Repo Scaffold + MVP)
|
||||
> Du bist ein Senior TypeScript Engineer. Implementiere ein Obsidian Plugin „Mindnet Causal Assistant“.
|
||||
> Ziele MVP:
|
||||
> 1) Parse Frontmatter (YAML) und Edge-Callouts im Format:
|
||||
> `> [!abstract]- 🕸️ Semantic Mapping` → `>> [!edge] <relation>` → `>> [[target]]`.
|
||||
> 2) Normalisiere Edge Aliasse auf canonical edge types (Vokabular als JSON im Code; später ersetzbar).
|
||||
> 3) Baue eine Sidebar View mit Tabs „Validate“ und „Chains“.
|
||||
> 4) Implementiere Lint Regeln: missing target note, alias-not-normalized, hub-has-causal-edge, chronology-vs-causality warning.
|
||||
> 5) Implementiere Chain Explorer (forward/backward, maxHops=3).
|
||||
> 6) Implementiere Quickfix: replace edge type token, create stub note.
|
||||
> Nutze Obsidian APIs, schreibe sauberen TS Code, mit Tests für Parser/Normalizer.
|
||||
|
||||
### Prompt B (Parser Unit Tests)
|
||||
> Schreibe Unit Tests für den Markdown Parser:
|
||||
> - erkennt mehrere Edge-Blocks pro Datei
|
||||
> - erkennt mehrere Targets pro Edge
|
||||
> - liefert line numbers
|
||||
> - ignoriert WikiLinks außerhalb der Semantic Mapping Callouts
|
||||
> Nutze vitest/jest. Erzeuge fixtures.
|
||||
|
||||
### Prompt C (Lint Engine + Quickfix)
|
||||
> Implementiere eine Lint Engine als Rule-Pipeline.
|
||||
> Jede Regel: id, severity, detect(node, graph) -> findings, fix(finding)->patch.
|
||||
> Baue eine Diff Preview Modal und applyPatch über Obsidian file API.
|
||||
> Implementiere zunächst 6 Regeln aus der Checkliste.
|
||||
|
||||
### Prompt D (Vocabulary Loader)
|
||||
> Implementiere einen VocabularyLoader:
|
||||
> - lädt entweder eingebettetes JSON oder eine Vault-Datei `edge_vocabulary.md`
|
||||
> - parst canonical types, aliases, inverse
|
||||
> - bietet getCanonical(raw) und getInverse(canonical)
|
||||
> Fallback auf builtin vocabulary wenn parsing fehlschlägt.
|
||||
@@ -0,0 +1,136 @@
|
||||
<!-- DOCUMENT 2: checklist_lint_regeln_mindnet_assistant.md -->
|
||||
---
|
||||
id: checklist_lint_regeln_mindnet_assistant
|
||||
title: Checkliste – Lint-Regeln für Mindnet Causal Assistant
|
||||
type: specification
|
||||
status: draft
|
||||
created: 2026-01-13
|
||||
lang: de
|
||||
---
|
||||
|
||||
# Checkliste – Lint-Regeln für Mindnet Causal Assistant
|
||||
|
||||
## Severity Levels
|
||||
- **ERROR**: bricht Traversal/Indexer oder erzeugt falsche Nodes
|
||||
- **WARN**: wahrscheinlich falsche Semantik / schlechter Retrieval-Impact
|
||||
- **INFO**: Optimierung / Empfehlung
|
||||
|
||||
---
|
||||
|
||||
## A. Graph-Integrität & Naming
|
||||
|
||||
### L1 (ERROR) Missing Target Note
|
||||
**Wenn:** Edge target `[[X]]` existiert nicht als Datei im Vault
|
||||
**Dann:** Finding `missing_target`
|
||||
**Fix:** „Create Stub Note“ (default `type: open_question`) oder remove edge
|
||||
|
||||
### L2 (ERROR) Node Splitting durch Schreibvarianten
|
||||
**Wenn:** mehrere Targets im Vault sind ähnlich (slug distance), oder in Edges mehrere Varianten vorkommen
|
||||
**Dann:** Finding `node_split_candidate`
|
||||
**Fix:** Vorschlag canonical slug + bulk replace links
|
||||
|
||||
### L3 (ERROR) Invalid Filename Policy
|
||||
**Wenn:** Dateiname enthält Zeichen außerhalb `[a-z0-9_]`
|
||||
**Dann:** Finding `invalid_filename`
|
||||
**Fix:** Rename file + update all backlinks
|
||||
|
||||
---
|
||||
|
||||
## B. Edge-Formale Regeln
|
||||
|
||||
### L4 (ERROR) Unknown Edge Type / Unmapped Alias
|
||||
**Wenn:** raw edge type nicht im Vokabular (alias→canonical)
|
||||
**Dann:** Finding `unknown_edge_type`
|
||||
**Fix:** Edge type ersetzen durch best guess oder user selection
|
||||
|
||||
### L5 (WARN) Alias not normalized
|
||||
**Wenn:** raw edge type ist Alias, canonical bekannt, aber Note enthält Alias
|
||||
**Dann:** Finding `alias_not_normalized`
|
||||
**Fix:** Replace raw with canonical (optional config)
|
||||
|
||||
### L6 (WARN) Missing Inverse Edge (optional strict mode)
|
||||
**Wenn:** Edge A->B existiert, inverse nach Vokabular fehlt in B
|
||||
**Dann:** Finding `missing_inverse`
|
||||
**Fix:** Add inverse edge to target note (review + diff)
|
||||
|
||||
---
|
||||
|
||||
## C. Semantik: Kausalität vs Chronologie
|
||||
|
||||
### L7 (WARN) Chronology used as Causality
|
||||
**Wenn:** Knoten/Target wirkt wie Prozessschritt („warten“, „gehen“, „ankommen“) und Edge type ist `resulted_in`
|
||||
**Dann:** Finding `chronology_as_causality`
|
||||
**Fix:** Vorschlag `followed_by` (inverse `preceeded_by`)
|
||||
|
||||
### L8 (INFO) Kausalität ohne Brücken (Gap)
|
||||
**Wenn:** Pfad springt von Ereignis direkt zu Entscheidung, aber intermediäre Knoten fehlen (heuristisch)
|
||||
**Dann:** Finding `missing_bridge_node`
|
||||
**Fix:** Vorschlag „Create open_question bridge“ (z.B. „Was war der konkrete Auslöser…?“)
|
||||
|
||||
---
|
||||
|
||||
## D. Node-Type Regeln
|
||||
|
||||
### L9 (ERROR) Causal edges from open_question/hypothesis/white_spot
|
||||
**Wenn:** node.type in `{open_question, hypothesis, white_spot}` und Edge type in `{caused_by, resulted_in, impacts, derived_from}`
|
||||
**Dann:** Finding `invalid_causal_edge_from_uncertain`
|
||||
**Fix:** Replace with `related_to` oder remove edge
|
||||
|
||||
### L10 (WARN) Hub/Insight Note trägt Kausalität
|
||||
**Wenn:** node.type == `insight` (oder Hub-Pattern) und hat `caused_by/resulted_in`
|
||||
**Dann:** Finding `hub_has_causality`
|
||||
**Fix:** Replace edges with `related_to` und verschiebe Kausalität in atomare Notes
|
||||
|
||||
### L11 (WARN) Principle uses caused_by for origin
|
||||
**Wenn:** node.type == `principle` und enthält `caused_by` zu Erlebnissen
|
||||
**Dann:** Finding `principle_origin_edge`
|
||||
**Fix:** Vorschlag `derived_from` oder `based_on`
|
||||
|
||||
### L12 (INFO) Decision without caused_by
|
||||
**Wenn:** node.type == `decision` und hat keine `caused_by`-Kanten
|
||||
**Dann:** Finding `decision_without_causes`
|
||||
**Fix:** Wizard: „Was war der Auslöser?“ → create open_question or add edges
|
||||
|
||||
---
|
||||
|
||||
## E. Redundanz & Zyklen
|
||||
|
||||
### L13 (WARN) Duplicate Edges
|
||||
**Wenn:** identische canonical edge mehrfach gesetzt (src,type,dst)
|
||||
**Dann:** Finding `duplicate_edge`
|
||||
**Fix:** remove duplicates
|
||||
|
||||
### L14 (WARN) Cycles in pure causality subgraph
|
||||
**Wenn:** Zyklus ausschließlich über `{caused_by,resulted_in,derived_from,source_of}`
|
||||
**Dann:** Finding `causal_cycle`
|
||||
**Fix:** Markiere zur Review; oft ist eine Kante falsch gerichtet
|
||||
|
||||
---
|
||||
|
||||
## F. Traversal-Optimierung (Retrieval-Wirkung)
|
||||
|
||||
### L15 (INFO) Overuse of related_to
|
||||
**Wenn:** Note enthält nur `related_to` und keine spezifischeren Kanten
|
||||
**Dann:** Finding `weak_semantics`
|
||||
**Fix:** Vorschlag: präzisere Beziehungstypen setzen
|
||||
|
||||
### L16 (INFO) Missing type metadata
|
||||
**Wenn:** Frontmatter `type` fehlt
|
||||
**Dann:** Finding `missing_type`
|
||||
**Fix:** Prompt user to choose type; set via template
|
||||
|
||||
### L17 (INFO) Missing date on experience
|
||||
**Wenn:** node.type == `experience` und kein Datum/Zeitraum vorhanden
|
||||
**Dann:** Finding `missing_date_experience`
|
||||
**Fix:** Prompt: „Wann ungefähr?“ → set `date` oder `time_range`
|
||||
|
||||
---
|
||||
|
||||
## Suggested Implementation Notes
|
||||
- Jede Regel liefert:
|
||||
- `ruleId`, `severity`, `message`, `location`, `evidence`, `quickFixes[]`
|
||||
- QuickFixes sind Patch-Operationen:
|
||||
- replaceText(range, text)
|
||||
- insertBlock(atLine, block)
|
||||
- createFile(path, content)
|
||||
- renameFile(old, new) + updateLinks(glob)
|
||||
Reference in new issue
Block a user