# 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)