To migrare la documentazione in Markdown, fornisci a un agente AI la cartella di archivio e fallo eseguire convert_to_markdown una volta per file, in batch revisionati. Con GroupDocs.Markdown.Mcp questo avviene localmente in Claude Code, Cursor, GitHub Copilot o un altro client MCP, quindi un archivio di procedure interne non viene mai caricato su un servizio di conversione:

Converti tutto nella cartella di archivio in Markdown con front matter e immagini come file. Riporta il formato di origine, il conteggio delle pagine e la dimensione dell’output per ciascuno.

La versione passo‑passo con configurazione e risoluzione dei problemi è nella documentazione: Come migrare la documentazione legacy in Markdown con AI.

Perché la migrazione di documentazione legacy è un compito per un agente?

La conversione è meccanica e il lavoro circostante è ripetitivo: elencare i file, convertire ciascuno, misurare il risultato, trovare i fallimenti, ripetere. Una persona che lo fa per centinaia di file prende la stessa decisione centinaia di volte. Un agente lo fa in modo coerente e riporta ogni risultato, mentre il motore, non il modello, produce il Markdown. Il Markdown salvato non è una parafrasi delle tue procedure.

Questo è un runbook. Ogni passo ha un prompt, e la tabella successiva separa ciò che decide l’agente da ciò che fa il motore.

Runbook: come migrare un archivio Word in Markdown?

  1. Verifica la licenza prima di qualsiasi altra cosa.

    Prima di convertire qualsiasi cosa: qual è lo stato della licenza del server markdown?

    get_license_status restituisce mode, licensed, consumption e le versioni del server e del motore. La modalità di valutazione elabora 3 pagine per documento, quindi un’esecuzione non licenziata produce bozze plausibili.

  2. Inventaria l’archivio.

    Elenca ogni file nella cartella di archivio con il suo formato, il conteggio delle pagine e se è criptato.

    Il server Markdown non ha uno strumento di elencazione delle cartelle, quindi l’agente elenca la cartella con l’accesso ai file del proprio client o lavora con i nomi dei file che gli fornisci.

    Poi get_document_info restituisce fileFormat, pageCount, title, author e isEncrypted per ogni file senza convertirlo. I file criptati necessitano del parametro password.

  3. Esegui un pilota di circa venti file.

    Converti i primi venti documenti in Markdown con front matter e immagini come file. Riporta formato, pagine e dimensione dell’output per ciascuno.

  4. Trova cosa non è stato convertito.

    Elenca i PDF la cui conversione ha prodotto meno di 2 KB di Markdown per più di 5 pagine.

    Questi sono quasi sempre scansioni. Non c’è alcun passaggio OCR in questo server, quindi hanno bisogno di un altro strumento o rimangono come PDF indicizzati dai metadati.

  5. Correggi il modello, poi esegui il resto in batch. Venti file per round, con un report ogni volta, mantengono l’esecuzione revisionabile e l’uso a consumo prevedibile.

  6. Rivedi l’output come faresti con una pull request. Le sezioni successive elencano cosa osservare.

Decisione Agente Motore
Quali file convertire, in quale ordine e dimensione del batch Sì No
Quali opzioni passare (images, frontMatter, flavor) Sì, dal tuo prompt No
Convertire intestazioni, elenchi e tabelle in Markdown No Sì
Salvare i file .md e le immagini No Sì
Rilevare un file di 300 pagine che è diventato 4 KB Sì, dal report No
Rinominare, layout delle cartelle, chiavi front‑matter extra Sì No

Quali formati migrano bene?

  • DOCX, DOC, RTF, ODT. La struttura è esplicita nella sorgente, quindi intestazioni e tabelle vengono trasferite in modo pulito.
  • EPUB e MOBI. La struttura dei capitoli si mappa su intestazioni Markdown.
  • CHM. Vecchi file di aiuto, spesso l’unica copia di una procedura.
  • XLSX. I fogli di lavoro diventano tabelle, il che è adatto per elenchi di parametri.

Cosa dovrebbe verificare il passaggio di revisione?

Chiedi all’agente di fare la prima scansione, poi leggi un campione tu stesso:

Per ogni file convertito, elenca le immagini a cui fa riferimento e dimmi quali file immagine mancano.

Mostrami i cinque output con la dimensione più piccola rispetto al loro conteggio di pagine.

Le immagini scritte con images: "file" si trovano accanto al .md e sono referenziate tramite percorso relativo, che è ciò che si aspetta un repository di documentazione. Un .md che punta a immagini mai scritte viene renderizzato come immagini rotte. Poi apri la sorgente più caotica e il suo output fianco a fianco prima di applicare il modello al resto. Effettua il commit del risultato revisionato con il tuo normale flusso di lavoro git; il server scrive i file e non tocca il tuo repository.

Sessione di esempio (abbreviata)

You:   Convert the first twenty documents in /archive to Markdown with front matter
       and images as files. Report format, pages and output size for each.
Agent: convert_to_markdown (frontMatter: true, images: "file") x 20
       ops-manual-2014.docx   DOCX   88 pages   converted
       install-guide.chm      CHM    41 pages   converted
       supplier-forms-2009.pdf PDF   12 pages   1 KB of Markdown: probably a scan
       Nineteen files look consistent; one scan needs separate handling.

Limiti onesti

Senza licenza, la modalità di valutazione elabora solo le prime 3 pagine di ogni documento, con una filigrana di valutazione su ciascuna. Un’esecuzione di migrazione in quello stato produce centinaia di file brevi che sembrano corretti, e la lacuna viene scoperta settimane dopo quando qualcuno cerca una procedura mancante. La migrazione richiede una licenza, quindi esegui get_license_status prima del primo batch. I PDF scansionati non si convertono.

FAQ

Posso convertire centinaia di documenti Word in Markdown contemporaneamente?

Sì, ma non in un unico prompt. Converti in batch di circa venti e leggi il report dopo ciascuno, così un’opzione errata viene corretta prima di essere applicata all’intero archivio.

Come migrare la documentazione in git con un agente AI?

Il server scrive file .md e file immagine nella cartella di output. Li rivedi e li committi con il tuo consueto flusso di lavoro git.

La migrazione docs-as-code carica i miei documenti?

No. GroupDocs.Markdown.Mcp è un processo locale, e l’archivio viene letto dal disco. Solo ciò che l’agente scrive nella conversazione raggiunge il provider del modello.

Approfondisci