v2.0.1: CI-Workflow + README mit Architektur-Diagramm
- .gitea/workflows/ci.yml: gitea-Actions-Workflow - Job 1 (test): npm ci + build + test auf Node 22 - Job 2 (webapp): webapp-Build + Artifact-Verifikation - Trigger: push + pull_request auf main - README.md komplett neu strukturiert: - Architektur-Diagramm (ASCII) mit allen 5 Bausteinen - 5-Bausteine-Tabelle mit Spalte 'Wo' (Tool/Vault/QMD) - Installations-Anleitung (Tool, Vault, QMD, Webapp) - Beispiel-Session end-to-end - Erweiterte CLI-Referenz mit allen Optionen - Test-Anleitung
This commit is contained in:
1 parent
f1244f615f
commit
e6356f8fac
2 files changed
+203
-42
No files matched your search
@@ -0,0 +1,51 @@
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '22'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Build
|
||||
run: npm run build
|
||||
|
||||
- name: Tests
|
||||
run: npm test
|
||||
|
||||
webapp:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '22'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install webapp dependencies
|
||||
run: |
|
||||
cd webapp
|
||||
npm ci
|
||||
npm run build
|
||||
|
||||
- name: Verify artifacts
|
||||
run: |
|
||||
test -f webapp/dist/index.html
|
||||
test -f webapp/dist/manifest.webmanifest
|
||||
echo "Webapp build artifacts present"
|
||||
@@ -5,73 +5,183 @@ Lokales Second-Brain-System für Obsidian-kompatible Markdown-Vaults. Besteht au
|
||||
- **Dieses Repo** (`Mind-o-Mat`) — die Code-Basis (Tool). Wird gebaut und über npm publiziert.
|
||||
- **Vault-Repo** (z. B. `Mind-o-Mat-Vault`) — die Notizen. Wird mit dem Tool initialisiert und via gitea synchronisiert.
|
||||
|
||||
> **Status:** Phase 1a in Arbeit. CLI-Skelett + Vault-Pfad-Discovery implementiert, andere Befehle sind Stubs. Siehe `10 Wiki/Plan.md` für den vollständigen Plan.
|
||||
> **Status:** v2.0 — alle 5 Phasen komplett. 50/50 Tests grün. Webapp-Build 1.05 MB. PWA-Editor + TWA-Konfig vorhanden. Siehe `10_Wiki/SPEC.md` für Details.
|
||||
|
||||
## Installation (Vault-User)
|
||||
## Architektur
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Mind-o-Mat (Tool) │
|
||||
│ C:\GitHub\Mind-o-Mat (dieses Repo) │
|
||||
│ │
|
||||
│ ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
|
||||
│ │ CLI │ │ Indexer │ │ Ingest │ │ Webapp │ │
|
||||
│ │ init- │ │ scan + │ │ LLM + │ │ React + │ │
|
||||
│ │ vault, │ │ parse │ │ Konfl. │ │ Cytosc. │ │
|
||||
│ │ index, │ │ + Veral.│ │ + Vera. │ │ + Tiptap │ │
|
||||
│ │ ingest, │ │ + Dupl. │ │ + Jacc. │ │ + PWA │ │
|
||||
│ │ sync │ │ │ │ │ │ Manifest │ │
|
||||
│ └─────┬─────┘ └─────┬────┘ └────┬─────┘ └──────┬─────┘ │
|
||||
│ │ │ │ │ │
|
||||
└────────┼──────────────┼───────────┼──────────────┼─────────┘
|
||||
│ │ │ │
|
||||
│ ▼ │ ▼
|
||||
│ landkarte.json │ Browser / PWA
|
||||
│ │ │ │
|
||||
│ └─────┬─────┘ │
|
||||
│ ▼ │
|
||||
│ 00_Inbox/*.md │
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Mind-o-Mat-Vault (Daten) │
|
||||
│ C:\GitHub\Mind-o-Mat-Vault (Repo) │
|
||||
│ gitea: git.orfel.de/Jannik/Mind-o-Mat-Vault.git │
|
||||
│ │
|
||||
│ 00_Inbox/ 01_Daily/ 10_Wiki/ 20_Projekte/ ... │
|
||||
│ 99_System/Konfig.md (Schwellen, KI-Config) │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼ git push
|
||||
┌────────────┐
|
||||
│ gitea │
|
||||
│ Remote │
|
||||
└────────────┘
|
||||
```
|
||||
|
||||
## 5 Bausteine
|
||||
|
||||
| # | Baustein | Zweck | KI drin? | Wo |
|
||||
|---|---|---|---|---|
|
||||
| 1 | **Vault** | Markdown-Dateien, Single Source of Truth | nein | Vault-Repo |
|
||||
| 2 | **Indexer** | Deterministisch: liest Vault, parst Frontmatter, extrahiert Wikilinks, erkennt Veraltet + Duplikate | nein | Tool-Repo |
|
||||
| 3 | **QMD** | Lokale Hybridsuche (BM25 + Vektor + Re-Ranking) | nein (lokal) | im Vault installiert |
|
||||
| 4 | **Wiki** (Ingest) | Pflegt Wiki-Seiten via LLM, deterministische Konflikt-Vorprüfung | ja (Minimax-API) | Tool-Repo |
|
||||
| 5 | **Webapp / PWA** | 3 Tabs (Graph, Cluster-Karte, Radial), Tiptap-Editor, installierbar auf Android | nein | Tool-Repo |
|
||||
|
||||
## Installation
|
||||
|
||||
### Tool global installieren
|
||||
|
||||
```bash
|
||||
# Tool global installieren (einmalig)
|
||||
npm install -g mindomat
|
||||
# Aus dem Repo (lokal):
|
||||
cd C:\GitHub\Mind-o-Mat
|
||||
npm install
|
||||
npm run build
|
||||
npm link # macht 'mindomat' global verfügbar
|
||||
|
||||
# Vault initialisieren
|
||||
mindomat init-vault C:\Pfad\Zu\Mein-Vault
|
||||
cd C:\Pfad\Zu\Mein-Vault
|
||||
# Später (sobald auf npm):
|
||||
# npm install -g mindomat
|
||||
```
|
||||
|
||||
### Vault initialisieren
|
||||
|
||||
```bash
|
||||
# Erstellt komplette Vault-Struktur (12 Ordner + Konfig + 2 Demo-Notizen + git init)
|
||||
mindomat init-vault C:\GitHub\Mein-Vault
|
||||
|
||||
# Konfiguriere gitea-Remote
|
||||
cd C:\GitHub\Mein-Vault
|
||||
git remote add origin https://git.example.com/Dein-Name/Mein-Vault.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
# QMD installieren (einmalig, ~2 GB Modelle)
|
||||
### QMD einrichten (einmalig)
|
||||
|
||||
```bash
|
||||
# QMD installieren
|
||||
npm install -g @tobilu/qmd
|
||||
cd C:\Pfad\Zu\Mein-Vault
|
||||
|
||||
# Collections anlegen
|
||||
cd C:\GitHub\Mein-Vault
|
||||
qmd collection add 00_Inbox --name inbox
|
||||
qmd collection add 01_Daily --name daily
|
||||
qmd collection add 10_Wiki --name wiki
|
||||
qmd collection add 20_Projekte --name projekte
|
||||
qmd embed
|
||||
|
||||
# Vault indizieren (erzeugt landkarte.json)
|
||||
MINDOMAT_VAULT_PATH=C:\Pfad\Zu\Mein-Vault mindomat index
|
||||
# Embeddings generieren (~2 GB Download beim ersten Mal)
|
||||
qmd embed
|
||||
```
|
||||
|
||||
### Vault-Index erstellen
|
||||
|
||||
```bash
|
||||
# Erzeugt landkarte.json + 99_System/Index.md + 10_Wiki/Index.md
|
||||
mindomat index
|
||||
```
|
||||
|
||||
### PWA-Editor starten
|
||||
|
||||
```bash
|
||||
# Im Tool-Repo:
|
||||
cd C:\GitHub\Mind-o-Mat\webapp
|
||||
npm install
|
||||
npm run dev
|
||||
# Browser öffnet http://localhost:5173
|
||||
# Setze MINDOMAT_VAULT_PATH für die Notes-API
|
||||
$env:MINDOMAT_VAULT_PATH = "C:\GitHub\Mein-Vault"
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Beispiel-Session
|
||||
|
||||
```bash
|
||||
# 1. Notiz in Inbox anlegen
|
||||
notepad C:\GitHub\Mein-Vault\00_Inbox\2026-09-05_Telefonat_Max.md
|
||||
# Inhalt: "[[Kaffee]] schmeckt gut."
|
||||
# Speichern.
|
||||
|
||||
# 2. Ingest: Notiz -> Wiki
|
||||
mindomat ingest --vault C:\GitHub\Mein-Vault
|
||||
# Output: Wiki-Seite Kaffee.md wird erstellt (oder aktualisiert)
|
||||
|
||||
# 3. Index aktualisieren
|
||||
mindomat index
|
||||
# Output: landkarte.json mit neuem Knoten
|
||||
|
||||
# 4. Webapp: Graph ansehen
|
||||
cd C:\GitHub\Mind-o-Mat\webapp
|
||||
npm run dev
|
||||
# Browser: http://localhost:5173 zeigt Graph mit Notiz + Wikilinks
|
||||
|
||||
# 5. Sync zu gitea
|
||||
mindomat sync
|
||||
# Output: git push zu gitea, andere Geräte sehen die Änderung
|
||||
```
|
||||
|
||||
## CLI-Referenz
|
||||
|
||||
```bash
|
||||
mindomat --version # Version anzeigen
|
||||
mindomat --version # Version
|
||||
mindomat --help # Hilfe
|
||||
mindomat init-vault <pfad> # Vault-Struktur erstellen
|
||||
mindomat index --vault <pfad> # Vault indizieren
|
||||
mindomat ingest --vault <pfad> # Inbox-Notizen verarbeiten
|
||||
mindomat sync --vault <pfad> # gitea-Sync
|
||||
|
||||
mindomat init-vault <pfad> # Vault initialisieren
|
||||
# --remote <url> gitea-URL setzen
|
||||
# --no-commit nur Struktur, kein Git-Init
|
||||
# --no-interactive ohne Rückfragen
|
||||
# --force existierenden Vault überschreiben
|
||||
|
||||
mindomat index --vault <pfad> # Index erstellen (deterministisch)
|
||||
# oder MINDOMAT_VAULT_PATH setzen
|
||||
|
||||
mindomat ingest --vault <pfad> # Inbox -> Wiki
|
||||
# --mock ohne API-Key, simulierte LLM-Antwort
|
||||
# --note <pfad> nur eine bestimmte Notiz
|
||||
# --dry-run nicht schreiben
|
||||
|
||||
mindomat sync --vault <pfad> # git pull + push zu gitea
|
||||
# --message <msg> custom commit-message
|
||||
# --force Lockfile ignorieren
|
||||
```
|
||||
|
||||
Der Vault-Pfad wird in dieser Reihenfolge aufgelöst:
|
||||
|
||||
1. CLI-Argument `--vault <pfad>` (oder `-v <pfad>`)
|
||||
2. Environment-Variable `MINDOMAT_VAULT_PATH`
|
||||
3. Fehler: klare Meldung
|
||||
|
||||
## Entwicklung (Tool-Contributor)
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
git clone https://git.orfel.de/Jannik/Mind-o-Mat
|
||||
cd Mind-o-Mat
|
||||
npm install
|
||||
npm run build # TypeScript kompilieren
|
||||
npm test # Unit-Tests (Vitest)
|
||||
npm run test:watch # Tests im Watch-Mode
|
||||
npm test # 50 Unit-Tests (Vitest)
|
||||
npm run build # TypeScript kompilieren
|
||||
cd webapp && npm run build # Vite-Build
|
||||
```
|
||||
|
||||
## Architektur
|
||||
|
||||
Siehe `10 Wiki/SPEC.md` (Spezifikation) und `10 Wiki/Plan.md` (20 Aufgaben, 5 Phasen).
|
||||
|
||||
**5 Bausteine:**
|
||||
|
||||
1. **Vault** — Markdown-Dateien, Single Source of Truth (im Vault-Repo)
|
||||
2. **Indexer** — deterministisch, erzeugt `landkarte.json` (im Tool)
|
||||
3. **QMD** — lokale Hybridsuche, ~2 GB GGUF-Modelle (im Vault installiert)
|
||||
4. **Wiki** — Ingest pflegt Markdown-Seiten via Minimax-API
|
||||
5. **Webapp/PWA** — React + Cytoscape, Graph-Ansicht, Mobile-Editor
|
||||
|
||||
## Lizenz
|
||||
|
||||
MIT
|
||||
Reference in new issue
Block a user