feat(acli): add built-in view_image tool so the agent can analyze images

The only multimodal entry point was user-input @path expansion, so
after scrape_web_screenshot/camera_capture the model could not see the
saved image and sometimes echoed the user-facing @path hint verbatim,
ending the turn prematurely. view_image routes a local image to a
vision-capable model on the active provider (active model if vision-
capable, else the provider's declared vision model, else a per-
provider fallback), and screenshot/camera hints now point at it.

Author: zhansheng.lzs

dashscope/acli/cli/repl.py

@@ -195,6 +195,10 @@ async def _run_loop(config: Config):
         get_mcp_clients_fn=lambda: _mcp_clients,
     )
 
+    from dashscope.acli.tools.vision import register_vision_tools
+
+    register_vision_tools(config, get_provider_fn=get_provider)
+
     from dashscope.acli.tools.evolution import register_evolution_tools
 
     register_evolution_tools(get_agent=lambda: agent)

dashscope/acli/cli/runners.py

@@ -358,6 +358,10 @@ def _run_tui_mode(config: Config):
         get_mcp_clients_fn=lambda: _mcp_clients,
     )
 
+    from dashscope.acli.tools.vision import register_vision_tools
+
+    register_vision_tools(config, get_provider_fn=get_provider)
+
     from dashscope.acli.tools.evolution import register_evolution_tools
 
     register_evolution_tools(get_agent=lambda: agent)

dashscope/acli/tools/browser.py

@@ -488,6 +488,7 @@ async def scrape_web_screenshot(
         return f"Error: screenshot failed — {e}"
 
     return (
-        f"Screenshot saved to {output_path}. Reference it with @path "
-        f"to send the image to a vision model for analysis."
+        f"Screenshot saved to {output_path}. Call the view_image tool "
+        f"with this path to analyze it (the user can also attach it "
+        f"via @path)."
     )

dashscope/acli/tools/camera.py

@@ -11,8 +11,8 @@
     name="camera_capture",
     description=(
         "Take a photo with the webcam and save it to the given path. "
-        "The user can then reference it via @path to send it to a "
-        "vision model for analysis."
+        "The photo can then be analyzed with the view_image tool (the "
+        "user can also attach it via @path)."
     ),
     permission=PermissionLevel.CONFIRM,
 )

dashscope/acli/tools/registry.py

@@ -368,6 +368,7 @@ def to_schema_list(self, user_input: str = "") -> list[dict]:
                 "switch_provider",
                 "capability_enable",
                 "capability_disable",
+                "view_image",
             ],
         )
         include_tools.update(["mcp_connect", "mcp_disconnect"])

dashscope/acli/tools/vision.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""Built-in vision tool — let the agent analyze local images itself.
+
+Previously the only multimodal entry point was user-input ``@path``
+expansion, so after ``scrape_web_screenshot`` / ``camera_capture`` the
+model could not see the saved image and sometimes echoed the
+user-facing ``@path`` hint verbatim, ending the turn prematurely.
+``view_image`` closes that gap by routing the image to a
+vision-capable model on the active provider.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from dashscope.acli.config import Config, is_vision_model
+from dashscope.acli.tools.registry import (
+    PermissionLevel,
+    ToolDefinition,
+    registry,
+)
+
+_FALLBACK_VISION_MODELS = {
+    "tongyi": "qwen-vl-max",
+    "openai": "gpt-4o",
+    "anthropic": "claude-sonnet-4-20250514",
+}
+
+
+def pick_vision_model(config: Config) -> str:
+    """Choose a vision-capable model on the active provider.
+
+    Preference: the active model when it accepts images, then the first
+    vision model declared on the provider's extension block, then a
+    per-provider built-in fallback.
+    """
+    if is_vision_model(config.model):
+        return config.model
+
+    from dashscope.acli.extensions import find_provider
+
+    ext = find_provider(config.provider)
+    if ext and ext.vision_models:
+        return ext.vision_models[0]
+    return _FALLBACK_VISION_MODELS.get(config.provider, "qwen-vl-max")
+
+
+def register_vision_tools(config: Config, *, get_provider_fn: Callable):
+    """Register ``view_image``; called once after agent construction."""
+
+    async def view_image(
+        image_path: str,
+        question: str = (
+            "Describe this image in detail. If it contains text or "
+            "tables, transcribe them verbatim."
+        ),
+    ) -> str:
+        from dashscope.acli.utils.images import image_to_data_url
+        from dashscope.acli.utils.paths import validate_path
+
+        try:
+            safe_path = validate_path(image_path)
+            data_url = image_to_data_url(safe_path)
+        except (ValueError, OSError) as e:
+            return f"Error: failed to read image: {e}"
+
+        model = pick_vision_model(config)
+        provider = get_provider_fn(
+            config.provider,
+            model,
+            config.api_key,
+            base_url=config.base_url or None,
+        )
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": question},
+                    {"type": "image_url", "image_url": {"url": data_url}},
+                ],
+            },
+        ]
+        try:
+            response = await provider.chat(messages)
+        except Exception as e:  # pylint: disable=broad-except
+            return f"Error: vision call failed: {e}"
+        return response.content or "(vision model returned no content)"
+
+    registry.register(
+        ToolDefinition(
+            name="view_image",
+            description=(
+                "Analyze a local image file (screenshot, photo, chart) "
+                "with a vision model: OCR/transcribe text, describe "
+                "layout or content. Use after scrape_web_screenshot or "
+                "camera_capture, or whenever you need to read an image."
+            ),
+            permission=PermissionLevel.AUTO,
+            func=view_image,
+            parameters={
+                "type": "object",
+                "properties": {
+                    "image_path": {
+                        "type": "string",
+                        "description": (
+                            "Path to the image file (relative to the "
+                            "workspace or absolute)"
+                        ),
+                    },
+                    "question": {
+                        "type": "string",
+                        "description": (
+                            "What to extract from the image; defaults "
+                            "to a full description + verbatim OCR"
+                        ),
+                    },
+                },
+                "required": ["image_path"],
+            },
+        ),
+    )

