WolfMarkTools/WolfMarkDown

Que fait WolfMarkDown ?

Un flux de travail de publication d'agent pour transformer les sorties d'IA désordonnées en Markdown professionnel, prêt à être révisé et conservé.

Jugement de l'agent pour la structure. Outils déterministes pour la preuve.

Les agents IA peuvent produire des recherches, des plans et de la documentation utiles tout en laissant derrière eux des comparaisons aplaties, des titres incohérents, des échafaudages de chat copiés, des blocs de code cassés et des identifiants techniques altérés.

WolfMarkDown offre à l'agent un flux de travail de publication discipliné :

• l'agent décide du sens, de la structure, de l'assainissement et de la composition ;
• les outils déterministes formatent et valident le Markdown résultant ;
• le contenu protégé, la restauration et les limites de publication sont vérifiés avant que le résultat ne soit conservé.

Le résultat n'est pas un moteur de réparation Markdown magique. C'est un flux de travail d'agent avec une preuve déterministe autour de l'artefact.

Pourquoi WolfMarkDown existe

Prettier est un excellent outil de formatage Markdown. Il ne peut pas décider si un bloc aplati contient un tableau de comparaison, si une phrase courte est un titre, ou si un message d'agent copié appartient au document.

WolfMarkDown rend ces décisions explicites et conservatrices. Il répare les structures claires, préserve le matériel véritablement ambigu et signale ce qui a été récupéré. Il ne vérifie pas les faits de la source et n'approuve pas la publication.

Capacité	Prettier seul	WolfMarkDown
Formatage Markdown déterministe	Oui	Oui
Réparation de la structure sémantique du document	Non	Oui
Suppression des échafaudages de conversation IA copiés	Non	Oui
Reconstruction des tableaux de comparaison malformés	Non	Oui
Protection des URLs, code, hachages, versions et identifiants	Non	Oui
Vérification du parsing GFM et de l'équilibre des blocs de code	Non	Oui
Exécution de markdownlint avant publication	Non	Oui
Vérification de l'idempotence	Non	Oui
Restauration de l'original après un échec de Clean	Non	Oui
Refus de publier un Compose échoué	Non	Oui

WolfMarkDown ne réécrit pas un texte déjà correct pour le faire sonner différemment. L'objectif est le nettoyage sémantique minimum nécessaire avec une preuve déterministe que le résultat peut être conservé en toute sécurité.

Installation

npx skills add WolfMarkTools/WolfMarkDown --skill wolfmarkdown

Le CLI skills installe la compétence canonique wolfmarkdown/ pour l'hôte compatible Agent Skills sélectionné. Un checkout du dépôt peut également exécuter :

npm ci --prefix wolfmarkdown
node wolfmarkdown/scripts/install.mjs

Pour une installation non interactive de Claude Code :

npx skills add WolfMarkTools/WolfMarkDown \
  --skill wolfmarkdown \
  -g \
  -a claude-code \
  -y

L'installateur répare les dépendances d'exécution uniquement si nécessaire, configure la découverte partagée .agents/skills/wolfmarkdown, configure le chemin de compatibilité Claude Code, utilise une jonction de répertoire sur Windows lorsque cela est approprié, et refuse d'écraser des chemins non liés.

Utilisation rapide

Utilise WolfMarkDown sur docs/architecture.md.

Exporte cette recherche en Markdown en utilisant WolfMarkDown.

Vérifie docs/architecture.md avec WolfMarkDown sans le modifier.

Lorsqu'un hôte expose des commandes slash, le même flux de travail peut être invoqué comme :

/wolfmarkdown docs/architecture.md
/wolfmarkdown verify docs/architecture.md

L'invocation en langage naturel est l'interface portable. La présentation des commandes slash est spécifique à l'hôte.

Opérations

Opération	Ce que fait WolfMarkDown
Compose	Crée un véritable fichier .md à partir du matériel source, supprime les échafaudages de chat, le formate, le vérifie et ne publie qu'après un SUCCÈS.
Clean	Répare un fichier Markdown existant avec les modifications sémantiques minimales nécessaires et restaure l'original si la vérification échoue.
Verify	Vérifie le Markdown sans le modifier.
Doctor	Inspecte les dépendances d'exécution et la découverte de la compétence sans modifier l'installation.
Setup	Répare les dépendances d'exécution uniquement si nécessaire et configure la découverte partagée de la compétence.

Les cibles de nettoyage typiques incluent la hiérarchie des titres, les listes malformées, les tableaux GFM cassés, les blocs de code non fermés, les commentaires d'agent copiés, le langage dépendant de la conversation et le bruit décoratif qui ne devrait pas survivre dans la documentation.

Avant et après

Un brouillon d'agent désordonné peut aplatir une comparaison en un seul bloc :

Recommandation utiliser relay_v2 pour le flux de portefeuille externe.
Comparaison Fournisseur Mode Risque Privy Approbation externe Moyen CDP Portefeuille intégré Élevé.
Notes d'implémentation relay_v2 confirme getTransaction après soumission.

