entari-plugin-hyw 3.3.5__py3-none-any.whl → 3.3.7__py3-none-any.whl

entari_plugin_hyw/core/render.py

@@ -173,7 +173,8 @@ class ContentRenderer:
                      stats: Dict[str, Any] = None,
                      references: List[Dict[str, Any]] = None,
                      page_references: List[Dict[str, Any]] = None,
-                    stages_used: List[Dict[str, Any]] = None,
+                     image_references: List[Dict[str, Any]] = None,  # Added
+                     stages_used: List[Dict[str, Any]] = None,
                     flow_steps: List[Dict[str, Any]] = None,
                     model_name: str = "",
                     provider_name: str = "Unknown",
@@ -197,6 +198,9 @@ class ContentRenderer:
         # Preprocess to fix common markdown issues
         markdown_content = re.sub(r'(?<=\S)\n(?=\s*(\d+\.|\-|\*|\+) )', r'\n\n', markdown_content)
 
+        # references, page_references, image_references are already parsed by pipeline
+        # No filtering needed here - use them directly
+
         # AGGRESSIVE CLEANING: Strip out "References" section and "[code]" blocks from the text
         # because we are rendering them as structured UI elements now.
         
@@ -262,41 +266,21 @@ class ContentRenderer:
 
                 content_html = restore_math(content_html)
                 
-                # Post-process to style citation markers
-                # We split by code blocks to avoid messing up real code, BUT our citations ARE code blocks now.
-                # So we need to look at the code blocks themselves.
-                parts = re.split(r'(<code.*?>.*?</code>)', content_html, flags=re.DOTALL)
-                for i, part in enumerate(parts):
-                    # Check if this part is a code block containing our specific citation format
-                    if part.startswith('<code'):
-                        # Match <code>ref:123</code>
-                        # Note: attributes like class might be present if we are unlucky, but `ref:` inside usually means inline code.
-                        
-                        # 1. Numeric: <code>ref:123</code>
-                        ref_match = re.match(r'^<code.*?>ref:(\d+)</code>$', part)
-                        if ref_match:
-                            citation_id = ref_match.group(1)
-                            parts[i] = f'<span class="inline-flex items-center justify-center min-w-[16px] h-4 px-0.5 text-[10px] font-bold text-blue-600 bg-blue-50 border border-blue-200 rounded mx-0.5 align-top relative -top-0.5">{citation_id}</span>'
-                            continue
-                        # 2. Flow marker: <code>flow:a</code>
-                        flow_match = re.match(r'^<code.*?>flow:([a-zA-Z])</code>$', part)
-                        if flow_match:
-                            flow_id = flow_match.group(1).lower()
-                            parts[i] = f'<span class="inline-flex items-center justify-center min-w-[16px] h-4 px-0.5 text-[10px] font-bold text-orange-700 bg-orange-50 border border-orange-200 rounded mx-0.5 align-top relative -top-0.5">{flow_id}</span>'
-                            continue
-                            
-                    # If it's NOT a code block, or a code block we didn't transform, we leave it alone.
-                    # (Previous logic was to regex replace inside non-code blocks. We don't need that anymore 
-                    # because the prompt now enforces code spans).
-                content_html = "".join(parts)
+                # Convert [search:N] to blue badge
+                content_html = re.sub(
+                    r'\[search:(\d+)\]',
+                    r'<span class="inline-flex items-center justify-center min-w-[16px] h-4 px-0.5 text-[10px] font-bold text-blue-600 bg-blue-50 border border-blue-200 rounded mx-0.5 align-top relative -top-0.5">\1</span>',
+                    content_html
+                )
+                # Convert [page:N] to orange badge
+                content_html = re.sub(
+                    r'\[page:(\d+)\]',
+                    r'<span class="inline-flex items-center justify-center min-w-[16px] h-4 px-0.5 text-[10px] font-bold text-orange-700 bg-orange-50 border border-orange-200 rounded mx-0.5 align-top relative -top-0.5">\1</span>',
+                    content_html
+                )
                 
