Guanghu Domestic Migration b69c03d60e chore: import sanitized domestic snapshot for REPO-003

Source snapshot: fa832f2f8245afdaf013ed8a1f689152972386b5

2026-07-17 15:55:11 +08:00

5.7 KiB

Raw Permalink Blame History

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 鉴权说明

密码直接发送，靠 HTTPS 加密传输。不搞伪安全变换。

密码存在服务器环境变量 GLOBAL_SEARCH_WRITE_PASSWORD 中（服务器存 SHA256 哈希，不存明文）
AI 发送时带上：密码 + 当前时间戳（时间戳 ±120 秒有效，防重放）
传输安全由 HTTPS 保证
应用层防护：时间戳防重放 + 跨进程文件锁防并发 + 内容大小限制

3.1 第一步：开门

GET /submit?action=open&pwd=你的密码&ts=当前时间戳&repo=fifth-domain

时间戳用 Unix 时间戳（秒），比如 1720651200。

服务器验证密码 → 通过 → 返回会话 ID：

{
  "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=第三段

服务器自动拼接。每次返回已接收的段数：

{
  "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/ 目录：

{
  "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

服务器返回适配信息，包括写入时的分片大小：

{
  "ok": true,
  "session": "GLM_1783706246",
  "your_format": "html",
  "write_chunk_size": 1800,
  "write_steps": ["1. open", "2. write", "3. commit"],
  "auth_note": "密码明文发送(靠HTTPS) + 时间戳防重放(±120秒)"
}

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

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

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

3. 获取当前时间戳
   AI 获取当前 Unix 时间戳（秒）

4. 开门
   GET /submit?action=open&pwd=128515&ts=<时间戳>&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	HTTPS	传输加密（nginx TLS 反代）
2	密码 SHA256 哈希存储	服务器不存明文密码
3	时间戳 ±120秒	防重放攻击
4	hmac.compare_digest	恒定时间比较，防时序攻击
5	跨进程文件锁(fcntl)	同一时间只允许一个写入，多 worker 也安全
6	60秒会话超时	开门后60秒未提交自动丢弃+释放锁
7	内容大小限制	单次50KB，会话总计500KB
8	文件名安全检查	防路径穿越 + 防覆盖
9	secrets.token_hex 会话ID	防会话ID猜测
10	读取限速	5 req/s per IP
11	写入到 inbox/	不直接进正式仓库，等铸渊审核

7. 服务器配置

环境变量

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

重启服务

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

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

5.7 KiB Raw Permalink Blame History Unescape Escape