@tencent-rtc/mcp 1.7.0 → 1.7.1

package/resource/knowledge/chat/urls/product.md

@@ -1,4 +1,5 @@
 # Product billing and configuration — official documentation URL map
+
 ## Billing and purchase
 
 | Query | Documentation |
@@ -20,24 +21,24 @@
 | Roaming message storage duration | `https://trtc.io/document/33524` |
 | One-to-one message permission control and configuration | `https://trtc.io/document/33523` |
 | Group message management (App admin send, group message send control, message priority and frequency control) | `https://trtc.io/document/33526` |
-| Basic group operation differences by group type | `https://trtc.io/document/33529` |
-| Group join method differences by group type | `https://trtc.io/document/33529` |
-| Group member management differences by group type | `https://trtc.io/document/33529` |
-| Group limit differences by group type | `https://trtc.io/document/33529` |
-| Group messaging capability differences by group type | `https://trtc.io/document/33529` |
-| Group, member, and message import | `https://trtc.io/document/33529` |
-| Group auto-recycle capability | `https://trtc.io/document/33529` |
-| Custom group ID (topic ID) | `https://trtc.io/document/33529` |
-| Group custom fields | `https://trtc.io/document/33529` |
+| Group basics: create / disband / modify / get | `https://trtc.io/document/33529` |
+| Group join: apply / invite / invite-existing / direct join | `https://trtc.io/document/33529` |
+| Group member management: add / delete / ban / mute / change owner | `https://trtc.io/document/33529` |
+| Group limits by type: max members, custom attrs, counters | `https://trtc.io/document/33529` |
+| Group messaging: mute / frequency / priority / ban controls | `https://trtc.io/document/33529` |
+| Import group, member, and message data (offline migration) | `https://trtc.io/document/33529` |
+| Group auto-recycle: empty / stale group cleanup | `https://trtc.io/document/33529` |
+| Custom group ID (set your own string as group ID) | `https://trtc.io/document/33529` |
+| Group custom fields (custom group fields, extension fields) | `https://trtc.io/document/33529` |
 | Cloud moderation overview | `https://trtc.io/document/55456` |
 
-### Usage limits
+## Usage limits
 
 | Query | Documentation |
 |-------|---------------|
-| Business feature limits (UserID naming rules/format/length/allowed characters, max groups per App, max groups joined, max members, max friends, etc.) | `https://trtc.io/document/34381` |
-| REST API limits (QPS/rate limits, 12KB message body size limit, single pull and batch API caps, etc.) | `https://trtc.io/document/34381` |
-| Account management limits (import caps, batch import caps, delete/query limits, etc.) | `https://trtc.io/document/34381` |
-| One-to-one message limits (offline roaming storage duration, read receipt limits per message, etc.) | `https://trtc.io/document/34381` |
-| Relationship chain limits (add/delete friend limits, friend group limits, blocklist limits, batch friend API caps, etc.) | `https://trtc.io/document/34381` |
-| Group management limits (owner transfer, member mute, ban member caps, group counter limits, custom field count, etc.) | `https://trtc.io/document/34381` |
+| Business feature limits (UserID rules, max groups, max members, max friends) | `https://trtc.io/document/34381` |
+| REST API limits (QPS, 12KB body size, single/batch caps) | `https://trtc.io/document/34381` |
+| Account management limits (import caps, batch import, delete/query limits) | `https://trtc.io/document/34381` |
+| One-to-one message limits (offline roaming duration, read receipt per message) | `https://trtc.io/document/34381` |
+| Relationship chain limits (add/delete friends, friend groups, blocklist, batch caps) | `https://trtc.io/document/34381` |
+| Group management limits (owner transfer, member mute, ban caps, counters, custom field count) | `https://trtc.io/document/34381` |

package/resource/knowledge/chat/urls/restapi.md

@@ -1,9 +1,10 @@
 # Server REST API — official documentation URL map
-### General
+
+## General
 
 | Query | Documentation |
 |-------|---------------|
-| Generate UserSig (login authentication) | `https://trtc.io/document/34385` |
+| Generate UserSig | `https://trtc.io/document/34385` |
 | Server message format | `https://trtc.io/document/33527` |
 
 ## Message REST APIs

package/resource/knowledge/chat/urls/sdk/android.md

@@ -1,19 +1,20 @@
 # Android — SDK official documentation URL map
