Super-squash branch 'main' using huggingface_hub

Co-authored-by: GitHub Actions <GitHub Actions@users.noreply.huggingface.co>

.gitattributes

@@ -0,0 +1,34 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.github/workflows/sync_to_hf.yml

@@ -0,0 +1,77 @@
+name: Sync to HuggingFace and ModelScope
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout GitHub repo
+        uses: actions/checkout@v4
+        with:
+          lfs: false
+
+      - name: Install Dependencies
+        run: pip install huggingface_hub
+
+      - name: Sync to HuggingFace Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          python - << 'PYEOF'
+          import os
+          from huggingface_hub import HfApi
+
+          api = HfApi(token=os.environ["HF_TOKEN"])
+          repo_id = "SAkizuki/DanbooruSearch"
+
+          api.upload_folder(
+              folder_path=".",
+              repo_id=repo_id,
+              repo_type="space",
+              ignore_patterns=[
+                  "tags_embedding/*",
+                  "origin_database/*",
+                  ".git/*", 
+                  "__pycache__/*", 
+                  "*.pyc", 
+                  "*.parquet", 
+                  "*.csv"
+              ],
+              commit_message="Auto-sync from GitHub Actions"
+          )
+          print("HF sync done")
+          PYEOF
+
+      - name: Sync to ModelScope Studio
+        env:
+          MS_TOKEN: ${{ secrets.MS_TOKEN }}
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+          export GIT_LFS_SKIP_SMUDGE=1
+          git clone https://oauth2:${MS_TOKEN}@www.modelscope.cn/studios/SAkizuki/DanbooruSearchOnline.git ms_repo
+          
+          # 拷贝根目录下的 .py 文件、依赖文件及 README.md
+          cp *.py ms_repo/ 2>/dev/null || true
+          cp requirements.txt ms_repo/ 2>/dev/null || true
+          cp README.md ms_repo/ 2>/dev/null || true
+          
+          # 拷贝 core 目录下的 .py 文件
+          mkdir -p ms_repo/core
+          cp core/*.py ms_repo/core/ 2>/dev/null || true
+          
+          cd ms_repo
+          git add .
+          
+          if ! git diff --staged --quiet; then
+            git commit -m "Auto-sync from GitHub Actions"
+            git push origin master
+            echo "MS sync done"
+          else
+            echo "No code changes to sync to MS."
+          fi

.gitignore

@@ -0,0 +1,18 @@
+*cuda*
+*.pyc
+core/__pychahce__
+__pychahce__
+my_model*/
+*.ignore
+tags_embedding/
+origin_database/
+.idea/
+*ignore*.py
+*.sh
+tempsave/
+*.env
+*.png
+*.bat
+eval/
+legacy_history.json
+CLAUDE.md

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+ENV PYTHONUNBUFFERED=1
+COPY --chown=user . /app
+EXPOSE 7860
+CMD ["python", "ui_nicegui.py"]

README.md

