DenshoApp/densho-skill

Densho

Densho est une base de connaissances auto-hébergée. Un espace de travail contient des espaces, chaque espace contient une arborescence de pages, et chaque page est un document collaboratif vivant que des personnes peuvent modifier en même temps que vous.

Vous y accédez via le serveur MCP connecté par l'utilisateur. Votre accès est exactement le sien : un outil qui ne retourne rien signifie généralement que cet espace ne lui appartient pas, pas que l'espace de travail est vide.

L'unique règle concernant l'écriture

update_page remplace l'intégralité du corps. Ce n'est pas un ajout. Écrire sans lire détruit tout ce qui se trouvait là.

Les instances récentes l'imposent : remplacer le contenu nécessite expectedVersion, le jeton que get_page retourne. Si la page a changé depuis que vous l'avez lue, ou si l'identifiant est erroné, l'écriture est refusée plutôt que d'être appliquée en silence. Lisez, fusionnez, écrivez :

1. get_page vous donne { version, title, content }
2. construisez le nouveau corps complet à partir de ce contenu
3. update_page avec content et expectedVersion: <version>

Si la réponse indique que la page a changé, relisez et refaites la fusion. Ne réessayez jamais avec l'ancienne version, et ne contournez jamais la protection en supprimant du contenu que vous n'avez pas lu.

Les instances plus anciennes n'ont pas ce jeton : get_page retourne un document Markdown unique avec le titre précédé d'un # H1, que le corps ne contient pas. Renvoyer cela directement dans update_page écrit le titre dans le corps et la page l'affiche alors deux fois. Supprimez cet en-tête avant d'écrire, et faites de même avec le reste : rien n'empêche une écriture erronée, alors lisez la page immédiatement avant de l'écrire et conservez tout ce que vous ne modifiez pas délibérément.

Avant de toucher à quoi que ce soit

• Recherchez avant de créer. search_pages d'abord. Un wiki meurt des doublons, et la page que vous êtes sur le point d'écrire existe souvent sous un autre titre.
• Appelez get_markdown_reference une fois par session avant de rédiger le corps d'une page. Elle retourne le dialecte exact que cette instance affiche, depuis l'instance elle-même, donc elle n'est jamais obsolète. Ne devinez pas la syntaxe de mémoire et ne partez pas du principe que c'est du Markdown flavored GitHub. Si l'outil n'est pas proposé, l'instance est antérieure : respectez les limites décrites dans "Ce qui ne fonctionnera pas" ci-dessous, et orientez l'utilisateur vers Guide > Éditeur > "Markdown in and out" dans son propre espace de travail pour la syntaxe complète.
• Préférez commenter plutôt que modifier une page qu'on ne vous a pas demandé de changer. add_comment place votre remarque à côté du texte et notifie l'auteur, ce qui est la démarche courtoise sur le travail d'autrui.
• Trouvez où une page appartient avec list_pages avant d'en créer une. Un wiki est une arborescence, et une page déposée à la racine d'un espace est une page que personne ne trouve. Passez parentPageId.
• Écrivez dans la langue des pages qui vous entourent, pas dans votre langue par défaut. Un espace de travail est souvent rédigé dans une seule langue, et une page dans une autre langue fait figure d'intruse.

Les outils