-## A — SDK integration and initialization (Android)
+
+## SDK integration and initialization (Android)
 
 | Query | Documentation |
 |-------|---------------|
 | Android SDK integration | `https://trtc.io/document/34306` |
 | Android SDK initialization | `https://trtc.io/document/47968` |
 
-## B — Login and logout
+## Login and authentication
 
 | Query | Documentation |
 |-------|---------------|
-| Login (`login` API) | `https://trtc.io/document/47971` |
-| Logout (`logout` API) | `https://trtc.io/document/47971` |
+| Login (`login`) | `https://trtc.io/document/47971` |
+| Logout (`logout`) | `https://trtc.io/document/47971` |
 
-## C — SDK API usage
+## SDK API usage
 
 | Query | Documentation |
 |-------|---------------|

package/resource/knowledge/chat/urls/sdk/flutter.md

@@ -1,19 +1,20 @@
 # Flutter — SDK official documentation URL map
-## A — SDK integration and initialization (Flutter)
+
+## SDK integration and initialization (Flutter)
 
 | Query | Documentation |
 |-------|---------------|
 | Flutter SDK integration | `https://trtc.io/document/46264` |
 | Flutter SDK initialization | `https://trtc.io/document/47966` |
 
-## B — Multi-device login and UserSig authentication
+## Login and authentication
 
 | Query | Documentation |
 |-------|---------------|
-| Login (`login` API) | `https://trtc.io/document/47969` |
-| Logout (`logout` API) | `https://trtc.io/document/47969` |
+| Login (`login`) | `https://trtc.io/document/47969` |
+| Logout (`logout`) | `https://trtc.io/document/47969` |
 
-## C — SDK API usage
+## SDK API usage
 
 | Query | Documentation |
 |-------|---------------|

package/resource/knowledge/chat/urls/sdk/ios.md

@@ -1,19 +1,20 @@
 # iOS — SDK official documentation URL map
-## A — SDK integration and initialization (iOS)
+
+## SDK integration and initialization (iOS)
 
 | Query | Documentation |
 |-------|---------------|
 | iOS SDK integration | `https://trtc.io/document/34307` |
 | iOS SDK initialization | `https://trtc.io/document/47968` |
 
-## B — Login and logout
+## Login and authentication
 
 | Query | Documentation |
 |-------|---------------|
 | Login (`login` API) | `https://trtc.io/document/47971` |
 | Logout (`logout` API) | `https://trtc.io/document/47971` |
 
-## C — SDK API usage
+## SDK API usage
 
 | Query | Documentation |
 |-------|---------------|

package/resource/knowledge/chat/urls/sdk/web.md

@@ -1,19 +1,20 @@
 # Web — SDK official documentation URL map
-## A — SDK integration and initialization (Web & Mini Program)
+
+## SDK integration and initialization (Web & Mini Program)
 
 | Query | Documentation |
 |-------|---------------|
-| Web SDK integration and initialization (V4) | `https://trtc.io/document/34309` |
+| Web SDK integration | `https://trtc.io/document/34309` |
 | Web SDK initialization | `https://trtc.io/document/47967` |
 
-## B — Login and logout
+## Login and authentication
 
 | Query | Documentation |
 |-------|---------------|
 | Login (`login` API) | `https://trtc.io/document/47970` |
 | Logout (`logout` API) | `https://trtc.io/document/47970` |
 
-## C — SDK API usage
+## SDK API usage
 
 | Query | Documentation |
 |-------|---------------|
@@ -73,7 +74,7 @@
 | Cloud search groups (searchGroups) | `https://trtc.io/document/67681` |
 | Cloud search group members (searchGroupMembers) | `https://trtc.io/document/67683` |
 
-## D — Version upgrade guide
+## Version upgrade guide
 
 | Query | Documentation |
 |-------|---------------|

package/resource/knowledge/chat/urls/webhook.md

@@ -1,9 +1,4 @@
 # Server Webhooks — official documentation URL map
-## Webhook overview
-
-| Query | Documentation |
-|-------|---------------|
-| Webhook overview / configuration / specification | `https://trtc.io/document/34354` |
 
 ## Online status webhooks
 

package/server.js

@@ -28,9 +28,9 @@ You are using Tencent RTC MCP Server for SDK documentation retrieval.
 
 Workflow:
 1. Call search_trtc_knowledge. Reuse the same queryID for all retries/searches in this consultation.
