106 lines
3.5 KiB
Markdown
106 lines
3.5 KiB
Markdown
# 光湖全局检索 API
|
||
|
||
> **给通用 AI 的只读导航与仓库检索入口**
|
||
> 先确认路径，再读取资料；不写入、不登录、不接管服务器。
|
||
|
||
[V2 接口说明](README-V2.md) · [部署与验收](DEPLOY-V2.md) · [第五域世界路由](https://guanghubingshuo.com/code/bingshuo/fifth-domain/src/branch/main/WORLD-ROUTER.hdlp)
|
||
|
||
---
|
||
|
||
## 当前状态
|
||
|
||
| 项目 | 状态 | 说明 |
|
||
|---|---|---|
|
||
| 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。
|