b2507adf0a
铸渊 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 索引页, 不再报错
139 lines
3.5 KiB
Markdown
139 lines
3.5 KiB
Markdown
# 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 · 豆包立刻懂
|