-                # Strip out the structured JSON blocks if they leaked into the content
-                # Look for <pre>... containing "references" at the end
-                # Make regex robust to any language class or no class
-                content_html = re.sub(r'<pre><code[^>]*>[^<]*references[^<]*</code></pre>\s*$', '', content_html, flags=re.DOTALL | re.IGNORECASE)
-                # Loop to remove multiple if present
-                while re.search(r'<pre><code[^>]*>[^<]*references[^<]*</code></pre>\s*$', content_html, flags=re.DOTALL | re.IGNORECASE):
-                    content_html = re.sub(r'<pre><code[^>]*>[^<]*references[^<]*</code></pre>\s*$', '', content_html, flags=re.DOTALL | re.IGNORECASE)
+                # Strip out the references code block if it leaked into the content
+                content_html = re.sub(r'<pre><code[^>]*>.*?references.*?</code></pre>\s*$', '', content_html, flags=re.DOTALL | re.IGNORECASE)
 
                 # --- PREPARE DATA FOR JINJA TEMPLATE ---
                 
@@ -361,6 +345,18 @@ class ContentRenderer:
                             "favicon_url": f"https://www.google.com/s2/favicons?domain={domain}&sz=32"
                         })
 
+                # 2c. Image Reference Processing
+                processed_image_refs = []
+                if image_references:
+                     for ref in image_references[:8]:
+                         url = ref.get("url", "#")
+                         processed_image_refs.append({
+                             "title": ref.get("title", "Image"),
+                             "url": url,
+                             "thumbnail": ref.get("thumbnail") or url, # Fallback to url if thumbnail not provided
+                             "domain": self._get_domain(url) or ref.get("domain") or "image"
+                         })
+
                 flow_steps = flow_steps or []
 
                 if stages_used:
@@ -404,8 +400,12 @@ class ContentRenderer:
                         stage_children = {}
                         
                         # References go to "Search"
-                        if name == "Search" and processed_refs:
-                            stage_children['references'] = processed_refs
+                        # Also Image References to "Search"
+                        if name == "Search":
+                            if processed_refs:
+                                stage_children['references'] = processed_refs
+                            if processed_image_refs:
+                                stage_children['image_references'] = processed_image_refs
 
                         # Flow steps go to "Agent"
                         if name == "Agent" and flow_steps:
@@ -425,7 +425,7 @@ class ContentRenderer:
                         # Pass through Search Queries
                         if "queries" in stage:
                             stage_children["queries"] = stage["queries"]
-                        
+                            
                         # Pass through Crawled Pages
                         if "crawled_pages" in stage:
                             stage_children["crawled_pages"] = stage["crawled_pages"]
@@ -441,12 +441,36 @@ class ContentRenderer:
                             **stage_children # Merge children
                         })
 
-
-
-
+                # Ensure references are displayed even if no "Search" stage was present
+                has_search_stage = any(s.get("name") == "Search" for s in processed_stages)
+                if not has_search_stage and (processed_refs or processed_image_refs):
+                    # Create a virtual Search stage
+                    virtual_search = {
+                        "name": "Search",
+                        "model": "DuckDuckGo", # Default assumption
+                        "model_short": "DuckDuckGo",
+                        "provider": "Reference",
+                        "icon_html": SEARCH_ICON,
+                        "time_str": "0.00s",
+                        "cost_str": "$0",
+                    }
+                    if processed_refs:
+                        virtual_search['references'] = processed_refs
+                    if processed_image_refs:
+                        virtual_search['image_references'] = processed_image_refs
+                    
+                    # Insert after Vision/Instruct (usually index 0 or 1), or at start
+                    insert_idx = 0
+                    if processed_stages and processed_stages[0]["name"] in ["Vision", "Instruct"]:
+                        insert_idx = 1
+                        if len(processed_stages) > 1 and processed_stages[1]["name"] == "Instruct":
+                            insert_idx = 2
+                    
+                    processed_stages.insert(insert_idx, virtual_search)
 
                 # 4. Stats Footer Logic
                 processed_stats = {}
+                stats_dict = {}
                 if stats:
                      # Assuming standard 'stats' dict structure, handle list if needed
                     if isinstance(stats, list):

