@tencent-rtc/mcp 1.6.7 → 1.7.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# CHANGELOG
+
+## Version 1.7.0 @2026.08.02
+
+### Added
+- Added and synchronized best-practice docs across product domains including Chat / Call / Live / Room to improve knowledge coverage.
+
+### Changed
+- Continued refactoring of the bilingual retrieval pipeline, including query normalization, intent routing, candidate filtering, and exact-match strategies.
+- Improved recall and ranking for best-practice and URL-based documents to increase answer usability and stability.
+- Improved `search_trtc_knowledge` definitions and answer constraints for better readability and executability.
+
+### Fixed
+- Fixed off-topic retrieval in some complex queries, reducing high-score false-positive hits.
+
+## Version 1.6.6 @2026.07.18
+
+### Added
+- Added support for `get_native_live_uikit_integration`, enabling LiveKit(Android/iOS) UI integration guidance.
+
+## Version 1.6.0 @2026.07.01
+
+### Added
+- Refactored MCP retrieval capabilities and consolidated the MCP toolset.
+- Added support for `search_trtc_knowledge` to retrieve real-time audio/video (TRTC/IM) documentation.

package/README.md

@@ -1,45 +1,27 @@
-## Tencent SDK Model Context Protocol (MCP) Server for Cursor IDE
-
-This repository provides a CLI-based Model Context Protocol (MCP) server that exposes Tencent SDK documentation and Tencent API resources to LLM-powered tools.
-This improves the LLM AI Agent's ability to understand and interact with Tencent's SDKs and APIs.
+## Tencent RTC SDK MCP Server Guide
 
+This repository provides a CLI-based Model Context Protocol (MCP) Server that exposes Tencent RTC SDK documentation and API resources to LLM tools, helping AI agents deliver more accurate implementation guidance and integration support.
 
 ## Features
 
-- MCP server exposing tools for interacting with Tencent via JSON-RPC over STDIN/STDOUT.
-- MCP server supports SSE Mode by supplying `HTTP_PORT` environment variable.
-- Retrieve official Tencent SDK documentation (HTML → Markdown) for:
-  - Languages: JavaScript, Java, Swift, Objective-C, Kotlin.
-  - API reference sections: configuration, calls function.
-- Retrieve official Tencent TUICallKit SDK documentation (HTML → Markdown) for:
-  - TUICallKit SDK languages: JavaScript, Kotlin, Swift.
-  - TUICallKit SDK topics: configuration, calls function.
-- Retrieve official Tencent ChatUIKit documentation (HTML → Markdown) for:
-  - ChatUIKit SDK languages: JavaScript, Kotlin, Swift.
-  - ChatUIKit SDK topics: configuration, chat function.
-- Converts remote HTML articles to Markdown using `jsdom` and `turndown` for consistent documentation formatting.
-- Input validation via Zod schemas for all tool parameters, ensuring robust error handling.
-- Extensible tool definitions leveraging the Model Context Protocol SDK (`@modelcontextprotocol/sdk`) with `McpServer` and `StdioServerTransport`.
-
-
-## Prerequisites
-- Node.js (>= 18) and npm
-- Cursor IDE with MCP support
-
+- **Efficient retrieval**: Supports Tencent RTC documentation retrieval for fast access to official references and best practices.
+- **Broad coverage**: Covers Chat (IM), Call, Live, Room, RTCEngine (TRTC SDK), and TIMPush domains.
+- **Intelligent routing**: Supports product/platform intent disambiguation and prompts for missing platform/framework information when needed.
+- **Integration-friendly**: In addition to documentation Q&A, provides integration entry points for Web / Android / iOS / Flutter, including UI-based integration directions.
+- **Reliable source**: Grounded in official Tencent Cloud materials to improve answer reliability and implementation readiness.
+- **Wide compatibility**: Exposes MCP capabilities over STDIN/STDOUT JSON-RPC, compatible with MCP clients such as Cursor / Codex / Claude / CodeBuddy.
+- **Quick start**: Run with `npx` and get started with minimal setup.
 
