@qwen-code/qwen-code 0.15.11 → 0.15.12-preview.1

package/README.md

@@ -428,12 +428,13 @@ and adjust it to the context length configured on your local server.
 
 ## Usage
 
-As an open-source terminal agent, you can use Qwen Code in four primary ways:
+As an open-source terminal agent, you can use Qwen Code in five primary ways:
 
 1. Interactive mode (terminal UI)
 2. Headless mode (scripts, CI)
 3. IDE integration (VS Code, Zed)
 4. SDKs (TypeScript, Python, Java)
+5. Daemon mode — `qwen serve` exposes ACP over HTTP+SSE so multiple clients share one agent (experimental)
 
 #### Interactive mode
 
@@ -461,6 +462,20 @@ Use Qwen Code inside your editor (VS Code, Zed, and JetBrains IDEs):
 - [Use in Zed](https://qwenlm.github.io/qwen-code-docs/en/users/integration-zed/)
 - [Use in JetBrains IDEs](https://qwenlm.github.io/qwen-code-docs/en/users/integration-jetbrains/)
 
+#### Daemon mode (`qwen serve`, experimental)
+
+```bash
+cd your-project/
+qwen serve
+# → qwen serve listening on http://127.0.0.1:4170 (mode=http-bridge)
+```
+
+Run Qwen Code as a local HTTP daemon so IDE plugins, web UIs, CI scripts and custom CLIs all share **one** agent session over HTTP+SSE — instead of each spawning their own subprocess. Loopback bind has no auth by default (set `QWEN_SERVER_TOKEN` to enable bearer auth even on loopback); remote binds (`--hostname 0.0.0.0`) **require** a token — boot refuses without one. See:
+
+- [Daemon mode user guide](https://qwenlm.github.io/qwen-code-docs/en/users/qwen-serve)
+- [HTTP protocol reference](https://qwenlm.github.io/qwen-code-docs/en/developers/qwen-serve-protocol)
+- [DaemonClient TypeScript quickstart](https://qwenlm.github.io/qwen-code-docs/en/developers/examples/daemon-client-quickstart)
+
 #### SDKs
 
 Build on top of Qwen Code with the available SDKs:

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

@@ -13,7 +13,8 @@ export default {
   'integration-vscode': 'Visual Studio Code',
   'integration-zed': 'Zed IDE',
   'integration-jetbrains': 'JetBrains IDEs',
-  'integration-github-action': 'Github Actions',
+  'integration-github-action': 'GitHub Actions',
+  'qwen-serve': 'Daemon mode (qwen serve)',
   'Code with Qwen Code': {
     type: 'separator',
     title: 'Code with Qwen Code', // Title is optional

package/bundled/qc-helper/docs/configuration/settings.md

@@ -583,11 +583,16 @@ For authentication-related variables (like `OPENAI_*`) and the recommended `.qwe
 | `SEATBELT_PROFILE`                                 | (macOS specific) Switches the Seatbelt (`sandbox-exec`) profile on macOS.                                                                                                                                                                                                         | `permissive-open`: (Default) Restricts writes to the project folder (and a few other folders, see `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) but allows other operations. `strict`: Uses a strict profile that declines operations by default. `<profile_name>`: Uses a custom profile. To define a custom profile, create a file named `sandbox-macos-<profile_name>.sb` in your project's `.qwen/` directory (e.g., `my-project/.qwen/sandbox-macos-custom.sb`). |
 | `DEBUG` or `DEBUG_MODE`                            | (often used by underlying libraries or the CLI itself) Set to `true` or `1` to enable verbose debug logging, which can be helpful for troubleshooting.                                                                                                                            | **Note:** These variables are automatically excluded from project `.env` files by default to prevent interference with the CLI behavior. Use `.qwen/.env` files if you need to set these for Qwen Code specifically.                                                                                                                                                                                                                                                               |
 | `NO_COLOR`                                         | Set to any value to disable all color output in the CLI.                                                                                                                                                                                                                          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `FORCE_HYPERLINK`                                  | Override the OSC 8 clickable-link detection in the markdown renderer. Set to `1` (or any non-zero value, or empty string) to force-enable, `0` to force-disable. Honors `NO_COLOR` / `QWEN_DISABLE_HYPERLINKS` opt-outs above it.                                                 | Use this to opt into OSC 8 inside `tmux` / GNU `screen` (auto-detection refuses by default because the host terminal's capabilities are hidden behind the multiplexer). Requires `set -g allow-passthrough on` on tmux 3.3+. Also enables Hyper, which isn't auto-detected.                                                                                                                                                                                                        |
+| `QWEN_DISABLE_HYPERLINKS`                          | Set to `1` to hard-disable OSC 8 clickable hyperlinks in the markdown renderer even on terminals that auto-detect as capable.                                                                                                                                                     | Useful when a terminal advertises support but breaks on long URLs, or when piping output through an intermediary that mangles escape sequences. The renderer falls back to plain `label (url)` rendering.                                                                                                                                                                                                                                                                          |
 | `CLI_TITLE`                                        | Set to a string to customize the title of the CLI.                                                                                                                                                                                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `CODE_ASSIST_ENDPOINT`                             | Specifies the endpoint for the code assist server.                                                                                                                                                                                                                                | This is useful for development and testing.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `QWEN_CODE_MAX_OUTPUT_TOKENS`                      | Overrides the default maximum output tokens per response. When not set, Qwen Code uses an adaptive strategy: starts with 8K tokens and automatically retries with 64K if the response is truncated. Set this to a specific value (e.g., `16000`) to use a fixed limit instead.    | Takes precedence over the capped default (8K) but is overridden by `samplingParams.max_tokens` in settings. Disables automatic escalation when set. Example: `export QWEN_CODE_MAX_OUTPUT_TOKENS=16000`                                                                                                                                                                                                                                                                            |
 | `QWEN_CODE_UNATTENDED_RETRY`                       | Set to `true` or `1` to enable persistent retry mode. When enabled, transient API capacity errors (HTTP 429 Rate Limit and 529 Overloaded) are retried indefinitely with exponential backoff (capped at 5 minutes per retry) and heartbeat keepalives every 30 seconds on stderr. | Designed for CI/CD pipelines and background automation where long-running tasks should survive temporary API outages. Must be set explicitly — `CI=true` alone does **not** activate this mode. See [Headless Mode](../features/headless#persistent-retry-mode) for details. Example: `export QWEN_CODE_UNATTENDED_RETRY=1`                                                                                                                                                        |
-| `QWEN_CODE_PROFILE_STARTUP`                        | Set to `1` to enable startup performance profiling. Writes a JSON timing report to `~/.qwen/startup-perf/` with per-phase durations.                                                                                                                                              | Only active inside the sandbox child process. Zero overhead when not set. Example: `export QWEN_CODE_PROFILE_STARTUP=1`                                                                                                                                                                                                                                                                                                                                                            |
+| `QWEN_CODE_PROFILE_STARTUP`                        | Set to `1` to enable startup performance profiling. Writes a JSON timing report to `~/.qwen/startup-perf/` with per-phase durations.                                                                                                                                              | Only active inside the sandbox child process (or with `QWEN_CODE_PROFILE_STARTUP_OUTER=1`). Zero overhead when not set. Example: `export QWEN_CODE_PROFILE_STARTUP=1`                                                                                                                                                                                                                                                                                                              |
+| `QWEN_CODE_PROFILE_STARTUP_OUTER`                  | Set to `1` together with `QWEN_CODE_PROFILE_STARTUP=1` to also collect a startup profile in the outer (pre-sandbox) process. Outer-process reports get an `outer-` filename prefix to keep them distinct from the sandbox child's report.                                         | Off by default — only the sandbox child collects, to avoid duplicate reports. Useful for local development where the cli isn't relaunched into a sandbox.                                                                                                                                                                                                                                                                                                                          |
+| `QWEN_CODE_PROFILE_STARTUP_NO_HEAP`                | Set to `1` together with `QWEN_CODE_PROFILE_STARTUP=1` to skip the per-checkpoint `process.memoryUsage()` snapshots. Useful when measuring the profiler's own Heisenberg overhead.                                                                                                | Off by default. Heap snapshots cost ~50 µs each (well below 1% of total startup) so most users should leave this alone.                                                                                                                                                                                                                                                                                                                                                            |
+| `QWEN_CODE_LEGACY_MCP_BLOCKING`                    | Set to `1` to restore the pre-progressive-MCP behavior where `Config.initialize()` waits synchronously for every configured MCP server's discover handshake before returning.                                                                                                     | Off by default. Modern qwen-code lets MCP servers come online in the background while the UI is already interactive; the model sees each batch of new tools within ~16 ms of the server settling. This flag is kept as a rollback escape hatch for ≥ 1 release. Example: `export QWEN_CODE_LEGACY_MCP_BLOCKING=1`                                                                                                                                                                  |
 
 When both user-level `.env` files define the same variable, the Qwen-specific
 file wins: `<QWEN_HOME>/.env` (or `~/.qwen/.env` when `QWEN_HOME` is unset) is

package/bundled/qc-helper/docs/features/commands.md

@@ -45,12 +45,11 @@ Commands for adjusting interface appearance and work environment.
 
 Commands specifically for controlling interface and output language.
 
-| Command               | Description                                                                 | Usage Examples             |
-| --------------------- | --------------------------------------------------------------------------- | -------------------------- |
-| `/language`           | View or change language settings                                            | `/language`                |
-| → `ui [language]`     | Set UI interface language                                                   | `/language ui zh-CN`       |
-| → `output [language]` | Set LLM output language                                                     | `/language output Chinese` |
-| → `translate on/off`  | Toggle AI translation for dynamic slash command descriptions (default: off) | `/language translate on`   |
+| Command               | Description                      | Usage Examples             |
+| --------------------- | -------------------------------- | -------------------------- |
+| `/language`           | View or change language settings | `/language`                |
+| → `ui [language]`     | Set UI interface language        | `/language ui zh-CN`       |
+| → `output [language]` | Set LLM output language          | `/language output Chinese` |
 
 - Available built-in UI languages: `zh-CN` (Simplified Chinese), `en-US` (English), `ru-RU` (Russian), `de-DE` (German), `ja-JP` (Japanese), `pt-BR` (Portuguese - Brazil), `fr-FR` (French), `ca-ES` (Catalan)
 - Output language examples: `Chinese`, `English`, `Japanese`, etc.

package/bundled/qc-helper/docs/features/hooks.md

@@ -30,13 +30,14 @@ Hooks are user-defined scripts or programs that are automatically executed by Qw
 
 ## Hook Types
 
-Qwen Code supports three hook executor types:
+Qwen Code supports four hook executor types:
 
 | Type       | Description                                                                                    |
 | :--------- | :--------------------------------------------------------------------------------------------- |
 | `command`  | Execute a shell command. Receives JSON via `stdin`, returns results via `stdout`.              |
 | `http`     | Send JSON as a `POST` request body to a specified URL. Returns results via HTTP response body. |
 | `function` | Directly call a registered JavaScript function (session-level hooks only).                     |
+| `prompt`   | Use an LLM to evaluate hook input and return a decision.                                       |
 
 ### Command Hooks
 
@@ -134,6 +135,102 @@ Function hooks directly call registered JavaScript/TypeScript functions. They ar
 
 **Note**: For most use cases, use **command hooks** or **HTTP hooks** instead, which can be configured in settings files.
 
+### Prompt Hooks
+
+Prompt hooks use an LLM to evaluate hook input and return a decision. This is useful for making intelligent decisions based on context, such as determining whether to allow or block an operation.
+
+**How it works:**
+
+1. The hook input JSON is injected into your prompt using the `$ARGUMENTS` placeholder
+2. The prompt is sent to an LLM (default: your current model)
+3. The LLM returns a JSON response with the decision
+4. Qwen Code processes the decision and continues or blocks execution accordingly
+
+**Configuration:**
+
+| Field           | Type       | Required | Description                                         |
+| :-------------- | :--------- | :------- | :-------------------------------------------------- |
+| `type`          | `"prompt"` | Yes      | Hook type                                           |
+| `prompt`        | `string`   | Yes      | Prompt sent to LLM. Use `$ARGUMENTS` for hook input |
+| `model`         | `string`   | No       | Model to use (defaults to your current model)       |
+| `timeout`       | `number`   | No       | Timeout in seconds, default 30                      |
+| `name`          | `string`   | No       | Hook name (for logging)                             |
+| `description`   | `string`   | No       | Hook description                                    |
+| `statusMessage` | `string`   | No       | Status message displayed during execution           |
+
+**Response Format:**
+
+The LLM must return JSON with the following structure:
+
+```json
+{
+  "ok": true,
+  "reason": "Explanation of the decision",
+  "additionalContext": "Optional context to inject into the conversation"
+}
+```
+
+| Field               | Description                                                                |
+| :------------------ | :------------------------------------------------------------------------- |
+| `ok`                | `true` to allow/continue, `false` to block/stop                            |
+| `reason`            | Required when `ok` is `false`. Shown to the model to explain the block     |
+| `additionalContext` | Optional. Additional context to inject into the conversation when allowing |
+
+**Supported Events:**
+
+Prompt hooks can be used with most hook events, including:
+
+- `PreToolUse` - Evaluate whether to allow a tool call
+- `PostToolUse` - Evaluate tool results and potentially inject context
+- `Stop` - Determine whether to continue or stop
+- `SubagentStop` - Evaluate subagent results
+- `UserPromptSubmit` - Evaluate or enrich user prompts
+
+**Example: Stop Hook**
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "You are evaluating whether Qwen Code should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+When `ok` is `false`, Qwen Code will continue working and use the `reason` as context for the next response.
+
+**Example: PreToolUse Hook**
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Evaluate this tool call for security concerns. Tool input: $ARGUMENTS\n\nCheck for:\n- Dangerous commands (rm -rf, curl | sh, etc.)\n- Unauthorized access attempts\n- Data exfiltration patterns\n\nRespond with {\"ok\": true} if safe, or {\"ok\": false, \"reason\": \"concern\"} if blocked.",
+            "model": "sonnet",
+            "timeout": 30,
+            "name": "security-evaluator"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
 ## Hook Events
 
 Hooks fire at specific points during a Qwen Code session. Different events support different matchers to filter trigger conditions.
@@ -152,6 +249,8 @@ Hooks fire at specific points during a Qwen Code session. Different events suppo
 | `PreCompact`         | Before conversation compaction            | Trigger (`manual`, `auto`)                                |
 | `Notification`       | When notifications are sent               | Type (`permission_prompt`, `idle_prompt`, `auth_success`) |
 | `PermissionRequest`  | When permission dialog is shown           | Tool name                                                 |
+| `TodoCreated`        | When a new todo item is created           | None (always fires)                                       |
+| `TodoCompleted`      | When a todo item is marked as completed   | None (always fires)                                       |
 
 ### Matcher Patterns
 
@@ -165,6 +264,7 @@ Hooks fire at specific points during a Qwen Code session. Different events suppo
 | Session Events      | `SessionEnd`                                                           | ✅ Regex        | Reason: `clear`, `logout`, `prompt_input_exit`, etc.     |
 | Notification Events | `Notification`                                                         | ✅ Exact match  | Type: `permission_prompt`, `idle_prompt`, `auth_success` |
 | Compact Events      | `PreCompact`                                                           | ✅ Exact match  | Trigger: `manual`, `auto`                                |
+| Todo Events         | `TodoCreated`, `TodoCompleted`                                         | ❌ No           | N/A                                                      |
 | Prompt Events       | `UserPromptSubmit`                                                     | ❌ No           | N/A                                                      |
 | Stop Events         | `Stop`                                                                 | ❌ No           | N/A                                                      |
 
@@ -754,6 +854,204 @@ Hook output supports three categories of fields:
 }
 ```
 
+#### TodoCreated
+
+**Purpose**: Executed when a new todo item is created via the `todo_write` tool. Allows validation, logging, or blocking of todo creation.
+
+Todo hooks run in two phases:
+
+- `validation`: runs before persistence. Use this phase for validation only; returning `block` or `deny` prevents the write.
+- `postWrite`: runs after persistence. Use this phase for side effects such as logging or syncing; `block` or `deny` is ignored in this phase.
+
+**Event-specific fields**:
+
+```json
+{
+  "todo_id": "unique identifier for the todo item",
+  "todo_content": "content/description of the todo item",
+  "todo_status": "pending | in_progress | completed",
+  "all_todos": "array of all todo items in the current list",
+  "phase": "validation | postWrite"
+}
+```
+
+**Output Options**:
+
+- `decision`: "allow", "block", or "deny"
+- `reason`: human-readable explanation for the decision (required when blocking)
+
+**Blocking Behavior**:
+
+During the `validation` phase, when `decision` is `block` or `deny` (exit code 2), todo creation is prevented. The todo list remains unchanged, and the reason is provided as feedback to the model.
+
+During the `postWrite` phase, the todo has already been persisted. Hooks may still return output, but `block` / `deny` does not undo the write and should not be used for validation.
+
+**Example Output (Allow)**:
+
+```json
+{
+  "decision": "allow",
+  "reason": "Todo content validated successfully"
+}
+```
+
+**Example Output (Block)**:
+
+```json
+{
+  "decision": "block",
+  "reason": "Todo content too short. Minimum 5 characters required."
+}
+```
+
+**Example Hook Script**:
+
+```bash
+#!/bin/bash
+# ~/.qwen/hooks/todo-validator.sh
+# Validates todo content before creation
+
+INPUT=$(cat)
+CONTENT=$(echo "$INPUT" | jq -r '.todo_content')
+
+# Check minimum length
+if [ ${#CONTENT} -lt 5 ]; then
+  echo '{"decision": "block", "reason": "Todo content must be at least 5 characters"}'
+  exit 2
+fi
+
+# Block test-related todos
+if [[ "$CONTENT" =~ "test" ]]; then
+  echo '{"decision": "block", "reason": "Test todos are not allowed in production"}'
+  exit 2
+fi
+
+echo '{"decision": "allow"}'
+exit 0
+```
+
+**Example Configuration**:
+
+```json
+{
+  "hooks": {
+    "TodoCreated": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.qwen/hooks/todo-validator.sh",
+            "name": "todo-validator",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### TodoCompleted
+
+**Purpose**: Executed when a todo item is marked as completed. Allows validation, logging, or blocking of todo completion.
+
+Todo hooks run in two phases:
+
+- `validation`: runs before persistence. Use this phase for validation only; returning `block` or `deny` prevents the write.
+- `postWrite`: runs after persistence. Use this phase for side effects such as logging or syncing; `block` or `deny` is ignored in this phase.
+
+**Event-specific fields**:
+
+```json
+{
+  "todo_id": "unique identifier for the todo item",
+  "todo_content": "content/description of the todo item",
+  "previous_status": "pending | in_progress (status before completion)",
+  "all_todos": "array of all todo items in the current list",
+  "phase": "validation | postWrite"
+}
+```
+
+**Output Options**:
+
+- `decision`: "allow", "block", or "deny"
+- `reason`: human-readable explanation for the decision (required when blocking)
+
+**Blocking Behavior**:
+
+During the `validation` phase, when `decision` is `block` or `deny` (exit code 2), todo completion is prevented. The todo item remains in its previous status, and the reason is provided as feedback to the model.
+
+During the `postWrite` phase, the todo has already been persisted. Hooks may still return output, but `block` / `deny` does not undo the write and should not be used for validation.
+
+**Example Output (Allow)**:
+
+```json
+{
+  "decision": "allow",
+  "reason": "Todo completion approved"
+}
+```
+
+**Example Output (Block)**:
+
+```json
+{
+  "decision": "block",
+  "reason": "Cannot complete this todo until dependent tasks are finished."
+}
+```
+
+**Example Hook Script**:
+
+```bash
+#!/bin/bash
+# ~/.qwen/hooks/todo-completion-validator.sh
+# Validates todo completion conditions
+
+INPUT=$(cat)
+TODO_ID=$(echo "$INPUT" | jq -r '.todo_id')
+ALL_TODOS=$(echo "$INPUT" | jq -r '.all_todos')
+
+# Check if there are incomplete dependent todos (example logic)
+INCOMPLETE_COUNT=$(echo "$ALL_TODOS" | jq '[.[] | select(.status != "completed")] | length')
+
+if [ "$INCOMPLETE_COUNT" -gt 5 ]; then
+  echo '{"decision": "block", "reason": "Too many incomplete todos. Complete other tasks first."}'
+  exit 2
+fi
+
+echo '{"decision": "allow"}'
+exit 0
+```
+
+**Example Configuration**:
+
+```json
+{
+  "hooks": {
+    "TodoCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOME/.qwen/hooks/todo-completion-validator.sh",
+            "name": "completion-validator",
+            "timeout": 5000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Use Cases**:
+
+- **Logging**: Track todo creation and completion for audit or analytics
+- **Validation**: Enforce content quality standards (minimum length, required keywords)
+- **Workflow Control**: Block completion until prerequisites are met
+- **Integration**: Sync todos with external task management systems (Jira, Trello, etc.)
+
 ## Hook Configuration
 
 Hooks are configured in Qwen Code settings, typically in `.qwen/settings.json` or user configuration files:

package/bundled/qc-helper/docs/features/language.md

@@ -55,22 +55,6 @@ Detection priority:
 3. System locale via JavaScript Intl API
 4. Default: English
 
-### Dynamic Command Translation
-
-Dynamic slash command descriptions from skills, extensions, file commands, and
-MCP prompts can be translated with AI. This is **off by default** to avoid
-unexpected model calls, latency, and token usage.
-
-```bash
-/language translate status  # Show current status
-/language translate on      # Enable AI translation for dynamic descriptions
-/language translate off     # Disable AI translation
-```
-
-Use `/language translate cache refresh` to re-translate cached dynamic
-descriptions after enabling translation, or `/language translate cache clear` to
-remove cached translations.
-
 ## LLM Output Language
 
 The LLM output language controls what language the AI assistant responds in, regardless of what language you type your questions in.
@@ -145,6 +129,29 @@ User directory takes precedence over built-in translations.
 > Contributions are welcome! If you’d like to improve built-in translations or add new languages.
 > For a concrete example, see [PR #1238: feat(i18n): add Russian language support](https://github.com/QwenLM/qwen-code/pull/1238).
 
+### Maintaining `zh-TW` (Traditional Chinese for Taiwan)
+
+`zh-TW` is **not** an automatic OpenCC s2t conversion of `zh.js` — it is a hand-maintained Taiwan-vocabulary translation. When adding or updating keys, please follow the conventions below.
+
+The "CI enforced?" column indicates whether `npm run check-i18n` will fail the build on a violation. Rows marked **No** are style guidance enforced by review only — typically because the offending form has a legitimate non-UI meaning (`文件` can mean "document", `打開` is colloquially fine in Taiwan).
+
+| Avoid                 | Use instead           | CI enforced? | Reason                                                                                                                                                                           |
+| --------------------- | --------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 文件 (file)           | 檔案                  | No           | Taiwan term for filesystem files (but `文件` can legitimately mean "document")                                                                                                   |
+| 服務器 / 服务器       | 伺服器                | Yes          | Taiwan term for "server"                                                                                                                                                         |
+| 菜單 / 菜单           | 選單                  | Yes          | Taiwan term for "menu"                                                                                                                                                           |
+| 鏈接 / 链接           | 連結                  | Yes          | Taiwan term for "link" (bare `鏈` is fine — e.g. 區塊鏈)                                                                                                                         |
+| 打開                  | 開啟                  | No           | Taiwan-preferred verb for "open" (UI); `打開` is colloquially common                                                                                                             |
+| 爲 / 啓 / 曆史 / 鏈接 | 為 / 啟 / 歷史 / 連結 | Yes          | Variant Traditional forms from raw OpenCC s2t. Note: `曆` is context-dependent and correct in calendar terms (日曆, 農曆, 西曆); CI only flags the bigram `曆史`, not bare `曆`. |
+
+If you are not a Traditional Chinese speaker and need to bootstrap a value, **do not paste raw OpenCC `s2t` output**: the default s2t profile emits variant Traditional characters (e.g. 爲, 啓) that Taiwan does not use, and never rewrites Mainland-Chinese vocabulary (服務器, 菜單). Prefer `s2twp.json` (Simplified → Taiwan with phrase mapping) as a starting point and then ask a Taiwan-Chinese speaker to review.
+
+The `check-i18n` script (run in CI via `npm run check-i18n`) will fail the build if any of the CI-enforced substrings above end up in a `zh-TW` value. See `scripts/check-i18n.ts → ZH_TW_FORBIDDEN_PATTERNS` for the full list. If a translation legitimately needs to contain a CI-forbidden substring, add its key to `ZH_TW_ALLOWED_EXCEPTIONS` in the same file with a brief justification.
+
+> [!note]
+>
+> The check uses plain substring matching, which does not understand Chinese word boundaries. A bigram pattern can therefore false-positive across compound-word boundaries — for example, `區塊鏈接口` (= `區塊鏈` + `接口`) contains the substring `鏈接` even though neither word is incorrect. If you hit a surprising CI failure of this kind, add the translation key to `ZH_TW_ALLOWED_EXCEPTIONS` rather than removing the pattern.
+
 ### Language Pack Format
 
 ```javascript

package/bundled/qc-helper/docs/features/mcp.md

@@ -147,6 +147,62 @@ CLI:
 qwen mcp add --transport sse sseServer http://localhost:8080/sse --timeout 30000
 ```
 
+## Progressive availability and discovery timeouts
+
+Qwen Code discovers MCP servers in the background after the UI is already
+interactive. You see the cli's first prompt within a few hundred
+milliseconds even when one of your MCP servers takes several seconds
+(or never responds), and the model's tool list updates within roughly
+one frame (~16 ms) of each server completing its discover handshake.
+
+- **Interactive mode**: the UI appears immediately; an MCP status pill in
+  the bottom-right shows `N/M MCP servers ready` while discovery is in
+  flight. Sending a prompt before MCP finishes simply means the model
+  sees the tools that are ready _at that moment_; subsequent prompts see
+  more tools as servers come online.
+- **Non-interactive mode** (`--prompt`, stream-json, ACP): the cli still
+  waits for MCP discovery to settle before sending the first prompt, so
+  scripted / piped invocations see the same complete tool set the
+  legacy synchronous behavior produced.
+
+### Per-server `discoveryTimeoutMs`
+
+Each MCP server gets a discovery-only timeout that caps how long the
+initial handshake (`connect` + `tools/list` + `prompts/list` +
+`resources/list`) is allowed to take. Defaults:
+
+- **stdio servers**: 30 s
+- **remote HTTP / SSE servers**: 5 s (network risk is higher)
+
+Override per server when needed:
+
+```jsonc
+{
+  "mcpServers": {
+    "slow-stdio": {
+      "command": "node",
+      "args": ["./slow-server.js"],
+      "discoveryTimeoutMs": 60000,
+    },
+    "flaky-remote": {
+      "httpUrl": "https://example.com/mcp",
+      "discoveryTimeoutMs": 10000,
+    },
+  },
+}
+```
+
+The existing `timeout` field is **tool-call** timeout (used for each
+`tools/call` request, default 10 minutes) and is unaffected by
+`discoveryTimeoutMs` — a long-running tool invocation is not a startup
+pathology.
+
+### Rolling back progressive MCP
+
+If you need the old synchronous behavior (cli waits for every MCP server
+before showing any UI), set `QWEN_CODE_LEGACY_MCP_BLOCKING=1` in your
+environment. This is kept as an escape hatch for at least one release.
+
 ## Safety and control
 
 ### Trust (skip confirmations)