Après que l'agent a rendu la structure explicite, WolfMarkDown peut publier un document tel que :

# Décision du flux de portefeuille

## Recommandation

Utiliser `relay_v2` pour le flux de portefeuille externe.

## Comparaison

| Fournisseur | Mode | Risque |
| --- | --- | --- |
| Privy | Approbation externe | Moyen |
| CDP | Portefeuille intégré | Élevé |

## Notes d'implémentation

`relay_v2` confirme `getTransaction` après soumission.

La sortie récupère un tableau et des titres, préserve les identifiants techniques et n'ajoute aucune information absente de la source. Ceci est un exemple structurel illustratif ; le jugement sémantique reste la propriété de l'agent.

Exemples

Les exemples publics montrent WolfMarkDown récupérant la structure à partir de Markdown réel façonné par l'IA sans inventer de sens manquant.

• Exemple de migration d'application mobile — un exemple complet avant-après couvrant l'assainissement d'enveloppe de chat, les tableaux séparés par tabulation, les puces Unicode, les variables d'environnement protégées et une note de base de données intentionnellement ambiguë.
• Entrée brute — la sortie IA source avant réparation.
• Sortie structurée — le Markdown résultant avec titres, tableaux GFM, listes et un bloc de code env.

Le README de l'exemple enregistre le harnais OpenCode, le modèle GLM-5.2 et l'invite exacte utilisée pour la reproduction.

Statut d'intégration des hôtes supportés

WolfMarkDown a une seule implémentation canonique. Le tableau distingue les chemins de découverte testés dans le dépôt de l'acceptation des hôtes qui nécessite encore un test dédié.

Hôte	Statut d'intégration	Chemin de découverte
Codex	Chemin de découverte et d'installateur du dépôt testé	.agents/skills partagé
Cursor	Chemin de découverte et d'installateur du dépôt testé	.agents/skills partagé
Claude Code	Chemin de lien de compatibilité testé	.claude/skills
OpenCode	Acceptation de l'hôte en attente	.agents/skills partagé lorsque activé par l'hôte
Gemini CLI	Acceptation de l'hôte en attente	.agents/skills partagé lorsque activé par l'hôte
GitHub Copilot	Acceptation de l'hôte en attente ; l'intégration de plugin est une preuve historique	Agent Skills ou support de plugin activé par l'hôte

L'acceptation de l'hôte n'est pas déduite de la présence d'un binaire ou d'un répertoire. Le modèle hôte détermine la qualité sémantique ; WolfMarkDown fournit le flux de travail et les vérifications déterministes.

Comment ça fonctionne

Intention de l'utilisateur
    ↓
Jugement sémantique de l'agent
    ↓
Carte source et réparation sémantique
    ↓
Parsing GFM + vérifications titres/tableaux
    ↓
Vérifications des blocs de code, frontmatter et espaces blancs
    ↓
Vérification du formatage Prettier
    ↓
markdownlint
    ↓
Intégrité des jetons protégés (avec un instantané source) + idempotence
    ↓
SUCCÈS → conserver ou publier     ÉCHEC → restaurer ou ne pas publier

Avant le formatage, l'agent vérifie la présence d'une structure sémantique aplatie. Un document peut être un Markdown valide et néanmoins être une transformation échouée s'il a perdu des tableaux, titres, listes ou relations.

Limite de la réparation sémantique

L'agent reconstruit les titres, listes, tableaux, paragraphes et sections sœurs uniquement lorsque la source rend la structure claire. Une suite de lignes sans en-tête n'est pas automatiquement un tableau, une phrase courte n'est pas automatiquement un titre, et une phrase isolée Étiquette : valeur n'est pas automatiquement un élément de liste. Pour les documents longs, l'agent maintient une carte source et réconcilie le plan complet, les relations entre sections, les limites des tableaux et les valeurs protégées avant de publier. Si la source ne peut pas être examinée complètement, il préserve l'incertitude et signale la limite plutôt que de deviner.

Vérification et limite de qualité

WolfMarkDown SUCCÈS signifie que l'artefact a passé les vérifications déterministes applicables :

• l'artefact Markdown a passé les vérifications de formatage, parsing, lint, blocs de code et idempotence ;
• l'agent a pris et rapporté des décisions structurelles fondées sur la source ;
• le contenu technique protégé a été préservé uniquement lorsque l'intégrité a été vérifiée par rapport à un instantané source intact, comme dans Clean et Compose ou avec --integrity-from ;
• les opérations Clean et Compose échouées n'ont pas laissé de résultat publié non vérifié.

Verify autonome sans source d'intégrité signale l'intégrité comme ignorée. Son SUCCÈS ne prouve pas que les jetons protégés ont été préservés.

Détails protégés

Lorsqu'un instantané source intact est disponible, les vérifications d'intégrité protègent le contenu technique incluant :

• URLs, code en ligne et code dans les blocs ;
• clés publiques, signatures, hachages, versions et identifiants ;
• chemins de fichiers et variables d'environnement contextuelles ;
• dates, pourcentages et valeurs monétaires.