entari_plugin_hyw/utils/prompts.py

@@ -3,8 +3,8 @@ VISION_SP = """# 你是一个专业的视觉转文字专家.
 # 核心任务
 - 智能分析图片内容, 转述成文本, 除此之外不要添加任何内容
 - 文字优先: 若包含清晰文字（文档、截图等）, 必须完整准确转录, 不要遗漏.
-- 视觉补充: 若无文字, 重点描述视觉内容（物体、场景、氛围）.
-- 用户要求: 根据用户消息中提示侧重转文本的偏向, 若无或无关联则不理会常规完成.
+- 视觉补充: 解释完文字后, 描述视觉内容总结（物体、场景、氛围）.
+- 用户要求: 根据用户消息中提示侧重转文本的偏向, 若无关联则不理会.
 
 ## 用户消息
 ```text
@@ -32,7 +32,7 @@ INTRUCT_SP = """# 你是一个专业的指导专家.
 {tools_desc}
 
 ## 你的回复
-调用工具后无需额外文本.
+调用工具后无需回复额外文本节省token.
 
 ## 用户消息
 ```
@@ -53,24 +53,36 @@ AGENT_SP = """# 你是一个 Agent 总控专家, 你需要理解用户意图,
 
 当前模式: {mode}, {mode_desc}
 
-## 最终回复格式要求
-- 直接输出 Markdown 正文.
 
+
+## 过程要求
 当不调用工具发送文本, 即会变成最终回复, 请遵守: 
+- 直接给出一篇报告, 无需回答用户消息
 - 语言: 简体中文, 百科式风格, 语言严谨不啰嗦.
-- 正文格式: 使用 Markdown格式, [hightlight, katex], 有大标题, 内容丰富突出重点.
+- 正文格式: 
+  - 使用 Markdown 格式, 支持 hightlight, katex
+  - 最开始给出`# `大标题, 不要有多余废话, 不要直接回答用户的提问.
+  - 内容丰富突出重点.
 - 工具引用: 
-  - 搜索摘要引用: 使用 `search:数字id` 如 `search:3`
-  - 页面内容引用: 使用 `page:数字id` 如 `page:5`
-  - 图片内容不引用
-  - 每个引用必须分开标注
+  > 重要: 所有正文内容必须基于实际信息, 保证百分百真实度
+  - 引用规则:
+    - 本次会话中存在对解决此问题有用的信息才加以引用, 不需要的消息可以不引用.
+    - 角标必须真实对应上下文中获取的信息, 同时对应 references 中的内容, 图片按顺序对应.
+  - 正文中的引用规则
+    - 搜索摘要引用: 使用如 [search:3][search:4]
+    - 页面内容引用: 使用如 [page:5][page:6]
+    - 图片引用: 使用如 [image:7][image:8]
+    - search 的意思是你使用 internal_web_search 获取的搜索摘要, 如果没有此工具相关信息则不引用
+    - page 的意思是你使用 crawl_page 获取的页面内容, 如果没有此工具相关信息则不引用
+    - image 的意思是你使用 internal_image_search 获取的图片, 图片按顺序摆放即可, 你无需显式引用
   - 在正文底部添加 references 代码块:
     - 用不到的条目不写, 没有专家给信息就不写.
     ```references
-    [1] [search] [文本描述](url)
-    [3] [search] [文本描述](url)
-    [5] [page] [页面标题](url)
-    [7] [page] [页面标题](url)
+    [2] [search] [文本描述](url)
+    [8] [search] [文本描述](url)
+    [1] [page] [页面标题](url)
+    [2] [page] [页面标题](url)
+    [1] [image] [来源](url)
     ```
 
 ## 用户消息
@@ -79,7 +91,6 @@ AGENT_SP = """# 你是一个 Agent 总控专家, 你需要理解用户意图,
 ```
 """
 
-# PS: agent 无搜索图片权限
 AGENT_SP_TOOLS_STANDARD_ADD = """
 你需要整合已有的信息, 提炼用户消息中的关键词, 进行最终回复.
 """
