DenshoApp/densho-skill

Densho

Densho ist eine selbst gehostete Wissensdatenbank. Ein Arbeitsbereich enthält Räume, jeder Raum enthält einen Baum von Seiten, und jede Seite ist ein Live-Dokument für die Zusammenarbeit, das andere Personen gleichzeitig mit Ihnen bearbeiten können.

Sie erreichen es über den MCP-Server, den der Benutzer verbunden hat. Ihr Zugriff entspricht genau seinem: Ein Tool, das nichts zurückgibt, bedeutet normalerweise, dass dieser Raum nicht für ihn lesbar ist, nicht dass der Arbeitsbereich leer ist.

Die eine Regel zum Schreiben

update_page ersetzt den gesamten Inhalt. Es hängt nichts an. Schreiben ohne Lesen zerstört alles, was davor da war.

Neuere Instanzen setzen dies durch: Das Ersetzen von Inhalten erfordert expectedVersion, das Token, das get_page zurückgibt. Wenn die Seite sich geändert hat, seit Sie sie gelesen haben, oder die ID falsch ist, wird der Schreibvorgang verweigert, anstatt stillschweigend angewendet zu werden. Lesen, zusammenführen, schreiben:

1. get_page liefert { version, title, content }.
2. Erstellen Sie den vollständigen neuen Text aus diesem Inhalt.
3. update_page mit content und expectedVersion: <version>

Wenn die Antwort lautet, dass die Seite geändert wurde, lesen Sie erneut und wiederholen Sie die Zusammenführung. Versuchen Sie es nie mit der alten Version, und umgehen Sie die Schutzmaßnahme nicht, indem Sie Inhalte weglassen, die Sie nicht gelesen haben.

Ältere Instanzen haben kein solches Token: get_page gibt ein einziges Markdown-Dokument zurück, bei dem der Titel als # H1 vorangestellt ist, den der Inhalt nicht enthält. Wenn Sie diesen direkt in update_page zurückgeben, wird der Titel in den Text geschrieben, und die Seite zeigt ihn dann doppelt an. Entfernen Sie diese erste Überschrift vor dem Schreiben und gehen Sie mit dem Rest ebenso sorgfältig um: Nichts dort verhindert einen fehlerhaften Schreibvorgang. Lesen Sie die Seite daher unmittelbar vor dem Schreiben und behalten Sie alles, was Sie nicht absichtlich ändern.

Bevor Sie etwas anfassen

• Suchen Sie, bevor Sie erstellen. search_pages zuerst. Ein Wiki stirbt an Duplikaten, und die Seite, die Sie erstellen wollen, existiert oft unter einem anderen Titel.
• Rufen Sie get_markdown_reference einmal pro Sitzung auf, bevor Sie einen Seiteninhalt verfassen. Es gibt den genauen Dialekt zurück, den diese Instanz rendert, direkt von der Instanz, sodass er nie veraltet ist. Raten Sie nicht die Syntax aus dem Gedächtnis und gehen Sie nicht von GitHub-Flavored Markdown aus. Wenn das Tool nicht angeboten wird, ist die Instanz älter: Halten Sie sich an die Einschränkungen unter „Was nicht funktioniert“ weiter unten und verweisen Sie den Benutzer auf Guide > Editor > „Markdown in and out“ in seinem eigenen Arbeitsbereich für die vollständige Syntax.
• Bevorzugen Sie Kommentare gegenüber Bearbeitungen auf einer Seite, deren Änderung nicht angefordert wurde. add_comment platziert Ihre Anmerkung neben dem Text und benachrichtigt den Autor – das ist die höfliche Art bei der Arbeit eines anderen.
• Finden Sie heraus, wo eine Seite hingehört, mit list_pages, bevor Sie eine erstellen. Ein Wiki ist ein Baum, und eine Seite, die an der Wurzel eines Raums abgelegt wird, ist eine Seite, die niemand findet. Übergeben Sie parentPageId.
• Schreiben Sie in der Sprache der Seiten um Sie herum, nicht in Ihrer eigenen Standardsprache. Ein Arbeitsbereich ist oft durchgängig in einer Sprache verfasst, und eine Seite in einer anderen wirkt wie ein Eindringling.

Die Werkzeuge

Lesen. list_spaces (die Räume, denen der Benutzer angehört), list_pages (der Seitenbaum eines Raums als flache Liste mit Eltern), search_pages (Volltext, optional auf einen Raum beschränkt, maximal 20 Treffer und keine Paginierung – verfeinern Sie die Abfrage, anstatt die Liste als vollständige Wahrheit zu betrachten), get_page (Titel und Inhalt als Markdown plus Versions-Token), list_comments (Threads und deren Status der Auflösung).

Schreiben. create_page (in einem Raum, optional unter einer übergeordneten Seite, optional mit Inhalt), update_page (Titel und/oder vollständiger Inhalt), add_comment (ein neuer Thread oder eine Antwort mit parentCommentId), resolve_comment.

