@mmmbuto/qwen-code-termux 0.12.0-termux → 0.14.0-termux

package/bundled/qc-helper/docs/extension/getting-started-extensions.md

@@ -0,0 +1,299 @@
+# Getting Started with Qwen Code Extensions
+
+This guide will walk you through creating your first Qwen Code extension. You'll learn how to set up a new extension, add a custom tool via an MCP server, create a custom command, and provide context to the model with a `QWEN.md` file.
+
+## Prerequisites
+
+Before you start, make sure you have the Qwen Code installed and a basic understanding of Node.js and TypeScript.
+
+## Step 1: Create a New Extension
+
+The easiest way to start is by using one of the built-in templates. We'll use the `mcp-server` example as our foundation.
+
+Run the following command to create a new directory called `my-first-extension` with the template files:
+
+```bash
+qwen extensions new my-first-extension mcp-server
+```
+
+This will create a new directory with the following structure:
+
+```
+my-first-extension/
+├── example.ts
+├── qwen-extension.json
+├── package.json
+└── tsconfig.json
+```
+
+## Step 2: Understand the Extension Files
+
+Let's look at the key files in your new extension.
+
+### `qwen-extension.json`
+
+This is the manifest file for your extension. It tells Qwen Code how to load and use your extension.
+
+```json
+{
+  "name": "my-first-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "nodeServer": {
+      "command": "node",
+      "args": ["${extensionPath}${/}dist${/}example.js"],
+      "cwd": "${extensionPath}"
+    }
+  }
+}
+```
+
+- `name`: The unique name for your extension.
+- `version`: The version of your extension.
+- `mcpServers`: This section defines one or more Model Context Protocol (MCP) servers. MCP servers are how you can add new tools for the model to use.
+  - `command`, `args`, `cwd`: These fields specify how to start your server. Notice the use of the `${extensionPath}` variable, which Qwen Code replaces with the absolute path to your extension's installation directory. This allows your extension to work regardless of where it's installed.
+
+### `example.ts`
+
+This file contains the source code for your MCP server. It's a simple Node.js server that uses the `@modelcontextprotocol/sdk`.
+
+```typescript
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new McpServer({
+  name: 'prompt-server',
+  version: '1.0.0',
+});
+
+// Registers a new tool named 'fetch_posts'
+server.registerTool(
+  'fetch_posts',
+  {
+    description: 'Fetches a list of posts from a public API.',
+    inputSchema: z.object({}).shape,
+  },
+  async () => {
+    const apiResponse = await fetch(
+      'https://jsonplaceholder.typicode.com/posts',
+    );
+    const posts = await apiResponse.json();
+    const response = { posts: posts.slice(0, 5) };
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response),
+        },
+      ],
+    };
+  },
+);
+
+// ... (prompt registration omitted for brevity)
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+This server defines a single tool called `fetch_posts` that fetches data from a public API.
+
+### `package.json` and `tsconfig.json`
+
+These are standard configuration files for a TypeScript project. The `package.json` file defines dependencies and a `build` script, and `tsconfig.json` configures the TypeScript compiler.
+
+## Step 3: Build and Link Your Extension
+
+Before you can use the extension, you need to compile the TypeScript code and link the extension to your Qwen Code installation for local development.
+
+1.  **Install dependencies:**
+
+    ```bash
+    cd my-first-extension
+    npm install
+    ```
+
+2.  **Build the server:**
+
+    ```bash
+    npm run build
+    ```
+
+    This will compile `example.ts` into `dist/example.js`, which is the file referenced in your `qwen-extension.json`.
+
+3.  **Link the extension:**
+
+    The `link` command creates a symbolic link from the Qwen Code extensions directory to your development directory. This means any changes you make will be reflected immediately without needing to reinstall.
+
+    ```bash
+    qwen extensions link .
+    ```
+
+Now, restart your Qwen Code session. The new `fetch_posts` tool will be available. You can test it by asking: "fetch posts".
+
+## Step 4: Add a Custom Command
+
+Custom commands provide a way to create shortcuts for complex prompts. Let's add a command that searches for a pattern in your code.
+
+1.  Create a `commands` directory and a subdirectory for your command group:
+
+    ```bash
+    mkdir -p commands/fs
+    ```
+
+2.  Create a file named `commands/fs/grep-code.md`:
+
+    ```markdown
+    ---
+    description: Search for a pattern in code and summarize findings
+    ---
+
+    Please summarize the findings for the pattern `{{args}}`.
+
+    Search Results:
+    !{grep -r {{args}} .}
+    ```
+
+    This command, `/fs:grep-code`, will take an argument, run the `grep` shell command with it, and pipe the results into a prompt for summarization.
+
+> **Note:** Commands use Markdown format with optional YAML frontmatter. TOML format is deprecated but still supported for backwards compatibility.
+
+After saving the file, restart the Qwen Code. You can now run `/fs:grep-code "some pattern"` to use your new command.
+
+## Step 5: Add Custom Skills and Subagents (Optional)
+
+Extensions can also provide custom skills and subagents to extend Qwen Code's capabilities.
+
+### Adding a Custom Skill
+
+Skills are model-invoked capabilities that the AI can automatically use when relevant.
+
+1.  Create a `skills` directory with a skill subdirectory:
+
+    ```bash
+    mkdir -p skills/code-analyzer
+    ```
+
+2.  Create a `skills/code-analyzer/SKILL.md` file:
+
+    ```markdown
+    ---
+    name: code-analyzer
+    description: Analyzes code structure and provides insights about complexity, dependencies, and potential improvements
+    ---
+
+    # Code Analyzer
+
+    ## Instructions
+
+    When analyzing code, focus on:
+
+    - Code complexity and maintainability
+    - Dependencies and coupling
+    - Potential performance issues
+    - Suggestions for improvements
+
+    ## Examples
+
+    - "Analyze the complexity of this function"
+    - "What are the dependencies of this module?"
+    ```
+
+### Adding a Custom Subagent
+
+Subagents are specialized AI assistants for specific tasks.
+
+1.  Create an `agents` directory:
+
+    ```bash
+    mkdir -p agents
+    ```
+
+2.  Create an `agents/refactoring-expert.md` file:
+
+    ```markdown
+    ---
+    name: refactoring-expert
+    description: Specialized in code refactoring, improving code structure and maintainability
+    tools:
+      - read_file
+      - write_file
+      - read_many_files
+    ---
+
+    You are a refactoring specialist focused on improving code quality.
+
+    Your expertise includes:
+
+    - Identifying code smells and anti-patterns
+    - Applying SOLID principles
+    - Improving code readability and maintainability
+    - Safe refactoring with minimal risk
+
+    For each refactoring task:
+
+    1. Analyze the current code structure
+    2. Identify areas for improvement
+    3. Propose refactoring steps
+    4. Implement changes incrementally
+    5. Verify functionality is preserved
+    ```
+
+After restarting Qwen Code, your custom skills will be available via `/skills` and subagents via `/agents manage`.
+
+## Step 6: Add a Custom `QWEN.md`
+
+You can provide persistent context to the model by adding a `QWEN.md` file to your extension. This is useful for giving the model instructions on how to behave or information about your extension's tools. Note that you may not always need this for extensions built to expose commands and prompts.
+
+1.  Create a file named `QWEN.md` in the root of your extension directory:
+
+    ```markdown
+    # My First Extension Instructions
+
+    You are an expert developer assistant. When the user asks you to fetch posts, use the `fetch_posts` tool. Be concise in your responses.
+    ```
+
+2.  Update your `qwen-extension.json` to tell the CLI to load this file:
+
+    ```json
+    {
+      "name": "my-first-extension",
+      "version": "1.0.0",
+      "contextFileName": "QWEN.md",
+      "mcpServers": {
+        "nodeServer": {
+          "command": "node",
+          "args": ["${extensionPath}${/}dist${/}example.js"],
+          "cwd": "${extensionPath}"
+        }
+      }
+    }
+    ```
+
+Restart the CLI again. The model will now have the context from your `QWEN.md` file in every session where the extension is active.
+
+## Step 7: Releasing Your Extension
+
+Once you are happy with your extension, you can share it with others. The two primary ways of releasing extensions are via a Git repository or through GitHub Releases. Using a public Git repository is the simplest method.
+
+For detailed instructions on both methods, please refer to the [Extension Releasing Guide](extension-releasing.md).
+
+## Conclusion
+
+You've successfully created a Qwen Code extension! You learned how to:
+
+- Bootstrap a new extension from a template.
+- Add custom tools with an MCP server.
+- Create convenient custom commands.
+- Add custom skills and subagents.
+- Provide persistent context to the model.
+- Link your extension for local development.
+
+From here, you can explore more advanced features and build powerful new capabilities into the Qwen Code.

package/bundled/qc-helper/docs/extension/introduction.md

@@ -0,0 +1,338 @@
+# Qwen Code Extensions
+
+Qwen Code extensions package prompts, MCP servers, subagents, skills and custom commands into a familiar and user-friendly format. With extensions, you can expand the capabilities of Qwen Code and share those capabilities with others. They are designed to be easily installable and shareable.
+
+Extensions and plugins from [Gemini CLI Extensions Gallery](https://geminicli.com/extensions/) and [Claude Code Marketplace](https://claudemarketplaces.com/) can be directly installed into Qwen Code. This cross-platform compatibility gives you access to a rich ecosystem of extensions and plugins, dramatically expanding Qwen Code's capabilities without requiring extension authors to maintain separate versions.
+
+## Extension management
+
+We offer a suite of extension management tools using both `qwen extensions` CLI commands and `/extensions` slash commands within the interactive CLI.
+
+### Runtime Extension Management (Slash Commands)
+
+You can manage extensions at runtime within the interactive CLI using `/extensions` slash commands. These commands support hot-reloading, meaning changes take effect immediately without restarting the application.
+
+| Command                               | Description                                                                  |
+| ------------------------------------- | ---------------------------------------------------------------------------- |
+| `/extensions` or `/extensions manage` | Manage all installed extensions                                              |
+| `/extensions install <source>`        | Install an extension from a git URL, local path, npm package, or marketplace |
+| `/extensions explore [source]`        | Open extensions source page(Gemini or ClaudeCode) in your browser            |
+
+### CLI Extension Management
+
+You can also manage extensions using `qwen extensions` CLI commands. Note that changes made via CLI commands will be reflected in active CLI sessions on restart.
+
+### Installing an extension
+
+You can install an extension using `qwen extensions install` from multiple sources:
+
+#### From Claude Code Marketplace
+
+Qwen Code also supports plugins from the [Claude Code Marketplace](https://claudemarketplaces.com/). Install from a marketplace and choose a plugin:
+
+```bash
+qwen extensions install <marketplace-name>
+# or
+qwen extensions install <marketplace-github-url>
+```
+
+If you want to install a specific plugin, you can use the format with plugin name:
+
+```bash
+qwen extensions install <marketplace-name>:<plugin-name>
+# or
+qwen extensions install <marketplace-github-url>:<plugin-name>
+```
+
+For example, to install the `prompts.chat` plugin from the [f/awesome-chatgpt-prompts](https://claudemarketplaces.com/plugins/f-awesome-chatgpt-prompts) marketplace:
+
+```bash
+qwen extensions install f/awesome-chatgpt-prompts:prompts.chat
+# or
+qwen extensions install https://github.com/f/awesome-chatgpt-prompts:prompts.chat
+```
+
+Claude plugins are automatically converted to Qwen Code format during installation:
+
+- `claude-plugin.json` is converted to `qwen-extension.json`
+- Agent configurations are converted to Qwen subagent format
+- Skill configurations are converted to Qwen skill format
+- Tool mappings are automatically handled
+
+You can quickly browse available extensions from different marketplaces using the `/extensions explore` command:
+
+```bash
+# Open Gemini CLI Extensions marketplace
+/extensions explore Gemini
+
+# Open Claude Code marketplace
+/extensions explore ClaudeCode
+```
+
+This command opens the respective marketplace in your default browser, allowing you to discover new extensions to enhance your Qwen Code experience.
+
+> **Cross-Platform Compatibility**: This allows you to leverage the rich extension ecosystems from both Gemini CLI and Claude Code, dramatically expanding the available functionality for Qwen Code users.
+
+#### From Gemini CLI Extensions
+
+Qwen Code fully supports extensions from the [Gemini CLI Extensions Gallery](https://geminicli.com/extensions/). Simply install them using the git URL:
+
+```bash
+qwen extensions install <gemini-cli-extension-github-url>
+# or
+qwen extensions install <owner>/<repo>
+```
+
+Gemini extensions are automatically converted to Qwen Code format during installation:
+
+- `gemini-extension.json` is converted to `qwen-extension.json`
+- TOML command files are automatically migrated to Markdown format
+- MCP servers, context files, and settings are preserved
+
+#### From npm Registry
+
+Qwen Code supports installing extensions from npm registries using scoped package names. This is ideal for teams with private registries that already have auth, versioning, and publishing infrastructure in place.
+
+```bash
+# Install the latest version
+qwen extensions install @scope/my-extension
+
+# Install a specific version
+qwen extensions install @scope/my-extension@1.2.0
+
+# Install from a custom registry
+qwen extensions install @scope/my-extension --registry https://your-registry.com
+```
+
+Only scoped packages (`@scope/package-name`) are supported to avoid ambiguity with the `owner/repo` GitHub shorthand format.
+
+**Registry resolution** follows this priority:
+
+1. `--registry` CLI flag (explicit override)
+2. Scoped registry from `.npmrc` (e.g. `@scope:registry=https://...`)
+3. Default registry from `.npmrc`
+4. Fallback: `https://registry.npmjs.org/`
+
+**Authentication** is handled automatically via the `NPM_TOKEN` environment variable or registry-specific `_authToken` entries in your `.npmrc` file.
+
+> **Note:** npm extensions must include a `qwen-extension.json` file at the package root, following the same format as any other Qwen Code extension. See [Extension Releasing](./extension-releasing.md#releasing-through-npm-registry) for packaging details.
+
+#### From Git Repository
+
+```bash
+qwen extensions install https://github.com/github/github-mcp-server
+```
+
+This will install the github mcp server extension.
+
+#### From Local Path
+
+```bash
+qwen extensions install /path/to/your/extension
+```
+
+Note that we create a copy of the installed extension, so you will need to run `qwen extensions update` to pull in changes from both locally-defined extensions and those on GitHub.
+
+### Uninstalling an extension
+
+To uninstall, run `qwen extensions uninstall extension-name`, so, in the case of the install example:
+
+```
+qwen extensions uninstall qwen-cli-security
+```
+
+### Disabling an extension
+
+Extensions are, by default, enabled across all workspaces. You can disable an extension entirely or for specific workspace.
+
+For example, `qwen extensions disable extension-name` will disable the extension at the user level, so it will be disabled everywhere. `qwen extensions disable extension-name --scope=workspace` will only disable the extension in the current workspace.
+
+### Enabling an extension
+
+You can enable extensions using `qwen extensions enable extension-name`. You can also enable an extension for a specific workspace using `qwen extensions enable extension-name --scope=workspace` from within that workspace.
+
+This is useful if you have an extension disabled at the top-level and only enabled in specific places.
+
+### Updating an extension
+
+For extensions installed from a local path, a git repository, or an npm registry, you can explicitly update to the latest version with `qwen extensions update extension-name`. For npm extensions installed without a version pin (e.g. `@scope/pkg`), updates check the `latest` dist-tag. For those installed with a specific dist-tag (e.g. `@scope/pkg@beta`), updates track that tag. Extensions pinned to an exact version (e.g. `@scope/pkg@1.2.0`) are always considered up-to-date.
+
+You can update all extensions with:
+
+```
+qwen extensions update --all
+```
+
+## How it works
+
+On startup, Qwen Code looks for extensions in `<home>/.qwen/extensions`
+
+Extensions exist as a directory that contains a `qwen-extension.json` file. For example:
+
+`<home>/.qwen/extensions/my-extension/qwen-extension.json`
+
+### `qwen-extension.json`
+
+The `qwen-extension.json` file contains the configuration for the extension. The file has the following structure:
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "my-server": {
+      "command": "node my-server.js"
+    }
+  },
+  "channels": {
+    "my-platform": {
+      "entry": "dist/index.js",
+      "displayName": "My Platform Channel"
+    }
+  },
+  "contextFileName": "QWEN.md",
+  "commands": "commands",
+  "skills": "skills",
+  "agents": "agents",
+  "settings": [
+    {
+      "name": "API Key",
+      "description": "Your API key for the service",
+      "envVar": "MY_API_KEY",
+      "sensitive": true
+    }
+  ]
+}
+```
+
+- `name`: The name of the extension. This is used to uniquely identify the extension and for conflict resolution when extension commands have the same name as user or project commands. The name should be lowercase or numbers and use dashes instead of underscores or spaces. This is how users will refer to your extension in the CLI. Note that we expect this name to match the extension directory name.
+- `version`: The version of the extension.
+- `mcpServers`: A map of MCP servers to configure. The key is the name of the server, and the value is the server configuration. These servers will be loaded on startup just like MCP servers configured in a [`settings.json` file](./cli/configuration.md). If both an extension and a `settings.json` file configure an MCP server with the same name, the server defined in the `settings.json` file takes precedence.
+  - Note that all MCP server configuration options are supported except for `trust`.
+- `channels`: A map of custom channel adapters. The key is the channel type name, and the value has an `entry` (path to compiled JS entry point) and optional `displayName`. The entry point must export a `plugin` object conforming to the `ChannelPlugin` interface. See [Channel Plugins](../features/channels/plugins) for a full guide.
+- `contextFileName`: The name of the file that contains the context for the extension. This will be used to load the context from the extension directory. If this property is not used but a `QWEN.md` file is present in your extension directory, then that file will be loaded.
+- `commands`: The directory containing custom commands (default: `commands`). Commands are `.md` files that define prompts.
+- `skills`: The directory containing custom skills (default: `skills`). Skills are discovered automatically and become available via the `/skills` command.
+- `agents`: The directory containing custom subagents (default: `agents`). Subagents are `.yaml` or `.md` files that define specialized AI assistants.
+- `settings`: An array of settings that the extension requires. When installing, users will be prompted to provide values for these settings. The values are stored securely and passed to MCP servers as environment variables.
+  - Each setting has the following properties:
+    - `name`: Display name for the setting
+    - `description`: A description of what this setting is used for
+    - `envVar`: The environment variable name that will be set
+    - `sensitive`: Boolean indicating if the value should be hidden (e.g., API keys, passwords)
+
+### Managing Extension Settings
+
+Extensions can require configuration through settings (such as API keys or credentials). These settings can be managed using the `qwen extensions settings` CLI command:
+
+**Set a setting value:**
+
+```bash
+qwen extensions settings set <extension-name> <setting-name> [--scope user|workspace]
+```
+
+**List all settings for an extension:**
+
+```bash
+qwen extensions settings list <extension-name>
+```
+
+**View current values (user and workspace):**
+
+```bash
+qwen extensions settings show <extension-name> <setting-name>
+```
+
+**Remove a setting value:**
+
+```bash
+qwen extensions settings unset <extension-name> <setting-name> [--scope user|workspace]
+```
+
+Settings can be configured at two levels:
+
+- **User level** (default): Settings apply across all projects (`~/.qwen/.env`)
+- **Workspace level**: Settings apply only to the current project (`.qwen/.env`)
+
+Workspace settings take precedence over user settings. Sensitive settings are stored securely and never displayed in plain text.
+
+When Qwen Code starts, it loads all the extensions and merges their configurations. If there are any conflicts, the workspace configuration takes precedence.
+
+### Custom commands
+
+Extensions can provide [custom commands](./cli/commands.md#custom-commands) by placing Markdown files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions.
+
+> **Note:** The command format has been updated from TOML to Markdown. TOML files are deprecated but still supported. You can migrate existing TOML commands using the automatic migration prompt that appears when TOML files are detected.
+
+**Example**
+
+An extension named `gcp` with the following structure:
+
+```
+.qwen/extensions/gcp/
+├── qwen-extension.json
+└── commands/
+    ├── deploy.md
+    └── gcs/
+        └── sync.md
+```
+
+Would provide these commands:
+
+- `/deploy` - Shows as `[gcp] Custom command from deploy.md` in help
+- `/gcs:sync` - Shows as `[gcp] Custom command from sync.md` in help
+
+### Custom skills
+
+Extensions can provide custom skills by placing skill files in a `skills/` subdirectory within the extension directory. Each skill should have a `SKILL.md` file with YAML frontmatter defining the skill's name and description.
+
+**Example**
+
+```
+.qwen/extensions/my-extension/
+├── qwen-extension.json
+└── skills/
+    └── pdf-processor/
+        └── SKILL.md
+```
+
+The skill will be available via the `/skills` command when the extension is active.
+
+### Custom subagents
+
+Extensions can provide custom subagents by placing agent configuration files in an `agents/` subdirectory within the extension directory. Agents are defined using YAML or Markdown files.
+
+**Example**
+
+```
+.qwen/extensions/my-extension/
+├── qwen-extension.json
+└── agents/
+    └── testing-expert.yaml
+```
+
+Extension subagents appear in the subagent manager dialog under "Extension Agents" section.
+
+### Conflict resolution
+
+Extension commands have the lowest precedence. When a conflict occurs with user or project commands:
+
+1. **No conflict**: Extension command uses its natural name (e.g., `/deploy`)
+2. **With conflict**: Extension command is renamed with the extension prefix (e.g., `/gcp.deploy`)
+
+For example, if both a user and the `gcp` extension define a `deploy` command:
+
+- `/deploy` - Executes the user's deploy command
+- `/gcp.deploy` - Executes the extension's deploy command (marked with `[gcp]` tag)
+
+## Variables
+
+Qwen Code extensions allow variable substitution in `qwen-extension.json`. This can be useful if e.g., you need the current directory to run an MCP server using `"cwd": "${extensionPath}${/}run.ts"`.
+
+**Supported variables:**
+
+| variable                   | description                                                                                                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `${extensionPath}`         | The fully-qualified path of the extension in the user's filesystem e.g., '/Users/username/.qwen/extensions/example-extension'. This will not unwrap symlinks. |
+| `${workspacePath}`         | The fully-qualified path of the current workspace.                                                                                                            |
+| `${/} or ${pathSeparator}` | The path separator (differs per OS).                                                                                                                          |

package/bundled/qc-helper/docs/features/_meta.ts

@@ -0,0 +1,19 @@
+export default {
+  commands: 'Commands',
+  'sub-agents': 'SubAgents',
+  arena: 'Agent Arena',
+  skills: 'Skills',
+  headless: 'Headless Mode',
+  checkpointing: {
+    display: 'hidden',
+  },
+  'approval-mode': 'Approval Mode',
+  mcp: 'MCP',
+  lsp: 'LSP (Language Server Protocol)',
+  'token-caching': 'Token Caching',
+  sandbox: 'Sandboxing',
+  language: 'i18n',
+  channels: 'Channels',
+  hooks: 'Hooks',
+  'scheduled-tasks': 'Scheduled Tasks',
+};