Zum Inhalt springen
Documentation

Den KI-Agenten anpassen

Alles auf dieser Seite ist eine lokale Datei. Dateien unter .champrep/ in einem Repository werden über Git mit Ihrem Team geteilt; Dateien unter $CONFIG/ai/ gelten nur für Sie, in jedem Projekt. Wenn ein Projekt und eine Benutzerdefinition denselben Namen haben, hat die Projektdefinition Vorrang.

Projektinhalte in .champrep/ bleibt inaktiv, bis Sie dem Repository vertrauen. Siehe Vertrauenswürdigkeit des Repositorys.

CHAMPREP.md enthält feststehende Anweisungen für den Agenten: wie das Projekt erstellt und getestet wird, Konventionen und Dinge, die zu vermeiden sind. Der Agent liest zu Beginn jeder Sitzung:

  • $CONFIG/ai/CHAMPREP.md, Ihre persönlichen Anweisungen für jedes Projekt;
  • CHAMPREP.md im Projektstammverzeichnis und in jedem Verzeichnis vom Stammverzeichnis abwärts bis zu dem Ort, an dem Sie den Agenten gestartet haben.

Wenn ein Verzeichnis kein CHAMPREP.md, ein AGENTS.md wird stattdessen verwendet.

AktionWie
Erstellen Sie eine/init durchsucht das Repository und schreibt CHAMPREP.md, wobei nützliche Inhalte aus einer bestehenden Vorlage beibehalten werden AGENTS.md.
Notiz hinzufügenStarten Sie eine Eingabeaufforderung mit #, zum Beispiel # run make lint before committing.
Anzeigen oder bearbeiten/memoryoder /memory edit [user|project|FILE] um sie in Ihrem Editor zu öffnen.

Ihr CHAMPREP AIKontospeicher, der in Ihren EinstellungenCHAMPREP AI im Web verwaltet wird, gilt auch im Terminal. /memory zeigt ihn schreibgeschützt an.

Ein benutzerdefinierter Befehl ist eine Markdown-Prompt-Vorlage, die Sie als ausführen. /<name>.

SpeicherortGültigkeitsbereich
.champrep/commands/NAME.mdDieses Projekt
$CONFIG/ai/commands/NAME.mdSie

Eine Datei in einem Unterordner, wie beispielsweise commands/git/commit.md, wird zu /git:commit. Erstellen Sie eine mit /commands new NAME und listen Sie diese mit /commands.

---
description: Explain a failing test and propose a fix
argument-hint: <test name>
allowed-tools: [local_read_file, local_grep, local_bash]
---
Find the test named $1, run it, and explain why it fails.
Relevant notes: @docs/testing.md
Recent changes:
!`git log --oneline -5`
  • $ARGUMENTS ist alles, was auf den Befehlsnamen folgt; $1, $2, … sind einzelne Argumente. Verwendet die Vorlage keines von beiden, werden die Argumente angehängt.
  • @path bezieht eine Arbeitsbereichsdatei ein. Geheime Dateien werden niemals einbezogen.
  • !`command` führt einen Befehl aus, wenn Sie die Vorlage aufrufen. Sie werden einmal pro Vorlage sowie bei jeder Änderung dazu aufgefordert, dies zu genehmigen.
  • allowed-tools schränkt die Tools für diesen Durchlauf ein, und model überschreibt das Modell.

Ein Skill ist ein Ordner mit Anweisungen und optionalen Begleitdateien, den der Agent nur dann lädt, wenn er ihn benötigt. Bis dahin sieht das Modell lediglich den Namen und die Beschreibung des Skills, sodass viele Skills nur sehr wenig Kontext beanspruchen.

SpeicherortGültigkeitsbereich
.champrep/skills/NAME/SKILL.mdDieses Projekt
$CONFIG/ai/skills/NAME/SKILL.mdSie
---
description: Release checklist for this service
when_to_use: When the user asks to cut, tag, or publish a release
---
1. Confirm the changelog has an entry for the new version.
2. ...

/skills listet Skills auf, einschließlich derer aus Ihrem KontoCHAMPREP AI. Führen Sie einen direkt mit /<skill-name>.

Ein benutzerdefinierter Agent ist ein Subagent mit eigenen Anweisungen, Tools und einem eigenen Modell.

SpeicherortGültigkeitsbereich
.champrep/agents/NAME.mdDieses Projekt
$CONFIG/ai/agents/NAME.mdSie
---
name: test-writer
description: Writes and fixes unit tests. Use after a code change.
tools: [local_read_file, local_grep, local_glob, local_edit_file, local_bash]
permission_mode: accept-edits
isolation: worktree
---
You write focused unit tests that follow this project's existing style.
  • description Teilt dem Hauptagenten mit, wann er Aufgaben an ihn delegieren soll.
  • tools schränkt die Tools ein; lassen Sie diesen Parameter weg, um die Tools der Sitzung zu übernehmen.
  • permission_mode kann den Agenten nur strenger einstellen als Ihre Sitzung.
  • isolation: worktree führt es in seinem eigenen Git-Arbeitsverzeichnis aus.

Verwalten Sie Agenten mit /agents create|edit|delete NAME. Starten Sie eine Sitzung als Agent mit champrep ai --agent NAMEoder senden Sie ihm eine Eingabeaufforderung mit @NAME prompt. Siehe Unteragenten.

Hooks sind Shell-Befehle, die der an bestimmten Punkten einer Sitzung ausführtCLI, beispielsweise um Dateien nach einer Bearbeitung zu formatieren oder bestimmte Befehle zu blockieren.

