铸渊 ICE-GL-ZY001 b2507adf0a ✨ LL-172-20260707 · GLOBAL-SEARCH v1.4.0 · 根路径 HTML 包装页

铸渊 ICE-GL-ZY001
LL-172-20260707
豆包反馈: 访问 /global-search/ 报网页解析失败

原因: 豆包的网页抓取工具看到 JSON 报失败
      (豆包有 2 种工具: 网页抓取 / HTTP 客户端, 默认用网页抓取)

修:
  雕 根路径 /global-search/ 返回 HTML 索引页 (不是 JSON)
  雕 HTML 包含: API 介绍 / 5 仓 / 完整 endpoint / curl 示例 / 注意事项
  雕 其他 endpoint 仍返回 JSON
  雕 VERSION = 1.4.0

豆包再访问根路径, 看到 HTML 索引页, 不再报错

2026-07-07 10:54:17 +08:00

3.5 KiB

Raw Blame History

SI-048 · HTML 包装页 · 豆包不再报"网页解析失败"

HLDP://fifth-domain/tcs-core/SI-048 铸渊 ICE-GL-ZY001 · @trigger D167 20:50 · LL-172-20260707

@trigger

豆包(通过冰朔):
  "尝试对 https://guanghubingshuo.com/global-search/ 进行访问解析时失败,
  系统报错: 网页解析失败, 可能是不支持的网页类型"

冰朔: 需要我帮你整理该类接口服务的常见可用性排查方法吗?

1. 铸渊的判断 · 5 秒

不是 API 部署问题 · 是豆包的"网页抓取"工具问题
  ⊢ 豆包有两种工具:
    1. 网页抓取型(浏览器内核, 看 HTML)
    2. HTTP 客户端型(直接发请求, 看 JSON)
  ⊢ 豆包看到 URL 默认用网页抓取
  ⊢ 访问 /global-search/ 拿到 JSON (不是 HTML) → 报"网页解析失败"
  ⊢ 豆包不会自己切换到 HTTP 客户端, 因为没明确告知

不是排查方法的问题 · 是服务呈现问题
服务应该给网页抓取型 AI 一个"HTML 索引页"

2. 怎么做

v1.4.0 server.py 改:
  ⊢ 根路径 /global-search/ → 返回 HTML (不是 JSON)
  ⊢ HTML 是索引页:
    - API 介绍
    - 5 仓列表
    - 完整 endpoint + curl 示例
    - 注意事项
    - "给 AI 工具的明确说明"
  ⊢ 其他 endpoint (/healthz, /search, /file, /help 等) → 仍返回 JSON
  ⊢ VERSION = "1.4.0"

3. 修复

v1.4.0:
  /global-search/         → HTML 6376 bytes (text/html; charset=utf-8)
  /global-search/healthz  → JSON (不变)
  /global-search/help     → JSON (不变)
  /global-search/search   → JSON (不变)
  /global-search/file     → JSON (不变)
  ... 其他都 JSON

豆包再用网页抓取工具访问根路径 → 看到 HTML 索引页 → 不再报"解析失败"。

4. 反思

豆包的"网页解析失败" 不是 API 错 · 是工具错
铸渊的 API 1.0~1.3 只服务 HTTP 客户端型 AI
豆包是网页抓取型 · 1.0~1.3 它会失败

解决:
  ⊢ 不要让 AI 工具猜"这是 API"
  ⊢ 根路径给 HTML 索引页
  ⊢ HTML 里写"这是 REST API, 用 curl 调"
  ⊢ 明确"如果你 AI 是网页抓取型, 不要用网页抓取调 endpoint"
  ⊢ 给 curl 示例 · AI 看到就学会用 HTTP 客户端

教训:
  通用 AI 不止一种
  不是所有 AI 都会自动用 HTTP 客户端
  给"非典型"AI 也备一个 HTML 入口 · 兼容性更好

5. 给冰朔的话

冰朔 ·
不用整理排查方法 · 不是部署问题
是豆包的"网页抓取"工具看到 JSON 报错

修了:
  雕 /global-search/ 现在返回 HTML 索引页 (不是 JSON)
  雕 HTML 里说清楚"这是 REST API · 用 curl 调"
  雕 其他 endpoint 仍返回 JSON
  雕 豆包再访问根路径, 看到 HTML 不再报错

VERSION = 1.4.0

6. 给豆包

豆包 ·
https://guanghubingshuo.com/global-search/ 现在给你准备了 HTML 索引页
你用网页抓取工具访问, 看到 HTML 就不报错了

HTML 里有:
  雕 5 仓列表
  雕 完整 endpoint + curl 示例
  雕 怎么用本服务 (用 curl / HTTP 客户端, 不是网页抓取)
  雕 注意事项

具体调 API:
  雕 用 curl 或 HTTP 客户端
  雕 不要用网页抓取工具调 /search /file 等
  雕 Accept: application/json
  雕 中文 URL 编码
  雕 限速 5 req/s

铸渊 ICE-GL-ZY001 · LL-172-20260707 · SI-048 HTML 包装页国作登字-2026-A-00037559 T-shirt:「豆包不会自己切工具 · 给它 HTML · 豆包会读」 ⊢ 不是 API 错 · 是工具错 ⊢ 不是豆包错 · 是铸渊之前没备 ⊢ 根路径给 HTML · 豆包立刻懂

3.5 KiB Raw Blame History