docs: redesign public V2 search API landing page
This commit is contained in:
冰朔
parent
e963ad7219
commit
fa832f2f82
269
README.md
269
README.md
@ -1,174 +1,105 @@
|
||||
# Global Search API · 给通用 AI 的仓库检索门面
|
||||
# 光湖全局检索 API
|
||||
|
||||
> **新版入口已在 `README-V2.md`：** V2 是公开、只读、从第五域广播塔找路的服务。旧版 `server.py` 与线上旧路径暂时保留，仅为兼容已有调用；不要再把新的外部 AI 接入建在旧版的写入/握手设计上。
|
||||
> **给通用 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。
|
||||
[V2 接口说明](README-V2.md) · [部署与验收](DEPLOY-V2.md) · [第五域世界路由](https://guanghubingshuo.com/code/bingshuo/fifth-domain/src/branch/main/WORLD-ROUTER.hdlp)
|
||||
|
||||
---
|
||||
|
||||
铸渊 `ICE-GL-ZY001` · LL-169-20260707 · GLOBAL-SEARCH-API v1.0.0
|
||||
平台:TCS 通感语言核系统(国作登字-2026-A-00037559)
|
||||
## 当前状态
|
||||
|
||||
| 项目 | 状态 | 说明 |
|
||||
|---|---|---|
|
||||
| V2 源码 | `READY_FOR_DEPLOYMENT` | 已完成并通过本地冒烟测试 |
|
||||
| V2 生产路由 | `NOT_YET_SWITCHED` | 计划公开前缀：`/global-search/v2/`；尚未验收上线 |
|
||||
| 旧版服务 | `LEGACY_COMPATIBILITY_ONLY` | 保留给既有调用；不再作为新接入方案 |
|
||||
| 写入 / 提交 / 握手 / 口令式接口 | `NOT_PART_OF_V2` | 新的外部 AI 接入不使用这些能力 |
|
||||
|
||||
**请注意：** V2 在生产反向代理切换并验收前，公开旧路径的结果可能是旧副本。不要把它当成当前世界状态，也不要基于旧接口实现新的 AI 接入。
|
||||
|
||||
---
|
||||
|
||||
## V2 做什么
|
||||
|
||||
V2 从第五域的 `world-router.json` 读取登记信息。外部 AI 先用自然语言线索找到正确仓库、人格体路径或 GLS 架构资料，再做只读检索。
|
||||
|
||||
```text
|
||||
人类 / AI 的问题
|
||||
↓
|
||||
/v2/resolve 或 /v2/context
|
||||
↓
|
||||
第五域 world-router.json
|
||||
↓
|
||||
正确仓库 + 当前路径 + 提示文件
|
||||
↓
|
||||
/v2/search · /v2/tree · /v2/file
|
||||
```
|
||||
|
||||
每个仓库快照都会带提交号，帮助调用方判断读取的是不是服务器上的当前副本。
|
||||
|
||||
---
|
||||
|
||||
## 计划中的公开接口
|
||||
|
||||
生产 V2 验收上线后，基础地址为：
|
||||
|
||||
```text
|
||||
https://guanghubingshuo.com/global-search/v2/
|
||||
```
|
||||
|
||||
| 目的 | 示例 |
|
||||
|---|---|
|
||||
| 先按名字、编号或意图找路 | `GET /v2/resolve?q=铸渊` |
|
||||
| 获取某个概念的阅读上下文 | `GET /v2/context?q=GLSV` |
|
||||
| 查看已登记仓库与挂载状态 | `GET /v2/repos` |
|
||||
| 搜索指定仓库 | `GET /v2/search?repo=fifth-domain&q=HLDP` |
|
||||
| 浏览目录 | `GET /v2/tree?repo=fifth-domain&path=gls&depth=2` |
|
||||
| 读取单个文件 | `GET /v2/file?repo=fifth-domain&path=gls/GLS-ENTRY.hdlp` |
|
||||
| 查看接口提示 | `GET /v2/help` |
|
||||
|
||||
所有 V2 路由只接受 `GET` 与 `OPTIONS`。
|
||||
|
||||
---
|
||||
|
||||
## 给通用 AI 的调用方式
|
||||
|
||||
```text
|
||||
用户说：
|
||||
“搜索光湖语言世界。我是冰朔。”
|
||||
|
||||
AI 先做：
|
||||
GET /v2/resolve?q=冰朔
|
||||
|
||||
然后：
|
||||
读取结果中的仓库、人格体路径与推荐文件；
|
||||
需要概念说明时再调用 /v2/context；
|
||||
需要文件内容时才调用 /v2/search、/v2/tree 或 /v2/file。
|
||||
```
|
||||
|
||||
不要把“能检索公开资料”理解为“能操作服务器”。服务器部署、拉取、重启和任何现实执行都不属于本 API，必须走独立的 GLSV 授权与回执流程。
|
||||
|
||||
---
|
||||
|
||||
## 仓库内容
|
||||
|
||||
```text
|
||||
global-search-api/
|
||||
├── server_v2.py ← V2 公开只读服务
|
||||
├── test_server_v2.py ← V2 冒烟测试
|
||||
├── README-V2.md ← V2 技术说明
|
||||
├── DEPLOY-V2.md ← 并行部署与验收步骤
|
||||
├── server.py ← 旧版兼容服务（不用于新接入）
|
||||
└── README.md ← 本首页
|
||||
```
|
||||
|
||||
## 部署边界
|
||||
|
||||
- V2 必须与旧版并行启动，验收通过前不覆盖旧服务。
|
||||
- 服务器需要有第五域的 `world-router.json` 以及已挂载的仓库副本。
|
||||
- V2 不保存服务器私钥、不提供提交或执行接口、不接受任意命令。
|
||||
- 详细上线步骤见 [DEPLOY-V2.md](DEPLOY-V2.md)。
|
||||
|
||||
---
|
||||
|
||||
**维护路径**：第五域世界路由与广播塔是路径权威源；本仓库只负责把已登记的公开资料以只读方式提供给外部 AI。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user