Wie HagiCode 13 Agent CLI-Tools in ein System integriert
Wie HagiCode 13 Agent CLI-Tools in ein System integriert
Ganz ehrlich: Die Aufgabe ist nicht unbedingt schwer, aber auch nicht einfach. Lassen Sie uns darüber sprechen, wie wir mit einer mehrschichtigen Architektur diverse Agent CLI-Tools wie Claude Code, Codex, Copilot und Gemini zentral verwalten und jederzeit neue hinzufügen können.
Hintergrund
Die Geschichte begann plötzlich, ausgehend von einem ziemlich nervigen Problem.
Agent CLI-Tools sind in den letzten zwei Jahren wie Pilze aus dem Boden geschossen – Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Kimi, Qoder, Kiro … Alle paar Monate taucht ein neues auf. Als Projekt, das möchte, dass Nutzer “ein HagiCode installieren und alle Agenten nutzen”, können wir nicht nur auf ein CLI setzen, aber wir können auch nicht für jedes CLI eine komplette Logik von Installation über Gesundheitsprüfung bis hin zur Planung schreiben – der Code würde so anschwellen, dass niemand ihn mehr warten will, wie ein verfilzter Wollknäuel, den niemand anfassen möchte.
Noch problematischer: Diese CLI-Tools haben ganz unterschiedliche “Temperamente”: manche nutzen stdio, andere gRPC, manche geben nur einen Shell-Eingang, und die Formate für Streaming-Ausgaben gehen alle auseinander. Wenn man direkt im Business-Code Entscheidungen wie if (provider == ClaudeCode) einbaut, wird das nach einem halben Jahr zu einem Klumpen “ererbter Code”, den niemand mehr anrühren möchte. Schließlich will niemand einen Ziegel anfassen, der schon wackelig aussieht.
Um all diese Schmerzen in den Griff zu bekommen, haben wir uns entschieden: Zwischen der Business-Schicht und den konkreten CLI-Tools eine dünne Abstraktionsschicht und eine gemeinsame Laufzeitumgebung einzufügen. Das sieht einfach aus, entscheidet aber direkt darüber, ob HagiCode neue CLI-Tools schnell integrieren kann. Ich werde später erklären, wie genau wir das machen.
Über HagiCode
Die in diesem Artikel geteilte Lösung stammt aus unserer Praxis im HagiCode-Projekt. HagiCode ist eine Integrationsplattform für KI-Coding-Assistenten, mit einem sehr klaren Ziel – mit einer einzigen Installation und einem einzigen Konfigurationssatz alle gängigen Agent CLI-Tools für Nutzer verfügbar zu machen.
Wie kommt die Zahl “13” zustande
Zuerst zu einer immer wieder gestellten Zahl – warum 13 Agent CLI-Tools.
Die Antwort steckt eigentlich in der Aufzählung AIProviderType, wie ein Bambusschatten vor dem Fenster – man muss nur hinschauen, um ihn zu sehen. Die ursprüngliche Definition sieht so aus:
public enum AIProviderType{ ClaudeCodeCli = 0, CodexCli = 1, GitHubCopilot = 2, CodebuddyCli = 3, OpenCodeCli = 4, IFlowCli = 5, // Veraltet HermesCli = 6, QoderCli = 7, KiroCli = 8, KimiCli = 9, GeminiCli = 10, DeepAgentsCli = 11, ReasonixCli = 12, PiCli = 13,}Die Aufzählung hat insgesamt 14 Werte, aber der Weg IFlowCli=5 ist nicht mehr gangbar. In AIProviderFactory wird sie explizit ausgeschlossen:
if (providerType == AIProviderType.IFlowCli){ throw new NotSupportedException("IFlowCli is no longer supported");}Zusammen mit einer Filterung durch IsActivelySupportedProviderType() sind im System tatsächlich 13 “lebendig”: Claude Code, Codex, GitHub Copilot, CodeBuddy, OpenCode, Hermes, Qoder, Kiro, Kimi, Gemini, DeepAgents, Reasonix, Pi.
So entsteht die “13”. Keine Marketingzahl, sondern eine Zahl, die im Code wirklich gezählt wurde. Zahlen lügen nicht, nur wir selbst tun es manchmal.
Schichtenarchitektur: Veränderungen in den Käfig sperren
Der Kerngedanke für die Integration von 13 CLI-Tools ist eigentlich ein Satz: Lassen Sie den Business-Code nicht kümmern, welches Tool er gerade aufruft.
Wir haben das in sechs Schichten unterteilt, von oben nach unten:
1. Identitätsschicht —— AIProviderType
Die Aufzählung ist die “Personalnummer” jedes CLI-Tools. Überall wo ein CLI-Tool erwähnt wird, wird es mit diesem Aufzählungswert identifiziert, zwischen Zeichenkette und Aufzählung wird mit ToStringValue() / ToAIProviderType() konvertiert. Einfach, aber unverzichtbar.
2. Business-Vertragsschicht —— IAIProvider / IAIProviderFactory
Die Business-Seite kennt nur die Schnittstelle IAIProvider, in der allgemeine Aktionen wie “einen Prompt senden und eine Streaming-Antwort erhalten” definiert sind. Was darunter liegt – Claude oder Codex – kümmert den Business nicht. Wie beim Briefschreiben: Sie geben den Brief ab, und was der Postbote heißt, ist Ihnen egal.
3. Adapterschicht —— *CliProvider
Jedes CLI-Tool hat einen dünnen Adapter, wie PiCliProvider, ReasonixCliProvider, ClaudeCodeCliProvider. Diese Adapter haben wenig zu tun: Sie übersetzen allgemeine Business-Anfragen in Parameter, die das konkrete CLI versteht, und übersetzen die Ausgaben zurück. Sie sind absichtlich sehr dünn gehalten – ein neues CLI-Tool hinzuzufügen ist im Grunde nur ein Kopieren und Anpassen.
4. Gemeinsame Laufzeitschicht —— ICliProvider<TOptions>
Diese Schicht in HagiCode.Libs ist der Ort, wo die echte Arbeit stattfindet: Prozesse plattformübergreifend starten, stdio-Übertragung verarbeiten, Streaming-Ausgaben parsen, Timeouts und Wiederholungen handhaben. Alle Adapter verwenden dieselbe Laufzeit, sodass die Prozessverwaltung bei der Integration eines neuen CLI-Tools im Grunde nicht neu geschrieben werden muss.
Als Vergleich: Die Adapterschicht ist der “Dolmetscher”, die gemeinsame Laufzeitschicht ist das “Logistikunternehmen”. Der Dolmetscher kümmert sich nur darum, dass die Botschaft verständlich ist. Wie das Paket geliefert wird und ob es Verkehrsstaus gibt, ist Sache des Logistikunternehmens. Wenn jeder seine Aufgabe erfüllt, ist die Welt in Ordnung.
5. Fabrik-Routing-Schicht —— AIProviderFactory
Ein switch in CreateProvider instanziiert den passenden Adapter je nach AIProviderType, prüft dabei auch IsConfigured. Das ist der einzige Ort, der “konkrete Typen kennt”, streng isoliert in der Fabrik. Veränderungen dürfen nur in einer Ecke stattfinden, sonst ist alles sauber.
6. Verzeichnis-/UI-Projektionsschicht —— main-professions.yaml
Diese Schicht ist interessant: Sie ist kein Code, sondern Daten.
Die Liste der Hauptberufe (“Ich bin Frontend-Entwickler”, “Ich bin Backend-Entwickler”, “Ich bin Full-Stack-Entwickler” – solche Rollenbilder) wird von der Preset-Datei main-professions.yaml gesteuert, durch HeroPrimaryProfessionPresetProvider gelesen und dann in das Frontend-UI projiziert. Einen neuen Hauptberuf hinzuzufügen erfordert keine einzige Codezeile, es reicht, die YAML zu ändern. Daten statt Code, einfach.
Übrigens ist dies der größte Umbau in HagiCode. Früher gab es ein
AgentCliInstallRegistrygenanntes Code-internes Register; später stellte sich heraus, dass die Wartungskosten zu hoch waren – zu viel Code, müde Entwickler – also wurde alles eingerissen und durch datengesteuerte Vorgehensweise + Gesundheitsüberwachung ersetzt. Das ist auch der Grund, warum HagiCode jetzt Berufstypen schnell erweitern kann.
Wie wird das Installationsproblem gelöst
13 CLI-Tools müssen installiert werden, jede mit einer anderen offiziellen Installationsmethode – das ist ein weiterer Berg.
Unser Ansatz: Docker Compose-Vorinstallation + externes Management als Fallback. Im Docker-Image sind die gängigen CLI-Tools (Claude Code, Codex, Copilot, CodeBuddy, OpenCode, Qoder, Kiro, Kimi, Gemini, Pi) vorinstalliert, Nutzer ziehen das Image und können sofort loslegen, ohne Befehl für Befehl einzutippen. Installiert = gute Laune.
Für CLI-Tools, die separat in der lokalen Umgebung installiert werden müssen, sieht die Matrix der Installationsbefehle ungefähr so aus (gemäß offizieller Dokumentation geprüft):
| CLI | Offizielle Installationsmethode |
|---|---|
| Claude Code | npm install -g @anthropic-ai/claude-code |
| Codex | npm install -g @openai/codex |
| GitHub Copilot | npm install -g @github/copilot |
| CodeBuddy | npm install -g @tencent-ai/codebuddy-code |
| OpenCode | npm i -g opencode-ai@latest |
| Qoder | npm install -g @qoder-ai/qodercli |
| Kiro | curl -fsSL https://cli.kiro.dev/install | bash |
| Kimi | curl -LsSf https://code.kimi.com/install.sh | bash |
| Gemini | npm |
| Hermes | Offizielles Skript, docs-only als Fallback |
| DeepAgents / Reasonix | Siehe jeweilige offizielle Dokumentation |
Auch im Frontend PrimaryProfessionCard.tsx hat sich das geändert – dort gibt es jetzt keinen “CLI installieren”-Button mehr, sondern es wird die CLI-Verfügbarkeit, Versionserkennungsergebnisse und der Hinweis “diese CLI wird extern verwaltet” angezeigt. Mit anderen Worten: Ob die Installation gelingt, liegt in der Verantwortung der Systemschicht, das UI zeigt nur den Status ehrlich zurück. Status und Logik an zwei Orten zu schreiben führt früher oder später zu Inkonsistenzen – warum also die Mühe?
Was muss man tun, um ein neues CLI hinzuzufügen
In der Praxis: In HagiCode ein neues CLI-Tool hinzuzufügen, ist nur wenige Schritte:
- Einen Aufzählungswert in
AIProviderTypehinzufügen - Ein vorhandenes
*CliProviderkopieren und Parameter sowie Ausgabeparsing an das neue CLI anpassen - Eine Routing-Zeile im
switchvonAIProviderFactoryhinzufügen - Falls es in das Hauptberufsverzeichnis soll, in
main-professions.yamlkonfigurieren - Einen Installationsbefehl im Docker-Image hinzufügen (oder externes Management als Fallback)
Der gesamte Prozess erfordert nicht mehr als 200 Zeilen Code an Kernänderungen – das ist der eigentliche Wert dieser Abstraktion. Die Grenzkosten für jedes weitere CLI sind sehr niedrig, der Business-Code muss nicht eine einzige Zeile geändert werden. Alle Wege führen nach Rom, unserer ist nur etwas einfacher zu begehen.
Zusammenfassung
Im Rückblick: “13 CLI-Tools zu integrieren” klingt einschüchternd, aber wenn man es aufbricht, sind es eigentlich nur zwei Fertigkeiten:
Die eine ist Veränderungen zu isolieren – durch AIProviderType-Aufzählung + IAIProvider-Vertrag + dünne Adapter + gemeinsame Laufzeit wird der Business-Code von konkreten CLI-Tools entkoppelt. Die andere ist Konfiguration zu datentisieren – YAML-Presets wie main-professions.yaml steuern Verzeichnis und UI, sodass bei jeder Ergänzung kein Code angefasst werden muss.
Diese Lösung haben wir in der praktischen Entwicklung von HagiCode durch einige Iterationen und Herausforderungen stabilisiert. Wenn Sie an einem ähnlichen System zur “Mehrfach-Provider-Integration” arbeiten, hoffe ich, dass dieser schichtenbasierte Ansatz Ihnen eine Referenz bieten kann. Agent CLI-Tools werden in den nächsten Jahren weiterhin aufkommen, und eine Architektur, die neue CLI-Tools schnell integrieren kann, ist wichtiger als “wie viele aktuell unterstützt werden”…
开始使用 HagiCode
一次安装，几分钟上手
HagiCode for Windows 在 Microsoft Store 免费提供。打开商店即可安装并保持更新；也可以先对比各版本与定价，再决定从哪个渠道开始。