davide
1771936ab9
Include una sezione dedicata al flusso di import degli output MinerU (cosa tenere/scartare, come strutturare raw/sources).
59 lines
3.8 KiB
Markdown
59 lines
3.8 KiB
Markdown
# Ingegneria Meccanica — Wiki
|
|
|
|
Vault Obsidian gestito con il pattern **llm-wiki**: i documenti grezzi vanno in `raw/`, un agente (Claude Code o Codex) li legge e costruisce/aggiorna le pagine in `wiki/`. Le regole operative per l'agente sono in [CLAUDE.md](./CLAUDE.md) (e [AGENTS.md](./AGENTS.md) per Codex); questo README è la guida rapida per l'umano che aggiunge materiale.
|
|
|
|
## Struttura
|
|
|
|
```
|
|
purpose.md # ambito e domande guida del progetto
|
|
schema.md # convenzioni delle pagine wiki (tipi, frontmatter, naming)
|
|
raw/
|
|
├── sources/ # un documento = una sottocartella
|
|
└── assets/ # immagini/scan sciolte, non legate a un documento
|
|
wiki/
|
|
├── entities/ # componenti, materiali, norme, produttori
|
|
├── concepts/ # fenomeni, metodi di calcolo, teorie
|
|
├── sources/ # una pagina di sintesi per ogni documento in raw/sources
|
|
├── queries/ # domande aperte
|
|
├── comparisons/ # confronti tra entità/concetti
|
|
├── synthesis/ # sintesi trasversali
|
|
├── index.md # indice di tutte le pagine
|
|
├── log.md # log cronologico delle sessioni di ingest
|
|
└── overview.md # stato attuale del progetto (aggiornato a checkpoint, non ad ogni ingest)
|
|
```
|
|
|
|
## Come caricare un nuovo documento
|
|
|
|
1. Crea una cartella in `raw/sources/` con uno slug kebab-case che identifica il documento (es. `iso-6336-gear-rating`, `catalogo-skf-cuscinetti-2024` — non serve rispecchiare il nome del file originale).
|
|
2. Mettici dentro il documento (PDF, markdown, testo — quello che hai).
|
|
3. Se hai solo immagini sciolte non legate a un documento specifico (foto, schemi disegnati a mano), vanno in `raw/assets/`, non in `raw/sources/`.
|
|
4. Apri il progetto con Claude Code o Codex e chiedi di fare l'ingest del nuovo documento (es. "ingerisci il documento in raw/sources/iso-6336-gear-rating"). L'agente crea/aggiorna le pagine in `wiki/` seguendo `schema.md`.
|
|
|
|
Non modificare mai un file dentro `raw/` dopo averlo caricato: è la fonte immutabile. Se un dato risulta sbagliato, la correzione va fatta nella pagina wiki, non nel raw.
|
|
|
|
## Documenti processati con MinerU
|
|
|
|
Se un PDF è stato passato attraverso **MinerU** (in particolare la modalità **pipeline**, non VLM), l'output è una cartella con molti file — solo una parte va copiata in `raw/sources/<slug>/`:
|
|
|
|
**Tieni:**
|
|
- `<nome>.md` — il testo
|
|
- `<nome>_content_list.json` (uno solo tra questo e la `_v2`) — blocchi con numero di pagina, utile per citare le fonti
|
|
- `images/` — l'intera cartella, così com'è: il `.md` la referenzia con path relativi (`images/<hash>.jpg`)
|
|
- `<nome>_origin.pdf` — facoltativo, tienilo solo se vuoi poter riaprire il PDF originale per verificare a occhio formule/tabelle dubbie (spesso pesa decine di MB)
|
|
|
|
**Scarta** (file di debug interni a MinerU, senza valore per la wiki, spesso centinaia di MB in totale):
|
|
- `_layout.pdf`, `_span.pdf`
|
|
- `_middle.json`
|
|
- `_model.json`
|
|
|
|
**Passaggi pratici:**
|
|
1. Crea `raw/sources/<slug-kebab-case>/`
|
|
2. Copia dentro solo i file "da tenere" sopra, eliminando l'eventuale cartella intermedia `auto/`
|
|
3. Puoi rinominare liberamente la cartella-slug; **non serve e non conviene** rinominare i file interni o `images/` — i riferimenti sono path relativi e restano validi finché la struttura interna non cambia
|
|
|
|
L'estrazione in modalità pipeline può contenere errori (ordine di lettura su layout multi-colonna, formule OCR imprecise, tabelle disallineate): l'agente ne è a conoscenza (vedi CLAUDE.md) e segnala i punti dubbi invece di darli per certi, ma vale la pena tenere sotto mano il PDF originale per i casi più critici.
|
|
|
|
## Dettagli
|
|
|
|
Per le convenzioni di frontmatter/naming delle pagine vedi [schema.md](./schema.md); per l'ambito del progetto vedi [purpose.md](./purpose.md); per il workflow completo dell'agente vedi [CLAUDE.md](./CLAUDE.md).
|