mini-agent-cli 0.2.0__py3-none-any.whl

mini_agent/__init__.py

@@ -0,0 +1,11 @@
+"""mini-agent：终端里的编码 Agent。
+
+    config.py     读 mini-agent.json（全局 + 项目，深度合并）
+    llm.py        三种协议：openai-chat / openai-responses / anthropic
+    tools.py      内置工具：bash read write edit grep glob
+    mcp.py        mcp 段 -> 连 MCP server
+    skills.py     Agent Skills（SKILL.md）发现与加载
+    images.py     剪贴板 / 文件里的图 -> 多模态 content
+    agent.py      装配、权限、循环、上下文预算
+    __main__.py   命令行入口
+"""

mini_agent/__main__.py

@@ -0,0 +1,172 @@
+"""命令行入口。
+
+    mini-agent                          交互模式
+    mini-agent -p "帮我看下这个仓库"      问一句就退出，适合脚本 / 管道
+    mini-agent -m bailian/qwen3.8-plus  换模型（<provider>/<model>，provider 来自配置）
+    mini-agent --yes                    ask 类操作全部放行（deny 仍然禁止）
+"""
+
+import argparse
+import asyncio
+import readline  # noqa: F401  让 input() 支持方向键和历史
+import signal
+import sys
+from contextlib import AsyncExitStack
+from importlib.metadata import version
+
+from .agent import Agent
+from .config import load
+from .images import grab_clipboard, looks_like_image
+from .llm import make_llm
+
+HELP = """/img [路径]      挂一张图（不带路径从剪贴板取；也可以直接把图片文件拖进来）
+/model [p/m]    看或切换模型（对话保留，可以跨厂商、跨协议）
+/reload         重新读配置、skills、MCP（对话保留）
+Ctrl+C          回答中：打断这一轮；输入时：清空当前行
+Ctrl+D          退出
+/clear          清空对话
+/tools          看工具清单
+exit            退出"""
+
+
+def switch_model(agent, ref):
+    try:
+        llm = make_llm(agent.config, ref)
+    except SystemExit as error:
+        print(f"  {error}")
+        return
+    # 历史是中立格式：别家模型的回复会被重建成新协议能接受的样子（见 llm.py 开头）
+    agent.llm = llm
+    print(f"  已切换到 {llm.ref}（{llm.api}）")
+
+
+class Turn:
+    """Ctrl+C 的去向：回答进行中就取消这一轮，否则按默认行为抛 KeyboardInterrupt。"""
+    task = agent = None
+
+    @classmethod
+    def on_sigint(cls, signum, frame):
+        if cls.task and not cls.task.done() and not (cls.agent and cls.agent.prompting):
+            cls.task.get_loop().call_soon_threadsafe(cls.task.cancel)
+            return
+        raise KeyboardInterrupt
+
+    @classmethod
+    async def run(cls, coroutine):
+        cls.task = asyncio.ensure_future(coroutine)
+        try:
+            return await cls.task
+        finally:
+            cls.task = None
+
+
+async def repl(agent):
+    """返回 "reload" 表示要重新装配，其余情况就是退出。"""
+    pending = []
+    while True:
+        # 输入在主线程里同步读：Ctrl+C 直接打断 input()，不会有卡在 stdin 上的后台线程
+        try:
+            line = input(f"\n❯ {f'[{len(pending)}图] ' if pending else ''}").strip()
+        except KeyboardInterrupt:
+            continue
+        except EOFError:
+            print()
+            return None
+        if not line:
+            continue
+        command, _, argument = line.partition(" ")
+        argument = argument.strip()
+        if line in ("exit", "quit", "/exit"):
+            return None
+        if command == "/help":
+            print(HELP)
+            continue
+        if command == "/reload":
+            return "reload"
+        if command == "/clear":
+            agent.reset()
+            pending = []
+            print("  已清空。")
+            continue
+        if command == "/tools":
+            print(agent.report())
+            continue
+        if command == "/model":
+            if argument:
+                switch_model(agent, argument)
+            else:
+                print(f"  当前 {agent.llm.ref}；provider：{'、'.join(agent.config.get('provider', {}))}")
+            continue
+
+        # 绝对路径也是 / 开头，先认图片路径再认命令
+        image = looks_like_image(line)
+        if not image and command == "/img":
+            image = looks_like_image(argument) if argument else grab_clipboard()
+            if not image:
+                print("  没取到图片。")
+                continue
+        if image:
+            pending.append(image)
+            print(f"  已挂上 {image.name}，接着把问题打出来。")
+            continue
+
+        try:
+            await Turn.run(agent.ask(line, pending))
+        except asyncio.CancelledError:
+            print("  已中断。", file=sys.stderr)
+        except Exception as error:
+            print(f"\n  请求失败：{type(error).__name__}: {error}", file=sys.stderr)
+        finally:
+            pending = []
+
+
+async def run(args):
+    signal.signal(signal.SIGINT, Turn.on_sigint)
+    config, sources = load()
+    agent = Turn.agent = Agent(config, make_llm(config, args.model), auto_yes=args.yes)
+    failure = None
+    while True:
+        async with AsyncExitStack() as stack:
+            await agent.build(stack)
+            if args.prompt:
+                try:
+                    await Turn.run(agent.ask(args.prompt))  # 正文已经流式打到 stdout
+                except asyncio.CancelledError:
+                    failure = "已中断"
+                except Exception as error:
+                    # 不能在这里 raise：MCP 的 TaskGroup 会把它包成一大坨异常组
+                    failure = f"请求失败：{type(error).__name__}: {error}"
+                break
+            print("配置  " + "、".join(map(str, sources)))
+            print(agent.report())
+            print("\n/help 看命令，exit 退出。")
+            action = await repl(agent)
+        if action != "reload":
+            break
+        try:
+            config, sources = load()
+        except SystemExit as error:
+            print(f"  {error}\n  沿用旧配置。")
+            continue
+        agent.config, agent.permission = config, config.get("permission") or {}
+        # 当前模型在新配置里还在就沿用，否则回到配置里的默认模型
+        name = agent.llm.ref.partition("/")[0]
+        switch_model(agent, agent.llm.ref if name in config.get("provider", {}) else None)
+    if failure:
+        raise SystemExit(failure)
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="mini-agent", description="终端里的编码 Agent")
+    parser.add_argument("-p", "--prompt", help="问一句就退出")
+    parser.add_argument("-m", "--model", help="<provider>/<model>，默认用配置里的 model")
+    parser.add_argument("-y", "--yes", action="store_true", help="ask 类操作全部放行")
+    parser.add_argument("-V", "--version", action="version", version=f"mini-agent {version('mini-agent-cli')}")
+    try:
+        asyncio.run(run(parser.parse_args()))
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

