蜂巢向量库

把这个应用接进了我们一个内部的小项目，真实跑了一轮，不是照着文档抄示例。

用 `Authorization: Bearer` 时末尾多了一个换行，是从 secret manager 复制带进来的，服务端返回 401 而不是 400，也不提示 header 格式非法，白白排查了半小时。

让 `GET /v1/events` 在 `limit` 很大时也返回 `next_cursor` 和 `total`；我预期能安全做全量同步，不用改成 50 条一轮慢慢拉。

分页游标在特定 limit 下直接消失，看起来像翻到底了，其实数据已经丢了。

第一次打开是抱着试试看的心态，结果在第一步就卡了一会儿，后面才顺起来。

`POST /v1/translate` 的 `target_lang` 传 `zh-CN` 返回 400 `unsupported language`，换成 `zh` 才行；但文档的环境表里明明列了 `zh-CN`，两处取值对不上。

对 `top_k` 这类数值参数做范围校验，越界返回 400 并说明合法区间；预期不会再因为一个参数把服务打成 500。

状态枚举存在文档外的隐藏值，任何严格的状态机都会在生产上抛异常。

装了两天，断断续续用了几次。下面这条是最影响我继续用下去的问题。

SDK 的 `client.retry({ max: 5 })` 文档说只重试 5xx，实测 400 也会重试，一次参数写错就重复创建了 5 个订单，这个默认行为太危险，清理了一晚上。

SDK 改成运行时读取 key，或在文档里给出 `Client.fromEnv()` 的 Serverless 用法；希望 key 不用写进构建产物也能生效。

返回值把无数据和 0 混为一谈，客户端分不清，业务代码里到处是特判。

我当时的调用大概是这样：

// 脱敏示例：超时与重试语义无法区分
func chatWithTimeout(ctx context.Context, c *beehub.Client, prompt string) (*beehub.ChatResponse, error) {
    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()
    res, err := c.Chat(ctx, beehub.ChatRequest{
        Model:    "bh-small",
        Messages: []beehub.Message{{Role: "user", Content: prompt}},
    })
    if errors.Is(err, context.DeadlineExceeded) {
        // 首次超时和重试预算耗尽都长这样
        return nil, fmt.Errorf("chat timeout: %w", err)
    }
    return res, err
}