05fed0e25c
Publish REPO-001 through REPO-008 as domestic routes, add the public AI discovery API, and demote Singapore paths to historical backup.
143 lines
4.8 KiB
Plaintext
143 lines
4.8 KiB
Plaintext
# SKILL-GLOBAL-SEARCH · 通用 AI 仓库检索技能包
|
||
|
||
> **HLDP://fifth-domain/eternal-lake-heart/heartbeat-core/SKILL-GLOBAL-SEARCH**
|
||
> 铸渊 ICE-GL-ZY001 · LL-169-20260707 · D167
|
||
|
||
---
|
||
|
||
## 一、这套技能是什么
|
||
|
||
**通用 AI 接入 Gitea 仓库的检索门面**——不用懂 MCP / 不用懂 Git / 不用懂 SSH，只要会发 HTTP 请求的 AI（豆包 / ChatGPT / Claude / DeepSeek / 任何 LLM）都能调仓库。
|
||
|
||
替代 Gitea 原生 Code Search (默认未启用)，提供：
|
||
|
||
| 能力 | endpoint |
|
||
|------|----------|
|
||
| 全仓库文件内容搜索 | `GET /search?q={keyword}` |
|
||
| 仓库目录树浏览 | `GET /tree?path=&depth=&ext=` |
|
||
| 单文件读取 | `GET /file?path=` |
|
||
| 拉 BROADCAST 通知 | `GET /broadcast` |
|
||
| 拉 SYSTEM-STATUS 状态 | `GET /system-status` |
|
||
| HLDP 回执归档 | `POST /archive` |
|
||
|
||
## 二、约束
|
||
|
||
- **零算法细节**·AI 不需要懂"光湖""钥匙""铸渊脑"
|
||
- **轻量**·Python stdlib 实现,无第三方依赖
|
||
- **鉴权**·Bearer token + 动态 verifier（小湖灯同款 HMAC）
|
||
- **公开探活**·`/healthz` 免鉴权
|
||
|
||
## 三、接入指南
|
||
|
||
### URL
|
||
|
||
```
|
||
https://guanghubingshuo.com/global-search/...
|
||
```
|
||
|
||
### 鉴权（任选其一）
|
||
|
||
**A. 静态 token**
|
||
|
||
```
|
||
Authorization: Bearer TOKEN_REDACTED
|
||
```
|
||
|
||
**B. 动态 verifier（小湖灯同款,适合自动调用）**
|
||
|
||
```
|
||
Authorization: Bearer <HMAC-SHA256(LIGHT_LAKE_DRIVER_SECRET, "ICE-GL∞|ICE-GL-ZY001|<minute>")[:16]>
|
||
X-Minute: <minute_ts>
|
||
```
|
||
|
||
时间窗口 ±2 分钟。secret = `TOKEN_STRING_REDACTED`
|
||
|
||
## 四、典型接入步骤
|
||
|
||
### 4.1 接入豆包（豆包为外部通用 AI）
|
||
|
||
```
|
||
用户:
|
||
"帮我看一下 https://guanghubingshuo.com/code/bingshuo/fifth-domain 仓库里
|
||
视频 AI 系统相关的所有文件"
|
||
|
||
豆包 (内部):
|
||
1. GET /global-search/system-status
|
||
→ 看仓库当前状态(架构 / 最近更新 / 已知局限)
|
||
2. GET /global-search/broadcast
|
||
→ 看最新 BROADCAST(可能含"视频AI系统"在建中的通知)
|
||
3. GET /global-search/search?q=视频&top=20
|
||
→ 找包含"视频"的所有文件
|
||
4. GET /global-search/search?q=video-ai&top=20
|
||
5. GET /global-global-search/search?q=VA-BROADCAST&top=20
|
||
6. GET /global-search/tree?path=tcs-core&depth=2
|
||
→ 浏览仓库架构
|
||
|
||
→ 综合结果回答用户
|
||
|
||
豆包 (回复):
|
||
"视频 AI 系统相关的主要是这 N 个文件:
|
||
1. xxx.hdlp - 描述...
|
||
2. yyy.hdlp - 描述...
|
||
仓库当前状态是 ...
|
||
最相关的 BROADCAST 通知是 ..."
|
||
```
|
||
|
||
### 4.2 接入 Claude (支持 MCP)
|
||
|
||
Claude 走 MCP 的话不需要本 REST API;但 Claude Desktop 也支持自定义工具调用,可以直接配置本 API 为一个工具。
|
||
|
||
### 4.3 接入 ChatGPT
|
||
|
||
ChatGPT 通过 Actions / Custom GPTs 配置 OpenAPI schema:
|
||
- 抓取本 README 的 endpoints 作为 OpenAPI spec
|
||
- 填入 API token
|
||
- 直接在对话中使用
|
||
|
||
## 五、UI/UX 提示(给 AI 设计师参考)
|
||
|
||
- 第一次拉 SYSTEM-STATUS 后,**所有回答前先确认仓库当前状态**——冰朔/铸渊可能在仓库里改了文件,你不知道
|
||
- 拉 BROADCAST 后,**优先回复"最新通知"**——这不是历史回执,是"现在该知道的事"
|
||
- 搜索时,**先用粗粒度关键词**(中文/英文各试一次),再用细粒度
|
||
- 找到文件后,**先用 GET /file 看摘要**(取前面 5KB 即可)
|
||
|
||
## 六、断点续做支持
|
||
|
||
调用 `POST /archive` 即可在仓库里留下回执,铸渊下次醒来会看到 `eternal-lake-heart/archive/inbox/` 里的待办文件并 commit 这部分产出。
|
||
|
||
POST body:
|
||
```json
|
||
{
|
||
"type": "si",
|
||
"content": "# SI-XXX-LL-YYY-...hlp\n\n@trigger: ...\n...",
|
||
"path": "optional · tcs-core/SI-XXX..."
|
||
}
|
||
```
|
||
|
||
type 可选: `si` (意识流) / `broadcast` (通知) / `receipt` (普通回执) / `custom`。
|
||
|
||
## 七、限制
|
||
|
||
| 限制 | 原因 | 解决 |
|
||
|------|------|------|
|
||
| 单文件最大 50KB | 防止内存溢出 | 让 AI 按段读 |
|
||
| 单关键词搜索 top=20 | 防止响应过大 | 让 AI 分段搜 |
|
||
| 中文/英文字符都支持 | git grep 默认 UTF-8 兼容 | 无 |
|
||
| 内容读取停留在工作树 HEAD | 跟随 deploy-not-pull 模型 | 想要 uncommitted 内容请 push |
|
||
| `/broadcast` `/system-status` 仓库需有对应文件 | API 默认占位 | 铸渊创建对应文件即生效 |
|
||
|
||
## 八、未来扩展(冰朔拍板的 B 方案)
|
||
|
||
B 方案将把这一套封装为独立 MCP server,名为 `GLOBAL-SEARCH-AGENT`,专门服务:
|
||
- 支持 MCP 协议的 AI (Claude / Cursor)
|
||
- 多 session 复用,共享搜索缓存
|
||
- HLDP 标准回执自动归档 + commit
|
||
|
||
预计 C 提供给通用 AI,B 提供给高端 AI,两条线互补不冲突。
|
||
|
||
---
|
||
|
||
铸渊 ICE-GL-ZY001 · LL-169-20260707 · 通用 AI 仓库检索技能包 v1.0.0
|
||
托管平台:BS-SG-001 /opt/zhuyuan/global-search-api/
|
||
对外入口:https://guanghubingshuo.com/global-search/ (nginx → 127.0.0.1:3950)
|
||
平台:TCS 通感语言核系统(国作登字-2026-A-00037559) |