global-search-api/USAGE.md

# Global Search API · 使用说明

> 铸渊 ICE-GL-ZY001 · v1.6.0 · 2026-07-11
> 给通用 AI（GLM / 豆包 / ChatGPT / Claude）用的仓库检索+写入门面

---

## 1. 基本信息

```
公网入口: https://guanghubingshuo.com/global-search/
内网端口: 3950
版本: v1.6.0
```

---

## 2. 读取（免鉴权）

所有 GET 读取端点免鉴权，直接用。

### 2.1 搜索文件内容
```
GET /search?q=关键词&top=10&repo=fifth-domain
```

### 2.2 读单文件
```
GET /file?path=README.md&repo=fifth-domain
```

### 2.3 列目录树
```
GET /tree?depth=2&repo=fifth-domain
```

### 2.4 综合状态
```
GET /status
```

### 2.5 健康检查
```
GET /healthz
```

### 2.6 HTML 模式（给浏览器/GLM/豆包用）
在任意 URL 后面加 `&format=html`，返回人类可读 HTML：
```
GET /search?q=铸渊&top=10&format=html
```

---

## 3. 写入（三步握手 + 密码验证）

通用 AI 只有 GET 工具（浏览器抓取），不能发 POST。
本系统用三次 GET 模拟一次写入。

### 3.0 密码规则

冰朔设一个密码（纯数字或数字+字母），存在服务器环境变量 `GLOBAL_SEARCH_WRITE_PASSWORD` 中。

AI 发请求前，**密码每位数字加 1**：
```
原密码: 128515
变换后: 239626
  1→2, 2→3, 8→9, 5→6, 1→2, 5→6
```

字母不变。只变数字。0 加 1 变 1，9 加 1 变 0（循环）。

### 3.1 第一步：开门

```
GET /submit?action=open&pwd=239626&repo=fifth-domain
```

服务器验证密码 → 通过 → 返回会话 ID：
```json
{
  "ok": true,
  "session": "write_1783706246",
  "timeout": 60,
  "message": "门已开，请发送内容"
}
```

60 秒内必须完成写入，否则会话自动过期。

### 3.2 第二步：发送内容（可多次）

```
GET /submit?action=write&sid=write_1783706246&content=这是要写入的内容
```

内容太长时，分多次发送：
```
GET /submit?action=write&sid=write_1783706246&content=第一段
GET /submit?action=write&sid=write_1783706246&content=第二段
GET /submit?action=write&sid=write_1783706246&content=第三段
```

服务器自动拼接。每次返回已接收的段数：
```json
{
  "ok": true,
  "received": 2,
  "message": "内容已暂存"
}
```

**支持 base64 编码**：如果内容含特殊字符，先 base64 编码再发送，服务器自动解码。

### 3.3 第三步：提交写入

```
GET /submit?action=commit&sid=write_1783706246&filename=my-file.txt
```

服务器把暂存内容写入仓库的 `eternal-lake-heart/archive/inbox/` 目录：
```json
{
  "ok": true,
  "written": true,
  "file": "my-file.txt",
  "repo": "fifth-domain",
  "path": "eternal-lake-heart/archive/inbox/my-file.txt",
  "size": 156,
  "message": "写入成功，等待铸渊 commit"
}
```

写入后等铸渊 git commit + push 到正式仓库。

### 3.4 查看写入状态

```
GET /submit?action=status
```

返回当前活跃的写入会话。

---

## 4. AI 报到（能力协商）

通用 AI 第一次使用时，先报到，服务器自动适配：

```
GET /handshake?agent=GLM&tools=browser&format=html&max_url=2000
```

| 参数 | 说明 | 示例 |
|------|------|------|
| agent | AI 的名字 | GLM / 豆包 / ChatGPT |
| tools | AI 有什么工具 | browser / curl / function_calling |
| format | AI 期望的返回格式 | html / json |
| max_url | AI 能处理的最大 URL 长度 | 2000 / 8000 |

服务器返回适配信息，包括写入时的分片大小：
```json
{
  "ok": true,
  "session": "GLM_1783706246",
  "your_format": "html",
  "write_chunk_size": 1800,
  "write_steps": ["1. open", "2. write", "3. commit"],
  "password_rule": "密码每位数字加1。例如128515→239626。字母不变。"
}
```

---

## 5. 完整使用流程（给 GLM/豆包的示例）

```
1. 报到
   GET /handshake?agent=GLM&tools=browser&format=html&max_url=2000
   → 服务器记住 GLM 的能力

2. 找冰朔要密码
   AI: "我需要写入密码"
   冰朔: "128515"

3. 密码变换
   AI 在推理中: 128515 → 每位加1 → 239626

4. 开门
   GET /submit?action=open&pwd=239626&repo=fifth-domain&format=html
   → 服务器返回 session ID

5. 发送内容（可多次）
   GET /submit?action=write&sid=<session>&content=第一段内容&format=html
   GET /submit?action=write&sid=<session>&content=第二段内容&format=html

6. 提交
   GET /submit?action=commit&sid=<session>&filename=output.txt&format=html
   → 写入成功
```

---

## 6. 安全机制

| 层 | 机制 | 说明 |
|---|------|------|
| 1 | 密码每位加1 | 真实密码不在网络传输 |
| 2 | HTTPS | 传输加密 |
| 3 | 会话锁 | 同一时间只允许一个写入 |
| 4 | 60秒超时 | 开门后60秒未提交自动丢弃 |
| 5 | 文件名安全检查 | 防路径穿越 |
| 6 | 写入到 inbox/ | 不直接进正式仓库，等铸渊审核 |
| 7 | 读取限速 | 5 req/s per IP |

---

## 7. 服务器配置

### 环境变量

```bash
GLOBAL_SEARCH_WRITE_PASSWORD=冰朔设的密码    # 写入密码
GLOBAL_SEARCH_API_TOKEN=原有token            # POST /archive 用
LIGHT_LAKE_DRIVER_SECRET=原有HMAC密钥         # 从代码仓库移除，只在服务器环境变量里
```

### 重启服务

```bash
# 在服务器上
cd /opt/zhuyuan/global-search-api
git pull
systemctl restart global-search-api
```

---

铸渊 ICE-GL-ZY001 · D170 · 2026-07-11
⊢ 使用说明 · v1.6.0 · 永久更新