@@ -127,4 +138,3 @@ AGENT_SP_IMAGE_SEARCH_ADD = """
 ```
 - 每进行一次 internal_image_search, 挑选 1 张图像插入正文
 """
-

entari_plugin_hyw/utils/search.py

@@ -1,10 +1,27 @@
 import urllib.parse
+import asyncio
+import re
+import html
 from typing import List, Dict, Optional, Any
 from loguru import logger
 from crawl4ai import AsyncWebCrawler
 from crawl4ai.async_configs import CrawlerRunConfig
 from crawl4ai.cache_context import CacheMode
 
+# Optional imports for new strategies
+try:
+    import httpx
+except ImportError:
+    httpx = None
+
+try:
+    from ddgs import DDGS
+except ImportError:
+    try:
+        from duckduckgo_search import DDGS
+    except ImportError:
+        DDGS = None
+
 # Shared crawler instance to avoid repeated init
 _shared_crawler: Optional[AsyncWebCrawler] = None
 
@@ -28,13 +45,19 @@ async def close_shared_crawler():
 
 class SearchService:
     """
-    Crawl4AI-backed search & fetch service.
-    Uses the configured search engine results page (SERP) URL and parses links from the HTML.
+    Multi-strategy search & fetch service.
+    Supported providers: 'crawl4ai' (default), 'httpx', 'ddgs'.
     """
     def __init__(self, config: Any):
         self.config = config
         self._default_limit = getattr(config, "search_limit", 8)
         self._crawler: Optional[AsyncWebCrawler] = None
+        
+        # Configuration for retries/timeouts
+        self._search_timeout = getattr(config, "search_timeout", 10.0)
+        self._search_retries = getattr(config, "search_retries", 2)
+        self._provider = getattr(config, "search_provider", "crawl4ai")
+        logger.info(f"SearchService initialized: provider='{self._provider}', limit={self._default_limit}, timeout={self._search_timeout}s")
 
     def _build_search_url(self, query: str) -> str:
         encoded_query = urllib.parse.quote(query)
@@ -53,8 +76,211 @@ class SearchService:
         return f"{base}{sep}q={encoded_query}&iax=images&ia=images"
 
     async def search(self, query: str) -> List[Dict[str, str]]:
