From 50bf3efac453815a256d18e779efa86d3c54093e Mon Sep 17 00:00:00 2001 From: pomelo-nwu Date: Thu, 28 Aug 2025 21:30:47 +0800 Subject: [PATCH 1/3] feat: sort docs --- website/app/[lang]/layout.tsx | 9 ++++----- website/content/zh/_meta.ts | 21 +++++++++++++++++++++ website/content/zh/cli/_meta.ts | 10 ++++++++++ website/content/zh/core/_meta.ts | 5 +++++ website/content/zh/examples/_meta.ts | 3 +++ website/content/zh/tools/_meta.ts | 10 ++++++++++ 6 files changed, 53 insertions(+), 5 deletions(-) create mode 100644 website/content/zh/_meta.ts create mode 100644 website/content/zh/cli/_meta.ts create mode 100644 website/content/zh/core/_meta.ts create mode 100644 website/content/zh/examples/_meta.ts create mode 100644 website/content/zh/tools/_meta.ts diff --git a/website/app/[lang]/layout.tsx b/website/app/[lang]/layout.tsx index 458e3d80..426ca050 100644 --- a/website/app/[lang]/layout.tsx +++ b/website/app/[lang]/layout.tsx @@ -6,6 +6,8 @@ import { Banner, Head } from "nextra/components"; import { getPageMap } from "nextra/page-map"; import { LanguageDropdown } from "../../src/components/language-dropdown"; import type { FC, ReactNode } from "react"; +import fs from "fs"; +import path from "path"; type LayoutProps = Readonly<{ children: ReactNode; @@ -20,10 +22,7 @@ const LanguageLayout: FC = async ({ children, params }) => { let sourcePageMap = await getPageMap(`/${lang}`); //@ts-ignore - const { children: pageMap } = sourcePageMap.find((page) => { - //@ts-ignore - return page.name === lang; - }); + // 用fs模块将sourcePageMap保存到本地 const banner = ( @@ -81,7 +80,7 @@ const LanguageLayout: FC = async ({ children, params }) => { defaultMenuCollapseLevel: 1, autoCollapse: true, }} - pageMap={pageMap} + pageMap={sourcePageMap} nextThemes={{ defaultTheme: "light" }} > {children} diff --git a/website/content/zh/_meta.ts b/website/content/zh/_meta.ts new file mode 100644 index 00000000..4430ba56 --- /dev/null +++ b/website/content/zh/_meta.ts @@ -0,0 +1,21 @@ +export default { + index: "欢迎阅读 Qwen Code 文档", + deployment: "执行与部署", + architecture: "架构概述", + cli: "CLI 使用指南", + core: "核心详情", + tools: "工具集合", + checkpointing: "检查点功能", + extension: "扩展开发", + telemetry: "可观测性", + examples: "示例代码", + npm: "包管理", + "gemini-ignore": "忽略文件配置", + "integration-tests": "集成测试", + "keyboard-shortcuts": "快捷键参考", + sandbox: "沙箱机制", + "issue-and-pr-automation": "自动化处理", + troubleshooting: "故障排除", + "tos-privacy": "服务条款与隐私", + Uninstall: "卸载指南", +}; diff --git a/website/content/zh/cli/_meta.ts b/website/content/zh/cli/_meta.ts new file mode 100644 index 00000000..1d9b72cc --- /dev/null +++ b/website/content/zh/cli/_meta.ts @@ -0,0 +1,10 @@ +export default { + index: "CLI 概述", + commands: "命令参考", + configuration: "配置指南", + authentication: "认证设置", + "openai-auth": "OpenAI 认证", + "token-caching": "Token 缓存", + themes: "主题配置", + tutorials: "使用教程", +}; diff --git a/website/content/zh/core/_meta.ts b/website/content/zh/core/_meta.ts new file mode 100644 index 00000000..59b5a05d --- /dev/null +++ b/website/content/zh/core/_meta.ts @@ -0,0 +1,5 @@ +export default { + index: "核心概述", + "tools-api": "工具 API", + memport: "内存导入处理器", +}; diff --git a/website/content/zh/examples/_meta.ts b/website/content/zh/examples/_meta.ts new file mode 100644 index 00000000..cbc807e2 --- /dev/null +++ b/website/content/zh/examples/_meta.ts @@ -0,0 +1,3 @@ +export default { + "proxy-script": "代理脚本示例", +}; diff --git a/website/content/zh/tools/_meta.ts b/website/content/zh/tools/_meta.ts new file mode 100644 index 00000000..3cb5da27 --- /dev/null +++ b/website/content/zh/tools/_meta.ts @@ -0,0 +1,10 @@ +export default { + index: "工具概述", + "file-system": "文件系统工具", + "multi-file": "多文件读取工具", + shell: "Shell 工具", + "web-fetch": "Web 获取工具", + "web-search": "Web 搜索工具", + memory: "内存工具", + "mcp-server": "MCP 服务器", +}; From f70cce266ac06bffd5162be6e4a04d30f4c5a668 Mon Sep 17 00:00:00 2001 From: pomelo-nwu Date: Thu, 28 Aug 2025 21:35:55 +0800 Subject: [PATCH 2/3] feat: sync 0.0.9 version --- website/content/de/cli/configuration.md | 200 ++++++++++--------- website/content/de/deployment.md | 20 +- website/content/de/ide-integration.md | 141 ++++++++++++++ website/content/de/index.md | 25 +-- website/content/de/integration-tests.md | 45 ++--- website/content/de/npm.md | 82 ++++---- website/content/de/tools/file-system.md | 74 ++++--- website/content/de/tools/index.md | 31 +-- website/content/de/tools/shell.md | 87 +++++++-- website/content/de/tools/todo-write.md | 63 ++++++ website/content/de/troubleshooting.md | 38 ++-- website/content/en/cli/configuration.md | 9 +- website/content/en/deployment.md | 2 +- website/content/en/ide-integration.md | 141 ++++++++++++++ website/content/en/index.md | 1 + website/content/en/integration-tests.md | 16 +- website/content/en/npm.md | 2 +- website/content/en/tools/file-system.md | 30 +++ website/content/en/tools/index.md | 1 + website/content/en/tools/shell.md | 69 ++++++- website/content/en/tools/todo-write.md | 63 ++++++ website/content/en/troubleshooting.md | 5 + website/content/fr/cli/configuration.md | 125 ++++++------ website/content/fr/deployment.md | 16 +- website/content/fr/ide-integration.md | 141 ++++++++++++++ website/content/fr/index.md | 15 +- website/content/fr/integration-tests.md | 35 ++-- website/content/fr/npm.md | 62 +++--- website/content/fr/tools/file-system.md | 106 ++++++---- website/content/fr/tools/index.md | 21 +- website/content/fr/tools/shell.md | 85 ++++++-- website/content/fr/tools/todo-write.md | 63 ++++++ website/content/fr/troubleshooting.md | 68 +++---- website/content/ja/cli/configuration.md | 245 ++++++++++++------------ website/content/ja/deployment.md | 27 +-- website/content/ja/ide-integration.md | 141 ++++++++++++++ website/content/ja/index.md | 23 +-- website/content/ja/integration-tests.md | 51 +++-- website/content/ja/npm.md | 134 +++++++------ website/content/ja/tools/file-system.md | 116 ++++++----- website/content/ja/tools/index.md | 37 ++-- website/content/ja/tools/shell.md | 99 +++++++--- website/content/ja/tools/todo-write.md | 63 ++++++ website/content/ja/troubleshooting.md | 41 ++-- website/content/ru/cli/configuration.md | 174 +++++++++-------- website/content/ru/deployment.md | 14 +- website/content/ru/ide-integration.md | 141 ++++++++++++++ website/content/ru/index.md | 17 +- website/content/ru/integration-tests.md | 41 ++-- website/content/ru/npm.md | 127 ++++++------ website/content/ru/tools/file-system.md | 62 ++++-- website/content/ru/tools/index.md | 23 +-- website/content/ru/tools/shell.md | 101 +++++++--- website/content/ru/tools/todo-write.md | 63 ++++++ website/content/ru/troubleshooting.md | 40 ++-- website/content/zh/cli/configuration.md | 189 +++++++++--------- website/content/zh/deployment.md | 8 +- website/content/zh/ide-integration.md | 139 ++++++++++++++ website/content/zh/index.md | 5 +- website/content/zh/integration-tests.md | 60 +++--- website/content/zh/npm.md | 92 ++++----- website/content/zh/tools/file-system.md | 68 +++++-- website/content/zh/tools/index.md | 29 +-- website/content/zh/tools/shell.md | 109 ++++++++--- website/content/zh/tools/todo-write.md | 63 ++++++ website/content/zh/troubleshooting.md | 45 +++-- website/translation-changelog.json | 93 +++++++++ 67 files changed, 3201 insertions(+), 1361 deletions(-) create mode 100644 website/content/de/ide-integration.md create mode 100644 website/content/de/tools/todo-write.md create mode 100644 website/content/en/ide-integration.md create mode 100644 website/content/en/tools/todo-write.md create mode 100644 website/content/fr/ide-integration.md create mode 100644 website/content/fr/tools/todo-write.md create mode 100644 website/content/ja/ide-integration.md create mode 100644 website/content/ja/tools/todo-write.md create mode 100644 website/content/ru/ide-integration.md create mode 100644 website/content/ru/tools/todo-write.md create mode 100644 website/content/zh/ide-integration.md create mode 100644 website/content/zh/tools/todo-write.md diff --git a/website/content/de/cli/configuration.md b/website/content/de/cli/configuration.md index 87669f2f..6f50669b 100644 --- a/website/content/de/cli/configuration.md +++ b/website/content/de/cli/configuration.md @@ -22,18 +22,18 @@ Qwen Code verwendet `settings.json` Dateien für die persistente Konfiguration. - **Scope:** Gilt für alle Qwen Code Sessions des aktuellen Benutzers. - **Project settings file:** - **Location:** `.qwen/settings.json` innerhalb des Root-Verzeichnisses deines Projekts. - - **Scope:** Gilt nur, wenn Qwen Code aus diesem spezifischen Projekt heraus gestartet wird. Project settings überschreiben User settings. + - **Scope:** Gilt nur, wenn Qwen Code aus diesem spezifischen Projekt heraus gestartet wird. Projekt-Einstellungen überschreiben User-Einstellungen. - **System settings file:** - **Location:** `/etc/gemini-cli/settings.json` (Linux), `C:\ProgramData\gemini-cli\settings.json` (Windows) oder `/Library/Application Support/GeminiCli/settings.json` (macOS). Der Pfad kann mit der Umgebungsvariable `GEMINI_CLI_SYSTEM_SETTINGS_PATH` überschrieben werden. - - **Scope:** 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 Setups der Benutzer zu haben. + - **Scope:** Gilt für alle Qwen Code Sessions 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 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 z. B. eine Umgebungsvariable `MY_API_TOKEN` hast, kannst du sie in der `settings.json` so verwenden: `"apiKey": "$MY_API_TOKEN"`. +**Hinweis zu Umgebungsvariablen in Einstellungen:** 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 Einstellungen geladen werden. Wenn du z. B. eine Umgebungsvariable `MY_API_TOKEN` hast, kannst du sie 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`: @@ -58,8 +58,8 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt - **Beschreibung:** Steuert das git-basierte Dateifilterverhalten für @-Befehle und Datei-Suchwerkzeuge. - **Standard:** `"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 Dateilistenoperationen ausgeschlossen. - - **`enableRecursiveFileSearch`** (boolean): Ob rekursive Suche nach Dateinamen unterhalb des aktuellen Verzeichnisses aktiviert werden soll, wenn @-Präfixe im Prompt vervollständigt werden. + - **`respectGitIgnore`** (boolean): Gibt an, ob `.gitignore`-Muster bei der Dateierkennung berücksichtigt werden. Bei `true` werden git-ignorierte Dateien (wie `node_modules/`, `dist/`, `.env`) automatisch von @-Befehlen und Dateilisten ausgeschlossen. + - **`enableRecursiveFileSearch`** (boolean): Gibt an, ob rekursiv nach Dateinamen unterhalb des aktuellen Verzeichnisses gesucht wird, wenn @-Präfixe im Prompt vervollständigt werden. - **Beispiel:** ```json "fileFiltering": { @@ -69,30 +69,30 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt ``` - **`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 Befehlsspezifische Einschränkungen für Tools wie `ShellTool` festgelegt werden. Beispiel: `"coreTools": ["ShellTool(ls -l)"]` erlaubt nur die Ausführung von `ls -l`. + - **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 Befehlsspezifische Einschränkungen für Tools wie `ShellTool` festgelegt werden. Beispiel: `"coreTools": ["ShellTool(ls -l)"]` erlaubt nur die Ausführung des `ls -l`-Befehls. - **Standard:** Alle Tools, die dem Modell zur Verfügung stehen. - **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 Befehlsspezifische Einschränkungen für Tools wie `ShellTool` festgelegt werden. Beispiel: `"excludeTools": ["ShellTool(rm -rf)"]` blockiert den Befehl `rm -rf`. + - **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. Auch hier können Befehlsspezifische Einschränkungen wie bei `ShellTool` verwendet werden. Beispiel: `"excludeTools": ["ShellTool(rm -rf)"]` blockiert den `rm -rf`-Befehl. - **Standard:** Keine Tools ausgeschlossen. - **Beispiel:** `"excludeTools": ["run_shell_command", "findFiles"]`. - - **Sicherheitshinweis:** Befehlsspezifische Einschränkungen in `excludeTools` für `run_shell_command` 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 die ausführbaren Befehle auszuwählen. + - **Sicherheitshinweis:** Befehlsspezifische Einschränkungen in `excludeTools` für `run_shell_command` basieren auf einfacher Stringvergleichung und können leicht umgangen werden. Diese Funktion ist **kein Sicherheitsmechanismus** und sollte nicht verwendet werden, um nicht vertrauenswürdigen Code sicher auszuführen. Es wird empfohlen, `coreTools` zu verwenden, um explizit die erlaubten Befehle auszuwählen. - **`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 MCP-Server eingeschränkt werden, mit denen eine Verbindung hergestellt wird. Diese Einstellung wird ignoriert, wenn `--allowed-mcp-server-names` gesetzt ist. + - **Beschreibung:** Ermöglicht es, eine Liste von MCP-Servernamen anzugeben, die dem Modell zur Verfügung gestellt werden sollen. Damit kann die Menge der MCP-Server eingeschränkt werden, mit denen verbunden wird. Diese Einstellung wird ignoriert, wenn `--allowed-mcp-server-names` gesetzt ist. - **Standard:** Alle MCP-Server stehen dem Modell zur Verfügung. - **Beispiel:** `"allowMCPServers": ["myPythonServer"]`. - - **Sicherheitshinweis:** Diese Einstellung verwendet einfache Stringvergleiche für MCP-Servernamen, die manipuliert werden können. Wenn du als Systemadministrator verhindern möchtest, dass Benutzer diese Einstellung umgehen, solltest du `mcpServers` auf Systemebene konfigurieren, sodass Benutzer keine eigenen MCP-Server konfigurieren können. Diese Funktion sollte **nicht als absoluter Sicherheitsmechanismus** betrachtet werden. + - **Sicherheitshinweis:** Diese Funktion verwendet einfache Stringvergleiche für MCP-Servernamen, die manipuliert werden können. Als Systemadministrator sollten Sie ggf. die `mcpServers` auf Systemebene konfigurieren, sodass Benutzer keine eigenen Server konfigurieren können. Diese Funktion sollte **nicht als sicherer 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. - **Beispiel:** `"excludeMCPServers": ["myNodeServer"]`. - - **Sicherheitshinweis:** Diese Einstellung verwendet einfache Stringvergleiche für MCP-Servernamen, die manipuliert werden können. Wenn du als Systemadministrator verhindern möchtest, dass Benutzer diese Einstellung umgehen, solltest du `mcpServers` auf Systemebene konfigurieren, sodass Benutzer keine eigenen MCP-Server konfigurieren können. Diese Funktion sollte **nicht als absoluter Sicherheitsmechanismus** betrachtet werden. + - **Sicherheitshinweis:** Diese Funktion verwendet einfache Stringvergleiche für MCP-Servernamen, die manipuliert werden können. Als Systemadministrator sollten Sie ggf. die `mcpServers` auf Systemebene konfigurieren, sodass Benutzer keine eigenen Server konfigurieren können. Diese Funktion sollte **nicht als sicherer Sicherheitsmechanismus betrachtet werden**. - **`autoAccept`** (boolean): - - **Beschreibung:** Legt fest, ob die CLI automatisch sichere Tool-Aufrufe (z. B. schreibgeschützte Operationen) akzeptiert und ausführt, ohne explizite Benutzerbestätigung. Bei `true` wird die Bestätigungsabfrage für als sicher eingestufte Tools übersprungen. + - **Beschreibung:** Legt fest, ob die CLI Tool-Aufrufe, die als sicher gelten (z. B. reine Leseoperationen), automatisch akzeptiert und ausgeführt werden, ohne explizite Benutzerbestätigung. Bei `true` wird die Bestätigungsabfrage für sichere Tools übersprungen. - **Standard:** `false` - **Beispiel:** `"autoAccept": true` @@ -102,30 +102,30 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt - **Beispiel:** `"theme": "GitHub"` - **`vimMode`** (boolean): - - **Beschreibung:** Aktiviert oder deaktiviert den vim-Modus für die Eingabebearbeitung. Wenn aktiviert, unterstützt der Eingabebereich vim-ähnliche Navigation und Bearbeitungsbefehle mit NORMAL- und INSERT-Modus. Der vim-Modus-Status wird in der Fußzeile angezeigt und bleibt zwischen Sitzungen erhalten. + - **Beschreibung:** Aktiviert oder deaktiviert den Vim-Modus für die Eingabebearbeitung. Im aktivierten Zustand unterstützt der Eingabebereich Vim-ähnliche Navigation und Bearbeitungsbefehle mit NORMAL- und INSERT-Modus. Der Status wird in der Fußzeile angezeigt und bleibt zwischen Sitzungen erhalten. - **Standard:** `false` - **Beispiel:** `"vimMode": true` - **`sandbox`** (boolean oder string): - - **Beschreibung:** Steuert, ob und wie Sandboxing für die Toolausführung verwendet wird. Bei `true` verwendet Qwen Code ein vorgefertigtes `qwen-code-sandbox` Docker-Image. Weitere Informationen findest du unter [Sandboxing](#sandboxing). + - **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` - **Beispiel:** `"sandbox": "docker"` - **`toolDiscoveryCommand`** (string): - - **Beschreibung:** Definiert einen benutzerdefinierten Shell-Befehl zum Auffinden von Tools aus deinem Projekt. Der Shell-Befehl muss auf `stdout` ein JSON-Array von [Funktionsdeklarationen](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) zurückgeben. Tool-Wrapper sind optional. + - **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-Wrapper sind optional. - **Standard:** 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 Shell-Befehl muss folgende Kriterien erfüllen: - - Er muss den Funktionsnamen (genau wie in der [Funktionsdeklaration](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). + - **Beschreibung:** Definiert einen benutzerdefinierten Shell-Befehl zum Aufruf eines spezifischen 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 - **Beispiel:** `"toolCallCommand": "bin/call_tool"` - **`mcpServers`** (object): - - **Beschreibung:** Konfiguriert Verbindungen zu einem oder mehreren Model-Context Protocol (MCP)-Servern zum Auffinden und Verwenden benutzerdefinierter Tools. Qwen Code versucht, sich mit jedem konfigurierten MCP-Server zu verbinden, um verfügbare Tools zu erkennen. Wenn mehrere MCP-Server ein Tool mit demselben Namen bereitstellen, werden die Toolnamen mit dem Server-Alias aus der Konfiguration vorangestellt (z. B. `serverAlias__actualToolName`), um Konflikte zu vermeiden. Beachte, dass das System bestimmte Schema-Eigenschaften aus MCP-Tooldefinitionen aus Kompatibilitätsgründen entfernen kann. + - **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 dem Toolname der 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. - **Standard:** Leer - **Eigenschaften:** - **``** (object): Die Serverparameter für den benannten Server. @@ -134,9 +134,9 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt - `env` (object, optional): Umgebungsvariablen, die für den Serverprozess gesetzt werden. - `cwd` (string, optional): Das Arbeitsverzeichnis, in dem der Server gestartet wird. - `timeout` (number, optional): Zeitlimit in Millisekunden für Anfragen an diesen MCP-Server. - - `trust` (boolean, optional): Vertraue diesem Server und umgehe alle Tool-Aufrufbestätigungen. - - `includeTools` (Array von Strings, optional): Liste der Toolnamen, die von diesem MCP-Server verwendet werden sollen. Wenn angegeben, sind nur die hier aufgelisteten Tools vom Server verfügbar (Whitelist-Verhalten). Wenn nicht angegeben, sind standardmäßig alle Tools des Servers aktiviert. - - `excludeTools` (Array von Strings, optional): Liste der Toolnamen, die von diesem MCP-Server ausgeschlossen werden sollen. Die hier aufgelisteten Tools stehen dem Modell nicht zur Verfügung, auch wenn sie vom Server bereitgestellt werden. **Hinweis:** `excludeTools` hat Vorrang vor `includeTools` – wenn ein Tool in beiden Listen steht, wird es ausgeschlossen. + - `trust` (boolean, optional): Vertraue diesem Server und umgehe alle Tool-Bestätigungen. + - `includeTools` (Array von Strings, optional): Liste der Toolnamen, die von diesem Server verwendet werden sollen. Wenn angegeben, sind nur diese Tools verfügbar (Whitelist-Verhalten). Ohne Angabe sind standardmäßig alle Tools des Servers aktiv. + - `excludeTools` (Array von Strings, optional): Liste der Toolnamen, die von diesem Server ausgeschlossen werden sollen. Diese Tools stehen dem Modell nicht zur Verfügung, auch 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": { @@ -164,10 +164,10 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt ``` - **`checkpointing`** (object): - - **Beschreibung:** Konfiguriert die Checkpointing-Funktion, mit der du Gesprächs- und Dateizustände speichern und wiederherstellen kannst. Weitere Informationen findest du in der [Checkpointing-Dokumentation](../checkpointing.md). + - **Beschreibung:** Konfiguriert die Checkpointing-Funktion, mit der Konversations- und Dateizustände gespeichert und wiederhergestellt werden können. Siehe [Checkpointing-Dokumentation](../checkpointing.md) für weitere Details. - **Standard:** `{"enabled": false}` - **Eigenschaften:** - - **`enabled`** (boolean): Wenn `true`, ist der `/restore`-Befehl verfügbar. + - **`enabled`** (boolean): Bei `true` ist der `/restore`-Befehl verfügbar. - **`preferredEditor`** (string): - **Beschreibung:** Gibt den bevorzugten Editor zum Anzeigen von Diffs an. @@ -175,13 +175,13 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt - **Beispiel:** `"preferredEditor": "vscode"` - **`telemetry`** (object) - - **Beschreibung:** Konfiguriert Logging und Metrikerfassung für Qwen Code. Weitere Informationen findest du unter [Telemetry](../telemetry.md). + - **Beschreibung:** Konfiguriert Logging und Metrikerfassung für Qwen Code. Weitere Informationen unter [Telemetry](../telemetry.md). - **Standard:** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **Eigenschaften:** - - **`enabled`** (boolean): Ob Telemetrie aktiviert ist. - - **`target`** (string): Das Ziel für gesammelte 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. + - **`enabled`** (boolean): Gibt an, 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): Gibt an, ob der Inhalt von Benutzerprompts in die Logs aufgenommen wird. - **Beispiel:** ```json "telemetry": { @@ -193,7 +193,7 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt ``` - **`usageStatisticsEnabled`** (boolean): - - **Beschreibung:** Aktiviert oder deaktiviert die Erfassung von Nutzungsstatistiken. Weitere Informationen findest du unter [Usage Statistics](#usage-statistics). + - **Beschreibung:** Aktiviert oder deaktiviert die Erfassung von Nutzungsstatistiken. Siehe [Usage Statistics](#usage-statistics) für weitere Informationen. - **Standard:** `true` - **Beispiel:** ```json @@ -217,7 +217,7 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt ``` - **`maxSessionTurns`** (number): - - **Beschreibung:** Legt die maximale Anzahl an Turns pro Sitzung fest. Wenn die Sitzung dieses Limit überschreitet, stoppt die CLI die Verarbeitung und startet einen neuen Chat. + - **Beschreibung:** Legt die maximale Anzahl an Turns pro Sitzung fest. Wenn das Limit überschritten wird, stoppt die CLI die Verarbeitung und startet einen neuen Chat. - **Standard:** `-1` (unbegrenzt) - **Beispiel:** ```json @@ -225,7 +225,7 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt ``` - **`summarizeToolOutput`** (object): - - **Beschreibung:** Aktiviert oder deaktiviert die Zusammenfassung der Toolausgabe. Du kannst das Token-Budget für die Zusammenfassung über die `tokenBudget`-Einstellung festlegen. + - **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:** @@ -238,12 +238,15 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt ``` - **`excludedProjectEnvVars`** (Array von Strings): - - **Beschreibung:** Gibt Umgebungsvariablen an, die beim Laden aus Projekt-`.env`-Dateien ausgeschlossen werden sollen. Dadurch wird verhindert, dass projektspezifische Umgebungsvariablen (wie `DEBUG=true`) das CLI-Verhalten beeinträchtigen. Variablen aus `.qwen/.env`-Dateien werden nie ausgeschlossen. + - **Beschreibung:** Gibt Umgebungsvariablen an, die aus Projekt-`.env`-Dateien ausgeschlossen werden sollen. Dadurch wird verhindert, dass projektspezifische Variablen (wie `DEBUG=true`) das CLI-Verhalten beeinflussen. Variablen aus `.qwen/.env`-Dateien werden nie ausgeschlossen. - **Standard:** `["DEBUG", "DEBUG_MODE"]` - **Beispiel:** ```json "excludedProjectEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"] - `` + ``` + +- **`includeDirectories`** (Array von Strings): + - **Beschreibung:** Gibt ein Array zusätzlicher absoluter oder relativer Pfade an, die in den Workspace-Kontext aufgenommen werden sollen. Damit können Dateien aus mehreren Verzeichnissen so behandelt werden, als befänden sie sich in einem einzigen Verzeichnis. Pfade können `~` verwenden, um sich auf das Home-Verzeichnis des Benutzers zu beziehen. Diese Einstellung kann mit ### Beispiel `settings.json`: @@ -292,36 +295,36 @@ Die CLI speichert einen Verlauf der Shell-Befehle, die du ausführst. Um Konflik - `` 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. -## Umgebungsvariablen & `.env` Dateien +## 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 Umgebungen unterscheiden können. -Die CLI lädt Umgebungsvariablen automatisch aus einer `.env` Datei. Die Ladereihenfolge ist: +Die CLI lädt Umgebungsvariablen automatisch 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 nach einer `.env` Datei, bis entweder eine gefunden wird oder das Projektverzeichnis (erkennbar an einem `.git` Ordner) oder das Home-Verzeichnis erreicht ist. -3. Wenn immer noch keine 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, 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. -**Ausschluss von Umgebungsvariablen:** Einige Umgebungsvariablen (wie `DEBUG` und `DEBUG_MODE`) werden standardmäßig aus Projekt `.env` Dateien ausgeschlossen, um Interferenzen mit dem 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:** Einige Umgebungsvariablen (wie `DEBUG` und `DEBUG_MODE`) werden standardmäßig aus Projekt-`.env`-Dateien ausgeschlossen, um Interferenzen mit dem 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. -- **`GEMINI_API_KEY`** (Erforderlich): +- **`GEMINI_API_KEY`** (erforderlich): - Dein API key für die Gemini API. - - **Wichtig für den Betrieb.** Ohne diesen funktioniert die CLI nicht. - - Setze ihn in deinem Shell-Profil (z. B. `~/.bashrc`, `~/.zshrc`) oder in einer `.env` Datei. + - **Wichtig für den Betrieb.** Die CLI funktioniert ohne diesen key nicht. + - Setze ihn in deinem Shell-Profil (z. B. `~/.bashrc`, `~/.zshrc`) oder in einer `.env`-Datei. - **`GEMINI_MODEL`**: - - Legt das Standard-Gemini-Modell fest. + - Legt das standardmäßig zu verwendende Gemini-Modell fest. - Überschreibt den fest codierten Standardwert. - Beispiel: `export GEMINI_MODEL="gemini-2.5-flash"` - **`GOOGLE_API_KEY`**: - Dein Google Cloud API key. - - Erforderlich für die Nutzung von Vertex AI im Express-Modus. + - Erforderlich für die Nutzung von Vertex AI im express mode. - Stelle sicher, dass du die nötigen Berechtigungen hast. - Beispiel: `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`. - **`GOOGLE_CLOUD_PROJECT`**: - Deine Google Cloud Project ID. - Erforderlich für die Nutzung von Code Assist oder Vertex AI. - - Bei Verwendung von Vertex AI stelle sicher, dass du die notwendigen Berechtigungen in diesem Projekt besitzt. - - **Cloud Shell Hinweis:** In einer Cloud Shell Umgebung wird diese Variable standardmäßig auf ein spezielles Projekt gesetzt, das für Cloud Shell Nutzer bereitgestellt wird. Wenn du `GOOGLE_CLOUD_PROJECT` bereits global in deiner Cloud Shell-Umgebung gesetzt hast, wird es durch diesen Standardwert überschrieben. Um ein anderes Projekt in Cloud Shell zu verwenden, musst du `GOOGLE_CLOUD_PROJECT` in einer `.env` Datei definieren. + - Falls du Vertex AI verwendest, stelle sicher, dass du die nötigen Berechtigungen in diesem Projekt hast. + - **Hinweis zu Cloud Shell:** Wenn du in einer Cloud Shell-Umgebung arbeitest, wird diese Variable standardmäßig auf ein spezielles Projekt gesetzt, das für Cloud Shell-Benutzer reserviert ist. Falls du `GOOGLE_CLOUD_PROJECT` bereits in deiner globalen Umgebung in Cloud Shell gesetzt hast, wird dieser Wert durch den Standardwert überschrieben. Um ein anderes Projekt in Cloud Shell zu verwenden, musst du `GOOGLE_CLOUD_PROJECT` in einer `.env`-Datei definieren. - Beispiel: `export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. - **`GOOGLE_APPLICATION_CREDENTIALS`** (string): - **Beschreibung:** Der Pfad zu deiner Google Application Credentials JSON-Datei. @@ -330,36 +333,36 @@ Die CLI lädt Umgebungsvariablen automatisch aus einer `.env` Datei. Die Laderei - Deine Google Cloud Project ID für Telemetrie in Google Cloud. - Beispiel: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. - **`GOOGLE_CLOUD_LOCATION`**: - - Dein Google Cloud Projektstandort (z. B. us-central1). - - Erforderlich für die Nutzung von Vertex AI im Nicht-Express-Modus. + - Der Standort deines Google Cloud Projekts (z. B. us-central1). + - Erforderlich für die Nutzung von Vertex AI im non-express mode. - Beispiel: `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`. - **`GEMINI_SANDBOX`**: - - Alternative zur `sandbox` Einstellung in `settings.json`. + - Alternative zur `sandbox`-Einstellung in `settings.json`. - Akzeptiert `true`, `false`, `docker`, `podman` oder einen benutzerdefinierten Befehl als String. - **`SEATBELT_PROFILE`** (macOS-spezifisch): - - 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`: Nutzt ein striktes Profil, das standardmäßig alle Operationen ablehnt. - - ``: Nutzt ein benutzerdefiniertes Profil. Um ein solches zu definieren, erstelle eine Datei namens `sandbox-macos-.sb` im `.qwen/` Verzeichnis deines Projekts (z. B. `my-project/.qwen/sandbox-macos-custom.sb`). + - Wechselt das Seatbelt- (`sandbox-exec`) Profil unter macOS. + - `permissive-open`: (Standard) Beschränkt Schreibzugriffe auf den Projektordner (und einige andere Ordner, 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 Interferenzen mit dem CLI-Verhalten zu vermeiden. Verwende `.qwen/.env` Dateien, wenn du diese speziell für Qwen Code setzen musst. + - Auf `true` oder `1` setzen, um ausführliche Debug-Logs zu aktivieren – nützlich zur Fehlersuche. + - **Hinweis:** Diese Variablen werden standardmäßig aus Projekt-`.env`-Dateien ausgeschlossen, um Interferenzen mit dem CLI-Verhalten zu vermeiden. Verwende `.qwen/.env`-Dateien, wenn du diese speziell für Qwen Code setzen musst. - **`NO_COLOR`**: - - Auf einen beliebigen Wert setzen, um alle Farbausgaben der CLI zu deaktivieren. + - Auf einen beliebigen Wert setzen, um alle farbigen Ausgaben in der CLI zu deaktivieren. - **`CLI_TITLE`**: - Auf einen String setzen, um den Titel der CLI anzupassen. - **`CODE_ASSIST_ENDPOINT`**: - - Gibt den Endpunkt des Code Assist Servers an. + - Legt den Endpunkt für den Code Assist Server fest. - 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 Search Service. + - Erforderlich, um die Funktionalität des `web_search`-Tools zu aktivieren. + - Falls nicht konfiguriert, wird das Web Search Tool deaktiviert und übersprungen. - Beispiel: `export TAVILY_API_KEY="tvly-your-api-key-here"` ## Command-Line Arguments -Argumente, die direkt beim Ausführen des CLI übergeben werden, können andere Konfigurationen für diese spezifische Sitzung überschreiben. +Argumente, die direkt beim Ausführen der CLI übergeben werden, können andere Konfigurationen für diese spezifische Sitzung überschreiben. - **`--model `** (**`-m `**): - Gibt das Gemini-Modell an, das für diese Sitzung verwendet werden soll. @@ -369,12 +372,12 @@ Argumente, die direkt beim Ausführen des CLI übergeben werden, können andere - **`--prompt-interactive `** (**`-i `**): - Startet eine interaktive Sitzung mit dem übergebenen Prompt als initiale Eingabe. - Der Prompt wird innerhalb der interaktiven Sitzung verarbeitet, nicht davor. - - Kann nicht verwendet werden, wenn Eingaben von stdin gepiped werden. + - Kann nicht verwendet werden, wenn Eingaben über stdin gepiped werden. - Beispiel: `qwen -i "explain this code"` - **`--sandbox`** (**`-s`**): - Aktiviert den Sandbox-Modus für diese Sitzung. - **`--sandbox-image`**: - - Legt die URI des Sandbox-Images fest. + - Setzt die URI des Sandbox-Images. - **`--debug`** (**`-d`**): - Aktiviert den Debug-Modus für diese Sitzung und gibt detailliertere Ausgaben aus. - **`--all-files`** (**`-a`**): @@ -382,15 +385,22 @@ Argumente, die direkt beim Ausführen des CLI übergeben werden, können andere - **`--help`** (oder **`-h`**): - Zeigt Hilfsinformationen zu den Command-Line Arguments an. - **`--show-memory-usage`**: - - Zeigt den aktuellen Speicherverbrauch an. + - Zeigt die aktuelle Speicherauslastung an. - **`--yolo`**: - Aktiviert den YOLO-Modus, bei dem alle Tool-Aufrufe automatisch genehmigt werden. +- **`--approval-mode `**: + - Legt den Genehmigungsmodus für Tool-Aufrufe fest. Verfügbare Modi: + - `default`: Fordert bei jedem Tool-Aufruf eine Genehmigung an (Standardverhalten) + - `auto_edit`: Genehmigt automatisch Edit-Tools (replace, write_file), während andere Tools zur Genehmigung abgefragt werden + - `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` - **`--telemetry`**: - Aktiviert [Telemetrie](../telemetry.md). - **`--telemetry-target`**: - - Legt das Telemetrie-Ziel fest. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. + - Setzt das Ziel für die Telemetrie. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. - **`--telemetry-otlp-endpoint`**: - - Legt den OTLP-Endpunkt für die Telemetrie fest. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. + - Setzt den OTLP-Endpunkt für die Telemetrie. 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. - **`--checkpointing`**: @@ -400,26 +410,26 @@ Argumente, die direkt beim Ausführen des CLI übergeben werden, können andere - Verwende 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 anschließend. + - Listet alle verfügbaren Erweiterungen auf und beendet sich danach. - **`--proxy`**: - - Legt den Proxy für das CLI fest. + - 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-Support zu ermöglichen. + - Fügt zusätzliche Verzeichnisse zum Workspace hinzu, um Multi-Directory-Unterstützung 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` - **`--version`**: - - Zeigt die Version des CLI an. + - Zeigt die Version der CLI an. - **`--openai-logging`**: - Aktiviert das Logging von OpenAI-API-Aufrufen zur Fehlersuche und Analyse. Dieses Flag überschreibt die Einstellung `enableOpenAILogging` in der `settings.json`. - **`--tavily-api-key `**: - - Legt den Tavily-API-Schlüssel für die Web-Suchfunktion dieser Sitzung fest. + - Setzt den Tavily-API-Key für die Web-Suchfunktion 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 die KI zu übermitteln, 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 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. - **Zweck:** Diese Markdown-Dateien enthalten Anweisungen, Richtlinien oder Kontextinformationen, die du möchtest, dass das Gemini-Modell während eurer Interaktionen berücksichtigt. Das System ist so konzipiert, dass es diesen Instruktionskontext hierarchisch verwaltet. @@ -433,9 +443,9 @@ Hier ist ein konzeptionelles Beispiel dafür, was eine Context-Datei im Stammver ## Allgemeine Anweisungen: -- Wenn du neuen TypeScript-Code generierst, halte dich bitte an den bestehenden Codierungsstil. +- Bei der Generierung neuer TypeScript-Code sollte der bestehende Codierungsstil befolgt werden. - Stelle sicher, dass alle neuen Funktionen und Klassen über JSDoc-Kommentare verfügen. -- Bevorzuge funktionale Programmierparadigmen, wo immer es sinnvoll ist. +- Bevorzuge funktionale Programmierparadigmen, wo dies angemessen ist. - Der gesamte Code sollte mit TypeScript 5.0 und Node.js 20+ kompatibel sein. ## Codierungsstil: @@ -448,7 +458,7 @@ Hier ist ein konzeptionelles Beispiel dafür, was eine Context-Datei im Stammver ## 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 neue API-Aufruffunktionen hinzugefügt werden, stellen sicher, dass diese eine robuste Fehlerbehandlung und Protokollierung enthalten. - Verwende das vorhandene `fetchWithRetry`-Utility für alle GET-Anfragen. ## Zu den Abhängigkeiten: @@ -457,26 +467,26 @@ 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 dich unterstützen. 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 dir helfen. Projekt-spezifische Kontextdateien sind sehr empfohlen, 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 (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: +- **Hierarchisches Laden und Priorität:** Die CLI implementiert ein ausgeklügeltes hierarchisches Speichersystem, indem sie Kontextdateien (z. B. `QWEN.md`) aus verschiedenen 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 Benutzer-Home-Verzeichnis). - - Geltungsbereich: Stellt Standardanweisungen für alle deine Projekte bereit. - 2. **Projekt-Hauptverzeichnis & übergeordnete Verzeichnisse:** - - Ort: Die CLI sucht nach der konfigurierten Kontextdatei im aktuellen Arbeitsverzeichnis und danach in jedem übergeordneten Verzeichnis bis entweder zum Projektstamm (erkennbar an einem `.git`-Ordner) oder zu deinem Home-Verzeichnis. - - Geltungsbereich: Stellt Kontext bereit, der für das gesamte Projekt oder einen großen Teil davon relevant ist. - 3. **Unterverzeichnis-Kontextdateien (kontextuell/lokal):** + - Gültigkeitsbereich: Stellt Standardanweisungen für alle deine Projekte bereit. + 2. **Projektstamm & übergeordnete Verzeichnisse:** + - Ort: Die CLI sucht nach der konfigurierten Kontextdatei im aktuellen Arbeitsverzeichnis und anschließend in jedem übergeordneten Verzeichnis bis entweder zum Projektstamm (erkennbar an einem `.git`-Ordner) oder zu deinem Home-Verzeichnis. + - Gültigkeitsbereich: Stellt Kontext bereit, der für das gesamte Projekt oder einen großen Teil davon relevant ist. + 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 Abschnitt deines Projekts relevant sind. + - Gültigkeitsbereich: Ermöglicht hochspezifische Anweisungen, die für eine bestimmte Komponente, ein Modul oder einen Abschnitt 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. - **Inhalte importieren:** Du kannst deine Kontextdateien modularisieren, indem du andere Markdown-Dateien mit der Syntax `@path/to/file.md` importierst. Weitere Details findest du in der [Dokumentation zum Memory Import Processor](../core/memport.md). - **Befehle zur Speicherverwaltung:** - - Nutze `/memory refresh`, um einen erneuten Scan und Reload aller Kontextdateien von allen konfigurierten Orten zu erzwingen. Dies aktualisiert den Anweisungskontext der KI. - - Nutze `/memory show`, um den aktuell geladenen kombinierten Anweisungskontext anzuzeigen, sodass du die Hierarchie und den von der KI verwendeten Inhalt überprüfen kannst. + - Verwende `/memory refresh`, um einen erneuten Scan und Reload aller Kontextdateien aus allen konfigurierten Orten zu erzwingen. Dadurch wird der Anweisungskontext der KI aktualisiert. + - 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 Bedürfnisse 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 an deine spezifischen Anforderungen und Projekte anpassen. ## Sandboxing @@ -486,16 +496,16 @@ Sandboxing ist standardmäßig deaktiviert, aber du kannst es auf verschiedene A - Mit dem Flag `--sandbox` oder `-s`. - Durch Setzen der Umgebungsvariable `GEMINI_SANDBOX`. -- Im `--yolo`-Modus ist Sandboxing standardmäßig aktiviert. +- 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. -Für projektspezifische Anforderungen kannst du ein eigenes Dockerfile unter `.qwen/sandbox.Dockerfile` im Root-Verzeichnis deines Projekts anlegen. Dieses Dockerfile kann auf dem Basis-Sandbox-Image aufbauen: +Für projektspezifische Anforderungen kannst du ein eigenes Dockerfile unter `.qwen/sandbox.Dockerfile` im Root-Verzeichnis deines Projekts anlegen. Dieses Dockerfile kann auf dem Basis-Sandbox-Image basieren: ```dockerfile FROM qwen-code-sandbox -# Hier kannst du eigene Abhängigkeiten oder Konfigurationen hinzufügen +# Füge hier deine eigenen Abhängigkeiten oder Konfigurationen hinzu # Zum Beispiel: @@ -523,8 +533,8 @@ Um uns bei der Verbesserung von Qwen Code zu helfen, sammeln wir anonymisierte N **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 Response-Inhalte:** Wir protokollieren nicht den Inhalt Ihrer Prompts oder die Antworten des Modells. +- **Personenbezogene Daten (PII):** Wir sammeln keine persönlichen Informationen wie Ihren Namen, Ihre E-Mail-Adresse oder API-Schlüssel. +- **Prompt- und Response-Inhalt:** Wir protokollieren nicht den Inhalt Ihrer Prompts oder die Antworten des Modells. - **Dateiinhalte:** Wir protokollieren nicht den Inhalt von Dateien, die von der CLI gelesen oder geschrieben werden. **So deaktivieren Sie die Sammlung:** diff --git a/website/content/de/deployment.md b/website/content/de/deployment.md index 27ca1c3c..94f0bda9 100644 --- a/website/content/de/deployment.md +++ b/website/content/de/deployment.md @@ -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 für Umgebungen, in denen du nur Docker installiert hast und die CLI ausführen möchtest. ```bash - # Das veröffentlichte Sandbox-Image ausführen - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.7 + # Run the published sandbox image + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.9 ``` - **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 du Qwen Code lokal installiert hast (gemäß der oben beschriebenen Standardinstallation), kannst du es anweisen, innerhalb des Sandbox-Containers zu laufen. ```bash qwen --sandbox -y -p "your prompt here" ``` @@ -58,11 +58,11 @@ Contributor des Projekts 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 Root des Repositories + # Vom Root des Repositories aus npm run start ``` - **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. + Diese Methode simuliert eine globale Installation, indem sie das lokale Package verknüpft. Sie ist nützlich, um einen lokalen Build in einem Produktions-Workflow zu testen. ```bash # Verknüpfe das lokale CLI-Package mit deinen globalen node_modules @@ -76,7 +76,7 @@ Contributor des Projekts möchten die CLI direkt aus dem Quellcode ausführen. ### 4. Ausführen des neuesten Qwen Code Commits von GitHub -Du kannst die aktuellste Version von Qwen Code direkt aus dem GitHub-Repository ausführen. Das ist nützlich, um Features zu testen, die sich noch in der Entwicklung befinden. +Du kannst die aktuellste committete Version von Qwen Code direkt aus dem GitHub-Repository ausführen. Das ist nützlich, um Features zu testen, die sich noch in der Entwicklung befinden. ```bash @@ -103,11 +103,11 @@ Es gibt zwei verschiedene Build-Prozesse, die je nach Verteilungskanal verwendet - **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 im NPM-Paket veröffentlicht. Dies ist ein Standardansatz 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 verwendet `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 nicht im Repository gespeichert. +- **GitHub `npx`-Ausführung:** Beim direkten Ausführen der neuesten Qwen Code-Version von GitHub wird ein anderer Prozess durch das `prepare`-Skript in der `package.json` ausgelöst. Dieses Skript verwendet `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 erstellt und nicht im Repository versioniert. **Docker-Sandbox-Image** -Die Docker-basierte Ausführungsmethode wird vom `qwen-code-sandbox`-Container-Image unterstützt. Dieses Image wird in einer Container-Registry veröffentlicht und enthält eine vorinstallierte, globale 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 diff --git a/website/content/de/ide-integration.md b/website/content/de/ide-integration.md new file mode 100644 index 00000000..4ab1297f --- /dev/null +++ b/website/content/de/ide-integration.md @@ -0,0 +1,141 @@ +# IDE-Integration + +Die Gemini CLI 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 Features 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 unterstützen. + +## 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). + +- **Native Diff-Ansicht:** Wenn Gemini 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 akzeptieren oder ablehnen. + +- **VS Code Commands:** Du kannst direkt über die VS Code Command Palette (`Cmd+Shift+P` oder `Ctrl+Shift+P`) auf die Funktionen der Gemini CLI zugreifen: + - `Gemini CLI: Run`: Startet eine neue Gemini CLI-Sitzung im integrierten Terminal. + - `Gemini CLI: Accept Diff`: Akzeptiert die Änderungen im aktiven Diff-Editor. + - `Gemini CLI: Close Diff Editor`: Lehnt die Änderungen ab und schließt den aktiven Diff-Editor. + - `Gemini CLI: View Third-Party Notices`: Zeigt die Third-Party-Hinweise für die Erweiterung an. + +## Installation und Einrichtung + +Es gibt drei Möglichkeiten, die IDE-Integration einzurichten: + +### 1. Automatischer Hinweis (Empfohlen) + +Wenn du Gemini CLI innerhalb eines unterstützten Editors ausführst, erkennt es automatisch deine Umgebung und fordert dich auf, eine Verbindung herzustellen. Wenn du mit "Yes" antwortest, wird automatisch das notwendige Setup ausgeführt, inklusive Installation der Companion-Extension und Aktivierung der Verbindung. + +### 2. Manuelle Installation über CLI + +Falls du die Aufforderung zuvor abgelehnt hast oder die Extension manuell installieren möchtest, kannst du folgenden Befehl innerhalb von Gemini CLI ausführen: + +``` +/ide install +``` + +Dieser Befehl findet die richtige Extension für deine IDE und installiert sie. + +### 3. Manuelle Installation aus einem Marketplace + +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=google.gemini-cli-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/google/gemini-cli-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 ist. Sobald die Installation abgeschlossen ist, kannst du `/ide enable` verwenden, um dich zu verbinden. + +## Verwendung + +### Aktivierung und Deaktivierung + +Du kannst die IDE-Integration direkt über die CLI steuern: + +- Um die Verbindung zur IDE zu aktivieren, führe aus: + ``` + /ide enable + ``` +- Um die Verbindung zu deaktivieren, führe aus: + ``` + /ide disable + ``` + +Wenn aktiviert, wird der Gemini CLI automatisch versuchen, sich mit der IDE-Companion-Erweiterung zu verbinden. + +### Status prüfen + +Um den Verbindungsstatus zu prüfen und den Kontext anzuzeigen, den die CLI von der IDE erhalten hat, führe aus: + +``` +/ide status +``` + +Wenn verbunden, zeigt dieser Befehl die IDE an, mit der die Verbindung besteht, sowie eine Liste der zuletzt geöffneten Dateien, die bekannt sind. + +(Hinweis: Die Dateiliste ist auf 10 zuletzt aufgerufene 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. + +**Um ein 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 **Gemini CLI: Accept Diff** aus. +- Antworte mit `yes` in der CLI, wenn du dazu aufgefordert wirst. + +**Um ein 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 **Gemini CLI: 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. + +## Verwendung mit Sandboxing + +Wenn du das Gemini CLI 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 das Gemini CLI innerhalb eines Docker- (oder Podman-) Containers ausführst, kann sich die IDE-Integration immer noch mit der VS Code-Erweiterung verbinden, die auf deinem Host-Rechner läuft. Das CLI ist so konfiguriert, dass es den IDE-Server automatisch unter `host.docker.internal` findet. Normalerweise ist keine spezielle Konfiguration erforderlich, aber du musst möglicherweise sicherstellen, dass dein Docker-Netzwerksetup Verbindungen vom Container zum Host zulässt. + +## Fehlerbehebung + +Falls du Probleme mit der IDE-Integration hast, 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:** Gemini CLI konnte die notwendigen Umgebungsvariablen (`GEMINI_CLI_IDE_WORKSPACE_PATH` oder `GEMINI_CLI_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. + - **Lösung:** + 1. Stelle sicher, dass du die **Gemini CLI 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. + +- **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. + - **Lösung:** Führe `/ide enable` aus, um eine erneute Verbindung herzustellen. Falls das Problem weiterhin besteht, öffne ein neues Terminalfenster oder starte deine IDE neu. + +### Konfigurationsfehler + +- **Meldung:** `🔴 Disconnected: Directory mismatch. Gemini CLI 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. + - **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 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. + +### Allgemeine Fehler + +- **Nachricht:** `IDE-Integration wird in deiner aktuellen Umgebung nicht unterstützt. Um diese Funktion zu nutzen, führe das Gemini CLI in einer der folgenden unterstützten IDEs aus: [Liste der IDEs]` + - **Ursache:** Du führst das Gemini CLI in einem Terminal oder einer Umgebung aus, die keine unterstützte IDE ist. + - **Lösung:** Führe das Gemini CLI über das integrierte Terminal einer unterstützten IDE wie VS Code aus. + +- **Nachricht:** `Für [IDE Name] ist kein Installer verfügbar. Bitte installiere den IDE-Companion manuell über den Marketplace der IDE.` + - **Ursache:** Du hast `/ide install` ausgeführt, aber das CLI verfügt nicht über einen automatisierten Installer für deine spezifische IDE. + - **Lösung:** Öffne den Extension-Marketplace deiner IDE, suche nach "Gemini CLI Companion" und installiere ihn manuell. \ No newline at end of file diff --git a/website/content/de/index.md b/website/content/de/index.md index 65b35d4b..d1928f41 100644 --- a/website/content/de/index.md +++ b/website/content/de/index.md @@ -4,35 +4,36 @@ Diese Dokumentation bietet einen umfassenden Leitfaden zur Installation, Verwend ## Übersicht -Qwen Code bringt die Fähigkeiten fortschrittlicher Code-Modelle direkt in dein Terminal, und zwar 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 Webanfragen – diese werden vom `packages/core` verwaltet. +Qwen Code bringt die Fähigkeiten fortschrittlicher Code-Modelle direkt 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 Webanfragen – diese werden vom `packages/core` verwaltet. ## 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. +- **[Architekturübersicht](./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 die Command-Line Interface. + - **[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. - - **[Telemetrie](./telemetry.md):** Übersicht zur Telemetrie in der CLI. + - **[IDE-Integration](./ide-integration.md):** Verbinde die CLI mit deinem Editor. + - **[Telemetrie](./telemetry.md):** Übersicht über die 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. + - **[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. + - **[Dateisystem-Tools](./tools/file-system.md):** Dokumentation für die `read_file` und `write_file` Tools. + - **[Multi-File Read Tool](./tools/multi-file.md):** Dokumentation für das `read_many_files` Tool. + - **[Shell Tool](./tools/shell.md):** Dokumentation für das `run_shell_command` Tool. + - **[Web Fetch Tool](./tools/web-fetch.md):** Dokumentation für das `web_fetch` Tool. + - **[Web Search Tool](./tools/web-search.md):** Dokumentation für das `web_search` Tool. + - **[Memory Tool](./tools/memory.md):** Dokumentation für das `save_memory` Tool. - **[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. +- **[Nutzungsbedingungen und Datenschutzhinweise](./tos-privacy.md):** Informationen zu den Nutzungsbedingungen und Datenschutzbestimmungen für die Nutzung von Qwen Code. 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/integration-tests.md b/website/content/de/integration-tests.md index 0df589ec..ff9ea177 100644 --- a/website/content/de/integration-tests.md +++ b/website/content/de/integration-tests.md @@ -4,7 +4,7 @@ Dieses Dokument enthält Informationen über das Integration Testing Framework, ## Übersicht -Die Integration Tests dienen dazu, die End-to-End-Funktionalität von Qwen Code zu validieren. Sie führen die gebaute Binary in einer kontrollierten Umgebung aus und prüfen, ob sie sich wie erwartet verhält, wenn sie mit dem Dateisystem interagiert. +Die Integration Tests dienen dazu, die End-to-End-Funktionalität von Qwen Code zu validieren. Sie führen die gebaute Binary in einer kontrollierten Umgebung aus und prüfen, ob sie wie erwartet mit dem Dateisystem interagiert. Diese Tests befinden sich im Verzeichnis `integration-tests` und werden mit einem eigenen Test Runner ausgeführt. @@ -20,7 +20,7 @@ npm run test:e2e ## Ausführen einer bestimmten Testsammlung -Um eine Teilmenge von Testdateien auszuführen, kannst du `npm run ....` verwenden, wobei `` entweder `test:e2e` oder `test:integration*` ist und `` eine der `.test.js`-Dateien im Verzeichnis `integration-tests/` darstellt. Der folgende Befehl führt beispielsweise `list_directory.test.js` und `write_file.test.js` aus: +Um eine Teilmenge von Testdateien auszuführen, kannst du `npm run ....` verwenden, wobei `` entweder `test:e2e` oder `test:integration*` ist und `` eine der `.test.js` Dateien im `integration-tests/` Verzeichnis ist. Der folgende Befehl führt beispielsweise `list_directory.test.js` und `write_file.test.js` aus: ```bash npm run test:e2e list_directory write_file @@ -28,7 +28,7 @@ npm run test:e2e list_directory write_file ### Ausführen eines einzelnen Tests anhand des Namens -Um einen einzelnen Test anhand seines Namens auszuführen, verwende das Flag `--test-name-pattern`: +Um einen einzelnen Test anhand seines Namens auszuführen, verwende das `--test-name-pattern` Flag: ```bash npm run test:e2e -- --test-name-pattern "reads a file" @@ -67,50 +67,45 @@ Der Integrationstest-Runner bietet mehrere Optionen zur Diagnose, um bei der Feh Du kannst die temporären Dateien, die während eines Testlaufs erstellt wurden, zur Überprüfung erhalten. Das ist besonders nützlich, um Probleme mit Dateisystemoperationen zu debuggen. -Um die Test-Ausgabe zu behalten, kannst du entweder das Flag `--keep-output` verwenden oder die Umgebungsvariable `KEEP_OUTPUT` auf `true` setzen. +Um die Test-Ausgabe zu behalten, setze die Umgebungsvariable `KEEP_OUTPUT` auf `true`. ```bash - -# Mit dem Flag -npm run test:integration:sandbox:none -- --keep-output - -# Verwendung der Umgebungsvariable KEEP_OUTPUT=true npm run test:integration:sandbox:none ``` -Wenn die Ausgabe beibehalten wird, gibt der Test-Runner den Pfad zum eindeutigen Verzeichnis für den Testlauf aus. +Wenn die Ausgabe behalten wird, gibt der Test-Runner den Pfad zum eindeutigen Verzeichnis des Testlaufs aus. -### Ausführliche Ausgabe +### Ausführliche Ausgabe (Verbose output) -Für detaillierteres Debugging streamt das `--verbose` Flag die Echtzeitausgabe des `qwen` Befehls an die Konsole. +Für detailliertere Debugging-Ausgaben kannst du die Umgebungsvariable `VERBOSE` auf `true` setzen. ```bash -npm run test:integration:sandbox:none -- --verbose +VERBOSE=true npm run test:integration:sandbox:none ``` -Wenn `--verbose` und `--keep-output` im selben Befehl verwendet werden, wird die Ausgabe sowohl an die Konsole gestreamt als auch in einer Log-Datei innerhalb des temporären Verzeichnisses des Tests gespeichert. +Wenn du `VERBOSE=true` und `KEEP_OUTPUT=true` im selben Befehl verwendest, wird die Ausgabe sowohl in der Konsole gestreamt als auch in einer Log-Datei innerhalb des temporären Verzeichnisses des Tests gespeichert. -Die ausführliche Ausgabe ist so formatiert, dass die Quelle der Logs klar identifiziert werden kann: +Die ausführliche Ausgabe ist so formatiert, dass die Quelle der Logs klar identifizierbar ist: ``` ---- TEST: : --- -... Ausgabe des qwen Befehls ... ---- END TEST: : --- +--- TEST: : --- +... Ausgabe vom qwen-Befehl ... +--- END TEST: : --- ``` ## Linting und Formatierung -Um die Codequalität und Konsistenz zu gewährleisten, werden die Integrationstest-Dateien als Teil des Haupt-Build-Prozesses gelintet. Du kannst den Linter auch manuell ausführen und automatisch korrigieren lassen. +Um die Codequalität und Konsistenz sicherzustellen, werden die Integrationstest-Dateien im Rahmen des Haupt-Build-Prozesses gelintet. Du kannst den Linter auch manuell ausführen und automatisch Fehler beheben lassen. -### Linter ausführen +### Den Linter ausführen -Um auf Linting-Fehler zu prüfen, führe den folgenden Befehl aus: +Um auf Linting-Fehler zu prüfen, führe folgenden Befehl aus: ```bash npm run lint ``` -Du kannst das `:fix`-Flag zum Befehl hinzufügen, um alle behebbaren Linting-Fehler automatisch zu korrigieren: +Du kannst den `:fix`-Flag zum Befehl hinzufügen, um alle behebbaren Linting-Fehler automatisch zu korrigieren: ```bash npm run lint:fix @@ -118,9 +113,9 @@ npm run lint:fix ## Verzeichnisstruktur -Die Integrationstests erstellen für jeden Testlauf ein eigenes Verzeichnis innerhalb des `.integration-tests`-Verzeichnisses. Innerhalb dieses Verzeichnisses wird für jede Testdatei ein Unterverzeichnis angelegt, und darin wiederum ein Unterverzeichnis für jeden einzelnen Testfall. +Die Integrationstests erstellen für jeden Testlauf ein eindeutiges Verzeichnis innerhalb des `.integration-tests` Verzeichnisses. Innerhalb dieses Verzeichnisses wird für jede Testdatei ein Unterverzeichnis angelegt, und darin wiederum ein Unterverzeichnis für jeden einzelnen Testfall. -Diese Struktur erleichtert das Auffinden der Artefakte für einen bestimmten Testlauf, eine Testdatei oder einen Testfall. +Diese Struktur erleichtert das Auffinden der Artefakte für einen bestimmten Testlauf, eine Datei oder einen Fall. ``` .integration-tests/ @@ -128,7 +123,7 @@ Diese Struktur erleichtert das Auffinden der Artefakte für einen bestimmten Tes └── .test.js/ └── / ├── output.log - └── ...weitere Test-Artefakte... + └── ...andere Test-Artefakte... ``` ## Continuous Integration diff --git a/website/content/de/npm.md b/website/content/de/npm.md index 1cdc4296..4a65d422 100644 --- a/website/content/de/npm.md +++ b/website/content/de/npm.md @@ -4,15 +4,15 @@ Dieses Monorepo enthält zwei Hauptpakete: `@qwen-code/qwen-code` und `@qwen-cod ## `@qwen-code/qwen-code` -Dies ist das Hauptpaket für Qwen Code. Es ist verantwortlich für die Benutzeroberfläche, das Parsen von Commands und alle anderen benutzerseitigen Funktionen. +Dies ist das Hauptpaket für Qwen Code. Es ist verantwortlich für die Benutzeroberfläche, das Parsen von Commands und alle anderen funktionalitäten, die direkt mit dem User interagieren. -Wenn dieses Paket veröffentlicht wird, wird es in eine einzelne ausführbare Datei gebündelt. Dieses Bundle enthält alle Abhängigkeiten des Pakets, einschließlich `@qwen-code/qwen-code-core`. Das bedeutet, egal ob ein Nutzer das Paket mit `npm install -g @qwen-code/qwen-code` installiert oder es direkt mit `npx @qwen-code/qwen-code` ausführt – er verwendet diese eine eigenständige, ausführbare Datei. +Wenn dieses Package veröffentlicht wird, wird es in eine einzelne ausführbare Datei gebündelt. Dieses Bundle enthält alle Abhängigkeiten des Packages, inklusive `@qwen-code/qwen-code-core`. Das bedeutet, egal ob ein User das Package mit `npm install -g @qwen-code/qwen-code` installiert oder es direkt mit `npx @qwen-code/qwen-code` ausführt – er verwendet immer diese eine eigenständige, ausführbare Datei. ## `@qwen-code/qwen-code-core` Dieses Package enthält die Kernlogik für die CLI. Es ist verantwortlich für das Senden von API-Anfragen an konfigurierte Provider, die Authentifizierung und das Management des lokalen Caches. -Dieses Package wird nicht gebundled. Bei der Veröffentlichung wird es als normales Node.js Package mit seinen eigenen Abhängigkeiten veröffentlicht. Dadurch kann es bei Bedarf als eigenständiges Package in anderen Projekten verwendet werden. Der gesamte transpilierte JavaScript-Code im `dist`-Ordner ist im Package enthalten. +Dieses Package wird nicht gebundled. Bei der Veröffentlichung wird es als Standard-Node.js-Package mit seinen eigenen Abhängigkeiten veröffentlicht. Dadurch kann es bei Bedarf als eigenständiges Package in anderen Projekten verwendet werden. Der gesamte transpilierte JavaScript-Code im `dist`-Ordner ist im Package enthalten. # Release-Prozess @@ -24,11 +24,11 @@ Releases werden über den [release.yml](https://github.com/QwenLM/qwen-code/acti 1. Gehe zum **Actions**-Tab des Repositories. 2. Wähle den **Release**-Workflow aus der Liste aus. -3. Klicke auf den Dropdown-Button **Run workflow**. +3. Klicke auf die Dropdown-Schaltfläche **Run workflow**. 4. Fülle die erforderlichen Eingaben aus: - **Version**: Die exakte Version, die released werden soll (z. B. `v0.2.1`). - **Ref**: Der Branch oder Commit-SHA, von dem aus der Release erfolgen soll (standardmäßig `main`). - - **Dry Run**: Auf `true` belassen, um den Workflow zu testen, ohne ihn zu veröffentlichen, oder auf `false` setzen, um einen echten Release durchzuführen. + - **Dry Run**: Lasse den Wert auf `true`, um den Workflow zu testen, ohne ihn zu veröffentlichen, oder setze ihn auf `false`, um einen echten Release durchzuführen. 5. Klicke auf **Run workflow**. ## Nightly Releases @@ -39,16 +39,16 @@ Zusätzlich zu manuellen Releases verfügt dieses Projekt über einen automatisi Jede Nacht um Mitternacht UTC wird der [Release-Workflow](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) automatisch nach Zeitplan ausgeführt. Er führt folgende Schritte durch: -1. Checkt den neuesten Code aus dem `main` Branch aus. +1. Checkt den neuesten Code aus dem `main`-Branch aus. 2. Installiert alle Abhängigkeiten. -3. Führt die komplette Suite an `preflight` Checks und Integrationstests aus. -4. Falls alle Tests erfolgreich sind, wird die nächste Nightly-Version berechnet (z. B. `v0.2.1-nightly.20230101`). +3. Führt die vollständige Suite an `preflight`-Checks und Integrationstests aus. +4. Falls alle Tests erfolgreich sind, wird die nächste Nightly-Versionsnummer berechnet (z. B. `v0.2.1-nightly.20230101`). 5. Anschließend werden die Pakete gebaut und mit dem `nightly` dist-tag auf npm veröffentlicht. 6. Abschließend wird ein GitHub Release für die Nightly-Version erstellt. ### Fehlerbehandlung -Falls ein Schritt im Nightly-Workflow fehlschlägt, wird automatisch ein neues Issue im Repository erstellt, gekennzeichnet mit den Labels `bug` und `nightly-failure`. Das Issue enthält einen Link zum fehlgeschlagenen Workflow-Lauf zur einfachen Fehlersuche. +Falls ein Schritt im Nightly-Workflow fehlschlägt, wird automatisch ein neues Issue im Repository mit den Labels `bug` und `nightly-failure` erstellt. Das Issue enthält einen Link zum fehlgeschlagenen Workflow-Lauf zur einfachen Fehlersuche. ### Wie man den Nightly Build verwendet @@ -58,35 +58,35 @@ Um den neuesten Nightly Build zu installieren, verwende den `@nightly` Tag: npm install -g @qwen-code/qwen-code@nightly ``` -Wir führen außerdem einen Google Cloud Build namens [release-docker.yml](../.gcp/release-docker.yaml) aus, der das Sandbox-Docker Image entsprechend deinem Release veröffentlicht. Sobald die Service Account Berechtigungen geklärt sind, wird dies ebenfalls auf GH verschoben und mit der Haupt-Release-Datei zusammengeführt. +Wir führen außerdem einen Google Cloud Build namens [release-docker.yml](../.gcp/release-docker.yml) aus. Dieser veröffentlicht das Sandbox-Docker-Image passend zu deinem Release. Sobald die Service-Account-Berechtigungen geklärt sind, wird dies ebenfalls auf GH verschoben und mit der Haupt-Release-Datei zusammengeführt. ### Nach dem Release -Sobald der Workflow erfolgreich abgeschlossen ist, kannst du den Fortschritt im [GitHub Actions Tab](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) verfolgen. Wenn er fertig ist, solltest du: +Sobald der Workflow erfolgreich abgeschlossen ist, kannst du den Fortschritt im [GitHub Actions Tab](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) verfolgen. Wenn alles erledigt ist, solltest du folgende Schritte durchführen: -1. Zur [Pull Requests Seite](https://github.com/QwenLM/qwen-code/pulls) des Repositories navigieren. -2. Einen neuen Pull Request vom `release/vX.Y.Z` Branch in den `main` Branch erstellen. -3. Den Pull Request reviewen (er sollte nur Versionsaktualisierungen in den `package.json` Dateien enthalten) und mergen. Dadurch bleibt die Version im `main` Branch aktuell. +1. Gehe zur [Pull Requests Seite](https://github.com/QwenLM/qwen-code/pulls) des Repositories. +2. Erstelle einen neuen Pull Request vom Branch `release/vX.Y.Z` in den `main` Branch. +3. Überprüfe den Pull Request (er sollte nur Versionsaktualisierungen in den `package.json` Dateien enthalten) und merge ihn. Dadurch bleibt die Version im `main` Branch aktuell. ## Release-Validierung -Nach dem Push eines neuen Releases sollte ein Smoke-Test durchgeführt werden, um sicherzustellen, dass die Pakete wie erwartet funktionieren. Dies kann durch eine lokale Installation der Pakete und das Ausführen einer Reihe von Tests erfolgen, um ihre ordnungsgemäße Funktionsweise zu überprüfen. +Nach dem Pushen eines neuen Releases sollte ein Smoke-Test durchgeführt werden, um sicherzustellen, dass die Pakete wie erwartet funktionieren. Dies kann durch eine lokale Installation der Pakete und das Ausführen einer Reihe von Tests erfolgen, um ihre ordnungsgemäße Funktionsweise zu überprüfen. - `npx -y @qwen-code/qwen-code@latest --version`, um zu validieren, dass der Push wie erwartet funktioniert hat, wenn kein RC- oder Dev-Tag verwendet wurde - `npx -y @qwen-code/qwen-code@ --version`, um zu überprüfen, ob der Tag korrekt gepusht wurde - _Dies ist lokal destruktiv_: `npm uninstall @qwen-code/qwen-code && npm uninstall -g @qwen-code/qwen-code && npm cache clean --force && npm install @qwen-code/qwen-code@` -- Ein Smoke-Test mit einer grundlegenden Ausführung einiger LLM-Befehle und Tools wird empfohlen, um sicherzustellen, dass die Pakete wie erwartet funktionieren. Wir werden dies in Zukunft weiter formalisieren. +- Für den Smoke-Test wird empfohlen, einige grundlegende LLM-Befehle und Tools auszuführen, um sicherzustellen, dass die Pakete wie erwartet funktionieren. Wir werden dies in Zukunft weiter formalisieren. -## Wann soll das Version-Update gemerged werden – oder nicht? +## Wann sollte die Versionsänderung gemerged werden, und wann nicht? -Das oben beschriebene Muster zum Erstellen von Patch- oder Hotfix-Releases von aktuellen oder älteren Commits aus führt dazu, dass sich das Repository in folgendem Zustand befindet: +Das oben beschriebene Muster zum Erstellen von Patch- oder Hotfix-Releases von aktuellen oder älteren Commits aus lässt das Repository in folgendem Zustand: -1. Der Tag (`vX.Y.Z-patch.1`): Dieser Tag zeigt korrekterweise auf den ursprünglichen Commit im main-Branch, der den stabilen Code enthält, den du veröffentlichen wolltest. Das ist entscheidend. Jeder, der diesen Tag auscheckt, erhält exakt den Code, der veröffentlicht wurde. -2. Der Branch (`release-vX.Y.Z-patch.1`): Dieser Branch enthält einen neuen Commit über dem getaggten Commit. Dieser neue Commit enthält ausschließlich die Versionsnummer-Änderung in der `package.json` (und anderen zugehörigen Dateien wie `package-lock.json`). +1. Der Tag (`vX.Y.Z-patch.1`): Dieser Tag zeigt korrekterweise auf den ursprünglichen Commit auf main, der den stabilen Code enthält, den du veröffentlichen wolltest. Das ist entscheidend. Jeder, der diesen Tag auscheckt, erhält den exakten Code, der veröffentlicht wurde. +2. Der Branch (`release-vX.Y.Z-patch.1`): Dieser Branch enthält einen neuen Commit über dem getaggten Commit. Dieser neue Commit enthält nur die Versionsnummer-Änderung in package.json (und anderen verwandten Dateien wie package-lock.json). -Diese Trennung ist gut. Sie hält den Verlauf deines main-Branch sauber von Release-spezifischen Versionsanpassungen, bis du dich entscheidest, diese zu mergen. +Diese Trennung ist gut. Sie hält den main Branch sauber von Release-spezifischen Versionsanhebungen, bis du dich entscheidest, sie zu mergen. -Das ist die entscheidende Frage, und sie hängt vollständig von der Art des Releases ab. +Das ist die kritische Entscheidung, und sie hängt vollständig von der Art des Releases ab. ### Merge Back für Stable Patches und Hotfixes @@ -104,7 +104,7 @@ Release Branches für Pre-Releases werden in der Regel nicht zurück in `main` g ## Lokales Testen und Validierung: Änderungen am Packaging- und Publishing-Prozess -Wenn du den Release-Prozess testen musst, ohne tatsächlich auf NPM zu veröffentlichen oder ein öffentliches GitHub-Release zu erstellen, kannst du den Workflow manuell über die GitHub UI auslösen. +Wenn du den Release-Prozess testen musst, ohne tatsächlich auf NPM zu veröffentlichen oder ein öffentliches GitHub-Release zu erstellen, kannst du den Workflow manuell über die GitHub-UI auslösen. 1. Gehe zum [Actions-Tab](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) des Repositories. 2. Klicke auf das Dropdown-Menü „Run workflow“. @@ -121,29 +121,29 @@ Um deine Änderungen zu validieren, kannst du einen Dry-Run des Publishing-Proze npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run ``` -Dieser Befehl führt folgende Schritte aus: +Dieser Befehl führt folgende Aktionen aus: 1. Erstellt alle Pakete. 2. Führt alle Prepublish-Skripte aus. -3. Erstellt die `.tgz`-Tarballs, die auf npm veröffentlicht würden. +3. Erzeugt die `.tgz`-Tarballs, die auf npm veröffentlicht würden. 4. Gibt eine Zusammenfassung der Pakete aus, die veröffentlicht werden würden. -Du kannst dann die generierten Tarballs überprüfen, um sicherzustellen, dass sie die korrekten Dateien enthalten und dass die `package.json`-Dateien korrekt aktualisiert wurden. Die Tarballs werden im Root-Verzeichnis jedes Pakets erstellt (z. B. `packages/cli/google-gemini-cli-0.1.6.tgz`). +Du kannst dann die generierten Tarballs überprüfen, um sicherzustellen, dass sie die korrekten Dateien enthalten und die `package.json`-Dateien ordnungsgemäß aktualisiert wurden. Die Tarballs werden im Stammverzeichnis jedes Pakets erstellt (z. B. `packages/cli/google-gemini-cli-0.1.6.tgz`). -Durch einen Dry-Run kannst du sicherstellen, dass deine Änderungen am Packaging-Prozess korrekt sind und dass die Pakete erfolgreich veröffentlicht werden. +Durch das Ausführen eines Dry-Runs kannst du sicher sein, dass deine Änderungen am Packaging-Prozess korrekt sind und die Pakete erfolgreich veröffentlicht werden. ## Release Deep Dive Das Hauptziel des Release-Prozesses ist es, den Source Code aus dem `packages/`-Verzeichnis zu nehmen, zu bauen und ein sauberes, eigenständiges Paket in einem temporären `bundle`-Verzeichnis im Root des Projekts zusammenzustellen. Dieses `bundle`-Verzeichnis ist es, was letztendlich auf NPM veröffentlicht wird. -Hier sind die wichtigsten Stufen: +Hier sind die wichtigsten Phasen: -### Stufe 1: Pre-Release Sanity Checks und Versionierung +### Phase 1: Pre-Release Sanity Checks und Versionierung -- **Was passiert**: Bevor Dateien verschoben werden, stellt der Prozess sicher, dass sich das Projekt in einem guten Zustand befindet. Dazu gehören das Ausführen von Tests, Linting und Type-Checking (`npm run preflight`). Die Versionsnummer in der root `package.json` und `packages/cli/package.json` wird auf die neue Release-Version aktualisiert. +- **Was passiert**: Bevor Dateien verschoben werden, stellt der Prozess sicher, dass sich das Projekt in einem guten Zustand befindet. Dazu gehören das Ausführen von Tests, Linting und Type-Checking (`npm run preflight`). Die Versionsnummer in der Root-`package.json` und in `packages/cli/package.json` wird auf die neue Release-Version aktualisiert. - **Warum**: Dadurch wird sichergestellt, dass nur hochwertiger, funktionierender Code veröffentlicht wird. Die Versionierung ist der erste Schritt, um ein neues Release zu kennzeichnen. -### Stufe 2: Build des Source Codes +### Phase 2: Kompilierung des Source Codes - **Was passiert**: Der TypeScript-Code in `packages/core/src` und `packages/cli/src` wird in JavaScript kompiliert. - **Dateibewegung**: @@ -151,20 +151,20 @@ Hier sind die wichtigsten Stufen: - `packages/cli/src/**/*.ts` → kompiliert zu → `packages/cli/dist/` - **Warum**: Der TypeScript-Code, der während der Entwicklung geschrieben wurde, muss in reines JavaScript umgewandelt werden, das von Node.js ausgeführt werden kann. Das Core-Package wird zuerst gebaut, da das CLI-Package davon abhängt. -### Stufe 3: Zusammenstellung des finalen, veröffentlichbaren Pakets +### Phase 3: Zusammenstellen des finalen, veröffentlichbaren Pakets -Dies ist die kritischste Stufe, in der Dateien in ihren finalen Zustand für die Veröffentlichung verschoben und transformiert werden. Ein temporäres `bundle`-Verzeichnis wird im Projekt-Root erstellt, um den finalen Paketinhalt aufzunehmen. +Dies ist die kritischste Phase, in der Dateien verschoben und in ihren finalen Zustand für die Veröffentlichung transformiert werden. Ein temporäres `bundle`-Verzeichnis wird im Projekt-Root erstellt, um den finalen Paketinhalt aufzunehmen. #### 1. Transformation der `package.json` -- **Was passiert**: Die `package.json` aus `packages/cli/` wird eingelesen, modifiziert und in das Root-`bundle`/-Verzeichnis geschrieben. +- **Was passiert**: Die `package.json` aus `packages/cli/` wird eingelesen, modifiziert und in das Root-`bundle`-Verzeichnis geschrieben. - **Dateibewegung**: `packages/cli/package.json` → (In-Memory-Transformation) → `bundle/package.json` - **Warum**: Die finale `package.json` muss sich von der unterscheiden, die während der Entwicklung verwendet wird. Wichtige Änderungen sind: - Entfernen von `devDependencies`. - - Entfernen von workspace-spezifischen `"dependencies": { "@gemini-cli/core": "workspace:*" }` und Sicherstellen, dass der Core-Code direkt in die finale JavaScript-Datei gebundled wird. + - Entfernen von workspace-spezifischen `"dependencies"`: `{ "@gemini-cli/core": "workspace:*" }` und Sicherstellen, dass der Core-Code direkt in die finale JavaScript-Datei gebundled wird. - Sicherstellen, dass die Felder `bin`, `main` und `files` auf die korrekten Pfade innerhalb der finalen Paketstruktur zeigen. -#### 2. Erstellung des JavaScript-Bundles +#### 2. Erstellen des JavaScript-Bundles - **Was passiert**: Der gebaute JavaScript-Code aus `packages/core/dist` und `packages/cli/dist` wird in eine einzelne, ausführbare JavaScript-Datei gebundled. - **Dateibewegung**: `packages/cli/dist/index.js` + `packages/core/dist/index.js` → (gebundled durch esbuild) → `bundle/gemini.js` (oder ähnlicher Name). @@ -178,13 +178,13 @@ Dies ist die kritischste Stufe, in der Dateien in ihren finalen Zustand für die - `LICENSE` → `bundle/LICENSE` - `packages/cli/src/utils/*.sb` (Sandbox-Profile) → `bundle/` - **Warum**: - - `README.md` und `LICENSE` sind Standarddateien, die in jedem NPM-Paket enthalten sein sollten. + - Die `README.md` und `LICENSE` sind Standarddateien, die in jedem NPM-Paket enthalten sein sollten. - Die Sandbox-Profile (`.sb`-Dateien) sind kritische Laufzeit-Assets, die für die Sandbox-Funktion des CLI erforderlich sind. Sie müssen sich direkt neben der finalen ausführbaren Datei befinden. -### Stufe 4: Veröffentlichen auf NPM +### Phase 4: Veröffentlichen auf NPM - **Was passiert**: Der Befehl `npm publish` wird aus dem Root-`bundle`-Verzeichnis heraus ausgeführt. -- **Warum**: Durch das Ausführen von `npm publish` aus dem `bundle`-Verzeichnis werden nur die Dateien hochgeladen, die wir sorgfältig in Stufe 3 zusammengestellt haben. Dadurch wird verhindert, dass versehentlich Source Code, Testdateien oder Entwicklungskonfigurationen veröffentlicht werden – das Ergebnis ist ein sauberes und minimales Paket für die Nutzer. +- **Warum**: Durch das Ausführen von `npm publish` aus dem `bundle`-Verzeichnis werden nur die Dateien hochgeladen, die wir sorgfältig in Phase 3 zusammengestellt haben. Dies verhindert, dass versehentlich Source Code, Testdateien oder Entwicklungskonfigurationen veröffentlicht werden, was zu einem sauberen und minimalen Paket für die Nutzer führt. ### Zusammenfassung des Dateiflusses @@ -222,7 +222,7 @@ graph TD J --> G --> K ``` -Dieser Prozess stellt sicher, dass das letztendlich veröffentlichte Artefakt eine gezielt erstellte, saubere und effiziente Darstellung des Projekts ist – und nicht einfach eine direkte Kopie des Entwicklungsumfelds. +Dieser Prozess stellt sicher, dass das final veröffentlichte Artefakt eine gezielt erstellte, saubere und effiziente Darstellung des Projekts ist – und nicht einfach eine direkte Kopie des Entwicklungsumfelds. ## NPM Workspaces @@ -244,4 +244,4 @@ Dies teilt NPM mit, dass jeder Ordner innerhalb des `packages` Verzeichnisses ei - **Vereinfachte Dependency-Management**: Wenn du `npm install` vom Root des Projekts ausführst, werden alle Abhängigkeiten für alle Pakete im Workspace installiert und miteinander verknüpft. Das bedeutet, dass du nicht in jedem Paket-Verzeichnis `npm install` ausführen musst. - **Automatische Verknüpfung**: Pakete innerhalb des Workspaces können voneinander abhängen. Beim Ausführen von `npm install` erstellt NPM automatisch Symlinks zwischen den Paketen. Das heißt, wenn du Änderungen an einem Paket vornimmst, sind diese sofort in anderen Paketen verfügbar, die davon abhängen. -- **Vereinfachte Skriptausführung**: Du kannst Skripte in jedem Paket vom Root des Projekts aus mit dem `--workspace`-Flag ausführen. Um beispielsweise das `build`-Skript im `cli`-Paket auszuführen, kannst du `npm run build --workspace @google/gemini-cli` verwenden. \ No newline at end of file +- **Vereinfachte Script-Ausführung**: Du kannst Scripts in jedem Paket vom Root des Projekts aus mit dem `--workspace`-Flag ausführen. Um beispielsweise das `build`-Script im `cli`-Paket auszuführen, kannst du `npm run build --workspace @google/gemini-cli` verwenden. \ No newline at end of file diff --git a/website/content/de/tools/file-system.md b/website/content/de/tools/file-system.md index 49faaff7..48667c5a 100644 --- a/website/content/de/tools/file-system.md +++ b/website/content/de/tools/file-system.md @@ -2,19 +2,19 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem lokalen Dateisystem. Diese Tools ermöglichen es dem Modell, Dateien und Verzeichnisse zu lesen, zu schreiben, aufzulisten, zu durchsuchen und zu ändern – alles unter deiner Kontrolle und in der Regel mit Bestätigungsabfrage bei sensiblen Operationen. -**Hinweis:** Alle Dateisystem-Tools arbeiten innerhalb eines `rootDirectory` (normalerweise das aktuelle Arbeitsverzeichnis, in dem du die CLI gestartet hast) aus Sicherheitsgründen. Die Pfade, die du diesen Tools übergibst, sollten grundsätzlich absolut sein oder werden relativ zu diesem Root-Verzeichnis aufgelöst. +**Hinweis:** Alle Dateisystem-Tools arbeiten innerhalb eines `rootDirectory` (normalerweise das aktuelle Arbeitsverzeichnis, in dem du die CLI gestartet hast) aus Sicherheitsgründen. Die Pfade, die du diesen Tools übergibst, sollten in der Regel absolut sein oder werden relativ zu diesem Root-Verzeichnis aufgelöst. ## 1. `list_directory` (ReadFolder) -`list_directory` listet die Namen von Dateien und Unterverzeichnissen direkt innerhalb eines angegebenen Verzeichnispfads auf. Es kann optional Einträge ignorieren, die mit den angegebenen Glob-Patterns übereinstimmen. +`list_directory` listet die Namen von Dateien und Unterverzeichnissen direkt innerhalb eines angegebenen Verzeichnispfads auf. Optional können Einträge ignoriert werden, die bestimmten Glob-Mustern entsprechen. - **Tool-Name:** `list_directory` - **Anzeigename:** ReadFolder - **Datei:** `ls.ts` - **Parameter:** - - `path` (string, erforderlich): Der absolute Pfad zum Verzeichnis, das aufgelistet werden soll. - - `ignore` (Array von Strings, optional): Eine Liste von Glob-Patterns, die von der Auflistung ausgeschlossen werden sollen (z. B. `["*.log", ".git"]`). - - `respect_git_ignore` (boolean, optional): Ob `.gitignore`-Patterns beim Auflisten von Dateien berücksichtigt werden sollen. Standardmäßig `true`. + - `path` (string, erforderlich): Der absolute Pfad zum aufzulistenden Verzeichnis. + - `ignore` (Array von Strings, optional): Eine Liste von Glob-Mustern, die von der Auflistung ausgeschlossen werden sollen (z. B. `["*.log", ".git"]`). + - `respect_git_ignore` (boolean, optional): Ob `.gitignore`-Muster beim Auflisten von Dateien berücksichtigt werden sollen. Standardmäßig `true`. - **Verhalten:** - Gibt eine Liste von Datei- und Verzeichnisnamen zurück. - Zeigt an, ob ein Eintrag ein Verzeichnis ist. @@ -24,19 +24,19 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem loka ## 2. `read_file` (ReadFile) -`read_file` liest und gibt den Inhalt einer angegebenen Datei zurück. Dieses Tool verarbeitet Text-, Bild- (PNG, JPG, GIF, WEBP, SVG, BMP) und PDF-Dateien. Bei Textdateien kann es bestimmte Zeilenbereiche lesen. Andere binäre Dateitypen werden in der Regel übersprungen. +`read_file` liest und gibt den Inhalt einer angegebenen Datei zurück. Dieses Tool verarbeitet Text-, Bild- (PNG, JPG, GIF, WEBP, SVG, BMP) und PDF-Dateien. Für Textdateien kann es bestimmte Zeilenbereiche lesen. Andere binäre Dateitypen werden in der Regel übersprungen. - **Tool-Name:** `read_file` - **Anzeigename:** ReadFile - **Datei:** `read-file.ts` - **Parameter:** - `path` (string, erforderlich): Der absolute Pfad zur zu lesenden Datei. - - `offset` (number, optional): Bei Textdateien die 0-basierte Zeilennummer, ab der das Lesen beginnen soll. Erfordert, dass `limit` gesetzt ist. + - `offset` (number, optional): Bei Textdateien die 0-basierte Zeilennummer, ab der das Lesen beginnt. Erfordert, dass `limit` gesetzt ist. - `limit` (number, optional): Bei Textdateien die maximale Anzahl an Zeilen, die gelesen werden sollen. Falls nicht angegeben, wird ein Standardmaximum (z. B. 2000 Zeilen) gelesen oder, wenn möglich, die gesamte Datei. - **Verhalten:** - Für Textdateien: Gibt den Inhalt zurück. Wenn `offset` und `limit` verwendet werden, wird nur dieser Abschnitt der Zeilen zurückgegeben. Zeigt an, ob der Inhalt aufgrund von Zeilen- oder Zeilenlängenbeschränkungen gekürzt wurde. - Für Bild- und PDF-Dateien: Gibt den Dateiinhalt als base64-kodierte Datenstruktur zurück, die für die Verarbeitung durch das Modell geeignet ist. - - Für andere binäre Dateien: Versucht, diese zu erkennen und zu überspringen, und gibt eine Meldung zurück, dass es sich um eine generische Binärdatei handelt. + - Für andere binäre Dateien: Versucht, sie zu erkennen und zu überspringen, und gibt eine Meldung zurück, dass es sich um eine generische Binärdatei handelt. - **Ausgabe:** (`llmContent`): - Für Textdateien: Der Dateiinhalt, ggf. mit einer Kürzungsmeldung am Anfang (z. B. `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`). - Für Bild-/PDF-Dateien: Ein Objekt mit `inlineData`, das `mimeType` und base64-kodierte `data` enthält (z. B. `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`). @@ -57,7 +57,7 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem loka - Schreibt den übergebenen `content` in die angegebene `file_path`. - Erstellt übergeordnete Verzeichnisse, falls diese nicht existieren. - **Ausgabe (`llmContent`):** Eine Erfolgsmeldung, z. B. `Successfully overwrote file: /path/to/your/file.txt` oder `Successfully created and wrote to new file: /path/to/new/file.txt`. -- **Bestätigung:** Ja. Zeigt einen Diff der Änderungen an und fordert die Zustimmung des Benutzers vor dem Schreiben an. +- **Bestätigung:** Ja. Zeigt einen Diff der Änderungen an und fordert die Nutzerbestätigung vor dem Schreiben an. ## 4. `glob` (FindFiles) @@ -68,12 +68,12 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem loka - **Datei:** `glob.ts` - **Parameter:** - `pattern` (string, erforderlich): Das Glob-Pattern, gegen das gematcht wird (z. B. `"*.py"`, `"src/**/*.js"`). - - `path` (string, optional): Der absolute Pfad zum Verzeichnis, in dem gesucht werden soll. Wenn nicht angegeben, wird im Root-Verzeichnis des Tools gesucht. + - `path` (string, optional): Der absolute Pfad zum Verzeichnis, in dem gesucht werden soll. Falls nicht angegeben, wird im Root-Verzeichnis des Tools gesucht. - `case_sensitive` (boolean, optional): Ob die Suche case-sensitive sein soll. Standardmäßig `false`. - `respect_git_ignore` (boolean, optional): Ob `.gitignore`-Patterns beim Suchen von Dateien berücksichtigt werden sollen. Standardmäßig `true`. - **Verhalten:** - - Sucht nach Dateien, die dem Glob-Pattern innerhalb des angegebenen Verzeichnisses entsprechen. - - Gibt eine Liste von absoluten Pfaden zurück, sortiert nach Änderungszeit (neueste zuerst). + - Sucht nach Dateien, die dem Glob-Pattern im angegebenen Verzeichnis entsprechen. + - Gibt eine Liste von absoluten Pfaden zurück, sortiert nach Änderungsdatum (neueste zuerst). - Ignoriert standardmäßig gängige Verzeichnisse wie `node_modules` und `.git`. - **Ausgabe (`llmContent`):** Eine Nachricht wie: `Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...` - **Bestätigung:** Nein. @@ -86,13 +86,16 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem loka - **Anzeigename:** SearchText - **Datei:** `grep.ts` - **Parameter:** - - `pattern` (string, erforderlich): Der reguläre Ausdruck (regex), nach dem gesucht werden soll (z. B. `"function\s+myFunction"`). + - `pattern` (string, erforderlich): Der reguläre Ausdruck, nach dem gesucht werden soll (z. B. `"function\s+myFunction"`). - `path` (string, optional): Der absolute Pfad zum Verzeichnis, in dem gesucht werden soll. Standardmäßig wird das aktuelle Arbeitsverzeichnis verwendet. - - `include` (string, optional): Ein Glob-Pattern, um festzulegen, welche Dateien durchsucht werden (z. B. `"*.js"`, `"src/**/*.{ts,tsx}"`). Falls nicht angegeben, werden die meisten Dateien durchsucht (unter Berücksichtigung gängiger Ignorierregeln). + - `include` (string, optional): Ein Glob-Pattern, um festzulegen, welche Dateien durchsucht werden (z. B. `"*.js"`, `"src/**/*.{ts,tsx}"`). Falls weggelassen, werden die meisten Dateien durchsucht (unter Berücksichtigung gängiger Ignorier-Regeln). + - `maxResults` (number, optional): Maximale Anzahl an Treffern, die zurückgegeben werden, um einen Kontextüberlauf zu vermeiden (Standard: 20, max: 100). Verwende niedrigere Werte bei allgemeinen Suchen, höhere bei spezifischen. - **Verhalten:** - - Verwendet `git grep`, falls innerhalb eines Git-Repositorys verfügbar, um die Geschwindigkeit zu erhöhen; ansonsten greift es auf das systemeigene `grep` oder eine JavaScript-basierte Suche zurück. + - Verwendet `git grep`, falls verfügbar (in einem Git-Repository) für bessere Performance; ansonsten greift es auf das systemeigene `grep` oder eine JavaScript-basierte Suche zurück. - Gibt eine Liste der übereinstimmenden Zeilen zurück, jeweils mit Dateipfad (relativ zum Suchverzeichnis) und Zeilennummer vorangestellt. -- **Ausgabe (`llmContent`):** Ein formatierter String der Treffer, z. B.: + - Begrenzt standardmäßig auf maximal 20 Treffer, um einen Kontextüberlauf zu verhindern. Bei gekürzten Ergebnissen wird eine klare Warnung mit Hinweisen zur Verfeinerung der Suche angezeigt. +- **Ausgabe (`llmContent`):** Ein formatierter String mit den Treffern, z. B.: + ``` Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"): --- @@ -103,10 +106,37 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem loka File: src/index.ts L5: import { myFunction } from './utils'; --- + + WARNING: Results truncated to prevent context overflow. To see more results: + - Use a more specific pattern to reduce matches + - Add file filters with the 'include' parameter (e.g., "*.js", "src/**") + - Specify a narrower 'path' to search in a subdirectory + - Increase 'maxResults' parameter if you need more matches (current: 20) ``` + - **Bestätigung:** Nein. -## 6. `replace` (Edit) +### `search_file_content` Beispiele + +Suche nach einem Muster mit standardmäßigem Limit für Ergebnisse: + +``` +search_file_content(pattern="function\s+myFunction", path="src") +``` + +Suche nach einem Muster mit benutzerdefiniertem Limit für Ergebnisse: + +``` +search_file_content(pattern="function", path="src", maxResults=50) +``` + +Suche nach einem Muster mit Dateifilterung und benutzerdefiniertem Limit für Ergebnisse: + +``` +search_file_content(pattern="function", include="*.js", maxResults=10) +``` + +## 6. `replace` (Editieren) `replace` ersetzt Text innerhalb einer Datei. Standardmäßig wird nur eine einzelne Fundstelle ersetzt, aber durch Angabe von `expected_replacements` können auch mehrere Vorkommen ersetzt werden. Dieses Tool ist für präzise, gezielte Änderungen konzipiert und benötigt einen ausreichenden Kontext um den `old_string`, um sicherzustellen, dass die korrekte Stelle verändert wird. @@ -126,18 +156,18 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem loka - Wenn `old_string` leer ist und `file_path` nicht existiert, wird eine neue Datei mit `new_string` als Inhalt erstellt. - Wenn `old_string` angegeben ist, liest das Tool die Datei unter `file_path` und sucht nach genau einem Vorkommen von `old_string`. - Wird genau ein Treffer gefunden, wird dieser durch `new_string` ersetzt. - - **Erweiterte Zuverlässigkeit (Mehrstufige Edit-Korrektur):** Um die Erfolgsrate von Änderungen deutlich zu erhöhen – besonders wenn der vom Modell bereitgestellte `old_string` nicht perfekt präzise ist – verwendet das Tool einen mehrstufigen Korrekturmechanismus. + - **Erweiterte Zuverlässigkeit (Mehrstufige Edit-Korrektur):** Um die Erfolgsrate von Änderungen deutlich zu erhöhen – insbesondere wenn der vom Modell gelieferte `old_string` nicht perfekt präzise ist – verwendet das Tool einen mehrstufigen Korrekturmechanismus. - Falls der ursprüngliche `old_string` nicht gefunden wird oder an mehreren Stellen vorkommt, kann das Tool das Gemini-Modell nutzen, um `old_string` (und ggf. auch `new_string`) iterativ zu verfeinern. - - Dieser Selbstkorrektur-Prozess versucht, das eindeutige Segment zu finden, das das Modell eigentlich ändern wollte, wodurch die `replace`-Operation robuster wird, selbst bei leicht ungenauem Ausgangskontext. + - Dieser Selbstkorrektur-Prozess versucht, das eindeutige Segment zu identifizieren, das das Modell eigentlich ändern wollte, wodurch die `replace`-Operation robuster wird, selbst bei leicht ungenauem Ausgangskontext. - **Fehlerbedingungen:** Trotz des Korrekturmechanismus schlägt das Tool fehl, wenn: - `file_path` kein absoluter Pfad ist oder außerhalb des Root-Verzeichnisses liegt. - `old_string` nicht leer ist, aber `file_path` nicht existiert. - `old_string` leer ist, aber `file_path` bereits existiert. - `old_string` nach Korrekturversuchen nicht in der Datei gefunden wird. - - `old_string` mehrfach vorkommt und der Selbstkorrektur-Mechanismus keine eindeutige Fundstelle bestimmen kann. + - `old_string` mehrfach vorkommt und der Selbstkorrektur-Mechanismus keine eindeutige Übereinstimmung finden kann. - **Ausgabe (`llmContent`):** - Bei Erfolg: `Successfully modified file: /path/to/file.txt (1 replacements).` oder `Created new file: /path/to/new_file.txt with provided content.` - Bei Fehler: Eine Fehlermeldung mit Erklärung des Grundes (z. B. `Failed to edit, 0 occurrences found...`, `Failed to edit, expected 1 occurrences but found 2...`). -- **Bestätigung:** Ja. Zeigt einen Diff der vorgeschlagenen Änderungen an und fordert die Nutzerbestätigung vor dem Schreiben in die Datei. +- **Bestätigung:** Ja. Zeigt einen Diff der vorgeschlagenen Änderungen an und fordert die Nutzer:in zur Bestätigung auf, bevor die Datei geschrieben wird. -Diese Filesystem-Tools bilden die Grundlage dafür, dass Qwen Code dein lokales Projektverzeichnis versteht und damit interagieren kann. \ No newline at end of file +Diese Filesystem-Tools bilden die Grundlage dafür, dass Qwen Code dein lokales Projekt-Kontext verstehen und damit interagieren kann. \ No newline at end of file diff --git a/website/content/de/tools/index.md b/website/content/de/tools/index.md index 9aca0201..523e548d 100644 --- a/website/content/de/tools/index.md +++ b/website/content/de/tools/index.md @@ -4,40 +4,40 @@ Qwen Code enthält integrierte Tools, die das Modell verwendet, um mit deiner lo ## Überblick über Qwen Code Tools -Im Kontext von Qwen Code sind Tools spezifische Funktionen oder Module, die das Modell anfordern kann, um ausgeführt zu werden. Wenn du zum Beispiel das Modell bittest, „die Inhalte von `my_document.txt` zu zusammenzufassen“, wird es wahrscheinlich erkennen, dass es diese Datei lesen muss, und anschließend das `read_file`-Tool anfordern. +Im Kontext von Qwen Code sind Tools spezifische Funktionen oder Module, die das Modell anfordern kann, um sie auszuführen. Wenn du das Modell zum Beispiel bittest, „die Inhalte von `my_document.txt` zu zusammenzufassen“, wird es wahrscheinlich erkennen, dass es diese Datei lesen muss, und anschließend das `read_file`-Tool anfordern. -Die Kernkomponente (`packages/core`) verwaltet diese Tools, stellt deren Definitionen (Schemas) dem Modell zur Verfügung, führt sie bei Anforderung aus und gibt die Ergebnisse an das Modell zurück, damit diese in eine benutzerfreundliche Antwort weiterverarbeitet werden können. +Die Kernkomponente (`packages/core`) verwaltet diese Tools, stellt deren Definitionen (Schemas) dem Modell zur Verfügung, führt sie bei Anforderung aus und gibt die Ergebnisse an das Modell zurück, damit diese in eine nutzbare Antwort weiterverarbeitet werden können. Diese Tools bieten folgende Funktionen: -- **Zugriff auf lokale Informationen:** Tools ermöglichen dem Modell den Zugriff auf dein lokales Dateisystem, das Lesen von Dateiinhalten, das Auflisten von Verzeichnissen usw. -- **Ausführen von Befehlen:** Mit Tools wie `run_shell_command` kann das Modell Shell-Befehle ausführen (mit entsprechenden Sicherheitsmaßnahmen und Benutzerbestätigung). -- **Interaktion mit dem Web:** Tools können Inhalte von URLs abrufen. +- **Zugriff auf lokale Informationen:** Tools ermöglichen es dem Modell, auf dein lokales Dateisystem zuzugreifen, Dateiinhalte zu lesen, Verzeichnisse aufzulisten usw. +- **Befehle ausführen:** Mit Tools wie `run_shell_command` kann das Modell Shell-Befehle ausführen (mit entsprechenden Sicherheitsmaßnahmen und Benutzerbestätigung). +- **Mit dem Web interagieren:** Tools können Inhalte von URLs abrufen. - **Aktionen durchführen:** Tools können Dateien ändern, neue Dateien schreiben oder andere Aktionen auf deinem System ausführen (in der Regel mit Sicherheitsvorkehrungen). -- **Antworten kontextbasiert gestalten:** Durch den Einsatz von Tools, um Echtzeit- oder lokale Daten abzurufen, können die Antworten präziser, relevanter und besser an deinen tatsächlichen Kontext angepasst sein. +- **Antworten kontextbasiert gestalten:** Durch den Einsatz von Tools, um Echtzeit- oder lokale Daten abzurufen, können die Antworten präziser, relevanter und besser an deinem tatsächlichen Kontext ausgerichtet werden. ## Wie man Qwen Code Tools verwendet -Um die Qwen Code Tools zu verwenden, gib einen Prompt an die CLI weiter. Der Prozess funktioniert wie folgt: +Um Qwen Code Tools zu verwenden, übergibst du einen Prompt an die CLI. Der Prozess funktioniert wie folgt: -1. Du gibst einen Prompt an die CLI ein. +1. Du übergibst einen Prompt an die CLI. 2. Die CLI sendet den Prompt an den Core. 3. Der Core sendet zusammen mit deinem Prompt und dem Konversationsverlauf eine Liste der verfügbaren Tools sowie deren Beschreibungen/Schemas an die konfigurierte Model API. -4. Das Modell analysiert deine Anfrage. Falls es feststellt, dass ein Tool benötigt wird, enthält seine Antwort eine Anforderung zur Ausführung eines bestimmten Tools mit spezifischen Parametern. -5. Der Core empfängt diese Tool-Anfrage, validiert sie und führt das Tool aus (häufig nach einer Bestätigung durch den Benutzer bei sensiblen Operationen). +4. Das Modell analysiert deine Anfrage. Falls es feststellt, dass ein Tool benötigt wird, enthält seine Antwort eine Anforderung, ein bestimmtes Tool mit spezifischen Parametern auszuführen. +5. Der Core empfängt diese Tool-Anforderung, validiert sie und führt das Tool aus (häufig nach einer Bestätigung durch den Benutzer bei sensiblen Operationen). 6. Die Ausgabe des Tools wird zurück an das Modell gesendet. 7. Das Modell verwendet die Tool-Ausgabe, um seine endgültige Antwort zu formulieren, welche dann über den Core an die CLI zurückgesendet und dir angezeigt wird. -In der Regel wirst du in der CLI Meldungen sehen, die anzeigen, wann ein Tool aufgerufen wird und ob der Aufruf erfolgreich war oder fehlgeschlagen ist. +In der Regel wirst du in der CLI Nachrichten sehen, die anzeigen, wann ein Tool aufgerufen wird und ob der Aufruf erfolgreich war oder fehlgeschlagen ist. ## Sicherheit und Bestätigung Viele Tools, insbesondere solche, die dein Dateisystem ändern oder Befehle ausführen können (`write_file`, `edit`, `run_shell_command`), sind mit Sicherheit im Hinterkopf entwickelt. Qwen Code wird typischerweise: -- **Bestätigung erfordern:** Dich vor dem Ausführen potenziell sensibler Operationen um Bestätigung bitten und dir zeigen, welche Aktion als nächstes durchgeführt wird. +- **Bestätigung erfordern:** Dich vor dem Ausführen potenziell sensibler Operationen einen Hinweis anzeigen und dir zeigen, welche Aktion als nächstes durchgeführt wird. - **Sandboxing nutzen:** Alle Tools unterliegen Einschränkungen, die durch Sandboxing erzwungen werden (siehe [Sandboxing in Qwen Code](../sandbox.md)). Das bedeutet, dass bei der Ausführung in einer Sandbox alle Tools (einschließlich MCP-Server), die du verwenden möchtest, _innerhalb_ der Sandbox-Umgebung verfügbar sein müssen. Um beispielsweise einen MCP-Server über `npx` auszuführen, muss die `npx`-Executable innerhalb des Docker-Images der Sandbox installiert oder in der `sandbox-exec`-Umgebung verfügbar sein. -Es ist wichtig, die Bestätigungsdialoge stets sorgfältig zu prüfen, bevor du einem Tool erlaubst fortzufahren. +Es ist wichtig, die Bestätigungshinweise sorgfältig zu prüfen, bevor du einem Tool erlaubst fortzufahren. ## Erfahre mehr über Qwen Codes Tools @@ -49,8 +49,9 @@ Die integrierten Tools von Qwen Code lassen sich grob wie folgt kategorisieren: - **[Web Search Tool](./web-search.md) (`web_search`):** Zum Durchsuchen des Webs. - **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** Ein spezialisiertes Tool zum Lesen von Inhalten aus mehreren Dateien oder Verzeichnissen, häufig verwendet vom `@` Befehl. - **[Memory Tool](./memory.md) (`save_memory`):** Zum Speichern und Abrufen von Informationen über mehrere Sitzungen hinweg. +- **[Todo Write Tool](./todo-write.md) (`todo_write`):** Zum Erstellen und Verwalten strukturierter Aufgabenlisten während Codierungs-Sitzungen. Zusätzlich integrieren diese Tools: -- **[MCP servers](./mcp-server.md)**: MCP-Server fungieren als Brücke zwischen dem Modell und deiner lokalen Umgebung oder anderen Diensten wie APIs. -- **[Sandboxing](../sandbox.md)**: Sandboxing isoliert das Modell und dessen Änderungen von deiner Umgebung, um potenzielle Risiken zu reduzieren. \ No newline at end of file +- **[MCP Server](./mcp-server.md):** MCP Server fungieren als Brücke zwischen dem Modell und deiner lokalen Umgebung oder anderen Diensten wie APIs. +- **[Sandboxing](../sandbox.md):** Sandboxing isoliert das Modell und dessen Änderungen von deiner Umgebung, um potenzielle Risiken zu reduzieren. \ No newline at end of file diff --git a/website/content/de/tools/shell.md b/website/content/de/tools/shell.md index 9acd2468..dcc72f39 100644 --- a/website/content/de/tools/shell.md +++ b/website/content/de/tools/shell.md @@ -10,59 +10,110 @@ Verwende `run_shell_command`, um mit dem zugrunde liegenden System zu interagier `run_shell_command` akzeptiert die folgenden Argumente: -- `command` (string, required): Der exakte Shell-Befehl, der ausgeführt werden soll. +- `command` (string, erforderlich): Der exakte Shell-Befehl, der ausgeführt werden soll. - `description` (string, optional): Eine kurze Beschreibung des Zwecks des Befehls, die dem Benutzer angezeigt wird. - `directory` (string, optional): Das Verzeichnis (relativ zum Projektstamm), in dem der Befehl ausgeführt werden soll. Wenn nicht angegeben, wird der Befehl im Projektstamm ausgeführt. +- `is_background` (boolean, erforderlich): Ob der Befehl im Hintergrund ausgeführt werden soll. Dieser Parameter ist erforderlich, um eine explizite Entscheidung über den Ausführungsmodus des Befehls zu gewährleisten. Auf `true` setzen für langlaufende Prozesse wie Entwicklungsserver, Watcher oder Daemons, die weiterlaufen sollen, ohne weitere Befehle zu blockieren. Auf `false` setzen für einmalige Befehle, die abgeschlossen werden müssen, bevor fortgefahren wird. ## Verwendung von `run_shell_command` mit Qwen Code -Bei der Verwendung von `run_shell_command` wird der Befehl als Subprozess ausgeführt. `run_shell_command` kann Hintergrundprozesse mit `&` starten. Das Tool gibt detaillierte Informationen über die Ausführung zurück, darunter: +Bei der Verwendung von `run_shell_command` wird der Befehl als Subprozess ausgeführt. Du kannst steuern, ob Befehle im Hintergrund oder Vordergrund laufen, indem du den Parameter `is_background` verwendest oder explizit ein `&` an die Befehle anhängst. Das Tool gibt detaillierte Informationen über die Ausführung zurück, darunter: -- `Command`: Der ausgeführte Befehl. +### Erforderlicher Background-Parameter + +Der Parameter `is_background` ist **erforderlich** für alle Befehlsausführungen. Dieses Design stellt sicher, dass das LLM (und die Benutzer) explizit entscheiden müssen, ob jeder Befehl im Hintergrund oder Vordergrund ausgeführt werden soll. Dadurch wird ein bewusstes und vorhersehbares Verhalten bei der Befehlsausführung gefördert. Durch die obligatorische Angabe dieses Parameters wird vermieden, dass unbeabsichtigt auf die Vordergrundausführung zurückgegriffen wird, was bei lang laufenden Prozessen nachfolgende Operationen blockieren könnte. + +### Background vs Foreground Execution + +Das Tool behandelt Background- und Foreground-Ausführung intelligent basierend auf deiner expliziten Auswahl: + +**Verwende Background-Ausführung (`is_background: true`) für:** + +- Langlaufende Development-Server: `npm run start`, `npm run dev`, `yarn dev` +- Build-Watcher: `npm run watch`, `webpack --watch` +- Datenbank-Server: `mongod`, `mysql`, `redis-server` +- Web-Server: `python -m http.server`, `php -S localhost:8000` +- Jeder Befehl, der unbestimmt lange läuft, bis er manuell gestoppt wird + +**Verwende Foreground-Ausführung (`is_background: false`) für:** + +- Einmalige Befehle: `ls`, `cat`, `grep` +- Build-Befehle: `npm run build`, `make` +- Installationsbefehle: `npm install`, `pip install` +- Git-Operationen: `git commit`, `git push` +- Testläufe: `npm test`, `pytest` + +### Ausführungs-Informationen + +Das Tool gibt detaillierte Informationen über die Ausführung zurück, darunter: + +- `Command`: Der Befehl, der ausgeführt wurde. - `Directory`: Das Verzeichnis, in dem der Befehl ausgeführt wurde. -- `Stdout`: Ausgabe des Standardausgabestreams. -- `Stderr`: Ausgabe des Standardfehlerstreams. -- `Error`: Fehlermeldung, die vom Subprozess gemeldet wurde. +- `Stdout`: Ausgabe des Standard-Ausgabestreams. +- `Stderr`: Ausgabe des Standard-Fehlerstreams. +- `Error`: Jegliche Fehlermeldung, die vom Subprozess gemeldet wurde. - `Exit Code`: Der Exit-Code des Befehls. - `Signal`: Die Signalnummer, falls der Befehl durch ein Signal beendet wurde. -- `Background PIDs`: Eine Liste der PIDs für gestartete Hintergrundprozesse. +- `Background PIDs`: Eine Liste der PIDs für alle gestarteten Hintergrundprozesse. Verwendung: +```bash +run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.", is_background=false) ``` -run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.") -``` + +**Hinweis:** Der Parameter `is_background` ist erforderlich und muss für jede Befehlsausführung explizit angegeben werden. ## `run_shell_command` Beispiele Dateien im aktuellen Verzeichnis auflisten: -``` -run_shell_command(command="ls -la") +```bash +run_shell_command(command="ls -la", is_background=false) ``` Ein Skript in einem bestimmten Verzeichnis ausführen: +```bash +run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script", is_background=false) +``` + +Einen Development-Server im Hintergrund starten (empfohlener Ansatz): + +```bash +run_shell_command(command="npm run dev", description="Start development server in background", is_background=true) ``` -run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script") + +Einen Server im Hintergrund starten (Alternative mit explizitem &): + +```bash +run_shell_command(command="npm run dev &", description="Start development server in background", is_background=false) ``` -Einen Server im Hintergrund starten: +Einen Build-Befehl im Vordergrund ausführen: +```bash +run_shell_command(command="npm run build", description="Build the project", is_background=false) ``` -run_shell_command(command="npm run dev &", description="Start development server in background") + +Mehrere Services im Hintergrund starten: + +```bash +run_shell_command(command="docker-compose up", description="Start all services", is_background=true) ``` ## Wichtige Hinweise - **Sicherheit:** Sei vorsichtig beim Ausführen von Befehlen, besonders solchen, die aus Benutzereingaben zusammengesetzt werden, um Sicherheitslücken zu vermeiden. -- **Interaktive Befehle:** Vermeide Befehle, die eine interaktive Eingabe des Benutzers erfordern, da dies dazu führen kann, dass das Tool hängen bleibt. Verwende nach Möglichkeit nicht-interaktive Flags (z. B. `npm init -y`). +- **Interaktive Befehle:** Vermeide Befehle, die eine interaktive Benutzereingabe erfordern, da dies dazu führen kann, dass das Tool hängen bleibt. Verwende nach Möglichkeit nicht-interaktive Flags (z. B. `npm init -y`). - **Fehlerbehandlung:** Prüfe die Felder `Stderr`, `Error` und `Exit Code`, um festzustellen, ob ein Befehl erfolgreich ausgeführt wurde. -- **Hintergrundprozesse:** Wenn ein Befehl mit `&` im Hintergrund ausgeführt wird, kehrt das Tool sofort zurück und der Prozess läuft weiterhin im Hintergrund. Das Feld `Background PIDs` enthält die Prozess-ID des Hintergrundprozesses. +- **Hintergrundprozesse:** Wenn `is_background=true` ist oder wenn ein Befehl `&` enthält, kehrt das Tool sofort zurück und der Prozess läuft im Hintergrund weiter. Das Feld `Background PIDs` enthält die Prozess-ID des Hintergrundprozesses. +- **Auswahl der Hintergrundausführung:** Der Parameter `is_background` ist erforderlich und bietet explizite Kontrolle über den Ausführungsmodus. Du kannst auch `&` zum Befehl hinzufügen, um die manuelle Hintergrundausführung zu erzwingen, aber der Parameter `is_background` muss dennoch angegeben werden. Der Parameter macht die Absicht klarer und übernimmt automatisch das Setup für die Hintergrundausführung. +- **Befehlsbeschreibungen:** Bei Verwendung von `is_background=true` enthält die Befehlsbeschreibung einen `[background]`-Hinweis, um den Ausführungsmodus klar zu kennzeichnen. ## Umgebungsvariablen -Wenn `run_shell_command` einen Befehl ausführt, setzt es die Umgebungsvariable `QWEN_CODE=1` in der Umgebung des Subprozesses. Dadurch können Skripte oder Tools erkennen, ob sie aus der CLI heraus ausgeführt werden. +Wenn `run_shell_command` einen Befehl ausführt, setzt es die Umgebungsvariable `QWEN_CODE=1` in der Umgebung des Subprozesses. Dies ermöglicht es Skripten oder Tools zu erkennen, ob sie aus der CLI heraus ausgeführt werden. ## Command Restrictions @@ -74,7 +125,7 @@ Du kannst die Befehle, die vom `run_shell_command` Tool ausgeführt werden dürf Die Validierungslogik ist sicher und flexibel gestaltet: 1. **Command Chaining deaktiviert**: Das Tool trennt automatisch verkettete Befehle, die mit `&&`, `||` oder `;` verbunden sind, und validiert jeden Teil separat. Wenn ein Teil der Kette nicht erlaubt ist, wird der gesamte Befehl blockiert. -2. **Präfix-Matching**: Das Tool verwendet Präfix-Matching. Wenn du beispielsweise `git` erlaubst, kannst du auch `git status` oder `git log` ausführen. +2. **Präfix-basiertes Matching**: Das Tool verwendet Präfix-Vergleiche. Wenn du beispielsweise `git` erlaubst, kannst du auch `git status` oder `git log` ausführen. 3. **Blocklist hat Vorrang**: Die `excludeTools` Liste wird immer zuerst überprüft. Wenn ein Befehl einem blockierten Präfix entspricht, wird er abgelehnt – selbst dann, wenn er gleichzeitig einem erlaubten Präfix aus `coreTools` entspricht. ### Beispiele für Befehlseinschränkungen diff --git a/website/content/de/tools/todo-write.md b/website/content/de/tools/todo-write.md new file mode 100644 index 00000000..e8df9326 --- /dev/null +++ b/website/content/de/tools/todo-write.md @@ -0,0 +1,63 @@ +# Todo Write Tool (`todo_write`) + +Dieses Dokument beschreibt das `todo_write` Tool für Qwen Code. + +## Beschreibung + +Verwende `todo_write`, um eine strukturierte Aufgabenliste für deine aktuelle Coding-Session zu erstellen und zu verwalten. Dieses Tool hilft dem AI-Assistenten, den Fortschritt zu verfolgen und komplexe Aufgaben zu organisieren, indem es dir einen Überblick darüber gibt, welche Arbeiten gerade durchgeführt werden. + +### Argumente + +`todo_write` akzeptiert ein Argument: + +- `todos` (Array, erforderlich): Ein Array von Todo-Elementen, wobei jedes Element folgende Eigenschaften enthält: + - `id` (String, erforderlich): Eine eindeutige Kennung für das Todo-Element. + - `content` (String, erforderlich): Die Beschreibung der Aufgabe. + - `status` (String, erforderlich): Der aktuelle Status (`pending`, `in_progress` oder `completed`). + +## Wie man `todo_write` mit Qwen Code verwendet + +Der KI-Assistent verwendet dieses Tool automatisch, wenn er an komplexen, mehrstufigen Aufgaben arbeitet. Du musst es nicht explizit anfordern, aber du kannst den Assistenten bitten, eine Todo-Liste zu erstellen, wenn du den geplanten Ansatz für deine Anfrage sehen möchtest. + +Das Tool speichert Todo-Listen in deinem Home-Verzeichnis (`~/.qwen/todos/`) in sessionspezifischen Dateien, sodass jede Coding-Session ihre eigene Aufgabenliste verwaltet. + +## Wann die KI dieses Tool verwendet + +Der Assistent verwendet `todo_write` für: + +- Komplexe Aufgaben, die mehrere Schritte erfordern +- Feature-Implementierungen mit mehreren Komponenten +- Refactoring-Operationen über mehrere Dateien hinweg +- Jegliche Arbeit, die 3 oder mehr unterschiedliche Aktionen beinhaltet + +Der Assistent wird dieses Tool nicht für einfache, einstufige Aufgaben oder rein informative Anfragen verwenden. + +### `todo_write` Beispiele + +Erstellen eines Feature-Implementierungsplans: + +``` +todo_write(todos=[ + { + "id": "create-model", + "content": "Create user preferences model", + "status": "pending" + }, + { + "id": "add-endpoints", + "content": "Add API endpoints for preferences", + "status": "pending" + }, + { + "id": "implement-ui", + "content": "Implement frontend components", + "status": "pending" + } +]) +``` + +## Wichtige Hinweise + +- **Automatische Verwendung:** Der AI-Assistent verwaltet Todo-Listen automatisch während komplexer Aufgaben. +- **Fortschrittsanzeige:** Du siehst Todo-Listen in Echtzeit aktualisiert, während die Arbeit voranschreitet. +- **Session-Isolation:** Jede Coding-Session hat ihre eigene Todo-Liste, die andere Sessions nicht beeinträchtigt. \ No newline at end of file diff --git a/website/content/de/troubleshooting.md b/website/content/de/troubleshooting.md index 92ad8339..5536efa3 100644 --- a/website/content/de/troubleshooting.md +++ b/website/content/de/troubleshooting.md @@ -10,14 +10,14 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da ## Authentifizierungs- oder Login-Fehler - **Fehler: `Failed to login. Message: Request contains an invalid argument`** - - Benutzer mit Google Workspace-Konten oder Google Cloud-Konten, - die mit ihren Gmail-Konten verknüpft sind, können möglicherweise nicht den Free - Tier des Google Code Assist-Plans aktivieren. - - Für Google Cloud-Konten kannst du dies umgehen, indem du - `GOOGLE_CLOUD_PROJECT` auf deine Projekt-ID setzt. - - Alternativ kannst du den Gemini API-Key von - [Google AI Studio](http://aistudio.google.com/app/apikey) erhalten, der auch einen - separaten Free Tier beinhaltet. + - Benutzer mit Google Workspace-Konten oder Google Cloud-Konten, die mit ihren Gmail-Konten verknüpft sind, können möglicherweise den kostenlosen Tarif des Google Code Assist-Plans nicht aktivieren. + - Für Google Cloud-Konten kannst du dies umgehen, indem du `GOOGLE_CLOUD_PROJECT` auf deine Projekt-ID setzt. + - Alternativ kannst du den Gemini API key von [Google AI Studio](http://aistudio.google.com/app/apikey) erhalten, das ebenfalls einen separaten Free Tier enthält. + +- **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, dass ein benutzerdefiniertes Root-CA-Zertifikat von Node.js vertraut wird. + - **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) @@ -39,29 +39,29 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da - **Fehler: `EADDRINUSE` (Adresse bereits in Verwendung) beim Starten eines MCP-Servers.** - **Ursache:** Ein anderer Prozess verwendet bereits den Port, den der MCP-Server binden möchte. - **Lösung:** - Beende entweder den anderen Prozess, der den Port verwendet, oder konfiguriere den MCP-Server so, dass er einen anderen Port verwendet. + Beende den anderen Prozess, der den Port verwendet, oder konfiguriere den MCP-Server so, dass er einen anderen Port verwendet. - **Fehler: Befehl nicht gefunden (beim Versuch, Qwen Code mit `qwen` auszuführen).** - **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 dann den Befehl `npm run build` aus, um neu zu bauen. - **Fehler: `MODULE_NOT_FOUND` oder Import-Fehler.** - **Ursache:** Abhängigkeiten sind nicht korrekt installiert oder das Projekt wurde nicht gebaut. - **Lösung:** - 1. Führe `npm install` aus, um sicherzustellen, dass alle Abhängigkeiten vorhanden sind. - 2. Führe `npm run build` aus, um das Projekt zu kompilieren. - 3. Überprüfe mit `npm run start`, ob der Build erfolgreich abgeschlossen wurde. + 1. Führe `npm install` aus, um sicherzustellen, dass alle Abhängigkeiten vorhanden sind. + 2. Führe `npm run build` aus, um das Projekt zu kompilieren. + 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. außerhalb des Projektverzeichnisses oder des systemweiten Temp-Verzeichnisses zu schreiben. - **Lösung:** Weitere Informationen findest du in der Dokumentation unter [Configuration: Sandboxing](./cli/configuration.md#sandboxing), einschließlich Anweisungen zur Anpassung deiner Sandbox-Konfiguration. - **Qwen Code läuft in „CI“-Umgebungen nicht im interaktiven Modus** - - **Problem:** Qwen Code startet nicht im 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 die Umgebung nicht interaktiv ist, wodurch der Start im interaktiven Modus verhindert wird. + - **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 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** @@ -75,7 +75,7 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da - 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, überprüfe, ob `host.docker.internal` aufgelöst werden kann. Andernfalls musst du den Host entsprechend mappen. +- Wenn du in einem Container arbeitest, prü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. ## Debugging-Tipps @@ -92,9 +92,9 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da - **Tool-Probleme:** - Wenn ein bestimmtes Tool fehlschlägt, versuche das Problem zu isolieren, indem du die einfachste mögliche Version des Befehls oder der Operation ausführst, die das Tool durchführt. - 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 prüfe die Berechtigungen. + - Für _Filesystem-Tools_ stelle sicher, dass die Pfade korrekt sind und überprüfe die Berechtigungen. -- **Pre-Flight-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/cli/configuration.md b/website/content/en/cli/configuration.md index 18932ba8..78147c3f 100644 --- a/website/content/en/cli/configuration.md +++ b/website/content/en/cli/configuration.md @@ -432,6 +432,13 @@ Arguments passed directly when running the CLI can override other configurations - Displays the current memory usage. - **`--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 (replace, 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` - **`--telemetry`**: - Enables [telemetry](../telemetry.md). - **`--telemetry-target`**: @@ -532,7 +539,7 @@ Sandboxing is disabled by default, but you can enable it in a few ways: - Using `--sandbox` or `-s` flag. - Setting `GEMINI_SANDBOX` environment variable. -- Sandbox is enabled in `--yolo` mode by default. +- Sandbox is enabled when using `--yolo` or `--approval-mode=yolo` by default. By default, it uses a pre-built `qwen-code-sandbox` Docker image. diff --git a/website/content/en/deployment.md b/website/content/en/deployment.md index e59034f4..28d7a220 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.7 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.9 ``` - **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/ide-integration.md b/website/content/en/ide-integration.md new file mode 100644 index 00000000..a0bd4976 --- /dev/null +++ b/website/content/en/ide-integration.md @@ -0,0 +1,141 @@ +# IDE Integration + +Gemini CLI can integrate with your IDE to provide a more seamless and context-aware experience. This integration allows the CLI to understand your workspace better and enables powerful features like native in-editor diffing. + +Currently, the only supported IDE is [Visual Studio Code](https://code.visualstudio.com/) and other editors that support VS Code extensions. + +## Features + +- **Workspace Context:** The CLI automatically gains awareness of your workspace to provide more relevant and accurate responses. This context includes: + - The **10 most recently accessed files** in your workspace. + - Your active cursor position. + - Any text you have selected (up to a 16KB limit; longer selections will be truncated). + +- **Native Diffing:** When Gemini suggests code modifications, you can view the changes directly within your IDE's native diff viewer. This allows you to review, edit, and accept or reject the suggested changes seamlessly. + +- **VS Code Commands:** You can access Gemini CLI features directly from the VS Code Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`): + - `Gemini CLI: Run`: Starts a new Gemini CLI session in the integrated terminal. + - `Gemini CLI: Accept Diff`: Accepts the changes in the active diff editor. + - `Gemini CLI: Close Diff Editor`: Rejects the changes and closes the active diff editor. + - `Gemini CLI: View Third-Party Notices`: Displays the third-party notices for the extension. + +## Installation and Setup + +There are three ways to set up the IDE integration: + +### 1. Automatic Nudge (Recommended) + +When you run Gemini CLI inside a supported editor, it will automatically detect your environment and prompt you to connect. Answering "Yes" will automatically run the necessary setup, which includes installing the companion extension and enabling the connection. + +### 2. Manual Installation from CLI + +If you previously dismissed the prompt or want to install the extension manually, you can run the following command inside Gemini CLI: + +``` +/ide install +``` + +This will find the correct extension for your IDE and install it. + +### 3. Manual Installation from a Marketplace + +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=google.gemini-cli-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/google/gemini-cli-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. + +## Usage + +### Enabling and Disabling + +You can control the IDE integration from within the CLI: + +- To enable the connection to the IDE, run: + ``` + /ide enable + ``` +- To disable the connection, run: + ``` + /ide disable + ``` + +When enabled, Gemini CLI will automatically attempt to connect to the IDE companion extension. + +### Checking the Status + +To check the connection status and see the context the CLI has received from the IDE, run: + +``` +/ide status +``` + +If connected, this command will show the IDE it's connected to and a list of recently opened files it is aware of. + +(Note: The file list is limited to 10 recently accessed files within your workspace and only includes local files on disk.) + +### Working with Diffs + +When you ask Gemini 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: + +- Click the **checkmark icon** in the diff editor's title bar. +- Save the file (e.g., with `Cmd+S` or `Ctrl+S`). +- Open the Command Palette and run **Gemini CLI: Accept Diff**. +- Respond with `yes` in the CLI when prompted. + +**To reject a diff**, you can: + +- Click the **'x' icon** in the diff editor's title bar. +- Close the diff editor tab. +- Open the Command Palette and run **Gemini CLI: Close Diff Editor**. +- Respond with `no` in the CLI when prompted. + +You can also **modify the suggested changes** directly in the diff view before accepting them. + +If you select ‘Yes, allow always’ in the CLI, changes will no longer show up in the IDE as they will be auto-accepted. + +## Using with Sandboxing + +If you are using Gemini CLI within a sandbox, please be aware of the following: + +- **On macOS:** The IDE integration requires network access to communicate with the IDE companion extension. You must use a Seatbelt profile that allows network access. +- **In a Docker Container:** If you run Gemini CLI inside a Docker (or Podman) container, the IDE integration can still connect to the VS Code extension running on your host machine. The CLI is configured to automatically find the IDE server on `host.docker.internal`. No special configuration is usually required, but you may need to ensure your Docker networking setup allows connections from the container to the host. + +## Troubleshooting + +If you encounter issues with IDE integration, here are some common error messages and how to resolve them. + +### Connection Errors + +- **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:** Gemini CLI could not find the necessary environment variables (`GEMINI_CLI_IDE_WORKSPACE_PATH` or `GEMINI_CLI_IDE_SERVER_PORT`) to connect to the IDE. This usually means the IDE companion extension is not running or did not initialize correctly. + - **Solution:** + 1. Make sure you have installed the **Gemini CLI Companion** extension in your IDE and that it is enabled. + 2. Open a new terminal window in your IDE to ensure it picks up the correct environment. + +- **Message:** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` + - **Cause:** The connection to the IDE companion was lost. + - **Solution:** Run `/ide enable` to try and reconnect. If the issue continues, open a new terminal window or restart your IDE. + +### Configuration Errors + +- **Message:** `🔴 Disconnected: Directory mismatch. Gemini CLI 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:** 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. + +### General Errors + +- **Message:** `IDE integration is not supported in your current environment. To use this feature, run Gemini CLI in one of these supported IDEs: [List of IDEs]` + - **Cause:** You are running Gemini CLI in a terminal or environment that is not a supported IDE. + - **Solution:** Run Gemini CLI 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.` + - **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 "Gemini CLI Companion", and install it manually. diff --git a/website/content/en/index.md b/website/content/en/index.md index 03710f76..9c405645 100644 --- a/website/content/en/index.md +++ b/website/content/en/index.md @@ -18,6 +18,7 @@ This documentation is organized into the following sections: - **[Configuration](./cli/configuration.md):** Information on configuring the CLI. - **[Checkpointing](./checkpointing.md):** Documentation for the checkpointing feature. - **[Extensions](./extension.md):** How to extend the CLI with new functionality. + - **[IDE Integration](./ide-integration.md):** Connect the CLI to your editor. - **[Telemetry](./telemetry.md):** Overview of telemetry in the CLI. - **Core Details:** Documentation for `packages/core`. - **[Core Introduction](./core/index.md):** Overview of the core component. diff --git a/website/content/en/integration-tests.md b/website/content/en/integration-tests.md index cb611a4c..00c91fe1 100644 --- a/website/content/en/integration-tests.md +++ b/website/content/en/integration-tests.md @@ -67,13 +67,9 @@ The integration test runner provides several options for diagnostics to help tra You can preserve the temporary files created during a test run for inspection. This is useful for debugging issues with file system operations. -To keep the test output, you can either use the `--keep-output` flag or set the `KEEP_OUTPUT` environment variable to `true`. +To keep the test output set the `KEEP_OUTPUT` environment variable to `true`. ```bash -# Using the flag -npm run test:integration:sandbox:none -- --keep-output - -# Using the environment variable KEEP_OUTPUT=true npm run test:integration:sandbox:none ``` @@ -81,20 +77,20 @@ When output is kept, the test runner will print the path to the unique directory ### Verbose output -For more detailed debugging, the `--verbose` flag streams the real-time output from the `qwen` command to the console. +For more detailed debugging, set the `VERBOSE` environment variable to `true`. ```bash -npm run test:integration:sandbox:none -- --verbose +VERBOSE=true npm run test:integration:sandbox:none ``` -When using `--verbose` and `--keep-output` in the same command, the output is streamed to the console and also saved to a log file within the test's temporary directory. +When using `VERBOSE=true` and `KEEP_OUTPUT=true` in the same command, the output is streamed to the console and also saved to a log file within the test's temporary directory. The verbose output is formatted to clearly identify the source of the logs: ``` ---- TEST: : --- +--- TEST: : --- ... output from the qwen command ... ---- END TEST: : --- +--- END TEST: : --- ``` ## Linting and formatting diff --git a/website/content/en/npm.md b/website/content/en/npm.md index f32c50bc..43332193 100644 --- a/website/content/en/npm.md +++ b/website/content/en/npm.md @@ -58,7 +58,7 @@ To install the latest nightly build, use the `@nightly` tag: npm install -g @qwen-code/qwen-code@nightly ``` -We also run a Google cloud build called [release-docker.yml](../.gcp/release-docker.yaml). Which publishes the sandbox docker to match your release. This will also be moved to GH and combined with the main release file once service account permissions are sorted out. +We also run a Google cloud build called [release-docker.yml](../.gcp/release-docker.yml). Which publishes the sandbox docker to match your release. This will also be moved to GH and combined with the main release file once service account permissions are sorted out. ### After the Release diff --git a/website/content/en/tools/file-system.md b/website/content/en/tools/file-system.md index 965ff9af..45c1eaa7 100644 --- a/website/content/en/tools/file-system.md +++ b/website/content/en/tools/file-system.md @@ -89,10 +89,13 @@ Qwen Code provides a comprehensive suite of tools for interacting with the local - `pattern` (string, required): The regular expression (regex) to search for (e.g., `"function\s+myFunction"`). - `path` (string, optional): The absolute path to the directory to search within. Defaults to the current working directory. - `include` (string, optional): A glob pattern to filter which files are searched (e.g., `"*.js"`, `"src/**/*.{ts,tsx}"`). If omitted, searches most files (respecting common ignores). + - `maxResults` (number, optional): Maximum number of matches to return to prevent context overflow (default: 20, max: 100). Use lower values for broad searches, higher for specific searches. - **Behavior:** - Uses `git grep` if available in a Git repository for speed; otherwise, falls back to system `grep` or a JavaScript-based search. - Returns a list of matching lines, each prefixed with its file path (relative to the search directory) and line number. + - Limits results to a maximum of 20 matches by default to prevent context overflow. When results are truncated, shows a clear warning with guidance on refining searches. - **Output (`llmContent`):** A formatted string of matches, e.g.: + ``` Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"): --- @@ -103,9 +106,36 @@ Qwen Code provides a comprehensive suite of tools for interacting with the local File: src/index.ts L5: import { myFunction } from './utils'; --- + + WARNING: Results truncated to prevent context overflow. To see more results: + - Use a more specific pattern to reduce matches + - Add file filters with the 'include' parameter (e.g., "*.js", "src/**") + - Specify a narrower 'path' to search in a subdirectory + - Increase 'maxResults' parameter if you need more matches (current: 20) ``` + - **Confirmation:** No. +### `search_file_content` examples + +Search for a pattern with default result limiting: + +``` +search_file_content(pattern="function\s+myFunction", path="src") +``` + +Search for a pattern with custom result limiting: + +``` +search_file_content(pattern="function", path="src", maxResults=50) +``` + +Search for a pattern with file filtering and custom result limiting: + +``` +search_file_content(pattern="function", include="*.js", maxResults=10) +``` + ## 6. `replace` (Edit) `replace` replaces text within a file. By default, replaces a single occurrence, but can replace multiple occurrences when `expected_replacements` is specified. This tool is designed for precise, targeted changes and requires significant context around the `old_string` to ensure it modifies the correct location. diff --git a/website/content/en/tools/index.md b/website/content/en/tools/index.md index d586e37a..6c3cec3d 100644 --- a/website/content/en/tools/index.md +++ b/website/content/en/tools/index.md @@ -49,6 +49,7 @@ Qwen Code's built-in tools can be broadly categorized as follows: - **[Web Search Tool](./web-search.md) (`web_search`):** For searching the web. - **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** A specialized tool for reading content from multiple files or directories, often used by the `@` command. - **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling information across sessions. +- **[Todo Write Tool](./todo-write.md) (`todo_write`):** For creating and managing structured task lists during coding sessions. Additionally, these tools incorporate: diff --git a/website/content/en/tools/shell.md b/website/content/en/tools/shell.md index 77f6b026..9bd82a39 100644 --- a/website/content/en/tools/shell.md +++ b/website/content/en/tools/shell.md @@ -13,10 +13,39 @@ Use `run_shell_command` to interact with the underlying system, run scripts, or - `command` (string, required): The exact shell command to execute. - `description` (string, optional): A brief description of the command's purpose, which will be shown to the user. - `directory` (string, optional): The directory (relative to the project root) in which to execute the command. If not provided, the command runs in the project root. +- `is_background` (boolean, required): Whether to run the command in background. This parameter is required to ensure explicit decision-making about command execution mode. Set to true for long-running processes like development servers, watchers, or daemons that should continue running without blocking further commands. Set to false for one-time commands that should complete before proceeding. ## How to use `run_shell_command` with Qwen Code -When using `run_shell_command`, the command is executed as a subprocess. `run_shell_command` can start background processes using `&`. The tool returns detailed information about the execution, including: +When using `run_shell_command`, the command is executed as a subprocess. You can control whether commands run in background or foreground using the `is_background` parameter, or by explicitly adding `&` to commands. The tool returns detailed information about the execution, including: + +### Required Background Parameter + +The `is_background` parameter is **required** for all command executions. This design ensures that the LLM (and users) must explicitly decide whether each command should run in the background or foreground, promoting intentional and predictable command execution behavior. By making this parameter mandatory, we avoid unintended fallback to foreground execution, which could block subsequent operations when dealing with long-running processes. + +### Background vs Foreground Execution + +The tool intelligently handles background and foreground execution based on your explicit choice: + +**Use background execution (`is_background: true`) for:** + +- Long-running development servers: `npm run start`, `npm run dev`, `yarn dev` +- Build watchers: `npm run watch`, `webpack --watch` +- Database servers: `mongod`, `mysql`, `redis-server` +- Web servers: `python -m http.server`, `php -S localhost:8000` +- Any command expected to run indefinitely until manually stopped + +**Use foreground execution (`is_background: false`) for:** + +- One-time commands: `ls`, `cat`, `grep` +- Build commands: `npm run build`, `make` +- Installation commands: `npm install`, `pip install` +- Git operations: `git commit`, `git push` +- Test runs: `npm test`, `pytest` + +### Execution Information + +The tool returns detailed information about the execution, including: - `Command`: The command that was executed. - `Directory`: The directory where the command was run. @@ -29,28 +58,48 @@ When using `run_shell_command`, the command is executed as a subprocess. `run_sh Usage: +```bash +run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.", is_background=false) ``` -run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.") -``` + +**Note:** The `is_background` parameter is required and must be explicitly specified for every command execution. ## `run_shell_command` examples List files in the current directory: -``` -run_shell_command(command="ls -la") +```bash +run_shell_command(command="ls -la", is_background=false) ``` Run a script in a specific directory: +```bash +run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script", is_background=false) +``` + +Start a background development server (recommended approach): + +```bash +run_shell_command(command="npm run dev", description="Start development server in background", is_background=true) ``` -run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script") + +Start a background server (alternative with explicit &): + +```bash +run_shell_command(command="npm run dev &", description="Start development server in background", is_background=false) ``` -Start a background server: +Run a build command in foreground: +```bash +run_shell_command(command="npm run build", description="Build the project", is_background=false) ``` -run_shell_command(command="npm run dev &", description="Start development server in background") + +Start multiple background services: + +```bash +run_shell_command(command="docker-compose up", description="Start all services", is_background=true) ``` ## Important notes @@ -58,7 +107,9 @@ run_shell_command(command="npm run dev &", description="Start development server - **Security:** Be cautious when executing commands, especially those constructed from user input, to prevent security vulnerabilities. - **Interactive commands:** Avoid commands that require interactive user input, as this can cause the tool to hang. Use non-interactive flags if available (e.g., `npm init -y`). - **Error handling:** Check the `Stderr`, `Error`, and `Exit Code` fields to determine if a command executed successfully. -- **Background processes:** When a command is run in the background with `&`, the tool will return immediately and the process will continue to run in the background. The `Background PIDs` field will contain the process ID of the background process. +- **Background processes:** When `is_background=true` or when a command contains `&`, the tool will return immediately and the process will continue to run in the background. The `Background PIDs` field will contain the process ID of the background process. +- **Background execution choices:** The `is_background` parameter is required and provides explicit control over execution mode. You can also add `&` to the command for manual background execution, but the `is_background` parameter must still be specified. The parameter provides clearer intent and automatically handles the background execution setup. +- **Command descriptions:** When using `is_background=true`, the command description will include a `[background]` indicator to clearly show the execution mode. ## Environment Variables diff --git a/website/content/en/tools/todo-write.md b/website/content/en/tools/todo-write.md new file mode 100644 index 00000000..5da90b12 --- /dev/null +++ b/website/content/en/tools/todo-write.md @@ -0,0 +1,63 @@ +# Todo Write Tool (`todo_write`) + +This document describes the `todo_write` tool for Qwen Code. + +## Description + +Use `todo_write` to create and manage a structured task list for your current coding session. This tool helps the AI assistant track progress and organize complex tasks, providing you with visibility into what work is being performed. + +### Arguments + +`todo_write` takes one argument: + +- `todos` (array, required): An array of todo items, where each item contains: + - `id` (string, required): A unique identifier for the todo item. + - `content` (string, required): The description of the task. + - `status` (string, required): The current status (`pending`, `in_progress`, or `completed`). + +## How to use `todo_write` with Qwen Code + +The AI assistant will automatically use this tool when working on complex, multi-step tasks. You don't need to explicitly request it, but you can ask the assistant to create a todo list if you want to see the planned approach for your request. + +The tool stores todo lists in your home directory (`~/.qwen/todos/`) with session-specific files, so each coding session maintains its own task list. + +## When the AI uses this tool + +The assistant uses `todo_write` for: + +- Complex tasks requiring multiple steps +- Feature implementations with several components +- Refactoring operations across multiple files +- Any work involving 3 or more distinct actions + +The assistant will not use this tool for simple, single-step tasks or purely informational requests. + +### `todo_write` examples + +Creating a feature implementation plan: + +``` +todo_write(todos=[ + { + "id": "create-model", + "content": "Create user preferences model", + "status": "pending" + }, + { + "id": "add-endpoints", + "content": "Add API endpoints for preferences", + "status": "pending" + }, + { + "id": "implement-ui", + "content": "Implement frontend components", + "status": "pending" + } +]) +``` + +## Important notes + +- **Automatic usage:** The AI assistant manages todo lists automatically during complex tasks. +- **Progress visibility:** You'll see todo lists updated in real-time as work progresses. +- **Session isolation:** Each coding session has its own todo list that doesn't interfere with others. diff --git a/website/content/en/troubleshooting.md b/website/content/en/troubleshooting.md index 067ff0b5..e9252dba 100644 --- a/website/content/en/troubleshooting.md +++ b/website/content/en/troubleshooting.md @@ -19,6 +19,11 @@ This guide provides solutions to common issues and debugging tips, including top [Google AI Studio](http://aistudio.google.com/app/apikey), which also includes a separate free tier. +- **Error: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` or `unable to get local issuer certificate`** + - **Cause:** You may be on a corporate network with a firewall that intercepts and inspects SSL/TLS traffic. This often requires a custom root CA certificate to be trusted by Node.js. + - **Solution:** Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of your corporate root CA certificate file. + - Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` + ## Frequently asked questions (FAQs) - **Q: How do I update Qwen Code to the latest version?** diff --git a/website/content/fr/cli/configuration.md b/website/content/fr/cli/configuration.md index 82e2ea77..b81f82a4 100644 --- a/website/content/fr/cli/configuration.md +++ b/website/content/fr/cli/configuration.md @@ -24,10 +24,10 @@ Qwen Code utilise des fichiers `settings.json` pour la configuration persistante - **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. - **Fichier de configuration système :** - - **Emplacement :** `/etc/gemini-cli/settings.json` (Linux), `C:\ProgramData\gemini-cli\settings.json` (Windows) ou `/Library/Application Support/GeminiCli/settings.json` (macOS). Ce chemin peut être modifié via la variable d'environnement `GEMINI_CLI_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 ont priorité sur les paramètres utilisateur et projet. Peut être utile aux administrateurs système dans les entreprises pour contrôler les configurations Qwen Code des utilisateurs. + - **Emplacement :** `/etc/gemini-cli/settings.json` (Linux), `C:\ProgramData\gemini-cli\settings.json` (Windows) ou `/Library/Application Support/GeminiCli/settings.json` (macOS). Ce chemin peut être modifié via la variable d’environnement `GEMINI_CLI_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 ont priorité sur les paramètres utilisateur et projet. Peut être utile aux administrateurs système dans un environnement d'entreprise pour 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 fichiers de configuration :** 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"`. ### Le répertoire `.qwen` dans votre projet @@ -43,7 +43,7 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro - **Exemple :** `"contextFileName": "AGENTS.md"` - **`bugCommand`** (objet) : - - **Description :** Remplace l'URL par défaut de la commande `/bug`. + - **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}"` - **Propriétés :** - **`urlTemplate`** (string) : Une URL pouvant contenir les placeholders `{title}` et `{info}`. @@ -58,7 +58,7 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro - **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` - **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. + - **`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 listages 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. - **Exemple :** ```json @@ -74,25 +74,25 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro - **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 qui le supportent, comme `ShellTool`. Par exemple, `"excludeTools": ["ShellTool(rm -rf)"]` bloquera la commande `rm -rf`. + - **Description :** Permet de spécifier une liste d'outils intégrés à exclure du modèle. Un outil présent dans `excludeTools` et `coreTools` est exclu. Vous pouvez également spécifier des restrictions par commande pour les outils qui le supportent, 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. Il est recommandé d'utiliser `coreTools` pour sélectionner explicitement les commandes autorisées. + - **Note de sécurité :** Les restrictions par commande dans `excludeTools` pour `run_shell_command` reposent sur une simple correspondance 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. Il est recommandé d'utiliser `coreTools` pour sélectionner explicitement les commandes autorisé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 les serveurs MCP auxquels se connecter. Notez que ce paramètre est ignoré si `--allowed-mcp-server-names` est défini. - **Par défaut :** Tous les serveurs MCP sont disponibles. - **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. + - **Note de sécurité :** Ce paramètre 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, configurez `mcpServers` au niveau des paramètres système de sorte que l'utilisateur ne puisse pas configurer ses propres serveurs MCP. Ne pas utiliser comme mécanisme de sécurité strict. - **`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. + - **Description :** Permet de spécifier une liste de serveurs MCP à exclure du modèle. Un serveur présent dans `excludeMCPServers` et `allowMCPServers` est exclu. Notez que ce paramètre est ignoré 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. + - **Note de sécurité :** Ce paramètre 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, configurez `mcpServers` au niveau des paramètres système de sorte que l'utilisateur ne puisse pas configurer ses propres serveurs MCP. Ne pas utiliser comme mécanisme de sécurité strict. - **`autoAccept`** (boolean) : - - **Description :** Contrôle si le CLI accepte et exécute automatiquement les appels d'outils considérés comme 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 jugés sûrs. + - **Description :** Contrôle si le CLI accepte automatiquement et exécute les appels d'outils considérés comme 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 jugés sûrs. - **Par défaut :** `false` - **Exemple :** `"autoAccept": true` @@ -118,14 +118,14 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro - **`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 : - - Elle doit 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. - - 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). + - 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). - **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 supprimer certaines propriétés du schéma des définitions d'outils MCP pour des raisons de compatibilité. + - **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. Le système peut retirer certaines propriétés de schéma des définitions d'outils MCP pour des raisons de compatibilité. - **Par défaut :** Vide - **Propriétés :** - **``** (objet) : Les paramètres du serveur nommé. @@ -247,7 +247,10 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro - **`includeDirectories`** (tableau de strings) : - **Description :** Spécifie un tableau de chemins absolus ou relatifs supplémentaires à inclure dans le contexte de l'espace de travail. Cela permet de travailler avec des fichiers situés dans plusieurs répertoires comme s'ils étaient dans un seul. Les chemins peuvent utiliser `~` pour faire référence au répertoire personnel de l'utilisateur. Ce paramètre peut être combiné avec le flag `--include-directories` en ligne de commande. - - ** + - **Par défaut :** `[]` + - **Exemple :** + ```json + "includeDirectories": [ ### Exemple `settings.json` : @@ -298,13 +301,13 @@ Le CLI conserve un historique des commandes shell que vous exécutez. Pour évit ## 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. +Les variables d'environnement sont un moyen courant de configurer les applications, en particulier pour les informations sensibles comme les clés API ou les paramètres qui peuvent varier selon les environnements. Le CLI charge automatiquement les variables d'environnement depuis un fichier `.env`. L'ordre de chargement est le suivant : -1. Fichier `.env` dans le répertoire de travail 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 non trouvé, il cherche `~/.env` (dans le répertoire utilisateur). +1. Fichier `.env` dans le répertoire de travail 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 non trouvé, il cherche `~/.env` (dans le répertoire utilisateur). **Exclusion de variables d'environnement :** Certaines variables d'environnement (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 provenant des fichiers `.qwen/.env` ne sont jamais exclues. Vous pouvez personnaliser ce comportement en utilisant le paramètre `excludedProjectEnvVars` dans votre fichier `settings.json`. @@ -314,7 +317,7 @@ Le CLI charge automatiquement les variables d'environnement depuis un fichier `. - Définissez-la dans votre profil shell (ex. `~/.bashrc`, `~/.zshrc`) ou dans un fichier `.env`. - **`GEMINI_MODEL`** : - Spécifie le modèle Gemini par défaut à utiliser. - - Remplace le modèle par défaut codé en dur. + - Remplace le modèle codé en dur par défaut. - Exemple : `export GEMINI_MODEL="gemini-2.5-flash"` - **`GOOGLE_API_KEY`** : - Votre clé API Google Cloud. @@ -325,7 +328,7 @@ Le CLI charge automatiquement les variables d'environnement depuis un fichier `. - L'ID de votre projet Google Cloud. - Requis pour utiliser Code Assist ou Vertex AI. - Si vous utilisez Vertex AI, assurez-vous d'avoir les permissions nécessaires sur ce projet. - - **Note Cloud Shell :** Lorsque vous exécutez le CLI dans un environnement Cloud Shell, cette variable est définie par défaut sur un projet spécial alloué aux utilisateurs Cloud Shell. Si vous avez défini `GOOGLE_CLOUD_PROJECT` dans votre environnement global dans Cloud Shell, elle sera remplacée par cette valeur par défaut. Pour utiliser un projet différent dans Cloud Shell, vous devez définir `GOOGLE_CLOUD_PROJECT` dans un fichier `.env`. + - **Note Cloud Shell :** Lorsque vous exécutez le CLI dans un environnement Cloud Shell, cette variable est définie par défaut sur un projet spécial alloué aux utilisateurs Cloud Shell. Si vous avez défini `GOOGLE_CLOUD_PROJECT` dans votre environnement global dans Cloud Shell, elle sera remplacée par cette valeur par défaut. Pour utiliser un autre projet dans Cloud Shell, vous devez définir `GOOGLE_CLOUD_PROJECT` dans un fichier `.env`. - Exemple : `export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. - **`GOOGLE_APPLICATION_CREDENTIALS`** (string) : - **Description :** Le chemin vers votre fichier JSON de Google Application Credentials. @@ -340,20 +343,20 @@ Le CLI charge automatiquement les variables d'environnement depuis un fichier `. - **`GEMINI_SANDBOX`** : - Alternative au paramètre `sandbox` dans `settings.json`. - Accepte `true`, `false`, `docker`, `podman`, ou une commande personnalisée sous forme de chaîne. -- **`SEATBELT_PROFILE`** (spécifique à macOS) : +- **`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 dossiers, 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`). -- **`DEBUG` ou `DEBUG_MODE`** (souvent utilisées par les bibliothèques sous-jacentes ou le CLI lui-même) : +- **`DEBUG` ou `DEBUG_MODE`** (souvent utilisés par les bibliothèques sous-jacentes ou le CLI lui-même) : - Définir à `true` ou `1` active la journalisation détaillée, utile 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. - **`NO_COLOR`** : - Définir à n'importe quelle valeur désactive toute sortie colorée dans le CLI. - **`CLI_TITLE`** : - - Définir à une chaîne de caractères pour personnaliser le titre du CLI. + - Définir à une chaîne pour personnaliser le titre du CLI. - **`CODE_ASSIST_ENDPOINT`** : - - Spécifie l'endpoint du serveur code assist. + - Spécifie l'endpoint du serveur d'assistance au code. - Utile pour le développement et les tests. - **`TAVILY_API_KEY`** : - Votre clé API pour le service de recherche web Tavily. @@ -373,7 +376,7 @@ Les arguments passés directement lors de l'exécution du CLI peuvent remplacer - **`--prompt-interactive `** (**`-i `**) : - Démarre une session interactive avec le prompt fourni comme entrée initiale. - Le prompt est traité dans la session interactive, et non avant celle-ci. - - Ne peut pas être utilisé lorsque l'entrée provient de stdin via un pipe. + - Ne peut pas être utilisé lorsque l'entrée provient d'un pipe via stdin. - Exemple : `qwen -i "explain this code"` - **`--sandbox`** (**`-s`**) : - Active le mode sandbox pour cette session. @@ -382,13 +385,20 @@ Les arguments passés directement lors de l'exécution du CLI peuvent remplacer - **`--debug`** (**`-d`**) : - Active le mode debug pour cette session, fournissant une sortie plus verbeuse. - **`--all-files`** (**`-a`**) : - - Si activé, inclut récursivement tous les fichiers du répertoire courant comme contexte pour le prompt. + - Si défini, inclut récursivement tous les fichiers du répertoire courant comme contexte pour le prompt. - **`--help`** (ou **`-h`**) : - Affiche les informations d'aide concernant les arguments de ligne de commande. - **`--show-memory-usage`** : - Affiche l'utilisation actuelle de la mémoire. - **`--yolo`** : - Active le mode YOLO, qui approuve automatiquement tous les appels d'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 (replace, write_file) tout en demandant une validation 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` - **`--telemetry`** : - Active la [télémétrie](../telemetry.md). - **`--telemetry-target`** : @@ -400,7 +410,7 @@ Les arguments passés directement lors de l'exécution du CLI peuvent remplacer - **`--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`**) : @@ -416,14 +426,14 @@ Les arguments passés directement lors de l'exécution du CLI peuvent remplacer - **`--version`** : - Affiche la version du CLI. - **`--openai-logging`** : - - Active la journalisation des appels API OpenAI à des fins de débogage et d'analyse. Ce flag remplace le paramètre `enableOpenAILogging` dans `settings.json`. + - Active la journalisation des appels à l'API OpenAI à des fins de débogage et d'analyse. Cet argument 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. - 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 codage ou toute information contextuelle pertinente à l'IA, rendant ainsi ses réponses plus adaptées et précises selon 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_ de la 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 codage ou toute information contextuelle pertinente à l'IA, rendant ainsi ses réponses plus adaptées et précises par rapport à vos besoins. La CLI inclut des éléments d'interface utilisateur, comme un indicateur dans le pied de page indiquant le nombre de fichiers de contexte chargés, afin de vous tenir informé du contexte actif. - **Objectif :** Ces fichiers Markdown contiennent des instructions, des directives ou du contexte que vous souhaitez que le modèle Gemini prenne en compte durant vos interactions. Le système est conçu pour gérer ce contexte d'instructions de manière hiérarchique. @@ -433,7 +443,7 @@ Voici un exemple conceptuel du contenu d'un fichier contexte à la racine d'un p ```markdown -# Project: My Awesome TypeScript Library +# Projet : My Awesome TypeScript Library ## Instructions générales : @@ -445,15 +455,16 @@ Voici un exemple conceptuel du contenu d'un fichier contexte à la racine d'un p ## 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 noms d'interfaces doivent être préfixés avec `I` (ex. : `IUserService`). +- Les membres privés des classes doivent être préfixés avec un underscore (`_`). - Utilisez toujours l'égalité stricte (`===` et `!==`). ## 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'erreurs robuste et une journalisation (logging). +- Lors de l'ajout de nouvelles fonctions d'appel API, assurez-vous qu'elles incluent une gestion d'erreurs robuste et une journalisation. - Utilisez l'utilitaire `fetchWithRetry` existant pour toutes les requêtes GET. +``` ## Concernant les dépendances : @@ -461,26 +472,26 @@ Voici un exemple conceptuel du contenu d'un fichier contexte à la racine d'un p - 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, ainsi que 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. - -- **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. - - 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 recherche également le fichier de contexte configuré dans les sous-répertoires _situés sous_ le répertoire courant (en respectant les motifs d'exclusion courants comme `node_modules`, `.git`, etc.). 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`. - - Portée : Permet d'avoir 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 ainsi un indicateur visuel 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). +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 certains fichiers ou composants particuliers. Plus vos fichiers de contexte sont pertinents et précis, mieux l'IA pourra vous assister. L'utilisation de fichiers de contexte spécifiques au projet est fortement encouragée afin d'établir clairement les conventions et le contexte. + +- **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 via 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'à atteindre soit la racine du projet (identifiée par un dossier `.git`), soit 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 _situés sous_ le répertoire courant (en respectant les motifs d'exclusion usuels tels que `node_modules`, `.git`, etc.) à la recherche du fichier de contexte configuré. Par défaut, cette recherche est limitée à 200 répertoires, mais ce seuil peut être ajusté via le champ `memoryDiscoveryMaxDirs` dans votre fichier `settings.json`. + - Portée : Permet d'appliquer des instructions très spécifiques relatives à un composant, module ou section particulière de votre projet. +- **Concaténation & Indication dans l'interface utilisateur :** 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 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). - **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 sur la commande `/memory` et ses sous-commandes (`show` et `refresh`). + - Utilisez `/memory show` pour afficher le contexte instructionnel combiné actuellement chargé, vous permettant ainsi de vérifier la hiérarchie et le contenu utilisé par l'IA. + - 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. +En comprenant et en exploitant 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 @@ -490,7 +501,7 @@ Le sandboxing est désactivé par défaut, mais vous pouvez l'activer de plusieu - En utilisant le flag `--sandbox` ou `-s`. - En définissant la variable d'environnement `GEMINI_SANDBOX`. -- Le sandbox est activé par défaut en mode `--yolo`. +- Le sandbox est activé par défaut lorsque vous utilisez `--yolo` ou `--approval-mode=yolo`. Par défaut, il utilise une image Docker pré-construite `qwen-code-sandbox`. @@ -509,7 +520,7 @@ FROM qwen-code-sandbox # COPY ./my-config /app/my-config ``` -Quand `.qwen/sandbox.Dockerfile` existe, tu peux utiliser la variable d'environnement `BUILD_SANDBOX` lors de l'exécution de Qwen Code pour automatiquement construire l'image sandbox personnalisée : +Quand `.qwen/sandbox.Dockerfile` existe, tu peux utiliser la variable d'environnement `BUILD_SANDBOX` lors de l'exécution de Qwen Code pour automatiquement construire l'image du sandbox personnalisé : ```bash BUILD_SANDBOX=1 qwen -s @@ -527,13 +538,13 @@ 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, votre adresse e-mail ou vos 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. **Comment désactiver la collecte :** -Vous pouvez désactiver la collecte des statistiques d'utilisation à tout moment en définissant la propriété `usageStatisticsEnabled` à `false` dans votre fichier `settings.json` : +Vous pouvez désactiver la collecte des statistiques d'utilisation à tout moment en définissant la propriété `usageStatisticsEnabled` sur `false` dans votre fichier `settings.json` : ```json { @@ -541,4 +552,4 @@ Vous pouvez désactiver la collecte des statistiques d'utilisation à tout momen } ``` -Remarque : Lorsque les statistiques d'utilisation sont activées, les événements sont envoyés à un endpoint de collecte RUM d'Alibaba Cloud. \ No newline at end of file +Remarque : Lorsque les statistiques d'utilisation sont activées, les événements sont envoyés à un endpoint de collecte Alibaba Cloud RUM. \ No newline at end of file diff --git a/website/content/fr/deployment.md b/website/content/fr/deployment.md index f7c4d4c3..4dcfd5d8 100644 --- a/website/content/fr/deployment.md +++ b/website/content/fr/deployment.md @@ -1,10 +1,10 @@ # Exécution et déploiement de Qwen Code -Ce document explique comment exécuter Qwen Code et décrit l'architecture de déploiement utilisée par Qwen Code. +Ce document décrit comment exécuter Qwen Code et explique l'architecture de déploiement utilisée par Qwen Code. ## 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. --- @@ -38,14 +38,14 @@ C'est la méthode recommandée pour que les utilisateurs finaux installent Qwen 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. - **Directement depuis le Registry :** - Vous pouvez exécuter l'image du sandbox publiée directement. C'est pratique pour les environnements où vous n'avez que Docker et souhaitez exécuter le CLI. + 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. ```bash # Exécuter l'image du sandbox publiée - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.7 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.9 ``` -- **Utilisation du flag `--sandbox` :** - Si vous avez Qwen Code installé localement (via l'installation standard décrite ci-dessus), vous pouvez lui demander de s'exécuter à l'intérieur du container sandbox. +- **Avec le 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. ```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 @@ -102,7 +102,7 @@ Ces packages sont utilisés lors de l'installation standard et lors de l'exécut Deux processus de build distincts sont utilisés, selon le canal de distribution : -- **Publication NPM :** Pour publier sur le registre NPM, le code source TypeScript dans `@qwen-code/qwen-code-core` et `@qwen-code/qwen-code` est transpilé en JavaScript standard à l’aide du TypeScript Compiler (`tsc`). Le répertoire `dist/` résultant est celui qui est publié dans le package NPM. Il s’agit d’une approche standard pour les bibliothèques TypeScript. +- **Publication NPM :** Pour publier sur le registre NPM, le code source TypeScript dans `@qwen-code/qwen-code-core` et `@qwen-code/qwen-code` est transpilé en JavaScript standard à l’aide du TypeScript Compiler (`tsc`). Le répertoire `dist/` ainsi généré est celui qui est publié dans le package NPM. Il s’agit d’une approche standard pour les bibliothèques TypeScript. - **Exécution via `npx` depuis GitHub :** Lors de l’exécution de la dernière version de Qwen Code directement depuis GitHub, un processus différent est déclenché par le script `prepare` dans `package.json`. Ce script utilise `esbuild` pour regrouper l’ensemble de l’application et de ses dépendances dans un seul fichier JavaScript autonome. Ce bundle est généré à la volée sur la machine de l’utilisateur et n’est pas inclus dans le dépôt. diff --git a/website/content/fr/ide-integration.md b/website/content/fr/ide-integration.md new file mode 100644 index 00000000..adabc4c6 --- /dev/null +++ b/website/content/fr/ide-integration.md @@ -0,0 +1,141 @@ +# Intégration IDE + +Gemini CLI 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 dans l'éditeur. + +Actuellement, le seul IDE supporté est [Visual Studio Code](https://code.visualstudio.com/) ainsi que les autres éditeurs qui supportent 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. + - Tout texte sélectionné (jusqu'à une limite de 16 Ko ; les sélections plus longues seront tronquées). + +- **Diffing natif :** Lorsque Gemini 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 fluide. + +- **Commandes VS Code :** Vous pouvez accéder aux fonctionnalités du CLI Gemini directement depuis la Palette de commandes de VS Code (`Cmd+Shift+P` ou `Ctrl+Shift+P`) : + - `Gemini CLI: Run` : Démarre une nouvelle session CLI Gemini dans le terminal intégré. + - `Gemini CLI: Accept Diff` : Accepte les modifications dans l'éditeur de différences actif. + - `Gemini CLI: Close Diff Editor` : Rejette les modifications et ferme l'éditeur de différences actif. + - `Gemini CLI: View Third-Party Notices` : Affiche les mentions tierces pour l'extension. + +## Installation et Configuration + +Il existe trois façons de configurer l'intégration IDE : + +### 1. Invitation Automatique (Recommandé) + +Lorsque vous exécutez Gemini CLI dans un éditeur pris en charge, il détectera automatiquement votre environnement et vous proposera de vous connecter. Répondre "Yes" exécutera automatiquement la configuration nécessaire, qui inclut l'installation de l'extension companion et l'activation de la connexion. + +### 2. Installation Manuelle depuis le CLI + +Si vous avez précédemment ignoré l'invitation ou si vous souhaitez installer l'extension manuellement, vous pouvez exécuter la commande suivante dans Gemini CLI : + +``` +/ide install +``` + +Cette commande trouvera l'extension appropriée pour votre IDE et l'installera. + +### 3. Installation manuelle depuis un marketplace + +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=google.gemini-cli-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/google/gemini-cli-vscode-ide-companion). Suivez les instructions de votre éditeur pour installer des extensions depuis ce registry. + +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. + +## Usage + +### Activation et Désactivation + +Vous pouvez contrôler l'intégration IDE depuis le CLI : + +- Pour activer la connexion à l'IDE, exécutez : + ``` + /ide enable + ``` +- Pour désactiver la connexion, exécutez : + ``` + /ide disable + ``` + +Lorsque activée, l'IDE CLI tentera automatiquement de se connecter à l'extension compagnon de l'IDE. + +### Vérification du Statut + +Pour vérifier l'état de la connexion et voir le contexte que le CLI a reçu de l'IDE, exécutez : + +``` +/ide status +``` + +Si connecté, cette commande affichera l'IDE auquel il est connecté et une liste des fichiers récemment ouverts dont il a connaissance. + +(Note : La liste des fichiers est limitée aux 10 fichiers récemment consultés dans votre workspace et inclut uniquement les fichiers locaux sur le disque.) + +### Travailler avec les diffs + +Quand vous demandez à Gemini 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 en forme de checkmark** dans la barre de titre de l'éditeur de diff. +- Sauvegarder le fichier (par exemple avec `Cmd+S` ou `Ctrl+S`). +- Ouvrir la Command Palette et exécuter **Gemini CLI: 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. +- Ouvrir la Command Palette et exécuter **Gemini CLI: 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 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. + +## Utilisation avec le Sandboxing + +Si vous utilisez Gemini CLI 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 Gemini CLI à 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. Le CLI est configuré 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 + +Si vous rencontrez des problèmes avec l'intégration IDE, voici quelques messages d'erreur courants et les méthodes pour les résoudre. + +### 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 :** Gemini CLI n'a pas pu trouver les variables d'environnement nécessaires (`GEMINI_CLI_IDE_WORKSPACE_PATH` ou `GEMINI_CLI_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 **Gemini CLI 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. + +- **Message :** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` + - **Cause :** La connexion à 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. Gemini CLI 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 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 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. + +### 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 Gemini CLI dans l'un de ces IDE pris en charge : [Liste des IDE]` + - **Cause :** Vous exécutez Gemini CLI dans un terminal ou un environnement qui n'est pas un IDE pris en charge. + - **Solution :** Exécutez Gemini CLI 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 automatique pour votre IDE spécifique. + - **Solution :** Ouvrez le marketplace d'extensions de votre IDE, recherchez "Gemini CLI 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 994664b4..625093d8 100644 --- a/website/content/fr/index.md +++ b/website/content/fr/index.md @@ -4,35 +4,36 @@ 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 sur 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 interactif de type 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`. ## 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 leurs interactions. +- **[Aperçu de l'architecture](./architecture.md) :** Comprenez la conception de haut niveau de Qwen Code, y compris ses composants et leur interaction. - **Utilisation du CLI :** Documentation pour `packages/cli`. - - **[Introduction au CLI](./cli/index.md) :** Vue d'ensemble de l'interface en ligne de commande. + - **[Introduction au CLI](./cli/index.md) :** Aperçu de l'interface en ligne de commande. - **[Commandes](./cli/commands.md) :** Description des commandes CLI disponibles. - **[Configuration](./cli/configuration.md) :** Informations sur la configuration du CLI. - **[Checkpointing](./checkpointing.md) :** Documentation de la fonctionnalité de checkpointing. - **[Extensions](./extension.md) :** Comment étendre le CLI avec de nouvelles fonctionnalités. + - **[Intégration IDE](./ide-integration.md) :** Connectez le CLI à votre éditeur. - **[Télémétrie](./telemetry.md) :** Aperçu de la télémétrie dans le CLI. - **Détails du Core :** Documentation pour `packages/core`. - - **[Introduction au Core](./core/index.md) :** Vue d'ensemble du composant principal. + - **[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) :** Vue d'ensemble des outils disponibles. + - **[Aperçu des outils](./tools/index.md) :** Aperçu 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`. -- **[Guide de contribution et de développement](../CONTRIBUTING.md) :** Informations pour les contributeurs et développeurs, incluant l'installation, la construction, les tests et les conventions de codage. +- **[Guide de contribution et de développement](../CONTRIBUTING.md) :** Informations pour les contributeurs et développeurs, y compris 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 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/integration-tests.md b/website/content/fr/integration-tests.md index 482b2178..2192d7d6 100644 --- a/website/content/fr/integration-tests.md +++ b/website/content/fr/integration-tests.md @@ -20,7 +20,7 @@ npm run test:e2e ## Exécuter un ensemble spécifique de tests -Pour exécuter un sous-ensemble de fichiers de test, vous pouvez utiliser `npm run ....` où `` est soit `test:e2e`, soit `test:integration*` et `` est n'importe quel fichier `.test.js` dans le répertoire `integration-tests/`. Par exemple, la commande suivante exécute `list_directory.test.js` et `write_file.test.js` : +Pour exécuter un sous-ensemble de fichiers de test, vous pouvez utiliser `npm run ....` où est soit `test:e2e` soit `test:integration*` et `` est n'importe quel fichier `.test.js` dans le répertoire `integration-tests/`. Par exemple, la commande suivante exécute `list_directory.test.js` et `write_file.test.js` : ```bash npm run test:e2e list_directory write_file @@ -36,7 +36,7 @@ npm run test:e2e -- --test-name-pattern "reads a file" ### Exécuter tous les tests -Pour exécuter la suite complète des tests d'intégration, utilisez la commande suivante : +Pour exécuter l'ensemble complet des tests d'intégration, utilisez la commande suivante : ```bash npm run test:integration:all @@ -67,52 +67,45 @@ Le test runner d'intégration propose plusieurs options de diagnostic pour aider Vous pouvez conserver les fichiers temporaires créés pendant l'exécution d'un test pour inspection. Cela est utile pour déboguer les problèmes liés aux opérations sur le système de fichiers. -Pour conserver la sortie des tests, vous pouvez soit utiliser le flag `--keep-output`, soit définir la variable d'environnement `KEEP_OUTPUT` à `true`. - -```bash - -# Utilisation du flag -npm run test:integration:sandbox:none -- --keep-output - -# Utilisation de la variable d'environnement +Pour conserver la sortie des tests, définissez la variable d'environnement `KEEP_OUTPUT` à `true`. ```bash KEEP_OUTPUT=true npm run test:integration:sandbox:none ``` -Lorsque la sortie est conservée, le test runner affiche le chemin vers le répertoire unique pour l'exécution des tests. +Lorsque la sortie est conservée, le test runner affichera le chemin vers le répertoire unique pour l'exécution du test. ### Sortie verbeuse -Pour un débogage plus détaillé, le flag `--verbose` permet de diffuser en temps réel la sortie de la commande `qwen` vers la console. +Pour un débogage plus détaillé, définis la variable d'environnement `VERBOSE` à `true`. ```bash -npm run test:integration:sandbox:none -- --verbose +VERBOSE=true npm run test:integration:sandbox:none ``` -Lorsque vous utilisez à la fois `--verbose` et `--keep-output` dans la même commande, la sortie est diffusée vers la console et également enregistrée dans un fichier de log à l'intérieur du répertoire temporaire des tests. +Lorsque tu utilises `VERBOSE=true` et `KEEP_OUTPUT=true` dans la même commande, la sortie est diffusée dans la console et également enregistrée dans un fichier de log situé dans le répertoire temporaire du test. La sortie verbeuse est formatée pour identifier clairement la source des logs : ``` ---- TEST: : --- +--- TEST: : --- ... output from the qwen command ... ---- END TEST: : --- +--- END TEST: : --- ``` ## Linting et mise en forme -Pour garantir la qualité et la cohérence du code, les fichiers de tests d'intégration sont analysés par le linter dans le cadre du processus de build principal. Vous pouvez également exécuter manuellement le linter et l'auto-correcteur. +Pour garantir la qualité et la cohérence du code, les fichiers de test d'intégration sont analysés par le linter dans le cadre du processus de build principal. Tu peux également exécuter manuellement le linter et le correcteur automatique. ### Exécuter le linter -Pour vérifier les erreurs de linting, exécutez la commande suivante : +Pour vérifier les erreurs de linting, exécute la commande suivante : ```bash npm run lint ``` -Vous pouvez inclure le flag `:fix` dans la commande pour corriger automatiquement les erreurs de linting qui peuvent l'être : +Tu peux ajouter le flag `:fix` à la commande pour corriger automatiquement les erreurs de linting qui peuvent l'être : ```bash npm run lint:fix @@ -120,7 +113,7 @@ npm run lint:fix ## Structure des répertoires -Les tests d'intégration créent un répertoire unique pour chaque exécution de test à l'intérieur du répertoire `.integration-tests`. Dans ce répertoire, un sous-répertoire est créé pour chaque fichier de test, et à l'intérieur de celui-ci, un sous-répertoire est créé pour chaque cas de test individuel. +Les tests d'intégration créent un répertoire unique pour chaque exécution de test à l'intérieur du répertoire `.integration-tests`. Dans ce répertoire, un sous-répertoire est créé pour chaque fichier de test, et dans celui-ci, un sous-répertoire est créé pour chaque cas de test individuel. Cette structure facilite la localisation des artefacts pour une exécution de test, un fichier ou un cas spécifique. @@ -135,7 +128,7 @@ Cette structure facilite la localisation des artefacts pour une exécution de te ## Intégration continue -Pour garantir que les tests d'intégration soient toujours exécutés, un workflow GitHub Actions est défini dans `.github/workflows/e2e.yml`. Ce workflow exécute automatiquement les tests d'intégration pour les pull requests contre la branche `main`, ou lorsqu'une pull request est ajoutée à une file d'attente de fusion. +Pour garantir que les tests d'intégration soient toujours exécutés, un workflow GitHub Actions est défini dans `.github/workflows/e2e.yml`. Ce workflow exécute automatiquement les tests d'intégration pour les pull requests contre la branche `main`, ou lorsqu'une pull request est ajoutée à une merge queue. Le workflow exécute les tests dans différents environnements de sandboxing pour s'assurer que Qwen Code est testé dans chacun d'eux : diff --git a/website/content/fr/npm.md b/website/content/fr/npm.md index 9ed81313..b8a2be31 100644 --- a/website/content/fr/npm.md +++ b/website/content/fr/npm.md @@ -4,13 +4,13 @@ Ce monorepo contient deux packages principaux : `@qwen-code/qwen-code` et `@qwen ## `@qwen-code/qwen-code` -Il s'agit du package principal pour Qwen Code. Il est responsable de l'interface utilisateur, de l'analyse des commandes, et de toutes les autres fonctionnalités destinées à l'utilisateur. +Ceci est le package principal pour Qwen Code. Il est responsable de l'interface utilisateur, de l'analyse des commandes, et de toutes les autres fonctionnalités orientées utilisateur. -Lorsque ce package est publié, il est regroupé dans un seul fichier exécutable. Ce bundle inclut toutes les dépendances du package, y compris `@qwen-code/qwen-code-core`. Cela signifie que, qu'un utilisateur installe le package avec `npm install -g @qwen-code/qwen-code` ou l'exécute directement avec `npx @qwen-code/qwen-code`, il utilise ce seul exécutable autonome. +Lorsque ce package est publié, il est regroupé dans un seul fichier exécutable. Ce bundle inclut toutes les dépendances du package, y compris `@qwen-code/qwen-code-core`. Cela signifie que qu'un utilisateur installe le package avec `npm install -g @qwen-code/qwen-code` ou l'exécute directement avec `npx @qwen-code/qwen-code`, il utilise ce seul exécutable autonome. ## `@qwen-code/qwen-code-core` -Ce package contient la logique principale pour le CLI. Il est responsable des requêtes API vers les fournisseurs configurés, de la gestion de l'authentification, et du cache local. +Ce package contient la logique principale pour le CLI. Il est responsable des requêtes API vers les providers configurés, de la gestion de l'authentification, et du cache local. Ce package n'est pas bundlé. Lorsqu'il est publié, il l'est en tant que package Node.js standard avec ses propres dépendances. Cela permet de l'utiliser comme package autonome dans d'autres projets, si nécessaire. Tout le code js transpilé dans le dossier `dist` est inclus dans le package. @@ -22,13 +22,13 @@ Ce projet suit un processus de release structuré afin de garantir que tous les Les releases sont gérées via le workflow GitHub Actions [release.yml](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml). Pour effectuer une release manuelle d'un patch ou d'un hotfix : -1. Allez dans l'onglet **Actions** du repository. +1. Accédez à l'onglet **Actions** du repository. 2. Sélectionnez le workflow **Release** dans la liste. 3. Cliquez sur le bouton déroulant **Run workflow**. 4. Remplissez les champs requis : - **Version** : La version exacte à publier (ex : `v0.2.1`). - **Ref** : La branche ou le SHA du commit à partir duquel publier (par défaut `main`). - - **Dry Run** : Laissez `true` pour tester le workflow sans publier, ou mettez `false` pour effectuer une release réelle. + - **Dry Run** : Laissez `true` pour tester le workflow sans publier, ou définissez sur `false` pour effectuer une release réelle. 5. Cliquez sur **Run workflow**. ## Releases Nightly @@ -58,7 +58,7 @@ Pour installer la dernière nightly build, utilisez le tag `@nightly` : npm install -g @qwen-code/qwen-code@nightly ``` -Nous exécutons également un Google Cloud Build appelé [release-docker.yml](../.gcp/release-docker.yaml). Celui-ci publie l'image Docker sandbox correspondant à votre release. Une fois les permissions du compte de service résolues, cela sera déplacé vers GitHub et combiné avec le fichier de release principal. +Nous exécutons également un Google Cloud Build appelé [release-docker.yml](../.gcp/release-docker.yml). Celui-ci publie l'image Docker sandbox correspondant à votre release. Une fois les permissions du compte de service résolues, cela sera déplacé vers GitHub et combiné avec le fichier de release principal. ### Après la release @@ -81,33 +81,38 @@ Après avoir poussé une nouvelle release, un smoke testing doit être effectué Le pattern décrit ci-dessus pour créer des patchs ou des hotfix releases à partir de commits actuels ou anciens laisse le repository dans l'état suivant : -1. Le Tag (`vX.Y.Z-patch.1`) : Ce tag pointe correctement vers le commit original sur main qui contient le code stable que vous souhaitez release. C'est crucial. Toute personne qui checkout ce tag obtient le code exact qui a été publié. -2. La Branche (`release-vX.Y.Z-patch.1`) : Cette branche contient un nouveau commit en plus du commit taggé. Ce nouveau commit ne contient que le changement de numéro de version dans package.json (et autres fichiers liés comme package-lock.json). +1. Le Tag (`vX.Y.Z-patch.1`) : Ce tag pointe correctement vers le commit original sur main + qui contient le code stable que vous souhaitez release. C'est crucial. Toute personne qui + checkout ce tag obtient le code exact qui a été publié. +2. La Branche (`release-vX.Y.Z-patch.1`) : Cette branche contient un nouveau commit en plus du + commit taggé. Ce nouveau commit contient uniquement le changement de numéro de version dans package.json + (et autres fichiers liés comme package-lock.json). -Cette séparation est bénéfique. Elle garde l'historique de votre branche main propre, sans les modifications de version spécifiques aux releases jusqu'au moment où vous décidez de les merger. +Cette séparation est bénéfique. Elle garde l'historique de votre branche main propre, sans les bumps +de version spécifiques aux releases jusqu'au moment où vous décidez de les merger. -C'est ici que se trouve la décision critique, et elle dépend entièrement de la nature du release. +C'est ici que réside la décision critique, et elle dépend entièrement de la nature du release. ### Merge Back pour les Correctifs Stables et les Hotfixes Vous devez presque toujours merger la branche `release-` dans `main` pour toute release de correctif stable ou hotfix. -- Pourquoi ? La raison principale est de mettre à jour la version dans le package.json de la branche main. Si vous releasez la v1.2.1 depuis un commit plus ancien mais que vous ne mergez jamais la montée de version, le package.json de votre branche main indiquera toujours "version": "1.2.0". Le prochain développeur qui commencera le travail sur la prochaine feature release (v1.3.0) partira d'une base de code avec un numéro de version incorrect et obsolète. Cela cause de la confusion et nécessite une montée de version manuelle plus tard. -- Le Processus : Après la création de la branche release-v1.2.1 et la publication réussie du package, vous devez ouvrir une pull request pour merger release-v1.2.1 dans main. Cette PR ne contiendra qu'un seul commit : "chore: bump version to v1.2.1". C'est une intégration propre et simple qui maintient votre branche main synchronisée avec la dernière version release. +- Pourquoi ? La raison principale est de mettre à jour la version dans le package.json de la branche main. Si vous releasez la v1.2.1 depuis un commit plus ancien mais que vous ne mergez jamais la montée de version, le package.json de votre branche main indiquera toujours "version": "1.2.0". Le prochain développeur qui commencera le travail sur la prochaine feature release (v1.3.0) branchera depuis une base de code contenant un numéro de version incorrect et obsolète. Cela cause de la confusion et nécessite une montée de version manuelle plus tard. +- Le Processus : Après que la branche release-v1.2.1 soit créée et que le package soit publié avec succès, vous devez ouvrir une pull request pour merger release-v1.2.1 dans main. Cette PR ne contiendra qu'un seul commit : "chore: bump version to v1.2.1". C'est une intégration propre et simple qui maintient votre branche main synchronisée avec la dernière version release. ### Ne pas fusionner les pré-releases (RC, Beta, Dev) -En général, vous ne fusionnez pas les branches de release pour les pré-releases dans `main`. +En général, vous ne fusionnez pas les branches de pré-release dans `main`. -- Pourquoi ? Les versions préliminaires (ex. : v1.3.0-rc.1, v1.3.0-rc.2) ne sont, par définition, pas stables et sont temporaires. Vous ne souhaitez pas polluer l'historique de votre branche principale avec une série de mises à jour de version pour les release candidates. Le fichier package.json dans main doit refléter la dernière version stable, et non une RC. -- Le processus : La branche release-v1.3.0-rc.1 est créée, la commande `npm publish --tag rc` est exécutée, puis... la branche a rempli son rôle. Vous pouvez simplement la supprimer. Le code de la RC est déjà sur main (ou sur une branche feature), donc aucun code fonctionnel n'est perdu. La branche de release n’était qu’un véhicule temporaire pour le numéro de version. +- Pourquoi ? Les versions préliminaires (ex. : v1.3.0-rc.1, v1.3.0-rc.2) ne sont, par définition, ni stables ni permanentes. Vous ne souhaitez pas polluer l'historique de votre branche principale avec une série de mises à jour de version pour les release candidates. Le fichier package.json sur main doit refléter la dernière version stable publiée, et non une RC. +- Le processus : La branche release-v1.3.0-rc.1 est créée, la commande `npm publish --tag rc` est exécutée, puis... la branche a rempli son rôle. Vous pouvez simplement la supprimer. Le code correspondant à la RC existe déjà sur main (ou sur une branche de fonctionnalité), donc aucun code fonctionnel n’est perdu. La branche de release n’était qu’un moyen temporaire de gérer le numéro de version. ## Tests et validation en local : Modifications du processus de packaging et de publication Si vous devez tester le processus de release sans publier réellement sur NPM ou créer une release publique sur GitHub, vous pouvez déclencher le workflow manuellement depuis l'interface GitHub. 1. Allez dans l'onglet [Actions](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) du repository. -2. Cliquez sur le dropdown "Run workflow". +2. Cliquez sur le menu déroulant "Run workflow". 3. Laissez l'option `dry_run` cochée (`true`). 4. Cliquez sur le bouton "Run workflow". @@ -115,7 +120,7 @@ Cela exécutera l'ensemble du processus de release mais ignorera les étapes `np Il est crucial de tester localement toutes les modifications apportées au processus de packaging et de publication avant de les committer. Cela garantit que les packages seront publiés correctement et qu'ils fonctionneront comme attendu lorsqu'ils seront installés par un utilisateur. -Pour valider vos modifications, vous pouvez effectuer un dry run du processus de publication. Cela simulera le processus de publication sans envoyer effectivement les packages sur le registre npm. +Pour valider vos changements, vous pouvez effectuer un dry run du processus de publication. Cela simulera le processus de publication sans envoyer effectivement les packages sur le registre npm. ```bash npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run @@ -130,30 +135,30 @@ Cette commande va : Vous pouvez ensuite inspecter les tarballs générés pour vérifier qu'ils contiennent les bons fichiers et que les fichiers `package.json` ont été mis à jour correctement. Les tarballs seront créés à la racine du répertoire de chaque package (par exemple, `packages/cli/google-gemini-cli-0.1.6.tgz`). -En effectuant un dry run, vous pouvez être certain que vos modifications du processus de packaging sont correctes et que les packages seront publiés avec succès. +En effectuant un dry run, vous pouvez être certain que vos modifications au processus de packaging sont correctes et que les packages seront publiés avec succès. ## Plongée dans le processus de release -L'objectif principal du processus de release est de prendre le code source du répertoire `packages/`, de le builder, et d'assembler un package propre et autonome dans un répertoire temporaire `bundle` à la racine du projet. C’est ce répertoire `bundle` qui est effectivement publié sur NPM. +L'objectif principal du processus de release est de prendre le code source situé dans le répertoire `packages/`, de le builder, puis d’assembler un package autonome et propre dans un répertoire temporaire `bundle` à la racine du projet. C’est ce répertoire `bundle` qui est effectivement publié sur NPM. Voici les étapes clés : ### Étape 1 : Vérifications pré-release et gestion des versions -- **Ce qui se passe** : Avant de déplacer des fichiers, le processus vérifie que le projet est dans un état sain. Cela inclut l’exécution des tests, du linting et du type-checking (`npm run preflight`). Le numéro de version dans les fichiers `package.json` à la racine et dans `packages/cli/package.json` est mis à jour vers la nouvelle version de release. -- **Pourquoi** : Cela garantit que seul du code de qualité, fonctionnel, est publié. La gestion des versions est la première étape pour signaler une nouvelle release. +- **Ce qui se passe** : Avant de déplacer des fichiers, le processus vérifie que le projet est dans un état stable. Cela inclut l’exécution des tests, du linting et du type-checking (`npm run preflight`). Le numéro de version dans les fichiers `package.json` à la racine et dans `packages/cli/package.json` est mis à jour vers la nouvelle version de release. +- **Pourquoi** : Cela garantit que seul du code fonctionnel et de qualité est publié. La gestion des versions est la première étape pour signaler une nouvelle release. ### Étape 2 : Compilation du code source -- **Ce qui se passe** : Le code TypeScript dans `packages/core/src` et `packages/cli/src` est compilé en JavaScript. +- **Ce qui se passe** : Le code TypeScript présent dans `packages/core/src` et `packages/cli/src` est compilé en JavaScript. - **Déplacement des fichiers** : - `packages/core/src/**/*.ts` → compilé vers → `packages/core/dist/` - `packages/cli/src/**/*.ts` → compilé vers → `packages/cli/dist/` -- **Pourquoi** : Le code TypeScript écrit pendant le développement doit être converti en JavaScript pur exécutable par Node.js. Le package `core` est compilé en premier car le package `cli` en dépend. +- **Pourquoi** : Le code TypeScript écrit pendant le développement doit être converti en JavaScript pur pour être exécuté par Node.js. Le package `core` est compilé en premier car le package `cli` en dépend. ### Étape 3 : Assemblage du package final publié -C’est l’étape la plus critique, où les fichiers sont déplacés et transformés dans leur état final pour la publication. Un dossier temporaire `bundle` est créé à la racine du projet pour contenir le package final. +C’est l’étape la plus critique, où les fichiers sont déplacés et transformés pour leur forme finale de publication. Un dossier temporaire `bundle` est créé à la racine du projet pour contenir le package final. #### 1. Transformation du `package.json` @@ -161,15 +166,14 @@ C’est l’étape la plus critique, où les fichiers sont déplacés et transfo - **Déplacement des fichiers** : `packages/cli/package.json` → (transformation en mémoire) → `bundle/package.json` - **Pourquoi** : Le `package.json` final doit être différent de celui utilisé en développement. Les changements clés incluent : - Suppression des `devDependencies`. - - Suppression des dépendances spécifiques à l’espace de travail : `{ "@gemini-cli/core": "workspace:*" }`, et inclusion directe du code `core` dans le fichier JavaScript final. + - Suppression des dépendances spécifiques à l’espace de travail : `{ "@gemini-cli/core": "workspace:*" }`, en veillant à ce que le code du core soit intégré directement dans le fichier JavaScript final. - S’assurer que les champs `bin`, `main` et `files` pointent vers les bons chemins dans la structure finale du package. #### 2. Création du bundle JavaScript - **Ce qui se passe** : Le JavaScript compilé depuis `packages/core/dist` et `packages/cli/dist` est bundlé en un seul fichier JavaScript exécutable. -- **Déplacement des fichiers** : - `packages/cli/dist/index.js` + `packages/core/dist/index.js` → (bundlé par esbuild) → `bundle/gemini.js` (ou nom similaire). -- **Pourquoi** : Cela crée un fichier unique et optimisé contenant tout le code nécessaire. Cela simplifie le package en supprimant la nécessité d’avoir le package `core` comme dépendance séparée sur NPM, son code étant désormais inclus directement. +- **Déplacement des fichiers** : `packages/cli/dist/index.js` + `packages/core/dist/index.js` → (bundlé par esbuild) → `bundle/gemini.js` (ou nom similaire). +- **Pourquoi** : Cela crée un fichier unique et optimisé contenant tout le code nécessaire à l’application. Cela simplifie le package en supprimant la nécessité que le package `core` soit une dépendance séparée sur NPM, son code étant désormais inclus directement. #### 3. Copie des fichiers statiques et de support @@ -185,7 +189,7 @@ C’est l’étape la plus critique, où les fichiers sont déplacés et transfo ### Étape 4 : Publication sur NPM - **Ce qui se passe** : La commande `npm publish` est exécutée depuis le répertoire `bundle` à la racine. -- **Pourquoi** : En exécutant `npm publish` depuis le répertoire `bundle`, seuls les fichiers soigneusement assemblés à l’étape 3 sont envoyés au registre NPM. Cela évite de publier accidentellement du code source, des fichiers de test ou des configurations de développement, garantissant ainsi un package propre et minimal pour les utilisateurs. +- **Pourquoi** : En exécutant `npm publish` depuis le répertoire `bundle`, seuls les fichiers soigneusement assemblés lors de l’étape 3 sont envoyés sur le registre NPM. Cela évite la publication accidentelle de code source, fichiers de test ou configurations de développement, garantissant ainsi un package propre et minimal pour les utilisateurs. ### Résumé du flux des fichiers diff --git a/website/content/fr/tools/file-system.md b/website/content/fr/tools/file-system.md index fb3508bc..daba0b9a 100644 --- a/website/content/fr/tools/file-system.md +++ b/website/content/fr/tools/file-system.md @@ -2,11 +2,11 @@ Qwen Code fournit une suite complète d'outils pour interagir avec le système de fichiers local. Ces outils permettent au modèle de lire, écrire, lister, rechercher et modifier des fichiers et des répertoires, le tout sous votre contrôle et généralement avec confirmation pour les opérations sensibles. -**Note :** Tous les outils de système de fichiers opèrent dans un `rootDirectory` (généralement le répertoire de travail courant où vous avez lancé le CLI) pour des raisons de sécurité. Les chemins que vous fournissez à ces outils sont généralement attendus en absolu ou sont résolus par rapport à ce répertoire racine. +**Note :** Tous les outils de système de fichiers fonctionnent dans un `rootDirectory` (généralement le répertoire de travail courant où vous avez lancé le CLI) pour des raisons de sécurité. Les chemins que vous fournissez à ces outils sont généralement attendus en absolu ou sont résolus par rapport à ce répertoire racine. ## 1. `list_directory` (ReadFolder) -`list_directory` liste les noms des fichiers et sous-dossiers directement présents dans un chemin de répertoire spécifié. Il peut éventuellement ignorer les entrées correspondant à des motifs glob fournis. +`list_directory` liste les noms des fichiers et sous-répertoires directement présents dans un chemin de répertoire spécifié. Il peut éventuellement ignorer les entrées correspondant à des motifs glob fournis. - **Nom de l'outil :** `list_directory` - **Nom d'affichage :** ReadFolder @@ -30,12 +30,12 @@ Qwen Code fournit une suite complète d'outils pour interagir avec le système d - **Nom d’affichage :** ReadFile - **Fichier :** `read-file.ts` - **Paramètres :** - - `path` (string, requis) : Le chemin absolu vers le fichier à lire. - - `offset` (number, optionnel) : Pour les fichiers texte, le numéro de ligne de départ (0-based). Nécessite que `limit` soit défini. - - `limit` (number, optionnel) : Pour les fichiers texte, le nombre maximum de lignes à lire. S’il est omis, lit un maximum par défaut (par exemple, 2000 lignes) ou tout le fichier si possible. + - `path` (string, requis) : Le chemin absolu du fichier à lire. + - `offset` (number, optionnel) : Pour les fichiers texte, le numéro de ligne de départ (commençant à 0). Nécessite que `limit` soit défini. + - `limit` (number, optionnel) : Pour les fichiers texte, le nombre maximum de lignes à lire. S’il est omis, lit un maximum par défaut (par exemple, 2000 lignes) ou le fichier entier si possible. - **Comportement :** - - Pour les fichiers texte : Retourne le contenu. Si `offset` et `limit` sont utilisés, retourne uniquement cette portion de lignes. Indique si le contenu a été tronqué en raison des limites de lignes ou de longueur de ligne. - - Pour les fichiers image et PDF : Retourne le contenu du fichier sous forme d’une structure de données encodée en base64 adaptée à la consommation par le modèle. + - Pour les fichiers texte : Retourne le contenu. Si `offset` et `limit` sont utilisés, retourne uniquement cette portion de lignes. Indique si le contenu a été tronqué en raison de limites de lignes ou de longueur de ligne. + - Pour les fichiers image et PDF : Retourne le contenu du fichier sous forme d’une structure de données encodée en base64, adaptée à la consommation par un modèle. - Pour les autres fichiers binaires : Tente de les identifier et les ignore, en retournant un message indiquant qu’il s’agit d’un fichier binaire générique. - **Sortie :** (`llmContent`) : - Pour les fichiers texte : Le contenu du fichier, éventuellement précédé d’un message de troncature (par exemple, `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`). @@ -56,7 +56,7 @@ Qwen Code fournit une suite complète d'outils pour interagir avec le système d - **Comportement :** - Écrit le `content` fourni dans le `file_path`. - Crée les répertoires parents s'ils n'existent pas. -- **Sortie (`llmContent`) :** Un message de succès, par exemple : `Successfully overwrote file: /path/to/your/file.txt` ou `Successfully created and wrote to new file: /path/to/new/file.txt`. +- **Sortie (`llmContent`) :** Un message de succès, par exemple, `Successfully overwrote file: /path/to/your/file.txt` ou `Successfully created and wrote to new file: /path/to/new/file.txt`. - **Confirmation :** Oui. Affiche un diff des changements et demande l'approbation de l'utilisateur avant d'écrire. ## 4. `glob` (FindFiles) @@ -69,30 +69,33 @@ Qwen Code fournit une suite complète d'outils pour interagir avec le système d - **Paramètres :** - `pattern` (string, requis) : Le pattern glob à utiliser pour la recherche (ex : `"*.py"`, `"src/**/*.js"`). - `path` (string, optionnel) : Le chemin absolu du répertoire dans lequel effectuer la recherche. S’il est omis, la recherche se fait à partir du répertoire racine de l’outil. - - `case_sensitive` (boolean, optionnel) : Indique si la recherche doit respecter la casse. Par défaut, `false`. - - `respect_git_ignore` (boolean, optionnel) : Indique si les patterns du `.gitignore` doivent être respectés. Par défaut, `true`. + - `case_sensitive` (boolean, optionnel) : Indique si la recherche doit être sensible à la casse. Valeur par défaut : `false`. + - `respect_git_ignore` (boolean, optionnel) : Indique si les patterns définis dans `.gitignore` doivent être respectés. Valeur par défaut : `true`. - **Comportement :** - Recherche des fichiers correspondant au pattern glob dans le répertoire spécifié. - Retourne une liste de chemins absolus, triés par ordre de modification décroissant (les plus récents en premier). - Ignore par défaut les répertoires courants inutiles comme `node_modules` et `.git`. -- **Sortie (`llmContent`) :** Un message comme : `Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...` +- **Sortie (`llmContent`) :** Un message du type : `Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...` - **Confirmation :** Non. ## 5. `search_file_content` (SearchText) -`search_file_content` recherche un pattern d'expression régulière (regex) dans le contenu des fichiers d'un répertoire spécifié. Il peut filtrer les fichiers selon un pattern glob. Retourne les lignes contenant des correspondances, avec leurs chemins de fichier et numéros de ligne. +`search_file_content` recherche un motif d'expression régulière (regex) dans le contenu des fichiers d'un répertoire spécifié. Il peut filtrer les fichiers à l'aide d'un motif glob. Retourne les lignes contenant des correspondances, ainsi que leurs chemins de fichier et numéros de ligne. - **Nom de l'outil :** `search_file_content` - **Nom d'affichage :** SearchText - **Fichier :** `grep.ts` - **Paramètres :** - - `pattern` (string, requis) : L'expression régulière à rechercher (ex. : `"function\s+myFunction"`). + - `pattern` (string, requis) : L'expression régulière (regex) à rechercher (ex. : `"function\s+myFunction"`). - `path` (string, optionnel) : Le chemin absolu du répertoire dans lequel effectuer la recherche. Par défaut, il s'agit du répertoire courant. - - `include` (string, optionnel) : Un pattern glob pour filtrer les fichiers à explorer (ex. : `"*.js"`, `"src/**/*.{ts,tsx}"`). Si omis, la recherche s'applique à la plupart des fichiers (en respectant les exclusions classiques). + - `include` (string, optionnel) : Un motif glob pour filtrer les fichiers à explorer (ex. : `"*.js"`, `"src/**/*.{ts,tsx}"`). Si omis, la recherche s'applique à la plupart des fichiers (en respectant les ignorés classiques). + - `maxResults` (number, optionnel) : Nombre maximum de correspondances à retourner afin d'éviter un dépassement de contexte (par défaut : 20, max : 100). Utilisez une valeur plus faible pour les recherches larges, et plus élevée pour les recherches précises. - **Comportement :** - Utilise `git grep` si disponible dans un dépôt Git pour des raisons de performance ; sinon, utilise `grep` système ou une implémentation JavaScript. - Retourne une liste des lignes correspondantes, chacune préfixée par son chemin de fichier (relatif au répertoire de recherche) et son numéro de ligne. + - Limite les résultats à 20 correspondances par défaut afin d'éviter un dépassement de contexte. En cas de troncature, un avertissement clair est affiché avec des conseils pour affiner la recherche. - **Sortie (`llmContent`) :** Une chaîne formatée des correspondances, par exemple : + ``` Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"): --- @@ -103,41 +106,68 @@ Qwen Code fournit une suite complète d'outils pour interagir avec le système d File: src/index.ts L5: import { myFunction } from './utils'; --- + + WARNING: Results truncated to prevent context overflow. To see more results: + - Use a more specific pattern to reduce matches + - Add file filters with the 'include' parameter (e.g., "*.js", "src/**") + - Specify a narrower 'path' to search in a subdirectory + - Increase 'maxResults' parameter if you need more matches (current: 20) ``` + - **Confirmation :** Non. -## 6. `replace` (Edit) +### Exemples `search_file_content` + +Rechercher un motif avec limitation des résultats par défaut : + +``` +search_file_content(pattern="function\s+myFunction", path="src") +``` + +Rechercher un motif avec limitation personnalisée des résultats : + +``` +search_file_content(pattern="function", path="src", maxResults=50) +``` + +Rechercher un motif avec filtrage des fichiers et limitation personnalisée des résultats : + +``` +search_file_content(pattern="function", include="*.js", maxResults=10) +``` + +## 6. `replace` (Modifier) -`replace` remplace du texte dans un fichier. Par défaut, il remplace une seule occurrence, mais peut remplacer plusieurs occurrences lorsque `expected_replacements` est spécifié. Cet outil est conçu pour apporter des modifications précises et ciblées, et nécessite un contexte important autour de `old_string` pour s'assurer qu'il modifie le bon endroit. +L’outil `replace` remplace du texte dans un fichier. Par défaut, il ne remplace qu’une seule occurrence, mais peut en remplacer plusieurs si `expected_replacements` est spécifié. Cet outil est conçu pour effectuer des modifications précises et ciblées, et nécessite un contexte important autour de `old_string` pour s’assurer qu’il modifie le bon endroit. -- **Nom de l'outil :** `replace` -- **Nom d'affichage :** Edit +- **Nom de l’outil :** `replace` +- **Nom d’affichage :** Modifier - **Fichier :** `edit.ts` - **Paramètres :** - - `file_path` (string, requis) : Le chemin absolu vers le fichier à modifier. - - `old_string` (string, requis) : Le texte littéral exact à remplacer. + - `file_path` (string, requis) : Le chemin absolu du fichier à modifier. + - `old_string` (string, requis) : Le texte exact à remplacer. - **CRITIQUE :** Cette chaîne doit identifier de manière unique l'instance à modifier. Elle doit inclure au moins 3 lignes de contexte _avant_ et _après_ le texte cible, en respectant précisément les espaces et l'indentation. Si `old_string` est vide, l'outil tente de créer un nouveau fichier à `file_path` avec `new_string` comme contenu. + **IMPORTANT :** Cette chaîne doit identifier de manière unique l’instance à modifier. Elle doit inclure au moins 3 lignes de contexte _avant_ et _après_ le texte cible, en respectant précisément les espaces et l’indentation. Si `old_string` est vide, l’outil tente de créer un nouveau fichier à `file_path` avec `new_string` comme contenu. - - `new_string` (string, requis) : Le texte littéral exact qui remplacera `old_string`. - - `expected_replacements` (number, optionnel) : Le nombre d'occurrences à remplacer. La valeur par défaut est `1`. + - `new_string` (string, requis) : Le texte exact qui remplacera `old_string`. + - `expected_replacements` (number, optionnel) : Le nombre d’occurrences à remplacer. Par défaut : `1`. - **Comportement :** - - Si `old_string` est vide et que `file_path` n'existe pas, crée un nouveau fichier avec `new_string` comme contenu. - - Si `old_string` est fourni, il lit `file_path` et tente de trouver exactement une occurrence de `old_string`. - - Si une occurrence est trouvée, il la remplace par `new_string`. - - **Fiabilité améliorée (Correction d'édition multi-étapes) :** Pour améliorer significativement le taux de réussite des modifications, surtout lorsque `old_string` fourni par le modèle n'est pas parfaitement précis, l'outil intègre un mécanisme de correction d'édition en plusieurs étapes. - - Si `old_string` initial n'est pas trouvé ou correspond à plusieurs endroits, l'outil peut utiliser le modèle Gemini pour affiner de manière itérative `old_string` (et potentiellement `new_string`). - - Ce processus d'auto-correction tente d'identifier le segment unique que le modèle voulait modifier, rendant l'opération `replace` plus robuste même avec un contexte initial légèrement imparfait. -- **Conditions d'échec :** Malgré le mécanisme de correction, l'outil échouera si : - - `file_path` n'est pas absolu ou se trouve en dehors du répertoire racine. - - `old_string` n'est pas vide, mais `file_path` n'existe pas. - - `old_string` est vide, mais `file_path` existe déjà. - - `old_string` n'est pas trouvé dans le fichier après les tentatives de correction. - - `old_string` est trouvé plusieurs fois, et le mécanisme d'auto-correction ne parvient pas à le résoudre en une seule correspondance non ambiguë. + - Si `old_string` est vide et que `file_path` n’existe pas, un nouveau fichier est créé avec `new_string` comme contenu. + - Si `old_string` est fourni, l’outil lit le fichier à `file_path` et tente de trouver une seule occurrence de `old_string`. + - Si une occurrence est trouvée, elle est remplacée par `new_string`. + - **Fiabilité améliorée (Correction multi-étapes) :** Pour améliorer significativement le taux de réussite des modifications, surtout lorsque le `old_string` fourni par le modèle n’est pas parfaitement précis, l’outil utilise un mécanisme de correction en plusieurs étapes. + - Si `old_string` n’est pas trouvé ou correspond à plusieurs endroits, l’outil peut utiliser le modèle Gemini pour affiner itérativement `old_string` (et éventuellement `new_string`). + - Ce processus d’auto-correction tente d’identifier le segment unique que le modèle voulait modifier, rendant l’opération `replace` plus robuste même avec un contexte initial légèrement imparfait. +- **Conditions d’échec :** Malgré le mécanisme de correction, l’outil échoue si : + - `file_path` n’est pas un chemin absolu ou se trouve en dehors du répertoire racine. + - `old_string` n’est pas vide mais `file_path` n’existe pas. + - `old_string` est vide mais `file_path` existe déjà. + - `old_string` n’est pas trouvé dans le fichier après les tentatives de correction. + - `old_string` est trouvé plusieurs fois et le mécanisme de correction ne parvient pas à identifier une correspondance unique. - **Sortie (`llmContent`) :** - En cas de succès : `Successfully modified file: /path/to/file.txt (1 replacements).` ou `Created new file: /path/to/new_file.txt with provided content.` - - En cas d'échec : Un message d'erreur expliquant la raison (par exemple, `Failed to edit, 0 occurrences found...`, `Failed to edit, expected 1 occurrences but found 2...`). -- **Confirmation :** Oui. Affiche un diff des modifications proposées et demande l'approbation de l'utilisateur avant d'écrire dans le fichier. + - En cas d’échec : Un message d’erreur expliquant la raison (ex. : `Failed to edit, 0 occurrences found...`, `Failed to edit, expected 1 occurrences but found 2...`). +- **Confirmation :** Oui. Affiche un diff des modifications proposées et demande l’approbation de l’utilisateur avant d’écrire dans le fichier. -Ces outils de système de fichiers fournissent une base pour que Qwen Code comprenne et interagisse avec le contexte de votre projet local. \ No newline at end of file +Ces outils du système de fichiers fournissent à Qwen Code une base pour comprendre et interagir avec le contexte de votre projet local. \ No newline at end of file diff --git a/website/content/fr/tools/index.md b/website/content/fr/tools/index.md index 1b9fd354..3a06c1de 100644 --- a/website/content/fr/tools/index.md +++ b/website/content/fr/tools/index.md @@ -1,4 +1,4 @@ -# Outils Qwen Code +# Outils de code Qwen Qwen Code inclut des outils intégrés que le modèle utilise pour interagir avec votre environnement local, accéder à des informations et effectuer des actions. Ces outils améliorent les capacités du CLI, lui permettant d'aller au-delà de la génération de texte et de vous aider dans un large éventail de tâches. @@ -6,14 +6,14 @@ Qwen Code inclut des outils intégrés que le modèle utilise pour interagir ave Dans le contexte de Qwen Code, les outils sont des fonctions ou modules spécifiques que le modèle peut demander d'exécuter. Par exemple, si vous demandez au modèle de "Résumer le contenu de `my_document.txt`", il identifiera probablement le besoin de lire ce fichier et demandera l'exécution de l'outil `read_file`. -Le composant principal (`packages/core`) gère ces outils, présente leurs définitions (schémas) au modèle, les exécute lorsqu'ils sont demandés, et renvoie les résultats au modèle pour un traitement supplémentaire dans une réponse destinée à l'utilisateur. +Le composant principal (`packages/core`) gère ces outils, présente leurs définitions (schémas) au modèle, les exécute lorsqu'ils sont demandés et renvoie les résultats au modèle pour un traitement supplémentaire dans une réponse destinée à l'utilisateur. Ces outils fournissent les capacités suivantes : - **Accès aux informations locales :** Les outils permettent au modèle d'accéder à votre système de fichiers local, de lire le contenu des fichiers, de lister les répertoires, etc. - **Exécution de commandes :** Avec des outils comme `run_shell_command`, le modèle peut exécuter des commandes shell (avec des mesures de sécurité appropriées et confirmation de l'utilisateur). - **Interaction avec le web :** Les outils peuvent récupérer du contenu à partir d'URLs. -- **Réalisation d'actions :** Les outils peuvent modifier des fichiers, écrire de nouveaux fichiers, ou effectuer d'autres actions sur votre système (là encore, généralement avec des protections). +- **Réalisation d'actions :** Les outils peuvent modifier des fichiers, écrire de nouveaux fichiers ou effectuer d'autres actions sur votre système (là encore, généralement avec des protections). - **Ancrage des réponses :** En utilisant des outils pour récupérer des données en temps réel ou des données locales spécifiques, les réponses peuvent être plus précises, pertinentes et ancrées dans votre contexte actuel. ## Comment utiliser les outils Qwen Code @@ -22,7 +22,7 @@ Pour utiliser les outils Qwen Code, il suffit de fournir un prompt au CLI. Le pr 1. Vous fournissez un prompt au CLI. 2. Le CLI envoie le prompt au core. -3. Le core, en combinaison avec votre prompt et l'historique de conversation, transmet la liste des outils disponibles ainsi que leurs descriptions/schémas à l'API du modèle configuré. +3. Le core, accompagné de votre prompt et de l'historique de conversation, transmet la liste des outils disponibles ainsi que leurs descriptions/schémas à l'API du modèle configuré. 4. Le modèle analyse votre requête. S'il détermine qu'un outil est nécessaire, sa réponse inclura une demande d'exécution d'un outil spécifique avec certains paramètres. 5. Le core reçoit cette demande d'outil, la valide, puis (souvent après confirmation de l'utilisateur pour les opérations sensibles) exécute l'outil. 6. La sortie de l'outil est renvoyée au modèle. @@ -34,21 +34,22 @@ En général, vous verrez des messages dans le CLI indiquant quand un outil est De nombreux outils, en particulier ceux qui peuvent modifier votre système de fichiers ou exécuter des commandes (`write_file`, `edit`, `run_shell_command`), sont conçus avec la sécurité en tête. Qwen Code va généralement : -- **Demander une confirmation :** Vous demander avant d'exécuter des opérations potentiellement sensibles, en vous montrant quelle action va être effectuée. -- **Utiliser le sandboxing :** Tous les outils sont soumis aux restrictions imposées par le sandboxing (voir [Sandboxing dans Qwen Code](../sandbox.md)). Cela signifie que lorsqu'on opère dans un sandbox, tous les outils (y compris les serveurs MCP) que vous souhaitez utiliser doivent être disponibles _à l'intérieur_ de l'environnement du sandbox. Par exemple, pour exécuter un serveur MCP via `npx`, l'exécutable `npx` doit être installé dans l'image Docker du sandbox ou être disponible dans l'environnement `sandbox-exec`. +- **Demander une confirmation :** Vous invite à confirmer avant d'exécuter des opérations potentiellement sensibles, en vous montrant l'action qui va être effectuée. +- **Utiliser le sandboxing :** Tous les outils sont soumis aux restrictions imposées par le sandboxing (voir [Sandboxing dans Qwen Code](../sandbox.md)). Cela signifie que lors d'une exécution dans un sandbox, tous les outils (y compris les serveurs MCP) que vous souhaitez utiliser doivent être disponibles _à l'intérieur_ de l'environnement du sandbox. Par exemple, pour exécuter un serveur MCP via `npx`, l'exécutable `npx` doit être installé dans l'image Docker du sandbox ou être disponible dans l'environnement `sandbox-exec`. -Il est important de toujours examiner attentivement les invites de confirmation avant d'autoriser un outil à continuer. +Il est important de toujours lire attentivement les messages de confirmation avant d'autoriser un outil à continuer. ## En savoir plus sur les outils de Qwen Code Les outils intégrés de Qwen Code peuvent être classés de la manière suivante : -- **[Outils de système de fichiers](./file-system.md) :** Pour interagir avec les fichiers et répertoires (lecture, écriture, listage, recherche, etc.). +- **[Outils du système de fichiers](./file-system.md) :** Pour interagir avec les fichiers et répertoires (lecture, écriture, listage, recherche, etc.). - **[Outil Shell](./shell.md) (`run_shell_command`) :** Pour exécuter des commandes shell. -- **[Outil Web Fetch](./web-fetch.md) (`web_fetch`) :** Pour récupérer du contenu à partir d'URLs. +- **[Outil Web Fetch](./web-fetch.md) (`web_fetch`) :** Pour récupérer le contenu d’URLs. - **[Outil Web Search](./web-search.md) (`web_search`) :** Pour effectuer des recherches sur le web. - **[Outil Multi-File Read](./multi-file.md) (`read_many_files`) :** Un outil spécialisé pour lire le contenu de plusieurs fichiers ou répertoires, souvent utilisé par la commande `@`. -- **[Outil Mémoire](./memory.md) (`save_memory`) :** Pour sauvegarder et rappeler des informations entre les sessions. +- **[Outil Mémoire](./memory.md) (`save_memory`) :** Pour sauvegarder et rappeler des informations entre différentes sessions. +- **[Outil Todo Write](./todo-write.md) (`todo_write`) :** Pour créer et gérer des listes de tâches structurées pendant les sessions de codage. En outre, ces outils intègrent : diff --git a/website/content/fr/tools/shell.md b/website/content/fr/tools/shell.md index 5a388e42..30a4c0a9 100644 --- a/website/content/fr/tools/shell.md +++ b/website/content/fr/tools/shell.md @@ -12,45 +12,94 @@ Utilisez `run_shell_command` pour interagir avec le système sous-jacent, exécu - `command` (string, requis) : La commande shell exacte à exécuter. - `description` (string, optionnel) : Une brève description de l'objectif de la commande, qui sera affichée à l'utilisateur. -- `directory` (string, optionnel) : Le répertoire (relatif à la racine du projet) dans lequel exécuter la commande. Si non fourni, la commande s'exécute dans la racine du projet. +- `directory` (string, optionnel) : Le répertoire (relatif à la racine du projet) dans lequel exécuter la commande. Si non spécifié, la commande s'exécute dans la racine du projet. +- `is_background` (boolean, requis) : Indique s'il faut exécuter la commande en arrière-plan. Ce paramètre est obligatoire pour s'assurer que le mode d'exécution est choisi explicitement. Définir à `true` pour les processus longs comme les serveurs de développement, les watchers ou les daemons qui doivent continuer à fonctionner sans bloquer les commandes suivantes. Définir à `false` pour les commandes ponctuelles qui doivent se terminer avant de continuer. ## Comment utiliser `run_shell_command` avec Qwen Code -Lors de l'utilisation de `run_shell_command`, la commande est exécutée en tant que sous-processus. `run_shell_command` peut démarrer des processus en arrière-plan en utilisant `&`. L'outil renvoie des informations détaillées sur l'exécution, notamment : +Lorsque vous utilisez `run_shell_command`, la commande est exécutée en tant que sous-processus. Vous pouvez contrôler si les commandes s'exécutent en arrière-plan ou en avant-plan en utilisant le paramètre `is_background`, ou en ajoutant explicitement `&` aux commandes. L'outil renvoie des informations détaillées sur l'exécution, notamment : + +### Paramètre obligatoire `is_background` + +Le paramètre `is_background` est **obligatoire** pour toutes les exécutions de commandes. Cette conception garantit que le LLM (et les utilisateurs) doit explicitement décider si chaque commande doit s'exécuter en arrière-plan ou en avant-plan, favorisant ainsi un comportement d'exécution intentionnel et prévisible. En rendant ce paramètre obligatoire, nous évitons les retours involontaires à l'exécution en avant-plan, ce qui pourrait bloquer les opérations suivantes lors du traitement de processus longs. + +### Exécution en arrière-plan vs premier plan + +L'outil gère intelligemment l'exécution en arrière-plan et en premier plan selon votre choix explicite : + +**Utilisez l'exécution en arrière-plan (`is_background: true`) pour :** + +- Les serveurs de développement longue durée : `npm run start`, `npm run dev`, `yarn dev` +- Les watchers de build : `npm run watch`, `webpack --watch` +- Les serveurs de base de données : `mongod`, `mysql`, `redis-server` +- Les serveurs web : `python -m http.server`, `php -S localhost:8000` +- Toute commande prévue pour s'exécuter indéfiniment jusqu'à un arrêt manuel + +**Utilisez l'exécution en premier plan (`is_background: false`) pour :** + +- Les commandes ponctuelles : `ls`, `cat`, `grep` +- Les commandes de build : `npm run build`, `make` +- Les commandes d'installation : `npm install`, `pip install` +- Les opérations Git : `git commit`, `git push` +- Les exécutions de tests : `npm test`, `pytest` + +### Informations d'exécution + +L'outil retourne des informations détaillées sur l'exécution, incluant : - `Command` : La commande qui a été exécutée. -- `Directory` : Le répertoire dans lequel la commande a été exécutée. +- `Directory` : Le répertoire dans lequel la commande a été lancée. - `Stdout` : La sortie du flux standard. - `Stderr` : La sortie du flux d'erreur standard. - `Error` : Tout message d'erreur rapporté par le sous-processus. - `Exit Code` : Le code de sortie de la commande. - `Signal` : Le numéro du signal si la commande a été terminée par un signal. -- `Background PIDs` : Une liste des PIDs des processus en arrière-plan démarrés. +- `Background PIDs` : Une liste des PIDs des processus lancés en arrière-plan. Utilisation : +```bash +run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.", is_background=false) ``` -run_shell_command(command="Vos commandes.", description="Votre description de la commande.", directory="Votre répertoire d'exécution.") -``` -## Exemples de `run_shell_command` +**Note :** Le paramètre `is_background` est obligatoire et doit être explicitement spécifié pour chaque exécution de commande. + +## Exemples `run_shell_command` Lister les fichiers dans le répertoire courant : -``` -run_shell_command(command="ls -la") +```bash +run_shell_command(command="ls -la", is_background=false) ``` Exécuter un script dans un répertoire spécifique : +```bash +run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script", is_background=false) +``` + +Démarrer un serveur de développement en arrière-plan (approche recommandée) : + +```bash +run_shell_command(command="npm run dev", description="Start development server in background", is_background=true) ``` -run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script") + +Démarrer un serveur en arrière-plan (alternative avec & explicite) : + +```bash +run_shell_command(command="npm run dev &", description="Start development server in background", is_background=false) ``` -Démarrer un serveur en arrière-plan : +Exécuter une commande de build en premier plan : +```bash +run_shell_command(command="npm run build", description="Build the project", is_background=false) ``` -run_shell_command(command="npm run dev &", description="Start development server in background") + +Démarrer plusieurs services en arrière-plan : + +```bash +run_shell_command(command="docker-compose up", description="Start all services", is_background=true) ``` ## Notes importantes @@ -58,11 +107,13 @@ run_shell_command(command="npm run dev &", description="Start development server - **Sécurité :** Soyez prudent lors de l'exécution de commandes, en particulier celles construites à partir d'entrées utilisateur, afin d'éviter les vulnérabilités de sécurité. - **Commandes interactives :** Évitez les commandes qui nécessitent une entrée utilisateur interactive, car cela peut bloquer l'outil. Utilisez des options non interactives si disponibles (par exemple, `npm init -y`). - **Gestion des erreurs :** Vérifiez les champs `Stderr`, `Error` et `Exit Code` pour déterminer si une commande s'est exécutée avec succès. -- **Processus en arrière-plan :** Lorsqu'une commande est lancée en arrière-plan avec `&`, l'outil retourne immédiatement la main et le processus continue de s'exécuter en arrière-plan. Le champ `Background PIDs` contiendra l'identifiant du processus exécuté en arrière-plan. +- **Processus en arrière-plan :** Lorsque `is_background=true` ou quand une commande contient `&`, l'outil retourne immédiatement la main et le processus continue de s'exécuter en arrière-plan. Le champ `Background PIDs` contiendra l'identifiant du processus en arrière-plan. +- **Choix d'exécution en arrière-plan :** Le paramètre `is_background` est obligatoire et permet un contrôle explicite sur le mode d'exécution. Vous pouvez également ajouter `&` à la commande pour une exécution manuelle en arrière-plan, mais le paramètre `is_background` doit tout de même être spécifié. Ce paramètre rend l'intention plus claire et gère automatiquement la configuration de l'exécution en arrière-plan. +- **Descriptions des commandes :** Lors de l'utilisation de `is_background=true`, la description de la commande inclura un indicateur `[background]` pour montrer clairement le mode d'exécution. ## Variables d'environnement -Lorsque `run_shell_command` exécute une commande, il définit la variable d'environnement `QWEN_CODE=1` dans l'environnement du sous-processus. Cela permet aux scripts ou outils de détecter s'ils sont exécutés depuis le CLI. +Lorsque `run_shell_command` exécute une commande, elle définit la variable d'environnement `QWEN_CODE=1` dans l'environnement du sous-processus. Cela permet aux scripts ou aux outils de détecter s'ils sont exécutés depuis l'CLI. ## Restrictions des commandes @@ -108,9 +159,9 @@ Pour bloquer `rm` et autoriser toutes les autres commandes : - `git status` : Autorisé - `npm install` : Autorisé -**La liste de blocage a priorité** +**La liste noire (blocklist) est prioritaire** -Si un préfixe de commande est à la fois dans `coreTools` et `excludeTools`, il sera bloqué. +Si un préfixe de commande est présent à la fois dans `coreTools` et `excludeTools`, il sera bloqué. ```json { @@ -133,7 +184,7 @@ Pour bloquer toutes les commandes shell, ajoutez le wildcard `run_shell_command` ``` - `ls -l` : Bloqué -- `n'importe quelle autre commande` : Bloqué +- `n'importe quelle autre commande` : Bloquée ## Note de sécurité pour `excludeTools` diff --git a/website/content/fr/tools/todo-write.md b/website/content/fr/tools/todo-write.md new file mode 100644 index 00000000..251f602e --- /dev/null +++ b/website/content/fr/tools/todo-write.md @@ -0,0 +1,63 @@ +# Outil Todo Write (`todo_write`) + +Ce document décrit l'outil `todo_write` pour Qwen Code. + +## Description + +Utilisez `todo_write` pour créer et gérer une liste de tâches structurée pendant votre session de codage actuelle. Cet outil aide l'assistant IA à suivre l'avancement et organiser les tâches complexes, en vous offrant une visibilité sur le travail en cours. + +### Arguments + +`todo_write` prend un seul argument : + +- `todos` (array, requis) : Un tableau d'éléments todo, où chaque élément contient : + - `id` (string, requis) : Un identifiant unique pour l'élément todo. + - `content` (string, requis) : La description de la tâche. + - `status` (string, requis) : Le statut actuel (`pending`, `in_progress`, ou `completed`). + +## Comment utiliser `todo_write` avec Qwen Code + +L'assistant IA utilisera automatiquement cet outil lorsqu'il travaille sur des tâches complexes nécessitant plusieurs étapes. Vous n'avez pas besoin de le demander explicitement, mais vous pouvez demander à l'assistant de créer une liste de tâches si vous souhaitez voir l'approche planifiée pour votre demande. + +L'outil stocke les listes de tâches dans votre répertoire personnel (`~/.qwen/todos/`) avec des fichiers spécifiques à chaque session, afin que chaque session de codage conserve sa propre liste de tâches. + +## Quand l'IA utilise cet outil + +L'assistant utilise `todo_write` pour : + +- Les tâches complexes nécessitant plusieurs étapes +- Les implémentations de fonctionnalités avec plusieurs composants +- Les opérations de refactoring sur plusieurs fichiers +- Tout travail impliquant 3 actions distinctes ou plus + +L'assistant n'utilisera pas cet outil pour les tâches simples d'une seule étape ou les demandes purement informatives. + +### Exemples `todo_write` + +Création d'un plan d'implémentation de fonctionnalité : + +``` +todo_write(todos=[ + { + "id": "create-model", + "content": "Create user preferences model", + "status": "pending" + }, + { + "id": "add-endpoints", + "content": "Add API endpoints for preferences", + "status": "pending" + }, + { + "id": "implement-ui", + "content": "Implement frontend components", + "status": "pending" + } +]) +``` + +## Notes importantes + +- **Utilisation automatique :** L'assistant AI gère automatiquement les listes todo pendant les tâches complexes. +- **Visibilité de la progression :** Vous verrez les listes todo mises à jour en temps réel au fur et à mesure de l'avancement du travail. +- **Isolation des sessions :** Chaque session de codage possède sa propre liste todo qui n'interfère pas avec les autres. \ No newline at end of file diff --git a/website/content/fr/troubleshooting.md b/website/content/fr/troubleshooting.md index c3ac22f6..74ad14f4 100644 --- a/website/content/fr/troubleshooting.md +++ b/website/content/fr/troubleshooting.md @@ -1,28 +1,28 @@ # Guide de dépannage -Ce guide fournit des solutions aux problèmes courants et des conseils de débogage, notamment sur les sujets suivants : +Ce guide fournit des solutions aux problèmes courants et des conseils de débogage, incluant les sujets suivants : - Erreurs d'authentification ou de connexion -- Foire aux questions (FAQ) +- Foire aux questions (FAQs) - 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 : `Failed to login. Message: Request contains an invalid argument`** - - Les utilisateurs disposant de comptes Google Workspace ou de comptes Google Cloud - associés à leurs comptes Gmail peuvent ne pas pouvoir activer la - formule Google Code Assist gratuite. - - Pour les comptes Google Cloud, vous pouvez contourner ce problème en définissant - `GOOGLE_CLOUD_PROJECT` avec l'ID de votre projet. - - Vous pouvez également obtenir la clé API Gemini depuis - [Google AI Studio](http://aistudio.google.com/app/apikey), qui inclut également une - formule gratuite distincte. + - Les utilisateurs disposant de comptes Google Workspace ou de comptes Google Cloud associés à leurs comptes Gmail peuvent ne pas pouvoir activer la formule Google Code Assist gratuite. + - Pour les comptes Google Cloud, vous pouvez contourner ce problème en définissant `GOOGLE_CLOUD_PROJECT` avec l'ID de votre projet. + - Vous pouvez également obtenir une clé API Gemini depuis [Google AI Studio](http://aistudio.google.com/app/apikey), qui inclut également un quota gratuit distinct. + +- **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é racine 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 l'autorité racine de votre 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` : @@ -32,41 +32,41 @@ 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 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 (Gemini API key ou Google Cloud Vertex AI), mais pas pour les utilisateurs OAuth (comme les comptes Google personnels ou professionnels, par exemple Gmail ou Google Workspace). Cela est dû au fait que l'API Gemini 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`. + - 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 (clé API Gemini ou Google Cloud Vertex AI), mais pas pour les utilisateurs OAuth (comme les comptes Google personnels ou professionnels, par exemple Gmail ou Google Workspace). Cela est dû au fait que l'API Gemini 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`. ## Messages d'erreur courants et solutions -- **Erreur : `EADDRINUSE` (Adresse déjà utilisée) lors du démarrage d’un serveur MCP.** +- **Erreur : `EADDRINUSE` (Adresse déjà utilisée) lors du démarrage d'un serveur MCP.** - **Cause :** Un autre processus utilise déjà le port sur lequel le serveur MCP tente de se lier. - **Solution :** - Arrêtez l’autre processus qui utilise le port ou configurez le serveur MCP pour utiliser un port différent. + Arrêtez l'autre processus utilisant le port ou configurez le serveur MCP pour utiliser un port différent. -- **Erreur : Command not found (lors de la tentative d’exécution de Qwen Code avec `qwen`).** - - **Cause :** Le CLI n’est pas correctement installé ou il n’est pas dans le `PATH` de votre système. +- **Erreur : Command not found (lors de la tentative d'exécution de Qwen Code avec `qwen`).** + - **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 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’appeler (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`. + - 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 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.** - - **Cause :** Les dépendances ne sont pas correctement installées, ou le projet n’a pas été compilé. +- **Erreur : `MODULE_NOT_FOUND` ou erreurs d'import.** + - **Cause :** Les dépendances ne sont pas installées correctement, ou le projet n'a pas été construit. - **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 en exécutant `npm run start`. + 3. Vérifiez que la construction s'est terminée avec succès avec `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. - - **Solution :** Consultez la documentation [Configuration : Sandboxing](./cli/configuration.md#sandboxing) pour plus d’informations, notamment sur la personnalisation de votre configuration de sandbox. + - **Solution :** Consultez la documentation [Configuration : Sandboxing](./cli/configuration.md#sandboxing) pour plus d'informations, notamment sur la personnalisation de votre configuration de sandbox. -- **Qwen Code ne s’exécute pas en mode interactif dans les environnements "CI"** - - **Problème :** Qwen Code ne démarre pas en mode interactif (aucune invite de commande n’apparaît) si une variable d’environnement commençant par `CI_` (par exemple, `CI_TOKEN`) est définie. Cela est dû au fait que le package `is-in-ci`, utilisé par le framework UI sous-jacent, détecte ces variables et considère qu’il s’agit d’un environnement CI non interactif. - - **Cause :** Le package `is-in-ci` vérifie la présence de `CI`, `CONTINUOUS_INTEGRATION`, ou de toute variable d’environnement avec un préfixe `CI_`. Si l’une d’elles est trouvée, cela indique que l’environnement est non interactif, ce qui empêche le CLI de démarrer en mode interactif. - - **Solution :** Si la variable préfixée avec `CI_` n’est pas nécessaire au fonctionnement du CLI, vous pouvez la désactiver temporairement pour la commande. Par exemple : `env -u CI_TOKEN qwen` +- **Qwen Code ne s'exécute pas en mode interactif dans les environnements "CI"** + - **Problème :** Qwen Code ne démarre pas en mode interactif (aucune invite n'apparaît) si une variable d'environnement commençant par `CI_` (par exemple, `CI_TOKEN`) est définie. Cela est dû au fait que le package `is-in-ci`, utilisé par le framework UI sous-jacent, détecte ces variables et considère qu'il s'agit d'un environnement CI non interactif. + - **Cause :** Le package `is-in-ci` vérifie la présence de `CI`, `CONTINUOUS_INTEGRATION`, ou de toute variable d'environnement préfixée par `CI_`. Si l'une d'elles est trouvée, cela indique que l'environnement est non interactif, ce qui empêche le CLI de démarrer en mode interactif. + - **Solution :** Si la variable préfixée par `CI_` n'est pas nécessaire au fonctionnement du CLI, vous pouvez la désactiver temporairement pour la commande. Par exemple : `env -u CI_TOKEN qwen` - **Le mode DEBUG ne fonctionne pas depuis le fichier .env du projet** - - **Problème :** Définir `DEBUG=true` dans le fichier `.env` d’un projet n’active pas le mode debug pour le CLI. - - **Cause :** Les variables `DEBUG` et `DEBUG_MODE` sont automatiquement exclues des fichiers `.env` du projet pour éviter d’interférer avec le comportement du CLI. + - **Problème :** Définir `DEBUG=true` dans le fichier `.env` d'un projet n'active pas le mode debug pour le CLI. + - **Cause :** Les variables `DEBUG` et `DEBUG_MODE` sont automatiquement exclues des fichiers `.env` du projet pour éviter d'interférer avec le comportement du CLI. - **Solution :** Utilisez plutôt un fichier `.qwen/.env`, ou configurez le paramètre `excludedProjectEnvVars` dans votre `settings.json` pour exclure moins de variables. ## IDE Companion ne se connecte pas @@ -75,19 +75,19 @@ 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 de manière appropriée. -- Réinstallez le companion avec `/ide install` et utilisez "Qwen Code: Run" dans la Command Palette pour vérifier qu'il se lance correctement. +- Si vous exécutez dans un container, vérifiez que `host.docker.internal` est résolu. Sinon, mappez l'hôte correctement. +- Réinstallez le companion avec `/ide install` et utilisez "Qwen Code: Run" dans la Command Palette pour vérifier qu'il se lance. ## 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. - 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. + - Utilisez les outils de débogage Node.js (ex : `node --inspect`) si vous devez parcourir le code côté serveur pas à pas. - **Problèmes d'outils :** - Si un outil spécifique échoue, essayez d'isoler le problème en exécutant la version la plus simple possible de la commande ou de l'opération effectuée par l'outil. @@ -95,7 +95,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 nombreux problèmes courants liés 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 type. ## Issues GitHub existants similaires au vôtre ou création de nouvelles Issues diff --git a/website/content/ja/cli/configuration.md b/website/content/ja/cli/configuration.md index 18b744b5..e1f87258 100644 --- a/website/content/ja/cli/configuration.md +++ b/website/content/ja/cli/configuration.md @@ -22,12 +22,12 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 - **適用範囲:** 現在のユーザーのすべての Qwen Code セッションに適用されます。 - **プロジェクト設定ファイル:** - **場所:** プロジェクトのルートディレクトリ内の `.qwen/settings.json` - - **適用範囲:** その特定のプロジェクトから Qwen Code を実行するときのみ適用されます。プロジェクト設定はユーザー設定より優先されます。 + - **適用範囲:** その特定のプロジェクトから Qwen Code を実行するときのみ適用されます。プロジェクト設定はユーザー設定よりも優先されます。 - **システム設定ファイル:** - - **場所:** `/etc/gemini-cli/settings.json`（Linux）、`C:\ProgramData\gemini-cli\settings.json`（Windows）または `/Library/Application Support/GeminiCli/settings.json`（macOS）。パスは環境変数 `GEMINI_CLI_SYSTEM_SETTINGS_PATH` で上書き可能です。 - - **適用範囲:** システム上のすべてのユーザーの Qwen Code セッションに適用されます。システム設定はユーザー設定およびプロジェクト設定より優先されます。エンタープライズ環境のシステム管理者がユーザーの Qwen Code 環境を一元管理するのに役立ちます。 + - **場所:** `/etc/gemini-cli/settings.json`（Linux）、`C:\ProgramData\gemini-cli\settings.json`（Windows）、または `/Library/Application Support/GeminiCli/settings.json`（macOS）。パスは環境変数 `GEMINI_CLI_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` ディレクトリ @@ -37,16 +37,16 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 ### `settings.json` で利用可能な設定: -- **`contextFileName`** (string または string の配列): +- **`contextFileName`** (文字列または文字列の配列): - **説明:** コンテキストファイルのファイル名を指定します（例: `QWEN.md`, `AGENTS.md`）。単一のファイル名、または許可するファイル名のリストを指定できます。 - **デフォルト:** `QWEN.md` - **例:** `"contextFileName": "AGENTS.md"` -- **`bugCommand`** (object): +- **`bugCommand`** (オブジェクト): - **説明:** `/bug` コマンドのデフォルト URL を上書きします。 - **デフォルト:** `"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"` - **プロパティ:** - - **`urlTemplate`** (string): `{title}` および `{info}` プレースホルダーを含むことができる URL。 + - **`urlTemplate`** (文字列): `{title}` および `{info}` プレースホルダーを含むことができる URL。 - **例:** ```json "bugCommand": { @@ -54,11 +54,11 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 } ``` -- **`fileFiltering`** (object): +- **`fileFiltering`** (オブジェクト): - **説明:** @ コマンドやファイル検出ツールにおける git-aware なファイルフィルタリングの動作を制御します。 - **デフォルト:** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` - **プロパティ:** - - **`respectGitIgnore`** (boolean): ファイル検出時に .gitignore のパターンを尊重するかどうか。`true` に設定すると、git で無視されたファイル（例: `node_modules/`, `dist/`, `.env`）は @ コマンドやファイル一覧操作から自動的に除外されます。 + - **`respectGitIgnore`** (boolean): ファイル検出時に .gitignore のパターンを尊重するかどうか。`true` に設定すると、git で無視されたファイル（`node_modules/`, `dist/`, `.env` など）は @ コマンドやファイルリスト操作から自動的に除外されます。 - **`enableRecursiveFileSearch`** (boolean): プロンプトで @ プレフィックスを補完する際に、現在のツリー配下のファイル名を再帰的に検索するかどうか。 - **例:** ```json @@ -68,75 +68,75 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 } ``` -- **`coreTools`** (string の配列): - - **説明:** モデルで利用可能にするコアツール名のリストを指定できます。これにより、組み込みツールのセットを制限できます。コアツールの一覧については [Built-in Tools](../core/tools-api.md#built-in-tools) を参照してください。また、`ShellTool` のような対応するツールに対して、コマンド単位での制限を指定することも可能です。例えば、`"coreTools": ["ShellTool(ls -l)"]` とすると、`ls -l` コマンドのみが実行可能になります。 +- **`coreTools`** (文字列の配列): + - **説明:** モデルで利用可能にするコアツール名のリストを指定できます。これにより、組み込みツールのセットを制限できます。コアツールの一覧については [Built-in Tools](../core/tools-api.md#built-in-tools) を参照してください。また、`ShellTool` のように対応しているツールについては、コマンド単位での制限も可能です。例: `"coreTools": ["ShellTool(ls -l)"]` と指定すると、`ls -l` コマンドのみが実行可能になります。 - **デフォルト:** モデルで利用可能なすべてのツール。 - **例:** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]` -- **`excludeTools`** (string の配列): - - **説明:** モデルから除外するコアツール名のリストを指定できます。`excludeTools` と `coreTools` の両方に記載されたツールは除外されます。また、`ShellTool` のような対応するツールに対して、コマンド単位での制限を指定することも可能です。例えば、`"excludeTools": ["ShellTool(rm -rf)"]` とすると、`rm -rf` コマンドがブロックされます。 +- **`excludeTools`** (文字列の配列): + - **説明:** モデルから除外するコアツール名のリストを指定できます。`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`** (string の配列): +- **`allowMCPServers`** (文字列の配列): - **説明:** モデルで利用可能にする MCP サーバー名のリストを指定できます。これにより、接続する MCP サーバーのセットを制限できます。`--allowed-mcp-server-names` が設定されている場合、この設定は無視されます。 - **デフォルト:** モデルで利用可能なすべての MCP サーバー。 - **例:** `"allowMCPServers": ["myPythonServer"]` - - **セキュリティに関する注意:** MCP サーバー名に対して単純な文字列一致を使用しており、変更可能です。この設定をユーザーに回避させたくない場合は、システム設定レベルで `mcpServers` を構成し、ユーザーが独自の MCP サーバーを設定できないようにすることを検討してください。これは堅牢なセキュリティメカニズムとしては使用しないでください。 + - **セキュリティに関する注意:** MCP サーバー名の単純な文字列マッチを使用しており、変更可能です。ユーザーによるバイパスを防ぎたいシステム管理者は、システム設定レベルで `mcpServers` を構成し、ユーザーが独自の MCP サーバーを設定できないようにすることを検討してください。これは堅牢なセキュリティメカニズムとしては使用しないでください。 -- **`excludeMCPServers`** (string の配列): - - **説明:** モデルから除外する MCP サーバー名のリストを指定できます。`excludeMCPServers` と `allowMCPServers` の両方に記載されたサーバーは除外されます。`--allowed-mcp-server-names` が設定されている場合、この設定は無視されます。 +- **`excludeMCPServers`** (文字列の配列): + - **説明:** モデルから除外する 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): +- **`theme`** (文字列): - **説明:** Qwen Code の視覚的な [テーマ](./themes.md) を設定します。 - **デフォルト:** `"Default"` - **例:** `"theme": "GitHub"` - **`vimMode`** (boolean): - - **説明:** 入力編集用の vim モードを有効または無効にします。有効にすると、入力エリアで vim スタイルのナビゲーションおよび編集コマンド（NORMAL モードと INSERT モード）がサポートされます。vim モードの状態はフッターに表示され、セッション間で保持されます。 + - **説明:** 入力編集時の vim モードを有効または無効にします。有効にすると、入力エリアで vim スタイルのナビゲーションおよび編集コマンド（NORMAL モードと INSERT モード）がサポートされます。vim モードの状態はフッターに表示され、セッション間で保持されます。 - **デフォルト:** `false` - **例:** `"vimMode": true` -- **`sandbox`** (boolean または string): +- **`sandbox`** (boolean または文字列): - **説明:** ツール実行時のサンドボックスの使用方法を制御します。`true` に設定すると、Qwen Code は事前にビルドされた `qwen-code-sandbox` Docker イメージを使用します。詳細については [Sandboxing](#sandboxing) を参照してください。 - **デフォルト:** `false` - **例:** `"sandbox": "docker"` -- **`toolDiscoveryCommand`** (string): +- **`toolDiscoveryCommand`** (文字列): - **説明:** プロジェクトからツールを検出するためのカスタムシェルコマンドを定義します。シェルコマンドは `stdout` に [function declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) の JSON 配列を返す必要があります。ツールラッパーはオプションです。 - **デフォルト:** 空 - **例:** `"toolDiscoveryCommand": "bin/get_tools"` -- **`toolCallCommand`** (string): - - **説明:** `toolDiscoveryCommand` を使用して検出された特定のツールを呼び出すためのカスタムシェルコマンドを定義します。シェルコマンドは以下の条件を満たす必要があります: +- **`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": "bin/call_tool"` -- **`mcpServers`** (object): - - **説明:** カスタムツールを検出して使用するための 1 つ以上の Model-Context Protocol (MCP) サーバーへの接続を構成します。Qwen Code は構成された各 MCP サーバーに接続を試み、利用可能なツールを検出します。複数の MCP サーバーが同じ名前のツールを公開している場合、ツール名は構成で定義したサーバーエイリアスでプレフィックスが付けられ（例: `serverAlias__actualToolName`）、競合を回避します。システムは互換性のために MCP ツール定義から特定のスキーマプロパティを削除する場合があります。 +- **`mcpServers`** (オブジェクト): + - **説明:** カスタムツールを検出して使用するための 1 つ以上の Model-Context Protocol (MCP) サーバーへの接続を構成します。Qwen Code は構成された各 MCP サーバーに接続し、利用可能なツールを検出しようとします。複数の MCP サーバーが同じ名前のツールを公開している場合、ツール名は構成で定義したサーバーエイリアスでプレフィックスが付けられ（例: `serverAlias__actualToolName`）、競合を回避します。システムは互換性のために MCP ツール定義から特定のスキーマプロパティを削除する場合があります。 - **デフォルト:** 空 - **プロパティ:** - - **``** (object): 指定されたサーバーのパラメータ。 - - `command` (string, 必須): MCP サーバーを起動するためのコマンド。 - - `args` (string の配列, オプション): コマンドに渡す引数。 - - `env` (object, オプション): サーバープロセスに設定する環境変数。 - - `cwd` (string, オプション): サーバーを起動する作業ディレクトリ。 - - `timeout` (number, オプション): この MCP サーバーへのリクエストのタイムアウト（ミリ秒）。 + - **``** (オブジェクト): 指定されたサーバーのパラメータ。 + - `command` (文字列, 必須): MCP サーバーを起動するためのコマンド。 + - `args` (文字列の配列, オプション): コマンドに渡す引数。 + - `env` (オブジェクト, オプション): サーバープロセスに設定する環境変数。 + - `cwd` (文字列, オプション): サーバーを起動する作業ディレクトリ。 + - `timeout` (数値, オプション): この MCP サーバーへのリクエストのタイムアウト（ミリ秒）。 - `trust` (boolean, オプション): このサーバーを信頼し、すべてのツール呼び出し確認をバイパスします。 - - `includeTools` (string の配列, オプション): この MCP サーバーから含めるツール名のリスト。指定された場合、ここにリストされたツールのみがこのサーバーから利用可能になります（ホワイトリスト動作）。指定されていない場合、デフォルトでサーバーのすべてのツールが有効になります。 - - `excludeTools` (string の配列, オプション): この MCP サーバーから除外するツール名のリスト。ここにリストされたツールは、サーバーによって公開されていてもモデルでは利用できません。**注意:** `excludeTools` は `includeTools` よりも優先されます。両方のリストにツールが含まれている場合、除外されます。 + - `includeTools` (文字列の配列, オプション): この MCP サーバーからインクルードするツール名のリスト。指定された場合、ここにリストされたツールのみがこのサーバーから利用可能になります（ホワイトリスト動作）。指定されていない場合、デフォルトでサーバーのすべてのツールが有効になります。 + - `excludeTools` (文字列の配列, オプション): この MCP サーバーから除外するツール名のリスト。ここにリストされたツールは、サーバーが公開していてもモデルでは利用できません。**注意:** `excludeTools` は `includeTools` よりも優先されます。両方のリストにツールが含まれている場合、除外されます。 - **例:** ```json "mcpServers": { @@ -163,24 +163,24 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 } ``` -- **`checkpointing`** (object): - - **説明:** 会話およびファイルの状態を保存および復元するためのチェックポイント機能を構成します。詳細については [Checkpointing documentation](../checkpointing.md) を参照してください。 +- **`checkpointing`** (オブジェクト): + - **説明:** 会話およびファイル状態の保存・復元を可能にするチェックポイント機能を構成します。詳細については [Checkpointing documentation](../checkpointing.md) を参照してください。 - **デフォルト:** `{"enabled": false}` - **プロパティ:** - **`enabled`** (boolean): `true` の場合、`/restore` コマンドが利用可能になります。 -- **`preferredEditor`** (string): +- **`preferredEditor`** (文字列): - **説明:** diff 表示に使用するエディタを指定します。 - **デフォルト:** `vscode` - **例:** `"preferredEditor": "vscode"` -- **`telemetry`** (object) - - **説明:** Qwen Code のロギングおよびメトリクス収集を構成します。詳細については [Telemetry](../telemetry.md) を参照してください。 +- **`telemetry`** (オブジェクト): + - **説明:** Qwen Code のログおよびメトリクス収集を構成します。詳細については [Telemetry](../telemetry.md) を参照してください。 - **デフォルト:** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **プロパティ:** - **`enabled`** (boolean): テレメトリが有効かどうか。 - - **`target`** (string): 収集されたテレメトリの送信先。サポートされる値は `local` および `gcp`。 - - **`otlpEndpoint`** (string): OTLP Exporter のエンドポイント。 + - **`target`** (文字列): 収集されたテレメトリの送信先。サポートされる値は `local` および `gcp`。 + - **`otlpEndpoint`** (文字列): OTLP Exporter のエンドポイント。 - **`logPrompts`** (boolean): ユーザープロンプトの内容をログに含めるかどうか。 - **例:** ```json @@ -216,18 +216,18 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 "hideBanner": true ``` -- **`maxSessionTurns`** (number): +- **`maxSessionTurns`** (数値): - **説明:** セッションの最大ターン数を設定します。セッションがこの制限を超えると、CLI は処理を停止し、新しいチャットを開始します。 - - **デフォルト:** `-1`（無制限） + - **デフォルト:** `-1` (無制限) - **例:** ```json "maxSessionTurns": 10 ``` -- **`summarizeToolOutput`** (object): +- **`summarizeToolOutput`** (オブジェクト): - **説明:** ツール出力の要約を有効または無効にします。`tokenBudget` 設定を使用して、要約のトークン予算を指定できます。 - 注意: 現在は `run_shell_command` ツールのみがサポートされています。 - - **デフォルト:** `{}`（デフォルトでは無効） + - **デフォルト:** `{}` (デフォルトでは無効) - **例:** ```json "summarizeToolOutput": { @@ -237,8 +237,8 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 } ``` -- **`excludedProjectEnvVars`** (string の配列): - - **説明:** プロジェクトの `.env` ファイルから読み込まれるべきでない環境変数を指定します。これにより、プロジェクト固有の環境変数（例: `DEBUG=true`）が CLI の動作に干渉することを防ぎます。`.qwen/.env` ファイルからの変 +- **`excludedProjectEnvVars`** (文字列の配列): + - **説明:** プロジェクトの `.env` ファイルから読み込まれるべきでない環境変数を指定します。これにより、プロジェクト固有 ### `settings.json` の例: @@ -283,29 +283,29 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 CLIは実行したshellコマンドの履歴を保持します。異なるプロジェクト間での競合を避けるため、この履歴はユーザーのホームフォルダ内のプロジェクト固有のディレクトリに保存されます。 -- **Location:** `~/.qwen/tmp//shell_history` +- **保存場所:** `~/.qwen/tmp//shell_history` - ``はプロジェクトのルートパスから生成される一意の識別子です。 - 履歴は`shell_history`という名前のファイルに保存されます。 -## 環境変数 & `.env` ファイル +## 環境変数と `.env` ファイル -環境変数は、特に API キーのような機密情報や、環境によって変わる設定に対して、アプリケーションを設定する一般的な方法です。 +環境変数は、アプリケーションを設定する一般的な方法です。特に API キーのような機密情報や、環境によって変わる設定に使われます。 CLI は `.env` ファイルから自動的に環境変数を読み込みます。読み込み順序は以下の通りです： -1. 現在の作業ディレクトリにある `.env` ファイル。 -2. 見つからない場合、親ディレクトリを上に向かって検索し、`.env` ファイルが見つかるか、プロジェクトルート（`.git` フォルダで識別される）またはホームディレクトリに到達するまで続けます。 +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` 設定でカスタマイズできます。 - **`GEMINI_API_KEY`**（必須）： - Gemini API 用の API キー。 - - **動作に不可欠。** CLI はこれがないと機能しません。 + - **動作に必須。** CLI はこれがないと動作しません。 - シェルプロファイル（例：`~/.bashrc`、`~/.zshrc`）または `.env` ファイルで設定してください。 - **`GEMINI_MODEL`**： - 使用するデフォルトの Gemini モデルを指定します。 - - ハードコードされたデフォルトを上書きします。 + - ハードコードされたデフォルト値を上書きします。 - 例：`export GEMINI_MODEL="gemini-2.5-flash"` - **`GOOGLE_API_KEY`**： - Google Cloud API キー。 @@ -313,7 +313,7 @@ CLI は `.env` ファイルから自動的に環境変数を読み込みます - 必要な権限があることを確認してください。 - 例：`export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`。 - **`GOOGLE_CLOUD_PROJECT`**： - - Google Cloud プロジェクト ID。 + - Google Cloud Project ID。 - Code Assist または Vertex AI を使用するために必要です。 - Vertex AI を使用する場合、このプロジェクトで必要な権限があることを確認してください。 - **Cloud Shell メモ：** Cloud Shell 環境で実行している場合、この変数は Cloud Shell ユーザー用に割り当てられた特別なプロジェクトをデフォルトとします。Cloud Shell のグローバル環境で `GOOGLE_CLOUD_PROJECT` が設定されている場合、このデフォルトによって上書きされます。Cloud Shell で別のプロジェクトを使用するには、`.env` ファイルで `GOOGLE_CLOUD_PROJECT` を定義する必要があります。 @@ -322,10 +322,10 @@ CLI は `.env` ファイルから自動的に環境変数を読み込みます - **説明：** Google Application Credentials JSON ファイルへのパス。 - **例：** `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"` - **`OTLP_GOOGLE_CLOUD_PROJECT`**： - - Google Cloud のテレメトリ用の Google Cloud プロジェクト ID。 + - Google Cloud でのテレメトリ用の Google Cloud Project ID。 - 例：`export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`。 - **`GOOGLE_CLOUD_LOCATION`**： - - Google Cloud プロジェクトのロケーション（例：us-central1）。 + - Google Cloud Project のロケーション（例：us-central1）。 - Express モード以外で Vertex AI を使用するために必要です。 - 例：`export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`。 - **`GEMINI_SANDBOX`**： @@ -333,16 +333,16 @@ CLI は `.env` ファイルから自動的に環境変数を読み込みます - `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`）。 -- **`DEBUG` または `DEBUG_MODE`**（下位ライブラリや CLI 自体でよく使用される）： - - `true` または `1` に設定すると、詳細なデバッグログが有効になり、トラブルシューティングに役立ちます。 - - **注意：** これらの変数は、CLI の動作への干渉を防ぐため、デフォルトでプロジェクトの `.env` ファイルからは自動的に除外されます。Qwen Code でこれらの変数を設定する必要がある場合は、`.qwen/.env` ファイルを使用してください。 +- **`DEBUG` または `DEBUG_MODE`**（下位ライブラリや CLI 自体でよく使われる）： + - `true` または `1` に設定すると、詳細なデバッグログを有効にします。トラブルシューティングに役立ちます。 + - **注意：** これらの変数は、CLI の動作に干渉するのを防ぐため、デフォルトでプロジェクトの `.env` ファイルからは自動的に除外されます。Qwen Code でこれらの変数を設定する必要がある場合は、`.qwen/.env` ファイルを使用してください。 - **`NO_COLOR`**： - - 任意の値に設定すると、CLI のすべてのカラー出力を無効にします。 + - 任意の値を設定すると、CLI のすべてのカラー出力を無効にします。 - **`CLI_TITLE`**： - - 文字列に設定すると、CLI のタイトルをカスタマイズできます。 + - 文字列を設定すると、CLI のタイトルをカスタマイズできます。 - **`CODE_ASSIST_ENDPOINT`**： - コードアシストサーバーのエンドポイントを指定します。 - 開発やテストに役立ちます。 @@ -354,17 +354,17 @@ CLI は `.env` ファイルから自動的に環境変数を読み込みます ## コマンドライン引数 -CLI 実行時に直接渡される引数は、そのセッションにおいて他の設定を上書きできます。 +CLI 実行時に直接渡された引数は、そのセッションにおいて他の設定を上書きできます。 - **`--model `** (**`-m `**): - このセッションで使用する Gemini モデルを指定します。 - 例: `npm start -- --model gemini-1.5-pro-latest` - **`--prompt `** (**`-p `**): - - プロンプトを直接コマンドに渡すために使用します。これにより、Qwen Code が非インタラクティブモードで起動します。 + - プロンプトを直接コマンドに渡すために使用します。これにより、Qwen Code は非対話モードで起動されます。 - **`--prompt-interactive `** (**`-i `**): - - 指定されたプロンプトを初期入力としてインタラクティブセッションを開始します。 - - プロンプトはセッション内で処理され、事前に処理されることはありません。 - - stdin からのパイプ入力時には使用できません。 + - 指定したプロンプトを初期入力として対話セッションを開始します。 + - プロンプトは対話セッション内で処理され、セッション開始前ではありません。 + - stdin からのパイプ入力がある場合は使用できません。 - 例: `qwen -i "explain this code"` - **`--sandbox`** (**`-s`**): - このセッションでサンドボックスモードを有効にします。 @@ -373,13 +373,20 @@ CLI 実行時に直接渡される引数は、そのセッションにおいて - **`--debug`** (**`-d`**): - このセッションでデバッグモードを有効にし、より詳細な出力を提供します。 - **`--all-files`** (**`-a`**): - - 設定すると、現在のディレクトリ内のすべてのファイルを再帰的にプロンプトのコンテキストに含めます。 + - 設定されている場合、現在のディレクトリ内のすべてのファイルを再帰的にプロンプトのコンテキストに含めます。 - **`--help`** (または **`-h`**): - コマンドライン引数に関するヘルプ情報を表示します。 - **`--show-memory-usage`**: - 現在のメモリ使用量を表示します。 - **`--yolo`**: - - YOLO モードを有効にし、すべてのツール呼び出しを自動的に承認します。 + - YOLO モードを有効にし、すべてのツール呼び出しを自動で承認します。 +- **`--approval-mode `**: + - ツール呼び出しの承認モードを設定します。利用可能なモード: + - `default`: 各ツール呼び出しで承認を求める（デフォルトの動作） + - `auto_edit`: 編集系ツール（replace、write_file）は自動承認し、それ以外は承認を求める + - `yolo`: すべてのツール呼び出しを自動承認（`--yolo` と同等） + - `--yolo` と同時に使用することはできません。新しい統一アプローチでは、`--yolo` の代わりに `--approval-mode=yolo` を使用してください。 + - 例: `qwen --approval-mode auto_edit` - **`--telemetry`**: - [telemetry](../telemetry.md) を有効にします。 - **`--telemetry-target`**: @@ -391,17 +398,17 @@ CLI 実行時に直接渡される引数は、そのセッションにおいて - **`--checkpointing`**: - [checkpointing](../checkpointing.md) を有効にします。 - **`--extensions `** (**`-e `**): - - セッションで使用する拡張機能のリストを指定します。指定しない場合、利用可能なすべての拡張機能が使用されます。 + - セッションで使用する拡張機能のリストを指定します。指定がない場合、利用可能なすべての拡張機能が使用されます。 - 特殊なキーワード `qwen -e none` を使用して、すべての拡張機能を無効にできます。 - 例: `qwen -e my-extension -e my-other-extension` - **`--list-extensions`** (**`-l`**): - 利用可能なすべての拡張機能をリスト表示して終了します。 - **`--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` - **`--version`**: @@ -414,13 +421,13 @@ CLI 実行時に直接渡される引数は、そのセッションにおいて ## コンテキストファイル（階層的な指示コンテキスト） -CLI の**動作**設定というわけではありませんが、コンテキストファイル（デフォルトでは `QWEN.md` ですが、`contextFileName` 設定で変更可能）は、**指示コンテキスト**（「メモリ」とも呼ばれます）の設定において非常に重要です。この強力な機能により、プロジェクト固有の指示、コーディングスタイルガイド、または関連する背景情報を AI に提供し、あなたのニーズにより適した正確な応答を得ることができます。CLI には、現在読み込まれているコンテキストファイル数をフッターに表示する UI 要素などがあり、アクティブなコンテキストの状態を確認できます。 +CLI の**動作**設定というわけではありませんが、コンテキストファイル（デフォルトでは `QWEN.md` ですが、`contextFileName` 設定で変更可能）は、**指示コンテキスト**（「メモリ」とも呼ばれます）を設定するために非常に重要です。この強力な機能により、プロジェクト固有の指示、コーディングスタイルガイド、または関連する背景情報を AI に提供でき、あなたのニーズにより適した正確な応答が得られるようになります。CLI には、フッターにロードされたコンテキストファイル数を表示する UI 要素などがあり、現在のコンテキスト状態を確認できます。 -- **目的：** これらの Markdown ファイルには、Gemini モデルとのやり取り中に参照してほしい指示、ガイドライン、またはコンテキスト情報を記述します。システムは、この指示コンテキストを階層的に管理するように設計されています。 +- **目的：** これらの Markdown ファイルには、Gemini モデルとのやり取り中に参照してほしい指示、ガイドライン、またはコンテキスト情報を記述します。この指示コンテキストは、階層的に管理されるように設計されています。 ### コンテキストファイルの例（例：`QWEN.md`） -以下は、TypeScriptプロジェクトのルートにあるコンテキストファイルが含む可能性のある概念的な例です： +以下は、TypeScriptプロジェクトのルートにあるコンテキストファイルが含むかもしれない内容の概念的な例です： ```markdown @@ -429,64 +436,64 @@ CLI の**動作**設定というわけではありませんが、コンテキス ## 一般的な指示: - 新しいTypeScriptコードを生成する際は、既存のコーディングスタイルに従ってください。 -- 新しい関数やクラスには、必ずJSDocコメントを付与してください。 -- 適切な場所では、関数型プログラミングのパラダイムを優先してください。 -- すべてのコードは、TypeScript 5.0およびNode.js 20+との互換性を保つ必要があります。 +- すべての新しい関数とクラスにはJSDocコメントを付与してください。 +- 適切な場所では関数型プログラミングのパラダイムを優先してください。 +- すべてのコードはTypeScript 5.0およびNode.js 20+との互換性を保つ必要があります。 ## コーディングスタイル: - インデントにはスペース2つを使用してください。 - インターフェース名の先頭には`I`を付けてください（例：`IUserService`）。 -- クラスのプライベートメンバーの先頭にはアンダースコア（`_`）を付けてください。 -- 常に厳密等価演算子（`===`および`!==`）を使用してください。 +- privateなクラスメンバの先頭にはアンダースコア（`_`）を付けてください。 +- 常に厳密等価演算子（`===`と`!==`）を使用してください。 ## 特定のコンポーネント: `src/api/client.ts` -- このファイルは、すべての外部APIリクエストを処理します。 -- 新しいAPI呼び出し関数を追加する際は、堅牢なエラーハンドリングとロギングを必ず含めてください。 -- すべてのGETリクエストには、既存の`fetchWithRetry`ユーティリティを使用してください。 +- このファイルはすべての外部APIリクエストを処理します。 +- 新しいAPI呼び出し関数を追加する際は、堅牢なエラーハンドリングとロギングを含めるようにしてください。 +- すべてのGETリクエストには既存の`fetchWithRetry`ユーティリティを使用してください。 ```markdown ## 依存関係について: -- 新しい外部依存関係の導入は、どうしても必要な場合を除き避けてください。 +- 必要がない限り、新しい外部依存関係の導入は避けてください。 - 新しい依存関係が必要な場合は、その理由を明記してください。 +``` -この例は、プロジェクト全体のコンテキスト情報、特定のコーディング規約、特定のファイルやコンポーネントに関する注意書きなどをどのように提供できるかを示しています。コンテキストファイルがどれだけ関連性が高く、正確であるかによって、AIがどれだけ効果的に支援できるかが決まります。プロジェクト固有のコンテキストファイルの作成を強く推奨します。これにより、プロジェクト内での規約やコンテキストを確立できます。 +この例は、プロジェクト全体のコンテキスト情報や特定のコーディング規約、特定のファイルやコンポーネントに関する注意書きなどをどのように提供できるかを示しています。コンテキストファイルがどれだけ関連性があり、正確であるかが重要であり、それがAIによる支援の質を左右します。プロジェクト固有のコンテキストファイルの作成を強く推奨します。これにより、プロジェクト内での規約やコンテキストを確立できます。 -- **階層的な読み込みと優先順位:** CLIは、複数の場所からコンテキストファイル（例: `QWEN.md`）を読み込むことで、洗練された階層的なメモリシステムを実装しています。このリストの下位（より具体的な）ファイルの内容は、通常、上位（より一般的な）ファイルの内容を上書きまたは補完します。結合順序や最終的なコンテキストは、`/memory show` コマンドで確認できます。一般的な読み込み順序は以下の通りです： +- **階層的な読み込みと優先順位:** 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表示:** 見つかったすべてのコンテキストファイルの内容は結合され（元の場所とパスを示すセパレータ付き）、システムプロンプトの一部として提供されます。CLIのフッターには読み込まれたコンテキストファイルの数が表示され、現在アクティブな指示コンテキストを視覚的に確認できます。 + - 場所: 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 refresh` を使用して、すべての設定された場所からすべてのコンテキストファイルを強制的に再スキャンおよび再読み込みできます。これにより、AIの指示コンテキストが更新されます。 + - `/memory show` を使用して、現在読み込まれている結合された指示コンテキストを表示し、AIが使用している階層と内容を確認できます。 - `/memory` コマンドとそのサブコマンド（`show` および `refresh`）の詳細については、[Commands documentation](./commands.md#memory) を参照してください。 -これらの設定レイヤーとコンテキストファイルの階層構造を理解し活用することで、AIのメモリを効果的に管理し、Qwen Codeの応答をあなたの特定のニーズやプロジェクトに合わせて調整できます。 -``` +これらの設定レイヤーとコンテキストファイルの階層構造を理解し活用することで、AIのメモリを効果的に管理し、Qwen Codeの応答を特定のニーズやプロジェクトに合わせて調整できます。 -## Sandboxing +## サンドボックス -Qwen Code は、システムを保護するために、サンドボックス環境内で潜在的に危険な操作（シェルコマンドやファイルの変更など）を実行できます。 +Qwen Code は、システムを保護するために、潜在的に安全でない操作（シェルコマンドやファイルの変更など）をサンドボックス環境内で実行できます。 -サンドボックス機能はデフォルトでは無効になっていますが、以下の方法で有効にできます： +サンドボックスはデフォルトでは無効になっていますが、以下の方法で有効にできます： - `--sandbox` または `-s` フラグを使用する -- `GEMI_SANDBOX` 環境変数を設定する -- `--yolo` モードではデフォルトでサンドボックスが有効になっています +- `GEMINI_SANDBOX` 環境変数を設定する +- `--yolo` または `--approval-mode=yolo` を使用する場合、デフォルトでサンドボックスが有効になります デフォルトでは、事前にビルドされた `qwen-code-sandbox` Docker イメージを使用します。 -プロジェクト固有のサンドボックス要件がある場合は、プロジェクトのルートディレクトリに `.qwen/sandbox.Dockerfile` というカスタム Dockerfile を作成できます。この Dockerfile はベースとなるサンドボックスイメージを元に作成できます： +プロジェクト固有のサンドボックス要件がある場合は、プロジェクトのルートディレクトリに `.qwen/sandbox.Dockerfile` というカスタム Dockerfile を作成できます。この Dockerfile はベースとなるサンドボックスイメージを元にできます： ```dockerfile FROM qwen-code-sandbox @@ -501,7 +508,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 @@ -509,23 +516,23 @@ BUILD_SANDBOX=1 qwen -s ## 使用統計 -Qwen Code の改善のために、匿名化された使用統計情報を収集しています。このデータは、CLI がどのように使われているかを理解し、一般的な問題を特定し、新機能の優先順位を決定するために役立ちます。 +Qwen Code の改善のために、匿名化された使用統計情報を収集しています。このデータは、CLI の使用状況の理解、一般的な問題の特定、新機能の優先順位付けに役立てています。 **収集する情報:** - **ツール呼び出し:** 呼び出されたツールの名前、成功または失敗の結果、実行にかかった時間を記録します。ツールに渡された引数や、ツールから返されたデータは収集しません。 -- **API リクエスト:** 各リクエストで使用されたモデル、リクエストの所要時間、成功したかどうかを記録します。プロンプトやレスポンスの内容は収集しません。 -- **セッション情報:** 有効になっているツールや承認モードなど、CLI の設定に関する情報を収集します。 +- **APIリクエスト:** 各リクエストで使用されたモデル、リクエストの所要時間、成功したかどうかを記録します。プロンプトやレスポンスの内容は収集しません。 +- **セッション情報:** 有効化されているツールや承認モードなど、CLI の設定に関する情報を収集します。 **収集しない情報:** -- **個人を特定できる情報 (PII):** 氏名、メールアドレス、API キーなど、個人を特定できる情報は一切収集しません。 -- **プロンプトおよびレスポンスの内容:** プロンプトの内容や、モデルからのレスポンス内容は記録しません。 -- **ファイルの内容:** CLI によって読み書きされたファイルの内容は記録しません。 +- **個人を特定できる情報 (PII):** 氏名、メールアドレス、APIキーなど、個人を特定できる情報は一切収集しません。 +- **プロンプトおよびレスポンスの内容:** ユーザーが入力したプロンプトや、モデルからのレスポンス内容は記録しません。 +- **ファイルの内容:** CLI が読み書きしたファイルの内容は記録しません。 -**オプトアウト方法:** +**使用統計の無効化方法:** -`settings.json` ファイルで `usageStatisticsEnabled` プロパティを `false` に設定することで、いつでも使用統計情報の収集をオプトアウトできます： +`settings.json` ファイルで `usageStatisticsEnabled` プロパティを `false` に設定することで、いつでも使用統計の収集を無効化できます: ```json { @@ -533,4 +540,4 @@ Qwen Code の改善のために、匿名化された使用統計情報を収集 } ``` -注意: 使用統計が有効になっている場合、イベントは Alibaba Cloud RUM 収集エンドポイントに送信されます。 \ No newline at end of file +注意: 使用統計が有効な場合、イベントは Alibaba Cloud RUM コレクションエンドポイントに送信されます。 \ No newline at end of file diff --git a/website/content/ja/deployment.md b/website/content/ja/deployment.md index af693324..9ab7696e 100644 --- a/website/content/ja/deployment.md +++ b/website/content/ja/deployment.md @@ -37,14 +37,14 @@ Qwen Code を実行するにはいくつかの方法があります。どの方 セキュリティと分離性を確保するために、Qwen Code はコンテナ内で実行できます。これは、CLI が副作用を伴う可能性のあるツールを実行する際のデフォルトの方法です。 -- **Registry から直接実行:** +- **Registry からの直接実行:** 公開されているサンドボックスイメージを直接実行できます。Docker のみが利用可能で CLI を実行したい環境で便利です。 ```bash - # 公開されているサンドボックスイメージを実行 - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.7 + # 公開されたサンドボックスイメージを実行 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.9 ``` -- **`--sandbox` フラグを使用:** - Qwen Code をローカルにインストール済みの場合（前述の標準インストール手順に従って）、サンドボックスコンテナ内で実行するよう指示できます。 +- **`--sandbox` フラグの使用:** + Qwen Code をローカルにインストール済みの場合（前述の標準インストール手順に従って）、サンドボックスコンテナ内で実行するように指示できます。 ```bash qwen --sandbox -y -p "your prompt here" ``` @@ -55,14 +55,15 @@ Qwen Code を実行するにはいくつかの方法があります。どの方 プロジェクトへのコントリビューターは、CLI をソースコードから直接実行することになるでしょう。 -- **開発モード:** - この方法ではホットリロードが有効で、開発中に便利です。 +- **開発モード：** + この方法ではホットリロードが有効になるため、開発中に便利です。 ```bash # リポジトリのルートから実行 npm run start ``` -- **本番環境に近いモード（リンクされたパッケージ）:** - この方法では、ローカルのパッケージをグローバルにリンクすることで、npm install -g したときと同じように動作します。本番環境でのローカルビルドのテストに便利です。 + +- **本番環境に近いモード（リンクされたパッケージ）：** + この方法では、ローカルのパッケージをグローバルにリンクすることで、npm でインストールしたときと同じように動作させることができます。ローカルビルドを本番ワークフローでテストするのに便利です。 ```bash # ローカルの cli パッケージをグローバルな node_modules にリンク @@ -90,20 +91,20 @@ npx https://github.com/QwenLM/qwen-code **NPM パッケージ** -Qwen Code プロジェクトは monorepo であり、コアパッケージを NPM レジストリに公開しています： +Qwen Code プロジェクトはモノレポで、コアパッケージを NPM レジストリに公開しています： -- `@qwen-code/qwen-code-core`: バックエンド。ロジックとツールの実行を担当。 +- `@qwen-code/qwen-code-core`: バックエンド。ロジックとツールの実行を処理します。 - `@qwen-code/qwen-code`: ユーザー向けのフロントエンド。 これらのパッケージは、標準インストール時やソースから Qwen Code を実行する際に使用されます。 -**ビルドとパッケージングのプロセス** +**ビルドとパッケージングプロセス** 配布チャネルに応じて、2 種類のビルドプロセスが使用されます： - **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` を使用して、アプリケーション全体とその依存関係を 1 つの自己完結型 JavaScript ファイルにバンドルします。このバンドルファイルはユーザーのマシン上でその場で生成され、リポジトリにはコミットされません。 +- **GitHub からの `npx` 実行:** GitHub から最新版の Qwen Code を直接実行する際は、`package.json` の `prepare` スクリプトによって別のプロセスが起動します。このスクリプトは `esbuild` を使ってアプリケーション全体とその依存関係を 1 つの自己完結型 JavaScript ファイルにバンドルします。このバンドルファイルはユーザーのマシン上でオンザフライで生成され、リポジトリにはコミットされません。 **Docker サンドボックスイメージ** diff --git a/website/content/ja/ide-integration.md b/website/content/ja/ide-integration.md new file mode 100644 index 00000000..ebae654e --- /dev/null +++ b/website/content/ja/ide-integration.md @@ -0,0 +1,141 @@ +# IDE Integration + +Gemini CLI は、IDE との連携により、よりシームレスでコンテキストを意識した体験を提供できます。この連携により、CLI はワークスペースをより適切に理解し、エディタ内でのネイティブな diff 機能などの強力な機能が利用可能になります。 + +現在サポートされている IDE は [Visual Studio Code](https://code.visualstudio.com/) のみで、VS Code 拡張機能に対応する他のエディタも含まれます。 + +## 機能 + +- **ワークスペースコンテキスト:** CLI は自動的にワークスペースの状況を把握し、より関連性が高く正確なレスポンスを提供します。このコンテキストには以下が含まれます： + - ワークスペース内で**最近アクセスした上位 10 個のファイル** + - 現在のカーソル位置 + - 選択中のテキスト（最大 16KB。それ以上は切り捨てられます） + +- **ネイティブな差分表示:** Gemini がコード変更を提案する際、IDE のネイティブな diff ビューア内で直接変更内容を確認できます。これにより、提案された変更をシームレスにレビュー、編集、承認または拒否することが可能になります。 + +- **VS Code コマンド:** VS Code のコマンドパレット（`Cmd+Shift+P` または `Ctrl+Shift+P`）から直接 Gemini CLI の機能にアクセスできます： + - `Gemini CLI: Run`: 統合ターミナルで新しい Gemini CLI セッションを開始します。 + - `Gemini CLI: Accept Diff`: アクティブな diff エディタ内の変更を承認します。 + - `Gemini CLI: Close Diff Editor`: 変更を拒否し、アクティブな diff エディタを閉じます。 + - `Gemini CLI: View Third-Party Notices`: 拡張機能のサードパーティ通知を表示します。 + +## インストールとセットアップ + +IDE連携のセットアップには3つの方法があります： + +### 1. 自動案内（推奨） + +サポートされているエディタ内でGemini CLIを実行すると、環境が自動的に検出され、接続を促す案内が表示されます。「Yes」と答えることで、必要なセットアップが自動的に実行され、関連するextensionのインストールと接続の有効化が行われます。 + +### 2. CLIからの手動インストール + +以前に案内を-dismissした場合や、手動でextensionをインストールしたい場合は、Gemini CLI内で以下のコマンドを実行できます： + +``` +/ide install +``` + +このコマンドは、使用しているIDEに適したextensionを見つけ出してインストールします。 + +### 3. マーケットプレイスからの手動インストール + +エクステンションは、マーケットプレイスから直接インストールすることもできます。 + +- **Visual Studio Code 向け:** [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=google.gemini-cli-vscode-ide-companion) からインストールしてください。 +- **VS Code フォーク向け:** VS Code のフォークをサポートするため、このエクステンションは [Open VSX Registry](https://open-vsx.org/extension/google/gemini-cli-vscode-ide-companion) にも公開されています。お使いのエディタの手順に従って、このレジストリからエクステンションをインストールしてください。 + +どのインストール方法を選んでも、インテグレーションが正しく有効化されるように、新しいターミナルウィンドウを開くことをおすすめします。インストールが完了したら、`/ide enable` を使って接続できます。 + +## 使い方 + +### 有効化と無効化 + +CLI から IDE 連携をコントロールできます： + +- IDE への接続を有効にするには、以下を実行します： + ``` + /ide enable + ``` +- 接続を無効にするには、以下を実行します： + ``` + /ide disable + ``` + +有効化すると、Gemini CLI は自動的に IDE companion extension への接続を試みます。 + +### ステータスの確認 + +接続ステータスを確認し、CLI が IDE から受け取ったコンテキストを表示するには、以下を実行します： + +``` +/ide status +``` + +接続されている場合、このコマンドは接続先の IDE と、認識している最近開いたファイルのリストを表示します。 + +（注：ファイルリストはワークスペース内の最近アクセスした 10 個のファイルに制限されており、ローカルディスク上のファイルのみが含まれます。） + +### Diff との連携 + +Gemini にファイルの変更を依頼すると、エディタ内で直接 diff ビューを開くことができます。 + +**diff を受け入れるには**、以下のいずれかの操作を行います： + +- diff エディタのタイトルバーにある**チェックマークアイコン**をクリックする +- ファイルを保存する（例：`Cmd+S` または `Ctrl+S`） +- Command Palette を開き、**Gemini CLI: Accept Diff** を実行する +- CLI でプロンプトが表示されたら `yes` と応答する + +**diff を拒否するには**、以下の操作を行います： + +- diff エディタのタイトルバーにある**'x' アイコン**をクリックする +- diff エディタのタブを閉じる +- Command Palette を開き、**Gemini CLI: Close Diff Editor** を実行する +- CLI でプロンプトが表示されたら `no` と応答する + +また、受け入れる前に diff ビュー内で**提案された変更を直接編集する**こともできます。 + +CLI で「Yes, allow always」を選択すると、変更は IDE に表示されなくなり、自動的に受け入れられるようになります。 + +## サンドボックス環境での使用 + +Gemini CLIをサンドボックス内で使用する場合、以下の点に注意してください： + +- **macOSの場合：** IDE連携機能は、IDE companion extensionと通信するためにネットワークアクセスを必要とします。ネットワークアクセスを許可するSeatbeltプロファイルを使用する必要があります。 +- **Dockerコンテナ内の場合：** Docker（またはPodman）コンテナ内でGemini CLIを実行する場合でも、ホストマシン上で動作しているVS Code extensionにIDE連携機能は接続できます。CLIは自動的に`host.docker.internal`上のIDEサーバーを見つけるように設定されています。通常、特別な設定は必要ありませんが、コンテナからホストへの接続を許可するようにDockerのネットワーク設定を確認する必要があるかもしれません。 + +## トラブルシューティング + +IDE連携機能で問題が発生した場合、以下によくあるエラーメッセージとその解決方法を示します。 + +### 接続エラー + +- **メッセージ:** `🔴 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.` + - **原因:** Gemini CLI が IDE に接続するために必要な環境変数（`GEMINI_CLI_IDE_WORKSPACE_PATH` または `GEMINI_CLI_IDE_SERVER_PORT`）を見つけられませんでした。これは通常、IDE companion extension が起動していないか、正しく初期化されていないことを意味します。 + - **解決方法:** + 1. IDE に **Gemini CLI Companion** extension がインストールされていて、有効になっていることを確認してください。 + 2. 新しい terminal window を IDE で開き、正しい環境変数が読み込まれるようにしてください。 + +- **メッセージ:** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` + - **原因:** IDE companion への接続が失われました。 + - **解決方法:** `/ide enable` を実行して再接続を試みてください。問題が続く場合は、新しい terminal window を開くか、IDE を再起動してください。 + +### 設定エラー + +- **メッセージ:** `🔴 Disconnected: Directory mismatch. Gemini CLI 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で開いているフォルダまたはワークスペースとは異なる場所にある。 + - **解決方法:** IDEで開いているのと同じディレクトリに`cd`して、CLIを再起動してください。 + +- **メッセージ:** `🔴 Disconnected: To use this feature, please open a single workspace folder in [IDE Name] and try again.` + - **原因:** IDEで複数のワークスペースフォルダが開いている、またはフォルダがまったく開かれていない。IDE連携機能が正しく動作するには、単一のルートワークスペースフォルダが必要です。 + - **解決方法:** IDEで単一のプロジェクトフォルダを開いて、CLIを再起動してください。 + +### 一般的なエラー + +- **メッセージ:** `IDE integration is not supported in your current environment. To use this feature, run Gemini CLI in one of these supported IDEs: [List of IDEs]` + - **原因:** サポートされている IDE 以外のターミナルまたは環境で Gemini CLI を実行しています。 + - **解決方法:** VS Code などのサポートされている IDE の統合ターミナルから Gemini CLI を実行してください。 + +- **メッセージ:** `No installer is available for [IDE Name]. Please install the IDE companion manually from its marketplace.` + - **原因:** `/ide install` を実行しましたが、CLI に該当の IDE 用の自動インストーラーが用意されていません。 + - **解決方法:** ご利用の IDE の拡張機能マーケットプレイスを開き、「Gemini CLI Companion」を検索して手動でインストールしてください。 \ No newline at end of file diff --git a/website/content/ja/index.md b/website/content/ja/index.md index 1afc30fb..32a5797b 100644 --- a/website/content/ja/index.md +++ b/website/content/ja/index.md @@ -8,31 +8,32 @@ Qwen Code は、高度なコードモデルの機能をあなたのターミナ ## ドキュメントのナビゲーション -このドキュメントは以下のセクションに分かれています： +このドキュメントは以下のセクションに整理されています： - **[実行とデプロイ](./deployment.md)：** Qwen Code を実行するための情報。 -- **[アーキテクチャ概要](./architecture.md)：** Qwen Code の高レベル設計、コンポーネントとその相互作用について理解できます。 +- **[アーキテクチャ概要](./architecture.md)：** コンポーネントとその相互作用を含む、Qwen Code の高レベル設計を理解します。 - **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 の詳細：** `packages/core` のドキュメント。 - - **[Core の紹介](./core/index.md)：** Core コンポーネントの概要。 - - **[Tools API](./core/tools-api.md)：** Core がツールを管理・公開する方法に関する情報。 +- **コアの詳細：** `packages/core` のドキュメント。 + - **[コアの紹介](./core/index.md)：** コアコンポーネントの概要。 + - **[Tools API](./core/tools-api.md)：** コアがツールを管理・公開する方法に関する情報。 - **ツール：** - **[ツールの概要](./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` ツールのドキュメント。 -- **[貢献と開発ガイド](../CONTRIBUTING.md)：** 貢献者および開発者のための情報。セットアップ、ビルド、テスト、コーディング規則などを含みます。 -- **[NPM Workspaces とパッケージ公開](./npm.md)：** プロジェクトのパッケージ管理と公開方法の詳細。 +- **[貢献と開発ガイド](../CONTRIBUTING.md)：** 設定、ビルド、テスト、コーディング規則など、貢献者および開発者向けの情報。 +- **[NPM Workspaces とパブリッシュ](./npm.md)：** プロジェクトのパッケージがどのように管理・公開されているかの詳細。 - **[トラブルシューティングガイド](./troubleshooting.md)：** よくある問題と FAQ の解決方法。 -- **[利用規約とプライバシー通知](./tos-privacy.md)：** Qwen Code の利用に適用される利用規約およびプライバシー通知に関する情報。 +- **[利用規約およびプライバシー通知](./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/integration-tests.md b/website/content/ja/integration-tests.md index 0ade814d..cde7cb49 100644 --- a/website/content/ja/integration-tests.md +++ b/website/content/ja/integration-tests.md @@ -1,18 +1,18 @@ -# 統合テスト +# 結合テスト -このドキュメントでは、本プロジェクトで使用されている統合テストフレームワークについて説明します。 +このドキュメントでは、本プロジェクトで使用されている結合テストフレームワークについて説明します。 ## 概要 -統合テストは、Qwen Code のエンドツーエンドの機能を検証するために設計されています。これらは制御された環境でビルドされたバイナリを実行し、ファイルシステムとやり取りする際に期待通りに動作するかを確認します。 +結合テストは、Qwen Code のエンドツーエンドの機能を検証するために設計されています。これらは制御された環境でビルドされたバイナリを実行し、ファイルシステムとやり取りする際の動作が期待通りであることを確認します。 -テストは `integration-tests` ディレクトリに配置されており、カスタムの test runner を使用して実行されます。 +テストは `integration-tests` ディレクトリに配置されており、カスタムのテストランナーを使って実行されます。 ## テストの実行方法 -統合テストは、デフォルトの `npm run test` コマンドでは実行されません。明示的に `npm run test:integration:all` スクリプトを使用して実行する必要があります。 +結合テストは、デフォルトの `npm run test` コマンドでは実行されません。明示的に `npm run test:integration:all` スクリプトを使って実行する必要があります。 -統合テストは以下のショートカットでも実行できます： +結合テストは以下のショートカットでも実行できます： ```bash npm run test:e2e @@ -61,58 +61,51 @@ npm run test:integration:sandbox:podman ## 診断 -インテグレーションテストランナーは、テスト失敗の追跡を支援するための診断オプションをいくつか提供しています。 +integration test runner は、テスト失敗の追跡を支援するための診断オプションをいくつか提供しています。 ### テスト出力の保持 テスト実行中に作成された一時ファイルを検査用に保持できます。これはファイルシステム操作に関する問題をデバッグするのに役立ちます。 -テスト出力を保持するには、`--keep-output` フラグを使用するか、`KEEP_OUTPUT` 環境変数を `true` に設定します。 - -```bash - -# フラグを使用 -npm run test:integration:sandbox:none -- --keep-output - -# 環境変数の使用 +テスト出力を保持するには、`KEEP_OUTPUT` 環境変数を `true` に設定します。 ```bash KEEP_OUTPUT=true npm run test:integration:sandbox:none ``` -出力を保持する場合、テストランナーはテスト実行用の一意のディレクトリパスを表示します。 +出力が保持される場合、test runner はテスト実行用の一意のディレクトリへのパスを出力します。 -### 詳細出力 (Verbose output) +### 詳細な出力 -より詳細なデバッグのために、`--verbose` フラグを使用すると、`qwen` コマンドのリアルタイム出力がコンソールにストリームされます。 +より詳細なデバッグ情報を得るには、`VERBOSE` 環境変数を `true` に設定してください。 ```bash -npm run test:integration:sandbox:none -- --verbose +VERBOSE=true npm run test:integration:sandbox:none ``` -同じコマンド内で `--verbose` と `--keep-output` を同時に使用した場合、出力はコンソールにストリームされると同時に、テストの一時ディレクトリ内のログファイルにも保存されます。 +同じコマンド内で `VERBOSE=true` と `KEEP_OUTPUT=true` を使用すると、出力はコンソールにストリームされると同時に、テストの一時ディレクトリ内のログファイルにも保存されます。 詳細出力は、ログの出力元を明確に識別できるようにフォーマットされています： ``` ---- TEST: : --- -... output from the qwen command ... ---- END TEST: : --- +--- TEST: : --- +... qwen コマンドからの出力 ... +--- END TEST: : --- ``` ## Linting とフォーマット -コードの品質と一貫性を確保するため、インテグレーションテストファイルはメインのビルドプロセスの一環として lint されます。手動で linter と自動修正を実行することも可能です。 +コードの品質と一貫性を保つために、インテグレーションテストファイルはメインのビルドプロセスの一環として lint されます。手動で linter と自動修正を実行することも可能です。 -### linter の実行 +### Linter の実行 -linting エラーをチェックするには、以下のコマンドを実行してください： +lint エラーをチェックするには、以下のコマンドを実行してください： ```bash npm run lint ``` -自動で修正可能な linting エラーを自動修正するには、コマンドに `:fix` フラグを追加してください： +`:fix` フラグをコマンドに含めると、修正可能な lint エラーを自動で修正できます： ```bash npm run lint:fix @@ -120,7 +113,7 @@ npm run lint:fix ## ディレクトリ構造 -統合テストでは、`.integration-tests` ディレクトリ内に各テスト実行用のユニークなディレクトリが作成されます。このディレクトリ内には各テストファイル用のサブディレクトリが作成され、さらにその中に各テストケース用のサブディレクトリが作成されます。 +統合テストは、`.integration-tests`ディレクトリ内に各テスト実行ごとに一意のディレクトリを作成します。このディレクトリ内には各テストファイルごとにサブディレクトリが作成され、さらにその中に各テストケースごとのサブディレクトリが作成されます。 この構造により、特定のテスト実行、ファイル、またはケースのアーティファクトを簡単に見つけることができます。 @@ -135,7 +128,7 @@ npm run lint:fix ## 継続的インテグレーション -インテグレーションテストが常に実行されるようにするため、`.github/workflows/e2e.yml` に GitHub Actions のワークフローが定義されています。このワークフローは、`main` ブランチに対するプルリクエストや、プルリクエストがマージキューに追加された際に、自動でインテグレーションテストを実行します。 +インテグレーションテストが常に実行されるようにするために、`.github/workflows/e2e.yml` に GitHub Actions のワークフローが定義されています。このワークフローは、`main` ブランチに対するプルリクエストや、プルリクエストがマージキューに追加された際に自動でインテグレーションテストを実行します。 ワークフローは異なるサンドボックス環境でテストを実行し、Qwen Code がそれぞれの環境で正しく動作することを確認します： diff --git a/website/content/ja/npm.md b/website/content/ja/npm.md index 5d75142a..26d572fc 100644 --- a/website/content/ja/npm.md +++ b/website/content/ja/npm.md @@ -6,7 +6,7 @@ これはQwen Codeのメインパッケージです。ユーザーインターフェース、コマンド解析、およびその他のすべてのユーザー向け機能を担当しています。 -このパッケージが公開される際には、単一の実行可能ファイルにバンドルされます。このバンドルには、`@qwen-code/qwen-code-core`を含むすべてのパッケージ依存関係が含まれます。つまり、ユーザーが`npm install -g @qwen-code/qwen-code`でパッケージをインストールしても、`npx @qwen-code/qwen-code`で直接実行しても、どちらの場合もこの単一の自己完結型実行ファイルを使用しています。 +このパッケージがpublishされる際、単一の実行可能ファイルにバンドルされます。このバンドルには、`@qwen-code/qwen-code-core`を含むすべてのパッケージ依存関係が含まれます。つまり、ユーザーが`npm install -g @qwen-code/qwen-code`でパッケージをインストールしても、`npx @qwen-code/qwen-code`で直接実行しても、この単一の自己完結型実行ファイルを使用していることになります。 ## `@qwen-code/qwen-code-core` @@ -26,7 +26,7 @@ 2. リストから **Release** ワークフローを選択します。 3. **Run workflow** ドロップダウンボタンをクリックします。 4. 必要な入力項目を記入します： - - **Version**: リリースする正確なバージョン（例：`v0.2.1`）。 + - **Version**: リリースする正確なバージョン（例: `v0.2.1`）。 - **Ref**: リリース元のブランチまたはコミット SHA（デフォルトは `main`）。 - **Dry Run**: ワークフローをテストのみで実行する場合は `true` のままにし、本番リリースする場合は `false` に設定します。 5. **Run workflow** をクリックします。 @@ -37,18 +37,18 @@ ### プロセス -毎日深夜0時（UTC）に、[Release workflow](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) がスケジュール通り自動実行されます。このワークフローは以下の手順を実行します： +毎日 UTC の真夜中（深夜 0 時）に、[Release workflow](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) がスケジュールに基づいて自動実行されます。このワークフローでは以下のステップが実行されます： 1. `main` ブランチから最新のコードをチェックアウトします。 -2. すべての依存関係をインストールします。 -3. `preflight` チェックと統合テストの全スイートを実行します。 -4. すべてのテストが成功した場合、次のナイトリー版のバージョン番号を計算します（例：`v0.2.1-nightly.20230101`）。 +2. すべての依存パッケージをインストールします。 +3. `preflight` チェックと統合テストをすべて実行します。 +4. すべてのテストに成功した場合、次の nightly バージョン番号を計算します（例：`v0.2.1-nightly.20230101`）。 5. パッケージをビルドし、`nightly` dist-tag 付きで npm に公開します。 -6. 最後に、ナイトリー版の GitHub Release を作成します。 +6. 最後に、nightly バージョンに対応する GitHub Release を作成します。 -### エラー処理 +### エラー発生時の処理 -ナイトリー・ワークフローのいずれかのステップが失敗した場合、リポジトリ内に `bug` および `nightly-failure` ラベル付きの新しい issue が自動的に作成されます。この issue には、簡単にデバッグできるように失敗したワークフロー実行へのリンクが含まれます。 +nightly ワークフローのいずれかのステップが失敗した場合、リポジトリ内に新しい issue が自動で作成されます。この issue には `bug` および `nightly-failure` のラベルが付与され、失敗したワークフロー実行へのリンクが含まれるため、デバッグが容易になります。 ### Nightly Build の使い方 @@ -58,67 +58,64 @@ npm install -g @qwen-code/qwen-code@nightly ``` -また、[release-docker.yml](../.gcp/release-docker.yaml) という Google Cloud Build を実行しています。これは、リリースに合わせて Sandbox 用の Docker イメージを公開するものです。サービスアカウントの権限が整理され次第、こちらも GH に移行し、メインのリリースファイルと統合される予定です。 +また、[release-docker.yml](../.gcp/release-docker.yml) という Google Cloud Build を実行しています。これは、リリースに合わせて Sandbox 用の Docker イメージを公開するものです。サービスアカウントの権限が整理され次第、こちらも GH に移行し、メインのリリースファイルと統合される予定です。 -### リリース後に行うこと +### リリース後のこと Workflow が正常に完了した後は、[GitHub Actions タブ](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) で進行状況を確認できます。完了したら以下の手順を行ってください： 1. リポジトリの [Pull Requests ページ](https://github.com/QwenLM/qwen-code/pulls) にアクセスします。 2. `release/vX.Y.Z` ブランチから `main` への Pull Request を新規作成します。 -3. Pull Request をレビューしてください（`package.json` ファイル内のバージョン更新のみを含むはずです）。問題がなければマージしてください。これにより `main` ブランチのバージョン情報が最新の状態に保たれます。 +3. Pull Request をレビューします（`package.json` ファイル内のバージョン更新のみを含むはずです）し、マージしてください。これにより `main` ブランチのバージョンが最新の状態に保たれます。 ## リリースの検証 -新しいリリースをプッシュした後は、パッケージが期待通りに動作することを確認するために、Smoke Testing を実行してください。これは、ローカルにパッケージをインストールし、一連のテストを実行して正しく機能していることを確認することで可能です。 +新しいリリースをプッシュした後は、パッケージが期待通りに動作することを確認するために、Smoke Testing を実施してください。これは、ローカルにパッケージをインストールし、一連のテストを実行することで、正しく機能しているかを確認できます。 - `npx -y @qwen-code/qwen-code@latest --version`：rc や dev タグを使用していない場合、プッシュが成功したことを確認できます。 - `npx -y @qwen-code/qwen-code@ --version`：タグが正しくプッシュされたことを確認できます。 -- _これはローカル環境に破壊的影響を与える操作です_：`npm uninstall @qwen-code/qwen-code && npm uninstall -g @qwen-code/qwen-code && npm cache clean --force && npm install @qwen-code/qwen-code@` -- 基本的な llm コマンドやツールをいくつか実行して、パッケージが期待通りに動作することを確認する Smoke Testing を推奨します。将来的にはこれをさらに体系化する予定です。 +- _これはローカル環境に破壊的です_：`npm uninstall @qwen-code/qwen-code && npm uninstall -g @qwen-code/qwen-code && npm cache clean --force && npm install @qwen-code/qwen-code@` +- 基本的な llm コマンドやツールをいくつか実行して確認する Smoke Testing を推奨します。これにより、パッケージが期待通りに動作しているかを確認できます。将来的には、これをさらに形式化する予定です。 ## バージョン変更をマージするべきか、しないべきか？ -現在または過去のコミットからパッチリリースやホットフィックスリリースを作成する上記のパターンでは、リポジトリは以下の状態になります： +現在または古いコミットからパッチリリースやホットフィックスリリースを作成する上記のパターンでは、リポジトリは以下の状態になります： -1. タグ (`vX.Y.Z-patch.1`): このタグは、リリースしたい安定版コードを含むmainブランチ上の元のコミットを正しく指しています。これは非常に重要です。このタグをチェックアウトする人は、公開されたコードそのものを取得できます。 -2. ブランチ (`release-vX.Y.Z-patch.1`): このブランチは、タグ付けされたコミットの上に1つの新しいコミットを含んでいます。この新しいコミットには、package.json（およびpackage-lock.jsonなどの関連ファイル）のバージョン番号変更のみが含まれています。 +1. タグ (`vX.Y.Z-patch.1`): このタグは、リリースしたい安定版コードを含む main ブランチ上の元のコミットを正しく指しています。これは非常に重要です。このタグをチェックアウトする人は、公開されたコードそのものを取得できます。 +2. ブランチ (`release-vX.Y.Z-patch.1`): このブランチは、タグ付けされたコミットの上に1つの新しいコミットを含んでいます。その新しいコミットには、package.json（および package-lock.json などの関連ファイル）のバージョン番号変更のみが含まれています。 -このような分離は良いことです。メインブランチの履歴をリリース固有のバージョンアップで汚すことなく、マージするタイミングを自分で決めることができます。 +このような分離は良いことです。メインブランチの履歴をリリース固有のバージョンアップで汚すことなく、マージするタイミングを自分で決められるからです。 -これが重要な判断ポイントであり、リリースの性質によって完全に異なります。 +これが重要な判断ポイントであり、リリースの性質によって完全に左右されます。 -### Stable パッチとホットフィックスのマージバック +### Stable Patch および Hotfix リリースは main にマージバックする -Stable パッチやホットフィックスリリースを行う際は、ほぼ常に `release-` ブランチを `main` ブランチにマージバックする必要があります。 +Stable patch や hotfix リリースでは、ほぼ必ず `release-` ブランチを `main` にマージバックする必要があります。 -- **なぜ必要なのか？** - 主な理由は、main ブランチの package.json 内のバージョン情報を更新するためです。例えば、古いコミットから v1.2.1 をリリースしたにもかかわらず、バージョン更新を main にマージしなければ、main ブランチの package.json には依然として `"version": "1.2.0"` と記載されたままです。次の開発者が次の機能リリース（例：v1.3.0）の作業を開始する際、誤った古いバージョン番号を持つコードベースからブランチを作成することになり、混乱を招いたり、後で手動でバージョンを修正する必要が出てきます。 - -- **手順:** - release-v1.2.1 ブランチを作成し、パッケージの公開が成功した後、release-v1.2.1 を main にマージするためのプルリクエストを作成してください。この PR には `"chore: bump version to v1.2.1"` という1つのコミットのみが含まれます。これはシンプルでクリーンな統合方法であり、main ブランチを最新のリリースバージョンと同期した状態に保ちます。 +- **なぜ？** 主な理由は、main の package.json のバージョン情報を更新するためです。古いコミットから v1.2.1 をリリースしたけれども、バージョンアップの変更を main にマージし忘れると、main ブランチの package.json にはまだ `"version": "1.2.0"` と記載されたままになります。次の開発者が次の機能リリース（v1.3.0）の作業を開始する際、誤った古いバージョン番号を持つコードベースからブランチを作成することになり、混乱を招いたり、後で手動でバージョンを修正する必要が出てきます。 +- **手順:** release-v1.2.1 ブランチを作成し、パッケージの公開が成功した後、release-v1.2.1 を main にマージするための pull request を作成してください。この PR には `"chore: bump version to v1.2.1"` という1つのコミットのみが含まれます。これは main ブランチを最新リリースバージョンと同期させるための、クリーンでシンプルな統合です。 ### プレリリース（RC、Beta、Dev）では main へのマージをしない 通常、プレリリース用のリリースブランチは `main` にマージしません。 -- **理由**: プレリリースバージョン（例: v1.3.0-rc.1、v1.3.0-rc.2）は、定義上、不安定で一時的なものです。リリース候補（RC）のためのバージョン更新を一連のコミットで `main` の履歴に残したくはありません。`main` の package.json には RC ではなく、最新の安定版リリースのバージョンが反映されているべきです。 -- **プロセス**: release-v1.3.0-rc.1 ブランチを作成し、`npm publish --tag rc` を実行します。その後、ブランチの役目は終わりです。そのまま削除して問題ありません。RC のコード自体はすでに `main`（または feature ブランチ）に存在しているため、機能的なコードは失われません。リリースブランチは、バージョン番号を一時的に載せるためだけの「手段」に過ぎません。 +- **理由**: プレリリースバージョン（例: v1.3.0-rc.1、v1.3.0-rc.2）は、定義上、安定版ではないため、一時的なものです。リリース候補（RC）のためのバージョン更新を複数回 `main` の履歴に残すのは避けるべきです。`main` の package.json には RC ではなく、最新の安定版リリースのバージョンが反映されているべきです。 +- **プロセス**: `release-v1.3.0-rc.1` ブランチが作成され、`npm publish --tag rc` が実行されたら、そのブランチの役目は終わりです。そのまま削除して問題ありません。RC のコード自体はすでに `main`（または feature ブランチ）に存在しているため、機能的なコードは失われません。リリースブランチは、バージョン番号を扱う一時的な手段に過ぎません。 ## ローカルでのテストと検証：パッケージングおよび公開プロセスの変更 -NPM への公開や GitHub リリースを作成することなく、リリースプロセスをテストする必要がある場合は、GitHub UI からワークフローを手動でトリガーできます。 +実際に NPM に公開したり、GitHub リリースを作成したりすることなくリリースプロセスをテストする必要がある場合は、GitHub UI からワークフローを手動でトリガーできます。 -1. リポジトリの [Actions タブ](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) にアクセスします。 +1. リポジトリの [Actions タブ](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) に移動します。 2. 「Run workflow」ドロップダウンをクリックします。 3. `dry_run` オプションをチェックしたまま（`true` のまま）にします。 4. 「Run workflow」ボタンをクリックします。 -これにより、リリースプロセス全体が実行されますが、`npm publish` および `gh release create` ステップはスキップされます。ワークフローのログを確認して、すべてが期待通りに動作していることを確認できます。 +これにより、リリースプロセス全体が実行されますが、`npm publish` および `gh release create` ステップはスキップされます。ワークフローのログを確認して、すべてが期待通りに動作していることを検証できます。 -パッケージングおよび公開プロセスへの変更をコミットする前に、ローカルでテストを行うことが重要です。これにより、パッケージが正しく公開され、ユーザーによってインストールされた際に期待通りに動作することを保証できます。 +パッケージングおよび公開プロセスへの変更をコミットする前に、ローカルでテストを行うことは非常に重要です。これにより、パッケージが正しく公開され、ユーザーによってインストールされた際に期待通りに動作することを保証できます。 -変更を検証するには、公開プロセスの dry run を実行できます。これにより、npm レジストリに実際にパッケージを公開せずに、公開プロセスをシミュレートできます。 +変更内容を検証するには、公開プロセスのドライランを実行できます。これにより、npm レジストリに実際にパッケージを公開せずに、公開プロセスをシミュレートできます。 ```bash npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run @@ -131,19 +128,19 @@ npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME=" 3. npm に公開される予定のパッケージ tarball を作成します。 4. 公開される予定のパッケージのサマリーを表示します。 -生成された tarball を確認して、正しいファイルが含まれていること、および `package.json` ファイルが正しく更新されていることを確認できます。tarball は各パッケージディレクトリのルートに作成されます（例：`packages/cli/google-gemini-cli-0.1.6.tgz`）。 +生成された tarball を確認して、正しいファイルが含まれていること、および `package.json` ファイルが正しく更新されていることを検証できます。tarball は各パッケージディレクトリのルートに作成されます（例：`packages/cli/google-gemini-cli-0.1.6.tgz`）。 -dry run を実行することで、パッケージングプロセスへの変更が正しいことを確認し、パッケージが正常に公開されることを確信できます。 +ドライランを実行することで、パッケージングプロセスへの変更が正しいことを確認し、パッケージが正常に公開されることに自信を持てるようになります。 ## リリースの詳細 -リリースプロセスの主な目的は、`packages/` ディレクトリ内のソースコードを取り出し、ビルドし、プロジェクトのルートに一時的な `bundle` ディレクトリを作成して、そこにクリーンで自己完結型のパッケージを構築することです。実際に NPM に公開されるのはこの `bundle` ディレクトリの中身です。 +リリースプロセスの主な目的は、`packages/` ディレクトリにあるソースコードをビルドし、プロジェクトのルートに一時的な `bundle` ディレクトリを作成して、クリーンで自己完結型のパッケージをアセンブルすることです。実際に NPM に公開されるのはこの `bundle` ディレクトリの中身です。 以下が主なステージです： ### ステージ 1: リリース前の健全性チェックとバージョン管理 -- **処理内容**: ファイルを移動する前に、プロジェクトが正常な状態にあることを確認します。これにはテスト、lint、型チェック（`npm run preflight`）が含まれます。ルートの `package.json` と `packages/cli/package.json` のバージョン番号が新しいリリースバージョンに更新されます。 +- **処理内容**: ファイルを移動する前に、プロジェクトが正常な状態であることを確認します。これにはテスト、lint、型チェック（`npm run preflight`）が含まれます。ルートの `package.json` と `packages/cli/package.json` のバージョン番号が新しいリリースバージョンに更新されます。 - **目的**: 高品質で動作するコードのみがリリースされるように保証します。バージョン管理は新しいリリースを示す最初のステップです。 ### ステージ 2: ソースコードのビルド @@ -152,42 +149,39 @@ dry run を実行することで、パッケージングプロセスへの変更 - **ファイルの移動**: - `packages/core/src/**/*.ts` → コンパイル → `packages/core/dist/` - `packages/cli/src/**/*.ts` → コンパイル → `packages/cli/dist/` -- **目的**: 開発中に書かれた TypeScript コードは、Node.js で実行できるプレーンな JavaScript に変換する必要があります。`cli` パッケージが `core` パッケージに依存しているため、まず `core` パッケージがビルドされます。 +- **目的**: 開発中に書かれた TypeScript コードは、Node.js で実行できるプレーンな JavaScript に変換する必要があります。`cli` パッケージが `core` パッケージに依存しているため、`core` パッケージが最初にビルドされます。 ### ステージ 3: 最終的な公開パッケージのアセンブル -これはファイルが最終的な公開形式に変換される最も重要なステージです。プロジェクトのルートに一時的な `bundle` フォルダが作成され、最終的なパッケージの内容が配置されます。 - -#### 1. `package.json` の変換 - -- **処理内容**: `packages/cli/` の `package.json` が読み込まれ、変更され、ルートの `bundle/` ディレクトリに書き込まれます。 -- **ファイルの移動**: `packages/cli/package.json` → （メモリ上で変換）→ `bundle/package.json` -- **目的**: 最終的な `package.json` は開発時に使用するものとは異なる必要があります。主な変更点： - - `devDependencies` を削除 - - ワークスペース固有の依存関係 `"dependencies": { "@gemini-cli/core": "workspace:*" }` を削除し、core コードが最終的な JavaScript ファイルに直接バンドルされるようにする - - `bin`、`main`、`files` フィールドが最終的なパッケージ構造内の正しい場所を指すようにする - -#### 2. JavaScript バンドルの作成 - -- **処理内容**: `packages/core/dist` と `packages/cli/dist` のビルド済み JavaScript が単一の実行可能な JavaScript ファイルにバンドルされます。 -- **ファイルの移動**: `packages/cli/dist/index.js` + `packages/core/dist/index.js` → （esbuild でバンドル）→ `bundle/gemini.js` （または類似の名前） -- **目的**: これにより、必要なすべてのアプリケーションコードを含む単一の最適化されたファイルが作成されます。core パッケージを NPM 上の別々の依存関係として保持する必要がなくなり、コードが直接含まれるため、パッケージが簡潔になります。 - -#### 3. 静的ファイルとサポートファイルのコピー - -- **処理内容**: ソースコードの一部ではないが、パッケージが正しく動作したり適切に記述されたりするために必要な必須ファイルが `bundle` ディレクトリにコピーされます。 -- **ファイルの移動**: - - `README.md` → `bundle/README.md` - - `LICENSE` → `bundle/LICENSE` - - `packages/cli/src/utils/*.sb` （サンドボックスプロファイル）→ `bundle/` -- **目的**: - - `README.md` と `LICENSE` は、すべての NPM パッケージに含めるべき標準的なファイルです。 - - サンドボックスプロファイル（.sb ファイル）は CLI のサンドボックス機能が機能するために必要な重要な実行時アセットです。これらは最終的な実行ファイルの隣に配置される必要があります。 +これはファイルが最終的な公開形式に変換・移動される最も重要なステージです。プロジェクトのルートに一時的な `bundle` フォルダが作成され、最終的なパッケージの内容が格納されます。 + +1. **`package.json` の変換**: + - **処理内容**: `packages/cli/` の `package.json` が読み込まれ、変更され、ルートの `bundle/` ディレクトリに書き込まれます。 + - **ファイルの移動**: `packages/cli/package.json` → （メモリ内変換）→ `bundle/package.json` + - **目的**: 最終的な `package.json` は開発時に使用するものとは異なる必要があります。主な変更点は以下の通りです： + - `devDependencies` の削除 + - ワークスペース固有の依存関係 `"dependencies": { "@gemini-cli/core": "workspace:*" }` の削除。`core` コードが最終的な JavaScript ファイルに直接バンドルされるようにします。 + - `bin`、`main`、`files` フィールドが最終的なパッケージ構造内の正しい場所を指すようにします。 + +2. **JavaScript バンドルの作成**: + - **処理内容**: `packages/core/dist` と `packages/cli/dist` のビルド済み JavaScript が、単一の実行可能な JavaScript ファイルにバンドルされます。 + - **ファイルの移動**: `packages/cli/dist/index.js` + `packages/core/dist/index.js` → （esbuild によるバンドル）→ `bundle/gemini.js`（または同様の名前） + - **目的**: これにより、必要なすべてのアプリケーションコードを含む単一の最適化されたファイルが作成されます。core パッケージを NPM 上の別々の依存関係として保持する必要がなくなり、コードが直接含まれるため、パッケージが簡潔になります。 + +3. **静的ファイルとサポートファイルのコピー**: + - **処理内容**: ソースコードの一部ではないが、パッケージが正しく動作したり適切に説明されたりするために必要な重要なファイルが `bundle` ディレクトリにコピーされます。 + - **ファイルの移動**: + - `README.md` → `bundle/README.md` + - `LICENSE` → `bundle/LICENSE` + - `packages/cli/src/utils/*.sb`（サンドボックスプロファイル）→ `bundle/` + - **目的**: + - `README.md` と `LICENSE` は、すべての NPM パッケージに含めるべき標準的なファイルです。 + - サンドボックスプロファイル（.sb ファイル）は CLI のサンドボックス機能が機能するために必要な重要な実行時アセットです。最終的な実行ファイルの隣に配置する必要があります。 ### ステージ 4: NPM への公開 - **処理内容**: ルートの `bundle` ディレクトリ内で `npm publish` コマンドが実行されます。 -- **目的**: `bundle` ディレクトリ内から `npm publish` を実行することで、ステージ 3 で慎重にアセンブルしたファイルのみが NPM レジストリにアップロードされます。これにより、ソースコード、テストファイル、開発設定が誤って公開されるのを防ぎ、ユーザー向けにクリーンで最小限のパッケージを提供できます。 +- **目的**: `bundle` ディレクトリ内から `npm publish` を実行することで、ステージ 3 で慎重にアセンブルしたファイルのみが NPM レジストリにアップロードされます。これにより、ソースコード、テストファイル、開発設定などが誤って公開されるのを防ぎ、ユーザー向けにクリーンで最小限のパッケージを提供できます。 ## ファイルフローの概要 @@ -245,6 +239,6 @@ graph TD ### Workspaces の利点 -- **依存関係管理の簡素化**: プロジェクトのルートから `npm install` を実行すると、ワークスペース内のすべてのパッケージの依存関係がインストールされ、相互にリンクされます。つまり、各パッケージのディレクトリでそれぞれ `npm install` を実行する必要がないということです。 -- **自動リンク**: ワークスペース内のパッケージは互いに依存できます。`npm install` を実行すると、NPM はパッケージ間のシンボリックリンクを自動的に作成します。これにより、あるパッケージに変更を加えると、それに依存する他のパッケージからすぐにその変更を利用できるようになります。 -- **スクリプト実行の簡素化**: ルートプロジェクトから `--workspace` フラグを使って、任意のパッケージ内のスクリプトを実行できます。例えば、`cli` パッケージの `build` スクリプトを実行するには、`npm run build --workspace @google/gemini-cli` とします。 \ No newline at end of file +- **依存関係管理の簡素化**: プロジェクトのルートから `npm install` を実行すると、ワークスペース内のすべてのパッケージの依存関係がインストールされ、それらが相互にリンクされます。つまり、各パッケージのディレクトリで `npm install` を実行する必要がないということです。 +- **自動リンク**: ワークスペース内のパッケージは、互いに依存関係を持つことができます。`npm install` を実行すると、NPM はパッケージ間のシンボリックリンクを自動的に作成します。これにより、あるパッケージに変更を加えると、そのパッケージに依存する他のパッケージですぐにその変更を利用できるようになります。 +- **スクリプト実行の簡素化**: `--workspace` フラグを使用して、プロジェクトのルートから任意のパッケージ内のスクリプトを実行できます。例えば、`cli` パッケージの `build` スクリプトを実行するには、`npm run build --workspace @google/gemini-cli` と実行します。 \ No newline at end of file diff --git a/website/content/ja/tools/file-system.md b/website/content/ja/tools/file-system.md index f9a01041..f74bb910 100644 --- a/website/content/ja/tools/file-system.md +++ b/website/content/ja/tools/file-system.md @@ -1,12 +1,12 @@ # Qwen Code ファイルシステムツール -Qwen Code は、ローカルファイルシステムとやり取りするための包括的なツールスイートを提供します。これらのツールにより、モデルはファイルやディレクトリの読み書き、一覧表示、検索、変更などの操作を実行できます。すべての操作はユーザーの管理下にあり、通常、機密性の高い操作については確認が求められます。 +Qwen Code は、ローカルファイルシステムとやり取りするための包括的なツールスイートを提供します。これらのツールにより、モデルはファイルやディレクトリの読み書き、一覧表示、検索、変更などの操作を行うことができます。すべての操作はユーザーの管理下で行われ、通常は機密性の高い操作に対して確認が求められます。 -**注意:** すべてのファイルシステムツールは、セキュリティのために `rootDirectory`（通常は CLI を起動した現在の作業ディレクトリ）内で動作します。これらのツールに指定するパスは、一般的に絶対パスであるか、またはこのルートディレクトリからの相対パスとして解決されます。 +**注意:** すべてのファイルシステムツールは、セキュリティのために `rootDirectory`（通常は CLI を起動したカレントワーキングディレクトリ）内で動作します。これらのツールに指定するパスは、一般的に絶対パスであるか、またはこのルートディレクトリからの相対パスとして解決されます。 ## 1. `list_directory` (ReadFolder) -`list_directory` は、指定されたディレクトリパス直下にあるファイルとサブディレクトリの名前を一覧表示します。オプションで、指定された glob パターンに一致するエントリを無視することもできます。 +`list_directory` は、指定されたディレクトリパス直下のファイルとサブディレクトリの名前を一覧表示します。オプションで、指定された glob パターンに一致するエントリを無視することもできます。 - **ツール名:** `list_directory` - **表示名:** ReadFolder @@ -14,11 +14,11 @@ Qwen Code は、ローカルファイルシステムとやり取りするため - **パラメータ:** - `path` (string, 必須): 一覧を表示するディレクトリの絶対パス。 - `ignore` (string の配列, オプション): 一覧から除外する glob パターンのリスト（例: `["*.log", ".git"]`）。 - - `respect_git_ignore` (boolean, オプション): ファイルを一覧表示する際に `.gitignore` パターンを尊重するかどうか。デフォルトは `true`。 + - `respect_git_ignore` (boolean, オプション): ファイル一覧表示時に `.gitignore` パターンを尊重するかどうか。デフォルトは `true`。 - **動作:** - - ファイル名とディレクトリ名のリストを返します。 + - ファイルとディレクトリの名前のリストを返します。 - 各エントリがディレクトリかどうかを示します。 - - ディレクトリを先に、その後アルファベット順にエントリをソートします。 + - エントリをディレクトリを先に、その後アルファベット順にソートします。 - **出力 (`llmContent`):** 以下のような文字列: `Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png` - **確認:** なし。 @@ -31,14 +31,14 @@ Qwen Code は、ローカルファイルシステムとやり取りするため - **ファイル:** `read-file.ts` - **パラメータ:** - `path` (string, 必須): 読み込むファイルの絶対パス。 - - `offset` (number, 任意): テキストファイルの場合、読み込みを開始する0始まりの行番号。`limit` が設定されている必要があります。 - - `limit` (number, 任意): テキストファイルの場合、読み込む最大行数。省略された場合、デフォルトの最大行数（例: 2000行）または可能であればファイル全体を読み込みます。 + - `offset` (number, 任意): テキストファイルにおいて、読み込みを開始する0から始まる行番号。`limit` が設定されている必要があります。 + - `limit` (number, 任意): テキストファイルにおいて、読み込む最大行数。省略された場合、デフォルトの最大行数（例: 2000行）または可能であればファイル全体を読み込みます。 - **動作:** - - テキストファイルの場合: 内容を返却します。`offset` と `limit` が指定された場合は、その範囲の行のみを返却します。行数制限または1行の長さ制限により内容が切り捨てられた場合はその旨を示します。 - - 画像および PDF ファイルの場合: モデルが処理できる形式の base64 エンコードされたデータ構造としてファイル内容を返却します。 + - テキストファイルの場合: 内容を返却します。`offset` と `limit` が指定された場合は、その範囲の行のみを返却します。行数制限や1行の長さ制限により内容が切り捨てられた場合はその旨を示します。 + - 画像および PDF ファイルの場合: モデルが処理できるように、base64 エンコードされたデータ構造としてファイル内容を返却します。 - その他のバイナリファイルの場合: 識別を試み、スキップして汎用的なバイナリファイルであることを示すメッセージを返却します。 -- **出力:** (`llmContent`): - - テキストファイルの場合: ファイル内容。切り捨てが発生した場合は先頭に切り捨てメッセージが付加されます（例: `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`）。 +- **出力:** (`llmContent`) + - テキストファイルの場合: ファイルの内容。切り捨てが発生した場合は冒頭にメッセージが付加されます（例: `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`）。 - 画像/PDF ファイルの場合: `mimeType` と base64 の `data` を含む `inlineData` オブジェクト（例: `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`）。 - その他のバイナリファイルの場合: `Cannot display content of binary file: /path/to/data.bin` のようなメッセージ。 - **確認:** なし。 @@ -51,48 +51,51 @@ Qwen Code は、ローカルファイルシステムとやり取りするため - **表示名:** WriteFile - **ファイル:** `write-file.ts` - **パラメータ:** - - `file_path` (string, 必須): 書き込み先ファイルの絶対パス - - `content` (string, 必須): ファイルに書き込む内容 + - `file_path` (string, 必須): 書き込み先ファイルの絶対パス。 + - `content` (string, 必須): ファイルに書き込む内容。 - **動作:** - - 指定された `content` を `file_path` に書き込みます - - 親ディレクトリが存在しない場合は作成します -- **出力 (`llmContent`):** 成功メッセージ、例: `Successfully overwrote file: /path/to/your/file.txt` または `Successfully created and wrote to new file: /path/to/new/file.txt` -- **確認:** あり。変更内容の差分を表示し、書き込み前にユーザーの承認を求めます + - 指定された `content` を `file_path` に書き込みます。 + - 親ディレクトリが存在しない場合は作成します。 +- **出力 (`llmContent`):** 成功メッセージ、例: `Successfully overwrote file: /path/to/your/file.txt` または `Successfully created and wrote to new file: /path/to/new/file.txt`。 +- **確認:** あり。変更内容の差分を表示し、書き込み前にユーザーの承認を求めます。 ## 4. `glob` (FindFiles) -`glob` は特定の glob パターン（例: `src/**/*.ts`、`*.md`）に一致するファイルを検索し、最終更新日時順（新しい順）にソートされた絶対パスを返します。 +`glob` は特定の glob パターン（例: `src/**/*.ts`、`*.md`）に一致するファイルを検索し、絶対パスのリストを変更時刻順（新しい順）にソートして返します。 - **ツール名:** `glob` - **表示名:** FindFiles - **ファイル:** `glob.ts` - **パラメータ:** - `pattern` (string, 必須): マッチさせる glob パターン（例: `"*.py"`、`"src/**/*.js"`）。 - - `path` (string, 任意): 検索対象のディレクトリの絶対パス。省略された場合、ツールのルートディレクトリを検索します。 + - `path` (string, 任意): 検索対象のディレクトリの絶対パス。省略された場合は、ツールのルートディレクトリを検索します。 - `case_sensitive` (boolean, 任意): 検索時に大文字小文字を区別するかどうか。デフォルトは `false`。 - - `respect_git_ignore` (boolean, 任意): ファイル検索時に .gitignore パターンを尊重するかどうか。デフォルトは `true`。 + - `respect_git_ignore` (boolean, 任意): ファイル検索時に .gitignore のパターンを尊重するかどうか。デフォルトは `true`。 - **動作:** - 指定されたディレクトリ内で glob パターンに一致するファイルを検索します。 - - 絶対パスのリストを返し、最も最近更新されたファイルが先頭に来るようにソートされます。 - - デフォルトでは `node_modules` や `.git` などの一般的な不要なディレクトリは無視されます。 -- **出力 (`llmContent`):** 以下のようなメッセージ: `Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...` + - 絶対パスのリストを、最も最近変更されたファイルが先頭に来るようソートして返します。 + - デフォルトでは `node_modules` や `.git` などの一般的な不要なディレクトリを無視します。 +- **出力 (`llmContent`):** 以下のようなメッセージを返します: `Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...` - **確認:** なし。 ## 5. `search_file_content` (SearchText) -`search_file_content` は、指定されたディレクトリ内のファイルの内容に対して正規表現パターンを検索します。glob パターンでファイルをフィルタリングできます。マッチした行とそのファイルパス、行番号を返します。 +`search_file_content` は、指定されたディレクトリ内のファイルの内容に対して正規表現パターンを検索します。glob パターンを使ってファイルをフィルタリングすることも可能です。マッチした行とそのファイルパス、行番号を返します。 - **Tool name:** `search_file_content` - **Display name:** SearchText - **File:** `grep.ts` - **Parameters:** - - `pattern` (string, required): 検索する正規表現（regex）（例: `"function\s+myFunction"`）。 - - `path` (string, optional): 検索対象のディレクトリの絶対パス。デフォルトはカレントワーキングディレクトリ。 - - `include` (string, optional): 検索するファイルをフィルタリングする glob パターン（例: `"*.js"`, `"src/**/*.{ts,tsx}"`）。省略した場合、一般的な無視ファイルを除いてほとんどのファイルを検索。 + - `pattern` (string, required): 検索する正規表現（regex）パターン（例: `"function\s+myFunction"`）。 + - `path` (string, optional): 検索対象のディレクトリの絶対パス。省略された場合はカレントディレクトリが使用されます。 + - `include` (string, optional): 検索するファイルをフィルタリングする glob パターン（例: `"*.js"`, `"src/**/*.{ts,tsx}"`）。省略された場合は、一般的な無視ファイルを除いたほとんどのファイルが検索されます。 + - `maxResults` (number, optional): コンテキストのオーバーフローを防ぐために返すマッチ結果の最大数（デフォルト: 20、最大: 100）。広範囲な検索には小さな値を、特定の検索には大きな値を使用してください。 - **Behavior:** - Git リポジトリ内で利用可能な場合は高速化のため `git grep` を使用し、それ以外の場合はシステムの `grep` または JavaScript ベースの検索にフォールバックします。 - - マッチした行のリストを返し、各行には検索ディレクトリからの相対パスと行番号がプレフィックスとして付加されます。 -- **Output (`llmContent`):** 以下のようにフォーマットされたマッチ結果の文字列: + - マッチした行のリストを返し、各行には検索ディレクトリからの相対パスと行番号が付加されます。 + - デフォルトではコンテキストのオーバーフローを防ぐため、最大20件のマッチ結果に制限されます。結果が切り捨てられた場合は、検索を絞り込むための案を含む明確な警告が表示されます。 +- **Output (`llmContent`):** 以下のようなフォーマットされた文字列で結果を返します: + ``` Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"): --- @@ -103,41 +106,68 @@ Qwen Code は、ローカルファイルシステムとやり取りするため File: src/index.ts L5: import { myFunction } from './utils'; --- + + WARNING: Results truncated to prevent context overflow. To see more results: + - Use a more specific pattern to reduce matches + - Add file filters with the 'include' parameter (e.g., "*.js", "src/**") + - Specify a narrower 'path' to search in a subdirectory + - Increase 'maxResults' parameter if you need more matches (current: 20) ``` + - **Confirmation:** なし +### `search_file_content` の例 + +デフォルトの結果制限でパターンを検索: + +``` +search_file_content(pattern="function\s+myFunction", path="src") +``` + +カスタム結果制限でパターンを検索: + +``` +search_file_content(pattern="function", path="src", maxResults=50) +``` + +ファイルフィルタリングとカスタム結果制限でパターンを検索: + +``` +search_file_content(pattern="function", include="*.js", maxResults=10) +``` + ## 6. `replace` (編集) -`replace` はファイル内のテキストを置換します。デフォルトでは1つの出現箇所のみを置換しますが、`expected_replacements` を指定することで複数の出現箇所を置換することも可能です。このツールは正確で対象を絞った変更を行うために設計されており、正しい場所を変更するために `old_string` の前後にある十分なコンテキストを必要とします。 +`replace` はファイル内のテキストを置換します。デフォルトでは1つの出現箇所のみを置換しますが、`expected_replacements` を指定することで複数の出現箇所を置換することも可能です。このツールは正確で対象を絞った変更を行うために設計されており、正しい位置を変更することを保証するために `old_string` の周囲に十分なコンテキストが必要です。 - **ツール名:** `replace` - **表示名:** 編集 - **ファイル:** `edit.ts` - **パラメータ:** - `file_path` (string, 必須): 変更するファイルの絶対パス。 - - `old_string` (string, 必須): 置換する正確な文字列。 + - `old_string` (string, 必須): 置換する正確なリテラルテキスト。 - **重要:** この文字列は変更する単一のインスタンスを一意に識別する必要があります。ターゲットテキストの前後少なくとも3行分のコンテキストを含み、空白やインデントも正確に一致させる必要があります。`old_string` が空の場合、ツールは `new_string` を内容として `file_path` に新しいファイルを作成しようとします。 + **重要:** この文字列は変更する単一のインスタンスを一意に識別する必要があります。ターゲットテキストの前後少なくとも3行のコンテキストを含み、空白とインデントを正確に一致させる必要があります。`old_string` が空の場合、ツールは `file_path` に `new_string` を内容とする新しいファイルを作成しようとします。 - - `new_string` (string, 必須): `old_string` を置換する正確な文字列。 - - `expected_replacements` (number, 任意): 置換する出現回数。デフォルトは `1`。 + - `new_string` (string, 必須): `old_string` を置換する正確なリテラルテキスト。 + - `expected_replacements` (number, オプション): 置換する出現回数。デフォルトは `1`。 - **動作:** - - `old_string` が空で `file_path` が存在しない場合、`new_string` を内容として新しいファイルを作成します。 - - `old_string` が指定されている場合、`file_path` を読み込み、`old_string` の出現箇所を正確に1つだけ探します。 - - 出現箇所が1つ見つかった場合、それを `new_string` で置換します。 - - **信頼性の向上 (マルチステージ編集修正):** 編集の成功率を大幅に向上させるために、特にモデルが提供した `old_string` が完全に正確でない可能性がある場合に備えて、ツールにはマルチステージ編集修正メカニズムが組み込まれています。 - - 初期の `old_string` が見つからない、または複数の場所に一致する場合、ツールはGeminiモデルを活用して `old_string`（および場合によっては `new_string`）を段階的に洗練させることができます。 - - この自己修正プロセスは、モデルが変更しようとした一意のセグメントを識別しようとし、初期コンテキストがわずかに不完全であっても `replace` 操作をより堅牢にします。 + - `old_string` が空で `file_path` が存在しない場合、`new_string` を内容とする新しいファイルを作成します。 + - `old_string` が提供された場合、`file_path` を読み取り、`old_string` の出現を正確に1つ見つけようとします。 + - 1つの出現が見つかった場合、それを `new_string` で置換します。 + - **信頼性の向上 (マルチステージ編集修正):** 編集の成功率を大幅に向上させるために、特にモデルが提供した `old_string` が完全に正確でない可能性がある場合、ツールにはマルチステージ編集修正メカニズムが組み込まれています。 + - 初期の `old_string` が見つからない、または複数の場所に一致する場合、ツールはGeminiモデルを活用して `old_string`（および場合によっては `new_string`）を反復的に洗練させることができます。 + - この自己修正プロセスは、モデルが変更することを意図した一意のセグメントを識別しようとし、初期コンテキストがわずかに不完全であっても `replace` 操作をより堅牢にします。 - **失敗条件:** 修正メカニズムにもかかわらず、以下の場合はツールが失敗します: - `file_path` が絶対パスでない、またはルートディレクトリ外にある。 - `old_string` が空でなく、`file_path` が存在しない。 - `old_string` が空で、`file_path` が既に存在する。 - 修正を試みた後も `old_string` がファイル内に見つからない。 - - `old_string` が複数回見つかり、自己修正メカニズムが一意で明確な一致に解決できない。 + - `old_string` が複数回見つかり、自己修正メカニズムが単一の明確な一致に解決できない。 - **出力 (`llmContent`):** - 成功時: `Successfully modified file: /path/to/file.txt (1 replacements).` または `Created new file: /path/to/new_file.txt with provided content.` - - 失敗時: 失敗理由を説明するエラーメッセージ（例: `Failed to edit, 0 occurrences found...`, `Failed to edit, expected 1 occurrences but found 2...`）。 + - 失敗時: 失敗の理由を説明するエラーメッセージ（例: `Failed to edit, 0 occurrences found...`, `Failed to edit, expected 1 occurrences but found 2...`）。 - **確認:** あり。提案された変更の差分を表示し、ファイルに書き込む前にユーザーの承認を求めます。 これらのファイルシステムツールは、Qwen Codeがローカルプロジェクトのコンテキストを理解し、操作するための基盤を提供します。 \ No newline at end of file diff --git a/website/content/ja/tools/index.md b/website/content/ja/tools/index.md index 85142756..2b41492f 100644 --- a/website/content/ja/tools/index.md +++ b/website/content/ja/tools/index.md @@ -6,27 +6,27 @@ Qwen Code には、モデルがローカル環境とやり取りしたり、情 Qwen Code の文脈において、ツールとはモデルが実行を要求できる特定の関数またはモジュールのことです。例えば、モデルに「`my_document.txt` の内容を要約してください」と依頼すると、モデルはそのファイルを読み込む必要性を判断し、`read_file` ツールの実行を要求するでしょう。 -コアコンポーネント（`packages/core`）はこれらのツールを管理し、モデルに対してツールの定義（スキーマ）を提示し、要求されたタイミングでツールを実行し、その結果をモデルに返して、最終的なユーザー向けレスポンスを生成するための処理を行います。 +コアコンポーネント（`packages/core`）はこれらのツールを管理し、モデルに対してツールの定義（スキーマ）を提示し、要求されたときにツールを実行し、その結果をモデルに返して、最終的なユーザー向けレスポンスを生成するための処理を行います。 これらのツールにより、以下の機能が提供されます： -- **ローカル情報へのアクセス:** ツールを使用することで、モデルはローカルファイルシステムにアクセスし、ファイルの内容を読み込んだり、ディレクトリをリスト表示したりできます。 -- **コマンドの実行:** `run_shell_command` のようなツールにより、モデルはシェルコマンドを実行できます（適切なセーフティメカニズムとユーザー確認を伴います）。 -- **ウェブとの連携:** ツールを使って URL からコンテンツを取得できます。 -- **アクションの実行:** ツールを使ってファイルの変更、新規ファイルの作成、またはシステム上のその他のアクションを実行できます（こちらも通常はセーフガード付きで）。 -- **レスポンスの根拠の確保:** ツールを使ってリアルタイムまたは特定のローカルデータを取得することで、レスポンスをより正確で関連性が高く、実際のコンテキストに基づいたものにできます。 +- **ローカル情報へのアクセス：** ツールを使用することで、モデルはローカルファイルシステムにアクセスし、ファイルの内容を読み込んだり、ディレクトリをリスト表示したりできます。 +- **コマンドの実行：** `run_shell_command` のようなツールにより、モデルはシェルコマンドを実行できます（適切なセーフティメカニズムとユーザー確認を経て）。 +- **Web との連携：** ツールを使って URL からコンテンツを取得できます。 +- **アクションの実行：** ツールを使ってファイルの変更、新規ファイルの作成、またはシステム上でのその他のアクションを実行できます（こちらも通常はセーフガード付きで）。 +- **レスポンスの根拠の確保：** ツールを使ってリアルタイムまたは特定のローカルデータを取得することで、レスポンスをより正確で関連性が高く、実際のコンテキストに基づいたものにできます。 ## Qwen Code ツールの使い方 Qwen Code ツールを使用するには、CLI にプロンプトを入力します。処理の流れは以下の通りです： -1. あなたが CLI にプロンプトを入力します。 -2. CLI がそのプロンプトをコアに送信します。 -3. コアは、あなたのプロンプトと会話履歴とともに、利用可能なツールの一覧とその説明・スキーマを、設定されたモデル API に送信します。 -4. モデルがリクエストを解析し、ツールの利用が必要と判断した場合、レスポンスには特定のツールを指定のパラメータで実行するリクエストが含まれます。 -5. コアはこのツール実行リクエストを受け取り、検証を行った上で（機密性の高い操作の場合はユーザーの確認を得て）、ツールを実行します。 -6. ツールの出力結果がモデルに送り返されます。 -7. モデルはその出力結果をもとに最終的な回答を生成し、コアを経由して CLI に送信され、表示されます。 +1. あなたが CLI にプロンプトを入力する。 +2. CLI がそのプロンプトをコアに送信する。 +3. コアは、あなたのプロンプトと会話履歴とともに、利用可能なツールの一覧とその説明・スキーマを、設定された model API に送信する。 +4. モデルがリクエストを分析し、ツールの利用が必要と判断した場合、レスポンスには特定のツールを指定されたパラメータで実行するリクエストが含まれる。 +5. コアはこのツール実行リクエストを受け取り、検証した上で（機密性の高い操作の場合はユーザー確認を経て）ツールを実行する。 +6. ツールの出力はモデルに送り返される。 +7. モデルはツールの出力を使って最終的な回答を生成し、それがコアを経由して CLI に送られ、表示される。 通常、CLI 上ではツールが呼び出されたタイミングや、その成否に関するメッセージが表示されます。 @@ -35,22 +35,23 @@ Qwen Code ツールを使用するには、CLI にプロンプトを入力しま 多くのツール、特にファイルシステムを変更したりコマンドを実行できるツール（`write_file`、`edit`、`run_shell_command` など）は、安全性を考慮して設計されています。Qwen Code は通常以下のように動作します： - **確認を要求する：** 潜在的に危険な操作を実行する前に、どのようなアクションが実行されようとしているかを表示して確認を求めます。 -- **サンドボックスの利用：** すべてのツールはサンドボックスによって強制される制限の対象となります（[Qwen Code におけるサンドボックス](../sandbox.md)を参照）。これは、サンドボックス内で動作している場合、使用したいすべてのツール（MCP サーバーを含む）がサンドボックス環境 _内部_ で利用可能である必要があることを意味します。例えば、`npx` を通じて MCP サーバーを実行するには、`npx` 実行ファイルがサンドボックスの Docker イメージ内にインストールされているか、または `sandbox-exec` 環境内で利用可能である必要があります。 +- **サンドボックスの利用：** すべてのツールはサンドボックスによって適用される制限の対象となります（[Qwen Code におけるサンドボックス](../sandbox.md)を参照）。これは、サンドボックス内で動作している場合、使用したいすべてのツール（MCP サーバーを含む）が**サンドボックス環境内**で利用可能でなければならないことを意味します。例えば、`npx` を介して MCP サーバーを実行するには、`npx` 実行ファイルがサンドボックスの Docker イメージ内にインストールされているか、または `sandbox-exec` 環境内で利用可能である必要があります。 -ツールに処理を進める許可を与える前に、常に確認プロンプトを慎重に確認することが重要です。 +ツールに処理を進める許可を与える前に、確認プロンプトを常に慎重に確認することが重要です。 -## Qwen Code のツールについて詳しく学ぶ +## Qwen Code のツールについて詳しく知る Qwen Code に組み込まれているツールは、大まかに以下のように分類できます： - **[File System Tools](./file-system.md):** ファイルやディレクトリに対する操作（読み込み、書き込み、一覧表示、検索など）を行うためのツールです。 - **[Shell Tool](./shell.md) (`run_shell_command`):** シェルコマンドを実行するためのツールです。 - **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** URL からコンテンツを取得するためのツールです。 -- **[Web Search Tool](./web-search.md) (`web_search`):** ウェブを検索するためのツールです。 +- **[Web Search Tool](./web-search.md) (`web_search`):** Web を検索するためのツールです。 - **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** 複数のファイルやディレクトリからコンテンツを読み込むための専用ツールで、`@` コマンドでよく使われます。 - **[Memory Tool](./memory.md) (`save_memory`):** セッションをまたいで情報を保存・呼び出すためのツールです。 +- **[Todo Write Tool](./todo-write.md) (`todo_write`):** コーディングセッション中に構造化されたタスクリストを作成・管理するためのツールです。 さらに、これらのツールには以下が組み込まれています： - **[MCP servers](./mcp-server.md)**: MCP サーバーは、モデルとローカル環境や API などの他のサービスとの間のブリッジとして機能します。 -- **[Sandboxing](../sandbox.md)**: サンドボックス化により、モデルとその変更が環境から隔離され、潜在的なリスクを低減します。 \ No newline at end of file +- **[Sandboxing](../sandbox.md)**: サンドボックス機能により、モデルとその変更が環境から隔離され、潜在的なリスクを低減します。 \ No newline at end of file diff --git a/website/content/ja/tools/shell.md b/website/content/ja/tools/shell.md index 3d9eeb35..e71b288e 100644 --- a/website/content/ja/tools/shell.md +++ b/website/content/ja/tools/shell.md @@ -4,78 +4,129 @@ ## 概要 -`run_shell_command` を使用して、下位のシステムとやり取りしたり、スクリプトを実行したり、コマンドライン操作を実行したりできます。`run_shell_command` は指定された shell コマンドを実行します。Windows では、コマンドは `cmd.exe /c` で実行されます。他のプラットフォームでは、コマンドは `bash -c` で実行されます。 +`run_shell_command` を使用して、下位システムとやり取りしたり、スクリプトを実行したり、コマンドライン操作を実行したりできます。`run_shell_command` は、指定された shell コマンドを実行します。Windows では、コマンドは `cmd.exe /c` で実行されます。他のプラットフォームでは、コマンドは `bash -c` で実行されます。 ### 引数 `run_shell_command` は以下の引数を取ります： - `command` (string, 必須): 実行する正確な shell コマンド。 -- `description` (string, 任意): コマンドの目的を示す簡単な説明。ユーザーに表示されます。 +- `description` (string, 任意): コマンドの目的についての簡単な説明で、ユーザーに表示されます。 - `directory` (string, 任意): コマンドを実行するディレクトリ（プロジェクトルートからの相対パス）。指定しない場合、コマンドはプロジェクトルートで実行されます。 +- `is_background` (boolean, 必須): コマンドをバックグラウンドで実行するかどうか。このパラメータは、コマンド実行モードについて明示的な判断を行うために必須です。開発サーバーやウォッチャー、デーモンなど、継続的に実行し続ける必要があり、他のコマンドの実行をブロックすべきではない長時間実行プロセスに対しては `true` を設定します。完了まで待機してから次に進む一時的なコマンドに対しては `false` を設定します。 ## Qwen Code での `run_shell_command` の使い方 -`run_shell_command` を使用する際、コマンドはサブプロセスとして実行されます。`run_shell_command` では `&` を使ってバックグラウンドプロセスを起動することも可能です。このツールは以下のような実行に関する詳細情報を返します： +`run_shell_command` を使用する際、コマンドはサブプロセスとして実行されます。`is_background` パラメータを使用するか、コマンドに明示的に `&` を追加することで、コマンドをバックグラウンドで実行するかフォアグラウンドで実行するかを制御できます。このツールは、以下を含む実行に関する詳細情報を返します： + +### 必須の Background パラメータ + +`is_background` パラメータは、**すべてのコマンド実行で必須**です。この設計により、LLM（およびユーザー）は各コマンドをバックグラウンドで実行するかフォアグラウンドで実行するかを明示的に判断する必要があり、意図的で予測可能なコマンド実行動作が促進されます。このパラメータを必須とすることで、長時間実行されるプロセスを扱う際に後続の操作をブロックする可能性のある、意図しないフォアグラウンド実行へのフォールバックを回避できます。 + +### バックグラウンド実行 vs フォアグラウンド実行 + +このツールは、明示的な選択に基づいてバックグラウンドとフォアグラウンドの実行を適切に処理します： + +**バックグラウンド実行 (`is_background: true`) を使うケース：** + +- 長時間実行される開発サーバー：`npm run start`、`npm run dev`、`yarn dev` +- ビルドウォッチャー：`npm run watch`、`webpack --watch` +- データベースサーバー：`mongod`、`mysql`、`redis-server` +- Webサーバー：`python -m http.server`、`php -S localhost:8000` +- 手動で停止するまで無期限に実行し続けるコマンド + +**フォアグラウンド実行 (`is_background: false`) を使うケース：** + +- 一度限りのコマンド：`ls`、`cat`、`grep` +- ビルドコマンド：`npm run build`、`make` +- インストールコマンド：`npm install`、`pip install` +- Git操作：`git commit`、`git push` +- テスト実行：`npm test`、`pytest` + +### 実行情報 + +このツールは、実行に関する詳細情報を返します。含まれる情報は以下の通りです： - `Command`: 実行されたコマンド。 - `Directory`: コマンドが実行されたディレクトリ。 - `Stdout`: 標準出力ストリームからの出力。 -- `Stderr`: 標準エラー出力ストリームからの出力。 -- `Error`: サブプロセスから報告されたエラーメッセージ。 +- `Stderr`: 標準エラー ストリームからの出力。 +- `Error`: サブプロセスによって報告されたエラー メッセージ。 - `Exit Code`: コマンドの終了コード。 - `Signal`: コマンドがシグナルによって終了された場合のシグナル番号。 -- `Background PIDs`: 起動されたバックグラウンドプロセスの PID のリスト。 +- `Background PIDs`: 起動されたバックグラウンド プロセスの PID のリスト。 使用方法： +```bash +run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.", is_background=false) ``` -run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.") -``` + +**注意:** `is_background` パラメータは必須であり、すべてのコマンド実行で明示的に指定する必要があります。 ## `run_shell_command` の例 カレントディレクトリのファイルを一覧表示: -``` -run_shell_command(command="ls -la") +```bash +run_shell_command(command="ls -la", is_background=false) ``` 特定のディレクトリでスクリプトを実行: +```bash +run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script", is_background=false) +``` + +バックグラウンドで開発サーバーを起動 (推奨アプローチ): + +```bash +run_shell_command(command="npm run dev", description="Start development server in background", is_background=true) ``` -run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script") + +バックグラウンドでサーバーを起動 (明示的に & を使用した代替方法): + +```bash +run_shell_command(command="npm run dev &", description="Start development server in background", is_background=false) ``` -バックグラウンドでサーバーを起動: +フォアグラウンドでビルドコマンドを実行: +```bash +run_shell_command(command="npm run build", description="Build the project", is_background=false) ``` -run_shell_command(command="npm run dev &", description="Start development server in background") + +複数のバックグラウンドサービスを起動: + +```bash +run_shell_command(command="docker-compose up", description="Start all services", is_background=true) ``` -## 重要な注意点 +## 重要な注意事項 -- **セキュリティ:** 特にユーザー入力から構築されたコマンドを実行する際は、セキュリティ上の脆弱性を防ぐために注意が必要です。 -- **インタラクティブなコマンド:** ユーザーの対話入力を必要とするコマンドは避けてください。これによりツールがハングアップする可能性があります。可能であれば、非対話的なフラグを使用してください（例: `npm init -y`）。 -- **エラー処理:** コマンドが正常に実行されたかどうかを判断するには、`Stderr`、`Error`、および `Exit Code` フィールドを確認してください。 -- **バックグラウンドプロセス:** `&` を使用してバックグラウンドでコマンドを実行すると、ツールは即座に制御を返し、プロセスはバックグラウンドで引き続き実行されます。`Background PIDs` フィールドには、バックグラウンドプロセスのプロセスIDが格納されます。 +- **セキュリティ:** 特にユーザー入力から構築されたコマンドを実行する際は、セキュリティ脆弱性を防ぐために注意が必要です。 +- **インタラクティブなコマンド:** ユーザーの対話入力を必要とするコマンドは避けてください。これによりツールがハングアップする可能性があります。可能であれば非対話フラグを使用してください（例: `npm init -y`）。 +- **エラー処理:** コマンドが正常に実行されたかどうかを判断するには、`Stderr`、`Error`、`Exit Code` フィールドを確認してください。 +- **バックグラウンドプロセス:** `is_background=true` の場合、またはコマンドに `&` が含まれている場合、ツールは即座に返却し、プロセスはバックグラウンドで実行を続けます。`Background PIDs` フィールドにはバックグラウンドプロセスのプロセスIDが含まれます。 +- **バックグラウンド実行の選択:** `is_background` パラメータは必須であり、実行モードを明示的に制御できます。手動でバックグラウンド実行するためにコマンドに `&` を追加することも可能ですが、`is_background` パラメータの指定は依然として必須です。このパラメータにより意図が明確になり、バックグラウンド実行のセットアップを自動的に処理します。 +- **コマンドの説明:** `is_background=true` を使用する場合、コマンドの説明には実行モードを明確に示すための `[background]` インジケータが含まれます。 ## 環境変数 -`run_shell_command` がコマンドを実行する際、サブプロセスの環境に `QWEN_CODE=1` という環境変数が設定されます。これにより、スクリプトやツールが CLI 内から実行されているかどうかを検出できます。 +`run_shell_command` がコマンドを実行する際、サブプロセスの環境に `QWEN_CODE=1` という環境変数を設定します。これにより、スクリプトやツールが CLI から実行されているかどうかを検出できます。 ## コマンド制限 `run_shell_command` ツールで実行可能なコマンドを制限するには、設定ファイルの `coreTools` および `excludeTools` 設定を使用します。 -- `coreTools`: `run_shell_command` を特定のコマンド群に制限するには、`coreTools` リストに `run_shell_command()` 形式のエントリを追加します。例えば、`"coreTools": ["run_shell_command(git)"]` とすると、`git` コマンドのみが許可されます。一般的な `run_shell_command` を含めるとワイルドカードとして機能し、明示的にブロックされていないすべてのコマンドが許可されます。 +- `coreTools`: `run_shell_command` を特定のコマンドセットに制限するには、`coreTools` リストに `run_shell_command()` 形式のエントリを追加します。例えば、`"coreTools": ["run_shell_command(git)"]` とすると、`git` コマンドのみが許可されます。一般的な `run_shell_command` を含めるとワイルドカードとして機能し、明示的にブロックされていないすべてのコマンドが許可されます。 - `excludeTools`: 特定のコマンドをブロックするには、`excludeTools` リストに `run_shell_command()` 形式のエントリを追加します。例えば、`"excludeTools": ["run_shell_command(rm)"]` とすると、`rm` コマンドがブロックされます。 -検証ロジックは、セキュアかつ柔軟性を保つために設計されています： +検証ロジックは、セキュアかつ柔軟性のある設計になっています： -1. **コマンドチェーンの無効化**: ツールは自動的に `&&`、`||`、または `;` で連結されたコマンドを分割し、各部分を個別に検証します。チェーン内のいずれかの部分が許可されていない場合、コマンド全体がブロックされます。 +1. **コマンドチェーンの無効化**: ツールは自動的に `&&`、`||`、または `;` でチェーンされたコマンドを分割し、各部分を個別に検証します。チェーンのいずれかの部分が許可されていない場合、コマンド全体がブロックされます。 2. **プレフィックスマッチング**: ツールはプレフィックスマッチングを使用します。例えば、`git` を許可すると、`git status` や `git log` を実行できます。 -3. **ブロックリストの優先順位**: `excludeTools` リストは常に最初にチェックされます。コマンドがブロックされたプレフィックスにマッチする場合、たとえ `coreTools` の許可されたプレフィックスにもマッチしても、拒否されます。 +3. **ブロックリストの優先順位**: `excludeTools` リストは常に最初にチェックされます。コマンドがブロックされたプレフィックスにマッチする場合、`coreTools` で許可されたプレフィックスにマッチしていても拒否されます。 ### コマンド制限の例 @@ -137,4 +188,4 @@ run_shell_command(command="npm run dev &", description="Start development server ## `excludeTools` のセキュリティに関する注意 -`run_shell_command` の `excludeTools` によるコマンド固有の制限は、単純な文字列マッチングに基づいているため、簡単にバイパスされる可能性があります。この機能は**セキュリティメカニズムではない**ため、信頼できないコードを安全に実行するために依存すべきではありません。実行可能なコマンドを明示的に選択するには、`coreTools` の使用を推奨します。 \ No newline at end of file +`run_shell_command` の `excludeTools` によるコマンド固有の制限は、単純な文字列マッチングに基づいており、簡単にバイパスされる可能性があります。この機能は**セキュリティメカニズムではない**ため、信頼できないコードを安全に実行するために依存すべきではありません。実行可能なコマンドを明示的に選択するには、`coreTools` の使用を推奨します。 \ No newline at end of file diff --git a/website/content/ja/tools/todo-write.md b/website/content/ja/tools/todo-write.md new file mode 100644 index 00000000..33b6e892 --- /dev/null +++ b/website/content/ja/tools/todo-write.md @@ -0,0 +1,63 @@ +# Todo Write Tool (`todo_write`) + +このドキュメントでは、Qwen Code 用の `todo_write` ツールについて説明します。 + +## 概要 + +`todo_write` を使用して、現在のコーディングセッション用に構造化されたタスクリストを作成・管理できます。このツールは、AIアシスタントが進捗状況を追跡し、複雑なタスクを整理するのに役立ち、あなたがどの作業が行われているかを可視化できます。 + +### 引数 + +`todo_write` は1つの引数を取ります： + +- `todos` (array, required): todoアイテムの配列。各アイテムには以下が含まれます： + - `id` (string, required): todoアイテムの一意の識別子。 + - `content` (string, required): タスクの説明。 + - `status` (string, required): 現在のステータス（`pending`、`in_progress`、または`completed`）。 + +## Qwen Code で `todo_write` を使う方法 + +AIアシスタントは、複雑な複数ステップのタスクに取り組む際、自動的にこのツールを使用します。明示的にリクエストする必要はありませんが、リクエストに対する計画的なアプローチを確認したい場合は、アシスタントにtodoリストの作成を依頼できます。 + +このツールは、ホームディレクトリ（`~/.qwen/todos/`）にセッション固有のファイルとしてtodoリストを保存するため、各コーディングセッションで独自のタスクリストを維持します。 + +## AIがこのツールを使うタイミング + +アシスタントは以下のケースで `todo_write` を使用します： + +- 複数のステップを必要とする複雑なタスク +- 複数のコンポーネントを持つ機能の実装 +- 複数のファイルにまたがるリファクタリング操作 +- 3つ以上の異なるアクションを含む作業 + +アシスタントは、単純な1ステップのタスクや純粋に情報提供のみを目的とするリクエストに対しては、このツールを使用しません。 + +### `todo_write` の例 + +機能実装プランの作成: + +``` +todo_write(todos=[ + { + "id": "create-model", + "content": "Create user preferences model", + "status": "pending" + }, + { + "id": "add-endpoints", + "content": "Add API endpoints for preferences", + "status": "pending" + }, + { + "id": "implement-ui", + "content": "Implement frontend components", + "status": "pending" + } +]) +``` + +## 重要な注意点 + +- **自動利用:** AIアシスタントは複雑なタスク中に自動的にtodoリストを管理します。 +- **進捗可視化:** 作業が進むにつれてtodoリストがリアルタイムで更新されるのを確認できます。 +- **セッション隔離:** 各コーディングセッションは独立したtodoリストを持ち、他のセッションと干渉しません。 \ No newline at end of file diff --git a/website/content/ja/troubleshooting.md b/website/content/ja/troubleshooting.md index 805d5dfc..e22b55e6 100644 --- a/website/content/ja/troubleshooting.md +++ b/website/content/ja/troubleshooting.md @@ -1,23 +1,28 @@ # トラブルシューティングガイド -このガイドでは、一般的な問題への対処方法とデバッグのヒントを提供します。以下のトピックを含みます： +このガイドでは、以下のような一般的な問題への対処方法とデバッグのヒントを提供します： - 認証またはログインエラー -- よくある質問（FAQ） +- よくある質問（FAQs） - デバッグのヒント -- あなたの問題に類似した既存の GitHub Issues または新しい Issue の作成 +- あなたの問題に類似した既存の GitHub Issues、または新しい Issue の作成方法 ## 認証またはログインエラー - **エラー: `Failed to login. Message: Request contains an invalid argument`** - - Gmail アカウントに関連付けられた Google Workspace アカウントまたは Google Cloud アカウントのユーザーは、Google Code Assist プランのフリーティアをアクティベートできない場合があります。 + - Gmail アカウントに関連付けられている Google Workspace アカウントまたは Google Cloud アカウントのユーザーは、Google Code Assist プランの無料ティアをアクティベートできない場合があります。 - Google Cloud アカウントの場合、`GOOGLE_CLOUD_PROJECT` をプロジェクト ID に設定することで回避できます。 - - または、[Google AI Studio](http://aistudio.google.com/app/apikey) から Gemini API key を取得することもできます。これには別のフリーティアも含まれます。 + - または、[Google AI Studio](http://aistudio.google.com/app/apikey) から Gemini API key を取得することもできます。こちらも別途無料ティアが用意されています。 + +- **エラー: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` または `unable to get local issuer certificate`** + - **原因:** SSL/TLS 通信を傍受・検査するファイアウォールがある企業ネットワークにいる可能性があります。このような環境では、Node.js が信頼するカスタムルート CA 証明書が必要になることがよくあります。 + - **解決方法:** `NODE_EXTRA_CA_CERTS` 環境変数に、企業のルート CA 証明書ファイルの絶対パスを設定してください。 + - 例: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` ## よくある質問 (FAQ) - **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` コマンドで更新してください。ソースからビルドした場合は、リポジトリから最新の変更を pull して、`npm run build` コマンドで再ビルドしてください。 - **Q: Qwen Code の設定ファイルや設定情報はどこに保存されますか？** - A: Qwen Code の設定は以下の2つの `settings.json` ファイルに保存されます： @@ -27,9 +32,9 @@ 詳細については [Qwen Code Configuration](./cli/configuration.md) を参照してください。 - **Q: なぜ統計出力にキャッシュされたトークン数が表示されないのですか？** - - A: キャッシュされたトークン情報は、キャッシュされたトークンが使用されている場合にのみ表示されます。この機能は API キーのユーザー（Gemini API キーまたは Google Cloud Vertex AI）には利用可能ですが、OAuth ユーザー（Google Gmail や Google Workspace などの Google 個人/エンタープライズアカウント）には利用できません。これは Gemini Code Assist API がキャッシュされたコンテンツの作成をサポートしていないためです。`/stats` コマンドを使用して、引き続き合計トークン使用量を確認できます。 + - A: キャッシュされたトークン情報は、キャッシュされたトークンが使用されている場合にのみ表示されます。この機能は API キーのユーザー（Gemini API キーまたは Google Cloud Vertex AI）向けに提供されていますが、OAuth ユーザー（Google Gmail や Google Workspace などの Google 個人/エンタープライズアカウント）には提供されていません。これは、Gemini Code Assist API がキャッシュされたコンテンツの作成をサポートしていないためです。`/stats` コマンドを使用して、引き続き合計トークン使用量を確認できます。 -## よくあるエラーメッセージとその解決方法 +## よくあるエラーメッセージと解決方法 - **エラー: MCP サーバー起動時に `EADDRINUSE` (Address already in use) が発生する** - **原因:** 別のプロセスが、MCP サーバーがバインドしようとしているポートをすでに使用しています。 @@ -40,7 +45,7 @@ - **原因:** CLI が正しくインストールされていないか、システムの `PATH` に含まれていません。 - **解決方法:** Qwen Code のインストール方法に応じて対応してください： - - `qwen` をグローバルにインストールした場合、`npm` のグローバルバイナリディレクトリが `PATH` に含まれていることを確認してください。更新するには、`npm install -g @qwen-code/qwen-code@latest` コマンドを使用します。 + - `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 エラーが発生する** @@ -56,13 +61,13 @@ - **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` + - **原因:** `is-in-ci` パッケージは、`CI`、`CONTINUOUS_INTEGRATION`、または `CI_` プレフィックス付きの環境変数が存在するかどうかをチェックします。これらのいずれかが見つかると、環境が非インタラクティブであると判断され、CLI はインタラクティブモードで起動しません。 + - **解決方法:** CLI の動作に `CI_` プレフィックス付きの変数が必要でない場合、コマンド実行時に一時的にその変数を解除できます。例: `env -u CI_TOKEN qwen` - **プロジェクトの .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 が接続されない @@ -71,23 +76,23 @@ - `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」を使用して、正しく起動するか確認してください。 ## デバッグのヒント - **CLI デバッグ:** - 詳細な出力が必要な場合は、CLI コマンドで `--verbose` フラグ（利用可能な場合）を使用してください。 - - CLI のログを確認してください。ログは通常、ユーザー固有の設定ディレクトリやキャッシュディレクトリに保存されています。 + - CLI のログを確認してください。ログは多くの場合、ユーザー固有の設定ディレクトリやキャッシュディレクトリに保存されています。 - **Core デバッグ:** - サーバーのコンソール出力を確認し、エラーメッセージやスタックトレースがないかチェックしてください。 - - 設定可能な場合は、ログの詳細度（verbosity）を上げてください。 + - 設定可能な場合は、ログの詳細レベルを上げてください。 - サーバーサイドのコードをステップ実行する必要がある場合は、Node.js のデバッグツール（例: `node --inspect`）を使用してください。 - **ツールの問題:** - - 特定のツールが失敗する場合、そのツールが実行するコマンドや操作を最小限に単純化したバージョンを実行して、問題を切り分けてみてください。 + - 特定のツールが失敗する場合は、そのツールが実行するコマンドや操作を最もシンプルな形で実行し、問題を切り分けてみてください。 - `run_shell_command` の場合は、まず直接シェルでコマンドが動作するか確認してください。 - - _ファイルシステム系のツール_ の場合は、パスが正しいこととパーミッションを確認してください。 + - _ファイルシステムツール_ の場合は、パスが正しいことを確認し、パーミッションもチェックしてください。 - **プレフライトチェック:** - コードをコミットする前には、必ず `npm run preflight` を実行してください。これにより、フォーマット、リンティング、型エラーなど、多くの一般的な問題を事前に検出できます。 diff --git a/website/content/ru/cli/configuration.md b/website/content/ru/cli/configuration.md index 312260cb..2ddd879e 100644 --- a/website/content/ru/cli/configuration.md +++ b/website/content/ru/cli/configuration.md @@ -4,13 +4,13 @@ Qwen Code предлагает несколько способов настро ## Уровни конфигурации -Конфигурация применяется в следующем порядке приоритета (параметры с меньшими номерами переопределяются параметрами с большими номерами): +Конфигурация применяется в следующем порядке приоритета (параметры с меньшим номером переопределяются параметрами с большим номером): 1. **Значения по умолчанию:** Жестко закодированные значения по умолчанию внутри приложения. 2. **Файл пользовательских настроек:** Глобальные настройки для текущего пользователя. 3. **Файл настроек проекта:** Настройки, специфичные для проекта. -4. **Файл системных настроек:** Настройки на уровне всей системы. -5. **Переменные окружения:** Переменные на уровне всей системы или сессии, потенциально загружаемые из файлов `.env`. +4. **Файл системных настроек:** Общесистемные настройки. +5. **Переменные окружения:** Переменные на уровне системы или сессии, которые могут быть загружены из файлов `.env`. 6. **Аргументы командной строки:** Значения, переданные при запуске CLI. ## Файлы настроек @@ -25,9 +25,9 @@ Qwen Code использует файлы `settings.json` для хранени - **Область применения:** Настройки применяются только при запуске Qwen Code из этого конкретного проекта. Настройки проекта переопределяют пользовательские. - **Файл системных настроек:** - **Расположение:** `/etc/gemini-cli/settings.json` (Linux), `C:\ProgramData\gemini-cli\settings.json` (Windows) или `/Library/Application Support/GeminiCli/settings.json` (macOS). Путь можно изменить с помощью переменной окружения `GEMINI_CLI_SYSTEM_SETTINGS_PATH`. - - **Область применения:** Настройки применяются ко всем сессиям Qwen Code в системе, для всех пользователей. Системные настройки переопределяют как пользовательские, так и проектные. Это может быть полезно системным администраторам в корпоративной среде для централизованного управления настройками Qwen Code пользователей. + - **Область применения:** Настройки применяются ко всем сессиям 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` в вашем проекте @@ -46,7 +46,7 @@ Qwen Code использует файлы `settings.json` для хранени - **Описание:** Переопределяет URL по умолчанию для команды `/bug`. - **По умолчанию:** `"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"` - **Свойства:** - - **`urlTemplate`** (строка): URL, который может содержать плейсхолдеры `{title}` и `{info}`. + - **`urlTemplate`** (строка): URL, который может содержать заполнители `{title}` и `{info}`. - **Пример:** ```json "bugCommand": { @@ -55,11 +55,11 @@ Qwen Code использует файлы `settings.json` для хранени ``` - **`fileFiltering`** (объект): - - **Описание:** Управляет поведением фильтрации файлов с учетом git для команд @ и инструментов поиска файлов. + - **Описание:** Управляет поведением фильтрации файлов с учетом 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): Включать ли рекурсивный поиск файлов в текущем дереве при завершении префиксов @ в prompt. - **Пример:** ```json "fileFiltering": { @@ -69,30 +69,30 @@ Qwen Code использует файлы `settings.json` для хранени ``` - **`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)"]`. - **`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` для явного выбора команд, которые могут быть выполнены. - **`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, которые должны быть исключены из модели. Сервер, указанный и в `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` @@ -107,12 +107,12 @@ Qwen Code использует файлы `settings.json` для хранени - **Пример:** `"vimMode": true` - **`sandbox`** (boolean или строка): - - **Описание:** Управляет тем, использовать ли песочницу для выполнения инструментов и как это делать. Если установлено в `true`, Qwen Code использует предварительно собранный Docker-образ `qwen-code-sandbox`. Подробнее см. [Песочница](#sandboxing). + - **Описание:** Управляет тем, использовать ли песочницу для выполнения инструментов и как это делать. Если установлено значение `true`, Qwen Code использует предварительно собранный Docker-образ `qwen-code-sandbox`. Дополнительную информацию см. в разделе [Песочница](#sandboxing). - **По умолчанию:** `false` - **Пример:** `"sandbox": "docker"` - **`toolDiscoveryCommand`** (строка): - - **Описание:** Определяет пользовательскую shell-команду для обнаружения инструментов из вашего проекта. Команда должна возвращать на `stdout` JSON-массив [объявлений функций](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). Обертки инструментов не обязательны. + - **Описание:** Определяет пользовательскую shell-команду для обнаружения инструментов из вашего проекта. Команда должна возвращать в `stdout` массив [объявлений функций](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) в формате JSON. Обертки инструментов необязательны. - **По умолчанию:** Пусто - **Пример:** `"toolDiscoveryCommand": "bin/get_tools"` @@ -120,23 +120,23 @@ Qwen Code использует файлы `settings.json` для хранени - **Описание:** Определяет пользовательскую 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). + - Возвращать вывод функции в формате JSON в `stdout`, аналогично [`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 для обеспечения совместимости. + - **Описание:** Настраивает подключения к одному или нескольким серверам Model-Context Protocol (MCP) для обнаружения и использования пользовательских инструментов. Qwen Code пытается подключиться к каждому настроенному серверу MCP для обнаружения доступных инструментов. Если несколько серверов MCP предоставляют инструмент с одинаковым именем, имена инструментов будут дополнены псевдонимом сервера, определенным в конфигурации (например, `serverAlias__actualToolName`), чтобы избежать конфликтов. Обратите внимание, что система может удалить некоторые свойства схемы из определений инструментов MCP для обеспечения совместимости. - **По умолчанию:** Пусто - **Свойства:** - - **``** (объект): Параметры сервера с указанным именем. + - **``** (объект): Параметры сервера для указанного сервера. - `command` (строка, обязательный): Команда для запуска сервера MCP. - - `args` (массив строк, опционально): Аргументы, передаваемые команде. - - `env` (объект, опционально): Переменные окружения, устанавливаемые для процесса сервера. - - `cwd` (строка, опционально): Рабочая директория для запуска сервера. - - `timeout` (число, опционально): Таймаут в миллисекундах для запросов к этому серверу MCP. - - `trust` (boolean, опционально): Доверять этому серверу и пропускать все подтверждения вызова инструментов. - - `includeTools` (массив строк, опционально): Список имен инструментов, которые следует включить с этого сервера MCP. Если указано, только перечисленные инструменты будут доступны с этого сервера (поведение белого списка). Если не указано, по умолчанию включаются все инструменты с сервера. - - `excludeTools` (массив строк, опционально): Список имен инструментов, которые следует исключить с этого сервера MCP. Перечисленные инструменты не будут доступны модели, даже если они предоставлены сервером. **Примечание:** `excludeTools` имеет приоритет над `includeTools` — если инструмент присутствует в обоих списках, он будет исключен. + - `args` (массив строк, необязательный): Аргументы, передаваемые команде. + - `env` (объект, необязательный): Переменные окружения, устанавливаемые для процесса сервера. + - `cwd` (строка, необязательный): Рабочая директория, в которой запускается сервер. + - `timeout` (число, необязательный): Таймаут в миллисекундах для запросов к этому серверу MCP. + - `trust` (boolean, необязательный): Доверять этому серверу и обходить все подтверждения вызова инструментов. + - `includeTools` (массив строк, необязательный): Список имен инструментов, которые нужно включить с этого сервера MCP. Если указано, то будут доступны только перечисленные здесь инструменты (поведение белого списка). Если не указано, по умолчанию включаются все инструменты с сервера. + - `excludeTools` (массив строк, необязательный): Список имен инструментов, которые нужно исключить с этого сервера MCP. Перечисленные здесь инструменты не будут доступны модели, даже если они предоставлены сервером. **Примечание:** `excludeTools` имеет приоритет над `includeTools` — если инструмент присутствует в обоих списках, он будет исключен. - **Пример:** ```json "mcpServers": { @@ -164,24 +164,24 @@ Qwen Code использует файлы `settings.json` для хранени ``` - **`checkpointing`** (объект): - - **Описание:** Настраивает функцию контрольных точек, которая позволяет сохранять и восстанавливать состояние разговора и файлов. Подробнее см. в [документации по контрольным точкам](../checkpointing.md). + - **Описание:** Настраивает функцию контрольных точек, которая позволяет сохранять и восстанавливать состояния разговора и файлов. Подробнее см. в [документации по контрольным точкам](../checkpointing.md). - **По умолчанию:** `{"enabled": false}` - **Свойства:** - **`enabled`** (boolean): Если `true`, команда `/restore` становится доступной. - **`preferredEditor`** (строка): - - **Описание:** Указывает предпочитаемый редактор для просмотра diff'ов. + - **Описание:** Указывает предпочитаемый редактор для просмотра diff. - **По умолчанию:** `vscode` - **Пример:** `"preferredEditor": "vscode"` - **`telemetry`** (объект) - - **Описание:** Настраивает сбор логов и метрик для Qwen Code. Подробнее см. [Телеметрия](../telemetry.md). + - **Описание:** Настраивает сбор логов и метрик для Qwen Code. Подробнее см. в разделе [Телеметрия](../telemetry.md). - **По умолчанию:** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **Свойства:** - **`enabled`** (boolean): Включена ли телеметрия. - **`target`** (строка): Назначение для собранной телеметрии. Поддерживаемые значения: `local` и `gcp`. - **`otlpEndpoint`** (строка): Конечная точка для OTLP Exporter. - - **`logPrompts`** (boolean): Включать ли содержимое пользовательских prompt'ов в логи. + - **`logPrompts`** (boolean): Включать ли содержимое пользовательских prompt в логи. - **Пример:** ```json "telemetry": { @@ -192,7 +192,7 @@ Qwen Code использует файлы `settings.json` для хранени } ``` - **`usageStatisticsEnabled`** (boolean): - - **Описание:** Включает или отключает сбор статистики использования. Подробнее см. [Статистика использования](#usage-statistics). + - **Описание:** Включает или отключает сбор статистики использования. Подробнее см. в разделе [Статистика использования](#usage-statistics). - **По умолчанию:** `true` - **Пример:** ```json @@ -231,6 +231,7 @@ Qwen Code использует файлы `settings.json` для хранени - **По умолчанию:** `{}` (по умолчанию отключено) - **Пример:** ```json + "summarizeToolOutput": { ### Пример `settings.json`: @@ -281,7 +282,7 @@ CLI сохраняет историю выполненных вами shell-ко ## Переменные окружения и файлы `.env` -Переменные окружения — это распространённый способ конфигурации приложений, особенно для чувствительных данных, таких как API keys, или для настроек, которые могут отличаться в зависимости от среды. +Переменные окружения — это распространённый способ конфигурации приложений, особенно для чувствительных данных, таких как API ключи, или для настроек, которые могут отличаться в зависимости от среды. CLI автоматически загружает переменные окружения из файла `.env`. Порядок загрузки следующий: @@ -292,45 +293,45 @@ CLI автоматически загружает переменные окру **Исключение переменных окружения:** Некоторые переменные (например, `DEBUG` и `DEBUG_MODE`) по умолчанию исключаются из проектных `.env` файлов, чтобы не мешать работе CLI. Переменные из файлов `.qwen/.env` никогда не исключаются. Вы можете настроить это поведение с помощью параметра `excludedProjectEnvVars` в файле `settings.json`. - **`GEMINI_API_KEY`** (обязательно): - - Ваш API key для Gemini API. - - **Критично для работы.** CLI не будет функционировать без этой переменной. - - Установите её в вашем shell-профиле (например, `~/.bashrc`, `~/.zshrc`) или в файле `.env`. + - Ваш API ключ для Gemini API. + - **Критично для работы.** CLI не будет функционировать без этого ключа. + - Установите его в вашем shell-профиле (например, `~/.bashrc`, `~/.zshrc`) или в файле `.env`. - **`GEMINI_MODEL`**: - Указывает модель Gemini по умолчанию. - - Переопределяет значение по умолчанию, заданное в коде. + - Переопределяет жёстко заданную модель по умолчанию. - Пример: `export GEMINI_MODEL="gemini-2.5-flash"` - **`GOOGLE_API_KEY`**: - - Ваш API key для Google Cloud. + - Ваш API ключ Google Cloud. - Требуется для использования Vertex AI в express-режиме. - Убедитесь, что у вас есть необходимые права доступа. - Пример: `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`. - **`GOOGLE_CLOUD_PROJECT`**: - - ID вашего проекта в Google Cloud. + - ID вашего проекта Google Cloud. - Требуется для использования Code Assist или Vertex AI. - - При использовании Vertex AI убедитесь, что у вас есть нужные права доступа в этом проекте. - - **Примечание для Cloud Shell:** При запуске в среде Cloud Shell эта переменная по умолчанию указывает на специальный проект, выделенный для пользователей Cloud Shell. Если у вас уже установлена переменная `GOOGLE_CLOUD_PROJECT` в глобальном окружении Cloud Shell, она будет переопределена этим значением. Чтобы использовать другой проект в Cloud Shell, необходимо задать `GOOGLE_CLOUD_PROJECT` в файле `.env`. + - При использовании Vertex AI убедитесь, что у вас есть необходимые права доступа в этом проекте. + - **Примечание для Cloud Shell:** При запуске в среде Cloud Shell эта переменная по умолчанию указывает на специальный проект, выделенный для пользователей Cloud Shell. Если у вас уже установлена переменная `GOOGLE_CLOUD_PROJECT` в глобальном окружении Cloud Shell, она будет переопределена этим значением. Чтобы использовать другой проект в Cloud Shell, необходимо определить `GOOGLE_CLOUD_PROJECT` в файле `.env`. - Пример: `export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. - **`GOOGLE_APPLICATION_CREDENTIALS`** (строка): - **Описание:** Путь к JSON-файлу с учётными данными Google Application. - **Пример:** `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"` - **`OTLP_GOOGLE_CLOUD_PROJECT`**: - - ID вашего проекта в Google Cloud для телеметрии. + - ID вашего проекта Google Cloud для телеметрии. - Пример: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. - **`GOOGLE_CLOUD_LOCATION`**: - - Регион вашего проекта в Google Cloud (например, `us-central1`). + - Регион вашего проекта Google Cloud (например, `us-central1`). - Требуется для использования Vertex AI в не-express режиме. - Пример: `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`. - **`GEMINI_SANDBOX`**: - Альтернатива настройке `sandbox` в `settings.json`. - - Принимает значения: `true`, `false`, `docker`, `podman` или строку с кастомной командой. + - Принимает значения: `true`, `false`, `docker`, `podman` или строку с пользовательской командой. - **`SEATBELT_PROFILE`** (только для macOS): - Переключает профиль Seatbelt (`sandbox-exec`) в macOS. - `permissive-open`: (по умолчанию) Ограничивает запись в папку проекта (и несколько других, см. `packages/cli/src/utils/sandbox-macos-permissive-open.sb`), но разрешает другие операции. - `strict`: Использует строгий профиль, который по умолчанию блокирует операции. - - ``: Использует кастомный профиль. Чтобы определить кастомный профиль, создайте файл с именем `sandbox-macos-.sb` в директории `.qwen/` вашего проекта (например, `my-project/.qwen/sandbox-macos-custom.sb`). + - ``: Использует пользовательский профиль. Чтобы определить свой профиль, создайте файл с именем `sandbox-macos-.sb` в директории `.qwen/` вашего проекта (например, `my-project/.qwen/sandbox-macos-custom.sb`). - **`DEBUG` или `DEBUG_MODE`** (часто используются библиотеками или самим CLI): - - Установите в `true` или `1`, чтобы включить подробный debug-лог, полезный при отладке. - - **Примечание:** Эти переменные по умолчанию исключаются из проектных `.env` файлов, чтобы не мешать работе CLI. Если вам нужно задать их для Qwen Code, используйте файлы `.qwen/.env`. + - Установите значение `true` или `1`, чтобы включить подробный режим отладки, что может быть полезно при устранении неполадок. + - **Примечание:** Эти переменные по умолчанию исключаются из проектных `.env` файлов, чтобы не мешать работе CLI. Если вам нужно установить их специально для Qwen Code, используйте файлы `.qwen/.env`. - **`NO_COLOR`**: - Установите любое значение, чтобы отключить цветной вывод в CLI. - **`CLI_TITLE`**: @@ -339,14 +340,14 @@ CLI автоматически загружает переменные окру - Указывает endpoint сервера code assist. - Полезно при разработке и тестировании. - **`TAVILY_API_KEY`**: - - Ваш API key для сервиса веб-поиска Tavily. + - Ваш API ключ для сервиса веб-поиска Tavily. - Требуется для включения функциональности инструмента `web_search`. - Если не настроено, инструмент веб-поиска будет отключён и пропущен. - Пример: `export TAVILY_API_KEY="tvly-your-api-key-here"` ## Аргументы командной строки -Аргументы, переданные напрямую при запуске CLI, могут переопределять другие настройки для текущей сессии. +Аргументы, переданные напрямую при запуске CLI, могут переопределять другие конфигурации для текущей сессии. - **`--model `** (**`-m `**): - Указывает модель Gemini, которая будет использоваться в этой сессии. @@ -359,11 +360,11 @@ CLI автоматически загружает переменные окру - Не может использоваться при передаче ввода через stdin. - Пример: `qwen -i "explain this code"` - **`--sandbox`** (**`-s`**): - - Включает режим песочницы для текущей сессии. + - Включает режим sandbox для этой сессии. - **`--sandbox-image`**: - - Устанавливает URI образа песочницы. + - Устанавливает URI образа sandbox. - **`--debug`** (**`-d`**): - - Включает режим отладки для текущей сессии, обеспечивая более подробный вывод. + - Включает режим отладки для этой сессии, обеспечивая более подробный вывод. - **`--all-files`** (**`-a`**): - Если установлен, рекурсивно включает все файлы в текущей директории в качестве контекста для prompt. - **`--help`** (или **`-h`**): @@ -372,6 +373,13 @@ CLI автоматически загружает переменные окру - Отображает текущее использование памяти. - **`--yolo`**: - Включает режим YOLO, при котором автоматически одобряются все вызовы инструментов. +- **`--approval-mode `**: + - Устанавливает режим подтверждения для вызовов инструментов. Доступные режимы: + - `default`: Запрашивать подтверждение для каждого вызова инструмента (поведение по умолчанию) + - `auto_edit`: Автоматически одобрять инструменты редактирования (replace, write_file), запрашивать подтверждение для остальных + - `yolo`: Автоматически одобрять все вызовы инструментов (эквивалент `--yolo`) + - Не может использоваться вместе с `--yolo`. Используйте `--approval-mode=yolo` вместо `--yolo` для нового унифицированного подхода. + - Пример: `qwen --approval-mode auto_edit` - **`--telemetry`**: - Включает [телеметрию](../telemetry.md). - **`--telemetry-target`**: @@ -389,30 +397,30 @@ CLI автоматически загружает переменные окру - **`--list-extensions`** (**`-l`**): - Выводит список всех доступных расширений и завершает работу. - **`--proxy`**: - - Устанавливает прокси для CLI. + - Устанавливает proxy для 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` - **`--version`**: - Отображает версию CLI. - **`--openai-logging`**: - Включает логирование вызовов OpenAI API для отладки и анализа. Этот флаг переопределяет настройку `enableOpenAILogging` в `settings.json`. - **`--tavily-api-key `**: - - Устанавливает API-ключ Tavily для функции веб-поиска в текущей сессии. + - Устанавливает Tavily API key для функции веб-поиска в этой сессии. - Пример: `qwen --tavily-api-key tvly-your-api-key-here` ## Файлы контекста (иерархический instructional context) -Хотя эти файлы и не являются строгой конфигурацией _поведения_ CLI, файлы контекста (по умолчанию `QWEN.md`, но настраиваемые через параметр `contextFileName`) играют ключевую роль в настройке _инструкционного контекста_ (также называемого "памятью"). Эта мощная функция позволяет передавать AI проектные инструкции, руководства по стилю кодирования или любую другую релевантную информацию, благодаря чему ответы модели становятся более точными и соответствующими вашим потребностям. CLI включает элементы UI, например индикатор в нижнем колонтитуле, показывающий количество загруженных файлов контекста, чтобы вы всегда могли видеть активный контекст. +Хотя файлы контекста не являются строгой конфигурацией _поведения_ CLI, они играют ключевую роль в настройке _инструкционного контекста_ (также называемого "памятью"). По умолчанию используется файл `QWEN.md`, но имя файла можно изменить с помощью настройки `contextFileName`. Эта мощная функция позволяет передавать ИИ проектные инструкции, руководства по стилю кода или любую другую релевантную информацию, благодаря чему ответы модели становятся более точными и соответствующими вашим потребностям. CLI включает элементы UI, например индикатор в нижнем колонтитуле, показывающий количество загруженных файлов контекста, чтобы вы всегда были в курсе активного контекста. - **Назначение:** Эти Markdown-файлы содержат инструкции, руководящие принципы или контекст, о котором вы хотите, чтобы модель Gemini знала во время взаимодействия. Система спроектирована так, чтобы управлять этим инструкционным контекстом иерархически. ### Пример содержимого контекстного файла (например, `QWEN.md`) -Вот концептуальный пример того, что может содержаться в контекстном файле в корне проекта на TypeScript: +Вот концептуальный пример того, что может содержать контекстный файл в корне проекта на TypeScript: ```markdown @@ -422,7 +430,7 @@ CLI автоматически загружает переменные окру - При генерации нового кода на TypeScript следуйте существующему стилю кодирования. - Убедитесь, что все новые функции и классы сопровождаются комментариями JSDoc. -- Предпочтение отдавайте парадигмам функционального программирования, где это уместно. +- Предпочтительно использовать парадигмы функционального программирования, где это уместно. - Весь код должен быть совместим с TypeScript 5.0 и Node.js 20+. ## Стиль кодирования: @@ -434,7 +442,7 @@ CLI автоматически загружает переменные окру ## Конкретный компонент: `src/api/client.ts` -- Этот файл отвечает за все исходящие API-запросы. +- Этот файл обрабатывает все исходящие API-запросы. - При добавлении новых функций для API-вызовов убедитесь, что они включают надежную обработку ошибок и логирование. - Используйте существующую утилиту `fetchWithRetry` для всех GET-запросов. ``` @@ -445,26 +453,26 @@ CLI автоматически загружает переменные окру - Если новая зависимость необходима, пожалуйста, укажите причину. ``` -Этот пример демонстрирует, как можно предоставить общий контекст проекта, конкретные соглашения о кодировании, а также заметки о конкретных файлах или компонентах. Чем более релевантны и точны ваши контекстные файлы, тем лучше ИИ сможет вам помочь. Настоятельно рекомендуется использовать специфичные для проекта контекстные файлы, чтобы установить соглашения и контекст. +Этот пример демонстрирует, как можно предоставить общий контекст проекта, конкретные соглашения о кодировании, а также заметки о конкретных файлах или компонентах. Чем более релевантными и точными являются ваши контекстные файлы, тем лучше ИИ сможет вам помочь. Настоятельно рекомендуется использовать специфичные для проекта контекстные файлы для установления соглашений и контекста. -- **Иерархическая загрузка и приоритет:** 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`. + - Расположение: CLI также сканирует наличие указанного контекстного файла в подкаталогах _ниже_ текущей рабочей директории (с учетом стандартных шаблонов игнорирования, таких как `node_modules`, `.git` и т.д.). По умолчанию глубина поиска ограничена 200 каталогами, но может быть изменена с помощью поля `memoryDiscoveryMaxDirs` в вашем файле `settings.json`. - Область применения: Позволяет задать очень специфичные инструкции, относящиеся к конкретному компоненту, модулю или разделу проекта. -- **Объединение и отображение в интерфейсе:** Содержимое всех найденных контекстных файлов объединяется (с разделителями, указывающими их источник и путь) и передается как часть системного промпта. В нижнем колонтитуле CLI отображается количество загруженных контекстных файлов — это позволяет быстро понять, какой объем инструкций активен в данный момент. -- **Импорт содержимого:** Вы можете модульно организовать свои контекстные файлы, импортируя другие Markdown-файлы с помощью синтаксиса `@path/to/file.md`. Подробнее см. в [документации по Memory Import Processor](../core/memport.md). +- **Объединение и отображение в интерфейсе:** Содержимое всех найденных контекстных файлов объединяется (с разделителями, указывающими их источник и путь) и передается как часть системного 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 под свои конкретные задачи и проекты. +Понимая и используя эти уровни конфигурации и иерархическую природу контекстных файлов, вы сможете эффективно управлять памятью ИИ и адаптировать ответы Qwen Code под ваши конкретные нужды и проекты. ## Sandboxing @@ -474,16 +482,16 @@ Qwen Code может выполнять потенциально небезоп - Используя флаг `--sandbox` или `-s`. - Установив переменную окружения `GEMINI_SANDBOX`. -- Sandbox включён по умолчанию в режиме `--yolo`. +- Sandbox включается по умолчанию при использовании `--yolo` или `--approval-mode=yolo`. -По умолчанию используется предварительно собранный Docker-образ `qwen-code-sandbox`. +По умолчанию используется готовый Docker-образ `qwen-code-sandbox`. -Если вашему проекту требуется специфичная sandbox-конфигурация, вы можете создать собственный Dockerfile по пути `.qwen/sandbox.Dockerfile` в корневой директории проекта. Этот Dockerfile может быть основан на базовом sandbox-образе: +Если вашему проекту требуется особое sandbox-окружение, вы можете создать собственный Dockerfile по пути `.qwen/sandbox.Dockerfile` в корневой директории проекта. Этот Dockerfile может быть основан на базовом sandbox-образе: ```dockerfile FROM qwen-code-sandbox -# Добавьте сюда ваши кастомные зависимости или настройки +# Добавьте сюда свои зависимости или настройки # Например: @@ -505,19 +513,19 @@ BUILD_SANDBOX=1 qwen -s **Что мы собираем:** -- **Вызовы инструментов:** Мы записываем названия вызываемых инструментов, информацию об успешном или неудачном выполнении и время их работы. Мы не собираем аргументы, передаваемые инструментам, и не сохраняем данные, возвращаемые ими. -- **API-запросы:** Мы записываем модель, использованную в каждом запросе, продолжительность запроса и информацию об успешном выполнении. Мы не собираем содержимое промтов или ответов. -- **Информация о сессии:** Мы собираем информацию о конфигурации CLI, например, список включенных инструментов и режим подтверждения. +- **Вызовы инструментов:** Мы записываем названия вызываемых инструментов, информацию об успешном или неудачном выполнении и время их выполнения. Мы не собираем аргументы, передаваемые инструментам, или любые данные, возвращаемые ими. +- **API запросы:** Мы записываем модель, использованную для каждого запроса, продолжительность запроса и информацию об успешном или неудачном выполнении. Мы не собираем содержимое промптов или ответов. +- **Информация о сессии:** Мы собираем информацию о конфигурации CLI, например, включенные инструменты и режим подтверждения. **Что мы НЕ собираем:** -- **Персональные данные (PII):** Мы не собираем никакой персональной информации, такой как ваше имя, адрес электронной почты или API-ключи. -- **Содержимое промтов и ответов:** Мы не записываем содержимое ваших промтов или ответов модели. +- **Персональные данные (PII):** Мы не собираем никакой личной информации, такой как ваше имя, адрес электронной почты или API ключи. +- **Содержимое промптов и ответов:** Мы не записываем содержимое ваших промптов или ответов модели. - **Содержимое файлов:** Мы не записываем содержимое файлов, которые читаются или записываются CLI. -**Как отключить сбор статистики:** +**Как отказаться от сбора:** -Вы можете отключить сбор статистики использования в любое время, установив значение свойства `usageStatisticsEnabled` в `false` в вашем файле `settings.json`: +Вы можете отказаться от сбора статистики использования в любое время, установив значение свойства `usageStatisticsEnabled` в `false` в вашем файле `settings.json`: ```json { @@ -525,4 +533,4 @@ BUILD_SANDBOX=1 qwen -s } ``` -Примечание: Когда сбор статистики включен, события отправляются на endpoint сбора данных Alibaba Cloud RUM. \ No newline at end of file +Примечание: Когда сбор статистики использования включен, события отправляются на endpoint сбора данных Alibaba Cloud RUM. \ No newline at end of file diff --git a/website/content/ru/deployment.md b/website/content/ru/deployment.md index 4e34fced..a4f4829a 100644 --- a/website/content/ru/deployment.md +++ b/website/content/ru/deployment.md @@ -27,7 +27,7 @@ - **Запуск через NPX:** ```bash - # Выполнить последнюю версию из NPM без глобальной установки + # Запустить последнюю версию из NPM без глобальной установки npx @qwen-code/qwen-code ``` @@ -41,7 +41,7 @@ Вы можете запустить опубликованный образ песочницы напрямую. Это удобно для сред, где у вас есть только Docker и вы хотите запустить CLI. ```bash # Запуск опубликованного образа песочницы - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.7 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.9 ``` - **Использование флага `--sandbox`:** Если у вас локально установлен Qwen Code (с использованием стандартной установки, описанной выше), вы можете указать ему запускаться внутри контейнера песочницы. @@ -65,7 +65,7 @@ Этот метод имитирует глобальную установку, связывая ваш локальный пакет. Полезно для тестирования локальной сборки в production-сценарии. ```bash - # Свяжите локальный cli пакет с глобальным node_modules + # Связываем локальный cli-пакет с глобальным node_modules npm link packages/cli # Теперь вы можете запускать свою локальную версию с помощью команды `qwen` @@ -74,9 +74,9 @@ --- -### 4. Запуск последнего коммита Qwen Code с GitHub +### 4. Запуск последнего коммита Qwen Code из GitHub -Вы можете запустить последнюю закоммиченную версию Qwen Code напрямую из репозитория на GitHub. Это удобно для тестирования функций, находящихся в разработке. +Вы можете запустить самую свежую версию Qwen Code напрямую из репозитория на GitHub. Это удобно для тестирования функций, находящихся в разработке. ```bash @@ -114,5 +114,5 @@ npx https://github.com/QwenLM/qwen-code Процесс релиза автоматизирован с помощью GitHub Actions. Workflow релиза выполняет следующие действия: 1. Собирает NPM пакеты с использованием `tsc`. -2. Публикует NPM пакеты в artifact registry. -3. Создает релизы в GitHub с приложенными assets. \ No newline at end of file +2. Публикует NPM пакеты в реестре артефактов. +3. Создает релизы GitHub с bundled assets. \ No newline at end of file diff --git a/website/content/ru/ide-integration.md b/website/content/ru/ide-integration.md new file mode 100644 index 00000000..8476fcf4 --- /dev/null +++ b/website/content/ru/ide-integration.md @@ -0,0 +1,141 @@ +# Интеграция с IDE + +Gemini CLI может интегрироваться с вашей IDE для более удобной и контекстно-зависимой работы. Эта интеграция позволяет CLI лучше понимать ваш workspace и включает мощные функции, такие как native in-editor diffing. + +На данный момент единственной поддерживаемой IDE является [Visual Studio Code](https://code.visualstudio.com/), а также другие редакторы, которые поддерживают расширения VS Code. + +## Возможности + +- **Контекст рабочей области:** CLI автоматически получает информацию о вашей рабочей области для предоставления более релевантных и точных ответов. Этот контекст включает: + - **10 последних открытых файлов** в вашей рабочей области. + - Активную позицию курсора. + - Любой выделенный текст (до 16 КБ; более длинные выделения будут обрезаны). + +- **Встроенный diff:** Когда Gemini предлагает изменения в коде, вы можете просматривать эти изменения прямо во встроенном diff-редакторе вашей IDE. Это позволяет легко просматривать, редактировать, а также принимать или отклонять предложенные изменения. + +- **Команды VS Code:** Вы можете использовать функции Gemini CLI прямо из Command Palette в VS Code (`Cmd+Shift+P` или `Ctrl+Shift+P`): + - `Gemini CLI: Run`: Запускает новую сессию Gemini CLI во встроенном терминале. + - `Gemini CLI: Accept Diff`: Принимает изменения в активном diff-редакторе. + - `Gemini CLI: Close Diff Editor`: Отклоняет изменения и закрывает активный diff-редактор. + - `Gemini CLI: View Third-Party Notices`: Открывает уведомления о сторонних библиотеках, используемых в расширении. + +## Установка и настройка + +Есть три способа настроить интеграцию с IDE: + +### 1. Автоматическое подключение (рекомендуется) + +Когда вы запускаете Gemini CLI внутри поддерживаемого редактора, он автоматически определит вашу среду и предложит подключиться. Если вы ответите «Да», автоматически выполнится необходимая настройка, включая установку расширения-компаньона и включение соединения. + +### 2. Ручная установка через CLI + +Если вы ранее отклонили запрос или хотите установить расширение вручную, вы можете выполнить следующую команду внутри Gemini CLI: + +``` +/ide install +``` + +Эта команда найдет правильное расширение для вашей IDE и установит его. + +### 3. Ручная установка из маркетплейса + +Вы также можете установить расширение напрямую из маркетплейса. + +- **Для Visual Studio Code:** Установите из [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=google.gemini-cli-vscode-ide-companion). +- **Для форков VS Code:** Чтобы поддерживать форки VS Code, расширение также опубликовано в [Open VSX Registry](https://open-vsx.org/extension/google/gemini-cli-vscode-ide-companion). Следуйте инструкциям вашего редактора для установки расширений из этого реестра. + +После любого метода установки рекомендуется открыть новое окно терминала, чтобы интеграция активировалась корректно. После установки вы можете использовать `/ide enable` для подключения. + +## Использование + +### Включение и отключение + +Вы можете управлять интеграцией с IDE прямо из CLI: + +- Чтобы включить подключение к IDE, выполните: + ``` + /ide enable + ``` +- Чтобы отключить подключение, выполните: + ``` + /ide disable + ``` + +Когда подключение включено, Gemini CLI автоматически попытается подключиться к companion extension в IDE. + +### Проверка статуса + +Чтобы проверить статус подключения и посмотреть контекст, который CLI получил от IDE, выполните: + +``` +/ide status +``` + +Если подключение установлено, эта команда покажет, к какой IDE подключен CLI, и список недавно открытых файлов, о которых он знает. + +(Примечание: Список файлов ограничен 10 последними открытыми файлами в вашем workspace и включает только локальные файлы на диске.) + +### Работа с Diffs + +Когда вы просите Gemini изменить файл, он может открыть diff-представление прямо в вашем редакторе. + +**Чтобы принять diff**, вы можете выполнить любое из следующих действий: + +- Нажать **иконку с галочкой** в заголовке diff-редактора. +- Сохранить файл (например, с помощью `Cmd+S` или `Ctrl+S`). +- Открыть Command Palette и выполнить команду **Gemini CLI: Accept Diff**. +- Ответить `yes` в CLI при запросе. + +**Чтобы отклонить diff**, вы можете: + +- Нажать **иконку 'x'** в заголовке diff-редактора. +- Закрыть вкладку diff-редактора. +- Открыть Command Palette и выполнить команду **Gemini CLI: Close Diff Editor**. +- Ответить `no` в CLI при запросе. + +Вы также можете **изменить предложенные изменения** прямо в diff-представлении перед их принятием. + +Если вы выберете ‘Yes, allow always’ в CLI, изменения больше не будут отображаться в IDE, так как они будут автоматически приниматься. + +## Использование в песочнице + +Если вы используете Gemini CLI в песочнице, обратите внимание на следующее: + +- **На macOS:** Для интеграции с IDE требуется доступ к сети, чтобы взаимодействовать с расширением-компаньоном IDE. Вы должны использовать профиль Seatbelt, который разрешает доступ к сети. +- **В Docker-контейнере:** Если вы запускаете Gemini CLI внутри контейнера Docker (или Podman), интеграция с IDE все равно сможет подключиться к расширению VS Code, запущенному на вашей хост-машине. CLI настроен автоматически находить сервер IDE по адресу `host.docker.internal`. Обычно никакой специальной настройки не требуется, но вам может понадобиться убедиться, что ваша настройка Docker networking разрешает подключения из контейнера к хосту. + +## Устранение неполадок + +Если у вас возникли проблемы с интеграцией IDE, вот несколько распространенных сообщений об ошибках и способы их устранения. + +### Ошибки подключения + +- **Сообщение:** `🔴 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.` + - **Причина:** Gemini CLI не смог найти необходимые переменные окружения (`GEMINI_CLI_IDE_WORKSPACE_PATH` или `GEMINI_CLI_IDE_SERVER_PORT`) для подключения к IDE. Обычно это означает, что companion extension для IDE не запущен или не инициализировался корректно. + - **Решение:** + 1. Убедитесь, что вы установили расширение **Gemini CLI Companion** в вашей IDE и что оно включено. + 2. Откройте новое окно терминала в вашей IDE, чтобы убедиться, что оно получает правильные переменные окружения. + +- **Сообщение:** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` + - **Причина:** Соединение с companion extension было потеряно. + - **Решение:** Выполните команду `/ide enable`, чтобы попытаться переподключиться. Если проблема сохраняется, откройте новое окно терминала или перезапустите вашу IDE. + +### Ошибки конфигурации + +- **Сообщение:** `🔴 Disconnected: Directory mismatch. Gemini CLI 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 находится вне папки или 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. + +### Общие ошибки + +- **Сообщение:** `IDE integration is not supported in your current environment. To use this feature, run Gemini CLI in one of these supported IDEs: [List of IDEs]` + - **Причина:** Вы запускаете Gemini CLI в терминале или среде, которая не является поддерживаемой IDE. + - **Решение:** Запустите Gemini CLI из встроенного терминала поддерживаемой IDE, например VS Code. + +- **Сообщение:** `No installer is available for [IDE Name]. Please install the IDE companion manually from its marketplace.` + - **Причина:** Вы выполнили команду `/ide install`, но CLI не имеет автоматического установщика для вашей конкретной IDE. + - **Решение:** Откройте маркетплейс расширений вашей IDE, найдите "Gemini CLI Companion" и установите его вручную. \ No newline at end of file diff --git a/website/content/ru/index.md b/website/content/ru/index.md index 859e8300..e2e521b0 100644 --- a/website/content/ru/index.md +++ b/website/content/ru/index.md @@ -18,19 +18,20 @@ Qwen Code предоставляет возможности продвинуты - **[Конфигурация](./cli/configuration.md):** Информация о настройке CLI. - **[Контрольные точки](./checkpointing.md):** Документация по функции контрольных точек. - **[Расширения](./extension.md):** Как расширить CLI новыми функциями. + - **[Интеграция с IDE](./ide-integration.md):** Подключение CLI к вашему редактору. - **[Телеметрия](./telemetry.md):** Обзор телеметрии в CLI. - **Детали ядра:** Документация для `packages/core`. - **[Введение в ядро](./core/index.md):** Обзор основного компонента. - - **[API инструментов](./core/tools-api.md):** Информация о том, как ядро управляет и предоставляет инструменты. + - **[API инструментов](./core/tools-api.md):** Информация о том, как ядро управляет и предоставляет доступ к инструментам. - **Инструменты:** - **[Обзор инструментов](./tools/index.md):** Обзор доступных инструментов. - - **[Инструменты файловой системы](./tools/file-system.md):** Документация по инструментам `read_file` и `write_file`. - - **[Инструмент чтения нескольких файлов](./tools/multi-file.md):** Документация по инструменту `read_many_files`. - - **[Shell-инструмент](./tools/shell.md):** Документация по инструменту `run_shell_command`. - - **[Инструмент веб-запросов](./tools/web-fetch.md):** Документация по инструменту `web_fetch`. - - **[Инструмент веб-поиска](./tools/web-search.md):** Документация по инструменту `web_search`. - - **[Инструмент памяти](./tools/memory.md):** Документация по инструменту `save_memory`. -- **[Руководство по участию и разработке](../CONTRIBUTING.md):** Информация для контрибьюторов и разработчиков, включая установку, сборку, тестирование и соглашения по кодированию. + - **[Инструменты файловой системы](./tools/file-system.md):** Документация для инструментов `read_file` и `write_file`. + - **[Инструмент чтения нескольких файлов](./tools/multi-file.md):** Документация для инструмента `read_many_files`. + - **[Shell-инструмент](./tools/shell.md):** Документация для инструмента `run_shell_command`. + - **[Инструмент веб-запросов](./tools/web-fetch.md):** Документация для инструмента `web_fetch`. + - **[Инструмент веб-поиска](./tools/web-search.md):** Документация для инструмента `web_search`. + - **[Инструмент памяти](./tools/memory.md):** Документация для инструмента `save_memory`. +- **[Руководство по участию и разработке](../CONTRIBUTING.md):** Информация для контрибьюторов и разработчиков, включая установку, сборку, тестирование и соглашения о кодировании. - **[NPM Workspaces и публикация](./npm.md):** Подробности о том, как управляются и публикуются пакеты проекта. - **[Руководство по устранению неполадок](./troubleshooting.md):** Найдите решения распространенных проблем и часто задаваемых вопросов. - **[Условия использования и политика конфиденциальности](./tos-privacy.md):** Информация об условиях использования и уведомлениях о конфиденциальности, применимых к вашему использованию Qwen Code. diff --git a/website/content/ru/integration-tests.md b/website/content/ru/integration-tests.md index e6f27867..07b774d1 100644 --- a/website/content/ru/integration-tests.md +++ b/website/content/ru/integration-tests.md @@ -12,7 +12,7 @@ Интеграционные тесты не запускаются по умолчанию командой `npm run test`. Их нужно запускать явно, используя скрипт `npm run test:integration:all`. -Также интеграционные тесты можно запустить, используя следующий ярлык: +Интеграционные тесты также можно запустить, используя следующий ярлык: ```bash npm run test:e2e @@ -61,20 +61,13 @@ npm run test:integration:sandbox:podman ## Диагностика -Test runner интеграционных тестов предоставляет несколько опций для диагностики, которые помогут отследить причины падений тестов. +Test runner интеграционных тестов предоставляет несколько опций диагностики, которые помогут отследить причины падений тестов. ### Сохранение вывода тестов Вы можете сохранить временные файлы, созданные во время запуска тестов, для последующего анализа. Это полезно при отладке проблем с операциями файловой системы. -Чтобы сохранить вывод тестов, можно либо использовать флаг `--keep-output`, либо установить переменную окружения `KEEP_OUTPUT` в значение `true`. - -```bash - -# С использованием флага -npm run test:integration:sandbox:none -- --keep-output - -# Использование переменной окружения +Чтобы сохранить вывод тестов, установите переменную окружения `KEEP_OUTPUT` в значение `true`. ```bash KEEP_OUTPUT=true npm run test:integration:sandbox:none @@ -82,27 +75,27 @@ KEEP_OUTPUT=true npm run test:integration:sandbox:none Если вывод сохраняется, test runner выведет путь к уникальному каталогу для этого запуска тестов. -### Подробный вывод (Verbose output) +### Подробный вывод -Для более детальной отладки флаг `--verbose` передаёт вывод команды `qwen` в реальном времени прямо в консоль. +Для более детальной отладки установите переменную окружения `VERBOSE` в значение `true`. ```bash -npm run test:integration:sandbox:none -- --verbose +VERBOSE=true npm run test:integration:sandbox:none ``` -Если в одной команде используются одновременно `--verbose` и `--keep-output`, то вывод будет отображаться в консоли и также сохраняться в log-файл внутри временного каталога теста. +При одновременном использовании `VERBOSE=true` и `KEEP_OUTPUT=true` в одной команде вывод будет направлен в консоль и также сохранен в лог-файл внутри временной директории теста. Формат подробного вывода позволяет легко определить источник логов: ``` ---- TEST: : --- +--- TEST: : --- ... вывод от команды qwen ... ---- END TEST: : --- +--- END TEST: : --- ``` ## Линтинг и форматирование -Для обеспечения качества и единообразия кода, файлы интеграционных тестов проходят линтинг в рамках основного процесса сборки. Также можно вручную запустить линтер и автоисправление. +Для обеспечения качества и консистентности кода, файлы интеграционных тестов проходят линтинг в рамках основного процесса сборки. Вы также можете вручную запустить линтер и автофиксер. ### Запуск линтера @@ -112,7 +105,7 @@ npm run test:integration:sandbox:none -- --verbose npm run lint ``` -Вы можете добавить флаг `:fix` к команде, чтобы автоматически исправить все ошибки линтинга, которые можно исправить: +Вы можете добавить флаг `:fix` к команде, чтобы автоматически исправить все исправляемые ошибки линтинга: ```bash npm run lint:fix @@ -120,9 +113,9 @@ npm run lint:fix ## Структура директорий -Интеграционные тесты создают уникальную директорию для каждого запуска теста внутри директории `.integration-tests`. В этой директории создается поддиректория для каждого тестового файла, а внутри нее — поддиректория для каждого отдельного тест-кейса. +Интеграционные тесты создают уникальную директорию для каждого запуска тестов внутри директории `.integration-tests`. В этой директории создаётся поддиректория для каждого тестового файла, а внутри неё — поддиректория для каждого отдельного тест-кейса. -Такая структура позволяет легко находить артефакты для конкретного запуска теста, файла или кейса. +Такая структура позволяет легко находить артефакты для конкретного запуска тестов, файла или кейса. ``` .integration-tests/ @@ -130,7 +123,7 @@ npm run lint:fix └── .test.js/ └── / ├── output.log - └── ...другие артефакты теста... + └── ...other test artifacts... ``` ## Непрерывная интеграция @@ -139,6 +132,6 @@ npm run lint:fix Workflow запускает тесты в различных средах песочницы, чтобы убедиться, что Qwen Code тестируется в каждой из них: -- `sandbox:none`: Запускает тесты без какой-либо песочницы. -- `sandbox:docker`: Запускает тесты в Docker-контейнере. -- `sandbox:podman`: Запускает тесты в Podman-контейнере. \ No newline at end of file +- `sandbox:none`: Запуск тестов без какой-либо песочницы. +- `sandbox:docker`: Запуск тестов в Docker-контейнере. +- `sandbox:podman`: Запуск тестов в Podman-контейнере. \ No newline at end of file diff --git a/website/content/ru/npm.md b/website/content/ru/npm.md index c221e9be..6b81a2fa 100644 --- a/website/content/ru/npm.md +++ b/website/content/ru/npm.md @@ -1,18 +1,18 @@ # Обзор пакета -Этот монорепозиторий содержит два основных пакета: `@qwen-code/qwen-code` и `@qwen-code/qwen-code-core`. +Этот monorepo содержит два основных пакета: `@qwen-code/qwen-code` и `@qwen-code/qwen-code-core`. ## `@qwen-code/qwen-code` Это основной пакет для Qwen Code. Он отвечает за пользовательский интерфейс, парсинг команд и весь другой функционал, с которым взаимодействует пользователь. -Когда этот пакет публикуется, он собирается в один исполняемый файл. Этот бандл включает все зависимости пакета, включая `@qwen-code/qwen-code-core`. Это означает, что независимо от того, устанавливает ли пользователь пакет через `npm install -g @qwen-code/qwen-code` или запускает его напрямую через `npx @qwen-code/qwen-code`, он использует этот единственный, самодостаточный исполняемый файл. +При публикации этот пакет собирается в один исполняемый файл. В этот бандл включены все зависимости пакета, включая `@qwen-code/qwen-code-core`. Это означает, что независимо от того, устанавливает ли пользователь пакет с помощью `npm install -g @qwen-code/qwen-code` или запускает его напрямую через `npx @qwen-code/qwen-code`, он использует этот единственный, самодостаточный исполняемый файл. ## `@qwen-code/qwen-code-core` Этот пакет содержит основную логику для CLI. Он отвечает за выполнение API-запросов к настроенным провайдерам, обработку аутентификации и управление локальным кэшем. -Этот пакет не собирается в бандл. При публикации он выпускается как стандартный Node.js пакет со своими собственными зависимостями. Это позволяет использовать его как отдельный пакет в других проектах, если это необходимо. Весь транспилированный js-код в папке `dist` включается в пакет. +Этот пакет не является bundled. При публикации он выпускается как стандартный Node.js пакет со своими собственными зависимостями. Это позволяет использовать его как отдельный пакет в других проектах, если это необходимо. В пакет включён весь транспилированный js-код из папки `dist`. # Процесс релиза @@ -37,18 +37,18 @@ ### Процесс -Каждую ночь в 00:00 UTC автоматически запускается [Release workflow](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml). Он выполняет следующие шаги: +Каждую ночь в 00:00 UTC автоматически запускается [Release workflow](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) по расписанию. Он выполняет следующие шаги: -1. Выполняет checkout последнего кода из ветки `main`. -2. Устанавливает все зависимости. -3. Запускает полный набор проверок `preflight` и интеграционных тестов. -4. Если все тесты пройдены успешно, вычисляет номер следующей nightly-версии (например, `v0.2.1-nightly.20230101`). -5. Затем собирает и публикует пакеты в npm с dist-tag `nightly`. -6. Наконец, создает GitHub Release для nightly-версии. +1. Выполняет checkout последнего кода из ветки `main`. +2. Устанавливает все зависимости. +3. Запускает полный набор проверок `preflight` и интеграционных тестов. +4. Если все тесты пройдены успешно, вычисляет следующий номер ночной версии (например, `v0.2.1-nightly.20230101`). +5. Затем собирает и публикует пакеты в npm с dist-tag `nightly`. +6. Наконец, создает GitHub Release для ночной версии. ### Обработка ошибок -Если какой-либо шаг в nightly workflow завершается с ошибкой, автоматически создается новый issue в репозитории с метками `bug` и `nightly-failure`. В issue будет содержаться ссылка на неудавшийся запуск workflow для удобства отладки. +Если какой-либо шаг в ночном workflow завершится с ошибкой, автоматически будет создан новый issue в репозитории с метками `bug` и `nightly-failure`. В issue будет содержаться ссылка на неудачный запуск workflow для удобства отладки. ### Как использовать Nightly Build @@ -58,80 +58,79 @@ npm install -g @qwen-code/qwen-code@nightly ``` -Мы также запускаем Google Cloud Build под названием [release-docker.yml](../.gcp/release-docker.yaml), который публикует sandbox Docker-образ, соответствующий вашему релизу. После настройки разрешений для service account, этот процесс также будет перенесён в GitHub и объединён с основным release-файлом. +Мы также запускаем Google Cloud Build под названием [release-docker.yml](../.gcp/release-docker.yml), который публикует sandbox Docker-образ, соответствующий вашему релизу. После настройки разрешений для service account, этот процесс также будет перенесён в GitHub и объединён с основным release-файлом. ### После релиза -После успешного завершения workflow вы можете отслеживать его выполнение во вкладке [GitHub Actions](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml). После завершения необходимо: +После успешного завершения workflow вы можете отслеживать его выполнение на вкладке [GitHub Actions](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml). После завершения необходимо: -1. Перейти на страницу [Pull Requests](https://github.com/QwenLM/qwen-code/pulls) репозитория. -2. Создать новый pull request из ветки `release/vX.Y.Z` в `main`. +1. Перейти на страницу [pull requests](https://github.com/QwenLM/qwen-code/pulls) репозитория. +2. Создать новый pull request из ветки `release/vX.Y.Z` в ветку `main`. 3. Проверить pull request (он должен содержать только обновления версий в файлах `package.json`) и выполнить слияние (merge). Это позволит поддерживать актуальную версию в ветке `main`. ## Валидация релиза После пуша нового релиза необходимо провести smoke testing, чтобы убедиться, что пакеты работают корректно. Это можно сделать, установив пакеты локально и запустив набор тестов для проверки их функциональности. -- `npx -y @qwen-code/qwen-code@latest --version` — проверка, что пуш прошёл успешно (если вы не использовали теги rc или dev) -- `npx -y @qwen-code/qwen-code@ --version` — проверка, что тег был запушен корректно -- _Это действие разрушительно для локальной среды_: +- `npx -y @qwen-code/qwen-code@latest --version` — проверка, что пуш прошёл успешно, если вы не использовали теги rc или dev +- `npx -y @qwen-code/qwen-code@ --version` — проверка, что тег был запушен корректно +- _Это деструктивная операция для локальной среды_: `npm uninstall @qwen-code/qwen-code && npm uninstall -g @qwen-code/qwen-code && npm cache clean --force && npm install @qwen-code/qwen-code@` -- Рекомендуется выполнить базовый smoke тест, включающий запуск нескольких команд и инструментов LLM, чтобы убедиться, что пакеты работают как ожидается. В будущем мы формализуем этот процесс. +- Рекомендуется выполнить smoke тестирование, запустив базовые команды и инструменты LLM, чтобы убедиться, что пакеты работают как ожидается. В будущем мы формализуем этот процесс. ## Когда сливать изменения версии, а когда нет? -Описанный выше подход к созданию патч-релизов или hotfix-релизов из текущих или старых коммитов оставляет репозиторий в следующем состоянии: +Описанный выше подход к созданию патч- или хотфикс-релизов из текущих или старых коммитов оставляет репозиторий в следующем состоянии: -1. Тег (`vX.Y.Z-patch.1`): Этот тег корректно указывает на оригинальный коммит в ветке main, который содержит стабильный код, предназначенный для релиза. Это важно. Любой, кто сделает checkout этого тега, получит точную копию опубликованного кода. -2. Ветка (`release-vX.Y.Z-patch.1`): Эта ветка содержит один новый коммит поверх тегированного коммита. Этот новый коммит включает только изменение номера версии в package.json (и других связанных файлах, таких как package-lock.json). +1. Тег (`vX.Y.Z-patch.1`): Этот тег корректно указывает на оригинальный коммит в ветке main, + который содержит стабильный код, предназначенный для релиза. Это важно. Любой, кто сделает + checkout этого тега, получит в точности тот код, который был опубликован. +2. Ветка (`release-vX.Y.Z-patch.1`): Эта ветка содержит один новый коммит поверх + коммита с тегом. Этот новый коммит содержит только изменение номера версии в package.json + (и других связанных файлах, таких как package-lock.json). -Такое разделение полезно. Оно позволяет сохранить историю основной ветки без лишних коммитов с изменениями версий, пока вы явно не решите их слить. +Такое разделение полезно. Оно позволяет истории основной ветки оставаться чистой от изменений +номеров версий, специфичных для релизов, до тех пор, пока вы не решите их слить. Это ключевое решение, и оно полностью зависит от характера релиза. ### Merge Back для стабильных патчей и хотфиксов -Почти всегда необходимо мержить ветку `release-` обратно в `main` для любого -стабильного патча или релиза с хотфиксом. +Почти всегда нужно мержить ветку `release-` обратно в `main` для любого +стабильного патча или хотфикса. -- Зачем? Основная причина — обновление версии в package.json ветки main. Если вы делаете релиз, - например v1.2.1, из старого коммита, но не мержите изменение версии обратно, - package.json в вашей ветке main всё ещё будет содержать "version": "1.2.0". Следующий разработчик, - который начнёт работу над следующим фичерелизом (например, v1.3.0), будет работать с кодовой базой, - содержащей некорректную, устаревшую версию. Это вызывает путаницу и требует ручного обновления - версии позже. -- Процесс: После создания ветки release-v1.2.1 и успешной публикации пакета, - необходимо открыть pull request для мержа release-v1.2.1 в main. Этот PR - будет содержать всего один коммит: "chore: bump version to v1.2.1". Это чистая и простая - интеграция, которая поддерживает ветку main в актуальном состоянии с последней выпущенной версией. +- Зачем? Основная причина — обновление версии в package.json ветки main. Если вы выпускаете + v1.2.1 из старого коммита, но никогда не мержите обновление версии обратно, то package.json + в вашей основной ветке всё ещё будет содержать "version": "1.2.0". Следующий разработчик, + который начнёт работу над следующим фичерелизом (v1.3.0), будет создавать ветку от кодовой + базы с некорректным, устаревшим номером версии. Это вызывает путаницу и требует ручного + обновления версии позже. +- Процесс: После создания ветки release-v1.2.1 и успешной публикации пакета, вы должны + открыть pull request для мержа release-v1.2.1 в main. Этот PR будет содержать всего один + коммит: "chore: bump version to v1.2.1". Это чистая, простая интеграция, которая + поддерживает синхронизацию вашей основной ветки с последней выпущенной версией. ### НЕ выполняйте Merge Back для предварительных релизов (RC, Beta, Dev) Обычно вы не выполняете слияние веток релизов для предварительных релизов обратно в `main`. -- Почему? Предварительные версии (например, v1.3.0-rc.1, v1.3.0-rc.2) по определению не являются - стабильными и временными. Вы не хотите загрязнять историю своей основной ветки серией - изменений версий для релиз-кандидатов. Файл package.json в main должен отражать - последнюю стабильную версию релиза, а не RC. -- Процесс: Создается ветка release-v1.3.0-rc.1, выполняется npm publish --tag rc, - и затем... ветка выполнила свою задачу. Вы можете просто удалить ее. Код для - RC уже находится в main (или в feature branch), поэтому функциональный код не теряется. Ветка - релиза была просто временным средством для номера версии. +- Почему? Предварительные версии (например, v1.3.0-rc.1, v1.3.0-rc.2) по определению не являются стабильными и временными. Вы не хотите засорять историю своей основной ветки серией изменений номеров версий для релиз-кандидатов. Файл package.json в main должен отражать последнюю стабильную версию релиза, а не RC. +- Процесс: Создается ветка release-v1.3.0-rc.1, выполняется npm publish --tag rc, и затем... ветка выполнила свою задачу. Вы можете просто удалить ее. Код для RC уже находится в main (или в feature-ветке), поэтому функциональный код не теряется. Ветка релиза была просто временным средством для номера версии. ## Локальное тестирование и валидация: Изменения в процессе упаковки и публикации -Если вам нужно протестировать процесс релиза без фактической публикации в NPM или создания публичного релиза на GitHub, вы можете вручную запустить workflow через GitHub UI. +Если вам нужно протестировать процесс релиза без фактической публикации в NPM или создания публичного релиза на GitHub, вы можете запустить workflow вручную через GitHub UI. -1. Перейдите на вкладку [Actions](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) репозитория. +1. Перейдите на вкладку [Actions](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) в репозитории. 2. Нажмите на выпадающий список "Run workflow". 3. Оставьте опцию `dry_run` включенной (`true`). 4. Нажмите кнопку "Run workflow". Это запустит весь процесс релиза, но пропустит шаги `npm publish` и `gh release create`. Вы можете изучить логи workflow, чтобы убедиться, что всё работает как ожидается. -Крайне важно тестировать любые изменения в процессе упаковки и публикации локально перед коммитом. Это гарантирует, что пакеты будут опубликованы корректно и будут работать как ожидается при установке пользователем. +Крайне важно тестировать любые изменения в процессе упаковки и публикации локально перед коммитом. Это гарантирует, что пакеты будут опубликованы корректно и будут работать так, как ожидается, при установке пользователем. -Для проверки ваших изменений вы можете выполнить пробный запуск процесса публикации. Это симулирует процесс публикации, но не будет публиковать пакеты в реестр npm. +Чтобы проверить ваши изменения, вы можете выполнить пробный запуск процесса публикации. Это симулирует процесс публикации, но не будет отправлять пакеты в реестр npm. ```bash npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run @@ -140,11 +139,11 @@ npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME=" Эта команда выполнит следующее: 1. Соберет все пакеты. -2. Выполнит все prepublish скрипты. +2. Выполнит все скрипты prepublish. 3. Создаст tar-архивы пакетов, которые были бы опубликованы в npm. -4. Выведет сводку пакетов, которые были бы опубликованы. +4. Выведет сводку по пакетам, которые должны быть опубликованы. -После этого вы можете проверить сгенерированные tar-архивы, чтобы убедиться, что они содержат правильные файлы и что `package.json` файлы были обновлены корректно. Архивы будут созданы в корневой директории каждого пакета (например, `packages/cli/google-gemini-cli-0.1.6.tgz`). +После этого вы можете проверить сгенерированные tar-архивы, чтобы убедиться, что они содержат правильные файлы и что `package.json` обновлены корректно. Архивы будут созданы в корневой директории каждого пакета (например, `packages/cli/google-gemini-cli-0.1.6.tgz`). Выполнив пробный запуск, вы можете быть уверены, что ваши изменения в процессе упаковки корректны и что пакеты будут успешно опубликованы. @@ -157,7 +156,7 @@ npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME=" ### Этап 1: Предварительные проверки и версионирование - **Что происходит**: Перед перемещением любых файлов система убеждается, что проект находится в рабочем состоянии. Это включает запуск тестов, линтинга и проверки типов (`npm run preflight`). Номер версии в корневом `package.json` и в `packages/cli/package.json` обновляется до новой версии релиза. -- **Зачем**: Это гарантирует, что в релиз попадает только качественный и рабочий код. Версионирование — первый шаг к обозначению нового релиза. +- **Зачем**: Это гарантирует, что в релиз попадает только качественный и рабочий код. Версионирование — первый шаг, обозначающий новый релиз. ### Этап 2: Сборка исходного кода @@ -165,26 +164,26 @@ npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME=" - **Перемещение файлов**: - `packages/core/src/**/*.ts` → компилируется в → `packages/core/dist/` - `packages/cli/src/**/*.ts` → компилируется в → `packages/cli/dist/` -- **Зачем**: Код на TypeScript, написанный во время разработки, должен быть преобразован в обычный JavaScript, который может выполнить Node.js. Сначала собирается core-пакет, так как CLI-пакет от него зависит. +- **Зачем**: Код на TypeScript, написанный во время разработки, должен быть преобразован в обычный JavaScript, который может выполнить Node.js. Сначала собирается core-пакет, так как cli-пакет от него зависит. -### Этап 3: Сборка финального публикуемого пакета +### Этап 3: Формирование финального пакета для публикации -Это самый критичный этап, на котором файлы перемещаются и преобразуются в финальный вид для публикации. Во временной директории `bundle` в корне проекта формируется содержимое финального пакета. +Это самый важный этап, на котором файлы перемещаются и преобразуются в финальный вид для публикации. Во временной директории `bundle` в корне проекта формируется содержимое финального пакета. #### 1. Преобразование `package.json`: - **Что происходит**: `package.json` из `packages/cli/` считывается, модифицируется и записывается в директорию `bundle/`. -- **Перемещение файла**: `packages/cli/package.json` → (преобразование в памяти) → `bundle/package.json` +- **Перемещение файлов**: `packages/cli/package.json` → (преобразование в памяти) → `bundle/package.json` - **Зачем**: Финальный `package.json` должен отличаться от того, что используется в разработке. Основные изменения: - Удаление `devDependencies`. - Удаление зависимостей вида `"@gemini-cli/core": "workspace:*"` и включение кода core-пакета напрямую в финальный JS-файл. - - Поля `bin`, `main` и `files` должны указывать на правильные пути внутри финальной структуры пакета. + - Убедиться, что поля `bin`, `main` и `files` указывают на правильные пути внутри финальной структуры пакета. -#### 2. Создание JavaScript-бандла: +#### 2. Создание бандла JavaScript: - **Что происходит**: Собранный JavaScript из `packages/core/dist` и `packages/cli/dist` объединяется в один исполняемый JS-файл. -- **Перемещение файла**: `packages/cli/dist/index.js` + `packages/core/dist/index.js` → (бандлинг через esbuild) → `bundle/gemini.js` (или аналогичное имя). -- **Зачем**: Это создаёт один оптимизированный файл со всем необходимым кодом приложения. Это упрощает пакет, так как core-пакет больше не нужно публиковать как отдельную зависимость — его код теперь встроен напрямую. +- **Перемещение файлов**: `packages/cli/dist/index.js` + `packages/core/dist/index.js` → (бандлинг через esbuild) → `bundle/gemini.js` (или аналогичное имя). +- **Зачем**: Это создаёт один оптимизированный файл со всем необходимым кодом приложения. Это упрощает пакет, так как core-пакет больше не нужен как отдельная зависимость в NPM — его код теперь встроен напрямую. #### 3. Копирование статических и вспомогательных файлов: @@ -195,14 +194,14 @@ npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME=" - `packages/cli/src/utils/*.sb` (профили песочницы) → `bundle/` - **Зачем**: - `README.md` и `LICENSE` — стандартные файлы, которые должны присутствовать в любом NPM-пакете. - - Файлы `.sb` — критически важные рантайм-ресурсы для функции песочницы CLI. Они должны находиться рядом с финальным исполняемым файлом. + - Профили песочницы (`.sb` файлы) — критически важные рантайм-ресурсы для функции sandboxing CLI. Они должны находиться рядом с финальным исполняемым файлом. ### Этап 4: Публикация в NPM - **Что происходит**: Команда `npm publish` запускается из директории `bundle`. -- **Зачем**: Запуская `npm publish` из директории `bundle`, мы публикуем только те файлы, которые были тщательно собраны на этапе 3. Это предотвращает случайную публикацию исходного кода, тестов или конфигураций разработки, обеспечивая чистый и минималистичный пакет для пользователей. +- **Зачем**: Запуская `npm publish` из директории `bundle`, мы публикуем только те файлы, которые были тщательно собраны на этапе 3. Это предотвращает случайную публикацию исходного кода, тестов или конфигураций разработки, обеспечивая чистый и минимальный пакет для пользователей. -### Сводка потока файлов +### Сводная схема потока файлов ```mermaid graph TD @@ -259,5 +258,5 @@ graph TD ### Преимущества Workspaces - **Упрощенное управление зависимостями**: Запуск `npm install` из корня проекта установит все зависимости для всех пакетов в workspace и свяжет их между собой. Это означает, что вам не нужно запускать `npm install` в каждой директории пакета. -- **Автоматическая линковка**: Пакеты внутри workspace могут зависеть друг от друга. При запуске `npm install` NPM автоматически создаст symlinks между пакетами. Это значит, что при внесении изменений в один пакет, изменения сразу становятся доступны другим пакетам, которые от него зависят. -- **Упрощенный запуск скриптов**: Вы можете запускать скрипты из любого пакета из корня проекта, используя флаг `--workspace`. Например, чтобы запустить скрипт `build` в пакете `cli`, выполните команду `npm run build --workspace @google/gemini-cli`. \ No newline at end of file +- **Автоматическая линковка**: Пакеты в рамках workspace могут зависеть друг от друга. При запуске `npm install` NPM автоматически создаст symlinks между пакетами. Это значит, что при внесении изменений в один пакет, они сразу становятся доступны другим пакетам, которые от него зависят. +- **Упрощенный запуск скриптов**: Вы можете запускать скрипты из любого пакета из корня проекта, используя флаг `--workspace`. Например, чтобы запустить скрипт `build` из пакета `cli`, выполните команду `npm run build --workspace @google/gemini-cli`. \ No newline at end of file diff --git a/website/content/ru/tools/file-system.md b/website/content/ru/tools/file-system.md index 574f4567..387a36ae 100644 --- a/website/content/ru/tools/file-system.md +++ b/website/content/ru/tools/file-system.md @@ -2,7 +2,7 @@ Qwen Code предоставляет комплексный набор инструментов для взаимодействия с локальной файловой системой. Эти инструменты позволяют модели читать, записывать, перечислять, искать и изменять файлы и директории, всё под вашим контролем и, как правило, с подтверждением для чувствительных операций. -**Примечание:** Все инструменты файловой системы работают в пределах `rootDirectory` (обычно это текущая рабочая директория, из которой вы запустили CLI) в целях безопасности. Пути, которые вы указываете этим инструментам, как правило, должны быть абсолютными или будут разрешены относительно этой корневой директории. +**Примечание:** Все инструменты файловой системы работают в пределах `rootDirectory` (обычно это текущая рабочая директория, из которой вы запустили CLI) в целях безопасности. Пути, которые вы передаёте этим инструментам, как правило, должны быть абсолютными или будут разрешены относительно этой корневой директории. ## 1. `list_directory` (ReadFolder) @@ -14,7 +14,7 @@ Qwen Code предоставляет комплексный набор инст - **Параметры:** - `path` (string, обязательный): Абсолютный путь к каталогу для вывода списка. - `ignore` (массив строк, необязательный): Список glob-паттернов, которые нужно исключить из списка (например, `["*.log", ".git"]`). - - `respect_git_ignore` (boolean, необязательный): Учитывать ли паттерны из `.gitignore` при составлении списка файлов. По умолчанию `true`. + - `respect_git_ignore` (boolean, необязательный): Учитывать ли паттерны из `.gitignore` при выводе списка файлов. По умолчанию `true`. - **Поведение:** - Возвращает список имен файлов и каталогов. - Указывает, является ли каждая запись каталогом. @@ -24,14 +24,14 @@ Qwen Code предоставляет комплексный набор инст ## 2. `read_file` (ReadFile) -`read_file` читает и возвращает содержимое указанного файла. Этот инструмент работает с текстовыми файлами, изображениями (PNG, JPG, GIF, WEBP, SVG, BMP) и PDF-файлами. Для текстовых файлов можно читать определённый диапазон строк. Другие бинарные файлы, как правило, пропускаются. +`read_file` читает и возвращает содержимое указанного файла. Этот инструмент работает с текстовыми файлами, изображениями (PNG, JPG, GIF, WEBP, SVG, BMP) и PDF-файлами. Для текстовых файлов можно читать определённые диапазоны строк. Другие бинарные файлы, как правило, пропускаются. - **Название инструмента:** `read_file` - **Отображаемое имя:** ReadFile - **Файл:** `read-file.ts` - **Параметры:** - `path` (string, обязательный): Абсолютный путь к файлу для чтения. - - `offset` (number, опциональный): Для текстовых файлов — номер строки (начиная с 0), с которой начинать чтение. Требует установки параметра `limit`. + - `offset` (number, опциональный): Для текстовых файлов — номер строки (с 0), с которой начинать чтение. Требует установки параметра `limit`. - `limit` (number, опциональный): Для текстовых файлов — максимальное количество строк для чтения. Если не указан, читается стандартное максимальное количество (например, 2000 строк) или весь файл, если это возможно. - **Поведение:** - Для текстовых файлов: Возвращает содержимое. Если используются `offset` и `limit`, возвращается только указанный диапазон строк. Указывает, если содержимое было обрезано из-за ограничений по количеству или длине строк. @@ -40,7 +40,7 @@ Qwen Code предоставляет комплексный набор инст - **Вывод:** (`llmContent`): - Для текстовых файлов: Содержимое файла, возможно, с префиксом сообщения об обрезке (например, `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`). - Для изображений/PDF-файлов: Объект, содержащий `inlineData` с `mimeType` и base64-кодированными `data` (например, `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`). - - Для других бинарных файлов: Сообщение вида `Cannot display content of binary file: /path/to/data.bin`. + - Для других бинарных файлов: Сообщение вроде `Cannot display content of binary file: /path/to/data.bin`. - **Подтверждение:** Нет. ## 3. `write_file` (WriteFile) @@ -57,11 +57,11 @@ Qwen Code предоставляет комплексный набор инст - Записывает предоставленный `content` в `file_path`. - Создает родительские директории, если они не существуют. - **Вывод (`llmContent`):** Сообщение об успешном выполнении, например, `Successfully overwrote file: /path/to/your/file.txt` или `Successfully created and wrote to new file: /path/to/new/file.txt`. -- **Подтверждение:** Да. Показывает diff изменений и запрашивает подтверждение пользователя перед записью. +- **Подтверждение:** Да. Показывает diff изменений и запрашивает одобрение пользователя перед записью. ## 4. `glob` (FindFiles) -`glob` находит файлы, соответствующие заданным glob-паттернам (например, `src/**/*.ts`, `*.md`), и возвращает абсолютные пути, отсортированные по времени модификации (новые файлы первыми). +`glob` находит файлы, соответствующие определенным glob-паттернам (например, `src/**/*.ts`, `*.md`), и возвращает абсолютные пути, отсортированные по времени модификации (новые файлы первыми). - **Название инструмента:** `glob` - **Отображаемое имя:** FindFiles @@ -80,7 +80,7 @@ Qwen Code предоставляет комплексный набор инст ## 5. `search_file_content` (SearchText) -`search_file_content` ищет регулярное выражение (regex) в содержимом файлов указанной директории. Может фильтровать файлы по glob-паттерну. Возвращает строки, содержащие совпадения, вместе с путями к файлам и номерами строк. +`search_file_content` ищет регулярное выражение (regex) в содержимом файлов указанной директории. Может фильтровать файлы по glob-паттерну. Возвращает строки с совпадениями, а также пути к файлам и номера строк. - **Имя инструмента:** `search_file_content` - **Отображаемое имя:** SearchText @@ -88,11 +88,14 @@ Qwen Code предоставляет комплексный набор инст - **Параметры:** - `pattern` (string, обязательный): Регулярное выражение для поиска (например, `"function\s+myFunction"`). - `path` (string, опциональный): Абсолютный путь к директории, в которой нужно искать. По умолчанию — текущая рабочая директория. - - `include` (string, опциональный): Glob-паттерн для фильтрации файлов (например, `"*.js"`, `"src/**/*.{ts,tsx}"`). Если не указан, поиск осуществляется по большинству файлов (с учетом стандартных игнорируемых файлов). + - `include` (string, опциональный): Glob-паттерн для фильтрации файлов (например, `"*.js"`, `"src/**/*.{ts,tsx}"`). Если не указан, поиск осуществляется по большинству файлов (с учетом стандартных игнор-файлов). + - `maxResults` (number, опциональный): Максимальное количество совпадений для возврата, чтобы избежать переполнения контекста (по умолчанию: 20, максимум: 100). Используйте меньшие значения для широких поисков, большие — для точных. - **Поведение:** - - Использует `git grep`, если доступен в Git-репозитории, для повышения скорости; в противном случае использует системный `grep` или поиск на основе JavaScript. - - Возвращает список строк с совпадениями, каждая из которых предваряется путем к файлу (относительно директории поиска) и номером строки. -- **Вывод (`llmContent`):** Отформатированная строка с результатами, например: + - Использует `git grep`, если доступен в Git-репозитории, для повышения скорости; иначе использует системный `grep` или поиск на JavaScript. + - Возвращает список строк с совпадениями, каждая из которых снабжена путем к файлу (относительно директории поиска) и номером строки. + - По умолчанию ограничивает количество результатов 20 совпадениями, чтобы избежать переполнения контекста. При обрезке результатов выводится предупреждение с рекомендациями по уточнению поиска. +- **Вывод (`llmContent`):** Отформатированная строка с совпадениями, например: + ``` Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"): --- @@ -103,12 +106,39 @@ Qwen Code предоставляет комплексный набор инст File: src/index.ts L5: import { myFunction } from './utils'; --- + + WARNING: Results truncated to prevent context overflow. To see more results: + - Use a more specific pattern to reduce matches + - Add file filters with the 'include' parameter (e.g., "*.js", "src/**") + - Specify a narrower 'path' to search in a subdirectory + - Increase 'maxResults' parameter if you need more matches (current: 20) ``` + - **Подтверждение:** Нет. +### Примеры использования `search_file_content` + +Поиск по паттерну с ограничением результатов по умолчанию: + +``` +search_file_content(pattern="function\s+myFunction", path="src") +``` + +Поиск по паттерну с пользовательским ограничением результатов: + +``` +search_file_content(pattern="function", path="src", maxResults=50) +``` + +Поиск по паттерну с фильтрацией файлов и пользовательским ограничением результатов: + +``` +search_file_content(pattern="function", include="*.js", maxResults=10) +``` + ## 6. `replace` (Редактирование) -`replace` заменяет текст в файле. По умолчанию заменяется одно вхождение, но можно заменить несколько вхождений, если указать `expected_replacements`. Этот инструмент предназначен для точных, целенаправленных изменений и требует значительного контекста вокруг `old_string`, чтобы убедиться, что он изменяет правильное место. +`replace` заменяет текст в файле. По умолчанию заменяется одно вхождение, но можно заменить несколько вхождений, если указать `expected_replacements`. Этот инструмент предназначен для точных, целевых изменений и требует значительного контекста вокруг `old_string`, чтобы убедиться, что он изменяет правильное место. - **Название инструмента:** `replace` - **Отображаемое имя:** Edit @@ -117,7 +147,7 @@ Qwen Code предоставляет комплексный набор инст - `file_path` (string, обязательный): Абсолютный путь к файлу, который нужно изменить. - `old_string` (string, обязательный): Точный текст, который нужно заменить. - **ВАЖНО:** Эта строка должна однозначно идентифицировать единственный экземпляр для изменения. Она должна включать как минимум 3 строки контекста _до_ и _после_ целевого текста, точно соответствующего пробелам и отступам. Если `old_string` пустая, инструмент пытается создать новый файл по пути `file_path` с содержимым `new_string`. + **ВАЖНО:** Эта строка должна однозначно идентифицировать единственный экземпляр для изменения. Она должна включать как минимум 3 строки контекста _до_ и _после_ целевого текста, точно соответствующие пробелам и отступам. Если `old_string` пустая, инструмент пытается создать новый файл по пути `file_path` с содержимым `new_string`. - `new_string` (string, обязательный): Точный текст, на который нужно заменить `old_string`. - `expected_replacements` (number, опциональный): Количество вхождений для замены. По умолчанию — `1`. @@ -133,8 +163,8 @@ Qwen Code предоставляет комплексный набор инст - `file_path` не является абсолютным или находится вне корневой директории. - `old_string` не пустая, но `file_path` не существует. - `old_string` пустая, но `file_path` уже существует. - - `old_string` не найдена в файле после попыток её коррекции. - - `old_string` встречается несколько раз, и механизм самокоррекции не может определить однозначное совпадение. + - `old_string` не найдена в файле после попыток коррекции. + - `old_string` найдена несколько раз, и механизм самокоррекции не может определить однозначное совпадение. - **Вывод (`llmContent`):** - При успехе: `Successfully modified file: /path/to/file.txt (1 replacements).` или `Created new file: /path/to/new_file.txt with provided content.` - При ошибке: Сообщение об ошибке с объяснением причины (например, `Failed to edit, 0 occurrences found...`, `Failed to edit, expected 1 occurrences but found 2...`). diff --git a/website/content/ru/tools/index.md b/website/content/ru/tools/index.md index 9367d555..0f8a2610 100644 --- a/website/content/ru/tools/index.md +++ b/website/content/ru/tools/index.md @@ -1,10 +1,10 @@ # Инструменты Qwen Code -Qwen Code включает встроенные инструменты, которые модель использует для взаимодействия с вашей локальной средой, доступа к информации и выполнения действий. Эти инструменты расширяют возможности CLI, позволяя ему выходить за рамки генерации текста и помогать в широком спектре задач. +Qwen Code включает встроенные инструменты, которые модель использует для взаимодействия с вашей локальной средой, получения информации и выполнения действий. Эти инструменты расширяют возможности CLI, позволяя ему выходить за рамки генерации текста и помогать в широком спектре задач. ## Обзор инструментов Qwen Code -В контексте Qwen Code инструменты — это специфичные функции или модули, выполнение которых модель может запрашивать. Например, если вы попросите модель «сделать краткое содержание файла `my_document.txt`», она, скорее всего, определит необходимость прочитать этот файл и запросит выполнение инструмента `read_file`. +В контексте Qwen Code, инструменты — это специфичные функции или модули, которые модель может запрашивать для выполнения. Например, если вы попросите модель «сделать краткое содержание файла `my_document.txt`», она, скорее всего, определит необходимость прочитать этот файл и запросит выполнение инструмента `read_file`. Основной компонент (`packages/core`) управляет этими инструментами, предоставляет их определения (схемы) модели, выполняет их по запросу и возвращает результаты модели для дальнейшей обработки в ответ, предназначенный для пользователя. @@ -12,7 +12,7 @@ Qwen Code включает встроенные инструменты, кото - **Доступ к локальной информации:** Инструменты позволяют модели получать доступ к вашей локальной файловой системе, читать содержимое файлов, просматривать списки каталогов и т. д. - **Выполнение команд:** С помощью таких инструментов, как `run_shell_command`, модель может запускать команды оболочки (с соответствующими мерами безопасности и подтверждением пользователя). -- **Взаимодействие с вебом:** Инструменты могут извлекать содержимое по URL-адресам. +- **Взаимодействие с вебом:** Инструменты могут извлекать контент по URL-адресам. - **Выполнение действий:** Инструменты могут изменять файлы, создавать новые файлы или выполнять другие действия в вашей системе (опять же, как правило, с защитными механизмами). - **Обоснованные ответы:** Используя инструменты для получения актуальных или специфичных локальных данных, ответы могут быть более точными, релевантными и основанными на вашем реальном контексте. @@ -20,28 +20,28 @@ Qwen Code включает встроенные инструменты, кото Чтобы использовать инструменты Qwen Code, передайте prompt в CLI. Процесс работает следующим образом: -1. Вы передаете prompt в CLI. +1. Вы передаёте prompt в CLI. 2. CLI отправляет prompt в ядро (core). -3. Ядро вместе с вашим prompt и историей диалога отправляет список доступных инструментов и их описания/схемы в настроенный model API. -4. Модель анализирует ваш запрос. Если она определяет, что требуется инструмент, её ответ будет содержать запрос на выполнение конкретного инструмента с определёнными параметрами. +3. Ядро вместе с вашим prompt и историей разговора отправляет список доступных инструментов и их описания/схемы в настроенный model API. +4. Модель анализирует ваш запрос. Если она определяет, что нужен инструмент, её ответ будет содержать запрос на выполнение конкретного инструмента с определёнными параметрами. 5. Ядро получает этот запрос инструмента, проверяет его и (часто после подтверждения пользователем для чувствительных операций) выполняет инструмент. 6. Вывод инструмента отправляется обратно в модель. 7. Модель использует вывод инструмента для формирования финального ответа, который затем отправляется через ядро обратно в CLI и отображается вам. -Обычно в CLI вы будете видеть сообщения о том, что инструмент вызывается, и информацию о том, успешно ли он выполнился или произошла ошибка. +Обычно в CLI вы будете видеть сообщения о том, что инструмент вызывается, и информацию о том, успешно ли он выполнился. ## Безопасность и подтверждение Многие инструменты, особенно те, которые могут изменять вашу файловую систему или выполнять команды (`write_file`, `edit`, `run_shell_command`), разработаны с учетом безопасности. Qwen Code обычно: -- **Требует подтверждения:** Запрашивает подтверждение перед выполнением потенциально чувствительных операций, показывая, какое действие будет выполнено. -- **Использует песочницу (sandboxing):** Все инструменты подчиняются ограничениям, установленным песочницей (см. [Sandboxing in Qwen Code](../sandbox.md)). Это означает, что при работе в песочнице все инструменты (включая MCP-серверы), которые вы хотите использовать, должны быть доступны _внутри_ песочницы. Например, чтобы запустить MCP-сервер через `npx`, исполняемый файл `npx` должен быть установлен внутри Docker-образа песочницы или быть доступен в среде `sandbox-exec`. +- **Требует подтверждения:** Запрашивает у вас подтверждение перед выполнением потенциально чувствительных операций, показывая, какое действие будет выполнено. +- **Использует песочницу (sandboxing):** Все инструменты подчиняются ограничениям, установленным песочницей (см. [Песочница в Qwen Code](../sandbox.md)). Это означает, что при работе в песочнице любые инструменты (включая MCP-серверы), которые вы хотите использовать, должны быть доступны _внутри_ песочницы. Например, чтобы запустить MCP-сервер через `npx`, исполняемый файл `npx` должен быть установлен внутри Docker-образа песочницы или быть доступен в среде `sandbox-exec`. Всегда внимательно проверяйте запросы на подтверждение перед тем, как разрешить инструменту продолжить выполнение. ## Узнайте больше об инструментах Qwen Code -Встроенные инструменты Qwen Code можно разделить на следующие категории: +Встроенные инструменты Qwen Code можно условно разделить на следующие категории: - **[Инструменты файловой системы](./file-system.md):** Для работы с файлами и директориями (чтение, запись, список, поиск и т. д.). - **[Shell Tool](./shell.md) (`run_shell_command`):** Для выполнения shell-команд. @@ -49,8 +49,9 @@ Qwen Code включает встроенные инструменты, кото - **[Web Search Tool](./web-search.md) (`web_search`):** Для поиска в интернете. - **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** Специализированный инструмент для чтения контента из нескольких файлов или директорий, часто используется командой `@`. - **[Memory Tool](./memory.md) (`save_memory`):** Для сохранения и воспроизведения информации между сессиями. +- **[Todo Write Tool](./todo-write.md) (`todo_write`):** Для создания и управления структурированными списками задач во время сессий программирования. Кроме того, эти инструменты включают: - **[MCP-серверы](./mcp-server.md)**: MCP-серверы выступают в роли моста между моделью и вашей локальной средой или другими сервисами, такими как API. -- **[Песочница (Sandboxing)](../sandbox.md)**: Песочница изолирует модель и её изменения от вашей среды, снижая потенциальные риски. \ No newline at end of file +- **[Sandboxing](../sandbox.md)**: Sandboxing изолирует модель и её изменения от вашей среды, снижая потенциальные риски. \ No newline at end of file diff --git a/website/content/ru/tools/shell.md b/website/content/ru/tools/shell.md index 30709097..389a50cc 100644 --- a/website/content/ru/tools/shell.md +++ b/website/content/ru/tools/shell.md @@ -11,71 +11,122 @@ `run_shell_command` принимает следующие аргументы: - `command` (string, обязательный): Точная shell-команда для выполнения. -- `description` (string, опциональный): Краткое описание цели команды, которое будет показано пользователю. +- `description` (string, опциональный): Краткое описание назначения команды, которое будет показано пользователю. - `directory` (string, опциональный): Директория (относительно корня проекта), в которой нужно выполнить команду. Если не указана, команда выполняется в корне проекта. +- `is_background` (boolean, обязательный): Определяет, следует ли запускать команду в фоновом режиме. Этот параметр обязателен, чтобы явно указать режим выполнения команды. Установите `true` для долгоживущих процессов, таких как серверы разработки, наблюдатели или демоны, которые должны продолжать работу, не блокируя выполнение других команд. Установите `false` для одноразовых команд, которые должны завершиться до продолжения работы. ## Как использовать `run_shell_command` с Qwen Code -При использовании `run_shell_command` команда выполняется как подпроцесс. `run_shell_command` может запускать фоновые процессы с помощью `&`. Инструмент возвращает подробную информацию о выполнении, включая: +При использовании `run_shell_command` команда выполняется как подпроцесс. Вы можете контролировать, будут ли команды выполняться в фоновом или активном режиме, используя параметр `is_background`, либо явно добавляя `&` к командам. Инструмент возвращает подробную информацию о выполнении, включая: -- `Command`: Выполненная команда. +### Обязательный параметр Background + +Параметр `is_background` является **обязательным** для всех выполнений команд. Такое решение гарантирует, что LLM (и пользователи) должны явно решать, должна ли каждая команда выполняться в фоновом или активном режиме, способствуя целенаправленному и предсказуемому поведению выполнения команд. Обязательность этого параметра позволяет избежать непреднамеренного возврата к активному выполнению, которое может блокировать последующие операции при работе с длительными процессами. + +### Фоновое и активное выполнение + +Инструмент интеллектуально управляет фоновым и активным выполнением в зависимости от вашего явного выбора: + +**Используйте фоновое выполнение (`is_background: true`) для:** + +- Долго работающих серверов разработки: `npm run start`, `npm run dev`, `yarn dev` +- Наблюдателей за сборкой: `npm run watch`, `webpack --watch` +- Серверов баз данных: `mongod`, `mysql`, `redis-server` +- Веб-серверов: `python -m http.server`, `php -S localhost:8000` +- Любых команд, которые должны работать бесконечно до ручной остановки + +**Используйте активное выполнение (`is_background: false`) для:** + +- Одноразовых команд: `ls`, `cat`, `grep` +- Команд сборки: `npm run build`, `make` +- Команд установки: `npm install`, `pip install` +- Операций Git: `git commit`, `git push` +- Запуска тестов: `npm test`, `pytest` + +### Информация о выполнении + +Инструмент возвращает подробную информацию о выполнении, включая: + +- `Command`: Команда, которая была выполнена. - `Directory`: Директория, в которой была запущена команда. - `Stdout`: Вывод из стандартного потока вывода. - `Stderr`: Вывод из стандартного потока ошибок. -- `Error`: Любое сообщение об ошибке, сообщенное подпроцессом. +- `Error`: Любое сообщение об ошибке, сообщенное subprocess. - `Exit Code`: Код завершения команды. - `Signal`: Номер сигнала, если команда была прервана сигналом. -- `Background PIDs`: Список PID для любых запущенных фоновых процессов. +- `Background PIDs`: Список PID для любых фоновых процессов, запущенных в фоновом режиме. Использование: +```bash +run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.", is_background=false) ``` -run_shell_command(command="Ваши команды.", description="Ваше описание команды.", directory="Ваша директория выполнения.") -``` -## Примеры `run_shell_command` +**Примечание:** Параметр `is_background` является обязательным и должен быть явно указан при каждом выполнении команды. + +## Примеры использования `run_shell_command` -Показать список файлов в текущей директории: +Вывести список файлов в текущей директории: +```bash +run_shell_command(command="ls -la", is_background=false) ``` -run_shell_command(command="ls -la") + +Запустить скрипт в определённой директории: + +```bash +run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script", is_background=false) ``` -Запустить скрипт из определенной директории: +Запустить сервер для разработки в фоновом режиме (рекомендуемый способ): +```bash +run_shell_command(command="npm run dev", description="Start development server in background", is_background=true) ``` -run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script") + +Запустить сервер в фоне (альтернативный способ с явным указанием &): + +```bash +run_shell_command(command="npm run dev &", description="Start development server in background", is_background=false) ``` -Запустить сервер в фоновом режиме: +Выполнить команду сборки в основном потоке: +```bash +run_shell_command(command="npm run build", description="Build the project", is_background=false) ``` -run_shell_command(command="npm run dev &", description="Start development server in background") + +Запустить несколько сервисов в фоновом режиме: + +```bash +run_shell_command(command="docker-compose up", description="Start all services", is_background=true) ``` ## Важные замечания -- **Безопасность:** Будьте осторожны при выполнении команд, особенно тех, что строятся на основе пользовательского ввода, чтобы избежать уязвимостей безопасности. -- **Интерактивные команды:** Избегайте команд, требующих интерактивного ввода от пользователя, так как это может привести к зависанию инструмента. По возможности используйте флаги для отключения интерактивности (например, `npm init -y`). +- **Безопасность:** Будьте осторожны при выполнении команд, особенно тех, что собраны из пользовательского ввода, чтобы избежать уязвимостей безопасности. +- **Интерактивные команды:** Избегайте команд, требующих интерактивного ввода от пользователя, так как это может привести к зависанию инструмента. Используйте флаги для неинтерактивного режима, если они доступны (например, `npm init -y`). - **Обработка ошибок:** Проверяйте поля `Stderr`, `Error` и `Exit Code`, чтобы определить, успешно ли выполнилась команда. -- **Фоновые процессы:** Если команда запускается в фоне с помощью `&`, инструмент немедленно возвращает управление, а процесс продолжает выполняться в фоновом режиме. Поле `Background PIDs` будет содержать ID фонового процесса. +- **Фоновые процессы:** Когда `is_background=true` или когда команда содержит `&`, инструмент немедленно вернёт управление, а процесс продолжит выполняться в фоне. Поле `Background PIDs` будет содержать ID фонового процесса. +- **Выбор фонового выполнения:** Параметр `is_background` обязателен и обеспечивает явный контроль над режимом выполнения. Вы также можете добавить `&` к команде для ручного запуска в фоне, но параметр `is_background` всё равно должен быть указан. Этот параметр делает намерение более понятным и автоматически управляет настройкой фонового выполнения. +- **Описание команд:** При использовании `is_background=true` в описании команды будет указано `[background]`, чтобы явно показать режим выполнения. ## Переменные окружения -Когда `run_shell_command` выполняет команду, она устанавливает переменную окружения `QWEN_CODE=1` в среде подпроцесса. Это позволяет скриптам или инструментам определить, запущены ли они из CLI. +Когда `run_shell_command` выполняет команду, она устанавливает переменную окружения `QWEN_CODE=1` в среде дочернего процесса. Это позволяет скриптам или инструментам определить, запущены ли они из CLI. ## Ограничения команд -Вы можете ограничить команды, которые могут выполняться инструментом `run_shell_command`, используя настройки `coreTools` и `excludeTools` в вашем конфигурационном файле. +Вы можете ограничить команды, которые могут быть выполнены с помощью инструмента `run_shell_command`, используя настройки `coreTools` и `excludeTools` в вашем конфигурационном файле. -- `coreTools`: Чтобы ограничить `run_shell_command` определенным набором команд, добавьте записи в список `coreTools` в формате `run_shell_command()`. Например, `"coreTools": ["run_shell_command(git)"]` разрешит только команды `git`. Включение общего `run_shell_command` действует как wildcard, разрешая любую команду, не заблокированную явно. -- `excludeTools`: Чтобы заблокировать определенные команды, добавьте записи в список `excludeTools` в формате `run_shell_command()`. Например, `"excludeTools": ["run_shell_command(rm)"]` заблокирует команды `rm`. +- `coreTools`: Чтобы ограничить `run_shell_command` определённым набором команд, добавьте записи в список `coreTools` в формате `run_shell_command()`. Например, `"coreTools": ["run_shell_command(git)"]` разрешит только команды `git`. Если указать общий `run_shell_command`, это будет работать как wildcard, разрешая любые команды, которые явно не заблокированы. +- `excludeTools`: Чтобы заблокировать определённые команды, добавьте записи в список `excludeTools` в формате `run_shell_command()`. Например, `"excludeTools": ["run_shell_command(rm)"]` заблокирует команды `rm`. Логика валидации разработана так, чтобы быть безопасной и гибкой: -1. **Цепочки команд отключены**: Инструмент автоматически разделяет команды, объединенные с помощью `&&`, `||` или `;`, и проверяет каждую часть отдельно. Если какая-либо часть цепочки запрещена, вся команда блокируется. -2. **Сопоставление по префиксу**: Инструмент использует сопоставление по префиксу. Например, если вы разрешаете `git`, вы можете выполнить `git status` или `git log`. -3. **Приоритет черного списка**: Список `excludeTools` всегда проверяется первым. Если команда совпадает с заблокированным префиксом, она будет отклонена, даже если она также совпадает с разрешенным префиксом в `coreTools`. +1. **Цепочки команд отключены**: Инструмент автоматически разделяет команды, объединённые с помощью `&&`, `||` или `;`, и проверяет каждую часть отдельно. Если какая-либо часть цепочки запрещена, вся команда блокируется. +2. **Сопоставление по префиксу**: Инструмент использует сопоставление по префиксу. Например, если вы разрешаете `git`, вы можете выполнять `git status` или `git log`. +3. **Приоритет чёрного списка**: Список `excludeTools` всегда проверяется первым. Если команда совпадает с заблокированным префиксом, она будет отклонена, даже если также совпадает с разрешённым префиксом из `coreTools`. ### Примеры ограничений команд @@ -137,4 +188,4 @@ run_shell_command(command="npm run dev &", description="Start development server ## Заметка о безопасности для `excludeTools` -Ограничения, специфичные для команд, в `excludeTools` для `run_shell_command`, основаны на простом сравнении строк и могут быть легко обойдены. Эта функция **не является механизмом безопасности** и не должна использоваться для безопасного выполнения недоверенного кода. Рекомендуется использовать `coreTools` для явного выбора команд, которые могут быть выполнены. \ No newline at end of file +Ограничения на уровне команд в `excludeTools` для `run_shell_command` основаны на простом сравнении строк и могут быть легко обойдены. Эта функция **не является механизмом безопасности** и не должна использоваться для безопасного выполнения недоверенного кода. Рекомендуется использовать `coreTools` для явного выбора команд, которые можно выполнять. \ No newline at end of file diff --git a/website/content/ru/tools/todo-write.md b/website/content/ru/tools/todo-write.md new file mode 100644 index 00000000..4be15286 --- /dev/null +++ b/website/content/ru/tools/todo-write.md @@ -0,0 +1,63 @@ +# Инструмент для работы с Todo (`todo_write`) + +В этом документе описывается инструмент `todo_write` для Qwen Code. + +## Описание + +Используйте `todo_write`, чтобы создавать и управлять структурированным списком задач для текущей сессии кодинга. Этот инструмент помогает AI-ассистенту отслеживать прогресс и организовывать сложные задачи, предоставляя вам наглядное представление о том, какая работа выполняется. + +### Аргументы + +`todo_write` принимает один аргумент: + +- `todos` (массив, обязательный): Массив элементов todo, где каждый элемент содержит: + - `id` (строка, обязательный): Уникальный идентификатор элемента todo. + - `content` (строка, обязательный): Описание задачи. + - `status` (строка, обязательный): Текущий статус (`pending`, `in_progress` или `completed`). + +## Как использовать `todo_write` с Qwen Code + +AI-ассистент будет автоматически использовать этот инструмент при работе над сложными, многоэтапными задачами. Вам не нужно явно запрашивать его, но вы можете попросить ассистента создать список задач, если хотите увидеть запланированный подход к вашему запросу. + +Инструмент сохраняет списки задач в вашем домашнем каталоге (`~/.qwen/todos/`) в файлах, специфичных для сессии, поэтому каждая сессия программирования сохраняет свой собственный список задач. + +## Когда AI использует этот инструмент + +Ассистент использует `todo_write` для: + +- Сложных задач, требующих нескольких шагов +- Реализации функций с несколькими компонентами +- Операций рефакторинга в нескольких файлах +- Любых работ, включающих 3 или более отдельных действия + +Ассистент не будет использовать этот инструмент для простых, одноэтапных задач или purely informational запросов. + +### Примеры `todo_write` + +Создание плана реализации фичи: + +``` +todo_write(todos=[ + { + "id": "create-model", + "content": "Create user preferences model", + "status": "pending" + }, + { + "id": "add-endpoints", + "content": "Add API endpoints for preferences", + "status": "pending" + }, + { + "id": "implement-ui", + "content": "Implement frontend components", + "status": "pending" + } +]) +``` + +## Важные замечания + +- **Автоматическое использование:** AI-ассистент автоматически управляет списками todo во время сложных задач. +- **Видимость прогресса:** Вы будете видеть, как списки todo обновляются в реальном времени по мере выполнения работы. +- **Изоляция сессий:** Каждая сессия кодинга имеет свой собственный список todo, который не мешает другим. \ No newline at end of file diff --git a/website/content/ru/troubleshooting.md b/website/content/ru/troubleshooting.md index 13c71abd..8fed3aa4 100644 --- a/website/content/ru/troubleshooting.md +++ b/website/content/ru/troubleshooting.md @@ -10,14 +10,14 @@ ## Ошибки аутентификации или входа в систему - **Ошибка: `Failed to login. Message: Request contains an invalid argument`** - - Пользователи с аккаунтами Google Workspace или аккаунтами Google Cloud, - связанными с их Gmail-аккаунтами, могут не иметь возможности активировать - бесплатный тарифный план Google Code Assist. - - Для аккаунтов Google Cloud эту проблему можно обойти, установив - переменную окружения `GOOGLE_CLOUD_PROJECT` равной вашему ID проекта. - - Также вы можете получить API-ключ Gemini в - [Google AI Studio](http://aistudio.google.com/app/apikey), где также доступен - отдельный бесплатный лимит. + - Пользователи с аккаунтами Google Workspace или Google Cloud, связанными с их аккаунтами Gmail, могут не иметь возможности активировать бесплатный тарифный план Google Code Assist. + - Для аккаунтов Google Cloud эту проблему можно обойти, установив переменную окружения `GOOGLE_CLOUD_PROJECT` равной ID вашего проекта. + - Также вы можете получить API-ключ Gemini из [Google AI Studio](http://aistudio.google.com/app/apikey), который также включает отдельный бесплатный лимит. + +- **Ошибка: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` или `unable to get local issuer certificate`** + - **Причина:** Возможно, вы находитесь в корпоративной сети с брандмауэром, который перехватывает и инспектирует SSL/TLS-трафик. Для этого часто требуется, чтобы Node.js доверял пользовательскому корневому сертификату ЦС. + - **Решение:** Установите переменную окружения `NODE_EXTRA_CA_CERTS`, указав абсолютный путь к файлу корневого сертификата вашей корпоративной ЦС. + - Пример: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` ## Часто задаваемые вопросы (FAQ) @@ -32,20 +32,20 @@ Дополнительную информацию см. в разделе [Конфигурация Qwen Code](./cli/configuration.md). - **В: Почему я не вижу кэшированных подсчетов токенов в выводе статистики?** - - О: Информация о кэшированных токенах отображается только при использовании кэшированных токенов. Эта функция доступна для пользователей API-ключей (Gemini API key или Google Cloud Vertex AI), но недоступна для пользователей OAuth (например, личных/корпоративных аккаунтов Google, таких как Google Gmail или Google Workspace соответственно). Это связано с тем, что Gemini Code Assist API не поддерживает создание кэшированного контента. Вы по-прежнему можете просматривать общее использование токенов с помощью команды `/stats`. + - О: Информация о кэшированных токенах отображается только тогда, когда используются кэшированные токены. Эта функция доступна для пользователей API-ключей (Gemini API key или Google Cloud Vertex AI), но недоступна для пользователей OAuth (например, личных/корпоративных аккаунтов Google, таких как Google Gmail или Google Workspace соответственно). Это связано с тем, что Gemini Code Assist API не поддерживает создание кэшированного контента. Вы по-прежнему можете просматривать общее использование токенов с помощью команды `/stats`. ## Распространенные сообщения об ошибках и решения -- **Ошибка: `EADDRINUSE` (Адрес уже используется) при запуске MCP сервера.** +- **Ошибка: `EADDRINUSE` (Address already in use) при запуске MCP сервера.** - **Причина:** Другой процесс уже использует порт, к которому пытается привязаться MCP сервер. - **Решение:** Остановите другой процесс, использующий этот порт, или настройте MCP сервер на использование другого порта. - **Ошибка: Command not found (при попытке запустить Qwen Code с помощью `qwen`).** - - **Причина:** CLI не установлен корректно или не добавлен в системную переменную `PATH`. + - **Причина:** CLI не установлен корректно или не добавлен в `PATH` вашей системы. - **Решение:** Способ обновления зависит от того, как вы установили Qwen Code: - - Если вы установили `qwen` глобально, проверьте, что директория с глобальными бинарниками `npm` находится в вашем `PATH`. Вы можете обновить его с помощью команды `npm install -g @qwen-code/qwen-code@latest`. + - Если вы установили `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` или ошибки импорта.** @@ -56,17 +56,17 @@ 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` файле проекта не включает режим отладки для CLI. + - **Причина:** Переменные `DEBUG` и `DEBUG_MODE` автоматически исключаются из `.env` файлов проекта, чтобы не мешать работе CLI. - **Решение:** Используйте файл `.qwen/.env` вместо этого, или настройте параметр `excludedProjectEnvVars` в вашем `settings.json`, чтобы исключить меньше переменных. ## IDE Companion не подключается @@ -76,7 +76,7 @@ - `QWEN_CODE_IDE_WORKSPACE_PATH` - `QWEN_CODE_IDE_SERVER_PORT` - Если вы работаете в контейнере, проверьте, что `host.docker.internal` резолвится. В противном случае, настройте соответствующий маппинг хоста. -- Переустановите companion с помощью `/ide install` и используйте команду “Qwen Code: Run” в Command Palette, чтобы убедиться, что он запускается. +- Переустановите companion с помощью `/ide install` и используйте команду “Qwen Code: Run” из Command Palette, чтобы проверить запуск. ## Советы по отладке diff --git a/website/content/zh/cli/configuration.md b/website/content/zh/cli/configuration.md index 6c4ed7d6..6c09c1b6 100644 --- a/website/content/zh/cli/configuration.md +++ b/website/content/zh/cli/configuration.md @@ -4,9 +4,9 @@ Qwen Code 提供了多种方式来配置其行为，包括环境变量、命令 ## 配置层级 -配置按照以下优先级顺序应用（数字越小优先级越低，会被数字越高的覆盖）： +配置按以下优先级顺序应用（较低数字的配置会被较高数字的配置覆盖）： -1. **默认值：** 应用程序内部的硬编码默认值。 +1. **默认值：** 应用程序内的硬编码默认值。 2. **用户设置文件：** 当前用户的全局设置。 3. **项目设置文件：** 项目特定的设置。 4. **系统设置文件：** 系统范围的设置。 @@ -25,20 +25,20 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **作用范围：** 仅在从该特定项目运行 Qwen Code 时应用。项目设置会覆盖用户设置。 - **系统配置文件：** - **位置：** `/etc/gemini-cli/settings.json`（Linux）、`C:\ProgramData\gemini-cli\settings.json`（Windows）或 `/Library/Application Support/GeminiCli/settings.json`（macOS）。可以通过 `GEMINI_CLI_SYSTEM_SETTINGS_PATH` 环境变量覆盖路径。 - - **作用范围：** 应用于系统上所有用户的 Qwen Code 会话。系统设置会覆盖用户和项目设置。企业中的系统管理员可以使用此功能来控制用户的 Qwen Code 设置。 + - **作用范围：** 应用于系统上所有用户的 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` 中可用的配置项： - **`contextFileName`**（字符串或字符串数组）： - - **说明：** 指定上下文文件的文件名（例如 `QWEN.md`、`AGENTS.md`）。可以是一个文件名，也可以是多个可接受的文件名组成的数组。 + - **说明：** 指定上下文文件的文件名（例如 `QWEN.md`、`AGENTS.md`）。可以是单个文件名，也可以是多个可接受的文件名组成的数组。 - **默认值：** `QWEN.md` - **示例：** `"contextFileName": "AGENTS.md"` @@ -58,7 +58,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **说明：** 控制 @ 命令和文件发现工具的 git-aware 文件过滤行为。 - **默认值：** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` - **属性：** - - **`respectGitIgnore`**（布尔值）：在发现文件时是否遵循 `.gitignore` 规则。设置为 `true` 时，git 忽略的文件（如 `node_modules/`、`dist/`、`.env`）将自动从 @ 命令和文件列表操作中排除。 + - **`respectGitIgnore`**（布尔值）：在发现文件时是否遵循 `.gitignore` 的规则。设置为 `true` 时，git 忽略的文件（如 `node_modules/`、`dist/`、`.env`）会自动从 @ 命令和文件列表操作中排除。 - **`enableRecursiveFileSearch`**（布尔值）：是否在提示中补全 @ 前缀时，启用递归搜索当前目录树下的文件名。 - **示例：** ```json @@ -69,30 +69,30 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`coreTools`**（字符串数组）： - - **说明：** 允许你指定一组核心工具名称，这些工具将对模型可用。可用于限制内置工具的使用范围。有关核心工具列表，请参见 [Built-in Tools](../core/tools-api.md#built-in-tools)。你也可以为支持的工具（如 `ShellTool`）指定命令级别的限制。例如，`"coreTools": ["ShellTool(ls -l)"]` 将只允许执行 `ls -l` 命令。 + - **说明：** 允许你指定一个核心工具名称列表，这些工具将对模型可用。可用于限制内置工具的使用范围。有关核心工具的列表，请参见 [Built-in Tools](../core/tools-api.md#built-in-tools)。你也可以为支持该功能的工具（如 `ShellTool`）指定命令级别的限制。例如，`"coreTools": ["ShellTool(ls -l)"]` 将只允许执行 `ls -l` 命令。 - **默认值：** 所有工具都对模型可用。 - **示例：** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]` - **`excludeTools`**（字符串数组）： - - **说明：** 允许你指定一组应从模型中排除的核心工具名称。如果某个工具同时出现在 `excludeTools` 和 `coreTools` 中，则会被排除。你也可以为支持的工具（如 `ShellTool`）指定命令级别的限制。例如，`"excludeTools": ["ShellTool(rm -rf)"]` 将阻止执行 `rm -rf` 命令。 + - **说明：** 允许你指定一个应从模型中排除的核心工具名称列表。如果某个工具同时出现在 `excludeTools` 和 `coreTools` 中，则会被排除。你也可以为支持该功能的工具（如 `ShellTool`）指定命令级别的限制。例如，`"excludeTools": ["ShellTool(rm -rf)"]` 将阻止执行 `rm -rf` 命令。 - **默认值：** 不排除任何工具。 - **示例：** `"excludeTools": ["run_shell_command", "findFiles"]` - - **安全提示：** 对于 `run_shell_command` 工具，`excludeTools` 中的命令限制基于简单的字符串匹配，容易被绕过。此功能**不是安全机制**，不应依赖它来安全执行不受信任的代码。建议使用 `coreTools` 明确指定允许执行的命令。 + - **安全提示：** 对于 `run_shell_command`，`excludeTools` 中的命令限制基于简单的字符串匹配，容易被绕过。此功能**不是安全机制**，不应依赖它来安全地执行不受信任的代码。建议使用 `coreTools` 明确选择允许执行的命令。 - **`allowMCPServers`**（字符串数组）： - - **说明：** 允许你指定一组 MCP server 名称，这些 server 将对模型可用。可用于限制连接的 MCP server 范围。注意：如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 - - **默认值：** 所有 MCP server 都对模型可用。 + - **说明：** 允许你指定一个 MCP server 名称列表，这些服务器将对模型可用。可用于限制连接的 MCP 服务器。注意：如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 + - **默认值：** 所有 MCP 服务器都对模型可用。 - **示例：** `"allowMCPServers": ["myPythonServer"]` - - **安全提示：** 此配置使用简单的字符串匹配来识别 MCP server 名称，容易被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法自行配置 MCP server。此配置不应被视为严格的安全机制。 + - **安全提示：** 此功能使用简单的字符串匹配来识别 MCP 服务器名称，可被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法配置自己的 MCP 服务器。此功能不应被视为严格的安全机制。 - **`excludeMCPServers`**（字符串数组）： - - **说明：** 允许你指定一组应从模型中排除的 MCP server 名称。如果某个 server 同时出现在 `excludeMCPServers` 和 `allowMCPServers` 中，则会被排除。注意：如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 - - **默认值：** 不排除任何 MCP server。 + - **说明：** 允许你指定一个应从模型中排除的 MCP server 名称列表。如果某个服务器同时出现在 `excludeMCPServers` 和 `allowMCPServers` 中，则会被排除。注意：如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 + - **默认值：** 不排除任何 MCP 服务器。 - **示例：** `"excludeMCPServers": ["myNodeServer"]` - - **安全提示：** 此配置使用简单的字符串匹配来识别 MCP server 名称，容易被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法自行配置 MCP server。此配置不应被视为严格的安全机制。 + - **安全提示：** 此功能使用简单的字符串匹配来识别 MCP 服务器名称，可被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法配置自己的 MCP 服务器。此功能不应被视为严格的安全机制。 - **`autoAccept`**（布尔值）： - - **说明：** 控制 CLI 是否自动接受并执行被认为是安全的工具调用（例如只读操作），而无需用户显式确认。如果设为 `true`，CLI 将跳过对安全工具的确认提示。 + - **说明：** 控制 CLI 是否自动接受并执行被认为是安全的工具调用（例如只读操作），而无需用户明确确认。如果设置为 `true`，CLI 将跳过对安全工具的确认提示。 - **默认值：** `false` - **示例：** `"autoAccept": true` @@ -102,41 +102,41 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **示例：** `"theme": "GitHub"` - **`vimMode`**（布尔值）： - - **说明：** 启用或禁用输入编辑的 vim 模式。启用后，输入区域支持 vim 风格的导航和编辑命令（NORMAL 和 INSERT 模式）。vim 模式状态会在页脚显示，并在会话之间保持。 + - **说明：** 启用或禁用输入编辑的 vim 模式。启用后，输入区域支持 vim 风格的导航和编辑命令，包括 NORMAL 和 INSERT 模式。vim 模式状态会在页脚显示，并在会话之间保持。 - **默认值：** `false` - **示例：** `"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 数组。工具包装器是可选的。 + - **说明：** 定义一个自定义 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 命令必须满足以下条件： + - **说明：** 定义一个自定义 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)。 + - 必须在 `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 属性。 + - **说明：** 配置一个或多个 Model-Context Protocol (MCP) 服务器的连接，用于发现和使用自定义工具。Qwen Code 会尝试连接每个配置的 MCP 服务器以发现可用工具。如果多个 MCP 服务器暴露了同名工具，工具名称将加上你在配置中定义的服务器别名前缀（例如 `serverAlias__actualToolName`）以避免冲突。注意：系统可能会为了兼容性而从 MCP 工具定义中剥离某些 schema 属性。 - **默认值：** 空 - **属性：** - - **``**（对象）：指定 server 的参数。 - - `command`（字符串，必填）：启动 MCP server 的命令。 + - **``**（对象）：指定服务器的参数。 + - `command`（字符串，必填）：启动 MCP 服务器的命令。 - `args`（字符串数组，可选）：传递给命令的参数。 - - `env`（对象，可选）：为 server 进程设置的环境变量。 - - `cwd`（字符串，可选）：启动 server 的工作目录。 - - `timeout`（数字，可选）：对此 MCP server 的请求超时时间（毫秒）。 - - `trust`（布尔值，可选）：信任此 server 并跳过所有工具调用确认。 - - `includeTools`（字符串数组，可选）：从此 MCP server 包含的工具名称列表。指定后，仅列出的工具可用（白名单行为）。未指定时，默认启用 server 的所有工具。 - - `excludeTools`（字符串数组，可选）：从此 MCP server 排除的工具名称列表。即使 server 提供这些工具，模型也无法使用。**注意：** `excludeTools` 优先级高于 `includeTools` —— 如果一个工具同时出现在两个列表中，它将被排除。 + - `env`（对象，可选）：为服务器进程设置的环境变量。 + - `cwd`（字符串，可选）：启动服务器的工作目录。 + - `timeout`（数字，可选）：对此 MCP 服务器请求的超时时间（毫秒）。 + - `trust`（布尔值，可选）：信任此服务器并跳过所有工具调用确认。 + - `includeTools`（字符串数组，可选）：从此 MCP 服务器包含的工具名称列表。指定后，只有列出的工具会从该服务器可用（白名单行为）。未指定时，默认启用服务器的所有工具。 + - `excludeTools`（字符串数组，可选）：从此 MCP 服务器排除的工具名称列表。即使服务器暴露了这些工具，模型也无法使用。**注意：** `excludeTools` 优先于 `includeTools` —— 如果某个工具同时出现在两个列表中，它将被排除。 - **示例：** ```json "mcpServers": { @@ -164,10 +164,10 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`checkpointing`**（对象）： - - **说明：** 配置 checkpointing 功能，允许你保存和恢复对话及文件状态。更多详情请参见 [Checkpointing 文档](../checkpointing.md)。 + - **说明：** 配置 checkpointing 功能，允许你保存和恢复对话和文件状态。更多详情请参见 [Checkpointing documentation](../checkpointing.md)。 - **默认值：** `{"enabled": false}` - **属性：** - - **`enabled`**（布尔值）：当设为 `true` 时，`/restore` 命令可用。 + - **`enabled`**（布尔值）：当为 `true` 时，`/restore` 命令可用。 - **`preferredEditor`**（字符串）： - **说明：** 指定查看 diff 时使用的首选编辑器。 @@ -246,7 +246,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`includeDirectories`**（字符串数组）： - - **说明：** 指定一组额外的绝对或相对路径，将其包含在工作区上下文中。这允许你像操作单个目录一样操作多个目录中的文件。路径可以使用 `~` 表示用户主目录。此设置可与 `--include-directories` 命令行参数结合使用。 + - **说明：** 指定一个额外的绝对或相对路径数组，这些路径将包含在工作区上下文中。这允许你像操作单个目录一样操作多个目录中的文件。路径可以使用 `~` 来引用用户的主目录。此设置可以与 `--include-directories` 命令行标志结合使用。 - **默认值：** `[]` - **示例：** ```json @@ -258,7 +258,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`loadMemoryFromIncludeDirectories`**（布尔值）： - - **说明：** 控制 `/memory refresh` 命令的行为。如果设为 `true`，应从所有添加的目录加载 `QWEN.md` 文件。如果设为 `false`，则只从当前目录加载 `QWEN.md`。 + - **说明：** 控制 `/memory refresh` 命令的行为。如果设置为 `true`，应从所有添加的目录中加载 `QWEN.md` 文件。如果设置为 `false`，则只从当前目录加载 `QWEN.md`。 - **默认值：** `false` - **示例：** ```json @@ -273,7 +273,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **`chatCompression`**（对象）： - **说明：** 控制聊天历史压缩的设置，包括自动压缩和通过 `/compress` 命令手动触发的压缩。 - **属性：** - - **`contextPercentageThreshold`**（数字）：介于 0 和 1 之间的值，指定触发压缩的 token 阈值占模型总 token 限制的百分比。例如，值为 `0.6` 时，当聊天历史超过 token 限制的 60% 时将触发压缩。 + - **`contextPercentageThreshold`**（数字）：介于 0 到 1 之间的值，指定触发压缩的 token 阈值占模型总 token 限制的百分比。例如，值为 `0.6` 时，当聊天历史超过 token 限制的 60% 时将触发压缩。 - **示例：** ```json "chatCompression": { @@ -334,71 +334,71 @@ CLI 会保存你运行的 shell 命令历史记录。为了避免不同项目之 - **位置：** `~/.qwen/tmp//shell_history` - `` 是根据你的项目根路径生成的唯一标识符。 - - 历史记录存储在一个名为 `shell_history` 的文件中。 + - 历史记录存储在名为 `shell_history` 的文件中。 ## 环境变量与 `.env` 文件 -环境变量是配置应用程序的常见方式，尤其适用于敏感信息（如 API key）或在不同环境中可能变化的设置。 +环境变量是配置应用程序的常见方式，尤其适用于敏感信息（如 API key）或在不同环境中可能发生变化的设置。 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` 来自定义这一行为。 - **`GEMINI_API_KEY`**（必填）： - - 你的 Gemini API key。 + - 用于 Gemini API 的 API key。 - **至关重要**，CLI 无法在没有它的情况下运行。 - 可在 shell 配置文件（如 `~/.bashrc`、`~/.zshrc`）或 `.env` 文件中设置。 - **`GEMINI_MODEL`**： - 指定默认使用的 Gemini 模型。 - - 会覆盖硬编码的默认值。 + - 会覆盖代码中硬编码的默认值。 - 示例：`export GEMINI_MODEL="gemini-2.5-flash"` - **`GOOGLE_API_KEY`**： - 你的 Google Cloud API key。 - 在 express 模式下使用 Vertex AI 时必需。 - - 确保你拥有必要的权限。 + - 请确保你拥有相应的权限。 - 示例：`export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"` - **`GOOGLE_CLOUD_PROJECT`**： - 你的 Google Cloud Project ID。 - 使用 Code Assist 或 Vertex AI 时必需。 - - 如果使用 Vertex AI，请确保你在此项目中具有必要的权限。 - - **Cloud Shell 注意事项：** 在 Cloud Shell 环境中运行时，该变量默认为 Cloud Shell 用户分配的特殊项目。如果你在 Cloud Shell 的全局环境中设置了 `GOOGLE_CLOUD_PROJECT`，它将被此默认值覆盖。要在 Cloud Shell 中使用其他项目，你必须在 `.env` 文件中定义 `GOOGLE_CLOUD_PROJECT`。 + - 如果使用 Vertex AI，请确保你在此项目中具有相应权限。 + - **Cloud Shell 注意事项：** 在 Cloud Shell 环境中运行时，该变量默认指向为 Cloud Shell 用户分配的特殊项目。如果你在 Cloud Shell 的全局环境中设置了 `GOOGLE_CLOUD_PROJECT`，它将被此默认值覆盖。若要在 Cloud Shell 中使用其他项目，必须在 `.env` 文件中定义 `GOOGLE_CLOUD_PROJECT`。 - 示例：`export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"` - **`GOOGLE_APPLICATION_CREDENTIALS`**（字符串）： - - **说明：** 你的 Google Application Credentials JSON 文件路径。 + - **说明：** 指向你的 Google Application Credentials JSON 文件的路径。 - **示例：** `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"` - **`OTLP_GOOGLE_CLOUD_PROJECT`**： - 用于 Google Cloud 中遥测数据的 Google Cloud Project ID。 - 示例：`export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"` - **`GOOGLE_CLOUD_LOCATION`**： - - 你的 Google Cloud 项目位置（例如：us-central1）。 + - 你的 Google Cloud 项目所在区域（例如：us-central1）。 - 在非 express 模式下使用 Vertex AI 时必需。 - 示例：`export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"` - **`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`），但允许其他操作。 + - 切换 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`）。 + - ``：使用自定义配置文件。要定义自定义配置文件，请在项目 `.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`**： - 设置一个字符串来自定义 CLI 的标题。 - **`CODE_ASSIST_ENDPOINT`**： - - 指定代码辅助服务器的 endpoint。 + - 指定 code assist server 的 endpoint。 - 对开发和测试很有用。 - **`TAVILY_API_KEY`**： - - 你的 Tavily 网络搜索服务 API key。 + - 用于 Tavily 网络搜索服务的 API key。 - 启用 `web_search` 工具功能时必需。 - - 如果未配置，网络搜索工具将被禁用并跳过。 + - 若未配置，网络搜索工具将被禁用并跳过。 - 示例：`export TAVILY_API_KEY="tvly-your-api-key-here"` ## 命令行参数 @@ -411,16 +411,16 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： - **`--prompt `** (**`-p `**): - 用于直接将 prompt 传递给命令。这会以非交互模式调用 Qwen Code。 - **`--prompt-interactive `** (**`-i `**): - - 使用提供的 prompt 作为初始输入启动一个交互式会话。 + - 使用提供的 prompt 作为初始输入启动交互式会话。 - prompt 会在交互式会话中处理，而不是在会话开始前处理。 - - 当从 stdin 管道输入时不能使用此参数。 + - 当从 stdin 管道输入时不能使用。 - 示例：`qwen -i "explain this code"` - **`--sandbox`** (**`-s`**): - 为本次会话启用 sandbox 模式。 - **`--sandbox-image`**: - 设置 sandbox 镜像 URI。 - **`--debug`** (**`-d`**): - - 启用本次会话的 debug 模式，提供更详细的输出信息。 + - 为本次会话启用 debug 模式，提供更详细的输出信息。 - **`--all-files`** (**`-a`**): - 如果设置，则递归地将当前目录中的所有文件作为 prompt 的上下文包含进来。 - **`--help`** (或 **`-h`**): @@ -429,6 +429,13 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： - 显示当前内存使用情况。 - **`--yolo`**: - 启用 YOLO 模式，自动批准所有工具调用。 +- **`--approval-mode `**: + - 设置工具调用的审批模式。可用模式包括： + - `default`：每个工具调用都需要手动审批（默认行为） + - `auto_edit`：自动批准编辑类工具（replace、write_file），其他工具仍需手动审批 + - `yolo`：自动批准所有工具调用（等同于 `--yolo`） + - 不能与 `--yolo` 同时使用。请使用 `--approval-mode=yolo` 替代 `--yolo`，以采用新的统一方式。 + - 示例：`qwen --approval-mode auto_edit` - **`--telemetry`**: - 启用 [telemetry](../telemetry.md)。 - **`--telemetry-target`**: @@ -440,8 +447,8 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： - **`--checkpointing`**: - 启用 [checkpointing](../checkpointing.md)。 - **`--extensions `** (**`-e `**): - - 指定本次会话要使用的扩展列表。如果未提供，则使用所有可用扩展。 - - 使用特殊参数 `qwen -e none` 可禁用所有扩展。 + - 指定本次会话使用的扩展列表。如果未提供，则使用所有可用扩展。 + - 使用特殊关键字 `qwen -e none` 可禁用所有扩展。 - 示例：`qwen -e my-extension -e my-other-extension` - **`--list-extensions`** (**`-l`**): - 列出所有可用扩展并退出。 @@ -449,8 +456,8 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： - 设置 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`**: @@ -458,18 +465,18 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： - **`--openai-logging`**: - 启用 OpenAI API 调用的日志记录，用于调试和分析。此标志会覆盖 `settings.json` 中的 `enableOpenAILogging` 设置。 - **`--tavily-api-key `**: - - 为本次会话设置 Tavily API key 以启用网页搜索功能。 + - 为本次会话设置 Tavily API key，用于启用网页搜索功能。 - 示例：`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 文件包含你希望 Gemini 模型在交互过程中了解的指令、指南或上下文信息。该系统被设计为分层管理这种指令上下文。 ### 示例上下文文件内容（例如，`QWEN.md`） -以下是一个位于 TypeScript 项目根目录的上下文文件可能包含的内容的概念示例： +以下是一个概念性示例，展示了一个位于 TypeScript 项目根目录的上下文文件可能包含的内容： ```markdown @@ -486,43 +493,43 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： - 使用 2 个空格进行缩进。 - 接口名称应以 `I` 为前缀（例如，`IUserService`）。 -- 私有类成员应以下划线（`_`）为前缀。 +- 类的私有成员应以下划线（`_`）为前缀。 - 始终使用严格相等（`===` 和 `!==`）。 ## 特定组件：`src/api/client.ts` -- 此文件处理所有出站 API 请求。 -- 在添加新的 API 调用函数时，请确保它们包含健壮的错误处理和日志记录。 +- 此文件负责处理所有向外的 API 请求。 +- 在添加新的 API 调用函数时，请确保包含完善的错误处理和日志记录。 - 对于所有 GET 请求，请使用现有的 `fetchWithRetry` 工具函数。 ``` ## 关于依赖项： - 除非绝对必要，否则应避免引入新的外部依赖项。 -- 如果确实需要新增依赖项，请说明具体原因。 +- 如果确实需要新的依赖项，请说明原因。 ``` -这个示例展示了如何提供通用的项目背景、具体的编码规范，甚至针对特定文件或组件的说明。你的上下文文件越相关且精确，AI 就能更好地为你提供帮助。我们强烈建议你为项目创建特定的上下文文件，以便建立统一的规范和上下文环境。 +这个示例展示了如何提供通用的项目背景、具体的编码规范，甚至关于特定文件或组件的说明。你的上下文文件越相关且精确，AI 就能更好地协助你。我们强烈建议为项目创建特定的上下文文件，以建立约定和上下文环境。 -- **分层加载与优先级：** CLI 通过从多个位置加载上下文文件（例如 `QWEN.md`）实现了一套复杂的分层内存系统。列表中靠后的位置（更具体）的内容通常会覆盖或补充靠前位置（更通用）的内容。你可以使用 `/memory show` 命令查看具体的拼接顺序和最终使用的上下文内容。典型的加载顺序如下： +- **分层加载与优先级：** CLI 通过从多个位置加载上下文文件（例如 `QWEN.md`）实现了一套复杂的分层内存系统。列表中靠后（更具体）的文件内容通常会覆盖或补充靠前（更通用）的文件内容。你可以使用 `/memory show` 命令查看确切的拼接顺序和最终上下文。典型的加载顺序如下： 1. **全局上下文文件：** - - 路径：`~/.qwen/`（例如在你的用户主目录下的 `~/.qwen/QWEN.md`）。 - - 作用范围：为所有项目提供默认指令。 - 2. **项目根目录及祖先目录中的上下文文件：** - - 路径：CLI 会在当前工作目录及其上级目录中查找配置的上下文文件，一直向上查找到项目根目录（以 `.git` 文件夹标识）或你的主目录为止。 - - 作用范围：提供整个项目或其重要部分相关的上下文信息。 - 3. **子目录中的上下文文件（局部/上下文相关）：** - - 路径：CLI 还会扫描当前工作目录 _之下_ 的子目录中是否存在配置的上下文文件（遵循如 `node_modules`、`.git` 等常见的忽略规则）。默认情况下最多扫描 200 个目录，但可以通过在 `settings.json` 文件中设置 `memoryDiscoveryMaxDirs` 字段来调整这一限制。 - - 作用范围：允许为项目的某个特定组件、模块或子部分提供高度定制化的指令。 -- **内容拼接与 UI 提示：** 所有找到的上下文文件内容会被依次拼接（并用分隔符标明来源路径），然后作为 system prompt 的一部分提供给 AI。CLI 的底部会显示已加载的上下文文件数量，让你可以快速了解当前激活的指令上下文。 -- **导入内容：** 你可以通过在 Markdown 文件中使用 `@path/to/file.md` 语法来模块化管理上下文文件。更多详情请参阅 [Memory Import Processor 文档](../core/memport.md)。 + - 位置：`~/.qwen/`（例如在你的用户主目录下的 `~/.qwen/QWEN.md`）。 + - 作用域：为你的所有项目提供默认指令。 + 2. **项目根目录及祖先目录的上下文文件：** + - 位置：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)。 - **内存管理命令：** - - 使用 `/memory refresh` 强制重新扫描并从所有配置的位置重新加载上下文文件。这将更新 AI 的指令上下文。 - - 使用 `/memory show` 显示当前已加载的完整指令上下文，方便你确认 AI 正在使用的层级结构和具体内容。 - - 更多关于 `/memory` 命令及其子命令（`show` 和 `refresh`）的详细信息，请参阅 [Commands 文档](./commands.md#memory)。 + - 使用 `/memory refresh` 强制重新扫描并从所有配置的位置重新加载所有上下文文件。这将更新 AI 的指令上下文。 + - 使用 `/memory show` 显示当前加载的组合指令上下文，方便你验证 AI 正在使用的层级结构和内容。 + - 有关 `/memory` 命令及其子命令（`show` 和 `refresh`）的完整详情，请参见 [Commands 文档](./commands.md#memory)。 -通过理解并利用这些配置层级以及上下文文件的分层特性，你可以有效地管理 AI 的记忆，并根据你的具体需求和项目定制 Qwen Code 的响应行为。 +通过理解并利用这些配置层级以及上下文文件的分层特性，你可以有效地管理 AI 的内存，并根据你的具体需求和项目定制 Qwen Code 的响应。 ## 沙箱机制 @@ -532,11 +539,11 @@ Qwen Code 可以在一个沙箱环境中执行潜在的不安全操作（如 she - 使用 `--sandbox` 或 `-s` 参数。 - 设置 `GEMI_SANDBOX` 环境变量。 -- 在 `--yolo` 模式下，沙箱默认是启用的。 +- 当使用 `--yolo` 或 `--approval-mode=yolo` 时，沙箱机制会默认启用。 默认情况下，它会使用一个预构建的 `qwen-code-sandbox` Docker 镜像。 -如果你的项目有特定的沙箱需求，可以在项目根目录下创建一个 `.qwen/sandbox.Dockerfile` 文件来自定义 Docker 配置。这个 Dockerfile 可以基于基础沙箱镜像： +如果你的项目有特定的沙箱需求，可以在项目根目录下创建一个 `.qwen/sandbox.Dockerfile` 文件来自定义 Dockerfile。这个 Dockerfile 可以基于基础沙箱镜像： ```dockerfile FROM qwen-code-sandbox @@ -559,19 +566,19 @@ BUILD_SANDBOX=1 qwen -s ## 使用统计 -为了帮助我们改进 Qwen Code，我们会收集匿名化的使用统计数据。这些数据帮助我们了解 CLI 的使用情况，识别常见问题，并优先开发新功能。 +为了帮助我们改进 Qwen Code，我们会收集匿名化的使用统计数据。这些数据帮助我们了解 CLI 的使用情况，识别常见问题，并确定新功能的优先级。 **我们收集的数据包括：** - **工具调用：** 我们会记录被调用的工具名称、执行成功或失败的状态以及执行耗时。我们不会收集传递给工具的参数或工具返回的任何数据。 - **API 请求：** 我们会记录每次请求所使用的模型、请求耗时以及请求是否成功。我们不会收集 prompt 或 response 的具体内容。 -- **会话信息：** 我们会收集 CLI 的配置信息，例如启用的工具和审批模式。 +- **会话信息：** 我们会收集 CLI 配置相关的信息，例如启用的工具和审批模式。 **我们不会收集的数据包括：** - **个人身份信息 (PII)：** 我们不会收集任何个人信息，例如您的姓名、邮箱地址或 API key。 - **Prompt 和 Response 内容：** 我们不会记录您提交的 prompt 或模型返回的 response 内容。 -- **文件内容：** 我们不会记录 CLI 读取或写入的任何文件内容。 +- **文件内容：** 我们不会记录 CLI 读取或写入的任何文件的内容。 **如何退出数据收集：** diff --git a/website/content/zh/deployment.md b/website/content/zh/deployment.md index f8698390..f9f27770 100644 --- a/website/content/zh/deployment.md +++ b/website/content/zh/deployment.md @@ -41,7 +41,7 @@ 你可以直接运行已发布的沙箱镜像。这在你只有 Docker 并希望运行 CLI 的环境中非常有用。 ```bash # 运行已发布的沙箱镜像 - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.7 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.9 ``` - **使用 `--sandbox` 参数：** 如果你已经在本地安装了 Qwen Code（使用上述标准安装方式），你可以指示它在沙箱容器内运行。 @@ -103,15 +103,15 @@ Qwen Code 项目是一个 monorepo，会将核心包发布到 NPM registry： - **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。 ## 发布流程 -发布流程通过 GitHub Actions 自动化执行。发布工作流包含以下操作： +发布流程通过 GitHub Actions 自动化执行。发布工作流会执行以下操作： 1. 使用 `tsc` 构建 NPM 包。 2. 将 NPM 包发布到 artifact registry。 diff --git a/website/content/zh/ide-integration.md b/website/content/zh/ide-integration.md new file mode 100644 index 00000000..117dd4ae --- /dev/null +++ b/website/content/zh/ide-integration.md @@ -0,0 +1,139 @@ +# IDE 集成 + +Gemini CLI 可以与你的 IDE 集成，提供更无缝且具备上下文感知的体验。通过这种集成，CLI 能够更好地理解你的工作区，并启用强大的功能，例如编辑器内原生 diff 比对。 + +目前，唯一支持的 IDE 是 [Visual Studio Code](https://code.visualstudio.com/) 以及其他支持 VS Code 扩展的编辑器。 + +## 功能特性 + +- **Workspace 上下文感知：** CLI 会自动感知你的 workspace，从而提供更相关和准确的响应。该上下文包括： + - 你 workspace 中**最近访问的 10 个文件**。 + - 你当前的光标位置。 + - 你选中的文本（最多 16KB，超出部分将被截断）。 + +- **原生 Diff 支持：** 当 Gemini 建议代码修改时，你可以直接在 IDE 的原生 diff 查看器中查看变更。这样你可以无缝地审查、编辑并接受或拒绝建议的更改。 + +- **VS Code 命令支持：** 你可以直接从 VS Code 命令面板（`Cmd+Shift+P` 或 `Ctrl+Shift+P`）访问 Gemini CLI 功能： + - `Gemini CLI: Run`：在集成终端中启动一个新的 Gemini CLI 会话。 + - `Gemini CLI: Accept Diff`：接受当前 diff 编辑器中的更改。 + - `Gemini CLI: Close Diff Editor`：拒绝更改并关闭当前 diff 编辑器。 + - `Gemini CLI: View Third-Party Notices`：显示该扩展的第三方声明信息。 + +## 安装和设置 + +有三种方式可以设置 IDE 集成： + +### 1. 自动提示（推荐） + +当你在支持的编辑器中运行 Gemini CLI 时，它会自动检测你的环境并提示你进行连接。回答 "Yes" 后将自动运行必要的设置，包括安装配套扩展和启用连接。 + +### 2. 从 CLI 手动安装 + +如果你之前关闭了提示框或想要手动安装扩展，可以在 Gemini CLI 中运行以下命令： + +``` +/ide install +``` + +这将找到适合你 IDE 的正确扩展并进行安装。 + +### 3. 从 Marketplace 手动安装 + +你也可以直接从 marketplace 安装这个 extension。 + +- **对于 Visual Studio Code：** 从 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=google.gemini-cli-vscode-ide-companion) 安装。 +- **对于 VS Code Forks：** 为了支持 VS Code 的 fork 版本，该 extension 也发布在 [Open VSX Registry](https://open-vsx.org/extension/google/gemini-cli-vscode-ide-companion) 上。请按照你的编辑器说明从这个 registry 安装 extension。 + +使用任何安装方法后，建议打开一个新的 terminal 窗口以确保 integration 正确激活。安装完成后，你可以使用 `/ide enable` 来连接。 + +### 启用和禁用 + +你可以通过 CLI 来控制 IDE 集成： + +- 要启用与 IDE 的连接，运行： + ``` + /ide enable + ``` +- 要禁用连接，运行： + ``` + /ide disable + ``` + +启用后，Gemini CLI 会自动尝试连接到 IDE companion extension。 + +### 检查状态 + +要检查连接状态并查看 CLI 从 IDE 接收到的上下文信息，运行： + +``` +/ide status +``` + +如果已连接，该命令会显示所连接的 IDE 以及它感知到的最近打开的文件列表。 + +（注意：文件列表仅限工作区中最近访问的 10 个文件，且只包含磁盘上的本地文件。） + +### 使用 Diff + +当你要求 Gemini 修改文件时，它可以在你的编辑器中直接打开 diff 视图。 + +**要接受一个 diff**，你可以执行以下任意操作： + +- 点击 diff 编辑器标题栏中的 **checkmark icon**。 +- 保存文件（例如使用 `Cmd+S` 或 `Ctrl+S`）。 +- 打开 Command Palette 并运行 **Gemini CLI: Accept Diff**。 +- 在 CLI 中提示时回复 `yes`。 + +**要拒绝一个 diff**，你可以： + +- 点击 diff 编辑器标题栏中的 **'x' icon**。 +- 关闭 diff 编辑器标签页。 +- 打开 Command Palette 并运行 **Gemini CLI: Close Diff Editor**。 +- 在 CLI 中提示时回复 `no`。 + +你也可以在接受之前**直接在 diff 视图中修改建议的更改**。 + +如果你在 CLI 中选择 'Yes, allow always'，更改将不再在 IDE 中显示，因为它们会被自动接受。 + +## 在沙盒环境中使用 + +如果你在沙盒环境中使用 Gemini CLI，请注意以下事项： + +- **在 macOS 上：** IDE 集成需要网络访问权限来与 IDE companion 扩展通信。你必须使用允许网络访问的 Seatbelt 配置文件。 +- **在 Docker 容器中：** 如果你在 Docker（或 Podman）容器内运行 Gemini CLI，IDE 集成仍然可以连接到运行在宿主机上的 VS Code 扩展。CLI 已配置为自动在 `host.docker.internal` 上查找 IDE 服务器。通常不需要特殊配置，但你可能需要确保 Docker 网络设置允许从容器到宿主机的连接。 + +## 故障排除 + +如果你遇到 IDE 集成问题，以下是一些常见错误信息及其解决方法。 + +### 连接错误 + +- **错误信息：** `🔴 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.` + - **原因：** Gemini CLI 无法找到连接 IDE 所需的环境变量（`GEMINI_CLI_IDE_WORKSPACE_PATH` 或 `GEMINI_CLI_IDE_SERVER_PORT`）。这通常意味着 IDE companion 扩展未运行或未正确初始化。 + - **解决方案：** + 1. 确保你已在 IDE 中安装并启用了 **Gemini CLI Companion** 扩展。 + 2. 在 IDE 中打开一个新的 terminal 窗口，以确保它能获取到正确的环境变量。 + +- **错误信息：** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` + - **原因：** 与 IDE companion 的连接意外中断。 + - **解决方案：** 运行 `/ide enable` 尝试重新连接。如果问题仍然存在，可以尝试打开一个新的 terminal 窗口或重启你的 IDE。 + +### 配置错误 + +- **错误信息：** `🔴 Disconnected: Directory mismatch. Gemini CLI 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 中打开的文件夹或 workspace 不一致。 + - **解决方案：** 使用 `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。 + +### 通用错误 + +- **错误信息：** `IDE integration is not supported in your current environment. To use this feature, run Gemini CLI in one of these supported IDEs: [List of IDEs]` + - **原因：** 你当前在终端或非支持的 IDE 环境中运行 Gemini CLI。 + - **解决方案：** 请在支持的 IDE（如 VS Code）的集成终端中运行 Gemini CLI。 + +- **错误信息：** `No installer is available for [IDE Name]. Please install the IDE companion manually from its marketplace.` + - **原因：** 你执行了 `/ide install`，但 CLI 没有为你使用的 IDE 提供自动安装器。 + - **解决方案：** 打开你的 IDE 的扩展市场，搜索 "Gemini CLI Companion"，然后手动安装。 \ No newline at end of file diff --git a/website/content/zh/index.md b/website/content/zh/index.md index 39457c3b..364c5060 100644 --- a/website/content/zh/index.md +++ b/website/content/zh/index.md @@ -15,15 +15,16 @@ Qwen Code 将先进的代码模型能力带入你的终端，提供交互式的 - **CLI 使用：** `packages/cli` 的文档。 - **[CLI 简介](./cli/index.md)：** 命令行界面的概述。 - **[命令](./cli/commands.md)：** 可用 CLI 命令的说明。 - - **[配置](./cli/configuration.md)：** CLI 配置的相关信息。 + - **[配置](./cli/configuration.md)：** 配置 CLI 的相关信息。 - **[检查点](./checkpointing.md)：** 检查点功能的文档。 - **[扩展](./extension.md)：** 如何通过新功能扩展 CLI。 + - **[IDE 集成](./ide-integration.md)：** 将 CLI 与你的编辑器连接。 - **[遥测](./telemetry.md)：** CLI 中遥测功能的概述。 - **核心详情：** `packages/core` 的文档。 - **[核心简介](./core/index.md)：** 核心组件的概述。 - **[工具 API](./core/tools-api.md)：** 核心如何管理和暴露工具的信息。 - **工具：** - - **[工具概述](./tools/index.md)：** 可用工具的概述。 + - **[工具概览](./tools/index.md)：** 可用工具的概述。 - **[文件系统工具](./tools/file-system.md)：** `read_file` 和 `write_file` 工具的文档。 - **[多文件读取工具](./tools/multi-file.md)：** `read_many_files` 工具的文档。 - **[Shell 工具](./tools/shell.md)：** `run_shell_command` 工具的文档。 diff --git a/website/content/zh/integration-tests.md b/website/content/zh/integration-tests.md index 7deb04e1..1a5caf07 100644 --- a/website/content/zh/integration-tests.md +++ b/website/content/zh/integration-tests.md @@ -10,7 +10,7 @@ ## 运行测试 -集成测试不会作为默认的 `npm run test` 命令的一部分运行。必须使用 `npm run test:integration:all` 脚本显式运行它们。 +集成测试不会作为默认 `npm run test` 命令的一部分运行。必须使用 `npm run test:integration:all` 脚本显式运行它们。 也可以使用以下快捷方式运行集成测试： @@ -20,15 +20,15 @@ npm run test:e2e ## 运行特定测试集 -要运行部分测试文件，可以使用 `npm run ....`，其中 `` 是 `test:e2e` 或 `test:integration*` 之一，`` 是 `integration-tests/` 目录下的任意 `.test.js` 文件。例如，以下命令会运行 `list_directory.test.js` 和 `write_file.test.js`： +要运行一部分测试文件，可以使用 `npm run ....`，其中 `` 是 `test:e2e` 或 `test:integration*` 之一，`` 是 `integration-tests/` 目录下的任意 `.test.js` 文件。例如，以下命令会运行 `list_directory.test.js` 和 `write_file.test.js`： ```bash npm run test:e2e list_directory write_file ``` -### 根据名称运行单个测试 +### 按名称运行单个测试 -要根据测试名称运行单个测试，可以使用 `--test-name-pattern` 参数： +要按名称运行单个测试，可以使用 `--test-name-pattern` 参数： ```bash npm run test:e2e -- --test-name-pattern "reads a file" @@ -36,7 +36,7 @@ npm run test:e2e -- --test-name-pattern "reads a file" ### 运行所有测试 -要运行完整的集成测试套件，使用以下命令： +要运行完整的 integration tests 套件，使用以下命令： ```bash npm run test:integration:all @@ -44,8 +44,8 @@ npm run test:integration:all ### Sandbox 矩阵 -`all` 命令会针对 `no sandboxing`、`docker` 和 `podman` 运行测试。 -你也可以通过以下命令单独运行每种类型： +`all` 命令会为 `no sandboxing`、`docker` 和 `podman` 运行测试。 +每种类型可以使用以下命令单独运行： ```bash npm run test:integration:sandbox:none @@ -59,59 +59,53 @@ npm run test:integration:sandbox:docker npm run test:integration:sandbox:podman ``` -## 诊断功能 +## 诊断 -integration test runner 提供了多个诊断选项，帮助你排查测试失败的问题。 +integration test runner 提供了几个诊断选项来帮助追踪测试失败。 ### 保留测试输出 -你可以保留测试运行期间创建的临时文件以便检查。这在调试文件系统操作相关问题时非常有用。 +你可以保留测试运行期间创建的临时文件以供检查。这对于调试文件系统操作问题很有用。 -要保留测试输出，可以使用 `--keep-output` flag，或者将 `KEEP_OUTPUT` 环境变量设置为 `true`。 +要保留测试输出，请将 `KEEP_OUTPUT` 环境变量设置为 `true`。 -```bash - -# 使用 flag -npm run test:integration:sandbox:none -- --keep-output - -# 使用环境变量 ```bash KEEP_OUTPUT=true npm run test:integration:sandbox:none ``` -当保留输出时，测试运行器会打印出本次测试运行的唯一目录路径。 +当保留输出时，test runner 会打印测试运行的唯一目录路径。 ### 详细输出 -如果需要更详细的调试信息，可以使用 `--verbose` 参数，它会将 `qwen` 命令的实时输出流式传输到控制台。 +如果需要更详细的调试信息，可以将 `VERBOSE` 环境变量设置为 `true`。 ```bash -npm run test:integration:sandbox:none -- --verbose +VERBOSE=true npm run test:integration:sandbox:none ``` -当在同一命令中同时使用 `--verbose` 和 `--keep-output` 时，输出既会显示在控制台上，也会保存到测试临时目录中的日志文件里。 +当在同一命令中同时使用 `VERBOSE=true` 和 `KEEP_OUTPUT=true` 时，输出内容会同时打印到控制台，并保存到测试临时目录中的日志文件里。 -详细输出的格式会清楚地标明日志来源： +详细输出的格式会清楚标明日志来源： ``` ---- TEST: : --- -... 来自 qwen 命令的输出 ... ---- END TEST: : --- +--- TEST: : --- +... output from the qwen command ... +--- END TEST: : --- ``` -## 代码检查和格式化 +## 代码检查与格式化 -为了确保代码质量和一致性，集成测试文件会在主构建流程中进行 lint 检查。你也可以手动运行 linter 和自动修复工具。 +为了确保代码质量和风格统一，集成测试文件会在主构建流程中进行 lint 检查。你也可以手动运行 linter 和自动修复工具。 ### 运行 linter -要检查 linting 错误，运行以下命令： +要检查是否存在 lint 错误，可以运行以下命令： ```bash npm run lint ``` -你可以在命令中包含 `:fix` 标志来自动修复任何可修复的 linting 错误： +你可以在命令中加上 `:fix` 参数，自动修复所有可修复的 lint 错误： ```bash npm run lint:fix @@ -119,9 +113,9 @@ npm run lint:fix ## 目录结构 -集成测试会在 `.integration-tests` 目录内为每次测试运行创建一个唯一的目录。在此目录中，会为每个测试文件创建一个子目录，而在该子目录中，会为每个单独的测试用例创建一个子目录。 +集成测试会在 `.integration-tests` 目录内为每次测试运行创建一个唯一的目录。在此目录中，会为每个测试文件创建一个子目录，然后在该子目录中为每个单独的测试用例创建一个子目录。 -这种结构使得定位特定测试运行、文件或用例的 artifacts 变得容易。 +这种结构使得定位特定测试运行、文件或用例的 artifacts 变得非常容易。 ``` .integration-tests/ @@ -129,12 +123,12 @@ npm run lint:fix └── .test.js/ └── / ├── output.log - └── ...other test artifacts... + └── ...其他测试 artifacts... ``` ## 持续集成 -为确保集成测试始终运行，我们在 `.github/workflows/e2e.yml` 中定义了一个 GitHub Actions workflow。该 workflow 会在针对 `main` 分支的 pull request 提交时，或当 pull request 被加入 merge queue 时，自动运行集成测试。 +为确保集成测试始终运行，我们在 `.github/workflows/e2e.yml` 中定义了一个 GitHub Actions workflow。该 workflow 会在针对 `main` 分支的 pull request 提交时，或当 pull request 被加入 merge queue 时自动运行集成测试。 该 workflow 会在不同的沙箱环境中运行测试，以确保 Qwen Code 在每种环境下都经过测试： diff --git a/website/content/zh/npm.md b/website/content/zh/npm.md index e94f85ab..1fec4baf 100644 --- a/website/content/zh/npm.md +++ b/website/content/zh/npm.md @@ -6,34 +6,34 @@ 这是 Qwen Code 的主 package。它负责用户界面、命令解析以及所有其他面向用户的 functionality。 -当这个 package 被发布时，它会被打包成一个单独的可执行文件。这个 bundle 包含了所有 package 的 dependencies，包括 `@qwen-code/qwen-code-core`。这意味着无论用户是通过 `npm install -g @qwen-code/qwen-code` 安装，还是直接使用 `npx @qwen-code/qwen-code` 运行，他们使用的都是这个单一的、自包含的 executable。 +当这个 package 被发布时，它会被打包成一个单独的可执行文件。这个 bundle 包含了所有 package 的 dependencies，包括 `@qwen-code/qwen-code-core`。这意味着无论用户是通过 `npm install -g @qwen-code/qwen-code` 安装，还是直接使用 `npx @qwen-code/qwen-code` 运行，他们使用的都是这个单一的、自包含的可执行文件。 ## `@qwen-code/qwen-code-core` 这个 package 包含了 CLI 的核心逻辑。它负责向配置的 providers 发起 API 请求、处理认证以及管理本地缓存。 -这个 package 不会被打包（bundled）。发布时，它会作为一个标准的 Node.js package 发布，并带有自己的 dependencies。这使得它可以在其他项目中作为独立 package 使用（如果需要的话）。`dist` 文件夹中所有编译后的 js 代码都会包含在 package 中。 +这个 package 没有被打包。发布时，它会作为一个标准的 Node.js package 进行发布，并带有自己的 dependencies。这使得它可以在其他项目中作为独立 package 使用（如果需要的话）。`dist` 文件夹中所有编译后的 js 代码都会包含在 package 中。 # 发布流程 -本项目遵循结构化的发布流程，以确保所有 packages 都能被正确地版本化和发布。该流程尽可能实现了自动化。 +本项目遵循结构化的发布流程，以确保所有 packages 都能正确地进行版本控制和发布。该流程的设计目标是尽可能实现自动化。 -## 如何发布版本 +## 如何发布 -版本发布通过 [release.yml](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) GitHub Actions workflow 来管理。如需手动发布一个 patch 或 hotfix 版本，请按以下步骤操作： +发布通过 [release.yml](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) GitHub Actions workflow 来管理。要手动发布一个 patch 或 hotfix： -1. 进入仓库的 **Actions** 标签页。 -2. 从列表中选择 **Release** workflow。 +1. 进入 repository 的 **Actions** tab。 +2. 在列表中选择 **Release** workflow。 3. 点击 **Run workflow** 下拉按钮。 4. 填写必要的输入项： - **Version**：要发布的具体版本号（例如 `v0.2.1`）。 - **Ref**：要发布的目标 branch 或 commit SHA（默认为 `main`）。 - - **Dry Run**：保留为 `true` 可在不实际发布的情况下测试 workflow，设置为 `false` 则执行正式发布。 + - **Dry Run**：保留为 `true` 可在不实际发布的情况下测试 workflow，设置为 `false` 则执行真实发布。 5. 点击 **Run workflow**。 -## Nightly Releases +## Nightly 发布 -除了手动发布版本之外，该项目还支持自动化的 nightly release 流程，用于提供最新的“前沿”版本，方便测试和开发使用。 +除了手动发布之外，该项目还具有自动化的 nightly 发布流程，用于提供最新的“前沿”版本以供测试和开发使用。 ### 流程 @@ -43,12 +43,12 @@ 2. 安装所有依赖项。 3. 运行完整的 `preflight` 检查和集成测试套件。 4. 如果所有测试都通过，它会计算下一个 nightly 版本号（例如，`v0.2.1-nightly.20230101`）。 -5. 然后构建并将 packages 发布到 npm，并使用 `nightly` dist-tag。 -6. 最后，为 nightly 版本创建一个 GitHub Release。 +5. 然后构建并将包发布到 npm，并使用 `nightly` dist-tag。 +6. 最后，它会为 nightly 版本创建一个 GitHub Release。 ### 故障处理 -如果 nightly workflow 中的任何步骤失败，它会自动在仓库中创建一个新 issue，并打上 `bug` 和 `nightly-failure` 标签。该 issue 会包含指向失败 workflow 运行的链接，方便调试。 +如果 nightly workflow 中的任何步骤失败，它会在仓库中自动创建一个新 issue，并打上 `bug` 和 `nightly-failure` 标签。该 issue 会包含指向失败 workflow 运行的链接，方便调试。 ### 如何使用 Nightly Build @@ -58,15 +58,15 @@ npm install -g @qwen-code/qwen-code@nightly ``` -我们还会运行一个名为 [release-docker.yml](../.gcp/release-docker.yaml) 的 Google Cloud Build，用于发布与你 release 版本匹配的 sandbox Docker 镜像。一旦 service account 权限问题解决后，这部分也会迁移至 GitHub，并与主 release 文件合并。 +我们还运行一个名为 [release-docker.yml](../.gcp/release-docker.yml) 的 Google Cloud Build，它会发布与你的 release 对应的 sandbox docker 镜像。一旦 service account 权限问题解决后，这个流程也会迁移到 GitHub，并与主 release 文件合并。 ### 发布之后 -当 workflow 成功完成后，你可以在 [GitHub Actions tab](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) 中监控其进度。完成后，请执行以下操作： +当 workflow 成功完成后，你可以在 [GitHub Actions tab](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) 中监控其进度。完成后，你应该： -1. 前往仓库的 [pull requests 页面](https://github.com/QwenLM/qwen-code/pulls)。 -2. 从 `release/vX.Y.Z` 分支向 `main` 分支创建一个新的 pull request。 -3. 审查该 pull request（应该只包含 `package.json` 文件中的版本更新），然后合并它。这样可以确保 `main` 分支中的版本保持最新。 +1. 前往仓库的 [pull requests 页面](https://github.com/QwenLM/qwen-code/pulls)。 +2. 从 `release/vX.Y.Z` 分支创建一个新的 pull request 到 `main` 分支。 +3. 审查该 pull request（应该只包含 `package.json` 文件中的版本更新），然后合并它。这样可以保持 `main` 分支中的版本为最新。 ## 发布验证 @@ -75,14 +75,14 @@ npm install -g @qwen-code/qwen-code@nightly - `npx -y @qwen-code/qwen-code@latest --version` 用于验证推送是否按预期工作（如果你不是在推送 rc 或 dev 标签） - `npx -y @qwen-code/qwen-code@ --version` 用于验证标签是否正确推送 - _这会在本地造成破坏性影响_ `npm uninstall @qwen-code/qwen-code && npm uninstall -g @qwen-code/qwen-code && npm cache clean --force && npm install @qwen-code/qwen-code@` -- 建议对几个 LLM 命令和工具进行基本的运行测试，以冒烟测试包是否按预期工作。我们未来会进一步规范化这一流程。 +- 建议对几个 LLM 命令和工具进行基本的运行测试，以冒烟测试包是否按预期工作。我们将在未来进一步规范化这一流程。 ## 何时合并版本变更，何时不合并？ 从当前或较旧的 commit 创建 patch 或 hotfix 发布的上述模式会使 repository 处于以下状态： -1. Tag (`vX.Y.Z-patch.1`)：这个 tag 正确指向 main 分支上包含你打算发布的稳定代码的原始 commit。这一点至关重要。任何人检出这个 tag 都能得到确切的已发布代码。 -2. Branch (`release-vX.Y.Z-patch.1`)：这个分支在 tagged commit 的基础上包含一个新的 commit。这个新 commit 只包含 package.json 中的版本号变更（以及其他相关文件如 package-lock.json）。 +1. Tag (`vX.Y.Z-patch.1`)：这个 tag 正确指向 main 分支上包含你打算发布的稳定代码的原始 commit。这一点至关重要。任何检出这个 tag 的人都能获得确切的发布代码。 +2. Branch (`release-vX.Y.Z-patch.1`)：这个分支在 tag 指向的 commit 基础上包含一个新的 commit。这个新 commit 只包含 package.json 中的版本号变更（以及其他相关文件如 package-lock.json）。 这种分离是很好的做法。它让你的 main 分支历史保持干净，不会包含发布特定的版本号提升，直到你决定合并它们。 @@ -92,16 +92,16 @@ npm install -g @qwen-code/qwen-code@nightly 对于任何稳定补丁或热修复版本，你几乎总是需要将 `release-` 分支合并回 `main` 分支。 -- **为什么？** 主要原因是为了更新 main 分支中 package.json 的版本号。如果你从一个较旧的 commit 发布了 v1.2.1 版本，但从未将版本号更新合并回 main 分支，那么你的 main 分支的 package.json 仍然会显示 "version": "1.2.0"。下一个开始开发下一个功能版本（v1.3.0）的开发者将会基于一个版本号不正确、较旧的代码库进行开发。这会导致混淆，并需要后续手动更新版本号。 +- **为什么？** 主要原因是为了更新 main 分支中 package.json 的版本号。如果你从一个较旧的 commit 发布了 v1.2.1 版本，但从未将版本号更新合并回 main 分支，那么你的 main 分支中的 package.json 仍然会显示 `"version": "1.2.0"`。下一个为下一个功能版本（v1.3.0）开始工作的开发者将会从一个版本号不正确、较旧的代码库中创建分支。这会导致混淆，并需要后续手动更新版本号。 -- **流程：** 在 release-v1.2.1 分支创建完成并且 package 成功发布后，你应该创建一个 pull request 将 release-v1.2.1 分支合并到 main 分支。这个 PR 只会包含一个 commit："chore: bump version to v1.2.1"。这是一个干净、简单的集成操作，能够保持你的 main 分支与最新发布的版本同步。 +- **流程：** 在 release-v1.2.1 分支创建完成并且包成功发布后，你应该创建一个 pull request 将 release-v1.2.1 合并到 main 分支。这个 PR 只包含一个 commit：`"chore: bump version to v1.2.1"`。这是一个干净、简单的集成，能够保持你的 main 分支与最新发布的版本同步。 ### 预发布版本（RC、Beta、Dev）不要合并回主分支 -通常情况下，预发布版本的 release branch 不需要合并回 `main` 分支。 +通常情况下，你不应该将预发布版本的 release 分支合并回 `main` 分支。 -- **为什么？** 预发布版本（例如 v1.3.0-rc.1、v1.3.0-rc.2）本质上是不稳定的临时版本。你不希望因为一系列的 RC 版本更新而污染 main 分支的提交历史。main 分支中的 package.json 应该反映最新的稳定版本号，而不是 RC 版本。 -- **流程说明：** 创建 release-v1.3.0-rc.1 分支后，执行 `npm publish --tag rc` 发布操作，之后这个分支就完成了它的使命，可以直接删除。RC 版本的代码其实已经存在于 main 分支（或某个 feature branch）中了，所以不会丢失任何功能代码。release branch 只是用来临时承载版本号的载体。 +- 为什么？预发布版本（例如 v1.3.0-rc.1、v1.3.0-rc.2）本质上就是不稳定的临时版本。你不希望用一系列的 RC 版本号更新来污染 main 分支的历史记录。main 分支中的 package.json 应该反映最新的稳定版本，而不是 RC 版本。 +- 流程：创建 release-v1.3.0-rc.1 分支，执行 `npm publish --tag rc`，然后……这个分支就完成使命了。你可以直接删除它。RC 版本的代码已经在 main 分支（或某个 feature 分支）上了，所以不会丢失任何功能代码。release 分支只是用来临时承载版本号的载体。 ## 本地测试与验证：打包和发布流程的变更 @@ -112,11 +112,11 @@ npm install -g @qwen-code/qwen-code@nightly 3. 保持 `dry_run` 选项为勾选状态（即 `true`）。 4. 点击 "Run workflow" 按钮。 -这将运行整个发布流程，但会跳过 `npm publish` 和 `gh release create` 步骤。你可以查看 workflow 日志，确保一切按预期工作。 +这将运行完整的发布流程，但会跳过 `npm publish` 和 `gh release create` 步骤。你可以查看 workflow 日志，确保一切按预期工作。 -在提交任何对打包和发布流程的更改之前，在本地进行测试是至关重要的。这样可以确保包能被正确发布，并且在用户安装时能按预期工作。 +在提交任何对打包和发布流程的更改之前，在本地进行测试是至关重要的。这样可以确保包能被正确发布，并且用户安装后能按预期工作。 -要验证你的更改，可以执行一次发布流程的 dry run。这将模拟发布过程，而不会真正将包发布到 npm registry。 +要验证你的更改，可以执行一次发布流程的 dry run。这会模拟发布过程，但不会真正将包发布到 npm registry。 ```bash npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run @@ -131,35 +131,35 @@ npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME=" 然后你可以检查生成的 tarball，确保它们包含正确的文件，并且 `package.json` 文件已正确更新。tarball 将在每个包的根目录下生成（例如：`packages/cli/google-gemini-cli-0.1.6.tgz`）。 -通过执行 dry run，你可以确认你对打包流程的修改是正确的，并且包将能成功发布。 +通过执行 dry run，你可以确认对打包流程的修改是正确的，并确保包能成功发布。 ## Release Deep Dive -发布流程的主要目标是从 `packages/` 目录中获取源代码，进行构建，并在项目根目录下的临时 `bundle` 文件夹中组装一个干净、自包含的 package。这个 `bundle` 目录才是最终发布到 NPM 的内容。 +发布流程的主要目标是从 `packages/` 目录中获取源代码，进行构建，并在项目根目录下的临时 `bundle` 文件夹中组装出一个干净、自包含的 package。这个 `bundle` 目录就是最终发布到 NPM 的内容。 以下是关键阶段： ### 阶段 1：发布前检查与版本更新 - **发生了什么**：在移动任何文件之前，流程会确保项目处于良好状态。这包括运行测试、linting 和类型检查（`npm run preflight`）。同时，根目录下的 `package.json` 和 `packages/cli/package.json` 中的版本号会被更新为新的发布版本。 -- **为什么这样做**：这确保只有高质量、可运行的代码才会被发布。版本更新是新发布的第一个标志。 +- **为什么这样做**：这保证了只有高质量、可运行的代码才会被发布。版本更新是标识新发布的第一个步骤。 ### 阶段 2：构建源代码 -- **发生了什么**：将 `packages/core/src` 和 `packages/cli/src` 中的 TypeScript 源代码编译为 JavaScript。 +- **发生了什么**：将 `packages/core/src` 和 `packages/cli/src` 中的 TypeScript 源代码编译成 JavaScript。 - **文件移动**： - - `packages/core/src/**/*.ts` -> 编译为 -> `packages/core/dist/` - - `packages/cli/src/**/*.ts` -> 编译为 -> `packages/cli/dist/` -- **为什么这样做**：开发时编写的 TypeScript 需要转换为 Node.js 可以运行的纯 JavaScript。core 包会先构建，因为 cli 包依赖它。 + - `packages/core/src/**/*.ts` -> 编译后 -> `packages/core/dist/` + - `packages/cli/src/**/*.ts` -> 编译后 -> `packages/cli/dist/` +- **为什么这样做**：开发时编写的 TypeScript 代码需要转换为 Node.js 可执行的纯 JavaScript。core 包优先构建，因为 cli 包依赖它。 ### 阶段 3：组装最终可发布的 package 这是最关键的一个阶段，文件会被移动并转换为最终用于发布的状态。项目根目录会创建一个临时的 `bundle` 文件夹，用于存放最终 package 的内容。 -#### 1. 转换 `package.json` +#### 1. `package.json` 被转换 -- **发生了什么**：读取 `packages/cli/` 中的 `package.json`，进行修改后写入项目根目录的 `bundle/` 文件夹中。 -- **文件移动**：`packages/cli/package.json` -> （内存中转换） -> `bundle/package.json` +- **发生了什么**：读取 `packages/cli/package.json`，进行修改后写入项目根目录的 `bundle/` 文件夹中。 +- **文件移动**：`packages/cli/package.json` -> （内存中转换）-> `bundle/package.json` - **为什么这样做**：最终的 `package.json` 必须与开发时使用的不同。关键变化包括： - 移除 `devDependencies`。 - 移除 workspace 特定的依赖 `"dependencies": { "@gemini-cli/core": "workspace:*" }`，并确保 core 代码被直接打包进最终的 JavaScript 文件中。 @@ -168,8 +168,8 @@ npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME=" #### 2. 创建 JavaScript Bundle - **发生了什么**：将 `packages/core/dist` 和 `packages/cli/dist` 中构建好的 JavaScript 代码打包成一个单独的可执行 JavaScript 文件。 -- **文件移动**：`packages/cli/dist/index.js` + `packages/core/dist/index.js` -> （由 esbuild 打包） -> `bundle/gemini.js`（或类似名称）。 -- **为什么这样做**：这样可以生成一个包含所有必要应用代码的单一优化文件。它简化了 package，不再需要将 core 包作为单独的 NPM 依赖，因为其代码已直接包含在内。 +- **文件移动**：`packages/cli/dist/index.js` + `packages/core/dist/index.js` -> （由 esbuild 打包）-> `bundle/gemini.js`（或类似名称）。 +- **为什么这样做**：这样可以创建一个包含所有必要应用代码的单一优化文件。通过将 core 代码直接包含进来，避免了将其作为单独依赖发布到 NPM 的需要，从而简化了 package。 #### 3. 复制静态和支持文件 @@ -177,15 +177,15 @@ npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME=" - **文件移动**： - `README.md` -> `bundle/README.md` - `LICENSE` -> `bundle/LICENSE` - - `packages/cli/src/utils/*.sb`（沙箱配置文件） -> `bundle/` + - `packages/cli/src/utils/*.sb`（sandbox profiles）-> `bundle/` - **为什么这样做**： - `README.md` 和 `LICENSE` 是任何 NPM package 都应包含的标准文件。 - - 沙箱配置文件（.sb 文件）是 CLI 沙箱功能运行所必需的关键运行时资源，必须与最终可执行文件位于同一目录。 + - sandbox profiles（.sb 文件）是 CLI 的沙箱功能运行所必需的关键运行时资源，必须与最终可执行文件位于同一目录下。 ### 阶段 4：发布到 NPM - **发生了什么**：在项目根目录的 `bundle` 文件夹中运行 `npm publish` 命令。 -- **为什么这样做**：通过在 `bundle` 目录中运行 `npm publish`，只有我们在阶段 3 中精心组装的文件会被上传到 NPM registry。这可以防止源代码、测试文件或开发配置被意外发布，从而为用户提供一个干净、最小化的 package。 +- **为什么这样做**：通过在 `bundle` 目录中运行 `npm publish`，只有我们在阶段 3 中精心组装的文件会被上传到 NPM registry。这样可以防止源代码、测试文件或开发配置被意外发布，确保用户获得的是干净、最小化的 package。 ### 文件流转概览 @@ -223,7 +223,7 @@ graph TD J --> G --> K ``` -这个流程确保最终发布的 artifact 是一个专为发布而构建的、干净且高效的项目表示，而不是开发工作区的直接拷贝。 +这个流程确保了最终发布的 artifact 是一个专为发布而构建的、干净且高效的项目表示，而不是开发工作区的直接拷贝。 ## NPM Workspaces @@ -231,7 +231,7 @@ graph TD ### 工作原理 -根目录下的 `package.json` 文件定义了本项目的工作区： +根目录的 `package.json` 文件定义了本项目的 workspaces： ```json { diff --git a/website/content/zh/tools/file-system.md b/website/content/zh/tools/file-system.md index b0c2cbbc..6439022b 100644 --- a/website/content/zh/tools/file-system.md +++ b/website/content/zh/tools/file-system.md @@ -2,7 +2,7 @@ Qwen Code 提供了一套全面的工具，用于与本地文件系统进行交互。这些工具允许模型在你的控制下读取、写入、列出、搜索和修改文件及目录，敏感操作通常需要确认。 -**注意：** 出于安全考虑，所有文件系统工具都在一个 `rootDirectory`（通常是启动 CLI 的当前工作目录）内运行。你提供给这些工具的路径通常应为绝对路径，或相对于该根目录解析。 +**注意：** 出于安全考虑，所有文件系统工具都在一个 `rootDirectory`（通常是启动 CLI 的当前工作目录）内运行。你提供给这些工具的路径通常应为绝对路径，或相对于该根目录解析的路径。 ## 1. `list_directory` (ReadFolder) @@ -32,15 +32,15 @@ Qwen Code 提供了一套全面的工具，用于与本地文件系统进行交 - **Parameters:** - `path` (string, required): 要读取的文件的绝对路径。 - `offset` (number, optional): 对于文本文件，表示从第几行开始读取（从 0 开始计数）。需要配合 `limit` 使用。 - - `limit` (number, optional): 对于文本文件，表示最多读取多少行。如果省略，则读取默认最大行数（例如 2000 行），或者在可行的情况下读取整个文件。 + - `limit` (number, optional): 对于文本文件，表示最多读取多少行。如果未设置，则默认读取最大行数（例如 2000 行），或者在可行的情况下读取整个文件。 - **Behavior:** - 对于文本文件：返回文件内容。如果使用了 `offset` 和 `limit`，则只返回对应范围的行内容。如果因行数限制或单行长度限制导致内容被截断，会进行提示。 - 对于图像和 PDF 文件：以 base64 编码的数据结构返回文件内容，适用于模型处理。 - - 对于其他二进制文件：尝试识别并跳过，返回一条消息说明这是一个通用二进制文件。 + - 对于其他二进制文件：尝试识别并跳过，返回提示信息说明这是一个通用二进制文件。 - **Output:** (`llmContent`): - 对于文本文件：返回文件内容，可能带有截断提示信息（例如 `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`）。 - 对于图像/PDF 文件：返回一个包含 `inlineData` 的对象，其中包含 `mimeType` 和 base64 编码的 `data`（例如 `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`）。 - - 对于其他二进制文件：返回类似 `Cannot display content of binary file: /path/to/data.bin` 的消息。 + - 对于其他二进制文件：返回类似 `Cannot display content of binary file: /path/to/data.bin` 的提示信息。 - **Confirmation:** No. ## 3. `write_file` (WriteFile) @@ -57,7 +57,7 @@ Qwen Code 提供了一套全面的工具，用于与本地文件系统进行交 - 将提供的 `content` 写入 `file_path`。 - 如果父目录不存在，则会自动创建。 - **Output (`llmContent`):** 成功消息，例如：`Successfully overwrote file: /path/to/your/file.txt` 或 `Successfully created and wrote to new file: /path/to/new/file.txt`。 -- **Confirmation:** 是。在写入前会显示变更的 diff 并请求用户确认。 +- **Confirmation:** 是。在写入前会显示变更的 diff 并要求用户确认。 ## 4. `glob` (FindFiles) @@ -89,10 +89,13 @@ Qwen Code 提供了一套全面的工具，用于与本地文件系统进行交 - `pattern` (string, required): 要搜索的正则表达式（regex）（例如 `"function\s+myFunction"`）。 - `path` (string, optional): 要搜索的目录的绝对路径。默认为当前工作目录。 - `include` (string, optional): 用于过滤搜索文件的 glob 模式（例如 `"*.js"`、`"src/**/*.{ts,tsx}"`）。如果省略，则搜索大多数文件（遵循常见的忽略规则）。 + - `maxResults` (number, optional): 返回的最大匹配数量，防止上下文溢出（默认值：20，最大值：100）。对于广泛搜索使用较低值，对于精确搜索使用较高值。 - **Behavior:** - - 如果在 Git 仓库中可用，则优先使用 `git grep` 以提高速度；否则回退到系统 `grep` 或基于 JavaScript 的搜索。 - - 返回匹配的行列表，每行前面附带其文件路径（相对于搜索目录）和行号。 -- **Output (`llmContent`):** 格式化后的匹配结果字符串，例如： + - 如果在 Git 仓库中可用，则使用 `git grep` 以提高速度；否则回退到系统 `grep` 或基于 JavaScript 的搜索。 + - 返回匹配行的列表，每行前面带有其文件路径（相对于搜索目录）和行号。 + - 默认将结果限制为最多 20 个匹配项以防止上下文溢出。当结果被截断时，会显示明确的警告，并提供优化搜索的建议。 +- **Output (`llmContent`):** 格式化的匹配结果字符串，例如： + ``` Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"): --- @@ -103,38 +106,65 @@ Qwen Code 提供了一套全面的工具，用于与本地文件系统进行交 File: src/index.ts L5: import { myFunction } from './utils'; --- + + WARNING: Results truncated to prevent context overflow. To see more results: + - Use a more specific pattern to reduce matches + - Add file filters with the 'include' parameter (e.g., "*.js", "src/**") + - Specify a narrower 'path' to search in a subdirectory + - Increase 'maxResults' parameter if you need more matches (current: 20) ``` + - **Confirmation:** No. +### `search_file_content` 示例 + +使用默认结果限制搜索模式： + +``` +search_file_content(pattern="function\s+myFunction", path="src") +``` + +使用自定义结果限制搜索模式： + +``` +search_file_content(pattern="function", path="src", maxResults=50) +``` + +使用文件过滤和自定义结果限制搜索模式： + +``` +search_file_content(pattern="function", include="*.js", maxResults=10) +``` + ## 6. `replace` (编辑) -`replace` 用于替换文件中的文本。默认情况下，只替换第一个匹配项，但如果指定了 `expected_replacements` 参数，则可以替换多个匹配项。此工具设计用于精确、有针对性的修改，并要求 `old_string` 周围有足够的上下文，以确保修改的是正确位置。 +`replace` 用于替换文件中的文本。默认情况下，只替换第一个匹配项，但如果指定了 `expected_replacements` 参数，则可以替换多个匹配项。此工具专为精确、有针对性的修改而设计，要求 `old_string` 周围有足够的上下文，以确保修改的是正确的位置。 - **工具名称:** `replace` - **显示名称:** Edit - **文件:** `edit.ts` - **参数:** - `file_path` (string, 必填): 要修改的文件的绝对路径。 - - `old_string` (string, 必填): 需要被替换的确切文本。 + - `old_string` (string, 必填): 需要被替换的确切文本内容。 **重要提示：** 此字符串必须能唯一标识要更改的那一处内容。它应至少包含目标文本**之前**和**之后**各 3 行的上下文，并且要精确匹配空格和缩进。如果 `old_string` 为空，则工具会尝试在 `file_path` 创建一个新文件，并将 `new_string` 作为其内容。 - - `new_string` (string, 必填): 用来替换 `old_string` 的确切文本。 + - `new_string` (string, 必填): 用来替换 `old_string` 的确切文本内容。 - `expected_replacements` (number, 可选): 要替换的匹配次数。默认值为 `1`。 - **行为:** - - 如果 `old_string` 为空，且 `file_path` 不存在，则创建一个新文件，内容为 `new_string`。 - - 如果提供了 `old_string`，则读取 `file_path` 并尝试找到唯一一处匹配的 `old_string`。 + - 如果 `old_string` 为空，且 `file_path` 不存在，则会创建一个新文件，并将 `new_string` 作为其内容。 + - 如果提供了 `old_string`，工具会读取 `file_path` 文件，并尝试找到唯一一处与 `old_string` 匹配的内容。 - 找到后，将其替换为 `new_string`。 - **增强可靠性（多阶段编辑校正）：** 为了显著提高编辑成功率，尤其是在模型提供的 `old_string` 可能不够精确的情况下，工具引入了多阶段编辑校正机制。 - - 如果初始的 `old_string` 未找到或匹配多个位置，工具可以借助 Gemini 模型迭代优化 `old_string`（以及可能的 `new_string`）。 - - 这种自我校正过程会尝试识别模型原本想要修改的唯一段落，使 `replace` 操作即使在初始上下文略有偏差时也更加稳健。 + - 如果初始的 `old_string` 未找到或匹配到多个位置，工具可以借助 Gemini 模型迭代优化 `old_string`（以及可能的 `new_string`）。 + - 这种自我校正过程会尝试识别模型原本想要修改的唯一段落，使 `replace` 操作即使在初始上下文稍有偏差时也更加稳健。 - **失败条件：** 尽管有校正机制，工具仍会在以下情况下失败： - `file_path` 不是绝对路径，或超出了根目录范围。 - - `old_string` 非空，但 `file_path` 不存在。 - - `old_string` 为空，但 `file_path` 已存在。 - - 经过尝试校正后，`old_string` 仍无法在文件中找到。 - - `old_string` 在文件中匹配多处，且自我校正机制无法将其解析为唯一、明确的匹配项。 + - `old_string` 非空，但 `file_path` 文件不存在。 + - `old_string` 为空，但 `file_path` 文件已存在。 + - 经过尝试校正后，`old_string` 在文件中仍找不到。 + - `old_string` 在文件中匹配到多个位置，且自我校正机制无法将其解析为唯一、明确的匹配项。 - **输出 (`llmContent`):** - 成功时：`Successfully modified file: /path/to/file.txt (1 replacements).` 或 `Created new file: /path/to/new_file.txt with provided content.` - 失败时：返回错误信息说明原因（例如：`Failed to edit, 0 occurrences found...`，`Failed to edit, expected 1 occurrences but found 2...`）。 diff --git a/website/content/zh/tools/index.md b/website/content/zh/tools/index.md index 26350a20..4a1e8e9b 100644 --- a/website/content/zh/tools/index.md +++ b/website/content/zh/tools/index.md @@ -1,6 +1,6 @@ # Qwen Code 工具 -Qwen Code 内置了一系列工具，模型可以通过这些工具与你的本地环境进行交互、获取信息并执行操作。这些工具扩展了 CLI 的功能，使其不仅限于文本生成，还能协助处理各种任务。 +Qwen Code 内置了一系列工具，模型可以通过这些工具与你的本地环境进行交互、获取信息并执行操作。这些工具增强了 CLI 的功能，使其不仅限于文本生成，还能协助处理各种任务。 ## Qwen Code 工具概述 @@ -22,35 +22,36 @@ Qwen Code 内置了一系列工具，模型可以通过这些工具与你的本 1. 你向 CLI 提供一个 prompt。 2. CLI 将该 prompt 发送给 core。 -3. core 结合你的 prompt 和对话历史，将可用工具列表及其描述/结构发送给配置好的 model API。 -4. 模型分析你的请求。如果它判断需要使用某个工具，其响应中将包含调用特定工具并附带参数的请求。 -5. core 接收到这个工具调用请求后会进行验证，并（通常在用户确认敏感操作后）执行该工具。 -6. 工具的输出结果会被发送回模型。 -7. 模型利用工具的输出结果生成最终答案，并通过 core 返回给 CLI，最终展示给你。 +3. core 结合你的 prompt 和对话历史，将可用工具列表及其描述/schema 发送给配置好的 model API。 +4. model 分析你的请求。如果它判断需要使用某个工具，其响应中将包含一个调用特定工具并附带参数的请求。 +5. core 接收到这个工具调用请求后，会进行验证，并（在敏感操作时通常需要用户确认）执行该工具。 +6. 工具的输出结果会被发送回 model。 +7. model 利用工具的输出结果生成最终回答，并通过 core 返回给 CLI，最终展示给你。 -在 CLI 中，你通常会看到提示信息，告知你某个工具正在被调用以及调用是否成功或失败。 +在 CLI 中，你通常会看到提示信息，告知你某个工具正在被调用以及调用是否成功。 ## 安全性和确认机制 许多工具，特别是那些可以修改文件系统或执行命令的工具（如 `write_file`、`edit`、`run_shell_command`），在设计时就考虑了安全性。Qwen Code 通常会： - **要求确认：** 在执行可能敏感的操作之前提示你，并显示即将执行的操作。 -- **使用沙箱：** 所有工具都受到沙箱强制实施的限制（参见 [Qwen Code 中的沙箱](../sandbox.md)）。这意味着在沙箱中操作时，你希望使用的任何工具（包括 MCP 服务器）都必须在沙箱环境**内部**可用。例如，要通过 `npx` 运行 MCP 服务器，`npx` 可执行文件必须安装在沙箱的 Docker 镜像中，或者在 `sandbox-exec` 环境中可用。 +- **使用沙箱：** 所有工具都受到沙箱强制实施的限制（参见 [Qwen Code 中的沙箱](../sandbox.md)）。这意味着在沙箱中操作时，你希望使用的任何工具（包括 MCP 服务器）都必须在沙箱环境 _内部_ 可用。例如，要通过 `npx` 运行 MCP 服务器，`npx` 可执行文件必须安装在沙箱的 Docker 镜像中，或者在 `sandbox-exec` 环境中可用。 在允许工具继续执行之前，仔细查看确认提示非常重要。 ## 了解更多关于 Qwen Code 的工具 -Qwen Code 的内置工具可以大致分为以下几类： +Qwen Code 内置的工具可以大致分为以下几类： -- **[File System Tools](./file-system.md)：** 用于与文件和目录交互（读取、写入、列出、搜索等）。 +- **[File System Tools](./file-system.md)：** 用于与文件和目录进行交互（读取、写入、列出、搜索等）。 - **[Shell Tool](./shell.md) (`run_shell_command`)：** 用于执行 shell 命令。 - **[Web Fetch Tool](./web-fetch.md) (`web_fetch`)：** 用于从 URL 获取内容。 - **[Web Search Tool](./web-search.md) (`web_search`)：** 用于搜索网络。 -- **[Multi-File Read Tool](./multi-file.md) (`read_many_files`)：** 一个专门用于从多个文件或目录读取内容的工具，通常由 `@` 命令使用。 -- **[Memory Tool](./memory.md) (`save_memory`)：** 用于在会话之间保存和回忆信息。 +- **[Multi-File Read Tool](./multi-file.md) (`read_many_files`)：** 一个专门用于从多个文件或目录中读取内容的工具，通常由 `@` 命令使用。 +- **[Memory Tool](./memory.md) (`save_memory`)：** 用于在不同会话之间保存和回忆信息。 +- **[Todo Write Tool](./todo-write.md) (`todo_write`)：** 用于在编码会话期间创建和管理结构化任务列表。 -此外，这些工具还包含： +此外，这些工具还集成了： -- **[MCP servers](./mcp-server.md)：** MCP 服务器作为模型与本地环境或其他服务（如 API）之间的桥梁。 +- **[MCP servers](./mcp-server.md)：** MCP 服务器充当模型与本地环境或其他服务（如 API）之间的桥梁。 - **[Sandboxing](../sandbox.md)：** 沙箱机制将模型及其更改与你的环境隔离，以降低潜在风险。 \ No newline at end of file diff --git a/website/content/zh/tools/shell.md b/website/content/zh/tools/shell.md index 0ece930c..5ffa44fd 100644 --- a/website/content/zh/tools/shell.md +++ b/website/content/zh/tools/shell.md @@ -1,6 +1,6 @@ # Shell 工具 (`run_shell_command`) -本文档介绍了 Qwen Code 的 `run_shell_command` 工具。 +本文档描述了用于 Qwen Code 的 `run_shell_command` 工具。 ## 描述 @@ -10,78 +10,129 @@ `run_shell_command` 接受以下参数： -- `command`（string，必填）：要执行的确切 shell 命令。 -- `description`（string，可选）：命令用途的简要描述，将展示给用户。 -- `directory`（string，可选）：执行命令的目录（相对于项目根目录）。如果未提供，则命令将在项目根目录中运行。 +- `command` (string, 必填): 要执行的确切 shell 命令。 +- `description` (string, 可选): 命令用途的简要描述，将显示给用户。 +- `directory` (string, 可选): 执行命令的目录（相对于项目根目录）。如果未提供，则命令在项目根目录中运行。 +- `is_background` (boolean, 必填): 是否在后台运行命令。此参数是必需的，以确保对命令执行模式进行明确的决策。对于应该在不阻塞后续命令的情况下继续运行的长时间运行进程（如开发服务器、监听器或守护进程），设置为 true。对于应在继续执行之前完成的一次性命令，设置为 false。 ## 如何在 Qwen Code 中使用 `run_shell_command` -使用 `run_shell_command` 时，命令会作为子进程执行。`run_shell_command` 可以通过 `&` 启动后台进程。该工具会返回详细的执行信息，包括： +使用 `run_shell_command` 时，命令会作为子进程执行。你可以通过 `is_background` 参数控制命令是在后台还是前台运行，或者显式地在命令后添加 `&`。该工具会返回详细的执行信息，包括： -- `Command`：实际执行的命令。 -- `Directory`：命令执行所在的目录。 -- `Stdout`：标准输出流的内容。 -- `Stderr`：标准错误流的内容。 -- `Error`：子进程报告的错误信息。 +### 必需的 Background 参数 + +`is_background` 参数对于所有命令执行来说都是**必需的**。这样设计是为了确保 LLM（以及用户）必须显式决定每个命令是在后台还是前台运行，从而促进命令执行行为的明确性和可预测性。通过将此参数设为必填项，我们可以避免在处理长时间运行的进程时，意外回退到前台执行而导致后续操作被阻塞。 + +### 后台 vs 前台执行 + +该工具会根据你的明确选择智能地处理后台和前台执行： + +**使用后台执行 (`is_background: true`) 适用于：** + +- 长时间运行的开发服务器：`npm run start`、`npm run dev`、`yarn dev` +- 构建监听器：`npm run watch`、`webpack --watch` +- 数据库服务器：`mongod`、`mysql`、`redis-server` +- Web 服务器：`python -m http.server`、`php -S localhost:8000` +- 任何预期会无限期运行直到手动停止的命令 + +**使用前台执行 (`is_background: false`) 适用于：** + +- 一次性命令：`ls`、`cat`、`grep` +- 构建命令：`npm run build`、`make` +- 安装命令：`npm install`、`pip install` +- Git 操作：`git commit`、`git push` +- 测试运行：`npm test`、`pytest` + +### 执行信息 + +该工具会返回详细的执行信息，包括： + +- `Command`：执行的命令。 +- `Directory`：命令运行的目录。 +- `Stdout`：标准输出流的输出内容。 +- `Stderr`：标准错误流的输出内容。 +- `Error`：子进程报告的任何错误信息。 - `Exit Code`：命令的退出码。 -- `Signal`：如果命令被信号终止，则显示信号编号。 -- `Background PIDs`：所有启动的后台进程的 PID 列表。 +- `Signal`：如果命令被信号终止，则为信号编号。 +- `Background PIDs`：启动的任何后台进程的 PID 列表。 用法： +```bash +run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.", is_background=false) ``` -run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.") -``` + +**注意：** `is_background` 参数是必需的，每次命令执行时都必须明确指定。 ## `run_shell_command` 示例 列出当前目录中的文件： -``` -run_shell_command(command="ls -la") +```bash +run_shell_command(command="ls -la", is_background=false) ``` 在指定目录中运行脚本： +```bash +run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script", is_background=false) +``` + +启动后台开发服务器（推荐方式）： + +```bash +run_shell_command(command="npm run dev", description="Start development server in background", is_background=true) ``` -run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script") + +启动后台服务器（使用显式 & 的替代方式）： + +```bash +run_shell_command(command="npm run dev &", description="Start development server in background", is_background=false) ``` -启动后台服务器： +在前台运行构建命令： +```bash +run_shell_command(command="npm run build", description="Build the project", is_background=false) ``` -run_shell_command(command="npm run dev &", description="Start development server in background") + +启动多个后台服务： + +```bash +run_shell_command(command="docker-compose up", description="Start all services", is_background=true) ``` ## 重要说明 -- **安全性：** 执行命令时要小心，特别是那些由用户输入构造的命令，以防止安全漏洞。 -- **交互式命令：** 避免需要交互式用户输入的命令，因为这可能导致工具挂起。如果可用，请使用非交互式标志（例如 `npm init -y`）。 +- **安全性：** 执行命令时要谨慎，特别是那些由用户输入构造的命令，以防止安全漏洞。 +- **交互式命令：** 避免使用需要交互式用户输入的命令，因为这可能导致工具挂起。如果可用，请使用非交互式标志（例如 `npm init -y`）。 - **错误处理：** 检查 `Stderr`、`Error` 和 `Exit Code` 字段以确定命令是否成功执行。 -- **后台进程：** 当使用 `&` 在后台运行命令时，工具会立即返回，而进程将在后台继续运行。`Background PIDs` 字段将包含后台进程的进程 ID。 +- **后台进程：** 当 `is_background=true` 或命令包含 `&` 时，工具将立即返回，进程将在后台继续运行。`Background PIDs` 字段将包含后台进程的进程 ID。 +- **后台执行选择：** `is_background` 参数是必需的，它提供了对执行模式的显式控制。你也可以在命令中添加 `&` 来手动后台执行，但仍然必须指定 `is_background` 参数。该参数提供了更清晰的意图，并自动处理后台执行设置。 +- **命令描述：** 当使用 `is_background=true` 时，命令描述将包含 `[background]` 指示器，以清楚地显示执行模式。 ## 环境变量 -当 `run_shell_command` 执行命令时，它会在子进程的环境中设置 `QWEN_CODE=1` 环境变量。这允许脚本或工具检测它们是否从 CLI 中运行。 +当 `run_shell_command` 执行命令时，它会在子进程的环境中设置 `QWEN_CODE=1` 环境变量。这允许脚本或工具检测它们是否是从 CLI 中运行的。 ## 命令限制 你可以通过在配置文件中使用 `coreTools` 和 `excludeTools` 设置来限制 `run_shell_command` 工具可以执行的命令。 -- `coreTools`：要将 `run_shell_command` 限制为特定的一组命令，请在 `coreTools` 列表中添加格式为 `run_shell_command()` 的条目。例如，`"coreTools": ["run_shell_command(git)"]` 将只允许执行 `git` 命令。如果包含通用的 `run_shell_command`，则作为通配符处理，允许执行任何未被明确阻止的命令。 +- `coreTools`：要将 `run_shell_command` 限制为特定的一组命令，请在 `coreTools` 列表中添加格式为 `run_shell_command()` 的条目。例如，`"coreTools": ["run_shell_command(git)"]` 将只允许执行 `git` 命令。如果包含通用的 `run_shell_command`，则相当于通配符，允许执行任何未被明确阻止的命令。 - `excludeTools`：要阻止特定命令，请在 `excludeTools` 列表中添加格式为 `run_shell_command()` 的条目。例如，`"excludeTools": ["run_shell_command(rm)"]` 将阻止执行 `rm` 命令。 验证逻辑设计得既安全又灵活： -1. **禁用命令链**：工具会自动将使用 `&&`、`||` 或 `;` 连接的命令拆分，并分别验证每个部分。如果链条中的任何一部分不被允许，则整个命令将被阻止。 +1. **禁用命令链**：工具会自动将使用 `&&`、`||` 或 `;` 连接的命令拆分，并分别验证每个部分。如果链条中的任何部分不被允许，则整个命令将被阻止。 2. **前缀匹配**：工具使用前缀匹配。例如，如果你允许 `git`，那么你可以运行 `git status` 或 `git log`。 -3. **黑名单优先**：始终优先检查 `excludeTools` 列表。如果某个命令匹配了被阻止的前缀，即使它也匹配 `coreTools` 中允许的前缀，该命令仍将被拒绝。 +3. **黑名单优先**：始终优先检查 `excludeTools` 列表。如果命令匹配了被阻止的前缀，即使它也匹配了 `coreTools` 中允许的前缀，该命令仍将被拒绝。 ### 命令限制示例 **仅允许特定命令前缀** -若只允许 `git` 和 `npm` 命令，阻止其他所有命令： +若只允许执行 `git` 和 `npm` 命令，其他命令均被阻止： ```json { @@ -95,7 +146,7 @@ run_shell_command(command="npm run dev &", description="Start development server **阻止特定命令前缀** -若要阻止 `rm` 命令，同时允许所有其他命令： +若要阻止 `rm` 命令，但允许所有其他命令： ```json { @@ -135,6 +186,6 @@ run_shell_command(command="npm run dev &", description="Start development server - `ls -l`：阻止 - `any other command`：阻止 -## `excludeTools` 安全说明 +## `excludeTools` 安全提醒 `excludeTools` 中针对 `run_shell_command` 的命令限制是基于简单的字符串匹配实现的，很容易被绕过。此功能**不是一种安全机制**，不应依赖它来安全地执行不受信任的代码。建议使用 `coreTools` 来显式选择可以执行的命令。 \ No newline at end of file diff --git a/website/content/zh/tools/todo-write.md b/website/content/zh/tools/todo-write.md new file mode 100644 index 00000000..6a3bf80a --- /dev/null +++ b/website/content/zh/tools/todo-write.md @@ -0,0 +1,63 @@ +# Todo Write Tool (`todo_write`) + +本文档描述了用于 Qwen Code 的 `todo_write` 工具。 + +## 描述 + +使用 `todo_write` 为当前 coding session 创建和管理结构化的任务列表。该工具帮助 AI assistant 跟踪进度并组织复杂任务，让你能够清楚地了解正在进行的工作。 + +### 参数 + +`todo_write` 接受一个参数： + +- `todos` (array, 必填): 一个包含待办事项的数组，每个项目包含： + - `id` (string, 必填): 待办事项的唯一标识符。 + - `content` (string, 必填): 任务的描述。 + - `status` (string, 必填): 当前状态（`pending`、`in_progress` 或 `completed`）。 + +## 如何在 Qwen Code 中使用 `todo_write` + +在处理复杂的、多步骤的任务时，AI 助手会自动使用这个工具。你无需显式调用它，但如果你希望查看请求的计划执行步骤，可以要求助手创建一个待办事项列表。 + +该工具会将待办事项列表存储在你的主目录下（`~/.qwen/todos/`），并为每个会话创建独立的文件，因此每个编程会话都会维护其专属的任务列表。 + +## AI 何时使用此工具 + +助手会在以下场景中使用 `todo_write`： + +- 需要多个步骤才能完成的复杂任务 +- 涉及多个组件的功能实现 +- 跨多个文件的重构操作 +- 任何需要执行 3 个或更多不同操作的工作 + +对于简单的单步任务或纯信息查询类请求，助手不会使用此工具。 + +### `todo_write` 示例 + +创建功能实现计划： + +``` +todo_write(todos=[ + { + "id": "create-model", + "content": "Create user preferences model", + "status": "pending" + }, + { + "id": "add-endpoints", + "content": "Add API endpoints for preferences", + "status": "pending" + }, + { + "id": "implement-ui", + "content": "Implement frontend components", + "status": "pending" + } +]) +``` + +## 重要说明 + +- **自动使用：** AI 助手在复杂任务期间会自动管理 todo 列表。 +- **进度可见性：** 随着工作进展，你会实时看到 todo 列表的更新。 +- **会话隔离：** 每个 coding session 都有自己独立的 todo 列表，不会相互干扰。 \ No newline at end of file diff --git a/website/content/zh/troubleshooting.md b/website/content/zh/troubleshooting.md index 7fe8dd1e..9ffe7a56 100644 --- a/website/content/zh/troubleshooting.md +++ b/website/content/zh/troubleshooting.md @@ -7,13 +7,18 @@ - 调试技巧 - 与你遇到的问题相似的现有 GitHub Issues，或创建新的 Issues -## 认证或登录错误 +## 身份验证或登录错误 - **错误：`Failed to login. Message: Request contains an invalid argument`** - 使用 Google Workspace 账户或与 Gmail 账户关联的 Google Cloud 账户的用户可能无法激活 Google Code Assist 计划的免费额度。 - 对于 Google Cloud 账户，你可以通过设置 `GOOGLE_CLOUD_PROJECT` 为你的项目 ID 来解决这个问题。 - 或者，你可以从 [Google AI Studio](http://aistudio.google.com/app/apikey) 获取 Gemini API key，该服务也包含独立的免费额度。 +- **错误：`UNABLE_TO_GET_ISSUER_CERT_LOCALLY` 或 `unable to get local issuer certificate`** + - **原因：** 你可能处于企业网络环境中，防火墙会拦截并检查 SSL/TLS 流量。这通常需要 Node.js 信任自定义的根 CA 证书。 + - **解决方案：** 将 `NODE_EXTRA_CA_CERTS` 环境变量设置为你的企业根 CA 证书文件的绝对路径。 + - 示例：`export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` + ## 常见问题 (FAQs) - **Q: 如何将 Qwen Code 更新到最新版本？** @@ -34,35 +39,35 @@ - **错误：启动 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`，请确认你的 `npm` 全局二进制目录已加入 `PATH`。你可以使用命令 `npm install -g @qwen-code/qwen-code@latest` 进行更新。 + - 如果你是从源码运行 `qwen`，请确保使用了正确的命令来调用（例如 `node packages/cli/dist/index.js ...`）。要更新的话，请从仓库拉取最新更改，然后使用命令 `npm run build` 重新构建。 - **错误：`MODULE_NOT_FOUND` 或导入错误** - - **原因：** 依赖未正确安装，或项目尚未构建。 + - **原因：** 依赖未正确安装，或者项目尚未构建。 - **解决方案：** 1. 运行 `npm install` 确保所有依赖都已安装。 2. 运行 `npm run build` 编译项目。 - 3. 使用 `npm run start` 验证构建是否成功。 + 3. 使用 `npm run start` 验证构建是否成功完成。 -- **错误：出现 "Operation not permitted"、"Permission denied" 或类似提示** +- **错误：提示 "Operation not permitted"、"Permission denied" 或类似信息** - **原因：** 当启用沙箱时，Qwen Code 可能尝试执行被沙箱配置限制的操作，例如在项目目录或系统临时目录之外进行写入。 - **解决方案：** 请参考 [配置：沙箱](./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 启动交互模式。 + - **解决方案：** 如果 CLI 并不需要使用以 `CI_` 为前缀的变量，可以临时取消设置该变量后再运行命令。例如：`env -u CI_TOKEN qwen` -- **从项目 .env 文件中无法启用 DEBUG 模式** +- **DEBUG 模式无法通过项目 .env 文件启用** - **问题：** 在项目的 `.env` 文件中设置 `DEBUG=true` 并不会启用 CLI 的 debug 模式。 - **原因：** 为了避免影响 CLI 行为，`DEBUG` 和 `DEBUG_MODE` 变量会自动从项目 `.env` 文件中排除。 - - **解决方案：** 使用 `.qwen/.env` 文件代替，或者在 `settings.json` 中配置 `excludedProjectEnvVars` 以减少被排除的变量数量。 + - **解决方案：** 使用 `.qwen/.env` 文件代替，或者在 `settings.json` 中配置 `excludedProjectEnvVars` 设置，减少被排除的变量数量。 ## IDE Companion 无法连接 @@ -79,9 +84,9 @@ - 使用 `--verbose` 参数（如果可用）来获取更详细的输出信息。 - 检查 CLI 日志，通常位于用户特定的配置或缓存目录中。 -- **Core 调试：** - - 查看服务器控制台输出中的错误信息或堆栈跟踪。 - - 如果可以配置，增加日志的详细程度。 +- **核心调试：** + - 检查服务器控制台输出中的错误信息或堆栈跟踪。 + - 如果可以配置，增加日志详细程度。 - 如果需要逐步调试服务端代码，可以使用 Node.js 调试工具（例如 `node --inspect`）。 - **工具问题：** @@ -92,6 +97,6 @@ - **预检检查：** - 提交代码前始终运行 `npm run preflight`。这可以捕获许多与格式化、代码规范和类型错误相关的常见问题。 -## 查找类似问题或创建新 Issue +## 查找类似的 GitHub Issues 或创建新 Issues -如果你遇到的问题未在本 _Troubleshooting guide_ 中提及，建议前往 Qwen Code 的 [GitHub Issue 跟踪页面](https://github.com/QwenLM/qwen-code/issues) 进行搜索。如果找不到与你问题相似的 Issue，欢迎创建一个新的 GitHub Issue，并提供详细描述。我们也欢迎你提交 Pull Request！ \ No newline at end of file +如果你遇到的问题未在本 _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 diff --git a/website/translation-changelog.json b/website/translation-changelog.json index 0a991998..b94e03ef 100644 --- a/website/translation-changelog.json +++ b/website/translation-changelog.json @@ -1,4 +1,97 @@ [ + { + "timestamp": "2025-08-28T13:34:49.676Z", + "commit": "1610c1586e47a867edd12e87d1c64051325648c5", + "sourceLanguage": "en", + "translatedFiles": { + "zh": { + "success": [ + "cli/configuration.md", + "deployment.md", + "ide-integration.md", + "index.md", + "integration-tests.md", + "npm.md", + "tools/file-system.md", + "tools/index.md", + "tools/shell.md", + "tools/todo-write.md", + "troubleshooting.md" + ], + "failed": [] + }, + "de": { + "success": [ + "cli/configuration.md", + "deployment.md", + "ide-integration.md", + "index.md", + "integration-tests.md", + "npm.md", + "tools/file-system.md", + "tools/index.md", + "tools/shell.md", + "tools/todo-write.md", + "troubleshooting.md" + ], + "failed": [] + }, + "fr": { + "success": [ + "cli/configuration.md", + "deployment.md", + "ide-integration.md", + "index.md", + "integration-tests.md", + "npm.md", + "tools/file-system.md", + "tools/index.md", + "tools/shell.md", + "tools/todo-write.md", + "troubleshooting.md" + ], + "failed": [] + }, + "ru": { + "success": [ + "cli/configuration.md", + "deployment.md", + "ide-integration.md", + "index.md", + "integration-tests.md", + "npm.md", + "tools/file-system.md", + "tools/index.md", + "tools/shell.md", + "tools/todo-write.md", + "troubleshooting.md" + ], + "failed": [] + }, + "ja": { + "success": [ + "cli/configuration.md", + "deployment.md", + "ide-integration.md", + "index.md", + "integration-tests.md", + "npm.md", + "tools/file-system.md", + "tools/index.md", + "tools/shell.md", + "tools/todo-write.md", + "troubleshooting.md" + ], + "failed": [] + } + }, + "stats": { + "totalFiles": 11, + "languages": 5, + "successCount": 55, + "failedCount": 0 + } + }, { "timestamp": "2025-08-21T07:05:29.537Z", "commit": "cd5e592b6a874b93f65491ddfe34e45150791fd1", From d5827f69bc0c7d5000e8993dfee37ccaa77f59e7 Mon Sep 17 00:00:00 2001 From: pomelo-nwu Date: Thu, 28 Aug 2025 21:43:03 +0800 Subject: [PATCH 3/3] feat: update _meta.ts --- website/content/de/_meta.ts | 22 ++++++++++++++++++++++ website/content/de/cli/_meta.ts | 10 ++++++++++ website/content/de/core/_meta.ts | 5 +++++ website/content/de/examples/_meta.ts | 3 +++ website/content/de/tools/_meta.ts | 11 +++++++++++ website/content/en/_meta.ts | 22 ++++++++++++++++++++++ website/content/en/cli/_meta.ts | 10 ++++++++++ website/content/en/core/_meta.ts | 5 +++++ website/content/en/examples/_meta.ts | 3 +++ website/content/en/tools/_meta.ts | 11 +++++++++++ website/content/fr/_meta.ts | 22 ++++++++++++++++++++++ website/content/fr/cli/_meta.ts | 10 ++++++++++ website/content/fr/core/_meta.ts | 5 +++++ website/content/fr/examples/_meta.ts | 3 +++ website/content/fr/tools/_meta.ts | 11 +++++++++++ website/content/ja/_meta.ts | 22 ++++++++++++++++++++++ website/content/ja/cli/_meta.ts | 10 ++++++++++ website/content/ja/core/_meta.ts | 5 +++++ website/content/ja/examples/_meta.ts | 3 +++ website/content/ja/tools/_meta.ts | 11 +++++++++++ website/content/ru/_meta.ts | 22 ++++++++++++++++++++++ website/content/ru/cli/_meta.ts | 10 ++++++++++ website/content/ru/core/_meta.ts | 5 +++++ website/content/ru/examples/_meta.ts | 3 +++ website/content/ru/tools/_meta.ts | 11 +++++++++++ website/content/zh/_meta.ts | 1 + website/content/zh/tools/_meta.ts | 1 + 27 files changed, 257 insertions(+) create mode 100644 website/content/de/_meta.ts create mode 100644 website/content/de/cli/_meta.ts create mode 100644 website/content/de/core/_meta.ts create mode 100644 website/content/de/examples/_meta.ts create mode 100644 website/content/de/tools/_meta.ts create mode 100644 website/content/en/_meta.ts create mode 100644 website/content/en/cli/_meta.ts create mode 100644 website/content/en/core/_meta.ts create mode 100644 website/content/en/examples/_meta.ts create mode 100644 website/content/en/tools/_meta.ts create mode 100644 website/content/fr/_meta.ts create mode 100644 website/content/fr/cli/_meta.ts create mode 100644 website/content/fr/core/_meta.ts create mode 100644 website/content/fr/examples/_meta.ts create mode 100644 website/content/fr/tools/_meta.ts create mode 100644 website/content/ja/_meta.ts create mode 100644 website/content/ja/cli/_meta.ts create mode 100644 website/content/ja/core/_meta.ts create mode 100644 website/content/ja/examples/_meta.ts create mode 100644 website/content/ja/tools/_meta.ts create mode 100644 website/content/ru/_meta.ts create mode 100644 website/content/ru/cli/_meta.ts create mode 100644 website/content/ru/core/_meta.ts create mode 100644 website/content/ru/examples/_meta.ts create mode 100644 website/content/ru/tools/_meta.ts diff --git a/website/content/de/_meta.ts b/website/content/de/_meta.ts new file mode 100644 index 00000000..87d26294 --- /dev/null +++ b/website/content/de/_meta.ts @@ -0,0 +1,22 @@ +export default { + index: "Willkommen zur Qwen Code Dokumentation", + deployment: "Ausführung & Bereitstellung", + architecture: "Architektur-Übersicht", + cli: "CLI Nutzungsanleitung", + core: "Kern-Details", + tools: "Tools Sammlung", + checkpointing: "Checkpointing-Funktion", + extension: "Erweiterungs-Entwicklung", + "ide-integration": "IDE Integration", + telemetry: "Observabilität", + examples: "Beispielcode", + npm: "Paket-Management", + "gemini-ignore": "Ignorier-Datei Konfiguration", + "integration-tests": "Integrationstests", + "keyboard-shortcuts": "Tastaturkürzel", + sandbox: "Sandbox-Mechanismus", + "issue-and-pr-automation": "Automatisierte Behandlung", + troubleshooting: "Fehlerbehebung", + "tos-privacy": "Nutzungsbedingungen & Datenschutz", + Uninstall: "Deinstallations-Anleitung", +}; diff --git a/website/content/de/cli/_meta.ts b/website/content/de/cli/_meta.ts new file mode 100644 index 00000000..470f4ea0 --- /dev/null +++ b/website/content/de/cli/_meta.ts @@ -0,0 +1,10 @@ +export default { + index: "CLI Übersicht", + commands: "Befehls-Referenz", + configuration: "Konfigurationsanleitung", + authentication: "Authentifizierungs-Setup", + "openai-auth": "OpenAI Authentifizierung", + "token-caching": "Token Caching", + themes: "Theme-Konfiguration", + tutorials: "Nutzungs-Tutorials", +}; diff --git a/website/content/de/core/_meta.ts b/website/content/de/core/_meta.ts new file mode 100644 index 00000000..d993106d --- /dev/null +++ b/website/content/de/core/_meta.ts @@ -0,0 +1,5 @@ +export default { + index: "Kern-Übersicht", + "tools-api": "Tools API", + memport: "Memory Import Processor", +}; diff --git a/website/content/de/examples/_meta.ts b/website/content/de/examples/_meta.ts new file mode 100644 index 00000000..9e674254 --- /dev/null +++ b/website/content/de/examples/_meta.ts @@ -0,0 +1,3 @@ +export default { + "proxy-script": "Proxy-Script Beispiel", +}; diff --git a/website/content/de/tools/_meta.ts b/website/content/de/tools/_meta.ts new file mode 100644 index 00000000..af79d2bc --- /dev/null +++ b/website/content/de/tools/_meta.ts @@ -0,0 +1,11 @@ +export default { + index: "Tools Übersicht", + "file-system": "Dateisystem-Tools", + "multi-file": "Multi-Datei Lese-Tools", + shell: "Shell Tools", + "web-fetch": "Web Fetch Tools", + "web-search": "Web Such-Tools", + memory: "Memory Tools", + "todo-write": "Todo Write Tool", + "mcp-server": "MCP Server", +}; diff --git a/website/content/en/_meta.ts b/website/content/en/_meta.ts new file mode 100644 index 00000000..14f85af1 --- /dev/null +++ b/website/content/en/_meta.ts @@ -0,0 +1,22 @@ +export default { + index: "Welcome to Qwen Code Documentation", + deployment: "Execution & Deployment", + architecture: "Architecture Overview", + cli: "CLI Usage Guide", + core: "Core Details", + tools: "Tools Collection", + checkpointing: "Checkpointing Feature", + extension: "Extension Development", + "ide-integration": "IDE Integration", + telemetry: "Observability", + examples: "Example Code", + npm: "Package Management", + "gemini-ignore": "Ignore File Configuration", + "integration-tests": "Integration Tests", + "keyboard-shortcuts": "Keyboard Shortcuts", + sandbox: "Sandbox Mechanism", + "issue-and-pr-automation": "Automation Handling", + troubleshooting: "Troubleshooting", + "tos-privacy": "Terms of Service & Privacy", + Uninstall: "Uninstall Guide", +}; diff --git a/website/content/en/cli/_meta.ts b/website/content/en/cli/_meta.ts new file mode 100644 index 00000000..07235edf --- /dev/null +++ b/website/content/en/cli/_meta.ts @@ -0,0 +1,10 @@ +export default { + index: "CLI Overview", + commands: "Command Reference", + configuration: "Configuration Guide", + authentication: "Authentication Setup", + "openai-auth": "OpenAI Authentication", + "token-caching": "Token Caching", + themes: "Theme Configuration", + tutorials: "Usage Tutorials", +}; diff --git a/website/content/en/core/_meta.ts b/website/content/en/core/_meta.ts new file mode 100644 index 00000000..f56d0ebe --- /dev/null +++ b/website/content/en/core/_meta.ts @@ -0,0 +1,5 @@ +export default { + index: "Core Overview", + "tools-api": "Tools API", + memport: "Memory Import Processor", +}; diff --git a/website/content/en/examples/_meta.ts b/website/content/en/examples/_meta.ts new file mode 100644 index 00000000..08fd7168 --- /dev/null +++ b/website/content/en/examples/_meta.ts @@ -0,0 +1,3 @@ +export default { + "proxy-script": "Proxy Script Example", +}; diff --git a/website/content/en/tools/_meta.ts b/website/content/en/tools/_meta.ts new file mode 100644 index 00000000..21a200e2 --- /dev/null +++ b/website/content/en/tools/_meta.ts @@ -0,0 +1,11 @@ +export default { + index: "Tools Overview", + "file-system": "File System Tools", + "multi-file": "Multi-File Read Tools", + shell: "Shell Tools", + "web-fetch": "Web Fetch Tools", + "web-search": "Web Search Tools", + memory: "Memory Tools", + "todo-write": "Todo Write Tool", + "mcp-server": "MCP Server", +}; diff --git a/website/content/fr/_meta.ts b/website/content/fr/_meta.ts new file mode 100644 index 00000000..86f70fb1 --- /dev/null +++ b/website/content/fr/_meta.ts @@ -0,0 +1,22 @@ +export default { + index: "Bienvenue dans la Documentation Qwen Code", + deployment: "Exécution et Déploiement", + architecture: "Vue d'ensemble de l'Architecture", + cli: "Guide d'Utilisation CLI", + core: "Détails du Noyau", + tools: "Collection d'Outils", + checkpointing: "Fonctionnalité de Checkpointing", + extension: "Développement d'Extensions", + "ide-integration": "Intégration IDE", + telemetry: "Observabilité", + examples: "Code d'Exemple", + npm: "Gestion des Packages", + "gemini-ignore": "Configuration des Fichiers à Ignorer", + "integration-tests": "Tests d'Intégration", + "keyboard-shortcuts": "Raccourcis Clavier", + sandbox: "Mécanisme Sandbox", + "issue-and-pr-automation": "Traitement Automatisé", + troubleshooting: "Dépannage", + "tos-privacy": "Conditions d'Utilisation et Confidentialité", + Uninstall: "Guide de Désinstallation", +}; diff --git a/website/content/fr/cli/_meta.ts b/website/content/fr/cli/_meta.ts new file mode 100644 index 00000000..b361e0ac --- /dev/null +++ b/website/content/fr/cli/_meta.ts @@ -0,0 +1,10 @@ +export default { + index: "Vue d'ensemble CLI", + commands: "Référence des Commandes", + configuration: "Guide de Configuration", + authentication: "Configuration d'Authentification", + "openai-auth": "Authentification OpenAI", + "token-caching": "Mise en Cache des Tokens", + themes: "Configuration des Thèmes", + tutorials: "Tutoriels d'Utilisation", +}; diff --git a/website/content/fr/core/_meta.ts b/website/content/fr/core/_meta.ts new file mode 100644 index 00000000..9b78b881 --- /dev/null +++ b/website/content/fr/core/_meta.ts @@ -0,0 +1,5 @@ +export default { + index: "Vue d'ensemble du Noyau", + "tools-api": "API des Outils", + memport: "Processeur d'Import Mémoire", +}; diff --git a/website/content/fr/examples/_meta.ts b/website/content/fr/examples/_meta.ts new file mode 100644 index 00000000..fd9bc489 --- /dev/null +++ b/website/content/fr/examples/_meta.ts @@ -0,0 +1,3 @@ +export default { + "proxy-script": "Exemple de Script Proxy", +}; diff --git a/website/content/fr/tools/_meta.ts b/website/content/fr/tools/_meta.ts new file mode 100644 index 00000000..ee583f6a --- /dev/null +++ b/website/content/fr/tools/_meta.ts @@ -0,0 +1,11 @@ +export default { + index: "Vue d'ensemble des Outils", + "file-system": "Outils du Système de Fichiers", + "multi-file": "Outils de Lecture Multi-Fichiers", + shell: "Outils Shell", + "web-fetch": "Outils Web Fetch", + "web-search": "Outils de Recherche Web", + memory: "Outils Mémoire", + "todo-write": "Outil Todo Write", + "mcp-server": "Serveur MCP", +}; diff --git a/website/content/ja/_meta.ts b/website/content/ja/_meta.ts new file mode 100644 index 00000000..2dbd5fa5 --- /dev/null +++ b/website/content/ja/_meta.ts @@ -0,0 +1,22 @@ +export default { + index: "Qwen Code ドキュメントへようこそ", + deployment: "実行とデプロイ", + architecture: "アーキテクチャ概要", + cli: "CLI 使用ガイド", + core: "コア詳細", + tools: "ツールコレクション", + checkpointing: "チェックポイント機能", + extension: "拡張開発", + "ide-integration": "IDE 統合", + telemetry: "可観測性", + examples: "サンプルコード", + npm: "パッケージ管理", + "gemini-ignore": "無視ファイル設定", + "integration-tests": "統合テスト", + "keyboard-shortcuts": "キーボードショートカット", + sandbox: "サンドボックス機構", + "issue-and-pr-automation": "自動化処理", + troubleshooting: "トラブルシューティング", + "tos-privacy": "利用規約とプライバシー", + Uninstall: "アンインストールガイド", +}; diff --git a/website/content/ja/cli/_meta.ts b/website/content/ja/cli/_meta.ts new file mode 100644 index 00000000..cb57a4fa --- /dev/null +++ b/website/content/ja/cli/_meta.ts @@ -0,0 +1,10 @@ +export default { + index: "CLI 概要", + commands: "コマンドリファレンス", + configuration: "設定ガイド", + authentication: "認証設定", + "openai-auth": "OpenAI 認証", + "token-caching": "トークンキャッシュ", + themes: "テーマ設定", + tutorials: "使用チュートリアル", +}; diff --git a/website/content/ja/core/_meta.ts b/website/content/ja/core/_meta.ts new file mode 100644 index 00000000..d13f8347 --- /dev/null +++ b/website/content/ja/core/_meta.ts @@ -0,0 +1,5 @@ +export default { + index: "コア概要", + "tools-api": "ツール API", + memport: "メモリインポートプロセッサ", +}; diff --git a/website/content/ja/examples/_meta.ts b/website/content/ja/examples/_meta.ts new file mode 100644 index 00000000..2e609208 --- /dev/null +++ b/website/content/ja/examples/_meta.ts @@ -0,0 +1,3 @@ +export default { + "proxy-script": "プロキシスクリプト例", +}; diff --git a/website/content/ja/tools/_meta.ts b/website/content/ja/tools/_meta.ts new file mode 100644 index 00000000..b590257d --- /dev/null +++ b/website/content/ja/tools/_meta.ts @@ -0,0 +1,11 @@ +export default { + index: "ツール概要", + "file-system": "ファイルシステムツール", + "multi-file": "マルチファイル読み取りツール", + shell: "シェルツール", + "web-fetch": "Web フェッチツール", + "web-search": "Web 検索ツール", + memory: "メモリツール", + "todo-write": "Todo 書き込みツール", + "mcp-server": "MCP サーバー", +}; diff --git a/website/content/ru/_meta.ts b/website/content/ru/_meta.ts new file mode 100644 index 00000000..952d8d71 --- /dev/null +++ b/website/content/ru/_meta.ts @@ -0,0 +1,22 @@ +export default { + index: "Добро пожаловать в документацию Qwen Code", + deployment: "Выполнение и Развертывание", + architecture: "Обзор Архитектуры", + cli: "Руководство по использованию CLI", + core: "Основные Детали", + tools: "Коллекция Инструментов", + checkpointing: "Функция Контрольных Точек", + extension: "Разработка Расширений", + "ide-integration": "Интеграция с IDE", + telemetry: "Наблюдаемость", + examples: "Примеры Кода", + npm: "Управление Пакетами", + "gemini-ignore": "Конфигурация Игнорируемых Файлов", + "integration-tests": "Интеграционные Тесты", + "keyboard-shortcuts": "Горячие Клавиши", + sandbox: "Механизм Песочницы", + "issue-and-pr-automation": "Автоматизированная Обработка", + troubleshooting: "Устранение Неполадок", + "tos-privacy": "Условия Использования и Конфиденциальность", + Uninstall: "Руководство по Удалению", +}; diff --git a/website/content/ru/cli/_meta.ts b/website/content/ru/cli/_meta.ts new file mode 100644 index 00000000..e719d676 --- /dev/null +++ b/website/content/ru/cli/_meta.ts @@ -0,0 +1,10 @@ +export default { + index: "Обзор CLI", + commands: "Справочник Команд", + configuration: "Руководство по Конфигурации", + authentication: "Настройка Аутентификации", + "openai-auth": "Аутентификация OpenAI", + "token-caching": "Кэширование Токенов", + themes: "Конфигурация Тем", + tutorials: "Учебные Пособия", +}; diff --git a/website/content/ru/core/_meta.ts b/website/content/ru/core/_meta.ts new file mode 100644 index 00000000..23207531 --- /dev/null +++ b/website/content/ru/core/_meta.ts @@ -0,0 +1,5 @@ +export default { + index: "Обзор Ядра", + "tools-api": "API Инструментов", + memport: "Процессор Импорта Памяти", +}; diff --git a/website/content/ru/examples/_meta.ts b/website/content/ru/examples/_meta.ts new file mode 100644 index 00000000..2d674dc8 --- /dev/null +++ b/website/content/ru/examples/_meta.ts @@ -0,0 +1,3 @@ +export default { + "proxy-script": "Пример Прокси-Скрипта", +}; diff --git a/website/content/ru/tools/_meta.ts b/website/content/ru/tools/_meta.ts new file mode 100644 index 00000000..b8dbaa98 --- /dev/null +++ b/website/content/ru/tools/_meta.ts @@ -0,0 +1,11 @@ +export default { + index: "Обзор Инструментов", + "file-system": "Инструменты Файловой Системы", + "multi-file": "Инструменты Чтения Множественных Файлов", + shell: "Инструменты Shell", + "web-fetch": "Инструменты Web Fetch", + "web-search": "Инструменты Веб-Поиска", + memory: "Инструменты Памяти", + "todo-write": "Инструмент Todo Write", + "mcp-server": "MCP Сервер", +}; diff --git a/website/content/zh/_meta.ts b/website/content/zh/_meta.ts index 4430ba56..5ce62d1d 100644 --- a/website/content/zh/_meta.ts +++ b/website/content/zh/_meta.ts @@ -7,6 +7,7 @@ export default { tools: "工具集合", checkpointing: "检查点功能", extension: "扩展开发", + "ide-integration": "IDE 集成", telemetry: "可观测性", examples: "示例代码", npm: "包管理", diff --git a/website/content/zh/tools/_meta.ts b/website/content/zh/tools/_meta.ts index 3cb5da27..db7f4c17 100644 --- a/website/content/zh/tools/_meta.ts +++ b/website/content/zh/tools/_meta.ts @@ -6,5 +6,6 @@ export default { "web-fetch": "Web 获取工具", "web-search": "Web 搜索工具", memory: "内存工具", + "todo-write": "Todo 写入工具", "mcp-server": "MCP 服务器", };