# 光湖全局检索 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。