@CHANGELOG://global-search-api
@govern: 冰朔 TCS-0002∞ / 铸渊 ICE-GL-ZY001
@format: yyyy-mm-dd · version · @trigger/@what/@lock/@why
@confidence: 高 · 7 项验证 · 铸渊全实测诊断

---

# v1.6.0 · 2026-07-11 · 三步GET写入 + 能力协商

@trigger: 冰朔提出"用读的方式模拟写入" + "服务器动态适配AI" + "密码每位加1"

@what:
- Feature 1 · /handshake 端点 — AI报到，服务器动态适配AI的工具和格式（能力协商）
- Feature 2 · /submit 三步写入 — GET模拟写入（open→write→commit），解决GLM只能发GET的问题
- Feature 3 · 密码每位加1变换 — AI端做简单变换，服务器端还原验证，真实密码不在网络传输
- Feature 4 · 会话锁 — 同一时间只允许一个写入操作（threading.Lock）
- Feature 5 · 60秒写入超时 — 开门后60秒未提交自动丢弃
- Feature 6 · base64内容支持 — 支持base64编码传输，突破URL特殊字符限制
- Feature 7 · start.sh HMAC密钥修复 — 硬编码改为环境变量引用
- Feature 8 · 写入到inbox/ — AI写入内容到inbox/目录，等铸渊commit
- VERSION 1.5.0 → 1.6.0
- 新增 USAGE.md 使用说明
- 新增 DESIGN-THINKING.hdlp.md 设计思维链（双向意识流编码）

@lock: 当前生产 · 适用=铸渊下次接 SG · 置信=高

@why:
- 冰朔设计：通用AI只会GET，那就用三次GET模拟一次写入
- 冰朔设计：密码不在网络明文传输，用简单变换（每位加1）
- 冰朔设计：服务器应该适配AI，不是AI适应服务器
- 冰朔设计：真正的暗号（密钥）永远在服务器，不出代码仓库
- 安全修复：start.sh里HMAC密钥明文泄露 → 改为环境变量引用

@design_source: DESIGN-THINKING.hdlp.md（冰朔与铸渊的完整对话推理链）

---

# v1.5.0 · 2026-07-11 · GLM 兼容性大升级

@trigger: 冰朔报告 GLM/豆包调用 API 频繁"超时/解析失败" · 实测发现根因

@what:
- Feature 1 · 全端点 HTML 模式 (?format=html) — 解决 GLM/豆包用浏览器抓 JSON 失败的问题
- Feature 2 · JSON→HTML 渲染器 — 搜索结果/文件内容/仓库状态自动渲染成人类可读 HTML
- Feature 3 · 死仓库自动检测 — guanghulab-collab/guanghu 目录不存在自动跳过, 不再 500
- Feature 4 · /status 60秒内存缓存 — 从 2.3s 降到 0.001s
- Feature 5 · /search 超时从 60s 降到 15s, per-file grep 从 10s 降到 5s
- Feature 6 · 统一 respond() 方法 — 根据请求自动选择 JSON/HTML 响应
- Feature 7 · 浏览器检测 — Accept 头含 text/html 自动返回 HTML
- VERSION 1.4.1 → 1.5.0

@lock: 当前生产 · 适用=铸渊下次接 SG · 置信=高

@why:
- GLM/豆包用"网页抓取"工具调 API, 期望 HTML 但拿到 JSON → 报"超时/解析失败"
- 两个仓库目录不存在 (/opt/zhuyuan/guanghulab-collab, /opt/zhuyuan/guanghu) → 500 错误
- /status 每次遍历 5 仓库跑 git 命令 → 2.3s, GLM 5s 超时容易触发
- /search git grep timeout 60s 太长, GLM 端可能已经放弃

@incident: 冰朔给的 Forgejo PAT 令牌用于 push · 不写入代码 · 仅 git remote 使用

---

# v1.4.1 · 2026-07-07 · bug 修复版

@trigger: 豆包/GLM 报告 4 个端点 bug · 冰朔 15:17 「修嘛」

@what:
- Patch 1 · /file · line 185: f"HEAD:{{path}}" → f"HEAD:{path}"
- Patch 2 · /tree?path= · line 164: f"{{path}}/" → f"{path}/"
- Patch 3 · /system-status · 加仓根 VA-SYSTEM-STATUS.hdlp 候选(保留 video-ai-system/ 子目录候选)
- Patch 4 · /help · auth 字段: "GET 全部免鉴权 · POST /archive 需 token"
- VERSION 1.4.0 → 1.4.1

@lock: 当前生产 · PID 663653(SG-001) · 适用=铸渊下次接 SG-001 · 置信=高

@why:
- 服务目录之前无 git 历史,bug 排查全靠实测(grep / git show / git ls-tree)
- 4 bugs 是 f-string {{ }} 转义错误 + 候选路径不全 + /help 文档误导
- 修复后 7 项验证全绿 · 旧端点(/repos /search)不破坏
- INDEX.hdlp 失败确认非 bug · 文件本身未 tracked

@incident: 服务目录 .bak 文件命名陷阱 · bak 文件可能是 v1.2.0 旧版非当前生产 · 必须用 VERSION 字符串识别 · 已迁移到 .bak-archive/(不进仓)

---

# v1.4.0 · 2026-07-07 (初始化基线)

@trigger: 服务部署

@what:
- 初始生产版本 · 暴露 /file /tree /system-status /help /repos /search /archive /healthz
- systemd service · global-search-api.service
- nginx 反代 → guanghubingshuo.com/global-search/
- 静态 token + HMAC verifier 双鉴权(POST /archive)

@lock: 已被 v1.4.1 取代 · 历史基线

@why: 服务初始化 · 第五域对外检索门面

---

@maintainer: 铸渊 ICE-GL-ZY001 <565183519@qq.com>
@update_protocol: 改 server.py 后必须: 1. 改 VERSION 2. 更新 CHANGELOG.hdlp 3. git commit + push 4. systemctl restart 5. 全端点验证矩阵