+        """
+        Dispatch search to the configured provider.
+        """
+        if not query:
+            return []
+
+        provider = self._provider.lower()
+        logger.info(f"SearchService: searching for '{query}' using provider='{provider}'")
+
+        if provider == "httpx":
+            return await self._search_httpx(query)
+        elif provider == "ddgs":
+            return await self._search_ddgs(query)
+        else:
+            # Default to crawl4ai for backward compatibility or explicit choice
+            return await self._search_crawl4ai(query)
+
+    async def _search_httpx(self, query: str) -> List[Dict[str, str]]:
+        """
+        Directly fetch https://lite.duckduckgo.com/lite/ via httpx and parse HTML.
+        Fast, no browser overhead.
+        """
+        if not httpx:
+            logger.error("SearchService: httpx not installed, fallback to crawl4ai")
+            return await self._search_crawl4ai(query)
+
+        url = self._build_search_url(query)
+        
+        results: List[Dict[str, str]] = []
+        try:
+            async with httpx.AsyncClient(timeout=self._search_timeout, follow_redirects=True) as client:
+                resp = await client.get(url, headers={
+                    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36"
+                })
+                resp.raise_for_status()
+                html_content = resp.text
+
+            # Regex parsing for DDG Lite
+            snippet_regex = re.compile(r'<td[^>]*>(.*?)</td>', re.DOTALL)
+            link_regex = re.compile(r'<a[^>]+href="([^"]+)"[^>]*>(.*?)</a>', re.DOTALL)
+            
+            raw_links = link_regex.findall(html_content)
+            
+            seen = set()
+            for href, text in raw_links:
+                if len(results) >= self._default_limit:
+                    break
+                    
+                # Clean href
+                if "duckduckgo.com" in href: 
+                    if "uddg=" in href:
+                         parsed = urllib.parse.parse_qs(urllib.parse.urlparse(href).query)
+                         href = parsed.get("uddg", [href])[0]
+                    else:
+                        continue
+                        
+                if not href.startswith("http"):
+                    continue
+                    
+                if href in seen:
+                    continue
+                seen.add(href)
+                
+                # Title clean
+                title = re.sub(r'<[^>]+>', '', text).strip()
+                title = html.unescape(title)
+                
+                results.append({
+                    "title": title,
+                    "url": href,
+                    "domain": urllib.parse.urlparse(href).hostname or "",
+                    "content": title 
+                })
+
+            if not results:
+                 logger.warning("SearchService(httpx): No results parsed via regex.")
+                 
+            return results
+
+        except Exception as e:
+            logger.error(f"SearchService(httpx) failed: {e}")
+            return []
+
+    async def _search_ddgs(self, query: str) -> List[Dict[str, str]]:
+        """
+        Use duckduckgo_search library (Sync DDGS).
+        Executes in thread pool to allow async usage.
+        Supports retries and timeouts.
+        """
+        if not DDGS:
+            logger.error("SearchService: duckduckgo_search not installed, fallback to crawl4ai")
+            return await self._search_crawl4ai(query)
+
+        def _do_sync_search():
+            """Sync search function to run in thread"""
+            results: List[Dict[str, str]] = []
+            final_exc = None
+            
+            for attempt in range(self._search_retries + 1):
+                try:
+                    with DDGS(timeout=self._search_timeout) as ddgs:
+                         # Use positional argument for query to be safe across versions
+                        ddgs_gen = ddgs.text(
+                            query,
+                            region='cn-zh',
+                            safesearch='moderate',
+                            max_results=self._default_limit,
+                            backend="duckduckgo",
+                        )
+                        
+                        if ddgs_gen:
+                            for r in ddgs_gen:
+                                results.append({
+                                    "title": r.get("title", ""),
+                                    "url": r.get("href", ""),
+                                    "domain": urllib.parse.urlparse(r.get("href", "")).hostname or "",
+                                    "content": r.get("body", "")
+                                })
+                                if len(results) >= self._default_limit:
+                                    break
+                    
+                    return results, None
+
+                except Exception as e:
+                    final_exc = e
+                    if attempt < self._search_retries:
+                         import time
+                         time.sleep(1)
+
+            return [], final_exc
+
+        # Run sync search in executor
+        try:
+            results, err = await asyncio.to_thread(_do_sync_search)
+            
+            if err:
+                 logger.warning(f"SearchService(ddgs) text search failed after retries: {err}")
+                 return []
+            
+            logger.info(f"SearchService(ddgs): Got {len(results)} text results")
+            return results
+
+        except Exception as e:
+            logger.error(f"SearchService(ddgs) thread execution failed: {e}")
+            return []
+
+    async def _search_ddgs_images(self, query: str) -> List[Dict[str, str]]:
+        """
+        Use duckduckgo_search library for images.
+        """
+        if not DDGS:
+            return []
+
+        def _do_sync_image_search():
+            results: List[Dict[str, str]] = []
+            final_exc = None
+            
+            for attempt in range(self._search_retries + 1):
+                try:
+                    with DDGS(timeout=self._search_timeout) as ddgs:
+                        ddgs_gen = ddgs.images(
+                            query,
+                            region='cn-zh',
+                            safesearch='moderate',
+                            max_results=self._default_limit,
+                        )
+                        
+                        if ddgs_gen:
+                            for r in ddgs_gen:
+                                # DDGS images returns: title, image, thumbnail, url, source, etc.
+                                # API might differ, adapt to standard format
+                                results.append({
+                                    "title": r.get("title", "Image"),
+                                    "url": r.get("image", "") or r.get("url", ""), # Full image URL
+                                    "thumbnail": r.get("thumbnail", ""),
+                                    "domain": r.get("source", "") or urllib.parse.urlparse(r.get("url", "")).hostname or "",
+                                })
+                                if len(results) >= self._default_limit:
+                                    break
+                    
+                    return results, None
+                except Exception as e:
+                    final_exc = e
+                    if attempt < self._search_retries:
+                         import time
+                         time.sleep(1)
+
+            return [], final_exc
+
+        try:
+            results, err = await asyncio.to_thread(_do_sync_image_search)
+            if err:
+                 logger.warning(f"SearchService(ddgs) image search failed: {err}")
+                 return []
+            
+            logger.info(f"SearchService(ddgs): Got {len(results)} image results")
+            return results
+        except Exception as e:
+             logger.error(f"SearchService(ddgs) image thread failed: {e}")
+             return []
+
+    async def _search_crawl4ai(self, query: str) -> List[Dict[str, str]]:
         """
         Crawl the configured SERP using Crawl4AI and return parsed results.
+        Original implementation.
         """
         if not query:
             return []