mini_agent/agent.py

@@ -0,0 +1,275 @@
+"""Agent = LLM + 工具 + 循环。另外管三件事：工具装配、权限、上下文预算。"""
+
+import asyncio
+import json
+import os
+import platform
+import re
+import sys
+from datetime import date
+from pathlib import Path
+
+from .images import user_message
+from .mcp import load_servers, open_session
+from .skills import SKILL_SCHEMA, catalog, load_skills, skill_dirs
+from .tools import TOOL_SCHEMAS, TOOLS, preview
+
+MAX_TURNS = 50               # 一次提问里最多调几轮模型
+MAX_TOOL_CHARS = 30_000      # 单个工具结果最多喂回这么多字符
+MAX_HISTORY_CHARS = 400_000  # 整段历史超过这个数就从最旧的一轮开始丢
+
+# stdout 只放回答正文，思考 / 工具进度 / 审批都走 stderr：-p 重定向到文件时只剩答案
+DIM, RESET = ("\033[2m", "\033[0m") if sys.stderr.isatty() else ("", "")
+
+# 外部 MCP 工具事先不知道有哪些，按动词判断：带副作用的归到 mcp 权限
+RISKY = re.compile(
+    r"^(create|delete|remove|update|edit|write|set|put|post|patch|publish|send|upload|"
+    r"insert|drop|exec|execute|run|move|rename|kill|push|merge|deploy)", re.I)
+
+SYSTEM_PROMPT = """你是运行在用户终端里的编码助手，用户是开发者。
+工作目录：{cwd}
+系统：{system}    今天：{today}
+
+用工具完成任务，最后用中文简洁说明做了什么。
+- 找文件用 glob，搜内容用 grep，看文件用 read，改文件优先 edit，其余用 bash
+- 改代码前先读懂上下文，改动保持最小
+- 操作被用户拒绝就换办法或直接说明，不要反复尝试同一件事"""
+
+
+class Agent:
+    def __init__(self, config, llm, auto_yes=False):
+        self.config, self.llm, self.auto_yes = config, llm, auto_yes
+        self.permission = config.get("permission") or {}
+        self.schemas, self.routes, self.skills, self.notes = [], {}, {}, []
+        self.messages = []
+        self._stream = None       # 正在输出的是 text 还是 thinking
+        self._interrupted = False
+        self.prompting = False    # 正卡在审批的 input() 上：Ctrl+C 要直接打断它
+
+    # ---------------- 装配 ----------------
+
+    async def build(self, stack):
+        """内置 > skill > MCP，重名时先注册的赢。routes[名字] = (类型, 执行者, 来源标签)。"""
+        self.schemas, self.routes, self.notes = [], {}, []
+
+        def claim(name, route, schema):
+            if name in self.routes:
+                self.notes.append(f"工具 {name} 重名，保留先注册的那个")
+                return
+            self.routes[name] = route
+            self.schemas.append(schema)
+
+        for schema in TOOL_SCHEMAS:
+            claim(schema["name"], ("local", TOOLS[schema["name"]], "内置"), schema)
+
+        self.skills, notes = load_skills()
+        self.notes += notes
+        if self.skills:
+            claim("skill", ("skill", self.skills, "skill"), SKILL_SCHEMA)
+
+        servers, notes = load_servers(self.config)
+        self.notes += notes
+        for server in servers:
+            try:
+                session = await open_session(stack, server)
+                tools = (await session.list_tools()).tools
+            except Exception as error:
+                # 一个 server 连不上只是少一批工具，不能拖垮整个 agent
+                self.notes.append(f"{server['name']}：连接失败（{type(error).__name__}: {error}）")
+                continue
+            for t in tools:
+                claim(t.name, ("mcp", session, server["name"]), {
+                    "name": t.name, "description": t.description or "", "parameters": t.input_schema})
+
+        system = SYSTEM_PROMPT.format(cwd=os.getcwd(), system=platform.system(), today=date.today())
+        self.system = system + catalog(self.skills)
+
+    def reset(self):
+        self.messages = []
+
+    def report(self):
+        groups = {}
+        for name, (kind, _, label) in self.routes.items():
+            if kind != "skill":  # skill 工具单独一行报数量
+                groups.setdefault(label, []).append(name)
+        lines = [f"模型  {self.llm.ref}（{self.llm.api}）"]
+        for label, names in groups.items():
+            shown = "、".join(names) if len(names) <= 8 else "、".join(names[:8]) + f" 等 {len(names)} 个"
+            lines.append(f"{label:<5} {shown}")
+        if self.skills:
+            lines.append(f"skills {len(self.skills)} 个，模型按需读取")
+        if self.notes:
+            lines += ["跳过："] + [f"  - {n}" for n in self.notes]
+        return "\n".join(lines)
+
+    # ---------------- 权限 ----------------
+
+    def _safe_path(self, path):
+        """工作目录和 skill 目录里的随便读，别处归 external。"""
+        target = Path(path).expanduser().resolve()
+        return any(target.is_relative_to(r.resolve()) for r in [Path.cwd(), *skill_dirs()])
+
+    def _category(self, kind, name, args):
+        if kind == "local":
+            if name == "bash":
+                return "bash"
+            if name in ("write", "edit"):
+                return "edit"
+            return None if self._safe_path(args.get("path", ".")) else "external"
+        if kind == "mcp" and RISKY.match(name):
+            return "mcp"
+        return None
+
+    def _question(self, category, name, args):
+        if category == "bash":
+            return f"执行：{args.get('command')}"
+        if category == "edit":
+            return f"{name} {args.get('path')}\n{preview(name, args)}"
+        if category == "external":
+            return f"{name} 工作目录外的 {args.get('path')}"
+        return f"调用 {name}({_clip(json.dumps(args, ensure_ascii=False), 300)})"
+
+    def _allowed(self, category, name, args):
+        """返回 None 表示放行，否则是喂回模型的拒绝理由。"""
+        level = self.permission.get(category, "ask")
+        if level == "deny":
+            return f"配置里禁止了 {category} 类操作（permission.{category} = deny）。"
+        if level == "allow" or self.auto_yes:
+            return None
+        if not sys.stdin.isatty():
+            _log("  （非交互模式，自动拒绝；加 --yes 放行）")
+            return "非交互模式下自动拒绝了这次操作。"
+        # 在主线程里同步问：Ctrl+C 能直接打断 input()，不会留下一个还在读 stdin 的线程
+        _log(f"  ⚠ {self._question(category, name, args)}")
+        self.prompting = True
+        try:
+            answer = input("  允许？[y/N] ").strip().lower()
+        except (KeyboardInterrupt, EOFError):
+            _log()
+            self._interrupted = True
+            return "用户中断了这一轮。"
+        finally:
+            self.prompting = False
+        return None if answer == "y" else "用户拒绝了这次操作。"
+
+    # ---------------- 执行 ----------------
+
+    async def _run_tool(self, call):
+        name = call["name"]
+        try:
+            args = json.loads(call["arguments"] or "{}")
+        except json.JSONDecodeError as error:
+            return f"错误：参数不是合法 JSON（{error}）"
+        if name not in self.routes:
+            return f"错误：没有叫 {name} 的工具"
+
+        kind, target, label = self.routes[name]
+        _log(f"  · [{label}] {name}({_clip(json.dumps(args, ensure_ascii=False), 160)})")
+        category = self._category(kind, name, args)
+        if category:
+            refusal = self._allowed(category, name, args)
+            if refusal:
+                return refusal
+
+        try:
+            if kind == "local":
+                # 同步函数丢线程里，别卡住 MCP 的事件循环
+                return str(await asyncio.to_thread(target, **args))
+            if kind == "skill":
+                skill = target.get(args.get("name"))
+                return skill.render() if skill else f"没有叫 {args.get('name')} 的 skill"
+            result = await target.call_tool(name, args)
+            text = "\n".join(b.text for b in result.content if getattr(b, "text", None)).strip()
+            return ("错误：" if result.is_error else "") + (text or "(工具没有返回内容)")
+        except Exception as error:
+            # 异常当普通结果喂回去，让模型自己看到并调整
+            return f"错误：{type(error).__name__}: {error}"
+
+    async def ask(self, text, images=()):
+        """流式输出到终端，返回最终回答。被取消（Ctrl+C）时历史保持可继续的状态。"""
+        self.messages.append(user_message(text, list(images)))
+        self._compact()
+        self._interrupted = False
+        self.prompting = False    # 正卡在审批的 input() 上：Ctrl+C 要直接打断它
+        try:
+            for _ in range(MAX_TURNS):
+                reply = await self.llm.complete(self.system, self.messages, self.schemas, self._emit)
+                self._end_stream()
+                self.messages.append(reply)
+                if not reply["tool_calls"]:
+                    return reply["text"]
+
+                for call in reply["tool_calls"]:
+                    result = "用户中断了这一轮，没有执行。" if self._interrupted else await self._run_tool(call)
+                    if len(result) > MAX_TOOL_CHARS:
+                        result = result[:MAX_TOOL_CHARS] + f"\n…（结果共 {len(result)} 字符，已截断）"
+                    self.messages.append({"role": "tool", "id": call["id"], "content": result})
+                if self._interrupted:
+                    _log("  已中断。")
+                    return "（已中断）"
+            return f"（已达到 {MAX_TURNS} 轮工具调用上限，提前停止）"
+        except asyncio.CancelledError:
+            self.llm.abort()
+            self._end_stream()
+            self._close_orphans()
+            raise
+
+    def _close_orphans(self):
+        """中断时可能留下「有调用没结果」的工具调用，各家接口都会拒绝这种历史。补上占位结果。"""
+        last = next((m for m in reversed(self.messages) if m["role"] == "assistant"), None)
+        if not last:
+            return
+        done = {m["id"] for m in self.messages if m["role"] == "tool"}
+        for call in last["tool_calls"]:
+            if call["id"] not in done:
+                self.messages.append({"role": "tool", "id": call["id"], "content": "用户中断了这一轮，没有执行。"})
+
+    def _emit(self, kind, delta):
+        """流式增量：正文进 stdout，思考过程灰色进 stderr。"""
+        if kind != self._stream:
+            self._end_stream()
+            self._stream = kind
+            if kind == "thinking":
+                sys.stderr.write(DIM)
+        out = sys.stderr if kind == "thinking" else sys.stdout
+        out.write(delta)
+        out.flush()
+
+    def _end_stream(self):
+        if self._stream == "thinking":
+            sys.stderr.write(RESET + "\n")
+            sys.stderr.flush()
+        elif self._stream == "text":
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+        self._stream = None
+
+    # ---------------- 上下文预算 ----------------
+
+    def _compact(self):
+        """旧消息里的图片换成占位符；总量超预算就丢最旧的整轮。
+
+        按「用户消息」切，保证 tool_calls 和对应的 tool 结果一起走，
+        不然接口会报调用 id 对不上。
+        """
+        for m in self.messages[:-1]:
+            if m["role"] == "user" and isinstance(m["content"], list):
+                text = next((p["text"] for p in m["content"] if p["type"] == "text"), "")
+                m["content"] = f"{text}\n[当时附了图片，已从历史中移除]"
+
+        def total():
+            return sum(len(json.dumps(m, ensure_ascii=False, default=str)) for m in self.messages)
+
+        while total() > MAX_HISTORY_CHARS:
+            users = [i for i, m in enumerate(self.messages) if m["role"] == "user" and i > 0]
+            if not users:
+                break
+            del self.messages[:users[0]]
+
+
+def _log(text=""):
+    print(text, file=sys.stderr, flush=True)
+
+
+def _clip(text, limit):
+    return text if len(text) <= limit else text[:limit] + "…"

