Lars
a9b3e2f0e2
- 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.
279 lines
11 KiB
Markdown
279 lines
11 KiB
Markdown
# Chain Workbench - Analyse-Basis und Erweiterungen
|
|
|
|
> **Version:** 0.5.x
|
|
> **Stand:** 2025-01-XX
|
|
> **Zielgruppe:** Entwickler, Architekten
|
|
|
|
---
|
|
|
|
## Übersicht
|
|
|
|
Die Chain Workbench (0.5.x) basiert **hauptsächlich** auf den Analysen aus Chain Inspector (0.4.x), erweitert diese aber um zusätzliche Heuristiken und granularere Todo-Generierung.
|
|
|
|
---
|
|
|
|
## Basis: Chain Inspector 0.4.x Analysen
|
|
|
|
### Template Matching (0.4.x)
|
|
|
|
Die Workbench nutzt direkt die **Template Matches** aus Chain Inspector:
|
|
|
|
- **`TemplateMatch` Interface:**
|
|
- `templateName`: Name des Templates
|
|
- `score`: Match-Score (+10 pro Link, +2 pro Slot, -5 pro fehlendem required Link)
|
|
- `slotAssignments`: Map von Slot-ID → Node-Referenz
|
|
- `missingSlots`: Array von fehlenden Slot-IDs
|
|
- `satisfiedLinks`: Anzahl erfüllter Links
|
|
- `requiredLinks`: Anzahl erforderlicher Links
|
|
- `roleEvidence`: Array von Edge-Role-Evidence
|
|
- `slotsComplete`: Boolean
|
|
- `linksComplete`: Boolean
|
|
- `confidence`: "confirmed" | "plausible" | "weak"
|
|
|
|
**Quelle:** `src/analysis/chainInspector.ts` → `inspectChains()` → `matchTemplates()`
|
|
|
|
### Findings aus 0.4.x (aktuell NICHT verwendet, aber sollten integriert werden)
|
|
|
|
**Status:** Die Findings aus Chain Inspector werden aktuell **nicht** in der Workbench verwendet, obwohl sie aufwendig getestet wurden und wertvolle Informationen liefern.
|
|
|
|
**Findings aus 0.4.x:**
|
|
- `missing_edges` - Section hat Content aber keine Edges
|
|
- `one_sided_connectivity` - Nur incoming oder nur outgoing edges
|
|
- `only_candidates` - Nur Candidate-Edges, keine expliziten
|
|
- `dangling_target` - Target-Datei existiert nicht
|
|
- `dangling_target_heading` - Target-Heading existiert nicht
|
|
- `no_causal_roles` - Section hat Edges aber keine kausalen Rollen
|
|
- `missing_slot_<slotId>` - Template-basiert: Slot fehlt (aggregiert)
|
|
- `missing_link_constraints` - Template-basiert: Links fehlen (aggregiert)
|
|
- `weak_chain_roles` - Template-basiert: Nur non-causal Rollen (aggregiert)
|
|
|
|
**Warum aktuell nicht verwendet?**
|
|
- Die Workbench fokussiert sich aktuell nur auf **Template-basierte Todos**
|
|
- Findings sind teilweise **aggregiert** (z.B. "missing_slot_trigger" für alle Matches)
|
|
- Workbench benötigt **granulare Todos** pro Match (z.B. "missing_slot_trigger" für jeden Match einzeln)
|
|
- Workbench benötigt **konkrete Actions** (z.B. `insert_edge_forward`, `create_note_via_interview`)
|
|
|
|
**Sollten integriert werden:**
|
|
Die Findings könnten als **zusätzliche Todos** integriert werden:
|
|
- `dangling_target` → Todo mit Action `create_missing_note` oder `retarget_link`
|
|
- `dangling_target_heading` → Todo mit Action `create_missing_heading` oder `retarget_to_existing_heading`
|
|
- `only_candidates` → Todo mit Action `promote_all_candidates` oder `create_explicit_edges`
|
|
- `missing_edges` → Todo mit Action `add_edges_to_section`
|
|
- `no_causal_roles` → Todo ähnlich wie `weak_roles`, aber section-weit (nicht template-basiert)
|
|
- `one_sided_connectivity` → Informatives Todo (keine Action, nur Hinweis)
|
|
|
|
**Vorteil der Integration:**
|
|
- Nutzung der **getesteten Heuristiken** aus 0.4.x
|
|
- **Vollständigere Analyse** (nicht nur Template-basiert)
|
|
- **Konsistenz** zwischen Chain Inspector und Workbench
|
|
|
|
---
|
|
|
|
## Neue Analysen in 0.5.x
|
|
|
|
### 1. Status-Berechnung (`statusCalculator.ts`)
|
|
|
|
**Neu in 0.5.x:** Berechnet `MatchStatus` basierend auf Slot/Link-Erfüllung:
|
|
|
|
- **`complete`**: `slotsFilled == slotsTotal && linksSatisfied == linksRequired`
|
|
- **`near_complete`**:
|
|
- `slotsFilled == slotsTotal && (linksRequired - linksSatisfied) in {1,2}`
|
|
- ODER `(slotsTotal - slotsFilled) == 1 && linksSatisfied == linksRequired`
|
|
- **`weak`**: Match vorhanden, aber nur structural/temporal Rollen (keine causal)
|
|
- **`partial`**: Sonstige Fälle mit mindestens einer Lücke
|
|
|
|
**Basis:** TemplateMatch aus 0.4.x, aber **neue Heuristik** für Status-Kategorisierung.
|
|
|
|
### 2. Granulare Todo-Generierung (`todoGenerator.ts`)
|
|
|
|
**Neu in 0.5.x:** Generiert konkrete Todos pro Match:
|
|
|
|
#### `missing_slot` Todo
|
|
- **Basis:** `match.missingSlots` aus TemplateMatch
|
|
- **Erweiterung:**
|
|
- Pro Slot ein Todo (nicht aggregiert)
|
|
- Enthält `allowedNodeTypes` für Interview-Filterung
|
|
- Enthält Actions: `["link_existing", "create_note_via_interview"]`
|
|
|
|
#### `missing_link` Todo
|
|
- **Basis:** Template-Links aus `template.links` + `match.slotAssignments`
|
|
- **Erweiterung:**
|
|
- Prüft, ob beide Slots gefüllt sind, aber Link fehlt
|
|
- Enthält `fromNodeRef` und `toNodeRef` (konkrete Referenzen)
|
|
- Enthält `suggestedEdgeTypes` aus `chain_roles.yaml`
|
|
- Enthält Actions: `["insert_edge_forward", "insert_edge_inverse", "choose_target_anchor"]`
|
|
|
|
#### `weak_roles` Todo
|
|
- **Basis:** `match.roleEvidence` aus TemplateMatch
|
|
- **Erweiterung:**
|
|
- Prüft, ob alle Rollen structural/temporal sind (keine causal)
|
|
- Enthält Liste von `edges` mit `currentRole` und `suggestedRoles`
|
|
- Enthält Actions: `["change_edge_type"]`
|
|
|
|
#### `candidate_cleanup` Todo (NEU)
|
|
- **Basis:** Candidate-Edges aus `graphIndex` + `missing_link` Todos
|
|
- **Vollständig neu:**
|
|
- Findet Candidate-Edges, die zu `missing_link` Requirements passen
|
|
- **Relation-Equality-Check:** Prüft, ob bereits ein confirmed Edge für dieselbe Relation existiert
|
|
- Wenn ja → kein Todo (verhindert Duplikate)
|
|
- Wenn nein → Todo mit `promote_candidate` Action
|
|
|
|
**Relation-Equality-Logik:**
|
|
```typescript
|
|
// Prüft:
|
|
// 1. Direction match (from → to)
|
|
// 2. Node-Refs match (file + heading)
|
|
// 3. Canonical Edge-Type match (via edge_vocabulary.md)
|
|
```
|
|
|
|
### 3. Effective Required Links Resolution
|
|
|
|
**Neu in 0.5.x:** Resolved `required_links` Flag mit Priorität:
|
|
|
|
1. `template.matching?.required_links` (höchste Priorität)
|
|
2. `profile.required_links`
|
|
3. `defaults.matching?.required_links`
|
|
4. Fallback: `false`
|
|
|
|
**Basis:** TemplateMatch nutzt bereits `requiredLinks`, aber Workbench benötigt explizite Resolution für UI-Darstellung.
|
|
|
|
---
|
|
|
|
## Vergleich: Findings vs. Todos
|
|
|
|
| Aspekt | Chain Inspector 0.4.x (Findings) | Chain Workbench 0.5.x (Todos) |
|
|
|--------|----------------------------------|-------------------------------|
|
|
| **Granularität** | Aggregiert (pro Template-Typ) | Granular (pro Match, pro Slot/Link) |
|
|
| **Format** | `Finding` Interface (code, severity, message) | `WorkbenchTodoUnion` Interface (type, actions, refs) |
|
|
| **Actions** | Keine (nur Informativ) | Konkrete Actions (`insert_edge_forward`, etc.) |
|
|
| **Basis** | Template Matches + Gap-Heuristiken | Template Matches + zusätzliche Analysen |
|
|
| **Verwendung** | Console-Output, Fix Findings Command | Workbench UI, interaktive Bearbeitung |
|
|
|
|
---
|
|
|
|
## Abhängigkeiten
|
|
|
|
### Direkte Abhängigkeiten (0.4.x)
|
|
|
|
1. **`TemplateMatch`** aus `chainInspector.ts`
|
|
- Wird direkt verwendet für Status-Berechnung und Todo-Generierung
|
|
|
|
2. **`ChainTemplatesConfig`** aus `dictionary/types.ts`
|
|
- Wird verwendet für Slot/Link-Definitionen und `allowed_node_types`
|
|
|
|
3. **`ChainRolesConfig`** aus `dictionary/types.ts`
|
|
- Wird verwendet für `suggestedEdgeTypes` in `missing_link` Todos
|
|
|
|
4. **`EdgeVocabulary`** aus `vocab/types.ts`
|
|
- Wird verwendet für Canonical-Type-Resolution (Relation-Equality)
|
|
|
|
5. **`IndexedEdge[]`** aus `graphIndex.ts`
|
|
- Wird verwendet für Candidate/Confirmed-Edge-Trennung
|
|
|
|
### Indirekte Abhängigkeiten
|
|
|
|
1. **Template Matching Algorithmus** (0.4.x)
|
|
- Backtracking-Algorithmus für Slot-Assignment
|
|
- Scoring-Mechanismus (+10 pro Link, +2 pro Slot, -5 pro fehlendem required Link)
|
|
|
|
2. **Edge-Role-Mapping** (0.4.x)
|
|
- `chain_roles.yaml` → Edge-Types → Roles
|
|
- Wird verwendet für `weak_roles` Detection
|
|
|
|
---
|
|
|
|
## Neue Heuristiken (nicht in 0.4.x)
|
|
|
|
### 1. Relation-Equality-Check
|
|
|
|
**Zweck:** Verhindert Duplikate bei Candidate-Cleanup.
|
|
|
|
**Logik:**
|
|
- Prüft, ob bereits ein confirmed Edge für dieselbe Relation existiert
|
|
- Relation = (fromNodeRef, toNodeRef, canonicalEdgeType)
|
|
- Wenn ja → kein `candidate_cleanup` Todo
|
|
|
|
**Implementierung:** `todoGenerator.ts` → `checkRelationExists()`
|
|
|
|
### 2. Status-Kategorisierung
|
|
|
|
**Zweck:** Priorisierung von Matches in Workbench UI.
|
|
|
|
**Logik:**
|
|
- `complete` → höchste Priorität (grün)
|
|
- `near_complete` → hohe Priorität (gelb)
|
|
- `partial` → mittlere Priorität (orange)
|
|
- `weak` → niedrige Priorität (rot)
|
|
|
|
**Implementierung:** `statusCalculator.ts` → `calculateMatchStatus()`
|
|
|
|
### 3. Effective Required Links Resolution
|
|
|
|
**Zweck:** Korrekte Darstellung von Link-Requirements in UI.
|
|
|
|
**Logik:**
|
|
- Resolved `required_links` Flag mit Priorität (template > profile > defaults)
|
|
- Beeinflusst, ob `missing_link` Todos generiert werden
|
|
|
|
**Implementierung:** `statusCalculator.ts` → `getEffectiveRequiredLinks()`
|
|
|
|
---
|
|
|
|
## Zusammenfassung
|
|
|
|
### Basierend auf 0.4.x
|
|
|
|
✅ **Template Matches** - Direkt verwendet
|
|
✅ **Slot-Assignments** - Direkt verwendet
|
|
✅ **Missing Slots** - Direkt verwendet
|
|
✅ **Role Evidence** - Direkt verwendet
|
|
✅ **Edge-Role-Mapping** - Direkt verwendet
|
|
✅ **Canonical Edge Types** - Direkt verwendet
|
|
|
|
### Neu in 0.5.x
|
|
|
|
🆕 **Status-Berechnung** - Neue Heuristik
|
|
🆕 **Granulare Todos** - Pro Match, pro Slot/Link
|
|
🆕 **Candidate-Cleanup** - Relation-Equality-Check
|
|
🆕 **Effective Required Links** - Prioritäts-Resolution
|
|
🆕 **Action-System** - Konkrete Actions pro Todo
|
|
|
|
### Nicht verwendet aus 0.4.x (sollten integriert werden)
|
|
|
|
⚠️ **Findings** - Werden aktuell nicht verwendet, sollten aber integriert werden
|
|
⚠️ **Gap-Heuristiken** - Werden aktuell nicht verwendet, sollten aber integriert werden
|
|
⚠️ **Dangling Target Checks** - Werden aktuell nicht verwendet, sollten aber integriert werden
|
|
|
|
**Empfehlung:** Die Findings sollten als **zusätzliche Todos** in die Workbench integriert werden, um die getesteten Heuristiken zu nutzen und eine vollständigere Analyse zu bieten.
|
|
|
|
---
|
|
|
|
## Fazit
|
|
|
|
Die Chain Workbench (0.5.x) basiert **hauptsächlich** auf den Template Matches aus Chain Inspector (0.4.x), erweitert diese aber um:
|
|
|
|
1. **Granulare Todo-Generierung** (pro Match, pro Slot/Link)
|
|
2. **Status-Kategorisierung** (complete, near_complete, partial, weak)
|
|
3. **Candidate-Cleanup-Heuristik** (Relation-Equality-Check)
|
|
4. **Action-System** (konkrete Actions pro Todo)
|
|
|
|
**Aktueller Stand:**
|
|
Die Workbench verwendet aktuell **nur** die Template Matches aus 0.4.x, nicht die Findings. Dies ermöglicht eine **interaktive Bearbeitung** mit konkreten Actions.
|
|
|
|
**Empfohlene Erweiterung:**
|
|
Die Findings aus 0.4.x sollten als **zusätzliche Todos** integriert werden, um:
|
|
- Die **getesteten Heuristiken** zu nutzen
|
|
- Eine **vollständigere Analyse** zu bieten (nicht nur Template-basiert)
|
|
- **Konsistenz** zwischen Chain Inspector und Workbench zu gewährleisten
|
|
|
|
**Nächste Schritte:**
|
|
1. Findings aus `report.findings` in `buildWorkbenchModel` einlesen
|
|
2. Findings zu Todos konvertieren (mit entsprechenden Actions)
|
|
3. Findings-Todos zu den Template-basierten Todos hinzufügen
|
|
4. UI erweitern, um beide Todo-Typen anzuzeigen
|
|
|
|
---
|
|
|
|
**Letzte Aktualisierung:** 2025-01-XX
|
|
**Version:** 0.5.x
|