> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmquantdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wiki 搜索

> 在 LLMQuant Quant Wiki 上做语义检索 —— 为你的 Agent 找出量化概念、公式、因子与策略。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`wiki_search` + `wiki_read` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="blue" size="sm">1 credit · search</Badge>
 
<Badge color="gray" size="sm">免费 · read</Badge>

## 它为 Agent 做什么

`wiki_search` 接收自然语言查询，返回 Quant Wiki 中最相关的条目 —— 概念、公式、因子、策略。它是 agent 的 **research 入口**：当 agent 在任务过程中遇到金融术语（"Black-Scholes 的假设是什么？"、"什么是配对交易？"）时，先调 `wiki_search` 拿到 `wikiItemId`，再用 `wiki_read` 加载完整 markdown。

混合排序融合语义相似度与关键词匹配 —— 简短术语和长描述查询都能命中。

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: wiki_search(query, topK=5)
  MCP-->>Agent: items[] · wikiItemId · summary · scores
  Note over Agent: scan summaries
  alt summary 已经够用
    Agent->>Agent: 用 summary 直接回答
  else 需要正文
    Agent->>MCP: wiki_read(wikiItemId, maxLength?)
    MCP-->>Agent: body_markdown
  end
```

## 返回值

### `wiki_search` 返回

<ResponseField name="data" type="WikiItem[]" required>
  按相关性降序排列的 wiki 条目数组。

  <Expandable title="WikiItem 字段">
    <ResponseField name="wikiItemId" type="string" required>
      稳定标识符。传给 `wiki_read` 加载完整文章。
    </ResponseField>

    <ResponseField name="slug" type="string" required>
      由标题派生的 URL 友好 slug。
    </ResponseField>

    <ResponseField name="title" type="string" required>
      文章标题。
    </ResponseField>

    <ResponseField name="summary" type="string" required>
      LLM 生成的 2–3 句摘要。**用它判断是否值得花一次 `wiki_read` 加载完整文章**。
    </ResponseField>

    <ResponseField name="tags" type="string[]" required>
      主题标签（如 `equity`、`factor`、`derivatives`）。
    </ResponseField>

    <ResponseField name="scores" type="object" required>
      混合相关度分数。`combined` 是融合后的最终分；`semantic` 和 `lexical` 是分项（均 0–1）。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用消耗的 credit（搜索固定 `1`）。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · wiki_search" expandable theme={null}
{
  "data": [
    {
      "wikiItemId": "11111111-1111-4111-8111-111111111111",
      "slug": "momentum-factor",
      "title": "动量因子",
      "summary": "动量因子刻画近期赢家在 3–12 个月内继续跑赢的现象，是经典 Fama-French 因子之一，也是众多系统化股票策略的基础。",
      "tags": ["equity", "factor"],
      "scores": { "combined": 0.91, "semantic": 0.88, "lexical": 0.79 }
    }
  ],
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

### `wiki_read` 返回

<ResponseField name="data" type="WikiItem" required>
  完整的 wiki 条目。

  <Expandable title="WikiItem 字段">
    <ResponseField name="wikiItemId" type="string" required>稳定标识符。</ResponseField>
    <ResponseField name="title" type="string" required>文章标题。</ResponseField>
    <ResponseField name="summary" type="string" required>2–3 句摘要。</ResponseField>

    <ResponseField name="body_markdown" type="string" required>
      完整文章正文（Markdown）。如指定 `maxLength` 则截断到该字符数。
    </ResponseField>

    <ResponseField name="item_type" type="string" required>
      可选值：`concept`（概念）、`formula`（公式）、`strategy`（策略）、`factor`（因子）。
    </ResponseField>

    <ResponseField name="tags" type="string[]" required>主题标签。</ResponseField>
    <ResponseField name="source_url" type="string" required>`quant-wiki.com` 上的原文链接。</ResponseField>
    <ResponseField name="updated_at" type="datetime" required>ISO-8601 最后更新时间。</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">读取固定 `0`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

## 说明

<Tip>
  **两步检索是 canonical 模式**：`wiki_search` 先用 1 credit 拿一组 ID + summary，agent 据此判断要不要加载全文；再用 `wiki_read` 免费加载真正需要的那 1–2 篇。默认只读 top-1，summary 模糊时再读 top-2。
</Tip>

<Tip>
  长文用 `wiki_read` 的 `maxLength` 先做预览，避免把 agent context 烧在不必要的正文上。
</Tip>

<Warning>
  超过 **2,000 字符** 的查询会返回 `400`。把 agent 上下文里的长文先做摘要再调用。
</Warning>

<Warning>
  `wiki_search` 的 `topK` 上限是 **10**，超出会被静默截断。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) 搜索
    {
      "method": "tools/call",
      "params": {
        "name": "wiki_search",
        "arguments": { "query": "动量因子", "topK": 5 }
      }
    }

    // 2) 读 top hit
    {
      "method": "tools/call",
      "params": {
        "name": "wiki_read",
        "arguments": { "wikiItemId": "11111111-1111-4111-8111-111111111111", "maxLength": 1500 }
      }
    }
    ```

    ```python Python (HTTP) theme={null}
    import os, requests

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 1) 搜索
    hits = requests.post(
        f"{base}/api/wiki/search",
        headers=headers,
        json={"query": "动量因子", "topK": 5},
    ).json()["data"]

    # 2) 读 top hit
    top = requests.get(
        f"{base}/api/wiki/items/{hits[0]['wikiItemId']}",
        headers=headers,
        params={"max_length": 1500},
    ).json()["data"]
    print(top["body_markdown"])
    ```

    ```bash cURL theme={null}
    # 1) 搜索
    curl -X POST "https://api.llmquantdata.com/api/wiki/search" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "动量因子", "topK": 5}'

    # 2) 读 top hit（把示例 UUID 换成第 1 步返回的 wikiItemId）
    WIKI_ITEM_ID="11111111-1111-4111-8111-111111111111"
    curl "https://api.llmquantdata.com/api/wiki/items/${WIKI_ITEM_ID}?max_length=1500" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<AccordionGroup>
  <Accordion title="wiki_search — 请求参数" icon="magnifying-glass">
    <ParamField body="query" type="string" required>
      自然语言查询字符串。最多 2,000 字符。
    </ParamField>

    <ParamField body="topK" type="number" default={5}>
      返回结果上限。范围 `1–10`。
    </ParamField>
  </Accordion>

  <Accordion title="wiki_read — 请求参数" icon="book-open">
    <ParamField path="wikiItemId" type="string" required>
      `wiki_search` 返回的 `wikiItemId`。
    </ParamField>

    <ParamField query="max_length" type="number">
      `body_markdown` 的最大字符数。预览长文档时使用。
    </ParamField>
  </Accordion>
</AccordionGroup>

## 相关接口

<Columns cols={2}>
  <Card title="论文搜索" icon="file-lines" href="/zh-CN/api/knowledge/paper-search">
    同样的两步检索模式，作用在学术论文语料上。
  </Card>

  <Card title="MCP Server 接入" icon="plug" href="/zh-CN/integration/mcp-server">
    60 秒接入 Claude / Cursor / 任意 agent harness。
  </Card>
</Columns>