EreignisWird ausgeführt
SessionStartWenn eine Sitzung beginnt.
UserPromptSubmitBevor eine Abfrage gesendet wird. Kann diese blockieren oder Kontext hinzufügen.
PreToolUseBevor ein lokales Tool ausgeführt wird. Kann die Ausführung blockieren.
PostToolUseNach der Ausführung eines lokalen Tools. Kann dem Ergebnis Feedback hinzufügen.
PermissionRequestWenn eine Berechtigungsabfrage angezeigt wird.
NotificationWann der Agent Sie benachrichtigt.
SubagentStopWenn ein Subagent abgeschlossen ist.
PreCompactBevor die Konversation komprimiert wird.
StopWenn eine Runde endet.
SessionEndWenn die Sitzung endet.

Konfigurieren Sie Hooks in einer beliebigen Einstellungsdatei:

{
"hooks": {
"PostToolUse": [
{ "matcher": "local_edit_file|local_write_file", "command": "npm run format --silent", "timeout": 30 }
],
"PreToolUse": [
{ "matcher": "local_bash", "command": "./scripts/check-command.sh" }
]
}
}
  • matcher ist ein regulärer Ausdruck für den Tool-Namen; lassen Sie ihn weg, um alle Tools zu erfassen.
  • Der Hook erhält eine JSON-Beschreibung des Ereignisses über die Standardeingabe.
  • Exit-Code 2oder JSON-Ausgabe mit "decision": "block" und ein reason, blockiert die Aktion, sofern das Ereignis dies zulässt. additionalContext in JSON Die Ausgabe fügt Text für das Modell hinzu.
  • Die Standard-Zeitüberschreitung beträgt 60 Sekunden, das Maximum liegt bei 10 Minuten.
  • Hooks werden mit Ihrer Umgebung ohne AnmeldedatenCHAMPREP ausgeführt.

Verwalten Sie Hooks mit /hooks, /hooks add EVENT [--matcher M] [--timeout S] [--scope user|project] -- COMMAND, /hooks disable ID, und /hooks enable ID.

BefehlOptionen
/colorEine Akzentfarbe für die Sitzungen dieses Projekts, um parallele Sitzungen voneinander zu unterscheiden: blue, cyan, green, yellow, orange, red, pink, magenta, purple, grayoder reset.
/themeauto, dark, light, high-contrastoder colorblind. NO_COLOR und --no-color Farbe deaktivieren.
/statuslineWählen Sie Segmente aus profile, model, context, branch, mode, cost, und tasks; verwenden Sie /statusline command CMD um die erste Zeile der Ausgabe Ihres eigenen Befehls anzuzeigen; /statusline reset Stellt die Standardeinstellung wieder her.
/output-styledefault, concise, explanatoryoder learning.
/vimBearbeitung im Vim-Stil in der Eingabeaufforderung.
/keybindingsTastenbelegungen anzeigen; /keybindings edit öffnet $CONFIG/ai/keybindings.json.
/configAll das auf einem Bildschirm.

Die Konversationen des Agenten befinden sich auf Ihrem CHAMPREP AIKonto. Nur der maschinenspezifische Status wird lokal gespeichert. Zeigen Sie alle Speicherorte auf Ihrem Rechner mit folgendem Befehl an:

Terminal-Fenster
champrep ai paths
WasWo
CLI Profile und Umgebungen$CONFIG/config.toml
Ihre Agent-Einstellungen: Regeln, Modus, Design, Statuszeile, Hooks$CONFIG/ai/settings.json
Überschreiben von Tastenbelegungen$CONFIG/ai/keybindings.json
Ihre persönlichen Anweisungen$CONFIG/ai/CHAMPREP.md
Ihre Agenten, Befehle und Skills$CONFIG/ai/agents/, commands/, skills/
Ihre lokalen MCP-Server$CONFIG/ai/mcp.json
Vertrauenswürdige Projekte$CONFIG/ai/trusted-projects.json
Aktuelle Konversationen pro Verzeichnis und Aufgabenlisten$STATE/ai/sessions.json
Eingabeverlauf (geschwärzt und gekürzt)$STATE/ai/history.jsonl
Debug-Protokolle (geschwärzt, werden 7 Tage lang aufbewahrt)$STATE/ai/logs/
Datei-Checkpoints$CACHE/ai/checkpoints/
Projekteinstellungen (committbar).champrep/settings.json, mcp.json, agents/, commands/, skills/
Ihre Projektüberschreibungen (von Git ignoriert).champrep/settings.local.json
ProjektanweisungenCHAMPREP.md
Arbeitsverzeichnisse.champrep/worktrees/

Anmeldedaten werden niemals in diesen Dateien gespeichert. Sie verbleiben im Schlüsselbund des Betriebssystems.

RootmacOS und LinuxWindows
$CONFIG$XDG_CONFIG_HOME/champrep, andernfalls ~/.config/champrep%APPDATA%\champrep
$STATE$XDG_STATE_HOME/champrep, andernfalls ~/.local/state/champrep%LOCALAPPDATA%\champrep\state
$CACHE$XDG_CACHE_HOME/champrep, andernfalls ~/.cache/champrep%LOCALAPPDATA%\champrep\cache

Festlegen CHAMPREP_CONFIG_DIR um alle drei in einem Verzeichnis zu halten, in config/, state/, und cache/ Unterordner. Dies ist nützlich für portable Installationen und isolierte CI-Läufe.