Auto-sync from GitHub Actions

README.md

@@ -49,7 +49,9 @@ thumbnail: >-
   * 表格内置 Danbooru 维基释义悬浮提示，并提供前往原站的快捷链接。
 
 
-## 功能概览
+## 快速了解
+
+### 功能概览
 
 本工具提供以下核心功能：
 
@@ -60,11 +62,11 @@ thumbnail: >-
 - [关联推荐](#5-关联推荐共现匹配)
 - [推荐擅长画师](#6-推荐擅长画师)
 
-前四项基于**语义向量匹配**，后两项基于**标签-画师共现数据**。
+前四项基于**语义向量匹配**，后两项基于**共现数据**（标签-标签共现与标签-画师共现）。
 
 ---
 
-## 参数说明
+### 参数说明
 
 在进入功能介绍之前，先了解几个关键参数，它们会影响所有搜索模式的结果质量。
 
@@ -92,7 +94,9 @@ thumbnail: >-
 
 ---
 
-## 1. 精确查词
+## 功能介绍
+
+### 1. 精确查词
 
 **适用场景：** 你知道某个标签的大概写法，但不确定拼写是否准确，或者只记得部分写法。
 
@@ -102,7 +106,7 @@ thumbnail: >-
 
 > 关闭智能分词，确保整个输入作为一个整体进行语义匹配，不会被拆散。
 
-### 示例
+#### 示例
 
 | 你的输入 | 实际标准标签 | 说明 |
 |---|---|---|
@@ -114,13 +118,13 @@ thumbnail: >-
 
 ---
 
-## 2. 概念模糊发散
+### 2. 概念模糊发散
 
 **适用场景：** 你脑中有一个模糊的概念或风格意象，但不知道在 Danbooru 里对应哪些标签，希望系统帮你"发散"出相关的候选标签。
 
 **建议参数：** Top K: 80~160 | 结果上限: 80 | 热度权重: 0.15 | **开启智能分词**
 
-### 示例
+#### 示例
 
 **示例 1：「兔耳朵」**
 
@@ -154,7 +158,7 @@ thumbnail: >-
 
 ---
 
-## 3. 输入描述查词
+### 3. 输入描述查词
 
 **适用场景：** 你能描述某个具体的事物、角色、场景，但不知道 Danbooru 的对应标签。可以使用中文或英文自然语言描述，也可以通过 IP 名称、角色外号来查找角色标签。
 
@@ -162,7 +166,7 @@ thumbnail: >-
 
 > 关闭智能分词，使系统对你的整段描述做整体语义匹配，而不是拆词。
 
-### 示例
+#### 示例
 
 **示例 1：用描述定位角色**
 
@@ -186,7 +190,7 @@ thumbnail: >-
 
 ---
 
-## 4. 完整画面查找
+### 4. 完整画面查找
 
 **适用场景：** 你脑中已经有了一幅完整的画面，希望一次性把整段描述转换成尽可能多的 Danbooru 标签，用于 AI 绘画的完整 Prompt。
 
@@ -194,7 +198,7 @@ thumbnail: >-
 
 > 开启智能分词：系统会自动拆分你的长句，提取其中的关键概念分别检索，再合并去重，覆盖尽可能多的画面元素。
 
-### 示例
+#### 示例
 
 **示例 1：雨中奔跑的少女**
 
@@ -235,7 +239,7 @@ thumbnail: >-
 
 ---
 
-## 5. 关联推荐（共现匹配）
+### 5. 关联推荐（共现匹配）
 
 关联推荐与前四项功能机制不同，它不依赖语义相似度，而是基于 **Danbooru 图库中标签的共现统计**：如果两个标签经常出现在同一张图上，就认为它们相关。
 
@@ -243,7 +247,7 @@ thumbnail: >-
 
 关联推荐的得分是基于 NPMI（互信息归一化）计算的，能有效过滤掉那些只是因为自身热度高而频繁出现的标签。
 
-### 适用场景
+#### 适用场景
 
 **场景 1：查看某种服饰/道具的常见搭配**
 
@@ -279,7 +283,7 @@ thumbnail: >-
 
 ---
 
-## 6. 推荐擅长画师
+### 6. 推荐擅长画师
 
 推荐擅长画师与关联推荐类似，基于 **标签-画师 NPMI 共现数据**，但目标是推荐擅长绘制已选标签所描述元素的画师。
 
@@ -287,7 +291,7 @@ thumbnail: >-
 
 **评分逻辑：** 对每个已选标签，计算该标签与画师的 NPMI 共现分，累加后乘以命中标签数加成，最终归一化显示为百分比。
 
-### 适用场景
+#### 适用场景
 
 **场景 1：根据风格标签找画师**
 
@@ -303,7 +307,7 @@ thumbnail: >-
 
 ---
 
-## 使用技巧
+### 使用技巧
 
 **技巧 1：先宽后窄**
 先用完整画面查找拿到大量候选标签，再用分词筛选 chip 或手动去掉不相关的，然后勾选剩余标签触发关联推荐，补充遗漏细节。
@@ -330,7 +334,9 @@ thumbnail: >-
 
 ---
 
-## API 接口
+## 接口方法
+
+### REST API
 
 本工具同时提供 REST API，可集成到你自己的工作流中。
 
@@ -341,37 +347,61 @@ thumbnail: >-
 POST /api/search
 {
     "query": "白色水手服的女孩",
-    "top_k": 20,
-    "limit": 20,
-    "show_nsfw": false
+    "search_mode": "full_scene",
+    "category": "all",
+    "show_nsfw": true,
+    "include_wiki": false
 }
 ```
 
+`search_mode` 使用预设检索策略，不再直接暴露 `top_k`、`limit`、`popularity_weight`、`use_segmentation` 等底层参数：
+
+| 模式 | 适用场景 |
+|---|---|
+| `full_scene` | 默认模式。用于完整画面、多人/多元素描述，返回可直接使用的 prompt |
+| `concept_explore` | 开放式概念发散，例如“兔耳朵都有哪些” |
+| `subject_describe` | 单一角色、物品或视觉概念描述，例如“EVA中蓝发的驾驶员” |
+| `precise_lookup` | 精确查词或拼写���错，例如 `selafuku` |
+
+`category` 可选：`all`、`general`、`character`、`copyright`。搜索响应包含 `prompt`、`keywords`、`results`，当 `include_wiki=true` 时，每条结果会附带 `wiki` 字段。
+
 **关联推荐接口**
 ```
 POST /api/related
 {
     "tags": ["white_serafuku", "sailor_collar"],
-    "limit": 20,
-    "show_nsfw": false
+    "limit": 50,
+    "show_nsfw": true,
+    "include_wiki": false
 }
 ```
 
+响应为 `results` 列表；如果输入标签拼写错误但可被纠正，会额外返回 `correction_note` 和 `corrections`。
+
 **推荐擅长画师接口**
 ```
 POST /api/artists
 {
     "tags": ["1girl", "blue_hair", "school_uniform"],
     "limit": 30,
-    "min_cooc": 3
+    "min_cooc": 3,
+    "show_nsfw": true
 }
 ```
 
+响应字段：`artist`（画师名）、`cooc_count`（共现次数）、`post_count`（作品数）、`sources`（命中标签）、`top_tags`（该画师最常画的 10 个标签，含中文名）。
+
+**健康检查接口**
+
+```
+GET /api/health
+```
+
 详见：[API 文档](https://sakizuki-danboorusearch.hf.space/api/docs)
 
 ---
 
-## MCP 接口
+### MCP 接口
 
 本工具提供 MCP（Model Context Protocol）服务，支持将搜索引擎直接接入 Claude Desktop、Cursor、Cherry Studio 等支持 MCP 协议的大模型客户端，让 AI 能够在对话中直接调用标签搜索能力。
 
@@ -387,7 +417,7 @@ https://sakizuki-danboorusearchonline.ms.show/mcp/mcp
 
 以上两个端口提供完全相同的服务，互为备份
 
-### 接入方法
+#### 接入方法
 
 **方法一：Claude Desktop**
 
@@ -417,7 +447,7 @@ npm install -g mcp-remote
 }
 ```
 
-保存后重启 Claude Desktop，工具列表中出现 `search_tags`、`get_related_tags` 和 `get_artist_recommendations` 即为成功。
+保存后重启 Claude Desktop，工具列表中出现 `search_tags`、`get_related_tags`、`get_artist_recommendations`、`get_anima_format` 和 `get_newbie_format` 即为成功。
 
 > 注意：不要使用 `"url"` 字段直接填写地址，Claude Desktop 不支持该格式，会提示配置无效。也不推荐通过 `npx mcp-remote` 调用，首次执行时 `npx` 需要临时下载包，npm 缓存损坏时会导致启动失败。全局安装可规避此问题。
 
@@ -433,7 +463,7 @@ npm install -g mcp-remote
 
 添加完成后重启客户端，或在 MCP 管理界面手动刷新连接。
 
-### 可用工具
+#### 可用工具
 
 接入后 AI 可调用以下工具：
 
@@ -444,17 +474,33 @@ npm install -g mcp-remote
 | 参数 | 默认值 | 说明 |
 |---|---|---|
 | `query` | — | 自然语言描述（必填，推荐中文）。支持空格/逗号/顿号显式分隔概念 |
-| `use_segmentation` | `true` | 智能分词开关，完整画面描述时开启，精确查词时关闭 |
-| `top_k` | `5` | 每个分词的语义召回数量，发散探索时调高至 80~160 |
-| `limit` | `80` | 返回标签总数上限 |
-| `popularity_weight` | `0.15` | 热度权重，控制高频标签的排名影响 |
-| `show_nsfw` | `true` | 是否包含 NSFW 标签 |
+| `search_mode` | `"full_scene"` | 检索策略：`full_scene`、`concept_explore`、`subject_describe`、`precise_lookup` |
 | `category` | `"all"` | 标签类别筛选：`"all"` 全部、`"general"` 通用、`"character"` 角色、`"copyright"` 作品 |
+| `show_nsfw` | `true` | 是否包含 NSFW 标签 |
+| `include_wiki` | `false` | 是否在结果中附带 Danbooru wiki 释义 |
+
+`search_mode` 的选择规则：
+
+- `full_scene`：默认值。用户描述的是一张具体画面时使用，即使描述里有很多元素，也仍然属于完整画面。
+- `concept_explore`：用户想浏览某个概念下有哪些候选标签时使用，结果更多，token 消耗更高。
+- `subject_describe`：只描述一个单一视觉概念、角色或物品时使用；多元素画面不要用这个模式。
+- `precise_lookup`：用于拼写纠错或接近精确的标签查询。
+
+返回 JSON 包含：`prompt`（逗号分隔标签）、`keywords`（检索关键词）、`results`（标签结果）。每条结果包含 `tag`、`cn_name`，当 `include_wiki=true` 时包含 `wiki`。
 
 **`get_related_tags`** — 共现关联推荐
 
 给定一组已选标签，返回在 Danbooru 图库中与之最常共现的相关标签，基于 NPMI 评分，可有效过滤掉仅因自身热度高而频繁出现的标签。
 
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `tags` | — | 标签列表（必填，Danbooru 英文标签名） |
+| `limit` | `50` | 最多返回关联标签数 |
+| `show_nsfw` | `true` | 是否包含 NSFW 标签 |
+| `include_wiki` | `false` | 是否在结果中附带 Danbooru wiki 释义 |
+
+返回字段：`tag`、`cn_name`、`sources`，当 `include_wiki=true` 时包含 `wiki`。如果输入标签拼写错误但可纠正，会返回纠错说明。
+
 **`get_artist_recommendations`** — 推荐擅长画师
 
 给定一组标签，返回擅长绘制这些元素的画师列表，基于标签-画师 NPMI 共现数据排序。
@@ -468,7 +514,15 @@ npm install -g mcp-remote
 
 返回字段：`artist`（画师名）、`cooc_count`（共现次数）、`post_count`（作品数）、`sources`（命中标签）、`top_tags`（该画师最常画的 10 个标签，含中文名）
 
-### 调用示例
+**`get_anima_format`** — 获取 Anima 提示词格式规范
+
+当用户需要把检索到的标签整理为 Anima 模型的 Hybrid 提示词时调用。返回完整格式说明，包括硬标签层、空间叙事层、标签格式化、权重语法、多人物防串扰和中文解释规则。
+
+**`get_newbie_format`** — 获取 NewBie XML 提示词格式规范
+
+当用户需要输出 NewBie 模型 XML 提示词时调用。返回 XML 结构、字段职责、标签处理规则、多人角色分组和 caption 写作要求。
+
+#### 调用示例
 
 接入后，你可以直接用自然语言告诉 AI 你的需求，AI 会自动选择合适的参数调用工具：
 
@@ -486,21 +540,22 @@ npm install -g mcp-remote
 
 > 找「反乌托邦、赛博朋克、蒸汽朋克」的 General 类标签，只查通用特征不查作品名
 
-### 查询写作技巧（写给 LLM）
-
-为了让搜索更精准，在构造 `query` 时请注意以下几点：
+> 按 Anima 模型格式，把这些标签整理成 Hybrid 提示词
 
-1. **概念列表用显式分隔符：** 需要批量查询多个独立概念时，用空格、中文逗号（，）或顿号（、）分隔。每个 ≤7 字的片段会作为完整概念匹配，不会被错误拆开。例如 `运动社团 校队 比赛` 而非 `运动社团校队比赛`。
+> 按 NewBie XML 格式输出这个角色场景的提示词
 
-2. **画面描述写自然语句：** 完整场景描述不需要显式分隔，系统会自动分词。例如 `一个穿着白色水手服蓝色短裙的少女在雨中奔跑`。
+#### 服务使用说明
 
-3. **查角色/作品时关闭分词：** 精确查找某个角色名或作品名时，设 `use_segmentation=false` 和 `category="character"`（或 `"copyright"`），避免名字中的词汇被单独匹配到无关标签。
+HF Space 在无流量时会进入休眠状态，首次请求需要等待冷启动（约 30~60 秒）。若 AI 调用超时，稍等片刻后重试即可，或先访问 [Space 页面](https://huggingface.co/spaces/SAkizuki/DanbooruSearch) 将其唤醒。
 
-4. **长短语会自动保持完整语义：** 即使用显式分隔符切出的片段超过 7 字，系统也会对其自动分词并同时保留原始片段作为额外查询（从句级语义），不会丢失整体语境。
+任何用户都可以免费将本服务的API或MCP接口接入自己的私有或公开服务中。
 
-### 注意事项
+**如果接入公开服务，务必在主页提供链接到本服务主地址的友情链接**：
 
-HF Space 在无流量时会进入休眠状态，首次请求需要等待冷启动（约 30~60 秒）。若 AI 调用超时，稍等片刻后重试即可，或先访问 [Space 页面](https://huggingface.co/spaces/SAkizuki/DanbooruSearch) 将其唤醒。
+```
+URL: https://huggingface.co/spaces/SAkizuki/DanbooruSearch
+简介: 基于语义匹配的Danbooru标签搜索引擎，支持多维匹配与共现关联推荐。
+```
 
 ---
 
@@ -516,7 +571,7 @@ HF Space 在无流量时会进入休眠状态，首次请求需要等待冷启
 
 ---
 
-## 注意事项
+## 使用注意事项
 
 - 本工具为 AI 辅助工具，检索结果未必 100% 准确
 - 查找结果可能包含 NSFW 内容（默认隐藏）
@@ -527,7 +582,7 @@ HF Space 在无流量时会进入休眠状态，首次请求需要等待冷启
 
 DanbooruSearch 会继续免费开放。如果这个小工具刚好帮你省了点时间，可以自愿赞赏一点维护成本；赞赏不解锁任何功能、不提高额度、不影响搜索结果，也不会获得特殊待遇。量力而行就好，未成年人请勿赞赏。
 
-微信赞赏码：<https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202501120027592.png>
+![微信赞赏码](https://akizukipic.oss-cn-beijing.aliyuncs.com/img/202501120027592.png)
 
 
 ## 搜索统计

mcp_server.py

@@ -590,25 +590,80 @@ prompt 内部分两层组装，同一语义不跨层重复：
 
 ---
 
-## 冲突检查（输出前必做）
+## 标签质量检查（输出前必做）
+
+### 冲突消解
 
 组装前必须消解以下冲突，逐项通过后才输出：
 
-| 冲突对 | 规则 |
-|--------|------|
-| `solo` vs 多人 | 选一个，不共存 |
-| `close-up` vs `full body` | 选一个景别 |
-| `from above` vs `from below` | 选一个视角 |
-| `from front` vs `from behind` | 选一个朝向 |
-| `closed eyes` vs `looking at viewer` | 选一个视线 |
-| 裸体 vs 服装 | 选一个着装状态 |
-| 多角色属性归属 | 发色/服装必须绑定具体角色，不串 |
-| 室内光源 vs 室外背景 | 光源和背景必须同空间 |
-| 背光 | 必须补脸部补光或轮廓保护 |
+#### 视角互斥示例
+
+| 标签A | 标签B | 原因 |
+|---|---|---|
+| `from front` | `from behind` | 物理矛盾 |
+| `from above` | `from below` | 物理矛盾 |
+| `looking at viewer` | `facing away` | 视线矛盾 |
+| `pov` | `full body` | POV 不可能看到自己全身 |
+| `close-up` | `full body` | 景别矛盾 |
+
+#### 身份互斥示例
+
+| 标签A | 标签B | 原因 |
+|---|---|---|
+| `solo` | `hetero` / `1boy` / `yuri` | 单人不存在互动 |
+| `femdom` | `male-on-female rape` | 逻辑矛盾（主导方冲突） |
+| `sleeping` / `unconscious` | `looking at viewer` | 无意识不可能直视 |
+| `blindfold` | `heart-shaped pupils` / `rolling eyes` | 看不到眼睛 |
+
+#### 服装互斥示例
+
+| 标签A | 标签B | 原因 |
+|---|---|---|
+| `completely nude` | 任何具体服装标签 | 全裸不穿衣 |
+| `pantyhose` | `barefoot` | 穿了丝袜不可能光脚（除非 `torn pantyhose`） |
+| `blindfold` | `glasses` | 物理冲突 |
+| 内衣套装 (`cat lingerie`, `lace lingerie`, `babydoll`, `negligee`, `chemise` 等) | `no panties` / `bottomless` | 内衣套装隐含包含内裤，模型优先解析套装忽略暴露标签；需暴露时拆为单件（`cat bra` + `no panties`） |
 
-单人正面默认保护脸部：保留 `looking at viewer` 或 `facing viewer`，空间叙事层补一句脸部清晰。
+> **不互斥**：外衣/制服（`maid outfit`、`school uniform`、`bunny suit`、`sailor uniform` 等）与 `no panties` / `bottomless` 完全兼容——穿制服不穿内裤 = 合理场景。
 
-多人必须绑定：`Place X on the left, with [hair], [outfit], [action].`
+#### 动作互斥示例
+
+| 标签A | 标签B | 原因 |
+|---|---|---|
+| `standing sex` | `lying` / `on back` | 体位矛盾 |
+| `missionary` | `doggystyle` | 不可能同时两个体位 |
+| `cowgirl position` | `prone bone` | 体位矛盾 |
+
+#### 细节过多互斥示例
+
+同一身体部位同时堆叠多个细节标签会导致模型过度渲染，产生畸形。**每部位细节标签 ≤2 个，且不能互斥。**
+
+| 部位 | 矛盾组合 | 原因 |
+|---|---|---|
+| 脚趾 | `spread toes` + `toe scrunch` / `toes curling` | 舒展 vs 蜷缩，物理矛盾 |
+| 脚趾 | `spread toes` + `feet together` | 分趾需要空间，合拢则压缩 |
+| 手指 | `spread fingers` + `clenched fist` / `gripping` | 张开 vs 握拳 |
+| 胸部 | `bouncing breasts` + `breasts squeeze together` | 弹跳 vs 挤压，动态矛盾 |
+| 嘴巴 | `open mouth` + `clenched teeth` / `closed mouth` | 张嘴 vs 闭嘴 |
+| 眼睛 | `rolling eyes` + `looking at viewer` | 翻白眼 vs 直视 |
+| 腿部 | `spread legs` + `legs together` | 分开 vs 并拢 |
+| 足部整体 | 3 个以上足部标签（如 `foot focus` + `footjob` + `toe scrunch` + `spread toes`） | 过度细化导致脚趾/脚掌畸形 |
+
+
+### 视线保护规则
+
+**单人场景下**，除非用户明确要求「背影/背对/转身离开/侧脸/profile/from behind」等具体视线限制，否则必须注入 `direct eye contact, facing viewer`。
+**两人及以上场景**：不强制注入 `direct eye contact`。根据角色间互动关系选择合适的视线标签（如 `looking at another`），或由用户明确指定。
+
+### 标签数量
+
+组装前按照下面的表格检查标签数量，严禁输出过多标签。过多标签会破坏模型的注意力。
+
+| 场景复杂度 | 总标签数 |
+|---|---|
+| 简单 | 16-30 |
+| 标准 | 22-38 |
+| 复杂（多人/特殊主题/剧情主视觉） | 30-48 | 
 
 ---
 
@@ -640,7 +695,7 @@ prompt 内部分两层组装，同一语义不跨层重复：
 ### 多人物详细结构（防串扰核心规则）
 
 ```
-[quality/meta/safety], [2girls / 1girl 1boy],
+[quality/meta/safety], [2girls / 1girl 1boy],[多人互动标签,例如：duo, holding each other's hands...]
 [character_A name], [series_A], [A hair], [A eyes], [A clothing], [A body], [A expression],
 [character_B name], [series_B], [B hair], [B eyes], [B clothing], [B body], [B expression],
 [shared pose/action], [background], [atmosphere], [composition], [@artist]
@@ -672,6 +727,9 @@ prompt 内部分两层组装，同一语义不跨层重复：
 
 ### 数据集标签（非动漫风格时的备选）
 
+当且仅当用户明确要求抽象、油画、概���艺术、数字绘画、插画风格，且 **明确要求排除动漫风格** 时才可用。
+如果用户仅要求油画风格，但没有明确说明排除动漫风格，仍然不能使用。
+
 在提示词最开头另起一行使用，可大幅改变风格倾向：
 - `ye-pop`：LAION-POP 数据集风格，偏抽象/油画/概念艺术
 - `deviantart`：DeviantArt 数据集风格，偏数字绘画/插画
@@ -695,7 +753,7 @@ masterpiece, best quality, very aesthetic, score_7, safe,
 ## 权重语法
 
 Anima 支持 Prompt Weighting，但需要的权重值 **高于 SDXL**：
-
+- 慎用权重：一段提示词中最多用权重强调4个标签，少而精，只强调最重要的部分
 - 正常强调：`(tag:2)` 起步
 - 强强调：`(tag:3)` 到 `(tag:5)`
 - 权重取值范围：2 ~ 5
@@ -719,16 +777,12 @@ Anima 支持 Prompt Weighting，但需要的权重值 **高于 SDXL**：
 Anima 在多人场景中极易发生特征混淆。必须严格遵守：
 
 1. **角色属性按角色分组排列**。同一角色的发型、瞳色、服装、体型连续出现后再切换。严禁交叉排列（如 `blue hair, red hair, short hair, long hair`）。
-
-2. **空间叙事层中为每个角色写一句"外观锚定短语"**。格式：`CharacterName with [key features]... do something...` 明确指出视觉归属。这比仅靠标签的防串扰效果强得多。
-
-3. **使用空间方位词分离角色**：left/right/foreground/background。
-
-4. **为易混淆特征使用权重**：`(blue hair:2)`, `(red hair:2)`。
-
-5. **角色外观在硬锚点层中充分描述**。官方文档明确指出：先命名角色，再描述其外观。仅列出角色名而不描述外观会让模型困惑。
-
-6. **空间叙事层中不重复标签内容**——空间叙事层补充空间关系、互动动作、光影氛围、构图取景。
+2. **互动词必须紧跟在人数后**。如果画中有多个人物，必须在人数声明完毕后，**立即** 写下他们的互动行为。推荐写法：2girls, duo, holding each other's hands,，然后开始分开描述每位美少女的容貌和衣服。
+3. **空间叙事层中为每个角色写一句"外观锚定短语"**。格式：`CharacterName with [key features]... do something...` 明确指出视觉归属。这比仅靠标签的防串扰效果强得多。
+4. **使用空间方位词分离角色**：left/right/foreground/background。
+5. **为易混淆特征使用权重**：`(blue hair:2)`, `(red hair:2)`。
+6. **角色外观在硬锚点层中充分描述**。官方文档明确指出：先命名角色，再描述其外观。仅列出角色名而不描述外观会让模型困惑。
+7. **空间叙事层中不重复标签内容**——空间叙事层补充空间关系、互动动作、光影氛围、构图取景。
 
 ---