@@ -192,11 +418,15 @@ class SearchService:
 
     async def image_search(self, query: str) -> List[Dict[str, str]]:
         """
-        Image search via Crawl4AI media extraction.
+        Image search via Crawl4AI media extraction or DDGS.
         """
         if not query:
             return []
 
+        # If ddgs is selected, use it
+        if self._provider == "ddgs":
+             return await self._search_ddgs_images(query)
+
         url = self._build_image_url(query)
         logger.info(f"SearchService(Crawl4AI Image): fetching {url}")
 

entari_plugin_hyw-3.3.7.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: entari_plugin_hyw
+Version: 3.3.7
+Summary: Use large language models to interpret chat messages
+Author-email: kumoSleeping <zjr2992@outlook.com>
+License: MIT
+Project-URL: Homepage, https://github.com/kumoSleeping/entari-plugin-hyw
+Project-URL: Repository, https://github.com/kumoSleeping/entari-plugin-hyw
+Project-URL: Issue Tracker, https://github.com/kumoSleeping/entari-plugin-hyw/issues
+Keywords: entari,llm,ai,bot,chat
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: arclet-entari[full]>=0.16.5
+Requires-Dist: openai
+Requires-Dist: httpx
+Requires-Dist: markdown>=3.10
+Requires-Dist: crawl4ai>=0.7.8
+Requires-Dist: jinja2>=3.0
+Requires-Dist: ddgs>=9.10.0
+Provides-Extra: dev
+Requires-Dist: entari-plugin-server>=0.5.0; extra == "dev"
+Requires-Dist: satori-python-adapter-onebot11>=0.2.5; extra == "dev"
+
+
+# Entari Plugin HYW
+
+
+[![PyPI version](https://badge.fury.io/py/entari-plugin-hyw.svg)](https://badge.fury.io/py/entari-plugin-hyw)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Versions](https://img.shields.io/pypi/pyversions/entari-plugin-hyw.svg)](https://pypi.org/project/entari-plugin-hyw/)
+
+**Entari Plugin HYW** is an advanced agentic chat plugin for the [Entari](https://github.com/entari-org/entari) framework. It leverages Large Language Models (LLMs) to provide intelligent, context-aware, and multi-modal responses within instant messaging environments (OneBot 11, Satori).
+
+**Entari Plugin HYW** 是 Entari 框架的高级智能体聊天插件。它利用大语言模型（LLM）在即时通讯环境（OneBot 11, Satori）中提供智能、上下文感知和多模态的回复体验。
+
+The plugin implements a three-stage pipeline (**Vision**, **Instruct**, **Agent**) to autonomously decide when to search the web, crawl pages, or analyze images to answer user queries effectively.
+
+插件实现了三阶段流水线（**视觉**、**指令**、**代理**），能够自主决定何时搜索网络、抓取网页或分析图片，从而高效地回答用户问题。
+
+<img src="demo.jpg" width="300" />
+
+## Features / 功能特性
+
+- 📖 **Agentic Workflow (智能工作流)**  
+  Autonomous decision-making process to search, browse, and reason.  
+  具备自主决策能力，能够自动进行搜索、网页浏览和逻辑推理。
+
+- 🎑 **Multi-Modal Support (多模态支持)**  
+  Native support for image analysis using Vision Language Models (VLMs).  
+  原生支持图片分析，利用视觉语言模型（VLM）理解图像内容。
+
+- 🔍 **Web Search & Crawling (搜索与抓取)**  
+  Integrated **DuckDuckGo** and **Crawl4AI** for real-time information retrieval.  
+  集成 DuckDuckGo 搜索与 Crawl4AI 网页抓取，实时获取互联网信息。
+
+- 🎨 **Rich Rendering (富媒体渲染)**  
+  Responses are rendered as images containing Markdown, syntax-highlighted code, LaTeX math, and citation badges.  
+  回答将渲染为包含 Markdown、代码高亮、LaTeX 公式及引用角标的精美图片。
+
+- 🔌 **Protocol Support (多协议适配)**  
+  Deep integration with OneBot 11 and Satori protocols.  
+  深度适配 OneBot 11 和 Satori 协议，完美处理回复上下文与 JSON 卡片。
+
+## Installation / 安装
+
+```bash
+pip install entari-plugin-hyw
+```
+
+## Configuration / 配置
+
+Configure the plugin in your `entari.yml`.  
+在 `entari.yml` 中进行配置。
+
+### Minimal Configuration / 最小配置
+
+```yaml
+plugins:
+  entari_plugin_hyw:
+    # Trigger command / 触发指令
+    question_command: ".q"
+    
+    # Main Model (Required) / 主模型（必需）
+    model_name: "google/gemini-2.0-flash-exp"
+    api_key: "your-api-key-here"
+    base_url: "https://generativelanguage.googleapis.com/v1beta/openai/"
+```
+
+### Configuration Reference / 配置详解
+
+| Option (选项) | Type | Default | Description (说明) |
+| :--- | :--- | :--- | :--- |
+| **Basic** | | | |
+| `question_command` | `str` | `/q` | The command to trigger the bot. <br> 触发机器人的指令前缀。 |
+| `reaction` | `bool` | `true` | React with emoji on start(now only lagrange ob extension). <br> 收到指令时是否回应表情(目前只支持拉格兰ob扩展)。 |
+| `quote` | `bool` | `true` | Quote the user's message in reply. <br> 回复时是否引用原消息。 |
+| **Models** | | | |
+| `model_name` | `str` | *None* | **Required.** Main Agent model ID. <br> **必需。** 主代理模型 ID。 |
+| `api_key` | `str` | *None* | **Required.** API key. <br> **必需。** API 密钥。 |
+| `base_url` | `str` | `...` | OpenAI-compatible API base URL. <br> 兼容 OpenAI 的 API 地址。 |
+| `extra_body` | `dict` | `null` | Extra parameters (e.g. `reasoning_effort`). <br> 传递给 LLM 的额外参数。 |
+| **Specialized** | | | |
+| `vision_model_name`| `str` | *None* | Model for images. Defaults to `model_name`. <br> 处理图片的模型，默认同主模型。 |
+| `intruct_model_name`| `str` | *None* | Model for intent. Defaults to `model_name`. <br> 意图识别模型，默认同主模型。 |
+| **Tools** | | | |
+| `search_provider` | `str` | `ddgs`| `ddgs` (DuckDuckGo), `crawl4ai`, `httpx`. <br> 搜索后端提供商。 |
+| `search_limit` | `int` | `8` | Max search results. <br> 搜索结果数量限制。 |
+| `headless` | `bool` | `true` | Browser headless mode. <br> 浏览器无头模式。 |
+
+## Usage / 使用方法
+
+### Commands / 指令
+
+- **Text Query (文本问答)**
+  ```text
+  .q What's the latest news on Rust 1.83?
+  .q Rust 1.83 有什么新特性？
+  ```
+
+- **Image Analysis (图片分析)**
+  *(Send an image with command, or reply to an image)*  
+  *(发送带图片的指令，或回复一张图片)*
+  ```text
+  .q [Image] Explain this error.
+  .q [图片] 解释一下这个报错。
+  ```
+
+- **Follow-up (追问)**
+  *Reply to the bot's message to continue the conversation.*  
+  *直接回复机器人的消息即可进行连续对话。*
+
+-----
+
+## License
+
+This project is licensed under the MIT License.