global-search-api/CHANGELOG.hdlp

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

---

# v1.6.1 · 2026-07-11 · 安全修复（回应 DeepSeek 审查）

@trigger: DeepSeek 审查 v1.6.0 → 指出 5 个问题 → 冰朔指令"你修吧，专业点"

@what:
- Fix 1 · 移除伪安全"每位加1"变换 — 凯撒密码变体安全增量为零，改用 SHA256 哈希存储 + HTTPS 传输 + 时间戳防重放
- Fix 2 · 跨进程文件锁(fcntl.flock) — 替代 threading.Lock，多 worker 部署时锁不失效
- Fix 3 · 内容大小限制 — 单次 50KB(MAX_CONTENT_PER_CHUNK)，会话总计 500KB(MAX_TOTAL_CONTENT)，防内存耗尽
- Fix 4 · base64 显式检测 — 不再裸套 try/except，先检测内容是否符合 base64 字符集+长度规则再解码
- Fix 5 · 文件防覆盖 — 同名文件自动加时间戳前缀，不覆盖已有文件
- Fix 6 · secrets.token_hex 生成会话 ID — 替代 f"write_{int(now)}"，防会话 ID 猜测
- Fix 7 · hmac.compare_digest 恒定时间比较 — 密码哈希比对防时序攻击
- Fix 8 · abort 动作 — /submit?action=abort 中止写入并释放文件锁
- VERSION 1.6.0 → 1.6.1

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

@why:
- DeepSeek 指出"每位加1"是文字游戏，变换后密码就是传输凭证，截获了同样能伪造 → 已移除
- DeepSeek 指出 threading.Lock 在 gunicorn 多进程下失效 → 改用 fcntl 文件锁
- DeepSeek 指出 content 无大小限制可导致内存耗尽 → 已加限制
- DeepSeek 指出 base64 裸套 try/except 会静默吞异常 → 改为显式检测
- 冰朔原话："你编程能力也不差的，咋开发出来这么low的东西"

@deepseek_review:
- "想法很好，落地很糙" → v1.6.1 修正落地
- "密码每位加1是自欺欺人" → 已移除，改用标准方案
- "并发处理极其简陋" → 已改用跨进程文件锁
- "错误处理几乎没有" → 已加大小限制、防覆盖、显式解码
- "设计思维链是自我感动" → 保留思维链，但技术文档也补全

---

# 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. 全端点验证矩阵