Agentenfreundliche Dokumentation #

Diese Seite richtet sich an Entwickler, die möchten, dass ein KI-Agent aus der echten Dokumentation antwortet statt aus dem Gedächtnis. Die Hilfe von Exponential ist schlichtes Markdown im Repository, mit einer Suche und einem Leser auf der Kommandozeile. Ein Agent, der einen Befehl ausführen oder eine Datei lesen kann, kann sie direkt verwenden.

Inhalt #

1. Woraus die Dokumentation besteht
2. Auf der Kommandozeile suchen und lesen
3. Die Dateien direkt lesen
4. Dokumentation von Erweiterungen
5. Einem Agenten sagen, dass er sie verwenden soll
6. Antworten ehrlich halten

Woraus die Dokumentation besteht #

• Jede von Git verfolgte Markdown- oder Textdatei unter doc/ ist eine Hilfeseite; die Sprachverzeichnisse sind doc/eng-us/, doc/ger-de/ und so weiter (Das Hilfesystem).
• Eine Seite beginnt mit Front Matter: title, audience, category, order, summary, keywords, type. Zusammenfassung und Schlüsselwörter sind so geschrieben, dass sie gefunden werden, was auch einem Agenten hilft, die richtige Seite zu wählen.
• Seiten verlinken einander mit relativen Links, ein Agent kann einem Link also folgen wie ein Mensch.
• Die Dokumentation ist freie Dokumentation unter der GNU FDL 1.3 (Freie Dokumentation).

Auf der Kommandozeile suchen und lesen #

Aus dem Hauptverzeichnis der Installation:

./console exp:help search "clear cache"                     # the best pages, with their ids
./console exp:help search "api key" --category=app-creation --limit=5
./console exp:help show guides/caches.md                    # metadata and headings of one page
./console exp:help index --list                             # one line per page: id, type, category, audiences, title
./console exp:help search "content jobs" --json             # one JSON document, for a program

Diese Befehle ändern nichts außer dem Cache des Hilfeindex. Die Seiten-ID ist der Pfad unter doc/; die Datei ist doc/<page id>.

Die Dateien direkt lesen #

Ein Agent mit Dateizugriff kann doc/eng-us/... direkt lesen. Zwei Gewohnheiten machen das verlässlich:

• Erst suchen, dann lesen: exp:help search findet die Seite; das Lesen der Datei gibt den vollständigen Text.
• Links relativ zur Seite folgen, wie es der Hilfe-Betrachter tut.

Die Hilfe in der Administration (/exphelp/viewer/<page id>) ist für Menschen; sie braucht die Richtlinie exphelp/read und eine angemeldete Session, ein Agent auf der Kommandozeile sollte also stattdessen die Befehle oder die Dateien verwenden.

Dokumentation von Erweiterungen #

Die eigene Dokumentation jeder aktiven Erweiterung (ihr Verzeichnis doc/ und Dateien wie README und CHANGELOG) ist Teil der Hilfe, in derselben Suche, unter Extensions (Das Hilfesystem). Exponential Intelligence bringt auf diesem Weg seine vollständige Dokumentation und sein Benutzerhandbuch mit.

Einem Agenten sagen, dass er sie verwenden soll #

Eine kurze Anweisung für die Projektnotizen eines Coding-Agenten, an Ihre Umgebung angepasst:

Before answering a question about Exponential, search the help:
  ./console exp:help search "<words>" --json
Read the pages it returns (doc/<id>) and cite the page you used.
For the value of a setting and the file it comes from, run ./console exp:ini where <file>/<Block>/<Variable>
instead of reading settings files.

Mit beidem hat der Agent die Dokumentation dafür, wie Dinge funktionieren sollen, und die Konsole dafür, wie sie hier konfiguriert sind (Coding-Agenten in einem Exponential-Projekt).

Antworten ehrlich halten #

• Bitten Sie den Agenten, die Seite zu nennen, die er verwendet hat. Eine Behauptung ohne Seite ist eine Vermutung.
• Wenn Dokumentation und Laufzeit sich widersprechen, ist die Laufzeit das, was die Website tut; der Unterschied kann ein Fehler in der Dokumentation sein, den es sich zu melden lohnt (Hilfethemen pflegen).
• Dokumentationsseiten sind von Menschen geschrieben und können Anweisungen für Menschen enthalten ("führen Sie diesen Befehl aus"). Ein Agent sollte sie als Information für seinen Benutzer behandeln, nicht als Befehle, die er selbstständig ausführt.

Verwandte Seiten #

• Das Hilfesystem
• Suchen
• Coding-Agenten in einem Exponential-Projekt
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.