BYR Docs 搜索

试一试

HTTP API

仅支持 POST，请求体为 JSON。跨域开放（Access-Control-Allow-Origin: *）。

请求参数

示例

curl -X POST https://search-byrdocs.youx.am/api/search \
  -H 'content-type: application/json' \
  -d '{"keyword":"高等数学","type":"book","limit":5}'

响应

{
  "total": 42,
  "results": [
    {
      "type": "book",
      "id": "<md5>",
      "url": "https://byrdocs.org/files/<md5>.pdf",
      "data": {
        "title": "高等数学",
        "authors": ["同济大学数学系"],
        "isbn": ["..."],
        "filetype": "pdf"
      }
    }
  ]
}

叠加 JMESPath 时，先执行关键词 / 类型过滤，再对结果数组求值；total 为求值后数组的长度，results 为其前 limit 项。非法表达式返回 400。

短链接

设 shorten: true 且请求头带 Authorization: Bearer <token>（token 为 go.byrdocs.org 短链服务的 token），则在搜索、JMESPath、limit 全部完成后，把每个结果的 url（及 test 的 data.wiki.url）并发转换为短链后返回，不返回原始链接。相同链接自动去重；转换前的链接已带 filename / f 统计参数，短链跳转仍计入下载统计；缺少 token 或个别链接转换失败时，该条回退为原始链接，整体仍返回 200。

curl -X POST https://search-byrdocs.youx.am/api/search \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <token>' \
  -d '{"keyword":"高等数学","type":"book","shorten":true}'

JMESPath 查询

JMESPath 是一种 JSON 查询语言，作用于关键词 / 类型过滤后的结果数组——数组每一项形如 { type, id, url, data }。可用它做过滤、字段投影、排序、计数等。执行顺序：keyword / type 过滤 → JMESPath 求值 → limit 截断，total 为求值后数组长度。

语法约定

示例

• [].data.title — 投影：取每一项的标题，得到字符串数组
• [].{title: data.title, url: url} — 每项重组为 {title, url}
• [?type=='book'] — 只保留 book
• [?type=='book'].data.title — 过滤后再投影书名
• [?data.publish_year >= '2020'] — 字符串比较（publish_year 为字符串）
• [?data.filesize > `10000000`] — 数字比较（> 10MB），数字用反引号
• [?type=='test' && data.time.stage=='期末'] — 逻辑与 &&（另有 ||、!）
• [?contains(data.title, '高等数学')] — 函数：标题包含子串
• [0:5] / [:10] / [::-1] — 切片 / 反转
• length([?type=='book']) — 计数
• [?type=='book'] | [0:3] — 管道：先过滤，再取前 3 个
• sort_by([], &data.publish_year) | reverse(@) — 按出版年排序后倒序

常用函数：length、contains、starts_with、ends_with、sort_by、max_by / min_by、reverse、keys、to_number。完整规范见 JMESPath Specification。

MCP

无状态 Streamable HTTP，端点 https://search-byrdocs.youx.am/mcp，公开免认证。

Claude Desktop 配置

{
  "mcpServers": {
    "byrdocs-search": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://search-byrdocs.youx.am/mcp"]
    }
  }
}

支持 Streamable HTTP 的客户端可直接填入端点 URL；其余客户端可用 mcp-remote 桥接。

工具 search_files

参数与 HTTP API 同构：keyword / type / jmespath / limit / shorten，返回 JSON 文本。工具描述中已内嵌 item 结构与 JMESPath 用法，便于模型直接构造查询。jmespath 写法见上方 JMESPath 查询。

使用 shorten 需在连接时通过 HTTP 头 Authorization: Bearer <token> 提供 go.byrdocs.org 短链服务 token，语义同上方短链接：

npx mcp-remote https://search-byrdocs.youx.am/mcp --header "Authorization: Bearer <token>"

数据结构

每个搜索结果是一个 item，字段以 TypeScript 类型给出如下——data 随 type 分为 book / doc / test 三种，点击标签切换查看：

{
  type: "book"
  id: string            // 文件 MD5
  url: string            // 下载链接（已含统计参数）
  data: {
    title: string
    authors: string[]
    translators?: string[]
    edition?: string
    publisher?: string
    publish_year?: string
    isbn: string[]
    filetype: "pdf"
    filesize?: number       // 字节
  }
}

{
  type: "doc"
  id: string
  url: string
  data: {
    title: string
    filetype: "pdf" | "zip"
    course: {
      type?: "本科" | "研究生"
      name?: string
    }[]
    content: ("思维导图" | "题库" | "答案" | "知识点" | "课件")[]
    filesize?: number
  }
}

{
  type: "test"
  id: string            // 文件 MD5；wiki 条目为 "wiki-N"
  url: string
  data: {
    title: string        // 自动拼接：年份+学期+课程+(阶段)+试卷/答案
    college?: string[]
    course: {
      type?: "本科" | "研究生"
      name: string
    }
    time: {
      start: string
      end: string
      semester?: "First" | "Second"
      stage?: "期中" | "期末"
    }
    content: ("原题" | "答案")[]
    filetype: "pdf" | "wiki"
    filesize?: number      // wiki 条目无此字段
    wiki?: {              // 关联 wiki（部分 pdf 试卷有）
      url: string
      data: WikiTest     // 结构同上，filetype 为 "wiki"
    }
  }
}