diff --git a/website/content/de/cli/commands.md b/website/content/de/cli/commands.md index 4251fb5e..105276eb 100644 --- a/website/content/de/cli/commands.md +++ b/website/content/de/cli/commands.md @@ -1,198 +1,218 @@ # CLI Commands -Qwen Code unterstützt mehrere eingebaute Befehle, die dir helfen, deine Session zu verwalten, die Oberfläche anzupassen und das Verhalten zu steuern. Diese Befehle beginnen mit einem Schrägstrich (`/`), einem @-Symbol (`@`) oder einem Ausrufezeichen (`!`). +Qwen Code unterstützt mehrere eingebaute Befehle, die dir helfen, deine Sitzung zu verwalten, die Oberfläche anzupassen und das Verhalten zu steuern. Diese Befehle beginnen mit einem Schrägstrich (`/`), einem @-Symbol (`@`) oder einem Ausrufezeichen (`!`). -## Slash commands (`/`) +## Slash-Befehle (`/`) -Slash commands bieten Meta-Ebene-Kontrolle über die CLI selbst. +Slash-Befehle bieten Meta-Ebene-Kontrolle über die CLI selbst. ### Integrierte Befehle - **`/bug`** - - **Beschreibung:** Erstelle ein Issue zu Qwen Code. Standardmäßig wird das Issue im GitHub-Repository für Qwen Code erstellt. Der Text, den du nach `/bug` eingibst, wird zum Titel des erstellten Bugs. Das Standardverhalten von `/bug` kann über die Einstellung `bugCommand` in deiner `.qwen/settings.json` angepasst werden. + - **Beschreibung:** Erstelle ein Issue zu Qwen Code. Standardmäßig wird das Issue im GitHub Repository für Qwen Code erstellt. Der Text, den du nach `/bug` eingibst, wird zum Titel des gemeldeten Bugs. Das Standardverhalten von `/bug` kann über die Einstellung `bugCommand` in deiner `.qwen/settings.json` Datei angepasst werden. - **`/chat`** - - **Beschreibung:** Speichere und setze den Gesprächsverlauf interaktiv fort, um verschiedene Gesprächszweige zu verwalten oder einen früheren Zustand in einer späteren Sitzung wiederherzustellen. + - **Beschreibung:** Speichere und setze Gesprächsverläufe interaktiv fort oder lade einen früheren Zustand aus einer späteren Sitzung wiederher. - **Unterbefehle:** - **`save`** - - **Beschreibung:** Speichert den aktuellen Gesprächsverlauf. Du musst ein `` hinzufügen, um den Zustand zu identifizieren. + - **Beschreibung:** Speichert den aktuellen Gesprächsverlauf. Du musst ein `` hinzufügen, um den Konversationszustand zu identifizieren. - **Verwendung:** `/chat save ` - - **Details zum Speicherort der Checkpoints:** Die Standardverzeichnisse für gespeicherte Chat-Checkpoints sind: - - Linux/macOS: `~/.config/qwen-code/checkpoints/` - - Windows: `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` - - Wenn du `/chat list` ausführst, scannt die CLI nur diese Verzeichnisse, um verfügbare Checkpoints zu finden. - - **Hinweis:** Diese Checkpoints dienen dem manuellen Speichern und Wiederherstellen von Gesprächszuständen. Für automatisch erstellte Checkpoints vor Dateiänderungen, siehe [Checkpointing-Dokumentation](../checkpointing.md). + - **Details zum Speicherort der Checkpoints:** Die Standardpfade für gespeicherte Chat-Checkpoints sind: + - Linux/macOS: `~/.qwen/tmp//` + - Windows: `C:\Users\\.qwen\tmp\\` + - Wenn du `/chat list` ausführst, scannt die CLI nur diese spezifischen Verzeichnisse, um verfügbare Checkpoints zu finden. + - **Hinweis:** Diese Checkpoints dienen dem manuellen Speichern und Wiederherstellen von Gesprächszuständen. Für automatisch erstellte Checkpoints vor Dateiänderungen siehe [Checkpointing Dokumentation](../checkpointing.md). - **`resume`** - - **Beschreibung:** Setzt ein Gespräch von einem früheren Speicherstand fort. + - **Beschreibung:** Setzt eine Konversation von einem früheren Speicherstand fort. - **Verwendung:** `/chat resume ` - **`list`** - - **Beschreibung:** Zeigt verfügbare Tags für die Wiederherstellung von Gesprächszuständen an. + - **Beschreibung:** Zeigt verfügbare Tags zur Wiederherstellung von Chat-Zuständen an. - **`delete`** - - **Beschreibung:** Löscht einen gespeicherten Gesprächs-Checkpoint. + - **Beschreibung:** Löscht einen gespeicherten Konversations-Checkpoint. - **Verwendung:** `/chat delete ` - **`/clear`** - - **Beschreibung:** Leert den Terminalbildschirm, einschließlich des sichtbaren Sitzungsverlaufs und des Scrollbacks innerhalb der CLI. Je nach Implementierung können die zugrunde liegenden Sitzungsdaten (für den Verlauf) erhalten bleiben, aber die Anzeige wird geleert. - - **Tastenkürzel:** Drücke jederzeit **Strg+L**, um den Bildschirm zu leeren. + - **Beschreibung:** Lösche den Terminalbildschirm inklusive sichtbarem Sitzungsverlauf und Scrollback innerhalb der CLI. Je nach Implementierung können die zugrunde liegenden Sitzungsdaten (für die Historie) erhalten bleiben, aber die visuelle Anzeige wird gelöscht. + - **Tastenkürzel:** Drücke jederzeit **Strg+L**, um eine Bereinigung durchzuführen. - **`/summary`** - - **Beschreibung:** Generiert eine umfassende Projektzusammenfassung aus dem aktuellen Gesprächsverlauf und speichert sie in `.qwen/PROJECT_SUMMARY.md`. Diese Zusammenfassung enthält das Gesamtziel, wichtige Erkenntnisse, kürzliche Aktionen und den aktuellen Plan – ideal, um die Arbeit in zukünftigen Sitzungen fortzusetzen. + - **Beschreibung:** Generiere eine umfassende Projektübersicht basierend auf dem aktuellen Gesprächsverlauf und speichere sie in `.qwen/PROJECT_SUMMARY.md`. Diese Zusammenfassung enthält das Gesamtziel, wichtige Erkenntnisse, kürzliche Aktionen und den aktuellen Plan – ideal, um später weiterzuarbeiten. - **Verwendung:** `/summary` - **Funktionen:** - Analysiert den gesamten Gesprächsverlauf, um wichtigen Kontext zu extrahieren - - Erstellt eine strukturierte Markdown-Zusammenfassung mit Abschnitten zu Zielen, Wissen, Aktionen und Plänen - - Speichert automatisch in `.qwen/PROJECT_SUMMARY.md` im Projektstammverzeichnis - - Zeigt Fortschrittsanzeige während der Generierung und beim Speichern - - Integriert sich mit der "Welcome Back"-Funktion für nahtlose Sitzungswiederherstellung - - **Hinweis:** Dieser Befehl erfordert ein aktives Gespräch mit mindestens 2 Nachrichten, um eine aussagekräftige Zusammenfassung zu generieren. + - Erstellt eine strukturierte Markdown-Zusammenfassung mit Abschnitten für Ziele, Wissen, Aktionen und Pläne + - Speichert automatisch unter `.qwen/PROJECT_SUMMARY.md` im Projektstammverzeichnis + - Zeigt Fortschrittsanzeiger während der Generierung und beim Speichern + - Integriert sich mit der Willkommen-zurück-Funktion für nahtlose Sitzungswiederaufnahme + - **Hinweis:** Dieser Befehl benötigt mindestens zwei Nachrichten in einer aktiven Konversation, um eine aussagekräftige Zusammenfassung zu generieren. - **`/compress`** - - **Beschreibung:** Ersetzt den gesamten Chat-Kontext durch eine Zusammenfassung. Dadurch werden Tokens für zukünftige Aufgaben gespart, während eine grobe Übersicht über den bisherigen Verlauf erhalten bleibt. + - **Beschreibung:** Ersetze den gesamten Chat-Kontext durch eine Zusammenfassung. Dadurch werden Tokens für zukünftige Aufgaben eingespart, während eine grobe Übersicht über bisherige Ereignisse erhalten bleibt. - **`/copy`** - - **Beschreibung:** Kopiert die letzte Ausgabe von Qwen Code in die Zwischenablage, um sie einfach zu teilen oder weiterzuverwenden. + - **Beschreibung:** Kopiert die letzte Ausgabe von Qwen Code in deine Zwischenablage, um einfaches Teilen oder Wiederverwenden zu ermöglichen. - **`/directory`** (oder **`/dir`**) - - **Beschreibung:** Verwalte Workspace-Verzeichnisse für Multi-Directory-Unterstützung. + - **Beschreibung:** Verwalte Workspace-Verzeichnisse für Multi-Directory-Support. - **Unterbefehle:** - **`add`**: - - **Beschreibung:** Fügt ein Verzeichnis zum Workspace hinzu. Der Pfad kann absolut oder relativ zum aktuellen Arbeitsverzeichnis sein. Auch Referenzen vom Home-Verzeichnis aus werden unterstützt. - - **Verwendung:** `/directory add ,` - - **Hinweis:** Deaktiviert in restriktiven Sandbox-Profilen. Wenn du diese verwendest, nutze stattdessen `--include-directories` beim Starten der Sitzung. + - **Beschreibung:** Füge ein Verzeichnis zum Workspace hinzu. Der Pfad kann absolut oder relativ zum aktuellen Arbeitsverzeichnis sein. Auch Referenzen vom Home-Verzeichnis aus werden unterstützt. + - **Verwendung:** `/directory add ,` + - **Hinweis:** In restriktiven Sandbox-Profilen deaktiviert. Falls du eines verwendest, nutze stattdessen `--include-directories` beim Starten der Sitzung. - **`show`**: - - **Beschreibung:** Zeigt alle Verzeichnisse an, die mit `/directory add` oder `--include-directories` hinzugefügt wurden. + - **Beschreibung:** Zeige alle Verzeichnisse an, die per `/directory add` und `--include-directories` hinzugefügt wurden. + - **Verwendung:** `/directory show` + +- **`/directory`** (oder **`/dir`**) + - **Beschreibung:** Verwalte Workspace-Verzeichnisse für Multi-Directory-Support. + - **Unterbefehle:** + - **`add`**: + - **Beschreibung:** Füge ein Verzeichnis zum Workspace hinzu. Der Pfad kann absolut oder relativ zum aktuellen Arbeitsverzeichnis sein. Auch Referenzen vom Home-Verzeichnis aus werden unterstützt. + - **Verwendung:** `/directory add ,` + - **Hinweis:** In restriktiven Sandbox-Profilen deaktiviert. Falls du eines verwendest, nutze stattdessen `--include-directories` beim Starten der Sitzung. + - **`show`**: + - **Beschreibung:** Zeige alle Verzeichnisse an, die per `/directory add` und `--include-directories` hinzugefügt wurden. - **Verwendung:** `/directory show` - **`/editor`** - - **Beschreibung:** Öffnet einen Dialog zur Auswahl unterstützter Editoren. + - **Beschreibung:** Öffne einen Dialog zur Auswahl unterstützter Editoren. - **`/extensions`** - - **Beschreibung:** Listet alle aktiven Erweiterungen in der aktuellen Qwen Code-Sitzung auf. Siehe [Qwen Code Extensions](../extension.md). + - **Beschreibung:** Liste alle aktiven Erweiterungen in der aktuellen Qwen Code-Sitzung auf. Siehe [Qwen Code Erweiterungen](../extension.md). - **`/help`** (oder **`/?`**) - - **Beschreibung:** Zeigt Hilfsinformationen zu Qwen Code an, einschließlich verfügbarer Befehle und deren Verwendung. + - **Beschreibung:** Zeige Hilfsinformationen zu Qwen Code an, einschließlich verfügbarer Befehle und deren Nutzung. - **`/mcp`** - - **Beschreibung:** Listet konfigurierte Model Context Protocol (MCP)-Server, deren Verbindungsstatus, Serverdetails und verfügbare Tools auf. + - **Beschreibung:** Liste konfigurierte Model Context Protocol (MCP)-Server, deren Verbindungsstatus, Serverdetails und verfügbare Tools auf. - **Unterbefehle:** - **`desc`** oder **`descriptions`**: - - **Beschreibung:** Zeigt detaillierte Beschreibungen der MCP-Server und Tools an. + - **Beschreibung:** Zeige detaillierte Beschreibungen für MCP-Server und Tools an. - **`nodesc`** oder **`nodescriptions`**: - - **Beschreibung:** Versteckt Tool-Beschreibungen und zeigt nur die Tool-Namen an. + - **Beschreibung:** Blende Tool-Beschreibungen aus und zeige nur die Tool-Namen. - **`schema`**: - - **Beschreibung:** Zeigt das vollständige JSON-Schema für die konfigurierten Parameter des Tools an. - - **Tastenkürzel:** Drücke jederzeit **Strg+T**, um zwischen Anzeige und Ausblenden der Tool-Beschreibungen zu wechseln. + - **Beschreibung:** Zeige das vollständige JSON-Schema für die konfigurierten Parameter des Tools an. + - **Tastenkürzel:** Drücke jederzeit **Strg+T**, um zwischen Anzeigen mit und ohne Tool-Beschreibungen zu wechseln. - **`/memory`** - - **Beschreibung:** Verwalte den instruktiven Kontext der KI (standardmäßig aus `QWEN.md` geladene hierarchische Speicherstruktur; konfigurierbar über `contextFileName`). + - **Beschreibung:** Verwalte den instruktiven Kontext der KI (standardmäßig hierarchisch aus `QWEN.md` geladen; konfigurierbar über `contextFileName`). - **Unterbefehle:** - **`add`**: - - **Beschreibung:** Fügt den folgenden Text dem Speicher der KI hinzu. Verwendung: `/memory add ` + - **Beschreibung:** Fügt den folgenden Text dem Gedächtnis der KI hinzu. Verwendung: `/memory add ` - **`show`**: - - **Beschreibung:** Zeigt den vollständigen, zusammengeführten Inhalt des aktuellen hierarchischen Speichers an, der aus allen Kontextdateien (z. B. `QWEN.md`) geladen wurde. So kannst du den instruktiven Kontext einsehen, der dem Modell zur Verfügung gestellt wird. + - **Beschreibung:** Zeige den vollständigen, zusammengefügten Inhalt des aktuellen hierarchischen Gedächtnisses an, das aus allen Kontextdateien (z.B. `QWEN.md`) geladen wurde. So kannst du den instruktiven Kontext prüfen, der dem Modell bereitgestellt wird. - **`refresh`**: - - **Beschreibung:** Lädt den hierarchischen instruktiven Speicher aus allen Kontextdateien (Standard: `QWEN.md`) neu, die in den konfigurierten Orten (global, Projekt-/Vorgängerordner und Unterverzeichnisse) gefunden werden. Dadurch wird das Modell mit dem neuesten Kontext aktualisiert. - - **Hinweis:** Weitere Informationen zur Funktionsweise von Kontextdateien im hierarchischen Speicher findest du in der [CLI-Konfigurationsdokumentation](./configuration.md#context-files-hierarchical-instructional-context). + - **Beschreibung:** Lade das hierarchische instruktive Gedächtnis neu aus allen Kontextdateien (Standard: `QWEN.md`), die in den konfigurierten Orten gefunden wurden (global, Projekt/Vorfahren und Unterverzeichnisse). Dadurch wird das Modell mit dem neuesten Kontext aktualisiert. + - **Hinweis:** Weitere Details dazu, wie Kontextdateien zum hierarchischen Gedächtnis beitragen, findest du in der [CLI-Konfigurationsdokumentation](./configuration.md#context-files-hierarchical-instructional-context). - **`/restore`** - - **Beschreibung:** Stellt die Projektdateien in den Zustand vor der Ausführung eines Tools wieder her. Besonders nützlich, um Dateiänderungen eines Tools rückgängig zu machen. Ohne Angabe einer `tool_call_id` werden verfügbare Checkpoints zur Wiederherstellung aufgelistet. + - **Beschreibung:** Stellt Projektdateien auf den Zustand direkt vor der Ausführung eines Tools zurück. Besonders nützlich, um Dateiänderungen rückgängig zu machen. Ohne Angabe einer Tool-Aufruf-ID werden verfügbare Checkpoints zur Wiederherstellung aufgelistet. - **Verwendung:** `/restore [tool_call_id]` - - **Hinweis:** Nur verfügbar, wenn die CLI mit der Option `--checkpointing` gestartet wurde oder über [Einstellungen](./configuration.md) konfiguriert ist. Siehe [Checkpointing-Dokumentation](../checkpointing.md) für weitere Details. + - **Hinweis:** Nur verfügbar, wenn die CLI mit der Option `--checkpointing` gestartet wurde oder entsprechend konfiguriert ist ([Einstellungen](./configuration.md)). Siehe [Checkpointing-Dokumentation](../checkpointing.md) für weitere Informationen. - **`/settings`** - - **Beschreibung:** Öffnet den Einstellungseditor, um Qwen Code-Einstellungen anzuzeigen und zu ändern. - - **Details:** Dieser Befehl bietet eine benutzerfreundliche Oberfläche zum Ändern von Einstellungen, die das Verhalten und Aussehen von Qwen Code steuern. Er entspricht dem manuellen Bearbeiten der Datei `.qwen/settings.json`, bietet aber Validierung und Hilfestellung zur Fehlervermeidung. - - **Verwendung:** Führe einfach `/settings` aus, und der Editor öffnet sich. Du kannst dann nach Einstellungen suchen, ihre aktuellen Werte anzeigen und sie nach Belieben ändern. Einige Änderungen werden sofort übernommen, andere erfordern einen Neustart. + - **Beschreibung:** Öffne den Einstellungseditor, um Qwen Code-Einstellungen anzusehen und zu ändern. + - **Details:** Dieser Befehl bietet eine benutzerfreundliche Oberfläche zum Ändern von Einstellungen, die das Verhalten und Aussehen von Qwen Code steuern. Er entspricht dem manuellen Bearbeiten der `.qwen/settings.json`-Datei, jedoch mit Validierung und Unterstützung zur Fehlervermeidung. + - **Verwendung:** Führe einfach `/settings` aus, dann öffnet sich der Editor. Du kannst dann nach bestimmten Einstellungen suchen, ihre aktuellen Werte anzeigen und sie nach Belieben ändern. Einige Änderungen werden sofort übernommen, andere erfordern einen Neustart. - **`/stats`** - - **Beschreibung:** Zeigt detaillierte Statistiken zur aktuellen Qwen Code-Sitzung an, darunter Token-Nutzung, eingesparte gecachte Tokens (falls verfügbar) und Sitzungsdauer. Hinweis: Informationen zu gecachten Tokens werden nur angezeigt, wenn diese tatsächlich verwendet werden – dies geschieht derzeit nur bei Authentifizierung per API-Schlüssel, nicht bei OAuth. + - **Beschreibung:** Zeige detaillierte Statistiken zur aktuellen Qwen Code-Sitzung an, darunter Token-Nutzung, eingesparte gecachte Tokens (falls verfügbar) und Sitzungsdauer. Hinweis: Informationen zu gecachten Tokens werden nur angezeigt, wenn solche Tokens verwendet werden – dies geschieht momentan bei API-Key-Authentifizierung, nicht jedoch bei OAuth-Authentifizierung. - [**`/theme`**](./themes.md) - - **Beschreibung:** Öffnet einen Dialog, in dem du das visuelle Theme von Qwen Code ändern kannst. + - **Beschreibung:** Öffne einen Dialog, mit dem du das visuelle Theme von Qwen Code ändern kannst. - **`/auth`** - - **Beschreibung:** Öffnet einen Dialog, in dem du die Authentifizierungsmethode ändern kannst. + - **Beschreibung:** Öffne einen Dialog, mit dem du die Authentifizierungsmethode ändern kannst. + +- **`/approval-mode`** + - **Beschreibung:** Ändere den Genehmigungsmodus für Tool-Nutzung. + - **Verwendung:** `/approval-mode [Modus] [--session|--project|--user]` + - **Verfügbare Modi:** + - **`plan`**: Nur analysieren; keine Dateiänderungen oder Shell-Befehle ausführen + - **`default`**: Genehmigung für Dateiänderungen oder Shell-Befehle erforderlich + - **`auto-edit`**: Automatische Genehmigung für Dateiänderungen + - **`yolo`**: Automatische Genehmigung aller Tools + - **Beispiele:** + - `/approval-mode plan --project` (Plan-Modus dauerhaft für dieses Projekt festlegen) + - `/approval-mode yolo --user` (YOLO-Modus dauerhaft für diesen Benutzer projektübergreifend festlegen) - **`/about`** - - **Beschreibung:** Zeigt Versionsinformationen an. Bitte teile diese Informationen mit, wenn du ein Issue erstellst. + - **Beschreibung:** Zeige Versionsinformationen an. Bitte teile diese Informationen mit, wenn du Issues meldest. - **`/agents`** - - **Beschreibung:** Verwalte spezialisierte KI-Subagents für fokussierte Aufgaben. Subagents sind unabhängige KI-Assistenten mit spezifischer Expertise und Tool-Zugriff. + - **Beschreibung:** Verwalte spezialisierte KI-Subagenten für fokussierte Aufgaben. Subagenten sind unabhängige KI-Assistenten mit spezifischer Expertise und Zugriff auf bestimmte Tools. - **Unterbefehle:** - **`create`**: - - **Beschreibung:** Startet einen interaktiven Assistenten zum Erstellen eines neuen Subagents. Der Assistent führt dich durch die Auswahl des Speicherorts, KI-gestützte Prompt-Generierung, Tool-Auswahl und visuelle Anpassung. + - **Beschreibung:** Starte einen interaktiven Assistenten zum Erstellen eines neuen Subagenten. Der Assistent führt dich durch Standortauswahl, KI-gesteuerte Promptgenerierung, Toolauswahl und visuelle Anpassung. - **Verwendung:** `/agents create` - **`manage`**: - - **Beschreibung:** Öffnet einen interaktiven Verwaltungsdialog zum Anzeigen, Bearbeiten und Löschen bestehender Subagents. Zeigt sowohl Projekt- als auch benutzerdefinierte Agents an. + - **Beschreibung:** Öffne einen interaktiven Verwaltungsdialog zum Anzeigen, Bearbeiten und Löschen bestehender Subagenten. Zeigt sowohl Projekt- als auch Benutzerebene-Agenten an. - **Verwendung:** `/agents manage` - **Speicherorte:** - - **Projekt-Ebene:** `.qwen/agents/` (geteilt mit dem Team, hat Vorrang) - - **Benutzer-Ebene:** `~/.qwen/agents/` (persönliche Agents, projektübergreifend verfügbar) - - **Hinweis:** Weitere Informationen zum Erstellen und Verwalten von Subagents findest du in der [Subagents-Dokumentation](../subagents.md). + - **Projektebene:** `.qwen/agents/` (mit Team geteilt, hat Vorrang) + - **Benutzerebene:** `~/.qwen/agents/` (persönliche Agenten, projektübergreifend verfügbar) + - **Hinweis:** Detaillierte Informationen zum Erstellen und Verwalten von Subagenten findest du in der [Subagenten-Dokumentation](../subagents.md). - [**`/tools`**](../tools/index.md) - - **Beschreibung:** Zeigt eine Liste der aktuell in Qwen Code verfügbaren Tools an. + - **Beschreibung:** Zeige eine Liste der aktuell in Qwen Code verfügbaren Tools an. + - **Verwendung:** `/tools [desc]` - **Unterbefehle:** - **`desc`** oder **`descriptions`**: - - **Beschreibung:** Zeigt detaillierte Beschreibungen jedes Tools an, einschließlich Name und vollständiger Beschreibung, wie sie dem Modell zur Verfügung gestellt wird. + - **Beschreibung:** Zeige detaillierte Beschreibungen jedes Tools an, inklusive Name und vollständiger Beschreibung, wie sie dem Modell bereitgestellt wird. - **`nodesc`** oder **`nodescriptions`**: - - **Beschreibung:** Versteckt Tool-Beschreibungen und zeigt nur die Tool-Namen an. + - **Beschreibung:** Blende Tool-Beschreibungen aus und zeige nur die Tool-Namen. - **`/privacy`** - - **Beschreibung:** Zeigt den Datenschutzhinweis an und ermöglicht es Nutzern, auszuwählen, ob sie der Datenerhebung zur Verbesserung des Dienstes zustimmen. + - **Beschreibung:** Zeige den Datenschutzhinweis an und erlaube Nutzern, auszuwählen, ob sie der Erfassung ihrer Daten zur Verbesserung des Dienstes zustimmen. - **`/quit-confirm`** - - **Beschreibung:** Zeigt einen Bestätigungsdialog vor dem Beenden von Qwen Code an, in dem du auswählen kannst, wie mit der aktuellen Sitzung umgegangen werden soll. + - **Beschreibung:** Zeige einen Bestätigungsdialog vor dem Beenden von Qwen Code an, sodass du entscheiden kannst, wie mit deiner aktuellen Sitzung umgegangen werden soll. - **Verwendung:** `/quit-confirm` - **Funktionen:** - - **Sofort beenden:** Beendet ohne Speichern (entspricht `/quit`) - - **Zusammenfassung generieren und beenden:** Erstellt eine Projektzusammenfassung mit `/summary` vor dem Beenden - - **Gespräch speichern und beenden:** Speichert das aktuelle Gespräch mit einem automatisch generierten Tag vor dem Beenden - - **Tastenkürzel:** Drücke **Strg+C** zweimal, um den Beendigungsdialog zu öffnen + - **Sofort beenden:** Beenden ohne etwas zu speichern (entspricht `/quit`) + - **Zusammenfassung generieren und beenden:** Erstelle eine Projektzusammenfassung mittels `/summary` vor dem Beenden + - **Konversation speichern und beenden:** Speichere die aktuelle Konversation mit einem automatisch generierten Tag vor dem Beenden + - **Tastenkürzel:** Drücke zweimal **Strg+C**, um den Beendigungsbestätigungsdialog auszulösen - **Hinweis:** Dieser Befehl wird automatisch ausgelöst, wenn du einmal Strg+C drückst, um versehentliches Beenden zu verhindern. - **`/quit`** (oder **`/exit`**) - - **Beschreibung:** Beendet Qwen Code sofort ohne Bestätigungsdialog. + - **Beschreibung:** Beende Qwen Code sofort ohne Bestätigungsdialog. - **`/vim`** - - **Beschreibung:** Schaltet den Vim-Modus ein oder aus. Im Vim-Modus unterstützt der Eingabebereich vim-ähnliche Navigations- und Bearbeitungsbefehle in den Modi NORMAL und INSERT. + - **Beschreibung:** Schalte den Vim-Modus ein oder aus. Im aktivierten Zustand unterstützt der Eingabebereich Vim-artige Navigations- und Bearbeitungsbefehle sowohl im NORMAL- als auch im INSERT-Modus. - **Funktionen:** - - **NORMAL-Modus:** Navigation mit `h`, `j`, `k`, `l`; Wortwechsel mit `w`, `b`, `e`; Zeilenanfang/-ende mit `0`, `$`, `^`; gehe zu bestimmten Zeilen mit `G` (oder `gg` für erste Zeile) - - **INSERT-Modus:** Standard-Texteingabe mit Escape zum Wechsel zurück in den NORMAL-Modus + - **NORMAL-Modus:** Navigation mit `h`, `j`, `k`, `l`; Wortweise Springen mit `w`, `b`, `e`; Zeilenanfang/-ende mit `0`, `$`, `^`; Gehe zu bestimmten Zeilen mit `G` (oder `gg` für erste Zeile) + - **INSERT-Modus:** Standardtexteingabe mit Escape-Taste zum Zurückkehren in den NORMAL-Modus - **Bearbeitungsbefehle:** Löschen mit `x`, Ändern mit `c`, Einfügen mit `i`, `a`, `o`, `O`; komplexe Operationen wie `dd`, `cc`, `dw`, `cw` - - **Zählerunterstützung:** Befehle mit Zahlen als Präfix (z. B. `3h`, `5w`, `10G`) - - **Letzten Befehl wiederholen:** Nutze `.` zur Wiederholung der letzten Bearbeitung - - **Persistente Einstellung:** Die Vim-Modus-Einstellung wird in `~/.qwen/settings.json` gespeichert und zwischen Sitzungen wiederhergestellt - - **Statusanzeige:** Wenn aktiviert, zeigt `[NORMAL]` oder `[INSERT]` in der Fußzeile an - -- **`/init`** - - **Beschreibung:** Analysiert das aktuelle Verzeichnis und erstellt standardmäßig eine `QWEN.md`-Kontextdatei (oder den durch `contextFileName` festgelegten Dateinamen). Falls bereits eine nicht-leere Datei existiert, werden keine Änderungen vorgenommen. Der Befehl legt eine leere Datei an und fordert das Modell auf, sie mit projektspezifischen Anweisungen zu füllen. + - **Anzahl-Support:** Präfixe mit Zahlen (z.B. `3h`, `5w`, `10G`) + - **Letzten Befehl wiederholen:** Mit `.` den letzten Bearbeitungsvorgang wiederholen + - **Persistente Einstellung:** Vim -### Custom Commands +### Benutzerdefinierte Befehle -Für einen schnellen Einstieg siehe das [Beispiel](#example-a-pure-function-refactoring-command) unten. +Für einen schnellen Einstieg siehe das [Beispiel](#beispiel-ein-refactoring-befehl-als-reine-funktion) unten. -Custom Commands ermöglichen es dir, deine favorisierten oder am häufigsten verwendeten Prompts als persönliche Shortcuts innerhalb von Qwen Code zu speichern und wiederzuverwenden. Du kannst Commands erstellen, die spezifisch für ein einzelnes Projekt sind, oder Commands, die global in allen deinen Projekten verfügbar sind – so wird dein Workflow optimiert und Konsistenz gewährleistet. +Benutzerdefinierte Befehle ermöglichen es dir, deine favorisierten oder am häufigsten verwendeten Prompts als persönliche Shortcuts innerhalb von Qwen Code zu speichern und wiederzuverwenden. Du kannst Befehle erstellen, die spezifisch für ein einzelnes Projekt sind, oder Befehle, die global in allen deinen Projekten verfügbar sind – so wird dein Workflow optimiert und Konsistenz gewährleistet. #### Dateispeicherorte & Priorität Qwen Code erkennt Befehle aus zwei Speicherorten, die in einer bestimmten Reihenfolge geladen werden: -1. **Benutzerbefehle (Global):** Befinden sich in `~/.qwen/commands/`. Diese Befehle sind in jedem Projekt verfügbar, an dem du arbeitest. -2. **Projektbefehle (Lokal):** Befinden sich in `/.qwen/commands/`. Diese Befehle sind spezifisch für das aktuelle Projekt und können in die Versionskontrolle eingecheckt werden, um sie mit deinem Team zu teilen. +1. **Benutzerbefehle (Global):** Diese befinden sich in `~/.qwen/commands/`. Diese Befehle sind in jedem Projekt verfügbar, an dem Sie arbeiten. +2. **Projektbefehle (Lokal):** Diese befinden sich in `/.qwen/commands/`. Diese Befehle sind spezifisch für das aktuelle Projekt und können in die Versionskontrolle eingecheckt werden, um sie mit Ihrem Team zu teilen. -Wenn ein Befehl im Projektverzeichnis denselben Namen wie ein Befehl im Benutzerverzeichnis hat, wird **immer der Projektbefehl verwendet**. Dadurch können Projekte globale Befehle mit projektspezifischen Versionen überschreiben. +Wenn ein Befehl im Projektverzeichnis denselben Namen wie ein Befehl im Benutzerverzeichnis hat, wird **immer der Projektbefehl verwendet.** Dadurch können Projekte globale Befehle mit projektspezifischen Versionen überschreiben. -#### Benennung und Namespacing +#### Benennung und Namensräume -Der Name eines Befehls ergibt sich aus seinem Dateipfad relativ zum `commands`-Verzeichnis. Unterverzeichnisse dienen zur Erstellung von namespaced Befehlen, wobei der Pfadtrenner (`/` oder `\`) in einen Doppelpunkt (`:`) umgewandelt wird. +Der Name eines Befehls ergibt sich aus seinem Dateipfad relativ zum `commands`-Verzeichnis. Unterverzeichnisse dienen zur Erstellung von Befehlen mit Namensräumen (Namespaces), wobei der Pfadtrenner (`/` oder `\`) in einen Doppelpunkt (`:`) umgewandelt wird. - Eine Datei unter `~/.qwen/commands/test.toml` wird zum Befehl `/test`. -- Eine Datei unter `/.qwen/commands/git/commit.toml` wird zum namespaced Befehl `/git:commit`. +- Eine Datei unter `/.qwen/commands/git/commit.toml` wird zum Befehl `/git:commit` mit Namensraum. #### TOML-Dateiformat (v1) -Deine Befehlsdefinitionsdateien müssen im TOML-Format geschrieben und mit der Dateiendung `.toml` versehen werden. +Deine Befehlsdefinitionsdateien müssen im TOML-Format geschrieben und mit der Dateierweiterung `.toml` versehen werden. ##### Erforderliche Felder @@ -200,7 +220,7 @@ Deine Befehlsdefinitionsdateien müssen im TOML-Format geschrieben und mit der D ##### Optionale Felder -- `description` (String): Eine kurze, einzeilige Beschreibung dessen, was der Befehl bewirkt. Dieser Text wird neben deinem Befehl im `/help`-Menü angezeigt. **Wenn du dieses Feld weglässt, wird automatisch eine allgemeine Beschreibung aus dem Dateinamen generiert.** +- `description` (String): Eine kurze, einzeilige Beschreibung dessen, was der Befehl bewirkt. Dieser Text wird neben deinem Befehl im `/help`-Menü angezeigt. **Falls du dieses Feld weglässt, wird automatisch eine generische Beschreibung aus dem Dateinamen erzeugt.** #### Umgang mit Argumenten @@ -221,17 +241,17 @@ Wenn sie im Hauptteil des Prompts verwendet wird, werden die Argumente exakt so ```toml ```markdown -# Aufgerufen via: /git:fix "Button is misaligned" +# Aufgerufen über: /git:fix "Button ist falsch ausgerichtet" -description = "Generiert einen Fix für ein gegebenes Problem." +description = "Erzeugt einen Fix für ein gegebenes Problem." prompt = "Bitte stelle einen Code-Fix für das hier beschriebene Problem bereit: {{args}}." ``` -Das Modell erhält: `Bitte stelle einen Code-Fix für das hier beschriebene Problem bereit: "Button is misaligned".` +Das Modell erhält: `Bitte stelle einen Code-Fix für das hier beschriebene Problem bereit: "Button ist falsch ausgerichtet".` **B. Verwendung von Argumenten in Shell-Befehlen (Innerhalb von `!{...}`-Blöcken)** -Wenn du `{{args}}` innerhalb eines Shell-Injection-Blocks (`!{...}`) verwendest, werden die Argumente automatisch **shell-escaped** vor der Ersetzung. Dadurch kannst du Argumente sicher an Shell-Befehle übergeben, wodurch sichergestellt ist, dass der resultierende Befehl syntaktisch korrekt und sicher ist und Command-Injection-Schwachstellen verhindert werden. +Wenn du `{{args}}` innerhalb eines Shell-Injection-Blocks (`!{...}`) verwendest, werden die Argumente automatisch **shell-escaped** vor der Ersetzung. Dadurch kannst du Argumente sicher an Shell-Befehle übergeben, wodurch sichergestellt wird, dass der resultierende Befehl syntaktisch korrekt und sicher ist und gleichzeitig Command-Injection-Schwachstellen verhindert werden. **Beispiel (`/grep-code.toml`):** @@ -248,19 +268,19 @@ Wenn du `/grep-code It's complicated` ausführst: 1. Die CLI erkennt, dass `{{args}}` sowohl außerhalb als auch innerhalb von `!{...}` verwendet wird. 2. Außerhalb: Das erste `{{args}}` wird roh durch `It's complicated` ersetzt. -3. Innerhalb: Das zweite `{{args}}` wird durch die escaped-Version ersetzt (z. B. unter Linux: `"It's complicated"`). +3. Innerhalb: Das zweite `{{args}}` wird durch die escapte Version ersetzt (z. B. unter Linux: `"It's complicated"`). 4. Der ausgeführte Befehl lautet `grep -r "It's complicated" .`. 5. Die CLI fordert dich auf, diesen exakten, sicheren Befehl vor der Ausführung zu bestätigen. 6. Der finale Prompt wird gesendet. ``` -##### 2. Standardargument-Handling +##### 2. Standardargument-Verarbeitung -Falls dein `prompt` den speziellen Platzhalter `{{args}}` **nicht** enthält, verwendet die CLI ein Standardverhalten für die Argumentverarbeitung. +Falls dein `prompt` den speziellen Platzhalter `{{args}}` **nicht** enthält, verwendet die CLI ein Standardverhalten zur Verarbeitung von Argumenten. -Wenn du der Kommandozeile Argumente übergibst (z. B. `/mycommand arg1`), wird die CLI den vollständigen Befehl, den du eingegeben hast, am Ende des Prompts anfügen, getrennt durch zwei Zeilenumbrüche. Dadurch kann das Modell sowohl die ursprünglichen Anweisungen als auch die spezifischen Argumente sehen, die du gerade übergeben hast. +Wenn du der Kommandozeile Argumente übergibst (z. B. `/mycommand arg1`), wird die CLI den vollständigen Befehl, den du eingegeben hast, am Ende des Prompts mit zwei Zeilenumbrüchen getrennt anhängen. Dadurch kann das Modell sowohl die ursprünglichen Anweisungen als auch die spezifischen Argumente sehen, die du gerade übergeben hast. -Falls du **keine** Argumente übergibst (z. B. `/mycommand`), wird der Prompt exakt so an das Modell gesendet, wie er ist – ohne etwas anzuhängen. +Falls du **keine** Argumente übergibst (z. B. `/mycommand`), wird der Prompt exakt so, wie er ist, an das Modell gesendet – ohne etwas anzuhängen. **Beispiel (`changelog.toml`):** @@ -270,14 +290,15 @@ Dieses Beispiel zeigt, wie du einen robusten Befehl erstellst, indem du eine Rol # In: /.qwen/commands/changelog.toml -# Aufgerufen über: /changelog 1.2.0 added "Support for default argument parsing." +```markdown +# Aufgerufen via: /changelog 1.2.0 added "Support for default argument parsing." description = "Fügt einen neuen Eintrag zur CHANGELOG.md-Datei des Projekts hinzu." prompt = """ # Aufgabe: Changelog aktualisieren -Du bist ein erfahrener Maintainer dieses Softwareprojekts. Ein Benutzer hat einen Befehl ausgeführt, um einen neuen Eintrag zum Changelog hinzuzufügen. +Du bist ein erfahrener Maintainer dieses Softwareprojekts. Ein Benutzer hat einen Befehl aufgerufen, um einen neuen Eintrag zum Changelog hinzuzufügen. **Der rohe Befehl des Benutzers steht unterhalb deiner Anweisungen.** @@ -285,7 +306,8 @@ Deine Aufgabe ist es, ``, `` und `` aus der Einga ## Erwartetes Format Der Befehl folgt diesem Format: `/changelog ` -- `` muss einer der folgenden Werte sein: "added", "changed", "fixed", "removed"." +- `` muss einer der folgenden Werte sein: "added", "changed", "fixed", "removed". +``` ```markdown ## Verhalten @@ -296,26 +318,26 @@ Der Befehl folgt diesem Format: `/changelog ` 5. Halte dich strikt an das "Keep a Changelog"-Format. """ -Wenn du `/changelog 1.2.0 added "New feature"` ausführst, wird der finale Text, der an das Modell gesendet wird, der ursprüngliche Prompt gefolgt von zwei Zeilenumbrüchen und dem von dir eingegebenen Befehl sein. +Wenn du `/changelog 1.2.0 added "New feature"` ausführst, wird der endgültige Text, der an das Modell gesendet wird, der ursprüngliche Prompt gefolgt von zwei Zeilenumbrüchen und dem von dir eingegebenen Befehl sein. ``` ##### 3. Shell-Befehle mit `!{...}` ausführen -Du kannst deine Befehle dynamisch gestalten, indem du Shell-Befehle direkt innerhalb deines `prompt` ausführst und deren Ausgabe einfügst. Das ist ideal, um Kontext aus deiner lokalen Umgebung zu sammeln, wie z. B. den Inhalt von Dateien zu lesen oder den Status von Git abzufragen. +Du kannst deine Befehle dynamisch gestalten, indem du Shell-Befehle direkt innerhalb deines `prompt` ausführst und deren Ausgabe einfügst. Das ist ideal, um Kontext aus deiner lokalen Umgebung zu sammeln, wie z. B. den Inhalt von Dateien zu lesen oder den Status von Git zu prüfen. Wenn ein benutzerdefinierter Befehl versucht, einen Shell-Befehl auszuführen, fordert Qwen Code dich nun zur Bestätigung auf, bevor er fortfährt. Dies ist eine Sicherheitsmaßnahme, um sicherzustellen, dass nur beabsichtigte Befehle ausgeführt werden können. -**So funktioniert's:** +**So funktioniert es:** 1. **Befehle einfügen:** Verwende die `!{...}`-Syntax. -2. **Argument-Substitution:** Falls `{{args}}` innerhalb des Blocks vorhanden ist, wird es automatisch shell-escaped (siehe [Kontextabhängige Injection](#1-context-aware-injection-with-args) oben). -3. **Robuste Parsing-Funktion:** Der Parser verarbeitet korrekt komplexe Shell-Befehle mit verschachtelten Klammern, wie z. B. JSON-Payloads. +2. **Argument-Substitution:** Falls `{{args}}` innerhalb des Blocks vorhanden ist, wird es automatisch für die Shell escaped (siehe [Kontextabhängige Injection](#1-context-aware-injection-with-args) oben). +3. **Robuste Parsing-Funktion:** Der Parser verarbeitet korrekt komplexe Shell-Befehle mit verschachtelten Klammern, wie z. B. JSON-Payloads. **Hinweis:** Der Inhalt innerhalb von `!{...}` muss ausgeglichene Klammern (`{` und `}`) enthalten. Wenn du einen Befehl mit unausgeglichenen Klammern ausführen musst, solltest du ihn in eine externe Skriptdatei auslagern und das Skript innerhalb des `!{...}`-Blocks aufrufen. 4. **Sicherheitsprüfung und Bestätigung:** Die CLI führt eine Sicherheitsprüfung des finalen, aufgelösten Befehls durch (nachdem die Argumente escaped und ersetzt wurden). Ein Dialog zeigt die exakten Befehle an, die ausgeführt werden sollen. -5. **Ausführung und Fehlerberichterstattung:** Der Befehl wird ausgeführt. Falls der Befehl fehlschlägt, enthält die in den Prompt eingefügte Ausgabe die Fehlermeldungen (stderr), gefolgt von einer Statuszeile, z. B. `[Shell command exited with code 1]`. Das hilft dem Modell, den Kontext des Fehlers zu verstehen. +5. **Ausführung und Fehlerberichterstattung:** Der Befehl wird ausgeführt. Falls der Befehl fehlschlägt, enthält die in das Prompt eingefügte Ausgabe die Fehlermeldungen (stderr), gefolgt von einer Statuszeile, z. B. `[Shell command exited with code 1]`. Dies hilft dem Modell, den Kontext des Fehlers zu verstehen. **Beispiel (`git/commit.toml`):** -Dieser Befehl ruft den gestageten Git-Diff ab und verwendet ihn, um das Modell eine Commit-Nachricht schreiben zu lassen. +Dieser Befehl ruft den gestageten Git-Diff ab und verwendet ihn, um das Modell zu bitten, eine Commit-Nachricht zu schreiben. ````toml @@ -323,7 +345,7 @@ Dieser Befehl ruft den gestageten Git-Diff ab und verwendet ihn, um das Modell e # Aufgerufen via: /git:commit -description = "Generiert eine Git Commit-Nachricht basierend auf den gestageten Änderungen." +description = "Generiert eine Git Commit-Nachricht basierend auf den gestagten Änderungen." # Der Prompt verwendet !{...}, um den Befehl auszuführen und dessen Ausgabe einzufügen. prompt = """ @@ -337,9 +359,47 @@ Bitte generiere eine Conventional Commit-Nachricht basierend auf dem folgenden g ```` -Wenn du `/git:commit` ausführst, führt die CLI zuerst `git diff --staged` aus, ersetzt dann `!{git diff --staged}` mit der Ausgabe dieses Befehls, bevor der finale, vollständige Prompt an das Modell gesendet wird. +Wenn du `/git:commit` ausführst, führt die CLI zuerst `git diff --staged` aus, ersetzt dann `!{git diff --staged}` mit der Ausgabe dieses Befehls, bevor sie den finalen, vollständigen Prompt an das Modell sendet. + +##### 4. Dateiinhalte mit `@{...}` einfügen + +Du kannst den Inhalt einer Datei oder eine Verzeichnisliste direkt in deinen Prompt einbetten, indem du die `@{...}`-Syntax verwendest. Das ist besonders nützlich, um Befehle zu erstellen, die auf bestimmten Dateien arbeiten. + +**So funktioniert's:** + +- **Datei-Injektion**: `@{path/to/file.txt}` wird durch den Inhalt von `file.txt` ersetzt. +- **Multimodale Unterstützung**: Wenn der Pfad auf ein unterstütztes Bild (z. B. PNG, JPEG), PDF, Audio- oder Videodatei zeigt, wird diese korrekt kodiert und als multimodaler Input injiziert. Andere Binärdateien werden übersprungen. +- **Verzeichnis-Auflistung**: `@{path/to/dir}` wird durchlaufen und jede Datei innerhalb des Verzeichnisses sowie aller Unterverzeichnisse wird in den Prompt eingefügt. Dabei werden `.gitignore` und `.qwenignore` berücksichtigt, sofern aktiviert. +- **Workspace-bezogen**: Der Befehl sucht den Pfad im aktuellen Verzeichnis sowie in anderen Workspace-Verzeichnissen. Absolute Pfade sind erlaubt, solange sie sich innerhalb des Workspaces befinden. +- **Reihenfolge der Verarbeitung**: Die Injektion von Dateiinhalten mit `@{...}` erfolgt _vor_ Shell-Befehlen (`!{...}`) und Argument-Substitution (`{{args}}`). +- **Parsing**: Der Parser erwartet, dass der Inhalt innerhalb von `@{...}` (also der Pfad) geschlossene geschweifte Klammern (`{` und `}`) verwendet. + +**Beispiel (`review.toml`):** + +Dieser Befehl injiziert den Inhalt einer _festgelegten_ Best Practices-Datei (`docs/best-practices.md`) und verwendet die vom Nutzer übergebenen Argumente, um Kontext für den Review bereitzustellen. + +```toml + +```markdown +# In: /.qwen/commands/review.toml + +# Aufgerufen via: /review FileCommandLoader.ts + +description = "Überprüft den bereitgestellten Kontext anhand eines Best Practices Leitfadens." +prompt = """ +Du bist ein erfahrener Code-Reviewer. + +Deine Aufgabe ist es, {{args}} zu reviewen. + +Verwende die folgenden Best Practices für dein Review: + +@{docs/best-practices.md} +""" + +Wenn du `/review FileCommandLoader.ts` ausführst, wird der Platzhalter `@{docs/best-practices.md}` durch den Inhalt dieser Datei ersetzt und `{{args}}` durch den von dir angegebenen Text, bevor der finale Prompt an das Modell gesendet wird. --- +``` #### Beispiel: Ein "Pure Function" Refactoring Command @@ -347,7 +407,7 @@ Erstellen wir ein globales Command, das das Modell bittet, einen Code-Abschnitt **1. Erstelle die Datei und Verzeichnisse:** -Stelle zunächst sicher, dass das User Commands Verzeichnis existiert, erstelle dann ein `refactor` Unterverzeichnis zur Organisation und die finale TOML Datei. +Stelle zunächst sicher, dass das Verzeichnis für User Commands existiert, erstelle dann ein `refactor` Unterverzeichnis zur Organisation und die finale TOML-Datei. ```bash mkdir -p ~/.qwen/commands/refactor @@ -369,16 +429,17 @@ description = "Fordert das Modell auf, den aktuellen Kontext in eine reine Funkt prompt = """ Bitte analysiere den Code, den ich im aktuellen Kontext bereitgestellt habe. -Strukturiere ihn in eine reine Funktion um. +Strukturiere ihn in eine reine Funktion (pure function) um. Deine Antwort sollte Folgendes enthalten: 1. Den umstrukturierten Codeblock der reinen Funktion. -2. Eine kurze Erklärung der wichtigsten Änderungen und warum diese zur Reinheit beitragen. +2. Eine kurze Erklärung der wichtigsten Änderungen und warum diese zur Reinheit (Purity) beitragen. """ +``` **3. Befehl ausführen:** -Das war's! Du kannst jetzt deinen Befehl in der CLI ausführen. Zuerst fügst du vielleicht eine Datei zum Kontext hinzu und rufst dann deinen Befehl auf: +Das war's! Du kannst deinen Befehl jetzt in der CLI ausführen. Zuerst fügst du vielleicht eine Datei zum Kontext hinzu und rufst dann deinen Befehl auf: ``` > @my-messy-function.js @@ -393,34 +454,34 @@ Qwen Code führt dann die mehrzeilige Eingabeaufforderung aus, die in deiner TOM At-Befehle werden verwendet, um den Inhalt von Dateien oder Verzeichnissen als Teil deines Prompts an das Modell zu übergeben. Diese Befehle enthalten git-basierte Filterung. - **`@`** - - **Beschreibung:** Fügt den Inhalt der angegebenen Datei oder mehrerer Dateien in deinen aktuellen Prompt ein. Das ist nützlich, um Fragen zu spezifischem Code, Text oder ganzen Dateisammlungen zu stellen. + - **Beschreibung:** Fügt den Inhalt der angegebenen Datei oder mehrerer Dateien in deinen aktuellen Prompt ein. Das ist nützlich, wenn du Fragen zu bestimmtem Code, Text oder Sammlungen von Dateien stellen willst. - **Beispiele:** - `@path/to/your/file.txt Erkläre diesen Text.` - `@src/my_project/ Fasse den Code in diesem Verzeichnis zusammen.` - `Worum geht es in dieser Datei? @README.md` - **Details:** - - Wenn ein Pfad zu einer einzelnen Datei angegeben wird, wird deren Inhalt gelesen. - - Wenn ein Pfad zu einem Verzeichnis angegeben wird, versucht der Befehl, den Inhalt der Dateien innerhalb dieses Verzeichnisses und aller Unterverzeichnisse zu lesen. + - Wenn ein Pfad zu einer einzelnen Datei angegeben wird, wird deren Inhalt eingelesen. + - Wenn ein Pfad zu einem Verzeichnis angegeben wird, versucht der Befehl, den Inhalt aller Dateien innerhalb dieses Verzeichnisses und seiner Unterverzeichnisse einzulesen. - Leerzeichen in Pfaden sollten mit einem Backslash maskiert werden (z. B. `@Meine\ Dokumente/datei.txt`). - - Intern verwendet der Befehl das `read_many_files`-Tool. Der Inhalt wird abgerufen und dann in deinen Prompt eingefügt, bevor er an das Modell gesendet wird. - - **Git-basierte Filterung:** Standardmäßig werden git-ignorierte Dateien (wie `node_modules/`, `dist/`, `.env`, `.git/`) ausgeschlossen. Dieses Verhalten kann über die `fileFiltering`-Einstellungen angepasst werden. - - **Dateitypen:** Der Befehl ist für textbasierte Dateien gedacht. Auch wenn versucht wird, beliebige Dateien zu lesen, könnten binäre oder sehr große Dateien vom zugrunde liegenden `read_many_files`-Tool übersprungen oder gekürzt werden, um Leistung und Relevanz zu gewährleisten. Das Tool zeigt an, wenn Dateien übersprungen wurden. - - **Ausgabe:** Die CLI zeigt eine Tool-Aufruf-Nachricht an, die angibt, dass `read_many_files` verwendet wurde, sowie eine Nachricht mit Details zum Status und den verarbeiteten Pfaden. + - Intern nutzt der Befehl das `read_many_files`-Tool. Der Inhalt wird abgerufen und dann vor dem Senden an das Modell in deinen Query eingefügt. + - **Git-basierte Filterung:** Standardmäßig werden git-ignorierte Dateien (wie `node_modules/`, `dist/`, `.env`, `.git/`) ausgeschlossen. Dieses Verhalten kann über die `fileFiltering`-Einstellungen geändert werden. + - **Dateitypen:** Der Befehl ist für textbasierte Dateien gedacht. Auch wenn versucht wird, beliebige Dateien einzulesen, könnten binäre oder sehr große Dateien vom zugrunde liegenden `read_many_files`-Tool übersprungen oder gekürzt werden, um Performance und Relevanz sicherzustellen. Das Tool zeigt an, wenn Dateien übersprungen wurden. + - **Ausgabe:** Die CLI zeigt eine Tool-Aufruf-Nachricht an, die angibt, dass `read_many_files` verwendet wurde, sowie eine Meldung mit Statusinformationen und den verarbeiteten Pfaden. -- **`@` (Alleinstehendes @-Symbol)** - - **Beschreibung:** Wenn du nur ein `@`-Symbol ohne Pfad eingibst, wird der Prompt unverändert an das Modell weitergeleitet. Das kann nützlich sein, wenn du im Prompt _über_ das `@`-Symbol selbst sprichst. +- **`@` (Allein stehendes @-Symbol)** + - **Beschreibung:** Wenn du nur ein einzelnes `@` ohne Pfad eingibst, wird der Query unverändert an das Modell weitergeleitet. Das kann nützlich sein, wenn du im Prompt explizit _über_ das `@`-Symbol sprichst. ### Fehlerbehandlung für `@`-Befehle -- Wenn der nach `@` angegebene Pfad nicht gefunden wird oder ungültig ist, wird eine Fehlermeldung angezeigt, und die Abfrage wird möglicherweise nicht an das Modell gesendet oder ohne den Dateiinhalt gesendet. -- Wenn das `read_many_files`-Tool auf einen Fehler stößt (z. B. Berechtigungsprobleme), wird dies ebenfalls gemeldet. +- Wenn der nach `@` angegebene Pfad nicht gefunden wird oder ungültig ist, wird eine Fehlermeldung angezeigt, und die Abfrage wird möglicherweise nicht an das Modell gesendet oder ohne den Dateiinhalt versandt. +- Wenn das `read_many_files`-Tool auf einen Fehler stößt (z. B. Berechtigungsprobleme), wird dies ebenfalls gemeldet. ## Shell-Modus & Passthrough-Befehle (`!`) Das Präfix `!` ermöglicht es dir, direkt mit der Shell deines Systems aus Qwen Code heraus zu interagieren. - **`!`** - - **Beschreibung:** Führt den angegebenen `` mit `bash` unter Linux/macOS oder `cmd.exe` unter Windows aus. Jegliche Ausgaben oder Fehler des Befehls werden im Terminal angezeigt. + - **Beschreibung:** Führt den angegebenen `` mit `bash` auf Linux/macOS oder `cmd.exe` auf Windows aus. Jegliche Ausgaben oder Fehler des Befehls werden im Terminal angezeigt. - **Beispiele:** - `!ls -la` (führt `ls -la` aus und kehrt zu Qwen Code zurück) - `!git status` (führt `git status` aus und kehrt zu Qwen Code zurück) @@ -428,11 +489,11 @@ Das Präfix `!` ermöglicht es dir, direkt mit der Shell deines Systems aus Qwen - **`!` (Shell-Modus umschalten)** - **Beschreibung:** Die Eingabe von `!` allein schaltet den Shell-Modus um. - **Shell-Modus aktivieren:** - - Im aktiven Zustand verwendet der Shell-Modus eine andere Farbdarstellung und einen „Shell Mode Indicator“. - - Während des Shell-Modus wird der eingegebene Text direkt als Shell-Befehl interpretiert. + - Wenn aktiviert, verwendet der Shell-Modus eine andere Farbdarstellung und einen „Shell Mode Indicator“. + - Im Shell-Modus wird der eingegebene Text direkt als Shell-Befehl interpretiert. - **Shell-Modus verlassen:** - - Beim Verlassen kehrt die Benutzeroberfläche zu ihrem Standard-Aussehen zurück und das normale Verhalten von Qwen Code wird fortgesetzt. + - Beim Verlassen kehrt die Benutzeroberfläche zur Standarddarstellung zurück und das normale Verhalten von Qwen Code wird fortgesetzt. -- **Vorsicht bei der Verwendung von `!`:** Befehle, die du im Shell-Modus ausführst, haben dieselben Berechtigungen und Auswirkungen, als würdest du sie direkt in deinem Terminal ausführen. +- **Achtung bei der Nutzung von `!`:** Befehle, die du im Shell-Modus ausführst, haben dieselben Berechtigungen und Auswirkungen, als würdest du sie direkt in deinem Terminal ausführen. -- **Umgebungsvariable:** Wenn ein Befehl über `!` oder im Shell-Modus ausgeführt wird, wird die Umgebungsvariable `QWEN_CODE=1` in der Umgebung des Unterprozesses gesetzt. Dies erlaubt Skripten oder Tools zu erkennen, ob sie aus der CLI heraus gestartet wurden. \ No newline at end of file +- **Umgebungsvariable:** Wenn ein Befehl über `!` oder im Shell-Modus ausgeführt wird, ist die Umgebungsvariable `QWEN_CODE=1` in der Umgebung des Unterprozesses gesetzt. Dies erlaubt Skripten oder Tools zu erkennen, ob sie innerhalb der CLI ausgeführt werden. \ No newline at end of file diff --git a/website/content/de/cli/configuration.md b/website/content/de/cli/configuration.md index f7042941..fc6a693d 100644 --- a/website/content/de/cli/configuration.md +++ b/website/content/de/cli/configuration.md @@ -1,53 +1,59 @@ # Qwen Code Konfiguration -Qwen Code bietet mehrere Möglichkeiten, um sein Verhalten zu konfigurieren, darunter Umgebungsvariablen, Kommandozeilenargumente und Einstellungsdateien. Dieses Dokument beschreibt die verschiedenen Konfigurationsmethoden und verfügbaren Einstellungen. +Qwen Code bietet mehrere Möglichkeiten, sein Verhalten zu konfigurieren, darunter Umgebungsvariablen, Kommandozeilenargumente und Einstellungsdateien. Dieses Dokument beschreibt die verschiedenen Konfigurationsmethoden und verfügbaren Einstellungen. ## Konfigurationsebenen Die Konfiguration wird in der folgenden Reihenfolge der Priorität angewendet (niedrigere Nummern werden von höheren überschrieben): 1. **Standardwerte:** Fest codierte Standardwerte innerhalb der Anwendung. -2. **Benutzereinstellungsdatei:** Globale Einstellungen für den aktuellen Benutzer. -3. **Projekteinstellungsdatei:** Projektspezifische Einstellungen. -4. **Systemeinstellungsdatei:** Systemweite Einstellungen. -5. **Umgebungsvariablen:** Systemweite oder sitzungsspezifische Variablen, möglicherweise geladen aus `.env` Dateien. -6. **Kommandozeilenargumente:** Werte, die beim Starten der CLI übergeben werden. +2. **System-Standarddatei:** Systemweite Standardeinstellungen, die durch andere Einstellungsdateien überschrieben werden können. +3. **Benutzereinstellungsdatei:** Globale Einstellungen für den aktuellen Benutzer. +4. **Projekteinstellungsdatei:** Projektspezifische Einstellungen. +5. **Systemeinstellungsdatei:** Systemweite Einstellungen, die alle anderen Einstellungsdateien überschreiben. +6. **Umgebungsvariablen:** Systemweite oder sitzungsspezifische Variablen, möglicherweise geladen aus `.env` Dateien. +7. **Kommandozeilenargumente:** Werte, die beim Starten der CLI übergeben werden. -## Settings-Dateien +## Einstellungsdateien -Qwen Code verwendet `settings.json` Dateien für die persistente Konfiguration. Es gibt drei Speicherorte für diese Dateien: +Qwen Code verwendet JSON-Einstellungsdateien für die persistente Konfiguration. Es gibt vier Speicherorte für diese Dateien: -- **User Settings-Datei:** - - **Speicherort:** `~/.qwen/settings.json` (wobei `~` dein Home-Verzeichnis ist). - - **Gültigkeitsbereich:** Gilt für alle Qwen Code Sessions des aktuellen Benutzers. -- **Project Settings-Datei:** - - **Speicherort:** `.qwen/settings.json` im Root-Verzeichnis deines Projekts. - - **Gültigkeitsbereich:** Gilt nur, wenn Qwen Code aus diesem spezifischen Projekt heraus gestartet wird. Project Settings überschreiben User Settings. +- **System-Standarddatei:** + - **Speicherort:** `/etc/qwen-code/system-defaults.json` (Linux), `C:\ProgramData\qwen-code\system-defaults.json` (Windows) oder `/Library/Application Support/QwenCode/system-defaults.json` (macOS). Der Pfad kann mithilfe der Umgebungsvariable `QWEN_CODE_SYSTEM_DEFAULTS_PATH` überschrieben werden. + - **Geltungsbereich:** Stellt eine Basisebene mit systemweiten Standardeinstellungen bereit. Diese Einstellungen haben die niedrigste Priorität und sollen durch Benutzer-, Projekt- oder Systemüberschreibungseinstellungen überschrieben werden. -- **System Settings-Datei:** - - **Speicherort:** `/etc/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) oder `/Library/Application Support/QwenCode/settings.json` (macOS). Der Pfad kann mit der Umgebungsvariable `QWEN_CODE_SYSTEM_SETTINGS_PATH` überschrieben werden. - - **Gültigkeitsbereich:** Gilt für alle Qwen Code Sessions auf dem System, für alle Benutzer. System Settings überschreiben User und Project Settings. Kann für Systemadministratoren in Unternehmen nützlich sein, um Kontrolle über die Qwen Code Einrichtungen der Benutzer zu haben. +- **Benutzereinstellungsdatei:** + - **Speicherort:** `~/.qwen/settings.json` (wobei `~` Ihr Home-Verzeichnis ist). + - **Geltungsbereich:** Gilt für alle Qwen Code-Sitzungen des aktuellen Benutzers. -**Hinweis zu Umgebungsvariablen in Settings:** String-Werte innerhalb deiner `settings.json` Dateien können Umgebungsvariablen mit der Syntax `$VAR_NAME` oder `${VAR_NAME}` referenzieren. Diese Variablen werden automatisch aufgelöst, wenn die Settings geladen werden. Wenn du zum Beispiel eine Umgebungsvariable `MY_API_TOKEN` hast, kannst du sie in der `settings.json` so verwenden: `"apiKey": "$MY_API_TOKEN"`. +- **Projekteinstellungsdatei:** + - **Speicherort:** `.qwen/settings.json` im Stammverzeichnis Ihres Projekts. + - **Geltungsbereich:** Gilt nur, wenn Qwen Code aus diesem spezifischen Projekt heraus ausgeführt wird. Projekteinstellungen überschreiben Benutzereinstellungen. + +- **Systemeinstellungsdatei:** + - **Speicherort:** `/etc/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) oder `/Library/Application Support/QwenCode/settings.json` (macOS). Der Pfad kann mithilfe der Umgebungsvariable `QWEN_CODE_SYSTEM_SETTINGS_PATH` überschrieben werden. + - **Geltungsbereich:** Gilt für alle Qwen Code-Sitzungen auf dem System, für alle Benutzer. Systemeinstellungen überschreiben Benutzer- und Projekteinstellungen. Kann für Systemadministratoren in Unternehmen nützlich sein, um Kontrolle über die Qwen Code-Konfigurationen der Benutzer zu haben. + +**Hinweis zu Umgebungsvariablen in den Einstellungen:** Zeichenkettenwerte innerhalb Ihrer `settings.json`-Dateien können Umgebungsvariablen enthalten, indem sie entweder die Syntax `$VAR_NAME` oder `${VAR_NAME}` verwenden. Diese Variablen werden automatisch aufgelöst, sobald die Einstellungen geladen werden. Wenn Sie zum Beispiel eine Umgebungsvariable namens `MY_API_TOKEN` haben, könnten Sie diese in der `settings.json` wie folgt verwenden: `"apiKey": "$MY_API_TOKEN"`. ### Das `.qwen`-Verzeichnis in deinem Projekt -Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekts auch andere projektspezifische Dateien enthalten, die für den Betrieb von Qwen Code relevant sind, wie z. B.: +Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekts auch andere projektspezifische Dateien enthalten, die für den Betrieb von Qwen Code relevant sind, wie z. B.: -- [Benutzerdefinierte Sandbox-Profile](#sandboxing) (z. B. `.qwen/sandbox-macos-custom.sb`, `.qwen/sandbox.Dockerfile`). +- [Benutzerdefinierte Sandbox-Profile](#sandboxing) (z. B. `.qwen/sandbox-macos-custom.sb`, `.qwen/sandbox.Dockerfile`). ### Verfügbare Einstellungen in `settings.json`: -- **`contextFileName`** (string oder Array von Strings): +- **`contextFileName`** (String oder Array aus Strings): - **Beschreibung:** Gibt den Dateinamen für Kontextdateien an (z. B. `QWEN.md`, `AGENTS.md`). Kann ein einzelner Dateiname oder eine Liste akzeptierter Dateinamen sein. - - **Standard:** `QWEN.md` + - **Standardwert:** `QWEN.md` - **Beispiel:** `"contextFileName": "AGENTS.md"` -- **`bugCommand`** (object): +- **`bugCommand`** (Objekt): - **Beschreibung:** Überschreibt die Standard-URL für den `/bug`-Befehl. - - **Standard:** `"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"` + - **Standardwert:** `"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"` - **Eigenschaften:** - - **`urlTemplate`** (string): Eine URL, die Platzhalter `{title}` und `{info}` enthalten kann. + - **`urlTemplate`** (String): Eine URL, die Platzhalter `{title}` und `{info}` enthalten kann. - **Beispiel:** ```json "bugCommand": { @@ -55,93 +61,112 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt } ``` -- **`fileFiltering`** (object): - - **Beschreibung:** Steuert das git-basierte Dateifilterverhalten für @-Befehle und Datei-Suchwerkzeuge. - - **Standard:** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` +- **`fileFiltering`** (Objekt): + - **Beschreibung:** Steuert das git-basierte Filterverhalten für @-Befehle und Datei-Suchwerkzeuge. + - **Standardwert:** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` - **Eigenschaften:** - - **`respectGitIgnore`** (boolean): Ob `.gitignore`-Muster bei der Dateierkennung berücksichtigt werden sollen. Bei `true` werden git-ignorierte Dateien (wie `node_modules/`, `dist/`, `.env`) automatisch von @-Befehlen und Dateilisten ausgeschlossen. - - **`enableRecursiveFileSearch`** (boolean): Ob rekursive Suche nach Dateinamen unterhalb des aktuellen Verzeichnisses aktiviert ist, wenn @-Präfixe im Prompt vervollständigt werden. + - **`respectGitIgnore`** (Boolean): Legt fest, ob `.gitignore`-Muster bei der Dateisuche berücksichtigt werden. Bei `true` werden git-ignorierte Dateien (wie `node_modules/`, `dist/`, `.env`) automatisch von @-Befehlen und Dateilisten ausgeschlossen. + - **`enableRecursiveFileSearch`** (Boolean): Legt fest, ob rekursiv nach Dateinamen im aktuellen Verzeichnisbaum gesucht wird, wenn @-Präfixe im Prompt vervollständigt werden. + - **`disableFuzzySearch`** (Boolean): Wenn `true`, wird die Fuzzy-Suche beim Auffinden von Dateien deaktiviert, was die Performance in Projekten mit vielen Dateien verbessern kann. - **Beispiel:** ```json "fileFiltering": { "respectGitIgnore": true, - "enableRecursiveFileSearch": false + "enableRecursiveFileSearch": false, + "disableFuzzySearch": true } ``` -- **`coreTools`** (Array von Strings): - - **Beschreibung:** Ermöglicht es, eine Liste von Core-Tool-Namen anzugeben, die dem Modell zur Verfügung gestellt werden sollen. Damit kann die Menge der eingebauten Tools eingeschränkt werden. Siehe [Built-in Tools](../core/tools-api.md#built-in-tools) für eine Liste der Core-Tools. Es können auch Tool-spezifische Einschränkungen für Tools wie `ShellTool` festgelegt werden. Beispiel: `"coreTools": ["ShellTool(ls -l)"]` erlaubt nur den Befehl `ls -l`. - - **Standard:** Alle Tools sind standardmäßig verfügbar. +### Problemlösung bei der Dateisuche-Performance + +Wenn du Performance-Probleme bei der Dateisuche (z. B. mit `@`-Vervollständigungen) hast – besonders in Projekten mit sehr vielen Dateien – kannst du folgende Maßnahmen in der angegebenen Reihenfolge ausprobieren: + +1. **Verwende `.qwenignore`:** Erstelle eine `.qwenignore`-Datei im Projektverzeichnis, um Verzeichnisse auszuschließen, die viele Dateien enthalten, auf die du nicht zugreifen musst (z. B. Build-Artefakte, Logs, `node_modules`). Die Reduzierung der Anzahl der durchsuchten Dateien ist die effektivste Methode zur Verbesserung der Performance. + +2. **Deaktiviere Fuzzy Search:** Wenn das Ignorieren von Dateien nicht ausreicht, kannst du die Fuzzy-Suche deaktivieren, indem du `disableFuzzySearch` in deiner `settings.json` auf `true` setzt. Dadurch wird ein einfacherer, nicht-fuzzy-basierter Algorithmus verwendet, der schneller sein kann. + +3. **Deaktiviere rekursive Dateisuche:** Als letztes Mittel kannst du die rekursive Dateisuche komplett deaktivieren, indem du `enableRecursiveFileSearch` auf `false` setzt. Dies ist die schnellste Option, da dadurch der rekursive Durchlauf des Projekts vermieden wird. Du musst dann jedoch den vollständigen Pfad zu Dateien eingeben, wenn du `@`-Vervollständigungen verwendest. + +--- + +- **`coreTools`** (Array aus Strings): + - **Beschreibung:** Ermöglicht es dir, eine Liste von Core-Tool-Namen anzugeben, die für das Modell verfügbar gemacht werden sollen. Damit kannst du die Menge der integrierten Tools einschränken. Eine Liste der Core-Tools findest du unter [Built-in Tools](../core/tools-api.md#built-in-tools). Du kannst auch Befehlseinschränkungen für Tools festlegen, die dies unterstützen, wie z. B. das `ShellTool`. Beispiel: `"coreTools": ["ShellTool(ls -l)"]` erlaubt nur die Ausführung des Befehls `ls -l`. + - **Standardwert:** Alle Tools sind für das Modell verfügbar. - **Beispiel:** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`. -- **`excludeTools`** (Array von Strings): - - **Beschreibung:** Ermöglicht es, eine Liste von Core-Tool-Namen anzugeben, die vom Modell ausgeschlossen werden sollen. Ein Tool, das sowohl in `excludeTools` als auch in `coreTools` aufgeführt ist, wird ausgeschlossen. Es können auch Tool-spezifische Einschränkungen wie bei `ShellTool` festgelegt werden. Beispiel: `"excludeTools": ["ShellTool(rm -rf)"]` blockiert den Befehl `rm -rf`. - - **Standard:** Keine Tools ausgeschlossen. +- **`allowedTools`** (Array aus Strings): + - **Standardwert:** `undefined` + - **Beschreibung:** Eine Liste von Tool-Namen, die den Bestätigungsdialog umgehen. Das ist nützlich für Tools, denen du vertraust und die du häufig verwendest. Die Matching-Logik entspricht der von `coreTools`. + - **Beispiel:** `"allowedTools": ["ShellTool(git status)"]`. + +- **`excludeTools`** (Array aus Strings): + - **Beschreibung:** Ermöglicht es dir, eine Liste von Core-Tool-Namen anzugeben, die vom Modell ausgeschlossen werden sollen. Ein Tool, das sowohl in `excludeTools` als auch in `coreTools` aufgeführt ist, wird ausgeschlossen. Du kannst auch Befehlseinschränkungen für Tools festlegen, die dies unterstützen, wie z. B. das `ShellTool`. Beispiel: `"excludeTools": ["ShellTool(rm -rf)"]` blockiert den Befehl `rm -rf`. + - **Standardwert:** Keine Tools ausgeschlossen. - **Beispiel:** `"excludeTools": ["run_shell_command", "findFiles"]`. - - **Sicherheitshinweis:** Die Einschränkungen in `excludeTools` basieren auf einfacher Stringvergleichung und können leicht umgangen werden. Diese Funktion ist **kein Sicherheitsmechanismus** und sollte nicht verwendet werden, um das sichere Ausführen von nicht vertrauenswürdigem Code zu gewährleisten. Es wird empfohlen, `coreTools` zu verwenden, um explizit erlaubte Befehle auszuwählen. + - **Sicherheitshinweis:** Befehlseinschränkungen in `excludeTools` für `run_shell_command` basieren auf einfacher String-Matching und können leicht umgangen werden. Diese Funktion ist **kein Sicherheitsmechanismus** und sollte nicht darauf verlassen werden, um nicht vertrauenswürdigen Code sicher auszuführen. Es wird empfohlen, `coreTools` zu verwenden, um explizit die Befehle auszuwählen, die ausgeführt werden dürfen. -- **`allowMCPServers`** (Array von Strings): - - **Beschreibung:** Ermöglicht es, eine Liste von MCP-Servernamen anzugeben, die dem Modell zur Verfügung gestellt werden sollen. Damit kann die Menge der verfügbaren MCP-Server eingeschränkt werden. Diese Einstellung wird ignoriert, wenn `--allowed-mcp-server-names` gesetzt ist. - - **Standard:** Alle MCP-Server sind standardmäßig verfügbar. +- **`allowMCPServers`** (Array aus Strings): + - **Beschreibung:** Ermöglicht es dir, eine Liste von MCP-Servernamen anzugeben, die für das Modell verfügbar gemacht werden sollen. Damit kannst du die Menge der MCP-Server einschränken, mit denen verbunden wird. Beachte, dass diese Einstellung ignoriert wird, wenn `--allowed-mcp-server-names` gesetzt ist. + - **Standardwert:** Alle MCP-Server sind für das Modell verfügbar. - **Beispiel:** `"allowMCPServers": ["myPythonServer"]`. - - **Sicherheitshinweis:** Diese Funktion verwendet einfache Stringvergleiche auf Servernamen, die manipuliert werden können. Systemadministratoren sollten ggf. die `mcpServers` auf Systemebene konfigurieren, um zu verhindern, dass Benutzer eigene Server konfigurieren. Diese Funktion sollte **nicht als sicherer Mechanismus** betrachtet werden. + - **Sicherheitshinweis:** Hierbei wird einfaches String-Matching auf MCP-Servernamen verwendet, die manipuliert werden können. Wenn du als Systemadministrator verhindern möchtest, dass Benutzer dies umgehen, solltest du `mcpServers` auf Systemebene konfigurieren, sodass Benutzer keine eigenen MCP-Server konfigurieren können. Dies sollte **nicht** als absoluter Sicherheitsmechanismus betrachtet werden. -- **`excludeMCPServers`** (Array von Strings): - - **Beschreibung:** Ermöglicht es, eine Liste von MCP-Servernamen anzugeben, die vom Modell ausgeschlossen werden sollen. Ein Server, der sowohl in `excludeMCPServers` als auch in `allowMCPServers` aufgeführt ist, wird ausgeschlossen. Diese Einstellung wird ignoriert, wenn `--allowed-mcp-server-names` gesetzt ist. - - **Standard:** Keine MCP-Server ausgeschlossen. +- **`excludeMCPServers`** (Array aus Strings): + - **Beschreibung:** Ermöglicht es dir, eine Liste von MCP-Servernamen anzugeben, die vom Modell ausgeschlossen werden sollen. Ein Server, der sowohl in `excludeMCPServers` als auch in `allowMCPServers` aufgeführt ist, wird ausgeschlossen. Beachte, dass diese Einstellung ignoriert wird, wenn `--allowed-mcp-server-names` gesetzt ist. + - **Standardwert:** Keine MCP-Server ausgeschlossen. - **Beispiel:** `"excludeMCPServers": ["myNodeServer"]`. - - **Sicherheitshinweis:** Diese Funktion verwendet einfache Stringvergleiche auf Servernamen, die manipuliert werden können. Systemadministratoren sollten ggf. die `mcpServers` auf Systemebene konfigurieren, um zu verhindern, dass Benutzer eigene Server konfigurieren. Diese Funktion sollte **nicht als sicherer Mechanismus** betrachtet werden. + - **Sicherheitshinweis:** Hierbei wird einfaches String-Matching auf MCP-Servernamen verwendet, die manipuliert werden können. Wenn du als Systemadministrator verhindern möchtest, dass Benutzer dies umgehen, solltest du `mcpServers` auf Systemebene konfigurieren, sodass Benutzer keine eigenen MCP-Server konfigurieren können. Dies sollte **nicht** als absoluter Sicherheitsmechanismus betrachtet werden. -- **`autoAccept`** (boolean): - - **Beschreibung:** Legt fest, ob die CLI Tool-Aufrufe, die als sicher gelten (z. B. read-only-Operationen), automatisch akzeptiert und ausgeführt werden, ohne explizite Benutzerbestätigung. Bei `true` wird die Bestätigungsabfrage für sichere Tools übersprungen. - - **Standard:** `false` +- **`autoAccept`** (Boolean): + - **Beschreibung:** Legt fest, ob die CLI automatisch Tool-Aufrufe akzeptiert und ausführt, die als sicher gelten (z. B. schreibgeschützte Operationen), ohne explizite Benutzerbestätigung. Bei `true` wird der Bestätigungsdialog für sichere Tools übersprungen. + - **Standardwert:** `false` - **Beispiel:** `"autoAccept": true` -- **`theme`** (string): +- **`theme`** (String): - **Beschreibung:** Setzt das visuelle [Theme](./themes.md) für Qwen Code. - - **Standard:** `"Default"` + - **Standardwert:** `"Default"` - **Beispiel:** `"theme": "GitHub"` -- **`vimMode`** (boolean): - - **Beschreibung:** Aktiviert oder deaktiviert den Vim-Modus für die Eingabebearbeitung. Im aktivierten Zustand unterstützt der Eingabebereich Vim-Befehle mit NORMAL- und INSERT-Modus. Der Status wird in der Fußzeile angezeigt und bleibt zwischen Sitzungen erhalten. - - **Standard:** `false` +- **`vimMode`** (Boolean): + - **Beschreibung:** Aktiviert oder deaktiviert den Vim-Modus für die Eingabebearbeitung. Im aktivierten Zustand unterstützt der Eingabebereich Vim-artige Navigations- und Bearbeitungsbefehle mit NORMAL- und INSERT-Modus. Der Status des Vim-Modus wird in der Fußzeile angezeigt und bleibt zwischen Sitzungen erhalten. + - **Standardwert:** `false` - **Beispiel:** `"vimMode": true` -- **`sandbox`** (boolean oder string): - - **Beschreibung:** Steuert, ob und wie Sandboxing für Toolausführung verwendet wird. Bei `true` verwendet Qwen Code das vorgefertigte Docker-Image `qwen-code-sandbox`. Weitere Informationen unter [Sandboxing](#sandboxing). - - **Standard:** `false` +- **`sandbox`** (Boolean oder String): + - **Beschreibung:** Legt fest, ob und wie Sandboxing für die Toolausführung verwendet wird. Bei `true` verwendet Qwen Code ein vorgebautes `qwen-code-sandbox` Docker-Image. Weitere Informationen findest du unter [Sandboxing](#sandboxing). + - **Standardwert:** `false` - **Beispiel:** `"sandbox": "docker"` -- **`toolDiscoveryCommand`** (string): - - **Beschreibung:** Definiert einen benutzerdefinierten Shell-Befehl zur Erkennung von Tools aus dem Projekt. Der Befehl muss auf `stdout` ein JSON-Array von [Function Declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) zurückgeben. Tool-Wrappers sind optional. - - **Standard:** Leer +- **`toolDiscoveryCommand`** (String): + - **Beschreibung:** **Gemäß Gemini CLI.** Definiert einen benutzerdefinierten Shell-Befehl zum Entdecken von Tools aus deinem Projekt. Der Shell-Befehl muss auf `stdout` ein JSON-Array von [Function Declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) zurückgeben. Tool-Wrappers sind optional. + - **Standardwert:** Leer - **Beispiel:** `"toolDiscoveryCommand": "bin/get_tools"` -- **`toolCallCommand`** (string): - - **Beschreibung:** Definiert einen benutzerdefinierten Shell-Befehl zum Aufrufen eines bestimmten Tools, das über `toolDiscoveryCommand` gefunden wurde. Der Befehl muss folgende Kriterien erfüllen: - - Der erste Parameter muss der Funktionsname sein (genau wie in der [Function Declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)). - - Die Funktionsargumente müssen als JSON über `stdin` gelesen werden (analog zu [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall)). - - Die Funktionsausgabe muss als JSON über `stdout` zurückgegeben werden (analog zu [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse)). - - **Standard:** Leer +- **`toolCallCommand`** (String): + - **Beschreibung:** **Gemäß Gemini CLI.** Definiert einen benutzerdefinierten Shell-Befehl zum Aufrufen eines bestimmten Tools, das über `toolDiscoveryCommand` entdeckt wurde. Der Shell-Befehl muss folgende Kriterien erfüllen: + - Er muss den Funktionsnamen (genau wie in der [Function Declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) als erstes Kommandozeilenargument entgegennehmen. + - Er muss Funktionsargumente als JSON von `stdin` lesen, analog zu [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). + - Er muss die Funktionsausgabe als JSON auf `stdout` zurückgeben, analog zu [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). + - **Standardwert:** Leer - **Beispiel:** `"toolCallCommand": "bin/call_tool"` -- **`mcpServers`** (object): - - **Beschreibung:** Konfiguriert Verbindungen zu einem oder mehreren Model-Context Protocol (MCP)-Servern zur Erkennung und Nutzung benutzerdefinierter Tools. Qwen Code versucht, sich mit jedem konfigurierten MCP-Server zu verbinden, um verfügbare Tools zu erkennen. Wenn mehrere Server ein Tool mit demselben Namen anbieten, wird der Name mit dem Server-Alias vorangestellt (z. B. `serverAlias__actualToolName`), um Konflikte zu vermeiden. Das System kann bestimmte Schema-Eigenschaften aus MCP-Tooldefinitionen entfernen, um Kompatibilität zu gewährleisten. Mindestens eines der Felder `command`, `url` oder `httpUrl` muss angegeben werden. Die Priorität ist: `httpUrl`, dann `url`, dann `command`. - - **Standard:** Leer +- **`mcpServers`** (Objekt): + - **Beschreibung:** Konfiguriert Verbindungen zu einem oder mehreren Model-Context Protocol (MCP)-Servern zum Entdecken und Nutzen von benutzerdefinierten Tools. Qwen Code versucht, sich mit jedem konfigurierten MCP-Server zu verbinden, um verfügbare Tools zu entdecken. Wenn mehrere MCP-Server ein Tool mit demselben Namen bereitstellen, werden die Tool-Namen mit dem Server-Alias aus der Konfiguration vorangestellt (z. B. `serverAlias__actualToolName`), um Konflikte zu vermeiden. Beachte, dass das System möglicherweise bestimmte Schema-Eigenschaften aus MCP-Tooldefinitionen entfernt, um die Kompatibilität zu gewährleisten. Mindestens eines von `command`, `url` oder `httpUrl` muss angegeben werden. Falls mehrere angegeben sind, gilt die Priorität: `httpUrl`, dann `url`, dann `command`. + - **Standardwert:** Leer - **Eigenschaften:** - - **``** (object): Die Serverparameter für den benannten Server. - - `command` (string, optional): Der Befehl zum Starten des MCP-Servers über Standard-I/O. - - `args` (Array von Strings, optional): Argumente für den Befehl. - - `env` (object, optional): Umgebungsvariablen für den Serverprozess. - - `cwd` (string, optional): Arbeitsverzeichnis zum Starten des Servers. - - `url` (string, optional): URL eines MCP-Servers, der Server-Sent Events (SSE) verwendet. - - `httpUrl` (string, optional): URL eines MCP-Servers, der streambare HTTP-Kommunikation verwendet. - - `headers` (object, optional): HTTP-Header, die mit Anfragen an `url` oder `httpUrl` gesendet werden. - - `timeout` (number, optional): Zeitlimit in Millisekunden für Anfragen an diesen MCP-Server. - - `trust` (boolean, optional): Vertraue diesem Server und umgehe alle Tool-Bestätigungen. - - `description` (string, optional): Kurze Beschreibung des Servers, z. B. für Anzeigezwecke. - - `includeTools` (Array von Strings, optional): Liste der Tool-Namen, die von diesem Server verwendet werden sollen. Wenn angegeben, sind nur diese Tools verfügbar (Whitelist). Andernfalls sind alle Tools standardmäßig aktiviert. - - `excludeTools` (Array von Strings, optional): Liste der Tool-Namen, die von diesem Server ausgeschlossen werden sollen. Diese Tools sind dann nicht verfügbar, auch wenn sie vom Server angeboten werden. **Hinweis:** `excludeTools` hat Vorrang vor `includeTools` – wenn ein Tool in beiden Listen steht, wird es ausgeschlossen. + - **``** (Objekt): Die Serverparameter für den benannten Server. + - `command` (String, optional): Der Befehl zum Starten des MCP-Servers über Standard-I/O. + - `args` (Array aus Strings, optional): Argumente, die an den Befehl übergeben werden. + - `env` (Objekt, optional): Umgebungsvariablen, die für den Serverprozess gesetzt werden. + - `cwd` (String, optional): Das Arbeitsverzeichnis, in dem der Server gestartet wird. + - `url` (String, optional): Die URL eines MCP-Servers, der Server-Sent Events (SSE) für die Kommunikation verwendet. + - `httpUrl` (String, optional): Die URL eines MCP-Servers, der streambare HTTP-Kommunikation verwendet. + - `headers` (Objekt, optional): Eine Zuordnung von HTTP-Headers, die mit Anfragen an `url` oder `httpUrl` gesendet werden. + - `timeout` (Zahl, optional): Zeitlimit in Millisekunden für Anfragen an diesen MCP-Server. + - `trust` (Boolean, optional): Dem Server vertrauen und alle Tool-Aufrufbestätigungen umgehen. + - `description` (String, optional): Eine kurze Beschreibung des Servers, die zu Anzeigezwecken verwendet werden kann. + - `includeTools` (Array aus Strings, optional): Liste der Tool-Namen, die von diesem MCP-Server eingeschlossen werden sollen. Wenn angegeben, sind nur die hier aufgelisteten Tools von diesem Server verfügbar (Whitelist-Verhalten). Wenn nicht angegeben, sind standardmäßig alle Tools des Servers aktiviert. + - `excludeTools` (Array aus Strings, optional): Liste der Tool-Namen, die von diesem MCP-Server ausgeschlossen werden sollen. Die hier aufgelisteten Tools stehen dem Modell nicht zur Verfügung, selbst wenn sie vom Server bereitgestellt werden. **Hinweis:** `excludeTools` hat Vorrang vor `includeTools` – wenn ein Tool in beiden Listen steht, wird es ausgeschlossen. - **Beispiel:** ```json "mcpServers": { @@ -177,30 +202,30 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt "headers": { "X-API-Key": "$MY_HTTP_API_KEY" }, - "description": "Ein Beispiel-Streamable-HTTP-basierter MCP-Server." + "description": "Ein Beispiel-HTTP-basierter MCP-Server mit Streaming." } } ``` -- **`checkpointing`** (object): - - **Beschreibung:** Konfiguriert die Checkpointing-Funktion, mit der Konversations- und Dateizustände gespeichert und wiederhergestellt werden können. Weitere Informationen unter [Checkpointing documentation](../checkpointing.md). - - **Standard:** `{"enabled": false}` +- **`checkpointing`** (Objekt): + - **Beschreibung:** Konfiguriert die Checkpoint-Funktion, mit der du Gesprächs- und Dateizustände speichern und wiederherstellen kannst. Weitere Details findest du in der [Checkpointing-Dokumentation](../checkpointing.md). + - **Standardwert:** `{"enabled": false}` - **Eigenschaften:** - - **`enabled`** (boolean): Bei `true` ist der `/restore`-Befehl verfügbar. + - **`enabled`** (Boolean): Wenn `true`, ist der Befehl `/restore` verfügbar. -- **`preferredEditor`** (string): +- **`preferredEditor`** (String): - **Beschreibung:** Gibt den bevorzugten Editor zum Anzeigen von Diffs an. - - **Standard:** `vscode` + - **Standardwert:** `vscode` - **Beispiel:** `"preferredEditor": "vscode"` -- **`telemetry`** (object) - - **Beschreibung:** Konfiguriert das Logging und die Erfassung von Metriken für Qwen Code. Weitere Informationen unter [Telemetry](../telemetry.md). - - **Standard:** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` +- **`telemetry`** (Objekt) + - **Beschreibung:** Konfiguriert das Logging und die Erfassung von Metriken für Qwen Code. Weitere Informationen findest du unter [Telemetrie](../telemetry.md). + - **Standardwert:** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **Eigenschaften:** - - **`enabled`** (boolean): Ob Telemetrie aktiviert ist. - - **`target`** (string): Ziel für gesammelte Telemetriedaten. Unterstützte Werte: `local` und `gcp`. - - **`otlpEndpoint`** (string): Endpunkt für den OTLP Exporter. - - **`logPrompts`** (boolean): Ob der Inhalt von Benutzerprompts in Logs enthalten sein soll. + - **`enabled`** (Boolean): Ob Telemetrie aktiviert ist oder nicht. + - **`target`** (String): Das Ziel für die gesammelten Telemetriedaten. Unterstützte Werte sind `local` und `gcp`. + - **`otlpEndpoint`** (String): Der Endpunkt für den OTLP-Exporter. + - **`logPrompts`** (Boolean): Ob der Inhalt von Benutzerprompts in die Logs aufgenommen werden soll. - **Beispiel:** ```json "telemetry": { @@ -211,53 +236,36 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt } ``` -- **`usageStatisticsEnabled`** (boolean): - - **Beschreibung:** Aktiviert oder deaktiviert die Erfassung von Nutzungsstatistiken. Weitere Informationen unter [Usage Statistics](#usage-statistics). - - **Standard:** `true` +- **`usageStatisticsEnabled`** (Boolean): + - **Beschreibung:** Aktiviert oder deaktiviert die Erfassung von Nutzungsstatistiken. Weitere Informationen findest du unter [Nutzungsstatistiken](#usage-statistics). + - **Standardwert:** `true` - **Beispiel:** ```json "usageStatisticsEnabled": false ``` -- **`hideTips`** (boolean): +- **`hideTips`** (Boolean): - **Beschreibung:** Aktiviert oder deaktiviert hilfreiche Tipps in der CLI-Oberfläche. - - **Standard:** `false` + - **Standardwert:** `false` - **Beispiel:** ```json "hideTips": true ``` -- **`hideBanner`** (boolean): +- **`hideBanner`** (Boolean): - **Beschreibung:** Aktiviert oder deaktiviert das Startbanner (ASCII-Art-Logo) in der CLI-Oberfläche. - - **Standard:** `false` + - **Standardwert:** `false` - **Beispiel:** ```json "hideBanner": true ``` -- **`maxSessionTurns`** (number): - - **Beschreibung:** Legt die maximale Anzahl von Turns pro Sitzung fest. Wenn das Limit überschritten wird, stoppt die CLI und startet einen neuen Chat. - - **Standard:** `-1` (unbegrenzt) +- **`maxSessionTurns`** (Zahl): + - **Beschreibung:** Legt die maximale Anzahl von Turns pro Session fest. Wenn die Session dieses Limit überschreitet, stoppt die CLI die Verarbeitung und beginnt einen neuen Chat. + - **Standardwert:** `-1` (unbegrenzt) - **Beispiel:** ```json - "maxSessionTurns": 10 - ``` - -- **`summarizeToolOutput`** (object): - - **Beschreibung:** Aktiviert oder deaktiviert die Zusammenfassung von Toolausgaben. Mit der Einstellung `tokenBudget` kann das Token-Budget für die Zusammenfassung festgelegt werden. - - Hinweis: Derzeit wird nur das `run_shell_command`-Tool unterstützt. - - **Standard:** `{}` (standardmäßig deaktiviert) - - **Beispiel:** - ```json - "summarizeToolOutput": { - "run_shell_command": { - "tokenBudget": 2000 - } - } - ``` - -- **`excludedProjectEnvVars`** (Array von Strings): - - **Beschreibung:** Gibt Umgebungsvariablen an, die aus Projekt-`.env`-Dateien ausgeschlossen werden sollen. Dies verhindert, dass projektspezifische + "maxSessionTurns": ### Beispiel `settings.json`: @@ -286,6 +294,8 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt "usageStatisticsEnabled": true, "hideTips": false, "hideBanner": false, + "skipNextSpeakerCheck": false, + "skipLoopDetection": false, "maxSessionTurns": 10, "summarizeToolOutput": { "run_shell_command": { @@ -298,25 +308,25 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt } ``` -## Shell History +## Shell-Historie -Die CLI speichert einen Verlauf der Shell-Befehle, die du ausführst. Um Konflikte zwischen verschiedenen Projekten zu vermeiden, wird dieser Verlauf in einem projektspezifischen Verzeichnis innerhalb deines Benutzer-Home-Ordners gespeichert. +Die CLI speichert eine Historie der Shell-Befehle, die du ausführst. Um Konflikte zwischen verschiedenen Projekten zu vermeiden, wird diese Historie in einem projektspezifischen Verzeichnis innerhalb deines Benutzer-Home-Ordners gespeichert. - **Speicherort:** `~/.qwen/tmp//shell_history` - - `` ist eine eindeutige Kennung, die aus dem Root-Pfad deines Projekts generiert wird. - - Der Verlauf wird in einer Datei mit dem Namen `shell_history` gespeichert. + - `` ist ein eindeutiger Identifier, der aus dem Root-Pfad deines Projekts generiert wird. + - Die Historie wird in einer Datei mit dem Namen `shell_history` gespeichert. ## Umgebungsvariablen & `.env` Dateien -Umgebungsvariablen sind eine gängige Methode, um Anwendungen zu konfigurieren – besonders für sensible Informationen wie API keys oder Einstellungen, die sich zwischen verschiedenen Umgebungen unterscheiden. Informationen zur Authentifizierung findest du in der [Authentication Dokumentation](./authentication.md), die alle verfügbaren Authentifizierungsmethoden abdeckt. +Umgebungsvariablen sind eine gängige Methode zur Konfiguration von Anwendungen – besonders für sensible Informationen wie API Keys oder Einstellungen, die sich zwischen verschiedenen Umgebungen unterscheiden können. Für das Setup der Authentifizierung siehe die [Authentifizierungs-Dokumentation](./authentication.md), die alle verfügbaren Authentifizierungsmethoden abdeckt. -Die CLI lädt Umgebungsvariablen automatisch aus einer `.env` Datei. Die Ladereihenfolge ist: +Die CLI lädt automatisch Umgebungsvariablen aus einer `.env` Datei. Die Ladereihenfolge ist wie folgt: -1. `.env` Datei im aktuellen Arbeitsverzeichnis. -2. Falls nicht gefunden, sucht sie rekursiv in den übergeordneten Verzeichnissen, bis eine `.env` Datei gefunden wird oder das Projekt-Root-Verzeichnis (erkennbar an einem `.git` Ordner) oder das Home-Verzeichnis erreicht ist. -3. Falls immer noch nichts gefunden wurde, wird `~/.env` (im Home-Verzeichnis des Benutzers) geladen. +1. `.env` Datei im aktuellen Arbeitsverzeichnis. +2. Falls nicht gefunden, sucht sie rekursiv in den übergeordneten Verzeichnissen nach einer `.env` Datei, bis entweder eine gefunden wird oder das Projektstammverzeichnis (erkennbar an einem `.git` Ordner) oder das Home-Verzeichnis erreicht ist. +3. Wenn immer noch keine gefunden wurde, wird `~/.env` (im Benutzer-Home-Verzeichnis) geladen. -**Ausschluss von Umgebungsvariablen:** Bestimmte Umgebungsvariablen (wie `DEBUG` und `DEBUG_MODE`) werden standardmäßig aus Projekt `.env` Dateien ausgeschlossen, um Störungen im CLI-Verhalten zu vermeiden. Variablen aus `.qwen/.env` Dateien werden niemals ausgeschlossen. Du kannst dieses Verhalten über die Einstellung `excludedProjectEnvVars` in deiner `settings.json` Datei anpassen. +**Ausschluss von Umgebungsvariablen:** Bestimmte Umgebungsvariablen (wie `DEBUG` und `DEBUG_MODE`) werden standardmäßig aus Projekt `.env` Dateien ausgeschlossen, um mögliche Beeinträchtigungen des CLI-Verhaltens zu vermeiden. Variablen aus `.qwen/.env` Dateien werden niemals ausgeschlossen. Du kannst dieses Verhalten über die Einstellung `excludedProjectEnvVars` in deiner `settings.json` Datei anpassen. - **`OPENAI_API_KEY`**: - Eine von mehreren verfügbaren [Authentifizierungsmethoden](./authentication.md). @@ -325,31 +335,31 @@ Die CLI lädt Umgebungsvariablen automatisch aus einer `.env` Datei. Die Laderei - Eine von mehreren verfügbaren [Authentifizierungsmethoden](./authentication.md). - Setze diesen Wert in deinem Shell-Profil (z. B. `~/.bashrc`, `~/.zshrc`) oder in einer `.env` Datei. - **`OPENAI_MODEL`**: - - Legt das standardmäßig zu verwendende OPENAI-Modell fest. - - Überschreibt den fest codierten Standardwert. + - Legt das Standard-OPENAI Modell fest. + - Überschreibt den fest codierten Default-Wert. - Beispiel: `export OPENAI_MODEL="qwen3-coder-plus"` - **`GEMINI_SANDBOX`**: - - Alternative zur `sandbox` Einstellung in der `settings.json`. - - Akzeptiert `true`, `false`, `docker`, `podman` oder einen benutzerdefinierten Befehl als String. + - Alternative zur `sandbox` Einstellung in `settings.json`. + - Akzeptiert Werte wie `true`, `false`, `docker`, `podman` oder einen benutzerdefinierten Befehl als String. - **`SEATBELT_PROFILE`** (nur macOS): - Wechselt das Seatbelt (`sandbox-exec`) Profil unter macOS. - `permissive-open`: (Standard) Beschränkt Schreibzugriffe auf den Projektordner (und einige andere, siehe `packages/cli/src/utils/sandbox-macos-permissive-open.sb`), erlaubt aber andere Operationen. - - `strict`: Verwendet ein striktes Profil, das standardmäßig alle Operationen ablehnt. - - ``: Verwendet ein benutzerdefiniertes Profil. Um ein solches Profil zu definieren, erstelle eine Datei mit dem Namen `sandbox-macos-.sb` im `.qwen/` Verzeichnis deines Projekts (z. B. `my-project/.qwen/sandbox-macos-custom.sb`). -- **`DEBUG` oder `DEBUG_MODE`** (häufig von zugrunde liegenden Bibliotheken oder der CLI selbst verwendet): - - Auf `true` oder `1` setzen, um detaillierte Debug-Logs zu aktivieren – hilfreich bei der Fehlersuche. - - **Hinweis:** Diese Variablen werden standardmäßig aus Projekt `.env` Dateien ausgeschlossen, um das CLI-Verhalten nicht zu beeinträchtigen. Verwende `.qwen/.env` Dateien, wenn du diese speziell für Qwen Code setzen musst. + - `strict`: Nutzt ein striktes Profil, das standardmäßig alle Operationen ablehnt. + - ``: Nutzt ein benutzerdefiniertes Profil. Um eines zu definieren, erstelle eine Datei mit dem Namen `sandbox-macos-.sb` im `.qwen/` Verzeichnis deines Projekts (z. B. `my-project/.qwen/sandbox-macos-custom.sb`). +- **`DEBUG` oder `DEBUG_MODE`** (häufig genutzt von zugrunde liegenden Bibliotheken oder der CLI selbst): + - Auf `true` oder `1` setzen, um detaillierte Debug-Ausgaben zu aktivieren – hilfreich bei der Fehlersuche. + - **Hinweis:** Diese Variablen werden standardmäßig aus Projekt `.env` Dateien ausgeschlossen, um das CLI-Verhalten nicht zu beeinträchtigen. Verwende stattdessen `.qwen/.env` Dateien, wenn du diese explizit für Qwen Code setzen musst. - **`NO_COLOR`**: - - Auf einen beliebigen Wert setzen, um alle farbigen Ausgaben in der CLI zu deaktivieren. + - Auf einen beliebigen Wert setzen, um jegliche Farbausgabe in der CLI zu deaktivieren. - **`CLI_TITLE`**: - Auf einen String setzen, um den Titel der CLI anzupassen. - **`CODE_ASSIST_ENDPOINT`**: - Gibt den Endpunkt für den Code Assist Server an. - Nützlich für Entwicklung und Tests. - **`TAVILY_API_KEY`**: - - Dein API key für den Tavily Web-Suchdienst. - - Erforderlich, um die `web_search` Tool-Funktionalität zu aktivieren. - - Wenn nicht konfiguriert, wird das Web-Suchtool deaktiviert und übersprungen. + - Dein API Key für den Tavily Web-Suchdienst. + - Erforderlich, um die Funktionalität des `web_search` Tools zu aktivieren. + - Ohne Konfiguration wird das Web-Suchtool deaktiviert und übersprungen. - Beispiel: `export TAVILY_API_KEY="tvly-your-api-key-here"` ## Command-Line Arguments @@ -360,18 +370,18 @@ Argumente, die direkt beim Ausführen der CLI übergeben werden, können andere - Gibt das Qwen-Modell an, das für diese Sitzung verwendet werden soll. - Beispiel: `npm start -- --model qwen3-coder-plus` - **`--prompt `** (**`-p `**): - - Wird verwendet, um einen Prompt direkt an den Befehl zu übergeben. Dies startet Qwen Code im nicht-interaktiven Modus. + - Wird verwendet, um einen Prompt direkt an den Befehl zu übergeben. Dies ruft Qwen Code im nicht-interaktiven Modus auf. - **`--prompt-interactive `** (**`-i `**): - - Startet eine interaktive Sitzung mit dem übergebenen Prompt als initiale Eingabe. + - Startet eine interaktive Sitzung mit dem angegebenen Prompt als initiale Eingabe. - Der Prompt wird innerhalb der interaktiven Sitzung verarbeitet, nicht davor. - - Kann nicht verwendet werden, wenn Eingaben über stdin gepiped werden. + - Kann nicht verwendet werden, wenn Eingaben von stdin weitergeleitet werden. - Beispiel: `qwen -i "explain this code"` - **`--sandbox`** (**`-s`**): - Aktiviert den Sandbox-Modus für diese Sitzung. - **`--sandbox-image`**: - - Setzt die URI des Sandbox-Images. + - Legt die URI des Sandbox-Images fest. - **`--debug`** (**`-d`**): - - Aktiviert den Debug-Modus für diese Sitzung und gibt detailliertere Ausgaben aus. + - Aktiviert den Debug-Modus für diese Sitzung und gibt ausführlichere Ausgaben zurück. - **`--all-files`** (**`-a`**): - Falls gesetzt, werden rekursiv alle Dateien im aktuellen Verzeichnis als Kontext für den Prompt einbezogen. - **`--help`** (oder **`-h`**): @@ -379,29 +389,33 @@ Argumente, die direkt beim Ausführen der CLI übergeben werden, können andere - **`--show-memory-usage`**: - Zeigt den aktuellen Speicherverbrauch an. - **`--yolo`**: - - Aktiviert den YOLO-Modus, bei dem alle Tool-Aufrufe automatisch genehmigt werden. + - Aktiviert den YOLO-Modus, bei dem automatisch alle Tool-Aufrufe genehmigt werden. - **`--approval-mode `**: - - Setzt den Genehmigungsmodus für Tool-Aufrufe. Verfügbare Modi: - - `default`: Fordert bei jedem Tool-Aufruf eine Genehmigung an (Standardverhalten) - - `auto_edit`: Genehmigt automatisch Edit-Tools (edit, write_file), während für andere eine Eingabe erforderlich ist - - `yolo`: Genehmigt automatisch alle Tool-Aufrufe (äquivalent zu `--yolo`) - - Kann nicht zusammen mit `--yolo` verwendet werden. Verwende stattdessen `--approval-mode=yolo` für den neuen einheitlichen Ansatz. - - Beispiel: `qwen --approval-mode auto_edit` + - Legt den Genehmigungsmodus für Tool-Aufrufe fest. Unterstützte Modi: + - `plan`: Nur analysieren – keine Dateien ändern oder Befehle ausführen. + - `default`: Genehmigung für Dateiänderungen oder Shell-Befehle erforderlich (Standardverhalten). + - `auto-edit`: Automatische Genehmigung von Editierwerkzeugen (edit, write_file), während andere nachgefragt werden. + - `yolo`: Automatische Genehmigung aller Tool-Aufrufe (äquivalent zu `--yolo`). + - Kann nicht zusammen mit `--yolo` verwendet werden. Verwende stattdessen `--approval-mode=yolo`, um den neuen vereinheitlichten Ansatz zu nutzen. + - Beispiel: `qwen --approval-mode auto-edit` +- **`--allowed-tools `**: + - Eine durch Kommas getrennte Liste von Tool-Namen, die den Bestätigungsdialog umgehen. + - Beispiel: `qwen --allowed-tools "ShellTool(git status)"` - **`--telemetry`**: - Aktiviert [Telemetrie](../telemetry.md). - **`--telemetry-target`**: - - Setzt das Ziel für die Telemetrie. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. + - Legt das Ziel für Telemetriedaten fest. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. - **`--telemetry-otlp-endpoint`**: - - Setzt den OTLP-Endpunkt für die Telemetrie. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. + - Legt den OTLP-Endpunkt für Telemetrie fest. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. - **`--telemetry-otlp-protocol`**: - - Setzt das OTLP-Protokoll für die Telemetrie (`grpc` oder `http`). Standardmäßig `grpc`. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. + - Legt das OTLP-Protokoll für Telemetrie fest (`grpc` oder `http`). Standardmäßig ist `grpc` eingestellt. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. - **`--telemetry-log-prompts`**: - - Aktiviert das Logging von Prompts für die Telemetrie. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. + - Aktiviert das Logging von Prompts für Telemetrie-Zwecke. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. - **`--checkpointing`**: - Aktiviert [Checkpointing](../checkpointing.md). - **`--extensions `** (**`-e `**): - - Gibt eine Liste von Erweiterungen an, die für die Sitzung verwendet werden sollen. Falls nicht angegeben, werden alle verfügbaren Erweiterungen verwendet. - - Verwende den speziellen Begriff `qwen -e none`, um alle Erweiterungen zu deaktivieren. + - Gibt eine Liste von Erweiterungen an, die für die Sitzung verwendet werden sollen. Wenn nichts angegeben wird, werden alle verfügbaren Erweiterungen verwendet. + - Nutze den speziellen Begriff `qwen -e none`, um alle Erweiterungen zu deaktivieren. - Beispiel: `qwen -e my-extension -e my-other-extension` - **`--list-extensions`** (**`-l`**): - Listet alle verfügbaren Erweiterungen auf und beendet sich danach. @@ -409,51 +423,54 @@ Argumente, die direkt beim Ausführen der CLI übergeben werden, können andere - Setzt den Proxy für die CLI. - Beispiel: `--proxy http://localhost:7890`. - **`--include-directories `**: - - Fügt zusätzliche Verzeichnisse zum Workspace hinzu, um Multi-Directory-Unterstützung zu ermöglichen. + - Fügt zusätzliche Verzeichnisse zum Workspace hinzu, um Unterstützung für mehrere Verzeichnisse zu ermöglichen. - Kann mehrfach oder als kommagetrennte Werte angegeben werden. - Maximal 5 Verzeichnisse können hinzugefügt werden. - Beispiel: `--include-directories /path/to/project1,/path/to/project2` oder `--include-directories /path/to/project1 --include-directories /path/to/project2` +- **`--screen-reader`**: + - Aktiviert den Screenreader-Modus zur Barrierefreiheit. - **`--version`**: - Zeigt die Version der CLI an. - **`--openai-logging`**: - - Aktiviert das Logging von OpenAI-API-Aufrufen zur Fehlersuche und Analyse. Dieses Flag überschreibt die `enableOpenAILogging`-Einstellung in der `settings.json`. + - Aktiviert das Logging von OpenAI-API-Aufrufen zum Debuggen und Analysieren. Dieses Flag überschreibt die Einstellung `enableOpenAILogging` in der `settings.json`. - **`--tavily-api-key `**: - - Setzt den Tavily-API-Key für die Web-Suchfunktion dieser Sitzung. + - Setzt den Tavily-API-Schlüssel für die Web-Suche-Funktionalität dieser Sitzung. - Beispiel: `qwen --tavily-api-key tvly-your-api-key-here` ## Context Files (Hierarchischer Instruktionskontext) -Auch wenn es sich nicht um eine strikte Konfiguration des CLI-Verhaltens handelt, sind Context Files (standardmäßig `QWEN.md`, aber konfigurierbar über die Einstellung `contextFileName`) entscheidend für die Konfiguration des _Instruktionskontexts_ (auch als "Memory" bezeichnet). Diese leistungsstarke Funktion ermöglicht es dir, projektspezifische Anweisungen, Coding-Standards oder andere relevante Hintergrundinformationen an das KI-Modell zu übergeben, wodurch die Antworten gezielter und präziser auf deine Anforderungen abgestimmt werden. Die CLI enthält UI-Elemente, wie z. B. einen Indikator in der Fußzeile, der die Anzahl der geladenen Context Files anzeigt, um dich über den aktiven Kontext zu informieren. +Auch wenn es sich nicht um eine direkte Konfiguration des CLI-Verhaltens handelt, sind Context Files (standardmäßig `QWEN.md`, konfigurierbar über die Einstellung `contextFileName`) entscheidend für die Konfiguration des _Instruktionskontexts_ (auch „Memory“ genannt). Diese leistungsstarke Funktion ermöglicht es dir, projektspezifische Anweisungen, Coding-Standards oder andere relevante Hintergrundinformationen an das KI-Modell zu übergeben, wodurch die Antworten gezielter und präziser auf deine Anforderungen abgestimmt werden. Die CLI bietet UI-Elemente, wie z. B. eine Anzeige in der Fußzeile, die die Anzahl der geladenen Context Files zeigt, um dich über den aktiven Kontext zu informieren. -- **Zweck:** Diese Markdown-Dateien enthalten Anweisungen, Richtlinien oder Kontextinformationen, die du möchtest, dass das Qwen-Modell während eurer Interaktionen berücksichtigt. Das System ist so konzipiert, dass es diesen Instruktionskontext hierarchisch verwaltet. +- **Zweck:** Diese Markdown-Dateien enthalten Anweisungen, Richtlinien oder Kontextinformationen, die das Qwen-Modell während der Interaktionen kennen sollte. Das System ist so konzipiert, dass es diesen Instruktionskontext hierarchisch verwaltet. ### Beispiel für den Inhalt einer Context-Datei (z. B. `QWEN.md`) -Hier ist ein konzeptionelles Beispiel dafür, was eine Context-Datei im Stammverzeichnis eines TypeScript-Projekts enthalten könnte: +Hier ist ein konzeptionelles Beispiel dafür, was eine Context-Datei im Root eines TypeScript-Projekts enthalten könnte: ```markdown -# Project: My Awesome TypeScript Library +# Projekt: My Awesome TypeScript Library ## Allgemeine Anweisungen: - Wenn du neuen TypeScript-Code generierst, halte dich bitte an den bestehenden Codierungsstil. - Stelle sicher, dass alle neuen Funktionen und Klassen über JSDoc-Kommentare verfügen. -- Bevorzuge funktionale Programmierparadigmen, wo dies angemessen ist. +- Bevorzuge funktionale Programmierparadigmen, wo es sinnvoll ist. - Der gesamte Code sollte mit TypeScript 5.0 und Node.js 20+ kompatibel sein. ## Codierungsstil: - Verwende 2 Leerzeichen für die Einrückung. - Interface-Namen sollten mit `I` beginnen (z. B. `IUserService`). -- Private Klassenmember sollten mit einem Unterstrich (`_`) beginnen. +- Private Klassenmember sollten mit einem Unterstrich (`_`) gekennzeichnet werden. - Verwende immer strikte Gleichheit (`===` und `!==`). ## Spezifische Komponente: `src/api/client.ts` - Diese Datei behandelt alle ausgehenden API-Anfragen. -- Wenn du neue API-Aufruffunktionen hinzufügst, stelle sicher, dass diese eine robuste Fehlerbehandlung und Protokollierung enthalten. +- Wenn du neue API-Aufruffunktionen hinzufügst, stelle sicher, dass diese eine robuste Fehlerbehandlung und Logging enthalten. - Verwende das vorhandene `fetchWithRetry`-Utility für alle GET-Anfragen. +``` ## Zu den Abhängigkeiten: @@ -461,16 +478,16 @@ Hier ist ein konzeptionelles Beispiel dafür, was eine Context-Datei im Stammver - Falls eine neue Abhängigkeit erforderlich ist, gib bitte den Grund dafür an. ``` -Dieses Beispiel zeigt, wie du allgemeinen Projektkontext, spezifische Coding-Konventionen und sogar Hinweise zu bestimmten Dateien oder Komponenten bereitstellen kannst. Je relevanter und präziser deine Kontextdateien sind, desto besser kann die KI dir helfen. Projekt-spezifische Kontextdateien sind sehr empfohlen, um Konventionen und Kontext festzulegen. +Dieses Beispiel zeigt, wie du allgemeinen Projektkontext, spezifische Coding-Konventionen und sogar Hinweise zu bestimmten Dateien oder Komponenten bereitstellen kannst. Je relevanter und präziser deine Kontextdateien sind, desto besser kann die KI dich unterstützen. Projekt-spezifische Kontextdateien sind sehr empfehlenswert, um Konventionen und Kontext festzulegen. -- **Hierarchisches Laden und Priorität:** Die CLI implementiert ein ausgeklügeltes hierarchisches Speichersystem, indem sie Kontextdateien (z. B. `QWEN.md`) aus mehreren Verzeichnissen lädt. Inhalte aus Dateien weiter unten in dieser Liste (also spezifischer) überschreiben oder ergänzen in der Regel die Inhalte aus Dateien weiter oben (also allgemeiner). Die genaue Reihenfolge der Verkettung und der finale Kontext können mit dem Befehl `/memory show` eingesehen werden. Die typische Ladereihenfolge ist: +- **Hierarchisches Laden und Priorität:** Die CLI implementiert ein ausgeklügeltes hierarchisches Speichersystem, indem sie Kontextdateien (z. B. `QWEN.md`) aus mehreren Verzeichnissen lädt. Inhalte aus Dateien weiter unten in dieser Liste (spezifischer) überschreiben oder ergänzen in der Regel Inhalte aus Dateien weiter oben (allgemeiner). Die genaue Reihenfolge der Verkettung und der finale Kontext können mit dem Befehl `/memory show` eingesehen werden. Die typische Ladereihenfolge ist: 1. **Globale Kontextdatei:** - Ort: `~/.qwen/` (z. B. `~/.qwen/QWEN.md` in deinem Benutzerverzeichnis). - Geltungsbereich: Stellt Standardanweisungen für alle deine Projekte bereit. 2. **Projektstamm & übergeordnete Verzeichnisse:** - - Ort: Die CLI sucht nach der konfigurierten Kontextdatei im aktuellen Arbeitsverzeichnis und dann in jedem übergeordneten Verzeichnis bis entweder zum Projektstamm (erkennbar an einem `.git`-Ordner) oder zu deinem Home-Verzeichnis. + - Ort: Die CLI sucht nach der konfigurierten Kontextdatei im aktuellen Arbeitsverzeichnis und anschließend in jedem übergeordneten Verzeichnis bis zum Projektstamm (erkennbar an einem `.git`-Ordner) oder deinem Home-Verzeichnis. - Geltungsbereich: Stellt Kontext bereit, der für das gesamte Projekt oder einen großen Teil davon relevant ist. - 3. **Unterverzeichnisse (Kontextuell/Lokal):** + 3. **Unterverzeichnisse (kontextuell/lokal):** - Ort: Die CLI scannt auch nach der konfigurierten Kontextdatei in Unterverzeichnissen _unterhalb_ des aktuellen Arbeitsverzeichnisses (unter Beachtung gängiger Ignoriermuster wie `node_modules`, `.git`, etc.). Die Breite dieser Suche ist standardmäßig auf 200 Verzeichnisse begrenzt, kann aber über das Feld `memoryDiscoveryMaxDirs` in deiner `settings.json`-Datei konfiguriert werden. - Geltungsbereich: Ermöglicht hochspezifische Anweisungen, die für eine bestimmte Komponente, ein Modul oder einen Teil deines Projekts relevant sind. - **Verkettung & UI-Anzeige:** Die Inhalte aller gefundenen Kontextdateien werden verkettet (mit Trennzeichen, die ihren Ursprung und Pfad angeben) und als Teil des Systemprompts bereitgestellt. In der CLI-Fußzeile wird die Anzahl der geladenen Kontextdateien angezeigt, was dir einen schnellen visuellen Hinweis auf den aktiven Anweisungskontext gibt. @@ -480,7 +497,7 @@ Dieses Beispiel zeigt, wie du allgemeinen Projektkontext, spezifische Coding-Kon - Verwende `/memory show`, um den aktuell geladenen, kombinierten Anweisungskontext anzuzeigen, sodass du die Hierarchie und den von der KI verwendeten Inhalt überprüfen kannst. - Die vollständigen Details zum `/memory`-Befehl und seinen Unterbefehlen (`show` und `refresh`) findest du in der [Befehlsdokumentation](./commands.md#memory). -Durch das Verstehen und Nutzen dieser Konfigurationsebenen sowie der hierarchischen Struktur von Kontextdateien kannst du den Speicher der KI effektiv verwalten und die Antworten von Qwen Code an deine spezifischen Anforderungen und Projekte anpassen. +Durch das Verstehen und Nutzen dieser Konfigurationsebenen sowie der hierarchischen Struktur von Kontextdateien kannst du den Speicher der KI effektiv verwalten und die Antworten von Qwen Code auf deine spezifischen Bedürfnisse und Projekte zuschneiden. ## Sandboxing @@ -492,7 +509,7 @@ Sandboxing ist standardmäßig deaktiviert, aber du kannst es auf verschiedene A - Durch Setzen der Umgebungsvariable `GEMINI_SANDBOX`. - Sandboxing ist standardmäßig aktiviert, wenn du `--yolo` oder `--approval-mode=yolo` verwendest. -Standardmäßig wird ein vorgefertigtes Docker-Image namens `qwen-code-sandbox` verwendet. +Standardmäßig wird ein vorgefertigtes `qwen-code-sandbox` Docker-Image verwendet. Für projektspezifische Anforderungen kannst du ein eigenes Dockerfile unter `.qwen/sandbox.Dockerfile` im Root-Verzeichnis deines Projekts erstellen. Dieses Dockerfile kann auf dem Basis-Sandbox-Image basieren: @@ -517,23 +534,23 @@ BUILD_SANDBOX=1 qwen -s ## Nutzungsstatistiken -Um uns bei der Verbesserung von Qwen Code zu unterstützen, sammeln wir anonymisierte Nutzungsstatistiken. Diese Daten helfen uns zu verstehen, wie die CLI verwendet wird, häufige Probleme zu identifizieren und neue Funktionen zu priorisieren. +Um uns bei der Verbesserung von Qwen Code zu helfen, sammeln wir anonymisierte Nutzungsdaten. Diese Daten ermöglichen es uns zu verstehen, wie die CLI verwendet wird, häufige Probleme zu erkennen und neue Funktionen gezielt zu priorisieren. **Was wir sammeln:** -- **Tool-Aufrufe:** Wir protokollieren die Namen der aufgerufenen Tools, ob sie erfolgreich waren oder fehlschlugen, sowie deren Ausführungszeit. Wir sammeln weder die an die Tools übergebenen Argumente noch von ihnen zurückgegebene Daten. -- **API-Anfragen:** Wir protokollieren das für jede Anfrage verwendete Modell, die Dauer der Anfrage und ob sie erfolgreich war. Wir sammeln weder den Inhalt der Prompts noch der Antworten. -- **Sitzungsinformationen:** Wir sammeln Informationen zur Konfiguration der CLI, wie z. B. die aktivierten Tools und der Genehmigungsmodus. +- **Tool-Aufrufe:** Wir protokollieren die Namen der aufgerufenen Tools, ob diese erfolgreich oder fehlerhaft ausgeführt wurden sowie deren Ausführungszeit. Die übergebenen Argumente oder von den Tools zurückgegebenen Daten werden nicht erfasst. +- **API-Anfragen:** Wir erfassen das für jede Anfrage verwendete Modell, die Dauer der Anfrage sowie deren Erfolg. Der Inhalt der Prompts oder Responses wird nicht gespeichert. +- **Sitzungsinformationen:** Informationen zur Konfiguration der CLI, wie z. B. aktivierte Tools und der Genehmigungsmodus, werden ebenfalls erfasst. **Was wir NICHT sammeln:** -- **Personenbezogene Daten (PII):** Wir sammeln keine persönlichen Informationen wie Ihren Namen, Ihre E-Mail-Adresse oder API-Keys. -- **Prompt- und Antwortinhalte:** Wir protokollieren weder den Inhalt Ihrer Prompts noch die Antworten des Modells. -- **Dateiinhalte:** Wir protokollieren nicht den Inhalt von Dateien, die von der CLI gelesen oder geschrieben werden. +- **Personenbezogene Daten (PII):** Es werden keinerlei persönliche Informationen wie Name, E-Mail-Adresse oder API-Schlüssel gesammelt. +- **Prompt- und Response-Inhalte:** Weder der Inhalt eurer Prompts noch die Antworten des Modells werden protokolliert. +- **Dateiinhalte:** Jeglicher Inhalt von Dateien, die von der CLI gelesen oder geschrieben werden, wird nicht erfasst. -**So deaktivieren Sie die Sammlung:** +**So deaktivierst du die Sammlung von Nutzungsdaten:** -Sie können die Sammlung von Nutzungsstatistiken jederzeit deaktivieren, indem Sie die Eigenschaft `usageStatisticsEnabled` in Ihrer `settings.json`-Datei auf `false` setzen: +Du kannst die Erfassung von Nutzungsstatistiken jederzeit deaktivieren, indem du die Eigenschaft `usageStatisticsEnabled` in deiner `settings.json`-Datei auf `false` setzt: ```json { @@ -541,12 +558,12 @@ Sie können die Sammlung von Nutzungsstatistiken jederzeit deaktivieren, indem S } ``` -Hinweis: Wenn die Nutzungsstatistiken aktiviert sind, werden Ereignisse an einen Alibaba Cloud RUM-Sammlungsendpunkt gesendet. +Hinweis: Wenn die Nutzungsstatistik aktiviert ist, werden Ereignisse an einen Alibaba Cloud RUM-Sammlungsendpunkt gesendet. - **`enableWelcomeBack`** (boolean): - - **Beschreibung:** Zeigt einen „Willkommen zurück“-Dialog an, wenn Sie zu einem Projekt mit Konversationsverlauf zurückkehren. + - **Beschreibung:** Zeigt beim Zurückkehren zu einem Projekt mit Konversationsverlauf einen „Willkommen zurück“-Dialog an. - **Standardwert:** `true` - **Kategorie:** UI - **Neustart erforderlich:** Nein - **Beispiel:** `"enableWelcomeBack": false` - - **Details:** Wenn aktiviert, erkennt Qwen Code automatisch, ob Sie zu einem Projekt mit einer zuvor generierten Projektzusammenfassung (`.qwen/PROJECT_SUMMARY.md`) zurückkehren, und zeigt einen Dialog an, der es Ihnen ermöglicht, Ihre vorherige Konversation fortzusetzen oder neu zu beginnen. Diese Funktion ist mit dem Befehl `/chat summary` und dem Beendigungsbestätigungsdialog integriert. Weitere Informationen finden Sie in der [Welcome Back Dokumentation](./welcome-back.md). \ No newline at end of file + - **Details:** Ist diese Option aktiviert, erkennt Qwen Code automatisch, wenn du zu einem Projekt mit einer zuvor generierten Projektsynthese (`.qwen/PROJECT_SUMMARY.md`) zurückkehrst, und zeigt einen Dialog an, der dir erlaubt, entweder die vorherige Unterhaltung fortzusetzen oder neu zu beginnen. Diese Funktion ist eng mit dem Befehl `/chat summary` und dem Beenden-Bestätigungsdialog verknüpft. Weitere Informationen findest du in der [Welcome Back Dokumentation](./welcome-back.md). \ No newline at end of file diff --git a/website/content/de/cli/themes.md b/website/content/de/cli/themes.md index 03a691d9..adb0cd75 100644 --- a/website/content/de/cli/themes.md +++ b/website/content/de/cli/themes.md @@ -1,19 +1,19 @@ # Themes -Qwen Code unterstützt eine Vielzahl von Themes, um das Farbschema und das Erscheinungsbild anzupassen. Du kannst das Theme über den Befehl `/theme` oder über die Konfigurationseinstellung `"theme":` ändern, um es deinen Vorlieben anzupassen. +Qwen Code unterstützt eine Vielzahl von Themes, um das Farbschema und das Erscheinungsbild anzupassen. Du kannst das Theme über den Befehl `/theme` oder die Konfigurationseinstellung `"theme":` ändern, um es deinen Vorlieben anzupassen. ## Verfügbare Themes Qwen Code wird mit einer Auswahl vordefinierter Themes geliefert, die du mithilfe des Befehls `/theme` innerhalb der CLI auflisten kannst: -- **Dark Themes:** +- **Dunkle Themes:** - `ANSI` - `Atom One` - `Ayu` - `Default` - `Dracula` - `GitHub` -- **Light Themes:** +- **Helle Themes:** - `ANSI Light` - `Ayu Light` - `Default Light` @@ -23,24 +23,26 @@ Qwen Code wird mit einer Auswahl vordefinierter Themes geliefert, die du mithilf ### Themes ändern -1. Gib `/theme` in Qwen Code ein. -2. Ein Dialog oder eine Auswahl erscheint, in dem die verfügbaren Themes aufgelistet sind. -3. Wähle mit den Pfeiltasten ein Theme aus. Manche Oberflächen bieten eventuell eine Live-Vorschau oder markieren das aktuelle Theme. -4. Bestätige deine Auswahl, um das Theme zu übernehmen. +1. Gib `/theme` in Qwen Code ein. +2. Ein Dialog oder eine Auswahl-Eingabeaufforderung erscheint, in der die verfügbaren Themes aufgelistet sind. +3. Wähle mit den Pfeiltasten ein Theme aus. Manche Oberflächen bieten eventuell eine Live-Vorschau oder markieren das aktuelle Element beim Auswählen. +4. Bestätige deine Auswahl, um das Theme anzuwenden. -### Theme Persistence +**Hinweis:** Wenn in deiner `settings.json`-Datei bereits ein Theme definiert ist (entweder über den Namen oder einen Dateipfad), musst du den `"theme"`-Eintrag aus der Datei entfernen, bevor du das Theme über den `/theme`-Befehl ändern kannst. -Ausgewählte Themes werden in der [Konfiguration](./configuration.md) von Qwen Code gespeichert, sodass deine Präferenz über mehrere Sitzungen hinweg beibehalten wird. +### Speichern von Themes + +Ausgewählte Themes werden in der [Konfiguration](./configuration.md) von Qwen Code gespeichert, sodass deine Präferenz auch über mehrere Sitzungen hinweg beibehalten wird. --- -## Custom Color Themes +## Benutzerdefinierte Farb-Themes -Qwen Code ermöglicht es dir, eigene Custom Color Themes zu erstellen, indem du diese in deiner `settings.json`-Datei definierst. Dadurch hast du volle Kontrolle über die Farbpalette, die in der CLI verwendet wird. +Qwen Code erlaubt dir, eigene benutzerdefinierte Farb-Themes zu erstellen, indem du diese in deiner `settings.json`-Datei definierst. Dadurch hast du volle Kontrolle über die Farbpalette, die in der CLI verwendet wird. -### Wie du ein Custom Theme definierst +### Wie du ein benutzerdefiniertes Theme definierst -Füge einen `customThemes`-Block zu deiner `settings.json`-Datei auf User-, Projekt- oder Systemebene hinzu. Jedes Custom Theme wird als Objekt mit einem eindeutigen Namen und einem Satz von Farbschlüsseln definiert. Zum Beispiel: +Füge einen `customThemes`-Block zu deiner `settings.json`-Datei auf Benutzer-, Projekt- oder Systemebene hinzu. Jedes benutzerdefinierte Theme wird als Objekt mit einem eindeutigen Namen und einer Reihe von Farbschlüsseln definiert. Zum Beispiel: ```json { @@ -85,9 +87,9 @@ Füge einen `customThemes`-Block zu deiner `settings.json`-Datei auf User-, Proj - `DiffRemoved` (optional, für entfernte Zeilen in Diffs) - `DiffModified` (optional, für geänderte Zeilen in Diffs) -**Erforderliche Properties:** +**Erforderliche Eigenschaften:** -- `name` (muss mit dem Key im `customThemes`-Objekt übereinstimmen und ein String sein) +- `name` (muss mit dem Schlüssel im `customThemes`-Objekt übereinstimmen und ein String sein) - `type` (muss der String `"custom"` sein) - `Background` - `Foreground` @@ -101,9 +103,49 @@ Füge einen `customThemes`-Block zu deiner `settings.json`-Datei auf User-, Proj - `Comment` - `Gray` -Du kannst entweder Hex-Codes (z. B. `#FF0000`) **oder** standardisierte CSS-Farbnamen (z. B. `coral`, `teal`, `blue`) für jeden Farbwert verwenden. Eine vollständige Liste der unterstützten Namen findest du unter [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords). +Du kannst entweder Hex-Codes (z. B. `#FF0000`) **oder** Standard-CSS-Farbnamen (z. B. `coral`, `teal`, `blue`) für jeden Farbwert verwenden. Eine vollständige Liste der unterstützten Namen findest du unter [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords). + +Du kannst mehrere benutzerdefinierte Themes definieren, indem du weitere Einträge zum `customThemes`-Objekt hinzufügst. + +### Themes aus einer Datei laden + +Neben der Definition eigener Themes in der `settings.json` kannst du auch direkt ein Theme aus einer JSON-Datei laden, indem du den Dateipfad in deiner `settings.json` angibst. Das ist nützlich, um Themes zu teilen oder sie separat von deiner Hauptkonfiguration zu halten. + +Um ein Theme aus einer Datei zu laden, setze die `theme`-Property in deiner `settings.json` auf den Pfad zu deiner Theme-Datei: + +```json +{ + "theme": "/path/to/your/theme.json" +} +``` + +Die Theme-Datei muss eine gültige JSON-Datei sein und dieselbe Struktur aufweisen wie ein benutzerdefiniertes Theme, das in der `settings.json` definiert ist. + +**Beispiel `my-theme.json`:** + +```json +{ + "name": "My File Theme", + "type": "custom", + "Background": "#282A36", + "Foreground": "#F8F8F2", + "LightBlue": "#82AAFF", + "AccentBlue": "#61AFEF", + "AccentPurple": "#BD93F9", + "AccentCyan": "#8BE9FD", + "AccentGreen": "#50FA7B", + "AccentYellow": "#F1FA8C", + "AccentRed": "#FF5555", + "Comment": "#6272A4", + "Gray": "#ABB2BF", + "DiffAdded": "#A6E3A1", + "DiffRemoved": "#F38BA8", + "DiffModified": "#89B4FA", + "GradientColors": ["#4796E4", "#847ACE", "#C3677F"] +} +``` -Du kannst mehrere Custom Themes definieren, indem du weitere Einträge zum `customThemes`-Objekt hinzufügst. +**Sicherheitshinweis:** Aus Sicherheitsgründen lädt der Gemini CLI nur Theme-Dateien, die sich innerhalb deines Home-Verzeichnisses befinden. Wenn du versuchst, ein Theme von außerhalb deines Home-Verzeichnisses zu laden, wird eine Warnung angezeigt und das Theme wird nicht geladen. Dies verhindert das Laden potenziell schädlicher Theme-Dateien aus nicht vertrauenswürdigen Quellen. ### Beispiel für ein benutzerdefiniertes Theme @@ -141,30 +183,30 @@ Du kannst mehrere Custom Themes definieren, indem du weitere Einträge zum `cust ### GitHub -GitHub Theme +GitHub theme ## Light Themes ### ANSI Light -ANSI Light Theme +ANSI Light theme ### Ayu Light -Ayu Light Theme +Ayu Light theme ### Default Light -Default Light Theme +Default Light theme ### GitHub Light -GitHub Light Theme +GitHub Light theme ### Google Code -Google Code Theme +Google Code theme ### Xcode -Xcode Light Theme \ No newline at end of file +Xcode Light theme \ No newline at end of file diff --git a/website/content/de/deployment.md b/website/content/de/deployment.md index 48748cf6..951b0180 100644 --- a/website/content/de/deployment.md +++ b/website/content/de/deployment.md @@ -10,7 +10,7 @@ Es gibt mehrere Möglichkeiten, Qwen Code auszuführen. Die Option, die du wähl ### 1. Standardinstallation (Empfohlen für typische Benutzer) -Dies ist die empfohlene Methode für Endbenutzer, um Qwen Code zu installieren. Dabei wird das Qwen Code Package aus der NPM Registry heruntergeladen. +Dies ist die empfohlene Methode für Endbenutzer, um Qwen Code zu installieren. Dabei wird das Qwen Code-Paket aus der NPM-Registry heruntergeladen. - **Globale Installation:** @@ -27,7 +27,7 @@ Dies ist die empfohlene Methode für Endbenutzer, um Qwen Code zu installieren. - **Mit NPX ausführen:** ```bash - # Führe die neueste Version von NPM aus, ohne eine globale Installation + # Führt die neueste Version von NPM aus, ohne eine globale Installation npx @qwen-code/qwen-code ``` @@ -35,16 +35,16 @@ Dies ist die empfohlene Methode für Endbenutzer, um Qwen Code zu installieren. ### 2. Ausführen in einer Sandbox (Docker/Podman) -Aus Gründen der Sicherheit und Isolation kann Qwen Code innerhalb eines Containers ausgeführt werden. Dies ist die Standardmethode, wie die CLI Tools ausführt, die Nebenwirkungen haben könnten. +Aus Gründen der Sicherheit und Isolation kann Qwen Code innerhalb eines Containers ausgeführt werden. Dies ist die Standardmethode, wie die CLI Tools mit möglichen Nebenwirkungen ausführt. - **Direkt aus der Registry:** - Du kannst das veröffentlichte Sandbox-Image direkt ausführen. Dies ist nützlich für Umgebungen, in denen du nur Docker zur Verfügung hast und die CLI ausführen möchtest. + Du kannst das veröffentlichte Sandbox-Image direkt ausführen. Dies ist nützlich in Umgebungen, in denen du nur Docker zur Verfügung hast und die CLI ausführen möchtest. ```bash # Run the published sandbox image - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.11 ``` - **Verwendung des `--sandbox` Flags:** - Wenn du Qwen Code lokal installiert hast (gemäß der oben beschriebenen Standardinstallation), kannst du es anweisen, innerhalb des Sandbox-Containers ausgeführt zu werden. + Wenn Qwen Code lokal installiert ist (gemäß der oben beschriebenen Standardinstallation), kannst du es anweisen, innerhalb des Sandbox-Containers ausgeführt zu werden. ```bash qwen --sandbox -y -p "your prompt here" ``` @@ -58,17 +58,17 @@ Mitwirkende am Projekt möchten die CLI direkt aus dem Quellcode ausführen. - **Entwicklungsmodus:** Diese Methode bietet Hot-Reloading und ist nützlich für die aktive Entwicklung. ```bash - # Vom Stammverzeichnis des Repositories + # Vom Root des Repositorys npm run start ``` -- **Produktionsähnlicher Modus (Verknüpftes Paket):** - Diese Methode simuliert eine globale Installation, indem sie Ihr lokales Paket verknüpft. Sie ist nützlich, um einen lokalen Build in einem Produktions-Workflow zu testen. +- **Produktionsähnlicher Modus (Verknüpftes Package):** + Diese Methode simuliert eine globale Installation, indem sie dein lokales Package verknüpft. Sie ist nützlich, um einen lokalen Build in einem Produktions-Workflow zu testen. ```bash - # Verknüpfen Sie das lokale CLI-Paket mit Ihren globalen node_modules + # Verknüpfe das lokale CLI-Package mit deinen globalen node_modules npm link packages/cli - # Jetzt können Sie Ihre lokale Version mit dem Befehl `qwen` ausführen + # Jetzt kannst du deine lokale Version mit dem `qwen` Befehl ausführen qwen ``` @@ -76,23 +76,23 @@ Mitwirkende am Projekt möchten die CLI direkt aus dem Quellcode ausführen. ### 4. Ausführen des neuesten Qwen Code Commits von GitHub -Sie können die zuletzt committete Version von Qwen Code direkt aus dem GitHub-Repository ausführen. Dies ist nützlich, um Funktionen zu testen, die sich noch in der Entwicklung befinden. +Du kannst die zuletzt committete Version von Qwen Code direkt aus dem GitHub-Repository ausführen. Das ist nützlich, um Features zu testen, die sich noch in Entwicklung befinden. ```bash -# CLI direkt aus dem main branch auf GitHub ausführen +# CLI direkt aus dem main Branch auf GitHub ausführen npx https://github.com/QwenLM/qwen-code ``` ## Deployment-Architektur -Die oben beschriebenen Ausführungsmethoden werden durch die folgenden Architekturkomponenten und -prozesse ermöglicht: +Die oben beschriebenen Ausführungsmethoden werden durch die folgenden Architekturkomponenten und Prozesse ermöglicht: **NPM-Pakete** Das Qwen Code-Projekt ist ein Monorepo, das Kernpakete im NPM-Registry veröffentlicht: -- `@qwen-code/qwen-code-core`: Das Backend, das die Logik und Tool-Ausführung übernimmt. +- `@qwen-code/qwen-code-core`: Das Backend, welches Logik und Toolausführung übernimmt. - `@qwen-code/qwen-code`: Das benutzerseitige Frontend. Diese Pakete werden sowohl bei der Standardinstallation als auch beim Ausführen von Qwen Code aus dem Quellcode verwendet. @@ -101,17 +101,17 @@ Diese Pakete werden sowohl bei der Standardinstallation als auch beim Ausführen Es gibt zwei verschiedene Build-Prozesse, abhängig vom Verteilungskanal: -- **NPM-Veröffentlichung:** Für die Veröffentlichung im NPM-Registry wird der TypeScript-Quellcode in `@qwen-code/qwen-code-core` und `@qwen-code/qwen-code` mithilfe des TypeScript Compilers (`tsc`) in Standard-JavaScript transpiliert. Das resultierende `dist/`-Verzeichnis wird dann im NPM-Paket veröffentlicht. Dies ist ein Standardansatz für TypeScript-Bibliotheken. +- **NPM-Veröffentlichung:** Für die Veröffentlichung im NPM-Registry wird der TypeScript-Quellcode in `@qwen-code/qwen-code-core` und `@qwen-code/qwen-code` mithilfe des TypeScript Compilers (`tsc`) in Standard-JavaScript transpiliert. Das resultierende `dist/`-Verzeichnis wird dann im NPM-Paket veröffentlicht. Dies ist ein üblicher Ansatz für TypeScript-Bibliotheken. -- **GitHub `npx`-Ausführung:** Beim direkten Ausführen der neuesten Qwen Code-Version von GitHub wird ein anderer Prozess durch das `prepare`-Script in der `package.json` ausgelöst. Dieses Script nutzt `esbuild`, um die gesamte Anwendung und ihre Abhängigkeiten in eine einzelne, eigenständige JavaScript-Datei zu bündeln. Dieses Bundle wird dynamisch auf dem Rechner des Benutzers erzeugt und ist nicht im Repository enthalten. +- **GitHub `npx`-Ausführung:** Beim direkten Ausführen der neuesten Version von Qwen Code von GitHub aus wird ein anderer Prozess durch das `prepare`-Skript in der `package.json` gestartet. Dieses Skript nutzt `esbuild`, um die gesamte Anwendung samt Abhängigkeiten in eine einzelne, eigenständige JavaScript-Datei zu bündeln. Dieses Bundle wird dynamisch auf dem Rechner des Benutzers erzeugt und nicht im Repository versioniert. **Docker-Sandbox-Image** -Die Docker-basierte Ausführungsmethode wird vom Container-Image `qwen-code-sandbox` unterstützt. Dieses Image wird in einer Container-Registry veröffentlicht und enthält eine global vorinstallierte Version von Qwen Code. +Die Docker-basierte Ausführungsmethode wird vom Container-Image `qwen-code-sandbox` unterstützt. Dieses Image wird in einer Container-Registry veröffentlicht und enthält eine vorinstallierte globale Version von Qwen Code. ## Release-Prozess -Der Release-Prozess ist über GitHub Actions automatisiert. Der Release-Workflow führt folgende Aktionen durch: +Der Release-Prozess ist durch GitHub Actions automatisiert. Der Release-Workflow führt folgende Aktionen durch: 1. Build der NPM-Pakete mit `tsc`. 2. Veröffentlichen der NPM-Pakete in der Artifact Registry. diff --git a/website/content/de/examples/proxy-script.md b/website/content/de/examples/proxy-script.md index 3ee293b8..994a3be7 100644 --- a/website/content/de/examples/proxy-script.md +++ b/website/content/de/examples/proxy-script.md @@ -1,6 +1,6 @@ -# Beispiel-Proxy-Script +# Beispiel Proxy-Skript -Das folgende ist ein Beispiel für ein Proxy-Script, das mit der Umgebungsvariable `GEMINI_SANDBOX_PROXY_COMMAND` verwendet werden kann. Dieses Script erlaubt ausschließlich `HTTPS`-Verbindungen zu `example.com:443` und lehnt alle anderen Anfragen ab. +Das folgende ist ein Beispiel für ein Proxy-Skript, das mit der Umgebungsvariable `GEMINI_SANDBOX_PROXY_COMMAND` verwendet werden kann. Dieses Skript erlaubt nur `HTTPS`-Verbindungen zu `example.com:443` und lehnt alle anderen Anfragen ab. ```javascript #!/usr/bin/env node @@ -12,13 +12,13 @@ Das folgende ist ein Beispiel für ein Proxy-Script, das mit der Umgebungsvariab */ // Beispiel-Proxy-Server, der auf :::8877 lauscht und nur HTTPS-Verbindungen zu example.com erlaubt. -// Setze `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js`, um den Proxy zusammen mit der Sandbox zu starten. -// Teste mit `curl https://example.com` innerhalb der Sandbox (im Shell-Modus oder über das Shell-Tool) +// Setze `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js`, um den Proxy zusammen mit dem Sandbox-Modus zu starten. +// Teste ihn mit `curl https://example.com` innerhalb der Sandbox (im Shell-Modus oder über das Shell-Tool). -import http from 'http'; -import net from 'net'; -import { URL } from 'url'; -import console from 'console'; +import http from 'node:http'; +import net from 'node:net'; +import { URL } from 'node:url'; +import console from 'node:console'; const PROXY_PORT = 8877; const ALLOWED_DOMAINS = ['example.com', 'googleapis.com']; @@ -34,7 +34,7 @@ const server = http.createServer((req, res) => { }); server.on('connect', (req, clientSocket, head) => { - // req.url hat für CONNECT-Anfragen das Format "hostname:port" + // req.url hat bei einer CONNECT-Anfrage das Format "hostname:port" const { port, hostname } = new URL(`http://${req.url}`); console.log(`[PROXY] CONNECT-Anfrage abgefangen für: ${hostname}:${port}`); @@ -47,10 +47,10 @@ server.on('connect', (req, clientSocket, head) => { ) { console.log(`[PROXY] Verbindung zu ${hostname}:${port} erlaubt`); - // TCP-Verbindung zum ursprünglichen Ziel herstellen + // Stelle eine TCP-Verbindung zum ursprünglichen Ziel her. const serverSocket = net.connect(port, hostname, () => { clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n'); - // Tunnel erstellen, indem Daten zwischen Client und Zielserver weitergeleitet werden + // Erstelle einen Tunnel durch Weiterleitung der Daten zwischen Client und Zielserver. serverSocket.write(head); serverSocket.pipe(clientSocket); clientSocket.pipe(serverSocket); @@ -66,7 +66,7 @@ server.on('connect', (req, clientSocket, head) => { } clientSocket.on('error', (err) => { - // Kann passieren, wenn der Client die Verbindung abbricht + // Kann passieren, wenn der Client die Verbindung schließt. console.error(`[PROXY] Client-Socket-Fehler: ${err.message}`); }); }); @@ -75,7 +75,7 @@ server.listen(PROXY_PORT, () => { const address = server.address(); console.log(`[PROXY] Proxy hört auf ${address.address}:${address.port}`); console.log( - `[PROXY] HTTPS-Verbindungen erlaubt zu Domains: ${ALLOWED_DOMAINS.join(', ')}`, + `[PROXY] Erlaubte HTTPS-Verbindungen zu Domains: ${ALLOWED_DOMAINS.join(', ')}`, ); }); ``` \ No newline at end of file diff --git a/website/content/de/extension.md b/website/content/de/extension.md index af0f3864..900353e3 100644 --- a/website/content/de/extension.md +++ b/website/content/de/extension.md @@ -11,7 +11,7 @@ Beim Start sucht Qwen Code nach Extensions in zwei Verzeichnissen: Qwen Code lädt alle Extensions aus beiden Verzeichnissen. Wenn eine Extension mit demselben Namen in beiden Verzeichnissen existiert, hat die Extension im Workspace-Verzeichnis Vorrang. -Innerhalb jedes Verzeichnisses sind einzelne Extensions als Unterverzeichnisse organisiert, die eine `qwen-extension.json` Datei enthalten. Zum Beispiel: +Innerhalb jedes Verzeichnisses existieren einzelne Extensions als Unterverzeichnis, das eine `qwen-extension.json` Datei enthält. Zum Beispiel: `/.qwen/extensions/my-extension/qwen-extension.json` @@ -43,11 +43,11 @@ Wenn Qwen Code startet, lädt es alle Extensions und führt deren Konfiguratione ## Extension Commands -Erweiterungen können [benutzerdefinierte Befehle](./cli/commands.md#custom-commands) bereitstellen, indem sie TOML-Dateien in einem `commands/` Unterverzeichnis innerhalb des Erweiterungsverzeichnisses ablegen. Diese Befehle folgen dem gleichen Format wie benutzer- und projektspezifische Custom Commands und verwenden standardisierte Namenskonventionen. +Erweiterungen können [benutzerdefinierte Befehle](./cli/commands.md#custom-commands) bereitstellen, indem sie TOML-Dateien in einem `commands/` Unterverzeichnis innerhalb des Erweiterungsverzeichnisses ablegen. Diese Befehle folgen demselben Format wie benutzer- und projektspezifische benutzerdefinierte Befehle und verwenden Standard-Namenskonventionen. ### Beispiel -Eine Erweiterung mit dem Namen `gcp` und folgender Struktur: +Eine Erweiterung mit dem Namen `gcp` und der folgenden Struktur: ``` .qwen/extensions/gcp/ @@ -65,12 +65,36 @@ Stellt diese Befehle zur Verfügung: ### Konfliktlösung -Extension Commands haben die niedrigste Priorität. Wenn ein Konflikt mit User- oder Project Commands auftritt: +Erweiterungsbefehle haben die niedrigste Priorität. Wenn ein Konflikt mit Benutzer- oder Projektbefehlen auftritt: -1. **Kein Konflikt**: Das Extension Command verwendet seinen natürlichen Namen (z.B. `/deploy`) -2. **Mit Konflikt**: Das Extension Command wird mit dem Extension Prefix umbenannt (z.B. `/gcp.deploy`) +1. **Kein Konflikt**: Der Erweiterungsbefehl verwendet seinen natürlichen Namen (z. B. `/deploy`) +2. **Mit Konflikt**: Der Erweiterungsbefehl wird mit dem Präfix der Erweiterung umbenannt (z. B. `/gcp.deploy`) -Beispiel: Wenn sowohl ein User als auch die `gcp` Extension ein `deploy` Command definieren: +Wenn zum Beispiel sowohl ein Benutzer als auch die `gcp`-Erweiterung einen `deploy`-Befehl definieren: -- `/deploy` - Führt das User Deploy Command aus -- `/gcp.deploy` - Führt das Extension Deploy Command aus (markiert mit `[gcp]` Tag) \ No newline at end of file +- `/deploy` – Führt den Deploy-Befehl des Benutzers aus +- `/gcp.deploy` – Führt den Deploy-Befehl der Erweiterung aus (gekennzeichnet mit dem Tag `[gcp]`) + +## Installation von Erweiterungen + +Du kannst Erweiterungen mithilfe des `install`-Befehls installieren. Dieser Befehl ermöglicht es, Erweiterungen aus einem Git-Repository oder einem lokalen Pfad zu installieren. + +### Verwendung + +`qwen extensions install | [options]` + +### Optionen + +- `source positional argument`: Die URL eines Git-Repositorys, von dem die Erweiterung installiert werden soll. Das Repository muss eine `qwen-extension.json`-Datei im Stammverzeichnis enthalten. +- `--path `: Der Pfad zu einem lokalen Verzeichnis, das als Erweiterung installiert werden soll. Das Verzeichnis muss eine `qwen-extension.json`-Datei enthalten. + +# Variablen + +Qwen Code Erweiterungen erlauben die Verwendung von Variablen in `qwen-extension.json`. Dies kann nützlich sein, wenn du z. B. das aktuelle Verzeichnis benötigst, um einen MCP-Server mit `"cwd": "${extensionPath}${/}run.ts"` auszuführen. + +**Unterstützte Variablen:** + +| Variable | Beschreibung | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `${extensionPath}` | Der vollständige Pfad der Erweiterung im Dateisystem des Benutzers, z. B. '/Users/username/.qwen/extensions/example-extension'. Symbolische Links werden nicht aufgelöst. | +| `${/} or ${pathSeparator}` | Der Pfadtrenner (unterscheidet sich je nach Betriebssystem). | \ No newline at end of file diff --git a/website/content/de/gemini-ignore.md b/website/content/de/gemini-ignore.md index 103205e5..70a273cf 100644 --- a/website/content/de/gemini-ignore.md +++ b/website/content/de/gemini-ignore.md @@ -2,29 +2,29 @@ Dieses Dokument bietet einen Überblick über die Gemini Ignore (`.geminiignore`) Funktion von Qwen Code. -Qwen Code bietet die Möglichkeit, Dateien automatisch zu ignorieren, ähnlich wie `.gitignore` (verwendet von Git) und `.aiexclude` (verwendet von Gemini Code Assist). Wenn du Pfade zu deiner `.geminiignore` Datei hinzufügst, werden diese von Tools ausgeschlossen, die diese Funktion unterstützen, obwohl sie für andere Services (wie Git) weiterhin sichtbar bleiben. +Qwen Code verfügt über die Möglichkeit, Dateien automatisch zu ignorieren, ähnlich wie `.gitignore` (verwendet von Git) und `.aiexclude` (verwendet von Gemini Code Assist). Das Hinzufügen von Pfaden zu deiner `.geminiignore` Datei schließt diese von Tools aus, die dieses Feature unterstützen, obwohl sie für andere Services (wie Git) weiterhin sichtbar bleiben. ## Wie es funktioniert -Wenn du einen Pfad zu deiner `.geminiignore`-Datei hinzufügst, schließen Tools, die diese Datei berücksichtigen, übereinstimmende Dateien und Verzeichnisse von ihren Operationen aus. Wenn du zum Beispiel den Befehl [`read_many_files`](./tools/multi-file.md) verwendest, werden alle Pfade in deiner `.geminiignore`-Datei automatisch ausgeschlossen. +Wenn du einen Pfad zu deiner `.gemmiignore`-Datei hinzufügst, schließen Tools, die diese Datei berücksichtigen, übereinstimmende Dateien und Verzeichnisse automatisch von ihren Operationen aus. Wenn du zum Beispiel den Befehl [`read_many_files`](./tools/multi-file.md) verwendest, werden alle Pfade in deiner `.geminiignore`-Datei automatisch ignoriert. Im Wesentlichen folgt `.geminiignore` den Konventionen von `.gitignore`-Dateien: -- Leere Zeilen und Zeilen, die mit `#` beginnen, werden ignoriert. -- Standard-Glob-Muster werden unterstützt (wie `*`, `?` und `[]`). -- Ein `/` am Ende matcht nur Verzeichnisse. -- Ein `/` am Anfang verankert den Pfad relativ zur `.geminiignore`-Datei. +- Leere Zeilen sowie Zeilen, die mit `#` beginnen, werden ignoriert. +- Standard-Glob-Muster werden unterstützt (wie z. B. `*`, `?` und `[]`). +- Ein abschließender `/` bewirkt, dass nur Verzeichnisse gematcht werden. +- Ein vorangestellter `/` verankert den Pfad relativ zur Position der `.geminiignore`-Datei. - `!` negiert ein Muster. -Du kannst deine `.geminiignore`-Datei jederzeit aktualisieren. Um die Änderungen anzuwenden, musst du deine Qwen Code-Sitzung neu starten. +Du kannst deine `.geminiignore`-Datei jederzeit aktualisieren. Um die Änderungen zu übernehmen, musst du deine Qwen Code-Sitzung neu starten. ## Wie man `.geminiignore` verwendet Um `.geminiignore` zu aktivieren: -1. Erstelle eine Datei mit dem Namen `.geminiignore` im Stammverzeichnis deines Projektordners. +1. Erstelle eine Datei mit dem Namen `.geminiignore` im Root-Verzeichnis deines Projekts. -Um eine Datei oder ein Verzeichnis zu `.geminiignore` hinzuzufügen: +So fügst du eine Datei oder ein Verzeichnis zur `.geminiignore` hinzu: 1. Öffne deine `.geminiignore`-Datei. 2. Füge den Pfad oder die Datei hinzu, die du ignorieren möchtest, zum Beispiel: `/archive/` oder `apikeys.txt`. @@ -42,7 +42,7 @@ Du kannst `.geminiignore` verwenden, um Verzeichnisse und Dateien zu ignorieren: apikeys.txt ``` -Du kannst Platzhalter in deiner `.geminiignore`-Datei mit `*` verwenden: +Du kannst Wildcards in deiner `.geminiignore`-Datei mit `*` verwenden: ``` diff --git a/website/content/de/ide-integration.md b/website/content/de/ide-integration.md index fc6aa9d4..1b017cd3 100644 --- a/website/content/de/ide-integration.md +++ b/website/content/de/ide-integration.md @@ -1,15 +1,15 @@ # IDE-Integration -Qwen Code kann in deine IDE integriert werden, um ein nahtloseres und kontextbezogenes Erlebnis zu bieten. Diese Integration ermöglicht es der CLI, deinen Workspace besser zu verstehen und leistungsstarke Funktionen wie native Diff-Ansichten direkt im Editor zu aktivieren. +Qwen Code kann in deine IDE integriert werden, um ein nahtloseres und kontextbezogenes Erlebnis zu bieten. Diese Integration ermöglicht es der CLI, deinen Workspace besser zu verstehen und leistungsstarke Funktionen wie native Diff-Ansicht direkt im Editor zu aktivieren. -Derzeit wird als einzige IDE [Visual Studio Code](https://code.visualstudio.com/) sowie andere Editoren unterstützt, die VS Code-Erweiterungen nutzen können. +Derzeit ist nur [Visual Studio Code](https://code.visualstudio.com/) und andere Editoren, die VS Code-Erweiterungen unterstützen, kompatibel. ## Funktionen - **Workspace-Kontext:** Die CLI erhält automatisch Informationen über deinen Workspace, um relevantere und genauere Antworten zu liefern. Dieser Kontext umfasst: - Die **10 zuletzt geöffneten Dateien** in deinem Workspace. - Deine aktuelle Cursor-Position. - - Jeden Text, den du ausgewählt hast (bis zu einem Limit von 16 KB; längere Selektionen werden gekürzt). + - Jeden ausgewählten Text (bis zu einem Limit von 16 KB; längere Selektionen werden gekürzt). - **Native Diff-Ansicht:** Wenn Qwen Code-Änderungen vorschlägt, kannst du die Änderungen direkt in der nativen Diff-Ansicht deiner IDE betrachten. So kannst du die vorgeschlagenen Änderungen nahtlos überprüfen, bearbeiten und entweder annehmen oder ablehnen. @@ -17,19 +17,19 @@ Derzeit wird als einzige IDE [Visual Studio Code](https://code.visualstudio.com/ - `Qwen Code: Run`: Startet eine neue Qwen Code-Sitzung im integrierten Terminal. - `Qwen Code: Accept Diff`: Übernimmt die Änderungen im aktiven Diff-Editor. - `Qwen Code: Close Diff Editor`: Lehnt die Änderungen ab und schließt den aktiven Diff-Editor. - - `Qwen Code: View Third-Party Notices`: Zeigt die Drittanbieter-Hinweise für die Erweiterung an. + - `Qwen Code: View Third-Party Notices`: Zeigt die Third-Party-Hinweise für die Erweiterung an. -## Installation und Setup +## Installation und Einrichtung Es gibt drei Möglichkeiten, die IDE-Integration einzurichten: ### 1. Automatischer Hinweis (empfohlen) -Wenn du Qwen Code in einem unterstützten Editor ausführst, erkennt es automatisch deine Umgebung und fordert dich auf, eine Verbindung herzustellen. Wenn du mit "Ja" antwortest, wird das notwendige Setup automatisch ausgeführt, einschließlich der Installation der Companion-Erweiterung und der Aktivierung der Verbindung. +Wenn du Qwen Code in einem unterstützten Editor ausführst, erkennt es automatisch deine Umgebung und fordert dich auf, eine Verbindung herzustellen. Wenn du mit "Ja" antwortest, wird automatisch das notwendige Setup ausgeführt, einschließlich der Installation der Companion-Erweiterung und Aktivierung der Verbindung. ### 2. Manuelle Installation über CLI -Falls du die Aufforderung zuvor abgelehnt hast oder die Erweiterung manuell installieren möchtest, kannst du den folgenden Befehl innerhalb von Qwen Code ausführen: +Falls du den Hinweis zuvor abgelehnt hast oder die Erweiterung manuell installieren möchtest, kannst du folgenden Befehl innerhalb von Qwen Code ausführen: ``` /ide install @@ -44,7 +44,10 @@ Du kannst die Extension auch direkt aus einem Marketplace installieren. - **Für Visual Studio Code:** Installiere sie über den [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion). - **Für VS Code Forks:** Um Forks von VS Code zu unterstützen, ist die Extension auch im [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion) veröffentlicht. Befolge die Anweisungen deines Editors, um Extensions aus diesem Registry zu installieren. -Nach jeder Installationsmethode wird empfohlen, ein neues Terminal-Fenster zu öffnen, um sicherzustellen, dass die Integration korrekt aktiviert wird. Sobald die Installation abgeschlossen ist, kannst du `/ide enable` verwenden, um dich zu verbinden. +> HINWEIS: +> Die „Qwen Code Companion“-Extension kann weiter unten in den Suchergebnissen erscheinen. Wenn du sie nicht sofort findest, versuche nach unten zu scrollen oder nach „Neu veröffentlicht“ zu sortieren. +> +> Nach der manuellen Installation der Extension musst du `/ide enable` in der CLI ausführen, um die Integration zu aktivieren. ## Verwendung @@ -61,7 +64,7 @@ Du kannst die IDE-Integration direkt über die CLI steuern: /ide disable ``` -Wenn die Verbindung aktiviert ist, wird Qwen Code automatisch versuchen, sich mit der IDE-Companion-Erweiterung zu verbinden. +Wenn die Verbindung aktiviert ist, versucht Qwen Code automatisch, sich mit der IDE-Erweiterung zu verbinden. ### Status prüfen @@ -71,50 +74,50 @@ Um den Verbindungsstatus zu überprüfen und den Kontext anzuzeigen, den die CLI /ide status ``` -Falls eine Verbindung besteht, zeigt dieser Befehl die IDE an, mit der die Verbindung besteht, sowie eine Liste der zuletzt geöffneten Dateien, die bekannt sind. +Falls eine Verbindung besteht, zeigt dieser Befehl die verbundene IDE sowie eine Liste der zuletzt geöffneten Dateien an, die der CLI bekannt sind. -(Hinweis: Die Dateiliste ist auf 10 zuletzt geöffnete Dateien innerhalb deines Workspaces beschränkt und enthält nur lokale Dateien auf der Festplatte.) +(Hinweis: Die Dateiliste ist auf 10 zuletzt verwendete Dateien innerhalb deines Workspaces beschränkt und enthält nur lokale Dateien auf der Festplatte.) ### Arbeiten mit Diffs -Wenn du Gemini bittest, eine Datei zu ändern, kann es direkt eine Diff-Ansicht in deinem Editor öffnen. +Wenn du das Qwen-Modell bittest, eine Datei zu ändern, kann es direkt eine Diff-Ansicht in deinem Editor öffnen. **Um einen Diff zu akzeptieren**, kannst du eine der folgenden Aktionen durchführen: - Klicke auf das **Häkchen-Symbol** in der Titelleiste des Diff-Editors. - Speichere die Datei (z. B. mit `Cmd+S` oder `Ctrl+S`). -- Öffne die Command Palette und führe **Qwen Code: Accept Diff** aus. +- Öffne die Befehlspalette und führe **Qwen Code: Accept Diff** aus. - Antworte mit `yes` in der CLI, wenn du dazu aufgefordert wirst. **Um einen Diff abzulehnen**, kannst du: - Klicke auf das **'x'-Symbol** in der Titelleiste des Diff-Editors. - Schließe den Diff-Editor-Tab. -- Öffne die Command Palette und führe **Qwen Code: Close Diff Editor** aus. +- Öffne die Befehlspalette und führe **Qwen Code: Close Diff Editor** aus. - Antworte mit `no` in der CLI, wenn du dazu aufgefordert wirst. Du kannst auch **die vorgeschlagenen Änderungen direkt in der Diff-Ansicht anpassen**, bevor du sie akzeptierst. -Wenn du in der CLI „Yes, allow always“ auswählst, werden die Änderungen nicht mehr im IDE angezeigt, da sie dann automatisch akzeptiert werden. +Falls du in der CLI „Yes, allow always“ auswählst, werden die Änderungen nicht mehr im IDE angezeigt, da sie dann automatisch akzeptiert werden. ## Verwendung mit Sandboxing Wenn du Qwen Code innerhalb einer Sandbox verwendest, beachte bitte Folgendes: - **Unter macOS:** Die IDE-Integration benötigt Netzwerkzugriff, um mit der IDE-Begleiter-Erweiterung zu kommunizieren. Du musst ein Seatbelt-Profil verwenden, das den Netzwerkzugriff erlaubt. -- **In einem Docker-Container:** Wenn du Qwen Code innerhalb eines Docker- (oder Podman-) Containers ausführst, kann die IDE-Integration dennoch eine Verbindung zur VS Code-Erweiterung auf deinem Host-Rechner herstellen. Die CLI ist so konfiguriert, dass sie automatisch den IDE-Server unter `host.docker.internal` findet. Normalerweise ist keine spezielle Konfiguration erforderlich, aber du solltest sicherstellen, dass dein Docker-Netzwerksetup Verbindungen vom Container zum Host zulässt. +- **In einem Docker-Container:** Wenn du Qwen Code innerhalb eines Docker- (oder Podman-) Containers ausführst, kann die IDE-Integration sich weiterhin mit der VS Code-Erweiterung verbinden, die auf deinem Host-Rechner läuft. Der CLI ist so konfiguriert, dass er automatisch den IDE-Server unter `host.docker.internal` findet. Normalerweise ist keine spezielle Konfiguration erforderlich, aber du solltest sicherstellen, dass dein Docker-Netzwerksetup Verbindungen vom Container zum Host zulässt. ## Fehlerbehebung -Falls Probleme mit der IDE-Integration auftreten, findest du hier einige häufige Fehlermeldungen und deren Lösungen. +Falls Probleme bei der IDE-Integration auftreten, findest du hier einige häufige Fehlermeldungen und deren Lösungen. ### Verbindungsfehler - **Nachricht:** `🔴 Disconnected: Failed to connect to IDE companion extension for [IDE Name]. Please ensure the extension is running and try restarting your terminal. To install the extension, run /ide install.` - - **Ursache:** Qwen Code konnte die notwendigen Umgebungsvariablen (`QWEN_CODE_IDE_WORKSPACE_PATH` oder `QWEN_CODE_IDE_SERVER_PORT`) nicht finden, um sich mit der IDE zu verbinden. Das bedeutet in der Regel, dass die IDE-Begleiter-Extension nicht läuft oder nicht korrekt initialisiert wurde. + - **Ursache:** Qwen Code konnte die erforderlichen Umgebungsvariablen (`QWEN_CODE_IDE_WORKSPACE_PATH` oder `QWEN_CODE_IDE_SERVER_PORT`) nicht finden, um sich mit der IDE zu verbinden. Das bedeutet in der Regel, dass die IDE-Begleitererweiterung nicht läuft oder nicht korrekt initialisiert wurde. - **Lösung:** - 1. Stelle sicher, dass du die **Qwen Code Companion**-Extension in deiner IDE installiert hast und diese aktiviert ist. - 2. Öffne ein neues Terminalfenster in deiner IDE, um sicherzustellen, dass die korrekten Umgebungsvariablen übernommen werden. + 1. Stelle sicher, dass du die Erweiterung **Qwen Code Companion** in deiner IDE installiert hast und diese aktiviert ist. + 2. Öffne ein neues Terminalfenster in deiner IDE, damit die richtige Umgebung übernommen wird. - **Nachricht:** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` - **Ursache:** Die Verbindung zum IDE-Begleiter wurde unerwartet unterbrochen. @@ -123,19 +126,19 @@ Falls Probleme mit der IDE-Integration auftreten, findest du hier einige häufig ### Konfigurationsfehler - **Meldung:** `🔴 Disconnected: Directory mismatch. Qwen Code is running in a different location than the open workspace in [IDE Name]. Please run the CLI from the same directory as your project's root folder.` - - **Ursache:** Das aktuelle Arbeitsverzeichnis der CLI befindet sich außerhalb des Ordners oder Workspaces, der in deiner IDE geöffnet ist. + - **Ursache:** Das aktuelle Arbeitsverzeichnis der CLI befindet sich außerhalb des Ordners oder Workspaces, den du in deiner IDE geöffnet hast. - **Lösung:** Wechsle mit `cd` in das Verzeichnis, das in deiner IDE geöffnet ist, und starte die CLI neu. -- **Meldung:** `🔴 Disconnected: To use this feature, please open a single workspace folder in [IDE Name] and try again.` - - **Ursache:** Du hast entweder mehrere Workspace-Ordner in deiner IDE geöffnet oder es ist überhaupt kein Ordner geöffnet. Die IDE-Integration benötigt einen einzelnen Root-Workspace-Ordner, um korrekt zu funktionieren. - - **Lösung:** Öffne einen einzelnen Projektordner in deiner IDE und starte die CLI neu. +- **Meldung:** `🔴 Disconnected: To use this feature, please open a workspace folder in [IDE Name] and try again.` + - **Ursache:** Du hast keinen Workspace in deiner IDE geöffnet. + - **Lösung:** Öffne einen Workspace in deiner IDE und starte die CLI neu. ### Allgemeine Fehler -- **Meldung:** `IDE-Integration wird in Ihrer aktuellen Umgebung nicht unterstützt. Um diese Funktion zu nutzen, führen Sie Qwen Code in einer der folgenden unterstützten IDEs aus: [Liste der IDEs]` - - **Ursache:** Sie führen Qwen Code in einem Terminal oder einer Umgebung aus, die keine unterstützte IDE ist. - - **Lösung:** Führen Sie Qwen Code aus dem integrierten Terminal einer unterstützten IDE wie VS Code aus. +- **Meldung:** `IDE-Integration wird in deiner aktuellen Umgebung nicht unterstützt. Um diese Funktion zu nutzen, führe Qwen Code in einer der folgenden unterstützten IDEs aus: [Liste der IDEs]` + - **Ursache:** Du führst Qwen Code in einem Terminal oder einer Umgebung aus, die keine unterstützte IDE ist. + - **Lösung:** Führe Qwen Code über das integrierte Terminal einer unterstützten IDE wie VS Code aus. -- **Meldung:** `Für [IDE Name] ist kein Installer verfügbar. Bitte installieren Sie den IDE-Companion manuell über den Marketplace der IDE.` - - **Ursache:** Sie haben `/ide install` ausgeführt, aber die CLI verfügt über keinen automatisierten Installer für Ihre spezifische IDE. - - **Lösung:** Öffnen Sie den Extension-Marketplace Ihrer IDE, suchen Sie nach "Qwen Code Companion" und installieren Sie die Erweiterung manuell. \ No newline at end of file +- **Meldung:** `Es ist kein Installer für die IDE verfügbar. Bitte installiere die Qwen Code Companion-Erweiterung manuell über den Marketplace.` + - **Ursache:** Du hast `/ide install` ausgeführt, aber die CLI verfügt nicht über einen automatisierten Installer für deine spezifische IDE. + - **Lösung:** Öffne den Erweiterungs-Marketplace deiner IDE, suche nach „Qwen Code Companion“ und installiere sie manuell. \ No newline at end of file diff --git a/website/content/de/index.md b/website/content/de/index.md index c3acd31a..98c07c3b 100644 --- a/website/content/de/index.md +++ b/website/content/de/index.md @@ -1,40 +1,40 @@ # Willkommen zur Qwen Code Dokumentation -Diese Dokumentation bietet einen umfassenden Leitfaden zur Installation, Verwendung und Entwicklung von Qwen Code. Dieses Tool ermöglicht es dir, über eine Command-Line Interface (CLI) mit KI-Modellen zu interagieren. +Diese Dokumentation bietet einen umfassenden Leitfaden zur Installation, Nutzung und Entwicklung von Qwen Code. Dieses Tool ermöglicht es dir, über eine command-line interface mit KI-Modellen zu interagieren. ## Übersicht -Qwen Code bringt die Fähigkeiten fortschrittlicher Code-Modelle in dein Terminal, in Form einer interaktiven Read-Eval-Print Loop (REPL)-Umgebung. Qwen Code besteht aus einer clientseitigen Anwendung (`packages/cli`), die mit einem lokalen Server (`packages/core`) kommuniziert. Qwen Code enthält außerdem verschiedene Tools für Aufgaben wie Dateisystemoperationen, Shell-Befehle ausführen und Web-Anfragen, welche vom `packages/core` verwaltet werden. +Qwen Code bringt die Fähigkeiten fortschrittlicher Code-Modelle in dein Terminal, in Form einer interaktiven Read-Eval-Print Loop (REPL) Umgebung. Qwen Code besteht aus einer clientseitigen Anwendung (`packages/cli`), die mit einem lokalen Server (`packages/core`) kommuniziert. Qwen Code enthält außerdem verschiedene Tools für Aufgaben wie Dateisystemoperationen, Shell-Befehle ausführen und Web-Fetching, welche vom `packages/core` verwaltet werden. ## Navigation in der Dokumentation Diese Dokumentation ist in folgende Abschnitte unterteilt: - **[Ausführung und Deployment](./deployment.md):** Informationen zum Ausführen von Qwen Code. -- **[Architektur-Überblick](./architecture.md):** Verständnis des High-Level-Designs von Qwen Code, einschließlich seiner Komponenten und deren Interaktion. -- **CLI Usage:** Dokumentation für `packages/cli`. - - **[CLI Einführung](./cli/index.md):** Übersicht über das Command-Line Interface. +- **[Architekturübersicht](./architecture.md):** Verständnis des High-Level Designs von Qwen Code, einschließlich seiner Komponenten und deren Interaktion. +- **CLI-Nutzung:** Dokumentation für `packages/cli`. + - **[CLI-Einführung](./cli/index.md):** Übersicht über das Command-Line Interface. - **[Befehle](./cli/commands.md):** Beschreibung der verfügbaren CLI-Befehle. - **[Konfiguration](./cli/configuration.md):** Informationen zur Konfiguration der CLI. - **[Checkpointing](./checkpointing.md):** Dokumentation zur Checkpointing-Funktion. - **[Erweiterungen](./extension.md):** Wie du die CLI mit neuer Funktionalität erweiterst. - **[IDE-Integration](./ide-integration.md):** Verbinde die CLI mit deinem Editor. - **[Telemetrie](./telemetry.md):** Übersicht zur Telemetrie in der CLI. -- **Core Details:** Dokumentation für `packages/core`. - - **[Core Einführung](./core/index.md):** Übersicht über die Core-Komponente. - - **[Tools API](./core/tools-api.md):** Informationen dazu, wie der Core Tools verwaltet und bereitstellt. +- **Core-Details:** Dokumentation für `packages/core`. + - **[Core-Einführung](./core/index.md):** Übersicht über die Core-Komponente. + - **[Tools-API](./core/tools-api.md):** Informationen darüber, wie der Core Tools verwaltet und bereitstellt. - **Tools:** - - **[Tools Übersicht](./tools/index.md):** Überblick über die verfügbaren Tools. - - **[Dateisystem-Tools](./tools/file-system.md):** Dokumentation zu den `read_file` und `write_file` Tools. - - **[Multi-File Read Tool](./tools/multi-file.md):** Dokumentation zum `read_many_files` Tool. - - **[Shell Tool](./tools/shell.md):** Dokumentation zum `run_shell_command` Tool. - - **[Web Fetch Tool](./tools/web-fetch.md):** Dokumentation zum `web_fetch` Tool. - - **[Web Search Tool](./tools/web-search.md):** Dokumentation zum `web_search` Tool. - - **[Memory Tool](./tools/memory.md):** Dokumentation zum `save_memory` Tool. + - **[Tools-Übersicht](./tools/index.md):** Überblick über die verfügbaren Tools. + - **[Dateisystem-Tools](./tools/file-system.md):** Dokumentation zu den `read_file`- und `write_file`-Tools. + - **[Multi-File Read Tool](./tools/multi-file.md):** Dokumentation zum `read_many_files`-Tool. + - **[Shell-Tool](./tools/shell.md):** Dokumentation zum `run_shell_command`-Tool. + - **[Web Fetch Tool](./tools/web-fetch.md):** Dokumentation zum `web_fetch`-Tool. + - **[Web Search Tool](./tools/web-search.md):** Dokumentation zum `web_search`-Tool. + - **[Memory Tool](./tools/memory.md):** Dokumentation zum `save_memory`-Tool. - **[Subagents](./subagents.md):** Spezialisierte KI-Assistenten für fokussierte Aufgaben mit umfassender Verwaltung, Konfiguration und Nutzungshinweisen. -- **[Beitragen & Entwicklerhandbuch](../CONTRIBUTING.md):** Informationen für Mitwirkende und Entwickler, inklusive Setup, Build-Prozess, Tests und Coding-Konventionen. -- **[NPM Workspaces und Publishing](./npm.md):** Details zur Verwaltung und Veröffentlichung der Projekt-Pakete. -- **[Fehlerbehebung](./troubleshooting.md):** Lösungen für häufige Probleme und FAQs. -- **[Nutzungsbedingungen und Datenschutzhinweise](./tos-privacy.md):** Informationen zu den Nutzungsbedingungen und Datenschutzbestimmungen bei der Nutzung von Qwen Code. +- **[Beitragen & Entwicklerhandbuch](../CONTRIBUTING.md):** Informationen für Mitwirkende und Entwickler, inklusive Setup, Build-Prozess, Tests und Coding-Standards. +- **[NPM](./npm.md):** Details zur Struktur der Projekt-Pakete. +- **[Fehlerbehebung](./troubleshooting.md):** Lösungen für häufig auftretende Probleme und FAQs. +- **[Allgemeine Geschäftsbedingungen und Datenschutzhinweise](./tos-privacy.md):** Informationen zu den Allgemeinen Geschäftsbedingungen und Datenschutzhinweisen, die bei der Nutzung von Qwen Code gelten. Wir hoffen, diese Dokumentation hilft dir dabei, das Beste aus Qwen Code herauszuholen! \ No newline at end of file diff --git a/website/content/de/keyboard-shortcuts.md b/website/content/de/keyboard-shortcuts.md index e56a6e6b..9ef3f559 100644 --- a/website/content/de/keyboard-shortcuts.md +++ b/website/content/de/keyboard-shortcuts.md @@ -4,20 +4,20 @@ Dieses Dokument listet die verfügbaren Tastaturkürzel in Qwen Code auf. ## Allgemein -| Shortcut | Beschreibung | -| -------- | --------------------------------------------------------------------------------------------------------------------- | -| `Esc` | Schließt Dialoge und Vorschläge. | -| `Ctrl+C` | Bricht die laufende Anfrage ab und leert die Eingabe. Zweimal drücken, um die Anwendung zu beenden. | -| `Ctrl+D` | Beendet die Anwendung, wenn die Eingabe leer ist. Zweimal drücken zur Bestätigung. | -| `Ctrl+L` | Leert den Bildschirm. | -| `Ctrl+O` | Schaltet die Anzeige der Debug-Konsole um. | -| `Ctrl+S` | Ermöglicht die vollständige Ausgabe langer Antworten, deaktiviert das Abschneiden. Verwende den Scrollback deines Terminals, um die gesamte Ausgabe zu sehen. | -| `Ctrl+T` | Schaltet die Anzeige der Tool-Beschreibungen um. | -| `Ctrl+Y` | Schaltet die automatische Genehmigung (YOLO-Modus) für alle Tool-Aufrufe um. | +| Tastenkürzel | Beschreibung | +| ------------ | --------------------------------------------------------------------------------------------------------------------- | +| `Esc` | Schließt Dialoge und Vorschläge. | +| `Ctrl+C` | Bricht die laufende Anfrage ab und leert die Eingabe. Zweimal drücken, um die Anwendung zu beenden. | +| `Ctrl+D` | Beendet die Anwendung, wenn die Eingabe leer ist. Zweimal drücken zur Bestätigung. | +| `Ctrl+L` | Löscht den Bildschirm. | +| `Ctrl+O` | Schaltet die Anzeige der Debug-Konsole ein/aus. | +| `Ctrl+S` | Ermöglicht die vollständige Ausgabe langer Antworten durch Deaktivierung der Kürzung. Verwende den Scrollback deines Terminals, um die gesamte Ausgabe zu sehen. | +| `Ctrl+T` | Schaltet die Anzeige der Tool-Beschreibungen ein/aus. | +| `Shift+Tab` | Wechselt zwischen den Genehmigungsmodi (`plan` → `default` → `auto-edit` → `yolo`). | ## Eingabeaufforderung -| Tastenkürzel | Beschreibung | +| Tastenkürzel | Beschreibung | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `!` | Shell-Modus umschalten, wenn die Eingabe leer ist. | | `\` (am Zeilenende) + `Enter` | Neue Zeile einfügen. | @@ -27,28 +27,29 @@ Dieses Dokument listet die verfügbaren Tastaturkürzel in Qwen Code auf. | `Tab` | Aktuellen Vorschlag vervollständigen, falls vorhanden. | | `Pfeil nach oben` | Durch den Eingabeverlauf nach oben navigieren. | | `Strg+A` / `Pos1` | Cursor an den Anfang der Zeile bewegen. | -| `Strg+B` / `Pfeil nach links` | Cursor ein Zeichen nach links bewegen. | +| `Strg+B` / `Pfeil links` | Cursor ein Zeichen nach links bewegen. | | `Strg+C` | Eingabeaufforderung leeren | +| `Esc` (doppeltes Drücken) | Eingabeaufforderung leeren. | | `Strg+D` / `Entf` | Zeichen rechts vom Cursor löschen. | | `Strg+E` / `Ende` | Cursor ans Ende der Zeile bewegen. | -| `Strg+F` / `Pfeil nach rechts` | Cursor ein Zeichen nach rechts bewegen. | +| `Strg+F` / `Pfeil rechts` | Cursor ein Zeichen nach rechts bewegen. | | `Strg+H` / `Rücktaste` | Zeichen links vom Cursor löschen. | | `Strg+K` | Von der Cursorposition bis zum Ende der Zeile löschen. | -| `Strg+Pfeil nach links` / `Meta+Pfeil nach links` / `Meta+B` | Cursor ein Wort nach links bewegen. | +| `Strg+Pfeil links` / `Meta+Pfeil links` / `Meta+B` | Cursor ein Wort nach links bewegen. | | `Strg+N` | Durch den Eingabeverlauf nach unten navigieren. | | `Strg+P` | Durch den Eingabeverlauf nach oben navigieren. | -| `Strg+Pfeil nach rechts` / `Meta+Pfeil nach rechts` / `Meta+F` | Cursor ein Wort nach rechts bewegen. | +| `Strg+Pfeil rechts` / `Meta+Pfeil rechts` / `Meta+F` | Cursor ein Wort nach rechts bewegen. | | `Strg+U` | Von der Cursorposition bis zum Anfang der Zeile löschen. | -| `Strg+V` | Inhalt der Zwischenablage einfügen. Wenn die Zwischenablage ein Bild enthält, wird dieses gespeichert und ein Verweis darauf in die Eingabe eingefügt. | +| `Strg+V` | Inhalt aus der Zwischenablage einfügen. Wenn die Zwischenablage ein Bild enthält, wird dieses gespeichert und ein Verweis darauf in die Eingabe eingefügt. | | `Strg+W` / `Meta+Rücktaste` / `Strg+Rücktaste` | Wort links vom Cursor löschen. | | `Strg+X` / `Meta+Enter` | Aktuelle Eingabe in einem externen Editor öffnen. | ## Vorschläge -| Tastenkürzel | Beschreibung | +| Shortcut | Beschreibung | | --------------- | ----------------------------------------- | | `Down Arrow` | Nach unten durch die Vorschläge navigieren. | -| `Tab` / `Enter` | Den ausgewählten Vorschlag übernehmen. | +| `Tab` / `Enter` | Den ausgewählten Vorschlag akzeptieren. | | `Up Arrow` | Nach oben durch die Vorschläge navigieren. | ## Radio Button Select @@ -59,10 +60,10 @@ Dieses Dokument listet die verfügbaren Tastaturkürzel in Qwen Code auf. | `Enter` | Auswahl bestätigen. | | `Up Arrow` / `k` | Auswahl nach oben bewegen. | | `1-9` | Eintrag über seine Nummer auswählen. | -| (mehrere Ziffern) | Für Einträge mit Nummern größer 9 die Ziffernfolge schnell hintereinander drücken, um den entsprechenden Eintrag auszuwählen. | +| (mehrziffrig) | Für Einträge mit Nummern größer 9 die Ziffernfolge schnell hintereinander drücken, um den entsprechenden Eintrag auszuwählen. | ## IDE-Integration -| Shortcut | Beschreibung | -| -------- | ------------------------------------- | +| Shortcut | Beschreibung | +| -------- | -------------------------------------- | | `Ctrl+G` | Kontext-CLI anzeigen, die von der IDE empfangen wurde | \ No newline at end of file diff --git a/website/content/de/qwen-ignore.md b/website/content/de/qwen-ignore.md new file mode 100644 index 00000000..1b7dbf62 --- /dev/null +++ b/website/content/de/qwen-ignore.md @@ -0,0 +1,62 @@ +# Dateien ignorieren + +Dieses Dokument bietet einen Überblick über die Qwen Ignore (`.qwenignore`) Funktion von Qwen Code. + +Qwen Code unterstützt die automatische Ignorierung von Dateien, ähnlich wie `.gitignore` (verwendet von Git). Wenn Sie Pfade zu Ihrer `.qwenignore` Datei hinzufügen, werden diese von Tools ausgeschlossen, die diese Funktion unterstützen, obwohl sie für andere Services (wie Git) weiterhin sichtbar bleiben. + +## Wie es funktioniert + +Wenn du einen Pfad zu deiner `.qwenignore`-Datei hinzufügst, schließen Tools, die diese Datei berücksichtigen, passende Dateien und Verzeichnisse von ihren Operationen aus. Zum Beispiel werden bei Verwendung des [`read_many_files`](./tools/multi-file.md)-Befehls alle Pfade in deiner `.qwenignore`-Datei automatisch ignoriert. + +Im Wesentlichen folgt `.qwenignore` den Konventionen von `.gitignore`-Dateien: + +- Leere Zeilen und Zeilen, die mit `#` beginnen, werden ignoriert. +- Standard-Glob-Muster werden unterstützt (wie `*`, `?` und `[]`). +- Ein `/` am Ende matcht nur Verzeichnisse. +- Ein `/` am Anfang verankert den Pfad relativ zur `.qwenignore`-Datei. +- `!` negiert ein Muster. + +Du kannst deine `.qwenignore`-Datei jederzeit aktualisieren. Um die Änderungen zu übernehmen, musst du deine Qwen Code-Sitzung neu starten. + +## Wie man `.qwenignore` verwendet + +Um `.qwenignore` zu aktivieren: + +1. Erstelle eine Datei mit dem Namen `.qwenignore` im Stammverzeichnis deines Projektordners. + +Um eine Datei oder ein Verzeichnis zu `.qwenignore` hinzuzufügen: + +1. Öffne deine `.qwenignore`-Datei. +2. Füge den Pfad oder die Datei hinzu, die du ignorieren möchtest, zum Beispiel: `/archive/` oder `apikeys.txt`. + +### `.qwenignore` Beispiele + +Du kannst `.qwenignore` verwenden, um Verzeichnisse und Dateien zu ignorieren: + +``` + +# Schließe dein /packages/-Verzeichnis und alle Unterverzeichnisse aus +/packages/ + +# Schließe deine apikeys.txt-Datei aus +apikeys.txt +``` + +Du kannst Platzhalter in deiner `.qwenignore`-Datei mit `*` verwenden: + +``` + +# Schließe alle .md-Dateien aus +*.md +``` + +Schließlich kannst du Dateien und Verzeichnisse von der Ausschlussliste mit `!` wieder einbeziehen: + +``` + +# Schließe alle .md-Dateien außer README.md aus +*.md +!README.md +``` + +Um Pfade aus deiner `.qwenignore`-Datei zu entfernen, lösche die entsprechenden Zeilen. \ No newline at end of file diff --git a/website/content/de/subagents.md b/website/content/de/subagents.md index 00cb2a7c..c4b74712 100644 --- a/website/content/de/subagents.md +++ b/website/content/de/subagents.md @@ -1,31 +1,31 @@ # Subagents -Subagents sind spezialisierte KI-Assistenten, die bestimmte Arten von Aufgaben innerhalb von Qwen Code übernehmen. Sie ermöglichen es dir, gezielte Arbeiten an KI-Agenten zu delegieren, die mit aufgabenspezifischen Prompts, Tools und Verhaltensweisen konfiguriert sind. +Subagents sind spezialisierte KI-Assistenten, die bestimmte Arten von Aufgaben innerhalb von Qwen Code übernehmen. Sie ermöglichen es dir, gezielte Arbeit an KI-Agenten zu delegieren, die mit aufgabenspezifischen Prompts, Tools und Verhaltensweisen konfiguriert sind. ## Was sind Subagents? Subagents sind unabhängige KI-Assistenten, die: -- **Spezialisierung auf bestimmte Aufgaben** - Jeder Subagent ist mit einem fokussierten System-Prompt für bestimmte Arbeitstypen konfiguriert -- **Separater Kontext** - Sie führen ihren eigenen Konversationsverlauf unabhängig von deinem Hauptchat -- **Kontrollierte Tool-Nutzung** - Du kannst festlegen, auf welche Tools jeder Subagent Zugriff hat -- **Autonome Arbeitsweise** - Sobald eine Aufgabe übergeben wurde, arbeiten sie eigenständig bis zur Fertigstellung oder zum Fehler -- **Detailliertes Feedback** - Du kannst ihren Fortschritt, die Tool-Nutzung und Ausführungsstatistiken in Echtzeit verfolgen +- **Spezialisierung auf bestimmte Aufgaben** – Jeder Subagent ist mit einem fokussierten System-Prompt für bestimmte Arbeitstypen konfiguriert +- **Separater Kontext** – Sie führen ihren eigenen Konversationsverlauf, getrennt von deinem Hauptchat +- **Kontrollierter Tool-Zugriff** – Du kannst festlegen, welche Tools jeder Subagent nutzen darf +- **Autonome Arbeitsweise** – Sobald eine Aufgabe erteilt wurde, arbeiten sie eigenständig bis zur Fertigstellung oder zum Fehler +- **Detailliertes Feedback** – Du kannst ihren Fortschritt, die verwendeten Tools und Ausführungsstatistiken in Echtzeit verfolgen ## Hauptvorteile - **Task Specialization**: Erstelle Agents, die für bestimmte Workflows optimiert sind (Testing, Documentation, Refactoring, etc.) - **Context Isolation**: Halte spezialisierte Arbeiten separat von deiner Hauptunterhaltung - **Reusability**: Speichere und wiederverwende Agent-Konfigurationen über Projekte und Sessions hinweg -- **Controlled Access**: Beschränke, welche Tools jeder Agent aus Sicherheits- und Fokusgründen nutzen kann +- **Controlled Access**: Beschränke, welche Tools jeder Agent aus Sicherheits- und Fokusgründen verwenden kann - **Progress Visibility**: Überwache die Agent-Ausführung mit Echtzeit-Fortschrittsaktualisierungen ## Wie Subagents funktionieren 1. **Configuration**: Du erstellst Subagent-Konfigurationen, die ihr Verhalten, ihre Tools und System-Prompts definieren 2. **Delegation**: Die Haupt-KI kann automatisch Aufgaben an geeignete Subagents delegieren -3. **Execution**: Subagents arbeiten unabhängig und nutzen ihre konfigurierten Tools, um Aufgaben abzuschließen -4. **Results**: Sie liefern Ergebnisse und Ausführungsübersichten an die Hauptunterhaltung zurück +3. **Execution**: Subagents arbeiten unabhängig und verwenden ihre konfigurierten Tools, um Aufgaben abzuschließen +4. **Results**: Sie geben Ergebnisse und Ausführungsübersichten an die Hauptunterhaltung zurück ## Erste Schritte @@ -48,16 +48,16 @@ Subagents sind unabhängige KI-Assistenten, die: Zeige und verwalte deine konfigurierten Subagenten. 3. **Nutze Subagenten automatisch**: - Frage einfach die Haupt-KI, Aufgaben zu erledigen, die den Spezialisierungen deiner Subagenten entsprechen. Die KI wird automatisch die passende Arbeit delegieren. + Frage einfach die Haupt-KI, Aufgaben durchzuführen, die den Spezialisierungen deiner Subagenten entsprechen. Die KI wird automatisch passende Arbeit delegieren. ### Beispielhafte Nutzung ``` User: "Bitte schreibe umfassende Tests für das Authentifizierungsmodul" -AI: Ich delegiere das an deinen Testing-Spezialisten-Subagenten. -[Delegiert an "testing-expert" Subagenten] -[Zeigt Fortschritt der Testerstellung in Echtzeit] +AI: Ich übertrage dies an deinen Testing-Spezialisten-Subagenten. +[Delegiert an "testing-expert" Subagent] +[Zeigt Echtzeit-Fortschritt der Testerstellung] [Gibt fertige Testdateien und Ausführungsübersicht zurück] ``` @@ -69,9 +69,9 @@ Subagenten werden über den Slash-Befehl `/agents` und seine Unterbefehle verwal #### `/agents create` -Erstellt einen neuen Subagenten über einen geführten Schritt-für-Schritt-Wizard. +Erstellt einen neuen Subagenten durch einen geführten Schritt-für-Schritt-Wizard. -**Verwendung:** +**Nutzung:** ``` /agents create @@ -94,7 +94,7 @@ Subagents werden als Markdown-Dateien an zwei Orten gespeichert: - **Projektebene**: `.qwen/agents/` (hat Vorrang) - **Benutzerebene**: `~/.qwen/agents/` (Fallback) -So kannst du sowohl projektspezifische Agents als auch persönliche Agents haben, die in allen Projekten funktionieren. +So können Sie sowohl projektspezifische Agents als auch persönliche Agents haben, die in allen Projekten funktionieren. ### Dateiformat @@ -109,9 +109,9 @@ description: Kurze Beschreibung, wann und wie dieser Agent verwendet wird tools: tool1, tool2, tool3 # Optional --- -Der System-Prompt-Inhalt kommt hier hin. +System Prompt-Inhalt kommt hierhin. Mehrere Absätze werden unterstützt. -Du kannst ${variable} Templating für dynamische Inhalte verwenden. +Sie können ${variable} Templating für dynamischen Inhalt verwenden. ``` #### Beispielverwendung @@ -122,15 +122,37 @@ name: project-documenter description: Erstellt Projektdokumentation und README-Dateien --- -Sie sind ein Dokumentationsspezialist für das ${project_name}-Projekt. +Du bist ein Dokumentationsspezialist für das ${project_name}-Projekt. -Ihre Aufgabe: ${task_description} +Deine Aufgabe: ${task_description} Arbeitsverzeichnis: ${current_directory} Generiert am: ${timestamp} -Konzentrieren Sie sich auf die Erstellung klarer, umfassender Dokumentation, die sowohl -neuen Mitwirkenden als auch Endbenutzern hilft, das Projekt zu verstehen. +Konzentriere dich darauf, klare und umfassende Dokumentation zu erstellen, die sowohl +neuen Mitwirkenden als auch Endnutzern hilft, das Projekt zu verstehen. +``` + +## Effektive Nutzung von Subagents + +### Automatische Delegation + +Qwen Code delegiert proaktiv Aufgaben basierend auf: + +- Der Aufgabenbeschreibung in deiner Anfrage +- Dem description-Feld in den Subagent-Konfigurationen +- Dem aktuellen Kontext und den verfügbaren Tools + +Um eine proaktivere Nutzung von Subagents zu fördern, füge Formulierungen wie "PROACTIVELY verwenden" oder "MUSS VERWENDET WERDEN" in dein description-Feld ein. + +### Expliziter Aufruf + +Fordere einen bestimmten Subagenten an, indem du ihn in deinem Befehl erwähnst: + +``` +> Lass den testing-expert Subagenten Unit-Tests für das Payment-Modul erstellen +> Lass den documentation-writer Subagenten die API-Referenz aktualisieren +> Lass den react-specialist Subagenten die Performance dieser Komponente optimieren ``` ## Beispiele @@ -153,7 +175,7 @@ Du bist ein Testing-Spezialist, der sich auf die Erstellung hochwertiger, wartba Deine Expertise umfasst: - Unit-Testing mit geeignetem Mocking und Isolation -- Integrationstests für Komponenten-Interaktionen +- Integrationstests für Komponenteninteraktionen - Testgetriebene Entwicklung (TDD) - Identifizierung von Edge Cases und umfassende Abdeckung - Performance- und Lasttests, wenn angebracht @@ -163,7 +185,7 @@ Für jede Testing-Aufgabe: 1. Analysiere die Code-Struktur und Abhängigkeiten 2. Identifiziere Kernfunktionalitäten, Edge Cases und Fehlerbedingungen 3. Erstelle umfassende Testsuiten mit beschreibenden Namen -4. Integriere korrektes Setup/Teardown und aussagekräftige Assertions +4. Integriere ordnungsgemäßes Setup/Teardown und aussagekräftige Assertions 5. Füge Kommentare für komplexe Testszenarien hinzu 6. Stelle sicher, dass Tests wartbar sind und DRY-Prinzipien befolgen @@ -174,12 +196,12 @@ Fokussiere dich sowohl auf positive als auch negative Testfälle. **Anwendungsfälle:** - "Schreibe Unit-Tests für den Authentication Service" -- "Erstelle Integrationstests für den Payment Processing Workflow" -- "Füge Testabdeckung für Edge Cases im Data Validation Modul hinzu" +- "Erstelle Integrationstests für den Payment-Processing-Workflow" +- "Füge Testabdeckung für Edge Cases im Data-Validation-Modul hinzu" #### Documentation Writer -Spezialisiert auf das Erstellen von klaren, umfassenden Dokumentationen. +Spezialisiert auf die Erstellung von klaren, umfassenden Dokumentationen. ```markdown --- @@ -196,7 +218,7 @@ Entwickler als auch Endnutzer ansprechen. Konzentriere dich auf: **Für API-Dokumentationen:** - Klare Endpoint-Beschreibungen mit Beispielen -- Detaillierte Parameterbeschreibungen inkl. Typen und Einschränkungen +- Detaillierte Parameterbeschreibungen inkl. Typen und Constraints - Dokumentation der Response-Formate - Erläuterung der Fehlercodes - Authentifizierungsanforderungen @@ -217,7 +239,7 @@ Entwickler als auch Endnutzer ansprechen. Konzentriere dich auf: - Einrichtung der Entwicklungsumgebung Überprüfe immer die Codebeispiele und stelle sicher, dass die Dokumentation -mit der tatsächlichen Implementierung übereinstimmt. Nutze klare Überschriften, +mit der tatsächlichen Implementierung übereinstimmt. Verwende klare Überschriften, Aufzählungen und Beispiele. ``` @@ -225,7 +247,7 @@ Aufzählungen und Beispiele. - "Erstelle eine API-Dokumentation für die User-Management-Endpoints" - "Schreibe eine umfassende README für dieses Projekt" -- "Dokumentiere den Deployment-Prozess inkl. Troubleshooting-Schritten" +- "Dokumentiere den Deployment-Prozess mit Schritten zur Fehlerbehebung" #### Code Reviewer @@ -267,16 +289,16 @@ Prioritize issues by impact and provide rationale for recommendations. - "Check the performance implications of this database query logic" - "Evaluate the code structure and suggest improvements" -### Technologie-Spezifische Agents +### Technologie-spezifische Agents #### React Specialist -Optimiert für React-Entwicklung, Hooks und Komponentenmuster. +Optimiert für React-Entwicklung, Hooks und Component-Patterns. ```markdown --- name: react-specialist -description: Experte in React-Entwicklung, Hooks, Komponentenmustern und modernen React-Best-Practices +description: Experte in React-Entwicklung, Hooks, Component-Patterns und modernen React-Best-Practices tools: read_file, write_file, read_many_files, run_shell_command --- @@ -284,31 +306,31 @@ Du bist ein React-Spezialist mit tiefgreifender Expertise in moderner React-Entw Deine Expertise umfasst: -- **Komponentendesign**: Funktionale Komponenten, Custom Hooks, Kompositions-Muster +- **Component Design**: Function Components, Custom Hooks, Composition Patterns - **State Management**: useState, useReducer, Context API und externe Libraries - **Performance**: React.memo, useMemo, useCallback, Code Splitting -- **Testing**: React Testing Library, Jest, Strategien zum Testen von Komponenten -- **TypeScript-Integration**: Korrekte Typisierung von Props, Hooks und Komponenten -- **Moderne Muster**: Suspense, Error Boundaries, Concurrent Features +- **Testing**: React Testing Library, Jest, Component-Testing-Strategien +- **TypeScript Integration**: Korrekte Typisierung für Props, Hooks und Components +- **Moderne Patterns**: Suspense, Error Boundaries, Concurrent Features Für React-Aufgaben: -1. Verwende standardmäßig funktionale Komponenten und Hooks +1. Verwende standardmäßig Function Components und Hooks 2. Implementiere korrekte TypeScript-Typisierung 3. Folge React-Best-Practices und Konventionen 4. Berücksichtige Performance-Auswirkungen 5. Integriere angemessenes Error Handling -6. Schreibe testbaren und wartbaren Code +6. Schreibe testbaren, wartbaren Code -Bleibe immer auf dem neuesten Stand der React-Best-Practices und vermeide veraltete Muster. -Fokussiere dich auf Barrierefreiheit und Aspekte der Benutzererfahrung. +Bleibe immer auf dem neuesten Stand der React-Best-Practices und vermeide deprecated Patterns. +Fokussiere dich auf Accessibility und User Experience Aspekte. ``` -**Anwendungsfälle:** +**Use Cases:** -- "Erstelle eine wiederverwendbare Data-Table-Komponente mit Sortierung und Filterung" -- "Implementiere einen Custom Hook für API-Datenabruf mit Caching" -- "Refaktoriere diese Klassenkomponente, um moderne React-Muster zu verwenden" +- "Erstelle eine wiederverwendbare Data-Table-Component mit Sorting und Filtering" +- "Implementiere einen Custom Hook für API-Data-Fetching mit Caching" +- "Refactore diese Class Component, um moderne React-Patterns zu verwenden" #### Python-Experte @@ -327,7 +349,7 @@ Deine Expertise umfasst: - **Core Python**: Pythonic Patterns, Datenstrukturen, Algorithmen - **Frameworks**: Django, Flask, FastAPI, SQLAlchemy -- **Testing**: pytest, unittest, Mocking, test-driven development +- **Testing**: pytest, unittest, Mocking, Test-driven Development - **Data Science**: pandas, numpy, matplotlib, Jupyter Notebooks - **Async Programming**: asyncio, async/await Patterns - **Package Management**: pip, poetry, Virtual Environments @@ -337,19 +359,19 @@ Für Python-Aufgaben: 1. Befolge die PEP 8 Style Guidelines 2. Verwende Type Hints für bessere Code-Dokumentation -3. Implementiere korrektes Error Handling mit spezifischen Exceptions +3. Implementiere korrekte Fehlerbehandlung mit spezifischen Exceptions 4. Schreibe umfassende Docstrings 5. Berücksichtige Performance und Speicherverbrauch 6. Integriere angemessenes Logging 7. Schreibe testbaren, modularen Code -Fokus auf sauberen, wartbaren Python-Code, der Community-Standards entspricht. +Fokussiere dich auf sauberen, wartbaren Python-Code, der Community-Standards entspricht. ``` **Anwendungsfälle:** -- "Erstelle einen FastAPI-Service für User Authentication mit JWT Tokens" -- "Implementiere eine Datenverarbeitungs-Pipeline mit pandas und Error Handling" +- "Erstelle einen FastAPI-Service für User Authentication mit JWT-Tokens" +- "Implementiere eine Data Processing Pipeline mit pandas und Fehlerbehandlung" - "Schreibe ein CLI-Tool mit argparse und umfassender Hilfe-Dokumentation" ## Best Practices @@ -424,7 +446,7 @@ description: A helpful code reviewer ### Configuration Best Practices -#### Richtlinien für System Prompts +#### Richtlinien für Systemprompts **Sei spezifisch bezüglich der Expertise:** @@ -465,6 +487,6 @@ Always follow these standards: - **Tool-Einschränkungen**: Subagents haben nur Zugriff auf ihre konfigurierten Tools - **Sandboxing**: Die Ausführung aller Tools folgt demselben Sicherheitsmodell wie die direkte Tool-Nutzung - **Audit Trail**: Alle Aktionen von Subagents werden protokolliert und in Echtzeit sichtbar -- **Zugriffskontrolle**: Die Trennung auf Projekt- und Benutzerebene sorgt für angemessene Grenzen +- **Zugriffskontrolle**: Trennung auf Projekt- und Benutzerebene stellt angemessene Grenzen sicher - **Sensible Informationen**: Vermeide es, Secrets oder Zugangsdaten in Agent-Konfigurationen einzubeziehen -- **Produktionsumgebungen**: Erwäge den Einsatz separater Agents für Produktions- und Entwicklungs-Umgebungen \ No newline at end of file +- **Produktionsumgebungen**: Erwäge den Einsatz separater Agents für Produktions- vs. Entwicklungs-Umgebungen \ No newline at end of file diff --git a/website/content/de/telemetry.md b/website/content/de/telemetry.md index a926cc19..189660fb 100644 --- a/website/content/de/telemetry.md +++ b/website/content/de/telemetry.md @@ -1,6 +1,6 @@ # Qwen Code Observability Guide -Telemetry liefert Daten über die Performance, den Zustand und die Nutzung von Qwen Code. Wenn du es aktivierst, kannst du Abläufe überwachen, Probleme debuggen und die Tool-Nutzung über Traces, Metriken und strukturierte Logs optimieren. +Telemetry stellt Daten über die Performance, den Zustand und die Nutzung von Qwen Code bereit. Wenn du es aktivierst, kannst du Abläufe überwachen, Probleme debuggen und die Tool-Nutzung mithilfe von Traces, Metriken und strukturierten Logs optimieren. Das Telemetriesystem von Qwen Code basiert auf dem **[OpenTelemetry] (OTEL)**-Standard, wodurch du Daten an jedes kompatible Backend senden kannst. @@ -10,9 +10,9 @@ Das Telemetriesystem von Qwen Code basiert auf dem **[OpenTelemetry] (OTEL)**-St Du kannst Telemetrie auf verschiedene Arten aktivieren. Die Konfiguration erfolgt hauptsächlich über die [`.qwen/settings.json`-Datei](./cli/configuration.md) und Umgebungsvariablen, aber CLI-Flags können diese Einstellungen für eine bestimmte Sitzung überschreiben. -### Reihenfolge der Priorität +### Rangfolge -Die folgende Liste zeigt die Priorität beim Anwenden der Telemetrie-Einstellungen, wobei Einträge weiter oben eine höhere Priorität haben: +Die folgende Liste zeigt die Rangfolge beim Anwenden der Telemetrie-Einstellungen, wobei Einträge weiter oben eine höhere Priorität haben: 1. **CLI-Flags (für den `qwen`-Befehl):** - `--telemetry` / `--no-telemetry`: Überschreibt `telemetry.enabled`. @@ -28,14 +28,14 @@ Die folgende Liste zeigt die Priorität beim Anwenden der Telemetrie-Einstellung 1. **Benutzereinstellungsdatei (`~/.qwen/settings.json`):** Werte aus dem `telemetry`-Objekt in dieser globalen Benutzerdatei. -1. **Standardwerte:** Werden angewandt, wenn sie nicht durch eine der oben genannten Quellen gesetzt wurden. +1. **Standardwerte:** Werden angewendet, wenn sie nicht durch eine der oben genannten Optionen gesetzt wurden. - `telemetry.enabled`: `false` - `telemetry.target`: `local` - `telemetry.otlpEndpoint`: `http://localhost:4317` - `telemetry.logPrompts`: `true` -**Für das Skript `npm run telemetry -- --target=`:** -Das `--target`-Argument dieses Skripts überschreibt _nur_ den Wert von `telemetry.target` für die Dauer und den Zweck dieses Skripts (d. h. zur Auswahl des zu startenden Collectors). Es ändert nicht dauerhaft deine `settings.json`. Das Skript prüft zunächst in der `settings.json`, ob dort ein `telemetry.target` definiert ist, und verwendet diesen als Standardwert. +**Für das `npm run telemetry -- --target=`-Skript:** +Das `--target`-Argument dieses Skripts überschreibt _nur_ den `telemetry.target` für die Dauer und den Zweck dieses Skripts (d. h. zur Auswahl des zu startenden Collectors). Es ändert nicht dauerhaft deine `settings.json`. Das Skript prüft zunächst in der `settings.json`, ob ein `telemetry.target` als Standardwert vorhanden ist. ### Beispiel-Einstellungen @@ -55,18 +55,18 @@ Der folgende Code kann in deine Workspace-Einstellungen (`.qwen/settings.json`) Du kannst alle Telemetriedaten in eine Datei exportieren, um sie lokal zu inspizieren. -Um den Dateiexport zu aktivieren, verwende das Flag `--telemetry-outfile` mit einem Pfad zu deiner gewünschten Ausgabedatei. Dies muss mit `--telemetry-target=local` ausgeführt werden. +Um den Export in eine Datei zu aktivieren, verwende das Flag `--telemetry-outfile` mit einem Pfad zur gewünschten Ausgabedatei. Dies muss zusammen mit `--telemetry-target=local` ausgeführt werden. ```bash -# Setze den Pfad zur gewünschten Ausgabedatei +# Lege deinen gewünschten Ausgabedateipfad fest TELEMETRY_FILE=".qwen/telemetry.log" # Führe Qwen Code mit lokaler Telemetrie aus # HINWEIS: --telemetry-otlp-endpoint="" ist erforderlich, um den Standard- -# OTLP-Exporter zu überschreiben und sicherzustellen, dass die Telemetrie in die lokale Datei geschrieben wird. +# OTLP-Exporter zu überschreiben und sicherzustellen, dass die Telemetriedaten in die lokale Datei geschrieben werden. qwen --telemetry \ --telemetry-target=local \ --telemetry-otlp-endpoint="" \ @@ -82,15 +82,15 @@ Du kannst festlegen, welches Protokoll verwendet werden soll, über das Flag `-- oder die Einstellung `telemetry.otlpProtocol` in deiner `settings.json`-Datei. Weitere Informationen findest du in der [Konfigurationsdokumentation](./cli/configuration.md#--telemetry-otlp-protocol). -Weitere Informationen zur Standardkonfiguration von OTEL Exportern findest du in der [Dokumentation][otel-config-docs]. +Weitere Informationen zur Standardkonfiguration des OTEL Exporters findest du in der [Dokumentation][otel-config-docs]. [otel-config-docs]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/ -### Local +### Lokal -Verwende den Befehl `npm run telemetry -- --target=local`, um den Prozess zur Einrichtung einer lokalen Telemetrie-Pipeline zu automatisieren. Dazu gehört auch das Konfigurieren der erforderlichen Einstellungen in deiner `.qwen/settings.json`-Datei. Das zugrunde liegende Skript installiert `otelcol-contrib` (den OpenTelemetry Collector) und `jaeger` (das Jaeger UI zur Anzeige von Traces). So gehst du vor: +Verwende den Befehl `npm run telemetry -- --target=local`, um den Prozess zur Einrichtung einer lokalen Telemetrie-Pipeline zu automatisieren. Dazu gehört auch das Konfigurieren der erforderlichen Einstellungen in deiner Datei `.qwen/settings.json`. Das zugrunde liegende Skript installiert `otelcol-contrib` (den OpenTelemetry Collector) und `jaeger` (das Jaeger UI zum Anzeigen von Traces). So gehst du vor: -1. **Befehl ausführen**: +1. **Führe den Befehl aus**: Führe den Befehl im Root-Verzeichnis des Repositorys aus: ```bash @@ -98,24 +98,24 @@ Verwende den Befehl `npm run telemetry -- --target=local`, um den Prozess zur Ei ``` Das Skript führt folgende Aktionen durch: - - Lädt Jaeger und OTEL herunter, falls erforderlich. + - Lädt Jaeger und OTEL herunter, falls nötig. - Startet eine lokale Jaeger-Instanz. - - Startet einen OTEL-Collector, der für den Empfang von Daten aus Qwen Code konfiguriert ist. - - Aktiviert Telemetrie automatisch in deinen Workspace-Einstellungen. + - Startet einen OTEL-Collector, der für den Empfang von Daten von Qwen Code konfiguriert ist. + - Aktiviert die Telemetrie automatisch in deinen Workspace-Einstellungen. - Deaktiviert beim Beenden die Telemetrie. -1. **Traces anzeigen**: +2. **Traces anzeigen**: Öffne deinen Webbrowser und navigiere zu **http://localhost:16686**, um auf das Jaeger UI zuzugreifen. Dort kannst du detaillierte Traces der Qwen Code-Vorgänge einsehen. -1. **Logs und Metriken prüfen**: - Das Skript leitet die Ausgabe des OTEL-Collectors (einschließlich Logs und Metriken) in die Datei `~/.qwen/tmp//otel/collector.log` um. Das Skript stellt Links zur Verfügung, um deine Telemetriedaten (Traces, Metriken, Logs) lokal anzusehen, sowie einen Befehl, um diese live im Terminal zu verfolgen. +3. **Logs und Metriken prüfen**: + Das Skript leitet die Ausgabe des OTEL Collectors (einschließlich Logs und Metriken) in die Datei `~/.qwen/tmp//otel/collector.log` um. Es werden Links angezeigt, über die du deine Telemetriedaten (Traces, Metriken, Logs) lokal einsehen kannst, sowie ein Befehl, um diese live mitzuverfolgen. -1. **Dienste stoppen**: +4. **Dienste stoppen**: Drücke `Ctrl+C` im Terminal, in dem das Skript läuft, um den OTEL Collector und die Jaeger-Dienste zu stoppen. ### Google Cloud -Verwende den Befehl `npm run telemetry -- --target=gcp`, um automatisch einen lokalen OpenTelemetry Collector einzurichten, der Daten an dein Google Cloud-Projekt weiterleitet. Dazu gehören auch die notwendigen Konfigurationen in deiner `.qwen/settings.json`-Datei. Das zugrunde liegende Skript installiert `otelcol-contrib`. So gehst du vor: +Verwende den Befehl `npm run telemetry -- --target=gcp`, um automatisch einen lokalen OpenTelemetry Collector einzurichten, der Daten an dein Google Cloud-Projekt weiterleitet. Dazu gehören auch die notwendigen Konfigurationen in deiner `.qwen/settings.json`-Datei. Das zugrunde liegende Skript installiert `otelcol-contrib`. So geht's: 1. **Voraussetzungen**: - Du benötigst eine Google Cloud Project ID. @@ -124,7 +124,7 @@ Verwende den Befehl `npm run telemetry -- --target=gcp`, um automatisch einen lo export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" ``` - Authentifiziere dich bei Google Cloud (z. B. mit `gcloud auth application-default login` oder stelle sicher, dass `GOOGLE_APPLICATION_CREDENTIALS` gesetzt ist). - - Stelle sicher, dass dein Google Cloud-Konto bzw. dein Service-Account über die erforderlichen IAM-Rollen verfügt: „Cloud Trace Agent“, „Monitoring Metric Writer“ und „Logs Writer“. + - Stelle sicher, dass dein Google Cloud-Konto bzw. dein Service-Account über die erforderlichen IAM-Rollen verfügt: "Cloud Trace Agent", "Monitoring Metric Writer" und "Logs Writer". 1. **Befehl ausführen**: Führe den Befehl im Root-Verzeichnis deines Repositorys aus: @@ -134,7 +134,7 @@ Verwende den Befehl `npm run telemetry -- --target=gcp`, um automatisch einen lo ``` Das Skript wird: - - Die Binary `otelcol-contrib` herunterladen (falls erforderlich). + - Die `otelcol-contrib`-Binary herunterladen (falls nötig). - Einen OTEL Collector starten, der so konfiguriert ist, dass er Daten von Qwen Code empfängt und an dein angegebenes Google Cloud-Projekt exportiert. - Telemetrie automatisch aktivieren und den Sandbox-Modus in deinen Workspace-Einstellungen (`.qwen/settings.json`) deaktivieren. - Direkte Links bereitstellen, um Traces, Metriken und Logs in der Google Cloud Console anzuzeigen. @@ -147,7 +147,7 @@ Verwende den Befehl `npm run telemetry -- --target=gcp`, um automatisch einen lo Verwende die vom Skript bereitgestellten Links, um zur Google Cloud Console zu navigieren und deine Traces, Metriken und Logs einzusehen. 1. **Lokale Collector-Logs einsehen**: - Das Skript leitet die Ausgabe des lokalen OTEL Collectors in die Datei `~/.qwen/tmp//otel/collector-gcp.log` um. Es stellt auch Links und Befehle bereit, um die Logs lokal einzusehen oder zu tailen. + Das Skript leitet die Ausgabe des lokalen OTEL Collectors in die Datei `~/.qwen/tmp//otel/collector-gcp.log` um. Es stellt auch Links und Befehle bereit, um die Logs lokal anzusehen oder zu tailen. 1. **Dienst stoppen**: Drücke `Strg+C` im Terminal, in dem das Skript läuft, um den OTEL Collector zu stoppen. @@ -179,9 +179,10 @@ Logs sind zeitgestempelte Aufzeichnungen spezifischer Ereignisse. Die folgenden - `qwen-code.user_prompt`: Dieses Ereignis tritt auf, wenn ein Benutzer einen Prompt absendet. - **Attribute**: - - `prompt_length` - - `prompt` (dieses Attribut wird ausgelassen, wenn `log_prompts_enabled` auf `false` konfiguriert ist) - - `auth_type` + - `prompt_length` (int) + - `prompt_id` (string) + - `prompt` (string, dieses Attribut wird ausgelassen, wenn `log_prompts_enabled` auf `false` konfiguriert ist) + - `auth_type` (string) - `qwen-code.tool_call`: Dieses Ereignis tritt bei jedem Funktionsaufruf auf. - **Attribute**: @@ -233,21 +234,21 @@ Logs sind zeitgestempelte Aufzeichnungen spezifischer Ereignisse. Die folgenden ### Metriken -Metriken sind numerische Messungen des Verhaltens über die Zeit. Die folgenden Metriken werden für Qwen Code gesammelt (die Metriknamen bleiben aus Kompatibilitätsgründen `qwen-code.*`): +Metriken sind numerische Messungen des Verhaltens über einen bestimmten Zeitraum. Für Qwen Code werden die folgenden Metriken gesammelt (die Metriknamen bleiben aus Kompatibilitätsgründen `qwen-code.*`): - `qwen-code.session.count` (Counter, Int): Wird bei jedem CLI-Start um eins erhöht. -- `qwen-code.tool.call.count` (Counter, Int): Zählt die Tool-Aufrufe. +- `qwen-code.tool.call.count` (Counter, Int): Zählt die Anzahl der Tool-Aufrufe. - **Attribute**: - `function_name` - `success` (boolean) - - `decision` (string: "accept", "reject" oder "modify", falls zutreffend) - - `tool_type` (string: "mcp" oder "native", falls zutreffend) + - `decision` (string: "accept", "reject", oder "modify", falls zutreffend) + - `tool_type` (string: "mcp", oder "native", falls zutreffend) - `qwen-code.tool.call.latency` (Histogram, ms): Misst die Latenz von Tool-Aufrufen. - **Attribute**: - `function_name` - - `decision` (string: "accept", "reject" oder "modify", falls zutreffend) + - `decision` (string: "accept", "reject", oder "modify", falls zutreffend) - `qwen-code.api.request.count` (Counter, Int): Zählt alle API-Anfragen. - **Attribute**: @@ -262,20 +263,21 @@ Metriken sind numerische Messungen des Verhaltens über die Zeit. Die folgenden - `qwen-code.token.usage` (Counter, Int): Zählt die Anzahl der verwendeten Tokens. - **Attribute**: - `model` - - `type` (string: "input", "output", "thought", "cache" oder "tool") + - `type` (string: "input", "output", "thought", "cache", oder "tool") - `qwen-code.file.operation.count` (Counter, Int): Zählt Dateioperationen. - **Attribute**: - `operation` (string: "create", "read", "update"): Der Typ der Dateioperation. - `lines` (Int, falls zutreffend): Anzahl der Zeilen in der Datei. - `mimetype` (string, falls zutreffend): Mimetype der Datei. - - `extension` (string, falls zutreffend): Dateierweiterung der Datei. + - `extension` (string, falls zutreffend): Dateiendung der Datei. - `ai_added_lines` (Int, falls zutreffend): Anzahl der von der KI hinzugefügten/geänderten Zeilen. - `ai_removed_lines` (Int, falls zutreffend): Anzahl der von der KI entfernten/geänderten Zeilen. - - `user_added_lines` (Int, falls zutreffend): Anzahl der vom Benutzer hinzugefügten/geänderten Zeilen in KI-vorgeschlagenen Änderungen. - - `user_removed_lines` (Int, falls zutreffend): Anzahl der vom Benutzer entfernten/geänderten Zeilen in KI-vorgeschlagenen Änderungen. + - `user_added_lines` (Int, falls zutreffend): Anzahl der vom Benutzer hinzugefügten/geänderten Zeilen in den von der KI vorgeschlagenen Änderungen. + - `user_removed_lines` (Int, falls zutreffend): Anzahl der vom Benutzer entfernten/geänderten Zeilen in den von der KI vorgeschlagenen Änderungen. + - `programming_language` (string, falls zutreffend): Die Programmiersprache der Datei. -- `qwen-code.chat_compression` (Counter, Int): Zählt Chat-Komprimierungsvorgänge. +- `qwen-code.chat_compression` (Counter, Int): Zählt die Chat-Komprimierungsoperationen. - **Attribute**: - - `tokens_before` (Int): Anzahl der Tokens im Kontext vor der Komprimierung. - - `tokens_after` (Int): Anzahl der Tokens im Kontext nach der Komprimierung. \ No newline at end of file + - `tokens_before`: (Int): Anzahl der Tokens im Kontext vor der Komprimierung. + - `tokens_after`: (Int): Anzahl der Tokens im Kontext nach der Komprimierung. \ No newline at end of file diff --git a/website/content/de/tools/multi-file.md b/website/content/de/tools/multi-file.md index b9cd779f..287719df 100644 --- a/website/content/de/tools/multi-file.md +++ b/website/content/de/tools/multi-file.md @@ -4,12 +4,12 @@ Dieses Dokument beschreibt das `read_many_files` Tool für Qwen Code. ## Beschreibung -Verwende `read_many_files`, um Inhalte aus mehreren Dateien zu lesen, die durch Pfade oder Glob-Muster angegeben werden. Das Verhalten dieses Tools hängt von den bereitgestellten Dateien ab: +Verwende `read_many_files`, um Inhalte aus mehreren Dateien zu lesen, die durch Pfade oder Glob-Muster angegeben werden. Das Verhalten dieses Tools hängt von den übergebenen Dateien ab: -- Für Textdateien verknüpft dieses Tool deren Inhalt zu einem einzigen String. -- Für Bilddateien (z. B. PNG, JPEG), PDF-, Audio- (MP3, WAV) und Videodateien (MP4, MOV) liest es diese als base64-kodierte Daten, sofern sie explizit nach Name oder Erweiterung angefordert werden. +- Für Textdateien verbindet dieses Tool deren Inhalt zu einem einzigen String. +- Für Bilddateien (z. B. PNG, JPEG), PDFs, Audiodateien (MP3, WAV) und Videodateien (MP4, MOV) liest es diese ein und gibt sie als base64-kodierte Daten zurück, sofern sie explizit nach Name oder Erweiterung angefordert wurden. -`read_many_files` kann für Aufgaben wie das Überblicken einer Codebasis, das Finden von Implementierungen bestimmter Funktionen, das Überprüfen von Dokumentationen oder das Sammeln von Kontext aus mehreren Konfigurationsdateien verwendet werden. +`read_many_files` kann für Aufgaben wie das Überblicken einer Codebasis, das Finden bestimmter Funktionalität, das Prüfen von Dokumentationen oder das Sammeln von Kontext aus mehreren Konfigurationsdateien verwendet werden. **Hinweis:** `read_many_files` sucht nach Dateien anhand der angegebenen Pfade oder Glob-Muster. Ein Verzeichnispfad wie `"/docs"` liefert ein leeres Ergebnis; das Tool benötigt ein Muster wie `"/docs/*"` oder `"/docs/*.md"`, um die relevanten Dateien zu identifizieren. @@ -17,25 +17,26 @@ Verwende `read_many_files`, um Inhalte aus mehreren Dateien zu lesen, die durch `read_many_files` akzeptiert die folgenden Argumente: -- `paths` (list[string], required): Ein Array von Glob-Patterns oder Pfaden relativ zum Zielverzeichnis des Tools (z. B. `["src/**/*.ts"]`, `["README.md", "docs/*", "assets/logo.png"]`). -- `exclude` (list[string], optional): Glob-Patterns für Dateien/Verzeichnisse, die ausgeschlossen werden sollen (z. B. `["**/*.log", "temp/"]`). Diese werden zu den Standard-Excludes hinzugefügt, wenn `useDefaultExcludes` auf `true` gesetzt ist. +- `paths` (list[string], erforderlich): Ein Array von Glob-Patterns oder Pfaden relativ zum Zielverzeichnis des Tools (z. B. `["src/**/*.ts"]`, `["README.md", "docs/*", "assets/logo.png"]`). +- `exclude` (list[string], optional): Glob-Patterns für Dateien/Verzeichnisse, die ausgeschlossen werden sollen (z. B. `["**/*.log", "temp/"]`). Diese werden zu den Standard-Ausschlüssen hinzugefügt, wenn `useDefaultExcludes` auf `true` gesetzt ist. - `include` (list[string], optional): Zusätzliche Glob-Patterns, die explizit eingeschlossen werden sollen. Diese werden mit `paths` zusammengeführt (z. B. `["*.test.ts"]`, um Testdateien gezielt hinzuzufügen, falls sie allgemein ausgeschlossen wurden, oder `["images/*.jpg"]`, um bestimmte Bildtypen einzuschließen). - `recursive` (boolean, optional): Gibt an, ob rekursiv gesucht werden soll. Dies wird hauptsächlich durch `**` in den Glob-Patterns gesteuert. Standardwert ist `true`. - `useDefaultExcludes` (boolean, optional): Legt fest, ob eine Liste von Standard-Ausschlussmustern angewendet wird (z. B. `node_modules`, `.git`, binäre Dateien, die keine Bilder oder PDFs sind). Standardwert ist `true`. -- `respect_git_ignore` (boolean, optional): Gibt an, ob `.gitignore`-Muster beim Suchen von Dateien berücksichtigt werden sollen. Standardwert ist `true`. +- `respect_git_ignore` (boolean, optional): Bestimmt, ob `.gitignore`-Muster beim Suchen von Dateien berücksichtigt werden sollen. Standardwert ist `true`. ## Wie man `read_many_files` mit Qwen Code verwendet -`read_many_files` sucht nach Dateien, die den angegebenen `paths`- und `include`-Mustern entsprechen, und berücksichtigt dabei `exclude`-Muster sowie Standard-Ausschlüsse (falls aktiviert). +`read_many_files` sucht nach Dateien, die den angegebenen `paths` und `include`-Mustern entsprechen, wobei `exclude`-Muster und Standard-Ausschlüsse (falls aktiviert) berücksichtigt werden. -- **Für Textdateien**: Der Inhalt jeder gefundenen Datei wird gelesen (es wird versucht, Binärdateien zu überspringen, es sei denn, sie wurden explizit als Bild/PDF angefordert). Die Inhalte werden zu einem einzigen String zusammengefasst, wobei zwischen den Inhalten der einzelnen Dateien der Trenner `--- {filePath} ---` eingefügt wird. Standardmäßig wird UTF-8-Encoding verwendet. -- **Für Bilder und PDFs**: Wenn explizit nach Name oder Erweiterung angefordert (z. B. `paths: ["logo.png"]` oder `include: ["*.pdf"]`), liest das Tool die Datei und gibt ihren Inhalt als base64-kodierten String zurück. -- **Für andere Binärdateien**: Das Tool versucht, diese zu erkennen und zu überspringen (solche, die weder zu den gängigen Bild-/PDF-Typen gehören noch explizit angefordert wurden), indem es auf das Vorhandensein von Null-Bytes im Anfangsbereich prüft. +- Für Textdateien: liest der Tool den Inhalt jeder gefundenen Datei (und versucht, Binärdateien zu überspringen, es sei denn, sie wurden explizit als Bild/PDF angefordert) und fügt diesen zu einem einzigen String zusammen. Zwischen den Inhalten der einzelnen Dateien wird ein Trennzeichen `--- {filePath} ---` eingefügt. Standardmäßig wird UTF-8-Encoding verwendet. +- Der Tool fügt nach der letzten Datei ein `--- End of content ---` hinzu. +- Für Bilder und PDF-Dateien: wenn diese explizit nach Name oder Erweiterung angefordert wurden (z. B. `paths: ["logo.png"]` oder `include: ["*.pdf"]`), liest der Tool die Datei und gibt ihren Inhalt als base64-kodierten String zurück. +- Der Tool versucht, andere Binärdateien (die weder gängigen Bild-/PDF-Typen entsprechen noch explizit angefordert wurden) durch Prüfung auf Null-Bytes im Anfangsinhalt zu erkennen und zu überspringen. Verwendung: ``` -read_many_files(paths=["Deine Dateien oder Pfade hier."], include=["Zusätzliche Dateien zum Einbinden."], exclude=["Dateien zum Ausschließen."], recursive=False, useDefaultExcludes=false, respect_git_ignore=true) +read_many_files(paths=["Deine Dateien oder Pfade hier."], include=["Zusätzliche Dateien zum Einbeziehen."], exclude=["Auszuschließende Dateien."], recursive=False, useDefaultExcludes=false, respect_git_ignore=true) ``` ## `read_many_files` Beispiele @@ -46,7 +47,7 @@ Lese alle TypeScript-Dateien im `src` Verzeichnis: read_many_files(paths=["src/**/*.ts"]) ``` -Lese die Haupt-README, alle Markdown-Dateien im `docs` Verzeichnis und ein bestimmtes Logo-Bild, ausgenommen eine bestimmte Datei: +Lese die Haupt-README, alle Markdown-Dateien im `docs` Verzeichnis und ein bestimmtes Logo-Bild, ausschließlich einer bestimmten Datei: ``` read_many_files(paths=["README.md", "docs/**/*.md", "assets/logo.png"], exclude=["docs/OLD_README.md"]) @@ -62,7 +63,7 @@ read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], - **Umgang mit Binärdateien:** - **Bild-/PDF-/Audio-/Videodateien:** Das Tool kann gängige Bildformate (PNG, JPEG, etc.), PDF-, Audio- (mp3, wav) und Videodateien (mp4, mov) lesen und gibt diese als base64-kodierte Daten zurück. Diese Dateien _müssen_ explizit über die `paths`- oder `include`-Muster angesprochen werden (z. B. durch Angabe des exakten Dateinamens wie `video.mp4` oder eines Musters wie `*.mov`). - - **Andere Binärdateien:** Das Tool versucht, andere Binärdateitypen zu erkennen und zu überspringen, indem es den Anfang der Datei auf null-Bytes prüft. Solche Dateien werden von der Ausgabe ausgeschlossen. + - **Andere Binärdateien:** Das Tool versucht, andere Binärdateitypen zu erkennen und überspringt diese, indem es den Anfang der Datei auf null-Bytes prüft. Solche Dateien werden von der Ausgabe ausgeschlossen. - **Performance:** Das Lesen einer sehr großen Anzahl an Dateien oder einzelner sehr großer Dateien kann ressourcenintensiv sein. -- **Pfadangaben:** Stelle sicher, dass Pfade und Glob-Muster korrekt relativ zum Zielverzeichnis des Tools angegeben sind. Bei Bild-/PDF-Dateien solltest du sicherstellen, dass die Muster spezifisch genug sind, um sie einzuschließen. -- **Standardmäßig ausgeschlossene Pfade:** Beachte die standardmäßig ausgeschlossenen Pfade (wie `node_modules`, `.git`) und verwende `useDefaultExcludes=False`, wenn du diese überschreiben musst – aber tue dies mit Vorsicht. \ No newline at end of file +- **Pfadangaben:** Stelle sicher, dass Pfade und Glob-Muster korrekt relativ zum Zielverzeichnis des Tools angegeben sind. Bei Bild-/PDF-Dateien sollten die Muster spezifisch genug sein, um diese einzuschließen. +- **Standardmäßig ausgeschlossene Pfade:** Beachte die standardmäßig ausgeschlossenen Muster (wie `node_modules`, `.git`) und verwende `useDefaultExcludes=False`, wenn du diese überschreiben musst – aber tue dies mit Bedacht. \ No newline at end of file diff --git a/website/content/de/troubleshooting.md b/website/content/de/troubleshooting.md index 37a06d27..b1275a25 100644 --- a/website/content/de/troubleshooting.md +++ b/website/content/de/troubleshooting.md @@ -1,8 +1,8 @@ # Leitfaden zur Fehlerbehebung -Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, darunter Themen wie: +Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, darunter Themen zu: -- Authentifizierungs- oder Login-Fehler +- Authentifizierungs- oder Login-Fehlern - Häufig gestellte Fragen (FAQs) - Debugging-Tipps - Vorhandene GitHub Issues, die deinem Problem ähneln, oder Erstellen neuer Issues @@ -10,14 +10,14 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da ## Authentifizierungs- oder Login-Fehler - **Fehler: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` oder `unable to get local issuer certificate`** - - **Ursache:** Du befindest dich möglicherweise in einem Unternehmensnetzwerk mit einer Firewall, die SSL/TLS-Verkehr abfängt und untersucht. Dies erfordert oft ein benutzerdefiniertes Root-CA-Zertifikat, das von Node.js vertraut werden muss. + - **Ursache:** Du befindest dich möglicherweise in einem Unternehmensnetzwerk mit einer Firewall, die SSL/TLS-Datenverkehr abfängt und untersucht. Dies erfordert oft ein benutzerdefiniertes Root-CA-Zertifikat, das von Node.js vertraut werden muss. - **Lösung:** Setze die Umgebungsvariable `NODE_EXTRA_CA_CERTS` auf den absoluten Pfad deiner Unternehmens-Root-CA-Zertifikatsdatei. - Beispiel: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` ## Häufig gestellte Fragen (FAQs) - **Q: Wie aktualisiere ich Qwen Code auf die neueste Version?** - - A: Wenn du es global über `npm` installiert hast, aktualisiere es mit dem Befehl `npm install -g @qwen-code/qwen-code@latest`. Wenn du es aus dem Quellcode kompiliert hast, pull die neuesten Änderungen aus dem Repository und führe dann den Befehl `npm run build` aus, um es neu zu erstellen. + - A: Wenn du es global über `npm` installiert hast, kannst du es mit dem Befehl `npm install -g @qwen-code/qwen-code@latest` aktualisieren. Wenn du es aus dem Quellcode kompiliert hast, ziehe die neuesten Änderungen aus dem Repository und führe dann den Befehl `npm run build` aus, um es neu zu erstellen. - **Q: Wo werden die Qwen Code Konfigurations- oder Einstellungsdateien gespeichert?** - A: Die Qwen Code Konfiguration wird in zwei `settings.json` Dateien gespeichert: @@ -27,7 +27,7 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da Weitere Informationen findest du unter [Qwen Code Konfiguration](./cli/configuration.md). - **Q: Warum sehe ich keine zwischengespeicherten Token-Zähler in meiner Statistik-Ausgabe?** - - A: Informationen zu zwischengespeicherten Tokens werden nur angezeigt, wenn zwischengespeicherte Tokens verwendet werden. Diese Funktion ist für API-Key-Benutzer (Qwen API Key oder Google Cloud Vertex AI) verfügbar, aber nicht für OAuth-Benutzer (wie z. B. Google Personal/Enterprise-Konten wie Google Gmail oder Google Workspace). Der Grund dafür ist, dass die Qwen Code Assist API die Erstellung von zwischengespeicherten Inhalten nicht unterstützt. Du kannst deine gesamte Token-Nutzung weiterhin mit dem Befehl `/stats` anzeigen. + - A: Informationen zu zwischengespeicherten Tokens werden nur angezeigt, wenn solche Tokens tatsächlich verwendet werden. Dieses Feature steht Nutzern mit API-Schlüssel (Qwen API key oder Google Cloud Vertex AI) zur Verfügung, jedoch nicht für OAuth-Nutzer (wie z. B. persönliche oder Enterprise-Google-Konten wie Google Gmail oder Google Workspace). Grund dafür ist, dass die Qwen Code Assist API das Erstellen von zwischengespeicherten Inhalten nicht unterstützt. Du kannst deine gesamte Token-Nutzung weiterhin mit dem Befehl `/stats` einsehen. ## Häufige Fehlermeldungen und Lösungen @@ -40,8 +40,8 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da - **Ursache:** Die CLI ist nicht korrekt installiert oder befindet sich nicht im `PATH` deines Systems. - **Lösung:** Das Update hängt davon ab, wie du Qwen Code installiert hast: - - Wenn du `qwen` global installiert hast, stelle sicher, dass das globale `npm`-Binary-Verzeichnis in deinem `PATH` enthalten ist. Du kannst mit dem Befehl `npm install -g @qwen-code/qwen-code@latest` aktualisieren. - - Wenn du `qwen` aus dem Quellcode ausführst, stelle sicher, dass du den richtigen Befehl zum Aufruf verwendest (z. B. `node packages/cli/dist/index.js ...`). Zum Aktualisieren, lade die neuesten Änderungen aus dem Repository und führe anschließend den Befehl `npm run build` aus. + - Wenn du `qwen` global installiert hast, stelle sicher, dass dein globales `npm`-Binary-Verzeichnis im `PATH` enthalten ist. Du kannst mit dem Befehl `npm install -g @qwen-code/qwen-code@latest` aktualisieren. + - Wenn du `qwen` aus dem Quellcode ausführst, stelle sicher, dass du den richtigen Befehl zum Aufruf verwendest (z. B. `node packages/cli/dist/index.js ...`). Um zu aktualisieren, pull die neuesten Änderungen aus dem Repository und führe anschließend mit dem Befehl `npm run build` einen Neubuild durch. - **Fehler: `MODULE_NOT_FOUND` oder Import-Fehler.** - **Ursache:** Abhängigkeiten sind nicht korrekt installiert oder das Projekt wurde nicht gebaut. @@ -51,33 +51,45 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da 3. Überprüfe mit `npm run start`, ob der Build erfolgreich abgeschlossen wurde. - **Fehler: „Operation not permitted“, „Permission denied“ oder Ähnliches.** - - **Ursache:** Wenn Sandboxing aktiviert ist, kann Qwen Code versuchen, Operationen durchzuführen, die durch deine Sandbox-Konfiguration eingeschränkt sind, z. B. Schreibzugriffe außerhalb des Projektverzeichnisses oder des systemweiten Temp-Verzeichnisses. - - **Lösung:** Weitere Informationen findest du in der Dokumentation unter [Configuration: Sandboxing](./cli/configuration.md#sandboxing), einschließlich Anweisungen zur Anpassung deiner Sandbox-Konfiguration. + - **Ursache:** Wenn Sandboxing aktiviert ist, kann Qwen Code versuchen, Operationen durchzuführen, die durch deine Sandbox-Konfiguration eingeschränkt sind, z. B. Schreibzugriffe außerhalb des Projektverzeichnisses oder des temporären Systemverzeichnisses. + - **Lösung:** Weitere Informationen findest du in der Dokumentation unter [Konfiguration: Sandboxing](./cli/configuration.md#sandboxing), einschließlich Anweisungen zum Anpassen deiner Sandbox-Konfiguration. - **Qwen Code läuft in „CI“-Umgebungen nicht im interaktiven Modus** - **Problem:** Qwen Code wechselt nicht in den interaktiven Modus (es erscheint keine Eingabeaufforderung), wenn eine Umgebungsvariable mit dem Präfix `CI_` (z. B. `CI_TOKEN`) gesetzt ist. Das liegt daran, dass das `is-in-ci`-Paket, das vom zugrunde liegenden UI-Framework verwendet wird, diese Variablen erkennt und eine nicht-interaktive CI-Umgebung annimmt. - - **Ursache:** Das `is-in-ci`-Paket prüft auf das Vorhandensein von `CI`, `CONTINUOUS_INTEGRATION` oder beliebigen Umgebungsvariablen mit dem Präfix `CI_`. Wenn eine dieser Variablen gefunden wird, wird davon ausgegangen, dass es sich um eine nicht-interaktive Umgebung handelt, wodurch der Start im interaktiven Modus verhindert wird. + - **Ursache:** Das `is-in-ci`-Paket prüft auf das Vorhandensein von `CI`, `CONTINUOUS_INTEGRATION` oder beliebigen Umgebungsvariablen mit dem Präfix `CI_`. Wenn eine dieser Variablen gefunden wird, wird signalisiert, dass die Umgebung nicht interaktiv ist, wodurch die CLI daran gehindert wird, im interaktiven Modus zu starten. - **Lösung:** Falls die Variable mit dem Präfix `CI_` für die CLI nicht benötigt wird, kannst du sie vorübergehend für den Befehl deaktivieren, z. B. mit `env -u CI_TOKEN qwen`. - **DEBUG-Modus funktioniert nicht über die .env-Datei des Projekts** - **Problem:** Das Setzen von `DEBUG=true` in der `.env`-Datei eines Projekts aktiviert den Debug-Modus für die CLI nicht. - - **Ursache:** Die Variablen `DEBUG` und `DEBUG_MODE` werden automatisch aus Projekt-`.env`-Dateien ausgeschlossen, um Störungen im CLI-Verhalten zu vermeiden. + - **Ursache:** Die Variablen `DEBUG` und `DEBUG_MODE` werden automatisch aus Projekt-`.env`-Dateien ausgeschlossen, um Interferenzen mit dem CLI-Verhalten zu vermeiden. - **Lösung:** Verwende stattdessen eine `.qwen/.env`-Datei oder passe die Einstellung `excludedProjectEnvVars` in deiner `settings.json` an, um weniger Variablen auszuschließen. ## IDE Companion verbindet nicht - Stelle sicher, dass VS Code einen einzelnen Workspace-Ordner geöffnet hat. -- Starte das integrierte Terminal neu, nachdem die Extension installiert wurde, damit es folgende Umgebungsvariablen übernimmt: +- Starte das integrierte Terminal neu, nachdem du die Extension installiert hast, damit es folgende Umgebungsvariablen übernimmt: - `QWEN_CODE_IDE_WORKSPACE_PATH` - `QWEN_CODE_IDE_SERVER_PORT` -- Wenn du in einem Container arbeitest, prüfe, ob `host.docker.internal` aufgelöst werden kann. Andernfalls muss der Host entsprechend gemappt werden. +- Wenn du in einem Container arbeitest, überprüfe, ob `host.docker.internal` aufgelöst werden kann. Andernfalls musst du den Host entsprechend mappen. - Installiere den Companion neu mit `/ide install` und verwende „Qwen Code: Run“ in der Command Palette, um zu überprüfen, ob er startet. +## Exit Codes + +Qwen Code verwendet spezifische Exit Codes, um den Grund für die Beendigung anzugeben. Dies ist besonders nützlich für Scripting und Automatisierung. + +| Exit Code | Fehlerart | Beschreibung | +| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- | +| 41 | `FatalAuthenticationError` | Ein Fehler ist während des Authentifizierungsprozesses aufgetreten. | +| 42 | `FatalInputError` | Ungültige oder fehlende Eingabe wurde an die CLI übergeben. (nur im nicht-interaktiven Modus) | +| 44 | `FatalSandboxError` | Ein Fehler ist mit der Sandbox-Umgebung aufgetreten (z. B. Docker, Podman oder Seatbelt). | +| 52 | `FatalConfigError` | Eine Konfigurationsdatei (`settings.json`) ist ungültig oder enthält Fehler. | +| 53 | `FatalTurnLimitedError` | Die maximale Anzahl an Konversationsschritten für die Sitzung wurde erreicht. (nur im nicht-interaktiven Modus) | + ## Debugging-Tipps - **CLI-Debugging:** - Verwende das `--verbose`-Flag (falls verfügbar) mit CLI-Befehlen, um detailliertere Ausgaben zu erhalten. - - Prüfe die CLI-Logs, diese befinden sich oft in einem benutzerspezifischen Konfigurations- oder Cache-Verzeichnis. + - Prüfe die CLI-Logs, die sich oft in einem benutzerspezifischen Konfigurations- oder Cache-Verzeichnis befinden. - **Core-Debugging:** - Prüfe die Server-Konsolenausgabe auf Fehlermeldungen oder Stack-Traces. @@ -89,7 +101,7 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da - Für `run_shell_command` prüfe zuerst, ob der Befehl direkt in deiner Shell funktioniert. - Für _Filesystem-Tools_ stelle sicher, dass die Pfade korrekt sind und überprüfe die Berechtigungen. -- **Preflight-Checks:** +- **Pre-flight-Checks:** - Führe immer `npm run preflight` vor dem Committen von Code aus. Dies kann viele häufige Probleme im Zusammenhang mit Formatierung, Linting und Typfehlern abfangen. ## Vorhandene GitHub Issues, die deinem Problem ähneln, oder neue Issues erstellen diff --git a/website/content/en/assets/release_patch.png b/website/content/en/assets/release_patch.png new file mode 100644 index 00000000..952dc6ab Binary files /dev/null and b/website/content/en/assets/release_patch.png differ diff --git a/website/content/en/cli/commands.md b/website/content/en/cli/commands.md index 40ca2278..4c66d6d2 100644 --- a/website/content/en/cli/commands.md +++ b/website/content/en/cli/commands.md @@ -18,8 +18,8 @@ Slash commands provide meta-level control over the CLI itself. - **Description:** Saves the current conversation history. You must add a `` for identifying the conversation state. - **Usage:** `/chat save ` - **Details on Checkpoint Location:** The default locations for saved chat checkpoints are: - - Linux/macOS: `~/.config/qwen-code/checkpoints/` - - Windows: `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` + - Linux/macOS: `~/.qwen/tmp//` + - Windows: `C:\Users\\.qwen\tmp\\` - When you run `/chat list`, the CLI only scans these specific directories to find available checkpoints. - **Note:** These checkpoints are for manually saving and resuming conversation states. For automatic checkpoints created before file modifications, see the [Checkpointing documentation](../checkpointing.md). - **`resume`** @@ -124,6 +124,18 @@ Slash commands provide meta-level control over the CLI itself. - **`/auth`** - **Description:** Open a dialog that lets you change the authentication method. +- **`/approval-mode`** + - **Description:** Change the approval mode for tool usage. + - **Usage:** `/approval-mode [mode] [--session|--project|--user]` + - **Available Modes:** + - **`plan`**: Analyze only; do not modify files or execute commands + - **`default`**: Require approval for file edits or shell commands + - **`auto-edit`**: Automatically approve file edits + - **`yolo`**: Automatically approve all tools + - **Examples:** + - `/approval-mode plan --project` (persist plan mode for this project) + - `/approval-mode yolo --user` (persist YOLO mode for this user across projects) + - **`/about`** - **Description:** Show version info. Please share this information when filing issues. @@ -143,6 +155,7 @@ Slash commands provide meta-level control over the CLI itself. - [**`/tools`**](../tools/index.md) - **Description:** Display a list of tools that are currently available within Qwen Code. + - **Usage:** `/tools [desc]` - **Sub-commands:** - **`desc`** or **`descriptions`**: - **Description:** Show detailed descriptions of each tool, including each tool's name with its full description as provided to the model. @@ -313,7 +326,7 @@ When a custom command attempts to execute a shell command, Qwen Code will now pr 1. **Inject Commands:** Use the `!{...}` syntax. 2. **Argument Substitution:** If `{{args}}` is present inside the block, it is automatically shell-escaped (see [Context-Aware Injection](#1-context-aware-injection-with-args) above). -3. **Robust Parsing:** The parser correctly handles complex shell commands that include nested braces, such as JSON payloads. +3. **Robust Parsing:** The parser correctly handles complex shell commands that include nested braces, such as JSON payloads. **Note:** The content inside `!{...}` must have balanced braces (`{` and `}`). If you need to execute a command containing unbalanced braces, consider wrapping it in an external script file and calling the script within the `!{...}` block. 4. **Security Check and Confirmation:** The CLI performs a security check on the final, resolved command (after arguments are escaped and substituted). A dialog will appear showing the exact command(s) to be executed. 5. **Execution and Error Reporting:** The command is executed. If the command fails, the output injected into the prompt will include the error messages (stderr) followed by a status line, e.g., `[Shell command exited with code 1]`. This helps the model understand the context of the failure. @@ -341,6 +354,41 @@ Please generate a Conventional Commit message based on the following git diff: When you run `/git:commit`, the CLI first executes `git diff --staged`, then replaces `!{git diff --staged}` with the output of that command before sending the final, complete prompt to the model. +##### 4. Injecting File Content with `@{...}` + +You can directly embed the content of a file or a directory listing into your prompt using the `@{...}` syntax. This is useful for creating commands that operate on specific files. + +**How It Works:** + +- **File Injection**: `@{path/to/file.txt}` is replaced by the content of `file.txt`. +- **Multimodal Support**: If the path points to a supported image (e.g., PNG, JPEG), PDF, audio, or video file, it will be correctly encoded and injected as multimodal input. Other binary files are handled gracefully and skipped. +- **Directory Listing**: `@{path/to/dir}` is traversed and each file present within the directory and all subdirectories are inserted into the prompt. This respects `.gitignore` and `.qwenignore` if enabled. +- **Workspace-Aware**: The command searches for the path in the current directory and any other workspace directories. Absolute paths are allowed if they are within the workspace. +- **Processing Order**: File content injection with `@{...}` is processed _before_ shell commands (`!{...}`) and argument substitution (`{{args}}`). +- **Parsing**: The parser requires the content inside `@{...}` (the path) to have balanced braces (`{` and `}`). + +**Example (`review.toml`):** + +This command injects the content of a _fixed_ best practices file (`docs/best-practices.md`) and uses the user's arguments to provide context for the review. + +```toml +# In: /.qwen/commands/review.toml +# Invoked via: /review FileCommandLoader.ts + +description = "Reviews the provided context using a best practice guide." +prompt = """ +You are an expert code reviewer. + +Your task is to review {{args}}. + +Use the following best practices when providing your review: + +@{docs/best-practices.md} +""" +``` + +When you run `/review FileCommandLoader.ts`, the `@{docs/best-practices.md}` placeholder is replaced by the content of that file, and `{{args}}` is replaced by the text you provided, before the final prompt is sent to the model. + --- #### Example: A "Pure Function" Refactoring Command diff --git a/website/content/en/cli/configuration.md b/website/content/en/cli/configuration.md index 6bf1642c..0a16eb2e 100644 --- a/website/content/en/cli/configuration.md +++ b/website/content/en/cli/configuration.md @@ -7,16 +7,20 @@ Qwen Code offers several ways to configure its behavior, including environment v Configuration is applied in the following order of precedence (lower numbers are overridden by higher numbers): 1. **Default values:** Hardcoded defaults within the application. -2. **User settings file:** Global settings for the current user. -3. **Project settings file:** Project-specific settings. -4. **System settings file:** System-wide settings. -5. **Environment variables:** System-wide or session-specific variables, potentially loaded from `.env` files. -6. **Command-line arguments:** Values passed when launching the CLI. +2. **System defaults file:** System-wide default settings that can be overridden by other settings files. +3. **User settings file:** Global settings for the current user. +4. **Project settings file:** Project-specific settings. +5. **System settings file:** System-wide settings that override all other settings files. +6. **Environment variables:** System-wide or session-specific variables, potentially loaded from `.env` files. +7. **Command-line arguments:** Values passed when launching the CLI. ## Settings files -Qwen Code uses `settings.json` files for persistent configuration. There are three locations for these files: +Qwen Code uses JSON settings files for persistent configuration. There are four locations for these files: +- **System defaults file:** + - **Location:** `/etc/qwen-code/system-defaults.json` (Linux), `C:\ProgramData\qwen-code\system-defaults.json` (Windows) or `/Library/Application Support/QwenCode/system-defaults.json` (macOS). The path can be overridden using the `QWEN_CODE_SYSTEM_DEFAULTS_PATH` environment variable. + - **Scope:** Provides a base layer of system-wide default settings. These settings have the lowest precedence and are intended to be overridden by user, project, or system override settings. - **User settings file:** - **Location:** `~/.qwen/settings.json` (where `~` is your home directory). - **Scope:** Applies to all Qwen Code sessions for the current user. @@ -61,19 +65,36 @@ In addition to a project settings file, a project's `.qwen` directory can contai - **Properties:** - **`respectGitIgnore`** (boolean): Whether to respect .gitignore patterns when discovering files. When set to `true`, git-ignored files (like `node_modules/`, `dist/`, `.env`) are automatically excluded from @ commands and file listing operations. - **`enableRecursiveFileSearch`** (boolean): Whether to enable searching recursively for filenames under the current tree when completing @ prefixes in the prompt. + - **`disableFuzzySearch`** (boolean): When `true`, disables the fuzzy search capabilities when searching for files, which can improve performance on projects with a large number of files. - **Example:** ```json "fileFiltering": { "respectGitIgnore": true, - "enableRecursiveFileSearch": false + "enableRecursiveFileSearch": false, + "disableFuzzySearch": true } ``` +### Troubleshooting File Search Performance + +If you are experiencing performance issues with file searching (e.g., with `@` completions), especially in projects with a very large number of files, here are a few things you can try in order of recommendation: + +1. **Use `.qwenignore`:** Create a `.qwenignore` file in your project root to exclude directories that contain a large number of files that you don't need to reference (e.g., build artifacts, logs, `node_modules`). Reducing the total number of files crawled is the most effective way to improve performance. + +2. **Disable Fuzzy Search:** If ignoring files is not enough, you can disable fuzzy search by setting `disableFuzzySearch` to `true` in your `settings.json` file. This will use a simpler, non-fuzzy matching algorithm, which can be faster. + +3. **Disable Recursive File Search:** As a last resort, you can disable recursive file search entirely by setting `enableRecursiveFileSearch` to `false`. This will be the fastest option as it avoids a recursive crawl of your project. However, it means you will need to type the full path to files when using `@` completions. + - **`coreTools`** (array of strings): - **Description:** Allows you to specify a list of core tool names that should be made available to the model. This can be used to restrict the set of built-in tools. See [Built-in Tools](../core/tools-api.md#built-in-tools) for a list of core tools. You can also specify command-specific restrictions for tools that support it, like the `ShellTool`. For example, `"coreTools": ["ShellTool(ls -l)"]` will only allow the `ls -l` command to be executed. - **Default:** All tools available for use by the model. - **Example:** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`. +- **`allowedTools`** (array of strings): + - **Default:** `undefined` + - **Description:** A list of tool names that will bypass the confirmation dialog. This is useful for tools that you trust and use frequently. The match semantics are the same as `coreTools`. + - **Example:** `"allowedTools": ["ShellTool(git status)"]`. + - **`excludeTools`** (array of strings): - **Description:** Allows you to specify a list of core tool names that should be excluded from the model. A tool listed in both `excludeTools` and `coreTools` is excluded. You can also specify command-specific restrictions for tools that support it, like the `ShellTool`. For example, `"excludeTools": ["ShellTool(rm -rf)"]` will block the `rm -rf` command. - **Default**: No tools excluded. @@ -115,12 +136,12 @@ In addition to a project settings file, a project's `.qwen` directory can contai - **Example:** `"sandbox": "docker"` - **`toolDiscoveryCommand`** (string): - - **Description:** Defines a custom shell command for discovering tools from your project. The shell command must return on `stdout` a JSON array of [function declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). Tool wrappers are optional. + - **Description:** **Align with Gemini CLI.** Defines a custom shell command for discovering tools from your project. The shell command must return on `stdout` a JSON array of [function declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). Tool wrappers are optional. - **Default:** Empty - **Example:** `"toolDiscoveryCommand": "bin/get_tools"` - **`toolCallCommand`** (string): - - **Description:** Defines a custom shell command for calling a specific tool that was discovered using `toolDiscoveryCommand`. The shell command must meet the following criteria: + - **Description:** **Align with Gemini CLI.** Defines a custom shell command for calling a specific tool that was discovered using `toolDiscoveryCommand`. The shell command must meet the following criteria: - It must take function `name` (exactly as in [function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) as first command line argument. - It must read function arguments as JSON on `stdin`, analogous to [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). - It must return function output as JSON on `stdout`, analogous to [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). @@ -268,7 +289,7 @@ In addition to a project settings file, a project's `.qwen` directory can contai ``` - **`includeDirectories`** (array of strings): - - **Description:** Specifies an array of additional absolute or relative paths to include in the workspace context. This allows you to work with files across multiple directories as if they were one. Paths can use `~` to refer to the user's home directory. This setting can be combined with the `--include-directories` command-line flag. + - **Description:** Specifies an array of additional absolute or relative paths to include in the workspace context. Missing directories will be skipped with a warning by default. Paths can use `~` to refer to the user's home directory. This setting can be combined with the `--include-directories` command-line flag. - **Default:** `[]` - **Example:** ```json @@ -311,6 +332,48 @@ In addition to a project settings file, a project's `.qwen` directory can contai "showLineNumbers": false ``` +- **`accessibility`** (object): + - **Description:** Configures accessibility features for the CLI. + - **Properties:** + - **`screenReader`** (boolean): Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers. This can also be enabled with the `--screen-reader` command-line flag, which will take precedence over the setting. + - **`disableLoadingPhrases`** (boolean): Disables the display of loading phrases during operations. + - **Default:** `{"screenReader": false, "disableLoadingPhrases": false}` + - **Example:** + ```json + "accessibility": { + "screenReader": true, + "disableLoadingPhrases": true + } + ``` + +- **`skipNextSpeakerCheck`** (boolean): + - **Description:** Skips the next speaker check after text responses. When enabled, the system bypasses analyzing whether the AI should continue speaking. + - **Default:** `false` + - **Example:** + ```json + "skipNextSpeakerCheck": true + ``` + +- **`skipLoopDetection`** (boolean): + - **Description:** Disables all loop detection checks (streaming and LLM-based). Loop detection prevents infinite loops in AI responses but can generate false positives that interrupt legitimate workflows. Enable this option if you experience frequent false positive loop detection interruptions. + - **Default:** `false` + - **Example:** + ```json + "skipLoopDetection": true + ``` + +- **`approvalMode`** (string): + - **Description:** Sets the default approval mode for tool usage. Accepted values are: + - `plan`: Analyze only, do not modify files or execute commands. + - `default`: Require approval before file edits or shell commands run. + - `auto-edit`: Automatically approve file edits. + - `yolo`: Automatically approve all tool calls. + - **Default:** `"default"` + - **Example:** + ```json + "approvalMode": "plan" + ``` + ### Example `settings.json`: ```json @@ -338,6 +401,8 @@ In addition to a project settings file, a project's `.qwen` directory can contai "usageStatisticsEnabled": true, "hideTips": false, "hideBanner": false, + "skipNextSpeakerCheck": false, + "skipLoopDetection": false, "maxSessionTurns": 10, "summarizeToolOutput": { "run_shell_command": { @@ -433,12 +498,16 @@ Arguments passed directly when running the CLI can override other configurations - **`--yolo`**: - Enables YOLO mode, which automatically approves all tool calls. - **`--approval-mode `**: - - Sets the approval mode for tool calls. Available modes: - - `default`: Prompt for approval on each tool call (default behavior) - - `auto_edit`: Automatically approve edit tools (edit, write_file) while prompting for others - - `yolo`: Automatically approve all tool calls (equivalent to `--yolo`) + - Sets the approval mode for tool calls. Supported modes: + - `plan`: Analyze only—do not modify files or execute commands. + - `default`: Require approval for file edits or shell commands (default behavior). + - `auto-edit`: Automatically approve edit tools (edit, write_file) while prompting for others. + - `yolo`: Automatically approve all tool calls (equivalent to `--yolo`). - Cannot be used together with `--yolo`. Use `--approval-mode=yolo` instead of `--yolo` for the new unified approach. - - Example: `qwen --approval-mode auto_edit` + - Example: `qwen --approval-mode auto-edit` +- **`--allowed-tools `**: + - A comma-separated list of tool names that will bypass the confirmation dialog. + - Example: `qwen --allowed-tools "ShellTool(git status)"` - **`--telemetry`**: - Enables [telemetry](../telemetry.md). - **`--telemetry-target`**: @@ -465,6 +534,8 @@ Arguments passed directly when running the CLI can override other configurations - Can be specified multiple times or as comma-separated values. - 5 directories can be added at maximum. - Example: `--include-directories /path/to/project1,/path/to/project2` or `--include-directories /path/to/project1 --include-directories /path/to/project2` +- **`--screen-reader`**: + - Enables screen reader mode for accessibility. - **`--version`**: - Displays the version of the CLI. - **`--openai-logging`**: diff --git a/website/content/en/cli/themes.md b/website/content/en/cli/themes.md index c28e1ec8..ad8a046a 100644 --- a/website/content/en/cli/themes.md +++ b/website/content/en/cli/themes.md @@ -28,6 +28,8 @@ Qwen Code comes with a selection of pre-defined themes, which you can list using 3. Using the arrow keys, select a theme. Some interfaces might offer a live preview or highlight as you select. 4. Confirm your selection to apply the theme. +**Note:** If a theme is defined in your `settings.json` file (either by name or by a file path), you must remove the `"theme"` setting from the file before you can change the theme using the `/theme` command. + ### Theme Persistence Selected themes are saved in Qwen Code's [configuration](./configuration.md) so your preference is remembered across sessions. @@ -105,6 +107,46 @@ You can use either hex codes (e.g., `#FF0000`) **or** standard CSS color names ( You can define multiple custom themes by adding more entries to the `customThemes` object. +### Loading Themes from a File + +In addition to defining custom themes in `settings.json`, you can also load a theme directly from a JSON file by specifying the file path in your `settings.json`. This is useful for sharing themes or keeping them separate from your main configuration. + +To load a theme from a file, set the `theme` property in your `settings.json` to the path of your theme file: + +```json +{ + "theme": "/path/to/your/theme.json" +} +``` + +The theme file must be a valid JSON file that follows the same structure as a custom theme defined in `settings.json`. + +**Example `my-theme.json`:** + +```json +{ + "name": "My File Theme", + "type": "custom", + "Background": "#282A36", + "Foreground": "#F8F8F2", + "LightBlue": "#82AAFF", + "AccentBlue": "#61AFEF", + "AccentPurple": "#BD93F9", + "AccentCyan": "#8BE9FD", + "AccentGreen": "#50FA7B", + "AccentYellow": "#F1FA8C", + "AccentRed": "#FF5555", + "Comment": "#6272A4", + "Gray": "#ABB2BF", + "DiffAdded": "#A6E3A1", + "DiffRemoved": "#F38BA8", + "DiffModified": "#89B4FA", + "GradientColors": ["#4796E4", "#847ACE", "#C3677F"] +} +``` + +**Security Note:** For your safety, Gemini CLI will only load theme files that are located within your home directory. If you attempt to load a theme from outside your home directory, a warning will be displayed and the theme will not be loaded. This is to prevent loading potentially malicious theme files from untrusted sources. + ### Example Custom Theme Custom theme example diff --git a/website/content/en/deployment.md b/website/content/en/deployment.md index fc9f3c6a..ca2b3ec5 100644 --- a/website/content/en/deployment.md +++ b/website/content/en/deployment.md @@ -41,7 +41,7 @@ For security and isolation, Qwen Code can be run inside a container. This is the You can run the published sandbox image directly. This is useful for environments where you only have Docker and want to run the CLI. ```bash # Run the published sandbox image - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.11 ``` - **Using the `--sandbox` flag:** If you have Qwen Code installed locally (using the standard installation described above), you can instruct it to run inside the sandbox container. diff --git a/website/content/en/examples/proxy-script.md b/website/content/en/examples/proxy-script.md index 15afc355..78299001 100644 --- a/website/content/en/examples/proxy-script.md +++ b/website/content/en/examples/proxy-script.md @@ -15,10 +15,10 @@ The following is an example of a proxy script that can be used with the `GEMINI_ // Set `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js` to run proxy alongside sandbox // Test via `curl https://example.com` inside sandbox (in shell mode or via shell tool) -import http from 'http'; -import net from 'net'; -import { URL } from 'url'; -import console from 'console'; +import http from 'node:http'; +import net from 'node:net'; +import { URL } from 'node:url'; +import console from 'node:console'; const PROXY_PORT = 8877; const ALLOWED_DOMAINS = ['example.com', 'googleapis.com']; diff --git a/website/content/en/extension.md b/website/content/en/extension.md index 37336b15..358b666f 100644 --- a/website/content/en/extension.md +++ b/website/content/en/extension.md @@ -74,3 +74,27 @@ For example, if both a user and the `gcp` extension define a `deploy` command: - `/deploy` - Executes the user's deploy command - `/gcp.deploy` - Executes the extension's deploy command (marked with `[gcp]` tag) + +## Installing Extensions + +You can install extensions using the `install` command. This command allows you to install extensions from a Git repository or a local path. + +### Usage + +`qwen extensions install | [options]` + +### Options + +- `source positional argument`: The URL of a Git repository to install the extension from. The repository must contain a `qwen-extension.json` file in its root. +- `--path `: The path to a local directory to install as an extension. The directory must contain a `qwen-extension.json` file. + +# Variables + +Qwen Code extensions allow variable substitution in `qwen-extension.json`. This can be useful if e.g., you need the current directory to run an MCP server using `"cwd": "${extensionPath}${/}run.ts"`. + +**Supported variables:** + +| variable | description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `${extensionPath}` | The fully-qualified path of the extension in the user's filesystem e.g., '/Users/username/.qwen/extensions/example-extension'. This will not unwrap symlinks. | +| `${/} or ${pathSeparator}` | The path separator (differs per OS). | diff --git a/website/content/en/ide-integration.md b/website/content/en/ide-integration.md index e213d257..e2040f5d 100644 --- a/website/content/en/ide-integration.md +++ b/website/content/en/ide-integration.md @@ -44,7 +44,10 @@ You can also install the extension directly from a marketplace. - **For Visual Studio Code:** Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion). - **For VS Code Forks:** To support forks of VS Code, the extension is also published on the [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion). Follow your editor's instructions for installing extensions from this registry. -After any installation method, it's recommended to open a new terminal window to ensure the integration is activated correctly. Once installed, you can use `/ide enable` to connect. +> NOTE: +> The "Qwen Code Companion" extension may appear towards the bottom of search results. If you don't see it immediately, try scrolling down or sorting by "Newly Published". +> +> After manually installing the extension, you must run `/ide enable` in the CLI to activate the integration. ## Usage @@ -77,7 +80,7 @@ If connected, this command will show the IDE it's connected to and a list of rec ### Working with Diffs -When you ask Gemini to modify a file, it can open a diff view directly in your editor. +When you ask Qwen model to modify a file, it can open a diff view directly in your editor. **To accept a diff**, you can perform any of the following actions: @@ -126,9 +129,9 @@ If you encounter issues with IDE integration, here are some common error message - **Cause:** The CLI's current working directory is outside the folder or workspace you have open in your IDE. - **Solution:** `cd` into the same directory that is open in your IDE and restart the CLI. -- **Message:** `🔴 Disconnected: To use this feature, please open a single workspace folder in [IDE Name] and try again.` - - **Cause:** You have multiple workspace folders open in your IDE, or no folder is open at all. The IDE integration requires a single root workspace folder to operate correctly. - - **Solution:** Open a single project folder in your IDE and restart the CLI. +- **Message:** `🔴 Disconnected: To use this feature, please open a workspace folder in [IDE Name] and try again.` + - **Cause:** You have no workspace open in your IDE. + - **Solution:** Open a workspace in your IDE and restart the CLI. ### General Errors @@ -136,6 +139,6 @@ If you encounter issues with IDE integration, here are some common error message - **Cause:** You are running Qwen Code in a terminal or environment that is not a supported IDE. - **Solution:** Run Qwen Code from the integrated terminal of a supported IDE, like VS Code. -- **Message:** `No installer is available for [IDE Name]. Please install the IDE companion manually from its marketplace.` +- **Message:** `No installer is available for IDE. Please install the Qwen Code Companion extension manually from the marketplace.` - **Cause:** You ran `/ide install`, but the CLI does not have an automated installer for your specific IDE. - **Solution:** Open your IDE's extension marketplace, search for "Qwen Code Companion", and install it manually. diff --git a/website/content/en/index.md b/website/content/en/index.md index cf61778d..37100f92 100644 --- a/website/content/en/index.md +++ b/website/content/en/index.md @@ -33,7 +33,7 @@ This documentation is organized into the following sections: - **[Memory Tool](./tools/memory.md):** Documentation for the `save_memory` tool. - **[Subagents](./subagents.md):** Specialized AI assistants for focused tasks with comprehensive management, configuration, and usage guidance. - **[Contributing & Development Guide](../CONTRIBUTING.md):** Information for contributors and developers, including setup, building, testing, and coding conventions. -- **[NPM Workspaces and Publishing](./npm.md):** Details on how the project's packages are managed and published. +- **[NPM](./npm.md):** Details on how the project's packages are structured - **[Troubleshooting Guide](./troubleshooting.md):** Find solutions to common problems and FAQs. - **[Terms of Service and Privacy Notice](./tos-privacy.md):** Information on the terms of service and privacy notices applicable to your use of Qwen Code. diff --git a/website/content/en/keyboard-shortcuts.md b/website/content/en/keyboard-shortcuts.md index 23c4d79f..b029c4a0 100644 --- a/website/content/en/keyboard-shortcuts.md +++ b/website/content/en/keyboard-shortcuts.md @@ -4,16 +4,16 @@ This document lists the available keyboard shortcuts in Qwen Code. ## General -| Shortcut | Description | -| -------- | --------------------------------------------------------------------------------------------------------------------- | -| `Esc` | Close dialogs and suggestions. | -| `Ctrl+C` | Cancel the ongoing request and clear the input. Press twice to exit the application. | -| `Ctrl+D` | Exit the application if the input is empty. Press twice to confirm. | -| `Ctrl+L` | Clear the screen. | -| `Ctrl+O` | Toggle the display of the debug console. | -| `Ctrl+S` | Allows long responses to print fully, disabling truncation. Use your terminal's scrollback to view the entire output. | -| `Ctrl+T` | Toggle the display of tool descriptions. | -| `Ctrl+Y` | Toggle auto-approval (YOLO mode) for all tool calls. | +| Shortcut | Description | +| ----------- | --------------------------------------------------------------------------------------------------------------------- | +| `Esc` | Close dialogs and suggestions. | +| `Ctrl+C` | Cancel the ongoing request and clear the input. Press twice to exit the application. | +| `Ctrl+D` | Exit the application if the input is empty. Press twice to confirm. | +| `Ctrl+L` | Clear the screen. | +| `Ctrl+O` | Toggle the display of the debug console. | +| `Ctrl+S` | Allows long responses to print fully, disabling truncation. Use your terminal's scrollback to view the entire output. | +| `Ctrl+T` | Toggle the display of tool descriptions. | +| `Shift+Tab` | Cycle approval modes (`plan` → `default` → `auto-edit` → `yolo`). | ## Input Prompt @@ -29,6 +29,7 @@ This document lists the available keyboard shortcuts in Qwen Code. | `Ctrl+A` / `Home` | Move the cursor to the beginning of the line. | | `Ctrl+B` / `Left Arrow` | Move the cursor one character to the left. | | `Ctrl+C` | Clear the input prompt | +| `Esc` (double press) | Clear the input prompt. | | `Ctrl+D` / `Delete` | Delete the character to the right of the cursor. | | `Ctrl+E` / `End` | Move the cursor to the end of the line. | | `Ctrl+F` / `Right Arrow` | Move the cursor one character to the right. | diff --git a/website/content/en/qwen-ignore.md b/website/content/en/qwen-ignore.md new file mode 100644 index 00000000..1b870910 --- /dev/null +++ b/website/content/en/qwen-ignore.md @@ -0,0 +1,59 @@ +# Ignoring Files + +This document provides an overview of the Qwen Ignore (`.qwenignore`) feature of Qwen Code. + +Qwen Code includes the ability to automatically ignore files, similar to `.gitignore` (used by Git). Adding paths to your `.qwenignore` file will exclude them from tools that support this feature, although they will still be visible to other services (such as Git). + +## How it works + +When you add a path to your `.qwenignore` file, tools that respect this file will exclude matching files and directories from their operations. For example, when you use the [`read_many_files`](./tools/multi-file.md) command, any paths in your `.qwenignore` file will be automatically excluded. + +For the most part, `.qwenignore` follows the conventions of `.gitignore` files: + +- Blank lines and lines starting with `#` are ignored. +- Standard glob patterns are supported (such as `*`, `?`, and `[]`). +- Putting a `/` at the end will only match directories. +- Putting a `/` at the beginning anchors the path relative to the `.qwenignore` file. +- `!` negates a pattern. + +You can update your `.qwenignore` file at any time. To apply the changes, you must restart your Qwen Code session. + +## How to use `.qwenignore` + +To enable `.qwenignore`: + +1. Create a file named `.qwenignore` in the root of your project directory. + +To add a file or directory to `.qwenignore`: + +1. Open your `.qwenignore` file. +2. Add the path or file you want to ignore, for example: `/archive/` or `apikeys.txt`. + +### `.qwenignore` examples + +You can use `.qwenignore` to ignore directories and files: + +``` +# Exclude your /packages/ directory and all subdirectories +/packages/ + +# Exclude your apikeys.txt file +apikeys.txt +``` + +You can use wildcards in your `.qwenignore` file with `*`: + +``` +# Exclude all .md files +*.md +``` + +Finally, you can exclude files and directories from exclusion with `!`: + +``` +# Exclude all .md files except README.md +*.md +!README.md +``` + +To remove paths from your `.qwenignore` file, delete the relevant lines. diff --git a/website/content/en/subagents.md b/website/content/en/subagents.md index 415df7ce..15b5e273 100644 --- a/website/content/en/subagents.md +++ b/website/content/en/subagents.md @@ -133,6 +133,28 @@ Focus on creating clear, comprehensive documentation that helps both new contributors and end users understand the project. ``` +## Using Subagents Effectively + +### Automatic Delegation + +Qwen Code proactively delegates tasks based on: + +- The task description in your request +- The description field in subagent configurations +- Current context and available tools + +To encourage more proactive subagent use, include phrases like "use PROACTIVELY" or "MUST BE USED" in your description field. + +### Explicit Invocation + +Request a specific subagent by mentioning it in your command: + +``` +> Let the testing-expert subagent create unit tests for the payment module +> Have the documentation-writer subagent update the API reference +> Get the react-specialist subagent to optimize this component's performance +``` + ## Examples ### Development Workflow Agents diff --git a/website/content/en/telemetry.md b/website/content/en/telemetry.md index e6f2309d..3d6df75e 100644 --- a/website/content/en/telemetry.md +++ b/website/content/en/telemetry.md @@ -177,9 +177,10 @@ Logs are timestamped records of specific events. The following events are logged - `qwen-code.user_prompt`: This event occurs when a user submits a prompt. - **Attributes**: - - `prompt_length` - - `prompt` (this attribute is excluded if `log_prompts_enabled` is configured to be `false`) - - `auth_type` + - `prompt_length` (int) + - `prompt_id` (string) + - `prompt` (string, this attribute is excluded if `log_prompts_enabled` is configured to be `false`) + - `auth_type` (string) - `qwen-code.tool_call`: This event occurs for each function call. - **Attributes**: @@ -272,6 +273,7 @@ Metrics are numerical measurements of behavior over time. The following metrics - `ai_removed_lines` (Int, if applicable): Number of lines removed/changed by AI. - `user_added_lines` (Int, if applicable): Number of lines added/changed by user in AI proposed changes. - `user_removed_lines` (Int, if applicable): Number of lines removed/changed by user in AI proposed changes. + - `programming_language` (string, if applicable): The programming language of the file. - `qwen-code.chat_compression` (Counter, Int): Counts chat compression operations - **Attributes**: diff --git a/website/content/en/tools/multi-file.md b/website/content/en/tools/multi-file.md index 0ffc9136..cbf05dae 100644 --- a/website/content/en/tools/multi-file.md +++ b/website/content/en/tools/multi-file.md @@ -29,6 +29,7 @@ Use `read_many_files` to read content from multiple files specified by paths or `read_many_files` searches for files matching the provided `paths` and `include` patterns, while respecting `exclude` patterns and default excludes (if enabled). - For text files: it reads the content of each matched file (attempting to skip binary files not explicitly requested as image/PDF) and concatenates it into a single string, with a separator `--- {filePath} ---` between the content of each file. Uses UTF-8 encoding by default. +- The tool inserts a `--- End of content ---` after the last file. - For image and PDF files: if explicitly requested by name or extension (e.g., `paths: ["logo.png"]` or `include: ["*.pdf"]`), the tool reads the file and returns its content as a base64 encoded string. - The tool attempts to detect and skip other binary files (those not matching common image/PDF types or not explicitly requested) by checking for null bytes in their initial content. diff --git a/website/content/en/troubleshooting.md b/website/content/en/troubleshooting.md index ca7b5195..5950fc97 100644 --- a/website/content/en/troubleshooting.md +++ b/website/content/en/troubleshooting.md @@ -73,6 +73,18 @@ This guide provides solutions to common issues and debugging tips, including top - If running in a container, verify `host.docker.internal` resolves. Otherwise, map the host appropriately. - Reinstall the companion with `/ide install` and use “Qwen Code: Run” in the Command Palette to verify it launches. +## Exit Codes + +The Qwen Code uses specific exit codes to indicate the reason for termination. This is especially useful for scripting and automation. + +| Exit Code | Error Type | Description | +| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- | +| 41 | `FatalAuthenticationError` | An error occurred during the authentication process. | +| 42 | `FatalInputError` | Invalid or missing input was provided to the CLI. (non-interactive mode only) | +| 44 | `FatalSandboxError` | An error occurred with the sandboxing environment (e.g., Docker, Podman, or Seatbelt). | +| 52 | `FatalConfigError` | A configuration file (`settings.json`) is invalid or contains errors. | +| 53 | `FatalTurnLimitedError` | The maximum number of conversational turns for the session was reached. (non-interactive mode only) | + ## Debugging Tips - **CLI debugging:** diff --git a/website/content/fr/cli/commands.md b/website/content/fr/cli/commands.md index 3912118d..c6ca90c8 100644 --- a/website/content/fr/cli/commands.md +++ b/website/content/fr/cli/commands.md @@ -4,180 +4,193 @@ Qwen Code prend en charge plusieurs commandes intégrées pour vous aider à gé ## Commandes slash (`/`) -Les commandes slash fournissent un contrôle de niveau méta sur le CLI lui-même. +Les commandes slash fournissent un contrôle au niveau méta sur le CLI lui-même. -### Commandes intégrées +### Built-in Commands - **`/bug`** - - **Description :** Signaler un problème concernant Qwen Code. Par défaut, le problème est signalé dans le dépôt GitHub de Qwen Code. La chaîne de caractères saisie après `/bug` devient le titre du bug signalé. Le comportement par défaut de `/bug` peut être modifié en utilisant le paramètre `bugCommand` dans vos fichiers `.qwen/settings.json`. + - **Description:** File an issue about Qwen Code. By default, the issue is filed within the GitHub repository for Qwen Code. The string you enter after `/bug` will become the headline for the bug being filed. The default `/bug` behavior can be modified using the `bugCommand` setting in your `.qwen/settings.json` files. - **`/chat`** - - **Description :** Sauvegarder et reprendre l'historique des conversations pour gérer des états de conversation multiples de manière interactive, ou reprendre un état précédent lors d'une session ultérieure. - - **Sous-commandes :** + - **Description:** Save and resume conversation history for branching conversation state interactively, or resuming a previous state from a later session. + - **Sub-commands:** - **`save`** - - **Description :** Sauvegarde l'historique de la conversation en cours. Vous devez ajouter une `` pour identifier l'état de la conversation. - - **Usage :** `/chat save ` - - **Emplacement des checkpoints :** Les emplacements par défaut des checkpoints de chat sauvegardés sont : - - Linux/macOS : `~/.config/qwen-code/checkpoints/` - - Windows : `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` - - Lorsque vous exécutez `/chat list`, le CLI ne scanne que ces répertoires spécifiques pour trouver les checkpoints disponibles. - - **Note :** Ces checkpoints servent à sauvegarder et reprendre manuellement les états de conversation. Pour les checkpoints automatiques créés avant les modifications de fichiers, consultez la [documentation sur les checkpoints](../checkpointing.md). + - **Description:** Saves the current conversation history. You must add a `` for identifying the conversation state. + - **Usage:** `/chat save ` + - **Details on Checkpoint Location:** The default locations for saved chat checkpoints are: + - Linux/macOS: `~/.qwen/tmp//` + - Windows: `C:\Users\\.qwen\tmp\\` + - When you run `/chat list`, the CLI only scans these specific directories to find available checkpoints. + - **Note:** These checkpoints are for manually saving and resuming conversation states. For automatic checkpoints created before file modifications, see the [Checkpointing documentation](../checkpointing.md). - **`resume`** - - **Description :** Reprend une conversation à partir d'une sauvegarde précédente. - - **Usage :** `/chat resume ` + - **Description:** Resumes a conversation from a previous save. + - **Usage:** `/chat resume ` - **`list`** - - **Description :** Liste les tags disponibles pour reprendre un état de conversation. + - **Description:** Lists available tags for chat state resumption. - **`delete`** - - **Description :** Supprime un checkpoint de conversation sauvegardé. - - **Usage :** `/chat delete ` + - **Description:** Deletes a saved conversation checkpoint. + - **Usage:** `/chat delete ` - **`/clear`** - - **Description :** Efface l'écran du terminal, y compris l'historique de session visible et le défilement dans le CLI. Les données de session sous-jacentes (pour rappel de l'historique) peuvent être conservées selon l'implémentation exacte, mais l'affichage visuel est effacé. - - **Raccourci clavier :** Appuyez sur **Ctrl+L** à tout moment pour effectuer une action d'effacement. + - **Description:** Clear the terminal screen, including the visible session history and scrollback within the CLI. The underlying session data (for history recall) might be preserved depending on the exact implementation, but the visual display is cleared. + - **Keyboard shortcut:** Press **Ctrl+L** at any time to perform a clear action. - **`/summary`** - - **Description :** Génère un résumé complet du projet à partir de l'historique de conversation actuel et le sauvegarde dans `.qwen/PROJECT_SUMMARY.md`. Ce résumé inclut l'objectif global, les connaissances clés, les actions récentes et le plan actuel, ce qui est parfait pour reprendre le travail lors de sessions futures. - - **Usage :** `/summary` - - **Fonctionnalités :** - - Analyse l'historique complet de la conversation pour extraire le contexte important - - Crée un résumé structuré en markdown avec des sections pour les objectifs, les connaissances, les actions et les plans - - Sauvegarde automatiquement dans `.qwen/PROJECT_SUMMARY.md` à la racine de votre projet - - Affiche des indicateurs de progression pendant la génération et la sauvegarde - - S'intègre à la fonction Welcome Back pour une reprise de session fluide - - **Note :** Cette commande nécessite une conversation active avec au moins 2 messages pour générer un résumé pertinent. + - **Description:** Generate a comprehensive project summary from the current conversation history and save it to `.qwen/PROJECT_SUMMARY.md`. This summary includes the overall goal, key knowledge, recent actions, and current plan, making it perfect for resuming work in future sessions. + - **Usage:** `/summary` + - **Features:** + - Analyzes the entire conversation history to extract important context + - Creates a structured markdown summary with sections for goals, knowledge, actions, and plans + - Automatically saves to `.qwen/PROJECT_SUMMARY.md` in your project root + - Shows progress indicators during generation and saving + - Integrates with the Welcome Back feature for seamless session resumption + - **Note:** This command requires an active conversation with at least 2 messages to generate a meaningful summary. - **`/compress`** - - **Description :** Remplace tout le contexte de chat par un résumé. Cela permet d'économiser les tokens utilisés pour les tâches futures tout en conservant un résumé de haut niveau de ce qui s'est produit. + - **Description:** Replace the entire chat context with a summary. This saves on tokens used for future tasks while retaining a high level summary of what has happened. - **`/copy`** - - **Description :** Copie la dernière sortie produite par Qwen Code dans votre presse-papiers, pour un partage ou une réutilisation facile. - -- **`/directory`** (ou **`/dir`**) - - **Description :** Gérer les répertoires de l'espace de travail pour la prise en charge multi-répertoires. - - **Sous-commandes :** - - **`add`** : - - **Description :** Ajoute un répertoire à l'espace de travail. Le chemin peut être absolu ou relatif au répertoire de travail actuel. De plus, la référence depuis le répertoire personnel est également prise en charge. - - **Usage :** `/directory add ,` - - **Note :** Désactivé dans les profils sandbox restrictifs. Si vous l'utilisez, utilisez plutôt `--include-directories` lors du démarrage de la session. - - **`show`** : - - **Description :** Affiche tous les répertoires ajoutés par `/directory add` et `--include-directories`. - - **Usage :** `/directory show` - -- **`/directory`** (ou **`/dir`**) - - **Description :** Gérer les répertoires de l'espace de travail pour la prise en charge multi-répertoires. - - **Sous-commandes :** - - **`add`** : - - **Description :** Ajoute un répertoire à l'espace de travail. Le chemin peut être absolu ou relatif au répertoire de travail actuel. De plus, la référence depuis le répertoire personnel est également prise en charge. - - **Usage :** `/directory add ,` - - **Note :** Désactivé dans les profils sandbox restrictifs. Si vous l'utilisez, utilisez plutôt `--include-directories` lors du démarrage de la session. - - **`show`** : - - **Description :** Affiche tous les répertoires ajoutés par `/directory add` et `--include-directories`. - - **Usage :** `/directory show` + - **Description:** Copies the last output produced by Qwen Code to your clipboard, for easy sharing or reuse. + +- **`/directory`** (or **`/dir`**) + - **Description:** Manage workspace directories for multi-directory support. + - **Sub-commands:** + - **`add`**: + - **Description:** Add a directory to the workspace. The path can be absolute or relative to the current working directory. Moreover, the reference from home directory is supported as well. + - **Usage:** `/directory add ,` + - **Note:** Disabled in restrictive sandbox profiles. If you're using that, use `--include-directories` when starting the session instead. + - **`show`**: + - **Description:** Display all directories added by `/directory add` and `--include-directories`. + - **Usage:** `/directory show` + +- **`/directory`** (or **`/dir`**) + - **Description:** Manage workspace directories for multi-directory support. + - **Sub-commands:** + - **`add`**: + - **Description:** Add a directory to the workspace. The path can be absolute or relative to the current working directory. Moreover, the reference from home directory is supported as well. + - **Usage:** `/directory add ,` + - **Note:** Disabled in restrictive sandbox profiles. If you're using that, use `--include-directories` when starting the session instead. + - **`show`**: + - **Description:** Display all directories added by `/directory add` and `--include-directories`. + - **Usage:** `/directory show` - **`/editor`** - - **Description :** Ouvre une boîte de dialogue pour sélectionner les éditeurs pris en charge. + - **Description:** Open a dialog for selecting supported editors. - **`/extensions`** - - **Description :** Liste toutes les extensions actives dans la session Qwen Code actuelle. Voir [Extensions Qwen Code](../extension.md). + - **Description:** Lists all active extensions in the current Qwen Code session. See [Qwen Code Extensions](../extension.md). -- **`/help`** (ou **`/?`**) - - **Description :** Affiche les informations d'aide concernant Qwen Code, y compris les commandes disponibles et leur utilisation. +- **`/help`** (or **`/?`**) + - **Description:** Display help information about the Qwen Code, including available commands and their usage. - **`/mcp`** - - **Description :** Liste les serveurs Model Context Protocol (MCP) configurés, leur statut de connexion, les détails du serveur et les outils disponibles. - - **Sous-commandes :** - - **`desc`** ou **`descriptions`** : - - **Description :** Affiche des descriptions détaillées des serveurs et outils MCP. - - **`nodesc`** ou **`nodescriptions`** : - - **Description :** Masque les descriptions des outils, n'affichant que les noms des outils. - - **`schema`** : - - **Description :** Affiche le schéma JSON complet des paramètres configurés de l'outil. - - **Raccourci clavier :** Appuyez sur **Ctrl+T** à tout moment pour basculer entre l'affichage et le masquage des descriptions d'outils. + - **Description:** List configured Model Context Protocol (MCP) servers, their connection status, server details, and available tools. + - **Sub-commands:** + - **`desc`** or **`descriptions`**: + - **Description:** Show detailed descriptions for MCP servers and tools. + - **`nodesc`** or **`nodescriptions`**: + - **Description:** Hide tool descriptions, showing only the tool names. + - **`schema`**: + - **Description:** Show the full JSON schema for the tool's configured parameters. + - **Keyboard Shortcut:** Press **Ctrl+T** at any time to toggle between showing and hiding tool descriptions. - **`/memory`** - - **Description :** Gérer le contexte instructionnel de l'IA (mémoire hiérarchique chargée depuis les fichiers `QWEN.md` par défaut ; configurable via `contextFileName`). - - **Sous-commandes :** - - **`add`** : - - **Description :** Ajoute le texte suivant à la mémoire de l'IA. Usage : `/memory add ` - - **`show`** : - - **Description :** Affiche le contenu complet et concaténé de la mémoire hiérarchique actuelle chargée depuis tous les fichiers de contexte (ex : `QWEN.md`). Cela vous permet d'inspecter le contexte instructionnel fourni au modèle. - - **`refresh`** : - - **Description :** Recharge la mémoire instructionnelle hiérarchique depuis tous les fichiers de contexte (par défaut : `QWEN.md`) trouvés dans les emplacements configurés (global, projet/ancêtres et sous-répertoires). Cela met à jour le modèle avec le contenu de contexte le plus récent. - - **Note :** Pour plus de détails sur la contribution des fichiers de contexte à la mémoire hiérarchique, voir la [documentation de configuration du CLI](./configuration.md#context-files-hierarchical-instructional-context). + - **Description:** Manage the AI's instructional context (hierarchical memory loaded from `QWEN.md` files by default; configurable via `contextFileName`). + - **Sub-commands:** + - **`add`**: + - **Description:** Adds the following text to the AI's memory. Usage: `/memory add ` + - **`show`**: + - **Description:** Display the full, concatenated content of the current hierarchical memory that has been loaded from all context files (e.g., `QWEN.md`). This lets you inspect the instructional context being provided to the model. + - **`refresh`**: + - **Description:** Reload the hierarchical instructional memory from all context files (default: `QWEN.md`) found in the configured locations (global, project/ancestors, and sub-directories). This updates the model with the latest context content. + - **Note:** For more details on how context files contribute to hierarchical memory, see the [CLI Configuration documentation](./configuration.md#context-files-hierarchical-instructional-context). - **`/restore`** - - **Description :** Restaure les fichiers du projet à l'état dans lequel ils se trouvaient juste avant l'exécution d'un outil. C'est particulièrement utile pour annuler les modifications de fichiers effectuées par un outil. S'il est exécuté sans ID d'appel d'outil, il listera les checkpoints disponibles pour la restauration. - - **Usage :** `/restore [tool_call_id]` - - **Note :** Disponible uniquement si le CLI est invoqué avec l'option `--checkpointing` ou configuré via [les paramètres](./configuration.md). Voir la [documentation sur les checkpoints](../checkpointing.md) pour plus de détails. + - **Description:** Restores the project files to the state they were in just before a tool was executed. This is particularly useful for undoing file edits made by a tool. If run without a tool call ID, it will list available checkpoints to restore from. + - **Usage:** `/restore [tool_call_id]` + - **Note:** Only available if the CLI is invoked with the `--checkpointing` option or configured via [settings](./configuration.md). See [Checkpointing documentation](../checkpointing.md) for more details. - **`/settings`** - - **Description :** Ouvre l'éditeur de paramètres pour afficher et modifier les paramètres de Qwen Code. - - **Détails :** Cette commande fournit une interface conviviale pour modifier les paramètres qui contrôlent le comportement et l'apparence de Qwen Code. Elle équivaut à modifier manuellement le fichier `.qwen/settings.json`, mais avec validation et assistance pour éviter les erreurs. - - **Usage :** Exécutez simplement `/settings` et l'éditeur s'ouvrira. Vous pouvez alors parcourir ou rechercher des paramètres spécifiques, afficher leurs valeurs actuelles et les modifier selon vos besoins. Les modifications de certains paramètres sont appliquées immédiatement, tandis que d'autres nécessitent un redémarrage. + - **Description:** Open the settings editor to view and modify Qwen Code settings. + - **Details:** This command provides a user-friendly interface for changing settings that control the behavior and appearance of Qwen Code. It is equivalent to manually editing the `.qwen/settings.json` file, but with validation and guidance to prevent errors. + - **Usage:** Simply run `/settings` and the editor will open. You can then browse or search for specific settings, view their current values, and modify them as desired. Changes to some settings are applied immediately, while others require a restart. - **`/stats`** - - **Description :** Affiche des statistiques détaillées pour la session Qwen Code actuelle, y compris l'utilisation des tokens, les économies de tokens mis en cache (lorsque disponibles) et la durée de la session. Note : Les informations sur les tokens mis en cache ne sont affichées que lorsque des tokens mis en cache sont utilisés, ce qui se produit avec l'authentification par clé API mais pas avec l'authentification OAuth pour le moment. + - **Description:** Display detailed statistics for the current Qwen Code session, including token usage, cached token savings (when available), and session duration. Note: Cached token information is only displayed when cached tokens are being used, which occurs with API key authentication but not with OAuth authentication at this time. - [**`/theme`**](./themes.md) - - **Description :** Ouvre une boîte de dialogue qui vous permet de modifier le thème visuel de Qwen Code. + - **Description:** Open a dialog that lets you change the visual theme of Qwen Code. - **`/auth`** - - **Description :** Ouvre une boîte de dialogue qui vous permet de modifier la méthode d'authentification. + - **Description:** Open a dialog that lets you change the authentication method. + +- **`/approval-mode`** + - **Description:** Change the approval mode for tool usage. + - **Usage:** `/approval-mode [mode] [--session|--project|--user]` + - **Available Modes:** + - **`plan`**: Analyze only; do not modify files or execute commands + - **`default`**: Require approval for file edits or shell commands + - **`auto-edit`**: Automatically approve file edits + - **`yolo`**: Automatically approve all tools + - **Examples:** + - `/approval-mode plan --project` (persist plan mode for this project) + - `/approval-mode yolo --user` (persist YOLO mode for this user across projects) - **`/about`** - - **Description :** Affiche les informations de version. Veuillez partager ces informations lors du signalement de problèmes. + - **Description:** Show version info. Please share this information when filing issues. - **`/agents`** - - **Description :** Gérer les sous-agents IA spécialisés pour des tâches ciblées. Les sous-agents sont des assistants IA indépendants configurés avec une expertise spécifique et un accès à des outils. - - **Sous-commandes :** - - **`create`** : - - **Description :** Lance un assistant interactif pour créer un nouveau sous-agent. L'assistant vous guide à travers la sélection d'emplacement, la génération de prompts assistée par IA, la sélection d'outils et la personnalisation visuelle. - - **Usage :** `/agents create` - - **`manage`** : - - **Description :** Ouvre une boîte de dialogue de gestion interactive pour afficher, modifier et supprimer les sous-agents existants. Affiche les agents au niveau projet et au niveau utilisateur. - - **Usage :** `/agents manage` - - **Emplacements de stockage :** - - **Niveau projet :** `.qwen/agents/` (partagé avec l'équipe, prioritaire) - - **Niveau utilisateur :** `~/.qwen/agents/` (agents personnels, disponibles dans tous les projets) - - **Note :** Pour des informations détaillées sur la création et la gestion des sous-agents, voir la [documentation sur les sous-agents](../subagents.md). + - **Description:** Manage specialized AI subagents for focused tasks. Subagents are independent AI assistants configured with specific expertise and tool access. + - **Sub-commands:** + - **`create`**: + - **Description:** Launch an interactive wizard to create a new subagent. The wizard guides you through location selection, AI-powered prompt generation, tool selection, and visual customization. + - **Usage:** `/agents create` + - **`manage`**: + - **Description:** Open an interactive management dialog to view, edit, and delete existing subagents. Shows both project-level and user-level agents. + - **Usage:** `/agents manage` + - **Storage Locations:** + - **Project-level:** `.qwen/agents/` (shared with team, takes precedence) + - **User-level:** `~/.qwen/agents/` (personal agents, available across projects) + - **Note:** For detailed information on creating and managing subagents, see the [Subagents documentation](../subagents.md). - [**`/tools`**](../tools/index.md) - - **Description :** Affiche une liste des outils actuellement disponibles dans Qwen Code. - - **Sous-commandes :** - - **`desc`** ou **`descriptions`** : - - **Description :** Affiche des descriptions détaillées de chaque outil, y compris le nom de chaque outil avec sa description complète telle que fournie au modèle. - - **`nodesc`** ou **`nodescriptions`** : - - **Description :** Masque les descriptions des outils, n'affichant que les noms des outils. + - **Description:** Display a list of tools that are currently available within Qwen Code. + - **Usage:** `/tools [desc]` + - **Sub-commands:** + - **`desc`** or **`descriptions`**: + - **Description:** Show detailed descriptions of each tool, including each tool's name with its full description as provided to the model. + - **`nodesc`** or **`nodescriptions`**: + - **Description:** Hide tool descriptions, showing only the tool names. - **`/privacy`** - - **Description :** Affiche l'Avis de confidentialité et permet aux utilisateurs de choisir s'ils consentent à la collecte de leurs données à des fins d'amélioration du service. + - **Description:** Display the Privacy Notice and allow users to select whether they consent to the collection of their data for service improvement purposes. - **`/quit-confirm`** - - **Description :** Affiche une boîte de dialogue de confirmation avant de quitter Qwen Code, vous permettant de choisir comment gérer votre session actuelle. - - **Usage :** `/quit-confirm` - - **Fonctionnalités :** - - **Quitter immédiatement :** Quitter sans sauvegarder quoi que ce soit (équivalent à `/quit`) - - **Générer un résumé et quitter :** Créer un résumé du projet en utilisant `/summary` avant de quitter - - **Sauvegarder la conversation et quitter :** Sauvegarder la conversation actuelle avec un tag généré automatiquement avant de quitter - - **Raccourci clavier :** Appuyez deux fois sur **Ctrl+C** pour déclencher la boîte de dialogue de confirmation de sortie - - **Note :** Cette commande est automatiquement déclenchée lorsque vous appuyez une fois sur Ctrl+C, fournissant un mécanisme de sécurité pour prévenir les sorties accidentelles. - -- **`/quit`** (ou **`/exit`**) - - **Description :** Quitte Qwen Code immédiatement sans boîte de dialogue de confirmation. + - **Description:** Show a confirmation dialog before exiting Qwen Code, allowing you to choose how to handle your current session. + - **Usage:** `/quit-confirm` + - **Features:** + - **Quit immediately:** Exit without saving anything (equivalent to `/quit`) + - **Generate summary and quit:** Create a project summary using `/summary` before exiting + - **Save conversation and quit:** Save the current conversation with an auto-generated tag before exiting + - **Keyboard shortcut:** Press **Ctrl+C** twice to trigger the quit confirmation dialog + - **Note:** This command is automatically triggered when you press Ctrl+C once, providing a safety mechanism to prevent accidental exits. + +- **`/quit`** (or **`/exit`**) + - **Description:** Exit Qwen Code immediately without any confirmation dialog. - **`/vim`** - - **Description :** Active ou désactive le mode vim. Lorsque le mode vim est activé, la zone de saisie prend en charge les commandes de navigation et d'édition de style vim dans les modes NORMAL et INSERT. - - **Fonctionnalités :** - - **Mode NORMAL :** Naviguer avec `h`, `j`, `k`, `l` ; se déplacer par mots avec `w`, `b`, `e` ; aller au début/fin de ligne avec `0`, `$`, `^` ; aller à des lignes spécifiques avec `G` (ou `gg` pour la première ligne) - - **Mode INSERT :** Saisie de texte standard avec échappement pour retourner au mode NORMAL - - **Commandes d'édition :** Supprimer avec `x`, changer avec `c`, insérer avec `i`, `a`, `o`, `O` ; opérations complexes comme `dd`, `cc`, `dw`, `cw` - - **Support des compteurs :** Préfixer les commandes avec des nombres (ex : `3h`, `5w`, `10G`) - - **Répétition de la dernière commande :** Utiliser `.` pour répéter la dernière opération d'édition - - **Paramètre persistant :** La préférence du mode vim est sauvegardée dans `~/.qwen/settings.json` et restaurée entre les sessions - - **Indicateur de statut :** Lorsqu'activé, affiche `[NORMAL]` ou `[INSERT]` dans le pied de page + - **Description:** Toggle vim mode on or off. When vim mode is enabled, the input area supports vim-style navigation and editing commands in both NORMAL and INSERT modes. + - **Features:** + - **NORMAL mode:** Navigate with `h`, `j`, `k`, `l`; jump by words with `w`, `b`, `e`; go to line start/end with `0`, `$`, `^`; go to specific lines with `G` (or `gg` for first line) + - **INSERT mode:** Standard text input with escape to return to NORMAL mode + - **Editing commands:** Delete with `x`, change with `c`, insert with `i`, `a`, `o`, `O`; complex operations like `dd`, `cc`, `dw`, `cw` + - **Count support:** Prefix commands with numbers (e.g., `3h`, `5w`, `10G`) + - **Repeat last command:** Use `.` to repeat the last editing operation + - **Persistent setting:** Vim mode preference is saved to `~/.qwen/settings.json` and restored between sessions + - **Status indicator:** When enabled, shows `[NORMAL]` or `[INSERT]` in the footer - **`/init`** - - **Description :** Analyse le répertoire actuel et crée un fichier de contexte `QWEN.md` par défaut (ou le nom de fichier spécifié par `contextFileName`). Si un fichier non vide existe déjà, aucune modification n'est apportée. La commande initialise un fichier vide et invite le modèle à le remplir avec des instructions spécifiques au projet. + - **Description:** Analyzes the current directory and creates a `QWEN.md` context file by default (or the filename specified by `contextFileName`). If a non-empty file already exists, no changes are made. The command seeds an empty file and prompts the model to populate it with project-specific instructions. ### Commandes personnalisées @@ -185,12 +198,12 @@ Pour un démarrage rapide, consultez l'[exemple](#example-a-pure-function-refact Les commandes personnalisées vous permettent de sauvegarder et de réutiliser vos prompts favoris ou les plus fréquemment utilisés comme des raccourcis personnels au sein de Qwen Code. Vous pouvez créer des commandes spécifiques à un seul projet ou des commandes disponibles globalement sur tous vos projets, ce qui rationalise votre workflow et garantit la cohérence. -#### Emplacement des fichiers et priorité +#### Emplacement des fichiers & Priorité Qwen Code découvre les commandes à partir de deux emplacements, chargés dans un ordre spécifique : -1. **Commandes utilisateur (globales)** : situées dans `~/.qwen/commands/`. Ces commandes sont disponibles dans n'importe quel projet sur lequel vous travaillez. -2. **Commandes de projet (locales)** : situées dans `/.qwen/commands/`. Ces commandes sont spécifiques au projet en cours et peuvent être ajoutées au contrôle de version pour être partagées avec votre équipe. +1. **Commandes utilisateur (globales) :** Situées dans `~/.qwen/commands/`. Ces commandes sont disponibles dans n'importe quel projet sur lequel vous travaillez. +2. **Commandes de projet (locales) :** Situées dans `/.qwen/commands/`. Ces commandes sont spécifiques au projet en cours et peuvent être ajoutées au contrôle de version pour être partagées avec votre équipe. Si une commande dans le répertoire du projet porte le même nom qu'une commande dans le répertoire utilisateur, **la commande du projet sera toujours utilisée.** Cela permet aux projets de remplacer les commandes globales par des versions spécifiques au projet. @@ -207,7 +220,7 @@ Vos fichiers de définition de commande doivent être écrits au format TOML et ##### Champs obligatoires -- `prompt` (String) : Le prompt qui sera envoyé au modèle lorsque la commande est exécutée. Il peut s'agir d'une chaîne de caractères sur une ou plusieurs lignes. +- `prompt` (String) : Le prompt qui sera envoyé au modèle lorsque la commande est exécutée. Il peut s'agir d'une chaîne sur une seule ligne ou multi-lignes. ##### Champs optionnels @@ -215,7 +228,7 @@ Vos fichiers de définition de commande doivent être écrits au format TOML et #### Gestion des Arguments -Les commandes personnalisées prennent en charge deux méthodes puissantes pour gérer les arguments. Le CLI choisit automatiquement la bonne méthode en fonction du contenu du `prompt` de votre commande. +Les commandes personnalisées prennent en charge deux méthodes puissantes pour gérer les arguments. Le CLI choisit automatiquement la bonne méthode en fonction du contenu de votre `prompt`. ##### 1. Injection Contextuelle avec `{{args}}` @@ -231,7 +244,7 @@ Lorsqu'elle est utilisée dans le corps principal du prompt, les arguments sont ```toml -# Invoqué via : /git:fix "Button is misaligned" +# Appelé via : /git:fix "Button is misaligned" description = "Génère un correctif pour un problème donné." prompt = "Veuillez fournir un correctif de code pour le problème décrit ici : {{args}}." @@ -239,9 +252,9 @@ prompt = "Veuillez fournir un correctif de code pour le problème décrit ici : Le modèle reçoit : `Veuillez fournir un correctif de code pour le problème décrit ici : "Button is misaligned".` -**B. Utilisation des Arguments dans les Commandes Shell (À l'intérieur des blocs `!{...}`)** +**B. Utilisation des Arguments dans les Commandes Shell (À l'intérieur des Blocs `!{...}`)** -Lorsque vous utilisez `{{args}}` à l'intérieur d'un bloc d'injection shell (`!{...}`), les arguments sont automatiquement **échappés pour le shell** avant remplacement. Cela vous permet de passer des arguments en toute sécurité aux commandes shell, en garantissant que la commande résultante est syntaxiquement correcte et sécurisée, tout en évitant les vulnérabilités d'injection de commande. +Lorsque vous utilisez `{{args}}` à l'intérieur d'un bloc d'injection shell (`!{...}`), les arguments sont automatiquement **échappés pour le shell** avant remplacement. Cela vous permet de passer en toute sécurité des arguments aux commandes shell, garantissant que la commande résultante est syntaxiquement correcte et sécurisée tout en évitant les vulnérabilités d'injection de commande. **Exemple (`/grep-code.toml`) :** @@ -296,11 +309,10 @@ Votre tâche consiste à parser ``, ``, et `` dep La commande suit ce format : `/changelog ` - `` doit être parmi : "added", "changed", "fixed", "removed".""" -```markdown ## Comportement 1. Lire le fichier `CHANGELOG.md`. 2. Trouver la section correspondant à la `` spécifiée. -3. Ajouter le `` sous le titre `` approprié. +3. Ajouter le `` sous l'en-tête `` approprié. 4. Si la section version ou type n'existe pas, la créer. 5. Suivre strictement le format "Keep a Changelog". """ @@ -310,15 +322,15 @@ Lorsque vous exécutez `/changelog 1.2.0 added "New feature"`, le texte final en ##### 3. Exécution de commandes Shell avec `!{...}` -Vous pouvez rendre vos commandes dynamiques en exécutant directement des commandes shell dans votre `prompt` et en injectant leur sortie. C'est idéal pour récupérer du contexte depuis votre environnement local, comme lire le contenu d'un fichier ou vérifier l'état de Git. +Vous pouvez rendre vos commandes dynamiques en exécutant directement des commandes shell au sein de votre `prompt` et en injectant leur sortie. C'est idéal pour récupérer du contexte depuis votre environnement local, comme lire le contenu d'un fichier ou vérifier l'état d'un dépôt Git. -Lorsqu'une commande personnalisée tente d'exécuter une commande shell, Qwen Code vous demandera maintenant une confirmation avant de continuer. Il s'agit d'une mesure de sécurité pour s'assurer que seules les commandes voulues sont exécutées. +Lorsqu'une commande personnalisée tente d'exécuter une commande shell, Qwen Code vous demandera maintenant une confirmation avant de procéder. Il s'agit d'une mesure de sécurité pour s'assurer que seules les commandes intentionnelles sont exécutées. **Fonctionnement :** 1. **Injection de commandes :** Utilisez la syntaxe `!{...}`. -2. **Substitution des arguments :** Si `{{args}}` est présent dans le bloc, il est automatiquement échappé pour le shell (voir [Injection contextuelle](#1-context-aware-injection-with-args) ci-dessus). -3. **Parsing robuste :** L'analyseur gère correctement les commandes shell complexes contenant des accolades imbriquées, comme les payloads JSON. +2. **Substitution d'arguments :** Si `{{args}}` est présent à l'intérieur du bloc, il est automatiquement échappé pour le shell (voir [Injection contextuelle](#1-context-aware-injection-with-args) ci-dessus). +3. **Parsing robuste :** L'analyseur gère correctement les commandes shell complexes contenant des accolades imbriquées, comme des payloads JSON. **Note :** Le contenu à l'intérieur de `!{...}` doit avoir des accolades équilibrées (`{` et `}`). Si vous devez exécuter une commande contenant des accolades non équilibrées, envisagez de l'encapsuler dans un script externe et d'appeler ce script à l'intérieur du bloc `!{...}`. 4. **Vérification de sécurité et confirmation :** Le CLI effectue une vérification de sécurité sur la commande finale résolue (après échappement et substitution des arguments). Une boîte de dialogue apparaîtra montrant la ou les commandes exactes à exécuter. 5. **Exécution et rapport d'erreurs :** La commande est exécutée. Si la commande échoue, la sortie injectée dans le prompt inclura les messages d'erreur (stderr) suivis d'une ligne indiquant le statut, par exemple `[Shell command exited with code 1]`. Cela permet au modèle de comprendre le contexte de l'échec. @@ -332,7 +344,7 @@ Cette commande récupère le diff git staged et l'utilise pour demander au modè # Invoqué via : /git:commit -description = "Génère un message de commit Git basé sur les modifications staged." +description = "Génère un message de commit Git basé sur les modifications stagées." # Le prompt utilise !{...} pour exécuter la commande et injecter sa sortie. prompt = """ @@ -348,11 +360,50 @@ Veuillez générer un message de commit Conventional Commit basé sur le git dif Lorsque vous exécutez `/git:commit`, le CLI exécute d'abord `git diff --staged`, puis remplace `!{git diff --staged}` par la sortie de cette commande avant d'envoyer le prompt final et complet au modèle. +##### 4. Injection du contenu d'un fichier avec `@{...}` + +Vous pouvez directement intégrer le contenu d'un fichier ou une liste de répertoires dans votre prompt en utilisant la syntaxe `@{...}`. Cela est utile pour créer des commandes qui agissent sur des fichiers spécifiques. + +**Fonctionnement :** + +- **Injection de fichier** : `@{chemin/vers/fichier.txt}` est remplacé par le contenu de `fichier.txt`. +- **Support multimodal** : Si le chemin pointe vers une image supportée (ex. : PNG, JPEG), un PDF, un fichier audio ou vidéo, il sera correctement encodé et injecté comme entrée multimodale. Les autres fichiers binaires sont gérés proprement et ignorés. +- **Liste de répertoires** : `@{chemin/vers/dossier}` est parcouru et chaque fichier présent dans ce dossier ainsi que dans tous ses sous-dossiers est inséré dans le prompt. Cette opération respecte les fichiers `.gitignore` et `.qwenignore`, si activés. +- **Prise en compte de l'espace de travail** : La commande recherche le chemin dans le répertoire courant ainsi que dans les autres répertoires définis dans l’espace de travail. Les chemins absolus sont autorisés s'ils se trouvent à l'intérieur de cet espace. +- **Ordre de traitement** : L'injection du contenu via `@{...}` est effectuée _avant_ l’exécution des commandes shell (`!{...}`) et la substitution d’arguments (`{{args}}`). +- **Analyse syntaxique** : Le parseur exige que le contenu entre accolades dans `@{...}` (le chemin) soit bien équilibré en termes d'accolades (`{` et `}`). + +**Exemple (`review.toml`) :** + +Cette commande injecte le contenu d’un fichier de bonnes pratiques _fixe_ (`docs/best-practices.md`) et utilise les arguments fournis par l'utilisateur pour fournir un contexte à la revue. + +```toml + +```toml +# Dans : /.qwen/commands/review.toml + +# Invoqué via : /review FileCommandLoader.ts + +description = "Examine le contexte fourni en utilisant un guide de bonnes pratiques." +prompt = """ +Vous êtes un expert en revue de code. + +Votre tâche consiste à examiner {{args}}. + +Utilisez les bonnes pratiques suivantes lors de votre revue : + +@{docs/best-practices.md} +``` + +Lorsque vous exécutez `/review FileCommandLoader.ts`, le placeholder `@{docs/best-practices.md}` est remplacé par le contenu de ce fichier, et `{{args}}` est remplacé par le texte que vous avez fourni, avant que le prompt final soit envoyé au modèle. + +--- + #### Exemple : Commande de refactoring "Fonction Pure" Créons une commande globale qui demande au modèle de refactorer un morceau de code. -**1. Créer le fichier et les répertoires :** +**1. Créez le fichier et les répertoires :** Tout d'abord, assurez-vous que le répertoire des commandes utilisateur existe, puis créez un sous-répertoire `refactor` pour l'organisation et le fichier TOML final. @@ -361,9 +412,9 @@ mkdir -p ~/.qwen/commands/refactor touch ~/.qwen/commands/refactor/pure.toml ``` -**2. Ajouter le contenu au fichier :** +**2. Ajoutez le contenu au fichier :** -Ouvrez `~/.qwen/commands/refactor/pure.toml` dans votre éditeur et ajoutez le contenu suivant. Nous incluons le `description` optionnel pour respecter les bonnes pratiques. +Ouvrez `~/.qwen/commands/refactor/pure.toml` dans votre éditeur et ajoutez le contenu suivant. Nous incluons le `description` optionnel par souci de bonne pratique. ```toml @@ -397,32 +448,32 @@ Qwen Code exécutera alors le prompt multiligne défini dans votre fichier TOML. ## Commandes At (`@`) -Les commandes At sont utilisées pour inclure le contenu de fichiers ou de répertoires dans votre prompt envoyé au modèle. Ces commandes prennent en charge le filtrage git-aware. +Les commandes At sont utilisées pour inclure le contenu de fichiers ou de répertoires dans votre prompt envoyé au modèle. Ces commandes prennent en compte le filtrage git-aware. -- **`@`** - - **Description :** Injecte le contenu du fichier ou des fichiers spécifiés dans votre prompt actuel. Cela est utile pour poser des questions sur du code spécifique, du texte ou des collections de fichiers. +- **`@`** + - **Description :** Injecte le contenu du fichier ou des fichiers spécifiés dans votre prompt actuel. Cela est utile pour poser des questions sur un code spécifique, un texte ou une collection de fichiers. - **Exemples :** - `@chemin/vers/votre/fichier.txt Explique ce texte.` - `@src/mon_projet/ Résume le code dans ce répertoire.` - `De quoi parle ce fichier ? @README.md` - **Détails :** - Si un chemin vers un seul fichier est fourni, le contenu de ce fichier est lu. - - Si un chemin vers un répertoire est fourni, la commande tente de lire le contenu des fichiers dans ce répertoire et ses sous-répertoires. + - Si un chemin vers un répertoire est fourni, la commande tente de lire le contenu des fichiers présents dans ce répertoire et ses sous-répertoires. - Les espaces dans les chemins doivent être échappés avec un antislash (ex. : `@Mes\ Documents/fichier.txt`). - - La commande utilise en interne l'outil `read_many_files`. Le contenu est récupéré puis inséré dans votre requête avant d'être envoyé au modèle. + - La commande utilise l'outil `read_many_files` en interne. Le contenu est récupéré puis inséré dans votre requête avant d'être envoyé au modèle. - **Filtrage git-aware :** Par défaut, les fichiers ignorés par git (comme `node_modules/`, `dist/`, `.env`, `.git/`) sont exclus. Ce comportement peut être modifié via les paramètres `fileFiltering`. - - **Types de fichiers :** La commande est destinée aux fichiers textuels. Bien qu'elle puisse tenter de lire n'importe quel fichier, les fichiers binaires ou très volumineux peuvent être ignorés ou tronqués par l'outil `read_many_files` sous-jacent afin de garantir performance et pertinence. L'outil indique si des fichiers ont été ignorés. - - **Sortie :** Le CLI affichera un message d'appel d'outil indiquant que `read_many_files` a été utilisé, accompagné d'un message détaillant le statut et les chemins traités. + - **Types de fichiers :** La commande est destinée aux fichiers textuels. Bien qu'elle puisse tenter de lire n’importe quel fichier, les fichiers binaires ou très volumineux peuvent être ignorés ou tronqués par l’outil `read_many_files` afin de garantir performances et pertinence. L’outil indique si certains fichiers ont été ignorés. + - **Sortie :** Le CLI affichera un message d'appel à l'outil indiquant que `read_many_files` a été utilisé, accompagné d’un message détaillant le statut ainsi que les chemins traités. - **`@` (Symbole @ seul)** - - **Description :** Si vous tapez un symbole `@` seul sans chemin, la requête est transmise telle quelle au modèle. Cela peut être utile si vous parlez _explicitement_ du symbole `@` dans votre prompt. + - **Description :** Si vous saisissez uniquement le symbole `@` sans préciser de chemin, la requête est transmise telle quelle au modèle. Cela peut être utile si vous discutez explicitement _du_ symbole `@` dans votre prompt. ### Gestion des erreurs pour les commandes `@` - Si le chemin spécifié après `@` n'est pas trouvé ou est invalide, un message d'erreur sera affiché, et la requête pourrait ne pas être envoyée au modèle, ou elle sera envoyée sans le contenu du fichier. - Si l'outil `read_many_files` rencontre une erreur (par exemple, des problèmes de permissions), cela sera également signalé. -## Mode shell & commandes pass-through (`!`) +## Mode shell & commandes de relais (`!`) Le préfixe `!` vous permet d'interagir directement avec le shell de votre système depuis Qwen Code. @@ -432,14 +483,14 @@ Le préfixe `!` vous permet d'interagir directement avec le shell de votre syst - `!ls -la` (exécute `ls -la` et retourne à Qwen Code) - `!git status` (exécute `git status` et retourne à Qwen Code) -- **`!` (Activer/désactiver le mode shell)** - - **Description :** Saisir `!` seul active ou désactive le mode shell. - - **Entrer en mode shell :** - - Une fois activé, le mode shell utilise une coloration différente et un "Shell Mode Indicator". +- **`!` (Basculer en mode shell)** + - **Description :** Saisir `!` seul permet de basculer en mode shell. + - **Entrée en mode shell :** + - Lorsqu'il est actif, le mode shell utilise une coloration différente et un "Shell Mode Indicator". - En mode shell, le texte que vous saisissez est interprété directement comme une commande shell. - - **Sortir du mode shell :** - - Une fois désactivé, l'interface retrouve son apparence standard et le comportement normal de Qwen Code reprend. + - **Sortie du mode shell :** + - Une fois sorti, l'interface retrouve son apparence standard et le comportement normal de Qwen Code reprend. - **Attention pour toute utilisation de `!` :** Les commandes que vous exécutez en mode shell ont les mêmes permissions et le même impact que si vous les exécutiez directement dans votre terminal. -- **Variable d'environnement :** Lorsqu'une commande est exécutée via `!` ou en mode shell, la variable d'environnement `QWEN_CODE=1` est définie dans l'environnement du sous-processus. Cela permet aux scripts ou outils de détecter s'ils sont exécutés depuis le CLI. \ No newline at end of file +- **Variable d'environnement :** Lorsqu'une commande est exécutée via `!` ou en mode shell, la variable d'environnement `QWEN_CODE=1` est définie dans l'environnement du sous-processus. Cela permet aux scripts ou outils de détecter s'ils sont exécutés depuis l'interface CLI. \ No newline at end of file diff --git a/website/content/fr/cli/configuration.md b/website/content/fr/cli/configuration.md index dd5ef04e..9bcef7eb 100644 --- a/website/content/fr/cli/configuration.md +++ b/website/content/fr/cli/configuration.md @@ -7,28 +7,34 @@ Qwen Code offre plusieurs façons de configurer son comportement, notamment via La configuration est appliquée selon l'ordre de priorité suivant (les numéros inférieurs sont écrasés par les numéros supérieurs) : 1. **Valeurs par défaut :** Valeurs codées en dur dans l'application. -2. **Fichier de configuration utilisateur :** Paramètres globaux pour l'utilisateur actuel. -3. **Fichier de configuration projet :** Paramètres spécifiques au projet. -4. **Fichier de configuration système :** Paramètres applicables à l'ensemble du système. -5. **Variables d'environnement :** Variables globales au système ou spécifiques à une session, pouvant être chargées depuis des fichiers `.env`. -6. **Arguments en ligne de commande :** Valeurs passées lors du lancement de la CLI. +2. **Fichier de valeurs par défaut système :** Paramètres par défaut à l'échelle du système, pouvant être remplacés par d'autres fichiers de configuration. +3. **Fichier de paramètres utilisateur :** Paramètres globaux pour l'utilisateur actuel. +4. **Fichier de paramètres projet :** Paramètres spécifiques au projet. +5. **Fichier de paramètres système :** Paramètres à l'échelle du système qui remplacent tous les autres fichiers de configuration. +6. **Variables d'environnement :** Variables à l'échelle du système ou spécifiques à une session, pouvant être chargées depuis des fichiers `.env`. +7. **Arguments en ligne de commande :** Valeurs passées lors du lancement de la CLI. ## Fichiers de configuration -Qwen Code utilise des fichiers `settings.json` pour la configuration persistante. Il existe trois emplacements possibles pour ces fichiers : +Qwen Code utilise des fichiers de configuration au format JSON pour stocker les paramètres de manière persistante. Il existe quatre emplacements possibles pour ces fichiers : -- **Fichier de configuration utilisateur :** - - **Emplacement :** `~/.qwen/settings.json` (où `~` représente votre répertoire personnel). - - **Portée :** S'applique à toutes les sessions Qwen Code de l'utilisateur courant. -- **Fichier de configuration projet :** +- **Fichier des valeurs par défaut du système :** + - **Emplacement :** `/etc/qwen-code/system-defaults.json` (Linux), `C:\ProgramData\qwen-code\system-defaults.json` (Windows) ou `/Library/Application Support/QwenCode/system-defaults.json` (macOS). Ce chemin peut être modifié via la variable d’environnement `QWEN_CODE_SYSTEM_DEFAULTS_PATH`. + - **Portée :** Fournit une couche de base contenant les paramètres par défaut à l’échelle du système. Ces paramètres ont la priorité la plus faible et sont destinés à être écrasés par les paramètres utilisateur, projet ou système. + +- **Fichier des paramètres utilisateur :** + - **Emplacement :** `~/.qwen/settings.json` (où `~` correspond à votre répertoire personnel). + - **Portée :** S’applique à toutes les sessions Qwen Code de l’utilisateur courant. + +- **Fichier des paramètres projet :** - **Emplacement :** `.qwen/settings.json` à la racine de votre projet. - - **Portée :** S'applique uniquement lorsque Qwen Code est exécuté depuis ce projet spécifique. Les paramètres du projet prennent le pas sur ceux de l'utilisateur. + - **Portée :** S’applique uniquement lorsque Qwen Code est exécuté depuis ce projet spécifique. Les paramètres projet prennent le pas sur les paramètres utilisateur. -- **Fichier de configuration système :** - - **Emplacement :** `/etc/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) ou `/Library/Application Support/QwenCode/settings.json` (macOS). Ce chemin peut être modifié via la variable d'environnement `QWEN_CODE_SYSTEM_SETTINGS_PATH`. - - **Portée :** S'applique à toutes les sessions Qwen Code sur le système, pour tous les utilisateurs. Les paramètres système prennent le pas sur ceux de l'utilisateur et du projet. Peut être utile aux administrateurs système dans les entreprises pour contrôler les configurations Qwen Code des utilisateurs. +- **Fichier des paramètres système :** + - **Emplacement :** `/etc/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) ou `/Library/Application Support/QwenCode/settings.json` (macOS). Ce chemin peut être modifié via la variable d’environnement `QWEN_CODE_SYSTEM_SETTINGS_PATH`. + - **Portée :** S’applique à toutes les sessions Qwen Code sur le système, pour tous les utilisateurs. Les paramètres système prennent le pas sur les paramètres utilisateur et projet. Peut être utile aux administrateurs système dans un environnement professionnel afin de contrôler les configurations Qwen Code des utilisateurs. -**Remarque sur les variables d’environnement dans les paramètres :** Les valeurs de type chaîne dans vos fichiers `settings.json` peuvent référencer des variables d’environnement en utilisant la syntaxe `$VAR_NAME` ou `${VAR_NAME}`. Ces variables seront automatiquement résolues au chargement des paramètres. Par exemple, si vous avez une variable d’environnement `MY_API_TOKEN`, vous pouvez l’utiliser dans `settings.json` comme ceci : `"apiKey": "$MY_API_TOKEN"`. +**Remarque sur les variables d’environnement dans les paramètres :** Les valeurs de type chaîne de caractères dans vos fichiers `settings.json` peuvent faire référence à des variables d’environnement en utilisant la syntaxe `$VAR_NAME` ou `${VAR_NAME}`. Ces variables seront automatiquement résolues au chargement des paramètres. Par exemple, si vous avez une variable d’environnement `MY_API_TOKEN`, vous pouvez l’utiliser dans `settings.json` comme ceci : `"apiKey": "$MY_API_TOKEN"`. ### Le répertoire `.qwen` dans votre projet @@ -39,13 +45,13 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro ### Paramètres disponibles dans `settings.json` : - **`contextFileName`** (string ou tableau de strings) : - - **Description :** Spécifie le nom du fichier de contexte (ex. `QWEN.md`, `AGENTS.md`). Peut être un seul nom de fichier ou une liste de noms acceptés. - - **Par défaut :** `QWEN.md` + - **Description :** Spécifie le nom du fichier de contexte (ex. : `QWEN.md`, `AGENTS.md`). Peut être un seul nom de fichier ou une liste de noms acceptés. + - **Valeur par défaut :** `QWEN.md` - **Exemple :** `"contextFileName": "AGENTS.md"` -- **`bugCommand`** (objet) : - - **Description :** Remplace l'URL par défaut pour la commande `/bug`. - - **Par défaut :** `"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"` +- **`bugCommand`** (object) : + - **Description :** Remplace l'URL par défaut utilisée par la commande `/bug`. + - **Valeur par défaut :** `"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"` - **Propriétés :** - **`urlTemplate`** (string) : Une URL pouvant contenir les placeholders `{title}` et `{info}`. - **Exemple :** @@ -55,93 +61,110 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro } ``` -- **`fileFiltering`** (objet) : - - **Description :** Contrôle le comportement de filtrage des fichiers compatible Git pour les commandes @ et les outils de découverte de fichiers. - - **Par défaut :** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` +- **`fileFiltering`** (object) : + - **Description :** Contrôle le comportement du filtrage des fichiers compatible Git pour les commandes @ et les outils de découverte de fichiers. + - **Valeur par défaut :** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` - **Propriétés :** - - **`respectGitIgnore`** (boolean) : Indique si les patterns de `.gitignore` doivent être respectés lors de la découverte des fichiers. Si `true`, les fichiers ignorés par Git (comme `node_modules/`, `dist/`, `.env`) sont automatiquement exclus des commandes @ et des listes de fichiers. - - **`enableRecursiveFileSearch`** (boolean) : Indique si la recherche récursive des fichiers doit être activée lors de la complétion des préfixes @ dans le prompt. + - **`respectGitIgnore`** (boolean) : Indique si les règles du `.gitignore` doivent être respectées lors de la découverte des fichiers. Si `true`, les fichiers ignorés par Git (comme `node_modules/`, `dist/`, `.env`) sont automatiquement exclus des commandes @ et des listes de fichiers. + - **`enableRecursiveFileSearch`** (boolean) : Active ou non la recherche récursive des fichiers dans l'arborescence courante lors de l'autocomplétion des préfixes @ dans le prompt. + - **`disableFuzzySearch`** (boolean) : Si `true`, désactive la recherche floue (fuzzy search) lors de la recherche de fichiers, ce qui peut améliorer les performances sur les projets contenant un grand nombre de fichiers. - **Exemple :** ```json "fileFiltering": { "respectGitIgnore": true, - "enableRecursiveFileSearch": false + "enableRecursiveFileSearch": false, + "disableFuzzySearch": true } ``` -- **`coreTools`** (tableau de strings) : - - **Description :** Permet de spécifier une liste d'outils intégrés qui doivent être disponibles pour le modèle. Cela peut servir à restreindre l'ensemble des outils intégrés. Voir [Built-in Tools](../core/tools-api.md#built-in-tools) pour la liste des outils. Vous pouvez également spécifier des restrictions par commande pour les outils qui le supportent, comme `ShellTool`. Par exemple, `"coreTools": ["ShellTool(ls -l)"]` n'autorisera que la commande `ls -l`. - - **Par défaut :** Tous les outils disponibles pour le modèle. +### Résolution des problèmes de performance de recherche de fichiers + +Si vous rencontrez des problèmes de performance avec la recherche de fichiers (par exemple, avec les complétions `@`), en particulier dans des projets comportant un très grand nombre de fichiers, voici quelques solutions que vous pouvez essayer par ordre de recommandation : + +1. **Utiliser `.qwenignore` :** Créez un fichier `.qwenignore` à la racine de votre projet pour exclure les répertoires contenant un grand nombre de fichiers dont vous n'avez pas besoin de référencer (par exemple, les artefacts de build, les logs, `node_modules`). Réduire le nombre total de fichiers parcourus est le moyen le plus efficace d'améliorer les performances. + +2. **Désactiver la recherche floue :** Si ignorer des fichiers ne suffit pas, vous pouvez désactiver la recherche floue en définissant `disableFuzzySearch` sur `true` dans votre fichier `settings.json`. Cela utilisera un algorithme de correspondance plus simple et non flou, ce qui peut être plus rapide. + +3. **Désactiver la recherche récursive de fichiers :** En dernier recours, vous pouvez désactiver entièrement la recherche récursive de fichiers en définissant `enableRecursiveFileSearch` sur `false`. Cette option sera la plus rapide car elle évite un parcours récursif de votre projet. Cependant, cela signifie que vous devrez taper le chemin complet des fichiers lors de l'utilisation des complétions `@`. + +- **`coreTools`** (tableau de chaînes de caractères) : + - **Description :** Permet de spécifier une liste de noms d’outils principaux qui doivent être mis à disposition du modèle. Cela peut servir à restreindre l’ensemble des outils intégrés. Voir [Outils intégrés](../core/tools-api.md#built-in-tools) pour obtenir la liste des outils principaux. Vous pouvez également spécifier des restrictions spécifiques aux commandes pour les outils qui le permettent, comme `ShellTool`. Par exemple, `"coreTools": ["ShellTool(ls -l)"]` autorisera uniquement l’exécution de la commande `ls -l`. + - **Par défaut :** Tous les outils sont disponibles pour le modèle. - **Exemple :** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`. -- **`excludeTools`** (tableau de strings) : - - **Description :** Permet de spécifier une liste d'outils intégrés à exclure du modèle. Un outil présent à la fois dans `excludeTools` et `coreTools` est exclu. Vous pouvez également spécifier des restrictions par commande pour les outils compatibles, comme `ShellTool`. Par exemple, `"excludeTools": ["ShellTool(rm -rf)"]` bloquera la commande `rm -rf`. +- **`allowedTools`** (tableau de chaînes de caractères) : + - **Par défaut :** `undefined` + - **Description :** Liste de noms d’outils qui contourneront la boîte de dialogue de confirmation. Utile pour les outils fiables et fréquemment utilisés. La logique de correspondance est identique à celle de `coreTools`. + - **Exemple :** `"allowedTools": ["ShellTool(git status)"]`. + +- **`excludeTools`** (tableau de chaînes de caractères) : + - **Description :** Permet de spécifier une liste de noms d’outils principaux devant être exclus du modèle. Un outil figurant à la fois dans `excludeTools` et `coreTools` est exclu. Vous pouvez également spécifier des restrictions spécifiques aux commandes pour les outils compatibles, comme `ShellTool`. Par exemple, `"excludeTools": ["ShellTool(rm -rf)"]` bloquera la commande `rm -rf`. - **Par défaut :** Aucun outil exclu. - **Exemple :** `"excludeTools": ["run_shell_command", "findFiles"]`. - - **Note de sécurité :** Les restrictions par commande dans `excludeTools` pour `run_shell_command` reposent sur une simple comparaison de chaînes de caractères et peuvent être facilement contournées. Cette fonctionnalité **n'est pas un mécanisme de sécurité** et ne doit pas être utilisée pour exécuter du code non fiable en toute sécurité. Il est recommandé d'utiliser `coreTools` pour sélectionner explicitement les commandes autorisées. + - **Remarque sur la sécurité :** Les restrictions spécifiques aux commandes dans `excludeTools` pour `run_shell_command` reposent sur une simple correspondance de chaînes de caractères et peuvent facilement être contournées. Cette fonctionnalité **n’est pas un mécanisme de sécurité** et ne doit pas être utilisée pour exécuter en toute sécurité du code non fiable. Il est recommandé d’utiliser `coreTools` pour sélectionner explicitement les commandes pouvant être exécutées. -- **`allowMCPServers`** (tableau de strings) : - - **Description :** Permet de spécifier une liste de serveurs MCP qui doivent être disponibles pour le modèle. Cela peut servir à restreindre l'ensemble des serveurs MCP auxquels se connecter. Notez que ce paramètre est ignoré si `--allowed-mcp-server-names` est défini. +- **`allowMCPServers`** (tableau de chaînes de caractères) : + - **Description :** Permet de spécifier une liste de noms de serveurs MCP devant être mis à disposition du modèle. Cela peut servir à limiter l’ensemble des serveurs MCP auxquels se connecter. Notez que cette valeur sera ignorée si `--allowed-mcp-server-names` est défini. - **Par défaut :** Tous les serveurs MCP sont disponibles pour le modèle. - **Exemple :** `"allowMCPServers": ["myPythonServer"]`. - - **Note de sécurité :** Ce paramètre utilise une simple comparaison de chaînes de caractères sur les noms de serveurs MCP, qui peuvent être modifiés. Si vous êtes administrateur système et souhaitez empêcher les utilisateurs de contourner ce paramètre, configurez `mcpServers` au niveau des paramètres système de sorte que l'utilisateur ne puisse pas configurer ses propres serveurs MCP. Ce mécanisme ne doit pas être considéré comme une sécurité infaillible. + - **Remarque sur la sécurité :** Cette fonction utilise une simple correspondance de chaînes de caractères sur les noms de serveurs MCP, qui peuvent être modifiés. Si vous êtes administrateur système et souhaitez empêcher les utilisateurs de contourner ce paramètre, envisagez de configurer `mcpServers` au niveau des paramètres système afin que l’utilisateur ne puisse configurer aucun serveur MCP personnel. Ce mécanisme ne doit pas être considéré comme une protection absolue. -- **`excludeMCPServers`** (tableau de strings) : - - **Description :** Permet de spécifier une liste de serveurs MCP à exclure du modèle. Un serveur présent à la fois dans `excludeMCPServers` et `allowMCPServers` est exclu. Notez que ce paramètre est ignoré si `--allowed-mcp-server-names` est défini. +- **`excludeMCPServers`** (tableau de chaînes de caractères) : + - **Description :** Permet de spécifier une liste de noms de serveurs MCP devant être exclus du modèle. Un serveur figurant à la fois dans `excludeMCPServers` et `allowMCPServers` est exclu. Notez que cette valeur sera ignorée si `--allowed-mcp-server-names` est défini. - **Par défaut :** Aucun serveur MCP exclu. - **Exemple :** `"excludeMCPServers": ["myNodeServer"]`. - - **Note de sécurité :** Ce paramètre utilise une simple comparaison de chaînes de caractères sur les noms de serveurs MCP, qui peuvent être modifiés. Si vous êtes administrateur système et souhaitez empêcher les utilisateurs de contourner ce paramètre, configurez `mcpServers` au niveau des paramètres système de sorte que l'utilisateur ne puisse pas configurer ses propres serveurs MCP. Ce mécanisme ne doit pas être considéré comme une sécurité infaillible. + - **Remarque sur la sécurité :** Cette fonction utilise une simple correspondance de chaînes de caractères sur les noms de serveurs MCP, qui peuvent être modifiés. Si vous êtes administrateur système et souhaitez empêcher les utilisateurs de contourner ce paramètre, envisagez de configurer `mcpServers` au niveau des paramètres système afin que l’utilisateur ne puisse configurer aucun serveur MCP personnel. Ce mécanisme ne doit pas être considéré comme une protection absolue. -- **`autoAccept`** (boolean) : - - **Description :** Contrôle si le CLI accepte et exécute automatiquement les appels d'outils jugés sûrs (ex. opérations en lecture seule) sans confirmation explicite de l'utilisateur. Si `true`, le CLI contourne la demande de confirmation pour les outils considérés comme sûrs. +- **`autoAccept`** (booléen) : + - **Description :** Contrôle si l’interface CLI accepte automatiquement et exécute les appels d’outils jugés sûrs (par exemple, les opérations en lecture seule) sans confirmation explicite de l’utilisateur. Si défini sur `true`, l’interface CLI ignore la demande de confirmation pour les outils considérés comme sûrs. - **Par défaut :** `false` - **Exemple :** `"autoAccept": true` -- **`theme`** (string) : +- **`theme`** (chaîne de caractères) : - **Description :** Définit le [thème](./themes.md) visuel de Qwen Code. - **Par défaut :** `"Default"` - **Exemple :** `"theme": "GitHub"` -- **`vimMode`** (boolean) : - - **Description :** Active ou désactive le mode vim pour l'édition de texte. Lorsqu'il est activé, la zone de saisie supporte les commandes de navigation et d'édition de type vim avec les modes NORMAL et INSERT. Le statut du mode vim est affiché dans le footer et persiste entre les sessions. +- **`vimMode`** (booléen) : + - **Description :** Active ou désactive le mode vim pour l’édition de texte. Une fois activé, la zone de saisie prend en charge les commandes de navigation et d’édition de style vim avec les modes NORMAL et INSERT. Le statut du mode vim s'affiche dans le pied de page et persiste entre les sessions. - **Par défaut :** `false` - **Exemple :** `"vimMode": true` -- **`sandbox`** (boolean ou string) : - - **Description :** Contrôle si et comment utiliser le sandboxing pour l'exécution des outils. Si `true`, Qwen Code utilise une image Docker pré-construite `qwen-code-sandbox`. Pour plus d'informations, voir [Sandboxing](#sandboxing). +- **`sandbox`** (booléen ou chaîne de caractères) : + - **Description :** Contrôle si et comment utiliser le bac à sable (sandbox) pour l’exécution des outils. Si défini sur `true`, Qwen Code utilise une image Docker prédéfinie `qwen-code-sandbox`. Pour plus d’informations, voir [Bac à sable (Sandboxing)](#sandboxing). - **Par défaut :** `false` - **Exemple :** `"sandbox": "docker"` -- **`toolDiscoveryCommand`** (string) : - - **Description :** Définit une commande shell personnalisée pour découvrir les outils de votre projet. La commande doit retourner sur `stdout` un tableau JSON de [déclarations de fonctions](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). Les wrappers d'outils sont optionnels. +- **`toolDiscoveryCommand`** (chaîne de caractères) : + - **Description :** **Aligné avec l’interface CLI de Gemini.** Définit une commande shell personnalisée pour découvrir les outils depuis votre projet. La commande shell doit renvoyer sur `stdout` un tableau JSON de [déclarations de fonctions](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). Les wrappers d’outils sont facultatifs. - **Par défaut :** Vide - **Exemple :** `"toolDiscoveryCommand": "bin/get_tools"` -- **`toolCallCommand`** (string) : - - **Description :** Définit une commande shell personnalisée pour appeler un outil spécifique découvert via `toolDiscoveryCommand`. La commande doit respecter les critères suivants : - - Prendre le `name` de la fonction (exactement comme dans la [déclaration de fonction](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) comme premier argument. - - Lire les arguments de la fonction au format JSON depuis `stdin`, de manière similaire à [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). - - Retourner la sortie de la fonction au format JSON sur `stdout`, de manière similaire à [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). +- **`toolCallCommand`** (chaîne de caractères) : + - **Description :** **Aligné avec l’interface CLI de Gemini.** Définit une commande shell personnalisée pour appeler un outil spécifique découvert via `toolDiscoveryCommand`. La commande shell doit respecter les critères suivants : + - Elle doit prendre le `nom` de la fonction (exactement tel que dans la [déclaration de fonction](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) comme premier argument de ligne de commande. + - Elle doit lire les arguments de la fonction au format JSON depuis `stdin`, de manière similaire à [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). + - Elle doit retourner la sortie de la fonction au format JSON sur `stdout`, de manière similaire à [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). - **Par défaut :** Vide - **Exemple :** `"toolCallCommand": "bin/call_tool"` - **`mcpServers`** (objet) : - - **Description :** Configure les connexions à un ou plusieurs serveurs Model-Context Protocol (MCP) pour découvrir et utiliser des outils personnalisés. Qwen Code tente de se connecter à chaque serveur MCP configuré pour découvrir les outils disponibles. Si plusieurs serveurs MCP exposent un outil avec le même nom, les noms des outils seront préfixés avec l'alias du serveur défini dans la configuration (ex. `serverAlias__actualToolName`) pour éviter les conflits. Notez que le système peut retirer certaines propriétés de schéma des définitions d'outils MCP pour des raisons de compatibilité. Au moins un des champs `command`, `url` ou `httpUrl` doit être fourni. Si plusieurs sont spécifiés, l'ordre de priorité est : `httpUrl`, puis `url`, puis `command`. + - **Description :** Configure les connexions vers un ou plusieurs serveurs Model-Context Protocol (MCP) pour découvrir et utiliser des outils personnalisés. Qwen Code tente de se connecter à chaque serveur MCP configuré afin de découvrir les outils disponibles. Si plusieurs serveurs MCP exposent un outil portant le même nom, les noms des outils seront préfixés avec l’alias du serveur défini dans la configuration (par exemple, `serverAlias__actualToolName`) afin d’éviter les conflits. Notez que le système peut supprimer certaines propriétés de schéma des définitions d’outils MCP pour des raisons de compatibilité. Au moins l’un des champs `command`, `url` ou `httpUrl` doit être fourni. Si plusieurs sont spécifiés, l’ordre de priorité est `httpUrl`, puis `url`, puis `command`. - **Par défaut :** Vide - **Propriétés :** - - **``** (objet) : Les paramètres du serveur nommé. - - `command` (string, optionnel) : La commande à exécuter pour démarrer le serveur MCP via les E/S standards. - - `args` (tableau de strings, optionnel) : Arguments à passer à la commande. - - `env` (objet, optionnel) : Variables d'environnement à définir pour le processus du serveur. - - `cwd` (string, optionnel) : Le répertoire de travail dans lequel démarrer le serveur. - - `url` (string, optionnel) : L'URL d'un serveur MCP utilisant Server-Sent Events (SSE) pour communiquer. - - `httpUrl` (string, optionnel) : L'URL d'un serveur MCP utilisant HTTP streamable pour communiquer. - - `headers` (objet, optionnel) : Une map d'en-têtes HTTP à envoyer avec les requêtes vers `url` ou `httpUrl`. - - `timeout` (number, optionnel) : Timeout en millisecondes pour les requêtes vers ce serveur MCP. - - `trust` (boolean, optionnel) : Faire confiance à ce serveur et contourner toutes les confirmations d'appel d'outils. - - `description` (string, optionnel) : Une brève description du serveur, pouvant être utilisée à des fins d'affichage. - - `includeTools` (tableau de strings, optionnel) : Liste des noms d'outils à inclure depuis ce serveur MCP. Si spécifié, seuls les outils listés ici seront disponibles (comportement whitelist). Sinon, tous les outils du serveur sont activés par défaut. - - `excludeTools` (tableau de strings, optionnel) : Liste des noms d'outils à exclure de ce serveur MCP. Les outils listés ici ne seront pas disponibles pour le modèle, même s'ils sont exposés par le serveur. **Note :** `excludeTools` a priorité sur `includeTools` – si un outil est dans les deux listes, il sera exclu. + - **``** (objet) : Paramètres du serveur nommé. + - `command` (chaîne de caractères, optionnel) : Commande à exécuter pour démarrer le serveur MCP via les E/S standards. + - `args` (tableau de chaînes de caractères, optionnel) : Arguments à transmettre à la commande. + - `env` (objet, optionnel) : Variables d’environnement à définir pour le processus du serveur. + - `cwd` (chaîne de caractères, optionnel) : Répertoire de travail dans lequel démarrer le serveur. + - `url` (chaîne de caractères, optionnel) : URL d’un serveur MCP utilisant Server-Sent Events (SSE) pour communiquer. + - `httpUrl` (chaîne de caractères, optionnel) : URL d’un serveur MCP utilisant HTTP streamable pour communiquer. + - `headers` (objet, optionnel) : Cartographie des en-têtes HTTP à envoyer avec les requêtes vers `url` ou `httpUrl`. + - `timeout` (nombre, optionnel) : Délai d’expiration en millisecondes pour les requêtes vers ce serveur MCP. + - `trust` (booléen, optionnel) : Faire confiance à ce serveur et ignorer toutes les confirmations d’appel d’outil. + - `description` (chaîne de caractères, optionnel) : Brève description du serveur, pouvant être utilisée à des fins d’affichage. + - `includeTools` (tableau de chaînes de caractères, optionnel) : Liste des noms d’outils à inclure depuis ce serveur MCP. Lorsque spécifié, seuls les outils listés ici seront disponibles depuis ce serveur (comportement de liste blanche). Sinon, tous les outils du serveur sont activés par défaut. + - `excludeTools` (tableau de chaînes de caractères, optionnel) : Liste des noms d’outils à exclure depuis ce serveur MCP. Les outils listés ici ne seront pas accessibles au modèle, même s’ils sont exposés par le serveur. **Remarque :** `excludeTools` prime sur `includeTools` – si un outil figure dans les deux listes, il sera exclu. - **Exemple :** ```json "mcpServers": { @@ -170,37 +193,37 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro "headers": { "Authorization": "Bearer $MY_SSE_TOKEN" }, - "description": "An example SSE-based MCP server." + "description": "Un exemple de serveur MCP basé sur SSE." }, "myStreamableHttpServer": { "httpUrl": "http://localhost:8082/stream", "headers": { "X-API-Key": "$MY_HTTP_API_KEY" }, - "description": "An example Streamable HTTP-based MCP server." + "description": "Un exemple de serveur MCP basé sur HTTP streamable." } } ``` - **`checkpointing`** (objet) : - - **Description :** Configure la fonctionnalité de checkpointing, qui permet de sauvegarder et restaurer l'état des conversations et des fichiers. Voir la [documentation sur le checkpointing](../checkpointing.md) pour plus de détails. + - **Description :** Configure la fonction de point de sauvegarde, qui vous permet d’enregistrer et de restaurer l’état des conversations et des fichiers. Consultez la [documentation sur les points de sauvegarde](../checkpointing.md) pour plus de détails. - **Par défaut :** `{"enabled": false}` - **Propriétés :** - - **`enabled`** (boolean) : Si `true`, la commande `/restore` est disponible. + - **`enabled`** (booléen) : Lorsque défini sur `true`, la commande `/restore` est disponible. -- **`preferredEditor`** (string) : - - **Description :** Spécifie l'éditeur préféré à utiliser pour afficher les diffs. +- **`preferredEditor`** (chaîne de caractères) : + - **Description :** Spécifie l’éditeur préféré à utiliser pour afficher les différences. - **Par défaut :** `vscode` - **Exemple :** `"preferredEditor": "vscode"` -- **`telemetry`** (objet) : - - **Description :** Configure la collecte de logs et de métriques pour Qwen Code. Pour plus d'informations, voir [Telemetry](../telemetry.md). +- **`telemetry`** (objet) + - **Description :** Configure la journalisation et la collecte de métriques pour Qwen Code. Pour plus d’informations, voir [Télémétrie](../telemetry.md). - **Par défaut :** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **Propriétés :** - - **`enabled`** (boolean) : Active ou désactive la télémétrie. - - **`target`** (string) : Destination des données de télémétrie. Valeurs supportées : `local` et `gcp`. - - **`otlpEndpoint`** (string) : Endpoint pour l'exportateur OTLP. - - **`logPrompts`** (boolean) : Indique si le contenu des prompts utilisateur doit être inclus dans les logs. + - **`enabled`** (booléen) : Indique si la télémétrie est activée ou non. + - **`target`** (chaîne de caractères) : Destination des données de télémétrie collectées. Valeurs prises en charge : `local` et `gcp`. + - **`otlpEndpoint`** (chaîne de caractères) : Point de terminaison de l’exportateur OTLP. + - **`logPrompts`** (booléen) : Indique si le contenu des invites utilisateur doit être inclus dans les journaux. - **Exemple :** ```json "telemetry": { @@ -210,48 +233,27 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro "logPrompts": false } ``` - -- **`usageStatisticsEnabled`** (boolean) : - - **Description :** Active ou désactive la collecte de statistiques d'utilisation. Voir [Usage Statistics](#usage-statistics) pour plus d'informations. +- **`usageStatisticsEnabled`** (booléen) : + - **Description :** Active ou désactive la collecte des statistiques d’utilisation. Voir [Statistiques d’utilisation](#usage-statistics) pour plus d’informations. - **Par défaut :** `true` - **Exemple :** ```json "usageStatisticsEnabled": false ``` -- **`hideTips`** (boolean) : - - **Description :** Active ou désactive les conseils utiles dans l'interface CLI. - - **Par défaut :** `false` - - **Exemple :** - ```json - "hideTips": true - ``` - -- **`hideBanner`** (boolean) : - - **Description :** Active ou désactive la bannière de démarrage (logo ASCII) dans l'interface CLI. +- **`hideTips`** (booléen) : + - **Description :** Active ou désactive les conseils utiles dans l’interface CLI. - **Par défaut :** `false` - **Exemple :** - ```json - "hideBanner": true - ``` -- **`maxSessionTurns`** (number) : - - **Description :** Définit le nombre maximum de tours dans une session. Si la session dépasse cette limite, le CLI arrête le traitement et démarre une nouvelle conversation. - - **Par défaut :** `-1` (illimité) - - **Exemple :** ```json - "maxSessionTurns": 10 + "hideTips": true ``` -- **`summarizeToolOutput`** (objet) : - - **Description :** Active ou désactive le résumé des sorties d'outils. Vous pouvez spécifier le budget de tokens pour le résumé via le paramètre `tokenBudget`. - - Note : Actuellement, seul l'outil `run_shell_command` est supporté. - - **Par défaut :** `{}` (Désactivé par défaut) - - **Exemple :** - ```json - " +- **`hideBanner`** (booléen) : + - **Description :** Active ou désactive la bannière de démarrage (logo -### Exemple `settings.json` : +### Exemple de `settings.json` : ```json { @@ -278,6 +280,8 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro "usageStatisticsEnabled": true, "hideTips": false, "hideBanner": false, + "skipNextSpeakerCheck": false, + "skipLoopDetection": false, "maxSessionTurns": 10, "summarizeToolOutput": { "run_shell_command": { @@ -292,56 +296,56 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro ## Historique du Shell -Le CLI conserve un historique des commandes shell que vous exécutez. Pour éviter les conflits entre différents projets, cet historique est stocké dans un répertoire spécifique au projet, situé dans le dossier home de votre utilisateur. +La CLI conserve un historique des commandes shell que vous exécutez. Pour éviter les conflits entre différents projets, cet historique est stocké dans un répertoire spécifique au projet, situé dans le dossier home de votre utilisateur. - **Emplacement :** `~/.qwen/tmp//shell_history` - `` est un identifiant unique généré à partir du chemin racine de votre projet. - - L'historique est stocké dans un fichier nommé `shell_history`. + - L'historique est enregistré dans un fichier nommé `shell_history`. ## Variables d'environnement et fichiers `.env` Les variables d'environnement sont une méthode courante pour configurer les applications, en particulier pour les informations sensibles comme les clés API ou les paramètres qui peuvent varier selon les environnements. Pour la configuration de l'authentification, consultez la [documentation sur l'authentification](./authentication.md) qui couvre toutes les méthodes disponibles. -Le CLI charge automatiquement les variables d'environnement depuis un fichier `.env`. L'ordre de chargement est le suivant : +Le CLI charge automatiquement les variables d’environnement depuis un fichier `.env`. L’ordre de chargement est le suivant : -1. Le fichier `.env` dans le répertoire de travail courant. -2. S'il n'est pas trouvé, il remonte dans les répertoires parents jusqu'à trouver un fichier `.env` ou atteindre la racine du projet (identifiée par un dossier `.git`) ou le répertoire utilisateur. -3. Si toujours introuvable, il cherche `~/.env` (dans le répertoire utilisateur). +1. Fichier `.env` dans le répertoire courant. +2. Si non trouvé, il remonte dans les répertoires parents jusqu’à trouver un fichier `.env`, ou atteindre la racine du projet (identifiée par un dossier `.git`) ou le répertoire utilisateur. +3. Si toujours introuvable, il cherche `~/.env` (dans le répertoire utilisateur). -**Exclusion de variables d'environnement :** Certaines variables (comme `DEBUG` et `DEBUG_MODE`) sont automatiquement exclues des fichiers `.env` du projet par défaut afin d'éviter toute interférence avec le comportement du CLI. Les variables issues des fichiers `.qwen/.env` ne sont jamais exclues. Vous pouvez personnaliser ce comportement via le paramètre `excludedProjectEnvVars` dans votre fichier `settings.json`. +**Exclusion de variables d’environnement :** Certaines variables (comme `DEBUG` et `DEBUG_MODE`) sont automatiquement exclues des fichiers `.env` du projet afin d’éviter tout conflit avec le comportement du CLI. Les variables issues des fichiers `.qwen/.env` ne sont jamais exclues. Vous pouvez personnaliser ce comportement via le paramètre `excludedProjectEnvVars` dans votre fichier `settings.json`. - **`OPENAI_API_KEY`** : - - Une des [méthodes d'authentification](./authentication.md) disponibles. - - Définissez-la dans votre profil shell (ex. `~/.bashrc`, `~/.zshrc`) ou dans un fichier `.env`. + - Une des nombreuses [méthodes d’authentification](./authentication.md) disponibles. + - Définissez-la dans votre profil shell (par exemple `~/.bashrc`, `~/.zshrc`) ou dans un fichier `.env`. - **`OPENAI_BASE_URL`** : - - Une des [méthodes d'authentification](./authentication.md) disponibles. - - Définissez-la dans votre profil shell (ex. `~/.bashrc`, `~/.zshrc`) ou dans un fichier `.env`. + - Une des nombreuses [méthodes d’authentification](./authentication.md) disponibles. + - Définissez-la dans votre profil shell (par exemple `~/.bashrc`, `~/.zshrc`) ou dans un fichier `.env`. - **`OPENAI_MODEL`** : - - Spécifie le modèle OPENAI par défaut à utiliser. - - Remplace le modèle codé en dur. + - Spécifie le modèle OpenAI à utiliser par défaut. + - Remplace la valeur codée en dur. - Exemple : `export OPENAI_MODEL="qwen3-coder-plus"` - **`GEMINI_SANDBOX`** : - Alternative au paramètre `sandbox` dans `settings.json`. - - Accepte `true`, `false`, `docker`, `podman`, ou une commande personnalisée. + - Accepte `true`, `false`, `docker`, `podman`, ou une commande personnalisée sous forme de chaîne. - **`SEATBELT_PROFILE`** (spécifique à macOS) : - Change le profil Seatbelt (`sandbox-exec`) sur macOS. - `permissive-open` : (Par défaut) Restreint les écritures au dossier du projet (et quelques autres, voir `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) mais autorise les autres opérations. - `strict` : Utilise un profil strict qui refuse les opérations par défaut. - - `` : Utilise un profil personnalisé. Pour définir un profil personnalisé, créez un fichier nommé `sandbox-macos-.sb` dans le répertoire `.qwen/` de votre projet (ex. `my-project/.qwen/sandbox-macos-custom.sb`). + - `` : Utilise un profil personnalisé. Pour définir un tel profil, créez un fichier nommé `sandbox-macos-.sb` dans le répertoire `.qwen/` de votre projet (ex. : `my-project/.qwen/sandbox-macos-custom.sb`). - **`DEBUG` ou `DEBUG_MODE`** (souvent utilisées par les bibliothèques sous-jacentes ou le CLI lui-même) : - - Mettez à `true` ou `1` pour activer les logs verbeux, utiles pour le débogage. - - **Note :** Ces variables sont automatiquement exclues des fichiers `.env` du projet par défaut afin d'éviter toute interférence avec le comportement du CLI. Utilisez les fichiers `.qwen/.env` si vous devez les définir spécifiquement pour Qwen Code. + - Définir à `true` ou `1` active les logs verbeux utiles pour le débogage. + - **Remarque :** Ces variables sont automatiquement exclues des fichiers `.env` du projet afin d’éviter tout conflit avec le comportement du CLI. Utilisez plutôt les fichiers `.qwen/.env` si vous devez spécifiquement activer ces options pour Qwen Code. - **`NO_COLOR`** : - - Définissez n'importe quelle valeur pour désactiver toute sortie colorée dans le CLI. + - Définir n’importe quelle valeur désactive toute sortie colorée dans le CLI. - **`CLI_TITLE`** : - - Définissez une chaîne de caractères pour personnaliser le titre du CLI. + - Permet de personnaliser le titre affiché dans le CLI. - **`CODE_ASSIST_ENDPOINT`** : - - Spécifie l'endpoint du serveur d'assistance au code. - - Utile pour le développement et les tests. + - Indique l’endpoint du serveur d’aide au code. + - Utile principalement lors du développement et des tests. - **`TAVILY_API_KEY`** : - Votre clé API pour le service de recherche web Tavily. - - Requise pour activer la fonctionnalité de l'outil `web_search`. - - Si non configurée, l'outil de recherche web sera désactivé et ignoré. + - Requise pour activer la fonctionnalité de l’outil `web_search`. + - Si elle n’est pas configurée, cet outil sera désactivé et ignoré. - Exemple : `export TAVILY_API_KEY="tvly-your-api-key-here"` ## Arguments de ligne de commande @@ -363,7 +367,7 @@ Les arguments passés directement lors de l'exécution du CLI peuvent remplacer - **`--sandbox-image`** : - Définit l'URI de l'image sandbox. - **`--debug`** (**`-d`**) : - - Active le mode debug pour cette session, fournissant une sortie plus verbeuse. + - Active le mode debug pour cette session, fournissant une sortie plus détaillée. - **`--all-files`** (**`-a`**) : - Si activé, inclut récursivement tous les fichiers du répertoire courant comme contexte pour le prompt. - **`--help`** (ou **`-h`**) : @@ -371,28 +375,32 @@ Les arguments passés directement lors de l'exécution du CLI peuvent remplacer - **`--show-memory-usage`** : - Affiche l'utilisation actuelle de la mémoire. - **`--yolo`** : - - Active le mode YOLO, qui approuve automatiquement tous les appels d'outils. + - Active le mode YOLO, qui approuve automatiquement tous les appels aux outils. - **`--approval-mode `** : - - Définit le mode d'approbation pour les appels d'outils. Modes disponibles : - - `default` : Demande une approbation pour chaque appel d'outil (comportement par défaut) - - `auto_edit` : Approuve automatiquement les outils d'édition (edit, write_file) tout en demandant une approbation pour les autres - - `yolo` : Approuve automatiquement tous les appels d'outils (équivalent à `--yolo`) - - Ne peut pas être utilisé conjointement avec `--yolo`. Utilisez plutôt `--approval-mode=yolo` pour la nouvelle approche unifiée. - - Exemple : `qwen --approval-mode auto_edit` + - Définit le mode d’approbation pour les appels aux outils. Modes pris en charge : + - `plan` : Analyse uniquement — ne modifie pas les fichiers ni n’exécute de commandes. + - `default` : Nécessite une approbation pour les modifications de fichiers ou les commandes shell (comportement par défaut). + - `auto-edit` : Approuve automatiquement les outils d’édition (edit, write_file), tout en demandant une validation pour les autres. + - `yolo` : Approuve automatiquement tous les appels aux outils (équivalent à `--yolo`). + - Ne peut pas être utilisé conjointement avec `--yolo`. Utilisez plutôt `--approval-mode=yolo` pour adopter la nouvelle approche unifiée. + - Exemple : `qwen --approval-mode auto-edit` +- **`--allowed-tools `** : + - Liste séparée par des virgules des noms d’outils qui contourneront la boîte de dialogue de confirmation. + - Exemple : `qwen --allowed-tools "ShellTool(git status)"` - **`--telemetry`** : - Active la [télémétrie](../telemetry.md). - **`--telemetry-target`** : - - Définit la cible de télémétrie. Voir [télémétrie](../telemetry.md) pour plus d'informations. + - Définit la cible de télémétrie. Voir [télémétrie](../telemetry.md) pour plus d’informations. - **`--telemetry-otlp-endpoint`** : - - Définit le endpoint OTLP pour la télémétrie. Voir [télémétrie](../telemetry.md) pour plus d'informations. + - Définit le endpoint OTLP pour la télémétrie. Voir [télémétrie](../telemetry.md) pour plus d’informations. - **`--telemetry-otlp-protocol`** : - - Définit le protocole OTLP pour la télémétrie (`grpc` ou `http`). Par défaut : `grpc`. Voir [télémétrie](../telemetry.md) pour plus d'informations. + - Définit le protocole OTLP pour la télémétrie (`grpc` ou `http`). Par défaut : `grpc`. Voir [télémétrie](../telemetry.md) pour plus d’informations. - **`--telemetry-log-prompts`** : - - Active la journalisation des prompts pour la télémétrie. Voir [télémétrie](../telemetry.md) pour plus d'informations. + - Active la journalisation des prompts pour la télémétrie. Voir [télémétrie](../telemetry.md) pour plus d’informations. - **`--checkpointing`** : - Active le [checkpointing](../checkpointing.md). - **`--extensions `** (**`-e `**) : - - Spécifie une liste d'extensions à utiliser pour la session. Si non fourni, toutes les extensions disponibles sont utilisées. + - Spécifie une liste d’extensions à utiliser pour la session. Si non spécifié, toutes les extensions disponibles sont utilisées. - Utilisez le terme spécial `qwen -e none` pour désactiver toutes les extensions. - Exemple : `qwen -e my-extension -e my-other-extension` - **`--list-extensions`** (**`-l`**) : @@ -401,86 +409,85 @@ Les arguments passés directement lors de l'exécution du CLI peuvent remplacer - Définit le proxy pour le CLI. - Exemple : `--proxy http://localhost:7890`. - **`--include-directories `** : - - Inclut des répertoires supplémentaires dans l'espace de travail pour prendre en charge plusieurs répertoires. + - Inclut des répertoires supplémentaires dans l’espace de travail pour prendre en charge plusieurs répertoires. - Peut être spécifié plusieurs fois ou sous forme de valeurs séparées par des virgules. - - Un maximum de 5 répertoires peut être ajouté. + - Maximum 5 répertoires peuvent être ajoutés. - Exemple : `--include-directories /path/to/project1,/path/to/project2` ou `--include-directories /path/to/project1 --include-directories /path/to/project2` +- **`--screen-reader`** : + - Active le mode lecteur d'écran pour l'accessibilité. - **`--version`** : - Affiche la version du CLI. - **`--openai-logging`** : - - Active la journalisation des appels API OpenAI à des fins de débogage et d'analyse. Cet argument remplace le paramètre `enableOpenAILogging` dans `settings.json`. + - Active la journalisation des appels à l’API OpenAI à des fins de débogage et d’analyse. Ce flag remplace le paramètre `enableOpenAILogging` dans `settings.json`. - **`--tavily-api-key `** : - - Définit la clé API Tavily pour la fonctionnalité de recherche web pour cette session. + - Définit la clé API Tavily pour la fonctionnalité de recherche Web pour cette session. - Exemple : `qwen --tavily-api-key tvly-your-api-key-here` ## Fichiers de contexte (Contexte hiérarchique d'instructions) -Bien qu'ils ne constituent pas strictement une configuration du _comportement_ du CLI, les fichiers de contexte (par défaut `QWEN.md`, mais configurable via le paramètre `contextFileName`) sont essentiels pour configurer le _contexte d'instructions_ (également appelé « mémoire »). Cette fonctionnalité puissante vous permet de fournir des instructions spécifiques au projet, des guides de style de code, ou toute information contextuelle pertinente à l'IA, rendant ainsi ses réponses plus adaptées et précises par rapport à vos besoins. Le CLI inclut des éléments d'interface utilisateur, comme un indicateur dans le pied de page montrant le nombre de fichiers de contexte chargés, afin de vous tenir informé du contexte actif. +Bien qu'ils ne constituent pas strictement une configuration du _comportement_ du CLI, les fichiers de contexte (par défaut `QWEN.md`, mais configurable via le paramètre `contextFileName`) sont essentiels pour configurer le _contexte d'instructions_ (également appelé « mémoire »). Cette fonctionnalité puissante vous permet de fournir des instructions spécifiques au projet, des guides de style de code, ou toute information contextuelle pertinente à l'IA, rendant ainsi ses réponses plus adaptées et précises par rapport à vos besoins. Le CLI inclut des éléments d'interface utilisateur, comme un indicateur dans le pied de page montrant le nombre de fichiers de contexte chargés, afin de vous informer sur le contexte actif. - **Objectif :** Ces fichiers Markdown contiennent des instructions, des directives ou du contexte que vous souhaitez que le modèle Qwen prenne en compte durant vos interactions. Le système est conçu pour gérer ce contexte d'instructions de manière hiérarchique. -### Exemple de contenu d'un fichier contexte (ex. `QWEN.md`) +### Exemple de Contenu d'un Fichier Contexte (ex. `QWEN.md`) -Voici un exemple conceptuel du contenu d'un fichier contexte à la racine d'un projet TypeScript : +Voici un exemple conceptuel du contenu qu'un fichier contexte à la racine d'un projet TypeScript pourrait contenir : ```markdown -# Project: My Awesome TypeScript Library +# Projet : Ma Superbe Librairie TypeScript -## Instructions générales : +## Instructions Générales : - Lors de la génération de nouveau code TypeScript, merci de suivre le style de codage existant. - Assurez-vous que toutes les nouvelles fonctions et classes possèdent des commentaires JSDoc. - Privilégiez les paradigmes de programmation fonctionnelle lorsque cela est approprié. - Tout le code doit être compatible avec TypeScript 5.0 et Node.js 20+. -## Style de codage : +## Style de Codage : - Utilisez 2 espaces pour l'indentation. - Les noms d'interfaces doivent être préfixés par `I` (ex. : `IUserService`). -- Les membres privés des classes doivent être préfixés par un underscore (`_`). +- Les membres privés des classes doivent être préfixés par un tiret bas (`_`). - Utilisez toujours l'égalité stricte (`===` et `!==`). -## Composant spécifique : `src/api/client.ts` +## Composant Spécifique : `src/api/client.ts` - Ce fichier gère toutes les requêtes API sortantes. -- Lors de l'ajout de nouvelles fonctions d'appel API, assurez-vous qu'elles incluent une gestion d'erreur robuste et des logs. +- Lors de l'ajout de nouvelles fonctions d'appel API, assurez-vous qu'elles incluent une gestion d'erreur robuste ainsi qu'un logging adéquat. - Utilisez l'utilitaire `fetchWithRetry` existant pour toutes les requêtes GET. ``` -```markdown ## Concernant les dépendances : - Évitez d'introduire de nouvelles dépendances externes sauf si c'est absolument nécessaire. - Si une nouvelle dépendance est requise, veuillez indiquer la raison. - ``` -Cet exemple montre comment vous pouvez fournir un contexte général sur le projet, des conventions de codage spécifiques, et même des notes sur des fichiers ou composants particuliers. Plus vos fichiers de contexte sont pertinents et précis, mieux l'IA pourra vous assister. Les fichiers de contexte spécifiques au projet sont fortement encouragés afin d'établir des conventions et un contexte clairs. +Cet exemple montre comment vous pouvez fournir un contexte général sur le projet, des conventions de codage spécifiques, ainsi que des notes concernant des fichiers ou composants particuliers. Plus vos fichiers de contexte sont pertinents et précis, mieux l'IA pourra vous assister. Les fichiers de contexte spécifiques au projet sont fortement encouragés afin d'établir des conventions et un contexte clairs. - **Chargement hiérarchique et priorité :** Le CLI implémente un système de mémoire hiérarchique sophistiqué en chargeant les fichiers de contexte (par exemple, `QWEN.md`) depuis plusieurs emplacements. Le contenu des fichiers situés plus bas dans cette liste (plus spécifiques) remplace généralement ou complète celui des fichiers situés plus haut (plus généraux). L'ordre exact de concaténation et le contexte final peuvent être inspectés à l'aide de la commande `/memory show`. L'ordre typique de chargement est le suivant : 1. **Fichier de contexte global :** - Emplacement : `~/.qwen/` (par exemple, `~/.qwen/QWEN.md` dans votre répertoire utilisateur). - Portée : Fournit des instructions par défaut pour tous vos projets. - 2. **Fichiers de contexte à la racine du projet et dans les répertoires parents :** - - Emplacement : Le CLI recherche le fichier de contexte configuré dans le répertoire courant, puis dans chaque répertoire parent jusqu'à la racine du projet (identifiée par un dossier `.git`) ou votre répertoire personnel. + 2. **Fichiers de contexte à la racine du projet et dans ses ancêtres :** + - Emplacement : Le CLI recherche le fichier de contexte configuré dans le répertoire courant, puis dans chaque répertoire parent jusqu'à atteindre la racine du projet (identifiée par un dossier `.git`) ou votre répertoire personnel. - Portée : Fournit un contexte pertinent pour l'ensemble du projet ou une grande partie de celui-ci. 3. **Fichiers de contexte dans les sous-répertoires (contextuels/locaux) :** - - Emplacement : Le CLI scanne également les sous-répertoires _sous_ le répertoire courant (en respectant les motifs d'exclusion courants comme `node_modules`, `.git`, etc.) à la recherche du fichier de contexte configuré. La profondeur de cette recherche est limitée à 200 répertoires par défaut, mais peut être configurée avec le champ `memoryDiscoveryMaxDirs` dans votre fichier `settings.json`. + - Emplacement : Le CLI scanne également les sous-répertoires _sous_ le répertoire courant (en respectant les motifs d'exclusion courants comme `node_modules`, `.git`, etc.) à la recherche du fichier de contexte configuré. La profondeur de cette recherche est limitée à 200 répertoires par défaut, mais peut être configurée via le champ `memoryDiscoveryMaxDirs` dans votre fichier `settings.json`. - Portée : Permet d'ajouter des instructions très spécifiques liées à un composant, module ou section particulière de votre projet. -- **Concaténation & indication dans l'interface :** Le contenu de tous les fichiers de contexte trouvés est concaténé (avec des séparateurs indiquant leur origine et leur chemin) et inclus dans le prompt système. Le pied de page du CLI affiche le nombre de fichiers de contexte chargés, vous donnant un indicateur visuel rapide du contexte instructionnel actif. -- **Importation de contenu :** Vous pouvez modulariser vos fichiers de contexte en important d'autres fichiers Markdown en utilisant la syntaxe `@path/to/file.md`. Pour plus de détails, consultez la [documentation du processeur d'import mémoire](../core/memport.md). +- **Concaténation & indication dans l'interface :** Le contenu de tous les fichiers de contexte trouvés est concaténé (avec des séparateurs indiquant leur origine et leur chemin) et inclus dans le prompt système. Le pied de page du CLI affiche le nombre total de fichiers de contexte chargés, vous donnant ainsi un aperçu rapide du contexte instructionnel actif. +- **Importation de contenu :** Vous pouvez modulariser vos fichiers de contexte en important d'autres fichiers Markdown à l’aide de la syntaxe `@path/to/file.md`. Pour plus de détails, consultez la [documentation du processeur d'import mémoire](../core/memport.md). - **Commandes de gestion de la mémoire :** - Utilisez `/memory refresh` pour forcer un nouveau scan et recharger tous les fichiers de contexte depuis tous les emplacements configurés. Cela met à jour le contexte instructionnel de l'IA. - Utilisez `/memory show` pour afficher le contexte instructionnel combiné actuellement chargé, afin de vérifier la hiérarchie et le contenu utilisé par l'IA. - - Consultez la [documentation des commandes](./commands.md#memory) pour tous les détails concernant la commande `/memory` et ses sous-commandes (`show` et `refresh`). + - Consultez la [documentation des commandes](./commands.md#memory) pour obtenir tous les détails sur la commande `/memory` et ses sous-commandes (`show` et `refresh`). En comprenant et en utilisant ces couches de configuration ainsi que la nature hiérarchique des fichiers de contexte, vous pouvez efficacement gérer la mémoire de l'IA et adapter les réponses de Qwen Code à vos besoins et projets spécifiques. -``` ## Sandboxing -Qwen Code peut exécuter des opérations potentiellement non sécurisées (comme des commandes shell et des modifications de fichiers) dans un environnement sandboxé pour protéger votre système. +Qwen Code peut exécuter des opérations potentiellement non sûres (comme des commandes shell et des modifications de fichiers) dans un environnement sandboxé pour protéger votre système. Le sandboxing est désactivé par défaut, mais vous pouvez l'activer de plusieurs façons : @@ -490,7 +497,7 @@ Le sandboxing est désactivé par défaut, mais vous pouvez l'activer de plusieu Par défaut, il utilise une image Docker pré-construite `qwen-code-sandbox`. -Pour des besoins de sandboxing spécifiques à un projet, vous pouvez créer un Dockerfile personnalisé à l'emplacement `.qwen/sandbox.Dockerfile` à la racine de votre projet. Ce Dockerfile peut être basé sur l'image de base du sandbox : +Pour des besoins de sandboxing spécifiques à un projet, vous pouvez créer un Dockerfile personnalisé à l'emplacement `.qwen/sandbox.Dockerfile` dans le répertoire racine de votre projet. Ce Dockerfile peut être basé sur l'image de base du sandbox : ```dockerfile FROM qwen-code-sandbox @@ -523,7 +530,7 @@ Pour nous aider à améliorer Qwen Code, nous collectons des statistiques d'util **Ce que nous ne collectons PAS :** -- **Informations personnelles identifiables (PII) :** Nous ne collectons aucune information personnelle, comme votre nom, adresse email ou clés API. +- **Informations personnelles identifiables (PII) :** Nous ne collectons aucune information personnelle, comme votre nom, adresse e-mail ou clés API. - **Contenu des prompts et réponses :** Nous n'enregistrons pas le contenu de vos prompts ou des réponses du modèle. - **Contenu des fichiers :** Nous n'enregistrons pas le contenu des fichiers lus ou écrits par le CLI. @@ -537,12 +544,12 @@ Vous pouvez désactiver la collecte des statistiques d'utilisation à tout momen } ``` -Note : Lorsque les statistiques d'utilisation sont activées, les événements sont envoyés à un endpoint de collecte RUM d'Alibaba Cloud. +Remarque : Lorsque les statistiques d'utilisation sont activées, les événements sont envoyés à un endpoint de collecte Alibaba Cloud RUM. - **`enableWelcomeBack`** (boolean) : - - **Description :** Affiche une boîte de dialogue de bienvenue lors du retour sur un projet avec un historique de conversation. + - **Description :** Affiche une boîte de dialogue de bienvenue lors du retour à un projet avec un historique de conversation. - **Par défaut :** `true` - **Catégorie :** UI - **Redémarrage requis :** Non - **Exemple :** `"enableWelcomeBack": false` - - **Détails :** Lorsque cette option est activée, Qwen Code détecte automatiquement si vous revenez sur un projet avec un résumé de projet généré précédemment (`.qwen/PROJECT_SUMMARY.md`) et affiche une boîte de dialogue vous permettant de continuer votre conversation précédente ou d'en commencer une nouvelle. Cette fonctionnalité s'intègre avec la commande `/chat summary` et la boîte de dialogue de confirmation de fermeture. Consultez la [documentation Welcome Back](./welcome-back.md) pour plus de détails. \ No newline at end of file + - **Détails :** Lorsque cette option est activée, Qwen Code détecte automatiquement si vous revenez à un projet avec un résumé de projet précédemment généré (`.qwen/PROJECT_SUMMARY.md`) et affiche une boîte de dialogue vous permettant de continuer votre conversation précédente ou d'en commencer une nouvelle. Cette fonctionnalité s'intègre avec la commande `/chat summary` et la boîte de dialogue de confirmation de fermeture. Consultez la [documentation Welcome Back](./welcome-back.md) pour plus de détails. \ No newline at end of file diff --git a/website/content/fr/cli/themes.md b/website/content/fr/cli/themes.md index c8361f50..0224562d 100644 --- a/website/content/fr/cli/themes.md +++ b/website/content/fr/cli/themes.md @@ -23,20 +23,22 @@ Qwen Code est livré avec une sélection de thèmes prédéfinis, que vous pouve ### Changer de thème -1. Saisissez `/theme` dans Qwen Code. -2. Une boîte de dialogue ou un prompt de sélection apparaît, listant les thèmes disponibles. -3. Utilisez les touches fléchées pour sélectionner un thème. Certaines interfaces peuvent offrir un aperçu en direct ou un surlignage pendant la sélection. -4. Confirmez votre choix pour appliquer le thème. +1. Saisissez `/theme` dans Qwen Code. +2. Une boîte de dialogue ou une invite de sélection s'affiche, listant les thèmes disponibles. +3. Utilisez les touches fléchées pour sélectionner un thème. Certaines interfaces peuvent offrir un aperçu en direct ou un surlignage lors de la sélection. +4. Confirmez votre sélection pour appliquer le thème. + +**Remarque :** Si un thème est défini dans votre fichier `settings.json` (soit par nom, soit par chemin de fichier), vous devez supprimer le paramètre `"theme"` du fichier avant de pouvoir changer de thème via la commande `/theme`. ### Persistance des thèmes -Les thèmes sélectionnés sont enregistrés dans la [configuration](./configuration.md) de Qwen Code afin que vos préférences soient conservées d'une session à l'autre. +Les thèmes sélectionnés sont enregistrés dans la [configuration](./configuration.md) de Qwen Code, afin que vos préférences soient conservées d'une session à l'autre. --- -## Thèmes de couleurs personnalisés +## Thèmes de couleur personnalisés -Qwen Code vous permet de créer vos propres thèmes de couleurs personnalisés en les spécifiant dans votre fichier `settings.json`. Cela vous donne un contrôle total sur la palette de couleurs utilisée dans le CLI. +Qwen Code vous permet de créer vos propres thèmes de couleur personnalisés en les spécifiant dans votre fichier `settings.json`. Cela vous donne un contrôle total sur la palette de couleurs utilisée dans l'interface CLI. ### Comment définir un thème personnalisé @@ -101,10 +103,50 @@ Ajoutez un bloc `customThemes` à votre fichier `settings.json` utilisateur, pro - `Comment` - `Gray` -Vous pouvez utiliser soit des codes hexadécimaux (ex. `#FF0000`) **ou** des noms de couleurs CSS standards (ex. `coral`, `teal`, `blue`) pour toute valeur de couleur. Consultez [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords) pour une liste complète des noms supportés. +Vous pouvez utiliser soit des codes hexadécimaux (ex. `#FF0000`), **soit** des noms de couleurs CSS standards (ex. `coral`, `teal`, `blue`) pour toute valeur de couleur. Consultez [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords) pour obtenir la liste complète des noms supportés. Vous pouvez définir plusieurs thèmes personnalisés en ajoutant davantage d'entrées à l'objet `customThemes`. +### Chargement des thèmes depuis un fichier + +En plus de définir des thèmes personnalisés dans `settings.json`, vous pouvez également charger un thème directement depuis un fichier JSON en spécifiant le chemin du fichier dans votre `settings.json`. Cela est utile pour partager des thèmes ou les conserver séparément de votre configuration principale. + +Pour charger un thème depuis un fichier, définissez la propriété `theme` dans votre `settings.json` avec le chemin vers votre fichier de thème : + +```json +{ + "theme": "/path/to/your/theme.json" +} +``` + +Le fichier de thème doit être un fichier JSON valide qui suit la même structure qu'un thème personnalisé défini dans `settings.json`. + +**Exemple `my-theme.json` :** + +```json +{ + "name": "My File Theme", + "type": "custom", + "Background": "#282A36", + "Foreground": "#F8F8F2", + "LightBlue": "#82AAFF", + "AccentBlue": "#61AFEF", + "AccentPurple": "#BD93F9", + "AccentCyan": "#8BE9FD", + "AccentGreen": "#50FA7B", + "AccentYellow": "#F1FA8C", + "AccentRed": "#FF5555", + "Comment": "#6272A4", + "Gray": "#ABB2BF", + "DiffAdded": "#A6E3A1", + "DiffRemoved": "#F38BA8", + "DiffModified": "#89B4FA", + "GradientColors": ["#4796E4", "#847ACE", "#C3677F"] +} +``` + +**Note de sécurité :** Pour votre sécurité, Gemini CLI ne chargera que les fichiers de thème situés dans votre répertoire personnel (home directory). Si vous tentez de charger un thème depuis un emplacement en dehors de votre répertoire personnel, un avertissement sera affiché et le thème ne sera pas chargé. Cette mesure vise à empêcher le chargement de fichiers de thème potentiellement malveillants provenant de sources non fiables. + ### Exemple de thème personnalisé Exemple de thème personnalisé diff --git a/website/content/fr/deployment.md b/website/content/fr/deployment.md index ce9dcc3d..4155618b 100644 --- a/website/content/fr/deployment.md +++ b/website/content/fr/deployment.md @@ -4,13 +4,13 @@ Ce document explique comment exécuter Qwen Code et décrit l'architecture de d ## Exécuter Qwen Code -Il existe plusieurs façons d'exécuter Qwen Code. L'option que vous choisissez dépend de votre utilisation prévue. +Il existe plusieurs façons d'exécuter Qwen Code. L'option que vous choisissez dépend de la manière dont vous comptez l'utiliser. --- ### 1. Installation standard (Recommandée pour les utilisateurs classiques) -C'est la méthode recommandée pour que les utilisateurs finaux installent Qwen Code. Elle consiste à télécharger le package Qwen Code depuis le registre NPM. +Cette méthode est recommandée pour les utilisateurs finaux souhaitant installer Qwen Code. Elle consiste à télécharger le package Qwen Code depuis le registre NPM. - **Installation globale :** @@ -18,7 +18,7 @@ C'est la méthode recommandée pour que les utilisateurs finaux installent Qwen npm install -g @qwen-code/qwen-code ``` - Ensuite, exécutez le CLI depuis n'importe où : + Ensuite, exécutez le CLI depuis n'importe quel endroit : ```bash qwen @@ -35,17 +35,17 @@ C'est la méthode recommandée pour que les utilisateurs finaux installent Qwen ### 2. Exécution dans un sandbox (Docker/Podman) -Pour des raisons de sécurité et d'isolation, Qwen Code peut être exécuté à l'intérieur d'un container. C'est d'ailleurs la méthode par défaut utilisée par le CLI pour exécuter les outils qui pourraient avoir des effets de bord. +Pour des raisons de sécurité et d'isolation, Qwen Code peut être exécuté à l'intérieur d'un container. C'est d'ailleurs la méthode par défaut utilisée par le CLI pour exécuter les outils qui pourraient avoir des effets secondaires. - **Directement depuis le Registry :** - Vous pouvez exécuter l'image du sandbox directement depuis le registry. C'est pratique dans les environnements où vous n'avez que Docker d'installé et que vous souhaitez lancer le CLI. + Vous pouvez exécuter directement l'image du sandbox publiée. C'est pratique pour les environnements où vous n'avez que Docker et souhaitez exécuter le CLI. ```bash # Exécuter l'image du sandbox publiée - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.11 ``` - **Utilisation du flag `--sandbox` :** - Si Qwen Code est installé localement (via l'installation standard décrite plus haut), vous pouvez lui demander de s'exécuter à l'intérieur du container sandbox. + Si Qwen Code est installé localement (via l'installation standard décrite ci-dessus), vous pouvez lui demander de s'exécuter à l'intérieur du container sandbox. ```bash qwen --sandbox -y -p "your prompt here" ``` @@ -63,7 +63,7 @@ Les contributeurs du projet voudront exécuter le CLI directement depuis le code npm run start ``` - **Mode production (package lié) :** - Cette méthode simule une installation globale en liant votre package local. Elle est utile pour tester un build local dans un workflow de production. + Cette méthode simule une installation globale en liant votre package local. Elle est utile pour tester une version locale dans un workflow de production. ```bash # Lier le package cli local à vos node_modules globaux diff --git a/website/content/fr/examples/proxy-script.md b/website/content/fr/examples/proxy-script.md index 6485bd95..7059fea0 100644 --- a/website/content/fr/examples/proxy-script.md +++ b/website/content/fr/examples/proxy-script.md @@ -15,10 +15,10 @@ Voici un exemple de script proxy qui peut être utilisé avec la variable d'envi // Définir `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js` pour exécuter le proxy en parallèle du sandbox // Tester via `curl https://example.com` à l'intérieur du sandbox (en mode shell ou via l'outil shell) -import http from 'http'; -import net from 'net'; -import { URL } from 'url'; -import console from 'console'; +import http from 'node:http'; +import net from 'node:net'; +import { URL } from 'node:url'; +import console from 'node:console'; const PROXY_PORT = 8877; const ALLOWED_DOMAINS = ['example.com', 'googleapis.com']; @@ -67,7 +67,7 @@ server.on('connect', (req, clientSocket, head) => { clientSocket.on('error', (err) => { // Cela peut arriver si le client raccroche. - console.error(`[PROXY] Erreur socket client : ${err.message}`); + console.error(`[PROXY] Erreur socket cliente : ${err.message}`); }); }); diff --git a/website/content/fr/extension.md b/website/content/fr/extension.md index 45aeaa41..8d87dbd0 100644 --- a/website/content/fr/extension.md +++ b/website/content/fr/extension.md @@ -9,7 +9,7 @@ Au démarrage, Qwen Code recherche les extensions dans deux emplacements : 1. `/.qwen/extensions` 2. `/.qwen/extensions` -Qwen Code charge toutes les extensions depuis ces deux emplacements. Si une extension portant le même nom existe dans les deux emplacements, l'extension du répertoire workspace prend le pas. +Qwen Code charge toutes les extensions depuis ces deux emplacements. Si une extension portant le même nom existe dans les deux emplacements, l'extension du répertoire workspace prend le dessus. Dans chaque emplacement, les extensions individuelles existent sous forme de répertoire contenant un fichier `qwen-extension.json`. Par exemple : @@ -35,11 +35,11 @@ Le fichier `qwen-extension.json` contient la configuration de l'extension. Le fi - `name` : Le nom de l'extension. Il est utilisé pour identifier de manière unique l'extension et pour résoudre les conflits lorsque les commandes de l'extension portent le même nom que les commandes utilisateur ou projet. - `version` : La version de l'extension. -- `mcpServers` : Une map des serveurs MCP à configurer. La clé est le nom du serveur, et la valeur est la configuration du serveur. Ces serveurs seront chargés au démarrage, tout comme les serveurs MCP configurés dans un fichier [`settings.json`](./cli/configuration.md). Si à la fois une extension et un fichier `settings.json` configurent un serveur MCP avec le même nom, le serveur défini dans le fichier `settings.json` prend le pas. -- `contextFileName` : Le nom du fichier contenant le contexte de l'extension. Ce fichier sera utilisé pour charger le contexte depuis l'espace de travail. Si cette propriété n'est pas utilisée mais qu'un fichier `QWEN.md` est présent dans le répertoire de votre extension, alors ce fichier sera chargé. -- `excludeTools` : Un tableau contenant les noms des outils à exclure du modèle. Vous pouvez également spécifier des restrictions spécifiques à certaines commandes pour les outils qui le permettent, comme l'outil `run_shell_command`. Par exemple, `"excludeTools": ["run_shell_command(rm -rf)"]` bloquera la commande `rm -rf`. +- `mcpServers` : Une map des serveurs MCP à configurer. La clé est le nom du serveur, et la valeur est la configuration du serveur. Ces serveurs seront chargés au démarrage, tout comme les serveurs MCP configurés dans un fichier [`settings.json`](./cli/configuration.md). Si à la fois une extension et un fichier `settings.json` configurent un serveur MCP avec le même nom, le serveur défini dans le fichier `settings.json` prend la priorité. +- `contextFileName` : Le nom du fichier contenant le contexte de l'extension. Il sera utilisé pour charger le contexte depuis l'espace de travail. Si cette propriété n'est pas utilisée mais qu'un fichier `QWEN.md` est présent dans le répertoire de votre extension, alors ce fichier sera chargé. +- `excludeTools` : Un tableau de noms d'outils à exclure du modèle. Vous pouvez également spécifier des restrictions spécifiques aux commandes pour les outils qui le permettent, comme l'outil `run_shell_command`. Par exemple, `"excludeTools": ["run_shell_command(rm -rf)"]` bloquera la commande `rm -rf`. -Lorsque Qwen Code démarre, il charge toutes les extensions et fusionne leurs configurations. En cas de conflit, la configuration de l'espace de travail est prioritaire. +Lorsque Qwen Code démarre, il charge toutes les extensions et fusionne leurs configurations. En cas de conflit, la configuration de l'espace de travail prend la priorité. ## Commandes d'extension @@ -73,4 +73,28 @@ Les commandes d'extension ont la priorité la plus faible. Lorsqu'un conflit sur Par exemple, si à la fois un utilisateur et l'extension `gcp` définissent une commande `deploy` : - `/deploy` - Exécute la commande deploy de l'utilisateur -- `/gcp.deploy` - Exécute la commande deploy de l'extension (marquée avec le tag `[gcp]`) \ No newline at end of file +- `/gcp.deploy` - Exécute la commande deploy de l'extension (marquée avec le tag `[gcp]`) + +## Installation des extensions + +Vous pouvez installer des extensions en utilisant la commande `install`. Cette commande vous permet d'installer des extensions depuis un dépôt Git ou un chemin local. + +### Utilisation + +`qwen extensions install | [options]` + +### Options + +- `source positional argument` : L'URL d'un repository Git à partir duquel installer l'extension. Le repository doit contenir un fichier `qwen-extension.json` à sa racine. +- `--path ` : Le chemin vers un répertoire local à installer comme extension. Le répertoire doit contenir un fichier `qwen-extension.json`. + +# Variables + +Les extensions Qwen Code permettent la substitution de variables dans le fichier `qwen-extension.json`. Cela peut être utile si, par exemple, vous avez besoin du répertoire courant pour exécuter un serveur MCP en utilisant `"cwd": "${extensionPath}${/}run.ts"`. + +**Variables supportées :** + +| variable | description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `${extensionPath}` | Le chemin complet de l'extension dans le système de fichiers de l'utilisateur, par exemple : '/Users/username/.qwen/extensions/example-extension'. Les liens symboliques ne sont pas résolus. | +| `${/} or ${pathSeparator}` | Le séparateur de chemin (varie selon l'OS). | \ No newline at end of file diff --git a/website/content/fr/gemini-ignore.md b/website/content/fr/gemini-ignore.md index 62f05774..eb7e9090 100644 --- a/website/content/fr/gemini-ignore.md +++ b/website/content/fr/gemini-ignore.md @@ -2,19 +2,19 @@ Ce document fournit un aperçu de la fonctionnalité Gemini Ignore (`.geminiignore`) de Qwen Code. -Qwen Code inclut la capacité d'ignorer automatiquement des fichiers, de manière similaire à `.gitignore` (utilisé par Git) et `.aiexclude` (utilisé par Gemini Code Assist). Ajouter des chemins à votre fichier `.geminiignore` les exclura des outils qui supportent cette fonctionnalité, bien qu'ils resteront visibles pour les autres services (comme Git). +Qwen Code inclut la possibilité d'ignorer automatiquement des fichiers, de manière similaire à `.gitignore` (utilisé par Git) et `.aiexclude` (utilisé par Gemini Code Assist). Ajouter des chemins à votre fichier `.geminiignore` les exclura des outils qui prennent en charge cette fonctionnalité, bien qu'ils resteront visibles pour d'autres services (comme Git). ## Fonctionnement -Lorsque vous ajoutez un chemin à votre fichier `.geminiignore`, les outils qui respectent ce fichier excluront automatiquement les fichiers et dossiers correspondants de leurs opérations. Par exemple, lorsque vous utilisez la commande [`read_many_files`](./tools/multi-file.md), tous les chemins présents dans votre fichier `.geminiignore` seront automatiquement ignorés. +Lorsque vous ajoutez un chemin à votre fichier `.geminiignore`, les outils qui respectent ce fichier excluront automatiquement les fichiers et répertoires correspondants de leurs opérations. Par exemple, lorsque vous utilisez la commande [`read_many_files`](./tools/multi-file.md), tous les chemins présents dans votre fichier `.geminiignore` seront automatiquement exclus. Dans l'ensemble, `.geminiignore` suit les conventions des fichiers `.gitignore` : - Les lignes vides et les lignes commençant par `#` sont ignorées. - Les motifs glob standards sont pris en charge (comme `*`, `?`, et `[]`). -- Ajouter un `/` à la fin ne correspondra qu'aux dossiers. +- Ajouter un `/` à la fin ne correspondra qu'aux répertoires. - Placer un `/` au début ancre le chemin par rapport au fichier `.geminiignore`. -- Le symbole `!` permet d'inverser (négation) un motif. +- `!` inverse un motif (négation). Vous pouvez modifier votre fichier `.geminiignore` à tout moment. Pour appliquer les changements, vous devez redémarrer votre session Qwen Code. diff --git a/website/content/fr/ide-integration.md b/website/content/fr/ide-integration.md index 1ca4df36..8220e717 100644 --- a/website/content/fr/ide-integration.md +++ b/website/content/fr/ide-integration.md @@ -2,22 +2,22 @@ Qwen Code peut s'intégrer à votre IDE pour offrir une expérience plus fluide et contextuelle. Cette intégration permet au CLI de mieux comprendre votre espace de travail et active des fonctionnalités puissantes comme le diffing natif directement dans l'éditeur. -Actuellement, le seul IDE supporté est [Visual Studio Code](https://code.visualstudio.com/) ainsi que les autres éditeurs compatibles avec les extensions VS Code. +Actuellement, le seul IDE supporté est [Visual Studio Code](https://code.visualstudio.com/) ainsi que les autres éditeurs qui prennent en charge les extensions VS Code. ## Fonctionnalités - **Contexte de l'espace de travail :** Le CLI prend automatiquement connaissance de votre espace de travail pour fournir des réponses plus pertinentes et précises. Ce contexte inclut : - Les **10 fichiers les plus récemment consultés** dans votre espace de travail. - - La position actuelle de votre curseur. + - La position active de votre curseur. - Tout texte sélectionné (jusqu'à une limite de 16 Ko ; les sélections plus longues seront tronquées). -- **Diffing natif :** Lorsque Qwen propose des modifications de code, vous pouvez visualiser les changements directement dans le visualiseur de différences natif de votre IDE. Cela vous permet de revoir, modifier, accepter ou rejeter facilement les modifications suggérées. +- **Diffing natif :** Lorsque Qwen propose des modifications de code, vous pouvez visualiser les changements directement dans le visualiseur de différences natif de votre IDE. Cela vous permet de revoir, modifier, accepter ou rejeter les changements suggérés de manière transparente. - **Commandes VS Code :** Vous pouvez accéder aux fonctionnalités de Qwen Code directement depuis la Palette de commandes de VS Code (`Cmd+Shift+P` ou `Ctrl+Shift+P`) : - `Qwen Code: Run` : Démarre une nouvelle session Qwen Code dans le terminal intégré. - `Qwen Code: Accept Diff` : Accepte les modifications dans l'éditeur de différences actif. - `Qwen Code: Close Diff Editor` : Rejette les modifications et ferme l'éditeur de différences actif. - - `Qwen Code: View Third-Party Notices` : Affiche les mentions relatives aux logiciels tiers utilisés par l'extension. + - `Qwen Code: View Third-Party Notices` : Affiche les mentions tierces pour l'extension. ## Installation et Configuration @@ -25,9 +25,9 @@ Il existe trois façons de configurer l'intégration IDE : ### 1. Invitation Automatique (Recommandé) -Lorsque vous exécutez Qwen Code dans un éditeur pris en charge, il détectera automatiquement votre environnement et vous invitera à vous connecter. Répondre par "Yes" lancera automatiquement la configuration nécessaire, qui inclut l'installation de l'extension companion et l'activation de la connexion. +Lorsque vous exécutez Qwen Code dans un éditeur pris en charge, il détectera automatiquement votre environnement et vous invitera à vous connecter. Répondre par "Yes" exécutera automatiquement la configuration nécessaire, ce qui inclut l'installation de l'extension compagnon et l'activation de la connexion. -### 2. Installation Manuelle depuis le CLI +### 2. Installation Manuelle via CLI Si vous avez précédemment ignoré l'invite ou si vous souhaitez installer l'extension manuellement, vous pouvez exécuter la commande suivante dans Qwen Code : @@ -44,7 +44,10 @@ Vous pouvez également installer l'extension directement depuis un marketplace. - **Pour Visual Studio Code :** Installez depuis le [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion). - **Pour les forks de VS Code :** Pour supporter les forks de VS Code, l'extension est également publiée sur le [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion). Suivez les instructions de votre éditeur pour installer des extensions depuis ce registre. -Après n'importe quelle méthode d'installation, il est recommandé d'ouvrir une nouvelle fenêtre de terminal pour vous assurer que l'intégration est activée correctement. Une fois installée, vous pouvez utiliser `/ide enable` pour vous connecter. +> NOTE : +> L'extension "Qwen Code Companion" peut apparaître vers le bas des résultats de recherche. Si vous ne la voyez pas immédiatement, essayez de faire défiler vers le bas ou de trier par "Newly Published". +> +> Après avoir installé manuellement l'extension, vous devez exécuter `/ide enable` dans le CLI pour activer l'intégration. ## Usage @@ -73,36 +76,36 @@ Pour vérifier l'état de la connexion et voir le contexte que le CLI a reçu de Si la connexion est établie, cette commande affichera l'IDE auquel il est connecté ainsi qu'une liste des fichiers récemment ouverts dont il a connaissance. -(Note : La liste des fichiers est limitée aux 10 fichiers récents accédés dans votre espace de travail et inclut uniquement les fichiers locaux présents sur le disque.) +(Remarque : La liste des fichiers est limitée aux 10 fichiers récents accessibles dans votre espace de travail et inclut uniquement les fichiers locaux présents sur le disque.) ### Travailler avec les diffs -Quand vous demandez à Gemini de modifier un fichier, il peut ouvrir directement une vue de diff dans votre éditeur. +Quand vous demandez au modèle Qwen de modifier un fichier, il peut ouvrir directement une vue diff dans votre éditeur. **Pour accepter un diff**, vous pouvez effectuer l'une des actions suivantes : -- Cliquer sur l'**icône de validation (✓)** dans la barre de titre de l'éditeur de diff. +- Cliquer sur l'**icône en forme de coche** dans la barre de titre de l'éditeur diff. - Sauvegarder le fichier (par exemple avec `Cmd+S` ou `Ctrl+S`). - Ouvrir la Command Palette et exécuter **Qwen Code: Accept Diff**. - Répondre par `yes` dans le CLI quand vous y êtes invité. **Pour rejeter un diff**, vous pouvez : -- Cliquer sur l'**icône 'x'** dans la barre de titre de l'éditeur de diff. -- Fermer l'onglet de l'éditeur de diff. +- Cliquer sur l'**icône 'x'** dans la barre de titre de l'éditeur diff. +- Fermer l'onglet de l'éditeur diff. - Ouvrir la Command Palette et exécuter **Qwen Code: Close Diff Editor**. - Répondre par `no` dans le CLI quand vous y êtes invité. -Vous pouvez également **modifier les changements suggérés** directement dans la vue de diff avant de les accepter. +Vous pouvez également **modifier les changements suggérés** directement dans la vue diff avant de les accepter. -Si vous sélectionnez ‘Yes, allow always’ dans le CLI, les modifications n’apparaîtront plus dans l'IDE car elles seront automatiquement acceptées. +Si vous sélectionnez ‘Yes, allow always’ dans le CLI, les modifications n'apparaîtront plus dans l'IDE car elles seront automatiquement acceptées. ## Utilisation avec le Sandboxing Si vous utilisez Qwen Code dans un environnement sandbox, veuillez prendre en compte les points suivants : -- **Sur macOS :** L'intégration avec l'IDE nécessite un accès réseau pour communiquer avec l'extension compagnon de l'IDE. Vous devez utiliser un profil Seatbelt qui autorise l'accès réseau. -- **Dans un conteneur Docker :** Si vous exécutez Qwen Code à l'intérieur d'un conteneur Docker (ou Podman), l'intégration avec l'IDE peut toujours se connecter à l'extension VS Code qui s'exécute sur votre machine hôte. La CLI est configurée pour trouver automatiquement le serveur IDE sur `host.docker.internal`. Aucune configuration spéciale n'est généralement requise, mais vous devrez peut-être vérifier que votre configuration réseau Docker autorise les connexions depuis le conteneur vers l'hôte. +- **Sur macOS :** L'intégration IDE nécessite un accès réseau pour communiquer avec l'extension compagnon de l'IDE. Vous devez utiliser un profil Seatbelt qui autorise l'accès réseau. +- **Dans un conteneur Docker :** Si vous exécutez Qwen Code à l'intérieur d'un conteneur Docker (ou Podman), l'intégration IDE peut toujours se connecter à l'extension VS Code qui s'exécute sur votre machine hôte. La CLI est configurée pour trouver automatiquement le serveur IDE sur `host.docker.internal`. Aucune configuration spéciale n'est généralement requise, mais vous devrez peut-être vérifier que votre configuration réseau Docker autorise les connexions depuis le conteneur vers l'hôte. ## Dépannage @@ -111,31 +114,31 @@ Si vous rencontrez des problèmes avec l'intégration IDE, voici quelques messag ### Erreurs de connexion - **Message :** `🔴 Disconnected: Failed to connect to IDE companion extension for [IDE Name]. Please ensure the extension is running and try restarting your terminal. To install the extension, run /ide install.` - - **Cause :** Qwen Code n’a pas pu trouver les variables d’environnement nécessaires (`QWEN_CODE_IDE_WORKSPACE_PATH` ou `QWEN_CODE_IDE_SERVER_PORT`) pour se connecter à l’IDE. Cela signifie généralement que l’extension companion de l’IDE n’est pas en cours d’exécution ou qu’elle n’a pas été initialisée correctement. + - **Cause :** Qwen Code n'a pas pu trouver les variables d'environnement nécessaires (`QWEN_CODE_IDE_WORKSPACE_PATH` ou `QWEN_CODE_IDE_SERVER_PORT`) pour se connecter à l'IDE. Cela signifie généralement que l'extension compagnon de l'IDE n'est pas en cours d'exécution ou qu'elle n'a pas été initialisée correctement. - **Solution :** - 1. Assurez-vous d’avoir installé l’extension **Qwen Code Companion** dans votre IDE et qu’elle est activée. - 2. Ouvrez une nouvelle fenêtre de terminal dans votre IDE pour vous assurer qu’elle récupère le bon environnement. + 1. Assurez-vous d'avoir installé l'extension **Qwen Code Companion** dans votre IDE et qu'elle est activée. + 2. Ouvrez une nouvelle fenêtre de terminal dans votre IDE afin de vous assurer qu'il récupère le bon environnement. - **Message :** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` - - **Cause :** La connexion à l’extension companion de l’IDE a été perdue. + - **Cause :** La connexion avec l'extension compagnon de l'IDE a été perdue. - **Solution :** Exécutez `/ide enable` pour tenter de vous reconnecter. Si le problème persiste, ouvrez une nouvelle fenêtre de terminal ou redémarrez votre IDE. ### Erreurs de configuration - **Message :** `🔴 Disconnected: Directory mismatch. Qwen Code is running in a different location than the open workspace in [IDE Name]. Please run the CLI from the same directory as your project's root folder.` - - **Cause :** Le répertoire de travail actuel de la CLI se trouve en dehors du dossier ou de l'espace de travail que vous avez ouvert dans votre IDE. - - **Solution :** Utilisez `cd` pour accéder au même répertoire que celui ouvert dans votre IDE, puis redémarrez la CLI. + - **Cause :** Le répertoire de travail actuel de la CLI est en dehors du dossier ou de l'espace de travail que vous avez ouvert dans votre IDE. + - **Solution :** Exécutez `cd` pour accéder au même répertoire que celui ouvert dans votre IDE, puis redémarrez la CLI. -- **Message :** `🔴 Disconnected: To use this feature, please open a single workspace folder in [IDE Name] and try again.` - - **Cause :** Vous avez plusieurs dossiers d'espace de travail ouverts dans votre IDE, ou aucun dossier n'est ouvert. L'intégration avec l'IDE nécessite un seul dossier racine d'espace de travail pour fonctionner correctement. - - **Solution :** Ouvrez un seul dossier de projet dans votre IDE et redémarrez la CLI. +- **Message :** `🔴 Disconnected: To use this feature, please open a workspace folder in [IDE Name] and try again.` + - **Cause :** Vous n'avez aucun espace de travail ouvert dans votre IDE. + - **Solution :** Ouvrez un espace de travail dans votre IDE et redémarrez la CLI. ### Erreurs générales -- **Message :** `L'intégration IDE n'est pas prise en charge dans votre environnement actuel. Pour utiliser cette fonctionnalité, exécutez Qwen Code dans l'un de ces IDE pris en charge : [Liste des IDE]` +- **Message :** `IDE integration is not supported in your current environment. To use this feature, run Qwen Code in one of these supported IDEs: [List of IDEs]` - **Cause :** Vous exécutez Qwen Code dans un terminal ou un environnement qui n'est pas un IDE pris en charge. - **Solution :** Exécutez Qwen Code depuis le terminal intégré d'un IDE pris en charge, comme VS Code. -- **Message :** `Aucun installateur n'est disponible pour [Nom de l'IDE]. Veuillez installer l'extension IDE manuellement depuis son marketplace.` - - **Cause :** Vous avez exécuté `/ide install`, mais le CLI ne dispose pas d'un installateur automatisé pour votre IDE spécifique. - - **Solution :** Ouvrez le marketplace d'extensions de votre IDE, recherchez "Qwen Code Companion", et installez-le manuellement. \ No newline at end of file +- **Message :** `No installer is available for IDE. Please install the Qwen Code Companion extension manually from the marketplace.` + - **Cause :** Vous avez exécuté `/ide install`, mais la CLI ne dispose pas d'un installateur automatique pour votre IDE spécifique. + - **Solution :** Ouvrez le marketplace des extensions de votre IDE, recherchez "Qwen Code Companion", et installez-le manuellement. \ No newline at end of file diff --git a/website/content/fr/index.md b/website/content/fr/index.md index c85e0f4b..1e129c32 100644 --- a/website/content/fr/index.md +++ b/website/content/fr/index.md @@ -4,14 +4,14 @@ Cette documentation fournit un guide complet pour installer, utiliser et dévelo ## Aperçu -Qwen Code apporte les capacités de modèles de code avancés directement dans votre terminal, au sein d'un environnement interactif Read-Eval-Print Loop (REPL). Qwen Code se compose d'une application côté client (`packages/cli`) qui communique avec un serveur local (`packages/core`). Qwen Code inclut également divers outils pour effectuer des opérations sur le système de fichiers, exécuter des commandes shell, et récupérer des données depuis le web, tous gérés par `packages/core`. +Qwen Code apporte les capacités de modèles de code avancés directement dans votre terminal, au sein d'un environnement REPL (Read-Eval-Print Loop) interactif. Qwen Code se compose d'une application côté client (`packages/cli`) qui communique avec un serveur local (`packages/core`). Qwen Code inclut également divers outils pour effectuer des opérations sur le système de fichiers, exécuter des commandes shell, ou encore récupérer des données depuis le web — ces fonctionnalités sont gérées par `packages/core`. ## Navigation dans la documentation Cette documentation est organisée en plusieurs sections : - **[Exécution et déploiement](./deployment.md) :** Informations pour exécuter Qwen Code. -- **[Aperçu de l'architecture](./architecture.md) :** Comprenez la conception de haut niveau de Qwen Code, y compris ses composants et leur interaction. +- **[Aperçu de l'architecture](./architecture.md) :** Comprenez la conception globale de Qwen Code, y compris ses composants et leurs interactions. - **Utilisation du CLI :** Documentation pour `packages/cli`. - **[Introduction au CLI](./cli/index.md) :** Aperçu de l'interface en ligne de commande. - **[Commandes](./cli/commands.md) :** Description des commandes CLI disponibles. @@ -24,17 +24,17 @@ Cette documentation est organisée en plusieurs sections : - **[Introduction au Core](./core/index.md) :** Aperçu du composant principal. - **[API des outils](./core/tools-api.md) :** Informations sur la façon dont le core gère et expose les outils. - **Outils :** - - **[Aperçu des outils](./tools/index.md) :** Aperçu des outils disponibles. + - **[Vue d'ensemble des outils](./tools/index.md) :** Présentation des outils disponibles. - **[Outils du système de fichiers](./tools/file-system.md) :** Documentation des outils `read_file` et `write_file`. - **[Outil de lecture multi-fichiers](./tools/multi-file.md) :** Documentation de l'outil `read_many_files`. - **[Outil Shell](./tools/shell.md) :** Documentation de l'outil `run_shell_command`. - - **[Outil de récupération web](./tools/web-fetch.md) :** Documentation de l'outil `web_fetch`. - - **[Outil de recherche web](./tools/web-search.md) :** Documentation de l'outil `web_search`. - - **[Outil de mémoire](./tools/memory.md) :** Documentation de l'outil `save_memory`. + - **[Outil Web Fetch](./tools/web-fetch.md) :** Documentation de l'outil `web_fetch`. + - **[Outil Web Search](./tools/web-search.md) :** Documentation de l'outil `web_search`. + - **[Outil Mémoire](./tools/memory.md) :** Documentation de l'outil `save_memory`. - **[Sous-agents](./subagents.md) :** Assistants IA spécialisés pour des tâches ciblées, avec un guide complet de gestion, configuration et utilisation. -- **[Guide de contribution et développement](../CONTRIBUTING.md) :** Informations pour les contributeurs et développeurs, incluant l'installation, la construction, les tests et les conventions de codage. -- **[Workspaces NPM et publication](./npm.md) :** Détails sur la gestion et la publication des packages du projet. -- **[Guide de dépannage](./troubleshooting.md) :** Trouvez des solutions aux problèmes courants et aux questions fréquentes. +- **[Guide de contribution et développement](../CONTRIBUTING.md) :** Informations destinées aux contributeurs et développeurs, incluant l'installation, la compilation, les tests et les conventions de codage. +- **[NPM](./npm.md) :** Détails sur la structure des packages du projet. +- **[Guide de dépannage](./troubleshooting.md) :** Trouvez des solutions aux problèmes courants et FAQ. - **[Conditions d'utilisation et politique de confidentialité](./tos-privacy.md) :** Informations sur les conditions d'utilisation et les mentions de confidentialité applicables à votre utilisation de Qwen Code. Nous espérons que cette documentation vous aidera à tirer le meilleur parti de Qwen Code ! \ No newline at end of file diff --git a/website/content/fr/keyboard-shortcuts.md b/website/content/fr/keyboard-shortcuts.md index b536e59c..b034dd5e 100644 --- a/website/content/fr/keyboard-shortcuts.md +++ b/website/content/fr/keyboard-shortcuts.md @@ -4,16 +4,16 @@ Ce document liste les raccourcis clavier disponibles dans Qwen Code. ## Général -| Raccourci | Description | -| --------- | --------------------------------------------------------------------------------------------------------------------- | -| `Esc` | Fermer les boîtes de dialogue et les suggestions. | -| `Ctrl+C` | Annuler la requête en cours et effacer l'entrée. Appuyez deux fois pour quitter l'application. | -| `Ctrl+D` | Quitter l'application si l'entrée est vide. Appuyez deux fois pour confirmer. | -| `Ctrl+L` | Effacer l'écran. | -| `Ctrl+O` | Activer/désactiver l'affichage de la console de débogage. | -| `Ctrl+S` | Permet aux réponses longues de s'afficher entièrement, en désactivant la troncature. Utilisez le défilement de votre terminal pour voir la sortie complète. | -| `Ctrl+T` | Activer/désactiver l'affichage des descriptions des outils. | -| `Ctrl+Y` | Activer/désactiver l'approbation automatique (mode YOLO) pour tous les appels d'outils. | +| Raccourci | Description | +| ----------- | --------------------------------------------------------------------------------------------------------------------- | +| `Esc` | Fermer les boîtes de dialogue et les suggestions. | +| `Ctrl+C` | Annuler la requête en cours et effacer l'entrée. Appuyez deux fois pour quitter l'application. | +| `Ctrl+D` | Quitter l'application si l'entrée est vide. Appuyez deux fois pour confirmer. | +| `Ctrl+L` | Effacer l'écran. | +| `Ctrl+O` | Activer/désactiver l'affichage de la console de débogage. | +| `Ctrl+S` | Permet aux réponses longues de s'afficher entièrement, en désactivant la troncature. Utilisez le défilement de votre terminal pour voir la sortie complète. | +| `Ctrl+T` | Activer/désactiver l'affichage des descriptions des outils. | +| `Shift+Tab` | Parcourir les modes d'approbation (`plan` → `default` → `auto-edit` → `yolo`). | ## Input Prompt @@ -21,14 +21,15 @@ Ce document liste les raccourcis clavier disponibles dans Qwen Code. | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `!` | Basculer en mode shell lorsque l'entrée est vide. | | `\` (en fin de ligne) + `Enter` | Insérer un saut de ligne. | -| `Flèche du bas` | Naviguer vers le bas dans l'historique des entrées. | +| `Flèche bas` | Naviguer vers le bas dans l'historique des entrées. | | `Enter` | Soumettre l'invite actuelle. | | `Meta+Delete` / `Ctrl+Delete` | Supprimer le mot à droite du curseur. | | `Tab` | Compléter automatiquement la suggestion actuelle si elle existe. | -| `Flèche du haut` | Naviguer vers le haut dans l'historique des entrées. | +| `Flèche haut` | Naviguer vers le haut dans l'historique des entrées. | | `Ctrl+A` / `Home` | Déplacer le curseur au début de la ligne. | | `Ctrl+B` / `Flèche gauche` | Déplacer le curseur d'un caractère vers la gauche. | | `Ctrl+C` | Effacer l'invite d'entrée. | +| `Esc` (appui double) | Effacer l'invite d'entrée. | | `Ctrl+D` / `Delete` | Supprimer le caractère à droite du curseur. | | `Ctrl+E` / `End` | Déplacer le curseur à la fin de la ligne. | | `Ctrl+F` / `Flèche droite` | Déplacer le curseur d'un caractère vers la droite. | @@ -51,7 +52,7 @@ Ce document liste les raccourcis clavier disponibles dans Qwen Code. | `Tab` / `Enter` | Accepter la suggestion sélectionnée. | | `Up Arrow` | Naviguer vers le haut dans les suggestions. | -## Radio Button Select +## Sélection par bouton radio | Raccourci | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------- | @@ -59,7 +60,7 @@ Ce document liste les raccourcis clavier disponibles dans Qwen Code. | `Enter` | Confirmer la sélection. | | `Up Arrow` / `k` | Déplacer la sélection vers le haut. | | `1-9` | Sélectionner un élément par son numéro. | -| (multi-digit) | Pour les éléments avec des numéros supérieurs à 9, appuyez rapidement sur les chiffres pour sélectionner l'élément correspondant. | +| (multi-chiffres) | Pour les éléments avec des numéros supérieurs à 9, appuyez rapidement sur les chiffres pour sélectionner l'élément correspondant. | ## Intégration IDE diff --git a/website/content/fr/qwen-ignore.md b/website/content/fr/qwen-ignore.md new file mode 100644 index 00000000..c95500c1 --- /dev/null +++ b/website/content/fr/qwen-ignore.md @@ -0,0 +1,62 @@ +# Ignorer des fichiers + +Ce document fournit une vue d'ensemble de la fonctionnalité Qwen Ignore (`.qwenignore`) de Qwen Code. + +Qwen Code inclut la capacité d'ignorer automatiquement des fichiers, de manière similaire à `.gitignore` (utilisé par Git). Ajouter des chemins à votre fichier `.qwenignore` les exclura des outils qui supportent cette fonctionnalité, bien qu'ils resteront visibles pour les autres services (comme Git). + +## Fonctionnement + +Lorsque vous ajoutez un chemin à votre fichier `.qwenignore`, les outils qui respectent ce fichier excluront automatiquement les fichiers et dossiers correspondants de leurs opérations. Par exemple, lorsque vous utilisez la commande [`read_many_files`](./tools/multi-file.md), tous les chemins présents dans votre fichier `.qwenignore` seront automatiquement ignorés. + +Dans l'ensemble, `.qwenignore` suit les conventions des fichiers `.gitignore` : + +- Les lignes vides ainsi que celles commençant par `#` sont ignorées. +- Les motifs glob standards sont pris en charge (comme `*`, `?`, et `[]`). +- Ajouter un `/` à la fin ne correspondra qu’aux dossiers. +- Placer un `/` au début ancre le chemin relativement au fichier `.qwenignore`. +- Le symbole `!` permet d’inverser (négation) un motif. + +Vous pouvez modifier votre fichier `.qwenignore` à tout moment. Pour appliquer les changements, vous devez redémarrer votre session Qwen Code. + +## Comment utiliser `.qwenignore` + +Pour activer `.qwenignore` : + +1. Créez un fichier nommé `.qwenignore` à la racine de votre répertoire de projet. + +Pour ajouter un fichier ou un répertoire à `.qwenignore` : + +1. Ouvrez votre fichier `.qwenignore`. +2. Ajoutez le chemin ou le fichier que vous souhaitez ignorer, par exemple : `/archive/` ou `apikeys.txt`. + +### Exemples de `.qwenignore` + +Vous pouvez utiliser `.qwenignore` pour ignorer des répertoires et des fichiers : + +``` + +# Exclure votre répertoire /packages/ et tous ses sous-répertoires +/packages/ + +# Exclure votre fichier apikeys.txt +apikeys.txt +``` + +Vous pouvez utiliser des wildcards dans votre fichier `.qwenignore` avec `*` : + +``` + +# Exclure tous les fichiers .md +*.md +``` + +Enfin, vous pouvez exclure des fichiers et des répertoires de l'exclusion avec `!` : + +``` + +# Exclure tous les fichiers .md sauf README.md +*.md +!README.md +``` + +Pour supprimer des chemins de votre fichier `.qwenignore`, supprimez les lignes concernées. \ No newline at end of file diff --git a/website/content/fr/subagents.md b/website/content/fr/subagents.md index ac68d1d5..f777a29a 100644 --- a/website/content/fr/subagents.md +++ b/website/content/fr/subagents.md @@ -1,33 +1,33 @@ # Subagents -Les subagents sont des assistants AI spécialisés qui gèrent des types de tâches spécifiques au sein de Qwen Code. Ils vous permettent de déléguer du travail ciblé à des agents AI configurés avec des prompts, des outils et des comportements adaptés à chaque tâche. +Les subagents sont des assistants IA spécialisés qui gèrent des types de tâches spécifiques au sein de Qwen Code. Ils vous permettent de déléguer un travail ciblé à des agents IA configurés avec des prompts, des outils et des comportements adaptés à chaque tâche. -## Que sont les Subagents ? +## Qu'est-ce qu'un Subagent ? -Les subagents sont des assistants AI indépendants qui : +Les subagents sont des assistants IA indépendants qui : -- **Spécialisés dans des tâches spécifiques** - Chaque subagent est configuré avec un prompt système dédié à un type particulier de travail -- **Possèdent un contexte séparé** - Ils maintiennent leur propre historique de conversation, distinct de votre chat principal +- **Se spécialisent dans des tâches précises** - Chaque subagent est configuré avec un prompt système spécifique pour un type particulier de travail +- **Possèdent leur propre contexte** - Ils maintiennent un historique de conversation distinct de votre discussion principale - **Utilisent des outils contrôlés** - Vous pouvez configurer les outils auxquels chaque subagent a accès -- **Travaillent de manière autonome** - Une fois une tâche assignée, ils travaillent indépendamment jusqu'à son achèvement ou son échec -- **Fournissent des retours détaillés** - Vous pouvez suivre leur progression, l'utilisation des outils et les statistiques d'exécution en temps réel +- **Travaillent de manière autonome** - Une fois une tâche assignée, ils travaillent indépendamment jusqu'à son achèvement ou échec +- **Fournissent un feedback détaillé** - Vous pouvez suivre en temps réel leur progression, l'utilisation des outils et les statistiques d'exécution -## Principaux avantages +## Avantages Clés -- **Spécialisation des tâches** : Créez des agents optimisés pour des workflows spécifiques (tests, documentation, refactoring, etc.) -- **Isolation du contexte** : Gardez le travail spécialisé séparé de votre conversation principale +- **Spécialisation des Tâches** : Créez des agents optimisés pour des workflows spécifiques (tests, documentation, refactoring, etc.) +- **Isolation du Contexte** : Gardez le travail spécialisé séparé de votre conversation principale - **Réutilisabilité** : Sauvegardez et réutilisez les configurations d'agents entre projets et sessions -- **Accès contrôlé** : Limitez les outils disponibles pour chaque agent afin d'assurer la sécurité et la concentration -- **Visibilité sur l'avancement** : Surveillez l'exécution des agents avec des mises à jour en temps réel +- **Accès Contrôlé** : Limitez les outils que chaque agent peut utiliser pour la sécurité et la concentration +- **Visibilité sur l'Avancement** : Surveillez l'exécution des agents avec des mises à jour en temps réel -## Fonctionnement des sous-agents +## Comment Fonctionnent les Sous-Agents -1. **Configuration** : Vous définissez des configurations de sous-agents qui spécifient leur comportement, leurs outils et leurs prompts système +1. **Configuration** : Vous créez des configurations de sous-agents qui définissent leur comportement, leurs outils et leurs prompts système 2. **Délégation** : L'IA principale peut automatiquement déléguer des tâches aux sous-agents appropriés -3. **Exécution** : Les sous-agents travaillent de manière indépendante en utilisant leurs outils configurés pour accomplir les tâches -4. **Résultats** : Ils renvoient les résultats et un résumé de l'exécution dans la conversation principale +3. **Exécution** : Les sous-agents travaillent indépendamment, utilisant leurs outils configurés pour accomplir les tâches +4. **Résultats** : Ils renvoient les résultats et les résumés d'exécution dans la conversation principale -## Premiers pas +## Premiers Pas ### Démarrage rapide @@ -47,7 +47,7 @@ Les subagents sont des assistants AI indépendants qui : Affichez et gérez vos subagents configurés. -3. **Utiliser les subagents automatiquement** : +3. **Utiliser les subagents automatiquement** : Il suffit de demander à l'IA principale d'effectuer des tâches correspondant aux spécialisations de vos subagents. L'IA déléguera automatiquement le travail approprié. ### Exemple d'utilisation @@ -56,9 +56,9 @@ Les subagents sont des assistants AI indépendants qui : Utilisateur : "Veuillez écrire des tests complets pour le module d'authentification" IA : Je vais déléguer cela à votre subagent spécialiste des tests. -[Délégue au subagent "testing-expert"] +[Délègue au subagent "testing-expert"] [Affiche la progression en temps réel de la création des tests] -[Renvoie les fichiers de test terminés et un résumé de l'exécution] +[Retourne les fichiers de test terminés et un résumé de l'exécution] ``` ## Gestion @@ -94,7 +94,7 @@ Les sous-agents sont stockés sous forme de fichiers Markdown dans deux emplacem - **Niveau projet** : `.qwen/agents/` (prioritaire) - **Niveau utilisateur** : `~/.qwen/agents/` (solution de repli) -Cela vous permet d'avoir à la fois des agents spécifiques au projet et des agents personnels qui fonctionnent dans tous les projets. +Cela vous permet d'avoir à la fois des agents spécifiques au projet et des agents personnels qui fonctionnent sur tous vos projets. ### Format de fichier @@ -111,7 +111,7 @@ tools: tool1, tool2, tool3 # Optionnel Le contenu du prompt système va ici. Plusieurs paragraphes sont pris en charge. -Vous pouvez utiliser la syntaxe ${variable} pour du contenu dynamique. +Vous pouvez utiliser le templating ${variable} pour du contenu dynamique. ``` #### Exemple d'utilisation @@ -129,10 +129,32 @@ Votre tâche : ${task_description} Répertoire de travail : ${current_directory} Généré le : ${timestamp} -Concentrez-vous sur la création d'une documentation claire et complète qui aide +Concentrez-vous sur la création d'une documentation claire et complète qui aide à la fois les nouveaux contributeurs et les utilisateurs finaux à comprendre le projet. ``` +## Utilisation efficace des sous-agents + +### Délégation automatique + +Qwen Code délègue proactivement les tâches en se basant sur : + +- La description de la tâche dans votre requête +- Le champ description dans les configurations des sous-agents +- Le contexte actuel et les outils disponibles + +Pour encourager une utilisation plus proactive des sous-agents, incluez des phrases comme "utiliser de manière PROACTIVE" ou "DOIT ÊTRE UTILISÉ" dans votre champ description. + +### Invocation explicite + +Demandez un sous-agent spécifique en le mentionnant dans votre commande : + +``` +> Laissez le sous-agent testing-expert créer des tests unitaires pour le module de paiement +> Demandez au sous-agent documentation-writer de mettre à jour la référence API +> Faites en sorte que le sous-agent react-specialist optimise les performances de ce composant +``` + ## Exemples ### Agents de workflow de développement @@ -150,7 +172,7 @@ tools: read_file, write_file, read_many_files, run_shell_command Vous êtes un spécialiste des tests, concentré sur la création de tests de haute qualité et maintenables. -Votre expertise comprend : +Votre expertise inclut : - Les tests unitaires avec mocking et isolation appropriés - Les tests d'intégration pour les interactions entre composants @@ -163,19 +185,19 @@ Pour chaque tâche de test : 1. Analysez la structure du code et ses dépendances 2. Identifiez les fonctionnalités clés, les cas limites et les conditions d'erreur 3. Créez des suites de tests complètes avec des noms explicites -4. Incluez une configuration/nettoyage approprié et des assertions significatives +4. Incluez une configuration/nettoyage appropriés et des assertions significatives 5. Ajoutez des commentaires pour expliquer les scénarios de test complexes -6. Assurez-vous que les tests sont maintenables et respectent les principes DRY +6. Assurez-vous que les tests sont maintenables et respectent le principe DRY -Suivez toujours les meilleures pratiques de test pour le langage et le framework détectés. -Portez attention aux cas de test positifs et négatifs. +Appliquez toujours les meilleures pratiques de test pour le langage et le framework détectés. +Portez attention aux cas de test positifs comme négatifs. ``` **Cas d'usage :** -- "Écrire des tests unitaires pour le service d'authentification" -- "Créer des tests d'intégration pour le workflow de traitement des paiements" -- "Ajouter une couverture de test pour les cas limites dans le module de validation des données" +- "Écris des tests unitaires pour le service d'authentification" +- "Crée des tests d'intégration pour le workflow de traitement des paiements" +- "Ajoute une couverture de test pour les cas limites dans le module de validation des données" #### Documentation Writer @@ -195,7 +217,7 @@ les développeurs et les utilisateurs finaux. Concentrez-vous sur : **Pour la documentation API :** -- Des descriptions claires des endpoints avec des exemples +- Des descriptions d'endpoints claires avec des exemples - Les détails des paramètres avec leurs types et contraintes - La documentation du format des réponses - Les explications des codes d'erreur @@ -203,7 +225,7 @@ les développeurs et les utilisateurs finaux. Concentrez-vous sur : **Pour la documentation utilisateur :** -- Des instructions pas à pas avec des captures d'écran quand c'est utile +- Des instructions pas à pas avec des captures d'écran quand cela aide - Des guides d'installation et de configuration - Les options de configuration et des exemples - Des sections de dépannage pour les problèmes courants @@ -213,110 +235,110 @@ les développeurs et les utilisateurs finaux. Concentrez-vous sur : - Des aperçus de l'architecture et des décisions de conception - Des exemples de code qui fonctionnent vraiment -- Des guidelines pour contribuer +- Des directives de contribution - La configuration de l'environnement de développement Vérifiez toujours les exemples de code et assurez-vous que la documentation reste à jour avec l'implémentation actuelle. Utilisez des titres clairs, des listes à puces et des exemples. ``` -**Cas d'usage :** +**Cas d'utilisation :** - "Créez la documentation API pour les endpoints de gestion des utilisateurs" -- "Écrivez un README complet pour ce projet" -- "Documentez le processus de déploiement avec des étapes de dépannage" +- "Rédigez un README complet pour ce projet" +- "Documentez le processus de déploiement avec les étapes de dépannage" #### Code Reviewer -Axé sur la qualité du code, la sécurité et les bonnes pratiques. +Axé sur la qualité du code, la sécurité et les meilleures pratiques. ```markdown --- name: code-reviewer -description: Examine le code pour vérifier les bonnes pratiques, les problèmes de sécurité, les performances et la maintenabilité +description: Reviews code for best practices, security issues, performance, and maintainability tools: read_file, read_many_files --- -Vous êtes un relecteur de code expérimenté, concentré sur la qualité, la sécurité et la maintenabilité. +You are an experienced code reviewer focused on quality, security, and maintainability. -Critères d'évaluation : +Review criteria: -- **Structure du code** : Organisation, modularité et séparation des responsabilités -- **Performance** : Efficacité algorithmique et utilisation des ressources -- **Sécurité** : Évaluation des vulnérabilités et pratiques de codage sécurisé -- **Bonnes pratiques** : Conventions spécifiques au langage/au framework -- **Gestion des erreurs** : Gestion correcte des exceptions et couverture des cas limites -- **Lisibilité** : Nommage clair, commentaires et organisation du code -- **Tests** : Couverture des tests et facilité de testabilité +- **Code Structure**: Organization, modularity, and separation of concerns +- **Performance**: Algorithmic efficiency and resource usage +- **Security**: Vulnerability assessment and secure coding practices +- **Best Practices**: Language/framework-specific conventions +- **Error Handling**: Proper exception handling and edge case coverage +- **Readability**: Clear naming, comments, and code organization +- **Testing**: Test coverage and testability considerations -Fournissez des retours constructifs comprenant : +Provide constructive feedback with: -1. **Problèmes critiques** : Vulnérabilités de sécurité, bugs majeurs -2. **Améliorations importantes** : Problèmes de performance, problèmes de conception -3. **Suggestions mineures** : Améliorations stylistiques, opportunités de refactoring -4. **Retours positifs** : Patterns bien implémentés et bonnes pratiques +1. **Critical Issues**: Security vulnerabilities, major bugs +2. **Important Improvements**: Performance issues, design problems +3. **Minor Suggestions**: Style improvements, refactoring opportunities +4. **Positive Feedback**: Well-implemented patterns and good practices -Concentrez-vous sur des retours exploitables avec des exemples précis et des solutions suggérées. -Priorisez les problèmes par impact et fournissez une justification pour vos recommandations. +Focus on actionable feedback with specific examples and suggested solutions. +Prioritize issues by impact and provide rationale for recommendations. ``` -**Cas d'utilisation :** +**Cas d'usage :** -- "Examinez cette implémentation d'authentification pour identifier les problèmes de sécurité" -- "Analysez les implications de performance de cette logique de requête de base de données" -- "Évaluez la structure du code et suggérez des améliorations" +- "Review this authentication implementation for security issues" +- "Check the performance implications of this database query logic" +- "Evaluate the code structure and suggest improvements" ### Agents Spécifiques aux Technologies -#### Spécialiste React +#### React Specialist Optimisé pour le développement React, les hooks et les patterns de composants. ```markdown --- name: react-specialist -description: Expert en développement React, hooks, patterns de composants et meilleures pratiques React modernes +description: Expert in React development, hooks, component patterns, and modern React best practices tools: read_file, write_file, read_many_files, run_shell_command --- -Vous êtes un spécialiste React avec une expertise approfondie en développement React moderne. +You are a React specialist with deep expertise in modern React development. -Votre expertise couvre : +Your expertise covers: -- **Conception de composants** : Composants fonctionnels, hooks personnalisés, patterns de composition -- **Gestion d'état** : useState, useReducer, Context API et bibliothèques externes -- **Performance** : React.memo, useMemo, useCallback, code splitting -- **Testing** : React Testing Library, Jest, stratégies de testing de composants -- **Intégration TypeScript** : Typage approprié pour les props, hooks et composants -- **Patterns modernes** : Suspense, Error Boundaries, fonctionnalités concurrentes +- **Component Design**: Functional components, custom hooks, composition patterns +- **State Management**: useState, useReducer, Context API, and external libraries +- **Performance**: React.memo, useMemo, useCallback, code splitting +- **Testing**: React Testing Library, Jest, component testing strategies +- **TypeScript Integration**: Proper typing for props, hooks, and components +- **Modern Patterns**: Suspense, Error Boundaries, Concurrent Features -Pour les tâches React : +For React tasks: -1. Utilisez des composants fonctionnels et des hooks par défaut -2. Implémentez un typage TypeScript approprié -3. Suivez les meilleures pratiques et conventions React -4. Considérez les implications de performance -5. Incluez une gestion d'erreurs appropriée -6. Écrivez du code testable et maintenable +1. Use functional components and hooks by default +2. Implement proper TypeScript typing +3. Follow React best practices and conventions +4. Consider performance implications +5. Include appropriate error handling +6. Write testable, maintainable code -Restez toujours à jour avec les meilleures pratiques React et évitez les patterns dépréciés. -Focalisez-vous sur les considérations d'accessibilité et d'expérience utilisateur. +Always stay current with React best practices and avoid deprecated patterns. +Focus on accessibility and user experience considerations. ``` **Cas d'usage :** -- "Créer un composant de tableau de données réutilisable avec tri et filtrage" -- "Implémenter un hook personnalisé pour la récupération de données API avec mise en cache" -- "Refactorer ce composant classe pour utiliser les patterns React modernes" +- "Create a reusable data table component with sorting and filtering" +- "Implement a custom hook for API data fetching with caching" +- "Refactor this class component to use modern React patterns" -#### Python Expert +#### Expert Python Spécialisé dans le développement Python, les frameworks et les meilleures pratiques. ```markdown --- name: python-expert -description: Expert en développement Python, frameworks, testing, et meilleures pratiques spécifiques à Python +description: Expert en développement Python, frameworks, tests et meilleures pratiques spécifiques à Python tools: read_file, write_file, read_many_files, run_shell_command --- @@ -326,8 +348,8 @@ Votre expertise inclut : - **Python de base** : Patterns pythoniques, structures de données, algorithmes - **Frameworks** : Django, Flask, FastAPI, SQLAlchemy -- **Testing** : pytest, unittest, mocking, test-driven development -- **Data Science** : pandas, numpy, matplotlib, jupyter notebooks +- **Tests** : pytest, unittest, mocking, développement piloté par les tests +- **Science des données** : pandas, numpy, matplotlib, notebooks Jupyter - **Programmation asynchrone** : asyncio, patterns async/await - **Gestion des paquets** : pip, poetry, environnements virtuels - **Qualité du code** : PEP 8, type hints, linting avec pylint/flake8 @@ -337,9 +359,9 @@ Pour les tâches Python : 1. Suivez les directives de style PEP 8 2. Utilisez des type hints pour une meilleure documentation du code 3. Implémentez une gestion d'erreurs appropriée avec des exceptions spécifiques -4. Écrivez des docstrings complètes -5. Prenez en compte les performances et l'utilisation de la mémoire -6. Incluez un logging approprié +4. Écrivez des docstrings complets +5. Considérez les performances et l'utilisation de la mémoire +6. Incluez une journalisation appropriée 7. Écrivez du code modulaire et testable Concentrez-vous sur l'écriture de code Python propre et maintenable qui suit les standards de la communauté. @@ -347,9 +369,9 @@ Concentrez-vous sur l'écriture de code Python propre et maintenable qui suit le **Cas d'usage :** -- "Créer un service FastAPI pour l'authentification des utilisateurs avec des tokens JWT" +- "Créer un service FastAPI pour l'authentification utilisateur avec des tokens JWT" - "Implémenter un pipeline de traitement de données avec pandas et gestion des erreurs" -- "Écrire un outil CLI en utilisant argparse avec une documentation d'aide complète" +- "Écrire un outil CLI utilisant argparse avec une documentation d'aide complète" ## Bonnes pratiques @@ -359,7 +381,7 @@ Concentrez-vous sur l'écriture de code Python propre et maintenable qui suit le Chaque sous-agent doit avoir un objectif clair et précis. -**✅ Bon :** +**✅ Bon exemple :** ```markdown --- @@ -383,7 +405,7 @@ description: Helps with testing, documentation, code review, and deployment Définissez des domaines d'expertise spécifiques plutôt que des compétences générales. -**✅ Bon :** +**✅ Bon exemple :** ```markdown --- @@ -407,16 +429,16 @@ description: Works on frontend development tasks Rédigez des descriptions qui indiquent clairement quand utiliser l'agent. -**✅ Bon :** +**✅ Bon exemple :** ```markdown -description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns +description: Analyse le code pour détecter les vulnérabilités de sécurité, les problèmes de performance et les concerns de maintenabilité ``` **❌ À éviter :** ```markdown -description: A helpful code reviewer +description: Un assistant utile pour la revue de code ``` **Pourquoi :** Des descriptions claires aident l'IA principale à choisir le bon agent pour chaque tâche. @@ -461,9 +483,9 @@ Suivez toujours ces standards : ## Considérations de sécurité -- **Restrictions des outils** : Les subagents n'ont accès qu'aux outils configurés +- **Restrictions des outils** : Les sous-agents n'ont accès qu'aux outils configurés - **Sandboxing** : Toute exécution d'outil suit le même modèle de sécurité que l'utilisation directe des outils -- **Journal d'audit** : Toutes les actions des subagents sont enregistrées et visibles en temps réel +- **Journalisation** : Toutes les actions des sous-agents sont enregistrées et visibles en temps réel - **Contrôle d'accès** : La séparation au niveau projet et utilisateur fournit des limites appropriées - **Informations sensibles** : Évitez d'inclure des secrets ou des identifiants dans les configurations des agents - **Environnements de production** : Envisagez d'utiliser des agents distincts pour les environnements de production et de développement \ No newline at end of file diff --git a/website/content/fr/telemetry.md b/website/content/fr/telemetry.md index a8eda139..27d60241 100644 --- a/website/content/fr/telemetry.md +++ b/website/content/fr/telemetry.md @@ -6,9 +6,9 @@ Le système de télémétrie de Qwen Code est basé sur la norme **[OpenTelemetr [OpenTelemetry]: https://opentelemetry.io/ -## Activer la télémétrie +## Activation de la télémétrie -Vous pouvez activer la télémétrie de plusieurs façons. La configuration est principalement gérée via le fichier [`.qwen/settings.json`](./cli/configuration.md) et les variables d'environnement, mais les flags CLI peuvent outrepasser ces paramètres pour une session spécifique. +Vous pouvez activer la télémétrie de plusieurs façons. La configuration est principalement gérée via le fichier [`.qwen/settings.json`](./cli/configuration.md) et les variables d'environnement, mais les flags CLI peuvent remplacer ces paramètres pour une session spécifique. ### Ordre de priorité @@ -24,22 +24,22 @@ Voici la liste des priorités d'application des paramètres de télémétrie, le 1. **Variables d'environnement :** - `OTEL_EXPORTER_OTLP_ENDPOINT` : Remplace `telemetry.otlpEndpoint`. -1. **Fichier de paramètres du workspace (`.qwen/settings.json`) :** Valeurs provenant de l'objet `telemetry` dans ce fichier spécifique au projet. +1. **Fichier de configuration du workspace (`.qwen/settings.json`) :** Valeurs issues de l’objet `telemetry` dans ce fichier spécifique au projet. -1. **Fichier de paramètres utilisateur (`~/.qwen/settings.json`) :** Valeurs provenant de l'objet `telemetry` dans ce fichier global de l'utilisateur. +1. **Fichier de configuration utilisateur (`~/.qwen/settings.json`) :** Valeurs issues de l’objet `telemetry` dans ce fichier global utilisateur. -1. **Valeurs par défaut :** appliquées si elles ne sont définies par aucun des moyens ci-dessus. +1. **Valeurs par défaut :** appliquées si aucune des sources ci-dessus ne les définit. - `telemetry.enabled` : `false` - `telemetry.target` : `local` - `telemetry.otlpEndpoint` : `http://localhost:4317` - `telemetry.logPrompts` : `true` **Pour le script `npm run telemetry -- --target=` :** -L'argument `--target` de ce script ne remplace _que_ `telemetry.target` le temps de l'exécution et dans le but de ce script (c'est-à-dire choisir quel collector démarrer). Il ne modifie pas de manière permanente votre `settings.json`. Le script regardera d'abord dans `settings.json` s'il y a un `telemetry.target` à utiliser comme valeur par défaut. +L’argument `--target` de ce script remplace _uniquement_ la valeur de `telemetry.target` pendant l'exécution et à seule fin de ce script (c’est-à-dire choisir quel collecteur démarrer). Il ne modifie pas durablement votre fichier `settings.json`. Le script utilisera d'abord la valeur définie dans `settings.json` pour `telemetry.target` comme valeur par défaut. ### Exemple de configuration -Le code suivant peut être ajouté à vos paramètres de workspace (`.qwen/settings.json`) ou utilisateur (`~/.qwen/settings.json`) pour activer la télémétrie et envoyer les données vers Google Cloud : +Le code suivant peut être ajouté à vos paramètres d'espace de travail (`.qwen/settings.json`) ou utilisateur (`~/.qwen/settings.json`) pour activer la télémétrie et envoyer les données vers Google Cloud : ```json { @@ -53,16 +53,16 @@ Le code suivant peut être ajouté à vos paramètres de workspace (`.qwen/setti ### Export vers un fichier -Vous pouvez exporter toutes les données de télémétrie vers un fichier pour inspection locale. +Vous pouvez exporter toutes les données de télémétrie dans un fichier pour inspection locale. -Pour activer l'export vers un fichier, utilisez le flag `--telemetry-outfile` avec un chemin vers le fichier de sortie souhaité. Cela doit être exécuté en utilisant `--telemetry-target=local`. +Pour activer l'export vers un fichier, utilisez le flag `--telemetry-outfile` avec le chemin du fichier de sortie souhaité. Cela doit être exécuté en utilisant `--telemetry-target=local`. ```bash -# Définissez le chemin du fichier de sortie souhaité +# Définir le chemin du fichier de sortie TELEMETRY_FILE=".qwen/telemetry.log" -# Exécutez Qwen Code avec la télémétrie locale +# Exécuter Qwen Code avec la télémétrie locale # NOTE : --telemetry-otlp-endpoint="" est requis pour remplacer l'exporter @@ -89,10 +89,10 @@ Pour en savoir plus sur la configuration standard de l'exporter OTEL, consultez ### Local -Utilisez la commande `npm run telemetry -- --target=local` pour automatiser la configuration d’un pipeline de télémétrie local, y compris la configuration des paramètres nécessaires dans votre fichier `.qwen/settings.json`. Le script sous-jacent installe `otelcol-contrib` (le OpenTelemetry Collector) et `jaeger` (l’interface Jaeger pour visualiser les traces). Pour l’utiliser : +Utilisez la commande `npm run telemetry -- --target=local` pour automatiser le processus de configuration d’un pipeline de télémétrie local, y compris la configuration des paramètres nécessaires dans votre fichier `.qwen/settings.json`. Le script sous-jacent installe `otelcol-contrib` (le OpenTelemetry Collector) et `jaeger` (l’interface utilisateur Jaeger pour visualiser les traces). Pour l’utiliser : 1. **Exécutez la commande** : - Lancez la commande depuis la racine du repository : + Lancez la commande depuis la racine du dépôt : ```bash npm run telemetry -- --target=local @@ -100,7 +100,7 @@ Utilisez la commande `npm run telemetry -- --target=local` pour automatiser la c Le script va : - Télécharger Jaeger et OTEL si nécessaire. - - Démarrer une instance Jaeger locale. + - Démarrer une instance locale de Jaeger. - Démarrer un collecteur OTEL configuré pour recevoir les données de Qwen Code. - Activer automatiquement la télémétrie dans les paramètres de votre espace de travail. - À l’arrêt, désactiver la télémétrie. @@ -109,49 +109,49 @@ Utilisez la commande `npm run telemetry -- --target=local` pour automatiser la c Ouvrez votre navigateur web et rendez-vous sur **http://localhost:16686** pour accéder à l’interface Jaeger. Vous pourrez ici inspecter les traces détaillées des opérations de Qwen Code. 3. **Inspectez les logs et métriques** : - Le script redirige la sortie du collecteur OTEL (incluant les logs et métriques) vers `~/.qwen/tmp//otel/collector.log`. Le script fournira des liens pour visualiser et une commande pour suivre en temps réel vos données de télémétrie (traces, métriques, logs) localement. + Le script redirige la sortie du collecteur OTEL (incluant les logs et métriques) vers `~/.qwen/tmp//otel/collector.log`. Le script vous fournira des liens pour consulter et une commande pour suivre en temps réel vos données de télémétrie (traces, métriques, logs) localement. 4. **Arrêtez les services** : Appuyez sur `Ctrl+C` dans le terminal où le script est en cours d’exécution pour arrêter le collecteur OTEL et les services Jaeger. ### Google Cloud -Utilisez la commande `npm run telemetry -- --target=gcp` pour automatiser la configuration d’un collecteur OpenTelemetry local qui transmet les données à votre projet Google Cloud, y compris la configuration des paramètres nécessaires dans votre fichier `.qwen/settings.json`. Le script sous-jacent installe `otelcol-contrib`. Pour l’utiliser : +Utilisez la commande `npm run telemetry -- --target=gcp` pour automatiser la configuration d’un collecteur OpenTelemetry local qui transmet les données vers votre projet Google Cloud, y compris la configuration des paramètres nécessaires dans votre fichier `.qwen/settings.json`. Le script sous-jacent installe `otelcol-contrib`. Pour l’utiliser : -1. **Prérequis** : - - Disposer d’un ID de projet Google Cloud. - - Exporter la variable d’environnement `GOOGLE_CLOUD_PROJECT` pour la rendre disponible au collecteur OTEL. - ```bash - export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" - ``` - - Vous authentifier auprès de Google Cloud (par exemple, exécutez `gcloud auth application-default login` ou assurez-vous que `GOOGLE_APPLICATION_CREDENTIALS` est défini). - - Vérifier que votre compte Google Cloud ou votre compte de service dispose des rôles IAM nécessaires : "Cloud Trace Agent", "Monitoring Metric Writer" et "Logs Writer". +1. **Prérequis** : + - Avoir un ID de projet Google Cloud. + - Exporter la variable d’environnement `GOOGLE_CLOUD_PROJECT` pour la rendre disponible au collecteur OTEL. + ```bash + export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" + ``` + - Être authentifié avec Google Cloud (ex. : exécutez `gcloud auth application-default login` ou assurez-vous que `GOOGLE_APPLICATION_CREDENTIALS` est défini). + - Vérifier que votre compte Google Cloud ou le compte de service dispose des rôles IAM nécessaires : "Cloud Trace Agent", "Monitoring Metric Writer" et "Logs Writer". -1. **Exécutez la commande** : - Exécutez la commande depuis la racine du dépôt : +2. **Exécutez la commande** : + Exécutez la commande depuis la racine du dépôt : - ```bash - npm run telemetry -- --target=gcp - ``` + ```bash + npm run telemetry -- --target=gcp + ``` - Le script va : - - Télécharger le binaire `otelcol-contrib` si nécessaire. - - Démarrer un collecteur OTEL configuré pour recevoir les données de Qwen Code et les exporter vers le projet Google Cloud spécifié. - - Activer automatiquement la télémétrie et désactiver le mode sandbox dans les paramètres de votre espace de travail (`.qwen/settings.json`). - - Fournir des liens directs pour visualiser les traces, métriques et logs dans la Google Cloud Console. - - À l’arrêt (Ctrl+C), il tentera de restaurer vos paramètres initiaux de télémétrie et de sandbox. + Le script va : + - Télécharger le binaire `otelcol-contrib` si nécessaire. + - Démarrer un collecteur OTEL configuré pour recevoir les données de Qwen Code et les exporter vers le projet Google Cloud spécifié. + - Activer automatiquement la télémétrie et désactiver le mode sandbox dans vos paramètres d’espace de travail (`.qwen/settings.json`). + - Fournir des liens directs pour visualiser les traces, métriques et logs dans la Google Cloud Console. + - À l’arrêt (Ctrl+C), il tentera de restaurer vos paramètres initiaux de télémétrie et de sandbox. -1. **Exécutez Qwen Code** : - Dans un autre terminal, lancez vos commandes Qwen Code. Cela génère des données de télémétrie que le collecteur capture. +3. **Exécutez Qwen Code** : + Dans un autre terminal, lancez vos commandes Qwen Code. Cela génère des données de télémétrie capturées par le collecteur. -1. **Visualisez la télémétrie dans Google Cloud** : - Utilisez les liens fournis par le script pour accéder à la Google Cloud Console et consulter vos traces, métriques et logs. +4. **Visualisez la télémétrie dans Google Cloud** : + Utilisez les liens fournis par le script pour accéder à la Google Cloud Console et consulter vos traces, métriques et logs. -1. **Consultez les logs du collecteur local** : - Le script redirige la sortie du collecteur OTEL local vers `~/.qwen/tmp//otel/collector-gcp.log`. Le script fournit des liens pour visualiser et une commande pour suivre en direct les logs du collecteur localement. +5. **Consultez les logs du collecteur local** : + Le script redirige la sortie du collecteur OTEL local vers `~/.qwen/tmp//otel/collector-gcp.log`. Le script fournit également des liens pour visualiser et une commande pour suivre en temps réel les logs du collecteur localement. -1. **Arrêtez le service** : - Appuyez sur `Ctrl+C` dans le terminal où le script est en cours d’exécution pour arrêter le collecteur OTEL. +6. **Arrêtez le service** : + Appuyez sur `Ctrl+C` dans le terminal où le script est en cours d’exécution pour arrêter le collecteur OTEL. ## Référence des logs et métriques @@ -161,7 +161,7 @@ La section suivante décrit la structure des logs et métriques générés pour ### Logs -Les logs sont des enregistrements horodatés d'événements spécifiques. Les événements suivants sont loggés pour Qwen Code : +Les logs sont des enregistrements horodatés d'événements spécifiques. Les événements suivants sont loggués pour Qwen Code : - `qwen-code.config` : Cet événement se produit une fois au démarrage avec la configuration du CLI. - **Attributs** : @@ -180,9 +180,10 @@ Les logs sont des enregistrements horodatés d'événements spécifiques. Les é - `qwen-code.user_prompt` : Cet événement se produit lorsqu'un utilisateur soumet un prompt. - **Attributs** : - - `prompt_length` - - `prompt` (cet attribut est exclu si `log_prompts_enabled` est configuré à `false`) - - `auth_type` + - `prompt_length` (int) + - `prompt_id` (string) + - `prompt` (string, cet attribut est exclu si `log_prompts_enabled` est configuré à `false`) + - `auth_type` (string) - `qwen-code.tool_call` : Cet événement se produit pour chaque appel de fonction. - **Attributs** : @@ -209,7 +210,7 @@ Les logs sont des enregistrements horodatés d'événements spécifiques. Les é - `duration_ms` - `auth_type` -- `qwen-code.api_response` : Cet événement se produit lorsqu'une réponse est reçue de l'API Qwen. +- `qwen-code.api_response` : Cet événement se produit lors de la réception d'une réponse de l'API Qwen. - **Attributs** : - `model` - `status_code` @@ -232,7 +233,7 @@ Les logs sont des enregistrements horodatés d'événements spécifiques. Les é - `command` (string) - `subcommand` (string, si applicable) -### Metrics +### Métriques Les métriques sont des mesures numériques du comportement au fil du temps. Les métriques suivantes sont collectées pour Qwen Code (les noms des métriques restent `qwen-code.*` pour des raisons de compatibilité) : @@ -267,14 +268,15 @@ Les métriques sont des mesures numériques du comportement au fil du temps. Les - `qwen-code.file.operation.count` (Compteur, Int) : Compte les opérations sur les fichiers. - **Attributs** : - - `operation` (chaîne : "create", "read", "update") : Le type d'opération sur le fichier. + - `operation` (chaîne : "create", "read", "update") : Le type d’opération sur le fichier. - `lines` (Int, si applicable) : Nombre de lignes dans le fichier. - `mimetype` (chaîne, si applicable) : Type MIME du fichier. - `extension` (chaîne, si applicable) : Extension du fichier. - - `ai_added_lines` (Int, si applicable) : Nombre de lignes ajoutées/modifiées par l'IA. - - `ai_removed_lines` (Int, si applicable) : Nombre de lignes supprimées/modifiées par l'IA. - - `user_added_lines` (Int, si applicable) : Nombre de lignes ajoutées/modifiées par l'utilisateur dans les modifications proposées par l'IA. - - `user_removed_lines` (Int, si applicable) : Nombre de lignes supprimées/modifiées par l'utilisateur dans les modifications proposées par l'IA. + - `ai_added_lines` (Int, si applicable) : Nombre de lignes ajoutées/modifiées par l’IA. + - `ai_removed_lines` (Int, si applicable) : Nombre de lignes supprimées/modifiées par l’IA. + - `user_added_lines` (Int, si applicable) : Nombre de lignes ajoutées/modifiées par l’utilisateur dans les modifications proposées par l’IA. + - `user_removed_lines` (Int, si applicable) : Nombre de lignes supprimées/modifiées par l’utilisateur dans les modifications proposées par l’IA. + - `programming_language` (chaîne, si applicable) : Langage de programmation du fichier. - `qwen-code.chat_compression` (Compteur, Int) : Compte les opérations de compression du chat. - **Attributs** : diff --git a/website/content/fr/tools/multi-file.md b/website/content/fr/tools/multi-file.md index 777fdd47..88d6bca2 100644 --- a/website/content/fr/tools/multi-file.md +++ b/website/content/fr/tools/multi-file.md @@ -1,4 +1,4 @@ -# Multi File Read Tool (`read_many_files`) +# Outil de lecture multi-fichiers (`read_many_files`) Ce document décrit l'outil `read_many_files` pour Qwen Code. @@ -7,30 +7,31 @@ Ce document décrit l'outil `read_many_files` pour Qwen Code. Utilisez `read_many_files` pour lire le contenu de plusieurs fichiers spécifiés par des chemins ou des patterns glob. Le comportement de cet outil dépend des fichiers fournis : - Pour les fichiers texte, cet outil concatène leur contenu en une seule chaîne. -- Pour les fichiers image (ex. : PNG, JPEG), PDF, audio (MP3, WAV) et vidéo (MP4, MOV), il les lit et les retourne encodés en base64, à condition qu'ils soient explicitement demandés par nom ou extension. +- Pour les fichiers image (ex. PNG, JPEG), PDF, audio (MP3, WAV) et vidéo (MP4, MOV), il les lit et les retourne en tant que données encodées en base64, à condition qu'ils soient explicitement demandés par nom ou extension. -`read_many_files` peut être utilisé pour effectuer des tâches telles qu'obtenir un aperçu d'une base de code, trouver où une fonctionnalité spécifique est implémentée, examiner de la documentation ou rassembler du contexte à partir de plusieurs fichiers de configuration. +`read_many_files` peut être utilisé pour effectuer des tâches telles que l'obtention d'un aperçu d'une base de code, la recherche d'implémentations spécifiques, la revue de documentation, ou la collecte de contexte depuis plusieurs fichiers de configuration. -**Note :** `read_many_files` recherche les fichiers correspondant aux chemins ou patterns glob fournis. Un chemin de répertoire tel que `"/docs"` renverra un résultat vide ; l'outil nécessite un pattern tel que `"/docs/*"` ou `"/docs/*.md"` pour identifier les fichiers concernés. +**Note :** `read_many_files` recherche les fichiers correspondant aux chemins ou patterns glob fournis. Un chemin de répertoire tel que `"/docs"` renverra un résultat vide ; l'outil nécessite un pattern tel que `"/docs/*"` ou `"/docs/*.md"` pour identifier les fichiers pertinents. ### Arguments `read_many_files` prend les arguments suivants : -- `paths` (list[string], requis) : Un tableau de glob patterns ou de chemins relatifs au répertoire cible de l'outil (ex : `["src/**/*.ts"]`, `["README.md", "docs/*", "assets/logo.png"]`). -- `exclude` (list[string], optionnel) : Des glob patterns pour les fichiers/répertoires à exclure (ex : `["**/*.log", "temp/"]`). Ceux-ci sont ajoutés aux exclusions par défaut si `useDefaultExcludes` est à `true`. -- `include` (list[string], optionnel) : Des glob patterns supplémentaires à inclure. Ceux-ci sont fusionnés avec `paths` (ex : `["*.test.ts"]` pour inclure spécifiquement les fichiers de test s'ils ont été globalement exclus, ou `["images/*.jpg"]` pour inclure certains types d'images). -- `recursive` (boolean, optionnel) : Indique s’il faut effectuer une recherche récursive. Cette option est principalement contrôlée par `**` dans les glob patterns. Valeur par défaut : `true`. -- `useDefaultExcludes` (boolean, optionnel) : Indique s’il faut appliquer une liste de patterns d’exclusion par défaut (ex : `node_modules`, `.git`, fichiers binaires non image/PDF). Valeur par défaut : `true`. -- `respect_git_ignore` (boolean, optionnel) : Indique s’il faut respecter les patterns définis dans le `.gitignore` lors de la recherche des fichiers. Valeur par défaut : `true`. +- `paths` (list[string], requis) : Un tableau de motifs glob ou de chemins relatifs au répertoire cible de l'outil (ex. `["src/**/*.ts"]`, `["README.md", "docs/*", "assets/logo.png"]`). +- `exclude` (list[string], optionnel) : Motifs glob pour les fichiers/répertoires à exclure (ex. `["**/*.log", "temp/"]`). Ceux-ci sont ajoutés aux exclusions par défaut si `useDefaultExcludes` est vrai. +- `include` (list[string], optionnel) : Motifs glob supplémentaires à inclure. Ceux-ci sont fusionnés avec `paths` (ex. `["*.test.ts"]` pour ajouter spécifiquement des fichiers de test s'ils ont été largement exclus, ou `["images/*.jpg"]` pour inclure des types d'images spécifiques). +- `recursive` (boolean, optionnel) : Indique s'il faut effectuer une recherche récursive. Cette fonctionnalité est principalement contrôlée par `**` dans les motifs glob. Valeur par défaut : `true`. +- `useDefaultExcludes` (boolean, optionnel) : Indique s'il faut appliquer une liste de motifs d'exclusion par défaut (ex. `node_modules`, `.git`, fichiers binaires non image/PDF). Valeur par défaut : `true`. +- `respect_git_ignore` (boolean, optionnel) : Indique s'il faut respecter les motifs définis dans le fichier .gitignore lors de la recherche des fichiers. Valeur par défaut : `true`. ## Comment utiliser `read_many_files` avec Qwen Code -`read_many_files` recherche les fichiers correspondant aux `paths` et `include` fournis, tout en respectant les patterns `exclude` et les exclusions par défaut (si activées). +`read_many_files` recherche les fichiers correspondant aux `paths` et `include` fournis, tout en respectant les motifs `exclude` et les exclusions par défaut (si activées). -- Pour les fichiers texte : il lit le contenu de chaque fichier correspondant (en tentant de sauter les fichiers binaires non explicitement demandés comme image/PDF) et les concatène en une seule chaîne, avec un séparateur `--- {filePath} ---` entre le contenu de chaque fichier. Utilise l'encodage UTF-8 par défaut. +- Pour les fichiers texte : il lit le contenu de chaque fichier trouvé (en tentant d'ignorer les fichiers binaires non explicitement demandés comme image/PDF) et les concatène dans une seule chaîne, avec un séparateur `--- {filePath} ---` entre le contenu de chaque fichier. Utilise l'encodage UTF-8 par défaut. +- L'outil insère un `--- End of content ---` après le dernier fichier. - Pour les fichiers image et PDF : si explicitement demandés par nom ou extension (ex : `paths: ["logo.png"]` ou `include: ["*.pdf"]`), l'outil lit le fichier et retourne son contenu sous forme de chaîne encodée en base64. -- L'outil tente de détecter et ignorer les autres fichiers binaires (ceux ne correspondant pas aux types image/PDF courants ou non explicitement demandés) en vérifiant la présence d'octets null dans leur contenu initial. +- L'outil tente de détecter et ignorer les autres fichiers binaires (ceux ne correspondant pas aux types image/PDF courants ou non explicitement demandés) en vérifiant la présence d'octets nuls dans leur contenu initial. Utilisation : @@ -52,7 +53,7 @@ Lire le README principal, tous les fichiers Markdown dans le répertoire `docs`, read_many_files(paths=["README.md", "docs/**/*.md", "assets/logo.png"], exclude=["docs/OLD_README.md"]) ``` -Lire tous les fichiers JavaScript mais inclure explicitement les fichiers de test et tous les JPEGs dans un dossier `images` : +Lire tous les fichiers JavaScript mais inclure explicitement les fichiers de test et tous les JPEG dans un dossier `images` : ``` read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], useDefaultExcludes=False) @@ -61,8 +62,8 @@ read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], ## Notes importantes - **Gestion des fichiers binaires :** - - **Fichiers image/PDF/audio/vidéo :** L'outil peut lire les types d'images courants (PNG, JPEG, etc.), les fichiers PDF, audio (mp3, wav) et vidéo (mp4, mov), et les retourner en tant que données encodées en base64. Ces fichiers _doivent_ être ciblés explicitement par les motifs `paths` ou `include` (par exemple, en spécifiant le nom exact du fichier comme `video.mp4` ou un motif comme `*.mov`). - - **Autres fichiers binaires :** L'outil tente de détecter et d'ignorer les autres types de fichiers binaires en examinant leur contenu initial à la recherche d'octets nuls. L'outil exclut ces fichiers de sa sortie. -- **Performance :** La lecture d'un très grand nombre de fichiers ou de fichiers individuels très volumineux peut être gourmande en ressources. + - **Fichiers image/PDF/audio/vidéo :** L'outil peut lire les types d'images courants (PNG, JPEG, etc.), les fichiers PDF, audio (mp3, wav) et vidéo (mp4, mov), en les retournant sous forme de données encodées en base64. Ces fichiers _doivent_ être explicitement ciblés par les motifs `paths` ou `include` (par exemple, en spécifiant le nom exact du fichier comme `video.mp4` ou un motif comme `*.mov`). + - **Autres fichiers binaires :** L'outil tente de détecter et d'ignorer les autres types de fichiers binaires en examinant leur contenu initial à la recherche d'octets nuls. Ces fichiers sont exclus de la sortie de l'outil. +- **Performance :** La lecture d'un très grand nombre de fichiers ou de fichiers individuels très volumineux peut consommer beaucoup de ressources. - **Spécificité des chemins :** Assurez-vous que les chemins et les motifs glob sont correctement spécifiés par rapport au répertoire cible de l'outil. Pour les fichiers image/PDF, veillez à ce que les motifs soient suffisamment précis pour les inclure. - **Exclusions par défaut :** Soyez conscient des motifs d'exclusion par défaut (comme `node_modules`, `.git`) et utilisez `useDefaultExcludes=False` si vous devez les outrepasser, mais faites-le avec prudence. \ No newline at end of file diff --git a/website/content/fr/troubleshooting.md b/website/content/fr/troubleshooting.md index f57266c6..d5c68704 100644 --- a/website/content/fr/troubleshooting.md +++ b/website/content/fr/troubleshooting.md @@ -5,19 +5,19 @@ Ce guide fournit des solutions aux problèmes courants et des conseils de débog - Erreurs d'authentification ou de connexion - Foire aux questions (FAQ) - Conseils de débogage -- Issues GitHub existants similaires au vôtre ou création de nouvelles Issues +- Issues GitHub existantes similaires à la vôtre ou création de nouvelles Issues ## Erreurs d'authentification ou de connexion - **Erreur : `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` ou `unable to get local issuer certificate`** - **Cause :** Vous êtes peut-être sur un réseau d'entreprise avec un pare-feu qui intercepte et inspecte le trafic SSL/TLS. Cela nécessite souvent qu'un certificat d'autorité de certification (CA) personnalisé soit approuvé par Node.js. - - **Solution :** Définissez la variable d'environnement `NODE_EXTRA_CA_CERTS` avec le chemin absolu vers le fichier de certificat de votre CA racine d'entreprise. - - Exemple : `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` + - **Solution :** Définissez la variable d'environnement `NODE_EXTRA_CA_CERTS` avec le chemin absolu vers votre fichier de certificat CA racine d'entreprise. + - Exemple : `export NODE_EXTRA_CA_CERTS=/chemin/vers/votre/corporate-ca.crt` ## Foire aux questions (FAQ) - **Q : Comment mettre à jour Qwen Code vers la dernière version ?** - - R : Si vous l'avez installé globalement via `npm`, mettez-le à jour avec la commande `npm install -g @qwen-code/qwen-code@latest`. Si vous l'avez compilé depuis les sources, récupérez les derniers changements depuis le repository, puis reconstruisez-le avec la commande `npm run build`. + - R : Si vous l'avez installé globalement via `npm`, mettez-le à jour avec la commande `npm install -g @qwen-code/qwen-code@latest`. Si vous l'avez compilé depuis les sources, récupérez les dernières modifications du repository, puis reconstruisez-le avec la commande `npm run build`. - **Q : Où sont stockés les fichiers de configuration ou de paramètres de Qwen Code ?** - R : La configuration de Qwen Code est stockée dans deux fichiers `settings.json` : @@ -26,8 +26,8 @@ Ce guide fournit des solutions aux problèmes courants et des conseils de débog Consultez [Configuration de Qwen Code](./cli/configuration.md) pour plus de détails. -- **Q : Pourquoi ne vois-je pas les comptages de tokens mis en cache dans la sortie des statistiques ?** - - R : Les informations sur les tokens en cache ne s'affichent que lorsque des tokens mis en cache sont utilisés. Cette fonctionnalité est disponible pour les utilisateurs avec une clé API (Qwen API key ou Google Cloud Vertex AI), mais pas pour les utilisateurs OAuth (comme les comptes Google personnels ou professionnels, par exemple Google Gmail ou Google Workspace). Cela est dû au fait que l'API Qwen Code Assist ne prend pas en charge la création de contenu mis en cache. Vous pouvez néanmoins consulter votre consommation totale de tokens à l’aide de la commande `/stats`. +- **Q : Pourquoi ne vois-je pas les nombres de tokens mis en cache dans la sortie des statistiques ?** + - R : Les informations sur les tokens mis en cache ne s'affichent que lorsque ces tokens sont effectivement utilisés. Cette fonctionnalité est disponible pour les utilisateurs avec une API key (Qwen API key ou Google Cloud Vertex AI), mais pas pour les utilisateurs OAuth (comme les comptes Google personnels ou d'entreprise, par exemple Google Gmail ou Google Workspace). Cela est dû au fait que l'API Qwen Code Assist ne prend pas en charge la création de contenu mis en cache. Vous pouvez néanmoins consulter votre consommation totale de tokens en utilisant la commande `/stats`. ## Messages d'erreur courants et solutions @@ -37,10 +37,10 @@ Ce guide fournit des solutions aux problèmes courants et des conseils de débog Arrêtez l'autre processus utilisant ce port ou configurez le serveur MCP pour utiliser un port différent. - **Erreur : Command not found (lorsque vous tentez d'exécuter Qwen Code avec `qwen`).** - - **Cause :** Le CLI n'est pas correctement installé ou il n'est pas dans le `PATH` de votre système. + - **Cause :** Le CLI n'est pas installé correctement ou il n'est pas dans le `PATH` de votre système. - **Solution :** La mise à jour dépend de la façon dont vous avez installé Qwen Code : - - Si vous avez installé `qwen` globalement, vérifiez que le répertoire des binaires globaux de `npm` est dans votre `PATH`. Vous pouvez mettre à jour avec la commande `npm install -g @qwen-code/qwen-code@latest`. + - Si vous avez installé `qwen` globalement, vérifiez que le répertoire des binaires globaux de `npm` est dans votre `PATH`. Vous pouvez le mettre à jour avec la commande `npm install -g @qwen-code/qwen-code@latest`. - Si vous exécutez `qwen` depuis les sources, assurez-vous d'utiliser la bonne commande pour l'invoquer (par exemple, `node packages/cli/dist/index.js ...`). Pour mettre à jour, récupérez les derniers changements depuis le repository, puis reconstruisez avec la commande `npm run build`. - **Erreur : `MODULE_NOT_FOUND` ou erreurs d'import.** @@ -48,7 +48,7 @@ Ce guide fournit des solutions aux problèmes courants et des conseils de débog - **Solution :** 1. Exécutez `npm install` pour vous assurer que toutes les dépendances sont présentes. 2. Exécutez `npm run build` pour compiler le projet. - 3. Vérifiez que la compilation s'est terminée avec succès avec `npm run start`. + 3. Vérifiez que la compilation s'est terminée avec succès en exécutant `npm run start`. - **Erreur : "Operation not permitted", "Permission denied", ou similaire.** - **Cause :** Lorsque le sandboxing est activé, Qwen Code peut tenter des opérations restreintes par votre configuration de sandbox, comme écrire en dehors du répertoire du projet ou du répertoire temporaire du système. @@ -70,17 +70,29 @@ Ce guide fournit des solutions aux problèmes courants et des conseils de débog - Redémarrez le terminal intégré après avoir installé l'extension pour qu'il hérite des variables : - `QWEN_CODE_IDE_WORKSPACE_PATH` - `QWEN_CODE_IDE_SERVER_PORT` -- Si vous exécutez dans un container, vérifiez que `host.docker.internal` est résolu. Sinon, mappez l'hôte correctement. +- Si vous exécutez dans un container, vérifiez que `host.docker.internal` est résolu. Sinon, mappez correctement l'hôte. - Réinstallez le companion avec `/ide install` et utilisez "Qwen Code: Run" dans la Command Palette pour vérifier qu'il se lance. +## Codes de sortie + +Qwen Code utilise des codes de sortie spécifiques pour indiquer la raison de l'arrêt. Cela est particulièrement utile pour les scripts et l'automatisation. + +| Code de sortie | Type d'erreur | Description | +| -------------- | -------------------------- | --------------------------------------------------------------------------------------------------- | +| 41 | `FatalAuthenticationError` | Une erreur s'est produite pendant le processus d'authentification. | +| 42 | `FatalInputError` | Une entrée invalide ou manquante a été fournie au CLI. (mode non-interactif uniquement) | +| 44 | `FatalSandboxError` | Une erreur s'est produite avec l'environnement de sandbox (ex. Docker, Podman, ou Seatbelt). | +| 52 | `FatalConfigError` | Un fichier de configuration (`settings.json`) est invalide ou contient des erreurs. | +| 53 | `FatalTurnLimitedError` | Le nombre maximum de tours conversationnels pour la session a été atteint. (mode non-interactif uniquement) | + ## Conseils de débogage - **Débogage CLI :** - Utilisez le flag `--verbose` (si disponible) avec les commandes CLI pour obtenir une sortie plus détaillée. - - Consultez les logs CLI, souvent situés dans un répertoire de configuration ou de cache spécifique à l'utilisateur. + - Consultez les logs du CLI, souvent situés dans un répertoire de configuration ou de cache spécifique à l'utilisateur. - **Débogage du core :** - - Vérifiez la sortie console du serveur pour repérer les messages d'erreur ou les stack traces. + - Vérifiez la sortie de la console du serveur pour repérer les messages d'erreur ou les stack traces. - Augmentez le niveau de verbosité des logs si c'est configurable. - Utilisez les outils de débogage Node.js (ex. `node --inspect`) si vous devez parcourir le code côté serveur pas à pas. @@ -90,7 +102,7 @@ Ce guide fournit des solutions aux problèmes courants et des conseils de débog - Pour les _outils de système de fichiers_, assurez-vous que les chemins sont corrects et vérifiez les permissions. - **Vérifications préalables :** - - Exécutez toujours `npm run preflight` avant de commiter du code. Cela permet de détecter de nombreuses erreurs courantes liées au formatage, au linting et aux erreurs de type. + - Exécutez toujours `npm run preflight` avant de commiter du code. Cela permet de détecter de nombreuses erreurs courantes liées au formatage, au linting et aux erreurs de types. ## Issues GitHub existants similaires au vôtre ou création de nouvelles Issues diff --git a/website/content/ja/cli/commands.md b/website/content/ja/cli/commands.md index 27eb12a0..90cc3f28 100644 --- a/website/content/ja/cli/commands.md +++ b/website/content/ja/cli/commands.md @@ -1,54 +1,53 @@ -# CLI Commands +# CLI コマンド -Qwen Code では、セッションの管理、インターフェースのカスタマイズ、およびその動作を制御するための複数の組み込みコマンドがサポートされています。これらのコマンドは、スラッシュ (`/`)、アットマーク (`@`)、または感嘆符 (`!`) を接頭辞として使用します。 +Qwen Code では、セッションの管理、インターフェースのカスタマイズ、およびその動作を制御するための複数の組み込みコマンドがサポートされています。これらのコマンドは、スラッシュ記号（`/`）、アットマーク（`@`）、または感嘆符（`!`）で始まります。 -## スラッシュコマンド (`/`) +## スラッシュコマンド（`/`） -スラッシュコマンドは、CLI 自体に対するメタレベルの制御を提供します。 +スラッシュコマンドは、CLI 自体に対するメタレベルの操作を提供します。 -```markdown ### 組み込みコマンド - **`/bug`** - - **説明:** Qwen Codeに関するissueを提出します。デフォルトでは、GitHubのQwen Codeリポジトリ内にissueが作成されます。`/bug`の後に記述した文字列が、提出されるバグのタイトルになります。`.qwen/settings.json`ファイル内の`bugCommand`設定により、デフォルトの`/bug`の動作を変更できます。 + - **説明:** Qwen Codeに関するissueを提出します。デフォルトでは、GitHubのQwen Codeリポジトリ内にissueが作成されます。`/bug`の後に記述した文字列が、提出されるバグのタイトルになります。デフォルトの`/bug`の動作は、`.qwen/settings.json`ファイル内の`bugCommand`設定で変更できます。 - **`/chat`** - - **説明:** 対話的に会話履歴を保存・再開し、分岐した会話状態を管理したり、以前のセッションから状態を再開できます。 + - **説明:** 対話的に会話履歴を保存・再開し、分岐した会話状態を維持したり、以前の状態を別のセッションから再開できます。 - **サブコマンド:** - **`save`** - **説明:** 現在の会話履歴を保存します。会話状態を識別するために``を指定する必要があります。 - **使用方法:** `/chat save ` - - **チェックポイント保存場所の詳細:** 保存されたチャットチェックポイントのデフォルト保存場所は以下の通りです： - - Linux/macOS: `~/.config/qwen-code/checkpoints/` - - Windows: `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` - - `/chat list`を実行すると、CLIはこれらのディレクトリのみをスキャンして利用可能なチェックポイントを検索します。 - - **注意:** これらのチェックポイントは、手動で会話状態を保存・再開するためのものです。ファイル変更前に自動作成されるチェックポイントについては、[Checkpointing documentation](../checkpointing.md)を参照してください。 + - **チェックポイントの保存場所に関する詳細:** 保存されたチャットチェックポイントのデフォルトの場所は以下の通りです： + - Linux/macOS: `~/.qwen/tmp//` + - Windows: `C:\Users\\.qwen\tmp\\` + - `/chat list`を実行すると、CLIはこれらの特定のディレクトリのみをスキャンして利用可能なチェックポイントを検索します。 + - **注意:** これらのチェックポイントは、手動で会話状態を保存・再開するためのものです。ファイル変更前に自動的に作成されるチェックポイントについては、[Checkpointing documentation](../checkpointing.md)を参照してください。 - **`resume`** - **説明:** 以前に保存した会話状態を再開します。 - **使用方法:** `/chat resume ` - **`list`** - - **説明:** 再開可能なチャット状態のタグ一覧を表示します。 + - **説明:** 再開可能なチャット状態のタグを一覧表示します。 - **`delete`** - **説明:** 保存された会話チェックポイントを削除します。 - **使用方法:** `/chat delete ` - **`/clear`** - - **説明:** CLI内の表示履歴とスクロールバックを含む、ターミナル画面全体をクリアします。実装によっては履歴データ自体は保持される場合がありますが、画面上の表示はクリアされます。 - - **キーボードショートカット:** いつでも**Ctrl+L**を押すことで画面をクリアできます。 + - **説明:** CLI内の表示履歴とスクロールバックを含む、ターミナル画面全体をクリアします。実装によっては履歴の元データが保持される場合がありますが、視覚的な表示はクリアされます。 + - **キーボードショートカット:** いつでも**Ctrl+L**を押すことでクリア操作を実行できます。 - **`/summary`** - **説明:** 現在の会話履歴から包括的なプロジェクトサマリーを生成し、`.qwen/PROJECT_SUMMARY.md`に保存します。このサマリーには全体の目標、重要な知識、最近のアクション、現在の計画が含まれており、将来のセッションで作業を再開するのに最適です。 - **使用方法:** `/summary` - **機能:** - - 全会話履歴を解析して重要なコンテキストを抽出 + - 全会話履歴を分析して重要なコンテキストを抽出 - 目標、知識、アクション、計画のセクションを持つ構造化されたMarkdownサマリーを作成 - プロジェクトルートの`.qwen/PROJECT_SUMMARY.md`に自動保存 - - 生成・保存中に進行状況を表示 - - セッション再開機能と統合してシームレスな再開を実現 - - **注意:** このコマンドを使用するには、最低でも2件のメッセージを含むアクティブな会話が必要です。 + - 生成および保存中に進行状況インジケーターを表示 + - Welcome Back機能と統合してシームレスなセッション再開を実現 + - **注意:** このコマンドを使用するには、最低でも2つのメッセージを含むアクティブな会話が必要です。 - **`/compress`** - - **説明:** チャットコンテキスト全体をサマリーに置き換えます。これにより、将来のタスクで使用するトークン数を削減しつつ、これまでの内容の高レベルなサマリーを保持できます。 + - **説明:** チャットコンテキスト全体をサマリーに置き換えます。これにより、将来のタスクで使用されるトークンを節約しつつ、これまでの出来事の高レベルなサマリーを保持できます。 - **`/copy`** - **説明:** Qwen Codeが最後に出力した内容をクリップボードにコピーし、共有や再利用を容易にします。 @@ -57,7 +56,7 @@ Qwen Code では、セッションの管理、インターフェースのカス - **説明:** 複数ディレクトリ対応のワークスペースディレクトリを管理します。 - **サブコマンド:** - **`add`**: - - **説明:** ワークスペースにディレクトリを追加します。パスは絶対パスまたは現在の作業ディレクトリからの相対パスを指定できます。また、ホームディレクトリからの参照もサポートされています。 + - **説明:** ワークスペースにディレクトリを追加します。パスは絶対パスでも、現在の作業ディレクトリからの相対パスでも指定できます。また、ホームディレクトリからの参照もサポートされています。 - **使用方法:** `/directory add ,` - **注意:** 制限付きサンドボックスプロファイルでは無効です。その場合、セッション開始時に`--include-directories`を使用してください。 - **`show`**: @@ -68,7 +67,7 @@ Qwen Code では、セッションの管理、インターフェースのカス - **説明:** 複数ディレクトリ対応のワークスペースディレクトリを管理します。 - **サブコマンド:** - **`add`**: - - **説明:** ワークスペースにディレクトリを追加します。パスは絶対パスまたは現在の作業ディレクトリからの相対パスを指定できます。また、ホームディレクトリからの参照もサポートされています。 + - **説明:** ワークスペースにディレクトリを追加します。パスは絶対パスでも、現在の作業ディレクトリからの相対パスでも指定できます。また、ホームディレクトリからの参照もサポートされています。 - **使用方法:** `/directory add ,` - **注意:** 制限付きサンドボックスプロファイルでは無効です。その場合、セッション開始時に`--include-directories`を使用してください。 - **`show`**: @@ -82,10 +81,10 @@ Qwen Code では、セッションの管理、インターフェースのカス - **説明:** 現在のQwen Codeセッションでアクティブなすべての拡張機能を一覧表示します。詳細は[Qwen Code Extensions](../extension.md)を参照してください。 - **`/help`** (または **`/?`**) - - **説明:** Qwen Codeで利用可能なコマンドとその使用方法を含むヘルプ情報を表示します。 + - **説明:** 利用可能なコマンドとその使用方法を含む、Qwen Codeに関するヘルプ情報を表示します。 - **`/mcp`** - - **説明:** 設定されたModel Context Protocol (MCP)サーバー、接続状況、サーバー詳細、利用可能なツールを一覧表示します。 + - **説明:** 設定されたModel Context Protocol (MCP)サーバー、その接続状態、サーバー詳細、利用可能なツールを一覧表示します。 - **サブコマンド:** - **`desc`** または **`descriptions`**: - **説明:** MCPサーバーとツールの詳細な説明を表示します。 @@ -93,115 +92,123 @@ Qwen Code では、セッションの管理、インターフェースのカス - **説明:** ツールの説明を非表示にし、ツール名のみを表示します。 - **`schema`**: - **説明:** ツールの設定パラメータの完全なJSONスキーマを表示します。 - - **キーボードショートカット:** いつでも**Ctrl+T**を押すことで、ツールの説明表示/非表示を切り替えられます。 + - **キーボードショートカット:** いつでも**Ctrl+T**を押すことで、ツールの説明の表示/非表示を切り替えられます。 - **`/memory`** - **説明:** AIの指示コンテキスト（デフォルトでは`QWEN.md`ファイルから読み込まれる階層メモリ；`contextFileName`で設定可能）を管理します。 - **サブコマンド:** - **`add`**: - - **説明:** 次のテキストをAIのメモリに追加します。使用方法: `/memory add <記憶するテキスト>` + - **説明:** 以下のテキストをAIのメモリに追加します。使用方法: `/memory add <記憶するテキスト>` - **`show`**: - **説明:** すべてのコンテキストファイル（例：`QWEN.md`）から読み込まれた現在の階層メモリの完全な内容を表示します。これにより、モデルに提供されている指示コンテキストを確認できます。 - **`refresh`**: - - **説明:** 設定された場所（グローバル、プロジェクト/祖先、サブディレクトリ）にあるすべてのコンテキストファイル（デフォルト：`QWEN.md`）から階層指示メモリを再読み込みします。これにより、モデルに最新のコンテキスト内容が反映されます。 + - **説明:** 設定された場所（グローバル、プロジェクト/祖先、サブディレクトリ）にあるすべてのコンテキストファイル（デフォルト：`QWEN.md`）から階層的な指示メモリを再読み込みします。これにより、モデルに最新のコンテキスト内容が反映されます。 - **注意:** コンテキストファイルが階層メモリにどのように寄与するかの詳細については、[CLI Configuration documentation](./configuration.md#context-files-hierarchical-instructional-context)を参照してください。 - **`/restore`** - - **説明:** ツールが実行される直前のプロジェクトファイルの状態に復元します。これは、ツールによって行われたファイル編集を元に戻すのに特に便利です。ツール呼び出しIDなしで実行した場合、復元可能なチェックポイントの一覧が表示されます。 + - **説明:** ツールが実行される直前のプロジェクトファイルの状態に復元します。これは、ツールによって行われたファイル編集を元に戻すのに特に便利です。ツール呼び出しIDなしで実行された場合、復元可能なチェックポイントの一覧が表示されます。 - **使用方法:** `/restore [tool_call_id]` - **注意:** CLIが`--checkpointing`オプションで起動された場合、または[settings](./configuration.md)で設定されている場合にのみ使用可能です。詳細は[Checkpointing documentation](../checkpointing.md)を参照してください。 - **`/settings`** - **説明:** Qwen Codeの設定を表示・変更するための設定エディタを開きます。 - - **詳細:** このコマンドは、Qwen Codeの動作と外観を制御する設定を変更するためのユーザーフレンドリーなインターフェースを提供します。`.qwen/settings.json`ファイルを手動で編集するのと同等ですが、エラーを防ぐための検証とガイダンスが含まれています。 + - **詳細:** このコマンドは、Qwen Codeの動作や外観を制御する設定を変更するためのユーザーフレンドリーなインターフェースを提供します。これは`.qwen/settings.json`ファイルを手動で編集するのと同等ですが、エラーを防ぐための検証とガイダンスが含まれています。 - **使用方法:** 単に`/settings`を実行するとエディタが開きます。そこから特定の設定を閲覧・検索し、現在の値を確認し、必要に応じて変更できます。一部の設定は即座に反映されますが、他の設定は再起動が必要です。 - **`/stats`** - - **説明:** 現在のQwen Codeセッションの詳細な統計情報を表示します。これにはトークン使用量、キャッシュされたトークンの節約量（利用可能な場合）、セッション時間などが含まれます。注意：キャッシュされたトークン情報は、APIキー認証時にトークンが使用されている場合にのみ表示され、現在のところOAuth認証では表示されません。 + - **説明:** 現在のQwen Codeセッションの詳細な統計情報を表示します。これにはトークン使用量、キャッシュされたトークンによる節約（利用可能な場合）、セッションの継続時間などが含まれます。注意：キャッシュされたトークン情報は、APIキー認証でトークンが使用されている場合にのみ表示され、現在のところOAuth認証では表示されません。 - [**`/theme`**](./themes.md) - - **説明:** Qwen Codeの視覚テーマを変更するためのダイアログを開きます。 + - **説明:** Qwen Codeの視覚的なテーマを変更するためのダイアログを開きます。 - **`/auth`** - **説明:** 認証方法を変更するためのダイアログを開きます。 +- **`/approval-mode`** + - **説明:** ツール使用の承認モードを変更します。 + - **使用方法:** `/approval-mode [mode] [--session|--project|--user]` + - **利用可能なモード:** + - **`plan`**: 分析のみ；ファイルの変更やコマンドの実行は行いません + - **`default`**: ファイル編集やシェルコマンドには承認が必要 + - **`auto-edit`**: ファイル編集を自動的に承認 + - **`yolo`**: すべてのツールを自動的に承認 + - **例:** + - `/approval-mode plan --project` (このプロジェクトでplanモードを永続化) + - `/approval-mode yolo --user` (このユーザーのYOLOモードをプロジェクト間で永続化) + - **`/about`** - **説明:** バージョン情報を表示します。issueを提出する際はこの情報を共有してください。 - **`/agents`** - - **説明:** 特定のタスクに特化したAIサブエージェントを管理します。サブエージェントは特定の専門知識とツールアクセスで構成された独立したAIアシスタントです。 + - **説明:** 特定のタスクに特化したAIサブエージェントを管理します。サブエージェントは、特定の専門知識とツールアクセスで構成された独立したAIアシスタントです。 - **サブコマンド:** - **`create`**: - - **説明:** 新しいサブエージェントを作成するためのインタラクティブウィザードを起動します。ウィザードでは場所選択、AIによるプロンプト生成、ツール選択、視覚的カスタマイズをガイドします。 + - **説明:** 新しいサブエージェントを作成するためのインタラクティブなウィザードを起動します。ウィザードでは、場所の選択、AIによるプロンプト生成、ツール選択、視覚的なカスタマイズをガイドします。 - **使用方法:** `/agents create` - **`manage`**: - **説明:** 既存のサブエージェントを表示・編集・削除するためのインタラクティブな管理ダイアログを開きます。プロジェクトレベルとユーザーレベルのエージェントの両方を表示します。 - **使用方法:** `/agents manage` - **保存場所:** - - **プロジェクトレベル:** `.qwen/agents/`（チームで共有、優先度高） - - **ユーザーレベル:** `~/.qwen/agents/`（個人用エージェント、プロジェクト間で利用可能） - - **注意:** サブエージェントの作成・管理の詳細については、[Subagents documentation](../subagents.md)を参照してください。 + - **プロジェクトレベル:** `.qwen/agents/` (チームで共有、優先される) + - **ユーザーレベル:** `~/.qwen/agents/` (個人用エージェント、プロジェクト間で利用可能) + - **注意:** サブエージェントの作成と管理の詳細については、[Subagents documentation](../subagents.md)を参照してください。 - [**`/tools`**](../tools/index.md) - - **説明:** Qwen Code内で現在利用可能なツールの一覧を表示します。 + - **説明:** 現在Qwen Code内で利用可能なツールの一覧を表示します。 + - **使用方法:** `/tools [desc]` - **サブコマンド:** - **`desc`** または **`descriptions`**: - - **説明:** 各ツールの詳細な説明を表示します。これには、モデルに提供された各ツールの名前と完全な説明が含まれます。 + - **説明:** 各ツールの詳細な説明を表示します。これには、モデルに提供される各ツールの名前と完全な説明が含まれます。 - **`nodesc`** または **`nodescriptions`**: - **説明:** ツールの説明を非表示にし、ツール名のみを表示します。 - **`/privacy`** - - **説明:** プライバシー通知を表示し、ユーザーがサービス改善のためのデータ収集に同意するかどうかを選択できるようにします。 + - **説明:** プライバシー通知を表示し、ユーザーがサービス改善の目的でデータ収集に同意するかどうかを選択できるようにします。 - **`/quit-confirm`** - **説明:** Qwen Codeを終了する前に確認ダイアログを表示し、現在のセッションをどのように処理するかを選択できるようにします。 - **使用方法:** `/quit-confirm` - **機能:** - **即時終了:** 何も保存せずに終了（`/quit`と同等） - - **サマリー生成して終了:** 終了前に`/summary`を使用してプロジェクトサマリーを作成 - - **会話を保存して終了:** 自動生成されたタグで現在の会話を保存してから終了 + - **サマリー生成後に終了:** 終了前に`/summary`を使用してプロジェクトサマリーを作成 + - **会話を保存して終了:** 現在の会話を自動生成されたタグで保存してから終了 - **キーボードショートカット:** **Ctrl+C**を2回押すことで終了確認ダイアログを起動 - - **注意:** Ctrl+Cを1回押したときに自動的にこのコマンドが起動され、誤って終了することを防ぐ安全機構が提供されます。 + - **注意:** このコマンドはCtrl+Cを1回押したときに自動的に起動され、誤って終了することを防ぐための安全機構を提供します。 - **`/quit`** (または **`/exit`**) - **説明:** 確認ダイアログなしでQwen Codeを即座に終了します。 - **`/vim`** - - **説明:** vimモードのオン/オフを切り替えます。vimモードが有効になると、入力エリアでNORMALモードとINSERTモードの両方でvimスタイルのナビゲーションと編集コマンドがサポートされます。 + - **説明:** vimモードをオンまたはオフに切り替えます。vimモードが有効な場合、入力エリアはNORMALモードとINSERTモードの両方でvimスタイルのナビゲーションと編集コマンドをサポートします。 - **機能:** - - **NORMALモード:** `h`, `j`, `k`, `l`で移動；`w`, `b`, `e`で単語単位移動；`0`, `$`, `^`で行頭/行末/非空白文字の行頭に移動；`G`（または`gg`で最初の行）で特定行に移動 + - **NORMALモード:** `h`, `j`, `k`, `l`で移動；`w`, `b`, `e`で単語単位のジャンプ；`0`, `$`, `^`で行の先頭/末尾に移動；`G`（または`gg`で最初の行）で特定の行に移動 - **INSERTモード:** 標準的なテキスト入力で、エスケープでNORMALモードに戻る - **編集コマンド:** `x`で削除、`c`で変更、`i`, `a`, `o`, `O`で挿入；`dd`, `cc`, `dw`, `cw`などの複雑な操作 - **カウントサポート:** コマンドの前に数字を付ける（例：`3h`, `5w`, `10G`） - - **最後のコマンド繰り返し:** `.`で最後の編集操作を繰り返す - - **永続設定:** Vimモードの設定は`~/.qwen/settings.json`に保存され、セッション間で復元される - - **ステータス表示:** 有効時はフッターに`[NORMAL]`または`[INSERT]`を表示 - -- **`/init`** - - **説明:** 現在のディレクトリを解析し、デフォルトでは`QWEN.md`コンテキストファイル（または`contextFileName`で指定されたファイル名）を作成します。空でないファイルが既に存在する場合は変更されません。このコマンドは空のファイルを作成し、モデルにプロジェクト固有の指示で埋めるようプロンプトを表示します。 -``` + - **最後のコマンドを繰り返す:** `.`で最後の編集操作を繰り返す + - **永続的な設定:** Vimモードの設定は`~/.qwen/settings.json`に保存され、セッション ### カスタムコマンド -すぐに始めるには、以下の[例](#example-a-pure-function-refactoring-command)を参照してください。 +クイックスタートについては、以下の[例](#example-a-pure-function-refactoring-command)を参照してください。 -カスタムコマンドを使用すると、お気に入りやよく使うプロンプトを Qwen Code 内で個人用のショートカットとして保存・再利用できます。1つのプロジェクト専用のコマンドや、すべてのプロジェクトでグローバルに利用可能なコマンドを作成でき、ワークフローを効率化し、一貫性を保つことができます。 +カスタムコマンドを使用すると、お気に入りや最もよく使うプロンプトをQwen Code内でパーソナルなショートカットとして保存・再利用できます。単一のプロジェクトに特化したコマンドや、すべてのプロジェクトでグローバルに利用可能なコマンドを作成でき、ワークフローを効率化し、一貫性を確保できます。 #### ファイルの場所と優先順位 -Qwen Code は、以下の2つの場所からコマンドを読み込み、特定の順序でロードします： +Qwen Code は以下の2つの場所からコマンドを読み込み、特定の順序でロードします： -1. **ユーザー コマンド (グローバル):** `~/.qwen/commands/` に配置されます。これらのコマンドは、作業中のすべてのプロジェクトで利用可能です。 -2. **プロジェクト コマンド (ローカル):** `/.qwen/commands/` に配置されます。これらのコマンドは現在のプロジェクト専用であり、チームと共有するためにバージョン管理に含めることができます。 +1. **ユーザー コマンド（グローバル）：** `~/.qwen/commands/` に配置されます。これらのコマンドは、作業中のすべてのプロジェクトで利用可能です。 +2. **プロジェクト コマンド（ローカル）：** `/.qwen/commands/` に配置されます。これらのコマンドは現在のプロジェクト専用であり、バージョン管理に含めてチームと共有できます。 -プロジェクトディレクトリ内のコマンドとユーザーディレクトリ内のコマンドで名前が同じ場合、**プロジェクト コマンドが常に使用されます。** これにより、プロジェクト固有のバージョンでグローバル コマンドを上書きできます。 +プロジェクトディレクトリ内のコマンドとユーザーディレクトリ内のコマンドで名前が同じ場合、**常にプロジェクト コマンドが使用されます。** これにより、プロジェクト固有のバージョンでグローバル コマンドを上書きできます。 -#### コマンド名と名前空間 +#### コマンド名とネームスペース -コマンド名は、そのファイルが存在する `commands` ディレクトリからの相対パスに基づいて決定されます。サブディレクトリを使用することで名前空間付きコマンドを作成でき、パス区切り文字（`/` または `\`）はコロン（`:`）に変換されます。 +コマンドの名前は、そのファイルが存在する `commands` ディレクトリからの相対パスに基づいて決定されます。サブディレクトリを使用することで、ネームスペース付きのコマンドを作成でき、パス区切り文字（`/` または `\`）はコロン（`:`）に変換されます。 - `~/.qwen/commands/test.toml` にあるファイルは、コマンド `/test` になります。 -- `/.qwen/commands/git/commit.toml` にあるファイルは、名前空間付きコマンド `/git:commit` になります。 +- `/.qwen/commands/git/commit.toml` にあるファイルは、ネームスペース付きコマンド `/git:commit` になります。 #### TOML ファイル形式 (v1) @@ -225,7 +232,7 @@ Qwen Code は、以下の2つの場所からコマンドを読み込み、特定 この注入の動作は、使用場所によって異なります： -**A. 生の注入（Shellコマンド外）** +**A. 生の注入（シェルコマンド外）** プロンプトの本文で使用される場合、引数はユーザーがタイプした通りに正確に注入されます。 @@ -237,14 +244,14 @@ Qwen Code は、以下の2つの場所からコマンドを読み込み、特定 # 実行方法: /git:fix "Button is misaligned" description = "与えられた問題に対する修正を生成します。" -prompt = "ここに記述された問題に対するコード修正を提供してください: {{args}}." +prompt = "ここに記述された問題に対するコード修正を提供してください: {{args}}。" ``` -モデルが受け取る内容: `ここに記述された問題に対するコード修正を提供してください: "Button is misaligned".` +モデルが受け取る内容: `ここに記述された問題に対するコード修正を提供してください: "Button is misaligned"。` -**B. Shell コマンド内での引数の使用 (`!{...}` ブロック内)** +**B. シェルコマンド内での引数の使用 (`!{...}` ブロック内)** -Shell インジェクションブロック (`!{...}`) 内で `{{args}}` を使用する場合、引数は置換前に自動的に **shell-escape** されます。これにより、Shell コマンドに安全に引数を渡すことができ、結果として生成されるコマンドが構文的に正しく、セキュアであることを保証し、コマンドインジェクションの脆弱性を防ぎます。 +シェルインジェクションブロック (`!{...}`) 内で `{{args}}` を使用する場合、引数は置換前に自動的に **shell-escaped** されます。これにより、シェルコマンドに安全に引数を渡すことができ、結果として生成されるコマンドが構文的に正しく、かつコマンドインジェクション脆弱性を防ぎながらセキュアになります。 **例 (`/grep-code.toml`):** @@ -257,40 +264,41 @@ prompt = """ """ ``` -`/grep-code It's complicated` を実行する場合: +`/grep-code It's complicated` を実行すると: -1. CLI は `{{args}}` が `!{...}` の外と内の両方で使用されていることを検出します。 +1. CLI は `{{args}}` が `!{...}` の外と内の両方で使われていることを検出します。 2. 外側: 最初の `{{args}}` はそのまま `It's complicated` に置換されます。 -3. 内側: 2番目の `{{args}}` はエスケープされたバージョンに置換されます（例：Linux では `"It's complicated"`）。 +3. 内側: 2つ目の `{{args}}` はエスケープされたバージョンに置換されます（例：Linuxでは `"It's complicated"`）。 4. 実行されるコマンドは `grep -r "It's complicated" .` になります。 -5. CLI は実行前にこの正確で安全なコマンドを確認するプロンプトを表示します。 +5. CLI はこの正確で安全なコマンドを実行前に確認を求めます。 6. 最終的な prompt が送信されます。 ``` ##### 2. デフォルトの引数処理 -あなたの `prompt` に特別なプレースホルダー `{{args}}` が含まれて**いない**場合、CLI は引数処理に対してデフォルトの動作を使用します。 +あなたの `prompt` に特別なプレースホルダー `{{args}}` が含まれて**いない**場合、CLI は引数を処理するためのデフォルトの動作を使用します。 -コマンドに引数を指定した場合（例: `/mycommand arg1`）、CLI はあなたが入力したコマンド全体をプロンプトの末尾に2つの改行で区切って追加します。これにより、モデルは元の指示とあなたが指定した具体的な引数の両方を見ることができます。 +コマンドに引数を指定した場合（例：`/mycommand arg1`）、CLI はあなたが入力したコマンド全体をプロンプトの末尾に2つの改行で区切って追加します。これにより、モデルは元の指示とあなたが提供した特定の引数の両方を見ることができます。 -引数を指定**しなかった**場合（例: `/mycommand`）、プロンプトはそのまま何も追加されずにモデルに送信されます。 +引数を指定**しなかった**場合（例：`/mycommand`）、プロンプトはそのまま何も追加されずにモデルに送信されます。 -**例 (`changelog.toml`):** +**例（`changelog.toml`）：** -この例では、モデルの役割を定義し、ユーザーの入力がどこにあるかを説明し、期待されるフォーマットと動作を指定することで、堅牢なコマンドを作成する方法を示しています。 +この例では、モデルの役割を定義し、ユーザーの入力を見つける場所を説明し、期待される形式と動作を指定することで、堅牢なコマンドを作成する方法を示しています。 ```toml # In: /.qwen/commands/changelog.toml -# 実行方法: /changelog 1.2.0 added "Support for default argument parsing." +```markdown +# 呼び出し方法: /changelog 1.2.0 added "デフォルト引数解析のサポート" description = "プロジェクトの CHANGELOG.md ファイルに新しいエントリを追加します。" prompt = """ # タスク: Changelog の更新 -あなたはこのソフトウェアプロジェクトの経験豊富なメンテナーです。ユーザーが changelog に新しいエントリを追加するコマンドを実行しました。 +あなたはこのソフトウェアプロジェクトのエキスパートメンテナーです。ユーザーが changelog に新しいエントリを追加するコマンドを実行しました。 **ユーザーの生のコマンドが以下の指示の後に追加されています。** @@ -299,35 +307,36 @@ prompt = """ ## 期待されるフォーマット コマンドは以下のフォーマットに従います: `/changelog ` - `` は以下のいずれかでなければなりません: "added", "changed", "fixed", "removed"。 +``` ```markdown ## 挙動 1. `CHANGELOG.md` ファイルを読み込む。 2. 指定された `` のセクションを探す。 3. 正しい `` 見出しの下に `` を追加する。 -4. バージョンまたはタイプのセクションが存在しない場合は、新しく作成する。 +4. バージョンまたはタイプのセクションが存在しない場合は、新たに作成する。 5. "Keep a Changelog" 形式に厳密に従う。 -/changelog 1.2.0 added "New feature" を実行すると、モデルに送信される最終的なテキストは、元のプロンプトに続けて2つの改行と入力したコマンドになります。 +/changelog 1.2.0 added "New feature" を実行すると、モデルに送信される最終的なテキストは、元のプロンプトに続けて2つの改行と入力したコマンドとなる。 ``` ##### 3. `!{...}` を使用した Shell コマンドの実行 `prompt` 内で直接 Shell コマンドを実行し、その出力を注入することで、コマンドを動的にすることができます。これは、ファイルの内容を読み込んだり、Git のステータスを確認したりといったローカル環境からのコンテキスト収集に最適です。 -カスタムコマンドが Shell コマンドの実行を試みると、Qwen Code は処理を進める前に確認ダイアログを表示するようになりました。これは意図しないコマンドが実行されないようにするためのセキュリティ対策です。 +カスタムコマンドが Shell コマンドの実行を試みると、Qwen Code は処理を進める前に確認ダイアログを表示するようになりました。これは意図しないコマンドが実行されてしまうことを防ぐためのセキュリティ対策です。 **仕組み:** 1. **コマンドの注入:** `!{...}` 構文を使用します。 -2. **引数の置換:** ブロック内で `{{args}}` が存在する場合、自動的に Shell エスケープされます（上記の [Context-Aware Injection](#1-context-aware-injection-with-args) を参照）。 -3. **堅牢なパース:** パーサーは、JSON ペイロードを含む複雑な Shell コマンドも正しく処理できます。 +2. **引数の置換:** ブロック内で `{{args}}` が使われている場合、自動的に Shell エスケープされます（上記の [Context-Aware Injection](#1-context-aware-injection-with-args) を参照）。 +3. **堅牢なパース:** パーサーは、JSON ペイロードを含む複雑な Shell コマンドも正しく処理できます。**注意:** `!{...}` 内の内容は、括弧（`{` と `}`）がバランスよく閉じている必要があります。もし、対応が取れていない括弧を含むコマンドを実行したい場合は、外部スクリプトファイルにまとめて、そのスクリプトを `!{...}` ブロック内で呼び出すことを検討してください。 4. **セキュリティチェックと確認:** CLI は、引数がエスケープ・置換された後の最終コマンドに対してセキュリティチェックを実施します。実行されるコマンドを正確に表示するダイアログが表示されます。 -5. **実行とエラー報告:** コマンドが実行されます。コマンドが失敗した場合、プロンプトに注入される出力にはエラーメッセージ（stderr）と、例えば `[Shell command exited with code 1]` のようなステータス行が含まれます。これにより、モデルはエラーのコンテキストを理解できます。 +5. **実行とエラー報告:** コマンドが実行されます。コマンドが失敗した場合、プロンプトに注入される出力にはエラーメッセージ（stderr）と、例えば `[Shell command exited with code 1]` のようなステータス行が含まれます。これにより、モデルはエラー発生時の状況を理解しやすくなります。 **例 (`git/commit.toml`):** -このコマンドは、ステージングされた Git の diff を取得し、それを使用してモデルにコミットメッセージを作成させます。 +このコマンドは、ステージングされた Git の diff を取得し、それを元にモデルにコミットメッセージを作成させます。 ````toml @@ -335,11 +344,11 @@ prompt = """ # Invoked via: /git:commit -description = "ステージされた変更に基づいて Git commit メッセージを生成します。" +description = "ステージされた変更に基づいて Git のコミットメッセージを生成します。" -# prompt では !{...} を使用してコマンドを実行し、その出力を挿入します。 +# プロンプトでは !{...} を使用してコマンドを実行し、その出力を挿入しています。 prompt = """ -以下の git diff に基づいて、Conventional Commit メッセージを生成してください: +以下の git diff に基づいて Conventional Commit メッセージを生成してください： ```diff !{git diff --staged} @@ -347,11 +356,51 @@ prompt = """ """ +```` + +`/git:commit` を実行すると、CLI はまず `git diff --staged` を実行し、次に `!{git diff --staged}` をそのコマンドの出力で置換してから、最終的な完全なプロンプトをモデルに送信します。 + +##### 4. `@{...}` によるファイル内容の注入 + +`@{...}` 構文を使用して、ファイルの内容やディレクトリのリストを直接プロンプトに埋め込むことができます。これは、特定のファイルを操作するコマンドを作成する際に便利です。 + +**動作方法:** + +- **ファイルの注入**: `@{path/to/file.txt}` は `file.txt` の内容に置き換えられます。 +- **マルチモーダル対応**: パスが対応する画像（例: PNG、JPEG）、PDF、音声、動画ファイルを指している場合、適切にエンコードされてマルチモーダル入力として注入されます。その他のバイナリファイルは適切に処理され、スキップされます。 +- **ディレクトリリスト**: `@{path/to/dir}` は再帰的に探索され、そのディレクトリおよびすべてのサブディレクトリ内にある各ファイルがプロンプトに挿入されます。`.gitignore` および `.qwenignore` が有効な場合、これらは尊重されます。 +- **ワークスペース対応**: コマンドは現在のディレクトリおよびその他のワークスペースディレクトリからパスを検索します。ワークスペース内であれば絶対パスも使用可能です。 +- **処理順序**: `@{...}` によるファイル内容の注入は、シェルコマンド（`!{...}`）や引数の置換（`{{args}}`）より**前**に処理されます。 +- **パース**: パーサーは `@{...}` 内の内容（パス）が対応する括弧（`{` と `}`）を持っていることを要求します。 + +**例 (`review.toml`):** + +このコマンドは、**固定された**ベストプラクティスファイル（`docs/best-practices.md`）の内容を注入し、ユーザーの引数を使用してレビューのコンテキストを提供します。 + +```toml + +```markdown +# 位置: /.qwen/commands/review.toml + +# 呼び出し方法: /review FileCommandLoader.ts + +description = "提供されたコンテキストをベストプラクティスガイドを使ってレビューします。" +prompt = """ +あなたはエキスパートコードレビュアーです。 + +あなたのタスクは {{args}} をレビューすることです。 + +レビューを行う際には、以下のベストプラクティスを使用してください： + +@{docs/best-practices.md} +""" ``` -/git:commit を実行すると、CLI はまず `git diff --staged` を実行し、次に `!{git diff --staged}` をそのコマンドの出力に置き換えて、最終的な完全な prompt をモデルに送信します。 +`/review FileCommandLoader.ts` を実行すると、`@{docs/best-practices.md}` のプレースホルダーがそのファイルの内容に置き換えられ、`{{args}}` はあなたが提供したテキストに置き換えられます。その後、最終的なプロンプトがモデルに送信されます。 -#### 例: 「純粋関数」リファクタリングコマンド +--- + +#### 例: 「Pure Function」リファクタリングコマンド コードの一部をリファクタリングするようモデルに指示するグローバルコマンドを作成してみましょう。 @@ -375,75 +424,75 @@ touch ~/.qwen/commands/refactor/pure.toml ```markdown # このコマンドは以下のように実行されます: /refactor:pure -description = "現在のコンテキストにあるコードを、純粋関数（pure function）にリファクタリングするようモデルに指示します。" +description = "現在のコンテキストにあるコードを、純粋関数にリファクタリングするようモデルに指示します。" prompt = """ -現在のコンテキストで提供されているコードを分析してください。 +提供された現在のコンテキスト内のコードを分析してください。 それを純粋関数にリファクタリングしてください。 あなたのレスポンスには以下を含めてください: 1. リファクタリングされた純粋関数のコードブロック。 -2. あなたが加えた主要な変更点と、それが純粋性にどう貢献するかの簡単な説明。 +2. 純粋性にどのように寄与するかという観点から、行った主要な変更とその理由の簡単な説明。 """ ``` -**3. コマンドを実行する:** +**3. コマンドを実行:** -以上です！CLIでコマンドを実行できるようになりました。まずコンテキストにファイルを追加し、それからコマンドを実行してください: +以上です！CLIでコマンドを実行できるようになりました。まずコンテキストにファイルを追加し、それからコマンドを呼び出してください: ``` > @my-messy-function.js > /refactor:pure ``` -Qwen Codeは、TOMLファイルで定義された複数行のプロンプトを実行します。 +Qwen Code は、TOMLファイルで定義した複数行のプロンプトを実行します。 ``` ## At コマンド (`@`) -At コマンドは、ファイルやディレクトリの内容をプロンプトの一部としてモデルに渡すために使用されます。これらのコマンドには Git を意識したフィルタリング機能が含まれています。 +At コマンドは、ファイルやディレクトリの内容をプロンプトに含めるために使用されます。これらのコマンドには Git を意識したフィルタリング機能が含まれています。 -- **`@`** - - **説明:** 指定したファイルまたは複数のファイルの内容を現在のプロンプトに挿入します。特定のコードやテキスト、ファイル群について質問する際に便利です。 +- **`@<ファイルまたはディレクトリへのパス>`** + - **説明:** 指定されたファイルまたは複数のファイルの内容を現在のプロンプトに挿入します。特定のコードやテキスト、あるいはファイル群について質問する際に便利です。 - **例:** - - `@path/to/your/file.txt Explain this text.` - - `@src/my_project/ Summarize the code in this directory.` - - `What is this file about? @README.md` + - `@path/to/your/file.txt このテキストを説明してください。` + - `@src/my_project/ このディレクトリ内のコードを要約してください。` + - `このファイルは何についてですか？ @README.md` - **詳細:** - 単一のファイルパスが指定された場合、そのファイルの内容が読み込まれます。 - - ディレクトリパスが指定された場合、そのディレクトリおよびサブディレクトリ内のファイル内容を読み込もうとします。 - - パスにスペースが含まれる場合は、バックスラッシュでエスケープしてください（例: `@My\ Documents/file.txt`）。 - - 内部的には `read_many_files` ツールを使用しています。内容が取得された後、クエリに挿入されてからモデルに送信されます。 - - **Git を意識したフィルタリング:** デフォルトでは、Git で無視されるファイル（`node_modules/`、`dist/`、`.env`、`.git/` など）は除外されます。この動作は `fileFiltering` 設定で変更可能です。 - - **ファイルタイプ:** このコマンドは主にテキストベースのファイルを対象としています。バイナリファイルや非常に大きなファイルは、パフォーマンスと関連性を保つために、`read_many_files` ツールによってスキップまたは切り捨てられることがあります。ツールはファイルがスキップされた場合にその旨を示します。 - - **出力:** CLI には `read_many_files` が使用されたことを示すツール呼び出しメッセージと、処理されたパスおよびステータスの詳細が表示されます。 + - ディレクトリパスが指定された場合、そのディレクトリおよびサブディレクトリ内のファイルの内容を読み込もうとします。 + - パスにスペースが含まれる場合は、バックスラッシュでエスケープする必要があります（例: `@My\ Documents/file.txt`）。 + - 内部的には `read_many_files` ツールを使用しています。内容が取得され、クエリに挿入されてからモデルに送信されます。 + - **Git 対応フィルタリング:** デフォルトでは、Git で無視されるファイル（`node_modules/`、`dist/`、`.env`、`.git/` など）は除外されます。この動作は `fileFiltering` 設定で変更できます。 + - **ファイル形式:** このコマンドは主にテキストベースのファイルを対象としています。バイナリファイルや非常に大きなファイルは、パフォーマンスと関連性を保つため、`read_many_files` ツールによってスキップまたは切り捨てられる可能性があります。ツール側でファイルがスキップされたかどうかは表示されます。 + - **出力:** CLI 上では、`read_many_files` が使用されたことを示すツール呼び出しメッセージと、処理されたパスおよびステータスの詳細が表示されます。 - **`@`（単独の @ 記号）** - - **説明:** パスなしで単独の `@` 記号を入力した場合、クエリはそのままモデルに渡されます。プロンプト内で `@` 記号そのものについて話す場合に便利です。 + - **説明:** パスなしで単独の `@` 記号を入力した場合、クエリはそのままモデルに渡されます。プロンプト内で `@` 記号自体について話したいケースで役立つかもしれません。 ### `@` コマンドのエラーハンドリング - `@` の後に指定されたパスが見つからない、または無効な場合、エラーメッセージが表示され、クエリはモデルに送信されないか、ファイル内容なしで送信されることがあります。 - `read_many_files` ツールがエラー（例：権限の問題）に遭遇した場合も、その旨が報告されます。 -## Shell モードとパススルー コマンド (`!`) +## Shell モードとパススルー コマンド（`!`） `!` プレフィックスを使用すると、Qwen Code 内から直接システムのシェルとやり取りできます。 - **`!`** - - **説明:** Linux/macOS では `bash`、Windows では `cmd.exe` を使用して、指定された `` を実行します。コマンドの出力やエラーはすべてターミナルに表示されます。 - - **例:** - - `!ls -la` (`ls -la` を実行し、Qwen Code に戻る) - - `!git status` (`git status` を実行し、Qwen Code に戻る) - -- **`!` (Shell モードの切り替え)** - - **説明:** `!` のみを入力すると、Shell モードが切り替わります。 - - **Shell モードに入る:** - - 有効になると、Shell モードでは別のカラー表示と「Shell モードインジケーター」が使用されます。 - - Shell モード中は、入力したテキストが直接シェルコマンドとして解釈されます。 - - **Shell モードを抜ける:** - - 抜けると、UI は標準の外観に戻り、通常の Qwen Code の動作が再開されます。 - -- **すべての `!` 使用時の注意:** Shell モードで実行するコマンドは、ターミナルで直接実行する場合と同じ権限と影響を持ちます。 - -- **環境変数:** `!` 経由または Shell モードでコマンドが実行される際、サブプロセスの環境には `QWEN_CODE=1` という環境変数が設定されます。これにより、スクリプトやツールが CLI 内から実行されているかどうかを検出できます。 \ No newline at end of file + - **説明：** 指定した `` を、Linux/macOS では `bash`、Windows では `cmd.exe` を使用して実行します。コマンドからの出力やエラーはすべてターミナルに表示されます。 + - **例：** + - `!ls -la` （`ls -la` を実行し、Qwen Code に戻る） + - `!git status` （`git status` を実行し、Qwen Code に戻る） + +- **`!`（Shell モードの切り替え）** + - **説明：** 単独で `!` と入力すると、Shell モードを切り替えます。 + - **Shell モードに入る：** + - 有効になると、Shell モードでは色分けが異なり、「Shell モードインジケーター」が表示されます。 + - Shell モード中に入力したテキストは、そのままシェル コマンドとして解釈されます。 + - **Shell モードを抜ける：** + - 抜けると UI は標準の外観に戻り、通常の Qwen Code の動作に戻ります。 + +- **すべての `!` 使用時の注意点：** Shell モードで実行するコマンドは、ターミナルで直接実行する場合と同じ権限と影響を持ちます。 + +- **環境変数：** `!` 経由または Shell モードでコマンドが実行される際、サブプロセスの環境には `QWEN_CODE=1` 環境変数が設定されます。これにより、スクリプトやツールが CLI 内から実行されているかどうかを検出できます。 \ No newline at end of file diff --git a/website/content/ja/cli/configuration.md b/website/content/ja/cli/configuration.md index dd38f330..fbec8f72 100644 --- a/website/content/ja/cli/configuration.md +++ b/website/content/ja/cli/configuration.md @@ -4,37 +4,47 @@ Qwen Code では、動作を設定する方法がいくつか用意されてい ## 設定の優先順位 -設定は以下の優先順位に従って適用されます（数字が小さいほど優先度が低く、大きいものに上書きされます）： +設定は以下の優先順位に従って適用されます（数字が小さいものほど優先度が低く、大きいものに上書きされます）： -1. **デフォルト値:** アプリケーション内にハードコードされたデフォルト値。 -2. **ユーザー設定ファイル:** 現在のユーザー向けのグローバル設定。 -3. **プロジェクト設定ファイル:** プロジェクト固有の設定。 -4. **システム設定ファイル:** システム全体に適用される設定。 -5. **環境変数:** システム全体またはセッション固有の変数。`.env` ファイルから読み込まれる場合もあります。 -6. **コマンドライン引数:** CLI 起動時に渡される値。 +1. **Default values:** アプリケーション内にハードコードされたデフォルト値。 +2. **System defaults file:** 他の設定ファイルで上書き可能な、システム全体のデフォルト設定。 +3. **User settings file:** 現在のユーザー向けのグローバル設定。 +4. **Project settings file:** プロジェクト固有の設定。 +5. **System settings file:** すべての他の設定ファイルを上書きする、システム全体の設定。 +6. **Environment variables:** システム全体またはセッション固有の変数。`.env` ファイルから読み込まれる場合もあります。 +7. **Command-line arguments:** CLI 起動時に渡される値。 ## 設定ファイル -Qwen Code は永続的な設定のために `settings.json` ファイルを使用します。このファイルの配置場所は次の3つです： +Qwen Code は JSON 設定ファイルを使用して、永続的な設定を管理します。設定ファイルは以下の4つの場所に配置できます： + +- **システムデフォルトファイル:** + - **場所:** `/etc/qwen-code/system-defaults.json` (Linux)、`C:\ProgramData\qwen-code\system-defaults.json` (Windows)、または `/Library/Application Support/QwenCode/system-defaults.json` (macOS)。このパスは、環境変数 `QWEN_CODE_SYSTEM_DEFAULTS_PATH` を使用して上書きできます。 + - **スコープ:** システム全体のデフォルト設定のベースレイヤーを提供します。これらの設定は最も低い優先度を持ち、ユーザー設定、プロジェクト設定、またはシステムオーバーライド設定によって上書きされることを想定しています。 - **ユーザー設定ファイル:** - - **場所:** `~/.qwen/settings.json`（`~` はホームディレクトリ） - - **適用範囲:** 現在のユーザーのすべての Qwen Code セッションに適用されます。 + - **場所:** `~/.qwen/settings.json`（`~` はホームディレクトリ）。 + - **スコープ:** 現在のユーザーのすべての Qwen Code セッションに適用されます。 + - **プロジェクト設定ファイル:** - - **場所:** プロジェクトのルートディレクトリ内の `.qwen/settings.json` - - **適用範囲:** その特定のプロジェクトから Qwen Code を実行するときのみ適用されます。プロジェクト設定はユーザー設定より優先されます。 + - **場所:** プロジェクトのルートディレクトリ内の `.qwen/settings.json`。 + - **スコープ:** 特定のプロジェクトから Qwen Code を実行する場合にのみ適用されます。プロジェクト設定はユーザー設定を上書きします。 - **システム設定ファイル:** - - **場所:** `/etc/qwen-code/settings.json`（Linux）、`C:\ProgramData\qwen-code\settings.json`（Windows）または `/Library/Application Support/QwenCode/settings.json`（macOS）。パスは環境変数 `QWEN_CODE_SYSTEM_SETTINGS_PATH` で上書きできます。 - - **適用範囲:** システム上のすべてのユーザーの Qwen Code セッションに適用されます。システム設定はユーザー設定およびプロジェクト設定より優先されます。エンタープライズ環境でシステム管理者がユーザーの Qwen Code 環境を一元管理したい場合に便利です。 + - **場所:** `/etc/qwen-code/settings.json` (Linux)、`C:\ProgramData\qwen-code\settings.json` (Windows)、または `/Library/Application Support/QwenCode/settings.json` (macOS)。このパスは、環境変数 `QWEN_CODE_SYSTEM_SETTINGS_PATH` を使用して上書きできます。 + - **スコープ:** システム上のすべてのユーザーに対して、すべての Qwen Code セッションに適用されます。システム設定はユーザー設定およびプロジェクト設定を上書きします。エンタープライズ環境のシステム管理者が、ユーザーの Qwen Code 環境を一元管理する際に役立ちます。 -**設定における環境変数についての注意:** `settings.json` ファイル内の文字列値では、`$VAR_NAME` または `${VAR_NAME}` 構文を使って環境変数を参照できます。これらの変数は設定読み込み時に自動的に解決されます。例えば、環境変数 `MY_API_TOKEN` がある場合、次のように `settings.json` で使用できます：`"apiKey": "$MY_API_TOKEN"`。 +**設定における環境変数についての注意:** `settings.json` ファイル内の文字列値では、`$VAR_NAME` または `${VAR_NAME}` の構文を使って環境変数を参照できます。これらの変数は、設定が読み込まれる際に自動的に解決されます。例えば、環境変数 `MY_API_TOKEN` がある場合、次のように `settings.json` 内で使用できます： + +```json +"apiKey": "$MY_API_TOKEN" +``` ### プロジェクト内の `.qwen` ディレクトリ -プロジェクト設定ファイルに加えて、プロジェクトの `.qwen` ディレクトリには、Qwen Code の動作に関連するその他のプロジェクト固有のファイルを含めることができます。例: +プロジェクト設定ファイルに加えて、プロジェクトの `.qwen` ディレクトリには、Qwen Code の動作に関連するその他のプロジェクト固有のファイルを含めることができます。例えば： -- [カスタムサンドボックスプロファイル](#sandboxing) (例: `.qwen/sandbox-macos-custom.sb`、`.qwen/sandbox.Dockerfile`) +- [カスタムサンドボックスプロファイル](#sandboxing)（例：`.qwen/sandbox-macos-custom.sb`、`.qwen/sandbox.Dockerfile`）など。 ### `settings.json` で利用可能な設定: @@ -43,11 +53,11 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 - **デフォルト:** `QWEN.md` - **例:** `"contextFileName": "AGENTS.md"` -- **`bugCommand`** (オブジェクト): - - **説明:** `/bug` コマンドのデフォルトURLを上書きします。 +- **`bugCommand`** (object): + - **説明:** `/bug` コマンドで使用されるデフォルトの URL を上書きします。 - **デフォルト:** `"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"` - **プロパティ:** - - **`urlTemplate`** (文字列): `{title}` および `{info}` プレースホルダーを含むことができるURL。 + - **`urlTemplate`** (string): `{title}` および `{info}` プレースホルダーを含むことができる URL。 - **例:** ```json "bugCommand": { @@ -55,93 +65,110 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 } ``` -- **`fileFiltering`** (オブジェクト): - - **説明:** @ コマンドやファイル検出ツールにおける git-aware なファイルフィルタリングの動作を制御します。 +- **`fileFiltering`** (object): + - **説明:** @ コマンドやファイル検出ツールにおける git を意識したファイルフィルタリングの動作を制御します。 - **デフォルト:** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` - **プロパティ:** - - **`respectGitIgnore`** (boolean): ファイル検出時に .gitignore のパターンを尊重するかどうか。`true` に設定すると、git で無視されたファイル（`node_modules/`, `dist/`, `.env` など）は @ コマンドやファイルリスト操作から自動的に除外されます。 - - **`enableRecursiveFileSearch`** (boolean): プロンプトで @ プレフィックスを補完する際に、現在のツリー配下のファイル名を再帰的に検索するかどうか。 + - **`respectGitIgnore`** (boolean): ファイル検出時に .gitignore のパターンを尊重するかどうか。`true` に設定すると、git で無視されたファイル（例: `node_modules/`, `dist/`, `.env`）は @ コマンドやファイル一覧操作から自動的に除外されます。 + - **`enableRecursiveFileSearch`** (boolean): プロンプトで @ プレフィックスの補完中に、現在のディレクトリツリー以下を再帰的に探索するかどうか。 + - **`disableFuzzySearch`** (boolean): `true` に設定すると、ファイル検索時のファジー検索機能を無効にします。これにより、ファイル数の多いプロジェクトでのパフォーマンスが向上する可能性があります。 - **例:** ```json "fileFiltering": { "respectGitIgnore": true, - "enableRecursiveFileSearch": false + "enableRecursiveFileSearch": false, + "disableFuzzySearch": true } ``` +### ファイル検索パフォーマンスのトラブルシューティング + +ファイル検索（例：`@` 補完）でパフォーマンスの問題が発生している場合、特に非常に多くのファイルを持つプロジェクトで問題が起きやすいです。以下に、推奨順に試してみるべき対策をいくつか紹介します： + +1. **`.qwenignore` を使用する：** プロジェクトのルートに `.qwenignore` ファイルを作成し、参照する必要がない大量のファイルを含むディレクトリ（例：ビルド成果物、ログ、`node_modules`）を除外します。クロール対象のファイル数を減らすことが、パフォーマンス向上の最も効果的な方法です。 + +2. **ファジー検索を無効にする：** ファイルを無視するだけでは不十分な場合、`settings.json` ファイルで `disableFuzzySearch` を `true` に設定してファジー検索を無効にできます。これにより、シンプルなファジーでないマッチングアルゴリズムが使用され、高速化される場合があります。 + +3. **再帰的なファイル検索を無効にする：** 最後の手段として、`enableRecursiveFileSearch` を `false` に設定して、再帰的なファイル検索を完全に無効にできます。これにより、プロジェクト全体の再帰的なクロールを回避するため、最も高速なオプションになります。ただし、`@` 補完を使用する際にはファイルのフルパスを入力する必要があるため、注意が必要です。 + - **`coreTools`** (文字列の配列): - - **説明:** モデルで利用可能にするコアツール名のリストを指定できます。これにより、組み込みツールのセットを制限できます。コアツールの一覧については [Built-in Tools](../core/tools-api.md#built-in-tools) を参照してください。また、`ShellTool` のように対応しているツールについては、コマンド単位での制限を指定できます。例: `"coreTools": ["ShellTool(ls -l)"]` は `ls -l` コマンドのみを許可します。 - - **デフォルト:** モデルで利用可能なすべてのツール。 - - **例:** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]` + - **説明:** モデルで使用可能にするコアツール名のリストを指定できます。これにより、組み込みツールのセットを制限できます。コアツールの一覧については [Built-in Tools](../core/tools-api.md#built-in-tools) を参照してください。また、`ShellTool` のように対応しているツールについては、コマンド単位での制限を指定できます。例：`"coreTools": ["ShellTool(ls -l)"]` とすると、`ls -l` コマンドのみが実行可能になります。 + - **デフォルト:** モデルで使用可能なすべてのツール。 + - **例:** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`。 + +- **`allowedTools`** (文字列の配列): + - **デフォルト:** `undefined` + - **説明:** 確認ダイアログをバイパスするツール名のリストです。頻繁に使用する信頼できるツールに便利です。マッチングの仕組みは `coreTools` と同じです。 + - **例:** `"allowedTools": ["ShellTool(git status)"]`。 - **`excludeTools`** (文字列の配列): - - **説明:** モデルから除外するコアツール名のリストを指定できます。`excludeTools` と `coreTools` の両方に記載されたツールは除外されます。`ShellTool` のように対応しているツールについては、コマンド単位での制限を指定できます。例: `"excludeTools": ["ShellTool(rm -rf)"]` は `rm -rf` コマンドをブロックします。 + - **説明:** モデルから除外するコアツール名のリストを指定できます。`excludeTools` と `coreTools` の両方に記載されたツールは除外されます。また、`ShellTool` のように対応しているツールについては、コマンド単位での制限を指定できます。例：`"excludeTools": ["ShellTool(rm -rf)"]` とすると、`rm -rf` コマンドがブロックされます。 - **デフォルト:** 除外されるツールはありません。 - - **例:** `"excludeTools": ["run_shell_command", "findFiles"]` - - **セキュリティに関する注意:** `excludeTools` における `run_shell_command` のコマンド単位の制限は、単純な文字列マッチに基づいているため、簡単に回避可能です。この機能は**セキュリティメカニズムではありません**。信頼できないコードを安全に実行するためにこの機能に依存しないでください。実行可能なコマンドを明示的に選択するには `coreTools` を使用することを推奨します。 + - **例:** `"excludeTools": ["run_shell_command", "findFiles"]`。 + - **セキュリティに関する注意:** `run_shell_command` の `excludeTools` におけるコマンド単位の制限は、単純な文字列マッチに基づいているため、簡単にバイパス可能です。この機能は**セキュリティメカニズムではない**ため、信頼できないコードを安全に実行するために依存すべきではありません。実行可能なコマンドを明示的に選択するには、`coreTools` を使用することを推奨します。 - **`allowMCPServers`** (文字列の配列): - - **説明:** モデルで利用可能にする MCP サーバー名のリストを指定できます。これにより、接続する MCP サーバーのセットを制限できます。`--allowed-mcp-server-names` が設定されている場合、この設定は無視されます。 - - **デフォルト:** モデルで利用可能なすべての MCP サーバー。 - - **例:** `"allowMCPServers": ["myPythonServer"]` - - **セキュリティに関する注意:** この設定は MCP サーバー名の単純な文字列マッチを使用しており、変更可能です。ユーザーによるバイパスを防ぎたいシステム管理者は、システム設定レベルで `mcpServers` を構成し、ユーザーが独自の MCP サーバーを設定できないようにすることを検討してください。これは堅牢なセキュリティメカニズムとして使用すべきではありません。 + - **説明:** モデルで使用可能にする MCP サーバー名のリストを指定できます。これにより、接続する MCP サーバーのセットを制限できます。`--allowed-mcp-server-names` が設定されている場合、この設定は無視されます。 + - **デフォルト:** モデルで使用可能なすべての MCP サーバー。 + - **例:** `"allowMCPServers": ["myPythonServer"]`。 + - **セキュリティに関する注意:** MCP サーバー名の単純な文字列マッチを使用しており、変更可能です。ユーザーによるバイパスを防ぎたいシステム管理者は、システム設定レベルで `mcpServers` を構成し、ユーザーが独自の MCP サーバーを設定できないようにすることを検討してください。これは堅牢なセキュリティメカニズムとしては使用しないでください。 - **`excludeMCPServers`** (文字列の配列): - **説明:** モデルから除外する MCP サーバー名のリストを指定できます。`excludeMCPServers` と `allowMCPServers` の両方に記載されたサーバーは除外されます。`--allowed-mcp-server-names` が設定されている場合、この設定は無視されます。 - **デフォルト:** 除外される MCP サーバーはありません。 - - **例:** `"excludeMCPServers": ["myNodeServer"]` - - **セキュリティに関する注意:** この設定は MCP サーバー名の単純な文字列マッチを使用しており、変更可能です。ユーザーによるバイパスを防ぎたいシステム管理者は、システム設定レベルで `mcpServers` を構成し、ユーザーが独自の MCP サーバーを設定できないようにすることを検討してください。これは堅牢なセキュリティメカニズムとして使用すべきではありません。 + - **例:** `"excludeMCPServers": ["myNodeServer"]`。 + - **セキュリティに関する注意:** MCP サーバー名の単純な文字列マッチを使用しており、変更可能です。ユーザーによるバイパスを防ぎたいシステム管理者は、システム設定レベルで `mcpServers` を構成し、ユーザーが独自の MCP サーバーを設定できないようにすることを検討してください。これは堅牢なセキュリティメカニズムとしては使用しないでください。 - **`autoAccept`** (boolean): - - **説明:** CLI が安全と見なされるツール呼び出し（例: 読み取り専用操作）を、ユーザーの明示的な確認なしに自動的に受け入れて実行するかどうかを制御します。`true` に設定すると、CLI は安全と判断されたツールに対して確認プロンプトをスキップします。 + - **説明:** CLI が安全と判断されるツール呼び出し（例：読み取り専用操作）を、明示的なユーザー確認なしに自動的に受け入れて実行するかどうかを制御します。`true` に設定すると、CLI は安全と判断されたツールの確認プロンプトをバイパスします。 - **デフォルト:** `false` - **例:** `"autoAccept": true` -- **`theme`** (文字列): +- **`theme`** (string): - **説明:** Qwen Code の視覚的な [テーマ](./themes.md) を設定します。 - **デフォルト:** `"Default"` - **例:** `"theme": "GitHub"` - **`vimMode`** (boolean): - - **説明:** 入力編集用の vim モードを有効または無効にします。有効にすると、入力エリアで vim スタイルのナビゲーションおよび編集コマンド（NORMAL モードと INSERT モード）がサポートされます。vim モードの状態はフッターに表示され、セッション間で保持されます。 + - **説明:** 入力編集用の vim モードを有効または無効にします。有効にすると、入力エリアで vim スタイルのナビゲーションと編集コマンド（NORMAL モードと INSERT モード）がサポートされます。vim モードの状態はフッターに表示され、セッション間で保持されます。 - **デフォルト:** `false` - **例:** `"vimMode": true` -- **`sandbox`** (boolean または文字列): +- **`sandbox`** (boolean または string): - **説明:** ツール実行時のサンドボックスの使用方法を制御します。`true` に設定すると、Qwen Code は事前にビルドされた `qwen-code-sandbox` Docker イメージを使用します。詳細については [Sandboxing](#sandboxing) を参照してください。 - **デフォルト:** `false` - **例:** `"sandbox": "docker"` -- **`toolDiscoveryCommand`** (文字列): - - **説明:** プロジェクトからツールを検出するためのカスタムシェルコマンドを定義します。シェルコマンドは `stdout` に [function declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) の JSON 配列を返す必要があります。ツールラッパーはオプションです。 +- **`toolDiscoveryCommand`** (string): + - **説明:** **Gemini CLI と連携。** プロジェクトからツールを検出するためのカスタムシェルコマンドを定義します。シェルコマンドは `stdout` に [function declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) の JSON 配列を返す必要があります。ツールラッパーはオプションです。 - **デフォルト:** 空 - **例:** `"toolDiscoveryCommand": "bin/get_tools"` -- **`toolCallCommand`** (文字列): - - **説明:** `toolDiscoveryCommand` を使用して検出された特定のツールを呼び出すためのカスタムシェルコマンドを定義します。シェルコマンドは以下の条件を満たす必要があります: - - 最初のコマンドライン引数として関数の `name`（[function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) と完全に一致するもの）を受け取る。 - - `stdin` から JSON 形式の関数引数を読み取る（[`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall) と同様）。 - - `stdout` に JSON 形式の関数出力を返す（[`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse) と同様）。 +- **`toolCallCommand`** (string): + - **説明:** **Gemini CLI と連携。** `toolDiscoveryCommand` で検出した特定のツールを呼び出すためのカスタムシェルコマンドを定義します。シェルコマンドは以下の条件を満たす必要があります： + - 最初のコマンドライン引数として関数 `name`（[function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) と完全一致）を受け取る必要があります。 + - `stdin` から JSON 形式の関数引数を読み取る必要があります（[`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall) と同様）。 + - `stdout` に JSON 形式の関数出力を返す必要があります（[`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse) と同様）。 - **デフォルト:** 空 - **例:** `"toolCallCommand": "bin/call_tool"` -- **`mcpServers`** (オブジェクト): - - **説明:** カスタムツールを検出して使用するための Model-Context Protocol (MCP) サーバーへの接続を構成します。Qwen Code は構成された各 MCP サーバーに接続し、利用可能なツールを検出しようとします。複数の MCP サーバーが同じ名前のツールを公開している場合、ツール名は構成で定義したサーバーエイリアスでプレフィックスが付けられ（例: `serverAlias__actualToolName`）、競合を回避します。システムは互換性のために MCP ツール定義から特定のスキーマプロパティを削除する場合があります。`command`、`url`、`httpUrl` のうち少なくとも1つを指定する必要があります。複数が指定された場合、優先順位は `httpUrl` > `url` > `command` です。 +- **`mcpServers`** (object): + - **説明:** カスタムツールを検出して使用するための 1 つ以上の Model-Context Protocol (MCP) サーバーへの接続を構成します。Qwen Code は、構成された各 MCP サーバーに接続し、利用可能なツールを検出しようとします。複数の MCP サーバーが同じ名前のツールを公開している場合、競合を避けるために、構成で定義したサーバーエイリアスがツール名の前に付加されます（例：`serverAlias__actualToolName`）。システムは互換性のために MCP ツール定義から特定のスキーマプロパティを削除する場合があります。`command`、`url`、`httpUrl` のうち少なくとも 1 つを指定する必要があります。複数が指定された場合、優先順位は `httpUrl`、`url`、`command` の順になります。 - **デフォルト:** 空 - **プロパティ:** - - **``** (オブジェクト): 指定されたサーバーのパラメータ。 - - `command` (文字列, 任意): 標準入出力を介して MCP サーバーを起動するコマンド。 - - `args` (文字列の配列, 任意): コマンドに渡す引数。 - - `env` (オブジェクト, 任意): サーバープロセスに設定する環境変数。 - - `cwd` (文字列, 任意): サーバーを起動する作業ディレクトリ。 - - `url` (文字列, 任意): Server-Sent Events (SSE) を使用して通信する MCP サーバーの URL。 - - `httpUrl` (文字列, 任意): ストリーム可能な HTTP を使用して通信する MCP サーバーの URL。 - - `headers` (オブジェクト, 任意): `url` または `httpUrl` へのリクエストで送信する HTTP ヘッダーのマップ。 - - `timeout` (数値, 任意): この MCP サーバーへのリクエストのタイムアウト（ミリ秒）。 - - `trust` (boolean, 任意): このサーバーを信頼し、すべてのツール呼び出し確認をバイパスします。 - - `description` (文字列, 任意): 表示目的で使用されるサーバーの簡単な説明。 - - `includeTools` (文字列の配列, 任意): この MCP サーバーから含めるツール名のリスト。指定された場合、ここにリストされたツールのみがこのサーバーから利用可能になります（ホワイトリスト動作）。指定されていない場合、デフォルトでサーバーのすべてのツールが有効になります。 - - `excludeTools` (文字列の配列, 任意): この MCP サーバーから除外するツール名のリスト。ここにリストされたツールは、サーバーが公開していてもモデルでは利用できません。**注意:** `excludeTools` は `includeTools` よりも優先されます。両方のリストにツールが含まれている場合、除外されます。 + - **``** (object): 指定されたサーバーのパラメータ。 + - `command` (string, optional): 標準 I/O 経由で MCP サーバーを起動するコマンド。 + - `args` (文字列の配列, optional): コマンドに渡す引数。 + - `env` (object, optional): サーバープロセスに設定する環境変数。 + - `cwd` (string, optional): サーバーを起動する作業ディレクトリ。 + - `url` (string, optional): Server-Sent Events (SSE) を使用して通信する MCP サーバーの URL。 + - `httpUrl` (string, optional): ストリーム可能な HTTP を使用して通信する MCP サーバーの URL。 + - `headers` (object, optional): `url` または `httpUrl` へのリクエストで送信する HTTP ヘッダーのマップ。 + - `timeout` (number, optional): この MCP サーバーへのリクエストのタイムアウト（ミリ秒）。 + - `trust` (boolean, optional): このサーバーを信頼し、すべてのツール呼び出し確認をバイパスします。 + - `description` (string, optional): 表示目的で使用されるサーバーの簡単な説明。 + - `includeTools` (文字列の配列, optional): この MCP サーバーから含めるツール名のリスト。指定された場合、ここにリストされたツールのみがこのサーバーから利用可能になります（ホワイトリスト動作）。指定しない場合、デフォルトではサーバーからのすべてのツールが有効になります。 + - `excludeTools` (文字列の配列, optional): この MCP サーバーから除外するツール名のリスト。ここにリストされたツールは、サーバーが公開していてもモデルでは利用できません。**注意:** `excludeTools` は `includeTools` よりも優先されます。両方のリストにツールが含まれている場合、除外されます。 - **例:** ```json "mcpServers": { @@ -182,24 +209,24 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 } ``` -- **`checkpointing`** (オブジェクト): - - **説明:** 会話およびファイルの状態を保存・復元するチェックポイント機能を構成します。詳細については [Checkpointing documentation](../checkpointing.md) を参照してください。 +- **`checkpointing`** (object): + - **説明:** 会話とファイルの状態を保存および復元するチェックポイント機能を構成します。詳細については [Checkpointing documentation](../checkpointing.md) を参照してください。 - **デフォルト:** `{"enabled": false}` - **プロパティ:** - **`enabled`** (boolean): `true` の場合、`/restore` コマンドが利用可能になります。 -- **`preferredEditor`** (文字列): +- **`preferredEditor`** (string): - **説明:** diff 表示に使用するエディタを指定します。 - **デフォルト:** `vscode` - **例:** `"preferredEditor": "vscode"` -- **`telemetry`** (オブジェクト) - - **説明:** Qwen Code のロギングおよびメトリクス収集を構成します。詳細については [Telemetry](../telemetry.md) を参照してください。 +- **`telemetry`** (object) + - **説明:** Qwen Code のログとメトリクス収集を構成します。詳細については [Telemetry](../telemetry.md) を参照してください。 - **デフォルト:** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **プロパティ:** - **`enabled`** (boolean): テレメトリが有効かどうか。 - - **`target`** (文字列): 収集されたテレメトリの送信先。サポートされる値は `local` および `gcp`。 - - **`otlpEndpoint`** (文字列): OTLP Exporter のエンドポイント。 + - **`target`** (string): 収集されたテレメトリの送信先。サポートされる値は `local` と `gcp`。 + - **`otlpEndpoint`** (string): OTLP Exporter のエンドポイント。 - **`logPrompts`** (boolean): ユーザープロンプトの内容をログに含めるかどうか。 - **例:** ```json @@ -210,7 +237,6 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 "logPrompts": false } ``` - - **`usageStatisticsEnabled`** (boolean): - **説明:** 使用統計情報の収集を有効または無効にします。詳細については [Usage Statistics](#usage-statistics) を参照してください。 - **デフォルト:** `true` @@ -220,22 +246,26 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 ``` - **`hideTips`** (boolean): - - **説明:** CLI インターフェースでの役立つヒントの表示を有効または無効にします。 + - **説明:** CLI インターフェースの役立つヒントを有効または無効にします。 - **デフォルト:** `false` - **例:** + ```json "hideTips": true ``` - **`hideBanner`** (boolean): - - **説明:** CLI インターフェースでの起動バナー（ASCII アートロゴ）の表示を有効または無効にします。 + - **説明:** CLI インターフェースの起動バナー（ASCII アートロゴ）を有効または無効にします。 - **デフォルト:** `false` - **例:** + ```json "hideBanner": true ``` -- **`maxSessionTurns`** (数値 +- **`maxSessionTurns`** (number): + - **説明:** セッションの最大ターン数を設定します。セッションがこの制限を超えると、CLI は処理を停止し、新しいチャットを開始します。 + - **デフォルト:** `- ### `settings.json` の例: @@ -264,6 +294,8 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 "usageStatisticsEnabled": true, "hideTips": false, "hideBanner": false, + "skipNextSpeakerCheck": false, + "skipLoopDetection": false, "maxSessionTurns": 10, "summarizeToolOutput": { "run_shell_command": { @@ -276,73 +308,75 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 } ``` -## Shell History +## Shell 履歴 CLI は実行した shell コマンドの履歴を保持します。異なるプロジェクト間での競合を避けるため、この履歴はユーザーのホームフォルダ内のプロジェクト固有のディレクトリに保存されます。 -- **Location:** `~/.qwen/tmp//shell_history` +- **場所:** `~/.qwen/tmp//shell_history` - `` はプロジェクトのルートパスから生成される一意の識別子です。 - 履歴は `shell_history` という名前のファイルに保存されます。 +```markdown ## 環境変数と `.env` ファイル -環境変数は、アプリケーションを設定する一般的な方法です。特に API キーのような機密情報や、環境によって変わる設定に使われます。認証の設定については、[認証ドキュメント](./authentication.md)を参照してください。利用可能なすべての認証方法が記載されています。 +環境変数は、アプリケーションを設定する一般的な方法であり、特にAPIキーのような機密情報や、環境によって変わる可能性のある設定に使われます。認証のセットアップについては、利用可能なすべての認証方法を網羅した[認証ドキュメント](./authentication.md)を参照してください。 -CLI は `.env` ファイルから自動的に環境変数を読み込みます。読み込み順序は以下の通りです： +CLIは自動的に `.env` ファイルから環境変数を読み込みます。読み込み順序は以下の通りです： -1. カレントディレクトリにある `.env` ファイル。 -2. 見つからない場合、親ディレクトリを上に向かって探索し、`.env` ファイルが見つかるか、プロジェクトルート（`.git` フォルダで識別）またはホームディレクトリに到達するまで続けます。 -3. それでも見つからない場合、`~/.env`（ユーザーのホームディレクトリ内）を探します。 +1. カレントディレクトリにある `.env` ファイル。 +2. 見つからない場合、親ディレクトリを上に向かって探索し、`.env` ファイルが見つかるか、プロジェクトルート（`.git` フォルダで識別）またはホームディレクトリに到達するまで続けます。 +3. それでも見つからない場合は、`~/.env`（ユーザーのホームディレクトリ内）を探します。 -**環境変数の除外：** 一部の環境変数（例：`DEBUG` や `DEBUG_MODE`）は、CLI の動作に干渉するのを防ぐため、プロジェクトの `.env` ファイルからはデフォルトで除外されます。`.qwen/.env` ファイルからの変数は除外されません。この動作は、`settings.json` ファイルの `excludedProjectEnvVars` 設定でカスタマイズできます。 +**環境変数の除外：** 一部の環境変数（例：`DEBUG` や `DEBUG_MODE`）は、CLIの動作への干渉を防ぐため、デフォルトではプロジェクトの `.env` ファイルからは自動的に除外されます。`.qwen/.env` ファイルからの変数は一切除外されません。この動作は、`settings.json` ファイル内の `excludedProjectEnvVars` 設定を使ってカスタマイズできます。 -- **`OPENAI_API_KEY`**: - - 利用可能な[認証方法](./authentication.md)の一つ。 - - シェルプロファイル（例：`~/.bashrc`、`~/.zshrc`）または `.env` ファイルで設定します。 -- **`OPENAI_BASE_URL`**: - - 利用可能な[認証方法](./authentication.md)の一つ。 - - シェルプロファイル（例：`~/.bashrc`、`~/.zshrc`）または `.env` ファイルで設定します。 -- **`OPENAI_MODEL`**: +- **`OPENAI_API_KEY`**： + - 利用可能な複数の[認証方法](./authentication.md)の一つ。 + - シェルプロファイル（例：`~/.bashrc`、`~/.zshrc`）または `.env` ファイルで設定してください。 +- **`OPENAI_BASE_URL`**： + - 利用可能な複数の[認証方法](./authentication.md)の一つ。 + - シェルプロファイル（例：`~/.bashrc`、`~/.zshrc`）または `.env` ファイルで設定してください。 +- **`OPENAI_MODEL`**： - 使用するデフォルトの OPENAI モデルを指定します。 - ハードコードされたデフォルト値を上書きします。 - - 例: `export OPENAI_MODEL="qwen3-coder-plus"` -- **`GEMINI_SANDBOX`**: - - `settings.json` の `sandbox` 設定の代替。 + - 例：`export OPENAI_MODEL="qwen3-coder-plus"` +- **`GEMINI_SANDBOX`**： + - `settings.json` の `sandbox` 設定の代替手段。 - `true`、`false`、`docker`、`podman`、またはカスタムコマンド文字列を受け取ります。 -- **`SEATBELT_PROFILE`**（macOS 固有）: - - macOS で Seatbelt（`sandbox-exec`）プロファイルを切り替えます。 - - `permissive-open`: （デフォルト）プロジェクトフォルダ（およびいくつかの他のフォルダ）への書き込みを制限しますが、その他の操作は許可されます（詳細は `packages/cli/src/utils/sandbox-macos-permissive-open.sb` を参照）。 - - `strict`: デフォルトで操作を拒否する厳格なプロファイルを使用します。 - - ``: カスタムプロファイルを使用します。カスタムプロファイルを定義するには、プロジェクトの `.qwen/` ディレクトリに `sandbox-macos-.sb` という名前のファイルを作成します（例：`my-project/.qwen/sandbox-macos-custom.sb`）。 -- **`DEBUG` または `DEBUG_MODE`**（CLI 自体や内部ライブラリでよく使われる）: - - `true` または `1` に設定すると、詳細なデバッグログを有効にします。トラブルシューティングに役立ちます。 - - **注意：** これらの変数は、CLI の動作に干渉するのを防ぐため、プロジェクトの `.env` ファイルからはデフォルトで除外されます。Qwen Code でこれらの変数を使用する必要がある場合は、`.qwen/.env` ファイルを使用してください。 -- **`NO_COLOR`**: - - 任意の値を設定すると、CLI のすべてのカラー出力を無効にします。 -- **`CLI_TITLE`**: - - 文字列を設定して、CLI のタイトルをカスタマイズします。 -- **`CODE_ASSIST_ENDPOINT`**: +- **`SEATBELT_PROFILE`**（macOS専用）： + - macOS 上で Seatbelt（`sandbox-exec`）プロファイルを切り替えます。 + - `permissive-open`：（デフォルト）プロジェクトフォルダ（およびその他のいくつかのフォルダ。詳細は `packages/cli/src/utils/sandbox-macos-permissive-open.sb` を参照）への書き込みを制限しますが、それ以外の操作は許可されます。 + - `strict`：デフォルトで操作を拒否する厳格なプロファイルを使用します。 + - ``：カスタムプロファイルを使用します。カスタムプロファイルを定義するには、プロジェクトの `.qwen/` ディレクトリに `sandbox-macos-.sb` という名前のファイルを作成してください（例：`my-project/.qwen/sandbox-macos-custom.sb`）。 +- **`DEBUG` または `DEBUG_MODE`**（多くの場合、下位ライブラリやCLI自体で使用）： + - `true` または `1` に設定すると、詳細なデバッグログを有効にし、トラブルシューティングに役立ちます。 + - **注意：** これらの変数は、CLIの動作への干渉を防ぐため、デフォルトではプロジェクトの `.env` ファイルからは自動的に除外されます。Qwen Code 専用にこれらを設定する必要がある場合は、`.qwen/.env` ファイルを使用してください。 +- **`NO_COLOR`**： + - 任意の値を設定することで、CLIでのすべてのカラー出力を無効にします。 +- **`CLI_TITLE`**： + - 文字列を設定して、CLIのタイトルをカスタマイズします。 +- **`CODE_ASSIST_ENDPOINT`**： - コードアシストサーバーのエンドポイントを指定します。 - - 開発やテストに役立ちます。 -- **`TAVILY_API_KEY`**: - - Tavily ウェブ検索サービスの API キー。 - - `web_search` ツール機能を有効にするために必要です。 + - 開発やテスト時に便利です。 +- **`TAVILY_API_KEY`**： + - Tavilyウェブ検索サービスのAPIキー。 + - `web_search` ツール機能を有効にするために必須です。 - 設定されていない場合、ウェブ検索ツールは無効化されスキップされます。 - - 例: `export TAVILY_API_KEY="tvly-your-api-key-here"` + - 例：`export TAVILY_API_KEY="tvly-your-api-key-here"` +``` ## コマンドライン引数 -CLI 実行時に直接渡された引数は、そのセッションにおいて他の設定を上書きできます。 +CLI 実行時に直接渡す引数により、そのセッションにおける他の設定を上書きできます。 - **`--model `** (**`-m `**): - このセッションで使用する Qwen モデルを指定します。 - 例: `npm start -- --model qwen3-coder-plus` - **`--prompt `** (**`-p `**): - - プロンプトをコマンドに直接渡すために使用します。これにより、Qwen Code が非インタラクティブモードで起動します。 + - プロンプトを直接コマンドに渡すために使用します。これにより、Qwen Code が非インタラクティブモードで起動します。 - **`--prompt-interactive `** (**`-i `**): - - 指定したプロンプトを初期入力としてインタラクティブセッションを開始します。 + - 指定されたプロンプトを初期入力としてインタラクティブセッションを開始します。 - プロンプトはセッション開始前に処理されるのではなく、セッション内で処理されます。 - - stdin からの入力をパイプで渡す場合には使用できません。 + - stdin からのパイプ入力時には使用できません。 - 例: `qwen -i "explain this code"` - **`--sandbox`** (**`-s`**): - このセッションでサンドボックスモードを有効にします。 @@ -352,29 +386,33 @@ CLI 実行時に直接渡された引数は、そのセッションにおいて - このセッションでデバッグモードを有効にし、より詳細な出力を提供します。 - **`--all-files`** (**`-a`**): - 設定すると、現在のディレクトリ内のすべてのファイルを再帰的にプロンプトのコンテキストに含めます。 -- **`--help`** (**`-h`**): +- **`--help`** (または **`-h`**): - コマンドライン引数に関するヘルプ情報を表示します。 - **`--show-memory-usage`**: - 現在のメモリ使用量を表示します。 - **`--yolo`**: - YOLO モードを有効にし、すべてのツール呼び出しを自動的に承認します。 - **`--approval-mode `**: - - ツール呼び出しの承認モードを設定します。利用可能なモード: - - `default`: 各ツール呼び出しで承認を求める（デフォルトの動作） - - `auto_edit`: 編集系ツール（edit、write_file）は自動承認し、それ以外は承認を求める - - `yolo`: すべてのツール呼び出しを自動承認（`--yolo` と同等） - - `--yolo` と同時に使用することはできません。新しい統一されたアプローチでは、`--yolo` の代わりに `--approval-mode=yolo` を使用してください。 - - 例: `qwen --approval-mode auto_edit` + - ツール呼び出しの承認モードを設定します。サポートされるモード: + - `plan`: 分析のみ—ファイルの変更やコマンドの実行は行いません。 + - `default`: ファイル編集やシェルコマンド実行には承認が必要（デフォルトの動作）。 + - `auto-edit`: 編集系ツール（edit、write_file）は自動承認し、それ以外は確認を求めます。 + - `yolo`: すべてのツール呼び出しを自動承認（`--yolo` と同等）。 + - `--yolo` と同時に使用することはできません。新しい統一アプローチでは、`--yolo` の代わりに `--approval-mode=yolo` を使用してください。 + - 例: `qwen --approval-mode auto-edit` +- **`--allowed-tools `**: + - 確認ダイアログをスキップするツール名のカンマ区切りリスト。 + - 例: `qwen --allowed-tools "ShellTool(git status)"` - **`--telemetry`**: - [telemetry](../telemetry.md) を有効にします。 - **`--telemetry-target`**: - - テレメトリのターゲットを設定します。詳細は [telemetry](../telemetry.md) を参照してください。 + - テレメトリーターゲットを設定します。詳細は [telemetry](../telemetry.md) を参照してください。 - **`--telemetry-otlp-endpoint`**: - - テレメトリ用の OTLP エンドポイントを設定します。詳細は [telemetry](../telemetry.md) を参照してください。 + - テレメトリー用の OTLP エンドポイントを設定します。詳細は [telemetry](../telemetry.md) を参照してください。 - **`--telemetry-otlp-protocol`**: - - テレメトリ用の OTLP プロトコルを設定します（`grpc` または `http`）。デフォルトは `grpc` です。詳細は [telemetry](../telemetry.md) を参照してください。 + - テレメトリー用の OTLP プロトコルを設定します（`grpc` または `http`）。デフォルトは `grpc` です。詳細は [telemetry](../telemetry.md) を参照してください。 - **`--telemetry-log-prompts`**: - - テレメトリ用にプロンプトのログを有効にします。詳細は [telemetry](../telemetry.md) を参照してください。 + - テレメトリー用にプロンプトのログを有効にします。詳細は [telemetry](../telemetry.md) を参照してください。 - **`--checkpointing`**: - [checkpointing](../checkpointing.md) を有効にします。 - **`--extensions `** (**`-e `**): @@ -384,30 +422,32 @@ CLI 実行時に直接渡された引数は、そのセッションにおいて - **`--list-extensions`** (**`-l`**): - 利用可能なすべての拡張機能をリスト表示して終了します。 - **`--proxy`**: - - CLI のプロキシを設定します。 + - CLI 用のプロキシを設定します。 - 例: `--proxy http://localhost:7890` - **`--include-directories `**: - マルチディレクトリ対応のためにワークスペースに追加のディレクトリを含めます。 - 複数回指定するか、カンマ区切りで指定できます。 - - 最大で 5 つのディレクトリを追加できます。 + - 最大5つのディレクトリを追加できます。 - 例: `--include-directories /path/to/project1,/path/to/project2` または `--include-directories /path/to/project1 --include-directories /path/to/project2` +- **`--screen-reader`**: + - アクセシビリティのためのスクリーンリーダーモードを有効にします。 - **`--version`**: - CLI のバージョンを表示します。 - **`--openai-logging`**: - - OpenAI API 呼び出しのログを有効にして、デバッグや分析に役立てます。このフラグは `settings.json` の `enableOpenAILogging` 設定を上書きします。 + - デバッグおよび分析のために OpenAI API 呼び出しのログを有効にします。このフラグは `settings.json` の `enableOpenAILogging` 設定よりも優先されます。 - **`--tavily-api-key `**: - このセッションでウェブ検索機能に使用する Tavily API キーを設定します。 - 例: `qwen --tavily-api-key tvly-your-api-key-here` -## Context ファイル（階層型インストラクショナルコンテキスト） +## コンテキストファイル（階層型指示コンテキスト） -CLI の**動作**を直接設定するものではありませんが、Context ファイル（デフォルトでは `QWEN.md`、`contextFileName` 設定で変更可能）は、**インストラクショナルコンテキスト**（「メモリ」とも呼ばれます）を設定するために非常に重要です。この強力な機能により、プロジェクト固有の指示、コーディングスタイルガイド、または関連する背景情報を AI に提供でき、あなたのニーズにより適切で正確な応答を得ることができます。CLI には、フッターにロードされた Context ファイル数を表示するインジケータなど、アクティブなコンテキストの状態を確認できる UI 要素も含まれています。 +CLI の**動作**設定というわけではありませんが、コンテキストファイル（デフォルトでは `QWEN.md`、`contextFileName` 設定で変更可能）は、**指示コンテキスト**（「メモリ」とも呼ばれます）の設定に不可欠です。この強力な機能により、プロジェクト固有の指示、コーディングスタイルガイド、その他の関連する背景情報を AI に提供でき、あなたのニーズにより適した正確な応答を得ることができます。CLI には、現在アクティブなコンテキストファイルの数をフッターに表示する UI 要素などがあり、使用中のコンテキスト状態を常に確認できます。 -- **目的：** これらの Markdown ファイルには、Qwen モデルとのやり取り中に参照してほしい指示、ガイドライン、またはコンテキスト情報を記述します。システムは、このインストラクショナルコンテキストを階層的に管理するように設計されています。 +- **目的：** これらの Markdown ファイルには、Qwen モデルとのやり取り中に参照してほしい指示、ガイドライン、またはコンテキスト情報を記述します。システムは、この指示コンテキストを階層的に管理するように設計されています。 ### コンテキストファイルの例（例：`QWEN.md`） -以下は、TypeScriptプロジェクトのルートにあるコンテキストファイルが含む内容の概念的な例です： +以下は、TypeScriptプロジェクトのルートにあるコンテキストファイルが含むかもしれない内容の概念的な例です： ```markdown @@ -417,21 +457,21 @@ CLI の**動作**を直接設定するものではありませんが、Context - 新しいTypeScriptコードを生成する際は、既存のコーディングスタイルに従ってください。 - 新しい関数やクラスには、必ずJSDocコメントを付与してください。 -- 適切な場面では、関数型プログラミングのパラダイムを優先してください。 -- すべてのコードは、TypeScript 5.0およびNode.js 20+と互換性がある必要があります。 +- 適切な場所では、関数型プログラミングのパラダイムを優先してください。 +- すべてのコードは、TypeScript 5.0およびNode.js 20+との互換性を保つ必要があります。 ## コーディングスタイル: - インデントにはスペース2つを使用してください。 -- インターフェース名の先頭には`I`を付けてください（例：`IUserService`）。 -- クラスのプライベートメンバーの先頭にはアンダースコア（`_`）を付けてください。 +- インターフェース名には`I`を接頭辞として付けてください（例：`IUserService`）。 +- privateなクラスメンバには、アンダースコア（`_`）を接頭辞として付けてください。 - 常に厳密等価演算子（`===`および`!==`）を使用してください。 ## 特定のコンポーネント: `src/api/client.ts` - このファイルは、すべての外部APIリクエストを処理します。 -- 新しいAPI呼び出し関数を追加する際は、堅牢なエラーハンドリングとロギングを必ず含めてください。 -- GETリクエストには、既存の`fetchWithRetry`ユーティリティを使用してください。 +- 新しいAPI呼び出し関数を追加する際は、堅牢なエラーハンドリングとロギングを含めるようにしてください。 +- すべてのGETリクエストには、既存の`fetchWithRetry`ユーティリティを使用してください。 ```markdown ## 依存関係について: @@ -439,39 +479,39 @@ CLI の**動作**を直接設定するものではありませんが、Context - 新しい外部依存関係の導入は、どうしても必要な場合を除き避けてください。 - 新しい依存関係が必要な場合は、その理由を明記してください。 -この例は、プロジェクト全体のコンテキスト情報や特定のコーディング規約、特定のファイルやコンポーネントに関する注意書きなどをどのように提供するかを示しています。コンテキストファイルがどれだけ関連性が高く正確であるかによって、AIがあなたをどれだけ効果的に支援できるかが決まります。プロジェクト固有のコンテキストファイルの作成を強く推奨します。これにより、プロジェクト内での規約やコンテキストを確立できます。 +この例では、プロジェクト全体のコンテキスト情報や特定のコーディング規約、特定ファイルやコンポーネントに関する注意書きなどをどのように提供できるかを示しています。コンテキストファイルがどれだけ関連性があり、正確であるかによって、AIがあなたをどの程度効果的に支援できるかが決まります。プロジェクト固有のコンテキストファイルを作成し、積極的に活用することを強く推奨します。 -- **階層的なロードと優先順位:** CLIは、複数の場所からコンテキストファイル（例: `QWEN.md`）をロードすることで、洗練された階層的なメモリシステムを実装しています。このリストの下位（より具体的な）ファイルの内容は、通常、上位（より一般的な）ファイルの内容を上書きまたは補完します。結合順序や最終的なコンテキストの詳細は、`/memory show` コマンドで確認できます。一般的なロード順序は以下の通りです: - 1. **グローバルコンテキストファイル:** - - 場所: `~/.qwen/`（例: ユーザーのホームディレクトリにある `~/.qwen/QWEN.md`）。 - - 範囲: すべてのプロジェクトに対してデフォルトの指示を提供します。 +- **階層的な読み込みと優先順位:** CLIは、複数の場所からコンテキストファイル（例：`QWEN.md`）を読み込むことで、洗練された階層型メモリシステムを実装しています。このリストで下位（より具体的な）に位置するファイルの内容は、通常、上位（より一般的な）ファイルの内容をオーバーライドまたは補完します。結合順序および最終的なコンテキストは、`/memory show` コマンドを使用して確認できます。典型的な読み込み順序は以下の通りです： + 1. **グローバル・コンテキストファイル:** + - 場所: `~/.qwen/` （例：ユーザーのホームディレクトリにある `~/.qwen/QWEN.md`） + - 範囲: 全てのプロジェクトに対してデフォルトの指示を提供します。 2. **プロジェクトルートおよび祖先ディレクトリのコンテキストファイル:** - - 場所: CLIは、現在の作業ディレクトリから設定されたコンテキストファイルを検索し、次に各親ディレクトリを `.git` フォルダで識別されるプロジェクトルートまたはホームディレクトリまで検索します。 - - 範囲: プロジェクト全体またはその主要な部分に関連するコンテキストを提供します。 - 3. **サブディレクトリのコンテキストファイル（コンテキスト依存/ローカル）:** - - 場所: CLIは、現在の作業ディレクトリ以下のサブディレクトリ（`node_modules`、`.git` などの一般的な無視パターンを尊重して）からも設定されたコンテキストファイルをスキャンします。この検索の深さはデフォルトでは200ディレクトリに制限されていますが、`settings.json` ファイルの `memoryDiscoveryMaxDirs` フィールドで設定可能です。 - - 範囲: 特定のコンポーネント、モジュール、またはプロジェクトのサブセクションに関連する非常に具体的な指示を可能にします。 -- **結合とUI表示:** 見つかったすべてのコンテキストファイルの内容は、（その出所とパスを示すセパレータとともに）結合され、システムプロンプトの一部として提供されます。CLIのフッターにはロードされたコンテキストファイルの数が表示され、現在アクティブな指示コンテキストを視覚的に確認できます。 -- **コンテンツのインポート:** `@path/to/file.md` 構文を使用して、他のMarkdownファイルをインポートすることで、コンテキストファイルをモジュール化できます。詳細については、[Memory Import Processor documentation](../core/memport.md) を参照してください。 -- **メモリ管理用コマンド:** - - `/memory refresh` を使用して、すべての設定された場所からすべてのコンテキストファイルを強制的に再スキャンおよび再ロードできます。これにより、AIの指示コンテキストが更新されます。 - - `/memory show` を使用して、現在ロードされている結合された指示コンテキストを表示し、AIが使用している階層と内容を確認できます。 - - `/memory` コマンドとそのサブコマンド（`show` および `refresh`）の詳細については、[Commands documentation](./commands.md#memory) を参照してください。 - -これらの設定レイヤーとコンテキストファイルの階層構造を理解し活用することで、AIのメモリを効果的に管理し、Qwen Codeの応答をあなたの特定のニーズやプロジェクトに合わせて調整できます。 + - 場所: CLIは現在の作業ディレクトリから開始し、各親ディレクトリを探索して設定されたコンテキストファイルを探します。探索は、`.git` フォルダで識別されるプロジェクトルートか、ホームディレクトリまで続きます。 + - 範囲: プロジェクト全体またはその主要部分に関連するコンテキスト情報を提供します。 + 3. **サブディレクトリのコンテキストファイル（コンテキスト依存／ローカル）:** + - 場所: CLIは、現在の作業ディレクトリ以下のサブディレクトリにも設定されたコンテキストファイルがないかスキャンします（`node_modules` や `.git` などの一般的な無視パターンは尊重されます）。この検索範囲はデフォルトで最大200ディレクトリに制限されていますが、`settings.json` ファイル内の `memoryDiscoveryMaxDirs` フィールドで変更可能です。 + - 範囲: 特定のコンポーネント、モジュール、またはプロジェクトの一部に対する非常に詳細な指示を可能にします。 +- **連結とUI表示:** 見つかったすべてのコンテキストファイルの内容は、それぞれの出典とパスを示す区切り文字とともに連結され、システムプロンプトの一部として提供されます。CLIのフッターには読み込まれたコンテキストファイル数が表示され、アクティブな指示コンテキストを視覚的に把握できます。 +- **コンテンツのインポート:** `@path/to/file.md` 構文を使って他のMarkdownファイルをインポートすることで、コンテキストファイルをモジュール化できます。詳しくは[Memory Import Processor のドキュメント](../core/memport.md)をご参照ください。 +- **メモリ管理コマンド:** + - `/memory refresh` を使用すると、すべての設定済み場所からコンテキストファイルを強制的に再スキャン・再読み込みできます。これにより、AIへの指示コンテキストが更新されます。 + - `/memory show` を使用すると、現在読み込まれている統合された指示コンテキストを表示でき、AIが使用している階層構造と内容を確認できます。 + - `/memory` コマンドおよびそのサブコマンド（`show` および `refresh`）の詳細については、[Commands documentation](./commands.md#memory) をご参照ください。 + +これらの設定レイヤーとコンテキストファイルの階層的性質を理解し活用することで、AIのメモリを効果的に管理し、Qwen Codeの応答をあなたの特定のニーズやプロジェクトに合わせて調整することが可能になります。 ``` -## サンドボックス +## Sandboxing Qwen Code は、システムを保護するために、サンドボックス環境内で潜在的に危険な操作（シェルコマンドやファイルの変更など）を実行できます。 -サンドボックスはデフォルトでは無効になっていますが、以下の方法で有効にできます： +サンドボックス機能はデフォルトでは無効になっていますが、以下の方法で有効にできます： - `--sandbox` または `-s` フラグを使用する - `GEMINI_SANDBOX` 環境変数を設定する - `--yolo` または `--approval-mode=yolo` を使用する場合、デフォルトでサンドボックスが有効になります -デフォルトでは、事前にビルドされた `qwen-code-sandbox` Docker イメージを使用します。 +デフォルトでは、事前にビルドされた `qwen-code-sandbox` Docker イメージが使用されます。 プロジェクト固有のサンドボックス要件がある場合は、プロジェクトのルートディレクトリに `.qwen/sandbox.Dockerfile` というカスタム Dockerfile を作成できます。この Dockerfile はベースとなるサンドボックスイメージを元に作成できます： @@ -488,7 +528,7 @@ FROM qwen-code-sandbox # COPY ./my-config /app/my-config ``` -`.qwen/sandbox.Dockerfile` が存在する場合、Qwen Code を実行する際に `BUILD_SANDBOX` 環境変数を使用することで、カスタム sandbox イメージを自動的にビルドできます： +`.qwen/sandbox.Dockerfile` が存在する場合、Qwen Code を実行する際に `BUILD_SANDBOX` 環境変数を使用して、カスタム sandbox イメージを自動ビルドできます： ```bash BUILD_SANDBOX=1 qwen -s @@ -496,11 +536,11 @@ BUILD_SANDBOX=1 qwen -s ## 使用統計情報 -Qwen Code の改善のために、匿名化された使用統計情報を収集しています。このデータは、CLI がどのように使われているかを理解し、一般的な問題を特定し、新機能の優先順位を決定するために役立ちます。 +Qwen Code の改善のため、匿名化された使用統計情報を収集しています。このデータは、CLI の利用状況の把握、一般的な問題の特定、新機能の優先順位付けに役立てています。 **収集する情報:** -- **ツール呼び出し:** 呼び出されたツールの名前、成功または失敗の結果、実行にかかった時間などを記録します。ただし、ツールに渡された引数や、ツールが返したデータは収集しません。 +- **ツール呼び出し:** 呼び出されたツールの名前、成功または失敗の結果、実行にかかった時間などを記録します。ツールに渡された引数や、ツールから返されたデータは収集しません。 - **API リクエスト:** 各リクエストで使用されたモデル、リクエストの所要時間、成功したかどうかを記録します。プロンプトやレスポンスの内容は収集しません。 - **セッション情報:** 有効化されているツールや承認モードなど、CLI の設定に関する情報を収集します。 @@ -508,9 +548,9 @@ Qwen Code の改善のために、匿名化された使用統計情報を収集 - **個人を特定できる情報 (PII):** 氏名、メールアドレス、API キーなど、個人を特定できる情報は一切収集しません。 - **プロンプトおよびレスポンスの内容:** ユーザーが入力したプロンプトや、モデルからのレスポンスの内容は記録しません。 -- **ファイルの内容:** CLI によって読み書きされたファイルの内容は記録しません。 +- **ファイルの内容:** CLI が読み書きしたファイルの内容は記録しません。 -**使用統計情報の収集をオプトアウトする方法:** +**収集をオプトアウトする方法:** `settings.json` ファイルで `usageStatisticsEnabled` プロパティを `false` に設定することで、いつでも使用統計情報の収集をオプトアウトできます： diff --git a/website/content/ja/cli/themes.md b/website/content/ja/cli/themes.md index b1410568..0606aec4 100644 --- a/website/content/ja/cli/themes.md +++ b/website/content/ja/cli/themes.md @@ -4,7 +4,7 @@ Qwen Code は、配色や外観をカスタマイズできるさまざまなテ ## 利用可能なテーマ -Qwen Code にはいくつかの事前定義されたテーマが含まれており、CLI 内で `/theme` コマンドを実行することで一覧を表示できます： +Qwen Code にはいくつかの事前定義されたテーマが含まれており、CLI 内で `/theme` コマンドを使用して一覧を表示できます： - **ダークテーマ:** - `ANSI` @@ -21,22 +21,24 @@ Qwen Code にはいくつかの事前定義されたテーマが含まれてお - `Google Code` - `Xcode` -### テーマの変更方法 +### テーマの変更 -1. Qwen Code で `/theme` と入力します。 -2. 利用可能なテーマの一覧を表示するダイアログまたは選択プロンプトが表示されます。 -3. 矢印キーを使ってテーマを選択します。一部のインターフェースでは、選択中にライブプレビューやハイライト表示が行われる場合があります。 -4. 選択内容を確定して、テーマを適用します。 +1. Qwen Code で `/theme` を入力します。 +2. 利用可能なテーマの一覧が表示されたダイアログまたは選択プロンプトが表示されます。 +3. 矢印キーを使ってテーマを選択します。一部のインターフェースでは、選択中にライブプレビューまたはハイライト表示が提供される場合があります。 +4. 選択内容を確定してテーマを適用します。 + +**注意:** `settings.json` ファイル内でテーマが定義されている場合（名前またはファイルパスによる）、`/theme` コマンドを使ってテーマを変更する前に、ファイルから `"theme"` 設定を削除する必要があります。 ### テーマの永続化 -選択されたテーマは Qwen Code の[設定](./configuration.md)に保存されるため、セッションをまたいでユーザーの設定が保持されます。 +選択されたテーマは Qwen Code の [configuration](./configuration.md) に保存されるため、セッションをまたいで設定が記憶されます。 --- ## カスタムカラーテーマ -Qwen Code では、`settings.json` ファイルにテーマを指定することで、独自のカスタムカラーテーマを作成できます。これにより、CLI で使用されるカラーパレットを完全にコントロールすることが可能になります。 +Qwen Code では、`settings.json` ファイルでテーマを指定することで、独自のカスタムカラーテーマを作成できます。これにより、CLI で使用されるカラーパレットを完全にコントロールできます。 ### カスタムテーマの定義方法 @@ -81,14 +83,14 @@ Qwen Code では、`settings.json` ファイルにテーマを指定すること - `AccentRed` - `Comment` - `Gray` -- `DiffAdded`（任意、diff の追加行用） -- `DiffRemoved`（任意、diff の削除行用） -- `DiffModified`（任意、diff の変更行用） +- `DiffAdded` (オプション、diff の追加行用) +- `DiffRemoved` (オプション、diff の削除行用) +- `DiffModified` (オプション、diff の変更行用) **必須プロパティ:** -- `name`（`customThemes` オブジェクト内のキーと一致し、文字列である必要があります） -- `type`（文字列 `"custom"` である必要があります） +- `name` (`customThemes` オブジェクト内のキーと一致する必要があり、文字列であること) +- `type` (文字列 `"custom"` であること) - `Background` - `Foreground` - `LightBlue` @@ -101,19 +103,59 @@ Qwen Code では、`settings.json` ファイルにテーマを指定すること - `Comment` - `Gray` -色の値には、16進コード（例：`#FF0000`）**または**標準的な CSS カラー名（例：`coral`、`teal`、`blue`）を使用できます。サポートされている名前の完全なリストについては、[CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords) を参照してください。 +色の値には、16進コード（例: `#FF0000`）**または** 標準的な CSS カラー名（例: `coral`, `teal`, `blue`）のいずれかを使用できます。サポートされている名前の完全なリストについては [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords) を参照してください。 `customThemes` オブジェクトにエントリを追加することで、複数のカスタムテーマを定義できます。 +### ファイルからテーマを読み込む + +`settings.json` でカスタムテーマを定義するだけでなく、`settings.json` にファイルパスを指定することで、JSON ファイルから直接テーマを読み込むこともできます。これはテーマを共有したり、メインの設定ファイルとは別に管理したりするのに便利です。 + +ファイルからテーマを読み込むには、`settings.json` の `theme` プロパティにテーマファイルのパスを設定します： + +```json +{ + "theme": "/path/to/your/theme.json" +} +``` + +テーマファイルは、`settings.json` で定義されたカスタムテーマと同じ構造に従った有効な JSON ファイルである必要があります。 + +**例 `my-theme.json`:** + +```json +{ + "name": "My File Theme", + "type": "custom", + "Background": "#282A36", + "Foreground": "#F8F8F2", + "LightBlue": "#82AAFF", + "AccentBlue": "#61AFEF", + "AccentPurple": "#BD93F9", + "AccentCyan": "#8BE9FD", + "AccentGreen": "#50FA7B", + "AccentYellow": "#F1FA8C", + "AccentRed": "#FF5555", + "Comment": "#6272A4", + "Gray": "#ABB2BF", + "DiffAdded": "#A6E3A1", + "DiffRemoved": "#F38BA8", + "DiffModified": "#89B4FA", + "GradientColors": ["#4796E4", "#847ACE", "#C3677F"] +} +``` + +**セキュリティに関する注意:** 安全性を考慮して、Gemini CLI はホームディレクトリ内にあるテーマファイルのみを読み込みます。ホームディレクトリ外からテーマを読み込もうとすると警告が表示され、テーマは読み込まれません。これは信頼できないソースからの悪意のあるテーマファイルの読み込みを防ぐためです。 + ### カスタムテーマの例 Custom theme example ### カスタムテーマの使い方 -- Qwen Code で `/theme` コマンドを使用して、カスタムテーマを選択します。作成したテーマはテーマ選択ダイアログに表示されます。 -- または、`settings.json` に `"theme": "MyCustomTheme"` を追加してデフォルトとして設定します。 -- カスタムテーマはユーザー、プロジェクト、システムのいずれかのレベルで設定でき、他の設定と同様の[設定の優先順位](./configuration.md)に従います。 +- Qwen Code で `/theme` コマンドを使用して、カスタムテーマを選択できます。テーマ選択ダイアログにあなたのカスタムテーマが表示されます。 +- または、`settings.json` に `"theme": "MyCustomTheme"` を追加することでデフォルトとして設定できます。 +- カスタムテーマはユーザー、プロジェクト、システムのいずれかのレベルで設定可能で、他の設定と同様の[設定優先順位](./configuration.md)に従います。 --- diff --git a/website/content/ja/deployment.md b/website/content/ja/deployment.md index 7b4889cb..f8062224 100644 --- a/website/content/ja/deployment.md +++ b/website/content/ja/deployment.md @@ -10,7 +10,7 @@ Qwen Code を実行するにはいくつかの方法があります。どの方 ### 1. 標準インストール（一般ユーザー向け推奨） -これは、エンドユーザーが Qwen Code をインストールするための推奨方法です。NPM レジストリから Qwen Code パッケージをダウンロードすることになります。 +これは、エンドユーザーが Qwen Code をインストールするための推奨方法です。NPM レジストリから Qwen Code パッケージをダウンロードする方法です。 - **グローバルインストール:** @@ -18,7 +18,7 @@ Qwen Code を実行するにはいくつかの方法があります。どの方 npm install -g @qwen-code/qwen-code ``` - その後、どこからでも CLI を実行できます: + その後、どこからでも CLI を実行できます： ```bash qwen @@ -35,16 +35,16 @@ Qwen Code を実行するにはいくつかの方法があります。どの方 ### 2. サンドボックス環境での実行 (Docker/Podman) -セキュリティと分離性を確保するために、Qwen Code はコンテナ内で実行できます。これは、CLI が副作用を伴う可能性のあるツールを実行する際のデフォルトの方法です。 +セキュリティと分離性を確保するために、Qwen Code はコンテナ内で実行できます。CLI が副作用を伴う可能性のあるツールを実行する際のデフォルトの方法です。 - **Registry から直接実行:** - 公開されているサンドボックスイメージを直接実行できます。Docker のみが利用可能で CLI を実行したい環境で便利です。 + 公開されているサンドボックスイメージを直接実行できます。Docker のみが利用可能で CLI を実行したい環境に便利です。 ```bash # 公開されたサンドボックスイメージを実行 - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.11 ``` - **`--sandbox` フラグを使用:** - Qwen Code をローカルにインストール済みの場合（前述の標準インストール手順に従って）、サンドボックスコンテナ内で実行するよう指示できます。 + Qwen Code をローカルにインストール済みの場合（前述の標準インストール手順に従って）、サンドボックスコンテナ内で実行するように指示できます。 ```bash qwen --sandbox -y -p "your prompt here" ``` @@ -53,7 +53,7 @@ Qwen Code を実行するにはいくつかの方法があります。どの方 ### 3. ソースコードから実行（Qwen Code コントリビューター向け推奨） -プロジェクトへのコントリビューターは、CLI をソースコードから直接実行することになるでしょう。 +プロジェクトへのコントリビューターは、CLI をソースコードから直接実行することを推奨します。 - **開発モード:** この方法ではホットリロードが有効で、開発中に便利です。 @@ -62,7 +62,7 @@ Qwen Code を実行するにはいくつかの方法があります。どの方 npm run start ``` - **本番環境に近いモード（リンクされたパッケージ）:** - この方法では、ローカルのパッケージをリンクしてグローバルインストールをシミュレートします。本番ワークフローでのローカルビルドのテストに便利です。 + この方法では、ローカルパッケージをリンクしてグローバルインストールをシミュレートします。本番ワークフローでのローカルビルドのテストに便利です。 ```bash # ローカルの cli パッケージをグローバルな node_modules にリンク @@ -76,7 +76,7 @@ Qwen Code を実行するにはいくつかの方法があります。どの方 ### 4. GitHub から最新の Qwen Code コミットを実行 -GitHub リポジトリから最新のコミット済みバージョンの Qwen Code を直接実行できます。これは、まだ開発中の機能をテストするのに便利です。 +GitHub リポジトリから最新のコミット済みバージョンの Qwen Code を直接実行できます。開発中の機能をテストするのに便利です。 ```bash @@ -86,28 +86,28 @@ npx https://github.com/QwenLM/qwen-code ## デプロイアーキテクチャ -上記で説明した実行方法は、以下のアーキテクチャコンポーネントとプロセスによって実現されています： +上記の実行方法は、以下のアーキテクチャコンポーネントとプロセスによって実現されています： **NPM パッケージ** -Qwen Code プロジェクトは monorepo であり、コアパッケージを NPM レジストリに公開しています： +Qwen Code プロジェクトはモノレポで、コアパッケージを NPM レジストリに公開しています： -- `@qwen-code/qwen-code-core`: バックエンド。ロジックとツールの実行を処理します。 -- `@qwen-code/qwen-code`: ユーザー向けのフロントエンド。 +- `@qwen-code/qwen-code-core`: バックエンド。ロジックとツールの実行を担当。 +- `@qwen-code/qwen-code`: ユーザー向けフロントエンド。 これらのパッケージは、標準インストール時やソースから Qwen Code を実行する際に使用されます。 -**ビルドとパッケージングプロセス** +**ビルドおよびパッケージングプロセス** -配布チャネルに応じて、2 種類のビルドプロセスが使用されます： +配布チャネルに応じて、2 種類の異なるビルドプロセスが使用されます： -- **NPM への公開:** NPM レジストリに公開する際には、`@qwen-code/qwen-code-core` および `@qwen-code/qwen-code` 内の TypeScript ソースコードが TypeScript Compiler (`tsc`) を使用して標準的な JavaScript にトランスパイルされます。生成された `dist/` ディレクトリが NPM パッケージとして公開されます。これは TypeScript ライブラリの一般的な手法です。 +- **NPM への公開:** NPM レジストリに公開する際には、`@qwen-code/qwen-code-core` および `@qwen-code/qwen-code` 内の TypeScript ソースコードが TypeScript Compiler（`tsc`）を使って標準的な JavaScript にトランスパイルされます。生成された `dist/` ディレクトリが NPM パッケージとして公開されます。これは TypeScript ライブラリにおける一般的な手法です。 -- **GitHub 経由での `npx` 実行:** GitHub から最新バージョンの Qwen Code を直接実行する場合、`package.json` の `prepare` スクリプトによって別のプロセスが起動されます。このスクリプトは `esbuild` を使用して、アプリケーション全体とその依存関係を単一の自己完結型 JavaScript ファイルにバンドルします。このバンドルはユーザーのマシン上でオンザフライで作成され、リポジトリにはコミットされません。 +- **GitHub 経由での `npx` 実行:** GitHub から最新バージョンの Qwen Code を直接実行する場合、`package.json` の `prepare` スクリプトによって別のプロセスが起動します。このスクリプトでは `esbuild` を使ってアプリケーション全体とその依存関係を単一の自己完結型 JavaScript ファイルにバンドルします。このバンドルファイルはユーザーのマシン上でオンザフライで作成され、リポジトリにはコミットされません。 **Docker サンドボックスイメージ** -Docker ベースの実行方法は、`qwen-code-sandbox` コンテナイメージによってサポートされています。このイメージはコンテナレジストリに公開されており、Qwen Code のグローバルインストール済みバージョンを含んでいます。 +Docker ベースの実行方法は、`qwen-code-sandbox` コンテナイメージによってサポートされています。このイメージはコンテナレジストリに公開されており、グローバルにインストールされた Qwen Code の事前ビルド版を含んでいます。 ## リリースプロセス @@ -115,4 +115,4 @@ Docker ベースの実行方法は、`qwen-code-sandbox` コンテナイメー 1. `tsc` を使用して NPM パッケージをビルドします。 2. NPM パッケージをアーティファクトレジストリに公開します。 -3. バンドルされたアセットを含む GitHub リリースを作成します。 \ No newline at end of file +3. バンドルされたアセット付きで GitHub リリースを作成します。 \ No newline at end of file diff --git a/website/content/ja/examples/proxy-script.md b/website/content/ja/examples/proxy-script.md index 2b3a3a16..c4f0f8e9 100644 --- a/website/content/ja/examples/proxy-script.md +++ b/website/content/ja/examples/proxy-script.md @@ -1,6 +1,6 @@ -# Proxy スクリプトの例 +# プロキシスクリプトの例 -以下は、`GEMINI_SANDBOX_PROXY_COMMAND` 環境変数で使用できる Proxy スクリプトの例です。このスクリプトは、`example.com:443` への `HTTPS` 接続のみを許可し、それ以外のリクエストはすべて拒否します。 +以下は、`GEMINI_SANDBOX_PROXY_COMMAND` 環境変数で使用できるプロキシスクリプトの例です。このスクリプトは `example.com:443` への `HTTPS` 接続のみを許可し、それ以外のリクエストはすべて拒否します。 ```javascript #!/usr/bin/env node @@ -11,21 +11,21 @@ * SPDX-License-Identifier: Apache-2.0 */ -// :::8877 で listen し、example.com への HTTPS 接続のみを許可する Proxy サーバーの例 -// Proxy を sandbox と一緒に実行するには `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js` を設定してください -// sandbox 内で（shell モードまたは shell tool 経由で）`curl https://example.com` を使ってテストできます +// :::8877 を listen するプロキシサーバーの例。example.com への HTTPS 接続のみを許可します。 +// `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js` を設定して、sandbox と一緒にプロキシを起動します。 +// sandbox 内で（shell モードまたは shell tool 経由で）`curl https://example.com` を実行してテストできます。 -import http from 'http'; -import net from 'net'; -import { URL } from 'url'; -import console from 'console'; +import http from 'node:http'; +import net from 'node:net'; +import { URL } from 'node:url'; +import console from 'node:console'; const PROXY_PORT = 8877; const ALLOWED_DOMAINS = ['example.com', 'googleapis.com']; const ALLOWED_PORT = '443'; const server = http.createServer((req, res) => { - // HTTPS 用の CONNECT 以外のリクエストはすべて拒否 + // HTTPS の CONNECT 以外のリクエストはすべて拒否 console.log( `[PROXY] Denying non-CONNECT request for: ${req.method} ${req.url}`, ); @@ -34,7 +34,7 @@ const server = http.createServer((req, res) => { }); server.on('connect', (req, clientSocket, head) => { - // CONNECT リクエストの場合、req.url は "hostname:port" の形式になります + // req.url は CONNECT リクエストの場合 "hostname:port" 形式になります。 const { port, hostname } = new URL(`http://${req.url}`); console.log(`[PROXY] Intercepted CONNECT request for: ${hostname}:${port}`); @@ -47,10 +47,10 @@ server.on('connect', (req, clientSocket, head) => { ) { console.log(`[PROXY] Allowing connection to ${hostname}:${port}`); - // 実際の宛先への TCP 接続を確立 + // 宛先サーバーへの TCP 接続を確立します。 const serverSocket = net.connect(port, hostname, () => { clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n'); - // クライアントと宛先サーバー間でデータをパイプしてトンネルを確立 + // クライアントと宛先サーバー間でデータをパイプしてトンネルを作成します。 serverSocket.write(head); serverSocket.pipe(clientSocket); clientSocket.pipe(serverSocket); @@ -66,7 +66,7 @@ server.on('connect', (req, clientSocket, head) => { } clientSocket.on('error', (err) => { - // クライアントが接続を切った場合などに発生することがあります + // クライアントが接続を切った場合などに発生します。 console.error(`[PROXY] Client socket error: ${err.message}`); }); }); diff --git a/website/content/ja/extension.md b/website/content/ja/extension.md index dff6fa0d..b82bace0 100644 --- a/website/content/ja/extension.md +++ b/website/content/ja/extension.md @@ -1,17 +1,17 @@ # Qwen Code Extensions -Qwen Code は、機能を設定および拡張するために使用できる Extensions をサポートしています。 +Qwen Code は、機能を設定・拡張するために使用できる Extensions をサポートしています。 ## 動作方法 -起動時に、Qwen Code は以下の 2 つの場所で Extensions を検索します： +起動時に、Qwen Code は以下の2つの場所から Extensions を検索します： 1. `/.qwen/extensions` 2. `/.qwen/extensions` -Qwen Code は両方の場所からすべての Extensions をロードします。同じ名前の Extension が両方の場所に存在する場合、ワークスペースディレクトリ内の Extension が優先されます。 +Qwen Code は両方の場所からすべての Extensions をロードします。同じ名前の Extension が両方の場所に存在する場合、ワークスペースディレクトリにある Extension が優先されます。 -各場所内で、個々の Extensions は `qwen-extension.json` ファイルを含むディレクトリとして存在します。例： +各場所内で、個別の Extensions は `qwen-extension.json` ファイルを含むディレクトリとして存在します。例： `/.qwen/extensions/my-extension/qwen-extension.json` @@ -33,11 +33,11 @@ Qwen Code は両方の場所からすべての Extensions をロードします } ``` -- `name`: エクステンションの名前です。これは、エクステンションを一意に識別し、エクステンションのコマンドがユーザーまたはプロジェクトのコマンドと同じ名前を持つ場合の競合解決に使用されます。 +- `name`: エクステンションの名前です。これは、エクステンションを一意に識別し、エクステンションのコマンドとユーザーまたはプロジェクトのコマンドが同じ名前の場合に競合を解決するために使用されます。 - `version`: エクステンションのバージョンです。 -- `mcpServers`: 設定する MCP サーバーのマップです。キーはサーバーの名前で、値はサーバーの設定です。これらのサーバーは、[`settings.json` ファイル](./cli/configuration.md)で設定された MCP サーバーと同様に、起動時にロードされます。エクステンションと `settings.json` ファイルの両方で同じ名前の MCP サーバーが設定されている場合、`settings.json` ファイルで定義されたサーバーが優先されます。 -- `contextFileName`: エクステンションのコンテキストを含むファイルの名前です。ワークスペースからコンテキストをロードするために使用されます。このプロパティが使用されていないが、エクステンションディレクトリに `QWEN.md` ファイルが存在する場合、そのファイルがロードされます。 -- `excludeTools`: モデルから除外するツール名の配列です。`run_shell_command` ツールのように、対応しているツールについてはコマンド固有の制限を指定することもできます。例えば、`"excludeTools": ["run_shell_command(rm -rf)"]` とすると、`rm -rf` コマンドがブロックされます。 +- `mcpServers`: 設定するMCPサーバーのマップです。キーはサーバーの名前で、値はサーバーの設定です。これらのサーバーは、[`settings.json` ファイル](./cli/configuration.md)で設定されたMCPサーバーと同様に、起動時にロードされます。エクステンションと `settings.json` ファイルの両方で同じ名前のMCPサーバーが設定されている場合、`settings.json` ファイルで定義されたサーバーが優先されます。 +- `contextFileName`: エクステンションのコンテキストを含むファイルの名前です。ワークスペースからコンテキストをロードするために使用されます。このプロパティが使用されていないが、エクステンションディレクトリに `QWEN.md` ファイルが存在する場合は、そのファイルがロードされます。 +- `excludeTools`: モデルから除外するツール名の配列です。`run_shell_command` ツールのように対応しているツールについては、コマンド固有の制限を指定することもできます。例えば、`"excludeTools": ["run_shell_command(rm -rf)"]` とすると、`rm -rf` コマンドがブロックされます。 Qwen Code が起動すると、すべてのエクステンションがロードされ、それらの設定がマージされます。競合がある場合は、ワークスペースの設定が優先されます。 @@ -47,7 +47,7 @@ Qwen Code が起動すると、すべてのエクステンションがロード ### 例 -以下の構造を持つ `gcp` という名前の拡張機能: +以下の構造を持つ `gcp` という名前の拡張機能： ``` .qwen/extensions/gcp/ @@ -58,19 +58,43 @@ Qwen Code が起動すると、すべてのエクステンションがロード └── sync.toml ``` -以下のコマンドを提供します: +以下のコマンドを提供します： - `/deploy` - ヘルプでは `[gcp] Custom command from deploy.toml` として表示 - `/gcs:sync` - ヘルプでは `[gcp] Custom command from sync.toml` として表示 ### コンフリクトの解決 -Extension コマンドは最も低い優先順位を持ちます。ユーザーまたはプロジェクトのコマンドと競合が発生した場合： +拡張機能のコマンドは最も低い優先順位を持ちます。ユーザーまたはプロジェクトのコマンドと競合が発生した場合： -1. **競合なし**: Extension コマンドは本来の名前を使用（例: `/deploy`） -2. **競合あり**: Extension コマンドは拡張機能のプレフィックス付きでリネームされる（例: `/gcp.deploy`） +1. **競合なし**：拡張機能コマンドは本来の名前を使用（例：`/deploy`） +2. **競合あり**：拡張機能コマンドは拡張機能のプレフィックス付きでリネームされる（例：`/gcp.deploy`） -例えば、ユーザーと `gcp` Extension の両方で `deploy` コマンドが定義されている場合： +例えば、ユーザーと `gcp` 拡張機能の両方で `deploy` コマンドが定義されている場合： - `/deploy` - ユーザーの deploy コマンドを実行 -- `/gcp.deploy` - Extension の deploy コマンドを実行（`[gcp]` タグ付き） \ No newline at end of file +- `/gcp.deploy` - 拡張機能の deploy コマンドを実行（`[gcp]` タグ付き） + +## 拡張機能のインストール + +`install` コマンドを使って拡張機能をインストールできます。このコマンドでは Git リポジトリまたはローカルパスから拡張機能をインストール可能です。 + +### 使い方 + +`qwen extensions install | [options]` + +### オプション + +- `source 位置引数`: 拡張機能をインストールする Git リポジトリの URL。リポジトリのルートには `qwen-extension.json` ファイルが含まれている必要があります。 +- `--path `: 拡張機能としてインストールするローカルディレクトリへのパス。ディレクトリには `qwen-extension.json` ファイルが含まれている必要があります。 + +# 変数 + +Qwen Code 拡張機能では、`qwen-extension.json` 内で変数の置換が可能です。例えば、MCP サーバーを実行する際にカレントディレクトリが必要な場合、`"cwd": "${extensionPath}${/}run.ts"` のように指定できます。 + +**サポートされている変数:** + +| 変数 | 説明 | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `${extensionPath}` | ユーザーのファイルシステムにおける拡張機能の絶対パス（例: '/Users/username/.qwen/extensions/example-extension'）。シンボリックリンクは展開されません。 | +| `${/} or ${pathSeparator}` | パス区切り文字（OS によって異なります）。 | \ No newline at end of file diff --git a/website/content/ja/gemini-ignore.md b/website/content/ja/gemini-ignore.md index 9d819db2..a227f7b0 100644 --- a/website/content/ja/gemini-ignore.md +++ b/website/content/ja/gemini-ignore.md @@ -8,7 +8,7 @@ Qwen Code には、ファイルを自動的に無視する機能が含まれて `.geminiignore` ファイルにパスを追加すると、このファイルを尊重するツールは、一致するファイルやディレクトリを操作から除外します。例えば、[`read_many_files`](./tools/multi-file.md) コマンドを使用する際、`.geminiignore` ファイル内のすべてのパスは自動的に除外されます。 -基本的に、`.geminiignore` は `.gitignore` ファイルの慣習に従います： +基本的に、`.geminiignore` は `.gitignore` ファイルの規則に従います： - 空行や `#` で始まる行は無視されます。 - 標準的な glob パターンがサポートされています（例：`*`、`?`、`[]`）。 @@ -50,7 +50,7 @@ apikeys.txt *.md ``` -最後に、`!` を使って除外対象からファイルやディレクトリを除外解除できます： +最後に、`!` を使って除外対象から特定のファイルやディレクトリを除外解除できます： ``` diff --git a/website/content/ja/ide-integration.md b/website/content/ja/ide-integration.md index 99f05581..b7151643 100644 --- a/website/content/ja/ide-integration.md +++ b/website/content/ja/ide-integration.md @@ -1,21 +1,21 @@ -# IDE Integration +# IDE連携 -Qwen Code は、IDE との連携により、よりシームレスでコンテキストを意識した体験を提供できます。この連携により、CLI はワークスペースをより適切に理解し、エディタ内でのネイティブな diff 機能などの強力な機能が利用可能になります。 +Qwen Codeは、IDEと連携することで、よりシームレスでコンテキストを理解したエクスペリエンスを提供できます。この連携により、CLIがワークスペースをより適切に理解できるようになり、エディタ内でのネイティブな差分表示などの強力な機能が利用可能になります。 -現在サポートされている IDE は [Visual Studio Code](https://code.visualstudio.com/) および VS Code 拡張機能をサポートする他のエディタのみです。 +現在サポートされているIDEは[Visual Studio Code](https://code.visualstudio.com/)およびVS Code拡張機能に対応する他のエディタのみです。 ## 機能 - **ワークスペースコンテキスト:** CLIは自動的にワークスペースの状況を把握し、より関連性が高く正確なレスポンスを提供します。このコンテキストには以下が含まれます： - - ワークスペース内で**最近アクセスした上位10ファイル**。 - - 現在のカーソル位置。 - - 選択中のテキスト（最大16KBまで。それ以上は切り捨てられます）。 + - ワークスペース内で**最近アクセスした上位10ファイル** + - 現在のカーソル位置 + - 選択中のテキスト（最大16KBまで。それ以上は切り捨てられます） - **ネイティブDiff表示:** Qwenがコード変更を提案する際、IDEのネイティブdiffビューア内で直接変更内容を確認できます。これにより、提案された変更をシームレスにレビュー、編集、承認または拒否することが可能になります。 - **VS Codeコマンド:** VS Codeのコマンドパレット（`Cmd+Shift+P` または `Ctrl+Shift+P`）から直接Qwen Codeの機能にアクセスできます： - `Qwen Code: Run`: 統合ターミナルで新しいQwen Codeセッションを開始します。 - - `Qwen Code: Accept Diff`: アクティブなdiffエディタ内の変更を承認します。 + - `Qwen Code: Accept Diff`: アクティブなdiffエディタの変更を承認します。 - `Qwen Code: Close Diff Editor`: 変更を拒否し、アクティブなdiffエディタを閉じます。 - `Qwen Code: View Third-Party Notices`: 拡張機能のサードパーティ通知を表示します。 @@ -25,26 +25,29 @@ IDE連携のセットアップには3つの方法があります： ### 1. 自動案内（推奨） -サポートされているエディタ内でQwen Codeを実行すると、自動的に環境を検出し、接続を促す案内が表示されます。「Yes」と答えることで、必要なセットアップが自動的に実行されます。これには、連携用拡張機能のインストールと接続の有効化が含まれます。 +サポートされているエディタ内でQwen Codeを実行すると、環境を自動的に検出し、接続を促す案内が表示されます。"Yes"と答えることで、必要なセットアップが自動的に実行され、これにはコンパニオン拡張機能のインストールと接続の有効化が含まれます。 ### 2. CLIからの手動インストール -以前に案内を閉じてしまった場合や、手動で拡張機能をインストールしたい場合は、Qwen Code内で以下のコマンドを実行してください： +以前に案内を-dismissした場合や、拡張機能を手動でインストールしたい場合は、Qwen Code内で以下のコマンドを実行できます： ``` /ide install ``` -このコマンドにより、ご利用のIDEに適した拡張機能が検出され、インストールされます。 +このコマンドは、お使いのIDEに適した拡張機能を見つけ出してインストールします。 ### 3. マーケットプレイスからの手動インストール エクステンションは、マーケットプレイスから直接インストールすることもできます。 -- **Visual Studio Codeの場合:** [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion) からインストールしてください。 -- **VS Codeのフォーク版の場合:** VS Codeのフォーク版をサポートするため、このエクステンションは[Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion)にも公開されています。お使いのエディタの指示に従って、このレジストリからエクステンションをインストールしてください。 +- **Visual Studio Code 向け:** [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion) からインストールしてください。 +- **VS Code フォーク向け:** VS Code のフォークをサポートするため、このエクステンションは [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion) にも公開されています。お使いのエディタの指示に従って、このレジストリからエクステンションをインストールしてください。 -どのインストール方法を選んでも、インテグレーションが正しく有効化されるように、新しいターミナルウィンドウを開くことを推奨します。インストールが完了したら、`/ide enable` を使用して接続できます。 +> NOTE: +> 「Qwen Code Companion」エクステンションは検索結果の下の方に表示されることがあります。すぐに見つからない場合は、スクロールダウンするか、「Newly Published」でソートしてみてください。 +> +> エクステンションを手動でインストールした後、CLI で `/ide enable` を実行して連携機能を有効化する必要があります。 ## 使用方法 @@ -61,23 +64,23 @@ CLI から IDE 連携をコントロールできます： /ide disable ``` -有効にすると、Qwen Code は自動的に IDE companion extension への接続を試みます。 +有効にすると、Qwen Code は自動的に IDE の companion extension への接続を試みます。 ### ステータスの確認 -接続ステータスを確認し、CLI が IDE から受け取ったコンテキストを表示するには、以下を実行してください： +接続ステータスを確認し、CLI が IDE から受け取ったコンテキストを表示するには、以下を実行します： ``` /ide status ``` -接続されている場合、このコマンドは接続中の IDE と、認識している最近開いたファイルのリストを表示します。 +接続されている場合、このコマンドでは接続中の IDE と、認識している最近開いたファイルの一覧が表示されます。 -（注：ファイルリストはワークスペース内で最近アクセスした 10 個のファイルに限定され、ローカルディスク上のファイルのみが含まれます。） +（注：ファイル一覧はワークスペース内で最近アクセスした 10 個のファイルに限定され、ローカルディスク上のファイルのみが含まれます。） ### Diff との連携 -Gemini にファイルの変更を依頼すると、エディタ内で直接 diff ビューを開くことができます。 +Qwen モデルにファイルの変更を依頼すると、エディタ内で直接 diff ビューを開くことができます。 **Diff を適用するには**、以下のいずれかの操作を行ってください： @@ -86,23 +89,23 @@ Gemini にファイルの変更を依頼すると、エディタ内で直接 dif - Command Palette を開き、**Qwen Code: Accept Diff** を実行する。 - CLI でプロンプトが表示されたら `yes` と応答する。 -**Diff を拒否するには**、以下の操作を行ってください： +**Diff を拒否するには**、以下の操作が可能です： - diff エディタのタイトルバーにある **'x' アイコン** をクリックする。 - diff エディタのタブを閉じる。 - Command Palette を開き、**Qwen Code: Close Diff Editor** を実行する。 - CLI でプロンプトが表示されたら `no` と応答する。 -また、適用前に diff ビュー内で **提案された変更を直接編集** することも可能です。 +また、適用前に diff ビュー内で**提案された変更を直接編集**することもできます。 -CLI で「Yes, allow always」を選択すると、変更は IDE に表示されず、自動的に適用されるようになります。 +CLI で「Yes, allow always」を選択すると、変更は IDE に表示されなくなり、自動的に適用されるようになります。 ## サンドボックス環境での使用 Qwen Codeをサンドボックス内で使用する場合、以下の点に注意してください： -- **macOSの場合：** IDE連携機能は、IDE用のcompanion extensionと通信するためにネットワークアクセスが必要です。ネットワークアクセスを許可するSeatbeltプロファイルを使用する必要があります。 -- **Dockerコンテナ内の場合：** Docker（またはPodman）コンテナ内でQwen Codeを実行する場合でも、ホストマシン上で動作しているVS Code extensionにIDE連携機能は接続可能です。CLIは自動的に`host.docker.internal`上のIDEサーバーを見つけられるように設定されています。通常は特別な設定は必要ありませんが、コンテナからホストへの接続を許可するようにDockerのネットワーク設定を調整する必要があるかもしれません。 +- **macOSの場合：** IDE連携機能は、IDE用のコンパニオン拡張機能と通信するためにネットワークアクセスが必要です。ネットワークアクセスを許可するSeatbeltプロファイルを使用する必要があります。 +- **Dockerコンテナ内の場合：** Docker（またはPodman）コンテナ内でQwen Codeを実行する場合でも、IDE連携機能はホストマシン上で動作しているVS Code拡張機能に接続できます。CLIは自動的に`host.docker.internal`上のIDEサーバーを見つけるように設定されています。通常、特別な設定は必要ありませんが、コンテナからホストへの接続を許可するようにDockerのネットワーク設定を確認する必要があるかもしれません。 ## トラブルシューティング @@ -114,7 +117,7 @@ IDE連携機能で問題が発生した場合、以下によくあるエラー - **原因:** Qwen Code が IDE に接続するために必要な環境変数（`QWEN_CODE_IDE_WORKSPACE_PATH` または `QWEN_CODE_IDE_SERVER_PORT`）を見つけられませんでした。これは通常、IDE companion extension が実行されていないか、正しく初期化されていないことを意味します。 - **解決方法:** 1. IDE に **Qwen Code Companion** extension がインストールされており、有効になっていることを確認してください。 - 2. 正しい環境変数を取得するために、IDE で新しい terminal ウィンドウを開いてください。 + 2. 正しい環境変数を取得するために、IDE 内で新しい terminal ウィンドウを開いてください。 - **メッセージ:** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` - **原因:** IDE companion への接続が失われました。 @@ -126,16 +129,16 @@ IDE連携機能で問題が発生した場合、以下によくあるエラー - **原因:** CLIの現在の作業ディレクトリが、IDEで開いているフォルダまたはワークスペースとは異なる場所にある。 - **解決方法:** IDEで開いているのと同じディレクトリに`cd`して、CLIを再起動してください。 -- **メッセージ:** `🔴 Disconnected: To use this feature, please open a single workspace folder in [IDE Name] and try again.` - - **原因:** IDEで複数のワークスペースフォルダが開いている、またはフォルダがまったく開かれていない。IDE連携機能が正しく動作するには、単一のルートワークスペースフォルダが必要です。 - - **解決方法:** IDEで単一のプロジェクトフォルダを開き、CLIを再起動してください。 +- **メッセージ:** `🔴 Disconnected: To use this feature, please open a workspace folder in [IDE Name] and try again.` + - **原因:** IDEにワークスペースが開かれていない。 + - **解決方法:** IDEでワークスペースを開き、CLIを再起動してください。 ### 一般的なエラー - **メッセージ:** `IDE integration is not supported in your current environment. To use this feature, run Qwen Code in one of these supported IDEs: [List of IDEs]` - - **原因:** 現在の環境（ターミナルなど）は、サポートされている IDE ではない。 - - **解決方法:** VS Code などの対応 IDE に内蔵されているターミナルから Qwen Code を実行してください。 + - **原因:** 現在の環境（ターミナルなど）は、サポートされている IDE ではないため、Qwen Code が実行されています。 + - **解決方法:** VS Code などのサポートされている IDE に内蔵されているターミナルから Qwen Code を実行してください。 -- **メッセージ:** `No installer is available for [IDE Name]. Please install the IDE companion manually from its marketplace.` - - **原因:** `/ide install` を実行したが、使用している IDE に対して CLI による自動インストールがサポートされていない。 - - **解決方法:** 利用している IDE の拡張機能マーケットプレイスを開き、「Qwen Code Companion」を検索して手動でインストールしてください。 \ No newline at end of file +- **メッセージ:** `No installer is available for IDE. Please install the Qwen Code Companion extension manually from the marketplace.` + - **原因:** `/ide install` を実行しましたが、CLI にあなたの使用している IDE 用の自動インストーラーが用意されていません。 + - **解決方法:** ご利用の IDE の拡張機能マーケットプレイスを開き、「Qwen Code Companion」を検索して手動でインストールしてください。 \ No newline at end of file diff --git a/website/content/ja/index.md b/website/content/ja/index.md index 3e2ef944..a421201f 100644 --- a/website/content/ja/index.md +++ b/website/content/ja/index.md @@ -1,40 +1,40 @@ # Qwen Code ドキュメントへようこそ -このドキュメントでは、Qwen Code のインストール、使用方法、開発に関する包括的なガイドを提供します。このツールを使うと、コマンドラインインターフェースを通じて AI モデルとやり取りできます。 +このドキュメントでは、Qwen Code のインストール、使用、開発に関する包括的なガイドを提供します。このツールを使用すると、コマンドラインインターフェースを通じて AI モデルとやり取りできます。 ## 概要 -Qwen Code は、高度なコードモデルの機能を対話型の Read-Eval-Print Loop (REPL) 環境でターミナルに持ち込みます。Qwen Code は、ローカルサーバー（`packages/core`）と通信するクライアントサイドアプリケーション（`packages/cli`）で構成されています。また、Qwen Code には、ファイルシステム操作、シェルの実行、Web リクエストなどを行うためのさまざまなツールが含まれており、これらは `packages/core` によって管理されています。 +Qwen Code は、高度なコードモデルの機能を対話型の Read-Eval-Print Loop (REPL) 環境でターミナルに提供します。Qwen Code は、ローカルサーバー（`packages/core`）と通信するクライアントサイドアプリケーション（`packages/cli`）で構成されています。また、Qwen Code には、ファイルシステム操作の実行、シェルの実行、Web フェッチなどのタスク用のさまざまなツールが含まれており、これらは `packages/core` によって管理されています。 ## ドキュメントのナビゲーション -このドキュメントは以下のセクションに分かれています： +このドキュメントは以下のセクションに整理されています： - **[実行とデプロイ](./deployment.md)：** Qwen Code を実行するための情報。 - **[アーキテクチャ概要](./architecture.md)：** コンポーネントとその相互作用を含む、Qwen Code の高レベル設計を理解します。 -- **CLI Usage：** `packages/cli` のドキュメント。 - - **[CLI イントロダクション](./cli/index.md)：** コマンドラインインターフェースの概要。 - - **[コマンド](./cli/commands.md)：** 利用可能な CLI コマンドの説明。 +- **CLI の使用方法：** `packages/cli` のドキュメント。 + - **[CLI の紹介](./cli/index.md)：** コマンドラインインターフェースの概要。 + - **[コマンド一覧](./cli/commands.md)：** 利用可能な CLI コマンドの説明。 - **[設定](./cli/configuration.md)：** CLI の設定に関する情報。 - - **[チェックポイント](./checkpointing.md)：** チェックポイント機能のドキュメント。 + - **[チェックポイント機能](./checkpointing.md)：** チェックポイント機能のドキュメント。 - **[拡張機能](./extension.md)：** 新しい機能で CLI を拡張する方法。 - **[IDE との連携](./ide-integration.md)：** CLI をエディタに接続する方法。 - **[テレメトリ](./telemetry.md)：** CLI 内のテレメトリの概要。 -- **Core Details：** `packages/core` のドキュメント。 - - **[Core イントロダクション](./core/index.md)：** コアコンポーネントの概要。 - - **[Tools API](./core/tools-api.md)：** コアがツールを管理・公開する方法に関する情報。 -- **Tools：** +- **Core の詳細：** `packages/core` のドキュメント。 + - **[Core の紹介](./core/index.md)：** Core コンポーネントの概要。 + - **[Tools API](./core/tools-api.md)：** Core がツールを管理・公開する方法に関する情報。 +- **ツール：** - **[ツールの概要](./tools/index.md)：** 利用可能なツールの概要。 - **[ファイルシステムツール](./tools/file-system.md)：** `read_file` および `write_file` ツールのドキュメント。 - - **[マルチファイル読み込みツール](./tools/multi-file.md)：** `read_many_files` ツールのドキュメント。 + - **[複数ファイル読み込みツール](./tools/multi-file.md)：** `read_many_files` ツールのドキュメント。 - **[シェルツール](./tools/shell.md)：** `run_shell_command` ツールのドキュメント。 - **[Web フェッチツール](./tools/web-fetch.md)：** `web_fetch` ツールのドキュメント。 - **[Web 検索ツール](./tools/web-search.md)：** `web_search` ツールのドキュメント。 - **[メモリーツール](./tools/memory.md)：** `save_memory` ツールのドキュメント。 -- **[サブエージェント](./subagents.md)：** 専門的なタスクに対応した AI アシスタントで、包括的な管理・設定・使用方法を提供します。 +- **[サブエージェント](./subagents.md)：** 特定のタスクに特化した AI アシスタントで、包括的な管理、設定、使用方法のガイダンスを提供します。 - **[貢献と開発ガイド](../CONTRIBUTING.md)：** 貢献者および開発者のための情報。セットアップ、ビルド、テスト、コーディング規則などを含みます。 -- **[NPM Workspaces とパブリッシュ](./npm.md)：** プロジェクトのパッケージがどのように管理・公開されているかの詳細。 -- **[トラブルシューティングガイド](./troubleshooting.md)：** 一般的な問題や FAQ の解決策を見つけます。 +- **[NPM](./npm.md)：** プロジェクトのパッケージ構造に関する詳細。 +- **[トラブルシューティングガイド](./troubleshooting.md)：** よくある問題と FAQ の解決方法を紹介します。 - **[利用規約およびプライバシー通知](./tos-privacy.md)：** Qwen Code の利用に適用される利用規約およびプライバシー通知に関する情報。 -このドキュメントがあなたが Qwen Code を最大限に活用するお手伝いができることを願っています！ \ No newline at end of file +このドキュメントが、Qwen Code を最大限に活用するお手伝いができることを願っています！ \ No newline at end of file diff --git a/website/content/ja/keyboard-shortcuts.md b/website/content/ja/keyboard-shortcuts.md index f740313d..cba23e8e 100644 --- a/website/content/ja/keyboard-shortcuts.md +++ b/website/content/ja/keyboard-shortcuts.md @@ -4,16 +4,16 @@ ## 一般 -| ショートカット | 説明 | -| -------- | --------------------------------------------------------------------------------------------------------------------- | -| `Esc` | ダイアログとサジェストを閉じる。 | -| `Ctrl+C` | 進行中のリクエストをキャンセルし、入力をクリアする。2回押すとアプリケーションを終了する。 | -| `Ctrl+D` | 入力が空の場合、アプリケーションを終了する。2回押して確認する。 | -| `Ctrl+L` | 画面をクリアする。 | -| `Ctrl+O` | デバッグコンソールの表示を切り替える。 | -| `Ctrl+S` | 長いレスポンスを完全に表示できるようにし、切り捨てを無効にする。端末のスクロールバックを使用して 전체出力を表示する。 | -| `Ctrl+T` | ツールの説明表示を切り替える。 | -| `Ctrl+Y` | すべてのツール呼び出しに対して自動承認（YOLOモード）を切り替える。 | +| ショートカット | 説明 | +| -------------- | ------------------------------------------------------------------------------------------------------------------------ | +| `Esc` | ダイアログとサジェストを閉じる。 | +| `Ctrl+C` | 進行中のリクエストをキャンセルし、入力をクリアする。2回押すとアプリケーションを終了する。 | +| `Ctrl+D` | 入力が空の場合、アプリケーションを終了する。2回押して確認する。 | +| `Ctrl+L` | 画面をクリアする。 | +| `Ctrl+O` | デバッグコンソールの表示を切り替える。 | +| `Ctrl+S` | 長いレスポンスを完全に表示できるようにし、切り捨てを無効にする。端末のスクロールバック機能を使用して全体の出力を確認する。 | +| `Ctrl+T` | ツールの説明表示を切り替える。 | +| `Shift+Tab` | 承認モードを切り替える (`plan` → `default` → `auto-edit` → `yolo`)。 | ## 入力プロンプト @@ -26,20 +26,21 @@ | `Meta+Delete` / `Ctrl+Delete` | カーソルの右側の単語を削除する。 | | `Tab` | サジェストがある場合は、現在のサジェストを自動補完する。 | | `Up Arrow` | 入力履歴を上に移動する。 | -| `Ctrl+A` / `Home` | カーソルを行頭に移動する。 | -| `Ctrl+B` / `Left Arrow` | カーソルを左に1文字移動する。 | +| `Ctrl+A` / `Home` | 行頭にカーソルを移動する。 | +| `Ctrl+B` / `Left Arrow` | カーソルを1文字左に移動する。 | | `Ctrl+C` | 入力プロンプトをクリアする。 | +| `Esc` (ダブルプレス) | 入力プロンプトをクリアする。 | | `Ctrl+D` / `Delete` | カーソルの右側の文字を削除する。 | -| `Ctrl+E` / `End` | カーソルを行末に移動する。 | -| `Ctrl+F` / `Right Arrow` | カーソルを右に1文字移動する。 | +| `Ctrl+E` / `End` | 行末にカーソルを移動する。 | +| `Ctrl+F` / `Right Arrow` | カーソルを1文字右に移動する。 | | `Ctrl+H` / `Backspace` | カーソルの左側の文字を削除する。 | | `Ctrl+K` | カーソル位置から行末までを削除する。 | -| `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B` | カーソルを左に1単語移動する。 | +| `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B` | カーソルを1単語左に移動する。 | | `Ctrl+N` | 入力履歴を下に移動する。 | | `Ctrl+P` | 入力履歴を上に移動する。 | -| `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F` | カーソルを右に1単語移動する。 | +| `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F` | カーソルを1単語右に移動する。 | | `Ctrl+U` | カーソル位置から行頭までを削除する。 | -| `Ctrl+V` | クリップボードの内容を貼り付ける。クリップボードに画像が含まれている場合、画像は保存され、その参照がプロンプトに挿入される。 | +| `Ctrl+V` | クリップボードの内容を貼り付ける。クリップボードに画像が含まれている場合、それは保存され、その参照がプロンプトに挿入される。 | | `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace` | カーソルの左側の単語を削除する。 | | `Ctrl+X` / `Meta+Enter` | 現在の入力を外部エディタで開く。 | @@ -65,4 +66,4 @@ | ショートカット | 説明 | | -------------- | ------------------------------- | -| `Ctrl+G` | IDE から受け取った context CLI を表示 | \ No newline at end of file +| `Ctrl+G` | IDE から受信した CLI コンテキストを表示 | \ No newline at end of file diff --git a/website/content/ja/qwen-ignore.md b/website/content/ja/qwen-ignore.md new file mode 100644 index 00000000..3f0ddde3 --- /dev/null +++ b/website/content/ja/qwen-ignore.md @@ -0,0 +1,62 @@ +# ファイルの無視 + +このドキュメントでは、Qwen Code の Qwen Ignore (`.qwenignore`) 機能の概要を説明します。 + +Qwen Code には、ファイルを自動的に無視する機能が含まれています。これは `.gitignore` (Git で使用される) と同様のものです。`.qwenignore` ファイルにパスを追加することで、この機能をサポートするツールからそれらのファイルを除外できますが、他のサービス (Git など) からは引き続き表示されます。 + +## 仕組み + +`.qwenignore` ファイルにパスを追加すると、このファイルを尊重するツールは、操作から該当するファイルやディレクトリを除外します。例えば、[`read_many_files`](./tools/multi-file.md) コマンドを使用する際、`.qwenignore` ファイル内のすべてのパスは自動的に除外されます。 + +大まかに言えば、`.qwenignore` は `.gitignore` ファイルの慣習に従います： + +- 空行や `#` で始まる行は無視されます。 +- 標準的な glob パターンがサポートされています（例：`*`、`?`、`[]`）。 +- 末尾に `/` を置くと、ディレクトリのみにマッチします。 +- 先頭に `/` を置くと、`.qwenignore` ファイルからの相対パスとして扱われます。 +- `!` はパターンを否定します。 + +`.qwenignore` ファイルはいつでも更新可能です。変更を適用するには、Qwen Code セッションを再起動する必要があります。 + +## `.qwenignore` の使い方 + +`.qwenignore` を有効にするには： + +1. プロジェクトディレクトリのルートに `.qwenignore` という名前のファイルを作成します。 + +ファイルやディレクトリを `.qwenignore` に追加するには： + +1. `.qwenignore` ファイルを開きます。 +2. 無視したいパスまたはファイルを追加します。例：`/archive/` や `apikeys.txt`。 + +### `.qwenignore` の例 + +`.qwenignore` を使ってディレクトリやファイルを無視できます： + +``` + +# /packages/ ディレクトリとそのサブディレクトリを除外 +/packages/ + +# apikeys.txt ファイルを除外 +apikeys.txt +``` + +`.qwenignore` ファイルでは `*` を使ってワイルドカードが使えます： + +``` + +# すべての .md ファイルを除外 +*.md +``` + +最後に、`!` を使って除外対象から特定のファイルやディレクトリを除外解除できます： + +``` + +# README.md を除くすべての .md ファイルを除外 +*.md +!README.md +``` + +`.qwenignore` ファイルからパスを削除するには、該当する行を削除してください。 \ No newline at end of file diff --git a/website/content/ja/subagents.md b/website/content/ja/subagents.md index ff4d42bd..a7b7a9e7 100644 --- a/website/content/ja/subagents.md +++ b/website/content/ja/subagents.md @@ -1,16 +1,16 @@ # サブエージェント -サブエージェントは、Qwen Code 内で特定のタスクを処理するための専門的な AI アシスタントです。タスクに特化したプロンプト、ツール、および動作で構成された AI エージェントに、特定の作業を委任することができます。 +サブエージェントは、Qwen Code 内で特定のタスクを処理するための専門的な AI アシスタントです。タスクに特化したプロンプト、ツール、および動作が設定された AI エージェントに、集中的な作業を委任することができます。 ## サブエージェントとは？ サブエージェントとは、以下のような特徴を持つ独立した AI アシスタントです： -- **特定のタスクに特化** - 各サブエージェントは、特定の作業向けに特化したシステムプロンプトで構成されています -- **独立したコンテキストを持つ** - メインチャットとは別に、独自の会話履歴を保持します -- **制御されたツールを使用** - 各サブエージェントが利用できるツールを個別に設定できます -- **自律的に動作** - タスクを割り当てられると、完了または失敗するまで独立して動作します -- **詳細なフィードバックを提供** - 進行状況、ツールの使用状況、実行統計をリアルタイムで確認できます +- **特定のタスクに特化** - 各サブエージェントには、特定の作業向けに焦点を当てたシステムプロンプトが設定されています +- **独立したコンテキストを持ちます** - メインチャットとは別に、独自の会話履歴を保持します +- **制御されたツールを使用** - 各サブエージェントが利用できるツールを個別に設定できます +- **自律的に動作** - タスクが与えられると、完了または失敗するまで独立して動作します +- **詳細なフィードバックを提供** - 進行状況、使用ツール、実行統計情報をリアルタイムで確認できます ## 主要なメリット @@ -45,31 +45,31 @@ /agents manage ``` - 設定済みのサブエージェントを表示・管理できます。 + 設定済みのサブエージェントを表示・管理します。 3. **サブエージェントを自動的に使用する**: - メインのAIに、サブエージェントの専門領域に合致するタスクを依頼するだけです。AIが自動的に適切な作業を委譲します。 + メインのAIに、サブエージェントの専門領域に合致するタスクを実行するように依頼するだけです。AIが自動的に適切な作業を委任します。 ### 使用例 ``` User: "認証モジュールの包括的なテストを書いてください" -AI: これをテスト専門のサブエージェントに委譲します。 -[Delegates to "testing-expert" subagent] +AI: これをテスト専門のサブエージェントに委任します。 +[「testing-expert」サブエージェントに委任] [テスト作成のリアルタイム進捗を表示] [完了したテストファイルと実行サマリを返却] ``` ## 管理 -### CLI コマンド +### CLIコマンド -サブエージェントは、`/agents` スラッシュコマンドおよびそのサブコマンドを通じて管理されます： +サブエージェントは、`/agents` スラッシュコマンドとそのサブコマンドを通じて管理されます： #### `/agents create` -ガイド付きステップ・ウィザードで新しいサブエージェントを作成します。 +ガイド付きステップウィザードで新しいサブエージェントを作成します。 **使用方法:** @@ -91,14 +91,14 @@ AI: これをテスト専門のサブエージェントに委譲します。 サブエージェントは以下の2つの場所に Markdown ファイルとして保存されます： -- **プロジェクトレベル**: `.qwen/agents/`（優先） -- **ユーザーレベル**: `~/.qwen/agents/`（フォールバック） +- **プロジェクトレベル**: `.qwen/agents/`（優先的に使用） +- **ユーザーレベル**: `~/.qwen/agents/`（フォールバック用） これにより、プロジェクト固有のエージェントと、すべてのプロジェクトで使用できる個人用エージェントの両方を持つことができます。 ### ファイル形式 -サブエージェントは、YAML frontmatter を含む Markdown ファイルを使用して設定されます。この形式は人間が読みやすく、任意のテキストエディタで簡単に編集できます。 +サブエージェントは、YAML frontmatter を含む Markdown ファイルで設定されます。この形式は人間が読みやすく、任意のテキストエディタで簡単に編集できます。 #### 基本構造 @@ -111,7 +111,7 @@ tools: tool1, tool2, tool3 # 任意 システムプロンプトの内容をここに記述します。 複数の段落に対応しています。 -動的なコンテンツには ${variable} 形式のテンプレートを使用できます。 +動的なコンテンツには ${variable} 形式のテンプレートが使用できます。 ``` #### 使用例 @@ -119,7 +119,7 @@ tools: tool1, tool2, tool3 # 任意 ```markdown --- name: project-documenter -description: プロジェクトのドキュメントとREADMEファイルを作成 +description: プロジェクトのドキュメントとREADMEファイルを作成します --- あなたは${project_name}プロジェクトのドキュメントスペシャリストです。 @@ -133,9 +133,31 @@ description: プロジェクトのドキュメントとREADMEファイルを作 明確で包括的なドキュメントを作成することに重点を置いてください。 ``` +## サブエージェントを効果的に使用する + +### 自動委任 + +Qwen Codeは以下に基づいて積極的にタスクを委任します： + +- リクエスト内のタスク説明 +- サブエージェント設定のdescriptionフィールド +- 現在のコンテキストと利用可能なツール + +より積極的なサブエージェントの使用を促進するには、descriptionフィールドに「PROACTIVELYを使用」や「必ず使用する必要がある」などのフレーズを含めてください。 + +### 明示的な呼び出し + +コマンド内で特定のサブエージェントを指定してリクエストします： + +``` +> testing-expert サブエージェントに支払いモジュールのユニットテストを作成させる +> documentation-writer サブエージェントにAPIリファレンスを更新させる +> react-specialist サブエージェントにこのコンポーネントのパフォーマンスを最適化させる +``` + ## 例 -### 開発ワークフロー Agents +### 開発ワークフロー用エージェント #### Testing Specialist @@ -155,27 +177,27 @@ tools: read_file, write_file, read_many_files, run_shell_command - 適切なモックと分離によるユニットテスト - コンポーネント間の相互作用を検証する結合テスト - テスト駆動開発（TDD）のプラクティス -- エッジケースの特定と網羅的なテストカバレッジ -- 必要に応じたパフォーマンステストと負荷テスト +- エッジケースの特定と網羅的なカバレッジ +- 必要に応じたパフォーマンステストおよび負荷テスト -各テストタスクに対して以下の手順を実施します： +各テストタスクに対して以下の手順を踏んでください： -1. コード構造と依存関係を分析 -2. 主要機能、エッジケース、エラー条件を特定 -3. 説明的な名前を持つ網羅的なテストスイートを作成 -4. 適切なセットアップ／ティアダウンと意味のあるアサーションを含める -5. 複雑なテストシナリオを説明するコメントを追加 -6. テストが保守可能であり、DRY原則に従っていることを確認 - -常に検出された言語とフレームワークに適したテストのベストプラクティスに従ってください。 -正常系と異常系の両方のテストケースに焦点を当ててください。 +1. コード構造と依存関係を分析する +2. 主要機能、エッジケース、エラー条件を特定する +3. 説明的な名前を持つ包括的なテストスイートを作成する +4. 適切なセットアップ／テアダウン処理と意味のあるアサーションを含める +5. 複雑なテストシナリオについてはコメントを追加する +6. テストが保守可能であり、DRY原則に従っていることを確認する + +常に検出された言語とフレームワークにおけるテストのベストプラクティスに従ってください。 +正常系だけでなく異常系のテストケースにも注目してください。 ``` **Use Cases:** - "認証サービスのユニットテストを書く" - "支払い処理ワークフローの結合テストを作成する" -- "データ検証モジュールのエッジケースに対するテストカバレッジを追加する" +- "データバリデーションモジュールのエッジケースに対するテストカバレッジを追加する" #### Documentation Writer @@ -188,7 +210,7 @@ description: 包括的なドキュメント、READMEファイル、APIドキュ tools: read_file, write_file, read_many_files, web_search --- -あなたは${project_name}の技術ドキュメントスペシャリストです。 +あなたは ${project_name} の技術ドキュメントスペシャリストです。 あなたの役割は、開発者とエンドユーザーの両方に役立つ、明確で包括的なドキュメントを作成することです。以下の点に重点を置いてください： @@ -210,9 +232,9 @@ tools: read_file, write_file, read_many_files, web_search **開発者ドキュメント向け：** -- アーキテクチャ概要と設計判断 +- アーキテクチャ概要と設計決定 - 実際に動作するコード例 -- コントリビューションガイドライン +- コントリビュートガイドライン - 開発環境のセットアップ 常にコード例を検証し、ドキュメントが実際の実装と同期していることを確認してください。明確な見出し、箇条書き、サンプルを使用してください。 @@ -220,55 +242,55 @@ tools: read_file, write_file, read_many_files, web_search **ユースケース：** -- "ユーザー管理エンドポイントのAPIドキュメントを作成" -- "このプロジェクトの包括的なREADMEを書く" -- "トラブルシューティング手順付きでデプロイメントプロセスをドキュメント化" +- "ユーザー管理エンドポイントのAPIドキュメントを作成してください" +- "このプロジェクトの包括的なREADMEを書いてください" +- "トラブルシューティング手順付きでデプロイメントプロセスをドキュメント化してください" #### Code Reviewer -コードの品質、セキュリティ、およびベストプラクティスに焦点を当てたレビューを行う。 +コードの品質、セキュリティ、およびベストプラクティスに焦点を当てています。 ```markdown --- name: code-reviewer -description: ベストプラクティス、セキュリティ問題、パフォーマンス、および保守性の観点からコードをレビューします +description: Reviews code for best practices, security issues, performance, and maintainability tools: read_file, read_many_files --- -あなたは品質、セキュリティ、保守性にフォーカスした経験豊富なコードレビュアーです。 +あなたは品質、セキュリティ、保守性に重点を置いた経験豊富なコードレビュアーです。 -レビュー基準: +レビュー基準： -- **コード構造**: オーガニゼーション、モジュール性、関心の分離 -- **パフォーマンス**: アルゴリズムの効率性とリソース使用量 -- **セキュリティ**: 脆弱性評価とセキュアコーディングプラクティス -- **ベストプラクティス**: 言語/フレームワーク固有の規約 -- **エラーハンドリング**: 適切な例外処理とエッジケースのカバレッジ -- **可読性**: 明確な命名、コメント、コード構成 -- **テスト**: テストカバレッジとテスト容易性の考慮事項 +- **コード構造**：組織化、モジュール性、関心の分離 +- **パフォーマンス**：アルゴリズム効率とリソース使用量 +- **セキュリティ**：脆弱性評価とセキュアコーディングプラクティス +- **ベストプラクティス**：言語/フレームワーク固有の規約 +- **エラーハンドリング**：適切な例外処理とエッジケースのカバレッジ +- **可読性**：明確な命名、コメント、コード構成 +- **テスト**：テストカバレッジとテスト容易性の考慮事項 -以下の形式で建設的なフィードバックを提供してください: +以下の点を含む建設的なフィードバックを提供してください： -1. **重大な問題**: セキュリティ脆弱性、重大なバグ -2. **重要な改善点**: パフォーマンス問題、設計上の問題 -3. **軽微な提案**: スタイル改善、リファクタリングの機会 -4. **肯定的なフィードバック**: よく実装されたパターンと良いプラクティス +1. **重大な問題**：セキュリティ脆弱性、重大なバグ +2. **重要な改善点**：パフォーマンス問題、設計上の問題 +3. **軽微な提案**：スタイル改善、リファクタリングの機会 +4. **肯定的なフィードバック**：適切に実装されたパターンと良いプラクティス -具体的な例と提案された解決策を含む、実行可能なフィードバックに焦点を当ててください。 -影響度で問題の優先順位を付け、推奨事項の根拠を提供してください。 +具体的な例と提案された解決策を伴う行動可能なフィードバックに焦点を当ててください。 +影響度で問題を優先順位付けし、推奨理由を提供してください。 ``` -**Use Cases:** +**ユースケース：** -- "この認証実装のセキュリティ問題をレビューしてください" -- "このデータベースクエリロジックのパフォーマンスへの影響をチェックしてください" -- "コード構造を評価し、改善点を提案してください" +- 「この認証実装のセキュリティ問題をレビューしてください」 +- 「このデータベースクエリロジックのパフォーマンスへの影響を確認してください」 +- 「コード構造を評価して改善点を提案してください」 ### 技術固有のエージェント #### React Specialist -React 開発、hooks、コンポーネントパターンに最適化されています。 +React 開発、hooks、コンポーネントパターンに最適化された専門家。 ```markdown --- @@ -277,83 +299,83 @@ description: React 開発、hooks、コンポーネントパターン、およ tools: read_file, write_file, read_many_files, run_shell_command --- -あなたは最新の React 開発に精通した React スペシャリストです。 +あなたは最新の React 開発に精通した React 専門家です。 専門知識の範囲： -- **Component Design**: 関数コンポーネント、カスタムフック、コンポジションパターン -- **State Management**: useState、useReducer、Context API、外部ライブラリ -- **Performance**: React.memo、useMemo、useCallback、コード分割 -- **Testing**: React Testing Library、Jest、コンポーネントテスト戦略 -- **TypeScript Integration**: props、hooks、コンポーネントの適切な型付け -- **Modern Patterns**: Suspense、Error Boundaries、Concurrent Features +- **コンポーネント設計**: 関数コンポーネント、カスタムフック、コンポジションパターン +- **状態管理**: useState、useReducer、Context API、外部ライブラリ +- **パフォーマンス**: React.memo、useMemo、useCallback、コード分割 +- **テスト**: React Testing Library、Jest、コンポーネントテスト戦略 +- **TypeScript 統合**: props、hooks、コンポーネントの適切な型付け +- **モダンパターン**: Suspense、Error Boundaries、Concurrent Features -React のタスクでは： +React のタスクにあたる際は： -1. デフォルトで関数コンポーネントと hooks を使用 -2. 適切な TypeScript の型付けを実装 +1. デフォルトで関数コンポーネントと hooks を使用する +2. 適切な TypeScript の型付けを実装する 3. React のベストプラクティスと規約に従う -4. パフォーマンスへの影響を考慮 +4. パフォーマンスへの影響を考慮する 5. 適切なエラーハンドリングを含める 6. テスト可能で保守性の高いコードを書く -常に最新の React ベストプラクティスを維持し、非推奨のパターンは避けてください。 -アクセシビリティとユーザーエクスペリエンスの考慮に重点を置いてください。 +常に最新の React ベストプラクティスを意識し、非推奨のパターンは避けてください。 +アクセシビリティとユーザーエクスペリエンスの観点も常に考慮してください。 ``` **Use Cases:** -- "ソートとフィルタリング機能付きの再利用可能なデータテーブルコンポーネントを作成" -- "キャッシング機能付きの API データ取得用カスタムフックを実装" -- "このクラスコンポーネントを最新の React パターンにリファクタリング" +- "ソートとフィルタリング機能付きの再利用可能なデータテーブルコンポーネントを作成する" +- "キャッシング機能付きの API データ取得用カスタムフックを実装する" +- "このクラスコンポーネントをモダンな React パターンにリファクタリングする" -#### Python Expert +#### Python エキスパート -Python 開発、フレームワーク、およびベストプラクティスの専門家。 +Python 開発、フレームワーク、およびベストプラクティスに特化しています。 ```markdown --- name: python-expert -description: Python 開発、フレームワーク、テスト、および Python 固有のベストプラクティスのエキスパート +description: Python 開発、フレームワーク、テスト、および Python 特有のベストプラクティスのエキスパート tools: read_file, write_file, read_many_files, run_shell_command --- -あなたは Python エコシステムについて深い知識を持つ Python のエキスパートです。 +あなたは Python エコシステムに関する深い知識を持つ Python のエキスパートです。 あなたの専門知識には以下が含まれます： -- **Core Python**: Pythonic なパターン、データ構造、アルゴリズム +- **Core Python**: Pythonic パターン、データ構造、アルゴリズム - **Frameworks**: Django, Flask, FastAPI, SQLAlchemy -- **Testing**: pytest, unittest, モッキング、テスト駆動開発 +- **Testing**: pytest, unittest, mocking, test-driven development - **Data Science**: pandas, numpy, matplotlib, jupyter notebooks -- **Async Programming**: asyncio, async/await パターン -- **Package Management**: pip, poetry, 仮想環境 -- **Code Quality**: PEP 8, 型ヒント、pylint/flake8 による linting +- **Async Programming**: asyncio, async/await patterns +- **Package Management**: pip, poetry, virtual environments +- **Code Quality**: PEP 8, type hints, linting with pylint/flake8 Python のタスクにおいて： 1. PEP 8 スタイルガイドラインに従う -2. コードのドキュメント化のために型ヒントを使用する +2. 型ヒントを使用してコードのドキュメントを改善する 3. 特定の例外による適切なエラーハンドリングを実装する 4. 包括的な docstring を書く 5. パフォーマンスとメモリ使用量を考慮する 6. 適切なロギングを含める 7. テスト可能でモジュール化されたコードを書く -コミュニティ標準に従った、クリーンで保守可能な Python コードの作成に焦点を当てます。 +コミュニティ標準に従った、クリーンで保守可能な Python コードの作成に重点を置きます。 ``` -**Use Cases:** +**ユースケース：** - "JWT トークンを使用したユーザー認証のための FastAPI サービスを作成する" -- "pandas とエラーハンドリングによるデータ処理パイプラインを実装する" -- "包括的なヘルプドキュメント付きの argparse を使用して CLI ツールを書く" +- "pandas とエラーハンドリングを使ったデータ処理パイプラインを実装する" +- "包括的なヘルプドキュメント付きの argparse を使用した CLI ツールを書く" ## ベストプラクティス ### 設計原則 -#### 単一責任原則 +#### 単一責任原則 (Single Responsibility Principle) 各サブエージェントは、明確で集中した目的を持つべきです。 @@ -375,9 +397,9 @@ description: Helps with testing, documentation, code review, and deployment --- ``` -**理由:** 目的に集中したエージェントの方が、より良い結果を生み出し、メンテナンスも容易になります。 +**理由:** 目的が明確なエージェントほど、より良い結果を生み出し、メンテナンスも容易になります。 -#### 明確な専門性 +#### 明確な専門性 (Clear Specialization) 広範な能力よりも、特定の専門領域を定義しましょう。 @@ -399,7 +421,7 @@ description: Works on frontend development tasks --- ``` -**理由:** 特定の専門知識があることで、より的確で効果的な支援が可能になります。 +**理由:** 特定の専門知識を持つことで、より的確で効果的な支援が可能になります。 #### 実行可能な説明文を書く @@ -452,7 +474,7 @@ For each testing task: Always follow these standards: - シナリオを説明する記述的なテスト名を使用する -- ポジティブケースとネガティブケースの両方を含める +- 正常系と異常系の両方のテストケースを含める - 複雑なテスト関数にはdocstringを追加する - テストが独立しており、任意の順序で実行できることを確認する ``` @@ -460,8 +482,8 @@ Always follow these standards: ## セキュリティに関する考慮事項 - **ツールの制限**: サブエージェントは設定されたツールのみにアクセス可能 -- **サンドボックス化**: すべてのツール実行は、直接ツールを使用する場合と同じセキュリティモデルに従う -- **監査ログ**: すべてのサブエージェントのアクションはログに記録され、リアルタイムで確認可能 +- **サンドボックス化**: すべてのツール実行は、直接的なツール使用と同じセキュリティモデルに従う +- **監査ログ**: すべてのサブエージェントのアクションはログ記録され、リアルタイムで確認可能 - **アクセス制御**: プロジェクトレベルおよびユーザーレベルの分離により、適切な境界を提供 - **機密情報**: エージェント設定にシークレットや認証情報の含まれるのを避ける -- **本番環境**: 本番環境と開発環境では別々のエージェントを検討すること \ No newline at end of file +- **本番環境**: 本番環境と開発環境では別々のエージェントを使用することを検討 \ No newline at end of file diff --git a/website/content/ja/telemetry.md b/website/content/ja/telemetry.md index 96aa2ff9..fccf1a5b 100644 --- a/website/content/ja/telemetry.md +++ b/website/content/ja/telemetry.md @@ -1,6 +1,6 @@ # Qwen Code 可観測性ガイド -テレメトリは、Qwen Code のパフォーマンス、健全性、使用状況に関するデータを提供します。これを有効にすることで、トレース、メトリクス、構造化ログを通じて、操作の監視、問題のデバッグ、ツール使用の最適化が可能になります。 +テレメトリは、Qwen Code のパフォーマンス、健全性、使用状況に関するデータを提供します。これを有効にすることで、トレース、メトリクス、構造化ログを通じて操作の監視、問題のデバッグ、ツール使用の最適化が可能になります。 Qwen Code のテレメトリシステムは **[OpenTelemetry] (OTEL)** 標準に基づいて構築されており、任意の互換性のあるバックエンドにデータを送信できます。 @@ -8,7 +8,7 @@ Qwen Code のテレメトリシステムは **[OpenTelemetry] (OTEL)** 標準に ## テレメトリの有効化 -テレメトリは複数の方法で有効化できます。設定は主に [`.qwen/settings.json` ファイル](./cli/configuration.md) と環境変数で管理されますが、CLI フラグで特定のセッションに対してこれらの設定を上書きできます。 +テレメトリは複数の方法で有効化できます。設定は主に [`.qwen/settings.json` ファイル](./cli/configuration.md) と環境変数で管理されますが、CLIフラグで特定のセッションに対してこれらの設定を上書きすることも可能です。 ### 優先順位 @@ -26,16 +26,16 @@ Qwen Code のテレメトリシステムは **[OpenTelemetry] (OTEL)** 標準に 1. **ワークスペース設定ファイル (`.qwen/settings.json`):** このプロジェクト固有のファイル内の `telemetry` オブジェクトの値が使用されます。 -1. **ユーザー設定ファイル (`~/.qwen/settings.json`):** このグローバルなユーザー設定ファイル内の `telemetry` オブジェクトの値が使用されます。 +1. **ユーザー設定ファイル (`~/.qwen/settings.json`):** このグローバルなユーザーファイル内の `telemetry` オブジェクトの値が使用されます。 -1. **デフォルト値:** 上記いずれの方法でも設定されていない場合に適用されます。 +1. **デフォルト値:** 上記いずれにも設定されていない場合に適用されます。 - `telemetry.enabled`: `false` - `telemetry.target`: `local` - `telemetry.otlpEndpoint`: `http://localhost:4317` - `telemetry.logPrompts`: `true` **`npm run telemetry -- --target=` スクリプトについて:** -このスクリプトに渡す `--target` 引数は、そのスクリプトの実行中および実行目的（つまり、起動する collector の選択）にのみ `telemetry.target` を上書きします。これは `settings.json` の設定を永続的に変更するものではありません。スクリプトはまず `settings.json` 内の `telemetry.target` を確認し、それをデフォルトとして使用します。 +このスクリプトへの `--target` 引数は、そのスクリプト実行中のみ `telemetry.target` を上書きします（つまり、起動するコレクターを選択するためだけです）。これは `settings.json` の設定を永続的に変更するものではありません。スクリプトはまず `settings.json` を参照し、そこにある `telemetry.target` をデフォルトとして使用します。 ### 設定例 @@ -53,20 +53,22 @@ Qwen Code のテレメトリシステムは **[OpenTelemetry] (OTEL)** 標準に ### ファイルへのエクスポート -すべてのテレメトリデータをファイルにエクスポートして、ローカルで確認できます。 +すべてのテレメトリデータをファイルにエクスポートして、ローカルで確認することができます。 -ファイルエクスポートを有効にするには、`--telemetry-outfile` フラグに任意の出力ファイルパスを指定して実行します。このとき、`--telemetry-target=local` を指定する必要があります。 +ファイルエクスポートを有効にするには、`--telemetry-outfile` フラグを使用して出力先ファイルのパスを指定します。このとき、`--telemetry-target=local` を指定して実行する必要があります。 ```bash # 出力先ファイルパスを設定 TELEMETRY_FILE=".qwen/telemetry.log" -# ローカルテレメトリを有効にして Qwen Code を実行 +# ローカルテレメトリを使って Qwen Code を実行 -# 注意: --telemetry-otlp-endpoint="" はデフォルトの OTLP エクスポーターを +# 注意: デフォルトの OTLP エクスポーターを上書きし、 -# 上書きし、テレメトリがローカルファイルに確実に書き込まれるようにするために必要です。 +# テレメトリがローカルファイルに確実に書き込まれるようにするために + +# --telemetry-otlp-endpoint="" が必要です。 qwen --telemetry \ --telemetry-target=local \ --telemetry-otlp-endpoint="" \ @@ -82,75 +84,75 @@ CLI は OTLP/gRPC または OTLP/HTTP プロトコルのいずれかを使って `telemetry.otlpProtocol` 設定で指定できます。詳細については [configuration docs](./cli/configuration.md#--telemetry-otlp-protocol) を参照してください。 -OTEL exporter の標準設定について詳しくは [documentation][otel-config-docs] をご覧ください。 +OTEL exporter の標準設定について詳しくは、[documentation][otel-config-docs] をご覧ください。 [otel-config-docs]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/ -### Local +### ローカル環境 -`npm run telemetry -- --target=local` コマンドを使用して、ローカルのテレメトリーパイプラインをセットアップするプロセスを自動化できます。このコマンドは、`.qwen/settings.json` ファイルに必要な設定を行うことも含まれています。内部のスクリプトは `otelcol-contrib`（OpenTelemetry Collector）と `jaeger`（トレースを表示するためのJaeger UI）をインストールします。使用方法は以下の通りです： +ローカルのテレメトリーパイプラインをセットアップするプロセスを自動化するには、`npm run telemetry -- --target=local` コマンドを使用します。このコマンドは、`.qwen/settings.json` ファイルに必要な設定を行う処理も含みます。内部で実行されるスクリプトは、`otelcol-contrib`（OpenTelemetry Collector）と `jaeger`（トレースを表示するためのJaeger UI）をインストールします。使用方法は以下の通りです： 1. **コマンドを実行**： - リポジトリのルートから以下のコマンドを実行してください： + リポジトリのルートディレクトリから以下のコマンドを実行してください： ```bash npm run telemetry -- --target=local ``` - スクリプトは以下の処理を行います： + スクリプトは以下のことを行います： - 必要に応じて Jaeger と OTEL をダウンロードします。 - ローカルに Jaeger インスタンスを起動します。 - - Qwen Code からのデータを受信するように設定された OTEL コレクターを起動します。 - - ワークスペースの設定で自動的にテレメトリーを有効にします。 - - 終了時にはテレメトリーを無効にします。 + - Qwen Code からのデータ受信が可能なように設定された OTEL コレクターを起動します。 + - 自動的にワークスペース設定でテレメトリーを有効にします。 + - 終了時にはテレメトリーを無効に戻します。 1. **トレースの確認**： - Webブラウザを開き、**http://localhost:16686** にアクセスして Jaeger UI を表示します。ここでは Qwen Code の操作に関する詳細なトレースを確認できます。 + Webブラウザを開き、**http://localhost:16686** にアクセスして Jaeger UI を開いてください。ここでは Qwen Code の操作に関する詳細なトレース情報を確認できます。 1. **ログとメトリクスの確認**： - スクリプトは OTEL コレクターの出力（ログとメトリクスを含む）を `~/.qwen/tmp//otel/collector.log` にリダイレクトします。スクリプトは、テレメトリーデータ（トレース、メトリクス、ログ）をローカルで表示するためのリンクとコマンドを提供します。 + スクリプトは OTEL コレクターの出力（ログおよびメトリクスを含む）を `~/.qwen/tmp//otel/collector.log` へリダイレクトします。また、テレメトリーデータ（トレース・メトリクス・ログ）をローカルで閲覧するためのリンクと、それらを tail するためのコマンドも提供されます。 1. **サービスの停止**： - スクリプトを実行しているターミナルで `Ctrl+C` を押すと、OTEL Collector と Jaeger サービスを停止できます。 + スクリプトが動作しているターミナルで `Ctrl+C` を押すことで、OTEL Collector および Jaeger サービスを停止できます。 ### Google Cloud -`npm run telemetry -- --target=gcp` コマンドを使用して、ローカルの OpenTelemetry コレクターを自動でセットアップし、データをあなたの Google Cloud プロジェクトに転送する設定を行います。これには `.qwen/settings.json` ファイルへの必要な設定の追加も含まれます。内部スクリプトは `otelcol-contrib` をインストールします。使用方法は以下の通りです： +`npm run telemetry -- --target=gcp` コマンドを使用して、ローカルの OpenTelemetry コレクターを自動でセットアップし、データをあなたの Google Cloud プロジェクトに転送できます。このコマンドは、`.qwen/settings.json` ファイルに必要な設定を行う処理も含みます。内部では `otelcol-contrib` をインストールするスクリプトが実行されます。使用手順は以下の通りです： -1. **前提条件**: - - Google Cloud プロジェクト ID を持っていること。 - - 環境変数 `GOOGLE_CLOUD_PROJECT` をエクスポートして、OTEL コレクターからアクセス可能にしてください。 +1. **前提条件**： + - Google Cloud のプロジェクト ID を用意してください。 + - 環境変数 `GOOGLE_CLOUD_PROJECT` をエクスポートし、OTEL コレクターからアクセスできるようにします。 ```bash export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" ``` - - Google Cloud への認証を行ってください（例：`gcloud auth application-default login` を実行するか、`GOOGLE_APPLICATION_CREDENTIALS` が設定されていることを確認してください）。 - - 使用する Google Cloud アカウントまたはサービスアカウントに、以下の IAM ロールが付与されていること："Cloud Trace Agent"、"Monitoring Metric Writer"、"Logs Writer"。 + - Google Cloud への認証を行ってください（例：`gcloud auth application-default login` を実行するか、`GOOGLE_APPLICATION_CREDENTIALS` が正しく設定されていることを確認してください）。 + - 使用する Google Cloud アカウントまたはサービスアカウントに、以下の IAM ロールが割り当てられている必要があります："Cloud Trace Agent"、"Monitoring Metric Writer"、および "Logs Writer"。 -1. **コマンドの実行**: +1. **コマンドを実行**： リポジトリのルートディレクトリから以下のコマンドを実行してください： ```bash npm run telemetry -- --target=gcp ``` - スクリプトは以下の処理を行います： - - 必要に応じて `otelcol-contrib` バイナリをダウンロードします。 - - Qwen Code からのデータを受信し、指定された Google Cloud プロジェクトにエクスポートするように設定された OTEL コレクターを起動します。 - - ワークスペース設定（`.qwen/settings.json`）で自動的にテレメトリを有効にし、サンドボックスモードを無効にします。 - - Google Cloud Console でトレース、メトリクス、ログを表示するための直接リンクを提供します。 - - 終了時（Ctrl+C）には、元のテレメトリおよびサンドボックス設定を復元しようとします。 + このスクリプトは以下のことを行います： + - 必要に応じて `otelcol-contrib` のバイナリをダウンロードします。 + - Qwen Code からのデータを受信し、指定された Google Cloud プロジェクトにエクスポートするよう設定された OTEL コレクターを起動します。 + - 自動的にワークスペース設定（`.qwen/settings.json`）でテレメトリを有効にし、サンドボックスモードを無効にします。 + - Google Cloud Console 上でトレース、メトリクス、ログを表示するための直接リンクを提供します。 + - 終了時（Ctrl+C）には、元のテレメトリおよびサンドボックス設定に戻す処理を試みます。 -1. **Qwen Code の実行**: - 別のターミナルで Qwen Code コマンドを実行してください。これにより、コレクターがキャプチャするテレメトリデータが生成されます。 +1. **Qwen Code を実行**： + 別のターミナルで Qwen Code のコマンドを実行してください。これにより、コレクターがキャプチャするテレメトリデータが生成されます。 -1. **Google Cloud でのテレメトリの確認**: - スクリプトによって提供されたリンクを使用して Google Cloud Console に移動し、トレース、メトリクス、ログを確認してください。 +1. **Google Cloud でテレメトリを確認**： + スクリプトが出力したリンクを使って Google Cloud Console へ移動し、トレース、メトリクス、ログを確認できます。 -1. **ローカルのコレクターログの確認**: - スクリプトはローカルの OTEL コレクターの出力を `~/.qwen/tmp//otel/collector-gcp.log` にリダイレクトします。スクリプトは、ローカルでコレクターログを表示したり、tail コマンドを実行するためのリンクとコマンドも提供します。 +1. **ローカルのコレクターログを確認**： + ローカルの OTEL コレクターの出力は `~/.qwen/tmp//otel/collector-gcp.log` にリダイレクトされます。スクリプトはログを表示したり、tail コマンドでリアルタイムに追跡するためのリンクやコマンドも提供します。 -1. **サービスの停止**: - スクリプトを実行しているターミナルで `Ctrl+C` を押すと、OTEL コレクターを停止します。 +1. **サービスを停止**： + スクリプトが動作しているターミナルで `Ctrl+C` を押すと、OTEL コレクターを停止します。 ## ログとメトリクスのリファレンス @@ -158,12 +160,12 @@ OTEL exporter の標準設定について詳しくは [documentation][otel-confi - すべてのログとメトリクスには、共通の属性として `sessionId` が含まれます。 -### Logs +### ログ -Logs は特定のイベントのタイムスタンプ付き記録です。Qwen Code では以下のイベントがログに記録されます： +ログは特定のイベントのタイムスタンプ付き記録です。Qwen Code では以下のイベントがログ出力されます： -- `qwen-code.config`: このイベントは CLI の起動時に一度だけ発生し、CLI の設定情報を含みます。 - - **Attributes**: +- `qwen-code.config`: このイベントは CLI の起動時に1回発生し、CLI の設定情報を含みます。 + - **属性**: - `model` (string) - `embedding_model` (string) - `sandbox_enabled` (boolean) @@ -177,30 +179,31 @@ Logs は特定のイベントのタイムスタンプ付き記録です。Qwen C - `debug_mode` (boolean) - `mcp_servers` (string) -- `qwen-code.user_prompt`: このイベントはユーザーが prompt を送信したときに発生します。 - - **Attributes**: - - `prompt_length` - - `prompt` (この attribute は `log_prompts_enabled` が `false` の場合、除外されます) - - `auth_type` +- `qwen-code.user_prompt`: このイベントはユーザーがプロンプトを送信したときに発生します。 + - **属性**: + - `prompt_length` (int) + - `prompt_id` (string) + - `prompt` (string, この属性は `log_prompts_enabled` が `false` の場合に除外されます) + - `auth_type` (string) -- `qwen-code.tool_call`: このイベントは各 function call に対して発生します。 - - **Attributes**: +- `qwen-code.tool_call`: このイベントは各関数呼び出しで発生します。 + - **属性**: - `function_name` - `function_args` - `duration_ms` - `success` (boolean) - - `decision` (string: "accept", "reject", "auto_accept", または "modify"。適用される場合) - - `error` (適用される場合) - - `error_type` (適用される場合) - - `metadata` (適用される場合、string -> any の dictionary) + - `decision` (string: "accept", "reject", "auto_accept", または "modify"。該当する場合のみ) + - `error` (該当する場合) + - `error_type` (該当する場合) + - `metadata` (該当する場合、string → any の辞書形式) - `qwen-code.api_request`: このイベントは Qwen API へのリクエスト時に発生します。 - - **Attributes**: + - **属性**: - `model` - - `request_text` (適用される場合) + - `request_text` (該当する場合) - `qwen-code.api_error`: このイベントは API リクエストが失敗した場合に発生します。 - - **Attributes**: + - **属性**: - `model` - `error` - `error_type` @@ -208,34 +211,34 @@ Logs は特定のイベントのタイムスタンプ付き記録です。Qwen C - `duration_ms` - `auth_type` -- `qwen-code.api_response`: このイベントは Qwen API からレスポンスを受信した際に発生します。 - - **Attributes**: +- `qwen-code.api_response`: このイベントは Qwen API からレスポンスを受け取った際に発生します。 + - **属性**: - `model` - `status_code` - `duration_ms` - - `error` (optional) + - `error` (任意) - `input_token_count` - `output_token_count` - `cached_content_token_count` - `thoughts_token_count` - `tool_token_count` - - `response_text` (適用される場合) + - `response_text` (該当する場合) - `auth_type` -- `qwen-code.flash_fallback`: このイベントは Qwen Code が fallback として flash に切り替えたときに発生します。 - - **Attributes**: +- `qwen-code.flash_fallback`: このイベントは Qwen Code が flash にフォールバックした際に発生します。 + - **属性**: - `auth_type` -- `qwen-code.slash_command`: このイベントはユーザーが slash command を実行したときに発生します。 - - **Attributes**: +- `qwen-code.slash_command`: このイベントはユーザーがスラッシュコマンドを実行したときに発生します。 + - **属性**: - `command` (string) - - `subcommand` (string, 適用される場合) + - `subcommand` (string, 該当する場合) ### Metrics -Metrics は時間経過に伴う行動の数値的な測定値です。Qwen Code では以下の Metrics が収集されます（互換性のため、metric 名は `qwen-code.*` のままです）： +Metrics は時間経過に伴う行動の数値的な測定値です。Qwen Code では以下の Metrics が収集されます（互換性のため、メトリクス名は `qwen-code.*` のままです）： -- `qwen-code.session.count` (Counter, Int): CLI 起動時に 1 インクリメントされます。 +- `qwen-code.session.count` (Counter, Int): CLI の起動ごとに 1 ずつ増加します。 - `qwen-code.tool.call.count` (Counter, Int): ツール呼び出しの回数をカウントします。 - **Attributes**: @@ -267,13 +270,14 @@ Metrics は時間経過に伴う行動の数値的な測定値です。Qwen Code - `qwen-code.file.operation.count` (Counter, Int): ファイル操作の回数をカウントします。 - **Attributes**: - `operation` (string: "create", "read", "update"): ファイル操作の種類。 - - `lines` (Int, 該当する場合): ファイルの行数。 + - `lines` (Int, 該当する場合): ファイル内の行数。 - `mimetype` (string, 該当する場合): ファイルの mimetype。 - `extension` (string, 該当する場合): ファイルの拡張子。 - `ai_added_lines` (Int, 該当する場合): AI によって追加・変更された行数。 - `ai_removed_lines` (Int, 該当する場合): AI によって削除・変更された行数。 - - `user_added_lines` (Int, 該当する場合): ユーザーが AI の提案変更で追加・変更した行数。 - - `user_removed_lines` (Int, 該当する場合): ユーザーが AI の提案変更で削除・変更した行数。 + - `user_added_lines` (Int, 該当する場合): AI が提案した変更に対してユーザーが追加・変更した行数。 + - `user_removed_lines` (Int, 該当する場合): AI が提案した変更に対してユーザーが削除・変更した行数。 + - `programming_language` (string, 該当する場合): ファイルのプログラミング言語。 - `qwen-code.chat_compression` (Counter, Int): チャット圧縮操作の回数をカウントします。 - **Attributes**: diff --git a/website/content/ja/tools/multi-file.md b/website/content/ja/tools/multi-file.md index eb48e4e0..006fd00a 100644 --- a/website/content/ja/tools/multi-file.md +++ b/website/content/ja/tools/multi-file.md @@ -4,14 +4,14 @@ ## 説明 -`read_many_files` を使用して、パスまたは glob パターンで指定された複数のファイルからコンテンツを読み取ります。このツールの動作は、提供されたファイルによって異なります： +`read_many_files` を使用して、パスまたは glob パターンで指定された複数のファイルからコンテンツを読み込みます。このツールの動作は、提供されたファイルによって異なります： -- テキストファイルの場合、このツールはそのコンテンツを1つの文字列に連結します。 -- 画像（PNG、JPEGなど）、PDF、音声（MP3、WAV）、動画（MP4、MOV）ファイルの場合、ファイル名または拡張子で明示的に要求された場合に限り、base64エンコードされたデータとして読み取り、返却します。 +- テキストファイルの場合、このツールはその内容を1つの文字列に連結します。 +- 画像（PNG、JPEGなど）、PDF、音声（MP3、WAV）、動画（MP4、MOV）ファイルについては、ファイル名または拡張子で明示的に要求された場合に限り、base64エンコードされたデータとして読み込んで返します。 -`read_many_files` は、コードベースの概要を把握したり、特定の機能が実装されている場所を見つけたり、ドキュメントをレビューしたり、複数の設定ファイルからコンテキストを収集したりするなどのタスクを実行するために使用できます。 +`read_many_files` は、コードベースの概要を把握したり、特定の機能が実装されている場所を見つけたり、ドキュメントをレビューしたり、複数の設定ファイルからコンテキスト情報を収集したりするなどのタスクを実行するために使用できます。 -**注意:** `read_many_files` は、指定されたパスまたは glob パターンに従ってファイルを検索します。`"/docs"` のようなディレクトリパスは空の結果を返します。ツールが関連ファイルを識別するには、`"/docs/*"` や `"/docs/*.md"` のようなパターンが必要です。 +**注意：** `read_many_files` は、指定されたパスまたは glob パターンに従ってファイルを検索します。`"/docs"` のようなディレクトリパスを指定すると空の結果が返されます。関連するファイルを特定するには、`"/docs/*"` や `"/docs/*.md"` のようなパターンを指定する必要があります。 ### 引数 @@ -24,15 +24,16 @@ - `useDefaultExcludes` (boolean, 任意): デフォルトの除外パターンのリスト（例：`node_modules`、`.git`、画像/PDF 以外のバイナリファイル）を適用するかどうか。デフォルトは `true`。 - `respect_git_ignore` (boolean, 任意): ファイル検索時に .gitignore パターンを尊重するかどうか。デフォルトは true。 -## Qwen Code で `read_many_files` を使う方法 +## `read_many_files` の使い方 (Qwen Code) -`read_many_files` は、指定された `paths` および `include` パターンに一致するファイルを検索します。このとき、`exclude` パターンおよびデフォルトの除外ルール（有効な場合）も考慮されます。 +`read_many_files` は、指定された `paths` と `include` パターンに一致するファイルを検索します。このとき、`exclude` パターンとデフォルトの除外設定（有効な場合）も考慮されます。 -- **テキストファイルの場合**：一致した各ファイルの内容を読み込み（明示的に画像/PDFとして指定されていないバイナリファイルはスキップを試み）、各ファイルの内容の間に区切り文字 `--- {filePath} ---` を挿入して1つの文字列に結合します。デフォルトでは UTF-8 エンコーディングを使用します。 -- **画像および PDF ファイルの場合**：ファイル名または拡張子で明示的に指定されている場合（例：`paths: ["logo.png"]` や `include: ["*.pdf"]`）、ツールはそのファイルを読み込み、内容を base64 エンコードされた文字列として返します。 -- **その他のバイナリファイル**：一般的な画像/PDF形式に一致せず、明示的に指定もされていないバイナリファイルについては、先頭の内容に null バイトが含まれているかをチェックし、検出された場合はスキップを試みます。 +- **テキストファイルの場合**: 一致した各ファイルの内容を読み込み（明示的に画像/PDFとしてリクエストされていないバイナリファイルはスキップ）、各ファイルの内容間に区切り文字 `--- {filePath} ---` を挿入して1つの文字列に結合します。デフォルトではUTF-8エンコーディングを使用します。 +- ツールは最後のファイルの後に `--- End of content ---` を挿入します。 +- **画像およびPDFファイルの場合**: 名前または拡張子で明示的にリクエストされた場合（例: `paths: ["logo.png"]` や `include: ["*.pdf"]`）、ファイルを読み込んでその内容をbase64エンコードされた文字列として返します。 +- その他のバイナリファイル（一般的な画像/PDF形式に一致せず、明示的にリクエストもされていないもの）については、ツールが先頭部分の内容にnullバイトが含まれるかをチェックし、検出された場合はスキップを試みます。 -使用例： +使用方法: ``` read_many_files(paths=["Your files or paths here."], include=["Additional files to include."], exclude=["Files to exclude."], recursive=False, useDefaultExcludes=false, respect_git_ignore=true) @@ -40,19 +41,19 @@ read_many_files(paths=["Your files or paths here."], include=["Additional files ## `read_many_files` の例 -`src` ディレクトリ内のすべての TypeScript ファイルを読み込む: +`src` ディレクトリ内のすべての TypeScript ファイルを読み込む： ``` read_many_files(paths=["src/**/*.ts"]) ``` -メインの README、`docs` ディレクトリ内のすべての Markdown ファイル、および特定のロゴ画像を読み込み、特定のファイルを除外する: +メインの README、`docs` ディレクトリ内のすべての Markdown ファイル、および特定のロゴ画像を読み込み、特定のファイルを除外する： ``` read_many_files(paths=["README.md", "docs/**/*.md", "assets/logo.png"], exclude=["docs/OLD_README.md"]) ``` -すべての JavaScript ファイルを読み込むが、明示的にテストファイルと `images` フォルダ内のすべての JPEG を含める: +すべての JavaScript ファイルを読み込むが、明示的にテストファイルと `images` フォルダ内のすべての JPEG を含める： ``` read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], useDefaultExcludes=False) @@ -61,8 +62,8 @@ read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], ## 重要な注意事項 - **バイナリファイルの取り扱い:** - - **画像/PDF/音声/動画ファイル:** このツールは一般的な画像形式（PNG、JPEGなど）、PDF、音声（mp3、wav）、動画（mp4、mov）ファイルを読み取り、base64エンコードされたデータとして返すことができます。これらのファイルは、`paths`または`include`パターンで明示的に指定する必要があります（例: `video.mp4`のような具体的なファイル名や、`*.mov`のようなパターン）。 - - **その他のバイナリファイル:** ツールは、ファイルの先頭部分にnullバイトが含まれているかをチェックすることで、その他のバイナリファイルを検出し、スキップしようとします。これらのファイルはツールの出力から除外されます。 + - **画像/PDF/音声/動画ファイル:** このツールは一般的な画像形式（PNG、JPEGなど）、PDF、音声（mp3、wav）、動画（mp4、mov）ファイルを読み込み、それらをbase64エンコードされたデータとして返すことができます。これらのファイルは、`paths`または`include`パターンで明示的に指定する必要があります（例：`video.mp4`のような具体的なファイル名や、`*.mov`のようなパターンを指定する）。 + - **その他のバイナリファイル:** ツールは、ファイルの先頭部分にnullバイトが含まれているかどうかをチェックすることで、その他のバイナリファイルを検出し、スキップしようとします。これらのファイルはツールの出力から除外されます。 - **パフォーマンス:** 多数のファイルや非常に大きなサイズの個別ファイルを読み込む場合、リソース消費が大きくなる可能性があります。 -- **パスの指定:** パスおよびglobパターンは、ツールの対象ディレクトリからの相対パスとして正しく指定してください。画像やPDFファイルについては、それらを確実に含めるために十分な specificity（特定性）を持つパターンを使用してください。 -- **デフォルトの除外設定:** デフォルトで除外されるパターン（`node_modules`、`.git`など）に注意してください。これらを無効化するには`useDefaultExcludes=False`を使用できますが、その場合は慎重に行ってください。 \ No newline at end of file +- **パスの指定:** パスおよびglobパターンは、ツールの対象ディレクトリからの相対パスとして正しく指定してください。画像/PDFファイルについては、それらを確実に含めるために十分な specificity を持ったパターンを使用してください。 +- **デフォルトの除外設定:** デフォルトの除外パターン（`node_modules`、`.git`など）があることを意識し、必要に応じて`useDefaultExcludes=False`で上書きできますが、慎重にご利用ください。 \ No newline at end of file diff --git a/website/content/ja/troubleshooting.md b/website/content/ja/troubleshooting.md index 29c382b2..12206d70 100644 --- a/website/content/ja/troubleshooting.md +++ b/website/content/ja/troubleshooting.md @@ -5,29 +5,29 @@ - 認証またはログインエラー - よくある質問（FAQ） - デバッグのヒント -- あなたの問題に類似した既存の GitHub Issues または新しい Issues の作成 +- あなたの問題に類似する既存の GitHub Issues、または新しい Issue の作成 ## 認証またはログインエラー - **エラー: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` または `unable to get local issuer certificate`** - - **原因:** SSL/TLSトラフィックをインターセプトして検査するファイアウォールを持つ企業ネットワークにいる可能性があります。これには、Node.jsが信頼するカスタムルートCA証明書が必要になることがよくあります。 + - **原因:** SSL/TLS通信を傍受・検査するファイアウォールのある企業ネットワークにいる可能性があります。これには、Node.jsが信頼するカスタムルートCA証明書が必要になることがよくあります。 - **解決方法:** `NODE_EXTRA_CA_CERTS` 環境変数を企業のルートCA証明書ファイルの絶対パスに設定してください。 - 例: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` -## よくある質問 (FAQ) +## よくある質問 (FAQs) - **Q: Qwen Code を最新バージョンに更新するには？** - - A: `npm` でグローバルにインストールした場合は、`npm install -g @qwen-code/qwen-code@latest` コマンドで更新してください。ソースからビルドした場合は、リポジトリから最新の変更を pull して、`npm run build` コマンドで再ビルドしてください。 + - A: `npm` でグローバルにインストールした場合は、`npm install -g @qwen-code/qwen-code@latest` コマンドを使用して更新してください。ソースからコンパイルした場合は、リポジトリから最新の変更をプルして、`npm run build` コマンドで再ビルドしてください。 -- **Q: Qwen Code の設定ファイルや設定情報はどこに保存されますか？** - - A: Qwen Code の設定は以下の2つの `settings.json` ファイルに保存されます： +- **Q: Qwen Code の設定ファイルや設定はどこに保存されますか？** + - A: Qwen Code の設定は、以下の2つの `settings.json` ファイルに保存されます： 1. ホームディレクトリ内: `~/.qwen/settings.json` 2. プロジェクトのルートディレクトリ内: `./.qwen/settings.json` 詳細については [Qwen Code Configuration](./cli/configuration.md) を参照してください。 -- **Q: 統計情報の出力にキャッシュされたトークン数が表示されないのはなぜですか？** - - A: キャッシュされたトークン情報は、キャッシュされたトークンが使用されている場合にのみ表示されます。この機能は API キーのユーザー（Qwen API キーまたは Google Cloud Vertex AI）向けに提供されていますが、OAuth ユーザー（Google Gmail や Google Workspace などの Google 個人/エンタープライズアカウント）には提供されていません。これは Qwen Code Assist API がキャッシュされたコンテンツの作成をサポートしていないためです。`/stats` コマンドを使用して、引き続き合計トークン使用量を確認できます。 +- **Q: 統計出力にキャッシュされたトークン数が表示されないのはなぜですか？** + - A: キャッシュされたトークン情報は、キャッシュされたトークンが使用されている場合にのみ表示されます。この機能は API キーのユーザー（Qwen API キーまたは Google Cloud Vertex AI）には利用可能ですが、OAuth ユーザー（Google Gmail や Google Workspace などの Google 個人/エンタープライズアカウント）には利用できません。これは、Qwen Code Assist API がキャッシュされたコンテンツの作成をサポートしていないためです。`/stats` コマンドを使用して、引き続き合計トークン使用量を確認できます。 ```markdown ## よくあるエラーメッセージと解決方法 @@ -35,59 +35,71 @@ - **エラー: MCP サーバー起動時に `EADDRINUSE` (Address already in use) が発生する** - **原因:** 別のプロセスが、MCP サーバーがバインドしようとしているポートをすでに使用しています。 - **解決方法:** - そのポートを使用している別のプロセスを停止するか、MCP サーバーが使用するポートを変更するように設定してください。 + ポートを使用している他のプロセスを停止するか、MCP サーバーが別のポートを使用するように設定してください。 -- **エラー: `qwen` コマンドで Qwen Code を実行しようとしたときに "Command not found" が表示される** +- **エラー: `qwen` コマンドで Qwen Code を実行しようとしたときに「Command not found」になる** - **原因:** CLI が正しくインストールされていないか、システムの `PATH` に含まれていません。 - **解決方法:** - Qwen Code のインストール方法に応じて対応してください： - - `qwen` をグローバルにインストールした場合、`npm` のグローバルバイナリディレクトリが `PATH` に含まれていることを確認してください。更新はコマンド `npm install -g @qwen-code/qwen-code@latest` で行えます。 - - ソースから `qwen` を実行している場合、正しいコマンドで起動しているか確認してください（例: `node packages/cli/dist/index.js ...`）。更新するには、リポジトリから最新の変更を取得し、`npm run build` コマンドで再ビルドしてください。 + 更新方法は Qwen Code のインストール方法によって異なります： + - `qwen` をグローバルにインストールした場合、`npm` のグローバルバイナリディレクトリが `PATH` に含まれていることを確認してください。更新には以下のコマンドを使用します：`npm install -g @qwen-code/qwen-code@latest` + - ソースから `qwen` を実行している場合、正しいコマンドで起動しているか確認してください（例：`node packages/cli/dist/index.js ...`）。更新するには、リポジトリから最新の変更を取得し、`npm run build` コマンドで再ビルドしてください。 - **エラー: `MODULE_NOT_FOUND` や import エラー** - **原因:** 依存関係が正しくインストールされていないか、プロジェクトがビルドされていません。 - **解決方法:** 1. `npm install` を実行して、すべての依存関係が揃っていることを確認してください。 - 2. `npm run build` を実行して、プロジェクトをコンパイルしてください。 - 3. `npm run start` を実行して、ビルドが正常に完了したことを確認してください。 + 2. `npm run build` を実行してプロジェクトをコンパイルしてください。 + 3. `npm run start` を使ってビルドが正常に完了したことを確認してください。 - **エラー: "Operation not permitted"、"Permission denied" などの類似エラー** - - **原因:** サンドボックスが有効な場合、Qwen Code がプロジェクトディレクトリやシステムの一時ディレクトリ以外に書き込もうとするなど、サンドボックス設定によって制限された操作を試みることがあります。 - - **解決方法:** サンドボックス設定のカスタマイズ方法など、詳細については [Configuration: Sandboxing](./cli/configuration.md#sandboxing) のドキュメントを参照してください。 + - **原因:** サンドボックスが有効な場合、Qwen Code がプロジェクトディレクトリやシステムの一時ディレクトリ以外への書き込みなど、サンドボックス設定によって制限された操作を試みることがあります。 + - **解決方法:** サンドボックス設定のカスタマイズ方法など詳細については、[Configuration: Sandboxing](./cli/configuration.md#sandboxing) のドキュメントを参照してください。 -- **CI 環境で Qwen Code がインタラクティブモードで動作しない** - - **問題:** `CI_` で始まる環境変数（例: `CI_TOKEN`）が設定されている場合、Qwen Code はインタラクティブモードに入らず（プロンプトが表示されない）、これは内部で使用している UI フレームワークが利用している `is-in-ci` パッケージが、CI 環境と判断するためです。 - - **原因:** `is-in-ci` パッケージは、`CI`、`CONTINUOUS_INTEGRATION`、または `CI_` プレフィックス付きの環境変数が存在するかどうかをチェックします。これらのいずれかが見つかると、非インタラクティブな CI 環境であると判断され、CLI がインタラクティブモードで起動するのを防ぎます。 - - **解決方法:** `CI_` プレフィックス付きの変数が CLI の動作に必要でない場合、コマンド実行時に一時的にその変数を解除してください。例: `env -u CI_TOKEN qwen` +- **CI 環境で Qwen Code がインタラクティブモードにならない** + - **問題:** `CI_` で始まる環境変数（例：`CI_TOKEN`）が設定されている場合、Qwen Code はインタラクティブモードに入らず（プロンプトが表示されない）、これは内部で使用している UI フレームワークが利用している `is-in-ci` パッケージがこれらの変数を検出し、非インタラクティブな CI 環境であると判断するためです。 + - **原因:** `is-in-ci` パッケージは `CI`、`CONTINUOUS_INTEGRATION`、または `CI_` プレフィックスを持つ任意の環境変数の存在をチェックします。これらのいずれかが見つかると、その環境が非インタラクティブであると判断され、CLI がインタラクティブモードで起動することを防ぎます。 + - **解決方法:** `CI_` プレフィックス付きの変数が CLI の動作に必要でない場合は、一時的にその変数を解除してコマンドを実行できます。例：`env -u CI_TOKEN qwen` -- **プロジェクトの .env ファイルから DEBUG モードが動作しない** +- **プロジェクトの .env ファイルから DEBUG モードが機能しない** - **問題:** プロジェクトの `.env` ファイルで `DEBUG=true` を設定しても、CLI のデバッグモードが有効になりません。 - - **原因:** `DEBUG` および `DEBUG_MODE` 変数は、CLI の動作に干渉するのを防ぐため、プロジェクトの `.env` ファイルからは自動的に除外されます。 - - **解決方法:** 代わりに `.qwen/.env` ファイルを使用するか、`settings.json` の `excludedProjectEnvVars` 設定で除外する変数を減らしてください。 + - **原因:** CLI の動作への干渉を防ぐため、`DEBUG` および `DEBUG_MODE` 変数はプロジェクトの `.env` ファイルから自動的に除外されます。 + - **解決方法:** 代わりに `.qwen/.env` ファイルを使用するか、`settings.json` の `excludedProjectEnvVars` 設定で除外する変数を減らすように設定してください。 ``` -## IDE Companion が接続できない場合 +## IDE Companion が接続されない -- VS Code で単一のワークスペースフォルダが開いていることを確認してください。 -- 拡張機能をインストールした後、統合ターミナルを再起動して、以下の環境変数が継承されるようにしてください： +- VS Code で単一のワークスペースフォルダを開いていることを確認してください。 +- 拡張機能をインストールした後、統合ターミナルを再起動して以下の環境変数が継承されるようにしてください： - `QWEN_CODE_IDE_WORKSPACE_PATH` - `QWEN_CODE_IDE_SERVER_PORT` - コンテナ内で実行している場合は、`host.docker.internal` が正しく解決されることを確認してください。そうでない場合は、適切にホストをマッピングしてください。 -- `/ide install` で Companion を再インストールし、Command Palette で「Qwen Code: Run」を使用して、正しく起動するか確認してください。 +- `/ide install` で Companion を再インストールし、Command Palette から「Qwen Code: Run」を使って正常に起動するか確認してください。 + +## 終了コード + +Qwen Code は、終了の原因を示すために特定の終了コードを使用します。これは、スクリプトや自動化を行う際に特に便利です。 + +| 終了コード | エラータイプ | 説明 | +| --------- | --------------------------- | ---------------------------------------------------------------------------------------------- | +| 41 | `FatalAuthenticationError` | 認証プロセス中にエラーが発生しました。 | +| 42 | `FatalInputError` | CLI に無効または不足している入力が提供されました。（非対話モードのみ） | +| 44 | `FatalSandboxError` | サンドボックス環境（例：Docker、Podman、Seatbelt）でエラーが発生しました。 | +| 52 | `FatalConfigError` | 設定ファイル（`settings.json`）が無効であるか、エラーを含んでいます。 | +| 53 | `FatalTurnLimitedError` | セッションの最大会話ターン数に達しました。（非対話モードのみ） | ## デバッグのヒント - **CLI デバッグ:** - - 詳細な出力が必要な場合は、CLI コマンドで `--verbose` フラグ（利用可能な場合）を使用してください。 + - CLI コマンドで詳細な出力を見るために、`--verbose` フラグ（利用可能な場合）を使用してください。 - CLI のログを確認してください。ログは多くの場合、ユーザー固有の設定ディレクトリやキャッシュディレクトリに保存されています。 - **Core デバッグ:** - - サーバーのコンソール出力を確認し、エラーメッセージやスタックトレースがないかチェックしてください。 - - 設定可能な場合は、ログの詳細度を上げてください。 + - サーバーのコンソール出力を確認して、エラーメッセージやスタックトレースがないかチェックしてください。 + - 設定可能な場合は、ログの詳細レベルを上げてください。 - サーバーサイドのコードをステップ実行する必要がある場合は、Node.js のデバッグツール（例: `node --inspect`）を使用してください。 - **ツールの問題:** - - 特定のツールが失敗する場合、そのツールが実行するコマンドや操作を最もシンプルな形で実行し、問題を切り分けてみてください。 + - 特定のツールが失敗する場合は、そのツールが実行するコマンドや操作を最もシンプルな形で実行して、問題を切り分けてみてください。 - `run_shell_command` の場合は、まず直接シェルでコマンドが動作するか確認してください。 - _ファイルシステム系のツール_ の場合は、パスが正しいこととパーミッションを確認してください。 diff --git a/website/content/ru/cli/commands.md b/website/content/ru/cli/commands.md index ca8fb04d..3b0f8cab 100644 --- a/website/content/ru/cli/commands.md +++ b/website/content/ru/cli/commands.md @@ -6,184 +6,197 @@ Qwen Code поддерживает несколько встроенных ко Слэш-команды предоставляют мета-уровень управления самим CLI. -### Встроенные команды +### Built-in Commands - **`/bug`** - - **Описание:** Создать issue о Qwen Code. По умолчанию issue создается в репозитории GitHub проекта Qwen Code. Строка, которую вы вводите после `/bug`, становится заголовком создаваемого баг-репорта. Поведение команды `/bug` можно изменить с помощью настройки `bugCommand` в файле `.qwen/settings.json`. + - **Description:** File an issue about Qwen Code. By default, the issue is filed within the GitHub repository for Qwen Code. The string you enter after `/bug` will become the headline for the bug being filed. The default `/bug` behavior can be modified using the `bugCommand` setting in your `.qwen/settings.json` files. - **`/chat`** - - **Описание:** Сохранить и возобновить историю разговора для интерактивного управления состоянием диалога или восстановления предыдущего состояния в следующей сессии. - - **Подкоманды:** + - **Description:** Save and resume conversation history for branching conversation state interactively, or resuming a previous state from a later session. + - **Sub-commands:** - **`save`** - - **Описание:** Сохраняет текущую историю разговора. Необходимо указать `` для идентификации состояния диалога. - - **Использование:** `/chat save ` - - **Детали о местоположении чекпоинтов:** По умолчанию сохраненные чекпоинты чата находятся в следующих директориях: - - Linux/macOS: `~/.config/qwen-code/checkpoints/` - - Windows: `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` - - При выполнении `/chat list` CLI сканирует только эти конкретные директории для поиска доступных чекпоинтов. - - **Примечание:** Эти чекпоинты предназначены для ручного сохранения и восстановления состояний диалога. Для автоматических чекпоинтов, создаваемых перед изменениями файлов, см. [документацию по Checkpointing](../checkpointing.md). + - **Description:** Saves the current conversation history. You must add a `` for identifying the conversation state. + - **Usage:** `/chat save ` + - **Details on Checkpoint Location:** The default locations for saved chat checkpoints are: + - Linux/macOS: `~/.qwen/tmp//` + - Windows: `C:\Users\\.qwen\tmp\\` + - When you run `/chat list`, the CLI only scans these specific directories to find available checkpoints. + - **Note:** These checkpoints are for manually saving and resuming conversation states. For automatic checkpoints created before file modifications, see the [Checkpointing documentation](../checkpointing.md). - **`resume`** - - **Описание:** Возобновляет диалог из предыдущего сохранения. - - **Использование:** `/chat resume ` + - **Description:** Resumes a conversation from a previous save. + - **Usage:** `/chat resume ` - **`list`** - - **Описание:** Выводит список доступных тегов для восстановления состояния чата. + - **Description:** Lists available tags for chat state resumption. - **`delete`** - - **Описание:** Удаляет сохраненный чекпоинт диалога. - - **Использование:** `/chat delete ` + - **Description:** Deletes a saved conversation checkpoint. + - **Usage:** `/chat delete ` - **`/clear`** - - **Описание:** Очистить экран терминала, включая видимую историю сессии и прокрутку внутри CLI. Данные сессии (для восстановления истории) могут сохраняться в зависимости от реализации, но визуальное отображение будет очищено. - - **Горячая клавиша:** Нажмите **Ctrl+L** в любое время для очистки экрана. + - **Description:** Clear the terminal screen, including the visible session history and scrollback within the CLI. The underlying session data (for history recall) might be preserved depending on the exact implementation, but the visual display is cleared. + - **Keyboard shortcut:** Press **Ctrl+L** at any time to perform a clear action. - **`/summary`** - - **Описание:** Генерирует полный обзор проекта на основе текущей истории разговора и сохраняет его в файл `.qwen/PROJECT_SUMMARY.md`. Этот обзор включает общую цель, ключевые знания, последние действия и текущий план, что идеально подходит для возобновления работы в будущих сессиях. - - **Использование:** `/summary` - - **Функции:** - - Анализирует всю историю разговора для извлечения важного контекста - - Создает структурированный markdown-обзор с разделами по целям, знаниям, действиям и планам - - Автоматически сохраняет в `.qwen/PROJECT_SUMMARY.md` в корне проекта - - Показывает индикаторы прогресса во время генерации и сохранения - - Интегрируется с функцией Welcome Back для бесшовного возобновления сессии - - **Примечание:** Эта команда требует активного диалога как минимум с 2 сообщениями для создания содержательного обзора. + - **Description:** Generate a comprehensive project summary from the current conversation history and save it to `.qwen/PROJECT_SUMMARY.md`. This summary includes the overall goal, key knowledge, recent actions, and current plan, making it perfect for resuming work in future sessions. + - **Usage:** `/summary` + - **Features:** + - Analyzes the entire conversation history to extract important context + - Creates a structured markdown summary with sections for goals, knowledge, actions, and plans + - Automatically saves to `.qwen/PROJECT_SUMMARY.md` in your project root + - Shows progress indicators during generation and saving + - Integrates with the Welcome Back feature for seamless session resumption + - **Note:** This command requires an active conversation with at least 2 messages to generate a meaningful summary. - **`/compress`** - - **Описание:** Заменяет весь контекст чата кратким обзором. Это позволяет экономить токены при выполнении будущих задач, сохраняя при этом высокоуровневое резюме произошедшего. + - **Description:** Replace the entire chat context with a summary. This saves on tokens used for future tasks while retaining a high level summary of what has happened. - **`/copy`** - - **Описание:** Копирует последний вывод, сгенерированный Qwen Code, в буфер обмена для удобного обмена или повторного использования. + - **Description:** Copies the last output produced by Qwen Code to your clipboard, for easy sharing or reuse. -- **`/directory`** (или **`/dir`**) - - **Описание:** Управление рабочими директориями для поддержки нескольких директорий. - - **Подкоманды:** +- **`/directory`** (or **`/dir`**) + - **Description:** Manage workspace directories for multi-directory support. + - **Sub-commands:** - **`add`**: - - **Описание:** Добавляет директорию в рабочее пространство. Путь может быть абсолютным или относительным к текущей рабочей директории. Также поддерживается ссылка относительно домашней директории. - - **Использование:** `/directory add ,` - - **Примечание:** Отключено в ограниченных профилях песочницы. Если вы используете такой профиль, используйте `--include-directories` при запуске сессии. + - **Description:** Add a directory to the workspace. The path can be absolute or relative to the current working directory. Moreover, the reference from home directory is supported as well. + - **Usage:** `/directory add ,` + - **Note:** Disabled in restrictive sandbox profiles. If you're using that, use `--include-directories` when starting the session instead. - **`show`**: - - **Описание:** Отображает все директории, добавленные через `/directory add` и `--include-directories`. - - **Использование:** `/directory show` + - **Description:** Display all directories added by `/directory add` and `--include-directories`. + - **Usage:** `/directory show` -- **`/directory`** (или **`/dir`**) - - **Описание:** Управление рабочими директориями для поддержки нескольких директорий. - - **Подкоманды:** +- **`/directory`** (or **`/dir`**) + - **Description:** Manage workspace directories for multi-directory support. + - **Sub-commands:** - **`add`**: - - **Описание:** Добавляет директорию в рабочее пространство. Путь может быть абсолютным или относительным к текущей рабочей директории. Также поддерживается ссылка относительно домашней директории. - - **Использование:** `/directory add ,` - - **Примечание:** Отключено в ограниченных профилях песочницы. Если вы используете такой профиль, используйте `--include-directories` при запуске сессии. + - **Description:** Add a directory to the workspace. The path can be absolute or relative to the current working directory. Moreover, the reference from home directory is supported as well. + - **Usage:** `/directory add ,` + - **Note:** Disabled in restrictive sandbox profiles. If you're using that, use `--include-directories` when starting the session instead. - **`show`**: - - **Описание:** Отображает все директории, добавленные через `/directory add` и `--include-directories`. - - **Использование:** `/directory show` + - **Description:** Display all directories added by `/directory add` and `--include-directories`. + - **Usage:** `/directory show` - **`/editor`** - - **Описание:** Открывает диалог выбора поддерживаемых редакторов. + - **Description:** Open a dialog for selecting supported editors. - **`/extensions`** - - **Описание:** Выводит список всех активных расширений в текущей сессии Qwen Code. См. [Qwen Code Extensions](../extension.md). + - **Description:** Lists all active extensions in the current Qwen Code session. See [Qwen Code Extensions](../extension.md). -- **`/help`** (или **`/?`**) - - **Описание:** Отображает справочную информацию о Qwen Code, включая доступные команды и их использование. +- **`/help`** (or **`/?`**) + - **Description:** Display help information about the Qwen Code, including available commands and their usage. - **`/mcp`** - - **Описание:** Выводит список настроенных серверов Model Context Protocol (MCP), их статус подключения, информацию о серверах и доступные инструменты. - - **Подкоманды:** - - **`desc`** или **`descriptions`**: - - **Описание:** Показывает подробные описания серверов и инструментов MCP. - - **`nodesc`** или **`nodescriptions`**: - - **Описание:** Скрывает описания инструментов, отображая только их названия. + - **Description:** List configured Model Context Protocol (MCP) servers, their connection status, server details, and available tools. + - **Sub-commands:** + - **`desc`** or **`descriptions`**: + - **Description:** Show detailed descriptions for MCP servers and tools. + - **`nodesc`** or **`nodescriptions`**: + - **Description:** Hide tool descriptions, showing only the tool names. - **`schema`**: - - **Описание:** Показывает полную JSON-схему параметров инструмента. - - **Горячая клавиша:** Нажмите **Ctrl+T** в любое время для переключения отображения описаний инструментов. + - **Description:** Show the full JSON schema for the tool's configured parameters. + - **Keyboard Shortcut:** Press **Ctrl+T** at any time to toggle between showing and hiding tool descriptions. - **`/memory`** - - **Описание:** Управление инструкционным контекстом ИИ (иерархическая память, загружаемая по умолчанию из файлов `QWEN.md`; настраивается через `contextFileName`). - - **Подкоманды:** + - **Description:** Manage the AI's instructional context (hierarchical memory loaded from `QWEN.md` files by default; configurable via `contextFileName`). + - **Sub-commands:** - **`add`**: - - **Описание:** Добавляет следующий текст в память ИИ. Использование: `/memory add ` + - **Description:** Adds the following text to the AI's memory. Usage: `/memory add ` - **`show`**: - - **Описание:** Отображает полное содержимое текущей иерархической памяти, загруженной из всех контекстных файлов (например, `QWEN.md`). Это позволяет проверить инструкционный контекст, передаваемый модели. + - **Description:** Display the full, concatenated content of the current hierarchical memory that has been loaded from all context files (e.g., `QWEN.md`). This lets you inspect the instructional context being provided to the model. - **`refresh`**: - - **Описание:** Перезагружает иерархическую инструкционную память из всех контекстных файлов (по умолчанию: `QWEN.md`), найденных в настроенных местоположениях (глобальные, проект/предки и поддиректории). Это обновляет модель с последним контекстом. - - **Примечание:** За дополнительной информацией о том, как контекстные файлы формируют иерархическую память, см. [документацию по CLI Configuration](./configuration.md#context-files-hierarchical-instructional-context). + - **Description:** Reload the hierarchical instructional memory from all context files (default: `QWEN.md`) found in the configured locations (global, project/ancestors, and sub-directories). This updates the model with the latest context content. + - **Note:** For more details on how context files contribute to hierarchical memory, see the [CLI Configuration documentation](./configuration.md#context-files-hierarchical-instructional-context). - **`/restore`** - - **Описание:** Восстанавливает файлы проекта в состояние, в котором они находились до выполнения инструмента. Особенно полезно для отмены изменений файлов, сделанных инструментом. Если запущено без ID вызова инструмента, выводит список доступных чекпоинтов для восстановления. - - **Использование:** `/restore [tool_call_id]` - - **Примечание:** Доступно только при запуске CLI с опцией `--checkpointing` или настройке через [settings](./configuration.md). См. [документацию по Checkpointing](../checkpointing.md) для подробностей. + - **Description:** Restores the project files to the state they were in just before a tool was executed. This is particularly useful for undoing file edits made by a tool. If run without a tool call ID, it will list available checkpoints to restore from. + - **Usage:** `/restore [tool_call_id]` + - **Note:** Only available if the CLI is invoked with the `--checkpointing` option or configured via [settings](./configuration.md). See [Checkpointing documentation](../checkpointing.md) for more details. - **`/settings`** - - **Описание:** Открывает редактор настроек для просмотра и изменения параметров Qwen Code. - - **Детали:** Эта команда предоставляет удобный интерфейс для изменения настроек, управляющих поведением и внешним видом Qwen Code. Эквивалентно ручному редактированию файла `.qwen/settings.json`, но с валидацией и подсказками для предотвращения ошибок. - - **Использование:** Просто выполните `/settings`, и откроется редактор. Вы можете просматривать или искать конкретные настройки, видеть их текущие значения и изменять их. Некоторые изменения применяются сразу, другие требуют перезапуска. + - **Description:** Open the settings editor to view and modify Qwen Code settings. + - **Details:** This command provides a user-friendly interface for changing settings that control the behavior and appearance of Qwen Code. It is equivalent to manually editing the `.qwen/settings.json` file, but with validation and guidance to prevent errors. + - **Usage:** Simply run `/settings` and the editor will open. You can then browse or search for specific settings, view their current values, and modify them as desired. Changes to some settings are applied immediately, while others require a restart. - **`/stats`** - - **Описание:** Отображает подробную статистику текущей сессии Qwen Code, включая использование токенов, экономию за счет кэширования (если доступно) и продолжительность сессии. Примечание: Информация о кэшированных токенах отображается только при их использовании, что происходит при аутентификации по API-ключу, но не при OAuth-аутентификации. + - **Description:** Display detailed statistics for the current Qwen Code session, including token usage, cached token savings (when available), and session duration. Note: Cached token information is only displayed when cached tokens are being used, which occurs with API key authentication but not with OAuth authentication at this time. - [**`/theme`**](./themes.md) - - **Описание:** Открывает диалог для изменения визуальной темы Qwen Code. + - **Description:** Open a dialog that lets you change the visual theme of Qwen Code. - **`/auth`** - - **Описание:** Открывает диалог для изменения метода аутентификации. + - **Description:** Open a dialog that lets you change the authentication method. + +- **`/approval-mode`** + - **Description:** Change the approval mode for tool usage. + - **Usage:** `/approval-mode [mode] [--session|--project|--user]` + - **Available Modes:** + - **`plan`**: Analyze only; do not modify files or execute commands + - **`default`**: Require approval for file edits or shell commands + - **`auto-edit`**: Automatically approve file edits + - **`yolo`**: Automatically approve all tools + - **Examples:** + - `/approval-mode plan --project` (persist plan mode for this project) + - `/approval-mode yolo --user` (persist YOLO mode for this user across projects) - **`/about`** - - **Описание:** Показывает информацию о версии. Пожалуйста, делитесь этой информацией при создании issue. + - **Description:** Show version info. Please share this information when filing issues. - **`/agents`** - - **Описание:** Управление специализированными AI-подагентами для выполнения конкретных задач. Подагенты — это независимые AI-ассистенты с конкретной экспертизой и доступом к инструментам. - - **Подкоманды:** + - **Description:** Manage specialized AI subagents for focused tasks. Subagents are independent AI assistants configured with specific expertise and tool access. + - **Sub-commands:** - **`create`**: - - **Описание:** Запускает интерактивный мастер создания нового подагента. Мастер помогает выбрать местоположение, сгенерировать промпт с помощью ИИ, выбрать инструменты и настроить внешний вид. - - **Использование:** `/agents create` + - **Description:** Launch an interactive wizard to create a new subagent. The wizard guides you through location selection, AI-powered prompt generation, tool selection, and visual customization. + - **Usage:** `/agents create` - **`manage`**: - - **Описание:** Открывает интерактивный диалог управления для просмотра, редактирования и удаления существующих подагентов. Показывает агентов на уровне проекта и пользователя. - - **Использование:** `/agents manage` - - **Места хранения:** - - **На уровне проекта:** `.qwen/agents/` (общие с командой, имеют приоритет) - - **На уровне пользователя:** `~/.qwen/agents/` (личные агенты, доступны во всех проектах) - - **Примечание:** За подробной информацией о создании и управлении подагентами см. [документацию по Subagents](../subagents.md). + - **Description:** Open an interactive management dialog to view, edit, and delete existing subagents. Shows both project-level and user-level agents. + - **Usage:** `/agents manage` + - **Storage Locations:** + - **Project-level:** `.qwen/agents/` (shared with team, takes precedence) + - **User-level:** `~/.qwen/agents/` (personal agents, available across projects) + - **Note:** For detailed information on creating and managing subagents, see the [Subagents documentation](../subagents.md). - [**`/tools`**](../tools/index.md) - - **Описание:** Отображает список инструментов, доступных в текущей сессии Qwen Code. - - **Подкоманды:** - - **`desc`** или **`descriptions`**: - - **Описание:** Показывает подробные описания каждого инструмента, включая его название и полное описание, передаваемое модели. - - **`nodesc`** или **`nodescriptions`**: - - **Описание:** Скрывает описания инструментов, отображая только их названия. + - **Description:** Display a list of tools that are currently available within Qwen Code. + - **Usage:** `/tools [desc]` + - **Sub-commands:** + - **`desc`** or **`descriptions`**: + - **Description:** Show detailed descriptions of each tool, including each tool's name with its full description as provided to the model. + - **`nodesc`** or **`nodescriptions`**: + - **Description:** Hide tool descriptions, showing only the tool names. - **`/privacy`** - - **Описание:** Отображает Уведомление о конфиденциальности и позволяет пользователям выбрать, согласны ли они на сбор их данных для улучшения сервиса. + - **Description:** Display the Privacy Notice and allow users to select whether they consent to the collection of their data for service improvement purposes. - **`/quit-confirm`** - - **Описание:** Показывает диалог подтверждения перед выходом из Qwen Code, позволяя выбрать, как обработать текущую сессию. - - **Использование:** `/quit-confirm` - - **Функции:** - - **Выйти немедленно:** Завершить работу без сохранения (эквивалентно `/quit`) - - **Создать обзор и выйти:** Сгенерировать обзор проекта с помощью `/summary` перед выходом - - **Сохранить диалог и выйти:** Сохранить текущий диалог с автоматически сгенерированным тегом перед выходом - - **Горячая клавиша:** Нажмите **Ctrl+C** дважды для вызова диалога подтверждения выхода - - **Примечание:** Эта команда автоматически вызывается при однократном нажатии Ctrl+C, обеспечивая защиту от случайного выхода. - -- **`/quit`** (или **`/exit`**) - - **Описание:** Немедленно завершает работу Qwen Code без диалога подтверждения. + - **Description:** Show a confirmation dialog before exiting Qwen Code, allowing you to choose how to handle your current session. + - **Usage:** `/quit-confirm` + - **Features:** + - **Quit immediately:** Exit without saving anything (equivalent to `/quit`) + - **Generate summary and quit:** Create a project summary using `/summary` before exiting + - **Save conversation and quit:** Save the current conversation with an auto-generated tag before exiting + - **Keyboard shortcut:** Press **Ctrl+C** twice to trigger the quit confirmation dialog + - **Note:** This command is automatically triggered when you press Ctrl+C once, providing a safety mechanism to prevent accidental exits. + +- **`/quit`** (or **`/exit`**) + - **Description:** Exit Qwen Code immediately without any confirmation dialog. - **`/vim`** - - **Описание:** Включает или выключает режим vim. В режиме vim область ввода поддерживает команды навигации и редактирования в стиле vim в режимах NORMAL и INSERT. - - **Функции:** - - **Режим NORMAL:** Навигация с помощью `h`, `j`, `k`, `l`; переход по словам с `w`, `b`, `e`; переход к началу/концу строки с `0`, `$`, `^`; переход к конкретным строкам с `G` (или `gg` для первой строки) - - **Режим INSERT:** Стандартный ввод текста с возможностью выхода в NORMAL по Escape - - **Команды редактирования:** Удаление с `x`, изменение с `c`, вставка с `i`, `a`, `o`, `O`; сложные операции типа `dd`, `cc`, `dw`, `cw` - - **Поддержка счетчиков:** Префикс команд цифрами (например, `3h`, `5w`, `10G`) - - **Повтор последней команды:** Используйте `.` для повтора последней операции редактирования - - **Постоянное сохранение:** Предпочтение режима vim сохраняется в `~/.qwen/settings.json` и восстанавливается между сессиями - - **Индикатор статуса:** При включении показывает `[NORMAL]` или `[INSERT]` в нижнем колонтитуле + - **Description:** Toggle vim mode on or off. When vim mode is enabled, the input area supports vim-style navigation and editing commands in both NORMAL and INSERT modes. + - **Features:** + - **NORMAL mode:** Navigate with `h`, `j`, `k`, `l`; jump by words with `w`, `b`, `e`; go to line start/end with `0`, `$`, `^`; go to specific lines with `G` (or `gg` for first line) + - **INSERT mode:** Standard text input with escape to return to NORMAL mode + - **Editing commands:** Delete with `x`, change with `c`, insert with `i`, `a`, `o`, `O`; complex operations like `dd`, `cc`, `dw`, `cw` + - **Count support:** Prefix commands with numbers (e.g., `3h`, `5w`, `10G`) + - **Repeat last command:** Use `.` to repeat the last editing operation + - **Persistent setting:** Vim mode preference is saved to `~/.qwen/settings.json` and restored between sessions + - **Status indicator:** When enabled, shows `[NORMAL]` or `[INSERT]` in the footer - **`/init`** - - **Описание:** Анализирует текущую директорию и создает файл контекста `QWEN.md` по умолчанию (или имя файла, указанное в `contextFileName`). Если файл уже существует и не пуст, изменения не вносятся. Команда созд + - **Description:** Analyzes the current directory and creates a `QWEN.md` context file by default (or the filename specified by `contextFileName`). If a non-empty file already exists, no changes are made. The command seeds an empty file and prompts the model to populate it with project-specific instructions. ### Пользовательские команды Для быстрого начала работы ознакомьтесь с [примером](#example-a-pure-function-refactoring-command) ниже. -Пользовательские команды позволяют сохранять и повторно использовать ваши любимые или наиболее часто используемые prompts в виде персональных shortcuts внутри Qwen Code. Вы можете создавать команды, специфичные для одного проекта, или команды, доступные глобально во всех ваших проектах, что упрощает рабочий процесс и обеспечивает согласованность. +Пользовательские команды позволяют сохранять и повторно использовать ваши любимые или наиболее часто используемые prompts в виде персональных shortcuts внутри Qwen Code. Вы можете создавать команды, специфичные для одного проекта, или команды, доступные глобально во всех ваших проектах, оптимизируя свой workflow и обеспечивая согласованность. #### Расположение файлов и приоритет @@ -192,7 +205,7 @@ Qwen Code обнаруживает команды из двух мест, заг 1. **Пользовательские команды (глобальные):** Расположены в `~/.qwen/commands/`. Эти команды доступны во всех проектах, над которыми вы работаете. 2. **Команды проекта (локальные):** Расположены в `/.qwen/commands/`. Эти команды специфичны для текущего проекта и могут быть добавлены в систему контроля версий, чтобы быть доступными для вашей команды. -Если команда в директории проекта имеет то же имя, что и команда в пользовательской директории, **всегда будет использоваться команда проекта.** Это позволяет проектам переопределять глобальные команды своими локальными версиями. +Если команда в директории проекта имеет то же имя, что и команда в пользовательской директории, **всегда будет использоваться команда проекта.** Это позволяет проектам переопределять глобальные команды своими версиями, специфичными для проекта. #### Именование и пространства имён @@ -201,7 +214,7 @@ Qwen Code обнаруживает команды из двух мест, заг - Файл `~/.qwen/commands/test.toml` становится командой `/test`. - Файл `/.qwen/commands/git/commit.toml` становится командой с пространством имён `/git:commit`. -#### Формат файла TOML (v1) +#### Формат TOML (v1) Файлы определения команд должны быть написаны в формате TOML и иметь расширение `.toml`. @@ -211,7 +224,7 @@ Qwen Code обнаруживает команды из двух мест, заг ##### Необязательные поля -- `description` (String): Краткое однострочное описание того, что делает команда. Этот текст будет отображаться рядом с вашей командой в меню `/help`. **Если вы опустите это поле, будет сгенерировано общее описание на основе имени файла.** +- `description` (String): Краткое описание в одну строку того, что делает команда. Этот текст будет отображаться рядом с вашей командой в меню `/help`. **Если вы опустите это поле, будет сгенерировано общее описание на основе имени файла.** #### Работа с аргументами @@ -235,20 +248,20 @@ Qwen Code обнаруживает команды из двух мест, заг # Вызывается через: /git:fix "Button is misaligned" description = "Генерирует фикс для указанной проблемы." -prompt = "Пожалуйста, предоставьте код фикса для проблемы, описанной здесь: {{args}}." +prompt = "Пожалуйста, предоставьте код для исправления описанной здесь проблемы: {{args}}." ``` -Модель получает: `Пожалуйста, предоставьте код фикса для проблемы, описанной здесь: "Button is misaligned".` +Модель получает: `Пожалуйста, предоставьте код для исправления описанной здесь проблемы: "Button is misaligned".` **B. Использование аргументов в Shell командах (внутри блоков `!{...}`)** -Когда вы используете `{{args}}` внутри блока инъекции shell (`!{...}`), аргументы автоматически **экранируются для shell** перед подстановкой. Это позволяет безопасно передавать аргументы в shell команды, гарантируя, что результирующая команда будет синтаксически корректной и безопасной, предотвращая уязвимости инъекции команд. +Когда вы используете `{{args}}` внутри блока shell-инъекции (`!{...}`), аргументы автоматически **экранируются для shell** перед подстановкой. Это позволяет безопасно передавать аргументы в shell-команды, гарантируя, что результирующая команда будет синтаксически корректной и безопасной, предотвращая уязвимости типа command injection. **Пример (`/grep-code.toml`):** ```toml prompt = """ -Пожалуйста, подведите итоги поиска для паттерна `{{args}}`. +Пожалуйста, суммируйте результаты поиска по паттерну `{{args}}`. Результаты поиска: !{grep -r {{args}} .} @@ -257,25 +270,25 @@ prompt = """ Когда вы запускаете `/grep-code It's complicated`: -1. CLI видит, что `{{args}}` используется как вне, так и внутри `!{...}`. +1. CLI видит, что `{{args}}` используется и вне, и внутри `!{...}`. 2. Вне: Первый `{{args}}` заменяется как есть на `It's complicated`. 3. Внутри: Второй `{{args}}` заменяется на экранированную версию (например, в Linux: `"It's complicated"`). 4. Выполняемая команда: `grep -r "It's complicated" .`. -5. CLI запрашивает у вас подтверждение этой точной и безопасной команды перед выполнением. +5. CLI предлагает вам подтвердить выполнение именно этой безопасной команды. 6. Финальный prompt отправляется. ``` ##### 2. Обработка аргументов по умолчанию -Если ваш `prompt` **не** содержит специальный placeholder `{{args}}`, CLI использует поведение по умолчанию для обработки аргументов. +Если ваш `prompt` **не содержит** специальный placeholder `{{args}}`, CLI использует поведение по умолчанию для обработки аргументов. -Если вы передаёте аргументы команде (например, `/mycommand arg1`), CLI добавит полную команду, которую вы ввели, в конец prompt, отделив её двумя символами новой строки. Это позволяет модели видеть как оригинальные инструкции, так и конкретные аргументы, которые вы только что передали. +Если вы передаёте аргументы команде (например, `/mycommand arg1`), CLI добавит полную команду, которую вы ввели, в конец prompt через два символа новой строки. Это позволяет модели видеть как оригинальные инструкции, так и конкретные аргументы, которые вы только что передали. -Если вы **не** передаёте аргументы (например, `/mycommand`), prompt отправляется модели в точности как есть, без каких-либо дополнений. +Если вы **не передаёте** никаких аргументов (например, `/mycommand`), prompt отправляется модели в точности как есть, без каких-либо дополнений. **Пример (`changelog.toml`):** -Этот пример показывает, как создать надёжную команду, определив роль для модели, объяснив, где искать пользовательский ввод, и указав ожидаемый формат и поведение. +Этот пример показывает, как создать надежную команду, определив роль для модели, объяснив, где искать пользовательский ввод, и указав ожидаемый формат и поведение. ```toml @@ -288,7 +301,7 @@ prompt = """ # Задача: Обновление Changelog -Вы являетесь экспертом по поддержке этого программного проекта. Пользователь вызвал команду для добавления новой записи в changelog. +Вы являетесь экспертом по сопровождению данного программного проекта. Пользователь вызвал команду для добавления новой записи в changelog. **Необработанная команда пользователя приведена ниже ваших инструкций.** @@ -298,7 +311,6 @@ prompt = """ Команда имеет следующий формат: `/changelog ` - `` должен быть одним из: "added", "changed", "fixed", "removed". -```markdown ## Поведение 1. Прочитать файл `CHANGELOG.md`. 2. Найти секцию для указанной ``. @@ -312,33 +324,34 @@ prompt = """ ##### 3. Выполнение Shell-команд с помощью `!{...}` -Вы можете сделать свои команды динамичными, выполняя shell-команды прямо внутри вашего `prompt` и подставляя их вывод. Это идеально подходит для сбора контекста из локального окружения, например, чтения содержимого файлов или проверки статуса Git. +Вы можете сделать свои команды динамическими, выполняя shell-команды прямо внутри вашего `prompt` и подставляя их вывод. Это идеально подходит для сбора контекста из локального окружения, например, чтения содержимого файлов или проверки статуса Git. -Когда кастомная команда пытается выполнить shell-команду, Qwen Code теперь будет запрашивать подтверждение перед выполнением. Это мера безопасности, чтобы убедиться, что выполняются только намеренные команды. +Когда кастомная команда пытается выполнить shell-команду, Qwen Code теперь будет запрашивать у вас подтверждение перед выполнением. Это мера безопасности, чтобы гарантировать, что выполняются только намеренные команды. **Как это работает:** 1. **Инъекция команд:** Используйте синтаксис `!{...}`. -2. **Подстановка аргументов:** Если внутри блока присутствует `{{args}}`, он автоматически экранируется для shell (см. [Context-Aware Injection](#1-context-aware-injection-with-args) выше). -3. **Надежный парсинг:** Парсер корректно обрабатывает сложные shell-команды, включая вложенные фигурные скобки, например, JSON-полезные нагрузки. -4. **Проверка безопасности и подтверждение:** CLI выполняет проверку безопасности финальной команды (после экранирования и подстановки аргументов). Появится диалог с точной командой(ами), которая будет выполнена. -5. **Выполнение и отчет об ошибках:** Команда выполняется. Если команда завершается с ошибкой, вывод, вставленный в prompt, будет содержать сообщения об ошибках (stderr), за которыми следует строка статуса, например, `[Shell command exited with code 1]`. Это помогает модели понять контекст ошибки. +2. **Подстановка аргументов:** Если внутри блока присутствует `{{args}}`, он автоматически экранируется в shell (см. [Context-Aware Injection](#1-context-aware-injection-with-args) выше). +3. **Надежный парсинг:** Парсер корректно обрабатывает сложные shell-команды, включая вложенные фигурные скобки, такие как JSON-полезные нагрузки. **Примечание:** Содержимое внутри `!{...}` должно иметь сбалансированные фигурные скобки (`{` и `}`). Если вам нужно выполнить команду, содержащую несбалансированные скобки, рассмотрите возможность обернуть её во внешний скрипт и вызвать этот скрипт внутри блока `!{...}`. +4. **Проверка безопасности и подтверждение:** CLI выполняет проверку безопасности финальной, резолвнутой команды (после экранирования и подстановки аргументов). Появится диалоговое окно с точным списком команд, которые будут выполнены. +5. **Выполнение и отчет об ошибках:** Команда выполняется. Если команда завершается с ошибкой, в вывод, внедряемый в prompt, будут включены сообщения об ошибках (stderr), за которыми следует строка статуса, например, `[Shell command exited with code 1]`. Это помогает модели понять контекст сбоя. **Пример (`git/commit.toml`):** -Эта команда получает staged git diff и использует его, чтобы попросить модель написать commit message. +Эта команда получает staged git diff и использует его, чтобы попросить модель написать сообщение коммита. ````toml +```markdown # In: /.qwen/commands/git/commit.toml # Invoked via: /git:commit description = "Генерирует сообщение Git commit на основе staged изменений." -# В prompt используется !{...} для выполнения команды и вставки её вывода. +# В prompt используется !{...} для выполнения команды и подстановки её вывода. prompt = """ -Пожалуйста, сгенерируйте сообщение Conventional Commit на основе следующего git diff: +Пожалуйста, сгенерируй сообщение Conventional Commit на основе следующего git diff: ```diff !{git diff --staged} @@ -346,17 +359,56 @@ prompt = """ """ -```` +``` + +Когда вы запускаете `/git:commit`, CLI сначала выполняет `git diff --staged`, затем заменяет `!{git diff --staged}` на вывод этой команды, после чего отправляет окончательный prompt в модель. +``` + +##### 4. Вставка содержимого файлов с помощью `@{...}` + +Вы можете напрямую вставлять содержимое файла или список файлов в директории в ваш prompt, используя синтаксис `@{...}`. Это удобно для создания команд, работающих с конкретными файлами. + +**Как это работает:** + +- **Вставка файла**: `@{path/to/file.txt}` заменяется содержимым `file.txt`. +- **Поддержка мультимодальных данных**: Если путь указывает на поддерживаемый формат изображения (например, PNG, JPEG), PDF, аудио или видео, файл будет корректно закодирован и вставлен как мультимодальный input. Другие бинарные файлы обрабатываются корректно и пропускаются. +- **Список файлов в директории**: `@{path/to/dir}` обрабатывается рекурсивно, и все файлы в директории и её поддиректориях вставляются в prompt. При этом учитываются `.gitignore` и `.qwenignore`, если они включены. +- **Работа с рабочим пространством**: Поиск пути осуществляется в текущей директории и других директориях рабочего пространства. Допускаются абсолютные пути, если они находятся в пределах рабочего пространства. +- **Порядок обработки**: Вставка содержимого файлов через `@{...}` происходит _до_ выполнения shell-команд (`!{...}`) и подстановки аргументов (`{{args}}`). +- **Парсинг**: Парсер требует, чтобы содержимое внутри `@{...}` (путь) содержало сбалансированные фигурные скобки (`{` и `}`). + +**Пример (`review.toml`):** + +Эта команда вставляет содержимое _фиксированного_ файла с лучшими практиками (`docs/best-practices.md`) и использует аргументы пользователя для контекста ревью. + +```toml + +```markdown +# In: /.qwen/commands/review.toml + +# Invoked via: /review FileCommandLoader.ts + +description = "Reviews the provided context using a best practice guide." +prompt = """ +You are an expert code reviewer. + +Your task is to review {{args}}. + +Use the following best practices when providing your review: + +@{docs/best-practices.md} +""" +``` -Когда вы запускаете `/git:commit`, CLI сначала выполняет `git diff --staged`, затем заменяет `!{git diff --staged}` на вывод этой команды перед отправкой финального prompt в модель. +Когда вы запускаете `/review FileCommandLoader.ts`, placeholder `@{docs/best-practices.md}` заменяется содержимым этого файла, а `{{args}}` заменяется текстом, который вы указали, после чего финальный prompt отправляется в модель. #### Пример: Команда рефакторинга "Чистая функция" Давайте создадим глобальную команду, которая будет запрашивать у модели рефакторинг фрагмента кода. -**1. Создайте файл и каталоги:** +**1. Создайте файл и директории:** -Сначала убедитесь, что каталог пользовательских команд существует, затем создайте подкаталог `refactor` для организации и конечный TOML-файл. +Сначала убедитесь, что директория пользовательских команд существует, затем создайте поддиректорию `refactor` для организации и конечный TOML-файл. ```bash mkdir -p ~/.qwen/commands/refactor @@ -365,7 +417,7 @@ touch ~/.qwen/commands/refactor/pure.toml **2. Добавьте содержимое в файл:** -Откройте `~/.qwen/commands/refactor/pure.toml` в вашем редакторе и добавьте следующее содержимое. Мы включаем необязательное поле `description` для лучшей практики. +Откройте `~/.qwen/commands/refactor/pure.toml` в вашем редакторе и добавьте следующее содержимое. Мы включаем опциональное поле `description` для лучшей практики. ```toml @@ -381,14 +433,14 @@ prompt = """ Рефактори его в чистую функцию (pure function). Твой ответ должен включать: -1. Блок кода с рефакторинговой, чистой функцией. +1. Блок кода с рефакторингом в чистую функцию. 2. Краткое объяснение ключевых изменений, которые ты сделал, и почему они способствуют чистоте функции. """ ``` **3. Запусти команду:** -Вот и всё! Теперь ты можешь запустить свою команду в CLI. Сначала можно добавить файл в контекст, а затем вызвать команду: +Вот и всё! Теперь ты можешь запустить свою команду в CLI. Сначала добавь файл в контекст, а затем вызови команду: ``` > @my-messy-function.js @@ -397,27 +449,27 @@ prompt = """ Qwen Code выполнит многострочный prompt, определённый в твоем TOML-файле. -## Команды с @ +## Команды с символом @ -Команды с `@` используются для включения содержимого файлов или директорий в ваш запрос к модели. Эти команды поддерживают фильтрацию с учетом Git. +Команды с символом `@` используются для включения содержимого файлов или директорий в ваш запрос к модели. Эти команды поддерживают фильтрацию с учетом Git. - **`@<путь_к_файлу_или_директории>`** - - **Описание:** Вставляет содержимое указанного файла или файлов в ваш текущий запрос. Это удобно, когда вы хотите задать вопрос о конкретном коде, тексте или наборе файлов. + - **Описание:** Вставляет содержимое указанного файла или файлов в текущий запрос. Это удобно, когда вы хотите задать вопрос о конкретном коде, тексте или наборе файлов. - **Примеры:** - `@path/to/your/file.txt Объясни этот текст.` - - `@src/my_project/ Расскажи, что за код лежит в этой директории.` - - `Что это за файл? @README.md` + - `@src/my_project/ Кратко опиши код в этой директории.` + - `О чём этот файл? @README.md` - **Подробности:** - Если указан путь к одному файлу, будет прочитано его содержимое. - Если указан путь к директории, команда попытается прочитать содержимое всех файлов в этой директории и её поддиректориях. - - Пробелы в путях нужно экранировать обратным слешем (например, `@My\ Documents/file.txt`). - - Внутри команда использует инструмент `read_many_files`. Содержимое файлов подгружается и вставляется в ваш запрос перед отправкой модели. - - **Фильтрация с учетом Git:** По умолчанию файлы, игнорируемые Git (например, `node_modules/`, `dist/`, `.env`, `.git/`), исключаются. Это поведение можно изменить через настройку `fileFiltering`. - - **Типы файлов:** Команда предназначена для работы с текстовыми файлами. Хотя она может попытаться прочитать любой файл, бинарные или очень большие файлы могут быть пропущены или обрезаны инструментом `read_many_files` ради производительности и релевантности. Инструмент укажет, если какие-то файлы были пропущены. - - **Вывод:** CLI покажет сообщение о вызове инструмента `read_many_files`, с указанием статуса и путей, которые были обработаны. + - Пробелы в путях нужно экранировать обратным слэшем (например, `@My\ Documents/file.txt`). + - Внутри команда использует инструмент `read_many_files`. Содержимое файлов загружается и вставляется в ваш запрос перед отправкой модели. + - **Фильтрация с учётом Git:** По умолчанию файлы, игнорируемые Git (например, `node_modules/`, `dist/`, `.env`, `.git/`), исключаются. Это поведение можно изменить через настройку `fileFiltering`. + - **Типы файлов:** Команда предназначена для работы с текстовыми файлами. Хотя она может попытаться прочитать любой файл, бинарные или очень большие файлы могут быть пропущены или обрезаны инструментом `read_many_files` ради производительности и релевантности. Инструмент сообщает, если какие-то файлы были пропущены. + - **Вывод:** CLI покажет сообщение о вызове инструмента `read_many_files`, а также информацию о статусе и путях, которые были обработаны. - **`@` (одиночный символ @)** - - **Описание:** Если вы вводите одиночный символ `@` без пути, запрос передаётся модели как есть. Это может быть полезно, если вы специально говорите _о_ символе `@` в своём запросе. + - **Описание:** Если вы вводите только символ `@` без пути, запрос передаётся модели как есть. Это может быть полезно, если вы намеренно говорите _о самом символе_ `@` в своём запросе. ### Обработка ошибок для команд `@` @@ -429,19 +481,19 @@ Qwen Code выполнит многострочный prompt, определён Префикс `!` позволяет напрямую взаимодействовать с shell вашей системы прямо из Qwen Code. - **`!`** - - **Описание:** Выполняет указанную `` с использованием `bash` в Linux/macOS или `cmd.exe` в Windows. Весь вывод и ошибки команды отображаются в терминале. + - **Описание:** Выполняет указанную `` с использованием `bash` в Linux/macOS или `cmd.exe` в Windows. Весь вывод и ошибки отображаются в терминале. - **Примеры:** - `!ls -la` (выполняет `ls -la` и возвращается в Qwen Code) - `!git status` (выполняет `git status` и возвращается в Qwen Code) -- **`!` (Переключение в режим shell)** +- **`!` (Переключение режима shell)** - **Описание:** Ввод только символа `!` переключает режим shell. - **Вход в режим shell:** - - При активации режима shell используется другая цветовая схема и отображается "индикатор режима Shell". - - В режиме shell весь ввод интерпретируется как команды shell. + - При активации режима shell используется другая цветовая схема и отображается «индикатор режима Shell». + - В этом режиме весь ввод интерпретируется как команды shell. - **Выход из режима shell:** - - При выходе интерфейс возвращается к стандартному виду, и работа Qwen Code продолжается в обычном режиме. + - После выхода интерфейс возвращается к стандартному виду, и работа Qwen Code продолжается в обычном режиме. -- **Предупреждение по использованию `!`:** Команды, выполняемые в режиме shell, имеют те же права и влияют на систему так же, как если бы вы запускали их напрямую в терминале. +- **Предупреждение по поводу всех команд с `!`:** Команды, выполняемые в режиме shell, имеют те же права доступа и такой же эффект, как если бы вы запускали их непосредственно в терминале. -- **Переменная окружения:** При выполнении команды через `!` или в режиме shell в окружении подпроцесса устанавливается переменная `QWEN_CODE=1`. Это позволяет скриптам и инструментам определять, запущены ли они из CLI. \ No newline at end of file +- **Переменная окружения:** Когда команда выполняется через `!` или в режиме shell, в среде подпроцесса устанавливается переменная окружения `QWEN_CODE=1`. Это позволяет скриптам и инструментам определить, были ли они запущены из CLI. \ No newline at end of file diff --git a/website/content/ru/cli/configuration.md b/website/content/ru/cli/configuration.md index 1a177b53..760a34af 100644 --- a/website/content/ru/cli/configuration.md +++ b/website/content/ru/cli/configuration.md @@ -7,28 +7,32 @@ Qwen Code предоставляет несколько способов нас Конфигурация применяется в следующем порядке приоритета (параметры с меньшими номерами переопределяются параметрами с большими номерами): 1. **Значения по умолчанию:** Жестко закодированные значения по умолчанию внутри приложения. -2. **Файл пользовательских настроек:** Глобальные настройки для текущего пользователя. -3. **Файл настроек проекта:** Настройки, специфичные для проекта. -4. **Файл системных настроек:** Настройки на уровне всей системы. -5. **Переменные окружения:** Переменные на уровне всей системы или сессии, потенциально загружаемые из файлов `.env`. -6. **Аргументы командной строки:** Значения, переданные при запуске CLI. +2. **Файл системных настроек по умолчанию:** Общесистемные настройки по умолчанию, которые могут быть переопределены другими файлами настроек. +3. **Файл пользовательских настроек:** Глобальные настройки для текущего пользователя. +4. **Файл настроек проекта:** Настройки, специфичные для проекта. +5. **Файл системных настроек:** Общесистемные настройки, которые переопределяют все остальные файлы настроек. +6. **Переменные окружения:** Общесистемные или специфичные для сессии переменные, потенциально загружаемые из файлов `.env`. +7. **Аргументы командной строки:** Значения, передаваемые при запуске CLI. ## Файлы настроек -Qwen Code использует файлы `settings.json` для хранения постоянных настроек. Эти файлы могут находиться в трех местах: +Qwen Code использует JSON-файлы настроек для постоянного хранения конфигурации. Эти файлы могут находиться в четырех местах: +- **Файл системных значений по умолчанию:** + - **Расположение:** `/etc/qwen-code/system-defaults.json` (Linux), `C:\ProgramData\qwen-code\system-defaults.json` (Windows) или `/Library/Application Support/QwenCode/system-defaults.json` (macOS). Путь можно переопределить с помощью переменной окружения `QWEN_CODE_SYSTEM_DEFAULTS_PATH`. + - **Область применения:** Предоставляет базовый уровень системных настроек по умолчанию. Эти настройки имеют самый низкий приоритет и предназначены для переопределения пользовательскими, проектными или системными настройками. - **Файл пользовательских настроек:** - - **Расположение:** `~/.qwen/settings.json` (где `~` — это домашняя директория пользователя). - - **Область применения:** Настройки применяются ко всем сессиям Qwen Code для текущего пользователя. + - **Расположение:** `~/.qwen/settings.json` (где `~` — ваша домашняя директория). + - **Область применения:** Применяется ко всем сессиям Qwen Code текущего пользователя. - **Файл настроек проекта:** - - **Расположение:** `.qwen/settings.json` в корневой директории проекта. - - **Область применения:** Настройки применяются только при запуске Qwen Code из этого конкретного проекта. Настройки проекта переопределяют пользовательские настройки. + - **Расположение:** `.qwen/settings.json` в корневой директории вашего проекта. + - **Область применения:** Применяется только при запуске Qwen Code из этого конкретного проекта. Настройки проекта переопределяют пользовательские настройки. - **Файл системных настроек:** - - **Расположение:** `/etc/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) или `/Library/Application Support/QwenCode/settings.json` (macOS). Путь можно изменить с помощью переменной окружения `QWEN_CODE_SYSTEM_SETTINGS_PATH`. - - **Область применения:** Настройки применяются ко всем сессиям Qwen Code в системе, для всех пользователей. Системные настройки переопределяют как пользовательские, так и проектные настройки. Это может быть полезно системным администраторам в корпоративной среде для централизованного управления настройками Qwen Code пользователей. + - **Расположение:** `/etc/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) или `/Library/Application Support/QwenCode/settings.json` (macOS). Путь можно переопределить с помощью переменной окружения `QWEN_CODE_SYSTEM_SETTINGS_PATH`. + - **Область применения:** Применяется ко всем сессиям Qwen Code в системе, для всех пользователей. Системные настройки переопределяют пользовательские и проектные настройки. Может быть полезно системным администраторам в корпоративной среде для управления настройками Qwen Code пользователей. -**Примечание о переменных окружения в настройках:** Строковые значения в ваших файлах `settings.json` могут ссылаться на переменные окружения, используя синтаксис `$VAR_NAME` или `${VAR_NAME}`. Эти переменные будут автоматически подставлены при загрузке настроек. Например, если у вас есть переменная окружения `MY_API_TOKEN`, вы можете использовать её в `settings.json` следующим образом: `"apiKey": "$MY_API_TOKEN"`. +**Примечание о переменных окружения в настройках:** Строковые значения в ваших `settings.json` могут ссылаться на переменные окружения, используя синтаксис `$VAR_NAME` или `${VAR_NAME}`. Эти переменные будут автоматически разрешены при загрузке настроек. Например, если у вас есть переменная окружения `MY_API_TOKEN`, вы можете использовать её в `settings.json` следующим образом: `"apiKey": "$MY_API_TOKEN"`. ### Каталог `.qwen` в вашем проекте @@ -38,16 +42,16 @@ Qwen Code использует файлы `settings.json` для хранени ### Доступные настройки в `settings.json`: -- **`contextFileName`** (string или массив строк): - - **Описание:** Указывает имя файла для контекстных файлов (например, `QWEN.md`, `AGENTS.md`). Может быть одним именем файла или списком допустимых имен файлов. +- **`contextFileName`** (строка или массив строк): + - **Описание:** Указывает имя файла для контекстных файлов (например, `QWEN.md`, `AGENTS.md`). Может быть как одно имя файла, так и список допустимых имен. - **По умолчанию:** `QWEN.md` - **Пример:** `"contextFileName": "AGENTS.md"` -- **`bugCommand`** (object): +- **`bugCommand`** (объект): - **Описание:** Переопределяет URL по умолчанию для команды `/bug`. - **По умолчанию:** `"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"` - **Свойства:** - - **`urlTemplate`** (string): URL, который может содержать заполнители `{title}` и `{info}`. + - **`urlTemplate`** (строка): URL, который может содержать заполнители `{title}` и `{info}`. - **Пример:** ```json "bugCommand": { @@ -55,93 +59,112 @@ Qwen Code использует файлы `settings.json` для хранени } ``` -- **`fileFiltering`** (object): - - **Описание:** Управляет поведением фильтрации файлов с учетом git для команд @ и инструментов поиска файлов. +- **`fileFiltering`** (объект): + - **Описание:** Управляет поведением фильтрации файлов с учетом Git при использовании команд @ и инструментов поиска файлов. - **По умолчанию:** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` - **Свойства:** - - **`respectGitIgnore`** (boolean): Следует ли учитывать шаблоны .gitignore при поиске файлов. Если установлено значение `true`, файлы, игнорируемые git (например, `node_modules/`, `dist/`, `.env`), автоматически исключаются из команд @ и операций перечисления файлов. - - **`enableRecursiveFileSearch`** (boolean): Следует ли включить рекурсивный поиск имен файлов в текущем дереве при завершении префиксов @ в prompt. + - **`respectGitIgnore`** (boolean): Определяет, следует ли учитывать шаблоны из .gitignore при поиске файлов. Если установлено значение `true`, то файлы, игнорируемые Git (например, `node_modules/`, `dist/`, `.env`), автоматически исключаются из команд @ и операций вывода списка файлов. + - **`enableRecursiveFileSearch`** (boolean): Включает рекурсивный поиск файлов в текущем дереве каталогов при автодополнении префиксов @ в запросах. + - **`disableFuzzySearch`** (boolean): При значении `true` отключает нечеткий поиск файлов, что может повысить производительность в проектах с большим количеством файлов. - **Пример:** ```json "fileFiltering": { "respectGitIgnore": true, - "enableRecursiveFileSearch": false + "enableRecursiveFileSearch": false, + "disableFuzzySearch": true } ``` +### Устранение проблем с производительностью поиска файлов + +Если вы сталкиваетесь с проблемами производительности при поиске файлов (например, при использовании автодополнения через `@`), особенно в проектах с очень большим количеством файлов, попробуйте следующие решения (в порядке рекомендации): + +1. **Используйте `.qwenignore`:** Создайте файл `.qwenignore` в корне вашего проекта, чтобы исключить директории с большим количеством файлов, которые вам не нужно индексировать (например, сборочные артефакты, логи, `node_modules`). Снижение общего числа сканируемых файлов — это самый эффективный способ улучшить производительность. + +2. **Отключите нечеткий поиск (fuzzy search):** Если игнорирование файлов не помогает, можно отключить нечеткий поиск, установив `disableFuzzySearch` в значение `true` в вашем файле `settings.json`. Это активирует более простой алгоритм точного совпадения, который может работать быстрее. + +3. **Отключите рекурсивный поиск файлов:** В крайнем случае можно полностью отключить рекурсивный поиск файлов, установив `enableRecursiveFileSearch` в значение `false`. Это будет самым быстрым вариантом, так как избежит рекурсивного обхода проекта. Однако в этом случае вам придется вводить полный путь к файлам при использовании автодополнения через `@`. + +--- + - **`coreTools`** (массив строк): - - **Описание:** Позволяет указать список имен основных инструментов, которые должны быть доступны модели. Это можно использовать для ограничения набора встроенных инструментов. См. [Встроенные инструменты](../core/tools-api.md#built-in-tools) для списка основных инструментов. Вы также можете указать ограничения для конкретных команд для инструментов, которые это поддерживают, например, `ShellTool`. Например, `"coreTools": ["ShellTool(ls -l)"]` разрешит выполнение только команды `ls -l`. - - **По умолчанию:** Все инструменты, доступные для использования моделью. + - **Описание:** Позволяет указать список имен основных инструментов, которые должны быть доступны модели. Это можно использовать для ограничения набора встроенных инструментов. Список доступных инструментов см. в разделе [Встроенные инструменты](../core/tools-api.md#built-in-tools). Также можно указать ограничения на конкретные команды для инструментов, поддерживающих это, например, для `ShellTool`. Например, `"coreTools": ["ShellTool(ls -l)"]` разрешит выполнение только команды `ls -l`. + - **По умолчанию:** Все инструменты доступны для использования моделью. - **Пример:** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`. +- **`allowedTools`** (массив строк): + - **По умолчанию:** `undefined` + - **Описание:** Список имен инструментов, для которых будет пропущен диалог подтверждения. Полезно для часто используемых и доверенных инструментов. Логика сопоставления аналогична `coreTools`. + - **Пример:** `"allowedTools": ["ShellTool(git status)"]`. + - **`excludeTools`** (массив строк): - - **Описание:** Позволяет указать список имен основных инструментов, которые должны быть исключены из модели. Инструмент, указанный и в `excludeTools`, и в `coreTools`, будет исключен. Вы также можете указать ограничения для конкретных команд для инструментов, которые это поддерживают, например, `ShellTool`. Например, `"excludeTools": ["ShellTool(rm -rf)"]` заблокирует команду `rm -rf`. - - **По умолчанию:** Нет исключенных инструментов. + - **Описание:** Позволяет указать список имен инструментов, которые должны быть исключены из доступа модели. Инструмент, указанный и в `excludeTools`, и в `coreTools`, будет исключен. Также можно указывать ограничения на конкретные команды, например, для `ShellTool`. Например, `"excludeTools": ["ShellTool(rm -rf)"]` заблокирует команду `rm -rf`. + - **По умолчанию:** Никакие инструменты не исключены. - **Пример:** `"excludeTools": ["run_shell_command", "findFiles"]`. - - **Примечание по безопасности:** Ограничения для конкретных команд в `excludeTools` для `run_shell_command` основаны на простом сопоставлении строк и могут быть легко обойдены. Эта функция **не является механизмом безопасности** и не должна использоваться для безопасного выполнения недоверенного кода. Рекомендуется использовать `coreTools` для явного выбора команд, которые могут быть выполнены. + - **Примечание по безопасности:** Ограничения на уровне команд в `excludeTools` для `run_shell_command` основаны на простом сопоставлении строк и могут быть легко обойдены. Эта функция **не является механизмом безопасности** и не должна использоваться для безопасного выполнения недоверенного кода. Рекомендуется использовать `coreTools` для явного выбора разрешенных команд. - **`allowMCPServers`** (массив строк): - - **Описание:** Позволяет указать список имен серверов MCP, которые должны быть доступны модели. Это можно использовать для ограничения набора серверов MCP, к которым можно подключиться. Обратите внимание, что это будет проигнорировано, если установлен флаг `--allowed-mcp-server-names`. + - **Описание:** Позволяет указать список имен серверов MCP, которые должны быть доступны модели. Можно использовать для ограничения набора серверов MCP, к которым разрешено подключение. Обратите внимание, что этот параметр будет проигнорирован, если задан флаг `--allowed-mcp-server-names`. - **По умолчанию:** Все серверы MCP доступны для использования моделью. - **Пример:** `"allowMCPServers": ["myPythonServer"]`. - - **Примечание по безопасности:** Используется простое сопоставление строк по именам серверов MCP, которое может быть изменено. Если вы являетесь системным администратором и хотите предотвратить обход этого ограничения пользователями, рассмотрите возможность настройки `mcpServers` на уровне системных настроек так, чтобы пользователь не мог настроить свои собственные серверы MCP. Это не следует использовать как надежный механизм безопасности. + - **Примечание по безопасности:** Используется простое сопоставление строк по именам серверов MCP, которое может быть изменено. Если вы администратор системы и хотите предотвратить обход этого ограничения пользователями, рекомендуется настроить `mcpServers` на уровне системных настроек так, чтобы пользователи не могли задавать свои собственные серверы MCP. Не следует полагаться на это как на надежный механизм безопасности. - **`excludeMCPServers`** (массив строк): - - **Описание:** Позволяет указать список имен серверов MCP, которые должны быть исключены из модели. Сервер, указанный и в `excludeMCPServers`, и в `allowMCPServers`, будет исключен. Обратите внимание, что это будет проигнорировано, если установлен флаг `--allowed-mcp-server-names`. - - **По умолчанию:** Нет исключенных серверов MCP. + - **Описание:** Позволяет указать список имен серверов MCP, которые должны быть исключены из доступа модели. Сервер, указанный и в `excludeMCPServers`, и в `allowMCPServers`, будет исключен. Обратите внимание, что этот параметр будет проигнорирован, если задан флаг `--allowed-mcp-server-names`. + - **По умолчанию:** Никакие серверы MCP не исключены. - **Пример:** `"excludeMCPServers": ["myNodeServer"]`. - - **Примечание по безопасности:** Используется простое сопоставление строк по именам серверов MCP, которое может быть изменено. Если вы являетесь системным администратором и хотите предотвратить обход этого ограничения пользователями, рассмотрите возможность настройки `mcpServers` на уровне системных настроек так, чтобы пользователь не мог настроить свои собственные серверы MCP. Это не следует использовать как надежный механизм безопасности. + - **Примечание по безопасности:** Используется простое сопоставление строк по именам серверов MCP, которое может быть изменено. Если вы администратор системы и хотите предотвратить обход этого ограничения пользователями, рекомендуется настроить `mcpServers` на уровне системных настроек так, чтобы пользователи не могли задавать свои собственные серверы MCP. Не следует полагаться на это как на надежный механизм безопасности. - **`autoAccept`** (boolean): - - **Описание:** Управляет тем, будет ли CLI автоматически принимать и выполнять вызовы инструментов, которые считаются безопасными (например, операции только для чтения), без явного подтверждения пользователя. Если установлено значение `true`, CLI пропустит запрос на подтверждение для инструментов, считающихся безопасными. + - **Описание:** Определяет, будет ли CLI автоматически принимать и выполнять вызовы инструментов, считающихся безопасными (например, операции только для чтения), без явного подтверждения пользователя. Если установлено значение `true`, CLI пропустит запрос подтверждения для таких инструментов. - **По умолчанию:** `false` - **Пример:** `"autoAccept": true` - **`theme`** (string): - - **Описание:** Устанавливает визуальную [тему](./themes.md) для Qwen Code. + - **Описание:** Задает визуальную [тему](./themes.md) для Qwen Code. - **По умолчанию:** `"Default"` - **Пример:** `"theme": "GitHub"` - **`vimMode`** (boolean): - - **Описание:** Включает или отключает режим vim для редактирования ввода. При включении область ввода поддерживает команды навигации и редактирования в стиле vim с режимами NORMAL и INSERT. Статус режима vim отображается в нижнем колонтитуле и сохраняется между сессиями. + - **Описание:** Включает или отключает режим vim для редактирования ввода. При включении область ввода поддерживает навигацию и команды редактирования в стиле vim с режимами NORMAL и INSERT. Статус режима vim отображается в нижнем колонтитуле и сохраняется между сессиями. - **По умолчанию:** `false` - **Пример:** `"vimMode": true` - **`sandbox`** (boolean или string): - - **Описание:** Управляет тем, использовать ли песочницу для выполнения инструментов и как это делать. Если установлено значение `true`, Qwen Code использует предварительно собранный Docker-образ `qwen-code-sandbox`. Дополнительную информацию см. в разделе [Песочница](#sandboxing). + - **Описание:** Определяет, использовать ли песочницу для выполнения инструментов и как именно. Если установлено значение `true`, Qwen Code использует предварительно собраный Docker-образ `qwen-code-sandbox`. Подробнее см. в разделе [Песочница](#sandboxing). - **По умолчанию:** `false` - **Пример:** `"sandbox": "docker"` - **`toolDiscoveryCommand`** (string): - - **Описание:** Определяет пользовательскую shell-команду для обнаружения инструментов из вашего проекта. Команда shell должна возвращать на `stdout` массив JSON [объявлений функций](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). Обертки инструментов являются необязательными. + - **Описание:** **Совместимость с Gemini CLI.** Определяет пользовательскую shell-команду для обнаружения инструментов в вашем проекте. Команда должна выводить в `stdout` JSON-массив [объявлений функций](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). Обертки инструментов не обязательны. - **По умолчанию:** Пусто - **Пример:** `"toolDiscoveryCommand": "bin/get_tools"` - **`toolCallCommand`** (string): - - **Описание:** Определяет пользовательскую shell-команду для вызова конкретного инструмента, обнаруженного с помощью `toolDiscoveryCommand`. Команда shell должна соответствовать следующим критериям: - - Она должна принимать имя функции (точно как в [объявлении функции](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) в качестве первого аргумента командной строки. - - Она должна читать аргументы функции в формате JSON из `stdin`, аналогично [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). - - Она должна возвращать вывод функции в формате JSON в `stdout`, аналогично [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). + - **Описание:** **Совместимость с Gemini CLI.** Определяет пользовательскую shell-команду для вызова конкретного инструмента, найденного через `toolDiscoveryCommand`. Команда должна соответствовать следующим требованиям: + - Первым аргументом командной строки должно быть имя функции (точно как в [объявлении функции](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)). + - Функция должна читать аргументы в формате JSON из `stdin`, аналогично [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). + - Функция должна возвращать результат в формате JSON в `stdout`, аналогично [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). - **По умолчанию:** Пусто - **Пример:** `"toolCallCommand": "bin/call_tool"` - **`mcpServers`** (object): - - **Описание:** Настраивает подключения к одному или нескольким серверам Model-Context Protocol (MCP) для обнаружения и использования пользовательских инструментов. Qwen Code пытается подключиться к каждому настроенному серверу MCP для обнаружения доступных инструментов. Если несколько серверов MCP предоставляют инструмент с одинаковым именем, имена инструментов будут дополнены псевдонимом сервера, определенным в конфигурации (например, `serverAlias__actualToolName`), чтобы избежать конфликтов. Обратите внимание, что система может удалить определенные свойства схемы из определений инструментов MCP для совместимости. Необходимо указать хотя бы одно из следующих: `command`, `url` или `httpUrl`. Если указано несколько, приоритет имеет следующий порядок: `httpUrl`, затем `url`, затем `command`. + - **Описание:** Настраивает подключения к одному или нескольким серверам Model-Context Protocol (MCP) для обнаружения и использования пользовательских инструментов. Qwen Code пытается подключиться к каждому указанному серверу MCP для получения списка доступных инструментов. Если несколько серверов предоставляют инструмент с одинаковым именем, имена инструментов будут дополнены псевдонимом сервера (например, `serverAlias__actualToolName`), чтобы избежать конфликта. Обратите внимание, что система может удалить некоторые свойства схемы из определений инструментов MCP для обеспечения совместимости. Должно быть указано хотя бы одно из полей: `command`, `url` или `httpUrl`. Если указано несколько, приоритет имеет следующий порядок: `httpUrl`, затем `url`, затем `command`. - **По умолчанию:** Пусто - **Свойства:** - - **``** (object): Параметры сервера для указанного сервера. - - `command` (string, необязательно): Команда для запуска сервера MCP через стандартный ввод/вывод. - - `args` (массив строк, необязательно): Аргументы, передаваемые команде. - - `env` (object, необязательно): Переменные окружения, устанавливаемые для процесса сервера. - - `cwd` (string, необязательно): Рабочая директория, в которой запускается сервер. - - `url` (string, необязательно): URL сервера MCP, использующего Server-Sent Events (SSE) для связи. - - `httpUrl` (string, необязательно): URL сервера MCP, использующего потоковое HTTP для связи. - - `headers` (object, необязательно): Карта HTTP-заголовков, отправляемых с запросами к `url` или `httpUrl`. - - `timeout` (number, необязательно): Таймаут в миллисекундах для запросов к этому серверу MCP. - - `trust` (boolean, необязательно): Доверять этому серверу и обходить все подтверждения вызова инструментов. - - `description` (string, необязательно): Краткое описание сервера, которое может использоваться для отображения. - - `includeTools` (массив строк, необязательно): Список имен инструментов, которые следует включить с этого сервера MCP. Если указано, только перечисленные здесь инструменты будут доступны с этого сервера (поведение белого списка). Если не указано, по умолчанию включаются все инструменты с сервера. - - `excludeTools` (массив строк, необязательно): Список имен инструментов, которые следует исключить с этого сервера MCP. Перечисленные здесь инструменты не будут доступны модели, даже если они предоставлены сервером. **Примечание:** `excludeTools` имеет приоритет над `includeTools` — если инструмент присутствует в обоих списках, он будет исключен. + - **``** (object): Параметры сервера с указанным именем. + - `command` (string, опционально): Команда для запуска сервера MCP через стандартный ввод-вывод. + - `args` (массив строк, опционально): Аргументы командной строки. + - `env` (object, опционально): Переменные окружения для процесса сервера. + - `cwd` (string, опционально): Рабочая директория для запуска сервера. + - `url` (string, опционально): URL сервера MCP, использующего Server-Sent Events (SSE) для связи. + - `httpUrl` (string, опционально): URL сервера MCP, использующего потоковое HTTP для связи. + - `headers` (object, опционально): HTTP-заголовки для запросов к `url` или `httpUrl`. + - `timeout` (number, опционально): Таймаут в миллисекундах для запросов к этому серверу MCP. + - `trust` (boolean, опционально): Доверять этому серверу и пропускать все подтверждения вызовов инструментов. + - `description` (string, опционально): Краткое описание сервера, может использоваться для отображения. + - `includeTools` (массив строк, опционально): Список имен инструментов, которые нужно включить с этого сервера. Если указан, то будут доступны только перечисленные инструменты (whitelist). Если не указан — доступны все инструменты сервера. + - `excludeTools` (массив строк, опционально): Список имен инструментов, которые нужно исключить с этого сервера. Эти инструменты не будут доступны модели, даже если они предоставлены сервером. **Примечание:** `excludeTools` имеет приоритет над `includeTools` — если инструмент есть в обоих списках, он будет исключен. - **Пример:** ```json "mcpServers": { @@ -183,13 +206,13 @@ Qwen Code использует файлы `settings.json` для хранени ``` - **`checkpointing`** (object): - - **Описание:** Настраивает функцию контрольных точек, которая позволяет сохранять и восстанавливать состояния разговора и файлов. Подробнее см. в [документации по контрольным точкам](../checkpointing.md). + - **Описание:** Настраивает функцию контрольных точек, позволяющую сохранять и восстанавливать состояние беседы и файлов. Подробнее см. в [документации по контрольным точкам](../checkpointing.md). - **По умолчанию:** `{"enabled": false}` - **Свойства:** - **`enabled`** (boolean): Если `true`, команда `/restore` становится доступной. - **`preferredEditor`** (string): - - **Описание:** Указывает предпочтительный редактор для просмотра diff. + - **Описание:** Указывает предпочитаемый редактор для просмотра diff'ов. - **По умолчанию:** `vscode` - **Пример:** `"preferredEditor": "vscode"` @@ -198,9 +221,9 @@ Qwen Code использует файлы `settings.json` для хранени - **По умолчанию:** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **Свойства:** - **`enabled`** (boolean): Включена ли телеметрия. - - **`target`** (string): Назначение для собранной телеметрии. Поддерживаемые значения: `local` и `gcp`. - - **`otlpEndpoint`** (string): Конечная точка для экспортера OTLP. - - **`logPrompts`** (boolean): Включать ли содержимое пользовательских prompt в логи. + - **`target`** (string): Назначение собранных данных. Поддерживаются значения `local` и `gcp`. + - **`otlpEndpoint`** (string): Endpoint для экспортера OTLP. + - **`logPrompts`** (boolean): Включать ли содержимое пользовательских запросов в логи. - **Пример:** ```json "telemetry": { @@ -210,6 +233,7 @@ Qwen Code использует файлы `settings.json` для хранени "logPrompts": false } ``` + - **`usageStatisticsEnabled`** (boolean): - **Описание:** Включает или отключает сбор статистики использования. Подробнее см. в разделе [Статистика использования](#usage-statistics). - **По умолчанию:** `true` @@ -222,12 +246,20 @@ Qwen Code использует файлы `settings.json` для хранени - **Описание:** Включает или отключает полезные подсказки в интерфейсе CLI. - **По умолчанию:** `false` - **Пример:** - ```json "hideTips": true ``` -- ** +- **`hideBanner`** (boolean): + - **Описание:** Включает или отключает стартовый баннер (ASCII-арт логотип) в интерфейсе CLI. + - **По умолчанию:** `false` + - **Пример:** + ```json + "hideBanner": true + ``` + +- **`maxSessionTurns`** (number): + - **Описание:** Устанавливает максимальное количество шагов (turns) в сесс ### Пример `settings.json`: @@ -256,6 +288,8 @@ Qwen Code использует файлы `settings.json` для хранени "usageStatisticsEnabled": true, "hideTips": false, "hideBanner": false, + "skipNextSpeakerCheck": false, + "skipLoopDetection": false, "maxSessionTurns": 10, "summarizeToolOutput": { "run_shell_command": { @@ -274,7 +308,7 @@ CLI сохраняет историю выполненных вами shell-ко - **Расположение:** `~/.qwen/tmp//shell_history` - `` — это уникальный идентификатор, сгенерированный на основе корневого пути вашего проекта. - - История хранится в файле с именем `shell_history`. + - История сохраняется в файле с именем `shell_history`. ## Переменные окружения и файлы `.env` @@ -283,10 +317,10 @@ CLI сохраняет историю выполненных вами shell-ко CLI автоматически загружает переменные окружения из файла `.env`. Порядок загрузки следующий: 1. Файл `.env` в текущей рабочей директории. -2. Если файл не найден, CLI ищет его в родительских директориях, пока не найдёт `.env` или не достигнет корня проекта (определяется по наличию папки `.git`) или домашней директории. -3. Если файл всё ещё не найден, CLI проверяет наличие `~/.env` (в домашней директории пользователя). +2. Если файл не найден, CLI ищет его в родительских директориях, пока не найдёт `.env` или не достигнет корня проекта (определяется наличием папки `.git`) или домашней директории. +3. Если файл всё ещё не найден, CLI пытается загрузить `~/.env` (в домашней директории пользователя). -**Исключение переменных окружения:** Некоторые переменные (например, `DEBUG` и `DEBUG_MODE`) по умолчанию исключаются из проектных `.env` файлов, чтобы не мешать работе CLI. Переменные из файлов `.qwen/.env` никогда не исключаются. Это поведение можно настроить с помощью параметра `excludedProjectEnvVars` в файле `settings.json`. +**Исключение переменных окружения:** Некоторые переменные (например, `DEBUG` и `DEBUG_MODE`) по умолчанию исключаются из проектных `.env` файлов, чтобы не мешать работе CLI. Переменные из файлов `.qwen/.env` никогда не исключаются. Это поведение можно изменить с помощью настройки `excludedProjectEnvVars` в файле `settings.json`. - **`OPENAI_API_KEY`**: - Один из доступных [методов аутентификации](./authentication.md). @@ -304,10 +338,10 @@ CLI автоматически загружает переменные окру - **`SEATBELT_PROFILE`** (только для macOS): - Переключает профиль Seatbelt (`sandbox-exec`) в macOS. - `permissive-open`: (по умолчанию) Ограничивает запись в папку проекта (и несколько других, см. `packages/cli/src/utils/sandbox-macos-permissive-open.sb`), но разрешает другие операции. - - `strict`: Использует строгий профиль, который по умолчанию блокирует операции. + - `strict`: Использует строгий профиль, который по умолчанию запрещает операции. - ``: Использует кастомный профиль. Чтобы определить кастомный профиль, создайте файл с именем `sandbox-macos-.sb` в директории `.qwen/` вашего проекта (например, `my-project/.qwen/sandbox-macos-custom.sb`). - **`DEBUG` или `DEBUG_MODE`** (часто используются библиотеками или самим CLI): - - Установите в `true` или `1`, чтобы включить подробный debug-лог, полезный при отладке. + - Установите в `true` или `1`, чтобы включить подробный режим отладки — это может быть полезно при решении проблем. - **Примечание:** Эти переменные по умолчанию исключаются из проектных `.env` файлов, чтобы не мешать работе CLI. Если нужно задать их для Qwen Code, используйте файлы `.qwen/.env`. - **`NO_COLOR`**: - Установите любое значение, чтобы отключить цветной вывод в CLI. @@ -351,12 +385,16 @@ CLI автоматически загружает переменные окру - **`--yolo`**: - Включает режим YOLO, который автоматически одобряет все вызовы инструментов. - **`--approval-mode `**: - - Устанавливает режим подтверждения вызовов инструментов. Доступные режимы: - - `default`: Запрашивать подтверждение для каждого вызова инструмента (поведение по умолчанию) - - `auto_edit`: Автоматически одобрять инструменты редактирования (edit, write_file), запрашивая подтверждение для остальных - - `yolo`: Автоматически одобрять все вызовы инструментов (эквивалент `--yolo`) + - Устанавливает режим подтверждения для вызовов инструментов. Поддерживаемые режимы: + - `plan`: Только анализ — не изменяет файлы и не выполняет команды. + - `default`: Требует подтверждения для редактирования файлов или выполнения shell-команд (поведение по умолчанию). + - `auto-edit`: Автоматически одобряет инструменты редактирования (edit, write_file), запрашивая подтверждение для остальных. + - `yolo`: Автоматически одобряет все вызовы инструментов (эквивалент `--yolo`). - Не может использоваться вместе с `--yolo`. Используйте `--approval-mode=yolo` вместо `--yolo` для нового унифицированного подхода. - - Пример: `qwen --approval-mode auto_edit` + - Пример: `qwen --approval-mode auto-edit` +- **`--allowed-tools `**: + - Список инструментов, разделённых запятыми, которые будут обходить диалог подтверждения. + - Пример: `qwen --allowed-tools "ShellTool(git status)"` - **`--telemetry`**: - Включает [телеметрию](../telemetry.md). - **`--telemetry-target`**: @@ -364,11 +402,11 @@ CLI автоматически загружает переменные окру - **`--telemetry-otlp-endpoint`**: - Устанавливает OTLP endpoint для телеметрии. Подробнее см. в [телеметрии](../telemetry.md). - **`--telemetry-otlp-protocol`**: - - Устанавливает OTLP протокол для телеметрии (`grpc` или `http`). По умолчанию — `grpc`. Подробнее см. в [телеметрии](../telemetry.md). + - Устанавливает OTLP протокол для телеметрии (`grpc` или `http`). По умолчанию `grpc`. Подробнее см. в [телеметрии](../telemetry.md). - **`--telemetry-log-prompts`**: - Включает логирование prompt'ов для телеметрии. Подробнее см. в [телеметрии](../telemetry.md). - **`--checkpointing`**: - - Включает [checkpointing](../checkpointing.md). + - Включает [чекпоинтинг](../checkpointing.md). - **`--extensions `** (**`-e `**): - Указывает список расширений для использования в сессии. Если не указано, используются все доступные расширения. - Используйте специальное значение `qwen -e none`, чтобы отключить все расширения. @@ -376,26 +414,28 @@ CLI автоматически загружает переменные окру - **`--list-extensions`** (**`-l`**): - Выводит список всех доступных расширений и завершает работу. - **`--proxy`**: - - Устанавливает proxy для CLI. + - Устанавливает прокси для CLI. - Пример: `--proxy http://localhost:7890`. - **`--include-directories `**: - - Добавляет дополнительные директории в рабочее пространство для поддержки работы с несколькими директориями. - - Можно указывать несколько раз или через запятую. + - Добавляет дополнительные директории в рабочую область для поддержки работы с несколькими директориями. + - Можно указывать несколько раз или в виде значений, разделённых запятыми. - Максимум можно добавить 5 директорий. - Пример: `--include-directories /path/to/project1,/path/to/project2` или `--include-directories /path/to/project1 --include-directories /path/to/project2` +- **`--screen-reader`**: + - Включает режим чтения с экрана для обеспечения доступности. - **`--version`**: - Отображает версию CLI. - **`--openai-logging`**: - Включает логирование вызовов OpenAI API для отладки и анализа. Этот флаг переопределяет настройку `enableOpenAILogging` в `settings.json`. - **`--tavily-api-key `**: - - Устанавливает Tavily API key для функции веб-поиска в этой сессии. + - Устанавливает API-ключ Tavily для функции веб-поиска в этой сессии. - Пример: `qwen --tavily-api-key tvly-your-api-key-here` ## Файлы контекста (иерархический instructional context) -Хотя файлы контекста не являются строгой конфигурацией _поведения_ CLI, они играют ключевую роль в настройке _инструкционного контекста_ (также называемого "памятью"). По умолчанию используется файл `QWEN.md`, но имя файла можно изменить через настройку `contextFileName`. Эта мощная функция позволяет передавать AI проект-специфичные инструкции, руководства по стилю кода или любую другую релевантную информацию, делая ответы модели более точными и соответствующими вашим потребностям. CLI включает UI-элементы, например, индикатор в нижнем колонтитуле, показывающий количество загруженных файлов контекста, чтобы вы всегда были в курсе активного контекста. +Хотя файлы контекста не являются строгой конфигурацией _поведения_ CLI, они играют ключевую роль в настройке _инструкционного контекста_ (также называемого "памятью"). По умолчанию используется файл `QWEN.md`, но имя файла можно изменить с помощью настройки `contextFileName`. Эта мощная функция позволяет передавать ИИ проектные инструкции, руководства по стилю кода или любую другую релевантную информацию, благодаря чему ответы модели становятся более точными и соответствующими вашим ожиданиям. CLI включает элементы интерфейса, например индикатор в нижнем колонтитуле, показывающий количество загруженных файлов контекста, чтобы вы всегда могли видеть, какой контекст активен. -- **Назначение:** Эти Markdown-файлы содержат инструкции, руководящие принципы или контекст, который вы хотите, чтобы модель Qwen учитывала во время взаимодействия. Система спроектирована так, чтобы управлять этим инструкционным контекстом иерархически. +- **Назначение:** Эти Markdown-файлы содержат инструкции, рекомендации или контекст, который вы хотите, чтобы модель Qwen учитывала во время взаимодействия. Система спроектирована так, чтобы управлять этим инструкционным контекстом иерархически. ### Пример содержимого контекстного файла (например, `QWEN.md`) @@ -409,14 +449,14 @@ CLI автоматически загружает переменные окру - При генерации нового кода на TypeScript следуйте существующему стилю кодирования. - Убедитесь, что все новые функции и классы сопровождаются комментариями JSDoc. -- Предпочтительно использовать парадигмы функционального программирования, где это уместно. +- Предпочтение отдавайте парадигмам функционального программирования, где это уместно. - Весь код должен быть совместим с TypeScript 5.0 и Node.js 20+. ## Стиль кодирования: - Используйте 2 пробела для отступов. -- Имена интерфейсов должны начинаться с префикса `I` (например, `IUserService`). -- Приватные члены класса должны начинаться с символа подчеркивания (`_`). +- Названия интерфейсов должны начинаться с префикса `I` (например, `IUserService`). +- Приватные члены классов должны начинаться с символа подчеркивания (`_`). - Всегда используйте строгое равенство (`===` и `!==`). ## Конкретный компонент: `src/api/client.ts` @@ -425,52 +465,51 @@ CLI автоматически загружает переменные окру - При добавлении новых функций вызова API убедитесь, что они включают надежную обработку ошибок и логирование. - Используйте существующую утилиту `fetchWithRetry` для всех GET-запросов. -```markdown ## О зависимостях: -- Избегайте добавления новых внешних зависимостей, если в этом нет абсолютной необходимости. +- Избегайте добавления новых внешних зависимостей, если в этом нет крайней необходимости. - Если новая зависимость необходима, пожалуйста, укажите причину. +``` -Этот пример демонстрирует, как можно предоставить общий контекст проекта, конкретные соглашения по кодированию, а также заметки о конкретных файлах или компонентах. Чем более релевантны и точны ваши контекстные файлы, тем лучше ИИ сможет вам помочь. Мы настоятельно рекомендуем использовать специфичные для проекта контекстные файлы для установления соглашений и контекста. +Этот пример демонстрирует, как можно предоставить общий контекст проекта, конкретные соглашения по кодированию, а также заметки о конкретных файлах или компонентах. Чем более релевантны и точны ваши контекстные файлы, тем лучше ИИ сможет вам помочь. Настоятельно рекомендуется использовать специфичные для проекта контекстные файлы для установления соглашений и контекста. -- **Иерархическая загрузка и приоритет:** CLI реализует сложную иерархическую систему памяти, загружая контекстные файлы (например, `QWEN.md`) из нескольких источников. Содержимое файлов, находящихся ниже в этом списке (более специфичных), обычно переопределяет или дополняет содержимое файлов выше (более общих). Точный порядок объединения и финальный контекст можно проверить с помощью команды `/memory show`. Типичный порядок загрузки следующий: +- **Иерархическая загрузка и приоритет:** CLI реализует сложную иерархическую систему памяти, загружая контекстные файлы (например, `QWEN.md`) из нескольких источников. Содержимое файлов, находящихся ниже в этом списке (более специфичных), как правило, переопределяет или дополняет содержимое файлов выше (более общих). Точный порядок объединения и финальный контекст можно проверить с помощью команды `/memory show`. Типичный порядок загрузки следующий: 1. **Глобальный контекстный файл:** - Расположение: `~/.qwen/` (например, `~/.qwen/QWEN.md` в вашем домашнем каталоге пользователя). - Область применения: Предоставляет стандартные инструкции для всех ваших проектов. 2. **Контекстные файлы корня проекта и его предков:** - - Расположение: CLI ищет указанный контекстный файл в текущем рабочем каталоге, а затем в каждом родительском каталоге вплоть до корня проекта (определяемого папкой `.git`) или вашего домашнего каталога. + - Расположение: CLI ищет указанный контекстный файл в текущей рабочей директории, а затем в каждой родительской директории вплоть до корня проекта (определяемого наличием папки `.git`) или вашего домашнего каталога. - Область применения: Предоставляет контекст, относящийся ко всему проекту или значительной его части. 3. **Контекстные файлы подкаталогов (локальные/контекстуальные):** - - Расположение: CLI также сканирует наличие указанного контекстного файла в подкаталогах _ниже_ текущего рабочего каталога (с учетом стандартных игнорируемых паттернов, таких как `node_modules`, `.git` и т.д.). По умолчанию глубина поиска ограничена 200 каталогами, но может быть изменена с помощью поля `memoryDiscoveryMaxDirs` в вашем файле `settings.json`. - - Область применения: Позволяет задавать очень специфичные инструкции, относящиеся к конкретному компоненту, модулю или разделу проекта. -- **Объединение и отображение в интерфейсе:** Содержимое всех найденных контекстных файлов объединяется (с разделителями, указывающими их источник и путь) и передается как часть системного prompt'а. В нижнем колонтитуле CLI отображается количество загруженных контекстных файлов — это позволяет быстро визуально оценить активный инструкционный контекст. -- **Импорт содержимого:** Вы можете модуляризировать свои контекстные файлы, импортируя другие Markdown-файлы с помощью синтаксиса `@path/to/file.md`. Подробнее см. в [документации Memory Import Processor](../core/memport.md). + - Расположение: CLI также сканирует наличие указанного контекстного файла в подкаталогах _ниже_ текущей рабочей директории (с учетом стандартных игнорируемых путей, таких как `node_modules`, `.git` и т.д.). По умолчанию глубина поиска ограничена 200 каталогами, но может быть изменена с помощью поля `memoryDiscoveryMaxDirs` в вашем файле `settings.json`. + - Область применения: Позволяет задать очень специфичные инструкции, относящиеся к конкретному компоненту, модулю или разделу проекта. +- **Объединение и отображение в интерфейсе:** Содержимое всех найденных контекстных файлов объединяется (с разделителями, указывающими их источник и путь) и передается как часть системного prompt'а. В нижнем колонтитуле CLI отображается количество загруженных контекстных файлов — это позволяет быстро оценить объем активного инструкционного контекста. +- **Импорт содержимого:** Вы можете модуляризировать свои контекстные файлы, импортируя другие Markdown-файлы с помощью синтаксиса `@path/to/file.md`. Подробнее см. в [документации по Memory Import Processor](../core/memport.md). - **Команды управления памятью:** - Используйте `/memory refresh`, чтобы принудительно пересканировать и перезагрузить все контекстные файлы из всех настроенных источников. Это обновит инструкционный контекст ИИ. - Используйте `/memory show`, чтобы отобразить текущий объединённый инструкционный контекст, что позволит вам проверить иерархию и содержимое, используемое ИИ. - - Полная информация о команде `/memory` и её подкомандах (`show` и `refresh`) доступна в [документации по командам](./commands.md#memory). + - Полное описание команды `/memory` и её подкоманд (`show` и `refresh`) см. в [документации по командам](./commands.md#memory). Понимая и используя эти уровни конфигурации и иерархическую природу контекстных файлов, вы сможете эффективно управлять памятью ИИ и адаптировать ответы Qwen Code под ваши конкретные нужды и проекты. -``` ## Sandboxing -Qwen Code может выполнять потенциально небезопасные операции (например, shell-команды и модификации файлов) в sandbox-окружении, чтобы защитить вашу систему. +Qwen Code может выполнять потенциально небезопасные операции (например, shell-команды и изменения файлов) в sandbox-окружении для защиты вашей системы. По умолчанию sandboxing отключен, но вы можете включить его несколькими способами: - Используя флаг `--sandbox` или `-s`. -- Установив переменную окружения `GEMINI_SANDBOX`. +- Установив переменную окружения `GEMFI_SANDBOX`. - Sandbox включается по умолчанию при использовании `--yolo` или `--approval-mode=yolo`. -По умолчанию используется готовый Docker-образ `qwen-code-sandbox`. +По умолчанию используется предварительно собранный Docker-образ `qwen-code-sandbox`. -Если вашему проекту нужны особые настройки sandboxing, вы можете создать собственный Dockerfile по пути `.qwen/sandbox.Dockerfile` в корневой директории проекта. Этот Dockerfile может быть основан на базовом sandbox-образе: +Если вам нужно настроить sandbox под конкретный проект, вы можете создать собственный Dockerfile по пути `.qwen/sandbox.Dockerfile` в корневой директории вашего проекта. Этот Dockerfile может быть основан на базовом sandbox-образе: ```dockerfile FROM qwen-code-sandbox -# Добавьте сюда свои зависимости или настройки +# Добавьте сюда свои зависимости или конфигурации # Например: @@ -492,17 +531,17 @@ BUILD_SANDBOX=1 qwen -s **Что мы собираем:** -- **Вызовы инструментов:** Мы записываем названия вызванных инструментов, успешность их выполнения и время выполнения. Мы не собираем аргументы, переданные инструментам, или любые данные, возвращенные ими. -- **API-запросы:** Мы записываем модель, использованную для каждого запроса, продолжительность запроса и его успешность. Мы не собираем содержимое промтов или ответов. +- **Вызовы инструментов:** Мы записываем названия вызываемых инструментов, информацию об успешном или неудачном выполнении и время их выполнения. Мы не собираем аргументы, переданные инструментам, или любые данные, возвращенные ими. +- **API-запросы:** Мы записываем модель, использованную для каждого запроса, продолжительность запроса и информацию об успешном выполнении. Мы не собираем содержимое промптов или ответов. - **Информация о сессии:** Мы собираем информацию о конфигурации CLI, например, включенные инструменты и режим подтверждения. **Что мы НЕ собираем:** -- **Персональные данные (PII):** Мы не собираем никакой личной информации, такой как ваше имя, адрес электронной почты или API-ключи. -- **Содержимое промтов и ответов:** Мы не записываем содержимое ваших промтов или ответов модели. +- **Персональные данные (PII):** Мы не собираем никакой персональной информации, такой как ваше имя, адрес электронной почты или API-ключи. +- **Содержимое промптов и ответов:** Мы не записываем содержимое ваших промптов или ответов модели. - **Содержимое файлов:** Мы не записываем содержимое файлов, которые читаются или записываются CLI. -**Как отказаться от сбора:** +**Как отключить сбор статистики:** Вы можете отказаться от сбора статистики использования в любое время, установив значение свойства `usageStatisticsEnabled` в `false` в вашем файле `settings.json`: @@ -512,7 +551,7 @@ BUILD_SANDBOX=1 qwen -s } ``` -Примечание: Когда статистика использования включена, события отправляются на эндпоинт сбора Alibaba Cloud RUM. +Примечание: Когда статистика использования включена, события отправляются на эндпоинт сбора данных Alibaba Cloud RUM. - **`enableWelcomeBack`** (boolean): - **Описание:** Показывать диалог приветствия при возвращении в проект с историей разговора. diff --git a/website/content/ru/cli/themes.md b/website/content/ru/cli/themes.md index 277519f9..cad77f72 100644 --- a/website/content/ru/cli/themes.md +++ b/website/content/ru/cli/themes.md @@ -1,10 +1,10 @@ # Темы -Qwen Code поддерживает различные темы для настройки цветовой схемы и внешнего вида. Вы можете изменить тему в соответствии со своими предпочтениями с помощью команды `/theme` или через настройку `"theme":` в конфигурации. +Qwen Code поддерживает различные темы для настройки цветовой схемы и внешнего вида. Вы можете изменить тему в соответствии со своими предпочтениями с помощью команды `/theme` или через параметр конфигурации `"theme":`. ## Доступные темы -Qwen Code поставляется с набором предустановленных тем, которые можно посмотреть, введя команду `/theme` в CLI: +Qwen Code поставляется с набором предустановленных тем, которые можно посмотреть, используя команду `/theme` в CLI: - **Темные темы:** - `ANSI` @@ -21,16 +21,18 @@ Qwen Code поставляется с набором предустановле - `Google Code` - `Xcode` -### Как изменить тему +### Смена тем 1. Введите `/theme` в Qwen Code. -2. Появится диалоговое окно или список с доступными темами. -3. С помощью стрелок выберите нужную тему. В некоторых интерфейсах может быть доступен предпросмотр или подсветка выбранной темы. -4. Подтвердите выбор, чтобы применить тему. +2. Появится диалоговое окно или приглашение к выбору, в котором будут перечислены доступные темы. +3. С помощью клавиш со стрелками выберите тему. В некоторых интерфейсах может отображаться предварительный просмотр или подсветка при выборе. +4. Подтвердите свой выбор, чтобы применить тему. + +**Примечание:** Если тема определена в вашем файле `settings.json` (по имени или пути к файлу), вы должны удалить настройку `"theme"` из файла, прежде чем вы сможете изменить тему с помощью команды `/theme`. ### Сохранение тем -Выбранные темы сохраняются в [конфигурации](./configuration.md) Qwen Code, поэтому ваши предпочтения запоминаются между сессиями. +Выбранные темы сохраняются в [конфигурации](./configuration.md) Qwen Code, поэтому ваш выбор будет запоминаться между сессиями. --- @@ -101,19 +103,59 @@ Qwen Code позволяет создавать собственные цвет - `Comment` - `Gray` -Для любого цветового значения можно использовать либо hex-коды (например, `#FF0000`), **либо** стандартные CSS-названия цветов (например, `coral`, `teal`, `blue`). Полный список поддерживаемых названий смотрите здесь: [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords). +Для любого цветового значения можно использовать hex-коды (например, `#FF0000`) **или** стандартные CSS-названия цветов (например, `coral`, `teal`, `blue`). Полный список поддерживаемых названий см. в [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords). Вы можете определить несколько кастомных тем, добавляя дополнительные записи в объект `customThemes`. -### Пример пользовательской темы +### Загрузка тем из файла + +Помимо определения пользовательских тем в `settings.json`, вы также можете загрузить тему напрямую из JSON-файла, указав путь к файлу в вашем `settings.json`. Это удобно для совместного использования тем или хранения их отдельно от основной конфигурации. + +Чтобы загрузить тему из файла, установите свойство `theme` в вашем `settings.json` равным пути к файлу темы: + +```json +{ + "theme": "/path/to/your/theme.json" +} +``` + +Файл темы должен быть корректным JSON-файлом и следовать той же структуре, что и пользовательская тема, определенная в `settings.json`. + +**Пример `my-theme.json`:** + +```json +{ + "name": "My File Theme", + "type": "custom", + "Background": "#282A36", + "Foreground": "#F8F8F2", + "LightBlue": "#82AAFF", + "AccentBlue": "#61AFEF", + "AccentPurple": "#BD93F9", + "AccentCyan": "#8BE9FD", + "AccentGreen": "#50FA7B", + "AccentYellow": "#F1FA8C", + "AccentRed": "#FF5555", + "Comment": "#6272A4", + "Gray": "#ABB2BF", + "DiffAdded": "#A6E3A1", + "DiffRemoved": "#F38BA8", + "DiffModified": "#89B4FA", + "GradientColors": ["#4796E4", "#847ACE", "#C3677F"] +} +``` + +**Примечание по безопасности:** В целях вашей безопасности Gemini CLI будет загружать только те файлы тем, которые находятся внутри вашей домашней директории. Если вы попытаетесь загрузить тему извне домашней директории, будет показано предупреждение, и тема не будет загружена. Это сделано для предотвращения загрузки потенциально вредоносных файлов тем из ненадежных источников. + +### Пример кастомной темы -Пример пользовательской темы +Пример кастомной темы -### Использование вашей пользовательской темы +### Использование вашей кастомной темы -- Выберите свою тему с помощью команды `/theme` в Qwen Code. Ваша пользовательская тема появится в диалоге выбора тем. -- Или установите её по умолчанию, добавив `"theme": "MyCustomTheme"` в ваш файл `settings.json`. -- Пользовательские темы можно задать на уровне пользователя, проекта или системы и они подчиняются тому же [порядку приоритета конфигурации](./configuration.md), что и другие настройки. +- Выберите свою кастомную тему с помощью команды `/theme` в Qwen Code. Ваша кастомная тема появится в диалоге выбора тем. +- Либо установите её как тему по умолчанию, добавив `"theme": "MyCustomTheme"` в ваш файл `settings.json`. +- Кастомные темы можно задавать на уровне пользователя, проекта или системы и они подчиняются тому же [порядку приоритетов конфигурации](./configuration.md), что и другие настройки. --- diff --git a/website/content/ru/deployment.md b/website/content/ru/deployment.md index baee44a3..b694f947 100644 --- a/website/content/ru/deployment.md +++ b/website/content/ru/deployment.md @@ -1,6 +1,6 @@ # Выполнение и развертывание Qwen Code -В этом документе описано, как запустить Qwen Code, и объясняется архитектура развертывания, которую использует Qwen Code. +Этот документ описывает, как запустить Qwen Code, и объясняет архитектуру развертывания, которую использует Qwen Code. ## Запуск Qwen Code @@ -8,7 +8,7 @@ --- -### 1. Стандартная установка (рекомендуется для обычных пользователей) +### 1. Стандартная установка (Рекомендуется для обычных пользователей) Это рекомендуемый способ установки Qwen Code для конечных пользователей. Он включает загрузку пакета Qwen Code из реестра NPM. @@ -18,13 +18,13 @@ npm install -g @qwen-code/qwen-code ``` - Затем CLI можно запустить из любого места: + Затем запустите CLI из любого места: ```bash qwen ``` -- **Запуск через NPX:** +- **Выполнение через NPX:** ```bash # Выполнить последнюю версию из NPM без глобальной установки @@ -35,16 +35,16 @@ ### 2. Запуск в песочнице (Docker/Podman) -Для обеспечения безопасности и изоляции Qwen Code можно запускать внутри контейнера. Это способ запуска CLI по умолчанию для инструментов, которые могут иметь побочные эффекты. +Для обеспечения безопасности и изоляции Qwen Code можно запускать внутри контейнера. Это способ по умолчанию, который CLI использует для выполнения инструментов, которые могут иметь побочные эффекты. - **Прямой запуск из Registry:** - Вы можете запустить опубликованный образ песочницы напрямую. Это удобно в средах, где установлен только Docker, и вы хотите запустить CLI. + Вы можете запустить опубликованный образ песочницы напрямую. Это удобно для сред, где у вас есть только Docker и вы хотите запустить CLI. ```bash # Запуск опубликованного образа песочницы - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.11 ``` - **Использование флага `--sandbox`:** - Если у вас локально установлен Qwen Code (стандартной установкой, описанной выше), вы можете указать ему запускаться внутри контейнера песочницы. + Если у вас локально установлен Qwen Code (с использованием стандартной установки, описанной выше), вы можете указать ему запускаться внутри контейнера песочницы. ```bash qwen --sandbox -y -p "your prompt here" ``` @@ -56,19 +56,19 @@ Контрибьюторы проекта захотят запускать CLI напрямую из исходного кода. - **Режим разработки:** - Этот метод обеспечивает hot-reloading и удобен для активной разработки. + Этот метод обеспечивает hot-reloading и удобен при активной разработке. ```bash # Из корня репозитория npm run start ``` - **Production-подобный режим (Linked package):** - Этот метод имитирует глобальную установку путем линковки вашего локального пакета. Полезно для тестирования локальной сборки в production-подобном workflow. + Этот метод имитирует глобальную установку путем линковки вашего локального пакета. Полезно для тестирования локальной сборки в production-сценарии. ```bash - # Линкуем локальный cli пакет в глобальный node_modules + # Линкуем локальный cli пакет в глобальные node_modules npm link packages/cli - # Теперь вы можете запускать вашу локальную версию с помощью команды `qwen` + # Теперь вы можете запустить вашу локальную версию с помощью команды `qwen` qwen ``` @@ -76,7 +76,7 @@ ### 4. Запуск последнего коммита Qwen Code из GitHub -Вы можете запустить самую свежую версию Qwen Code напрямую из репозитория на GitHub. Это удобно для тестирования функций, которые еще находятся в разработке. +Вы можете запустить самую свежую версию Qwen Code напрямую из репозитория на GitHub. Это удобно для тестирования функций, находящихся в разработке. ```bash @@ -84,35 +84,35 @@ npx https://github.com/QwenLM/qwen-code ``` -## Архитектура развертывания +## Архитектура деплоя Описанные выше методы выполнения становятся возможными благодаря следующим архитектурным компонентам и процессам: -**NPM-пакеты** +**NPM пакеты** Проект Qwen Code представляет собой монорепозиторий, который публикует основные пакеты в реестре NPM: - `@qwen-code/qwen-code-core`: Бэкенд, обрабатывающий логику и выполнение инструментов. -- `@qwen-code/qwen-code`: Фронтенд, взаимодействующий с пользователем. +- `@qwen-code/qwen-code`: Фронтенд для взаимодействия с пользователем. -Эти пакеты используются при выполнении стандартной установки и при запуске Qwen Code из исходного кода. +Эти пакеты используются при стандартной установке и при запуске Qwen Code из исходников. **Процессы сборки и упаковки** -Используются два различных процесса сборки в зависимости от канала распространения: +Используются два различных процесса сборки, в зависимости от канала распространения: -- **Публикация в NPM:** Для публикации в реестре NPM TypeScript-код из `@qwen-code/qwen-code-core` и `@qwen-code/qwen-code` транспилируется в стандартный JavaScript с помощью TypeScript Compiler (`tsc`). Полученный каталог `dist/` публикуется в NPM-пакете. Это стандартный подход для TypeScript-библиотек. +- **Публикация в NPM:** Для публикации в реестре NPM TypeScript код из `@qwen-code/qwen-code-core` и `@qwen-code/qwen-code` транспилируется в стандартный JavaScript с помощью TypeScript Compiler (`tsc`). Полученный каталог `dist/` и есть то, что попадает в NPM пакет. Это стандартный подход для библиотек на TypeScript. -- **Выполнение через `npx` из GitHub:** При запуске последней версии Qwen Code напрямую из GitHub запускается другой процесс, инициируемый скриптом `prepare` в `package.json`. Этот скрипт использует `esbuild` для сборки всего приложения и его зависимостей в один автономный JavaScript-файл. Эта сборка создается «на лету» на машине пользователя и не добавляется в репозиторий. +- **Выполнение через `npx` из GitHub:** При запуске последней версии Qwen Code напрямую из GitHub запускается другой процесс, инициируемый скриптом `prepare` в `package.json`. Этот скрипт использует `esbuild`, чтобы собрать всё приложение и его зависимости в один автономный JavaScript файл. Такой бандл создается «на лету» на машине пользователя и не добавляется в репозиторий. -**Docker-образ песочницы** +**Docker образ песочницы** -Метод выполнения на основе Docker поддерживается образом контейнера `qwen-code-sandbox`. Этот образ публикуется в реестре контейнеров и содержит предустановленную глобальную версию Qwen Code. +Метод выполнения на основе Docker поддерживается контейнерным образом `qwen-code-sandbox`. Этот образ публикуется в реестре контейнеров и содержит предустановленную глобальную версию Qwen Code. ## Процесс релиза Процесс релиза автоматизирован с помощью GitHub Actions. Workflow релиза выполняет следующие действия: 1. Собирает NPM пакеты с использованием `tsc`. -2. Публикует NPM пакеты в реестре артефактов. -3. Создает релизы GitHub с приложенными бандлами. \ No newline at end of file +2. Публикует NPM пакеты в artifact registry. +3. Создает релизы в GitHub с приложенными артефактами. \ No newline at end of file diff --git a/website/content/ru/examples/proxy-script.md b/website/content/ru/examples/proxy-script.md index 172ec134..9debc553 100644 --- a/website/content/ru/examples/proxy-script.md +++ b/website/content/ru/examples/proxy-script.md @@ -1,6 +1,6 @@ # Пример Proxy-скрипта -Ниже приведен пример proxy-скрипта, который можно использовать с переменной окружения `GEMINI_SANDBOX_PROXY_COMMAND`. Этот скрипт разрешает только `HTTPS`-подключения к `example.com:443` и отклоняет все остальные запросы. +Ниже приведен пример proxy-скрипта, который можно использовать с переменной окружения `GEMINI_SANDBOX_PROXY_COMMAND`. Этот скрипт разрешает только `HTTPS` соединения к `example.com:443` и отклоняет все остальные запросы. ```javascript #!/usr/bin/env node @@ -11,14 +11,14 @@ * SPDX-License-Identifier: Apache-2.0 */ -// Пример proxy-сервера, который слушает :::8877 и разрешает только HTTPS-подключения к example.com. +// Пример proxy-сервера, который слушает :::8877 и разрешает только HTTPS соединения к example.com. // Установите `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js`, чтобы запустить proxy вместе с sandbox // Проверьте через `curl https://example.com` внутри sandbox (в режиме shell или через shell tool) -import http from 'http'; -import net from 'net'; -import { URL } from 'url'; -import console from 'console'; +import http from 'node:http'; +import net from 'node:net'; +import { URL } from 'node:url'; +import console from 'node:console'; const PROXY_PORT = 8877; const ALLOWED_DOMAINS = ['example.com', 'googleapis.com']; @@ -34,10 +34,10 @@ const server = http.createServer((req, res) => { }); server.on('connect', (req, clientSocket, head) => { - // req.url будет в формате "hostname:port" для CONNECT-запроса. + // req.url будет в формате "hostname:port" для CONNECT запроса. const { port, hostname } = new URL(`http://${req.url}`); - console.log(`[PROXY] Перехват CONNECT-запроса для: ${hostname}:${port}`); + console.log(`[PROXY] Перехватываем CONNECT запрос: ${hostname}:${port}`); if ( ALLOWED_DOMAINS.some( @@ -45,9 +45,9 @@ server.on('connect', (req, clientSocket, head) => { ) && port === ALLOWED_PORT ) { - console.log(`[PROXY] Разрешаем подключение к ${hostname}:${port}`); + console.log(`[PROXY] Разрешаем соединение к ${hostname}:${port}`); - // Устанавливаем TCP-соединение с оригинальным адресатом. + // Устанавливаем TCP соединение с оригинальным адресатом. const serverSocket = net.connect(port, hostname, () => { clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n'); // Создаем туннель, перенаправляя данные между клиентом и сервером. @@ -57,11 +57,11 @@ server.on('connect', (req, clientSocket, head) => { }); serverSocket.on('error', (err) => { - console.error(`[PROXY] Ошибка подключения к адресату: ${err.message}`); + console.error(`[PROXY] Ошибка подключения к серверу: ${err.message}`); clientSocket.end(`HTTP/1.1 502 Bad Gateway\r\n\r\n`); }); } else { - console.log(`[PROXY] Запрещаем подключение к ${hostname}:${port}`); + console.log(`[PROXY] Запрещаем соединение к ${hostname}:${port}`); clientSocket.end('HTTP/1.1 403 Forbidden\r\n\r\n'); } @@ -75,7 +75,7 @@ server.listen(PROXY_PORT, () => { const address = server.address(); console.log(`[PROXY] Proxy слушает на ${address.address}:${address.port}`); console.log( - `[PROXY] Разрешены HTTPS-подключения к доменам: ${ALLOWED_DOMAINS.join(', ')}`, + `[PROXY] Разрешаем HTTPS соединения к доменам: ${ALLOWED_DOMAINS.join(', ')}`, ); }); ``` \ No newline at end of file diff --git a/website/content/ru/extension.md b/website/content/ru/extension.md index 29e7e4bf..89470348 100644 --- a/website/content/ru/extension.md +++ b/website/content/ru/extension.md @@ -11,7 +11,7 @@ Qwen Code поддерживает расширения, которые можн Qwen Code загружает все расширения из обоих мест. Если расширение с одинаковым именем существует в обоих местах, то расширение из директории workspace имеет приоритет. -В каждом из этих мест отдельные расширения представлены в виде директории, содержащей файл `qwen-extension.json`. Например: +В каждом месте отдельные расширения представлены как директория, содержащая файл `qwen-extension.json`. Например: `/.qwen/extensions/my-extension/qwen-extension.json` @@ -33,13 +33,13 @@ Qwen Code загружает все расширения из обоих мес } ``` -- `name`: Название расширения. Используется для уникальной идентификации расширения и разрешения конфликтов, когда команды расширения имеют те же имена, что и пользовательские или проектные команды. +- `name`: Имя расширения. Используется для уникальной идентификации расширения и разрешения конфликтов, когда команды из расширения имеют те же названия, что и пользовательские или проектные команды. - `version`: Версия расширения. -- `mcpServers`: Карта MCP-серверов для настройки. Ключ — это имя сервера, а значение — конфигурация сервера. Эти серверы будут загружены при запуске так же, как и MCP-серверы, настроенные в файле [`settings.json`](./cli/configuration.md). Если и расширение, и файл `settings.json` настраивают MCP-сервер с одинаковым именем, приоритет получает сервер, определенный в файле `settings.json`. -- `contextFileName`: Имя файла, содержащего контекст для расширения. Будет использоваться для загрузки контекста из рабочей области. Если это свойство не задано, но в директории расширения присутствует файл `QWEN.md`, то будет загружен именно этот файл. -- `excludeTools`: Массив имен инструментов, которые нужно исключить из модели. Также можно указать ограничения для конкретных команд инструментов, которые их поддерживают, например, для инструмента `run_shell_command`. Например, `"excludeTools": ["run_shell_command(rm -rf)"]` заблокирует команду `rm -rf`. +- `mcpServers`: Карта MCP-серверов для настройки. Ключ — это имя сервера, а значение — его конфигурация. Эти серверы будут загружены при запуске так же, как и MCP-серверы, указанные в файле [`settings.json`](./cli/configuration.md). Если и расширение, и файл `settings.json` определяют MCP-сервер с одинаковым именем, то приоритет получает сервер, описанный в `settings.json`. +- `contextFileName`: Имя файла, содержащего контекст расширения. Этот файл будет использоваться для загрузки контекста из рабочей области. Если данное свойство не задано, но в директории расширения присутствует файл `QWEN.md`, он будет загружен автоматически. +- `excludeTools`: Массив имён инструментов, которые нужно исключить из модели. Также можно указывать специфичные ограничения для конкретных команд внутри поддерживаемых инструментов, таких как `run_shell_command`. Например, `"excludeTools": ["run_shell_command(rm -rf)"]` заблокирует выполнение команды `rm -rf`. -Когда Qwen Code запускается, он загружает все расширения и объединяет их конфигурации. В случае конфликтов приоритет получает конфигурация рабочей области. +При запуске Qwen Code загружает все расширения и объединяет их конфигурации. В случае конфликтов приоритет получает конфигурация из рабочей области. ## Команды расширений @@ -73,4 +73,28 @@ Qwen Code загружает все расширения из обоих мес Например, если и пользователь, и расширение `gcp` определяют команду `deploy`: - `/deploy` - Выполняет пользовательскую команду deploy -- `/gcp.deploy` - Выполняет команду deploy расширения (помечена тегом `[gcp]`) \ No newline at end of file +- `/gcp.deploy` - Выполняет команду deploy расширения (помечена тегом `[gcp]`) + +## Установка расширений + +Вы можете устанавливать расширения с помощью команды `install`. Эта команда позволяет устанавливать расширения из Git репозитория или локального пути. + +### Использование + +`qwen extensions install | [options]` + +### Опции + +- `source позиционный аргумент`: URL Git-репозитория, из которого будет установлена расширение. Репозиторий должен содержать файл `qwen-extension.json` в корневой директории. +- `--path `: Путь к локальной директории, которая будет установлена как расширение. Директория должна содержать файл `qwen-extension.json`. + +# Переменные + +Расширения Qwen Code позволяют использовать подстановку переменных в файле `qwen-extension.json`. Это может быть полезно, например, если вам нужно указать текущую директорию для запуска MCP сервера, используя `"cwd": "${extensionPath}${/}run.ts"`. + +**Поддерживаемые переменные:** + +| переменная | описание | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `${extensionPath}` | Полный путь к расширению в файловой системе пользователя, например, '/Users/username/.qwen/extensions/example-extension'. Символические ссылки не разворачиваются. | +| `${/} или ${pathSeparator}` | Разделитель пути (отличается в зависимости от ОС). | \ No newline at end of file diff --git a/website/content/ru/gemini-ignore.md b/website/content/ru/gemini-ignore.md index 86b3f44e..4012a97a 100644 --- a/website/content/ru/gemini-ignore.md +++ b/website/content/ru/gemini-ignore.md @@ -11,10 +11,10 @@ Qwen Code поддерживает автоматическое игнориро В основном, `.geminiignore` следует тем же правилам, что и файлы `.gitignore`: - Пустые строки и строки, начинающиеся с `#`, игнорируются. -- Поддерживаются стандартные glob-паттерны (такие как `*`, `?` и `[]`). -- Если поставить `/` в конце, то правило будет применяться только к директориям. +- Поддерживаются стандартные шаблоны glob (например, `*`, `?` и `[]`). +- Если поставить `/` в конце, шаблон будет соответствовать только директориям. - Если поставить `/` в начале, путь будет привязан относительно файла `.geminiignore`. -- `!` отменяет действие паттерна. +- `!` отменяет шаблон. Вы можете обновлять файл `.geminiignore` в любое время. Чтобы изменения вступили в силу, необходимо перезапустить сессию Qwen Code. diff --git a/website/content/ru/ide-integration.md b/website/content/ru/ide-integration.md index 16ca9134..7007e625 100644 --- a/website/content/ru/ide-integration.md +++ b/website/content/ru/ide-integration.md @@ -1,23 +1,23 @@ # Интеграция с IDE -Qwen Code можно интегрировать с вашей IDE для более удобной и контекстно-зависимой работы. Такая интеграция позволяет CLI лучше понимать ваше рабочее пространство и включает мощные функции, такие как native in-editor diffing. +Qwen Code можно интегрировать с вашей IDE для более удобной и контекстно-зависимой работы. Такая интеграция позволяет CLI лучше понимать ваше рабочее пространство и включает мощные функции, такие как нативное сравнение изменений прямо в редакторе. На данный момент единственной поддерживаемой IDE является [Visual Studio Code](https://code.visualstudio.com/), а также другие редакторы, которые поддерживают расширения VS Code. ## Возможности -- **Контекст рабочей области:** CLI автоматически получает информацию о вашей рабочей области, чтобы предоставлять более релевантные и точные ответы. Этот контекст включает: - - **10 последних открытых файлов** в вашей рабочей области. +- **Контекст рабочей области:** CLI автоматически получает информацию о вашей рабочей области для предоставления более релевантных и точных ответов. Этот контекст включает: + - **10 самых последних файлов**, к которым вы обращались в своей рабочей области. - Активную позицию курсора. - Любой выделенный текст (до лимита 16 КБ; более длинные выделения будут обрезаны). -- **Встроенный diff:** Когда Qwen предлагает изменения в коде, вы можете просматривать эти изменения прямо во встроенном diff-редакторе вашей IDE. Это позволяет легко просматривать, редактировать и принимать или отклонять предложенные изменения. +- **Нативный diff:** Когда Qwen предлагает изменения кода, вы можете просматривать эти изменения прямо во встроенном diff-редакторе вашей IDE. Это позволяет вам легко просматривать, редактировать, а также принимать или отклонять предложенные изменения. - **Команды VS Code:** Вы можете получить доступ к функциям Qwen Code прямо из палитры команд VS Code (`Cmd+Shift+P` или `Ctrl+Shift+P`): - `Qwen Code: Run`: Запускает новую сессию Qwen Code во встроенном терминале. - `Qwen Code: Accept Diff`: Принимает изменения в активном diff-редакторе. - `Qwen Code: Close Diff Editor`: Отклоняет изменения и закрывает активный diff-редактор. - - `Qwen Code: View Third-Party Notices`: Отображает уведомления о сторонних библиотеках для расширения. + - `Qwen Code: View Third-Party Notices`: Отображает уведомления о сторонних библиотеках расширения. ## Установка и настройка @@ -25,7 +25,7 @@ Qwen Code можно интегрировать с вашей IDE для бол ### 1. Автоматический запрос (рекомендуется) -Когда вы запускаете Qwen Code внутри поддерживаемого редактора, он автоматически определит ваше окружение и предложит подключиться. Если вы ответите "Yes", необходимая настройка будет выполнена автоматически, включая установку соответствующего расширения и включение соединения. +Когда вы запускаете Qwen Code внутри поддерживаемого редактора, он автоматически определит вашу среду и предложит подключиться. Если вы ответите «Да», необходимая настройка будет выполнена автоматически, включая установку расширения-компаньона и включение соединения. ### 2. Ручная установка через CLI @@ -42,9 +42,12 @@ Qwen Code можно интегрировать с вашей IDE для бол Вы также можете установить расширение напрямую из маркетплейса. - **Для Visual Studio Code:** Установите из [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion). -- **Для форков VS Code:** Чтобы поддерживать форки VS Code, расширение также опубликовано в [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion). Следуйте инструкциям вашего редактора по установке расширений из этого реестра. +- **Для форков VS Code:** Чтобы поддерживать форки VS Code, расширение также опубликовано в [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion). Следуйте инструкциям вашего редактора для установки расширений из этого реестра. -После любого метода установки рекомендуется открыть новое окно терминала, чтобы убедиться, что интеграция активирована правильно. После установки вы можете использовать `/ide enable` для подключения. +> ПРИМЕЧАНИЕ: +> Расширение "Qwen Code Companion" может отображаться внизу результатов поиска. Если вы не видите его сразу, попробуйте прокрутить вниз или отсортировать по "Новым публикациям". +> +> После ручной установки расширения необходимо выполнить `/ide enable` в CLI, чтобы активировать интеграцию. ## Использование @@ -61,7 +64,7 @@ Qwen Code можно интегрировать с вашей IDE для бол /ide disable ``` -Когда подключение включено, Qwen Code автоматически попытается подключиться к расширению-компаньону в IDE. +При включении Qwen Code автоматически попытается подключиться к расширению-компаньону в IDE. ### Проверка статуса @@ -71,42 +74,42 @@ Qwen Code можно интегрировать с вашей IDE для бол /ide status ``` -Если подключение установлено, эта команда покажет, к какой IDE выполнено подключение, и список недавно открытых файлов, о которых известно. +Если подключение установлено, эта команда покажет, к какой IDE выполнено подключение, а также список недавно открытых файлов, о которых известно. (Примечание: Список файлов ограничен 10 последними открытыми файлами в вашем workspace и включает только локальные файлы на диске.) ### Работа с Diffs -Когда вы просите Gemini изменить файл, он может открыть представление diff прямо в вашем редакторе. +Когда вы просите модель Qwen изменить файл, она может открыть diff-представление прямо в вашем редакторе. **Чтобы принять diff**, вы можете выполнить любое из следующих действий: -- Нажать **иконку с галочкой** в заголовке редактора diff. +- Нажать **иконку с галочкой** в заголовке diff-редактора. - Сохранить файл (например, с помощью `Cmd+S` или `Ctrl+S`). - Открыть Command Palette и выполнить команду **Qwen Code: Accept Diff**. - Ответить `yes` в CLI при запросе. **Чтобы отклонить diff**, вы можете: -- Нажать **иконку 'x'** в заголовке редактора diff. -- Закрыть вкладку редактора diff. +- Нажать **иконку 'x'** в заголовке diff-редактора. +- Закрыть вкладку diff-редактора. - Открыть Command Palette и выполнить команду **Qwen Code: Close Diff Editor**. - Ответить `no` в CLI при запросе. -Вы также можете **изменить предложенные изменения** прямо в представлении diff перед их принятием. +Вы также можете **изменить предложенные изменения** прямо в diff-представлении перед их принятием. Если вы выберете ‘Yes, allow always’ в CLI, изменения больше не будут отображаться в IDE, так как они будут автоматически приниматься. -## Использование в песочнице +## Использование в песочнице (Sandboxing) -Если вы используете Qwen Code в песочнице, обратите внимание на следующее: +Если вы используете Qwen Code внутри песочницы, обратите внимание на следующие моменты: -- **На macOS:** Для интеграции с IDE требуется доступ к сети, чтобы взаимодействовать с расширением-компаньоном IDE. Вы должны использовать профиль Seatbelt, который разрешает доступ к сети. -- **В Docker-контейнере:** Если вы запускаете Qwen Code внутри Docker (или Podman) контейнера, интеграция с IDE всё ещё может подключиться к расширению VS Code, запущенному на вашей хост-машине. CLI настроен таким образом, чтобы автоматически находить IDE-сервер по адресу `host.docker.internal`. Обычно никакой дополнительной настройки не требуется, но вам может понадобиться убедиться, что ваша конфигурация Docker-сети разрешает подключения из контейнера к хосту. +- **На macOS:** Для интеграции с IDE требуется доступ к сети, чтобы взаимодействовать с расширением-компаньоном IDE. Вы должны использовать профиль Seatbelt, который разрешает сетевой доступ. +- **В Docker-контейнере:** Если вы запускаете Qwen Code внутри контейнера Docker (или Podman), интеграция с IDE всё ещё может подключиться к расширению VS Code, запущенному на вашем хосте. CLI настроен таким образом, чтобы автоматически находить IDE-сервер по адресу `host.docker.internal`. Обычно никакой дополнительной настройки не требуется, но вам может понадобиться убедиться, что ваша конфигурация сети Docker позволяет контейнеру устанавливать соединения с хостом. ## Устранение неполадок -Если у вас возникли проблемы с интеграцией IDE, ниже приведены некоторые распространённые сообщения об ошибках и способы их устранения. +Если у вас возникли проблемы с интеграцией в IDE, ниже приведены некоторые распространённые сообщения об ошибках и способы их устранения. ### Ошибки подключения @@ -114,7 +117,7 @@ Qwen Code можно интегрировать с вашей IDE для бол - **Причина:** Qwen Code не смог найти необходимые переменные окружения (`QWEN_CODE_IDE_WORKSPACE_PATH` или `QWEN_CODE_IDE_SERVER_PORT`) для подключения к IDE. Обычно это означает, что расширение-компаньон IDE не запущено или не инициализировалось корректно. - **Решение:** 1. Убедитесь, что вы установили расширение **Qwen Code Companion** в вашей IDE и что оно включено. - 2. Откройте новое окно терминала в вашей IDE, чтобы убедиться, что оно получает правильное окружение. + 2. Откройте новое окно терминала в вашей IDE, чтобы убедиться, что оно получило правильное окружение. - **Сообщение:** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` - **Причина:** Подключение к расширению-компаньону IDE было потеряно. @@ -126,9 +129,9 @@ Qwen Code можно интегрировать с вашей IDE для бол - **Причина:** Текущая рабочая директория CLI находится вне папки или workspace, открытого в вашем IDE. - **Решение:** Перейдите с помощью `cd` в ту же директорию, которая открыта в вашем IDE, и перезапустите CLI. -- **Сообщение:** `🔴 Disconnected: To use this feature, please open a single workspace folder in [IDE Name] and try again.` - - **Причина:** В вашем IDE открыто несколько папок workspace или ни одна папка не открыта. Для корректной работы интеграции с IDE требуется одна корневая папка workspace. - - **Решение:** Откройте одну папку проекта в вашем IDE и перезапустите CLI. +- **Сообщение:** `🔴 Disconnected: To use this feature, please open a workspace folder in [IDE Name] and try again.` + - **Причина:** В вашем IDE не открыт ни один workspace. + - **Решение:** Откройте workspace в вашем IDE и перезапустите CLI. ### Общие ошибки @@ -136,6 +139,6 @@ Qwen Code можно интегрировать с вашей IDE для бол - **Причина:** Вы запускаете Qwen Code в терминале или среде, которая не является поддерживаемой IDE. - **Решение:** Запустите Qwen Code из встроенного терминала поддерживаемой IDE, например VS Code. -- **Сообщение:** `No installer is available for [IDE Name]. Please install the IDE companion manually from its marketplace.` +- **Сообщение:** `No installer is available for IDE. Please install the Qwen Code Companion extension manually from the marketplace.` - **Причина:** Вы выполнили команду `/ide install`, но CLI не имеет автоматического установщика для вашей конкретной IDE. - **Решение:** Откройте маркетплейс расширений вашей IDE, найдите "Qwen Code Companion" и установите его вручную. \ No newline at end of file diff --git a/website/content/ru/index.md b/website/content/ru/index.md index 5751cf14..9837fa77 100644 --- a/website/content/ru/index.md +++ b/website/content/ru/index.md @@ -1,10 +1,10 @@ # Добро пожаловать в документацию Qwen Code -Эта документация представляет собой подробное руководство по установке, использованию и разработке Qwen Code. Этот инструмент позволяет взаимодействовать с AI моделями через command-line interface. +Эта документация представляет собой подробное руководство по установке, использованию и разработке Qwen Code. Этот инструмент позволяет взаимодействовать с AI моделями через интерфейс командной строки. ## Обзор -Qwen Code предоставляет возможности продвинутых кодовых моделей прямо в вашем терминале в интерактивной среде Read-Eval-Print Loop (REPL). Qwen Code состоит из клиентского приложения (`packages/cli`), которое взаимодействует с локальным сервером (`packages/core`). Qwen Code также содержит различные инструменты для выполнения таких задач, как операции с файловой системой, запуск shells и web fetching, которыми управляет `packages/core`. +Qwen Code предоставляет возможности продвинутых кодовых моделей прямо в вашем терминале в интерактивной среде Read-Eval-Print Loop (REPL). Qwen Code состоит из клиентского приложения (`packages/cli`), которое взаимодействует с локальным сервером (`packages/core`). Qwen Code также содержит различные инструменты для выполнения таких задач, как операции с файловой системой, запуск shell'ов и веб-запросы, которыми управляет `packages/core`. ## Навигация по документации @@ -31,9 +31,9 @@ Qwen Code предоставляет возможности продвинуты - **[Инструмент веб-запросов](./tools/web-fetch.md):** Документация по инструменту `web_fetch`. - **[Инструмент веб-поиска](./tools/web-search.md):** Документация по инструменту `web_search`. - **[Инструмент памяти](./tools/memory.md):** Документация по инструменту `save_memory`. -- **[Субагенты](./subagents.md):** Специализированные AI-ассистенты для выполнения конкретных задач с подробным руководством по управлению, конфигурации и использованию. +- **[Подагенты](./subagents.md):** Специализированные AI-ассистенты для выполнения конкретных задач с подробным руководством по управлению, конфигурации и использованию. - **[Руководство по участию и разработке](../CONTRIBUTING.md):** Информация для контрибьюторов и разработчиков, включая установку, сборку, тестирование и соглашения по кодированию. -- **[NPM Workspaces и публикация](./npm.md):** Подробности о том, как управляются и публикуются пакеты проекта. +- **[NPM](./npm.md):** Подробности о структуре пакетов проекта. - **[Руководство по устранению неполадок](./troubleshooting.md):** Найдите решения распространенных проблем и часто задаваемых вопросов. - **[Условия использования и политика конфиденциальности](./tos-privacy.md):** Информация об условиях использования и уведомлениях о конфиденциальности, применимых к вашему использованию Qwen Code. diff --git a/website/content/ru/keyboard-shortcuts.md b/website/content/ru/keyboard-shortcuts.md index e67f1ff7..0b546c0b 100644 --- a/website/content/ru/keyboard-shortcuts.md +++ b/website/content/ru/keyboard-shortcuts.md @@ -4,54 +4,55 @@ ## Общие -| Shortcut | Description | -| -------- | --------------------------------------------------------------------------------------------------------------------- | -| `Esc` | Закрыть диалоги и предложения. | -| `Ctrl+C` | Отменить текущий запрос и очистить ввод. Нажмите дважды, чтобы выйти из приложения. | -| `Ctrl+D` | Выйти из приложения, если поле ввода пустое. Нажмите дважды для подтверждения. | -| `Ctrl+L` | Очистить экран. | -| `Ctrl+O` | Переключить отображение консоли отладки. | -| `Ctrl+S` | Позволяет полностью отображать длинные ответы, отключая обрезку. Используйте прокрутку терминала для просмотра всего вывода. | -| `Ctrl+T` | Переключить отображение описаний инструментов. | -| `Ctrl+Y` | Переключить автоматическое подтверждение (режим YOLO) для всех вызовов инструментов. | +| Shortcut | Description | +| ----------- | --------------------------------------------------------------------------------------------------------------------- | +| `Esc` | Закрыть диалоги и предложения. | +| `Ctrl+C` | Отменить текущий запрос и очистить ввод. Нажмите дважды, чтобы выйти из приложения. | +| `Ctrl+D` | Выйти из приложения, если поле ввода пустое. Нажмите дважды для подтверждения. | +| `Ctrl+L` | Очистить экран. | +| `Ctrl+O` | Переключить отображение консоли отладки. | +| `Ctrl+S` | Позволяет полностью выводить длинные ответы, отключая обрезку. Используйте прокрутку терминала для просмотра всего вывода. | +| `Ctrl+T` | Переключить отображение описаний инструментов. | +| `Shift+Tab` | Переключение между режимами подтверждения (`plan` → `default` → `auto-edit` → `yolo`). | -## Input Prompt +## Ввод команд -| Shortcut | Description | +| Комбинация клавиш | Описание | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `!` | Переключить shell mode, если поле ввода пустое. | +| `!` | Переключение в режим shell, если поле ввода пустое. | | `\` (в конце строки) + `Enter` | Вставить символ новой строки. | | `Стрелка вниз` | Перемещение вниз по истории ввода. | -| `Enter` | Отправить текущий prompt. | +| `Enter` | Отправить текущую команду. | | `Meta+Delete` / `Ctrl+Delete` | Удалить слово справа от курсора. | | `Tab` | Автодополнение текущего предложения, если оно существует. | | `Стрелка вверх` | Перемещение вверх по истории ввода. | | `Ctrl+A` / `Home` | Переместить курсор в начало строки. | | `Ctrl+B` / `Стрелка влево` | Переместить курсор на один символ влево. | -| `Ctrl+C` | Очистить prompt. | +| `Ctrl+C` | Очистить строку ввода. | +| `Esc` (двойное нажатие) | Очистить строку ввода. | | `Ctrl+D` / `Delete` | Удалить символ справа от курсора. | | `Ctrl+E` / `End` | Переместить курсор в конец строки. | | `Ctrl+F` / `Стрелка вправо` | Переместить курсор на один символ вправо. | | `Ctrl+H` / `Backspace` | Удалить символ слева от курсора. | | `Ctrl+K` | Удалить всё от курсора до конца строки. | -| `Ctrl+Стрелка влево` / `Meta+Стрелка влево` / `Meta+B` | Переместить курсор на одно слово влево. | +| `Ctrl+Стрелка влево` / `Meta+Стрелка влево` / `Meta+B` | Переместить курсор на одно слово влево. | | `Ctrl+N` | Перемещение вниз по истории ввода. | | `Ctrl+P` | Перемещение вверх по истории ввода. | -| `Ctrl+Стрелка вправо` / `Meta+Стрелка вправо` / `Meta+F` | Переместить курсор на одно слово вправо. | +| `Ctrl+Стрелка вправо` / `Meta+Стрелка вправо` / `Meta+F` | Переместить курсор на одно слово вправо. | | `Ctrl+U` | Удалить всё от курсора до начала строки. | -| `Ctrl+V` | Вставить содержимое буфера обмена. Если в буфере изображение, оно будет сохранено, а в prompt будет вставлена ссылка на него. | +| `Ctrl+V` | Вставить содержимое буфера обмена. Если в буфере изображение, оно будет сохранено, а в команду будет вставлена ссылка на него. | | `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace` | Удалить слово слева от курсора. | | `Ctrl+X` / `Meta+Enter` | Открыть текущий ввод во внешнем редакторе. | ## Подсказки -| Shortcut | Description | -| --------------- | -------------------------------------- | +| Shortcut | Description | +| --------------- | ------------------------------------- | | `Down Arrow` | Перемещение вниз по списку подсказок. | -| `Tab` / `Enter` | Принять выбранную подсказку. | -| `Up Arrow` | Перемещение вверх по списку подсказок. | +| `Tab` / `Enter` | Принять выбранную подсказку. | +| `Up Arrow` | Перемещение вверх по списку подсказок.| -## Выбор с помощью Radio Button +## Выбор с помощью радио-кнопок | Shortcut | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------- | @@ -59,10 +60,10 @@ | `Enter` | Подтвердить выбор. | | `Up Arrow` / `k` | Переместить выбор вверх. | | `1-9` | Выбрать элемент по его номеру. | -| (multi-digit) | Для элементов с номерами больше 9, быстро нажмите цифры, чтобы выбрать соответствующий элемент. | +| (multi-digit) | Для элементов с номерами больше 9, нажмите цифры быстро друг за другом, чтобы выбрать соответствующий элемент. | ## Интеграция с IDE | Shortcut | Description | | -------- | --------------------------------- | -| `Ctrl+G` | See context CLI received from IDE | \ No newline at end of file +| `Ctrl+G` | Просмотр контекста CLI, полученного от IDE | \ No newline at end of file diff --git a/website/content/ru/qwen-ignore.md b/website/content/ru/qwen-ignore.md new file mode 100644 index 00000000..0108bed8 --- /dev/null +++ b/website/content/ru/qwen-ignore.md @@ -0,0 +1,62 @@ +# Игнорирование файлов + +Этот документ содержит обзор функции Qwen Ignore (`.qwenignore`) в Qwen Code. + +Qwen Code поддерживает автоматическое игнорирование файлов, аналогично `.gitignore` (используется Git). Добавление путей в ваш файл `.qwenignore` исключит их из инструментов, которые поддерживают эту функцию, хотя они по-прежнему будут видны другим сервисам (например, Git). + +## Как это работает + +Когда вы добавляете путь в файл `.qwenignore`, инструменты, которые учитывают этот файл, будут исключать соответствующие файлы и директории из своих операций. Например, когда вы используете команду [`read_many_files`](./tools/multi-file.md), все пути, указанные в вашем файле `.qwenignore`, будут автоматически исключены. + +В основном, `.qwenignore` следует тем же правилам, что и файлы `.gitignore`: + +- Пустые строки и строки, начинающиеся с `#`, игнорируются. +- Поддерживаются стандартные шаблоны glob (например, `*`, `?` и `[]`). +- Если поставить `/` в конце, то правило будет применяться только к директориям. +- Если поставить `/` в начале, путь становится привязанным относительно расположения файла `.qwenignore`. +- `!` отменяет действие шаблона. + +Вы можете обновлять файл `.qwenignore` в любое время. Чтобы изменения вступили в силу, необходимо перезапустить вашу сессию Qwen Code. + +## Как использовать `.qwenignore` + +Чтобы включить `.qwenignore`: + +1. Создайте файл с именем `.qwenignore` в корневой директории вашего проекта. + +Чтобы добавить файл или директорию в `.qwenignore`: + +1. Откройте ваш файл `.qwenignore`. +2. Добавьте путь или файл, который вы хотите игнорировать, например: `/archive/` или `apikeys.txt`. + +### Примеры `.qwenignore` + +Вы можете использовать `.qwenignore` для игнорирования директорий и файлов: + +``` + +# Исключить вашу директорию /packages/ и все поддиректории +/packages/ + +# Исключить ваш файл apikeys.txt +apikeys.txt +``` + +Вы можете использовать шаблоны в вашем файле `.qwenignore` с помощью `*`: + +``` + +# Исключить все файлы .md +*.md +``` + +Наконец, вы можете исключить файлы и директории из исключения с помощью `!`: + +``` + +# Исключить все файлы .md, кроме README.md +*.md +!README.md +``` + +Чтобы удалить пути из вашего файла `.qwenignore`, удалите соответствующие строки. \ No newline at end of file diff --git a/website/content/ru/subagents.md b/website/content/ru/subagents.md index 0af48e31..c6be0b50 100644 --- a/website/content/ru/subagents.md +++ b/website/content/ru/subagents.md @@ -1,31 +1,31 @@ -# Субагенты +# Subagents -Субагенты — это специализированные AI-ассистенты, которые обрабатывают определенные типы задач внутри Qwen Code. Они позволяют делегировать узкоспециализированную работу AI-агентам, настроенным под конкретные задачи с помощью специфических промптов, инструментов и поведений. +Subagents — это специализированные AI-ассистенты, которые обрабатывают определенные типы задач внутри Qwen Code. Они позволяют делегировать конкретную работу AI-агентам, настроенным под специфические задачи с помощью промптов, инструментов и поведенческих моделей. -## Что такое субагенты? +## Что такое Subagents? -Субагенты — это независимые AI-ассистенты, которые: +Subagents — это независимые AI-ассистенты, которые: -- **Специализируются на конкретных задачах** — Каждый субагент настраивается с помощью специфического системного промпта для определенного типа работы -- **Имеют отдельный контекст** — Они ведут свою собственную историю разговора, независимо от основного чата -- **Используют контролируемые инструменты** — Вы можете настроить, какие инструменты доступны каждому субагенту -- **Работают автономно** — После получения задачи они выполняют её независимо до завершения или ошибки +- **Специализируются на конкретных задачах** — Каждый subagent настроен с помощью специализированного system prompt для определенного типа работы +- **Имеют отдельный контекст** — Они ведут свою историю разговора, независимую от основного чата +- **Используют контролируемые инструменты** — Вы можете настроить, какие инструменты доступны каждому subagent +- **Работают автономно** — После получения задачи они выполняют её независимо до завершения или сбоя - **Предоставляют подробную обратную связь** — Вы можете отслеживать их прогресс, использование инструментов и статистику выполнения в реальном времени ## Основные преимущества - **Специализация задач**: Создавайте агентов, оптимизированных под конкретные рабочие процессы (тестирование, документация, рефакторинг и т.д.) -- **Изоляция контекста**: Разделяйте специализированную работу от основного разговора +- **Изоляция контекста**: Разделяйте специализированную работу от вашего основного разговора - **Повторное использование**: Сохраняйте и повторно используйте конфигурации агентов в разных проектах и сессиях -- **Контролируемый доступ**: Ограничивайте инструменты, которые может использовать каждый агент, для обеспечения безопасности и концентрации -- **Видимость прогресса**: Отслеживайте выполнение агентов с помощью обновлений в реальном времени +- **Контролируемый доступ**: Ограничивайте набор инструментов для каждого агента в целях безопасности и концентрации +- **Видимость прогресса**: Отслеживайте выполнение задач агентами в реальном времени ## Как работают Subagents -1. **Конфигурация**: Вы создаете конфигурации subagent, которые определяют их поведение, инструменты и системные подсказки +1. **Конфигурация**: Вы создаете конфигурации subagent, определяющие их поведение, инструменты и системные подсказки 2. **Делегирование**: Основной AI может автоматически делегировать задачи подходящим subagent 3. **Выполнение**: Subagents работают независимо, используя свои настроенные инструменты для выполнения задач -4. **Результаты**: Они возвращают результаты и сводки выполнения обратно в основной разговор +4. **Результаты**: Они возвращают результаты и сводку выполнения обратно в основной разговор ## Начало работы @@ -45,7 +45,7 @@ /agents manage ``` - Просматривайте и управляйте настроенными субагентами. + Просмотр и управление настроенными субагентами. 3. **Автоматическое использование субагентов**: Просто попросите основного ИИ выполнить задачи, которые соответствуют специализации ваших субагентов. ИИ автоматически делегирует подходящую работу. @@ -53,9 +53,9 @@ ### Пример использования ``` -Пользователь: "Пожалуйста, напиши комплексные тесты для модуля аутентификации" +Пользователь: "Пожалуйста, напишите комплексные тесты для модуля аутентификации" -ИИ: Я делегирую это вашему специалисту по тестированию. +ИИ: Я передам это вашему специалисту по тестированию. [Делегирует субагенту "testing-expert"] [Показывает прогресс создания тестов в реальном времени] [Возвращает готовые файлы тестов и сводку по выполнению] @@ -65,11 +65,11 @@ ### Команды CLI -Субагенты управляются через слэш-команду `/agents` и её подкоманды: +Субагентами можно управлять через слэш-команду `/agents` и её подкоманды: #### `/agents create` -Создаёт нового субагента через пошаговый мастер. +Создаёт нового субагента через интерактивный пошаговый мастер. **Использование:** @@ -129,13 +129,35 @@ description: Создает документацию проекта и файл Рабочая директория: ${current_directory} Сгенерировано: ${timestamp} -Сосредоточьтесь на создании понятной и полной документации, которая поможет -новым контрибьюторам и конечным пользователям разобраться в проекте. +Сосредоточьтесь на создании понятной и подробной документации, которая поможет +новым участникам и конечным пользователям разобраться в проекте. +``` + +## Эффективное использование субагентов + +### Автоматическая делегация + +Qwen Code активно делегирует задачи на основе: + +- Описания задачи в вашем запросе +- Поля `description` в конфигурации субагентов +- Текущего контекста и доступных инструментов + +Чтобы стимулировать более активное использование субагентов, добавляйте фразы вроде `"use PROACTIVELY"` или `"MUST BE USED"` в поле `description`. + +### Явный вызов + +Запросите конкретного субагента, упомянув его в вашей команде: + +``` +> Попросить субагента testing-expert создать unit тесты для модуля оплаты +> Попросить субагента documentation-writer обновить справочник API +> Попросить субагента react-specialist оптимизировать производительность этого компонента ``` ## Примеры -### Агенты рабочего процесса разработки +### Агенты для рабочего процесса разработки #### Testing Specialist @@ -144,7 +166,7 @@ description: Создает документацию проекта и файл ```markdown --- name: testing-expert -description: Пишет комплексные unit-тесты, интеграционные тесты и занимается автоматизацией тестирования согласно best practices +description: Пишет комплексные unit-тесты, интеграционные тесты и занимается автоматизацией тестирования с соблюдением best practices tools: read_file, write_file, read_many_files, run_shell_command --- @@ -152,30 +174,30 @@ tools: read_file, write_file, read_many_files, run_shell_command Ваша экспертиза включает: -- Модульное тестирование (unit testing) с использованием моков и изоляции +- Модульное тестирование (unit testing) с использованием mocking и изоляции - Интеграционное тестирование для проверки взаимодействия компонентов -- Разработку через тестирование (test-driven development) -- Выявление граничных случаев и обеспечение полного покрытия +- Практики разработки через тестирование (TDD) +- Выявление пограничных случаев и обеспечение полного покрытия - Тестирование производительности и нагрузочное тестирование (при необходимости) Для каждой задачи по тестированию: 1. Анализируйте структуру кода и зависимости -2. Определяйте ключевую функциональность, граничные случаи и условия ошибок +2. Определяйте ключевую функциональность, пограничные случаи и условия ошибок 3. Создавайте комплексные наборы тестов с понятными именами -4. Включайте корректную настройку/очистку и содержательные проверки (assertions) +4. Включайте корректную настройку/очистку и содержательные assertions 5. Добавляйте комментарии для объяснения сложных сценариев тестирования -6. Убедитесь, что тесты легко поддерживаются и следуют принципу DRY +6. Убедитесь, что тесты поддерживаемы и следуют принципам DRY Всегда следуйте лучшим практикам тестирования для обнаруженного языка и фреймворка. -Уделяйте внимание как позитивным, так и негативным тест-кейсам. +Сосредоточьтесь как на позитивных, так и на негативных тест-кейсах. ``` **Примеры использования:** - "Напиши unit-тесты для сервиса аутентификации" - "Создай интеграционные тесты для workflow обработки платежей" -- "Добавь покрытие тестами для граничных случаев в модуле валидации данных" +- "Добавь покрытие тестами для пограничных случаев в модуле валидации данных" #### Documentation Writer @@ -184,20 +206,20 @@ tools: read_file, write_file, read_many_files, run_shell_command ```markdown --- name: documentation-writer -description: Создает подробную документацию, README-файлы, API-документацию и руководства пользователя +description: Создает подробную документацию, файлы README, API-документацию и руководства пользователя tools: read_file, write_file, read_many_files, web_search --- Вы — специалист по технической документации для проекта ${project_name}. Ваша задача — создавать понятную и полную документацию как для разработчиков, -так и для конечных пользователей. Сфокусируйтесь на следующих аспектах: +так и для конечных пользователей. Сосредоточьтесь на следующем: **Для API-документации:** - Четкие описания endpoint'ов с примерами -- Подробная информация о параметрах, их типах и ограничениях -- Описание форматов ответов +- Подробности по параметрам, включая типы и ограничения +- Документирование формата ответа - Объяснение кодов ошибок - Требования к аутентификации @@ -205,15 +227,15 @@ tools: read_file, write_file, read_many_files, web_search - Пошаговые инструкции с скриншотами, где это уместно - Руководства по установке и настройке -- Описание параметров конфигурации и примеры +- Описание опций конфигурации и примеры - Разделы по устранению неполадок для частых проблем - FAQ на основе типичных вопросов пользователей **Для документации разработчика:** -- Обзор архитектуры и ключевых архитектурных решений -- Работающие примеры кода -- Руководство по внесению вклада в проект (contributing guidelines) +- Обзор архитектуры и принятых решений +- Рабочие примеры кода +- Руководство по внесению вклада (contributing guidelines) - Настройка среды разработки Всегда проверяйте примеры кода и следите за тем, чтобы документация соответствовала @@ -224,11 +246,11 @@ tools: read_file, write_file, read_many_files, web_search - "Создай API-документацию для endpoint'ов управления пользователями" - "Напиши подробный README для этого проекта" -- "Задокументируй процесс деплоя с разделом по устранению неполадок" +- "Задокументируй процесс деплоя с шагами по устранению неполадок" #### Code Reviewer -Сосредоточен на качестве кода, безопасности и лучших практиках. +Сфокусирован на качестве кода, безопасности и лучших практиках. ```markdown --- @@ -237,40 +259,40 @@ description: Проверяет код на соответствие лучши tools: read_file, read_many_files --- -Вы опытный code reviewer, фокусирующийся на качестве, безопасности и поддержке кода. +Вы опытный ревьюер кода, сфокусированный на качестве, безопасности и поддержке. Критерии ревью: - **Структура кода**: Организация, модульность и разделение ответственности - **Производительность**: Алгоритмическая эффективность и использование ресурсов -- **Безопасность**: Оценка уязвимостей и безопасные практики кодирования +- **Безопасность**: Оценка уязвимостей и безопасные практики программирования - **Лучшие практики**: Специфичные для языка/фреймворка конвенции - **Обработка ошибок**: Корректная обработка исключений и покрытие граничных случаев - **Читаемость**: Понятные названия, комментарии и организация кода - **Тестирование**: Покрытие тестами и возможность тестирования -Давайте конструктивный фидбек: +Предоставляйте конструктивную обратную связь с: 1. **Критические проблемы**: Уязвимости безопасности, серьезные баги -2. **Важные улучшения**: Проблемы с производительностью, архитектурные проблемы -3. **Мелкие предложения**: Улучшения стиля, возможности для рефакторинга -4. **Позитивный фидбек**: Хорошо реализованные паттерны и хорошие практики +2. **Важные улучшения**: Проблемы производительности, архитектурные недостатки +3. **Мелкие предложения**: Улучшения стиля, возможности рефакторинга +4. **Позитивная обратная связь**: Хорошо реализованные паттерны и хорошие практики -Фокусируйтесь на действенных рекомендациях с конкретными примерами и предложенными решениями. -Расставляйте приоритеты по степени влияния и объясняйте логику рекомендаций. +Фокусируйтесь на обратной связи, которую можно применить на практике, с конкретными примерами и предложенными решениями. +Расставляйте приоритеты по степени влияния и объясняйте причины рекомендаций. ``` **Примеры использования:** - "Проверь реализацию аутентификации на наличие проблем безопасности" -- "Оцени влияние этой логики запросов к БД на производительность" +- "Оцени влияние этой логики запросов к базе данных на производительность" - "Проанализируй структуру кода и предложи улучшения" -### Технологически-специфичные агенты +### Агенты для конкретных технологий #### React Specialist -Оптимизирован для разработки на React, использования hooks и паттернов компонентов. +Оптимизирован для разработки на React, hooks и паттернов компонентов. ```markdown --- @@ -293,7 +315,7 @@ tools: read_file, write_file, read_many_files, run_shell_command Для задач по React: 1. По умолчанию используйте функциональные компоненты и hooks -2. Реализуйте правильную типизацию с помощью TypeScript +2. Реализуйте правильную типизацию через TypeScript 3. Следуйте best practices и конвенциям React 4. Учитывайте влияние на производительность 5. Добавляйте корректную обработку ошибок @@ -316,30 +338,30 @@ tools: read_file, write_file, read_many_files, run_shell_command ```markdown --- name: python-expert -description: Эксперт в разработке на Python, фреймворках, тестировании и Python-специфичных лучших практиках +description: Эксперт в разработке на Python, фреймворках, тестировании и лучших практиках, специфичных для Python tools: read_file, write_file, read_many_files, run_shell_command --- -Вы — эксперт в Python с глубоким знанием экосистемы языка. +Вы — эксперт по Python с глубоким знанием экосистемы Python. Ваша экспертиза включает: - **Core Python**: Pythonic паттерны, структуры данных, алгоритмы - **Фреймворки**: Django, Flask, FastAPI, SQLAlchemy -- **Тестирование**: pytest, unittest, mocking, test-driven development -- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks +- **Тестирование**: pytest, unittest, мокинг, разработка через тестирование (TDD) +- **Data Science**: pandas, numpy, matplotlib, Jupyter Notebooks - **Асинхронное программирование**: asyncio, async/await паттерны -- **Управление пакетами**: pip, poetry, virtual environments -- **Качество кода**: PEP 8, type hints, линтинг с помощью pylint/flake8 +- **Управление пакетами**: pip, poetry, виртуальные окружения +- **Качество кода**: PEP 8, аннотации типов, линтинг с помощью pylint/flake8 Для задач на Python: -1. Следуйте стилю PEP 8 -2. Используйте type hints для лучшей документации кода +1. Следуйте рекомендациям стиля PEP 8 +2. Используйте аннотации типов для лучшей документации кода 3. Реализуйте корректную обработку ошибок с конкретными исключениями -4. Пишите полные docstrings +4. Пишите полные docstring'и 5. Учитывайте производительность и использование памяти -6. Добавляйте логирование там, где это уместно +6. Добавляйте соответствующее логирование 7. Пишите тестируемый, модульный код Сосредоточьтесь на написании чистого, поддерживаемого кода на Python, соответствующего стандартам сообщества. @@ -347,9 +369,9 @@ tools: read_file, write_file, read_many_files, run_shell_command **Примеры использования:** -- "Создай FastAPI сервис для аутентификации пользователей с JWT токенами" -- "Реализуй пайплайн обработки данных с pandas и обработкой ошибок" -- "Напиши CLI-тулзу с помощью argparse с полной документацией помощи" +- "Создай FastAPI сервис для аутентификации пользователей с использованием JWT токенов" +- "Реализуй пайплайн обработки данных с помощью pandas и обработкой ошибок" +- "Напиши CLI инструмент с использованием argparse и подробной справкой" ## Рекомендации @@ -410,16 +432,16 @@ description: Works on frontend development tasks **✅ Хорошо:** ```markdown -description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns +description: Проверяет код на наличие уязвимостей безопасности, проблем с производительностью и вопросов поддержки ``` **❌ Избегайте:** ```markdown -description: A helpful code reviewer +description: Полезный ревьюер кода ``` -**Почему:** Четкие описания помогают основному AI выбрать правильного агента для каждой задачи. +**Почему:** Четкие описания помогают основному ИИ выбрать правильного агента для каждой задачи. ### Рекомендации по конфигурации @@ -428,42 +450,42 @@ description: A helpful code reviewer **Уточняйте уровень экспертизы:** ```markdown -You are a Python testing specialist with expertise in: +Вы — специалист по тестированию на Python со знаниями в следующих областях: -- pytest framework and fixtures -- Mock objects and dependency injection -- Test-driven development practices -- Performance testing with pytest-benchmark +- Фреймворк pytest и фикстуры +- Mock-объекты и внедрение зависимостей +- Практики разработки через тестирование (TDD) +- Тестирование производительности с помощью pytest-benchmark ``` **Добавляйте пошаговые подходы:** ```markdown -For each testing task: +Для каждой задачи по тестированию: -1. Analyze the code structure and dependencies -2. Identify key functionality and edge cases -3. Create comprehensive test suites with clear naming -4. Include setup/teardown and proper assertions -5. Add comments explaining complex test scenarios +1. Анализируйте структуру кода и зависимости +2. Определяйте ключевую функциональность и граничные случаи +3. Создавайте комплексные наборы тестов с понятными названиями +4. Включайте setup/teardown и корректные проверки (assertions) +5. Добавляйте комментарии для объяснения сложных сценариев тестирования ``` -**Уточняйте стандарты вывода:** +**Описывайте стандарты вывода:** ```markdown -Always follow these standards: +Всегда следуйте этим стандартам: -- Use descriptive test names that explain the scenario -- Include both positive and negative test cases -- Add docstrings for complex test functions -- Ensure tests are independent and can run in any order +- Используйте описательные названия тестов, отражающие сценарий +- Включайте как позитивные, так и негативные тест-кейсы +- Добавляйте docstrings для сложных тестовых функций +- Убедитесь, что тесты независимы и могут выполняться в любом порядке ``` ## Вопросы безопасности -- **Ограничения инструментов**: Субагенты имеют доступ только к настроенным инструментам -- **Песочница**: Все выполнение инструментов следует той же модели безопасности, что и при прямом использовании инструментов -- **Аудит**: Все действия субагентов логируются и видны в реальном времени +- **Ограничения инструментов**: Subagents имеют доступ только к настроенным инструментам +- **Песочница**: Все выполнение инструментов следует той же модели безопасности, что и прямое использование инструментов +- **Аудит**: Все действия subagent'ов логируются и видны в реальном времени - **Контроль доступа**: Разделение на уровне проектов и пользователей обеспечивает соответствующие границы - **Конфиденциальная информация**: Избегайте включения секретов или учетных данных в конфигурации агентов -- **Продуктовые среды**: Рассмотрите возможность использования отдельных агентов для продуктовых и девелоперских сред \ No newline at end of file +- **Продуктовые среды**: Рассмотрите возможность использования отдельных агентов для продуктовой и девелоперской сред \ No newline at end of file diff --git a/website/content/ru/telemetry.md b/website/content/ru/telemetry.md index ee30f501..a25e0974 100644 --- a/website/content/ru/telemetry.md +++ b/website/content/ru/telemetry.md @@ -8,34 +8,34 @@ ## Включение телеметрии -Телеметрию можно включить несколькими способами. Основная настройка осуществляется через файл [`.qwen/settings.json`](./cli/configuration.md) и переменные окружения, но флаги CLI могут переопределять эти настройки для конкретной сессии. +Вы можете включить телеметрию несколькими способами. Основная настройка осуществляется через файл [`.qwen/settings.json`](./cli/configuration.md) и переменные окружения, но флаги CLI могут переопределять эти настройки для конкретной сессии. ### Порядок приоритета -Ниже перечислен порядок приоритета применения настроек телеметрии, где элементы, указанные выше, имеют больший приоритет: +Ниже приведен список приоритетов применения настроек телеметрии, где элементы, указанные выше, имеют больший приоритет: -1. **Флаги CLI (для команды `qwen`):** - - `--telemetry` / `--no-telemetry`: Переопределяет `telemetry.enabled`. - - `--telemetry-target `: Переопределяет `telemetry.target`. - - `--telemetry-otlp-endpoint `: Переопределяет `telemetry.otlpEndpoint`. - - `--telemetry-log-prompts` / `--no-telemetry-log-prompts`: Переопределяет `telemetry.logPrompts`. - - `--telemetry-outfile `: Перенаправляет вывод телеметрии в файл. См. [Экспорт в файл](#exporting-to-a-file). +1. **Флаги CLI (для команды `qwen`)**: + - `--telemetry` / `--no-telemetry`: Переопределяет `telemetry.enabled`. + - `--telemetry-target `: Переопределяет `telemetry.target`. + - `--telemetry-otlp-endpoint `: Переопределяет `telemetry.otlpEndpoint`. + - `--telemetry-log-prompts` / `--no-telemetry-log-prompts`: Переопределяет `telemetry.logPrompts`. + - `--telemetry-outfile `: Перенаправляет вывод телеметрии в файл. См. [Экспорт в файл](#exporting-to-a-file). -1. **Переменные окружения:** - - `OTEL_EXPORTER_OTLP_ENDPOINT`: Переопределяет `telemetry.otlpEndpoint`. +2. **Переменные окружения**: + - `OTEL_EXPORTER_OTLP_ENDPOINT`: Переопределяет `telemetry.otlpEndpoint`. -1. **Файл настроек рабочей области (`.qwen/settings.json`):** Значения из объекта `telemetry` в этом файле, специфичном для проекта. +3. **Файл настроек рабочей области (`.qwen/settings.json`)**: Значения из объекта `telemetry` в этом файле, специфичном для проекта. -1. **Файл пользовательских настроек (`~/.qwen/settings.json`):** Значения из объекта `telemetry` в этом глобальном файле пользователя. +4. **Файл пользовательских настроек (`~/.qwen/settings.json`)**: Значения из объекта `telemetry` в глобальном пользовательском файле. -1. **Значения по умолчанию:** применяются, если не заданы выше. - - `telemetry.enabled`: `false` - - `telemetry.target`: `local` - - `telemetry.otlpEndpoint`: `http://localhost:4317` - - `telemetry.logPrompts`: `true` +5. **Значения по умолчанию**: применяются, если не заданы вышеуказанными способами. + - `telemetry.enabled`: `false` + - `telemetry.target`: `local` + - `telemetry.otlpEndpoint`: `http://localhost:4317` + - `telemetry.logPrompts`: `true` -**Для скрипта `npm run telemetry -- --target=`:** -Аргумент `--target` для этого скрипта _только_ переопределяет `telemetry.target` на время выполнения и для целей этого скрипта (т.е. выбора collector'а, который нужно запустить). Он не изменяет ваш `settings.json` на постоянной основе. Скрипт сначала проверит `settings.json` на наличие `telemetry.target`, чтобы использовать его как значение по умолчанию. +**Для скрипта `npm run telemetry -- --target=`**: +Аргумент `--target` для этого скрипта _только_ переопределяет `telemetry.target` на время выполнения и с определенной целью (то есть выбор коллектора, который нужно запустить). Он не изменяет ваш `settings.json` на постоянной основе. Скрипт сначала проверит `settings.json` на наличие `telemetry.target`, чтобы использовать его как значение по умолчанию. ### Пример настроек @@ -55,11 +55,11 @@ Вы можете экспортировать все данные телеметрии в файл для локального анализа. -Чтобы включить экспорт в файл, используйте флаг `--telemetry-outfile`, указав путь к желаемому файлу вывода. Это необходимо запускать с параметром `--telemetry-target=local`. +Чтобы включить экспорт в файл, используйте флаг `--telemetry-outfile`, указав путь к желаемому выходному файлу. Это должно запускаться с параметром `--telemetry-target=local`. ```bash -# Укажите путь к файлу, в который хотите сохранить телеметрию +# Укажите путь к вашему файлу вывода TELEMETRY_FILE=".qwen/telemetry.log" # Запустите Qwen Code с локальной телеметрией @@ -77,7 +77,7 @@ qwen --telemetry \ ## Запуск OTEL Collector OTEL Collector — это сервис, который получает, обрабатывает и экспортирует телеметрические данные. -CLI может отправлять данные, используя либо протокол OTLP/gRPC, либо OTLP/HTTP. +CLI может отправлять данные, используя протокол OTLP/gRPC или OTLP/HTTP. Выбрать протокол можно с помощью флага `--telemetry-otlp-protocol` или настройки `telemetry.otlpProtocol` в файле `settings.json`. Подробнее — в [документации по конфигурации](./cli/configuration.md#--telemetry-otlp-protocol). @@ -86,9 +86,9 @@ CLI может отправлять данные, используя либо п [otel-config-docs]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/ -### Local +### Локально -Используйте команду `npm run telemetry -- --target=local`, чтобы автоматизировать процесс настройки локального telemetry pipeline, включая конфигурацию необходимых параметров в вашем файле `.qwen/settings.json`. Скрипт устанавливает `otelcol-contrib` (OpenTelemetry Collector) и `jaeger` (Jaeger UI для просмотра трассировок). Чтобы начать работу: +Используйте команду `npm run telemetry -- --target=local`, чтобы автоматизировать процесс настройки локального telemetry pipeline, включая конфигурацию необходимых параметров в файле `.qwen/settings.json`. Скрипт устанавливает `otelcol-contrib` (OpenTelemetry Collector) и `jaeger` (Jaeger UI для просмотра трассировок). Чтобы начать работу: 1. **Выполните команду**: Запустите команду из корня репозитория: @@ -98,9 +98,9 @@ CLI может отправлять данные, используя либо п ``` Скрипт выполнит следующие действия: - - Загрузит Jaeger и OTEL, если это необходимо. + - Загрузит Jaeger и OTEL при необходимости. - Запустит локальный экземпляр Jaeger. - - Запустит OTEL collector, настроенный на получение данных от Qwen Code. + - Запустит OTEL collector, сконфигурированный для получения данных от Qwen Code. - Автоматически включит telemetry в настройках вашего workspace. - При завершении отключит telemetry. @@ -108,53 +108,53 @@ CLI может отправлять данные, используя либо п Откройте браузер и перейдите по адресу **http://localhost:16686**, чтобы получить доступ к Jaeger UI. Здесь вы сможете изучить подробные трассировки операций Qwen Code. 1. **Просмотр логов и метрик**: - Скрипт перенаправляет вывод OTEL collector (включая логи и метрики) в файл `~/.qwen/tmp//otel/collector.log`. Скрипт также предоставит ссылки для просмотра и команду для отслеживания ваших telemetry данных (трассировки, метрики, логи) в реальном времени. + Скрипт перенаправляет вывод OTEL collector (включая логи и метрики) в файл `~/.qwen/tmp//otel/collector.log`. Скрипт также предоставит ссылки для просмотра и команду для отслеживания ваших telemetry данных (трассировки, метрики, логи) локально. 1. **Остановка сервисов**: Нажмите `Ctrl+C` в терминале, где запущен скрипт, чтобы остановить OTEL Collector и Jaeger. ### Google Cloud -Используйте команду `npm run telemetry -- --target=gcp`, чтобы автоматизировать настройку локального OpenTelemetry collector, который будет пересылать данные в ваш проект Google Cloud, включая конфигурацию необходимых параметров в файле `.qwen/settings.json`. Скрипт устанавливает `otelcol-contrib`. Чтобы использовать его: +Используйте команду `npm run telemetry -- --target=gcp`, чтобы автоматизировать настройку локального OpenTelemetry collector'а, который будет пересылать данные в ваш проект Google Cloud, включая конфигурацию необходимых параметров в файле `.qwen/settings.json`. Скрипт под капотом устанавливает `otelcol-contrib`. Чтобы использовать его: -1. **Предварительные требования**: +1. **Требования**: - У вас должен быть ID проекта Google Cloud. - - Экспортируйте переменную окружения `GOOGLE_CLOUD_PROJECT`, чтобы она была доступна для OTEL collector. + - Экспортируйте переменную окружения `GOOGLE_CLOUD_PROJECT`, чтобы она была доступна для OTEL collector'а. ```bash export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" ``` - - Пройдите аутентификацию в Google Cloud (например, выполните `gcloud auth application-default login` или убедитесь, что установлена переменная `GOOGLE_APPLICATION_CREDENTIALS`). - - Убедитесь, что у вашей учетной записи Google Cloud или сервисной учетной записи есть необходимые роли IAM: "Cloud Trace Agent", "Monitoring Metric Writer" и "Logs Writer". + - Авторизуйтесь в Google Cloud (например, выполните `gcloud auth application-default login` или убедитесь, что установлена переменная `GOOGLE_APPLICATION_CREDENTIALS`). + - Убедитесь, что у вашей учетной записи Google Cloud / сервисного аккаунта есть необходимые роли IAM: "Cloud Trace Agent", "Monitoring Metric Writer" и "Logs Writer". -1. **Выполните команду**: - Запустите команду из корня репозитория: +1. **Запустите команду**: + Выполните команду из корня репозитория: ```bash npm run telemetry -- --target=gcp ``` - Скрипт выполнит следующие действия: + Скрипт сделает следующее: - Загрузит бинарный файл `otelcol-contrib`, если это необходимо. - - Запустит OTEL collector, настроенный на получение данных от Qwen Code и их экспорт в указанный проект Google Cloud. + - Запустит OTEL collector, сконфигурированный для получения данных от Qwen Code и экспорта их в указанный проект Google Cloud. - Автоматически включит телеметрию и отключит sandbox mode в настройках вашего workspace (`.qwen/settings.json`). - Предоставит прямые ссылки для просмотра трассировок, метрик и логов в Google Cloud Console. - - При завершении работы (Ctrl+C) попытается восстановить исходные настройки телеметрии и sandbox mode. + - При завершении работы (Ctrl+C) попытается восстановить исходные настройки телеметрии и sandbox режима. 1. **Запустите Qwen Code**: - В отдельном терминале выполните команды Qwen Code. Это сгенерирует данные телеметрии, которые будут захвачены collector. + В отдельном терминале запустите свои команды Qwen Code. Это сгенерирует телеметрические данные, которые будут захвачены collector'ом. 1. **Просмотр телеметрии в Google Cloud**: - Используйте ссылки, предоставленные скриптом, чтобы перейти в Google Cloud Console и просмотреть трассировки, метрики и логи. + Используйте ссылки, предоставленные скриптом, чтобы перейти в Google Cloud Console и посмотреть ваши трассировки, метрики и логи. -1. **Просмотр логов локального collector**: - Скрипт перенаправляет вывод локального OTEL collector в `~/.qwen/tmp//otel/collector-gcp.log`. Скрипт также предоставляет ссылки и команды для просмотра логов collector локально. +1. **Проверьте локальные логи collector'а**: + Скрипт перенаправляет вывод локального OTEL collector'а в `~/.qwen/tmp//otel/collector-gcp.log`. Также предоставляются ссылки и команда для просмотра логов collector'а в реальном времени. 1. **Остановка сервиса**: Нажмите `Ctrl+C` в терминале, где запущен скрипт, чтобы остановить OTEL Collector. ## Справочник по логам и метрикам -В данном разделе описывается структура логов и метрик, генерируемых для Qwen Code. +В следующем разделе описывается структура логов и метрик, генерируемых для Qwen Code. - `sessionId` включается как общий атрибут во все логи и метрики. @@ -177,11 +177,12 @@ CLI может отправлять данные, используя либо п - `debug_mode` (boolean) - `mcp_servers` (string) -- `qwen-code.user_prompt`: Это событие происходит, когда пользователь отправляет prompt. +- `qwen-code.user_prompt`: Это событие происходит, когда пользователь отправляет промпт. - **Атрибуты**: - - `prompt_length` - - `prompt` (этот атрибут исключается, если `log_prompts_enabled` установлен в `false`) - - `auth_type` + - `prompt_length` (int) + - `prompt_id` (string) + - `prompt` (string, этот атрибут исключается, если `log_prompts_enabled` установлен в `false`) + - `auth_type` (string) - `qwen-code.tool_call`: Это событие происходит при каждом вызове функции. - **Атрибуты**: @@ -189,12 +190,12 @@ CLI может отправлять данные, используя либо п - `function_args` - `duration_ms` - `success` (boolean) - - `decision` (string: "accept", "reject", "auto_accept", или "modify", если применимо) + - `decision` (string: "accept", "reject", "auto_accept" или "modify", если применимо) - `error` (если применимо) - `error_type` (если применимо) - `metadata` (если применимо, словарь string -> any) -- `qwen-code.api_request`: Это событие происходит при отправке запроса к Qwen API. +- `qwen-code.api_request`: Это событие происходит при выполнении запроса к Qwen API. - **Атрибуты**: - `model` - `request_text` (если применимо) @@ -222,7 +223,7 @@ CLI может отправлять данные, используя либо п - `response_text` (если применимо) - `auth_type` -- `qwen-code.flash_fallback`: Это событие происходит, когда Qwen Code переключается на flash в качестве резервного варианта. +- `qwen-code.flash_fallback`: Это событие происходит, когда Qwen Code переключается на flash как резервный вариант. - **Атрибуты**: - `auth_type` @@ -233,7 +234,7 @@ CLI может отправлять данные, используя либо п ### Метрики -Метрики — это числовые измерения поведения за определённый период времени. Для Qwen Code собираются следующие метрики (названия метрик остаются `qwen-code.*` для совместимости): +Метрики — это числовые измерения поведения за определенный период времени. Для Qwen Code собираются следующие метрики (названия метрик остаются в формате `qwen-code.*` для совместимости): - `qwen-code.session.count` (Counter, Int): Увеличивается на 1 при каждом запуске CLI. @@ -241,41 +242,42 @@ CLI может отправлять данные, используя либо п - **Атрибуты**: - `function_name` - `success` (boolean) - - `decision` (string: "accept", "reject", или "modify", если применимо) - - `tool_type` (string: "mcp", или "native", если применимо) + - `decision` (string: "accept", "reject" или "modify", если применимо) + - `tool_type` (string: "mcp" или "native", если применимо) -- `qwen-code.tool.call.latency` (Histogram, ms): Измеряет задержку вызовов инструментов. +- `qwen-code.tool.call.latency` (Histogram, мс): Измеряет задержку вызова инструментов. - **Атрибуты**: - `function_name` - - `decision` (string: "accept", "reject", или "modify", если применимо) + - `decision` (string: "accept", "reject" или "modify", если применимо) -- `qwen-code.api.request.count` (Counter, Int): Считает все API-запросы. +- `qwen-code.api.request.count` (Counter, Int): Считает все запросы к API. - **Атрибуты**: - `model` - `status_code` - `error_type` (если применимо) -- `qwen-code.api.request.latency` (Histogram, ms): Измеряет задержку API-запросов. +- `qwen-code.api.request.latency` (Histogram, мс): Измеряет задержку запросов к API. - **Атрибуты**: - `model` - `qwen-code.token.usage` (Counter, Int): Считает количество использованных токенов. - **Атрибуты**: - `model` - - `type` (string: "input", "output", "thought", "cache", или "tool") + - `type` (string: "input", "output", "thought", "cache" или "tool") -- `qwen-code.file.operation.count` (Counter, Int): Считает количество операций с файлами. +- `qwen-code.file.operation.count` (Counter, Int): Считает операции с файлами. - **Атрибуты**: - `operation` (string: "create", "read", "update"): Тип операции с файлом. - `lines` (Int, если применимо): Количество строк в файле. - `mimetype` (string, если применимо): MIME-тип файла. - `extension` (string, если применимо): Расширение файла. - - `ai_added_lines` (Int, если применимо): Количество строк, добавленных/изменённых AI. - - `ai_removed_lines` (Int, если применимо): Количество строк, удалённых/изменённых AI. - - `user_added_lines` (Int, если применимо): Количество строк, добавленных/изменённых пользователем в предложенных AI изменениях. - - `user_removed_lines` (Int, если применимо): Количество строк, удалённых/изменённых пользователем в предложенных AI изменениях. + - `ai_added_lines` (Int, если применимо): Количество строк, добавленных/изменённых ИИ. + - `ai_removed_lines` (Int, если применимо): Количество строк, удалённых/изменённых ИИ. + - `user_added_lines` (Int, если применимо): Количество строк, добавленных/изменённых пользователем в предложенных ИИ изменениях. + - `user_removed_lines` (Int, если применимо): Количество строк, удалённых/изменённых пользователем в предложенных ИИ изменениях. + - `programming_language` (string, если применимо): Язык программирования файла. -- `qwen-code.chat_compression` (Counter, Int): Считает количество операций сжатия чата. +- `qwen-code.chat_compression` (Counter, Int): Считает операции сжатия чата. - **Атрибуты**: - - `tokens_before`: (Int): Количество токенов в контексте до сжатия. - - `tokens_after`: (Int): Количество токенов в контексте после сжатия. \ No newline at end of file + - `tokens_before` (Int): Количество токенов в контексте до сжатия. + - `tokens_after` (Int): Количество токенов в контексте после сжатия. \ No newline at end of file diff --git a/website/content/ru/tools/multi-file.md b/website/content/ru/tools/multi-file.md index 59891a68..4d092d08 100644 --- a/website/content/ru/tools/multi-file.md +++ b/website/content/ru/tools/multi-file.md @@ -4,14 +4,14 @@ ## Описание -Используйте `read_many_files` для чтения содержимого из нескольких файлов, указанных по путям или по glob-паттернам. Поведение этого инструмента зависит от переданных файлов: +Используйте `read_many_files` для чтения содержимого из нескольких файлов, указанных по путям или с помощью glob-паттернов. Поведение этого инструмента зависит от переданных файлов: - Для текстовых файлов инструмент объединяет их содержимое в одну строку. -- Для изображений (например, PNG, JPEG), PDF, аудио (MP3, WAV) и видео (MP4, MOV) файлов он читает и возвращает данные в формате base64, при условии, что они явно запрошены по имени или расширению. +- Для изображений (например, PNG, JPEG), PDF, аудио (MP3, WAV) и видеофайлов (MP4, MOV) он читает и возвращает данные в формате base64, при условии, что они явно запрошены по имени или расширению. `read_many_files` может использоваться для выполнения таких задач, как получение общего представления о кодовой базе, поиск мест реализации определённой функциональности, просмотр документации или сбор контекста из нескольких конфигурационных файлов. -**Примечание:** `read_many_files` ищет файлы по указанным путям или glob-паттернам. Путь к директории, например `"/docs"`, вернёт пустой результат; инструменту требуется паттерн, такой как `"/docs/*"` или `"/docs/*.md"`, чтобы определить нужные файлы. +**Примечание:** `read_many_files` ищет файлы по указанным путям или glob-паттернам. Указание пути к директории, например `"/docs"`, вернёт пустой результат; инструмент требует паттерн, такой как `"/docs/*"` или `"/docs/*.md"`, чтобы определить нужные файлы. ### Аргументы @@ -19,18 +19,19 @@ - `paths` (list[string], обязательный): Массив glob-паттернов или путей относительно целевой директории инструмента (например, `["src/**/*.ts"]`, `["README.md", "docs/*", "assets/logo.png"]`). - `exclude` (list[string], опциональный): Glob-паттерны для файлов/директорий, которые нужно исключить (например, `["**/*.log", "temp/"]`). Эти паттерны добавляются к стандартным исключениям, если `useDefaultExcludes` равен `true`. -- `include` (list[string], опциональный): Дополнительные glob-паттерны для включения. Они объединяются с `paths` (например, `["*.test.ts"]`, чтобы специально добавить тестовые файлы, если они были исключены в более общем виде, или `["images/*.jpg"]`, чтобы включить определенные типы изображений). -- `recursive` (boolean, опциональный): Искать ли файлы рекурсивно. В основном управляется символами `**` в glob-паттернах. По умолчанию `true`. -- `useDefaultExcludes` (boolean, опциональный): Применять ли список стандартных паттернов исключения (например, `node_modules`, `.git`, бинарные файлы, не являющиеся изображениями или PDF). По умолчанию `true`. +- `include` (list[string], опциональный): Дополнительные glob-паттерны для включения. Они объединяются с `paths` (например, `["*.test.ts"]`, чтобы явно добавить тестовые файлы, если они были исключены в более общем виде, или `["images/*.jpg"]`, чтобы включить определённые типы изображений). +- `recursive` (boolean, опциональный): Рекурсивный ли поиск. В основном управляется символами `**` в glob-паттернах. По умолчанию `true`. +- `useDefaultExcludes` (boolean, опциональный): Применять ли список стандартных паттернов исключения (например, `node_modules`, `.git`, бинарные файлы, не являющиеся изображениями/PDF). По умолчанию `true`. - `respect_git_ignore` (boolean, опциональный): Учитывать ли паттерны из .gitignore при поиске файлов. По умолчанию `true`. ## Как использовать `read_many_files` с Qwen Code `read_many_files` ищет файлы, соответствующие указанным шаблонам `paths` и `include`, при этом учитывая шаблоны `exclude` и стандартные исключения (если включены). -- Для текстовых файлов: инструмент читает содержимое каждого найденного файла (пытаясь пропустить бинарные файлы, если они не запрошены явно как изображения/PDF) и объединяет их в одну строку, разделяя содержимое каждого файла сепаратором `--- {filePath} ---`. По умолчанию используется кодировка UTF-8. -- Для изображений и PDF-файлов: если файлы запрошены явно по имени или расширению (например, `paths: ["logo.png"]` или `include: ["*.pdf"]`), инструмент читает файл и возвращает его содержимое в виде строки в кодировке base64. -- Инструмент пытается определить и пропустить другие бинарные файлы (которые не относятся к изображениям/PDF или не запрошены явно), проверяя наличие null-байтов в начале содержимого файла. +- Для текстовых файлов: инструмент читает содержимое каждого найденного файла (пытаясь пропустить бинарные файлы, которые явно не запрошены как изображения/PDF) и объединяет их в одну строку, разделяя содержимое каждого файла сепаратором `--- {filePath} ---`. По умолчанию используется кодировка UTF-8. +- Инструмент добавляет `--- End of content ---` после последнего файла. +- Для изображений и PDF-файлов: если они явно запрошены по имени или расширению (например, `paths: ["logo.png"]` или `include: ["*.pdf"]`), инструмент читает файл и возвращает его содержимое в виде строки в кодировке base64. +- Инструмент пытается определить и пропустить другие бинарные файлы (которые не относятся к распространенным типам изображений/PDF или не были явно запрошены), проверяя наличие нулевых байтов в начале содержимого файла. Использование: @@ -40,19 +41,19 @@ read_many_files(paths=["Ваши файлы или пути здесь."], inclu ## Примеры использования `read_many_files` -Чтение всех TypeScript файлов в директории `src`: +Чтение всех файлов TypeScript в директории `src`: ``` read_many_files(paths=["src/**/*.ts"]) ``` -Чтение основного README, всех Markdown файлов в директории `docs` и конкретного файла логотипа, исключая определенный файл: +Чтение основного README, всех Markdown файлов в директории `docs` и конкретного изображения логотипа, исключая определенный файл: ``` read_many_files(paths=["README.md", "docs/**/*.md", "assets/logo.png"], exclude=["docs/OLD_README.md"]) ``` -Чтение всех JavaScript файлов, но с явным включением тестовых файлов и всех JPEG из папки `images`: +Чтение всех файлов JavaScript, но с явным включением тестовых файлов и всех JPEG из папки `images`: ``` read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], useDefaultExcludes=False) @@ -61,8 +62,8 @@ read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], ## Важные замечания - **Работа с бинарными файлами:** - - **Файлы изображений/PDF/аудио/видео:** Инструмент может читать распространенные типы изображений (PNG, JPEG и т.д.), PDF, аудио (mp3, wav) и видео (mp4, mov) файлы, возвращая их как данные в кодировке base64. Эти файлы _должны_ быть явно указаны в паттернах `paths` или `include` (например, путем указания точного имени файла, как `video.mp4`, или паттерна вроде `*.mov`). - - **Другие бинарные файлы:** Инструмент пытается обнаружить и пропустить другие типы бинарных файлов, проверяя наличие null-байтов в начале содержимого файла. Такие файлы исключаются из вывода инструмента. -- **Производительность:** Чтение очень большого количества файлов или очень больших отдельных файлов может быть ресурсоемким. -- **Точность путей:** Убедитесь, что пути и glob-паттерны указаны корректно относительно целевой директории инструмента. Для файлов изображений/PDF убедитесь, что паттерны достаточно точные, чтобы включить нужные файлы. -- **Исключения по умолчанию:** Имейте в виду стандартные паттерны исключения (такие как `node_modules`, `.git`) и используйте `useDefaultExcludes=False`, если вам нужно их переопределить, но делайте это осмотрительно. \ No newline at end of file + - **Файлы изображений/PDF/аудио/видео:** Инструмент может читать распространенные типы изображений (PNG, JPEG и т.д.), PDF, аудио (mp3, wav) и видео (mp4, mov) файлы, возвращая их как данные в кодировке base64. Эти файлы _обязательно_ должны быть явно указаны в паттернах `paths` или `include` (например, путем указания точного имени файла, такого как `video.mp4`, или паттерна, например `*.mov`). + - **Другие бинарные файлы:** Инструмент пытается обнаружить и пропустить другие типы бинарных файлов, проверяя наличие нулевых байтов в начале содержимого файла. Такие файлы исключаются из вывода инструмента. +- **Производительность:** Чтение очень большого количества файлов или очень больших отдельных файлов может потреблять много ресурсов. +- **Точность путей:** Убедитесь, что пути и glob-паттерны правильно заданы относительно целевой директории инструмента. Для файлов изображений/PDF убедитесь, что паттерны достаточно точные, чтобы включить эти файлы. +- **Исключения по умолчанию:** Имейте в виду стандартные паттерны исключения (такие как `node_modules`, `.git`) и используйте `useDefaultExcludes=False`, если вам нужно их переопределить, но делайте это осторожно. \ No newline at end of file diff --git a/website/content/ru/troubleshooting.md b/website/content/ru/troubleshooting.md index e6c00ce2..5ae00ead 100644 --- a/website/content/ru/troubleshooting.md +++ b/website/content/ru/troubleshooting.md @@ -10,7 +10,7 @@ ## Ошибки аутентификации или входа в систему - **Ошибка: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` или `unable to get local issuer certificate`** - - **Причина:** Возможно, вы находитесь в корпоративной сети с брандмауэром, который перехватывает и инспектирует SSL/TLS трафик. Часто для этого требуется, чтобы Node.js доверял пользовательскому корневому сертификату ЦС. + - **Причина:** Вы можете находиться в корпоративной сети с брандмауэром, который перехватывает и инспектирует SSL/TLS трафик. Для этого часто требуется, чтобы пользовательский корневой сертификат ЦС был доверенным для Node.js. - **Решение:** Установите переменную окружения `NODE_EXTRA_CA_CERTS` в абсолютный путь к файлу корневого сертификата вашего корпоративного ЦС. - Пример: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` @@ -27,21 +27,21 @@ Дополнительную информацию см. в разделе [Конфигурация Qwen Code](./cli/configuration.md). - **В: Почему я не вижу кэшированные подсчеты токенов в выводе статистики?** - - О: Информация о кэшированных токенах отображается только при использовании кэшированных токенов. Эта функция доступна для пользователей API-ключей (Qwen API key или Google Cloud Vertex AI), но недоступна для пользователей OAuth (например, личных/корпоративных аккаунтов Google, таких как Google Gmail или Google Workspace). Это связано с тем, что Qwen Code Assist API не поддерживает создание кэшированного контента. Вы по-прежнему можете просматривать общее использование токенов с помощью команды `/stats`. + - О: Информация о кэшированных токенах отображается только тогда, когда используются кэшированные токены. Эта функция доступна для пользователей API-ключей (Qwen API key или Google Cloud Vertex AI), но недоступна для пользователей OAuth (например, личных/корпоративных аккаунтов Google, таких как Google Gmail или Google Workspace). Это связано с тем, что Qwen Code Assist API не поддерживает создание кэшированного контента. Вы по-прежнему можете просматривать общее использование токенов с помощью команды `/stats`. ## Распространенные сообщения об ошибках и решения -- **Ошибка: `EADDRINUSE` (Адрес уже используется) при запуске MCP сервера.** - - **Причина:** Другой процесс уже использует порт, к которому пытается привязаться MCP сервер. +- **Ошибка: `EADDRINUSE` (Адрес уже используется) при запуске сервера MCP.** + - **Причина:** Другой процесс уже использует порт, к которому пытается привязаться сервер MCP. - **Решение:** - Остановите другой процесс, использующий этот порт, или настройте MCP сервер на использование другого порта. + Остановите другой процесс, использующий этот порт, или настройте сервер MCP на использование другого порта. - **Ошибка: Команда не найдена (при попытке запустить Qwen Code с помощью `qwen`).** - - **Причина:** CLI не установлен корректно или не добавлен в системную переменную `PATH`. + - **Причина:** CLI не установлен корректно или не добавлен в `PATH` вашей системы. - **Решение:** Способ обновления зависит от того, как вы установили Qwen Code: - - Если вы установили `qwen` глобально, проверьте, что директория с глобальными бинарниками `npm` находится в вашем `PATH`. Вы можете обновить с помощью команды `npm install -g @qwen-code/qwen-code@latest`. - - Если вы запускаете `qwen` из исходников, убедитесь, что используете правильную команду для запуска (например, `node packages/cli/dist/index.js ...`). Чтобы обновить, сделайте pull последних изменений из репозитория и пересоберите проект командой `npm run build`. + - Если вы установили `qwen` глобально, убедитесь, что директория с глобальными бинарниками `npm` находится в вашем `PATH`. Вы можете обновить его с помощью команды `npm install -g @qwen-code/qwen-code@latest`. + - Если вы запускаете `qwen` из исходников, убедитесь, что используете правильную команду для запуска (например, `node packages/cli/dist/index.js ...`). Чтобы обновить, сделайте `pull` последних изменений из репозитория и пересоберите проект командой `npm run build`. - **Ошибка: `MODULE_NOT_FOUND` или ошибки импорта.** - **Причина:** Зависимости установлены некорректно или проект не был собран. @@ -51,33 +51,45 @@ 3. Убедитесь, что сборка прошла успешно, с помощью `npm run start`. - **Ошибка: "Operation not permitted", "Permission denied" или аналогичные.** - - **Причина:** Когда включено sandboxing, Qwen Code может пытаться выполнить операции, запрещенные вашей конфигурацией песочницы, например, запись вне директории проекта или системной временной директории. + - **Причина:** Если включён sandboxing, Qwen Code может пытаться выполнить операции, запрещённые вашей конфигурацией песочницы, например, запись вне директории проекта или системной временной директории. - **Решение:** Обратитесь к документации [Configuration: Sandboxing](./cli/configuration.md#sandboxing) для получения дополнительной информации, включая способы настройки конфигурации песочницы. - **Qwen Code не запускается в интерактивном режиме в CI-средах** - - **Проблема:** Qwen Code не переходит в интерактивный режим (не появляется приглашение ввода), если установлена переменная окружения, начинающаяся с `CI_` (например, `CI_TOKEN`). Это происходит потому, что пакет `is-in-ci`, используемый в UI-фреймворке, обнаруживает такие переменные и считает, что среда не интерактивна. - - **Причина:** Пакет `is-in-ci` проверяет наличие переменных `CI`, `CONTINUOUS_INTEGRATION` или любых переменных с префиксом `CI_`. Если такие переменные найдены, это сигнализирует о том, что среда не интерактивна, и CLI не запускается в интерактивном режиме. - - **Решение:** Если переменная с префиксом `CI_` не требуется для работы CLI, вы можете временно отключить её для команды. Например: `env -u CI_TOKEN qwen` + - **Проблема:** Qwen Code не переходит в интерактивный режим (не появляется приглашение ввода), если установлена переменная окружения, начинающаяся с `CI_` (например, `CI_TOKEN`). Это происходит потому, что пакет `is-in-ci`, используемый в UI-фреймворке, определяет такие переменные как признак неинтерактивной CI-среды. + - **Причина:** Пакет `is-in-ci` проверяет наличие переменных `CI`, `CONTINUOUS_INTEGRATION` или любых переменных с префиксом `CI_`. При обнаружении хотя бы одной из них он считает, что среда неинтерактивна, и CLI не запускается в интерактивном режиме. + - **Решение:** Если переменная с префиксом `CI_` не требуется для работы CLI, её можно временно отключить при запуске команды. Например: `env -u CI_TOKEN qwen` -- **DEBUG режим не работает из файла .env проекта** - - **Проблема:** Установка `DEBUG=true` в файле `.env` проекта не включает режим отладки для CLI. - - **Причина:** Переменные `DEBUG` и `DEBUG_MODE` автоматически исключаются из файлов `.env` проекта, чтобы не мешать работе CLI. +- **DEBUG-режим не работает при установке через .env файл проекта** + - **Проблема:** Установка `DEBUG=true` в `.env` файле проекта не включает debug-режим для CLI. + - **Причина:** Переменные `DEBUG` и `DEBUG_MODE` автоматически исключаются из `.env` файлов проекта, чтобы не мешать работе CLI. - **Решение:** Используйте файл `.qwen/.env` вместо этого, или настройте параметр `excludedProjectEnvVars` в вашем `settings.json`, чтобы исключить меньше переменных. ## IDE Companion не подключается - Убедитесь, что в VS Code открыт только один workspace folder. -- Перезапустите встроенный терминал после установки расширения, чтобы он унаследовал переменные: +- Перезапустите интегрированный терминал после установки расширения, чтобы он унаследовал переменные: - `QWEN_CODE_IDE_WORKSPACE_PATH` - `QWEN_CODE_IDE_SERVER_PORT` -- Если вы работаете в контейнере, проверьте, что `host.docker.internal` резолвится. В противном случае, настройте соответствующий маппинг хоста. -- Переустановите companion с помощью `/ide install` и используйте команду “Qwen Code: Run” из Command Palette, чтобы убедиться, что он запускается. +- Если вы работаете внутри контейнера, проверьте, что `host.docker.internal` резолвится. В противном случае, настройте соответствующий маппинг хоста. +- Переустановите companion с помощью `/ide install` и используйте команду “Qwen Code: Run” из Command Palette, чтобы проверить запуск. + +## Коды завершения + +Qwen Code использует определенные коды завершения для указания причины остановки. Это особенно полезно при написании скриптов и автоматизации. + +| Код завершения | Тип ошибки | Описание | +| -------------- | --------------------------- | -------------------------------------------------------------------------------------------------- | +| 41 | `FatalAuthenticationError` | Произошла ошибка в процессе аутентификации. | +| 42 | `FatalInputError` | Был предоставлен неверный или отсутствующий ввод в CLI. (только в неинтерактивном режиме) | +| 44 | `FatalSandboxError` | Произошла ошибка с песочницей (например, Docker, Podman или Seatbelt). | +| 52 | `FatalConfigError` | Конфигурационный файл (`settings.json`) недействителен или содержит ошибки. | +| 53 | `FatalTurnLimitedError` | Достигнуто максимальное количество шагов диалога в рамках сессии. (только в неинтерактивном режиме)| ## Советы по отладке - **Отладка CLI:** - Используйте флаг `--verbose` (если доступен) с командами CLI для получения более подробного вывода. - - Проверьте логи CLI, которые обычно находятся в пользовательской директории конфигурации или кэша. + - Проверьте логи CLI, которые часто находятся в пользовательской директории конфигурации или кэша. - **Отладка ядра:** - Проверьте вывод консоли сервера на наличие сообщений об ошибках или stack trace. @@ -85,7 +97,7 @@ - Используйте инструменты отладки Node.js (например, `node --inspect`), если нужно пошагово пройти по серверному коду. - **Проблемы с инструментами:** - - Если конкретный инструмент не работает, попробуйте изолировать проблему, запустив самую простую возможную версию команды или операции, которую выполняет инструмент. + - Если конкретный инструмент не работает, попробуйте изолировать проблему, запустив самую простую версию команды или операции, которую выполняет инструмент. - Для `run_shell_command` сначала проверьте, что команда работает напрямую в вашем shell. - Для _инструментов файловой системы_ убедитесь, что пути указаны правильно, и проверьте права доступа. diff --git a/website/content/zh/cli/commands.md b/website/content/zh/cli/commands.md index a88d0814..28aba4b9 100644 --- a/website/content/zh/cli/commands.md +++ b/website/content/zh/cli/commands.md @@ -9,181 +9,183 @@ Qwen Code 支持多个内置命令，帮助你管理会话、自定义界面并 ### 内置命令 - **`/bug`** - - **描述：** 提交一个关于 Qwen Code 的 issue。默认情况下，issue 会提交到 Qwen Code 的 GitHub 仓库中。你在 `/bug` 后输入的字符串将成为该 bug 的标题。你可以通过在 `.qwen/settings.json` 文件中配置 `bugCommand` 设置来修改 `/bug` 的默认行为。 + - **说明：** 提交关于 Qwen Code 的 issue。默认情况下，issue 会提交到 Qwen Code 的 GitHub 仓库中。你在 `/bug` 后输入的字符串将成为该 bug 的标题。你可以通过在 `.qwen/settings.json` 文件中设置 `bugCommand` 来修改 `/bug` 的默认行为。 - **`/chat`** - - **描述：** 交互式地保存和恢复对话历史，以便在不同分支对话状态之间切换，或在后续会话中恢复之前的对话状态。 + - **说明：** 交互式地保存和恢复对话历史，支持分支对话状态或从后续会话中恢复之前的状态。 - **子命令：** - **`save`** - - **描述：** 保存当前对话历史。你必须添加一个 `` 来标识该对话状态。 + - **说明：** 保存当前对话历史。你必须添加一个 `` 用于标识对话状态。 - **用法：** `/chat save ` - **检查点位置详情：** 默认的聊天检查点保存位置为： - - Linux/macOS: `~/.config/qwen-code/checkpoints/` - - Windows: `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` - - 当你运行 `/chat list` 时，CLI 只会扫描这些特定目录以查找可用的检查点。 - - **注意：** 这些检查点用于手动保存和恢复对话状态。如需了解在文件修改前自动创建的检查点，请参阅 [Checkpointing documentation](../checkpointing.md)。 + - Linux/macOS: `~/.qwen/tmp//` + - Windows: `C:\Users\\.qwen\tmp\\` + - 当你运行 `/chat list` 时，CLI 只会在这些特定目录中扫描可用的检查点。 + - **注意：** 这些检查点是手动保存和恢复对话状态使用的。如需了解文件修改前自动创建的检查点，请参阅 [Checkpointing 文档](../checkpointing.md)。 - **`resume`** - - **描述：** 从之前的保存点恢复对话。 + - **说明：** 从之前的保存中恢复对话。 - **用法：** `/chat resume ` - **`list`** - - **描述：** 列出可用于恢复对话状态的标签。 + - **说明：** 列出可用于恢复对话状态的标签。 - **`delete`** - - **描述：** 删除已保存的对话检查点。 + - **说明：** 删除已保存的对话检查点。 - **用法：** `/chat delete ` - **`/clear`** - - **描述：** 清除终端屏幕，包括 CLI 中可见的会话历史和滚动缓冲区。底层会话数据（用于历史回溯）可能会根据具体实现保留，但视觉显示会被清除。 - - **快捷键：** 随时按 **Ctrl+L** 执行清除操作。 + - **说明：** 清除终端屏幕内容，包括 CLI 中可见的会话历史和滚动缓冲区。底层会话数据（用于历史回溯）可能会根据具体实现保留，但视觉显示会被清除。 + - **快捷键：** 随时按 **Ctrl+L** 执行清屏操作。 - **`/summary`** - - **描述：** 根据当前对话历史生成一个全面的项目摘要，并保存到 `.qwen/PROJECT_SUMMARY.md`。该摘要包括总体目标、关键知识、最近操作和当前计划，非常适合在未来的会话中恢复工作。 + - **说明：** 根据当前对话历史生成全面的项目摘要，并保存至 `.qwen/PROJECT_SUMMARY.md`。此摘要包含整体目标、关键知识、最近的操作以及当前计划，非常适合在未来会话中继续工作。 - **用法：** `/summary` - - **功能：** - - 分析整个对话历史以提取重要上下文 - - 创建结构化的 markdown 摘要，包含目标、知识、操作和计划等部分 + - **功能特性：** + - 分析整个对话历史以提取重要上下文信息 + - 创建结构化的 markdown 摘要，分为目标、知识、操作和计划等部分 - 自动保存到项目根目录下的 `.qwen/PROJECT_SUMMARY.md` - - 在生成和保存过程中显示进度指示器 - - 与 Welcome Back 功能集成，实现无缝会话恢复 - - **注意：** 此命令需要至少包含 2 条消息的活跃对话才能生成有意义的摘要。 + - 在生成与保存过程中显示进度指示器 + - 与“Welcome Back”功能集成，实现无缝恢复会话 + - **注意：** 此命令需要至少有两条消息的有效对话才能生成有意义的摘要。 - **`/compress`** - - **描述：** 用摘要替换整个聊天上下文。这可以节省未来任务使用的 token 数量，同时保留已发生事件的高级摘要。 + - **说明：** 将整个聊天上下文替换为摘要。这可以节省未来任务所使用的 token 数量，同时保留高层次的历史总结。 - **`/copy`** - - **描述：** 将 Qwen Code 生成的最后一个输出复制到剪贴板，方便分享或重复使用。 + - **说明：** 复制 Qwen Code 最后一次输出的内容到剪贴板，便于分享或复用。 - **`/directory`**（或 **`/dir`**） - - **描述：** 管理工作区目录，支持多目录操作。 + - **说明：** 管理多目录支持的工作空间目录。 - **子命令：** - **`add`**： - - **描述：** 将目录添加到工作区。路径可以是绝对路径或相对于当前工作目录的相对路径。也支持从主目录开始的路径引用。 + - **说明：** 添加目录到工作空间。路径可以是绝对路径或相对于当前工作目录的相对路径。也支持从主目录开始引用。 - **用法：** `/directory add ,` - - **注意：** 在限制性沙盒配置文件中禁用此功能。如果你正在使用该配置，请在启动会话时使用 `--include-directories` 参数。 + - **注意：** 在受限沙盒配置文件中禁用。如果你正在使用这种模式，请改用启动会话时加上 `--include-directories` 参数。 - **`show`**： - - **描述：** 显示通过 `/directory add` 和 `--include-directories` 添加的所有目录。 - - **用法：** `/directory show` - -- **`/directory`**（或 **`/dir`**） - - **描述：** 管理工作区目录，支持多目录操作。 - - **子命令：** - - **`add`**： - - **描述：** 将目录添加到工作区。路径可以是绝对路径或相对于当前工作目录的相对路径。也支持从主目录开始的路径引用。 - - **用法：** `/directory add ,` - - **注意：** 在限制性沙盒配置文件中禁用此功能。如果你正在使用该配置，请在启动会话时使用 `--include-directories` 参数。 - - **`show`**： - - **描述：** 显示通过 `/directory add` 和 `--include-directories` 添加的所有目录。 + - **说明：** 显示所有通过 `/directory add` 和 `--include-directories` 添加的目录。 - **用法：** `/directory show` - **`/editor`** - - **描述：** 打开一个对话框，用于选择支持的编辑器。 + - **说明：** 打开一个对话框选择受支持的编辑器。 - **`/extensions`** - - **描述：** 列出当前 Qwen Code 会话中所有激活的扩展。详见 [Qwen Code Extensions](../extension.md)。 + - **说明：** 列出当前 Qwen Code 会话中的所有活跃扩展。详见 [Qwen Code Extensions](../extension.md)。 - **`/help`**（或 **`/?`**） - - **描述：** 显示 Qwen Code 的帮助信息，包括可用命令及其用法。 + - **说明：** 显示有关 Qwen Code 的帮助信息，包括可用命令及其使用方法。 - **`/mcp`** - - **描述：** 列出已配置的 Model Context Protocol (MCP) 服务器、其连接状态、服务器详情和可用工具。 + - **说明：** 列出已配置的 Model Context Protocol (MCP) 服务器、连接状态、服务器详细信息及可用工具。 - **子命令：** - **`desc`** 或 **`descriptions`**： - - **描述：** 显示 MCP 服务器和工具的详细描述。 + - **说明：** 显示 MCP 服务器和工具的详细描述。 - **`nodesc`** 或 **`nodescriptions`**： - - **描述：** 隐藏工具描述，仅显示工具名称。 + - **说明：** 隐藏工具描述，仅显示工具名称。 - **`schema`**： - - **描述：** 显示工具配置参数的完整 JSON schema。 - - **快捷键：** 随时按 **Ctrl+T** 在显示和隐藏工具描述之间切换。 + - **说明：** 显示工具配置参数的完整 JSON Schema。 + - **键盘快捷键：** 随时按 **Ctrl+T** 切换是否显示工具描述。 - **`/memory`** - - **描述：** 管理 AI 的指令上下文（默认从 `QWEN.md` 文件加载的分层内存；可通过 `contextFileName` 配置）。 + - **说明：** 管理 AI 的指令上下文（默认由 `QWEN.md` 文件加载的分层内存；可通过 `contextFileName` 配置）。 - **子命令：** - **`add`**： - - **描述：** 将以下文本添加到 AI 的内存中。用法：`/memory add ` + - **说明：** 将以下文本添加到 AI 的记忆中。用法：`/memory add ` - **`show`**： - - **描述：** 显示从所有上下文文件（如 `QWEN.md`）加载的当前分层内存的完整内容。这让你可以检查提供给模型的指令上下文。 + - **说明：** 显示当前从所有上下文文件（例如 `QWEN.md`）加载的所有分层内存的完整拼接内容。让你能够查看提供给模型的指令上下文。 - **`refresh`**： - - **描述：** 从配置位置（全局、项目/祖先目录和子目录）中找到的所有上下文文件（默认：`QWEN.md`）重新加载分层指令内存。这会用最新的上下文内容更新模型。 - - **注意：** 有关上下文文件如何贡献于分层内存的更多详情，请参阅 [CLI Configuration documentation](./configuration.md#context-files-hierarchical-instructional-context)。 + - **说明：** 重新从所有上下文文件（默认为 `QWEN.md`）中加载分层指令内存，这些文件位于全局、项目/祖先目录和子目录中。更新模型最新的上下文内容。 + - **注意：** 关于上下文文件如何贡献到分层内存的更多细节，请参见 [CLI Configuration 文档](./configuration.md#context-files-hierarchical-instructional-context)。 - **`/restore`** - - **描述：** 将项目文件恢复到工具执行前的状态。这对于撤销工具进行的文件编辑特别有用。如果在没有工具调用 ID 的情况下运行，它将列出可恢复的检查点。 + - **说明：** 将项目文件恢复到执行某个工具之前的状态。这对于撤销工具所做的文件更改特别有用。如果未指定工具调用 ID，则列出可从中恢复的检查点。 - **用法：** `/restore [tool_call_id]` - - **注意：** 仅在使用 `--checkpointing` 选项调用 CLI 或通过 [settings](./configuration.md) 配置时可用。详见 [Checkpointing documentation](../checkpointing.md)。 + - **注意：** 仅当 CLI 使用 `--checkpointing` 选项启动或通过 [settings](./configuration.md) 配置时才可用。详见 [Checkpointing 文档](../checkpointing.md)。 - **`/settings`** - - **描述：** 打开设置编辑器以查看和修改 Qwen Code 设置。 - - **详情：** 此命令提供了一个用户友好的界面来更改控制 Qwen Code 行为和外观的设置。它等效于手动编辑 `.qwen/settings.json` 文件，但带有验证和指导以防止错误。 - - **用法：** 简单运行 `/settings`，编辑器将打开。然后你可以浏览或搜索特定设置，查看其当前值并按需修改。某些设置的更改会立即生效，而其他设置需要重启。 + - **说明：** 打开设置编辑器以查看并修改 Qwen Code 设置。 + - **详情：** 此命令提供了用户友好的界面来更改控制 Qwen Code 行为和外观的设置项。它相当于手动编辑 `.qwen/settings.json` 文件，但具有验证和引导机制防止错误发生。 + - **用法：** 直接运行 `/settings` 即可打开编辑器。然后你可以浏览或搜索特定设置项，查看其当前值并进行修改。某些设置的更改立即生效，而其他一些则需要重启程序。 - **`/stats`** - - **描述：** 显示当前 Qwen Code 会话的详细统计信息，包括 token 使用量、缓存 token 节省量（如果可用）和会话持续时间。注意：缓存 token 信息仅在使用缓存 token 时显示，这在使用 API key 认证时发生，但目前在 OAuth 认证时不发生。 + - **说明：** 显示当前 Qwen Code 会话的详细统计信息，包括 token 使用情况、缓存 token 节省量（如有）、会话持续时间。注意：只有在使用 API 密钥认证且启用了缓存 token 功能时才会显示缓存 token 信息，目前 OAuth 认证不支持。 - [**`/theme`**](./themes.md) - - **描述：** 打开一个对话框，让你更改 Qwen Code 的视觉主题。 + - **说明：** 打开一个对话框允许你更改 Qwen Code 的视觉主题。 - **`/auth`** - - **描述：** 打开一个对话框，让你更改认证方法。 + - **说明：** 打开一个对话框允许你更改身份验证方式。 + +- **`/approval-mode`** + - **说明：** 更改工具使用的审批模式。 + - **用法：** `/approval-mode [mode] [--session|--project|--user]` + - **可用模式：** + - **`plan`**：仅分析，不修改文件或执行命令 + - **`default`**：要求对文件编辑或 shell 命令进行批准 + - **`auto-edit`**：自动批准文件编辑 + - **`yolo`**：自动批准所有工具 + - **示例：** + - `/approval-mode plan --project`（为此项目持久化 plan 模式） + - `/approval-mode yolo --user`（为此用户跨项目持久化 YOLO 模式） - **`/about`** - - **描述：** 显示版本信息。提交 issue 时请分享此信息。 + - **说明：** 显示版本信息。请在提交 issue 时共享这些信息。 - **`/agents`** - - **描述：** 管理专门用于特定任务的 AI 子代理。子代理是配置了特定专业知识和工具访问权限的独立 AI 助手。 + - **说明：** 管理专门针对聚焦任务的 AI 子代理。子代理是具备特定专业知识和工具访问权限的独立 AI 助手。 - **子命令：** - **`create`**： - - **描述：** 启动交互式向导以创建新的子代理。向导会引导你完成位置选择、AI 驱动的提示生成、工具选择和视觉定制。 + - **说明：** 启动交互向导创建新的子代理。向导将指导你完成位置选择、AI 驱动提示词生成、工具选择和可视化定制过程。 - **用法：** `/agents create` - **`manage`**： - - **描述：** 打开交互式管理对话框以查看、编辑和删除现有子代理。显示项目级和用户级代理。 + - **说明：** 打开交互管理对话框以查看、编辑和删除现有子代理。展示项目级和用户级代理。 - **用法：** `/agents manage` - **存储位置：** - - **项目级：** `.qwen/agents/`（与团队共享，优先级更高） - - **用户级：** `~/.qwen/agents/`（个人代理，跨项目可用） - - **注意：** 有关创建和管理子代理的详细信息，请参阅 [Subagents documentation](../subagents.md)。 + - **项目级：** `.qwen/agents/`（团队共享，优先级更高） + - **用户级：** `~/.qwen/agents/`（个人代理，在多个项目间可用） + - **注意：** 关于创建和管理子代理的详细信息，请参阅 [Subagents 文档](../subagents.md)。 - [**`/tools`**](../tools/index.md) - - **描述：** 显示当前在 Qwen Code 中可用的工具列表。 + - **说明：** 显示当前在 Qwen Code 中可用的工具列表。 + - **用法：** `/tools [desc]` - **子命令：** - **`desc`** 或 **`descriptions`**： - - **描述：** 显示每个工具的详细描述，包括提供给模型的每个工具的名称及其完整描述。 + - **说明：** 显示每个工具的详细描述，包括提供给模型的工具全名及其完整描述。 - **`nodesc`** 或 **`nodescriptions`**： - - **描述：** 隐藏工具描述，仅显示工具名称。 + - **说明：** 隐藏工具描述，只显示工具名称。 - **`/privacy`** - - **描述：** 显示隐私声明，并允许用户选择是否同意收集其数据以改进服务。 + - **说明：** 显示隐私声明，并允许用户选择是否同意收集他们的数据以改进服务。 - **`/quit-confirm`** - - **描述：** 退出 Qwen Code 前显示确认对话框，让你选择如何处理当前会话。 + - **说明：** 退出 Qwen Code 前显示确认对话框，允许你选择如何处理当前会话。 - **用法：** `/quit-confirm` - - **功能：** + - **功能特性：** - **立即退出：** 不保存任何内容直接退出（等效于 `/quit`） - - **生成摘要并退出：** 使用 `/summary` 创建项目摘要后退出 - - **保存对话并退出：** 使用自动生成的标签保存当前对话后退出 - - **快捷键：** 连续按两次 **Ctrl+C** 触发退出确认对话框 - - **注意：** 此命令在你按一次 Ctrl+C 时自动触发，提供防止意外退出的安全机制。 + - **生成摘要后退出：** 使用 `/summary` 创建项目摘要后再退出 + - **保存对话后退出：** 使用自动生成的标签保存当前对话后再退出 + - **键盘快捷键：** 连续两次按下 **Ctrl+C** 触发退出确认对话框 + - **注意：** 当你单次按下 Ctrl+C 时，此命令会自动触发，作为防止意外退出的安全机制。 - **`/quit`**（或 **`/exit`**） - - **描述：** 立即退出 Qwen Code，不显示任何确认对话框。 + - **说明：** 立即退出 Qwen Code，无需确认对话框。 - **`/vim`** - - **描述：** 切换 vim 模式开/关。启用 vim 模式时，输入区域在 NORMAL 和 INSERT 模式下都支持 vim 风格的导航和编辑命令。 - - **功能：** - - **NORMAL 模式：** 使用 `h`, `j`, `k`, `l` 导航；使用 `w`, `b`, `e` 按单词跳转；使用 `0`, `$`, `^` 跳转到行首/行尾；使用 `G`（或 `gg` 跳转到第一行）跳转到特定行 + - **说明：** 开启或关闭 vim 模式。启用 vim 模式后，输入区域支持 NORMAL 和 INSERT 模式下的 vim 式导航和编辑命令。 + - **功能特性：** + - **NORMAL 模式：** 使用 `h`, `j`, `k`, `l` 移动光标；使用 `w`, `b`, `e` 按单词跳转；使用 `0`, `$`, `^` 跳转行首/尾；使用 `G`（或 `gg` 第一行）跳转指定行 - **INSERT 模式：** 标准文本输入，按 Esc 返回 NORMAL 模式 - - **编辑命令：** 使用 `x` 删除，使用 `c` 更改，使用 `i`, `a`, `o`, `O` 插入；复杂操作如 `dd`, `cc`, `dw`, `cw` - - **计数支持：** 在命令前加数字前缀（如 `3h`, `5w`, `10G`） - - **重复最后命令：** 使用 `.` 重复最后的编辑操作 - - **持久设置：** Vim 模式偏好设置保存到 `~/.qwen/settings.json` 并在会话间恢复 - - **状态指示器：** 启用时在页脚显示 `[NORMAL]` 或 `[INSERT]` + - **编辑命令：** 使用 `x` 删除字符，`c` 修改内容，`i`, `a`, `o`, `O` 插入；支持复杂操作如 `dd`, `cc`, `dw`, `cw` + - **计数支持：** 在命令前加数字（如 `3h`, `5w`, `10G`） + - **重复上次命令：** 使用 `.` 重复上一次编辑操作 + - **持久设置：** Vim 模式偏好保存在 `~/.qwen/settings.json` 并在不同会话之间恢复 + - **状态指示符：** 启用后将在页脚显示 `[NORMAL]` 或 `[INSERT]` - **`/init`** - - **描述：** 分析当前目录并创建一个 `QWEN.md` 上下文文件（或由 `contextFileName` 指定的文件名）。如果已存在非空文件，则不进行任何更改。该命令会初始化一个空文件并提示模型用项目特定的指令填充它。 + - **说明：** 分析当前目录，默认创建名为 `QWEN.md` 的上下文文件（或者由 `contextFileName` 指定的文件名）。如果已有非空文件存在，则不做改动。该命令初始化一个空文件，并提示模型填充项目相关的指令内容。 ### 自定义命令 -快速入门，请参见下方的[示例](#example-a-pure-function-refactoring-command)。 +如需快速上手，请参见下方的[示例](#example-a-pure-function-refactoring-command)。 -自定义命令允许你将最常用或最喜欢的 prompt 保存为 Qwen Code 中的个人快捷方式。你可以创建仅适用于单个项目的命令，也可以创建在所有项目中全局可用的命令，从而简化工作流程并确保一致性。 +自定义命令允许你将最常用或最喜欢的 prompt 保存为个人快捷方式，在 Qwen Code 中重复使用。你可以创建仅适用于单个项目的命令，也可以创建在所有项目中全局可用的命令，从而简化工作流程并确保一致性。 #### 文件位置与优先级 @@ -194,7 +196,7 @@ Qwen Code 从两个位置发现命令，按特定顺序加载： 如果项目目录中的命令与用户目录中的命令同名，则**始终使用项目命令**。这允许项目使用特定于项目的版本覆盖全局命令。 -#### 命名与命名空间 +#### 命令命名与命名空间 命令的名称由其相对于 `commands` 目录的文件路径决定。子目录用于创建带命名空间的命令，路径分隔符（`/` 或 `\`）会被转换为冒号（`:`）。 @@ -207,11 +209,11 @@ Qwen Code 从两个位置发现命令，按特定顺序加载： ##### 必填字段 -- `prompt` (String)：命令执行时发送给模型的 prompt。可以是单行或多行字符串。 +- `prompt` (String): 命令执行时发送给模型的 prompt。可以是单行或多行字符串。 ##### 可选字段 -- `description` (String)：命令功能的简短一行描述。这段文字会显示在 `/help` 菜单中你的命令旁边。**如果你省略此字段，系统会根据文件名自动生成一个通用描述。** +- `description` (String): 命令功能的简短一行描述。这段文字会显示在 `/help` 菜单中你的命令旁边。**如果你省略此字段，系统会根据文件名生成一个通用描述。** #### 处理参数 @@ -231,17 +233,17 @@ Qwen Code 从两个位置发现命令，按特定顺序加载： ```toml -# 调用方式：/git:fix "按钮未对齐" +# 调用方式：/git:fix "Button is misaligned" description = "为给定问题生成修复方案。" prompt = "请为这里描述的问题提供代码修复：{{args}}。" ``` -模型接收到的内容是：`请为这里描述的问题提供代码修复："按钮未对齐"。` +模型接收到：`请为这里描述的问题提供代码修复："Button is misaligned"。` **B. 在 Shell 命令中使用参数（在 `!{...}` 块内）** -当你在 shell 注入块（`!{...}`）中使用 `{{args}}` 时，参数会在替换前自动进行 **shell 转义**。这使得你可以安全地将参数传递给 shell 命令，确保生成的命令语法正确且安全，同时防止命令注入漏洞。 +当你在 shell 注入块（`!{...}`）中使用 `{{args}}` 时，参数会在替换前自动进行 **shell 转义**。这使你可以安全地将参数传递给 shell 命令，确保生成的命令语法正确且安全，同时防止命令注入漏洞。 **示例（`/grep-code.toml`）：** @@ -256,11 +258,11 @@ prompt = """ 当你运行 `/grep-code It's complicated` 时： -1. CLI 检测到 `{{args}}` 同时出现在 `!{...}` 块内外。 +1. CLI 检测到 `{{args}}` 在 `!{...}` 块内外都有使用。 2. 块外：第一个 `{{args}}` 被直接替换为 `It's complicated`。 -3. 块内：第二个 `{{args}}` 被替换为转义后的版本（例如在 Linux 上是 `"It's complicated"`）。 +3. 块内：第二个 `{{args}}` 被替换为转义后的版本（例如在 Linux 上为：`"It's complicated"`）。 4. 实际执行的命令是 `grep -r "It's complicated" .`。 -5. CLI 会提示你确认这个确切且安全的命令后再执行。 +5. CLI 会在执行前提示你确认这个确切且安全的命令。 6. 最终 prompt 被发送出去。 ##### 2. 默认参数处理 @@ -296,6 +298,7 @@ prompt = """ 命令遵循以下格式：`/changelog ` - `` 必须是以下之一："added"、"changed"、"fixed"、"removed"。 +```markdown ## 行为 1. 读取 `CHANGELOG.md` 文件。 2. 找到指定 `` 的部分。 @@ -303,9 +306,9 @@ prompt = """ 4. 如果版本或类型部分不存在，则创建它。 5. 严格遵循 "Keep a Changelog" 格式。 """ -``` 当你运行 `/changelog 1.2.0 added "New feature"` 时，发送给模型的最终文本将是原始 prompt 后跟两个换行符和你输入的命令。 +``` ##### 3. 使用 `!{...}` 执行 Shell 命令 @@ -316,9 +319,9 @@ prompt = """ **工作原理：** 1. **注入命令：** 使用 `!{...}` 语法。 -2. **参数替换：** 如果块内存在 `{{args}}`，它会自动进行 shell 转义（参见上文的 [上下文感知注入](#1-context-aware-injection-with-args)）。 -3. **健壮解析：** 解析器能够正确处理包含嵌套大括号的复杂 shell 命令，例如包含 JSON 数据的命令。 -4. **安全检查与确认：** CLI 会对最终解析后的命令（即参数转义和替换后）执行安全检查。此时会弹出一个对话框，显示即将执行的确切命令。 +2. **参数替换：** 如果块内包含 `{{args}}`，它会自动进行 shell 转义处理（参见上文 [Context-Aware Injection](#1-context-aware-injection-with-args)）。 +3. **健壮解析：** 解析器能够正确处理包含嵌套大括号的复杂 shell 命令，例如包含 JSON 数据的命令。**注意：** `!{...}` 内部的内容必须保持大括号（`{` 和 `}`）的平衡。如果你需要执行包含不平衡括号的命令，建议将其包装在一个外部脚本文件中，并在 `!{...}` 块内调用该脚本。 +4. **安全检查与确认：** CLI 会对最终解析后的命令（即参数转义和替换之后的命令）执行安全检查。系统会弹出一个对话框，显示即将执行的确切命令。 5. **执行与错误报告：** 命令执行后，如果失败，注入到 prompt 中的输出将包含错误信息（stderr），并附带状态行，例如 `[Shell command exited with code 1]`。这有助于模型理解失败的上下文。 **示例 (`git/commit.toml`)：** @@ -343,9 +346,47 @@ prompt = """ """ +```` + +当你运行 `/git:commit` 时，CLI 会首先执行 `git diff --staged` 命令，然后将 `!{git diff --staged}` 替换为该命令的输出结果，最后将完整拼接好的 prompt 发送给模型处理。 + +##### 4. 使用 `@{...}` 注入文件内容 + +你可以使用 `@{...}` 语法将文件内容或目录列表直接嵌入到你的 prompt 中。这对于创建需要操作特定文件的命令非常有用。 + +**工作原理：** + +- **文件注入**：`@{path/to/file.txt}` 会被替换为 `file.txt` 的内容。 +- **多模态支持**：如果路径指向受支持的图像（如 PNG、JPEG）、PDF、音频或视频文件，它将被正确编码并作为多模态输入注入。其他二进制文件会被优雅地处理并跳过。 +- **目录列表**：`@{path/to/dir}` 会被遍历，目录及其所有子目录中的每个文件都会被插入到 prompt 中。如果启用了 `.gitignore` 和 `.qwenignore`，则会遵循这些忽略规则。 +- **工作区感知**：命令会在当前目录和任何其他工作区目录中搜索路径。如果绝对路径在工作区内，则允许使用。 +- **处理顺序**：`@{...}` 的文件内容注入会在 shell 命令 (`!{...}`) 和参数替换 (`{{args}}`) 之前处理。 +- **解析**：解析器要求 `@{...}` 内部的内容（即路径）具有平衡的大括号 (`{` 和 `}`)。 + +**示例 (`review.toml`)：** + +此命令注入一个 _固定_ 的最佳实践文件 (`docs/best-practices.md`) 的内容，并使用用户的参数为 review 提供上下文。 + +```toml + +```markdown +# 文件路径: /.qwen/commands/review.toml + +# 调用方式: /review FileCommandLoader.ts + +description = "使用最佳实践指南审查提供的上下文。" +prompt = """ +你是一位专业的代码审查员。 + +你的任务是审查 {{args}}。 + +在提供审查意见时，请参考以下最佳实践： + +@{docs/best-practices.md} +""" ``` -当你运行 `/git:commit` 时，CLI 会先执行 `git diff --staged`，然后将 `!{git diff --staged}` 替换为该命令的输出结果，最后将完整拼接好的 prompt 发送给模型。 +当你运行 `/review FileCommandLoader.ts` 时，`@{docs/best-practices.md}` 占位符会被该文件的内容替换，`{{args}}` 会被你提供的文本替换，然后最终的 prompt 会被发送给模型。 #### 示例：一个"纯函数"重构命令 @@ -395,29 +436,29 @@ Qwen Code 将会执行你在 TOML 文件中定义的多行 prompt。 ## At 命令 (`@`) -At 命令用于将文件或目录的内容作为 prompt 的一部分发送给模型。这些命令支持 Git 感知过滤。 +At 命令用于将文件或目录的内容包含到你发送给模型的 prompt 中。这些命令支持 Git 感知过滤。 - **`@<文件或目录路径>`** - - **说明：** 将指定文件或多个文件的内容注入到当前 prompt 中。适用于针对特定代码、文本或文件集合进行提问。 + - **说明：** 将指定文件或多个文件的内容注入到当前 prompt 中。这在你需要针对特定代码、文本或一组文件提问时非常有用。 - **示例：** - - `@path/to/your/file.txt Explain this text.` - - `@src/my_project/ Summarize the code in this directory.` - - `What is this file about? @README.md` + - `@path/to/your/file.txt 解释这段文本。` + - `@src/my_project/ 总结这个目录下的代码。` + - `这个文件是做什么的？@README.md` - **详细说明：** - - 如果提供的是单个文件路径，则读取该文件的内容。 - - 如果提供的是目录路径，则尝试读取该目录及其子目录下的所有文件内容。 - - 路径中如果包含空格，需使用反斜杠转义（例如：`@My\ Documents/file.txt`）。 - - 内部使用 `read_many_files` 工具实现。内容会被读取并插入到你的查询中，然后再发送给模型。 - - **Git 感知过滤：** 默认情况下，会排除被 Git 忽略的文件（如 `node_modules/`、`dist/`、`.env`、`.git/`）。可以通过 `fileFiltering` 设置更改此行为。 - - **文件类型：** 该命令主要适用于文本文件。虽然可能会尝试读取任何类型的文件，但二进制文件或非常大的文件可能会被底层的 `read_many_files` 工具跳过或截断，以确保性能和相关性。工具会提示哪些文件被跳过了。 - - **输出：** CLI 会显示一条工具调用消息，表明使用了 `read_many_files`，同时会显示处理状态和所涉及的路径信息。 + - 如果提供的是单个文件路径，则读取该文件内容。 + - 如果提供的是目录路径，则尝试读取该目录及其子目录中的所有文件内容。 + - 路径中如果包含空格，需要用反斜线转义（例如：`@My\ Documents/file.txt`）。 + - 内部使用 `read_many_files` 工具来实现功能。内容会被读取并插入到你的查询中，然后再发送给模型。 + - **Git 感知过滤：** 默认情况下会排除被 Git 忽略的文件（如 `node_modules/`、`dist/`、`.env`、`.git/`）。可以通过 `fileFiltering` 设置更改此行为。 + - **文件类型：** 此命令适用于基于文本的文件。虽然它可能会尝试读取任何类型的文件，但底层的 `read_many_files` 工具为了保证性能和相关性，可能会跳过或截断二进制文件或非常大的文件，并会在输出中标明哪些文件被跳过了。 + - **输出：** CLI 会显示一条工具调用消息，表明已使用了 `read_many_files`，同时还会展示处理状态及所涉及的文件路径信息。 - **`@`（单独的 @ 符号）** - - **说明：** 如果你只输入了一个 `@` 符号而没有指定路径，query 会原样发送给模型。这在你 prompt 中明确讨论 `@` 符号本身时可能有用。 + - **说明：** 如果你在 prompt 中只输入了一个 `@` 符号而没有跟路径，那么整个查询会原样传递给模型。当你确实需要在 prompt 中讨论 `@` 这个符号本身时，这种方式很有用。 ### `@` 命令的错误处理 -- 如果 `@` 后面指定的路径未找到或无效，将显示错误消息，查询可能不会发送到模型，或者会发送但不包含文件内容。 +- 如果 `@` 后面指定的路径未找到或无效，将显示错误信息，查询可能不会发送到模型，或者会发送但不包含文件内容。 - 如果 `read_many_files` 工具遇到错误（例如权限问题），也会报告此错误。 ## Shell 模式和透传命令 (`!`) @@ -425,7 +466,7 @@ At 命令用于将文件或目录的内容作为 prompt 的一部分发送给模 使用 `!` 前缀可以直接在 Qwen Code 中与系统 shell 进行交互。 - **`!`** - - **说明：** 使用 `bash`（Linux/macOS）或 `cmd.exe`（Windows）执行指定的 ``。命令的任何输出或错误都会显示在终端中。 + - **说明：** 使用 Linux/macOS 上的 `bash` 或 Windows 上的 `cmd.exe` 执行给定的 ``。命令的任何输出或错误都会显示在终端中。 - **示例：** - `!ls -la`（执行 `ls -la` 并返回 Qwen Code） - `!git status`（执行 `git status` 并返回 Qwen Code） @@ -433,11 +474,11 @@ At 命令用于将文件或目录的内容作为 prompt 的一部分发送给模 - **`!`（切换 Shell 模式）** - **说明：** 单独输入 `!` 可切换 Shell 模式。 - **进入 Shell 模式：** - - 激活后，Shell 模式会使用不同的颜色和“Shell 模式指示器”。 - - 在 Shell 模式下，你输入的文本将直接作为 shell 命令解释执行。 + - 激活后，Shell 模式会使用不同的颜色和一个“Shell 模式指示器”。 + - 在 Shell 模式下，你输入的文本会被直接解释为 shell 命令。 - **退出 Shell 模式：** - - 退出后，UI 将恢复为标准外观，Qwen Code 的正常行为也将恢复。 + - 退出后，UI 会恢复为标准外观，Qwen Code 的正常行为也会恢复。 -- **所有 `!` 使用注意事项：** 在 Shell 模式下执行的命令具有与你在终端中直接运行时相同的权限和影响。 +- **所有 `!` 使用注意事项：** 在 Shell 模式下执行的命令具有与你在终端中直接运行它们相同的权限和影响。 -- **环境变量：** 当通过 `!` 或 Shell 模式执行命令时，子进程中会设置 `QWEN_CODE=1` 环境变量。这允许脚本或工具检测它们是否从 CLI 中运行。 \ No newline at end of file +- **环境变量：** 当通过 `!` 或在 Shell 模式下执行命令时，子进程环境中会设置 `QWEN_CODE=1` 环境变量。这允许脚本或工具检测它们是否从 CLI 中运行。 \ No newline at end of file diff --git a/website/content/zh/cli/configuration.md b/website/content/zh/cli/configuration.md index ae8a123a..9ece5b6c 100644 --- a/website/content/zh/cli/configuration.md +++ b/website/content/zh/cli/configuration.md @@ -4,37 +4,43 @@ Qwen Code 提供了多种方式来配置其行为，包括环境变量、命令 ## 配置层级 -配置按以下优先级顺序应用（数字越小优先级越低，会被数字越高的覆盖）： +配置按以下优先级顺序应用（较低数字的配置会被较高数字的配置覆盖）： 1. **默认值：** 应用程序内的硬编码默认值。 -2. **用户设置文件：** 当前用户的全局设置。 -3. **项目设置文件：** 项目特定的设置。 -4. **系统设置文件：** 系统范围的设置。 -5. **环境变量：** 系统范围或会话特定的变量，可能从 `.env` 文件加载。 -6. **命令行参数：** 启动 CLI 时传入的值。 +2. **系统默认文件：** 系统范围的默认设置，可被其他设置文件覆盖。 +3. **用户设置文件：** 当前用户的全局设置。 +4. **项目设置文件：** 项目特定的设置。 +5. **系统设置文件：** 系统范围的设置，覆盖所有其他设置文件。 +6. **环境变量：** 系统范围或会话特定的变量，可能从 `.env` 文件加载。 +7. **命令行参数：** 启动 CLI 时传入的值。 ## 配置文件 -Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有三个位置： +Qwen Code 使用 JSON 配置文件来保存持久化设置。这些文件有四个不同的位置： + +- **系统默认配置文件：** + - **路径：** `/etc/qwen-code/system-defaults.json`（Linux）、`C:\ProgramData\qwen-code\system-defaults.json`（Windows）或 `/Library/Application Support/QwenCode/system-defaults.json`（macOS）。可以通过设置环境变量 `QWEN_CODE_SYSTEM_DEFAULTS_PATH` 来覆盖该路径。 + - **作用范围：** 提供系统级别的基础默认配置。这些设置优先级最低，预期会被用户、项目或系统覆盖配置所替代。 - **用户配置文件：** - - **位置：** `~/.qwen/settings.json`（其中 `~` 是你的 home 目录）。 + - **路径：** `~/.qwen/settings.json`（其中 `~` 表示你的主目录）。 - **作用范围：** 应用于当前用户的所有 Qwen Code 会话。 + - **项目配置文件：** - - **位置：** 项目根目录下的 `.qwen/settings.json`。 - - **作用范围：** 仅在从该特定项目运行 Qwen Code 时应用。项目配置会覆盖用户配置。 + - **路径：** 项目根目录下的 `.qwen/settings.json`。 + - **作用范围：** 只在从该项目运行 Qwen Code 时生效。项目配置会覆盖用户配置。 - **系统配置文件：** - - **位置：** `/etc/qwen-code/settings.json`（Linux）、`C:\ProgramData\qwen-code\settings.json`（Windows）或 `/Library/Application Support/QwenCode/settings.json`（macOS）。可以通过 `QWEN_CODE_SYSTEM_SETTINGS_PATH` 环境变量覆盖路径。 - - **作用范围：** 应用于系统上所有用户的 Qwen Code 会话。系统配置会覆盖用户和项目配置。对于企业中的系统管理员来说，这可能有助于控制用户的 Qwen Code 设置。 + - **路径：** `/etc/qwen-code/settings.json`（Linux）、`C:\ProgramData\qwen-code\settings.json`（Windows）或 `/Library/Application Support/QwenCode/settings.json`（macOS）。可以通过设置环境变量 `QWEN_CODE_SYSTEM_SETTINGS_PATH` 来覆盖该路径。 + - **作用范围：** 应用于整个系统中所有用户的 Qwen Code 会话。系统配置会覆盖用户和项目配置。企业中的系统管理员可以使用此文件对用户的 Qwen Code 设置进行统一控制。 -**关于配置中的环境变量说明：** 在你的 `settings.json` 文件中，字符串值可以使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量。这些变量在加载配置时会自动解析。例如，如果你有一个环境变量 `MY_API_TOKEN`，你可以在 `settings.json` 中这样使用它：`"apiKey": "$MY_API_TOKEN"`。 +**关于配置中的环境变量说明：** 在你的 `settings.json` 文件中，字符串值可以使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量。当加载配置时，这些变量将被自动解析。例如，如果你有一个名为 `MY_API_TOKEN` 的环境变量，则可以在 `settings.json` 中这样使用它：`"apiKey": "$MY_API_TOKEN"`。 ### 项目中的 `.qwen` 目录 -除了项目设置文件外，项目的 `.qwen` 目录还可以包含其他与 Qwen Code 运行相关的项目特定文件，例如： +除了项目设置文件之外，项目的 `.qwen` 目录还可以包含其他与 Qwen Code 运行相关的项目特定文件，例如： -- [自定义沙箱配置](#sandboxing)（例如，`.qwen/sandbox-macos-custom.sb`、`.qwen/sandbox.Dockerfile`）。 +- [自定义沙箱配置文件](#sandboxing)（例如：`.qwen/sandbox-macos-custom.sb`、`.qwen/sandbox.Dockerfile`）。 ### `settings.json` 中可用的配置项： @@ -56,41 +62,58 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`fileFiltering`**（对象）： - - **说明：** 控制 @ 命令和文件发现工具的 git-aware 文件过滤行为。 + - **说明：** 控制 @ 命令和文件发现工具中基于 git 的文件过滤行为。 - **默认值：** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` - **属性：** - - **`respectGitIgnore`**（布尔值）：在发现文件时是否遵循 `.gitignore` 的规则。设置为 `true` 时，被 git 忽略的文件（如 `node_modules/`、`dist/`、`.env`）会自动从 @ 命令和文件列表操作中排除。 - - **`enableRecursiveFileSearch`**（布尔值）：在提示中补全 @ 前缀时，是否启用递归搜索当前目录树下的文件名。 + - **`respectGitIgnore`**（布尔值）：在发现文件时是否遵循 `.gitignore` 的规则。当设置为 `true` 时，被 git 忽略的文件（如 `node_modules/`、`dist/`、`.env`）会自动从 @ 命令和文件列表操作中排除。 + - **`enableRecursiveFileSearch`**（布尔值）：在提示中补全 @ 前缀时，是否启用在当前目录树下递归搜索文件名。 + - **`disableFuzzySearch`**（布尔值）：当设置为 `true` 时，禁用文件搜索中的模糊搜索功能，可以在文件数量较多的项目中提升性能。 - **示例：** ```json "fileFiltering": { "respectGitIgnore": true, - "enableRecursiveFileSearch": false + "enableRecursiveFileSearch": false, + "disableFuzzySearch": true } ``` +### 文件搜索性能问题排查 + +如果你在文件搜索（例如使用 `@` 补全）时遇到性能问题，特别是在文件数量非常庞大的项目中，可以尝试以下几种方法（按推荐顺序排列）： + +1. **使用 `.qwenignore`：** 在项目根目录下创建一个 `.qwenignore` 文件，排除那些包含大量你不需要引用的文件的目录（例如构建产物、日志、`node_modules`）。减少需要遍历的文件总数是提升性能最有效的方式。 + +2. **禁用模糊搜索：** 如果忽略文件还不够，你可以在 `settings.json` 中将 `disableFuzzySearch` 设置为 `true` 来禁用模糊搜索。这将使用更简单的非模糊匹配算法，可能会更快。 + +3. **禁用递归文件搜索：** 作为最后的手段，你可以通过将 `enableRecursiveFileSearch` 设置为 `false` 来完全禁用递归文件搜索。这将是最快的选项，因为它避免了对整个项目的递归扫描。但这也意味着你在使用 `@` 补全时需要输入完整的文件路径。 + - **`coreTools`**（字符串数组）： - - **说明：** 允许你指定一组核心工具名称，这些工具将对模型可用。可用于限制内置工具的使用范围。有关核心工具列表，请参见 [Built-in Tools](../core/tools-api.md#built-in-tools)。你也可以为支持该功能的工具（如 `ShellTool`）指定命令级别的限制。例如，`"coreTools": ["ShellTool(ls -l)"]` 将只允许执行 `ls -l` 命令。 - - **默认值：** 所有工具均可使用。 - - **示例：** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]` + - **说明：** 允许你指定一组核心工具名称，这些工具将对模型可用。可用于限制内置工具的集合。有关核心工具列表，请参见 [Built-in Tools](../core/tools-api.md#built-in-tools)。你也可以为支持的工具（如 `ShellTool`）指定命令级别的限制。例如，`"coreTools": ["ShellTool(ls -l)"]` 将只允许执行 `ls -l` 命令。 + - **默认值：** 模型可以使用所有工具。 + - **示例：** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`。 + +- **`allowedTools`**（字符串数组）： + - **默认值：** `undefined` + - **说明：** 一组工具名称，这些工具在调用时将跳过确认对话框。这适用于你信任且经常使用的工具。匹配逻辑与 `coreTools` 相同。 + - **示例：** `"allowedTools": ["ShellTool(git status)"]`。 - **`excludeTools`**（字符串数组）： - - **说明：** 允许你指定一组应从模型中排除的核心工具名称。如果某个工具同时出现在 `excludeTools` 和 `coreTools` 中，则会被排除。你也可以为支持该功能的工具（如 `ShellTool`）指定命令级别的限制。例如，`"excludeTools": ["ShellTool(rm -rf)"]` 将阻止执行 `rm -rf` 命令。 + - **说明：** 允许你指定一组应从模型中排除的核心工具名称。如果某个工具同时出现在 `excludeTools` 和 `coreTools` 中，则会被排除。你也可以为支持的工具（如 `ShellTool`）指定命令级别的限制。例如，`"excludeTools": ["ShellTool(rm -rf)"]` 将阻止执行 `rm -rf` 命令。 - **默认值：** 不排除任何工具。 - - **示例：** `"excludeTools": ["run_shell_command", "findFiles"]` - - **安全提示：** `excludeTools` 中对 `run_shell_command` 的命令限制基于简单的字符串匹配，容易被绕过。此功能**不是安全机制**，不应依赖它来安全执行不受信任的代码。建议使用 `coreTools` 明确指定允许执行的命令。 + - **示例：** `"excludeTools": ["run_shell_command", "findFiles"]`。 + - **安全提示：** `excludeTools` 中对 `run_shell_command` 的命令限制基于简单的字符串匹配，容易被绕过。此功能 **不是安全机制**，不应依赖它来安全执行不受信任的代码。建议使用 `coreTools` 明确选择允许执行的命令。 - **`allowMCPServers`**（字符串数组）： - - **说明：** 允许你指定一组 MCP server 名称，这些 server 将对模型可用。可用于限制连接的 MCP server 范围。注意：如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 - - **默认值：** 所有 MCP server 均可用。 - - **示例：** `"allowMCPServers": ["myPythonServer"]` - - **安全提示：** 此配置基于简单的字符串匹配，MCP server 名称可能被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法自行配置 MCP server。此配置不应被视为严格的安全机制。 + - **说明：** 允许你指定一组 MCP 服务器名称，这些服务器将对模型可用。可用于限制连接的 MCP 服务器集合。注意，如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 + - **默认值：** 模型可以使用所有 MCP 服务器。 + - **示例：** `"allowMCPServers": ["myPythonServer"]`。 + - **安全提示：** 此功能基于 MCP 服务器名称的简单字符串匹配，名称可以被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法自行配置 MCP 服务器。此功能不应被视为严格的安全机制。 - **`excludeMCPServers`**（字符串数组）： - - **说明：** 允许你指定一组应从模型中排除的 MCP server 名称。如果某个 server 同时出现在 `excludeMCPServers` 和 `allowMCPServers` 中，则会被排除。注意：如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 - - **默认值：** 不排除任何 MCP server。 - - **示例：** `"excludeMCPServers": ["myNodeServer"]` - - **安全提示：** 此配置基于简单的字符串匹配，MCP server 名称可能被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法自行配置 MCP server。此配置不应被视为严格的安全机制。 + - **说明：** 允许你指定一组应从模型中排除的 MCP 服务器名称。如果某个服务器同时出现在 `excludeMCPServers` 和 `allowMCPServers` 中，则会被排除。注意，如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 + - **默认值：** 不排除任何 MCP 服务器。 + - **示例：** `"excludeMCPServers": ["myNodeServer"]`。 + - **安全提示：** 此功能基于 MCP 服务器名称的简单字符串匹配，名称可以被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法自行配置 MCP 服务器。此功能不应被视为严格的安全机制。 - **`autoAccept`**（布尔值）： - **说明：** 控制 CLI 是否自动接受并执行被认为是安全的工具调用（例如只读操作），而无需用户明确确认。如果设置为 `true`，CLI 将跳过对安全工具的确认提示。 @@ -108,40 +131,40 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **示例：** `"vimMode": true` - **`sandbox`**（布尔值或字符串）： - - **说明：** 控制是否以及如何使用沙箱执行工具。如果设置为 `true`，Qwen Code 将使用预构建的 `qwen-code-sandbox` Docker 镜像。更多信息请参见 [Sandboxing](#sandboxing)。 + - **说明：** 控制是否以及如何使用沙箱来执行工具。如果设置为 `true`，Qwen Code 将使用预构建的 `qwen-code-sandbox` Docker 镜像。更多信息请参见 [Sandboxing](#sandboxing)。 - **默认值：** `false` - **示例：** `"sandbox": "docker"` - **`toolDiscoveryCommand`**（字符串）： - - **说明：** 定义一个自定义 shell 命令，用于从项目中发现工具。该 shell 命令必须在 `stdout` 上返回一个 [function declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) 的 JSON 数组。工具包装器是可选的。 + - **说明：** **与 Gemini CLI 对齐。** 定义一个自定义 shell 命令，用于从项目中发现工具。该 shell 命令必须在 `stdout` 上返回一个 [function declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) 的 JSON 数组。工具包装器是可选的。 - **默认值：** 空 - **示例：** `"toolDiscoveryCommand": "bin/get_tools"` - **`toolCallCommand`**（字符串）： - - **说明：** 定义一个自定义 shell 命令，用于调用通过 `toolDiscoveryCommand` 发现的特定工具。该 shell 命令必须满足以下条件： + - **说明：** **与 Gemini CLI 对齐。** 定义一个自定义 shell 命令，用于调用通过 `toolDiscoveryCommand` 发现的特定工具。该 shell 命令必须满足以下条件： - 必须将函数 `name`（与 [function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) 中完全一致）作为第一个命令行参数。 - - 必须从 `stdin` 读取 JSON 格式的函数参数，类似于 [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall)。 - - 必须在 `stdout` 上返回 JSON 格式的函数输出，类似于 [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse)。 + - 必须从 `stdin` 读取函数参数（JSON 格式），类似于 [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall)。 + - 必须在 `stdout` 上返回函数输出（JSON 格式），类似于 [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse)。 - **默认值：** 空 - **示例：** `"toolCallCommand": "bin/call_tool"` - **`mcpServers`**（对象）： - - **说明：** 配置一个或多个 Model-Context Protocol (MCP) server 的连接，用于发现和使用自定义工具。Qwen Code 会尝试连接每个配置的 MCP server 以发现可用工具。如果多个 MCP server 提供同名工具，工具名称将加上你在配置中定义的 server 别名前缀（例如 `serverAlias__actualToolName`）以避免冲突。注意：系统可能会为了兼容性而从 MCP 工具定义中剥离某些 schema 属性。必须提供 `command`、`url` 或 `httpUrl` 中的至少一个。如果多个都指定，优先级顺序为 `httpUrl` > `url` > `command`。 + - **说明：** 配置一个或多个 Model-Context Protocol (MCP) 服务器的连接，用于发现和使用自定义工具。Qwen Code 会尝试连接每个配置的 MCP 服务器以发现可用工具。如果多个 MCP 服务器暴露了同名工具，工具名称将加上你在配置中定义的服务器别名前缀（例如 `serverAlias__actualToolName`）以避免冲突。注意，系统可能会为了兼容性而从 MCP 工具定义中剥离某些 schema 属性。至少需要提供 `command`、`url` 或 `httpUrl` 中的一项。如果多个都提供，优先级顺序为 `httpUrl` > `url` > `command`。 - **默认值：** 空 - **属性：** - - **``**（对象）：指定 server 的参数。 - - `command`（字符串，可选）：通过标准 I/O 启动 MCP server 的命令。 + - **``**（对象）：指定服务器的参数。 + - `command`（字符串，可选）：通过标准 I/O 启动 MCP 服务器的命令。 - `args`（字符串数组，可选）：传递给命令的参数。 - - `env`（对象，可选）：为 server 进程设置的环境变量。 - - `cwd`（字符串，可选）：启动 server 的工作目录。 - - `url`（字符串，可选）：使用 Server-Sent Events (SSE) 通信的 MCP server URL。 - - `httpUrl`（字符串，可选）：使用可流式 HTTP 通信的 MCP server URL。 - - `headers`（对象，可选）：发送到 `url` 或 `httpUrl` 的 HTTP headers。 - - `timeout`（数字，可选）：对此 MCP server 请求的超时时间（毫秒）。 - - `trust`（布尔值，可选）：信任此 server 并跳过所有工具调用确认。 - - `description`（字符串，可选）：server 的简要描述，可能用于显示。 - - `includeTools`（字符串数组，可选）：从此 MCP server 包含的工具名称列表。指定后，仅此列表中的工具可用（白名单行为）。未指定时，默认启用 server 的所有工具。 - - `excludeTools`（字符串数组，可选）：从此 MCP server 排除的工具名称列表。即使 server 提供这些工具，模型也无法使用。**注意：** `excludeTools` 优先级高于 `includeTools` —— 如果某个工具同时出现在两个列表中，它将被排除。 + - `env`（对象，可选）：为服务器进程设置的环境变量。 + - `cwd`（字符串，可选）：启动服务器的工作目录。 + - `url`（字符串，可选）：使用 Server-Sent Events (SSE) 通信的 MCP 服务器 URL。 + - `httpUrl`（字符串，可选）：使用可流式 HTTP 通信的 MCP 服务器 URL。 + - `headers`（对象，可选）：发送到 `url` 或 `httpUrl` 的 HTTP 请求头。 + - `timeout`（数字，可选）：对此 MCP 服务器请求的超时时间（毫秒）。 + - `trust`（布尔值，可选）：信任此服务器并跳过所有工具调用确认。 + - `description`（字符串，可选）：服务器的简要描述，可能用于显示。 + - `includeTools`（字符串数组，可选）：从此 MCP 服务器包含的工具名称列表。指定后，仅列出的工具可用（白名单行为）。未指定时，默认启用服务器的所有工具。 + - `excludeTools`（字符串数组，可选）：从此 MCP 服务器排除的工具名称列表。即使服务器暴露了这些工具，模型也无法使用。**注意：** `excludeTools` 优先级高于 `includeTools` —— 如果一个工具同时出现在两个列表中，它将被排除。 - **示例：** ```json "mcpServers": { @@ -183,7 +206,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`checkpointing`**（对象）： - - **说明：** 配置 checkpointing 功能，允许你保存和恢复对话及文件状态。详情请参见 [Checkpointing documentation](../checkpointing.md)。 + - **说明：** 配置检查点功能，允许你保存和恢复对话及文件状态。更多详情请参见 [Checkpointing documentation](../checkpointing.md)。 - **默认值：** `{"enabled": false}` - **属性：** - **`enabled`**（布尔值）：当为 `true` 时，`/restore` 命令可用。 @@ -193,13 +216,13 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **默认值：** `vscode` - **示例：** `"preferredEditor": "vscode"` -- **`telemetry`**（对象）： +- **`telemetry`**（对象） - **说明：** 配置 Qwen Code 的日志和指标收集。更多信息请参见 [Telemetry](../telemetry.md)。 - **默认值：** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **属性：** - **`enabled`**（布尔值）：是否启用遥测。 - **`target`**（字符串）：遥测数据的目标。支持的值为 `local` 和 `gcp`。 - - **`otlpEndpoint`**（字符串）：OTLP Exporter 的 endpoint。 + - **`otlpEndpoint`**（字符串）：OTLP Exporter 的端点。 - **`logPrompts`**（布尔值）：是否在日志中包含用户提示内容。 - **示例：** ```json @@ -210,7 +233,6 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 "logPrompts": false } ``` - - **`usageStatisticsEnabled`**（布尔值）： - **说明：** 启用或禁用使用统计信息的收集。更多信息请参见 [Usage Statistics](#usage-statistics)。 - **默认值：** `true` @@ -223,6 +245,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **说明：** 启用或禁用 CLI 界面中的提示信息。 - **默认值：** `false` - **示例：** + ```json "hideTips": true ``` @@ -231,12 +254,13 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **说明：** 启用或禁用 CLI 界面中的启动横幅（ASCII 艺术 logo）。 - **默认值：** `false` - **示例：** + ```json "hideBanner": true ``` - **`maxSessionTurns`**（数字）： - - **说明：** 设置会话的最大轮数。如果会话超过此限制，CLI 将停止处理并开始新对话。 + - **说明：** 设置会话的最大轮数。如果会话超过此限制，CLI 将停止处理并开始新的聊天。 - **默认值：** `-1`（无限制） - **示例：** ```json @@ -244,7 +268,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`summarizeToolOutput`**（对象）： - - **说明：** 启用或禁用工具输出的摘要功能。你可以使用 `tokenBudget` 设置摘要的 token 预算。 + - **说明：** 启用或禁用工具输出的摘要功能。你可以使用 `tokenBudget` 设置来指定摘要的 token 预算。 - 注意：目前仅支持 `run_shell_command` 工具。 - **默认值：** `{}`（默认禁用） - **示例：** @@ -265,7 +289,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`includeDirectories`**（字符串数组）： - - **说明：** 指定一组额外的绝对或相对路径，将其包含在工作区上下文中。这允许你跨多个目录操作文件，就像它们在一个目录中一样。路径可以使用 `~` 表示用户主目录。此设置可以与 `--include-directories` 命令行标志结合使用。 + - **说明：** 指定要包含在工作区上下文中的额外绝对或相对路径数组。缺失的目录默认会跳过并显示警告。路径可以使用 `~` 引用用户的主目录。此设置可以与 `--include-directories` 命令行标志结合使用。 - **默认值：** `[]` - **示例：** ```json @@ -288,8 +312,14 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **说明：** Tavily 网络搜索服务的 API key。启用 `web_search` 工具功能时必需。如果未配置，网络搜索工具将被禁用并跳过。 - **默认值：** `undefined`（网络搜索禁用） - **示例：** `"tavilyApiKey": "tvly-your-api-key-here"` - -- **`chatCompression`**（ +- **`chatCompression`**（对象）： + - **说明：** 控制聊天历史压缩的设置，包括自动压缩和通过 `/compress` 命令手动触发的压缩。 + - **属性：** + - **`contextPercentageThreshold`**（数字）：介于 0 和 1 之间的值，指定触发压缩的 token 阈值占模型总 token 限制的百分比。例如，值为 `0.6` 时，当聊天历史超过 token 限制的 60% 时将触发压缩。 + - **示例：** + ```json + "chatCompression": { + "contextPercentageThreshold": ### 示例 `settings.json`： @@ -318,6 +348,8 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 "usageStatisticsEnabled": true, "hideTips": false, "hideBanner": false, + "skipNextSpeakerCheck": false, + "skipLoopDetection": false, "maxSessionTurns": 10, "summarizeToolOutput": { "run_shell_command": { @@ -330,7 +362,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 } ``` -## Shell History +## Shell 历史记录 CLI 会保存你运行的 shell 命令历史记录。为了避免不同项目之间的冲突，这些历史记录会存储在用户主目录下的项目特定目录中。 @@ -338,39 +370,39 @@ CLI 会保存你运行的 shell 命令历史记录。为了避免不同项目之 - `` 是根据你的项目根路径生成的唯一标识符。 - 历史记录存储在一个名为 `shell_history` 的文件中。 -## 环境变量 & `.env` 文件 +## 环境变量与 `.env` 文件 -环境变量是配置应用程序的常见方式，尤其适用于敏感信息（如 API keys）或在不同环境中可能变化的设置。关于认证配置，请参考 [Authentication documentation](./authentication.md)，其中涵盖了所有可用的认证方法。 +环境变量是配置应用程序的常见方式，尤其适用于敏感信息（如 API keys）或在不同环境中可能变化的设置。关于认证配置，请参阅 [Authentication documentation](./authentication.md)，其中涵盖了所有可用的认证方法。 CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： 1. 当前工作目录中的 `.env` 文件。 -2. 如果未找到，则向上级目录查找，直到找到 `.env` 文件，或到达项目根目录（以 `.git` 文件夹为标识）或用户主目录。 -3. 如果仍未找到，则查找 `~/.env`（用户主目录下的 `.env` 文件）。 +2. 如果未找到，则向上级目录逐层查找，直到找到 `.env` 文件，或到达项目根目录（通过 `.git` 文件夹识别）或用户主目录。 +3. 如果仍未找到，则尝试加载 `~/.env`（用户主目录下的 `.env` 文件）。 -**环境变量排除：** 某些环境变量（如 `DEBUG` 和 `DEBUG_MODE`）默认会从项目 `.env` 文件中自动排除，以防止干扰 CLI 的行为。来自 `.qwen/.env` 文件的变量永远不会被排除。你可以通过在 `settings.json` 文件中配置 `excludedProjectEnvVars` 来自定义这一行为。 +**环境变量排除机制：** 某些环境变量（如 `DEBUG` 和 `DEBUG_MODE`）默认会从项目 `.env` 文件中自动排除，以避免干扰 CLI 的行为。而 `.qwen/.env` 文件中的变量则永远不会被排除。你可以通过在 `settings.json` 文件中配置 `excludedProjectEnvVars` 来自定义这一行为。 - **`OPENAI_API_KEY`**: - - 多种可用的 [认证方法](./authentication.md) 之一。 + - 多种可用的 [认证方式](./authentication.md) 之一。 - 可在 shell 配置文件（如 `~/.bashrc`、`~/.zshrc`）或 `.env` 文件中设置。 - **`OPENAI_BASE_URL`**: - - 多种可用的 [认证方法](./authentication.md) 之一。 + - 多种可用的 [认证方式](./authentication.md) 之一。 - 可在 shell 配置文件（如 `~/.bashrc`、`~/.zshrc`）或 `.env` 文件中设置。 - **`OPENAI_MODEL`**: - 指定默认使用的 OPENAI 模型。 - 会覆盖硬编码的默认值。 - 示例：`export OPENAI_MODEL="qwen3-coder-plus"` - **`GEMINI_SANDBOX`**: - - 替代 `settings.json` 中的 `sandbox` 设置。 - - 可接受的值包括 `true`、`false`、`docker`、`podman` 或自定义命令字符串。 + - 是 `settings.json` 中 `sandbox` 设置的替代方式。 + - 接受 `true`、`false`、`docker`、`podman` 或自定义命令字符串。 - **`SEATBELT_PROFILE`**（仅 macOS）: - 在 macOS 上切换 Seatbelt（`sandbox-exec`）配置文件。 - - `permissive-open`：（默认）限制写入项目文件夹（及其他少数文件夹，详见 `packages/cli/src/utils/sandbox-macos-permissive-open.sb`），但允许其他操作。 + - `permissive-open`：（默认）限制写入项目目录（及其他少数目录，详见 `packages/cli/src/utils/sandbox-macos-permissive-open.sb`），但允许其他操作。 - `strict`：使用严格配置文件，默认拒绝所有操作。 - - ``：使用自定义配置文件。要定义自定义配置文件，请在项目 `.qwen/` 目录下创建名为 `sandbox-macos-.sb` 的文件（例如 `my-project/.qwen/sandbox-macos-custom.sb`）。 + - ``：使用自定义配置文件。要定义自定义配置文件，请在项目 `.qwen/` 目录下创建名为 `sandbox-macos-.sb` 的文件（例如：`my-project/.qwen/sandbox-macos-custom.sb`）。 - **`DEBUG` 或 `DEBUG_MODE`**（通常由底层库或 CLI 自身使用）: - 设置为 `true` 或 `1` 可启用详细调试日志，有助于排查问题。 - - **注意：** 这些变量默认会从项目 `.env` 文件中自动排除，以防止干扰 CLI 行为。如需为 Qwen Code 特别设置这些变量，请使用 `.qwen/.env` 文件。 + - **注意：** 这些变量默认会从项目 `.env` 文件中自动排除，以避免干扰 CLI 行为。如需为 Qwen Code 设置这些变量，请使用 `.qwen/.env` 文件。 - **`NO_COLOR`**: - 设置任意值可禁用 CLI 中的所有颜色输出。 - **`CLI_TITLE`**: @@ -388,148 +420,153 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： 在运行 CLI 时直接传入的参数可以覆盖该特定会话的其他配置。 -- **`--model `** (**`-m `**): +- **`--model `** (**`-m `**)： - 指定本次会话使用的 Qwen 模型。 - 示例：`npm start -- --model qwen3-coder-plus` -- **`--prompt `** (**`-p `**): - - 用于直接向命令传递 prompt。这将以非交互模式调用 Qwen Code。 -- **`--prompt-interactive `** (**`-i `**): - - 使用提供的 prompt 作为初始输入启动交互式会话。 - - prompt 会在交互式会话中处理，而不是在会话开始前处理。 - - 当从 stdin 管道输入时不能使用。 +- **`--prompt `** (**`-p `**)： + - 直接将 prompt 传递给命令。这将以非交互模式调用 Qwen Code。 +- **`--prompt-interactive `** (**`-i `**)： + - 使用提供的 prompt 作为初始输入启动一个交互式会话。 + - prompt 将在交互式会话中处理，而不是在其之前处理。 + - 当从 stdin 管道输入时不能使用此选项。 - 示例：`qwen -i "explain this code"` -- **`--sandbox`** (**`-s`**): - - 为本次会话启用 sandbox 模式。 -- **`--sandbox-image`**: - - 设置 sandbox 镜像 URI。 -- **`--debug`** (**`-d`**): - - 为本次会话启用 debug 模式，提供更详细的输出信息。 -- **`--all-files`** (**`-a`**): - - 如果设置，则递归地将当前目录中的所有文件作为 prompt 的上下文包含进来。 -- **`--help`** (或 **`-h`**): - - 显示命令行参数的帮助信息。 -- **`--show-memory-usage`**: +- **`--sandbox`** (**`-s`**)： + - 为本次会话启用沙盒模式。 +- **`--sandbox-image`**： + - 设置沙盒镜像 URI。 +- **`--debug`** (**`-d`**)： + - 启用调试模式以获取更详细的输出信息。 +- **`--all-files`** (**`-a`**)： + - 如果设置，则递归地将当前目录中的所有文件包含为 prompt 的上下文。 +- **`--help`**（或 **`-h`**）： + - 显示有关命令行参数的帮助信息。 +- **`--show-memory-usage`**： - 显示当前内存使用情况。 -- **`--yolo`**: +- **`--yolo`**： - 启用 YOLO 模式，自动批准所有工具调用。 -- **`--approval-mode `**: - - 设置工具调用的审批模式。可用模式包括： - - `default`：对每个工具调用提示审批（默认行为） - - `auto_edit`：自动批准编辑类工具（edit、write_file），其他工具仍需提示审批 - - `yolo`：自动批准所有工具调用（等同于 `--yolo`） - - 不能与 `--yolo` 同时使用。请使用 `--approval-mode=yolo` 替代 `--yolo`，以采用新的统一方式。 - - 示例：`qwen --approval-mode auto_edit` -- **`--telemetry`**: - - 启用 [telemetry](../telemetry.md)。 -- **`--telemetry-target`**: - - 设置 telemetry 目标。更多信息请参见 [telemetry](../telemetry.md)。 -- **`--telemetry-otlp-endpoint`**: - - 设置 telemetry 的 OTLP endpoint。更多信息请参见 [telemetry](../telemetry.md)。 -- **`--telemetry-otlp-protocol`**: - - 设置 telemetry 的 OTLP 协议（`grpc` 或 `http`）。默认为 `grpc`。更多信息请参见 [telemetry](../telemetry.md)。 -- **`--telemetry-log-prompts`**: - - 启用 telemetry 的 prompt 日志记录。更多信息请参见 [telemetry](../telemetry.md)。 -- **`--checkpointing`**: - - 启用 [checkpointing](../checkpointing.md)。 -- **`--extensions `** (**`-e `**): - - 指定本次会话要使用的扩展列表。如果未提供，则使用所有可用扩展。 - - 可使用特殊关键字 `qwen -e none` 禁用所有扩展。 +- **`--approval-mode `**： + - 设置工具调用的审批模式。支持以下几种模式： + - `plan`：仅分析，不修改文件或执行命令。 + - `default`：需要对文件编辑或 shell 命令进行审批（默认行为）。 + - `auto-edit`：自动批准编辑类工具（如 edit、write_file），其他工具仍需提示确认。 + - `yolo`：自动批准所有工具调用（等同于 `--yolo`）。 + - 不可与 `--yolo` 同时使用。请改用 `--approval-mode=yolo` 来采用新的统一方式。 + - 示例：`qwen --approval-mode auto-edit` +- **`--allowed-tools `**： + - 工具名称列表（逗号分隔），这些工具将跳过确认对话框。 + - 示例：`qwen --allowed-tools "ShellTool(git status)"` +- **`--telemetry`**： + - 启用 [遥测功能](../telemetry.md)。 +- **`--telemetry-target`**： + - 设置遥测目标。更多信息请参见 [遥测功能](../telemetry.md)。 +- **`--telemetry-otlp-endpoint`**： + - 设置遥测的 OTLP 终端地址。更多信息请参见 [遥测功能](../telemetry.md)。 +- **`--telemetry-otlp-protocol`**： + - 设置遥测的 OTLP 协议（`grpc` 或 `http`）。默认值是 `grpc`。更多信息请参见 [遥测功能](../telemetry.md)。 +- **`--telemetry-log-prompts`**： + - 启用遥测日志记录 prompt 功能。更多信息请参见 [遥测功能](../telemetry.md)。 +- **`--checkpointing`**： + - 启用 [检查点功能](../checkpointing.md)。 +- **`--extensions `** (**`-e `**)： + - 指定本次会话要使用的扩展插件列表。如果未提供，默认使用所有可用扩展。 + - 可通过特殊关键字 `qwen -e none` 禁用所有扩展。 - 示例：`qwen -e my-extension -e my-other-extension` -- **`--list-extensions`** (**`-l`**): - - 列出所有可用扩展并退出。 -- **`--proxy`**: - - 设置 CLI 的代理。 - - 示例：`--proxy http://localhost:7890`。 -- **`--include-directories `**: - - 在工作区中包含额外目录，以支持多目录场景。 - - 可多次指定或使用逗号分隔的值。 - - 最多可添加 5 个目录。 - - 示例：`--include-directories /path/to/project1,/path/to/project2` 或 `--include-directories /path/to/project1 --include-directories /path/to/project2` -- **`--version`**: - - 显示 CLI 的版本。 -- **`--openai-logging`**: - - 启用 OpenAI API 调用的日志记录，便于调试和分析。此标志会覆盖 `settings.json` 中的 `enableOpenAILogging` 设置。 -- **`--tavily-api-key `**: - - 为本次会话设置 Tavily API key，用于启用网页搜索功能。 +- **`--list-extensions`** (**`-l`**)： + - 列出所有可用扩展并退出程序。 +- **`--proxy`**： + - 设置 CLI 所使用的代理服务器。 + - 示例：`--proxy http://localhost:7890` +- **`--include-directories `**： + - 在工作区中添加额外目录以支持多目录项目结构。 + - 支持多次指定或者使用逗号分隔多个路径。 + - 最多允许添加 5 个目录。 + - 示例：`--include-directories /path/to/project1,/path/to/project2` 或者 `--include-directories /path/to/project1 --include-directories /path/to/project2` +- **`--screen-reader`**： + - 启用屏幕阅读器模式以提高无障碍访问体验。 +- **`--version`**： + - 显示 CLI 版本信息。 +- **`--openai-logging`**： + - 启用 OpenAI API 调用的日志记录功能以便调试和分析。此标志优先级高于 `settings.json` 中的 `enableOpenAILogging` 配置项。 +- **`--tavily-api-key `**： + - 为此会话设置用于网页搜索功能的 Tavily API 密钥。 - 示例：`qwen --tavily-api-key tvly-your-api-key-here` ## Context Files (分层指令上下文) -虽然严格来说不是 CLI **行为** 的配置，但 context files（默认为 `QWEN.md`，可通过 `contextFileName` 设置项配置）对于配置 **指令上下文**（也称为 "memory"）至关重要。这个强大的功能允许你向 AI 提供项目特定的指令、编码风格指南或任何相关的背景信息，从而使它的响应更贴合你的需求。CLI 包含 UI 元素，例如页脚中显示已加载 context files 数量的指示器，让你随时了解当前激活的上下文。 +虽然严格来说不是 CLI **行为** 的配置，但 context files（默认为 `QWEN.md`，可通过 `contextFileName` 设置项配置）对于配置**指令上下文**（也称为 "memory"）至关重要。这个强大的功能允许你向 AI 提供项目特定的指令、编码风格指南或任何相关的背景信息，从而使它的响应更贴合你的需求。CLI 包含一些 UI 元素，例如底部显示已加载 context files 数量的指示器，让你随时了解当前激活的上下文。 -- **用途：** 这些 Markdown 文件包含你希望 Qwen 模型在交互过程中了解的指令、指南或上下文信息。系统被设计为分层管理这些指令上下文。 +- **用途：** 这些 Markdown 文件包含你希望 Qwen 模型在交互过程中了解的指令、指南或上下文信息。系统被设计为以分层方式管理这些指令上下文。 -### 示例上下文文件内容 (例如 `QWEN.md`) +### 示例上下文文件内容（例如，`QWEN.md`） -以下是一个位于 TypeScript 项目根目录的上下文文件可能包含的内容概念示例： +以下是一个位于 TypeScript 项目根目录的上下文文件的概念示例： ```markdown -# Project: My Awesome TypeScript Library +# 项目：My Awesome TypeScript Library -## General Instructions: +## 通用说明： -- When generating new TypeScript code, please follow the existing coding style. -- Ensure all new functions and classes have JSDoc comments. -- Prefer functional programming paradigms where appropriate. -- All code should be compatible with TypeScript 5.0 and Node.js 20+. +- 在生成新的 TypeScript 代码时，请遵循现有的代码风格。 +- 确保所有新增的函数和类都包含 JSDoc 注释。 +- 在适当的情况下，优先使用函数式编程范式。 +- 所有代码应兼容 TypeScript 5.0 和 Node.js 20+。 -## Coding Style: +## 代码风格： -- Use 2 spaces for indentation. -- Interface names should be prefixed with `I` (e.g., `IUserService`). -- Private class members should be prefixed with an underscore (`_`). -- Always use strict equality (`===` and `!==`). +- 使用 2 个空格进行缩进。 +- 接口名称应以 `I` 为前缀（例如，`IUserService`）。 +- 类的私有成员应以下划线（`_`）为前缀。 +- 始终使用严格相等（`===` 和 `!==`）。 -## Specific Component: `src/api/client.ts` +## 特定组件：`src/api/client.ts` -- This file handles all outbound API requests. -- When adding new API call functions, ensure they include robust error handling and logging. -- Use the existing `fetchWithRetry` utility for all GET requests. +- 该文件处理所有对外的 API 请求。 +- 在添加新的 API 调用函数时，请确保包含完善的错误处理和日志记录。 +- 所有 GET 请求请使用现有的 `fetchWithRetry` 工具函数。 ``` -```markdown ## 关于依赖项： -- 除非绝对必要，否则应避免引入新的外部依赖项。 -- 如果确实需要新的依赖项，请说明原因。 +- 除非绝对必要，否则应避免引入新的外部依赖。 +- 如果确实需要新依赖，请说明原因。 -``` +```markdown -这个示例展示了如何提供通用的项目背景、特定的编码规范，甚至关于特定文件或组件的说明。你的上下文文件越相关且精确，AI 就越能更好地协助你。我们强烈建议创建项目特定的上下文文件，以建立约定和上下文环境。 +这个示例展示了如何提供通用的项目背景、具体的编码规范，甚至针对特定文件或组件的说明。你的上下文文件越相关且精确，AI 就能更好地为你提供帮助。强烈建议创建项目特定的上下文文件来建立约定和上下文环境。 - **分层加载与优先级：** CLI 通过从多个位置加载上下文文件（例如 `QWEN.md`）实现了一套复杂的分层内存系统。列表中靠后的位置（更具体）的文件内容通常会覆盖或补充靠前位置（更通用）的文件内容。你可以使用 `/memory show` 命令查看确切的拼接顺序和最终上下文。典型的加载顺序如下： 1. **全局上下文文件：** - - 位置：`~/.qwen/`（例如在你的用户主目录下的 `~/.qwen/QWEN.md`）。 - - 范围：为你的所有项目提供默认指令。 + - 路径：`~/.qwen/`（例如在你的用户主目录下的 `~/.qwen/QWEN.md`）。 + - 作用域：为所有项目提供默认指令。 2. **项目根目录及祖先目录的上下文文件：** - - 位置：CLI 会在当前工作目录中查找配置的上下文文件，然后逐级向上搜索每个父目录，直到项目根目录（由 `.git` 文件夹标识）或你的主目录为止。 - - 范围：提供与整个项目或其重要部分相关的上下文。 + - 路径：CLI 会在当前工作目录以及向上每一级父目录中查找配置的上下文文件，直到遇到项目根目录（由 `.git` 文件夹标识）或你的主目录为止。 + - 作用域：提供整个项目或其重要部分相关的上下文。 3. **子目录上下文文件（局部/上下文相关）：** - - 位置：CLI 还会在当前工作目录 _之下_ 的子目录中扫描配置的上下文文件（遵循如 `node_modules`、`.git` 等常见的忽略模式）。默认情况下，此搜索范围限制为 200 个目录，但可以通过在 `settings.json` 文件中设置 `memoryDiscoveryMaxDirs` 字段进行配置。 - - 范围：允许为项目中的特定组件、模块或子部分提供高度具体的指令。 -- **拼接与 UI 提示：** 所有找到的上下文文件内容会被拼接在一起（使用分隔符标明其来源和路径），并作为系统提示的一部分提供给 AI。CLI 的页脚会显示已加载的上下文文件数量，让你快速了解当前激活的指令上下文。 -- **导入内容：** 你可以通过使用 `@path/to/file.md` 语法导入其他 Markdown 文件来模块化你的上下文文件。更多详情请参阅 [Memory Import Processor 文档](../core/memport.md)。 + - 路径：CLI 还会在当前工作目录之下的子目录中搜索配置的上下文文件（遵循如 `node_modules`、`.git` 等常见忽略模式）。默认情况下，此搜索限制为最多 200 个目录，但可以通过在 `settings.json` 文件中设置 `memoryDiscoveryMaxDirs` 字段进行调整。 + - 作用域：允许为项目的某个特定组件、模块或子部分提供高度定制化的指令。 +- **拼接与 UI 提示：** 所有找到的上下文文件内容会被依次拼接（并用分隔符标明来源和路径），作为系统提示的一部分提供给 AI。CLI 的底部会显示已加载的上下文文件数量，让你快速了解当前激活的指令上下文。 +- **导入内容：** 你可以通过使用 `@path/to/file.md` 语法导入其他 Markdown 文件，从而模块化管理你的上下文文件。更多详情请参阅 [Memory Import Processor 文档](../core/memport.md)。 - **内存管理命令：** - 使用 `/memory refresh` 强制重新扫描并从所有配置的位置重新加载所有上下文文件。这将更新 AI 的指令上下文。 - - 使用 `/memory show` 显示当前加载的组合指令上下文，方便你验证 AI 正在使用的层级结构和内容。 - - 有关 `/memory` 命令及其子命令（`show` 和 `refresh`）的完整详情，请参阅 [Commands 文档](./commands.md#memory)。 + - 使用 `/memory show` 显示当前加载的综合指令上下文，方便你确认 AI 正在使用的层级结构和内容。 + - 有关 `/memory` 命令及其子命令（`show` 和 `refresh`）的完整信息，请参阅 [Commands 文档](./commands.md#memory)。 -通过理解并利用这些配置层级以及上下文文件的分层特性，你可以有效地管理 AI 的内存，并根据你的具体需求和项目定制 Qwen Code 的响应。 +通过理解并利用这些配置层级和上下文文件的分层特性，你可以有效地管理 AI 的记忆，并根据你的具体需求和项目定制 Qwen Code 的响应行为。 ## 沙箱机制 Qwen Code 可以在沙箱环境中执行潜在的不安全操作（如 shell 命令和文件修改），以保护你的系统。 -沙箱机制默认是关闭的，但你可以通过以下几种方式启用它： +沙箱机制默认是禁用的，但你可以通过以下几种方式启用它： - 使用 `--sandbox` 或 `-s` 参数。 -- 设置 `GEMI_SANDBOX` 环境变量。 +- 设置 `GEMINI_SANDBOX` 环境变量。 - 当使用 `--yolo` 或 `--approval-mode=yolo` 时，沙箱机制会默认启用。 默认情况下，它会使用预构建的 `qwen-code-sandbox` Docker 镜像。 -如果你的项目有特定的沙箱需求，可以在项目根目录下创建一个自定义的 Dockerfile，路径为 `.qwen/sandbox.Dockerfile`。这个 Dockerfile 可以基于基础沙箱镜像进行构建： +如果你的项目有特定的沙箱需求，可以在项目根目录下创建一个自定义的 Dockerfile，路径为 `.qwen/sandbox.Dockerfile`。这个 Dockerfile 可以基于基础沙箱镜像： ```dockerfile FROM qwen-code-sandbox @@ -552,23 +589,23 @@ BUILD_SANDBOX=1 qwen -s ## 使用统计 -为了帮助我们改进 Qwen Code，我们会收集匿名化的使用统计数据。这些数据帮助我们了解 CLI 的使用情况、识别常见问题并优先开发新功能。 +为了帮助我们改进 Qwen Code，我们会收集匿名化的使用统计数据。这些数据有助于我们了解 CLI 的使用情况、识别常见问题并优先开发新功能。 **我们会收集的数据：** -- **工具调用：** 我们会记录被调用的工具名称、执行成功或失败的状态以及执行耗时。我们不会收集传递给工具的参数或工具返回的任何数据。 -- **API 请求：** 我们会记录每次请求使用的模型、请求耗时以及请求是否成功。我们不会收集 prompt 或 response 的内容。 -- **会话信息：** 我们会收集 CLI 配置相关的信息，例如启用的工具和审批模式。 +- **工具调用信息：** 我们会记录被调用的工具名称、执行成功或失败的状态以及执行耗时。但我们不会收集传递给工具的参数或工具返回的任何数据。 +- **API 请求信息：** 我们会记录每次请求所使用的模型、请求持续时间及是否成功。但我们不会收集 prompt 或 response 的具体内容。 +- **会话信息：** 我们会收集有关 CLI 配置的信息，例如启用的工具和审批模式。 **我们不会收集的数据：** -- **个人身份信息 (PII)：** 我们不会收集任何个人信息，例如你的姓名、邮箱地址或 API key。 -- **Prompt 和 Response 内容：** 我们不会记录你的 prompt 内容或模型返回的 response 内容。 -- **文件内容：** 我们不会记录 CLI 读取或写入的任何文件内容。 +- **个人身份信息（PII）：** 我们不会收集任何个人信息，如您的姓名、电子邮件地址或 API key。 +- **Prompt 和 Response 内容：** 我们不会记录您发送的 prompt 或模型返回的 response 内容。 +- **文件内容：** 我们不会记录 CLI 读取或写入的任何文件的内容。 **如何退出数据收集：** -你可以随时通过在 `settings.json` 文件中将 `usageStatisticsEnabled` 属性设置为 `false` 来退出使用统计收集： +您可以随时通过在 `settings.json` 文件中将 `usageStatisticsEnabled` 属性设置为 `false` 来选择不参与使用统计： ```json { @@ -576,12 +613,12 @@ BUILD_SANDBOX=1 qwen -s } ``` -注意：当启用使用统计时，事件会被发送到阿里云 RUM 收集端点。 +注意：当启用使用统计时，事件会被发送到阿里云 RUM 数据收集端点。 -- **`enableWelcomeBack`** (boolean)： - - **说明：** 当返回到有对话历史的项目时，显示欢迎回来对话框。 +- **`enableWelcomeBack`**（布尔值）： + - **说明：** 当回到一个有对话历史的项目时，显示欢迎回来对话框。 - **默认值：** `true` - **分类：** UI - **需要重启：** 否 - **示例：** `"enableWelcomeBack": false` - - **详情：** 启用后，Qwen Code 会自动检测你是否返回到一个已有项目摘要（`.qwen/PROJECT_SUMMARY.md`）的项目，并显示一个对话框，允许你继续之前的对话或重新开始。此功能与 `/chat summary` 命令和退出确认对话框集成。更多详情请参见 [Welcome Back 文档](./welcome-back.md)。 \ No newline at end of file + - **详细说明：** 启用后，Qwen Code 将自动检测你是否回到了一个已有之前生成的项目摘要（`.qwen/PROJECT_SUMMARY.md`）的项目，并弹出一个对话框让你选择继续之前的对话还是重新开始。此功能与 `/chat summary` 命令和退出确认对话框集成。更多详情请参阅 [Welcome Back 文档](./welcome-back.md)。 \ No newline at end of file diff --git a/website/content/zh/cli/themes.md b/website/content/zh/cli/themes.md index a65779f9..484b6311 100644 --- a/website/content/zh/cli/themes.md +++ b/website/content/zh/cli/themes.md @@ -21,26 +21,28 @@ Qwen Code 内置了一系列预定义主题，你可以在 CLI 中使用 `/theme - `Google Code` - `Xcode` -### 更改主题 +### 更换主题 1. 在 Qwen Code 中输入 `/theme`。 -2. 系统会弹出一个对话框或选择提示，列出所有可用的主题。 +2. 将出现一个对话框或选择提示，列出可用的主题。 3. 使用方向键选择一个主题。某些界面在你选择时可能会提供实时预览或高亮显示。 4. 确认你的选择以应用该主题。 +**注意：** 如果你的 `settings.json` 文件中已定义了某个主题（通过名称或文件路径），则必须先从该文件中移除 `"theme"` 设置，然后才能使用 `/theme` 命令更改主题。 + ### 主题持久化 -选定的主题会保存在 Qwen Code 的 [配置](./configuration.md) 中，这样你的偏好设置会在不同会话间被记住。 +所选主题会保存在 Qwen Code 的 [配置](./configuration.md) 中，这样你的偏好设置会在不同会话之间被记住。 --- ## 自定义颜色主题 -Qwen Code 允许你通过在 `settings.json` 文件中指定来自定义颜色主题。这让你可以完全控制 CLI 中使用的调色板。 +Qwen Code 允许你在 `settings.json` 文件中指定自定义颜色主题。这让你可以完全控制 CLI 中使用的调色板。 ### 如何定义自定义主题 -在你的用户、项目或系统 `settings.json` 文件中添加一个 `customThemes` 块。每个自定义主题都定义为一个具有唯一名称和一组颜色键的对象。例如： +在你的用户、项目或系统级别的 `settings.json` 文件中添加一个 `customThemes` 配置块。每个自定义主题都以一个唯一名称作为 key，值为包含颜色键的对象。例如： ```json { @@ -68,7 +70,7 @@ Qwen Code 允许你通过在 `settings.json` 文件中指定来自定义颜色 } ``` -**颜色键：** +**颜色键说明：** - `Background` - `Foreground` @@ -87,7 +89,7 @@ Qwen Code 允许你通过在 `settings.json` 文件中指定来自定义颜色 **必需属性：** -- `name`（必须与 `customThemes` 对象中的键匹配，且为字符串） +- `name`（必须与 `customThemes` 对象中的 key 相同，且为字符串） - `type`（必须是字符串 `"custom"`） - `Background` - `Foreground` @@ -101,9 +103,49 @@ Qwen Code 允许你通过在 `settings.json` 文件中指定来自定义颜色 - `Comment` - `Gray` -你可以为任何颜色值使用十六进制代码（例如 `#FF0000`）**或**标准 CSS 颜色名称（例如 `coral`、`teal`、`blue`）。有关支持的名称完整列表，请参见 [CSS 颜色名称](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords)。 +你可以使用十六进制颜色码（如 `#FF0000`）**或者**标准 CSS 颜色名称（如 `coral`、`teal`、`blue`）来设置任意颜色值。完整支持的颜色名称列表请参考 [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords)。 + +你可以在 `customThemes` 对象中添加多个条目来定义多个自定义主题。 + +### 从文件加载主题 + +除了在 `settings.json` 中定义自定义主题外，你还可以通过在 `settings.json` 中指定文件路径来直接从 JSON 文件加载主题。这对于分享主题或将主题与主配置分离非常有用。 + +要从文件加载主题，请在 `settings.json` 中将 `theme` 属性设置为你的主题文件路径： + +```json +{ + "theme": "/path/to/your/theme.json" +} +``` + +主题文件必须是有效的 JSON 文件，并且结构与在 `settings.json` 中定义的自定义主题相同。 + +**示例 `my-theme.json`：** + +```json +{ + "name": "My File Theme", + "type": "custom", + "Background": "#282A36", + "Foreground": "#F8F8F2", + "LightBlue": "#82AAFF", + "AccentBlue": "#61AFEF", + "AccentPurple": "#BD93F9", + "AccentCyan": "#8BE9FD", + "AccentGreen": "#50FA7B", + "AccentYellow": "#F1FA8C", + "AccentRed": "#FF5555", + "Comment": "#6272A4", + "Gray": "#ABB2BF", + "DiffAdded": "#A6E3A1", + "DiffRemoved": "#F38BA8", + "DiffModified": "#89B4FA", + "GradientColors": ["#4796E4", "#847ACE", "#C3677F"] +} +``` -你可以通过向 `customThemes` 对象添加更多条目来定义多个自定义主题。 +**安全提示：** 为了你的安全，Gemini CLI 只会加载位于你主目录内的主题文件。如果你尝试从主目录之外加载主题，将会显示警告并且主题不会被加载。这是为了防止从不受信任的来源加载潜在的恶意主题文件。 ### 自定义主题示例 @@ -113,7 +155,7 @@ Qwen Code 允许你通过在 `settings.json` 文件中指定来自定义颜色 - 在 Qwen Code 中使用 `/theme` 命令选择你的自定义主题。你的自定义主题将出现在主题选择对话框中。 - 或者，通过在 `settings.json` 中添加 `"theme": "MyCustomTheme"` 将其设为默认主题。 -- 自定义主题可以在用户、项目或系统级别进行设置，并遵循与其他设置相同的[配置优先级](./configuration.md)规则。 +- 自定义主题可以在用户、项目或系统级别进行设置，并遵循与其他设置相同的 [配置优先级](./configuration.md) 规则。 --- diff --git a/website/content/zh/deployment.md b/website/content/zh/deployment.md index 27daf96b..7b3a6d26 100644 --- a/website/content/zh/deployment.md +++ b/website/content/zh/deployment.md @@ -18,7 +18,7 @@ npm install -g @qwen-code/qwen-code ``` - 然后可以在任意位置运行 CLI： + 然后，可以在任意位置运行 CLI： ```bash qwen @@ -33,15 +33,15 @@ --- -### 2. 在沙箱中运行 (Docker/Podman) +### 2. 在沙箱中运行（Docker/Podman） 为了安全性和隔离性，Qwen Code 可以在容器内运行。这也是 CLI 执行可能产生副作用的工具时的默认方式。 - **直接从 Registry 运行：** - 你可以直接运行已发布的沙箱镜像。这在你只有 Docker 并希望运行 CLI 的环境中非常有用。 + 你可以直接运行已发布的沙箱镜像。这在你只有 Docker 并想运行 CLI 的环境中非常有用。 ```bash # 运行已发布的沙箱镜像 - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.11 ``` - **使用 `--sandbox` 参数：** 如果你已经在本地安装了 Qwen Code（使用上述标准安装方式），你可以指示它在沙箱容器内运行。 @@ -53,7 +53,7 @@ ### 3. 从源码运行（推荐 Qwen Code 贡献者使用） -项目贡献者会希望直接从源码运行 CLI。 +项目贡献者会希望直接从源代码运行 CLI。 - **开发模式：** 此方法提供热重载功能，适用于积极开发阶段。 @@ -61,7 +61,7 @@ # 从仓库根目录运行 npm run start ``` -- **生产模式（链接包）：** +- **生产环境模拟模式（链接包）：** 此方法通过链接本地包来模拟全局安装。适用于在生产工作流中测试本地构建。 ```bash @@ -74,7 +74,7 @@ --- -### 4. 从 GitHub 运行最新的 Qwen Code 提交 +### 4. 运行 GitHub 上最新的 Qwen Code 提交版本 你可以直接从 GitHub 仓库运行最新提交的 Qwen Code 版本。这对于测试仍在开发中的功能非常有用。 @@ -86,7 +86,7 @@ npx https://github.com/QwenLM/qwen-code ## 部署架构 -上述执行方式依赖于以下架构组件和流程： +上述执行方式的实现依赖于以下架构组件和流程： **NPM 包** @@ -95,19 +95,19 @@ Qwen Code 项目是一个 monorepo，会将核心包发布到 NPM registry： - `@qwen-code/qwen-code-core`：后端部分，负责处理逻辑和工具执行。 - `@qwen-code/qwen-code`：面向用户的前端部分。 -在进行标准安装或从源码运行 Qwen Code 时，都会使用到这些包。 +在进行标准安装或从源码运行 Qwen Code 时，都会使用这些包。 **构建与打包流程** -根据不同的分发渠道，会采用两种不同的构建流程： +根据分发渠道的不同，有两种不同的构建流程： -- **NPM 发布：** 在发布到 NPM registry 时，`@qwen-code/qwen-code-core` 和 `@qwen-code/qwen-code` 中的 TypeScript 源码会通过 TypeScript Compiler（`tsc`）被编译为标准 JavaScript。最终生成的 `dist/` 目录会被发布为 NPM 包。这是 TypeScript 库的标准发布方式。 +- **NPM 发布**：当发布到 NPM registry 时，`@qwen-code/qwen-code-core` 和 `@qwen-code/qwen-code` 中的 TypeScript 源码会通过 TypeScript Compiler（`tsc`）被转译为标准 JavaScript。最终生成的 `dist/` 目录会被发布为 NPM 包。这是 TypeScript 库的标准做法。 -- **GitHub `npx` 执行：** 当直接从 GitHub 运行最新版本的 Qwen Code 时，`package.json` 中的 `prepare` 脚本会触发另一个构建流程。该脚本使用 `esbuild` 将整个应用及其依赖项打包成一个独立的 JavaScript 文件。这个 bundle 是在用户机器上即时生成的，并不会被提交到代码仓库中。 +- **GitHub `npx` 执行**：当你直接从 GitHub 运行最新版本的 Qwen Code 时，`package.json` 中的 `prepare` 脚本会触发一个不同的构建过程。该脚本使用 `esbuild` 将整个应用及其依赖项打包成一个独立的 JavaScript 文件。这个 bundle 是在用户机器上即时生成的，并不会提交到代码仓库中。 **Docker 沙箱镜像** -基于 Docker 的执行方式由 `qwen-code-sandbox` 容器镜像支持。该镜像会被发布到容器镜像仓库，其中包含了预装的全局版本的 Qwen Code。 +基于 Docker 的执行方式由 `qwen-code-sandbox` 容器镜像支持。该镜像会发布到容器注册中心，其中包含了预装好的全局版 Qwen Code。 ## 发布流程 diff --git a/website/content/zh/examples/proxy-script.md b/website/content/zh/examples/proxy-script.md index 3e8a4b68..4742ad05 100644 --- a/website/content/zh/examples/proxy-script.md +++ b/website/content/zh/examples/proxy-script.md @@ -1,6 +1,6 @@ # 示例代理脚本 -以下是一个可以与 `GEMINI_SANDBOX_PROXY_COMMAND` 环境变量一起使用的代理脚本示例。该脚本只允许 `HTTPS` 连接到 `example.com:443`，并拒绝所有其他请求。 +以下是一个可以与 `GEMINI_SANDBOX_PROXY_COMMAND` 环境变量一起使用的代理脚本示例。该脚本只允许到 `example.com:443` 的 `HTTPS` 连接，拒绝所有其他请求。 ```javascript #!/usr/bin/env node @@ -11,21 +11,21 @@ * SPDX-License-Identifier: Apache-2.0 */ -// 示例代理服务器监听 :::8877，只允许 HTTPS 连接到 example.com。 +// 示例代理服务器监听 :::8877，仅允许 HTTPS 连接到 example.com。 // 设置 `GEMINI_SANDBOX_PROXY_COMMAND=scripts/example-proxy.js` 来在沙箱中运行代理 -// 在沙箱中通过 `curl https://example.com` 测试（在 shell 模式下或通过 shell 工具） +// 在沙箱内通过 `curl https://example.com` 测试（在 shell 模式下或通过 shell 工具） -import http from 'http'; -import net from 'net'; -import { URL } from 'url'; -import console from 'console'; +import http from 'node:http'; +import net from 'node:net'; +import { URL } from 'node:url'; +import console from 'node:console'; const PROXY_PORT = 8877; const ALLOWED_DOMAINS = ['example.com', 'googleapis.com']; const ALLOWED_PORT = '443'; const server = http.createServer((req, res) => { - // 拒绝所有非 CONNECT 的 HTTPS 请求 + // 拒绝除 CONNECT 外的所有非 HTTPS 请求 console.log( `[PROXY] Denying non-CONNECT request for: ${req.method} ${req.url}`, ); @@ -34,7 +34,7 @@ const server = http.createServer((req, res) => { }); server.on('connect', (req, clientSocket, head) => { - // req.url 对于 CONNECT 请求来说格式是 "hostname:port" + // req.url 对于 CONNECT 请求来说是 "hostname:port" 格式 const { port, hostname } = new URL(`http://${req.url}`); console.log(`[PROXY] Intercepted CONNECT request for: ${hostname}:${port}`); @@ -50,7 +50,7 @@ server.on('connect', (req, clientSocket, head) => { // 建立到原始目标的 TCP 连接 const serverSocket = net.connect(port, hostname, () => { clientSocket.write('HTTP/1.1 200 Connection Established\r\n\r\n'); - // 通过在客户端和目标服务器之间传输数据来创建隧道 + // 通过在客户端和目标服务器之间传输数据创建隧道 serverSocket.write(head); serverSocket.pipe(clientSocket); clientSocket.pipe(serverSocket); diff --git a/website/content/zh/extension.md b/website/content/zh/extension.md index a7afaffc..af1ad521 100644 --- a/website/content/zh/extension.md +++ b/website/content/zh/extension.md @@ -9,7 +9,7 @@ Qwen Code 支持扩展，可用于配置和扩展其功能。 1. `/.qwen/extensions` 2. `/.qwen/extensions` -Qwen Code 会从这两个位置加载所有扩展。如果两个位置存在同名扩展，则工作区目录中的扩展优先级更高。 +Qwen Code 会从这两个位置加载所有扩展。如果两个位置存在同名的扩展，则工作区目录中的扩展会优先加载。 在每个位置中，单个扩展以包含 `qwen-extension.json` 文件的目录形式存在。例如： @@ -33,17 +33,17 @@ Qwen Code 会从这两个位置加载所有扩展。如果两个位置存在同 } ``` -- `name`：扩展的名称。用于唯一标识扩展，并在扩展命令与用户或项目命令同名时进行冲突处理。 +- `name`：扩展的名称。用于唯一标识扩展，并在扩展命令与用户或项目命令重名时进行冲突处理。 - `version`：扩展的版本。 -- `mcpServers`：需要配置的 MCP 服务器映射。键为服务器名称，值为服务器配置。这些服务器将在启动时加载，就像在 [`settings.json` 文件](./cli/configuration.md) 中配置的 MCP 服务器一样。如果扩展和 `settings.json` 文件都配置了同名的 MCP 服务器，则以 `settings.json` 文件中定义的服务器为准。 -- `contextFileName`：包含扩展上下文的文件名。将用于从工作区加载上下文。如果未指定此属性，但扩展目录中存在 `QWEN.md` 文件，则会自动加载该文件。 -- `excludeTools`：要从模型中排除的工具名称数组。你还可以对支持该功能的工具（如 `run_shell_command`）指定命令级别的限制。例如，`"excludeTools": ["run_shell_command(rm -rf)"]` 将阻止执行 `rm -rf` 命令。 +- `mcpServers`：需要配置的 MCP server 映射。键为 server 名称，值为对应的 server 配置。这些 servers 会在启动时加载，就像在 [`settings.json` 文件](./cli/configuration.md) 中配置的 MCP servers 一样。如果某个 server 在扩展和 `settings.json` 中都被定义了，则以 `settings.json` 中的配置为准。 +- `contextFileName`：包含扩展上下文内容的文件名。系统将使用此文件从 workspace 中加载上下文。如果未指定该属性，但扩展目录中存在 `QWEN.md` 文件，则会自动加载该文件。 +- `excludeTools`：要从模型中排除的工具名称数组。你也可以对支持命令级限制的工具（如 `run_shell_command`）指定具体命令限制。例如，`"excludeTools": ["run_shell_command(rm -rf)"]` 将阻止执行 `rm -rf` 命令。 -当 Qwen Code 启动时，它会加载所有扩展并合并它们的配置。如果存在任何冲突，工作区配置将具有更高的优先级。 +当 Qwen Code 启动时，它会加载所有扩展并合并它们的配置。如果有任何配置冲突，workspace 中的配置优先级更高。 ## 扩展命令 -扩展可以通过在扩展目录内的 `commands/` 子目录中放置 TOML 文件来提供 [自定义命令](./cli/commands.md#custom-commands)。这些命令遵循与用户和项目自定义命令相同的格式，并使用标准命名约定。 +扩展可以通过在扩展目录内的 `commands/` 子目录中放置 TOML 文件来提供[自定义命令](./cli/commands.md#custom-commands)。这些命令遵循与用户和项目自定义命令相同的格式，并使用标准命名约定。 ### 示例 @@ -65,12 +65,36 @@ Qwen Code 会从这两个位置加载所有扩展。如果两个位置存在同 ### 冲突解决 -Extension commands 的优先级最低。当与 user 或 project commands 发生冲突时： +Extension commands 的优先级最低。当与用户或项目 commands 发生冲突时： 1. **无冲突**：Extension command 使用其自然名称（例如，`/deploy`） 2. **有冲突**：Extension command 会以 extension 前缀重命名（例如，`/gcp.deploy`） -例如，如果 user 和 `gcp` extension 都定义了一个 `deploy` command： +举个例子，如果用户和 `gcp` extension 都定义了一个 `deploy` command： -- `/deploy` - 执行 user 的 deploy command -- `/gcp.deploy` - 执行 extension 的 deploy command（标记为 `[gcp]` tag） \ No newline at end of file +- `/deploy` - 执行用户的 deploy command +- `/gcp.deploy` - 执行 extension 的 deploy command（标记为 `[gcp]` tag） + +## 安装 Extensions + +你可以使用 `install` command 来安装 extensions。该 command 允许你从 Git repository 或本地路径安装 extensions。 + +### 用法 + +`qwen extensions install | [options]` + +### 选项 + +- `source positional argument`：Git 仓库的 URL，用于安装扩展。该仓库的根目录下必须包含一个 `qwen-extension.json` 文件。 +- `--path `：本地目录的路径，用于安装为扩展。该目录下必须包含一个 `qwen-extension.json` 文件。 + +# 变量 + +Qwen Code 扩展支持在 `qwen-extension.json` 中使用变量替换。例如，如果你需要使用当前目录来运行一个 MCP 服务器，可以这样写：`"cwd": "${extensionPath}${/}run.ts"`。 + +**支持的变量：** + +| 变量 | 描述 | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `${extensionPath}` | 扩展在用户文件系统中的完整路径，例如：'/Users/username/.qwen/extensions/example-extension'。该路径不会解析符号链接。 | +| `${/} or ${pathSeparator}` | 路径分隔符（因操作系统而异）。 | \ No newline at end of file diff --git a/website/content/zh/gemini-ignore.md b/website/content/zh/gemini-ignore.md index 28d8b50e..eeab8982 100644 --- a/website/content/zh/gemini-ignore.md +++ b/website/content/zh/gemini-ignore.md @@ -2,21 +2,21 @@ 本文档概述了 Qwen Code 的 Gemini Ignore（`.geminiignore`）功能。 -Qwen Code 支持自动忽略文件，类似于 Git 使用的 `.gitignore` 和 Gemini Code Assist 使用的 `.aiexclude`。将路径添加到你的 `.geminiignore` 文件中，可以将这些路径排除在支持此功能的工具之外，但这些文件对其他服务（如 Git）仍然可见。 +Qwen Code 支持自动忽略文件，类似于 Git 使用的 `.gitignore` 和 Gemini Code Assist 使用的 `.aiexclude`。将路径添加到你的 `.geminiignore` 文件中，可以将这些路径从支持此功能的工具中排除，但这些文件对其他服务（如 Git）仍然可见。 ## 工作原理 -当你在 `.geminiignore` 文件中添加路径时，支持该文件的工具会在操作中自动排除匹配的文件和目录。例如，当你使用 [`read_many_files`](./tools/multi-file.md) 命令时，所有在 `.geminiignore` 文件中定义的路径都会被自动忽略。 +当你在 `.geminiignore` 文件中添加路径时，支持该文件的工具会在其操作中自动排除匹配的文件和目录。例如，当你使用 [`read_many_files`](./tools/multi-file.md) 命令时，所有在 `.geminiignore` 文件中定义的路径都会被自动忽略。 -大部分情况下，`.geminiignore` 遵循与 `.gitignore` 文件相同的规则： +大多数情况下，`.geminiignore` 遵循与 `.gitignore` 文件相同的规则： - 空行以及以 `#` 开头的行会被忽略。 - 支持标准的通配符模式（如 `*`、`?` 和 `[]`）。 - 路径末尾加上 `/` 表示只匹配目录。 -- 路径开头加上 `/` 表示该路径是相对于 `.geminiignore` 文件的位置。 -- 使用 `!` 可以对模式进行取反。 +- 路径开头加上 `/` 表示从 `.geminiignore` 文件所在位置开始锚定匹配路径。 +- 使用 `!` 可对模式进行取反操作。 -你可以随时更新 `.geminiignore` 文件。要使更改生效，需要重启你的 Qwen Code 会话。 +你可以随时更新 `.geminiignore` 文件。要使更改生效，必须重启你的 Qwen Code 会话。 ## 如何使用 `.geminiignore` @@ -35,10 +35,10 @@ Qwen Code 支持自动忽略文件，类似于 Git 使用的 `.gitignore` 和 Ge ``` -# 排除你的 /packages/ 目录及其所有子目录 +# 排除 /packages/ 目录及其所有子目录 /packages/ -# 排除你的 apikeys.txt 文件 +# 排除 apikeys.txt 文件 apikeys.txt ``` diff --git a/website/content/zh/ide-integration.md b/website/content/zh/ide-integration.md index e5369036..37157284 100644 --- a/website/content/zh/ide-integration.md +++ b/website/content/zh/ide-integration.md @@ -1,23 +1,23 @@ # IDE 集成 -Qwen Code 可以与你的 IDE 集成，提供更无缝且具备上下文感知的体验。通过这种集成，CLI 能够更好地理解你的工作区，并支持强大的功能，例如编辑器内的原生 diff 对比。 +Qwen Code 可以与你的 IDE 集成，提供更无缝且具备上下文感知的体验。这种集成使 CLI 能够更好地理解你的工作区，并支持强大的功能，例如编辑器内的原生 diff 功能。 目前，唯一支持的 IDE 是 [Visual Studio Code](https://code.visualstudio.com/) 以及其他支持 VS Code 扩展的编辑器。 ## 功能特性 -- **工作区上下文感知：** CLI 会自动感知你的工作区信息，从而提供更相关和准确的响应。上下文信息包括： - - 你工作区中**最近访问的 10 个文件**。 +- **工作区上下文感知：** CLI 能自动识别你当前的工作区，从而提供更相关、准确的响应。该上下文包括： + - 当前工作区中**最近访问的 10 个文件**。 - 你当前的光标位置。 - 你选中的文本（最多 16KB，超出部分将被截断）。 -- **原生 Diff 支持：** 当 Qwen 建议代码修改时，你可以在 IDE 的原生 diff 查看器中直接查看变更内容。这样你可以方便地审查、编辑，并接受或拒绝建议的修改。 +- **原生 Diff 支持：** 当 Qwen 建议代码修改时，你可以直接在 IDE 的原生 diff 查看器中查看变更内容。这样你可以方便地审阅、编辑，并接受或拒绝建议的更改。 -- **VS Code 命令支持：** 你可以通过 VS Code 命令面板（`Cmd+Shift+P` 或 `Ctrl+Shift+P`）直接访问 Qwen Code 的功能： +- **VS Code 命令支持：** 你可以通过 VS Code 命令面板（`Cmd+Shift+P` 或 `Ctrl+Shift+P`）直接调用 Qwen Code 的功能： - `Qwen Code: Run`：在集成终端中启动一个新的 Qwen Code 会话。 - - `Qwen Code: Accept Diff`：接受当前 diff 编辑器中的修改。 - - `Qwen Code: Close Diff Editor`：拒绝修改并关闭当前 diff 编辑器。 - - `Qwen Code: View Third-Party Notices`：显示该扩展的第三方声明信息。 + - `Qwen Code: Accept Diff`：接受当前 diff 编辑器中的更改。 + - `Qwen Code: Close Diff Editor`：拒绝更改并关闭当前 diff 编辑器。 + - `Qwen Code: View Third-Party Notices`：显示该插件使用的第三方声明信息。 ## 安装与设置 @@ -25,45 +25,48 @@ Qwen Code 可以与你的 IDE 集成，提供更无缝且具备上下文感知 ### 1. 自动提示（推荐） -当你在支持的编辑器中运行 Qwen Code 时，它会自动检测你的环境并提示你进行连接。选择 "Yes" 后，系统将自动运行必要的设置步骤，包括安装配套扩展并启用连接。 +当你在支持的编辑器中运行 Qwen Code 时，它会自动检测你的环境并提示你进行连接。选择 "Yes" 后，系统将自动运行必要的设置流程，包括安装配套扩展并启用连接。 ### 2. 通过 CLI 手动安装 -如果你之前关闭了提示，或者想手动安装扩展，可以在 Qwen Code 中运行以下命令： +如果你之前关闭了提示框，或者希望手动安装扩展，可以在 Qwen Code 中运行以下命令： ``` /ide install ``` -该命令会自动找到适合你 IDE 的扩展并进行安装。 +该命令会自动找到适合你当前 IDE 的扩展并完成安装。 ### 3. 从 Marketplace 手动安装 你也可以直接从 marketplace 安装这个 extension。 - **对于 Visual Studio Code：** 从 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion) 安装。 -- **对于 VS Code Forks：** 为了支持 VS Code 的 fork 版本，该 extension 也发布在 [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion) 上。请根据你所使用编辑器的说明，从该 registry 安装 extension。 +- **对于 VS Code Forks：** 为了支持 VS Code 的 fork 版本，该 extension 也发布在 [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion) 上。请按照你所使用编辑器的说明，从该 registry 安装 extension。 -无论使用哪种安装方式，安装完成后建议打开一个新的 terminal 窗口，以确保集成正确激活。安装完成后，你可以使用 `/ide enable` 来连接。 +> 注意： +> "Qwen Code Companion" extension 可能会出现在搜索结果的底部。如果你没有立即看到它，可以尝试向下滚动或按“最新发布”排序。 +> +> 手动安装 extension 后，你必须在 CLI 中运行 `/ide enable` 来激活集成。 ### 启用和禁用 你可以通过 CLI 控制 IDE 集成： -- 要启用与 IDE 的连接，运行： +- 要启用与 IDE 的连接，请运行： ``` /ide enable ``` -- 要禁用连接，运行： +- 要禁用连接，请运行： ``` /ide disable ``` -启用后，Qwen Code 将自动尝试连接到 IDE companion 扩展。 +启用后，Qwen Code 将自动尝试连接到 IDE companion extension。 ### 检查状态 -要检查连接状态并查看 CLI 从 IDE 接收到的上下文信息，运行： +要检查连接状态并查看 CLI 从 IDE 接收到的上下文信息，请运行： ``` /ide status @@ -71,36 +74,36 @@ Qwen Code 可以与你的 IDE 集成，提供更无缝且具备上下文感知 如果已连接，该命令将显示所连接的 IDE 以及它感知到的最近打开的文件列表。 -（注意：文件列表仅限于工作区内最近访问的 10 个文件，且只包含磁盘上的本地文件。） +（注意：文件列表仅限于工作区中最近访问的 10 个文件，并且只包含磁盘上的本地文件。） ### 使用 Diff -当你请求 Gemini 修改文件时，它可以在你的编辑器中直接打开一个 diff 视图。 +当你要求 Qwen 模型修改文件时，它可以直接在你的编辑器中打开一个 diff 视图。 **要接受一个 diff**，你可以执行以下任意操作： - 点击 diff 编辑器标题栏中的 **对勾图标**。 - 保存文件（例如使用 `Cmd+S` 或 `Ctrl+S`）。 -- 打开 Command Palette 并运行 **Qwen Code: Accept Diff**。 -- 在 CLI 提示时回复 `yes`。 +- 打开命令面板并运行 **Qwen Code: Accept Diff**。 +- 在 CLI 中提示时回复 `yes`。 **要拒绝一个 diff**，你可以： - 点击 diff 编辑器标题栏中的 **'x' 图标**。 - 关闭 diff 编辑器标签页。 -- 打开 Command Palette 并运行 **Qwen Code: Close Diff Editor**。 -- 在 CLI 提示时回复 `no`。 +- 打开命令面板并运行 **Qwen Code: Close Diff Editor**。 +- 在 CLI 中提示时回复 `no`。 你也可以在 **接受之前直接在 diff 视图中修改建议的更改**。 -如果你在 CLI 中选择了 ‘Yes, allow always’，更改将不再在 IDE 中显示，因为它们会被自动接受。 +如果你在 CLI 中选择‘Yes, allow always’，更改将不再在 IDE 中显示，因为它们会被自动接受。 ## 在沙箱环境中使用 如果你在沙箱环境中使用 Qwen Code，请注意以下事项： -- **在 macOS 上：** IDE 集成需要网络访问权限来与 IDE companion 扩展通信。你必须使用允许网络访问的 Seatbelt 配置文件。 -- **在 Docker 容器中：** 如果你在 Docker（或 Podman）容器内运行 Qwen Code，IDE 集成仍然可以连接到运行在宿主机上的 VS Code 扩展。CLI 已配置为自动在 `host.docker.internal` 上查找 IDE 服务器。通常不需要特殊配置，但你可能需要确保 Docker 网络设置允许从容器到宿主机的连接。 +- **在 macOS 上：** IDE 集成需要网络访问权限来与 IDE companion extension 通信。你必须使用允许网络访问的 Seatbelt 配置文件。 +- **在 Docker 容器中：** 如果你在 Docker（或 Podman）容器内运行 Qwen Code，IDE 集成仍然可以连接到运行在宿主机上的 VS Code extension。CLI 已配置为自动在 `host.docker.internal` 上查找 IDE server。通常不需要特殊配置，但你可能需要确保 Docker 网络设置允许从容器到宿主机的连接。 ## 故障排除 @@ -112,7 +115,7 @@ Qwen Code 可以与你的 IDE 集成，提供更无缝且具备上下文感知 - **原因：** Qwen Code 无法找到连接 IDE 所需的环境变量（`QWEN_CODE_IDE_WORKSPACE_PATH` 或 `QWEN_CODE_IDE_SERVER_PORT`）。这通常意味着 IDE companion 扩展未运行或未正确初始化。 - **解决方案：** 1. 确保你已在 IDE 中安装并启用了 **Qwen Code Companion** 扩展。 - 2. 在你的 IDE 中打开一个新的 terminal 窗口，以确保它能获取到正确的环境变量。 + 2. 在 IDE 中打开一个新的 terminal 窗口，以确保它能获取到正确的环境变量。 - **错误信息：** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` - **原因：** 与 IDE companion 的连接意外中断。 @@ -121,19 +124,19 @@ Qwen Code 可以与你的 IDE 集成，提供更无缝且具备上下文感知 ### 配置错误 - **错误信息：** `🔴 Disconnected: Directory mismatch. Qwen Code is running in a different location than the open workspace in [IDE Name]. Please run the CLI from the same directory as your project's root folder.` - - **原因：** CLI 的当前工作目录不在你 IDE 中打开的文件夹或工作区中。 - - **解决方案：** 使用 `cd` 命令进入与你在 IDE 中打开的目录相同的路径，然后重新启动 CLI。 + - **原因：** CLI 的当前工作目录与你在 [IDE Name] 中打开的文件夹或 workspace 不一致。 + - **解决方案：** 使用 `cd` 命令进入与你在 IDE 中打开的相同目录，然后重新启动 CLI。 -- **错误信息：** `🔴 Disconnected: To use this feature, please open a single workspace folder in [IDE Name] and try again.` - - **原因：** 你在 IDE 中打开了多个工作区文件夹，或者根本没有打开任何文件夹。IDE 集成需要一个单一的根工作区文件夹才能正常运行。 - - **解决方案：** 在你的 IDE 中打开一个单一的项目文件夹，然后重新启动 CLI。 +- **错误信息：** `🔴 Disconnected: To use this feature, please open a workspace folder in [IDE Name] and try again.` + - **原因：** 你当前在 IDE 中没有打开任何 workspace。 + - **解决方案：** 在你的 IDE 中打开一个 workspace，然后重新启动 CLI。 ### 通用错误 - **错误信息：** `IDE integration is not supported in your current environment. To use this feature, run Qwen Code in one of these supported IDEs: [List of IDEs]` - **原因：** 你当前在 terminal 或者不支持的 IDE 环境中运行 Qwen Code。 - - **解决方案：** 请从受支持的 IDE（如 VS Code）的 integrated terminal 中运行 Qwen Code。 + - **解决方案：** 请从受支持的 IDE（如 VS Code）的集成 terminal 中运行 Qwen Code。 -- **错误信息：** `No installer is available for [IDE Name]. Please install the IDE companion manually from its marketplace.` - - **原因：** 你执行了 `/ide install`，但 CLI 没有为你使用的 IDE 提供自动安装程序。 - - **解决方案：** 打开你的 IDE 的 extension marketplace，搜索 "Qwen Code Companion"，然后手动安装。 \ No newline at end of file +- **错误信息：** `No installer is available for IDE. Please install the Qwen Code Companion extension manually from the marketplace.` + - **原因：** 你执行了 `/ide install`，但 CLI 没有为你当前使用的 IDE 提供自动安装器。 + - **解决方案：** 打开你的 IDE 的 extension marketplace，搜索 "Qwen Code Companion"，然后手动安装该插件。 \ No newline at end of file diff --git a/website/content/zh/index.md b/website/content/zh/index.md index 5aff2ff0..c2283155 100644 --- a/website/content/zh/index.md +++ b/website/content/zh/index.md @@ -1,22 +1,22 @@ # 欢迎阅读 Qwen Code 文档 -本文档提供了安装、使用和开发 Qwen Code 的完整指南。该工具允许你通过命令行界面与 AI 模型进行交互。 +本文档提供了安装、使用和开发 Qwen Code 的全面指南。该工具允许你通过命令行界面与 AI 模型进行交互。 ## 概述 -Qwen Code 将先进的代码模型能力带入你的终端，提供交互式的 Read-Eval-Print Loop (REPL) 环境。Qwen Code 由一个客户端应用 (`packages/cli`) 和一个本地 server (`packages/core`) 组成。Qwen Code 还包含多种工具，用于执行文件系统操作、运行 shell 命令和网络请求等任务，这些工具由 `packages/core` 管理。 +Qwen Code 将先进的代码模型能力带入你的终端，提供交互式的 Read-Eval-Print Loop (REPL) 环境。Qwen Code 由一个客户端应用（`packages/cli`）组成，它与本地服务器（`packages/core`）通信。Qwen Code 还包含多种工具，用于执行文件系统操作、运行 shell 和网络获取等任务，这些工具由 `packages/core` 管理。 ## 浏览文档 -本文档分为以下几个部分： +本文档组织如下： -- **[执行与部署](./deployment.md)：** 关于如何运行 Qwen Code 的信息。 +- **[执行与部署](./deployment.md)：** 运行 Qwen Code 的相关信息。 - **[架构概览](./architecture.md)：** 了解 Qwen Code 的高层设计，包括其组件及交互方式。 - **CLI 使用：** `packages/cli` 的文档。 - **[CLI 简介](./cli/index.md)：** 命令行界面的概述。 - **[命令](./cli/commands.md)：** 可用 CLI 命令的说明。 - - **[配置](./cli/configuration.md)：** CLI 配置相关信息。 - - **[Checkpointing](./checkpointing.md)：** checkpointing 特性的文档。 + - **[配置](./cli/configuration.md)：** CLI 配置的相关信息。 + - **[Checkpointing](./checkpointing.md)：** checkpointing 功能的文档。 - **[扩展](./extension.md)：** 如何通过新功能扩展 CLI。 - **[IDE 集成](./ide-integration.md)：** 将 CLI 与你的编辑器连接。 - **[遥测](./telemetry.md)：** CLI 中遥测功能的概述。 @@ -33,8 +33,8 @@ Qwen Code 将先进的代码模型能力带入你的终端，提供交互式的 - **[Memory 工具](./tools/memory.md)：** `save_memory` 工具的文档。 - **[子代理](./subagents.md)：** 专注于特定任务的 AI 助手，提供全面的管理、配置和使用指导。 - **[贡献与开发指南](../CONTRIBUTING.md)：** 面向贡献者和开发者的相关信息，包括环境设置、构建、测试和编码规范。 -- **[NPM Workspaces 与发布](./npm.md)：** 项目包的管理与发布详情。 +- **[NPM](./npm.md)：** 项目包结构的详细说明。 - **[故障排除指南](./troubleshooting.md)：** 常见问题和 FAQ 的解决方案。 - **[服务条款与隐私声明](./tos-privacy.md)：** 适用于你使用 Qwen Code 的服务条款和隐私声明信息。 -我们希望这份文档能帮助你充分利用 Qwen Code！ \ No newline at end of file +我们希望这份文档能帮助你充分发挥 Qwen Code 的潜力！ \ No newline at end of file diff --git a/website/content/zh/keyboard-shortcuts.md b/website/content/zh/keyboard-shortcuts.md index d4c2e94f..f94b25f0 100644 --- a/website/content/zh/keyboard-shortcuts.md +++ b/website/content/zh/keyboard-shortcuts.md @@ -2,42 +2,43 @@ 本文档列出了 Qwen Code 中可用的键盘快捷键。 -## 通用 +## 通用快捷键 -| 快捷键 | 描述 | -| -------- | --------------------------------------------------------------------------------------------------------------------- | -| `Esc` | 关闭对话框和建议。 | -| `Ctrl+C` | 取消正在进行的请求并清除输入。按两次退出应用程序。 | -| `Ctrl+D` | 如果输入为空，则退出应用程序。按两次确认。 | -| `Ctrl+L` | 清屏。 | -| `Ctrl+O` | 切换调试控制台的显示。 | -| `Ctrl+S` | 允许长响应完整打印，禁用截断。使用终端的回滚功能查看完整输出。 | -| `Ctrl+T` | 切换工具描述的显示。 | -| `Ctrl+Y` | 切换所有工具调用的自动批准（YOLO 模式）。 | +| 快捷键 | 描述 | +| ----------- | --------------------------------------------------------------------------------------------------------------------- | +| `Esc` | 关闭对话框和建议。 | +| `Ctrl+C` | 取消正在进行的请求并清除输入。按两次退出应用。 | +| `Ctrl+D` | 如果输入为空则退出应用。按两次确认退出。 | +| `Ctrl+L` | 清屏。 | +| `Ctrl+O` | 切换调试控制台的显示。 | +| `Ctrl+S` | 允许长响应完整打印，禁用截断。使用终端的滚动功能查看完整输出。 | +| `Ctrl+T` | 切换工具描述的显示。 | +| `Shift+Tab` | 循环切换审批模式（`plan` → `default` → `auto-edit` → `yolo`）。 | ## 输入提示 | 快捷键 | 描述 | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `!` | 当输入为空时，切换 shell 模式。 | -| `\`（行尾）+ `Enter` | 插入一个新行。 | -| `向下箭头` | 在输入历史记录中向下导航。 | +| `\`（行尾）+ `Enter` | 插入一个换行符。 | +| `↓` | 在输入历史记录中向下导航。 | | `Enter` | 提交当前 prompt。 | | `Meta+Delete` / `Ctrl+Delete` | 删除光标右侧的单词。 | -| `Tab` | 如果存在自动补全建议，则补全当前建议。 | -| `向上箭头` | 在输入历史记录中向上导航。 | +| `Tab` | 如果存在当前建议，则自动补全。 | +| `↑` | 在输入历史记录中向上导航。 | | `Ctrl+A` / `Home` | 将光标移动到行首。 | -| `Ctrl+B` / `左箭头` | 将光标向左移动一个字符。 | +| `Ctrl+B` / `←` | 将光标向左移动一个字符。 | | `Ctrl+C` | 清除输入 prompt。 | +| `Esc`（双击） | 清除输入 prompt。 | | `Ctrl+D` / `Delete` | 删除光标右侧的字符。 | | `Ctrl+E` / `End` | 将光标移动到行尾。 | -| `Ctrl+F` / `右箭头` | 将光标向右移动一个字符。 | +| `Ctrl+F` / `→` | 将光标向右移动一个字符。 | | `Ctrl+H` / `Backspace` | 删除光标左侧的字符。 | | `Ctrl+K` | 删除从光标到行尾的内容。 | -| `Ctrl+左箭头` / `Meta+左箭头` / `Meta+B` | 将光标向左移动一个单词。 | +| `Ctrl+←` / `Meta+←` / `Meta+B` | 将光标向左移动一个单词。 | | `Ctrl+N` | 在输入历史记录中向下导航。 | | `Ctrl+P` | 在输入历史记录中向上导航。 | -| `Ctrl+右箭头` / `Meta+右箭头` / `Meta+F` | 将光标向右移动一个单词。 | +| `Ctrl+→` / `Meta+→` / `Meta+F` | 将光标向右移动一个单词。 | | `Ctrl+U` | 删除从光标到行首的内容。 | | `Ctrl+V` | 粘贴剪贴板内容。如果剪贴板包含图像，将保存该图像并在 prompt 中插入其引用。 | | `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace` | 删除光标左侧的单词。 | @@ -54,12 +55,12 @@ ## Radio Button Select | 快捷键 | 描述 | -| ------------------ | ------------------------------------------------------------------------------------------------------ | +| ------------------ | ------------------------------------------------------------------------------------------------------------- | | `Down Arrow` / `j` | 向下移动选择。 | -| `Enter` | 确认选择。 | -| `Up Arrow` / `k` | 向上移动选择。 | -| `1-9` | 通过编号选择项目。 | -| (多位数字) | 对于编号大于 9 的项目，快速连续按下数字键来选择对应的项目。 | +| `Enter` | 确认选择。 | +| `Up Arrow` / `k` | 向上移动选择。 | +| `1-9` | 通过数字选择项目。 | +| (多位数) | 对于数字大于 9 的项目，快速连续按下数字键来选择对应的项目。 | ## IDE 集成 diff --git a/website/content/zh/qwen-ignore.md b/website/content/zh/qwen-ignore.md new file mode 100644 index 00000000..44589797 --- /dev/null +++ b/website/content/zh/qwen-ignore.md @@ -0,0 +1,62 @@ +# 忽略文件 + +本文档概述了 Qwen Code 的 Qwen Ignore（`.qwenignore`）功能。 + +Qwen Code 支持自动忽略文件，类似于 `.gitignore`（Git 使用的忽略文件）。将路径添加到你的 `.qwenignore` 文件中，可以将这些文件从支持此功能的工具中排除，但这些文件对其他服务（如 Git）仍然可见。 + +## 工作原理 + +当你在 `.qwenignore` 文件中添加路径时，支持该文件的工具会在操作中自动排除匹配的文件和目录。例如，当你使用 [`read_many_files`](./tools/multi-file.md) 命令时，所有在 `.qwenignore` 文件中定义的路径都会被自动忽略。 + +大多数情况下，`.qwenignore` 遵循 `.gitignore` 文件的规则： + +- 空行以及以 `#` 开头的行会被忽略。 +- 支持标准的通配符模式（如 `*`、`?` 和 `[]`）。 +- 路径末尾加上 `/` 表示只匹配目录。 +- 路径开头加上 `/` 表示相对于 `.qwenignore` 文件位置进行锚定匹配。 +- 使用 `!` 可以对某个模式取反。 + +你可以随时更新 `.qwenignore` 文件。要使更改生效，需要重启你的 Qwen Code 会话。 + +## 如何使用 `.qwenignore` + +要启用 `.qwenignore`： + +1. 在你的项目根目录下创建一个名为 `.qwenignore` 的文件。 + +要将文件或目录添加到 `.qwenignore`： + +1. 打开你的 `.qwenignore` 文件。 +2. 添加你想要忽略的路径或文件，例如：`/archive/` 或 `apikeys.txt`。 + +### `.qwenignore` 示例 + +你可以使用 `.qwenignore` 来忽略目录和文件： + +``` + +# 排除你的 /packages/ 目录及其所有子目录 +/packages/ + +# 排除你的 apikeys.txt 文件 +apikeys.txt +``` + +你可以在 `.qwenignore` 文件中使用通配符 `*`： + +``` + +# 排除所有 .md 文件 +*.md +``` + +最后，你可以使用 `!` 来将文件和目录从排除列表中恢复： + +``` + +# 排除所有 .md 文件，但 README.md 除外 +*.md +!README.md +``` + +要从 `.qwenignore` 文件中移除路径，只需删除相应的行。 \ No newline at end of file diff --git a/website/content/zh/subagents.md b/website/content/zh/subagents.md index ca283fd8..dd4b5f0d 100644 --- a/website/content/zh/subagents.md +++ b/website/content/zh/subagents.md @@ -1,16 +1,16 @@ # Subagents -Subagents 是专门处理 Qwen Code 中特定类型任务的 AI 助手。它们允许你将专注的工作委派给配置了任务特定提示、工具和行为的 AI agents。 +Subagents 是专门处理 Qwen Code 中特定类型任务的 AI 助手。它们允许你将专注的工作委托给配置了任务特定提示、工具和行为的 AI agents。 ## 什么是 Subagents？ Subagents 是独立的 AI 助手，具备以下特点： -- **专精特定任务** - 每个 subagent 都配置了专注于特定类型工作的 system prompt -- **独立上下文** - 它们维护自己的对话历史，与你的主聊天窗口分离 -- **受控工具访问** - 你可以配置每个 subagent 可以访问的工具 +- **专精特定任务** - 每个 subagent 都配置了专注于特定类型工作的系统提示 +- **拥有独立上下文** - 它们维护自己的对话历史，与你的主聊天分开 +- **使用受控工具** - 你可以配置每个 subagent 可以访问的工具 - **自主工作** - 一旦分配任务，它们会独立工作直到完成或失败 -- **详细反馈** - 你可以实时查看它们的进度、工具使用情况和执行统计信息 +- **提供详细反馈** - 你可以实时查看它们的进度、工具使用情况和执行统计信息 ## 核心优势 @@ -48,14 +48,14 @@ Subagents 是独立的 AI 助手，具备以下特点： 查看和管理你已配置的 subagents。 3. **自动使用 subagents**： - 只需让主 AI 执行与你的 subagents 专长相匹配的任务。AI 会自动将合适的工作委派出去。 + 只需让主 AI 执行与你的 subagents 专长匹配的任务。AI 会自动将合适的工作委派出去。 ### 使用示例 ``` User: "请为认证模块编写全面的测试" -AI: 我将把这个任务委派给你的测试专家 subagent。 +AI: 我会把这个任务委派给你的测试专家 subagent。 [委派给 "testing-expert" subagent] [显示测试创建的实时进度] [返回完成的测试文件和执行摘要] @@ -94,11 +94,11 @@ Subagents 通过 `/agents` 斜杠命令及其子命令进行管理： - **项目级别**：`.qwen/agents/`（优先级更高） - **用户级别**：`~/.qwen/agents/`（备选方案） -这样你可以同时拥有项目特定的 agent 和跨项目使用的个人 agent。 +这样你可以同时拥有项目专用的 agent 和跨项目使用的个人 agent。 ### 文件格式 -子 agent 使用带有 YAML frontmatter 的 Markdown 文件进行配置。这种格式易于阅读，且可以用任何文本编辑器轻松编辑。 +子 agent 使用带有 YAML frontmatter 的 Markdown 文件进行配置。这种格式易于阅读，也方便用任何文本编辑器进行编辑。 #### 基本结构 @@ -132,9 +132,31 @@ description: 创建项目文档和 README 文件 专注于创建清晰、全面的文档，帮助新贡献者和最终用户理解项目。 ``` +## 高效使用 Subagents + +### 自动委派 + +Qwen Code 会根据以下内容主动委派任务： + +- 你请求中的任务描述 +- subagent 配置中的 description 字段 +- 当前上下文和可用工具 + +要鼓励更主动地使用 subagent，可以在 description 字段中加入 "use PROACTIVELY" 或 "MUST BE USED" 等短语。 + +### 显式调用 + +通过在命令中提及特定子代理来请求其服务： + +``` +> 让 testing-expert 子代理为支付模块创建单元测试 +> 让 documentation-writer 子代理更新 API 参考文档 +> 让 react-specialist 子代理优化这个组件的性能 +``` + ## 示例 -### 开发工作流 Agents +### 开发工作流代理 #### 测试专家 @@ -151,77 +173,77 @@ tools: read_file, write_file, read_many_files, run_shell_command 你的专业技能包括： -- 使用适当的 mocking 和隔离进行单元测试 +- 使用适当的 mock 和隔离进行单元测试 - 针对组件交互的集成测试 -- 测试驱动开发实践 -- 边缘情况识别和全面覆盖 -- 在适当时进行性能和负载测试 +- 测试驱动开发（TDD）实践 +- 边缘情况识别和全面覆盖率 +- 在适当情况下进行性能和负载测试 对于每个测试任务： 1. 分析代码结构和依赖关系 2. 识别关键功能、边缘情况和错误条件 3. 创建具有描述性名称的全面测试套件 -4. 包含适当的 setup/teardown 和有意义的断言 +4. 包含正确的 setUp/tearDown 和有意义的断言 5. 添加注释解释复杂的测试场景 -6. 确保测试具有可维护性并遵循 DRY 原则 +6. 确保测试具备可维护性并遵循 DRY 原则 -始终遵循所检测语言和框架的测试最佳实践。 -关注正面和负面测试用例。 +始终根据检测到的语言和框架遵循测试最佳实践。 +关注正向和负向测试用例。 ``` **使用场景：** - "为认证服务编写单元测试" - "为支付处理工作流创建集成测试" -- "为数据验证模块中的边缘情况添加测试覆盖" +- "在数据验证模块中增加边缘情况的测试覆盖" -#### Documentation Writer +#### 文档撰写员 专门负责创建清晰、全面的文档。 ```markdown --- name: documentation-writer -description: 创建全面的文档，包括 README 文件、API 文档和用户指南 +description: 负责创建全面的文档，包括 README 文件、API 文档和用户指南 tools: read_file, write_file, read_many_files, web_search --- 你是 ${project_name} 的技术文档专家。 -你的职责是创建清晰、全面的文档，服务于开发者和最终用户。重点关注： +你的职责是为开发者和终端用户创建清晰、全面的文档。重点关注： **API 文档方面：** -- 清晰的 endpoint 描述及示例 -- 参数详情（包括类型和约束） -- 响应格式说明 -- 错误码解释 +- 包含示例的清晰 endpoint 描述 +- 带有类型和约束条件的参数详情 +- 响应格式文档 +- 错误代码说明 - 认证要求 **用户文档方面：** -- 带截图的逐步操作指南（适当情况下） -- 安装与设置指南 -- 配置选项及示例 -- 常见问题的故障排查章节 +- 带有截图（如有帮助）的逐步操作指南 +- 安装和设置指南 +- 配置选项和示例 +- 常见问题的故障排除部分 - 基于常见用户问题的 FAQ 部分 **开发者文档方面：** -- 架构概览和设计决策 -- 可实际运行的代码示例 +- 架构概述和设计决策 +- 真正可用的代码示例 - 贡献指南 -- 开发环境搭建说明 +- 开发环境设置 -始终验证代码示例，并确保文档内容与实际实现保持同步。使用清晰的标题、项目符号和示例。 +始终验证代码示例，并确保文档与实际实现保持同步。使用清晰的标题、项目符号和示例。 ``` **使用场景：** - "为用户管理 endpoints 创建 API 文档" -- "为该项目编写一份全面的 README" -- "记录部署流程并包含故障排查步骤" +- "为这个项目编写一份全面的 README" +- "记录部署流程并包含故障排除步骤" #### Code Reviewer @@ -234,36 +256,36 @@ description: Reviews code for best practices, security issues, performance, and tools: read_file, read_many_files --- -你是一位专注于质量、安全性和可维护性的资深代码审查员。 +You are an experienced code reviewer focused on quality, security, and maintainability. -审查标准： +Review criteria: -- **代码结构**：组织结构、模块化和关注点分离 -- **性能**：算法效率和资源使用情况 -- **安全性**：漏洞评估和安全编码实践 -- **最佳实践**：特定语言/框架的编码规范 -- **错误处理**：正确的异常处理和边界情况覆盖 -- **可读性**：清晰的命名、注释和代码组织 -- **测试**：测试覆盖率和可测试性考虑 +- **Code Structure**: Organization, modularity, and separation of concerns +- **Performance**: Algorithmic efficiency and resource usage +- **Security**: Vulnerability assessment and secure coding practices +- **Best Practices**: Language/framework-specific conventions +- **Error Handling**: Proper exception handling and edge case coverage +- **Readability**: Clear naming, comments, and code organization +- **Testing**: Test coverage and testability considerations -提供建设性反馈，包括： +Provide constructive feedback with: -1. **严重问题**：安全漏洞、重大 bug -2. **重要改进**：性能问题、设计缺陷 -3. **次要建议**：风格改进、重构机会 -4. **正面反馈**：实现良好的模式和优秀实践 +1. **Critical Issues**: Security vulnerabilities, major bugs +2. **Important Improvements**: Performance issues, design problems +3. **Minor Suggestions**: Style improvements, refactoring opportunities +4. **Positive Feedback**: Well-implemented patterns and good practices -专注于可操作的反馈，提供具体示例和建议解决方案。 -根据影响程度对问题进行优先级排序，并为建议提供理由。 +Focus on actionable feedback with specific examples and suggested solutions. +Prioritize issues by impact and provide rationale for recommendations. ``` **使用场景：** -- "审查这个认证实现是否存在安全问题" -- "检查这个数据库查询逻辑的性能影响" -- "评估代码结构并提出改进建议" +- "Review this authentication implementation for security issues" +- "Check the performance implications of this database query logic" +- "Evaluate the code structure and suggest improvements" -### 技术特定 Agents +### 技术特定的 Agents #### React 专家 @@ -285,7 +307,7 @@ tools: read_file, write_file, read_many_files, run_shell_command - **性能优化**：React.memo、useMemo、useCallback、代码分割 - **测试**：React Testing Library、Jest、组件测试策略 - **TypeScript 集成**：props、hooks 和组件的正确类型定义 -- **现代模式**：Suspense、Error Boundaries、Concurrent Features +- **现代模式**：Suspense、Error Boundaries、并发特性 处理 React 任务时： @@ -296,15 +318,16 @@ tools: read_file, write_file, read_many_files, run_shell_command 5. 包含适当的错误处理 6. 编写可测试、可维护的代码 -始终保持对 React 最佳实践的跟进，避免使用已弃用的模式。 -关注无障碍性和用户体验考虑。 +始终保持对 React 最佳实践的关注，避免使用已弃用的模式。 +关注无障碍性和用户体验。 + ``` **使用场景：** -- "创建一个支持排序和过滤的可复用数据表格组件" +- "创建一个支持排序和过滤功能的可复用数据表格组件" - "实现一个带缓存功能的自定义 hook 用于 API 数据获取" -- "将这个 class 组件重构为使用现代 React 模式" +- "将这个 class 组件重构为使用现代 React 模式的组件" #### Python 专家 @@ -327,26 +350,26 @@ tools: read_file, write_file, read_many_files, run_shell_command - **数据科学**：pandas、numpy、matplotlib、jupyter notebooks - **异步编程**：asyncio、async/await 模式 - **包管理**：pip、poetry、虚拟环境 -- **代码质量**：PEP 8、类型提示、使用 pylint/flake8 进行 linting +- **代码质量**：PEP 8、类型提示、使用 pylint/flake8 进行代码检查 -处理 Python 任务时： +处理 Python 任务时请遵循以下原则： 1. 遵循 PEP 8 编码规范 -2. 使用类型提示提升代码可读性 -3. 使用具体异常实现完善的错误处理机制 -4. 编写完整的 docstring +2. 使用类型提示以增强代码可读性 +3. 实现适当的错误处理机制，捕获具体异常 +4. 编写完整的 docstring 文档 5. 考虑性能与内存使用情况 -6. 添加适当的日志记录 -7. 编写模块化、易于测试的代码 +6. 添加合适的日志记录 +7. 编写模块化且易于测试的代码 -专注于编写符合社区标准的清晰、可维护的 Python 代码。 +专注于编写符合社区标准的清晰、易维护的 Python 代码。 ``` -**使用场景示例：** +**典型用例：** - “创建一个基于 FastAPI 的用户认证服务，支持 JWT token” -- “用 pandas 实现一个具备错误处理能力的数据处理流水线” -- “使用 argparse 开发一个 CLI 工具，并提供完整的帮助文档” +- “实现一个包含错误处理机制的数据处理流水线，使用 pandas” +- “使用 argparse 编写一个命令行工具，并提供详细的帮助文档” ## 最佳实践 @@ -413,10 +436,10 @@ description: 检查代码中的安全漏洞、性能问题和可维护性问题 **❌ 避免：** ```markdown -description: 一个有用的代码审查员 +description: 一个有用的代码审查工具 ``` -**原因：** 清晰的描述有助于主 AI 为每个任务选择正确的 agent。 +**原因：** 清晰的描述能帮助主 AI 为每个任务选择正确的 agent。 ### 配置最佳实践 @@ -440,8 +463,8 @@ description: 一个有用的代码审查员 1. 分析代码结构和依赖关系 2. 识别核心功能和边界情况 -3. 创建全面的测试套件，并使用清晰的命名 -4. 包含 setup/teardown 和正确的断言 +3. 创建全面的测试套件并使用清晰的命名 +4. 包含 setUp/tearDown 和正确的断言 5. 添加注释解释复杂的测试场景 ``` @@ -450,7 +473,7 @@ description: 一个有用的代码审查员 ```markdown 始终遵循以下标准： -- 使用描述性的 test 名称，能够说明测试场景 +- 使用能清楚描述测试场景的测试函数名 - 包含正向和负向测试用例 - 为复杂的测试函数添加 docstrings - 确保测试之间相互独立，可以按任意顺序运行 @@ -460,7 +483,7 @@ description: 一个有用的代码审查员 - **工具限制**：Subagents 只能访问其配置的工具 - **沙箱机制**：所有工具执行都遵循与直接使用工具相同的安全模型 -- **审计追踪**：所有 subagent 操作都会被记录，并实时可见 +- **审计追踪**：所有 subagent 操作都会被记录，并可实时查看 - **访问控制**：项目和用户级别的隔离提供了适当的边界 - **敏感信息**：避免在 agent 配置中包含 secrets 或 credentials - **生产环境**：考虑为生产环境和开发环境使用不同的 agents \ No newline at end of file diff --git a/website/content/zh/telemetry.md b/website/content/zh/telemetry.md index 0ebc8bd9..0d3d3ad4 100644 --- a/website/content/zh/telemetry.md +++ b/website/content/zh/telemetry.md @@ -26,7 +26,7 @@ Qwen Code 的遥测系统基于 **[OpenTelemetry] (OTEL)** 标准构建，允许 1. **工作区设置文件（`.qwen/settings.json`）：** 该 project-specific 文件中 `telemetry` 对象的值。 -1. **用户设置文件（`~/.qwen/settings.json`）：** 该 global user 文件中 `telemetry` 对象的值。 +1. **用户设置文件（`~/.qwen/settings.json`）：** 该全局用户文件中 `telemetry` 对象的值。 1. **默认值：** 如果以上均未设置，则应用以下默认值。 - `telemetry.enabled`: `false` @@ -39,7 +39,7 @@ Qwen Code 的遥测系统基于 **[OpenTelemetry] (OTEL)** 标准构建，允许 ### 示例配置 -你可以将以下代码添加到你的工作区配置文件 (`.qwen/settings.json`) 或用户配置文件 (`~/.qwen/settings.json`) 中，以启用遥测功能并将数据发送到 Google Cloud： +你可以将以下代码添加到你的工作区（`.qwen/settings.json`）或用户级别（`~/.qwen/settings.json`）的配置文件中，以启用遥测功能并将数据发送至 Google Cloud： ```json { @@ -53,20 +53,20 @@ Qwen Code 的遥测系统基于 **[OpenTelemetry] (OTEL)** 标准构建，允许 ### 导出到文件 -你可以将所有遥测数据导出到一个文件中，方便在本地查看。 +你也可以将所有遥测数据导出到一个本地文件中，方便后续查看和分析。 -要启用文件导出功能，请使用 `--telemetry-outfile` 参数，并指定你希望输出的文件路径。此功能必须配合 `--telemetry-target=local` 一起使用。 +要启用文件导出功能，请使用 `--telemetry-outfile` 参数，并指定输出文件的路径。注意此命令必须配合 `--telemetry-target=local` 使用。 ```bash -# 设置你希望输出的文件路径 +# 设置你想要的输出文件路径 TELEMETRY_FILE=".qwen/telemetry.log" -# 使用本地遥测功能运行 Qwen Code +# 运行 Qwen Code 并开启本地遥测记录 -# 注意：必须设置 --telemetry-otlp-endpoint="" 来覆盖默认的 +# 注意：--telemetry-otlp-endpoint="" 是必需的，用于覆盖默认的 OTLP 导出设置， -# OTLP 导出器，确保遥测数据写入本地文件。 +# 确保遥测数据写入本地文件而不是远程服务。 qwen --telemetry \ --telemetry-target=local \ --telemetry-otlp-endpoint="" \ @@ -79,7 +79,7 @@ qwen --telemetry \ OTEL Collector 是一个接收、处理和导出遥测数据的服务。 CLI 可以使用 OTLP/gRPC 或 OTLP/HTTP 协议发送数据。 你可以通过 `--telemetry-otlp-protocol` flag -或 `settings.json` 文件中的 `telemetry.otlpProtocol` 设置来指定使用哪种协议。更多 +或在 `settings.json` 文件中的 `telemetry.otlpProtocol` 设置来指定使用哪种协议。更多 详情请参见 [配置文档](./cli/configuration.md#--telemetry-otlp-protocol)。 在 [documentation][otel-config-docs] 中了解更多关于 OTEL exporter 标准配置的信息。 @@ -88,24 +88,24 @@ CLI 可以使用 OTLP/gRPC 或 OTLP/HTTP 协议发送数据。 ### 本地部署 -使用 `npm run telemetry -- --target=local` 命令可以自动化设置本地 telemetry pipeline，包括在你的 `.qwen/settings.json` 文件中配置必要的设置。底层脚本会安装 `otelcol-contrib`（OpenTelemetry Collector）和 `jaeger`（用于查看 traces 的 Jaeger UI）。使用方式如下： +使用 `npm run telemetry -- --target=local` 命令可以自动设置本地 telemetry pipeline，包括在你的 `.qwen/settings.json` 文件中配置必要的设置。该脚本会自动安装 `otelcol-contrib`（即 OpenTelemetry Collector）和 `jaeger`（用于查看 traces 的 Jaeger UI）。使用方式如下： 1. **运行命令**： - 在 repository 根目录下执行以下命令： + 在项目根目录下执行以下命令： ```bash npm run telemetry -- --target=local ``` 脚本将会： - - 如有需要，下载 Jaeger 和 OTEL。 + - 如有需要，自动下载 Jaeger 和 OTEL。 - 启动一个本地 Jaeger 实例。 - 启动一个配置好的 OTEL collector，用于接收来自 Qwen Code 的数据。 - 自动在你的 workspace settings 中启用 telemetry。 - - 退出时，自动禁用 telemetry。 + - 脚本退出时，自动禁用 telemetry。 1. **查看 traces**： - 打开浏览器并访问 **http://localhost:16686** 进入 Jaeger UI，在这里你可以查看 Qwen Code 操作的详细 traces。 + 打开浏览器并访问 **http://localhost:16686**，即可进入 Jaeger UI，查看 Qwen Code 操作的详细 traces。 1. **查看 logs 和 metrics**： 脚本会将 OTEL collector 的输出（包括 logs 和 metrics）重定向到 `~/.qwen/tmp//otel/collector.log`。脚本还会提供链接和命令，方便你本地查看 telemetry 数据（traces、metrics、logs）。 @@ -115,19 +115,19 @@ CLI 可以使用 OTLP/gRPC 或 OTLP/HTTP 协议发送数据。 ### Google Cloud -使用 `npm run telemetry -- --target=gcp` 命令可以自动化设置一个本地 OpenTelemetry collector，将数据转发到你的 Google Cloud 项目，并自动配置 `.qwen/settings.json` 文件中的必要设置。该脚本底层会安装 `otelcol-contrib`。使用步骤如下： +使用 `npm run telemetry -- --target=gcp` 命令可以自动设置一个本地的 OpenTelemetry collector，将数据转发到你的 Google Cloud 项目，并自动配置 `.qwen/settings.json` 文件中的必要参数。该脚本会安装 `otelcol-contrib`。使用步骤如下： 1. **前置条件**： - 拥有一个 Google Cloud 项目 ID。 - - 导出 `GOOGLE_CLOUD_PROJECT` 环境变量，以便 OTEL collector 可以读取。 + - 导出 `GOOGLE_CLOUD_PROJECT` 环境变量，以便 OTEL collector 可以访问它。 ```bash export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" ``` - - 完成 Google Cloud 身份验证（例如运行 `gcloud auth application-default login`，或确保已设置 `GOOGLE_APPLICATION_CREDENTIALS`）。 - - 确保你的 Google Cloud 账户或服务账户拥有以下 IAM 角色："Cloud Trace Agent"、"Monitoring Metric Writer" 和 "Logs Writer"。 + - 完成 Google Cloud 身份验证（例如运行 `gcloud auth application-default login` 或确保已设置 `GOOGLE_APPLICATION_CREDENTIALS`）。 + - 确保你的 Google Cloud 账号或服务账号拥有以下 IAM 角色："Cloud Trace Agent"、"Monitoring Metric Writer" 和 "Logs Writer"。 -1. **运行命令**： - 在项目根目录下执行以下命令： +1. **执行命令**： + 在仓库根目录下运行以下命令： ```bash npm run telemetry -- --target=gcp @@ -135,22 +135,22 @@ CLI 可以使用 OTLP/gRPC 或 OTLP/HTTP 协议发送数据。 脚本将会： - 如果需要，下载 `otelcol-contrib` 二进制文件。 - - 启动一个 OTEL collector，配置为接收来自 Qwen Code 的数据并导出到你指定的 Google Cloud 项目。 - - 自动在你的工作区设置（`.qwen/settings.json`）中启用 telemetry 并关闭 sandbox 模式。 - - 提供直接链接，用于在 Google Cloud Console 中查看 traces、metrics 和 logs。 - - 在退出时（Ctrl+C），尝试恢复你原来的 telemetry 和 sandbox 设置。 + - 启动一个 OTEL collector，用于接收来自 Qwen Code 的遥测数据并导出至你指定的 Google Cloud 项目。 + - 自动在工作区设置中启用 telemetry 并关闭 sandbox 模式（`.qwen/settings.json`）。 + - 提供直接链接，方便你在 Google Cloud Console 中查看 traces、metrics 和 logs。 + - 当你退出脚本时（按 Ctrl+C），它会尝试恢复原始的 telemetry 和 sandbox 设置。 1. **运行 Qwen Code**： - 在另一个终端中运行你的 Qwen Code 命令。这将生成 telemetry 数据，由 collector 捕获。 + 在另一个终端窗口中运行你的 Qwen Code 命令。这会产生遥测数据，由 collector 进行捕获。 -1. **在 Google Cloud 中查看 telemetry 数据**： - 使用脚本提供的链接跳转到 Google Cloud Console，查看你的 traces、metrics 和 logs。 +1. **在 Google Cloud 中查看遥测数据**： + 使用脚本提供的链接跳转到 Google Cloud Console 查看 traces、metrics 和 logs。 -1. **查看本地 collector 日志**： - 脚本将本地 OTEL collector 的输出重定向到 `~/.qwen/tmp//otel/collector-gcp.log`。脚本还会提供链接和命令，方便你在本地查看或 tail collector 日志。 +1. **检查本地 collector 日志**： + 脚本会将本地 OTEL collector 的输出重定向到 `~/.qwen/tmp//otel/collector-gcp.log`。脚本同时提供查看和实时跟踪 collector 日志的链接与命令。 1. **停止服务**： - 在脚本运行的终端中按下 `Ctrl+C`，即可停止 OTEL Collector。 + 在脚本运行的终端中按下 `Ctrl+C` 即可停止 OTEL Collector。 ## 日志和指标参考 @@ -179,9 +179,10 @@ CLI 可以使用 OTLP/gRPC 或 OTLP/HTTP 协议发送数据。 - `qwen-code.user_prompt`：该事件在用户提交 prompt 时发生。 - **属性**： - - `prompt_length` - - `prompt`（如果 `log_prompts_enabled` 配置为 `false`，则该属性会被排除） - - `auth_type` + - `prompt_length` (int) + - `prompt_id` (string) + - `prompt` (string，如果 `log_prompts_enabled` 配置为 `false`，则该属性会被排除) + - `auth_type` (string) - `qwen-code.tool_call`：该事件在每次函数调用时发生。 - **属性**： @@ -190,14 +191,14 @@ CLI 可以使用 OTLP/gRPC 或 OTLP/HTTP 协议发送数据。 - `duration_ms` - `success` (boolean) - `decision` (string: "accept", "reject", "auto_accept", 或 "modify"，如适用) - - `error`（如适用） - - `error_type`（如适用） - - `metadata`（如适用，string -> any 的字典） + - `error` (如适用) + - `error_type` (如适用) + - `metadata` (如适用，string -> any 的字典) - `qwen-code.api_request`：该事件在向 Qwen API 发起请求时发生。 - **属性**： - `model` - - `request_text`（如适用） + - `request_text` (如适用) - `qwen-code.api_error`：该事件在 API 请求失败时发生。 - **属性**： @@ -213,13 +214,13 @@ CLI 可以使用 OTLP/gRPC 或 OTLP/HTTP 协议发送数据。 - `model` - `status_code` - `duration_ms` - - `error`（可选） + - `error` (可选) - `input_token_count` - `output_token_count` - `cached_content_token_count` - `thoughts_token_count` - `tool_token_count` - - `response_text`（如适用） + - `response_text` (如适用) - `auth_type` - `qwen-code.flash_fallback`：该事件在 Qwen Code 切换为使用 flash 作为 fallback 时发生。 @@ -229,53 +230,54 @@ CLI 可以使用 OTLP/gRPC 或 OTLP/HTTP 协议发送数据。 - `qwen-code.slash_command`：该事件在用户执行斜杠命令时发生。 - **属性**： - `command` (string) - - `subcommand` (string，如适用) + - `subcommand` (string, 如适用) -### Metrics +### 指标（Metrics） -Metrics 是对行为随时间变化的数值测量。Qwen Code 收集以下指标（指标名称仍保留为 `qwen-code.*` 以保持兼容性）： +指标是随时间变化的行为数值测量。Qwen Code 会收集以下指标（为保持兼容性，指标名称仍为 `qwen-code.*`）： -- `qwen-code.session.count` (Counter, Int)：每次 CLI 启动时递增一次。 +- `qwen-code.session.count`（计数器，整数）：每次 CLI 启动时递增一次。 -- `qwen-code.tool.call.count` (Counter, Int)：统计工具调用次数。 - - **Attributes**： +- `qwen-code.tool.call.count`（计数器，整数）：统计工具调用次数。 + - **属性**： - `function_name` - - `success` (boolean) - - `decision` (string: "accept", "reject", 或 "modify"，如果适用) - - `tool_type` (string: "mcp", 或 "native"，如果适用) + - `success`（布尔值） + - `decision`（字符串："accept"、"reject" 或 "modify"，如适用） + - `tool_type`（字符串："mcp" 或 "native"，如适用） -- `qwen-code.tool.call.latency` (Histogram, ms)：测量工具调用延迟。 - - **Attributes**： +- `qwen-code.tool.call.latency`（直方图，单位：毫秒）：测量工具调用的延迟。 + - **属性**： - `function_name` - - `decision` (string: "accept", "reject", 或 "modify"，如果适用) + - `decision`（字符串："accept"、"reject" 或 "modify"，如适用） -- `qwen-code.api.request.count` (Counter, Int)：统计所有 API 请求次数。 - - **Attributes**： +- `qwen-code.api.request.count`（计数器，整数）：统计所有 API 请求次数。 + - **属性**： - `model` - `status_code` - - `error_type` (如果适用) + - `error_type`（如适用） -- `qwen-code.api.request.latency` (Histogram, ms)：测量 API 请求延迟。 - - **Attributes**： +- `qwen-code.api.request.latency`（直方图，单位：毫秒）：测量 API 请求的延迟。 + - **属性**： - `model` -- `qwen-code.token.usage` (Counter, Int)：统计使用的 token 数量。 - - **Attributes**： +- `qwen-code.token.usage`（计数器，整数）：统计使用的 token 数量。 + - **属性**： - `model` - - `type` (string: "input", "output", "thought", "cache", 或 "tool") - -- `qwen-code.file.operation.count` (Counter, Int)：统计文件操作次数。 - - **Attributes**： - - `operation` (string: "create", "read", "update")：文件操作类型。 - - `lines` (Int, 如果适用)：文件中的行数。 - - `mimetype` (string, 如果适用)：文件的 MIME 类型。 - - `extension` (string, 如果适用)：文件扩展名。 - - `ai_added_lines` (Int, 如果适用)：AI 添加/修改的行数。 - - `ai_removed_lines` (Int, 如果适用)：AI 删除/修改的行数。 - - `user_added_lines` (Int, 如果适用)：用户在 AI 提议的更改中添加/修改的行数。 - - `user_removed_lines` (Int, 如果适用)：用户在 AI 提议的更改中删除/修改的行数。 - -- `qwen-code.chat_compression` (Counter, Int)：统计聊天压缩操作次数。 - - **Attributes**： - - `tokens_before` (Int)：压缩前上下文中的 token 数量。 - - `tokens_after` (Int)：压缩后上下文中的 token 数量。 \ No newline at end of file + - `type`（字符串："input"、"output"、"thought"、"cache" 或 "tool"） + +- `qwen-code.file.operation.count`（计数器，整数）：统计文件操作次数。 + - **属性**： + - `operation`（字符串："create"、"read"、"update"）：文件操作类型。 + - `lines`（整数，如适用）：文件行数。 + - `mimetype`（字符串，如适用）：文件的 MIME 类型。 + - `extension`（字符串，如适用）：文件扩展名。 + - `ai_added_lines`（整数，如适用）：AI 添加/修改的行数。 + - `ai_removed_lines`（整数，如适用）：AI 删除/修改的行数。 + - `user_added_lines`（整数，如适用）：用户在 AI 提议的更改中添加/修改的行数。 + - `user_removed_lines`（整数，如适用）：用户在 AI 提议的更改中删除/修改的行数。 + - `programming_language`（字符串，如适用）：文件的编程语言。 + +- `qwen-code.chat_compression`（计数器，整数）：统计聊天压缩操作次数。 + - **属性**： + - `tokens_before`（整数）：压缩前上下文中的 token 数量。 + - `tokens_after`（整数）：压缩后上下文中的 token 数量。 \ No newline at end of file diff --git a/website/content/zh/tools/multi-file.md b/website/content/zh/tools/multi-file.md index 63cca4e1..595b23db 100644 --- a/website/content/zh/tools/multi-file.md +++ b/website/content/zh/tools/multi-file.md @@ -7,20 +7,20 @@ 使用 `read_many_files` 从指定路径或 glob 模式匹配的多个文件中读取内容。此工具的行为取决于提供的文件类型： - 对于文本文件，该工具会将其内容连接成一个单一字符串。 -- 对于图像（如 PNG、JPEG）、PDF、音频（MP3、WAV）和视频（MP4、MOV）文件，如果通过文件名或扩展名明确请求，它会读取并以 base64 编码数据的形式返回。 +- 对于图像（如 PNG、JPEG）、PDF、音频（MP3、WAV）和视频（MP4、MOV）文件，如果通过文件名或扩展名明确请求，它会以 base64 编码的数据形式读取并返回这些文件。 -`read_many_files` 可用于执行诸如概览代码库、查找特定功能实现位置、审查文档或从多个配置文件中收集上下文等任务。 +`read_many_files` 可用于执行以下任务：概览代码库、查找特定功能的实现位置、审查文档，或从多个配置文件中收集上下文信息。 -**注意：** `read_many_files` 会根据提供的路径或 glob 模式查找文件。像 `"/docs"` 这样的目录路径将返回空结果；该工具需要像 `"/docs/*"` 或 `"/docs/*.md"` 这样的模式来识别相关文件。 +**注意：** `read_many_files` 会根据提供的路径或 glob 模式查找文件。像 `"/docs"` 这样的目录路径将返回空结果；该工具需要类似 `"/docs/*"` 或 `"/docs/*.md"` 的模式来识别相关文件。 ### 参数 `read_many_files` 接受以下参数： -- `paths` (list[string], 必填): 一个 glob 模式或相对于工具目标目录的路径数组（例如 `["src/**/*.ts"]`、`["README.md", "docs/*", "assets/logo.png"]`）。 -- `exclude` (list[string], 可选): 要排除的文件/目录的 glob 模式（例如 `["**/*.log", "temp/"]`）。如果 `useDefaultExcludes` 为 true，这些模式会与默认排除模式合并。 -- `include` (list[string], 可选): 要包含的额外 glob 模式。这些模式会与 `paths` 合并（例如 `["*.test.ts"]` 用于特别添加测试文件，或者 `["images/*.jpg"]` 用于包含特定类型的图像）。 -- `recursive` (boolean, 可选): 是否递归搜索。主要通过 glob 模式中的 `**` 控制。默认值为 `true`。 +- `paths` (list[string], 必填): 一个包含 glob 模式或相对于工具目标目录的路径数组（例如 `["src/**/*.ts"]`、`["README.md", "docs/*", "assets/logo.png"]`）。 +- `exclude` (list[string], 可选): 要排除的文件/目录的 glob 模式（例如 `["**/*.log", "temp/"]`）。如果 `useDefaultExcludes` 为 true，这些模式会添加到默认排除列表中。 +- `include` (list[string], 可选): 要包含的额外 glob 模式。这些模式会与 `paths` 合并（例如 `["*.test.ts"]` 用于特别添加测试文件，如果它们被广泛排除；或者 `["images/*.jpg"]` 用于包含特定类型的图像）。 +- `recursive` (boolean, 可选): 是否递归搜索。这主要由 glob 模式中的 `**` 控制。默认值为 `true`。 - `useDefaultExcludes` (boolean, 可选): 是否应用默认的排除模式列表（例如 `node_modules`、`.git`、非图像/PDF 的二进制文件）。默认值为 `true`。 - `respect_git_ignore` (boolean, 可选): 查找文件时是否遵循 .gitignore 模式。默认值为 true。 @@ -29,8 +29,9 @@ `read_many_files` 会根据提供的 `paths` 和 `include` 模式搜索匹配的文件，同时遵守 `exclude` 模式和默认排除规则（如果启用）。 - 对于文本文件：它会读取每个匹配文件的内容（尝试跳过未明确指定为 image/PDF 的二进制文件），并将它们连接成一个字符串，每个文件内容之间用分隔符 `--- {filePath} ---` 分隔。默认使用 UTF-8 编码。 -- 对于图像和 PDF 文件：如果通过文件名或扩展名显式指定（例如 `paths: ["logo.png"]` 或 `include: ["*.pdf"]`），该工具会读取文件并将其内容以 base64 编码字符串的形式返回。 -- 对于其他二进制文件（不匹配常见 image/PDF 类型且未显式指定的文件），工具会通过检查文件开头是否存在 null 字节来尝试检测并跳过这些文件。 +- 工具会在最后一个文件之后插入 `--- End of content ---`。 +- 对于图像和 PDF 文件：如果通过文件名或扩展名显式指定（例如 `paths: ["logo.png"]` 或 `include: ["*.pdf"]`），工具会读取该文件并将其内容以 base64 编码字符串的形式返回。 +- 工具会尝试通过检查文件初始内容中是否包含 null 字节来检测并跳过其他二进制文件（即不匹配常见图像/PDF 类型且未被显式指定的文件）。 用法： @@ -46,13 +47,13 @@ read_many_files(paths=["Your files or paths here."], include=["Additional files read_many_files(paths=["src/**/*.ts"]) ``` -读取主 README 文件、`docs` 目录下的所有 Markdown 文件以及一个特定的 logo 图片，但排除一个特定文件： +读取主 README 文件、`docs` 目录下的所有 Markdown 文件，以及一个特定的 logo 图片，排除某个特定文件： ``` read_many_files(paths=["README.md", "docs/**/*.md", "assets/logo.png"], exclude=["docs/OLD_README.md"]) ``` -读取所有 JavaScript 文件，但显式包含测试文件以及 `images` 文件夹中的所有 JPEG 图片： +读取所有 JavaScript 文件，但显式包含测试文件和 `images` 文件夹中的所有 JPEG 图片： ``` read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], useDefaultExcludes=False) @@ -61,8 +62,8 @@ read_many_files(paths=["**/*.js"], include=["**/*.test.js", "images/**/*.jpg"], ## 重要说明 - **二进制文件处理：** - - **图像/PDF/音频/视频文件：** 该工具可以读取常见的图像格式（PNG、JPEG 等）、PDF、音频（mp3、wav）和视频（mp4、mov）文件，并将其作为 base64 编码数据返回。这些文件**必须**通过 `paths` 或 `include` 模式显式指定（例如，指定确切的文件名如 `video.mp4` 或模式如 `*.mov`）。 - - **其他二进制文件：** 该工具会尝试通过检查文件开头内容中的空字节来检测并跳过其他类型的二进制文件。这些文件会被排除在输出之外。 -- **性能：** 读取大量文件或单个大文件可能会消耗较多资源。 -- **路径指定：** 确保路径和 glob 模式相对于工具的目标目录正确指定。对于图像/PDF 文件，请确保模式足够具体以包含它们。 -- **默认排除：** 注意默认的排除模式（如 `node_modules`、`.git`），如果需要覆盖这些模式，可以使用 `useDefaultExcludes=False`，但请谨慎操作。 \ No newline at end of file + - **图像/PDF/音频/视频文件：** 该工具可以读取常见的图像格式（PNG、JPEG 等）、PDF、音频（mp3、wav）和视频（mp4、mov）文件，并将其作为 base64 编码数据返回。这些文件**必须**通过 `paths` 或 `include` 模式显式指定目标（例如，指定确切的文件名如 `video.mp4` 或模式如 `*.mov`）。 + - **其他二进制文件：** 该工具会尝试通过检查文件开头内容中是否包含空字节来检测并跳过其他类型的二进制文件。这些文件会被排除在输出之外。 +- **性能：** 读取大量文件或单个大文件可能会占用较多资源。 +- **路径准确性：** 请确保路径和 glob 模式相对于工具的目标目录正确指定。对于图像/PDF 文件，请确保模式足够具体以包含它们。 +- **默认排除项：** 注意默认的排除模式（如 `node_modules`、`.git`），如果需要覆盖这些默认设置，可以使用 `useDefaultExcludes=False`，但请谨慎操作。 \ No newline at end of file diff --git a/website/content/zh/troubleshooting.md b/website/content/zh/troubleshooting.md index 4b414527..286b3344 100644 --- a/website/content/zh/troubleshooting.md +++ b/website/content/zh/troubleshooting.md @@ -17,61 +17,73 @@ ## 常见问题 (FAQs) - **Q: 如何将 Qwen Code 更新到最新版本？** - - A: 如果你是通过 `npm` 全局安装的，可以使用命令 `npm install -g @qwen-code/qwen-code@latest` 进行更新。如果你是从源码编译的，请从仓库拉取最新更改，然后使用命令 `npm run build` 重新构建。 + - A: 如果你是通过 `npm` 全局安装的，可以使用命令 `npm install -g @qwen-code/qwen-code@latest` 进行更新。如果你是从源码编译的，则需要从仓库拉取最新的更改，然后使用命令 `npm run build` 重新构建。 - **Q: Qwen Code 的配置或设置文件存储在哪里？** - - A: Qwen Code 的配置存储在两个 `settings.json` 文件中： - 1. 用户主目录下：`~/.qwen/settings.json`。 - 2. 项目根目录下：`./.qwen/settings.json`。 + - A: Qwen Code 的配置信息保存在两个 `settings.json` 文件中： + 1. 用户主目录下：`~/.qwen/settings.json` + 2. 项目根目录下：`./.qwen/settings.json` - 更多详情请参考 [Qwen Code 配置](./cli/configuration.md)。 + 更多详情请参考 [Qwen Code 配置说明](./cli/configuration.md)。 -- **Q: 为什么在统计输出中看不到缓存的 token 数量？** - - A: 缓存的 token 信息只有在使用缓存 token 时才会显示。此功能适用于 API key 用户（Qwen API key 或 Google Cloud Vertex AI），但不适用于 OAuth 用户（例如 Google 个人/企业账户，如 Google Gmail 或 Google Workspace）。这是因为 Qwen Code Assist API 不支持缓存内容的创建。你仍然可以使用 `/stats` 命令查看总 token 使用量。 +- **Q: 为什么我在统计输出中看不到缓存的 token 数量？** + - A: 缓存的 token 信息只有在实际使用了缓存时才会显示。此功能适用于 API key 用户（如 Qwen API key 或 Google Cloud Vertex AI），但不支持 OAuth 用户（例如 Google 个人账户或企业账户，如 Gmail 或 Google Workspace）。这是因为 Qwen Code Assist API 不支持创建缓存内容。你仍然可以通过 `/stats` 命令查看总的 token 使用情况。 ## 常见错误信息及解决方案 -- **错误：启动 MCP server 时出现 `EADDRINUSE`（地址已被占用）** +- **错误：启动 MCP server 时出现 `EADDRINUSE`（地址已被使用）** - **原因：** 另一个进程已经占用了 MCP server 尝试绑定的端口。 - **解决方案：** - 停止占用该端口的其他进程，或者配置 MCP server 使用不同的端口。 + 要么停止占用该端口的其他进程，要么配置 MCP server 使用不同的端口。 -- **错误：命令未找到（运行 `qwen` 时提示 Command not found）** - - **原因：** CLI 未正确安装，或未添加到系统的 `PATH` 中。 +- **错误：运行 `qwen` 命令时提示 “Command not found”** + - **原因：** CLI 没有正确安装，或者未添加到系统的 `PATH` 环境变量中。 - **解决方案：** - 更新方式取决于你安装 Qwen Code 的方式： - - 如果你是全局安装的 `qwen`，请确认你的 `npm` 全局二进制目录已加入 `PATH`。你可以使用命令 `npm install -g @qwen-code/qwen-code@latest` 进行更新。 - - 如果你是从源码运行 `qwen`，请确保使用了正确的命令来调用（例如：`node packages/cli/dist/index.js ...`）。要更新，请从仓库拉取最新更改，然后使用命令 `npm run build` 重新构建。 + 具体操作取决于你如何安装 Qwen Code： + - 如果你是全局安装了 `qwen`，请确认你的 `npm` 全局二进制目录已加入系统 `PATH`。你可以通过以下命令更新：`npm install -g @qwen-code/qwen-code@latest` + - 如果你是从源码运行 `qwen`，请确保使用正确的命令调用它（例如：`node packages/cli/dist/index.js ...`）。要更新的话，请先拉取仓库最新代码，然后执行构建命令：`npm run build` -- **错误：`MODULE_NOT_FOUND` 或导入错误** - - **原因：** 依赖未正确安装，或项目未构建。 +- **错误：`MODULE_NOT_FOUND` 或导入相关错误** + - **原因：** 依赖项没有正确安装，或项目尚未完成构建。 - **解决方案：** - 1. 运行 `npm install` 确保所有依赖已安装。 - 2. 运行 `npm run build` 编译项目。 - 3. 使用 `npm run start` 验证构建是否成功。 + 1. 运行 `npm install` 确保所有依赖都已安装。 + 2. 运行 `npm run build` 编译整个项目。 + 3. 执行 `npm run start` 验证是否成功启动。 -- **错误：提示“Operation not permitted”、“Permission denied”或类似信息** - - **原因：** 当沙箱（sandboxing）启用时，Qwen Code 可能尝试执行被沙箱配置限制的操作，例如在项目目录或系统临时目录之外进行写入。 - - **解决方案：** 请参考 [配置：沙箱](./cli/configuration.md#sandboxing) 文档获取更多信息，包括如何自定义沙箱配置。 +- **错误："Operation not permitted"、"Permission denied" 或类似问题** + - **原因：** 当启用沙箱机制后，Qwen Code 可能会尝试一些被沙箱策略限制的操作，比如在项目目录或系统临时目录之外进行写入。 + - **解决方案：** 更多详情以及自定义沙箱配置的方法，请参考文档 [Configuration: Sandboxing](./cli/configuration.md#sandboxing) -- **Qwen Code 在 “CI” 环境中未进入交互模式** - - **问题：** 如果设置了以 `CI_` 开头的环境变量（如 `CI_TOKEN`），Qwen Code 不会进入交互模式（不会显示提示符）。这是因为底层 UI 框架使用的 `is-in-ci` 包检测到这些变量后，会认为当前处于非交互式的 CI 环境。 - - **原因：** `is-in-ci` 包会检查是否存在 `CI`、`CONTINUOUS_INTEGRATION` 或任何以 `CI_` 为前缀的环境变量。一旦检测到，它会判定当前环境为非交互式，从而阻止 CLI 启动交互模式。 - - **解决方案：** 如果 CLI 不需要使用以 `CI_` 为前缀的变量，可以临时取消设置该变量。例如：`env -u CI_TOKEN qwen` +- **Qwen Code 在 CI 环境下无法进入交互模式** + - **现象：** 如果设置了以 `CI_` 开头的环境变量（如 `CI_TOKEN`），Qwen Code 不会进入交互模式（即不会显示输入提示符）。这是因为底层 UI 框架使用的 `is-in-ci` 包检测到了这些变量，并认为当前处于非交互式的 CI 环境。 + - **原因：** `is-in-ci` 包会检查是否存在 `CI`、`CONTINUOUS_INTEGRATION` 或任何以 `CI_` 为前缀的环境变量。一旦发现其中之一，就会判定为非交互式环境，从而阻止 CLI 启动交互模式。 + - **解决方案：** 若不需要这个 `CI_` 前缀的变量来驱动 CLI 功能，可以临时取消设置后再运行命令，例如：`env -u CI_TOKEN qwen` -- **从项目 .env 文件中无法启用 DEBUG 模式** - - **问题：** 在项目的 `.env` 文件中设置 `DEBUG=true` 无法启用 CLI 的 debug 模式。 - - **原因：** 为避免干扰 CLI 行为，`DEBUG` 和 `DEBUG_MODE` 变量会自动从项目 `.env` 文件中排除。 - - **解决方案：** 使用 `.qwen/.env` 文件代替，或在 `settings.json` 中配置 `excludedProjectEnvVars` 以减少被排除的变量。 +- **DEBUG 模式无法通过项目中的 .env 文件生效** + - **现象：** 即使你在项目的 `.env` 文件里设置了 `DEBUG=true`，也无法激活 CLI 的 debug 模式。 + - **原因：** 为了避免影响 CLI 行为，`DEBUG` 和 `DEBUG_MODE` 这两个变量会被自动排除在项目 `.env` 文件之外。 + - **解决方案：** 改用 `.qwen/.env` 文件来进行配置，或者修改你的 `settings.json` 中的 `excludedProjectEnvVars` 设置，减少被排除的变量数量。 ## IDE Companion 无法连接 - 确保 VS Code 中只打开一个 workspace folder。 -- 安装插件后重启集成终端，以便继承以下环境变量： +- 安装扩展后重启集成终端，以便继承以下环境变量： - `QWEN_CODE_IDE_WORKSPACE_PATH` - `QWEN_CODE_IDE_SERVER_PORT` -- 如果在容器中运行，请确认 `host.docker.internal` 可以正确解析。否则，请适当配置 host 映射。 -- 使用 `/ide install` 重新安装 companion，并通过 Command Palette 中的 “Qwen Code: Run” 命令验证其是否能正常启动。 +- 如果在容器中运行，请确认 `host.docker.internal` 可以解析。否则，请适当映射主机地址。 +- 使用 `/ide install` 重新安装 companion，并通过命令面板中的 "Qwen Code: Run" 来验证是否能正常启动。 + +## 退出码 + +Qwen Code 使用特定的退出码来指示终止的原因。这对于脚本编写和自动化特别有用。 + +| 退出码 | 错误类型 | 描述 | +| ------ | -------------------------- | ---------------------------------------------------------------------------------------------- | +| 41 | `FatalAuthenticationError` | 在认证过程中发生了错误。 | +| 42 | `FatalInputError` | 提供给 CLI 的输入无效或缺失。（仅限非交互模式） | +| 44 | `FatalSandboxError` | 沙箱环境（例如 Docker、Podman 或 Seatbelt）发生了错误。 | +| 52 | `FatalConfigError` | 配置文件（`settings.json`）无效或包含错误。 | +| 53 | `FatalTurnLimitedError` | 达到了会话的最大对话轮数。（仅限非交互模式） | ## 调试技巧 @@ -80,18 +92,18 @@ - 检查 CLI 日志，通常位于用户特定的配置或缓存目录中。 - **核心调试：** - - 检查服务器控制台输出中的错误信息或堆栈跟踪。 - - 如果可以配置，增加日志详细程度。 - - 如果需要逐步调试服务端代码，可以使用 Node.js 调试工具（例如 `node --inspect`）。 + - 查看服务器控制台输出中的错误信息或堆栈跟踪。 + - 如果可以配置，尝试提高日志详细程度。 + - 如需逐步调试服务端代码，可使用 Node.js 调试工具（例如 `node --inspect`）。 - **工具问题：** - 如果某个特定工具失败，尝试通过运行该工具执行的最简版本命令或操作来隔离问题。 - - 对于 `run_shell_command`，首先检查命令是否能在你的 shell 中直接运行。 - - 对于**文件系统工具**，验证路径是否正确并检查权限。 + - 对于 `run_shell_command`，先确认命令在你的 shell 中可以直接运行。 + - 对于_文件系统工具_，验证路径是否正确并检查权限设置。 - **预检检查：** - - 提交代码前始终运行 `npm run preflight`。这可以捕获许多与格式化、代码规范和类型错误相关的常见问题。 + - 提交代码前务必运行 `npm run preflight`。这能捕获许多常见的格式、linting 和类型错误问题。 -## 查找类似问题或创建新 Issue +## 查找类似的 GitHub Issues 或创建新 Issue -如果你遇到的问题未在本 _Troubleshooting guide_ 中提及，建议先搜索 Qwen Code 的 [GitHub Issue tracker](https://github.com/QwenLM/qwen-code/issues)。如果找不到与你问题相似的 Issue，欢迎创建一个新的 GitHub Issue 并提供详细描述。我们也欢迎你提交 Pull requests！ \ No newline at end of file +如果你遇到的问题未在本 _故障排除指南_ 中涵盖，建议搜索 Qwen Code 的 [GitHub Issue 跟踪器](https://github.com/QwenLM/qwen-code/issues)。如果找不到与你问题相似的 Issue，欢迎创建一个新的 GitHub Issue，并提供详细描述。我们也欢迎 Pull Request！ \ No newline at end of file diff --git a/website/src/components/comparison-section.tsx b/website/src/components/comparison-section.tsx index 6b45aaa2..465022da 100644 --- a/website/src/components/comparison-section.tsx +++ b/website/src/components/comparison-section.tsx @@ -49,7 +49,37 @@ const comparisonFeatures = [ }, { name: "SubAgent Support", - qwen: "in progress", + qwen: true, + claude: true, + }, + { + name: "SDK Support", + qwen: "todo", + claude: true, + }, + { + name: "GitHub Actions Integration", + qwen: "todo", + claude: true, + }, + { + name: "Output Style Customization", + qwen: "todo", + claude: true, + }, + { + name: "Hooks System", + qwen: "todo", + claude: true, + }, + { + name: "Git Worktree Support", + qwen: "todo", + claude: true, + }, + { + name: "Permission Management", + qwen: "todo", claude: true, }, ], @@ -106,12 +136,12 @@ const comparisonFeatures = [ }, { name: "Git Integration", - qwen: "basic", + qwen: true, claude: true, }, { name: "IDE Integration", - qwen: "basic", + qwen: true, claude: true, }, ], @@ -156,7 +186,7 @@ const getFeatureIcon = (status: boolean | string) => { return ; } else if (status === "2000/day") { return ( - + {status} ); @@ -164,7 +194,7 @@ const getFeatureIcon = (status: boolean | string) => { return ( {status} @@ -202,8 +232,8 @@ export const ComparisonSection = () => { {/* Advantage Badge */}
- - 🏆 Recommended + + ⭐ Free & Open Source,Worth Waiting!
@@ -214,9 +244,6 @@ export const ComparisonSection = () => {

Qwen Code

- - Free & Open Source -
@@ -297,7 +324,13 @@ export const ComparisonSection = () => {
{/* Claude Code Card */} - + + {/* Advantage Badge */} +
+ + 🏆 Commercial Solution, Recommended! + +
@@ -305,9 +338,6 @@ export const ComparisonSection = () => {

Claude Code

- - Commercial Solution -
diff --git a/website/src/components/features-section.tsx b/website/src/components/features-section.tsx index 6109789f..97299eb8 100644 --- a/website/src/components/features-section.tsx +++ b/website/src/components/features-section.tsx @@ -119,7 +119,7 @@ export const FeaturesSection = () => { {architectureFeatures.map((feature, index) => (
diff --git a/website/src/components/hero-section.tsx b/website/src/components/hero-section.tsx index 58bfaa12..e4b50636 100644 --- a/website/src/components/hero-section.tsx +++ b/website/src/components/hero-section.tsx @@ -34,7 +34,9 @@ export const HeroSection = () => {

A coding agent
- that lives in digital world. + + that lives in the digital world +

{/* Subheading */} @@ -55,7 +57,7 @@ export const HeroSection = () => {
-
+
user@machine : @@ -65,7 +67,7 @@ export const HeroSection = () => { npm install -g @qwen-code/qwen-code
-
+
✓ Package installed successfully
@@ -75,7 +77,15 @@ export const HeroSection = () => { $ qwen
-
+ 
+                {`██╗       ██████╗ ██╗    ██╗███████╗███╗   ██╗
+╚██╗     ██╔═══██╗██║    ██║██╔════╝████╗  ██║
+ ╚██╗    ██║   ██║██║ █╗ ██║█████╗  ██╔██╗ ██║
+ ██╔╝    ██║▄▄ ██║██║███╗██║██╔══╝  ██║╚██╗██║
+██╔╝     ╚██████╔╝╚███╔███╔╝███████╗██║ ╚████║
+╚═╝       ╚══▀▀═╝  ╚══╝╚══╝ ╚══════╝╚═╝  ╚═══╝`}
+
+
Welcome to Qwen Code! Type /help for commands.
@@ -87,7 +97,7 @@ export const HeroSection = () => {
-

+

Install Node.js 18+, then run the command above

@@ -97,15 +107,15 @@ export const HeroSection = () => {
- 10.4k+ GitHub Stars + 14.4k+ GitHub Stars
- 753 Forks + 1.1k Forks
- 2k+ Active Users + 10k+ Active Users
diff --git a/website/src/page/index.tsx b/website/src/page/index.tsx index d534d8be..bc9491f8 100644 --- a/website/src/page/index.tsx +++ b/website/src/page/index.tsx @@ -13,23 +13,27 @@ const Index = () => {
- {/* 桌面端显示完整logo */} - - Qwen Code - Qwen Code + <> + + Qwen Code + + Qwen - + + Code + + + } projectLink='https://github.com/QwenLM/qwen-code' /> diff --git a/website/translation-changelog.json b/website/translation-changelog.json index b0b432a9..2a179a41 100644 --- a/website/translation-changelog.json +++ b/website/translation-changelog.json @@ -1,4 +1,117 @@ [ + { + "timestamp": "2025-10-16T03:26:44.011Z", + "commit": "9d664623f56dfd025d21c84cedcf63851689248b", + "sourceLanguage": "en", + "translatedFiles": { + "zh": { + "success": [ + "cli/commands.md", + "cli/configuration.md", + "cli/themes.md", + "deployment.md", + "examples/proxy-script.md", + "extension.md", + "gemini-ignore.md", + "ide-integration.md", + "index.md", + "keyboard-shortcuts.md", + "qwen-ignore.md", + "subagents.md", + "telemetry.md", + "tools/multi-file.md", + "troubleshooting.md" + ], + "failed": [] + }, + "de": { + "success": [ + "cli/commands.md", + "cli/configuration.md", + "cli/themes.md", + "deployment.md", + "examples/proxy-script.md", + "extension.md", + "gemini-ignore.md", + "ide-integration.md", + "index.md", + "keyboard-shortcuts.md", + "qwen-ignore.md", + "subagents.md", + "telemetry.md", + "tools/multi-file.md", + "troubleshooting.md" + ], + "failed": [] + }, + "fr": { + "success": [ + "cli/commands.md", + "cli/configuration.md", + "cli/themes.md", + "deployment.md", + "examples/proxy-script.md", + "extension.md", + "gemini-ignore.md", + "ide-integration.md", + "index.md", + "keyboard-shortcuts.md", + "qwen-ignore.md", + "subagents.md", + "telemetry.md", + "tools/multi-file.md", + "troubleshooting.md" + ], + "failed": [] + }, + "ru": { + "success": [ + "cli/commands.md", + "cli/configuration.md", + "cli/themes.md", + "deployment.md", + "examples/proxy-script.md", + "extension.md", + "gemini-ignore.md", + "ide-integration.md", + "index.md", + "keyboard-shortcuts.md", + "qwen-ignore.md", + "subagents.md", + "telemetry.md", + "tools/multi-file.md", + "troubleshooting.md" + ], + "failed": [] + }, + "ja": { + "success": [ + "cli/commands.md", + "cli/configuration.md", + "cli/themes.md", + "deployment.md", + "examples/proxy-script.md", + "extension.md", + "gemini-ignore.md", + "ide-integration.md", + "index.md", + "keyboard-shortcuts.md", + "qwen-ignore.md", + "subagents.md", + "telemetry.md", + "tools/multi-file.md", + "troubleshooting.md" + ], + "failed": [] + } + }, + "stats": { + "totalFiles": 15, + "languages": 5, + "successCount": 75, + "failedCount": 0 + } + }, { "timestamp": "2025-09-12T09:44:34.622Z", "commit": "67e2e270bd548ab9845f3e0d99f0b35423ae94da",