@qwen-code/sdk 0.1.5 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +48 -9
- package/dist/cli/cli.js +329861 -290367
- package/dist/cli/locales/de.js +1951 -0
- package/dist/cli/locales/en.js +1992 -0
- package/dist/cli/locales/ja.js +1444 -0
- package/dist/cli/locales/pt.js +1941 -0
- package/dist/cli/locales/ru.js +1948 -0
- package/dist/cli/locales/zh.js +1798 -0
- package/dist/cli/vendor/tree-sitter/tree-sitter-bash.wasm +0 -0
- package/dist/cli/vendor/tree-sitter/tree-sitter.wasm +0 -0
- package/dist/index.cjs +3 -3
- package/dist/index.d.ts +15 -0
- package/dist/index.mjs +5 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -60,19 +60,23 @@ Creates a new query session with the Qwen Code.
|
|
|
60
60
|
| `permissionMode` | `'default' \| 'plan' \| 'auto-edit' \| 'yolo'` | `'default'` | Permission mode controlling tool execution approval. See [Permission Modes](#permission-modes) for details. |
|
|
61
61
|
| `canUseTool` | `CanUseTool` | - | Custom permission handler for tool execution approval. Invoked when a tool requires confirmation. Must respond within 60 seconds or the request will be auto-denied. See [Custom Permission Handler](#custom-permission-handler). |
|
|
62
62
|
| `env` | `Record<string, string>` | - | Environment variables to pass to the Qwen Code process. Merged with the current process environment. |
|
|
63
|
+
| `systemPrompt` | `string \| QuerySystemPromptPreset` | - | System prompt configuration for the main session. Use a string to fully override the built-in Qwen Code system prompt, or a preset object to keep the built-in prompt and append extra instructions. |
|
|
63
64
|
| `mcpServers` | `Record<string, McpServerConfig>` | - | MCP (Model Context Protocol) servers to connect. Supports external servers (stdio/SSE/HTTP) and SDK-embedded servers. External servers are configured with transport options like `command`, `args`, `url`, `httpUrl`, etc. SDK servers use `{ type: 'sdk', name: string, instance: Server }`. |
|
|
64
65
|
| `abortController` | `AbortController` | - | Controller to cancel the query session. Call `abortController.abort()` to terminate the session and cleanup resources. |
|
|
65
66
|
| `debug` | `boolean` | `false` | Enable debug mode for verbose logging from the CLI process. |
|
|
66
67
|
| `maxSessionTurns` | `number` | `-1` (unlimited) | Maximum number of conversation turns before the session automatically terminates. A turn consists of a user message and an assistant response. |
|
|
67
|
-
| `coreTools` | `string[]` | - | Equivalent to `
|
|
68
|
-
| `excludeTools` | `string[]` | - | Equivalent to `
|
|
69
|
-
| `allowedTools` | `string[]` | - | Equivalent to `
|
|
68
|
+
| `coreTools` | `string[]` | - | Equivalent to `permissions.allow` in settings.json as an allowlist. If specified, only these tools will be available to the AI (all other tools are disabled at registry level). Supports tool name aliases and pattern matching. Example: `['Read', 'Edit', 'Bash(git *)']`. |
|
|
69
|
+
| `excludeTools` | `string[]` | - | Equivalent to `permissions.deny` in settings.json. Excluded tools return a permission error immediately. Takes highest priority over all other permission settings. Supports tool name aliases and pattern matching: tool name (`'write_file'`), shell command prefix (`'Bash(rm *)'`), or path patterns (`'Read(.env)'`, `'Edit(/src/**)'`). |
|
|
70
|
+
| `allowedTools` | `string[]` | - | Equivalent to `permissions.allow` in settings.json. Matching tools bypass `canUseTool` callback and execute automatically. Only applies when tool requires confirmation. Supports same pattern matching as `excludeTools`. Example: `['ShellTool(git status)', 'ShellTool(npm test)']`. |
|
|
70
71
|
| `authType` | `'openai' \| 'qwen-oauth'` | `'openai'` | Authentication type for the AI service. Using `'qwen-oauth'` in SDK is not recommended as credentials are stored in `~/.qwen` and may need periodic refresh. |
|
|
71
72
|
| `agents` | `SubagentConfig[]` | - | Configuration for subagents that can be invoked during the session. Subagents are specialized AI agents for specific tasks or domains. |
|
|
72
73
|
| `includePartialMessages` | `boolean` | `false` | When `true`, the SDK emits incomplete messages as they are being generated, allowing real-time streaming of the AI's response. |
|
|
73
74
|
| `resume` | `string` | - | Resume a previous session by providing its session ID. Equivalent to CLI's `--resume` flag. |
|
|
74
75
|
| `sessionId` | `string` | - | Specify a session ID for the new session. Ensures SDK and CLI use the same ID without resuming history. Equivalent to CLI's `--session-id` flag. |
|
|
75
76
|
|
|
77
|
+
> [!tip]
|
|
78
|
+
> If you need to configure `coreTools`, `excludeTools`, or `allowedTools`, it is **strongly recommended** to read the [permissions configuration documentation](../docs/users/configuration/settings.md#permissions) first, especially the **Tool name aliases** and **Rule syntax examples** sections, to understand the available aliases and pattern matching syntax (e.g., `Bash(git *)`, `Read(.env)`, `Edit(/src/**)`).
|
|
79
|
+
|
|
76
80
|
### Timeouts
|
|
77
81
|
|
|
78
82
|
The SDK enforces the following default timeouts:
|
|
@@ -156,12 +160,17 @@ The SDK supports different permission modes for controlling tool execution:
|
|
|
156
160
|
|
|
157
161
|
### Permission Priority Chain
|
|
158
162
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
163
|
+
Decision priority (highest first): `deny` > `ask` > `allow` > _(default/interactive mode)_
|
|
164
|
+
|
|
165
|
+
The first matching rule wins.
|
|
166
|
+
|
|
167
|
+
1. `excludeTools` / `permissions.deny` - Blocks tools completely (returns permission error)
|
|
168
|
+
2. `permissions.ask` - Always requires user confirmation
|
|
169
|
+
3. `permissionMode: 'plan'` - Blocks all non-read-only tools
|
|
170
|
+
4. `permissionMode: 'yolo'` - Auto-approves all tools
|
|
171
|
+
5. `allowedTools` / `permissions.allow` - Auto-approves matching tools
|
|
172
|
+
6. `canUseTool` callback - Custom approval logic (if provided, not called for allowed tools)
|
|
173
|
+
7. Default behavior - Auto-deny in SDK mode (write tools require explicit approval)
|
|
165
174
|
|
|
166
175
|
## Examples
|
|
167
176
|
|
|
@@ -247,6 +256,36 @@ const result = query({
|
|
|
247
256
|
});
|
|
248
257
|
```
|
|
249
258
|
|
|
259
|
+
### Override the System Prompt
|
|
260
|
+
|
|
261
|
+
```typescript
|
|
262
|
+
import { query } from '@qwen-code/sdk';
|
|
263
|
+
|
|
264
|
+
const result = query({
|
|
265
|
+
prompt: 'Say hello in one sentence.',
|
|
266
|
+
options: {
|
|
267
|
+
systemPrompt: 'You are a terse assistant. Answer in exactly one sentence.',
|
|
268
|
+
},
|
|
269
|
+
});
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
### Append to the Built-in System Prompt
|
|
273
|
+
|
|
274
|
+
```typescript
|
|
275
|
+
import { query } from '@qwen-code/sdk';
|
|
276
|
+
|
|
277
|
+
const result = query({
|
|
278
|
+
prompt: 'Review the current directory.',
|
|
279
|
+
options: {
|
|
280
|
+
systemPrompt: {
|
|
281
|
+
type: 'preset',
|
|
282
|
+
preset: 'qwen_code',
|
|
283
|
+
append: 'Be terse and focus on concrete findings.',
|
|
284
|
+
},
|
|
285
|
+
},
|
|
286
|
+
});
|
|
287
|
+
```
|
|
288
|
+
|
|
250
289
|
### With SDK-Embedded MCP Servers
|
|
251
290
|
|
|
252
291
|
The SDK provides `tool` and `createSdkMcpServer` to create MCP servers that run in the same process as your SDK application. This is useful when you want to expose custom tools to the AI without running a separate server process.
|