Map top support questions to FAQ (#3384)

Co-authored-by: LauraGPT <[email protected]>

docs/community_growth_20k.md

@@ -369,7 +369,7 @@ Paste the Markdown output into launch notes, weekly community updates, or releas
 - [x] Share the release in relevant developer communities. On 2026-07-23, GitHub Discussion [`modelscope/FunASR#3376`](https://github.com/modelscope/FunASR/discussions/3376) was published in the `Announcements` category with the title `FunASR v1.3.26: OpenAI-compatible ASR deployment, vLLM, and llama.cpp runtime`. It routes readers to `funasr==1.3.26`, `/v1/audio/transcriptions`, WebSocket realtime examples, `docs/vllm_guide.md`, the H100 vLLM smoke evidence, `runtime-llamacpp-v0.1.8`, troubleshooting docs, and asks real app users to share hardware, model path, latency, and deployment friction.
 - [ ] Pin a GitHub discussion for the release. The release discussion exists at [`modelscope/FunASR#3376`](https://github.com/modelscope/FunASR/discussions/3376), but the GitHub GraphQL API currently exposes `createDiscussion` and `updateDiscussion` but no discussion pin mutation; pin manually in the GitHub Discussions UI or retry if GitHub exposes an API for discussion pinning.
 - [ ] Triage all new issues within 48 hours.
-- [ ] Convert top 3 support questions into docs.
+- [x] Convert top 3 support questions into docs. On 2026-07-23, the latest 80 FunASR issues were triaged into three repeat support blockers: install / hub / model-id selection (#3321, #3045, #3042, #2973, #2976), llama.cpp / GGUF / CUDA-Vulkan runtime packages (#3298, #3297, #3296, #3289, #3243), and realtime / VAD / vLLM / server output behavior (#3101, #3109, #3038, #3031, #2968, #2965). `docs/troubleshooting.md` and `docs/troubleshooting_zh.md` now start with a Top support questions section that maps those three issue clusters to the existing install, model-download, OpenAI-compatible server, WebSocket, and llama.cpp / GGUF FAQ anchors.
 - [ ] Track stars, PyPI downloads, issue volume, and docs traffic. `collect_growth_metrics.py` now tracks GitHub stars, open issues, and open pull requests for the four core repositories and adds PyPIStats download windows for `funasr` as `downloads_last_7_days` and `downloads_last_30_days` when `pypistats.org` is reachable. The script keeps the patrol usable when PyPIStats is rate-limited by reporting downloads as unavailable instead of failing the run. GitHub/PyPI tracking is now covered; docs traffic remains unavailable until an analytics credential or export is connected.
 
 ## Release-note template

docs/troubleshooting.md

@@ -2,6 +2,14 @@
 
 This short FAQ covers the install and deployment failures that most often block a first FunASR trial. For model choice, see the [model selection guide](./model_selection.md); for serving options, see the [deployment matrix](./deployment_matrix.md).
 
+## Top support questions from recent issues
+
+Recent issue triage shows three repeat blockers that stop first-time users most often:
+
+- **Which install or hub path should I use?** See [Install or import fails](#install-or-import-fails) and [Model download is slow or fails](#model-download-is-slow-or-fails). This covers reports like #3321, #3045, #3042, #2973, and #2976.
+- **Which runtime package should I run on CPU, CUDA, Vulkan, or GGUF?** See [llama.cpp or GGUF runtime does not start](#llamacpp-or-gguf-runtime-does-not-start). This covers reports like #3298, #3297, #3296, #3289, and #3243.
+- **Why is realtime, VAD, vLLM, or server output delayed, empty, or different from local Python?** See [`funasr-server` starts but OpenAI-compatible requests fail](#funasr-server-starts-but-openai-compatible-requests-fail) and [WebSocket realtime output is empty or delayed](#websocket-realtime-output-is-empty-or-delayed). This covers reports like #3101, #3109, #3038, #3031, #2968, and #2965.
+
 ## Install or import fails
 
 - Install `torch` and `torchaudio` first, then install FunASR:

docs/troubleshooting_zh.md

@@ -2,6 +2,14 @@
 
 这份简短 FAQ 汇总首次安装和部署 FunASR 时最常见的阻塞问题。模型选择请看[模型选择指南](./model_selection_zh.md)，服务化选型请看[部署选型](./deployment_matrix_zh.md)。
 
+## 最近 issue 里的 Top 支持问题
+
+最近 issue 巡检显示，最容易阻塞首次试用的三类问题是：
+
+- **应该用哪个安装命令、模型 id 或 hub？** 看[安装或 import 失败](#安装或-import-失败)和[模型下载慢或失败](#模型下载慢或失败)。对应 #3321、#3045、#3042、#2973、#2976 等问题。
+- **CPU、CUDA、Vulkan、GGUF 应该下载哪个 runtime 包？** 看[llama.cpp 或 GGUF runtime 无法启动](#llamacpp-或-gguf-runtime-无法启动)。对应 #3298、#3297、#3296、#3289、#3243 等问题。
+- **实时服务、VAD、vLLM 或 server 输出为什么延迟、为空，或和本地 Python 不一致？** 看[`funasr-server` 启动后 OpenAI 兼容接口请求失败](#funasr-server-启动后-openai-兼容接口请求失败)和[WebSocket 实时输出为空或延迟很大](#websocket-实时输出为空或延迟很大)。对应 #3101、#3109、#3038、#3031、#2968、#2965 等问题。
+
 ## 安装或 import 失败
 
 - 先安装 `torch` 和 `torchaudio`，再安装 FunASR：

tests/test_growth_plan_doc.py

@@ -208,6 +208,36 @@ def test_growth_plan_records_sharp_github_release_focus():
     assert "[ ] Create a GitHub release focused on one sharp value proposition" not in text
 
 
+def test_growth_plan_records_top_support_questions_completion():
+    text = PLAN.read_text()
+    troubleshooting = (ROOT / "docs" / "troubleshooting.md").read_text()
+    troubleshooting_zh = (ROOT / "docs" / "troubleshooting_zh.md").read_text()
+
+    required_markers = [
+        "[x] Convert top 3 support questions into docs",
+        "latest 80 FunASR issues",
+        "install / hub / model-id selection",
+        "llama.cpp / GGUF / CUDA-Vulkan runtime packages",
+        "realtime / VAD / vLLM / server output behavior",
+        "#3321",
+        "#3298",
+        "#3101",
+        "Top support questions",
+        "`docs/troubleshooting.md`",
+        "`docs/troubleshooting_zh.md`",
+    ]
+    for marker in required_markers:
+        assert marker in text
+
+    assert "[ ] Convert top 3 support questions into docs" not in text
+    assert "## Top support questions from recent issues" in troubleshooting
+    assert "Which install or hub path should I use?" in troubleshooting
+    assert "Which runtime package should I run on CPU, CUDA, Vulkan, or GGUF?" in troubleshooting
+    assert "Why is realtime, VAD, vLLM, or server output delayed" in troubleshooting
+    assert "## 最近 issue 里的 Top 支持问题" in troubleshooting_zh
+    assert "应该用哪个安装命令、模型 id 或 hub？" in troubleshooting_zh
+
+
 def test_growth_plan_records_modelscope_card_sync_blocker():
     text = PLAN.read_text()