Add AI search query expansion

docs/design/llm-integration-design.md

@@ -210,7 +210,7 @@ OpenAI 兼容的薄客户端，基于 `httpx`，**无新依赖** / A thin OpenAI
 
 - `is_configured(cfg) -> bool`：开关开启且 `model`/`api_key` 齐全。
 - `test_connection(cfg) -> Result`：发一个最小请求验证 `base_url`/`model`/`api_key`，供配置页"测试连接"用。
-- `expand_query(cfg, query) -> list[str]`：把查询词扩成一批近义/相关词（提示词与输出契约见 §5.2）。
+- `expand_query(cfg, query, extra_hints="") -> ExpansionResult`：把查询词扩成一批近义/相关词；`terms` 为扩展词列表（不含原词），`error` 用于区分超时/网络/HTTP 等真实调用失败（提示词与输出契约见 §5.2）。
 - `analyze_image(...)`：**本轮不实现**，仅在文档中预留为未来接口（图片分析轮次）。Reserved for a future round, not implemented now.
 
 要点 / Notes：
@@ -247,8 +247,8 @@ When disabled/unconfigured: the settings page still works; the AI-search button
 
 - **常驻动作 / Persistent action：** 搜索页**始终**提供「AI 智能搜索」，**不以"零结果"为前提**——即便普通搜索已出结果，用户不满意时也能点。
   The "AI search" action is **always** present on the search page, **not gated on zero results** — usable even when normal results exist.
-- **流程 / Flow：** 普通 `LIKE` 照常先出结果 → 用户触发 AI → `expand_query` 把查询词扩成近义/相关词 → 用「原词 + 扩展词」对 `name`/`note` 做 OR `LIKE` 重搜 → 展示，并用横幅标注「AI 帮你扩展了：…」。
-  Normal `LIKE` first → user triggers AI → `expand_query` → OR-`LIKE` over name/note with the original + expanded terms → render with a banner listing the expansion.
+- **流程 / Flow：** 普通 `LIKE` 照常先出结果 → 用户触发 AI → `expand_query` 返回 `ExpansionResult`（扩展词 `terms` 不含原词；调用失败写入 `error`）→ `ai_search` 用「原词 + 扩展词」对 `name`/`note` 做 OR `LIKE` 重搜 → 展示，并用横幅标注「AI 帮你扩展了：…」。
+  Normal `LIKE` first → user triggers AI → `expand_query` returns an `ExpansionResult` (`terms` exclude the original query; failures are represented by `error`) → `ai_search` OR-`LIKE`s over name/note with the original + expanded terms → render with a banner listing the expansion.
 - **只把查询词发出去 / Only the query leaves**，不外泄物品清单；token 恒定、不随上千件物品增长。
   Only the query is sent; the inventory is not. Token cost is constant and does not grow with thousands of items.
 
@@ -261,8 +261,8 @@ Quality hinges on the prompt; integration stability hinges on the output contrac
   Frames the moving/household domain, asks for related naming terms, follows the query's language, caps the count, no prose.
 - **可选「额外领域提示」/ Optional extra hints：** KV `ai_search_extra_hints`（设置页一个多行输入，默认空）。非空时**追加**到基础提示词之后，供业主微调倾向（如"厨房用品多，偏向厨具类"）。**它只能补充，不能改写输出格式。**
   An optional free-text setting appended to the base prompt; it can only add guidance, never alter the output format.
-- **输出契约（代码强制，与提示词解耦）/ Output contract (code-enforced)：** 要求模型只返回 **JSON 字符串数组**；解析时去掉 ` ```json ` 围栏 → `json.loads` → 失败按行/逗号兜底 → 再不行返回 `[]`。`expand_query` 只返回扩展词；**原词由 `ai_search` 并入并去重**，数量在代码侧再封顶一次。
-  Require a JSON string array; tolerant parse with fallbacks to `[]`. `ai_search` adds the original term and dedupes; the count is capped in code.
+- **输出契约（代码强制，与提示词解耦）/ Output contract (code-enforced)：** 要求模型只返回 **JSON 字符串数组**；解析时去掉 ` ```json ` 围栏 → `json.loads` → 只接受字符串数组 → 过滤空串/过长词 → 最多 8 个。散文、坏 JSON、JSON object、非字符串数组都视为**合法空扩展**（`terms=[]`, `error=None`）；网络错误、HTTP 错误、超时等真实调用失败写入 `ExpansionResult.error`。`expand_query` 的 `terms` 只包含扩展词；**原词由 `ai_search` 并入并去重**。
+  Require a JSON string array; strip code fences, `json.loads`, accept only string arrays, filter empty/overlong terms, and cap to 8 terms. Prose, bad JSON, JSON objects, and non-string arrays are successful empty expansions (`terms=[]`, `error=None`); network/HTTP/timeout failures are represented by `ExpansionResult.error`. `expand_query.terms` contains only expanded terms; `ai_search` adds the original term and dedupes.
 - **客户端参数 / Client params：** 低 temperature、较小 max_tokens、设超时。Low temperature, small max_tokens, a timeout.
 - **措辞留松 / Wording left loose：** 默认提示词的具体字句可在 step-3 实测中迭代，不在文档里冻死。
   Exact default wording can be iterated during step-3 testing.
@@ -271,8 +271,8 @@ Quality hinges on the prompt; integration stability hinges on the output contrac
 
 - 路由层扩展现有 `GET /search`：增加 `ai=1` 触发位（如 `GET /search?q=锅&ai=1`），保持单页、可收藏、SSR 友好。
   Extend the existing `GET /search` with an `ai=1` trigger (e.g. `/search?q=…&ai=1`), staying single-page and bookmarkable.
-- 内部定义可替换的检索 seam，例如 `ai_search(db, query) -> (expanded_terms, results)`：
-  Define a replaceable retrieval seam, e.g. `ai_search(db, query) -> (expanded_terms, results)`:
+- 内部定义可替换的检索 seam，例如 `ai_search(db, query) -> (expanded_terms, results, error_message)`：
+  Define a replaceable retrieval seam, e.g. `ai_search(db, query) -> (expanded_terms, results, error_message)`:
   - **本轮 / now：** 内部＝查询词扩展 + 本地 `LIKE`。
   - **未来 / later：** 换成向量嵌入 + 相似度检索，**路由与模板不变**。
     Swap to embeddings + similarity later **without changing the route or template**.
@@ -284,6 +284,9 @@ Quality hinges on the prompt; integration stability hinges on the output contrac
 AI 关闭/未配置 → 不显示按钮（或提示去 `/settings`）；调用失败 → 友好提示并回退到普通结果。
 AI off/unconfigured → no button (or a hint to `/settings`); on failure → a friendly message, fall back to normal results.
 
+合法空扩展（模型返回 `[]` 或输出无法通过严格 JSON 字符串数组契约）不视为调用失败：回退普通结果，不显示故障提示。
+A legitimate empty expansion (model returns `[]` or output fails the strict JSON-string-array contract) is not treated as a call failure: fall back to normal results without an error banner.
+
 ---
 
 ## 6. 数据模型与路由变更 / Data Model & Route Changes