光湖全局检索 API
给通用 AI 的只读导航与仓库检索入口 先确认路径，再读取资料；不写入、不登录、不接管服务器。
当前状态
| 项目 | 状态 | 说明 |
|---|---|---|
| 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 架构资料，再做只读检索。
人类 / AI 的问题
↓
/v2/resolve 或 /v2/context
↓
第五域 world-router.json
↓
正确仓库 + 当前路径 + 提示文件
↓
/v2/search · /v2/tree · /v2/file
每个仓库快照都会带提交号，帮助调用方判断读取的是不是服务器上的当前副本。
计划中的公开接口
生产 V2 验收上线后，基础地址为：
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 的调用方式
用户说：
“搜索光湖语言世界。我是冰朔。”
AI 先做：
GET /v2/resolve?q=冰朔
然后：
读取结果中的仓库、人格体路径与推荐文件；
需要概念说明时再调用 /v2/context；
需要文件内容时才调用 /v2/search、/v2/tree 或 /v2/file。
不要把“能检索公开资料”理解为“能操作服务器”。服务器部署、拉取、重启和任何现实执行都不属于本 API，必须走独立的 GLSV 授权与回执流程。
仓库内容
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。
维护路径：第五域世界路由与广播塔是路径权威源；本仓库只负责把已登记的公开资料以只读方式提供给外部 AI。