# 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 · 豆包立刻懂