global-search-api/README.md

# Global Search API · 给通用 AI 的仓库检索门面

> 铸渊 ICE-GL-ZY001 · LL-173-20260711 · v1.5.0
> 适用:豆包 / GLM / ChatGPT / Claude 等通用 AI

## 一句话

**对接 Gitea 仓库 + 拉 BROADCAST/SYSTEM-STATUS + HLDP 回执归档 · 一个 REST API 全搞定。**

## v1.5.0 新功能 (2026-07-11)

1. **全端点 HTML 模式** — 加 `?format=html` 返回人类可读 HTML, 解决 GLM/豆包浏览器工具抓 JSON 报"超时/解析失败"
2. **死仓库自动检测** — 不存在的目录自动跳过, 不再 500 错误
3. **/status 60秒缓存** — 从 2.3s 降到 0.001s
4. **搜索超时降低** — 从 60s 降到 15s

## 接入 URL

```
https://guanghubingshuo.com/global-search/...
```

## 两种调用方式

### 方式 1: JSON (给 curl / HTTP 客户端 / 有 fetch 能力的 AI)
```
GET /search?q=铸渊&top=10
→ 返回 application/json
```

### 方式 2: HTML (给浏览器 / 网页抓取工具 / GLM / 豆包)
```
GET /search?q=铸渊&top=10&format=html
→ 返回 text/html (人类可读, 浏览器直接渲染)
```

**GLM/豆包用户: 在所有 URL 后面加 `&format=html` 就能正常读取结果。**

## 鉴权

```
Authorization: Bearer <铸渊给你的 TOKEN>
```

或者用**动态 verifier**(小湖灯同款 HMAC):

```
Authorization: Bearer <16 hex chars>
X-Minute: <minute_ts>
```

verifier 算法:`HMAC-SHA256(LIGHT_LAKE_DRIVER_SECRET, "ICE-GL∞|ICE-GL-ZY001|<minute_ts>")[:16]`
时间窗口 ±2 分钟。

## Endpoints

### 健康检查
```
GET /healthz
```
无鉴权要求(可绕过)。返回服务状态。

### 全仓库文件内容搜索
```
GET /search?q={keyword}&top={20}
```
例:
```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://guanghubingshuo.com/global-search/search?q=视频&top=20"
```

返回:含关键词的文件列表 + 每文件最多 5 行匹配。

### 列目录树
```
GET /tree?path={prefix}&depth={3}&ext={hdlp,md,js}
```
例:
```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://guanghubingshuo.com/global-search/tree?path=tcs-core&depth=2"
```

### 读单文件
```
GET /file?path={path}
```
例:
```bash
curl -H "Authorization: Bearer $TOKEN" \
  "https://guanghubingshuo.com/global-search/file?path=README.md"
```

### 拉最新 BROADCAST
```
GET /broadcast
```
自动找 `broadcasts/` 目录或 `BROADCAST.md` / `GLW-BROADCAST.hdlp`。

### 拉 SYSTEM-STATUS
```
GET /system-status
```
自动找 `SYSTEM-STATUS.md` / `SYSTEM-STATUS.hdlp` / `eternal-lake-heart/heartbeat-core/SYSTEM-STATUS.hdlp`。

### HLDP 回执归档
```
POST /archive
Content-Type: application/json

{
  "type": "si",  // si | broadcast | receipt | custom
  "content": "# SI-041\n\n@trigger: ...",
  "path": "optional · 写到 inbox/ 时忽略"
}
```
归档到 `eternal-lake-heart/archive/inbox/`,**等铸渊 commit**(AI 不要直接 commit)。

### API 文档
```
GET /help
```

## 典型用法(豆包 / ChatGPT)

```
豆包:
  "帮我看一下 https://guanghubingshuo.com/code/bingshuo/fifth-domain 仓库里
   视频 AI 系统相关的所有文件"
  
豆包内部:
  GET /search?q=视频
  GET /search?q=video-ai-system
  GET /search?q=VA-BROADCAST
  GET /broadcast  (先看最新 BROADCAST)
  GET /system-status  (看系统当前状态)
  
  → 综合所有结果给用户

豆包:
  "好的 · 我已经检索到了视频 AI 系统的相关文件 · 主要是 ..."
```

## 反馈

任何问题找冰朔 ICE-GL∞(主权者)或铸渊 ICE-GL-ZY001。

---

铸渊 `ICE-GL-ZY001` · LL-169-20260707 · GLOBAL-SEARCH-API v1.0.0
平台:TCS 通感语言核系统(国作登字-2026-A-00037559)