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

docs/design/step-2-llm-integration.md

@@ -55,7 +55,7 @@ A settings page to enter & test the LLM config, persisted to `app_settings`, plu
 - [ ] 新增 `app/llm.py`（基于 `httpx`）：
   - [ ] `is_configured(cfg) -> bool`
   - [ ] `test_connection(cfg) -> Result`（发最小请求验证 `base_url`/`model`/`api_key`）。
-  - [ ] `expand_query(cfg, query) -> list[str]`（查询词扩展；**步骤 3 会用**，本步先落地+单测）。
+  - [ ] `expand_query(cfg, query) -> ExpansionResult`（查询词扩展；**步骤 3 会校准提示词与输出契约**；`terms` 为扩展词列表，`error` 用于区分超时/网络/HTTP 等真实调用失败）。
   - [ ] 统一超时 + 错误处理；失败优雅降级。
   - [ ] **（预留，不实现）** `analyze_image(...)`：仅留 TODO/签名占位 + 注释指向"未来图片分析轮次"。Reserved, not implemented.
   - [ ] 把所有网络调用收敛到**单一函数边界**，便于测试整体 mock。

docs/design/step-3-ai-search.md

@@ -17,7 +17,7 @@ A **persistent** "AI search" action on the search page that broadens results via
 
 - 现有搜索：`app/main.py::_build_search_results(db, query)` 对 `Box`/`Item`/`SubItem` 的 `name` 与 `note` 做大小写不敏感 `LIKE`，返回结果列表；路由 `GET /search`（函数 `search_page`，参数 `q`）渲染 `app/templates/search/index.html`。
   Existing search: `_build_search_results(db, query)` does case-insensitive `LIKE` over name/note; route `GET /search` renders `search/index.html`.
-- 步骤 2 已提供：`app/llm.py::expand_query(cfg, query) -> list[str]`、配置读取 `get_app_settings(db)`、开关 `ai_search_enabled` 与 `is_configured(cfg)`、设置页 `app/templates/settings/form.html`。
+- 步骤 2 已提供：`app/llm.py::expand_query` 的基础能力、配置读取 `get_app_settings(db)`、开关 `ai_search_enabled` 与 `is_configured(cfg)`、设置页 `app/templates/settings/form.html`；本步将 `expand_query` 校准为返回结构化 `ExpansionResult(terms, error)`。
 - 本步**新增**配置项 `ai_search_extra_hints`（可选「额外领域提示」）并在设置页加一个多行输入——这是本步**唯一**触及设置页之处。
   This step adds the `ai_search_extra_hints` setting + a textarea on the settings page (the only settings-page change here).
 - 本轮检索范围＝`name` + `note`（`image_description` 本轮不存在，属未来图片分析轮次）。
@@ -27,12 +27,12 @@ A **persistent** "AI search" action on the search page that broadens results via
 
 - **常驻、不依赖零结果。** 普通 `LIKE` 照常先出结果；AI 动作始终可用（开启且已配置时）。
   Persistent and not gated on zero results.
-- **流程：** 触发 AI → `expand_query` 得到"原词 + 一批近义/相关词" → 用这组词对 `name`/`note` 做 OR `LIKE` 重搜 → 展示，并用横幅标注「AI 帮你扩展了：…」。**只把查询词发出去**，不外泄物品清单。
-  Trigger → expand → OR-`LIKE` over the original + expanded terms → render with a banner of the expansion. Only the query leaves.
-- **可替换的检索 seam。** 把 AI 检索抽成一个函数（如 `ai_search(db, query) -> (expanded_terms, results)`），本轮内部＝查询词扩展 + 本地 `LIKE`；**未来换成向量嵌入 + 相似度时，路由与模板不变**。
+- **流程：** 触发 AI → `expand_query` 返回 `ExpansionResult`（扩展词 `terms` 不含原词，调用失败写入 `error`）→ `ai_search` 合并「原词 + 扩展词」并对 `name`/`note` 做 OR `LIKE` 重搜 → 展示，并用横幅标注「AI 帮你扩展了：…」。**只把查询词发出去**，不外泄物品清单。
+  Trigger → `expand_query` returns an `ExpansionResult` (`terms` exclude the original query; failures are represented by `error`) → `ai_search` OR-`LIKE`s over the original + expanded terms → render with a banner of the expansion. Only the query leaves.
+- **可替换的检索 seam。** 把 AI 检索抽成一个函数（如 `ai_search(db, query) -> (expanded_terms, results, error_message)`），本轮内部＝查询词扩展 + 本地 `LIKE`；**未来换成向量嵌入 + 相似度时，路由与模板不变**。
   Wrap AI retrieval behind a swappable seam so embeddings can replace it later without touching route/template.
-- **提示词（决策 C，详见设计 §5.2）。** 基础系统提示词**写死在 `app/llm.py`**；设置页可选的 `ai_search_extra_hints` 非空时**追加**到其后；**输出契约由代码强制**（要求 JSON 字符串数组 → 容忍性解析 → 失败返回 `[]`），用户改 hints 也改不坏解析。
-  Base prompt hardcoded; optional extra hints appended; output contract (JSON array → tolerant parse → `[]`) enforced in code.
+- **提示词（决策 C，详见设计 §5.2）。** 基础系统提示词**写死在 `app/llm.py`**；设置页可选的 `ai_search_extra_hints` 非空时**追加**到其后；**输出契约由代码强制**（只接受 JSON 字符串数组；散文/坏 JSON/非字符串数组解析为合法空扩展；网络/超时/HTTP 失败写入 `ExpansionResult.error`），用户改 hints 也改不坏解析。
+  Base prompt hardcoded; optional extra hints appended; output contract enforced in code: only a JSON string array is accepted; prose/bad JSON/non-string arrays become a successful empty expansion; network/timeout/HTTP failures are represented by `ExpansionResult.error`.
 - **优雅降级。** AI 关闭/未配置 → 不显示按钮（或提示去 `/settings`）；调用失败 → 友好提示 + 回退普通结果。
 
 ---