Seiten sind auch als densho://page/{id}-Ressourcen verfügbar, sodass ein Client eine Seite direkt anhängen kann.

Nicht jede Instanz bietet alle an. Schreibwerkzeuge existieren nur, wenn der Benutzer bei der Autorisierung Schreibzugriff gewährt hat, und eine ältere Instanz hat möglicherweise nicht die Kommentarauflistung, das Auflösungswerkzeug und die Markdown-Referenz. Arbeiten Sie mit dem, was der Client Ihnen tatsächlich zeigt, und sagen Sie es, anstatt eine Bearbeitung zu beschreiben, die Sie nicht durchführen können.

Eine Seite schreiben, die Leute lesen werden

Strukturieren Sie sie wie eine Dokumentation, nicht wie eine Chat-Antwort. Überschriften, die sagen, worum es im Abschnitt geht, kurze Absätze und Aufzählungen, wenn der Inhalt eine Liste ist.

• Verwenden Sie :::info, :::warning und die anderen Hervorhebungen für das, was den Leser wirklich unterbricht. Drei Hervorhebungen hintereinander wirken wie keine.
• Verwenden Sie :::toggle für Details, die die meisten Leser überspringen, nicht um die Antwort zu verstecken.
• Verwenden Sie :::subpages für einen Index von Unterseiten anstelle einer handgeschriebenen Liste von Links, die veraltet, sobald jemand eine Seite hinzufügt.
• Bevorzugen Sie eine Tabelle gegenüber einem Absatz, der Paare von Dingen aufzählt.

Alles, was der Editor unterstützt, wird über Markdown hin und zurück übertragen, sodass das, was Sie schreiben, das ist, was die Person sieht und was sie später exportiert. Der Hin- und Rückweg normalisiert dabei: $$maths$$ kommt auf drei Zeilen zurück, Blöcke erhalten Leerzeilen dazwischen. Wenn etwas, das Sie zurücklesen, etwas anders geformt ist als das, was Sie gesendet haben, ist das normal und kein Zeichen für einen Fehler.

Was nicht funktioniert

• Raw-HTML-Tags werden maskiert und als Text angezeigt. Ein eingerahmter ```htmlrender-Block ist der Weg, HTML zu rendern, und er muss in sich geschlossen sein: kein Netzwerk, keine externen Ressourcen.
• GitHub-Callouts (> [!NOTE]) sind nicht Teil des Dialekts: Die Klammern werden maskiert, und der Leser sieht \[!NOTE\] innerhalb eines einfachen Zitats. Verwenden Sie einen Callout.
• Fußnoten sind hier schlimmer als nutzlos. text[^1] mit seiner [^1]: note-Definition ergibt [^1](note), einen Link, der ins Leere zeigt. Schreiben Sie den Nebensatz inline oder in einen Callout.
• Ein ```math-Rahmen wird nicht gerendert. Block-Mathematik ist $$ ... $$.
• Sie können nichts hochladen. Es gibt kein Datei- oder Bildwerkzeug, also schreiben Sie niemals ein Markdown-Bild, das auf einen lokalen Pfad oder eine Datei verweist, die Sie angeblich hinzugefügt haben. Ein bereits auf der Seite vorhandenes Bild funktioniert weiterhin: Lassen Sie seinen Link unangetastet, wenn Sie den Inhalt neu schreiben.
• Erfinden Sie keine Chip-Identifikatoren. Erwähnungen, Seitenlinks und synchronisierte Blöcke kodieren echte IDs ([@Name](mention:<userId>), [label](page:<pageId>), ![[synced-blocks/...]]). Eine erfundene ID wird als toter Chip gerendert. Verwenden Sie eine echte ID, die Sie von einem Tool erhalten haben, oder schreiben Sie einen einfachen Link.

Dinge, die Auswirkungen auf das Team haben

• Eine von Ihnen bearbeitete Seite erscheint sofort im Editor aller, die sie geöffnet haben, und zwar unter ihrem Cursor. Das Umschreiben einer langen Seite, während jemand daran arbeitet, ist störend, selbst wenn es technisch sicher ist.
• Das Bearbeiten einer als Verifiziert markierten Seite setzt sie zurück auf „Bereit zur Verifizierung“, was einem Administrator Arbeit aufhalst. Sagen Sie es, wenn Sie es tun.
• Kommentare benachrichtigen Personen. Eröffnen Sie keinen Thread für etwas, das Sie nebenbei beheben können, und lösen Sie keinen Thread auf, den Sie nicht behandelt haben.

Rückmeldung geben

Geben Sie dem Benutzer den Seitentitel und wo sie sich befindet, nicht die rohen IDs. Sagen Sie klar, was Sie geändert haben: Ein vollständiger Ersatz des Inhalts verdient es, als solcher benannt zu werden, und wenn Sie Ihren Text in eine vorhandene Seite eingefügt haben, sagen Sie, was Sie behalten haben.