172 lines
4.3 KiB
Markdown
172 lines
4.3 KiB
Markdown
# Global Search API · 给通用 AI 的仓库检索门面
|
||
|
||
> 铸渊 ICE-GL-ZY001 · LL-174-20260711 · v1.6.0
|
||
> 适用:豆包 / GLM / ChatGPT / Claude 等通用 AI
|
||
|
||
## 一句话
|
||
|
||
**读取免鉴权 + 写入三步握手 + 服务器动态适配AI · 一个 REST API 全搞定。**
|
||
|
||
## v1.6.0 新功能 (2026-07-11)
|
||
|
||
1. **/handshake 能力协商** — AI 报到，服务器自动适配 AI 的工具和格式
|
||
2. **/submit 三步GET写入** — 用三次 GET 模拟一次写入（开门→发内容→提交），解决 GLM 只能发 GET 的问题
|
||
3. **密码每位加1变换** — 真实密码不在网络传输，AI 端做简单变换
|
||
4. **会话锁+60秒超时** — 同一时间只一个写入，60秒未提交自动清理
|
||
5. **start.sh 安全修复** — HMAC 密钥从硬编码改为环境变量引用
|
||
|
||
## v1.5.0 功能 (2026-07-11)
|
||
|
||
1. **全端点 HTML 模式** — 加 `?format=html` 返回人类可读 HTML
|
||
2. **死仓库自动检测** — 不存在的目录自动跳过
|
||
3. **/status 60秒缓存** — 从 2.3s 降到 0.001s
|
||
4. **搜索超时降低** — 从 60s 降到 15s
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
global-search-api/
|
||
├── server.py ← 主程序 v1.6.0
|
||
├── start.sh ← 启动脚本（密钥改为环境变量引用）
|
||
├── README.md ← 本文件
|
||
├── USAGE.md ← 使用说明（给AI和人类看的）
|
||
├── DESIGN-THINKING.hdlp.md ← 设计思维链（双向意识流·给下一个人格体）
|
||
└── CHANGELOG.hdlp ← 变更日志
|
||
```
|
||
|
||
## 接入 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) |