Merge pull request #1484 from QwenLM/fix-docs

fix: docs errors and add community contacts

README.md

@@ -201,6 +201,11 @@ If you encounter issues, check the [troubleshooting guide](https://qwenlm.github
 
 To report a bug from within the CLI, run `/bug` and include a short title and repro steps.
 
+## Connect with Us
+
+- Discord: https://discord.gg/ycKBjdNd
+- Dingtalk: https://qr.dingtalk.com/action/joingroup?code=v1,k1,+FX6Gf/ZDlTahTIRi8AEQhIaBlqykA0j+eBKKdhLeAE=&_dt_no_comment=1&origin=1
+
 ## Acknowledgments
 
 This project is based on [Google Gemini CLI](https://github.com/google-gemini/gemini-cli). We acknowledge and appreciate the excellent work of the Gemini CLI team. Our main contribution focuses on parser-level adaptations to better support Qwen-Coder models.

docs/users/configuration/settings.md

@@ -480,7 +480,7 @@ Arguments passed directly when running the CLI can override other configurations
 | `--telemetry-otlp-protocol`  |       | Sets the OTLP protocol for telemetry (`grpc` or `http`).                                                                                                                                |                                        | Defaults to `grpc`. See [telemetry](../../developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `--telemetry-log-prompts`    |       | Enables logging of prompts for telemetry.                                                                                                                                               |                                        | See [telemetry](../../developers/development/telemetry) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `--checkpointing`            |       | Enables [checkpointing](../features/checkpointing).                                                                                                                                     |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `--acp`                      |       | Enables ACP mode (Agent Control Protocol). Useful for IDE/editor integrations like [Zed](../integration-zed).                                                                           |                                        | Stable. Replaces the deprecated `--experimental-acp` flag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `--acp`                      |       | Enables ACP mode (Agent Client Protocol). Useful for IDE/editor integrations like [Zed](../integration-zed).                                                                            |                                        | Stable. Replaces the deprecated `--experimental-acp` flag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `--experimental-skills`      |       | Enables experimental [Agent Skills](../features/skills) (registers the `skill` tool and loads Skills from `.qwen/skills/` and `~/.qwen/skills/`).                                       |                                        | Experimental.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `--extensions`               | `-e`  | Specifies a list of extensions to use for the session.                                                                                                                                  | Extension names                        | If not provided, all available extensions are used. Use the special term `qwen -e none` to disable all extensions. Example: `qwen -e my-extension -e my-other-extension`                                                                                                                                                                                                                                                                                                                                                                                        |
 | `--list-extensions`          | `-l`  | Lists all available extensions and exits.                                                                                                                                               |                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

docs/users/integration-jetbrains.md

@@ -1,11 +1,11 @@
 # JetBrains IDEs
 
-> JetBrains IDEs provide native support for AI coding assistants through the Agent Control Protocol (ACP). This integration allows you to use Qwen Code directly within your JetBrains IDE with real-time code suggestions.
+> JetBrains IDEs provide native support for AI coding assistants through the Agent Client Protocol (ACP). This integration allows you to use Qwen Code directly within your JetBrains IDE with real-time code suggestions.
 
 ### Features
 
 - **Native agent experience**: Integrated AI assistant panel within your JetBrains IDE
-- **Agent Control Protocol**: Full support for ACP enabling advanced IDE interactions
+- **Agent Client Protocol**: Full support for ACP enabling advanced IDE interactions
 - **Symbol management**: #-mention files to add them to the conversation context
 - **Conversation history**: Access to past conversations within the IDE
 
@@ -40,7 +40,7 @@
 
 4. The Qwen Code agent should now be available in the AI Assistant panel
 
-![Qwen Code in JetBrains AI Chat](./images/jetbrains-acp.png)
+![Qwen Code in JetBrains AI Chat](https://img.alicdn.com/imgextra/i3/O1CN01ZxYel21y433Ci6eg0_!!6000000006524-2-tps-2774-1494.png)
 
 ## Troubleshooting
 

docs/users/integration-zed.md

@@ -1,6 +1,6 @@
 # Zed Editor
 
-> Zed Editor provides native support for AI coding assistants through the Agent Control Protocol (ACP). This integration allows you to use Qwen Code directly within Zed's interface with real-time code suggestions.
+> Zed Editor provides native support for AI coding assistants through the Agent Client Protocol (ACP). This integration allows you to use Qwen Code directly within Zed's interface with real-time code suggestions.
 
 ![Zed Editor Overview](https://img.alicdn.com/imgextra/i1/O1CN01aAhU311GwEoNh27FP_!!6000000000686-2-tps-3024-1898.png)
 

package-lock.json

@@ -18588,7 +18588,7 @@
     },
     "packages/sdk-typescript": {
       "name": "@qwen-code/sdk",
-      "version": "0.1.2",
+      "version": "0.1.3",
       "license": "Apache-2.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.25.1",

packages/core/src/qwen/qwenOAuth2.ts

@@ -559,6 +559,109 @@ export async function getQwenOAuthClient(
   }
 }
 
+/**
+ * Displays a formatted box with OAuth device authorization URL.
+ * Uses process.stderr.write() to bypass ConsolePatcher and ensure the auth URL
+ * is always visible to users, especially in non-interactive mode.
+ * Using stderr prevents corruption of structured JSON output (which goes to stdout)
+ * and follows the standard Unix convention of user-facing messages to stderr.
+ */
+function showFallbackMessage(verificationUriComplete: string): void {
+  const title = 'Qwen OAuth Device Authorization';
+  const url = verificationUriComplete;
+  const minWidth = 70;
+  const maxWidth = 80;
+  const boxWidth = Math.min(Math.max(title.length + 4, minWidth), maxWidth);
+
+  // Calculate the width needed for the box (account for padding)
+  const contentWidth = boxWidth - 4; // Subtract 2 spaces and 2 border chars
+
+  // Helper to wrap text to fit within box width
+  const wrapText = (text: string, width: number): string[] => {
+    // For URLs, break at any character if too long
+    if (text.startsWith('http://') || text.startsWith('https://')) {
+      const lines: string[] = [];
+      for (let i = 0; i < text.length; i += width) {
+        lines.push(text.substring(i, i + width));
+      }
+      return lines;
+    }
+
+    // For regular text, break at word boundaries
+    const words = text.split(' ');
+    const lines: string[] = [];
+    let currentLine = '';
+
+    for (const word of words) {
+      if (currentLine.length + word.length + 1 <= width) {
+        currentLine += (currentLine ? ' ' : '') + word;
+      } else {
+        if (currentLine) {
+          lines.push(currentLine);
+        }
+        currentLine = word.length > width ? word.substring(0, width) : word;
+      }
+    }
+    if (currentLine) {
+      lines.push(currentLine);
+    }
+    return lines;
+  };
+
+  // Build the box borders with title centered in top border
+  // Format: +--- Title ---+
+  const titleWithSpaces = ' ' + title + ' ';
+  const totalDashes = boxWidth - 2 - titleWithSpaces.length; // Subtract corners and title
+  const leftDashes = Math.floor(totalDashes / 2);
+  const rightDashes = totalDashes - leftDashes;
+  const topBorder =
+    '+' +
+    '-'.repeat(leftDashes) +
+    titleWithSpaces +
+    '-'.repeat(rightDashes) +
+    '+';
+  const emptyLine = '|' + ' '.repeat(boxWidth - 2) + '|';
+  const bottomBorder = '+' + '-'.repeat(boxWidth - 2) + '+';
+
+  // Build content lines
+  const instructionLines = wrapText(
+    'Please visit the following URL in your browser to authorize:',
+    contentWidth,
+  );
+  const urlLines = wrapText(url, contentWidth);
+  const waitingLine = 'Waiting for authorization to complete...';
+
+  // Write the box
+  process.stderr.write('\n' + topBorder + '\n');
+  process.stderr.write(emptyLine + '\n');
+
+  // Write instructions
+  for (const line of instructionLines) {
+    process.stderr.write(
+      '| ' + line + ' '.repeat(contentWidth - line.length) + ' |\n',
+    );
+  }
+
+  process.stderr.write(emptyLine + '\n');
+
+  // Write URL
+  for (const line of urlLines) {
+    process.stderr.write(
+      '| ' + line + ' '.repeat(contentWidth - line.length) + ' |\n',
+    );
+  }
+
+  process.stderr.write(emptyLine + '\n');
+
+  // Write waiting message
+  process.stderr.write(
+    '| ' + waitingLine + ' '.repeat(contentWidth - waitingLine.length) + ' |\n',
+  );
+
+  process.stderr.write(emptyLine + '\n');
+  process.stderr.write(bottomBorder + '\n\n');
+}
+
 async function authWithQwenDeviceFlow(
   client: QwenOAuth2Client,
   config: Config,
@@ -571,6 +674,50 @@ async function authWithQwenDeviceFlow(
   };
   qwenOAuth2Events.once(QwenOAuth2Event.AuthCancel, cancelHandler);
 
+  // Helper to check cancellation and return appropriate result
+  const checkCancellation = (): AuthResult | null => {
+    if (!isCancelled) {
+      return null;
+    }
+    const message = 'Authentication cancelled by user.';
+    console.debug('\n' + message);
+    qwenOAuth2Events.emit(QwenOAuth2Event.AuthProgress, 'error', message);
+    return { success: false, reason: 'cancelled', message };
+  };
+
+  // Helper to emit auth progress events
+  const emitAuthProgress = (
+    status: 'polling' | 'success' | 'error' | 'timeout' | 'rate_limit',
+    message: string,
+  ): void => {
+    qwenOAuth2Events.emit(QwenOAuth2Event.AuthProgress, status, message);
+  };
+
+  // Helper to handle browser launch with error handling
+  const launchBrowser = async (url: string): Promise<void> => {
+    try {
+      const childProcess = await open(url);
+
+      // IMPORTANT: Attach an error handler to the returned child process.
+      // Without this, if `open` fails to spawn a process (e.g., `xdg-open` is not found
+      // in a minimal Docker container), it will emit an unhandled 'error' event,
+      // causing the entire Node.js process to crash.
+      if (childProcess) {
+        childProcess.on('error', (err) => {
+          console.debug(
+            'Browser launch failed:',
+            err.message || 'Unknown error',
+          );
+        });
+      }
+    } catch (err) {
+      console.debug(
+        'Failed to open browser:',
+        err instanceof Error ? err.message : 'Unknown error',
+      );
+    }
+  };
+
   try {
     // Generate PKCE code verifier and challenge
     const { code_verifier, code_challenge } = generatePKCEPair();
@@ -593,56 +740,18 @@ async function authWithQwenDeviceFlow(
     // Emit device authorization event for UI integration immediately
     qwenOAuth2Events.emit(QwenOAuth2Event.AuthUri, deviceAuth);
 
-    const showFallbackMessage = () => {
-      console.log('\n=== Qwen OAuth Device Authorization ===');
-      console.log(
-        'Please visit the following URL in your browser to authorize:',
-      );
-      console.log(`\n${deviceAuth.verification_uri_complete}\n`);
-      console.log('Waiting for authorization to complete...\n');
-    };
-
     // Always show the fallback message in non-interactive environments to ensure
     // users can see the authorization URL even if browser launching is attempted.
     // This is critical for headless/remote environments where browser launching
     // may silently fail without throwing an error.
-    if (config.isBrowserLaunchSuppressed()) {
-      // Browser launch is suppressed, show fallback message
-      showFallbackMessage();
-    } else {
-      // Try to open the URL in browser, but always show the URL as fallback
-      // to handle cases where browser launch silently fails (e.g., headless servers)
-      showFallbackMessage();
-      try {
-        const childProcess = await open(deviceAuth.verification_uri_complete);
+    showFallbackMessage(deviceAuth.verification_uri_complete);
 
-        // IMPORTANT: Attach an error handler to the returned child process.
-        // Without this, if `open` fails to spawn a process (e.g., `xdg-open` is not found
-        // in a minimal Docker container), it will emit an unhandled 'error' event,
-        // causing the entire Node.js process to crash.
-        if (childProcess) {
-          childProcess.on('error', (err) => {
-            console.debug(
-              'Browser launch failed:',
-              err.message || 'Unknown error',
-            );
-          });
-        }
-      } catch (err) {
-        console.debug(
-          'Failed to open browser:',
-          err instanceof Error ? err.message : 'Unknown error',
-        );
-      }
+    // Try to open browser if not suppressed
+    if (!config.isBrowserLaunchSuppressed()) {
+      await launchBrowser(deviceAuth.verification_uri_complete);
     }
 
-    // Emit auth progress event
-    qwenOAuth2Events.emit(
-      QwenOAuth2Event.AuthProgress,
-      'polling',
-      'Waiting for authorization...',
-    );
-
+    emitAuthProgress('polling', 'Waiting for authorization...');
     console.debug('Waiting for authorization...\n');
 
     // Poll for the token
@@ -653,11 +762,9 @@ async function authWithQwenDeviceFlow(
 
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       // Check if authentication was cancelled
-      if (isCancelled) {
-        const message = 'Authentication cancelled by user.';
-        console.debug('\n' + message);
-        qwenOAuth2Events.emit(QwenOAuth2Event.AuthProgress, 'error', message);
-        return { success: false, reason: 'cancelled', message };
+      const cancellationResult = checkCancellation();
+      if (cancellationResult) {
+        return cancellationResult;
       }
 
       try {
@@ -700,9 +807,7 @@ async function authWithQwenDeviceFlow(
             // minimal stub; cache invalidation is best-effort and should not break auth.
           }
 
-          // Emit auth progress success event
-          qwenOAuth2Events.emit(
-            QwenOAuth2Event.AuthProgress,
+          emitAuthProgress(
             'success',
             'Authentication successful! Access token obtained.',
           );
@@ -725,9 +830,7 @@ async function authWithQwenDeviceFlow(
             pollInterval = 2000; // Reset to default interval
           }
 
-          // Emit polling progress event
-          qwenOAuth2Events.emit(
-            QwenOAuth2Event.AuthProgress,
+          emitAuthProgress(
             'polling',
             `Polling... (attempt ${attempt + 1}/${maxAttempts})`,
           );
@@ -757,15 +860,9 @@ async function authWithQwenDeviceFlow(
           });
 
           // Check for cancellation after waiting
-          if (isCancelled) {
-            const message = 'Authentication cancelled by user.';
-            console.debug('\n' + message);
-            qwenOAuth2Events.emit(
-              QwenOAuth2Event.AuthProgress,
-              'error',
-              message,
-            );
-            return { success: false, reason: 'cancelled', message };
+          const cancellationResult = checkCancellation();
+          if (cancellationResult) {
+            return cancellationResult;
           }
 
           continue;
@@ -793,15 +890,17 @@ async function authWithQwenDeviceFlow(
           message: string,
           eventType: 'error' | 'rate_limit' = 'error',
         ): AuthResult => {
-          qwenOAuth2Events.emit(
-            QwenOAuth2Event.AuthProgress,
-            eventType,
-            message,
-          );
+          emitAuthProgress(eventType, message);
           console.error('\n' + message);
           return { success: false, reason, message };
         };
 
+        // Check for cancellation first
+        const cancellationResult = checkCancellation();
+        if (cancellationResult) {
+          return cancellationResult;
+        }
+
         // Handle credential caching failures - stop polling immediately
         if (errorMessage.includes('Failed to cache credentials')) {
           return handleError('error', errorMessage);
@@ -825,26 +924,14 @@ async function authWithQwenDeviceFlow(
         }
 
         const message = `Error polling for token: ${errorMessage}`;
-        qwenOAuth2Events.emit(QwenOAuth2Event.AuthProgress, 'error', message);
-
-        if (isCancelled) {
-          const message = 'Authentication cancelled by user.';
-          return { success: false, reason: 'cancelled', message };
-        }
+        emitAuthProgress('error', message);
 
         await new Promise((resolve) => setTimeout(resolve, pollInterval));
       }
     }
 
     const timeoutMessage = 'Authorization timeout, please restart the process.';
-
-    // Emit timeout error event
-    qwenOAuth2Events.emit(
-      QwenOAuth2Event.AuthProgress,
-      'timeout',
-      timeoutMessage,
-    );
-
+    emitAuthProgress('timeout', timeoutMessage);
     console.error('\n' + timeoutMessage);
     return { success: false, reason: 'timeout', message: timeoutMessage };
   } catch (error: unknown) {
@@ -853,7 +940,7 @@ async function authWithQwenDeviceFlow(
     });
     const message = `Device authorization flow failed: ${fullErrorMessage}`;
 
-    qwenOAuth2Events.emit(QwenOAuth2Event.AuthProgress, 'error', message);
+    emitAuthProgress('error', message);
     console.error(message);
     return { success: false, reason: 'error', message };
   } finally {

packages/sdk-typescript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qwen-code/sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "TypeScript SDK for programmatic access to qwen-code CLI",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",