tests/unit/test_acli_vision_tool.py

@@ -0,0 +1,136 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Alibaba, Inc. and its affiliates.
+# pylint: disable=protected-access
+
+from types import SimpleNamespace
+
+import pytest
+
+from dashscope.acli.tools import vision
+from dashscope.acli.tools.registry import registry
+
+
+class FakeProvider:
+    def __init__(self):
+        self.messages = None
+
+    async def chat(self, messages):
+        self.messages = messages
+        return SimpleNamespace(content="transcribed table text")
+
+
+def _config():
+    return SimpleNamespace(
+        provider="tongyi",
+        model="qwen3.8-max",
+        api_key="sk-test",
+        base_url="",
+    )
+
+
+def _register(fake_provider):
+    captured = {}
+
+    def get_provider_fn(provider, model, api_key, base_url=None):
+        captured.update(
+            provider=provider,
+            model=model,
+            api_key=api_key,
+            base_url=base_url,
+        )
+        return fake_provider
+
+    vision.register_vision_tools(
+        _config(),
+        get_provider_fn=get_provider_fn,
+    )
+    return captured
+
+
+class TestViewImage:
+    async def test_sends_image_to_vision_model(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(
+            vision,
+            "is_vision_model",
+            lambda model: False,
+        )
+        monkeypatch.setattr(
+            "dashscope.acli.extensions.find_provider",
+            lambda name: SimpleNamespace(vision_models=["qwen-vl-plus"]),
+        )
+        fake_provider = FakeProvider()
+        captured = _register(fake_provider)
+
+        image = tmp_path / "shot.png"
+        image.write_bytes(b"\x89PNG fake bytes")
+
+        result = await registry.get("view_image").func(
+            image_path=str(image),
+        )
+
+        assert result == "transcribed table text"
+        assert captured["model"] == "qwen-vl-plus"
+        content = fake_provider.messages[0]["content"]
+        assert content[0]["type"] == "text"
+        assert content[1]["image_url"]["url"].startswith(
+            "data:image/png;base64,",
+        )
+
+    async def test_missing_file_returns_error(self):
+        _register(FakeProvider())
+        result = await registry.get("view_image").func(
+            image_path=str("no-such-image.png"),
+        )
+        assert result.startswith("Error: failed to read image")
+
+    async def test_vision_call_failure_returns_error(self, tmp_path):
+        class BrokenProvider:
+            async def chat(self, messages):
+                raise RuntimeError("boom")
+
+        _register(BrokenProvider())
+        image = tmp_path / "shot.png"
+        image.write_bytes(b"\x89PNG fake bytes")
+        result = await registry.get("view_image").func(
+            image_path=str(image),
+        )
+        assert result == "Error: vision call failed: boom"
+
+
+class TestPickVisionModel:
+    def test_active_model_when_vision_capable(self, monkeypatch):
+        monkeypatch.setattr(vision, "is_vision_model", lambda m: True)
+        assert vision.pick_vision_model(_config()) == "qwen3.8-max"
+
+    def test_extension_vision_models(self, monkeypatch):
+        monkeypatch.setattr(vision, "is_vision_model", lambda m: False)
+        monkeypatch.setattr(
+            "dashscope.acli.extensions.find_provider",
+            lambda name: SimpleNamespace(vision_models=["qwen-vl-max"]),
+        )
+        assert vision.pick_vision_model(_config()) == "qwen-vl-max"
+
+    def test_fallback_per_provider(self, monkeypatch):
+        monkeypatch.setattr(vision, "is_vision_model", lambda m: False)
+        monkeypatch.setattr(
+            "dashscope.acli.extensions.find_provider",
+            lambda name: None,
+        )
+        assert vision.pick_vision_model(_config()) == "qwen-vl-max"
+        cfg = _config()
+        cfg.provider = "openai"
+        assert vision.pick_vision_model(cfg) == "gpt-4o"
+
+
+class TestSchemaExposure:
+    def test_view_image_always_offered(self):
+        vision.register_vision_tools(
+            _config(),
+            get_provider_fn=lambda *a, **k: FakeProvider(),
+        )
+        names = [t["name"] for t in registry.to_schema_list()]
+        assert "view_image" in names
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])