@@ -43,10 +43,13 @@ A **persistent** "AI search" action on the search page that broadens results via
   - 基础系统提示词写死在 `app/llm.py`（搬家/家居场景、列相关命名词、跟随查询语言、≤ ~8 个、不解释、不造无关词）。默认提示词起点（**可迭代** / a starting point, tune during testing）：
     > 你是搬家物品搜索助手。用户在搜索自己打包的箱子与物品（家居/搬家场景）。给定一个搜索词，列出用户可能用来命名同一类物品的相关词：近义词、常见别称、上位类别、具体品类。规则：用与查询相同的语言；只给与该物品紧密相关、有助于在清单里找到它的词；不要解释、不要造无关词；最多 8 个；只输出一个 JSON 字符串数组，例如 `["炒锅","平底锅","汤锅","厨具"]`。
   - 读取 `ai_search_extra_hints`，非空则**追加**到基础提示词之后（只补充，不改格式）。
-  - **输出契约**：要求模型只回 JSON 字符串数组；解析去 ` ```json ` 围栏 → `json.loads` → 失败按行/逗号兜底 → 再不行返回 `[]`；任何异常/超时都返回 `[]`（不抛错）。
+  - **返回契约**：`expand_query(cfg, query, extra_hints="") -> ExpansionResult`，其中 `terms` 是扩展词列表（**不含原词**），`error` 在成功时为 `None`。
+  - **输出契约**：要求模型只回 JSON 字符串数组；解析去 ` ```json ` 围栏 → `json.loads` → 只接受字符串数组 → 过滤空串/过长词 → 最多 8 个；散文、坏 JSON、JSON object、非字符串数组都返回 `terms=[]` 且 `error=None`（合法空扩展）；网络错误、HTTP 错误、超时等调用失败返回 `terms=[]` 且 `error=<友好错误>`；不向上抛 500。
 - [ ] **新增配置项 `ai_search_extra_hints`**：KV 默认空；纳入 `get_app_settings` / `save_app_settings`；设置页 `app/templates/settings/form.html` 加一个多行输入（沿用 step 2 风格）。
-- [ ] 实现检索 seam：在 `app/main.py`（或抽一个小搜索模块 `app/search.py`）加 `ai_search(db, query) -> (expanded_terms, results)`：
-  - 调 `expand_query(cfg, query)` 得到扩展词；
+- [ ] 实现检索 seam：在 `app/main.py`（或抽一个小搜索模块 `app/search.py`）加 `ai_search(db, query) -> (expanded_terms, results, error_message)`：
+  - 调 `expand_query(cfg, query)` 得到 `ExpansionResult`；
+  - 若 `result.error` 非空：回退普通搜索，并把友好错误传给模板；
+  - 若 `result.terms` 为空且无错误：视为合法空扩展，回退普通搜索，不显示故障提示；
   - 用「原词 + 扩展词」对 `name`/`note` 做 OR `LIKE`（**复用现有 `_build_search_results` 的匹配逻辑**，避免重复实现），去重。
   - 注意：现有 `_build_search_results(db, query)` 只接收单个查询词；建议把它泛化为接收一组关键词（对多个词做 OR），让 AI 搜索与普通搜索共用同一套匹配逻辑，避免分叉。
     Note: `_build_search_results` currently takes a single query — generalize it to accept multiple keywords so AI and normal search share one matching path.
@@ -62,9 +65,9 @@ A **persistent** "AI search" action on the search page that broadens results via
   - [ ] 扩展词驱动命中：原词 `LIKE` 搜不到、扩展后能搜到。
   - [ ] 已有结果时点 AI 仍可用，且结果集被扩大（含原结果）。
   - [ ] 按钮可见性随 `ai_search_enabled` + `is_configured()` 门控。
-  - [ ] 调用失败 → 回退普通结果、页面不报错。
-  - [ ] `expand_query` 输出解析：模型回合法 JSON 数组 → 正确解析；回散文/坏 JSON/超时 → 返回 `[]`、不抛错。
-    Output parsing: valid JSON array → parsed; prose/bad JSON/timeout → `[]`, no raise.
+  - [ ] 调用失败（超时/网络/HTTP）→ 回退普通结果、显示友好提示、页面不报错。
+  - [ ] `expand_query` 输出解析：模型回合法 JSON 数组 → 正确解析；回散文/坏 JSON/非字符串数组 → `terms=[]` 且 `error=None`；超时/网络/HTTP 失败 → `terms=[]` 且 `error` 非空；均不抛错。
+    Output parsing: valid JSON array → parsed; prose/bad JSON/non-string arrays → `terms=[]`, `error=None`; timeout/network/HTTP failures → `terms=[]`, non-empty `error`; no raise.
   - [ ] `ai_search_extra_hints` 非空时确被追加进请求（可对构造的请求体断言）。
     Extra hints, when set, are appended to the request.