echo-agent 0.2.0__tar.gz → 0.2.2__tar.gz

{echo_agent-0.2.0 → echo_agent-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echo-agent
-Version: 0.2.0
+Version: 0.2.2
 Summary: A modular AI agent framework with multi-channel support
 Author: Echo Agent contributors
 License: MIT
@@ -25,6 +25,7 @@ Requires-Dist: anthropic>=0.40; extra == 'all'
 Requires-Dist: boto3>=1.34; extra == 'all'
 Requires-Dist: cryptography>=41.0; extra == 'all'
 Requires-Dist: faiss-cpu>=1.7; extra == 'all'
+Requires-Dist: fal-client>=0.5; extra == 'all'
 Requires-Dist: google-generativeai>=0.8; extra == 'all'
 Requires-Dist: openai>=1.30; extra == 'all'
 Requires-Dist: psutil>=5.9; extra == 'all'
@@ -45,6 +46,8 @@ Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: fal
+Requires-Dist: fal-client>=0.5; extra == 'fal'
 Provides-Extra: gemini
 Requires-Dist: google-generativeai>=0.8; extra == 'gemini'
 Provides-Extra: openai
@@ -55,6 +58,24 @@ Requires-Dist: opentelemetry-exporter-otlp>=1.20; extra == 'otel'
 Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
 Provides-Extra: process
 Requires-Dist: psutil>=5.9; extra == 'process'
+Provides-Extra: skills
+Requires-Dist: caldav>=1.3; extra == 'skills'
+Requires-Dist: croniter>=1.4; extra == 'skills'
+Requires-Dist: duckduckgo-search>=7.0; extra == 'skills'
+Requires-Dist: edge-tts>=7.0; extra == 'skills'
+Requires-Dist: faster-whisper>=1.0; extra == 'skills'
+Requires-Dist: feedparser>=6.0; extra == 'skills'
+Requires-Dist: icalendar>=5.0; extra == 'skills'
+Requires-Dist: markdown>=3.6; extra == 'skills'
+Requires-Dist: openpyxl>=3.1; extra == 'skills'
+Requires-Dist: pillow>=10.0; extra == 'skills'
+Requires-Dist: psutil>=5.9; extra == 'skills'
+Requires-Dist: pymupdf>=1.24; extra == 'skills'
+Requires-Dist: pytesseract>=0.3; extra == 'skills'
+Requires-Dist: python-docx>=1.1; extra == 'skills'
+Requires-Dist: python-pptx>=1.0; extra == 'skills'
+Requires-Dist: pyyaml>=6.0; extra == 'skills'
+Requires-Dist: trafilatura>=2.0; extra == 'skills'
 Provides-Extra: tokenizers
 Requires-Dist: tiktoken>=0.7; extra == 'tokenizers'
 Provides-Extra: vector
@@ -76,9 +97,6 @@ Description-Content-Type: text/markdown
 <br/>
 
 [![PyPI](https://img.shields.io/pypi/v/echo-agent)](https://pypi.org/project/echo-agent/)
-[![Python](https://img.shields.io/pypi/pyversions/echo-agent)](https://pypi.org/project/echo-agent/)
-[![CI](https://github.com/fuyuxiang/echo-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/fuyuxiang/echo-agent/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Downloads](https://static.pepy.tech/badge/echo-agent)](https://pepy.tech/project/echo-agent)
 [![GitHub stars](https://img.shields.io/github/stars/fuyuxiang/echo-agent?style=social)](https://github.com/fuyuxiang/echo-agent)
 
@@ -202,9 +220,7 @@ PR 前请确保 lint 和测试通过（CI 会在 PR 上自动运行同样的检
 **参与方向：** 通道适配器 · 内置工具 · MCP 集成 · 技能示例 · 评测数据集 · 文档完善 · 部署模板
 
 **社区：**
-- [GitHub Discussions](https://github.com/fuyuxiang/echo-agent/discussions) — 设计讨论、用法咨询
-- [GitHub Issues](https://github.com/fuyuxiang/echo-agent/issues) — Bug 与新特性
-- [QQ 群 47572014](https://qm.qq.com/q/JWOPDBNssw)
+- QQ群：[47572014](https://qm.qq.com/q/JWOPDBNssw)
 
 ---
 

{echo_agent-0.2.0 → echo_agent-0.2.2}/README.md

@@ -11,9 +11,6 @@
 <br/>
 
 [![PyPI](https://img.shields.io/pypi/v/echo-agent)](https://pypi.org/project/echo-agent/)
-[![Python](https://img.shields.io/pypi/pyversions/echo-agent)](https://pypi.org/project/echo-agent/)
-[![CI](https://github.com/fuyuxiang/echo-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/fuyuxiang/echo-agent/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Downloads](https://static.pepy.tech/badge/echo-agent)](https://pepy.tech/project/echo-agent)
 [![GitHub stars](https://img.shields.io/github/stars/fuyuxiang/echo-agent?style=social)](https://github.com/fuyuxiang/echo-agent)
 
@@ -137,9 +134,7 @@ PR 前请确保 lint 和测试通过（CI 会在 PR 上自动运行同样的检
 **参与方向：** 通道适配器 · 内置工具 · MCP 集成 · 技能示例 · 评测数据集 · 文档完善 · 部署模板
 
 **社区：**
-- [GitHub Discussions](https://github.com/fuyuxiang/echo-agent/discussions) — 设计讨论、用法咨询
-- [GitHub Issues](https://github.com/fuyuxiang/echo-agent/issues) — Bug 与新特性
-- [QQ 群 47572014](https://qm.qq.com/q/JWOPDBNssw)
+- QQ群：[47572014](https://qm.qq.com/q/JWOPDBNssw)
 
 ---
 

{echo_agent-0.2.0 → echo_agent-0.2.2}/echo_agent/agent/compression/compressor.py

@@ -87,6 +87,14 @@ class ConversationCompressor(ContextEngine):
         tokens_before = self.estimate_tokens(messages)
         working = list(messages)
 
+        # Phase 0: Strip media_refs — they are lightweight session pointers
+        # that the summarizer/boundary stages should not see.  The text
+        # content stays, so the LLM summary naturally captures "user sent
+        # an image" without carrying the ref metadata forward.
+        for msg in working:
+            if "media_refs" in msg:
+                del msg["media_refs"]
+
         # Phase 1: Tool output pruning
         pruned_count = 0
         if self._pruner:

{echo_agent-0.2.0 → echo_agent-0.2.2}/echo_agent/agent/context.py

@@ -211,35 +211,59 @@ class ContextBuilder:
         expiry-prone CDN URLs; on failure we fall back to the original URL so the
         message is never dropped. Non-image attachments (file/video/audio) are not
         downloaded — the model cannot consume their bytes, so we only reference them
-        by name/URL and skip the wasted I/O."""
+        by name/URL and skip the wasted I/O.
+
+        If the media carries an AES key (WeChat CDN encryption), the downloaded bytes
+        are decrypted in-place before being handed to the model."""
         resolved: list[dict[str, str]] = []
-        download_targets: list[tuple[int, str]] = []
+        download_targets: list[tuple[int, str, str]] = []
         for idx, block in enumerate(items):
             btype = getattr(block.type, "value", str(block.type))
             url = block.url
+            meta = getattr(block, "metadata", None) or {}
+            aes_key = meta.get("aes_key", "")
             entry = {
                 "type": btype,
                 "url": url,
                 "mime_type": getattr(block, "mime_type", "") or "",
                 "name": self._block_name(block),
+                "aes_key": aes_key,
+                "original_url": url,
             }
             resolved.append(entry)
             if btype == "image" and url.startswith(("http://", "https://")):
-                download_targets.append((idx, url))
+                download_targets.append((idx, url, aes_key))
 
         if download_targets:
             cache = self._get_media_cache()
             results = await asyncio.gather(
-                *(cache.download(url, channel or "inbound") for _, url in download_targets),
+                *(cache.download(url, channel or "inbound") for _, url, _ in download_targets),
                 return_exceptions=True,
             )
-            for (idx, url), result in zip(download_targets, results):
+            for (idx, url, aes_key), result in zip(download_targets, results):
                 if isinstance(result, Exception):
                     logger.warning("Inbound media download failed, using original URL: {}", result)
                 elif result:
+                    if aes_key:
+                        result = self._decrypt_media_file(result, aes_key)
                     resolved[idx]["url"] = str(result)
         return resolved
 
+    @staticmethod
+    def _decrypt_media_file(path: Path, aes_key_b64: str) -> Path:
+        """Decrypt an AES-128-ECB encrypted media file in-place."""
+        from echo_agent.channels.weixin import _aes128_ecb_decrypt, _parse_aes_key
+
+        try:
+            key = _parse_aes_key(aes_key_b64)
+            ciphertext = path.read_bytes()
+            plaintext = _aes128_ecb_decrypt(ciphertext, key)
+            path.write_bytes(plaintext)
+            logger.debug("Decrypted media file: {}", path.name)
+        except Exception as e:
+            logger.warning("Media decryption failed for {}: {}", path.name, e)
+        return path
+
     def build_system_prompt(
         self,
         memory_context: str = "",
@@ -287,6 +311,9 @@ class ContextBuilder:
         chat_id: str | None = None,
         system_prompt: str = "",
         retrieval_context: str = "",
+        history_image_ttl_minutes: int = 30,
+        history_image_limit: int = 4,
+        history_image_skip_if_current: bool = True,
     ) -> list[dict[str, Any]]:
         runtime = self._runtime_context(channel, chat_id)
         user_content = current_message
@@ -299,9 +326,18 @@ class ContextBuilder:
         messages: list[dict[str, Any]] = []
         if system_prompt:
             messages.append({"role": "system", "content": system_prompt})
-        messages.extend(history)
 
         normalized = self._normalize_media(media)
+        has_current_image = any(item.get("type") == "image" for item in normalized)
+
+        enriched_history = self._inject_history_images(
+            history,
+            ttl_minutes=history_image_ttl_minutes,
+            limit=history_image_limit,
+            skip=has_current_image and history_image_skip_if_current,
+        )
+        messages.extend(enriched_history)
+
         if normalized:
             content_parts: list[dict[str, Any]] = [{"type": "text", "text": merged_user}]
             file_notes: list[str] = []
@@ -316,12 +352,8 @@ class ContextBuilder:
                     if image_url:
                         content_parts.append({"type": "image_url", "image_url": {"url": image_url}})
                     else:
-                        # 图片本地缓存已失效/不可读：不要静默丢弃，降级为文本引用，
-                        # 让模型至少知道用户发过一张图。
                         file_notes.append(f"[附件] 类型=image 名称={name} 路径={url}")
                 else:
-                    # 非图片附件（文件/视频/音频）模型无法直接看图，改为文本引用，
-                    # 给出类型、名称和本地路径，避免被误当成图片塞进 image_url。
                     file_notes.append(f"[附件] 类型={mtype} 名称={name} 路径={url}")
             if file_notes:
                 content_parts[0]["text"] = merged_user + "\n\n" + "\n".join(file_notes)
@@ -330,6 +362,113 @@ class ContextBuilder:
             messages.append({"role": "user", "content": merged_user})
         return messages
 
+    def _inject_history_images(
+        self,
+        history: list[dict[str, Any]],
+        ttl_minutes: int = 30,
+        limit: int = 4,
+        skip: bool = False,
+    ) -> list[dict[str, Any]]:
+        """Enrich history messages that carry ``media_refs`` with image content.
+
+        Returns a shallow copy of *history* where qualifying user messages have
+        their ``content`` replaced by a multimodal list.  The original dicts are
+        not mutated.  When a cached file is missing, attempts to re-download from
+        the original URL (and decrypt if an AES key is stored).  Expired or
+        unrecoverable images degrade to a text placeholder."""
+        if skip or limit <= 0:
+            if skip:
+                logger.debug("Skipping history image injection (current turn has images)")
+            return history
+
+        import time
+
+        now = time.time()
+        cutoff = now - ttl_minutes * 60
+
+        collected: list[tuple[int, list[dict[str, Any]]]] = []
+        total = 0
+        for idx in range(len(history) - 1, -1, -1):
+            if total >= limit:
+                break
+            msg = history[idx]
+            if msg.get("role") != "user":
+                continue
+            refs = msg.get("media_refs")
+            if not refs:
+                continue
+            parts: list[dict[str, Any]] = []
+            for ref in refs:
+                ts = ref.get("timestamp", 0)
+                if ts < cutoff:
+                    age_min = (now - ts) / 60
+                    logger.debug(
+                        "History image expired ({:.0f}m old, TTL={}m): {}",
+                        age_min, ttl_minutes, ref.get("cache_path", "?"),
+                    )
+                    continue
+                data_url = self._resolve_history_image(ref)
+                age_min = int((now - ts) / 60)
+                if data_url:
+                    parts.append({"type": "image_url", "image_url": {"url": data_url}})
+                    parts.append({
+                        "type": "text",
+                        "text": f"[历史图片，来自{age_min}分钟前]",
+                    })
+                    logger.debug("Injected history image ({} min old)", age_min)
+                else:
+                    parts.append({"type": "text", "text": "[该图片已过期，无法显示]"})
+                    logger.info(
+                        "History image unavailable (cache={}, url={})",
+                        ref.get("cache_path", ""), ref.get("original_url", ""),
+                    )
+                total += 1
+                if total >= limit:
+                    break
+            if parts:
+                collected.append((idx, parts))
+
+        if not collected:
+            return history
+
+        logger.debug("Injecting {} history image(s) into {} message(s)", total, len(collected))
+        enriched = list(history)
+        for idx, image_parts in collected:
+            orig = enriched[idx]
+            text = orig.get("content", "")
+            if isinstance(text, list):
+                continue
+            enriched[idx] = {
+                **orig,
+                "content": [{"type": "text", "text": text}] + image_parts,
+            }
+        return enriched
+
+    def _resolve_history_image(self, ref: dict[str, Any]) -> str | None:
+        """Try to load a history image: cache first, then fallback re-download."""
+        cache_path = ref.get("cache_path", "")
+        if cache_path:
+            data_url = self._local_image_to_data_url(cache_path)
+            if data_url:
+                return data_url
+
+        original_url = ref.get("original_url", "")
+        if not original_url:
+            return None
+
+        cache = self._get_media_cache()
+        cached = cache.get_cached(original_url)
+        if cached and cached.exists():
+            aes_key = ref.get("aes_key", "")
+            if aes_key:
+                self._decrypt_media_file(cached, aes_key)
+            data_url = self._local_image_to_data_url(str(cached))
+            if data_url:
+                logger.debug("Recovered history image from cache lookup: {}", cached.name)
+                return data_url
+
+        return None
+
     @staticmethod
     def _normalize_media(media: Any) -> list[dict[str, str]]:
         """Accept either a list of bare URL strings (legacy) or type-aware dicts."""

{echo_agent-0.2.0 → echo_agent-0.2.2}/echo_agent/agent/pipeline/context_stage.py

@@ -127,7 +127,18 @@ class ContextStage:
                 session.messages = session.messages[:session.last_consolidated] + result.messages
                 await self._sessions.save(session)
 
-        session.add_message("user", event.text)
+        media_items = event.media_items
+        resolved_media = (
+            await self._context_builder.resolve_inbound_media(media_items, event.channel)
+            if media_items
+            else None
+        )
+
+        media_refs = self._build_media_refs(resolved_media) if resolved_media else None
+        if media_refs:
+            session.add_message("user", event.text, media_refs=media_refs)
+        else:
+            session.add_message("user", event.text)
 
         retrieval_parts: list[str] = []
         if self._config.memory.enabled:
@@ -159,13 +170,7 @@ class ContextStage:
 
         retrieval = "\n\n".join(retrieval_parts)
 
-        media_items = event.media_items
-        resolved_media = (
-            await self._context_builder.resolve_inbound_media(media_items, event.channel)
-            if media_items
-            else None
-        )
-
+        session_cfg = self._config.session
         messages = self._context_builder.build_messages(
             history=history,
             current_message=event.text,
@@ -174,6 +179,9 @@ class ContextStage:
             chat_id=event.chat_id,
             system_prompt=system_prompt,
             retrieval_context=retrieval,
+            history_image_ttl_minutes=session_cfg.history_image_ttl_minutes,
+            history_image_limit=session_cfg.history_image_limit,
+            history_image_skip_if_current=session_cfg.history_image_skip_if_current,
         )
 
         # tool_defs already computed above for capability derivation.
@@ -192,9 +200,13 @@ class ContextStage:
                 # information — injecting it just burns prompt tokens.
                 if execution_plan and len(execution_plan.steps) > 1:
                     plan_context = execution_plan.to_prompt()
-                    messages[-1]["content"] = (
-                        messages[-1]["content"] + f"\n\n[Plan]\n{plan_context}"
-                    )
+                    last_content = messages[-1]["content"]
+                    if isinstance(last_content, list):
+                        last_content[0]["text"] += f"\n\n[Plan]\n{plan_context}"
+                    else:
+                        messages[-1]["content"] = (
+                            last_content + f"\n\n[Plan]\n{plan_context}"
+                        )
             except Exception as e:
                 logger.debug("Planning failed, proceeding without plan: {}", e)
 
@@ -213,6 +225,31 @@ class ContextStage:
             stream_publisher=stream_publisher,
         )
 
+    @staticmethod
+    def _build_media_refs(resolved_media: list[dict[str, str]]) -> list[dict[str, Any]]:
+        """Extract lightweight image references from resolved media for session storage."""
+        import time
+
+        from echo_agent.session.media_ref import MediaRef
+
+        refs: list[dict[str, Any]] = []
+        now = time.time()
+        for item in resolved_media:
+            if item.get("type") != "image":
+                continue
+            url = item.get("url", "")
+            if not url:
+                continue
+            is_local = not url.startswith(("http://", "https://", "data:"))
+            refs.append(MediaRef(
+                cache_path=url if is_local else "",
+                original_url=item.get("original_url", "") or (url if not is_local else ""),
+                mime_type=item.get("mime_type", ""),
+                timestamp=now,
+                aes_key=item.get("aes_key", ""),
+            ).to_dict())
+        return refs
+
     def _infer_task_type(self, text: str) -> str:
         lower = text.lower()
         for task_type, markers in self._TASK_MARKERS.items():

{echo_agent-0.2.0 → echo_agent-0.2.2}/echo_agent/agent/tools/__init__.py

@@ -115,8 +115,8 @@ def discover_tools(
         from echo_agent.agent.tools.vision import VisionTool
         tools.append(VisionTool(provider=provider, workspace=ws))
 
-    _try_register_image_gen(tools, config)
-    _try_register_tts(tools, config, ws)
+    _try_register_image_gen(tools, config, provider)
+    _try_register_tts(tools, config, ws, provider)
 
     if session_manager:
         from echo_agent.agent.tools.session_search import SessionSearchTool
@@ -148,20 +148,115 @@ def discover_tools(
     return tools
 
 
-def _try_register_image_gen(tools: list[Tool], config: Config) -> None:
+def _unwrap_provider(provider: LLMProvider | None) -> LLMProvider | None:
+    """Unwrap decorator layers (RateLimitedProvider, _PooledProvider) to get the real provider."""
+    if provider is None:
+        return None
+    inner = provider
+    while hasattr(inner, "_inner"):
+        inner = inner._inner
+    return inner
+
+
+def _is_openai_compatible_provider(provider: LLMProvider | None) -> bool:
+    """Check if provider uses the OpenAI-compatible API (images/audio endpoints available)."""
+    from echo_agent.models.providers.openai_provider import OpenAIProvider
+    inner = _unwrap_provider(provider)
+    return isinstance(inner, OpenAIProvider)
+
+
+def _infer_image_model(api_base: str) -> str:
+    """Infer image generation model name from API base URL."""
+    base = (api_base or "").lower()
+    if "minimax" in base:
+        return "image-01"
+    if "dashscope" in base or "aliyun" in base:
+        return "wanx-v1"
+    if "zhipu" in base or "bigmodel" in base:
+        return "cogview-3"
+    return "dall-e-3"
+
+
+def _infer_tts_model(api_base: str) -> str:
+    """Infer TTS model name from API base URL."""
+    base = (api_base or "").lower()
+    if "minimax" in base:
+        return "speech-02"
+    if "dashscope" in base or "aliyun" in base:
+        return "cosyvoice-v1"
+    return "tts-1"
+
+
+def _try_register_image_gen(tools: list[Tool], config: Config, provider: LLMProvider | None = None) -> None:
     ig = getattr(config.tools, "image_gen", None)
-    if not ig or not getattr(ig, "api_key", ""):
+    backend = getattr(ig, "backend", "openai") if ig else "openai"
+
+    if backend == "fal":
+        fal_key = getattr(ig, "fal_key", "") if ig else ""
+        fal_model = getattr(ig, "fal_model", "") if ig else ""
+        if not fal_key:
+            logger.info(
+                "image_generate tool not registered: no fal_key configured. "
+                "Set tools.image_gen.fal_key and tools.image_gen.fal_model in config to enable."
+            )
+            return
+        from echo_agent.agent.tools.image_gen_fal import FalImageGenTool, FAL_MODELS
+        if fal_model and fal_model not in FAL_MODELS:
+            logger.warning(
+                "image_generate: configured fal_model '{}' is not in the built-in catalog. "
+                "Supported: {}. The tool will error at execution time.",
+                fal_model, ", ".join(sorted(FAL_MODELS.keys())),
+            )
+        tools.append(FalImageGenTool(fal_key=fal_key, model=fal_model))
         return
+
+    api_key = getattr(ig, "api_key", "") if ig else ""
+    api_base = getattr(ig, "api_base", "") if ig else ""
+    model = getattr(ig, "model", "") if ig else ""
+
+    if not api_key:
+        if _is_openai_compatible_provider(provider):
+            logger.info(
+                "image_generate tool not registered: no explicit image_gen.api_key configured. "
+                "Set tools.image_gen.api_key, tools.image_gen.api_base, and tools.image_gen.model in config to enable."
+            )
+        return
+
+    if not model:
+        model = _infer_image_model(api_base)
+        logger.debug("image_generate: model not configured, inferred '{}' from api_base", model)
+
     from echo_agent.agent.tools.image_gen import ImageGenTool
-    tools.append(ImageGenTool(
-        api_key=ig.api_key,
-        api_base=getattr(ig, "api_base", ""),
-        model=getattr(ig, "model", "dall-e-3"),
-    ))
+    tools.append(ImageGenTool(api_key=api_key, api_base=api_base, model=model))
 
 
-def _try_register_tts(tools: list[Tool], config: Config, ws: str) -> None:
+def _try_register_tts(tools: list[Tool], config: Config, ws: str, provider: LLMProvider | None = None) -> None:
     from echo_agent.agent.tools.tts import TTSTool
     tts_cfg = getattr(config.tools, "tts", None)
     openai_key = getattr(tts_cfg, "openai_api_key", "") if tts_cfg else ""
-    tools.append(TTSTool(workspace=ws, openai_api_key=openai_key))
+    openai_base = getattr(tts_cfg, "openai_api_base", "") if tts_cfg else ""
+    tts_model = getattr(tts_cfg, "model", "") if tts_cfg else ""
+    default_backend = getattr(tts_cfg, "default_backend", "edge") if tts_cfg else "edge"
+    default_voice = getattr(tts_cfg, "default_voice", "") if tts_cfg else ""
+
+    if not openai_key and _is_openai_compatible_provider(provider):
+        logger.info(
+            "TTS openai backend not available: no explicit tts.openai_api_key configured. "
+            "Set tools.tts.openai_api_key, tools.tts.openai_api_base, and tools.tts.model in config to enable. "
+            "edge backend remains available without configuration."
+        )
+
+    if not tts_model and openai_key:
+        tts_model = _infer_tts_model(openai_base)
+        logger.debug("TTS: model not configured, inferred '{}' from openai_api_base", tts_model)
+    if not tts_model:
+        tts_model = "tts-1"
+
+    tools.append(TTSTool(
+        workspace=ws,
+        openai_api_key=openai_key,
+        openai_api_base=openai_base,
+        tts_model=tts_model,
+        default_backend=default_backend,
+        default_voice=default_voice,
+    ))