aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/providers/llm/autoconfig.py

@@ -0,0 +1,213 @@
+"""按用户的**实际环境**生成 providers.yaml，而不是发一份通用模板。
+
+为什么不是写死一份文档让用户照抄：通用模板对每个人都是"差不多但不对"——
+装了 Ollama 的人不需要被告知怎么配 OpenAI，配了 DEEPSEEK_API_KEY 的人不该看到
+一堆用不上的占位符，而真正卡住他的（本地服务没起来 / key 名字拼错）模板里
+一个字都不会提。
+
+这里的做法是先探测再生成：
+  - 本地推理服务（Ollama / LM Studio）是否在跑、跑着哪些模型
+  - 哪些 provider 的环境变量已经设了
+  - 用户已有的配置文件里声明过什么
+
+然后产出一份**只包含这台机器上真的能用的东西**的配置，并把"还差什么、
+去哪拿"作为注释写进同一个文件——用户不必在文档和配置之间来回对照。
+
+探测全部是只读的：不发请求到任何云端 provider（那需要消耗用户的额度，也会
+把 key 泄给一次纯粹的探活），只查本地端口和环境变量。云端 provider 的判定
+标准就是"环境变量在不在"，这跟 registry 实际取 key 的方式完全一致。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+from urllib.parse import urlparse
+
+__all__ = ["Finding", "probe_environment", "render_providers_yaml", "suggest_default_chain"]
+
+# (provider id, 环境变量, 默认模型, 去哪拿 key)
+_CLOUD_PROVIDERS: List[tuple] = [
+    ("deepseek",    "DEEPSEEK_API_KEY",    "deepseek-chat",                  "https://platform.deepseek.com/api_keys"),
+    ("siliconflow", "SILICONFLOW_API_KEY", "deepseek-ai/DeepSeek-V3",        "https://cloud.siliconflow.cn/account/ak"),
+    ("dashscope",   "DASHSCOPE_API_KEY",   "qwen-plus",                      "https://bailian.console.aliyun.com/"),
+    ("moonshot",    "MOONSHOT_API_KEY",    "moonshot-v1-8k",                 "https://platform.moonshot.cn/console/api-keys"),
+    ("zhipu",       "ZHIPUAI_API_KEY",     "glm-4-flash",                    "https://open.bigmodel.cn/usercenter/apikeys"),
+    ("openai",      "OPENAI_API_KEY",      "gpt-4o-mini",                    "https://platform.openai.com/api-keys"),
+    ("anthropic",   "ANTHROPIC_API_KEY",   "claude-3-5-haiku-latest",        "https://console.anthropic.com/settings/keys"),
+    ("groq",        "GROQ_API_KEY",        "llama-3.3-70b-versatile",        "https://console.groq.com/keys"),
+    ("together",    "TOGETHER_API_KEY",    "meta-llama/Llama-3.3-70B-Instruct-Turbo", "https://api.together.xyz/settings/api-keys"),
+]
+
+# 本地推理服务：(provider id, 默认地址, 列模型的路径)
+_LOCAL_PROVIDERS: List[tuple] = [
+    ("ollama",   os.environ.get("OLLAMA_BASE_URL",   "http://localhost:11434"), "/api/tags"),
+    ("lmstudio", os.environ.get("LMSTUDIO_BASE_URL", "http://localhost:1234"),  "/v1/models"),
+]
+
+
+@dataclass
+class Finding:
+    """一个 provider 的探测结果。"""
+    provider: str
+    kind: str                       # "local" | "cloud"
+    available: bool
+    detail: str = ""
+    models: List[str] = field(default_factory=list)
+    env_key: Optional[str] = None
+    signup_url: str = ""
+    base_url: str = ""
+
+
+def _port_open(url: str, timeout: float = 0.4) -> bool:
+    """只做 TCP 探活。比发 HTTP 请求快得多，且本地服务没起来时能立刻返回，
+    不会让整个探测卡在连接超时上。"""
+    parsed = urlparse(url)
+    host = parsed.hostname or "localhost"
+    port = parsed.port or (443 if parsed.scheme == "https" else 80)
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except (OSError, ValueError):
+        return False
+
+
+def _fetch_json(url: str, timeout: float = 1.5) -> Optional[dict]:
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            return json.loads(resp.read())
+    except (urllib.error.URLError, OSError, ValueError, json.JSONDecodeError):
+        return None
+
+
+def _local_models(provider: str, base_url: str, path: str) -> List[str]:
+    payload = _fetch_json(base_url.rstrip("/") + path)
+    if not payload:
+        return []
+    if provider == "ollama":
+        return [m.get("name", "") for m in payload.get("models", []) if m.get("name")]
+    return [m.get("id", "") for m in payload.get("data", []) if m.get("id")]
+
+
+def probe_environment(*, check_local: bool = True) -> List[Finding]:
+    """探测这台机器上有什么。只读、不消耗任何额度。"""
+    findings: List[Finding] = []
+
+    if check_local:
+        for provider, base_url, path in _LOCAL_PROVIDERS:
+            if not _port_open(base_url):
+                findings.append(Finding(
+                    provider=provider, kind="local", available=False,
+                    base_url=base_url,
+                    detail=f"{base_url} 未监听（服务没启动，或端口不是默认值）",
+                ))
+                continue
+            models = _local_models(provider, base_url, path)
+            findings.append(Finding(
+                provider=provider, kind="local", available=bool(models),
+                base_url=base_url, models=models,
+                detail=(f"在跑，{len(models)} 个模型" if models
+                        else "端口通但没列出模型（可能还没 pull 过任何模型）"),
+            ))
+
+    for provider, env_key, _model, signup in _CLOUD_PROVIDERS:
+        has_key = bool(os.environ.get(env_key, "").strip())
+        findings.append(Finding(
+            provider=provider, kind="cloud", available=has_key,
+            env_key=env_key, signup_url=signup,
+            detail=(f"{env_key} 已设置" if has_key else f"{env_key} 未设置"),
+        ))
+
+    return findings
+
+
+def suggest_default_chain(findings: List[Finding]) -> tuple[Optional[str], List[str]]:
+    """按探测结果给出 default 与 fallback 链。
+
+    排序原则：本地优先（零成本、不出网、隐私最好），其次是已配好 key 的云端。
+    没配 key 的一律不进链——把用不了的东西写进 fallback 只会在真正需要兜底时
+    连续失败几次才走到能用的那个。
+    """
+    local_ready = [f for f in findings if f.kind == "local" and f.available]
+    cloud_ready = [f for f in findings if f.kind == "cloud" and f.available]
+
+    chain: List[str] = []
+    for f in local_ready:
+        model = f.models[0] if f.models else ""
+        chain.append(f"{f.provider}/{model}" if model else f.provider)
+
+    cloud_default = {p: m for p, _e, m, _s in _CLOUD_PROVIDERS}
+    for f in cloud_ready:
+        chain.append(f"{f.provider}/{cloud_default.get(f.provider, '')}".rstrip("/"))
+
+    return (chain[0] if chain else None), chain[1:]
+
+
+def render_providers_yaml(findings: List[Finding]) -> str:
+    """生成配置文本。缺什么、去哪拿，作为注释写在同一个文件里。"""
+    default, fallback = suggest_default_chain(findings)
+    lines: List[str] = [
+        "# ~/.aria/providers.yaml",
+        "# 由 `aria-code /providers init` 按本机实际环境生成。",
+        "# 密钥一律不写在这里——只写环境变量名，值放 ~/.aria/.env。",
+        "",
+    ]
+
+    if not default:
+        lines += [
+            "# ⚠️ 这台机器上暂时没有可用的模型来源。最快的两条路：",
+            "#   1. 本地（免费、离线可用）：",
+            "#        brew install ollama && ollama serve && ollama pull qwen2.5:7b",
+            "#   2. 云端：拿一个 key 写进 ~/.aria/.env，然后重跑 /providers init",
+            "",
+            "llm:",
+            "  default: ollama/qwen2.5:7b   # 装好 Ollama 后即可用",
+            "",
+        ]
+    else:
+        lines += ["llm:", f"  default: {default}"]
+        if fallback:
+            lines.append("  fallback:")
+            lines += [f"    - {item}" for item in fallback]
+        else:
+            lines += [
+                "  # 只探测到一个可用来源，暂无 fallback。多配一个 key 可以让",
+                "  # 默认来源故障时自动切换。",
+            ]
+        lines.append("")
+
+    ready_local = [f for f in findings if f.kind == "local" and f.available]
+    if ready_local:
+        lines.append("# ── 本机检测到的本地模型 ─────────────────────────────")
+        for f in ready_local:
+            preview = ", ".join(f.models[:6]) + (" …" if len(f.models) > 6 else "")
+            lines.append(f"#   {f.provider} @ {f.base_url} → {preview}")
+        lines.append("")
+
+    missing = [f for f in findings if f.kind == "cloud" and not f.available]
+    if missing:
+        lines.append("# ── 还没配的云端 provider（想用哪个就取哪个 key）────────")
+        lines.append("#   把值写进 ~/.aria/.env，格式 KEY=值（不要加引号）")
+        for f in missing:
+            lines.append(f"#   {f.env_key:<22} {f.signup_url}")
+        lines.append("")
+
+    lines += [
+        "# ── 接入未列出的服务（自建 vLLM / 内网网关 / 任意 OpenAI 兼容端点）──",
+        "# 取消注释并改成你自己的地址即可；之后 mycorp/<model> 就能用在上面的",
+        "# default 和 fallback 里。",
+        "#",
+        "# model_providers:",
+        "#   mycorp:",
+        "#     base_url: http://192.168.1.50:8000/v1",
+        "#     env_key: MYCORP_LLM_TOKEN        # 只写变量名，不写值",
+        "#     env_key_instructions: 找基础架构组申请",
+        "#     model: qwen-72b",
+        "",
+    ]
+    return "\n".join(lines)

aria_code/providers/llm/base.py

@@ -0,0 +1,139 @@
+"""
+providers/llm/base.py — LLM Provider 统一抽象基类
+==================================================
+所有 provider（本地/云端）实现同一接口，上层代码无需关心具体后端。
+
+事件类型 (stream yields):
+    {"type": "token",     "text": "..."}          # 文本增量
+    {"type": "thinking",  "text": "..."}          # 思考过程 (Claude/DeepSeek-R1)
+    {"type": "tool_call", "name": "...", "arguments": {...}}  # 工具调用
+    {"type": "done",      "text": "完整响应"}      # 流结束
+    {"type": "error",     "message": "..."}       # 错误
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Dict, List, Optional
+
+
+@dataclass
+class Message:
+    role: str       # "system" | "user" | "assistant" | "tool"
+    content: str
+    name: Optional[str] = None        # tool name (for role=tool)
+    tool_call_id: Optional[str] = None
+
+
+@dataclass
+class ProviderConfig:
+    """可由 providers.yaml / 环境变量 / CLI 参数覆盖"""
+    name:        str
+    api_key:     Optional[str]   = None
+    base_url:    Optional[str]   = None
+    model:       Optional[str]   = None
+    temperature: float           = 0.3
+    max_tokens:  int             = 4096
+    timeout:     int             = 120
+    # 扩展字段（各 provider 可自定义）
+    extra:       Dict[str, Any]  = field(default_factory=dict)
+
+    @classmethod
+    def from_env(cls, name: str, **defaults) -> "ProviderConfig":
+        """从环境变量自动读取 API Key（DEEPSEEK_API_KEY / OPENAI_API_KEY 等）"""
+        key_map = {
+            "deepseek":    "DEEPSEEK_API_KEY",
+            "openai":      "OPENAI_API_KEY",
+            "anthropic":   "ANTHROPIC_API_KEY",
+            "groq":        "GROQ_API_KEY",
+            "together":    "TOGETHER_API_KEY",
+            "dashscope":   "DASHSCOPE_API_KEY",
+            "siliconflow": "SILICONFLOW_API_KEY",
+            "moonshot":    "MOONSHOT_API_KEY",
+            "zhipu":       "ZHIPUAI_API_KEY",
+        }
+        env_var = key_map.get(name.lower())
+        api_key = os.getenv(env_var, "") if env_var else ""
+        return cls(name=name, api_key=api_key or None, **defaults)
+
+    def is_configured(self) -> bool:
+        """判断 provider 是否可用（本地 provider 无需 api_key）"""
+        _local = {"ollama", "lmstudio", "vllm", "llamacpp", "jan"}
+        if self.name.lower() in _local:
+            return True
+        return bool(self.api_key)
+
+
+class BaseLLMProvider(ABC):
+    """
+    所有 LLM provider 的统一基类。
+
+    子类只需实现 `stream()` 方法；`complete()` 会自动聚合流结果。
+    """
+
+    # 子类声明这些属性
+    provider_name: str = "base"
+    supports_tools: bool = False
+    supports_thinking: bool = False
+    local: bool = False          # True = 本地运行，不需要 api_key
+
+    def __init__(self, config: ProviderConfig):
+        self.config = config
+
+    # ── 必须实现 ──────────────────────────────────────────────────────────────
+
+    @abstractmethod
+    async def stream(
+        self,
+        messages: List[Message],
+        tools: Optional[List[Dict]] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        cancel_event=None,
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """
+        流式生成 token。
+
+        每次 yield 一个事件 dict（见模块文档中的事件类型）。
+        """
+        ...
+        yield {}  # 让 Python 识别为 async generator
+
+    # ── 默认实现（子类可覆盖）────────────────────────────────────────────────
+
+    async def complete(
+        self,
+        messages: List[Message],
+        tools: Optional[List[Dict]] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """聚合 stream() 事件，返回完整响应 dict。"""
+        full_text = ""
+        tool_calls = []
+        async for event in self.stream(
+            messages, tools=tools,
+            temperature=temperature, max_tokens=max_tokens,
+        ):
+            t = event.get("type")
+            if t == "token":
+                full_text += event.get("text", "")
+            elif t == "tool_call":
+                tool_calls.append({
+                    "name": event.get("name"),
+                    "arguments": event.get("arguments", {}),
+                })
+            elif t == "error":
+                return {"success": False, "error": event.get("message"),
+                        "response": full_text, "tool_calls": tool_calls}
+        return {"success": True, "response": full_text, "tool_calls": tool_calls}
+
+    async def is_available(self) -> bool:
+        """检查 provider 是否在线/可用（子类覆盖以做实际探测）"""
+        return self.config.is_configured()
+
+    def __repr__(self) -> str:
+        model = self.config.model or "default"
+        return f"{self.__class__.__name__}(model={model})"

aria_code/providers/llm/custom.py

@@ -0,0 +1,158 @@
+"""声明式自定义 provider —— 用户只写配置文件，不写 Python 代码。
+
+背景：registry.py 里内置了 12 个 provider，但它们的名字、base_url、环境变量
+都是**硬编码**的。用户要接一个未列出的服务（自建 vLLM、公司内网网关、
+Arthera 自己的云端 API、任何 OpenAI 兼容端点），此前唯一的办法是写一个
+BaseLLMProvider 子类再调 register_provider()——对"只想填个地址和 key"的
+用户门槛太高。
+
+设计对标 codex 的 `model_providers`（codex-rs/model-provider-info/src/lib.rs）：
+配置里**只写环境变量名，不写密钥值**。codex 那边同时提供了明文
+`experimental_bearer_token` 字段，但源码注释明确写着 "Use of this config is
+discouraged in favor of `env_key` for security reasons"——这里不提供明文字段，
+只认 env_key，理由见下面 build_custom_provider 的说明。
+
+用户配置示例（~/.aria/providers.yaml 或 ~/.arthera/providers.json）：
+
+    llm:
+      default: mycorp/qwen-72b
+
+    model_providers:
+      mycorp:
+        name: 公司内网推理网关
+        base_url: https://llm.internal.example.com/v1
+        env_key: MYCORP_LLM_TOKEN
+        env_key_instructions: 找基础架构组申请，写进 ~/.aria/.env
+        model: qwen-72b
+        http_headers:
+          X-Tenant: research
+        env_http_headers:
+          X-Trace-Id: MYCORP_TRACE_ID
+
+      arthera-cloud:
+        name: Arthera 云端（Cloud Run）
+        base_url: https://api.arthera.example/api/v2
+        env_key: ARTHERA_API_TOKEN
+
+声明后即可像内置 provider 一样使用：default / fallback / code_tasks 里都能写
+`mycorp/<model>`。
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+from .base import ProviderConfig
+from .openai_compat import OpenAICompatProvider
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["CustomProviderSpec", "parse_custom_providers", "build_custom_provider"]
+
+# 配置里出现这些键一律拒绝：它们意味着用户把密钥明文写进了配置文件。
+# 配置文件常被连同项目一起备份、同步、甚至误提交，明文密钥的暴露面比环境
+# 变量大一个量级。codex 提供了明文字段但自己在注释里劝退；这里直接不提供，
+# 并在检测到时给出可操作的替代方案，而不是静默忽略——静默忽略会让用户以为
+# 配好了，实际请求全部 401，排查成本更高。
+_FORBIDDEN_INLINE_SECRET_KEYS = ("api_key", "apikey", "token", "bearer_token", "secret")
+
+
+class CustomProviderSpec:
+    """一个用户声明的 provider。"""
+
+    __slots__ = ("id", "name", "base_url", "env_key", "env_key_instructions",
+                 "model", "http_headers", "env_http_headers", "timeout")
+
+    def __init__(self, provider_id: str, raw: Dict[str, Any]):
+        self.id = provider_id
+        self.name = str(raw.get("name") or provider_id)
+        self.base_url = str(raw.get("base_url") or "").rstrip("/")
+        self.env_key = raw.get("env_key") or None
+        self.env_key_instructions = raw.get("env_key_instructions") or ""
+        self.model = raw.get("model") or None
+        self.http_headers = dict(raw.get("http_headers") or {})
+        self.env_http_headers = dict(raw.get("env_http_headers") or {})
+        self.timeout = int(raw.get("timeout") or 120)
+
+    def resolved_headers(self) -> Dict[str, str]:
+        """静态头 + 从环境变量取值的头。环境变量缺失时**不发**该头，
+        而不是发一个空值——空值头在很多网关那里会被当成"显式声明为空"，
+        比缺失更难排查。"""
+        headers = dict(self.http_headers)
+        for header_name, env_name in self.env_http_headers.items():
+            value = os.environ.get(str(env_name), "").strip()
+            if value:
+                headers[str(header_name)] = value
+        return headers
+
+    def api_key(self) -> str:
+        return os.environ.get(str(self.env_key), "").strip() if self.env_key else ""
+
+    def missing_key_hint(self) -> str:
+        base = f"provider '{self.id}' 需要环境变量 {self.env_key}，当前未设置或为空。"
+        return f"{base} {self.env_key_instructions}".strip()
+
+
+def parse_custom_providers(cfg: Dict[str, Any]) -> Dict[str, CustomProviderSpec]:
+    """从用户配置解析 model_providers 段。
+
+    配置有问题时记录 warning 并跳过该条，不抛异常——一个写错的自定义 provider
+    不该让整个 CLI 起不来，其余 provider 应当照常可用。
+    """
+    raw_section = cfg.get("model_providers") if isinstance(cfg, dict) else None
+    if not isinstance(raw_section, dict):
+        return {}
+
+    specs: Dict[str, CustomProviderSpec] = {}
+    for provider_id, raw in raw_section.items():
+        pid = str(provider_id).strip().lower()
+        if not pid or not isinstance(raw, dict):
+            logger.warning("model_providers 中跳过无效条目: %r", provider_id)
+            continue
+
+        inline = [k for k in raw if str(k).lower() in _FORBIDDEN_INLINE_SECRET_KEYS]
+        if inline:
+            logger.warning(
+                "model_providers['%s'] 含明文密钥字段 %s —— 已忽略该 provider。"
+                "请改用 env_key 指向环境变量名，把值写进 ~/.aria/.env："
+                "\n  %s:\n    base_url: ...\n    env_key: %s_API_KEY",
+                pid, inline, pid, pid.upper().replace("-", "_"),
+            )
+            continue
+
+        if not raw.get("base_url"):
+            logger.warning("model_providers['%s'] 缺少 base_url —— 已跳过", pid)
+            continue
+
+        specs[pid] = CustomProviderSpec(pid, raw)
+
+    if specs:
+        logger.info("✓ 已加载 %d 个自定义 provider: %s", len(specs), ", ".join(sorted(specs)))
+    return specs
+
+
+def build_custom_provider(spec: CustomProviderSpec, model: Optional[str] = None):
+    """按 spec 构造一个 OpenAI 兼容 provider 实例。
+
+    复用 OpenAICompatProvider 而不是新写一套 HTTP 客户端：绝大多数第三方与
+    自建推理服务（vLLM / LM Studio / Ollama 的 OpenAI 兼容层 / 各家云厂商网关）
+    都实现了 /chat/completions，重写一遍只会多一处要维护的重试与流式解析。
+    """
+    config = ProviderConfig(
+        name=spec.id,
+        api_key=spec.api_key() or None,
+        base_url=spec.base_url,
+        model=model or spec.model,
+        timeout=spec.timeout,
+        extra={"http_headers": spec.resolved_headers(), "custom": True},
+    )
+
+    class _DeclaredProvider(OpenAICompatProvider):
+        provider_name = spec.id
+        DEFAULT_BASE_URL = spec.base_url
+        DEFAULT_MODEL = spec.model or ""
+
+    _DeclaredProvider.__name__ = f"Declared_{spec.id.replace('-', '_')}"
+    return _DeclaredProvider(config)

aria_code/providers/llm/ollama.py

@@ -0,0 +1,137 @@
+"""
+providers/llm/ollama.py — Ollama 本地 LLM Provider
+====================================================
+连接本地运行的 Ollama 服务，支持工具调用（native + text-based fallback）。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, AsyncIterator, Dict, List, Optional
+
+from .base import BaseLLMProvider, Message, ProviderConfig
+
+logger = logging.getLogger(__name__)
+
+
+class OllamaProvider(BaseLLMProvider):
+
+    provider_name    = "ollama"
+    supports_tools   = True
+    supports_thinking = False
+    local            = True
+
+    DEFAULT_URL = "http://localhost:11434"
+
+    def __init__(self, config: ProviderConfig):
+        super().__init__(config)
+        from aria_code.providers.ollama_models import ollama_base_url
+        self.base_url = ollama_base_url({"ollama_base_url": config.base_url})
+        self.model    = config.model or "qwen2.5:7b"
+
+    async def is_available(self) -> bool:
+        """探测 Ollama 服务是否在线"""
+        import urllib.request
+        for url in [self.base_url,
+                    self.base_url.replace("localhost", "127.0.0.1")]:
+            try:
+                urllib.request.urlopen(f"{url}/api/tags", timeout=2).close()
+                return True
+            except Exception:
+                continue
+        return False
+
+    async def list_models(self) -> List[str]:
+        """返回已安装的模型列表"""
+        import urllib.request
+        import json as _json
+        try:
+            with urllib.request.urlopen(f"{self.base_url}/api/tags", timeout=3) as r:
+                data = _json.loads(r.read())
+                return [m["name"] for m in data.get("models", [])]
+        except Exception:
+            return []
+
+    async def stream(
+        self,
+        messages: List[Message],
+        tools: Optional[List[Dict]] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        cancel_event=None,
+    ) -> AsyncIterator[Dict[str, Any]]:
+        import aiohttp
+
+        from aria_code.providers.ollama_models import resolve_model_async
+        try:
+            model = await resolve_model_async(self.base_url, self.model)
+        except ValueError as exc:
+            yield {"type": "error", "message": str(exc)}
+            return
+
+        temp     = temperature if temperature is not None else self.config.temperature
+        n_tokens = max_tokens  if max_tokens  is not None else self.config.max_tokens
+
+        payload = {
+            "model":   model,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "stream":  True,
+            "options": {"temperature": temp, "num_predict": n_tokens, "num_ctx": 32768},
+        }
+        if tools:
+            # 只有支持 native tool call 的模型才注入（其他走 text-based 解析）
+            payload["tools"] = tools
+
+        url = f"{self.base_url}/api/chat"
+        try:
+            async with aiohttp.ClientSession(trust_env=True) as sess:
+                async with sess.post(
+                    url, json=payload,
+                    timeout=aiohttp.ClientTimeout(total=self.config.timeout)
+                ) as resp:
+                    if resp.status != 200:
+                        body = await resp.text()
+                        yield {"type": "error",
+                               "message": f"Ollama HTTP {resp.status}: {body[:200]}"}
+                        return
+
+                    async for raw in resp.content:
+                        if cancel_event and cancel_event.is_set():
+                            return
+                        line = raw.decode("utf-8", errors="ignore").strip()
+                        if not line:
+                            continue
+                        try:
+                            data = json.loads(line)
+                        except json.JSONDecodeError:
+                            continue
+
+                        # Native tool calls
+                        tc_list = (data.get("message") or {}).get("tool_calls") or []
+                        for tc in tc_list:
+                            fn = tc.get("function") or {}
+                            args = fn.get("arguments", {})
+                            if isinstance(args, str):
+                                try:
+                                    args = json.loads(args)
+                                except json.JSONDecodeError:
+                                    args = {"_raw": args}
+                            yield {"type": "tool_call",
+                                   "name": fn.get("name", ""),
+                                   "arguments": args}
+
+                        # Text token
+                        token = (data.get("message") or {}).get("content", "")
+                        if token:
+                            yield {"type": "token", "text": token}
+
+                        if data.get("done"):
+                            yield {"type": "done"}
+                            return
+
+        except aiohttp.ClientConnectorError as e:
+            yield {"type": "error",
+                   "message": f"Ollama 连接失败 ({self.base_url}): {e}"}
+        except Exception as e:
+            yield {"type": "error", "message": f"Ollama 错误: {e}"}