mini_agent/config.py

@@ -0,0 +1,78 @@
+"""读 mini-agent.json：全局一份，项目里可以再放一份覆盖。
+
+    ~/.config/mini-agent/mini-agent.json        全局（$MINI_AGENT_CONFIG 可改路径）
+    <从 git 根目录到当前目录>/mini-agent.json    项目，越靠近当前目录优先级越高
+
+全局配置不存在时，从包里的 mini-agent.example.json 复制一份过去。
+"""
+
+import json
+import os
+import re
+import shutil
+from pathlib import Path
+
+GLOBAL = Path(os.getenv("MINI_AGENT_CONFIG", "~/.config/mini-agent/mini-agent.json")).expanduser()
+EXAMPLE = Path(__file__).resolve().parent / "mini-agent.example.json"  # 在包里，wheel 安装后也找得到
+NAME = "mini-agent.json"
+
+_ENV = re.compile(r"\{env:([A-Za-z_][A-Za-z0-9_]*)\}")
+_COMMENT = re.compile(r"^\s*//.*$", re.M)  # 只认整行注释，URL 里的 // 不受影响
+
+
+class MissingEnv(Exception):
+    """配置引用了一个没设置的环境变量。"""
+
+
+def project_dirs(start=None):
+    """从 git 根目录到当前目录的每一层（根在前）。不在 git 里就只有当前目录。"""
+    here = Path(start or os.getcwd()).resolve()
+    chain = [here, *here.parents]
+    root = next((i for i, d in enumerate(chain) if (d / ".git").exists()), 0)
+    return list(reversed(chain[:root + 1]))
+
+
+def _read(path):
+    try:
+        return json.loads(_COMMENT.sub("", path.read_text(encoding="utf-8")))
+    except json.JSONDecodeError as error:
+        raise SystemExit(f"{path} 不是合法 JSON：{error}")
+
+
+def merge(base, override):
+    out = dict(base)
+    for key, value in override.items():
+        out[key] = merge(out[key], value) if isinstance(value, dict) and isinstance(out.get(key), dict) else value
+    return out
+
+
+def load():
+    """返回 (合并后的配置, 读到的文件列表)。"""
+    if not GLOBAL.exists():
+        GLOBAL.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(EXAMPLE, GLOBAL)
+        print(f"已生成默认配置：{GLOBAL}")
+    config, sources = _read(GLOBAL), [GLOBAL]
+    for directory in project_dirs():
+        path = directory / NAME
+        if path.exists() and path != GLOBAL:
+            config = merge(config, _read(path))
+            sources.append(path)
+    return config, sources
+
+
+def expand(value):
+    """把 {env:X} 换成环境变量的值，递归处理 list / dict。"""
+    def replace(match):
+        got = os.getenv(match.group(1))
+        if not got:
+            raise MissingEnv(match.group(1))
+        return got
+
+    if isinstance(value, str):
+        return _ENV.sub(replace, value)
+    if isinstance(value, list):
+        return [expand(v) for v in value]
+    if isinstance(value, dict):
+        return {k: expand(v) for k, v in value.items()}
+    return value

