From fa832f2f8245afdaf013ed8a1f689152972386b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=86=B0=E6=9C=94?= <565183519@qq.com> Date: Tue, 14 Jul 2026 19:29:10 +0800 Subject: [PATCH] docs: redesign public V2 search API landing page --- README.md | 269 ++++++++++++++++++++---------------------------------- 1 file changed, 100 insertions(+), 169 deletions(-) diff --git a/README.md b/README.md index ad52cc0..3e289ba 100644 --- a/README.md +++ b/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: -``` - -verifier 算法:`HMAC-SHA256(LIGHT_LAKE_DRIVER_SECRET, "ICE-GL∞|ICE-GL-ZY001|")[: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。