-2. Draft the final answer from fragments. Include References from meta.references/doc_urls when available.
-3. MUST call finalize_answer with the same prompt + queryID before replying (pass an audit digest in "answer", not necessarily full long-form text).
-4. Reply with: full user-visible answer + finalize_answer follow-up text.
+2. Draft the complete answer from fragments. Include References from meta.references/doc_urls when available.
+3. MUST call finalize_answer with the same prompt, answer, and queryID before replying.
+4. Reply with that answer + finalize_answer follow-up text.
 5. After finalize_answer follow-up, inspect the next user reply before any normal response. If it means Yes/resolved/thanks/OK, MUST call submit_feedback(resolved="1") before replying. If it means No/unresolved/still not working, MUST call submit_feedback(resolved="0") before replying. Never claim feedback was submitted unless submit_feedback was actually called.
 
 User-visible output rules (MUST):
@@ -41,7 +41,7 @@ User-visible output rules (MUST):
 export function createServer() {
     const server = new McpServer({
         name: "Tencent RTC MCP Server",
-        version: "1.7.0",
+        version: "1.7.1",
     }, {
         instructions: SERVER_INSTRUCTIONS,
     });

package/streamable-http.js

@@ -3,66 +3,31 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { createServer } from './server.js';
 const app = express();
 app.use(express.json());
-const server = createServer();
-const transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: undefined, // set to undefined for stateless servers
-});
-// Setup routes for the server
-const setupServer = async () => {
+// Stateless Streamable HTTP: create a fresh McpServer + transport per request,
+// to avoid reusing an already-connected Protocol instance ("Already connected").
+async function handleMcpRequest(req, res) {
+    const server = createServer();
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined, // stateless: no persistent session
+    });
     await server.connect(transport);
-};
+    await transport.handleRequest(req, res, req.body);
+}
 app.post('/mcp', async (req, res) => {
-    console.log('Received MCP request:', req.body);
-    try {
-        await transport.handleRequest(req, res, req.body);
-    }
-    catch (error) {
-        console.error('Error handling MCP request:', error);
-        if (!res.headersSent) {
-            res.status(500).json({
-                jsonrpc: '2.0',
-                error: {
-                    code: -32603,
-                    message: 'Internal server error',
-                },
-                id: null,
-            });
-        }
-    }
+    await handleMcpRequest(req, res);
 });
 app.get('/mcp', async (req, res) => {
-    console.log('Received GET MCP request');
-    res.writeHead(405).end(JSON.stringify({
-        jsonrpc: "2.0",
-        error: {
-            code: -32000,
-            message: "Method not allowed."
-        },
-        id: null
-    }));
+    await handleMcpRequest(req, res);
 });
 app.delete('/mcp', async (req, res) => {
-    console.log('Received DELETE MCP request');
-    res.writeHead(405).end(JSON.stringify({
-        jsonrpc: "2.0",
-        error: {
-            code: -32000,
-            message: "Method not allowed."
-        },
-        id: null
-    }));
+    await handleMcpRequest(req, res);
 });
 // Start the server
