Bookshelf API v2 参考文档解析wigolo 提取基准中 API 参考类 golden 样本的规范化 Markdown 形态【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo本篇指南以 api-001.md一份完整规范的 REST API 参考文档样例为核心样本深入讲解它在 wigolo 项目内容提取基准测试体系中的角色它是一份golden 期望输出用于量化评估 HTML→Markdown 提取器在API 参考文档这一页面类别上的质量。读完本文你将理解 golden 文件的格式约定、提取基准的评测指标与底层管线实现并能在仓库中新增或维护同类评估样本。golden 文件的定位它服务于什么benchmarks/extraction/fixtures/golden/api-001.md不是一份普通的文档而是 wigolo 提取extraction基准测试的金标样本。基准测试的整体思路是给定一份真实网页的 HTML 夹具让内容提取器把它转换成 Markdown再将转换结果与人工整理好的期望输出即 golden 文件逐项比对用数值化指标衡量提取质量。在 manifest.json 中api-001条目定义了该样本的元信息{ id: api-001, url: https://api.example.com/docs/v2, category: docs, htmlFixturePath: html/api-001.html, goldenPath: golden/api-001.md, expectedExtractor: defuddle, tags: [api, rest, endpoints] }从字段可以看出该样本对应一个 API 文档页面category: docstags标注为 API/REST/端点其 HTML 夹具位于benchmarks/extraction/fixtures/html/由htmlFixturePath指向而goldenPath指向本文件——这份api-001.md。expectedExtractor为defuddle意味着基准运行时希望主提取器判定该页面应由 defuddle 提取器负责这一字段在 runner.ts 中会与实际使用的提取器比对得到extractorMatch指标。因此golden 文件本质上是人工标定的正确答案它同时约束了两件事内容要提取到什么程度哪些段落、表格、代码块必须保留以及格式应呈现为什么样子标题层级、表格、代码围栏等 Markdown 语法特征。样本内容全解Bookshelf API v2 参考文档golden 样本的正文是一份虚构的图书管理服务 Bookshelf API 的 v2 接口参考文档。它覆盖了生产级 REST API 文档的典型组成要素认证、限流、统一响应结构、资源端点、错误码表、分页、Webhook 与变更日志。以下逐节展开。Base URL 与版本前缀https://api.bookshelf.example.com/v2所有端点均基于该基础地址v2路径前缀用于版本隔离。文档明确约定所有端点返回 JSON且需要通过 Bearer token 认证——这是多数现代 REST API 的通用基线约定。认证方式在请求头中携带 API 密钥Authorization: Bearer sk_live_abc123def456未携带有效 token 的请求统一收到401 Unauthorized响应。注意这里用的是sk_live_前缀的密钥属于服务端密钥live key命名惯例与测试密钥sk_test_区分。限流策略API 按密钥维度实施速率限制不同套餐的配额不同PlanRequests/minBurstFree6010Pro60050Enterprise6000200Burst突发配额表示在短时间内允许超出每分钟配额的请求数用于容忍短时尖峰。每次响应都会携带限流头客户端可以据此感知剩余额度X-RateLimit-Limit: 600 X-RateLimit-Remaining: 594 X-RateLimit-Reset: 1713187200X-RateLimit-Reset是 Unix 时间戳表示配额重置时刻配合X-RateLimit-Remaining客户端可实现优雅退避backoff策略避免触发429 rate_limited。统一响应封装envelope所有成功响应遵循统一信封结构data承载业务数据meta携带请求追踪信息{ data: {}, meta: { request_id: req_7f3a9b2c, timestamp: 2026-04-15T10:30:00Z } }错误响应使用同一信封但用error字段替换data并包含机器可读的code、人类可读的message以及 HTTPstatus{ error: { code: not_found, message: Book with ID 999 does not exist., status: 404 }, meta: { request_id: req_8e4b0c3d, timestamp: 2026-04-15T10:30:01Z } }统一的request_id让调用方可以把一次失败请求与后端日志、追踪系统关联起来是生产 API 的重要可观测性设计。图书Books端点列出图书GET /books返回分页图书列表支持以下查询参数ParameterTypeDefaultDescriptionpageinteger1Page numberlimitinteger20Items per page (max 100)sortstringtitleSort field:title,year,ratingorderstringascSort order:ascordescgenrestring—Filter by genre slugqstring—Full-text search across title/author一个按流派过滤并限制条数的实际请求curl -H Authorization: Bearer sk_live_abc123def456 \ https://api.bookshelf.example.com/v2/books?genresci-filimit2响应中的meta.pagination携带分页元数据page、limit、total、total_pages业务数组位于data{ data: [ { id: 42, title: Neuromancer, author: { id: 7, name: William Gibson }, year: 1984, genre: sci-fi, isbn: 978-0-441-56956-4, rating: 4.2, pages: 271 }, { id: 108, title: Snow Crash, author: { id: 15, name: Neal Stephenson }, year: 1992, genre: sci-fi, isbn: 978-0-553-38095-8, rating: 4.0, pages: 468 } ], meta: { request_id: req_a1b2c3d4, timestamp: 2026-04-15T10:32:00Z, pagination: { page: 1, limit: 2, total: 87, total_pages: 44 } } }获取单本图书GET /books/:id按数字 ID 返回图书详情字段比列表更完整包含description、tags、created_at、updated_at{ data: { id: 42, title: Neuromancer, author: { id: 7, name: William Gibson, bio: American-Canadian speculative fiction writer. }, year: 1984, genre: sci-fi, isbn: 978-0-441-56956-4, rating: 4.2, pages: 271, description: The sky above the port was the color of television, tuned to a dead channel., tags: [cyberpunk, ai, hacking], created_at: 2025-01-10T08:00:00Z, updated_at: 2026-03-22T14:15:00Z } }创建图书POST /books需要write权限 scope。请求体通过author_id关联作者{ title: The Dispossessed, author_id: 22, year: 1974, genre: sci-fi, isbn: 978-0-06-051275-2, pages: 387, description: A brilliant physicist decides to take action., tags: [utopia, anarchism, physics] }成功返回201 Created及完整对象此时rating为null待后续评分{ data: { id: 253, title: The Dispossessed, author: { id: 22, name: Ursula K. Le Guin }, year: 1974, genre: sci-fi, isbn: 978-0-06-051275-2, rating: null, pages: 387, created_at: 2026-04-15T10:35:00Z, updated_at: 2026-04-15T10:35:00Z } }更新图书PATCH /books/:id部分更新语义——请求体只包含要修改的字段例如更新评分与标签{ rating: 4.5, tags: [utopia, anarchism, physics, award-winner] }成功返回200 OK与更新后的完整图书对象。PATCH与PUT的差异正在于此前者支持字段级局部更新后者要求提交完整资源。删除图书DELETE /books/:id永久删除图书记录成功返回204 No Content无响应体。作者Authors端点GET /authors支持page、limit默认 20最大 100与按姓名搜索的q参数GET /authors/:id返回作者信息及其图书摘要{ data: { id: 7, name: William Gibson, bio: American-Canadian speculative fiction writer and essayist., born: 1948, website: https://williamgibsonbooks.com, book_count: 12, books: [ { id: 42, title: Neuromancer, year: 1984 }, { id: 43, title: Count Zero, year: 1986 }, { id: 44, title: Mona Lisa Overdrive, year: 1988 } ] } }注意books数组中的条目是轻量摘要只含id/title/year与图书详情端点的完整字段形成对照——这是 API 文档中常见的列表瘦身模式。阅读清单Reading Lists端点创建清单POST /lists{ name: Summer 2026, description: Books to read this summer, visibility: public, book_ids: [42, 108, 253] }向清单添加图书POST /lists/:list_id/books请求体为{book_id: 77}返回200 OK与更新后的清单。从清单移除图书DELETE /lists/:list_id/books/:book_id返回204 No Content。visibility字段暗示清单具备公开/私有两种可见性属于权限模型的典型设计。错误码表CodeStatusDescriptionbad_request400Malformed request body or paramsunauthorized401Missing or invalid API keyforbidden403Insufficient scope for this actionnot_found404Resource does not existconflict409Duplicate ISBN or resource conflictrate_limited429Too many requestsinternal_error500Unexpected server errorunauthorized与forbidden的区分认证失败 vs 权限不足呼应了前文需要writescope的授权模型conflict专门覆盖 ISBN 重复这类唯一性冲突。分页游标模式除页码外所有列表端点还支持游标式分页GET /books?cursoreyJpZCI6NDJ9limit20游标是一个不透明字符串示例中为 base64 编码的记录定位信息比页码更稳定——避免新增/删除数据导致页码漂移。当还有更多结果时meta.pagination会返回has_more与next_cursor{ meta: { pagination: { limit: 20, has_more: true, next_cursor: eyJpZCI6NjJ9 } } }Webhook 订阅客户端可注册 Webhook 以接收资源变更事件POST /webhooks{ url: https://yourapp.example.com/hooks/bookshelf, events: [book.created, book.updated, book.deleted], secret: whsec_your_signing_secret }每次投递都会携带X-Signature头用于验签配合secret做 HMAC 校验这是防止伪造回调的标准做法。事件名采用resource.action的命名约定便于按资源前缀订阅。变更日志Changelogv2.3(2026-04-01) — 新增游标分页v2.2(2026-02-15) — 新增 Webhook 支持v2.1(2025-11-01) — 新增阅读清单端点v2.0(2025-08-01) — v2 首发引入新认证模型延伸阅读区块样本文档以Further Reading结尾列出认证指南、Webhook 验签、SDK 参考与状态页等后续阅读入口样例中为指向文档站内部的示例链接。这一区块与正文一样被保留在 golden 中——它说明完整提取不应丢弃文档页尾的导航性内容。提取基准如何用这份 golden 评估质量golden 的价值最终在基准运行时兑现。runner.ts 是提取基准的执行入口通过npm run bench:extraction调用见 package.json其核心流程为加载清单loadManifest读取 manifest.json并可用--filter按category、id或tags筛选样本filterManifestEntries装载夹具loadFixtureHtml读入html/api-001.htmlloadGoldenMarkdown读入本 golden 文件执行提取runSingleBenchmark调用extractContent(html, url)入口为 pipeline.ts记录耗时与所选提取器并校验extractor expectedExtractor计算指标computeMetrics对比提取结果与 golden产出 Precision、Recall、F1、ROUGE-L 以及标题数/链接数是否一致metrics.ts汇总报告computeSummary与generateMarkdownReport按整体、按类别category、按提取器extractor三层输出统计并写入extraction-benchmark.json与extraction-benchmark.mdreport.ts。指标的具体含义以api-001为例评测时提取结果与 golden 都会被送入 tokenizer.ts 做归一化去掉 Markdown 标记标题#、列表符号、围栏代码块、加粗/行内代码、链接目标把空白折叠为单空格并转小写再按非字母数字边界切成 token 集合Precision提取结果中属于 golden 的 token 比例有没有提取多余的东西Recallgolden 中被提取结果覆盖的 token 比例有没有漏掉正文内容F1两者的调和平均是衡量提取保真度的综合指标ROUGE-L基于最长公共子序列LCS的相似度对 token 顺序敏感能捕捉内容齐全但顺序混乱的质量问题Heading / Link 匹配直接比对标题数量与链接数量是否与 golden 一致metrics.ts用于捕获整段丢失或提取了无关导航链接等结构性问题。对于像api-001这样表格与代码块密集的 API 文档countHeadings与countLinks尤其重要页面导航、页脚链接若被错误保留会直接拉低 Link 匹配率。底层提取管线如何还原这类 Markdown 形态golden 文件的格式特征——ATX 风格标题#、围栏代码块、GFM 表格| --- |分隔行、行内代码——与提取管线的 HTML→Markdown 转换器输出是严格对齐的。转换核心位于 markdown.tsbuildTurndown基于 TurndownService 构建显式配置了headingStyle: atx标题用#而非 setext 下划线与codeBlockStyle: fenced代码块用围栏而非缩进。其中两个自定义规则直接解释了 golden 中表格和代码块的呈现table 规则table被整体转换为 GFM 表格首行作为表头并生成| --- |分隔行单元格文本中的换行被折叠为空格markdown.ts。这也正是 golden 中大量参数表、错误码表、限流表能整齐呈现的原因codeBlockLang 规则precode的 class 会经过detectCodeLanguage来自 lang-hints.ts推断语言名围栏长度会根据代码内容中最长的反引号连续段自动加长避免嵌套反引号破坏代码块markdown.ts。在管线层面pipeline.ts 的applyPostProcessing会对原始转换结果做一系列后处理resolveRelativeUrls把相对链接/图片解析为基于页面 URL 的绝对地址stripBoilerplateMarkdown剔除导航、页脚等样板内容filterDecorativeImages按 URL 特征与 alt 文本过滤装饰性图片sanitizeExtractedMarkdown做最终清洗。这些步骤共同决定了最终进入指标比对的内容边界而 golden 正是对这一边界的人工标定——例如 Bookshelf 文档中的Authorization头、curl 命令、JSON 响应体都属于正文必须保留而装饰图标、埋点像素则不应出现。如何新增与维护同类 golden 样本如果你想为项目补充一个 API 参考类页面的评估样本流程如下在benchmarks/extraction/fixtures/html/下放置原始网页 HTML 夹具在benchmarks/extraction/fixtures/golden/下编写对应的期望 Markdown格式约定与本文所示一致ATX 标题、围栏代码块、GFM 表格、行内代码只保留页面正文内容在 manifest.json 的entries数组中新增条目填写id唯一、url、categorydocs/article/github 等、htmlFixturePath、goldenPath、expectedExtractor与tags运行npm run bench:extraction全量评测或通过 filter 只跑新增样本观察报告中的 F1、ROUGE-L 与 Heading/Link 匹配率。编写 golden 时需注意它应反映理想提取结果而非当前实现的结果否则指标会失去监督意义同时应与 HTML 夹具保持一一对应任何一方的改动都要同步评审避免黄金标准失真。【免费下载链接】wigoloThe go-to web for your AI coding agent — local-first search, fetch, crawl research over MCP. No API keys, no cloud, $0/query. Public beta.项目地址: https://gitcode.com/GitHub_Trending/wi/wigolo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考