Lecture. list_spaces (les espaces auxquels l'utilisateur appartient), list_pages (l'arborescence d'un espace sous forme de liste plate avec les parents), search_pages (texte intégral, éventuellement limité à un espace, au plus 20 résultats et sans pagination, donc affinez la requête plutôt que de prendre la liste pour la vérité absolue), get_page (titre et corps en Markdown, plus le jeton de version), list_comments (discussions et leur état de résolution).

Écriture. create_page (dans un espace, éventuellement sous un parent, éventuellement avec un corps), update_page (titre et/ou corps complet), add_comment (une nouvelle discussion, ou une réponse avec parentCommentId), resolve_comment.

Les pages sont également exposées en tant que ressources densho://page/{id}, afin qu'un client puisse en attacher une directement.

Toutes les instances ne proposent pas tous ces outils. Les outils d'écriture n'existent que si l'utilisateur a accordé l'accès en écriture lors de l'autorisation, et une instance plus ancienne peut manquer de la liste des commentaires, de l'outil de résolution et de la référence Markdown. Travaillez avec ce que le client vous montre réellement, et dites-le plutôt que de décrire une modification que vous ne pouvez pas effectuer.

Rédiger une page que les gens liront

Structurez-la comme de la documentation, pas comme une réponse de chat. Des titres qui indiquent le sujet de la section, des paragraphes courts, et des listes là où le contenu est une liste.

• Utilisez :::info, :::warning et les autres callouts pour ce qui interrompt réellement le lecteur. Trois callouts à la suite n'en signifient aucun.
• Utilisez :::toggle pour les détails que la plupart des lecteurs ignorent, pas pour cacher la réponse.
• Utilisez :::subpages pour un index des pages enfants plutôt qu'une liste de liens écrite à la main, qui devient obsolète dès que quelqu'un ajoute une page.
• Préférez un tableau à un paragraphe énumérant des paires d'éléments.

Tout ce que l'éditeur prend en charge fait un aller-retour via Markdown, donc ce que vous écrivez est ce que la personne voit, et ce qu'elle exporte plus tard. L'aller-retour normalise au passage : $$maths$$ revient sur trois lignes, les blocs gagnent des lignes vides entre eux. Relire quelque chose de forme légèrement différente de ce que vous avez envoyé est normal et n'est pas un signe d'échec.

Ce qui ne fonctionnera pas

• Les balises HTML brutes sont échappées et affichées comme du texte. Un bloc délimité ```htmlrender est la façon d'afficher du HTML, et il doit être autonome : pas de réseau, pas de ressources externes.
• Les callouts GitHub (> [!NOTE]) ne font pas partie du dialecte : les crochets sont échappés et le lecteur voit \[!NOTE\] à l'intérieur d'une citation simple. Utilisez un callout.
• Les notes de bas de page sont pires qu'inutiles ici. texte[^1] avec sa définition [^1]: note donne [^1](note), un lien qui ne mène nulle part. Écrivez la digression en ligne ou dans un callout.
• Un bloc délimité ```math ne s'affiche pas. Les maths en bloc se font avec $$ ... $$.
• Vous ne pouvez rien téléverser. Il n'y a pas d'outil de fichier ou d'image, donc n'écrivez jamais d'image Markdown pointant vers un chemin local ou un fichier que vous prétendez avoir ajouté. Une image déjà présente dans la page continue de fonctionner : laissez son lien intact lorsque vous réécrivez le corps.
• N'inventez jamais d'identifiants de puces. Les mentions, les liens de page et les blocs synchronisés encodent des identifiants réels ([@Nom](mention:<userId>), [étiquette](page:<pageId>), ![[synced-blocks/...]]). Un identifiant inventé s'affiche comme une puce morte. Utilisez un identifiant réel obtenu via un outil, ou écrivez un lien simple.

Choses qui ont des conséquences pour l'équipe

• Une page modifiée par votre intermédiaire apparaît instantanément dans l'éditeur de toute personne qui l'a ouverte, sous son curseur. Réécrire une longue page pendant que quelqu'un y travaille est perturbateur, même si c'est techniquement sûr.
• Modifier une page marquée Vérifiée la renvoie à "Prête à vérifier", ce qui ajoute du travail à un administrateur. Dites-le lorsque vous le faites.
• Les commentaires notifient les personnes. N'ouvrez pas une discussion pour quelque chose que vous pouvez corriger en passant, et ne résolvez pas une discussion que vous n'avez pas traitée.

Rapport sur les actions

Donnez à l'utilisateur le titre de la page et son emplacement, pas des identifiants bruts. Dites clairement ce que vous avez changé : un remplacement complet du corps mérite d'être nommé comme tel, et si vous avez fusionné votre texte dans une page existante, dites ce que vous avez conservé.