@@ -0,0 +1,472 @@
+---
+title: DanbooruSearch
+emoji: 👁
+colorFrom: red
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: 基于语义匹配的 Danbooru 标签搜索引擎，支持多维匹配、智能分词与共现关联推荐。
+tags:
+  - text-to-image
+  - prompt-engineering
+  - stable-diffusion
+  - danbooru
+  - nlp
+thumbnail: >-
+    https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202604022117025.png
+---
+
+# Danbooru Tags Searcher
+
+![](https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202604022117025.png)
+
+本项目提供一种基于语义匹配的 Danbooru 标签查找方案。用户可以通过输入日常语言或模糊描述，查找并匹配 Danbooru 数据集中对应的标准标签，适用于辅助构建 Stable Diffusion、NovelAI 等 AI 绘画工具的提示词（Prompt）。
+
+目前支持使用汉语和英语进行查找
+
+**立即使用：** https://huggingface.co/spaces/SAkizuki/DanbooruSearch
+
+**ComfyUI 插件版本：** [ComfyUI-DanbooruSearcher](https://github.com/SuzumiyaAkizuki/ComfyUI-DanbooruSearcher)
+
+本项目的数据库由Danbooru API抓取而成，使用LLM进行语义扩充和中文翻译。角色名、作品名使用二次元垂类数据库Bangumi API进行精确查询，尽可能地避免了在角色名、作品名上的幻觉问题。
+
+**数据库生成代码：** https://github.com/SuzumiyaAkizuki/danbooru-tag-pipeline
+
+---
+
+## 核心特性
+
+本版本在基础语义检索之上，引入了完整的标签工作流辅助功能：
+
+* **多维度语义匹配：** 底层支持 4 个维度的向量空间检索（英文、中文扩展词、维基释义、中文核心词），大幅提升模糊描述的命中率。
+* **智能分词与显式分隔：** 支持一键开启/关闭自动分词。开启后自动提取长句中概念分别检索；同时支持用空格、换行、中文逗号（，）和顿号（、）手动分隔概念，系统会尊重你的分隔意图，将每个片段作为整体匹配（超过 7 字的片段仍然自动分词）。
+* **标签互相关推荐：** 引擎内置标签共现数据。当你选中某些标签后，系统会自动推荐在 Danbooru 图库中经常与它们一同出现的相关标签，辅助补全画面细节。
+* **精细化查阅与过滤：** 支持按标签类别（General通用 / Character角色 / Copyright作品）进行硬过滤。
+  * 提供 **NSFW 保护模式**（开启后自动模糊敏感词汇）。
+  * 表格内置 Danbooru 维基释义悬浮提示，并提供前往原站的快捷链接。
+
+
+## 功能概览
+
+本工具提供以下五项核心功能：
+
+- [精确查词](#1-精确查词)（容错拼写错误）
+- [概念模糊发散](#2-概念模糊发散)
+- [输入描述查词](#3-输入描述查词)
+- [完整画面查找](#4-完整画面查找)
+- [关联推荐](#5-关联推荐共现匹配)
+
+前四项基于**语义向量匹配**，后一项基于**标签共现数据**。
+
+---
+
+## 参数说明
+
+在进入功能介绍之前，先了解几个关键参数，它们会影响所有搜索模式的结果质量。
+
+**Top K（语义相关）**
+针对单个分词，检索语义最相关的候选标签数量。该值作用于每个向量检索层，最终候选池大小约为 Top K × 层数，再截断至结果上限。值越大，召回越广，但热度高的分词会占据更多名额，可能挤压低频但精确的分词。精确查词场景建议调低（20），发散探索场景可以调高（80~160）。
+
+**结果上限**
+最终展示的标签总条数。建议设为 70~80 以适配主流 SDXL 模型的 prompt 长度。精确查词时可以调低到 10，避免干扰。
+
+**热度权重（0~1）**
+控制标签在 Danbooru 站内发帖量对最终排序的影响。数值越高，越倾向于推荐常用高频标签。默认值 0.15 在大多数场景下表现良好。
+
+**智能分词**
+开启时，程序会自动拆分输入的长句，提取其中的关键概念分别检索，再合并结果。适合完整画面描述；若只想检索一个完整短语的语义，建议关闭。
+
+**新版支持显式分隔符：** 用空格、换行、或中文逗号/顿号（，、）手动分隔概念时，系统会将每个分隔片段视为独立的原子概念，不再做进一步拆分。这在你明确知道自己想要哪些概念时比自动分词更精准。
+
+| 输入示例 | 分词结果 | 说明 |
+|---|---|---|
+| `运动社团 校队 比赛` | `运动社团` `校队` `比赛` | 空格分隔，每个片段原样保留 |
+| `运动社团、校队、比赛` | `运动社团` `校队` `比赛` | 逗号/顿号同理 |
+| `一个穿着白色水手服的少女` | `穿着` `白色` `水手服` `少女` | 无显式分隔，自动分词（停用词已过滤） |
+
+> 当分隔后的某个片段超过 **7 个字**时，系统会退回到自动分词——因为超过这个长度的片段通常是短句而非单一概念。这一阈值基于对所有标签核心中文名长度的统计分析得出。
+
+---
+
+## 1. 精确查词
+
+**适用场景���** 你知道某个标签的大概写法，但不确定拼写是否准确，或者只记得部分写法。
+
+本工具通过语义相似度匹配而非字符串精确匹配，因此具备一定的拼写容错能力。
+
+**建议参数：** Top K: 20 | 结果上限: 10 | 热度权重: 0.15 | **关闭智能分词**
+
+> 关闭智能分词，确保整个输入作为一个整体进行语义匹配，不会被拆散。
+
+### 示例
+
+| 你的输入 | 实际标准标签 | 说明 |
+|---|---|---|
+| `selafuku` | `serafuku` | 经典拼写错误，仍可命中 |
+| `school unifor` | `school_uniform` | 漏字母，仍可命中 |
+| `twintail` | `twintails` | 单复数混淆，仍可命中 |
+| `zettai ryouiki` | `zettai_ryouiki` | 罗马音输入，可命中 |
+| `thighhigh` | `thighhighs` | 词形变体，仍可命中 |
+
+---
+
+## 2. 概念模糊发散
+
+**适用场景：** 你脑中有一个模糊的概念或风格意象，但不知道在 Danbooru 里对应哪些标签，希望系统帮你"发散"出相关的候选标签。
+
+**建议参数：** Top K: 80~160 | 结果上限: 80 | 热度权重: 0.15 | **开启智能分词**
+
+### 示例
+
+**示例 1：「兔耳朵」**
+
+输入一个宽泛概念，系统会返回各类耳型相关标签，包括真兔耳、头饰耳、兽娘耳等变体。
+
+![image-20260402202537091](https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202604022025661.png)
+
+---
+
+**示例 2：「中国风古装」**
+
+返回汉服、旗袍、各朝代服制等细分标签，帮助你快速了解这一风格下的标签体系。
+
+![image-20260402202652780](https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202604022026925.png)
+
+---
+
+**示例 3：「机械义肢」**
+
+返回包含义肢、机械臂、赛博朋克肢体等标签，适合进一步结合关联推荐做细化筛选。
+
+![image-20260402202730735](https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202604022027911.png)
+
+---
+
+**示例 4：「战斗姿势」**
+
+返回各类战斗动作、持武器动作等标签。
+
+![image-20260402202757757](https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202604022028668.png)
+
+---
+
+## 3. 输入描述查词
+
+**适用场景：** 你能描述某个具体的事物、角色、场景，但不知道 Danbooru 的对应标签。可以使用中文或英文自然语言描述，也可以通过 IP 名称、角色外号来查找角色标签。
+
+**建议参数：** Top K: 20 | 结果上限: 20 | 热度权重: 0.15 | **关闭智能分词**
+
+> 关闭智能分词，使系统对你的整段描述做整体语义匹配，而不是拆词。
+
+### 示例
+
+**示例 1：用描述定位角色**
+
+| 你的输入 | 期望命中的角色标签 | 说明 |
+|---|---|---|
+| `原神里面须弥主线的NPC贵族女孩` | `dunyarzad_(genshin_impact)`（迪纳泽黛） | 通过剧情身份描述定位角色 |
+| `命运石之门的助手` | `makise_kurisu`（牧瀬红莉栖） | 通过人物关系描述定位角色 |
+| `某科学的超电磁炮中会传送的那个人` | `shirai_kuroko`（白井黑子） | 通过能力和动作描述定位角色 |
+| `EVA 里驾驶零号机的蓝发角色` | `ayanami_rei`（凌波丽） | 通过机体和外貌描述定位角色 |
+| `明日方舟里游戏商店的老板` | `closure_(arknights)`（可露希尔） | 通过职位描述定位角色 |
+
+---
+
+**示例 2：用描述定位服饰/物品**
+
+| 你的输入 | 期望命中的标签 | 说明 |
+|---|---|---|
+| `紧身衣勒入皮肤产生的凹陷` | `skindentation` | 非常具体的视觉细节描述 |
+| `半透明薄纱覆盖胸前` | `see-through_bra` | 材质与遮盖关系描述 |
+| `两侧有开缝、有拉绳的运动短裤` | `dolphin_shorts` | 服饰细节描述 |
+
+---
+
+## 4. 完整画面查找
+
+**适用场景：** 你脑中已经有了一幅完整的画面，希望一次性把整段描述转换成尽可能多的 Danbooru 标签，用于 AI 绘画的完整 Prompt。
+
+**建议参数：** Top K: 5 | 结果上限: 80 | 热度权重: 0.15 | **开启智能分词**
+
+> 开启智能分词：系统会自动拆分你的长句，提取其中的关键概念分别检索，再合并去重，覆盖尽可能多的画面元素。
+
+### 示例
+
+**示例 1：雨中奔跑的少女**
+
+```
+一个穿着白色水手服、蓝色短裙的少女，在下着大雨的城市街道奔跑，
+她的表情是不甘、愤怒、流泪，她的衣服湿透。
+```
+
+> short_dress, city, streaming_tears, street, white_serafuku, furious, fume, rain, tears, running, skirt, crying, tearing_up, urban
+
+**示例 2：赛博朋克城市夜景**
+
+```
+赛博朋克风格的城市，霓虹灯招牌，雨后潮湿的街道倒映灯光，
+远处高楼林立，一个穿着皮夹克的女孩站在路灯下抽烟。
+```
+
+> street, reflection, lights, lamp, leather_jacket, fur_jacket, 1girl, standing, lamppost, smoking, holding_cigarette, cyberpunk, after_rain, city, urban, neon_lights, wet_floor, utility_pole
+
+---
+
+**示例 3：奇幻战场**
+
+```
+一个银发的精灵女战士，身穿轻甲，手持弓箭，站在废墟上，
+背景是正在燃烧的城市和布满乌云的天空，衣服上有血迹。
+```
+
+> burning, city, dark_cloud, sky, clothes, blood_stain, blood_on_clothes, silver_hairband, standing, white_hair, cyberpunk, after_rain, holding, bow_(weapon), urban, ruins, elf, rubble, holding_bow_(weapon), arrow_(projectile), neon_lights, burning_building, wet_floor, utility_pole
+
+---
+
+**技巧：关于描述的写法**
+
+- 分段描述不同要素（人物 / 背景 / 表情 / 服装）比混在一起效果更好
+- 细节越具体，匹配越准确——「蓝色长发」优于「特别的发色」
+- 遇到感觉应该有但没命中的标签，可以把该部分单独截取，切换到「输入描述查词」模式单独查
+
+---
+
+## 5. 关联推荐（共现匹配）
+
+关联推荐与前四项功能机制不同，它不依赖语义相似度，而是基于 **Danbooru 图库中标签的共现统计**：如果两个标签经常出现在同一张图上，就认为它们相关。
+
+**使用方式：** 在左侧结果表格中勾选你感兴趣的标签，右侧关联推荐栏会自动刷新，显示在 Danbooru 图库中与你选中标签最常共现的其他标签。也可以点击「根据已选刷新」手动触发。
+
+关联推荐的得分是基于 NPMI（互信息归一化）计算的，能有效过滤掉那些只是因为自身热度高而频繁出现的标签。
+
+### 适用场景
+
+**场景 1：查看某种服饰/道具的常见搭配**
+
+勾选 `fingerless_gloves`（露指手套），关联推荐会列出穿露指手套的角色们。
+
+![image-20260402204128858](https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202604022041742.png)
+
+---
+
+**场景 2：查看某个角色的典型特征**
+
+勾选角色标签（如 `amiya_(arknights)`），关联推荐会列出该角色最常出现的服装、配件、表情等标签，相当于自动生成角色的"标签画像"。
+
+![image-20260402204239836](https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202604022042492.png)
+
+---
+
+**场景 3：探索某类主题的标签体系**
+
+勾选 `fighter_jet`（战斗机），关联推荐会列出各类机型、飞行动作、背景等相关标签，帮助你快速摸清一个主题下的标签生态。
+
+![image-20260402204306860](https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202604022043665.png)
+
+---
+
+**场景 4：组合多个标签获得交集推荐**
+
+同时勾选多个标签时，关联推荐会综合计算多标签的共现关系，推荐与这组标签**整体**最匹配的标签，而不只是单个标签的邻居。
+
+比如同时勾选 `maid` + `twintails`，推荐结果会更倾向于「女仆且双马尾」场景下经常出现的标签，而不是单纯「女仆」或「双马尾」各自的高频搭配。
+
+![image-20260402204415282](https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202604022044935.png)
+
+---
+
+## 使用技巧
+
+**技巧 1：先宽后窄**
+先用完整画面查找拿到大量候选标签，再用分词筛选 chip 或手动去掉不相关的，然后勾选剩余标签触发关联推荐，补充遗漏细节。
+
+**技巧 2：拿不准标签含义时悬浮查看**
+鼠标悬停在任意标签行或关联推荐行上，会弹出该标签的 Danbooru 维基释义，方便快速判断是否符合需求，无需跳转站外。
+
+**技巧 3：点击标签名直接跳转**
+标签名是可点击链接，点击后在新标签页打开 Danbooru 的对应维基页，可以查看详细说明、相关图例和近义标签。
+
+**技巧 4：NSFW 保护模式**
+默认关闭 NSFW 显示。打开后标签的完整名称和含义会显示出来，但平台限制下（魔搭创空间）此选项不可用。
+
+**技巧 5：复制全部 vs 复制选中**
+- **复制全部标签**：把当前搜索结果中所有标签复制为逗号分隔的字符串，适合快速生成完整 Prompt
+- **复制选中标签**：只复制你在表格中手动勾选的标签，适合精选后使用
+
+**技巧 6：用显式分隔符精细控制分词**
+当你知道自己想要哪些独立概念时，用空格或中文逗号手动分隔它们：
+- 「`运动社团 校队 比赛 运动会 体育祭 田径部`」→ 每个概念原样保留
+- 「`反乌托邦、赛博朋克、蒸汽朋克、废土`」→ 逗号分隔同理
+- 分隔后的短片段（≤7 字）作为整体匹配，不会被错误拆开
+- 如果需要混合长短查询，可以一部分用空格分隔、另一部分写成自然语句
+
+---
+
+## API 接口
+
+本工具同时提供 REST API，可集成到你自己的工作流中。
+
+启动后访问 `/api/docs` 查看完整的交互式 API 文档。
+
+**搜索接口**
+```
+POST /api/search
+{
+    "query": "白色水手服的女孩",
+    "top_k": 20,
+    "limit": 20,
+    "show_nsfw": false
+}
+```
+
+**关联推荐接口**
+```
+POST /api/related
+{
+    "tags": ["white_serafuku", "sailor_collar"],
+    "limit": 20,
+    "show_nsfw": false
+}
+```
+
+详见：[API 文档](https://sakizuki-danboorusearch.hf.space/api/docs)
+
+---
+
+## MCP 接口
+
+本工具提供 MCP（Model Context Protocol）服务，支持将搜索引擎直接接入 Claude Desktop、Cursor、Cherry Studio 等支持 MCP 协议的大模型客户端，让 AI 能够在对话中直接调用标签搜索能力。
+
+**MCP 服务地址：**
+```
+https://sakizuki-danboorusearch.hf.space/mcp/mcp
+```
+
+### 接入方法
+
+**方法一：Claude Desktop**
+
+Claude Desktop 不支持直接连接 Streamable HTTP 端点，需要通过 `mcp-remote` 作为本地桥接。
+
+首先全局安装 `mcp-remote`（需要本机已安装 Node.js）：
+
+```bash
+npm install -g mcp-remote
+```
+
+然后在配置文件中添加以下内容：
+
+- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
+- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "danbooru-searcher": {
+      "command": "mcp-remote",
+      "args": [
+        "https://sakizuki-danboorusearch.hf.space/mcp/mcp"
+      ]
+    }
+  }
+}
+```
+
+保存后重启 Claude Desktop，工具列表中出现 `search_tags` 和 `get_related_tags` 即为成功。
+
+> 注意：不要使用 `"url"` 字段直接填写地址，Claude Desktop 不支持该格式，会提示配置无效。也不推荐通过 `npx mcp-remote` 调用，首次执行时 `npx` 需要临时下载包，npm 缓存损坏时会导致启动失败。全局安装可规避此问题。
+
+**方法二：图形界面（Cherry Studio 等）**
+
+在 MCP 服务器管理页面点击「添加」，填写以下信息：
+
+- 名称：`danbooru-searcher`（可自定义）
+- 类型：`Streamable HTTP`
+- URL：`https://sakizuki-danboorusearch.hf.space/mcp/mcp`
+
+> 注意：类型务必选择 **Streamable HTTP**，不要选 SSE，否则工具列表无法正常加载。
+
+添加完成后重启客户端，或在 MCP 管理界面手动刷新连接。
+
+### 可用工具
+
+接入后 AI 可调用以下两个工具：
+
+**`search_tags`** — 自然语言搜索标签
+
+接受中文或英文描述，返回匹配的 Danbooru 标签列表和可直接用于 AI 绘画的 prompt 字符串。支持参数：
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `query` | — | 自然语言描述（必填，推荐中文）。支持空格/逗号/顿号显式分隔概念 |
+| `use_segmentation` | `true` | 智能分词开关，完整画面描述时开启，精确查词时关闭 |
+| `top_k` | `5` | 每个分词的语义召回数量，发散探索时调高至 80~160 |
+| `limit` | `80` | 返回标签总数上限 |
+| `popularity_weight` | `0.15` | 热度权重，控制高频标签的排名影响 |
+| `show_nsfw` | `true` | 是否包含 NSFW 标签 |
+| `category` | `"all"` | 标签类别筛选：`"all"` 全部、`"general"` 通用、`"character"` 角色、`"copyright"` 作品 |
+
+**`get_related_tags`** — 共现关联推荐
+
+给定一组已选标签，返回在 Danbooru 图库中与之最常共现的相关标签，基于 NPMI 评分，可有效过滤掉仅因自身热度高而频繁出现的标签。
+
+### 调用示例
+
+接入后，你可以直接用自然语言告诉 AI 你的需求，AI 会自动选择合适的参数调用工具：
+
+> 帮我把「一个穿白色水手服的少女在大雨中奔跑，表情愤怒、流泪，衣服湿透」转换成 Danbooru 标签 prompt
+
+> 我想找「机械义肢」相关的标签，帮我发散一下
+
+> 帮我查一下「命运石之门的助手」对应的角色标签是什么
+
+> 我已经选了 `white_serafuku` 和 `rain` 这两个标签，帮我推荐一些常见的搭配标签
+
+> 查一下「运动社团 校队 比赛 运动会 体育祭 田径部 网球部 篮球部」这些概念对应的标签
+
+> 找「反乌托邦、赛博朋克、蒸汽朋克」的 General 类标签，只查通用特征不查作品名
+
+### 查询写作技巧（写给 LLM）
+
+为了让搜索更精准，在构造 `query` 时请注意以下几点：
+
+1. **概念列表用显式分隔符：** 需要批量查询多个独立概念时，用空格、中文逗号（，）或顿号（、）分隔。每个 ≤7 字的片段会作为完整概念匹配，不会被错误拆开。例如 `运动社团 校队 比赛` 而非 `运动社团校队比赛`。
+
+2. **画面描述写自然语句：** 完整场景描述不需要显式分隔，系统会自动分词。例如 `一个穿着白色水手服蓝色短裙的少女在雨中奔跑`。
+
+3. **查角色/作品时关闭分词：** 精确查找某个角色名或作品名时，设 `use_segmentation=false` 和 `category="character"`（或 `"copyright"`），避免名字中的词汇被单独匹配到无关标签。
+
+4. **长短语会自动保持完整语义：** 即使用显式分隔符切出的片段超过 7 字，系统也会对其自动分词并同时保留原始片段作为额外查询（从句级语义），不会丢失整体语境。
+
+### 注意事项
+
+HF Space 在无流量时会进入休眠状态，首次请求需要等待冷启动（约 30~60 秒）。若 AI 调用超时，稍等片刻后重试即可，或先访问 [Space 页面](https://huggingface.co/spaces/SAkizuki/DanbooruSearch) 将其唤醒。
+
+---
+
+## 数据库说明
+
+- 数据来源：Danbooru API 抓取
+- 中文翻译与语义扩充：由 LLM 辅助完成
+- 角色名、作品名：通过二次元垂类数据库 [Bangumi](https://bgm.tv) API 精确查询，尽量避免幻觉
+- 仅收录 Danbooru 频数 **≥ 100** 的标签，保证标签实际可用
+- 仅覆盖 General（通用特征）、Character（角色）、Copyright（作品）三类标签
+
+**数据库生成代码：** https://github.com/SuzumiyaAkizuki/danbooru-tag-pipeline
+
+---
+
+## 注意事项
+
+- 本工具为 AI 辅助工具，检索结果未必 100% 准确
+- 查找结果可能包含 NSFW 内容（默认隐藏）
+- 仅支持中文 / 英文双语查找
+- 如果检索结果不理想，欢迎点击「没搜到？」按钮提交反馈，帮助持续优化引擎
+
+
+
+## 搜索统计
+
+![](https://dsocounter.oss-cn-hongkong.aliyuncs.com/danbooru_counter/search_stats.png)

api_fastapi.py

@@ -0,0 +1,160 @@
+"""
+api_fastapi.py
+──────────────
+FastAPI 适配层（可选）。
+
+演示如何在完全不修改 core/ 的情况下将引擎 API 化。
+
+启动方式：
+    uvicorn api_fastapi:app --host 0.0.0.0 --port 8000
+
+请求示例：
+    POST /search
+    {
+        "query": "白色水手服的女孩",
+        "top_k": 5,
+        "limit": 20
+    }
+
+    POST /related
+    {
+        "tags": ["white_serafuku", "sailor_collar"],
+        "limit": 20,
+        "show_nsfw": false
+    }
+"""
+
+from __future__ import annotations
+
+import asyncio
+from fastapi import FastAPI
+from pydantic import BaseModel, Field
+
+from core.engine import DanbooruTagger
+from core.models import SearchRequest, SearchResponse, TagResult, RelatedTag
+import core.counter as counter
+
+
+# ── Pydantic I/O 模型（API 层专用，与 core.models 解耦）──
+
+class SearchIn(BaseModel):
+    query: str
+    top_k: int = Field(5, ge=1, le=50)
+    limit: int = Field(80, ge=1, le=500)
+    popularity_weight: float = Field(0.15, ge=0.0, le=1.0)
+    show_nsfw: bool = True
+    use_segmentation: bool = True
+    target_layers: list[str] = ['英文', '中文扩展词', '释义', '中文核心词']
+    target_categories: list[str] = ['General', 'Character', 'Copyright']
+
+
+class TagOut(BaseModel):
+    tag: str
+    cn_name: str
+    category: str
+    nsfw: str
+    final_score: float
+    semantic_score: float
+    count: int
+    source: str
+    layer: str
+    wiki: str = ""
+
+
+class RelatedIn(BaseModel):
+    tags: list[str]
+    limit: int = Field(50, ge=1, le=200)
+    show_nsfw: bool = True
+
+
+class RelatedTagOut(BaseModel):
+    tag: str
+    cn_name: str
+    category: str
+    nsfw: str
+    cooc_count: int
+    cooc_score: float
+    sources: list[str]
+
+
+class SearchOut(BaseModel):
+    tags_all: str
+    tags_sfw: str
+    results: list[TagOut]
+    keywords: list[str]
+
+
+# ── FastAPI 子应用（挂载到 NiceGUI 的 /api 路径下）──
+# lifespan / 预热由 ui_nicegui.py 的 @app.on_startup 统一管理，此处不重复。
+app = FastAPI(
+    title="Danbooru Tag Searcher API",
+    description="通过 /api/docs 查看完整接口文档。",
+    version="1.0.0",
+)
+
+
+# ── 端点 ──
+
+@app.post("/search", response_model=SearchOut)
+async def search(body: SearchIn) -> SearchOut:
+    tagger = await DanbooruTagger.get_instance()
+
+    # SearchIn → core.models.SearchRequest（两者字段一一对应，直接解包）
+    request = SearchRequest(**body.model_dump())
+
+    # 在线程池中运行阻塞的 search()
+    response: SearchResponse = await asyncio.to_thread(tagger.search, request)
+
+    # 计数：每次 API 搜索调用均计入搜索、成功、复制；访问不变
+    await counter.increment()
+    await counter.increment_success()
+    await counter.increment_copy()
+
+    return SearchOut(
+        tags_all=response.tags_all,
+        tags_sfw=response.tags_sfw,
+        results=[TagOut(**vars(r)) for r in response.results],
+        keywords=response.keywords,
+    )
+
+
+@app.post("/related", response_model=list[RelatedTagOut])
+async def related(body: RelatedIn) -> list[RelatedTagOut]:
+    """
+    给定已选标签列表，返回基于共现表的关联推荐。
+
+    - tags：种子标签列表（Danbooru 英文标签名）
+    - limit：最多返回条数，默认 50
+    - show_nsfw：是否包含 NSFW 标签，默认 True
+    """
+    tagger = await DanbooruTagger.get_instance()
+    results = await asyncio.to_thread(
+        tagger.get_related,
+        body.tags,
+        set(body.tags),   # exclude 已选标签自身
+        body.limit,
+        body.show_nsfw,
+    )
+    # 计数：每次 API related 调用均计入搜索、成功、复制；访问不变
+    await counter.increment()
+    await counter.increment_success()
+    await counter.increment_copy()
+
+    return [
+        RelatedTagOut(
+            tag=r.tag,
+            cn_name=r.cn_name,
+            category=r.category,
+            nsfw=r.nsfw,
+            cooc_count=r.cooc_count,
+            cooc_score=r.cooc_score,
+            sources=r.sources,
+        )
+        for r in results
+    ]
+
+
+@app.get("/health")
+async def health():
+    tagger = await DanbooruTagger.get_instance()
+    return {"status": "ok", "loaded": tagger.is_loaded}

cli.py

@@ -0,0 +1,143 @@
+"""
+cli.py
+──────
+命令行适配层（可选）。
+
+子命令：
+    search   语义搜索标签
+    related  基于共现表查关联推荐
+
+用法：
+    python cli.py search "白色水手服的女孩" --limit 10 --no-nsfw
+    python cli.py related "white_serafuku,sailor_collar" --limit 20
+    python cli.py related "white_serafuku,sailor_collar" --no-nsfw --show-sources
+"""
+
+import argparse
+import asyncio
+
+from core.engine import DanbooruTagger
+from core.models import SearchRequest
+
+
+# ── search ────────────────────────────────────────────────────────────
+
+async def cmd_search(args):
+    tagger = await DanbooruTagger.get_instance()
+    request = SearchRequest(
+        query=args.query,
+        top_k=args.top_k,
+        limit=args.limit,
+        popularity_weight=args.weight,
+        show_nsfw=not args.no_nsfw,
+        use_segmentation=not args.no_seg,
+        target_layers=args.layers,
+        target_categories=args.categories,
+    )
+    resp = await asyncio.to_thread(tagger.search, request)
+
+    print(f"\n{'='*60}")
+    print(f"查询：{args.query}  |  共 {len(resp.results)} 条结果")
+    print(f"{'='*60}")
+    print(f"推荐 Prompt：\n  {resp.tags_sfw if args.no_nsfw else resp.tags_all}\n")
+
+    for r in resp.results:
+        nsfw_mark = "🔴" if r.nsfw == '1' else "🟢"
+        print(f"  {nsfw_mark} [{r.final_score:.3f}] {r.tag:<30}  {r.cn_name[:20]:<20}  {r.category}")
+
+
+# ── related ───────────────────────────────────────────────────────────
+
+async def cmd_related(args):
+    seed_tags = [t.strip() for t in args.tags.split(',') if t.strip()]
+    if not seed_tags:
+        print("[CLI] 错误：请提供至少一个种子标签，多个标签以逗号分隔。")
+        return
+
+    tagger = await DanbooruTagger.get_instance()
+    results = await asyncio.to_thread(
+        tagger.get_related,
+        seed_tags,
+        set(seed_tags),   # exclude 种子标签自身
+        args.limit,
+        not args.no_nsfw,
+    )
+
+    if not results:
+        print("[CLI] 未找到关联推荐（共现表可能未加载，或种子标签不在库中）。")
+        return
+
+    print(f"\n{'='*60}")
+    print(f"种子标签：{', '.join(seed_tags)}  |  共 {len(results)} 条推荐")
+    print(f"{'='*60}")
+
+    # 输出逗号分隔的标签串（方便直接复制使用）
+    tag_list = [r.tag for r in results if not (r.nsfw == '1' and args.no_nsfw)]
+    print(f"推荐标签：\n  {', '.join(tag_list)}\n")
+
+    # 明细表
+    for r in results:
+        if r.nsfw == '1' and args.no_nsfw:
+            continue
+        nsfw_mark   = "🔴" if r.nsfw == '1' else "🟢"
+        sources_str = f"  ← {', '.join(r.sources)}" if args.show_sources else ""
+        print(
+            f"  {nsfw_mark} [{r.cooc_score:.3f}] {r.tag:<30}"
+            f"  {r.cn_name[:20]:<20}  {r.category}"
+            f"  (共现:{r.cooc_count:,}){sources_str}"
+        )
+
+
+# ── 入口 ──────────────────────────────────────────────────────────────
+
+async def main():
+    parser = argparse.ArgumentParser(
+        description="Danbooru Tag CLI Searcher",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+示例：
+  python cli.py search "白色水手服的女孩" --limit 10
+  python cli.py related "white_serafuku,sailor_collar"
+  python cli.py related "white_serafuku" --limit 30 --no-nsfw --show-sources
+        """,
+    )
+    sub = parser.add_subparsers(dest='cmd', required=True)
+
+    _all_layers = ['英文', '中文扩展词', '释义', '中文核心词']
+    _all_cats   = ['General', 'Character', 'Copyright']
+
+    # ── search 子命令 ──
+    p_search = sub.add_parser('search', help='语义搜索标签')
+    p_search.add_argument('query',       help='搜索词（支持中英文自然语言）')
+    p_search.add_argument('--top-k',   type=int,   default=5,    help='每层返回数量（默认 5）')
+    p_search.add_argument('--limit',   type=int,   default=80,   help='结果上限（默认 80）')
+    p_search.add_argument('--weight',  type=float, default=0.15, help='热度权重（默认 0.15）')
+    p_search.add_argument('--no-nsfw', action='store_true',      help='过滤 NSFW 内容')
+    p_search.add_argument('--no-seg',  action='store_true',      help='禁用智能分词')
+    p_search.add_argument(
+        '--layers', nargs='+', default=_all_layers,
+        metavar='LAYER',
+        help=f'匹配层筛选，可多选，用空格分隔（默认全部）。可选值：{_all_layers}',
+    )
+    p_search.add_argument(
+        '--categories', nargs='+', default=_all_cats,
+        metavar='CAT',
+        help=f'标签类型筛选，可多选，用空格分隔（默认全部）。可选值：{_all_cats}',
+    )
+
+    # ── related 子命令 ──
+    p_related = sub.add_parser('related', help='基于共现表查关联推荐')
+    p_related.add_argument('tags',           help='种子标签，以英文逗号分隔（如 white_serafuku,sailor_collar）')
+    p_related.add_argument('--limit',        type=int, default=50, help='推荐结果上限（默认 50）')
+    p_related.add_argument('--no-nsfw',      action='store_true',  help='过滤 NSFW 内容')
+    p_related.add_argument('--show-sources', action='store_true',  help='显示每条推荐由哪个种子触发')
+
+    args = parser.parse_args()
+    if args.cmd == 'search':
+        await cmd_search(args)
+    elif args.cmd == 'related':
+        await cmd_related(args)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

core/counter.py

@@ -0,0 +1,392 @@
+"""
+core/counter.py
+──────────────
+极简持久化计数器（核心业务指标：总搜索、总访问、复制次数、成功交互、词频聚合、bad_case）。
+
+数据持久化到阿里云 OSS，通过 platform_utils 屏蔽细节。
+无任何本地落盘操作。
+
+count.json 结构：
+  {
+    "total":        int,
+    "visits":       int,
+    "copies":       int,
+    "successes":    int,
+    "hot_keywords": {word: count, ...},
+    "bad_cases":    [{q, t}, ...],
+    "history":      [{"date": "YYYY-MM-DD", "total": int}, ...]   # 每日快照，最近 180 天
+  }
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from collections import Counter
+from datetime import datetime, timezone, timedelta, date
+from typing import Optional
+
+from platform_utils import get_counter_cfg, read_bytes, upload_bytes, CounterConfig
+
+# ── 核心状态变量 ────────────────────────────────
+_memory_count: int = 0
+_dirty_count: int = 0
+
+_memory_visits: int = 0
+_dirty_visits: int = 0
+BASE_VISITS: int = 0
+
+_memory_copies: int = 0
+_dirty_copies: int = 0
+BASE_COPIES: int = 0
+
+_memory_mcp: int = 0
+_dirty_mcp: int = 0
+
+_memory_successes: int = 0
+_dirty_successes: int = 0
+
+_memory_keywords: Counter = Counter()
+_dirty_keywords: Counter = Counter()
+MAX_KEYWORDS_LIMIT = 200
+
+_memory_bad_cases: list[dict] = []
+_dirty_bad_cases: list[dict] = []
+MAX_BAD_CASES = 50
+
+_memory_history: list[dict] = []   # [{"date": "YYYY-MM-DD", "total": int}, ...]
+MAX_HISTORY_DAYS = 180
+
+_last_sync: float = 0.0
+_sync_lock: Optional[asyncio.Lock] = None
+
+SYNC_INTERVAL = 1800       # 每 30 分钟同步一次
+SYNC_THRESHOLD = 500       # 或各项增量之和达到 200 次时同步
+
+
+def _get_sync_lock() -> asyncio.Lock:
+    global _sync_lock
+    if _sync_lock is None:
+        _sync_lock = asyncio.Lock()
+    return _sync_lock
+
+
+# ── 历史快照工具 ──────────────────────────────────────────────────────────────
+
+def _today_str() -> str:
+    return datetime.now(timezone(timedelta(hours=8))).date().isoformat()
+
+
+def _merge_history(
+    remote: list[dict],
+    current_total: int,
+    memory: list[dict] | None = None,
+) -> list[dict]:
+    """
+    将当天的 total 写入（或更新）历史列表，保留最近 MAX_HISTORY_DAYS 天。
+    同一天只保留最新一条（total 取较大值）。
+
+    remote : 从 OSS 读回的历史（可能因缓存导致不完整）
+    memory : 内存中已加载的历史（init() 时从 OSS 完整读取，用于兜底）
+    """
+    today = _today_str()
+    by_date: dict[str, int] = {}
+    # 先用内存数据打底，再用远端数据覆盖（远端是最终写入态，优先级更高）
+    for r in (memory or []):
+        by_date[r['date']] = r['total']
+    for r in remote:
+        by_date[r['date']] = max(by_date.get(r['date'], 0), r['total'])
+    # 当天记录取较大值，避免同步时序问题导致数据回退
+    by_date[today] = max(by_date.get(today, 0), current_total)
+
+    sorted_records = sorted(by_date.items(), reverse=True)[:MAX_HISTORY_DAYS]
+    # 返回时按时间正序，方便绘图
+    return [{'date': d, 'total': t} for d, t in sorted(sorted_records)]
+
+
+# ── 远端 IO ───────────────────────────────────────────────────────────────────
+
+_COUNTER_FILE = 'count.json'
+
+
+def _parse_remote_data(raw: bytes | None) -> tuple[int, int, int, int, int, dict, list, list]:
+    """解析远端 JSON bytes，返回 (total, visits, copies, mcp, successes, keywords, bad_cases, history)。"""
+    if raw is None:
+        return 0, BASE_VISITS, BASE_COPIES, 0, 0, {}, [], []
+    try:
+        data = json.loads(raw.decode('utf-8'))
+        r_total     = int(data.get('total',     0))
+        r_visits    = int(data.get('visits',    BASE_VISITS))
+        r_copies    = int(data.get('copies',    BASE_COPIES))
+        r_mcp       = int(data.get('mcp',       0))
+        r_successes = int(data.get('successes', int(r_total * 0.75)))
+        r_keywords  = data.get('hot_keywords', {})
+        r_bad_cases = data.get('bad_cases', [])
+        r_history   = data.get('history', [])
+        return r_total, r_visits, r_copies, r_mcp, r_successes, r_keywords, r_bad_cases, r_history
+    except Exception:
+        return 0, BASE_VISITS, BASE_COPIES, 0, 0, {}, [], []
+
+
+def _read_remote() -> tuple[int, int, int, int, int, dict, list, list]:
+    cfg = get_counter_cfg()
+    if not cfg.available:
+        return 0, BASE_VISITS, BASE_COPIES, 0, 0, {}, [], []
+
+    try:
+        raw = read_bytes(_COUNTER_FILE, cfg)
+    except Exception as e:
+        print(f'[Counter] 启动读取远端数据异常: {e}')
+        return 0, BASE_VISITS, BASE_COPIES, 0, 0, {}, [], []
+
+    if raw is None:
+        return 0, BASE_VISITS, BASE_COPIES, 0, 0, {}, [], []
+    return _parse_remote_data(raw)
+
+
+def _sync_remote_task(
+    adds_count: int,
+    adds_visits: int,
+    adds_copies: int,
+    adds_mcp: int,
+    adds_successes: int,
+    adds_keywords: dict,
+    adds_bad_cases: list,
+    memory_history_snapshot: list,
+) -> tuple[bool, int, int, int, int, int, dict, list, list]:
+    cfg: CounterConfig = get_counter_cfg()
+    if not cfg.available:
+        return False, 0, 0, 0, 0, 0, {}, [], []
+
+    try:
+        raw = read_bytes(_COUNTER_FILE, cfg)
+    except Exception as e:
+        print(f'[Counter] 远端读取异常，中止本次同步以保护数据: {e}')
+        return False, 0, 0, 0, 0, 0, {}, [], []
+
+    r_total, r_visits, r_copies, r_mcp, r_successes, r_keywords, r_bad_cases, r_history = (
+        _parse_remote_data(raw)
+    )
+
+    n_total     = r_total     + adds_count
+    n_visits    = r_visits    + adds_visits
+    n_copies    = r_copies    + adds_copies
+    n_mcp       = r_mcp       + adds_mcp
+    n_successes = r_successes + adds_successes
+
+    merged_keywords = Counter(r_keywords)
+    for word, count in adds_keywords.items():
+        merged_keywords[word] += count
+    top_keywords = dict(merged_keywords.most_common(MAX_KEYWORDS_LIMIT))
+
+    merged_bad_cases = (adds_bad_cases + r_bad_cases)[:MAX_BAD_CASES]
+
+    n_history = _merge_history(r_history, n_total, memory=memory_history_snapshot)
+
+    content = json.dumps({
+        'total':        n_total,
+        'visits':       n_visits,
+        'copies':       n_copies,
+        'mcp':          n_mcp,
+        'successes':    n_successes,
+        'hot_keywords': top_keywords,
+        'bad_cases':    merged_bad_cases,
+        'history':      n_history,
+    }, ensure_ascii=False, indent=2).encode('utf-8')
+
+    commit_msg = (
+        f'Sync: 搜索:{n_total} | MCP:{n_mcp} | 成功:{n_successes} | '
+        f'复制:{n_copies} | 访问:{n_visits} | bad_cases:{len(merged_bad_cases)}'
+    )
+
+    ok = upload_bytes(content, _COUNTER_FILE, cfg, commit_msg, retries=3, retry_delay=1.0)
+    if ok:
+        print(
+            f'[Counter] 同步成功！搜索:{n_total}, MCP:{n_mcp}, 成功交互:{n_successes}, '
+            f'复制:{n_copies}, bad_cases:{len(merged_bad_cases)}'
+        )
+        return True, n_total, n_visits, n_copies, n_mcp, n_successes, top_keywords, merged_bad_cases, n_history
+
+    return False, 0, 0, 0, 0, 0, {}, [], []
+
+
+# ── 后台同步协程 ──────────────────────────────────────────────────────────────
+
+async def _perform_sync():
+    global _dirty_count, _dirty_visits, _dirty_copies, _dirty_mcp, _dirty_successes
+    global _dirty_keywords, _dirty_bad_cases, _last_sync
+    global _memory_count, _memory_visits, _memory_copies, _memory_mcp, _memory_successes
+    global _memory_keywords, _memory_bad_cases, _memory_history
+
+    lock = _get_sync_lock()
+    if lock.locked():
+        return
+
+    async with lock:
+        has_dirty = (
+            _dirty_count + _dirty_visits + _dirty_copies + _dirty_mcp + _dirty_successes
+            + len(_dirty_keywords) + len(_dirty_bad_cases)
+        ) > 0
+        if not has_dirty:
+            return
+
+        c_adds, v_adds, cp_adds, m_adds, s_adds = (
+            _dirty_count, _dirty_visits, _dirty_copies, _dirty_mcp, _dirty_successes
+        )
+        k_adds  = dict(_dirty_keywords)
+        bc_adds = list(_dirty_bad_cases)
+        history_snapshot = list(_memory_history)
+
+        _dirty_count     = 0
+        _dirty_visits    = 0
+        _dirty_copies    = 0
+        _dirty_mcp       = 0
+        _dirty_successes = 0
+        _dirty_keywords.clear()
+        _dirty_bad_cases.clear()
+
+        loop = asyncio.get_running_loop()
+        result = await loop.run_in_executor(
+            None, _sync_remote_task,
+            c_adds, v_adds, cp_adds, m_adds, s_adds, k_adds, bc_adds, history_snapshot,
+        )
+        success, l_total, l_visits, l_copies, l_mcp, l_successes, l_keywords, l_bad_cases, l_history = result
+
+        if success:
+            _last_sync = time.time()
+            _memory_count     = max(_memory_count,     l_total)
+            _memory_visits    = max(_memory_visits,    l_visits)
+            _memory_copies    = max(_memory_copies,    l_copies)
+            _memory_mcp       = max(_memory_mcp,       l_mcp)
+            _memory_successes = max(_memory_successes, l_successes)
+            _memory_keywords.clear()
+            _memory_keywords.update(l_keywords)
+            _memory_bad_cases.clear()
+            _memory_bad_cases.extend(l_bad_cases)
+            _memory_history.clear()
+            _memory_history.extend(l_history)
+        else:
+            _dirty_count     += c_adds
+            _dirty_visits    += v_adds
+            _dirty_copies    += cp_adds
+            _dirty_mcp       += m_adds
+            _dirty_successes += s_adds
+            _dirty_keywords.update(k_adds)
+            _dirty_bad_cases.extend(bc_adds)
+
+
+# ── 公共 API ──────────────────────────────────────────────────────────────────
+
+async def init():
+    """启动时从 OSS 拉取最新计数，初始化内存状态。"""
+    global _memory_count, _memory_visits, _memory_copies, _memory_mcp, _memory_successes
+    global _memory_keywords, _memory_bad_cases, _memory_history, _last_sync
+
+    cfg = get_counter_cfg()
+    if not cfg.available:
+        print(f'[Counter] 计数器未配置（platform={cfg.platform}），仅使用内存计数。')
+        return
+
+    loop = asyncio.get_running_loop()
+    (
+        _memory_count, _memory_visits, _memory_copies, _memory_mcp, _memory_successes,
+        r_keys, r_bad_cases, r_history,
+    ) = await loop.run_in_executor(None, _read_remote)
+
+    _memory_keywords.update(r_keys)
+    _memory_bad_cases.clear()
+    _memory_bad_cases.extend(r_bad_cases)
+    _memory_history.clear()
+    _memory_history.extend(r_history)
+    _last_sync = time.time()
+    print(
+        f'[Counter] 初始化完成（{cfg.platform}）：搜索={_memory_count}, MCP={_memory_mcp}, '
+        f'访问={_memory_visits}, 复制={_memory_copies}, 历史={len(_memory_history)}天'
+    )
+
+
+def _check_sync():
+    cfg = get_counter_cfg()
+    if not cfg.available:
+        return
+    if (time.time() - _last_sync > SYNC_INTERVAL) or (
+        _dirty_count + _dirty_visits + _dirty_copies + _dirty_mcp + _dirty_successes
+        + len(_dirty_keywords) + len(_dirty_bad_cases)
+    ) >= SYNC_THRESHOLD:
+        asyncio.create_task(_perform_sync())
+
+
+async def increment() -> int:
+    global _memory_count, _dirty_count
+    _memory_count += 1; _dirty_count += 1
+    _check_sync()
+    return _memory_count
+
+async def increment_visit() -> int:
+    global _memory_visits, _dirty_visits
+    _memory_visits += 1; _dirty_visits += 1
+    _check_sync()
+    return _memory_visits
+
+async def increment_copy() -> int:
+    global _memory_copies, _dirty_copies
+    _memory_copies += 1; _dirty_copies += 1
+    _check_sync()
+    return _memory_copies
+
+async def increment_mcp() -> int:
+    global _memory_mcp, _dirty_mcp
+    _memory_mcp += 1; _dirty_mcp += 1
+    _check_sync()
+    return _memory_mcp
+
+async def increment_success() -> int:
+    global _memory_successes, _dirty_successes
+    _memory_successes += 1; _dirty_successes += 1
+    _check_sync()
+    return _memory_successes
+
+async def add_keywords(words: list[str]):
+    global _dirty_keywords, _memory_keywords
+    valid_words = [w for w in words if len(w) > 1 and w not in {'一个', '的', '在', '了', '是', '有'}]
+    for word in valid_words:
+        _memory_keywords[word] += 1
+        _dirty_keywords[word] += 1
+    _check_sync()
+
+async def add_bad_case(query: str, platform: str = '', settings: dict | None = None) -> None:
+    global _dirty_bad_cases, _memory_bad_cases
+    entry = {
+        'q': query,
+        't': datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'),
+    }
+    if platform:
+        entry['platform'] = platform
+    if settings:
+        entry['settings'] = settings
+    _memory_bad_cases.insert(0, entry)
+    if len(_memory_bad_cases) > MAX_BAD_CASES:
+        _memory_bad_cases[:] = _memory_bad_cases[:MAX_BAD_CASES]
+    _dirty_bad_cases.insert(0, entry)
+    _check_sync()
+
+
+def get() -> int:           return _memory_count
+def get_visits() -> int:    return _memory_visits
+def get_copies() -> int:    return _memory_copies
+def get_mcp() -> int:       return _memory_mcp
+def get_successes() -> int: return _memory_successes
+
+def get_hot_keywords(top_n: int = 10) -> dict:
+    return dict(_memory_keywords.most_common(top_n))
+
+def get_bad_cases() -> list[dict]:
+    return list(_memory_bad_cases)
+
+def get_history() -> list[dict]:
+    """返回每日搜索量快照，格式 [{"date": "YYYY-MM-DD", "total": int}, ...]，按日期正序。"""
+    return list(_memory_history)
+
+async def force_sync():
+    await _perform_sync()

core/engine.py

@@ -0,0 +1,897 @@
+"""
+core/engine.py
+──────────────
+DanbooruTagger 核心引擎
+
+缓存格式（存于 cache_dir/ 目录）：
+  embeddings.safetensors   — 四路向量矩阵（FP16），行顺序与 metadata.parquet 完全对齐
+  metadata.parquet         — DataFrame（name/cn_name/cn_core/wiki/nsfw/category/post_count）
+  meta.json                — 标量元数据（max_log_count、schema_version）
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import time
+from collections import OrderedDict
+from pathlib import Path
+from datetime import datetime
+from typing import Any, Optional
+
+import jieba
+import numpy as np
+import pandas as pd
+import torch
+from safetensors.torch import load_file as st_load, save_file as st_save
+from sentence_transformers import SentenceTransformer
+
+from .models import SearchRequest, SearchResponse, TagResult
+from platform_utils import (
+    PLATFORM,
+    is_cloud,
+    download_file,
+    resolve_model_path,
+)
+
+
+# LRU 缓存
+class LRUCache:
+    def __init__(self, maxsize: int):
+        self._cache: OrderedDict[Any, Any] = OrderedDict()
+        self._maxsize = maxsize
+
+    def get(self, key: Any) -> Any:
+        if key not in self._cache:
+            return None
+        self._cache.move_to_end(key)
+        return self._cache[key]
+
+    def put(self, key: Any, value: Any) -> None:
+        if key in self._cache:
+            self._cache.move_to_end(key)
+        else:
+            if len(self._cache) >= self._maxsize:
+                self._cache.popitem(last=False)
+        self._cache[key] = value
+
+    def __len__(self) -> int:
+        return len(self._cache)
+
+
+# ──────────────────────────────────────────────
+# 常量
+# ──────────────────────────────────────────────
+
+STOP_WORDS: frozenset[str] = frozenset({
+    ',', '.', ':', ';', '?', '!', '"', "'", '`',
+    '(', ')', '[', ']', '{', '}', '<', '>',
+    '-', '_', '=', '+', '/', '\\', '|', '@', '#', '$', '%', '^', '&', '*', '~',
+    '，', '。', '：', '；', '？', '！', '\u201c', '\u201d', '\u2018', '\u2019',
+    '（', '）', '【', '】', '《', '》', '、', '…', '—', '·',
+    ' ', '\t', '\n', '\r',
+    '的', '地', '得', '了', '着', '过',
+    '是', '为', '被', '给', '把', '让', '由',
+    '在', '从', '自', '向', '往', '对', '于',
+    '和', '与', '及', '或', '且', '而', '但', '并', '即', '又', '也',
+    '啊', '吗', '吧', '呢', '噢', '哦', '哈', '呀', '哇',
+    '我', '你', '他', '她', '它', '我们', '你们', '他们',
+    '这', '那', '此', '其', '谁', '啥', '某', '每',
+    '这个', '那个', '这些', '那些', '这里', '那里',
+    '个', '位', '只', '条', '张', '幅', '件', '套', '双', '对', '副',
+    '种', '类', '群', '些', '点', '份', '部', '名',
+    '很', '太', '更', '最', '挺', '特', '好', '真',
+    '一', '一个', '一种', '一下', '一点', '一些',
+    '有', '无', '非', '没', '不',
+    '正在', '已经', '正', '刚', '开始', '继续', '一直', '不断',
+    '穿着', '戴着', '穿', '戴',
+    '带有', '具有', '拥有',
+    '看起来', '看上去', '显得', '仿佛', '似乎',
+    '十分', '非常', '特别', '比较',
+    '图片', '画面', '图像',
+    '位于', '处于',
+    '许多', '大量', '各种', '所有', '其他', '其它'
+})
+
+CAT_MAP: dict[str, str] = {
+    '0': 'General', '1': 'Artist', '3': 'Copyright', '4': 'Character', '5': 'Meta',
+}
+
+SCHEMA_VERSION = 3   # 升级此值将自动触发全量重建，用于破坏性格式变更
+
+# 用户显式分隔后，纯 CJK 片段超过此长度仍用 jieba 切分（避免长句被当作原子概念）
+_ATOMIC_CJK_MAX_LEN = 7
+
+# 四路 embedding 层配置: (层名, tensor 属性名, DataFrame 列名)
+_LAYER_SPEC: list[tuple[str, str, str]] = [
+    ('英文',   'emb_en',      'name'),
+    ('中文扩展词', 'emb_cn',      'cn_name'),
+    ('释义',   'emb_wiki',    'wiki'),
+    ('中文核心词', 'emb_cn_core', 'cn_core'),
+]
+_ALL_LAYER_NAMES = [ln for ln, _, _ in _LAYER_SPEC]
+
+
+# ──────────────────────────────────────────────
+# 缓存路径助手
+# ──────────────────────────────────────────────
+
+class _CachePaths:
+    def __init__(self, cache_dir: str | Path):
+        self.dir        = Path(cache_dir)
+        self.embeddings = self.dir / 'danbooru_multiview_embeddings.safetensors'
+        self.metadata   = self.dir / 'tags_metadata.parquet'
+        self.meta_json  = self.dir / 'version_data.json'
+
+    def exists(self) -> bool:
+        return (
+            self.embeddings.is_file()
+            and self.metadata.is_file()
+            and self.meta_json.is_file()
+        )
+
+    def ensure_dir(self):
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+
+class DanbooruTagger:
+    """核心搜索引擎（单例）"""
+
+    _instance: Optional['DanbooruTagger'] = None
+    _lock: Optional[asyncio.Lock] = None
+
+    @classmethod
+    def is_ready(cls) -> bool:
+        return cls._instance is not None and cls._instance.is_loaded
+
+    @classmethod
+    async def get_instance(cls, **kwargs) -> 'DanbooruTagger':
+        if cls._lock is None:
+            cls._lock = asyncio.Lock()
+        async with cls._lock:
+            if cls._instance is None:
+                inst = cls(**kwargs)
+                await asyncio.to_thread(inst.load)
+                cls._instance = inst
+            return cls._instance
+
+    def __init__(
+        self,
+        model_path: Optional[str] = None,
+        csv_file:   str = 'origin_database/tags_enhanced.csv',
+        cache_dir:  str = 'tags_embedding',
+        cooc_file:  str = 'origin_database/cooccurrence_clean.csv',
+    ):
+        # 模型路径：优先使用显式传入，否则交由 platform_utils 解析
+        self.model_path = model_path or resolve_model_path()
+
+        self.csv_path  = csv_file
+        self.device    = 'cuda' if torch.cuda.is_available() else 'cpu'
+        self.paths     = _CachePaths(cache_dir)
+        self.cooc_file = cooc_file
+
+        self.model:         Optional[SentenceTransformer]         = None
+        self.df:            Optional[pd.DataFrame]                = None
+        self.emb_en:        Optional[torch.Tensor]                = None
+        self.emb_cn:        Optional[torch.Tensor]                = None
+        self.emb_wiki:      Optional[torch.Tensor]                = None
+        self.emb_cn_core:   Optional[torch.Tensor]                = None
+        self.max_log_count: float                                 = 15.0
+        self.cooc: dict[str, list[tuple[str, int]]]               = {}
+        self._name_to_idx: dict[str, int]                         = {}
+        self.is_loaded:     bool                                  = False
+
+        # 预提取的列数组，避免热点路径上反复执行 df.iloc[idx]
+        self._arr_name:       Optional[np.ndarray] = None
+        self._arr_cn_name:    Optional[np.ndarray] = None
+        self._arr_category:   Optional[np.ndarray] = None
+        self._arr_nsfw:       Optional[np.ndarray] = None
+        self._arr_wiki:       Optional[np.ndarray] = None
+        self._arr_post_count: Optional[np.ndarray] = None
+        self._arr_pop_score:  Optional[np.ndarray] = None
+
+        # 三层 LRU 缓存（纯内存，重启后自动重热）
+        # embedding 缓存：key=文本, value=归一化后的 1-D Tensor (D,)，约 40 MB
+        self._emb_cache:     LRUCache = LRUCache(maxsize=10_000)
+        # 搜索结果缓存：key=请求参数 tuple, value=SearchResponse，约 100 MB
+        self._search_cache:  LRUCache = LRUCache(maxsize=5_000)
+        # 关联推荐缓存：key=(seed_tuple, limit, show_nsfw), value=list[RelatedTag]，约 20 MB
+        self._related_cache: LRUCache = LRUCache(maxsize=2_000)
+
+    # ── 初始化 ────────────────────────────────────────────────────────────
+
+    def load(self) -> None:
+        """同步加载，在线程池中调用。"""
+        if self.is_loaded:
+            return
+        t0 = time.time()
+
+        # ── 云端环境：从对应平台 Hub 拉取数据文件 ──────────────────────────
+        if is_cloud():
+            self._pull_cloud_files()
+
+        # ── 缓存校验与构建 ─────────────────────────────────────────────────
+        if not self.paths.exists():
+            print('\n' + '=' * 50)
+            print('[Engine] 未找到缓存，开始首次构建（约 1~3 分钟）...')
+            print('=' * 50 + '\n')
+            self._load_model()
+            self._build_full()
+        else:
+            print(f'[Engine] 加载缓存 ({self.paths.dir}) ...')
+            self._load_from_cache()
+            if self._cached_schema_version() != SCHEMA_VERSION:
+                print('[Engine] 缓存格式版本不符，触发全量重建...')
+                self._load_model()
+                self._build_full()
+            elif os.path.exists(self.csv_path):
+                self._load_model()
+                self._smart_update()
+
+        if self.model is None:
+            self._load_model()
+
+        self._setup_jieba_from_memory()
+        self._load_cooc()
+        self._name_to_idx = {n: i for i, n in enumerate(self.df['name'])}
+        self._rebuild_arrays_from_df()
+        self._normalize_embeddings()
+        self.is_loaded = True
+        print(f'[Engine] 初始化完成，耗时 {time.time() - t0:.2f}s')
+
+    def _normalize_embeddings(self) -> None:
+        """
+        对四路 embedding 矩阵做 L2 归一化（in-place 替换 self.emb_*）。
+        归一化后 search 阶段可直接用矩阵乘法得到 cosine similarity，
+        无需每次调用 util.semantic_search 内部再做一次归一化。
+        """
+        for _, attr, _ in _LAYER_SPEC:
+            t = getattr(self, attr)
+            if t is None:
+                continue
+            setattr(self, attr, torch.nn.functional.normalize(t, p=2, dim=1))
+
+    def _rebuild_arrays_from_df(self) -> None:
+        """
+        将 DataFrame 中搜索热点路径需要的列预提取为 numpy 数组。
+        任何修改 self.df 行内容或行数的操作之后都必须调用此方法刷新。
+        """
+        if self.df is None:
+            return
+        self._arr_name       = self.df['name'].to_numpy()
+        self._arr_cn_name    = self.df['cn_name'].to_numpy()
+        self._arr_category   = self.df['category'].astype(str).to_numpy()
+        self._arr_nsfw       = self.df['nsfw'].astype(str).to_numpy()
+        self._arr_wiki       = self.df['wiki'].astype(str).to_numpy()
+        self._arr_post_count = self.df['post_count'].to_numpy()
+        # 预算热度归一化分，避免 search 中每次 np.log1p
+        max_log = self.max_log_count if self.max_log_count > 0 else 1.0
+        self._arr_pop_score  = np.log1p(self._arr_post_count) / max_log
+
+    def _pull_cloud_files(self) -> None:
+        """
+        从当前云平台拉取所有数据文件，并将路径写回实例属性。
+        HF / MS 的差异完全由 platform_utils.download_file() 屏蔽。
+        """
+        print(f'[Engine] 云端环境 ({PLATFORM})，开始拉取数据文件...')
+
+        # ── HF 平台需要额外指定 repo_id（SPACE_ID）和 repo_type ──────────
+        extra_hf_kwargs = {}
+        if PLATFORM == 'hf':
+            extra_hf_kwargs = {
+                'hf_repo_id':   os.environ.get('SPACE_ID'),
+                'hf_repo_type': 'space',
+            }
+
+        def pull(filename: str) -> str:
+            try:
+                return download_file(filename, **extra_hf_kwargs)
+            except Exception as e:
+                print(f'[Engine] 拉取 {filename} 失败（非致命）: {e}')
+                return filename   # 回退到原始路径，让后续逻辑决定是否重建
+
+        self.csv_path  = pull('origin_database/tags_enhanced.csv')
+        self.cooc_file = pull('origin_database/cooccurrence_clean.parquet')
+
+        meta_path = pull('tags_embedding/tags_metadata.parquet')
+        emb_path  = pull('tags_embedding/danbooru_multiview_embeddings.safetensors')
+        json_path = pull('tags_embedding/version_data.json')
+
+        # 只有三个缓存文件都成功拉取才覆盖路径，防止部分失败导致 exists() 误判
+        if all(
+            Path(p).is_file()
+            for p in (meta_path, emb_path, json_path)
+        ):
+            self.paths.metadata   = Path(meta_path)
+            self.paths.embeddings = Path(emb_path)
+            self.paths.meta_json  = Path(json_path)
+            print('[Engine] 云端数据文件拉取完毕。')
+        else:
+            print('[Engine] 部分缓存文件拉取失败，将触发本地重建。')
+
+    # ── 搜索 ──────────────────────────────────────────────────────────────
+
+    def _encode_queries(self, queries: list[str]) -> torch.Tensor:
+        """批量编码查询词，命中 embedding 缓存的跳过 model.encode。"""
+        cached_vecs: list[Optional[torch.Tensor]] = [self._emb_cache.get(q) for q in queries]
+        uncached_idx = [i for i, v in enumerate(cached_vecs) if v is None]
+
+        if uncached_idx:
+            uncached_texts = [queries[i] for i in uncached_idx]
+            new_embs = self.model.encode(
+                uncached_texts, convert_to_tensor=True, show_progress_bar=False,
+            ).float()
+            new_embs = torch.nn.functional.normalize(new_embs, p=2, dim=1)
+            for j, i in enumerate(uncached_idx):
+                emb = new_embs[j]
+                self._emb_cache.put(queries[i], emb)
+                cached_vecs[i] = emb
+
+        return torch.stack(cached_vecs)  # type: ignore[arg-type]
+
+    def search(self, request: SearchRequest) -> SearchResponse:
+        if not self.is_loaded:
+            self.load()
+
+        cache_key = (
+            request.query,
+            request.top_k,
+            request.limit,
+            request.popularity_weight,
+            request.use_segmentation,
+            tuple(sorted(request.target_layers)),
+            tuple(sorted(request.target_categories)),
+        )
+        cached = self._search_cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        if request.use_segmentation:
+            raw_kw, raw_segments = self._smart_split(request.query)
+            keywords = [w.strip() for w in raw_kw if w.strip() and w.strip() not in STOP_WORDS]
+            # raw_segments: 分隔符切分后的原始片段（未经 jieba），作为从句级查询插入。
+            # 排除与完整 query 相同、以及已出现在 keywords 中的片段，避免重复编码和权重膨胀。
+            keywords_set = set(keywords)
+            extra_segments = [s for s in raw_segments if s != request.query and s not in keywords_set]
+            queries = [request.query] + extra_segments + keywords
+        else:
+            keywords = []
+            extra_segments = []
+            queries  = [request.query]
+
+        q_emb = self._encode_queries(queries)
+
+        tl    = request.target_layers
+        k     = request.top_k
+
+        # 每个查询词单独做意图识别，避免长句意图污染短分词
+        query_weights = [self._detect_intent(q) for q in queries]
+        active_layers = [ln for ln in _ALL_LAYER_NAMES if ln in tl]
+
+        # 预算每个 query × 每个 layer 的 top_k 配额
+        # cur_pvk_per_q[i][ln] = 第 i 个 query 在 layer ln 的配额
+        cur_pvk_per_q: list[dict[str, int]] = []
+        for cur_weights in query_weights:
+            if active_layers:
+                aw       = {l: cur_weights.get(l, 1.0) for l in active_layers}
+                total_aw = sum(aw.values())
+                cur_pvk  = {l: max(1, round(k * aw[l] / total_aw)) for l in active_layers}
+            else:
+                cur_pvk = {}
+            cur_pvk_per_q.append(cur_pvk)
+
+        target_cats = request.target_categories
+        w_pop       = request.popularity_weight
+
+        final: dict[str, TagResult] = {}
+
+        # 按 layer 批量做矩阵乘 + topk，合并 Q×L=20 次小调用为 L=4 次大调用
+        for ln, attr, _ in _LAYER_SPEC:
+            if ln not in tl:
+                continue
+            emb_matrix = getattr(self, attr)   # (N, D)，已归一化
+            if emb_matrix is None:
+                continue
+
+            # 该 layer 在所有 query 中的最大配额（少数 query 会算到多余的 hit，最后按各自配额截断）
+            k_max = max((cur_pvk_per_q[i].get(ln, 1) for i in range(len(queries))), default=1)
+            k_max = min(k_max, emb_matrix.shape[0])
+
+            scores = q_emb @ emb_matrix.T                       # (Q, N)
+            top_v, top_i = scores.topk(k_max, dim=1)            # (Q, k_max)
+            top_v_list = top_v.tolist()
+            top_i_list = top_i.tolist()
+
+            for i, source_word in enumerate(queries):
+                cur_weights = query_weights[i]
+                kq = cur_pvk_per_q[i].get(ln, 1)
+                layer_w = cur_weights.get(ln, 1.0)
+                row_v = top_v_list[i]
+                row_i = top_i_list[i]
+                # 仅取该 query 自己的配额条数
+                for j in range(min(kq, len(row_v))):
+                    score = row_v[j]
+                    if score < 0.35:
+                        # topk 已按分数降序，后续都低于阈值，可提前结束
+                        break
+                    idx = row_i[j]
+                    cat_text = CAT_MAP.get(self._arr_category[idx], 'Other')
+                    if cat_text not in target_cats:
+                        continue
+                    tag_name    = self._arr_name[idx]
+                    count       = self._arr_post_count[idx]
+                    pop_score   = self._arr_pop_score[idx]
+                    final_score = score * layer_w * (1 - w_pop) + pop_score * w_pop
+                    if tag_name not in final or final_score > final[tag_name].final_score:
+                        final[tag_name] = TagResult(
+                            tag=tag_name, cn_name=self._arr_cn_name[idx], category=cat_text,
+                            nsfw=self._arr_nsfw[idx],
+                            final_score=round(float(final_score), 4),
+                            semantic_score=round(float(score), 4),
+                            count=int(count), source=source_word, layer=ln,
+                            wiki=self._arr_wiki[idx],
+                        )
+
+        # ── 全句语义一致性软重排 ──────────────────────────────────────────
+        # 对每个候选标签，计算其与完整原始查询（而非分词片段）的语义相似度，
+        # 将相似度作为软因子乘入 final_score，使仅由分词碎片匹配到的噪声
+        # 标签自然下沉，同时不硬过滤任何结果。
+        full_q = q_emb[0]          # queries[0] 始终为完整原始查询
+        alpha  = 0.3 if SearchRequest.use_segmentation else 0   # 一致性调节强度（0=不调节, 1=完全按一致性重排），仅在启用分词时有意义
+        for r in final.values():
+            idx = self._name_to_idx[r.tag]
+            max_co = 0.0
+            for ln, attr, _ in _LAYER_SPEC:
+                if ln not in tl:
+                    continue
+                max_co = max(max_co, float(torch.dot(full_q, getattr(self, attr)[idx])))
+            # coherence=0 时最多扣 alpha=15%；coherence=1 时不扣分
+            r.final_score = round(r.final_score * (1.0 - alpha + alpha * max_co), 4)
+
+        # 收集每个查询源的 top-1 结果（高于阈值）
+        guaranteed_tags: set[str] = set()
+        for source_word in queries:
+            best: TagResult | None = None
+            for r in final.values():
+                if r.source == source_word and r.final_score > 0.45:
+                    if best is None or r.final_score > best.final_score:
+                        best = r
+            if best is not None:
+                guaranteed_tags.add(best.tag)
+
+        # 对所有候选进行排序，然后在保留保证结果的同时截断至限制数量
+        sorted_results = sorted(final.values(), key=lambda r: r.final_score, reverse=True)
+        valid: list[TagResult] = []
+        for r in sorted_results:
+            if r.final_score <= 0.45:
+                continue
+            if len(valid) < request.limit or r.tag in guaranteed_tags:
+                valid.append(r)
+
+        tags_all = ', '.join(r.tag for r in valid)
+        tags_sfw = ', '.join(r.tag for r in valid if r.nsfw != '1')
+        response = SearchResponse(
+            tags_all=tags_all, tags_sfw=tags_sfw,
+            results=valid, keywords=keywords, segments=extra_segments,
+        )
+        self._search_cache.put(cache_key, response)
+        return response
+
+    # ── 全量构建 ──────────────────────────────────────────────────────────
+
+    def _build_full(self) -> None:
+        print(f'[Engine] 全量读取 {self.csv_path} ...')
+        raw_df         = self._read_csv_robust(self.csv_path)
+        self.df        = self._preprocess_raw_df(raw_df)
+        self.max_log_count = float(np.log1p(self.df['post_count'].max()))
+        self._encode_all_and_save()
+
+    def _encode_all_and_save(self) -> None:
+        print('[Engine] 全量编码...')
+        for _, attr, col in _LAYER_SPEC:
+            setattr(self, attr, self._encode_texts(self.df[col].tolist()))
+        self._save_cache()
+
+    # ── 增量更新 ──────────────────────────────────────────────────────────
+
+    def _smart_update(self) -> None:
+        print('[Engine] 检查增量变更...')
+        t0 = time.time()
+
+        raw_df = self._read_csv_robust(self.csv_path)
+        new_df = self._preprocess_raw_df(raw_df)
+
+        _SIG_COLS = ['cn_name', 'wiki', 'cn_core']
+
+        def _sig(df: pd.DataFrame, iloc_idx: int) -> tuple:
+            row = df.iloc[iloc_idx]
+            return tuple(str(row.get(c, '')) for c in _SIG_COLS)
+
+        cached_idx: dict[str, int] = {n: i for i, n in enumerate(self.df['name'])}
+        new_idx:    dict[str, int] = {n: i for i, n in enumerate(new_df['name'])}
+
+        added_names   = [n for n in new_idx if n not in cached_idx]
+        deleted_names = [n for n in cached_idx if n not in new_idx]
+        changed_names = [
+            n for n in new_idx
+            if n in cached_idx and _sig(new_df, new_idx[n]) != _sig(self.df, cached_idx[n])
+        ]
+
+        if not added_names and not deleted_names and not changed_names:
+            print('[Engine] 数据已是最新，无需更新。')
+            return
+
+        print(f'[Engine] 变更 → 新增: {len(added_names)}  修改: {len(changed_names)}  删除: {len(deleted_names)}')
+
+        if deleted_names:
+            keep_mask = ~self.df['name'].isin(set(deleted_names))
+            keep_pos  = [i for i, v in enumerate(keep_mask) if v]
+            self.df = self.df[keep_mask].reset_index(drop=True)
+            for _, attr, _ in _LAYER_SPEC:
+                setattr(self, attr, getattr(self, attr)[keep_pos])
+            cached_idx = {n: i for i, n in enumerate(self.df['name'])}
+
+        if changed_names:
+            changed_rows = new_df[new_df['name'].isin(set(changed_names))].reset_index(drop=True)
+            _vecs = {attr: self._encode_texts(changed_rows[col].tolist()) for _, attr, col in _LAYER_SPEC}
+            for j, name in enumerate(changed_rows['name']):
+                ci = cached_idx[name]
+                for _, attr, _ in _LAYER_SPEC:
+                    getattr(self, attr)[ci] = _vecs[attr][j]
+                for col in changed_rows.columns:
+                    self.df.at[ci, col] = changed_rows.at[j, col]
+
+        if added_names:
+            added_rows = new_df[new_df['name'].isin(set(added_names))].reset_index(drop=True)
+            for _, attr, col in _LAYER_SPEC:
+                vecs = self._encode_texts(added_rows[col].tolist())
+                setattr(self, attr, torch.cat([getattr(self, attr), vecs], dim=0))
+            self.df = pd.concat([self.df, added_rows], ignore_index=True)
+
+        self.max_log_count = float(np.log1p(self.df['post_count'].max()))
+        self._name_to_idx = {n: i for i, n in enumerate(self.df['name'])}
+        self._rebuild_arrays_from_df()
+        self._normalize_embeddings()
+        self._save_cache()
+        print(f'[Engine] 增量更新完成，耗时 {time.time() - t0:.2f}s（共 {len(self.df)} 条）')
+
+    # ── 缓存 I/O ──────────────────────────────────────────────────────────
+
+    def _save_cache(self) -> None:
+        self.paths.ensure_dir()
+        st_save(
+            {attr: getattr(self, attr).half() for _, attr, _ in _LAYER_SPEC},
+            str(self.paths.embeddings),
+        )
+        save_cols = ['name', 'cn_name', 'cn_core', 'wiki', 'nsfw', 'category', 'post_count']
+        self.df[save_cols].to_parquet(str(self.paths.metadata), index=False)
+
+        current_time = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+        with open(self.paths.meta_json, 'w', encoding='utf-8') as f:
+            json.dump({
+                'schema_version': SCHEMA_VERSION,
+                'updated_at': current_time,
+            }, f, ensure_ascii=False, indent=4)
+
+        print(f'[Engine] 缓存保存完成（{len(self.df)} 条记录），生成时间: {current_time}')
+
+    def _load_from_cache(self) -> None:
+        tensors = st_load(str(self.paths.embeddings), device=self.device)
+        for _, attr, _ in _LAYER_SPEC:
+            setattr(self, attr, tensors[attr].float())
+        self.df = pd.read_parquet(str(self.paths.metadata))
+        self.max_log_count = float(np.log1p(self.df['post_count'].max()))
+
+    def _cached_schema_version(self) -> int:
+        try:
+            with open(self.paths.meta_json, 'r', encoding='utf-8') as f:
+                return int(json.load(f).get('schema_version', 1))
+        except Exception:
+            return 0
+
+    # ── 编码 & 预处理 ──────────────────────────────────────────────────────
+
+    def _encode_texts(self, texts: list[str]) -> torch.Tensor:
+        return self.model.encode(
+            texts, batch_size=64, show_progress_bar=False, convert_to_tensor=True,
+        ).float()
+
+    def _load_model(self) -> None:
+        if self.model is not None:
+            return
+        print(f'[Engine] 加载模型 (path={self.model_path}, device={self.device})...')
+        try:
+            self.model = SentenceTransformer(self.model_path, device=self.device)
+        except Exception as e:
+            print(f'[Engine] 指定路径加载失败，尝试重新解析: {e}')
+            fallback = resolve_model_path()
+            self.model = SentenceTransformer(fallback, device=self.device)
+
+    def _read_csv_robust(self, path: str) -> pd.DataFrame:
+        for enc in ['utf-8', 'gbk', 'gb18030']:
+            try:
+                return pd.read_csv(path, dtype=str, encoding=enc).fillna('')
+            except UnicodeDecodeError:
+                continue
+        raise ValueError('CSV 读取失败，请检查编码')
+
+    def _preprocess_raw_df(self, df: pd.DataFrame) -> pd.DataFrame:
+        df = df.copy()
+        df.dropna(subset=['name'], inplace=True)
+        df = df[df['name'].str.strip() != '']
+        for col in ['cn_name', 'category', 'wiki', 'nsfw']:
+            if col not in df.columns:
+                df[col] = ''
+        df['category']   = df['category'].fillna('0')
+        df['nsfw']       = df['nsfw'].fillna('0')
+        for char in ['，', '|', '、']:
+            df['cn_name'] = df['cn_name'].str.replace(char, ',', regex=False)
+        if 'post_count' not in df.columns:
+            df['post_count'] = 0
+        df['post_count'] = pd.to_numeric(df['post_count'], errors='coerce').fillna(0)
+        df['cn_name']    = df['cn_name'].fillna('')
+        df['wiki']       = df['wiki'].fillna('')
+        df['cn_core']    = df['cn_name'].str.split(',', n=1).str[0].str.strip().fillna('')
+        df.drop_duplicates(subset=['name'], inplace=True)
+        df.reset_index(drop=True, inplace=True)
+        return df
+
+    def _setup_jieba_from_memory(self) -> None:
+        if self.df is None:
+            return
+        unique_words: set[str] = set()
+        for text in self.df['cn_name'].dropna().astype(str):
+            for part in text.replace(',', ' ').split():
+                part = part.strip()
+                if len(part) > 1:
+                    unique_words.add(part)
+        for word in unique_words:
+            jieba.add_word(word, 2000)
+
+    def _detect_intent(self, query: str) -> dict[str, float]:
+        """
+        根据查询词特征返回各视图的语义分系数。
+        系数 > 1 表示加权，< 1 表示降权。
+        """
+        stripped = query.replace(' ', '')
+        cn_chars = sum(1 for c in stripped if '\u4e00' <= c <= '\u9fff')
+        en_chars = sum(1 for c in stripped if c.isascii() and c.isalpha())
+        total    = max(len(stripped), 1)
+        is_long  = len(query) > 8
+        is_cn    = cn_chars / total > 0.5
+        is_en    = en_chars / total > 0.5
+
+        if is_long and is_cn:
+            return {'英文': 0.8, '中文核心词': 0.9, '中文扩展词': 1.1, '释义': 1.4}
+        if is_long and is_en:
+            return {'英文': 1.0, '中文核心词': 0.8, '中文扩展词': 0.9, '释义': 1.3}
+        if is_cn:
+            return {'英文': 0.8, '中文核心词': 1.3, '中文扩展词': 1.1, '释义': 0.6}
+        if is_en:
+            return {'英文': 1.3, '中文核心词': 1.0, '中文扩展词': 0.8, '释义': 0.6}
+        return {'英文': 1.0, '中文核心词': 1.0, '中文扩展词': 1.0, '释义': 1.0}
+
+    def _smart_split(self, text: str) -> tuple[list[str], list[str]]:
+        """将查询文本拆分为关键词列表，同时返回分隔后的原始片段。
+
+        两层切分：
+        1. 首先按分隔符切分——空格、换行、中文逗号/顿号/分号/句号均视为
+           用户显式指定的概念边界（中文自然语句不使用这些符号来分隔概念）。
+        2. 若只有一个片段（无显式分隔），完全走原有 jieba 逻辑。
+           若有多片段，每个纯 CJK 片段按长度决定：
+           - ≤ _ATOMIC_CJK_MAX_LEN 字 → 原子概念，直接保留
+           - >  _ATOMIC_CJK_MAX_LEN 字 → 走 jieba 切分（长短语/短句）
+           混合文本（含标点/英文）片段始终走原有逻辑。
+
+        Returns:
+            (tokens, raw_segments):
+            - tokens: 处理后的关键词列表（原子概念或 jieba 切分结果）
+            - raw_segments: 分隔符切分后的原始片段（未经 jieba），用于多粒度查询
+        """
+        segments = [s.strip() for s in re.split(r'[\s\n\r，、；。]+', text) if s.strip()]
+        if not segments:
+            return [], []
+
+        tokens: list[str] = []
+        # 单一片段 → 无显式分隔，完全走原有 jieba 逻辑
+        if len(segments) == 1:
+            segment = segments[0]
+            for chunk in re.split(r'([一-龥]+)', segment):
+                if not chunk.strip():
+                    continue
+                if re.match(r'[一-龥]+', chunk):
+                    tokens.extend(jieba.cut(chunk))
+                else:
+                    cleaned = re.sub(r'[,()\[\]{}:]', ' ', chunk)
+                    for part in cleaned.split():
+                        try:
+                            float(part)
+                        except ValueError:
+                            tokens.append(part)
+            return tokens, segments
+
+        # 多片段 → 每个分隔的片段按长度决定是否原子保留
+        for segment in segments:
+            # 纯 CJK 片段
+            if re.match(r'^[一-龥]+$', segment):
+                if len(segment) <= _ATOMIC_CJK_MAX_LEN:
+                    tokens.append(segment)          # 短 → 原子概念
+                else:
+                    tokens.extend(jieba.cut(segment))  # 长 → jieba 切分
+                continue
+            # 混合文本 → 原有 jieba 切分逻辑
+            for chunk in re.split(r'([一-龥]+)', segment):
+                if not chunk.strip():
+                    continue
+                if re.match(r'[一-龥]+', chunk):
+                    tokens.extend(jieba.cut(chunk))
+                else:
+                    cleaned = re.sub(r'[,()\[\]{}:]', ' ', chunk)
+                    for part in cleaned.split():
+                        try:
+                            float(part)
+                        except ValueError:
+                            tokens.append(part)
+        return tokens, segments
+
+    # ── 关联推荐 ──────────────────────────────────────────────────────────
+
+    def get_related(
+            self,
+            seed_tags: list[str],
+            exclude: set[str] | None = None,
+            limit: int = 20,
+            show_nsfw: bool = True,
+    ) -> list:
+        from .models import RelatedTag
+        import math
+
+        if not self.cooc or not seed_tags:
+            return []
+        exclude = exclude or set()
+
+        related_key = (tuple(sorted(seed_tags)), tuple(sorted(exclude)), limit, show_nsfw)
+        cached = self._related_cache.get(related_key)
+        if cached is not None:
+            return cached
+
+        # 估算语料库总大小 N，取数据集中发帖量的最大值，并设置合理下限
+        total_posts = float(max(self.df['post_count'].max(), 7000000.0))
+
+        npmi_scores: dict[str, float] = {}
+        total_cooc: dict[str, int] = {}
+        tag_sources: dict[str, list[str]] = {}
+        name_to_idx = self._name_to_idx
+        arr_post_count = self._arr_post_count
+
+        for seed in seed_tags:
+            if seed not in name_to_idx:
+                continue
+
+            seed_count = float(arr_post_count[name_to_idx[seed]] or 1)
+
+            for neighbor, cnt in self.cooc.get(seed, []):
+                if neighbor in exclude or neighbor == seed:
+                    continue
+                if neighbor not in name_to_idx:
+                    continue
+
+                neighbor_count = float(arr_post_count[name_to_idx[neighbor]] or 1)
+
+                cooc = min(float(cnt), seed_count, neighbor_count)
+                if cooc <= 0:
+                    continue
+
+                # 计算分子：(Cooc * N) / (Count(A) * Count(B))
+                numerator = (cooc * total_posts) / (seed_count * neighbor_count)
+
+                # 忽略负相关或完全不相关的词条
+                if numerator <= 1.0:
+                    continue
+
+                pmi = math.log(numerator)
+
+                # 计算分母：-log(P(A, B))
+                p_a_b = cooc / total_posts
+                if p_a_b >= 1.0:
+                    npmi = 1.0
+                else:
+                    npmi = pmi / -math.log(p_a_b)
+
+                # 多词条搜索时累加 NPMI
+                npmi_scores[neighbor] = npmi_scores.get(neighbor, 0.0) + npmi
+                total_cooc[neighbor] = total_cooc.get(neighbor, 0) + cnt
+                tag_sources.setdefault(neighbor, []).append(seed)
+
+        if not npmi_scores:
+            return []
+
+        # 归一化用于前端展示
+        max_score = max(npmi_scores.values())
+
+        sorted_candidates = sorted(npmi_scores.items(), key=lambda x: x[1], reverse=True)
+        results = []
+
+        for tag_name, raw_score in sorted_candidates:
+            if len(results) >= limit:
+                break
+
+            idx = name_to_idx[tag_name]
+            nsfw = self._arr_nsfw[idx]
+            if nsfw == '1' and not show_nsfw:
+                continue
+
+            cat = CAT_MAP.get(self._arr_category[idx], 'Other')
+
+            results.append(RelatedTag(
+                tag=tag_name,
+                cn_name=str(self._arr_cn_name[idx]),
+                category=cat,
+                nsfw=nsfw,
+                cooc_count=total_cooc[tag_name],
+                cooc_score=round(raw_score / max_score, 4),
+                sources=tag_sources.get(tag_name, []),
+                post_count=int(self._arr_post_count[idx]),
+                wiki=str(self._arr_wiki[idx]) if self._arr_wiki is not None else '',
+            ))
+
+        self._related_cache.put(related_key, results)
+        return results
+
+    def _load_cooc(self) -> None:
+        csv_path     = Path(self.cooc_file)
+        parquet_path = csv_path.with_suffix('.parquet')
+
+        if parquet_path.is_file() and (
+            not csv_path.is_file()
+            or parquet_path.stat().st_mtime >= csv_path.stat().st_mtime
+        ):
+            read_path  = parquet_path
+            is_parquet = True
+        elif csv_path.is_file():
+            read_path  = csv_path
+            is_parquet = False
+        else:
+            print(f'[Engine] 未找到共现表 ({self.cooc_file})，关联推荐功能不可用。')
+            return
+
+        print(f'[Engine] 加载共现表 ({read_path.name})...')
+        t0 = time.time()
+        try:
+            if is_parquet:
+                df = pd.read_parquet(str(read_path))
+            else:
+                df = self._read_csv_robust(str(read_path))
+                df['count'] = pd.to_numeric(df['count'], errors='coerce').fillna(0).astype(int)
+                df.to_parquet(str(parquet_path), index=False)
+                print(f'[Engine] 已将共现表缓存为 {parquet_path.name}，下次启动将直接加载。')
+
+            tag_a  = df['tag_a'].astype(str).to_numpy()
+            tag_b  = df['tag_b'].astype(str).to_numpy()
+            counts = df['count'].astype(int).to_numpy()
+
+            src = np.concatenate([tag_a, tag_b])
+            dst = np.concatenate([tag_b, tag_a])
+            cnt = np.concatenate([counts, counts])
+
+            sort_idx = np.lexsort((-cnt, src))
+            src = src[sort_idx]
+            dst = dst[sort_idx]
+            cnt = cnt[sort_idx]
+
+            unique_srcs, first_pos = np.unique(src, return_index=True)
+            end_pos = np.append(first_pos[1:], len(src))
+
+            cooc: dict[str, list[tuple[str, int]]] = {}
+            for s, start, end in zip(unique_srcs, first_pos, end_pos):
+                cooc[s] = list(zip(dst[start:end].tolist(), cnt[start:end].tolist()))
+
+            self.cooc = cooc
+            print(
+                f'[Engine] 共现表加载完成，{len(cooc):,} 个 tag，'
+                f'耗时 {time.time() - t0:.2f}s'
+            )
+        except Exception as e:
+            print(f'[Engine] 共现表加载失败: {e}')

core/models.py

@@ -0,0 +1,61 @@
+"""
+core/models.py
+数据结构
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+@dataclass
+class TagResult:
+    """单条标签搜索结果。"""
+    tag: str
+    cn_name: str
+    category: str
+    nsfw: str
+    final_score: float
+    semantic_score: float
+    count: int
+    source: str
+    layer: str
+    wiki: str = ""
+
+
+@dataclass
+class RelatedTag:
+    """单条关联推荐结果"""
+    tag: str
+    cn_name: str
+    category: str
+    nsfw: str
+    cooc_count: int       # 累计共现次数
+    cooc_score: float     # 归一化分数
+    sources: list[str] = field(default_factory=list)  # 触发该推荐的种子 tag 列表
+    post_count: int = 0   # 该标签的发帖总数（与 search_tags 的 count 对齐）
+    wiki: str = ""        # 标签 wiki 描述
+
+
+@dataclass
+class SearchRequest:
+    """搜索参数"""
+    query: str
+    top_k: int = 5
+    limit: int = 80
+    popularity_weight: float = 0.15
+    show_nsfw: bool = True
+    use_segmentation: bool = True
+    target_layers: list[str] = field(
+        default_factory=lambda: ['英文', '中文扩展词', '释义', '中文核心词']
+    )
+    target_categories: list[str] = field(
+        default_factory=lambda: ['General', 'Character', 'Copyright']
+    )
+
+
+@dataclass
+class SearchResponse:
+    """搜索返回值。"""
+    tags_all: str
+    tags_sfw: str
+    results: list[TagResult]
+    keywords: list[str]
+    segments: list[str] = field(default_factory=list)  # 分隔符切分后的原始从句级片段

mcp_server.py

@@ -0,0 +1,283 @@
+"""
+mcp_server.py
+─────────────
+MCP 服务层
+
+挂载方式（在 ui_nicegui.py 中）：
+    from mcp_server import mcp
+    app.mount('/mcp', mcp.streamable_http_app())
+
+接入地址：
+    https://sakizuki-danboorusearch.hf.space/mcp/mcp
+
+支持的工具：
+    search_tags      自然语言搜索标签
+    get_related_tags 基于共现表查关联推荐
+"""
+
+import json
+import asyncio
+from mcp.server.fastmcp import FastMCP
+from mcp.server.transport_security import TransportSecuritySettings
+from core.engine import DanbooruTagger
+from core.models import SearchRequest
+import core.counter as counter
+import re
+
+
+mcp = FastMCP(
+    name="danbooru-searcher",
+    transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),
+)
+
+
+@mcp.tool()
+async def search_tags(
+    query: str,
+    use_segmentation: bool = True,
+    top_k: int = 5,
+    limit: int = 80,
+    popularity_weight: float = 0.15,
+    show_nsfw: bool = True,
+    include_wiki: bool = False,
+    category: str = "all",
+) -> str:
+    """
+Search Danbooru tags using natural language and return a ready-to-use prompt.
+
+## Args
+- query: Natural language description (Chinese recommended).
+- use_segmentation: Split multi-concept input into segments for separate retrieval. True for scene descriptions, False for single-concept queries.
+- top_k: Candidates recalled per segment. Semantics change with use_segmentation — see guide below.
+- limit: Max tags returned.
+- popularity_weight: Influence of tag post count on ranking (0.0–1.0). Default 0.15.
+- show_nsfw: Include NSFW tags. Default True.
+- include_wiki: Append wiki description to each result. Default False.
+- category: Filter results to a specific tag category. Default "all".
+    "all"       —  All categories (通用 + 版权 + 人物 )
+    "general"   —  General: visual attributes, clothing, pose, background, etc.
+    "copyright" —  Copyright: specific anime/game/franchise titles
+    "character" —  Character: named characters from any series
+    Use this when you know what kind of tag you need — e.g. looking for a
+    character name vs. describing a scene visually.
+
+## Query writing guide
+
+The `query` parameter supports explicit delimiter control for precise segmentation.
+
+### Explicit delimiters
+
+Use **spaces, newlines, Chinese commas (，), or Chinese dunhao (、)** to manually separate concepts.
+Each delimiter-bounded segment ≤7 characters stays atomic — the engine respects your intent.
+
+| Query style | Example | When to use |
+|---|---|---|
+| Concept list (spaces) | `运动社团 校队 比赛 运动会` | You know the exact concepts to search |
+| Concept list (dun hao) | `反乌托邦、赛博朋克、蒸汽朋克` | Same, with Chinese list punctuation |
+| Natural sentence | `一个穿着白色水手服的少女在雨中奔跑` | Scene description, let the engine auto-split |
+| Mixed | `运动社团 一个穿水手服的少女` | Mix concepts with descriptive phrases |
+
+Segments >7 characters are still auto-split by jieba, but the raw segment is kept as an additional query
+to preserve clause-level semantics (multi-granularity retrieval).
+
+### Recommendations
+
+1. **Concept lists → use explicit delimiters:** Group independent concepts with spaces or dunhao.
+   `运动社团 校队 比赛 体育祭 田径部` is better than `运动社团校队比赛体育祭田径部`.
+
+2. **Scene descriptions → write naturally:** Natural Chinese with Chinese commas works well for full scenes.
+   `一个穿着白色水手服，蓝色短裙的少女在雨中奔跑` — commas here are grammatical, not delimiters.
+
+3. **Precise lookup → turn off segmentation:** For finding a specific character or copyright title,
+   set `use_segmentation=False` and combine with `category` filter.
+   e.g. `query="EVA中蓝发的零号机驾驶员"` with `category="character"` and `use_segmentation=False`.
+
+4. **Category filtering:** Use `category` to narrow results. Looking for a character?
+   `category="character"`. Building a scene prompt? `category="general"`.
+
+## Parameter guide
+
+### Step 1 — Decide use_segmentation + top_k together
+
+top_k means "candidates per segment"; its effect depends on whether segmentation is on.
+
+Multi-concept input (scene description) → use_segmentation=True
+
+| Sub-scenario          | top_k | Reason                                                   |
+|-----------------------|-------|----------------------------------------------------------|
+| Full scene → prompt   | 5     | Many segments; low top_k distributes result slots fairly |
+| Vague concept explore | 80    | Few segments; high top_k needed for broad recall         |
+
+Single-concept input → use_segmentation=False
+
+top_k acts as total candidate pool size. Use 20 for all single-concept cases.
+
+| Sub-scenario                  | top_k |
+|-------------------------------|-------|
+| Describe subject / find tag   | 20    |
+| Precise lookup / spell fix    | 20    |
+
+### Step 2 — Decide limit independently
+
+| Goal                         | limit |
+|------------------------------|-------|
+| Full prompt for image gen    | 80    |
+| Concept exploration          | 20–80 |
+| Precise lookup / role search | 10–20 |
+
+### Auxiliary params
+
+popularity_weight (default 0.15, rarely needs changing):
+- Higher (0.3+): favor common, well-established tags
+- Lower (0.0): surface niche/rare tags
+
+include_wiki (default False):
+- True: tag meaning matters — disambiguation, explaining tags to user, exploring unfamiliar domains
+- False: prompt generation (wiki irrelevant to downstream), tags already known
+
+### Quick reference
+
+| Scenario                      | use_segmentation | top_k | limit |
+|-------------------------------|------------------|-------|-------|
+| Full scene → prompt (default) | True             | 5     | 80    |
+| Vague concept exploration     | True             | 80    | 80    |
+| Describe subject / find tag   | False            | 20    | 20    |
+| Precise lookup / spell fix    | False            | 20    | 10    |
+
+### Workflow
+
+After search_tags, pass selected tags to get_related_tags to discover complementary tags via co-occurrence (accessories, character features, scene atmosphere).
+
+## Examples
+
+Precise lookup / spell fix — e.g. "selafuku", "thighhigh", "twintail"
+→ use_segmentation=False, top_k=20, limit=10
+
+Vague concept exploration — e.g. "兔耳朵", "赛博朋克服装", "假肢"
+→ use_segmentation=True, top_k=80, limit=80
+
+Describe subject / find tag — e.g. "EVA中蓝发的零号机驾驶员", "命运石之门中的助手"
+→ use_segmentation=False, top_k=20, limit=20
+
+Full scene → prompt — e.g. "一个穿着白色水手服，蓝色短裙的少女在雨中的城市里奔跑"
+→ use_segmentation=True, top_k=5, limit=80
+
+## Returns
+JSON with: prompt (comma-separated tags), keywords, results.
+Each result: tag, cn_name, category, final_score, count[, wiki if include_wiki=True].
+    """
+    _CATEGORY_MAP: dict[str, list[str]] = {
+        "all":       ["General", "Character", "Copyright", "Artist", "Meta"],
+        "general":   ["General"],
+        "character": ["Character"],
+        "copyright": ["Copyright"],
+    }
+    target_categories = _CATEGORY_MAP.get(
+        category,
+        _CATEGORY_MAP["all"],  # unrecognized value → fall back to all
+    )
+
+    tagger = await DanbooruTagger.get_instance()
+    request = SearchRequest(
+        query=query,
+        top_k=top_k,
+        limit=limit,
+        popularity_weight=popularity_weight,
+        show_nsfw=show_nsfw,
+        use_segmentation=use_segmentation,
+        target_categories=target_categories,
+    )
+    response = await asyncio.to_thread(tagger.search, request)
+    # 计数：每次 MCP 搜索调用均计入搜索、成功、复制；访问不变
+    await counter.increment()
+    await counter.increment_success()
+    await counter.increment_copy()
+    await counter.increment_mcp()
+
+    results = []
+    for r in response.results:
+        if r.nsfw == '1' and not show_nsfw:
+            continue
+        item = {
+            "tag":         r.tag,
+            "cn_name":     r.cn_name,
+            "category":    r.category,
+            "final_score": r.final_score,
+            "count":       r.count,
+        }
+        if include_wiki:
+            item["wiki"] = r.wiki
+        results.append(item)
+
+    payload = {
+        "prompt":   response.tags_sfw if not show_nsfw else response.tags_all,
+        "keywords": response.keywords,
+        "results":  results,
+    }
+    han_chars = re.findall(r'[\u4e00-\u9fff]', query)
+    if len(query) > 0 and len(han_chars) / len(query) < 0.5:
+        payload["hint"] = (
+            "检测到英文查询，该搜索引擎对中文查询优化更好，如果搜索结果不合预期，推荐用中文重试"
+        )
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+
+@mcp.tool()
+async def get_related_tags(
+    tags: list[str],
+    limit: int = 20,
+    show_nsfw: bool = True,
+    include_wiki: bool = False,
+) -> str:
+    """
+Return co-occurrence-based tag recommendations for a given tag list (NPMI scoring).
+Typical workflow: call search_tags first, then pass selected tags here to discover complementary ones.
+
+Works well for: clothing accessories, character visual features, theme exploration, multi-tag intersections.
+    e.g. tags=["fingerless_gloves"] → returns characters often wearing them
+    e.g. tags=["amiya_(arknights)"] → returns outfit, expression, accessory tags
+         that define this character's appearance
+    e.g. tags=["fighter_jet"] → returns aircraft types, action, background tags
+    e.g. tags=["maid", "twintails"] → returns tags specific to the
+         "maid + twintails" combination, not just each tag individually
+
+Args:
+    tags:      List of Danbooru tag names, e.g. ["white_serafuku", "sailor_collar"].
+    limit:     Maximum number of recommendations returned.
+    show_nsfw: Whether to include NSFW tags. Defaults to True.
+    include_wiki: Append wiki description to each result. Default False.
+
+Returns:
+    A JSON string containing recommended tags sorted by NPMI co-occurrence score.
+    Each result: tag, cn_name, category, count, cooc_score, sources[, wiki if include_wiki=True].
+    """
+    tagger = await DanbooruTagger.get_instance()
+    results = await asyncio.to_thread(
+        tagger.get_related,
+        tags,
+        set(tags),
+        limit,
+        show_nsfw,
+    )
+    # 计数：每次 MCP related 调用均计入搜索、成功、复制；访问不变
+    await counter.increment()
+    await counter.increment_success()
+    await counter.increment_copy()
+    await counter.increment_mcp()
+
+    output = []
+    for r in results:
+        item = {
+            "tag":        r.tag,
+            "cn_name":    r.cn_name,
+            "category":   r.category,
+            "count":      r.post_count,
+            "cooc_score": r.cooc_score,
+            "sources":    r.sources,
+        }
+        if include_wiki:
+            item["wiki"] = r.wiki
+        output.append(item)
+
+    return json.dumps(output, ensure_ascii=False, indent=2)

platform_utils.py

@@ -0,0 +1,298 @@
+"""
+platform_utils.py
+
+统一的平台检测与 Hub 操作封装。
+
+支持平台：
+  - HuggingFace Space
+  - ModelScope 创空间（魔搭）
+  - 本地开发环境
+
+对外暴露：
+  PLATFORM          : Literal['hf', 'ms', 'local']
+  is_cloud()        : bool
+  get_host_port()   : tuple[str, int]
+  download_file()   : 下载单个文件，返回本地路径
+  upload_bytes()    : 上传 bytes 到 OSS（用于计数器持久化）
+  read_bytes()      : 从 OSS 读取文件内容，返回 bytes | None
+  get_counter_cfg() : 返回 CounterConfig（platform / available）
+
+环境变量约定：
+  
+   HuggingFace Space（由 HF 自动注入）                                  
+     SPACE_ID          Space 唯一标识，存在即代表在 HF 环境            
+     SPACE_AUTHOR_NAME 作者名                                           
+                                                                        
+   用户手动配置（HF Secrets）：                                         
+     HF_TOKEN          HF 访问令牌（仅用于 download_file，非计数器）    
+
+   ModelScope 创空间（由魔搭自动注入）                                   
+     MODELSCOPE_ENVIRONMENT  存在即代表在魔搭环境（值通常为 "studio"）  
+     STUDIO_ID               创空间 ID（备用检测）                      
+                                                                        
+   魔搭平台数据文件说明：                                                
+     数据文件（CSV / parquet / safetensors）直接放在创空间 studio repo  
+     中，容器启动时会自动同步到工作目录，download_file() 在 MS 平台     
+     直接返回本地路径，无需额外配置 Model repo。                         
+
+   阿里云 OSS（计数器唯一后端，HF 与 MS 共享同一数据）                  
+                                                                        
+     OSS_ACCESS_KEY_ID      RAM 子账号 AccessKey ID                    
+     OSS_ACCESS_KEY_SECRET  RAM 子账号 AccessKey Secret                
+     OSS_ENDPOINT           Bucket 所在地域节点                         
+                            例: oss-cn-hangzhou.aliyuncs.com           
+                            （无需加 https://，代码自动拼接）            
+     OSS_BUCKET_NAME        Bucket 名称                                 
+     OSS_COUNTER_DIR        计数文件在 Bucket 中的前缀目录（可选）       
+                            默认 "danbooru_counter"                    
+                            最终路径: {OSS_COUNTER_DIR}/count.json
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+import oss2
+from typing import Literal, Optional
+
+#  平台检测 
+
+def _detect_platform() -> Literal['hf', 'ms', 'local']:
+    if os.environ.get('SPACE_ID'):
+        return 'hf'
+    if os.environ.get('MODELSCOPE_ENVIRONMENT') or os.environ.get('STUDIO_ID'):
+        return 'ms'
+    return 'local'
+
+
+PLATFORM: Literal['hf', 'ms', 'local'] = _detect_platform()
+
+
+def is_cloud() -> bool:
+    """是否运行在任意云端平台。"""
+    return PLATFORM in ('hf', 'ms')
+
+
+def get_host_port() -> tuple[str, int]:
+    """
+    返回 NiceGUI 应使用的 (host, port)。
+    HF 和魔搭创空间都使用 0.0.0.0:7860；本地使用 127.0.0.1:1111。
+    """
+    if is_cloud():
+        return '0.0.0.0', 7860
+    return '127.0.0.1', 11111
+
+
+def nsfw_allowed() -> bool:
+    """
+    返回当前平台是否允许用户开启 NSFW 显示。
+    魔搭（MS）平台禁用 NSFW，其余平台默认允许。
+    如需在任意平台强制禁用，可设置环境变量 DISABLE_NSFW=1。
+    """
+    if os.environ.get('DISABLE_NSFW', '0') == '1':
+        return False
+    return PLATFORM != 'ms'
+
+
+#  阿里云 OSS 
+
+def _get_oss_bucket():
+    """
+    从环境变量读取 OSS 配置，返回 oss2.Bucket 对象。
+    若环境变量不完整或 oss2 未安装则返回 None。
+    """
+    ak  = os.environ.get('OSS_ACCESS_KEY_ID')
+    sk  = os.environ.get('OSS_ACCESS_KEY_SECRET')
+    ep  = os.environ.get('OSS_ENDPOINT')
+    bkt = os.environ.get('OSS_BUCKET_NAME')
+    if not all([ak, sk, ep, bkt]):
+        return None
+    try:
+        import oss2
+        auth = oss2.Auth(ak, sk)
+        endpoint = ep if ep.startswith('http') else f'https://{ep}'
+        return oss2.Bucket(auth, endpoint, bkt)
+    except ImportError:
+        print('[PlatformUtils] oss2 未安装，OSS 计数器不可用。请 pip install oss2。')
+        return None
+
+
+def _oss_key(filename: str) -> str:
+    """将 filename 拼上可选的前缀目录，得到 OSS Object Key。"""
+    prefix = os.environ.get('OSS_COUNTER_DIR', 'danbooru_counter').rstrip('/')
+    return f'{prefix}/{filename}'
+
+
+def _oss_available() -> bool:
+    """检测 OSS 四项环境变量是否均已设置且 oss2 可导入。"""
+    return _get_oss_bucket() is not None
+
+
+#  计数器配置 
+
+@dataclass
+class CounterConfig:
+    platform: Literal['oss', 'local']
+
+    @property
+    def available(self) -> bool:
+        if self.platform == 'oss':
+            return _oss_available()
+        return False
+
+
+def get_counter_cfg() -> CounterConfig:
+    """
+    读取计数器配置。
+    配置了 OSS 环境变量则使用 OSS，否则退化为本地模式（无持久化）。
+    """
+    if _oss_available():
+        return CounterConfig(platform='oss')
+    return CounterConfig(platform='local')
+
+
+#  计数器读写（OSS）
+
+def read_bytes(filename: str, cfg: CounterConfig) -> Optional[bytes]:
+    """
+    从 OSS 读取文件内容，返回 bytes。
+    文件不存在返回 None；网络或权限异常向上抛出。
+    """
+    if not cfg.available:
+        return None
+
+    bucket = _get_oss_bucket()
+    key = _oss_key(filename)
+    try:
+        import oss2
+        result = bucket.get_object(key)
+        return result.read()
+    except oss2.exceptions.NoSuchKey:
+        return None
+    except Exception as e:
+        print(f'[PlatformUtils] OSS 读取失败 ({key}): {e}')
+        raise
+
+
+def upload_bytes(
+    content: bytes,
+    filename: str,
+    cfg: CounterConfig,
+    commit_message: str = 'Update',
+    *,
+    retries: int = 3,
+    retry_delay: float = 1.0,
+) -> bool:
+    """
+    将 bytes 写入 OSS 的 filename 路径。
+    返回 True 表示成功，False 表示全部重试均失败。
+    commit_message 参数保留以兼容 counter.py 的调用签名，OSS 不使用。
+    """
+    if not cfg.available:
+        return False
+
+    bucket = _get_oss_bucket()
+    key = _oss_key(filename)
+
+    for attempt in range(retries):
+        try:
+            bucket.put_object(key, content)
+            return True
+        except Exception as e:
+            print(f'[PlatformUtils] OSS 上传失败（第 {attempt + 1} 次）({key}): {e}')
+            if attempt < retries - 1:
+                time.sleep(retry_delay)
+
+    return False
+
+
+#  文件下载（引擎数据文件，与计数器无关）
+
+# 魔搭创空间工作目录，studio repo 的文件会被同步到此处
+_MS_WORKDIR = Path('/home/user/app')
+
+
+def download_file(
+    filename: str,
+    *,
+    # HF 专用参数
+    hf_repo_id:   Optional[str] = None,
+    hf_repo_type: str           = 'space',
+    hf_token:     Optional[str] = None,
+    # MS 专用参数（保留签名兼容性，魔搭平台已不再使用）
+    ms_repo_id:   Optional[str] = None,
+    ms_token:     Optional[str] = None,
+    ms_cache_dir: str           = '/tmp/ms_cache',
+) -> str:
+    """
+    下载单个引擎数据文件，返回本地绝对路径字符串。
+
+    HF 平台：
+        从 Space repo 下载，hf_repo_id 默认读取环境变量 SPACE_ID。
+
+    MS 平台：
+        文件已随 studio repo 部署到容器本地，直接返回工作目录下的路径，
+        无需配置任何额外 repo。若文件不存在则抛出 FileNotFoundError。
+
+    本地：
+        直接返回原始路径。
+    """
+    if PLATFORM == 'hf':
+        from huggingface_hub import hf_hub_download
+        repo_id = hf_repo_id or os.environ.get('SPACE_ID')
+        if not repo_id:
+            raise RuntimeError('[PlatformUtils] HF 平台未找到 SPACE_ID，无法下载文件。')
+        return hf_hub_download(
+            repo_id=repo_id,
+            repo_type=hf_repo_type,
+            filename=filename,
+            token=hf_token or os.environ.get('HF_TOKEN'),
+        )
+
+    if PLATFORM == 'ms':
+        local_path = _MS_WORKDIR / filename
+        if not local_path.is_file():
+            raise FileNotFoundError(
+                f'[PlatformUtils] 魔搭平台本地文件不存在: {local_path}\n'
+                f'请确认已将 {filename} 提交到创空间 studio repo 中。'
+            )
+        print(f'[PlatformUtils] MS 本地文件: {local_path}')
+        return str(local_path)
+
+    # 本地环境：直接返回原始路径（由调用方保证文件存在）
+    return filename
+
+
+#  模型路径解析 
+
+LOCAL_MODEL_PATH = 'my_model_bge_m3'
+HF_MODEL_ID      = 'BAAI/bge-m3'
+MS_MODEL_ID      = 'BAAI/bge-m3'   # 魔搭上同名，走国内节点
+
+
+def resolve_model_path(prefer_local: Optional[str] = None) -> str:
+    """
+    按优先级解析模型路径：
+      1. 本地目录（prefer_local 或 LOCAL_MODEL_PATH）
+      2. 当前平台的 Hub Model ID（首次会自动下载缓存）
+    返回可直接传给 SentenceTransformer 的路径或 model_id 字符串。
+    """
+    local = prefer_local or LOCAL_MODEL_PATH
+    if os.path.exists(local):
+        print(f'[PlatformUtils] 使用本地模型: {local}')
+        return local
+
+    if PLATFORM == 'ms':
+        print(f'[PlatformUtils] 魔搭环境，使用 ModelScope Hub 模型: {MS_MODEL_ID}')
+        try:
+            from modelscope import snapshot_download
+            cached = snapshot_download(MS_MODEL_ID, cache_dir='/tmp/ms_model')
+            print(f'[PlatformUtils] 模型已缓存至: {cached}')
+            return cached
+        except Exception as e:
+            print(f'[PlatformUtils] ModelScope snapshot_download 失败，回退到 HF ID: {e}')
+
+    print(f'[PlatformUtils] 使用 HuggingFace Hub 模型: {HF_MODEL_ID}')
+    return HF_MODEL_ID

requirements.txt

@@ -0,0 +1,13 @@
+nicegui
+pandas
+sentence-transformers
+torch
+jieba
+pyarrow
+safetensors
+huggingface_hub
+fastapi
+uvicorn
+modelscope
+oss2
+mcp==1.27.0

tags_embedding/version_data.json

@@ -0,0 +1,4 @@
+{
+    "schema_version": 3,
+    "updated_at": "2026-05-02 20:19:08"
+}

ui_nicegui.py

@@ -0,0 +1,1381 @@
+"""
+ui_nicegui.py
+─────────────
+NiceGUI 前端层（重构版）。
+
+▸ 只负责渲染 / 交互。
+▸ 调用 core.engine.DanbooruTagger，通过 core.models 的数据结构通信。
+▸ 不包含任何算法逻辑。
+▸ 平台相关配置（host/port/云端判断）统一由 platform_utils 提供。
+"""
+import sys
+sys.stdout.reconfigure(line_buffering=True)
+print("[UI] 脚本开始执行", flush=True)
+import asyncio
+import os
+import json as _json
+import subprocess
+import traceback
+from dataclasses import asdict
+from fastapi.responses import PlainTextResponse
+
+def _excepthook(exc_type, exc_value, exc_tb):
+    print("[UI] FATAL ERROR ON STARTUP:", flush=True)
+    traceback.print_exception(exc_type, exc_value, exc_tb)
+    sys.__excepthook__(exc_type, exc_value, exc_tb)
+
+sys.excepthook = _excepthook
+
+from nicegui import ui, app, run
+from core import counter
+from api_fastapi import app as api_app
+from core.engine import DanbooruTagger
+from core.models import RelatedTag, SearchRequest
+from platform_utils import is_cloud, get_host_port, nsfw_allowed
+from mcp_server import mcp
+
+import logging
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("huggingface_hub").setLevel(logging.WARNING)
+logging.getLogger("mcp").setLevel(logging.WARNING)
+logging.getLogger("mcp.server").setLevel(logging.WARNING)
+logging.getLogger("fastmcp").setLevel(logging.WARNING)
+# suppress MCP streamable-HTTP transport noise ("No response returned" from Starlette middleware)
+class _SuppressMCPNoise(logging.Filter):
+    _MARKER = "No response returned"
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if self._MARKER in record.getMessage():
+            return False
+        if record.exc_info:
+            import traceback
+            tb_text = "".join(traceback.format_exception(*record.exc_info))
+            if self._MARKER in tb_text:
+                return False
+        return True
+
+logging.getLogger("uvicorn.error").addFilter(_SuppressMCPNoise())
+
+# ── 表格列定义 ─────────────────────────────────────────────────────────────────
+
+TABLE_COLUMNS = [
+    {'name': 'tag',         'label': '匹配标签', 'field': 'tag',         'align': 'left', 'sortable': True},
+    {'name': 'cn_name',     'label': '含义',     'field': 'cn_name',     'align': 'left'},
+    {'name': 'nsfw',        'label': '分级',     'field': 'nsfw',        'align': 'center', 'sortable': True},
+    {'name': 'final_score', 'label': '综合分',   'field': 'final_score', 'sortable': True},
+    {'name': 'count',       'label': '热度',     'field': 'count',       'sortable': True},
+]
+
+OPTIONAL_COLS = {
+    'semantic': {'name': 'semantic_score', 'label': '语义分',   'field': 'semantic_score', 'sortable': True},
+    'layer':    {'name': 'layer',          'label': '匹配层',   'field': 'layer'},
+    'source':   {'name': 'source',         'label': '匹配来源', 'field': 'source'},
+}
+
+# localStorage key 与配置版本，版本变更时自动丢弃旧配置
+_CONFIG_LS_KEY = 'danbooru_search_config'
+_CONFIG_VERSION = 4
+
+
+
+# ── 辅助函数 ───────────────────────────────────────────────────────────────────
+
+def _get_git_commit() -> str:
+    try:
+        return subprocess.check_output(
+            ['git', 'rev-parse', '--short', 'HEAD'],
+            stderr=subprocess.DEVNULL,
+            text=True,
+        ).strip()
+    except Exception:
+        return os.environ.get('COMMIT_SHA', 'unknown')[:7]
+
+
+def result_to_row(r, nsfw_visible: bool) -> dict:
+    d = asdict(r)
+    d['_nsfw_blocked'] = (r.nsfw == '1') and not nsfw_visible
+    return d
+
+
+def apply_nsfw_filter(rows: list[dict], show_nsfw: bool) -> list[dict]:
+    result = []
+    for row in rows:
+        r = dict(row)
+        r['_nsfw_blocked'] = (r.get('nsfw') == '1') and not show_nsfw
+        result.append(r)
+    return result
+
+
+def _format_tag_with_weight(tag: str, weight: float, fmt: str = 'sdxl') -> str:
+    """格式化单个标签。
+    sdxl: (tag:1.2)  权重 1.0 时输出 tag
+    nai:  1.2::tag:: 权重 1.0 时输出 tag
+    """
+    if weight == 1.0:
+        return tag
+    if fmt == 'nai':
+        return f'{weight:.1f}::{tag}::'
+    return f'({tag}:{weight:.1f})'
+
+
+# ── UI 类 ─────────────────────────────────────────────────────────────────────
+
+class DanbooruSearchUI:
+    def __init__(self):
+        self.search_count_label = None
+        self.current_search_interacted = True
+
+        self.full_table_data: list[dict] = []
+        self.current_segments: list[str] = []   # 从句级原始片段，用于区分 chip 颜色
+        self.current_query_str: str = ""
+        self.full_tags_str: str = ""
+        self.full_tags_str_sfw: str = ""
+
+        self.result_table = None           # 左栏表格
+        self.related_list_container = None  # 右栏关联推荐列表
+        self.results_section = None        # 整个结果区域（搜索前隐藏）
+        self.selection_count_label = None
+        self.selected_display = None       # 已废弃 textarea，保留兼容
+        self.selected_chips_container = None  # 已选标签 chip 容器
+        self.current_related: list = []
+        self.chip_extra_selected: set = set()
+
+        # tag -> prompt 权重，范围 [0.1, 1.9]，默认 1.0
+        self.tag_weights: dict[str, float] = {}
+        # 复制格式：'sdxl' 或 'nai'
+        self.prompt_format: str = 'sdxl'
+        self.format_toggle_btn = None
+
+        self.init_banner = None
+        self.input_top_k = None
+        self.input_limit = None
+        self.input_weight = None
+        self.input_nsfw = None
+        self.input_segment = None
+        self.search_input = None
+        self.keywords_container = None
+        self.spinner = None
+        self.search_btn = None
+
+        self.selected_layers = {'英文': True, '中文扩展词': True, '释义': True, '中文核心词': True}
+        self.selected_cats = {'General': True, 'Copyright': True, 'Character': True}
+
+        self.bad_case_btn = None
+
+        self.mcp_notice = None
+        self.notice_expansion = None
+
+        # 表格显示选项开关
+        self.sw_semantic = None
+        self.sw_layer = None
+        self.sw_source = None
+
+        # 关联推荐的 checkbox 引用
+        self._related_checkboxes: dict[str, ui.checkbox] = {}
+
+        # 高级选项中各层/类型的 checkbox 引用，用于 restore 时同步控件状态
+        self._layer_checkboxes: dict[str, ui.checkbox] = {}
+        self._cat_checkboxes: dict[str, ui.checkbox] = {}
+
+    def _update_footer_text(self):
+        if self.search_count_label is not None:
+            try:
+                total = counter.get()
+                visits = counter.get_visits()
+                commit = _get_git_commit()
+                self.search_count_label.content = (
+                    f'累计搜索 {total:,} 次 | 累计访问 {visits:,} 次 | '
+                    f'<span class="font-mono text-gray-300">版本号: {commit}</span>'
+                    f'<br>'
+                    f'<a href="/api/docs" '
+                    f'target="_blank" rel="noopener noreferrer" '
+                    f'class="text-blue-400 hover:text-blue-600 hover:underline">使用 API 服务</a>'
+                    f' | <a href="https://github.com/SuzumiyaAkizuki/DanbooruSearchOnline#mcp-接口" '
+                    f'target="_blank" rel="noopener noreferrer" '
+                    f'class="text-blue-400 hover:text-blue-600 hover:underline">使用 MCP 服务</a>'
+                )
+            except AttributeError:
+                pass
+
+    def _mark_interaction(self, e=None):
+        if not self.current_search_interacted:
+            self.current_search_interacted = True
+
+            async def silent_success_update():
+                try:
+                    await counter.increment_success()
+                except Exception:
+                    pass
+            asyncio.create_task(silent_success_update())
+
+    # ── 分页辅助 ──────────────────────────────────────────────────────────
+
+    def _get_rows_per_page(self) -> int:
+        if self.result_table is None:
+            return 0
+        p = self.result_table.pagination
+        # pagination 可能是 int 或 dict
+        if isinstance(p, dict):
+            return int(p.get('rowsPerPage', 0))
+        return int(p) if p else 0
+
+    def _set_rows_per_page(self, value: int):
+        if self.result_table is None:
+            return
+        allowed = {5, 7, 10, 15, 20, 25, 50, 0}  # 0 = All
+        value = value if value in allowed else 0
+        p = self.result_table.pagination
+        if isinstance(p, dict):
+            p['rowsPerPage'] = value
+            self.result_table.pagination = p
+        else:
+            self.result_table.pagination = value
+
+    # ── 配置持久化 ────────────────────────────────────────────────────────
+
+    def _save_config(self):
+        """将当前控件状态序列化并写入 localStorage。"""
+        cfg = {
+            'version': _CONFIG_VERSION,
+            'top_k': int(self.input_top_k.value) if self.input_top_k else 10,
+            'limit': int(self.input_limit.value) if self.input_limit else 80,
+            'popularity_weight': float(self.input_weight.value) if self.input_weight else 0.15,
+            'show_nsfw': bool(self.input_nsfw.value) if self.input_nsfw else False,
+            'use_segmentation': bool(self.input_segment.value) if self.input_segment else True,
+            'selected_layers': dict(self.selected_layers),
+            'selected_cats': dict(self.selected_cats),
+            'sw_semantic': bool(self.sw_semantic.value) if self.sw_semantic else False,
+            'sw_layer': bool(self.sw_layer.value) if self.sw_layer else False,
+            'sw_source': bool(self.sw_source.value) if self.sw_source else False,
+            'prompt_format': self.prompt_format,
+            'rows_per_page': self._get_rows_per_page(),
+            'search_query': self.search_input.value if self.search_input else '',
+            'notice_expanded': bool(self.notice_expansion.value) if self.notice_expansion else True,
+            'mcp_notice_dismissed': not bool(self.mcp_notice.visible) if self.mcp_notice else False,
+        }
+        js = _json.dumps(cfg, ensure_ascii=False)
+        ui.run_javascript(f"localStorage.setItem('{_CONFIG_LS_KEY}', {_json.dumps(js)});")
+
+    async def _restore_config(self):
+        """从 localStorage 读取配置并恢复控件状态。"""
+        try:
+            raw = await ui.run_javascript(
+                f"localStorage.getItem('{_CONFIG_LS_KEY}');",
+                timeout=5.0,
+            )
+        except Exception:
+            return
+
+        if not raw:
+            return
+
+        try:
+            cfg = _json.loads(raw)
+        except Exception:
+            return
+
+        if cfg.get('version') != _CONFIG_VERSION:
+            # 版本不符，丢弃旧配置
+            ui.run_javascript(f"localStorage.removeItem('{_CONFIG_LS_KEY}');")
+            return
+
+        if self.input_top_k and 'top_k' in cfg:
+            self.input_top_k.set_value(cfg['top_k'])
+        if self.input_limit and 'limit' in cfg:
+            self.input_limit.set_value(cfg['limit'])
+        if self.input_weight and 'popularity_weight' in cfg:
+            self.input_weight.set_value(cfg['popularity_weight'])
+        if self.input_segment and 'use_segmentation' in cfg:
+            self.input_segment.set_value(cfg['use_segmentation'])
+
+        # NSFW：仅在平台允许时恢复
+        if nsfw_allowed() and self.input_nsfw and 'show_nsfw' in cfg:
+            self.input_nsfw.set_value(cfg['show_nsfw'])
+
+        if 'selected_layers' in cfg:
+            for layer, val in cfg['selected_layers'].items():
+                if layer in self.selected_layers:
+                    self.selected_layers[layer] = bool(val)
+                    if layer in self._layer_checkboxes:
+                        self._layer_checkboxes[layer].set_value(bool(val))
+
+        if 'selected_cats' in cfg:
+            for cat, val in cfg['selected_cats'].items():
+                if cat in self.selected_cats:
+                    self.selected_cats[cat] = bool(val)
+                    if cat in self._cat_checkboxes:
+                        self._cat_checkboxes[cat].set_value(bool(val))
+
+        if self.sw_semantic and 'sw_semantic' in cfg:
+            self.sw_semantic.set_value(cfg['sw_semantic'])
+        if self.sw_layer and 'sw_layer' in cfg:
+            self.sw_layer.set_value(cfg['sw_layer'])
+        if self.sw_source and 'sw_source' in cfg:
+            self.sw_source.set_value(cfg['sw_source'])
+
+        if 'prompt_format' in cfg and cfg['prompt_format'] in ('sdxl', 'nai'):
+            self.prompt_format = cfg['prompt_format']
+            if self.format_toggle_btn:
+                if self.prompt_format == 'nai':
+                    self.format_toggle_btn.text = 'NAI'
+                    self.format_toggle_btn.props('color=purple-7')
+                else:
+                    self.format_toggle_btn.text = 'SDXL'
+                    self.format_toggle_btn.props('color=grey-7')
+
+        if 'rows_per_page' in cfg:
+            self._set_rows_per_page(cfg['rows_per_page'])
+
+        if self.search_input and cfg.get('search_query'):
+            self.search_input.set_value(cfg['search_query'])
+
+        if self.notice_expansion and 'notice_expanded' in cfg:
+            self.notice_expansion.set_value(cfg['notice_expanded'])
+
+        if self.mcp_notice and cfg.get('mcp_notice_dismissed'):
+            self.mcp_notice.set_visibility(False)
+
+        # 若高级选项列有变更，同步更新表格列
+        self._update_table_columns()
+
+    # ══════════════════════════════════════════════════════════════════════
+    # 页面构建
+    # ══════════════════════════════════════════════════════════════════════
+
+    def build_page(self):
+        ui.colors(primary='#4A90E2', secondary='#5E6C84', accent='#FF6B6B')
+        ui.add_head_html('''
+            <meta name="description" content="基于语义匹配的 Danbooru 标签搜索引擎，支持中英双语描述、多维匹配、智能分词与共现关联推荐。">
+            <meta name="keywords" content="Danbooru, AI绘画, Stable Diffusion, 提示词, 标签搜索, RAG, Prompt, NovelAI">
+            <meta name="google-site-verification" content="cx4sl9Mb172GUFL556JFwKCP-pT3naQcmlMriy5B8ls" />
+
+            <style>
+                .nsfw-blur-cell      { filter: blur(8px); opacity: 0.5; transition: all 0.3s ease;
+                                       pointer-events: none !important; user-select: none !important; }
+                .nsfw-checkbox-disabled { pointer-events: none !important; opacity: 0.3 !important; }
+                .nsfw-row-blocked    { cursor: not-allowed !important; }
+                .related-item { transition: background-color 0.15s ease; }
+                .related-item:hover { background-color: rgba(74, 144, 226, 0.04); }
+                .tag-link { text-decoration: none; font-family: 'Consolas', 'Monaco', 'Courier New', monospace; }
+                .tag-link:hover { text-decoration: underline; }
+                .weight-chip { display: inline-flex; align-items: center; gap: 2px;
+                               border-radius: 16px; padding: 2px 6px 2px 4px;
+                               background: #e3edf7; border: 1px solid #b3cde8;
+                               font-size: 12px; margin: 3px; white-space: nowrap; }
+                .weight-chip.boosted  { background: #fff3e0; border-color: #ffb74d; }
+                .weight-chip.reduced  { background: #f3e5f5; border-color: #ce93d8; }
+                .weight-btn { cursor: pointer; width: 18px; height: 18px; border-radius: 50%;
+                              display: inline-flex; align-items: center; justify-content: center;
+                              font-size: 13px; font-weight: bold; line-height: 1;
+                              border: none; background: rgba(0,0,0,0.08);
+                              color: #555; transition: background 0.15s; padding: 0; }
+                .weight-btn:hover { background: rgba(0,0,0,0.18); }
+                .weight-label { font-family: Consolas, Monaco, monospace; font-size: 11px;
+                                color: #888; min-width: 28px; text-align: center; }
+
+                /* 强制双栏并排 */
+                .two-col-layout {
+                    display: flex !important;
+                    flex-wrap: nowrap !important;
+                    align-items: flex-start !important;
+                    gap: 16px !important;
+                }
+                .two-col-layout > .col-left {
+                    flex: 0 0 62% !important;
+                    min-width: 0 !important;
+                    max-width: 62% !important;
+                    overflow: hidden;
+                }
+                .two-col-layout > .col-right {
+                    flex: 0 0 36% !important;
+                    min-width: 0 !important;
+                    max-width: 36% !important;
+                    overflow: hidden;
+                }
+
+                /* 窄屏回退为上下排列 */
+                @media (max-width: 900px) {
+                    .two-col-layout {
+                        flex-wrap: wrap !important;
+                    }
+                    .two-col-layout > .col-left,
+                    .two-col-layout > .col-right {
+                        flex: 1 1 100% !important;
+                        max-width: 100% !important;
+                    }
+                }
+            </style>
+            <script async src="https://www.googletagmanager.com/gtag/js?id=G-QPB7EEPR5G"></script>
+            <script>
+                window.dataLayer = window.dataLayer || [];
+                function gtag(){dataLayer.push(arguments);}
+                gtag('js', new Date());
+                gtag('config', 'G-QPB7EEPR5G');
+            </script>
+            <script>
+                document.addEventListener('DOMContentLoaded', function() {
+                    function openExternal(root) {
+                        root.querySelectorAll('a[href^="http"]').forEach(function(a) {
+                            a.setAttribute('target', '_blank');
+                            a.setAttribute('rel', 'noopener noreferrer');
+                        });
+                    }
+                    openExternal(document);
+                    new MutationObserver(function(mutations) {
+                        mutations.forEach(function(m) {
+                            m.addedNodes.forEach(function(node) {
+                                if (node.querySelectorAll) openExternal(node);
+                            });
+                        });
+                    }).observe(document.body, { childList: true, subtree: true });
+                });
+            </script>
+        ''')
+
+        with ui.column().classes('w-full max-w-7xl mx-auto p-4 gap-4'):
+
+            # ── 初始化提示 ──
+            self.init_banner = ui.card().classes(
+                'w-full bg-blue-50 border-l-4 border-blue-400'
+            )
+            with self.init_banner:
+                with ui.row().classes('items-center gap-3 p-2'):
+                    ui.spinner(size='sm')
+                    ui.label('引擎初始化中，请稍候…首次加载约需 15 秒').classes('text-sm text-blue-700')
+            self.init_banner.set_visibility(not DanbooruTagger.is_ready())
+            if not DanbooruTagger.is_ready():
+                asyncio.ensure_future(self._hide_banner_when_ready())
+
+            # ── 1. MCP 上线通知 ──
+            self._build_mcp_notice()
+
+            # ── 2. 注意事项 ──
+            self._build_notice()
+
+            # ── 2. 搜索卡片 ──
+            self._build_search_card()
+
+            # ── 3~5. 结果区域（搜索前隐藏）──
+            self.results_section = ui.column().classes('w-full gap-4')
+            self.results_section.set_visibility(False)
+
+            with self.results_section:
+                # ── 3. 已选标签栏 ──
+                self._build_selection_bar()
+
+                # ── 4. 分词筛选 chips ──
+                self.keywords_container = ui.row().classes('gap-2 items-center flex-wrap')
+
+                # ── 5. 两栏结果 ──
+                self._build_results_columns()
+
+            # ── 6. 底部 ──
+            with ui.element('div').classes('w-full text-center py-4 mt-2'):
+                self.search_count_label = ui.html('正在加载数据...').classes('text-xs text-gray-400')
+                self._update_footer_text()
+
+    # ── MCP 上线通知 ──────────────────────────────────────────────────────
+
+    def _build_mcp_notice(self):
+        self.mcp_notice = ui.card().classes(
+            'w-full bg-green-50 border-l-4 border-green-500 p-0 overflow-hidden'
+        )
+        with self.mcp_notice:
+            with ui.column().classes('px-4 py-3 w-full gap-1'):
+                with ui.row().classes('items-center justify-between w-full'):
+                    ui.label('🎉 MCP 服务正式上线！').classes('text-base font-bold text-green-800')
+                    ui.button(icon='close').props('flat dense round color=grey-6') \
+                        .on_click(self._dismiss_mcp_notice)
+                ui.html(
+                    '本站现已支持通过 MCP 协议接入 AI Agent（如 Claude Desktop）。'
+                    '如需体验<b>托管版</b>（免配置、开箱即用），请访问 '
+                    '<a href="https://huggingface.co/spaces/SAkizuki/WenQiuYue" '
+                    'target="_blank" rel="noopener noreferrer" '
+                    'class="text-green-700 font-bold underline">问秋月 Space</a>，'
+                    '进入后点击「搜标签」即可调用。'
+                    '<span class="text-gray-500 ml-1">'
+                    'API 额度有限（约 30 元），用完即止，仅供体验。'
+                    '</span>'
+                    '&nbsp;&nbsp;'
+                    '<a href="https://github.com/SuzumiyaAkizuki/DanbooruSearchOnline#mcp-接口" '
+                    'target="_blank" rel="noopener noreferrer" '
+                    'class="text-green-700 underline">查看接入文档 →</a>'
+                ).classes('text-sm text-green-900')
+
+    def _dismiss_mcp_notice(self):
+        if self.mcp_notice:
+            self.mcp_notice.set_visibility(False)
+        self._save_config()
+
+    # ── 注意事项 ──────────────────────────────────────────────────────────
+
+    def _build_notice(self):
+        with ui.card().classes('w-full bg-orange-50 border-l-4 border-orange-500 p-0 overflow-hidden'):
+            with ui.expansion(value=True).classes('w-full') as notice_expansion:
+                self.notice_expansion = notice_expansion
+                notice_expansion.on('update:model-value', lambda _: self._save_config())
+                notice_expansion.add_slot('header', '''
+                    <div class="flex items-center gap-2 px-4 py-2 w-full flex-wrap">
+                        <span class="text-base font-bold text-orange-800">⚠️ 注意事项 / Note</span>
+                        <span v-if="!props.expanded" class="text-sm text-gray-600 ml-1">
+                             如果觉得好用，请点击顶部给本 Space 点个
+                            <strong>Like ❤️</strong>，或前往 GitHub 点个 <strong>Star ⭐</strong>！
+                        </span>
+                    </div>
+                ''')
+                ui.markdown("""
+- **AI 辅助**：基于语义匹配，结果未必绝对准确(Results may contain errors)
+- **内容警告**：查找结果可能包含 NSFW 内容 (May include NSFW content)
+- **检索限制**：仅支持中/英双语查找 ，更推荐中文(CN/EN only,CN is preferred)
+- **标签范围**：仅显示特征、角色与作品标签，且频数须 ≥ 100 (General, Character & Copyright only, Freq ≥ 100)
+- **集成与接口**���[ComfyUI 插件](https://github.com/SuzumiyaAkizuki/ComfyUI-DanbooruSearcher) · [API 文档](/api/docs) · [MCP 接入](https://github.com/SuzumiyaAkizuki/DanbooruSearchOnline#mcp-接口)
+- **支持作者**：如果觉得好用，欢迎点击顶部给本 Space 点个 **Like ❤️**，或前往 [GitHub](https://github.com/SuzumiyaAkizuki/DanbooruSearchOnline) 点个 **Star ⭐**！
+- **🚀 首次使用？[点击查看使用指南](https://github.com/SuzumiyaAkizuki/DanbooruSearchOnline)**，了解五种搜索模式与进阶技巧
+""").classes('text-sm text-gray-800 px-4 pb-3')
+
+    # ── 搜索卡片 ─────────────────────────────────────────────────────────
+
+    def _build_search_card(self):
+        with ui.card().classes('w-full'):
+            with ui.row().classes('items-center gap-2 mb-2'):
+                ui.icon('search', size='2em', color='primary')
+                ui.label('Danbooru 标签模糊搜索').classes('text-2xl font-bold text-gray-800')
+            ui.label('基于语义匹配的标签搜索引擎，支持多维匹配与共现关联推荐。').classes(
+                'text-sm text-gray-500 -mt-1 mb-3'
+            )
+
+            with ui.row().classes('w-full gap-3 items-stretch'):
+                self.search_input = ui.textarea(
+                    placeholder='输入自然语言描述或模糊概念，例如：一个穿着白色水手服的少女在雨中奔跑...'
+                ).classes('flex-grow text-base').props('outlined rows=2')
+                self.search_input.on('keydown.ctrl.enter', self.perform_search)
+
+                with ui.column().classes('justify-center'):
+                    self.search_btn = ui.button(
+                        '', on_click=self.perform_search, icon='search'
+                    ).classes('px-6 h-full min-h-16').props('unelevated color=dark')
+                    with self.search_btn:
+                        ui.label('搜索').classes('text-sm mt-1')
+                    self.spinner = ui.spinner(size='2em').classes('hidden')
+
+            with ui.row().classes('w-full gap-6 items-center mt-3 flex-wrap'):
+                with ui.row().classes('items-center gap-2'):
+                    ui.label('Top K (语义相关)').classes('text-sm text-gray-600')
+                    self.input_top_k = ui.number(value=10, min=1, max=200).classes('w-20') \
+                        .props('outlined dense')
+
+                with ui.row().classes('items-center gap-2'):
+                    ui.label('结果上限').classes('text-sm text-gray-600')
+                    self.input_limit = ui.number(value=80, min=10, max=500).classes('w-20') \
+                        .props('outlined dense')
+
+                with ui.row().classes('items-center gap-2'):
+                    ui.label('热度权重').classes('text-sm text-gray-600')
+                    self.input_weight = ui.slider(min=0.0, max=1.0, value=0.15, step=0.05).classes('w-32')
+                    ui.label().bind_text_from(self.input_weight, 'value', lambda v: f"{v:.2f}") \
+                        .classes('text-sm font-mono text-gray-700 w-8')
+
+                with ui.switch('显示 NSFW(成人) 内容', value=False).props('color=red') as _nsfw_sw:
+                    if not nsfw_allowed():
+                        with ui.tooltip().props('content-class="bg-black text-white shadow-4"'):
+                            ui.label('NSFW 内容在当前平台不可用').style('font-size:14px;')
+                self.input_nsfw = _nsfw_sw
+                if not nsfw_allowed():
+                    self.input_nsfw.disable()
+                else:
+                    self.input_nsfw.on('update:model-value', self.on_nsfw_toggle)
+
+                with ui.switch('智能分词', value=True).props('color=primary') as _seg_sw:
+                    with ui.tooltip().props('content-class="bg-black text-white shadow-4"'):
+                        ui.label('关闭后系统将只匹配完整句子，适用于精准搜索整句。').style('font-size:14px;')
+                self.input_segment = _seg_sw
+
+            with ui.expansion('高级选项', icon='tune').classes('w-full mt-2'):
+                with ui.column().classes('w-full p-3 gap-4'):
+                    with ui.row().classes('w-full gap-8 flex-wrap'):
+                        with ui.column().classes('gap-2'):
+                            ui.label('匹配层筛选').classes('font-bold text-sm text-gray-700')
+                            display_map = {
+                                '英文': '英文标签', '中文扩展词': '中文扩展词',
+                                '释义': '维基释义', '中文核心词': '中文核心词',
+                            }
+                            for layer in ['英文', '中文扩展词', '释义', '中文核心词']:
+                                cb = ui.checkbox(
+                                    display_map.get(layer, layer), value=True,
+                                    on_change=lambda e, l=layer: self.selected_layers.__setitem__(l, e.value)
+                                ).props('color=primary dense')
+                                self._layer_checkboxes[layer] = cb
+
+                        with ui.column().classes('gap-2'):
+                            ui.label('类型筛选').classes('font-bold text-sm text-gray-700')
+                            color_map = {'General': 'blue', 'Copyright': 'pink', 'Character': 'green'}
+                            label_map = {
+                                'General': '通用 (General)',
+                                'Copyright': '作品 (Copyright)',
+                                'Character': '角色 (Character)',
+                            }
+                            for cat in ['General', 'Copyright', 'Character']:
+                                cb = ui.checkbox(
+                                    label_map[cat], value=True,
+                                    on_change=lambda e, c=cat: self.selected_cats.__setitem__(c, e.value)
+                                ).props(f'color={color_map[cat]} dense')
+                                self._cat_checkboxes[cat] = cb
+
+                        with ui.column().classes('gap-2'):
+                            ui.label('表格显示列').classes('font-bold text-sm text-gray-700')
+                            self.sw_semantic = ui.switch('显示语义分', value=False)
+                            self.sw_layer    = ui.switch('显示匹配层', value=False)
+                            self.sw_source   = ui.switch('显示匹配来源', value=False)
+                            self.sw_semantic.on('update:model-value', self._update_table_columns)
+                            self.sw_layer.on('update:model-value', self._update_table_columns)
+                            self.sw_source.on('update:model-value', self._update_table_columns)
+
+    # ── 已选标签栏 ────────────────────────────────────────────────────────
+
+    def _build_selection_bar(self):
+        with ui.card().classes('w-full bg-blue-50 border border-blue-200'):
+            with ui.row().classes('w-full items-center justify-between'):
+                with ui.row().classes('items-center gap-2'):
+                    ui.icon('check_circle', color='primary')
+                    ui.label('已选标签').classes('font-bold text-primary')
+                    self.selection_count_label = ui.label('0').classes(
+                        'bg-primary text-white px-2 rounded-full text-sm')
+                    with ui.icon('info_outline', size='sm', color='grey').classes('cursor-help'):
+                        with ui.tooltip().props('content-class="bg-black text-white shadow-4"'):
+                            ui.html(
+                                '点击 <b>−</b> / <b>+</b> 可调整标签权重（步长 0.1，范围 0.1~1.9）。<br>'
+                                '权重 1.0 时输出原始标签；其余输出 <code>(tag:1.2)</code> 格式。'
+                            ).style('font-size:14px;line-height:1.6;')
+
+                with ui.row().classes('items-center gap-2'):
+                    with ui.button('没搜到？', icon='help_outline').props('dense flat color=grey-6').classes('text-sm') as _bad_btn:
+                        with ui.tooltip().props('content-class="bg-black text-white shadow-4"'):
+                            ui.html('点击此处以反馈失败案例。<br>您的搜索词将被匿名收集用于优化引擎（不包含个人隐私）。').style('font-size:14px;line-height:1.5;')
+                    self.bad_case_btn = _bad_btn
+                    self.bad_case_btn.disable()
+                    self.bad_case_btn.on_click(self.report_bad_case)
+                    self.format_toggle_btn = ui.button(
+                        'SDXL', icon='swap_horiz'
+                    ).props('dense flat color=grey-7').classes('text-xs font-mono')
+                    with self.format_toggle_btn:
+                        with ui.tooltip().props('content-class="bg-black text-white shadow-4"'):
+                            ui.html(
+                                '切换复制格式：<br>'
+                                '<b>SDXL</b>：<code>(tag:1.2)</code><br>'
+                                '<b>NAI</b>：<code>1.2::tag::</code>'
+                            ).style('font-size:13px;line-height:1.7;')
+                    self.format_toggle_btn.on_click(self._toggle_prompt_format)
+                    copy_btn = ui.button('复制选中', icon='content_copy').props('dense unelevated color=primary')
+                    copy_btn.on_click(self.copy_selection)
+
+            # chip 容器：每个已选标签渲染为一个带加减按钮的 chip
+            self.selected_chips_container = ui.element('div').classes(
+                'w-full mt-2 min-h-10 p-1 rounded bg-white border border-blue-100 flex flex-wrap'
+            )
+
+    def _render_selected_chips(self):
+        """重新渲染已选标签的 chip 列表。"""
+        if self.selected_chips_container is None:
+            return
+        self.selected_chips_container.clear()
+        tags = self._get_selected_tags()
+        if not tags:
+            with self.selected_chips_container:
+                ui.label('暂无已选标签').classes('text-xs text-gray-400 italic p-2 self-center')
+            return
+        with self.selected_chips_container:
+            for tag in tags:
+                w = self.tag_weights.get(tag, 1.0)
+                extra_cls = 'boosted' if w > 1.0 else ('reduced' if w < 1.0 else '')
+                w_str = f'{w:.1f}'
+                with ui.element('div').classes(f'weight-chip {extra_cls}'):
+                    # 删除按钮（×）
+                    with ui.element('button').classes('weight-btn').props(f'title="移除 {tag}"').on(
+                        'click', lambda t=tag: self._remove_selected_tag(t)
+                    ):
+                        ui.html('&times;')
+                    # 减号
+                    with ui.element('button').classes('weight-btn').on(
+                        'click', lambda t=tag: self._adjust_weight(t, -0.1)
+                    ):
+                        ui.html('&minus;')
+                    # 标签名
+                    ui.label(tag).style(
+                        'font-family:Consolas,Monaco,monospace;font-size:12px;'
+                        'color:#2c5282;max-width:150px;overflow:hidden;'
+                        'text-overflow:ellipsis;white-space:nowrap;'
+                    )
+                    # 权重值（仅非 1.0 时显示）
+                    if w != 1.0:
+                        ui.label(w_str).classes('weight-label').style('color:#e65100;font-weight:bold;')
+                    # 加号
+                    with ui.element('button').classes('weight-btn').on(
+                        'click', lambda t=tag: self._adjust_weight(t, +0.1)
+                    ):
+                        ui.html('&plus;')
+
+    def _adjust_weight(self, tag: str, delta: float):
+        """调整单个标签权重，钳位到 [0.1, 1.9]。"""
+        current = self.tag_weights.get(tag, 1.0)
+        new_w = round(current + delta, 1)
+        if new_w < 0.1:
+            ui.notify('权重范围为 0.1 ~ 1.9，已到达最小值', type='warning', timeout=2000)
+            return
+        if new_w > 1.9:
+            ui.notify('权重范围为 0.1 ~ 1.9，已到达最大值', type='warning', timeout=2000)
+            return
+        self.tag_weights[tag] = new_w
+        self._render_selected_chips()
+
+    def _remove_selected_tag(self, tag: str):
+        """从已选中移除标签（同步表格选中状态）。"""
+        self._mark_interaction()
+        current = self._get_selected_tags()
+        if tag in current:
+            current.remove(tag)
+        self.tag_weights.pop(tag, None)
+        self._set_selected_tags(current)
+
+        # ── 两栏结果（CSS 强制并排）──────────────────────────────────────────
+
+    def _build_results_columns(self):
+        with ui.element('div').classes('w-full two-col-layout'):
+            # ── 左栏：语义匹配结果（表格）──
+            with ui.card().classes('col-left'):
+                with ui.row().classes('items-center justify-between mb-2 w-full'):
+                    ui.label('匹配标签结果').classes('font-bold text-lg text-gray-800')
+                    ui.button('复制全部标签', icon='content_copy', on_click=self._copy_all_tags) \
+                        .props('dense flat color=primary').classes('text-sm')
+
+                self.result_table = ui.table(
+                    columns=TABLE_COLUMNS,
+                    rows=[],
+                    pagination=0,
+                    selection='multiple',
+                    row_key='tag',
+                ).classes('w-full')
+                self.result_table.on('selection', self._update_selection_display)
+                self.result_table.on('link_click', self._mark_interaction)
+                self.result_table.on('pagination', lambda _: self._save_config())
+
+                # 自定义行模板：行背景色按分类，整行悬浮显示 wiki（NSFW模糊行除外）
+                self.result_table.add_slot('body', r'''
+                    <q-tr :props="props"
+                          :class="props.row._nsfw_blocked ? 'nsfw-row-blocked' : ''"
+                          :style="{
+                              'background-color':
+                                  props.row.category === 'General'   ? 'rgba(59,130,246,0.06)' :
+                                  props.row.category === 'Character' ? 'rgba(34,197,94,0.06)'  :
+                                  props.row.category === 'Copyright' ? 'rgba(236,72,153,0.06)' : ''
+                          }">
+                        <q-td auto-width>
+                            <q-checkbox v-model="props.selected"
+                                :class="props.row._nsfw_blocked ? 'nsfw-checkbox-disabled' : ''"/>
+                        </q-td>
+                        <q-td v-for="col in props.cols" :key="col.name" :props="props">
+                            <template v-if="col.name === 'tag' || col.name === 'cn_name'">
+                                <div :class="props.row._nsfw_blocked ? 'nsfw-blur-cell' : ''">
+                                    <template v-if="col.name === 'cn_name' && col.value">
+                                        <span style="font-size:14px">
+                                            {{ col.value.split(',')[0] }}
+                                        </span>
+                                    </template>
+                                    <template v-else-if="col.name === 'tag'">
+                                        <a :href="'https://danbooru.donmai.us/wiki_pages/'+col.value"
+                                           target="_blank"
+                                           class="text-primary hover:underline font-bold inline-flex items-center"
+                                           style="text-decoration:none; font-family: Consolas, Monaco, Courier New, monospace;"
+                                           @click.stop="$emit('link_click', col.value)">
+                                            {{ col.value }}
+                                            <q-icon name="open_in_new" size="xs" class="q-ml-xs opacity-50"/>
+                                        </a>
+                                    </template>
+                                    <template v-else>{{ col.value }}</template>
+                                </div>
+                            </template>
+                            <template v-else-if="col.name === 'nsfw'">
+                                <div v-if="col.value === '1'" class="text-red-500">🔴</div>
+                                <div v-else class="text-green-500">🟢</div>
+                            </template>
+                            <template v-else-if="col.name === 'final_score'">
+                                <q-badge :color="col.value > 0.6 ? 'green' : (col.value > 0.5 ? 'teal' : 'orange')">
+                                    {{ col.value }}
+                                </q-badge>
+                            </template>
+                            <template v-else>{{ col.value }}</template>
+                        </q-td>
+                        <q-tooltip v-if="props.row.wiki && !props.row._nsfw_blocked"
+                            content-class="bg-black text-white shadow-4"
+                            max-width="500px" :offset="[10,10]">
+                            <div style="font-size:14px;line-height:1.5;">
+                                <span style="opacity:0.7;margin-right:4px;">{{
+                                    props.row.category === 'General'   ? '[通用]' :
+                                    props.row.category === 'Character' ? '[角色]' :
+                                    props.row.category === 'Copyright' ? '[作品]' : ''
+                                }}</span>{{ props.row.wiki }}
+                            </div>
+                        </q-tooltip>
+                    </q-tr>
+                ''')
+
+            # ── 右栏：关联推荐 ──
+            with ui.card().classes('col-right'):
+                with ui.row().classes('items-center justify-between w-full mb-2'):
+                    with ui.row().classes('items-center gap-2'):
+                        ui.label('关联推荐').classes('font-bold text-lg text-gray-800')
+                        with ui.icon('info_outline', size='sm', color='grey').classes('cursor-help'):
+                            with ui.tooltip().props('content-class="bg-black text-white shadow-4"'):
+                                ui.html(
+                                    '基于标签共现数据，发掘语义之外的相关性，为您推荐更多可能的标签。<br>勾选可加入或移出已选。如需根据最新选项更新推荐，请点击刷新按钮。').style(
+                                    'font-size:14px;line-height:1.5;')
+
+                    # 新增手动刷新按钮
+                    ui.button('根据已选刷新', icon='refresh', on_click=self._manual_refresh_related) \
+                        .props('dense flat color=primary').classes('text-sm')
+
+                self.related_list_container = ui.column().classes('w-full gap-0')
+                with self.related_list_container:
+                    ui.label('请先搜索并勾选标签…').classes('text-sm text-gray-400 italic p-4')
+
+    # ══════════════════════════════════════════════════════════════════════
+    # 渲染关联推荐列表
+    # ═════════════════════════════════════════════════════════════���════════
+
+    def _render_related_list(self, related: list, show_nsfw: bool):
+        self.related_list_container.clear()
+        self._related_checkboxes.clear()
+
+        filtered = [r for r in related if not (r.nsfw == '1' and not show_nsfw)]
+        if not filtered:
+            with self.related_list_container:
+                ui.label('暂无推荐').classes('text-sm text-gray-400 italic p-4')
+            return
+
+        selected_now = set(self._get_selected_tags())
+
+        with self.related_list_container:
+            for r in filtered:
+                tag = r.tag
+                cn_first = r.cn_name.split(',')[0].strip() if r.cn_name else ''
+                is_selected = tag in selected_now
+                score_pct = f'+{r.cooc_score * 100:.0f}%'
+
+                # 获取 wiki
+                wiki_text = ''
+                try:
+                    tagger = DanbooruTagger._instance
+                    if tagger and tagger.df is not None and tag in tagger._name_to_idx:
+                        idx = tagger._name_to_idx[tag]
+                        wiki_text = str(tagger.df.iloc[idx].get('wiki', ''))
+                except Exception:
+                    pass
+
+                sources_str = '、'.join(r.sources) if r.sources else '—'
+                CAT_LABEL = {'General': '通用', 'Character': '角色', 'Copyright': '作品'}
+                cat_label = CAT_LABEL.get(r.category, '')
+                tooltip_html = ''
+                if wiki_text:
+                    prefix = f'<span style="opacity:0.7;margin-right:4px;">[{cat_label}] </span>' if cat_label else ''
+                    tooltip_html += f'<div style="margin-bottom:6px;">{prefix}{wiki_text}</div>'
+                tooltip_html += (
+                    f'<div style="opacity:0.85;">'
+                    f'{r.cn_name}<br>'
+                    f'共现: {r.cooc_count:,}  相关度: {r.cooc_score:.2f}<br>'
+                    f'来自选中: {sources_str}'
+                    f'</div>'
+                )
+
+                # 行背景色按分类区分
+                CAT_BG = {
+                    'General':   'background-color: rgba(59,130,246,0.06);',   # 淡蓝
+                    'Character': 'background-color: rgba(34,197,94,0.06);',    # 淡绿
+                    'Copyright': 'background-color: rgba(236,72,153,0.06);',   # 淡红/粉
+                }
+                row_bg = CAT_BG.get(r.category, '')
+
+                # 整行容器，tooltip 挂在行上
+                with ui.row().classes(
+                    'w-full items-center gap-2 px-3 py-2 related-item border-b border-gray-100'
+                ).style(row_bg):
+                    # 整行 wiki tooltip
+                    if tooltip_html:
+                        with ui.tooltip().props('content-class="bg-black text-white shadow-4" max-width="500px"'):
+                            ui.html(tooltip_html).style('font-size:14px;line-height:1.5;max-width:480px;')
+
+                    # Checkbox
+                    cb = ui.checkbox(
+                        '', value=is_selected,
+                        on_change=lambda e, t=tag: self._on_related_checkbox_change(t, e.value)
+                    ).props('dense')
+                    self._related_checkboxes[tag] = cb
+
+                    # 标签名（可点击跳转）+ 中文名
+                    with ui.column().classes('flex-grow gap-0 min-w-0'):
+                        link = ui.link(
+                            tag,
+                            f'https://danbooru.donmai.us/wiki_pages/{tag}',
+                            new_tab=True
+                        ).classes('tag-link text-primary font-bold text-xs')
+                        link.on('click', self._mark_interaction)
+
+                        if cn_first:
+                            ui.label(cn_first).classes('text-xs text-gray-500 truncate')
+
+                    # 关联分数
+                    score_color = 'green' if r.cooc_score > 0.6 else ('teal' if r.cooc_score > 0.3 else 'grey')
+                    ui.label(score_pct).classes(f'text-sm font-bold text-{score_color}-600 whitespace-nowrap')
+
+    # ══════════════════════════════════════════════════════════════════════
+    # 交互逻辑
+    # ══════════════════════════════════════════════════════════════════════
+
+    async def _hide_banner_when_ready(self):
+        while not DanbooruTagger.is_ready():
+            await asyncio.sleep(1)
+        if self.init_banner:
+            self.init_banner.set_visibility(False)
+
+    def _client_alive(self) -> bool:
+        try:
+            _ = self.search_btn.client
+            return True
+        except RuntimeError:
+            return False
+
+    # ── 分词筛选 ────────────────���─────────────────────────────────────────
+
+    def _filter_by_source(self, keyword: str):
+        show_nsfw_val = self.input_nsfw.value
+        if not keyword or keyword == 'ALL':
+            filtered = self.full_table_data
+        else:
+            filtered = [r for r in self.full_table_data if r['source'] == keyword]
+
+        self.result_table.rows = apply_nsfw_filter(filtered, show_nsfw_val)
+
+        for child in self.keywords_container.default_slot.children:
+            if isinstance(child, ui.chip):
+                selected = (
+                    (keyword == 'ALL' and child.text == '全部')
+                    or (keyword == self.current_query_str and child.text == '整句')
+                    or (child.text == keyword)
+                )
+                is_segment = child.text in self.current_segments
+                if selected:
+                    chip_color, text_color = 'primary', 'white'
+                elif is_segment:
+                    chip_color, text_color = 'blue-1', 'blue-8'
+                else:
+                    chip_color, text_color = 'grey-4', 'black'
+                child.props(f'color={chip_color} text-color={text_color}')
+
+    # ── 搜索 ──────────────────────────────────────────────────────────────
+
+    async def perform_search(self):
+        query = self.search_input.value.strip()
+        if not query:
+            return
+
+        # 搜索前保存配置
+        self._save_config()
+
+        self.current_query_str = query
+        self.search_btn.disable()
+        self.spinner.classes(remove='hidden')
+        ui.notify('正在搜索...', type='info')
+
+        if self.bad_case_btn is not None:
+            self.bad_case_btn.disable()
+
+        target_layers_list = [k for k, v in self.selected_layers.items() if v]
+        target_cats_list   = [k for k, v in self.selected_cats.items()   if v]
+
+        if not target_layers_list:
+            ui.notify('请至少选择一个匹配层！', type='warning')
+            self.search_btn.enable()
+            self.spinner.classes(add='hidden')
+            return
+
+        try:
+            tagger = await DanbooruTagger.get_instance()
+
+            # NSFW 保护模式：开 = 不显示 NSFW
+            show_nsfw_val = self.input_nsfw.value
+
+            request = SearchRequest(
+                query=query,
+                top_k=int(self.input_top_k.value),
+                limit=int(self.input_limit.value),
+                popularity_weight=float(self.input_weight.value),
+                show_nsfw=show_nsfw_val,
+                use_segmentation=self.input_segment.value if self.input_segment else True,
+                target_layers=target_layers_list,
+                target_categories=target_cats_list,
+            )
+            response = await run.io_bound(tagger.search, request)
+
+            # 后台计数
+            async def silent_counter_update():
+                try:
+                    await counter.increment()
+                    if response.keywords:
+                        await counter.add_keywords(response.keywords)
+                    self._update_footer_text()
+                except Exception as e:
+                    print(f"[UI] 后台静默更新计数失败: {e}", flush=True)
+            asyncio.create_task(silent_counter_update())
+
+            if not self._client_alive():
+                return
+
+            table_data = [result_to_row(r, show_nsfw_val) for r in response.results]
+            self.full_table_data = table_data
+            self.full_tags_str = response.tags_all
+            self.full_tags_str_sfw = response.tags_sfw
+            self.current_segments = list(response.segments) if response.segments else []
+
+            # 显示结果区域
+            self.results_section.set_visibility(True)
+
+            _saved_rpp = self._get_rows_per_page()
+            self.result_table.rows = apply_nsfw_filter(table_data, show_nsfw_val)
+            self._set_rows_per_page(_saved_rpp)
+            self.result_table.selected = []
+            self.tag_weights.clear()
+            self.chip_extra_selected.clear()
+            self._render_selected_chips()
+            self._update_selection_display(None)
+
+            # 清空关联推荐
+            self._refresh_related([], show_nsfw_val)
+
+            # 分词筛选 chips
+            self.keywords_container.clear()
+            with self.keywords_container:
+                ui.label('分词筛选:').classes('text-sm text-gray-500 font-bold mr-2')
+                ui.chip('全部', on_click=lambda: self._filter_by_source('ALL')) \
+                    .props('color=primary text-color=white clickable')
+                use_seg = self.input_segment.value if self.input_segment else True
+                if use_seg:
+                    ui.chip('整句',
+                            on_click=lambda: self._filter_by_source(self.current_query_str)) \
+                        .props('color=grey-4 text-color=black clickable')
+                    # 从句级原始片段（分隔符切分后未 jieba 的长片段，区别于关键词）
+                    for seg in response.segments:
+                        ui.chip(seg,
+                                on_click=lambda s=seg: self._filter_by_source(s)) \
+                            .props('color=blue-1 text-color=blue-8 clickable')
+                    for kw in response.keywords:
+                        ui.chip(kw,
+                                on_click=lambda k=kw: self._filter_by_source(k)) \
+                            .props('color=grey-4 text-color=black clickable')
+                else:
+                    ui.label('(分词已关闭)').classes('text-xs text-gray-400')
+
+            ui.notify(f'找到 {len(table_data)} 个标签', type='positive')
+            self.current_search_interacted = False
+
+            if self.bad_case_btn is not None:
+                self.bad_case_btn.enable()
+
+        except RuntimeError as e:
+            if 'deleted' in str(e).lower() or 'client' in str(e).lower():
+                return
+            try:
+                ui.notify(f'错误: {str(e)}', type='negative')
+            except RuntimeError:
+                pass
+        except Exception as e:
+            try:
+                ui.notify(f'错误: {str(e)}', type='negative')
+            except RuntimeError:
+                pass
+        finally:
+            try:
+                self.search_btn.enable()
+                self.spinner.classes(add='hidden')
+            except RuntimeError:
+                pass
+
+    # ── 选择管理 ──────────────────────────────────────────────────────────
+
+    def _get_selected_tags(self) -> list[str]:
+        table_tags = [row['tag'] for row in self.result_table.selected] if self.result_table else []
+        seen = set(table_tags)
+        extra = [t for t in self.chip_extra_selected if t not in seen]
+        return table_tags + extra
+
+    def _set_selected_tags(self, tags: list[str]):
+        tag_set = set(tags)
+        table_tag_set = {row['tag'] for row in self.result_table.rows} if self.result_table else set()
+        self.chip_extra_selected.clear()
+        self.chip_extra_selected.update(t for t in tag_set if t not in table_tag_set)
+        # clean up weights for deselected tags
+        for t in list(self.tag_weights):
+            if t not in tag_set:
+                del self.tag_weights[t]
+
+        if self.result_table is not None:
+            self.result_table.selected = [row for row in self.result_table.rows if row.get('tag') in tag_set]
+
+        all_tags = self._get_selected_tags()
+        if self.selection_count_label is not None:
+            self.selection_count_label.text = str(len(all_tags))
+        self._render_selected_chips()
+
+    def _update_selection_display(self, _e):
+        if self.result_table is None:
+            return
+        self._mark_interaction()
+
+        all_tags = self._get_selected_tags()
+        # clean up weights for deselected tags
+        tag_set = set(all_tags)
+        for t in list(self.tag_weights):
+            if t not in tag_set:
+                del self.tag_weights[t]
+        # init weight for newly selected tags
+        for t in all_tags:
+            self.tag_weights.setdefault(t, 1.0)
+
+        if self.selection_count_label is not None:
+            self.selection_count_label.text = str(len(all_tags))
+        self._render_selected_chips()
+
+        show_nsfw_val = self.input_nsfw.value
+        if all_tags:
+            self._refresh_related_from_selection(all_tags, show_nsfw_val)
+        else:
+            self.chip_extra_selected.clear()
+            self._refresh_related([], show_nsfw_val)
+
+    def _on_related_checkbox_change(self, tag: str, checked: bool):
+        self._mark_interaction()
+        current = self._get_selected_tags()
+        if checked:
+            if tag not in current:
+                current.append(tag)
+                self.tag_weights.setdefault(tag, 1.0)
+                self._set_selected_tags(current)
+                ui.notify(f'已添加 {tag}', type='positive', timeout=1500)
+        else:
+            if tag in current:
+                current.remove(tag)
+                self.tag_weights.pop(tag, None)
+                self._set_selected_tags(current)
+                ui.notify(f'已移除 {tag}', type='warning', timeout=1500)
+
+    def _manual_refresh_related(self):
+        """手动触发关联推荐列表的刷新"""
+        self._mark_interaction()
+        show_nsfw_val = self.input_nsfw.value
+        all_tags = self._get_selected_tags()
+
+        if all_tags:
+            self._refresh_related_from_selection(all_tags, show_nsfw_val)
+            ui.notify('已触发关联推荐更新', type='info', timeout=1500)
+        else:
+            self.chip_extra_selected.clear()
+            self._refresh_related([], show_nsfw_val)
+            ui.notify('已清空关联推荐', type='info', timeout=1500)
+
+    # ── 关联推荐 ──────────────────────────────────────────────────────────
+
+    def _refresh_related(self, related: list, show_nsfw: bool):
+        selected_now = set(self._get_selected_tags())
+        old_related  = self.current_related
+        new_tags  = {r.tag for r in related}
+        preserved = [r for r in old_related if r.tag in selected_now and r.tag not in new_tags]
+        merged = list(related) + preserved
+
+        self.current_related = merged
+        if self.related_list_container is not None:
+            self._render_related_list(merged, show_nsfw)
+
+    def _refresh_related_from_selection(self, selected_tags: list[str], show_nsfw: bool):
+        async def _do():
+            tagger  = await DanbooruTagger.get_instance()
+            related = await run.io_bound(
+                tagger.get_related,
+                selected_tags,
+                set(selected_tags),
+                50,
+                show_nsfw,
+            )
+            self._refresh_related(related, show_nsfw)
+        asyncio.ensure_future(_do())
+
+    # ── 表格列动态更新 ──────────────────────────────────────────────────
+
+    def _update_table_columns(self, e=None):
+        cols = list(TABLE_COLUMNS)
+        if self.sw_semantic and self.sw_semantic.value:
+            cols.append(OPTIONAL_COLS['semantic'])
+        if self.sw_layer and self.sw_layer.value:
+            cols.append(OPTIONAL_COLS['layer'])
+        if self.sw_source and self.sw_source.value:
+            cols.append(OPTIONAL_COLS['source'])
+        self.result_table.columns = cols
+
+    # ── NSFW 切换 ─────────────────────────────────────────────────────────
+
+    def on_nsfw_toggle(self, e):
+        show_nsfw_val = self.input_nsfw.value
+
+        self.result_table.rows = apply_nsfw_filter(self.full_table_data, show_nsfw_val)
+        if not show_nsfw_val:
+            self.result_table.selected = [r for r in self.result_table.selected if r.get('nsfw') != '1']
+        self._update_selection_display(None)
+
+    # ── 复制 / 反馈 ──────────────────────────────────────────────────────
+
+    def _toggle_prompt_format(self):
+        if self.prompt_format == 'sdxl':
+            self.prompt_format = 'nai'
+            if self.format_toggle_btn:
+                self.format_toggle_btn.text = 'NAI'
+                self.format_toggle_btn.props('color=purple-7')
+        else:
+            self.prompt_format = 'sdxl'
+            if self.format_toggle_btn:
+                self.format_toggle_btn.text = 'SDXL'
+                self.format_toggle_btn.props('color=grey-7')
+
+    def copy_selection(self):
+        self._mark_interaction()
+        tags = self._get_selected_tags()
+        prompt = ', '.join(
+            _format_tag_with_weight(t, self.tag_weights.get(t, 1.0), self.prompt_format)
+            for t in tags
+        )
+        ui.clipboard.write(prompt)
+        fmt_label = 'NAI' if self.prompt_format == 'nai' else 'SDXL'
+        ui.notify(f'已复制选中标签（{fmt_label} 格式）!', type='positive')
+
+        async def silent_copy_update():
+            try:
+                await counter.increment_copy()
+            except Exception:
+                pass
+        asyncio.create_task(silent_copy_update())
+
+    def _copy_all_tags(self):
+        self._mark_interaction()
+        show_nsfw_val = self.input_nsfw.value
+        tags_str = self.full_tags_str if show_nsfw_val else self.full_tags_str_sfw
+        if tags_str:
+            ui.clipboard.write(tags_str)
+            ui.notify('已复制全部标签!', type='positive')
+        else:
+            ui.notify('暂无标签可复制', type='warning')
+
+    async def report_bad_case(self):
+        from platform_utils import PLATFORM
+        query = self.current_query_str.strip()
+        if len(query) <= 1:
+            ui.notify('搜索词太短，无法提交反馈。', type='warning', timeout=2000)
+            return
+        if self.bad_case_btn is not None:
+            self.bad_case_btn.disable()
+        try:
+            settings = {
+                'top_k': int(self.input_top_k.value) if self.input_top_k else None,
+                'segmentation': self.input_segment.value if self.input_segment else None,
+                'nsfw': self.input_nsfw.value if self.input_nsfw else None,
+            }
+            await counter.add_bad_case(query, platform=PLATFORM, settings=settings)
+            ui.notify('感谢反馈！我们会持续优化。', type='positive', timeout=3000)
+        except Exception as e:
+            print(f'[UI] bad_case 记录异常: {e}')
+            ui.notify('记录失败，请稍后再试。', type='warning', timeout=3000)
+            if self.bad_case_btn is not None:
+                self.bad_case_btn.enable()
+
+# ── 页面路由 ───────────────────────────────────────────────────────────────────
+
+@ui.page('/')
+async def main_page():
+    app_ui = DanbooruSearchUI()
+    app_ui.build_page()
+
+    async def silent_visit_update():
+        try:
+            await counter.increment_visit()
+            app_ui._update_footer_text()
+        except Exception:
+            pass
+    asyncio.create_task(silent_visit_update())
+
+    # 恢复用户配置（在页面渲染完成后执行）
+    await app_ui._restore_config()
+
+
+# ── 入口 ───────────────────────────────────────────────────────────────────────
+
+if __name__ in {'__main__', '__mp_main__'}:
+    host, port = get_host_port()
+
+    @app.on_startup
+    def _warmup():
+        async def background_init_tasks():
+            await asyncio.sleep(5)
+            print("[UI] 开始预热计数器与引擎", flush=True)
+            await counter.init()
+            await DanbooruTagger.get_instance()
+            print("[UI] 后台预热全部完成！", flush=True)
+        asyncio.create_task(background_init_tasks())
+
+    @app.on_shutdown
+    def _shutdown():
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                loop.create_task(counter.force_sync())
+            else:
+                asyncio.run(counter.force_sync())
+        except Exception as e:
+            print(f"[UI] 关机同步失败: {e}")
+
+    app.mount('/api', api_app)
+
+    mcp_app = mcp.streamable_http_app()
+    app.mount('/mcp', mcp_app)
+    _mcp_lifespan_ctx = None
+    @app.on_startup
+    async def _start_mcp():
+        global _mcp_lifespan_ctx
+        _mcp_lifespan_ctx = mcp_app.router.lifespan_context(mcp_app)
+        await _mcp_lifespan_ctx.__aenter__()
+    @app.on_shutdown
+    async def _stop_mcp():
+        global _mcp_lifespan_ctx
+        if _mcp_lifespan_ctx is not None:
+            await _mcp_lifespan_ctx.__aexit__(None, None, None)
+
+    @app.get('/googlebd34b54f8562aa06.html')
+    def google_verification():
+        return PlainTextResponse('google-site-verification: googlebd34b54f8562aa06.html')
+
+    @app.get('/robots.txt')
+    def robots_txt():
+        content = (
+            "User-agent: *\n"
+            "Allow: /$\n"
+            "Disallow: /api/\n"
+            "Disallow: /_nicegui/\n"
+            "Disallow: /socket.io/\n"
+        )
+        return PlainTextResponse(content)
+
+    @app.head('/')
+    async def head_root():
+        return PlainTextResponse("")
+
+    ui.run(
+        host=host,
+        port=port,
+        title='Danbooru Tags Searcher',
+        reload=not is_cloud(),
+        show=not is_cloud(),
+        reconnect_timeout=120,
+    )