Ceci est une preuve de qualité Markdown, pas une approbation de contenu. SUCCÈS n'établit pas l'exactitude factuelle, l'exhaustivité, l'actualité, la conformité politique ou l'autorisation de publier. Il ne vérifie pas les faits.

Les vérifications déterministes sont une preuve des propriétés de l'artefact. Ce ne sont pas un oracle sémantique, et ils ne remplacent pas la responsabilité de l'agent de tenir compte de chaque signal source clair.

Preuve de la version v0.2.1

• 82/82 tests Node passent.
• Les vérifications de propriétés sémantiques exécutables couvrent les titres, les tableaux GFM, les jetons protégés et la préservation des tableaux ambigus.
• skills-ref validate ./wolfmarkdown passe.
• Les vérifications de l'installateur, Doctor, restauration, collision de cible, intégrité et idempotence restent couvertes.

Intégration historique de plugin externe

Le package Agent Plugins v0.1.1 a passé l'intégration automatisée de plugin externe de GitHub Awesome Copilot. Ceci est une preuve d'empaquetage historique, pas une preuve d'acceptation par l'hôte pour la v0.2.1.

Détails d'architecture

WolfMarkDown/
├── plugin.json
├── .agents/
│   └── skills/
│       └── wolfmarkdown → ../../wolfmarkdown
├── skills/
│   └── wolfmarkdown → ../wolfmarkdown
└── wolfmarkdown/
    ├── SKILL.md
    ├── config/
    ├── lib/
    ├── references/
    ├── scripts/
    └── tests/

Décisions de l'agent

L'agent possède le routage de l'intention, la cartographie source, la classification sémantique, l'assainissement de la conversation, la récupération des titres/listes/tableaux, la gestion de l'ambiguïté et la composition.

Preuve déterministe

Les scripts possèdent le formatage, le lint Markdown, le parsing GFM, l'équilibre des blocs de code, les vérifications de frontmatter, l'intégrité des jetons protégés, l'idempotence, l'installation, les vérifications Doctor, la restauration et l'évaluation sémantique basée sur les propriétés. Ils ne réécrivent pas le sens de la source.

Prettier est le seul imprimeur final.

L'identifiant machine de la compétence et le répertoire du système de fichiers sont intentionnellement en minuscules wolfmarkdown ; le nom du produit est WolfMarkDown.

Évaluations sémantiques

Le corpus d'évaluation utilise des documents synthétiques et des propriétés structurelles plutôt que des instantanés de documents complets et fragiles. Exécutez un cas contre un candidat produit par un agent après le vérificateur normal :

node wolfmarkdown/scripts/evaluate-semantic.mjs \
  --case preservation-de-structure-ambiguë \
  source.md candidat.md

L'évaluateur vérifie les titres attendus et le nombre de tableaux, la préservation des jetons protégés et les propriétés de sécurité telles que le refus de transformer une suite de lignes sans en-tête ambiguë en tableau. Il n'infère ni ne répare le candidat.

Commandes développeur

npm ci --prefix wolfmarkdown
npm test
npx --yes skills-ref validate ./wolfmarkdown

Commandes directes utiles :

node wolfmarkdown/scripts/doctor.mjs
node wolfmarkdown/scripts/format-markdown.mjs chemin/vers/fichier.md
node wolfmarkdown/scripts/verify-markdown.mjs chemin/vers/fichier.md
node wolfmarkdown/scripts/evaluate-semantic.mjs --help

Les cas sémantiques se trouvent dans wolfmarkdown/tests/evals/. Les entrées d'acceptation multi-hôtes se trouvent dans wolfmarkdown/tests/acceptance/.

Limites actuelles

• /wolfmarkdown setup fonctionne uniquement après que la compétence est détectable par l'hôte.
• --mode n'est pas pris en charge.
• Aucun fork de compétence spécifique au fournisseur n'est créé.
• Windows nécessite une autorisation pour créer la jonction de découverte appropriée.
• L'assainissement sémantique reste jugé par l'agent par conception.
• Le vérificateur prouve les propriétés de l'artefact Markdown ; il ne certifie pas la prose arbitraire ou l'aptitude à la publication.
• La réparation de documents longs dépend de la capacité de l'agent à conserver et à réconcilier son registre de documents ; une revue de source incomplète doit être signalée plutôt que devinée.

Métadonnées du dépôt

Sujets de dépôt GitHub recommandés :

ai-agents agent-skills markdown documentation claude-code codex cursor github-copilot

Les sujets doivent être configurés dans les paramètres du dépôt GitHub. Ce sont des métadonnées de découvrabilité, pas une preuve de compatibilité.

Contribuer

Vous avez trouvé un cas limite Markdown que WolfMarkDown devrait mieux gérer ? Ouvrez un ticket.

Les pull requests sont particulièrement utiles pour les échecs Markdown reproductibles, les cas limites d'intégrité, les problèmes d'installation multiplateforme, des preuves supplémentaires d'acceptation par l'hôte et des améliorations ciblées qui préservent l'architecture à implémentation unique.

Licence

WolfMarkDown est disponible sous la Licence MIT.