-## How To Use
-To set up the @tencent-rtc/mcp MCP Server, follow these steps:
-
-- Step1: Installation.
-
-```
-npx -y @tencent-rtc/mcp
-```
+## Requirements
+- Node.js (>= 18) and npm
+- An MCP-capable IDE
 
+## Usage
+### Standard setup flow
 
-- Step2: In your Cursor project, create or open the `.cursor/mcp.json` or `~/.cursor/mcp.json` files and add your config.
+- Step1: In your Cursor project, create or edit `.cursor/mcp.json` or `~/.cursor/mcp.json` and add the following configuration.
 
-```javascript
+```json
 {
   "mcpServers": {
     "tencent-rtc": {
@@ -53,16 +35,48 @@ npx -y @tencent-rtc/mcp
   }
 }
 ```
-When you save the file, a notification is displayed. In the prompt, click **Enable**.
+After saving, a prompt appears. Click **Enable** in the prompt.
 
 ![mcp-server-prompt](https://web.sdk.qcloud.com/im/assets/images/mcp-server-prompt-en.png)
 
-- Step3: Navigate to **Cursor Settings** (the gear icon in top right corner) -> **MCP**, and check if tencentcloud-sdk-mcp server is enabled.
+- Step2: Go to **Cursor Settings** (top-right gear icon) -> **MCP**, and make sure `tencent-rtc` is enabled.
 
 ![cursor-setting](https://web.sdk.qcloud.com/im/assets/images/cursor-setting-en.png)
 
+- Step3: Describe your requirements directly in the IDE, and let the AI complete implementation or troubleshooting based on Tencent Cloud SDK documentation.
+
+### Optional: global install
+
+If you want quick global invocation locally, run:
+
+```bash
+npx -y @tencent-rtc/mcp
+```
+
+## Changelog
+
+> Only recent updates are listed here. For full history, see `CHANGELOG.md`.
+
+### Version 1.7.0 @2026.08.02
+
+#### Added
+- Added and synchronized best-practice docs across product domains including Chat / Call / Live / Room to improve knowledge coverage.
+
+#### Changed
+- Continued refactoring of the bilingual retrieval pipeline, including query normalization, intent routing, candidate filtering, and exact-match strategies.
+- Improved recall and ranking for best-practice and URL-based documents to increase answer usability and stability.
+- Improved `search_trtc_knowledge` definitions and answer constraints for better readability and executability.
+
+#### Fixed
+- Fixed off-topic retrieval in some complex queries, reducing high-score false-positive hits.
+
+### Version 1.6.6 @2026.07.18
+
+#### Added
+- Added support for `get_native_live_uikit_integration`, enabling LiveKit(Android/iOS) UI integration guidance.
 
-Step4: Ask the AI agent to build your Tencentcloud sdk app for you by describing the functionality yourself or by using a sample prompt.
+### Version 1.6.0 @2026.07.01
 
-> [!WARNING]
-Make sure to use the Agent mode. Depending on your Cursor rules, you may also need to explicitly ask the AI agent to use the Tencentcloud sdk-mcp server.
+#### Added
+- Refactored MCP retrieval capabilities and consolidated the MCP toolset.
+- Added support for `search_trtc_knowledge` to retrieve real-time audio/video (TRTC/IM) documentation.

package/knowledge/build-index.js

@@ -3,8 +3,13 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { chunkMarkdown, toManifestChunk } from './chunker.js';
 import { buildDocSourceUrlMap } from './doc-url-resolver.js';
+import { mergePathMetaWithFrontmatter, resolveFrontmatterMeta } from './frontmatter-meta.js';
 import { inferPathMeta } from './path-meta.js';
+import { loadChunkingPolicy, resolveChunkingRule, resolvePolicyFilePath } from './chunking-policy.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// 构建期写入索引到 dist/resource/index/：
+//   dist/knowledge/ → ../resource/ → dist/resource/
+// 必须在 scripts/copy-resource.js 之后执行，否则目标目录不存在。
 const RESOURCE_ROOT = path.resolve(__dirname, '../resource');
 function walkMarkdownFiles(dir, baseRel) {
     if (!fs.existsSync(dir))
@@ -42,11 +47,32 @@ export function buildKnowledgeIndex() {
         ...walkMarkdownFiles(path.join(RESOURCE_ROOT, 'integration'), 'integration'),
     ];
     const chunks = [];
+    let frontmatterFileCount = 0;
+    let frontmatterMergedCount = 0;
+    let frontmatterParseErrorCount = 0;
+    const chunkingPolicyPath = resolvePolicyFilePath(__dirname);
+    const chunkingPolicy = loadChunkingPolicy(chunkingPolicyPath);
     for (const source of sources) {
         const abs = path.join(RESOURCE_ROOT, source);
-        const content = fs.readFileSync(abs, 'utf-8');
-        const meta = inferPathMeta(source);
-        chunks.push(...chunkMarkdown(source, content, meta).map(toManifestChunk));
+        const rawContent = fs.readFileSync(abs, 'utf-8');
+        // Phase A（兼容期）：frontmatter 优先，未声明字段继续走路径推断 fallback。
+        const pathMeta = inferPathMeta(source);
+        const fm = resolveFrontmatterMeta(rawContent);
+        const meta = mergePathMetaWithFrontmatter(pathMeta, fm.frontmatterMeta, fm.overrideFields);
+        if (fm.hasFrontmatter)
+            frontmatterFileCount += 1;
+        if (meta.meta_source === 'merged')
+            frontmatterMergedCount += 1;
+        if (fm.parseError) {
+            frontmatterParseErrorCount += 1;
+            console.warn(`[build-knowledge-index] frontmatter parse failed: ${source} - ${fm.parseError}`);
+        }
+        const policyRule = resolveChunkingRule(source, chunkingPolicy);
+        chunks.push(...chunkMarkdown(source, fm.content, meta, {
+            baseOffset: fm.contentOffset,
+            policyRule,
+            defaultSplitTokenThreshold: chunkingPolicy.default.split_token_threshold,
+        }).map(toManifestChunk));
     }
     const indexDir = path.join(RESOURCE_ROOT, 'index');
     fs.mkdirSync(indexDir, { recursive: true });
@@ -65,5 +91,6 @@ export function buildKnowledgeIndex() {
     if (fs.existsSync(staleSearchIndex)) {
         fs.unlinkSync(staleSearchIndex);
     }
-    console.warn(`build-knowledge-index: ${chunks.length} chunks (manifest-lite) from ${sources.length} files`);
+    console.warn(`build-knowledge-index: ${chunks.length} chunks (manifest-lite) from ${sources.length} files; `
+        + `frontmatter files=${frontmatterFileCount}, merged=${frontmatterMergedCount}, parse_errors=${frontmatterParseErrorCount}`);
 }

package/knowledge/chunker.js

@@ -42,6 +42,34 @@ function isFaqLike(source, content) {
 function shouldForceSectionSplit(source, meta) {
     return source.endsWith('unsupported-features.md') || meta.doc_kind === 'unsupported_summary';
 }
+function isBestPracticeSource(source) {
+    return /\/best-practice\//i.test(source.replace(/\\/g, '/'));
+}
+const BEST_PRACTICE_SINGLE_CHUNK_MAX_TOKENS = 4096;
+const LEGACY_SINGLE_CHUNK_CHAR_THRESHOLD = 2048;
+function estimateTextTokens(text) {
+    let tokens = 0;
+    for (const ch of text) {
+        tokens += /[A-Za-z]/.test(ch) ? 0.5 : 1;
+    }
+    return tokens;
+}
+function estimateMarkdownTokens(content) {
+    let tokens = 0;
+    let cursor = 0;
+    const codeBlockRE = /```[\s\S]*?```/g;
+    for (const match of content.matchAll(codeBlockRE)) {
+        const start = match.index ?? cursor;
+        const end = start + match[0].length;
+        tokens += estimateTextTokens(content.slice(cursor, start));
+        tokens += match[0].length * 1.3;
+        cursor = end;
+    }
+    if (cursor < content.length) {
+        tokens += estimateTextTokens(content.slice(cursor));
+    }
+    return tokens;
+}
 function isChatUrlMapping(source) {
     return /knowledge\/chat\/urls\/.+\.md$/i.test(source.replace(/\\/g, '/'));
 }
@@ -86,7 +114,7 @@ function extractKeyPhrases(title, body) {
         .slice(0, 8);
     return [...new Set(phrases)];
 }
-function buildChunk(meta, source, title, body, id, char_start, char_end) {
+function buildChunk(meta, source, title, body, id, char_start, char_end, extra) {
     const api_names = extractApiNames(body);
     const key_phrases = extractKeyPhrases(title, body);
     return {
@@ -101,6 +129,8 @@ function buildChunk(meta, source, title, body, id, char_start, char_end) {
         doc_kind: meta.doc_kind,
         capability_status: meta.capability_status,
         retrievable_scope: meta.retrievable_scope,
+        meta_source: meta.meta_source,
+        meta_override_fields: meta.meta_override_fields,
         title,
         source,
         content: body,
@@ -109,14 +139,15 @@ function buildChunk(meta, source, title, body, id, char_start, char_end) {
         ...(api_names.length ? { api_names } : {}),
         ...(containsCodeBlock(body) ? { contains_code: true } : {}),
         ...(key_phrases.length ? { key_phrases } : {}),
+        ...(extra ?? {}),
         char_start,
         char_end,
     };
 }
-function parseUrlMappingRows(content) {
+function parseUrlMappingRows(content, baseOffset) {
     const lines = content.split('\n');
     let sectionTitle = '';
-    let offset = 0;
+    let offset = baseOffset;
     const rows = [];
     for (const line of lines) {
         const lineStart = offset;
@@ -144,8 +175,8 @@ function parseUrlMappingRows(content) {
     }
     return rows;
 }
-function chunkUrlMapping(source, content, meta) {
-    const rows = parseUrlMappingRows(content);
+function chunkUrlMapping(source, content, meta, baseOffset) {
+    const rows = parseUrlMappingRows(content, baseOffset);
     if (rows.length === 0) {
         return [];
     }
@@ -157,33 +188,70 @@ function chunkUrlMapping(source, content, meta) {
         return buildChunk(meta, source, row.label, body, `${baseSlug}#${headingSlug}`, row.lineStart, row.lineEnd);
     });
 }