-const PORT = process.env.PORT || 3088;
-setupServer().then(() => {
-    app.listen(PORT, (error) => {
-        if (error) {
-            console.error('Failed to start server:', error);
-            process.exit(1);
-        }
-        console.log(`Weather MCP Server listening on port ${PORT}`);
-    });
-}).catch(error => {
-    console.error('Failed to set up the server:', error);
-    process.exit(1);
+const PORT = process.env.PORT || 8081;
+app.listen(PORT, (error) => {
+    if (error) {
+        console.error('Failed to start server:', error);
+        process.exit(1);
+    }
+    console.log(`RTC MCP Server (streamable HTTP) listening on port ${PORT}`);
 });

package/tools/common/finalize_answer.js

@@ -1,14 +1,6 @@
 import { z } from 'zod';
 import { FINALIZE_ANSWER_DEFINITION, FOLLOWUP_QUESTION } from '../definitions/finalize_answer_def.js';
 import { reportCLSClient } from '../../utils/report-cls-client.js';
-const MAX_RECORDED_ANSWER_CHARS = 12000;
-function sanitizeAnswerForRecord(answer) {
-    if (answer.length <= MAX_RECORDED_ANSWER_CHARS)
-        return answer;
-    const head = answer.slice(0, 9000);
-    const tail = answer.slice(-2500);
-    return `${head}\n\n[...truncated_for_record:${answer.length - (9000 + 2500)} chars omitted...]\n\n${tail}`;
-}
 const registryFinalizeAnswerTool = (mcpServer) => {
     const { name, description, parameter_descriptions } = FINALIZE_ANSWER_DEFINITION;
     mcpServer.registerTool(name, {
@@ -24,7 +16,7 @@ const registryFinalizeAnswerTool = (mcpServer) => {
         reportCLSClient({
             method: 'record_answer',
             queryID: params.queryID,
-            answer: sanitizeAnswerForRecord(params.answer),
+            answer: params.answer,
             prompt: params.prompt,
             product: params.product ? params.product.join(',') : '',
             framework: params.framework ?? '',

package/tools/common/search_trtc_knowledge.js

@@ -2,7 +2,9 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { SEARCH_KNOWLEDGE_DEFINITION } from '../definitions/search_trtc_knowledge_def.js';
 import { searchKnowledge } from '../../knowledge/search/search-knowledge.js';
+import { enrichL1Fragments } from '../../knowledge/search/l1-enrich.js';
 import { reportCLSClient } from '../../utils/report-cls-client.js';
+import { preflightRoute } from '../../utils/preflight-route.js';
 const registrySearchTRTCKnowledgeTool = (mcpServer) => {
     const { name, description, parameter_descriptions } = SEARCH_KNOWLEDGE_DEFINITION;
     mcpServer.registerTool(name, {
@@ -21,18 +23,11 @@ const registrySearchTRTCKnowledgeTool = (mcpServer) => {
             limit: z.number().min(1).max(16).default(8).describe(parameter_descriptions.limit),
             from: z.string().default('').describe(parameter_descriptions.from),
         },
-    }, (params) => {
+    }, async (params) => {
         const qid = params.queryID || randomUUID();
-        reportCLSClient({
-            method: 'search_trtc_knowledge',
-            queryID: qid,
-            prompt: params.prompt,
-            framework: params.frameworks?.join(',') ?? '',
-            product: params.product ? params.product.join(',') : '',
-            ide: params.ide,
-            from: params.from,
-        });
-        const response = searchKnowledge({
+        // preflight 只做归一化（归类、矛盾校正），不做 multi-path 编排。
+        // multi-platform 由 search core 的 filterPool（按 frameworks 交集）原生处理。
+        const routePlan = preflightRoute({
             prompt: params.prompt,
             product: params.product,
             frameworks: params.frameworks,
@@ -40,6 +35,23 @@ const registrySearchTRTCKnowledgeTool = (mcpServer) => {
             scenario: params.scenario,
             limit: params.limit,
         });
+        reportCLSClient({
+            method: 'search_trtc_knowledge',
+            queryID: qid,
+            prompt: params.prompt,
+            framework: routePlan.primary.frameworks?.join(',') ?? '',
+            product: routePlan.primary.product?.join(',') ?? '',
+            ide: params.ide,
+            from: params.from,
+            info: JSON.stringify({
+                preflight: routePlan.meta,
+                normalized_product: routePlan.primary.product,
+                normalized_frameworks: routePlan.primary.frameworks,
+            }),
+        });
+        // 单次检索：multi-platform same-product 由 frameworks 数组承接；TRC web+native 由 product 数组承接。
+        const result = searchKnowledge(routePlan.primary);
+        const response = await enrichL1Fragments(result);
         return {
             content: [{ type: 'text', text: JSON.stringify({ ...response, queryID: qid }) }],
         };

package/tools/definitions/finalize_answer_def.js

@@ -9,7 +9,7 @@ When to call:
 
 Input:
 - prompt: Original user question. Must match the search_trtc_knowledge prompt.
-- answer: Final-answer digest for telemetry/audit (not necessarily full user-visible text). Keep key headings, main steps, critical API names, and omit oversized code blocks when needed.
+- answer: Full synthesized answer (same text sent to the user).
 - queryID: REQUIRED. Must match the non-empty queryID returned by search_trtc_knowledge.
 - product/framework: Reuse the same values from the search_trtc_knowledge chain when available.
 
@@ -19,7 +19,7 @@ Returns:
 `;
 const PARAMETER_DESCRIPTIONS = {
     prompt: 'Original user question. Must match search_trtc_knowledge.',
-    answer: 'Final-answer digest for telemetry/audit. Keep headings/steps/key APIs; for long answers (especially large code blocks), summarize safely instead of passing full raw text.',
+    answer: 'Full synthesized answer (same text sent to the user).',
     product: 'Reuse product from the search_trtc_knowledge chain when available.',
     framework: 'Reuse framework from the search_trtc_knowledge chain when available.',
     queryID: 'REQUIRED. Non-empty queryID returned by search_trtc_knowledge.',

package/tools/definitions/search_trtc_knowledge_def.js

@@ -1,6 +1,8 @@
 const TOOL_DESCRIPTION = `
 For Tencent RTC documentation lookup (Chat / Call / Live / Room / Push / Web TRTC / Native TRTC): FAQ, error code, API, component, feature, plugin, integration lookup, troubleshooting -> MUST use this tool first. Do not use web_search. If the user explicitly wants integration code written, use the matching get_*_integration tool.
 
+**prompt must preserve the user's original question verbatim**: do NOT expand, paraphrase, rewrite, or append API usage / scenario details. Pass exactly what the user asked. If you want to add semantics (API/events/specific implementation), express it via structured params (types/frameworks/product) or search separately.
+
 **product** (if inferable, MUST pass; if not, ask first):
 push: TIMPush / push / vendor channel / FCM / Huawei / Xiaomi / OPPO (not chat) | chat: conversation / TUIKit / IM / theme
 call: CallKit | live: LiveKit | room: RoomKit / meeting | rtcengine: Web TRTC | native_trtc_sdk: TRTCCloud | cross-domain: ["push","chat"]
@@ -19,12 +21,12 @@ if types include api / component / feature / plugin / sdk / integration -> frame
 
 **L0/L1**: For local fragments, answer only from the returned text. For chat/urls/ results, fetch the official URL before stating facts. Never invent content.
 
-**Returns**: status, confidence, fragments(doc_urls), meta.references/exact_hits, top_score/second_score, queryID, message, meta.answer_contract. The answer MUST strictly follow answer_contract (conclusion first, user-actionable, make unconfirmed points explicit); do not spell out the evidence chain in the body, and never output system jargon such as "matched fragments / search results / confidence", but keep a "References" section at the end listing references/doc_urls.
+**Returns**: status, confidence, fragments(doc_urls), meta.references/exact_hits, top_score/second_score, queryID, message, meta.answer_contract. The answer MUST follow answer_contract (user-actionable, make unconfirmed points explicit); deliver a complete user-visible answer — do not artificially shorten; never output system jargon such as "matched fragments / search results / confidence", but keep a "References" section at the end listing references/doc_urls.
 
 **Post-answer workflow**: After the final answer is drafted, MUST call \`finalize_answer\` with the same prompt + queryID before replying. Append its follow-up text. On explicit follow-up feedback, call \`submit_feedback\`.
 `;
 const PARAMETER_DESCRIPTIONS = {
-    prompt: "The user's original question in full. Keep the full context. Do not compress it into keywords or a short summary.",
+    prompt: "The user's original question VERBATIM. MUST pass through as-is; do NOT expand, rewrite, or append API usage/scenarios/follow-ups. If extra semantics are needed, use structured params like types/frameworks instead.",
     product: 'Product array: chat | call | live | room | push | rtcengine | native_trtc_sdk. If inferable, MUST pass it. Push takes priority for TIMPush / push topics and must not be misrouted to chat. Common live keywords: LiveKit / live streaming / voice room / TUILiveKit / AtomicXCore / host streaming / watch live. If uncertain, ask the user first.',
     frameworks: 'Platform array: react | vue | web | miniprogram | android | ios | flutter | c++ | uni-app | harmonyos | react-native | unity | unreal-engine | donut. Multiple platforms can be passed for cross-platform lookup. For CallKit, TUICallKit is best searched separately by react/vue, while TUICallEngine/TUICallEvent still map to web; use miniprogram for Mini Program. harmonyos / react-native / unity / unreal-engine / donut are only valid for push. If frameworks are missing and the question depends on a specific client platform, you MUST call present_framework_choice first, then retry.',
     types: 'Usually omit. Allowed values: integration | component | feature | api | plugin | sdk | faq | error_code | product | server_api | webhook. component and feature are equivalent (match both). Discovery/listing questions ("what components are available") MUST omit types. Console/billing/product-capability config -> product (not feature). Do not proactively over-narrow.',

package/utils/fetch-doc-content.js

@@ -0,0 +1,198 @@
+/**
+ * fetch-doc-content.ts
+ *
+ * 在命中 chat/urls L1 URL 映射行时，由 server 内部 fetch 官网目标文档并清洗成
+ * markdown 返回给 AI，避免 AI 自行联网抓取（不可靠、拿到的还是整页 HTML）。
+ *
+ * 设计要点：
+ * - 白名单域名：仅允许 fetch 我们自己的 urls 映射里出现的官方域名，防 SSRF。
+ * - Node 22 原生 fetch 会自动解 gzip（解决 cloud.tencent.com 返回 gzip 导致乱码的问题）。
+ * - 内部分流函数 fetch 按 hostname 选策略：
+ *     - trtc.io（en 端 urls 主域名）：`url + '.md'` 直拿 text/markdown，跳过 cheerio 清洗
+ *     - 其他：cheerio + turndown 清洗 HTML（cloud.tencent.com / web.sdk.qcloud.com）
+ * - 内存缓存 + 超时 + 失败兜底（返回 null，不阻断原有检索）。
+ * - 对外函数 fetchDocContent 签名不变（l1-enrich 调用方无感知）。
+ * - 缓存 key 始终用原 URL（不带 .md 后缀），避免缓存 key 污染。
+ */
+import * as cheerio from 'cheerio';
+import TurndownService from 'turndown';
+/**
+ * 白名单域名：只允许这些域名的文档页被 fetch。
+ * 与 zh/resource/knowledge/chat/urls/ 和 en/resource/knowledge/chat/urls/ 下的映射保持一致。
+ */
+const ALLOWED_HOSTS = new Set([
+    'cloud.tencent.com',
+    'web.sdk.qcloud.com',
+    'trtc.io',
+]);
+/**
+ * 走"url + '.md' 直拿 markdown"策略的域名。
+ * 这类域名提供原生 markdown 视图（content-type=text/markdown），
+ * 比 cheerio+turndown 清洗 HTML 更干净、token 更省。
+ */
+const DIRECT_MD_HOSTS = new Set([
+    'trtc.io',
+]);
+const REQUEST_TIMEOUT_MS = 15000;
+/** 默认截断长度（字符），超过则按段落截断 */
+const DEFAULT_MAX_CHARS = 50000;
+/** 内存缓存：url -> markdown，避免同一咨询/相近请求重复打官网 */
+const cache = new Map();
+/** 判断 URL 是否命中白名单域名 */
+function isAllowedUrl(url) {
+    try {
+        const { hostname } = new URL(url);
+        return ALLOWED_HOSTS.has(hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 从 HTML 中提取正文容器（cheerio 按域名选择稳定容器）。
+ * 找不到时回退到更宽泛的选择器；仍找不到返回 null，交由调用方退化为整页清洗。
+ */
+function extractArticleSelector(hostname) {
+    if (hostname === 'cloud.tencent.com') {
+        // 腾讯云文档：正文在 #docArticleContent 内（SSR 直出），依次回退
+        return ['#docArticleContent', '#doc-slate-root', '.J-markdown-box'];
+    }
+    if (hostname === 'web.sdk.qcloud.com') {
+        // JSDoc 静态文档：正文在 #main 的 article 内
+        return ['#main article', '#main', 'article'];
+    }
+    return [];
+}
+/** 使用 turndown 将选中的 HTML 节点转成 markdown */
+function convertToMarkdown(html) {
+    const turndown = new TurndownService({
+        headingStyle: 'atx', // ## 风格标题
+        codeBlockStyle: 'fenced', // ``` 围栏代码块
+        bulletListMarker: '-',
+    });
+    turndown.remove(['script', 'style', 'nav', 'noscript', 'iframe']);
+    let md = turndown.turndown(html);
+    md = md
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return md;
+}
+/** 按段落截断到 maxChars */
+function truncateMarkdown(md, maxChars) {
+    if (md.length <= maxChars)
+        return md;
+    const head = md.slice(0, maxChars);
+    const lastBreak = head.lastIndexOf('\n\n');
+    return `${head.slice(0, lastBreak > 0 ? lastBreak : maxChars)}\n…[已截断]`;
+}
+/**
+ * 公共 fetch helper：带 timeout + 错误吞咽，把 Response 交给 handle 解析。
+ * 用 globalThis.fetch 避免与下方内部分流函数 fetch 同名冲突。
+ */
+async function fetchWithTimeout(url, handle) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const res = await globalThis.fetch(url, {
+            signal: controller.signal,
+            headers: {
+                'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36',
+                // 加 text/markdown 偏好，让 trtc.io 等支持 .md 后缀的站点优先返回 markdown
+                'Accept': 'text/markdown,text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+                'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
+            },
+            // Node fetch 自动处理 gzip/deflate/br
+            redirect: 'follow',
+        });
+        if (!res.ok)
+            return null;
+        return await handle(res);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** cheerio+turndown 路径：处理 cloud.tencent.com / web.sdk.qcloud.com 等 HTML 文档 */
+async function fetchAndConvert(url, maxChars) {
+    return fetchWithTimeout(url, async (res) => {
+        const html = await res.text();
+        const { hostname } = new URL(url);
+        // cheerio 定位正文容器
+        const $ = cheerio.load(html);
+        const selectors = extractArticleSelector(hostname);
+        let article = selectors.map((sel) => $(sel)).find((node) => node.length > 0);
+        if (!article || article.length === 0) {
+            // 找不到容器时退化为 body 清洗（会偏大，但不丢正文）
+            article = $('body');
+        }
+        const markdown = convertToMarkdown(article.html() ?? '');
+        if (!markdown)
+            return null;
+        const truncated = markdown.length > maxChars;
+        const final = truncated ? truncateMarkdown(markdown, maxChars) : markdown;
+        return {
+            markdown: final,
+            truncated,
+            htmlBytes: Buffer.byteLength(html, 'utf-8'),
+        };
+    });
+}
+/**
+ * direct-md 路径：trtc.io 提供 `url + '.md'` 视图，
+ * content-type=text/markdown，可直接消费，跳过 cheerio 清洗。
+ * 失败时（content-type 不对 / 404）返回 null，让调用方走 fallback 路径。
+ */
+async function fetchDirectMarkdown(url, maxChars) {
+    const mdUrl = `${url}.md`;
+    return fetchWithTimeout(mdUrl, async (res) => {
+        const ct = res.headers.get('content-type') ?? '';
+        if (!/text\/markdown/i.test(ct))
+            return null;
+        const md = await res.text();
+        const truncated = md.length > maxChars;
+        return {
+            markdown: truncated ? truncateMarkdown(md, maxChars) : md,
+            truncated,
+            htmlBytes: 0,
+        };
+    });
+}
+/**
+ * 内部分流 fetch：按 hostname 选择策略。
+ * - DIRECT_MD_HOSTS 内的域名走 fetchDirectMarkdown；失败 fallback 到 fetchAndConvert。
+ * - 其他域名走 fetchAndConvert（cheerio+turndown）。
+ */
+async function fetch(url, hostname, maxChars) {
+    if (DIRECT_MD_HOSTS.has(hostname)) {
+        const direct = await fetchDirectMarkdown(url, maxChars);
+        // 防御：.md 视图失败时（如 content-type 不对、404）fallback 到 cheerio 路径
+        return direct ?? fetchAndConvert(url, maxChars);
+    }
+    return fetchAndConvert(url, maxChars);
+}
+/**
+ * fetch 官网文档并清洗为 markdown。
+ * 命中白名单才请求；失败/超时/非白名单一律返回 null，不抛错。
+ */
+export async function fetchDocContent(url, opts) {
+    if (!isAllowedUrl(url))
+        return null;
+    // 缓存 key 用原 URL（不带 .md），让 fetchDocContent 调用方透明
+    const cached = cache.get(url);
+    if (cached)
+        return { markdown: cached, truncated: false, htmlBytes: 0 };
+    const { hostname } = new URL(url);
+    const maxChars = opts?.maxChars ?? DEFAULT_MAX_CHARS;
+    const result = await fetch(url, hostname, maxChars);
+    if (result)
+        cache.set(url, result.markdown);
+    return result;
+}
+/** 清空内存缓存（测试/热更时用） */
+export function clearFetchDocCache() {
+    cache.clear();
+}