@tencentcloud/sdk-mcp 1.6.7 → 1.7.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# CHANGELOG
+
+## Version 1.7.0 @2026.08.02
+
+### 新增
+- 补充并同步 Chat / Call / Live / Room 等产品域最佳实践文档，增强知识覆盖范围。
+
+### 变更
+- 持续重构双语检索链路，优化 query 归一化、意图路由、候选过滤与精确命中策略。
+- 优化最佳实践与 URL 类文档的召回与排序，提升问答结果可用性与稳定性。
+- 优化 `search_trtc_knowledge` 相关定义与答复约束，提升回答可读性与可执行性。
+
+### 修复
+- 修复复杂问法下部分检索结果偏题的问题，降低高分误召回概率。
+
+## Version 1.6.6 @2026.07.18
+
+### 新增
+- 支持 `get_native_live_uikit_integration` 工具，支持 LiveKit(Android/iOS) 含 UI 集成。
+
+## Version 1.6.0 @2026.07.01
+
+### 新增
+- 重构 MCP 检索能力，收敛 MCP 工具数量。
+- 支持 `search_trtc_knowledge` 工具，支持实时音视频（TRTC/IM）相关文档检索。

package/README.md

@@ -1,42 +1,29 @@
-## Tencent SDK Model Context Protocol (MCP) Server for Cursor IDE
+## 腾讯云 SDK MCP Server 使用说明
 
-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.
+本仓库提供一个基于 CLI 的 Model Context Protocol（MCP）Server，向 LLM 工具暴露腾讯云 SDK 文档与 API 资料，帮助 AI Agent 更准确地理解并集成腾讯云实时音视频能力。
 
 
-## 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.
-- 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`.
+- **高效检索**：支持腾讯云实时音视频文档检索，快速定位官方资料与实践说明。
+- **覆盖全面**：支持 Chat（IM）、Call、Live、Room、RTCEngine（TRTC SDK）、TIMPush 等产品域。
+- **智能路由**：支持产品/平台语义识别与消歧，在必要时引导补齐平台与框架信息。
+- **集成友好**：除文档问答外，提供 Web / Android / iOS / Flutter 等含 UI 集成入口。
+- **官方可信**：基于官方资料，提升答案可靠性与可落地性。
+- **广泛兼容**：通过 STDIN/STDOUT 的 JSON-RPC 提供 MCP 能力，可接入 Cursor / Codex / Claude / CodeBuddy 等 MCP 客户端。
+- **开箱即用**：`npx` 即可运行，低接入门槛。
 
+## 环境要求
+- Node.js（>= 18）与 npm
+- 支持 MCP 的 IDE
 
-## Prerequisites
-- Node.js (>= 18) and npm
-- Cursor IDE with MCP support
 
+## 使用方式
+### 标准接入流程
 
-## How To Use
-To set up the @tencentcloud/sdk-mcp MCP Server, follow these steps:
+- Step1：在你的 Cursor 项目中，创建或编辑 `.cursor/mcp.json` 或 `~/.cursor/mcp.json`，添加如下配置。
 
-- Step1: Installation.
-
-```
-npx -y @tencentcloud/sdk-mcp
-```
-
-
-- Step2: In your Cursor project, create or open the `.cursor/mcp.json` or `~/.cursor/mcp.json` files and add your config.
-
-```javascript
+```json
 {
   "mcpServers": {
     "tencentcloud-sdk-mcp": {
@@ -50,16 +37,48 @@ npx -y @tencentcloud/sdk-mcp
   }
 }
 ```
-When you save the file, a notification is displayed. In the prompt, click **Enable**.
+保存后会弹出提示，在提示中点击 **Enable**。
 
 ![mcp-server-prompt](https://web.sdk.qcloud.com/im/assets/images/mcp-server-prompt.png)
 
-- Step3: Navigate to **Cursor Settings** (the gear icon in top right corner) -> **MCP**, and check if tencentcloud-sdk-mcp server is enabled.
+- Step2：进入 **Cursor Settings**（右上角齿轮）-> **MCP**，确认 `tencentcloud-sdk-mcp` 已启用。
 
 ![cursor-setting](https://web.sdk.qcloud.com/im/assets/images/cursor-setting.png)
 
+- Step3：在 IDE 中直接描述你的需求，让 AI 基于腾讯云 SDK 文档完成实现或答疑。
+
+### 可选：全局安装
+
+如需在本地全局快速调用，可先执行：
+
+```bash
+npx -y @tencentcloud/sdk-mcp
+```
+
+## 更新记录
+
+> 仅展示最近更新，完整历史请查看 `CHANGELOG.md`。
+
+### Version 1.7.0 @2026.08.02
+
+#### 新增
+- 补充并同步 Chat / Call / Live / Room 等产品域最佳实践文档，增强知识覆盖范围。
+
+#### 变更
+- 持续重构双语检索链路，优化 query 归一化、意图路由、候选过滤与精确命中策略。
+- 优化最佳实践与 URL 类文档的召回与排序，提升问答结果可用性与稳定性。
+- 优化 `search_trtc_knowledge` 相关定义与答复约束，提升回答可读性与可执行性。
+
+#### 修复
+- 修复复杂问法下部分检索结果偏题的问题，降低高分误召回概率。
+
+### Version 1.6.6 @2026.07.18
+
+#### 新增
+- 支持 `get_native_live_uikit_integration` 工具，支持 LiveKit(Android/iOS) 含 UI 集成。
 
-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.
+#### 新增
+- 重构 MCP 检索能力，收敛 MCP 工具数量。
+- 支持 `search_trtc_knowledge` 工具，支持实时音视频（TRTC/IM）相关文档检索。

package/knowledge/build-index.js

@@ -3,9 +3,14 @@ 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));
-const RESOURCE_ROOT = path.resolve(__dirname, '../../resource');
+// 构建期写入索引到 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))
         return [];
@@ -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;
+}