-export function chunkMarkdown(source, content, meta) {
+export function chunkMarkdown(source, content, meta, options) {
     const chunks = [];
     const baseSlug = sourceSlug(source);
-    if (isChatUrlMapping(source)) {
-        const urlChunks = chunkUrlMapping(source, content, meta);
+    const baseOffset = options?.baseOffset ?? 0;
+    const policyRule = options?.policyRule;
+    if (isChatUrlMapping(source) || policyRule?.strategy === 'by_row') {
+        const urlChunks = chunkUrlMapping(source, content, meta, baseOffset);
         if (urlChunks.length > 0) {
             return urlChunks;
         }
     }
     const forceSectionSplit = shouldForceSectionSplit(source, meta);
-    if (content.length < 2048 && !forceSectionSplit) {
-        const { body, char_start, char_end } = trimSliceOffsets(content, 0);
+    const isBestPractice = isBestPracticeSource(source);
+    const estimatedTokenCount = estimateMarkdownTokens(content);
+    const defaultSplitThreshold = options?.defaultSplitTokenThreshold ?? LEGACY_SINGLE_CHUNK_CHAR_THRESHOLD;
+    const singleChunkMaxTokens = policyRule?.max_tokens
+        ?? (isBestPractice ? BEST_PRACTICE_SINGLE_CHUNK_MAX_TOKENS : undefined);
+    const shouldSingleChunk = policyRule?.strategy === 'single_chunk_per_file'
+        || (isBestPractice && !policyRule?.strategy);
+    if (shouldSingleChunk && singleChunkMaxTokens !== undefined && estimatedTokenCount <= singleChunkMaxTokens) {
+        const { body, char_start, char_end } = trimSliceOffsets(content, baseOffset);
         if (!body)
             return chunks;
         chunks.push(buildChunk(meta, source, pathBasename(source), body, `${baseSlug}#full`, char_start, char_end));
         return chunks;
     }
-    const level = forceSectionSplit ? 3 : (isFaqLike(source, content) ? 3 : 2);
+    if (!shouldSingleChunk
+        && !forceSectionSplit
+        && content.length < (policyRule?.split_token_threshold ?? defaultSplitThreshold)) {
+        const { body, char_start, char_end } = trimSliceOffsets(content, baseOffset);
+        if (!body)
+            return chunks;
+        chunks.push(buildChunk(meta, source, pathBasename(source), body, `${baseSlug}#full`, char_start, char_end));
+        return chunks;
+    }
+    const fallbackStrategy = policyRule?.split_fallback ?? policyRule?.strategy ?? 'by_h2';
+    const level = forceSectionSplit
+        ? 3
+        : fallbackStrategy === 'by_h3'
+            ? 3
+            : (isFaqLike(source, content) ? 3 : 2);
     const sections = splitByHeading(content, level);
     for (const section of sections) {
-        const { body, char_start, char_end } = trimSliceOffsets(section.raw, section.start);
+        const { body, char_start, char_end } = trimSliceOffsets(section.raw, section.start + baseOffset);
         if (!body)
             continue;
         const headingSlug = slugify(section.title);
-        chunks.push(buildChunk(meta, source, section.title, body, `${baseSlug}#${headingSlug}`, char_start, char_end));
+        const fallbackMeta = shouldSingleChunk && singleChunkMaxTokens !== undefined && estimatedTokenCount > singleChunkMaxTokens
+            ? {
+                split_reason: 'exceed_token_threshold',
+                original_file_token_count: Math.ceil(estimatedTokenCount),
+                aggregable: policyRule?.split_aggregable ?? isBestPractice,
+                parent_h2: section.title,
+            }
+            : undefined;
+        chunks.push(buildChunk(meta, source, section.title, body, `${baseSlug}#${headingSlug}`, char_start, char_end, fallbackMeta));
     }
-    return chunks.length > 0 ? chunks : chunkMarkdown(source, content.slice(0, 2048), meta);
+    return chunks.length > 0
+        ? chunks
+        : chunkMarkdown(source, content.slice(0, defaultSplitThreshold), meta, {
+            baseOffset,
+            policyRule,
+            defaultSplitTokenThreshold: defaultSplitThreshold,
+        });
 }
 export function toManifestChunk(chunk) {
     const { content: _content, ...manifestChunk } = chunk;

package/knowledge/chunking-policy.js

@@ -0,0 +1,100 @@
+import fs from 'fs';
+import path from 'path';
+import * as yaml from 'js-yaml';
+const DEFAULT_POLICY = {
+    default: {
+        strategy: 'by_h2',
+        split_token_threshold: 2048,
+    },
+    rules: [
+        {
+            path_prefix: 'knowledge/chat/best-practice/',
+            strategy: 'single_chunk_per_file',
+            max_tokens: 4096,
+            hard_max_tokens: 8192,
+            split_fallback: 'by_h2',
+            split_aggregable: true,
+        },
+        {
+            path_prefix: 'knowledge/chat/urls/',
+            strategy: 'by_row',
+        },
+    ],
+};
+function toPolicy(raw) {
+    if (!raw || typeof raw !== 'object')
+        return DEFAULT_POLICY;
+    const root = raw;
+    const policyObj = (root.chunking_policy && typeof root.chunking_policy === 'object')
+        ? root.chunking_policy
+        : null;
+    if (!policyObj)
+        return DEFAULT_POLICY;
+    const rawDefault = (policyObj.default && typeof policyObj.default === 'object')
+        ? policyObj.default
+        : {};
+    const strategy = rawDefault.strategy === 'by_h3' ? 'by_h3' : 'by_h2';
+    const splitThreshold = typeof rawDefault.split_token_threshold === 'number'
+        ? rawDefault.split_token_threshold
+        : 2048;
+    const rules = Array.isArray(policyObj.rules)
+        ? policyObj.rules
+            .map((item) => {
+            if (!item || typeof item !== 'object')
+                return null;
+            const rule = item;
+            const pathPrefix = typeof rule.path_prefix === 'string' ? rule.path_prefix.trim() : '';
+            const strategyValue = typeof rule.strategy === 'string' ? rule.strategy : '';
+            if (!pathPrefix || !['single_chunk_per_file', 'by_h2', 'by_h3', 'by_row'].includes(strategyValue)) {
+                return null;
+            }
+            return {
+                path_prefix: pathPrefix,
+                strategy: strategyValue,
+                max_tokens: typeof rule.max_tokens === 'number' ? rule.max_tokens : undefined,
+                hard_max_tokens: typeof rule.hard_max_tokens === 'number' ? rule.hard_max_tokens : undefined,
+                split_fallback: rule.split_fallback === 'by_h3' ? 'by_h3' : (rule.split_fallback === 'by_h2' ? 'by_h2' : undefined),
+                split_aggregable: typeof rule.split_aggregable === 'boolean' ? rule.split_aggregable : undefined,
+                split_token_threshold: typeof rule.split_token_threshold === 'number' ? rule.split_token_threshold : undefined,
+            };
+        })
+            .filter((rule) => Boolean(rule))
+        : [];
+    return {
+        default: {
+            strategy,
+            split_token_threshold: splitThreshold,
+        },
+        rules,
+    };
+}
+function extractYamlBlock(markdown) {
+    const match = markdown.match(/```ya?ml\n([\s\S]*?)\n```/i);
+    return match?.[1] ?? null;
+}
+export function loadChunkingPolicy(policyFilePath) {
+    if (!fs.existsSync(policyFilePath)) {
+        return DEFAULT_POLICY;
+    }
+    try {
+        const markdown = fs.readFileSync(policyFilePath, 'utf-8');
+        const yamlBlock = extractYamlBlock(markdown);
+        if (!yamlBlock)
+            return DEFAULT_POLICY;
+        const parsed = yaml.load(yamlBlock);
+        return toPolicy(parsed);
+    }
+    catch {
+        return DEFAULT_POLICY;
+    }
+}
+export function resolveChunkingRule(source, policy) {
+    const normalized = source.replace(/\\/g, '/');
+    const matched = policy.rules
+        .filter((rule) => normalized.startsWith(rule.path_prefix.replace(/\\/g, '/')))
+        .sort((a, b) => b.path_prefix.length - a.path_prefix.length);
+    return matched[0];
+}
+export function resolvePolicyFilePath(knowledgeDirname) {
+    return path.resolve(knowledgeDirname, '../../../chunking-policy.md');
+}

package/knowledge/content-loader.js

@@ -4,7 +4,9 @@ import { fileURLToPath } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const fileCache = new Map();
 function resolveResourceRoot() {
-    // npm: knowledge/ → ../resource/ 到包根；dev: dist/knowledge/ → ../resource/ 到 dist/resource/
+    // 运行时读 md 源目录（与 knowledge/ 同级的 resource/）：
+    //   npm 包：<pkg>/knowledge/  →  <pkg>/resource/
+    //   本地：  dist/knowledge/   →  dist/resource/（依赖 build 时 copy-resource.js）
     return path.resolve(__dirname, '../resource');
 }
 function readSourceFile(source) {

package/knowledge/frontmatter-meta.js

@@ -0,0 +1,167 @@
+import * as yaml from 'js-yaml';
+const FRONTMATTER_RE = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+function uniq(arr) {
+    return [...new Set(arr)];
+}
+function normalizeString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized ? normalized : undefined;
+}
+function normalizeStringArray(value) {
+    if (Array.isArray(value)) {
+        const normalized = value
+            .map((item) => (typeof item === 'string' ? item.trim() : ''))
+            .filter(Boolean);
+        return normalized.length ? uniq(normalized) : undefined;
+    }
+    if (typeof value === 'string') {
+        const normalized = value
+            .split(',')
+            .map((item) => item.trim())
+            .filter(Boolean);
+        return normalized.length ? uniq(normalized) : undefined;
+    }
+    return undefined;
+}
+function normalizeScenario(value) {
+    if (value === 'live' || value === 'voice')
+        return value;
+    return undefined;
+}
+function normalizeVariant(value) {
+    if (value === 'core-sdk' || value === 'preset')
+        return value;
+    return undefined;
+}
+function normalizeDocKind(value) {
+    if (value === 'capability_matrix' || value === 'unsupported_summary' || value === 'negative_faq') {
+        return value;
+    }
+    return undefined;
+}
+function normalizeCapabilityStatus(value) {
+    if (value === 'supported' || value === 'unsupported' || value === 'partial' || value === 'version_gated') {
+        return value;
+    }
+    return undefined;
+}
+function normalizeRetrievableScope(value) {
+    if (value === 'always')
+        return 'always';
+    return normalizeStringArray(value);
+}
+function parseFrontmatterObject(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        return {};
+    }
+    return input;
+}
+export function resolveFrontmatterMeta(rawMarkdown) {
+    const match = rawMarkdown.match(FRONTMATTER_RE);
+    if (!match) {
+        return {
+            content: rawMarkdown,
+            contentOffset: 0,
+            hasFrontmatter: false,
+            frontmatterMeta: {},
+            overrideFields: [],
+        };
+    }
+    const rawBlock = match[1] ?? '';
+    const contentOffset = match[0].length;
+    const content = rawMarkdown.slice(contentOffset);
+    let parsed;
+    try {
+        parsed = yaml.load(rawBlock);
+    }
+    catch (error) {
+        const parseError = error instanceof Error ? error.message : String(error);
+        return {
+            content,
+            contentOffset,
+            hasFrontmatter: true,
+            parseError,
+            frontmatterMeta: {},
+            overrideFields: [],
+        };
+    }
+    const fm = parseFrontmatterObject(parsed);
+    const frontmatterMeta = {};
+    const overrideFields = [];
+    const product = normalizeString(fm.product);
+    if (product) {
+        frontmatterMeta.product = product;
+        overrideFields.push('product');
+    }
+    const framework = normalizeStringArray(fm.frameworks) ?? normalizeStringArray(fm.framework);
+    if (framework?.length) {
+        frontmatterMeta.framework = framework;
+        overrideFields.push('framework');
+    }
+    const types = normalizeStringArray(fm.types);
+    if (types?.length) {
+        frontmatterMeta.types = types;
+        overrideFields.push('types');
+    }
+    const scenario = normalizeScenario(fm.scenario);
+    if (scenario !== undefined) {
+        frontmatterMeta.scenario = scenario;
+        overrideFields.push('scenario');
+    }
+    const variant = normalizeVariant(fm.variant);
+    if (variant) {
+        frontmatterMeta.variant = variant;
+        overrideFields.push('variant');
+    }
+    const scope = normalizeString(fm.scope);
+    if (scope) {
+        frontmatterMeta.scope = scope;
+        overrideFields.push('scope');
+    }
+    const docKind = normalizeDocKind(fm.doc_kind);
+    if (docKind) {
+        frontmatterMeta.doc_kind = docKind;
+        overrideFields.push('doc_kind');
+    }
+    const capabilityStatus = normalizeCapabilityStatus(fm.capability_status);
+    if (capabilityStatus) {
+        frontmatterMeta.capability_status = capabilityStatus;
+        overrideFields.push('capability_status');
+    }
+    const retrievableScope = normalizeRetrievableScope(fm.retrievable_scope);
+    if (retrievableScope) {
+        frontmatterMeta.retrievable_scope = retrievableScope;
+        overrideFields.push('retrievable_scope');
+    }
+    return {
+        content,
+        contentOffset,
+        hasFrontmatter: true,
+        frontmatterMeta,
+        overrideFields: uniq(overrideFields),
+    };
+}
+export function mergePathMetaWithFrontmatter(pathMeta, frontmatterMeta, overrideFields) {
+    if (!overrideFields.length) {
+        return {
+            ...pathMeta,
+            meta_source: 'path',
+            meta_override_fields: [],
+        };
+    }
+    const merged = {
+        ...pathMeta,
+        meta_source: 'merged',
+        meta_override_fields: uniq(overrideFields),
+    };
+    for (const field of overrideFields) {
+        const value = frontmatterMeta[field];
+        if (value === undefined)
+            continue;
+        // PathMeta 字段由 frontmatter 显式声明时优先；未声明字段保留路径推断兜底。
+        merged[field] = value;
+    }
+    return merged;
+}