From f384c97fe6d207dc353e1f12384ab9c0ee95182c Mon Sep 17 00:00:00 2001 From: pomelo-nwu Date: Fri, 12 Sep 2025 17:56:29 +0800 Subject: [PATCH] feat: update docs --- translator/bin/qwen-translator | 16 +- translator/package.json | 2 +- translator/src/cli.ts | 109 ++++-- translator/src/translator.ts | 34 +- website/content/de/Uninstall.md | 8 +- website/content/de/checkpointing.md | 20 +- website/content/de/cli/commands.md | 240 +++++++----- website/content/de/cli/configuration.md | 256 ++++++------ website/content/de/cli/index.md | 15 +- website/content/de/cli/token-caching.md | 6 +- website/content/de/cli/welcome-back.md | 135 +++++++ website/content/de/deployment.md | 34 +- website/content/de/ide-integration.md | 78 ++-- website/content/de/index.md | 23 +- website/content/de/keyboard-shortcuts.md | 54 +-- website/content/de/npm.md | 139 ++++--- website/content/de/subagents.md | 470 +++++++++++++++++++++++ website/content/de/telemetry.md | 87 +++-- website/content/de/tools/file-system.md | 54 +-- website/content/de/tools/mcp-server.md | 145 +++---- website/content/de/tools/memory.md | 14 +- website/content/de/tools/web-fetch.md | 14 +- website/content/de/troubleshooting.md | 37 +- website/content/en/Uninstall.md | 2 +- website/content/en/checkpointing.md | 2 +- website/content/en/cli/commands.md | 99 ++++- website/content/en/cli/configuration.md | 80 ++-- website/content/en/cli/index.md | 1 + website/content/en/cli/token-caching.md | 2 +- website/content/en/cli/welcome-back.md | 133 +++++++ website/content/en/deployment.md | 2 +- website/content/en/ide-integration.md | 46 +-- website/content/en/index.md | 1 + website/content/en/keyboard-shortcuts.md | 8 +- website/content/en/npm.md | 6 +- website/content/en/subagents.md | 469 ++++++++++++++++++++++ website/content/en/telemetry.md | 16 +- website/content/en/tools/file-system.md | 10 +- website/content/en/tools/mcp-server.md | 10 +- website/content/en/tools/memory.md | 2 +- website/content/en/tools/web-fetch.md | 2 +- website/content/en/troubleshooting.md | 12 +- website/content/fr/Uninstall.md | 6 +- website/content/fr/checkpointing.md | 18 +- website/content/fr/cli/commands.md | 268 ++++++++----- website/content/fr/cli/configuration.md | 235 ++++++------ website/content/fr/cli/index.md | 15 +- website/content/fr/cli/token-caching.md | 8 +- website/content/fr/cli/welcome-back.md | 133 +++++++ website/content/fr/deployment.md | 10 +- website/content/fr/ide-integration.md | 76 ++-- website/content/fr/index.md | 7 +- website/content/fr/keyboard-shortcuts.md | 26 +- website/content/fr/npm.md | 93 +++-- website/content/fr/subagents.md | 469 ++++++++++++++++++++++ website/content/fr/telemetry.md | 42 +- website/content/fr/tools/file-system.md | 84 ++-- website/content/fr/tools/mcp-server.md | 144 +++---- website/content/fr/tools/memory.md | 8 +- website/content/fr/tools/web-fetch.md | 12 +- website/content/fr/troubleshooting.md | 37 +- website/content/ja/Uninstall.md | 14 +- website/content/ja/checkpointing.md | 24 +- website/content/ja/cli/commands.md | 239 +++++++----- website/content/ja/cli/configuration.md | 316 ++++++++------- website/content/ja/cli/index.md | 13 +- website/content/ja/cli/token-caching.md | 10 +- website/content/ja/cli/welcome-back.md | 134 +++++++ website/content/ja/deployment.md | 29 +- website/content/ja/ide-integration.md | 98 ++--- website/content/ja/index.md | 27 +- website/content/ja/keyboard-shortcuts.md | 54 +-- website/content/ja/npm.md | 152 ++++---- website/content/ja/subagents.md | 467 ++++++++++++++++++++++ website/content/ja/telemetry.md | 151 ++++---- website/content/ja/tools/file-system.md | 110 +++--- website/content/ja/tools/mcp-server.md | 216 +++++------ website/content/ja/tools/memory.md | 12 +- website/content/ja/tools/web-fetch.md | 24 +- website/content/ja/troubleshooting.md | 53 ++- website/content/ru/Uninstall.md | 4 +- website/content/ru/checkpointing.md | 14 +- website/content/ru/cli/commands.md | 261 ++++++++----- website/content/ru/cli/configuration.md | 295 +++++++------- website/content/ru/cli/index.md | 5 +- website/content/ru/cli/token-caching.md | 12 +- website/content/ru/cli/welcome-back.md | 133 +++++++ website/content/ru/deployment.md | 32 +- website/content/ru/ide-integration.md | 72 ++-- website/content/ru/index.md | 17 +- website/content/ru/keyboard-shortcuts.md | 38 +- website/content/ru/npm.md | 106 ++--- website/content/ru/subagents.md | 469 ++++++++++++++++++++++ website/content/ru/telemetry.md | 51 ++- website/content/ru/tools/file-system.md | 42 +- website/content/ru/tools/mcp-server.md | 130 +++---- website/content/ru/tools/memory.md | 12 +- website/content/ru/tools/web-fetch.md | 6 +- website/content/ru/troubleshooting.md | 45 +-- website/content/zh/Uninstall.md | 8 +- website/content/zh/checkpointing.md | 24 +- website/content/zh/cli/commands.md | 250 +++++++----- website/content/zh/cli/configuration.md | 306 ++++++++------- website/content/zh/cli/index.md | 21 +- website/content/zh/cli/token-caching.md | 8 +- website/content/zh/cli/welcome-back.md | 134 +++++++ website/content/zh/deployment.md | 16 +- website/content/zh/ide-integration.md | 94 ++--- website/content/zh/index.md | 19 +- website/content/zh/keyboard-shortcuts.md | 50 +-- website/content/zh/npm.md | 116 +++--- website/content/zh/subagents.md | 466 ++++++++++++++++++++++ website/content/zh/telemetry.md | 83 ++-- website/content/zh/tools/file-system.md | 70 ++-- website/content/zh/tools/mcp-server.md | 148 ++++--- website/content/zh/tools/memory.md | 10 +- website/content/zh/tools/web-fetch.md | 12 +- website/content/zh/troubleshooting.md | 67 ++-- website/translation-changelog.json | 133 +++++++ 119 files changed, 7366 insertions(+), 3140 deletions(-) create mode 100644 website/content/de/cli/welcome-back.md create mode 100644 website/content/de/subagents.md create mode 100644 website/content/en/cli/welcome-back.md create mode 100644 website/content/en/subagents.md create mode 100644 website/content/fr/cli/welcome-back.md create mode 100644 website/content/fr/subagents.md create mode 100644 website/content/ja/cli/welcome-back.md create mode 100644 website/content/ja/subagents.md create mode 100644 website/content/ru/cli/welcome-back.md create mode 100644 website/content/ru/subagents.md create mode 100644 website/content/zh/cli/welcome-back.md create mode 100644 website/content/zh/subagents.md diff --git a/translator/bin/qwen-translator b/translator/bin/qwen-translator index 42dca483..9992d0af 100755 --- a/translator/bin/qwen-translator +++ b/translator/bin/qwen-translator @@ -2,6 +2,20 @@ const { TranslationCLI } = require("../dist/cli.js"); +// Read version from package.json +function getPackageVersion() { + try { + const path = require("path"); + const fs = require("fs"); + const packageJsonPath = path.join(__dirname, "../package.json"); + const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")); + return packageJson.version; + } catch (error) { + console.warn("Could not read version from package.json, using default"); + return "0.0.1"; + } +} + async function main() { const cli = new TranslationCLI(); const { Command } = require("commander"); @@ -10,7 +24,7 @@ async function main() { program .name("qwen-translator") .description("AI-powered documentation translation tool") - .version("1.0.0"); + .version(getPackageVersion()); // init command program diff --git a/translator/package.json b/translator/package.json index a8cbcd05..1860c71e 100644 --- a/translator/package.json +++ b/translator/package.json @@ -1,6 +1,6 @@ { "name": "@qwen-code/translator", - "version": "0.0.1", + "version": "0.0.2", "description": "A universal documentation translator for any GitHub project. Instantly translate docs with AI and automatically build a Nextra-based documentation site.", "main": "./dist/cli.js", "bin": { diff --git a/translator/src/cli.ts b/translator/src/cli.ts index 993a1c59..2202cbc4 100755 --- a/translator/src/cli.ts +++ b/translator/src/cli.ts @@ -7,6 +7,7 @@ import fs from "fs-extra"; import path from "path"; import { SyncManager } from "./sync"; import { DocumentTranslator } from "./translator"; +import { readFileSync } from "fs"; /** * CLI project configuration interface @@ -43,7 +44,9 @@ class TranslationCLI { */ async initProject(): Promise { console.log(chalk.blue("🚀 Initializing document translation project")); - console.log(chalk.gray("Please provide the following project configuration:\n")); + console.log( + chalk.gray("Please provide the following project configuration:\n") + ); const answers = await inquirer.prompt([ { @@ -62,7 +65,8 @@ class TranslationCLI { validate: (input: string) => { const urlPattern = /^https?:\/\/.+\.git$/; return ( - urlPattern.test(input) || "Please enter a valid Git repository URL (ending with .git)" + urlPattern.test(input) || + "Please enter a valid Git repository URL (ending with .git)" ); }, }, @@ -134,17 +138,31 @@ class TranslationCLI { await this.copyEnvExample(); console.log(chalk.green("\n✅ Project initialization completed!")); - console.log(chalk.yellow(`📝 Project configuration saved to: ${this.projectConfigPath}`)); + console.log( + chalk.yellow( + `📝 Project configuration saved to: ${this.projectConfigPath}` + ) + ); console.log(chalk.blue("\n📋 Next steps:")); console.log(chalk.gray("1. Configure environment variables:")); console.log(chalk.gray(" cp .env.example .env")); console.log(chalk.gray(" # Edit .env file and add your API keys")); console.log(chalk.gray("2. Run commands:")); - console.log(chalk.gray(" qwen-translation sync # Sync source repository docs")); - console.log(chalk.gray(" qwen-translation translate # Translate documents")); - console.log(chalk.gray(" qwen-translation config # View/modify configuration")); - console.log(chalk.gray(" npm install # Install dependencies")); - console.log(chalk.gray(" npm run dev # Start development server")); + console.log( + chalk.gray(" qwen-translation sync # Sync source repository docs") + ); + console.log( + chalk.gray(" qwen-translation translate # Translate documents") + ); + console.log( + chalk.gray(" qwen-translation config # View/modify configuration") + ); + console.log( + chalk.gray(" npm install # Install dependencies") + ); + console.log( + chalk.gray(" npm run dev # Start development server") + ); } /** @@ -195,15 +213,17 @@ class TranslationCLI { console.log(chalk.green("✅ Nextra template copied successfully")); } catch (error: any) { if (error.code === "EEXIST") { - console.log(chalk.yellow("⚠️ Target directory already contains files, skipping copy")); + console.log( + chalk.yellow( + "⚠️ Target directory already contains files, skipping copy" + ) + ); } else { throw new Error(`Failed to copy template: ${error.message}`); } } } - - /** * Update .gitignore file, add translation-related ignore rules */ @@ -241,7 +261,9 @@ class TranslationCLI { console.log(chalk.green("✅ .gitignore file updated successfully")); } else { console.log( - chalk.yellow("⚠️ .gitignore file already contains translation rules, skipping update") + chalk.yellow( + "⚠️ .gitignore file already contains translation rules, skipping update" + ) ); } } catch (error: any) { @@ -265,13 +287,19 @@ class TranslationCLI { await fs.copy(examplePath, targetPath); console.log(chalk.green("✅ .env example file copied successfully")); console.log( - chalk.yellow("💡 Please copy .env.example to .env and add your API keys") + chalk.yellow( + "💡 Please copy .env.example to .env and add your API keys" + ) ); } else { - console.log(chalk.yellow("⚠️ .env example file does not exist, skipping copy")); + console.log( + chalk.yellow("⚠️ .env example file does not exist, skipping copy") + ); } } catch (error: any) { - console.log(chalk.yellow(`⚠️ Failed to copy .env example file: ${error.message}`)); + console.log( + chalk.yellow(`⚠️ Failed to copy .env example file: ${error.message}`) + ); } } @@ -282,7 +310,9 @@ class TranslationCLI { const projectConfig = await this.loadProjectConfig(); if (!projectConfig) { console.error( - chalk.red("❌ Project not initialized, please run 'qwen-translation init' first") + chalk.red( + "❌ Project not initialized, please run 'qwen-translation init' first" + ) ); return; } @@ -302,7 +332,9 @@ class TranslationCLI { const result = await syncManager.syncDocuments(force); if (result.success) { - console.log(chalk.green(`✅ Sync completed! Changed files: ${result.changes}`)); + console.log( + chalk.green(`✅ Sync completed! Changed files: ${result.changes}`) + ); if (result.files.length > 0) { console.log(chalk.blue("\n📄 Changed files:")); @@ -338,7 +370,9 @@ class TranslationCLI { const projectConfig = await this.loadProjectConfig(); if (!projectConfig) { console.error( - chalk.red("❌ Project not initialized, please run 'qwen-translation init' first") + chalk.red( + "❌ Project not initialized, please run 'qwen-translation init' first" + ) ); return; } @@ -350,7 +384,11 @@ class TranslationCLI { ? [options.language] : projectConfig.targetLanguages; - console.log(chalk.blue(`🌍 Starting document translation (${languages.join(", ")})...`)); + console.log( + chalk.blue( + `🌍 Starting document translation (${languages.join(", ")})...` + ) + ); try { for (const lang of languages) { @@ -396,7 +434,9 @@ class TranslationCLI { const projectConfig = await this.loadProjectConfig(); if (!projectConfig) { console.error( - chalk.red("❌ Project not initialized, please run 'qwen-translation init' first") + chalk.red( + "❌ Project not initialized, please run 'qwen-translation init' first" + ) ); return; } @@ -462,7 +502,6 @@ class TranslationCLI { console.log(chalk.green("✅ Project configuration updated successfully")); } - /** * Save project configuration */ @@ -499,7 +538,9 @@ class TranslationCLI { if (!projectConfig) { console.log(chalk.red("❌ Project not initialized")); - console.log(chalk.gray("💡 Run 'qwen-translation init' to initialize project")); + console.log( + chalk.gray("💡 Run 'qwen-translation init' to initialize project") + ); return; } @@ -507,9 +548,13 @@ class TranslationCLI { console.log(chalk.gray(` Project name: ${projectConfig.name}`)); console.log(chalk.gray(` Source repository: ${projectConfig.sourceRepo}`)); console.log(chalk.gray(` Documentation path: ${projectConfig.docsPath}`)); - console.log(chalk.gray(` Source language: ${projectConfig.sourceLanguage}`)); console.log( - chalk.gray(` Target languages: ${projectConfig.targetLanguages.join(", ")}`) + chalk.gray(` Source language: ${projectConfig.sourceLanguage}`) + ); + console.log( + chalk.gray( + ` Target languages: ${projectConfig.targetLanguages.join(", ")}` + ) ); console.log(chalk.gray(` Output directory: ${projectConfig.outputDir}`)); @@ -537,6 +582,20 @@ class TranslationCLI { /** * Main function - Setup CLI commands */ +// Read version from package.json +function getPackageVersion(): string { + try { + // Get the directory where this script is located + const scriptDir = path.dirname(__filename); + const packageJsonPath = path.join(scriptDir, "../package.json"); + const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")); + return packageJson.version; + } catch (error) { + console.warn("Could not read version from package.json, using default"); + return "0.0.1"; + } +} + async function main() { const cli = new TranslationCLI(); const program = new Command(); @@ -544,7 +603,7 @@ async function main() { program .name("qwen-translation") .description("AI-powered document translation tool") - .version("1.0.0"); + .version(getPackageVersion()); // init command program diff --git a/translator/src/translator.ts b/translator/src/translator.ts index 390e3c66..091f711e 100644 --- a/translator/src/translator.ts +++ b/translator/src/translator.ts @@ -26,7 +26,6 @@ interface TranslationChunk extends DocumentSection { index?: number; } - export class DocumentTranslator { private openai: OpenAI; private apiConfig: TranslatorConfig; @@ -40,7 +39,6 @@ export class DocumentTranslator { const envLoader = createEnvLoader(this.projectRoot); envLoader.loadEnv(); - // 获取API配置 const apiConfig = envLoader.getApiConfig(); @@ -96,7 +94,6 @@ export class DocumentTranslator { parsedContent.structure ); - console.log(chalk.green(`✓ Completed ${path.basename(filePath)}`)); return translatedDocument; } catch (error: any) { @@ -113,8 +110,12 @@ export class DocumentTranslator { targetLang: string, index: number ): Promise { - // Skip code blocks and links + // Skip code blocks and links (all code blocks are skipped, including markdown) if (chunk.type === "code" || chunk.type === "link") { + // Add special logging for markdown code blocks + if (chunk.type === "code" && chunk.metadata?.language === "markdown") { + console.log(chalk.gray(` ✓ Skipped markdown code block`)); + } return chunk; } @@ -128,7 +129,10 @@ export class DocumentTranslator { console.log(chalk.cyan(` → Chunk ${index + 1} (${targetLang})`)); const prompt = this.buildTranslationPrompt(chunk.content, targetLang); - const translatedContent = await this.callTranslationAPI(prompt, targetLang); + const translatedContent = await this.callTranslationAPI( + prompt, + targetLang + ); // Cache translation result this.translationCache.set(cacheKey, translatedContent); @@ -148,7 +152,7 @@ export class DocumentTranslator { buildSystemPrompt(targetLang: string): string { const languageNames: Record = { zh: "Chinese", - de: "German", + de: "German", fr: "French", ru: "Russian", ja: "Japanese", @@ -167,7 +171,7 @@ Translate from a programmer's perspective - keep it natural and technically accu - Tool names: Node.js, React, TypeScript, VS Code, etc. - File extensions: .js, .md, .json, .yaml, etc. - Command names: npm, git, curl, etc. -- Code blocks, variable names, function names +- Code blocks, variable names, function names (especially \`\`\`markdown blocks) - URLs, file paths, configuration keys **TRANSLATE NATURALLY:** @@ -196,7 +200,7 @@ Think like a developer reading technical docs - what feels most natural and clea buildTranslationPrompt(content: string, targetLang: string): string { const languageNames: Record = { zh: "Chinese", - de: "German", + de: "German", fr: "French", ru: "Russian", ja: "Japanese", @@ -212,7 +216,11 @@ ${content}`; /** * Call translation API (using OpenAI SDK) with retry mechanism */ - async callTranslationAPI(prompt: string, targetLang: string, retryCount = 0): Promise { + async callTranslationAPI( + prompt: string, + targetLang: string, + retryCount = 0 + ): Promise { const maxRetries = 3; const baseDelay = 1000; // 1 second base delay @@ -236,7 +244,9 @@ ${content}`; if (error.status === 429 && retryCount < maxRetries) { const delay = baseDelay * Math.pow(2, retryCount); // Exponential backoff console.log( - chalk.yellow(` ⏳ Rate limited, retrying in ${delay / 1000}s (${retryCount + 1}/${maxRetries})`) + chalk.yellow( + ` ⏳ Rate limited, retrying in ${delay / 1000}s (${retryCount + 1}/${maxRetries})` + ) ); await new Promise((resolve) => setTimeout(resolve, delay)); return this.callTranslationAPI(prompt, targetLang, retryCount + 1); @@ -336,7 +346,9 @@ ${content}`; await fs.writeFile(targetPath, translatedContent, "utf-8"); console.log(chalk.green(`✓ Saved: ${path.basename(targetPath)}`)); } catch (error: any) { - console.error(chalk.red(`✗ Failed to translate ${file}: ${error.message}`)); + console.error( + chalk.red(`✗ Failed to translate ${file}: ${error.message}`) + ); } } } diff --git a/website/content/de/Uninstall.md b/website/content/de/Uninstall.md index 7125a215..8cc12f35 100644 --- a/website/content/de/Uninstall.md +++ b/website/content/de/Uninstall.md @@ -4,9 +4,9 @@ Die Methode zur Deinstallation hängt davon ab, wie du die CLI ausgeführt hast. ## Methode 1: Verwendung von npx -npx führt Pakete aus einem temporären Cache aus, ohne eine dauerhafte Installation vorzunehmen. Um die CLI zu "deinstallieren", musst du diesen Cache leeren, wodurch gemini-cli und alle anderen Pakete, die zuvor mit npx ausgeführt wurden, entfernt werden. +npx führt Pakete aus einem temporären Cache aus, ohne eine dauerhafte Installation vorzunehmen. Um die CLI zu "deinstallieren", musst du diesen Cache leeren, wodurch qwen-code und alle anderen Pakete, die zuvor mit npx ausgeführt wurden, entfernt werden. -Der npx-Cache ist ein Verzeichnis mit dem Namen `_npx` innerhalb deines Haupt-npm-Cache-Ordners. Du kannst deinen npm-Cache-Pfad finden, indem du `npm config get cache` ausführst. +Der npx-Cache ist ein Verzeichnis namens `_npx` innerhalb deines Haupt-npm-Cache-Ordners. Du kannst deinen npm-Cache-Pfad herausfinden, indem du `npm config get cache` ausführst. **Für macOS / Linux** @@ -35,10 +35,10 @@ Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force ## Methode 2: Verwendung von npm (Globale Installation) -Wenn du die CLI global installiert hast (z. B. `npm install -g @qwen-code/qwen-code`), verwende den Befehl `npm uninstall` mit dem Flag `-g`, um das Paket zu entfernen. +Wenn du die CLI global installiert hast (z. B. `npm install -g @qwen-code/qwen-code`), verwende den Befehl `npm uninstall` mit dem Flag `-g`, um das Package zu entfernen. ```bash npm uninstall -g @qwen-code/qwen-code ``` -Dieser Befehl entfernt das Paket vollständig von deinem System. \ No newline at end of file +Dieser Befehl entfernt das Package vollständig von deinem System. \ No newline at end of file diff --git a/website/content/de/checkpointing.md b/website/content/de/checkpointing.md index 3f3aab03..9b0f9fb7 100644 --- a/website/content/de/checkpointing.md +++ b/website/content/de/checkpointing.md @@ -4,23 +4,23 @@ Qwen Code bietet ein Checkpointing-Feature, das automatisch einen Snapshot des P ## Wie es funktioniert -Wenn du ein Tool freigibst, das das Dateisystem ändert (wie `write_file` oder `replace`), erstellt die CLI automatisch einen "Checkpoint". Dieser Checkpoint enthält: +Wenn du ein Tool freigibst, das das Dateisystem verändert (wie `write_file` oder `edit`), erstellt die CLI automatisch einen "Checkpoint". Dieser Checkpoint enthält: 1. **Ein Git-Snapshot:** Ein Commit wird in einem speziellen, versteckten Git-Repository in deinem Home-Verzeichnis erstellt (`~/.qwen/history/`). Dieser Snapshot erfasst den vollständigen Zustand deiner Projektdateien zu diesem Zeitpunkt. Er greift **nicht** in das Git-Repository deines eigenen Projekts ein. 2. **Konversationsverlauf:** Die gesamte Konversation, die du bis zu diesem Punkt mit dem Agenten geführt hast, wird gespeichert. 3. **Der Tool-Aufruf:** Der spezifische Tool-Aufruf, der ausgeführt werden sollte, wird ebenfalls gespeichert. -Wenn du die Änderung rückgängig machen oder einfach zurückgehen möchtest, kannst du den Befehl `/restore` verwenden. Beim Wiederherstellen eines Checkpoints wird: +Falls du die Änderung rückgängig machen oder einfach zurückgehen möchtest, kannst du den Befehl `/restore` verwenden. Beim Wiederherstellen eines Checkpoints wird Folgendes durchgeführt: -- Der Zustand aller Dateien in deinem Projekt auf den im Snapshot erfassten Zustand zurückgesetzt. -- Der Konversationsverlauf in der CLI wiederhergestellt. -- Der ursprüngliche Tool-Aufruf erneut vorgeschlagen, sodass du ihn erneut ausführen, anpassen oder einfach ignorieren kannst. +- Alle Dateien in deinem Projekt werden auf den Zustand des Snapshots zurückgesetzt. +- Der Konversationsverlauf in der CLI wird wiederhergestellt. +- Der ursprüngliche Tool-Aufruf wird erneut vorgeschlagen, sodass du ihn erneut ausführen, anpassen oder einfach ignorieren kannst. -Alle Checkpoint-Daten, einschließlich des Git-Snapshots und des Konversationsverlaufs, werden lokal auf deinem Rechner gespeichert. Der Git-Snapshot wird im versteckten Repository gespeichert, während der Konversationsverlauf und die Tool-Aufrufe in einer JSON-Datei im temporären Verzeichnis deines Projekts gespeichert werden, normalerweise unter `~/.qwen/tmp//checkpoints`. +Alle Checkpoint-Daten, einschließlich des Git-Snapshots und des Konversationsverlaufs, werden lokal auf deinem Rechner gespeichert. Der Git-Snapshot wird im Shadow-Repository gespeichert, während der Konversationsverlauf und die Tool-Aufrufe in einer JSON-Datei im temporären Verzeichnis deines Projekts gespeichert werden, normalerweise unter `~/.qwen/tmp//checkpoints`. -## Aktivieren des Features +## Aktivieren der Funktion -Das Checkpointing-Feature ist standardmäßig deaktiviert. Um es zu aktivieren, kannst du entweder ein Command-Line Flag verwenden oder deine `settings.json` Datei bearbeiten. +Die Checkpointing-Funktion ist standardmäßig deaktiviert. Um sie zu aktivieren, kannst du entweder ein Command-Line Flag verwenden oder deine `settings.json` Datei bearbeiten. ### Verwendung des Command-Line Flags @@ -56,7 +56,7 @@ Um eine Liste aller gespeicherten Checkpoints für das aktuelle Projekt anzuzeig /restore ``` -Die CLI zeigt dann eine Liste der verfügbaren Checkpoint-Dateien an. Diese Dateinamen setzen sich in der Regel aus einem Zeitstempel, dem Namen der zuvor geänderten Datei sowie dem Namen des Tools zusammen, das ausgeführt werden sollte (z. B. `2025-06-22T10-00-00_000Z-my-file.txt-write_file`). +Die CLI zeigt dann eine Liste der verfügbaren Checkpoint-Dateien an. Diese Dateinamen setzen sich in der Regel aus einem Zeitstempel, dem Namen der geänderten Datei und dem Namen des Tools zusammen, das ausgeführt werden sollte (z. B. `2025-06-22T10-00-00_000Z-my-file.txt-write_file`). ### Einen bestimmten Checkpoint wiederherstellen @@ -72,4 +72,4 @@ Beispiel: /restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file ``` -Nach Ausführung des Befehls werden deine Dateien und der Konversationsverlauf sofort in den Zustand zurückversetzt, in dem sich das Projekt zum Zeitpunkt der Checkpoint-Erstellung befand. Danach wird die ursprüngliche Tool-Eingabeaufforderung erneut angezeigt. \ No newline at end of file +Nach Ausführung des Befehls werden deine Dateien und der Konversationsverlauf sofort auf den Zustand zum Zeitpunkt der Checkpoint-Erstellung zurückgesetzt, und die ursprüngliche Tool-Eingabeaufforderung wird erneut angezeigt. \ No newline at end of file diff --git a/website/content/de/cli/commands.md b/website/content/de/cli/commands.md index 57fcbd77..4251fb5e 100644 --- a/website/content/de/cli/commands.md +++ b/website/content/de/cli/commands.md @@ -1,27 +1,27 @@ # CLI Commands -Qwen Code unterstützt mehrere integrierte Befehle, mit denen du deine Sitzung verwalten, die Oberfläche anpassen und das Verhalten steuern kannst. Diese Befehle beginnen mit einem Schrägstrich (`/`), einem @-Symbol (`@`) oder einem Ausrufezeichen (`!`). +Qwen Code unterstützt mehrere eingebaute Befehle, die dir helfen, deine Session zu verwalten, die Oberfläche anzupassen und das Verhalten zu steuern. Diese Befehle beginnen mit einem Schrägstrich (`/`), einem @-Symbol (`@`) oder einem Ausrufezeichen (`!`). ## Slash commands (`/`) Slash commands bieten Meta-Ebene-Kontrolle über die CLI selbst. -### Built-in Commands +### Integrierte Befehle - **`/bug`** - - **Beschreibung:** Erstelle ein Issue zu Qwen Code. Standardmäßig wird das Issue im GitHub-Repository für Qwen Code erstellt. Der Text, den du nach `/bug` eingibst, wird zum Titel des gemeldeten Bugs. Das Standardverhalten von `/bug` kann über die Einstellung `bugCommand` in deiner `.qwen/settings.json`-Datei angepasst werden. + - **Beschreibung:** Erstelle ein Issue zu Qwen Code. Standardmäßig wird das Issue im GitHub-Repository für Qwen Code erstellt. Der Text, den du nach `/bug` eingibst, wird zum Titel des erstellten Bugs. Das Standardverhalten von `/bug` kann über die Einstellung `bugCommand` in deiner `.qwen/settings.json` angepasst werden. - **`/chat`** - **Beschreibung:** Speichere und setze den Gesprächsverlauf interaktiv fort, um verschiedene Gesprächszweige zu verwalten oder einen früheren Zustand in einer späteren Sitzung wiederherzustellen. - **Unterbefehle:** - **`save`** - - **Beschreibung:** Speichert den aktuellen Gesprächsverlauf. Du musst ein `` hinzufügen, um den Zustand des Gesprächs zu identifizieren. + - **Beschreibung:** Speichert den aktuellen Gesprächsverlauf. Du musst ein `` hinzufügen, um den Zustand zu identifizieren. - **Verwendung:** `/chat save ` - **Details zum Speicherort der Checkpoints:** Die Standardverzeichnisse für gespeicherte Chat-Checkpoints sind: - - Linux/macOS: `~/.config/google-generative-ai/checkpoints/` - - Windows: `C:\Users\\AppData\Roaming\google-generative-ai\checkpoints\` - - Wenn du `/chat list` ausführst, durchsucht die CLI nur diese Verzeichnisse nach verfügbaren Checkpoints. - - **Hinweis:** Diese Checkpoints dienen dem manuellen Speichern und Wiederherstellen von Gesprächszuständen. Informationen zu automatisch erstellten Checkpoints vor Dateiänderungen findest du in der [Checkpointing-Dokumentation](../checkpointing.md). + - Linux/macOS: `~/.config/qwen-code/checkpoints/` + - Windows: `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` + - Wenn du `/chat list` ausführst, scannt die CLI nur diese Verzeichnisse, um verfügbare Checkpoints zu finden. + - **Hinweis:** Diese Checkpoints dienen dem manuellen Speichern und Wiederherstellen von Gesprächszuständen. Für automatisch erstellte Checkpoints vor Dateiänderungen, siehe [Checkpointing-Dokumentation](../checkpointing.md). - **`resume`** - **Beschreibung:** Setzt ein Gespräch von einem früheren Speicherstand fort. - **Verwendung:** `/chat resume ` @@ -32,33 +32,33 @@ Slash commands bieten Meta-Ebene-Kontrolle über die CLI selbst. - **Verwendung:** `/chat delete ` - **`/clear`** - - **Beschreibung:** Löscht den Terminalbildschirm, einschließlich des sichtbaren Sitzungsverlaufs und des Scrollbacks innerhalb der CLI. Je nach Implementierung können die zugrunde liegenden Sitzungsdaten (für den Verlauf) erhalten bleiben, aber die visuelle Anzeige wird gelöscht. - - **Tastenkürzel:** Drücke jederzeit **Strg+L**, um den Bildschirm zu löschen. + - **Beschreibung:** Leert den Terminalbildschirm, einschließlich des sichtbaren Sitzungsverlaufs und des Scrollbacks innerhalb der CLI. Je nach Implementierung können die zugrunde liegenden Sitzungsdaten (für den Verlauf) erhalten bleiben, aber die Anzeige wird geleert. + - **Tastenkürzel:** Drücke jederzeit **Strg+L**, um den Bildschirm zu leeren. + +- **`/summary`** + - **Beschreibung:** Generiert eine umfassende Projektzusammenfassung aus dem aktuellen Gesprächsverlauf und speichert sie in `.qwen/PROJECT_SUMMARY.md`. Diese Zusammenfassung enthält das Gesamtziel, wichtige Erkenntnisse, kürzliche Aktionen und den aktuellen Plan – ideal, um die Arbeit in zukünftigen Sitzungen fortzusetzen. + - **Verwendung:** `/summary` + - **Funktionen:** + - Analysiert den gesamten Gesprächsverlauf, um wichtigen Kontext zu extrahieren + - Erstellt eine strukturierte Markdown-Zusammenfassung mit Abschnitten zu Zielen, Wissen, Aktionen und Plänen + - Speichert automatisch in `.qwen/PROJECT_SUMMARY.md` im Projektstammverzeichnis + - Zeigt Fortschrittsanzeige während der Generierung und beim Speichern + - Integriert sich mit der "Welcome Back"-Funktion für nahtlose Sitzungswiederherstellung + - **Hinweis:** Dieser Befehl erfordert ein aktives Gespräch mit mindestens 2 Nachrichten, um eine aussagekräftige Zusammenfassung zu generieren. - **`/compress`** - - **Beschreibung:** Ersetzt den gesamten Chat-Kontext durch eine Zusammenfassung. Dadurch werden Tokens für zukünftige Aufgaben gespart, während eine allgemeine Übersicht über den bisherigen Verlauf erhalten bleibt. + - **Beschreibung:** Ersetzt den gesamten Chat-Kontext durch eine Zusammenfassung. Dadurch werden Tokens für zukünftige Aufgaben gespart, während eine grobe Übersicht über den bisherigen Verlauf erhalten bleibt. - **`/copy`** - **Beschreibung:** Kopiert die letzte Ausgabe von Qwen Code in die Zwischenablage, um sie einfach zu teilen oder weiterzuverwenden. - **`/directory`** (oder **`/dir`**) - - **Beschreibung:** Verwalte Workspace-Verzeichnisse für die Unterstützung mehrerer Verzeichnisse. - - **Unterbefehle:** - - **`add`**: - - **Beschreibung:** Fügt ein Verzeichnis zum Workspace hinzu. Der Pfad kann absolut oder relativ zum aktuellen Arbeitsverzeichnis sein. Außerdem wird die Referenzierung vom Home-Verzeichnis aus unterstützt. - - **Verwendung:** `/directory add ,` - - **Hinweis:** In eingeschränkten Sandbox-Profilen deaktiviert. Falls du ein solches Profil verwendest, nutze stattdessen `--include-directories` beim Starten der Sitzung. - - **`show`**: - - **Beschreibung:** Zeigt alle Verzeichnisse an, die mit `/directory add` oder `--include-directories` hinzugefügt wurden. - - **Verwendung:** `/directory show` - -- **`/directory`** (oder **`/dir`**) - - **Beschreibung:** Verwalte Workspace-Verzeichnisse für die Unterstützung mehrerer Verzeichnisse. + - **Beschreibung:** Verwalte Workspace-Verzeichnisse für Multi-Directory-Unterstützung. - **Unterbefehle:** - **`add`**: - - **Beschreibung:** Fügt ein Verzeichnis zum Workspace hinzu. Der Pfad kann absolut oder relativ zum aktuellen Arbeitsverzeichnis sein. Außerdem wird die Referenzierung vom Home-Verzeichnis aus unterstützt. - - **Verwendung:** `/directory add ,` - - **Hinweis:** In eingeschränkten Sandbox-Profilen deaktiviert. Falls du ein solches Profil verwendest, nutze stattdessen `--include-directories` beim Starten der Sitzung. + - **Beschreibung:** Fügt ein Verzeichnis zum Workspace hinzu. Der Pfad kann absolut oder relativ zum aktuellen Arbeitsverzeichnis sein. Auch Referenzen vom Home-Verzeichnis aus werden unterstützt. + - **Verwendung:** `/directory add ,` + - **Hinweis:** Deaktiviert in restriktiven Sandbox-Profilen. Wenn du diese verwendest, nutze stattdessen `--include-directories` beim Starten der Sitzung. - **`show`**: - **Beschreibung:** Zeigt alle Verzeichnisse an, die mit `/directory add` oder `--include-directories` hinzugefügt wurden. - **Verwendung:** `/directory show` @@ -78,34 +78,34 @@ Slash commands bieten Meta-Ebene-Kontrolle über die CLI selbst. - **`desc`** oder **`descriptions`**: - **Beschreibung:** Zeigt detaillierte Beschreibungen der MCP-Server und Tools an. - **`nodesc`** oder **`nodescriptions`**: - - **Beschreibung:** Blendet Tool-Beschreibungen aus und zeigt nur die Tool-Namen an. + - **Beschreibung:** Versteckt Tool-Beschreibungen und zeigt nur die Tool-Namen an. - **`schema`**: - **Beschreibung:** Zeigt das vollständige JSON-Schema für die konfigurierten Parameter des Tools an. - - **Tastenkürzel:** Drücke jederzeit **Strg+T**, um zwischen dem Anzeigen und Ausblenden von Tool-Beschreibungen zu wechseln. + - **Tastenkürzel:** Drücke jederzeit **Strg+T**, um zwischen Anzeige und Ausblenden der Tool-Beschreibungen zu wechseln. - **`/memory`** - - **Beschreibung:** Verwalte den instruktiven Kontext der KI (standardmäßig aus `QWEN.md`-Dateien geladener hierarchischer Speicher; konfigurierbar über `contextFileName`). + - **Beschreibung:** Verwalte den instruktiven Kontext der KI (standardmäßig aus `QWEN.md` geladene hierarchische Speicherstruktur; konfigurierbar über `contextFileName`). - **Unterbefehle:** - **`add`**: - **Beschreibung:** Fügt den folgenden Text dem Speicher der KI hinzu. Verwendung: `/memory add ` - **`show`**: - - **Beschreibung:** Zeigt den vollständigen, zusammengeführten Inhalt des aktuellen hierarchischen Speichers an, der aus allen Kontextdateien (z. B. `QWEN.md`) geladen wurde. So kannst du den instruktiven Kontext überprüfen, der dem Modell zur Verfügung steht. + - **Beschreibung:** Zeigt den vollständigen, zusammengeführten Inhalt des aktuellen hierarchischen Speichers an, der aus allen Kontextdateien (z. B. `QWEN.md`) geladen wurde. So kannst du den instruktiven Kontext einsehen, der dem Modell zur Verfügung gestellt wird. - **`refresh`**: - - **Beschreibung:** Lädt den hierarchischen instruktiven Speicher aus allen Kontextdateien (Standard: `QWEN.md`) neu, die in den konfigurierten Orten (global, Projekt-/Vorgängerordner und Unterverzeichnisse) gefunden wurden. Dadurch wird das Modell mit dem neuesten Kontext aktualisiert. - - **Hinweis:** Weitere Informationen dazu, wie Kontextdateien zum hierarchischen Speicher beitragen, findest du in der [CLI-Konfigurationsdokumentation](./configuration.md#context-files-hierarchical-instructional-context). + - **Beschreibung:** Lädt den hierarchischen instruktiven Speicher aus allen Kontextdateien (Standard: `QWEN.md`) neu, die in den konfigurierten Orten (global, Projekt-/Vorgängerordner und Unterverzeichnisse) gefunden werden. Dadurch wird das Modell mit dem neuesten Kontext aktualisiert. + - **Hinweis:** Weitere Informationen zur Funktionsweise von Kontextdateien im hierarchischen Speicher findest du in der [CLI-Konfigurationsdokumentation](./configuration.md#context-files-hierarchical-instructional-context). - **`/restore`** - - **Beschreibung:** Stellt die Projektdateien auf den Zustand vor der Ausführung eines Tools wieder her. Dies ist besonders nützlich, um Dateiänderungen rückgängig zu machen, die von einem Tool vorgenommen wurden. Wird der Befehl ohne eine Tool-Aufruf-ID ausgeführt, werden verfügbare Checkpoints zur Wiederherstellung aufgelistet. + - **Beschreibung:** Stellt die Projektdateien in den Zustand vor der Ausführung eines Tools wieder her. Besonders nützlich, um Dateiänderungen eines Tools rückgängig zu machen. Ohne Angabe einer `tool_call_id` werden verfügbare Checkpoints zur Wiederherstellung aufgelistet. - **Verwendung:** `/restore [tool_call_id]` - - **Hinweis:** Nur verfügbar, wenn die CLI mit der Option `--checkpointing` aufgerufen wurde oder über [Einstellungen](./configuration.md) konfiguriert ist. Weitere Informationen findest du in der [Checkpointing-Dokumentation](../checkpointing.md). + - **Hinweis:** Nur verfügbar, wenn die CLI mit der Option `--checkpointing` gestartet wurde oder über [Einstellungen](./configuration.md) konfiguriert ist. Siehe [Checkpointing-Dokumentation](../checkpointing.md) für weitere Details. - **`/settings`** - **Beschreibung:** Öffnet den Einstellungseditor, um Qwen Code-Einstellungen anzuzeigen und zu ändern. - - **Details:** Dieser Befehl bietet eine benutzerfreundliche Oberfläche zum Ändern von Einstellungen, die das Verhalten und Aussehen von Qwen Code steuern. Er entspricht dem manuellen Bearbeiten der `.qwen/settings.json`-Datei, bietet aber Validierung und Anleitung, um Fehler zu vermeiden. - - **Verwendung:** Führe einfach `/settings` aus, und der Editor öffnet sich. Du kannst dann nach bestimmten Einstellungen suchen, ihre aktuellen Werte anzeigen und sie nach Belieben ändern. Änderungen an einigen Einstellungen werden sofort übernommen, andere erfordern einen Neustart. + - **Details:** Dieser Befehl bietet eine benutzerfreundliche Oberfläche zum Ändern von Einstellungen, die das Verhalten und Aussehen von Qwen Code steuern. Er entspricht dem manuellen Bearbeiten der Datei `.qwen/settings.json`, bietet aber Validierung und Hilfestellung zur Fehlervermeidung. + - **Verwendung:** Führe einfach `/settings` aus, und der Editor öffnet sich. Du kannst dann nach Einstellungen suchen, ihre aktuellen Werte anzeigen und sie nach Belieben ändern. Einige Änderungen werden sofort übernommen, andere erfordern einen Neustart. - **`/stats`** - - **Beschreibung:** Zeigt detaillierte Statistiken zur aktuellen Qwen Code-Sitzung an, darunter Token-Nutzung, eingesparte gecachte Tokens (falls verfügbar) und Sitzungsdauer. Hinweis: Informationen zu gecachten Tokens werden nur angezeigt, wenn diese tatsächlich verwendet werden – dies geschieht derzeit nur bei Authentifizierung mit API-Schlüssel, nicht jedoch bei OAuth. + - **Beschreibung:** Zeigt detaillierte Statistiken zur aktuellen Qwen Code-Sitzung an, darunter Token-Nutzung, eingesparte gecachte Tokens (falls verfügbar) und Sitzungsdauer. Hinweis: Informationen zu gecachten Tokens werden nur angezeigt, wenn diese tatsächlich verwendet werden – dies geschieht derzeit nur bei Authentifizierung per API-Schlüssel, nicht bei OAuth. - [**`/theme`**](./themes.md) - **Beschreibung:** Öffnet einen Dialog, in dem du das visuelle Theme von Qwen Code ändern kannst. @@ -114,41 +114,65 @@ Slash commands bieten Meta-Ebene-Kontrolle über die CLI selbst. - **Beschreibung:** Öffnet einen Dialog, in dem du die Authentifizierungsmethode ändern kannst. - **`/about`** - - **Beschreibung:** Zeigt Versionsinformationen an. Bitte teile diese Informationen mit, wenn du ein Issue meldest. + - **Beschreibung:** Zeigt Versionsinformationen an. Bitte teile diese Informationen mit, wenn du ein Issue erstellst. + +- **`/agents`** + - **Beschreibung:** Verwalte spezialisierte KI-Subagents für fokussierte Aufgaben. Subagents sind unabhängige KI-Assistenten mit spezifischer Expertise und Tool-Zugriff. + - **Unterbefehle:** + - **`create`**: + - **Beschreibung:** Startet einen interaktiven Assistenten zum Erstellen eines neuen Subagents. Der Assistent führt dich durch die Auswahl des Speicherorts, KI-gestützte Prompt-Generierung, Tool-Auswahl und visuelle Anpassung. + - **Verwendung:** `/agents create` + - **`manage`**: + - **Beschreibung:** Öffnet einen interaktiven Verwaltungsdialog zum Anzeigen, Bearbeiten und Löschen bestehender Subagents. Zeigt sowohl Projekt- als auch benutzerdefinierte Agents an. + - **Verwendung:** `/agents manage` + - **Speicherorte:** + - **Projekt-Ebene:** `.qwen/agents/` (geteilt mit dem Team, hat Vorrang) + - **Benutzer-Ebene:** `~/.qwen/agents/` (persönliche Agents, projektübergreifend verfügbar) + - **Hinweis:** Weitere Informationen zum Erstellen und Verwalten von Subagents findest du in der [Subagents-Dokumentation](../subagents.md). - [**`/tools`**](../tools/index.md) - **Beschreibung:** Zeigt eine Liste der aktuell in Qwen Code verfügbaren Tools an. - **Unterbefehle:** - **`desc`** oder **`descriptions`**: - - **Beschreibung:** Zeigt detaillierte Beschreibungen jedes Tools an, einschließlich des Namens und der vollständigen Beschreibung, wie sie dem Modell bereitgestellt wird. + - **Beschreibung:** Zeigt detaillierte Beschreibungen jedes Tools an, einschließlich Name und vollständiger Beschreibung, wie sie dem Modell zur Verfügung gestellt wird. - **`nodesc`** oder **`nodescriptions`**: - - **Beschreibung:** Blendet Tool-Beschreibungen aus und zeigt nur die Tool-Namen an. + - **Beschreibung:** Versteckt Tool-Beschreibungen und zeigt nur die Tool-Namen an. - **`/privacy`** - - **Beschreibung:** Zeigt den Datenschutzhinweis an und ermöglicht es Benutzern, auszuwählen, ob sie der Erfassung ihrer Daten zur Verbesserung des Dienstes zustimmen. + - **Beschreibung:** Zeigt den Datenschutzhinweis an und ermöglicht es Nutzern, auszuwählen, ob sie der Datenerhebung zur Verbesserung des Dienstes zustimmen. + +- **`/quit-confirm`** + - **Beschreibung:** Zeigt einen Bestätigungsdialog vor dem Beenden von Qwen Code an, in dem du auswählen kannst, wie mit der aktuellen Sitzung umgegangen werden soll. + - **Verwendung:** `/quit-confirm` + - **Funktionen:** + - **Sofort beenden:** Beendet ohne Speichern (entspricht `/quit`) + - **Zusammenfassung generieren und beenden:** Erstellt eine Projektzusammenfassung mit `/summary` vor dem Beenden + - **Gespräch speichern und beenden:** Speichert das aktuelle Gespräch mit einem automatisch generierten Tag vor dem Beenden + - **Tastenkürzel:** Drücke **Strg+C** zweimal, um den Beendigungsdialog zu öffnen + - **Hinweis:** Dieser Befehl wird automatisch ausgelöst, wenn du einmal Strg+C drückst, um versehentliches Beenden zu verhindern. - **`/quit`** (oder **`/exit`**) - - **Beschreibung:** Beendet Qwen Code. + - **Beschreibung:** Beendet Qwen Code sofort ohne Bestätigungsdialog. - **`/vim`** - - **Beschreibung:** Schaltet den Vim-Modus ein oder aus. Wenn der Vim-Modus aktiviert ist, unterstützt der Eingabebereich vim-ähnliche Navigations- und Bearbeitungsbefehle sowohl im NORMAL- als auch im INSERT-Modus. + - **Beschreibung:** Schaltet den Vim-Modus ein oder aus. Im Vim-Modus unterstützt der Eingabebereich vim-ähnliche Navigations- und Bearbeitungsbefehle in den Modi NORMAL und INSERT. - **Funktionen:** - - **NORMAL-Modus:** Navigation mit `h`, `j`, `k`, `l`; Wortweise Springen mit `w`, `b`, `e`; zum Zeilenanfang/-ende mit `0`, `$`, `^`; zu bestimmten Zeilen mit `G` (oder `gg` für die erste Zeile) - - **INSERT-Modus:** Standard-Texteingabe mit Escape zum Zurückkehren in den NORMAL-Modus + - **NORMAL-Modus:** Navigation mit `h`, `j`, `k`, `l`; Wortwechsel mit `w`, `b`, `e`; Zeilenanfang/-ende mit `0`, `$`, `^`; gehe zu bestimmten Zeilen mit `G` (oder `gg` für erste Zeile) + - **INSERT-Modus:** Standard-Texteingabe mit Escape zum Wechsel zurück in den NORMAL-Modus - **Bearbeitungsbefehle:** Löschen mit `x`, Ändern mit `c`, Einfügen mit `i`, `a`, `o`, `O`; komplexe Operationen wie `dd`, `cc`, `dw`, `cw` - **Zählerunterstützung:** Befehle mit Zahlen als Präfix (z. B. `3h`, `5w`, `10G`) - - **Letzten Befehl wiederholen:** Mit `.` wird die letzte Bearbeitungsoperation wiederholt + - **Letzten Befehl wiederholen:** Nutze `.` zur Wiederholung der letzten Bearbeitung - **Persistente Einstellung:** Die Vim-Modus-Einstellung wird in `~/.qwen/settings.json` gespeichert und zwischen Sitzungen wiederhergestellt - - **Statusanzeige:** Wenn aktiviert, wird `[NORMAL]` oder `[INSERT]` in der Fußzeile angezeigt + - **Statusanzeige:** Wenn aktiviert, zeigt `[NORMAL]` oder `[INSERT]` in der Fußzeile an - **`/init`** - - **Beschreibung:** Analysiert das aktuelle Verzeichnis und erstellt standardmäßig eine `QWEN.md`-Kontextdatei (oder den durch `contextFileName` festgelegten Dateinamen). Falls bereits eine nicht-leere Datei existiert, werden keine Änderungen vorgenommen. Der Befehl erstellt eine leere Datei und fordert das Modell auf, sie mit projektspezifischen Anweisungen zu füllen. + - **Beschreibung:** Analysiert das aktuelle Verzeichnis und erstellt standardmäßig eine `QWEN.md`-Kontextdatei (oder den durch `contextFileName` festgelegten Dateinamen). Falls bereits eine nicht-leere Datei existiert, werden keine Änderungen vorgenommen. Der Befehl legt eine leere Datei an und fordert das Modell auf, sie mit projektspezifischen Anweisungen zu füllen. -### Benutzerdefinierte Befehle +### Custom Commands Für einen schnellen Einstieg siehe das [Beispiel](#example-a-pure-function-refactoring-command) unten. -Benutzerdefinierte Befehle ermöglichen es dir, deine favorisierten oder am häufigsten verwendeten Prompts als persönliche Shortcuts innerhalb von Qwen Code zu speichern und wiederzuverwenden. Du kannst Befehle erstellen, die spezifisch für ein einzelnes Projekt sind, oder Befehle, die global in allen deinen Projekten verfügbar sind – so wird dein Workflow optimiert und die Konsistenz gewährleistet. +Custom Commands ermöglichen es dir, deine favorisierten oder am häufigsten verwendeten Prompts als persönliche Shortcuts innerhalb von Qwen Code zu speichern und wiederzuverwenden. Du kannst Commands erstellen, die spezifisch für ein einzelnes Projekt sind, oder Commands, die global in allen deinen Projekten verfügbar sind – so wird dein Workflow optimiert und Konsistenz gewährleistet. #### Dateispeicherorte & Priorität @@ -172,43 +196,71 @@ Deine Befehlsdefinitionsdateien müssen im TOML-Format geschrieben und mit der D ##### Erforderliche Felder -- `prompt` (String): Der Prompt, der beim Ausführen des Befehls an das Modell gesendet wird. Dies kann ein einzeiliger oder mehrzeiliger String sein. +- `prompt` (String): Die Eingabeaufforderung, die beim Ausführen des Befehls an das Modell gesendet wird. Dies kann ein einzeiliger oder mehrzeiliger String sein. ##### Optionale Felder -- `description` (String): Eine kurze, einzeilige Beschreibung dessen, was der Befehl bewirkt. Dieser Text wird neben deinem Befehl im `/help`-Menü angezeigt. **Falls du dieses Feld auslässt, wird automatisch eine generische Beschreibung aus dem Dateinamen erzeugt.** +- `description` (String): Eine kurze, einzeilige Beschreibung dessen, was der Befehl bewirkt. Dieser Text wird neben deinem Befehl im `/help`-Menü angezeigt. **Wenn du dieses Feld weglässt, wird automatisch eine allgemeine Beschreibung aus dem Dateinamen generiert.** #### Umgang mit Argumenten -Benutzerdefinierte Befehle unterstützen zwei leistungsstarke und einfach zu verwendende Methoden für den Umgang mit Argumenten. Die CLI wählt automatisch die richtige Methode basierend auf dem Inhalt des `prompt` deines Befehls aus. +Benutzerdefinierte Befehle unterstützen zwei leistungsstarke Methoden zur Verarbeitung von Argumenten. Die CLI wählt automatisch die richtige Methode basierend auf dem Inhalt des `prompt` deines Befehls aus. -##### 1. Kurzform-Injektion mit `{{args}}` +##### 1. Kontextabhängige Injektion mit `{{args}}` -Wenn dein `prompt` den speziellen Platzhalter `{{args}}` enthält, ersetzt die CLI diesen genauen Platzhalter durch den gesamten Text, den der Benutzer nach dem Befehlsnamen eingegeben hat. Dies ist ideal für einfache, deterministische Befehle, bei denen du die Benutzereingabe an einer bestimmten Stelle in eine größere Prompt-Vorlage einfügen musst. +Wenn dein `prompt` den speziellen Platzhalter `{{args}}` enthält, ersetzt die CLI diesen Platzhalter durch den Text, den der Benutzer nach dem Befehlsnamen eingegeben hat. + +Das Verhalten dieser Injektion hängt davon ab, wo sie verwendet wird: + +**A. Raw Injection (Außerhalb von Shell-Befehlen)** + +Wenn sie im Hauptteil des Prompts verwendet wird, werden die Argumente exakt so injiziert, wie der Benutzer sie eingegeben hat. **Beispiel (`git/fix.toml`):** ```toml -# In: ~/.qwen/commands/git/fix.toml - ```markdown -# Aufgerufen via: /git:fix "Button ist auf Mobilgeräten falsch ausgerichtet" +# Aufgerufen via: /git:fix "Button is misaligned" -description = "Erzeugt einen Fix für ein gegebenes GitHub-Issue." -prompt = "Bitte analysiere die gestageten Git-Änderungen und stelle einen Code-Fix für das hier beschriebene Problem bereit: {{args}}." +description = "Generiert einen Fix für ein gegebenes Problem." +prompt = "Bitte stelle einen Code-Fix für das hier beschriebene Problem bereit: {{args}}." ``` -Das Modell erhält den finalen Prompt: `Bitte analysiere die gestageten Git-Änderungen und stelle einen Code-Fix für das hier beschriebene Problem bereit: "Button ist auf Mobilgeräten falsch ausgerichtet".` +Das Modell erhält: `Bitte stelle einen Code-Fix für das hier beschriebene Problem bereit: "Button is misaligned".` + +**B. Verwendung von Argumenten in Shell-Befehlen (Innerhalb von `!{...}`-Blöcken)** + +Wenn du `{{args}}` innerhalb eines Shell-Injection-Blocks (`!{...}`) verwendest, werden die Argumente automatisch **shell-escaped** vor der Ersetzung. Dadurch kannst du Argumente sicher an Shell-Befehle übergeben, wodurch sichergestellt ist, dass der resultierende Befehl syntaktisch korrekt und sicher ist und Command-Injection-Schwachstellen verhindert werden. + +**Beispiel (`/grep-code.toml`):** + +```toml +prompt = """ +Bitte fasse die Ergebnisse für das Muster `{{args}}` zusammen. + +Suchergebnisse: +!{grep -r {{args}} .} +""" ``` -##### 2. Standardargument-Verarbeitung +Wenn du `/grep-code It's complicated` ausführst: -Falls dein `prompt` den speziellen Platzhalter `{{args}}` **nicht** enthält, verwendet die CLI ein Standardverhalten zur Verarbeitung von Argumenten. +1. Die CLI erkennt, dass `{{args}}` sowohl außerhalb als auch innerhalb von `!{...}` verwendet wird. +2. Außerhalb: Das erste `{{args}}` wird roh durch `It's complicated` ersetzt. +3. Innerhalb: Das zweite `{{args}}` wird durch die escaped-Version ersetzt (z. B. unter Linux: `"It's complicated"`). +4. Der ausgeführte Befehl lautet `grep -r "It's complicated" .`. +5. Die CLI fordert dich auf, diesen exakten, sicheren Befehl vor der Ausführung zu bestätigen. +6. Der finale Prompt wird gesendet. +``` + +##### 2. Standardargument-Handling + +Falls dein `prompt` den speziellen Platzhalter `{{args}}` **nicht** enthält, verwendet die CLI ein Standardverhalten für die Argumentverarbeitung. Wenn du der Kommandozeile Argumente übergibst (z. B. `/mycommand arg1`), wird die CLI den vollständigen Befehl, den du eingegeben hast, am Ende des Prompts anfügen, getrennt durch zwei Zeilenumbrüche. Dadurch kann das Modell sowohl die ursprünglichen Anweisungen als auch die spezifischen Argumente sehen, die du gerade übergeben hast. -Falls du **keine** Argumente übergibst (z. B. `/mycommand`), wird der Prompt exakt so, wie er ist, an das Modell gesendet – ohne etwas anzuhängen. +Falls du **keine** Argumente übergibst (z. B. `/mycommand`), wird der Prompt exakt so an das Modell gesendet, wie er ist – ohne etwas anzuhängen. **Beispiel (`changelog.toml`):** @@ -218,16 +270,16 @@ Dieses Beispiel zeigt, wie du einen robusten Befehl erstellst, indem du eine Rol # In: /.qwen/commands/changelog.toml -# Aufgerufen via: /changelog 1.2.0 added "Support for default argument parsing." +# Aufgerufen über: /changelog 1.2.0 added "Support for default argument parsing." description = "Fügt einen neuen Eintrag zur CHANGELOG.md-Datei des Projekts hinzu." prompt = """ # Aufgabe: Changelog aktualisieren -Du bist ein erfahrener Maintainer dieses Softwareprojekts. Ein Benutzer hat einen Befehl aufgerufen, um einen neuen Eintrag zum Changelog hinzuzufügen. +Du bist ein erfahrener Maintainer dieses Softwareprojekts. Ein Benutzer hat einen Befehl ausgeführt, um einen neuen Eintrag zum Changelog hinzuzufügen. -**Der rohe Befehl des Benutzers wird unterhalb deiner Anweisungen angehängt.** +**Der rohe Befehl des Benutzers steht unterhalb deiner Anweisungen.** Deine Aufgabe ist es, ``, `` und `` aus der Eingabe zu parsen und das `write_file`-Tool zu verwenden, um die `CHANGELOG.md`-Datei korrekt zu aktualisieren. @@ -235,6 +287,7 @@ Deine Aufgabe ist es, ``, `` und `` aus der Einga Der Befehl folgt diesem Format: `/changelog ` - `` muss einer der folgenden Werte sein: "added", "changed", "fixed", "removed"." +```markdown ## Verhalten 1. Lies die Datei `CHANGELOG.md`. 2. Finde den Abschnitt für die angegebene ``. @@ -242,30 +295,27 @@ Der Befehl folgt diesem Format: `/changelog ` 4. Falls die Version oder der Typ-Abschnitt nicht existiert, lege ihn an. 5. Halte dich strikt an das "Keep a Changelog"-Format. """ -``` Wenn du `/changelog 1.2.0 added "New feature"` ausführst, wird der finale Text, der an das Modell gesendet wird, der ursprüngliche Prompt gefolgt von zwei Zeilenumbrüchen und dem von dir eingegebenen Befehl sein. +``` ##### 3. Shell-Befehle mit `!{...}` ausführen -Du kannst deine Befehle dynamisch gestalten, indem du Shell-Befehle direkt innerhalb deines `prompt` ausführst und deren Ausgabe einfügst. Das ist ideal, um Kontext aus deiner lokalen Umgebung zu sammeln, wie z. B. den Inhalt einer Datei zu lesen oder den Status eines Git-Repositories abzufragen. +Du kannst deine Befehle dynamisch gestalten, indem du Shell-Befehle direkt innerhalb deines `prompt` ausführst und deren Ausgabe einfügst. Das ist ideal, um Kontext aus deiner lokalen Umgebung zu sammeln, wie z. B. den Inhalt von Dateien zu lesen oder den Status von Git abzufragen. -Wenn ein benutzerdefinierter Befehl versucht, einen Shell-Befehl auszuführen, fordert Qwen Code dich nun zur Bestätigung auf, bevor der Befehl ausgeführt wird. Dies ist eine Sicherheitsmaßnahme, um sicherzustellen, dass nur beabsichtigte Befehle ausgeführt werden können. +Wenn ein benutzerdefinierter Befehl versucht, einen Shell-Befehl auszuführen, fordert Qwen Code dich nun zur Bestätigung auf, bevor er fortfährt. Dies ist eine Sicherheitsmaßnahme, um sicherzustellen, dass nur beabsichtigte Befehle ausgeführt werden können. **So funktioniert's:** -1. **Befehle einfügen:** Verwende die `!{...}`-Syntax in deinem `prompt`, um anzugeben, wo der Befehl ausgeführt werden soll und wohin die Ausgabe eingefügt werden soll. -2. **Ausführung bestätigen:** Beim Ausführen des Befehls erscheint ein Dialog, der die Shell-Befehle auflistet, die der Prompt ausführen möchte. -3. **Berechtigung erteilen:** Du kannst wählen zwischen: - - **Einmal erlauben:** Der Befehl bzw. die Befehle werden nur dieses eine Mal ausgeführt. - - **Immer erlauben (für diese Session):** Der Befehl bzw. die Befehle werden für die aktuelle CLI-Session temporär auf eine Allowlist gesetzt und benötigen keine weitere Bestätigung. - - **Nein:** Die Ausführung der Shell-Befehle wird abgebrochen. - -Die CLI berücksichtigt weiterhin die globalen Einstellungen `excludeTools` und `coreTools`. Ein Befehl wird ohne Rückfrage blockiert, wenn er in der Konfiguration explizit deaktiviert wurde. +1. **Befehle einfügen:** Verwende die `!{...}`-Syntax. +2. **Argument-Substitution:** Falls `{{args}}` innerhalb des Blocks vorhanden ist, wird es automatisch shell-escaped (siehe [Kontextabhängige Injection](#1-context-aware-injection-with-args) oben). +3. **Robuste Parsing-Funktion:** Der Parser verarbeitet korrekt komplexe Shell-Befehle mit verschachtelten Klammern, wie z. B. JSON-Payloads. +4. **Sicherheitsprüfung und Bestätigung:** Die CLI führt eine Sicherheitsprüfung des finalen, aufgelösten Befehls durch (nachdem die Argumente escaped und ersetzt wurden). Ein Dialog zeigt die exakten Befehle an, die ausgeführt werden sollen. +5. **Ausführung und Fehlerberichterstattung:** Der Befehl wird ausgeführt. Falls der Befehl fehlschlägt, enthält die in den Prompt eingefügte Ausgabe die Fehlermeldungen (stderr), gefolgt von einer Statuszeile, z. B. `[Shell command exited with code 1]`. Das hilft dem Modell, den Kontext des Fehlers zu verstehen. **Beispiel (`git/commit.toml`):** -Dieser Befehl ruft den gestagten Git-Diff ab und verwendet ihn, um das Modell eine Commit-Nachricht schreiben zu lassen. +Dieser Befehl ruft den gestageten Git-Diff ab und verwendet ihn, um das Modell eine Commit-Nachricht schreiben zu lassen. ````toml @@ -273,7 +323,7 @@ Dieser Befehl ruft den gestagten Git-Diff ab und verwendet ihn, um das Modell ei # Aufgerufen via: /git:commit -description = "Generiert eine Git Commit-Nachricht basierend auf den gestagten Änderungen." +description = "Generiert eine Git Commit-Nachricht basierend auf den gestageten Änderungen." # Der Prompt verwendet !{...}, um den Befehl auszuführen und dessen Ausgabe einzufügen. prompt = """ @@ -285,9 +335,9 @@ Bitte generiere eine Conventional Commit-Nachricht basierend auf dem folgenden g """ -``` +```` -Wenn du `/git:commit` ausführst, führt die CLI zuerst `git diff --staged` aus, ersetzt dann `!{git diff --staged}` mit der Ausgabe dieses Befehls, bevor sie den finalen, vollständigen Prompt an das Modell sendet. +Wenn du `/git:commit` ausführst, führt die CLI zuerst `git diff --staged` aus, ersetzt dann `!{git diff --staged}` mit der Ausgabe dieses Befehls, bevor der finale, vollständige Prompt an das Modell gesendet wird. --- @@ -323,12 +373,12 @@ Strukturiere ihn in eine reine Funktion um. Deine Antwort sollte Folgendes enthalten: 1. Den umstrukturierten Codeblock der reinen Funktion. -2. Eine kurze Erklärung der wichtigsten Änderungen, die du vorgenommen hast, und warum diese zur Reinheit beitragen. +2. Eine kurze Erklärung der wichtigsten Änderungen und warum diese zur Reinheit beitragen. """ -**3. Führe den Befehl aus:** +**3. Befehl ausführen:** -Das war's! Du kannst jetzt deinen Befehl in der CLI ausführen. Zuerst fügst du möglicherweise eine Datei zum Kontext hinzu und rufst dann deinen Befehl auf: +Das war's! Du kannst jetzt deinen Befehl in der CLI ausführen. Zuerst fügst du vielleicht eine Datei zum Kontext hinzu und rufst dann deinen Befehl auf: ``` > @my-messy-function.js @@ -340,7 +390,7 @@ Qwen Code führt dann die mehrzeilige Eingabeaufforderung aus, die in deiner TOM ## At-Befehle (`@`) -At-Befehle werden verwendet, um den Inhalt von Dateien oder Verzeichnissen als Teil deines Prompts an das Modell zu übergeben. Diese Befehle beinhalten git-aware Filtering. +At-Befehle werden verwendet, um den Inhalt von Dateien oder Verzeichnissen als Teil deines Prompts an das Modell zu übergeben. Diese Befehle enthalten git-basierte Filterung. - **`@`** - **Beschreibung:** Fügt den Inhalt der angegebenen Datei oder mehrerer Dateien in deinen aktuellen Prompt ein. Das ist nützlich, um Fragen zu spezifischem Code, Text oder ganzen Dateisammlungen zu stellen. @@ -349,16 +399,16 @@ At-Befehle werden verwendet, um den Inhalt von Dateien oder Verzeichnissen als T - `@src/my_project/ Fasse den Code in diesem Verzeichnis zusammen.` - `Worum geht es in dieser Datei? @README.md` - **Details:** - - Wenn ein Pfad zu einer einzelnen Datei angegeben wird, wird deren Inhalt eingelesen. - - Wird ein Verzeichnispfad angegeben, versucht der Befehl, den Inhalt aller Dateien innerhalb dieses Verzeichnisses und seiner Unterverzeichnisse einzulesen. - - Leerzeichen in Pfaden müssen mit einem Backslash maskiert werden (z. B. `@Meine\ Dokumente/datei.txt`). + - Wenn ein Pfad zu einer einzelnen Datei angegeben wird, wird deren Inhalt gelesen. + - Wenn ein Pfad zu einem Verzeichnis angegeben wird, versucht der Befehl, den Inhalt der Dateien innerhalb dieses Verzeichnisses und aller Unterverzeichnisse zu lesen. + - Leerzeichen in Pfaden sollten mit einem Backslash maskiert werden (z. B. `@Meine\ Dokumente/datei.txt`). - Intern verwendet der Befehl das `read_many_files`-Tool. Der Inhalt wird abgerufen und dann in deinen Prompt eingefügt, bevor er an das Modell gesendet wird. - - **Git-aware Filtering:** Standardmäßig werden git-ignorierte Dateien (wie `node_modules/`, `dist/`, `.env`, `.git/`) ausgeschlossen. Dieses Verhalten kann über die `fileFiltering`-Einstellungen angepasst werden. - - **Dateitypen:** Der Befehl ist für textbasierte Dateien gedacht. Auch wenn versucht wird, beliebige Dateien einzulesen, könnten binäre oder sehr große Dateien vom zugrunde liegenden `read_many_files`-Tool übersprungen oder gekürzt werden, um Performance und Relevanz sicherzustellen. Das Tool zeigt an, wenn Dateien übersprungen wurden. - - **Ausgabe:** Die CLI zeigt eine Tool-Aufruf-Nachricht an, die angibt, dass `read_many_files` verwendet wurde, sowie eine Meldung mit Statusinformationen und den verarbeiteten Pfaden. + - **Git-basierte Filterung:** Standardmäßig werden git-ignorierte Dateien (wie `node_modules/`, `dist/`, `.env`, `.git/`) ausgeschlossen. Dieses Verhalten kann über die `fileFiltering`-Einstellungen angepasst werden. + - **Dateitypen:** Der Befehl ist für textbasierte Dateien gedacht. Auch wenn versucht wird, beliebige Dateien zu lesen, könnten binäre oder sehr große Dateien vom zugrunde liegenden `read_many_files`-Tool übersprungen oder gekürzt werden, um Leistung und Relevanz zu gewährleisten. Das Tool zeigt an, wenn Dateien übersprungen wurden. + - **Ausgabe:** Die CLI zeigt eine Tool-Aufruf-Nachricht an, die angibt, dass `read_many_files` verwendet wurde, sowie eine Nachricht mit Details zum Status und den verarbeiteten Pfaden. - **`@` (Alleinstehendes @-Symbol)** - - **Beschreibung:** Wird nur ein `@`-Symbol ohne Pfad eingegeben, wird der Prompt unverändert an das Modell weitergeleitet. Das kann nützlich sein, wenn du im Prompt explizit über das `@`-Symbol selbst sprichst. + - **Beschreibung:** Wenn du nur ein `@`-Symbol ohne Pfad eingibst, wird der Prompt unverändert an das Modell weitergeleitet. Das kann nützlich sein, wenn du im Prompt _über_ das `@`-Symbol selbst sprichst. ### Fehlerbehandlung für `@`-Befehle @@ -367,7 +417,7 @@ At-Befehle werden verwendet, um den Inhalt von Dateien oder Verzeichnissen als T ## Shell-Modus & Passthrough-Befehle (`!`) -Das Präfix `!` ermöglicht es dir, direkt von Qwen Code aus mit der Shell deines Systems zu interagieren. +Das Präfix `!` ermöglicht es dir, direkt mit der Shell deines Systems aus Qwen Code heraus zu interagieren. - **`!`** - **Beschreibung:** Führt den angegebenen `` mit `bash` unter Linux/macOS oder `cmd.exe` unter Windows aus. Jegliche Ausgaben oder Fehler des Befehls werden im Terminal angezeigt. @@ -378,7 +428,7 @@ Das Präfix `!` ermöglicht es dir, direkt von Qwen Code aus mit der Shell deine - **`!` (Shell-Modus umschalten)** - **Beschreibung:** Die Eingabe von `!` allein schaltet den Shell-Modus um. - **Shell-Modus aktivieren:** - - Im aktiven Zustand verwendet der Shell-Modus eine andere Farbgebung und zeigt einen "Shell Mode Indicator" an. + - Im aktiven Zustand verwendet der Shell-Modus eine andere Farbdarstellung und einen „Shell Mode Indicator“. - Während des Shell-Modus wird der eingegebene Text direkt als Shell-Befehl interpretiert. - **Shell-Modus verlassen:** - Beim Verlassen kehrt die Benutzeroberfläche zu ihrem Standard-Aussehen zurück und das normale Verhalten von Qwen Code wird fortgesetzt. diff --git a/website/content/de/cli/configuration.md b/website/content/de/cli/configuration.md index 6f50669b..f7042941 100644 --- a/website/content/de/cli/configuration.md +++ b/website/content/de/cli/configuration.md @@ -1,6 +1,6 @@ # Qwen Code Konfiguration -Qwen Code bietet mehrere Möglichkeiten, sein Verhalten zu konfigurieren, darunter Umgebungsvariablen, Kommandozeilenargumente und Einstellungsdateien. Dieses Dokument beschreibt die verschiedenen Konfigurationsmethoden und verfügbaren Einstellungen. +Qwen Code bietet mehrere Möglichkeiten, um sein Verhalten zu konfigurieren, darunter Umgebungsvariablen, Kommandozeilenargumente und Einstellungsdateien. Dieses Dokument beschreibt die verschiedenen Konfigurationsmethoden und verfügbaren Einstellungen. ## Konfigurationsebenen @@ -13,27 +13,28 @@ Die Konfiguration wird in der folgenden Reihenfolge der Priorität angewendet (n 5. **Umgebungsvariablen:** Systemweite oder sitzungsspezifische Variablen, möglicherweise geladen aus `.env` Dateien. 6. **Kommandozeilenargumente:** Werte, die beim Starten der CLI übergeben werden. -## Settings files +## Settings-Dateien Qwen Code verwendet `settings.json` Dateien für die persistente Konfiguration. Es gibt drei Speicherorte für diese Dateien: -- **User settings file:** - - **Location:** `~/.qwen/settings.json` (wobei `~` dein Home-Verzeichnis ist). - - **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. 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. 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. +- **User Settings-Datei:** + - **Speicherort:** `~/.qwen/settings.json` (wobei `~` dein Home-Verzeichnis ist). + - **Gültigkeitsbereich:** Gilt für alle Qwen Code Sessions des aktuellen Benutzers. +- **Project Settings-Datei:** + - **Speicherort:** `.qwen/settings.json` im Root-Verzeichnis deines Projekts. + - **Gültigkeitsbereich:** Gilt nur, wenn Qwen Code aus diesem spezifischen Projekt heraus gestartet wird. Project Settings überschreiben User Settings. -**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"`. +- **System Settings-Datei:** + - **Speicherort:** `/etc/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) oder `/Library/Application Support/QwenCode/settings.json` (macOS). Der Pfad kann mit der Umgebungsvariable `QWEN_CODE_SYSTEM_SETTINGS_PATH` überschrieben werden. + - **Gültigkeitsbereich:** Gilt für alle Qwen Code Sessions auf dem System, für alle Benutzer. System Settings überschreiben User und Project Settings. Kann für Systemadministratoren in Unternehmen nützlich sein, um Kontrolle über die Qwen Code Einrichtungen der Benutzer zu haben. + +**Hinweis zu Umgebungsvariablen in Settings:** String-Werte innerhalb deiner `settings.json` Dateien können Umgebungsvariablen mit der Syntax `$VAR_NAME` oder `${VAR_NAME}` referenzieren. Diese Variablen werden automatisch aufgelöst, wenn die Settings geladen werden. Wenn du zum Beispiel eine Umgebungsvariable `MY_API_TOKEN` hast, kannst du sie in der `settings.json` so verwenden: `"apiKey": "$MY_API_TOKEN"`. ### 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 +59,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): 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. + - **`respectGitIgnore`** (boolean): Ob `.gitignore`-Muster bei der Dateierkennung berücksichtigt werden sollen. Bei `true` werden git-ignorierte Dateien (wie `node_modules/`, `dist/`, `.env`) automatisch von @-Befehlen und Dateilisten ausgeschlossen. + - **`enableRecursiveFileSearch`** (boolean): Ob rekursive Suche nach Dateinamen unterhalb des aktuellen Verzeichnisses aktiviert ist, wenn @-Präfixe im Prompt vervollständigt werden. - **Beispiel:** ```json "fileFiltering": { @@ -69,30 +70,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 des `ls -l`-Befehls. - - **Standard:** Alle Tools, die dem Modell zur Verfügung stehen. + - **Beschreibung:** Ermöglicht es, eine Liste von Core-Tool-Namen anzugeben, die dem Modell zur Verfügung gestellt werden sollen. Damit kann die Menge der eingebauten Tools eingeschränkt werden. Siehe [Built-in Tools](../core/tools-api.md#built-in-tools) für eine Liste der Core-Tools. Es können auch Tool-spezifische Einschränkungen für Tools wie `ShellTool` festgelegt werden. Beispiel: `"coreTools": ["ShellTool(ls -l)"]` erlaubt nur den Befehl `ls -l`. + - **Standard:** Alle Tools sind standardmäßig verfügbar. - **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. Auch hier können Befehlsspezifische Einschränkungen wie bei `ShellTool` verwendet werden. Beispiel: `"excludeTools": ["ShellTool(rm -rf)"]` blockiert den `rm -rf`-Befehl. + - **Beschreibung:** Ermöglicht es, eine Liste von Core-Tool-Namen anzugeben, die vom Modell ausgeschlossen werden sollen. Ein Tool, das sowohl in `excludeTools` als auch in `coreTools` aufgeführt ist, wird ausgeschlossen. Es können auch Tool-spezifische Einschränkungen wie bei `ShellTool` festgelegt werden. Beispiel: `"excludeTools": ["ShellTool(rm -rf)"]` blockiert den Befehl `rm -rf`. - **Standard:** Keine Tools ausgeschlossen. - **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 nicht vertrauenswürdigen Code sicher auszuführen. Es wird empfohlen, `coreTools` zu verwenden, um explizit die erlaubten Befehle auszuwählen. + - **Sicherheitshinweis:** Die Einschränkungen in `excludeTools` basieren auf einfacher Stringvergleichung und können leicht umgangen werden. Diese Funktion ist **kein Sicherheitsmechanismus** und sollte nicht verwendet werden, um das sichere Ausführen von nicht vertrauenswürdigem Code zu gewährleisten. Es wird empfohlen, `coreTools` zu verwenden, um explizit erlaubte Befehle auszuwählen. - **`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 verbunden wird. Diese Einstellung wird ignoriert, wenn `--allowed-mcp-server-names` gesetzt ist. - - **Standard:** Alle MCP-Server stehen dem Modell zur Verfügung. + - **Beschreibung:** Ermöglicht es, eine Liste von MCP-Servernamen anzugeben, die dem Modell zur Verfügung gestellt werden sollen. Damit kann die Menge der verfügbaren MCP-Server eingeschränkt werden. Diese Einstellung wird ignoriert, wenn `--allowed-mcp-server-names` gesetzt ist. + - **Standard:** Alle MCP-Server sind standardmäßig verfügbar. - **Beispiel:** `"allowMCPServers": ["myPythonServer"]`. - - **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**. + - **Sicherheitshinweis:** Diese Funktion verwendet einfache Stringvergleiche auf Servernamen, die manipuliert werden können. Systemadministratoren sollten ggf. die `mcpServers` auf Systemebene konfigurieren, um zu verhindern, dass Benutzer eigene Server konfigurieren. Diese Funktion sollte **nicht als sicherer Mechanismus** betrachtet werden. - **`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 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**. + - **Sicherheitshinweis:** Diese Funktion verwendet einfache Stringvergleiche auf Servernamen, die manipuliert werden können. Systemadministratoren sollten ggf. die `mcpServers` auf Systemebene konfigurieren, um zu verhindern, dass Benutzer eigene Server konfigurieren. Diese Funktion sollte **nicht als sicherer Mechanismus** betrachtet werden. - **`autoAccept`** (boolean): - - **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. + - **Beschreibung:** Legt fest, ob die CLI Tool-Aufrufe, die als sicher gelten (z. B. read-only-Operationen), automatisch akzeptiert und ausgeführt werden, ohne explizite Benutzerbestätigung. Bei `true` wird die Bestätigungsabfrage für sichere Tools übersprungen. - **Standard:** `false` - **Beispiel:** `"autoAccept": true` @@ -102,7 +103,7 @@ 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. 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. + - **Beschreibung:** Aktiviert oder deaktiviert den Vim-Modus für die Eingabebearbeitung. Im aktivierten Zustand unterstützt der Eingabebereich Vim-Befehle mit NORMAL- und INSERT-Modus. Der Status wird in der Fußzeile angezeigt und bleibt zwischen Sitzungen erhalten. - **Standard:** `false` - **Beispiel:** `"vimMode": true` @@ -112,31 +113,35 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt - **Beispiel:** `"sandbox": "docker"` - **`toolDiscoveryCommand`** (string): - - **Beschreibung:** Definiert einen benutzerdefinierten Shell-Befehl zur Erkennung von Tools aus dem Projekt. Der Befehl muss auf `stdout` ein JSON-Array von [Function Declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) zurückgeben. Tool-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-Wrappers sind optional. - **Standard:** Leer - **Beispiel:** `"toolDiscoveryCommand": "bin/get_tools"` - **`toolCallCommand`** (string): - - **Beschreibung:** Definiert einen benutzerdefinierten Shell-Befehl zum Aufruf eines spezifischen Tools, das über `toolDiscoveryCommand` gefunden wurde. Der Befehl muss folgende Kriterien erfüllen: + - **Beschreibung:** Definiert einen benutzerdefinierten Shell-Befehl zum Aufrufen eines bestimmten Tools, das über `toolDiscoveryCommand` gefunden wurde. Der Befehl muss folgende Kriterien erfüllen: - Der erste Parameter muss der Funktionsname sein (genau wie in der [Function Declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)). - - Die Funktionsargumente müssen als JSON über `stdin` gelesen werden, analog zu [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). - - Die Funktionsausgabe muss als JSON über `stdout` zurückgegeben werden, analog zu [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). + - 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 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. + - **Beschreibung:** Konfiguriert Verbindungen zu einem oder mehreren Model-Context Protocol (MCP)-Servern zur Erkennung und Nutzung benutzerdefinierter Tools. Qwen Code versucht, sich mit jedem konfigurierten MCP-Server zu verbinden, um verfügbare Tools zu erkennen. Wenn mehrere Server ein Tool mit demselben Namen anbieten, wird der Name mit dem Server-Alias vorangestellt (z. B. `serverAlias__actualToolName`), um Konflikte zu vermeiden. Das System kann bestimmte Schema-Eigenschaften aus MCP-Tooldefinitionen entfernen, um Kompatibilität zu gewährleisten. Mindestens eines der Felder `command`, `url` oder `httpUrl` muss angegeben werden. Die Priorität ist: `httpUrl`, dann `url`, dann `command`. - **Standard:** Leer - **Eigenschaften:** - **``** (object): Die Serverparameter für den benannten Server. - - `command` (string, erforderlich): Der Befehl zum Starten des MCP-Servers. - - `args` (Array von Strings, optional): Argumente, die an den Befehl übergeben werden. - - `env` (object, optional): Umgebungsvariablen, die für den Serverprozess gesetzt werden. - - `cwd` (string, optional): Das Arbeitsverzeichnis, in dem der Server gestartet wird. + - `command` (string, optional): Der Befehl zum Starten des MCP-Servers über Standard-I/O. + - `args` (Array von Strings, optional): Argumente für den Befehl. + - `env` (object, optional): Umgebungsvariablen für den Serverprozess. + - `cwd` (string, optional): Arbeitsverzeichnis zum Starten des Servers. + - `url` (string, optional): URL eines MCP-Servers, der Server-Sent Events (SSE) verwendet. + - `httpUrl` (string, optional): URL eines MCP-Servers, der streambare HTTP-Kommunikation verwendet. + - `headers` (object, optional): HTTP-Header, die mit Anfragen an `url` oder `httpUrl` gesendet werden. - `timeout` (number, optional): Zeitlimit in Millisekunden für Anfragen an diesen MCP-Server. - `trust` (boolean, optional): Vertraue diesem Server und umgehe alle Tool-Bestätigungen. - - `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. + - `description` (string, optional): Kurze Beschreibung des Servers, z. B. für Anzeigezwecke. + - `includeTools` (Array von Strings, optional): Liste der Tool-Namen, die von diesem Server verwendet werden sollen. Wenn angegeben, sind nur diese Tools verfügbar (Whitelist). Andernfalls sind alle Tools standardmäßig aktiviert. + - `excludeTools` (Array von Strings, optional): Liste der Tool-Namen, die von diesem Server ausgeschlossen werden sollen. Diese Tools sind dann nicht verfügbar, auch wenn sie vom Server angeboten werden. **Hinweis:** `excludeTools` hat Vorrang vor `includeTools` – wenn ein Tool in beiden Listen steht, wird es ausgeschlossen. - **Beispiel:** ```json "mcpServers": { @@ -159,12 +164,26 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt "env": { "API_KEY": "$MY_API_TOKEN" } + }, + "mySseServer": { + "url": "http://localhost:8081/events", + "headers": { + "Authorization": "Bearer $MY_SSE_TOKEN" + }, + "description": "Ein Beispiel-SSE-basierter MCP-Server." + }, + "myStreamableHttpServer": { + "httpUrl": "http://localhost:8082/stream", + "headers": { + "X-API-Key": "$MY_HTTP_API_KEY" + }, + "description": "Ein Beispiel-Streamable-HTTP-basierter MCP-Server." } } ``` - **`checkpointing`** (object): - - **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. + - **Beschreibung:** Konfiguriert die Checkpointing-Funktion, mit der Konversations- und Dateizustände gespeichert und wiederhergestellt werden können. Weitere Informationen unter [Checkpointing documentation](../checkpointing.md). - **Standard:** `{"enabled": false}` - **Eigenschaften:** - **`enabled`** (boolean): Bei `true` ist der `/restore`-Befehl verfügbar. @@ -175,13 +194,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 unter [Telemetry](../telemetry.md). + - **Beschreibung:** Konfiguriert das Logging und die Erfassung von Metriken für Qwen Code. Weitere Informationen unter [Telemetry](../telemetry.md). - **Standard:** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **Eigenschaften:** - - **`enabled`** (boolean): Gibt an, ob Telemetrie aktiviert ist. + - **`enabled`** (boolean): Ob Telemetrie aktiviert ist. - **`target`** (string): Ziel für gesammelte Telemetriedaten. Unterstützte Werte: `local` und `gcp`. - - **`otlpEndpoint`** (string): Endpunkt für den OTLP-Exporter. - - **`logPrompts`** (boolean): Gibt an, ob der Inhalt von Benutzerprompts in die Logs aufgenommen wird. + - **`otlpEndpoint`** (string): Endpunkt für den OTLP Exporter. + - **`logPrompts`** (boolean): Ob der Inhalt von Benutzerprompts in Logs enthalten sein soll. - **Beispiel:** ```json "telemetry": { @@ -193,7 +212,7 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt ``` - **`usageStatisticsEnabled`** (boolean): - - **Beschreibung:** Aktiviert oder deaktiviert die Erfassung von Nutzungsstatistiken. Siehe [Usage Statistics](#usage-statistics) für weitere Informationen. + - **Beschreibung:** Aktiviert oder deaktiviert die Erfassung von Nutzungsstatistiken. Weitere Informationen unter [Usage Statistics](#usage-statistics). - **Standard:** `true` - **Beispiel:** ```json @@ -217,7 +236,7 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt ``` - **`maxSessionTurns`** (number): - - **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. + - **Beschreibung:** Legt die maximale Anzahl von Turns pro Sitzung fest. Wenn das Limit überschritten wird, stoppt die CLI und startet einen neuen Chat. - **Standard:** `-1` (unbegrenzt) - **Beispiel:** ```json @@ -238,15 +257,7 @@ Neben einer Projekt-Einstellungsdatei kann das `.qwen`-Verzeichnis eines Projekt ``` - **`excludedProjectEnvVars`** (Array von Strings): - - **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 + - **Beschreibung:** Gibt Umgebungsvariablen an, die aus Projekt-`.env`-Dateien ausgeschlossen werden sollen. Dies verhindert, dass projektspezifische ### Beispiel `settings.json`: @@ -295,69 +306,50 @@ 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. +Umgebungsvariablen sind eine gängige Methode, um Anwendungen zu konfigurieren – besonders für sensible Informationen wie API keys oder Einstellungen, die sich zwischen verschiedenen Umgebungen unterscheiden. Informationen zur Authentifizierung findest du in der [Authentication Dokumentation](./authentication.md), die alle verfügbaren Authentifizierungsmethoden abdeckt. -Die CLI lädt Umgebungsvariablen automatisch aus einer `.env`-Datei. Die Ladereihenfolge ist wie folgt: +Die CLI lädt Umgebungsvariablen automatisch aus einer `.env` Datei. Die Ladereihenfolge ist: -1. `.env`-Datei im aktuellen Arbeitsverzeichnis. -2. Falls nicht gefunden, sucht sie rekursiv in den übergeordneten Verzeichnissen, bis eine `.env`-Datei gefunden wird oder das Projekt-Root-Verzeichnis (erkennbar an einem `.git`-Ordner) oder das Home-Verzeichnis erreicht ist. -3. Falls immer noch nichts gefunden wurde, wird `~/.env` (im Home-Verzeichnis des Benutzers) geladen. +1. `.env` Datei im aktuellen Arbeitsverzeichnis. +2. Falls nicht gefunden, sucht sie rekursiv in den übergeordneten Verzeichnissen, 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:** Bestimmte Umgebungsvariablen (wie `DEBUG` und `DEBUG_MODE`) werden standardmäßig aus Projekt `.env` Dateien ausgeschlossen, um Störungen im CLI-Verhalten zu vermeiden. Variablen aus `.qwen/.env` Dateien werden niemals ausgeschlossen. Du kannst dieses Verhalten über die Einstellung `excludedProjectEnvVars` in deiner `settings.json` Datei anpassen. -- **`GEMINI_API_KEY`** (erforderlich): - - Dein API key für die Gemini API. - - **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 standardmäßig zu verwendende Gemini-Modell fest. +- **`OPENAI_API_KEY`**: + - Eine von mehreren verfügbaren [Authentifizierungsmethoden](./authentication.md). + - Setze diesen Wert in deinem Shell-Profil (z. B. `~/.bashrc`, `~/.zshrc`) oder in einer `.env` Datei. +- **`OPENAI_BASE_URL`**: + - Eine von mehreren verfügbaren [Authentifizierungsmethoden](./authentication.md). + - Setze diesen Wert in deinem Shell-Profil (z. B. `~/.bashrc`, `~/.zshrc`) oder in einer `.env` Datei. +- **`OPENAI_MODEL`**: + - Legt das standardmäßig zu verwendende OPENAI-Modell fest. - Überschreibt den fest codierten Standardwert. - - 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 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. - - 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. - - **Beispiel:** `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"` -- **`OTLP_GOOGLE_CLOUD_PROJECT`**: - - Deine Google Cloud Project ID für Telemetrie in Google Cloud. - - Beispiel: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. -- **`GOOGLE_CLOUD_LOCATION`**: - - 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"`. + - Beispiel: `export OPENAI_MODEL="qwen3-coder-plus"` - **`GEMINI_SANDBOX`**: - - Alternative zur `sandbox`-Einstellung in `settings.json`. + - Alternative zur `sandbox` Einstellung in der `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 Ordner, siehe `packages/cli/src/utils/sandbox-macos-permissive-open.sb`), erlaubt aber andere Operationen. +- **`SEATBELT_PROFILE`** (nur macOS): + - Wechselt das Seatbelt (`sandbox-exec`) Profil unter macOS. + - `permissive-open`: (Standard) Beschränkt Schreibzugriffe auf den Projektordner (und einige andere, siehe `packages/cli/src/utils/sandbox-macos-permissive-open.sb`), erlaubt aber andere Operationen. - `strict`: Verwendet ein striktes Profil, das standardmäßig alle Operationen ablehnt. - - ``: Verwendet ein benutzerdefiniertes Profil. Um ein solches Profil zu definieren, erstelle eine Datei mit dem Namen `sandbox-macos-.sb` im `.qwen/`-Verzeichnis deines Projekts (z. B. `my-project/.qwen/sandbox-macos-custom.sb`). + - ``: 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 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. + - Auf `true` oder `1` setzen, um detaillierte Debug-Logs zu aktivieren – hilfreich bei der Fehlersuche. + - **Hinweis:** Diese Variablen werden standardmäßig aus Projekt `.env` Dateien ausgeschlossen, um das CLI-Verhalten nicht zu beeinträchtigen. Verwende `.qwen/.env` Dateien, wenn du diese speziell für Qwen Code setzen musst. - **`NO_COLOR`**: - 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`**: - - Legt den Endpunkt für den Code Assist Server fest. + - Gibt den Endpunkt für den Code Assist Server an. - Nützlich für Entwicklung und Tests. - **`TAVILY_API_KEY`**: - - Dein API key für den Tavily Web Search Service. - - Erforderlich, um die Funktionalität des `web_search`-Tools zu aktivieren. - - Falls nicht konfiguriert, wird das Web Search Tool deaktiviert und übersprungen. + - 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. - Beispiel: `export TAVILY_API_KEY="tvly-your-api-key-here"` ## Command-Line Arguments @@ -365,10 +357,10 @@ Die CLI lädt Umgebungsvariablen automatisch aus einer `.env`-Datei. Die Laderei 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. - - Beispiel: `npm start -- --model gemini-1.5-pro-latest` + - Gibt das Qwen-Modell an, das für diese Sitzung verwendet werden soll. + - Beispiel: `npm start -- --model qwen3-coder-plus` - **`--prompt `** (**`-p `**): - - Wird verwendet, um einen Prompt direkt an den Befehl zu übergeben. Dies ruft Qwen Code im nicht-interaktiven Modus auf. + - Wird verwendet, um einen Prompt direkt an den Befehl zu übergeben. Dies startet Qwen Code im nicht-interaktiven Modus. - **`--prompt-interactive `** (**`-i `**): - Startet eine interaktive Sitzung mit dem übergebenen Prompt als initiale Eingabe. - Der Prompt wird innerhalb der interaktiven Sitzung verarbeitet, nicht davor. @@ -385,13 +377,13 @@ Argumente, die direkt beim Ausführen der CLI übergeben werden, können andere - **`--help`** (oder **`-h`**): - Zeigt Hilfsinformationen zu den Command-Line Arguments an. - **`--show-memory-usage`**: - - Zeigt die aktuelle Speicherauslastung an. + - Zeigt den aktuellen Speicherverbrauch 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: + - Setzt den Genehmigungsmodus für Tool-Aufrufe. Verfügbare Modi: - `default`: Fordert bei jedem Tool-Aufruf eine Genehmigung an (Standardverhalten) - - `auto_edit`: Genehmigt automatisch Edit-Tools (replace, write_file), während andere Tools zur Genehmigung abgefragt werden + - `auto_edit`: Genehmigt automatisch Edit-Tools (edit, write_file), während für andere eine Eingabe erforderlich ist - `yolo`: Genehmigt automatisch alle Tool-Aufrufe (äquivalent zu `--yolo`) - Kann nicht zusammen mit `--yolo` verwendet werden. Verwende stattdessen `--approval-mode=yolo` für den neuen einheitlichen Ansatz. - Beispiel: `qwen --approval-mode auto_edit` @@ -401,6 +393,8 @@ Argumente, die direkt beim Ausführen der CLI übergeben werden, können andere - Setzt das Ziel für die Telemetrie. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. - **`--telemetry-otlp-endpoint`**: - Setzt den OTLP-Endpunkt für die Telemetrie. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. +- **`--telemetry-otlp-protocol`**: + - Setzt das OTLP-Protokoll für die Telemetrie (`grpc` oder `http`). Standardmäßig `grpc`. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. - **`--telemetry-log-prompts`**: - Aktiviert das Logging von Prompts für die Telemetrie. Siehe [Telemetrie](../telemetry.md) für weitere Informationen. - **`--checkpointing`**: @@ -422,16 +416,16 @@ Argumente, die direkt beim Ausführen der CLI übergeben werden, können andere - **`--version`**: - 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`. + - Aktiviert das Logging von OpenAI-API-Aufrufen zur Fehlersuche und Analyse. Dieses Flag überschreibt die `enableOpenAILogging`-Einstellung in der `settings.json`. - **`--tavily-api-key `**: - 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 das KI-Modell zu übergeben, wodurch die Antworten gezielter und präziser auf deine Anforderungen abgestimmt werden. Die CLI enthält UI-Elemente, wie z. B. einen Indikator in der Fußzeile, der die Anzahl der geladenen Context Files anzeigt, um dich über den aktiven Kontext zu informieren. +Auch wenn es sich nicht um eine 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. +- **Zweck:** Diese Markdown-Dateien enthalten Anweisungen, Richtlinien oder Kontextinformationen, die du möchtest, dass das Qwen-Modell während eurer Interaktionen berücksichtigt. Das System ist so konzipiert, dass es diesen Instruktionskontext hierarchisch verwaltet. ### Beispiel für den Inhalt einer Context-Datei (z. B. `QWEN.md`) @@ -443,7 +437,7 @@ Hier ist ein konzeptionelles Beispiel dafür, was eine Context-Datei im Stammver ## Allgemeine Anweisungen: -- Bei der Generierung neuer TypeScript-Code sollte der bestehende Codierungsstil befolgt werden. +- Wenn du neuen TypeScript-Code generierst, halte dich bitte an den bestehenden Codierungsstil. - Stelle sicher, dass alle neuen Funktionen und Klassen über JSDoc-Kommentare verfügen. - Bevorzuge funktionale Programmierparadigmen, wo dies angemessen ist. - Der gesamte Code sollte mit TypeScript 5.0 und Node.js 20+ kompatibel sein. @@ -458,7 +452,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 neue API-Aufruffunktionen hinzugefügt werden, stellen sicher, dass diese eine robuste Fehlerbehandlung und Protokollierung enthalten. +- Wenn du neue API-Aufruffunktionen hinzufügst, stelle sicher, dass diese eine robuste Fehlerbehandlung und Protokollierung enthalten. - Verwende das vorhandene `fetchWithRetry`-Utility für alle GET-Anfragen. ## Zu den Abhängigkeiten: @@ -469,21 +463,21 @@ Hier ist ein konzeptionelles Beispiel dafür, was eine Context-Datei im Stammver 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 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: +- **Hierarchisches Laden und Priorität:** Die CLI implementiert ein ausgeklügeltes hierarchisches Speichersystem, indem sie Kontextdateien (z. B. `QWEN.md`) aus mehreren Verzeichnissen lädt. Inhalte aus Dateien weiter unten in dieser Liste (also spezifischer) überschreiben oder ergänzen in der Regel die Inhalte aus Dateien weiter oben (also allgemeiner). Die genaue Reihenfolge der Verkettung und der finale Kontext können mit dem Befehl `/memory show` eingesehen werden. Die typische Ladereihenfolge ist: 1. **Globale Kontextdatei:** - - Ort: `~/.qwen/` (z. B. `~/.qwen/QWEN.md` in deinem Benutzer-Home-Verzeichnis). - - Gültigkeitsbereich: Stellt Standardanweisungen für alle deine Projekte bereit. + - Ort: `~/.qwen/` (z. B. `~/.qwen/QWEN.md` in deinem Benutzerverzeichnis). + - Geltungsbereich: Stellt Standardanweisungen für alle deine Projekte bereit. 2. **Projektstamm & übergeordnete Verzeichnisse:** - - Ort: Die CLI sucht nach der konfigurierten Kontextdatei im aktuellen Arbeitsverzeichnis und 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 sucht nach der konfigurierten Kontextdatei im aktuellen Arbeitsverzeichnis und dann in jedem übergeordneten Verzeichnis bis entweder zum Projektstamm (erkennbar an einem `.git`-Ordner) oder zu deinem Home-Verzeichnis. + - Geltungsbereich: 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. - - Gültigkeitsbereich: Ermöglicht hochspezifische Anweisungen, die für eine bestimmte Komponente, ein Modul oder einen Abschnitt deines Projekts relevant sind. + - Geltungsbereich: Ermöglicht hochspezifische Anweisungen, die für eine bestimmte Komponente, ein Modul oder einen Teil deines Projekts relevant sind. - **Verkettung & UI-Anzeige:** Die Inhalte aller gefundenen Kontextdateien werden verkettet (mit Trennzeichen, die ihren Ursprung und Pfad angeben) und als Teil des Systemprompts bereitgestellt. In der CLI-Fußzeile wird die Anzahl der geladenen Kontextdateien angezeigt, was dir einen schnellen visuellen Hinweis auf den aktiven Anweisungskontext gibt. - **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:** - - 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. + - Verwende `/memory refresh`, um einen erneuten Scan und Reload aller Kontextdateien aus allen konfigurierten Orten zu erzwingen. Dies aktualisiert den Anweisungskontext der KI. + - Verwende `/memory show`, um den aktuell geladenen, kombinierten Anweisungskontext anzuzeigen, sodass du die Hierarchie und den von der KI verwendeten Inhalt überprüfen kannst. - Die vollständigen Details zum `/memory`-Befehl und seinen Unterbefehlen (`show` und `refresh`) findest du in der [Befehlsdokumentation](./commands.md#memory). Durch das Verstehen und Nutzen dieser Konfigurationsebenen sowie der hierarchischen Struktur von Kontextdateien kannst du den Speicher der KI effektiv verwalten und die Antworten von Qwen Code an deine spezifischen Anforderungen und Projekte anpassen. @@ -500,7 +494,7 @@ Sandboxing ist standardmäßig deaktiviert, aber du kannst es auf verschiedene A 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 basieren: +Für projektspezifische Anforderungen kannst du ein eigenes Dockerfile unter `.qwen/sandbox.Dockerfile` im Root-Verzeichnis deines Projekts erstellen. Dieses Dockerfile kann auf dem Basis-Sandbox-Image basieren: ```dockerfile FROM qwen-code-sandbox @@ -523,18 +517,18 @@ BUILD_SANDBOX=1 qwen -s ## Nutzungsstatistiken -Um uns bei der Verbesserung von Qwen Code zu helfen, sammeln wir anonymisierte Nutzungsstatistiken. Diese Daten helfen uns zu verstehen, wie die CLI verwendet wird, häufige Probleme zu identifizieren und neue Funktionen zu priorisieren. +Um uns bei der Verbesserung von Qwen Code zu unterstützen, sammeln wir anonymisierte Nutzungsstatistiken. Diese Daten helfen uns zu verstehen, wie die CLI verwendet wird, häufige Probleme zu identifizieren und neue Funktionen zu priorisieren. **Was wir sammeln:** -- **Tool-Aufrufe:** Wir protokollieren die Namen der Tools, die aufgerufen werden, ob sie erfolgreich sind oder fehlschlagen, und wie lange ihre Ausführung dauert. Wir sammeln keine Argumente, die an die Tools übergeben werden, noch Daten, die von ihnen zurückgegeben werden. -- **API-Anfragen:** Wir protokollieren das für jede Anfrage verwendete Modell, die Dauer der Anfrage und ob sie erfolgreich war. Wir sammeln nicht den Inhalt der Prompts oder Responses. -- **Sitzungsinformationen:** Wir sammeln Informationen zur Konfiguration der CLI, wie z. B. die aktivierten Tools und der Genehmigungsmodus. +- **Tool-Aufrufe:** Wir protokollieren die Namen der aufgerufenen Tools, ob sie erfolgreich waren oder fehlschlugen, sowie deren Ausführungszeit. Wir sammeln weder die an die Tools übergebenen Argumente noch von ihnen zurückgegebene Daten. +- **API-Anfragen:** Wir protokollieren das für jede Anfrage verwendete Modell, die Dauer der Anfrage und ob sie erfolgreich war. Wir sammeln weder den Inhalt der Prompts noch der Antworten. +- **Sitzungsinformationen:** Wir sammeln Informationen zur Konfiguration der CLI, wie z. B. die aktivierten Tools und der Genehmigungsmodus. **Was wir NICHT sammeln:** -- **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. +- **Personenbezogene Daten (PII):** Wir sammeln keine persönlichen Informationen wie Ihren Namen, Ihre E-Mail-Adresse oder API-Keys. +- **Prompt- und Antwortinhalte:** Wir protokollieren weder den Inhalt Ihrer Prompts noch die Antworten des Modells. - **Dateiinhalte:** Wir protokollieren nicht den Inhalt von Dateien, die von der CLI gelesen oder geschrieben werden. **So deaktivieren Sie die Sammlung:** @@ -547,4 +541,12 @@ Sie können die Sammlung von Nutzungsstatistiken jederzeit deaktivieren, indem S } ``` -Hinweis: Wenn die Nutzungsstatistiken aktiviert sind, werden Ereignisse an einen Alibaba Cloud RUM-Sammlungsendpunkt gesendet. \ No newline at end of file +Hinweis: Wenn die Nutzungsstatistiken aktiviert sind, werden Ereignisse an einen Alibaba Cloud RUM-Sammlungsendpunkt gesendet. + +- **`enableWelcomeBack`** (boolean): + - **Beschreibung:** Zeigt einen „Willkommen zurück“-Dialog an, wenn Sie zu einem Projekt mit Konversationsverlauf zurückkehren. + - **Standardwert:** `true` + - **Kategorie:** UI + - **Neustart erforderlich:** Nein + - **Beispiel:** `"enableWelcomeBack": false` + - **Details:** Wenn aktiviert, erkennt Qwen Code automatisch, ob Sie zu einem Projekt mit einer zuvor generierten Projektzusammenfassung (`.qwen/PROJECT_SUMMARY.md`) zurückkehren, und zeigt einen Dialog an, der es Ihnen ermöglicht, Ihre vorherige Konversation fortzusetzen oder neu zu beginnen. Diese Funktion ist mit dem Befehl `/chat summary` und dem Beendigungsbestätigungsdialog integriert. Weitere Informationen finden Sie in der [Welcome Back Dokumentation](./welcome-back.md). \ No newline at end of file diff --git a/website/content/de/cli/index.md b/website/content/de/cli/index.md index 1bbc4fcf..204b8139 100644 --- a/website/content/de/cli/index.md +++ b/website/content/de/cli/index.md @@ -1,21 +1,22 @@ # Qwen Code CLI -Innerhalb von Qwen Code ist `packages/cli` das Frontend, über das Nutzer Prompts an Qwen und andere KI-Modelle senden und Antworten empfangen können – inklusive der dazugehörigen Tools. Eine allgemeine Übersicht über Qwen Code findest du auf der [Hauptdokumentationsseite](../index.md). +Innerhalb von Qwen Code ist `packages/cli` das Frontend, über das Nutzer Prompts an Qwen und andere KI-Modelle senden und Antworten empfangen können, inklusive der zugehörigen Tools. Eine allgemeine Übersicht über Qwen Code findest du auf der [Hauptdokumentationsseite](../index.md). ## Navigation in diesem Abschnitt -- **[Authentication](./authentication.md):** Anleitung zur Einrichtung der Authentifizierung mit Qwen OAuth und OpenAI-kompatiblen Anbietern. -- **[Commands](./commands.md):** Referenz der Qwen Code CLI-Befehle (z. B. `/help`, `/tools`, `/theme`). -- **[Configuration](./configuration.md):** Anleitung zur Anpassung des CLI-Verhaltens mithilfe von Konfigurationsdateien. +- **[Authentication](./authentication.md):** Ein Leitfaden zur Einrichtung der Authentifizierung mit Qwen OAuth und OpenAI-kompatiblen Anbietern. +- **[Commands](./commands.md):** Eine Referenz für Qwen Code CLI-Befehle (z. B. `/help`, `/tools`, `/theme`). +- **[Configuration](./configuration.md):** Ein Leitfaden zur Anpassung des Verhaltens der Qwen Code CLI mithilfe von Konfigurationsdateien. - **[Token Caching](./token-caching.md):** Optimiere API-Kosten durch Token-Caching. -- **[Themes](./themes.md):** Anleitung zur Anpassung des Erscheinungsbilds der CLI mit verschiedenen Themes. -- **[Tutorials](tutorials.md):** Tutorial, das zeigt, wie du Qwen Code zur Automatisierung einer Entwicklungsaufgabe nutzen kannst. +- **[Themes](./themes.md):** Ein Leitfaden zur Anpassung des Erscheinungsbilds der CLI mit verschiedenen Themes. +- **[Tutorials](tutorials.md):** Ein Tutorial, das zeigt, wie du Qwen Code zur Automatisierung einer Entwicklungsaufgabe verwenden kannst. +- **[Welcome Back](./welcome-back.md):** Erfahre mehr über die Welcome Back-Funktion, die dir hilft, nahtlos zwischen Sitzungen weiterzuarbeiten. ## Non-interactive mode Qwen Code kann im Non-interactive mode ausgeführt werden, was für Scripting und Automatisierung nützlich ist. In diesem Modus übergibst du die Eingabe per Pipe an die CLI, sie führt den Befehl aus und beendet sich anschließend. -Das folgende Beispiel übergibt einen Befehl per Pipe von deinem Terminal an Qwen Code: +Das folgende Beispiel übergibt einen Befehl von deinem Terminal per Pipe an Qwen Code: ```bash echo "What is fine tuning?" | qwen diff --git a/website/content/de/cli/token-caching.md b/website/content/de/cli/token-caching.md index f7456922..4c3cabaa 100644 --- a/website/content/de/cli/token-caching.md +++ b/website/content/de/cli/token-caching.md @@ -1,14 +1,14 @@ # Token Caching und Kostenoptimierung -Qwen Code optimiert automatisch die API-Kosten durch Token Caching, wenn du API-Key-Authentifizierung verwendest (z. B. OpenAI-kompatible Anbieter). Dieses Feature nutzt frühere Systemanweisungen und Kontexte wieder, um die Anzahl der verarbeiteten Tokens in nachfolgenden Requests zu reduzieren. +Qwen Code optimiert automatisch die API-Kosten durch Token Caching, wenn du API-Key-Authentifizierung verwendest (z. B. OpenAI-kompatible Anbieter). Dieses Feature nutzt vorherige Systemanweisungen und Kontexte wieder, um die Anzahl der verarbeiteten Tokens in nachfolgenden Requests zu reduzieren. **Token Caching ist verfügbar für:** -- API-Key-Nutzer (Gemini API key) +- API-Key-Nutzer (Qwen API key) - Vertex AI-Nutzer (mit Projekt- und Standortkonfiguration) **Token Caching ist nicht verfügbar für:** - OAuth-Nutzer (Google Personal/Enterprise Accounts) – die Code Assist API unterstützt derzeit keine Erstellung gecachter Inhalte -Du kannst deinen Token-Verbrauch und die Einsparungen durch gecachte Tokens mit dem Befehl `/stats` einsehen. Wenn gecachte Tokens verfügbar sind, werden sie in der Statistik angezeigt. \ No newline at end of file +Du kannst deinen Tokenverbrauch und die Einsparungen durch gecachte Tokens mit dem Befehl `/stats` einsehen. Wenn gecachte Tokens verfügbar sind, werden sie in der Statistik angezeigt. \ No newline at end of file diff --git a/website/content/de/cli/welcome-back.md b/website/content/de/cli/welcome-back.md new file mode 100644 index 00000000..ed50d2a8 --- /dev/null +++ b/website/content/de/cli/welcome-back.md @@ -0,0 +1,135 @@ +# Welcome Back Feature + +Die Welcome Back Funktion hilft dir dabei, deine Arbeit nahtlos fortzusetzen, indem sie automatisch erkennt, wann du zu einem Projekt mit bestehender Konversationshistorie zurückkehrst, und dir anbietet, dort weiterzumachen, wo du aufgehört hast. + +## Übersicht + +Wenn du Qwen Code in einem Projektverzeichnis startest, das eine zuvor generierte Projektzusammenfassung enthält (`.qwen/PROJECT_SUMMARY.md`), wird der Welcome Back Dialog automatisch angezeigt und gibt dir die Möglichkeit, entweder neu zu starten oder deine vorherige Konversation fortzusetzen. + +## Funktionsweise + +### Automatische Erkennung + +Die Welcome Back Funktion erkennt automatisch: + +- **Project Summary File:** Sucht nach `.qwen/PROJECT_SUMMARY.md` in deinem aktuellen Projektverzeichnis +- **Conversation History:** Prüft, ob es eine sinnvolle Konversationshistorie gibt, die fortgesetzt werden kann +- **Settings:** Berücksichtigt deine `enableWelcomeBack` Einstellung (standardmäßig aktiviert) + +### Welcome Back Dialog + +Wenn eine Projektübersicht gefunden wird, siehst du einen Dialog mit: + +- **Last Updated Time:** Zeigt an, wann die Übersicht zuletzt generiert wurde +- **Overall Goal:** Zeigt das Hauptziel deiner vorherigen Sitzung an +- **Current Plan:** Zeigt den Fortschritt der Aufgaben mit Status-Indikatoren: + - `[DONE]` – Abgeschlossene Aufgaben + - `[IN PROGRESS]` – Aktuell in Arbeit + - `[TODO]` – Geplante Aufgaben +- **Task Statistics:** Zusammenfassung der Gesamtaufgaben, abgeschlossenen, laufenden und ausstehenden Aufgaben + +### Optionen + +Wenn der Welcome Back Dialog erscheint, hast du zwei Wahlmöglichkeiten: + +1. **Start new chat session** + - Schließt den Dialog und beginnt eine neue Konversation + - Kein vorheriger Kontext wird geladen + +2. **Continue previous conversation** + - Füllt das Eingabefeld automatisch mit: `@.qwen/PROJECT_SUMMARY.md, Based on our previous conversation, Let's continue?` + - Lädt die Projektübersicht als Kontext für die KI + - Ermöglicht es dir, nahtlos dort weiterzumachen, wo du aufgehört hast + +## Konfiguration + +### Welcome Back aktivieren/deaktivieren + +Du kannst die Welcome Back-Funktion über die Einstellungen steuern: + +**Über den Einstellungsdialog:** + +1. Führe `/settings` in Qwen Code aus +2. Suche "Enable Welcome Back" in der UI-Kategorie +3. Schalte die Einstellung ein/aus + +**Über die Einstellungsdatei:** +Füge Folgendes zu deiner `.qwen/settings.json` hinzu: + +```json +{ + "enableWelcomeBack": true +} +``` + +**Speicherorte der Einstellungen:** + +- **Benutzereinstellungen:** `~/.qwen/settings.json` (wirkt sich auf alle Projekte aus) +- **Projekteinstellungen:** `.qwen/settings.json` (projektspezifisch) + +### Tastenkürzel + +- **Escape:** Schließt den Welcome Back-Dialog (standardmäßig wird eine "neue Chat-Session gestartet") + +## Integration mit anderen Funktionen + +### Generierung der Projektzusammenfassung + +Das Welcome Back-Feature arbeitet nahtlos mit dem Befehl `/chat summary` zusammen: + +1. **Zusammenfassung generieren:** Verwende `/chat summary`, um eine Projektzusammenfassung zu erstellen +2. **Automatische Erkennung:** Wenn du das nächste Mal Qwen Code in diesem Projekt startest, erkennt Welcome Back die Zusammenfassung automatisch +3. **Arbeit fortsetzen:** Wähle „Weitermachen“, und die Zusammenfassung wird als Kontext geladen + +### Beenden-Bestätigung + +Beim Beenden mit `/quit-confirm` und Auswahl von „Zusammenfassung generieren und beenden“: + +1. Wird automatisch eine Projektzusammenfassung erstellt +2. Die nächste Sitzung löst den Welcome Back-Dialog aus +3. Du kannst deine Arbeit nahtlos fortsetzen + +## Dateistruktur + +Das Welcome Back-Feature erstellt und verwendet: + +``` +dein-projekt/ +├── .qwen/ +│ └── PROJECT_SUMMARY.md # Generierte Projektzusammenfassung +``` + +### PROJECT_SUMMARY.md Format + +Die generierte Zusammenfassung folgt dieser Struktur: + +```markdown + +# Project Summary + +## Overall Goal + + +``` + +## Key Knowledge + + + + +## Recent Actions + + + + +## Current Plan + + + + +--- + +## Summary Metadata + +**Update time**: 2025-01-10T15:30:00.000Z +``` \ No newline at end of file diff --git a/website/content/de/deployment.md b/website/content/de/deployment.md index 94f0bda9..48748cf6 100644 --- a/website/content/de/deployment.md +++ b/website/content/de/deployment.md @@ -10,7 +10,7 @@ Es gibt mehrere Möglichkeiten, Qwen Code auszuführen. Die Option, die du wähl ### 1. Standardinstallation (Empfohlen für typische Benutzer) -Dies ist die empfohlene Methode für Endbenutzer, um Qwen Code zu installieren. Dabei wird das Qwen Code-Package aus der NPM-Registry heruntergeladen. +Dies ist die empfohlene Methode für Endbenutzer, um Qwen Code zu installieren. Dabei wird das Qwen Code Package aus der NPM Registry heruntergeladen. - **Globale Installation:** @@ -35,40 +35,40 @@ 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 mit möglichen Nebenwirkungen ausführt. +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. - **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 installiert 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 zur Verfügung hast und die CLI ausführen möchtest. ```bash # Run the published sandbox image - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.9 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 ``` - **Verwendung des `--sandbox` Flags:** - Wenn du Qwen Code lokal installiert hast (gemäß der oben beschriebenen Standardinstallation), kannst du es anweisen, innerhalb des Sandbox-Containers zu laufen. + Wenn du Qwen Code lokal installiert hast (gemäß der oben beschriebenen Standardinstallation), kannst du es anweisen, innerhalb des Sandbox-Containers ausgeführt zu werden. ```bash qwen --sandbox -y -p "your prompt here" ``` --- -### 3. Ausführen aus dem Quellcode (Empfohlen für Qwen Code Contributors) +### 3. Ausführen aus dem Quellcode (Empfohlen für Qwen Code Mitwirkende) -Contributor des Projekts möchten die CLI direkt aus dem Quellcode ausführen. +Mitwirkende am Projekt möchten die CLI direkt aus dem Quellcode ausführen. - **Entwicklungsmodus:** Diese Methode bietet Hot-Reloading und ist nützlich für die aktive Entwicklung. ```bash - # Vom Root des Repositories aus + # Vom Stammverzeichnis des Repositories npm run start ``` -- **Produktionsähnlicher Modus (Verknüpftes Package):** - 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. +- **Produktionsähnlicher Modus (Verknüpftes Paket):** + Diese Methode simuliert eine globale Installation, indem sie Ihr lokales Paket verknüpft. Sie ist nützlich, um einen lokalen Build in einem Produktions-Workflow zu testen. ```bash - # Verknüpfe das lokale CLI-Package mit deinen globalen node_modules + # Verknüpfen Sie das lokale CLI-Paket mit Ihren globalen node_modules npm link packages/cli - # Jetzt kannst du deine lokale Version mit dem `qwen`-Befehl ausführen + # Jetzt können Sie Ihre lokale Version mit dem Befehl `qwen` ausführen qwen ``` @@ -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 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. +Sie können die zuletzt committete Version von Qwen Code direkt aus dem GitHub-Repository ausführen. Dies ist nützlich, um Funktionen zu testen, die sich noch in der Entwicklung befinden. ```bash @@ -99,15 +99,15 @@ Diese Pakete werden sowohl bei der Standardinstallation als auch beim Ausführen **Build- und Packaging-Prozesse** -Es gibt zwei verschiedene Build-Prozesse, die je nach Verteilungskanal verwendet werden: +Es gibt zwei verschiedene Build-Prozesse, abhängig vom Verteilungskanal: -- **NPM-Veröffentlichung:** Für die Veröffentlichung im NPM-Registry wird der TypeScript-Quellcode in `@qwen-code/qwen-code-core` und `@qwen-code/qwen-code` mithilfe des TypeScript Compilers (`tsc`) in Standard-JavaScript transpiliert. Das resultierende `dist/`-Verzeichnis wird im NPM-Paket veröffentlicht. Dies ist ein Standardansatz für TypeScript-Bibliotheken. +- **NPM-Veröffentlichung:** Für die Veröffentlichung im NPM-Registry wird der TypeScript-Quellcode in `@qwen-code/qwen-code-core` und `@qwen-code/qwen-code` mithilfe des TypeScript Compilers (`tsc`) in Standard-JavaScript transpiliert. Das resultierende `dist/`-Verzeichnis wird dann im NPM-Paket veröffentlicht. Dies ist ein 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`-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. +- **GitHub `npx`-Ausführung:** Beim direkten Ausführen der neuesten Qwen Code-Version von GitHub wird ein anderer Prozess durch das `prepare`-Script in der `package.json` ausgelöst. Dieses Script nutzt `esbuild`, um die gesamte Anwendung und ihre Abhängigkeiten in eine einzelne, eigenständige JavaScript-Datei zu bündeln. Dieses Bundle wird dynamisch auf dem Rechner des Benutzers erzeugt und ist nicht im Repository enthalten. **Docker-Sandbox-Image** -Die Docker-basierte Ausführungsmethode wird vom Container-Image `qwen-code-sandbox` unterstützt. Dieses Image wird in einer Container-Registry veröffentlicht und enthält eine 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 global vorinstallierte Version von Qwen Code. ## Release-Prozess diff --git a/website/content/de/ide-integration.md b/website/content/de/ide-integration.md index 4ab1297f..fc6aa9d4 100644 --- a/website/content/de/ide-integration.md +++ b/website/content/de/ide-integration.md @@ -1,8 +1,8 @@ # 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. +Qwen Code kann in deine IDE integriert werden, um ein nahtloseres und kontextbezogenes Erlebnis zu bieten. Diese Integration ermöglicht es der CLI, deinen Workspace besser zu verstehen und leistungsstarke Funktionen wie native Diff-Ansichten direkt im Editor zu aktivieren. -Derzeit wird als einzige IDE [Visual Studio Code](https://code.visualstudio.com/) sowie andere Editoren unterstützt, die VS Code-Erweiterungen unterstützen. +Derzeit wird als einzige IDE [Visual Studio Code](https://code.visualstudio.com/) sowie andere Editoren unterstützt, die VS Code-Erweiterungen nutzen können. ## Funktionen @@ -11,40 +11,40 @@ Derzeit wird als einzige IDE [Visual Studio Code](https://code.visualstudio.com/ - 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. +- **Native Diff-Ansicht:** Wenn Qwen Code-Änderungen vorschlägt, kannst du die Änderungen direkt in der nativen Diff-Ansicht deiner IDE betrachten. So kannst du die vorgeschlagenen Änderungen nahtlos überprüfen, bearbeiten und entweder annehmen oder ablehnen. -- **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. +- **VS Code Commands:** Du kannst direkt über die VS Code Command Palette (`Cmd+Shift+P` oder `Ctrl+Shift+P`) auf die Funktionen von Qwen Code zugreifen: + - `Qwen Code: Run`: Startet eine neue Qwen Code-Sitzung im integrierten Terminal. + - `Qwen Code: Accept Diff`: Übernimmt die Änderungen im aktiven Diff-Editor. + - `Qwen Code: Close Diff Editor`: Lehnt die Änderungen ab und schließt den aktiven Diff-Editor. + - `Qwen Code: View Third-Party Notices`: Zeigt die Drittanbieter-Hinweise für die Erweiterung an. -## Installation und Einrichtung +## Installation und Setup Es gibt drei Möglichkeiten, die IDE-Integration einzurichten: -### 1. Automatischer Hinweis (Empfohlen) +### 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. +Wenn du Qwen Code in einem unterstützten Editor ausführst, erkennt es automatisch deine Umgebung und fordert dich auf, eine Verbindung herzustellen. Wenn du mit "Ja" antwortest, wird das notwendige Setup automatisch ausgeführt, einschließlich der Installation der Companion-Erweiterung und der Aktivierung der Verbindung. ### 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: +Falls du die Aufforderung zuvor abgelehnt hast oder die Erweiterung manuell installieren möchtest, kannst du den folgenden Befehl innerhalb von Qwen Code ausführen: ``` /ide install ``` -Dieser Befehl findet die richtige Extension für deine IDE und installiert sie. +Dadurch wird die richtige Erweiterung für deine IDE gefunden und installiert. ### 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. +- **Für Visual Studio Code:** Installiere sie über den [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion). +- **Für VS Code Forks:** Um Forks von VS Code zu unterstützen, ist die Extension auch im [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion) veröffentlicht. Befolge die Anweisungen deines Editors, um Extensions aus diesem Registry zu installieren. -Nach jeder Installationsmethode wird empfohlen, ein neues Terminal-Fenster zu öffnen, um sicherzustellen, dass die Integration korrekt aktiviert ist. Sobald die Installation abgeschlossen ist, kannst du `/ide enable` verwenden, um dich zu verbinden. +Nach jeder Installationsmethode wird empfohlen, ein neues Terminal-Fenster zu öffnen, um sicherzustellen, dass die Integration korrekt aktiviert wird. Sobald die Installation abgeschlossen ist, kannst du `/ide enable` verwenden, um dich zu verbinden. ## Verwendung @@ -52,45 +52,45 @@ Nach jeder Installationsmethode wird empfohlen, ein neues Terminal-Fenster zu ö Du kannst die IDE-Integration direkt über die CLI steuern: -- Um die Verbindung zur IDE zu aktivieren, führe aus: +- Um die Verbindung zur IDE zu aktivieren, führe folgenden Befehl aus: ``` /ide enable ``` -- Um die Verbindung zu deaktivieren, führe aus: +- Um die Verbindung zu deaktivieren, führe folgenden Befehl aus: ``` /ide disable ``` -Wenn aktiviert, wird der Gemini CLI automatisch versuchen, sich mit der IDE-Companion-Erweiterung zu verbinden. +Wenn die Verbindung aktiviert ist, wird Qwen Code 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: +Um den Verbindungsstatus zu überprüfen und den Kontext anzuzeigen, den die CLI von der IDE erhalten hat, führe folgenden Befehl 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. +Falls eine Verbindung besteht, zeigt dieser Befehl die IDE an, mit der die Verbindung besteht, sowie eine Liste der zuletzt geöffneten Dateien, die bekannt sind. -(Hinweis: Die Dateiliste ist auf 10 zuletzt aufgerufene Dateien innerhalb deines Workspaces beschränkt und enthält nur lokale Dateien auf der Festplatte.) +(Hinweis: Die Dateiliste ist auf 10 zuletzt geöffnete 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: +**Um einen Diff zu akzeptieren**, kannst du eine der folgenden Aktionen durchführen: - Klicke auf das **Häkchen-Symbol** in der Titelleiste des Diff-Editors. - Speichere die Datei (z. B. mit `Cmd+S` oder `Ctrl+S`). -- Öffne die Command Palette und führe **Gemini CLI: Accept Diff** aus. +- Öffne die Command Palette und führe **Qwen Code: Accept Diff** aus. - Antworte mit `yes` in der CLI, wenn du dazu aufgefordert wirst. -**Um ein Diff abzulehnen**, kannst du: +**Um einen Diff abzulehnen**, kannst du: - Klicke auf das **'x'-Symbol** in der Titelleiste des Diff-Editors. - Schließe den Diff-Editor-Tab. -- Öffne die Command Palette und führe **Gemini CLI: Close Diff Editor** aus. +- Öffne die Command Palette und führe **Qwen Code: Close Diff Editor** aus. - Antworte mit `no` in der CLI, wenn du dazu aufgefordert wirst. Du kannst auch **die vorgeschlagenen Änderungen direkt in der Diff-Ansicht anpassen**, bevor du sie akzeptierst. @@ -99,21 +99,21 @@ Wenn du in der CLI „Yes, allow always“ auswählst, werden die Änderungen ni ## Verwendung mit Sandboxing -Wenn du das Gemini CLI innerhalb einer Sandbox verwendest, beachte bitte Folgendes: +Wenn du Qwen Code innerhalb einer Sandbox verwendest, beachte bitte Folgendes: - **Unter macOS:** Die IDE-Integration benötigt Netzwerkzugriff, um mit der IDE-Begleiter-Erweiterung zu kommunizieren. Du musst ein Seatbelt-Profil verwenden, das den Netzwerkzugriff erlaubt. -- **In einem Docker-Container:** Wenn du 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. +- **In einem Docker-Container:** Wenn du Qwen Code innerhalb eines Docker- (oder Podman-) Containers ausführst, kann die IDE-Integration dennoch eine Verbindung zur VS Code-Erweiterung auf deinem Host-Rechner herstellen. Die CLI ist so konfiguriert, dass sie automatisch den IDE-Server unter `host.docker.internal` findet. Normalerweise ist keine spezielle Konfiguration erforderlich, aber du solltest sicherstellen, dass dein Docker-Netzwerksetup Verbindungen vom Container zum Host zulässt. ## Fehlerbehebung -Falls du Probleme mit der IDE-Integration hast, findest du hier einige häufige Fehlermeldungen und deren Lösungen. +Falls Probleme mit der IDE-Integration auftreten, findest du hier einige häufige Fehlermeldungen und deren Lösungen. ### Verbindungsfehler - **Nachricht:** `🔴 Disconnected: Failed to connect to IDE companion extension for [IDE Name]. Please ensure the extension is running and try restarting your terminal. To install the extension, run /ide install.` - - **Ursache:** 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. + - **Ursache:** Qwen Code konnte die notwendigen Umgebungsvariablen (`QWEN_CODE_IDE_WORKSPACE_PATH` oder `QWEN_CODE_IDE_SERVER_PORT`) nicht finden, um sich mit der IDE zu verbinden. Das bedeutet in der Regel, dass die IDE-Begleiter-Extension nicht läuft oder nicht korrekt initialisiert wurde. - **Lösung:** - 1. Stelle sicher, dass du die **Gemini CLI Companion** Extension in deiner IDE installiert hast und diese aktiviert ist. + 1. Stelle sicher, dass du die **Qwen Code Companion**-Extension in deiner IDE installiert hast und diese aktiviert ist. 2. Öffne ein neues Terminalfenster in deiner IDE, um sicherzustellen, dass die korrekten Umgebungsvariablen übernommen werden. - **Nachricht:** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` @@ -122,20 +122,20 @@ Falls du Probleme mit der IDE-Integration hast, findest du hier einige häufige ### 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.` +- **Meldung:** `🔴 Disconnected: Directory mismatch. Qwen Code is running in a different location than the open workspace in [IDE Name]. Please run the CLI from the same directory as your project's root folder.` - **Ursache:** Das aktuelle Arbeitsverzeichnis der CLI befindet sich außerhalb des Ordners oder Workspaces, der in deiner IDE geöffnet ist. - **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. + - **Ursache:** Du hast entweder mehrere Workspace-Ordner in deiner IDE geöffnet oder es ist überhaupt kein Ordner geöffnet. Die IDE-Integration benötigt einen einzelnen Root-Workspace-Ordner, um korrekt zu funktionieren. - **Lösung:** Öffne einen einzelnen Projektordner in deiner IDE und starte die CLI neu. ### 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. +- **Meldung:** `IDE-Integration wird in Ihrer aktuellen Umgebung nicht unterstützt. Um diese Funktion zu nutzen, führen Sie Qwen Code in einer der folgenden unterstützten IDEs aus: [Liste der IDEs]` + - **Ursache:** Sie führen Qwen Code in einem Terminal oder einer Umgebung aus, die keine unterstützte IDE ist. + - **Lösung:** Führen Sie Qwen Code aus dem integrierten Terminal einer unterstützten IDE wie VS Code aus. -- **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 +- **Meldung:** `Für [IDE Name] ist kein Installer verfügbar. Bitte installieren Sie den IDE-Companion manuell über den Marketplace der IDE.` + - **Ursache:** Sie haben `/ide install` ausgeführt, aber die CLI verfügt über keinen automatisierten Installer für Ihre spezifische IDE. + - **Lösung:** Öffnen Sie den Extension-Marketplace Ihrer IDE, suchen Sie nach "Qwen Code Companion" und installieren Sie die Erweiterung manuell. \ No newline at end of file diff --git a/website/content/de/index.md b/website/content/de/index.md index d1928f41..c3acd31a 100644 --- a/website/content/de/index.md +++ b/website/content/de/index.md @@ -4,14 +4,14 @@ Diese Dokumentation bietet einen umfassenden Leitfaden zur Installation, Verwend ## Übersicht -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. +Qwen Code bringt die Fähigkeiten fortschrittlicher Code-Modelle in dein Terminal, in Form einer interaktiven Read-Eval-Print Loop (REPL)-Umgebung. Qwen Code besteht aus einer clientseitigen Anwendung (`packages/cli`), die mit einem lokalen Server (`packages/core`) kommuniziert. Qwen Code enthält außerdem verschiedene Tools für Aufgaben wie Dateisystemoperationen, Shell-Befehle ausführen und Web-Anfragen, welche vom `packages/core` verwaltet werden. ## 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übersicht](./architecture.md):** Verständnis des High-Level-Designs von Qwen Code, einschließlich seiner Komponenten und deren Interaktion. +- **[Architektur-Überblick](./architecture.md):** Verständnis des High-Level-Designs von Qwen Code, einschließlich seiner Komponenten und deren Interaktion. - **CLI Usage:** Dokumentation für `packages/cli`. - **[CLI Einführung](./cli/index.md):** Übersicht über das Command-Line Interface. - **[Befehle](./cli/commands.md):** Beschreibung der verfügbaren CLI-Befehle. @@ -19,21 +19,22 @@ Diese Dokumentation ist in folgende Abschnitte unterteilt: - **[Checkpointing](./checkpointing.md):** Dokumentation zur Checkpointing-Funktion. - **[Erweiterungen](./extension.md):** Wie du die CLI mit neuer Funktionalität erweiterst. - **[IDE-Integration](./ide-integration.md):** Verbinde die CLI mit deinem Editor. - - **[Telemetrie](./telemetry.md):** Übersicht über die Telemetrie in der CLI. + - **[Telemetrie](./telemetry.md):** Übersicht zur Telemetrie in der CLI. - **Core Details:** Dokumentation für `packages/core`. - **[Core Einführung](./core/index.md):** Übersicht über die Core-Komponente. - - **[Tools API](./core/tools-api.md):** Informationen darüber, wie der Core Tools verwaltet und bereitstellt. + - **[Tools API](./core/tools-api.md):** Informationen dazu, 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 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. + - **[Dateisystem-Tools](./tools/file-system.md):** Dokumentation zu den `read_file` und `write_file` Tools. + - **[Multi-File Read Tool](./tools/multi-file.md):** Dokumentation zum `read_many_files` Tool. + - **[Shell Tool](./tools/shell.md):** Dokumentation zum `run_shell_command` Tool. + - **[Web Fetch Tool](./tools/web-fetch.md):** Dokumentation zum `web_fetch` Tool. + - **[Web Search Tool](./tools/web-search.md):** Dokumentation zum `web_search` Tool. + - **[Memory Tool](./tools/memory.md):** Dokumentation zum `save_memory` Tool. +- **[Subagents](./subagents.md):** Spezialisierte KI-Assistenten für fokussierte Aufgaben mit umfassender Verwaltung, Konfiguration und Nutzungshinweisen. - **[Beitragen & Entwicklerhandbuch](../CONTRIBUTING.md):** Informationen für Mitwirkende und Entwickler, inklusive Setup, Build-Prozess, Tests und Coding-Konventionen. - **[NPM Workspaces und Publishing](./npm.md):** Details zur Verwaltung und Veröffentlichung der Projekt-Pakete. - **[Fehlerbehebung](./troubleshooting.md):** Lösungen für häufige Probleme und FAQs. -- **[Nutzungsbedingungen und Datenschutzhinweise](./tos-privacy.md):** Informationen zu den Nutzungsbedingungen und Datenschutzbestimmungen für die Nutzung von Qwen Code. +- **[Nutzungsbedingungen und Datenschutzhinweise](./tos-privacy.md):** Informationen zu den Nutzungsbedingungen und Datenschutzbestimmungen bei der 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/keyboard-shortcuts.md b/website/content/de/keyboard-shortcuts.md index d7c6bcd1..e56a6e6b 100644 --- a/website/content/de/keyboard-shortcuts.md +++ b/website/content/de/keyboard-shortcuts.md @@ -7,41 +7,41 @@ Dieses Dokument listet die verfügbaren Tastaturkürzel in Qwen Code auf. | Shortcut | Beschreibung | | -------- | --------------------------------------------------------------------------------------------------------------------- | | `Esc` | Schließt Dialoge und Vorschläge. | -| `Ctrl+C` | Beendet die Anwendung. Zweimal drücken zum Bestätigen. | -| `Ctrl+D` | Beendet die Anwendung, wenn die Eingabe leer ist. Zweimal drücken zum Bestätigen. | -| `Ctrl+L` | Löscht den Bildschirm. | +| `Ctrl+C` | Bricht die laufende Anfrage ab und leert die Eingabe. Zweimal drücken, um die Anwendung zu beenden. | +| `Ctrl+D` | Beendet die Anwendung, wenn die Eingabe leer ist. Zweimal drücken zur Bestätigung. | +| `Ctrl+L` | Leert den Bildschirm. | | `Ctrl+O` | Schaltet die Anzeige der Debug-Konsole um. | -| `Ctrl+S` | Ermöglicht die vollständige Ausgabe langer Responses, deaktiviert das Abschneiden. Verwende den Scrollback deines Terminals, um die gesamte Ausgabe zu sehen. | +| `Ctrl+S` | Ermöglicht die vollständige Ausgabe langer Antworten, deaktiviert das Abschneiden. Verwende den Scrollback deines Terminals, um die gesamte Ausgabe zu sehen. | | `Ctrl+T` | Schaltet die Anzeige der Tool-Beschreibungen um. | -| `Ctrl+Y` | Schaltet die Auto-Approval (YOLO-Modus) für alle Tool-Calls um. | +| `Ctrl+Y` | Schaltet die automatische Genehmigung (YOLO-Modus) für alle Tool-Aufrufe um. | ## Eingabeaufforderung -| Tastenkürzel | Beschreibung | +| Tastenkürzel | Beschreibung | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `!` | Shell-Modus umschalten, wenn die Eingabe leer ist. | | `\` (am Zeilenende) + `Enter` | Neue Zeile einfügen. | | `Pfeil nach unten` | Durch den Eingabeverlauf nach unten navigieren. | | `Enter` | Aktuelle Eingabe absenden. | -| `Meta+Delete` / `Ctrl+Delete` | Wort rechts vom Cursor löschen. | +| `Meta+Entf` / `Strg+Entf` | Wort rechts vom Cursor löschen. | | `Tab` | Aktuellen Vorschlag vervollständigen, falls vorhanden. | | `Pfeil nach oben` | Durch den Eingabeverlauf nach oben navigieren. | -| `Ctrl+A` / `Home` | Cursor an den Anfang der Zeile bewegen. | -| `Ctrl+B` / `Pfeil nach links` | Cursor ein Zeichen nach links bewegen. | -| `Ctrl+C` | Eingabeaufforderung leeren | -| `Ctrl+D` / `Delete` | Zeichen rechts vom Cursor löschen. | -| `Ctrl+E` / `End` | Cursor ans Ende der Zeile bewegen. | -| `Ctrl+F` / `Pfeil nach rechts` | Cursor ein Zeichen nach rechts bewegen. | -| `Ctrl+H` / `Backspace` | Zeichen links vom Cursor löschen. | -| `Ctrl+K` | Von der Cursorposition bis zum Ende der Zeile löschen. | -| `Ctrl+Pfeil nach links` / `Meta+Pfeil nach links` / `Meta+B` | Cursor ein Wort nach links bewegen. | -| `Ctrl+N` | Durch den Eingabeverlauf nach unten navigieren. | -| `Ctrl+P` | Durch den Eingabeverlauf nach oben navigieren. | -| `Ctrl+Pfeil nach rechts` / `Meta+Pfeil nach rechts` / `Meta+F` | Cursor ein Wort nach rechts bewegen. | -| `Ctrl+U` | Von der Cursorposition bis zum Anfang der Zeile löschen. | -| `Ctrl+V` | Inhalt der Zwischenablage einfügen. Wenn die Zwischenablage ein Bild enthält, wird dieses gespeichert und ein Verweis darauf in die Eingabe eingefügt. | -| `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace` | Wort links vom Cursor löschen. | -| `Ctrl+X` / `Meta+Enter` | Aktuelle Eingabe in einem externen Editor öffnen. | +| `Strg+A` / `Pos1` | Cursor an den Anfang der Zeile bewegen. | +| `Strg+B` / `Pfeil nach links` | Cursor ein Zeichen nach links bewegen. | +| `Strg+C` | Eingabeaufforderung leeren | +| `Strg+D` / `Entf` | Zeichen rechts vom Cursor löschen. | +| `Strg+E` / `Ende` | Cursor ans Ende der Zeile bewegen. | +| `Strg+F` / `Pfeil nach rechts` | Cursor ein Zeichen nach rechts bewegen. | +| `Strg+H` / `Rücktaste` | Zeichen links vom Cursor löschen. | +| `Strg+K` | Von der Cursorposition bis zum Ende der Zeile löschen. | +| `Strg+Pfeil nach links` / `Meta+Pfeil nach links` / `Meta+B` | Cursor ein Wort nach links bewegen. | +| `Strg+N` | Durch den Eingabeverlauf nach unten navigieren. | +| `Strg+P` | Durch den Eingabeverlauf nach oben navigieren. | +| `Strg+Pfeil nach rechts` / `Meta+Pfeil nach rechts` / `Meta+F` | Cursor ein Wort nach rechts bewegen. | +| `Strg+U` | Von der Cursorposition bis zum Anfang der Zeile löschen. | +| `Strg+V` | Inhalt der Zwischenablage einfügen. Wenn die Zwischenablage ein Bild enthält, wird dieses gespeichert und ein Verweis darauf in die Eingabe eingefügt. | +| `Strg+W` / `Meta+Rücktaste` / `Strg+Rücktaste` | Wort links vom Cursor löschen. | +| `Strg+X` / `Meta+Enter` | Aktuelle Eingabe in einem externen Editor öffnen. | ## Vorschläge @@ -59,4 +59,10 @@ Dieses Dokument listet die verfügbaren Tastaturkürzel in Qwen Code auf. | `Enter` | Auswahl bestätigen. | | `Up Arrow` / `k` | Auswahl nach oben bewegen. | | `1-9` | Eintrag über seine Nummer auswählen. | -| (mehrstellig) | Für Einträge mit Nummern größer 9 die Ziffernfolge schnell hintereinander drücken, um den entsprechenden Eintrag auszuwählen. | \ No newline at end of file +| (mehrere Ziffern) | Für Einträge mit Nummern größer 9 die Ziffernfolge schnell hintereinander drücken, um den entsprechenden Eintrag auszuwählen. | + +## IDE-Integration + +| Shortcut | Beschreibung | +| -------- | ------------------------------------- | +| `Ctrl+G` | Kontext-CLI anzeigen, die von der IDE empfangen wurde | \ No newline at end of file diff --git a/website/content/de/npm.md b/website/content/de/npm.md index 4a65d422..158968bb 100644 --- a/website/content/de/npm.md +++ b/website/content/de/npm.md @@ -1,12 +1,12 @@ -# Package-Übersicht +# Package Overview Dieses Monorepo enthält zwei Hauptpakete: `@qwen-code/qwen-code` und `@qwen-code/qwen-code-core`. ## `@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 funktionalitäten, die direkt mit dem User interagieren. +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. -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. +Wenn dieses Paket veröffentlicht wird, wird es in eine einzelne ausführbare Datei gebundled. Dieses Bundle enthält alle Abhängigkeiten des Pakets, inklusive `@qwen-code/qwen-code-core`. Das bedeutet, egal ob ein User 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. ## `@qwen-code/qwen-code-core` @@ -18,17 +18,17 @@ Dieses Package wird nicht gebundled. Bei der Veröffentlichung wird es als Stand Dieses Projekt folgt einem strukturierten Release-Prozess, um sicherzustellen, dass alle Packages korrekt versioniert und veröffentlicht werden. Der Prozess ist so weit wie möglich automatisiert. -## Wie man einen Release durchführt +## How To Release -Releases werden über den [release.yml](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) GitHub Actions Workflow verwaltet. Um einen manuellen Release für einen Patch oder Hotfix durchzuführen: +Releases werden über den [release.yml](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) GitHub Actions Workflow verwaltet. Um ein manuelles Release für einen Patch oder Hotfix durchzuführen: 1. Gehe zum **Actions**-Tab des Repositories. 2. Wähle den **Release**-Workflow aus der Liste aus. 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**: 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. + - **Ref**: Der Branch oder Commit-SHA, von dem aus released werden soll (standardmäßig `main`). + - **Dry Run**: Auf `true` belassen, um den Workflow zu testen, ohne ihn zu veröffentlichen, oder auf `false` setzen, um ein echtes Release durchzuführen. 5. Klicke auf **Run workflow**. ## Nightly Releases @@ -42,13 +42,13 @@ Jede Nacht um Mitternacht UTC wird der [Release-Workflow](https://github.com/Qwe 1. Checkt den neuesten Code aus dem `main`-Branch aus. 2. Installiert alle Abhängigkeiten. 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`). +4. Falls alle Tests erfolgreich sind, wird die nächste Nightly-Version 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 mit den Labels `bug` und `nightly-failure` erstellt. 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 erstellt, gekennzeichnet mit den Labels `bug` und `nightly-failure`. Das Issue enthält einen Link zum fehlgeschlagenen Workflow-Lauf, um das Debugging zu erleichtern. ### Wie man den Nightly Build verwendet @@ -58,51 +58,51 @@ 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.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. +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 entsprechend deinem Release. Sobald die Service-Account-Berechtigungen geklärt sind, wird dies ebenfalls auf GitHub 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 alles erledigt ist, solltest du folgende Schritte durchführen: +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 der Vorgang abgeschlossen ist, solltest du folgende Schritte durchführen: -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. +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 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@latest --version`, um zu validieren, dass der Push erfolgreich war, sofern 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@` - 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 sollte die Versionsänderung gemerged werden, und wann nicht? +## Wann führe ich den Versionswechsel zusammen – oder nicht? -Das oben beschriebene Muster zum Erstellen von Patch- oder Hotfix-Releases von aktuellen oder älteren Commits aus lässt das Repository in folgendem Zustand: +Das oben beschriebene Muster zum Erstellen von Patch- oder Hotfix-Releases von aktuellen oder älteren Commits aus lässt das Repository in folgendem Zustand zurück: -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). +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 nur die Versionsnummer-Änderung in der package.json (und anderen zugehörigen Dateien wie package-lock.json). -Diese Trennung ist gut. Sie hält den main Branch sauber von Release-spezifischen Versionsanhebungen, bis du dich entscheidest, sie zu mergen. +Diese Trennung ist gut. Sie hält den Verlauf deines main-Branch sauber von Release-spezifischen Versionsanhebungen, bis du dich entscheidest, sie zusammenzuführen. -Das ist die kritische Entscheidung, und sie hängt vollständig von der Art des Releases ab. +Das ist die entscheidende Frage, und sie hängt vollständig von der Art des Releases ab. ### Merge Back für Stable Patches und Hotfixes In den meisten Fällen solltest du den `release-` Branch zurück in `main` mergen, sobald du einen Stable Patch oder Hotfix releast. - Warum? Der Hauptgrund ist, dass die Version in der package.json des main Branches aktualisiert werden muss. Wenn du z. B. v1.2.1 von einem älteren Commit releast, aber den Versionsbump nie zurückmerge, wird deine package.json im main Branch weiterhin `"version": "1.2.0"` anzeigen. Der nächste Entwickler, der mit der Arbeit an der nächsten Feature-Release (z. B. v1.3.0) beginnt, wird von einer Codebasis ausgehen, die eine falsche, veraltete Versionsnummer enthält. Das führt zu Verwirrung und erfordert später manuelles Anpassen der Versionsnummer. -- Der Prozess: Nachdem der release-v1.2.1 Branch erstellt und das Paket erfolgreich veröffentlicht wurde, solltest du einen Pull Request öffnen, um release-v1.2.1 in main zu mergen. Dieser PR enthält nur einen einzigen Commit: `"chore: bump version to v1.2.1"`. Es ist eine saubere und einfache Integration, die deinen main Branch mit der zuletzt releasten Version synchron hält. +- Der Prozess: Nachdem der release-v1.2.1 Branch erstellt und das Paket erfolgreich veröffentlicht wurde, solltest du einen Pull Request öffnen, um release-v1.2.1 in den main Branch zu mergen. Dieser PR enthält nur einen einzigen Commit: `"chore: bump version to v1.2.1"`. Es ist eine saubere und einfache Integration, die deinen main Branch mit der zuletzt releasten Version synchron hält. -### NICHT Zurückführen für Pre-Releases (RC, Beta, Dev) +### NICHT zurückmergen für Pre-Releases (RC, Beta, Dev) -Release Branches für Pre-Releases werden in der Regel nicht zurück in `main` gemerged. +Release Branches für Pre-Releases werden in der Regel nicht in `main` zurückgemerged. - Warum? Pre-Release-Versionen (z. B. v1.3.0-rc.1, v1.3.0-rc.2) sind definitionsgemäß nicht stabil und nur temporär. Du willst den Verlauf deines main-Branches nicht mit einer Reihe von Versionsanpassungen für Release Candidates verschmutzen. Die package.json in main sollte die neueste stabile Release-Version widerspiegeln, nicht einen RC. -- Der Prozess: Der release-v1.3.0-rc.1-Branch wird erstellt, der Befehl `npm publish --tag rc` wird ausgeführt, und danach hat der Branch seinen Zweck erfüllt. Du kannst ihn einfach löschen. Der Code für den RC ist bereits in main (oder einem Feature-Branch) enthalten, sodass kein funktionaler Code verloren geht. Der Release-Branch war nur ein temporäres Transportmittel für die Versionsnummer. +- Der Prozess: Der release-v1.3.0-rc.1-Branch wird erstellt, der Befehl `npm publish --tag rc` ausgeführt, und danach hat der Branch seinen Zweck erfüllt. Du kannst ihn einfach löschen. Der Code für den RC ist bereits in main (oder einem Feature-Branch), daher geht kein funktionaler Code verloren. Der Release-Branch war nur ein temporäres Mittel, um die Versionsnummer zu transportieren. -## Lokales Testen und Validierung: Änderungen am Packaging- und Publishing-Prozess +## Lokales Testen und Validieren: Ä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. @@ -121,70 +121,67 @@ 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 Aktionen aus: +Dieser Befehl führt folgende Schritte aus: 1. Erstellt alle Pakete. 2. Führt alle Prepublish-Skripte aus. -3. Erzeugt die `.tgz`-Tarballs, die auf npm veröffentlicht würden. +3. Erstellt die Paket-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 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`). +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 Stammverzeichnis jedes Pakets erstellt (z. B. `packages/cli/qwen-code-0.1.6.tgz`). -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. +Durch das Durchführen eines Dry-Runs kannst du sicherstellen, dass deine Änderungen am Packaging-Prozess korrekt sind und dass 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. +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, das letztendlich auf NPM veröffentlicht wird. -Hier sind die wichtigsten Phasen: +Hier sind die wichtigsten Schritte: -### Phase 1: Pre-Release Sanity Checks und Versionierung +**Stage 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 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. +- Was passiert: Bevor Dateien verschoben werden, stellt der Prozess sicher, dass sich das Projekt in einem guten Zustand befindet. Dazu gehören 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. -### Phase 2: Kompilierung des Source Codes +**Stage 2: Kompilieren des Source Codes** -- **Was passiert**: Der TypeScript-Code in `packages/core/src` und `packages/cli/src` wird in JavaScript kompiliert. -- **Dateibewegung**: +- Was passiert: Der TypeScript-Code in `packages/core/src` und `packages/cli/src` wird in JavaScript kompiliert. +- Dateibewegung: - `packages/core/src/**/*.ts` → kompiliert zu → `packages/core/dist/` - `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. +- 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. -### Phase 3: Zusammenstellen des finalen, veröffentlichbaren Pakets +**Stage 3: Zusammenstellen des finalen, veröffentlichbaren Pakets** -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. +Dies ist die kritischste Phase, in der Dateien verschoben und in ihren finalen Zustand für die Veröffentlichung gebracht werden. Ein temporäres `bundle`-Verzeichnis wird im Projekt-Root erstellt, um den finalen Paketinhalt aufzunehmen. -#### 1. Transformation der `package.json` +1. **Die `package.json` wird transformiert:** + - 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": { "@qwen-code/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. -- **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. - - Sicherstellen, dass die Felder `bin`, `main` und `files` auf die korrekten Pfade innerhalb der finalen Paketstruktur zeigen. +2. **Das JavaScript-Bundle wird erstellt:** + - 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 ein ähnlicher Name). + - Warum: Dies erzeugt eine einzelne, optimierte Datei, die den gesamten benötigten Anwendungscode enthält. Es vereinfacht das Paket, da das Core-Package nicht mehr als separate Abhängigkeit auf NPM benötigt wird – sein Code ist jetzt direkt enthalten. -#### 2. Erstellen des JavaScript-Bundles +3. **Statische und unterstützende Dateien werden kopiert:** + - Was passiert: Wesentliche Dateien, die nicht Teil des Source Codes sind, aber für das korrekte Funktionieren oder die Beschreibung des Pakets benötigt werden, werden in das `bundle`-Verzeichnis kopiert. + - Dateibewegung: + - `README.md` → `bundle/README.md` + - `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 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. -- **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). -- **Warum**: Dies erzeugt eine einzelne, optimierte Datei, die den gesamten notwendigen Anwendungscode enthält. Es vereinfacht das Paket, da das Core-Package nicht mehr als separate Dependency auf NPM benötigt wird – sein Code ist jetzt direkt enthalten. +**Stage 4: Veröffentlichen auf NPM** -#### 3. Kopieren statischer und unterstützender Dateien - -- **Was passiert**: Wesentliche Dateien, die nicht Teil des Source Codes sind, aber für das korrekte Funktionieren oder die Beschreibung des Pakets benötigt werden, werden in das `bundle`-Verzeichnis kopiert. -- **Dateibewegung**: - - `README.md` → `bundle/README.md` - - `LICENSE` → `bundle/LICENSE` - - `packages/cli/src/utils/*.sb` (Sandbox-Profile) → `bundle/` -- **Warum**: - - 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. - -### 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 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. +- 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 heraus werden nur die Dateien hochgeladen, die wir sorgfältig in Stage 3 zusammengestellt haben. Dadurch wird verhindert, dass versehentlich Source Code, Testdateien oder Entwicklungs-Konfigurationen veröffentlicht werden – das Ergebnis ist ein sauberes und minimales Paket für die Nutzer. ### Zusammenfassung des Dateiflusses @@ -222,7 +219,7 @@ graph TD J --> G --> K ``` -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. +Dieser Prozess stellt sicher, dass das letztendlich veröffentlichte Artefakt ein gezielt erstelltes, sauberes und effizientes Abbild des Projekts ist – und nicht einfach eine direkte Kopie des Entwicklungs-Workspace. ## NPM Workspaces @@ -242,6 +239,6 @@ Dies teilt NPM mit, dass jeder Ordner innerhalb des `packages` Verzeichnisses ei ### Vorteile von Workspaces -- **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 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 +- **Vereinfachte Dependency-Verwaltung**: 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 Verlinkung**: 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 beliebigen Paketen 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 @qwen-code/qwen-code` verwenden. \ No newline at end of file diff --git a/website/content/de/subagents.md b/website/content/de/subagents.md new file mode 100644 index 00000000..00cb2a7c --- /dev/null +++ b/website/content/de/subagents.md @@ -0,0 +1,470 @@ +# Subagents + +Subagents sind spezialisierte KI-Assistenten, die bestimmte Arten von Aufgaben innerhalb von Qwen Code übernehmen. Sie ermöglichen es dir, gezielte Arbeiten an KI-Agenten zu delegieren, die mit aufgabenspezifischen Prompts, Tools und Verhaltensweisen konfiguriert sind. + +## Was sind Subagents? + +Subagents sind unabhängige KI-Assistenten, die: + +- **Spezialisierung auf bestimmte Aufgaben** - Jeder Subagent ist mit einem fokussierten System-Prompt für bestimmte Arbeitstypen konfiguriert +- **Separater Kontext** - Sie führen ihren eigenen Konversationsverlauf unabhängig von deinem Hauptchat +- **Kontrollierte Tool-Nutzung** - Du kannst festlegen, auf welche Tools jeder Subagent Zugriff hat +- **Autonome Arbeitsweise** - Sobald eine Aufgabe übergeben wurde, arbeiten sie eigenständig bis zur Fertigstellung oder zum Fehler +- **Detailliertes Feedback** - Du kannst ihren Fortschritt, die Tool-Nutzung und Ausführungsstatistiken in Echtzeit verfolgen + +## Hauptvorteile + +- **Task Specialization**: Erstelle Agents, die für bestimmte Workflows optimiert sind (Testing, Documentation, Refactoring, etc.) +- **Context Isolation**: Halte spezialisierte Arbeiten separat von deiner Hauptunterhaltung +- **Reusability**: Speichere und wiederverwende Agent-Konfigurationen über Projekte und Sessions hinweg +- **Controlled Access**: Beschränke, welche Tools jeder Agent aus Sicherheits- und Fokusgründen nutzen kann +- **Progress Visibility**: Überwache die Agent-Ausführung mit Echtzeit-Fortschrittsaktualisierungen + +## Wie Subagents funktionieren + +1. **Configuration**: Du erstellst Subagent-Konfigurationen, die ihr Verhalten, ihre Tools und System-Prompts definieren +2. **Delegation**: Die Haupt-KI kann automatisch Aufgaben an geeignete Subagents delegieren +3. **Execution**: Subagents arbeiten unabhängig und nutzen ihre konfigurierten Tools, um Aufgaben abzuschließen +4. **Results**: Sie liefern Ergebnisse und Ausführungsübersichten an die Hauptunterhaltung zurück + +## Erste Schritte + +### Schnellstart + +1. **Erstelle deinen ersten Subagenten**: + + ``` + /agents create + ``` + + Folge dem geführten Wizard, um einen spezialisierten Agenten zu erstellen. + +2. **Verwalte bestehende Agenten**: + + ``` + /agents manage + ``` + + Zeige und verwalte deine konfigurierten Subagenten. + +3. **Nutze Subagenten automatisch**: + Frage einfach die Haupt-KI, Aufgaben zu erledigen, die den Spezialisierungen deiner Subagenten entsprechen. Die KI wird automatisch die passende Arbeit delegieren. + +### Beispielhafte Nutzung + +``` +User: "Bitte schreibe umfassende Tests für das Authentifizierungsmodul" + +AI: Ich delegiere das an deinen Testing-Spezialisten-Subagenten. +[Delegiert an "testing-expert" Subagenten] +[Zeigt Fortschritt der Testerstellung in Echtzeit] +[Gibt fertige Testdateien und Ausführungsübersicht zurück] +``` + +## Verwaltung + +### CLI-Befehle + +Subagenten werden über den Slash-Befehl `/agents` und seine Unterbefehle verwaltet: + +#### `/agents create` + +Erstellt einen neuen Subagenten über einen geführten Schritt-für-Schritt-Wizard. + +**Verwendung:** + +``` +/agents create +``` + +#### `/agents manage` + +Öffnet einen interaktiven Management-Dialog zum Anzeigen und Verwalten vorhandener Subagents. + +**Verwendung:** + +``` +/agents manage +``` + +### Speicherorte + +Subagents werden als Markdown-Dateien an zwei Orten gespeichert: + +- **Projektebene**: `.qwen/agents/` (hat Vorrang) +- **Benutzerebene**: `~/.qwen/agents/` (Fallback) + +So kannst du sowohl projektspezifische Agents als auch persönliche Agents haben, die in allen Projekten funktionieren. + +### Dateiformat + +Subagents werden mithilfe von Markdown-Dateien mit YAML-Frontmatter konfiguriert. Dieses Format ist menschenlesbar und lässt sich einfach mit jedem Texteditor bearbeiten. + +#### Grundstruktur + +```markdown +--- +name: agent-name +description: Kurze Beschreibung, wann und wie dieser Agent verwendet wird +tools: tool1, tool2, tool3 # Optional +--- + +Der System-Prompt-Inhalt kommt hier hin. +Mehrere Absätze werden unterstützt. +Du kannst ${variable} Templating für dynamische Inhalte verwenden. +``` + +#### Beispielverwendung + +```markdown +--- +name: project-documenter +description: Erstellt Projektdokumentation und README-Dateien +--- + +Sie sind ein Dokumentationsspezialist für das ${project_name}-Projekt. + +Ihre Aufgabe: ${task_description} + +Arbeitsverzeichnis: ${current_directory} +Generiert am: ${timestamp} + +Konzentrieren Sie sich auf die Erstellung klarer, umfassender Dokumentation, die sowohl +neuen Mitwirkenden als auch Endbenutzern hilft, das Projekt zu verstehen. +``` + +## Beispiele + +### Development Workflow Agents + +#### Testing Specialist + +Perfekt für umfassende Testerstellung und testgetriebene Entwicklung. + +```markdown +--- +name: testing-expert +description: Schreibt umfassende Unit-Tests, Integrationstests und behandelt Testautomatisierung mit Best Practices +tools: read_file, write_file, read_many_files, run_shell_command +--- + +Du bist ein Testing-Spezialist, der sich auf die Erstellung hochwertiger, wartbarer Tests konzentriert. + +Deine Expertise umfasst: + +- Unit-Testing mit geeignetem Mocking und Isolation +- Integrationstests für Komponenten-Interaktionen +- Testgetriebene Entwicklung (TDD) +- Identifizierung von Edge Cases und umfassende Abdeckung +- Performance- und Lasttests, wenn angebracht + +Für jede Testing-Aufgabe: + +1. Analysiere die Code-Struktur und Abhängigkeiten +2. Identifiziere Kernfunktionalitäten, Edge Cases und Fehlerbedingungen +3. Erstelle umfassende Testsuiten mit beschreibenden Namen +4. Integriere korrektes Setup/Teardown und aussagekräftige Assertions +5. Füge Kommentare für komplexe Testszenarien hinzu +6. Stelle sicher, dass Tests wartbar sind und DRY-Prinzipien befolgen + +Halte dich immer an die Best Practices für die erkannte Sprache und das Framework. +Fokussiere dich sowohl auf positive als auch negative Testfälle. +``` + +**Anwendungsfälle:** + +- "Schreibe Unit-Tests für den Authentication Service" +- "Erstelle Integrationstests für den Payment Processing Workflow" +- "Füge Testabdeckung für Edge Cases im Data Validation Modul hinzu" + +#### Documentation Writer + +Spezialisiert auf das Erstellen von klaren, umfassenden Dokumentationen. + +```markdown +--- +name: documentation-writer +description: Erstellt umfassende Dokumentationen, README-Dateien, API-Docs und Benutzerhandbücher +tools: read_file, write_file, read_many_files, web_search +--- + +Du bist ein technischer Dokumentationsspezialist für ${project_name}. + +Deine Aufgabe ist es, klare und umfassende Dokumentationen zu erstellen, die sowohl +Entwickler als auch Endnutzer ansprechen. Konzentriere dich auf: + +**Für API-Dokumentationen:** + +- Klare Endpoint-Beschreibungen mit Beispielen +- Detaillierte Parameterbeschreibungen inkl. Typen und Einschränkungen +- Dokumentation der Response-Formate +- Erläuterung der Fehlercodes +- Authentifizierungsanforderungen + +**Für Benutzerdokumentationen:** + +- Schritt-für-Schritt-Anleitungen, ggf. mit Screenshots +- Installations- und Setup-Anleitungen +- Konfigurationsoptionen und Beispiele +- Abschnitte zur Fehlerbehebung bei häufigen Problemen +- FAQ-Bereiche basierend auf typischen Benutzerfragen + +**Für Entwicklerdokumentationen:** + +- Architekturüberblick und Designentscheidungen +- Funktionierende Codebeispiele +- Richtlinien für Beiträge (Contributing Guidelines) +- Einrichtung der Entwicklungsumgebung + +Überprüfe immer die Codebeispiele und stelle sicher, dass die Dokumentation +mit der tatsächlichen Implementierung übereinstimmt. Nutze klare Überschriften, +Aufzählungen und Beispiele. +``` + +**Anwendungsfälle:** + +- "Erstelle eine API-Dokumentation für die User-Management-Endpoints" +- "Schreibe eine umfassende README für dieses Projekt" +- "Dokumentiere den Deployment-Prozess inkl. Troubleshooting-Schritten" + +#### Code Reviewer + +Fokussiert auf Codequalität, Sicherheit und Best Practices. + +```markdown +--- +name: code-reviewer +description: Reviews code for best practices, security issues, performance, and maintainability +tools: read_file, read_many_files +--- + +You are an experienced code reviewer focused on quality, security, and maintainability. + +Review criteria: + +- **Code Structure**: Organization, modularity, and separation of concerns +- **Performance**: Algorithmic efficiency and resource usage +- **Security**: Vulnerability assessment and secure coding practices +- **Best Practices**: Language/framework-specific conventions +- **Error Handling**: Proper exception handling and edge case coverage +- **Readability**: Clear naming, comments, and code organization +- **Testing**: Test coverage and testability considerations + +Provide constructive feedback with: + +1. **Critical Issues**: Security vulnerabilities, major bugs +2. **Important Improvements**: Performance issues, design problems +3. **Minor Suggestions**: Style improvements, refactoring opportunities +4. **Positive Feedback**: Well-implemented patterns and good practices + +Focus on actionable feedback with specific examples and suggested solutions. +Prioritize issues by impact and provide rationale for recommendations. +``` + +**Use Cases:** + +- "Review this authentication implementation for security issues" +- "Check the performance implications of this database query logic" +- "Evaluate the code structure and suggest improvements" + +### Technologie-Spezifische Agents + +#### React Specialist + +Optimiert für React-Entwicklung, Hooks und Komponentenmuster. + +```markdown +--- +name: react-specialist +description: Experte in React-Entwicklung, Hooks, Komponentenmustern und modernen React-Best-Practices +tools: read_file, write_file, read_many_files, run_shell_command +--- + +Du bist ein React-Spezialist mit tiefgreifender Expertise in moderner React-Entwicklung. + +Deine Expertise umfasst: + +- **Komponentendesign**: Funktionale Komponenten, Custom Hooks, Kompositions-Muster +- **State Management**: useState, useReducer, Context API und externe Libraries +- **Performance**: React.memo, useMemo, useCallback, Code Splitting +- **Testing**: React Testing Library, Jest, Strategien zum Testen von Komponenten +- **TypeScript-Integration**: Korrekte Typisierung von Props, Hooks und Komponenten +- **Moderne Muster**: Suspense, Error Boundaries, Concurrent Features + +Für React-Aufgaben: + +1. Verwende standardmäßig funktionale Komponenten und Hooks +2. Implementiere korrekte TypeScript-Typisierung +3. Folge React-Best-Practices und Konventionen +4. Berücksichtige Performance-Auswirkungen +5. Integriere angemessenes Error Handling +6. Schreibe testbaren und wartbaren Code + +Bleibe immer auf dem neuesten Stand der React-Best-Practices und vermeide veraltete Muster. +Fokussiere dich auf Barrierefreiheit und Aspekte der Benutzererfahrung. +``` + +**Anwendungsfälle:** + +- "Erstelle eine wiederverwendbare Data-Table-Komponente mit Sortierung und Filterung" +- "Implementiere einen Custom Hook für API-Datenabruf mit Caching" +- "Refaktoriere diese Klassenkomponente, um moderne React-Muster zu verwenden" + +#### Python-Experte + +Spezialisiert auf Python-Entwicklung, Frameworks und Best Practices. + +```markdown +--- +name: python-expert +description: Experte für Python-Entwicklung, Frameworks, Testing und Python-spezifische Best Practices +tools: read_file, write_file, read_many_files, run_shell_command +--- + +Du bist ein Python-Experte mit tiefem Wissen über das Python-Ökosystem. + +Deine Expertise umfasst: + +- **Core Python**: Pythonic Patterns, Datenstrukturen, Algorithmen +- **Frameworks**: Django, Flask, FastAPI, SQLAlchemy +- **Testing**: pytest, unittest, Mocking, test-driven development +- **Data Science**: pandas, numpy, matplotlib, Jupyter Notebooks +- **Async Programming**: asyncio, async/await Patterns +- **Package Management**: pip, poetry, Virtual Environments +- **Code Quality**: PEP 8, Type Hints, Linting mit pylint/flake8 + +Für Python-Aufgaben: + +1. Befolge die PEP 8 Style Guidelines +2. Verwende Type Hints für bessere Code-Dokumentation +3. Implementiere korrektes Error Handling mit spezifischen Exceptions +4. Schreibe umfassende Docstrings +5. Berücksichtige Performance und Speicherverbrauch +6. Integriere angemessenes Logging +7. Schreibe testbaren, modularen Code + +Fokus auf sauberen, wartbaren Python-Code, der Community-Standards entspricht. +``` + +**Anwendungsfälle:** + +- "Erstelle einen FastAPI-Service für User Authentication mit JWT Tokens" +- "Implementiere eine Datenverarbeitungs-Pipeline mit pandas und Error Handling" +- "Schreibe ein CLI-Tool mit argparse und umfassender Hilfe-Dokumentation" + +## Best Practices + +### Design Principles + +#### Single Responsibility Principle + +Jeder Subagent sollte eine klare, fokussierte Aufgabe haben. + +**✅ Gut:** + +```markdown +--- +name: testing-expert +description: Writes comprehensive unit tests and integration tests +--- +``` + +**❌ Vermeiden:** + +```markdown +--- +name: general-helper +description: Helps with testing, documentation, code review, and deployment +--- +``` + +**Warum:** Fokussierte Agents liefern bessere Ergebnisse und sind einfacher zu warten. + +#### Klare Spezialisierung + +Definiere spezifische Expertise-Bereiche statt allgemeiner Fähigkeiten. + +**✅ Gut:** + +```markdown +--- +name: react-performance-optimizer +description: Optimizes React applications for performance using profiling and best practices +--- +``` + +**❌ Vermeiden:** + +```markdown +--- +name: frontend-developer +description: Works on frontend development tasks +--- +``` + +**Warum:** Spezifische Expertise führt zu gezielterer und effektiverer Unterstützung. + +#### Actionable Descriptions + +Schreibe Beschreibungen, die klar angeben, wann der Agent verwendet werden soll. + +**✅ Gut:** + +```markdown +description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns +``` + +**❌ Vermeiden:** + +```markdown +description: A helpful code reviewer +``` + +**Warum:** Klare Beschreibungen helfen der Haupt-KI dabei, den richtigen Agenten für jede Aufgabe auszuwählen. + +### Configuration Best Practices + +#### Richtlinien für System Prompts + +**Sei spezifisch bezüglich der Expertise:** + +```markdown +You are a Python testing specialist with expertise in: + +- pytest framework and fixtures +- Mock objects and dependency injection +- Test-driven development practices +- Performance testing with pytest-benchmark +``` + +**Füge schrittweise Herangehensweisen hinzu:** + +```markdown +For each testing task: + +1. Analyze the code structure and dependencies +2. Identify key functionality and edge cases +3. Create comprehensive test suites with clear naming +4. Include setup/teardown and proper assertions +5. Add comments explaining complex test scenarios +``` + +**Lege die Ausgabestandards fest:** + +```markdown +Always follow these standards: + +- Use descriptive test names that explain the scenario +- Include both positive and negative test cases +- Add docstrings for complex test functions +- Ensure tests are independent and can run in any order +``` + +## Sicherheitsaspekte + +- **Tool-Einschränkungen**: Subagents haben nur Zugriff auf ihre konfigurierten Tools +- **Sandboxing**: Die Ausführung aller Tools folgt demselben Sicherheitsmodell wie die direkte Tool-Nutzung +- **Audit Trail**: Alle Aktionen von Subagents werden protokolliert und in Echtzeit sichtbar +- **Zugriffskontrolle**: Die Trennung auf Projekt- und Benutzerebene sorgt für angemessene Grenzen +- **Sensible Informationen**: Vermeide es, Secrets oder Zugangsdaten in Agent-Konfigurationen einzubeziehen +- **Produktionsumgebungen**: Erwäge den Einsatz separater Agents für Produktions- und Entwicklungs-Umgebungen \ No newline at end of file diff --git a/website/content/de/telemetry.md b/website/content/de/telemetry.md index d4bef670..a926cc19 100644 --- a/website/content/de/telemetry.md +++ b/website/content/de/telemetry.md @@ -1,8 +1,8 @@ # Qwen Code Observability Guide -Telemetry liefert Daten über die Performance, den Zustand und die Nutzung von Qwen Code. Durch die Aktivierung kannst du Abläufe überwachen, Probleme debuggen und die Tool-Nutzung mithilfe von Traces, Metriken und strukturierten Logs optimieren. +Telemetry liefert Daten über die Performance, den Zustand und die Nutzung von Qwen Code. Wenn du es aktivierst, kannst du Abläufe überwachen, Probleme debuggen und die Tool-Nutzung über Traces, Metriken und strukturierte Logs optimieren. -Das Telemetriesystem von Qwen Code basiert auf dem **[OpenTelemetry] (OTEL)**-Standard und ermöglicht dir, Daten an jedes kompatible Backend zu senden. +Das Telemetriesystem von Qwen Code basiert auf dem **[OpenTelemetry] (OTEL)**-Standard, wodurch du Daten an jedes kompatible Backend senden kannst. [OpenTelemetry]: https://opentelemetry.io/ @@ -10,9 +10,9 @@ Das Telemetriesystem von Qwen Code basiert auf dem **[OpenTelemetry] (OTEL)**-St Du kannst Telemetrie auf verschiedene Arten aktivieren. Die Konfiguration erfolgt hauptsächlich über die [`.qwen/settings.json`-Datei](./cli/configuration.md) und Umgebungsvariablen, aber CLI-Flags können diese Einstellungen für eine bestimmte Sitzung überschreiben. -### Rangfolge +### Reihenfolge der Priorität -Die folgende Liste zeigt die Rangfolge für die Anwendung der Telemetrie-Einstellungen, wobei Einträge weiter oben eine höhere Priorität haben: +Die folgende Liste zeigt die Priorität beim Anwenden der Telemetrie-Einstellungen, wobei Einträge weiter oben eine höhere Priorität haben: 1. **CLI-Flags (für den `qwen`-Befehl):** - `--telemetry` / `--no-telemetry`: Überschreibt `telemetry.enabled`. @@ -28,18 +28,18 @@ Die folgende Liste zeigt die Rangfolge für die Anwendung der Telemetrie-Einstel 1. **Benutzereinstellungsdatei (`~/.qwen/settings.json`):** Werte aus dem `telemetry`-Objekt in dieser globalen Benutzerdatei. -1. **Standardwerte:** Werden angewandt, wenn sie nicht durch eine der oben genannten Optionen gesetzt wurden. +1. **Standardwerte:** Werden angewandt, wenn sie nicht durch eine der oben genannten Quellen gesetzt wurden. - `telemetry.enabled`: `false` - `telemetry.target`: `local` - `telemetry.otlpEndpoint`: `http://localhost:4317` - `telemetry.logPrompts`: `true` **Für das Skript `npm run telemetry -- --target=`:** -Das `--target`-Argument dieses Skripts überschreibt _nur_ den `telemetry.target` für die Dauer und den Zweck dieses Skripts (d. h. zur Auswahl des zu startenden Collectors). Es ändert Ihre `settings.json` nicht dauerhaft. Das Skript prüft zunächst in der `settings.json`, ob ein `telemetry.target` als Standardwert vorhanden ist. +Das `--target`-Argument dieses Skripts überschreibt _nur_ den Wert von `telemetry.target` für die Dauer und den Zweck dieses Skripts (d. h. zur Auswahl des zu startenden Collectors). Es ändert nicht dauerhaft deine `settings.json`. Das Skript prüft zunächst in der `settings.json`, ob dort ein `telemetry.target` definiert ist, und verwendet diesen als Standardwert. ### Beispiel-Einstellungen -Der folgende Code kann zu deinen Workspace-Einstellungen (`.qwen/settings.json`) oder User-Einstellungen (`~/.qwen/settings.json`) hinzugefügt werden, um Telemetrie zu aktivieren und die Ausgabe an Google Cloud zu senden: +Der folgende Code kann in deine Workspace-Einstellungen (`.qwen/settings.json`) oder in deine User-Einstellungen (`~/.qwen/settings.json`) hinzugefügt werden, um Telemetrie zu aktivieren und die Ausgabe an Google Cloud zu senden: ```json { @@ -77,13 +77,16 @@ qwen --telemetry \ ## Einen OTEL Collector ausführen Ein OTEL Collector ist ein Service, der Telemetriedaten empfängt, verarbeitet und exportiert. -Die CLI sendet Daten über das OTLP/gRPC-Protokoll. +Die CLI kann Daten entweder über das OTLP/gRPC- oder OTLP/HTTP-Protokoll senden. +Du kannst festlegen, welches Protokoll verwendet werden soll, über das Flag `--telemetry-otlp-protocol` +oder die Einstellung `telemetry.otlpProtocol` in deiner `settings.json`-Datei. Weitere +Informationen findest du in der [Konfigurationsdokumentation](./cli/configuration.md#--telemetry-otlp-protocol). -Weitere Informationen zur Standardkonfiguration des OTEL Exporters findest du in der [Dokumentation][otel-config-docs]. +Weitere Informationen zur Standardkonfiguration von OTEL Exportern findest du in der [Dokumentation][otel-config-docs]. [otel-config-docs]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/ -### Lokal +### Local Verwende den Befehl `npm run telemetry -- --target=local`, um den Prozess zur Einrichtung einer lokalen Telemetrie-Pipeline zu automatisieren. Dazu gehört auch das Konfigurieren der erforderlichen Einstellungen in deiner `.qwen/settings.json`-Datei. Das zugrunde liegende Skript installiert `otelcol-contrib` (den OpenTelemetry Collector) und `jaeger` (das Jaeger UI zur Anzeige von Traces). So gehst du vor: @@ -94,18 +97,18 @@ Verwende den Befehl `npm run telemetry -- --target=local`, um den Prozess zur Ei npm run telemetry -- --target=local ``` - Das Skript wird: - - Jaeger und OTEL herunterladen, falls nötig. - - Eine lokale Jaeger-Instanz starten. - - Einen OTEL-Collector starten, der für den Empfang von Daten aus Qwen Code konfiguriert ist. - - Telemetrie automatisch in deinen Workspace-Einstellungen aktivieren. - - Beim Beenden die Telemetrie wieder deaktivieren. + Das Skript führt folgende Aktionen durch: + - Lädt Jaeger und OTEL herunter, falls erforderlich. + - Startet eine lokale Jaeger-Instanz. + - Startet einen OTEL-Collector, der für den Empfang von Daten aus Qwen Code konfiguriert ist. + - Aktiviert Telemetrie automatisch in deinen Workspace-Einstellungen. + - Deaktiviert beim Beenden die Telemetrie. 1. **Traces anzeigen**: Öffne deinen Webbrowser und navigiere zu **http://localhost:16686**, um auf das Jaeger UI zuzugreifen. Dort kannst du detaillierte Traces der Qwen Code-Vorgänge einsehen. 1. **Logs und Metriken prüfen**: - Das Skript leitet die Ausgabe des OTEL-Collectors (einschließlich Logs und Metriken) in die Datei `~/.qwen/tmp//otel/collector.log` um. Das Skript stellt dir Links zur Verfügung, um deine Telemetriedaten (Traces, Metriken, Logs) lokal anzusehen, sowie einen Befehl, um sie in Echtzeit zu verfolgen. + Das Skript leitet die Ausgabe des OTEL-Collectors (einschließlich Logs und Metriken) in die Datei `~/.qwen/tmp//otel/collector.log` um. Das Skript stellt Links zur Verfügung, um deine Telemetriedaten (Traces, Metriken, Logs) lokal anzusehen, sowie einen Befehl, um diese live im Terminal zu verfolgen. 1. **Dienste stoppen**: Drücke `Ctrl+C` im Terminal, in dem das Skript läuft, um den OTEL Collector und die Jaeger-Dienste zu stoppen. @@ -121,7 +124,7 @@ Verwende den Befehl `npm run telemetry -- --target=gcp`, um automatisch einen lo export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" ``` - Authentifiziere dich bei Google Cloud (z. B. mit `gcloud auth application-default login` oder stelle sicher, dass `GOOGLE_APPLICATION_CREDENTIALS` gesetzt ist). - - Stelle sicher, dass dein Google Cloud-Konto bzw. dein Service-Account über die erforderlichen IAM-Rollen verfügt: "Cloud Trace Agent", "Monitoring Metric Writer" und "Logs Writer". + - Stelle sicher, dass dein Google Cloud-Konto bzw. dein Service-Account über die erforderlichen IAM-Rollen verfügt: „Cloud Trace Agent“, „Monitoring Metric Writer“ und „Logs Writer“. 1. **Befehl ausführen**: Führe den Befehl im Root-Verzeichnis deines Repositorys aus: @@ -130,12 +133,12 @@ Verwende den Befehl `npm run telemetry -- --target=gcp`, um automatisch einen lo npm run telemetry -- --target=gcp ``` - Das Skript führt folgende Aktionen durch: - - Lädt bei Bedarf die `otelcol-contrib`-Binary herunter. - - Startet einen OTEL Collector, der so konfiguriert ist, dass er Daten von Qwen Code empfängt und an dein angegebenes Google Cloud-Projekt exportiert. - - Aktiviert automatisch Telemetrie und deaktiviert den Sandbox-Modus in deinen Workspace-Einstellungen (`.qwen/settings.json`). - - Stellt direkte Links bereit, um Traces, Metriken und Logs in der Google Cloud Console anzuzeigen. - - Beim Beenden (mit Strg+C) wird versucht, deine ursprünglichen Telemetrie- und Sandbox-Einstellungen wiederherzustellen. + Das Skript wird: + - Die Binary `otelcol-contrib` herunterladen (falls erforderlich). + - Einen OTEL Collector starten, der so konfiguriert ist, dass er Daten von Qwen Code empfängt und an dein angegebenes Google Cloud-Projekt exportiert. + - Telemetrie automatisch aktivieren und den Sandbox-Modus in deinen Workspace-Einstellungen (`.qwen/settings.json`) deaktivieren. + - Direkte Links bereitstellen, um Traces, Metriken und Logs in der Google Cloud Console anzuzeigen. + - Beim Beenden (Strg+C) versuchen, deine ursprünglichen Telemetrie- und Sandbox-Einstellungen wiederherzustellen. 1. **Qwen Code ausführen**: Führe in einem separaten Terminal deine Qwen Code-Befehle aus. Dadurch werden Telemetriedaten generiert, die vom Collector erfasst werden. @@ -144,12 +147,12 @@ Verwende den Befehl `npm run telemetry -- --target=gcp`, um automatisch einen lo Verwende die vom Skript bereitgestellten Links, um zur Google Cloud Console zu navigieren und deine Traces, Metriken und Logs einzusehen. 1. **Lokale Collector-Logs einsehen**: - Die Ausgabe des lokalen OTEL Collectors wird in `~/.qwen/tmp//otel/collector-gcp.log` umgeleitet. Das Skript stellt Links zur Verfügung, um die Logs lokal anzuzeigen oder mit einem Befehl zu verfolgen (tail). + Das Skript leitet die Ausgabe des lokalen OTEL Collectors in die Datei `~/.qwen/tmp//otel/collector-gcp.log` um. Es stellt auch Links und Befehle bereit, um die Logs lokal einzusehen oder zu tailen. 1. **Dienst stoppen**: Drücke `Strg+C` im Terminal, in dem das Skript läuft, um den OTEL Collector zu stoppen. -## Referenz zu Logs und Metriken +## Referenz für Logs und Metriken Der folgende Abschnitt beschreibt die Struktur der Logs und Metriken, die für Qwen Code generiert werden. @@ -191,7 +194,7 @@ Logs sind zeitgestempelte Aufzeichnungen spezifischer Ereignisse. Die folgenden - `error_type` (falls zutreffend) - `metadata` (falls zutreffend, Dictionary von string -> any) -- `qwen-code.api_request`: Dieses Ereignis tritt auf, wenn eine Anfrage an die Gemini API gesendet wird. +- `qwen-code.api_request`: Dieses Ereignis tritt auf, wenn eine Anfrage an die Qwen API gesendet wird. - **Attribute**: - `model` - `request_text` (falls zutreffend) @@ -205,7 +208,7 @@ Logs sind zeitgestempelte Aufzeichnungen spezifischer Ereignisse. Die folgenden - `duration_ms` - `auth_type` -- `qwen-code.api_response`: Dieses Ereignis tritt ein, wenn eine Antwort von der Gemini API empfangen wird. +- `qwen-code.api_response`: Dieses Ereignis tritt ein, wenn eine Antwort von der Qwen API empfangen wird. - **Attribute**: - `model` - `status_code` @@ -230,43 +233,49 @@ Logs sind zeitgestempelte Aufzeichnungen spezifischer Ereignisse. Die folgenden ### Metriken -Metriken sind numerische Messungen des Verhaltens über die Zeit. Die folgenden Metriken werden für Qwen Code gesammelt (Metriknamen bleiben aus Kompatibilitätsgründen `qwen-code.*`): +Metriken sind numerische Messungen des Verhaltens über die Zeit. Die folgenden Metriken werden für Qwen Code gesammelt (die Metriknamen bleiben aus Kompatibilitätsgründen `qwen-code.*`): -- `qwen-code.session.count` (Zähler, Int): Wird bei jedem CLI-Start um eins erhöht. +- `qwen-code.session.count` (Counter, Int): Wird bei jedem CLI-Start um eins erhöht. -- `qwen-code.tool.call.count` (Zähler, Int): Zählt die Tool-Aufrufe. +- `qwen-code.tool.call.count` (Counter, Int): Zählt die Tool-Aufrufe. - **Attribute**: - `function_name` - `success` (boolean) - `decision` (string: "accept", "reject" oder "modify", falls zutreffend) + - `tool_type` (string: "mcp" oder "native", falls zutreffend) -- `qwen-code.tool.call.latency` (Histogramm, ms): Misst die Latenz von Tool-Aufrufen. +- `qwen-code.tool.call.latency` (Histogram, ms): Misst die Latenz von Tool-Aufrufen. - **Attribute**: - `function_name` - `decision` (string: "accept", "reject" oder "modify", falls zutreffend) -- `qwen-code.api.request.count` (Zähler, Int): Zählt alle API-Anfragen. +- `qwen-code.api.request.count` (Counter, Int): Zählt alle API-Anfragen. - **Attribute**: - `model` - `status_code` - `error_type` (falls zutreffend) -- `qwen-code.api.request.latency` (Histogramm, ms): Misst die Latenz von API-Anfragen. +- `qwen-code.api.request.latency` (Histogram, ms): Misst die Latenz von API-Anfragen. - **Attribute**: - `model` -- `qwen-code.token.usage` (Zähler, Int): Zählt die Anzahl der verwendeten Tokens. +- `qwen-code.token.usage` (Counter, Int): Zählt die Anzahl der verwendeten Tokens. - **Attribute**: - `model` - `type` (string: "input", "output", "thought", "cache" oder "tool") -- `qwen-code.file.operation.count` (Zähler, Int): Zählt Dateioperationen. +- `qwen-code.file.operation.count` (Counter, Int): Zählt Dateioperationen. - **Attribute**: - - `operation` (string: "create", "read", "update"): Die Art der Dateioperation. + - `operation` (string: "create", "read", "update"): Der Typ der Dateioperation. - `lines` (Int, falls zutreffend): Anzahl der Zeilen in der Datei. - `mimetype` (string, falls zutreffend): Mimetype der Datei. - `extension` (string, falls zutreffend): Dateierweiterung der Datei. - `ai_added_lines` (Int, falls zutreffend): Anzahl der von der KI hinzugefügten/geänderten Zeilen. - `ai_removed_lines` (Int, falls zutreffend): Anzahl der von der KI entfernten/geänderten Zeilen. - - `user_added_lines` (Int, falls zutreffend): Anzahl der vom Benutzer hinzugefügten/geänderten Zeilen in von der KI vorgeschlagenen Änderungen. - - `user_removed_lines` (Int, falls zutreffend): Anzahl der vom Benutzer entfernten/geänderten Zeilen in von der KI vorgeschlagenen Änderungen. \ No newline at end of file + - `user_added_lines` (Int, falls zutreffend): Anzahl der vom Benutzer hinzugefügten/geänderten Zeilen in KI-vorgeschlagenen Änderungen. + - `user_removed_lines` (Int, falls zutreffend): Anzahl der vom Benutzer entfernten/geänderten Zeilen in KI-vorgeschlagenen Änderungen. + +- `qwen-code.chat_compression` (Counter, Int): Zählt Chat-Komprimierungsvorgänge. + - **Attribute**: + - `tokens_before` (Int): Anzahl der Tokens im Kontext vor der Komprimierung. + - `tokens_after` (Int): Anzahl der Tokens im Kontext nach der Komprimierung. \ No newline at end of file diff --git a/website/content/de/tools/file-system.md b/website/content/de/tools/file-system.md index 48667c5a..00617385 100644 --- a/website/content/de/tools/file-system.md +++ b/website/content/de/tools/file-system.md @@ -6,7 +6,7 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem loka ## 1. `list_directory` (ReadFolder) -`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. +`list_directory` listet die Namen von Dateien und Unterverzeichnissen direkt innerhalb eines angegebenen Verzeichnispfads auf. Es kann optional Einträge ignorieren, die bestimmten Glob-Mustern entsprechen. - **Tool-Name:** `list_directory` - **Anzeigename:** ReadFolder @@ -24,7 +24,7 @@ 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. Für 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. Bei Textdateien kann es bestimmte Zeilenbereiche lesen. Andere binäre Dateitypen werden in der Regel übersprungen. - **Tool-Name:** `read_file` - **Anzeigename:** ReadFile @@ -32,7 +32,7 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem loka - **Parameter:** - `path` (string, erforderlich): Der absolute Pfad zur zu lesenden Datei. - `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. + - `limit` (number, optional): Bei Textdateien die maximale Anzahl an Zeilen, die gelesen werden soll. Falls weggelassen, 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. @@ -45,7 +45,7 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem loka ## 3. `write_file` (WriteFile) -`write_file` schreibt Inhalte in eine angegebene Datei. Wenn die Datei bereits existiert, wird sie überschrieben. Falls die Datei nicht existiert, wird sie (samt notwendiger übergeordneter Verzeichnisse) erstellt. +`write_file` schreibt Inhalte in eine angegebene Datei. Wenn die Datei bereits existiert, wird sie überschrieben. Falls die Datei nicht existiert, wird sie (samt aller notwendigen übergeordneten Verzeichnisse) erstellt. - **Tool-Name:** `write_file` - **Anzeigename:** WriteFile @@ -57,22 +57,22 @@ 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 Nutzerbestätigung vor dem Schreiben an. +- **Bestätigung:** Ja. Zeigt einen Diff der Änderungen an und fordert die Nutzerbestätigung vor dem Schreibvorgang an. ## 4. `glob` (FindFiles) -`glob` findet Dateien, die bestimmten Glob-Patterns entsprechen (z. B. `src/**/*.ts`, `*.md`), und gibt absolute Pfade zurück, sortiert nach Änderungszeit (neueste zuerst). +`glob` sucht Dateien, die einem bestimmten Glob-Muster entsprechen (z. B. `src/**/*.ts`, `*.md`), und gibt absolute Pfade zurück, sortiert nach Änderungszeit (neueste zuerst). - **Tool-Name:** `glob` - **Anzeigename:** FindFiles - **Datei:** `glob.ts` - **Parameter:** - - `pattern` (string, erforderlich): Das Glob-Pattern, gegen das gematcht wird (z. B. `"*.py"`, `"src/**/*.js"`). + - `pattern` (string, erforderlich): Das Glob-Muster, gegen das abgeglichen wird (z. B. `"*.py"`, `"src/**/*.js"`). - `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`. + - `case_sensitive` (boolean, optional): Ob die Suche Groß-/Kleinschreibung berücksichtigen soll. Standardmäßig `false`. + - `respect_git_ignore` (boolean, optional): Ob `.gitignore`-Muster beim Suchen von Dateien berücksichtigt werden sollen. Standardmäßig `true`. - **Verhalten:** - - Sucht nach Dateien, die dem Glob-Pattern im angegebenen Verzeichnis entsprechen. + - Sucht nach Dateien, die dem Glob-Muster 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...` @@ -80,20 +80,20 @@ Qwen Code bietet eine umfassende Sammlung von Tools zur Interaktion mit dem loka ## 5. `search_file_content` (SearchText) -`search_file_content` sucht nach einem regulären Ausdruck (regex) innerhalb des Inhalts von Dateien in einem bestimmten Verzeichnis. Es können Dateien anhand eines Glob-Patterns gefiltert werden. Gibt die Zeilen mit Treffern sowie deren Dateipfade und Zeilennummern zurück. +`search_file_content` sucht nach einem regulären Ausdruck (Regex) innerhalb des Inhalts von Dateien in einem bestimmten Verzeichnis. Es können Dateien über ein Glob-Muster gefiltert werden. Gibt die Zeilen mit Treffern sowie deren Dateipfade und Zeilennummern zurück. - **Tool-Name:** `search_file_content` - **Anzeigename:** SearchText - **Datei:** `grep.ts` - **Parameter:** - - `pattern` (string, erforderlich): Der reguläre Ausdruck, nach dem gesucht werden soll (z. B. `"function\s+myFunction"`). + - `pattern` (string, erforderlich): Der reguläre Ausdruck (Regex), 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 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. + - `include` (string, optional): Ein Glob-Muster, 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 verhindern (Standard: 20, Max: 100). Verwende niedrigere Werte bei breiten Suchanfragen, höhere bei spezifischen. - **Verhalten:** - - 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. + - Verwendet `git grep`, falls verfügbar in einem Git-Repository, für bessere Geschwindigkeit; 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. - - 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. + - Begrenzt standardmäßig die Ergebnisse auf maximal 20 Treffer, um einen Kontextüberlauf zu vermeiden. 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.: ``` @@ -136,12 +136,12 @@ Suche nach einem Muster mit Dateifilterung und benutzerdefiniertem Limit für Er search_file_content(pattern="function", include="*.js", maxResults=10) ``` -## 6. `replace` (Editieren) +## 6. `edit` (Bearbeiten) -`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. +`edit` ersetzt Text innerhalb einer Datei. Standardmäßig wird nur eine einzelne Fundstelle ersetzt, aber es können auch mehrere Vorkommen ersetzt werden, wenn `expected_replacements` angegeben ist. 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. -- **Tool-Name:** `replace` -- **Anzeigename:** Edit +- **Tool-Name:** `edit` +- **Anzeigename:** Bearbeiten - **Datei:** `edit.ts` - **Parameter:** - `file_path` (string, erforderlich): Der absolute Pfad zur zu ändernden Datei. @@ -155,19 +155,19 @@ search_file_content(pattern="function", include="*.js", maxResults=10) - **Verhalten:** - 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 – 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 identifizieren, das das Modell eigentlich ändern wollte, wodurch die `replace`-Operation robuster wird, selbst bei leicht ungenauem Ausgangskontext. + - Wird genau ein Vorkommen gefunden, wird es 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. + - Wenn der ursprüngliche `old_string` nicht gefunden wird oder an mehreren Stellen vorkommt, kann das Tool das Qwen-Modell nutzen, um `old_string` (und gegebenenfalls auch `new_string`) iterativ zu verfeinern. + - Dieser Selbstkorrekturprozess versucht, das eindeutige Segment zu identifizieren, das das Modell ändern wollte, wodurch die `edit`-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. + - `file_path` kein absoluter Pfad ist oder sich außerhalb des Root-Verzeichnisses befindet. - `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 Übereinstimmung finden kann. + - `old_string` mehrfach vorkommt und der Selbstkorrekturmechanismus 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 Nutzer:in zur Bestätigung auf, bevor die Datei geschrieben wird. -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 +Diese Filesystem-Tools bilden die Grundlage dafür, dass Qwen Code dein lokales Projektverzeichnis verstehen und damit interagieren kann. \ No newline at end of file diff --git a/website/content/de/tools/mcp-server.md b/website/content/de/tools/mcp-server.md index 26c8027f..e8f88c1b 100644 --- a/website/content/de/tools/mcp-server.md +++ b/website/content/de/tools/mcp-server.md @@ -4,15 +4,15 @@ Dieses Dokument bietet eine Anleitung zur Konfiguration und Verwendung von Model ## Was ist ein MCP-Server? -Ein MCP-Server ist eine Anwendung, die Tools und Ressourcen über das Model Context Protocol für die CLI verfügbar macht, wodurch diese mit externen Systemen und Datenquellen interagieren kann. MCP-Server fungieren als Brücke zwischen dem Modell und deiner lokalen Umgebung oder anderen Services wie APIs. +Ein MCP-Server ist eine Anwendung, die über das Model Context Protocol Tools und Ressourcen für die CLI bereitstellt, sodass diese mit externen Systemen und Datenquellen interagieren kann. MCP-Server fungieren als Brücke zwischen dem Modell und deiner lokalen Umgebung oder anderen Services wie APIs. -Ein MCP-Server ermöglicht es der CLI: +Ein MCP-Server ermöglicht der CLI Folgendes: -- **Tools zu entdecken:** Verfügbare Tools, deren Beschreibungen und Parameter über standardisierte Schema-Definitionen aufzulisten. -- **Tools auszuführen:** Spezifische Tools mit definierten Argumenten aufzurufen und strukturierte Antworten zu erhalten. -- **Auf Ressourcen zuzugreifen:** Daten aus bestimmten Ressourcen zu lesen (wobei sich die CLI hauptsächlich auf die Tool-Ausführung konzentriert). +- **Tools entdecken:** Verfügbare Tools, deren Beschreibungen und Parameter über standardisierte Schema-Definitionen auflisten. +- **Tools ausführen:** Bestimmte Tools mit definierten Argumenten aufrufen und strukturierte Antworten erhalten. +- **Auf Ressourcen zugreifen:** Daten aus bestimmten Ressourcen lesen (wobei sich die CLI hauptsächlich auf die Tool-Ausführung konzentriert). -Mit einem MCP-Server kannst du die Fähigkeiten der CLI erweitern, um Aktionen jenseits der integrierten Funktionen durchzuführen, wie z. B. die Interaktion mit Datenbanken, APIs, benutzerdefinierten Skripten oder spezialisierten Workflows. +Mit einem MCP-Server kannst du die Fähigkeiten der CLI erweitern, um Aktionen auszuführen, die über die integrierten Funktionen hinausgehen, wie z. B. die Interaktion mit Datenbanken, APIs, benutzerdefinierten Skripten oder spezialisierten Workflows. ## Core Integration Architecture @@ -24,17 +24,17 @@ Der Discovery-Prozess wird von `discoverMcpTools()` orchestriert, welches: 1. **Durchläuft die konfigurierten Server** aus der `mcpServers`-Konfiguration in deiner `settings.json` 2. **Stellt Verbindungen her** unter Verwendung geeigneter Transportmechanismen (Stdio, SSE oder Streamable HTTP) -3. **Ruft Tool-Definitionen** von jedem Server über das MCP-Protokoll ab -4. **Bereinigt und validiert** die Tool-Schemas für die Kompatibilität mit der Gemini API +3. **Ruft Tool-Definitionen** von jedem Server mittels des MCP-Protokolls ab +4. **Bereinigt und validiert** die Tool-Schemas für die Kompatibilität mit der Qwen API 5. **Registriert Tools** im globalen Tool-Registry mit Konfliktlösung ### Execution Layer (`mcp-tool.ts`) Jedes gefundene MCP-Tool wird in eine `DiscoveredMCPTool`-Instanz verpackt, die: -- **Bestätigungslogik** basierend auf den Server-Vertrauenseinstellungen und Benutzerpräferenzen behandelt -- **Tool-Ausführung** verwaltet, indem der MCP-Server mit den richtigen Parametern aufgerufen wird -- **Antworten verarbeitet**, sowohl für den LLM-Kontext als auch für die Anzeige beim Benutzer +- **Bestätigungslogik behandelt** basierend auf den Server-Vertrauenseinstellungen und Benutzerpräferenzen +- **Tool-Ausführung verwaltet** durch Aufruf des MCP-Servers mit korrekten Parametern +- **Antworten verarbeitet** sowohl für den LLM-Kontext als auch für die Anzeige beim Benutzer - **Verbindungsstatus verwaltet** und Timeouts behandelt ### Transportmechanismen @@ -45,20 +45,20 @@ Die CLI unterstützt drei MCP-Transporttypen: - **SSE Transport:** Verbindet sich mit Server-Sent Events Endpoints - **Streamable HTTP Transport:** Nutzt HTTP-Streaming zur Kommunikation -## So richten Sie Ihren MCP-Server ein +## Wie du deinen MCP-Server einrichtest -Qwen Code verwendet die `mcpServers`-Konfiguration in Ihrer `settings.json`-Datei, um MCP-Server zu finden und sich mit ihnen zu verbinden. Diese Konfiguration unterstützt mehrere Server mit verschiedenen Transportmechanismen. +Qwen Code verwendet die `mcpServers`-Konfiguration in deiner `settings.json`-Datei, um MCP-Server zu finden und sich mit ihnen zu verbinden. Diese Konfiguration unterstützt mehrere Server mit unterschiedlichen Transportmechanismen. ### Konfiguriere den MCP-Server in settings.json -Du kannst MCP-Server global in der Datei `~/.qwen/settings.json` oder im Stammverzeichnis deines Projekts konfigurieren, indem du die Datei `.qwen/settings.json` erstellst oder öffnest. Füge in der Datei den Konfigurationsblock `mcpServers` hinzu. +Du kannst MCP-Server global in der Datei `~/.qwen/settings.json` oder im Stammverzeichnis deines Projekts konfigurieren, indem du die Datei `.qwen/settings.json` erstellst oder öffnest. Füge innerhalb der Datei den Konfigurationsblock `mcp_servers` hinzu. ### Konfigurationsstruktur Füge ein `mcpServers`-Objekt zu deiner `settings.json`-Datei hinzu: ```json -{ ...Datei enthält andere Konfigurationsobjekte +{ ...file contains other config objects "mcpServers": { "serverName": { "command": "path/to/server", @@ -76,9 +76,9 @@ Füge ein `mcpServers`-Objekt zu deiner `settings.json`-Datei hinzu: ### Konfigurationseigenschaften -Jede Serverkonfiguration unterstützt die folgenden Eigenschaften: +Jede Server-Konfiguration unterstützt folgende Eigenschaften: -#### Erforderlich (eine der folgenden Optionen) +#### Erforderlich (einer der folgenden Werte) - **`command`** (string): Pfad zur ausführbaren Datei für den Stdio-Transport - **`url`** (string): SSE-Endpoint-URL (z. B. `"http://localhost:8080/sse"`) @@ -86,14 +86,14 @@ Jede Serverkonfiguration unterstützt die folgenden Eigenschaften: #### Optional -- **`args`** (string[]): Command-line arguments für den Stdio transport -- **`headers`** (object): Benutzerdefinierte HTTP headers bei Verwendung von `url` oder `httpUrl` -- **`env`** (object): Environment Variablen für den Server-Prozess. Werte können Umgebungsvariablen mit der Syntax `$VAR_NAME` oder `${VAR_NAME}` referenzieren -- **`cwd`** (string): Arbeitsverzeichnis für den Stdio transport -- **`timeout`** (number): Request timeout in Millisekunden (Standard: 600.000ms = 10 Minuten) +- **`args`** (string[]): Command-line-Argumente für den Stdio-Transport +- **`headers`** (object): Benutzerdefinierte HTTP-Header bei Verwendung von `url` oder `httpUrl` +- **`env`** (object): Umgebungsvariablen für den Server-Prozess. Werte können Umgebungsvariablen mit der Syntax `$VAR_NAME` oder `${VAR_NAME}` referenzieren +- **`cwd`** (string): Arbeitsverzeichnis für den Stdio-Transport +- **`timeout`** (number): Request-Timeout in Millisekunden (Standard: 600.000 ms = 10 Minuten) - **`trust`** (boolean): Wenn `true`, werden alle Tool-Call-Bestätigungen für diesen Server umgangen (Standard: `false`) -- **`includeTools`** (string[]): Liste von Tool-Namen, die von diesem MCP-Server eingebunden werden sollen. Wenn angegeben, sind nur die hier aufgelisteten Tools von diesem Server verfügbar (Whitelist-Verhalten). Wenn nicht angegeben, sind standardmäßig alle Tools des Servers aktiviert. -- **`excludeTools`** (string[]): Liste von Tool-Namen, die von diesem MCP-Server ausgeschlossen werden sollen. Die hier aufgelisteten Tools stehen dem Modell nicht zur Verfügung, selbst wenn sie vom Server bereitgestellt werden. **Hinweis:** `excludeTools` hat Vorrang vor `includeTools` – wenn ein Tool in beiden Listen enthalten ist, wird es ausgeschlossen. +- **`includeTools`** (string[]): Liste der Tool-Namen, die von diesem MCP-Server eingebunden werden sollen. Wenn angegeben, sind nur die hier aufgelisteten Tools von diesem Server verfügbar (Whitelist-Verhalten). Falls nicht angegeben, sind standardmäßig alle Tools des Servers aktiviert. +- **`excludeTools`** (string[]): Liste der Tool-Namen, die von diesem MCP-Server ausgeschlossen werden sollen. Die hier aufgelisteten Tools stehen dem Modell nicht zur Verfügung, selbst wenn sie vom Server bereitgestellt werden. **Hinweis:** `excludeTools` hat Vorrang vor `includeTools` – wenn ein Tool in beiden Listen enthalten ist, wird es ausgeschlossen. ### OAuth-Unterstützung für Remote-MCP-Server @@ -101,7 +101,7 @@ Qwen Code unterstützt die OAuth 2.0-Authentifizierung für Remote-MCP-Server ü #### Automatische OAuth-Erkennung -Für Server, die OAuth-Discovery unterstützen, kannst du die OAuth-Konfiguration weglassen und sie vom CLI automatisch erkennen lassen: +Für Server, die OAuth-Discovery unterstützen, kannst du die OAuth-Konfiguration weglassen und die automatische Erkennung durch die CLI zulassen: ```json { @@ -113,7 +113,7 @@ Für Server, die OAuth-Discovery unterstützen, kannst du die OAuth-Konfiguratio } ``` -Das CLI führt dann automatisch folgende Schritte aus: +Die CLI führt dann automatisch folgende Schritte aus: - Erkennt, wenn ein Server eine OAuth-Authentifizierung benötigt (401-Antworten) - Findet OAuth-Endpunkte über die Server-Metadaten @@ -135,7 +135,7 @@ Beim Verbinden mit einem OAuth-fähigen Server: **Wichtig:** Die OAuth-Authentifizierung erfordert, dass dein lokaler Rechner: -- Einen Webbrowser öffnen kann für die Authentifizierung +- Einen Webbrowser für die Authentifizierung öffnen kann - Redirects auf `http://localhost:7777/oauth/callback` empfangen kann Dieses Feature funktioniert nicht in: @@ -152,6 +152,7 @@ Verwende den `/mcp auth` Befehl, um die OAuth-Authentifizierung zu verwalten: # Server auflisten, die Authentifizierung erfordern /mcp auth +``` ```markdown # Authentifizierung mit einem bestimmten Server @@ -189,7 +190,7 @@ Du kannst den Authentication Provider Type über die `authProviderType` Property - **`authProviderType`** (string): Gibt den Authentication Provider an. Mögliche Werte: - **`dynamic_discovery`** (default): Die CLI ermittelt die OAuth-Konfiguration automatisch vom Server. - - **`google_credentials`**: Die CLI verwendet die Google Application Default Credentials (ADC) für die Authentifizierung beim Server. Bei diesem Provider musst du die benötigten Scopes angeben. + - **`google_credentials`**: Die CLI verwendet die Google Application Default Credentials (ADC) für die Authentifizierung beim Server. Bei diesem Provider musst du die benötigten scopes angeben. ```json { @@ -266,7 +267,7 @@ Du kannst den Authentication Provider Type über die `authProviderType` Property } ``` -#### HTTP-basiertes MCP Server +#### HTTP-basierter MCP Server ```json { @@ -279,7 +280,7 @@ Du kannst den Authentication Provider Type über die `authProviderType` Property } ``` -#### HTTP-basiertes MCP Server mit Custom Headern +#### HTTP-basierter MCP Server mit Custom Headern ```json { @@ -327,7 +328,7 @@ Für jeden konfigurierten Server in `mcpServers`: - `url` → `SSEClientTransport` - `command` → `StdioClientTransport` 3. **Verbindungsaufbau:** Der MCP-Client versucht, eine Verbindung mit dem konfigurierten Timeout herzustellen -4. **Fehlerbehandlung:** Verbindungsfehler werden protokolliert und der Server-Status wird auf `DISCONNECTED` gesetzt +4. **Fehlerbehandlung:** Verbindungsfehler werden protokolliert und der Server-Status auf `DISCONNECTED` gesetzt ### 2. Tool Discovery @@ -336,13 +337,13 @@ Nach erfolgreicher Verbindung: 1. **Tool-Auflistung:** Der Client ruft den Tool-Listing-Endpoint des MCP-Servers auf 2. **Schema-Validierung:** Die Funktionsdeklaration jedes Tools wird validiert 3. **Tool-Filterung:** Tools werden basierend auf der `includeTools`- und `excludeTools`-Konfiguration gefiltert -4. **Namensbereinigung:** Tool-Namen werden bereinigt, um den Anforderungen der Gemini API zu entsprechen: +4. **Namensbereinigung:** Tool-Namen werden bereinigt, um den Qwen-API-Anforderungen zu entsprechen: - Ungültige Zeichen (nicht alphanumerisch, Unterstrich, Punkt, Bindestrich) werden durch Unterstriche ersetzt - Namen, die länger als 63 Zeichen sind, werden gekürzt mit mittlerem Ersatz (`___`) ### 3. Konfliktlösung -Wenn mehrere Server Tools mit demselben Namen bereitstellen: +Wenn mehrere Server Tools mit demselben Namen anbieten: 1. **First-come-first-served:** Der erste Server, der einen Tool-Namen registriert, erhält den unpräfixten Namen 2. **Automatische Präfixierung:** Nachfolgende Server erhalten präfixierte Namen: `serverName__toolName` @@ -365,9 +366,9 @@ Nach der Discovery: - **Aufräumen:** Server, die keine nutzbaren Tools bereitstellen, bekommen ihre Verbindungen geschlossen - **Status-Updates:** Die finalen Server-Status werden auf `CONNECTED` oder `DISCONNECTED` gesetzt -## Tool-Ausführungsflow +## Tool-Ausführungsfluss -Wenn das Model beschließt, ein MCP-Tool zu verwenden, erfolgt der folgende Ausführungsflow: +Wenn das Model beschließt, ein MCP-Tool zu verwenden, erfolgt der folgende Ausführungsablauf: ### 1. Tool-Aufruf @@ -399,7 +400,7 @@ Das System verwaltet interne Allow-lists für: Wenn eine Bestätigung erforderlich ist, können Benutzer folgende Optionen wählen: -- **Einmalig fortfahren:** Nur dieses Mal ausführen +- **Einmal ausführen:** Nur diesmal ausführen - **Dieses Tool immer erlauben:** Zur Allow-list auf Tool-Ebene hinzufügen - **Diesen Server immer erlauben:** Zur Allow-list auf Server-Ebene hinzufügen - **Abbrechen:** Ausführung abbrechen @@ -426,7 +427,7 @@ Nach Bestätigung (oder Umgehung der Vertrauensprüfung): Das Ausführungsergebnis enthält: -- **`llmContent`:** Rohdaten der Antwortanteile für den Kontext des Sprachmodells +- **`llmContent`:** Rohdaten der Antwortanteile für den Kontext des Language Models - **`returnDisplay`:** Formatierter Output für die Benutzeranzeige (häufig JSON in Markdown-Codeblöcken) ## Wie du mit deinem MCP-Server interagierst @@ -439,7 +440,7 @@ Der `/mcp` Befehl liefert umfassende Informationen zu deiner MCP-Server-Konfigur /mcp ``` -Dieser zeigt folgende Informationen an: +Dieser zeigt an: - **Serverliste:** Alle konfigurierten MCP-Server - **Verbindungsstatus:** `CONNECTED`, `CONNECTING` oder `DISCONNECTED` @@ -462,7 +463,7 @@ MCP Servers Status: Command: node dist/server.js --verbose Error: Connection refused -.dockerizedServer (CONNECTED) +🐳 dockerizedServer (CONNECTED) Command: docker run -i --rm -e API_KEY my-mcp-server:latest Tools: docker__deploy, docker__status @@ -471,11 +472,11 @@ Discovery State: COMPLETED ### Tool-Nutzung -Sobald MCP-Tools entdeckt wurden, stehen sie dem Gemini-Modell wie eingebaute Tools zur Verfügung. Das Modell wird automatisch: +Sobald sie entdeckt wurden, stehen MCP-Tools dem Qwen-Modell wie eingebaute Tools zur Verfügung. Das Modell wird automatisch: -1. **Passende Tools auswählen** basierend auf deinen Anfragen -2. **Bestätigungsdialoge anzeigen** (außer der Server ist als vertrauenswürdig markiert) -3. **Tools mit korrekten Parametern ausführen** +1. **Passende Tools auswählen** basierend auf deinen Anfragen +2. **Bestätigungsdialoge anzeigen** (außer der Server ist vertrauenswürdig) +3. **Tools mit korrekten Parametern ausführen** 4. **Ergebnisse in einem benutzerfreundlichen Format darstellen** ## Statusüberwachung und Fehlersuche @@ -486,15 +487,15 @@ Die MCP-Integration verfolgt mehrere Zustände: #### Server-Status (`MCPServerStatus`) -- **`DISCONNECTED`:** Server ist nicht verbunden oder es liegen Fehler vor -- **`CONNECTING`:** Verbindungsversuch läuft -- **`CONNECTED`:** Server ist verbunden und bereit +- **`DISCONNECTED`:** Server ist nicht verbunden oder hat Fehler +- **`CONNECTING`:** Verbindungsversuch läuft +- **`CONNECTED`:** Server ist verbunden und bereit -#### Discovery-Status (`MCPDiscoveryState`) +#### Entdeckungsstatus (`MCPDiscoveryState`) -- **`NOT_STARTED`:** Die Erkennung hat noch nicht begonnen -- **`IN_PROGRESS`:** Server werden aktuell erkannt -- **`COMPLETED`:** Discovery abgeschlossen (mit oder ohne Fehler) +- **`NOT_STARTED`:** Entdeckung hat noch nicht begonnen +- **`IN_PROGRESS`:** Server werden aktuell entdeckt +- **`COMPLETED`:** Entdeckung abgeschlossen (mit oder ohne Fehler) ### Häufige Probleme und Lösungen @@ -540,14 +541,14 @@ Die MCP-Integration verfolgt mehrere Zustände: 1. **Docker-basierte Server:** Verwenden Sie Docker-Container, die alle Abhängigkeiten enthalten 2. **Pfad-Zugriff:** Stellen Sie sicher, dass Server-Executables in der Sandbox verfügbar sind -3. **Netzwerkzugriff:** Konfigurieren Sie die Sandbox, um notwendige Netzwerkverbindungen zu erlauben -4. **Umgebungsvariablen:** Überprüfen Sie, ob benötigte Umgebungsvariablen durchgereicht werden +3. **Netzwerkzugriff:** Konfigurieren Sie die Sandbox so, dass notwendige Netzwerkverbindungen erlaubt sind +4. **Umgebungsvariablen:** Überprüfen Sie, ob erforderliche Environment-Variablen durchgereicht werden ### Debugging-Tipps 1. **Debug-Modus aktivieren:** Führe die CLI mit `--debug` aus, um detaillierte Ausgaben zu erhalten -2. **stderr prüfen:** MCP-Server-Fehlerausgaben (stderr) werden erfasst und geloggt (INFO-Meldungen werden gefiltert) -3. **Isoliertes Testen:** Teste deinen MCP-Server unabhängig, bevor du ihn integrierst +2. **stderr prüfen:** MCP-Server-Fehlerausgaben (stderr) werden erfasst und protokolliert (INFO-Meldungen werden gefiltert) +3. **Isoliert testen:** Teste deinen MCP-Server unabhängig, bevor du ihn integrierst 4. **Schrittweise Einrichtung:** Beginne mit einfachen Tools, bevor du komplexe Funktionalitäten hinzufügst 5. **Häufig `/mcp` nutzen:** Überwache den Server-Status während der Entwicklung @@ -555,29 +556,29 @@ Die MCP-Integration verfolgt mehrere Zustände: ### Sicherheitshinweise -- **Vertrauenseinstellungen:** Die `trust`-Option umgeht alle Bestätigungsdialoge. Verwende sie mit Bedacht und nur für Server, die du vollständig kontrollierst -- **Zugriffstoken:** Sei vorsichtig bei der Konfiguration von Umgebungsvariablen, die API-Schlüssel oder Tokens enthalten +- **Vertrauenseinstellungen:** Die `trust`-Option umgeht alle Bestätigungsdialoge. Verwende sie mit Vorsicht und nur für Server, die du vollständig kontrollierst +- **Zugriffstoken:** Sei dir der Sicherheitsimplikationen bewusst, wenn du Umgebungsvariablen mit API-Keys oder Tokens konfigurierst - **Sandbox-Kompatibilität:** Stelle bei der Verwendung von Sandboxing sicher, dass MCP-Server innerhalb der Sandbox-Umgebung erreichbar sind - **Private Daten:** Die Verwendung von allgemein gültigen Personal Access Tokens kann zu unbeabsichtigtem Datenleck zwischen Repositories führen ### Performance und Ressourcenmanagement -- **Connection persistence:** Die CLI hält persistente Verbindungen zu Servern aufrecht, die Tools erfolgreich registrieren +- **Connection Persistence:** Die CLI hält persistente Verbindungen zu Servern aufrecht, die Tools erfolgreich registrieren - **Automatische Bereinigung:** Verbindungen zu Servern, die keine Tools bereitstellen, werden automatisch geschlossen - **Timeout-Management:** Konfiguriere angemessene Timeouts basierend auf den Antwortzeiten deines Servers - **Ressourcenmonitoring:** MCP-Server laufen als separate Prozesse und verbrauchen Systemressourcen ### Schema-Kompatibilität -- **Property stripping:** Das System entfernt automatisch bestimmte Schema-Eigenschaften (`$schema`, `additionalProperties`) für die Kompatibilität mit der Gemini API +- **Property-Stripping:** Das System entfernt automatisch bestimmte Schema-Eigenschaften (`$schema`, `additionalProperties`) für die Kompatibilität mit der Qwen API - **Namensbereinigung:** Tool-Namen werden automatisch bereinigt, um die API-Anforderungen zu erfüllen - **Konfliktlösung:** Namenskonflikte von Tools zwischen Servern werden durch automatisches Präfixen gelöst -Diese umfassende Integration macht MCP-Server zu einer leistungsstarken Möglichkeit, die Fähigkeiten der CLI zu erweitern, ohne dabei Sicherheit, Zuverlässigkeit und Benutzerfreundlichkeit zu vernachlässigen. +Diese umfassende Integration macht MCP-Server zu einer leistungsstarken Möglichkeit, die Fähigkeiten der CLI zu erweitern, ohne dabei Sicherheit, Stabilität und Benutzerfreundlichkeit zu vernachlässigen. ## Rückgabe von Rich Content aus Tools -MCP-Tools sind nicht darauf beschränkt, einfachen Text zurückzugeben. Du kannst Rich Content mit mehreren Teilen zurückgeben, darunter Text, Bilder, Audio und andere Binärdaten in einer einzigen Tool-Antwort. Dies ermöglicht es dir, leistungsstarke Tools zu erstellen, die dem Modell in einem einzigen Schritt vielfältige Informationen bereitstellen können. +MCP-Tools sind nicht darauf beschränkt, einfachen Text zurückzugeben. Du kannst Rich Content mit mehreren Teilen zurückgeben, darunter Text, Bilder, Audio und andere Binärdaten – alles in einer einzigen Tool-Antwort. Dies ermöglicht es dir, leistungsstarke Tools zu erstellen, die dem Modell in einem einzigen Schritt vielfältige Informationen liefern können. Alle vom Tool zurückgegebenen Daten werden verarbeitet und als Kontext für die nächste Generierung an das Modell gesendet, sodass es die bereitgestellten Informationen verarbeiten oder zusammenfassen kann. @@ -595,14 +596,14 @@ Du kannst verschiedene Content Block-Typen im `content`-Array mischen und kombin ### Beispiel: Rückgabe von Text und einem Bild -Hier ist ein Beispiel für eine gültige JSON-Antwort von einem MCP-Tool, das sowohl eine Textbeschreibung als auch ein Bild zurückgibt: +Hier ist ein Beispiel für eine gültige JSON-Antwort eines MCP-Tools, das sowohl eine Textbeschreibung als auch ein Bild zurückgibt: ```json { "content": [ { "type": "text", - "text": "Here is the logo you requested." + "text": "Hier ist das Logo, das du angefordert hast." }, { "type": "image", @@ -611,7 +612,7 @@ Hier ist ein Beispiel für eine gültige JSON-Antwort von einem MCP-Tool, das so }, { "type": "text", - "text": "The logo was created in 2025." + "text": "Das Logo wurde 2025 erstellt." } ] } @@ -621,9 +622,9 @@ Wenn Qwen Code diese Antwort erhält, wird es: 1. Den gesamten Text extrahieren und zu einem einzigen `functionResponse`-Teil für das Modell zusammenfügen. 2. Die Bilddaten als separaten `inlineData`-Teil darstellen. -3. Eine saubere, benutzerfreundliche Zusammenfassung in der CLI anzeigen, die angibt, dass sowohl Text als auch ein Bild empfangen wurden. +3. Eine übersichtliche, benutzerfreundliche Zusammenfassung in der CLI anzeigen, die angibt, dass sowohl Text als auch ein Bild empfangen wurden. -Dadurch kannst du anspruchsvolle Tools entwickeln, die dem Gemini-Modell einen umfangreichen, multimodalen Kontext bieten. +Dadurch kannst du anspruchsvolle Tools entwickeln, die dem Qwen-Modell einen umfangreichen, multimodalen Kontext bieten. ## MCP Prompts als Slash Commands @@ -667,7 +668,7 @@ const transport = new StdioServerTransport(); await server.connect(transport); ``` -Dies kann in der `settings.json` unter `mcpServers` wie folgt eingetragen werden: +Dies kann in der `settings.json` unter `mcpServers` wie folgt eingebunden werden: ```json "nodeServer": { @@ -678,7 +679,7 @@ Dies kann in der `settings.json` unter `mcpServers` wie folgt eingetragen werden ### Prompts aufrufen -Sobald ein Prompt entdeckt wurde, kannst du ihn über seinen Namen als Slash-Befehl aufrufen. Die CLI übernimmt automatisch das Parsen der Argumente. +Sobald ein Prompt gefunden wurde, kannst du ihn über seinen Namen als Slash-Befehl aufrufen. Die CLI übernimmt automatisch das Parsen der Argumente. ```bash /poem-writer --title="Qwen Code" --mood="reverent" @@ -694,9 +695,9 @@ Wenn du diesen Befehl ausführst, führt die CLI die Methode `prompts/get` auf d ## Verwaltung von MCP-Servern mit `qwen mcp` -Auch wenn du MCP-Server immer durch manuelles Bearbeiten der `settings.json` konfigurieren kannst, bietet die CLI eine praktische Reihe von Befehlen, um deine Server-Konfigurationen programmatisch zu verwalten. Diese Befehle vereinfachen das Hinzufügen, Auflisten und Entfernen von MCP-Servern, ohne dass du JSON-Dateien direkt bearbeiten musst. +Auch wenn du MCP-Server jederzeit durch manuelles Bearbeiten der `settings.json` konfigurieren kannst, bietet das CLI eine praktische Reihe von Befehlen, um deine Server-Konfigurationen programmatisch zu verwalten. Diese Befehle vereinfachen das Hinzufügen, Auflisten und Entfernen von MCP-Servern, ohne dass du JSON-Dateien direkt bearbeiten musst. -### Einen Server hinzufügen (`qwen mcp add`) +### Server hinzufügen (`qwen mcp add`) Der `add`-Befehl konfiguriert einen neuen MCP-Server in deiner `settings.json`. Je nach Scope (`-s, --scope`) wird er entweder zur User-Konfiguration `~/.qwen/settings.json` oder zur Projekt-Konfiguration `.qwen/settings.json` hinzugefügt. @@ -715,7 +716,7 @@ qwen mcp add [Optionen] [args...] - `-s, --scope`: Konfigurations-Scope (user oder project). [Standard: "project"] - `-t, --transport`: Transport-Typ (stdio, sse, http). [Standard: "stdio"] - `-e, --env`: Umgebungsvariablen setzen (z. B. -e KEY=value). -- `-H, --header`: HTTP-Header für SSE- und HTTP-Transporte setzen (z. B. -H "X-Api-Key: abc123" -H "Authorization: Bearer abc123"). +- `-H, --header`: HTTP-Header für SSE- und HTTP-Transports setzen (z. B. -H "X-Api-Key: abc123" -H "Authorization: Bearer abc123"). - `--timeout`: Verbindungs-Timeout in Millisekunden festlegen. - `--trust`: Dem Server vertrauen (alle Bestätigungsdialoge für Tool-Aufrufe umgehen). - `--description`: Beschreibung für den Server festlegen. @@ -750,7 +751,7 @@ qwen mcp add --transport http # Beispiel: Hinzufügen eines HTTP-Servers qwen mcp add --transport http http-server https://api.example.com/mcp/ -# Beispiel: Hinzufügen eines HTTP-Servers mit einem Authentifizierungs-Header +# Beispiel: Hinzufügen eines HTTP-Servers mit Authentifizierungs-Header qwen mcp add --transport http secure-http https://api.example.com/mcp/ --header "Authorization: Bearer abc123" ``` @@ -806,4 +807,4 @@ qwen mcp remove qwen mcp remove my-server ``` -Dieser Befehl sucht den Eintrag „my-server“ im `mcpServers`-Objekt der entsprechenden `settings.json`-Datei und löscht ihn. Der Speicherort der Datei hängt vom verwendeten Scope (`-s, --scope`) ab. \ No newline at end of file +Dieser Befehl sucht den Eintrag "my-server" im `mcpServers`-Objekt der entsprechenden `settings.json`-Datei und löscht ihn. Der Speicherort der Datei hängt vom verwendeten Scope (`-s, --scope`) ab. \ No newline at end of file diff --git a/website/content/de/tools/memory.md b/website/content/de/tools/memory.md index e54a734b..927f70d8 100644 --- a/website/content/de/tools/memory.md +++ b/website/content/de/tools/memory.md @@ -4,7 +4,7 @@ Dieses Dokument beschreibt das `save_memory` Tool für Qwen Code. ## Beschreibung -Verwende `save_memory`, um Informationen über deine Qwen Code-Sitzungen hinweg zu speichern und abzurufen. Mit `save_memory` kannst du die CLI anweisen, wichtige Details über Sitzungen hinweg zu merken und so eine personalisierte und gezielte Unterstützung zu bieten. +Verwende `save_memory`, um Informationen über deine Qwen Code-Sitzungen hinweg zu speichern und abzurufen. Mit `save_memory` kannst du die CLI anweisen, wichtige Details über Sitzungen hinweg zu merken, um personalisierte und gezielte Unterstützung zu bieten. ### Argumente @@ -14,19 +14,19 @@ Verwende `save_memory`, um Informationen über deine Qwen Code-Sitzungen hinweg ## Verwendung von `save_memory` mit Qwen Code -Das Tool fügt den übergebenen `fact` deiner Kontextdatei im Home-Verzeichnis des Benutzers hinzu (standardmäßig `~/.qwen/QWEN.md`). Dieser Dateiname kann über `contextFileName` konfiguriert werden. +Das Tool fügt den übergebenen `fact` zur Kontextdatei im Home-Verzeichnis des Benutzers hinzu (standardmäßig `~/.qwen/QWEN.md`). Dieser Dateiname kann über `contextFileName` konfiguriert werden. -Einmal hinzugefügt, werden die Fakten unter einem Abschnitt namens `## Qwen Added Memories` gespeichert. Diese Datei wird in nachfolgenden Sitzungen als Kontext geladen, sodass die CLI die gespeicherten Informationen abrufen kann. +Einmal hinzugefügt, werden die Fakten unter einem Abschnitt mit dem Namen `## Qwen Added Memories` gespeichert. Diese Datei wird in nachfolgenden Sitzungen als Kontext geladen, sodass die CLI die gespeicherten Informationen abrufen kann. Verwendung: ``` -save_memory(fact="Dein Fakt hier.") +save_memory(fact="Your fact here.") ``` ### `save_memory` Beispiele -Eine Benutzerpräferenz speichern: +Eine Benutzereinstellung merken: ``` save_memory(fact="Meine bevorzugte Programmiersprache ist Python.") @@ -35,10 +35,10 @@ save_memory(fact="Meine bevorzugte Programmiersprache ist Python.") Ein projektspezifisches Detail speichern: ``` -save_memory(fact="Das Projekt, an dem ich gerade arbeite, heißt 'gemini-cli'.") +save_memory(fact="Das Projekt, an dem ich gerade arbeite, heißt 'qwen-code'.") ``` ## Wichtige Hinweise - **Allgemeine Verwendung:** Dieses Tool sollte für prägnante, wichtige Fakten verwendet werden. Es ist nicht dafür gedacht, große Datenmengen oder Konversationsverläufe zu speichern. -- **Memory-Datei:** Die Memory-Datei ist eine einfache Markdown-Textdatei, die du bei Bedarf manuell einsehen und bearbeiten kannst. \ No newline at end of file +- **Memory-Datei:** Die Memory-Datei ist eine einfache Text-Markdown-Datei, daher kannst du sie bei Bedarf manuell einsehen und bearbeiten. \ No newline at end of file diff --git a/website/content/de/tools/web-fetch.md b/website/content/de/tools/web-fetch.md index 68e7725d..0332076e 100644 --- a/website/content/de/tools/web-fetch.md +++ b/website/content/de/tools/web-fetch.md @@ -4,14 +4,14 @@ Dieses Dokument beschreibt das `web_fetch` Tool für Qwen Code. ## Beschreibung -Verwende `web_fetch`, um Inhalte von einer angegebenen URL abzurufen und mit einem KI-Modell zu verarbeiten. Das Tool benötigt eine URL und einen Prompt als Eingabe, ruft den Inhalt der URL ab, konvertiert HTML in Markdown und verarbeitet den Inhalt mit dem Prompt unter Verwendung eines kleinen, schnellen Modells. +Verwende `web_fetch`, um Inhalte von einer angegebenen URL abzurufen und mit einem KI-Modell zu verarbeiten. Das Tool benötigt eine URL und einen Prompt als Eingabe, ruft den Inhalt der URL ab, konvertiert HTML in Markdown und verarbeitet den Inhalt anhand des Prompts mit einem kleinen, schnellen Modell. ### Argumente `web_fetch` akzeptiert zwei Argumente: -- `url` (String, erforderlich): Die URL, von der der Inhalt abgerufen werden soll. Muss eine vollständig gültige URL sein, die mit `http://` oder `https://` beginnt. -- `prompt` (String, erforderlich): Der Prompt, der beschreibt, welche Informationen du aus dem Seiteninhalt extrahieren möchtest. +- `url` (string, erforderlich): Die URL, von der der Inhalt abgerufen werden soll. Muss eine vollständige, gültige URL sein, die mit `http://` oder `https://` beginnt. +- `prompt` (string, erforderlich): Der Prompt, der beschreibt, welche Informationen du aus dem Seiteninhalt extrahieren möchtest. ## Wie man `web_fetch` mit Qwen Code verwendet @@ -39,16 +39,16 @@ Extrahieren spezifischer Informationen: web_fetch(url="https://arxiv.org/abs/2401.0001", prompt="What are the key findings and methodology described in this paper?") ``` -Analyse von GitHub Dokumentation: +Analyse von GitHub-Dokumentation: ``` -web_fetch(url="https://github.com/google/gemini-react/blob/main/README.md", prompt="What are the installation steps and main features?") +web_fetch(url="https://github.com/QwenLM/Qwen/blob/main/README.md", prompt="What are the installation steps and main features?") ``` ## Wichtige Hinweise - **Einzelne URL-Verarbeitung:** `web_fetch` verarbeitet jeweils nur eine URL. Um mehrere URLs zu analysieren, führe separate Aufrufe des Tools durch. -- **URL-Format:** Das Tool aktualisiert HTTP-URLs automatisch auf HTTPS und wandelt GitHub-Blob-URLs in das Raw-Format um, um einen besseren Zugriff auf den Inhalt zu ermöglichen. +- **URL-Format:** Das Tool führt HTTP-URLs automatisch auf HTTPS hoch und wandelt GitHub-Blob-URLs in das Raw-Format um, um einen besseren Zugriff auf den Inhalt zu ermöglichen. - **Inhaltsverarbeitung:** Das Tool ruft den Inhalt direkt ab und verarbeitet ihn mithilfe eines KI-Modells, wobei HTML in ein lesbares Textformat konvertiert wird. - **Ausgabegüte:** Die Qualität der Ausgabe hängt von der Klarheit der Anweisungen im Prompt ab. -- **MCP-Tools:** Falls ein von MCP bereitgestelltes Web-Fetch-Tool verfügbar ist (beginnend mit "mcp\_\_"), verwende dieses Tool vorzugsweise, da es möglicherweise weniger Einschränkungen unterliegt. \ No newline at end of file +- **MCP-Tools:** Falls ein von MCP bereitgestelltes Web-Fetch-Tool verfügbar ist (beginnend mit "mcp\_\_"), bevorzuge die Verwendung dieses Tools, da es möglicherweise weniger Einschränkungen unterliegt. \ No newline at end of file diff --git a/website/content/de/troubleshooting.md b/website/content/de/troubleshooting.md index 5536efa3..37a06d27 100644 --- a/website/content/de/troubleshooting.md +++ b/website/content/de/troubleshooting.md @@ -1,21 +1,16 @@ # Leitfaden zur Fehlerbehebung -Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, darunter Themen zu: +Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, darunter Themen wie: -- Authentifizierungs- oder Login-Fehlern -- Häufig gestellten Fragen (FAQs) +- Authentifizierungs- oder Login-Fehler +- Häufig gestellte Fragen (FAQs) - Debugging-Tipps - Vorhandene GitHub Issues, die deinem Problem ähneln, oder Erstellen neuer Issues ## 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 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. + - **Ursache:** Du befindest dich möglicherweise in einem Unternehmensnetzwerk mit einer Firewall, die SSL/TLS-Verkehr abfängt und untersucht. Dies erfordert oft ein benutzerdefiniertes Root-CA-Zertifikat, das von Node.js vertraut werden muss. - **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` @@ -29,24 +24,24 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da 1. In deinem Home-Verzeichnis: `~/.qwen/settings.json`. 2. Im Root-Verzeichnis deines Projekts: `./.qwen/settings.json`. - Weitere Details findest du unter [Qwen Code Konfiguration](./cli/configuration.md). + Weitere Informationen findest du unter [Qwen Code Konfiguration](./cli/configuration.md). - **Q: Warum sehe ich keine zwischengespeicherten Token-Zähler in meiner Statistik-Ausgabe?** - - A: Informationen zu zwischengespeicherten Tokens werden nur angezeigt, wenn zwischengespeicherte Tokens verwendet werden. Dieses Feature ist für API-Key-Benutzer (Gemini API Key oder Google Cloud Vertex AI) verfügbar, aber nicht für OAuth-Benutzer (wie z. B. Google Personal/Enterprise Konten wie Google Gmail oder Google Workspace). Der Grund dafür ist, dass die Gemini Code Assist API das Erstellen von zwischengespeicherten Inhalten nicht unterstützt. Du kannst deine gesamte Token-Nutzung weiterhin mit dem Befehl `/stats` anzeigen. + - A: Informationen zu zwischengespeicherten Tokens werden nur angezeigt, wenn zwischengespeicherte Tokens verwendet werden. Diese Funktion ist für API-Key-Benutzer (Qwen API Key oder Google Cloud Vertex AI) verfügbar, aber nicht für OAuth-Benutzer (wie z. B. Google Personal/Enterprise-Konten wie Google Gmail oder Google Workspace). Der Grund dafür ist, dass die Qwen Code Assist API die Erstellung von zwischengespeicherten Inhalten nicht unterstützt. Du kannst deine gesamte Token-Nutzung weiterhin mit dem Befehl `/stats` anzeigen. ## Häufige Fehlermeldungen und Lösungen - **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 den anderen Prozess, der den Port verwendet, oder konfiguriere den MCP-Server so, dass er einen anderen Port verwendet. + Beende entweder 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 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. + - 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. - **Fehler: `MODULE_NOT_FOUND` oder Import-Fehler.** - **Ursache:** Abhängigkeiten sind nicht korrekt installiert oder das Projekt wurde nicht gebaut. @@ -56,33 +51,33 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da 3. Überprüfe mit `npm run start`, ob der Build erfolgreich abgeschlossen wurde. - **Fehler: „Operation not permitted“, „Permission denied“ oder Ähnliches.** - - **Ursache:** Wenn Sandboxing aktiviert ist, kann Qwen Code versuchen, Operationen durchzuführen, die durch deine Sandbox-Konfiguration eingeschränkt sind, z. B. außerhalb des Projektverzeichnisses oder des systemweiten Temp-Verzeichnisses zu schreiben. + - **Ursache:** Wenn Sandboxing aktiviert ist, kann Qwen Code versuchen, Operationen durchzuführen, die durch deine Sandbox-Konfiguration eingeschränkt sind, z. B. Schreibzugriffe außerhalb des Projektverzeichnisses oder des systemweiten Temp-Verzeichnisses. - **Lösung:** Weitere Informationen findest du in der Dokumentation unter [Configuration: Sandboxing](./cli/configuration.md#sandboxing), einschließlich Anweisungen zur Anpassung deiner Sandbox-Konfiguration. - **Qwen Code läuft in „CI“-Umgebungen nicht im interaktiven Modus** - **Problem:** Qwen Code wechselt nicht in den interaktiven Modus (es erscheint keine Eingabeaufforderung), wenn eine Umgebungsvariable mit dem Präfix `CI_` (z. B. `CI_TOKEN`) gesetzt ist. Das liegt daran, dass das `is-in-ci`-Paket, das vom zugrunde liegenden UI-Framework verwendet wird, diese Variablen erkennt und eine nicht-interaktive CI-Umgebung annimmt. - - **Ursache:** Das `is-in-ci`-Paket prüft auf das Vorhandensein von `CI`, `CONTINUOUS_INTEGRATION` oder beliebigen Umgebungsvariablen mit dem Präfix `CI_`. Wenn eine dieser Variablen gefunden wird, wird signalisiert, dass die Umgebung nicht interaktiv ist, wodurch die CLI daran gehindert wird, im interaktiven Modus zu starten. + - **Ursache:** Das `is-in-ci`-Paket prüft auf das Vorhandensein von `CI`, `CONTINUOUS_INTEGRATION` oder beliebigen Umgebungsvariablen mit dem Präfix `CI_`. Wenn eine dieser Variablen gefunden wird, wird davon ausgegangen, dass es sich um eine nicht-interaktive Umgebung handelt, wodurch der Start im interaktiven Modus verhindert wird. - **Lösung:** Falls die Variable mit dem Präfix `CI_` für die CLI nicht benötigt wird, kannst du sie vorübergehend für den Befehl deaktivieren, z. B. mit `env -u CI_TOKEN qwen`. - **DEBUG-Modus funktioniert nicht über die .env-Datei des Projekts** - **Problem:** Das Setzen von `DEBUG=true` in der `.env`-Datei eines Projekts aktiviert den Debug-Modus für die CLI nicht. - - **Ursache:** Die Variablen `DEBUG` und `DEBUG_MODE` werden automatisch aus Projekt `.env`-Dateien ausgeschlossen, um Störungen im CLI-Verhalten zu vermeiden. + - **Ursache:** Die Variablen `DEBUG` und `DEBUG_MODE` werden automatisch aus Projekt-`.env`-Dateien ausgeschlossen, um Störungen im CLI-Verhalten zu vermeiden. - **Lösung:** Verwende stattdessen eine `.qwen/.env`-Datei oder passe die Einstellung `excludedProjectEnvVars` in deiner `settings.json` an, um weniger Variablen auszuschließen. ## IDE Companion verbindet nicht - Stelle sicher, dass VS Code einen einzelnen Workspace-Ordner geöffnet hat. -- Starte das integrierte Terminal neu, nachdem du die Extension installiert hast, damit es folgende Umgebungsvariablen übernimmt: +- Starte das integrierte Terminal neu, nachdem die Extension installiert wurde, damit es folgende Umgebungsvariablen übernimmt: - `QWEN_CODE_IDE_WORKSPACE_PATH` - `QWEN_CODE_IDE_SERVER_PORT` -- Wenn du in einem Container arbeitest, prüfe, ob `host.docker.internal` aufgelöst werden kann. Andernfalls musst du den Host entsprechend mappen. +- Wenn du in einem Container arbeitest, prüfe, ob `host.docker.internal` aufgelöst werden kann. Andernfalls muss der Host entsprechend gemappt werden. - 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 - **CLI-Debugging:** - Verwende das `--verbose`-Flag (falls verfügbar) mit CLI-Befehlen, um detailliertere Ausgaben zu erhalten. - - Prüfe die CLI-Logs, die oft in einem benutzerspezifischen Konfigurations- oder Cache-Verzeichnis zu finden sind. + - Prüfe die CLI-Logs, diese befinden sich oft in einem benutzerspezifischen Konfigurations- oder Cache-Verzeichnis. - **Core-Debugging:** - Prüfe die Server-Konsolenausgabe auf Fehlermeldungen oder Stack-Traces. @@ -94,7 +89,7 @@ Dieser Leitfaden bietet Lösungen für häufige Probleme und Debugging-Tipps, da - Für `run_shell_command` prüfe zuerst, ob der Befehl direkt in deiner Shell funktioniert. - Für _Filesystem-Tools_ stelle sicher, dass die Pfade korrekt sind und überprüfe die Berechtigungen. -- **Pre-flight-Checks:** +- **Preflight-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/Uninstall.md b/website/content/en/Uninstall.md index 28d520f2..bdc7ae65 100644 --- a/website/content/en/Uninstall.md +++ b/website/content/en/Uninstall.md @@ -4,7 +4,7 @@ Your uninstall method depends on how you ran the CLI. Follow the instructions fo ## Method 1: Using npx -npx runs packages from a temporary cache without a permanent installation. To "uninstall" the CLI, you must clear this cache, which will remove gemini-cli and any other packages previously executed with npx. +npx runs packages from a temporary cache without a permanent installation. To "uninstall" the CLI, you must clear this cache, which will remove qwen-code and any other packages previously executed with npx. The npx cache is a directory named `_npx` inside your main npm cache folder. You can find your npm cache path by running `npm config get cache`. diff --git a/website/content/en/checkpointing.md b/website/content/en/checkpointing.md index 897400d1..2c5af00d 100644 --- a/website/content/en/checkpointing.md +++ b/website/content/en/checkpointing.md @@ -4,7 +4,7 @@ Qwen Code includes a Checkpointing feature that automatically saves a snapshot o ## How It Works -When you approve a tool that modifies the file system (like `write_file` or `replace`), the CLI automatically creates a "checkpoint." This checkpoint includes: +When you approve a tool that modifies the file system (like `write_file` or `edit`), the CLI automatically creates a "checkpoint." This checkpoint includes: 1. **A Git Snapshot:** A commit is made in a special, shadow Git repository located in your home directory (`~/.qwen/history/`). This snapshot captures the complete state of your project files at that moment. It does **not** interfere with your own project's Git repository. 2. **Conversation History:** The entire conversation you've had with the agent up to that point is saved. diff --git a/website/content/en/cli/commands.md b/website/content/en/cli/commands.md index ef72c9ef..40ca2278 100644 --- a/website/content/en/cli/commands.md +++ b/website/content/en/cli/commands.md @@ -18,8 +18,8 @@ Slash commands provide meta-level control over the CLI itself. - **Description:** Saves the current conversation history. You must add a `` for identifying the conversation state. - **Usage:** `/chat save ` - **Details on Checkpoint Location:** The default locations for saved chat checkpoints are: - - Linux/macOS: `~/.config/google-generative-ai/checkpoints/` - - Windows: `C:\Users\\AppData\Roaming\google-generative-ai\checkpoints\` + - Linux/macOS: `~/.config/qwen-code/checkpoints/` + - Windows: `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` - When you run `/chat list`, the CLI only scans these specific directories to find available checkpoints. - **Note:** These checkpoints are for manually saving and resuming conversation states. For automatic checkpoints created before file modifications, see the [Checkpointing documentation](../checkpointing.md). - **`resume`** @@ -35,6 +35,17 @@ Slash commands provide meta-level control over the CLI itself. - **Description:** Clear the terminal screen, including the visible session history and scrollback within the CLI. The underlying session data (for history recall) might be preserved depending on the exact implementation, but the visual display is cleared. - **Keyboard shortcut:** Press **Ctrl+L** at any time to perform a clear action. +- **`/summary`** + - **Description:** Generate a comprehensive project summary from the current conversation history and save it to `.qwen/PROJECT_SUMMARY.md`. This summary includes the overall goal, key knowledge, recent actions, and current plan, making it perfect for resuming work in future sessions. + - **Usage:** `/summary` + - **Features:** + - Analyzes the entire conversation history to extract important context + - Creates a structured markdown summary with sections for goals, knowledge, actions, and plans + - Automatically saves to `.qwen/PROJECT_SUMMARY.md` in your project root + - Shows progress indicators during generation and saving + - Integrates with the Welcome Back feature for seamless session resumption + - **Note:** This command requires an active conversation with at least 2 messages to generate a meaningful summary. + - **`/compress`** - **Description:** Replace the entire chat context with a summary. This saves on tokens used for future tasks while retaining a high level summary of what has happened. @@ -116,6 +127,20 @@ Slash commands provide meta-level control over the CLI itself. - **`/about`** - **Description:** Show version info. Please share this information when filing issues. +- **`/agents`** + - **Description:** Manage specialized AI subagents for focused tasks. Subagents are independent AI assistants configured with specific expertise and tool access. + - **Sub-commands:** + - **`create`**: + - **Description:** Launch an interactive wizard to create a new subagent. The wizard guides you through location selection, AI-powered prompt generation, tool selection, and visual customization. + - **Usage:** `/agents create` + - **`manage`**: + - **Description:** Open an interactive management dialog to view, edit, and delete existing subagents. Shows both project-level and user-level agents. + - **Usage:** `/agents manage` + - **Storage Locations:** + - **Project-level:** `.qwen/agents/` (shared with team, takes precedence) + - **User-level:** `~/.qwen/agents/` (personal agents, available across projects) + - **Note:** For detailed information on creating and managing subagents, see the [Subagents documentation](../subagents.md). + - [**`/tools`**](../tools/index.md) - **Description:** Display a list of tools that are currently available within Qwen Code. - **Sub-commands:** @@ -127,8 +152,18 @@ Slash commands provide meta-level control over the CLI itself. - **`/privacy`** - **Description:** Display the Privacy Notice and allow users to select whether they consent to the collection of their data for service improvement purposes. +- **`/quit-confirm`** + - **Description:** Show a confirmation dialog before exiting Qwen Code, allowing you to choose how to handle your current session. + - **Usage:** `/quit-confirm` + - **Features:** + - **Quit immediately:** Exit without saving anything (equivalent to `/quit`) + - **Generate summary and quit:** Create a project summary using `/summary` before exiting + - **Save conversation and quit:** Save the current conversation with an auto-generated tag before exiting + - **Keyboard shortcut:** Press **Ctrl+C** twice to trigger the quit confirmation dialog + - **Note:** This command is automatically triggered when you press Ctrl+C once, providing a safety mechanism to prevent accidental exits. + - **`/quit`** (or **`/exit`**) - - **Description:** Exit Qwen Code. + - **Description:** Exit Qwen Code immediately without any confirmation dialog. - **`/vim`** - **Description:** Toggle vim mode on or off. When vim mode is enabled, the input area supports vim-style navigation and editing commands in both NORMAL and INSERT modes. @@ -180,23 +215,52 @@ Your command definition files must be written in the TOML format and use the `.t #### Handling Arguments -Custom commands support two powerful, low-friction methods for handling arguments. The CLI automatically chooses the correct method based on the content of your command's `prompt`. +Custom commands support two powerful methods for handling arguments. The CLI automatically chooses the correct method based on the content of your command's `prompt`. -##### 1. Shorthand Injection with `{{args}}` +##### 1. Context-Aware Injection with `{{args}}` -If your `prompt` contains the special placeholder `{{args}}`, the CLI will replace that exact placeholder with all the text the user typed after the command name. This is perfect for simple, deterministic commands where you need to inject user input into a specific place in a larger prompt template. +If your `prompt` contains the special placeholder `{{args}}`, the CLI will replace that placeholder with the text the user typed after the command name. + +The behavior of this injection depends on where it is used: + +**A. Raw Injection (Outside Shell Commands)** + +When used in the main body of the prompt, the arguments are injected exactly as the user typed them. **Example (`git/fix.toml`):** ```toml -# In: ~/.qwen/commands/git/fix.toml -# Invoked via: /git:fix "Button is misaligned on mobile" +# Invoked via: /git:fix "Button is misaligned" -description = "Generates a fix for a given GitHub issue." -prompt = "Please analyze the staged git changes and provide a code fix for the issue described here: {{args}}." +description = "Generates a fix for a given issue." +prompt = "Please provide a code fix for the issue described here: {{args}}." ``` -The model will receive the final prompt: `Please analyze the staged git changes and provide a code fix for the issue described here: "Button is misaligned on mobile".` +The model receives: `Please provide a code fix for the issue described here: "Button is misaligned".` + +**B. Using Arguments in Shell Commands (Inside `!{...}` Blocks)** + +When you use `{{args}}` inside a shell injection block (`!{...}`), the arguments are automatically **shell-escaped** before replacement. This allows you to safely pass arguments to shell commands, ensuring the resulting command is syntactically correct and secure while preventing command injection vulnerabilities. + +**Example (`/grep-code.toml`):** + +```toml +prompt = """ +Please summarize the findings for the pattern `{{args}}`. + +Search Results: +!{grep -r {{args}} .} +""" +``` + +When you run `/grep-code It's complicated`: + +1. The CLI sees `{{args}}` used both outside and inside `!{...}`. +2. Outside: The first `{{args}}` is replaced raw with `It's complicated`. +3. Inside: The second `{{args}}` is replaced with the escaped version (e.g., on Linux: `"It's complicated"`). +4. The command executed is `grep -r "It's complicated" .`. +5. The CLI prompts you to confirm this exact, secure command before execution. +6. The final prompt is sent. ##### 2. Default Argument Handling @@ -247,14 +311,11 @@ When a custom command attempts to execute a shell command, Qwen Code will now pr **How It Works:** -1. **Inject Commands:** Use the `!{...}` syntax in your `prompt` to specify where the command should be run and its output injected. -2. **Confirm Execution:** When you run the command, a dialog will appear listing the shell commands the prompt wants to execute. -3. **Grant Permission:** You can choose to: - - **Allow once:** The command(s) will run this one time. - - **Allow always for this session:** The command(s) will be added to a temporary allowlist for the current CLI session and will not require confirmation again. - - **No:** Cancel the execution of the shell command(s). - -The CLI still respects the global `excludeTools` and `coreTools` settings. A command will be blocked without a confirmation prompt if it is explicitly disallowed in your configuration. +1. **Inject Commands:** Use the `!{...}` syntax. +2. **Argument Substitution:** If `{{args}}` is present inside the block, it is automatically shell-escaped (see [Context-Aware Injection](#1-context-aware-injection-with-args) above). +3. **Robust Parsing:** The parser correctly handles complex shell commands that include nested braces, such as JSON payloads. +4. **Security Check and Confirmation:** The CLI performs a security check on the final, resolved command (after arguments are escaped and substituted). A dialog will appear showing the exact command(s) to be executed. +5. **Execution and Error Reporting:** The command is executed. If the command fails, the output injected into the prompt will include the error messages (stderr) followed by a status line, e.g., `[Shell command exited with code 1]`. This helps the model understand the context of the failure. **Example (`git/commit.toml`):** diff --git a/website/content/en/cli/configuration.md b/website/content/en/cli/configuration.md index 78147c3f..6bf1642c 100644 --- a/website/content/en/cli/configuration.md +++ b/website/content/en/cli/configuration.md @@ -23,8 +23,9 @@ Qwen Code uses `settings.json` files for persistent configuration. There are thr - **Project settings file:** - **Location:** `.qwen/settings.json` within your project's root directory. - **Scope:** Applies only when running Qwen Code from that specific project. Project settings override user settings. + - **System settings file:** - - **Location:** `/etc/gemini-cli/settings.json` (Linux), `C:\ProgramData\gemini-cli\settings.json` (Windows) or `/Library/Application Support/GeminiCli/settings.json` (macOS). The path can be overridden using the `GEMINI_CLI_SYSTEM_SETTINGS_PATH` environment variable. + - **Location:** `/etc/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) or `/Library/Application Support/QwenCode/settings.json` (macOS). The path can be overridden using the `QWEN_CODE_SYSTEM_SETTINGS_PATH` environment variable. - **Scope:** Applies to all Qwen Code sessions on the system, for all users. System settings override user and project settings. May be useful for system administrators at enterprises to have controls over users' Qwen Code setups. **Note on environment variables in settings:** String values within your `settings.json` files can reference environment variables using either `$VAR_NAME` or `${VAR_NAME}` syntax. These variables will be automatically resolved when the settings are loaded. For example, if you have an environment variable `MY_API_TOKEN`, you could use it in `settings.json` like this: `"apiKey": "$MY_API_TOKEN"`. @@ -127,16 +128,20 @@ In addition to a project settings file, a project's `.qwen` directory can contai - **Example:** `"toolCallCommand": "bin/call_tool"` - **`mcpServers`** (object): - - **Description:** Configures connections to one or more Model-Context Protocol (MCP) servers for discovering and using custom tools. Qwen Code attempts to connect to each configured MCP server to discover available tools. If multiple MCP servers expose a tool with the same name, the tool names will be prefixed with the server alias you defined in the configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts. Note that the system might strip certain schema properties from MCP tool definitions for compatibility. + - **Description:** Configures connections to one or more Model-Context Protocol (MCP) servers for discovering and using custom tools. Qwen Code attempts to connect to each configured MCP server to discover available tools. If multiple MCP servers expose a tool with the same name, the tool names will be prefixed with the server alias you defined in the configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts. Note that the system might strip certain schema properties from MCP tool definitions for compatibility. At least one of `command`, `url`, or `httpUrl` must be provided. If multiple are specified, the order of precedence is `httpUrl`, then `url`, then `command`. - **Default:** Empty - **Properties:** - **``** (object): The server parameters for the named server. - - `command` (string, required): The command to execute to start the MCP server. + - `command` (string, optional): The command to execute to start the MCP server via standard I/O. - `args` (array of strings, optional): Arguments to pass to the command. - `env` (object, optional): Environment variables to set for the server process. - `cwd` (string, optional): The working directory in which to start the server. + - `url` (string, optional): The URL of an MCP server that uses Server-Sent Events (SSE) for communication. + - `httpUrl` (string, optional): The URL of an MCP server that uses streamable HTTP for communication. + - `headers` (object, optional): A map of HTTP headers to send with requests to `url` or `httpUrl`. - `timeout` (number, optional): Timeout in milliseconds for requests to this MCP server. - `trust` (boolean, optional): Trust this server and bypass all tool call confirmations. + - `description` (string, optional): A brief description of the server, which may be used for display purposes. - `includeTools` (array of strings, optional): List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (whitelist behavior). If not specified, all tools from the server are enabled by default. - `excludeTools` (array of strings, optional): List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server. **Note:** `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded. - **Example:** @@ -161,6 +166,20 @@ In addition to a project settings file, a project's `.qwen` directory can contai "env": { "API_KEY": "$MY_API_TOKEN" } + }, + "mySseServer": { + "url": "http://localhost:8081/events", + "headers": { + "Authorization": "Bearer $MY_SSE_TOKEN" + }, + "description": "An example SSE-based MCP server." + }, + "myStreamableHttpServer": { + "httpUrl": "http://localhost:8082/stream", + "headers": { + "X-API-Key": "$MY_HTTP_API_KEY" + }, + "description": "An example Streamable HTTP-based MCP server." } } ``` @@ -341,7 +360,7 @@ The CLI keeps a history of shell commands you run. To avoid conflicts between di ## Environment Variables & `.env` Files -Environment variables are a common way to configure applications, especially for sensitive information like API keys or for settings that might change between environments. +Environment variables are a common way to configure applications, especially for sensitive information like API keys or for settings that might change between environments. For authentication setup, see the [Authentication documentation](./authentication.md) which covers all available authentication methods. The CLI automatically loads environment variables from an `.env` file. The loading order is: @@ -351,35 +370,16 @@ The CLI automatically loads environment variables from an `.env` file. The loadi **Environment Variable Exclusion:** Some environment variables (like `DEBUG` and `DEBUG_MODE`) are automatically excluded from project `.env` files by default to prevent interference with the CLI behavior. Variables from `.qwen/.env` files are never excluded. You can customize this behavior using the `excludedProjectEnvVars` setting in your `settings.json` file. -- **`GEMINI_API_KEY`** (Required): - - Your API key for the Gemini API. - - **Crucial for operation.** The CLI will not function without it. +- **`OPENAI_API_KEY`**: + - One of several available [authentication methods](./authentication.md). - Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env` file. -- **`GEMINI_MODEL`**: - - Specifies the default Gemini model to use. +- **`OPENAI_BASE_URL`**: + - One of several available [authentication methods](./authentication.md). + - Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env` file. +- **`OPENAI_MODEL`**: + - Specifies the default OPENAI model to use. - Overrides the hardcoded default - - Example: `export GEMINI_MODEL="gemini-2.5-flash"` -- **`GOOGLE_API_KEY`**: - - Your Google Cloud API key. - - Required for using Vertex AI in express mode. - - Ensure you have the necessary permissions. - - Example: `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`. -- **`GOOGLE_CLOUD_PROJECT`**: - - Your Google Cloud Project ID. - - Required for using Code Assist or Vertex AI. - - If using Vertex AI, ensure you have the necessary permissions in this project. - - **Cloud Shell Note:** When running in a Cloud Shell environment, this variable defaults to a special project allocated for Cloud Shell users. If you have `GOOGLE_CLOUD_PROJECT` set in your global environment in Cloud Shell, it will be overridden by this default. To use a different project in Cloud Shell, you must define `GOOGLE_CLOUD_PROJECT` in a `.env` file. - - Example: `export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. -- **`GOOGLE_APPLICATION_CREDENTIALS`** (string): - - **Description:** The path to your Google Application Credentials JSON file. - - **Example:** `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"` -- **`OTLP_GOOGLE_CLOUD_PROJECT`**: - - Your Google Cloud Project ID for Telemetry in Google Cloud - - Example: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. -- **`GOOGLE_CLOUD_LOCATION`**: - - Your Google Cloud Project Location (e.g., us-central1). - - Required for using Vertex AI in non express mode. - - Example: `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`. + - Example: `export OPENAI_MODEL="qwen3-coder-plus"` - **`GEMINI_SANDBOX`**: - Alternative to the `sandbox` setting in `settings.json`. - Accepts `true`, `false`, `docker`, `podman`, or a custom command string. @@ -409,8 +409,8 @@ The CLI automatically loads environment variables from an `.env` file. The loadi Arguments passed directly when running the CLI can override other configurations for that specific session. - **`--model `** (**`-m `**): - - Specifies the Gemini model to use for this session. - - Example: `npm start -- --model gemini-1.5-pro-latest` + - Specifies the Qwen model to use for this session. + - Example: `npm start -- --model qwen3-coder-plus` - **`--prompt `** (**`-p `**): - Used to pass a prompt directly to the command. This invokes Qwen Code in a non-interactive mode. - **`--prompt-interactive `** (**`-i `**): @@ -435,7 +435,7 @@ Arguments passed directly when running the CLI can override other configurations - **`--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 + - `auto_edit`: Automatically approve edit tools (edit, write_file) while prompting for others - `yolo`: Automatically approve all tool calls (equivalent to `--yolo`) - Cannot be used together with `--yolo`. Use `--approval-mode=yolo` instead of `--yolo` for the new unified approach. - Example: `qwen --approval-mode auto_edit` @@ -445,6 +445,8 @@ Arguments passed directly when running the CLI can override other configurations - Sets the telemetry target. See [telemetry](../telemetry.md) for more information. - **`--telemetry-otlp-endpoint`**: - Sets the OTLP endpoint for telemetry. See [telemetry](../telemetry.md) for more information. +- **`--telemetry-otlp-protocol`**: + - Sets the OTLP protocol for telemetry (`grpc` or `http`). Defaults to `grpc`. See [telemetry](../telemetry.md) for more information. - **`--telemetry-log-prompts`**: - Enables logging of prompts for telemetry. See [telemetry](../telemetry.md) for more information. - **`--checkpointing`**: @@ -475,7 +477,7 @@ Arguments passed directly when running the CLI can override other configurations While not strictly configuration for the CLI's _behavior_, context files (defaulting to `QWEN.md` but configurable via the `contextFileName` setting) are crucial for configuring the _instructional context_ (also referred to as "memory"). This powerful feature allows you to give project-specific instructions, coding style guides, or any relevant background information to the AI, making its responses more tailored and accurate to your needs. The CLI includes UI elements, such as an indicator in the footer showing the number of loaded context files, to keep you informed about the active context. -- **Purpose:** These Markdown files contain instructions, guidelines, or context that you want the Gemini model to be aware of during your interactions. The system is designed to manage this instructional context hierarchically. +- **Purpose:** These Markdown files contain instructions, guidelines, or context that you want the Qwen model to be aware of during your interactions. The system is designed to manage this instructional context hierarchically. ### Example Context File Content (e.g., `QWEN.md`) @@ -587,3 +589,11 @@ You can opt out of usage statistics collection at any time by setting the `usage ``` Note: When usage statistics are enabled, events are sent to an Alibaba Cloud RUM collection endpoint. + +- **`enableWelcomeBack`** (boolean): + - **Description:** Show welcome back dialog when returning to a project with conversation history. + - **Default:** `true` + - **Category:** UI + - **Requires Restart:** No + - **Example:** `"enableWelcomeBack": false` + - **Details:** When enabled, Qwen Code will automatically detect if you're returning to a project with a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`) and show a dialog allowing you to continue your previous conversation or start fresh. This feature integrates with the `/chat summary` command and quit confirmation dialog. See the [Welcome Back documentation](./welcome-back.md) for more details. diff --git a/website/content/en/cli/index.md b/website/content/en/cli/index.md index 7827362e..e32eca14 100644 --- a/website/content/en/cli/index.md +++ b/website/content/en/cli/index.md @@ -10,6 +10,7 @@ Within Qwen Code, `packages/cli` is the frontend for users to send and receive p - **[Token Caching](./token-caching.md):** Optimize API costs through token caching. - **[Themes](./themes.md)**: A guide to customizing the CLI's appearance with different themes. - **[Tutorials](tutorials.md)**: A tutorial showing how to use Qwen Code to automate a development task. +- **[Welcome Back](./welcome-back.md)**: Learn about the Welcome Back feature that helps you resume work seamlessly across sessions. ## Non-interactive mode diff --git a/website/content/en/cli/token-caching.md b/website/content/en/cli/token-caching.md index 3e5133eb..8d6dc5ec 100644 --- a/website/content/en/cli/token-caching.md +++ b/website/content/en/cli/token-caching.md @@ -4,7 +4,7 @@ Qwen Code automatically optimizes API costs through token caching when using API **Token caching is available for:** -- API key users (Gemini API key) +- API key users (Qwen API key) - Vertex AI users (with project and location setup) **Token caching is not available for:** diff --git a/website/content/en/cli/welcome-back.md b/website/content/en/cli/welcome-back.md new file mode 100644 index 00000000..0a5acfe8 --- /dev/null +++ b/website/content/en/cli/welcome-back.md @@ -0,0 +1,133 @@ +# Welcome Back Feature + +The Welcome Back feature helps you seamlessly resume your work by automatically detecting when you return to a project with existing conversation history and offering to continue from where you left off. + +## Overview + +When you start Qwen Code in a project directory that contains a previously generated project summary (`.qwen/PROJECT_SUMMARY.md`), the Welcome Back dialog will automatically appear, giving you the option to either start fresh or continue your previous conversation. + +## How It Works + +### Automatic Detection + +The Welcome Back feature automatically detects: + +- **Project Summary File:** Looks for `.qwen/PROJECT_SUMMARY.md` in your current project directory +- **Conversation History:** Checks if there's meaningful conversation history to resume +- **Settings:** Respects your `enableWelcomeBack` setting (enabled by default) + +### Welcome Back Dialog + +When a project summary is found, you'll see a dialog with: + +- **Last Updated Time:** Shows when the summary was last generated +- **Overall Goal:** Displays the main objective from your previous session +- **Current Plan:** Shows task progress with status indicators: + - `[DONE]` - Completed tasks + - `[IN PROGRESS]` - Currently working on + - `[TODO]` - Planned tasks +- **Task Statistics:** Summary of total tasks, completed, in progress, and pending + +### Options + +You have two choices when the Welcome Back dialog appears: + +1. **Start new chat session** + - Closes the dialog and begins a fresh conversation + - No previous context is loaded + +2. **Continue previous conversation** + - Automatically fills the input with: `@.qwen/PROJECT_SUMMARY.md, Based on our previous conversation, Let's continue?` + - Loads the project summary as context for the AI + - Allows you to seamlessly pick up where you left off + +## Configuration + +### Enable/Disable Welcome Back + +You can control the Welcome Back feature through settings: + +**Via Settings Dialog:** + +1. Run `/settings` in Qwen Code +2. Find "Enable Welcome Back" in the UI category +3. Toggle the setting on/off + +**Via Settings File:** +Add to your `.qwen/settings.json`: + +```json +{ + "enableWelcomeBack": true +} +``` + +**Settings Locations:** + +- **User settings:** `~/.qwen/settings.json` (affects all projects) +- **Project settings:** `.qwen/settings.json` (project-specific) + +### Keyboard Shortcuts + +- **Escape:** Close the Welcome Back dialog (defaults to "Start new chat session") + +## Integration with Other Features + +### Project Summary Generation + +The Welcome Back feature works seamlessly with the `/chat summary` command: + +1. **Generate Summary:** Use `/chat summary` to create a project summary +2. **Automatic Detection:** Next time you start Qwen Code in this project, Welcome Back will detect the summary +3. **Resume Work:** Choose to continue and the summary will be loaded as context + +### Quit Confirmation + +When exiting with `/quit-confirm` and choosing "Generate summary and quit": + +1. A project summary is automatically created +2. Next session will trigger the Welcome Back dialog +3. You can seamlessly continue your work + +## File Structure + +The Welcome Back feature creates and uses: + +``` +your-project/ +├── .qwen/ +│ └── PROJECT_SUMMARY.md # Generated project summary +``` + +### PROJECT_SUMMARY.md Format + +The generated summary follows this structure: + +```markdown +# Project Summary + +## Overall Goal + + + +## Key Knowledge + + + + +## Recent Actions + + + + +## Current Plan + + + + +--- + +## Summary Metadata + +**Update time**: 2025-01-10T15:30:00.000Z +``` diff --git a/website/content/en/deployment.md b/website/content/en/deployment.md index 28d7a220..fc9f3c6a 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.9 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 ``` - **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 index a0bd4976..e213d257 100644 --- a/website/content/en/ide-integration.md +++ b/website/content/en/ide-integration.md @@ -1,6 +1,6 @@ # 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. +Qwen Code 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. @@ -11,13 +11,13 @@ Currently, the only supported IDE is [Visual Studio Code](https://code.visualstu - 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. +- **Native Diffing:** When Qwen 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. +- **VS Code Commands:** You can access Qwen Code features directly from the VS Code Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`): + - `Qwen Code: Run`: Starts a new Qwen Code session in the integrated terminal. + - `Qwen Code: Accept Diff`: Accepts the changes in the active diff editor. + - `Qwen Code: Close Diff Editor`: Rejects the changes and closes the active diff editor. + - `Qwen Code: View Third-Party Notices`: Displays the third-party notices for the extension. ## Installation and Setup @@ -25,11 +25,11 @@ 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. +When you run Qwen Code 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: +If you previously dismissed the prompt or want to install the extension manually, you can run the following command inside Qwen Code: ``` /ide install @@ -41,8 +41,8 @@ This will find the correct extension for your IDE and install it. 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. +- **For Visual Studio Code:** Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion). +- **For VS Code Forks:** To support forks of VS Code, the extension is also published on the [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion). Follow your editor's instructions for installing extensions from this registry. After any installation method, it's recommended to open a new terminal window to ensure the integration is activated correctly. Once installed, you can use `/ide enable` to connect. @@ -61,7 +61,7 @@ You can control the IDE integration from within the CLI: /ide disable ``` -When enabled, Gemini CLI will automatically attempt to connect to the IDE companion extension. +When enabled, Qwen Code will automatically attempt to connect to the IDE companion extension. ### Checking the Status @@ -83,14 +83,14 @@ When you ask Gemini to modify a file, it can open a diff view directly in your e - 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**. +- Open the Command Palette and run **Qwen Code: 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**. +- Open the Command Palette and run **Qwen Code: 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. @@ -99,10 +99,10 @@ If you select ‘Yes, allow always’ in the CLI, changes will no longer show up ## Using with Sandboxing -If you are using Gemini CLI within a sandbox, please be aware of the following: +If you are using Qwen Code 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. +- **In a Docker Container:** If you run Qwen Code 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 @@ -111,9 +111,9 @@ If you encounter issues with IDE integration, here are some common error message ### 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. + - **Cause:** Qwen Code could not find the necessary environment variables (`QWEN_CODE_IDE_WORKSPACE_PATH` or `QWEN_CODE_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. + 1. Make sure you have installed the **Qwen Code 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` @@ -122,7 +122,7 @@ If you encounter issues with IDE integration, here are some common error message ### 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.` +- **Message:** `🔴 Disconnected: Directory mismatch. Qwen Code is running in a different location than the open workspace in [IDE Name]. Please run the CLI from the same directory as your project's root folder.` - **Cause:** 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. @@ -132,10 +132,10 @@ If you encounter issues with IDE integration, here are some common error message ### 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:** `IDE integration is not supported in your current environment. To use this feature, run Qwen Code in one of these supported IDEs: [List of IDEs]` + - **Cause:** You are running Qwen Code in a terminal or environment that is not a supported IDE. + - **Solution:** Run Qwen Code from the integrated terminal of a supported IDE, like VS Code. - **Message:** `No installer is available for [IDE Name]. Please install the IDE companion manually from its marketplace.` - **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. + - **Solution:** Open your IDE's extension marketplace, search for "Qwen Code Companion", and install it manually. diff --git a/website/content/en/index.md b/website/content/en/index.md index 9c405645..cf61778d 100644 --- a/website/content/en/index.md +++ b/website/content/en/index.md @@ -31,6 +31,7 @@ This documentation is organized into the following sections: - **[Web Fetch Tool](./tools/web-fetch.md):** Documentation for the `web_fetch` tool. - **[Web Search Tool](./tools/web-search.md):** Documentation for the `web_search` tool. - **[Memory Tool](./tools/memory.md):** Documentation for the `save_memory` tool. +- **[Subagents](./subagents.md):** Specialized AI assistants for focused tasks with comprehensive management, configuration, and usage guidance. - **[Contributing & Development Guide](../CONTRIBUTING.md):** Information for contributors and developers, including setup, building, testing, and coding conventions. - **[NPM Workspaces and Publishing](./npm.md):** Details on how the project's packages are managed and published. - **[Troubleshooting Guide](./troubleshooting.md):** Find solutions to common problems and FAQs. diff --git a/website/content/en/keyboard-shortcuts.md b/website/content/en/keyboard-shortcuts.md index ac50ce73..23c4d79f 100644 --- a/website/content/en/keyboard-shortcuts.md +++ b/website/content/en/keyboard-shortcuts.md @@ -7,7 +7,7 @@ This document lists the available keyboard shortcuts in Qwen Code. | Shortcut | Description | | -------- | --------------------------------------------------------------------------------------------------------------------- | | `Esc` | Close dialogs and suggestions. | -| `Ctrl+C` | Exit the application. Press twice to confirm. | +| `Ctrl+C` | Cancel the ongoing request and clear the input. Press twice to exit the application. | | `Ctrl+D` | Exit the application if the input is empty. Press twice to confirm. | | `Ctrl+L` | Clear the screen. | | `Ctrl+O` | Toggle the display of the debug console. | @@ -60,3 +60,9 @@ This document lists the available keyboard shortcuts in Qwen Code. | `Up Arrow` / `k` | Move selection up. | | `1-9` | Select an item by its number. | | (multi-digit) | For items with numbers greater than 9, press the digits in quick succession to select the corresponding item. | + +## IDE Integration + +| Shortcut | Description | +| -------- | --------------------------------- | +| `Ctrl+G` | See context CLI received from IDE | diff --git a/website/content/en/npm.md b/website/content/en/npm.md index 43332193..0a3c0af2 100644 --- a/website/content/en/npm.md +++ b/website/content/en/npm.md @@ -148,7 +148,7 @@ This command will do the following: 3. Create the package tarballs that would be published to npm. 4. Print a summary of the packages that would be published. -You can then inspect the generated tarballs to ensure that they contain the correct files and that the `package.json` files have been updated correctly. The tarballs will be created in the root of each package's directory (e.g., `packages/cli/google-gemini-cli-0.1.6.tgz`). +You can then inspect the generated tarballs to ensure that they contain the correct files and that the `package.json` files have been updated correctly. The tarballs will be created in the root of each package's directory (e.g., `packages/cli/qwen-code-0.1.6.tgz`). By performing a dry run, you can be confident that your changes to the packaging process are correct and that the packages will be published successfully. @@ -187,7 +187,7 @@ This is the most critical stage where files are moved and transformed into their - File movement: packages/cli/package.json -> (in-memory transformation) -> `bundle`/package.json - Why: The final package.json must be different from the one used in development. Key changes include: - Removing devDependencies. - - Removing workspace-specific "dependencies": { "@gemini-cli/core": "workspace:\*" } and ensuring the core code is + - Removing workspace-specific "dependencies": { "@qwen-code/core": "workspace:\*" } and ensuring the core code is bundled directly into the final JavaScript file. - Ensuring the bin, main, and files fields point to the correct locations within the final package structure. @@ -277,4 +277,4 @@ This tells NPM that any folder inside the `packages` directory is a separate pac - **Simplified Dependency Management**: Running `npm install` from the root of the project will install all dependencies for all packages in the workspace and link them together. This means you don't need to run `npm install` in each package's directory. - **Automatic Linking**: Packages within the workspace can depend on each other. When you run `npm install`, NPM will automatically create symlinks between the packages. This means that when you make changes to one package, the changes are immediately available to other packages that depend on it. -- **Simplified Script Execution**: You can run scripts in any package from the root of the project using the `--workspace` flag. For example, to run the `build` script in the `cli` package, you can run `npm run build --workspace @google/gemini-cli`. +- **Simplified Script Execution**: You can run scripts in any package from the root of the project using the `--workspace` flag. For example, to run the `build` script in the `cli` package, you can run `npm run build --workspace @qwen-code/qwen-code`. diff --git a/website/content/en/subagents.md b/website/content/en/subagents.md new file mode 100644 index 00000000..415df7ce --- /dev/null +++ b/website/content/en/subagents.md @@ -0,0 +1,469 @@ +# Subagents + +Subagents are specialized AI assistants that handle specific types of tasks within Qwen Code. They allow you to delegate focused work to AI agents that are configured with task-specific prompts, tools, and behaviors. + +## What are Subagents? + +Subagents are independent AI assistants that: + +- **Specialize in specific tasks** - Each subagent is configured with a focused system prompt for particular types of work +- **Have separate context** - They maintain their own conversation history, separate from your main chat +- **Use controlled tools** - You can configure which tools each subagent has access to +- **Work autonomously** - Once given a task, they work independently until completion or failure +- **Provide detailed feedback** - You can see their progress, tool usage, and execution statistics in real-time + +## Key Benefits + +- **Task Specialization**: Create agents optimized for specific workflows (testing, documentation, refactoring, etc.) +- **Context Isolation**: Keep specialized work separate from your main conversation +- **Reusability**: Save and reuse agent configurations across projects and sessions +- **Controlled Access**: Limit which tools each agent can use for security and focus +- **Progress Visibility**: Monitor agent execution with real-time progress updates + +## How Subagents Work + +1. **Configuration**: You create subagent configurations that define their behavior, tools, and system prompts +2. **Delegation**: The main AI can automatically delegate tasks to appropriate subagents +3. **Execution**: Subagents work independently, using their configured tools to complete tasks +4. **Results**: They return results and execution summaries back to the main conversation + +## Getting Started + +### Quick Start + +1. **Create your first subagent**: + + ``` + /agents create + ``` + + Follow the guided wizard to create a specialized agent. + +2. **Manage existing agents**: + + ``` + /agents manage + ``` + + View and manage your configured subagents. + +3. **Use subagents automatically**: + Simply ask the main AI to perform tasks that match your subagents' specializations. The AI will automatically delegate appropriate work. + +### Example Usage + +``` +User: "Please write comprehensive tests for the authentication module" + +AI: I'll delegate this to your testing specialist subagent. +[Delegates to "testing-expert" subagent] +[Shows real-time progress of test creation] +[Returns with completed test files and execution summary] +``` + +## Management + +### CLI Commands + +Subagents are managed through the `/agents` slash command and its subcommands: + +#### `/agents create` + +Creates a new subagent through a guided step wizard. + +**Usage:** + +``` +/agents create +``` + +#### `/agents manage` + +Opens an interactive management dialog for viewing and managing existing subagents. + +**Usage:** + +``` +/agents manage +``` + +### Storage Locations + +Subagents are stored as Markdown files in two locations: + +- **Project-level**: `.qwen/agents/` (takes precedence) +- **User-level**: `~/.qwen/agents/` (fallback) + +This allows you to have both project-specific agents and personal agents that work across all projects. + +### File Format + +Subagents are configured using Markdown files with YAML frontmatter. This format is human-readable and easy to edit with any text editor. + +#### Basic Structure + +```markdown +--- +name: agent-name +description: Brief description of when and how to use this agent +tools: tool1, tool2, tool3 # Optional +--- + +System prompt content goes here. +Multiple paragraphs are supported. +You can use ${variable} templating for dynamic content. +``` + +#### Example Usage + +```markdown +--- +name: project-documenter +description: Creates project documentation and README files +--- + +You are a documentation specialist for the ${project_name} project. + +Your task: ${task_description} + +Working directory: ${current_directory} +Generated on: ${timestamp} + +Focus on creating clear, comprehensive documentation that helps both +new contributors and end users understand the project. +``` + +## Examples + +### Development Workflow Agents + +#### Testing Specialist + +Perfect for comprehensive test creation and test-driven development. + +```markdown +--- +name: testing-expert +description: Writes comprehensive unit tests, integration tests, and handles test automation with best practices +tools: read_file, write_file, read_many_files, run_shell_command +--- + +You are a testing specialist focused on creating high-quality, maintainable tests. + +Your expertise includes: + +- Unit testing with appropriate mocking and isolation +- Integration testing for component interactions +- Test-driven development practices +- Edge case identification and comprehensive coverage +- Performance and load testing when appropriate + +For each testing task: + +1. Analyze the code structure and dependencies +2. Identify key functionality, edge cases, and error conditions +3. Create comprehensive test suites with descriptive names +4. Include proper setup/teardown and meaningful assertions +5. Add comments explaining complex test scenarios +6. Ensure tests are maintainable and follow DRY principles + +Always follow testing best practices for the detected language and framework. +Focus on both positive and negative test cases. +``` + +**Use Cases:** + +- "Write unit tests for the authentication service" +- "Create integration tests for the payment processing workflow" +- "Add test coverage for edge cases in the data validation module" + +#### Documentation Writer + +Specialized in creating clear, comprehensive documentation. + +```markdown +--- +name: documentation-writer +description: Creates comprehensive documentation, README files, API docs, and user guides +tools: read_file, write_file, read_many_files, web_search +--- + +You are a technical documentation specialist for ${project_name}. + +Your role is to create clear, comprehensive documentation that serves both +developers and end users. Focus on: + +**For API Documentation:** + +- Clear endpoint descriptions with examples +- Parameter details with types and constraints +- Response format documentation +- Error code explanations +- Authentication requirements + +**For User Documentation:** + +- Step-by-step instructions with screenshots when helpful +- Installation and setup guides +- Configuration options and examples +- Troubleshooting sections for common issues +- FAQ sections based on common user questions + +**For Developer Documentation:** + +- Architecture overviews and design decisions +- Code examples that actually work +- Contributing guidelines +- Development environment setup + +Always verify code examples and ensure documentation stays current with +the actual implementation. Use clear headings, bullet points, and examples. +``` + +**Use Cases:** + +- "Create API documentation for the user management endpoints" +- "Write a comprehensive README for this project" +- "Document the deployment process with troubleshooting steps" + +#### Code Reviewer + +Focused on code quality, security, and best practices. + +```markdown +--- +name: code-reviewer +description: Reviews code for best practices, security issues, performance, and maintainability +tools: read_file, read_many_files +--- + +You are an experienced code reviewer focused on quality, security, and maintainability. + +Review criteria: + +- **Code Structure**: Organization, modularity, and separation of concerns +- **Performance**: Algorithmic efficiency and resource usage +- **Security**: Vulnerability assessment and secure coding practices +- **Best Practices**: Language/framework-specific conventions +- **Error Handling**: Proper exception handling and edge case coverage +- **Readability**: Clear naming, comments, and code organization +- **Testing**: Test coverage and testability considerations + +Provide constructive feedback with: + +1. **Critical Issues**: Security vulnerabilities, major bugs +2. **Important Improvements**: Performance issues, design problems +3. **Minor Suggestions**: Style improvements, refactoring opportunities +4. **Positive Feedback**: Well-implemented patterns and good practices + +Focus on actionable feedback with specific examples and suggested solutions. +Prioritize issues by impact and provide rationale for recommendations. +``` + +**Use Cases:** + +- "Review this authentication implementation for security issues" +- "Check the performance implications of this database query logic" +- "Evaluate the code structure and suggest improvements" + +### Technology-Specific Agents + +#### React Specialist + +Optimized for React development, hooks, and component patterns. + +```markdown +--- +name: react-specialist +description: Expert in React development, hooks, component patterns, and modern React best practices +tools: read_file, write_file, read_many_files, run_shell_command +--- + +You are a React specialist with deep expertise in modern React development. + +Your expertise covers: + +- **Component Design**: Functional components, custom hooks, composition patterns +- **State Management**: useState, useReducer, Context API, and external libraries +- **Performance**: React.memo, useMemo, useCallback, code splitting +- **Testing**: React Testing Library, Jest, component testing strategies +- **TypeScript Integration**: Proper typing for props, hooks, and components +- **Modern Patterns**: Suspense, Error Boundaries, Concurrent Features + +For React tasks: + +1. Use functional components and hooks by default +2. Implement proper TypeScript typing +3. Follow React best practices and conventions +4. Consider performance implications +5. Include appropriate error handling +6. Write testable, maintainable code + +Always stay current with React best practices and avoid deprecated patterns. +Focus on accessibility and user experience considerations. +``` + +**Use Cases:** + +- "Create a reusable data table component with sorting and filtering" +- "Implement a custom hook for API data fetching with caching" +- "Refactor this class component to use modern React patterns" + +#### Python Expert + +Specialized in Python development, frameworks, and best practices. + +```markdown +--- +name: python-expert +description: Expert in Python development, frameworks, testing, and Python-specific best practices +tools: read_file, write_file, read_many_files, run_shell_command +--- + +You are a Python expert with deep knowledge of the Python ecosystem. + +Your expertise includes: + +- **Core Python**: Pythonic patterns, data structures, algorithms +- **Frameworks**: Django, Flask, FastAPI, SQLAlchemy +- **Testing**: pytest, unittest, mocking, test-driven development +- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks +- **Async Programming**: asyncio, async/await patterns +- **Package Management**: pip, poetry, virtual environments +- **Code Quality**: PEP 8, type hints, linting with pylint/flake8 + +For Python tasks: + +1. Follow PEP 8 style guidelines +2. Use type hints for better code documentation +3. Implement proper error handling with specific exceptions +4. Write comprehensive docstrings +5. Consider performance and memory usage +6. Include appropriate logging +7. Write testable, modular code + +Focus on writing clean, maintainable Python code that follows community standards. +``` + +**Use Cases:** + +- "Create a FastAPI service for user authentication with JWT tokens" +- "Implement a data processing pipeline with pandas and error handling" +- "Write a CLI tool using argparse with comprehensive help documentation" + +## Best Practices + +### Design Principles + +#### Single Responsibility Principle + +Each subagent should have a clear, focused purpose. + +**✅ Good:** + +```markdown +--- +name: testing-expert +description: Writes comprehensive unit tests and integration tests +--- +``` + +**❌ Avoid:** + +```markdown +--- +name: general-helper +description: Helps with testing, documentation, code review, and deployment +--- +``` + +**Why:** Focused agents produce better results and are easier to maintain. + +#### Clear Specialization + +Define specific expertise areas rather than broad capabilities. + +**✅ Good:** + +```markdown +--- +name: react-performance-optimizer +description: Optimizes React applications for performance using profiling and best practices +--- +``` + +**❌ Avoid:** + +```markdown +--- +name: frontend-developer +description: Works on frontend development tasks +--- +``` + +**Why:** Specific expertise leads to more targeted and effective assistance. + +#### Actionable Descriptions + +Write descriptions that clearly indicate when to use the agent. + +**✅ Good:** + +```markdown +description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns +``` + +**❌ Avoid:** + +```markdown +description: A helpful code reviewer +``` + +**Why:** Clear descriptions help the main AI choose the right agent for each task. + +### Configuration Best Practices + +#### System Prompt Guidelines + +**Be Specific About Expertise:** + +```markdown +You are a Python testing specialist with expertise in: + +- pytest framework and fixtures +- Mock objects and dependency injection +- Test-driven development practices +- Performance testing with pytest-benchmark +``` + +**Include Step-by-Step Approaches:** + +```markdown +For each testing task: + +1. Analyze the code structure and dependencies +2. Identify key functionality and edge cases +3. Create comprehensive test suites with clear naming +4. Include setup/teardown and proper assertions +5. Add comments explaining complex test scenarios +``` + +**Specify Output Standards:** + +```markdown +Always follow these standards: + +- Use descriptive test names that explain the scenario +- Include both positive and negative test cases +- Add docstrings for complex test functions +- Ensure tests are independent and can run in any order +``` + +## Security Considerations + +- **Tool Restrictions**: Subagents only have access to their configured tools +- **Sandboxing**: All tool execution follows the same security model as direct tool use +- **Audit Trail**: All subagent actions are logged and visible in real-time +- **Access Control**: Project and user-level separation provides appropriate boundaries +- **Sensitive Information**: Avoid including secrets or credentials in agent configurations +- **Production Environments**: Consider separate agents for production vs development environments diff --git a/website/content/en/telemetry.md b/website/content/en/telemetry.md index fdffa7c6..e6f2309d 100644 --- a/website/content/en/telemetry.md +++ b/website/content/en/telemetry.md @@ -74,7 +74,11 @@ qwen --telemetry \ ## Running an OTEL Collector An OTEL Collector is a service that receives, processes, and exports telemetry data. -The CLI sends data using the OTLP/gRPC protocol. +The CLI can send data using either the OTLP/gRPC or OTLP/HTTP protocol. +You can specify which protocol to use via the `--telemetry-otlp-protocol` flag +or the `telemetry.otlpProtocol` setting in your `settings.json` file. See the +[configuration docs](./cli/configuration.md#--telemetry-otlp-protocol) for more +details. Learn more about OTEL exporter standard configuration in [documentation][otel-config-docs]. @@ -188,7 +192,7 @@ Logs are timestamped records of specific events. The following events are logged - `error_type` (if applicable) - `metadata` (if applicable, dictionary of string -> any) -- `qwen-code.api_request`: This event occurs when making a request to Gemini API. +- `qwen-code.api_request`: This event occurs when making a request to Qwen API. - **Attributes**: - `model` - `request_text` (if applicable) @@ -202,7 +206,7 @@ Logs are timestamped records of specific events. The following events are logged - `duration_ms` - `auth_type` -- `qwen-code.api_response`: This event occurs upon receiving a response from Gemini API. +- `qwen-code.api_response`: This event occurs upon receiving a response from Qwen API. - **Attributes**: - `model` - `status_code` @@ -236,6 +240,7 @@ Metrics are numerical measurements of behavior over time. The following metrics - `function_name` - `success` (boolean) - `decision` (string: "accept", "reject", or "modify", if applicable) + - `tool_type` (string: "mcp", or "native", if applicable) - `qwen-code.tool.call.latency` (Histogram, ms): Measures tool call latency. - **Attributes**: @@ -267,3 +272,8 @@ Metrics are numerical measurements of behavior over time. The following metrics - `ai_removed_lines` (Int, if applicable): Number of lines removed/changed by AI. - `user_added_lines` (Int, if applicable): Number of lines added/changed by user in AI proposed changes. - `user_removed_lines` (Int, if applicable): Number of lines removed/changed by user in AI proposed changes. + +- `qwen-code.chat_compression` (Counter, Int): Counts chat compression operations + - **Attributes**: + - `tokens_before`: (Int): Number of tokens in context prior to compression + - `tokens_after`: (Int): Number of tokens in context after compression diff --git a/website/content/en/tools/file-system.md b/website/content/en/tools/file-system.md index 45c1eaa7..7bf90d06 100644 --- a/website/content/en/tools/file-system.md +++ b/website/content/en/tools/file-system.md @@ -136,11 +136,11 @@ Search for a pattern with file filtering and custom result limiting: search_file_content(pattern="function", include="*.js", maxResults=10) ``` -## 6. `replace` (Edit) +## 6. `edit` (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. +`edit` 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. -- **Tool name:** `replace` +- **Tool name:** `edit` - **Display name:** Edit - **File:** `edit.ts` - **Parameters:** @@ -157,8 +157,8 @@ search_file_content(pattern="function", include="*.js", maxResults=10) - If `old_string` is provided, it reads the `file_path` and attempts to find exactly one occurrence of `old_string`. - If one occurrence is found, it replaces it with `new_string`. - **Enhanced Reliability (Multi-Stage Edit Correction):** To significantly improve the success rate of edits, especially when the model-provided `old_string` might not be perfectly precise, the tool incorporates a multi-stage edit correction mechanism. - - If the initial `old_string` isn't found or matches multiple locations, the tool can leverage the Gemini model to iteratively refine `old_string` (and potentially `new_string`). - - This self-correction process attempts to identify the unique segment the model intended to modify, making the `replace` operation more robust even with slightly imperfect initial context. + - If the initial `old_string` isn't found or matches multiple locations, the tool can leverage the Qwen model to iteratively refine `old_string` (and potentially `new_string`). + - This self-correction process attempts to identify the unique segment the model intended to modify, making the `edit` operation more robust even with slightly imperfect initial context. - **Failure conditions:** Despite the correction mechanism, the tool will fail if: - `file_path` is not absolute or is outside the root directory. - `old_string` is not empty, but the `file_path` does not exist. diff --git a/website/content/en/tools/mcp-server.md b/website/content/en/tools/mcp-server.md index 46c23bc0..07cea5e3 100644 --- a/website/content/en/tools/mcp-server.md +++ b/website/content/en/tools/mcp-server.md @@ -25,7 +25,7 @@ The discovery process is orchestrated by `discoverMcpTools()`, which: 1. **Iterates through configured servers** from your `settings.json` `mcpServers` configuration 2. **Establishes connections** using appropriate transport mechanisms (Stdio, SSE, or Streamable HTTP) 3. **Fetches tool definitions** from each server using the MCP protocol -4. **Sanitizes and validates** tool schemas for compatibility with the Gemini API +4. **Sanitizes and validates** tool schemas for compatibility with the Qwen API 5. **Registers tools** in the global tool registry with conflict resolution ### Execution Layer (`mcp-tool.ts`) @@ -333,7 +333,7 @@ Upon successful connection: 1. **Tool listing:** The client calls the MCP server's tool listing endpoint 2. **Schema validation:** Each tool's function declaration is validated 3. **Tool filtering:** Tools are filtered based on `includeTools` and `excludeTools` configuration -4. **Name sanitization:** Tool names are cleaned to meet Gemini API requirements: +4. **Name sanitization:** Tool names are cleaned to meet Qwen API requirements: - Invalid characters (non-alphanumeric, underscore, dot, hyphen) are replaced with underscores - Names longer than 63 characters are truncated with middle replacement (`___`) @@ -468,7 +468,7 @@ Discovery State: COMPLETED ### Tool Usage -Once discovered, MCP tools are available to the Gemini model like built-in tools. The model will automatically: +Once discovered, MCP tools are available to the Qwen model like built-in tools. The model will automatically: 1. **Select appropriate tools** based on your requests 2. **Present confirmation dialogs** (unless the server is trusted) @@ -566,7 +566,7 @@ The MCP integration tracks several states: ### Schema Compatibility -- **Property stripping:** The system automatically removes certain schema properties (`$schema`, `additionalProperties`) for Gemini API compatibility +- **Property stripping:** The system automatically removes certain schema properties (`$schema`, `additionalProperties`) for Qwen API compatibility - **Name sanitization:** Tool names are automatically sanitized to meet API requirements - **Conflict resolution:** Tool name conflicts between servers are resolved through automatic prefixing @@ -620,7 +620,7 @@ When Qwen Code receives this response, it will: 2. Present the image data as a separate `inlineData` part. 3. Provide a clean, user-friendly summary in the CLI, indicating that both text and an image were received. -This enables you to build sophisticated tools that can provide rich, multi-modal context to the Gemini model. +This enables you to build sophisticated tools that can provide rich, multi-modal context to the Qwen model. ## MCP Prompts as Slash Commands diff --git a/website/content/en/tools/memory.md b/website/content/en/tools/memory.md index 0b0c2674..6359f013 100644 --- a/website/content/en/tools/memory.md +++ b/website/content/en/tools/memory.md @@ -35,7 +35,7 @@ save_memory(fact="My preferred programming language is Python.") Store a project-specific detail: ``` -save_memory(fact="The project I'm currently working on is called 'gemini-cli'.") +save_memory(fact="The project I'm currently working on is called 'qwen-code'.") ``` ## Important notes diff --git a/website/content/en/tools/web-fetch.md b/website/content/en/tools/web-fetch.md index 3c58d7ae..21fdc54d 100644 --- a/website/content/en/tools/web-fetch.md +++ b/website/content/en/tools/web-fetch.md @@ -42,7 +42,7 @@ web_fetch(url="https://arxiv.org/abs/2401.0001", prompt="What are the key findin Analyze GitHub documentation: ``` -web_fetch(url="https://github.com/google/gemini-react/blob/main/README.md", prompt="What are the installation steps and main features?") +web_fetch(url="https://github.com/QwenLM/Qwen/blob/main/README.md", prompt="What are the installation steps and main features?") ``` ## Important notes diff --git a/website/content/en/troubleshooting.md b/website/content/en/troubleshooting.md index e9252dba..ca7b5195 100644 --- a/website/content/en/troubleshooting.md +++ b/website/content/en/troubleshooting.md @@ -9,16 +9,6 @@ This guide provides solutions to common issues and debugging tips, including top ## Authentication or login errors -- **Error: `Failed to login. Message: Request contains an invalid argument`** - - Users with Google Workspace accounts or Google Cloud accounts - associated with their Gmail accounts may not be able to activate the free - tier of the Google Code Assist plan. - - For Google Cloud accounts, you can work around this by setting - `GOOGLE_CLOUD_PROJECT` to your project ID. - - Alternatively, you can obtain the Gemini API key from - [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. @@ -37,7 +27,7 @@ This guide provides solutions to common issues and debugging tips, including top Refer to [Qwen Code Configuration](./cli/configuration.md) for more details. - **Q: Why don't I see cached token counts in my stats output?** - - A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Gemini API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Gemini Code Assist API does not support cached content creation. You can still view your total token usage using the `/stats` command. + - A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Qwen API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Qwen Code Assist API does not support cached content creation. You can still view your total token usage using the `/stats` command. ## Common error messages and solutions diff --git a/website/content/fr/Uninstall.md b/website/content/fr/Uninstall.md index fbbc96ef..857f1b65 100644 --- a/website/content/fr/Uninstall.md +++ b/website/content/fr/Uninstall.md @@ -1,12 +1,12 @@ # Désinstaller la CLI -La méthode de désinstallation dépend de la façon dont vous avez exécuté la CLI. Suivez les instructions correspondant à l'utilisation de npx ou d'une installation npm globale. +La méthode de désinstallation dépend de la façon dont vous avez exécuté la CLI. Suivez les instructions correspondant à l'utilisation de `npx` ou d'une installation globale via `npm`. ## Méthode 1 : Utilisation de npx -npx exécute les packages depuis un cache temporaire sans installation permanente. Pour "désinstaller" la CLI, vous devez vider ce cache, ce qui supprimera gemini-cli ainsi que tous les autres packages précédemment exécutés avec npx. +`npx` exécute les packages depuis un cache temporaire sans installation permanente. Pour "désinstaller" la CLI, vous devez vider ce cache, ce qui supprimera `qwen-code` ainsi que tous les autres packages précédemment exécutés avec `npx`. -Le cache de npx est un répertoire nommé `_npx` situé dans le dossier principal du cache npm. Vous pouvez trouver le chemin de votre cache npm en exécutant `npm config get cache`. +Le cache de `npx` est un répertoire nommé `_npx` situé dans le dossier principal du cache npm. Vous pouvez trouver le chemin de votre cache npm en exécutant la commande `npm config get cache`. **Pour macOS / Linux** diff --git a/website/content/fr/checkpointing.md b/website/content/fr/checkpointing.md index c78b0bb8..2580146e 100644 --- a/website/content/fr/checkpointing.md +++ b/website/content/fr/checkpointing.md @@ -1,22 +1,22 @@ # Checkpointing -Qwen Code inclut une fonctionnalité de Checkpointing qui sauvegarde automatiquement un snapshot de l'état de votre projet avant que des modifications de fichiers soient effectuées par des outils alimentés par l'IA. Cela vous permet d'expérimenter et d'appliquer en toute sécurité des changements de code, sachant que vous pouvez instantanément revenir à l'état précédent l'exécution de l'outil. +Qwen Code inclut une fonctionnalité de Checkpointing qui sauvegarde automatiquement un snapshot de l'état de votre projet avant que des modifications de fichiers ne soient effectuées par des outils alimentés par l'IA. Cela vous permet d'expérimenter et d'appliquer des changements de code en toute sécurité, sachant que vous pouvez instantanément revenir à l'état précédent l'exécution de l'outil. ## Fonctionnement -Lorsque vous approuvez un outil qui modifie le système de fichiers (comme `write_file` ou `replace`), le CLI crée automatiquement un "checkpoint". Ce checkpoint inclut : +Lorsque vous approuvez un outil qui modifie le système de fichiers (comme `write_file` ou `edit`), le CLI crée automatiquement un "checkpoint". Ce checkpoint inclut : -1. **Un snapshot Git :** Un commit est effectué dans un dépôt Git spécial et caché situé dans votre répertoire personnel (`~/.qwen/history/`). Ce snapshot capture l'état complet de vos fichiers de projet à ce moment-là. Il n'interfère **pas** avec le dépôt Git de votre propre projet. -2. **Historique de conversation :** La conversation entière que vous avez eue avec l'agent jusqu'à ce point est sauvegardée. -3. **L'appel de l'outil :** L'appel spécifique de l'outil sur le point d'être exécuté est également stocké. +1. **Un snapshot Git :** Un commit est effectué dans un dépôt Git spécial et caché situé dans votre répertoire personnel (`~/.qwen/history/`). Ce snapshot capture l'état complet des fichiers de votre projet à ce moment-là. Il n'interfère **pas** avec le dépôt Git de votre propre projet. +2. **L'historique de la conversation :** La conversation entière que vous avez eue avec l'agent jusqu'à ce point est sauvegardée. +3. **L'appel de l'outil :** L'appel spécifique de l'outil sur le point d'être exécuté est également stocké. Si vous souhaitez annuler la modification ou simplement revenir en arrière, vous pouvez utiliser la commande `/restore`. Restaurer un checkpoint va : - Rétablir tous les fichiers de votre projet à l'état capturé dans le snapshot. -- Restaurer l'historique de conversation dans le CLI. -- Reproposer l'appel d'outil original, vous permettant de le relancer, le modifier ou simplement l'ignorer. +- Restaurer l'historique de la conversation dans le CLI. +- Reproposer l'appel initial de l'outil, vous permettant de le relancer, le modifier ou simplement l'ignorer. -Toutes les données du checkpoint, y compris le snapshot Git et l'historique de conversation, sont stockées localement sur votre machine. Le snapshot Git est conservé dans le dépôt fantôme, tandis que l'historique de conversation et les appels d'outils sont enregistrés dans un fichier JSON dans le répertoire temporaire de votre projet, généralement situé à `~/.qwen/tmp//checkpoints`. +Toutes les données des checkpoints, y compris le snapshot Git et l'historique de conversation, sont stockées localement sur votre machine. Le snapshot Git est conservé dans le dépôt caché, tandis que l'historique de conversation et les appels d'outils sont enregistrés dans un fichier JSON dans le répertoire temporaire de votre projet, généralement situé à `~/.qwen/tmp//checkpoints`. ## Activation de la fonctionnalité @@ -56,7 +56,7 @@ Pour voir la liste de tous les checkpoints sauvegardés pour le projet en cours, /restore ``` -La CLI affichera la liste des fichiers de checkpoint disponibles. Ces noms de fichiers sont généralement composés d'un timestamp, du nom du fichier modifié, et du nom de l'outil qui allait être exécuté (par exemple, `2025-06-22T10-00-00_000Z-my-file.txt-write_file`). +Le CLI affichera la liste des fichiers de checkpoint disponibles. Ces noms de fichiers sont généralement composés d'un timestamp, du nom du fichier modifié, et du nom de l'outil qui allait être exécuté (par exemple, `2025-06-22T10-00-00_000Z-my-file.txt-write_file`). ### Restaurer un Checkpoint Spécifique diff --git a/website/content/fr/cli/commands.md b/website/content/fr/cli/commands.md index 065fdf29..3912118d 100644 --- a/website/content/fr/cli/commands.md +++ b/website/content/fr/cli/commands.md @@ -1,6 +1,6 @@ # Commandes CLI -Qwen Code prend en charge plusieurs commandes intégrées pour vous aider à gérer votre session, personnaliser l'interface et contrôler son comportement. Ces commandes sont préfixées par une barre oblique (`/`), un symbole arobase (`@`), ou un point d'exclamation (`!`). +Qwen Code prend en charge plusieurs commandes intégrées pour vous aider à gérer votre session, personnaliser l'interface et contrôler son comportement. Ces commandes sont préfixées par une barre oblique (`/`), un symbole arobase (`@`) ou un point d'exclamation (`!`). ## Commandes slash (`/`) @@ -9,21 +9,21 @@ Les commandes slash fournissent un contrôle de niveau méta sur le CLI lui-mêm ### Commandes intégrées - **`/bug`** - - **Description :** Signaler un problème concernant Qwen Code. Par défaut, le problème est signalé dans le repository GitHub de Qwen Code. La chaîne de caractères saisie après `/bug` devient le titre du bug signalé. Le comportement par défaut de `/bug` peut être modifié à l’aide du paramètre `bugCommand` dans vos fichiers `.qwen/settings.json`. + - **Description :** Signaler un problème concernant Qwen Code. Par défaut, le problème est signalé dans le dépôt GitHub de Qwen Code. La chaîne de caractères saisie après `/bug` devient le titre du bug signalé. Le comportement par défaut de `/bug` peut être modifié en utilisant le paramètre `bugCommand` dans vos fichiers `.qwen/settings.json`. - **`/chat`** - - **Description :** Sauvegarder et reprendre l’historique des conversations pour gérer des états de conversation multiples de manière interactive, ou reprendre un état précédent lors d’une session ultérieure. + - **Description :** Sauvegarder et reprendre l'historique des conversations pour gérer des états de conversation multiples de manière interactive, ou reprendre un état précédent lors d'une session ultérieure. - **Sous-commandes :** - **`save`** - - **Description :** Sauvegarde l’historique de la conversation actuelle. Vous devez ajouter une `` pour identifier l’état de la conversation. + - **Description :** Sauvegarde l'historique de la conversation en cours. Vous devez ajouter une `` pour identifier l'état de la conversation. - **Usage :** `/chat save ` - - **Détails sur l’emplacement des checkpoints :** Les emplacements par défaut des checkpoints de chat sauvegardés sont : - - Linux/macOS : `~/.config/google-generative-ai/checkpoints/` - - Windows : `C:\Users\\AppData\Roaming\google-generative-ai\checkpoints\` + - **Emplacement des checkpoints :** Les emplacements par défaut des checkpoints de chat sauvegardés sont : + - Linux/macOS : `~/.config/qwen-code/checkpoints/` + - Windows : `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` - Lorsque vous exécutez `/chat list`, le CLI ne scanne que ces répertoires spécifiques pour trouver les checkpoints disponibles. - **Note :** Ces checkpoints servent à sauvegarder et reprendre manuellement les états de conversation. Pour les checkpoints automatiques créés avant les modifications de fichiers, consultez la [documentation sur les checkpoints](../checkpointing.md). - **`resume`** - - **Description :** Reprend une conversation à partir d’une sauvegarde précédente. + - **Description :** Reprend une conversation à partir d'une sauvegarde précédente. - **Usage :** `/chat resume ` - **`list`** - **Description :** Liste les tags disponibles pour reprendre un état de conversation. @@ -32,45 +32,56 @@ Les commandes slash fournissent un contrôle de niveau méta sur le CLI lui-mêm - **Usage :** `/chat delete ` - **`/clear`** - - **Description :** Efface l’écran du terminal, y compris l’historique de session visible et le défilement dans le CLI. Les données de session sous-jacentes (pour rappel de l’historique) peuvent être conservées selon l’implémentation exacte, mais l’affichage visuel est effacé. - - **Raccourci clavier :** Appuyez sur **Ctrl+L** à tout moment pour effectuer une action d’effacement. + - **Description :** Efface l'écran du terminal, y compris l'historique de session visible et le défilement dans le CLI. Les données de session sous-jacentes (pour rappel de l'historique) peuvent être conservées selon l'implémentation exacte, mais l'affichage visuel est effacé. + - **Raccourci clavier :** Appuyez sur **Ctrl+L** à tout moment pour effectuer une action d'effacement. + +- **`/summary`** + - **Description :** Génère un résumé complet du projet à partir de l'historique de conversation actuel et le sauvegarde dans `.qwen/PROJECT_SUMMARY.md`. Ce résumé inclut l'objectif global, les connaissances clés, les actions récentes et le plan actuel, ce qui est parfait pour reprendre le travail lors de sessions futures. + - **Usage :** `/summary` + - **Fonctionnalités :** + - Analyse l'historique complet de la conversation pour extraire le contexte important + - Crée un résumé structuré en markdown avec des sections pour les objectifs, les connaissances, les actions et les plans + - Sauvegarde automatiquement dans `.qwen/PROJECT_SUMMARY.md` à la racine de votre projet + - Affiche des indicateurs de progression pendant la génération et la sauvegarde + - S'intègre à la fonction Welcome Back pour une reprise de session fluide + - **Note :** Cette commande nécessite une conversation active avec au moins 2 messages pour générer un résumé pertinent. - **`/compress`** - - **Description :** Remplace tout le contexte de la conversation par un résumé. Cela permet d’économiser des tokens pour les tâches futures tout en conservant un résumé de haut niveau de ce qui s’est passé. + - **Description :** Remplace tout le contexte de chat par un résumé. Cela permet d'économiser les tokens utilisés pour les tâches futures tout en conservant un résumé de haut niveau de ce qui s'est produit. - **`/copy`** - **Description :** Copie la dernière sortie produite par Qwen Code dans votre presse-papiers, pour un partage ou une réutilisation facile. - **`/directory`** (ou **`/dir`**) - - **Description :** Gérer les répertoires de l’espace de travail pour la prise en charge de plusieurs répertoires. + - **Description :** Gérer les répertoires de l'espace de travail pour la prise en charge multi-répertoires. - **Sous-commandes :** - **`add`** : - - **Description :** Ajoute un répertoire à l’espace de travail. Le chemin peut être absolu ou relatif au répertoire de travail actuel. De plus, les chemins relatifs au répertoire utilisateur sont également pris en charge. - - **Usage :** `/directory add ,` - - **Note :** Désactivé dans les profils sandbox restrictifs. Si vous utilisez ce type de profil, utilisez plutôt `--include-directories` au démarrage de la session. + - **Description :** Ajoute un répertoire à l'espace de travail. Le chemin peut être absolu ou relatif au répertoire de travail actuel. De plus, la référence depuis le répertoire personnel est également prise en charge. + - **Usage :** `/directory add ,` + - **Note :** Désactivé dans les profils sandbox restrictifs. Si vous l'utilisez, utilisez plutôt `--include-directories` lors du démarrage de la session. - **`show`** : - - **Description :** Affiche tous les répertoires ajoutés via `/directory add` et `--include-directories`. + - **Description :** Affiche tous les répertoires ajoutés par `/directory add` et `--include-directories`. - **Usage :** `/directory show` - **`/directory`** (ou **`/dir`**) - - **Description :** Gérer les répertoires de l’espace de travail pour la prise en charge de plusieurs répertoires. + - **Description :** Gérer les répertoires de l'espace de travail pour la prise en charge multi-répertoires. - **Sous-commandes :** - **`add`** : - - **Description :** Ajoute un répertoire à l’espace de travail. Le chemin peut être absolu ou relatif au répertoire de travail actuel. De plus, les chemins relatifs au répertoire utilisateur sont également pris en charge. - - **Usage :** `/directory add ,` - - **Note :** Désactivé dans les profils sandbox restrictifs. Si vous utilisez ce type de profil, utilisez plutôt `--include-directories` au démarrage de la session. + - **Description :** Ajoute un répertoire à l'espace de travail. Le chemin peut être absolu ou relatif au répertoire de travail actuel. De plus, la référence depuis le répertoire personnel est également prise en charge. + - **Usage :** `/directory add ,` + - **Note :** Désactivé dans les profils sandbox restrictifs. Si vous l'utilisez, utilisez plutôt `--include-directories` lors du démarrage de la session. - **`show`** : - - **Description :** Affiche tous les répertoires ajoutés via `/directory add` et `--include-directories`. + - **Description :** Affiche tous les répertoires ajoutés par `/directory add` et `--include-directories`. - **Usage :** `/directory show` - **`/editor`** - - **Description :** Ouvre une boîte de dialogue pour sélectionner un éditeur pris en charge. + - **Description :** Ouvre une boîte de dialogue pour sélectionner les éditeurs pris en charge. - **`/extensions`** - **Description :** Liste toutes les extensions actives dans la session Qwen Code actuelle. Voir [Extensions Qwen Code](../extension.md). - **`/help`** (ou **`/?`**) - - **Description :** Affiche les informations d’aide concernant Qwen Code, y compris les commandes disponibles et leur utilisation. + - **Description :** Affiche les informations d'aide concernant Qwen Code, y compris les commandes disponibles et leur utilisation. - **`/mcp`** - **Description :** Liste les serveurs Model Context Protocol (MCP) configurés, leur statut de connexion, les détails du serveur et les outils disponibles. @@ -78,71 +89,95 @@ Les commandes slash fournissent un contrôle de niveau méta sur le CLI lui-mêm - **`desc`** ou **`descriptions`** : - **Description :** Affiche des descriptions détaillées des serveurs et outils MCP. - **`nodesc`** ou **`nodescriptions`** : - - **Description :** Masque les descriptions des outils, n’affichant que les noms des outils. + - **Description :** Masque les descriptions des outils, n'affichant que les noms des outils. - **`schema`** : - - **Description :** Affiche le schéma JSON complet des paramètres configurés de l’outil. - - **Raccourci clavier :** Appuyez sur **Ctrl+T** à tout moment pour basculer entre l’affichage et le masquage des descriptions des outils. + - **Description :** Affiche le schéma JSON complet des paramètres configurés de l'outil. + - **Raccourci clavier :** Appuyez sur **Ctrl+T** à tout moment pour basculer entre l'affichage et le masquage des descriptions d'outils. - **`/memory`** - - **Description :** Gérer le contexte instructionnel de l’IA (mémoire hiérarchique chargée depuis les fichiers `QWEN.md` par défaut ; configurable via `contextFileName`). + - **Description :** Gérer le contexte instructionnel de l'IA (mémoire hiérarchique chargée depuis les fichiers `QWEN.md` par défaut ; configurable via `contextFileName`). - **Sous-commandes :** - **`add`** : - - **Description :** Ajoute le texte suivant à la mémoire de l’IA. Usage : `/memory add ` + - **Description :** Ajoute le texte suivant à la mémoire de l'IA. Usage : `/memory add ` - **`show`** : - - **Description :** Affiche le contenu complet et concaténé de la mémoire hiérarchique actuelle, chargée depuis tous les fichiers de contexte (ex. : `QWEN.md`). Cela vous permet d’inspecter le contexte instructionnel fourni au modèle. + - **Description :** Affiche le contenu complet et concaténé de la mémoire hiérarchique actuelle chargée depuis tous les fichiers de contexte (ex : `QWEN.md`). Cela vous permet d'inspecter le contexte instructionnel fourni au modèle. - **`refresh`** : - - **Description :** Recharge la mémoire instructionnelle hiérarchique depuis tous les fichiers de contexte (par défaut : `QWEN.md`) trouvés dans les emplacements configurés (global, projet/ancêtres, et sous-répertoires). Cela met à jour le modèle avec le contenu de contexte le plus récent. - - **Note :** Pour plus de détails sur la manière dont les fichiers de contexte contribuent à la mémoire hiérarchique, voir la [documentation sur la configuration du CLI](./configuration.md#context-files-hierarchical-instructional-context). + - **Description :** Recharge la mémoire instructionnelle hiérarchique depuis tous les fichiers de contexte (par défaut : `QWEN.md`) trouvés dans les emplacements configurés (global, projet/ancêtres et sous-répertoires). Cela met à jour le modèle avec le contenu de contexte le plus récent. + - **Note :** Pour plus de détails sur la contribution des fichiers de contexte à la mémoire hiérarchique, voir la [documentation de configuration du CLI](./configuration.md#context-files-hierarchical-instructional-context). - **`/restore`** - - **Description :** Restaure les fichiers du projet à l’état dans lequel ils se trouvaient juste avant l’exécution d’un outil. C’est particulièrement utile pour annuler les modifications de fichiers effectuées par un outil. S’il est exécuté sans ID d’appel d’outil, il liste les checkpoints disponibles à partir desquels restaurer. + - **Description :** Restaure les fichiers du projet à l'état dans lequel ils se trouvaient juste avant l'exécution d'un outil. C'est particulièrement utile pour annuler les modifications de fichiers effectuées par un outil. S'il est exécuté sans ID d'appel d'outil, il listera les checkpoints disponibles pour la restauration. - **Usage :** `/restore [tool_call_id]` - - **Note :** Disponible uniquement si le CLI est invoqué avec l’option `--checkpointing` ou configuré via les [paramètres](./configuration.md). Voir la [documentation sur les checkpoints](../checkpointing.md) pour plus de détails. + - **Note :** Disponible uniquement si le CLI est invoqué avec l'option `--checkpointing` ou configuré via [les paramètres](./configuration.md). Voir la [documentation sur les checkpoints](../checkpointing.md) pour plus de détails. - **`/settings`** - - **Description :** Ouvre l’éditeur de paramètres pour afficher et modifier les paramètres de Qwen Code. - - **Détails :** Cette commande fournit une interface conviviale pour modifier les paramètres qui contrôlent le comportement et l’apparence de Qwen Code. Elle équivaut à modifier manuellement le fichier `.qwen/settings.json`, mais avec validation et assistance pour éviter les erreurs. - - **Usage :** Exécutez simplement `/settings` et l’éditeur s’ouvrira. Vous pouvez alors parcourir ou rechercher des paramètres spécifiques, consulter leurs valeurs actuelles et les modifier selon vos besoins. Les modifications de certains paramètres sont appliquées immédiatement, tandis que d’autres nécessitent un redémarrage. + - **Description :** Ouvre l'éditeur de paramètres pour afficher et modifier les paramètres de Qwen Code. + - **Détails :** Cette commande fournit une interface conviviale pour modifier les paramètres qui contrôlent le comportement et l'apparence de Qwen Code. Elle équivaut à modifier manuellement le fichier `.qwen/settings.json`, mais avec validation et assistance pour éviter les erreurs. + - **Usage :** Exécutez simplement `/settings` et l'éditeur s'ouvrira. Vous pouvez alors parcourir ou rechercher des paramètres spécifiques, afficher leurs valeurs actuelles et les modifier selon vos besoins. Les modifications de certains paramètres sont appliquées immédiatement, tandis que d'autres nécessitent un redémarrage. - **`/stats`** - - **Description :** Affiche des statistiques détaillées sur la session Qwen Code actuelle, notamment l’utilisation des tokens, les économies de tokens mis en cache (lorsque disponibles) et la durée de la session. Note : Les informations sur les tokens mis en cache ne sont affichées que lorsque ces derniers sont utilisés, ce qui se produit avec l’authentification par clé API mais pas avec l’authentification OAuth pour le moment. + - **Description :** Affiche des statistiques détaillées pour la session Qwen Code actuelle, y compris l'utilisation des tokens, les économies de tokens mis en cache (lorsque disponibles) et la durée de la session. Note : Les informations sur les tokens mis en cache ne sont affichées que lorsque des tokens mis en cache sont utilisés, ce qui se produit avec l'authentification par clé API mais pas avec l'authentification OAuth pour le moment. - [**`/theme`**](./themes.md) - - **Description :** Ouvre une boîte de dialogue vous permettant de modifier le thème visuel de Qwen Code. + - **Description :** Ouvre une boîte de dialogue qui vous permet de modifier le thème visuel de Qwen Code. - **`/auth`** - - **Description :** Ouvre une boîte de dialogue vous permettant de modifier la méthode d’authentification. + - **Description :** Ouvre une boîte de dialogue qui vous permet de modifier la méthode d'authentification. - **`/about`** - - **Description :** Affiche les informations de version. Veuillez partager ces informations lorsque vous signalez un problème. + - **Description :** Affiche les informations de version. Veuillez partager ces informations lors du signalement de problèmes. + +- **`/agents`** + - **Description :** Gérer les sous-agents IA spécialisés pour des tâches ciblées. Les sous-agents sont des assistants IA indépendants configurés avec une expertise spécifique et un accès à des outils. + - **Sous-commandes :** + - **`create`** : + - **Description :** Lance un assistant interactif pour créer un nouveau sous-agent. L'assistant vous guide à travers la sélection d'emplacement, la génération de prompts assistée par IA, la sélection d'outils et la personnalisation visuelle. + - **Usage :** `/agents create` + - **`manage`** : + - **Description :** Ouvre une boîte de dialogue de gestion interactive pour afficher, modifier et supprimer les sous-agents existants. Affiche les agents au niveau projet et au niveau utilisateur. + - **Usage :** `/agents manage` + - **Emplacements de stockage :** + - **Niveau projet :** `.qwen/agents/` (partagé avec l'équipe, prioritaire) + - **Niveau utilisateur :** `~/.qwen/agents/` (agents personnels, disponibles dans tous les projets) + - **Note :** Pour des informations détaillées sur la création et la gestion des sous-agents, voir la [documentation sur les sous-agents](../subagents.md). - [**`/tools`**](../tools/index.md) - - **Description :** Affiche la liste des outils actuellement disponibles dans Qwen Code. + - **Description :** Affiche une liste des outils actuellement disponibles dans Qwen Code. - **Sous-commandes :** - **`desc`** ou **`descriptions`** : - - **Description :** Affiche des descriptions détaillées de chaque outil, incluant le nom de chaque outil avec sa description complète telle que fournie au modèle. + - **Description :** Affiche des descriptions détaillées de chaque outil, y compris le nom de chaque outil avec sa description complète telle que fournie au modèle. - **`nodesc`** ou **`nodescriptions`** : - - **Description :** Masque les descriptions des outils, n’affichant que les noms des outils. + - **Description :** Masque les descriptions des outils, n'affichant que les noms des outils. - **`/privacy`** - - **Description :** Affiche la Politique de confidentialité et permet aux utilisateurs de choisir s’ils consentent à la collecte de leurs données à des fins d’amélioration du service. + - **Description :** Affiche l'Avis de confidentialité et permet aux utilisateurs de choisir s'ils consentent à la collecte de leurs données à des fins d'amélioration du service. + +- **`/quit-confirm`** + - **Description :** Affiche une boîte de dialogue de confirmation avant de quitter Qwen Code, vous permettant de choisir comment gérer votre session actuelle. + - **Usage :** `/quit-confirm` + - **Fonctionnalités :** + - **Quitter immédiatement :** Quitter sans sauvegarder quoi que ce soit (équivalent à `/quit`) + - **Générer un résumé et quitter :** Créer un résumé du projet en utilisant `/summary` avant de quitter + - **Sauvegarder la conversation et quitter :** Sauvegarder la conversation actuelle avec un tag généré automatiquement avant de quitter + - **Raccourci clavier :** Appuyez deux fois sur **Ctrl+C** pour déclencher la boîte de dialogue de confirmation de sortie + - **Note :** Cette commande est automatiquement déclenchée lorsque vous appuyez une fois sur Ctrl+C, fournissant un mécanisme de sécurité pour prévenir les sorties accidentelles. - **`/quit`** (ou **`/exit`**) - - **Description :** Quitte Qwen Code. + - **Description :** Quitte Qwen Code immédiatement sans boîte de dialogue de confirmation. - **`/vim`** - - **Description :** Active ou désactive le mode vim. Lorsque le mode vim est activé, la zone de saisie prend en charge les commandes de navigation et d’édition de type vim dans les modes NORMAL et INSERT. + - **Description :** Active ou désactive le mode vim. Lorsque le mode vim est activé, la zone de saisie prend en charge les commandes de navigation et d'édition de style vim dans les modes NORMAL et INSERT. - **Fonctionnalités :** - - **Mode NORMAL :** Naviguer avec `h`, `j`, `k`, `l` ; se déplacer par mots avec `w`, `b`, `e` ; aller au début/fin de ligne avec `0`, `$`, `^` ; aller à une ligne spécifique avec `G` (ou `gg` pour la première ligne) - - **Mode INSERT :** Saisie de texte standard avec échappement pour revenir au mode NORMAL - - **Commandes d’édition :** Supprimer avec `x`, modifier avec `c`, insérer avec `i`, `a`, `o`, `O` ; opérations complexes comme `dd`, `cc`, `dw`, `cw` - - **Support des compteurs :** Préfixer les commandes avec des nombres (ex. : `3h`, `5w`, `10G`) - - **Répétition de la dernière commande :** Utiliser `.` pour répéter la dernière opération d’édition - - **Paramètre persistant :** La préférence du mode vim est enregistrée dans `~/.qwen/settings.json` et restaurée entre les sessions - - **Indicateur de statut :** Lorsqu’il est activé, affiche `[NORMAL]` ou `[INSERT]` dans le pied de page + - **Mode NORMAL :** Naviguer avec `h`, `j`, `k`, `l` ; se déplacer par mots avec `w`, `b`, `e` ; aller au début/fin de ligne avec `0`, `$`, `^` ; aller à des lignes spécifiques avec `G` (ou `gg` pour la première ligne) + - **Mode INSERT :** Saisie de texte standard avec échappement pour retourner au mode NORMAL + - **Commandes d'édition :** Supprimer avec `x`, changer avec `c`, insérer avec `i`, `a`, `o`, `O` ; opérations complexes comme `dd`, `cc`, `dw`, `cw` + - **Support des compteurs :** Préfixer les commandes avec des nombres (ex : `3h`, `5w`, `10G`) + - **Répétition de la dernière commande :** Utiliser `.` pour répéter la dernière opération d'édition + - **Paramètre persistant :** La préférence du mode vim est sauvegardée dans `~/.qwen/settings.json` et restaurée entre les sessions + - **Indicateur de statut :** Lorsqu'activé, affiche `[NORMAL]` ou `[INSERT]` dans le pied de page - **`/init`** - - **Description :** Analyse le répertoire actuel et crée un fichier de contexte `QWEN.md` par défaut (ou le nom de fichier spécifié par `contextFileName`). Si un fichier non vide existe déjà, aucune modification n’est apportée. La commande crée un fichier vide et invite le modèle à le remplir avec des instructions spécifiques au projet. + - **Description :** Analyse le répertoire actuel et crée un fichier de contexte `QWEN.md` par défaut (ou le nom de fichier spécifié par `contextFileName`). Si un fichier non vide existe déjà, aucune modification n'est apportée. La commande initialise un fichier vide et invite le modèle à le remplir avec des instructions spécifiques au projet. ### Commandes personnalisées @@ -150,63 +185,89 @@ Pour un démarrage rapide, consultez l'[exemple](#example-a-pure-function-refact Les commandes personnalisées vous permettent de sauvegarder et de réutiliser vos prompts favoris ou les plus fréquemment utilisés comme des raccourcis personnels au sein de Qwen Code. Vous pouvez créer des commandes spécifiques à un seul projet ou des commandes disponibles globalement sur tous vos projets, ce qui rationalise votre workflow et garantit la cohérence. -#### Emplacement des fichiers & Priorité +#### Emplacement des fichiers et priorité Qwen Code découvre les commandes à partir de deux emplacements, chargés dans un ordre spécifique : -1. **Commandes utilisateur (globales) :** Situées dans `~/.qwen/commands/`. Ces commandes sont disponibles dans n'importe quel projet sur lequel vous travaillez. -2. **Commandes de projet (locales) :** Situées dans `/.qwen/commands/`. Ces commandes sont spécifiques au projet en cours et peuvent être ajoutées au contrôle de version pour être partagées avec votre équipe. +1. **Commandes utilisateur (globales)** : situées dans `~/.qwen/commands/`. Ces commandes sont disponibles dans n'importe quel projet sur lequel vous travaillez. +2. **Commandes de projet (locales)** : situées dans `/.qwen/commands/`. Ces commandes sont spécifiques au projet en cours et peuvent être ajoutées au contrôle de version pour être partagées avec votre équipe. -Si une commande dans le répertoire du projet porte le même nom qu'une commande dans le répertoire utilisateur, la **commande du projet sera toujours utilisée.** Cela permet aux projets de remplacer les commandes globales par des versions spécifiques au projet. +Si une commande dans le répertoire du projet porte le même nom qu'une commande dans le répertoire utilisateur, **la commande du projet sera toujours utilisée.** Cela permet aux projets de remplacer les commandes globales par des versions spécifiques au projet. -#### Nommer et structurer les commandes (Namespacing) +#### Nommer et structurer les espaces de noms -Le nom d'une commande est déterminé par son chemin relatif par rapport au répertoire `commands`. Les sous-répertoires permettent de créer des commandes avec un namespace, le séparateur de chemin (`/` ou `\`) étant converti en deux-points (`:`). +Le nom d'une commande est déterminé par son chemin de fichier relatif au répertoire `commands`. Les sous-répertoires sont utilisés pour créer des commandes avec un espace de noms, le séparateur de chemin (`/` ou `\`) étant converti en deux-points (`:`). - Un fichier situé à `~/.qwen/commands/test.toml` devient la commande `/test`. - Un fichier situé à `/.qwen/commands/git/commit.toml` devient la commande namespacée `/git:commit`. #### Format de fichier TOML (v1) -Les fichiers de définition des commandes doivent être écrits au format TOML et utiliser l’extension `.toml`. +Vos fichiers de définition de commande doivent être écrits au format TOML et utiliser l'extension `.toml`. ##### Champs obligatoires -- `prompt` (String) : Le prompt qui sera envoyé au modèle lorsque la commande est exécutée. Il peut s'agir d'une chaîne sur une seule ligne ou multi-lignes. +- `prompt` (String) : Le prompt qui sera envoyé au modèle lorsque la commande est exécutée. Il peut s'agir d'une chaîne de caractères sur une ou plusieurs lignes. ##### Champs optionnels -- `description` (String) : Une brève description, sur une seule ligne, expliquant ce que fait la commande. Ce texte sera affiché à côté de votre commande dans le menu `/help`. **Si ce champ est omis, une description générique sera générée à partir du nom du fichier.** +- `description` (String) : Une brève description, sur une seule ligne, expliquant ce que fait la commande. Ce texte sera affiché à côté de votre commande dans le menu `/help`. **Si vous omettez ce champ, une description générique sera générée à partir du nom du fichier.** #### Gestion des Arguments -Les commandes personnalisées prennent en charge deux méthodes puissantes et simples pour gérer les arguments. Le CLI choisit automatiquement la bonne méthode en fonction du contenu du `prompt` de votre commande. +Les commandes personnalisées prennent en charge deux méthodes puissantes pour gérer les arguments. Le CLI choisit automatiquement la bonne méthode en fonction du contenu du `prompt` de votre commande. + +##### 1. Injection Contextuelle avec `{{args}}` -##### 1. Injection Simplifiée avec `{{args}}` +Si votre `prompt` contient le placeholder spécial `{{args}}`, le CLI remplacera ce placeholder par le texte que l'utilisateur a tapé après le nom de la commande. -Si votre `prompt` contient le placeholder spécial `{{args}}`, le CLI remplacera ce placeholder exact par tout le texte que l'utilisateur a tapé après le nom de la commande. C'est parfait pour les commandes simples et déterministes où vous devez injecter l'entrée utilisateur à un endroit spécifique d'un template de prompt plus large. +Le comportement de cette injection dépend de l'endroit où elle est utilisée : + +**A. Injection Brute (En dehors des Commandes Shell)** + +Lorsqu'elle est utilisée dans le corps principal du prompt, les arguments sont injectés exactement comme l'utilisateur les a tapés. **Exemple (`git/fix.toml`) :** ```toml -# In: ~/.qwen/commands/git/fix.toml - -```markdown -# Invoqué via : /git:fix "Button is misaligned on mobile" +# Invoqué via : /git:fix "Button is misaligned" -description = "Génère un fix pour un issue GitHub donnée." -prompt = "Veuillez analyser les modifications git staged et fournir un code fix pour l'issue décrite ici : {{args}}." +description = "Génère un correctif pour un problème donné." +prompt = "Veuillez fournir un correctif de code pour le problème décrit ici : {{args}}." ``` -Le modèle recevra le prompt final : `Veuillez analyser les modifications git staged et fournir un code fix pour l'issue décrite ici : "Button is misaligned on mobile".` +Le modèle reçoit : `Veuillez fournir un correctif de code pour le problème décrit ici : "Button is misaligned".` + +**B. Utilisation des Arguments dans les Commandes Shell (À l'intérieur des blocs `!{...}`)** + +Lorsque vous utilisez `{{args}}` à l'intérieur d'un bloc d'injection shell (`!{...}`), les arguments sont automatiquement **échappés pour le shell** avant remplacement. Cela vous permet de passer des arguments en toute sécurité aux commandes shell, en garantissant que la commande résultante est syntaxiquement correcte et sécurisée, tout en évitant les vulnérabilités d'injection de commande. + +**Exemple (`/grep-code.toml`) :** + +```toml +prompt = """ +Veuillez résumer les résultats pour le motif `{{args}}`. + +Résultats de la recherche : +!{grep -r {{args}} .} +""" ``` +Lorsque vous exécutez `/grep-code It's complicated` : + +1. Le CLI détecte que `{{args}}` est utilisé à la fois en dehors et à l'intérieur de `!{...}`. +2. En dehors : Le premier `{{args}}` est remplacé tel quel par `It's complicated`. +3. À l'intérieur : Le second `{{args}}` est remplacé par la version échappée (par exemple, sur Linux : `"It's complicated"`). +4. La commande exécutée est `grep -r "It's complicated" .`. +5. Le CLI vous demande de confirmer cette commande exacte et sécurisée avant exécution. +6. Le prompt final est envoyé. + ##### 2. Gestion des arguments par défaut -Si votre `prompt` ne contient **pas** le placeholder spécial `{{args}}`, le CLI utilise un comportement par défaut pour gérer les arguments. +Si votre `prompt` ne contient **pas** le placeholder spécial `{{args}}`, la CLI utilise un comportement par défaut pour gérer les arguments. -Si vous fournissez des arguments à la commande (par exemple, `/mycommand arg1`), le CLI ajoutera la commande complète que vous avez tapée à la fin du prompt, séparée par deux sauts de ligne. Cela permet au modèle de voir à la fois les instructions originales et les arguments spécifiques que vous venez de fournir. +Si vous fournissez des arguments à la commande (par exemple, `/mycommand arg1`), la CLI ajoutera la commande complète que vous avez tapée à la fin du prompt, séparée par deux sauts de ligne. Cela permet au modèle de voir à la fois les instructions originales et les arguments spécifiques que vous venez de fournir. Si vous ne fournissez **aucun** argument (par exemple, `/mycommand`), le prompt est envoyé au modèle tel quel, sans rien ajouter. @@ -233,12 +294,13 @@ Votre tâche consiste à parser ``, ``, et `` dep ## Format attendu La commande suit ce format : `/changelog ` -- `` doit être l'un des suivants : "added", "changed", "fixed", "removed".""" +- `` doit être parmi : "added", "changed", "fixed", "removed".""" +```markdown ## Comportement 1. Lire le fichier `CHANGELOG.md`. 2. Trouver la section correspondant à la `` spécifiée. -3. Ajouter le `` sous l'en-tête `` approprié. +3. Ajouter le `` sous le titre `` approprié. 4. Si la section version ou type n'existe pas, la créer. 5. Suivre strictement le format "Keep a Changelog". """ @@ -248,20 +310,17 @@ Lorsque vous exécutez `/changelog 1.2.0 added "New feature"`, le texte final en ##### 3. Exécution de commandes Shell avec `!{...}` -Vous pouvez rendre vos commandes dynamiques en exécutant directement des commandes shell au sein de votre `prompt` et en injectant leur sortie. C'est idéal pour récupérer du contexte depuis votre environnement local, comme lire le contenu d'un fichier ou vérifier l'état de Git. +Vous pouvez rendre vos commandes dynamiques en exécutant directement des commandes shell dans votre `prompt` et en injectant leur sortie. C'est idéal pour récupérer du contexte depuis votre environnement local, comme lire le contenu d'un fichier ou vérifier l'état de Git. -Lorsqu'une commande personnalisée tente d'exécuter une commande shell, Qwen Code vous demandera maintenant une confirmation avant de procéder. Il s'agit d'une mesure de sécurité pour s'assurer que seules les commandes intentionnelles peuvent être exécutées. +Lorsqu'une commande personnalisée tente d'exécuter une commande shell, Qwen Code vous demandera maintenant une confirmation avant de continuer. Il s'agit d'une mesure de sécurité pour s'assurer que seules les commandes voulues sont exécutées. **Fonctionnement :** -1. **Injection de commandes :** Utilisez la syntaxe `!{...}` dans votre `prompt` pour spécifier où la commande doit être exécutée et où sa sortie doit être injectée. -2. **Confirmation d'exécution :** Lorsque vous exécutez la commande, une boîte de dialogue apparaîtra listant les commandes shell que le prompt souhaite exécuter. -3. **Accorder l'autorisation :** Vous pouvez choisir de : - - **Autoriser une fois :** La ou les commandes seront exécutées cette fois-ci uniquement. - - **Toujours autoriser pour cette session :** La ou les commandes seront ajoutées à une liste temporaire d'autorisations pour la session CLI en cours et ne nécessiteront plus de confirmation. - - **Non :** Annuler l'exécution de la ou des commandes shell. - -Le CLI respecte toujours les paramètres globaux `excludeTools` et `coreTools`. Une commande sera bloquée sans demande de confirmation si elle est explicitement interdite dans votre configuration. +1. **Injection de commandes :** Utilisez la syntaxe `!{...}`. +2. **Substitution des arguments :** Si `{{args}}` est présent dans le bloc, il est automatiquement échappé pour le shell (voir [Injection contextuelle](#1-context-aware-injection-with-args) ci-dessus). +3. **Parsing robuste :** L'analyseur gère correctement les commandes shell complexes contenant des accolades imbriquées, comme les payloads JSON. +4. **Vérification de sécurité et confirmation :** Le CLI effectue une vérification de sécurité sur la commande finale résolue (après échappement et substitution des arguments). Une boîte de dialogue apparaîtra montrant la ou les commandes exactes à exécuter. +5. **Exécution et rapport d'erreurs :** La commande est exécutée. Si la commande échoue, la sortie injectée dans le prompt inclura les messages d'erreur (stderr) suivis d'une ligne indiquant le statut, par exemple `[Shell command exited with code 1]`. Cela permet au modèle de comprendre le contexte de l'échec. **Exemple (`git/commit.toml`) :** @@ -285,11 +344,11 @@ Veuillez générer un message de commit Conventional Commit basé sur le git dif """ -``` +```` -Quand vous exécutez `/git:commit`, le CLI exécute d'abord `git diff --staged`, puis remplace `!{git diff --staged}` par la sortie de cette commande avant d'envoyer le prompt final et complet au modèle. +Lorsque vous exécutez `/git:commit`, le CLI exécute d'abord `git diff --staged`, puis remplace `!{git diff --staged}` par la sortie de cette commande avant d'envoyer le prompt final et complet au modèle. -#### Exemple : Commande de refactoring "Fonction pure" +#### Exemple : Commande de refactoring "Fonction Pure" Créons une commande globale qui demande au modèle de refactorer un morceau de code. @@ -310,6 +369,7 @@ Ouvrez `~/.qwen/commands/refactor/pure.toml` dans votre éditeur et ajoutez le c # In: ~/.qwen/commands/refactor/pure.toml +```markdown # Cette commande sera invoquée via : /refactor:pure description = "Demande au modèle de refactorer le contexte actuel en une fonction pure." @@ -337,25 +397,25 @@ Qwen Code exécutera alors le prompt multiligne défini dans votre fichier TOML. ## Commandes At (`@`) -Les commandes At sont utilisées pour inclure le contenu de fichiers ou de répertoires dans votre prompt envoyé au modèle. Ces commandes prennent en compte le filtrage git-aware. +Les commandes At sont utilisées pour inclure le contenu de fichiers ou de répertoires dans votre prompt envoyé au modèle. Ces commandes prennent en charge le filtrage git-aware. - **`@`** - - **Description :** Injecte le contenu du ou des fichiers spécifiés dans votre prompt actuel. Cela est utile pour poser des questions sur du code spécifique, du texte ou des collections de fichiers. + - **Description :** Injecte le contenu du fichier ou des fichiers spécifiés dans votre prompt actuel. Cela est utile pour poser des questions sur du code spécifique, du texte ou des collections de fichiers. - **Exemples :** - `@chemin/vers/votre/fichier.txt Explique ce texte.` - `@src/mon_projet/ Résume le code dans ce répertoire.` - `De quoi parle ce fichier ? @README.md` - **Détails :** - Si un chemin vers un seul fichier est fourni, le contenu de ce fichier est lu. - - Si un chemin vers un répertoire est fourni, la commande tente de lire le contenu des fichiers présents dans ce répertoire et ses sous-répertoires. + - Si un chemin vers un répertoire est fourni, la commande tente de lire le contenu des fichiers dans ce répertoire et ses sous-répertoires. - Les espaces dans les chemins doivent être échappés avec un antislash (ex. : `@Mes\ Documents/fichier.txt`). - La commande utilise en interne l'outil `read_many_files`. Le contenu est récupéré puis inséré dans votre requête avant d'être envoyé au modèle. - **Filtrage git-aware :** Par défaut, les fichiers ignorés par git (comme `node_modules/`, `dist/`, `.env`, `.git/`) sont exclus. Ce comportement peut être modifié via les paramètres `fileFiltering`. - - **Types de fichiers :** La commande est destinée aux fichiers textuels. Bien qu'elle puisse tenter de lire n'importe quel fichier, les fichiers binaires ou très volumineux peuvent être ignorés ou tronqués par l'outil `read_many_files` sous-jacent afin d'assurer performance et pertinence. L'outil indique si des fichiers ont été ignorés. - - **Sortie :** Le CLI affichera un message d'appel à l'outil indiquant que `read_many_files` a été utilisé, accompagné d'un message détaillant le statut et les chemins qui ont été traités. + - **Types de fichiers :** La commande est destinée aux fichiers textuels. Bien qu'elle puisse tenter de lire n'importe quel fichier, les fichiers binaires ou très volumineux peuvent être ignorés ou tronqués par l'outil `read_many_files` sous-jacent afin de garantir performance et pertinence. L'outil indique si des fichiers ont été ignorés. + - **Sortie :** Le CLI affichera un message d'appel d'outil indiquant que `read_many_files` a été utilisé, accompagné d'un message détaillant le statut et les chemins traités. - **`@` (Symbole @ seul)** - - **Description :** Si vous tapez uniquement le symbole `@` sans préciser de chemin, la requête est transmise telle quelle au modèle. Cela peut être utile si vous parlez _explicitement_ du symbole `@` dans votre prompt. + - **Description :** Si vous tapez un symbole `@` seul sans chemin, la requête est transmise telle quelle au modèle. Cela peut être utile si vous parlez _explicitement_ du symbole `@` dans votre prompt. ### Gestion des erreurs pour les commandes `@` @@ -372,14 +432,14 @@ Le préfixe `!` vous permet d'interagir directement avec le shell de votre syst - `!ls -la` (exécute `ls -la` et retourne à Qwen Code) - `!git status` (exécute `git status` et retourne à Qwen Code) -- **`!` (Basculer en mode shell)** - - **Description :** Saisir `!` seul permet de basculer en mode shell. - - **Entrée en mode shell :** - - Lorsqu'il est actif, le mode shell utilise une coloration différente et un "Shell Mode Indicator". +- **`!` (Activer/désactiver le mode shell)** + - **Description :** Saisir `!` seul active ou désactive le mode shell. + - **Entrer en mode shell :** + - Une fois activé, le mode shell utilise une coloration différente et un "Shell Mode Indicator". - En mode shell, le texte que vous saisissez est interprété directement comme une commande shell. - - **Sortie du mode shell :** - - Une fois sorti, l'interface retrouve son apparence standard et le comportement normal de Qwen Code reprend. + - **Sortir du mode shell :** + - Une fois désactivé, l'interface retrouve son apparence standard et le comportement normal de Qwen Code reprend. -- **Précaution pour toute utilisation de `!` :** Les commandes que vous exécutez en mode shell ont les mêmes permissions et le même impact que si vous les exécutiez directement dans votre terminal. +- **Attention pour toute utilisation de `!` :** Les commandes que vous exécutez en mode shell ont les mêmes permissions et le même impact que si vous les exécutiez directement dans votre terminal. -- **Variable d'environnement :** Lorsqu'une commande est exécutée via `!` ou en mode shell, la variable d'environnement `QWEN_CODE=1` est définie dans l'environnement du sous-processus. Cela permet aux scripts ou outils de détecter s'ils sont exécutés depuis l'interface CLI. \ No newline at end of file +- **Variable d'environnement :** Lorsqu'une commande est exécutée via `!` ou en mode shell, la variable d'environnement `QWEN_CODE=1` est définie dans l'environnement du sous-processus. Cela permet aux scripts ou outils de détecter s'ils sont exécutés depuis le CLI. \ No newline at end of file diff --git a/website/content/fr/cli/configuration.md b/website/content/fr/cli/configuration.md index b81f82a4..dd5ef04e 100644 --- a/website/content/fr/cli/configuration.md +++ b/website/content/fr/cli/configuration.md @@ -7,7 +7,7 @@ Qwen Code offre plusieurs façons de configurer son comportement, notamment via La configuration est appliquée selon l'ordre de priorité suivant (les numéros inférieurs sont écrasés par les numéros supérieurs) : 1. **Valeurs par défaut :** Valeurs codées en dur dans l'application. -2. **Fichier de configuration utilisateur :** Paramètres globaux pour l'utilisateur courant. +2. **Fichier de configuration utilisateur :** Paramètres globaux pour l'utilisateur actuel. 3. **Fichier de configuration projet :** Paramètres spécifiques au projet. 4. **Fichier de configuration système :** Paramètres applicables à l'ensemble du système. 5. **Variables d'environnement :** Variables globales au système ou spécifiques à une session, pouvant être chargées depuis des fichiers `.env`. @@ -23,11 +23,12 @@ Qwen Code utilise des fichiers `settings.json` pour la configuration persistante - **Fichier de configuration projet :** - **Emplacement :** `.qwen/settings.json` à la racine de votre projet. - **Portée :** S'applique uniquement lorsque Qwen Code est exécuté depuis ce projet spécifique. Les paramètres du projet prennent le pas sur ceux de l'utilisateur. + - **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 un environnement d'entreprise pour contrôler les configurations Qwen Code des utilisateurs. + - **Emplacement :** `/etc/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) ou `/Library/Application Support/QwenCode/settings.json` (macOS). Ce chemin peut être modifié via la variable d'environnement `QWEN_CODE_SYSTEM_SETTINGS_PATH`. + - **Portée :** S'applique à toutes les sessions Qwen Code sur le système, pour tous les utilisateurs. Les paramètres système prennent le pas sur ceux de l'utilisateur et du projet. Peut être utile aux administrateurs système dans les entreprises pour contrôler les configurations Qwen Code des utilisateurs. -**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"`. +**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"`. ### Le répertoire `.qwen` dans votre projet @@ -58,7 +59,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 listages 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 listes de fichiers. - **`enableRecursiveFileSearch`** (boolean) : Indique si la recherche récursive des fichiers doit être activée lors de la complétion des préfixes @ dans le prompt. - **Exemple :** ```json @@ -69,30 +70,30 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro ``` - **`coreTools`** (tableau de strings) : - - **Description :** Permet de spécifier une liste d'outils intégrés qui doivent être disponibles pour le modèle. Cela peut servir à restreindre les outils intégrés. Voir [Built-in Tools](../core/tools-api.md#built-in-tools) pour la liste des outils. Vous pouvez également spécifier des restrictions par commande pour les outils qui le supportent, comme `ShellTool`. Par exemple, `"coreTools": ["ShellTool(ls -l)"]` n'autorisera que la commande `ls -l`. + - **Description :** Permet de spécifier une liste d'outils intégrés qui doivent être disponibles pour le modèle. Cela peut servir à restreindre l'ensemble des outils intégrés. Voir [Built-in Tools](../core/tools-api.md#built-in-tools) pour la liste des outils. Vous pouvez également spécifier des restrictions par commande pour les outils qui le supportent, comme `ShellTool`. Par exemple, `"coreTools": ["ShellTool(ls -l)"]` n'autorisera que la commande `ls -l`. - **Par défaut :** Tous les outils disponibles pour le modèle. - **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 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 à la fois dans `excludeTools` et `coreTools` est exclu. Vous pouvez également spécifier des restrictions par commande pour les outils compatibles, comme `ShellTool`. Par exemple, `"excludeTools": ["ShellTool(rm -rf)"]` bloquera la commande `rm -rf`. - **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 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. + - **Note de sécurité :** Les restrictions par commande dans `excludeTools` pour `run_shell_command` reposent sur une simple comparaison de chaînes de caractères et peuvent être facilement contournées. Cette fonctionnalité **n'est pas un mécanisme de sécurité** et ne doit pas être utilisée pour exécuter du code non fiable en toute sécurité. Il est recommandé d'utiliser `coreTools` pour sélectionner explicitement les commandes autorisées. - **`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. + - **Description :** Permet de spécifier une liste de serveurs MCP qui doivent être disponibles pour le modèle. Cela peut servir à restreindre l'ensemble des serveurs MCP auxquels se connecter. Notez que ce paramètre est ignoré si `--allowed-mcp-server-names` est défini. + - **Par défaut :** Tous les serveurs MCP sont disponibles pour le modèle. - **Exemple :** `"allowMCPServers": ["myPythonServer"]`. - - **Note de sécurité :** Ce paramètre utilise une simple 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. + - **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. - **`excludeMCPServers`** (tableau de strings) : - - **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. + - **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. - **Par défaut :** Aucun serveur MCP exclu. - **Exemple :** `"excludeMCPServers": ["myNodeServer"]`. - - **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. + - **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. - **`autoAccept`** (boolean) : - - **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. + - **Description :** Contrôle si le CLI accepte et exécute automatiquement les appels d'outils jugés sûrs (ex. opérations en lecture seule) sans confirmation explicite de l'utilisateur. Si `true`, le CLI contourne la demande de confirmation pour les outils considérés comme sûrs. - **Par défaut :** `false` - **Exemple :** `"autoAccept": true` @@ -102,7 +103,7 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro - **Exemple :** `"theme": "GitHub"` - **`vimMode`** (boolean) : - - **Description :** Active ou désactive le mode vim pour l'édition de texte. Lorsqu'il est activé, la zone de saisie prend en charge les commandes de navigation et d'édition de type vim avec les modes NORMAL et INSERT. Le statut du mode vim est affiché dans le pied de page et persiste entre les sessions. + - **Description :** Active ou désactive le mode vim pour l'édition de texte. Lorsqu'il est activé, la zone de saisie supporte les commandes de navigation et d'édition de type vim avec les modes NORMAL et INSERT. Le statut du mode vim est affiché dans le footer et persiste entre les sessions. - **Par défaut :** `false` - **Exemple :** `"vimMode": true` @@ -112,7 +113,7 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro - **Exemple :** `"sandbox": "docker"` - **`toolDiscoveryCommand`** (string) : - - **Description :** Définit une commande shell personnalisée pour découvrir les outils depuis votre projet. La commande doit retourner sur `stdout` un tableau JSON de [déclarations de fonctions](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). Les wrappers d'outils sont optionnels. + - **Description :** Définit une commande shell personnalisée pour découvrir les outils de votre projet. La commande doit retourner sur `stdout` un tableau JSON de [déclarations de fonctions](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). Les wrappers d'outils sont optionnels. - **Par défaut :** Vide - **Exemple :** `"toolDiscoveryCommand": "bin/get_tools"` @@ -125,18 +126,22 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro - **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. Le système peut retirer certaines propriétés de 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. Notez que le système peut retirer certaines propriétés de schéma des définitions d'outils MCP pour des raisons de compatibilité. Au moins un des champs `command`, `url` ou `httpUrl` doit être fourni. Si plusieurs sont spécifiés, l'ordre de priorité est : `httpUrl`, puis `url`, puis `command`. - **Par défaut :** Vide - **Propriétés :** - **``** (objet) : Les paramètres du serveur nommé. - - `command` (string, requis) : La commande à exécuter pour démarrer le serveur MCP. + - `command` (string, optionnel) : La commande à exécuter pour démarrer le serveur MCP via les E/S standards. - `args` (tableau de strings, optionnel) : Arguments à passer à la commande. - `env` (objet, optionnel) : Variables d'environnement à définir pour le processus du serveur. - `cwd` (string, optionnel) : Le répertoire de travail dans lequel démarrer le serveur. - - `timeout` (number, optionnel) : Délai d'attente en millisecondes pour les requêtes vers ce serveur MCP. + - `url` (string, optionnel) : L'URL d'un serveur MCP utilisant Server-Sent Events (SSE) pour communiquer. + - `httpUrl` (string, optionnel) : L'URL d'un serveur MCP utilisant HTTP streamable pour communiquer. + - `headers` (objet, optionnel) : Une map d'en-têtes HTTP à envoyer avec les requêtes vers `url` ou `httpUrl`. + - `timeout` (number, optionnel) : Timeout en millisecondes pour les requêtes vers ce serveur MCP. - `trust` (boolean, optionnel) : Faire confiance à ce serveur et contourner toutes les confirmations d'appel d'outils. - - `includeTools` (tableau de strings, optionnel) : Liste des noms d'outils à inclure depuis ce serveur MCP. Si spécifié, seuls les outils listés ici seront disponibles (comportement en liste blanche). Sinon, tous les outils du serveur sont activés par défaut. - - `excludeTools` (tableau de strings, optionnel) : Liste des noms d'outils à exclure depuis ce serveur MCP. Les outils listés ici ne seront pas disponibles pour le modèle, même s'ils sont exposés par le serveur. **Note :** `excludeTools` a priorité sur `includeTools` – si un outil est dans les deux listes, il sera exclu. + - `description` (string, optionnel) : Une brève description du serveur, pouvant être utilisée à des fins d'affichage. + - `includeTools` (tableau de strings, optionnel) : Liste des noms d'outils à inclure depuis ce serveur MCP. Si spécifié, seuls les outils listés ici seront disponibles (comportement whitelist). Sinon, tous les outils du serveur sont activés par défaut. + - `excludeTools` (tableau de strings, optionnel) : Liste des noms d'outils à exclure de ce serveur MCP. Les outils listés ici ne seront pas disponibles pour le modèle, même s'ils sont exposés par le serveur. **Note :** `excludeTools` a priorité sur `includeTools` – si un outil est dans les deux listes, il sera exclu. - **Exemple :** ```json "mcpServers": { @@ -159,6 +164,20 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro "env": { "API_KEY": "$MY_API_TOKEN" } + }, + "mySseServer": { + "url": "http://localhost:8081/events", + "headers": { + "Authorization": "Bearer $MY_SSE_TOKEN" + }, + "description": "An example SSE-based MCP server." + }, + "myStreamableHttpServer": { + "httpUrl": "http://localhost:8082/stream", + "headers": { + "X-API-Key": "$MY_HTTP_API_KEY" + }, + "description": "An example Streamable HTTP-based MCP server." } } ``` @@ -175,12 +194,12 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro - **Exemple :** `"preferredEditor": "vscode"` - **`telemetry`** (objet) : - - **Description :** Configure la journalisation et la collecte de métriques pour Qwen Code. Pour plus d'informations, voir [Telemetry](../telemetry.md). + - **Description :** Configure la collecte de logs et de métriques pour Qwen Code. Pour plus d'informations, voir [Telemetry](../telemetry.md). - **Par défaut :** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **Propriétés :** - **`enabled`** (boolean) : Active ou désactive la télémétrie. - **`target`** (string) : Destination des données de télémétrie. Valeurs supportées : `local` et `gcp`. - - **`otlpEndpoint`** (string) : Endpoint de l'exportateur OTLP. + - **`otlpEndpoint`** (string) : Endpoint pour l'exportateur OTLP. - **`logPrompts`** (boolean) : Indique si le contenu des prompts utilisateur doit être inclus dans les logs. - **Exemple :** ```json @@ -225,32 +244,12 @@ En plus d'un fichier de configuration du projet, le répertoire `.qwen` d'un pro ``` - **`summarizeToolOutput`** (objet) : - - **Description :** Active ou désactive le résumé de la sortie des outils. Vous pouvez spécifier le budget de tokens pour le résumé via le paramètre `tokenBudget`. + - **Description :** Active ou désactive le résumé des sorties d'outils. Vous pouvez spécifier le budget de tokens pour le résumé via le paramètre `tokenBudget`. - Note : Actuellement, seul l'outil `run_shell_command` est supporté. - - **Par défaut :** `{}` (désactivé par défaut) - - **Exemple :** - ```json - "summarizeToolOutput": { - "run_shell_command": { - "tokenBudget": 2000 - } - } - ``` - -- **`excludedProjectEnvVars`** (tableau de strings) : - - **Description :** Spécifie les variables d'environnement à exclure du chargement depuis les fichiers `.env` du projet. Cela empêche les variables spécifiques au projet (comme `DEBUG=true`) d'interférer avec le comportement du CLI. Les variables des fichiers `.qwen/.env` ne sont jamais exclues. - - **Par défaut :** `["DEBUG", "DEBUG_MODE"]` + - **Par défaut :** `{}` (Désactivé par défaut) - **Exemple :** ```json - "excludedProjectEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"] - ``` - -- **`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` : @@ -297,64 +296,45 @@ Le CLI conserve un historique des commandes shell que vous exécutez. Pour évit - **Emplacement :** `~/.qwen/tmp//shell_history` - `` est un identifiant unique généré à partir du chemin racine de votre projet. - - L'historique est enregistré dans un fichier nommé `shell_history`. + - L'historique est stocké dans un fichier nommé `shell_history`. ## Variables d'environnement et fichiers `.env` -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. +Les variables d'environnement sont une méthode courante pour configurer les applications, en particulier pour les informations sensibles comme les clés API ou les paramètres qui peuvent varier selon les environnements. Pour la configuration de l'authentification, consultez la [documentation sur l'authentification](./authentication.md) qui couvre toutes les méthodes disponibles. Le CLI charge automatiquement les variables d'environnement depuis un fichier `.env`. L'ordre de chargement est le suivant : -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. Le fichier `.env` dans le répertoire de travail courant. +2. S'il n'est pas trouvé, il remonte dans les répertoires parents jusqu'à trouver un fichier `.env` ou atteindre la racine du projet (identifiée par un dossier `.git`) ou le répertoire utilisateur. +3. Si toujours introuvable, il cherche `~/.env` (dans le répertoire utilisateur). -**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`. +**Exclusion de variables d'environnement :** Certaines variables (comme `DEBUG` et `DEBUG_MODE`) sont automatiquement exclues des fichiers `.env` du projet par défaut afin d'éviter toute interférence avec le comportement du CLI. Les variables issues des fichiers `.qwen/.env` ne sont jamais exclues. Vous pouvez personnaliser ce comportement via le paramètre `excludedProjectEnvVars` dans votre fichier `settings.json`. -- **`GEMINI_API_KEY`** (Requis) : - - Votre clé API pour l'API Gemini. - - **Essentiel au fonctionnement.** Le CLI ne fonctionnera pas sans cette clé. +- **`OPENAI_API_KEY`** : + - Une des [méthodes d'authentification](./authentication.md) disponibles. - Définissez-la dans votre profil shell (ex. `~/.bashrc`, `~/.zshrc`) ou dans un fichier `.env`. -- **`GEMINI_MODEL`** : - - Spécifie le modèle Gemini par défaut à utiliser. - - 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. - - Requise pour utiliser Vertex AI en mode express. - - Assurez-vous d'avoir les permissions nécessaires. - - Exemple : `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`. -- **`GOOGLE_CLOUD_PROJECT`** : - - 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 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. - - **Exemple :** `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"` -- **`OTLP_GOOGLE_CLOUD_PROJECT`** : - - L'ID de votre projet Google Cloud pour la télémétrie dans Google Cloud. - - Exemple : `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. -- **`GOOGLE_CLOUD_LOCATION`** : - - La région de votre projet Google Cloud (ex. us-central1). - - Requis pour utiliser Vertex AI en mode non express. - - Exemple : `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`. +- **`OPENAI_BASE_URL`** : + - Une des [méthodes d'authentification](./authentication.md) disponibles. + - Définissez-la dans votre profil shell (ex. `~/.bashrc`, `~/.zshrc`) ou dans un fichier `.env`. +- **`OPENAI_MODEL`** : + - Spécifie le modèle OPENAI par défaut à utiliser. + - Remplace le modèle codé en dur. + - Exemple : `export OPENAI_MODEL="qwen3-coder-plus"` - **`GEMINI_SANDBOX`** : - Alternative au paramètre `sandbox` dans `settings.json`. - - Accepte `true`, `false`, `docker`, `podman`, ou une commande personnalisée sous forme de chaîne. -- **`SEATBELT_PROFILE`** (spécifique macOS) : + - Accepte `true`, `false`, `docker`, `podman`, ou une commande personnalisée. +- **`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. + - `permissive-open` : (Par défaut) Restreint les écritures au dossier du projet (et quelques autres, voir `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) mais autorise les autres opérations. - `strict` : Utilise un profil strict qui refuse les opérations par défaut. - `` : Utilise un profil personnalisé. Pour définir un profil personnalisé, créez un fichier nommé `sandbox-macos-.sb` dans le répertoire `.qwen/` de votre projet (ex. `my-project/.qwen/sandbox-macos-custom.sb`). -- **`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. +- **`DEBUG` ou `DEBUG_MODE`** (souvent utilisées par les bibliothèques sous-jacentes ou le CLI lui-même) : + - Mettez à `true` ou `1` pour activer les logs verbeux, utiles pour le débogage. - **Note :** Ces variables sont automatiquement exclues des fichiers `.env` du projet par défaut afin d'éviter toute interférence avec le comportement du CLI. Utilisez les fichiers `.qwen/.env` si vous devez les définir spécifiquement pour Qwen Code. - **`NO_COLOR`** : - - Définir à n'importe quelle valeur désactive toute sortie colorée dans le CLI. + - Définissez n'importe quelle valeur pour désactiver toute sortie colorée dans le CLI. - **`CLI_TITLE`** : - - Définir à une chaîne pour personnaliser le titre du CLI. + - Définissez une chaîne de caractères pour personnaliser le titre du CLI. - **`CODE_ASSIST_ENDPOINT`** : - Spécifie l'endpoint du serveur d'assistance au code. - Utile pour le développement et les tests. @@ -369,8 +349,8 @@ Le CLI charge automatiquement les variables d'environnement depuis un fichier `. Les arguments passés directement lors de l'exécution du CLI peuvent remplacer les autres configurations pour cette session spécifique. - **`--model `** (**`-m `**) : - - Spécifie le modèle Gemini à utiliser pour cette session. - - Exemple : `npm start -- --model gemini-1.5-pro-latest` + - Spécifie le modèle Qwen à utiliser pour cette session. + - Exemple : `npm start -- --model qwen3-coder-plus` - **`--prompt `** (**`-p `**) : - Permet de passer un prompt directement à la commande. Cela invoque Qwen Code en mode non interactif. - **`--prompt-interactive `** (**`-i `**) : @@ -385,7 +365,7 @@ 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 défini, inclut récursivement tous les fichiers du répertoire courant comme contexte pour le prompt. + - Si activé, 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`** : @@ -395,7 +375,7 @@ Les arguments passés directement lors de l'exécution du CLI peuvent remplacer - **`--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 + - `auto_edit` : Approuve automatiquement les outils d'édition (edit, write_file) tout en demandant une approbation pour les autres - `yolo` : Approuve automatiquement tous les appels d'outils (équivalent à `--yolo`) - Ne peut pas être utilisé conjointement avec `--yolo`. Utilisez plutôt `--approval-mode=yolo` pour la nouvelle approche unifiée. - Exemple : `qwen --approval-mode auto_edit` @@ -405,12 +385,14 @@ Les arguments passés directement lors de l'exécution du CLI peuvent remplacer - Définit la cible de télémétrie. Voir [télémétrie](../telemetry.md) pour plus d'informations. - **`--telemetry-otlp-endpoint`** : - Définit le endpoint OTLP pour la télémétrie. Voir [télémétrie](../telemetry.md) pour plus d'informations. +- **`--telemetry-otlp-protocol`** : + - Définit le protocole OTLP pour la télémétrie (`grpc` ou `http`). Par défaut : `grpc`. Voir [télémétrie](../telemetry.md) pour plus d'informations. - **`--telemetry-log-prompts`** : - Active la journalisation des prompts pour la télémétrie. Voir [télémétrie](../telemetry.md) pour plus d'informations. - **`--checkpointing`** : - Active le [checkpointing](../checkpointing.md). - **`--extensions `** (**`-e `**) : - - Spécifie une liste d'extensions à utiliser pour la session. Si non spécifié, toutes les extensions disponibles sont utilisées. + - Spécifie une liste d'extensions à utiliser pour la session. Si non fourni, 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`**) : @@ -426,16 +408,16 @@ 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 à l'API OpenAI à des fins de débogage et d'analyse. Cet argument remplace le paramètre `enableOpenAILogging` dans `settings.json`. + - Active la journalisation des appels 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_ 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. +Bien qu'ils ne constituent pas strictement une configuration du _comportement_ du CLI, les fichiers de contexte (par défaut `QWEN.md`, mais configurable via le paramètre `contextFileName`) sont essentiels pour configurer le _contexte d'instructions_ (également appelé « mémoire »). Cette fonctionnalité puissante vous permet de fournir des instructions spécifiques au projet, des guides de style de code, ou toute information contextuelle pertinente à l'IA, rendant ainsi ses réponses plus adaptées et précises par rapport à vos besoins. Le CLI inclut des éléments d'interface utilisateur, comme un indicateur dans le pied de page montrant le nombre de fichiers de contexte chargés, afin de vous tenir informé du contexte actif. -- **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. +- **Objectif :** Ces fichiers Markdown contiennent des instructions, des directives ou du contexte que vous souhaitez que le modèle Qwen prenne en compte durant vos interactions. Le système est conçu pour gérer ce contexte d'instructions de manière hiérarchique. ### Exemple de contenu d'un fichier contexte (ex. `QWEN.md`) @@ -443,11 +425,11 @@ Voici un exemple conceptuel du contenu d'un fichier contexte à la racine d'un p ```markdown -# Projet : My Awesome TypeScript Library +# Project: My Awesome TypeScript Library ## Instructions générales : -- Lors de la génération de nouveau code TypeScript, veuillez suivre le style de codage existant. +- Lors de la génération de nouveau code TypeScript, merci de suivre le style de codage existant. - Assurez-vous que toutes les nouvelles fonctions et classes possèdent des commentaires JSDoc. - Privilégiez les paradigmes de programmation fonctionnelle lorsque cela est approprié. - Tout le code doit être compatible avec TypeScript 5.0 et Node.js 20+. @@ -455,43 +437,46 @@ 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 avec `I` (ex. : `IUserService`). -- Les membres privés des classes doivent être préfixés avec un underscore (`_`). +- 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 (`_`). - 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. +- Lors de l'ajout de nouvelles fonctions d'appel API, assurez-vous qu'elles incluent une gestion d'erreur robuste et des logs. - Utilisez l'utilitaire `fetchWithRetry` existant pour toutes les requêtes GET. ``` +```markdown ## Concernant les dépendances : - Évitez d'introduire de nouvelles dépendances externes sauf si c'est absolument nécessaire. - Si une nouvelle dépendance est requise, veuillez indiquer la raison. + ``` -Cet exemple montre comment vous pouvez fournir un contexte général sur le projet, des conventions de codage spécifiques, 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. +Cet exemple montre comment vous pouvez fournir un contexte général sur le projet, des conventions de codage spécifiques, et même des notes sur des fichiers ou composants particuliers. Plus vos fichiers de contexte sont pertinents et précis, mieux l'IA pourra vous assister. Les fichiers de contexte spécifiques au projet sont fortement encouragés afin d'établir des conventions et un contexte clairs. + +- **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 scanne également les sous-répertoires _sous_ le répertoire courant (en respectant les motifs d'exclusion courants comme `node_modules`, `.git`, etc.) à la recherche du fichier de contexte configuré. La profondeur de cette recherche est limitée à 200 répertoires par défaut, mais peut être configurée avec le champ `memoryDiscoveryMaxDirs` dans votre fichier `settings.json`. + - Portée : Permet d'ajouter des instructions très spécifiques liées à un composant, module ou section particulière de votre projet. +- **Concaténation & indication dans l'interface :** Le contenu de tous les fichiers de contexte trouvés est concaténé (avec des séparateurs indiquant leur origine et leur chemin) et inclus dans le prompt système. Le pied de page du CLI affiche le nombre de fichiers de contexte chargés, vous donnant un indicateur visuel rapide du contexte instructionnel actif. - **Importation de contenu :** Vous pouvez modulariser vos fichiers de contexte en important d'autres fichiers Markdown en utilisant la syntaxe `@path/to/file.md`. Pour plus de détails, consultez la [documentation du processeur d'import mémoire](../core/memport.md). - **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é, 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`). + - Utilisez `/memory show` pour afficher le contexte instructionnel combiné actuellement chargé, afin de vérifier la hiérarchie et le contenu utilisé par l'IA. + - Consultez la [documentation des commandes](./commands.md#memory) pour tous les détails concernant la commande `/memory` et ses sous-commandes (`show` et `refresh`). -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. +En comprenant et en utilisant ces couches de configuration ainsi que la nature hiérarchique des fichiers de contexte, vous pouvez efficacement gérer la mémoire de l'IA et adapter les réponses de Qwen Code à vos besoins et projets spécifiques. +``` ## Sandboxing @@ -505,7 +490,7 @@ Le sandboxing est désactivé par défaut, mais vous pouvez l'activer de plusieu Par défaut, il utilise une image Docker pré-construite `qwen-code-sandbox`. -Pour des besoins de sandboxing spécifiques à un projet, vous pouvez créer un Dockerfile personnalisé à l'emplacement `.qwen/sandbox.Dockerfile` dans le répertoire racine de votre projet. Ce Dockerfile peut être basé sur l'image de base du sandbox : +Pour des besoins de sandboxing spécifiques à un projet, vous pouvez créer un Dockerfile personnalisé à l'emplacement `.qwen/sandbox.Dockerfile` à la racine de votre projet. Ce Dockerfile peut être basé sur l'image de base du sandbox : ```dockerfile FROM qwen-code-sandbox @@ -520,7 +505,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 du sandbox personnalisé : +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 : ```bash BUILD_SANDBOX=1 qwen -s @@ -538,13 +523,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, votre adresse e-mail ou vos clés API. +- **Informations personnelles identifiables (PII) :** Nous ne collectons aucune information personnelle, comme votre nom, adresse email ou clés API. - **Contenu des prompts et réponses :** Nous n'enregistrons pas le contenu de vos prompts ou des réponses du modèle. - **Contenu des fichiers :** Nous n'enregistrons pas le contenu des fichiers lus ou écrits par le CLI. **Comment désactiver la collecte :** -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` : +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` : ```json { @@ -552,4 +537,12 @@ 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 Alibaba Cloud RUM. \ No newline at end of file +Note : Lorsque les statistiques d'utilisation sont activées, les événements sont envoyés à un endpoint de collecte RUM d'Alibaba Cloud. + +- **`enableWelcomeBack`** (boolean) : + - **Description :** Affiche une boîte de dialogue de bienvenue lors du retour sur un projet avec un historique de conversation. + - **Par défaut :** `true` + - **Catégorie :** UI + - **Redémarrage requis :** Non + - **Exemple :** `"enableWelcomeBack": false` + - **Détails :** Lorsque cette option est activée, Qwen Code détecte automatiquement si vous revenez sur un projet avec un résumé de projet généré précédemment (`.qwen/PROJECT_SUMMARY.md`) et affiche une boîte de dialogue vous permettant de continuer votre conversation précédente ou d'en commencer une nouvelle. Cette fonctionnalité s'intègre avec la commande `/chat summary` et la boîte de dialogue de confirmation de fermeture. Consultez la [documentation Welcome Back](./welcome-back.md) pour plus de détails. \ No newline at end of file diff --git a/website/content/fr/cli/index.md b/website/content/fr/cli/index.md index 1485da51..73dfece0 100644 --- a/website/content/fr/cli/index.md +++ b/website/content/fr/cli/index.md @@ -1,15 +1,16 @@ # Qwen Code CLI -Dans Qwen Code, `packages/cli` est l'interface utilisateur permettant d'envoyer et de recevoir des prompts avec Qwen et d'autres modèles IA ainsi que leurs outils associés. Pour une vue d'ensemble de Qwen Code, consultez la [page de documentation principale](../index.md). +Dans Qwen Code, `packages/cli` est l'interface frontend permettant aux utilisateurs d'envoyer et de recevoir des prompts avec Qwen et d'autres modèles IA ainsi que leurs outils associés. Pour une vue d'ensemble de Qwen Code, consultez la [page de documentation principale](../index.md). ## Navigation dans cette section -- **[Authentification](./authentication.md) :** Guide de configuration de l'authentification avec Qwen OAuth et les fournisseurs compatibles OpenAI. -- **[Commandes](./commands.md) :** Référence des commandes du Qwen Code CLI (ex. : `/help`, `/tools`, `/theme`). -- **[Configuration](./configuration.md) :** Guide pour personnaliser le comportement du Qwen Code CLI à l'aide de fichiers de configuration. -- **[Mise en cache des tokens](./token-caching.md) :** Optimisez les coûts API grâce à la mise en cache des tokens. -- **[Thèmes](./themes.md) :** Guide pour personnaliser l'apparence du CLI avec différents thèmes. -- **[Tutoriels](tutorials.md) :** Tutoriel montrant comment utiliser Qwen Code pour automatiser une tâche de développement. +- **[Authentication](./authentication.md) :** Guide de configuration de l'authentification avec Qwen OAuth et les providers compatibles OpenAI. +- **[Commands](./commands.md) :** Référence des commandes du Qwen Code CLI (ex. : `/help`, `/tools`, `/theme`). +- **[Configuration](./configuration.md) :** Guide pour personnaliser le comportement du Qwen Code CLI via des fichiers de configuration. +- **[Token Caching](./token-caching.md) :** Optimisez les coûts API grâce à la mise en cache des tokens. +- **[Themes](./themes.md) :** Guide pour personnaliser l'apparence du CLI avec différents thèmes. +- **[Tutorials](tutorials.md) :** Tutoriel montrant comment utiliser Qwen Code pour automatiser une tâche de développement. +- **[Welcome Back](./welcome-back.md) :** Découvrez la fonctionnalité Welcome Back qui vous permet de reprendre votre travail facilement d'une session à l'autre. ## Mode non-interactif diff --git a/website/content/fr/cli/token-caching.md b/website/content/fr/cli/token-caching.md index e474c6ab..735c415d 100644 --- a/website/content/fr/cli/token-caching.md +++ b/website/content/fr/cli/token-caching.md @@ -1,14 +1,14 @@ # Mise en cache des tokens et optimisation des coûts -Qwen Code optimise automatiquement les coûts API par le biais de la mise en cache des tokens lorsque vous utilisez l'authentification par clé API (par exemple, les fournisseurs compatibles OpenAI). Cette fonctionnalité réutilise les instructions système et le contexte précédents pour réduire le nombre de tokens traités lors des requêtes suivantes. +Qwen Code optimise automatiquement les coûts d'API grâce à la mise en cache des tokens lorsque vous utilisez l'authentification par clé API (par exemple, les fournisseurs compatibles OpenAI). Cette fonctionnalité réutilise les instructions système et le contexte précédents pour réduire le nombre de tokens traités dans les requêtes suivantes. **La mise en cache des tokens est disponible pour :** -- Les utilisateurs de clés API (clé API Gemini) +- Les utilisateurs de clé API (Qwen API key) - Les utilisateurs de Vertex AI (avec configuration du projet et de la région) **La mise en cache des tokens n'est pas disponible pour :** -- Les utilisateurs OAuth (comptes Google personnels/entreprise) - l'API Code Assist ne prend pas en charge la création de contenu mis en cache pour le moment +- Les utilisateurs OAuth (comptes Google Personnel/Entreprise) - l'API Code Assist ne prend pas en charge la création de contenu mis en cache pour le moment -Vous pouvez consulter votre utilisation des tokens et les économies de tokens mis en cache à l'aide de la commande `/stats`. Lorsque des tokens mis en cache sont disponibles, ils seront affichés dans la sortie des statistiques. \ No newline at end of file +Vous pouvez consulter votre utilisation de tokens et les économies de tokens mis en cache en utilisant la commande `/stats`. Lorsque des tokens mis en cache sont disponibles, ils seront affichés dans la sortie des statistiques. \ No newline at end of file diff --git a/website/content/fr/cli/welcome-back.md b/website/content/fr/cli/welcome-back.md new file mode 100644 index 00000000..17af0085 --- /dev/null +++ b/website/content/fr/cli/welcome-back.md @@ -0,0 +1,133 @@ +# Fonction Welcome Back + +La fonction Welcome Back vous aide à reprendre votre travail de manière transparente en détectant automatiquement lorsque vous revenez à un projet avec un historique de conversation existant et en vous proposant de continuer là où vous vous étiez arrêté. + +## Aperçu + +Lorsque vous démarrez Qwen Code dans un répertoire de projet contenant un résumé de projet généré précédemment (`.qwen/PROJECT_SUMMARY.md`), la boîte de dialogue Welcome Back apparaîtra automatiquement, vous donnant la possibilité de recommencer depuis zéro ou de continuer votre conversation précédente. + +## Fonctionnement + +### Détection automatique + +La fonction Welcome Back détecte automatiquement : + +- **Fichier de résumé de projet :** Recherche `.qwen/PROJECT_SUMMARY.md` dans votre répertoire de projet actuel +- **Historique de conversation :** Vérifie s'il existe un historique de conversation significatif à reprendre +- **Paramètres :** Respecte votre paramètre `enableWelcomeBack` (activé par défaut) + +### Welcome Back Dialog + +Lorsqu'un résumé de projet est trouvé, vous verrez une boîte de dialogue avec : + +- **Last Updated Time :** Indique quand le résumé a été généré pour la dernière fois +- **Overall Goal :** Affiche l'objectif principal de votre session précédente +- **Current Plan :** Montre l'avancement des tâches avec des indicateurs de statut : + - `[DONE]` - Tâches terminées + - `[IN PROGRESS]` - En cours de traitement + - `[TODO]` - Tâches planifiées +- **Task Statistics :** Résumé du nombre total de tâches, terminées, en cours et en attente + +### Options + +Vous avez deux choix lorsque la boîte de dialogue Welcome Back s'affiche : + +1. **Start new chat session** + - Ferme la boîte de dialogue et commence une nouvelle conversation + - Aucun contexte précédent n'est chargé + +2. **Continue previous conversation** + - Remplit automatiquement l'entrée avec : `@.qwen/PROJECT_SUMMARY.md, Based on our previous conversation, Let's continue?` + - Charge le résumé du projet comme contexte pour l'IA + - Vous permet de reprendre là où vous vous étiez arrêté de manière transparente + +## Configuration + +### Activer/Désactiver Welcome Back + +Vous pouvez contrôler la fonctionnalité Welcome Back via les paramètres : + +**Via la fenêtre de paramètres :** + +1. Exécutez `/settings` dans Qwen Code +2. Recherchez "Enable Welcome Back" dans la catégorie UI +3. Activez/désactivez le paramètre + +**Via le fichier de paramètres :** +Ajoutez ceci à votre `.qwen/settings.json` : + +```json +{ + "enableWelcomeBack": true +} +``` + +**Emplacements des paramètres :** + +- **Paramètres utilisateur :** `~/.qwen/settings.json` (affecte tous les projets) +- **Paramètres projet :** `.qwen/settings.json` (spécifique au projet) + +### Raccourcis clavier + +- **Échap :** Fermer la fenêtre Welcome Back (revient par défaut à "Start new chat session") + +## Intégration avec d'autres fonctionnalités + +### Génération du résumé de projet + +La fonctionnalité Welcome Back fonctionne de manière transparente avec la commande `/chat summary` : + +1. **Générer un résumé :** Utilisez `/chat summary` pour créer un résumé du projet +2. **Détection automatique :** La prochaine fois que vous démarrerez Qwen Code dans ce projet, Welcome Back détectera le résumé +3. **Reprendre le travail :** Choisissez de continuer et le résumé sera chargé comme contexte + +### Confirmation de sortie + +Lorsque vous quittez avec `/quit-confirm` et que vous choisissez "Generate summary and quit" : + +1. Un résumé du projet est automatiquement créé +2. La session suivante déclenchera la boîte de dialogue Welcome Back +3. Vous pouvez reprendre votre travail de manière fluide + +## Structure des fichiers + +La fonctionnalité Welcome Back crée et utilise : + +``` +your-project/ +├── .qwen/ +│ └── PROJECT_SUMMARY.md # Résumé du projet généré +``` + +### Format de PROJECT_SUMMARY.md + +Le résumé généré suit cette structure : + +```markdown + +# Project Summary + +## Overall Goal + + + +## Connaissances clés + + + + +## Actions récentes + + + + +## Plan actuel + + + + +--- + +## Métadonnées du résumé + +**Date de mise à jour** : 2025-01-10T15:30:00.000Z \ No newline at end of file diff --git a/website/content/fr/deployment.md b/website/content/fr/deployment.md index 4dcfd5d8..ce9dcc3d 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 décrit comment exécuter Qwen Code et explique l'architecture de déploiement utilisée par Qwen Code. +Ce document explique comment exécuter Qwen Code et décrit 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 la manière dont vous comptez l'utiliser. +Il existe plusieurs façons d'exécuter Qwen Code. L'option que vous choisissez dépend de votre utilisation prévue. --- @@ -41,10 +41,10 @@ Pour des raisons de sécurité et d'isolation, Qwen Code peut être exécuté à 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.9 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 ``` -- **Avec le flag `--sandbox` :** +- **Utilisation du flag `--sandbox` :** Si Qwen Code est installé localement (via l'installation standard décrite plus haut), vous pouvez lui demander de s'exécuter à l'intérieur du container sandbox. ```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 une version locale dans un workflow de production. + 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. ```bash # Lier le package cli local à vos node_modules globaux diff --git a/website/content/fr/ide-integration.md b/website/content/fr/ide-integration.md index adabc4c6..1ca4df36 100644 --- a/website/content/fr/ide-integration.md +++ b/website/content/fr/ide-integration.md @@ -1,8 +1,8 @@ # 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. +Qwen Code peut s'intégrer à votre IDE pour offrir une expérience plus fluide et contextuelle. Cette intégration permet au CLI de mieux comprendre votre espace de travail et active des fonctionnalités puissantes comme le diffing natif directement dans l'éditeur. -Actuellement, le seul IDE supporté est [Visual Studio Code](https://code.visualstudio.com/) ainsi que les autres éditeurs qui supportent les extensions VS Code. +Actuellement, le seul IDE supporté est [Visual Studio Code](https://code.visualstudio.com/) ainsi que les autres éditeurs compatibles avec les extensions VS Code. ## Fonctionnalités @@ -11,13 +11,13 @@ Actuellement, le seul IDE supporté est [Visual Studio Code](https://code.visual - 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. +- **Diffing natif :** Lorsque Qwen propose des modifications de code, vous pouvez visualiser les changements directement dans le visualiseur de différences natif de votre IDE. Cela vous permet de revoir, modifier, accepter ou rejeter facilement les modifications suggérées. -- **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. +- **Commandes VS Code :** Vous pouvez accéder aux fonctionnalités de Qwen Code directement depuis la Palette de commandes de VS Code (`Cmd+Shift+P` ou `Ctrl+Shift+P`) : + - `Qwen Code: Run` : Démarre une nouvelle session Qwen Code dans le terminal intégré. + - `Qwen Code: Accept Diff` : Accepte les modifications dans l'éditeur de différences actif. + - `Qwen Code: Close Diff Editor` : Rejette les modifications et ferme l'éditeur de différences actif. + - `Qwen Code: View Third-Party Notices` : Affiche les mentions relatives aux logiciels tiers utilisés par l'extension. ## Installation et Configuration @@ -25,11 +25,11 @@ 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. +Lorsque vous exécutez Qwen Code dans un éditeur pris en charge, il détectera automatiquement votre environnement et vous invitera à vous connecter. Répondre par "Yes" lancera automatiquement la configuration nécessaire, qui inclut l'installation de l'extension companion et l'activation de la connexion. ### 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 : +Si vous avez précédemment ignoré l'invite ou si vous souhaitez installer l'extension manuellement, vous pouvez exécuter la commande suivante dans Qwen Code : ``` /ide install @@ -37,12 +37,12 @@ Si vous avez précédemment ignoré l'invitation ou si vous souhaitez installer Cette commande trouvera l'extension appropriée pour votre IDE et l'installera. -### 3. Installation manuelle depuis un marketplace +### 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. +- **Pour Visual Studio Code :** Installez depuis le [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion). +- **Pour les forks de VS Code :** Pour supporter les forks de VS Code, l'extension est également publiée sur le [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion). Suivez les instructions de votre éditeur pour installer des extensions depuis ce registre. Après n'importe quelle méthode d'installation, il est recommandé d'ouvrir une nouvelle fenêtre de terminal pour vous assurer que l'intégration est activée correctement. Une fois installée, vous pouvez utiliser `/ide enable` pour vous connecter. @@ -50,7 +50,7 @@ Après n'importe quelle méthode d'installation, il est recommandé d'ouvrir une ### Activation et Désactivation -Vous pouvez contrôler l'intégration IDE depuis le CLI : +Vous pouvez contrôler l'intégration de l'IDE directement depuis le CLI : - Pour activer la connexion à l'IDE, exécutez : ``` @@ -61,7 +61,7 @@ Vous pouvez contrôler l'intégration IDE depuis le CLI : /ide disable ``` -Lorsque activée, l'IDE CLI tentera automatiquement de se connecter à l'extension compagnon de l'IDE. +Lorsque l'option est activée, Qwen Code tentera automatiquement de se connecter à l'extension compagnon de l'IDE. ### Vérification du Statut @@ -71,38 +71,38 @@ Pour vérifier l'état de la connexion et voir le contexte que le CLI a reçu de /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. +Si la connexion est établie, cette commande affichera l'IDE auquel il est connecté ainsi qu'une liste des fichiers récemment ouverts dont il a connaissance. -(Note : La liste des fichiers est limitée aux 10 fichiers récemment consultés dans votre workspace et inclut uniquement les fichiers locaux sur le disque.) +(Note : La liste des fichiers est limitée aux 10 fichiers récents accédés dans votre espace de travail et inclut uniquement les fichiers locaux présents sur le disque.) ### Travailler avec les diffs -Quand vous demandez à Gemini de modifier un fichier, il peut ouvrir directement une vue diff dans votre éditeur. +Quand vous demandez à Gemini de modifier un fichier, il peut ouvrir directement une vue de 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. +- Cliquer sur l'**icône de validation (✓)** 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**. +- Ouvrir la Command Palette et exécuter **Qwen Code: Accept Diff**. - Répondre par `yes` dans le CLI quand vous y êtes invité. **Pour rejeter un diff**, vous pouvez : - Cliquer sur l'**icône 'x'** dans la barre de titre de l'éditeur de diff. - Fermer l'onglet de l'éditeur de diff. -- Ouvrir la Command Palette et exécuter **Gemini CLI: Close Diff Editor**. +- Ouvrir la Command Palette et exécuter **Qwen Code: Close Diff Editor**. - Répondre par `no` dans le CLI quand vous y êtes invité. -Vous pouvez également **modifier les changements suggérés** directement dans la vue diff avant de les accepter. +Vous pouvez également **modifier les changements suggérés** directement dans la vue de diff avant de les accepter. -Si vous sélectionnez 'Yes, allow always' dans le CLI, les modifications n'apparaîtront plus dans l'IDE car elles seront automatiquement acceptées. +Si vous sélectionnez ‘Yes, allow always’ dans le CLI, les modifications n’apparaîtront plus dans l'IDE car elles seront automatiquement acceptées. ## Utilisation avec le Sandboxing -Si vous utilisez Gemini CLI dans un environnement sandbox, veuillez prendre en compte les points suivants : +Si vous utilisez Qwen Code dans un environnement sandbox, veuillez prendre en compte les points suivants : - **Sur macOS :** L'intégration avec l'IDE nécessite un accès réseau pour communiquer avec l'extension compagnon de l'IDE. Vous devez utiliser un profil Seatbelt qui autorise l'accès réseau. -- **Dans un conteneur Docker :** Si vous exécutez 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. +- **Dans un conteneur Docker :** Si vous exécutez Qwen Code à l'intérieur d'un conteneur Docker (ou Podman), l'intégration avec l'IDE peut toujours se connecter à l'extension VS Code qui s'exécute sur votre machine hôte. La CLI est configurée pour trouver automatiquement le serveur IDE sur `host.docker.internal`. Aucune configuration spéciale n'est généralement requise, mais vous devrez peut-être vérifier que votre configuration réseau Docker autorise les connexions depuis le conteneur vers l'hôte. ## Dépannage @@ -111,31 +111,31 @@ Si vous rencontrez des problèmes avec l'intégration IDE, voici quelques messag ### Erreurs de connexion - **Message :** `🔴 Disconnected: Failed to connect to IDE companion extension for [IDE Name]. Please ensure the extension is running and try restarting your terminal. To install the extension, run /ide install.` - - **Cause :** 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. + - **Cause :** Qwen Code n’a pas pu trouver les variables d’environnement nécessaires (`QWEN_CODE_IDE_WORKSPACE_PATH` ou `QWEN_CODE_IDE_SERVER_PORT`) pour se connecter à l’IDE. Cela signifie généralement que l’extension companion de l’IDE n’est pas en cours d’exécution ou qu’elle n’a pas été initialisée correctement. - **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. + 1. Assurez-vous d’avoir installé l’extension **Qwen Code Companion** dans votre IDE et qu’elle est activée. + 2. Ouvrez une nouvelle fenêtre de terminal dans votre IDE pour vous assurer qu’elle récupère le bon environnement. - **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. + - **Cause :** La connexion à l’extension companion 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: Directory mismatch. Qwen Code is running in a different location than the open workspace in [IDE Name]. Please run the CLI from the same directory as your project's root folder.` + - **Cause :** Le répertoire de travail actuel de la CLI se trouve en dehors du dossier ou de l'espace de travail que vous avez ouvert dans votre IDE. + - **Solution :** Utilisez `cd` pour accéder au même répertoire que celui ouvert dans votre IDE, puis redémarrez la CLI. - **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. + - **Cause :** Vous avez plusieurs dossiers d'espace de travail ouverts dans votre IDE, ou aucun dossier n'est ouvert. L'intégration avec l'IDE nécessite un seul dossier racine d'espace de travail pour fonctionner correctement. - **Solution :** Ouvrez un seul dossier de projet dans votre IDE et redémarrez la CLI. ### 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 :** `L'intégration IDE n'est pas prise en charge dans votre environnement actuel. Pour utiliser cette fonctionnalité, exécutez Qwen Code dans l'un de ces IDE pris en charge : [Liste des IDE]` + - **Cause :** Vous exécutez Qwen Code dans un terminal ou un environnement qui n'est pas un IDE pris en charge. + - **Solution :** Exécutez Qwen Code depuis le terminal intégré d'un IDE pris en charge, comme VS Code. - **Message :** `Aucun installateur n'est disponible pour [Nom de l'IDE]. Veuillez installer l'extension IDE manuellement depuis son marketplace.` - - **Cause :** Vous avez exécuté `/ide install`, mais le CLI ne dispose pas d'un installateur 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 + - **Cause :** Vous avez exécuté `/ide install`, mais le CLI ne dispose pas d'un installateur automatisé pour votre IDE spécifique. + - **Solution :** Ouvrez le marketplace d'extensions de votre IDE, recherchez "Qwen Code Companion", et installez-le manuellement. \ No newline at end of file diff --git a/website/content/fr/index.md b/website/content/fr/index.md index 625093d8..c85e0f4b 100644 --- a/website/content/fr/index.md +++ b/website/content/fr/index.md @@ -4,7 +4,7 @@ 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 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`. +Qwen Code apporte les capacités de modèles de code avancés directement dans votre terminal, au sein d'un environnement interactif Read-Eval-Print Loop (REPL). Qwen Code se compose d'une application côté client (`packages/cli`) qui communique avec un serveur local (`packages/core`). Qwen Code inclut également divers outils pour effectuer des opérations sur le système de fichiers, exécuter des commandes shell, et récupérer des données depuis le web, tous gérés par `packages/core`. ## Navigation dans la documentation @@ -31,9 +31,10 @@ Cette documentation est organisée en plusieurs sections : - **[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, y compris l'installation, la construction, les tests et les conventions de codage. +- **[Sous-agents](./subagents.md) :** Assistants IA spécialisés pour des tâches ciblées, avec un guide complet de gestion, configuration et utilisation. +- **[Guide de contribution et développement](../CONTRIBUTING.md) :** Informations pour les contributeurs et développeurs, incluant l'installation, la construction, les tests et les conventions de codage. - **[Workspaces NPM et publication](./npm.md) :** Détails sur la gestion et la publication des packages du projet. -- **[Guide de dépannage](./troubleshooting.md) :** Trouvez des solutions aux problèmes courants et FAQ. +- **[Guide de dépannage](./troubleshooting.md) :** Trouvez des solutions aux problèmes courants et aux questions fréquentes. - **[Conditions d'utilisation et politique de confidentialité](./tos-privacy.md) :** Informations sur les conditions d'utilisation et les mentions de confidentialité applicables à votre utilisation de Qwen Code. Nous espérons que cette documentation vous aidera à tirer le meilleur parti de Qwen Code ! \ No newline at end of file diff --git a/website/content/fr/keyboard-shortcuts.md b/website/content/fr/keyboard-shortcuts.md index ef8b9e65..b536e59c 100644 --- a/website/content/fr/keyboard-shortcuts.md +++ b/website/content/fr/keyboard-shortcuts.md @@ -7,11 +7,11 @@ Ce document liste les raccourcis clavier disponibles dans Qwen Code. | Raccourci | Description | | --------- | --------------------------------------------------------------------------------------------------------------------- | | `Esc` | Fermer les boîtes de dialogue et les suggestions. | -| `Ctrl+C` | Quitter l'application. Appuyer deux fois pour confirmer. | -| `Ctrl+D` | Quitter l'application si l'entrée est vide. Appuyer deux fois pour confirmer. | +| `Ctrl+C` | Annuler la requête en cours et effacer l'entrée. Appuyez deux fois pour quitter l'application. | +| `Ctrl+D` | Quitter l'application si l'entrée est vide. Appuyez deux fois pour confirmer. | | `Ctrl+L` | Effacer l'écran. | | `Ctrl+O` | Activer/désactiver l'affichage de la console de débogage. | -| `Ctrl+S` | Permet aux réponses longues de s'afficher complètement, en désactivant la troncature. Utilisez le défilement de votre terminal pour voir la sortie entière. | +| `Ctrl+S` | Permet aux réponses longues de s'afficher entièrement, en désactivant la troncature. Utilisez le défilement de votre terminal pour voir la sortie complète. | | `Ctrl+T` | Activer/désactiver l'affichage des descriptions des outils. | | `Ctrl+Y` | Activer/désactiver l'approbation automatique (mode YOLO) pour tous les appels d'outils. | @@ -20,7 +20,7 @@ Ce document liste les raccourcis clavier disponibles dans Qwen Code. | Raccourci | Description | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `!` | Basculer en mode shell lorsque l'entrée est vide. | -| `\` (à la fin de la ligne) + `Enter` | Insérer un saut de ligne. | +| `\` (en fin de ligne) + `Enter` | Insérer un saut de ligne. | | `Flèche du bas` | Naviguer vers le bas dans l'historique des entrées. | | `Enter` | Soumettre l'invite actuelle. | | `Meta+Delete` / `Ctrl+Delete` | Supprimer le mot à droite du curseur. | @@ -45,11 +45,11 @@ Ce document liste les raccourcis clavier disponibles dans Qwen Code. ## Suggestions -| Raccourci | Description | -| --------------- | --------------------------------------------- | -| `Down Arrow` | Naviguer vers le bas dans les suggestions. | -| `Tab` / `Enter` | Accepter la suggestion sélectionnée. | -| `Up Arrow` | Naviguer vers le haut dans les suggestions. | +| Raccourci | Description | +| --------------- | ------------------------------------- | +| `Down Arrow` | Naviguer vers le bas dans les suggestions. | +| `Tab` / `Enter` | Accepter la suggestion sélectionnée. | +| `Up Arrow` | Naviguer vers le haut dans les suggestions. | ## Radio Button Select @@ -59,4 +59,10 @@ Ce document liste les raccourcis clavier disponibles dans Qwen Code. | `Enter` | Confirmer la sélection. | | `Up Arrow` / `k` | Déplacer la sélection vers le haut. | | `1-9` | Sélectionner un élément par son numéro. | -| (multi-chiffres) | Pour les éléments avec des numéros supérieurs à 9, appuyez rapidement sur les chiffres pour sélectionner l'élément correspondant. | \ No newline at end of file +| (multi-digit) | Pour les éléments avec des numéros supérieurs à 9, appuyez rapidement sur les chiffres pour sélectionner l'élément correspondant. | + +## Intégration IDE + +| Raccourci | Description | +| --------- | ------------------------------------ | +| `Ctrl+G` | Voir le contexte CLI reçu de l'IDE | \ No newline at end of file diff --git a/website/content/fr/npm.md b/website/content/fr/npm.md index b8a2be31..776dd8c4 100644 --- a/website/content/fr/npm.md +++ b/website/content/fr/npm.md @@ -4,15 +4,15 @@ Ce monorepo contient deux packages principaux : `@qwen-code/qwen-code` et `@qwen ## `@qwen-code/qwen-code` -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. +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. -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 fichier 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 providers configurés, de la gestion de l'authentification, et du cache local. +Ce package contient la logique principale du 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. +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 standalone dans d'autres projets, si nécessaire. Tout le code js transpilé dans le dossier `dist` est inclus dans le package. # Processus de release @@ -28,7 +28,7 @@ Les releases sont gérées via le workflow GitHub Actions [release.yml](https:// 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 définissez sur `false` pour effectuer une release réelle. + - **Dry Run** : Laissez à `true` pour tester le workflow sans publier, ou définissez à `false` pour effectuer une release réelle. 5. Cliquez sur **Run workflow**. ## Releases Nightly @@ -39,12 +39,12 @@ En plus des releases manuelles, ce projet dispose d'un processus automatisé de Chaque nuit à minuit UTC, le [workflow Release](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) s'exécute automatiquement selon un planning. Il effectue les étapes suivantes : -1. Récupère la dernière version du code depuis la branche `main`. -2. Installe toutes les dépendances. -3. Exécute la suite complète des checks `preflight` et des tests d'intégration. -4. Si tous les tests réussissent, il calcule le numéro de version nightly suivant (par exemple, `v0.2.1-nightly.20230101`). -5. Il construit ensuite les packages et les publie sur npm avec le dist-tag `nightly`. -6. Enfin, il crée une GitHub Release pour cette version nightly. +1. Récupère la dernière version du code depuis la branche `main`. +2. Installe toutes les dépendances. +3. Exécute la suite complète des checks `preflight` et des tests d'intégration. +4. Si tous les tests réussissent, il calcule le numéro de version nightly suivant (par exemple, `v0.2.1-nightly.20230101`). +5. Il construit ensuite les packages et les publie sur npm avec le dist-tag `nightly`. +6. Enfin, il crée une GitHub Release pour cette version nightly. ### Gestion des échecs @@ -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.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. +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. Cette étape sera également déplacée vers GitHub et combinée avec le fichier de release principal une fois que les permissions du compte de service seront configurées. ### Après la release @@ -81,46 +81,41 @@ 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 contient uniquement 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 publier. C'est crucial. Toute personne qui checkout ce tag obtient exactement le code 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). -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. +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. -C'est ici que réside la décision critique, et elle dépend entièrement de la nature du release. +C'est ici que se trouve la décision critique, et elle dépend entièrement de la nature de la release. -### Merge Back pour les Correctifs Stables et les Hotfixes +### 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) 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. +- 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 le bump de version, le package.json de votre branche main indiquera toujours "version": "1.2.0". Le prochain développeur qui commencera à travailler 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 un bump de version manuel plus tard. +- Le Process : 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) +### Ne fusionnez PAS les pré-releases (RC, Beta, Dev) vers `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, 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. +- Pourquoi ? Les versions préliminaires (ex. : v1.3.0-rc.1, v1.3.0-rc.2) ne sont, par définition, ni stables ni destinées à durer. Vous ne souhaitez pas encombrer l'historique de votre branche principale avec une série de mises à jour de version pour des 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 feature), donc aucun code fonctionnel n’est perdu. La branche de release n’était qu’un véhicule temporaire pour 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. +1. Allez dans l’[onglet Actions](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) du repository. 2. Cliquez sur le menu déroulant "Run workflow". -3. Laissez l'option `dry_run` cochée (`true`). +3. Laissez l’option `dry_run` cochée (`true`). 4. Cliquez sur le bouton "Run workflow". -Cela exécutera l'ensemble du processus de release mais ignorera les étapes `npm publish` et `gh release create`. Vous pouvez inspecter les logs du workflow pour vous assurer que tout fonctionne comme prévu. +Cela exécutera l’ensemble du processus de release mais ignorera les étapes `npm publish` et `gh release create`. Vous pouvez inspecter les logs du workflow pour vérifier que tout fonctionne comme prévu. -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. +Il est essentiel 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 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. +Pour valider vos changements, vous pouvez effectuer un dry run du processus de publication. Cela simule la 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 @@ -133,32 +128,32 @@ Cette commande va : 3. Créer les tarballs des packages qui seraient publiés sur npm. 4. Afficher un résumé des packages qui seraient publiés. -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`). +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/qwen-code-0.1.6.tgz`). -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. +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. ## Plongée dans le processus de release -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. +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 propre et autonome dans un répertoire temporaire `bundle` à la racine du projet. Ce répertoire `bundle` est ce 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 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. +- **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 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 présent dans `packages/core/src` et `packages/cli/src` est compilé en JavaScript. +- **Ce qui se passe** : Le code TypeScript 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 pour être exécuté 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 exécutable 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 pour leur forme finale de 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 les fichiers finaux du package. #### 1. Transformation du `package.json` @@ -166,14 +161,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:*" }`, 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. + - Suppression des dépendances spécifiques à l’espace de travail : `{ "@qwen-code/core": "workspace:*" }`, et inclusion directe du code `core` dans le fichier JavaScript final. + - Vérification 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 à 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. +- **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 `@qwen-code/core` comme dépendance séparée sur NPM, son code étant désormais inclus directement. #### 3. Copie des fichiers statiques et de support @@ -183,13 +178,13 @@ C’est l’étape la plus critique, où les fichiers sont déplacés et transfo - `LICENSE` → `bundle/LICENSE` - `packages/cli/src/utils/*.sb` (profils sandbox) → `bundle/` - **Pourquoi** : - - Le `README.md` et la `LICENSE` sont des fichiers standards devant être inclus dans tout package NPM. + - `README.md` et `LICENSE` sont des fichiers standards devant être inclus dans tout package NPM. - Les profils sandbox (fichiers `.sb`) sont des ressources runtime critiques pour le fonctionnement de la fonctionnalité de sandboxing du CLI. Ils doivent être situés à côté de l’exécutable final. ### É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 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. +- **Pourquoi** : En lançant `npm publish` depuis le répertoire `bundle`, seuls les fichiers soigneusement assemblés à l’étape 3 sont envoyés sur le 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. ### Résumé du flux des fichiers @@ -235,7 +230,7 @@ Ce projet utilise les [NPM Workspaces](https://docs.npmjs.com/cli/v10/using-npm/ ### Fonctionnement -Le fichier `package.json` racine définit les workspaces pour ce projet : +Le fichier `package.json` à la racine définit les workspaces pour ce projet : ```json { @@ -243,10 +238,10 @@ Le fichier `package.json` racine définit les workspaces pour ce projet : } ``` -Cela indique à NPM que chaque dossier situé dans le répertoire `packages` est un package séparé qui doit être géré dans le cadre de l'espace de travail. +Cela indique à NPM que chaque dossier situé dans le répertoire `packages` est un package distinct qui doit être géré dans le cadre de l'espace de travail. ### Avantages des Workspaces -- **Gestion Simplifiée des Dépendances** : Exécuter `npm install` depuis la racine du projet installera toutes les dépendances pour tous les packages dans le workspace et les liera ensemble. Cela signifie que vous n'avez pas besoin d'exécuter `npm install` dans le répertoire de chaque package. -- **Liaison Automatique** : Les packages au sein du workspace peuvent dépendre les uns des autres. Lorsque vous exécutez `npm install`, NPM créera automatiquement des symlinks entre les packages. Cela signifie que lorsque vous apportez des modifications à un package, les changements sont immédiatement disponibles pour les autres packages qui en dépendent. -- **Exécution Simplifiée des Scripts** : Vous pouvez exécuter des scripts dans n'importe quel package depuis la racine du projet en utilisant le flag `--workspace`. Par exemple, pour exécuter le script `build` dans le package `cli`, vous pouvez exécuter `npm run build --workspace @google/gemini-cli`. \ No newline at end of file +- **Gestion Simplifiée des Dépendances** : Exécuter `npm install` depuis la racine du projet installera toutes les dépendances de tous les packages dans le workspace et les liera ensemble. Cela signifie que vous n'avez pas besoin d'exécuter `npm install` dans le répertoire de chaque package. +- **Liaison Automatique** : Les packages au sein du workspace peuvent dépendre les uns des autres. Lorsque vous exécutez `npm install`, NPM créera automatiquement des symlinks entre les packages. Cela signifie que lorsque vous apportez des modifications à un package, ces modifications sont immédiatement disponibles pour les autres packages qui en dépendent. +- **Exécution Simplifiée des Scripts** : Vous pouvez exécuter des scripts dans n'importe quel package depuis la racine du projet en utilisant le flag `--workspace`. Par exemple, pour exécuter le script `build` dans le package `cli`, vous pouvez exécuter `npm run build --workspace @qwen-code/qwen-code`. \ No newline at end of file diff --git a/website/content/fr/subagents.md b/website/content/fr/subagents.md new file mode 100644 index 00000000..ac68d1d5 --- /dev/null +++ b/website/content/fr/subagents.md @@ -0,0 +1,469 @@ +# Subagents + +Les subagents sont des assistants AI spécialisés qui gèrent des types de tâches spécifiques au sein de Qwen Code. Ils vous permettent de déléguer du travail ciblé à des agents AI configurés avec des prompts, des outils et des comportements adaptés à chaque tâche. + +## Que sont les Subagents ? + +Les subagents sont des assistants AI indépendants qui : + +- **Spécialisés dans des tâches spécifiques** - Chaque subagent est configuré avec un prompt système dédié à un type particulier de travail +- **Possèdent un contexte séparé** - Ils maintiennent leur propre historique de conversation, distinct de votre chat principal +- **Utilisent des outils contrôlés** - Vous pouvez configurer les outils auxquels chaque subagent a accès +- **Travaillent de manière autonome** - Une fois une tâche assignée, ils travaillent indépendamment jusqu'à son achèvement ou son échec +- **Fournissent des retours détaillés** - Vous pouvez suivre leur progression, l'utilisation des outils et les statistiques d'exécution en temps réel + +## Principaux avantages + +- **Spécialisation des tâches** : Créez des agents optimisés pour des workflows spécifiques (tests, documentation, refactoring, etc.) +- **Isolation du contexte** : Gardez le travail spécialisé séparé de votre conversation principale +- **Réutilisabilité** : Sauvegardez et réutilisez les configurations d'agents entre projets et sessions +- **Accès contrôlé** : Limitez les outils disponibles pour chaque agent afin d'assurer la sécurité et la concentration +- **Visibilité sur l'avancement** : Surveillez l'exécution des agents avec des mises à jour en temps réel + +## Fonctionnement des sous-agents + +1. **Configuration** : Vous définissez des configurations de sous-agents qui spécifient leur comportement, leurs outils et leurs prompts système +2. **Délégation** : L'IA principale peut automatiquement déléguer des tâches aux sous-agents appropriés +3. **Exécution** : Les sous-agents travaillent de manière indépendante en utilisant leurs outils configurés pour accomplir les tâches +4. **Résultats** : Ils renvoient les résultats et un résumé de l'exécution dans la conversation principale + +## Premiers pas + +### Démarrage rapide + +1. **Créer votre premier subagent** : + + ``` + /agents create + ``` + + Suivez l'assistant guidé pour créer un agent spécialisé. + +2. **Gérer les agents existants** : + + ``` + /agents manage + ``` + + Affichez et gérez vos subagents configurés. + +3. **Utiliser les subagents automatiquement** : + Il suffit de demander à l'IA principale d'effectuer des tâches correspondant aux spécialisations de vos subagents. L'IA déléguera automatiquement le travail approprié. + +### Exemple d'utilisation + +``` +Utilisateur : "Veuillez écrire des tests complets pour le module d'authentification" + +IA : Je vais déléguer cela à votre subagent spécialiste des tests. +[Délégue au subagent "testing-expert"] +[Affiche la progression en temps réel de la création des tests] +[Renvoie les fichiers de test terminés et un résumé de l'exécution] +``` + +## Gestion + +### Commandes CLI + +Les subagents sont gérés via la commande slash `/agents` et ses sous-commandes : + +#### `/agents create` + +Crée un nouveau subagent via un assistant étape par étape. + +**Utilisation :** + +``` +/agents create +``` + +#### `/agents manage` + +Ouvre un dialogue de gestion interactive pour visualiser et gérer les sous-agents existants. + +**Utilisation :** + +``` +/agents manage +``` + +### Emplacements de stockage + +Les sous-agents sont stockés sous forme de fichiers Markdown dans deux emplacements : + +- **Niveau projet** : `.qwen/agents/` (prioritaire) +- **Niveau utilisateur** : `~/.qwen/agents/` (solution de repli) + +Cela vous permet d'avoir à la fois des agents spécifiques au projet et des agents personnels qui fonctionnent dans tous les projets. + +### Format de fichier + +Les sous-agents sont configurés à l'aide de fichiers Markdown avec un frontmatter YAML. Ce format est lisible par l'homme et facile à modifier avec n'importe quel éditeur de texte. + +#### Structure de base + +```markdown +--- +name: agent-name +description: Brève description de quand et comment utiliser cet agent +tools: tool1, tool2, tool3 # Optionnel +--- + +Le contenu du prompt système va ici. +Plusieurs paragraphes sont pris en charge. +Vous pouvez utiliser la syntaxe ${variable} pour du contenu dynamique. +``` + +#### Exemple d'utilisation + +```markdown +--- +name: project-documenter +description: Crée la documentation du projet et les fichiers README +--- + +Vous êtes un spécialiste de la documentation pour le projet ${project_name}. + +Votre tâche : ${task_description} + +Répertoire de travail : ${current_directory} +Généré le : ${timestamp} + +Concentrez-vous sur la création d'une documentation claire et complète qui aide +les nouveaux contributeurs et les utilisateurs finaux à comprendre le projet. +``` + +## Exemples + +### Agents de workflow de développement + +#### Testing Specialist + +Parfait pour la création de tests complets et le développement piloté par les tests (TDD). + +```markdown +--- +name: testing-expert +description: Rédige des tests unitaires et d'intégration complets, et gère l'automatisation des tests selon les meilleures pratiques +tools: read_file, write_file, read_many_files, run_shell_command +--- + +Vous êtes un spécialiste des tests, concentré sur la création de tests de haute qualité et maintenables. + +Votre expertise comprend : + +- Les tests unitaires avec mocking et isolation appropriés +- Les tests d'intégration pour les interactions entre composants +- Les pratiques de développement piloté par les tests (TDD) +- L'identification des cas limites et une couverture complète +- Les tests de performance et de charge lorsque cela est pertinent + +Pour chaque tâche de test : + +1. Analysez la structure du code et ses dépendances +2. Identifiez les fonctionnalités clés, les cas limites et les conditions d'erreur +3. Créez des suites de tests complètes avec des noms explicites +4. Incluez une configuration/nettoyage approprié et des assertions significatives +5. Ajoutez des commentaires pour expliquer les scénarios de test complexes +6. Assurez-vous que les tests sont maintenables et respectent les principes DRY + +Suivez toujours les meilleures pratiques de test pour le langage et le framework détectés. +Portez attention aux cas de test positifs et négatifs. +``` + +**Cas d'usage :** + +- "Écrire des tests unitaires pour le service d'authentification" +- "Créer des tests d'intégration pour le workflow de traitement des paiements" +- "Ajouter une couverture de test pour les cas limites dans le module de validation des données" + +#### Documentation Writer + +Spécialisé dans la création de documentation claire et complète. + +```markdown +--- +name: documentation-writer +description: Crée une documentation complète, des fichiers README, de la doc API et des guides utilisateurs +tools: read_file, write_file, read_many_files, web_search +--- + +Vous êtes un spécialiste de la documentation technique pour ${project_name}. + +Votre rôle est de créer une documentation claire et complète qui serve à la fois +les développeurs et les utilisateurs finaux. Concentrez-vous sur : + +**Pour la documentation API :** + +- Des descriptions claires des endpoints avec des exemples +- Les détails des paramètres avec leurs types et contraintes +- La documentation du format des réponses +- Les explications des codes d'erreur +- Les exigences d'authentification + +**Pour la documentation utilisateur :** + +- Des instructions pas à pas avec des captures d'écran quand c'est utile +- Des guides d'installation et de configuration +- Les options de configuration et des exemples +- Des sections de dépannage pour les problèmes courants +- Des FAQ basées sur les questions fréquentes des utilisateurs + +**Pour la documentation développeur :** + +- Des aperçus de l'architecture et des décisions de conception +- Des exemples de code qui fonctionnent vraiment +- Des guidelines pour contribuer +- La configuration de l'environnement de développement + +Vérifiez toujours les exemples de code et assurez-vous que la documentation reste à jour avec +l'implémentation actuelle. Utilisez des titres clairs, des listes à puces et des exemples. +``` + +**Cas d'usage :** + +- "Créez la documentation API pour les endpoints de gestion des utilisateurs" +- "Écrivez un README complet pour ce projet" +- "Documentez le processus de déploiement avec des étapes de dépannage" + +#### Code Reviewer + +Axé sur la qualité du code, la sécurité et les bonnes pratiques. + +```markdown +--- +name: code-reviewer +description: Examine le code pour vérifier les bonnes pratiques, les problèmes de sécurité, les performances et la maintenabilité +tools: read_file, read_many_files +--- + +Vous êtes un relecteur de code expérimenté, concentré sur la qualité, la sécurité et la maintenabilité. + +Critères d'évaluation : + +- **Structure du code** : Organisation, modularité et séparation des responsabilités +- **Performance** : Efficacité algorithmique et utilisation des ressources +- **Sécurité** : Évaluation des vulnérabilités et pratiques de codage sécurisé +- **Bonnes pratiques** : Conventions spécifiques au langage/au framework +- **Gestion des erreurs** : Gestion correcte des exceptions et couverture des cas limites +- **Lisibilité** : Nommage clair, commentaires et organisation du code +- **Tests** : Couverture des tests et facilité de testabilité + +Fournissez des retours constructifs comprenant : + +1. **Problèmes critiques** : Vulnérabilités de sécurité, bugs majeurs +2. **Améliorations importantes** : Problèmes de performance, problèmes de conception +3. **Suggestions mineures** : Améliorations stylistiques, opportunités de refactoring +4. **Retours positifs** : Patterns bien implémentés et bonnes pratiques + +Concentrez-vous sur des retours exploitables avec des exemples précis et des solutions suggérées. +Priorisez les problèmes par impact et fournissez une justification pour vos recommandations. +``` + +**Cas d'utilisation :** + +- "Examinez cette implémentation d'authentification pour identifier les problèmes de sécurité" +- "Analysez les implications de performance de cette logique de requête de base de données" +- "Évaluez la structure du code et suggérez des améliorations" + +### Agents Spécifiques aux Technologies + +#### Spécialiste React + +Optimisé pour le développement React, les hooks et les patterns de composants. + +```markdown +--- +name: react-specialist +description: Expert en développement React, hooks, patterns de composants et meilleures pratiques React modernes +tools: read_file, write_file, read_many_files, run_shell_command +--- + +Vous êtes un spécialiste React avec une expertise approfondie en développement React moderne. + +Votre expertise couvre : + +- **Conception de composants** : Composants fonctionnels, hooks personnalisés, patterns de composition +- **Gestion d'état** : useState, useReducer, Context API et bibliothèques externes +- **Performance** : React.memo, useMemo, useCallback, code splitting +- **Testing** : React Testing Library, Jest, stratégies de testing de composants +- **Intégration TypeScript** : Typage approprié pour les props, hooks et composants +- **Patterns modernes** : Suspense, Error Boundaries, fonctionnalités concurrentes + +Pour les tâches React : + +1. Utilisez des composants fonctionnels et des hooks par défaut +2. Implémentez un typage TypeScript approprié +3. Suivez les meilleures pratiques et conventions React +4. Considérez les implications de performance +5. Incluez une gestion d'erreurs appropriée +6. Écrivez du code testable et maintenable + +Restez toujours à jour avec les meilleures pratiques React et évitez les patterns dépréciés. +Focalisez-vous sur les considérations d'accessibilité et d'expérience utilisateur. +``` + +**Cas d'usage :** + +- "Créer un composant de tableau de données réutilisable avec tri et filtrage" +- "Implémenter un hook personnalisé pour la récupération de données API avec mise en cache" +- "Refactorer ce composant classe pour utiliser les patterns React modernes" + +#### Python Expert + +Spécialisé dans le développement Python, les frameworks et les meilleures pratiques. + +```markdown +--- +name: python-expert +description: Expert en développement Python, frameworks, testing, et meilleures pratiques spécifiques à Python +tools: read_file, write_file, read_many_files, run_shell_command +--- + +Vous êtes un expert Python avec une connaissance approfondie de l'écosystème Python. + +Votre expertise inclut : + +- **Python de base** : Patterns pythoniques, structures de données, algorithmes +- **Frameworks** : Django, Flask, FastAPI, SQLAlchemy +- **Testing** : pytest, unittest, mocking, test-driven development +- **Data Science** : pandas, numpy, matplotlib, jupyter notebooks +- **Programmation asynchrone** : asyncio, patterns async/await +- **Gestion des paquets** : pip, poetry, environnements virtuels +- **Qualité du code** : PEP 8, type hints, linting avec pylint/flake8 + +Pour les tâches Python : + +1. Suivez les directives de style PEP 8 +2. Utilisez des type hints pour une meilleure documentation du code +3. Implémentez une gestion d'erreurs appropriée avec des exceptions spécifiques +4. Écrivez des docstrings complètes +5. Prenez en compte les performances et l'utilisation de la mémoire +6. Incluez un logging approprié +7. Écrivez du code modulaire et testable + +Concentrez-vous sur l'écriture de code Python propre et maintenable qui suit les standards de la communauté. +``` + +**Cas d'usage :** + +- "Créer un service FastAPI pour l'authentification des utilisateurs avec des tokens JWT" +- "Implémenter un pipeline de traitement de données avec pandas et gestion des erreurs" +- "Écrire un outil CLI en utilisant argparse avec une documentation d'aide complète" + +## Bonnes pratiques + +### Principes de conception + +#### Principe de responsabilité unique + +Chaque sous-agent doit avoir un objectif clair et précis. + +**✅ Bon :** + +```markdown +--- +name: testing-expert +description: Writes comprehensive unit tests and integration tests +--- +``` + +**❌ À éviter :** + +```markdown +--- +name: general-helper +description: Helps with testing, documentation, code review, and deployment +--- +``` + +**Pourquoi :** Des agents focalisés produisent de meilleurs résultats et sont plus faciles à maintenir. + +#### Spécialisation claire + +Définissez des domaines d'expertise spécifiques plutôt que des compétences générales. + +**✅ Bon :** + +```markdown +--- +name: react-performance-optimizer +description: Optimizes React applications for performance using profiling and best practices +--- +``` + +**❌ À éviter :** + +```markdown +--- +name: frontend-developer +description: Works on frontend development tasks +--- +``` + +**Pourquoi :** Une expertise spécifique permet une assistance plus ciblée et efficace. + +#### Descriptions Actionnables + +Rédigez des descriptions qui indiquent clairement quand utiliser l'agent. + +**✅ Bon :** + +```markdown +description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns +``` + +**❌ À éviter :** + +```markdown +description: A helpful code reviewer +``` + +**Pourquoi :** Des descriptions claires aident l'IA principale à choisir le bon agent pour chaque tâche. + +### Bonnes Pratiques de Configuration + +#### Guidelines pour le Prompt Système + +**Précisez votre expertise :** + +```markdown +Vous êtes un spécialiste Python testing avec une expertise dans : + +- Le framework pytest et les fixtures +- Les objets Mock et l'injection de dépendances +- Les pratiques de développement piloté par les tests (TDD) +- Le testing de performance avec pytest-benchmark +``` + +**Incluez des approches étape par étape :** + +```markdown +Pour chaque tâche de testing : + +1. Analysez la structure du code et ses dépendances +2. Identifiez les fonctionnalités clés et les cas limites +3. Créez des suites de tests complètes avec des noms clairs +4. Incluez le setup/teardown et les assertions appropriées +5. Ajoutez des commentaires expliquant les scénarios de test complexes +``` + +**Spécifiez les standards de sortie :** + +```markdown +Suivez toujours ces standards : + +- Utilisez des noms de test descriptifs qui expliquent le scénario +- Incluez à la fois des cas de test positifs et négatifs +- Ajoutez des docstrings pour les fonctions de test complexes +- Assurez-vous que les tests sont indépendants et peuvent s'exécuter dans n'importe quel ordre +``` + +## Considérations de sécurité + +- **Restrictions des outils** : Les subagents n'ont accès qu'aux outils configurés +- **Sandboxing** : Toute exécution d'outil suit le même modèle de sécurité que l'utilisation directe des outils +- **Journal d'audit** : Toutes les actions des subagents sont enregistrées et visibles en temps réel +- **Contrôle d'accès** : La séparation au niveau projet et utilisateur fournit des limites appropriées +- **Informations sensibles** : Évitez d'inclure des secrets ou des identifiants dans les configurations des agents +- **Environnements de production** : Envisagez d'utiliser des agents distincts pour les environnements de production et de développement \ No newline at end of file diff --git a/website/content/fr/telemetry.md b/website/content/fr/telemetry.md index afd1b56d..a8eda139 100644 --- a/website/content/fr/telemetry.md +++ b/website/content/fr/telemetry.md @@ -6,7 +6,7 @@ Le système de télémétrie de Qwen Code est basé sur la norme **[OpenTelemetr [OpenTelemetry]: https://opentelemetry.io/ -## Activation de la télémétrie +## Activer la télémétrie Vous pouvez activer la télémétrie de plusieurs façons. La configuration est principalement gérée via le fichier [`.qwen/settings.json`](./cli/configuration.md) et les variables d'environnement, mais les flags CLI peuvent outrepasser ces paramètres pour une session spécifique. @@ -26,7 +26,7 @@ Voici la liste des priorités d'application des paramètres de télémétrie, le 1. **Fichier de paramètres du workspace (`.qwen/settings.json`) :** Valeurs provenant de l'objet `telemetry` dans ce fichier spécifique au projet. -1. **Fichier de paramètres utilisateur (`~/.qwen/settings.json`) :** Valeurs provenant de l'objet `telemetry` dans ce fichier global utilisateur. +1. **Fichier de paramètres utilisateur (`~/.qwen/settings.json`) :** Valeurs provenant de l'objet `telemetry` dans ce fichier global de l'utilisateur. 1. **Valeurs par défaut :** appliquées si elles ne sont définies par aucun des moyens ci-dessus. - `telemetry.enabled` : `false` @@ -35,7 +35,7 @@ Voici la liste des priorités d'application des paramètres de télémétrie, le - `telemetry.logPrompts` : `true` **Pour le script `npm run telemetry -- --target=` :** -L'argument `--target` de ce script remplace _uniquement_ `telemetry.target` pendant la durée et à la seule fin de ce script (c'est-à-dire choisir quel collecteur démarrer). Il ne modifie pas de manière permanente votre `settings.json`. Le script regardera d'abord dans `settings.json` s'il y a un `telemetry.target` à utiliser comme valeur par défaut. +L'argument `--target` de ce script ne remplace _que_ `telemetry.target` le temps de l'exécution et dans le but de ce script (c'est-à-dire choisir quel collector démarrer). Il ne modifie pas de manière permanente votre `settings.json`. Le script regardera d'abord dans `settings.json` s'il y a un `telemetry.target` à utiliser comme valeur par défaut. ### Exemple de configuration @@ -59,10 +59,10 @@ Pour activer l'export vers un fichier, utilisez le flag `--telemetry-outfile` av ```bash -# Définir le chemin du fichier de sortie +# Définissez le chemin du fichier de sortie souhaité TELEMETRY_FILE=".qwen/telemetry.log" -# Exécuter Qwen Code avec la télémétrie locale +# Exécutez Qwen Code avec la télémétrie locale # NOTE : --telemetry-otlp-endpoint="" est requis pour remplacer l'exporter @@ -77,7 +77,11 @@ qwen --telemetry \ ## Exécuter un OTEL Collector Un OTEL Collector est un service qui reçoit, traite et exporte les données de télémétrie. -La CLI envoie les données en utilisant le protocole OTLP/gRPC. +Le CLI peut envoyer des données en utilisant soit le protocole OTLP/gRPC, soit le protocole OTLP/HTTP. +Vous pouvez spécifier le protocole à utiliser via le flag `--telemetry-otlp-protocol` +ou le paramètre `telemetry.otlpProtocol` dans votre fichier `settings.json`. Consultez la +[documentation de configuration](./cli/configuration.md#--telemetry-otlp-protocol) pour plus +de détails. Pour en savoir plus sur la configuration standard de l'exporter OTEL, consultez la [documentation][otel-config-docs]. @@ -85,7 +89,7 @@ Pour en savoir plus sur la configuration standard de l'exporter OTEL, consultez ### Local -Utilisez la commande `npm run telemetry -- --target=local` pour automatiser le processus de configuration d’un pipeline de télémétrie local, y compris la configuration des paramètres nécessaires dans votre fichier `.qwen/settings.json`. Le script sous-jacent installe `otelcol-contrib` (le OpenTelemetry Collector) et `jaeger` (l’interface Jaeger pour visualiser les traces). Pour l’utiliser : +Utilisez la commande `npm run telemetry -- --target=local` pour automatiser la configuration d’un pipeline de télémétrie local, y compris la configuration des paramètres nécessaires dans votre fichier `.qwen/settings.json`. Le script sous-jacent installe `otelcol-contrib` (le OpenTelemetry Collector) et `jaeger` (l’interface Jaeger pour visualiser les traces). Pour l’utiliser : 1. **Exécutez la commande** : Lancez la commande depuis la racine du repository : @@ -115,7 +119,7 @@ Utilisez la commande `npm run telemetry -- --target=local` pour automatiser le p Utilisez la commande `npm run telemetry -- --target=gcp` pour automatiser la configuration d’un collecteur OpenTelemetry local qui transmet les données à votre projet Google Cloud, y compris la configuration des paramètres nécessaires dans votre fichier `.qwen/settings.json`. Le script sous-jacent installe `otelcol-contrib`. Pour l’utiliser : 1. **Prérequis** : - - Avoir un ID de projet Google Cloud. + - Disposer d’un ID de projet Google Cloud. - Exporter la variable d’environnement `GOOGLE_CLOUD_PROJECT` pour la rendre disponible au collecteur OTEL. ```bash export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" @@ -138,13 +142,13 @@ Utilisez la commande `npm run telemetry -- --target=gcp` pour automatiser la con - À l’arrêt (Ctrl+C), il tentera de restaurer vos paramètres initiaux de télémétrie et de sandbox. 1. **Exécutez Qwen Code** : - Dans un autre terminal, lancez vos commandes Qwen Code. Cela génère des données de télémétrie que le collecteur va capturer. + Dans un autre terminal, lancez vos commandes Qwen Code. Cela génère des données de télémétrie que le collecteur capture. 1. **Visualisez la télémétrie dans Google Cloud** : Utilisez les liens fournis par le script pour accéder à la Google Cloud Console et consulter vos traces, métriques et logs. 1. **Consultez les logs du collecteur local** : - Le script redirige la sortie du collecteur OTEL local vers `~/.qwen/tmp//otel/collector-gcp.log`. Le script fournit également des liens pour visualiser et une commande pour suivre en direct les logs du collecteur localement. + Le script redirige la sortie du collecteur OTEL local vers `~/.qwen/tmp//otel/collector-gcp.log`. Le script fournit des liens pour visualiser et une commande pour suivre en direct les logs du collecteur localement. 1. **Arrêtez le service** : Appuyez sur `Ctrl+C` dans le terminal où le script est en cours d’exécution pour arrêter le collecteur OTEL. @@ -157,7 +161,7 @@ La section suivante décrit la structure des logs et métriques générés pour ### Logs -Les logs sont des enregistrements horodatés d'événements spécifiques. Les événements suivants sont loggués pour Qwen Code : +Les logs sont des enregistrements horodatés d'événements spécifiques. Les événements suivants sont loggés pour Qwen Code : - `qwen-code.config` : Cet événement se produit une fois au démarrage avec la configuration du CLI. - **Attributs** : @@ -180,7 +184,7 @@ Les logs sont des enregistrements horodatés d'événements spécifiques. Les é - `prompt` (cet attribut est exclu si `log_prompts_enabled` est configuré à `false`) - `auth_type` -- `qwen-code.tool_call` : Cet événement se produit à chaque appel de fonction. +- `qwen-code.tool_call` : Cet événement se produit pour chaque appel de fonction. - **Attributs** : - `function_name` - `function_args` @@ -191,7 +195,7 @@ Les logs sont des enregistrements horodatés d'événements spécifiques. Les é - `error_type` (si applicable) - `metadata` (si applicable, dictionnaire de string -> any) -- `qwen-code.api_request` : Cet événement se produit lorsqu'une requête est envoyée à l'API Gemini. +- `qwen-code.api_request` : Cet événement se produit lorsqu'une requête est envoyée à l'API Qwen. - **Attributs** : - `model` - `request_text` (si applicable) @@ -205,7 +209,7 @@ Les logs sont des enregistrements horodatés d'événements spécifiques. Les é - `duration_ms` - `auth_type` -- `qwen-code.api_response` : Cet événement se produit lors de la réception d'une réponse de l'API Gemini. +- `qwen-code.api_response` : Cet événement se produit lorsqu'une réponse est reçue de l'API Qwen. - **Attributs** : - `model` - `status_code` @@ -230,7 +234,7 @@ Les logs sont des enregistrements horodatés d'événements spécifiques. Les é ### Metrics -Les métriques sont des mesures numériques du comportement dans le temps. Les métriques suivantes sont collectées pour Qwen Code (les noms des métriques restent `qwen-code.*` pour des raisons de compatibilité) : +Les métriques sont des mesures numériques du comportement au fil du temps. Les métriques suivantes sont collectées pour Qwen Code (les noms des métriques restent `qwen-code.*` pour des raisons de compatibilité) : - `qwen-code.session.count` (Compteur, Int) : Incrémenté une fois à chaque démarrage du CLI. @@ -239,6 +243,7 @@ Les métriques sont des mesures numériques du comportement dans le temps. Les m - `function_name` - `success` (booléen) - `decision` (chaîne : "accept", "reject", ou "modify", si applicable) + - `tool_type` (chaîne : "mcp", ou "native", si applicable) - `qwen-code.tool.call.latency` (Histogramme, ms) : Mesure la latence des appels d'outils. - **Attributs** : @@ -269,4 +274,9 @@ Les métriques sont des mesures numériques du comportement dans le temps. Les m - `ai_added_lines` (Int, si applicable) : Nombre de lignes ajoutées/modifiées par l'IA. - `ai_removed_lines` (Int, si applicable) : Nombre de lignes supprimées/modifiées par l'IA. - `user_added_lines` (Int, si applicable) : Nombre de lignes ajoutées/modifiées par l'utilisateur dans les modifications proposées par l'IA. - - `user_removed_lines` (Int, si applicable) : Nombre de lignes supprimées/modifiées par l'utilisateur dans les modifications proposées par l'IA. \ No newline at end of file + - `user_removed_lines` (Int, si applicable) : Nombre de lignes supprimées/modifiées par l'utilisateur dans les modifications proposées par l'IA. + +- `qwen-code.chat_compression` (Compteur, Int) : Compte les opérations de compression du chat. + - **Attributs** : + - `tokens_before` (Int) : Nombre de tokens dans le contexte avant compression. + - `tokens_after` (Int) : Nombre de tokens dans le contexte après compression. \ No newline at end of file diff --git a/website/content/fr/tools/file-system.md b/website/content/fr/tools/file-system.md index daba0b9a..05cb7a37 100644 --- a/website/content/fr/tools/file-system.md +++ b/website/content/fr/tools/file-system.md @@ -2,7 +2,7 @@ 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 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. +**Note :** Tous les outils de système de fichiers fonctionnent dans un `rootDirectory` (généralement le répertoire de travail actuel 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) @@ -31,15 +31,15 @@ Qwen Code fournit une suite complète d'outils pour interagir avec le système d - **Fichier :** `read-file.ts` - **Paramètres :** - `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. + - `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. Si omis, lit un maximum par défaut (ex. : 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 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 fichiers image et PDF : Retourne le contenu du fichier sous forme d’une structure 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...`). - - Pour les fichiers image/PDF : Un objet contenant `inlineData` avec `mimeType` et les `data` encodées en base64 (par exemple, `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`). + - Pour les fichiers texte : Le contenu du fichier, éventuellement précédé d’un message de troncature (ex. : `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`). + - Pour les fichiers image/PDF : Un objet contenant `inlineData` avec `mimeType` et les `data` encodées en base64 (ex. : `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`). - Pour les autres fichiers binaires : Un message tel que `Cannot display content of binary file: /path/to/data.bin`. - **Confirmation :** Non. @@ -56,8 +56,8 @@ 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`. -- **Confirmation :** Oui. Affiche un diff des changements et demande l'approbation de l'utilisateur avant d'écrire. +- **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 modifications et demande l'approbation de l'utilisateur avant d'écrire. ## 4. `glob` (FindFiles) @@ -69,31 +69,31 @@ 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 ê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`. + - `case_sensitive` (boolean, optionnel) : Indique si la recherche doit être sensible à la casse. Par défaut, `false`. + - `respect_git_ignore` (boolean, optionnel) : Indique si les règles définies dans `.gitignore` doivent être respectées. 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). + - Retourne une liste de chemins absolus, triés du plus récemment modifié au plus ancien. - Ignore par défaut les répertoires courants inutiles comme `node_modules` et `.git`. -- **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...` +- **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...` - **Confirmation :** Non. ## 5. `search_file_content` (SearchText) -`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. +`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 via un motif glob. Retourne les lignes contenant des correspondances, avec leurs chemins de fichiers 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 (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. + - `pattern` (string, requis) : L'expression régulière à rechercher (ex. : `"function\s+myFunction"`). + - `path` (string, optionnel) : Le chemin absolu du répertoire dans lequel effectuer la recherche. Par défaut, utilise le répertoire de travail courant. - `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. + - `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, 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. + - Utilise `git grep` si disponible dans un dépôt Git pour plus de rapidité ; sinon, utilise `grep` système ou une recherche en 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. + - Limite les résultats à 20 correspondances par défaut pour éviter un dépassement de contexte. En cas de troncature, affiche un avertissement clair avec des conseils pour affiner la recherche. - **Sortie (`llmContent`) :** Une chaîne formatée des correspondances, par exemple : ``` @@ -136,38 +136,38 @@ Rechercher un motif avec filtrage des fichiers et limitation personnalisée des search_file_content(pattern="function", include="*.js", maxResults=10) ``` -## 6. `replace` (Modifier) +## 6. `edit` (Modifier) -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. +`edit` 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. -- **Nom de l’outil :** `replace` -- **Nom d’affichage :** Modifier +- **Nom de l'outil :** `edit` +- **Nom affiché :** Modifier - **Fichier :** `edit.ts` - **Paramètres :** - - `file_path` (string, requis) : Le chemin absolu du fichier à modifier. - - `old_string` (string, requis) : Le texte exact à remplacer. + - `file_path` (string, requis) : Le chemin absolu vers le fichier à modifier. + - `old_string` (string, requis) : Le texte littéral exact à remplacer. - **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. + **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 exact qui remplacera `old_string`. - - `expected_replacements` (number, optionnel) : Le nombre d’occurrences à remplacer. Par défaut : `1`. + - `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`. - **Comportement :** - - 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. + - 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 le fichier `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, notamment lorsque la `old_string` fournie par le modèle n'est pas parfaitement précise, l'outil intègre un mécanisme de correction d'édition en plusieurs étapes. + - Si la `old_string` initiale n'est pas trouvée ou correspond à plusieurs endroits, l'outil peut utiliser le modèle Qwen 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 `edit` 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 correspondance unique et non ambiguë. - **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 (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. + - 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. -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 +Ces outils du système de fichiers fournissent une base pour que Qwen Code puisse comprendre et interagir avec le contexte de votre projet local. \ No newline at end of file diff --git a/website/content/fr/tools/mcp-server.md b/website/content/fr/tools/mcp-server.md index 5b1ed4ee..0e69c45d 100644 --- a/website/content/fr/tools/mcp-server.md +++ b/website/content/fr/tools/mcp-server.md @@ -16,21 +16,21 @@ Avec un serveur MCP, vous pouvez étendre les capacités du CLI pour effectuer d ## Architecture d'intégration principale -Qwen Code s'intègre avec les serveurs MCP via un système sophistiqué de découverte et d'exécution intégré dans le package principal (`packages/core/src/tools/`) : +Qwen Code s'intègre aux serveurs MCP via un système sophistiqué de découverte et d'exécution intégré dans le package principal (`packages/core/src/tools/`) : ### Couche de découverte (`mcp-client.ts`) Le processus de découverte est orchestré par `discoverMcpTools()`, qui : 1. **Parcourt les serveurs configurés** à partir de la configuration `mcpServers` de votre `settings.json` -2. **Établit des connexions** en utilisant les mécanismes de transport appropriés (Stdio, SSE, ou Streamable HTTP) +2. **Établit des connexions** en utilisant les mécanismes de transport appropriés (Stdio, SSE ou Streamable HTTP) 3. **Récupère les définitions des outils** depuis chaque serveur en utilisant le protocole MCP -4. **Nettoie et valide** les schémas des outils pour assurer la compatibilité avec l'API Gemini +4. **Nettoie et valide** les schémas des outils pour assurer la compatibilité avec l'API Qwen 5. **Enregistre les outils** dans le registre global des outils avec résolution des conflits ### Couche d'exécution (`mcp-tool.ts`) -Chaque outil MCP découvert est encapsulé dans une instance de `DiscoveredMCPTool` qui : +Chaque outil MCP découvert est encapsulé dans une instance `DiscoveredMCPTool` qui : - **Gère la logique de confirmation** en fonction des paramètres de confiance du serveur et des préférences utilisateur - **Assure l'exécution de l'outil** en appelant le serveur MCP avec les paramètres appropriés @@ -39,11 +39,11 @@ Chaque outil MCP découvert est encapsulé dans une instance de `DiscoveredMCPTo ### Mécanismes de transport -Le CLI prend en charge trois types de transport MCP : +Le CLI supporte trois types de transport MCP : - **Transport Stdio :** Lance un sous-processus et communique via stdin/stdout - **Transport SSE :** Se connecte aux endpoints Server-Sent Events -- **Transport HTTP streamable :** Utilise le streaming HTTP pour la communication +- **Transport HTTP Streamable :** Utilise le streaming HTTP pour la communication ## Comment configurer votre serveur MCP @@ -78,10 +78,10 @@ Ajoutez un objet `mcpServers` à votre fichier `settings.json` : Chaque configuration de serveur prend en charge les propriétés suivantes : -#### Requis (un des éléments suivants) +#### Requis (un des suivants) - **`command`** (string) : Chemin vers l'exécutable pour le transport Stdio -- **`url`** (string) : URL du endpoint SSE (ex. : `"http://localhost:8080/sse"`) +- **`url`** (string) : URL du endpoint SSE (ex. `"http://localhost:8080/sse"`) - **`httpUrl`** (string) : URL du endpoint HTTP streaming #### Optionnel @@ -90,10 +90,10 @@ Chaque configuration de serveur prend en charge les propriétés suivantes : - **`headers`** (object) : En-têtes HTTP personnalisés lors de l'utilisation de `url` ou `httpUrl` - **`env`** (object) : Variables d'environnement pour le processus du serveur. Les valeurs peuvent référencer des variables d'environnement en utilisant la syntaxe `$VAR_NAME` ou `${VAR_NAME}` - **`cwd`** (string) : Répertoire de travail pour le transport Stdio -- **`timeout`** (number) : Délai d'expiration de la requête en millisecondes (par défaut : 600 000 ms = 10 minutes) +- **`timeout`** (number) : Délai d'expiration des requêtes en millisecondes (par défaut : 600 000 ms = 10 minutes) - **`trust`** (boolean) : Si `true`, contourne toutes les confirmations d'appel d'outils pour ce serveur (par défaut : `false`) - **`includeTools`** (string[]) : Liste des noms d'outils à inclure depuis ce serveur MCP. Lorsque cette liste est spécifiée, seuls les outils listés ici seront disponibles depuis ce serveur (comportement de liste blanche). Si non spécifié, tous les outils du serveur sont activés par défaut. -- **`excludeTools`** (string[]) : Liste des noms d'outils à exclure de ce serveur MCP. Les outils listés ici ne seront pas disponibles pour le modèle, même s'ils sont exposés par le serveur. **Note :** `excludeTools` prime sur `includeTools` – si un outil est présent dans les deux listes, il sera exclu. +- **`excludeTools`** (string[]) : Liste des noms d'outils à exclure de ce serveur MCP. Les outils listés ici ne seront pas disponibles pour le modèle, même s'ils sont exposés par le serveur. **Note :** `excludeTools` a priorité sur `includeTools` – si un outil est présent dans les deux listes, il sera exclu. ### Support OAuth pour les serveurs MCP distants @@ -101,7 +101,7 @@ Qwen Code prend en charge l'authentification OAuth 2.0 pour les serveurs MCP dis #### Découverte automatique OAuth -Pour les serveurs qui prennent en charge la découverte OAuth, vous pouvez omettre la configuration OAuth et laisser le CLI la découvrir automatiquement : +Pour les serveurs qui supportent la découverte OAuth, vous pouvez omettre la configuration OAuth et laisser le CLI la découvrir automatiquement : ```json { @@ -117,7 +117,7 @@ Le CLI va automatiquement : - Détecter quand un serveur requiert une authentification OAuth (réponses 401) - Découvrir les endpoints OAuth depuis les métadonnées du serveur -- Effectuer un enregistrement dynamique du client si pris en charge +- Effectuer un enregistrement dynamique du client si supporté - Gérer le flux OAuth et la gestion des tokens #### Flux d'authentification @@ -141,8 +141,8 @@ Lors de la connexion à un serveur compatible OAuth : Cette fonctionnalité ne fonctionnera pas dans : - Des environnements headless sans accès au navigateur -- Des sessions SSH distantes sans forwarding X11 -- Des environnements conteneurisés sans support du navigateur +- Des sessions SSH distantes sans X11 forwarding +- Des environnements containerisés sans support du navigateur #### Gestion de l'authentification OAuth @@ -155,22 +155,22 @@ Utilisez la commande `/mcp auth` pour gérer l'authentification OAuth : ``` ```markdown -# S'authentifier avec un serveur spécifique +# Authentification avec un serveur spécifique /mcp auth serverName -# Ré-authentifier si les tokens expirent +# Ré-authentification si les tokens expirent /mcp auth serverName ``` #### Propriétés de configuration OAuth - **`enabled`** (boolean): Active OAuth pour ce serveur -- **`clientId`** (string): Identifiant du client OAuth (optionnel avec l'enregistrement dynamique) +- **`clientId`** (string): Identifiant du client OAuth (optionnel avec enregistrement dynamique) - **`clientSecret`** (string): Secret du client OAuth (optionnel pour les clients publics) - **`authorizationUrl`** (string): Endpoint d'autorisation OAuth (auto-découvert si omis) - **`tokenUrl`** (string): Endpoint de token OAuth (auto-découvert si omis) - **`scopes`** (string[]): Scopes OAuth requis -- **`redirectUri`** (string): URI de redirection personnalisée (par défaut : `http://localhost:7777/oauth/callback`) +- **`redirectUri`** (string): URI de redirection personnalisée (par défaut `http://localhost:7777/oauth/callback`) - **`tokenParamName`** (string): Nom du paramètre de requête pour les tokens dans les URLs SSE - **`audiences`** (string[]): Audiences pour lesquelles le token est valide ``` @@ -188,7 +188,7 @@ Les tokens OAuth sont automatiquement : Vous pouvez spécifier le type de fournisseur d'authentification en utilisant la propriété `authProviderType` : -- **`authProviderType`** (string) : Spécifie le fournisseur d'authentification. Peut être l'une des valeurs suivantes : +- **`authProviderType`** (string) : Spécifie le fournisseur d'authentification. Peut prendre l'une des valeurs suivantes : - **`dynamic_discovery`** (par défaut) : Le CLI découvrira automatiquement la configuration OAuth depuis le serveur. - **`google_credentials`** : Le CLI utilisera les Google Application Default Credentials (ADC) pour s'authentifier auprès du serveur. Lorsque vous utilisez ce fournisseur, vous devez spécifier les scopes requis. @@ -208,7 +208,7 @@ Vous pouvez spécifier le type de fournisseur d'authentification en utilisant la ### Exemples de configurations -#### Python MCP Server (Stdio) +#### Serveur MCP Python (Stdio) ```json { @@ -227,7 +227,7 @@ Vous pouvez spécifier le type de fournisseur d'authentification en utilisant la } ``` -#### Node.js MCP Server (Stdio) +#### Serveur MCP Node.js (Stdio) ```json { @@ -242,7 +242,7 @@ Vous pouvez spécifier le type de fournisseur d'authentification en utilisant la } ``` -#### MCP Server basé sur Docker +#### Serveur MCP basé sur Docker ```json { @@ -280,7 +280,7 @@ Vous pouvez spécifier le type de fournisseur d'authentification en utilisant la } ``` -#### Serveur MCP basé sur HTTP avec headers personnalisés +#### Serveur MCP basé sur HTTP avec en-têtes personnalisés ```json { @@ -337,9 +337,9 @@ Une fois la connexion établie : 1. **Liste des outils :** Le client appelle l'endpoint de liste des outils du serveur MCP 2. **Validation du schéma :** La déclaration de chaque fonction d'outil est validée 3. **Filtrage des outils :** Les outils sont filtrés en fonction de la configuration `includeTools` et `excludeTools` -4. **Nettoyage des noms :** Les noms des outils sont nettoyés pour respecter les exigences de l'API Gemini : +4. **Nettoyage des noms :** Les noms des outils sont nettoyés pour respecter les exigences de l'API Qwen : - Les caractères invalides (non alphanumériques, underscore, point, trait d'union) sont remplacés par des underscores - - Les noms de plus de 63 caractères sont tronqués avec remplacement au milieu (`___`) + - Les noms de plus de 63 caractères sont tronqués avec un remplacement au milieu (`___`) ### 3. Résolution des conflits @@ -349,28 +349,28 @@ Lorsque plusieurs serveurs exposent des outils portant le même nom : 2. **Préfixage automatique :** Les serveurs suivants reçoivent des noms préfixés : `serverName__toolName` 3. **Suivi dans le registre :** Le registre des outils maintient les correspondances entre les noms de serveurs et leurs outils -### 4. Traitement des Schémas +### 4. Traitement des schémas Les schémas de paramètres des outils sont nettoyés pour assurer la compatibilité avec l'API : - Les propriétés **`$schema`** sont supprimées - Les propriétés **`additionalProperties`** sont retirées -- Les clauses **`anyOf` avec `default`** voient leurs valeurs par défaut supprimées (pour la compatibilité Vertex AI) +- Les blocs **`anyOf` avec `default`** voient leurs valeurs par défaut supprimées (pour la compatibilité Vertex AI) - Un traitement **récursif** est appliqué aux schémas imbriqués -### 5. Gestion des Connexions +### 5. Gestion des connexions -Après la découverte des outils : +Après la découverte : - **Connexions persistantes :** Les serveurs ayant réussi à enregistrer des outils conservent leur connexion - **Nettoyage :** Les connexions des serveurs ne fournissant aucun outil utilisable sont fermées -- **Mise à jour du statut :** Le statut final des serveurs est défini à `CONNECTED` ou `DISCONNECTED` +- **Mise à jour du statut :** Le statut final des serveurs est défini sur `CONNECTED` ou `DISCONNECTED` -## Flux d'Exécution des Outils +## Flux d'exécution des outils Lorsque le modèle décide d'utiliser un outil MCP, le flux d'exécution suivant se produit : -### 1. Invocation de l'Outil +### 1. Invocation de l'outil Le modèle génère un `FunctionCall` contenant : @@ -396,11 +396,11 @@ Le système maintient des listes d'autorisation internes pour : - **Niveau serveur :** `serverName` → Tous les outils de ce serveur sont approuvés - **Niveau outil :** `serverName.toolName` → Cet outil spécifique est approuvé -#### Gestion du choix utilisateur +#### Gestion des choix utilisateur Lorsqu'une confirmation est requise, les utilisateurs peuvent choisir : -- **Procéder une fois :** Exécuter uniquement cette fois-ci +- **Exécuter une fois :** Exécuter uniquement cette fois-ci - **Toujours autoriser cet outil :** Ajouter à la liste d'autorisation au niveau de l'outil - **Toujours autoriser ce serveur :** Ajouter à la liste d'autorisation au niveau du serveur - **Annuler :** Abandonner l'exécution @@ -410,7 +410,7 @@ Lorsqu'une confirmation est requise, les utilisateurs peuvent choisir : Après confirmation (ou contournement de la vérification de confiance) : 1. **Préparation des paramètres :** Les arguments sont validés par rapport au schéma de l'outil -2. **Appel MCP :** Le `CallableTool` sous-jacent invoque le serveur avec : +2. **Appel MCP :** L'outil `CallableTool` sous-jacent invoque le serveur avec : ```typescript const functionCalls = [ @@ -427,7 +427,7 @@ Après confirmation (ou contournement de la vérification de confiance) : Le résultat de l'exécution contient : -- **`llmContent` :** Parties de la réponse brute destinées au contexte du modèle de langage +- **`llmContent` :** Parties de la réponse brute destinées au contexte du modèle linguistique - **`returnDisplay` :** Sortie formatée pour l'affichage utilisateur (souvent du JSON dans des blocs de code markdown) ## Comment interagir avec votre serveur MCP @@ -444,11 +444,11 @@ Elle affiche : - **Liste des serveurs :** Tous les serveurs MCP configurés - **Statut de connexion :** `CONNECTED`, `CONNECTING`, ou `DISCONNECTED` -- **Détails du serveur :** Résumé de la configuration (données sensibles exclues) +- **Détails du serveur :** Résumé de la configuration (sans les données sensibles) - **Outils disponibles :** Liste des outils de chaque serveur avec leurs descriptions - **État de découverte :** Statut global du processus de découverte -### Exemple de sortie de `/mcp` +### Exemple de sortie de la commande `/mcp` ``` MCP Servers Status: @@ -470,34 +470,34 @@ MCP Servers Status: Discovery State: COMPLETED ``` -### Utilisation des Tools +### Utilisation des outils -Une fois découverts, les tools MCP sont disponibles pour le modèle Gemini comme des tools intégrés. Le modèle va automatiquement : +Une fois découverts, les outils MCP sont disponibles pour le modèle Qwen comme des outils intégrés. Le modèle va automatiquement : -1. **Sélectionner les tools appropriés** en fonction de vos requêtes +1. **Sélectionner les outils appropriés** en fonction de vos requêtes 2. **Afficher des dialogues de confirmation** (sauf si le serveur est approuvé) -3. **Exécuter les tools** avec les paramètres appropriés +3. **Exécuter les outils** avec les paramètres appropriés 4. **Afficher les résultats** dans un format convivial -## Surveillance du Statut et Dépannage +## Surveillance du statut et dépannage -### États de Connexion +### États de connexion L'intégration MCP suit plusieurs états : -#### Statut du Serveur (`MCPServerStatus`) +#### Statut du serveur (`MCPServerStatus`) - **`DISCONNECTED` :** Le serveur n'est pas connecté ou rencontre des erreurs - **`CONNECTING` :** Tentative de connexion en cours - **`CONNECTED` :** Le serveur est connecté et prêt -#### État de Découverte (`MCPDiscoveryState`) +#### État de découverte (`MCPDiscoveryState`) - **`NOT_STARTED` :** La découverte n'a pas encore commencé - **`IN_PROGRESS` :** Découverte des serveurs en cours - **`COMPLETED` :** Découverte terminée (avec ou sans erreurs) -### Problèmes Courants et Solutions +### Problèmes courants et solutions #### Le serveur ne se connecte pas @@ -506,7 +506,7 @@ L'intégration MCP suit plusieurs états : **Dépannage :** 1. **Vérifier la configuration :** Assurez-vous que `command`, `args`, et `cwd` sont corrects -2. **Tester manuellement :** Exécutez la commande du serveur directement pour vérifier qu'elle fonctionne +2. **Tester manuellement :** Exécutez directement la commande du serveur pour vérifier qu'elle fonctionne 3. **Vérifier les dépendances :** Assurez-vous que tous les packages requis sont installés 4. **Consulter les logs :** Recherchez les messages d'erreur dans la sortie CLI 5. **Vérifier les permissions :** Assurez-vous que le CLI peut exécuter la commande du serveur @@ -517,7 +517,7 @@ L'intégration MCP suit plusieurs états : **Dépannage :** -1. **Vérifier l'enregistrement des outils :** Assurez-vous que votre serveur enregistre effectivement des outils +1. **Vérifier l'enregistrement des outils :** Assurez-vous que votre serveur enregistre réellement des outils 2. **Vérifier le protocole MCP :** Confirmez que votre serveur implémente correctement le listing des outils MCP 3. **Consulter les logs du serveur :** Vérifiez la sortie stderr pour détecter les erreurs côté serveur 4. **Tester le listing des outils :** Testez manuellement le endpoint de découverte d'outils de votre serveur @@ -535,7 +535,7 @@ L'intégration MCP suit plusieurs états : #### Compatibilité du sandbox -**Symptômes :** Les serveurs MCP échouent lorsque le sandboxing est activé +**Symptômes :** Les serveurs MCP échouent quand le sandboxing est activé **Solutions :** @@ -547,8 +547,8 @@ L'intégration MCP suit plusieurs états : ### Conseils de débogage 1. **Activer le mode debug :** Exécutez le CLI avec `--debug` pour obtenir une sortie verbeuse -2. **Vérifier stderr :** Les erreurs du serveur MCP sont capturées et journalisées (les messages INFO sont filtrés) -3. **Tester de manière isolée :** Testez votre serveur MCP indépendamment avant l'intégration +2. **Vérifier stderr :** Les messages stderr du serveur MCP sont capturés et enregistrés (les messages INFO sont filtrés) +3. **Test isolé :** Testez votre serveur MCP indépendamment avant de l'intégrer 4. **Configuration progressive :** Commencez par des outils simples avant d'ajouter des fonctionnalités complexes 5. **Utiliser `/mcp` fréquemment :** Surveillez l'état du serveur pendant le développement @@ -557,28 +557,28 @@ L'intégration MCP suit plusieurs états : ### Considérations de sécurité - **Paramètres de confiance :** L'option `trust` contourne toutes les boîtes de dialogue de confirmation. À utiliser avec prudence et uniquement pour les serveurs que vous contrôlez entièrement -- **Jetons d'accès :** Soyez vigilant sur la sécurité lors de la configuration des variables d'environnement contenant des clés API ou des jetons -- **Compatibilité sandbox :** Lors de l'utilisation du sandboxing, assurez-vous que les serveurs MCP sont accessibles depuis l'environnement sandbox -- **Données privées :** L'utilisation de jetons d'accès personnels à portée large peut entraîner une fuite d'informations entre les repositories +- **Tokens d'accès :** Soyez vigilant sur la sécurité lors de la configuration des variables d'environnement contenant des API keys ou des tokens +- **Compatibilité sandbox :** Lors de l'utilisation du sandboxing, assurez-vous que les serveurs MCP sont disponibles dans l'environnement sandbox +- **Données privées :** L'utilisation de tokens d'accès personnels à portée large peut entraîner une fuite d'informations entre les repositories ### Performance et Gestion des Ressources - **Persistance des connexions :** Le CLI maintient des connexions persistantes vers les serveurs qui enregistrent avec succès des outils - **Nettoyage automatique :** Les connexions vers les serveurs ne fournissant aucun outil sont automatiquement fermées - **Gestion des timeouts :** Configurez des timeouts appropriés en fonction des caractéristiques de réponse de votre serveur -- **Monitoring des ressources :** Les serveurs MCP s'exécutent en tant que processus séparés et consomment des ressources système +- **Surveillance des ressources :** Les serveurs MCP s'exécutent en tant que processus séparés et consomment des ressources système ### Compatibilité des Schémas -- **Suppression de propriétés :** Le système supprime automatiquement certaines propriétés de schéma (`$schema`, `additionalProperties`) pour assurer la compatibilité avec l'API Gemini -- **Nettoyage des noms :** Les noms d'outils sont automatiquement nettoyés pour respecter les exigences de l'API -- **Résolution des conflits :** Les conflits de noms d'outils entre serveurs sont résolus par préfixage automatique +- **Suppression de propriétés :** Le système supprime automatiquement certaines propriétés de schéma (`$schema`, `additionalProperties`) pour assurer la compatibilité avec l'API Qwen +- **Nettoyage des noms :** Les noms des outils sont automatiquement nettoyés pour satisfaire aux exigences de l'API +- **Résolution des conflits :** Les conflits de noms d'outils entre serveurs sont résolus par un préfixage automatique Cette intégration complète fait des serveurs MCP un moyen puissant d'étendre les capacités du CLI tout en maintenant la sécurité, la fiabilité et la facilité d'utilisation. ## Retourner du contenu riche depuis les outils -Les outils MCP ne se limitent pas à renvoyer du texte simple. Vous pouvez retourner du contenu riche et multi-parties, incluant du texte, des images, de l'audio et d'autres données binaires dans une seule réponse d'outil. Cela vous permet de créer des outils puissants capables de fournir des informations diverses au modèle en un seul tour. +Les outils MCP ne se limitent pas à retourner du texte simple. Vous pouvez renvoyer du contenu riche et multi-parties, incluant du texte, des images, de l'audio et d'autres données binaires dans une seule réponse d'outil. Cela vous permet de créer des outils puissants capables de fournir des informations diverses au modèle en un seul tour. Toutes les données retournées par l'outil sont traitées et envoyées au modèle comme contexte pour sa prochaine génération, lui permettant de raisonner ou de résumer les informations fournies. @@ -596,7 +596,7 @@ Vous pouvez combiner différents types de blocs de contenu dans le tableau `cont ### Exemple : Retourner du texte et une image -Voici un exemple de réponse JSON valide d'un outil MCP qui retourne à la fois une description textuelle et une image : +Voici un exemple de réponse JSON valide depuis un outil MCP qui retourne à la fois une description textuelle et une image : ```json { @@ -621,12 +621,12 @@ Voici un exemple de réponse JSON valide d'un outil MCP qui retourne à la fois Lorsque Qwen Code reçoit cette réponse, il va : 1. Extraire tout le texte et le combiner en une seule partie `functionResponse` pour le modèle. -2. Présenter les données de l'image comme une partie `inlineData` distincte. -3. Fournir un résumé clair et convivial dans le CLI, indiquant que du texte et une image ont été reçus. +2. Présenter les données de l’image comme une partie `inlineData` distincte. +3. Fournir un résumé clair et convivial dans le CLI, indiquant qu’un texte et une image ont été reçus. -Cela vous permet de créer des outils sophistiqués capables de fournir un contexte riche et multi-modale au modèle Gemini. +Cela vous permet de créer des outils sophistiqués capables de fournir un contexte riche et multi-modale au modèle Qwen. -## Prompts MCP en tant que commandes slash +## Prompts MCP en tant que commandes Slash En plus des outils, les serveurs MCP peuvent exposer des prompts prédéfinis qui peuvent être exécutés en tant que commandes slash dans Qwen Code. Cela vous permet de créer des raccourcis pour des requêtes courantes ou complexes qui peuvent être facilement invoquées par leur nom. @@ -668,7 +668,7 @@ const transport = new StdioServerTransport(); await server.connect(transport); ``` -Cela peut être inclus dans `settings.json` sous `mcpServers` avec : +Ceci peut être inclus dans `settings.json` sous `mcpServers` avec : ```json "nodeServer": { @@ -695,7 +695,7 @@ Lorsque vous exécutez cette commande, le CLI exécute la méthode `prompts/get` ## Gérer les serveurs MCP avec `qwen mcp` -Bien que vous puissiez toujours configurer les serveurs MCP en modifiant manuellement votre fichier `settings.json`, la CLI fournit un ensemble pratique de commandes pour gérer vos configurations de serveur de manière programmatique. Ces commandes simplifient le processus d'ajout, de listage et de suppression de serveurs MCP sans avoir besoin de modifier directement les fichiers JSON. +Même si vous pouvez toujours configurer les serveurs MCP en modifiant manuellement votre fichier `settings.json`, la CLI fournit un ensemble pratique de commandes pour gérer vos configurations de serveur de manière programmatique. Ces commandes simplifient le processus d'ajout, de listage et de suppression de serveurs MCP sans avoir besoin de modifier directement les fichiers JSON. ### Ajouter un serveur (`qwen mcp add`) @@ -720,12 +720,12 @@ qwen mcp add [options] [args...] - `--timeout` : Définir le délai d'attente de connexion en millisecondes. - `--trust` : Faire confiance au serveur (contourne toutes les demandes de confirmation d'appel d'outils). - `--description` : Définir la description du serveur. -- `--include-tools` : Une liste d'outils à inclure, séparés par des virgules. -- `--exclude-tools` : Une liste d'outils à exclure, séparés par des virgules. +- `--include-tools` : Liste des outils à inclure, séparés par des virgules. +- `--exclude-tools` : Liste des outils à exclure, séparés par des virgules. #### Ajouter un serveur stdio -Il s'agit du transport par défaut pour exécuter des serveurs locaux. +C'est le transport par défaut pour exécuter des serveurs locaux. ```bash @@ -775,7 +775,7 @@ qwen mcp add --transport sse secure-sse https://api.example.com/sse/ --header "A ### Lister les serveurs (`qwen mcp list`) -Pour afficher tous les serveurs MCP actuellement configurés, utilisez la commande `list`. Elle affiche le nom de chaque serveur, ses détails de configuration ainsi que son statut de connexion. +Pour afficher tous les serveurs MCP actuellement configurés, utilise la commande `list`. Elle affiche le nom de chaque serveur, ses détails de configuration, ainsi que son statut de connexion. **Commande :** @@ -791,7 +791,7 @@ qwen mcp list ✗ sse-server: https://api.example.com/sse (sse) - Disconnected ``` -### Suppression d'un serveur (`qwen mcp remove`) +### Supprimer un serveur (`qwen mcp remove`) Pour supprimer un serveur de votre configuration, utilisez la commande `remove` avec le nom du serveur. diff --git a/website/content/fr/tools/memory.md b/website/content/fr/tools/memory.md index 5f6526cf..7f973277 100644 --- a/website/content/fr/tools/memory.md +++ b/website/content/fr/tools/memory.md @@ -16,7 +16,7 @@ Utilisez `save_memory` pour sauvegarder et rappeler des informations entre vos s L'outil ajoute le `fact` fourni à votre fichier de contexte situé dans le répertoire utilisateur (`~/.qwen/QWEN.md` par défaut). Ce nom de fichier peut être configuré via `contextFileName`. -Une fois ajoutés, les faits sont stockés sous une section `## Qwen Added Memories`. Ce fichier est chargé comme contexte lors des sessions suivantes, permettant au CLI de rappeler les informations sauvegardées. +Une fois ajoutés, les faits sont stockés sous une section intitulée `## Qwen Added Memories`. Ce fichier est chargé comme contexte lors des sessions suivantes, permettant au CLI de se rappeler les informations sauvegardées. Utilisation : @@ -24,18 +24,18 @@ Utilisation : save_memory(fact="Votre fait ici.") ``` -### Exemples `save_memory` +### Exemples avec `save_memory` Mémoriser une préférence utilisateur : ``` -save_memory(fact="My preferred programming language is Python.") +save_memory(fact="Mon langage de programmation préféré est Python.") ``` Stocker un détail spécifique à un projet : ``` -save_memory(fact="The project I'm currently working on is called 'gemini-cli'.") +save_memory(fact="Le projet sur lequel je travaille actuellement s'appelle 'qwen-code'.") ``` ## Notes importantes diff --git a/website/content/fr/tools/web-fetch.md b/website/content/fr/tools/web-fetch.md index c56eb78a..ecaf31e3 100644 --- a/website/content/fr/tools/web-fetch.md +++ b/website/content/fr/tools/web-fetch.md @@ -15,9 +15,9 @@ Utilisez `web_fetch` pour récupérer le contenu d'une URL spécifiée et le tra ## Comment utiliser `web_fetch` avec Qwen Code -Pour utiliser `web_fetch` avec Qwen Code, fournissez une URL et un prompt décrivant ce que vous souhaitez extraire de cette URL. L'outil demandera une confirmation avant de récupérer l'URL. Une fois confirmé, l'outil récupérera le contenu directement et le traitera en utilisant un modèle AI. +Pour utiliser `web_fetch` avec Qwen Code, fournissez une URL et un prompt décrivant ce que vous souhaitez extraire de cette URL. L'outil demandera une confirmation avant de récupérer le contenu. Une fois confirmé, l'outil récupérera le contenu directement et le traitera en utilisant un modèle AI. -L'outil convertit automatiquement le HTML en texte, gère les URLs GitHub blob (en les convertissant en URLs brutes), et met à niveau les URLs HTTP en HTTPS pour des raisons de sécurité. +L'outil convertit automatiquement le HTML en texte, gère les URLs GitHub blob (en les convertissant en URLs raw), et met à niveau les URLs HTTP en HTTPS pour des raisons de sécurité. Utilisation : @@ -42,13 +42,13 @@ web_fetch(url="https://arxiv.org/abs/2401.0001", prompt="Quels sont les résulta Analyser la documentation GitHub : ``` -web_fetch(url="https://github.com/google/gemini-react/blob/main/README.md", prompt="Quelles sont les étapes d'installation et les principales fonctionnalités ?") +web_fetch(url="https://github.com/QwenLM/Qwen/blob/main/README.md", prompt="Quelles sont les étapes d'installation et les principales fonctionnalités ?") ``` ## Notes importantes -- **Traitement d'une seule URL :** `web_fetch` traite une URL à la fois. Pour analyser plusieurs URLs, effectuez des appels séparés à l'outil. +- **Traitement d'URL unique :** `web_fetch` traite une seule URL à la fois. Pour analyser plusieurs URLs, effectuez des appels séparés à l'outil. - **Format d'URL :** L'outil met automatiquement à niveau les URLs HTTP vers HTTPS et convertit les URLs GitHub blob au format raw pour un meilleur accès au contenu. -- **Traitement du contenu :** L'outil récupère le contenu directement et le traite en utilisant un modèle AI, convertissant le HTML en texte lisible. +- **Traitement du contenu :** L'outil récupère le contenu directement et le traite en utilisant un modèle AI, convertissant le HTML en format texte lisible. - **Qualité de la sortie :** La qualité de la sortie dépendra de la clarté des instructions dans le prompt. -- **Outils MCP :** Si un outil web fetch fourni par MCP est disponible (commençant par "mcp\_\_"), préférez utiliser cet outil car il peut avoir moins de restrictions. \ No newline at end of file +- **Outils MCP :** Si un outil web fetch fourni par MCP est disponible (commençant par "mcp__"), préférez utiliser cet outil car il peut avoir moins de restrictions. \ No newline at end of file diff --git a/website/content/fr/troubleshooting.md b/website/content/fr/troubleshooting.md index 74ad14f4..f57266c6 100644 --- a/website/content/fr/troubleshooting.md +++ b/website/content/fr/troubleshooting.md @@ -3,26 +3,21 @@ 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 (FAQs) +- Foire aux questions (FAQ) - Conseils de débogage -- Issues GitHub existantes similaires à la vôtre ou création de nouvelles Issues +- Issues GitHub existants similaires au 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 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` + - **Cause :** Vous êtes peut-être sur un réseau d'entreprise avec un pare-feu qui intercepte et inspecte le trafic SSL/TLS. Cela nécessite souvent qu'un certificat d'autorité de certification (CA) personnalisé soit approuvé par Node.js. + - **Solution :** Définissez la variable d'environnement `NODE_EXTRA_CA_CERTS` avec le chemin absolu vers le fichier de certificat de votre CA racine d'entreprise. + - Exemple : `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` ## 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 dernières modifications du 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 derniers changements depuis le 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,36 +27,36 @@ 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 (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`. + - R : Les informations sur les tokens en cache ne s'affichent que lorsque des tokens mis en cache sont utilisés. Cette fonctionnalité est disponible pour les utilisateurs avec une clé API (Qwen API key ou Google Cloud Vertex AI), mais pas pour les utilisateurs OAuth (comme les comptes Google personnels ou professionnels, par exemple Google Gmail ou Google Workspace). Cela est dû au fait que l'API Qwen Code Assist ne prend pas en charge la création de contenu mis en cache. Vous pouvez néanmoins consulter votre consommation totale de tokens à l’aide de la commande `/stats`. ## Messages d'erreur courants et solutions - **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 utilisant le port ou configurez le serveur MCP pour utiliser un port différent. + Arrêtez l'autre processus utilisant ce 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 installé correctement ou il n'est pas dans le `PATH` de votre système. +- **Erreur : Command not found (lorsque vous tentez d'exécuter Qwen Code avec `qwen`).** + - **Cause :** Le CLI n'est pas correctement installé ou il n'est pas dans le `PATH` de votre système. - **Solution :** La mise à jour dépend de la façon dont vous avez installé Qwen Code : - Si vous avez installé `qwen` globalement, vérifiez que le répertoire des binaires globaux de `npm` est dans votre `PATH`. Vous pouvez mettre à jour avec la commande `npm install -g @qwen-code/qwen-code@latest`. - Si vous 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 installées correctement, ou le projet n'a pas été construit. + - **Cause :** Les dépendances ne sont pas installées correctement, ou le projet n'a pas été compilé. - **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 construction s'est terminée avec succès avec `npm run start`. + 3. Vérifiez que la compilation 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. - **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. + - **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 préfixée par `CI_`. Si l'une d'elles est trouvée, cela indique un environnement non interactif, empêchant 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** @@ -82,12 +77,12 @@ Ce guide fournit des solutions aux problèmes courants et des conseils de débog - **Débogage CLI :** - Utilisez le flag `--verbose` (si disponible) avec les commandes CLI pour obtenir une sortie plus détaillée. - - Consultez les logs du CLI, souvent situés dans un répertoire de configuration ou de cache spécifique à l'utilisateur. + - Consultez les logs 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. diff --git a/website/content/ja/Uninstall.md b/website/content/ja/Uninstall.md index 712465b4..74087b03 100644 --- a/website/content/ja/Uninstall.md +++ b/website/content/ja/Uninstall.md @@ -1,14 +1,14 @@ -# CLI のアンインストール +# CLIのアンインストール -CLI の実行方法によってアンインストール方法が異なります。npx を使用した場合と、グローバル npm インストールの場合のいずれかに該当する手順に従ってください。 +CLIの実行方法によってアンインストール方法が異なります。npxを使用した場合と、グローバルなnpmインストールの場合のいずれかに応じて、以下の手順に従ってください。 -## 方法 1: npx を使用する場合 +## 方法1: npxを使用する場合 -npx は永続的なインストールなしに、一時的なキャッシュからパッケージを実行します。CLI を「アンインストール」するには、このキャッシュをクリアする必要があります。これにより、gemini-cli および以前に npx で実行した他のパッケージも削除されます。 +npxは、永続的なインストールなしに一時的なキャッシュからパッケージを実行します。CLIを「アンインストール」するには、このキャッシュをクリアする必要があります。これにより、qwen-codeおよび以前にnpxで実行した他のパッケージも削除されます。 -npx のキャッシュは、メインの npm キャッシュフォルダ内の `_npx` という名前のディレクトリです。npm キャッシュのパスは、`npm config get cache` を実行することで確認できます。 +npxのキャッシュは、メインのnpmキャッシュフォルダ内の`_npx`という名前のディレクトリです。`npm config get cache`を実行することで、npmキャッシュのパスを確認できます。 -**macOS / Linux 向け** +**macOS / Linuxの場合** ```bash @@ -16,7 +16,7 @@ npx のキャッシュは、メインの npm キャッシュフォルダ内の ` rm -rf "$(npm config get cache)/_npx" ``` -**Windows 向け** +**Windowsの場合** _Command Prompt_ diff --git a/website/content/ja/checkpointing.md b/website/content/ja/checkpointing.md index 31d49ad5..69062aab 100644 --- a/website/content/ja/checkpointing.md +++ b/website/content/ja/checkpointing.md @@ -1,18 +1,18 @@ # Checkpointing -Qwen Code には Checkpointing 機能が含まれており、AI を搭載したツールによるファイル変更が行われる前に、プロジェクトの状態のスナップショットを自動的に保存します。これにより、ツールを実行する前の状態に即座に戻ることができることを理解した上で、コード変更を安全に試したり適用したりできます。 +Qwen Code には Checkpointing 機能が含まれており、AI を搭載したツールによるファイル変更が行われる前に、プロジェクトの状態のスナップショットを自動的に保存します。これにより、ツール実行前の状態に即座に戻ることができることを理解した上で、コード変更を安全に試すことができ、適用することもできます。 ## 仕組み -ファイルシステムを変更するツール（`write_file` や `replace` など）を承認すると、CLI は自動的に「チェックポイント」を作成します。このチェックポイントには以下が含まれます： +ファイルシステムを変更するツール（`write_file` や `edit` など）を承認すると、CLI は自動的に「チェックポイント」を作成します。このチェックポイントには以下が含まれます： -1. **Git スナップショット：** ホームディレクトリ（`~/.qwen/history/`）にある特別な影の Git リポジトリにコミットが作成されます。このスナップショットは、その時点でのプロジェクトファイルの完全な状態をキャプチャします。これは、あなたのプロジェクト自身の Git リポジトリには**一切干渉しません**。 -2. **会話履歴：** その時点までエージェントとやり取りしたすべての会話が保存されます。 -3. **ツール呼び出し：** 実行されようとしていた特定のツール呼び出しも保存されます。 +1. **Git スナップショット:** ホームディレクトリ（`~/.qwen/history/`）にある特別な影の Git リポジトリにコミットが作成されます。このスナップショットは、その時点でのプロジェクトファイルの完全な状態をキャプチャします。これはあなたのプロジェクトの Git リポジトリには**一切干渉しません**。 +2. **会話履歴:** その時点までエージェントとやり取りしたすべての会話が保存されます。 +3. **ツール呼び出し:** 実行されようとしていた特定のツール呼び出しも保存されます。 -変更を元に戻したい、あるいは単に以前の状態に戻りたい場合は、`/restore` コマンドを使用できます。チェックポイントをリストアすると以下の処理が行われます： +変更を元に戻したい、あるいは単に前の状態に戻りたい場合は、`/restore` コマンドを使用できます。チェックポイントをリストアすると以下の処理が行われます： -- プロジェクト内のすべてのファイルを、スナップショットでキャプチャされた状態に戻します。 +- プロジェクト内のすべてのファイルをスナップショットでキャプチャされた状態に戻します。 - CLI 内の会話履歴を復元します。 - 元のツール呼び出しを再度提案し、再度実行したり、変更したり、単に無視したりできるようにします。 @@ -20,7 +20,7 @@ Git スナップショットと会話履歴を含むすべてのチェックポ ## 機能の有効化 -Checkpointing 機能はデフォルトでは無効になっています。有効にするには、コマンドラインフラグを使用するか、`settings.json` ファイルを編集します。 +Checkpointing 機能はデフォルトで無効になっています。有効にするには、コマンドラインフラグを使用するか、`settings.json` ファイルを編集します。 ### コマンドラインフラグを使用する @@ -50,17 +50,17 @@ qwen --checkpointing ### 利用可能なチェックポイントの一覧表示 -現在のプロジェクトで保存されているすべてのチェックポイントを確認するには、以下のコマンドを実行してください： +現在のプロジェクトで保存されているすべてのチェックポイントを確認するには、以下を実行してください： ``` /restore ``` -CLI は利用可能なチェックポイントファイルの一覧を表示します。これらのファイル名は通常、タイムスタンプ、変更されたファイルの名前、実行予定のツール名（例：`2025-06-22T10-00-00_000Z-my-file.txt-write_file`）から構成されています。 +CLI は利用可能なチェックポイントファイルの一覧を表示します。これらのファイル名は通常、タイムスタンプ、変更されたファイルの名前、実行予定だったツールの名前から構成されます（例: `2025-06-22T10-00-00_000Z-my-file.txt-write_file`）。 -### 特定のチェックポイントへの復元 +### 特定のチェックポイントを復元する -プロジェクトを特定のチェックポイントに戻すには、一覧から該当するチェックポイントファイルを使用します： +プロジェクトを特定のチェックポイントに戻すには、一覧から該当するチェックポイントファイルを指定して以下を実行します： ``` /restore diff --git a/website/content/ja/cli/commands.md b/website/content/ja/cli/commands.md index 7a42cf2d..27eb12a0 100644 --- a/website/content/ja/cli/commands.md +++ b/website/content/ja/cli/commands.md @@ -6,10 +6,11 @@ Qwen Code では、セッションの管理、インターフェースのカス スラッシュコマンドは、CLI 自体に対するメタレベルの制御を提供します。 +```markdown ### 組み込みコマンド - **`/bug`** - - **説明:** Qwen Codeに関するissueを提出します。デフォルトでは、GitHubのQwen Codeリポジトリ内にissueが作成されます。`/bug`の後に続く文字列は、提出されるバグのタイトルになります。デフォルトの`/bug`の動作は、`.qwen/settings.json`ファイル内の`bugCommand`設定で変更できます。 + - **説明:** Qwen Codeに関するissueを提出します。デフォルトでは、GitHubのQwen Codeリポジトリ内にissueが作成されます。`/bug`の後に記述した文字列が、提出されるバグのタイトルになります。`.qwen/settings.json`ファイル内の`bugCommand`設定により、デフォルトの`/bug`の動作を変更できます。 - **`/chat`** - **説明:** 対話的に会話履歴を保存・再開し、分岐した会話状態を管理したり、以前のセッションから状態を再開できます。 @@ -17,26 +18,37 @@ Qwen Code では、セッションの管理、インターフェースのカス - **`save`** - **説明:** 現在の会話履歴を保存します。会話状態を識別するために``を指定する必要があります。 - **使用方法:** `/chat save ` - - **チェックポイントの保存場所:** 保存されたチャットチェックポイントのデフォルトの場所は以下の通りです： - - Linux/macOS: `~/.config/google-generative-ai/checkpoints/` - - Windows: `C:\Users\\AppData\Roaming\google-generative-ai\checkpoints\` + - **チェックポイント保存場所の詳細:** 保存されたチャットチェックポイントのデフォルト保存場所は以下の通りです： + - Linux/macOS: `~/.config/qwen-code/checkpoints/` + - Windows: `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` - `/chat list`を実行すると、CLIはこれらのディレクトリのみをスキャンして利用可能なチェックポイントを検索します。 - - **注意:** これらのチェックポイントは、手動で会話状態を保存・再開するためのものです。ファイル変更前に自動的に作成されるチェックポイントについては、[チェックポイントに関するドキュメント](../checkpointing.md)を参照してください。 + - **注意:** これらのチェックポイントは、手動で会話状態を保存・再開するためのものです。ファイル変更前に自動作成されるチェックポイントについては、[Checkpointing documentation](../checkpointing.md)を参照してください。 - **`resume`** - - **説明:** 以前に保存した会話を再開します。 + - **説明:** 以前に保存した会話状態を再開します。 - **使用方法:** `/chat resume ` - **`list`** - - **説明:** 再開可能なチャット状態のタグを一覧表示します。 + - **説明:** 再開可能なチャット状態のタグ一覧を表示します。 - **`delete`** - **説明:** 保存された会話チェックポイントを削除します。 - **使用方法:** `/chat delete ` - **`/clear`** - - **説明:** CLI内の表示履歴とスクロールバックを含む、ターミナル画面全体をクリアします。実装によっては、履歴の呼び出し用にセッションデータが保持される場合がありますが、視覚的な表示はクリアされます。 - - **キーボードショートカット:** **Ctrl+L**を押すと、いつでもクリア操作を実行できます。 + - **説明:** CLI内の表示履歴とスクロールバックを含む、ターミナル画面全体をクリアします。実装によっては履歴データ自体は保持される場合がありますが、画面上の表示はクリアされます。 + - **キーボードショートカット:** いつでも**Ctrl+L**を押すことで画面をクリアできます。 + +- **`/summary`** + - **説明:** 現在の会話履歴から包括的なプロジェクトサマリーを生成し、`.qwen/PROJECT_SUMMARY.md`に保存します。このサマリーには全体の目標、重要な知識、最近のアクション、現在の計画が含まれており、将来のセッションで作業を再開するのに最適です。 + - **使用方法:** `/summary` + - **機能:** + - 全会話履歴を解析して重要なコンテキストを抽出 + - 目標、知識、アクション、計画のセクションを持つ構造化されたMarkdownサマリーを作成 + - プロジェクトルートの`.qwen/PROJECT_SUMMARY.md`に自動保存 + - 生成・保存中に進行状況を表示 + - セッション再開機能と統合してシームレスな再開を実現 + - **注意:** このコマンドを使用するには、最低でも2件のメッセージを含むアクティブな会話が必要です。 - **`/compress`** - - **説明:** チャットの全コンテキストを要約に置き換えます。これにより、将来のタスクで使用されるトークンを節約しつつ、これまでの会話内容の概要を保持できます。 + - **説明:** チャットコンテキスト全体をサマリーに置き換えます。これにより、将来のタスクで使用するトークン数を削減しつつ、これまでの内容の高レベルなサマリーを保持できます。 - **`/copy`** - **説明:** Qwen Codeが最後に出力した内容をクリップボードにコピーし、共有や再利用を容易にします。 @@ -45,9 +57,9 @@ Qwen Code では、セッションの管理、インターフェースのカス - **説明:** 複数ディレクトリ対応のワークスペースディレクトリを管理します。 - **サブコマンド:** - **`add`**: - - **説明:** ワークスペースにディレクトリを追加します。パスは絶対パスでも、現在の作業ディレクトリからの相対パスでも指定できます。また、ホームディレクトリからの相対パスもサポートされています。 + - **説明:** ワークスペースにディレクトリを追加します。パスは絶対パスまたは現在の作業ディレクトリからの相対パスを指定できます。また、ホームディレクトリからの参照もサポートされています。 - **使用方法:** `/directory add ,` - - **注意:** 制限付きサンドボックスプロファイルでは無効です。その場合、セッション開始時に`--include-directories`オプションを使用してください。 + - **注意:** 制限付きサンドボックスプロファイルでは無効です。その場合、セッション開始時に`--include-directories`を使用してください。 - **`show`**: - **説明:** `/directory add`および`--include-directories`で追加されたすべてのディレクトリを表示します。 - **使用方法:** `/directory show` @@ -56,24 +68,24 @@ Qwen Code では、セッションの管理、インターフェースのカス - **説明:** 複数ディレクトリ対応のワークスペースディレクトリを管理します。 - **サブコマンド:** - **`add`**: - - **説明:** ワークスペースにディレクトリを追加します。パスは絶対パスでも、現在の作業ディレクトリからの相対パスでも指定できます。また、ホームディレクトリからの相対パスもサポートされています。 + - **説明:** ワークスペースにディレクトリを追加します。パスは絶対パスまたは現在の作業ディレクトリからの相対パスを指定できます。また、ホームディレクトリからの参照もサポートされています。 - **使用方法:** `/directory add ,` - - **注意:** 制限付きサンドボックスプロファイルでは無効です。その場合、セッション開始時に`--include-directories`オプションを使用してください。 + - **注意:** 制限付きサンドボックスプロファイルでは無効です。その場合、セッション開始時に`--include-directories`を使用してください。 - **`show`**: - **説明:** `/directory add`および`--include-directories`で追加されたすべてのディレクトリを表示します。 - **使用方法:** `/directory show` - **`/editor`** - - **説明:** サポートされているエディタを選択するダイアログを開きます。 + - **説明:** サポートされているエディタを選択するためのダイアログを開きます。 - **`/extensions`** - **説明:** 現在のQwen Codeセッションでアクティブなすべての拡張機能を一覧表示します。詳細は[Qwen Code Extensions](../extension.md)を参照してください。 - **`/help`** (または **`/?`**) - - **説明:** 利用可能なコマンドとその使用方法を含む、Qwen Codeに関するヘルプ情報を表示します。 + - **説明:** Qwen Codeで利用可能なコマンドとその使用方法を含むヘルプ情報を表示します。 - **`/mcp`** - - **説明:** 設定されたModel Context Protocol (MCP)サーバー、その接続状態、サーバーの詳細、および利用可能なツールを一覧表示します。 + - **説明:** 設定されたModel Context Protocol (MCP)サーバー、接続状況、サーバー詳細、利用可能なツールを一覧表示します。 - **サブコマンド:** - **`desc`** または **`descriptions`**: - **説明:** MCPサーバーとツールの詳細な説明を表示します。 @@ -81,7 +93,7 @@ Qwen Code では、セッションの管理、インターフェースのカス - **説明:** ツールの説明を非表示にし、ツール名のみを表示します。 - **`schema`**: - **説明:** ツールの設定パラメータの完全なJSONスキーマを表示します。 - - **キーボードショートカット:** **Ctrl+T**を押すと、ツールの説明の表示/非表示を切り替えることができます。 + - **キーボードショートカット:** いつでも**Ctrl+T**を押すことで、ツールの説明表示/非表示を切り替えられます。 - **`/memory`** - **説明:** AIの指示コンテキスト（デフォルトでは`QWEN.md`ファイルから読み込まれる階層メモリ；`contextFileName`で設定可能）を管理します。 @@ -91,33 +103,47 @@ Qwen Code では、セッションの管理、インターフェースのカス - **`show`**: - **説明:** すべてのコンテキストファイル（例：`QWEN.md`）から読み込まれた現在の階層メモリの完全な内容を表示します。これにより、モデルに提供されている指示コンテキストを確認できます。 - **`refresh`**: - - **説明:** 設定された場所（グローバル、プロジェクト/祖先、およびサブディレクトリ）にあるすべてのコンテキストファイル（デフォルト：`QWEN.md`）から階層的な指示メモリを再読み込みします。これにより、モデルに最新のコンテキスト内容が反映されます。 + - **説明:** 設定された場所（グローバル、プロジェクト/祖先、サブディレクトリ）にあるすべてのコンテキストファイル（デフォルト：`QWEN.md`）から階層指示メモリを再読み込みします。これにより、モデルに最新のコンテキスト内容が反映されます。 - **注意:** コンテキストファイルが階層メモリにどのように寄与するかの詳細については、[CLI Configuration documentation](./configuration.md#context-files-hierarchical-instructional-context)を参照してください。 - **`/restore`** - - **説明:** ツールが実行される直前のプロジェクトファイルの状態に復元します。これは、ツールによって行われたファイル編集を元に戻すのに特に便利です。ツール呼び出しIDなしで実行された場合、復元可能なチェックポイントの一覧が表示されます。 + - **説明:** ツールが実行される直前のプロジェクトファイルの状態に復元します。これは、ツールによって行われたファイル編集を元に戻すのに特に便利です。ツール呼び出しIDなしで実行した場合、復元可能なチェックポイントの一覧が表示されます。 - **使用方法:** `/restore [tool_call_id]` - **注意:** CLIが`--checkpointing`オプションで起動された場合、または[settings](./configuration.md)で設定されている場合にのみ使用可能です。詳細は[Checkpointing documentation](../checkpointing.md)を参照してください。 - **`/settings`** - **説明:** Qwen Codeの設定を表示・変更するための設定エディタを開きます。 - - **詳細:** このコマンドは、Qwen Codeの動作や外観を制御する設定を変更するためのユーザーフレンドリーなインターフェースを提供します。`.qwen/settings.json`ファイルを手動で編集するのと同等ですが、エラーを防ぐために検証とガイダンスが提供されます。 - - **使用方法:** 単に`/settings`を実行すると、エディタが開きます。そこから特定の設定を閲覧・検索し、現在の値を確認し、必要に応じて変更できます。一部の設定は即座に反映されますが、他の設定は再起動が必要です。 + - **詳細:** このコマンドは、Qwen Codeの動作と外観を制御する設定を変更するためのユーザーフレンドリーなインターフェースを提供します。`.qwen/settings.json`ファイルを手動で編集するのと同等ですが、エラーを防ぐための検証とガイダンスが含まれています。 + - **使用方法:** 単に`/settings`を実行するとエディタが開きます。そこから特定の設定を閲覧・検索し、現在の値を確認し、必要に応じて変更できます。一部の設定は即座に反映されますが、他の設定は再起動が必要です。 - **`/stats`** - - **説明:** 現在のQwen Codeセッションの詳細な統計情報を表示します。これには、トークン使用量、キャッシュされたトークンの節約量（利用可能な場合）、セッションの継続時間などが含まれます。注意：キャッシュされたトークン情報は、APIキー認証時にトークンが使用されている場合にのみ表示され、現在のところOAuth認証では表示されません。 + - **説明:** 現在のQwen Codeセッションの詳細な統計情報を表示します。これにはトークン使用量、キャッシュされたトークンの節約量（利用可能な場合）、セッション時間などが含まれます。注意：キャッシュされたトークン情報は、APIキー認証時にトークンが使用されている場合にのみ表示され、現在のところOAuth認証では表示されません。 - [**`/theme`**](./themes.md) - - **説明:** Qwen Codeの視覚的なテーマを変更できるダイアログを開きます。 + - **説明:** Qwen Codeの視覚テーマを変更するためのダイアログを開きます。 - **`/auth`** - - **説明:** 認証方法を変更できるダイアログを開きます。 + - **説明:** 認証方法を変更するためのダイアログを開きます。 - **`/about`** - - **説明:** バージョン情報を表示します。issueを提出する際は、この情報を共有してください。 + - **説明:** バージョン情報を表示します。issueを提出する際はこの情報を共有してください。 + +- **`/agents`** + - **説明:** 特定のタスクに特化したAIサブエージェントを管理します。サブエージェントは特定の専門知識とツールアクセスで構成された独立したAIアシスタントです。 + - **サブコマンド:** + - **`create`**: + - **説明:** 新しいサブエージェントを作成するためのインタラクティブウィザードを起動します。ウィザードでは場所選択、AIによるプロンプト生成、ツール選択、視覚的カスタマイズをガイドします。 + - **使用方法:** `/agents create` + - **`manage`**: + - **説明:** 既存のサブエージェントを表示・編集・削除するためのインタラクティブな管理ダイアログを開きます。プロジェクトレベルとユーザーレベルのエージェントの両方を表示します。 + - **使用方法:** `/agents manage` + - **保存場所:** + - **プロジェクトレベル:** `.qwen/agents/`（チームで共有、優先度高） + - **ユーザーレベル:** `~/.qwen/agents/`（個人用エージェント、プロジェクト間で利用可能） + - **注意:** サブエージェントの作成・管理の詳細については、[Subagents documentation](../subagents.md)を参照してください。 - [**`/tools`**](../tools/index.md) - - **説明:** 現在Qwen Code内で利用可能なツールの一覧を表示します。 + - **説明:** Qwen Code内で現在利用可能なツールの一覧を表示します。 - **サブコマンド:** - **`desc`** または **`descriptions`**: - **説明:** 各ツールの詳細な説明を表示します。これには、モデルに提供された各ツールの名前と完全な説明が含まれます。 @@ -125,24 +151,35 @@ Qwen Code では、セッションの管理、インターフェースのカス - **説明:** ツールの説明を非表示にし、ツール名のみを表示します。 - **`/privacy`** - - **説明:** プライバシー通知を表示し、ユーザーがサービス改善の目的でデータ収集に同意するかどうかを選択できるようにします。 + - **説明:** プライバシー通知を表示し、ユーザーがサービス改善のためのデータ収集に同意するかどうかを選択できるようにします。 + +- **`/quit-confirm`** + - **説明:** Qwen Codeを終了する前に確認ダイアログを表示し、現在のセッションをどのように処理するかを選択できるようにします。 + - **使用方法:** `/quit-confirm` + - **機能:** + - **即時終了:** 何も保存せずに終了（`/quit`と同等） + - **サマリー生成して終了:** 終了前に`/summary`を使用してプロジェクトサマリーを作成 + - **会話を保存して終了:** 自動生成されたタグで現在の会話を保存してから終了 + - **キーボードショートカット:** **Ctrl+C**を2回押すことで終了確認ダイアログを起動 + - **注意:** Ctrl+Cを1回押したときに自動的にこのコマンドが起動され、誤って終了することを防ぐ安全機構が提供されます。 - **`/quit`** (または **`/exit`**) - - **説明:** Qwen Codeを終了します。 + - **説明:** 確認ダイアログなしでQwen Codeを即座に終了します。 - **`/vim`** - **説明:** vimモードのオン/オフを切り替えます。vimモードが有効になると、入力エリアでNORMALモードとINSERTモードの両方でvimスタイルのナビゲーションと編集コマンドがサポートされます。 - **機能:** - - **NORMALモード:** `h`, `j`, `k`, `l`で移動；`w`, `b`, `e`で単語単位のジャンプ；`0`, `$`, `^`で行の先頭/末尾に移動；`G`（または`gg`で最初の行）で特定の行に移動 - - **INSERTモード:** 標準的なテキスト入力で、エスケープキーでNORMALモードに戻る + - **NORMALモード:** `h`, `j`, `k`, `l`で移動；`w`, `b`, `e`で単語単位移動；`0`, `$`, `^`で行頭/行末/非空白文字の行頭に移動；`G`（または`gg`で最初の行）で特定行に移動 + - **INSERTモード:** 標準的なテキスト入力で、エスケープでNORMALモードに戻る - **編集コマンド:** `x`で削除、`c`で変更、`i`, `a`, `o`, `O`で挿入；`dd`, `cc`, `dw`, `cw`などの複雑な操作 - **カウントサポート:** コマンドの前に数字を付ける（例：`3h`, `5w`, `10G`） - - **最後のコマンドの繰り返し:** `.`で最後の編集操作を繰り返す - - **永続設定:** vimモードの設定は`~/.qwen/settings.json`に保存され、セッション間で復元されます - - **ステータス表示:** 有効時、フッターに`[NORMAL]`または`[INSERT]`が表示されます + - **最後のコマンド繰り返し:** `.`で最後の編集操作を繰り返す + - **永続設定:** Vimモードの設定は`~/.qwen/settings.json`に保存され、セッション間で復元される + - **ステータス表示:** 有効時はフッターに`[NORMAL]`または`[INSERT]`を表示 - **`/init`** - - **説明:** 現在のディレクトリを分析し、デフォルトで`QWEN.md`コンテキストファイル（または`contextFileName`で指定されたファイル名）を作成します。空でないファイルが既に存在する場合は、変更は行われません。このコマンドは空のファイルを作成し、モデルにプロジェクト固有の指示を入力するよう促します。 + - **説明:** 現在のディレクトリを解析し、デフォルトでは`QWEN.md`コンテキストファイル（または`contextFileName`で指定されたファイル名）を作成します。空でないファイルが既に存在する場合は変更されません。このコマンドは空のファイルを作成し、モデルにプロジェクト固有の指示で埋めるようプロンプトを表示します。 +``` ### カスタムコマンド @@ -155,51 +192,80 @@ Qwen Code では、セッションの管理、インターフェースのカス Qwen Code は、以下の2つの場所からコマンドを読み込み、特定の順序でロードします： 1. **ユーザー コマンド (グローバル):** `~/.qwen/commands/` に配置されます。これらのコマンドは、作業中のすべてのプロジェクトで利用可能です。 -2. **プロジェクト コマンド (ローカル):** `/.qwen/commands/` に配置されます。これらのコマンドは現在のプロジェクト専用であり、バージョン管理に含めてチームと共有できます。 +2. **プロジェクト コマンド (ローカル):** `/.qwen/commands/` に配置されます。これらのコマンドは現在のプロジェクト専用であり、チームと共有するためにバージョン管理に含めることができます。 プロジェクトディレクトリ内のコマンドとユーザーディレクトリ内のコマンドで名前が同じ場合、**プロジェクト コマンドが常に使用されます。** これにより、プロジェクト固有のバージョンでグローバル コマンドを上書きできます。 -#### 命名と名前空間 +#### コマンド名と名前空間 -コマンドの名前は、そのファイルが存在する `commands` ディレクトリからの相対パスに基づいて決定されます。サブディレクトリを使用することで名前空間付きコマンドを作成でき、パス区切り文字（`/` または `\`）はコロン（`:`）に変換されます。 +コマンド名は、そのファイルが存在する `commands` ディレクトリからの相対パスに基づいて決定されます。サブディレクトリを使用することで名前空間付きコマンドを作成でき、パス区切り文字（`/` または `\`）はコロン（`:`）に変換されます。 - `~/.qwen/commands/test.toml` にあるファイルは、コマンド `/test` になります。 - `/.qwen/commands/git/commit.toml` にあるファイルは、名前空間付きコマンド `/git:commit` になります。 #### TOML ファイル形式 (v1) -コマンド定義ファイルは TOML 形式で記述し、拡張子は `.toml` を使用する必要があります。 +コマンド定義ファイルは TOML 形式で記述し、拡張子は `.toml` を使用してください。 ##### 必須フィールド -- `prompt` (String): コマンドが実行されたときにモデルに送信されるプロンプト。単一行または複数行の文字列を指定できます。 +- `prompt` (String): コマンド実行時にモデルに送信されるプロンプト。単一行または複数行の文字列を指定できます。 ##### オプションフィールド -- `description` (String): コマンドの機能を示す短い一行の説明。このテキストは `/help` メニューでコマンドの横に表示されます。**このフィールドを省略すると、ファイル名から汎用的な説明が自動生成されます。** +- `description` (String): コマンドの機能を説明する短い一行の説明文。このテキストは `/help` メニューでコマンドの横に表示されます。**このフィールドを省略した場合、ファイル名から汎用的な説明が自動生成されます。** #### 引数の処理 -カスタムコマンドでは、引数を処理するための2つの強力で使いやすい方法がサポートされています。CLIは、コマンドの`prompt`の内容に基づいて、自動的に適切な方法を選択します。 +カスタムコマンドでは、引数を処理するための2つの強力な方法がサポートされています。CLIは、コマンドの`prompt`の内容に基づいて、自動的に正しい方法を選択します。 -##### 1. `{{args}}`による簡易的な注入 +##### 1. `{{args}}`によるコンテキスト対応の注入 -`prompt`に特別なプレースホルダー`{{args}}`が含まれている場合、CLIはそのプレースホルダーを、ユーザーがコマンド名の後にタイプしたすべてのテキストに置き換えます。これは、大きなpromptテンプレートの特定の場所にユーザー入力を注入する必要がある、シンプルで決定的なコマンドに最適です。 +`prompt`に特殊なプレースホルダー`{{args}}`が含まれている場合、CLIはそのプレースホルダーをユーザーがコマンド名の後にタイプしたテキストに置き換えます。 -**例 (`git/fix.toml`):** +この注入の動作は、使用場所によって異なります： -```toml +**A. 生の注入（Shellコマンド外）** -# In: ~/.qwen/commands/git/fix.toml +プロンプトの本文で使用される場合、引数はユーザーがタイプした通りに正確に注入されます。 + +**例（`git/fix.toml`）：** + +```toml ```markdown -# 実行方法: /git:fix "モバイルでボタンがずれている" +# 実行方法: /git:fix "Button is misaligned" -description = "指定された GitHub の issue に対する修正を生成します。" -prompt = "ステージされた git の変更を分析し、ここで説明されている issue に対するコード修正を提供してください: {{args}}." +description = "与えられた問題に対する修正を生成します。" +prompt = "ここに記述された問題に対するコード修正を提供してください: {{args}}." ``` -モデルには最終的にこのようなプロンプトが送られます: `ステージされた git の変更を分析し、ここで説明されている issue に対するコード修正を提供してください: "モバイルでボタンがずれている"`。 +モデルが受け取る内容: `ここに記述された問題に対するコード修正を提供してください: "Button is misaligned".` + +**B. Shell コマンド内での引数の使用 (`!{...}` ブロック内)** + +Shell インジェクションブロック (`!{...}`) 内で `{{args}}` を使用する場合、引数は置換前に自動的に **shell-escape** されます。これにより、Shell コマンドに安全に引数を渡すことができ、結果として生成されるコマンドが構文的に正しく、セキュアであることを保証し、コマンドインジェクションの脆弱性を防ぎます。 + +**例 (`/grep-code.toml`):** + +```toml +prompt = """ +パターン `{{args}}` の検索結果を要約してください。 + +検索結果: +!{grep -r {{args}} .} +""" +``` + +`/grep-code It's complicated` を実行する場合: + +1. CLI は `{{args}}` が `!{...}` の外と内の両方で使用されていることを検出します。 +2. 外側: 最初の `{{args}}` はそのまま `It's complicated` に置換されます。 +3. 内側: 2番目の `{{args}}` はエスケープされたバージョンに置換されます（例：Linux では `"It's complicated"`）。 +4. 実行されるコマンドは `grep -r "It's complicated" .` になります。 +5. CLI は実行前にこの正確で安全なコマンドを確認するプロンプトを表示します。 +6. 最終的な prompt が送信されます。 +``` ##### 2. デフォルトの引数処理 @@ -211,20 +277,20 @@ prompt = "ステージされた git の変更を分析し、ここで説明さ **例 (`changelog.toml`):** -この例では、モデルの役割を定義し、ユーザーの入力を見つける場所を説明し、期待されるフォーマットと動作を指定することで、堅牢なコマンドを作成する方法を示しています。 +この例では、モデルの役割を定義し、ユーザーの入力がどこにあるかを説明し、期待されるフォーマットと動作を指定することで、堅牢なコマンドを作成する方法を示しています。 ```toml # In: /.qwen/commands/changelog.toml -# 呼び出し方法: /changelog 1.2.0 added "Support for default argument parsing." +# 実行方法: /changelog 1.2.0 added "Support for default argument parsing." description = "プロジェクトの CHANGELOG.md ファイルに新しいエントリを追加します。" prompt = """ # タスク: Changelog の更新 -あなたはこのソフトウェアプロジェクトのエキスパートメンテナーです。ユーザーが changelog に新しいエントリを追加するコマンドを実行しました。 +あなたはこのソフトウェアプロジェクトの経験豊富なメンテナーです。ユーザーが changelog に新しいエントリを追加するコマンドを実行しました。 **ユーザーの生のコマンドが以下の指示の後に追加されています。** @@ -239,32 +305,29 @@ prompt = """ 1. `CHANGELOG.md` ファイルを読み込む。 2. 指定された `` のセクションを探す。 3. 正しい `` 見出しの下に `` を追加する。 -4. バージョンまたはタイプのセクションが存在しない場合は、新たに作成する。 +4. バージョンまたはタイプのセクションが存在しない場合は、新しく作成する。 5. "Keep a Changelog" 形式に厳密に従う。 -/changelog 1.2.0 added "New feature" を実行すると、モデルに送信される最終的なテキストは、元のプロンプトに続けて2つの改行と入力したコマンドとなる。 +/changelog 1.2.0 added "New feature" を実行すると、モデルに送信される最終的なテキストは、元のプロンプトに続けて2つの改行と入力したコマンドになります。 ``` -##### 3. `!{...}` による Shell コマンドの実行 +##### 3. `!{...}` を使用した Shell コマンドの実行 -`prompt` 内で直接 Shell コマンドを実行し、その出力を注入することで、コマンドを動的にすることができます。これは、ファイルの内容を読み込んだり、Git のステータスを確認するなど、ローカル環境からのコンテキストを収集するのに最適です。 +`prompt` 内で直接 Shell コマンドを実行し、その出力を注入することで、コマンドを動的にすることができます。これは、ファイルの内容を読み込んだり、Git のステータスを確認したりといったローカル環境からのコンテキスト収集に最適です。 -カスタムコマンドが Shell コマンドの実行を試みると、Qwen Code は処理を進める前に確認ダイアログを表示するようになりました。これは、意図しないコマンドが実行されないようにするためのセキュリティ対策です。 +カスタムコマンドが Shell コマンドの実行を試みると、Qwen Code は処理を進める前に確認ダイアログを表示するようになりました。これは意図しないコマンドが実行されないようにするためのセキュリティ対策です。 **仕組み:** -1. **コマンドの挿入:** `prompt` 内で `!{...}` 構文を使用して、コマンドを実行する場所とその出力の挿入位置を指定します。 -2. **実行確認:** コマンド実行時、プロンプトが実行しようとしている Shell コマンドの一覧を表示するダイアログが表示されます。 -3. **許可の選択:** 以下の選択肢から選ぶことができます： - - **1回だけ許可:** 今回のみコマンドを実行します。 - - **このセッションでは常に許可:** 現在の CLI セッション中は、このコマンドを一時的な許可リストに追加し、再度確認を求められることはありません。 - - **いいえ:** Shell コマンドの実行をキャンセルします。 - -CLI は引き続きグローバル設定の `excludeTools` および `coreTools` を尊重します。設定で明示的に禁止されているコマンドは、確認ダイアログを表示せずにブロックされます。 +1. **コマンドの注入:** `!{...}` 構文を使用します。 +2. **引数の置換:** ブロック内で `{{args}}` が存在する場合、自動的に Shell エスケープされます（上記の [Context-Aware Injection](#1-context-aware-injection-with-args) を参照）。 +3. **堅牢なパース:** パーサーは、JSON ペイロードを含む複雑な Shell コマンドも正しく処理できます。 +4. **セキュリティチェックと確認:** CLI は、引数がエスケープ・置換された後の最終コマンドに対してセキュリティチェックを実施します。実行されるコマンドを正確に表示するダイアログが表示されます。 +5. **実行とエラー報告:** コマンドが実行されます。コマンドが失敗した場合、プロンプトに注入される出力にはエラーメッセージ（stderr）と、例えば `[Shell command exited with code 1]` のようなステータス行が含まれます。これにより、モデルはエラーのコンテキストを理解できます。 **例 (`git/commit.toml`):** -このコマンドは、ステージングされた Git の差分を取得し、それを使用してモデルにコミットメッセージを作成させます。 +このコマンドは、ステージングされた Git の diff を取得し、それを使用してモデルにコミットメッセージを作成させます。 ````toml @@ -272,9 +335,9 @@ CLI は引き続きグローバル設定の `excludeTools` および `coreTools` # Invoked via: /git:commit -description = "ステージされた変更に基づいて Git のコミットメッセージを生成します。" +description = "ステージされた変更に基づいて Git commit メッセージを生成します。" -# prompt では !{...} を使用してコマンドを実行し、その出力を挿入しています。 +# prompt では !{...} を使用してコマンドを実行し、その出力を挿入します。 prompt = """ 以下の git diff に基づいて、Conventional Commit メッセージを生成してください: @@ -284,11 +347,9 @@ prompt = """ """ -```` - -`/git:commit` を実行すると、CLI はまず `git diff --staged` を実行し、次にそのコマンドの出力で `!{git diff --staged}` を置換して、最終的な完全な prompt をモデルに送信します。 +``` ---- +/git:commit を実行すると、CLI はまず `git diff --staged` を実行し、次に `!{git diff --staged}` をそのコマンドの出力に置き換えて、最終的な完全な prompt をモデルに送信します。 #### 例: 「純粋関数」リファクタリングコマンド @@ -314,21 +375,21 @@ touch ~/.qwen/commands/refactor/pure.toml ```markdown # このコマンドは以下のように実行されます: /refactor:pure -description = "現在のコンテキストにあるコードを、モデルにpure functionへとリファクタリングするよう指示します。" +description = "現在のコンテキストにあるコードを、純粋関数（pure function）にリファクタリングするようモデルに指示します。" prompt = """ -現在のコンテキストで提供されたコードを分析してください。 -それをpure functionにリファクタリングしてください。 +現在のコンテキストで提供されているコードを分析してください。 +それを純粋関数にリファクタリングしてください。 あなたのレスポンスには以下を含めてください: -1. リファクタリングされたpure functionのコードブロック。 -2. あなたが加えた主要な変更点と、それがなぜpure functionに寄与するのかについての簡単な説明。 +1. リファクタリングされた純粋関数のコードブロック。 +2. あなたが加えた主要な変更点と、それが純粋性にどう貢献するかの簡単な説明。 """ ``` **3. コマンドを実行する:** -以上です！CLIでコマンドを実行できるようになりました。まず、コンテキストにファイルを追加し、それからコマンドを実行してください: +以上です！CLIでコマンドを実行できるようになりました。まずコンテキストにファイルを追加し、それからコマンドを実行してください: ``` > @my-messy-function.js @@ -351,10 +412,10 @@ At コマンドは、ファイルやディレクトリの内容をプロンプ - **詳細:** - 単一のファイルパスが指定された場合、そのファイルの内容が読み込まれます。 - ディレクトリパスが指定された場合、そのディレクトリおよびサブディレクトリ内のファイル内容を読み込もうとします。 - - パスにスペースが含まれる場合はバックスラッシュでエスケープしてください（例: `@My\ Documents/file.txt`）。 + - パスにスペースが含まれる場合は、バックスラッシュでエスケープしてください（例: `@My\ Documents/file.txt`）。 - 内部的には `read_many_files` ツールを使用しています。内容が取得された後、クエリに挿入されてからモデルに送信されます。 - **Git を意識したフィルタリング:** デフォルトでは、Git で無視されるファイル（`node_modules/`、`dist/`、`.env`、`.git/` など）は除外されます。この動作は `fileFiltering` 設定で変更可能です。 - - **ファイルタイプ:** このコマンドは主にテキストベースのファイルを対象としています。バイナリファイルや非常に大きなファイルは、パフォーマンスと関連性を保つために `read_many_files` ツールによってスキップまたは切り捨てられる可能性があります。ツールはファイルがスキップされた場合にその旨を示します。 + - **ファイルタイプ:** このコマンドは主にテキストベースのファイルを対象としています。バイナリファイルや非常に大きなファイルは、パフォーマンスと関連性を保つために、`read_many_files` ツールによってスキップまたは切り捨てられることがあります。ツールはファイルがスキップされた場合にその旨を示します。 - **出力:** CLI には `read_many_files` が使用されたことを示すツール呼び出しメッセージと、処理されたパスおよびステータスの詳細が表示されます。 - **`@`（単独の @ 記号）** @@ -370,19 +431,19 @@ At コマンドは、ファイルやディレクトリの内容をプロンプ `!` プレフィックスを使用すると、Qwen Code 内から直接システムのシェルとやり取りできます。 - **`!`** - - **説明:** Linux/macOS では `bash`、Windows では `cmd.exe` を使用して、指定された `` を実行します。コマンドからの出力やエラーはすべてターミナルに表示されます。 + - **説明:** Linux/macOS では `bash`、Windows では `cmd.exe` を使用して、指定された `` を実行します。コマンドの出力やエラーはすべてターミナルに表示されます。 - **例:** - - `!ls -la` (`ls -la` を実行して Qwen Code に戻る) - - `!git status` (`git status` を実行して Qwen Code に戻る) + - `!ls -la` (`ls -la` を実行し、Qwen Code に戻る) + - `!git status` (`git status` を実行し、Qwen Code に戻る) - **`!` (Shell モードの切り替え)** - - **説明:** 単独で `!` と入力すると、Shell モードを切り替えます。 + - **説明:** `!` のみを入力すると、Shell モードが切り替わります。 - **Shell モードに入る:** - - 有効になると、Shell モードでは別のカラー表示と「Shell モード インジケーター」が使用されます。 - - Shell モード中は、入力したテキストが直接シェル コマンドとして解釈されます。 + - 有効になると、Shell モードでは別のカラー表示と「Shell モードインジケーター」が使用されます。 + - Shell モード中は、入力したテキストが直接シェルコマンドとして解釈されます。 - **Shell モードを抜ける:** - 抜けると、UI は標準の外観に戻り、通常の Qwen Code の動作が再開されます。 - **すべての `!` 使用時の注意:** Shell モードで実行するコマンドは、ターミナルで直接実行する場合と同じ権限と影響を持ちます。 -- **環境変数:** `!` 経由または Shell モードでコマンドが実行されると、サブプロセスの環境に `QWEN_CODE=1` 環境変数が設定されます。これにより、スクリプトやツールが CLI 内から実行されているかどうかを検出できます。 \ No newline at end of file +- **環境変数:** `!` 経由または Shell モードでコマンドが実行される際、サブプロセスの環境には `QWEN_CODE=1` という環境変数が設定されます。これにより、スクリプトやツールが CLI 内から実行されているかどうかを検出できます。 \ No newline at end of file diff --git a/website/content/ja/cli/configuration.md b/website/content/ja/cli/configuration.md index e1f87258..dd38f330 100644 --- a/website/content/ja/cli/configuration.md +++ b/website/content/ja/cli/configuration.md @@ -4,14 +4,14 @@ Qwen Code では、動作を設定する方法がいくつか用意されてい ## 設定の優先順位 -設定は以下の優先順位に従って適用されます（数字が小さいものほど優先度が低く、大きいものに上書きされます）： +設定は以下の優先順位に従って適用されます（数字が小さいほど優先度が低く、大きいものに上書きされます）： -1. **デフォルト値：** アプリケーション内にハードコードされたデフォルト設定。 -2. **ユーザー設定ファイル：** 現在のユーザー向けのグローバル設定。 -3. **プロジェクト設定ファイル：** プロジェクト固有の設定。 -4. **システム設定ファイル：** システム全体に適用される設定。 -5. **環境変数：** システム全体またはセッション固有の変数。`.env` ファイルから読み込まれる場合もあります。 -6. **コマンドライン引数：** CLI 起動時に渡される値。 +1. **デフォルト値:** アプリケーション内にハードコードされたデフォルト値。 +2. **ユーザー設定ファイル:** 現在のユーザー向けのグローバル設定。 +3. **プロジェクト設定ファイル:** プロジェクト固有の設定。 +4. **システム設定ファイル:** システム全体に適用される設定。 +5. **環境変数:** システム全体またはセッション固有の変数。`.env` ファイルから読み込まれる場合もあります。 +6. **コマンドライン引数:** CLI 起動時に渡される値。 ## 設定ファイル @@ -22,18 +22,19 @@ 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/qwen-code/settings.json`（Linux）、`C:\ProgramData\qwen-code\settings.json`（Windows）または `/Library/Application Support/QwenCode/settings.json`（macOS）。パスは環境変数 `QWEN_CODE_SYSTEM_SETTINGS_PATH` で上書きできます。 + - **適用範囲:** システム上のすべてのユーザーの Qwen Code セッションに適用されます。システム設定はユーザー設定およびプロジェクト設定より優先されます。エンタープライズ環境でシステム管理者がユーザーの Qwen Code 環境を一元管理したい場合に便利です。 -**設定における環境変数についての注意:** `settings.json` ファイル内の文字列値では、`$VAR_NAME` または `${VAR_NAME}` 構文を使用して環境変数を参照できます。これらの変数は設定読み込み時に自動的に解決されます。例えば、環境変数 `MY_API_TOKEN` がある場合、次のように `settings.json` 内で使用できます：`"apiKey": "$MY_API_TOKEN"`。 +**設定における環境変数についての注意:** `settings.json` ファイル内の文字列値では、`$VAR_NAME` または `${VAR_NAME}` 構文を使って環境変数を参照できます。これらの変数は設定読み込み時に自動的に解決されます。例えば、環境変数 `MY_API_TOKEN` がある場合、次のように `settings.json` で使用できます：`"apiKey": "$MY_API_TOKEN"`。 ### プロジェクト内の `.qwen` ディレクトリ -プロジェクト設定ファイルに加えて、プロジェクトの `.qwen` ディレクトリには、Qwen Code の動作に関連するその他のプロジェクト固有のファイルを含めることができます。例えば： +プロジェクト設定ファイルに加えて、プロジェクトの `.qwen` ディレクトリには、Qwen Code の動作に関連するその他のプロジェクト固有のファイルを含めることができます。例: -- [カスタムサンドボックスプロファイル](#sandboxing)（例：`.qwen/sandbox-macos-custom.sb`、`.qwen/sandbox.Dockerfile`）など。 +- [カスタムサンドボックスプロファイル](#sandboxing) (例: `.qwen/sandbox-macos-custom.sb`、`.qwen/sandbox.Dockerfile`) ### `settings.json` で利用可能な設定: @@ -43,10 +44,10 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 - **例:** `"contextFileName": "AGENTS.md"` - **`bugCommand`** (オブジェクト): - - **説明:** `/bug` コマンドのデフォルト URL を上書きします。 + - **説明:** `/bug` コマンドのデフォルトURLを上書きします。 - **デフォルト:** `"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"` - **プロパティ:** - - **`urlTemplate`** (文字列): `{title}` および `{info}` プレースホルダーを含むことができる URL。 + - **`urlTemplate`** (文字列): `{title}` および `{info}` プレースホルダーを含むことができるURL。 - **例:** ```json "bugCommand": { @@ -69,30 +70,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"]` - - **セキュリティに関する注意:** `excludeTools` における `run_shell_command` のコマンド単位の制限は、単純な文字列マッチに基づいているため、簡単に回避される可能性があります。この機能は**セキュリティメカニズムではない**ため、信頼できないコードを安全に実行するために依存すべきではありません。実行可能なコマンドを明示的に選択するには、`coreTools` を使用することを推奨します。 + - **セキュリティに関する注意:** `excludeTools` における `run_shell_command` のコマンド単位の制限は、単純な文字列マッチに基づいているため、簡単に回避可能です。この機能は**セキュリティメカニズムではありません**。信頼できないコードを安全に実行するためにこの機能に依存しないでください。実行可能なコマンドを明示的に選択するには `coreTools` を使用することを推奨します。 - **`allowMCPServers`** (文字列の配列): - **説明:** モデルで利用可能にする 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` @@ -102,7 +103,7 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 - **例:** `"theme": "GitHub"` - **`vimMode`** (boolean): - - **説明:** 入力編集時の vim モードを有効または無効にします。有効にすると、入力エリアで vim スタイルのナビゲーションおよび編集コマンド（NORMAL モードと INSERT モード）がサポートされます。vim モードの状態はフッターに表示され、セッション間で保持されます。 + - **説明:** 入力編集用の vim モードを有効または無効にします。有効にすると、入力エリアで vim スタイルのナビゲーションおよび編集コマンド（NORMAL モードと INSERT モード）がサポートされます。vim モードの状態はフッターに表示され、セッション間で保持されます。 - **デフォルト:** `false` - **例:** `"vimMode": true` @@ -117,26 +118,30 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 - **例:** `"toolDiscoveryCommand": "bin/get_tools"` - **`toolCallCommand`** (文字列): - - **説明:** `toolDiscoveryCommand` を使用して検出した特定のツールを呼び出すためのカスタムシェルコマンドを定義します。シェルコマンドは以下の条件を満たす必要があります： - - 最初のコマンドライン引数として関数 `name`（[function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) と完全に一致）を受け取る。 + - **説明:** `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`** (オブジェクト): - - **説明:** カスタムツールを検出して使用するための 1 つ以上の Model-Context Protocol (MCP) サーバーへの接続を構成します。Qwen Code は構成された各 MCP サーバーに接続し、利用可能なツールを検出しようとします。複数の MCP サーバーが同じ名前のツールを公開している場合、ツール名は構成で定義したサーバーエイリアスでプレフィックスが付けられ（例: `serverAlias__actualToolName`）、競合を回避します。システムは互換性のために MCP ツール定義から特定のスキーマプロパティを削除する場合があります。 + - **説明:** カスタムツールを検出して使用するための Model-Context Protocol (MCP) サーバーへの接続を構成します。Qwen Code は構成された各 MCP サーバーに接続し、利用可能なツールを検出しようとします。複数の MCP サーバーが同じ名前のツールを公開している場合、ツール名は構成で定義したサーバーエイリアスでプレフィックスが付けられ（例: `serverAlias__actualToolName`）、競合を回避します。システムは互換性のために MCP ツール定義から特定のスキーマプロパティを削除する場合があります。`command`、`url`、`httpUrl` のうち少なくとも1つを指定する必要があります。複数が指定された場合、優先順位は `httpUrl` > `url` > `command` です。 - **デフォルト:** 空 - **プロパティ:** - **``** (オブジェクト): 指定されたサーバーのパラメータ。 - - `command` (文字列, 必須): MCP サーバーを起動するためのコマンド。 - - `args` (文字列の配列, オプション): コマンドに渡す引数。 - - `env` (オブジェクト, オプション): サーバープロセスに設定する環境変数。 - - `cwd` (文字列, オプション): サーバーを起動する作業ディレクトリ。 - - `timeout` (数値, オプション): この MCP サーバーへのリクエストのタイムアウト（ミリ秒）。 - - `trust` (boolean, オプション): このサーバーを信頼し、すべてのツール呼び出し確認をバイパスします。 - - `includeTools` (文字列の配列, オプション): この MCP サーバーからインクルードするツール名のリスト。指定された場合、ここにリストされたツールのみがこのサーバーから利用可能になります（ホワイトリスト動作）。指定されていない場合、デフォルトでサーバーのすべてのツールが有効になります。 - - `excludeTools` (文字列の配列, オプション): この MCP サーバーから除外するツール名のリスト。ここにリストされたツールは、サーバーが公開していてもモデルでは利用できません。**注意:** `excludeTools` は `includeTools` よりも優先されます。両方のリストにツールが含まれている場合、除外されます。 + - `command` (文字列, 任意): 標準入出力を介して MCP サーバーを起動するコマンド。 + - `args` (文字列の配列, 任意): コマンドに渡す引数。 + - `env` (オブジェクト, 任意): サーバープロセスに設定する環境変数。 + - `cwd` (文字列, 任意): サーバーを起動する作業ディレクトリ。 + - `url` (文字列, 任意): Server-Sent Events (SSE) を使用して通信する MCP サーバーの URL。 + - `httpUrl` (文字列, 任意): ストリーム可能な HTTP を使用して通信する MCP サーバーの URL。 + - `headers` (オブジェクト, 任意): `url` または `httpUrl` へのリクエストで送信する HTTP ヘッダーのマップ。 + - `timeout` (数値, 任意): この MCP サーバーへのリクエストのタイムアウト（ミリ秒）。 + - `trust` (boolean, 任意): このサーバーを信頼し、すべてのツール呼び出し確認をバイパスします。 + - `description` (文字列, 任意): 表示目的で使用されるサーバーの簡単な説明。 + - `includeTools` (文字列の配列, 任意): この MCP サーバーから含めるツール名のリスト。指定された場合、ここにリストされたツールのみがこのサーバーから利用可能になります（ホワイトリスト動作）。指定されていない場合、デフォルトでサーバーのすべてのツールが有効になります。 + - `excludeTools` (文字列の配列, 任意): この MCP サーバーから除外するツール名のリスト。ここにリストされたツールは、サーバーが公開していてもモデルでは利用できません。**注意:** `excludeTools` は `includeTools` よりも優先されます。両方のリストにツールが含まれている場合、除外されます。 - **例:** ```json "mcpServers": { @@ -159,12 +164,26 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 "env": { "API_KEY": "$MY_API_TOKEN" } + }, + "mySseServer": { + "url": "http://localhost:8081/events", + "headers": { + "Authorization": "Bearer $MY_SSE_TOKEN" + }, + "description": "An example SSE-based MCP server." + }, + "myStreamableHttpServer": { + "httpUrl": "http://localhost:8082/stream", + "headers": { + "X-API-Key": "$MY_HTTP_API_KEY" + }, + "description": "An example Streamable HTTP-based MCP server." } } ``` - **`checkpointing`** (オブジェクト): - - **説明:** 会話およびファイル状態の保存・復元を可能にするチェックポイント機能を構成します。詳細については [Checkpointing documentation](../checkpointing.md) を参照してください。 + - **説明:** 会話およびファイルの状態を保存・復元するチェックポイント機能を構成します。詳細については [Checkpointing documentation](../checkpointing.md) を参照してください。 - **デフォルト:** `{"enabled": false}` - **プロパティ:** - **`enabled`** (boolean): `true` の場合、`/restore` コマンドが利用可能になります。 @@ -174,8 +193,8 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 - **デフォルト:** `vscode` - **例:** `"preferredEditor": "vscode"` -- **`telemetry`** (オブジェクト): - - **説明:** Qwen Code のログおよびメトリクス収集を構成します。詳細については [Telemetry](../telemetry.md) を参照してください。 +- **`telemetry`** (オブジェクト) + - **説明:** Qwen Code のロギングおよびメトリクス収集を構成します。詳細については [Telemetry](../telemetry.md) を参照してください。 - **デフォルト:** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **プロパティ:** - **`enabled`** (boolean): テレメトリが有効かどうか。 @@ -216,29 +235,7 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 "hideBanner": true ``` -- **`maxSessionTurns`** (数値): - - **説明:** セッションの最大ターン数を設定します。セッションがこの制限を超えると、CLI は処理を停止し、新しいチャットを開始します。 - - **デフォルト:** `-1` (無制限) - - **例:** - ```json - "maxSessionTurns": 10 - ``` - -- **`summarizeToolOutput`** (オブジェクト): - - **説明:** ツール出力の要約を有効または無効にします。`tokenBudget` 設定を使用して、要約のトークン予算を指定できます。 - - 注意: 現在は `run_shell_command` ツールのみがサポートされています。 - - **デフォルト:** `{}` (デフォルトでは無効) - - **例:** - ```json - "summarizeToolOutput": { - "run_shell_command": { - "tokenBudget": 2000 - } - } - ``` - -- **`excludedProjectEnvVars`** (文字列の配列): - - **説明:** プロジェクトの `.env` ファイルから読み込まれるべきでない環境変数を指定します。これにより、プロジェクト固有 +- **`maxSessionTurns`** (数値 ### `settings.json` の例: @@ -281,15 +278,15 @@ Qwen Code は永続的な設定のために `settings.json` ファイルを使 ## Shell History -CLIは実行したshellコマンドの履歴を保持します。異なるプロジェクト間での競合を避けるため、この履歴はユーザーのホームフォルダ内のプロジェクト固有のディレクトリに保存されます。 +CLI は実行した shell コマンドの履歴を保持します。異なるプロジェクト間での競合を避けるため、この履歴はユーザーのホームフォルダ内のプロジェクト固有のディレクトリに保存されます。 -- **保存場所:** `~/.qwen/tmp//shell_history` - - ``はプロジェクトのルートパスから生成される一意の識別子です。 - - 履歴は`shell_history`という名前のファイルに保存されます。 +- **Location:** `~/.qwen/tmp//shell_history` + - `` はプロジェクトのルートパスから生成される一意の識別子です。 + - 履歴は `shell_history` という名前のファイルに保存されます。 ## 環境変数と `.env` ファイル -環境変数は、アプリケーションを設定する一般的な方法です。特に API キーのような機密情報や、環境によって変わる設定に使われます。 +環境変数は、アプリケーションを設定する一般的な方法です。特に API キーのような機密情報や、環境によって変わる設定に使われます。認証の設定については、[認証ドキュメント](./authentication.md)を参照してください。利用可能なすべての認証方法が記載されています。 CLI は `.env` ファイルから自動的に環境変数を読み込みます。読み込み順序は以下の通りです： @@ -297,74 +294,55 @@ CLI は `.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 はこれがないと動作しません。 - - シェルプロファイル（例：`~/.bashrc`、`~/.zshrc`）または `.env` ファイルで設定してください。 -- **`GEMINI_MODEL`**： - - 使用するデフォルトの Gemini モデルを指定します。 +- **`OPENAI_API_KEY`**: + - 利用可能な[認証方法](./authentication.md)の一つ。 + - シェルプロファイル（例：`~/.bashrc`、`~/.zshrc`）または `.env` ファイルで設定します。 +- **`OPENAI_BASE_URL`**: + - 利用可能な[認証方法](./authentication.md)の一つ。 + - シェルプロファイル（例：`~/.bashrc`、`~/.zshrc`）または `.env` ファイルで設定します。 +- **`OPENAI_MODEL`**: + - 使用するデフォルトの OPENAI モデルを指定します。 - ハードコードされたデフォルト値を上書きします。 - - 例：`export GEMINI_MODEL="gemini-2.5-flash"` -- **`GOOGLE_API_KEY`**： - - Google Cloud API キー。 - - 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` を定義する必要があります。 - - 例：`export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`。 -- **`GOOGLE_APPLICATION_CREDENTIALS`**（文字列）： - - **説明：** 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 Project のロケーション（例：us-central1）。 - - Express モード以外で Vertex AI を使用するために必要です。 - - 例：`export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`。 -- **`GEMINI_SANDBOX`**： + - 例: `export OPENAI_MODEL="qwen3-coder-plus"` +- **`GEMINI_SANDBOX`**: - `settings.json` の `sandbox` 設定の代替。 - - `true`、`false`、`docker`、`podman`、またはカスタムコマンド文字列を受け入れます。 -- **`SEATBELT_PROFILE`**（macOS 固有）： + - `true`、`false`、`docker`、`podman`、またはカスタムコマンド文字列を受け取ります。 +- **`SEATBELT_PROFILE`**（macOS 固有）: - macOS で Seatbelt（`sandbox-exec`）プロファイルを切り替えます。 - - `permissive-open`：（デフォルト）プロジェクトフォルダ（およびいくつかの他のフォルダ）への書き込みを制限します（詳細は `packages/cli/src/utils/sandbox-macos-permissive-open.sb` を参照）が、他の操作は許可します。 - - `strict`：デフォルトで操作を拒否する厳格なプロファイルを使用します。 - - ``：カスタムプロファイルを使用します。カスタムプロファイルを定義するには、プロジェクトの `.qwen/` ディレクトリに `sandbox-macos-.sb` という名前のファイルを作成します（例：`my-project/.qwen/sandbox-macos-custom.sb`）。 -- **`DEBUG` または `DEBUG_MODE`**（下位ライブラリや CLI 自体でよく使われる）： + - `permissive-open`: （デフォルト）プロジェクトフォルダ（およびいくつかの他のフォルダ）への書き込みを制限しますが、その他の操作は許可されます（詳細は `packages/cli/src/utils/sandbox-macos-permissive-open.sb` を参照）。 + - `strict`: デフォルトで操作を拒否する厳格なプロファイルを使用します。 + - ``: カスタムプロファイルを使用します。カスタムプロファイルを定義するには、プロジェクトの `.qwen/` ディレクトリに `sandbox-macos-.sb` という名前のファイルを作成します（例：`my-project/.qwen/sandbox-macos-custom.sb`）。 +- **`DEBUG` または `DEBUG_MODE`**（CLI 自体や内部ライブラリでよく使われる）: - `true` または `1` に設定すると、詳細なデバッグログを有効にします。トラブルシューティングに役立ちます。 - - **注意：** これらの変数は、CLI の動作に干渉するのを防ぐため、デフォルトでプロジェクトの `.env` ファイルからは自動的に除外されます。Qwen Code でこれらの変数を設定する必要がある場合は、`.qwen/.env` ファイルを使用してください。 -- **`NO_COLOR`**： + - **注意：** これらの変数は、CLI の動作に干渉するのを防ぐため、プロジェクトの `.env` ファイルからはデフォルトで除外されます。Qwen Code でこれらの変数を使用する必要がある場合は、`.qwen/.env` ファイルを使用してください。 +- **`NO_COLOR`**: - 任意の値を設定すると、CLI のすべてのカラー出力を無効にします。 -- **`CLI_TITLE`**： - - 文字列を設定すると、CLI のタイトルをカスタマイズできます。 -- **`CODE_ASSIST_ENDPOINT`**： +- **`CLI_TITLE`**: + - 文字列を設定して、CLI のタイトルをカスタマイズします。 +- **`CODE_ASSIST_ENDPOINT`**: - コードアシストサーバーのエンドポイントを指定します。 - 開発やテストに役立ちます。 -- **`TAVILY_API_KEY`**： - - Tavily ウェブ検索サービス用の API キー。 +- **`TAVILY_API_KEY`**: + - Tavily ウェブ検索サービスの API キー。 - `web_search` ツール機能を有効にするために必要です。 - - 設定されていない場合、ウェブ検索ツールは無効化され、スキップされます。 - - 例：`export TAVILY_API_KEY="tvly-your-api-key-here"` + - 設定されていない場合、ウェブ検索ツールは無効化されスキップされます。 + - 例: `export TAVILY_API_KEY="tvly-your-api-key-here"` ## コマンドライン引数 CLI 実行時に直接渡された引数は、そのセッションにおいて他の設定を上書きできます。 - **`--model `** (**`-m `**): - - このセッションで使用する Gemini モデルを指定します。 - - 例: `npm start -- --model gemini-1.5-pro-latest` + - このセッションで使用する Qwen モデルを指定します。 + - 例: `npm start -- --model qwen3-coder-plus` - **`--prompt `** (**`-p `**): - - プロンプトを直接コマンドに渡すために使用します。これにより、Qwen Code は非対話モードで起動されます。 + - プロンプトをコマンドに直接渡すために使用します。これにより、Qwen Code が非インタラクティブモードで起動します。 - **`--prompt-interactive `** (**`-i `**): - - 指定したプロンプトを初期入力として対話セッションを開始します。 - - プロンプトは対話セッション内で処理され、セッション開始前ではありません。 - - stdin からのパイプ入力がある場合は使用できません。 + - 指定したプロンプトを初期入力としてインタラクティブセッションを開始します。 + - プロンプトはセッション開始前に処理されるのではなく、セッション内で処理されます。 + - stdin からの入力をパイプで渡す場合には使用できません。 - 例: `qwen -i "explain this code"` - **`--sandbox`** (**`-s`**): - このセッションでサンドボックスモードを有効にします。 @@ -373,61 +351,63 @@ CLI 実行時に直接渡された引数は、そのセッションにおいて - **`--debug`** (**`-d`**): - このセッションでデバッグモードを有効にし、より詳細な出力を提供します。 - **`--all-files`** (**`-a`**): - - 設定されている場合、現在のディレクトリ内のすべてのファイルを再帰的にプロンプトのコンテキストに含めます。 -- **`--help`** (または **`-h`**): + - 設定すると、現在のディレクトリ内のすべてのファイルを再帰的にプロンプトのコンテキストに含めます。 +- **`--help`** (**`-h`**): - コマンドライン引数に関するヘルプ情報を表示します。 - **`--show-memory-usage`**: - 現在のメモリ使用量を表示します。 - **`--yolo`**: - - YOLO モードを有効にし、すべてのツール呼び出しを自動で承認します。 + - YOLO モードを有効にし、すべてのツール呼び出しを自動的に承認します。 - **`--approval-mode `**: - ツール呼び出しの承認モードを設定します。利用可能なモード: - `default`: 各ツール呼び出しで承認を求める（デフォルトの動作） - - `auto_edit`: 編集系ツール（replace、write_file）は自動承認し、それ以外は承認を求める + - `auto_edit`: 編集系ツール（edit、write_file）は自動承認し、それ以外は承認を求める - `yolo`: すべてのツール呼び出しを自動承認（`--yolo` と同等） - - `--yolo` と同時に使用することはできません。新しい統一アプローチでは、`--yolo` の代わりに `--approval-mode=yolo` を使用してください。 + - `--yolo` と同時に使用することはできません。新しい統一されたアプローチでは、`--yolo` の代わりに `--approval-mode=yolo` を使用してください。 - 例: `qwen --approval-mode auto_edit` - **`--telemetry`**: - [telemetry](../telemetry.md) を有効にします。 - **`--telemetry-target`**: - - テレメトリーターゲットを設定します。詳細は [telemetry](../telemetry.md) を参照してください。 + - テレメトリのターゲットを設定します。詳細は [telemetry](../telemetry.md) を参照してください。 - **`--telemetry-otlp-endpoint`**: - - テレメトリー用の OTLP エンドポイントを設定します。詳細は [telemetry](../telemetry.md) を参照してください。 + - テレメトリ用の OTLP エンドポイントを設定します。詳細は [telemetry](../telemetry.md) を参照してください。 +- **`--telemetry-otlp-protocol`**: + - テレメトリ用の OTLP プロトコルを設定します（`grpc` または `http`）。デフォルトは `grpc` です。詳細は [telemetry](../telemetry.md) を参照してください。 - **`--telemetry-log-prompts`**: - - テレメトリー用にプロンプトのログを有効にします。詳細は [telemetry](../telemetry.md) を参照してください。 + - テレメトリ用にプロンプトのログを有効にします。詳細は [telemetry](../telemetry.md) を参照してください。 - **`--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`**: - CLI のバージョンを表示します。 - **`--openai-logging`**: - - デバッグおよび分析のために OpenAI API 呼び出しのログを有効にします。このフラグは `settings.json` の `enableOpenAILogging` 設定を上書きします。 + - OpenAI API 呼び出しのログを有効にして、デバッグや分析に役立てます。このフラグは `settings.json` の `enableOpenAILogging` 設定を上書きします。 - **`--tavily-api-key `**: - このセッションでウェブ検索機能に使用する Tavily API キーを設定します。 - 例: `qwen --tavily-api-key tvly-your-api-key-here` -## コンテキストファイル（階層的な指示コンテキスト） +## Context ファイル（階層型インストラクショナルコンテキスト） -CLI の**動作**設定というわけではありませんが、コンテキストファイル（デフォルトでは `QWEN.md` ですが、`contextFileName` 設定で変更可能）は、**指示コンテキスト**（「メモリ」とも呼ばれます）を設定するために非常に重要です。この強力な機能により、プロジェクト固有の指示、コーディングスタイルガイド、または関連する背景情報を AI に提供でき、あなたのニーズにより適した正確な応答が得られるようになります。CLI には、フッターにロードされたコンテキストファイル数を表示する UI 要素などがあり、現在のコンテキスト状態を確認できます。 +CLI の**動作**を直接設定するものではありませんが、Context ファイル（デフォルトでは `QWEN.md`、`contextFileName` 設定で変更可能）は、**インストラクショナルコンテキスト**（「メモリ」とも呼ばれます）を設定するために非常に重要です。この強力な機能により、プロジェクト固有の指示、コーディングスタイルガイド、または関連する背景情報を AI に提供でき、あなたのニーズにより適切で正確な応答を得ることができます。CLI には、フッターにロードされた Context ファイル数を表示するインジケータなど、アクティブなコンテキストの状態を確認できる UI 要素も含まれています。 -- **目的：** これらの Markdown ファイルには、Gemini モデルとのやり取り中に参照してほしい指示、ガイドライン、またはコンテキスト情報を記述します。この指示コンテキストは、階層的に管理されるように設計されています。 +- **目的：** これらの Markdown ファイルには、Qwen モデルとのやり取り中に参照してほしい指示、ガイドライン、またはコンテキスト情報を記述します。システムは、このインストラクショナルコンテキストを階層的に管理するように設計されています。 ### コンテキストファイルの例（例：`QWEN.md`） -以下は、TypeScriptプロジェクトのルートにあるコンテキストファイルが含むかもしれない内容の概念的な例です： +以下は、TypeScriptプロジェクトのルートにあるコンテキストファイルが含む内容の概念的な例です： ```markdown @@ -436,54 +416,54 @@ 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`）。 - 範囲: すべてのプロジェクトに対してデフォルトの指示を提供します。 2. **プロジェクトルートおよび祖先ディレクトリのコンテキストファイル:** - - 場所: CLIは、現在の作業ディレクトリから設定されたコンテキストファイルを検索し、次に各親ディレクトリを `.git` フォルダで識別されるプロジェクトルートまたはホームディレクトリまで遡って検索します。 + - 場所: CLIは、現在の作業ディレクトリから設定されたコンテキストファイルを検索し、次に各親ディレクトリを `.git` フォルダで識別されるプロジェクトルートまたはホームディレクトリまで検索します。 - 範囲: プロジェクト全体またはその主要な部分に関連するコンテキストを提供します。 3. **サブディレクトリのコンテキストファイル（コンテキスト依存/ローカル）:** - - 場所: CLIは、現在の作業ディレクトリ以下のサブディレクトリ（`node_modules` や `.git` などの一般的な無視パターンを尊重して）からも設定されたコンテキストファイルをスキャンします。この検索の深さはデフォルトでは200ディレクトリに制限されていますが、`settings.json` ファイルの `memoryDiscoveryMaxDirs` フィールドで設定可能です。 + - 場所: CLIは、現在の作業ディレクトリ以下のサブディレクトリ（`node_modules`、`.git` などの一般的な無視パターンを尊重して）からも設定されたコンテキストファイルをスキャンします。この検索の深さはデフォルトでは200ディレクトリに制限されていますが、`settings.json` ファイルの `memoryDiscoveryMaxDirs` フィールドで設定可能です。 - 範囲: 特定のコンポーネント、モジュール、またはプロジェクトのサブセクションに関連する非常に具体的な指示を可能にします。 -- **結合とUI表示:** 見つかったすべてのコンテキストファイルの内容は結合され（元の場所とパスを示す区切り文字付きで）、システムプロンプトの一部として提供されます。CLIのフッターには読み込まれたコンテキストファイルの数が表示され、現在アクティブな指示コンテキストを視覚的に確認できます。 +- **結合と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の応答をあなたの特定のニーズやプロジェクトに合わせて調整できます。 +``` ## サンドボックス -Qwen Code は、システムを保護するために、潜在的に安全でない操作（シェルコマンドやファイルの変更など）をサンドボックス環境内で実行できます。 +Qwen Code は、システムを保護するために、サンドボックス環境内で潜在的に危険な操作（シェルコマンドやファイルの変更など）を実行できます。 サンドボックスはデフォルトでは無効になっていますが、以下の方法で有効にできます： @@ -493,7 +473,7 @@ Qwen Code は、システムを保護するために、潜在的に安全でな デフォルトでは、事前にビルドされた `qwen-code-sandbox` Docker イメージを使用します。 -プロジェクト固有のサンドボックス要件がある場合は、プロジェクトのルートディレクトリに `.qwen/sandbox.Dockerfile` というカスタム Dockerfile を作成できます。この Dockerfile はベースとなるサンドボックスイメージを元にできます： +プロジェクト固有のサンドボックス要件がある場合は、プロジェクトのルートディレクトリに `.qwen/sandbox.Dockerfile` というカスタム Dockerfile を作成できます。この Dockerfile はベースとなるサンドボックスイメージを元に作成できます： ```dockerfile FROM qwen-code-sandbox @@ -508,31 +488,31 @@ 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 ``` -## 使用統計 +## 使用統計情報 -Qwen Code の改善のために、匿名化された使用統計情報を収集しています。このデータは、CLI の使用状況の理解、一般的な問題の特定、新機能の優先順位付けに役立てています。 +Qwen Code の改善のために、匿名化された使用統計情報を収集しています。このデータは、CLI がどのように使われているかを理解し、一般的な問題を特定し、新機能の優先順位を決定するために役立ちます。 **収集する情報:** -- **ツール呼び出し:** 呼び出されたツールの名前、成功または失敗の結果、実行にかかった時間を記録します。ツールに渡された引数や、ツールから返されたデータは収集しません。 -- **APIリクエスト:** 各リクエストで使用されたモデル、リクエストの所要時間、成功したかどうかを記録します。プロンプトやレスポンスの内容は収集しません。 +- **ツール呼び出し:** 呼び出されたツールの名前、成功または失敗の結果、実行にかかった時間などを記録します。ただし、ツールに渡された引数や、ツールが返したデータは収集しません。 +- **API リクエスト:** 各リクエストで使用されたモデル、リクエストの所要時間、成功したかどうかを記録します。プロンプトやレスポンスの内容は収集しません。 - **セッション情報:** 有効化されているツールや承認モードなど、CLI の設定に関する情報を収集します。 **収集しない情報:** -- **個人を特定できる情報 (PII):** 氏名、メールアドレス、APIキーなど、個人を特定できる情報は一切収集しません。 -- **プロンプトおよびレスポンスの内容:** ユーザーが入力したプロンプトや、モデルからのレスポンス内容は記録しません。 -- **ファイルの内容:** CLI が読み書きしたファイルの内容は記録しません。 +- **個人を特定できる情報 (PII):** 氏名、メールアドレス、API キーなど、個人を特定できる情報は一切収集しません。 +- **プロンプトおよびレスポンスの内容:** ユーザーが入力したプロンプトや、モデルからのレスポンスの内容は記録しません。 +- **ファイルの内容:** CLI によって読み書きされたファイルの内容は記録しません。 -**使用統計の無効化方法:** +**使用統計情報の収集をオプトアウトする方法:** -`settings.json` ファイルで `usageStatisticsEnabled` プロパティを `false` に設定することで、いつでも使用統計の収集を無効化できます: +`settings.json` ファイルで `usageStatisticsEnabled` プロパティを `false` に設定することで、いつでも使用統計情報の収集をオプトアウトできます： ```json { @@ -540,4 +520,12 @@ Qwen Code の改善のために、匿名化された使用統計情報を収集 } ``` -注意: 使用統計が有効な場合、イベントは Alibaba Cloud RUM コレクションエンドポイントに送信されます。 \ No newline at end of file +注意: 使用統計情報が有効になっている場合、イベントは Alibaba Cloud の RUM 収集エンドポイントに送信されます。 + +- **`enableWelcomeBack`** (boolean): + - **説明:** 会話履歴のあるプロジェクトに戻ってきたときに「Welcome back」ダイアログを表示します。 + - **デフォルト:** `true` + - **カテゴリ:** UI + - **再起動が必要:** いいえ + - **例:** `"enableWelcomeBack": false` + - **詳細:** 有効にすると、Qwen Code は以前に生成されたプロジェクトサマリー（`.qwen/PROJECT_SUMMARY.md`）があるプロジェクトに戻ってきたことを自動的に検出し、以前の会話を続けるか、新たに開始するかを選択できるダイアログを表示します。この機能は `/chat summary` コマンドおよび終了確認ダイアログと連携しています。詳しくは [Welcome Back ドキュメント](./welcome-back.md) を参照してください。 \ No newline at end of file diff --git a/website/content/ja/cli/index.md b/website/content/ja/cli/index.md index 7474df42..6d12f74e 100644 --- a/website/content/ja/cli/index.md +++ b/website/content/ja/cli/index.md @@ -1,15 +1,16 @@ # Qwen Code CLI -Qwen Code 内において、`packages/cli` はユーザーが Qwen や他の AI モデル、およびそれに関連するツールとプロンプトを送受信するためのフロントエンドです。Qwen Code 全体の概要については、[メインドキュメントページ](../index.md)を参照してください。 +Qwen Code 内において、`packages/cli` はユーザーが Qwen や他の AI モデル、およびそれに関連するツールとプロンプトを送受信するためのフロントエンドです。Qwen Code の概要については、[メインドキュメントページ](../index.md)を参照してください。 -## このセクションの内容 +## このセクションのナビゲーション -- **[Authentication](./authentication.md):** Qwen OAuth および OpenAI 互換プロバイダを使用した認証設定のガイド。 +- **[Authentication](./authentication.md):** Qwen OAuth および OpenAI 互換プロバイダを使用した認証設定ガイド。 - **[Commands](./commands.md):** Qwen Code CLI コマンド（例: `/help`、`/tools`、`/theme`）のリファレンス。 -- **[Configuration](./configuration.md):** 設定ファイルを使用して Qwen Code CLI の動作をカスタマイズする方法のガイド。 +- **[Configuration](./configuration.md):** 設定ファイルを使用して Qwen Code CLI の動作をカスタマイズするガイド。 - **[Token Caching](./token-caching.md):** トークンキャッシングにより API コストを最適化する方法。 -- **[Themes](./themes.md):** 異なるテーマを使って CLI の外観をカスタマイズするガイド。 -- **[Tutorials](tutorials.md):** Qwen Code を使って開発タスクを自動化する方法を示すチュートリアル。 +- **[Themes](./themes.md)**: 異なるテーマを使って CLI の外観をカスタマイズするガイド。 +- **[Tutorials](tutorials.md)**: Qwen Code を使って開発タスクを自動化する方法を示すチュートリアル。 +- **[Welcome Back](./welcome-back.md)**: セッション間でシームレスに作業を再開できる Welcome Back 機能について学ぶ。 ## 非対話モード diff --git a/website/content/ja/cli/token-caching.md b/website/content/ja/cli/token-caching.md index bf5a4f6a..465ae782 100644 --- a/website/content/ja/cli/token-caching.md +++ b/website/content/ja/cli/token-caching.md @@ -2,13 +2,13 @@ Qwen Code は、API キー認証を使用している場合（例：OpenAI 互換プロバイダー）、トークンキャッシングを通じて API コストを自動的に最適化します。この機能は、以前のシステム指示とコンテキストを再利用して、後続のリクエストで処理されるトークン数を削減します。 -**トークンキャッシングが利用可能なのは以下の場合です：** +**トークンキャッシングが利用可能なのは以下のユーザーです：** -- API キー利用者（Gemini API キー） +- API キー利用者（Qwen API キー） - Vertex AI 利用者（プロジェクトとロケーションの設定済み） -**トークンキャッシングが利用できないのは以下の場合です：** +**トークンキャッシングが利用できないのは以下のユーザーです：** -- OAuth 利用者（Google 個人／エンタープライズアカウント）- 現在のところ、Code Assist API はキャッシュされたコンテンツの作成をサポートしていません +- OAuth 利用者（Google 個人／エンタープライズアカウント）— 現在のところ、Code Assist API はキャッシュされたコンテンツの作成をサポートしていません -トークン使用量とキャッシュされたトークンによる節約量は、`/stats` コマンドを使用して確認できます。キャッシュされたトークンがある場合、それは stats の出力に表示されます。 \ No newline at end of file +トークン使用量とキャッシュされたトークンによる節約量は、`/stats` コマンドで確認できます。キャッシュされたトークンがある場合、それは stats の出力に表示されます。 \ No newline at end of file diff --git a/website/content/ja/cli/welcome-back.md b/website/content/ja/cli/welcome-back.md new file mode 100644 index 00000000..a47d4df8 --- /dev/null +++ b/website/content/ja/cli/welcome-back.md @@ -0,0 +1,134 @@ +# Welcome Back 機能 + +Welcome Back 機能は、既存の会話履歴があるプロジェクトに戻ってきた際に自動的に検知し、中断した場所から作業を再開できるようにすることで、シームレスな作業再開をサポートします。 + +## 概要 + +プロジェクトディレクトリで Qwen Code を起動する際、以前に生成されたプロジェクトサマリー（`.qwen/PROJECT_SUMMARY.md`）が存在する場合、Welcome Back ダイアログが自動的に表示され、新規に開始するか、または以前の会話を継続するかを選択できます。 + +## 動作について + +### 自動検知 + +Welcome Back 機能は以下を自動的に検知します： + +- **Project Summary ファイル:** 現在のプロジェクトディレクトリに `.qwen/PROJECT_SUMMARY.md` が存在するかを確認 +- **会話履歴:** 継続可能な意味のある会話履歴があるかどうかをチェック +- **設定:** `enableWelcomeBack` 設定を尊重（デフォルトでは有効） + +### Welcome Back ダイアログ + +プロジェクトのサマリーが見つかると、次のような内容が表示されるダイアログが開きます： + +- **最終更新日時**：サマリーが最後に生成された日時を表示します +- **全体の目標**：前回のセッションで設定したメインの目標を表示します +- **現在の計画**：タスクの進行状況をステータス表示で確認できます： + - `[DONE]` - 完了したタスク + - `[IN PROGRESS]` - 現在進行中のタスク + - `[TODO]` - これから実行する予定のタスク +- **タスク統計情報**：全タスク数、完了数、進行中、保留中のタスク数をまとめた情報 + +### オプション + +Welcome Back ダイアログが表示された際には、以下の2つの選択肢があります： + +1. **新しいチャットセッションを開始する** + - ダイアログを閉じ、新しい会話を開始します + - 以前のコンテキストは読み込まれません + +2. **前回の会話を続ける** + - 入力欄に以下が自動で入力されます： + `@.qwen/PROJECT_SUMMARY.md, Based on our previous conversation, Let's continue?` + - プロジェクトサマリーがAIのコンテキストとして読み込まれます + - 前回中断した場所からシームレスに作業を再開できます + +## 設定（Configuration） + +### Welcome Back の有効化/無効化 + +Welcome Back 機能は、設定から制御できます： + +**設定ダイアログから:** + +1. Qwen Code で `/settings` を実行 +2. UI カテゴリから "Enable Welcome Back" を探す +3. 設定をオン/オフに切り替える + +**設定ファイルから:** +`.qwen/settings.json` に以下を追加: + +```json +{ + "enableWelcomeBack": true +} +``` + +**設定ファイルの場所:** + +- **ユーザー設定:** `~/.qwen/settings.json` (すべてのプロジェクトに影響) +- **プロジェクト設定:** `.qwen/settings.json` (プロジェクト固有) + +### キーボードショートカット + +- **Escape:** Welcome Back ダイアログを閉じる (デフォルトでは "Start new chat session") + +## 他の機能との統合 + +### プロジェクトサマリーの生成 + +Welcome Back機能は`/chat summary`コマンドとシームレスに連携します： + +1. **サマリーを生成：** `/chat summary`を使ってプロジェクトサマリーを作成 +2. **自動検出：** 次回このプロジェクトでQwen Codeを起動すると、Welcome Backがサマリーを検出 +3. **作業を再開：** 続行を選択するとサマリーがコンテキストとして読み込まれる + +### 終了確認 + +`/quit-confirm`で終了し、「サマリーを生成して終了」を選択した場合： + +1. プロジェクトサマリーが自動的に作成される +2. 次回セッションでWelcome Backダイアログが表示される +3. 作業をシームレスに継続可能 + +## ファイル構造 + +Welcome Back機能は以下のファイルを作成・使用します： + +``` +your-project/ +├── .qwen/ +│ └── PROJECT_SUMMARY.md # 生成されたプロジェクトサマリー +``` + +### PROJECT_SUMMARY.mdのフォーマット + +生成されるサマリーは以下の構造に従います： + +```markdown + +# Project Summary + +## Overall Goal + + + +## Key Knowledge + + + + +## Recent Actions + + + + +## Current Plan + + + + +--- + +## Summary Metadata + +**Update time**: 2025-01-10T15:30:00.000Z \ No newline at end of file diff --git a/website/content/ja/deployment.md b/website/content/ja/deployment.md index 9ab7696e..7b4889cb 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.9 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 ``` -- **`--sandbox` フラグの使用:** - Qwen Code をローカルにインストール済みの場合（前述の標準インストール手順に従って）、サンドボックスコンテナ内で実行するように指示できます。 +- **`--sandbox` フラグを使用:** + Qwen Code をローカルにインストール済みの場合（前述の標準インストール手順に従って）、サンドボックスコンテナ内で実行するよう指示できます。 ```bash qwen --sandbox -y -p "your prompt here" ``` @@ -55,21 +55,20 @@ Qwen Code を実行するにはいくつかの方法があります。どの方 プロジェクトへのコントリビューターは、CLI をソースコードから直接実行することになるでしょう。 -- **開発モード：** - この方法ではホットリロードが有効になるため、開発中に便利です。 +- **開発モード:** + この方法ではホットリロードが有効で、開発中に便利です。 ```bash # リポジトリのルートから実行 npm run start ``` - -- **本番環境に近いモード（リンクされたパッケージ）：** - この方法では、ローカルのパッケージをグローバルにリンクすることで、npm でインストールしたときと同じように動作させることができます。ローカルビルドを本番ワークフローでテストするのに便利です。 +- **本番環境に近いモード（リンクされたパッケージ）:** + この方法では、ローカルのパッケージをリンクしてグローバルインストールをシミュレートします。本番ワークフローでのローカルビルドのテストに便利です。 ```bash # ローカルの cli パッケージをグローバルな node_modules にリンク npm link packages/cli - # これで `qwen` コマンドを使ってローカル版を実行できます + # これで `qwen` コマンドを使ってローカルバージョンを実行できます qwen ``` @@ -77,7 +76,7 @@ Qwen Code を実行するにはいくつかの方法があります。どの方 ### 4. GitHub から最新の Qwen Code コミットを実行 -GitHub リポジトリから最新のコミット済みバージョンの Qwen Code を直接実行できます。これはまだ開発中の機能をテストするのに便利です。 +GitHub リポジトリから最新のコミット済みバージョンの Qwen Code を直接実行できます。これは、まだ開発中の機能をテストするのに便利です。 ```bash @@ -91,7 +90,7 @@ npx https://github.com/QwenLM/qwen-code **NPM パッケージ** -Qwen Code プロジェクトはモノレポで、コアパッケージを NPM レジストリに公開しています： +Qwen Code プロジェクトは monorepo であり、コアパッケージを NPM レジストリに公開しています： - `@qwen-code/qwen-code-core`: バックエンド。ロジックとツールの実行を処理します。 - `@qwen-code/qwen-code`: ユーザー向けのフロントエンド。 @@ -102,9 +101,9 @@ Qwen Code プロジェクトはモノレポで、コアパッケージを NPM 配布チャネルに応じて、2 種類のビルドプロセスが使用されます： -- **NPM への公開:** NPM レジストリに公開する際は、`@qwen-code/qwen-code-core` および `@qwen-code/qwen-code` 内の TypeScript ソースコードが TypeScript Compiler (`tsc`) を使って標準的な JavaScript にトランスパイルされます。生成された `dist/` ディレクトリが NPM パッケージとして公開されます。これは TypeScript ライブラリの一般的な手法です。 +- **NPM への公開:** NPM レジストリに公開する際には、`@qwen-code/qwen-code-core` および `@qwen-code/qwen-code` 内の TypeScript ソースコードが TypeScript Compiler (`tsc`) を使用して標準的な JavaScript にトランスパイルされます。生成された `dist/` ディレクトリが NPM パッケージとして公開されます。これは TypeScript ライブラリの一般的な手法です。 -- **GitHub からの `npx` 実行:** GitHub から最新版の Qwen Code を直接実行する際は、`package.json` の `prepare` スクリプトによって別のプロセスが起動します。このスクリプトは `esbuild` を使ってアプリケーション全体とその依存関係を 1 つの自己完結型 JavaScript ファイルにバンドルします。このバンドルファイルはユーザーのマシン上でオンザフライで生成され、リポジトリにはコミットされません。 +- **GitHub 経由での `npx` 実行:** GitHub から最新バージョンの Qwen Code を直接実行する場合、`package.json` の `prepare` スクリプトによって別のプロセスが起動されます。このスクリプトは `esbuild` を使用して、アプリケーション全体とその依存関係を単一の自己完結型 JavaScript ファイルにバンドルします。このバンドルはユーザーのマシン上でオンザフライで作成され、リポジトリにはコミットされません。 **Docker サンドボックスイメージ** @@ -112,7 +111,7 @@ Docker ベースの実行方法は、`qwen-code-sandbox` コンテナイメー ## リリースプロセス -リリースプロセスは GitHub Actions を通じて自動化されています。リリースワークフローは以下のアクションを実行します： +リリースプロセスは GitHub Actions を通じて自動化されています。リリースワークフローでは以下のアクションが実行されます： 1. `tsc` を使用して NPM パッケージをビルドします。 2. NPM パッケージをアーティファクトレジストリに公開します。 diff --git a/website/content/ja/ide-integration.md b/website/content/ja/ide-integration.md index ebae654e..99f05581 100644 --- a/website/content/ja/ide-integration.md +++ b/website/content/ja/ide-integration.md @@ -1,23 +1,23 @@ # IDE Integration -Gemini CLI は、IDE との連携により、よりシームレスでコンテキストを意識した体験を提供できます。この連携により、CLI はワークスペースをより適切に理解し、エディタ内でのネイティブな diff 機能などの強力な機能が利用可能になります。 +Qwen Code は、IDE との連携により、よりシームレスでコンテキストを意識した体験を提供できます。この連携により、CLI はワークスペースをより適切に理解し、エディタ内でのネイティブな diff 機能などの強力な機能が利用可能になります。 -現在サポートされている IDE は [Visual Studio Code](https://code.visualstudio.com/) のみで、VS Code 拡張機能に対応する他のエディタも含まれます。 +現在サポートされている IDE は [Visual Studio Code](https://code.visualstudio.com/) および VS Code 拡張機能をサポートする他のエディタのみです。 ## 機能 -- **ワークスペースコンテキスト:** CLI は自動的にワークスペースの状況を把握し、より関連性が高く正確なレスポンスを提供します。このコンテキストには以下が含まれます： - - ワークスペース内で**最近アクセスした上位 10 個のファイル** - - 現在のカーソル位置 - - 選択中のテキスト（最大 16KB。それ以上は切り捨てられます） +- **ワークスペースコンテキスト:** CLIは自動的にワークスペースの状況を把握し、より関連性が高く正確なレスポンスを提供します。このコンテキストには以下が含まれます： + - ワークスペース内で**最近アクセスした上位10ファイル**。 + - 現在のカーソル位置。 + - 選択中のテキスト（最大16KBまで。それ以上は切り捨てられます）。 -- **ネイティブな差分表示:** Gemini がコード変更を提案する際、IDE のネイティブな diff ビューア内で直接変更内容を確認できます。これにより、提案された変更をシームレスにレビュー、編集、承認または拒否することが可能になります。 +- **ネイティブDiff表示:** Qwenがコード変更を提案する際、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`: 拡張機能のサードパーティ通知を表示します。 +- **VS Codeコマンド:** VS Codeのコマンドパレット（`Cmd+Shift+P` または `Ctrl+Shift+P`）から直接Qwen Codeの機能にアクセスできます： + - `Qwen Code: Run`: 統合ターミナルで新しいQwen Codeセッションを開始します。 + - `Qwen Code: Accept Diff`: アクティブなdiffエディタ内の変更を承認します。 + - `Qwen Code: Close Diff Editor`: 変更を拒否し、アクティブなdiffエディタを閉じます。 + - `Qwen Code: View Third-Party Notices`: 拡張機能のサードパーティ通知を表示します。 ## インストールとセットアップ @@ -25,28 +25,28 @@ IDE連携のセットアップには3つの方法があります： ### 1. 自動案内（推奨） -サポートされているエディタ内でGemini CLIを実行すると、環境が自動的に検出され、接続を促す案内が表示されます。「Yes」と答えることで、必要なセットアップが自動的に実行され、関連するextensionのインストールと接続の有効化が行われます。 +サポートされているエディタ内でQwen Codeを実行すると、自動的に環境を検出し、接続を促す案内が表示されます。「Yes」と答えることで、必要なセットアップが自動的に実行されます。これには、連携用拡張機能のインストールと接続の有効化が含まれます。 ### 2. CLIからの手動インストール -以前に案内を-dismissした場合や、手動でextensionをインストールしたい場合は、Gemini CLI内で以下のコマンドを実行できます： +以前に案内を閉じてしまった場合や、手動で拡張機能をインストールしたい場合は、Qwen Code内で以下のコマンドを実行してください： ``` /ide install ``` -このコマンドは、使用しているIDEに適したextensionを見つけ出してインストールします。 +このコマンドにより、ご利用の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) にも公開されています。お使いのエディタの手順に従って、このレジストリからエクステンションをインストールしてください。 +- **Visual Studio Codeの場合:** [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion) からインストールしてください。 +- **VS Codeのフォーク版の場合:** VS Codeのフォーク版をサポートするため、このエクステンションは[Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion)にも公開されています。お使いのエディタの指示に従って、このレジストリからエクステンションをインストールしてください。 -どのインストール方法を選んでも、インテグレーションが正しく有効化されるように、新しいターミナルウィンドウを開くことをおすすめします。インストールが完了したら、`/ide enable` を使って接続できます。 +どのインストール方法を選んでも、インテグレーションが正しく有効化されるように、新しいターミナルウィンドウを開くことを推奨します。インストールが完了したら、`/ide enable` を使用して接続できます。 -## 使い方 +## 使用方法 ### 有効化と無効化 @@ -61,48 +61,48 @@ CLI から IDE 連携をコントロールできます： /ide disable ``` -有効化すると、Gemini CLI は自動的に IDE companion extension への接続を試みます。 +有効にすると、Qwen Code は自動的に IDE companion extension への接続を試みます。 ### ステータスの確認 -接続ステータスを確認し、CLI が IDE から受け取ったコンテキストを表示するには、以下を実行します： +接続ステータスを確認し、CLI が IDE から受け取ったコンテキストを表示するには、以下を実行してください： ``` /ide status ``` -接続されている場合、このコマンドは接続先の IDE と、認識している最近開いたファイルのリストを表示します。 +接続されている場合、このコマンドは接続中の IDE と、認識している最近開いたファイルのリストを表示します。 -（注：ファイルリストはワークスペース内の最近アクセスした 10 個のファイルに制限されており、ローカルディスク上のファイルのみが含まれます。） +（注：ファイルリストはワークスペース内で最近アクセスした 10 個のファイルに限定され、ローカルディスク上のファイルのみが含まれます。） ### Diff との連携 Gemini にファイルの変更を依頼すると、エディタ内で直接 diff ビューを開くことができます。 -**diff を受け入れるには**、以下のいずれかの操作を行います： +**Diff を適用するには**、以下のいずれかの操作を行ってください： -- diff エディタのタイトルバーにある**チェックマークアイコン**をクリックする -- ファイルを保存する（例：`Cmd+S` または `Ctrl+S`） -- Command Palette を開き、**Gemini CLI: Accept Diff** を実行する -- CLI でプロンプトが表示されたら `yes` と応答する +- diff エディタのタイトルバーにある **チェックマークアイコン** をクリックする。 +- ファイルを保存する（例：`Cmd+S` または `Ctrl+S`）。 +- Command Palette を開き、**Qwen Code: Accept Diff** を実行する。 +- CLI でプロンプトが表示されたら `yes` と応答する。 -**diff を拒否するには**、以下の操作を行います： +**Diff を拒否するには**、以下の操作を行ってください： -- diff エディタのタイトルバーにある**'x' アイコン**をクリックする -- diff エディタのタブを閉じる -- Command Palette を開き、**Gemini CLI: Close Diff Editor** を実行する -- CLI でプロンプトが表示されたら `no` と応答する +- diff エディタのタイトルバーにある **'x' アイコン** をクリックする。 +- diff エディタのタブを閉じる。 +- Command Palette を開き、**Qwen Code: Close Diff Editor** を実行する。 +- CLI でプロンプトが表示されたら `no` と応答する。 -また、受け入れる前に diff ビュー内で**提案された変更を直接編集する**こともできます。 +また、適用前に diff ビュー内で **提案された変更を直接編集** することも可能です。 -CLI で「Yes, allow always」を選択すると、変更は IDE に表示されなくなり、自動的に受け入れられるようになります。 +CLI で「Yes, allow always」を選択すると、変更は IDE に表示されず、自動的に適用されるようになります。 ## サンドボックス環境での使用 -Gemini CLIをサンドボックス内で使用する場合、以下の点に注意してください： +Qwen Codeをサンドボックス内で使用する場合、以下の点に注意してください： -- **macOSの場合：** IDE連携機能は、IDE companion extensionと通信するためにネットワークアクセスを必要とします。ネットワークアクセスを許可するSeatbeltプロファイルを使用する必要があります。 -- **Dockerコンテナ内の場合：** Docker（またはPodman）コンテナ内でGemini CLIを実行する場合でも、ホストマシン上で動作しているVS Code extensionにIDE連携機能は接続できます。CLIは自動的に`host.docker.internal`上のIDEサーバーを見つけるように設定されています。通常、特別な設定は必要ありませんが、コンテナからホストへの接続を許可するようにDockerのネットワーク設定を確認する必要があるかもしれません。 +- **macOSの場合：** IDE連携機能は、IDE用のcompanion extensionと通信するためにネットワークアクセスが必要です。ネットワークアクセスを許可するSeatbeltプロファイルを使用する必要があります。 +- **Dockerコンテナ内の場合：** Docker（またはPodman）コンテナ内でQwen Codeを実行する場合でも、ホストマシン上で動作しているVS Code extensionにIDE連携機能は接続可能です。CLIは自動的に`host.docker.internal`上のIDEサーバーを見つけられるように設定されています。通常は特別な設定は必要ありませんが、コンテナからホストへの接続を許可するようにDockerのネットワーク設定を調整する必要があるかもしれません。 ## トラブルシューティング @@ -111,31 +111,31 @@ 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 が起動していないか、正しく初期化されていないことを意味します。 + - **原因:** Qwen Code が IDE に接続するために必要な環境変数（`QWEN_CODE_IDE_WORKSPACE_PATH` または `QWEN_CODE_IDE_SERVER_PORT`）を見つけられませんでした。これは通常、IDE companion extension が実行されていないか、正しく初期化されていないことを意味します。 - **解決方法:** - 1. IDE に **Gemini CLI Companion** extension がインストールされていて、有効になっていることを確認してください。 - 2. 新しい terminal window を IDE で開き、正しい環境変数が読み込まれるようにしてください。 + 1. IDE に **Qwen Code Companion** extension がインストールされており、有効になっていることを確認してください。 + 2. 正しい環境変数を取得するために、IDE で新しい terminal ウィンドウを開いてください。 - **メッセージ:** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` - **原因:** IDE companion への接続が失われました。 - - **解決方法:** `/ide enable` を実行して再接続を試みてください。問題が続く場合は、新しい terminal window を開くか、IDE を再起動してください。 + - **解決方法:** `/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.` +- **メッセージ:** `🔴 Disconnected: Directory mismatch. Qwen Code is running in a different location than the open workspace in [IDE Name]. Please run the CLI from the same directory as your project's root folder.` - **原因:** CLIの現在の作業ディレクトリが、IDEで開いているフォルダまたはワークスペースとは異なる場所にある。 - **解決方法:** 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で単一のプロジェクトフォルダを開き、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 を実行してください。 +- **メッセージ:** `IDE integration is not supported in your current environment. To use this feature, run Qwen Code in one of these supported IDEs: [List of IDEs]` + - **原因:** 現在の環境（ターミナルなど）は、サポートされている IDE ではない。 + - **解決方法:** VS Code などの対応 IDE に内蔵されているターミナルから Qwen Code を実行してください。 - **メッセージ:** `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 + - **原因:** `/ide install` を実行したが、使用している IDE に対して CLI による自動インストールがサポートされていない。 + - **解決方法:** 利用している IDE の拡張機能マーケットプレイスを開き、「Qwen Code Companion」を検索して手動でインストールしてください。 \ No newline at end of file diff --git a/website/content/ja/index.md b/website/content/ja/index.md index 32a5797b..3e2ef944 100644 --- a/website/content/ja/index.md +++ b/website/content/ja/index.md @@ -1,39 +1,40 @@ # Qwen Code ドキュメントへようこそ -このドキュメントでは、Qwen Code のインストール、使用方法、開発に関する包括的なガイドを提供します。このツールを使うと、コマンドラインインターフェース (CLI) を通じて AI モデルとやり取りできます。 +このドキュメントでは、Qwen Code のインストール、使用方法、開発に関する包括的なガイドを提供します。このツールを使うと、コマンドラインインターフェースを通じて AI モデルとやり取りできます。 ## 概要 -Qwen Code は、高度なコードモデルの機能をあなたのターミナルに持ち込み、インタラクティブな Read-Eval-Print Loop (REPL) 環境で利用可能にします。Qwen Code は、ローカルサーバー (`packages/core`) と通信するクライアントサイドアプリケーション (`packages/cli`) で構成されています。また、Qwen Code には、ファイルシステム操作、シェルの実行、Web リクエストなどを行うためのさまざまなツールが含まれており、これらは `packages/core` によって管理されています。 +Qwen Code は、高度なコードモデルの機能を対話型の Read-Eval-Print Loop (REPL) 環境でターミナルに持ち込みます。Qwen Code は、ローカルサーバー（`packages/core`）と通信するクライアントサイドアプリケーション（`packages/cli`）で構成されています。また、Qwen Code には、ファイルシステム操作、シェルの実行、Web リクエストなどを行うためのさまざまなツールが含まれており、これらは `packages/core` によって管理されています。 ## ドキュメントのナビゲーション -このドキュメントは以下のセクションに整理されています： +このドキュメントは以下のセクションに分かれています： - **[実行とデプロイ](./deployment.md)：** Qwen Code を実行するための情報。 - **[アーキテクチャ概要](./architecture.md)：** コンポーネントとその相互作用を含む、Qwen Code の高レベル設計を理解します。 -- **CLI の使用方法：** `packages/cli` のドキュメント。 - - **[CLI の紹介](./cli/index.md)：** コマンドラインインターフェースの概要。 - - **[コマンド一覧](./cli/commands.md)：** 利用可能な CLI コマンドの説明。 +- **CLI Usage：** `packages/cli` のドキュメント。 + - **[CLI イントロダクション](./cli/index.md)：** コマンドラインインターフェースの概要。 + - **[コマンド](./cli/commands.md)：** 利用可能な CLI コマンドの説明。 - **[設定](./cli/configuration.md)：** CLI の設定に関する情報。 - **[チェックポイント](./checkpointing.md)：** チェックポイント機能のドキュメント。 - **[拡張機能](./extension.md)：** 新しい機能で CLI を拡張する方法。 - **[IDE との連携](./ide-integration.md)：** CLI をエディタに接続する方法。 - **[テレメトリ](./telemetry.md)：** CLI 内のテレメトリの概要。 -- **コアの詳細：** `packages/core` のドキュメント。 - - **[コアの紹介](./core/index.md)：** コアコンポーネントの概要。 +- **Core Details：** `packages/core` のドキュメント。 + - **[Core イントロダクション](./core/index.md)：** コアコンポーネントの概要。 - **[Tools API](./core/tools-api.md)：** コアがツールを管理・公開する方法に関する情報。 -- **ツール：** +- **Tools：** - **[ツールの概要](./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)：** 設定、ビルド、テスト、コーディング規則など、貢献者および開発者向けの情報。 +- **[サブエージェント](./subagents.md)：** 専門的なタスクに対応した AI アシスタントで、包括的な管理・設定・使用方法を提供します。 +- **[貢献と開発ガイド](../CONTRIBUTING.md)：** 貢献者および開発者のための情報。セットアップ、ビルド、テスト、コーディング規則などを含みます。 - **[NPM Workspaces とパブリッシュ](./npm.md)：** プロジェクトのパッケージがどのように管理・公開されているかの詳細。 -- **[トラブルシューティングガイド](./troubleshooting.md)：** よくある問題と FAQ の解決方法。 +- **[トラブルシューティングガイド](./troubleshooting.md)：** 一般的な問題や FAQ の解決策を見つけます。 - **[利用規約およびプライバシー通知](./tos-privacy.md)：** Qwen Code の利用に適用される利用規約およびプライバシー通知に関する情報。 -このドキュメントが、Qwen Code を最大限に活用するお手伝いができることを願っています！ \ No newline at end of file +このドキュメントがあなたが Qwen Code を最大限に活用するお手伝いができることを願っています！ \ No newline at end of file diff --git a/website/content/ja/keyboard-shortcuts.md b/website/content/ja/keyboard-shortcuts.md index a1cd0fd0..f740313d 100644 --- a/website/content/ja/keyboard-shortcuts.md +++ b/website/content/ja/keyboard-shortcuts.md @@ -4,22 +4,22 @@ ## 一般 -| ショートカット | 説明 | -| -------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `Esc` | ダイアログやサジェストを閉じる。 | -| `Ctrl+C` | アプリケーションを終了する。確認のために2回押す。 | -| `Ctrl+D` | 入力が空の場合にアプリケーションを終了する。確認のために2回押す。 | -| `Ctrl+L` | 画面をクリアする。 | -| `Ctrl+O` | デバッグコンソールの表示を切り替える。 | -| `Ctrl+S` | 長いレスポンスを完全に表示できるようにし、切り捨てを無効にする。端末のスクロールバックを使用して 전체出力を表示する。 | -| `Ctrl+T` | ツールの説明表示を切り替える。 | -| `Ctrl+Y` | すべてのツール呼び出しに対して自動承認（YOLOモード）を切り替える。 | +| ショートカット | 説明 | +| -------- | --------------------------------------------------------------------------------------------------------------------- | +| `Esc` | ダイアログとサジェストを閉じる。 | +| `Ctrl+C` | 進行中のリクエストをキャンセルし、入力をクリアする。2回押すとアプリケーションを終了する。 | +| `Ctrl+D` | 入力が空の場合、アプリケーションを終了する。2回押して確認する。 | +| `Ctrl+L` | 画面をクリアする。 | +| `Ctrl+O` | デバッグコンソールの表示を切り替える。 | +| `Ctrl+S` | 長いレスポンスを完全に表示できるようにし、切り捨てを無効にする。端末のスクロールバックを使用して 전체出力を表示する。 | +| `Ctrl+T` | ツールの説明表示を切り替える。 | +| `Ctrl+Y` | すべてのツール呼び出しに対して自動承認（YOLOモード）を切り替える。 | ## 入力プロンプト | ショートカット | 説明 | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `!` | 入力が空の場合にシェルモードを切り替える。 | +| `!` | 入力が空のときにシェルモードを切り替える。 | | `\` (行末) + `Enter` | 改行を挿入する。 | | `Down Arrow` | 入力履歴を下に移動する。 | | `Enter` | 現在のプロンプトを送信する。 | @@ -27,19 +27,19 @@ | `Tab` | サジェストがある場合は、現在のサジェストを自動補完する。 | | `Up Arrow` | 入力履歴を上に移動する。 | | `Ctrl+A` / `Home` | カーソルを行頭に移動する。 | -| `Ctrl+B` / `Left Arrow` | カーソルを1文字左に移動する。 | +| `Ctrl+B` / `Left Arrow` | カーソルを左に1文字移動する。 | | `Ctrl+C` | 入力プロンプトをクリアする。 | | `Ctrl+D` / `Delete` | カーソルの右側の文字を削除する。 | | `Ctrl+E` / `End` | カーソルを行末に移動する。 | -| `Ctrl+F` / `Right Arrow` | カーソルを1文字右に移動する。 | +| `Ctrl+F` / `Right Arrow` | カーソルを右に1文字移動する。 | | `Ctrl+H` / `Backspace` | カーソルの左側の文字を削除する。 | | `Ctrl+K` | カーソル位置から行末までを削除する。 | -| `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B` | カーソルを1単語左に移動する。 | +| `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B` | カーソルを左に1単語移動する。 | | `Ctrl+N` | 入力履歴を下に移動する。 | | `Ctrl+P` | 入力履歴を上に移動する。 | -| `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F` | カーソルを1単語右に移動する。 | +| `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F` | カーソルを右に1単語移動する。 | | `Ctrl+U` | カーソル位置から行頭までを削除する。 | -| `Ctrl+V` | クリップボードの内容をペーストする。クリップボードに画像が含まれている場合、画像は保存され、その参照がプロンプトに挿入される。 | +| `Ctrl+V` | クリップボードの内容を貼り付ける。クリップボードに画像が含まれている場合、画像は保存され、その参照がプロンプトに挿入される。 | | `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace` | カーソルの左側の単語を削除する。 | | `Ctrl+X` / `Meta+Enter` | 現在の入力を外部エディタで開く。 | @@ -51,12 +51,18 @@ | `Tab` / `Enter` | 選択中のサジェストを確定する | | `Up Arrow` | サジェストを上に移動する | -## ラジオボタン選択 +## Radio Button Select -| ショートカット | 説明 | -| ------------------ | ------------------------------------------------------------------------------------------------------ | -| `Down Arrow` / `j` | 選択を下に移動します。 | -| `Enter` | 選択を確定します。 | -| `Up Arrow` / `k` | 選択を上に移動します。 | -| `1-9` | 番号でアイテムを選択します。 | -| (複数桁) | 9より大きい番号のアイテムについては、対応するアイテムを選択するために素早く連続して数字キーを押してください。 | \ No newline at end of file +| Shortcut | Description | +| ------------------ | ------------------------------------------------------------------------------------------------------------- | +| `Down Arrow` / `j` | 選択を下に移動する。 | +| `Enter` | 選択を確定する。 | +| `Up Arrow` / `k` | 選択を上に移動する。 | +| `1-9` | 番号でアイテムを選択する。 | +| (multi-digit) | 9より大きい番号のアイテムについては、対応するアイテムを選択するために素早く連続して数字キーを押してください。 | + +## IDE 連携 + +| ショートカット | 説明 | +| -------------- | ------------------------------- | +| `Ctrl+G` | IDE から受け取った context CLI を表示 | \ No newline at end of file diff --git a/website/content/ja/npm.md b/website/content/ja/npm.md index 26d572fc..faf8fd02 100644 --- a/website/content/ja/npm.md +++ b/website/content/ja/npm.md @@ -6,17 +6,17 @@ これは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`を含むすべてのパッケージ依存関係が含まれます。つまり、ユーザーが`npm install -g @qwen-code/qwen-code`でパッケージをインストールしても、`npx @qwen-code/qwen-code`で直接実行しても、この単一の自己完結型実行ファイルを使用することになります。 ## `@qwen-code/qwen-code-core` このパッケージには、CLI のコアロジックが含まれています。設定されたプロバイダーへの API リクエストの実行、認証の処理、ローカルキャッシュの管理を担当します。 -このパッケージはバンドルされません。公開される際は、独自の依存関係を持つ標準的な Node.js パッケージとして公開されます。これにより、必要に応じて他のプロジェクトでスタンドアロンパッケージとして使用できます。`dist` フォルダー内のすべてのトランスパイルされた JS コードはパッケージに含まれています。 +このパッケージはバンドルされていません。パブリッシュ時には、独自の依存関係を持つ標準的な Node.js パッケージとしてパブリッシュされます。これにより、必要に応じて他のプロジェクトでスタンドアロンパッケージとして使用できます。`dist` フォルダー内のすべてのトランスパイルされた js コードがパッケージに含まれています。 # リリースプロセス -このプロジェクトでは、すべてのパッケージが正しくバージョン管理および公開されるように、構造化されたリリースプロセスに従っています。このプロセスは、可能な限り自動化されるように設計されています。 +このプロジェクトでは、すべてのパッケージが正しくバージョン管理およびパブリッシュされるように、構造化されたリリースプロセスに従っています。このプロセスは、可能な限り自動化されるように設計されています。 ## リリース方法 @@ -25,7 +25,7 @@ 1. リポジトリの **Actions** タブに移動します。 2. リストから **Release** ワークフローを選択します。 3. **Run workflow** ドロップダウンボタンをクリックします。 -4. 必要な入力項目を記入します： +4. 必要な入力項目を埋めます： - **Version**: リリースする正確なバージョン（例: `v0.2.1`）。 - **Ref**: リリース元のブランチまたはコミット SHA（デフォルトは `main`）。 - **Dry Run**: ワークフローをテストのみで実行する場合は `true` のままにし、本番リリースする場合は `false` に設定します。 @@ -37,22 +37,22 @@ ### プロセス -毎日 UTC の真夜中（深夜 0 時）に、[Release workflow](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml) がスケジュールに基づいて自動実行されます。このワークフローでは以下のステップが実行されます： +毎日UTCの真夜中（日本時間では午前9時）に、[Release workflow](https://github.com/QwenLM/qwen-code/actions/workflows/release.yml)がスケジュールに従って自動実行されます。このワークフローは以下のステップを実行します： -1. `main` ブランチから最新のコードをチェックアウトします。 -2. すべての依存パッケージをインストールします。 -3. `preflight` チェックと統合テストをすべて実行します。 -4. すべてのテストに成功した場合、次の nightly バージョン番号を計算します（例：`v0.2.1-nightly.20230101`）。 -5. パッケージをビルドし、`nightly` dist-tag 付きで npm に公開します。 -6. 最後に、nightly バージョンに対応する GitHub Release を作成します。 +1. `main`ブランチから最新のコードをチェックアウトします。 +2. すべての依存関係をインストールします。 +3. `preflight`チェックと統合テストの全スイートを実行します。 +4. すべてのテストが成功した場合、次のnightlyバージョン番号を計算します（例：`v0.2.1-nightly.20230101`）。 +5. パッケージをビルドし、`nightly` dist-tagでnpmに公開します。 +6. 最後に、nightlyバージョンのGitHub Releaseを作成します。 -### エラー発生時の処理 +### エラー処理 -nightly ワークフローのいずれかのステップが失敗した場合、リポジトリ内に新しい issue が自動で作成されます。この issue には `bug` および `nightly-failure` のラベルが付与され、失敗したワークフロー実行へのリンクが含まれるため、デバッグが容易になります。 +nightlyワークフローのいずれかのステップが失敗した場合、リポジトリに新しいissueが自動的に作成され、`bug`と`nightly-failure`のラベルが付与されます。このissueには、簡単にデバッグできるように失敗したワークフロー実行へのリンクが含まれます。 ### Nightly Build の使い方 -最新の Nightly Build をインストールするには、`@nightly` タグを使用してください： +最新の Nightly Build をインストールするには、`@nightly` タグを使用します： ```bash npm install -g @qwen-code/qwen-code@nightly @@ -60,62 +60,65 @@ npm install -g @qwen-code/qwen-code@nightly また、[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) で進行状況を確認できます。完了したら以下の手順を行ってください： +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 Patch および Hotfix リリースは main にマージバックする +### Stable Patch および Hotfix のための Merge Back -Stable patch や hotfix リリースでは、ほぼ必ず `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 にマージするための pull request を作成してください。この 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` にマージしません。 +通常、プレリリース用の release branch は `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）は、定義上、不安定で一時的なものです。main ブランチの履歴にリリース候補版のためのバージョン更新を多数含めたくはありません。main の package.json には RC ではなく、最新の stable リリースバージョンを反映させるべきです。 +- プロセス：release-v1.3.0-rc.1 ブランチを作成し、`npm publish --tag rc` を実行したら、そのブランチの役目は終わりです。そのまま削除して問題ありません。RC のコードはすでに main（または feature ブランチ）に存在しているため、機能的なコードは失われません。release ブランチはバージョン番号を扱うための一時的な手段にすぎません。 ## ローカルでのテストと検証：パッケージングおよび公開プロセスの変更 -実際に 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 レジストリに実際にパッケージを公開せずに、公開プロセスをシミュレートできます。 +変更を検証するには、公開プロセスのドライランを実行できます。これにより、npm レジストリに実際にパッケージを公開せずに、公開プロセスをシミュレートできます。 ```bash npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME="thename" npm run publish:npm --dry-run @@ -128,60 +131,63 @@ 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/qwen-code-0.1.6.tgz`）。 ドライランを実行することで、パッケージングプロセスへの変更が正しいことを確認し、パッケージが正常に公開されることに自信を持てるようになります。 -## リリースの詳細 +## Release Deep Dive -リリースプロセスの主な目的は、`packages/` ディレクトリにあるソースコードをビルドし、プロジェクトのルートに一時的な `bundle` ディレクトリを作成して、クリーンで自己完結型のパッケージをアセンブルすることです。実際に NPM に公開されるのはこの `bundle` ディレクトリの中身です。 +リリースプロセスの主な目的は、`packages/` ディレクトリ内のソースコードをビルドし、プロジェクトのルートに一時的な `bundle` ディレクトリを作成して、クリーンで自己完結型のパッケージをアセンブルすることです。実際に NPM に publish されるのはこの `bundle` ディレクトリの中身です。 以下が主なステージです： -### ステージ 1: リリース前の健全性チェックとバージョン管理 +### Stage 1: リリース前の健全性チェックとバージョニング -- **処理内容**: ファイルを移動する前に、プロジェクトが正常な状態であることを確認します。これにはテスト、lint、型チェック（`npm run preflight`）が含まれます。ルートの `package.json` と `packages/cli/package.json` のバージョン番号が新しいリリースバージョンに更新されます。 -- **目的**: 高品質で動作するコードのみがリリースされるように保証します。バージョン管理は新しいリリースを示す最初のステップです。 +- **処理内容**: ファイルを移動する前に、プロジェクトが正常な状態にあることを確認します。これにはテスト、lint、型チェック（`npm run preflight`）が含まれます。ルートの `package.json` と `packages/cli/package.json` のバージョン番号が新しいリリースバージョンに更新されます。 +- **目的**: 高品質で動作するコードのみがリリースされるように保証します。バージョンの更新は新しいリリースの開始を示す最初のステップです。 -### ステージ 2: ソースコードのビルド +### Stage 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 に変換する必要があります。`cli` パッケージが `core` パッケージに依存しているため、`core` パッケージが最初にビルドされます。 +- **目的**: 開発中に書かれた TypeScript コードは、Node.js で実行できるプレーンな JavaScript に変換する必要があります。`cli` パッケージが `core` パッケージに依存しているため、まず `core` パッケージがビルドされます。 + +### Stage 3: 最終的な publish 用パッケージのアセンブル + +これはファイルが最終的な publish 用の状態に変換・移動される最も重要なステージです。プロジェクトのルートに一時的な `bundle` フォルダが作成され、最終的なパッケージコンテンツが配置されます。 -### ステージ 3: 最終的な公開パッケージのアセンブル +#### 1. `package.json` の変換 -これはファイルが最終的な公開形式に変換・移動される最も重要なステージです。プロジェクトのルートに一時的な `bundle` フォルダが作成され、最終的なパッケージの内容が格納されます。 +- **処理内容**: `packages/cli/` にある `package.json` が読み込まれ、変更され、ルートの `bundle/` ディレクトリに書き込まれます。 +- **ファイルの移動**: `packages/cli/package.json` → （メモリ内変換）→ `bundle/package.json` +- **目的**: 最終的な `package.json` は開発中に使用していたものとは異なる必要があります。主な変更点は以下の通りです： + - `devDependencies` を削除 + - ワークスペース固有の依存関係 `"dependencies": { "@qwen-code/core": "workspace:*" }` を削除し、core コードが最終的な JavaScript ファイルに直接バンドルされるようにする + - `bin`、`main`、`files` フィールドが最終的なパッケージ構造内の正しい場所を指すようにする -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 バンドルの作成 -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 上の別々の依存関係として保持する必要がなくなり、コードが直接含まれるため、パッケージが簡潔になります。 +- **処理内容**: `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 のサンドボックス機能が機能するために必要な重要な実行時アセットです。最終的な実行ファイルの隣に配置する必要があります。 +#### 3. 静的ファイルとサポートファイルのコピー + +- **処理内容**: ソースコードの一部ではないが、パッケージが正しく動作したり適切に説明されたりするために必要な重要なファイルが `bundle` ディレクトリにコピーされます。 +- **ファイルの移動**: + - `README.md` → `bundle/README.md` + - `LICENSE` → `bundle/LICENSE` + - `packages/cli/src/utils/*.sb`（サンドボックスプロファイル）→ `bundle/` +- **目的**: + - `README.md` と `LICENSE` は、どの NPM パッケージにも含めるべき標準的なファイルです。 + - サンドボックスプロファイル（.sb ファイル）は CLI のサンドボックス機能が動作するために必要な重要なランタイムアセットです。最終的な実行ファイルの隣に配置される必要があります。 -### ステージ 4: NPM への公開 +### Stage 4: NPM への publish - **処理内容**: ルートの `bundle` ディレクトリ内で `npm publish` コマンドが実行されます。 -- **目的**: `bundle` ディレクトリ内から `npm publish` を実行することで、ステージ 3 で慎重にアセンブルしたファイルのみが NPM レジストリにアップロードされます。これにより、ソースコード、テストファイル、開発設定などが誤って公開されるのを防ぎ、ユーザー向けにクリーンで最小限のパッケージを提供できます。 +- **目的**: `bundle` ディレクトリ内から `npm publish` を実行することで、Stage 3 で慎重にアセンブルしたファイルのみが NPM レジストリにアップロードされます。これにより、ソースコード、テストファイル、開発用設定などが誤って publish されるのを防ぎ、ユーザー向けにクリーンで最小限のパッケージを提供できます。 ## ファイルフローの概要 @@ -219,7 +225,7 @@ graph TD J --> G --> K ``` -このプロセスにより、最終的に公開されるアーティファクトは、開発ワークスペースの直接的なコピーではなく、プロジェクトのためだけに構築されたクリーンで効率的な表現になります。 +このプロセスにより、最終的に publish されるアーティファクトは、開発ワークスペースの直接的なコピーではなく、プロジェクトのためだけにビルドされたクリーンで効率的な表現となることが保証されます。 ## NPM Workspaces @@ -239,6 +245,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 はパッケージ間の symlink を自動的に作成します。これにより、あるパッケージに変更を加えると、そのパッケージに依存する他のパッケージからすぐにその変更を利用できるようになります。 +- **スクリプト実行の簡素化**: プロジェクトのルートから `--workspace` フラグを使って、任意のパッケージ内のスクリプトを実行できます。例えば、`cli` パッケージ内の `build` スクリプトを実行するには、`npm run build --workspace @qwen-code/qwen-code` を実行します。 \ No newline at end of file diff --git a/website/content/ja/subagents.md b/website/content/ja/subagents.md new file mode 100644 index 00000000..ff4d42bd --- /dev/null +++ b/website/content/ja/subagents.md @@ -0,0 +1,467 @@ +# サブエージェント + +サブエージェントは、Qwen Code 内で特定のタスクを処理するための専門的な AI アシスタントです。タスクに特化したプロンプト、ツール、および動作で構成された AI エージェントに、特定の作業を委任することができます。 + +## サブエージェントとは？ + +サブエージェントとは、以下のような特徴を持つ独立した AI アシスタントです： + +- **特定のタスクに特化** - 各サブエージェントは、特定の作業向けに特化したシステムプロンプトで構成されています +- **独立したコンテキストを持つ** - メインチャットとは別に、独自の会話履歴を保持します +- **制御されたツールを使用** - 各サブエージェントが利用できるツールを個別に設定できます +- **自律的に動作** - タスクを割り当てられると、完了または失敗するまで独立して動作します +- **詳細なフィードバックを提供** - 進行状況、ツールの使用状況、実行統計をリアルタイムで確認できます + +## 主要なメリット + +- **タスクの専門化**: 特定のワークフロー（テスト、ドキュメント作成、リファクタリングなど）に最適化されたエージェントを作成 +- **コンテキストの分離**: 専門的な作業をメインの会話から分離して管理 +- **再利用性**: エージェント設定をプロジェクトやセッション間で保存・再利用 +- **アクセス制御**: 各エージェントが使用できるツールを制限し、セキュリティと集中力を確保 +- **進捗の可視化**: リアルタイムの進捗更新でエージェントの実行状況を監視 + +## サブエージェントの仕組み + +1. **設定**: 振る舞い、ツール、システムプロンプトを定義したサブエージェント設定を作成 +2. **委譲**: メインAIが適切なサブエージェントにタスクを自動的に委譲 +3. **実行**: サブエージェントが独立して動作し、設定されたツールを使ってタスクを完了 +4. **結果**: 結果と実行サマリーをメインの会話に戻す + +## はじめに + +### クイックスタート + +1. **最初のサブエージェントを作成する**: + + ``` + /agents create + ``` + + ガイド付きウィザードに従って、専門的なエージェントを作成します。 + +2. **既存のエージェントを管理する**: + + ``` + /agents manage + ``` + + 設定済みのサブエージェントを表示・管理できます。 + +3. **サブエージェントを自動的に使用する**: + メインのAIに、サブエージェントの専門領域に合致するタスクを依頼するだけです。AIが自動的に適切な作業を委譲します。 + +### 使用例 + +``` +User: "認証モジュールの包括的なテストを書いてください" + +AI: これをテスト専門のサブエージェントに委譲します。 +[Delegates to "testing-expert" subagent] +[テスト作成のリアルタイム進捗を表示] +[完了したテストファイルと実行サマリを返却] +``` + +## 管理 + +### CLI コマンド + +サブエージェントは、`/agents` スラッシュコマンドおよびそのサブコマンドを通じて管理されます： + +#### `/agents create` + +ガイド付きステップ・ウィザードで新しいサブエージェントを作成します。 + +**使用方法:** + +``` +/agents create +``` + +#### `/agents manage` + +既存のサブエージェントを表示・管理するためのインタラクティブな管理ダイアログを開きます。 + +**使用方法:** + +``` +/agents manage +``` + +### 保存場所 + +サブエージェントは以下の2つの場所に Markdown ファイルとして保存されます： + +- **プロジェクトレベル**: `.qwen/agents/`（優先） +- **ユーザーレベル**: `~/.qwen/agents/`（フォールバック） + +これにより、プロジェクト固有のエージェントと、すべてのプロジェクトで使用できる個人用エージェントの両方を持つことができます。 + +### ファイル形式 + +サブエージェントは、YAML frontmatter を含む Markdown ファイルを使用して設定されます。この形式は人間が読みやすく、任意のテキストエディタで簡単に編集できます。 + +#### 基本構造 + +```markdown +--- +name: agent-name +description: このエージェントを使用するタイミングと方法の簡単な説明 +tools: tool1, tool2, tool3 # 任意 +--- + +システムプロンプトの内容をここに記述します。 +複数の段落に対応しています。 +動的なコンテンツには ${variable} 形式のテンプレートを使用できます。 +``` + +#### 使用例 + +```markdown +--- +name: project-documenter +description: プロジェクトのドキュメントとREADMEファイルを作成 +--- + +あなたは${project_name}プロジェクトのドキュメントスペシャリストです。 + +あなたのタスク: ${task_description} + +作業ディレクトリ: ${current_directory} +生成日時: ${timestamp} + +新しいコントリビューターとエンドユーザーの両方がプロジェクトを理解できるような、 +明確で包括的なドキュメントを作成することに重点を置いてください。 +``` + +## 例 + +### 開発ワークフロー Agents + +#### Testing Specialist + +包括的なテスト作成とテスト駆動開発（TDD）に最適です。 + +```markdown +--- +name: testing-expert +description: 網羅的なユニットテスト、結合テストを作成し、ベストプラクティスに基づいたテスト自動化を実施 +tools: read_file, write_file, read_many_files, run_shell_command +--- + +あなたは高品質で保守性の高いテストを作成することに特化したテストスペシャリストです。 + +専門知識には以下が含まれます： + +- 適切なモックと分離によるユニットテスト +- コンポーネント間の相互作用を検証する結合テスト +- テスト駆動開発（TDD）のプラクティス +- エッジケースの特定と網羅的なテストカバレッジ +- 必要に応じたパフォーマンステストと負荷テスト + +各テストタスクに対して以下の手順を実施します： + +1. コード構造と依存関係を分析 +2. 主要機能、エッジケース、エラー条件を特定 +3. 説明的な名前を持つ網羅的なテストスイートを作成 +4. 適切なセットアップ／ティアダウンと意味のあるアサーションを含める +5. 複雑なテストシナリオを説明するコメントを追加 +6. テストが保守可能であり、DRY原則に従っていることを確認 + +常に検出された言語とフレームワークに適したテストのベストプラクティスに従ってください。 +正常系と異常系の両方のテストケースに焦点を当ててください。 +``` + +**Use Cases:** + +- "認証サービスのユニットテストを書く" +- "支払い処理ワークフローの結合テストを作成する" +- "データ検証モジュールのエッジケースに対するテストカバレッジを追加する" + +#### Documentation Writer + +明確で包括的なドキュメント作成を専門に行います。 + +```markdown +--- +name: documentation-writer +description: 包括的なドキュメント、READMEファイル、APIドキュメント、ユーザーガイドを作成します +tools: read_file, write_file, read_many_files, web_search +--- + +あなたは${project_name}の技術ドキュメントスペシャリストです。 + +あなたの役割は、開発者とエンドユーザーの両方に役立つ、明確で包括的なドキュメントを作成することです。以下の点に重点を置いてください： + +**APIドキュメント向け：** + +- サンプル付きの明確なエンドポイント説明 +- 型と制約付きのパラメータ詳細 +- レスポンス形式のドキュメント +- エラーコードの説明 +- 認証要件 + +**ユーザードキュメント向け：** + +- 必要に応じてスクリーンショット付きのステップバイステップ説明 +- インストールとセットアップガイド +- 設定オプションとサンプル +- 一般的な問題に対するトラブルシューティングセクション +- 一般的なユーザー質問に基づいたFAQセクション + +**開発者ドキュメント向け：** + +- アーキテクチャ概要と設計判断 +- 実際に動作するコード例 +- コントリビューションガイドライン +- 開発環境のセットアップ + +常にコード例を検証し、ドキュメントが実際の実装と同期していることを確認してください。明確な見出し、箇条書き、サンプルを使用してください。 +``` + +**ユースケース：** + +- "ユーザー管理エンドポイントのAPIドキュメントを作成" +- "このプロジェクトの包括的なREADMEを書く" +- "トラブルシューティング手順付きでデプロイメントプロセスをドキュメント化" + +#### Code Reviewer + +コードの品質、セキュリティ、およびベストプラクティスに焦点を当てたレビューを行う。 + +```markdown +--- +name: code-reviewer +description: ベストプラクティス、セキュリティ問題、パフォーマンス、および保守性の観点からコードをレビューします +tools: read_file, read_many_files +--- + +あなたは品質、セキュリティ、保守性にフォーカスした経験豊富なコードレビュアーです。 + +レビュー基準: + +- **コード構造**: オーガニゼーション、モジュール性、関心の分離 +- **パフォーマンス**: アルゴリズムの効率性とリソース使用量 +- **セキュリティ**: 脆弱性評価とセキュアコーディングプラクティス +- **ベストプラクティス**: 言語/フレームワーク固有の規約 +- **エラーハンドリング**: 適切な例外処理とエッジケースのカバレッジ +- **可読性**: 明確な命名、コメント、コード構成 +- **テスト**: テストカバレッジとテスト容易性の考慮事項 + +以下の形式で建設的なフィードバックを提供してください: + +1. **重大な問題**: セキュリティ脆弱性、重大なバグ +2. **重要な改善点**: パフォーマンス問題、設計上の問題 +3. **軽微な提案**: スタイル改善、リファクタリングの機会 +4. **肯定的なフィードバック**: よく実装されたパターンと良いプラクティス + +具体的な例と提案された解決策を含む、実行可能なフィードバックに焦点を当ててください。 +影響度で問題の優先順位を付け、推奨事項の根拠を提供してください。 +``` + +**Use Cases:** + +- "この認証実装のセキュリティ問題をレビューしてください" +- "このデータベースクエリロジックのパフォーマンスへの影響をチェックしてください" +- "コード構造を評価し、改善点を提案してください" + +### 技術固有のエージェント + +#### React Specialist + +React 開発、hooks、コンポーネントパターンに最適化されています。 + +```markdown +--- +name: react-specialist +description: React 開発、hooks、コンポーネントパターン、および最新の React ベストプラクティスのエキスパート +tools: read_file, write_file, read_many_files, run_shell_command +--- + +あなたは最新の React 開発に精通した React スペシャリストです。 + +専門知識の範囲： + +- **Component Design**: 関数コンポーネント、カスタムフック、コンポジションパターン +- **State Management**: useState、useReducer、Context API、外部ライブラリ +- **Performance**: React.memo、useMemo、useCallback、コード分割 +- **Testing**: React Testing Library、Jest、コンポーネントテスト戦略 +- **TypeScript Integration**: props、hooks、コンポーネントの適切な型付け +- **Modern Patterns**: Suspense、Error Boundaries、Concurrent Features + +React のタスクでは： + +1. デフォルトで関数コンポーネントと hooks を使用 +2. 適切な TypeScript の型付けを実装 +3. React のベストプラクティスと規約に従う +4. パフォーマンスへの影響を考慮 +5. 適切なエラーハンドリングを含める +6. テスト可能で保守性の高いコードを書く + +常に最新の React ベストプラクティスを維持し、非推奨のパターンは避けてください。 +アクセシビリティとユーザーエクスペリエンスの考慮に重点を置いてください。 +``` + +**Use Cases:** + +- "ソートとフィルタリング機能付きの再利用可能なデータテーブルコンポーネントを作成" +- "キャッシング機能付きの API データ取得用カスタムフックを実装" +- "このクラスコンポーネントを最新の React パターンにリファクタリング" + +#### Python Expert + +Python 開発、フレームワーク、およびベストプラクティスの専門家。 + +```markdown +--- +name: python-expert +description: Python 開発、フレームワーク、テスト、および Python 固有のベストプラクティスのエキスパート +tools: read_file, write_file, read_many_files, run_shell_command +--- + +あなたは Python エコシステムについて深い知識を持つ Python のエキスパートです。 + +あなたの専門知識には以下が含まれます： + +- **Core Python**: Pythonic なパターン、データ構造、アルゴリズム +- **Frameworks**: Django, Flask, FastAPI, SQLAlchemy +- **Testing**: pytest, unittest, モッキング、テスト駆動開発 +- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks +- **Async Programming**: asyncio, async/await パターン +- **Package Management**: pip, poetry, 仮想環境 +- **Code Quality**: PEP 8, 型ヒント、pylint/flake8 による linting + +Python のタスクにおいて： + +1. PEP 8 スタイルガイドラインに従う +2. コードのドキュメント化のために型ヒントを使用する +3. 特定の例外による適切なエラーハンドリングを実装する +4. 包括的な docstring を書く +5. パフォーマンスとメモリ使用量を考慮する +6. 適切なロギングを含める +7. テスト可能でモジュール化されたコードを書く + +コミュニティ標準に従った、クリーンで保守可能な Python コードの作成に焦点を当てます。 +``` + +**Use Cases:** + +- "JWT トークンを使用したユーザー認証のための FastAPI サービスを作成する" +- "pandas とエラーハンドリングによるデータ処理パイプラインを実装する" +- "包括的なヘルプドキュメント付きの argparse を使用して CLI ツールを書く" + +## ベストプラクティス + +### 設計原則 + +#### 単一責任原則 + +各サブエージェントは、明確で集中した目的を持つべきです。 + +**✅ 良い例:** + +```markdown +--- +name: testing-expert +description: Writes comprehensive unit tests and integration tests +--- +``` + +**❌ 避けるべき例:** + +```markdown +--- +name: general-helper +description: Helps with testing, documentation, code review, and deployment +--- +``` + +**理由:** 目的に集中したエージェントの方が、より良い結果を生み出し、メンテナンスも容易になります。 + +#### 明確な専門性 + +広範な能力よりも、特定の専門領域を定義しましょう。 + +**✅ 良い例:** + +```markdown +--- +name: react-performance-optimizer +description: Optimizes React applications for performance using profiling and best practices +--- +``` + +**❌ 避けるべき例:** + +```markdown +--- +name: frontend-developer +description: Works on frontend development tasks +--- +``` + +**理由:** 特定の専門知識があることで、より的確で効果的な支援が可能になります。 + +#### 実行可能な説明文を書く + +エージェントをいつ使うべきかを明確に示す説明文を書いてください。 + +**✅ 良い例:** + +```markdown +description: コードのセキュリティ脆弱性、パフォーマンス問題、保守性の懸念点をレビューします +``` + +**❌ 避けるべき例:** + +```markdown +description: 役に立つコードレビューア +``` + +**理由:** 明確な説明文があることで、メインのAIが各タスクに適したエージェントを選択しやすくなります。 + +### 設定のベストプラクティス + +#### System Prompt Guidelines + +**専門性について具体的に記述する:** + +```markdown +You are a Python testing specialist with expertise in: + +- pytest framework and fixtures +- Mock objects and dependency injection +- Test-driven development practices +- Performance testing with pytest-benchmark +``` + +**ステップ・バイ・ステップのアプローチを含める:** + +```markdown +For each testing task: + +1. コード構造と依存関係を分析する +2. キーとなる機能とエッジケースを特定する +3. 明確な命名規則を持った包括的なテストスイートを作成する +4. セットアップ/ティアダウンと適切なアサーションを含める +5. 複雑なテストシナリオを説明するコメントを追加する +``` + +**出力標準を指定する:** + +```markdown +Always follow these standards: + +- シナリオを説明する記述的なテスト名を使用する +- ポジティブケースとネガティブケースの両方を含める +- 複雑なテスト関数にはdocstringを追加する +- テストが独立しており、任意の順序で実行できることを確認する +``` + +## セキュリティに関する考慮事項 + +- **ツールの制限**: サブエージェントは設定されたツールのみにアクセス可能 +- **サンドボックス化**: すべてのツール実行は、直接ツールを使用する場合と同じセキュリティモデルに従う +- **監査ログ**: すべてのサブエージェントのアクションはログに記録され、リアルタイムで確認可能 +- **アクセス制御**: プロジェクトレベルおよびユーザーレベルの分離により、適切な境界を提供 +- **機密情報**: エージェント設定にシークレットや認証情報の含まれるのを避ける +- **本番環境**: 本番環境と開発環境では別々のエージェントを検討すること \ No newline at end of file diff --git a/website/content/ja/telemetry.md b/website/content/ja/telemetry.md index 93465af3..96aa2ff9 100644 --- a/website/content/ja/telemetry.md +++ b/website/content/ja/telemetry.md @@ -1,8 +1,8 @@ -# Qwen Code 観測性ガイド +# Qwen Code 可観測性ガイド テレメトリは、Qwen Code のパフォーマンス、健全性、使用状況に関するデータを提供します。これを有効にすることで、トレース、メトリクス、構造化ログを通じて、操作の監視、問題のデバッグ、ツール使用の最適化が可能になります。 -Qwen Code のテレメトリシステムは **[OpenTelemetry] (OTEL)** 標準に基づいて構築されており、互換性のある任意のバックエンドにデータを送信できます。 +Qwen Code のテレメトリシステムは **[OpenTelemetry] (OTEL)** 標準に基づいて構築されており、任意の互換性のあるバックエンドにデータを送信できます。 [OpenTelemetry]: https://opentelemetry.io/ @@ -35,7 +35,7 @@ Qwen Code のテレメトリシステムは **[OpenTelemetry] (OTEL)** 標準に - `telemetry.logPrompts`: `true` **`npm run telemetry -- --target=` スクリプトについて:** -このスクリプトに渡す `--target` 引数は、そのスクリプトの実行中およびその目的（つまり、起動する collector の選択）においてのみ `telemetry.target` を上書きします。これは `settings.json` の設定を永続的に変更するものではありません。スクリプトはまず `settings.json` を参照し、`telemetry.target` のデフォルト値として使用します。 +このスクリプトに渡す `--target` 引数は、そのスクリプトの実行中および実行目的（つまり、起動する collector の選択）にのみ `telemetry.target` を上書きします。これは `settings.json` の設定を永続的に変更するものではありません。スクリプトはまず `settings.json` 内の `telemetry.target` を確認し、それをデフォルトとして使用します。 ### 設定例 @@ -64,11 +64,9 @@ TELEMETRY_FILE=".qwen/telemetry.log" # ローカルテレメトリを有効にして Qwen Code を実行 -# 注意: デフォルトの OTLP エクスポーターを上書きし、 +# 注意: --telemetry-otlp-endpoint="" はデフォルトの OTLP エクスポーターを -# テレメトリがローカルファイルに確実に書き込まれるようにするために - -# --telemetry-otlp-endpoint="" が必要です。 +# 上書きし、テレメトリがローカルファイルに確実に書き込まれるようにするために必要です。 qwen --telemetry \ --telemetry-target=local \ --telemetry-otlp-endpoint="" \ @@ -78,10 +76,13 @@ qwen --telemetry \ ## OTEL Collector の実行 -OTEL Collector は、テレメトリデータを受信、処理、エクスポートするサービスです。 -CLI は OTLP/gRPC プロトコルを使用してデータを送信します。 +OTEL Collector は、テレメトリデータを受信、処理、エクスポートするサービスです。 +CLI は OTLP/gRPC または OTLP/HTTP プロトコルのいずれかを使ってデータを送信できます。 +使用するプロトコルは、`--telemetry-otlp-protocol` フラグまたは `settings.json` ファイル内の +`telemetry.otlpProtocol` 設定で指定できます。詳細については +[configuration docs](./cli/configuration.md#--telemetry-otlp-protocol) を参照してください。 -OTEL エクスポーターの標準設定について詳しくは、[documentation][otel-config-docs] を参照してください。 +OTEL exporter の標準設定について詳しくは [documentation][otel-config-docs] をご覧ください。 [otel-config-docs]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/ @@ -97,72 +98,72 @@ OTEL エクスポーターの標準設定について詳しくは、[documentati ``` スクリプトは以下の処理を行います： - - 必要に応じて Jaeger と OTEL をダウンロード。 - - ローカルに Jaeger インスタンスを起動。 - - Qwen Code からのデータを受信するように設定された OTEL コレクターを起動。 - - ワークスペースの設定で自動的にテレメトリーを有効化。 - - 終了時にテレメトリーを無効化。 + - 必要に応じて Jaeger と OTEL をダウンロードします。 + - ローカルに Jaeger インスタンスを起動します。 + - Qwen Code からのデータを受信するように設定された OTEL コレクターを起動します。 + - ワークスペースの設定で自動的にテレメトリーを有効にします。 + - 終了時にはテレメトリーを無効にします。 -1. **トレースの表示**： +1. **トレースの確認**： Webブラウザを開き、**http://localhost:16686** にアクセスして Jaeger UI を表示します。ここでは Qwen Code の操作に関する詳細なトレースを確認できます。 1. **ログとメトリクスの確認**： - スクリプトは OTEL コレクターの出力（ログとメトリクスを含む）を `~/.qwen/tmp//otel/collector.log` にリダイレクトします。スクリプトは、テレメトリーデータ（トレース、メトリクス、ログ）をローカルで表示するためのリンクと、それらを tail するコマンドを提供します。 + スクリプトは OTEL コレクターの出力（ログとメトリクスを含む）を `~/.qwen/tmp//otel/collector.log` にリダイレクトします。スクリプトは、テレメトリーデータ（トレース、メトリクス、ログ）をローカルで表示するためのリンクとコマンドを提供します。 1. **サービスの停止**： スクリプトを実行しているターミナルで `Ctrl+C` を押すと、OTEL Collector と Jaeger サービスを停止できます。 ### Google Cloud -`npm run telemetry -- --target=gcp` コマンドを使用すると、ローカルに OpenTelemetry collector を自動でセットアップし、データを指定した Google Cloud プロジェクトに転送できます。この際に必要な設定を `.qwen/settings.json` ファイルに自動で追加します。内部では `otelcol-contrib` をインストールするスクリプトが実行されます。使用手順は以下の通りです： +`npm run telemetry -- --target=gcp` コマンドを使用して、ローカルの OpenTelemetry コレクターを自動でセットアップし、データをあなたの Google Cloud プロジェクトに転送する設定を行います。これには `.qwen/settings.json` ファイルへの必要な設定の追加も含まれます。内部スクリプトは `otelcol-contrib` をインストールします。使用方法は以下の通りです： 1. **前提条件**: - - Google Cloud のプロジェクト ID を用意してください。 - - `GOOGLE_CLOUD_PROJECT` 環境変数をエクスポートし、OTEL collector から参照できるようにしてください。 + - Google Cloud プロジェクト ID を持っていること。 + - 環境変数 `GOOGLE_CLOUD_PROJECT` をエクスポートして、OTEL コレクターからアクセス可能にしてください。 ```bash export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" ``` - - Google Cloud への認証を行ってください（例：`gcloud auth application-default login` を実行する、または `GOOGLE_APPLICATION_CREDENTIALS` が正しく設定されていることを確認してください）。 - - 使用する Google Cloud アカウントまたはサービスアカウントに、以下の IAM ロールが割り当てられていることを確認してください："Cloud Trace Agent"、"Monitoring Metric Writer"、"Logs Writer"。 + - Google Cloud への認証を行ってください（例：`gcloud auth application-default login` を実行するか、`GOOGLE_APPLICATION_CREDENTIALS` が設定されていることを確認してください）。 + - 使用する Google Cloud アカウントまたはサービスアカウントに、以下の IAM ロールが付与されていること："Cloud Trace Agent"、"Monitoring Metric Writer"、"Logs Writer"。 -1. **コマンドを実行**: +1. **コマンドの実行**: リポジトリのルートディレクトリから以下のコマンドを実行してください： ```bash npm run telemetry -- --target=gcp ``` - スクリプトの処理内容： - - 必要に応じて `otelcol-contrib` のバイナリをダウンロードします。 - - Qwen Code からのデータを受信し、指定された Google Cloud プロジェクトにエクスポートするように設定された OTEL collector を起動します。 - - 自動的に telemetry を有効にし、workspace settings（`.qwen/settings.json`）の sandbox mode を無効化します。 - - Google Cloud Console 上で traces、metrics、logs を確認するための直接リンクを表示します。 - - 終了時（Ctrl+C）には、元の telemetry および sandbox 設定を復元しようとします。 + スクリプトは以下の処理を行います： + - 必要に応じて `otelcol-contrib` バイナリをダウンロードします。 + - Qwen Code からのデータを受信し、指定された Google Cloud プロジェクトにエクスポートするように設定された OTEL コレクターを起動します。 + - ワークスペース設定（`.qwen/settings.json`）で自動的にテレメトリを有効にし、サンドボックスモードを無効にします。 + - Google Cloud Console でトレース、メトリクス、ログを表示するための直接リンクを提供します。 + - 終了時（Ctrl+C）には、元のテレメトリおよびサンドボックス設定を復元しようとします。 -1. **Qwen Code を実行**: - 別のターミナルで Qwen Code のコマンドを実行してください。これにより、collector が取得する telemetry データが生成されます。 +1. **Qwen Code の実行**: + 別のターミナルで Qwen Code コマンドを実行してください。これにより、コレクターがキャプチャするテレメトリデータが生成されます。 -1. **Google Cloud で telemetry を確認**: - スクリプトが提供するリンクを使って Google Cloud Console にアクセスし、traces、metrics、logs を確認してください。 +1. **Google Cloud でのテレメトリの確認**: + スクリプトによって提供されたリンクを使用して Google Cloud Console に移動し、トレース、メトリクス、ログを確認してください。 -1. **ローカル collector のログを確認**: - ローカルの OTEL collector の出力は `~/.qwen/tmp//otel/collector-gcp.log` にリダイレクトされます。スクリプトは、このログを表示するリンクおよび tail コマンドも提供します。 +1. **ローカルのコレクターログの確認**: + スクリプトはローカルの OTEL コレクターの出力を `~/.qwen/tmp//otel/collector-gcp.log` にリダイレクトします。スクリプトは、ローカルでコレクターログを表示したり、tail コマンドを実行するためのリンクとコマンドも提供します。 -1. **サービスを停止**: - スクリプトを実行中のターミナルで `Ctrl+C` を押すと、OTEL Collector が停止します。 +1. **サービスの停止**: + スクリプトを実行しているターミナルで `Ctrl+C` を押すと、OTEL コレクターを停止します。 ## ログとメトリクスのリファレンス -以下のセクションでは、Qwen Code 用に生成されるログとメトリクスの構造について説明します。 +このセクションでは、Qwen Code 用に生成されるログとメトリクスの構造について説明します。 - すべてのログとメトリクスには、共通の属性として `sessionId` が含まれます。 -### ログ +### Logs -ログは、特定のイベントのタイムスタンプ付き記録です。Qwen Code では以下のイベントがログに記録されます： +Logs は特定のイベントのタイムスタンプ付き記録です。Qwen Code では以下のイベントがログに記録されます： -- `qwen-code.config`: CLI の起動時に1回発生し、CLI の設定情報を含みます。 - - **属性**: +- `qwen-code.config`: このイベントは CLI の起動時に一度だけ発生し、CLI の設定情報を含みます。 + - **Attributes**: - `model` (string) - `embedding_model` (string) - `sandbox_enabled` (boolean) @@ -176,30 +177,30 @@ OTEL エクスポーターの標準設定について詳しくは、[documentati - `debug_mode` (boolean) - `mcp_servers` (string) -- `qwen-code.user_prompt`: ユーザーがプロンプトを送信したときに発生します。 - - **属性**: +- `qwen-code.user_prompt`: このイベントはユーザーが prompt を送信したときに発生します。 + - **Attributes**: - `prompt_length` - - `prompt` (`log_prompts_enabled` が `false` の場合はこの属性は除外されます) + - `prompt` (この attribute は `log_prompts_enabled` が `false` の場合、除外されます) - `auth_type` -- `qwen-code.tool_call`: 各関数呼び出し時に発生します。 - - **属性**: +- `qwen-code.tool_call`: このイベントは各 function call に対して発生します。 + - **Attributes**: - `function_name` - `function_args` - `duration_ms` - `success` (boolean) - - `decision` (string: "accept"、"reject"、"auto_accept"、または "modify"。適用される場合) + - `decision` (string: "accept", "reject", "auto_accept", または "modify"。適用される場合) - `error` (適用される場合) - `error_type` (適用される場合) - - `metadata` (適用される場合、string → any の辞書形式) + - `metadata` (適用される場合、string -> any の dictionary) -- `qwen-code.api_request`: Gemini API へのリクエスト時に発生します。 - - **属性**: +- `qwen-code.api_request`: このイベントは Qwen API へのリクエスト時に発生します。 + - **Attributes**: - `model` - `request_text` (適用される場合) -- `qwen-code.api_error`: API リクエストが失敗した場合に発生します。 - - **属性**: +- `qwen-code.api_error`: このイベントは API リクエストが失敗した場合に発生します。 + - **Attributes**: - `model` - `error` - `error_type` @@ -207,12 +208,12 @@ OTEL エクスポーターの標準設定について詳しくは、[documentati - `duration_ms` - `auth_type` -- `qwen-code.api_response`: Gemini API からレスポンスを受信したときに発生します。 - - **属性**: +- `qwen-code.api_response`: このイベントは Qwen API からレスポンスを受信した際に発生します。 + - **Attributes**: - `model` - `status_code` - `duration_ms` - - `error` (任意) + - `error` (optional) - `input_token_count` - `output_token_count` - `cached_content_token_count` @@ -221,37 +222,38 @@ OTEL エクスポーターの標準設定について詳しくは、[documentati - `response_text` (適用される場合) - `auth_type` -- `qwen-code.flash_fallback`: Qwen Code がフォールバックとして flash に切り替えたときに発生します。 - - **属性**: +- `qwen-code.flash_fallback`: このイベントは Qwen Code が fallback として flash に切り替えたときに発生します。 + - **Attributes**: - `auth_type` -- `qwen-code.slash_command`: ユーザーがスラッシュコマンドを実行したときに発生します。 - - **属性**: +- `qwen-code.slash_command`: このイベントはユーザーが slash command を実行したときに発生します。 + - **Attributes**: - `command` (string) - `subcommand` (string, 適用される場合) ### Metrics -Metrics は時間経過に伴う行動の数値的な測定値です。Qwen Code では以下の Metrics が収集されます（互換性のため、メトリクス名は `qwen-code.*` のままです）： +Metrics は時間経過に伴う行動の数値的な測定値です。Qwen Code では以下の Metrics が収集されます（互換性のため、metric 名は `qwen-code.*` のままです）： -- `qwen-code.session.count` (Counter, Int): CLI の起動ごとに 1 ずつ増加します。 +- `qwen-code.session.count` (Counter, Int): CLI 起動時に 1 インクリメントされます。 - `qwen-code.tool.call.count` (Counter, Int): ツール呼び出しの回数をカウントします。 - **Attributes**: - `function_name` - `success` (boolean) - - `decision` (string: "accept", "reject", または "modify"。該当する場合のみ) + - `decision` (string: "accept", "reject", または "modify"。該当する場合) + - `tool_type` (string: "mcp" または "native"。該当する場合) - `qwen-code.tool.call.latency` (Histogram, ms): ツール呼び出しのレイテンシを測定します。 - **Attributes**: - `function_name` - - `decision` (string: "accept", "reject", または "modify"。該当する場合のみ) + - `decision` (string: "accept", "reject", または "modify"。該当する場合) - `qwen-code.api.request.count` (Counter, Int): すべての API リクエストの回数をカウントします。 - **Attributes**: - `model` - `status_code` - - `error_type` (該当する場合のみ) + - `error_type` (該当する場合) - `qwen-code.api.request.latency` (Histogram, ms): API リクエストのレイテンシを測定します。 - **Attributes**: @@ -265,10 +267,15 @@ Metrics は時間経過に伴う行動の数値的な測定値です。Qwen Code - `qwen-code.file.operation.count` (Counter, Int): ファイル操作の回数をカウントします。 - **Attributes**: - `operation` (string: "create", "read", "update"): ファイル操作の種類。 - - `lines` (Int, 該当する場合のみ): ファイル内の行数。 - - `mimetype` (string, 該当する場合のみ): ファイルの mimetype。 - - `extension` (string, 該当する場合のみ): ファイルの拡張子。 - - `ai_added_lines` (Int, 該当する場合のみ): AI によって追加・変更された行数。 - - `ai_removed_lines` (Int, 該当する場合のみ): AI によって削除・変更された行数。 - - `user_added_lines` (Int, 該当する場合のみ): ユーザーが AI の提案変更で追加・変更した行数。 - - `user_removed_lines` (Int, 該当する場合のみ): ユーザーが AI の提案変更で削除・変更した行数。 \ No newline at end of file + - `lines` (Int, 該当する場合): ファイルの行数。 + - `mimetype` (string, 該当する場合): ファイルの mimetype。 + - `extension` (string, 該当する場合): ファイルの拡張子。 + - `ai_added_lines` (Int, 該当する場合): AI によって追加・変更された行数。 + - `ai_removed_lines` (Int, 該当する場合): AI によって削除・変更された行数。 + - `user_added_lines` (Int, 該当する場合): ユーザーが AI の提案変更で追加・変更した行数。 + - `user_removed_lines` (Int, 該当する場合): ユーザーが AI の提案変更で削除・変更した行数。 + +- `qwen-code.chat_compression` (Counter, Int): チャット圧縮操作の回数をカウントします。 + - **Attributes**: + - `tokens_before`: (Int): 圧縮前のコンテキスト内のトークン数。 + - `tokens_after`: (Int): 圧縮後のコンテキスト内のトークン数。 \ 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 f74bb910..32031510 100644 --- a/website/content/ja/tools/file-system.md +++ b/website/content/ja/tools/file-system.md @@ -1,26 +1,26 @@ # Qwen Code ファイルシステムツール -Qwen Code は、ローカルファイルシステムとやり取りするための包括的なツールスイートを提供します。これらのツールにより、モデルはファイルやディレクトリの読み書き、一覧表示、検索、変更などの操作を行うことができます。すべての操作はユーザーの管理下で行われ、通常は機密性の高い操作に対して確認が求められます。 +Qwen Code は、ローカルファイルシステムとやり取りするための包括的なツールスイートを提供します。これらのツールにより、モデルはファイルやディレクトリの読み書き、一覧表示、検索、変更などの操作を実行できます。すべての操作はユーザーの管理下にあり、通常は機密性の高い操作に対して確認が求められます。 -**注意:** すべてのファイルシステムツールは、セキュリティのために `rootDirectory`（通常は CLI を起動したカレントワーキングディレクトリ）内で動作します。これらのツールに指定するパスは、一般的に絶対パスであるか、またはこのルートディレクトリからの相対パスとして解決されます。 +**注意:** すべてのファイルシステムツールは、セキュリティのために `rootDirectory`（通常は CLI を起動したカレントワーキングディレクトリ）内で動作します。これらのツールに指定するパスは、一般的に絶対パスであることが期待されるか、このルートディレクトリからの相対パスとして解決されます。 ## 1. `list_directory` (ReadFolder) -`list_directory` は、指定されたディレクトリパス直下のファイルとサブディレクトリの名前を一覧表示します。オプションで、指定された glob パターンに一致するエントリを無視することもできます。 +`list_directory` は、指定されたディレクトリパス直下のファイル名とサブディレクトリ名を一覧表示します。オプションで、指定された glob パターンに一致するエントリを無視することもできます。 -- **ツール名:** `list_directory` -- **表示名:** ReadFolder -- **ファイル:** `ls.ts` -- **パラメータ:** - - `path` (string, 必須): 一覧を表示するディレクトリの絶対パス。 - - `ignore` (string の配列, オプション): 一覧から除外する glob パターンのリスト（例: `["*.log", ".git"]`）。 - - `respect_git_ignore` (boolean, オプション): ファイル一覧表示時に `.gitignore` パターンを尊重するかどうか。デフォルトは `true`。 -- **動作:** - - ファイルとディレクトリの名前のリストを返します。 +- **Tool name:** `list_directory` +- **Display name:** ReadFolder +- **File:** `ls.ts` +- **Parameters:** + - `path` (string, required): 一覧を表示するディレクトリの絶対パス。 + - `ignore` (array of strings, optional): 一覧から除外する glob パターンのリスト（例: `["*.log", ".git"]`）。 + - `respect_git_ignore` (boolean, optional): ファイル一覧表示時に `.gitignore` パターンを尊重するかどうか。デフォルトは `true`。 +- **Behavior:** + - ファイル名とディレクトリ名のリストを返します。 - 各エントリがディレクトリかどうかを示します。 - - エントリをディレクトリを先に、その後アルファベット順にソートします。 -- **出力 (`llmContent`):** 以下のような文字列: `Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png` -- **確認:** なし。 + - ディレクトリを先に、その後アルファベット順にエントリをソートします。 +- **Output (`llmContent`):** 以下のような文字列: `Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png` +- **Confirmation:** なし。 ## 2. `read_file` (ReadFile) @@ -31,15 +31,15 @@ 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 エンコードされたデータ構造としてファイル内容を返却します。 - その他のバイナリファイルの場合: 識別を試み、スキップして汎用的なバイナリファイルであることを示すメッセージを返却します。 - **出力:** (`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' } }`）。 + - テキストファイルの場合: ファイル内容。切り捨てが発生した場合は先頭に切り捨てメッセージが付加されます（例: `[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` のようなメッセージ。 - **確認:** なし。 @@ -56,45 +56,45 @@ 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`。 +- **出力 (`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`。 - **動作:** - 指定されたディレクトリ内で 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}"`）。省略された場合は、一般的な無視ファイルを除いたほとんどのファイルが検索されます。 + - `path` (string, optional): 検索対象のディレクトリへの絶対パス。デフォルトはカレントディレクトリ。 + - `include` (string, optional): 検索対象のファイルをフィルタリングする glob パターン（例: `"*.js"`, `"src/**/*.{ts,tsx}"`）。省略された場合、一般的な無視パターンを尊重しつつ、ほとんどのファイルを検索対象とします。 - `maxResults` (number, optional): コンテキストのオーバーフローを防ぐために返すマッチ結果の最大数（デフォルト: 20、最大: 100）。広範囲な検索には小さな値を、特定の検索には大きな値を使用してください。 -- **Behavior:** - - Git リポジトリ内で利用可能な場合は高速化のため `git grep` を使用し、それ以外の場合はシステムの `grep` または JavaScript ベースの検索にフォールバックします。 - - マッチした行のリストを返し、各行には検索ディレクトリからの相対パスと行番号が付加されます。 - - デフォルトではコンテキストのオーバーフローを防ぐため、最大20件のマッチ結果に制限されます。結果が切り捨てられた場合は、検索を絞り込むための案を含む明確な警告が表示されます。 -- **Output (`llmContent`):** 以下のようなフォーマットされた文字列で結果を返します: +- **動作:** + - Git リポジトリ内で利用可能な場合は高速化のため `git grep` を使用し、それ以外ではシステムの `grep` または JavaScript ベースの検索にフォールバックします。 + - マッチした行のリストを返します。各行には、検索ディレクトリからの相対パスと行番号がプレフィックスとして付加されます。 + - コンテキストのオーバーフローを防ぐため、デフォルトで最大20件のマッチ結果に制限されます。結果が切り捨てられた場合は、検索を絞り込むためのガイダンスとともに明確な警告を表示します。 +- **出力 (`llmContent`):** 以下のようなフォーマットされた文字列： ``` Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"): @@ -114,7 +114,7 @@ Qwen Code は、ローカルファイルシステムとやり取りするため - Increase 'maxResults' parameter if you need more matches (current: 20) ``` -- **Confirmation:** なし +- **確認:** なし ### `search_file_content` の例 @@ -136,38 +136,38 @@ search_file_content(pattern="function", path="src", maxResults=50) search_file_content(pattern="function", include="*.js", maxResults=10) ``` -## 6. `replace` (編集) +## 6. `edit` (編集) -`replace` はファイル内のテキストを置換します。デフォルトでは1つの出現箇所のみを置換しますが、`expected_replacements` を指定することで複数の出現箇所を置換することも可能です。このツールは正確で対象を絞った変更を行うために設計されており、正しい位置を変更することを保証するために `old_string` の周囲に十分なコンテキストが必要です。 +`edit` はファイル内のテキストを置換します。デフォルトでは1箇所のみ置換しますが、`expected_replacements` を指定することで複数箇所の置換も可能です。このツールは正確で対象を絞った変更を行うことを目的としており、正しい位置を変更することを保証するために `old_string` の前後には十分なコンテキストが必要です。 -- **ツール名:** `replace` +- **ツール名:** `edit` - **表示名:** 編集 - **ファイル:** `edit.ts` - **パラメータ:** - `file_path` (string, 必須): 変更するファイルの絶対パス。 - - `old_string` (string, 必須): 置換する正確なリテラルテキスト。 + - `old_string` (string, 必須): 置換する正確な文字列。 - **重要:** この文字列は変更する単一のインスタンスを一意に識別する必要があります。ターゲットテキストの前後少なくとも3行のコンテキストを含み、空白とインデントを正確に一致させる必要があります。`old_string` が空の場合、ツールは `file_path` に `new_string` を内容とする新しいファイルを作成しようとします。 + **重要:** この文字列は変更する1箇所を一意に識別する必要があります。対象テキストの前後それぞれに最低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` 操作をより堅牢にします。 -- **失敗条件:** 修正メカニズムにもかかわらず、以下の場合はツールが失敗します: - - `file_path` が絶対パスでない、またはルートディレクトリ外にある。 - - `old_string` が空でなく、`file_path` が存在しない。 - - `old_string` が空で、`file_path` が既に存在する。 - - 修正を試みた後も `old_string` がファイル内に見つからない。 - - `old_string` が複数回見つかり、自己修正メカニズムが単一の明確な一致に解決できない。 + - `old_string` が指定されている場合、`file_path` を読み込み、`old_string` の出現箇所を正確に1箇所だけ検索します。 + - 1箇所見つかった場合、それを `new_string` で置換します。 + - **信頼性の向上（マルチステージ編集修正）:** 編集の成功率を大幅に向上させるため、特にモデルが提供した `old_string` が完全に正確でない可能性がある場合に、ツールにはマルチステージ編集修正メカニズムが組み込まれています。 + - 初期の `old_string` が見つからない、または複数箇所に一致する場合、ツールは Qwen モデルを利用して `old_string`（および場合によっては `new_string`）を段階的に修正できます。 + - この自己修正プロセスにより、モデルが意図した一意のセグメントを特定し、初期コンテキストがわずかに不正確であっても `edit` 操作をより堅牢にします。 +- **失敗条件:** 修正メカニズムがあっても、以下の場合はツールは失敗します： + - `file_path` が絶対パスでない、またはルートディレクトリ外の場合。 + - `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...`）。 -- **確認:** あり。提案された変更の差分を表示し、ファイルに書き込む前にユーザーの承認を求めます。 + - 失敗時: 失敗理由を説明するエラーメッセージ（例: `Failed to edit, 0 occurrences found...`, `Failed to edit, expected 1 occurrences but found 2...`）。 +- **確認:** あり。変更内容の差分を表示し、ファイルに書き込む前にユーザーの承認を求めます。 -これらのファイルシステムツールは、Qwen Codeがローカルプロジェクトのコンテキストを理解し、操作するための基盤を提供します。 \ No newline at end of file +これらのファイルシステムツールにより、Qwen Code がローカルプロジェクトのコンテキストを理解し、操作するための基盤が提供されます。 \ No newline at end of file diff --git a/website/content/ja/tools/mcp-server.md b/website/content/ja/tools/mcp-server.md index ed80a720..e7807acb 100644 --- a/website/content/ja/tools/mcp-server.md +++ b/website/content/ja/tools/mcp-server.md @@ -4,19 +4,19 @@ ## MCPサーバーとは？ -MCPサーバーは、Model Context Protocolを介してCLIにツールやリソースを公開するアプリケーションで、外部システムやデータソースとのインタラクションを可能にします。MCPサーバーは、モデルとローカル環境やAPIなどの他のサービスとの間のブリッジとして機能します。 +MCPサーバーは、Model Context Protocolを通じてCLIにツールやリソースを公開し、外部システムやデータソースとやり取りできるようにするアプリケーションです。MCPサーバーは、モデルとローカル環境やAPIなどの他のサービスとの間のブリッジとして機能します。 MCPサーバーにより、CLIは以下のような機能を実現できます： -- **ツールの検出:** 標準化されたスキーマ定義を通じて、利用可能なツール、その説明、パラメータをリストアップします。 +- **ツールの検出:** 標準化されたスキーマ定義を通じて、利用可能なツール、その説明、およびパラメータを一覧表示します。 - **ツールの実行:** 定義された引数で特定のツールを呼び出し、構造化されたレスポンスを受け取ります。 -- **リソースへのアクセス:** 特定のリソースからデータを読み込みます（ただし、CLIは主にツール実行に焦点を当てています）。 +- **リソースへのアクセス:** 特定のリソースからデータを読み込みます（ただし、CLIは主にツールの実行に焦点を当てています）。 -MCPサーバーを使用することで、CLIの機能を拡張し、データベースやAPI、カスタムスクリプト、または専用のワークフローとのインタラクションなど、組み込み機能を超えたアクションを実行できます。 +MCPサーバーを使用することで、CLIの機能を拡張し、データベースやAPI、カスタムスクリプト、または特殊なワークフローとのやり取りなど、組み込み機能を超えたアクションを実行できます。 -## コアインテグレーションアーキテクチャ +## コア連携アーキテクチャ -Qwen Code は、コアパッケージ (`packages/core/src/tools/`) に組み込まれた洗練された Discovery および実行システムを通じて、MCP サーバーと統合されます。 +Qwen Code は、コアパッケージ (`packages/core/src/tools/`) に組み込まれた洗練された Discovery および実行システムを通じて、MCP サーバーと連携します。 ### Discovery レイヤー (`mcp-client.ts`) @@ -25,21 +25,21 @@ Discovery プロセスは `discoverMcpTools()` によって制御され、以下 1. `settings.json` の `mcpServers` 設定から**設定されたサーバーをイテレート** 2. 適切なトランスポートメカニズム（Stdio、SSE、または Streamable HTTP）を使用して**接続を確立** 3. MCP プロトコルを使用して各サーバーから**ツール定義を取得** -4. Gemini API との互換性を確保するためにツールスキーマを**サニタイズおよび検証** -5. 競合解決を行いながらグローバルツールレジストリに**ツールを登録** +4. Qwen API との互換性を確保するため、ツールスキーマを**サニタイズおよび検証** +5. 競合解決を行いながら、グローバルなツールレジストリに**ツールを登録** ### 実行レイヤー (`mcp-tool.ts`) 検出された各 MCP ツールは、以下を行う `DiscoveredMCPTool` インスタンスでラップされます： -- サーバーの信頼設定とユーザーの設定に基づいた**確認ロジックの処理** +- サーバーの信頼設定とユーザーの設定に基づいて**確認ロジックを処理** - 適切なパラメータで MCP サーバーを呼び出して**ツールの実行を管理** - LLM コンテキストとユーザー表示の両方のために**レスポンスを処理** -- **接続状態の維持**およびタイムアウトの処理 +- **接続状態を維持**し、タイムアウトを処理 ### トランスポートメカニズム -CLI は3種類の MCP トランスポートタイプをサポートしています： +CLI は3つの MCP トランスポートタイプをサポートしています： - **Stdio Transport:** サブプロセスを起動し、stdin/stdout を介して通信 - **SSE Transport:** Server-Sent Events エンドポイントに接続 @@ -84,20 +84,20 @@ MCP サーバーは、グローバルレベルで `~/.qwen/settings.json` ファ - **`url`** (string): SSE endpoint URL (例: `"http://localhost:8080/sse"`) - **`httpUrl`** (string): HTTP streaming endpoint URL -#### 任意 +#### オプション - **`args`** (string[]): Stdio トランスポート用のコマンドライン引数 - **`headers`** (object): `url` または `httpUrl` 使用時のカスタム HTTP ヘッダー - **`env`** (object): サーバープロセス用の環境変数。値には `$VAR_NAME` または `${VAR_NAME}` 構文を使って環境変数を参照できます - **`cwd`** (string): Stdio トランスポート用の作業ディレクトリ -- **`timeout`** (number): リクエストタイムアウト（ミリ秒単位）（デフォルト: 600,000ms = 10分） -- **`trust`** (boolean): `true` の場合、このサーバーに対するすべてのツール呼び出し確認をバイパスします（デフォルト: `false`） +- **`timeout`** (number): リクエストのタイムアウト（ミリ秒）（デフォルト: 600,000ms = 10分） +- **`trust`** (boolean): `true` の場合、このサーバーに対するすべてのツール呼び出し確認をスキップします（デフォルト: `false`） - **`includeTools`** (string[]): この MCP サーバーからインクルードするツール名のリスト。指定された場合、ここにリストされたツールのみがこのサーバーから利用可能になります（ホワイトリスト動作）。指定しない場合、サーバーからのすべてのツールがデフォルトで有効になります。 -- **`excludeTools`** (string[]): この MCP サーバーから除外するツール名のリスト。ここにリストされたツールは、サーバーで公開されていてもモデルから利用できません。**注意:** `excludeTools` は `includeTools` よりも優先されます - 両方のリストに同じツールがある場合、そのツールは除外されます。 +- **`excludeTools`** (string[]): この MCP サーバーから除外するツール名のリスト。ここにリストされたツールは、サーバーが公開していてもモデルからは利用できません。**注意:** `excludeTools` は `includeTools` よりも優先されます — 両方のリストに同じツールがある場合、そのツールは除外されます。 ### リモート MCP サーバーでの OAuth サポート -Qwen Code は、SSE または HTTP トランスポートを使用するリモート MCP サーバーに対して OAuth 2.0 認証をサポートしています。これにより、認証が必要な MCP サーバーへの安全なアクセスが可能になります。 +Qwen Code は、SSE または HTTP トランスポートを使用するリモート MCP サーバーに対して OAuth 2.0 認証をサポートしています。これにより、認証を必要とする MCP サーバーへの安全なアクセスが可能になります。 #### 自動 OAuth 検出 @@ -115,34 +115,34 @@ OAuth 検出をサポートするサーバーでは、OAuth 設定を省略し CLI は自動的に以下を行います： -- サーバーが OAuth 認証を必要とする場合の検出（401 レスポンス） -- サーバーメタデータからの OAuth エンドポイントの検出 -- サポートされている場合の動的クライアント登録 -- OAuth フローとトークン管理の処理 +- サーバーが OAuth 認証を必要としていることを検出（401 レスポンス） +- サーバーメタデータから OAuth エンドポイントを検出 +- サポートされている場合、動的クライアント登録を実行 +- OAuth フローとトークン管理を処理 #### 認証フロー OAuthが有効なサーバーに接続する場合： 1. **初回接続試行** が401 Unauthorizedで失敗する -2. **OAuthディスカバリー** により認可エンドポイントとトークンエンドポイントが検出される -3. **ブラウザが開いて** ユーザー認証が行われる（ローカルブラウザへのアクセスが必要） -4. **認可コード** がアクセストークンと交換される -5. **トークンが安全に保存** されて次回以降の使用に備える -6. **再接続試行** が有効なトークンを使って成功する +2. **OAuthディスカバリー** により認可エンドポイントとトークンエンドポイントを検出 +3. **ブラウザが開いて** ユーザー認証を行う（ローカルブラウザへのアクセスが必要） +4. **認可コード** をアクセストークンと交換 +5. **トークンを安全に保存** して次回以降の利用に備える +6. **接続再試行** が有効なトークンを使って成功する -#### ブラウザリダイレクト要件 +#### ブラウザリダイレクトの要件 -**重要：** OAuth認証にはローカルマシンが以下の条件を満たす必要があります： +**重要：** OAuth認証には以下の条件が必要です： - 認証用にウェブブラウザを開くことができる - `http://localhost:7777/oauth/callback` でリダイレクトを受け取ることができる この機能は以下の環境では動作しません： -- ブラウザアクセスがないヘッドレス環境 -- X11フォワーディングなしのリモートSSHセッション -- ブラウザサポートがないコンテナ化された環境 +- ブラウザアクセスがないheadless環境 +- X11 forwardingなしのリモートSSHセッション +- ブラウザサポートがないコンテナ環境 #### OAuth認証の管理 @@ -150,7 +150,7 @@ OAuthが有効なサーバーに接続する場合： ```bash -# 認証が必要なサーバーを一覧表示 +# 認証が必要なサーバー一覧を表示 /mcp auth ``` @@ -165,8 +165,8 @@ OAuthが有効なサーバーに接続する場合： #### OAuth 設定プロパティ - **`enabled`** (boolean): このサーバーで OAuth を有効化する -- **`clientId`** (string): OAuth クライアント識別子（動的登録時は任意） -- **`clientSecret`** (string): OAuth クライアントシークレット（パブリッククライアントでは任意） +- **`clientId`** (string): OAuth クライアント識別子（動的登録の場合は任意） +- **`clientSecret`** (string): OAuth クライアントシークレット（パブリッククライアントの場合は任意） - **`authorizationUrl`** (string): OAuth 認可エンドポイント（省略時は自動検出） - **`tokenUrl`** (string): OAuth トークンエンドポイント（省略時は自動検出） - **`scopes`** (string[]): 必要な OAuth スコープ @@ -177,12 +177,12 @@ OAuthが有効なサーバーに接続する場合： #### Token Management -OAuth トークンは自動的に： +OAuth トークンは自動的に: -- **安全に保存** される（`~/.qwen/mcp-oauth-tokens.json` に） -- **期限切れ時に更新** される（リフレッシュトークンが利用可能な場合） +- **安全に保存** される (`~/.qwen/mcp-oauth-tokens.json` に) +- **期限切れ時に更新** される (リフレッシュトークンが利用可能な場合) - **各接続試行前に検証** される -- **無効または期限切れの際にクリーンアップ** される +- **無効または期限切れ時にクリーンアップ** される #### 認証プロバイダータイプ @@ -332,35 +332,35 @@ Qwen Codeが起動すると、以下のような詳細なプロセスを通じ ### 2. ツールの検出 -接続に成功すると: +接続に成功すると以下の処理が実行されます： -1. **ツール一覧の取得:** クライアントがMCPサーバーのツール一覧エンドポイントを呼び出します -2. **スキーマの検証:** 各ツールのfunction宣言が検証されます -3. **ツールのフィルタリング:** `includeTools`と`excludeTools`の設定に基づいてツールがフィルタリングされます -4. **名前のサニタイズ:** Gemini APIの要件を満たすためにツール名がクリーニングされます: - - 無効な文字（英数字、アンダースコア、ドット、ハイフン以外）はアンダースコアに置換されます - - 63文字を超える名前は中間置換（`___`）で切り詰められます +1. **ツール一覧の取得:** クライアントがMCPサーバーのツール一覧エンドポイントを呼び出します +2. **スキーマの検証:** 各ツールのfunction宣言が検証されます +3. **ツールのフィルタリング:** `includeTools` および `excludeTools` の設定に基づいてツールがフィルタリングされます +4. **名前のサニタイズ:** Qwen APIの要件を満たすためにツール名がクリーニングされます： + - 無効な文字（英数字、アンダースコア、ドット、ハイフン以外）はアンダースコアに置換されます + - 63文字を超える名前は中間置換（`___`）によって短縮されます ### 3. 競合の解決 -複数のサーバーが同じ名前のツールを公開している場合: +複数のサーバーが同じ名前のツールを公開している場合： -1. **最初の登録が優先:** 最初にツール名を登録したサーバーがプレフィックスなしの名前を取得します -2. **自動プレフィックス付与:** その後のサーバーにはプレフィックス付きの名前が付与されます: `serverName__toolName` -3. **レジストリの追跡:** ツールレジストリはサーバー名とそのツール間のマッピングを維持します +1. **最初の登録が優先:** 最初にツール名を登録したサーバーがプレフィックスなしの名前を取得します +2. **自動プレフィックス付与:** その後に登録するサーバーには `serverName__toolName` の形式でプレフィックスが付与されます +3. **レジストリの追跡:** ツールレジストリはサーバー名とそのツールのマッピングを維持します ### 4. スキーマ処理 -ツールパラメータのスキーマは、API互換性のためにサニタイズ処理が行われます： +ツールのパラメータスキーマは、API互換性のためにサニタイズ処理が行われます： - **`$schema` プロパティ**は削除されます - **`additionalProperties`** は除去されます - **`default` 付きの `anyOf`** はデフォルト値が削除されます（Vertex AI互換性のため） - **再帰的処理**がネストされたスキーマにも適用されます -### 5. コネクション管理 +### 5. 接続管理 -ディスカバリー処理後： +Discovery処理終了後： - **永続接続：** ツール登録に成功したサーバーは接続を維持します - **クリーンアップ：** 利用可能なツールを提供しないサーバーの接続はクローズされます @@ -375,7 +375,7 @@ Qwen Codeが起動すると、以下のような詳細なプロセスを通じ モデルは以下の情報を含む `FunctionCall` を生成します： - **ツール名：** 登録された名前（プレフィックスが付いている可能性あり） -- **引数：** ツールのパラメータスキーマにマッチするJSONオブジェクト +- **引数：** ツールのパラメータスキーマに一致するJSONオブジェクト ### 2. 確認プロセス @@ -391,41 +391,41 @@ if (this.trust) { #### 動的な許可リスト -システムは内部で以下の許可リストを管理しています： +システムは以下の内部許可リストを管理しています： -- **サーバーレベル:** `serverName` → このサーバーからのすべてのツールを信頼 -- **ツールレベル:** `serverName.toolName` → この特定のツールを信頼 +- **サーバーレベル：** `serverName` → このサーバーからのすべてのツールを信頼 +- **ツールレベル：** `serverName.toolName` → この特定のツールを信頼 #### ユーザー選択の処理 確認が必要な場合、ユーザーは以下から選択できます： -- **今回のみ実行:** 今回は実行するが、次回以降も確認する -- **常にこのツールを許可:** ツールレベルの許可リストに追加 -- **常にこのサーバーを許可:** サーバーレベルの許可リストに追加 -- **キャンセル:** 実行を中止 +- **今回のみ実行：** 今回は実行する +- **常にこのツールを許可：** ツールレベルの許可リストに追加 +- **常にこのサーバーを許可：** サーバーレベルの許可リストに追加 +- **キャンセル：** 実行を中止 ### 3. 実行 確認（または信頼のバイパス）後: -1. **パラメータ準備:** 引数はツールのスキーマに対して検証される -2. **MCP呼び出し:** 基底の`CallableTool`が以下でサーバを呼び出す: +1. **パラメータ準備:** 引数はツールのスキーマに対して検証されます +2. **MCP呼び出し:** 基底の`CallableTool`が以下でサーバを呼び出します: ```typescript const functionCalls = [ { - name: this.serverToolName, // 元のサーバツール名 + name: this.serverToolName, // 元のサーバーツール名 args: params, }, ]; ``` -3. **レスポンス処理:** 結果はLLMコンテキストとユーザ表示の両方でフォーマットされる +3. **レスポンス処理:** 結果はLLMコンテキストとユーザ表示の両方でフォーマットされます ### 4. レスポンス処理 -実行結果には以下が含まれる: +実行結果には以下が含まれます: - **`llmContent`:** 言語モデルのコンテキスト用の生レスポンス部分 - **`returnDisplay`:** ユーザ表示用のフォーマット済み出力（多くの場合、markdownコードブロック内のJSON） @@ -463,7 +463,7 @@ MCP Servers Status: Command: node dist/server.js --verbose Error: Connection refused -.dockerizedServer (CONNECTED) +🐳 dockerizedServer (CONNECTED) Command: docker run -i --rm -e API_KEY my-mcp-server:latest Tools: docker__deploy, docker__status @@ -472,30 +472,30 @@ Discovery State: COMPLETED ### ツールの使用方法 -発見されたMCPツールは、Geminiモデルにとってビルトインツールと同様に利用可能です。モデルは自動的に： +発見されたMCPツールは、Qwenモデルにとって組み込みツールのように利用可能です。モデルは自動的に： -1. **適切なツールを選択** リクエストに基づいて適切なツールを選択します -2. **確認ダイアログを表示** （サーバーが信頼済みでない場合） -3. **ツールを実行** 適切なパラメータでツールを実行します -4. **結果を表示** ユーザーに分かりやすい形式で結果を表示します +1. リクエストに基づいて**適切なツールを選択** +2. （サーバーが信頼されていない場合）**確認ダイアログを表示** +3. 適切なパラメータで**ツールを実行** +4. 結果をユーザーフレンドリーな形式で**表示** ## ステータス監視とトラブルシューティング ### 接続状態 -MCP連携は以下の状態を追跡します： +MCP連携では以下の状態が追跡されます： -#### サーバーステータス (`MCPServerStatus`) +#### サーバーステータス（`MCPServerStatus`） -- **`DISCONNECTED`:** サーバーが接続されていないか、エラーが発生しています -- **`CONNECTING`:** 接続試行中です -- **`CONNECTED`:** サーバーが接続され、準備完了です +- **`DISCONNECTED`:** サーバーが接続されていない、またはエラー状態 +- **`CONNECTING`:** 接続試行中 +- **`CONNECTED`:** サーバーが接続され、準備完了 -#### 発見状態 (`MCPDiscoveryState`) +#### 発見状態（`MCPDiscoveryState`） -- **`NOT_STARTED`:** 発見処理が開始されていません -- **`IN_PROGRESS`:** 現在サーバーを発見中です -- **`COMPLETED`:** 発見処理が完了しました（エラーの有無に関わらず） +- **`NOT_STARTED`:** 発見処理が開始されていない +- **`IN_PROGRESS`:** 現在サーバーを発見中 +- **`COMPLETED`:** 発見処理が完了（エラーの有無にかかわらず） ### よくある問題と解決方法 @@ -506,7 +506,7 @@ MCP連携は以下の状態を追跡します： **トラブルシューティング:** 1. **設定を確認:** `command`、`args`、`cwd` が正しいことを確認 -2. **手動でテスト:** サーバーコマンドを直接実行して、正常に動作することを確認 +2. **手動でテスト:** サーバーコマンドを直接実行して、正常に動作するか確認 3. **依存関係を確認:** 必要なパッケージがすべてインストールされていることを確認 4. **ログを確認:** CLI出力でエラーメッセージを探す 5. **権限を確認:** CLIがサーバーコマンドを実行できることを確認 @@ -530,7 +530,7 @@ MCP連携は以下の状態を追跡します： 1. **パラメータ検証:** ツールが期待するパラメータを受け取れているか確認する 2. **スキーマ互換性:** 入力スキーマが有効な JSON Schema であることを検証する -3. **エラーハンドリング:** ツールが未処理の例外をスローしていないか確認する +3. **エラー処理:** ツールが未処理の例外をスローしていないかチェックする 4. **タイムアウト問題:** `timeout` 設定を増やすことを検討する #### サンドボックス互換性 @@ -539,7 +539,7 @@ MCP連携は以下の状態を追跡します： **解決策:** -1. **Dockerベースのサーバー:** すべての依存関係を含む Docker コンテナを使用する +1. **Docker ベースのサーバー:** すべての依存関係を含む Docker コンテナを使用する 2. **パスのアクセシビリティ:** サンドボックス内でサーバー実行ファイルが利用可能であることを確認する 3. **ネットワークアクセス:** 必要なネットワーク接続を許可するようにサンドボックスを設定する 4. **環境変数:** 必要な環境変数が正しく渡されていることを検証する @@ -556,23 +556,23 @@ MCP連携は以下の状態を追跡します： ### セキュリティに関する考慮事項 -- **信頼設定:** `trust` オプションはすべての確認ダイアログをバイパスします。このオプションは慎重に使用し、自分が完全に管理するサーバーに対してのみ有効にしてください +- **信頼設定:** `trust` オプションはすべての確認ダイアログをバイパスします。完全に管理下にあるサーバーに対してのみ、慎重に使用してください - **アクセストークン:** API キーやトークンを含む環境変数を設定する際は、セキュリティに十分注意してください -- **サンドボックス互換性:** サンドボックス環境を使用する場合、MCP サーバーがサンドボックス内で利用可能であることを確認してください -- **プライベートデータ:** 広範囲にわたるスコープを持つ personal access token を使用すると、リポジトリ間での情報漏洩を引き起こす可能性があります +- **サンドボックス互換性:** サンドボックスを使用する場合、MCP サーバーがサンドボックス環境内で利用可能であることを確認してください +- **プライベートデータ:** 広範囲なスコープを持つ personal access token を使用すると、リポジトリ間での情報漏洩を引き起こす可能性があります ### パフォーマンスとリソース管理 - **接続の永続化:** CLI は、ツールの登録に成功したサーバーへの持続的な接続を維持します - **自動クリーンアップ:** ツールを提供しないサーバーへの接続は自動的に閉じられます -- **タイムアウト管理:** サーバーのレスポンス特性に応じて適切なタイムアウトを設定します +- **タイムアウト管理:** サーバーのレスポンス特性に応じて適切なタイムアウトを設定してください - **リソース監視:** MCP サーバーは別プロセスとして実行され、システムリソースを消費します ### スキーマ互換性 -- **プロパティの除去:** Gemini API との互換性を確保するため、システムは特定のスキーマプロパティ（`$schema`、`additionalProperties`）を自動的に削除します +- **プロパティの除去:** Qwen API との互換性を保つため、システムは特定のスキーマプロパティ（`$schema`、`additionalProperties`）を自動的に削除します - **名前サニタイズ:** API 要件を満たすために、ツール名は自動的にサニタイズされます -- **競合解決:** サーバー間でのツール名の競合は、自動的な接頭辞付与によって解決されます +- **競合の解決:** サーバー間でのツール名の競合は、自動的な接頭辞付与によって解決されます この包括的な統合により、MCP サーバーは CLI の機能を拡張する強力な手段となり、セキュリティ、信頼性、使いやすさを維持します。 @@ -580,13 +580,13 @@ MCP連携は以下の状態を追跡します： MCP ツールは単純なテキストの返却に限定されません。1 つのツールレスポンスで、テキスト、画像、音声、その他のバイナリデータを含む、リッチでマルチパートのコンテンツを返却できます。これにより、1 回のやり取りでモデルに多様な情報を提供できる強力なツールを構築できます。 -ツールから返却されたすべてのデータは処理され、モデルの次の生成のコンテキストとして送信されるため、モデルは提供された情報について推論したり要約したりすることが可能になります。 +ツールから返却されたすべてのデータは処理され、モデルの次の生成のコンテキストとして送信されるため、モデルは提供された情報について推論したり要約したりできます。 ### 動作原理 リッチなコンテンツを返すためには、ツールのレスポンスが [`CallToolResult`](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result) の MCP 仕様に準拠している必要があります。result の `content` フィールドは `ContentBlock` オブジェクトの配列であるべきです。CLI はこの配列を正しく処理し、テキストとバイナリデータを分離して、モデル用にパッケージ化します。 -`content` 配列内では、異なる content block タイプを混在させることができます。サポートされているブロックタイプは以下の通りです： +`content` 配列内では異なる content block タイプを混在させることができます。サポートされているブロックタイプは以下の通りです： - `text` - `image` @@ -622,17 +622,17 @@ Qwen Codeがこのレスポンスを受信すると、以下の処理を行い 1. すべてのテキストを抽出し、モデル用の単一の`functionResponse`パートに結合します。 2. 画像データを別の`inlineData`パートとして表示します。 -3. CLIに、テキストと画像の両方が受信されたことを示す、クリーンでユーザーにやさしいサマリーを提供します。 +3. CLIに、テキストと画像の両方が受信されたことを示す、クリーンでユーザーフレンドリーなサマリーを提供します。 -これにより、Geminiモデルにリッチでマルチモーダルなコンテキストを提供できる、洗練されたツールを構築できます。 +これにより、Qwenモデルにリッチでマルチモーダルなコンテキストを提供できる、洗練されたツールを構築できます。 ## MCP Prompts as Slash Commands -ツールに加えて、MCP サーバーは Qwen Code 内でスラッシュコマンドとして実行できる事前定義されたプロンプトを公開できます。これにより、一般的なクエリや複雑なクエリに対してショートカットを作成し、名前で簡単に呼び出すことができます。 +Toolsに加えて、MCPサーバーはQwen Code内でslash commandとして実行できる事前定義されたpromptsを公開できます。これにより、一般的なクエリや複雑なクエリに対してショートカットを作成し、名前で簡単に呼び出すことができるようになります。 -### サーバーでのプロンプトの定義 +### サーバーでのプロンプト定義 -以下は、プロンプトを定義する stdio MCP サーバーの小さな例です： +プロンプトを定義する stdio MCP サーバーの小さな例を以下に示します： ```ts import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; @@ -668,7 +668,7 @@ const transport = new StdioServerTransport(); await server.connect(transport); ``` -これは、`settings.json` の `mcpServers` 以下に以下のように含めることができます： +これは `settings.json` の `mcpServers` 以下に以下のように含めることができます： ```json "nodeServer": { @@ -679,7 +679,7 @@ await server.connect(transport); ### プロンプトの呼び出し -プロンプトが見つかったら、スラッシュコマンドとして名前を指定して呼び出すことができます。CLI が自動的に引数の解析を処理してくれます。 +プロンプトが見つかったら、スラッシュコマンドとして名前を指定して呼び出すことができます。CLI が自動的に引数の解析を処理します。 ```bash /poem-writer --title="Qwen Code" --mood="reverent" @@ -695,11 +695,11 @@ await server.connect(transport); ## `qwen mcp` による MCP サーバーの管理 -MCP サーバーの設定は `settings.json` ファイルを直接編集することでいつでも行えますが、CLI はサーバー設定をプログラムで管理するための便利なコマンド群を提供しています。これらのコマンドにより、JSON ファイルを直接編集することなく、MCP サーバーの追加、一覧表示、削除の処理を効率化できます。 +MCP サーバーの設定は `settings.json` ファイルを直接編集することでいつでも行えますが、CLI ではサーバー設定をプログラムで管理するための便利なコマンド群を提供しています。これらのコマンドにより、JSON ファイルを直接編集することなく、MCP サーバーの追加、一覧表示、削除を簡単に行えます。 ### サーバーの追加 (`qwen mcp add`) -`add` コマンドは、新しい MCP サーバーを `settings.json` に設定します。スコープ（`-s, --scope`）に応じて、ユーザー設定の `~/.qwen/settings.json` またはプロジェクト設定の `.qwen/settings.json` ファイルに追加されます。 +`add` コマンドは、新しい MCP サーバーを `settings.json` に設定します。スコープ (`-s, --scope`) に応じて、ユーザー設定 `~/.qwen/settings.json` またはプロジェクト設定 `.qwen/settings.json` ファイルに追加されます。 **コマンド:** @@ -709,7 +709,7 @@ qwen mcp add [options] [args...] - ``: サーバーの一意の名前。 - ``: 実行するコマンド（`stdio` の場合）または URL（`http`/`sse` の場合）。 -- `[args...]`: `stdio` コマンドに渡すオプションの引数。 +- `[args...]`: `stdio` コマンドに渡すオプション引数。 **オプション（フラグ）:** @@ -718,14 +718,14 @@ qwen mcp add [options] [args...] - `-e, --env`: 環境変数を設定（例: -e KEY=value）。 - `-H, --header`: SSE および HTTP 通信で使用する HTTP ヘッダーを設定（例: -H "X-Api-Key: abc123" -H "Authorization: Bearer abc123"）。 - `--timeout`: 接続タイムアウトをミリ秒で設定。 -- `--trust`: サーバーを信頼（すべてのツール呼び出し確認プロンプトをスキップ）。 +- `--trust`: サーバーを信頼（すべてのツール呼び出し確認プロンプトをバイパス）。 - `--description`: サーバーの説明を設定。 - `--include-tools`: 含めるツールのカンマ区切りリスト。 - `--exclude-tools`: 除外するツールのカンマ区切りリスト。 #### stdio サーバーの追加 -これはローカルサーバーを実行するためのデフォルトのトランスポートです。 +ローカルサーバーを実行するためのデフォルトのトランスポートです。 ```bash @@ -741,7 +741,7 @@ qwen mcp add python-server python server.py --port 8080 #### HTTP サーバーの追加 -このトランスポートは、ストリーミング可能な HTTP トランスポートを使用するサーバー向けです。 +ストリーミング可能な HTTP トランスポートを使用するサーバー用のトランスポートです。 ```bash @@ -757,7 +757,7 @@ qwen mcp add --transport http secure-http https://api.example.com/mcp/ --header #### SSE サーバーの追加 -このトランスポートは、Server-Sent Events (SSE) を使用するサーバー向けです。 +Server-Sent Events (SSE) を使用するサーバー用のトランスポートです。 ```bash @@ -769,13 +769,13 @@ qwen mcp add --transport sse # 例: SSE サーバーの追加 qwen mcp add --transport sse sse-server https://api.example.com/sse/ -# 例: 認証ヘッダー付きで SSE サーバーを追加 +# 例: 認証ヘッダー付きの SSE サーバーの追加 qwen mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123" ``` ### サーバー一覧の表示 (`qwen mcp list`) -現在設定されているすべての MCP サーバーを確認するには、`list` コマンドを使用します。各サーバーの名前、設定内容、接続状態が表示されます。 +現在設定されているすべての MCP サーバーを確認するには、`list` コマンドを使用します。各サーバーの名前、設定詳細、接続状態が表示されます。 **コマンド:** @@ -793,7 +793,7 @@ qwen mcp list ### サーバーの削除 (`qwen mcp remove`) -設定からサーバーを削除するには、`remove` コマンドをサーバー名と一緒に使用します。 +設定からサーバーを削除するには、`remove` コマンドをサーバー名と共に使用します。 **コマンド:** @@ -807,4 +807,4 @@ qwen mcp remove qwen mcp remove my-server ``` -これにより、スコープ (`-s, --scope`) に基づいて適切な `settings.json` ファイル内の `mcpServers` オブジェクトから "my-server" のエントリが検索され、削除されます。 \ No newline at end of file +このコマンドは、スコープ (`-s, --scope`) に基づいて適切な `settings.json` ファイル内の `mcpServers` オブジェクトから "my-server" のエントリを見つけて削除します。 \ No newline at end of file diff --git a/website/content/ja/tools/memory.md b/website/content/ja/tools/memory.md index eb2afd4e..f998680a 100644 --- a/website/content/ja/tools/memory.md +++ b/website/content/ja/tools/memory.md @@ -4,19 +4,19 @@ ## 概要 -`save_memory` を使用すると、Qwen Code のセッション間で情報を保存し、後で呼び出すことができます。`save_memory` を使うことで、CLI に重要な詳細情報をセッションをまたいで記憶させ、パーソナライズされた適切なサポートを提供できます。 +`save_memory` を使用すると、Qwen Code セッション間で情報を保存し、後で呼び出すことができます。`save_memory` を使うことで、CLI にセッションをまたいで重要な情報を記憶させ、パーソナライズされた適切なサポートを受けることが可能になります。 ### 引数 `save_memory` は以下の引数を取ります： -- `fact` (string, required): 記憶させたい特定の事実や情報。これは自然言語で書かれた、明確で自己完結的な文である必要があります。 +- `fact` (string, 必須): 記憶させたい具体的な事実や情報。これは自然言語で書かれた、明確で自己完結的な文である必要があります。 ## Qwen Code で `save_memory` を使う方法 このツールは、指定された `fact` をユーザーのホームディレクトリにあるコンテキストファイルに追加します（デフォルトでは `~/.qwen/QWEN.md`）。このファイル名は `contextFileName` で設定可能です。 -追加された事実は、`## Qwen Added Memories` セクションの下に保存されます。このファイルは以降のセッションでコンテキストとして読み込まれ、CLI が保存された情報を呼び出せるようになります。 +追加された情報は、`## Qwen Added Memories` セクションの下に保存されます。このファイルは以降のセッションでコンテキストとして読み込まれるため、CLI が保存された情報を呼び出せるようになります。 使用例： @@ -35,10 +35,10 @@ save_memory(fact="My preferred programming language is Python.") プロジェクト固有の詳細を保存する: ``` -save_memory(fact="The project I'm currently working on is called 'gemini-cli'.") +save_memory(fact="The project I'm currently working on is called 'qwen-code'.") ``` ## 重要な注意点 -- **一般的な使用法:** このツールは、簡潔で重要な事実を保存するために使用してください。大量のデータや会話履歴の保存を目的としていません。 -- **メモリファイル:** メモリファイルはプレーンテキストの Markdown ファイルなので、必要に応じて手動で表示・編集できます。 \ No newline at end of file +- **一般的な使用方法:** このツールは、簡潔で重要な事実を記録するために使用してください。大量のデータや会話履歴の保存には向いていません。 +- **メモリファイル:** メモリファイルはプレーンテキスト形式の Markdown ファイルなので、必要に応じて手動で確認や編集が可能です。 \ No newline at end of file diff --git a/website/content/ja/tools/web-fetch.md b/website/content/ja/tools/web-fetch.md index ea4749e1..cfacaee3 100644 --- a/website/content/ja/tools/web-fetch.md +++ b/website/content/ja/tools/web-fetch.md @@ -4,7 +4,7 @@ ## 概要 -`web_fetch` を使用して、指定された URL からコンテンツを取得し、AI モデルを使って処理します。このツールは、URL と prompt を入力として受け取り、URL のコンテンツを取得し、HTML を markdown に変換した上で、prompt を使って軽量で高速なモデルでコンテンツを処理します。 +`web_fetch` を使用して、指定された URL からコンテンツを取得し、AI モデルを使って処理します。このツールは、URL と prompt を入力として受け取り、URL のコンテンツを取得、HTML を markdown に変換し、そのコンテンツを prompt と一緒に小型で高速なモデルを使って処理します。 ### 引数 @@ -15,40 +15,40 @@ ## Qwen Code で `web_fetch` を使う方法 -Qwen Code で `web_fetch` を使用するには、URL とその URL から抽出したい内容を記述した prompt を指定します。このツールは、URL を取得する前に確認を求めます。確認されると、ツールはコンテンツを直接取得し、AI モデルを使用して処理を行います。 +Qwen Code で `web_fetch` を使用するには、URL とその URL から抽出したい内容を記述した prompt を指定します。このツールは、URL を取得する前に確認を求めます。確認が取れれば、ツールはコンテンツを直接取得し、AI モデルを使って処理を行います。 -このツールは自動的に HTML をテキストに変換し、GitHub の blob URL を処理（raw URL に変換）し、セキュリティのために HTTP URL を HTTPS にアップグレードします。 +このツールは自動的に HTML をテキストに変換し、GitHub の blob URL を raw URL に変換し、セキュリティのために HTTP URL を HTTPS にアップグレードします。 -使用方法: +使用例: ``` web_fetch(url="https://example.com", prompt="Summarize the main points of this article") ``` -## `web_fetch` の使用例 +## `web_fetch` の例 -単一の記事を要約する: +単一の記事を要約する： ``` web_fetch(url="https://example.com/news/latest", prompt="Can you summarize the main points of this article?") ``` -特定の情報を抽出する: +特定の情報を抽出する： ``` web_fetch(url="https://arxiv.org/abs/2401.0001", prompt="What are the key findings and methodology described in this paper?") ``` -GitHub のドキュメントを分析する: +GitHub のドキュメントを分析する： ``` -web_fetch(url="https://github.com/google/gemini-react/blob/main/README.md", prompt="What are the installation steps and main features?") +web_fetch(url="https://github.com/QwenLM/Qwen/blob/main/README.md", prompt="What are the installation steps and main features?") ``` -## 重要な注意点 +## 重要な注意事項 - **単一URL処理:** `web_fetch` は一度に1つのURLを処理します。複数のURLを分析するには、それぞれのURLに対して個別にツールを呼び出してください。 -- **URL形式:** このツールはHTTP URLを自動的にHTTPSにアップグレードし、GitHubのblob URLをraw形式に変換して、より良いコンテンツアクセスを実現します。 +- **URLフォーマット:** このツールはHTTP URLを自動的にHTTPSにアップグレードし、GitHubのblob URLをraw形式に変換して、コンテンツへのアクセスを改善します。 - **コンテンツ処理:** このツールは直接コンテンツを取得し、AIモデルを使用して処理を行い、HTMLを読みやすいテキスト形式に変換します。 - **出力品質:** 出力の品質は、プロンプト内の指示の明確さに依存します。 -- **MCPツール:** MCPが提供するweb fetchツール（"mcp\_\_"で始まるもの）が利用可能な場合、そのツールの使用を推奨します。こちらの方が制限が少ない可能性があります。 \ No newline at end of file +- **MCPツール:** MCPが提供するweb fetchツール（"mcp\_\_"で始まるもの）が利用可能な場合、制限が少ない可能性があるため、そのツールの使用を推奨します。 \ No newline at end of file diff --git a/website/content/ja/troubleshooting.md b/website/content/ja/troubleshooting.md index e22b55e6..29c382b2 100644 --- a/website/content/ja/troubleshooting.md +++ b/website/content/ja/troubleshooting.md @@ -1,22 +1,17 @@ # トラブルシューティングガイド -このガイドでは、以下のような一般的な問題への対処方法とデバッグのヒントを提供します： +このガイドでは、一般的な問題への対処方法とデバッグのヒントを提供します。以下のトピックを含みます： - 認証またはログインエラー -- よくある質問（FAQs） +- よくある質問（FAQ） - デバッグのヒント -- あなたの問題に類似した既存の GitHub Issues、または新しい Issue の作成方法 +- あなたの問題に類似した既存の GitHub Issues または新しい Issues の作成 ## 認証またはログインエラー -- **エラー: `Failed to login. Message: Request contains an invalid argument`** - - 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 を取得することもできます。こちらも別途無料ティアが用意されています。 - - **エラー: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` または `unable to get local issuer certificate`** - - **原因:** SSL/TLS 通信を傍受・検査するファイアウォールがある企業ネットワークにいる可能性があります。このような環境では、Node.js が信頼するカスタムルート CA 証明書が必要になることがよくあります。 - - **解決方法:** `NODE_EXTRA_CA_CERTS` 環境変数に、企業のルート CA 証明書ファイルの絶対パスを設定してください。 + - **原因:** SSL/TLSトラフィックをインターセプトして検査するファイアウォールを持つ企業ネットワークにいる可能性があります。これには、Node.jsが信頼するカスタムルートCA証明書が必要になることがよくあります。 + - **解決方法:** `NODE_EXTRA_CA_CERTS` 環境変数を企業のルートCA証明書ファイルの絶対パスに設定してください。 - 例: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` ## よくある質問 (FAQ) @@ -31,9 +26,10 @@ 詳細については [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` コマンドを使用して、引き続き合計トークン使用量を確認できます。 +- **Q: 統計情報の出力にキャッシュされたトークン数が表示されないのはなぜですか？** + - A: キャッシュされたトークン情報は、キャッシュされたトークンが使用されている場合にのみ表示されます。この機能は API キーのユーザー（Qwen API キーまたは Google Cloud Vertex AI）向けに提供されていますが、OAuth ユーザー（Google Gmail や Google Workspace などの Google 個人/エンタープライズアカウント）には提供されていません。これは Qwen Code Assist API がキャッシュされたコンテンツの作成をサポートしていないためです。`/stats` コマンドを使用して、引き続き合計トークン使用量を確認できます。 +```markdown ## よくあるエラーメッセージと解決方法 - **エラー: MCP サーバー起動時に `EADDRINUSE` (Address already in use) が発生する** @@ -46,9 +42,9 @@ - **解決方法:** Qwen Code のインストール方法に応じて対応してください： - `qwen` をグローバルにインストールした場合、`npm` のグローバルバイナリディレクトリが `PATH` に含まれていることを確認してください。更新はコマンド `npm install -g @qwen-code/qwen-code@latest` で行えます。 - - ソースコードから `qwen` を実行している場合、正しいコマンドで起動しているか確認してください（例: `node packages/cli/dist/index.js ...`）。更新するには、リポジトリから最新の変更を取得し、`npm run build` コマンドで再ビルドしてください。 + - ソースから `qwen` を実行している場合、正しいコマンドで起動しているか確認してください（例: `node packages/cli/dist/index.js ...`）。更新するには、リポジトリから最新の変更を取得し、`npm run build` コマンドで再ビルドしてください。 -- **エラー: `MODULE_NOT_FOUND` や import エラーが発生する** +- **エラー: `MODULE_NOT_FOUND` や import エラー** - **原因:** 依存関係が正しくインストールされていないか、プロジェクトがビルドされていません。 - **解決方法:** 1. `npm install` を実行して、すべての依存関係が揃っていることを確認してください。 @@ -56,20 +52,21 @@ 3. `npm run start` を実行して、ビルドが正常に完了したことを確認してください。 - **エラー: "Operation not permitted"、"Permission denied" などの類似エラー** - - **原因:** サンドボックスが有効な場合、Qwen Code がプロジェクトディレクトリやシステムの一時ディレクトリ以外に書き込もうとするなど、サンドボックス設定によって制限されている操作を試みることがあります。 - - **解決方法:** サンドボックス設定のカスタマイズ方法など詳細については、[Configuration: Sandboxing](./cli/configuration.md#sandboxing) のドキュメントを参照してください。 + - **原因:** サンドボックスが有効な場合、Qwen Code がプロジェクトディレクトリやシステムの一時ディレクトリ以外に書き込もうとするなど、サンドボックス設定によって制限された操作を試みることがあります。 + - **解決方法:** サンドボックス設定のカスタマイズ方法など、詳細については [Configuration: Sandboxing](./cli/configuration.md#sandboxing) のドキュメントを参照してください。 - **CI 環境で Qwen Code がインタラクティブモードで動作しない** - **問題:** `CI_` で始まる環境変数（例: `CI_TOKEN`）が設定されている場合、Qwen Code はインタラクティブモードに入らず（プロンプトが表示されない）、これは内部で使用している UI フレームワークが利用している `is-in-ci` パッケージが、CI 環境と判断するためです。 - - **原因:** `is-in-ci` パッケージは、`CI`、`CONTINUOUS_INTEGRATION`、または `CI_` プレフィックス付きの環境変数が存在するかどうかをチェックします。これらのいずれかが見つかると、環境が非インタラクティブであると判断され、CLI はインタラクティブモードで起動しません。 - - **解決方法:** CLI の動作に `CI_` プレフィックス付きの変数が必要でない場合、コマンド実行時に一時的にその変数を解除できます。例: `env -u CI_TOKEN qwen` + - **原因:** `is-in-ci` パッケージは、`CI`、`CONTINUOUS_INTEGRATION`、または `CI_` プレフィックス付きの環境変数が存在するかどうかをチェックします。これらのいずれかが見つかると、非インタラクティブな CI 環境であると判断され、CLI がインタラクティブモードで起動するのを防ぎます。 + - **解決方法:** `CI_` プレフィックス付きの変数が CLI の動作に必要でない場合、コマンド実行時に一時的にその変数を解除してください。例: `env -u CI_TOKEN qwen` -- **プロジェクトの .env ファイルから DEBUG モードが有効にならない** - - **問題:** プロジェクトの `.env` ファイルに `DEBUG=true` を設定しても、CLI のデバッグモードが有効になりません。 - - **原因:** CLI の動作に干渉するのを防ぐため、`DEBUG` および `DEBUG_MODE` 変数はプロジェクトの `.env` ファイルから自動的に除外されます。 - - **解決方法:** 代わりに `.qwen/.env` ファイルを使用するか、`settings.json` の `excludedProjectEnvVars` 設定で除外する変数を減らすように設定してください。 +- **プロジェクトの .env ファイルから DEBUG モードが動作しない** + - **問題:** プロジェクトの `.env` ファイルで `DEBUG=true` を設定しても、CLI のデバッグモードが有効になりません。 + - **原因:** `DEBUG` および `DEBUG_MODE` 変数は、CLI の動作に干渉するのを防ぐため、プロジェクトの `.env` ファイルからは自動的に除外されます。 + - **解決方法:** 代わりに `.qwen/.env` ファイルを使用するか、`settings.json` の `excludedProjectEnvVars` 設定で除外する変数を減らしてください。 +``` -## IDE Companion が接続されない +## IDE Companion が接続できない場合 - VS Code で単一のワークスペースフォルダが開いていることを確認してください。 - 拡張機能をインストールした後、統合ターミナルを再起動して、以下の環境変数が継承されるようにしてください： @@ -86,16 +83,16 @@ - **Core デバッグ:** - サーバーのコンソール出力を確認し、エラーメッセージやスタックトレースがないかチェックしてください。 - - 設定可能な場合は、ログの詳細レベルを上げてください。 + - 設定可能な場合は、ログの詳細度を上げてください。 - サーバーサイドのコードをステップ実行する必要がある場合は、Node.js のデバッグツール（例: `node --inspect`）を使用してください。 - **ツールの問題:** - - 特定のツールが失敗する場合は、そのツールが実行するコマンドや操作を最もシンプルな形で実行し、問題を切り分けてみてください。 + - 特定のツールが失敗する場合、そのツールが実行するコマンドや操作を最もシンプルな形で実行し、問題を切り分けてみてください。 - `run_shell_command` の場合は、まず直接シェルでコマンドが動作するか確認してください。 - - _ファイルシステムツール_ の場合は、パスが正しいことを確認し、パーミッションもチェックしてください。 + - _ファイルシステム系のツール_ の場合は、パスが正しいこととパーミッションを確認してください。 -- **プレフライトチェック:** - - コードをコミットする前には、必ず `npm run preflight` を実行してください。これにより、フォーマット、リンティング、型エラーなど、多くの一般的な問題を事前に検出できます。 +- **Pre-flight チェック:** + - コードをコミットする前には、必ず `npm run preflight` を実行してください。これにより、フォーマット、Lint、型エラーなど、多くの一般的な問題を事前に検出できます。 ## 既存の GitHub Issues または新しい Issues の作成 diff --git a/website/content/ru/Uninstall.md b/website/content/ru/Uninstall.md index 6b8d495e..35618478 100644 --- a/website/content/ru/Uninstall.md +++ b/website/content/ru/Uninstall.md @@ -4,9 +4,9 @@ ## Метод 1: Использование npx -npx запускает пакеты из временного кэша без постоянной установки. Чтобы "удалить" CLI, нужно очистить этот кэш, что приведет к удалению gemini-cli и любых других пакетов, запущенных ранее через npx. +npx запускает пакеты из временного кэша без постоянной установки. Чтобы "удалить" CLI, необходимо очистить этот кэш, что приведет к удалению qwen-code и любых других пакетов, ранее запущенных с помощью npx. -Кэш npx — это директория `_npx` внутри основной папки кэша npm. Найти путь к кэшу npm можно командой `npm config get cache`. +Кэш npx — это директория с названием `_npx` внутри основной папки кэша npm. Путь к кэшу npm можно найти, выполнив команду `npm config get cache`. **Для macOS / Linux** diff --git a/website/content/ru/checkpointing.md b/website/content/ru/checkpointing.md index c266b092..c12729d0 100644 --- a/website/content/ru/checkpointing.md +++ b/website/content/ru/checkpointing.md @@ -1,22 +1,22 @@ # Checkpointing -Qwen Code включает функцию Checkpointing, которая автоматически сохраняет снимок состояния вашего проекта перед любыми изменениями файлов, внесенными инструментами на базе AI. Это позволяет безопасно экспериментировать и применять изменения в коде, зная, что вы можете мгновенно вернуться к состоянию до запуска инструмента. +Qwen Code включает функцию Checkpointing, которая автоматически сохраняет снимок состояния вашего проекта перед любыми изменениями файлов, внесенными инструментами на базе AI. Это позволяет вам безопасно экспериментировать и применять изменения в коде, зная, что вы можете мгновенно вернуться к состоянию до запуска инструмента. ## Как это работает -Когда вы одобряете инструмент, который изменяет файловую систему (например, `write_file` или `replace`), CLI автоматически создает "checkpoint". Этот checkpoint включает в себя: +Когда вы одобряете инструмент, который изменяет файловую систему (например, `write_file` или `edit`), CLI автоматически создает "checkpoint". Этот checkpoint включает в себя: 1. **Снимок Git:** В специальном скрытом Git-репозитории, расположенном в вашей домашней директории (`~/.qwen/history/`), создается коммит. Данный снимок фиксирует полное состояние файлов вашего проекта на тот момент. Он **не** вмешивается в Git-репозиторий вашего собственного проекта. -2. **История разговора:** Сохраняется вся переписка между вами и агентом до этого момента. -3. **Вызов инструмента:** Также сохраняется конкретный вызов инструмента, который должен был быть выполнен. +2. **История разговора:** Сохраняется вся история общения с агентом до этого момента. +3. **Вызов инструмента:** Также сохраняется конкретный вызов инструмента, который собирался выполниться. Если вы захотите отменить изменения или просто вернуться к предыдущему состоянию, вы можете использовать команду `/restore`. Восстановление checkpoint приведет к: - Откату всех файлов проекта до состояния, зафиксированного в снимке. - Восстановлению истории разговора в CLI. -- Повторному предложению исходного вызова инструмента, что позволит вам снова его выполнить, изменить или просто проигнорировать. +- Повторному предложению оригинального вызова инструмента, что позволит вам снова его выполнить, изменить или просто проигнорировать. -Все данные checkpoint, включая снимок Git и историю разговора, хранятся локально на вашем компьютере. Снимок Git сохраняется в скрытом репозитории, а история разговора и вызовы инструментов — в JSON-файле во временном каталоге проекта, обычно расположенном по адресу `~/.qwen/tmp//checkpoints`. +Все данные checkpoint, включая снимок Git и историю разговора, хранятся локально на вашем компьютере. Снимок Git сохраняется в скрытом репозитории, а история разговора и вызовы инструментов — в JSON-файле во временном каталоге проекта, обычно расположенном по пути `~/.qwen/tmp//checkpoints`. ## Включение функции @@ -72,4 +72,4 @@ CLI отобразит список доступных файлов чекпои /restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file ``` -После выполнения команды ваши файлы и разговор будут немедленно восстановлены до состояния, в котором они находились на момент создания чекпоинта, и исходный prompt инструмента снова появится на экране. \ No newline at end of file +После выполнения команды ваши файлы и разговор будут немедленно восстановлены до состояния на момент создания чекпоинта, а исходный prompt инструмента появится снова. \ No newline at end of file diff --git a/website/content/ru/cli/commands.md b/website/content/ru/cli/commands.md index 2e9657b5..ca8fb04d 100644 --- a/website/content/ru/cli/commands.md +++ b/website/content/ru/cli/commands.md @@ -4,24 +4,24 @@ Qwen Code поддерживает несколько встроенных ко ## Слэш-команды (`/`) -Слэш-команды предоставляют метауровневый контроль над самим CLI. +Слэш-команды предоставляют мета-уровень управления самим CLI. ### Встроенные команды - **`/bug`** - - **Описание:** Создать issue о Qwen Code. По умолчанию issue создается в репозитории GitHub для Qwen Code. Строка, которую вы вводите после `/bug`, становится заголовком создаваемого баг-репорта. Поведение по умолчанию можно изменить с помощью настройки `bugCommand` в файле `.qwen/settings.json`. + - **Описание:** Создать issue о Qwen Code. По умолчанию issue создается в репозитории GitHub проекта Qwen Code. Строка, которую вы вводите после `/bug`, становится заголовком создаваемого баг-репорта. Поведение команды `/bug` можно изменить с помощью настройки `bugCommand` в файле `.qwen/settings.json`. - **`/chat`** - - **Описание:** Сохранить и возобновить историю разговора для интерактивного управления состоянием диалога или восстановления предыдущего состояния из более поздней сессии. + - **Описание:** Сохранить и возобновить историю разговора для интерактивного управления состоянием диалога или восстановления предыдущего состояния в следующей сессии. - **Подкоманды:** - **`save`** - **Описание:** Сохраняет текущую историю разговора. Необходимо указать `` для идентификации состояния диалога. - **Использование:** `/chat save ` - - **Информация о местоположении чекпоинтов:** По умолчанию сохраненные чекпоинты чата находятся в следующих директориях: - - Linux/macOS: `~/.config/google-generative-ai/checkpoints/` - - Windows: `C:\Users\\AppData\Roaming\google-generative-ai\checkpoints\` + - **Детали о местоположении чекпоинтов:** По умолчанию сохраненные чекпоинты чата находятся в следующих директориях: + - Linux/macOS: `~/.config/qwen-code/checkpoints/` + - Windows: `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` - При выполнении `/chat list` CLI сканирует только эти конкретные директории для поиска доступных чекпоинтов. - - **Примечание:** Эти чекпоинты предназначены для ручного сохранения и восстановления состояний диалога. Для автоматических чекпоинтов, созданных перед изменениями файлов, см. [документацию по чекпоинтам](../checkpointing.md). + - **Примечание:** Эти чекпоинты предназначены для ручного сохранения и восстановления состояний диалога. Для автоматических чекпоинтов, создаваемых перед изменениями файлов, см. [документацию по Checkpointing](../checkpointing.md). - **`resume`** - **Описание:** Возобновляет диалог из предыдущего сохранения. - **Использование:** `/chat resume ` @@ -33,10 +33,21 @@ Qwen Code поддерживает несколько встроенных ко - **`/clear`** - **Описание:** Очистить экран терминала, включая видимую историю сессии и прокрутку внутри CLI. Данные сессии (для восстановления истории) могут сохраняться в зависимости от реализации, но визуальное отображение будет очищено. - - **Горячая клавиша:** Нажмите **Ctrl+L** в любое время для выполнения очистки. + - **Горячая клавиша:** Нажмите **Ctrl+L** в любое время для очистки экрана. + +- **`/summary`** + - **Описание:** Генерирует полный обзор проекта на основе текущей истории разговора и сохраняет его в файл `.qwen/PROJECT_SUMMARY.md`. Этот обзор включает общую цель, ключевые знания, последние действия и текущий план, что идеально подходит для возобновления работы в будущих сессиях. + - **Использование:** `/summary` + - **Функции:** + - Анализирует всю историю разговора для извлечения важного контекста + - Создает структурированный markdown-обзор с разделами по целям, знаниям, действиям и планам + - Автоматически сохраняет в `.qwen/PROJECT_SUMMARY.md` в корне проекта + - Показывает индикаторы прогресса во время генерации и сохранения + - Интегрируется с функцией Welcome Back для бесшовного возобновления сессии + - **Примечание:** Эта команда требует активного диалога как минимум с 2 сообщениями для создания содержательного обзора. - **`/compress`** - - **Описание:** Заменить весь контекст чата кратким резюме. Это позволяет экономить токены при выполнении будущих задач, сохраняя при этом высокоуровневое резюме произошедшего. + - **Описание:** Заменяет весь контекст чата кратким обзором. Это позволяет экономить токены при выполнении будущих задач, сохраняя при этом высокоуровневое резюме произошедшего. - **`/copy`** - **Описание:** Копирует последний вывод, сгенерированный Qwen Code, в буфер обмена для удобного обмена или повторного использования. @@ -45,119 +56,143 @@ Qwen Code поддерживает несколько встроенных ко - **Описание:** Управление рабочими директориями для поддержки нескольких директорий. - **Подкоманды:** - **`add`**: - - **Описание:** Добавить директорию в рабочее пространство. Путь может быть абсолютным или относительным к текущей рабочей директории. Также поддерживается ссылка относительно домашней директории. + - **Описание:** Добавляет директорию в рабочее пространство. Путь может быть абсолютным или относительным к текущей рабочей директории. Также поддерживается ссылка относительно домашней директории. - **Использование:** `/directory add ,` - **Примечание:** Отключено в ограниченных профилях песочницы. Если вы используете такой профиль, используйте `--include-directories` при запуске сессии. - **`show`**: - - **Описание:** Отобразить все директории, добавленные через `/directory add` и `--include-directories`. + - **Описание:** Отображает все директории, добавленные через `/directory add` и `--include-directories`. - **Использование:** `/directory show` - **`/directory`** (или **`/dir`**) - **Описание:** Управление рабочими директориями для поддержки нескольких директорий. - **Подкоманды:** - **`add`**: - - **Описание:** Добавить директорию в рабочее пространство. Путь может быть абсолютным или относительным к текущей рабочей директории. Также поддерживается ссылка относительно домашней директории. + - **Описание:** Добавляет директорию в рабочее пространство. Путь может быть абсолютным или относительным к текущей рабочей директории. Также поддерживается ссылка относительно домашней директории. - **Использование:** `/directory add ,` - **Примечание:** Отключено в ограниченных профилях песочницы. Если вы используете такой профиль, используйте `--include-directories` при запуске сессии. - **`show`**: - - **Описание:** Отобразить все директории, добавленные через `/directory add` и `--include-directories`. + - **Описание:** Отображает все директории, добавленные через `/directory add` и `--include-directories`. - **Использование:** `/directory show` - **`/editor`** - - **Описание:** Открыть диалог выбора поддерживаемых редакторов. + - **Описание:** Открывает диалог выбора поддерживаемых редакторов. - **`/extensions`** - - **Описание:** Вывести список всех активных расширений в текущей сессии Qwen Code. См. [Расширения Qwen Code](../extension.md). + - **Описание:** Выводит список всех активных расширений в текущей сессии Qwen Code. См. [Qwen Code Extensions](../extension.md). - **`/help`** (или **`/?`**) - - **Описание:** Отобразить справочную информацию о Qwen Code, включая доступные команды и их использование. + - **Описание:** Отображает справочную информацию о Qwen Code, включая доступные команды и их использование. - **`/mcp`** - - **Описание:** Вывести список настроенных серверов Model Context Protocol (MCP), их статус подключения, информацию о серверах и доступные инструменты. + - **Описание:** Выводит список настроенных серверов Model Context Protocol (MCP), их статус подключения, информацию о серверах и доступные инструменты. - **Подкоманды:** - **`desc`** или **`descriptions`**: - - **Описание:** Показать подробные описания серверов и инструментов MCP. + - **Описание:** Показывает подробные описания серверов и инструментов MCP. - **`nodesc`** или **`nodescriptions`**: - - **Описание:** Скрыть описания инструментов, отображая только их названия. + - **Описание:** Скрывает описания инструментов, отображая только их названия. - **`schema`**: - - **Описание:** Показать полную JSON-схему параметров инструмента. - - **Горячая клавиша:** Нажмите **Ctrl+T** в любое время для переключения между отображением и скрытием описаний инструментов. + - **Описание:** Показывает полную JSON-схему параметров инструмента. + - **Горячая клавиша:** Нажмите **Ctrl+T** в любое время для переключения отображения описаний инструментов. - **`/memory`** - **Описание:** Управление инструкционным контекстом ИИ (иерархическая память, загружаемая по умолчанию из файлов `QWEN.md`; настраивается через `contextFileName`). - **Подкоманды:** - **`add`**: - - **Описание:** Добавляет указанный текст в память ИИ. Использование: `/memory add <текст для запоминания>` + - **Описание:** Добавляет следующий текст в память ИИ. Использование: `/memory add ` - **`show`**: - - **Описание:** Отобразить полное содержимое текущей иерархической памяти, загруженной из всех контекстных файлов (например, `QWEN.md`). Это позволяет проверить инструкционный контекст, передаваемый модели. + - **Описание:** Отображает полное содержимое текущей иерархической памяти, загруженной из всех контекстных файлов (например, `QWEN.md`). Это позволяет проверить инструкционный контекст, передаваемый модели. - **`refresh`**: - - **Описание:** Перезагрузить иерархическую инструкционную память из всех контекстных файлов (по умолчанию: `QWEN.md`), найденных в настроенных местоположениях (глобальные, проект/предки и поддиректории). Это обновляет модель с последними данными контекста. - - **Примечание:** Подробнее о том, как контекстные файлы формируют иерархическую память, см. в [документации по конфигурации CLI](./configuration.md#context-files-hierarchical-instructional-context). + - **Описание:** Перезагружает иерархическую инструкционную память из всех контекстных файлов (по умолчанию: `QWEN.md`), найденных в настроенных местоположениях (глобальные, проект/предки и поддиректории). Это обновляет модель с последним контекстом. + - **Примечание:** За дополнительной информацией о том, как контекстные файлы формируют иерархическую память, см. [документацию по CLI Configuration](./configuration.md#context-files-hierarchical-instructional-context). - **`/restore`** - - **Описание:** Восстанавливает файлы проекта до состояния, в котором они находились непосредственно перед выполнением инструмента. Особенно полезно для отмены изменений файлов, сделанных инструментом. Если команда запущена без ID вызова инструмента, будет выведен список доступных чекпоинтов для восстановления. + - **Описание:** Восстанавливает файлы проекта в состояние, в котором они находились до выполнения инструмента. Особенно полезно для отмены изменений файлов, сделанных инструментом. Если запущено без ID вызова инструмента, выводит список доступных чекпоинтов для восстановления. - **Использование:** `/restore [tool_call_id]` - - **Примечание:** Доступно только при запуске CLI с опцией `--checkpointing` или при настройке через [settings](./configuration.md). Подробнее см. в [документации по чекпоинтам](../checkpointing.md). + - **Примечание:** Доступно только при запуске CLI с опцией `--checkpointing` или настройке через [settings](./configuration.md). См. [документацию по Checkpointing](../checkpointing.md) для подробностей. - **`/settings`** - - **Описание:** Открыть редактор настроек для просмотра и изменения параметров Qwen Code. - - **Подробности:** Эта команда предоставляет удобный интерфейс для изменения настроек, управляющих поведением и внешним видом Qwen Code. Она эквивалентна ручному редактированию файла `.qwen/settings.json`, но с проверкой и подсказками для предотвращения ошибок. - - **Использование:** Просто выполните `/settings`, и откроется редактор. Вы можете просматривать или искать конкретные настройки, видеть их текущие значения и изменять их по желанию. Некоторые настройки применяются сразу, другие требуют перезапуска. + - **Описание:** Открывает редактор настроек для просмотра и изменения параметров Qwen Code. + - **Детали:** Эта команда предоставляет удобный интерфейс для изменения настроек, управляющих поведением и внешним видом Qwen Code. Эквивалентно ручному редактированию файла `.qwen/settings.json`, но с валидацией и подсказками для предотвращения ошибок. + - **Использование:** Просто выполните `/settings`, и откроется редактор. Вы можете просматривать или искать конкретные настройки, видеть их текущие значения и изменять их. Некоторые изменения применяются сразу, другие требуют перезапуска. - **`/stats`** - - **Описание:** Отобразить подробную статистику текущей сессии Qwen Code, включая использование токенов, экономию за счет кэширования токенов (если доступно) и продолжительность сессии. Примечание: информация о кэшированных токенах отображается только при их использовании, что происходит при аутентификации по API-ключу, но не при OAuth-аутентификации. + - **Описание:** Отображает подробную статистику текущей сессии Qwen Code, включая использование токенов, экономию за счет кэширования (если доступно) и продолжительность сессии. Примечание: Информация о кэшированных токенах отображается только при их использовании, что происходит при аутентификации по API-ключу, но не при OAuth-аутентификации. - [**`/theme`**](./themes.md) - - **Описание:** Открыть диалог для изменения визуальной темы Qwen Code. + - **Описание:** Открывает диалог для изменения визуальной темы Qwen Code. - **`/auth`** - - **Описание:** Открыть диалог для изменения метода аутентификации. + - **Описание:** Открывает диалог для изменения метода аутентификации. - **`/about`** - - **Описание:** Показать информацию о версии. Пожалуйста, делитесь этой информацией при создании issue. + - **Описание:** Показывает информацию о версии. Пожалуйста, делитесь этой информацией при создании issue. + +- **`/agents`** + - **Описание:** Управление специализированными AI-подагентами для выполнения конкретных задач. Подагенты — это независимые AI-ассистенты с конкретной экспертизой и доступом к инструментам. + - **Подкоманды:** + - **`create`**: + - **Описание:** Запускает интерактивный мастер создания нового подагента. Мастер помогает выбрать местоположение, сгенерировать промпт с помощью ИИ, выбрать инструменты и настроить внешний вид. + - **Использование:** `/agents create` + - **`manage`**: + - **Описание:** Открывает интерактивный диалог управления для просмотра, редактирования и удаления существующих подагентов. Показывает агентов на уровне проекта и пользователя. + - **Использование:** `/agents manage` + - **Места хранения:** + - **На уровне проекта:** `.qwen/agents/` (общие с командой, имеют приоритет) + - **На уровне пользователя:** `~/.qwen/agents/` (личные агенты, доступны во всех проектах) + - **Примечание:** За подробной информацией о создании и управлении подагентами см. [документацию по Subagents](../subagents.md). - [**`/tools`**](../tools/index.md) - - **Описание:** Отобразить список инструментов, доступных в текущей сессии Qwen Code. + - **Описание:** Отображает список инструментов, доступных в текущей сессии Qwen Code. - **Подкоманды:** - **`desc`** или **`descriptions`**: - - **Описание:** Показать подробные описания каждого инструмента, включая его название и полное описание, переданное модели. + - **Описание:** Показывает подробные описания каждого инструмента, включая его название и полное описание, передаваемое модели. - **`nodesc`** или **`nodescriptions`**: - - **Описание:** Скрыть описания инструментов, отображая только их названия. + - **Описание:** Скрывает описания инструментов, отображая только их названия. - **`/privacy`** - - **Описание:** Отобразить Уведомление о конфиденциальности и позволить пользователям выбрать, согласны ли они на сбор их данных для улучшения сервиса. + - **Описание:** Отображает Уведомление о конфиденциальности и позволяет пользователям выбрать, согласны ли они на сбор их данных для улучшения сервиса. + +- **`/quit-confirm`** + - **Описание:** Показывает диалог подтверждения перед выходом из Qwen Code, позволяя выбрать, как обработать текущую сессию. + - **Использование:** `/quit-confirm` + - **Функции:** + - **Выйти немедленно:** Завершить работу без сохранения (эквивалентно `/quit`) + - **Создать обзор и выйти:** Сгенерировать обзор проекта с помощью `/summary` перед выходом + - **Сохранить диалог и выйти:** Сохранить текущий диалог с автоматически сгенерированным тегом перед выходом + - **Горячая клавиша:** Нажмите **Ctrl+C** дважды для вызова диалога подтверждения выхода + - **Примечание:** Эта команда автоматически вызывается при однократном нажатии Ctrl+C, обеспечивая защиту от случайного выхода. - **`/quit`** (или **`/exit`**) - - **Описание:** Выйти из Qwen Code. + - **Описание:** Немедленно завершает работу Qwen Code без диалога подтверждения. - **`/vim`** - - **Описание:** Включить или отключить режим vim. В режиме vim область ввода поддерживает команды навигации и редактирования в стиле vim в режимах NORMAL и INSERT. + - **Описание:** Включает или выключает режим vim. В режиме vim область ввода поддерживает команды навигации и редактирования в стиле vim в режимах NORMAL и INSERT. - **Функции:** - - **Режим NORMAL:** Навигация с помощью `h`, `j`, `k`, `l`; переход по словам с `w`, `b`, `e`; переход к началу/концу строки с `0`, `$`, `^`; переход к конкретной строке с `G` (или `gg` для первой строки) - - **Режим INSERT:** Стандартный ввод текста с возможностью выхода в режим NORMAL по Escape - - **Команды редактирования:** Удаление с `x`, изменение с `c`, вставка с `i`, `a`, `o`, `O`; сложные операции, такие как `dd`, `cc`, `dw`, `cw` + - **Режим NORMAL:** Навигация с помощью `h`, `j`, `k`, `l`; переход по словам с `w`, `b`, `e`; переход к началу/концу строки с `0`, `$`, `^`; переход к конкретным строкам с `G` (или `gg` для первой строки) + - **Режим INSERT:** Стандартный ввод текста с возможностью выхода в NORMAL по Escape + - **Команды редактирования:** Удаление с `x`, изменение с `c`, вставка с `i`, `a`, `o`, `O`; сложные операции типа `dd`, `cc`, `dw`, `cw` - **Поддержка счетчиков:** Префикс команд цифрами (например, `3h`, `5w`, `10G`) - **Повтор последней команды:** Используйте `.` для повтора последней операции редактирования - **Постоянное сохранение:** Предпочтение режима vim сохраняется в `~/.qwen/settings.json` и восстанавливается между сессиями - - **Индикатор статуса:** При включении отображает `[NORMAL]` или `[INSERT]` в нижнем колонтитуле + - **Индикатор статуса:** При включении показывает `[NORMAL]` или `[INSERT]` в нижнем колонтитуле - **`/init`** - - **Описание:** Анализирует текущую директорию и создает файл контекста `QWEN.md` по умолчанию (или имя файла, указанное в `contextFileName`). Если файл уже существует и не пуст, изменения не вносятся. Команда создает пустой файл и запрашивает у модели заполнение его инструкциями, специфичными для проекта. + - **Описание:** Анализирует текущую директорию и создает файл контекста `QWEN.md` по умолчанию (или имя файла, указанное в `contextFileName`). Если файл уже существует и не пуст, изменения не вносятся. Команда созд ### Пользовательские команды Для быстрого начала работы ознакомьтесь с [примером](#example-a-pure-function-refactoring-command) ниже. -Пользовательские команды позволяют сохранять и повторно использовать ваши любимые или наиболее часто используемые prompts в виде персональных shortcuts внутри Qwen Code. Вы можете создавать команды, специфичные для одного проекта, или команды, доступные глобально во всех ваших проектах, что упрощает ваш рабочий процесс и обеспечивает согласованность. +Пользовательские команды позволяют сохранять и повторно использовать ваши любимые или наиболее часто используемые prompts в виде персональных shortcuts внутри Qwen Code. Вы можете создавать команды, специфичные для одного проекта, или команды, доступные глобально во всех ваших проектах, что упрощает рабочий процесс и обеспечивает согласованность. #### Расположение файлов и приоритет Qwen Code обнаруживает команды из двух мест, загружая их в определённом порядке: -1. **Пользовательские команды (глобальные):** Расположены в `~/.qwen/commands/`. Эти команды доступны в любом проекте, над которым вы работаете. +1. **Пользовательские команды (глобальные):** Расположены в `~/.qwen/commands/`. Эти команды доступны во всех проектах, над которыми вы работаете. 2. **Команды проекта (локальные):** Расположены в `/.qwen/commands/`. Эти команды специфичны для текущего проекта и могут быть добавлены в систему контроля версий, чтобы быть доступными для вашей команды. -Если команда в директории проекта имеет то же имя, что и команда в пользовательской директории, **всегда будет использоваться команда проекта.** Это позволяет проектам переопределять глобальные команды своими версиями, специфичными для проекта. +Если команда в директории проекта имеет то же имя, что и команда в пользовательской директории, **всегда будет использоваться команда проекта.** Это позволяет проектам переопределять глобальные команды своими локальными версиями. #### Именование и пространства имён @@ -166,40 +201,69 @@ Qwen Code обнаруживает команды из двух мест, заг - Файл `~/.qwen/commands/test.toml` становится командой `/test`. - Файл `/.qwen/commands/git/commit.toml` становится командой с пространством имён `/git:commit`. -#### Формат TOML (v1) +#### Формат файла TOML (v1) Файлы определения команд должны быть написаны в формате TOML и иметь расширение `.toml`. ##### Обязательные поля -- `prompt` (String): Prompt, который будет отправлен модели при выполнении команды. Может быть однострочной или многострочной строкой. +- `prompt` (String): Подсказка, которая будет отправлена модели при выполнении команды. Может быть однострочной или многострочной строкой. ##### Необязательные поля -- `description` (String): Краткое описание в одну строку того, что делает команда. Этот текст будет отображаться рядом с вашей командой в меню `/help`. **Если вы опустите это поле, будет сгенерировано общее описание на основе имени файла.** +- `description` (String): Краткое однострочное описание того, что делает команда. Этот текст будет отображаться рядом с вашей командой в меню `/help`. **Если вы опустите это поле, будет сгенерировано общее описание на основе имени файла.** #### Работа с аргументами -Пользовательские команды поддерживают два мощных и удобных метода обработки аргументов. CLI автоматически выбирает правильный метод на основе содержимого `prompt` вашей команды. +Пользовательские команды поддерживают два мощных метода обработки аргументов. CLI автоматически выбирает правильный метод на основе содержимого `prompt` вашей команды. + +##### 1. Контекстно-зависимая инъекция с `{{args}}` -##### 1. Быстрая вставка с помощью `{{args}}` +Если ваш `prompt` содержит специальный placeholder `{{args}}`, CLI заменит этот placeholder на текст, который пользователь ввел после имени команды. -Если ваш `prompt` содержит специальный placeholder `{{args}}`, CLI заменит этот placeholder на весь текст, который пользователь ввел после имени команды. Это идеально подходит для простых, детерминированных команд, где нужно вставить пользовательский ввод в определенное место шаблона prompt. +Поведение этой инъекции зависит от места использования: + +**A. Прямая инъекция (вне shell-команд)** + +Когда используется в основном теле prompt, аргументы инжектируются точно так, как их ввел пользователь. **Пример (`git/fix.toml`):** ```toml -# В: ~/.qwen/commands/git/fix.toml - ```markdown -# Вызывается через: /git:fix "Кнопка смещена на мобильных устройствах" +# Вызывается через: /git:fix "Button is misaligned" + +description = "Генерирует фикс для указанной проблемы." +prompt = "Пожалуйста, предоставьте код фикса для проблемы, описанной здесь: {{args}}." +``` + +Модель получает: `Пожалуйста, предоставьте код фикса для проблемы, описанной здесь: "Button is misaligned".` -description = "Генерирует исправление для указанной проблемы на GitHub." -prompt = "Проанализируй подготовленные изменения в git и предоставь исправление кода для проблемы, описанной здесь: {{args}}." +**B. Использование аргументов в Shell командах (внутри блоков `!{...}`)** + +Когда вы используете `{{args}}` внутри блока инъекции shell (`!{...}`), аргументы автоматически **экранируются для shell** перед подстановкой. Это позволяет безопасно передавать аргументы в shell команды, гарантируя, что результирующая команда будет синтаксически корректной и безопасной, предотвращая уязвимости инъекции команд. + +**Пример (`/grep-code.toml`):** + +```toml +prompt = """ +Пожалуйста, подведите итоги поиска для паттерна `{{args}}`. + +Результаты поиска: +!{grep -r {{args}} .} +""" ``` -Модель получит финальный prompt: `Проанализируй подготовленные изменения в git и предоставь исправление кода для проблемы, описанной здесь: "Кнопка смещена на мобильных устройствах".` +Когда вы запускаете `/grep-code It's complicated`: + +1. CLI видит, что `{{args}}` используется как вне, так и внутри `!{...}`. +2. Вне: Первый `{{args}}` заменяется как есть на `It's complicated`. +3. Внутри: Второй `{{args}}` заменяется на экранированную версию (например, в Linux: `"It's complicated"`). +4. Выполняемая команда: `grep -r "It's complicated" .`. +5. CLI запрашивает у вас подтверждение этой точной и безопасной команды перед выполнением. +6. Финальный prompt отправляется. +``` ##### 2. Обработка аргументов по умолчанию @@ -207,7 +271,7 @@ prompt = "Проанализируй подготовленные изменен Если вы передаёте аргументы команде (например, `/mycommand arg1`), CLI добавит полную команду, которую вы ввели, в конец prompt, отделив её двумя символами новой строки. Это позволяет модели видеть как оригинальные инструкции, так и конкретные аргументы, которые вы только что передали. -Если вы **не** передаёте никаких аргументов (например, `/mycommand`), prompt отправляется модели в точности как есть, без каких-либо дополнений. +Если вы **не** передаёте аргументы (например, `/mycommand`), prompt отправляется модели в точности как есть, без каких-либо дополнений. **Пример (`changelog.toml`):** @@ -224,7 +288,7 @@ prompt = """ # Задача: Обновление Changelog -Вы являетесь экспертом по сопровождению данного программного проекта. Пользователь вызвал команду для добавления новой записи в changelog. +Вы являетесь экспертом по поддержке этого программного проекта. Пользователь вызвал команду для добавления новой записи в changelog. **Необработанная команда пользователя приведена ниже ваших инструкций.** @@ -234,10 +298,11 @@ prompt = """ Команда имеет следующий формат: `/changelog ` - `` должен быть одним из: "added", "changed", "fixed", "removed". +```markdown ## Поведение 1. Прочитать файл `CHANGELOG.md`. 2. Найти секцию для указанной ``. -3. Добавить `` под соответствующий заголовок ``. +3. Добавить `` под правильным заголовком ``. 4. Если секция версии или типа не существует, создать её. 5. Строго придерживаться формата "Keep a Changelog". """ @@ -253,14 +318,11 @@ prompt = """ **Как это работает:** -1. **Внедрение команд:** Используйте синтаксис `!{...}` в вашем `prompt`, чтобы указать, где команда должна быть выполнена и куда внедрить её вывод. -2. **Подтверждение выполнения:** При запуске команды появится диалоговое окно со списком shell-команд, которые prompt хочет выполнить. -3. **Предоставление разрешения:** Вы можете выбрать: - - **Разрешить один раз:** Команда(ы) выполнится(ются) только в этот раз. - - **Разрешить всегда для этой сессии:** Команда(ы) будет(ут) добавлена(ы) во временный allowlist для текущей CLI-сессии и больше не потребует подтверждения. - - **Нет:** Отменить выполнение shell-команд(ы). - -CLI по-прежнему учитывает глобальные настройки `excludeTools` и `coreTools`. Команда будет заблокирована без запроса подтверждения, если она явно запрещена в вашей конфигурации. +1. **Инъекция команд:** Используйте синтаксис `!{...}`. +2. **Подстановка аргументов:** Если внутри блока присутствует `{{args}}`, он автоматически экранируется для shell (см. [Context-Aware Injection](#1-context-aware-injection-with-args) выше). +3. **Надежный парсинг:** Парсер корректно обрабатывает сложные shell-команды, включая вложенные фигурные скобки, например, JSON-полезные нагрузки. +4. **Проверка безопасности и подтверждение:** CLI выполняет проверку безопасности финальной команды (после экранирования и подстановки аргументов). Появится диалог с точной командой(ами), которая будет выполнена. +5. **Выполнение и отчет об ошибках:** Команда выполняется. Если команда завершается с ошибкой, вывод, вставленный в prompt, будет содержать сообщения об ошибках (stderr), за которыми следует строка статуса, например, `[Shell command exited with code 1]`. Это помогает модели понять контекст ошибки. **Пример (`git/commit.toml`):** @@ -284,7 +346,7 @@ prompt = """ """ -``` +```` Когда вы запускаете `/git:commit`, CLI сначала выполняет `git diff --staged`, затем заменяет `!{git diff --staged}` на вывод этой команды перед отправкой финального prompt в модель. @@ -292,9 +354,9 @@ prompt = """ Давайте создадим глобальную команду, которая будет запрашивать у модели рефакторинг фрагмента кода. -**1. Создайте файл и директории:** +**1. Создайте файл и каталоги:** -Сначала убедитесь, что директория пользовательских команд существует, затем создайте поддиректорию `refactor` для организации и конечный TOML-файл. +Сначала убедитесь, что каталог пользовательских команд существует, затем создайте подкаталог `refactor` для организации и конечный TOML-файл. ```bash mkdir -p ~/.qwen/commands/refactor @@ -303,36 +365,37 @@ touch ~/.qwen/commands/refactor/pure.toml **2. Добавьте содержимое в файл:** -Откройте `~/.qwen/commands/refactor/pure.toml` в вашем редакторе и добавьте следующее содержимое. Мы включаем опциональное поле `description` для лучшей практики. +Откройте `~/.qwen/commands/refactor/pure.toml` в вашем редакторе и добавьте следующее содержимое. Мы включаем необязательное поле `description` для лучшей практики. ```toml # In: ~/.qwen/commands/refactor/pure.toml +```markdown # Эта команда будет вызываться через: /refactor:pure -description = "Запрашивает у модели рефакторинг текущего контекста в чистую функцию." +description = "Просит модель рефакторить текущий контекст в чистую функцию (pure function)." prompt = """ -Пожалуйста, проанализируйте код, который я предоставил в текущем контексте. -Выполните его рефакторинг в чистую функцию. +Пожалуйста, проанализируй код, который я предоставил в текущем контексте. +Рефактори его в чистую функцию (pure function). -Ваш ответ должен включать: -1. Блок кода с рефакторингнутой чистой функцией. -2. Краткое объяснение ключевых изменений, которые вы внесли, и почему они способствуют чистоте. +Твой ответ должен включать: +1. Блок кода с рефакторинговой, чистой функцией. +2. Краткое объяснение ключевых изменений, которые ты сделал, и почему они способствуют чистоте функции. """ ``` -**3. Запустите команду:** +**3. Запусти команду:** -Вот и все! Теперь вы можете запустить свою команду в CLI. Сначала вы можете добавить файл в контекст, а затем вызвать команду: +Вот и всё! Теперь ты можешь запустить свою команду в CLI. Сначала можно добавить файл в контекст, а затем вызвать команду: ``` > @my-messy-function.js > /refactor:pure ``` -Qwen Code затем выполнит многострочный prompt, определенный в вашем TOML-файле. +Qwen Code выполнит многострочный prompt, определённый в твоем TOML-файле. ## Команды с @ @@ -342,26 +405,26 @@ Qwen Code затем выполнит многострочный prompt, опр - **Описание:** Вставляет содержимое указанного файла или файлов в ваш текущий запрос. Это удобно, когда вы хотите задать вопрос о конкретном коде, тексте или наборе файлов. - **Примеры:** - `@path/to/your/file.txt Объясни этот текст.` - - `@src/my_project/ Кратко опиши код в этой директории.` - - `О чём этот файл? @README.md` + - `@src/my_project/ Расскажи, что за код лежит в этой директории.` + - `Что это за файл? @README.md` - **Подробности:** - Если указан путь к одному файлу, будет прочитано его содержимое. - - Если указан путь к директории, команда попытается прочитать содержимое файлов в этой директории и всех поддиректориях. + - Если указан путь к директории, команда попытается прочитать содержимое всех файлов в этой директории и её поддиректориях. - Пробелы в путях нужно экранировать обратным слешем (например, `@My\ Documents/file.txt`). - - Внутри команда использует инструмент `read_many_files`. Содержимое считывается и вставляется в ваш запрос перед отправкой модели. + - Внутри команда использует инструмент `read_many_files`. Содержимое файлов подгружается и вставляется в ваш запрос перед отправкой модели. - **Фильтрация с учетом Git:** По умолчанию файлы, игнорируемые Git (например, `node_modules/`, `dist/`, `.env`, `.git/`), исключаются. Это поведение можно изменить через настройку `fileFiltering`. - - **Типы файлов:** Команда предназначена для текстовых файлов. Хотя она может попытаться прочитать любой файл, бинарные или очень большие файлы могут быть пропущены или обрезаны инструментом `read_many_files` ради производительности и релевантности. Инструмент укажет, если какие-то файлы были пропущены. - - **Вывод:** CLI покажет сообщение о вызове инструмента `read_many_files`, с указанием статуса и обработанных путей. + - **Типы файлов:** Команда предназначена для работы с текстовыми файлами. Хотя она может попытаться прочитать любой файл, бинарные или очень большие файлы могут быть пропущены или обрезаны инструментом `read_many_files` ради производительности и релевантности. Инструмент укажет, если какие-то файлы были пропущены. + - **Вывод:** CLI покажет сообщение о вызове инструмента `read_many_files`, с указанием статуса и путей, которые были обработаны. - **`@` (одиночный символ @)** - - **Описание:** Если вы вводите только символ `@` без пути, запрос передается модели как есть. Это может быть полезно, если вы специально говорите _о_ символе `@` в своем запросе. + - **Описание:** Если вы вводите одиночный символ `@` без пути, запрос передаётся модели как есть. Это может быть полезно, если вы специально говорите _о_ символе `@` в своём запросе. ### Обработка ошибок для команд `@` -- Если путь, указанный после `@`, не найден или является недопустимым, будет отображено сообщение об ошибке, и запрос может не быть отправлен в модель, либо он будет отправлен без содержимого файла. +- Если путь, указанный после `@`, не найден или является недопустимым, будет отображено сообщение об ошибке, и запрос может не быть отправлен в модель, либо будет отправлен без содержимого файла. - Если инструмент `read_many_files` столкнется с ошибкой (например, проблемы с правами доступа), это также будет сообщено. -## Режим Shell и команды прямого доступа (`!`) +## Режим Shell и команды прямого выполнения (`!`) Префикс `!` позволяет напрямую взаимодействовать с shell вашей системы прямо из Qwen Code. @@ -371,14 +434,14 @@ Qwen Code затем выполнит многострочный prompt, опр - `!ls -la` (выполняет `ls -la` и возвращается в Qwen Code) - `!git status` (выполняет `git status` и возвращается в Qwen Code) -- **`!` (Переключение режима shell)** +- **`!` (Переключение в режим shell)** - **Описание:** Ввод только символа `!` переключает режим shell. - **Вход в режим shell:** - - При активации режим shell использует другую цветовую схему и "индикатор режима Shell". - - В режиме shell весь вводимый текст интерпретируется непосредственно как команда shell. + - При активации режима shell используется другая цветовая схема и отображается "индикатор режима Shell". + - В режиме shell весь ввод интерпретируется как команды shell. - **Выход из режима shell:** - - При выходе интерфейс возвращается к стандартному виду, и возобновляется обычное поведение Qwen Code. + - При выходе интерфейс возвращается к стандартному виду, и работа Qwen Code продолжается в обычном режиме. -- **Предостережение при использовании `!`:** Команды, выполняемые в режиме shell, имеют те же права доступа и такой же эффект, как если бы вы запускали их напрямую в терминале. +- **Предупреждение по использованию `!`:** Команды, выполняемые в режиме shell, имеют те же права и влияют на систему так же, как если бы вы запускали их напрямую в терминале. -- **Переменная окружения:** Когда команда выполняется через `!` или в режиме shell, в окружении подпроцесса устанавливается переменная `QWEN_CODE=1`. Это позволяет скриптам или инструментам определить, запущены ли они из CLI. \ No newline at end of file +- **Переменная окружения:** При выполнении команды через `!` или в режиме shell в окружении подпроцесса устанавливается переменная `QWEN_CODE=1`. Это позволяет скриптам и инструментам определять, запущены ли они из CLI. \ No newline at end of file diff --git a/website/content/ru/cli/configuration.md b/website/content/ru/cli/configuration.md index 2ddd879e..1a177b53 100644 --- a/website/content/ru/cli/configuration.md +++ b/website/content/ru/cli/configuration.md @@ -1,16 +1,16 @@ -# Настройка Qwen Code +# Конфигурация Qwen Code -Qwen Code предлагает несколько способов настройки поведения приложения, включая переменные окружения, аргументы командной строки и файлы настроек. В этом документе описаны различные методы конфигурации и доступные параметры. +Qwen Code предоставляет несколько способов настройки своего поведения, включая переменные окружения, аргументы командной строки и файлы настроек. В этом документе описаны различные методы конфигурации и доступные параметры. ## Уровни конфигурации -Конфигурация применяется в следующем порядке приоритета (параметры с меньшим номером переопределяются параметрами с большим номером): +Конфигурация применяется в следующем порядке приоритета (параметры с меньшими номерами переопределяются параметрами с большими номерами): 1. **Значения по умолчанию:** Жестко закодированные значения по умолчанию внутри приложения. 2. **Файл пользовательских настроек:** Глобальные настройки для текущего пользователя. 3. **Файл настроек проекта:** Настройки, специфичные для проекта. -4. **Файл системных настроек:** Общесистемные настройки. -5. **Переменные окружения:** Переменные на уровне системы или сессии, которые могут быть загружены из файлов `.env`. +4. **Файл системных настроек:** Настройки на уровне всей системы. +5. **Переменные окружения:** Переменные на уровне всей системы или сессии, потенциально загружаемые из файлов `.env`. 6. **Аргументы командной строки:** Значения, переданные при запуске CLI. ## Файлы настроек @@ -22,10 +22,11 @@ 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/qwen-code/settings.json` (Linux), `C:\ProgramData\qwen-code\settings.json` (Windows) или `/Library/Application Support/QwenCode/settings.json` (macOS). Путь можно изменить с помощью переменной окружения `QWEN_CODE_SYSTEM_SETTINGS_PATH`. + - **Область применения:** Настройки применяются ко всем сессиям Qwen Code в системе, для всех пользователей. Системные настройки переопределяют как пользовательские, так и проектные настройки. Это может быть полезно системным администраторам в корпоративной среде для централизованного управления настройками Qwen Code пользователей. **Примечание о переменных окружения в настройках:** Строковые значения в ваших файлах `settings.json` могут ссылаться на переменные окружения, используя синтаксис `$VAR_NAME` или `${VAR_NAME}`. Эти переменные будут автоматически подставлены при загрузке настроек. Например, если у вас есть переменная окружения `MY_API_TOKEN`, вы можете использовать её в `settings.json` следующим образом: `"apiKey": "$MY_API_TOKEN"`. @@ -37,16 +38,16 @@ Qwen Code использует файлы `settings.json` для хранени ### Доступные настройки в `settings.json`: -- **`contextFileName`** (строка или массив строк): - - **Описание:** Указывает имя файла для контекстных файлов (например, `QWEN.md`, `AGENTS.md`). Может быть одной строкой или списком допустимых имен файлов. +- **`contextFileName`** (string или массив строк): + - **Описание:** Указывает имя файла для контекстных файлов (например, `QWEN.md`, `AGENTS.md`). Может быть одним именем файла или списком допустимых имен файлов. - **По умолчанию:** `QWEN.md` - **Пример:** `"contextFileName": "AGENTS.md"` -- **`bugCommand`** (объект): +- **`bugCommand`** (object): - **Описание:** Переопределяет URL по умолчанию для команды `/bug`. - **По умолчанию:** `"urlTemplate": "https://github.com/QwenLM/qwen-code/issues/new?template=bug_report.yml&title={title}&info={info}"` - **Свойства:** - - **`urlTemplate`** (строка): URL, который может содержать заполнители `{title}` и `{info}`. + - **`urlTemplate`** (string): URL, который может содержать заполнители `{title}` и `{info}`. - **Пример:** ```json "bugCommand": { @@ -54,12 +55,12 @@ Qwen Code использует файлы `settings.json` для хранени } ``` -- **`fileFiltering`** (объект): - - **Описание:** Управляет поведением фильтрации файлов с учетом Git для команд @ и инструментов поиска файлов. +- **`fileFiltering`** (object): + - **Описание:** Управляет поведением фильтрации файлов с учетом 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,13 +70,13 @@ 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` для явного выбора команд, которые могут быть выполнены. @@ -87,16 +88,16 @@ Qwen Code использует файлы `settings.json` для хранени - **`excludeMCPServers`** (массив строк): - **Описание:** Позволяет указать список имен серверов MCP, которые должны быть исключены из модели. Сервер, указанный и в `excludeMCPServers`, и в `allowMCPServers`, будет исключен. Обратите внимание, что это будет проигнорировано, если установлен флаг `--allowed-mcp-server-names`. - - **По умолчанию:** Никакие серверы MCP не исключены. + - **По умолчанию:** Нет исключенных серверов MCP. - **Пример:** `"excludeMCPServers": ["myNodeServer"]`. - **Примечание по безопасности:** Используется простое сопоставление строк по именам серверов MCP, которое может быть изменено. Если вы являетесь системным администратором и хотите предотвратить обход этого ограничения пользователями, рассмотрите возможность настройки `mcpServers` на уровне системных настроек так, чтобы пользователь не мог настроить свои собственные серверы MCP. Это не следует использовать как надежный механизм безопасности. - **`autoAccept`** (boolean): - - **Описание:** Управляет тем, будет ли CLI автоматически принимать и выполнять вызовы инструментов, считающихся безопасными (например, операции только для чтения), без явного подтверждения пользователя. Если установлено значение `true`, CLI пропустит запрос подтверждения для инструментов, считающихся безопасными. + - **Описание:** Управляет тем, будет ли CLI автоматически принимать и выполнять вызовы инструментов, которые считаются безопасными (например, операции только для чтения), без явного подтверждения пользователя. Если установлено значение `true`, CLI пропустит запрос на подтверждение для инструментов, считающихся безопасными. - **По умолчанию:** `false` - **Пример:** `"autoAccept": true` -- **`theme`** (строка): +- **`theme`** (string): - **Описание:** Устанавливает визуальную [тему](./themes.md) для Qwen Code. - **По умолчанию:** `"Default"` - **Пример:** `"theme": "GitHub"` @@ -106,37 +107,41 @@ Qwen Code использует файлы `settings.json` для хранени - **По умолчанию:** `false` - **Пример:** `"vimMode": true` -- **`sandbox`** (boolean или строка): +- **`sandbox`** (boolean или string): - **Описание:** Управляет тем, использовать ли песочницу для выполнения инструментов и как это делать. Если установлено значение `true`, Qwen Code использует предварительно собранный Docker-образ `qwen-code-sandbox`. Дополнительную информацию см. в разделе [Песочница](#sandboxing). - **По умолчанию:** `false` - **Пример:** `"sandbox": "docker"` -- **`toolDiscoveryCommand`** (строка): - - **Описание:** Определяет пользовательскую shell-команду для обнаружения инструментов из вашего проекта. Команда должна возвращать в `stdout` массив [объявлений функций](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations) в формате JSON. Обертки инструментов необязательны. +- **`toolDiscoveryCommand`** (string): + - **Описание:** Определяет пользовательскую shell-команду для обнаружения инструментов из вашего проекта. Команда shell должна возвращать на `stdout` массив JSON [объявлений функций](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). Обертки инструментов являются необязательными. - **По умолчанию:** Пусто - **Пример:** `"toolDiscoveryCommand": "bin/get_tools"` -- **`toolCallCommand`** (строка): - - **Описание:** Определяет пользовательскую shell-команду для вызова конкретного инструмента, обнаруженного с помощью `toolDiscoveryCommand`. Команда должна соответствовать следующим критериям: - - Принимать имя функции (точно как в [объявлении функции](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) в качестве первого аргумента командной строки. - - Читать аргументы функции в формате JSON из `stdin`, аналогично [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). - - Возвращать вывод функции в формате JSON в `stdout`, аналогично [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). +- **`toolCallCommand`** (string): + - **Описание:** Определяет пользовательскую shell-команду для вызова конкретного инструмента, обнаруженного с помощью `toolDiscoveryCommand`. Команда shell должна соответствовать следующим критериям: + - Она должна принимать имя функции (точно как в [объявлении функции](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) в качестве первого аргумента командной строки. + - Она должна читать аргументы функции в формате JSON из `stdin`, аналогично [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). + - Она должна возвращать вывод функции в формате JSON в `stdout`, аналогично [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). - **По умолчанию:** Пусто - **Пример:** `"toolCallCommand": "bin/call_tool"` -- **`mcpServers`** (объект): - - **Описание:** Настраивает подключения к одному или нескольким серверам Model-Context Protocol (MCP) для обнаружения и использования пользовательских инструментов. Qwen Code пытается подключиться к каждому настроенному серверу MCP для обнаружения доступных инструментов. Если несколько серверов MCP предоставляют инструмент с одинаковым именем, имена инструментов будут дополнены псевдонимом сервера, определенным в конфигурации (например, `serverAlias__actualToolName`), чтобы избежать конфликтов. Обратите внимание, что система может удалить некоторые свойства схемы из определений инструментов MCP для обеспечения совместимости. +- **`mcpServers`** (object): + - **Описание:** Настраивает подключения к одному или нескольким серверам Model-Context Protocol (MCP) для обнаружения и использования пользовательских инструментов. Qwen Code пытается подключиться к каждому настроенному серверу MCP для обнаружения доступных инструментов. Если несколько серверов MCP предоставляют инструмент с одинаковым именем, имена инструментов будут дополнены псевдонимом сервера, определенным в конфигурации (например, `serverAlias__actualToolName`), чтобы избежать конфликтов. Обратите внимание, что система может удалить определенные свойства схемы из определений инструментов MCP для совместимости. Необходимо указать хотя бы одно из следующих: `command`, `url` или `httpUrl`. Если указано несколько, приоритет имеет следующий порядок: `httpUrl`, затем `url`, затем `command`. - **По умолчанию:** Пусто - **Свойства:** - - **``** (объект): Параметры сервера для указанного сервера. - - `command` (строка, обязательный): Команда для запуска сервера MCP. - - `args` (массив строк, необязательный): Аргументы, передаваемые команде. - - `env` (объект, необязательный): Переменные окружения, устанавливаемые для процесса сервера. - - `cwd` (строка, необязательный): Рабочая директория, в которой запускается сервер. - - `timeout` (число, необязательный): Таймаут в миллисекундах для запросов к этому серверу MCP. - - `trust` (boolean, необязательный): Доверять этому серверу и обходить все подтверждения вызова инструментов. - - `includeTools` (массив строк, необязательный): Список имен инструментов, которые нужно включить с этого сервера MCP. Если указано, то будут доступны только перечисленные здесь инструменты (поведение белого списка). Если не указано, по умолчанию включаются все инструменты с сервера. - - `excludeTools` (массив строк, необязательный): Список имен инструментов, которые нужно исключить с этого сервера MCP. Перечисленные здесь инструменты не будут доступны модели, даже если они предоставлены сервером. **Примечание:** `excludeTools` имеет приоритет над `includeTools` — если инструмент присутствует в обоих списках, он будет исключен. + - **``** (object): Параметры сервера для указанного сервера. + - `command` (string, необязательно): Команда для запуска сервера MCP через стандартный ввод/вывод. + - `args` (массив строк, необязательно): Аргументы, передаваемые команде. + - `env` (object, необязательно): Переменные окружения, устанавливаемые для процесса сервера. + - `cwd` (string, необязательно): Рабочая директория, в которой запускается сервер. + - `url` (string, необязательно): URL сервера MCP, использующего Server-Sent Events (SSE) для связи. + - `httpUrl` (string, необязательно): URL сервера MCP, использующего потоковое HTTP для связи. + - `headers` (object, необязательно): Карта HTTP-заголовков, отправляемых с запросами к `url` или `httpUrl`. + - `timeout` (number, необязательно): Таймаут в миллисекундах для запросов к этому серверу MCP. + - `trust` (boolean, необязательно): Доверять этому серверу и обходить все подтверждения вызова инструментов. + - `description` (string, необязательно): Краткое описание сервера, которое может использоваться для отображения. + - `includeTools` (массив строк, необязательно): Список имен инструментов, которые следует включить с этого сервера MCP. Если указано, только перечисленные здесь инструменты будут доступны с этого сервера (поведение белого списка). Если не указано, по умолчанию включаются все инструменты с сервера. + - `excludeTools` (массив строк, необязательно): Список имен инструментов, которые следует исключить с этого сервера MCP. Перечисленные здесь инструменты не будут доступны модели, даже если они предоставлены сервером. **Примечание:** `excludeTools` имеет приоритет над `includeTools` — если инструмент присутствует в обоих списках, он будет исключен. - **Пример:** ```json "mcpServers": { @@ -159,28 +164,42 @@ Qwen Code использует файлы `settings.json` для хранени "env": { "API_KEY": "$MY_API_TOKEN" } + }, + "mySseServer": { + "url": "http://localhost:8081/events", + "headers": { + "Authorization": "Bearer $MY_SSE_TOKEN" + }, + "description": "Пример сервера MCP на основе SSE." + }, + "myStreamableHttpServer": { + "httpUrl": "http://localhost:8082/stream", + "headers": { + "X-API-Key": "$MY_HTTP_API_KEY" + }, + "description": "Пример сервера MCP на основе потокового HTTP." } } ``` -- **`checkpointing`** (объект): +- **`checkpointing`** (object): - **Описание:** Настраивает функцию контрольных точек, которая позволяет сохранять и восстанавливать состояния разговора и файлов. Подробнее см. в [документации по контрольным точкам](../checkpointing.md). - **По умолчанию:** `{"enabled": false}` - **Свойства:** - **`enabled`** (boolean): Если `true`, команда `/restore` становится доступной. -- **`preferredEditor`** (строка): - - **Описание:** Указывает предпочитаемый редактор для просмотра diff. +- **`preferredEditor`** (string): + - **Описание:** Указывает предпочтительный редактор для просмотра diff. - **По умолчанию:** `vscode` - **Пример:** `"preferredEditor": "vscode"` -- **`telemetry`** (объект) +- **`telemetry`** (object) - **Описание:** Настраивает сбор логов и метрик для Qwen Code. Подробнее см. в разделе [Телеметрия](../telemetry.md). - **По умолчанию:** `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - **Свойства:** - **`enabled`** (boolean): Включена ли телеметрия. - - **`target`** (строка): Назначение для собранной телеметрии. Поддерживаемые значения: `local` и `gcp`. - - **`otlpEndpoint`** (строка): Конечная точка для OTLP Exporter. + - **`target`** (string): Назначение для собранной телеметрии. Поддерживаемые значения: `local` и `gcp`. + - **`otlpEndpoint`** (string): Конечная точка для экспортера OTLP. - **`logPrompts`** (boolean): Включать ли содержимое пользовательских prompt в логи. - **Пример:** ```json @@ -208,30 +227,7 @@ Qwen Code использует файлы `settings.json` для хранени "hideTips": true ``` -- **`hideBanner`** (boolean): - - **Описание:** Включает или отключает стартовый баннер (ASCII-арт логотип) в интерфейсе CLI. - - **По умолчанию:** `false` - - **Пример:** - - ```json - "hideBanner": true - ``` - -- **`maxSessionTurns`** (число): - - **Описание:** Устанавливает максимальное количество ходов в сессии. Если сессия превышает этот лимит, CLI прекращает обработку и начинает новый чат. - - **По умолчанию:** `-1` (без ограничений) - - **Пример:** - ```json - "maxSessionTurns": 10 - ``` - -- **`summarizeToolOutput`** (объект): - - **Описание:** Включает или отключает суммаризацию вывода инструментов. Вы можете указать бюджет токенов для суммаризации с помощью настройки `tokenBudget`. - - Примечание: В настоящее время поддерживается только инструмент `run_shell_command`. - - **По умолчанию:** `{}` (по умолчанию отключено) - - **Пример:** - ```json - "summarizeToolOutput": { +- ** ### Пример `settings.json`: @@ -278,120 +274,103 @@ CLI сохраняет историю выполненных вами shell-ко - **Расположение:** `~/.qwen/tmp//shell_history` - `` — это уникальный идентификатор, сгенерированный на основе корневого пути вашего проекта. - - История сохраняется в файле с именем `shell_history`. + - История хранится в файле с именем `shell_history`. ## Переменные окружения и файлы `.env` -Переменные окружения — это распространённый способ конфигурации приложений, особенно для чувствительных данных, таких как API ключи, или для настроек, которые могут отличаться в зависимости от среды. +Переменные окружения — это распространённый способ конфигурации приложений, особенно для чувствительных данных, таких как API keys, или для настроек, которые могут отличаться в зависимости от среды. Подробнее о настройке аутентификации можно прочитать в [документации по аутентификации](./authentication.md), где описаны все доступные методы. CLI автоматически загружает переменные окружения из файла `.env`. Порядок загрузки следующий: 1. Файл `.env` в текущей рабочей директории. -2. Если файл не найден, CLI ищет его в родительских директориях, пока не найдёт `.env`, либо не достигнет корня проекта (определяется по наличию папки `.git`) или домашней директории. +2. Если файл не найден, CLI ищет его в родительских директориях, пока не найдёт `.env` или не достигнет корня проекта (определяется по наличию папки `.git`) или домашней директории. 3. Если файл всё ещё не найден, CLI проверяет наличие `~/.env` (в домашней директории пользователя). -**Исключение переменных окружения:** Некоторые переменные (например, `DEBUG` и `DEBUG_MODE`) по умолчанию исключаются из проектных `.env` файлов, чтобы не мешать работе CLI. Переменные из файлов `.qwen/.env` никогда не исключаются. Вы можете настроить это поведение с помощью параметра `excludedProjectEnvVars` в файле `settings.json`. - -- **`GEMINI_API_KEY`** (обязательно): - - Ваш API ключ для Gemini API. - - **Критично для работы.** CLI не будет функционировать без этого ключа. - - Установите его в вашем shell-профиле (например, `~/.bashrc`, `~/.zshrc`) или в файле `.env`. -- **`GEMINI_MODEL`**: - - Указывает модель Gemini по умолчанию. - - Переопределяет жёстко заданную модель по умолчанию. - - Пример: `export GEMINI_MODEL="gemini-2.5-flash"` -- **`GOOGLE_API_KEY`**: - - Ваш API ключ Google Cloud. - - Требуется для использования Vertex AI в express-режиме. - - Убедитесь, что у вас есть необходимые права доступа. - - Пример: `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`. -- **`GOOGLE_CLOUD_PROJECT`**: - - 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`. - - Пример: `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 для телеметрии. - - Пример: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. -- **`GOOGLE_CLOUD_LOCATION`**: - - Регион вашего проекта Google Cloud (например, `us-central1`). - - Требуется для использования Vertex AI в не-express режиме. - - Пример: `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`. +**Исключение переменных окружения:** Некоторые переменные (например, `DEBUG` и `DEBUG_MODE`) по умолчанию исключаются из проектных `.env` файлов, чтобы не мешать работе CLI. Переменные из файлов `.qwen/.env` никогда не исключаются. Это поведение можно настроить с помощью параметра `excludedProjectEnvVars` в файле `settings.json`. + +- **`OPENAI_API_KEY`**: + - Один из доступных [методов аутентификации](./authentication.md). + - Установите в вашем shell-профиле (например, `~/.bashrc`, `~/.zshrc`) или в `.env` файле. +- **`OPENAI_BASE_URL`**: + - Один из доступных [методов аутентификации](./authentication.md). + - Установите в вашем shell-профиле (например, `~/.bashrc`, `~/.zshrc`) или в `.env` файле. +- **`OPENAI_MODEL`**: + - Указывает модель OPENAI по умолчанию. + - Переопределяет значение по умолчанию, заданное в коде. + - Пример: `export OPENAI_MODEL="qwen3-coder-plus"` - **`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`, чтобы включить подробный режим отладки, что может быть полезно при устранении неполадок. - - **Примечание:** Эти переменные по умолчанию исключаются из проектных `.env` файлов, чтобы не мешать работе CLI. Если вам нужно установить их специально для Qwen Code, используйте файлы `.qwen/.env`. + - Установите в `true` или `1`, чтобы включить подробный debug-лог, полезный при отладке. + - **Примечание:** Эти переменные по умолчанию исключаются из проектных `.env` файлов, чтобы не мешать работе CLI. Если нужно задать их для Qwen Code, используйте файлы `.qwen/.env`. - **`NO_COLOR`**: - Установите любое значение, чтобы отключить цветной вывод в CLI. - **`CLI_TITLE`**: - Установите строку, чтобы изменить заголовок CLI. - **`CODE_ASSIST_ENDPOINT`**: - - Указывает endpoint сервера code assist. + - Указывает endpoint для сервера code assist. - Полезно при разработке и тестировании. - **`TAVILY_API_KEY`**: - - Ваш API ключ для сервиса веб-поиска Tavily. - - Требуется для включения функциональности инструмента `web_search`. - - Если не настроено, инструмент веб-поиска будет отключён и пропущен. + - Ваш API key для сервиса веб-поиска Tavily. + - Необходим для включения функциональности инструмента `web_search`. + - Если не задан, инструмент веб-поиска будет отключён и пропущен. - Пример: `export TAVILY_API_KEY="tvly-your-api-key-here"` ## Аргументы командной строки -Аргументы, переданные напрямую при запуске CLI, могут переопределять другие конфигурации для текущей сессии. +Аргументы, переданные напрямую при запуске CLI, могут переопределять другие настройки для текущей сессии. - **`--model `** (**`-m `**): - - Указывает модель Gemini, которая будет использоваться в этой сессии. - - Пример: `npm start -- --model gemini-1.5-pro-latest` + - Указывает, какую модель Qwen использовать в этой сессии. + - Пример: `npm start -- --model qwen3-coder-plus` - **`--prompt `** (**`-p `**): - - Используется для передачи prompt напрямую в команду. Это запускает Qwen Code в неинтерактивном режиме. + - Используется для передачи prompt'а напрямую в команду. Это запускает Qwen Code в неинтерактивном режиме. - **`--prompt-interactive `** (**`-i `**): - - Запускает интерактивную сессию с указанным prompt в качестве начального ввода. - - Prompt обрабатывается в рамках интерактивной сессии, а не до её начала. + - Запускает интерактивную сессию с указанным prompt'ом в качестве начального ввода. + - Prompt обрабатывается внутри интерактивной сессии, а не до неё. - Не может использоваться при передаче ввода через stdin. - Пример: `qwen -i "explain this code"` - **`--sandbox`** (**`-s`**): - - Включает режим sandbox для этой сессии. + - Включает режим песочницы для этой сессии. - **`--sandbox-image`**: - - Устанавливает URI образа sandbox. + - Устанавливает URI образа песочницы. - **`--debug`** (**`-d`**): - - Включает режим отладки для этой сессии, обеспечивая более подробный вывод. + - Включает режим отладки для этой сессии, предоставляя более подробный вывод. - **`--all-files`** (**`-a`**): - - Если установлен, рекурсивно включает все файлы в текущей директории в качестве контекста для prompt. + - Если установлен, рекурсивно включает все файлы в текущей директории в качестве контекста для prompt'а. - **`--help`** (или **`-h`**): - - Отображает справочную информацию об аргументах командной строки. + - Отображает справочную информацию по аргументам командной строки. - **`--show-memory-usage`**: - Отображает текущее использование памяти. - **`--yolo`**: - - Включает режим YOLO, при котором автоматически одобряются все вызовы инструментов. + - Включает режим YOLO, который автоматически одобряет все вызовы инструментов. - **`--approval-mode `**: - - Устанавливает режим подтверждения для вызовов инструментов. Доступные режимы: + - Устанавливает режим подтверждения вызовов инструментов. Доступные режимы: - `default`: Запрашивать подтверждение для каждого вызова инструмента (поведение по умолчанию) - - `auto_edit`: Автоматически одобрять инструменты редактирования (replace, write_file), запрашивать подтверждение для остальных + - `auto_edit`: Автоматически одобрять инструменты редактирования (edit, write_file), запрашивая подтверждение для остальных - `yolo`: Автоматически одобрять все вызовы инструментов (эквивалент `--yolo`) - Не может использоваться вместе с `--yolo`. Используйте `--approval-mode=yolo` вместо `--yolo` для нового унифицированного подхода. - Пример: `qwen --approval-mode auto_edit` - **`--telemetry`**: - Включает [телеметрию](../telemetry.md). - **`--telemetry-target`**: - - Устанавливает цель телеметрии. Подробнее см. в разделе [телеметрия](../telemetry.md). + - Устанавливает цель телеметрии. Подробнее см. в [телеметрии](../telemetry.md). - **`--telemetry-otlp-endpoint`**: - - Устанавливает OTLP endpoint для телеметрии. Подробнее см. в разделе [телеметрия](../telemetry.md). + - Устанавливает OTLP endpoint для телеметрии. Подробнее см. в [телеметрии](../telemetry.md). +- **`--telemetry-otlp-protocol`**: + - Устанавливает OTLP протокол для телеметрии (`grpc` или `http`). По умолчанию — `grpc`. Подробнее см. в [телеметрии](../telemetry.md). - **`--telemetry-log-prompts`**: - - Включает логирование prompt для телеметрии. Подробнее см. в разделе [телеметрия](../telemetry.md). + - Включает логирование prompt'ов для телеметрии. Подробнее см. в [телеметрии](../telemetry.md). - **`--checkpointing`**: - Включает [checkpointing](../checkpointing.md). - **`--extensions `** (**`-e `**): - - Указывает список расширений, которые будут использоваться в сессии. Если не указано, используются все доступные расширения. + - Указывает список расширений для использования в сессии. Если не указано, используются все доступные расширения. - Используйте специальное значение `qwen -e none`, чтобы отключить все расширения. - Пример: `qwen -e my-extension -e my-other-extension` - **`--list-extensions`** (**`-l`**): @@ -400,9 +379,9 @@ 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. @@ -414,9 +393,9 @@ CLI автоматически загружает переменные окру ## Файлы контекста (иерархический instructional context) -Хотя файлы контекста не являются строгой конфигурацией _поведения_ CLI, они играют ключевую роль в настройке _инструкционного контекста_ (также называемого "памятью"). По умолчанию используется файл `QWEN.md`, но имя файла можно изменить с помощью настройки `contextFileName`. Эта мощная функция позволяет передавать ИИ проектные инструкции, руководства по стилю кода или любую другую релевантную информацию, благодаря чему ответы модели становятся более точными и соответствующими вашим потребностям. CLI включает элементы UI, например индикатор в нижнем колонтитуле, показывающий количество загруженных файлов контекста, чтобы вы всегда были в курсе активного контекста. +Хотя файлы контекста не являются строгой конфигурацией _поведения_ CLI, они играют ключевую роль в настройке _инструкционного контекста_ (также называемого "памятью"). По умолчанию используется файл `QWEN.md`, но имя файла можно изменить через настройку `contextFileName`. Эта мощная функция позволяет передавать AI проект-специфичные инструкции, руководства по стилю кода или любую другую релевантную информацию, делая ответы модели более точными и соответствующими вашим потребностям. CLI включает UI-элементы, например, индикатор в нижнем колонтитуле, показывающий количество загруженных файлов контекста, чтобы вы всегда были в курсе активного контекста. -- **Назначение:** Эти Markdown-файлы содержат инструкции, руководящие принципы или контекст, о котором вы хотите, чтобы модель Gemini знала во время взаимодействия. Система спроектирована так, чтобы управлять этим инструкционным контекстом иерархически. +- **Назначение:** Эти Markdown-файлы содержат инструкции, руководящие принципы или контекст, который вы хотите, чтобы модель Qwen учитывала во время взаимодействия. Система спроектирована так, чтобы управлять этим инструкционным контекстом иерархически. ### Пример содержимого контекстного файла (например, `QWEN.md`) @@ -437,46 +416,46 @@ CLI автоматически загружает переменные окру - Используйте 2 пробела для отступов. - Имена интерфейсов должны начинаться с префикса `I` (например, `IUserService`). -- Приватные члены классов должны начинаться с символа подчеркивания (`_`). +- Приватные члены класса должны начинаться с символа подчеркивания (`_`). - Всегда используйте строгое равенство (`===` и `!==`). ## Конкретный компонент: `src/api/client.ts` - Этот файл обрабатывает все исходящие API-запросы. -- При добавлении новых функций для API-вызовов убедитесь, что они включают надежную обработку ошибок и логирование. +- При добавлении новых функций вызова API убедитесь, что они включают надежную обработку ошибок и логирование. - Используйте существующую утилиту `fetchWithRetry` для всех GET-запросов. -``` +```markdown ## О зависимостях: -- Избегайте добавления новых внешних зависимостей, если в этом нет крайней необходимости. +- Избегайте добавления новых внешних зависимостей, если в этом нет абсолютной необходимости. - Если новая зависимость необходима, пожалуйста, укажите причину. -``` -Этот пример демонстрирует, как можно предоставить общий контекст проекта, конкретные соглашения о кодировании, а также заметки о конкретных файлах или компонентах. Чем более релевантными и точными являются ваши контекстные файлы, тем лучше ИИ сможет вам помочь. Настоятельно рекомендуется использовать специфичные для проекта контекстные файлы для установления соглашений и контекста. +Этот пример демонстрирует, как можно предоставить общий контекст проекта, конкретные соглашения по кодированию, а также заметки о конкретных файлах или компонентах. Чем более релевантны и точны ваши контекстные файлы, тем лучше ИИ сможет вам помочь. Мы настоятельно рекомендуем использовать специфичные для проекта контекстные файлы для установления соглашений и контекста. -- **Иерархическая загрузка и приоритет:** CLI реализует сложную иерархическую систему памяти, загружая контекстные файлы (например, `QWEN.md`) из нескольких источников. Содержимое файлов, находящихся ниже в этом списке (более специфичные), обычно переопределяет или дополняет содержимое файлов выше (более общих). Точный порядок объединения и финальный контекст можно проверить с помощью команды `/memory show`. Типичный порядок загрузки следующий: +- **Иерархическая загрузка и приоритет:** CLI реализует сложную иерархическую систему памяти, загружая контекстные файлы (например, `QWEN.md`) из нескольких источников. Содержимое файлов, находящихся ниже в этом списке (более специфичных), обычно переопределяет или дополняет содержимое файлов выше (более общих). Точный порядок объединения и финальный контекст можно проверить с помощью команды `/memory show`. Типичный порядок загрузки следующий: 1. **Глобальный контекстный файл:** - Расположение: `~/.qwen/` (например, `~/.qwen/QWEN.md` в вашем домашнем каталоге пользователя). - Область применения: Предоставляет стандартные инструкции для всех ваших проектов. 2. **Контекстные файлы корня проекта и его предков:** - - Расположение: CLI ищет указанный контекстный файл в текущей рабочей директории, а затем в каждой родительской директории вплоть до корня проекта (определяемого папкой `.git`) или вашего домашнего каталога. + - Расположение: CLI ищет указанный контекстный файл в текущем рабочем каталоге, а затем в каждом родительском каталоге вплоть до корня проекта (определяемого папкой `.git`) или вашего домашнего каталога. - Область применения: Предоставляет контекст, относящийся ко всему проекту или значительной его части. 3. **Контекстные файлы подкаталогов (локальные/контекстуальные):** - - Расположение: CLI также сканирует наличие указанного контекстного файла в подкаталогах _ниже_ текущей рабочей директории (с учетом стандартных шаблонов игнорирования, таких как `node_modules`, `.git` и т.д.). По умолчанию глубина поиска ограничена 200 каталогами, но может быть изменена с помощью поля `memoryDiscoveryMaxDirs` в вашем файле `settings.json`. - - Область применения: Позволяет задать очень специфичные инструкции, относящиеся к конкретному компоненту, модулю или разделу проекта. + - Расположение: CLI также сканирует наличие указанного контекстного файла в подкаталогах _ниже_ текущего рабочего каталога (с учетом стандартных игнорируемых паттернов, таких как `node_modules`, `.git` и т.д.). По умолчанию глубина поиска ограничена 200 каталогами, но может быть изменена с помощью поля `memoryDiscoveryMaxDirs` в вашем файле `settings.json`. + - Область применения: Позволяет задавать очень специфичные инструкции, относящиеся к конкретному компоненту, модулю или разделу проекта. - **Объединение и отображение в интерфейсе:** Содержимое всех найденных контекстных файлов объединяется (с разделителями, указывающими их источник и путь) и передается как часть системного prompt'а. В нижнем колонтитуле CLI отображается количество загруженных контекстных файлов — это позволяет быстро визуально оценить активный инструкционный контекст. - **Импорт содержимого:** Вы можете модуляризировать свои контекстные файлы, импортируя другие Markdown-файлы с помощью синтаксиса `@path/to/file.md`. Подробнее см. в [документации Memory Import Processor](../core/memport.md). - **Команды управления памятью:** - Используйте `/memory refresh`, чтобы принудительно пересканировать и перезагрузить все контекстные файлы из всех настроенных источников. Это обновит инструкционный контекст ИИ. - Используйте `/memory show`, чтобы отобразить текущий объединённый инструкционный контекст, что позволит вам проверить иерархию и содержимое, используемое ИИ. - - Полное описание команды `/memory` и её подкоманд (`show` и `refresh`) см. в [документации по командам](./commands.md#memory). + - Полная информация о команде `/memory` и её подкомандах (`show` и `refresh`) доступна в [документации по командам](./commands.md#memory). Понимая и используя эти уровни конфигурации и иерархическую природу контекстных файлов, вы сможете эффективно управлять памятью ИИ и адаптировать ответы Qwen Code под ваши конкретные нужды и проекты. +``` ## Sandboxing -Qwen Code может выполнять потенциально небезопасные операции (например, shell-команды и изменения файлов) в sandbox-окружении, чтобы защитить вашу систему. +Qwen Code может выполнять потенциально небезопасные операции (например, shell-команды и модификации файлов) в sandbox-окружении, чтобы защитить вашу систему. По умолчанию sandboxing отключен, но вы можете включить его несколькими способами: @@ -486,7 +465,7 @@ Qwen Code может выполнять потенциально небезоп По умолчанию используется готовый Docker-образ `qwen-code-sandbox`. -Если вашему проекту требуется особое sandbox-окружение, вы можете создать собственный Dockerfile по пути `.qwen/sandbox.Dockerfile` в корневой директории проекта. Этот Dockerfile может быть основан на базовом sandbox-образе: +Если вашему проекту нужны особые настройки sandboxing, вы можете создать собственный Dockerfile по пути `.qwen/sandbox.Dockerfile` в корневой директории проекта. Этот Dockerfile может быть основан на базовом sandbox-образе: ```dockerfile FROM qwen-code-sandbox @@ -513,14 +492,14 @@ BUILD_SANDBOX=1 qwen -s **Что мы собираем:** -- **Вызовы инструментов:** Мы записываем названия вызываемых инструментов, информацию об успешном или неудачном выполнении и время их выполнения. Мы не собираем аргументы, передаваемые инструментам, или любые данные, возвращаемые ими. -- **API запросы:** Мы записываем модель, использованную для каждого запроса, продолжительность запроса и информацию об успешном или неудачном выполнении. Мы не собираем содержимое промптов или ответов. +- **Вызовы инструментов:** Мы записываем названия вызванных инструментов, успешность их выполнения и время выполнения. Мы не собираем аргументы, переданные инструментам, или любые данные, возвращенные ими. +- **API-запросы:** Мы записываем модель, использованную для каждого запроса, продолжительность запроса и его успешность. Мы не собираем содержимое промтов или ответов. - **Информация о сессии:** Мы собираем информацию о конфигурации CLI, например, включенные инструменты и режим подтверждения. **Что мы НЕ собираем:** -- **Персональные данные (PII):** Мы не собираем никакой личной информации, такой как ваше имя, адрес электронной почты или API ключи. -- **Содержимое промптов и ответов:** Мы не записываем содержимое ваших промптов или ответов модели. +- **Персональные данные (PII):** Мы не собираем никакой личной информации, такой как ваше имя, адрес электронной почты или API-ключи. +- **Содержимое промтов и ответов:** Мы не записываем содержимое ваших промтов или ответов модели. - **Содержимое файлов:** Мы не записываем содержимое файлов, которые читаются или записываются CLI. **Как отказаться от сбора:** @@ -533,4 +512,12 @@ BUILD_SANDBOX=1 qwen -s } ``` -Примечание: Когда сбор статистики использования включен, события отправляются на endpoint сбора данных Alibaba Cloud RUM. \ No newline at end of file +Примечание: Когда статистика использования включена, события отправляются на эндпоинт сбора Alibaba Cloud RUM. + +- **`enableWelcomeBack`** (boolean): + - **Описание:** Показывать диалог приветствия при возвращении в проект с историей разговора. + - **По умолчанию:** `true` + - **Категория:** UI + - **Требуется перезапуск:** Нет + - **Пример:** `"enableWelcomeBack": false` + - **Подробности:** Если включено, Qwen Code автоматически определит, возвращаетесь ли вы в проект с ранее сгенерированным сводным файлом проекта (`.qwen/PROJECT_SUMMARY.md`), и покажет диалог, позволяющий продолжить предыдущий разговор или начать заново. Эта функция интегрируется с командой `/chat summary` и диалогом подтверждения выхода. Подробнее см. в [документации Welcome Back](./welcome-back.md). \ No newline at end of file diff --git a/website/content/ru/cli/index.md b/website/content/ru/cli/index.md index 255d8221..ec2861d7 100644 --- a/website/content/ru/cli/index.md +++ b/website/content/ru/cli/index.md @@ -1,15 +1,16 @@ # Qwen Code CLI -В Qwen Code `packages/cli` — это интерфейс для пользователей, с помощью которого можно отправлять и получать промпты от Qwen и других AI-моделей, а также взаимодействовать с их инструментами. Общее описание Qwen Code см. на [главной странице документации](../index.md). +В Qwen Code, `packages/cli` — это интерфейс для пользователей, позволяющий отправлять и получать промпты с Qwen и другими AI-моделями, а также взаимодействовать с их инструментами. Общее описание Qwen Code можно найти на [главной странице документации](../index.md). ## Навигация по разделу -- **[Аутентификация](./authentication.md):** Руководство по настройке аутентификации с помощью Qwen OAuth и провайдеров, совместимых с OpenAI. +- **[Аутентификация](./authentication.md):** Руководство по настройке аутентификации с помощью Qwen OAuth и совместимых с OpenAI провайдеров. - **[Команды](./commands.md):** Справочник по командам Qwen Code CLI (например, `/help`, `/tools`, `/theme`). - **[Конфигурация](./configuration.md):** Руководство по настройке поведения Qwen Code CLI с помощью конфигурационных файлов. - **[Кэширование токенов](./token-caching.md):** Оптимизация затрат на API за счёт кэширования токенов. - **[Темы](./themes.md):** Руководство по кастомизации внешнего вида CLI с помощью различных тем. - **[Туториалы](tutorials.md):** Туториал, показывающий, как использовать Qwen Code для автоматизации задач разработки. +- **[Welcome Back](./welcome-back.md):** Узнайте о функции Welcome Back, которая помогает вам бесшовно продолжать работу между сессиями. ## Режим без интерактивного взаимодействия diff --git a/website/content/ru/cli/token-caching.md b/website/content/ru/cli/token-caching.md index c6b8dbd3..3eec14a4 100644 --- a/website/content/ru/cli/token-caching.md +++ b/website/content/ru/cli/token-caching.md @@ -1,14 +1,14 @@ -# Кэширование токенов и оптимизация затрат +# Кэширование токенов и оптимизация расходов -Qwen Code автоматически оптимизирует затраты на API через кэширование токенов при использовании аутентификации по API-ключу (например, провайдеры, совместимые с OpenAI). Эта функция повторно использует предыдущие системные инструкции и контекст, чтобы уменьшить количество токенов, обрабатываемых в последующих запросах. +Qwen Code автоматически оптимизирует API расходы за счёт кэширования токенов при использовании аутентификации по API ключу (например, провайдеры, совместимые с OpenAI). Эта функция повторно использует предыдущие системные инструкции и контекст, чтобы уменьшить количество токенов, обрабатываемых в последующих запросах. **Кэширование токенов доступно для:** -- Пользователей API-ключей (Gemini API key) -- Пользователей Vertex AI (с настройкой проекта и локации) +- Пользователей API ключей (Qwen API key) +- Пользователей Vertex AI (с настроенным проектом и регионом) **Кэширование токенов недоступно для:** -- Пользователей OAuth (личные/корпоративные аккаунты Google) - Code Assist API пока не поддерживает создание кэшированного контента +- Пользователей OAuth (личные/корпоративные аккаунты Google) — Code Assist API пока не поддерживает создание кэшированного контента -Вы можете просмотреть использование токенов и экономию за счет кэшированных токенов с помощью команды `/stats`. Когда кэшированные токены доступны, они будут отображаться в выводе статистики. \ No newline at end of file +Вы можете посмотреть статистику использования токенов и экономию за счёт кэширования с помощью команды `/stats`. Когда закэшированные токены доступны, они будут отображены в выводе статистики. \ No newline at end of file diff --git a/website/content/ru/cli/welcome-back.md b/website/content/ru/cli/welcome-back.md new file mode 100644 index 00000000..6c4ac558 --- /dev/null +++ b/website/content/ru/cli/welcome-back.md @@ -0,0 +1,133 @@ +# Функция Welcome Back + +Функция Welcome Back помогает вам без проблем возобновить работу, автоматически обнаруживая, когда вы возвращаетесь в проект с существующей историей разговора, и предлагая продолжить с того места, где вы остановились. + +## Обзор + +Когда вы запускаете Qwen Code в каталоге проекта, который содержит ранее сгенерированное описание проекта (`.qwen/PROJECT_SUMMARY.md`), диалог Welcome Back автоматически появляется, предлагая вам выбрать: начать заново или продолжить предыдущий разговор. + +## Как это работает + +### Автоматическое обнаружение + +Функция Welcome Back автоматически обнаруживает: + +- **Файл описания проекта:** Ищет `.qwen/PROJECT_SUMMARY.md` в текущем каталоге проекта +- **Историю разговора:** Проверяет, есть ли значимая история разговора для возобновления +- **Настройки:** Учитывает вашу настройку `enableWelcomeBack` (включена по умолчанию) + +### Диалог возврата + +Когда сводка проекта найдена, вы увидите диалог с: + +- **Время последнего обновления:** Показывает, когда сводка была последний раз сгенерирована +- **Общая цель:** Отображает основную задачу из вашей предыдущей сессии +- **Текущий план:** Показывает прогресс задач со статусами: + - `[DONE]` - Завершенные задачи + - `[IN PROGRESS]` - Задачи в работе + - `[TODO]` - Запланированные задачи +- **Статистика задач:** Сводка по общему количеству задач, завершенным, в работе и ожидающим + +### Опции + +У вас есть два варианта, когда появляется диалог возврата: + +1. **Начать новую сессию чата** + - Закрывает диалог и начинает новый разговор + - Предыдущий контекст не загружается + +2. **Продолжить предыдущий разговор** + - Автоматически заполняет поле ввода следующим: `@.qwen/PROJECT_SUMMARY.md, Based on our previous conversation, Let's continue?` + - Загружает сводку проекта как контекст для AI + - Позволяет вам бесшовно продолжить с того места, где вы остановились + +## Конфигурация + +### Включение/отключение Welcome Back + +Вы можете управлять функцией Welcome Back через настройки: + +**Через диалог настроек:** + +1. Выполните `/settings` в Qwen Code +2. Найдите "Enable Welcome Back" в категории UI +3. Переключите настройку вкл/выкл + +**Через файл настроек:** +Добавьте в ваш `.qwen/settings.json`: + +```json +{ + "enableWelcomeBack": true +} +``` + +**Расположение настроек:** + +- **Пользовательские настройки:** `~/.qwen/settings.json` (влияет на все проекты) +- **Настройки проекта:** `.qwen/settings.json` (специфично для проекта) + +### Горячие клавиши + +- **Escape:** Закрыть диалог Welcome Back (по умолчанию "Start new chat session") + +## Интеграция с другими функциями + +### Генерация сводки проекта + +Функция Welcome Back без проблем работает с командой `/chat summary`: + +1. **Генерация сводки:** Используйте `/chat summary`, чтобы создать сводку проекта +2. **Автоматическое обнаружение:** Когда вы в следующий раз запустите Qwen Code в этом проекте, Welcome Back автоматически обнаружит сводку +3. **Продолжение работы:** Выберите продолжение, и сводка будет загружена как контекст + +### Подтверждение выхода + +При выходе с помощью `/quit-confirm` и выборе опции "Generate summary and quit" ("Создать сводку и выйти"): + +1. Сводка проекта создаётся автоматически +2. При следующем сеансе появится диалог Welcome Back +3. Вы сможете бесшовно продолжить свою работу + +## Структура файлов + +Функция Welcome Back создаёт и использует следующие файлы: + +``` +your-project/ +├── .qwen/ +│ └── PROJECT_SUMMARY.md # Сгенерированная сводка проекта +``` + +### Формат PROJECT_SUMMARY.md + +Сгенерированная сводка имеет следующую структуру: + +```markdown + +# Project Summary + +## Overall Goal + + + +## Ключевые знания + + + + +## Последние действия + + + + +## Текущий план + + + + +--- + +## Метаданные сводки + +**Время обновления**: 2025-01-10T15:30:00.000Z \ No newline at end of file diff --git a/website/content/ru/deployment.md b/website/content/ru/deployment.md index a4f4829a..baee44a3 100644 --- a/website/content/ru/deployment.md +++ b/website/content/ru/deployment.md @@ -1,6 +1,6 @@ # Выполнение и развертывание Qwen Code -Этот документ описывает, как запустить Qwen Code, и объясняет архитектуру развертывания, которую использует Qwen Code. +В этом документе описано, как запустить Qwen Code, и объясняется архитектура развертывания, которую использует Qwen Code. ## Запуск Qwen Code @@ -27,7 +27,7 @@ - **Запуск через NPX:** ```bash - # Запустить последнюю версию из NPM без глобальной установки + # Выполнить последнюю версию из NPM без глобальной установки npx @qwen-code/qwen-code ``` @@ -35,18 +35,18 @@ ### 2. Запуск в песочнице (Docker/Podman) -Для обеспечения безопасности и изоляции Qwen Code можно запускать внутри контейнера. Это способ по умолчанию, который CLI использует для выполнения инструментов, которые могут иметь побочные эффекты. +Для обеспечения безопасности и изоляции Qwen Code можно запускать внутри контейнера. Это способ запуска CLI по умолчанию для инструментов, которые могут иметь побочные эффекты. - **Прямой запуск из Registry:** - Вы можете запустить опубликованный образ песочницы напрямую. Это удобно для сред, где у вас есть только Docker и вы хотите запустить CLI. + Вы можете запустить опубликованный образ песочницы напрямую. Это удобно в средах, где установлен только Docker, и вы хотите запустить CLI. ```bash # Запуск опубликованного образа песочницы - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.9 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 ``` - **Использование флага `--sandbox`:** - Если у вас локально установлен Qwen Code (с использованием стандартной установки, описанной выше), вы можете указать ему запускаться внутри контейнера песочницы. + Если у вас локально установлен Qwen Code (стандартной установкой, описанной выше), вы можете указать ему запускаться внутри контейнера песочницы. ```bash - qwen --sandbox -y -p "ваш промт здесь" + qwen --sandbox -y -p "your prompt here" ``` --- @@ -62,13 +62,13 @@ npm run start ``` - **Production-подобный режим (Linked package):** - Этот метод имитирует глобальную установку, связывая ваш локальный пакет. Полезно для тестирования локальной сборки в production-сценарии. + Этот метод имитирует глобальную установку путем линковки вашего локального пакета. Полезно для тестирования локальной сборки в production-подобном workflow. ```bash - # Связываем локальный cli-пакет с глобальным node_modules + # Линкуем локальный cli пакет в глобальный node_modules npm link packages/cli - # Теперь вы можете запускать свою локальную версию с помощью команды `qwen` + # Теперь вы можете запускать вашу локальную версию с помощью команды `qwen` qwen ``` @@ -76,7 +76,7 @@ ### 4. Запуск последнего коммита Qwen Code из GitHub -Вы можете запустить самую свежую версию Qwen Code напрямую из репозитория на GitHub. Это удобно для тестирования функций, находящихся в разработке. +Вы можете запустить самую свежую версию Qwen Code напрямую из репозитория на GitHub. Это удобно для тестирования функций, которые еще находятся в разработке. ```bash @@ -93,7 +93,7 @@ npx https://github.com/QwenLM/qwen-code Проект Qwen Code представляет собой монорепозиторий, который публикует основные пакеты в реестре NPM: - `@qwen-code/qwen-code-core`: Бэкенд, обрабатывающий логику и выполнение инструментов. -- `@qwen-code/qwen-code`: Фронтенд, ориентированный на пользователя. +- `@qwen-code/qwen-code`: Фронтенд, взаимодействующий с пользователем. Эти пакеты используются при выполнении стандартной установки и при запуске Qwen Code из исходного кода. @@ -105,7 +105,7 @@ npx https://github.com/QwenLM/qwen-code - **Выполнение через `npx` из GitHub:** При запуске последней версии Qwen Code напрямую из GitHub запускается другой процесс, инициируемый скриптом `prepare` в `package.json`. Этот скрипт использует `esbuild` для сборки всего приложения и его зависимостей в один автономный JavaScript-файл. Эта сборка создается «на лету» на машине пользователя и не добавляется в репозиторий. -**Образ песочницы Docker** +**Docker-образ песочницы** Метод выполнения на основе Docker поддерживается образом контейнера `qwen-code-sandbox`. Этот образ публикуется в реестре контейнеров и содержит предустановленную глобальную версию Qwen Code. @@ -113,6 +113,6 @@ npx https://github.com/QwenLM/qwen-code Процесс релиза автоматизирован с помощью GitHub Actions. Workflow релиза выполняет следующие действия: -1. Собирает NPM пакеты с использованием `tsc`. -2. Публикует NPM пакеты в реестре артефактов. -3. Создает релизы GitHub с bundled assets. \ No newline at end of file +1. Собирает NPM пакеты с использованием `tsc`. +2. Публикует NPM пакеты в реестре артефактов. +3. Создает релизы GitHub с приложенными бандлами. \ No newline at end of file diff --git a/website/content/ru/ide-integration.md b/website/content/ru/ide-integration.md index 8476fcf4..16ca9134 100644 --- a/website/content/ru/ide-integration.md +++ b/website/content/ru/ide-integration.md @@ -1,35 +1,35 @@ # Интеграция с IDE -Gemini CLI может интегрироваться с вашей IDE для более удобной и контекстно-зависимой работы. Эта интеграция позволяет CLI лучше понимать ваш workspace и включает мощные функции, такие как native in-editor diffing. +Qwen Code можно интегрировать с вашей IDE для более удобной и контекстно-зависимой работы. Такая интеграция позволяет CLI лучше понимать ваше рабочее пространство и включает мощные функции, такие как native in-editor diffing. На данный момент единственной поддерживаемой IDE является [Visual Studio Code](https://code.visualstudio.com/), а также другие редакторы, которые поддерживают расширения VS Code. ## Возможности -- **Контекст рабочей области:** CLI автоматически получает информацию о вашей рабочей области для предоставления более релевантных и точных ответов. Этот контекст включает: +- **Контекст рабочей области:** CLI автоматически получает информацию о вашей рабочей области, чтобы предоставлять более релевантные и точные ответы. Этот контекст включает: - **10 последних открытых файлов** в вашей рабочей области. - Активную позицию курсора. - - Любой выделенный текст (до 16 КБ; более длинные выделения будут обрезаны). + - Любой выделенный текст (до лимита 16 КБ; более длинные выделения будут обрезаны). -- **Встроенный diff:** Когда Gemini предлагает изменения в коде, вы можете просматривать эти изменения прямо во встроенном diff-редакторе вашей IDE. Это позволяет легко просматривать, редактировать, а также принимать или отклонять предложенные изменения. +- **Встроенный diff:** Когда Qwen предлагает изменения в коде, вы можете просматривать эти изменения прямо во встроенном 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`: Открывает уведомления о сторонних библиотеках, используемых в расширении. +- **Команды VS Code:** Вы можете получить доступ к функциям Qwen Code прямо из палитры команд VS Code (`Cmd+Shift+P` или `Ctrl+Shift+P`): + - `Qwen Code: Run`: Запускает новую сессию Qwen Code во встроенном терминале. + - `Qwen Code: Accept Diff`: Принимает изменения в активном diff-редакторе. + - `Qwen Code: Close Diff Editor`: Отклоняет изменения и закрывает активный diff-редактор. + - `Qwen Code: View Third-Party Notices`: Отображает уведомления о сторонних библиотеках для расширения. ## Установка и настройка Есть три способа настроить интеграцию с IDE: -### 1. Автоматическое подключение (рекомендуется) +### 1. Автоматический запрос (рекомендуется) -Когда вы запускаете Gemini CLI внутри поддерживаемого редактора, он автоматически определит вашу среду и предложит подключиться. Если вы ответите «Да», автоматически выполнится необходимая настройка, включая установку расширения-компаньона и включение соединения. +Когда вы запускаете Qwen Code внутри поддерживаемого редактора, он автоматически определит ваше окружение и предложит подключиться. Если вы ответите "Yes", необходимая настройка будет выполнена автоматически, включая установку соответствующего расширения и включение соединения. ### 2. Ручная установка через CLI -Если вы ранее отклонили запрос или хотите установить расширение вручную, вы можете выполнить следующую команду внутри Gemini CLI: +Если вы ранее отклонили запрос или хотите установить расширение вручную, вы можете выполнить следующую команду внутри Qwen Code: ``` /ide install @@ -41,10 +41,10 @@ Gemini CLI может интегрироваться с вашей IDE для б Вы также можете установить расширение напрямую из маркетплейса. -- **Для 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). Следуйте инструкциям вашего редактора для установки расширений из этого реестра. +- **Для Visual Studio Code:** Установите из [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion). +- **Для форков VS Code:** Чтобы поддерживать форки VS Code, расширение также опубликовано в [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion). Следуйте инструкциям вашего редактора по установке расширений из этого реестра. -После любого метода установки рекомендуется открыть новое окно терминала, чтобы интеграция активировалась корректно. После установки вы можете использовать `/ide enable` для подключения. +После любого метода установки рекомендуется открыть новое окно терминала, чтобы убедиться, что интеграция активирована правильно. После установки вы можете использовать `/ide enable` для подключения. ## Использование @@ -61,7 +61,7 @@ Gemini CLI может интегрироваться с вашей IDE для б /ide disable ``` -Когда подключение включено, Gemini CLI автоматически попытается подключиться к companion extension в IDE. +Когда подключение включено, Qwen Code автоматически попытается подключиться к расширению-компаньону в IDE. ### Проверка статуса @@ -71,58 +71,58 @@ Gemini CLI может интегрироваться с вашей IDE для б /ide status ``` -Если подключение установлено, эта команда покажет, к какой IDE подключен CLI, и список недавно открытых файлов, о которых он знает. +Если подключение установлено, эта команда покажет, к какой IDE выполнено подключение, и список недавно открытых файлов, о которых известно. (Примечание: Список файлов ограничен 10 последними открытыми файлами в вашем workspace и включает только локальные файлы на диске.) ### Работа с Diffs -Когда вы просите Gemini изменить файл, он может открыть diff-представление прямо в вашем редакторе. +Когда вы просите Gemini изменить файл, он может открыть представление diff прямо в вашем редакторе. **Чтобы принять diff**, вы можете выполнить любое из следующих действий: -- Нажать **иконку с галочкой** в заголовке diff-редактора. +- Нажать **иконку с галочкой** в заголовке редактора diff. - Сохранить файл (например, с помощью `Cmd+S` или `Ctrl+S`). -- Открыть Command Palette и выполнить команду **Gemini CLI: Accept Diff**. +- Открыть Command Palette и выполнить команду **Qwen Code: Accept Diff**. - Ответить `yes` в CLI при запросе. **Чтобы отклонить diff**, вы можете: -- Нажать **иконку 'x'** в заголовке diff-редактора. -- Закрыть вкладку diff-редактора. -- Открыть Command Palette и выполнить команду **Gemini CLI: Close Diff Editor**. +- Нажать **иконку 'x'** в заголовке редактора diff. +- Закрыть вкладку редактора diff. +- Открыть Command Palette и выполнить команду **Qwen Code: Close Diff Editor**. - Ответить `no` в CLI при запросе. -Вы также можете **изменить предложенные изменения** прямо в diff-представлении перед их принятием. +Вы также можете **изменить предложенные изменения** прямо в представлении diff перед их принятием. Если вы выберете ‘Yes, allow always’ в CLI, изменения больше не будут отображаться в IDE, так как они будут автоматически приниматься. ## Использование в песочнице -Если вы используете Gemini CLI в песочнице, обратите внимание на следующее: +Если вы используете Qwen Code в песочнице, обратите внимание на следующее: - **На macOS:** Для интеграции с IDE требуется доступ к сети, чтобы взаимодействовать с расширением-компаньоном IDE. Вы должны использовать профиль Seatbelt, который разрешает доступ к сети. -- **В Docker-контейнере:** Если вы запускаете Gemini CLI внутри контейнера Docker (или Podman), интеграция с IDE все равно сможет подключиться к расширению VS Code, запущенному на вашей хост-машине. CLI настроен автоматически находить сервер IDE по адресу `host.docker.internal`. Обычно никакой специальной настройки не требуется, но вам может понадобиться убедиться, что ваша настройка Docker networking разрешает подключения из контейнера к хосту. +- **В Docker-контейнере:** Если вы запускаете Qwen Code внутри Docker (или Podman) контейнера, интеграция с IDE всё ещё может подключиться к расширению VS Code, запущенному на вашей хост-машине. CLI настроен таким образом, чтобы автоматически находить IDE-сервер по адресу `host.docker.internal`. Обычно никакой дополнительной настройки не требуется, но вам может понадобиться убедиться, что ваша конфигурация Docker-сети разрешает подключения из контейнера к хосту. ## Устранение неполадок -Если у вас возникли проблемы с интеграцией IDE, вот несколько распространенных сообщений об ошибках и способы их устранения. +Если у вас возникли проблемы с интеграцией 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 не запущен или не инициализировался корректно. + - **Причина:** Qwen Code не смог найти необходимые переменные окружения (`QWEN_CODE_IDE_WORKSPACE_PATH` или `QWEN_CODE_IDE_SERVER_PORT`) для подключения к IDE. Обычно это означает, что расширение-компаньон IDE не запущено или не инициализировалось корректно. - **Решение:** - 1. Убедитесь, что вы установили расширение **Gemini CLI Companion** в вашей IDE и что оно включено. - 2. Откройте новое окно терминала в вашей IDE, чтобы убедиться, что оно получает правильные переменные окружения. + 1. Убедитесь, что вы установили расширение **Qwen Code Companion** в вашей IDE и что оно включено. + 2. Откройте новое окно терминала в вашей IDE, чтобы убедиться, что оно получает правильное окружение. - **Сообщение:** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` - - **Причина:** Соединение с companion extension было потеряно. + - **Причина:** Подключение к расширению-компаньону IDE было потеряно. - **Решение:** Выполните команду `/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.` +- **Сообщение:** `🔴 Disconnected: Directory mismatch. Qwen Code is running in a different location than the open workspace in [IDE Name]. Please run the CLI from the same directory as your project's root folder.` - **Причина:** Текущая рабочая директория CLI находится вне папки или workspace, открытого в вашем IDE. - **Решение:** Перейдите с помощью `cd` в ту же директорию, которая открыта в вашем IDE, и перезапустите CLI. @@ -132,10 +132,10 @@ Gemini CLI может интегрироваться с вашей IDE для б ### Общие ошибки -- **Сообщение:** `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. +- **Сообщение:** `IDE integration is not supported in your current environment. To use this feature, run Qwen Code in one of these supported IDEs: [List of IDEs]` + - **Причина:** Вы запускаете Qwen Code в терминале или среде, которая не является поддерживаемой IDE. + - **Решение:** Запустите Qwen Code из встроенного терминала поддерживаемой 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 + - **Решение:** Откройте маркетплейс расширений вашей IDE, найдите "Qwen Code Companion" и установите его вручную. \ No newline at end of file diff --git a/website/content/ru/index.md b/website/content/ru/index.md index e2e521b0..5751cf14 100644 --- a/website/content/ru/index.md +++ b/website/content/ru/index.md @@ -4,7 +4,7 @@ ## Обзор -Qwen Code предоставляет возможности продвинутых code моделей прямо в вашем терминале в интерактивной среде Read-Eval-Print Loop (REPL). Qwen Code состоит из клиентского приложения (`packages/cli`), которое взаимодействует с локальным сервером (`packages/core`). Qwen Code также содержит различные инструменты для выполнения таких задач, как операции с файловой системой, запуск shells и web fetching, которыми управляет `packages/core`. +Qwen Code предоставляет возможности продвинутых кодовых моделей прямо в вашем терминале в интерактивной среде Read-Eval-Print Loop (REPL). Qwen Code состоит из клиентского приложения (`packages/cli`), которое взаимодействует с локальным сервером (`packages/core`). Qwen Code также содержит различные инструменты для выполнения таких задач, как операции с файловой системой, запуск shells и web fetching, которыми управляет `packages/core`. ## Навигация по документации @@ -25,13 +25,14 @@ Qwen Code предоставляет возможности продвинуты - **[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`. +- **[Субагенты](./subagents.md):** Специализированные AI-ассистенты для выполнения конкретных задач с подробным руководством по управлению, конфигурации и использованию. +- **[Руководство по участию и разработке](../CONTRIBUTING.md):** Информация для контрибьюторов и разработчиков, включая установку, сборку, тестирование и соглашения по кодированию. - **[NPM Workspaces и публикация](./npm.md):** Подробности о том, как управляются и публикуются пакеты проекта. - **[Руководство по устранению неполадок](./troubleshooting.md):** Найдите решения распространенных проблем и часто задаваемых вопросов. - **[Условия использования и политика конфиденциальности](./tos-privacy.md):** Информация об условиях использования и уведомлениях о конфиденциальности, применимых к вашему использованию Qwen Code. diff --git a/website/content/ru/keyboard-shortcuts.md b/website/content/ru/keyboard-shortcuts.md index 8b928bc5..e67f1ff7 100644 --- a/website/content/ru/keyboard-shortcuts.md +++ b/website/content/ru/keyboard-shortcuts.md @@ -7,13 +7,13 @@ | Shortcut | Description | | -------- | --------------------------------------------------------------------------------------------------------------------- | | `Esc` | Закрыть диалоги и предложения. | -| `Ctrl+C` | Выйти из приложения. Нажмите дважды для подтверждения. | -| `Ctrl+D` | Выйти из приложения, если поле ввода пустое. Нажмите дважды для подтверждения. | -| `Ctrl+L` | Очистить экран. | +| `Ctrl+C` | Отменить текущий запрос и очистить ввод. Нажмите дважды, чтобы выйти из приложения. | +| `Ctrl+D` | Выйти из приложения, если поле ввода пустое. Нажмите дважды для подтверждения. | +| `Ctrl+L` | Очистить экран. | | `Ctrl+O` | Переключить отображение консоли отладки. | | `Ctrl+S` | Позволяет полностью отображать длинные ответы, отключая обрезку. Используйте прокрутку терминала для просмотра всего вывода. | -| `Ctrl+T` | Переключить отображение описаний инструментов. | -| `Ctrl+Y` | Переключить автоматическое подтверждение (режим YOLO) для всех вызовов инструментов. | +| `Ctrl+T` | Переключить отображение описаний инструментов. | +| `Ctrl+Y` | Переключить автоматическое подтверждение (режим YOLO) для всех вызовов инструментов. | ## Input Prompt @@ -26,20 +26,20 @@ | `Meta+Delete` / `Ctrl+Delete` | Удалить слово справа от курсора. | | `Tab` | Автодополнение текущего предложения, если оно существует. | | `Стрелка вверх` | Перемещение вверх по истории ввода. | -| `Ctrl+A` / `Home` | Переместить курсор в начало строки. | +| `Ctrl+A` / `Home` | Переместить курсор в начало строки. | | `Ctrl+B` / `Стрелка влево` | Переместить курсор на один символ влево. | -| `Ctrl+C` | Очистить поле ввода prompt | +| `Ctrl+C` | Очистить prompt. | | `Ctrl+D` / `Delete` | Удалить символ справа от курсора. | | `Ctrl+E` / `End` | Переместить курсор в конец строки. | | `Ctrl+F` / `Стрелка вправо` | Переместить курсор на один символ вправо. | | `Ctrl+H` / `Backspace` | Удалить символ слева от курсора. | -| `Ctrl+K` | Удалить текст от курсора до конца строки. | -| `Ctrl+Стрелка влево` / `Meta+Стрелка влево` / `Meta+B` | Переместить курсор на одно слово влево. | +| `Ctrl+K` | Удалить всё от курсора до конца строки. | +| `Ctrl+Стрелка влево` / `Meta+Стрелка влево` / `Meta+B` | Переместить курсор на одно слово влево. | | `Ctrl+N` | Перемещение вниз по истории ввода. | | `Ctrl+P` | Перемещение вверх по истории ввода. | -| `Ctrl+Стрелка вправо` / `Meta+Стрелка вправо` / `Meta+F` | Переместить курсор на одно слово вправо. | -| `Ctrl+U` | Удалить текст от курсора до начала строки. | -| `Ctrl+V` | Вставить содержимое буфера обмена. Если в буфере изображение, оно будет сохранено, а ссылка на него вставлена в prompt. | +| `Ctrl+Стрелка вправо` / `Meta+Стрелка вправо` / `Meta+F` | Переместить курсор на одно слово вправо. | +| `Ctrl+U` | Удалить всё от курсора до начала строки. | +| `Ctrl+V` | Вставить содержимое буфера обмена. Если в буфере изображение, оно будет сохранено, а в prompt будет вставлена ссылка на него. | | `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace` | Удалить слово слева от курсора. | | `Ctrl+X` / `Meta+Enter` | Открыть текущий ввод во внешнем редакторе. | @@ -55,8 +55,14 @@ | Shortcut | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------- | -| `Down Arrow` / `j` | Переместить выбор вниз. | +| `Down Arrow` / `j` | Переместить выбор вниз. | | `Enter` | Подтвердить выбор. | -| `Up Arrow` / `k` | Переместить выбор вверх. | -| `1-9` | Выбрать элемент по его номеру. | -| (multi-digit) | Для элементов с номерами больше 9, нажмите цифры быстро друг за другом, чтобы выбрать соответствующий элемент. | \ No newline at end of file +| `Up Arrow` / `k` | Переместить выбор вверх. | +| `1-9` | Выбрать элемент по его номеру. | +| (multi-digit) | Для элементов с номерами больше 9, быстро нажмите цифры, чтобы выбрать соответствующий элемент. | + +## Интеграция с IDE + +| Shortcut | Description | +| -------- | --------------------------------- | +| `Ctrl+G` | See context CLI received from IDE | \ No newline at end of file diff --git a/website/content/ru/npm.md b/website/content/ru/npm.md index 6b81a2fa..f234bcfb 100644 --- a/website/content/ru/npm.md +++ b/website/content/ru/npm.md @@ -1,6 +1,6 @@ # Обзор пакета -Этот monorepo содержит два основных пакета: `@qwen-code/qwen-code` и `@qwen-code/qwen-code-core`. +Этот монорепозиторий содержит два основных пакета: `@qwen-code/qwen-code` и `@qwen-code/qwen-code-core`. ## `@qwen-code/qwen-code` @@ -12,7 +12,7 @@ Этот пакет содержит основную логику для CLI. Он отвечает за выполнение API-запросов к настроенным провайдерам, обработку аутентификации и управление локальным кэшем. -Этот пакет не является bundled. При публикации он выпускается как стандартный Node.js пакет со своими собственными зависимостями. Это позволяет использовать его как отдельный пакет в других проектах, если это необходимо. В пакет включён весь транспилированный js-код из папки `dist`. +Этот пакет не собирается в бандл. При публикации он выпускается как стандартный Node.js пакет со своими собственными зависимостями. Это позволяет использовать его как отдельный пакет в других проектах, если это необходимо. Весь транспилированный js-код в папке `dist` включается в пакет. # Процесс релиза @@ -27,28 +27,28 @@ 3. Нажмите кнопку **Run workflow**. 4. Заполните необходимые поля: - **Version**: точная версия для релиза (например, `v0.2.1`). - - **Ref**: ветка или SHA коммита, из которого будет сделан релиз (по умолчанию — `main`). + - **Ref**: ветка или SHA коммита, из которого будет выполнен релиз (по умолчанию — `main`). - **Dry Run**: оставьте `true`, чтобы протестировать workflow без публикации, или установите `false`, чтобы выполнить настоящий релиз. 5. Нажмите **Run workflow**. ## Ночные релизы -В дополнение к ручным релизам, в проекте настроен автоматический процесс ночных релизов, предоставляющий самую свежую "bleeding edge" версию для тестирования и разработки. +В дополнение к ручным релизам, в проекте настроен автоматический процесс ночных релизов, предоставляющий последнюю "bleeding edge" версию для тестирования и разработки. ### Процесс -Каждую ночь в 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. Если все тесты пройдены успешно, вычисляет следующий номер ночной версии (например, `v0.2.1-nightly.20230101`). -5. Затем собирает и публикует пакеты в npm с dist-tag `nightly`. -6. Наконец, создает GitHub Release для ночной версии. +1. Получает последний код из ветки `main`. +2. Устанавливает все зависимости. +3. Запускает полный набор проверок `preflight` и интеграционных тестов. +4. Если все тесты пройдены успешно, вычисляет номер следующей nightly-версии (например, `v0.2.1-nightly.20230101`). +5. Затем собирает и публикует пакеты в npm с dist-tag `nightly`. +6. Наконец, создает GitHub Release для nightly-версии. ### Обработка ошибок -Если какой-либо шаг в ночном workflow завершится с ошибкой, автоматически будет создан новый issue в репозитории с метками `bug` и `nightly-failure`. В issue будет содержаться ссылка на неудачный запуск workflow для удобства отладки. +Если какой-либо шаг в nightly workflow завершится с ошибкой, автоматически будет создан новый issue в репозитории с метками `bug` и `nightly-failure`. В issue будет добавлена ссылка на неудачный запуск workflow для упрощения отладки. ### Как использовать Nightly Build @@ -62,7 +62,7 @@ npm install -g @qwen-code/qwen-code@nightly ### После релиза -После успешного завершения 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`. @@ -72,25 +72,25 @@ npm install -g @qwen-code/qwen-code@nightly После пуша нового релиза необходимо провести 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 testing, запустив базовые команды и инструменты LLM, чтобы убедиться, что пакеты работают как ожидается. В будущем мы формализуем этот процесс. ## Когда сливать изменения версии, а когда нет? -Описанный выше подход к созданию патч- или хотфикс-релизов из текущих или старых коммитов оставляет репозиторий в следующем состоянии: +Описанный выше подход к созданию патч-релизов или hotfix-релизов из текущих или старых коммитов оставляет репозиторий в следующем состоянии: -1. Тег (`vX.Y.Z-patch.1`): Этот тег корректно указывает на оригинальный коммит в ветке main, +1. Тег (`vX.Y.Z-patch.1`): Этот тег правильно указывает на оригинальный коммит в ветке main, который содержит стабильный код, предназначенный для релиза. Это важно. Любой, кто сделает - checkout этого тега, получит в точности тот код, который был опубликован. + checkout этого тега, получит точную копию опубликованного кода. 2. Ветка (`release-vX.Y.Z-patch.1`): Эта ветка содержит один новый коммит поверх коммита с тегом. Этот новый коммит содержит только изменение номера версии в package.json (и других связанных файлах, таких как package-lock.json). -Такое разделение полезно. Оно позволяет истории основной ветки оставаться чистой от изменений -номеров версий, специфичных для релизов, до тех пор, пока вы не решите их слить. +Такое разделение полезно. Оно позволяет сохранить историю основной ветки main без лишних +коммитов с изменениями версий, пока вы явно не решите их слить. Это ключевое решение, и оно полностью зависит от характера релиза. @@ -99,36 +99,36 @@ npm install -g @qwen-code/qwen-code@nightly Почти всегда нужно мержить ветку `release-` обратно в `main` для любого стабильного патча или хотфикса. -- Зачем? Основная причина — обновление версии в package.json ветки main. Если вы выпускаете - v1.2.1 из старого коммита, но никогда не мержите обновление версии обратно, то package.json - в вашей основной ветке всё ещё будет содержать "version": "1.2.0". Следующий разработчик, - который начнёт работу над следующим фичерелизом (v1.3.0), будет создавать ветку от кодовой - базы с некорректным, устаревшим номером версии. Это вызывает путаницу и требует ручного +- Зачем? Основная причина — обновление версии в 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". Это чистая, простая интеграция, которая - поддерживает синхронизацию вашей основной ветки с последней выпущенной версией. +- Процесс: После создания ветки release-v1.2.1 и успешной публикации пакета + вы должны открыть pull request для мержа release-v1.2.1 в main. Этот PR + будет содержать всего один коммит: "chore: bump version to v1.2.1". Это чистая и простая + интеграция, которая поддерживает вашу ветку main в актуальном состоянии с последней выпущенной версией. ### НЕ выполняйте 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-ветке), поэтому функциональный код не теряется. Ветка релиза была просто временным средством для номера версии. +- Почему? Предварительные версии (например, 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. -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. @@ -139,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/qwen-code-0.1.6.tgz`). Выполнив пробный запуск, вы можете быть уверены, что ваши изменения в процессе упаковки корректны и что пакеты будут успешно опубликованы. @@ -164,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: Формирование финального пакета для публикации -Это самый важный этап, на котором файлы перемещаются и преобразуются в финальный вид для публикации. Во временной директории `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` указывают на правильные пути внутри финальной структуры пакета. + - Удаление зависимостей вида `"@qwen-code/core": "workspace:*"` и включение кода `core` напрямую в финальный JS-файл. + - Поля `bin`, `main` и `files` должны указывать на правильные пути внутри финальной структуры пакета. #### 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-пакет больше не нужен как отдельная зависимость в NPM — его код теперь встроен напрямую. +- **Что происходит**: Скомпилированный JavaScript из `packages/core/dist` и `packages/cli/dist` объединяется в один исполняемый JS-файл. +- **Перемещение файла**: `packages/cli/dist/index.js` + `packages/core/dist/index.js` → (бандлится через esbuild) → `bundle/gemini.js` (или аналогичное имя). +- **Зачем**: Это создаёт один оптимизированный файл со всем необходимым кодом приложения. Это упрощает пакет, так как `core` больше не нужен как отдельная зависимость в NPM — его код теперь встроен напрямую. #### 3. Копирование статических и вспомогательных файлов: @@ -194,14 +194,16 @@ npm_package_version=9.9.9 SANDBOX_IMAGE_REGISTRY="registry" SANDBOX_IMAGE_NAME=" - `packages/cli/src/utils/*.sb` (профили песочницы) → `bundle/` - **Зачем**: - `README.md` и `LICENSE` — стандартные файлы, которые должны присутствовать в любом NPM-пакете. - - Профили песочницы (`.sb` файлы) — критически важные рантайм-ресурсы для функции sandboxing CLI. Они должны находиться рядом с финальным исполняемым файлом. + - Профили песочницы (`.sb` файлы) — критически важные рантайм-ресурсы для работы функции sandboxing в CLI. Они должны находиться рядом с финальным исполняемым файлом. ### Этап 4: Публикация в NPM - **Что происходит**: Команда `npm publish` запускается из директории `bundle`. -- **Зачем**: Запуская `npm publish` из директории `bundle`, мы публикуем только те файлы, которые были тщательно собраны на этапе 3. Это предотвращает случайную публикацию исходного кода, тестов или конфигураций разработки, обеспечивая чистый и минимальный пакет для пользователей. +- **Зачем**: Запуская `npm publish` из `bundle`, мы публикуем только те файлы, которые были тщательно собраны на этапе 3. Это предотвращает случайную публикацию исходного кода, тестов или конфигураций разработки, обеспечивая чистый и минималистичный пакет для пользователей. -### Сводная схема потока файлов +--- + +### Схема потока файлов ```mermaid graph TD @@ -245,7 +247,7 @@ graph TD ### Как это работает -Корневой файл `package.json` определяет рабочие области для этого проекта: +Корневой файл `package.json` определяет рабочие области (workspaces) для этого проекта: ```json { @@ -259,4 +261,4 @@ graph TD - **Упрощенное управление зависимостями**: Запуск `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`. Например, чтобы запустить скрипт `build` из пакета `cli`, выполните команду `npm run build --workspace @qwen-code/qwen-code`. \ No newline at end of file diff --git a/website/content/ru/subagents.md b/website/content/ru/subagents.md new file mode 100644 index 00000000..0af48e31 --- /dev/null +++ b/website/content/ru/subagents.md @@ -0,0 +1,469 @@ +# Субагенты + +Субагенты — это специализированные AI-ассистенты, которые обрабатывают определенные типы задач внутри Qwen Code. Они позволяют делегировать узкоспециализированную работу AI-агентам, настроенным под конкретные задачи с помощью специфических промптов, инструментов и поведений. + +## Что такое субагенты? + +Субагенты — это независимые AI-ассистенты, которые: + +- **Специализируются на конкретных задачах** — Каждый субагент настраивается с помощью специфического системного промпта для определенного типа работы +- **Имеют отдельный контекст** — Они ведут свою собственную историю разговора, независимо от основного чата +- **Используют контролируемые инструменты** — Вы можете настроить, какие инструменты доступны каждому субагенту +- **Работают автономно** — После получения задачи они выполняют её независимо до завершения или ошибки +- **Предоставляют подробную обратную связь** — Вы можете отслеживать их прогресс, использование инструментов и статистику выполнения в реальном времени + +## Основные преимущества + +- **Специализация задач**: Создавайте агентов, оптимизированных под конкретные рабочие процессы (тестирование, документация, рефакторинг и т.д.) +- **Изоляция контекста**: Разделяйте специализированную работу от основного разговора +- **Повторное использование**: Сохраняйте и повторно используйте конфигурации агентов в разных проектах и сессиях +- **Контролируемый доступ**: Ограничивайте инструменты, которые может использовать каждый агент, для обеспечения безопасности и концентрации +- **Видимость прогресса**: Отслеживайте выполнение агентов с помощью обновлений в реальном времени + +## Как работают Subagents + +1. **Конфигурация**: Вы создаете конфигурации subagent, которые определяют их поведение, инструменты и системные подсказки +2. **Делегирование**: Основной AI может автоматически делегировать задачи подходящим subagent +3. **Выполнение**: Subagents работают независимо, используя свои настроенные инструменты для выполнения задач +4. **Результаты**: Они возвращают результаты и сводки выполнения обратно в основной разговор + +## Начало работы + +### Быстрый старт + +1. **Создайте своего первого субагента**: + + ``` + /agents create + ``` + + Следуйте пошаговому мастеру для создания специализированного агента. + +2. **Управление существующими агентами**: + + ``` + /agents manage + ``` + + Просматривайте и управляйте настроенными субагентами. + +3. **Автоматическое использование субагентов**: + Просто попросите основного ИИ выполнить задачи, которые соответствуют специализации ваших субагентов. ИИ автоматически делегирует подходящую работу. + +### Пример использования + +``` +Пользователь: "Пожалуйста, напиши комплексные тесты для модуля аутентификации" + +ИИ: Я делегирую это вашему специалисту по тестированию. +[Делегирует субагенту "testing-expert"] +[Показывает прогресс создания тестов в реальном времени] +[Возвращает готовые файлы тестов и сводку по выполнению] +``` + +## Управление + +### Команды CLI + +Субагенты управляются через слэш-команду `/agents` и её подкоманды: + +#### `/agents create` + +Создаёт нового субагента через пошаговый мастер. + +**Использование:** + +``` +/agents create +``` + +#### `/agents manage` + +Открывает интерактивный диалог управления для просмотра и управления существующими подагентами. + +**Использование:** + +``` +/agents manage +``` + +### Места хранения + +Подагенты хранятся в виде Markdown-файлов в двух местах: + +- **На уровне проекта**: `.qwen/agents/` (имеет приоритет) +- **На уровне пользователя**: `~/.qwen/agents/` (резервный вариант) + +Это позволяет иметь как агенты, специфичные для проекта, так и личные агенты, которые работают во всех проектах. + +### Формат файла + +Подагенты настраиваются с помощью Markdown-файлов с YAML frontmatter. Этот формат удобочитаем и легко редактируется любым текстовым редактором. + +#### Базовая структура + +```markdown +--- +name: agent-name +description: Краткое описание того, когда и как использовать этого агента +tools: tool1, tool2, tool3 # Опционально +--- + +Содержимое системного prompt здесь. +Поддерживаются несколько абзацев. +Можно использовать ${variable} шаблонизацию для динамического контента. +``` + +#### Пример использования + +```markdown +--- +name: project-documenter +description: Создает документацию проекта и файлы README +--- + +Вы — специалист по документации для проекта ${project_name}. + +Ваша задача: ${task_description} + +Рабочая директория: ${current_directory} +Сгенерировано: ${timestamp} + +Сосредоточьтесь на создании понятной и полной документации, которая поможет +новым контрибьюторам и конечным пользователям разобраться в проекте. +``` + +## Примеры + +### Агенты рабочего процесса разработки + +#### Testing Specialist + +Идеально подходит для создания комплексных тестов и разработки через тестирование (test-driven development). + +```markdown +--- +name: testing-expert +description: Пишет комплексные unit-тесты, интеграционные тесты и занимается автоматизацией тестирования согласно best practices +tools: read_file, write_file, read_many_files, run_shell_command +--- + +Вы — специалист по тестированию, сосредоточенный на создании высококачественных и поддерживаемых тестов. + +Ваша экспертиза включает: + +- Модульное тестирование (unit testing) с использованием моков и изоляции +- Интеграционное тестирование для проверки взаимодействия компонентов +- Разработку через тестирование (test-driven development) +- Выявление граничных случаев и обеспечение полного покрытия +- Тестирование производительности и нагрузочное тестирование (при необходимости) + +Для каждой задачи по тестированию: + +1. Анализируйте структуру кода и зависимости +2. Определяйте ключевую функциональность, граничные случаи и условия ошибок +3. Создавайте комплексные наборы тестов с понятными именами +4. Включайте корректную настройку/очистку и содержательные проверки (assertions) +5. Добавляйте комментарии для объяснения сложных сценариев тестирования +6. Убедитесь, что тесты легко поддерживаются и следуют принципу DRY + +Всегда следуйте лучшим практикам тестирования для обнаруженного языка и фреймворка. +Уделяйте внимание как позитивным, так и негативным тест-кейсам. +``` + +**Примеры использования:** + +- "Напиши unit-тесты для сервиса аутентификации" +- "Создай интеграционные тесты для workflow обработки платежей" +- "Добавь покрытие тестами для граничных случаев в модуле валидации данных" + +#### Documentation Writer + +Специализируется на создании понятной и подробной документации. + +```markdown +--- +name: documentation-writer +description: Создает подробную документацию, README-файлы, API-документацию и руководства пользователя +tools: read_file, write_file, read_many_files, web_search +--- + +Вы — специалист по технической документации для проекта ${project_name}. + +Ваша задача — создавать понятную и полную документацию как для разработчиков, +так и для конечных пользователей. Сфокусируйтесь на следующих аспектах: + +**Для API-документации:** + +- Четкие описания endpoint'ов с примерами +- Подробная информация о параметрах, их типах и ограничениях +- Описание форматов ответов +- Объяснение кодов ошибок +- Требования к аутентификации + +**Для пользовательской документации:** + +- Пошаговые инструкции с скриншотами, где это уместно +- Руководства по установке и настройке +- Описание параметров конфигурации и примеры +- Разделы по устранению неполадок для частых проблем +- FAQ на основе типичных вопросов пользователей + +**Для документации разработчика:** + +- Обзор архитектуры и ключевых архитектурных решений +- Работающие примеры кода +- Руководство по внесению вклада в проект (contributing guidelines) +- Настройка среды разработки + +Всегда проверяйте примеры кода и следите за тем, чтобы документация соответствовала +реальной реализации. Используйте понятные заголовки, списки и примеры. +``` + +**Примеры использования:** + +- "Создай API-документацию для endpoint'ов управления пользователями" +- "Напиши подробный README для этого проекта" +- "Задокументируй процесс деплоя с разделом по устранению неполадок" + +#### Code Reviewer + +Сосредоточен на качестве кода, безопасности и лучших практиках. + +```markdown +--- +name: code-reviewer +description: Проверяет код на соответствие лучшим практикам, выявляет проблемы безопасности, производительности и поддержки +tools: read_file, read_many_files +--- + +Вы опытный code reviewer, фокусирующийся на качестве, безопасности и поддержке кода. + +Критерии ревью: + +- **Структура кода**: Организация, модульность и разделение ответственности +- **Производительность**: Алгоритмическая эффективность и использование ресурсов +- **Безопасность**: Оценка уязвимостей и безопасные практики кодирования +- **Лучшие практики**: Специфичные для языка/фреймворка конвенции +- **Обработка ошибок**: Корректная обработка исключений и покрытие граничных случаев +- **Читаемость**: Понятные названия, комментарии и организация кода +- **Тестирование**: Покрытие тестами и возможность тестирования + +Давайте конструктивный фидбек: + +1. **Критические проблемы**: Уязвимости безопасности, серьезные баги +2. **Важные улучшения**: Проблемы с производительностью, архитектурные проблемы +3. **Мелкие предложения**: Улучшения стиля, возможности для рефакторинга +4. **Позитивный фидбек**: Хорошо реализованные паттерны и хорошие практики + +Фокусируйтесь на действенных рекомендациях с конкретными примерами и предложенными решениями. +Расставляйте приоритеты по степени влияния и объясняйте логику рекомендаций. +``` + +**Примеры использования:** + +- "Проверь реализацию аутентификации на наличие проблем безопасности" +- "Оцени влияние этой логики запросов к БД на производительность" +- "Проанализируй структуру кода и предложи улучшения" + +### Технологически-специфичные агенты + +#### React Specialist + +Оптимизирован для разработки на React, использования hooks и паттернов компонентов. + +```markdown +--- +name: react-specialist +description: Эксперт в разработке на React, hooks, паттернах компонентов и современных best practices для React +tools: read_file, write_file, read_many_files, run_shell_command +--- + +Вы — специалист по React с глубокими знаниями современной разработки на React. + +Ваша экспертиза включает: + +- **Дизайн компонентов**: Функциональные компоненты, custom hooks, паттерны композиции +- **Управление состоянием**: useState, useReducer, Context API и внешние библиотеки +- **Производительность**: React.memo, useMemo, useCallback, code splitting +- **Тестирование**: React Testing Library, Jest, стратегии тестирования компонентов +- **Интеграция с TypeScript**: Правильная типизация props, hooks и компонентов +- **Современные паттерны**: Suspense, Error Boundaries, Concurrent Features + +Для задач по React: + +1. По умолчанию используйте функциональные компоненты и hooks +2. Реализуйте правильную типизацию с помощью TypeScript +3. Следуйте best practices и конвенциям React +4. Учитывайте влияние на производительность +5. Добавляйте корректную обработку ошибок +6. Пишите тестируемый и поддерживаемый код + +Всегда следите за актуальными best practices в React и избегайте устаревших паттернов. +Уделяйте внимание доступности (accessibility) и UX. +``` + +**Примеры использования:** + +- "Создай переиспользуемый компонент таблицы данных с сортировкой и фильтрацией" +- "Реализуй custom hook для получения данных из API с кэшированием" +- "Перепиши этот class component, чтобы использовать современные паттерны React" + +#### Python Expert + +Специализируюсь на разработке на Python, фреймворках и лучших практиках. + +```markdown +--- +name: python-expert +description: Эксперт в разработке на Python, фреймворках, тестировании и Python-специфичных лучших практиках +tools: read_file, write_file, read_many_files, run_shell_command +--- + +Вы — эксперт в Python с глубоким знанием экосистемы языка. + +Ваша экспертиза включает: + +- **Core Python**: Pythonic паттерны, структуры данных, алгоритмы +- **Фреймворки**: Django, Flask, FastAPI, SQLAlchemy +- **Тестирование**: pytest, unittest, mocking, test-driven development +- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks +- **Асинхронное программирование**: asyncio, async/await паттерны +- **Управление пакетами**: pip, poetry, virtual environments +- **Качество кода**: PEP 8, type hints, линтинг с помощью pylint/flake8 + +Для задач на Python: + +1. Следуйте стилю PEP 8 +2. Используйте type hints для лучшей документации кода +3. Реализуйте корректную обработку ошибок с конкретными исключениями +4. Пишите полные docstrings +5. Учитывайте производительность и использование памяти +6. Добавляйте логирование там, где это уместно +7. Пишите тестируемый, модульный код + +Сосредоточьтесь на написании чистого, поддерживаемого кода на Python, соответствующего стандартам сообщества. +``` + +**Примеры использования:** + +- "Создай FastAPI сервис для аутентификации пользователей с JWT токенами" +- "Реализуй пайплайн обработки данных с pandas и обработкой ошибок" +- "Напиши CLI-тулзу с помощью argparse с полной документацией помощи" + +## Рекомендации + +### Принципы проектирования + +#### Принцип единственной ответственности (Single Responsibility Principle) + +Каждый субагент должен иметь четкую и конкретную цель. + +**✅ Хорошо:** + +```markdown +--- +name: testing-expert +description: Writes comprehensive unit tests and integration tests +--- +``` + +**❌ Избегайте:** + +```markdown +--- +name: general-helper +description: Helps with testing, documentation, code review, and deployment +--- +``` + +**Почему:** Сфокусированные агенты дают лучшие результаты и проще в поддержке. + +#### Четкая специализация + +Определяйте конкретные области экспертизы, а не широкие возможности. + +**✅ Хорошо:** + +```markdown +--- +name: react-performance-optimizer +description: Optimizes React applications for performance using profiling and best practices +--- +``` + +**❌ Избегайте:** + +```markdown +--- +name: frontend-developer +description: Works on frontend development tasks +--- +``` + +**Почему:** Конкретная экспертиза обеспечивает более точную и эффективную помощь. + +#### Понятные описания + +Пишите описания, которые четко указывают, когда использовать агента. + +**✅ Хорошо:** + +```markdown +description: Reviews code for security vulnerabilities, performance issues, and maintainability concerns +``` + +**❌ Избегайте:** + +```markdown +description: A helpful code reviewer +``` + +**Почему:** Четкие описания помогают основному AI выбрать правильного агента для каждой задачи. + +### Рекомендации по конфигурации + +#### Рекомендации по системному промпту + +**Уточняйте уровень экспертизы:** + +```markdown +You are a Python testing specialist with expertise in: + +- pytest framework and fixtures +- Mock objects and dependency injection +- Test-driven development practices +- Performance testing with pytest-benchmark +``` + +**Добавляйте пошаговые подходы:** + +```markdown +For each testing task: + +1. Analyze the code structure and dependencies +2. Identify key functionality and edge cases +3. Create comprehensive test suites with clear naming +4. Include setup/teardown and proper assertions +5. Add comments explaining complex test scenarios +``` + +**Уточняйте стандарты вывода:** + +```markdown +Always follow these standards: + +- Use descriptive test names that explain the scenario +- Include both positive and negative test cases +- Add docstrings for complex test functions +- Ensure tests are independent and can run in any order +``` + +## Вопросы безопасности + +- **Ограничения инструментов**: Субагенты имеют доступ только к настроенным инструментам +- **Песочница**: Все выполнение инструментов следует той же модели безопасности, что и при прямом использовании инструментов +- **Аудит**: Все действия субагентов логируются и видны в реальном времени +- **Контроль доступа**: Разделение на уровне проектов и пользователей обеспечивает соответствующие границы +- **Конфиденциальная информация**: Избегайте включения секретов или учетных данных в конфигурации агентов +- **Продуктовые среды**: Рассмотрите возможность использования отдельных агентов для продуктовых и девелоперских сред \ No newline at end of file diff --git a/website/content/ru/telemetry.md b/website/content/ru/telemetry.md index 72d831bc..ee30f501 100644 --- a/website/content/ru/telemetry.md +++ b/website/content/ru/telemetry.md @@ -8,7 +8,7 @@ ## Включение телеметрии -Вы можете включить телеметрию несколькими способами. Основное управление конфигурацией осуществляется через файл [`.qwen/settings.json`](./cli/configuration.md) и переменные окружения, но флаги CLI могут переопределять эти настройки для конкретной сессии. +Телеметрию можно включить несколькими способами. Основная настройка осуществляется через файл [`.qwen/settings.json`](./cli/configuration.md) и переменные окружения, но флаги CLI могут переопределять эти настройки для конкретной сессии. ### Порядок приоритета @@ -26,7 +26,7 @@ 1. **Файл настроек рабочей области (`.qwen/settings.json`):** Значения из объекта `telemetry` в этом файле, специфичном для проекта. -1. **Файл пользовательских настроек (`~/.qwen/settings.json`):** Значения из объекта `telemetry` в этом глобальном пользовательском файле. +1. **Файл пользовательских настроек (`~/.qwen/settings.json`):** Значения из объекта `telemetry` в этом глобальном файле пользователя. 1. **Значения по умолчанию:** применяются, если не заданы выше. - `telemetry.enabled`: `false` @@ -35,7 +35,7 @@ - `telemetry.logPrompts`: `true` **Для скрипта `npm run telemetry -- --target=`:** -Аргумент `--target` для этого скрипта _только_ переопределяет `telemetry.target` на время выполнения и для целей этого скрипта (т.е. выбора, какой коллектор запустить). Он не изменяет ваш `settings.json` на постоянной основе. Скрипт сначала проверит `settings.json` на наличие `telemetry.target`, чтобы использовать его как значение по умолчанию. +Аргумент `--target` для этого скрипта _только_ переопределяет `telemetry.target` на время выполнения и для целей этого скрипта (т.е. выбора collector'а, который нужно запустить). Он не изменяет ваш `settings.json` на постоянной основе. Скрипт сначала проверит `settings.json` на наличие `telemetry.target`, чтобы использовать его как значение по умолчанию. ### Пример настроек @@ -55,7 +55,7 @@ Вы можете экспортировать все данные телеметрии в файл для локального анализа. -Чтобы включить экспорт в файл, используйте флаг `--telemetry-outfile`, указав путь к желаемому файлу вывода. Это должно запускаться с использованием `--telemetry-target=local`. +Чтобы включить экспорт в файл, используйте флаг `--telemetry-outfile`, указав путь к желаемому файлу вывода. Это необходимо запускать с параметром `--telemetry-target=local`. ```bash @@ -66,7 +66,7 @@ TELEMETRY_FILE=".qwen/telemetry.log" # ПРИМЕЧАНИЕ: --telemetry-otlp-endpoint="" требуется для отключения стандартного -# экспортера OTLP и гарантии записи телеметрии в локальный файл. +# экспортера OTLP и обеспечения записи телеметрии в локальный файл. qwen --telemetry \ --telemetry-target=local \ --telemetry-otlp-endpoint="" \ @@ -77,15 +77,18 @@ qwen --telemetry \ ## Запуск OTEL Collector OTEL Collector — это сервис, который получает, обрабатывает и экспортирует телеметрические данные. -CLI отправляет данные с использованием протокола OTLP/gRPC. +CLI может отправлять данные, используя либо протокол OTLP/gRPC, либо OTLP/HTTP. +Выбрать протокол можно с помощью флага `--telemetry-otlp-protocol` +или настройки `telemetry.otlpProtocol` в файле `settings.json`. Подробнее — в +[документации по конфигурации](./cli/configuration.md#--telemetry-otlp-protocol). -Подробнее о стандартной конфигурации OTEL экспортера можно узнать в [документации][otel-config-docs]. +Узнать больше о стандартной конфигурации OTEL exporter можно в [документации][otel-config-docs]. [otel-config-docs]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/ ### Local -Используйте команду `npm run telemetry -- --target=local`, чтобы автоматизировать процесс настройки локального telemetry pipeline, включая конфигурацию необходимых параметров в файле `.qwen/settings.json`. Скрипт устанавливает `otelcol-contrib` (OpenTelemetry Collector) и `jaeger` (Jaeger UI для просмотра трассировок). Чтобы начать работу: +Используйте команду `npm run telemetry -- --target=local`, чтобы автоматизировать процесс настройки локального telemetry pipeline, включая конфигурацию необходимых параметров в вашем файле `.qwen/settings.json`. Скрипт устанавливает `otelcol-contrib` (OpenTelemetry Collector) и `jaeger` (Jaeger UI для просмотра трассировок). Чтобы начать работу: 1. **Выполните команду**: Запустите команду из корня репозитория: @@ -95,7 +98,7 @@ CLI отправляет данные с использованием прото ``` Скрипт выполнит следующие действия: - - При необходимости загрузит Jaeger и OTEL. + - Загрузит Jaeger и OTEL, если это необходимо. - Запустит локальный экземпляр Jaeger. - Запустит OTEL collector, настроенный на получение данных от Qwen Code. - Автоматически включит telemetry в настройках вашего workspace. @@ -105,10 +108,10 @@ CLI отправляет данные с использованием прото Откройте браузер и перейдите по адресу **http://localhost:16686**, чтобы получить доступ к Jaeger UI. Здесь вы сможете изучить подробные трассировки операций Qwen Code. 1. **Просмотр логов и метрик**: - Скрипт перенаправляет вывод OTEL collector (включая логи и метрики) в файл `~/.qwen/tmp//otel/collector.log`. Скрипт также предоставит ссылки для просмотра и команду для отслеживания telemetry данных (трассировки, метрики, логи) в реальном времени. + Скрипт перенаправляет вывод OTEL collector (включая логи и метрики) в файл `~/.qwen/tmp//otel/collector.log`. Скрипт также предоставит ссылки для просмотра и команду для отслеживания ваших telemetry данных (трассировки, метрики, логи) в реальном времени. 1. **Остановка сервисов**: - Нажмите `Ctrl+C` в терминале, где запущен скрипт, чтобы остановить OTEL Collector и сервисы Jaeger. + Нажмите `Ctrl+C` в терминале, где запущен скрипт, чтобы остановить OTEL Collector и Jaeger. ### Google Cloud @@ -116,7 +119,7 @@ CLI отправляет данные с использованием прото 1. **Предварительные требования**: - У вас должен быть ID проекта Google Cloud. - - Экспортируйте переменную окружения `GOOGLE_CLOUD_PROJECT`, чтобы она была доступна collector'у OTEL. + - Экспортируйте переменную окружения `GOOGLE_CLOUD_PROJECT`, чтобы она была доступна для OTEL collector. ```bash export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" ``` @@ -133,18 +136,18 @@ CLI отправляет данные с использованием прото Скрипт выполнит следующие действия: - Загрузит бинарный файл `otelcol-contrib`, если это необходимо. - Запустит OTEL collector, настроенный на получение данных от Qwen Code и их экспорт в указанный проект Google Cloud. - - Автоматически включит телеметрию и отключит режим песочницы в настройках вашего workspace (`.qwen/settings.json`). + - Автоматически включит телеметрию и отключит sandbox mode в настройках вашего workspace (`.qwen/settings.json`). - Предоставит прямые ссылки для просмотра трассировок, метрик и логов в Google Cloud Console. - - При завершении работы (Ctrl+C) попытается восстановить исходные настройки телеметрии и режима песочницы. + - При завершении работы (Ctrl+C) попытается восстановить исходные настройки телеметрии и sandbox mode. 1. **Запустите Qwen Code**: - В отдельном терминале выполните команды Qwen Code. Это сгенерирует данные телеметрии, которые будут захвачены collector'ом. + В отдельном терминале выполните команды Qwen Code. Это сгенерирует данные телеметрии, которые будут захвачены collector. 1. **Просмотр телеметрии в Google Cloud**: Используйте ссылки, предоставленные скриптом, чтобы перейти в Google Cloud Console и просмотреть трассировки, метрики и логи. -1. **Просмотр логов локального collector'а**: - Скрипт перенаправляет вывод локального OTEL collector в `~/.qwen/tmp//otel/collector-gcp.log`. Скрипт также предоставляет ссылки для просмотра и команду для отслеживания логов collector'а в реальном времени. +1. **Просмотр логов локального collector**: + Скрипт перенаправляет вывод локального OTEL collector в `~/.qwen/tmp//otel/collector-gcp.log`. Скрипт также предоставляет ссылки и команды для просмотра логов collector локально. 1. **Остановка сервиса**: Нажмите `Ctrl+C` в терминале, где запущен скрипт, чтобы остановить OTEL Collector. @@ -191,7 +194,7 @@ CLI отправляет данные с использованием прото - `error_type` (если применимо) - `metadata` (если применимо, словарь string -> any) -- `qwen-code.api_request`: Это событие происходит при отправке запроса к Gemini API. +- `qwen-code.api_request`: Это событие происходит при отправке запроса к Qwen API. - **Атрибуты**: - `model` - `request_text` (если применимо) @@ -205,7 +208,7 @@ CLI отправляет данные с использованием прото - `duration_ms` - `auth_type` -- `qwen-code.api_response`: Это событие происходит при получении ответа от Gemini API. +- `qwen-code.api_response`: Это событие происходит при получении ответа от Qwen API. - **Атрибуты**: - `model` - `status_code` @@ -230,7 +233,7 @@ CLI отправляет данные с использованием прото ### Метрики -Метрики — это числовые измерения поведения за определенный период времени. Для Qwen Code собираются следующие метрики (названия метрик остаются `qwen-code.*` для совместимости): +Метрики — это числовые измерения поведения за определённый период времени. Для Qwen Code собираются следующие метрики (названия метрик остаются `qwen-code.*` для совместимости): - `qwen-code.session.count` (Counter, Int): Увеличивается на 1 при каждом запуске CLI. @@ -239,6 +242,7 @@ CLI отправляет данные с использованием прото - `function_name` - `success` (boolean) - `decision` (string: "accept", "reject", или "modify", если применимо) + - `tool_type` (string: "mcp", или "native", если применимо) - `qwen-code.tool.call.latency` (Histogram, ms): Измеряет задержку вызовов инструментов. - **Атрибуты**: @@ -269,4 +273,9 @@ CLI отправляет данные с использованием прото - `ai_added_lines` (Int, если применимо): Количество строк, добавленных/изменённых AI. - `ai_removed_lines` (Int, если применимо): Количество строк, удалённых/изменённых AI. - `user_added_lines` (Int, если применимо): Количество строк, добавленных/изменённых пользователем в предложенных AI изменениях. - - `user_removed_lines` (Int, если применимо): Количество строк, удалённых/изменённых пользователем в предложенных AI изменениях. \ No newline at end of file + - `user_removed_lines` (Int, если применимо): Количество строк, удалённых/изменённых пользователем в предложенных AI изменениях. + +- `qwen-code.chat_compression` (Counter, Int): Считает количество операций сжатия чата. + - **Атрибуты**: + - `tokens_before`: (Int): Количество токенов в контексте до сжатия. + - `tokens_after`: (Int): Количество токенов в контексте после сжатия. \ 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 387a36ae..5c637adf 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) @@ -17,7 +17,7 @@ Qwen Code предоставляет комплексный набор инст - `respect_git_ignore` (boolean, необязательный): Учитывать ли паттерны из `.gitignore` при выводе списка файлов. По умолчанию `true`. - **Поведение:** - Возвращает список имен файлов и каталогов. - - Указывает, является ли каждая запись каталогом. + - Показывает, является ли каждая запись каталогом. - Сортирует записи: сначала каталоги, затем в алфавитном порядке. - **Вывод (`llmContent`):** Строка вида: `Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png` - **Подтверждение:** Нет. @@ -31,10 +31,10 @@ Qwen Code предоставляет комплексный набор инст - **Файл:** `read-file.ts` - **Параметры:** - `path` (string, обязательный): Абсолютный путь к файлу для чтения. - - `offset` (number, опциональный): Для текстовых файлов — номер строки (с 0), с которой начинать чтение. Требует установки параметра `limit`. + - `offset` (number, опциональный): Для текстовых файлов — номер строки (с 0), с которой начинать чтение. Требует установки `limit`. - `limit` (number, опциональный): Для текстовых файлов — максимальное количество строк для чтения. Если не указан, читается стандартное максимальное количество (например, 2000 строк) или весь файл, если это возможно. - **Поведение:** - - Для текстовых файлов: Возвращает содержимое. Если используются `offset` и `limit`, возвращается только указанный диапазон строк. Указывает, если содержимое было обрезано из-за ограничений по количеству или длине строк. + - Для текстовых файлов: Возвращает содержимое. Если используются `offset` и `limit`, возвращает только указанный диапазон строк. Указывает, если содержимое было обрезано из-за ограничений по количеству или длине строк. - Для изображений и PDF-файлов: Возвращает содержимое файла в виде base64-закодированной структуры данных, подходящей для обработки моделью. - Для других бинарных файлов: Пытается определить и пропустить их, возвращая сообщение о том, что это обычный бинарный файл. - **Вывод:** (`llmContent`): @@ -54,10 +54,10 @@ Qwen Code предоставляет комплексный набор инст - `file_path` (string, обязательный): Абсолютный путь к файлу для записи. - `content` (string, обязательный): Контент, который нужно записать в файл. - **Поведение:** - - Записывает предоставленный `content` в `file_path`. + - Записывает переданный `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 изменений и запрашивает одобрение пользователя перед записью. +- **Вывод (`llmContent`):** Сообщение об успешной операции, например: `Successfully overwrote file: /path/to/your/file.txt` или `Successfully created and wrote to new file: /path/to/new/file.txt`. +- **Подтверждение:** Да. Показывает diff изменений и запрашивает подтверждение пользователя перед записью. ## 4. `glob` (FindFiles) @@ -89,11 +89,11 @@ Qwen Code предоставляет комплексный набор инст - `pattern` (string, обязательный): Регулярное выражение для поиска (например, `"function\s+myFunction"`). - `path` (string, опциональный): Абсолютный путь к директории, в которой нужно искать. По умолчанию — текущая рабочая директория. - `include` (string, опциональный): Glob-паттерн для фильтрации файлов (например, `"*.js"`, `"src/**/*.{ts,tsx}"`). Если не указан, поиск осуществляется по большинству файлов (с учетом стандартных игнор-файлов). - - `maxResults` (number, опциональный): Максимальное количество совпадений для возврата, чтобы избежать переполнения контекста (по умолчанию: 20, максимум: 100). Используйте меньшие значения для широких поисков, большие — для точных. + - `maxResults` (number, опциональный): Максимальное количество совпадений, которое будет возвращено, чтобы избежать переполнения контекста (по умолчанию: 20, максимум: 100). Используйте меньшие значения для широких поисков, большие — для точных. - **Поведение:** - Использует `git grep`, если доступен в Git-репозитории, для повышения скорости; иначе использует системный `grep` или поиск на JavaScript. - Возвращает список строк с совпадениями, каждая из которых снабжена путем к файлу (относительно директории поиска) и номером строки. - - По умолчанию ограничивает количество результатов 20 совпадениями, чтобы избежать переполнения контекста. При обрезке результатов выводится предупреждение с рекомендациями по уточнению поиска. + - По умолчанию ограничивает количество результатов 20 совпадениями, чтобы избежать переполнения контекста. При обрезке результатов выводится предупреждение с рекомендациями по уточнению запроса. - **Вывод (`llmContent`):** Отформатированная строка с совпадениями, например: ``` @@ -136,20 +136,20 @@ search_file_content(pattern="function", path="src", maxResults=50) search_file_content(pattern="function", include="*.js", maxResults=10) ``` -## 6. `replace` (Редактирование) +## 6. `edit` (Редактирование) -`replace` заменяет текст в файле. По умолчанию заменяется одно вхождение, но можно заменить несколько вхождений, если указать `expected_replacements`. Этот инструмент предназначен для точных, целевых изменений и требует значительного контекста вокруг `old_string`, чтобы убедиться, что он изменяет правильное место. +`edit` заменяет текст в файле. По умолчанию заменяется одно вхождение, но можно заменить несколько вхождений, если указать `expected_replacements`. Этот инструмент предназначен для точных, целевых изменений и требует значительного контекста вокруг `old_string`, чтобы убедиться, что он изменяет правильное место. -- **Название инструмента:** `replace` -- **Отображаемое имя:** Edit +- **Название инструмента:** `edit` +- **Отображаемое имя:** Редактирование - **Файл:** `edit.ts` - **Параметры:** - `file_path` (string, обязательный): Абсолютный путь к файлу, который нужно изменить. - - `old_string` (string, обязательный): Точный текст, который нужно заменить. + - `old_string` (string, обязательный): Точный буквальный текст для замены. - **ВАЖНО:** Эта строка должна однозначно идентифицировать единственный экземпляр для изменения. Она должна включать как минимум 3 строки контекста _до_ и _после_ целевого текста, точно соответствующие пробелам и отступам. Если `old_string` пустая, инструмент пытается создать новый файл по пути `file_path` с содержимым `new_string`. + **ВАЖНО:** Эта строка должна однозначно идентифицировать единственный экземпляр для изменения. Она должна включать как минимум 3 строки контекста _до_ и _после_ целевого текста, точно соответствующего пробелам и отступам. Если `old_string` пустая, инструмент пытается создать новый файл по пути `file_path` с содержимым `new_string`. - - `new_string` (string, обязательный): Точный текст, на который нужно заменить `old_string`. + - `new_string` (string, обязательный): Точный буквальный текст, на который нужно заменить `old_string`. - `expected_replacements` (number, опциональный): Количество вхождений для замены. По умолчанию — `1`. - **Поведение:** @@ -157,17 +157,17 @@ search_file_content(pattern="function", include="*.js", maxResults=10) - Если `old_string` задана, инструмент читает `file_path` и пытается найти ровно одно вхождение `old_string`. - Если одно вхождение найдено, оно заменяется на `new_string`. - **Повышенная надежность (многоэтапная коррекция редактирования):** Чтобы значительно повысить вероятность успешного редактирования, особенно когда предоставленная моделью `old_string` может быть не совсем точной, инструмент использует механизм многоэтапной коррекции редактирования. - - Если исходная `old_string` не найдена или совпадает с несколькими местами, инструмент может использовать модель Gemini для итеративного уточнения `old_string` (и, возможно, `new_string`). - - Этот процесс самокоррекции пытается определить уникальный сегмент, который модель хотела изменить, делая операцию `replace` более надежной даже при немного неточном начальном контексте. + - Если исходная `old_string` не найдена или совпадает с несколькими местами, инструмент может использовать модель Qwen для итеративного уточнения `old_string` (и, возможно, `new_string`). + - Этот процесс самокоррекции пытается определить уникальный сегмент, который модель хотела изменить, делая операцию `edit` более надежной даже при немного неточном начальном контексте. - **Условия сбоя:** Несмотря на механизм коррекции, инструмент завершится ошибкой, если: - `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 предлагаемых изменений и запрашивает подтверждение пользователя перед записью в файл. +- **Подтверждение:** Да. Показывает diff предложенных изменений и запрашивает подтверждение пользователя перед записью в файл. Эти инструменты файловой системы предоставляют основу для того, чтобы Qwen Code мог понимать и взаимодействовать с локальным контекстом вашего проекта. \ No newline at end of file diff --git a/website/content/ru/tools/mcp-server.md b/website/content/ru/tools/mcp-server.md index 2854912e..58380dfd 100644 --- a/website/content/ru/tools/mcp-server.md +++ b/website/content/ru/tools/mcp-server.md @@ -2,17 +2,17 @@ Этот документ содержит руководство по настройке и использованию Model Context Protocol (MCP) серверов с Qwen Code. -## Что такое MCP-сервер? +## Что такое MCP сервер? -MCP-сервер — это приложение, которое предоставляет инструменты и ресурсы CLI через Model Context Protocol, позволяя ему взаимодействовать с внешними системами и источниками данных. MCP-серверы выступают в роли моста между моделью и вашей локальной средой или другими сервисами, например API. +MCP сервер — это приложение, которое предоставляет инструменты и ресурсы для CLI через Model Context Protocol, позволяя ему взаимодействовать с внешними системами и источниками данных. MCP серверы выступают в роли моста между моделью и вашей локальной средой или другими сервисами, например API. -MCP-сервер позволяет CLI: +MCP сервер позволяет CLI: - **Обнаруживать инструменты:** Получать список доступных инструментов, их описания и параметры через стандартизированные схемы. - **Выполнять инструменты:** Вызывать конкретные инструменты с заданными аргументами и получать структурированные ответы. -- **Получать доступ к ресурсам:** Читать данные из определённых ресурсов (хотя CLI в основном ориентирован на выполнение инструментов). +- **Доступ к ресурсам:** Читать данные из определённых ресурсов (хотя CLI в основном ориентирован на выполнение инструментов). -С помощью MCP-сервера вы можете расширить возможности CLI, чтобы выполнять действия, выходящие за рамки встроенных функций, например взаимодействовать с базами данных, API, пользовательскими скриптами или специализированными рабочими процессами. +С помощью MCP сервера вы можете расширить возможности CLI, чтобы выполнять действия, выходящие за рамки встроенных функций, например взаимодействовать с базами данных, API, пользовательскими скриптами или специализированными рабочими процессами. ## Архитектура основной интеграции @@ -25,33 +25,33 @@ Qwen Code интегрируется с MCP-серверами через сло 1. **Перебирает настроенные серверы** из конфигурации `mcpServers` в вашем `settings.json` 2. **Устанавливает соединения** с использованием соответствующих транспортных механизмов (Stdio, SSE или Streamable HTTP) 3. **Получает определения инструментов** с каждого сервера по протоколу MCP -4. **Очищает и проверяет** схемы инструментов на совместимость с Gemini API +4. **Очищает и проверяет** схемы инструментов на совместимость с Qwen API 5. **Регистрирует инструменты** в глобальном реестре инструментов с разрешением конфликтов ### Execution Layer (`mcp-tool.ts`) Каждый обнаруженный MCP tool оборачивается в экземпляр `DiscoveredMCPTool`, который: -- **Обрабатывает логику подтверждения** на основе настроек доверия сервера и пользовательских предпочтений -- **Управляет выполнением tool'а** путем вызова MCP сервера с корректными параметрами -- **Обрабатывает ответы** как для контекста LLM, так и для отображения пользователю -- **Сохраняет состояние подключения** и обрабатывает таймауты +- **Обрабатывает логику подтверждения** на основе настроек доверия сервера и пользовательских предпочтений +- **Управляет выполнением tool'а** путем вызова MCP сервера с правильными параметрами +- **Обрабатывает ответы** как для контекста LLM, так и для отображения пользователю +- **Сохраняет состояние подключения** и обрабатывает таймауты ### Transport Mechanisms CLI поддерживает три типа транспорта MCP: -- **Stdio Transport:** Запускает subprocess и общается через stdin/stdout -- **SSE Transport:** Подключается к endpoint'ам Server-Sent Events -- **Streamable HTTP Transport:** Использует HTTP streaming для коммуникации +- **Stdio Transport:** Запускает subprocess и общается через stdin/stdout +- **SSE Transport:** Подключается к endpoint'ам Server-Sent Events +- **Streamable HTTP Transport:** Использует HTTP streaming для коммуникации ## Как настроить свой MCP сервер -Qwen Code использует конфигурацию `mcpServers` в вашем файле `settings.json`, чтобы находить и подключаться к MCP серверам. Эта конфигурация поддерживает несколько серверов с различными механизмами транспорта. +Qwen Code использует конфигурацию `mcpServers` в вашем файле `settings.json`, чтобы находить и подключаться к MCP серверам. Эта конфигурация поддерживает несколько серверов с разными механизмами транспорта. ### Настройка MCP-сервера в settings.json -Вы можете настроить MCP-серверы на глобальном уровне в файле `~/.qwen/settings.json` или в корневой директории вашего проекта, создав или открыв файл `.qwen/settings.json`. Внутри файла добавьте блок конфигурации `mcpServers`. +Вы можете настроить MCP-серверы глобально в файле `~/.qwen/settings.json` или в корневой директории вашего проекта, создав или открыв файл `.qwen/settings.json`. Внутри файла добавьте блок конфигурации `mcpServers`. ### Структура конфигурации @@ -81,8 +81,8 @@ Qwen Code использует конфигурацию `mcpServers` в ваше #### Обязательно (одно из следующих) - **`command`** (string): Путь к исполняемому файлу для транспорта Stdio -- **`url`** (string): URL endpoint'а SSE (например, `"http://localhost:8080/sse"`) -- **`httpUrl`** (string): URL endpoint'а HTTP streaming +- **`url`** (string): URL endpoint для SSE (например, `"http://localhost:8080/sse"`) +- **`httpUrl`** (string): URL endpoint для HTTP streaming #### Необязательные параметры @@ -90,18 +90,18 @@ Qwen Code использует конфигурацию `mcpServers` в ваше - **`headers`** (object): Пользовательские HTTP-заголовки при использовании `url` или `httpUrl` - **`env`** (object): Переменные окружения для процесса сервера. Значения могут ссылаться на переменные окружения с использованием синтаксиса `$VAR_NAME` или `${VAR_NAME}` - **`cwd`** (string): Рабочая директория для транспорта Stdio -- **`timeout`** (number): Таймаут запроса в миллисекундах (по умолчанию: 600 000 мс = 10 минут) +- **`timeout`** (number): Таймаут запроса в миллисекундах (по умолчанию: 600,000 мс = 10 минут) - **`trust`** (boolean): Если `true`, отключает все подтверждения вызовов инструментов для этого сервера (по умолчанию: `false`) -- **`includeTools`** (string[]): Список имен инструментов, которые нужно включить с этого MCP-сервера. Если указан, то будут доступны только перечисленные здесь инструменты (whitelist-поведение). Если не указан, по умолчанию включаются все инструменты с сервера. -- **`excludeTools`** (string[]): Список имен инструментов, которые нужно исключить с этого MCP-сервера. Указанные здесь инструменты не будут доступны модели, даже если они предоставлены сервером. **Примечание:** `excludeTools` имеет приоритет над `includeTools` — если инструмент присутствует в обоих списках, он будет исключен. +- **`includeTools`** (string[]): Список названий инструментов, которые нужно подключить с этого MCP-сервера. Если указано, то будут доступны только перечисленные здесь инструменты (whitelist-поведение). Если не указано, по умолчанию активны все инструменты сервера. +- **`excludeTools`** (string[]): Список названий инструментов, которые нужно исключить с этого MCP-сервера. Указанные здесь инструменты будут недоступны модели, даже если сервер их предоставляет. **Примечание:** `excludeTools` имеет приоритет над `includeTools` — если инструмент присутствует в обоих списках, он будет исключён. ### Поддержка OAuth для удаленных MCP серверов -Qwen Code поддерживает аутентификацию OAuth 2.0 для удаленных MCP серверов с использованием транспортов SSE или HTTP. Это позволяет безопасно получать доступ к MCP серверам, требующим аутентификации. +Qwen Code поддерживает аутентификацию OAuth 2.0 для удаленных MCP серверов с использованием транспортов SSE или HTTP. Это позволяет безопасно получать доступ к MCP серверам, которые требуют аутентификации. #### Автоматическое обнаружение OAuth -Для серверов, поддерживающих обнаружение OAuth, вы можете опустить конфигурацию OAuth и позволить CLI автоматически обнаружить её: +Для серверов, которые поддерживают автоматическое обнаружение OAuth, вы можете опустить конфигурацию OAuth и позволить CLI обнаружить её автоматически: ```json { @@ -116,7 +116,7 @@ Qwen Code поддерживает аутентификацию OAuth 2.0 для CLI автоматически: - Определяет, когда сервер требует аутентификацию через OAuth (ответы 401) -- Обнаруживает OAuth endpoint'ы из метаданных сервера +- Обнаруживает OAuth эндпоинты из метаданных сервера - Выполняет динамическую регистрацию клиента, если это поддерживается - Обрабатывает OAuth flow и управление токенами @@ -125,17 +125,17 @@ CLI автоматически: При подключении к серверу с поддержкой OAuth: 1. **Первая попытка подключения** завершается ошибкой 401 Unauthorized -2. **Обнаружение OAuth** находит endpoint'ы авторизации и токенов +2. **Обнаружение OAuth** находит endpoint'ы авторизации и получения токенов 3. **Открывается браузер** для аутентификации пользователя (требуется доступ к локальному браузеру) 4. **Authorization code** обменивается на access token'ы -5. **Токены сохраняются** безопасным образом для последующего использования +5. **Токены безопасно сохраняются** для последующего использования 6. **Повторная попытка подключения** проходит успешно с действующими токенами #### Требования к перенаправлению браузера -**Важно:** Аутентификация через OAuth требует, чтобы ваша локальная машина могла: +**Важно:** Для аутентификации через OAuth ваша локальная машина должна: -- Открыть веб-браузер для аутентификации +- Открывать веб-браузер для аутентификации - Принимать перенаправления по адресу `http://localhost:7777/oauth/callback` Эта функция не будет работать в: @@ -150,15 +150,15 @@ CLI автоматически: ```bash -# Список серверов, требующих аутентификации +# Показать список серверов, требующих аутентификацию /mcp auth ``` ```markdown -# Аутентификация с определённым сервером +# Аутентификация на определенном сервере /mcp auth serverName -# Повторная аутентификация при истечении токенов +# Повторная аутентификация при истечении срока действия токенов /mcp auth serverName ``` @@ -167,8 +167,8 @@ CLI автоматически: - **`enabled`** (boolean): Включить OAuth для этого сервера - **`clientId`** (string): Идентификатор клиента OAuth (необязательно при динамической регистрации) - **`clientSecret`** (string): Секрет клиента OAuth (необязательно для публичных клиентов) -- **`authorizationUrl`** (string): Эндпоинт авторизации OAuth (автоматически определяется, если не указан) -- **`tokenUrl`** (string): Эндпоинт токенов OAuth (автоматически определяется, если не указан) +- **`authorizationUrl`** (string): Конечная точка авторизации OAuth (автоматически определяется, если не указана) +- **`tokenUrl`** (string): Конечная точка токена OAuth (автоматически определяется, если не указана) - **`scopes`** (string[]): Требуемые scope'ы OAuth - **`redirectUri`** (string): Пользовательский URI перенаправления (по умолчанию `http://localhost:7777/oauth/callback`) - **`tokenParamName`** (string): Имя параметра запроса для токенов в URL SSE @@ -267,7 +267,7 @@ OAuth токены автоматически: } ``` -#### MCP Server на базе HTTP +#### HTTP-based MCP Server ```json { @@ -280,7 +280,7 @@ OAuth токены автоматически: } ``` -#### MCP Server на базе HTTP с кастомными заголовками +#### HTTP-based MCP Server с Custom Headers ```json { @@ -316,7 +316,7 @@ OAuth токены автоматически: ## Подробное описание процесса обнаружения -Когда Qwen Code запускается, он выполняет обнаружение MCP серверов через следующий детализированный процесс: +Когда Qwen Code запускается, он выполняет обнаружение MCP-серверов через следующий детализированный процесс: ### 1. Итерация по серверам и подключение @@ -327,7 +327,7 @@ OAuth токены автоматически: - `httpUrl` → `StreamableHTTPClientTransport` - `url` → `SSEClientTransport` - `command` → `StdioClientTransport` -3. **Установка соединения:** Клиент MCP пытается установить соединение с заданным таймаутом +3. **Установка соединения:** MCP-клиент пытается установить соединение с заданным таймаутом 4. **Обработка ошибок:** Ошибки подключения логируются, а статус сервера устанавливается в `DISCONNECTED` ### 2. Обнаружение инструментов @@ -337,16 +337,16 @@ OAuth токены автоматически: 1. **Получение списка инструментов:** Клиент вызывает endpoint получения списка инструментов сервера MCP 2. **Валидация схемы:** Проверяется объявление функции каждого инструмента 3. **Фильтрация инструментов:** Инструменты фильтруются на основе конфигурации `includeTools` и `excludeTools` -4. **Очистка имен:** Имена инструментов приводятся в соответствие с требованиями Gemini API: +4. **Очистка имен:** Имена инструментов приводятся в соответствие с требованиями Qwen API: - Недопустимые символы (все, кроме букв, цифр, подчеркивания, точки и дефиса) заменяются на подчеркивание - - Имена длиннее 63 символов обрезаются с заменой середины на `___` + - Имена длиннее 63 символов обрезаются с заменой средней части (`___`) ### 3. Разрешение конфликтов Когда несколько серверов предоставляют инструменты с одинаковыми именами: 1. **Первый зарегистрированный побеждает:** Первый сервер, зарегистрировавший имя инструмента, получает имя без префикса -2. **Автоматическое добавление префиксов:** Последующие серверы получают имена с префиксами: `serverName__toolName` +2. **Автоматическое добавление префикса:** Последующие серверы получают имена с префиксом: `serverName__toolName` 3. **Отслеживание в реестре:** Реестр инструментов хранит сопоставления между именами серверов и их инструментами ### 4. Обработка схем @@ -434,13 +434,13 @@ if (this.trust) { ### Использование команды `/mcp` -Команда `/mcp` предоставляет подробную информацию о настройке вашего MCP сервера: +Команда `/mcp` предоставляет полную информацию о настройке вашего MCP сервера: ```bash /mcp ``` -Отображает: +Вывод включает: - **Список серверов:** Все настроенные MCP серверы - **Статус подключения:** `CONNECTED`, `CONNECTING` или `DISCONNECTED` @@ -463,7 +463,7 @@ MCP Servers Status: Command: node dist/server.js --verbose Error: Connection refused -.dockerizedServer (CONNECTED) +🐳 dockerizedServer (CONNECTED) Command: docker run -i --rm -e API_KEY my-mcp-server:latest Tools: docker__deploy, docker__status @@ -472,11 +472,11 @@ Discovery State: COMPLETED ### Использование инструментов -После обнаружения инструменты MCP становятся доступны для модели Gemini как встроенные инструменты. Модель автоматически: +После обнаружения инструменты MCP становятся доступны модели Qwen как встроенные инструменты. Модель автоматически: 1. **Выбирает подходящие инструменты** в зависимости от ваших запросов 2. **Отображает диалоги подтверждения** (если только сервер не является доверенным) -3. **Выполняет инструменты** с правильными параметрами +3. **Выполняет инструменты** с корректными параметрами 4. **Отображает результаты** в удобном для пользователя формате ## Мониторинг состояния и устранение неполадок @@ -493,11 +493,11 @@ Discovery State: COMPLETED #### Состояние обнаружения (`MCPDiscoveryState`) -- **`NOT_STARTED`:** Обнаружение еще не началось +- **`NOT_STARTED`:** Обнаружение ещё не началось - **`IN_PROGRESS`:** В процессе обнаружения серверов -- **`COMPLETED`:** Обнаружение завершено (с ошибками или без них) +- **`COMPLETED`:** Обнаружение завершено (с ошибками или без) -### Распространенные проблемы и решения +### Распространённые проблемы и решения #### Сервер не подключается @@ -531,7 +531,7 @@ Discovery State: COMPLETED 1. **Валидация параметров:** Убедитесь, что ваш инструмент принимает ожидаемые параметры 2. **Совместимость схем:** Проверьте, что ваши input схемы являются валидными JSON Schema 3. **Обработка ошибок:** Проверьте, не выбрасывает ли ваш инструмент необработанные исключения -4. **Таймауты:** Рассмотрите возможность увеличения значения `timeout` +4. **Проблемы с таймаутом:** Рассмотрите возможность увеличения значения `timeout` #### Совместимость песочницы @@ -542,23 +542,23 @@ Discovery State: COMPLETED 1. **Серверы на базе Docker:** Используйте Docker контейнеры, которые включают все зависимости 2. **Доступность путей:** Убедитесь, что исполняемые файлы сервера доступны в песочнице 3. **Доступ к сети:** Настройте песочницу для разрешения необходимых сетевых подключений -4. **Переменные окружения:** Проверьте, что необходимые environment variables передаются корректно +4. **Переменные окружения:** Проверьте, что необходимые переменные окружения передаются корректно ### Советы по отладке 1. **Включите режим отладки:** Запустите CLI с флагом `--debug`, чтобы получить подробный вывод 2. **Проверьте stderr:** stderr сервера MCP записывается в лог (информационные сообщения фильтруются) -3. **Изолируйте тестирование:** Протестируйте сервер MCP отдельно перед интеграцией -4. **Настройка поэтапно:** Начните с простых инструментов, прежде чем добавлять сложный функционал -5. **Часто используйте `/mcp`:** Следите за статусом сервера во время разработки +3. **Изолируйте тестирование:** Протестируйте ваш MCP-сервер отдельно перед интеграцией +4. **Инкрементальная настройка:** Начните с простых инструментов, прежде чем добавлять сложный функционал +5. **Часто используйте `/mcp`:** Отслеживайте статус сервера во время разработки ## Важные замечания ### Вопросы безопасности - **Настройки доверия:** Опция `trust` отключает все диалоги подтверждения. Используйте с осторожностью и только для серверов, которыми вы полностью управляете -- **Токены доступа:** Будьте внимательны к безопасности при настройке переменных окружения, содержащих API keys или токены -- **Совместимость с песочницей:** При использовании песочницы убедитесь, что серверы MCP доступны внутри песочничной среды +- **Токены доступа:** Будьте внимательны к безопасности при настройке переменных окружения, содержащих API ключи или токены +- **Совместимость с песочницей:** При использовании песочницы убедитесь, что MCP-серверы доступны внутри песочничной среды - **Конфиденциальные данные:** Использование персональных токенов с широкими правами может привести к утечке информации между репозиториями ### Производительность и управление ресурсами @@ -566,19 +566,19 @@ Discovery State: COMPLETED - **Постоянные соединения:** CLI поддерживает постоянные соединения с серверами, которые успешно зарегистрировали инструменты - **Автоматическая очистка:** Соединения с серверами, не предоставляющими инструментов, автоматически закрываются - **Управление таймаутами:** Настройте соответствующие таймауты в зависимости от характеристик ответов вашего сервера -- **Мониторинг ресурсов:** MCP серверы запускаются как отдельные процессы и потребляют системные ресурсы +- **Мониторинг ресурсов:** MCP-серверы запускаются как отдельные процессы и потребляют системные ресурсы ### Совместимость схем -- **Удаление свойств:** Система автоматически удаляет определенные свойства схемы (`$schema`, `additionalProperties`) для совместимости с Gemini API -- **Санитизация имен:** Имена инструментов автоматически очищаются для соответствия требованиям API +- **Удаление свойств:** Система автоматически удаляет определенные свойства схемы (`$schema`, `additionalProperties`) для совместимости с Qwen API +- **Очистка имен:** Имена инструментов автоматически очищаются для соответствия требованиям API - **Разрешение конфликтов:** Конфликты имен инструментов между серверами разрешаются путем автоматического добавления префиксов -Эта комплексная интеграция делает MCP серверы мощным способом расширения возможностей CLI с сохранением безопасности, надежности и удобства использования. +Эта комплексная интеграция делает MCP-серверы мощным способом расширения возможностей CLI с сохранением безопасности, надежности и удобства использования. ## Возврат Rich Content из инструментов -Инструменты MCP не ограничены возвратом простого текста. Вы можете возвращать rich, multi-part контент, включая текст, изображения, аудио и другие бинарные данные в одном ответе инструмента. Это позволяет создавать мощные инструменты, которые могут предоставлять модели разнообразную информацию за один шаг. +Инструменты MCP не ограничены возвратом простого текста. Вы можете возвращать rich, multi-part контент, включая текст, изображения, аудио и другие бинарные данные в одном ответе инструмента. Это позволяет создавать мощные инструменты, которые могут предоставлять модели разнообразную информацию за один ход. Все данные, возвращаемые из инструмента, обрабатываются и отправляются модели в качестве контекста для следующей генерации, позволяя ей рассуждать или суммировать предоставленную информацию. @@ -624,7 +624,7 @@ Discovery State: COMPLETED 2. Представляет данные изображения как отдельную часть `inlineData`. 3. Выводит понятное и дружелюбное резюме в CLI, указывая, что были получены и текст, и изображение. -Это позволяет создавать сложные инструменты, которые могут предоставлять богатый мультимодальный контекст модели Gemini. +Это позволяет создавать сложные инструменты, которые могут предоставлять модели Qwen богатый многомодальный контекст. ## MCP Prompts как Slash Commands @@ -685,21 +685,21 @@ await server.connect(transport); /poem-writer --title="Qwen Code" --mood="reverent" ``` -или с использованием позиционных аргументов: +или, используя позиционные аргументы: ```bash /poem-writer "Qwen Code" reverent ``` -При выполнении этой команды CLI вызывает метод `prompts/get` на сервере MCP с переданными аргументами. Сервер отвечает за подстановку аргументов в шаблон промпта и возвращает финальный текст промпта. Затем CLI отправляет этот промпт модели для выполнения. Это удобный способ автоматизировать и делиться общими workflow. +При выполнении этой команды CLI вызывает метод `prompts/get` на сервере MCP с переданными аргументами. Сервер отвечает за подстановку аргументов в шаблон промпта и возвращает финальный текст промпта. Затем CLI отправляет этот промпт модели для выполнения. Это удобный способ автоматизировать и делиться общими рабочими процессами. ## Управление MCP серверами с помощью `qwen mcp` -Хотя вы всегда можете настроить MCP сервера, вручную отредактировав файл `settings.json`, CLI предоставляет удобный набор команд для программного управления конфигурациями ваших серверов. Эти команды упрощают процесс добавления, просмотра и удаления MCP серверов без необходимости напрямую редактировать JSON файлы. +Хотя вы всегда можете настроить MCP сервера, отредактировав вручную файл `settings.json`, CLI предоставляет удобный набор команд для программного управления конфигурациями ваших серверов. Эти команды упрощают процесс добавления, просмотра и удаления MCP серверов без необходимости напрямую редактировать JSON файлы. ### Добавление сервера (`qwen mcp add`) -Команда `add` настраивает новый MCP-сервер в вашем `settings.json`. В зависимости от области видимости (`-s, --scope`), сервер будет добавлен либо в пользовательский конфиг `~/.qwen/settings.json`, либо в конфиг проекта `.qwen/settings.json`. +Команда `add` настраивает новый MCP-сервер в вашем `settings.json`. В зависимости от области видимости (`-s, --scope`), сервер будет добавлен либо в пользовательский конфиг `~/.qwen/settings.json`, либо в проектный конфиг `.qwen/settings.json`. **Команда:** @@ -709,7 +709,7 @@ qwen mcp add [options] [args...] - ``: Уникальное имя сервера. - ``: Команда для выполнения (для `stdio`) или URL (для `http`/`sse`). -- `[args...]`: Необязательные аргументы для команды `stdio`. +- `[args...]`: Опциональные аргументы для команды `stdio`. **Опции (флаги):** diff --git a/website/content/ru/tools/memory.md b/website/content/ru/tools/memory.md index da3734bb..d4a9b0f6 100644 --- a/website/content/ru/tools/memory.md +++ b/website/content/ru/tools/memory.md @@ -1,10 +1,10 @@ # Инструмент работы с памятью (`save_memory`) -В этом документе описывается инструмент `save_memory` для Qwen Code. +Этот документ описывает инструмент `save_memory` для Qwen Code. ## Описание -Используйте `save_memory`, чтобы сохранять и вспоминать информацию между сессиями Qwen Code. С помощью `save_memory` вы можете указать CLI запомнить ключевые детали между сессиями, обеспечивая персонализированную и целенаправленную помощь. +Используйте `save_memory`, чтобы сохранять и вспоминать информацию между сессиями работы с Qwen Code. С помощью `save_memory` вы можете указать CLI запомнить ключевые детали между сессиями, обеспечивая персонализированную и целенаправленную помощь. ### Аргументы @@ -14,14 +14,14 @@ ## Как использовать `save_memory` с Qwen Code -Инструмент добавляет указанный `fact` в ваш файл контекста в домашней директории пользователя (по умолчанию `~/.qwen/QWEN.md`). Имя этого файла можно настроить через параметр `contextFileName`. +Инструмент добавляет указанный `fact` в ваш файл контекста в домашней директории пользователя (по умолчанию `~/.qwen/QWEN.md`). Имя этого файла можно изменить через параметр `contextFileName`. После добавления факты сохраняются в разделе `## Qwen Added Memories`. Этот файл загружается как контекст в последующих сессиях, позволяя CLI вспоминать сохраненную информацию. Пример использования: ``` -save_memory(fact="Ваш факт здесь.") +save_memory(fact="Your fact here.") ``` ### Примеры использования `save_memory` @@ -35,10 +35,10 @@ save_memory(fact="My preferred programming language is Python.") Сохранить информацию, связанную с проектом: ``` -save_memory(fact="The project I'm currently working on is called 'gemini-cli'.") +save_memory(fact="The project I'm currently working on is called 'qwen-code'.") ``` ## Важные замечания -- **Общее использование:** Этот инструмент следует использовать для кратких и важных фактов. Он не предназначен для хранения больших объемов данных или истории разговоров. +- **Общее использование:** Этот инструмент следует использовать для кратких и важных фактов. Он не предназначен для хранения больших объемов данных или истории разговора. - **Файл памяти:** Файл памяти — это обычный текстовый файл в формате Markdown, поэтому при необходимости вы можете просматривать и редактировать его вручную. \ No newline at end of file diff --git a/website/content/ru/tools/web-fetch.md b/website/content/ru/tools/web-fetch.md index 8c4a9639..6c87bcca 100644 --- a/website/content/ru/tools/web-fetch.md +++ b/website/content/ru/tools/web-fetch.md @@ -15,7 +15,7 @@ ## Как использовать `web_fetch` с Qwen Code -Чтобы использовать `web_fetch` с Qwen Code, передайте URL и prompt, описывающий, что вы хотите извлечь из этого URL. Инструмент запросит подтверждение перед тем, как выполнить fetch URL. После подтверждения инструмент получит контент напрямую и обработает его с помощью AI модели. +Чтобы использовать `web_fetch` с Qwen Code, передайте URL и prompt, описывающий, что вы хотите извлечь по этому URL. Инструмент запросит подтверждение перед тем, как выполнить fetch URL. После подтверждения инструмент получит контент напрямую и обработает его с помощью AI модели. Инструмент автоматически конвертирует HTML в текст, обрабатывает GitHub blob URLs (преобразуя их в raw URLs) и обновляет HTTP URLs до HTTPS для обеспечения безопасности. @@ -42,7 +42,7 @@ web_fetch(url="https://arxiv.org/abs/2401.0001", prompt="What are the key findin Анализ документации на GitHub: ``` -web_fetch(url="https://github.com/google/gemini-react/blob/main/README.md", prompt="What are the installation steps and main features?") +web_fetch(url="https://github.com/QwenLM/Qwen/blob/main/README.md", prompt="What are the installation steps and main features?") ``` ## Важные замечания @@ -51,4 +51,4 @@ web_fetch(url="https://github.com/google/gemini-react/blob/main/README.md", prom - **Формат URL:** Инструмент автоматически обновляет HTTP URL до HTTPS и преобразует GitHub blob URL в raw формат для лучшего доступа к содержимому. - **Обработка контента:** Инструмент напрямую загружает контент и обрабатывает его с помощью AI модели, преобразуя HTML в читаемый текстовый формат. - **Качество вывода:** Качество результата зависит от четкости инструкций в prompt. -- **MCP инструменты:** Если доступен предоставляемый MCP web fetch инструмент (начинающийся с "mcp\_\_"), предпочтительно использовать именно его, так как он может иметь меньше ограничений. \ No newline at end of file +- **MCP инструменты:** Если доступен предоставляемый MCP инструмент web fetch (начинающийся с "mcp\_\_"), предпочтительно использовать именно его, так как он может иметь меньше ограничений. \ No newline at end of file diff --git a/website/content/ru/troubleshooting.md b/website/content/ru/troubleshooting.md index 8fed3aa4..e6c00ce2 100644 --- a/website/content/ru/troubleshooting.md +++ b/website/content/ru/troubleshooting.md @@ -5,18 +5,13 @@ - Ошибки аутентификации или входа в систему - Часто задаваемые вопросы (FAQ) - Советы по отладке -- Существующие Issues в GitHub, похожие на вашу проблему, или создание новых Issues +- Существующие GitHub Issues, похожие на вашу проблему, или создание новых Issues ## Ошибки аутентификации или входа в систему -- **Ошибка: `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), который также включает отдельный бесплатный лимит. - - **Ошибка: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` или `unable to get local issuer certificate`** - - **Причина:** Возможно, вы находитесь в корпоративной сети с брандмауэром, который перехватывает и инспектирует SSL/TLS-трафик. Для этого часто требуется, чтобы Node.js доверял пользовательскому корневому сертификату ЦС. - - **Решение:** Установите переменную окружения `NODE_EXTRA_CA_CERTS`, указав абсолютный путь к файлу корневого сертификата вашей корпоративной ЦС. + - **Причина:** Возможно, вы находитесь в корпоративной сети с брандмауэром, который перехватывает и инспектирует SSL/TLS трафик. Часто для этого требуется, чтобы Node.js доверял пользовательскому корневому сертификату ЦС. + - **Решение:** Установите переменную окружения `NODE_EXTRA_CA_CERTS` в абсолютный путь к файлу корневого сертификата вашего корпоративного ЦС. - Пример: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` ## Часто задаваемые вопросы (FAQ) @@ -31,18 +26,18 @@ Дополнительную информацию см. в разделе [Конфигурация 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-ключей (Qwen API key или Google Cloud Vertex AI), но недоступна для пользователей OAuth (например, личных/корпоративных аккаунтов Google, таких как Google Gmail или Google Workspace). Это связано с тем, что Qwen Code Assist API не поддерживает создание кэшированного контента. Вы по-прежнему можете просматривать общее использование токенов с помощью команды `/stats`. ## Распространенные сообщения об ошибках и решения -- **Ошибка: `EADDRINUSE` (Address already in use) при запуске MCP сервера.** +- **Ошибка: `EADDRINUSE` (Адрес уже используется) при запуске MCP сервера.** - **Причина:** Другой процесс уже использует порт, к которому пытается привязаться MCP сервер. - **Решение:** Остановите другой процесс, использующий этот порт, или настройте MCP сервер на использование другого порта. -- **Ошибка: Command not found (при попытке запустить Qwen Code с помощью `qwen`).** - - **Причина:** CLI не установлен корректно или не добавлен в `PATH` вашей системы. +- **Ошибка: Команда не найдена (при попытке запустить Qwen Code с помощью `qwen`).** + - **Причина:** CLI не установлен корректно или не добавлен в системную переменную `PATH`. - **Решение:** Способ обновления зависит от того, как вы установили Qwen Code: - Если вы установили `qwen` глобально, проверьте, что директория с глобальными бинарниками `npm` находится в вашем `PATH`. Вы можете обновить с помощью команды `npm install -g @qwen-code/qwen-code@latest`. @@ -51,22 +46,22 @@ - **Ошибка: `MODULE_NOT_FOUND` или ошибки импорта.** - **Причина:** Зависимости установлены некорректно или проект не был собран. - **Решение:** - 1. Выполните `npm install`, чтобы убедиться, что все зависимости установлены. - 2. Выполните `npm run build`, чтобы скомпилировать проект. - 3. Убедитесь, что сборка прошла успешно, с помощью `npm run start`. + 1. Выполните `npm install`, чтобы убедиться, что все зависимости установлены. + 2. Выполните `npm run build`, чтобы скомпилировать проект. + 3. Убедитесь, что сборка прошла успешно, с помощью `npm run start`. - **Ошибка: "Operation not permitted", "Permission denied" или аналогичные.** - - **Причина:** Если включён sandboxing, Qwen Code может пытаться выполнить операции, запрещённые вашей конфигурацией песочницы, например, запись вне директории проекта или системной временной директории. + - **Причина:** Когда включено sandboxing, Qwen Code может пытаться выполнить операции, запрещенные вашей конфигурацией песочницы, например, запись вне директории проекта или системной временной директории. - **Решение:** Обратитесь к документации [Configuration: Sandboxing](./cli/configuration.md#sandboxing) для получения дополнительной информации, включая способы настройки конфигурации песочницы. - **Qwen Code не запускается в интерактивном режиме в CI-средах** - - **Проблема:** 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` + - **Проблема:** Qwen Code не переходит в интерактивный режим (не появляется приглашение ввода), если установлена переменная окружения, начинающаяся с `CI_` (например, `CI_TOKEN`). Это происходит потому, что пакет `is-in-ci`, используемый в UI-фреймворке, обнаруживает такие переменные и считает, что среда не интерактивна. + - **Причина:** Пакет `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,13 +71,13 @@ - `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, чтобы убедиться, что он запускается. ## Советы по отладке - **Отладка CLI:** - Используйте флаг `--verbose` (если доступен) с командами CLI для получения более подробного вывода. - - Проверьте логи CLI, которые часто находятся в пользовательской директории конфигурации или кэша. + - Проверьте логи CLI, которые обычно находятся в пользовательской директории конфигурации или кэша. - **Отладка ядра:** - Проверьте вывод консоли сервера на наличие сообщений об ошибках или stack trace. diff --git a/website/content/zh/Uninstall.md b/website/content/zh/Uninstall.md index 1478f7c3..d45aeadd 100644 --- a/website/content/zh/Uninstall.md +++ b/website/content/zh/Uninstall.md @@ -1,12 +1,12 @@ # 卸载 CLI -你的卸载方法取决于你运行 CLI 的方式。请根据你使用 npx 或全局 npm 安装的情况，按照相应的说明操作。 +你的卸载方法取决于你运行 CLI 的方式。请根据你是使用 npx 还是全局 npm 安装来选择相应的卸载说明。 -## 方法 1: 使用 npx +## 方法 1：使用 npx -npx 从临时缓存中运行包，而不会进行永久安装。要"卸载"CLI，你必须清除这个缓存，这将移除 gemini-cli 以及任何其他之前使用 npx 执行过的包。 +npx 从临时缓存中运行包，而不会进行永久安装。要“卸载”CLI，你必须清除这个缓存，这将移除 qwen-code 以及任何其他之前通过 npx 执行过的包。 -npx 缓存是你的主 npm 缓存文件夹内一个名为 `_npx` 的目录。你可以通过运行 `npm config get cache` 来找到你的 npm 缓存路径。 +npx 缓存是你主 npm 缓存文件夹中的一个名为 `_npx` 的目录。你可以通过运行 `npm config get cache` 来找到你的 npm 缓存路径。 **对于 macOS / Linux** diff --git a/website/content/zh/checkpointing.md b/website/content/zh/checkpointing.md index 24543adf..22666f50 100644 --- a/website/content/zh/checkpointing.md +++ b/website/content/zh/checkpointing.md @@ -1,22 +1,22 @@ # Checkpointing -Qwen Code 包含一个 Checkpointing 功能，该功能会在 AI 驱动的工具对项目文件进行任何修改之前，自动保存项目状态的快照。这样你可以安全地试验和应用代码变更，并且知道可以立即回滚到工具运行之前的状态。 +Qwen Code 包含一个 Checkpointing 功能，该功能会在 AI 工具对项目文件进行任何修改之前，自动保存项目状态的快照。这样你可以安全地试验和应用代码变更，并且知道可以立即恢复到工具运行前的状态。 ## 工作原理 -当你批准一个修改文件系统的工具（如 `write_file` 或 `replace`）时，CLI 会自动创建一个“检查点”。该检查点包括： +当你批准一个修改文件系统的工具（如 `write_file` 或 `edit`）时，CLI 会自动创建一个“检查点”。该检查点包括： -1. **Git 快照：** 在你主目录下的一个特殊的影子 Git 仓库中创建一个 commit（`~/.qwen/history/`）。这个快照会完整记录项目文件在那一刻的状态。它**不会**干扰你自己项目中的 Git 仓库。 -2. **对话历史：** 截至当时的完整对话记录会被保存。 +1. **Git 快照：** 在你主目录下的一个特殊影子 Git 仓库中创建一个 commit（路径为 `~/.qwen/history/`）。这个快照会完整记录项目文件在那一刻的状态。它**不会**干扰你自己项目中的 Git 仓库。 +2. **对话历史：** 截至当前时刻你与 agent 的完整对话会被保存。 3. **工具调用：** 即将执行的具体工具调用也会被存储。 -如果你想撤销更改或只是想回退，可以使用 `/restore` 命令。恢复一个检查点将会： +如果你想撤销更改或只是想回退到之前的状态，可以使用 `/restore` 命令。恢复检查点时将： -- 将项目中的所有文件恢复到快照中记录的状态。 +- 将项目中的所有文件还原到快照中记录的状态。 - 在 CLI 中恢复对话历史。 -- 重新提出原始的工具调用，允许你再次运行它、修改它或直接忽略。 +- 重新提出原始的工具调用，允许你再次运行、修改或直接忽略它。 -所有检查点数据，包括 Git 快照和对话历史，都存储在你本地机器上。Git 快照保存在影子仓库中，而对话历史和工具调用则保存在项目临时目录中的一个 JSON 文件里，通常位于 `~/.qwen/tmp//checkpoints`。 +所有的检查点数据，包括 Git 快照和对话历史，都存储在你本地机器上。Git 快照保存在影子仓库中，而对话历史和工具调用则以 JSON 文件的形式保存在项目的临时目录中，通常位于 `~/.qwen/tmp//checkpoints`。 ## 启用 Checkpointing 功能 @@ -24,7 +24,7 @@ Checkpointing 功能默认是关闭的。要启用它，你可以使用命令行 ### 使用命令行 Flag -你可以在启动 Qwen Code 时使用 `--checkpointing` flag 来为当前 session 启用 checkpointing： +你可以在启动 Qwen Code 时使用 `--checkpointing` flag 来为当前会话启用 checkpointing： ```bash qwen --checkpointing @@ -32,7 +32,7 @@ qwen --checkpointing ### 使用 `settings.json` 文件 -要为所有 session 默认启用 checkpointing，你需要编辑你的 `settings.json` 文件。 +要为所有会话默认启用 checkpointing，你需要编辑你的 `settings.json` 文件。 在你的 `settings.json` 中添加以下 key： @@ -60,7 +60,7 @@ CLI 将显示所有可用的 checkpoint 文件列表。这些文件名通常由 ### 恢复到指定 Checkpoint -要将项目恢复到某个特定的 checkpoint，请使用列表中的 checkpoint 文件： +要将项目恢复到某个特定的 checkpoint，请使用列表中的 checkpoint 文件名： ``` /restore @@ -72,4 +72,4 @@ CLI 将显示所有可用的 checkpoint 文件列表。这些文件名通常由 /restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file ``` -执行该命令后，你的文件和对话将立即恢复到创建该 checkpoint 时的状态，并且原始的工具提示会重新出现。 \ No newline at end of file +执行该命令后，你的文件和对话将立即恢复到创建该 checkpoint 时的状态，并且原始的 tool prompt 会重新出现。 \ No newline at end of file diff --git a/website/content/zh/cli/commands.md b/website/content/zh/cli/commands.md index 8154637c..a88d0814 100644 --- a/website/content/zh/cli/commands.md +++ b/website/content/zh/cli/commands.md @@ -9,146 +9,181 @@ Qwen Code 支持多个内置命令，帮助你管理会话、自定义界面并 ### 内置命令 - **`/bug`** - - **说明：** 提交一个关于 Qwen Code 的 issue。默认情况下，该 issue 会提交到 Qwen Code 的 GitHub 仓库中。你在 `/bug` 后输入的字符串将成为该 bug 的标题。你可以通过在 `.qwen/settings.json` 文件中配置 `bugCommand` 设置来修改 `/bug` 的默认行为。 + - **描述：** 提交一个关于 Qwen Code 的 issue。默认情况下，issue 会提交到 Qwen Code 的 GitHub 仓库中。你在 `/bug` 后输入的字符串将成为该 bug 的标题。你可以通过在 `.qwen/settings.json` 文件中配置 `bugCommand` 设置来修改 `/bug` 的默认行为。 - **`/chat`** - - **说明：** 交互式地保存和恢复对话历史，以支持分支对话状态，或在后续会话中恢复之前的对话状态。 + - **描述：** 交互式地保存和恢复对话历史，以便在不同分支对话状态之间切换，或在后续会话中恢复之前的对话状态。 - **子命令：** - **`save`** - - **说明：** 保存当前对话历史。你必须添加一个 `` 用于标识该对话状态。 + - **描述：** 保存当前对话历史。你必须添加一个 `` 来标识该对话状态。 - **用法：** `/chat save ` - **检查点位置详情：** 默认的聊天检查点保存位置为： - - Linux/macOS: `~/.config/google-generative-ai/checkpoints/` - - Windows: `C:\Users\\AppData\Roaming\google-generative-ai\checkpoints\` + - Linux/macOS: `~/.config/qwen-code/checkpoints/` + - Windows: `C:\Users\\AppData\Roaming\qwen-code\checkpoints\` - 当你运行 `/chat list` 时，CLI 只会扫描这些特定目录以查找可用的检查点。 - **注意：** 这些检查点用于手动保存和恢复对话状态。如需了解在文件修改前自动创建的检查点，请参阅 [Checkpointing documentation](../checkpointing.md)。 - **`resume`** - - **说明：** 从之前的保存点恢复对话。 + - **描述：** 从之前的保存点恢复对话。 - **用法：** `/chat resume ` - **`list`** - - **说明：** 列出可用于恢复对话状态的标签。 + - **描述：** 列出可用于恢复对话状态的标签。 - **`delete`** - - **说明：** 删除一个已保存的对话检查点。 + - **描述：** 删除已保存的对话检查点。 - **用法：** `/chat delete ` - **`/clear`** - - **说明：** 清除终端屏幕，包括 CLI 中可见的会话历史和滚动缓冲区。底层会话数据（用于历史回溯）可能会根据具体实现保留，但视觉显示会被清除。 + - **描述：** 清除终端屏幕，包括 CLI 中可见的会话历史和滚动缓冲区。底层会话数据（用于历史回溯）可能会根据具体实现保留，但视觉显示会被清除。 - **快捷键：** 随时按 **Ctrl+L** 执行清除操作。 +- **`/summary`** + - **描述：** 根据当前对话历史生成一个全面的项目摘要，并保存到 `.qwen/PROJECT_SUMMARY.md`。该摘要包括总体目标、关键知识、最近操作和当前计划，非常适合在未来的会话中恢复工作。 + - **用法：** `/summary` + - **功能：** + - 分析整个对话历史以提取重要上下文 + - 创建结构化的 markdown 摘要，包含目标、知识、操作和计划等部分 + - 自动保存到项目根目录下的 `.qwen/PROJECT_SUMMARY.md` + - 在生成和保存过程中显示进度指示器 + - 与 Welcome Back 功能集成，实现无缝会话恢复 + - **注意：** 此命令需要至少包含 2 条消息的活跃对话才能生成有意义的摘要。 + - **`/compress`** - - **说明：** 用摘要替换整个聊天上下文。这可以节省未来任务的 token 使用量，同时保留高层次的摘要信息。 + - **描述：** 用摘要替换整个聊天上下文。这可以节省未来任务使用的 token 数量，同时保留已发生事件的高级摘要。 - **`/copy`** - - **说明：** 将 Qwen Code 最后一次输出的内容复制到剪贴板，方便分享或复用。 + - **描述：** 将 Qwen Code 生成的最后一个输出复制到剪贴板，方便分享或重复使用。 - **`/directory`**（或 **`/dir`**） - - **说明：** 管理工作区目录，支持多目录操作。 + - **描述：** 管理工作区目录，支持多目录操作。 - **子命令：** - **`add`**： - - **说明：** 将目录添加到工作区。路径可以是绝对路径或相对于当前工作目录的路径。同时支持从主目录开始的路径引用。 + - **描述：** 将目录添加到工作区。路径可以是绝对路径或相对于当前工作目录的相对路径。也支持从主目录开始的路径引用。 - **用法：** `/directory add ,` - - **注意：** 在限制性沙箱配置中禁用。如果你使用的是该配置，请在启动会话时使用 `--include-directories` 参数。 + - **注意：** 在限制性沙盒配置文件中禁用此功能。如果你正在使用该配置，请在启动会话时使用 `--include-directories` 参数。 - **`show`**： - - **说明：** 显示通过 `/directory add` 和 `--include-directories` 添加的所有目录。 + - **描述：** 显示通过 `/directory add` 和 `--include-directories` 添加的所有目录。 - **用法：** `/directory show` - **`/directory`**（或 **`/dir`**） - - **说明：** 管理工作区目录，支持多目录操作。 + - **描述：** 管理工作区目录，支持多目录操作。 - **子命令：** - **`add`**： - - **说明：** 将目录添加到工作区。路径可以是绝对路径或相对于当前工作目录的路径。同时支持从主目录开始的路径引用。 + - **描述：** 将目录添加到工作区。路径可以是绝对路径或相对于当前工作目录的相对路径。也支持从主目录开始的路径引用。 - **用法：** `/directory add ,` - - **注意：** 在限制性沙箱配置中禁用。如果你使用的是该配置，请在启动会话时使用 `--include-directories` 参数。 + - **注意：** 在限制性沙盒配置文件中禁用此功能。如果你正在使用该配置，请在启动会话时使用 `--include-directories` 参数。 - **`show`**： - - **说明：** 显示通过 `/directory add` 和 `--include-directories` 添加的所有目录。 + - **描述：** 显示通过 `/directory add` 和 `--include-directories` 添加的所有目录。 - **用法：** `/directory show` - **`/editor`** - - **说明：** 打开一个对话框，用于选择支持的编辑器。 + - **描述：** 打开一个对话框，用于选择支持的编辑器。 - **`/extensions`** - - **说明：** 列出当前 Qwen Code 会话中所有激活的扩展。详见 [Qwen Code Extensions](../extension.md)。 + - **描述：** 列出当前 Qwen Code 会话中所有激活的扩展。详见 [Qwen Code Extensions](../extension.md)。 - **`/help`**（或 **`/?`**） - - **说明：** 显示 Qwen Code 的帮助信息，包括可用命令及其用法。 + - **描述：** 显示 Qwen Code 的帮助信息，包括可用命令及其用法。 - **`/mcp`** - - **说明：** 列出已配置的 Model Context Protocol (MCP) 服务器、其连接状态、服务器详情和可用工具。 + - **描述：** 列出已配置的 Model Context Protocol (MCP) 服务器、其连接状态、服务器详情和可用工具。 - **子命令：** - **`desc`** 或 **`descriptions`**： - - **说明：** 显示 MCP 服务器和工具的详细描述。 + - **描述：** 显示 MCP 服务器和工具的详细描述。 - **`nodesc`** 或 **`nodescriptions`**： - - **说明：** 隐藏工具描述，仅显示工具名称。 + - **描述：** 隐藏工具描述，仅显示工具名称。 - **`schema`**： - - **说明：** 显示工具配置参数的完整 JSON schema。 - - **快捷键：** 随时按 **Ctrl+T** 切换工具描述的显示与隐藏。 + - **描述：** 显示工具配置参数的完整 JSON schema。 + - **快捷键：** 随时按 **Ctrl+T** 在显示和隐藏工具描述之间切换。 - **`/memory`** - - **说明：** 管理 AI 的指令上下文（默认从 `QWEN.md` 文件加载的分层内存；可通过 `contextFileName` 配置）。 + - **描述：** 管理 AI 的指令上下文（默认从 `QWEN.md` 文件加载的分层内存；可通过 `contextFileName` 配置）。 - **子命令：** - **`add`**： - - **说明：** 将以下文本添加到 AI 的内存中。用法：`/memory add ` + - **描述：** 将以下文本添加到 AI 的内存中。用法：`/memory add ` - **`show`**： - - **说明：** 显示当前从所有上下文文件（如 `QWEN.md`）加载的分层内存的完整内容。这可以帮助你检查提供给模型的指令上下文。 + - **描述：** 显示从所有上下文文件（如 `QWEN.md`）加载的当前分层内存的完整内容。这让你可以检查提供给模型的指令上下文。 - **`refresh`**： - - **说明：** 重新从所有上下文文件（默认为 `QWEN.md`）中加载分层指令内存，这些文件位于配置的位置（全局、项目/祖先目录和子目录）。这将使用最新的上下文内容更新模型。 - - **注意：** 有关上下文文件如何构成分层内存的更多详情，请参阅 [CLI Configuration documentation](./configuration.md#context-files-hierarchical-instructional-context)。 + - **描述：** 从配置位置（全局、项目/祖先目录和子目录）中找到的所有上下文文件（默认：`QWEN.md`）重新加载分层指令内存。这会用最新的上下文内容更新模型。 + - **注意：** 有关上下文文件如何贡献于分层内存的更多详情，请参阅 [CLI Configuration documentation](./configuration.md#context-files-hierarchical-instructional-context)。 - **`/restore`** - - **说明：** 将项目文件恢复到工具执行前的状态。这特别适用于撤销工具所做的文件修改。如果未提供工具调用 ID，它将列出可恢复的检查点。 + - **描述：** 将项目文件恢复到工具执行前的状态。这对于撤销工具进行的文件编辑特别有用。如果在没有工具调用 ID 的情况下运行，它将列出可恢复的检查点。 - **用法：** `/restore [tool_call_id]` - - **注意：** 仅在 CLI 启动时使用 `--checkpointing` 选项或通过 [settings](./configuration.md) 配置时可用。详见 [Checkpointing documentation](../checkpointing.md)。 + - **注意：** 仅在使用 `--checkpointing` 选项调用 CLI 或通过 [settings](./configuration.md) 配置时可用。详见 [Checkpointing documentation](../checkpointing.md)。 - **`/settings`** - - **说明：** 打开设置编辑器以查看和修改 Qwen Code 的设置。 - - **详情：** 此命令提供了一个用户友好的界面，用于更改控制 Qwen Code 行为和外观的设置。它等效于手动编辑 `.qwen/settings.json` 文件，但带有验证和引导功能以防止错误。 - - **用法：** 直接运行 `/settings`，编辑器将自动打开。你可以浏览或搜索特定设置，查看当前值并按需修改。某些设置的更改会立即生效，而其他设置则需要重启。 + - **描述：** 打开设置编辑器以查看和修改 Qwen Code 设置。 + - **详情：** 此命令提供了一个用户友好的界面来更改控制 Qwen Code 行为和外观的设置。它等效于手动编辑 `.qwen/settings.json` 文件，但带有验证和指导以防止错误。 + - **用法：** 简单运行 `/settings`，编辑器将打开。然后你可以浏览或搜索特定设置，查看其当前值并按需修改。某些设置的更改会立即生效，而其他设置需要重启。 - **`/stats`** - - **说明：** 显示当前 Qwen Code 会话的详细统计信息，包括 token 使用量、缓存 token 节省情况（如果可用）和会话时长。注意：缓存 token 信息仅在使用缓存 token 时显示，目前仅在使用 API key 认证时支持。 + - **描述：** 显示当前 Qwen Code 会话的详细统计信息，包括 token 使用量、缓存 token 节省量（如果可用）和会话持续时间。注意：缓存 token 信息仅在使用缓存 token 时显示，这在使用 API key 认证时发生，但目前在 OAuth 认证时不发生。 - [**`/theme`**](./themes.md) - - **说明：** 打开一个对话框，允许你更改 Qwen Code 的视觉主题。 + - **描述：** 打开一个对话框，让你更改 Qwen Code 的视觉主题。 - **`/auth`** - - **说明：** 打开一个对话框，允许你更改认证方式。 + - **描述：** 打开一个对话框，让你更改认证方法。 - **`/about`** - - **说明：** 显示版本信息。提交 issue 时请分享此信息。 + - **描述：** 显示版本信息。提交 issue 时请分享此信息。 + +- **`/agents`** + - **描述：** 管理专门用于特定任务的 AI 子代理。子代理是配置了特定专业知识和工具访问权限的独立 AI 助手。 + - **子命令：** + - **`create`**： + - **描述：** 启动交互式向导以创建新的子代理。向导会引导你完成位置选择、AI 驱动的提示生成、工具选择和视觉定制。 + - **用法：** `/agents create` + - **`manage`**： + - **描述：** 打开交互式管理对话框以查看、编辑和删除现有子代理。显示项目级和用户级代理。 + - **用法：** `/agents manage` + - **存储位置：** + - **项目级：** `.qwen/agents/`（与团队共享，优先级更高） + - **用户级：** `~/.qwen/agents/`（个人代理，跨项目可用） + - **注意：** 有关创建和管理子代理的详细信息，请参阅 [Subagents documentation](../subagents.md)。 - [**`/tools`**](../tools/index.md) - - **说明：** 显示当前在 Qwen Code 中可用的工具列表。 + - **描述：** 显示当前在 Qwen Code 中可用的工具列表。 - **子命令：** - **`desc`** 或 **`descriptions`**： - - **说明：** 显示每个工具的详细描述，包括工具名称及其提供给模型的完整描述。 + - **描述：** 显示每个工具的详细描述，包括提供给模型的每个工具的名称及其完整描述。 - **`nodesc`** 或 **`nodescriptions`**： - - **说明：** 隐藏工具描述，仅显示工具名称。 + - **描述：** 隐藏工具描述，仅显示工具名称。 - **`/privacy`** - - **说明：** 显示隐私声明，并允许用户选择是否同意收集其数据以改进服务。 + - **描述：** 显示隐私声明，并允许用户选择是否同意收集其数据以改进服务。 + +- **`/quit-confirm`** + - **描述：** 退出 Qwen Code 前显示确认对话框，让你选择如何处理当前会话。 + - **用法：** `/quit-confirm` + - **功能：** + - **立即退出：** 不保存任何内容直接退出（等效于 `/quit`） + - **生成摘要并退出：** 使用 `/summary` 创建项目摘要后退出 + - **保存对话并退出：** 使用自动生成的标签保存当前对话后退出 + - **快捷键：** 连续按两次 **Ctrl+C** 触发退出确认对话框 + - **注意：** 此命令在你按一次 Ctrl+C 时自动触发，提供防止意外退出的安全机制。 - **`/quit`**（或 **`/exit`**） - - **说明：** 退出 Qwen Code。 + - **描述：** 立即退出 Qwen Code，不显示任何确认对话框。 - **`/vim`** - - **说明：** 切换 vim 模式开启或关闭。启用 vim 模式后，输入区域支持在 NORMAL 和 INSERT 模式下的 vim 风格导航和编辑命令。 + - **描述：** 切换 vim 模式开/关。启用 vim 模式时，输入区域在 NORMAL 和 INSERT 模式下都支持 vim 风格的导航和编辑命令。 - **功能：** - - **NORMAL 模式：** 使用 `h`, `j`, `k`, `l` 导航；使用 `w`, `b`, `e` 按单词跳转；使用 `0`, `$`, `^` 跳转到行首/行尾；使用 `G`（或 `gg` 跳转到第一行）跳转到指定行 + - **NORMAL 模式：** 使用 `h`, `j`, `k`, `l` 导航；使用 `w`, `b`, `e` 按单词跳转；使用 `0`, `$`, `^` 跳转到行首/行尾；使用 `G`（或 `gg` 跳转到第一行）跳转到特定行 - **INSERT 模式：** 标准文本输入，按 Esc 返回 NORMAL 模式 - - **编辑命令：** 使用 `x` 删除，`c` 修改，`i`, `a`, `o`, `O` 插入；支持复杂操作如 `dd`, `cc`, `dw`, `cw` - - **数字前缀支持：** 在命令前加数字（如 `3h`, `5w`, `10G`） - - **重复上次命令：** 使用 `.` 重复上一次编辑操作 - - **持久设置：** Vim 模式偏好会保存到 `~/.qwen/settings.json` 并在会话间恢复 - - **状态指示器：** 启用时会在页脚显示 `[NORMAL]` 或 `[INSERT]` + - **编辑命令：** 使用 `x` 删除，使用 `c` 更改，使用 `i`, `a`, `o`, `O` 插入；复杂操作如 `dd`, `cc`, `dw`, `cw` + - **计数支持：** 在命令前加数字前缀（如 `3h`, `5w`, `10G`） + - **重复最后命令：** 使用 `.` 重复最后的编辑操作 + - **持久设置：** Vim 模式偏好设置保存到 `~/.qwen/settings.json` 并在会话间恢复 + - **状态指示器：** 启用时在页脚显示 `[NORMAL]` 或 `[INSERT]` - **`/init`** - - **说明：** 分析当前目录并默认创建一个 `QWEN.md` 上下文文件（或由 `contextFileName` 指定的文件名）。如果已存在非空文件，则不会进行任何更改。该命令会创建一个空文件并提示模型用项目特定的指令填充它。 + - **描述：** 分析当前目录并创建一个 `QWEN.md` 上下文文件（或由 `contextFileName` 指定的文件名）。如果已存在非空文件，则不进行任何更改。该命令会初始化一个空文件并提示模型用项目特定的指令填充它。 ### 自定义命令 快速入门，请参见下方的[示例](#example-a-pure-function-refactoring-command)。 -自定义命令允许你将最喜爱或最常用的 prompts 保存为个人快捷方式，在 Qwen Code 中重复使用。你可以创建仅适用于单个项目的命令，也可以创建在所有项目中全局可用的命令，从而简化工作流程并确保一致性。 +自定义命令允许你将最常用或最喜欢的 prompt 保存为 Qwen Code 中的个人快捷方式。你可以创建仅适用于单个项目的命令，也可以创建在所有项目中全局可用的命令，从而简化工作流程并确保一致性。 #### 文件位置与优先级 @@ -176,35 +211,63 @@ Qwen Code 从两个位置发现命令，按特定顺序加载： ##### 可选字段 -- `description` (String)：命令功能的简短一行描述。这段文字会显示在 `/help` 菜单中你的命令旁边。**如果你省略此字段，系统会根据文件名生成一个通用描述。** +- `description` (String)：命令功能的简短一行描述。这段文字会显示在 `/help` 菜单中你的命令旁边。**如果你省略此字段，系统会根据文件名自动生成一个通用描述。** #### 处理参数 -自定义命令支持两种强大且低摩擦的参数处理方法。CLI 会根据你的命令 `prompt` 内容自动选择正确的方法。 +自定义命令支持两种强大的参数处理方法。CLI 会根据你的命令 `prompt` 内容自动选择正确的方法。 + +##### 1. 使用 `{{args}}` 的上下文感知注入 + +如果你的 `prompt` 包含特殊占位符 `{{args}}`，CLI 会将该占位符替换为用户在命令名后输入的文本。 -##### 1. 使用 `{{args}}` 的简写注入 +这种注入的行为取决于它被使用的位置： -如果你的 `prompt` 包含特殊占位符 `{{args}}`，CLI 会将该占位符替换为用户在命令名称后输入的所有文本。这种方法非常适合简单的、确定性的命令，你需要将用户输入注入到较大的 prompt 模板中的特定位置。 +**A. 原始注入（在 Shell 命令外部）** + +当在 prompt 的主体中使用时，参数会按用户输入的原样注入。 **示例 (`git/fix.toml`):** ```toml -# In: ~/.qwen/commands/git/fix.toml +# 调用方式：/git:fix "按钮未对齐" + +description = "为给定问题生成修复方案。" +prompt = "请为这里描述的问题提供代码修复：{{args}}。" +``` + +模型接收到的内容是：`请为这里描述的问题提供代码修复："按钮未对齐"。` + +**B. 在 Shell 命令中使用参数（在 `!{...}` 块内）** + +当你在 shell 注入块（`!{...}`）中使用 `{{args}}` 时，参数会在替换前自动进行 **shell 转义**。这使得你可以安全地将参数传递给 shell 命令，确保生成的命令语法正确且安全，同时防止命令注入漏洞。 + +**示例（`/grep-code.toml`）：** -# 调用方式：/git:fix "移动端按钮错位" +```toml +prompt = """ +请总结模式 `{{args}}` 的查找结果。 -description = "为给定的 GitHub issue 生成修复方案。" -prompt = "请分析已暂存的 git 更改，并为以下问题提供代码修复：{{args}}。" +搜索结果： +!{grep -r {{args}} .} +""" ``` -模型将收到最终的 prompt：`请分析已暂存的 git 更改，并为以下问题提供代码修复："移动端按钮错位"` +当你运行 `/grep-code It's complicated` 时： + +1. CLI 检测到 `{{args}}` 同时出现在 `!{...}` 块内外。 +2. 块外：第一个 `{{args}}` 被直接替换为 `It's complicated`。 +3. 块内：第二个 `{{args}}` 被替换为转义后的版本（例如在 Linux 上是 `"It's complicated"`）。 +4. 实际执行的命令是 `grep -r "It's complicated" .`。 +5. CLI 会提示你确认这个确切且安全的命令后再执行。 +6. 最终 prompt 被发送出去。 ##### 2. 默认参数处理 如果你的 `prompt` 中**没有**包含特殊占位符 `{{args}}`，CLI 会使用默认行为来处理参数。 -如果你为命令提供了参数（例如 `/mycommand arg1`），CLI 会在 prompt 的末尾追加你输入的完整命令，并用两个换行符分隔。这样可以让模型同时看到原始指令和你刚刚提供的具体参数。 +如果你为命令提供了参数（例如 `/mycommand arg1`），CLI 会在 prompt 的末尾追加你输入的完整命令，中间用两个换行符分隔。这样可以让模型同时看到原始指令和你刚刚提供的具体参数。 如果你**没有**提供任何参数（例如 `/mycommand`），prompt 会原样发送给模型，不追加任何内容。 @@ -223,11 +286,11 @@ prompt = """ # 任务：更新 Changelog -你是这个软件项目的专家维护者。用户调用了添加新 changelog 条目的命令。 +你是这个软件项目的专家维护者。用户调用了一个命令来向 changelog 添加新条目。 **用户的原始命令会附加在你的指令下方。** -你的任务是从用户输入中解析出 ``、`` 和 ``，然后使用 `write_file` 工具正确更新 `CHANGELOG.md` 文件。 +你的任务是从用户的输入中解析出 ``、`` 和 ``，然后使用 `write_file` 工具正确更新 `CHANGELOG.md` 文件。 ## 预期格式 命令遵循以下格式：`/changelog ` @@ -252,14 +315,11 @@ prompt = """ **工作原理：** -1. **注入命令：** 在你的 `prompt` 中使用 `!{...}` 语法，指定命令应在哪里运行以及如何注入其输出。 -2. **确认执行：** 当你运行命令时，会出现一个对话框，列出 prompt 想要执行的 shell 命令。 -3. **授予权限：** 你可以选择： - - **仅允许一次：** 命令将仅在此时执行一次。 - - **在此会话中始终允许：** 命令将被添加到当前 CLI 会话的临时白名单中，后续不再需要确认。 - - **否：** 取消执行 shell 命令。 - -CLI 仍然会遵循全局 `excludeTools` 和 `coreTools` 设置。如果某个命令在你的配置中被明确禁止，则该命令将被直接阻止，且不会弹出确认提示。 +1. **注入命令：** 使用 `!{...}` 语法。 +2. **参数替换：** 如果块内存在 `{{args}}`，它会自动进行 shell 转义（参见上文的 [上下文感知注入](#1-context-aware-injection-with-args)）。 +3. **健壮解析：** 解析器能够正确处理包含嵌套大括号的复杂 shell 命令，例如包含 JSON 数据的命令。 +4. **安全检查与确认：** CLI 会对最终解析后的命令（即参数转义和替换后）执行安全检查。此时会弹出一个对话框，显示即将执行的确切命令。 +5. **执行与错误报告：** 命令执行后，如果失败，注入到 prompt 中的输出将包含错误信息（stderr），并附带状态行，例如 `[Shell command exited with code 1]`。这有助于模型理解失败的上下文。 **示例 (`git/commit.toml`)：** @@ -285,7 +345,7 @@ prompt = """ ``` -当你运行 `/git:commit` 时，CLI 会首先执行 `git diff --staged`，然后将 `!{git diff --staged}` 替换为该命令的输出，再将最终完整的 prompt 发送给模型。 +当你运行 `/git:commit` 时，CLI 会先执行 `git diff --staged`，然后将 `!{git diff --staged}` 替换为该命令的输出结果，最后将完整拼接好的 prompt 发送给模型。 #### 示例：一个"纯函数"重构命令 @@ -310,11 +370,11 @@ touch ~/.qwen/commands/refactor/pure.toml # 此命令将通过以下方式调用：/refactor:pure -description = "要求模型将当前上下文中的代码重构为纯函数。" +description = "要求模型将当前上下文重构为纯函数。" prompt = """ 请分析我在当前上下文中提供的代码。 -将其重构为一个纯函数。 +将其重构为纯函数。 你的回复应包括： 1. 重构后的纯函数代码块。 @@ -324,7 +384,7 @@ prompt = """ **3. 运行命令：** -就是这样！你现在可以在 CLI 中运行你的命令了。首先，你可能需要将一个文件添加到上下文中，然后调用你的命令： +就是这样！你现在可以在 CLI 中运行你的命令了。首先，你可以将一个文件添加到上下文中，然后调用你的命令： ``` > @my-messy-function.js @@ -335,25 +395,25 @@ Qwen Code 将会执行你在 TOML 文件中定义的多行 prompt。 ## At 命令 (`@`) -At 命令用于将文件或目录的内容作为 prompt 的一部分包含到模型中。这些命令支持 Git 感知过滤。 +At 命令用于将文件或目录的内容作为 prompt 的一部分发送给模型。这些命令支持 Git 感知过滤。 - **`@<文件或目录路径>`** - - **说明：** 将指定文件或多个文件的内容注入到当前 prompt 中。这在需要针对特定代码、文本或文件集合提问时非常有用。 + - **说明：** 将指定文件或多个文件的内容注入到当前 prompt 中。适用于针对特定代码、文本或文件集合进行提问。 - **示例：** - - `@path/to/your/file.txt 解释这段文本。` - - `@src/my_project/ 总结这个目录中的代码。` - - `这个文件是关于什么的？@README.md` + - `@path/to/your/file.txt Explain this text.` + - `@src/my_project/ Summarize the code in this directory.` + - `What is this file about? @README.md` - **详细说明：** - - 如果提供的是单个文件的路径，则读取该文件的内容。 - - 如果提供的是目录路径，则尝试读取该目录及其子目录中的文件内容。 - - 路径中如果包含空格，应使用反斜杠进行转义（例如：`@My\ Documents/file.txt`）。 + - 如果提供的是单个文件路径，则读取该文件的内容。 + - 如果提供的是目录路径，则尝试读取该目录及其子目录下的所有文件内容。 + - 路径中如果包含空格，需使用反斜杠转义（例如：`@My\ Documents/file.txt`）。 - 内部使用 `read_many_files` 工具实现。内容会被读取并插入到你的查询中，然后再发送给模型。 - - **Git 感知过滤：** 默认情况下，Git 忽略的文件（如 `node_modules/`、`dist/`、`.env`、`.git/`）会被排除。可以通过 `fileFiltering` 设置更改此行为。 - - **文件类型：** 此命令适用于基于文本的文件。虽然可能会尝试读取任何文件，但底层的 `read_many_files` 工具可能会跳过或截断二进制文件或非常大的文件，以确保性能和相关性。工具会提示哪些文件被跳过。 - - **输出：** CLI 会显示一条工具调用消息，表明使用了 `read_many_files`，并附带一条详细说明处理状态和路径的消息。 + - **Git 感知过滤：** 默认情况下，会排除被 Git 忽略的文件（如 `node_modules/`、`dist/`、`.env`、`.git/`）。可以通过 `fileFiltering` 设置更改此行为。 + - **文件类型：** 该命令主要适用于文本文件。虽然可能会尝试读取任何类型的文件，但二进制文件或非常大的文件可能会被底层的 `read_many_files` 工具跳过或截断，以确保性能和相关性。工具会提示哪些文件被跳过了。 + - **输出：** CLI 会显示一条工具调用消息，表明使用了 `read_many_files`，同时会显示处理状态和所涉及的路径信息。 - **`@`（单独的 @ 符号）** - - **说明：** 如果你输入一个单独的 `@` 符号而没有指定路径，查询将按原样发送给模型。这在你特别想在 prompt 中**讨论** `@` 符号本身时可能有用。 + - **说明：** 如果你只输入了一个 `@` 符号而没有指定路径，query 会原样发送给模型。这在你 prompt 中明确讨论 `@` 符号本身时可能有用。 ### `@` 命令的错误处理 @@ -365,7 +425,7 @@ At 命令用于将文件或目录的内容作为 prompt 的一部分包含到模 使用 `!` 前缀可以直接在 Qwen Code 中与系统 shell 进行交互。 - **`!`** - - **说明：** 使用 `bash`（Linux/macOS）或 `cmd.exe`（Windows）执行指定的 ``。命令的输出或错误信息会显示在终端中。 + - **说明：** 使用 `bash`（Linux/macOS）或 `cmd.exe`（Windows）执行指定的 ``。命令的任何输出或错误都会显示在终端中。 - **示例：** - `!ls -la`（执行 `ls -la` 并返回 Qwen Code） - `!git status`（执行 `git status` 并返回 Qwen Code） @@ -374,10 +434,10 @@ At 命令用于将文件或目录的内容作为 prompt 的一部分包含到模 - **说明：** 单独输入 `!` 可切换 Shell 模式。 - **进入 Shell 模式：** - 激活后，Shell 模式会使用不同的颜色和“Shell 模式指示器”。 - - 在 Shell 模式下，你输入的内容会被直接解释为 shell 命令。 + - 在 Shell 模式下，你输入的文本将直接作为 shell 命令解释执行。 - **退出 Shell 模式：** - - 退出后，UI 会恢复为标准外观，Qwen Code 的正常行为也会恢复。 + - 退出后，UI 将恢复为标准外观，Qwen Code 的正常行为也将恢复。 -- **所有 `!` 用法的注意事项：** 在 Shell 模式下执行的命令具有与你在终端中直接运行时相同的权限和影响。 +- **所有 `!` 使用注意事项：** 在 Shell 模式下执行的命令具有与你在终端中直接运行时相同的权限和影响。 - **环境变量：** 当通过 `!` 或 Shell 模式执行命令时，子进程中会设置 `QWEN_CODE=1` 环境变量。这允许脚本或工具检测它们是否从 CLI 中运行。 \ No newline at end of file diff --git a/website/content/zh/cli/configuration.md b/website/content/zh/cli/configuration.md index 6c09c1b6..ae8a123a 100644 --- a/website/content/zh/cli/configuration.md +++ b/website/content/zh/cli/configuration.md @@ -4,7 +4,7 @@ Qwen Code 提供了多种方式来配置其行为，包括环境变量、命令 ## 配置层级 -配置按以下优先级顺序应用（较低数字的配置会被较高数字的配置覆盖）： +配置按以下优先级顺序应用（数字越小优先级越低，会被数字越高的覆盖）： 1. **默认值：** 应用程序内的硬编码默认值。 2. **用户设置文件：** 当前用户的全局设置。 @@ -22,16 +22,17 @@ 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/qwen-code/settings.json`（Linux）、`C:\ProgramData\qwen-code\settings.json`（Windows）或 `/Library/Application Support/QwenCode/settings.json`（macOS）。可以通过 `QWEN_CODE_SYSTEM_SETTINGS_PATH` 环境变量覆盖路径。 + - **作用范围：** 应用于系统上所有用户的 Qwen Code 会话。系统配置会覆盖用户和项目配置。对于企业中的系统管理员来说，这可能有助于控制用户的 Qwen Code 设置。 -**关于配置中的环境变量说明：** 在你的 `settings.json` 文件中，字符串值可以使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量。这些变量在设置加载时会自动解析。例如，如果你有一个环境变量 `MY_API_TOKEN`，你可以在 `settings.json` 中这样使用它：`"apiKey": "$MY_API_TOKEN"`。 +**关于配置中的环境变量说明：** 在你的 `settings.json` 文件中，字符串值可以使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量。这些变量在加载配置时会自动解析。例如，如果你有一个环境变量 `MY_API_TOKEN`，你可以在 `settings.json` 中这样使用它：`"apiKey": "$MY_API_TOKEN"`。 ### 项目中的 `.qwen` 目录 -除了项目设置文件外，项目的 `.qwen` 目录还可以包含其他与 Qwen Code 操作相关的项目特定文件，例如： +除了项目设置文件外，项目的 `.qwen` 目录还可以包含其他与 Qwen Code 运行相关的项目特定文件，例如： - [自定义沙箱配置](#sandboxing)（例如，`.qwen/sandbox-macos-custom.sb`、`.qwen/sandbox.Dockerfile`）。 @@ -58,8 +59,8 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **说明：** 控制 @ 命令和文件发现工具的 git-aware 文件过滤行为。 - **默认值：** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` - **属性：** - - **`respectGitIgnore`**（布尔值）：在发现文件时是否遵循 `.gitignore` 的规则。设置为 `true` 时，git 忽略的文件（如 `node_modules/`、`dist/`、`.env`）会自动从 @ 命令和文件列表操作中排除。 - - **`enableRecursiveFileSearch`**（布尔值）：是否在提示中补全 @ 前缀时，启用递归搜索当前目录树下的文件名。 + - **`respectGitIgnore`**（布尔值）：在发现文件时是否遵循 `.gitignore` 的规则。设置为 `true` 时，被 git 忽略的文件（如 `node_modules/`、`dist/`、`.env`）会自动从 @ 命令和文件列表操作中排除。 + - **`enableRecursiveFileSearch`**（布尔值）：在提示中补全 @ 前缀时，是否启用递归搜索当前目录树下的文件名。 - **示例：** ```json "fileFiltering": { @@ -69,27 +70,27 @@ 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` 明确选择允许执行的命令。 + - **安全提示：** `excludeTools` 中对 `run_shell_command` 的命令限制基于简单的字符串匹配，容易被绕过。此功能**不是安全机制**，不应依赖它来安全执行不受信任的代码。建议使用 `coreTools` 明确指定允许执行的命令。 - **`allowMCPServers`**（字符串数组）： - - **说明：** 允许你指定一个 MCP server 名称列表，这些服务器将对模型可用。可用于限制连接的 MCP 服务器。注意：如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 - - **默认值：** 所有 MCP 服务器都对模型可用。 + - **说明：** 允许你指定一组 MCP server 名称，这些 server 将对模型可用。可用于限制连接的 MCP server 范围。注意：如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 + - **默认值：** 所有 MCP server 均可用。 - **示例：** `"allowMCPServers": ["myPythonServer"]` - - **安全提示：** 此功能使用简单的字符串匹配来识别 MCP 服务器名称，可被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法配置自己的 MCP 服务器。此功能不应被视为严格的安全机制。 + - **安全提示：** 此配置基于简单的字符串匹配，MCP server 名称可能被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法自行配置 MCP server。此配置不应被视为严格的安全机制。 - **`excludeMCPServers`**（字符串数组）： - - **说明：** 允许你指定一个应从模型中排除的 MCP server 名称列表。如果某个服务器同时出现在 `excludeMCPServers` 和 `allowMCPServers` 中，则会被排除。注意：如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 - - **默认值：** 不排除任何 MCP 服务器。 + - **说明：** 允许你指定一组应从模型中排除的 MCP server 名称。如果某个 server 同时出现在 `excludeMCPServers` 和 `allowMCPServers` 中，则会被排除。注意：如果设置了 `--allowed-mcp-server-names`，此配置将被忽略。 + - **默认值：** 不排除任何 MCP server。 - **示例：** `"excludeMCPServers": ["myNodeServer"]` - - **安全提示：** 此功能使用简单的字符串匹配来识别 MCP 服务器名称，可被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法配置自己的 MCP 服务器。此功能不应被视为严格的安全机制。 + - **安全提示：** 此配置基于简单的字符串匹配，MCP server 名称可能被修改。如果你是系统管理员并希望防止用户绕过此限制，请考虑在系统级别配置 `mcpServers`，使用户无法自行配置 MCP server。此配置不应被视为严格的安全机制。 - **`autoAccept`**（布尔值）： - **说明：** 控制 CLI 是否自动接受并执行被认为是安全的工具调用（例如只读操作），而无需用户明确确认。如果设置为 `true`，CLI 将跳过对安全工具的确认提示。 @@ -102,7 +103,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **示例：** `"theme": "GitHub"` - **`vimMode`**（布尔值）： - - **说明：** 启用或禁用输入编辑的 vim 模式。启用后，输入区域支持 vim 风格的导航和编辑命令，包括 NORMAL 和 INSERT 模式。vim 模式状态会在页脚显示，并在会话之间保持。 + - **说明：** 启用或禁用输入编辑的 vim 模式。启用后，输入区域支持 vim 风格的导航和编辑命令，包括 NORMAL 和 INSERT 模式。vim 模式状态会在页脚显示，并在会话间保持。 - **默认值：** `false` - **示例：** `"vimMode": true` @@ -112,31 +113,35 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **示例：** `"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) 服务器的连接，用于发现和使用自定义工具。Qwen Code 会尝试连接每个配置的 MCP 服务器以发现可用工具。如果多个 MCP 服务器暴露了同名工具，工具名称将加上你在配置中定义的服务器别名前缀（例如 `serverAlias__actualToolName`）以避免冲突。注意：系统可能会为了兼容性而从 MCP 工具定义中剥离某些 schema 属性。 + - **说明：** 配置一个或多个 Model-Context Protocol (MCP) server 的连接，用于发现和使用自定义工具。Qwen Code 会尝试连接每个配置的 MCP server 以发现可用工具。如果多个 MCP server 提供同名工具，工具名称将加上你在配置中定义的 server 别名前缀（例如 `serverAlias__actualToolName`）以避免冲突。注意：系统可能会为了兼容性而从 MCP 工具定义中剥离某些 schema 属性。必须提供 `command`、`url` 或 `httpUrl` 中的至少一个。如果多个都指定，优先级顺序为 `httpUrl` > `url` > `command`。 - **默认值：** 空 - **属性：** - - **``**（对象）：指定服务器的参数。 - - `command`（字符串，必填）：启动 MCP 服务器的命令。 + - **``**（对象）：指定 server 的参数。 + - `command`（字符串，可选）：通过标准 I/O 启动 MCP server 的命令。 - `args`（字符串数组，可选）：传递给命令的参数。 - - `env`（对象，可选）：为服务器进程设置的环境变量。 - - `cwd`（字符串，可选）：启动服务器的工作目录。 - - `timeout`（数字，可选）：对此 MCP 服务器请求的超时时间（毫秒）。 - - `trust`（布尔值，可选）：信任此服务器并跳过所有工具调用确认。 - - `includeTools`（字符串数组，可选）：从此 MCP 服务器包含的工具名称列表。指定后，只有列出的工具会从该服务器可用（白名单行为）。未指定时，默认启用服务器的所有工具。 - - `excludeTools`（字符串数组，可选）：从此 MCP 服务器排除的工具名称列表。即使服务器暴露了这些工具，模型也无法使用。**注意：** `excludeTools` 优先于 `includeTools` —— 如果某个工具同时出现在两个列表中，它将被排除。 + - `env`（对象，可选）：为 server 进程设置的环境变量。 + - `cwd`（字符串，可选）：启动 server 的工作目录。 + - `url`（字符串，可选）：使用 Server-Sent Events (SSE) 通信的 MCP server URL。 + - `httpUrl`（字符串，可选）：使用可流式 HTTP 通信的 MCP server URL。 + - `headers`（对象，可选）：发送到 `url` 或 `httpUrl` 的 HTTP headers。 + - `timeout`（数字，可选）：对此 MCP server 请求的超时时间（毫秒）。 + - `trust`（布尔值，可选）：信任此 server 并跳过所有工具调用确认。 + - `description`（字符串，可选）：server 的简要描述，可能用于显示。 + - `includeTools`（字符串数组，可选）：从此 MCP server 包含的工具名称列表。指定后，仅此列表中的工具可用（白名单行为）。未指定时，默认启用 server 的所有工具。 + - `excludeTools`（字符串数组，可选）：从此 MCP server 排除的工具名称列表。即使 server 提供这些工具，模型也无法使用。**注意：** `excludeTools` 优先级高于 `includeTools` —— 如果某个工具同时出现在两个列表中，它将被排除。 - **示例：** ```json "mcpServers": { @@ -159,18 +164,32 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 "env": { "API_KEY": "$MY_API_TOKEN" } + }, + "mySseServer": { + "url": "http://localhost:8081/events", + "headers": { + "Authorization": "Bearer $MY_SSE_TOKEN" + }, + "description": "An example SSE-based MCP server." + }, + "myStreamableHttpServer": { + "httpUrl": "http://localhost:8082/stream", + "headers": { + "X-API-Key": "$MY_HTTP_API_KEY" + }, + "description": "An example Streamable HTTP-based MCP server." } } ``` - **`checkpointing`**（对象）： - - **说明：** 配置 checkpointing 功能，允许你保存和恢复对话和文件状态。更多详情请参见 [Checkpointing documentation](../checkpointing.md)。 + - **说明：** 配置 checkpointing 功能，允许你保存和恢复对话及文件状态。详情请参见 [Checkpointing documentation](../checkpointing.md)。 - **默认值：** `{"enabled": false}` - **属性：** - **`enabled`**（布尔值）：当为 `true` 时，`/restore` 命令可用。 - **`preferredEditor`**（字符串）： - - **说明：** 指定查看 diff 时使用的首选编辑器。 + - **说明：** 指定用于查看 diff 的首选编辑器。 - **默认值：** `vscode` - **示例：** `"preferredEditor": "vscode"` @@ -180,7 +199,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **属性：** - **`enabled`**（布尔值）：是否启用遥测。 - **`target`**（字符串）：遥测数据的目标。支持的值为 `local` 和 `gcp`。 - - **`otlpEndpoint`**（字符串）：OTLP Exporter 的端点。 + - **`otlpEndpoint`**（字符串）：OTLP Exporter 的 endpoint。 - **`logPrompts`**（布尔值）：是否在日志中包含用户提示内容。 - **示例：** ```json @@ -201,7 +220,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`hideTips`**（布尔值）： - - **说明：** 启用或禁用 CLI 界面中的帮助提示。 + - **说明：** 启用或禁用 CLI 界面中的提示信息。 - **默认值：** `false` - **示例：** ```json @@ -217,7 +236,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`maxSessionTurns`**（数字）： - - **说明：** 设置会话的最大轮数。如果超过此限制，CLI 将停止处理并开始新的聊天。 + - **说明：** 设置会话的最大轮数。如果会话超过此限制，CLI 将停止处理并开始新对话。 - **默认值：** `-1`（无限制） - **示例：** ```json @@ -246,7 +265,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 ``` - **`includeDirectories`**（字符串数组）： - - **说明：** 指定一个额外的绝对或相对路径数组，这些路径将包含在工作区上下文中。这允许你像操作单个目录一样操作多个目录中的文件。路径可以使用 `~` 来引用用户的主目录。此设置可以与 `--include-directories` 命令行标志结合使用。 + - **说明：** 指定一组额外的绝对或相对路径，将其包含在工作区上下文中。这允许你跨多个目录操作文件，就像它们在一个目录中一样。路径可以使用 `~` 表示用户主目录。此设置可以与 `--include-directories` 命令行标志结合使用。 - **默认值：** `[]` - **示例：** ```json @@ -270,24 +289,7 @@ Qwen Code 使用 `settings.json` 文件进行持久化配置。这些文件有 - **默认值：** `undefined`（网络搜索禁用） - **示例：** `"tavilyApiKey": "tvly-your-api-key-here"` -- **`chatCompression`**（对象）： - - **说明：** 控制聊天历史压缩的设置，包括自动压缩和通过 `/compress` 命令手动触发的压缩。 - - **属性：** - - **`contextPercentageThreshold`**（数字）：介于 0 到 1 之间的值，指定触发压缩的 token 阈值占模型总 token 限制的百分比。例如，值为 `0.6` 时，当聊天历史超过 token 限制的 60% 时将触发压缩。 - - **示例：** - ```json - "chatCompression": { - "contextPercentageThreshold": 0.6 - } - ``` - -- **`showLineNumbers`**（布尔值）： - - **说明：** 控制 CLI 输出中的代码块是否显示行号。 - - **默认值：** `true` - - **示例：** - ```json - "showLineNumbers": false - ``` +- **`chatCompression`**（ ### 示例 `settings.json`： @@ -334,70 +336,51 @@ CLI 会保存你运行的 shell 命令历史记录。为了避免不同项目之 - **位置：** `~/.qwen/tmp//shell_history` - `` 是根据你的项目根路径生成的唯一标识符。 - - 历史记录存储在名为 `shell_history` 的文件中。 + - 历史记录存储在一个名为 `shell_history` 的文件中。 -## 环境变量与 `.env` 文件 +## 环境变量 & `.env` 文件 -环境变量是配置应用程序的常见方式，尤其适用于敏感信息（如 API key）或在不同环境中可能发生变化的设置。 +环境变量是配置应用程序的常见方式，尤其适用于敏感信息（如 API keys）或在不同环境中可能变化的设置。关于认证配置，请参考 [Authentication documentation](./authentication.md)，其中涵盖了所有可用的认证方法。 CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： 1. 当前工作目录中的 `.env` 文件。 -2. 如果未找到，则向上级目录逐层查找，直到找到 `.env` 文件，或到达项目根目录（以 `.git` 文件夹为标识）或用户主目录。 -3. 如果仍未找到，则尝试加载 `~/.env`（用户主目录下的 `.env` 文件）。 +2. 如果未找到，则向上级目录查找，直到找到 `.env` 文件，或到达项目根目录（以 `.git` 文件夹为标识）或用户主目录。 +3. 如果仍未找到，则查找 `~/.env`（用户主目录下的 `.env` 文件）。 -**环境变量排除：** 某些环境变量（如 `DEBUG` 和 `DEBUG_MODE`）默认会自动从项目 `.env` 文件中排除，以避免干扰 CLI 的行为。来自 `.qwen/.env` 文件的变量则永远不会被排除。你可以通过在 `settings.json` 文件中配置 `excludedProjectEnvVars` 来自定义这一行为。 +**环境变量排除：** 某些环境变量（如 `DEBUG` 和 `DEBUG_MODE`）默认会从项目 `.env` 文件中自动排除，以防止干扰 CLI 的行为。来自 `.qwen/.env` 文件的变量永远不会被排除。你可以通过在 `settings.json` 文件中配置 `excludedProjectEnvVars` 来自定义这一行为。 -- **`GEMINI_API_KEY`**（必填）： - - 用于 Gemini API 的 API key。 - - **至关重要**，CLI 无法在没有它的情况下运行。 +- **`OPENAI_API_KEY`**: + - 多种可用的 [认证方法](./authentication.md) 之一。 - 可在 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`。 - - 示例：`export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"` -- **`GOOGLE_APPLICATION_CREDENTIALS`**（字符串）： - - **说明：** 指向你的 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）。 - - 在非 express 模式下使用 Vertex AI 时必需。 - - 示例：`export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"` -- **`GEMINI_SANDBOX`**： +- **`OPENAI_BASE_URL`**: + - 多种可用的 [认证方法](./authentication.md) 之一。 + - 可在 shell 配置文件（如 `~/.bashrc`、`~/.zshrc`）或 `.env` 文件中设置。 +- **`OPENAI_MODEL`**: + - 指定默认使用的 OPENAI 模型。 + - 会覆盖硬编码的默认值。 + - 示例：`export OPENAI_MODEL="qwen3-coder-plus"` +- **`GEMINI_SANDBOX`**: - 替代 `settings.json` 中的 `sandbox` 设置。 - - 接受 `true`、`false`、`docker`、`podman` 或自定义命令字符串。 -- **`SEATBELT_PROFILE`**（仅 macOS）： - - 切换 macOS 上的 Seatbelt（`sandbox-exec`）配置文件。 - - `permissive-open`：（默认）限制写入项目文件夹（及其他少数几个文件夹，详见 `packages/cli/src/utils/sandbox-macos-permissive-open.sb`），但允许其他操作。 + - 可接受的值包括 `true`、`false`、`docker`、`podman` 或自定义命令字符串。 +- **`SEATBELT_PROFILE`**（仅 macOS）: + - 在 macOS 上切换 Seatbelt（`sandbox-exec`）配置文件。 + - `permissive-open`：（默认）限制写入项目文件夹（及其他少数文件夹，详见 `packages/cli/src/utils/sandbox-macos-permissive-open.sb`），但允许其他操作。 - `strict`：使用严格配置文件，默认拒绝所有操作。 - - ``：使用自定义配置文件。要定义自定义配置文件，请在项目 `.qwen/` 目录下创建名为 `sandbox-macos-.sb` 的文件（例如：`my-project/.qwen/sandbox-macos-custom.sb`）。 -- **`DEBUG` 或 `DEBUG_MODE`**（通常由底层库或 CLI 自身使用）： + - ``：使用自定义配置文件。要定义自定义配置文件，请在项目 `.qwen/` 目录下创建名为 `sandbox-macos-.sb` 的文件（例如 `my-project/.qwen/sandbox-macos-custom.sb`）。 +- **`DEBUG` 或 `DEBUG_MODE`**（通常由底层库或 CLI 自身使用）: - 设置为 `true` 或 `1` 可启用详细调试日志，有助于排查问题。 - - **注意：** 这些变量默认会自动从项目 `.env` 文件中排除，以避免干扰 CLI 行为。如需为 Qwen Code 特别设置这些变量，请使用 `.qwen/.env` 文件。 -- **`NO_COLOR`**： + - **注意：** 这些变量默认会从项目 `.env` 文件中自动排除，以防止干扰 CLI 行为。如需为 Qwen Code 特别设置这些变量，请使用 `.qwen/.env` 文件。 +- **`NO_COLOR`**: - 设置任意值可禁用 CLI 中的所有颜色输出。 -- **`CLI_TITLE`**： +- **`CLI_TITLE`**: - 设置一个字符串来自定义 CLI 的标题。 -- **`CODE_ASSIST_ENDPOINT`**： - - 指定 code assist server 的 endpoint。 - - 对开发和测试很有用。 -- **`TAVILY_API_KEY`**： - - 用于 Tavily 网络搜索服务的 API key。 - - 启用 `web_search` 工具功能时必需。 +- **`CODE_ASSIST_ENDPOINT`**: + - 指定代码辅助服务的 endpoint。 + - 对开发和测试非常有用。 +- **`TAVILY_API_KEY`**: + - 你的 Tavily 网络搜索服务的 API key。 + - 启用 `web_search` 工具功能所必需。 - 若未配置，网络搜索工具将被禁用并跳过。 - 示例：`export TAVILY_API_KEY="tvly-your-api-key-here"` @@ -406,10 +389,10 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： 在运行 CLI 时直接传入的参数可以覆盖该特定会话的其他配置。 - **`--model `** (**`-m `**): - - 指定本次会话使用的 Gemini 模型。 - - 示例：`npm start -- --model gemini-1.5-pro-latest` + - 指定本次会话使用的 Qwen 模型。 + - 示例：`npm start -- --model qwen3-coder-plus` - **`--prompt `** (**`-p `**): - - 用于直接将 prompt 传递给命令。这会以非交互模式调用 Qwen Code。 + - 用于直接向命令传递 prompt。这将以非交互模式调用 Qwen Code。 - **`--prompt-interactive `** (**`-i `**): - 使用提供的 prompt 作为初始输入启动交互式会话。 - prompt 会在交互式会话中处理，而不是在会话开始前处理。 @@ -431,8 +414,8 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： - 启用 YOLO 模式，自动批准所有工具调用。 - **`--approval-mode `**: - 设置工具调用的审批模式。可用模式包括： - - `default`：每个工具调用都需要手动审批（默认行为） - - `auto_edit`：自动批准编辑类工具（replace、write_file），其他工具仍需手动审批 + - `default`：对每个工具调用提示审批（默认行为） + - `auto_edit`：自动批准编辑类工具（edit、write_file），其他工具仍需提示审批 - `yolo`：自动批准所有工具调用（等同于 `--yolo`） - 不能与 `--yolo` 同时使用。请使用 `--approval-mode=yolo` 替代 `--yolo`，以采用新的统一方式。 - 示例：`qwen --approval-mode auto_edit` @@ -442,13 +425,15 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： - 设置 telemetry 目标。更多信息请参见 [telemetry](../telemetry.md)。 - **`--telemetry-otlp-endpoint`**: - 设置 telemetry 的 OTLP endpoint。更多信息请参见 [telemetry](../telemetry.md)。 +- **`--telemetry-otlp-protocol`**: + - 设置 telemetry 的 OTLP 协议（`grpc` 或 `http`）。默认为 `grpc`。更多信息请参见 [telemetry](../telemetry.md)。 - **`--telemetry-log-prompts`**: - 启用 telemetry 的 prompt 日志记录。更多信息请参见 [telemetry](../telemetry.md)。 - **`--checkpointing`**: - 启用 [checkpointing](../checkpointing.md)。 - **`--extensions `** (**`-e `**): - - 指定本次会话使用的扩展列表。如果未提供，则使用所有可用扩展。 - - 使用特殊关键字 `qwen -e none` 可禁用所有扩展。 + - 指定本次会话要使用的扩展列表。如果未提供，则使用所有可用扩展。 + - 可使用特殊关键字 `qwen -e none` 禁用所有扩展。 - 示例：`qwen -e my-extension -e my-other-extension` - **`--list-extensions`** (**`-l`**): - 列出所有可用扩展并退出。 @@ -456,53 +441,54 @@ 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`**: - 显示 CLI 的版本。 - **`--openai-logging`**: - - 启用 OpenAI API 调用的日志记录，用于调试和分析。此标志会覆盖 `settings.json` 中的 `enableOpenAILogging` 设置。 + - 启用 OpenAI API 调用的日志记录，便于调试和分析。此标志会覆盖 `settings.json` 中的 `enableOpenAILogging` 设置。 - **`--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 模型在交互过程中了解的指令、指南或上下文信息。该系统被设计为分层管理这种指令上下文。 +- **用途：** 这些 Markdown 文件包含你希望 Qwen 模型在交互过程中了解的指令、指南或上下文信息。系统被设计为分层管理这些指令上下文。 -### 示例上下文文件内容（例如，`QWEN.md`） +### 示例上下文文件内容 (例如 `QWEN.md`) -以下是一个概念性示例，展示了一个位于 TypeScript 项目根目录的上下文文件可能包含的内容： +以下是一个位于 TypeScript 项目根目录的上下文文件可能包含的内容概念示例： ```markdown -# 项目：My Awesome TypeScript Library +# Project: My Awesome TypeScript Library -## 通用说明： +## General Instructions: -- 在生成新的 TypeScript 代码时，请遵循现有的编码风格。 -- 确保所有新增的函数和类都包含 JSDoc 注释。 -- 在适当的情况下，优先使用函数式编程范式。 -- 所有代码应兼容 TypeScript 5.0 和 Node.js 20+。 +- When generating new TypeScript code, please follow the existing coding style. +- Ensure all new functions and classes have JSDoc comments. +- Prefer functional programming paradigms where appropriate. +- All code should be compatible with TypeScript 5.0 and Node.js 20+. -## 编码风格： +## Coding Style: -- 使用 2 个空格进行缩进。 -- 接口名称应以 `I` 为前缀（例如，`IUserService`）。 -- 类的私有成员应以下划线（`_`）为前缀。 -- 始终使用严格相等（`===` 和 `!==`）。 +- Use 2 spaces for indentation. +- Interface names should be prefixed with `I` (e.g., `IUserService`). +- Private class members should be prefixed with an underscore (`_`). +- Always use strict equality (`===` and `!==`). -## 特定组件：`src/api/client.ts` +## Specific Component: `src/api/client.ts` -- 此文件负责处理所有向外的 API 请求。 -- 在添加新的 API 调用函数时，请确保包含完善的错误处理和日志记录。 -- 对于所有 GET 请求，请使用现有的 `fetchWithRetry` 工具函数。 +- This file handles all outbound API requests. +- When adding new API call functions, ensure they include robust error handling and logging. +- Use the existing `fetchWithRetry` utility for all GET requests. ``` +```markdown ## 关于依赖项： - 除非绝对必要，否则应避免引入新的外部依赖项。 @@ -510,30 +496,30 @@ CLI 会自动从 `.env` 文件中加载环境变量。加载顺序如下： ``` -这个示例展示了如何提供通用的项目背景、具体的编码规范，甚至关于特定文件或组件的说明。你的上下文文件越相关且精确，AI 就能更好地协助你。我们强烈建议为项目创建特定的上下文文件，以建立约定和上下文环境。 +这个示例展示了如何提供通用的项目背景、特定的编码规范，甚至关于特定文件或组件的说明。你的上下文文件越相关且精确，AI 就越能更好地协助你。我们强烈建议创建项目特定的上下文文件，以建立约定和上下文环境。 -- **分层加载与优先级：** 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 个目录，但可以通过在 `settings.json` 文件中设置 `memoryDiscoveryMaxDirs` 字段来调整。 - - 作用域：允许为项目中的特定组件、模块或子部分提供高度具体的指令。 + - 位置：CLI 还会在当前工作目录 _之下_ 的子目录中扫描配置的上下文文件（遵循如 `node_modules`、`.git` 等常见的忽略模式）。默认情况下，此搜索范围限制为 200 个目录，但可以通过在 `settings.json` 文件中设置 `memoryDiscoveryMaxDirs` 字段进行配置。 + - 范围：允许为项目中的特定组件、模块或子部分提供高度具体的指令。 - **拼接与 UI 提示：** 所有找到的上下文文件内容会被拼接在一起（使用分隔符标明其来源和路径），并作为系统提示的一部分提供给 AI。CLI 的页脚会显示已加载的上下文文件数量，让你快速了解当前激活的指令上下文。 -- **导入内容：** 你可以通过使用 `@path/to/file.md` 语法导入其他 Markdown 文件，从而模块化你的上下文文件。更多详情请参见 [Memory Import Processor 文档](../core/memport.md)。 +- **导入内容：** 你可以通过使用 `@path/to/file.md` 语法导入其他 Markdown 文件来模块化你的上下文文件。更多详情请参阅 [Memory Import Processor 文档](../core/memport.md)。 - **内存管理命令：** - 使用 `/memory refresh` 强制重新扫描并从所有配置的位置重新加载所有上下文文件。这将更新 AI 的指令上下文。 - 使用 `/memory show` 显示当前加载的组合指令上下文，方便你验证 AI 正在使用的层级结构和内容。 - - 有关 `/memory` 命令及其子命令（`show` 和 `refresh`）的完整详情，请参见 [Commands 文档](./commands.md#memory)。 + - 有关 `/memory` 命令及其子命令（`show` 和 `refresh`）的完整详情，请参阅 [Commands 文档](./commands.md#memory)。 通过理解并利用这些配置层级以及上下文文件的分层特性，你可以有效地管理 AI 的内存，并根据你的具体需求和项目定制 Qwen Code 的响应。 ## 沙箱机制 -Qwen Code 可以在一个沙箱环境中执行潜在的不安全操作（如 shell 命令和文件修改），以保护你的系统。 +Qwen Code 可以在沙箱环境中执行潜在的不安全操作（如 shell 命令和文件修改），以保护你的系统。 沙箱机制默认是关闭的，但你可以通过以下几种方式启用它： @@ -541,14 +527,14 @@ Qwen Code 可以在一个沙箱环境中执行潜在的不安全操作（如 she - 设置 `GEMI_SANDBOX` 环境变量。 - 当使用 `--yolo` 或 `--approval-mode=yolo` 时，沙箱机制会默认启用。 -默认情况下，它会使用一个预构建的 `qwen-code-sandbox` Docker 镜像。 +默认情况下，它会使用预构建的 `qwen-code-sandbox` Docker 镜像。 -如果你的项目有特定的沙箱需求，可以在项目根目录下创建一个 `.qwen/sandbox.Dockerfile` 文件来自定义 Dockerfile。这个 Dockerfile 可以基于基础沙箱镜像： +如果你的项目有特定的沙箱需求，可以在项目根目录下创建一个自定义的 Dockerfile，路径为 `.qwen/sandbox.Dockerfile`。这个 Dockerfile 可以基于基础沙箱镜像进行构建： ```dockerfile FROM qwen-code-sandbox -# 在这里添加你自定义的依赖或配置 +# 在这里添加你的自定义依赖或配置 # 例如： @@ -566,23 +552,23 @@ BUILD_SANDBOX=1 qwen -s ## 使用统计 -为了帮助我们改进 Qwen Code，我们会收集匿名化的使用统计数据。这些数据帮助我们了解 CLI 的使用情况，识别常见问题，并确定新功能的优先级。 +为了帮助我们改进 Qwen Code，我们会收集匿名化的使用统计数据。这些数据帮助我们了解 CLI 的使用情况、识别常见问题并优先开发新功能。 -**我们收集的数据包括：** +**我们会收集的数据：** - **工具调用：** 我们会记录被调用的工具名称、执行成功或失败的状态以及执行耗时。我们不会收集传递给工具的参数或工具返回的任何数据。 -- **API 请求：** 我们会记录每次请求所使用的模型、请求耗时以及请求是否成功。我们不会收集 prompt 或 response 的具体内容。 +- **API 请求：** 我们会记录每次请求使用的模型、请求耗时以及请求是否成功。我们不会收集 prompt 或 response 的内容。 - **会话信息：** 我们会收集 CLI 配置相关的信息，例如启用的工具和审批模式。 -**我们不会收集的数据包括：** +**我们不会收集的数据：** -- **个人身份信息 (PII)：** 我们不会收集任何个人信息，例如您的姓名、邮箱地址或 API key。 -- **Prompt 和 Response 内容：** 我们不会记录您提交的 prompt 或模型返回的 response 内容。 -- **文件内容：** 我们不会记录 CLI 读取或写入的任何文件的内容。 +- **个人身份信息 (PII)：** 我们不会收集任何个人信息，例如你的姓名、邮箱地址或 API key。 +- **Prompt 和 Response 内容：** 我们不会记录你的 prompt 内容或模型返回的 response 内容。 +- **文件内容：** 我们不会记录 CLI 读取或写入的任何文件内容。 **如何退出数据收集：** -您可以随时通过在 `settings.json` 文件中将 `usageStatisticsEnabled` 属性设置为 `false` 来退出使用统计收集： +你可以随时通过在 `settings.json` 文件中将 `usageStatisticsEnabled` 属性设置为 `false` 来退出使用统计收集： ```json { @@ -590,4 +576,12 @@ BUILD_SANDBOX=1 qwen -s } ``` -注意：当启用使用统计时，事件数据会被发送到阿里云 RUM 数据收集端点。 \ No newline at end of file +注意：当启用使用统计时，事件会被发送到阿里云 RUM 收集端点。 + +- **`enableWelcomeBack`** (boolean)： + - **说明：** 当返回到有对话历史的项目时，显示欢迎回来对话框。 + - **默认值：** `true` + - **分类：** UI + - **需要重启：** 否 + - **示例：** `"enableWelcomeBack": false` + - **详情：** 启用后，Qwen Code 会自动检测你是否返回到一个已有项目摘要（`.qwen/PROJECT_SUMMARY.md`）的项目，并显示一个对话框，允许你继续之前的对话或重新开始。此功能与 `/chat summary` 命令和退出确认对话框集成。更多详情请参见 [Welcome Back 文档](./welcome-back.md)。 \ No newline at end of file diff --git a/website/content/zh/cli/index.md b/website/content/zh/cli/index.md index 5c41a0df..beae3e9c 100644 --- a/website/content/zh/cli/index.md +++ b/website/content/zh/cli/index.md @@ -1,21 +1,22 @@ # Qwen Code CLI -在 Qwen Code 中，`packages/cli` 是用户与 Qwen 及其他 AI 模型及其相关工具进行交互的前端界面。关于 Qwen Code 的整体概述，请参见 [主文档页面](../index.md)。 +在 Qwen Code 中，`packages/cli` 是用户与 Qwen 及其他 AI 模型及其相关工具进行交互的前端界面。关于 Qwen Code 的整体介绍，请参见[主文档页面](../index.md)。 -## 本章节内容导航 +## 导航本节内容 -- **[认证](./authentication.md)：** 关于如何使用 Qwen OAuth 和兼容 OpenAI 的 provider 设置认证的指南。 -- **[命令](./commands.md)：** Qwen Code CLI 命令参考（例如 `/help`、`/tools`、`/theme`）。 -- **[配置](./configuration.md)：** 通过配置文件自定义 Qwen Code CLI 行为的指南。 -- **[Token 缓存](./token-caching.md)：** 通过 token 缓存优化 API 成本。 -- **[主题](./themes.md)：** 使用不同主题自定义 CLI 外观的指南。 -- **[教程](tutorials.md)：** 展示如何使用 Qwen Code 自动化开发任务的教程。 +- **[Authentication](./authentication.md):** 关于如何使用 Qwen OAuth 和兼容 OpenAI 的 providers 设置认证的指南。 +- **[Commands](./commands.md):** Qwen Code CLI 命令参考（例如 `/help`、`/tools`、`/theme`）。 +- **[Configuration](./configuration.md):** 通过配置文件自定义 Qwen Code CLI 行为的指南。 +- **[Token Caching](./token-caching.md):** 通过 token caching 优化 API 成本。 +- **[Themes](./themes.md)**: 自定义 CLI 外观主题的指南。 +- **[Tutorials](tutorials.md)**: 教程展示如何使用 Qwen Code 自动化开发任务。 +- **[Welcome Back](./welcome-back.md)**: 了解“Welcome Back”功能，帮助你在不同会话间无缝恢复工作。 ## 非交互模式 -Qwen Code 可以在非交互模式下运行，这对于脚本编写和自动化非常有用。在此模式下，你可以将输入通过管道传递给 CLI，它会执行命令，然后退出。 +Qwen Code 可以在非交互模式下运行，这对于脚本编写和自动化非常有用。在此模式下，你可以通过管道将输入传递给 CLI，它会执行命令然后退出。 -以下示例展示了如何从终端将命令通过管道传递给 Qwen Code： +以下示例展示了如何从终端通过管道将命令传递给 Qwen Code： ```bash echo "What is fine tuning?" | qwen diff --git a/website/content/zh/cli/token-caching.md b/website/content/zh/cli/token-caching.md index e2ee09a1..291d5e69 100644 --- a/website/content/zh/cli/token-caching.md +++ b/website/content/zh/cli/token-caching.md @@ -1,14 +1,14 @@ # Token 缓存与成本优化 -Qwen Code 在使用 API key 认证时（例如，与 OpenAI 兼容的提供商），会通过 token 缓存自动优化 API 成本。此功能可复用之前的系统指令和上下文，以减少后续请求中处理的 token 数量。 +Qwen Code 在使用 API key 认证时（例如，与 OpenAI 兼容的提供商），会通过 token 缓存自动优化 API 成本。该功能通过复用之前的系统指令和上下文，减少后续请求中处理的 token 数量。 **支持 token 缓存的用户类型：** -- API key 用户（Gemini API key） -- Vertex AI 用户（已配置 project 和 location） +- API key 用户（Qwen API key） +- Vertex AI 用户（已配置项目和区域） **不支持 token 缓存的用户类型：** - OAuth 用户（Google 个人/企业账户）——目前 Code Assist API 不支持创建缓存内容 -你可以通过 `/stats` 命令查看 token 使用情况和缓存节省的 token 数量。当有缓存的 token 可用时，它们会显示在 stats 输出中。 \ No newline at end of file +你可以通过 `/stats` 命令查看 token 使用情况和缓存节省的 token 数。当有缓存 token 可用时，它们会显示在统计输出中。 \ No newline at end of file diff --git a/website/content/zh/cli/welcome-back.md b/website/content/zh/cli/welcome-back.md new file mode 100644 index 00000000..4ab9fa0c --- /dev/null +++ b/website/content/zh/cli/welcome-back.md @@ -0,0 +1,134 @@ +# 欢迎回来功能 + +欢迎回来（Welcome Back）功能可帮助你无缝恢复工作，当检测到你返回到一个已有对话历史的项目时，它会自动弹出并提供从上次中断的地方继续工作的选项。 + +## 概述 + +当你在包含先前生成的项目摘要（`.qwen/PROJECT_SUMMARY.md`）的项目目录中启动 Qwen Code 时，欢迎回来对话框将自动出现，你可以选择重新开始或继续之前的对话。 + +## 工作原理 + +### 自动检测 + +欢迎回来功能会自动检测以下内容： + +- **项目摘要文件：** 在当前项目目录中查找 `.qwen/PROJECT_SUMMARY.md` +- **对话历史：** 检查是否存在可恢复的有意义对话历史 +- **设置：** 遵循你的 `enableWelcomeBack` 设置（默认启用） + +### 欢迎回来对话框 + +当找到项目摘要时，你会看到一个对话框，其中包含： + +- **最后更新时间：** 显示摘要上次生成的时间 +- **总体目标：** 显示你上一次会话中的主要目标 +- **当前计划：** 通过状态指示器显示任务进度： + - `[DONE]` - 已完成的任务 + - `[IN PROGRESS]` - 正在进行中的任务 + - `[TODO]` - 计划中的任务 +- **任务统计：** 总任务数、已完成、进行中和待处理任务的摘要 + +### 选项 + +当欢迎回来对话框出现时，你有两个选择： + +1. **开始新的聊天会话** + - 关闭对话框并开始新的对话 + - 不加载之前的上下文 + +2. **继续之前的对话** + - 自动在输入框中填充：`@.qwen/PROJECT_SUMMARY.md, Based on our previous conversation, Let's continue?` + - 将项目摘要作为上下文加载给 AI + - 让你可以无缝地从上次中断的地方继续 + +## 配置 + +### 启用/禁用 Welcome Back + +你可以通过设置来控制 Welcome Back 功能： + +**通过设置对话框：** + +1. 在 Qwen Code 中运行 `/settings` +2. 在 UI 分类中找到 "Enable Welcome Back" +3. 切换该设置的开启/关闭状态 + +**通过设置文件：** +在你的 `.qwen/settings.json` 中添加： + +```json +{ + "enableWelcomeBack": true +} +``` + +**设置位置：** + +- **用户设置：** `~/.qwen/settings.json`（影响所有项目） +- **项目设置：** `.qwen/settings.json`（仅当前项目生效） + +### 键盘快捷键 + +- **Escape：** 关闭 Welcome Back 对话框（默认选择"开始新的聊天会话"） + +## 与其他功能的集成 + +### 项目摘要生成 + +Welcome Back 功能与 `/chat summary` 命令无缝集成： + +1. **生成摘要**：使用 `/chat summary` 创建项目摘要 +2. **自动检测**：下次在此项目中启动 Qwen Code 时，Welcome Back 将自动检测到摘要 +3. **继续工作**：选择继续，摘要将作为上下文加载 + +### 退出确认 + +当使用 `/quit-confirm` 退出并选择 "Generate summary and quit" 时： + +1. 项目摘要会自动生成 +2. 下次会话将触发 Welcome Back 对话框 +3. 你可以无缝继续之前的工作 + +## 文件结构 + +Welcome Back 功能会创建并使用以下文件： + +``` +your-project/ +├── .qwen/ +│ └── PROJECT_SUMMARY.md # 生成的项目摘要 +``` + +### PROJECT_SUMMARY.md 格式 + +生成的摘要遵循以下结构： + +```markdown + +# Project Summary + +## Overall Goal + + +``` + +## 核心知识 + + + + +## 最近行动 + + + + +## 当前计划 + + + + +--- + +## 摘要元数据 + +**更新时间**：2025-01-10T15:30:00.000Z \ No newline at end of file diff --git a/website/content/zh/deployment.md b/website/content/zh/deployment.md index f9f27770..27daf96b 100644 --- a/website/content/zh/deployment.md +++ b/website/content/zh/deployment.md @@ -1,6 +1,6 @@ # Qwen Code 执行与部署 -本文档介绍如何运行 Qwen Code，并解释 Qwen Code 使用的部署架构。 +本文档介绍了如何运行 Qwen Code，并解释了 Qwen Code 使用的部署架构。 ## 运行 Qwen Code @@ -41,7 +41,7 @@ 你可以直接运行已发布的沙箱镜像。这在你只有 Docker 并希望运行 CLI 的环境中非常有用。 ```bash # 运行已发布的沙箱镜像 - docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.9 + docker run --rm -it ghcr.io/qwenlm/qwen-code:0.0.10 ``` - **使用 `--sandbox` 参数：** 如果你已经在本地安装了 Qwen Code（使用上述标准安装方式），你可以指示它在沙箱容器内运行。 @@ -86,7 +86,7 @@ npx https://github.com/QwenLM/qwen-code ## 部署架构 -上述执行方式的实现依赖于以下架构组件和流程： +上述执行方式依赖于以下架构组件和流程： **NPM 包** @@ -95,19 +95,19 @@ Qwen Code 项目是一个 monorepo，会将核心包发布到 NPM registry： - `@qwen-code/qwen-code-core`：后端部分，负责处理逻辑和工具执行。 - `@qwen-code/qwen-code`：面向用户的前端部分。 -在执行标准安装或从源码运行 Qwen Code 时，都会使用到这些包。 +在进行标准安装或从源码运行 Qwen Code 时，都会使用到这些包。 **构建与打包流程** -根据不同的分发渠道，会使用两种不同的构建流程： +根据不同的分发渠道，会采用两种不同的构建流程： -- **NPM 发布**：在发布到 NPM registry 时，`@qwen-code/qwen-code-core` 和 `@qwen-code/qwen-code` 中的 TypeScript 源码会通过 TypeScript Compiler（`tsc`）被转译为标准 JavaScript。最终生成的 `dist/` 目录会被发布为 NPM 包。这是 TypeScript 库的标准发布方式。 +- **NPM 发布：** 在发布到 NPM registry 时，`@qwen-code/qwen-code-core` 和 `@qwen-code/qwen-code` 中的 TypeScript 源码会通过 TypeScript Compiler（`tsc`）被编译为标准 JavaScript。最终生成的 `dist/` 目录会被发布为 NPM 包。这是 TypeScript 库的标准发布方式。 -- **GitHub `npx` 执行**：当直接从 GitHub 运行最新版本的 Qwen Code 时，`package.json` 中的 `prepare` 脚本会触发一个不同的构建流程。该脚本使用 `esbuild` 将整个应用及其依赖项打包成一个独立的 JavaScript 文件。这个 bundle 是在用户机器上即时生成的，并不会被提交到代码仓库中。 +- **GitHub `npx` 执行：** 当直接从 GitHub 运行最新版本的 Qwen Code 时，`package.json` 中的 `prepare` 脚本会触发另一个构建流程。该脚本使用 `esbuild` 将整个应用及其依赖项打包成一个独立的 JavaScript 文件。这个 bundle 是在用户机器上即时生成的，并不会被提交到代码仓库中。 **Docker 沙箱镜像** -基于 Docker 的执行方式由 `qwen-code-sandbox` 容器镜像提供支持。该镜像会被发布到容器镜像仓库中，并包含一个预装好的全局版本的 Qwen Code。 +基于 Docker 的执行方式由 `qwen-code-sandbox` 容器镜像支持。该镜像会被发布到容器镜像仓库，其中包含了预装的全局版本的 Qwen Code。 ## 发布流程 diff --git a/website/content/zh/ide-integration.md b/website/content/zh/ide-integration.md index 117dd4ae..e5369036 100644 --- a/website/content/zh/ide-integration.md +++ b/website/content/zh/ide-integration.md @@ -1,54 +1,54 @@ # IDE 集成 -Gemini CLI 可以与你的 IDE 集成，提供更无缝且具备上下文感知的体验。通过这种集成，CLI 能够更好地理解你的工作区，并启用强大的功能，例如编辑器内原生 diff 比对。 +Qwen Code 可以与你的 IDE 集成，提供更无缝且具备上下文感知的体验。通过这种集成，CLI 能够更好地理解你的工作区，并支持强大的功能，例如编辑器内的原生 diff 对比。 目前，唯一支持的 IDE 是 [Visual Studio Code](https://code.visualstudio.com/) 以及其他支持 VS Code 扩展的编辑器。 ## 功能特性 -- **Workspace 上下文感知：** CLI 会自动感知你的 workspace，从而提供更相关和准确的响应。该上下文包括： - - 你 workspace 中**最近访问的 10 个文件**。 +- **工作区上下文感知：** CLI 会自动感知你的工作区信息，从而提供更相关和准确的响应。上下文信息包括： + - 你工作区中**最近访问的 10 个文件**。 - 你当前的光标位置。 - 你选中的文本（最多 16KB，超出部分将被截断）。 -- **原生 Diff 支持：** 当 Gemini 建议代码修改时，你可以直接在 IDE 的原生 diff 查看器中查看变更。这样你可以无缝地审查、编辑并接受或拒绝建议的更改。 +- **原生 Diff 支持：** 当 Qwen 建议代码修改时，你可以在 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`：显示该扩展的第三方声明信息。 +- **VS Code 命令支持：** 你可以通过 VS Code 命令面板（`Cmd+Shift+P` 或 `Ctrl+Shift+P`）直接访问 Qwen Code 的功能： + - `Qwen Code: Run`：在集成终端中启动一个新的 Qwen Code 会话。 + - `Qwen Code: Accept Diff`：接受当前 diff 编辑器中的修改。 + - `Qwen Code: Close Diff Editor`：拒绝修改并关闭当前 diff 编辑器。 + - `Qwen Code: View Third-Party Notices`：显示该扩展的第三方声明信息。 -## 安装和设置 +## 安装与设置 有三种方式可以设置 IDE 集成： ### 1. 自动提示（推荐） -当你在支持的编辑器中运行 Gemini CLI 时，它会自动检测你的环境并提示你进行连接。回答 "Yes" 后将自动运行必要的设置，包括安装配套扩展和启用连接。 +当你在支持的编辑器中运行 Qwen Code 时，它会自动检测你的环境并提示你进行连接。选择 "Yes" 后，系统将自动运行必要的设置步骤，包括安装配套扩展并启用连接。 -### 2. 从 CLI 手动安装 +### 2. 通过 CLI 手动安装 -如果你之前关闭了提示框或想要手动安装扩展，可以在 Gemini CLI 中运行以下命令： +如果你之前关闭了提示，或者想手动安装扩展，可以在 Qwen Code 中运行以下命令： ``` /ide install ``` -这将找到适合你 IDE 的正确扩展并进行安装。 +该命令会自动找到适合你 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。 +- **对于 Visual Studio Code：** 从 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=qwenlm.qwen-code-vscode-ide-companion) 安装。 +- **对于 VS Code Forks：** 为了支持 VS Code 的 fork 版本，该 extension 也发布在 [Open VSX Registry](https://open-vsx.org/extension/qwenlm/qwen-code-vscode-ide-companion) 上。请根据你所使用编辑器的说明，从该 registry 安装 extension。 -使用任何安装方法后，建议打开一个新的 terminal 窗口以确保 integration 正确激活。安装完成后，你可以使用 `/ide enable` 来连接。 +无论使用哪种安装方式，安装完成后建议打开一个新的 terminal 窗口，以确保集成正确激活。安装完成后，你可以使用 `/ide enable` 来连接。 ### 启用和禁用 -你可以通过 CLI 来控制 IDE 集成： +你可以通过 CLI 控制 IDE 集成： - 要启用与 IDE 的连接，运行： ``` @@ -59,7 +59,7 @@ Gemini CLI 可以与你的 IDE 集成，提供更无缝且具备上下文感知 /ide disable ``` -启用后，Gemini CLI 会自动尝试连接到 IDE companion extension。 +启用后，Qwen Code 将自动尝试连接到 IDE companion 扩展。 ### 检查状态 @@ -69,50 +69,50 @@ Gemini CLI 可以与你的 IDE 集成，提供更无缝且具备上下文感知 /ide status ``` -如果已连接，该命令会显示所连接的 IDE 以及它感知到的最近打开的文件列表。 +如果已连接，该命令将显示所连接的 IDE 以及它感知到的最近打开的文件列表。 -（注意：文件列表仅限工作区中最近访问的 10 个文件，且只包含磁盘上的本地文件。） +（注意：文件列表仅限于工作区内最近访问的 10 个文件，且只包含磁盘上的本地文件。） ### 使用 Diff -当你要求 Gemini 修改文件时，它可以在你的编辑器中直接打开 diff 视图。 +当你请求 Gemini 修改文件时，它可以在你的编辑器中直接打开一个 diff 视图。 **要接受一个 diff**，你可以执行以下任意操作： -- 点击 diff 编辑器标题栏中的 **checkmark icon**。 +- 点击 diff 编辑器标题栏中的 **对勾图标**。 - 保存文件（例如使用 `Cmd+S` 或 `Ctrl+S`）。 -- 打开 Command Palette 并运行 **Gemini CLI: Accept Diff**。 -- 在 CLI 中提示时回复 `yes`。 +- 打开 Command Palette 并运行 **Qwen Code: Accept Diff**。 +- 在 CLI 提示时回复 `yes`。 **要拒绝一个 diff**，你可以： -- 点击 diff 编辑器标题栏中的 **'x' icon**。 +- 点击 diff 编辑器标题栏中的 **'x' 图标**。 - 关闭 diff 编辑器标签页。 -- 打开 Command Palette 并运行 **Gemini CLI: Close Diff Editor**。 -- 在 CLI 中提示时回复 `no`。 +- 打开 Command Palette 并运行 **Qwen Code: Close Diff Editor**。 +- 在 CLI 提示时回复 `no`。 -你也可以在接受之前**直接在 diff 视图中修改建议的更改**。 +你也可以在 **接受之前直接在 diff 视图中修改建议的更改**。 -如果你在 CLI 中选择 'Yes, allow always'，更改将不再在 IDE 中显示，因为它们会被自动接受。 +如果你在 CLI 中选择了 ‘Yes, allow always’，更改将不再在 IDE 中显示，因为它们会被自动接受。 -## 在沙盒环境中使用 +## 在沙箱环境中使用 -如果你在沙盒环境中使用 Gemini CLI，请注意以下事项： +如果你在沙箱环境中使用 Qwen Code，请注意以下事项： - **在 macOS 上：** IDE 集成需要网络访问权限来与 IDE companion 扩展通信。你必须使用允许网络访问的 Seatbelt 配置文件。 -- **在 Docker 容器中：** 如果你在 Docker（或 Podman）容器内运行 Gemini CLI，IDE 集成仍然可以连接到运行在宿主机上的 VS Code 扩展。CLI 已配置为自动在 `host.docker.internal` 上查找 IDE 服务器。通常不需要特殊配置，但你可能需要确保 Docker 网络设置允许从容器到宿主机的连接。 +- **在 Docker 容器中：** 如果你在 Docker（或 Podman）容器内运行 Qwen Code，IDE 集成仍然可以连接到运行在宿主机上的 VS Code 扩展。CLI 已配置为自动在 `host.docker.internal` 上查找 IDE 服务器。通常不需要特殊配置，但你可能需要确保 Docker 网络设置允许从容器到宿主机的连接。 ## 故障排除 -如果你遇到 IDE 集成问题，以下是一些常见错误信息及其解决方法。 +如果你遇到 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 扩展未运行或未正确初始化。 + - **原因：** Qwen Code 无法找到连接 IDE 所需的环境变量（`QWEN_CODE_IDE_WORKSPACE_PATH` 或 `QWEN_CODE_IDE_SERVER_PORT`）。这通常意味着 IDE companion 扩展未运行或未正确初始化。 - **解决方案：** - 1. 确保你已在 IDE 中安装并启用了 **Gemini CLI Companion** 扩展。 - 2. 在 IDE 中打开一个新的 terminal 窗口，以确保它能获取到正确的环境变量。 + 1. 确保你已在 IDE 中安装并启用了 **Qwen Code Companion** 扩展。 + 2. 在你的 IDE 中打开一个新的 terminal 窗口，以确保它能获取到正确的环境变量。 - **错误信息：** `🔴 Disconnected: IDE connection error. The connection was lost unexpectedly. Please try reconnecting by running /ide enable` - **原因：** 与 IDE companion 的连接意外中断。 @@ -120,20 +120,20 @@ Gemini CLI 可以与你的 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: Directory mismatch. Qwen Code is running in a different location than the open workspace in [IDE Name]. Please run the CLI from the same directory as your project's root folder.` + - **原因：** CLI 的当前工作目录不在你 IDE 中打开的文件夹或工作区中。 + - **解决方案：** 使用 `cd` 命令进入与你在 IDE 中打开的目录相同的路径，然后重新启动 CLI。 - **错误信息：** `🔴 Disconnected: To use this feature, please open a single workspace folder in [IDE Name] and try again.` - - **原因：** 你在 IDE 中打开了多个 workspace 文件夹，或者根本没有打开任何文件夹。IDE 集成需要一个单一的根 workspace 文件夹才能正常运行。 - - **解决方案：** 在 IDE 中打开单个项目文件夹，然后重新启动 CLI。 + - **原因：** 你在 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。 - - **解决方案：** 请在支持的 IDE（如 VS Code）的集成终端中运行 Gemini CLI。 +- **错误信息：** `IDE integration is not supported in your current environment. To use this feature, run Qwen Code in one of these supported IDEs: [List of IDEs]` + - **原因：** 你当前在 terminal 或者不支持的 IDE 环境中运行 Qwen Code。 + - **解决方案：** 请从受支持的 IDE（如 VS Code）的 integrated terminal 中运行 Qwen Code。 - **错误信息：** `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 + - **原因：** 你执行了 `/ide install`，但 CLI 没有为你使用的 IDE 提供自动安装程序。 + - **解决方案：** 打开你的 IDE 的 extension marketplace，搜索 "Qwen Code Companion"，然后手动安装。 \ No newline at end of file diff --git a/website/content/zh/index.md b/website/content/zh/index.md index 364c5060..5aff2ff0 100644 --- a/website/content/zh/index.md +++ b/website/content/zh/index.md @@ -1,6 +1,6 @@ # 欢迎阅读 Qwen Code 文档 -本文档提供了安装、使用和开发 Qwen Code 的全面指南。该工具允许你通过命令行界面与 AI 模型进行交互。 +本文档提供了安装、使用和开发 Qwen Code 的完整指南。该工具允许你通过命令行界面与 AI 模型进行交互。 ## 概述 @@ -8,21 +8,21 @@ Qwen Code 将先进的代码模型能力带入你的终端，提供交互式的 ## 浏览文档 -本文档组织如下： +本文档分为以下几个部分： -- **[执行与部署](./deployment.md)：** 运行 Qwen Code 的相关信息。 +- **[执行与部署](./deployment.md)：** 关于如何运行 Qwen Code 的信息。 - **[架构概览](./architecture.md)：** 了解 Qwen Code 的高层设计，包括其组件及交互方式。 - **CLI 使用：** `packages/cli` 的文档。 - **[CLI 简介](./cli/index.md)：** 命令行界面的概述。 - **[命令](./cli/commands.md)：** 可用 CLI 命令的说明。 - - **[配置](./cli/configuration.md)：** 配置 CLI 的相关信息。 - - **[检查点](./checkpointing.md)：** 检查点功能的文档。 + - **[配置](./cli/configuration.md)：** CLI 配置相关信息。 + - **[Checkpointing](./checkpointing.md)：** checkpointing 特性的文档。 - **[扩展](./extension.md)：** 如何通过新功能扩展 CLI。 - **[IDE 集成](./ide-integration.md)：** 将 CLI 与你的编辑器连接。 - **[遥测](./telemetry.md)：** CLI 中遥测功能的概述。 -- **核心详情：** `packages/core` 的文档。 +- **核心细节：** `packages/core` 的文档。 - **[核心简介](./core/index.md)：** 核心组件的概述。 - - **[工具 API](./core/tools-api.md)：** 核心如何管理和暴露工具的信息。 + - **[Tools API](./core/tools-api.md)：** 核心如何管理和暴露 tools 的信息。 - **工具：** - **[工具概览](./tools/index.md)：** 可用工具的概述。 - **[文件系统工具](./tools/file-system.md)：** `read_file` 和 `write_file` 工具的文档。 @@ -30,9 +30,10 @@ Qwen Code 将先进的代码模型能力带入你的终端，提供交互式的 - **[Shell 工具](./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` 工具的文档。 + - **[Memory 工具](./tools/memory.md)：** `save_memory` 工具的文档。 +- **[子代理](./subagents.md)：** 专注于特定任务的 AI 助手，提供全面的管理、配置和使用指导。 - **[贡献与开发指南](../CONTRIBUTING.md)：** 面向贡献者和开发者的相关信息，包括环境设置、构建、测试和编码规范。 -- **[NPM 工作区与发布](./npm.md)：** 项目包的管理与发布详情。 +- **[NPM Workspaces 与发布](./npm.md)：** 项目包的管理与发布详情。 - **[故障排除指南](./troubleshooting.md)：** 常见问题和 FAQ 的解决方案。 - **[服务条款与隐私声明](./tos-privacy.md)：** 适用于你使用 Qwen Code 的服务条款和隐私声明信息。 diff --git a/website/content/zh/keyboard-shortcuts.md b/website/content/zh/keyboard-shortcuts.md index a793bc15..d4c2e94f 100644 --- a/website/content/zh/keyboard-shortcuts.md +++ b/website/content/zh/keyboard-shortcuts.md @@ -5,41 +5,41 @@ ## 通用 | 快捷键 | 描述 | -| ------ | -------------------------------------------------------------------------------------------------------------- | -| `Esc` | 关闭对话框和建议。 | -| `Ctrl+C` | 退出应用程序。按两次确认。 | -| `Ctrl+D` | 如果输入为空则退出应用程序。按两次确认。 | -| `Ctrl+L` | 清屏。 | -| `Ctrl+O` | 切换调试控制台的显示。 | -| `Ctrl+S` | 允许长响应完整打印，禁用截断。使用终端的回滚功能查看完整输出。 | -| `Ctrl+T` | 切换工具描述的显示。 | -| `Ctrl+Y` | 切换所有工具调用的自动批准（YOLO 模式）。 | +| -------- | --------------------------------------------------------------------------------------------------------------------- | +| `Esc` | 关闭对话框和建议。 | +| `Ctrl+C` | 取消正在进行的请求并清除输入。按两次退出应用程序。 | +| `Ctrl+D` | 如果输入为空，则退出应用程序。按两次确认。 | +| `Ctrl+L` | 清屏。 | +| `Ctrl+O` | 切换调试控制台的显示。 | +| `Ctrl+S` | 允许长响应完整打印，禁用截断。使用终端的回滚功能查看完整输出。 | +| `Ctrl+T` | 切换工具描述的显示。 | +| `Ctrl+Y` | 切换所有工具调用的自动批准（YOLO 模式）。 | ## 输入提示 | 快捷键 | 描述 | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `!` | 当输入为空时，切换 shell 模式。 | -| `\`（行尾）+ `Enter` | 插入一个换行符。 | -| `Down Arrow` | 在输入历史记录中向下导航。 | +| `\`（行尾）+ `Enter` | 插入一个新行。 | +| `向下箭头` | 在输入历史记录中向下导航。 | | `Enter` | 提交当前 prompt。 | | `Meta+Delete` / `Ctrl+Delete` | 删除光标右侧的单词。 | | `Tab` | 如果存在自动补全建议，则补全当前建议。 | -| `Up Arrow` | 在输入历史记录中向上导航。 | +| `向上箭头` | 在输入历史记录中向上导航。 | | `Ctrl+A` / `Home` | 将光标移动到行首。 | -| `Ctrl+B` / `Left Arrow` | 将光标向左移动一个字符。 | +| `Ctrl+B` / `左箭头` | 将光标向左移动一个字符。 | | `Ctrl+C` | 清除输入 prompt。 | | `Ctrl+D` / `Delete` | 删除光标右侧的字符。 | | `Ctrl+E` / `End` | 将光标移动到行尾。 | -| `Ctrl+F` / `Right Arrow` | 将光标向右移动一个字符。 | +| `Ctrl+F` / `右箭头` | 将光标向右移动一个字符。 | | `Ctrl+H` / `Backspace` | 删除光标左侧的字符。 | | `Ctrl+K` | 删除从光标到行尾的内容。 | -| `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B` | 将光标向左移动一个单词。 | +| `Ctrl+左箭头` / `Meta+左箭头` / `Meta+B` | 将光标向左移动一个单词。 | | `Ctrl+N` | 在输入历史记录中向下导航。 | | `Ctrl+P` | 在输入历史记录中向上导航。 | -| `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F` | 将光标向右移动一个单词。 | +| `Ctrl+右箭头` / `Meta+右箭头` / `Meta+F` | 将光标向右移动一个单词。 | | `Ctrl+U` | 删除从光标到行首的内容。 | -| `Ctrl+V` | 粘贴剪贴板内容。如果剪贴板包含图像，将保存该图像并在 prompt 中插入对其的引用。 | +| `Ctrl+V` | 粘贴剪贴板内容。如果剪贴板包含图像，将保存该图像并在 prompt 中插入其引用。 | | `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace` | 删除光标左侧的单词。 | | `Ctrl+X` / `Meta+Enter` | 在外部编辑器中打开当前输入。 | @@ -54,9 +54,15 @@ ## Radio Button Select | 快捷键 | 描述 | -| ------------------ | ------------------------------------------------------------------------------------------------------------- | +| ------------------ | ------------------------------------------------------------------------------------------------------ | | `Down Arrow` / `j` | 向下移动选择。 | -| `Enter` | 确认选择。 | -| `Up Arrow` / `k` | 向上移动选择。 | -| `1-9` | 通过编号选择项目。 | -| (多位数字) | 对于编号大于 9 的项目，快速连续按下数字键来选择对应的项目。 | \ No newline at end of file +| `Enter` | 确认选择。 | +| `Up Arrow` / `k` | 向上移动选择。 | +| `1-9` | 通过编号选择项目。 | +| (多位数字) | 对于编号大于 9 的项目，快速连续按下数字键来选择对应的项目。 | + +## IDE 集成 + +| 快捷键 | 描述 | +| -------- | --------------------------------- | +| `Ctrl+G` | 查看从 IDE 接收到的上下文 CLI | \ No newline at end of file diff --git a/website/content/zh/npm.md b/website/content/zh/npm.md index 1fec4baf..60e81954 100644 --- a/website/content/zh/npm.md +++ b/website/content/zh/npm.md @@ -1,39 +1,39 @@ # Package Overview -这个 monorepo 包含两个主要的 packages：`@qwen-code/qwen-code` 和 `@qwen-code/qwen-code-core`。 +这个 monorepo 包含两个主要 package：`@qwen-code/qwen-code` 和 `@qwen-code/qwen-code-core`。 ## `@qwen-code/qwen-code` 这是 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` 运行，他们使用的都是这个单一的、自包含的可执行文件。 +当这个 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 包含了 CLI 的核心逻辑。它负责向配置的 providers 发起 API 请求、处理身份验证以及管理本地缓存。 -这个 package 没有被打包。发布时，它会作为一个标准的 Node.js package 进行发布，并带有自己的 dependencies。这使得它可以在其他项目中作为独立 package 使用（如果需要的话）。`dist` 文件夹中所有编译后的 js 代码都会包含在 package 中。 +这个 package 并未被打包。发布时，它会作为一个标准的 Node.js package 进行发布，并带有其自身的依赖项。这使得它可以在其他项目中作为独立 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 工作流进行管理。要手动发布一个 patch 或 hotfix 版本： -1. 进入 repository 的 **Actions** tab。 -2. 在列表中选择 **Release** workflow。 +1. 进入仓库的 **Actions** 标签页。 +2. 从列表中选择 **Release** 工作流。 3. 点击 **Run workflow** 下拉按钮。 -4. 填写必要的输入项： +4. 填写所需的输入项： - **Version**：要发布的具体版本号（例如 `v0.2.1`）。 - - **Ref**：要发布的目标 branch 或 commit SHA（默认为 `main`）。 - - **Dry Run**：保留为 `true` 可在不实际发布的情况下测试 workflow，设置为 `false` 则执行真实发布。 + - **Ref**：要发布的目标分支或 commit SHA（默认为 `main`）。 + - **Dry Run**：保留为 `true` 可在不实际发布的情况下测试工作流，设置为 `false` 则执行真实发布。 5. 点击 **Run workflow**。 ## Nightly 发布 -除了手动发布之外，该项目还具有自动化的 nightly 发布流程，用于提供最新的“前沿”版本以供测试和开发使用。 +除了手动发布之外，该项目还具有自动化的 nightly 发布流程，用于提供最新的“前沿”版本，供测试和开发使用。 ### 流程 @@ -42,13 +42,13 @@ 1. 检出 `main` 分支的最新代码。 2. 安装所有依赖项。 3. 运行完整的 `preflight` 检查和集成测试套件。 -4. 如果所有测试都通过，它会计算下一个 nightly 版本号（例如，`v0.2.1-nightly.20230101`）。 -5. 然后构建并将包发布到 npm，并使用 `nightly` dist-tag。 -6. 最后，它会为 nightly 版本创建一个 GitHub Release。 +4. 如果所有测试都通过，它会计算下一个 nightly 版本号（例如 `v0.2.1-nightly.20230101`）。 +5. 然后构建并将 packages 发布到 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,33 +58,33 @@ npm install -g @qwen-code/qwen-code@nightly ``` -我们还运行一个名为 [release-docker.yml](../.gcp/release-docker.yml) 的 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` 分支创建一个新的 pull request 到 `main` 分支。 +2. 从 `release/vX.Y.Z` 分支向 `main` 分支创建一个新的 pull request。 3. 审查该 pull request（应该只包含 `package.json` 文件中的版本更新），然后合并它。这样可以保持 `main` 分支中的版本为最新。 ## 发布验证 -推送新版本后，应进行冒烟测试以确保包按预期工作。可以通过本地安装包并运行一组测试来确保其功能正常。 +推送新版本后，应进行冒烟测试以确保包按预期工作。可以通过本地安装包并运行一组测试来验证其功能是否正常。 -- `npx -y @qwen-code/qwen-code@latest --version` 用于验证推送是否按预期工作（如果你不是在推送 rc 或 dev 标签） +- `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 命令和工具进行基本的运行测试，以冒烟测试包是否按预期工作。我们将在未来进一步规范化这一流程。 +- _这会在本地产生破坏性影响_：`npm uninstall @qwen-code/qwen-code && npm uninstall -g @qwen-code/qwen-code && npm cache clean --force && npm install @qwen-code/qwen-code@` +- 建议对几个 LLM 命令和工具进行基本的运行测试，以确保包按预期工作。我们未来会进一步规范这一流程。 ## 何时合并版本变更，何时不合并？ -从当前或较旧的 commit 创建 patch 或 hotfix 发布的上述模式会使 repository 处于以下状态： +上述从当前或较旧的 commit 创建 patch 或 hotfix 发布的模式会使 repository 处于以下状态： -1. Tag (`vX.Y.Z-patch.1`)：这个 tag 正确指向 main 分支上包含你打算发布的稳定代码的原始 commit。这一点至关重要。任何检出这个 tag 的人都能获得确切的发布代码。 +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 分支历史保持干净，不会包含发布特定的版本号提升，直到你决定合并它们。 +这种分离是很好的做法。它让你的 main 分支历史保持干净，不会包含发布特定的版本号提升，直到你决定要合并它们。 这是关键的决策点，完全取决于发布的性质。 @@ -92,15 +92,15 @@ 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 分支创建完成并且包成功发布后，你应该创建一个 pull request 将 release-v1.2.1 合并到 main 分支。这个 PR 只包含一个 commit：`"chore: bump version to v1.2.1"`。这是一个干净、简单的集成，能够保持你的 main 分支与最新发布的版本同步。 +- **流程：** 在 release-v1.2.1 分支创建完成并且 package 成功发布后，你应该创建一个 pull request 将 release-v1.2.1 合并到 main 分支。这个 PR 只会包含一个 commit：`"chore: bump version to v1.2.1"`。这是一个干净、简单的集成操作，能够保持你的 main 分支与最新发布的版本同步。 ### 预发布版本（RC、Beta、Dev）不要合并回主分支 通常情况下，你不应该将预发布版本的 release 分支合并回 `main` 分支。 -- 为什么？预发布版本（例如 v1.3.0-rc.1、v1.3.0-rc.2）本质上就是不稳定的临时版本。你不希望用一系列的 RC 版本号更新来污染 main 分支的历史记录。main 分支中的 package.json 应该反映最新的稳定版本，而不是 RC 版本。 +- 为什么？预发布版本（例如 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,7 +112,7 @@ 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 日志，确保一切按预期工作。 在提交任何对打包和发布流程的更改之前，在本地进行测试是至关重要的。这样可以确保包能被正确发布，并且用户安装后能按预期工作。 @@ -129,63 +129,63 @@ 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/qwen-code-0.1.6.tgz`）。 -通过执行 dry run，你可以确认对打包流程的修改是正确的，并确保包能成功发布。 +通过执行 dry run，你可以确认对打包流程的修改是正确的，并且包能够成功发布。 ## Release Deep Dive -发布流程的主要目标是从 `packages/` 目录中获取源代码，进行构建，并在项目根目录下的临时 `bundle` 文件夹中组装出一个干净、自包含的 package。这个 `bundle` 目录就是最终发布到 NPM 的内容。 +发布流程的主要目标是从 `packages/` 目录中获取源代码，进行构建，并在项目根目录下的临时 `bundle` 文件夹中组装一个干净、自包含的包。这个 `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 +### 阶段 3：组装最终可发布的包 -这是最关键的一个阶段，文件会被移动并转换为最终用于发布的状态。项目根目录会创建一个临时的 `bundle` 文件夹，用于存放最终 package 的内容。 +这是最关键的一个阶段，文件会被移动并转换为最终用于发布的状态。项目根目录会创建一个临时的 `bundle` 文件夹，用于存放最终的包内容。 -#### 1. `package.json` 被转换 +#### 1. 转换 `package.json` - **发生了什么**：读取 `packages/cli/package.json`，进行修改后写入项目根目录的 `bundle/` 文件夹中。 -- **文件移动**：`packages/cli/package.json` -> （内存中转换）-> `bundle/package.json` -- **为什么这样做**：最终的 `package.json` 必须与开发时使用的不同。关键变化包括： +- **文件移动**：`packages/cli/package.json` ->（内存中转换）-> `bundle/package.json` +- **为什么这么做**：最终的 `package.json` 必须与开发时使用的不同。关键变化包括： - 移除 `devDependencies`。 - - 移除 workspace 特定的依赖 `"dependencies": { "@gemini-cli/core": "workspace:*" }`，并确保 core 代码被直接打包进最终的 JavaScript 文件中。 - - 确保 `bin`、`main` 和 `files` 字段指向最终 package 结构中的正确位置。 + - 移除 workspace 特定的依赖项：`{ "@qwen-code/core": "workspace:*" }`，并确保 core 代码被直接打包进最终的 JavaScript 文件中。 + - 确保 `bin`、`main` 和 `files` 字段指向最终包结构中的正确位置。 #### 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`（或类似名称）。 -- **为什么这样做**：这样可以创建一个包含所有必要应用代码的单一优化文件。通过将 core 代码直接包含进来，避免了将其作为单独依赖发布到 NPM 的需要，从而简化了 package。 +- **文件移动**：`packages/cli/dist/index.js` + `packages/core/dist/index.js` ->（由 esbuild 打包）-> `bundle/gemini.js`（或类似名称）。 +- **为什么这么做**：这样可以创建一个包含所有必要应用代码的单一优化文件。它简化了包结构，不再需要将 core 包作为单独的 NPM 依赖项，因为其代码已直接包含在内。 #### 3. 复制静态和支持文件 -- **发生了什么**：将不属于源代码但对 package 正常运行或描述必要的文件复制到 `bundle` 目录中。 +- **发生了什么**：将不属于源代码但对包的正常运行或描述必要的文件复制到 `bundle` 目录中。 - **文件移动**： - `README.md` -> `bundle/README.md` - `LICENSE` -> `bundle/LICENSE` - - `packages/cli/src/utils/*.sb`（sandbox profiles）-> `bundle/` -- **为什么这样做**： - - `README.md` 和 `LICENSE` 是任何 NPM package 都应包含的标准文件。 - - sandbox profiles（.sb 文件）是 CLI 的沙箱功能运行所必需的关键运行时资源，必须与最终可执行文件位于同一目录下。 + - `packages/cli/src/utils/*.sb`（沙箱配置文件）-> `bundle/` +- **为什么这么做**： + - `README.md` 和 `LICENSE` 是任何 NPM 包都应包含的标准文件。 + - 沙箱配置文件（.sb 文件）是 CLI 沙箱功能运行所必需的关键运行时资源，必须与最终可执行文件位于同一目录下。 ### 阶段 4：发布到 NPM - **发生了什么**：在项目根目录的 `bundle` 文件夹中运行 `npm publish` 命令。 -- **为什么这样做**：通过在 `bundle` 目录中运行 `npm publish`，只有我们在阶段 3 中精心组装的文件会被上传到 NPM registry。这样可以防止源代码、测试文件或开发配置被意外发布，确保用户获得的是干净、最小化的 package。 +- **为什么这么做**：通过在 `bundle` 目录中运行 `npm publish`，只有我们在阶段 3 中精心组装的文件会被上传到 NPM registry。这可以防止源代码、测试文件或开发配置被意外发布，从而为用户提供一个干净、最小化的包。 ### 文件流转概览 @@ -223,15 +223,15 @@ graph TD J --> G --> K ``` -这个流程确保了最终发布的 artifact 是一个专为发布而构建的、干净且高效的项目表示，而不是开发工作区的直接拷贝。 +这个流程确保了最终发布的产物是一个专为发布而构建的、干净且高效的项目表示，而不是开发工作区的直接拷贝。 ## NPM Workspaces -本项目使用 [NPM Workspaces](https://docs.npmjs.com/cli/v10/using-npm/workspaces) 来管理 monorepo 中的各个 packages。这简化了开发流程，使我们能够从项目根目录统一管理依赖和运行多个 packages 的 scripts。 +本项目使用 [NPM Workspaces](https://docs.npmjs.com/cli/v10/using-npm/workspaces) 来管理 monorepo 中的各个 packages。这简化了开发流程，使我们能够从项目根目录统一管理依赖和运行多个 packages 中的 scripts。 ### 工作原理 -根目录的 `package.json` 文件定义了本项目的 workspaces： +根目录下的 `package.json` 文件定义了本项目的工作区： ```json { @@ -244,5 +244,5 @@ graph TD ### Workspaces 的优势 - **简化的依赖管理**：从项目根目录运行 `npm install` 将会为 workspace 中的所有包安装依赖并相互链接。这意味着你不需要在每个包的目录中分别运行 `npm install`。 -- **自动链接**：workspace 内的包可以相互依赖。当你运行 `npm install` 时，NPM 会自动在包之间创建 symlinks。这意味着当你修改一个包时，其他依赖它的包会立即获得这些更改。 -- **简化的脚本执行**：你可以使用 `--workspace` 标志从项目根目录运行任何包中的脚本。例如，要运行 `cli` 包中的 `build` 脚本，可以执行 `npm run build --workspace @google/gemini-cli`。 \ No newline at end of file +- **自动链接**：workspace 内的包可以相互依赖。当你运行 `npm install` 时，NPM 会自动在包之间创建符号链接（symlinks）。这意味着当你修改某个包时，依赖它的其他包可以立即使用到这些更改。 +- **简化的脚本执行**：你可以使用 `--workspace` 参数从项目根目录运行任意包中的脚本。例如，要在 `cli` 包中运行 `build` 脚本，可以执行 `npm run build --workspace @qwen-code/qwen-code`。 \ No newline at end of file diff --git a/website/content/zh/subagents.md b/website/content/zh/subagents.md new file mode 100644 index 00000000..ca283fd8 --- /dev/null +++ b/website/content/zh/subagents.md @@ -0,0 +1,466 @@ +# Subagents + +Subagents 是专门处理 Qwen Code 中特定类型任务的 AI 助手。它们允许你将专注的工作委派给配置了任务特定提示、工具和行为的 AI agents。 + +## 什么是 Subagents？ + +Subagents 是独立的 AI 助手，具备以下特点： + +- **专精特定任务** - 每个 subagent 都配置了专注于特定类型工作的 system prompt +- **独立上下文** - 它们维护自己的对话历史，与你的主聊天窗口分离 +- **受控工具访问** - 你可以配置每个 subagent 可以访问的工具 +- **自主工作** - 一旦分配任务，它们会独立工作直到完成或失败 +- **详细反馈** - 你可以实时查看它们的进度、工具使用情况和执行统计信息 + +## 核心优势 + +- **任务专业化**：创建针对特定工作流优化的 agents（测试、文档、重构等） +- **上下文隔离**：将专业工作与主对话分离 +- **可复用性**：保存并在项目和会话间复用 agent 配置 +- **访问控制**：限制每个 agent 可使用的工具，确保安全性和专注度 +- **进度可见性**：通过实时进度更新监控 agent 执行状态 + +## Subagents 工作原理 + +1. **配置**：创建 subagent 配置，定义其行为、工具和系统提示 +2. **委派**：主 AI 可自动将任务委派给合适的 subagents +3. **执行**：Subagents 独立工作，使用配置的工具完成任务 +4. **结果返回**：将结果和执行摘要返回到主对话中 + +## 快速开始 + +### 快速开始 + +1. **创建你的第一个 subagent**： + + ``` + /agents create + ``` + + 通过引导式向导创建一个专门的 agent。 + +2. **管理现有的 agents**： + + ``` + /agents manage + ``` + + 查看和管理你已配置的 subagents。 + +3. **自动使用 subagents**： + 只需让主 AI 执行与你的 subagents 专长相匹配的任务。AI 会自动将合适的工作委派出去。 + +### 使用示例 + +``` +User: "请为认证模块编写全面的测试" + +AI: 我将把这个任务委派给你的测试专家 subagent。 +[委派给 "testing-expert" subagent] +[显示测试创建的实时进度] +[返回完成的测试文件和执行摘要] +``` + +## 管理 + +### CLI 命令 + +Subagents 通过 `/agents` 斜杠命令及其子命令进行管理： + +#### `/agents create` + +通过引导式步骤向导创建一个新的 subagent。 + +**用法：** + +``` +/agents create +``` + +#### `/agents manage` + +打开一个交互式管理对话框，用于查看和管理现有的子 agent。 + +**使用方法：** + +``` +/agents manage +``` + +### 存储位置 + +子 agent 以 Markdown 文件形式存储在两个位置： + +- **项目级别**：`.qwen/agents/`（优先级更高） +- **用户级别**：`~/.qwen/agents/`（备选方案） + +这样你可以同时拥有项目特定的 agent 和跨项目使用的个人 agent。 + +### 文件格式 + +子 agent 使用带有 YAML frontmatter 的 Markdown 文件进行配置。这种格式易于阅读，且可以用任何文本编辑器轻松编辑。 + +#### 基本结构 + +```markdown +--- +name: agent-name +description: 简要描述该 agent 的使用场景和方式 +tools: tool1, tool2, tool3 # 可选 +--- + +System prompt 内容写在这里。 +支持多个段落。 +你可以使用 ${variable} 模板语法来实现动态内容。 +``` + +#### 使用示例 + +```markdown +--- +name: project-documenter +description: 创建项目文档和 README 文件 +--- + +你是 ${project_name} 项目的文档专家。 + +你的任务：${task_description} + +工作目录：${current_directory} +生成时间：${timestamp} + +专注于创建清晰、全面的文档，帮助新贡献者和最终用户理解项目。 +``` + +## 示例 + +### 开发工作流 Agents + +#### 测试专家 + +专为全面的测试创建和测试驱动开发而设计。 + +```markdown +--- +name: testing-expert +description: 编写全面的单元测试、集成测试，并使用最佳实践处理测试自动化 +tools: read_file, write_file, read_many_files, run_shell_command +--- + +你是一位专注于创建高质量、可维护测试的测试专家。 + +你的专业技能包括： + +- 使用适当的 mocking 和隔离进行单元测试 +- 针对组件交互的集成测试 +- 测试驱动开发实践 +- 边缘情况识别和全面覆盖 +- 在适当时进行性能和负载测试 + +对于每个测试任务： + +1. 分析代码结构和依赖关系 +2. 识别关键功能、边缘情况和错误条件 +3. 创建具有描述性名称的全面测试套件 +4. 包含适当的 setup/teardown 和有意义的断言 +5. 添加注释解释复杂的测试场景 +6. 确保测试具有可维护性并遵循 DRY 原则 + +始终遵循所检测语言和框架的测试最佳实践。 +关注正面和负面测试用例。 +``` + +**使用场景：** + +- "为认证服务编写单元测试" +- "为支付处理工作流创建集成测试" +- "为数据验证模块中的边缘情况添加测试覆盖" + +#### Documentation Writer + +专门负责创建清晰、全面的文档。 + +```markdown +--- +name: documentation-writer +description: 创建全面的文档，包括 README 文件、API 文档和用户指南 +tools: read_file, write_file, read_many_files, web_search +--- + +你是 ${project_name} 的技术文档专家。 + +你的职责是创建清晰、全面的文档，服务于开发者和最终用户。重点关注： + +**API 文档方面：** + +- 清晰的 endpoint 描述及示例 +- 参数详情（包括类型和约束） +- 响应格式说明 +- 错误码解释 +- 认证要求 + +**用户文档方面：** + +- 带截图的逐步操作指南（适当情况下） +- 安装与设置指南 +- 配置选项及示例 +- 常见问题的故障排查章节 +- 基于常见用户问题的 FAQ 部分 + +**开发者文档方面：** + +- 架构概览和设计决策 +- 可实际运行的代码示例 +- 贡献指南 +- 开发环境搭建说明 + +始终验证代码示例，并确保文档内容与实际实现保持同步。使用清晰的标题、项目符号和示例。 +``` + +**使用场景：** + +- "为用户管理 endpoints 创建 API 文档" +- "为该项目编写一份全面的 README" +- "记录部署流程并包含故障排查步骤" + +#### Code Reviewer + +专注于代码质量、安全性和最佳实践。 + +```markdown +--- +name: code-reviewer +description: Reviews code for best practices, security issues, performance, and maintainability +tools: read_file, read_many_files +--- + +你是一位专注于质量、安全性和可维护性的资深代码审查员。 + +审查标准： + +- **代码结构**：组织结构、模块化和关注点分离 +- **性能**：算法效率和资源使用情况 +- **安全性**：漏洞评估和安全编码实践 +- **最佳实践**：特定语言/框架的编码规范 +- **错误处理**：正确的异常处理和边界情况覆盖 +- **可读性**：清晰的命名、注释和代码组织 +- **测试**：测试覆盖率和可测试性考虑 + +提供建设性反馈，包括： + +1. **严重问题**：安全漏洞、重大 bug +2. **重要改进**：性能问题、设计缺陷 +3. **次要建议**：风格改进、重构机会 +4. **正面反馈**：实现良好的模式和优秀实践 + +专注于可操作的反馈，提供具体示例和建议解决方案。 +根据影响程度对问题进行优先级排序，并为建议提供理由。 +``` + +**使用场景：** + +- "审查这个认证实现是否存在安全问题" +- "检查这个数据库查询逻辑的性能影响" +- "评估代码结构并提出改进建议" + +### 技术特定 Agents + +#### React 专家 + +专为 React 开发、hooks 和组件模式优化。 + +```markdown +--- +name: react-specialist +description: 精通 React 开发、hooks、组件模式和现代 React 最佳实践 +tools: read_file, write_file, read_many_files, run_shell_command +--- + +你是一位在现代 React 开发方面有深厚专业知识的 React 专家。 + +你的专业领域包括： + +- **组件设计**：函数组件、自定义 hooks、组合模式 +- **状态管理**：useState、useReducer、Context API 以及外部库 +- **性能优化**：React.memo、useMemo、useCallback、代码分割 +- **测试**：React Testing Library、Jest、组件测试策略 +- **TypeScript 集成**：props、hooks 和组件的正确类型定义 +- **现代模式**：Suspense、Error Boundaries、Concurrent Features + +处理 React 任务时： + +1. 默认使用函数组件和 hooks +2. 实现正确的 TypeScript 类型定义 +3. 遵循 React 最佳实践和约定 +4. 考虑性能影响 +5. 包含适当的错误处理 +6. 编写可测试、可维护的代码 + +始终保持对 React 最佳实践的跟进，避免使用已弃用的模式。 +关注无障碍性和用户体验考虑。 +``` + +**使用场景：** + +- "创建一个支持排序和过滤的可复用数据表格组件" +- "实现一个带缓存功能的自定义 hook 用于 API 数据获取" +- "将这个 class 组件重构为使用现代 React 模式" + +#### Python 专家 + +专注于 Python 开发、框架和最佳实践。 + +```markdown +--- +name: python-expert +description: 精通 Python 开发、框架、测试以及 Python 特有的最佳实践 +tools: read_file, write_file, read_many_files, run_shell_command +--- + +你是一位对 Python 生态系统有深入了解的 Python 专家。 + +你的专长包括： + +- **核心 Python**：Pythonic 模式、数据结构、算法 +- **框架**：Django、Flask、FastAPI、SQLAlchemy +- **测试**：pytest、unittest、mocking、测试驱动开发（TDD） +- **数据科学**：pandas、numpy、matplotlib、jupyter notebooks +- **异步编程**：asyncio、async/await 模式 +- **包管理**：pip、poetry、虚拟环境 +- **代码质量**：PEP 8、类型提示、使用 pylint/flake8 进行 linting + +处理 Python 任务时： + +1. 遵循 PEP 8 编码规范 +2. 使用类型提示提升代码可读性 +3. 使用具体异常实现完善的错误处理机制 +4. 编写完整的 docstring +5. 考虑性能与内存使用情况 +6. 添加适当的日志记录 +7. 编写模块化、易于测试的代码 + +专注于编写符合社区标准的清晰、可维护的 Python 代码。 +``` + +**使用场景示例：** + +- “创建一个基于 FastAPI 的用户认证服务，支持 JWT token” +- “用 pandas 实现一个具备错误处理能力的数据处理流水线” +- “使用 argparse 开发一个 CLI 工具，并提供完整的帮助文档” + +## 最佳实践 + +### 设计原则 + +#### 单一职责原则 + +每个 subagent 应该有明确、专注的用途。 + +**✅ 推荐：** + +```markdown +--- +name: testing-expert +description: Writes comprehensive unit tests and integration tests +--- +``` + +**❌ 避免：** + +```markdown +--- +name: general-helper +description: Helps with testing, documentation, code review, and deployment +--- +``` + +**原因：** 专注的 agents 能产生更好的结果，也更容易维护。 + +#### 明确的专业化 + +定义具体的专业领域，而不是宽泛的能力。 + +**✅ 推荐：** + +```markdown +--- +name: react-performance-optimizer +description: Optimizes React applications for performance using profiling and best practices +--- +``` + +**❌ 避免：** + +```markdown +--- +name: frontend-developer +description: Works on frontend development tasks +--- +``` + +**原因：** 具体的专业知识能带来更有针对性和更有效的帮助。 + +#### 可操作的描述 + +编写能够清楚说明何时使用该 agent 的描述。 + +**✅ 推荐：** + +```markdown +description: 检查代码中的安全漏洞、性能问题和可维护性问题 +``` + +**❌ 避免：** + +```markdown +description: 一个有用的代码审查员 +``` + +**原因：** 清晰的描述有助于主 AI 为每个任务选择正确的 agent。 + +### 配置最佳实践 + +#### 系统提示指南 + +**明确专业领域：** + +```markdown +你是一位 Python 测试专家，专长包括： + +- pytest 框架和 fixtures +- Mock 对象和依赖注入 +- 测试驱动开发（TDD）实践 +- 使用 pytest-benchmark 进行性能测试 +``` + +**包含逐步操作方法：** + +```markdown +对于每个测试任务： + +1. 分析代码结构和依赖关系 +2. 识别核心功能和边界情况 +3. 创建全面的测试套件，并使用清晰的命名 +4. 包含 setup/teardown 和正确的断言 +5. 添加注释解释复杂的测试场景 +``` + +**指定输出标准：** + +```markdown +始终遵循以下标准： + +- 使用描述性的 test 名称，能够说明测试场景 +- 包含正向和负向测试用例 +- 为复杂的测试函数添加 docstrings +- 确保测试之间相互独立，可以按任意顺序运行 +``` + +## 安全注意事项 + +- **工具限制**：Subagents 只能访问其配置的工具 +- **沙箱机制**：所有工具执行都遵循与直接使用工具相同的安全模型 +- **审计追踪**：所有 subagent 操作都会被记录，并实时可见 +- **访问控制**：项目和用户级别的隔离提供了适当的边界 +- **敏感信息**：避免在 agent 配置中包含 secrets 或 credentials +- **生产环境**：考虑为生产环境和开发环境使用不同的 agents \ No newline at end of file diff --git a/website/content/zh/telemetry.md b/website/content/zh/telemetry.md index 31f61b72..0ebc8bd9 100644 --- a/website/content/zh/telemetry.md +++ b/website/content/zh/telemetry.md @@ -1,6 +1,6 @@ # Qwen Code 可观测性指南 -遥测（Telemetry）提供了有关 Qwen Code 性能、健康状况和使用情况的数据。通过启用遥测功能，你可以通过 traces、metrics 和结构化日志来监控操作、调试问题并优化工具使用。 +遥测（Telemetry）提供有关 Qwen Code 性能、健康状况和使用情况的数据。通过启用遥测功能，你可以通过 traces、metrics 和结构化日志来监控运行状态、调试问题并优化工具使用。 Qwen Code 的遥测系统基于 **[OpenTelemetry] (OTEL)** 标准构建，允许你将数据发送到任何兼容的后端。 @@ -26,7 +26,7 @@ Qwen Code 的遥测系统基于 **[OpenTelemetry] (OTEL)** 标准构建，允许 1. **工作区设置文件（`.qwen/settings.json`）：** 该 project-specific 文件中 `telemetry` 对象的值。 -1. **用户设置文件（`~/.qwen/settings.json`）：** 该全局用户文件中 `telemetry` 对象的值。 +1. **用户设置文件（`~/.qwen/settings.json`）：** 该 global user 文件中 `telemetry` 对象的值。 1. **默认值：** 如果以上均未设置，则应用以下默认值。 - `telemetry.enabled`: `false` @@ -35,11 +35,11 @@ Qwen Code 的遥测系统基于 **[OpenTelemetry] (OTEL)** 标准构建，允许 - `telemetry.logPrompts`: `true` **对于 `npm run telemetry -- --target=` 脚本：** -该脚本的 `--target` 参数**仅**在该脚本执行期间和目的范围内覆盖 `telemetry.target`（即，选择启动哪个 collector）。它不会永久更改你的 `settings.json`。脚本会首先查看 `settings.json` 中的 `telemetry.target` 作为默认值。 +该脚本的 `--target` 参数**仅**在该脚本执行期间和目的范围内覆盖 `telemetry.target`（即选择启动哪个 collector）。它不会永久更改你的 `settings.json`。脚本会首先查看 `settings.json` 中的 `telemetry.target` 作为默认值。 ### 示例配置 -你可以将以下代码添加到你的工作区 (`.qwen/settings.json`) 或用户 (`~/.qwen/settings.json`) 配置文件中，以启用遥测功能并将数据发送到 Google Cloud： +你可以将以下代码添加到你的工作区配置文件 (`.qwen/settings.json`) 或用户配置文件 (`~/.qwen/settings.json`) 中，以启用遥测功能并将数据发送到 Google Cloud： ```json { @@ -53,18 +53,18 @@ Qwen Code 的遥测系统基于 **[OpenTelemetry] (OTEL)** 标准构建，允许 ### 导出到文件 -你可以将所有遥测数据导出到一个文件中，以便在本地进行检查。 +你可以将所有遥测数据导出到一个文件中，方便在本地查看。 -要启用文件导出功能，请使用 `--telemetry-outfile` 参数，并指定你希望输出的文件路径。此操作必须配合 `--telemetry-target=local` 一起运行。 +要启用文件导出功能，请使用 `--telemetry-outfile` 参数，并指定你希望输出的文件路径。此功能必须配合 `--telemetry-target=local` 一起使用。 ```bash -# 设置你期望的输出文件路径 +# 设置你希望输出的文件路径 TELEMETRY_FILE=".qwen/telemetry.log" -# 使用本地遥测配置运行 Qwen Code +# 使用本地遥测功能运行 Qwen Code -# 注意：--telemetry-otlp-endpoint="" 是必需的，用于覆盖默认的 +# 注意：必须设置 --telemetry-otlp-endpoint="" 来覆盖默认的 # OTLP 导出器，确保遥测数据写入本地文件。 qwen --telemetry \ @@ -77,7 +77,10 @@ qwen --telemetry \ ## 运行 OTEL Collector OTEL Collector 是一个接收、处理和导出遥测数据的服务。 -CLI 使用 OTLP/gRPC 协议发送数据。 +CLI 可以使用 OTLP/gRPC 或 OTLP/HTTP 协议发送数据。 +你可以通过 `--telemetry-otlp-protocol` flag +或 `settings.json` 文件中的 `telemetry.otlpProtocol` 设置来指定使用哪种协议。更多 +详情请参见 [配置文档](./cli/configuration.md#--telemetry-otlp-protocol)。 在 [documentation][otel-config-docs] 中了解更多关于 OTEL exporter 标准配置的信息。 @@ -85,21 +88,21 @@ CLI 使用 OTLP/gRPC 协议发送数据。 ### 本地部署 -使用 `npm run telemetry -- --target=local` 命令可以自动化设置本地 telemetry pipeline，包括在你的 `.qwen/settings.json` 文件中配置必要的设置。该脚本会自动安装 `otelcol-contrib`（即 OpenTelemetry Collector）和 `jaeger`（用于查看 traces 的 Jaeger UI）。使用方式如下： +使用 `npm run telemetry -- --target=local` 命令可以自动化设置本地 telemetry pipeline，包括在你的 `.qwen/settings.json` 文件中配置必要的设置。底层脚本会安装 `otelcol-contrib`（OpenTelemetry Collector）和 `jaeger`（用于查看 traces 的 Jaeger UI）。使用方式如下： 1. **运行命令**： - 在项目根目录下执行以下命令： + 在 repository 根目录下执行以下命令： ```bash npm run telemetry -- --target=local ``` 脚本将会： - - 如果需要，下载 Jaeger 和 OTEL。 - - 启动一个本地的 Jaeger 实例。 + - 如有需要，下载 Jaeger 和 OTEL。 + - 启动一个本地 Jaeger 实例。 - 启动一个配置好的 OTEL collector，用于接收来自 Qwen Code 的数据。 - 自动在你的 workspace settings 中启用 telemetry。 - - 在退出时自动禁用 telemetry。 + - 退出时，自动禁用 telemetry。 1. **查看 traces**： 打开浏览器并访问 **http://localhost:16686** 进入 Jaeger UI，在这里你可以查看 Qwen Code 操作的详细 traces。 @@ -112,16 +115,16 @@ CLI 使用 OTLP/gRPC 协议发送数据。 ### Google Cloud -使用 `npm run telemetry -- --target=gcp` 命令可以自动设置一个本地 OpenTelemetry collector，将数据转发到你的 Google Cloud 项目，并自动配置 `.qwen/settings.json` 文件中的必要设置。该脚本会安装 `otelcol-contrib`。使用步骤如下： +使用 `npm run telemetry -- --target=gcp` 命令可以自动化设置一个本地 OpenTelemetry collector，将数据转发到你的 Google Cloud 项目，并自动配置 `.qwen/settings.json` 文件中的必要设置。该脚本底层会安装 `otelcol-contrib`。使用步骤如下： -1. **前提条件**： +1. **前置条件**： - 拥有一个 Google Cloud 项目 ID。 - 导出 `GOOGLE_CLOUD_PROJECT` 环境变量，以便 OTEL collector 可以读取。 ```bash export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id" ``` - 完成 Google Cloud 身份验证（例如运行 `gcloud auth application-default login`，或确保已设置 `GOOGLE_APPLICATION_CREDENTIALS`）。 - - 确保你的 Google Cloud 账号或 service account 拥有以下 IAM 角色："Cloud Trace Agent"、"Monitoring Metric Writer" 和 "Logs Writer"。 + - 确保你的 Google Cloud 账户或服务账户拥有以下 IAM 角色："Cloud Trace Agent"、"Monitoring Metric Writer" 和 "Logs Writer"。 1. **运行命令**： 在项目根目录下执行以下命令： @@ -130,12 +133,12 @@ CLI 使用 OTLP/gRPC 协议发送数据。 npm run telemetry -- --target=gcp ``` - 脚本将执行以下操作： + 脚本将会： - 如果需要，下载 `otelcol-contrib` 二进制文件。 - - 启动一个 OTEL collector，用于接收来自 Qwen Code 的数据并导出到你指定的 Google Cloud 项目。 - - 自动在你的 workspace settings（`.qwen/settings.json`）中启用 telemetry 并关闭 sandbox 模式。 + - 启动一个 OTEL collector，配置为接收来自 Qwen Code 的数据并导出到你指定的 Google Cloud 项目。 + - 自动在你的工作区设置（`.qwen/settings.json`）中启用 telemetry 并关闭 sandbox 模式。 - 提供直接链接，用于在 Google Cloud Console 中查看 traces、metrics 和 logs。 - - 当你退出（Ctrl+C）时，脚本会尝试恢复你原来的 telemetry 和 sandbox 设置。 + - 在退出时（Ctrl+C），尝试恢复你原来的 telemetry 和 sandbox 设置。 1. **运行 Qwen Code**： 在另一个终端中运行你的 Qwen Code 命令。这将生成 telemetry 数据，由 collector 捕获。 @@ -144,10 +147,10 @@ CLI 使用 OTLP/gRPC 协议发送数据。 使用脚本提供的链接跳转到 Google Cloud Console，查看你的 traces、metrics 和 logs。 1. **查看本地 collector 日志**： - 脚本将本地 OTEL collector 的输出重定向到 `~/.qwen/tmp//otel/collector-gcp.log`。脚本同时提供查看和实时跟踪 collector 日志的链接和命令。 + 脚本将本地 OTEL collector 的输出重定向到 `~/.qwen/tmp//otel/collector-gcp.log`。脚本还会提供链接和命令，方便你在本地查看或 tail collector 日志。 1. **停止服务**： - 在脚本运行的终端中按 `Ctrl+C`，即可停止 OTEL Collector。 + 在脚本运行的终端中按下 `Ctrl+C`，即可停止 OTEL Collector。 ## 日志和指标参考 @@ -177,7 +180,7 @@ CLI 使用 OTLP/gRPC 协议发送数据。 - `qwen-code.user_prompt`：该事件在用户提交 prompt 时发生。 - **属性**： - `prompt_length` - - `prompt`（如果 `log_prompts_enabled` 配置为 `false`，则不包含此属性） + - `prompt`（如果 `log_prompts_enabled` 配置为 `false`，则该属性会被排除） - `auth_type` - `qwen-code.tool_call`：该事件在每次函数调用时发生。 @@ -191,7 +194,7 @@ CLI 使用 OTLP/gRPC 协议发送数据。 - `error_type`（如适用） - `metadata`（如适用，string -> any 的字典） -- `qwen-code.api_request`：该事件在向 Gemini API 发起请求时发生。 +- `qwen-code.api_request`：该事件在向 Qwen API 发起请求时发生。 - **属性**： - `model` - `request_text`（如适用） @@ -205,7 +208,7 @@ CLI 使用 OTLP/gRPC 协议发送数据。 - `duration_ms` - `auth_type` -- `qwen-code.api_response`：该事件在接收到 Gemini API 响应时发生。 +- `qwen-code.api_response`：该事件在收到 Qwen API 响应时发生。 - **属性**： - `model` - `status_code` @@ -238,18 +241,19 @@ Metrics 是对行为随时间变化的数值测量。Qwen Code 收集以下指 - **Attributes**： - `function_name` - `success` (boolean) - - `decision` (string: "accept", "reject", 或 "modify"，如适用) + - `decision` (string: "accept", "reject", 或 "modify"，如果适用) + - `tool_type` (string: "mcp", 或 "native"，如果适用) - `qwen-code.tool.call.latency` (Histogram, ms)：测量工具调用延迟。 - **Attributes**： - `function_name` - - `decision` (string: "accept", "reject", 或 "modify"，如适用) + - `decision` (string: "accept", "reject", 或 "modify"，如果适用) - `qwen-code.api.request.count` (Counter, Int)：统计所有 API 请求次数。 - **Attributes**： - `model` - `status_code` - - `error_type` (如适用) + - `error_type` (如果适用) - `qwen-code.api.request.latency` (Histogram, ms)：测量 API 请求延迟。 - **Attributes**： @@ -263,10 +267,15 @@ Metrics 是对行为随时间变化的数值测量。Qwen Code 收集以下指 - `qwen-code.file.operation.count` (Counter, Int)：统计文件操作次数。 - **Attributes**： - `operation` (string: "create", "read", "update")：文件操作类型。 - - `lines` (Int, 如适用)：文件中的行数。 - - `mimetype` (string, 如适用)：文件的 MIME 类型。 - - `extension` (string, 如适用)：文件扩展名。 - - `ai_added_lines` (Int, 如适用)：AI 添加/修改的行数。 - - `ai_removed_lines` (Int, 如适用)：AI 删除/修改的行数。 - - `user_added_lines` (Int, 如适用)：用户在 AI 提议的更改中添加/修改的行数。 - - `user_removed_lines` (Int, 如适用)：用户在 AI 提议的更改中删除/修改的行数。 \ No newline at end of file + - `lines` (Int, 如果适用)：文件中的行数。 + - `mimetype` (string, 如果适用)：文件的 MIME 类型。 + - `extension` (string, 如果适用)：文件扩展名。 + - `ai_added_lines` (Int, 如果适用)：AI 添加/修改的行数。 + - `ai_removed_lines` (Int, 如果适用)：AI 删除/修改的行数。 + - `user_added_lines` (Int, 如果适用)：用户在 AI 提议的更改中添加/修改的行数。 + - `user_removed_lines` (Int, 如果适用)：用户在 AI 提议的更改中删除/修改的行数。 + +- `qwen-code.chat_compression` (Counter, Int)：统计聊天压缩操作次数。 + - **Attributes**： + - `tokens_before` (Int)：压缩前上下文中的 token 数量。 + - `tokens_after` (Int)：压缩后上下文中的 token 数量。 \ No newline at end of file diff --git a/website/content/zh/tools/file-system.md b/website/content/zh/tools/file-system.md index 6439022b..7e686ed8 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) @@ -24,24 +24,24 @@ Qwen Code 提供了一套全面的工具，用于与本地文件系统进行交 ## 2. `read_file` (ReadFile) -`read_file` 用于读取并返回指定文件的内容。该工具支持处理文本文件、图像文件（PNG、JPG、GIF、WEBP、SVG、BMP）以及 PDF 文件。对于文本文件，可以读取特定的行范围。其他二进制文件类型通常会被跳过。 +`read_file` 用于读取并返回指定文件的内容。该工具支持处理文本文件、图像文件（PNG、JPG、GIF、WEBP、SVG、BMP）以及 PDF 文件。对于文本文件，可以读取特定的行范围；其他二进制文件类型通常会被跳过。 - **Tool name:** `read_file` - **Display name:** ReadFile - **File:** `read-file.ts` -- **Parameters:** - - `path` (string, required): 要读取的文件的绝对路径。 - - `offset` (number, optional): 对于文本文件，表示从第几行开始读取（从 0 开始计数）。需要配合 `limit` 使用。 - - `limit` (number, optional): 对于文本文件，表示最多读取多少行。如果未设置，则默认读取最大行数（例如 2000 行），或者在可行的情况下读取整个文件。 -- **Behavior:** - - 对于文本文件：返回文件内容。如果使用了 `offset` 和 `limit`，则只返回对应范围的行内容。如果因行数限制或单行长度限制导致内容被截断，会进行提示。 +- **参数：** + - `path` (string, 必填): 要读取文件的绝对路径。 + - `offset` (number, 可选): 对于文本文件，表示从第几行开始读取（从 0 开始计数）。需要配合 `limit` 使用。 + - `limit` (number, 可选): 对于文本文件，表示最多读取多少行。如果未设置，则默认读取最大行数（例如 2000 行），或者在可行的情况下读取整个文件。 +- **行为说明：** + - 对于文本文件：返回文件内容。如果设置了 `offset` 和 `limit`，则只返回对应范围的行内容。如果因行数或单行长度限制导致内容被截断，会进行提示。 - 对于图像和 PDF 文件：以 base64 编码的数据结构返回文件内容，适用于模型处理。 - - 对于其他二进制文件：尝试识别并跳过，返回提示信息说明这是一个通用二进制文件。 -- **Output:** (`llmContent`): + - 对于其他二进制文件：尝试识别并跳过这些文件，返回一条消息说明这是一个通用二进制文件。 +- **输出格式：** (`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` 的提示信息。 -- **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) @@ -85,16 +85,16 @@ Qwen Code 提供了一套全面的工具，用于与本地文件系统进行交 - **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}"`）。如果省略，则搜索大多数文件（遵循常见的忽略规则）。 - - `maxResults` (number, optional): 返回的最大匹配数量，防止上下文溢出（默认值：20，最大值：100）。对于广泛搜索使用较低值，对于精确搜索使用较高值。 -- **Behavior:** - - 如果在 Git 仓库中可用，则使用 `git grep` 以提高速度；否则回退到系统 `grep` 或基于 JavaScript 的搜索。 - - 返回匹配行的列表，每行前面带有其文件路径（相对于搜索目录）和行号。 - - 默认将结果限制为最多 20 个匹配项以防止上下文溢出。当结果被截断时，会显示明确的警告，并提供优化搜索的建议。 -- **Output (`llmContent`):** 格式化的匹配结果字符串，例如： +- **参数:** + - `pattern` (string, 必填): 要搜索的正则表达式（regex）（例如 `"function\s+myFunction"`）。 + - `path` (string, 可选): 要搜索的目录的绝对路径。默认为当前工作目录。 + - `include` (string, 可选): 用于过滤搜索文件的 glob 模式（例如 `"*.js"`、`"src/**/*.{ts,tsx}"`）。如果省略，则搜索大多数文件（遵循常见的忽略规则）。 + - `maxResults` (number, 可选): 返回的最大匹配数量，防止上下文溢出（默认值：20，最大值：100）。对于范围较广的搜索建议使用较小值，对于精确搜索可使用较大值。 +- **行为:** + - 如果在 Git 仓库中且可用，则使用 `git grep` 以提高速度；否则回退到系统 `grep` 或基于 JavaScript 的搜索。 + - 返回匹配的行列表，每行前面带有其文件路径（相对于搜索目录）和行号。 + - 默认最多返回 20 条匹配结果，防止上下文溢出。当结果被截断时，会显示明确警告，并提供优化搜索的建议。 +- **输出 (`llmContent`):** 格式化后的匹配结果字符串，例如： ``` Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"): @@ -114,7 +114,7 @@ Qwen Code 提供了一套全面的工具，用于与本地文件系统进行交 - Increase 'maxResults' parameter if you need more matches (current: 20) ``` -- **Confirmation:** No. +- **确认操作:** 无。 ### `search_file_content` 示例 @@ -136,35 +136,35 @@ search_file_content(pattern="function", path="src", maxResults=50) search_file_content(pattern="function", include="*.js", maxResults=10) ``` -## 6. `replace` (编辑) +## 6. `edit` (编辑) -`replace` 用于替换文件中的文本。默认情况下，只替换第一个匹配项，但如果指定了 `expected_replacements` 参数，则可以替换多个匹配项。此工具专为精确、有针对性的修改而设计，要求 `old_string` 周围有足够的上下文，以确保修改的是正确的位置。 +`edit` 用于替换文件中的文本。默认情况下，它只会替换第一个匹配项，但如果指定了 `expected_replacements` 参数，则可以替换多个匹配项。该工具设计用于精确、有针对性的修改，并要求 `old_string` 周围有足够的上下文，以确保修改的是正确的位置。 -- **工具名称:** `replace` +- **工具名称:** `edit` - **显示名称:** Edit - **文件:** `edit.ts` - **参数:** - `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`。 - **行为:** - 如果 `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`，工具会读取 `file_path` 并尝试找到唯一一处匹配的 `old_string`。 + - 找到一处匹配后，会将其替换为 `new_string`。 + - **增强可靠性（多阶段编辑修正）：** 为了显著提高编辑的成功率，尤其是在模型提供的 `old_string` 可能不够精确的情况下，工具引入了多阶段编辑修正机制。 + - 如果初始的 `old_string` 没有找到，或者匹配了多个位置，工具可以借助 Qwen 模型迭代优化 `old_string`（以及可能的 `new_string`）。 + - 这种自我修正过程会尝试识别模型原本想要修改的唯一段落，使 `edit` 操作即使在初始上下文稍有偏差的情况下也更加稳健。 +- **失败条件：** 尽管有修正机制，工具仍会在以下情况下失败： - `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/zh/tools/mcp-server.md b/website/content/zh/tools/mcp-server.md index 6ee1ecb8..1086cdea 100644 --- a/website/content/zh/tools/mcp-server.md +++ b/website/content/zh/tools/mcp-server.md @@ -8,11 +8,11 @@ MCP server 是一个通过 Model Context Protocol 向 CLI 暴露工具和资源 MCP server 使 CLI 能够： -- **发现工具**：通过标准化的 schema 定义列出可用的工具、它们的描述和参数。 -- **执行工具**：使用定义好的参数调用特定工具，并接收结构化的响应。 -- **访问资源**：从特定资源中读取数据（尽管 CLI 主要专注于工具执行）。 +- **发现工具**：通过标准化的 schema 定义列出可用工具、它们的描述和参数。 +- **执行工具**：使用定义好的参数调用特定工具并接收结构化响应。 +- **访问资源**：从特定资源读取数据（尽管 CLI 主要专注于工具执行）。 -通过 MCP server，你可以扩展 CLI 的功能，使其执行超出其内置特性之外的操作，例如与数据库、API、自定义脚本或专业工作流进行交互。 +通过 MCP server，你可以扩展 CLI 的功能，使其执行超出其内置特性的操作，例如与数据库、API、自定义脚本或专业工作流进行交互。 ## 核心集成架构 @@ -20,12 +20,12 @@ Qwen Code 通过核心包（`packages/core/src/tools/`）中内置的一套复 ### 发现阶段（`mcp-client.ts`） -发现过程由 `discoverMcpTools()` 函数编排，其主要工作包括： +发现过程由 `discoverMcpTools()` 函数编排，该函数会： 1. **遍历配置的服务器**：从你的 `settings.json` 中的 `mcpServers` 配置读取服务器列表 2. **建立连接**：使用合适的传输机制（Stdio、SSE 或 Streamable HTTP）与各服务器建立连接 3. **获取工具定义**：通过 MCP 协议从每个服务器获取工具定义信息 -4. **清理并验证 schema**：对工具 schema 进行清理和验证，确保其与 Gemini API 兼容 +4. **清理并验证**：对工具 schema 进行清理和验证，确保其与 Qwen API 兼容 5. **注册工具**：将工具注册到全局工具注册表中，并处理可能的命名冲突问题 ### 执行层 (`mcp-tool.ts`) @@ -47,11 +47,11 @@ CLI 支持三种 MCP 传输类型： ## 如何设置你的 MCP 服务器 -Qwen Code 使用 `settings.json` 文件中的 `mcpServers` 配置来定位并连接到 MCP 服务器。该配置支持多个服务器，并可使用不同的传输机制。 +Qwen Code 使用 `settings.json` 文件中的 `mcpServers` 配置来定位并连接 MCP 服务器。该配置支持多个服务器，并可使用不同的传输机制。 ### 在 settings.json 中配置 MCP 服务器 -你可以在全局级别配置 MCP 服务器，编辑 `~/.qwen/settings.json` 文件，或者在你的项目根目录下创建或打开 `.qwen/settings.json` 文件。在文件中添加 `mcp_servers` 配置块。 +你可以在全局级别配置 MCP 服务器，编辑 `~/.qwen/settings.json` 文件，或者在你的项目根目录下创建或打开 `.qwen/settings.json` 文件。在文件中添加 `mcpServers` 配置块。 ### 配置结构 @@ -91,9 +91,9 @@ Qwen Code 使用 `settings.json` 文件中的 `mcpServers` 配置来定位并连 - **`env`** (object): 服务器进程的环境变量。值可以使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法引用环境变量 - **`cwd`** (string): Stdio 传输的工作目录 - **`timeout`** (number): 请求超时时间，单位为毫秒（默认值：600,000ms = 10分钟） -- **`trust`** (boolean): 当设置为 `true` 时，将跳过此服务器的所有 tool call 确认（默认值：`false`） -- **`includeTools`** (string[]): 从该 MCP 服务器包含的工具名称列表。指定后，只有此处列出的工具才可从此服务器使用（白名单行为）。未指定时，默认启用服务器提供的所有工具。 -- **`excludeTools`** (string[]): 从该 MCP 服务器排除的工具名称列表。即使服务器提供了这些工具，模型也无法使用。**注意：** `excludeTools` 的优先级高于 `includeTools` —— 如果某个工具同时出现在两个列表中，它将被排除。 +- **`trust`** (boolean): 当设置为 `true` 时，将跳过针对此服务器的所有 tool call 确认（默认值：`false`） +- **`includeTools`** (string[]): 指定从该 MCP 服务器包含的工具名称列表。指定后，仅此列表中的工具会从该服务器可用（白名单行为）。如果未指定，则默认启用服务器提供的所有工具。 +- **`excludeTools`** (string[]): 指定从该 MCP 服务器排除的工具名称列表。即使服务器提供了这些工具，它们也不会对模型可用。**注意：** `excludeTools` 的优先级高于 `includeTools` —— 如果某个工具同时出现在两个列表中，它将被排除。 ### 远程 MCP 服务器的 OAuth 支持 @@ -101,7 +101,7 @@ Qwen Code 支持通过 SSE 或 HTTP 传输方式对远程 MCP 服务器进行 OA #### 自动 OAuth 发现 -对于支持 OAuth 发现的服务器，你可以省略 OAuth 配置，让 CLI 自动完成发现： +对于支持 OAuth 发现的服务器，你可以省略 OAuth 配置，让 CLI 自动发现配置： ```json { @@ -136,7 +136,7 @@ CLI 将自动： **重要提示：** OAuth 认证要求你的本地机器能够： - 打开网页浏览器进行认证 -- 接收来自 `http://localhost:7777/oauth/callback` 的重定向 +- 接收来自 `http://localhost:7777/oauth/callback` 的重定向请求 以下环境将无法使用此功能： @@ -165,14 +165,14 @@ CLI 将自动： #### OAuth 配置属性 - **`enabled`** (boolean): 为此服务器启用 OAuth -- **`clientId`** (string): OAuth client ID（使用动态注册时可选） -- **`clientSecret`** (string): OAuth client secret（对于公共客户端可选） -- **`authorizationUrl`** (string): OAuth 授权端点（如果省略则自动发现） -- **`tokenUrl`** (string): OAuth token 端点（如果省略则自动发现） +- **`clientId`** (string): OAuth 客户端标识符（使用动态注册时可选） +- **`clientSecret`** (string): OAuth 客户端密钥（公共客户端可选） +- **`authorizationUrl`** (string): OAuth 授权端点（省略时自动发现） +- **`tokenUrl`** (string): OAuth token 端点（省略时自动发现） - **`scopes`** (string[]): 必需的 OAuth scopes -- **`redirectUri`** (string): 自定义 redirect URI（默认为 `http://localhost:7777/oauth/callback`） +- **`redirectUri`** (string): 自定义重定向 URI（默认为 `http://localhost:7777/oauth/callback`） - **`tokenParamName`** (string): SSE URLs 中 token 的查询参数名称 -- **`audiences`** (string[]): token 有效的 audiences +- **`audiences`** (string[]): token 有效的受众列表 ``` #### Token 管理 @@ -180,9 +180,9 @@ CLI 将自动： OAuth tokens 会自动： - **安全存储** 在 `~/.qwen/mcp-oauth-tokens.json` 中 -- **自动刷新**（如果提供了 refresh token，则在过期时自动刷新） -- **连接前验证** 每次连接尝试前都会进行有效性验证 -- **清理无效或过期的 token** 当 token 无效或过期时会被自动清除 +- **自动刷新** 当 token 过期时（如果有 refresh token） +- **连接前验证** 每次连接前都会验证 token 有效性 +- **自动清理** 当 token 无效或过期时自动清除 #### 认证提供者类型 @@ -322,13 +322,13 @@ OAuth tokens 会自动： 对于 `mcpServers` 中配置的每个 server： -1. **状态跟踪开始：** Server 状态被设置为 `CONNECTING` +1. **状态跟踪开始：** Server 状态设置为 `CONNECTING` 2. **Transport 选择：** 根据配置属性： - `httpUrl` → `StreamableHTTPClientTransport` - `url` → `SSEClientTransport` - `command` → `StdioClientTransport` -3. **建立连接：** MCP client 尝试在配置的 timeout 内建立连接 -4. **错误处理：** 连接失败会被记录日志，server 状态被设置为 `DISCONNECTED` +3. **建立连接：** MCP client 尝试与配置的 timeout 连接 +4. **错误处理：** 连接失败会被记录日志，server 状态设置为 `DISCONNECTED` ### 2. 工具发现 @@ -336,17 +336,17 @@ OAuth tokens 会自动： 1. **工具列表获取：** 客户端调用 MCP 服务器的工具列表 endpoint 2. **Schema 验证：** 验证每个工具的 function 声明 -3. **工具过滤：** 根据 `includeTools` 和 `excludeTools` 配置过滤工具 -4. **名称清理：** 清理工具名称以满足 Gemini API 要求： +3. **工具过滤：** 根据 `includeTools` 和 `excludeTools` 配置对工具进行过滤 +4. **名称清理：** 清理工具名称以满足 Qwen API 要求： - 将无效字符（非字母数字、下划线、点、连字符）替换为下划线 - - 超过 63 个字符的名称会被截断并用中间替换法处理（`___`） + - 超过 63 个字符的名称将被截断并用中间替换（`___`） ### 3. 冲突解决 当多个服务器暴露同名工具时： 1. **首次注册优先：** 第一个注册工具名称的服务器获得无前缀的名称 -2. **自动添加前缀：** 后续服务器的工具名称会被自动添加前缀：`serverName__toolName` +2. **自动添加前缀：** 后续服务器获得带前缀的名称：`serverName__toolName` 3. **注册表跟踪：** 工具注册表维护服务器名称与其工具之间的映射关系 ### 4. Schema 处理 @@ -355,7 +355,7 @@ OAuth tokens 会自动： - **`$schema` 属性** 会被移除 - **`additionalProperties`** 会被剥离 -- **包含 `default` 的 `anyOf`** 会移除默认值（为了兼容 Vertex AI） +- **包含 `default` 的 `anyOf`** 会移除默认值（为兼容 Vertex AI） - **递归处理** 会应用到嵌套的 schema ### 5. 连接管理 @@ -372,9 +372,9 @@ OAuth tokens 会自动： ### 1. 工具调用 -模型会生成一个 `FunctionCall`，包含： +模型生成一个 `FunctionCall`，包含： -- **工具名称：** 已注册的名称（可能带有前缀） +- **工具名称：** 注册时的名称（可能带有前缀） - **参数：** 符合工具参数 schema 的 JSON 对象 ### 2. 确认流程 @@ -409,8 +409,8 @@ if (this.trust) { 确认后（或绕过信任机制）： -1. **参数准备：** 参数会根据工具的 schema 进行验证 -2. **MCP 调用：** 底层的 `CallableTool` 会向服务器发起调用： +1. **参数准备：** 参数会根据工具的 schema 进行验证 +2. **MCP 调用：** 底层 `CallableTool` 会向服务器发起调用： ```typescript const functionCalls = [ @@ -427,14 +427,14 @@ if (this.trust) { 执行结果包含： -- **`llmContent`：** 供语言模型使用的原始响应内容 -- **`returnDisplay`：** 供用户展示的格式化输出（通常是 markdown 代码块中的 JSON） +- **`llmContent`：** 供语言模型使用的原始响应内容 +- **`returnDisplay`：** 用于用户展示的格式化输出（通常是 markdown 代码块中的 JSON） ## 如何与你的 MCP 服务器交互 ### 使用 `/mcp` 命令 -`/mcp` 命令提供关于你的 MCP 服务器设置的完整信息： +`/mcp` 命令提供关于你的 MCP 服务器配置的完整信息： ```bash /mcp @@ -472,7 +472,7 @@ Discovery State: COMPLETED ### 工具使用 -一旦被发现，MCP 工具就会像内置工具一样提供给 Gemini 模型使用。模型将自动： +一旦被发现，MCP 工具就会像内置工具一样提供给 Qwen 模型使用。模型将自动： 1. **根据你的请求选择合适的工具** 2. **显示确认对话框**（除非服务器是受信任的） @@ -483,7 +483,7 @@ Discovery State: COMPLETED ### 连接状态 -MCP 集成会跟踪几种状态： +MCP 集成会跟踪以下几种状态： #### 服务器状态 (`MCPServerStatus`) @@ -493,7 +493,7 @@ MCP 集成会跟踪几种状态： #### 发现阶段 (`MCPDiscoveryState`) -- **`NOT_STARTED`:** 发现尚未开始 +- **`NOT_STARTED`:** 尚未开始发现 - **`IN_PROGRESS`:** 正在发现服务器 - **`COMPLETED`:** 发现已完成（无论是否有错误） @@ -506,21 +506,21 @@ MCP 集成会跟踪几种状态： **排查步骤：** 1. **检查配置：** 确认 `command`、`args` 和 `cwd` 配置正确 -2. **手动测试：** 直接运行服务器命令，确保可以正常工作 +2. **手动测试：** 直接运行服务器命令，确保可以正常启动 3. **检查依赖：** 确保所有必需的 packages 都已安装 4. **查看日志：** 检查 CLI 输出中的错误信息 -5. **验证权限：** 确保 CLI 可以执行服务器命令 +5. **验证权限：** 确保 CLI 有权限执行服务器命令 #### 未发现工具 -**症状：** 服务器连接成功但没有可用工具 +**症状：** 服务器已连接但没有可用的 tools **排查步骤：** -1. **验证工具注册：** 确保你的服务器实际注册了工具 -2. **检查 MCP 协议：** 确认你的服务器正确实现了 MCP 工具列表功能 +1. **验证工具注册：** 确保你的服务器确实注册了 tools +2. **检查 MCP 协议：** 确认你的服务器正确实现了 MCP tool 列表功能 3. **查看服务器日志：** 检查 stderr 输出中的服务器端错误 -4. **测试工具列表：** 手动测试服务器的工具发现 endpoint +4. **测试工具列表：** 手动测试服务器的 tool discovery endpoint #### 工具无法执行 @@ -547,19 +547,19 @@ MCP 集成会跟踪几种状态： ### 调试技巧 1. **启用调试模式：** 使用 `--debug` 参数运行 CLI 以获取详细输出 -2. **检查 stderr：** MCP 服务器的 stderr 输出会被捕获并记录（INFO 级别消息会被过滤） -3. **独立测试：** 在集成之前，先独立测试你的 MCP 服务器 -4. **增量配置：** 从简单工具开始，再逐步添加复杂功能 -5. **频繁使用 `/mcp`：** 在开发过程中监控服务器状态 +2. **检查 stderr：** MCP server 的 stderr 会被捕获并记录（INFO 级别的消息会被过滤） +3. **独立测试：** 在集成之前，先独立测试你的 MCP server +4. **增量配置：** 从简单的 tools 开始，再逐步添加复杂功能 +5. **频繁使用 `/mcp`：** 在开发过程中监控 server 状态 ## 重要说明 ### 安全注意事项 -- **信任设置：** `trust` 选项会跳过所有确认对话框。请谨慎使用，仅用于你完全控制的服务器 -- **访问令牌：** 配置包含 API key 或 token 的环境变量时要注意安全性 -- **沙盒兼容性：** 使用沙盒时，确保 MCP 服务器在沙盒环境中可用 -- **私有数据：** 使用范围过广的 personal access token 可能导致不同仓库间的信息泄露 +- **信任设置：** `trust` 选项会跳过所有确认对话框。请谨慎使用，仅用于你完全控制的 server +- **访问令牌：** 配置包含 API key 或 token 的环境变量时要注意安全 +- **沙盒兼容性：** 使用沙盒时，确保 MCP server 在沙盒环境中可用 +- **私有数据：** 使用范围过广的 personal access token 可能导致不同 repository 间的信息泄露 ### 性能与资源管理 @@ -570,17 +570,17 @@ MCP 集成会跟踪几种状态： ### Schema 兼容性 -- **属性剥离：** 为兼容 Gemini API，系统会自动移除某些 schema 属性（如 `$schema`、`additionalProperties`） +- **属性剥离：** 为兼容 Qwen API，系统会自动移除某些 schema 属性（如 `$schema`、`additionalProperties`） - **名称清理：** 工具名称会自动清理以满足 API 要求 - **冲突解决：** 通过自动添加前缀来解决不同服务器之间的工具名称冲突 -这种全面的集成使 MCP 服务器成为扩展 CLI 功能的强大方式，同时保证了安全性、可靠性和易用性。 +这种全面的集成使 MCP 服务器成为扩展 CLI 功能的强大方式，同时兼顾安全性、可靠性和易用性。 -## 从 Tools 返回富内容 +## 从工具返回富内容 -MCP tools 不仅限于返回简单的文本。你可以返回丰富的多部分的内容，包括文本、图像、音频和其他二进制数据，所有这些都可以在单个 tool response 中完成。这使你能够构建强大的 tools，可以在一次交互中向模型提供多样化的信息。 +MCP 工具不仅限于返回简单的文本。你可以返回丰富的多部分的内容，包括文本、图像、音频和其他二进制数据，所有这些都在单个工具响应中完成。这使你能够构建强大的工具，在一次交互中为模型提供多样化的信息。 -所有从 tool 返回的数据都会被处理并作为上下文发送给模型，用于下一次生成，使模型能够对提供的信息进行推理或总结。 +所有从工具返回的数据都会被处理并作为上下文发送给模型，用于下一次生成，使模型能够对提供的信息进行推理或总结。 ### 工作原理 @@ -620,11 +620,11 @@ MCP tools 不仅限于返回简单的文本。你可以返回丰富的多部分 当 Qwen Code 接收到此响应时，它将： -1. 提取所有文本并将其合并为单个 `functionResponse` 部分，供模型使用。 -2. 将图像数据作为单独的 `inlineData` 部分呈现。 -3. 在 CLI 中提供简洁、用户友好的摘要，表明已接收到文本和图像。 +1. 提取所有文本并将其合并为一个单独的 `functionResponse` 部分，供模型使用。 +2. 将图像数据作为独立的 `inlineData` 部分呈现。 +3. 在 CLI 中提供清晰、用户友好的摘要，表明同时收到了文本和图像。 -这使你能够构建复杂的工具，为 Gemini 模型提供丰富的多模态上下文。 +这使你能够构建功能强大的工具，为 Qwen 模型提供丰富的多模态上下文。 ## MCP Prompts 作为 Slash Commands @@ -632,7 +632,7 @@ MCP tools 不仅限于返回简单的文本。你可以返回丰富的多部分 ### 在服务器端定义 Prompts -下面是一个定义了 prompts 的 stdio MCP 服务器的小例子： +下面是一个定义了 prompts 的 stdio MCP server 小示例： ```ts import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; @@ -668,7 +668,7 @@ const transport = new StdioServerTransport(); await server.connect(transport); ``` -这段代码可以通过以下方式添加到 `settings.json` 的 `mcpServers` 配置项中： +这段代码可以在 `settings.json` 中的 `mcpServers` 下这样配置： ```json "nodeServer": { @@ -695,13 +695,13 @@ await server.connect(transport); ## 使用 `qwen mcp` 管理 MCP 服务器 -虽然你可以通过手动编辑 `settings.json` 文件来配置 MCP 服务器，但 CLI 提供了一套便捷的命令，可以让你以编程方式管理服务器配置。这些命令简化了添加、列出和删除 MCP 服务器的过程，无需直接编辑 JSON 文件。 +虽然你可以通过手动编辑 `settings.json` 文件来配置 MCP 服务器，但 CLI 提供了一套便捷的命令，可以让你以编程方式管理服务器配置。这些命令简化了添加、列出和删除 MCP 服务器的操作，无需直接编辑 JSON 文件。 ### 添加服务器 (`qwen mcp add`) `add` 命令用于在你的 `settings.json` 中配置一个新的 MCP 服务器。根据作用域 (`-s, --scope`)，该配置将被添加到用户配置文件 `~/.qwen/settings.json` 或项目配置文件 `.qwen/settings.json` 中。 -**命令：** +**命令格式：** ```bash qwen mcp add [options] [args...] @@ -709,7 +709,7 @@ qwen mcp add [options] [args...] - ``: 服务器的唯一名称。 - ``: 要执行的命令（用于 `stdio`）或 URL（用于 `http`/`sse`）。 -- `[args...]`: 可选参数，用于 `stdio` 命令。 +- `[args...]`: 可选参数，仅适用于 `stdio` 类型的命令。 **选项（Flags）：** @@ -719,7 +719,7 @@ qwen mcp add [options] [args...] - `-H, --header`: 为 SSE 和 HTTP 传输设置 HTTP headers（例如 -H "X-Api-Key: abc123" -H "Authorization: Bearer abc123"）。 - `--timeout`: 设置连接超时时间（毫秒）。 - `--trust`: 信任该服务器（跳过所有工具调用确认提示）。 -- `--description`: 设置服务器的描述信息。 +- `--description`: 设置服务器描述信息。 - `--include-tools`: 包含的工具列表，以逗号分隔。 - `--exclude-tools`: 排除的工具列表，以逗号分隔。 @@ -765,13 +765,11 @@ qwen mcp add --transport http secure-http https://api.example.com/mcp/ --header qwen mcp add --transport sse ``` -# 示例：添加一个 SSE 服务器 -```bash +```markdown +# 示例：添加 SSE 服务器 qwen mcp add --transport sse sse-server https://api.example.com/sse/ -``` -# 示例：添加一个带认证 header 的 SSE 服务器 -```bash +# 示例：添加带认证 header 的 SSE 服务器 qwen mcp add --transport sse secure-sse https://api.example.com/sse/ --header "Authorization: Bearer abc123" ``` @@ -809,4 +807,4 @@ qwen mcp remove qwen mcp remove my-server ``` -该命令会根据作用域 (`-s, --scope`) 在相应的 `settings.json` 文件中找到并删除 `mcpServers` 对象里的 "my-server" 条目。 \ No newline at end of file +该命令会根据作用域 (`-s, --scope`) 在相应的 `settings.json` 文件中查找并删除 `mcpServers` 对象中的 "my-server" 条目。 \ No newline at end of file diff --git a/website/content/zh/tools/memory.md b/website/content/zh/tools/memory.md index fd737efc..c5c499eb 100644 --- a/website/content/zh/tools/memory.md +++ b/website/content/zh/tools/memory.md @@ -10,7 +10,7 @@ `save_memory` 接受一个参数： -- `fact` (string, 必填): 需要记住的具体事实或信息片段。这应该是一个清晰、独立的自然语言陈述。 +- `fact` (string, 必填): 需要记住的特定事实或信息片段。这应该是一个清晰、独立的自然语言陈述。 ## 如何在 Qwen Code 中使用 `save_memory` @@ -24,7 +24,7 @@ save_memory(fact="Your fact here.") ``` -### `save_memory` 使用示例 +### `save_memory` 示例 记住用户偏好： @@ -32,13 +32,13 @@ save_memory(fact="Your fact here.") save_memory(fact="My preferred programming language is Python.") ``` -存储项目特定信息： +存储项目特定的细节： ``` -save_memory(fact="The project I'm currently working on is called 'gemini-cli'.") +save_memory(fact="The project I'm currently working on is called 'qwen-code'.") ``` ## 重要说明 - **一般用法：** 此工具应用于存储简洁、重要的事实。不适用于存储大量数据或对话历史。 -- **Memory 文件：** memory 文件是一个纯文本 Markdown 文件，因此你可以根据需要手动查看和编辑它。 \ No newline at end of file +- **Memory 文件：** Memory 文件是一个纯文本 Markdown 文件，因此你可以根据需要手动查看和编辑它。 \ No newline at end of file diff --git a/website/content/zh/tools/web-fetch.md b/website/content/zh/tools/web-fetch.md index 680cb8bf..aa6d1fd4 100644 --- a/website/content/zh/tools/web-fetch.md +++ b/website/content/zh/tools/web-fetch.md @@ -4,25 +4,25 @@ ## 描述 -使用 `web_fetch` 可以从指定 URL 获取内容，并通过 AI 模型进行处理。该工具接收一个 URL 和一个 prompt 作为输入，获取 URL 内容后将 HTML 转换为 markdown 格式，并使用一个小而快的模型结合 prompt 对内容进行处理。 +使用 `web_fetch` 可以从指定 URL 获取内容，并通过 AI 模型进行处理。该工具接收一个 URL 和一个 prompt 作为输入，获取 URL 内容后，将 HTML 转换为 markdown 格式，并使用一个小而快的模型结合 prompt 对内容进行处理。 ### 参数 `web_fetch` 接收两个参数： -- `url` (string, 必填): 需要获取内容的 URL。必须是一个完整的有效 URL，以 `http://` 或 `https://` 开头。 +- `url` (string, 必填): 要获取内容的 URL。必须是一个以 `http://` 或 `https://` 开头的完整有效 URL。 - `prompt` (string, 必填): 描述你希望从页面内容中提取哪些信息的 prompt。 ## 如何在 Qwen Code 中使用 `web_fetch` -要在 Qwen Code 中使用 `web_fetch`，你需要提供一个 URL 和一个 prompt，描述你希望从该 URL 中提取什么内容。该工具在抓取 URL 之前会请求确认。确认后，工具将直接获取内容，并使用 AI 模型进行处理。 +要在 Qwen Code 中使用 `web_fetch`，你需要提供一个 URL 和一个 prompt，描述你希望从该 URL 中提取什么内容。该工具在抓取 URL 之前会请求确认。确认后，工具将直接获取内容并使用 AI 模型进行处理。 该工具会自动将 HTML 转换为文本，处理 GitHub blob URL（将其转换为 raw URL），并出于安全考虑将 HTTP URL 升级为 HTTPS。 -使用方式： +用法： ``` -web_fetch(url="https://example.com", prompt="Summarize the main points of this article") +web_fetch(url="https://example.com", prompt="总结这篇文章的主要观点") ``` ## `web_fetch` 示例 @@ -42,7 +42,7 @@ web_fetch(url="https://arxiv.org/abs/2401.0001", prompt="What are the key findin 分析 GitHub 文档： ``` -web_fetch(url="https://github.com/google/gemini-react/blob/main/README.md", prompt="What are the installation steps and main features?") +web_fetch(url="https://github.com/QwenLM/Qwen/blob/main/README.md", prompt="What are the installation steps and main features?") ``` ## 重要说明 diff --git a/website/content/zh/troubleshooting.md b/website/content/zh/troubleshooting.md index 9ffe7a56..4b414527 100644 --- a/website/content/zh/troubleshooting.md +++ b/website/content/zh/troubleshooting.md @@ -5,69 +5,64 @@ - 认证或登录错误 - 常见问题解答 (FAQs) - 调试技巧 -- 与你遇到的问题相似的现有 GitHub Issues，或创建新的 Issues +- 与你遇到的问题相似的现有 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` +- **错误: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` 或 `unable to get local issuer certificate`** + - **原因:** 你可能在 corporate network 中，防火墙会拦截并检查 SSL/TLS 流量。这通常需要 Node.js 信任自定义的根 CA 证书。 + - **解决方案:** 将 `NODE_EXTRA_CA_CERTS` 环境变量设置为你的 corporate root CA 证书文件的绝对路径。 + - 示例: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` ## 常见问题 (FAQs) - **Q: 如何将 Qwen Code 更新到最新版本？** - - A: 如果你是通过 `npm` 全局安装的，可以使用命令 `npm install -g @qwen-code/qwen-code@latest` 进行更新。如果你是从源码编译的，请从 repository 拉取最新更改，然后使用命令 `npm run build` 重新构建。 + - A: 如果你是通过 `npm` 全局安装的，可以使用命令 `npm install -g @qwen-code/qwen-code@latest` 进行更新。如果你是从源码编译的，请从仓库拉取最新更改，然后使用命令 `npm run build` 重新构建。 - **Q: Qwen Code 的配置或设置文件存储在哪里？** - A: Qwen Code 的配置存储在两个 `settings.json` 文件中： - 1. 在你的 home 目录下：`~/.qwen/settings.json`。 - 2. 在你的项目根目录下：`./.qwen/settings.json`。 + 1. 用户主目录下：`~/.qwen/settings.json`。 + 2. 项目根目录下：`./.qwen/settings.json`。 - 更多详情请参考 [Qwen Code Configuration](./cli/configuration.md)。 + 更多详情请参考 [Qwen Code 配置](./cli/configuration.md)。 -- **Q: 为什么我在 stats 输出中看不到缓存的 token 数量？** - - A: 缓存的 token 信息只有在使用缓存 token 时才会显示。此功能适用于 API key 用户（Gemini API key 或 Google Cloud Vertex AI），但不适用于 OAuth 用户（例如 Google 个人/企业账户，如 Google Gmail 或 Google Workspace）。这是因为 Gemini Code Assist API 不支持缓存内容的创建。你仍然可以使用 `/stats` 命令查看总 token 使用量。 +- **Q: 为什么在统计输出中看不到缓存的 token 数量？** + - A: 缓存的 token 信息只有在使用缓存 token 时才会显示。此功能适用于 API key 用户（Qwen API key 或 Google Cloud Vertex AI），但不适用于 OAuth 用户（例如 Google 个人/企业账户，如 Google Gmail 或 Google Workspace）。这是因为 Qwen Code Assist API 不支持缓存内容的创建。你仍然可以使用 `/stats` 命令查看总 token 使用量。 ## 常见错误信息及解决方案 - **错误：启动 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`，请确保使用了正确的命令来调用（例如：`node packages/cli/dist/index.js ...`）。要更新，请从仓库拉取最新更改，然后使用命令 `npm run build` 重新构建。 - **错误：`MODULE_NOT_FOUND` 或导入错误** - - **原因：** 依赖未正确安装，或者项目尚未构建。 + - **原因：** 依赖未正确安装，或项目未构建。 - **解决方案：** - 1. 运行 `npm install` 确保所有依赖都已安装。 + 1. 运行 `npm install` 确保所有依赖已安装。 2. 运行 `npm run build` 编译项目。 - 3. 使用 `npm run start` 验证构建是否成功完成。 + 3. 使用 `npm run start` 验证构建是否成功。 -- **错误：提示 "Operation not permitted"、"Permission denied" 或类似信息** - - **原因：** 当启用沙箱时，Qwen Code 可能尝试执行被沙箱配置限制的操作，例如在项目目录或系统临时目录之外进行写入。 +- **错误：提示“Operation not permitted”、“Permission denied”或类似信息** + - **原因：** 当沙箱（sandboxing）启用时，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` -- **DEBUG 模式无法通过项目 .env 文件启用** - - **问题：** 在项目的 `.env` 文件中设置 `DEBUG=true` 并不会启用 CLI 的 debug 模式。 - - **原因：** 为了避免影响 CLI 行为，`DEBUG` 和 `DEBUG_MODE` 变量会自动从项目 `.env` 文件中排除。 - - **解决方案：** 使用 `.qwen/.env` 文件代替，或者在 `settings.json` 中配置 `excludedProjectEnvVars` 设置，减少被排除的变量数量。 +- **从项目 .env 文件中无法启用 DEBUG 模式** + - **问题：** 在项目的 `.env` 文件中设置 `DEBUG=true` 无法启用 CLI 的 debug 模式。 + - **原因：** 为避免干扰 CLI 行为，`DEBUG` 和 `DEBUG_MODE` 变量会自动从项目 `.env` 文件中排除。 + - **解决方案：** 使用 `.qwen/.env` 文件代替，或在 `settings.json` 中配置 `excludedProjectEnvVars` 以减少被排除的变量。 ## IDE Companion 无法连接 @@ -97,6 +92,6 @@ - **预检检查：** - 提交代码前始终运行 `npm run preflight`。这可以捕获许多与格式化、代码规范和类型错误相关的常见问题。 -## 查找类似的 GitHub Issues 或创建新 Issues +## 查找类似问题或创建新 Issue -如果你遇到的问题未在本 _Troubleshooting guide_ 中涵盖，建议前往 Qwen Code 的 [GitHub Issue tracker](https://github.com/QwenLM/qwen-code/issues) 进行搜索。如果找不到与你问题相似的 Issue，欢迎创建一个新的 GitHub Issue，并提供详细描述。我们也非常欢迎你提交 Pull requests！ \ No newline at end of file +如果你遇到的问题未在本 _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 b94e03ef..b0b432a9 100644 --- a/website/translation-changelog.json +++ b/website/translation-changelog.json @@ -1,4 +1,137 @@ [ + { + "timestamp": "2025-09-12T09:44:34.622Z", + "commit": "67e2e270bd548ab9845f3e0d99f0b35423ae94da", + "sourceLanguage": "en", + "translatedFiles": { + "zh": { + "success": [ + "Uninstall.md", + "checkpointing.md", + "cli/commands.md", + "cli/configuration.md", + "cli/index.md", + "cli/token-caching.md", + "cli/welcome-back.md", + "deployment.md", + "ide-integration.md", + "index.md", + "keyboard-shortcuts.md", + "npm.md", + "subagents.md", + "telemetry.md", + "tools/file-system.md", + "tools/mcp-server.md", + "tools/memory.md", + "tools/web-fetch.md", + "troubleshooting.md" + ], + "failed": [] + }, + "de": { + "success": [ + "Uninstall.md", + "checkpointing.md", + "cli/commands.md", + "cli/configuration.md", + "cli/index.md", + "cli/token-caching.md", + "cli/welcome-back.md", + "deployment.md", + "ide-integration.md", + "index.md", + "keyboard-shortcuts.md", + "npm.md", + "subagents.md", + "telemetry.md", + "tools/file-system.md", + "tools/mcp-server.md", + "tools/memory.md", + "tools/web-fetch.md", + "troubleshooting.md" + ], + "failed": [] + }, + "fr": { + "success": [ + "Uninstall.md", + "checkpointing.md", + "cli/commands.md", + "cli/configuration.md", + "cli/index.md", + "cli/token-caching.md", + "cli/welcome-back.md", + "deployment.md", + "ide-integration.md", + "index.md", + "keyboard-shortcuts.md", + "npm.md", + "subagents.md", + "telemetry.md", + "tools/file-system.md", + "tools/mcp-server.md", + "tools/memory.md", + "tools/web-fetch.md", + "troubleshooting.md" + ], + "failed": [] + }, + "ru": { + "success": [ + "Uninstall.md", + "checkpointing.md", + "cli/commands.md", + "cli/configuration.md", + "cli/index.md", + "cli/token-caching.md", + "cli/welcome-back.md", + "deployment.md", + "ide-integration.md", + "index.md", + "keyboard-shortcuts.md", + "npm.md", + "subagents.md", + "telemetry.md", + "tools/file-system.md", + "tools/mcp-server.md", + "tools/memory.md", + "tools/web-fetch.md", + "troubleshooting.md" + ], + "failed": [] + }, + "ja": { + "success": [ + "Uninstall.md", + "checkpointing.md", + "cli/commands.md", + "cli/configuration.md", + "cli/index.md", + "cli/token-caching.md", + "cli/welcome-back.md", + "deployment.md", + "ide-integration.md", + "index.md", + "keyboard-shortcuts.md", + "npm.md", + "subagents.md", + "telemetry.md", + "tools/file-system.md", + "tools/mcp-server.md", + "tools/memory.md", + "tools/web-fetch.md", + "troubleshooting.md" + ], + "failed": [] + } + }, + "stats": { + "totalFiles": 19, + "languages": 5, + "successCount": 95, + "failedCount": 0 + } + }, { "timestamp": "2025-08-28T13:34:49.676Z", "commit": "1610c1586e47a867edd12e87d1c64051325648c5",