mini_agent/images.py

@@ -0,0 +1,143 @@
+"""把一张图变成模型能吃的一段 content。
+
+终端里的 input() 只能收字符串 —— 你按 Cmd+V 贴一张图，它什么都收不到，
+因为图片在系统剪贴板里是二进制，根本不经过 stdin。
+
+所以要绕一下：让 agent 自己去问系统剪贴板要那张图，落成文件，
+再编码成 data URL 塞进 messages。这个文件干的就是这件事。
+
+内部的中立格式（llm.py 再翻译成各协议自己的写法）：
+
+    {"role": "user", "content": [
+        {"type": "text", "text": "这张图里是什么？"},
+        {"type": "image", "url": "data:image/png;base64,..."},
+    ]}
+
+单独跑它可以测剪贴板通不通：
+
+    uv run python -m mini_agent.images
+"""
+
+import base64
+import mimetypes
+import platform
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+IMAGE_EXT = {".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp"}
+
+# 超过这个大小就先缩一下再发。视网膜屏截图动不动几 MB，
+# base64 之后还要再涨三分之一。
+MAX_BYTES = 4 * 1024 * 1024
+SHRINK_TO = 1600  # 长边像素
+
+# macOS：AppleScript 把剪贴板里的图强制转成 PNG 写到文件
+_OSASCRIPT = """
+set outFile to POSIX file "{path}"
+try
+    set imgData to the clipboard as «class PNGf»
+on error
+    return "no-image"
+end try
+set fh to open for access outFile with write permission
+set eof fh to 0
+write imgData to fh
+close access fh
+return "ok"
+"""
+
+_TEMP = Path(tempfile.mkdtemp(prefix="mini_agent_img_"))
+
+
+def looks_like_image(token):
+    """一段文本是不是一个图片文件路径。
+
+    终端里把文件拖进来，就会得到这样一个路径，空格是 \\ 转义的。
+    """
+    path = Path(token.strip().strip("'\"").replace("\\ ", " ")).expanduser()
+    return path if path.suffix.lower() in IMAGE_EXT and path.is_file() else None
+
+
+def grab_clipboard():
+    """从系统剪贴板取一张图，落成临时文件。取不到就返回 None。"""
+    target = _TEMP / f"clip_{len(list(_TEMP.iterdir()))}.png"
+    system = platform.system()
+
+    if system == "Darwin":
+        result = subprocess.run(
+            ["osascript", "-e", _OSASCRIPT.format(path=target)],
+            capture_output=True, text=True,
+        )
+        ok = result.stdout.strip() == "ok"
+    elif system == "Linux" and shutil.which("xclip"):
+        with open(target, "wb") as f:
+            result = subprocess.run(
+                ["xclip", "-selection", "clipboard", "-t", "image/png", "-o"],
+                stdout=f, stderr=subprocess.DEVNULL,
+            )
+        ok = result.returncode == 0
+    else:
+        print(f"  （{system} 上还没接剪贴板，用 /img <路径> 或者把文件拖进来）")
+        return None
+
+    if not ok or not target.exists() or target.stat().st_size == 0:
+        target.unlink(missing_ok=True)
+        return None
+    return target
+
+
+def shrink(path):
+    """太大就用 sips（macOS 自带）缩一下长边，缩不了就原样返回。"""
+    if path.stat().st_size <= MAX_BYTES or not shutil.which("sips"):
+        return path
+    smaller = _TEMP / f"small_{path.name}"
+    result = subprocess.run(
+        ["sips", "-Z", str(SHRINK_TO), str(path), "--out", str(smaller)],
+        capture_output=True,
+    )
+    if result.returncode != 0 or not smaller.exists():
+        return path
+    print(f"  （{path.stat().st_size // 1024}KB 太大，长边缩到 {SHRINK_TO}px"
+          f" → {smaller.stat().st_size // 1024}KB）")
+    return smaller
+
+
+def to_data_url(path):
+    """文件 -> data:image/png;base64,....
+
+    用 data URL 而不是上传拿链接，是因为它不需要任何外部存储 ——
+    图片跟着请求一起走，代价是 base64 会让体积涨 1/3。
+    """
+    path = shrink(Path(path))
+    mime = mimetypes.guess_type(path.name)[0] or "image/png"
+    encoded = base64.b64encode(path.read_bytes()).decode()
+    return f"data:{mime};base64,{encoded}"
+
+
+def user_message(text, images):
+    """拼一条用户消息。没有图就还是原来那个字符串，一点没变。"""
+    if not images:
+        return {"role": "user", "content": text}
+    content = [{"type": "text", "text": text or "看看这张图"}]
+    content += [{"type": "image", "url": to_data_url(p)} for p in images]
+    return {"role": "user", "content": content}
+
+
+def main():
+    print(f"平台：{platform.system()}    临时目录：{_TEMP}\n")
+    print("先随便截个图（Cmd+Shift+Ctrl+4 截到剪贴板），再跑这个脚本。\n")
+
+    path = grab_clipboard()
+    if not path:
+        print("剪贴板里没有图片。")
+        return
+
+    print(f"拿到了：{path}  {path.stat().st_size // 1024}KB")
+    url = to_data_url(path)
+    print(f"编码成 data URL：{url[:60]}...  共 {len(url) // 1024}KB")
+
+
+if __name__ == "__main__":
+    main()