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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echo-agent
-Version: 0.2.0
+Version: 0.2.1
 Summary: A modular AI agent framework with multi-channel support
 Author: Echo Agent contributors
 License: MIT
@@ -55,6 +55,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 +94,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 +217,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.1}/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.1}/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.1}/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.1}/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.1}/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,98 @@ 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", ""):
+    explicit_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 explicit_key:
+        # User explicitly configured image_gen — use their settings as-is
+        api_key = explicit_key
+    elif _is_openai_compatible_provider(provider):
+        # Fallback only for OpenAI-compatible providers — use unwrapped to get real key/base
+        real = _unwrap_provider(provider)
+        api_key = getattr(real, "api_key", "")
+        if not api_base:
+            api_base = getattr(real, "api_base", "")
+        # Reset default model so we infer from api_base
+        model = ""
+    else:
+        return
+
+    if not api_key:
         return
+
+    # Infer model from api_base if not explicitly set by user
+    if not model or (not explicit_key and model == "dall-e-3"):
+        model = _infer_image_model(api_base)
+
     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 = ""
+    default_backend = getattr(tts_cfg, "default_backend", "edge") if tts_cfg else "edge"
+    default_voice = getattr(tts_cfg, "default_voice", "") if tts_cfg else ""
+
+    # Fallback only for OpenAI-compatible providers
+    if not openai_key and _is_openai_compatible_provider(provider):
+        real = _unwrap_provider(provider)
+        openai_key = getattr(real, "api_key", "")
+        openai_base = getattr(real, "api_base", "")
+
+    # Infer TTS model from api_base
+    tts_model = _infer_tts_model(openai_base)
+
+    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,
+    ))

{echo_agent-0.2.0 → echo_agent-0.2.1}/echo_agent/agent/tools/tts.py

@@ -23,14 +23,18 @@ class TTSTool(Tool):
     }
     timeout_seconds = 60
 
-    def __init__(self, workspace: str, openai_api_key: str = ""):
+    def __init__(self, workspace: str, openai_api_key: str = "", openai_api_base: str = "", tts_model: str = "tts-1", default_backend: str = "", default_voice: str = ""):
         self._workspace = Path(workspace)
         self._openai_key = openai_api_key
+        self._openai_base = (openai_api_base or "https://api.openai.com/v1").rstrip("/")
+        self._tts_model = tts_model
+        self._default_backend = default_backend or "edge"
+        self._default_voice = default_voice
 
     async def execute(self, params: dict[str, Any], ctx: ToolExecutionContext | None = None) -> ToolResult:
         text = params["text"]
-        backend = params.get("backend", "edge" if not self._openai_key else "openai")
-        voice = params.get("voice", "")
+        backend = params.get("backend", self._default_backend)
+        voice = params.get("voice", self._default_voice or "")
         output_path = params.get("output_path", "")
 
         if not output_path:
@@ -59,9 +63,9 @@ class TTSTool(Tool):
             return ToolResult(success=False, error="OpenAI API key not configured for TTS")
 
         import aiohttp
-        url = "https://api.openai.com/v1/audio/speech"
+        url = f"{self._openai_base}/audio/speech"
         headers = {"Authorization": f"Bearer {self._openai_key}", "Content-Type": "application/json"}
-        body = {"model": "tts-1", "input": text, "voice": voice, "response_format": "mp3"}
+        body = {"model": self._tts_model, "input": text, "voice": voice, "response_format": "mp3"}
 
         try:
             async with aiohttp.ClientSession() as session:

{echo_agent-0.2.0 → echo_agent-0.2.1}/echo_agent/channels/base.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import hashlib
 from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -112,11 +114,16 @@ class BaseChannel(ABC):
         content_blocks = [ContentBlock(type=ContentType.TEXT, text=text)]
         for item in (media or []):
             name = item.get("name", "")
+            meta: dict[str, Any] = {}
+            if name:
+                meta["name"] = name
+            if item.get("aes_key"):
+                meta["aes_key"] = item["aes_key"]
             content_blocks.append(ContentBlock(
                 type=ContentType(item.get("type", "file")),
                 url=item.get("url", ""),
                 mime_type=item.get("mime_type", ""),
-                metadata={"name": name} if name else {},
+                metadata=meta,
             ))
 
         return InboundEvent(
@@ -173,6 +180,40 @@ class BaseChannel(ABC):
     def is_running(self) -> bool:
         return self._running
 
+    _media_cache_root: Path | None = None
+
+    async def _resolve_media_to_cache(
+        self,
+        source_id: str,
+        platform: str,
+        fetch: Callable[[], Awaitable[bytes]],
+        suffix: str = ".jpg",
+    ) -> str | None:
+        """Download media via a channel-provided *fetch* callback and cache locally.
+
+        Returns the absolute path string on success, ``None`` on any failure.
+        The caller decides how to degrade (skip the image, insert a placeholder, etc.).
+        """
+        root = self._media_cache_root or (Path.home() / ".echo-agent" / "data" / "media_cache")
+        cache_dir = root / platform
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        url_hash = hashlib.sha256(source_id.encode()).hexdigest()[:16]
+        target = cache_dir / f"{url_hash}{suffix}"
+        if target.exists():
+            target.touch()
+            return str(target)
+        try:
+            data = await fetch()
+            if not data:
+                logger.warning("Empty media response for {} on {}", source_id[:60], platform)
+                return None
+            target.write_bytes(data)
+            logger.debug("Cached channel media: {} → {}", source_id[:60], target.name)
+            return str(target)
+        except Exception as e:
+            logger.warning("Channel media download failed for {} on {}: {}", source_id[:60], platform, e)
+            return None
+
     async def transcribe_audio(self, file_path: str | Path) -> str:
         """Transcribe audio file via Groq Whisper API."""
         api_key = self.transcription_api_key

{echo_agent-0.2.0 → echo_agent-0.2.1}/echo_agent/channels/feishu.py

@@ -157,7 +157,11 @@ class FeishuChannel(BaseChannel):
                 content = json.loads(message.get("content", "{}"))
                 image_key = content.get("image_key", "")
                 if image_key:
-                    media.append({"type": "image", "url": image_key})
+                    local_path = await self._download_feishu_image(image_key, msg_id)
+                    if local_path:
+                        media.append({"type": "image", "url": local_path})
+                    else:
+                        logger.warning("Feishu image download failed, skipping: {}", image_key[:30])
             except json.JSONDecodeError:
                 pass
 
@@ -188,6 +192,24 @@ class FeishuChannel(BaseChannel):
             metadata={"chat_type": event.get("chat_type", ""), "receive_id_type": "chat_id"},
         )
 
+    async def _download_feishu_image(self, image_key: str, msg_id: str) -> str | None:
+        """Download a Feishu image by image_key via the message resource API."""
+        async def fetch() -> bytes:
+            await self._ensure_tenant_token()
+            url = (
+                f"{_API_BASE}/im/v1/messages/{msg_id}"
+                f"/resources/{image_key}?type=image"
+            )
+            headers = {"Authorization": f"Bearer {self._tenant_token}"}
+            if not self._session:
+                raise RuntimeError("no session")
+            async with self._session.get(url, headers=headers) as resp:
+                if resp.status != 200:
+                    raise RuntimeError(f"Feishu resource download failed ({resp.status})")
+                return await resp.read()
+
+        return await self._resolve_media_to_cache(image_key, "feishu", fetch, suffix=".jpg")
+
     # ── Encryption ───────────────────────────────────────────────────────────
 
     def _decrypt(self, encrypted: str) -> dict[str, Any] | None: