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

mini_agent/llm.py

@@ -0,0 +1,339 @@
+"""三种协议：openai-chat / openai-responses / anthropic。流式，只用标准库发 HTTP。
+
+内部历史用一种中立格式，每种协议各自负责「翻译过去、解析回来」：
+
+    {"role": "user", "content": "文字" 或 [{"type": "text", "text"}, {"type": "image", "url": data_url}]}
+    {"role": "assistant", "text", "thinking", "tool_calls": [{"id", "name", "arguments": JSON 字符串}],
+     "raw": 这一轮的协议原文, "api", "ref": 哪个协议、哪个模型产生的}
+    {"role": "tool", "id": 调用 id, "content": "结果"}
+
+中途换模型（参考 pi-ai 的 cross-provider handoff）：
+    同一个模型产生的 assistant 消息 → 回放 raw，thinking 签名、reasoning 项都不丢
+    别的模型产生的           → 只用中立字段重建：thinking 变成普通文本，签名丢掉，
+                               工具调用 id 规范成各家都接受的字符集
+"""
+
+import asyncio
+import json
+import re
+import threading
+import urllib.error
+import urllib.request
+
+from .config import MissingEnv, expand
+
+TIMEOUT = 600
+
+
+class LLMError(Exception):
+    pass
+
+
+class LLM:
+    def __init__(self, ref, api, base_url, api_key, model, options):
+        self.ref, self.api, self.base_url = ref, api, base_url.rstrip("/")
+        self.api_key, self.model, self.options = api_key, model, options
+        self._stop, self._response = threading.Event(), None
+
+    async def complete(self, system, messages, tools, emit):
+        """emit(kind, 增量文本)，kind 是 text / thinking。返回中立格式的 assistant 消息。"""
+        build, path, stream = PROTOCOLS[self.api]
+        body = {**build(self, system, messages, tools), "stream": True}
+        self._stop.clear()
+        reply = await asyncio.to_thread(self._run, path, body, stream(emit))
+        return {**reply, "api": self.api, "ref": self.ref}
+
+    def abort(self):
+        """Ctrl+C 时从主线程调：让读流的线程尽快停下。"""
+        self._stop.set()
+        if self._response:
+            try:
+                self._response.close()
+            except Exception:
+                pass
+
+    def _run(self, path, body, acc):
+        headers = {"content-type": "application/json", "accept": "text/event-stream",
+                   "authorization": f"Bearer {self.api_key}"}
+        if self.api == "anthropic":
+            headers |= {"x-api-key": self.api_key, "anthropic-version": "2023-06-01"}
+        request = urllib.request.Request(
+            self.base_url + path, data=json.dumps(body).encode(), headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(request, timeout=TIMEOUT) as response:
+                self._response = response
+                for raw in response:
+                    if self._stop.is_set():
+                        raise LLMError("已中断")
+                    line = raw.decode("utf-8", errors="replace").strip()
+                    if not line.startswith("data:"):
+                        continue
+                    data = line[5:].strip()
+                    if data == "[DONE]":
+                        break
+                    event = json.loads(data)
+                    if isinstance(event.get("error"), dict) or event.get("type") == "error":
+                        raise LLMError(json.dumps(event.get("error") or event, ensure_ascii=False)[:800])
+                    acc.add(event)
+        except urllib.error.HTTPError as error:
+            raise LLMError(f"{error.code} {error.read().decode(errors='replace')[:800]}") from None
+        except urllib.error.URLError as error:
+            raise LLMError(f"连不上 {self.base_url}：{error.reason}") from None
+        except (OSError, ValueError) as error:
+            if self._stop.is_set():
+                raise LLMError("已中断") from None
+            raise
+        finally:
+            self._response = None
+        return acc.result()
+
+
+def _native(llm, m):
+    """这条 assistant 消息是不是当前这个模型产生的 —— 是的话可以原样回放。"""
+    return m.get("api") == llm.api and m.get("ref") == llm.ref and m.get("raw") is not None
+
+
+def _plain(m):
+    """别家模型的回复：thinking 变普通文本（签名只对原模型有效，丢掉）。"""
+    thinking = m.get("thinking") or ""
+    return (f"<thinking>\n{thinking}\n</thinking>\n\n" if thinking.strip() else "") + (m["text"] or "")
+
+
+def _parts(content, text_type, image):
+    if isinstance(content, str):
+        return [{"type": text_type, "text": content}]
+    return [{"type": text_type, "text": p["text"]} if p["type"] == "text" else image(p["url"]) for p in content]
+
+
+# ---------------- openai-chat ----------------
+
+def _chat_build(llm, system, messages, tools):
+    out = [{"role": "system", "content": system}]
+    for m in messages:
+        if m["role"] == "user":
+            content = m["content"] if isinstance(m["content"], str) else _parts(
+                m["content"], "text", lambda url: {"type": "image_url", "image_url": {"url": url}})
+            out.append({"role": "user", "content": content})
+        elif m["role"] == "assistant":
+            native = _native(llm, m)
+            msg = {"role": "assistant", "content": (m["text"] if native else _plain(m)) or None}
+            if native:
+                msg |= m["raw"]  # DeepSeek / qwen 的 reasoning_content，工具调用中间轮要带回去
+            if m["tool_calls"]:
+                msg["tool_calls"] = [{"id": t["id"], "type": "function", "function": {
+                    "name": t["name"], "arguments": t["arguments"]}} for t in m["tool_calls"]]
+            out.append(msg)
+        else:
+            out.append({"role": "tool", "tool_call_id": m["id"], "content": m["content"]})
+    body = {"model": llm.model, "messages": out, **llm.options}
+    if tools:
+        body["tools"] = [{"type": "function", "function": t} for t in tools]
+    return body
+
+
+class _ChatStream:
+    def __init__(self, emit):
+        self.emit, self.text, self.thinking, self.calls = emit, [], [], {}
+
+    def add(self, event):
+        for choice in event.get("choices") or []:
+            delta = choice.get("delta") or {}
+            if delta.get("reasoning_content"):
+                self.thinking.append(delta["reasoning_content"])
+                self.emit("thinking", delta["reasoning_content"])
+            if delta.get("content"):
+                self.text.append(delta["content"])
+                self.emit("text", delta["content"])
+            for t in delta.get("tool_calls") or []:
+                call = self.calls.setdefault(t.get("index", 0), {"id": "", "name": "", "arguments": ""})
+                function = t.get("function") or {}
+                call["id"] = t.get("id") or call["id"]
+                call["name"] += function.get("name") or ""
+                call["arguments"] += function.get("arguments") or ""
+
+    def result(self):
+        thinking = "".join(self.thinking)
+        return {"role": "assistant", "text": "".join(self.text), "thinking": thinking,
+                "tool_calls": [{**c, "arguments": c["arguments"] or "{}"} for _, c in sorted(self.calls.items())],
+                "raw": {"reasoning_content": thinking} if thinking else {}}
+
+
+# ---------------- openai-responses ----------------
+
+def _responses_build(llm, system, messages, tools):
+    items = []
+    for m in messages:
+        if m["role"] == "user":
+            items.append({"role": "user", "content": _parts(
+                m["content"], "input_text", lambda url: {"type": "input_image", "image_url": url})})
+        elif m["role"] == "assistant":
+            if _native(llm, m):
+                items += m["raw"]
+                continue
+            if _plain(m):
+                items.append({"role": "assistant", "content": _plain(m)})
+            items += [{"type": "function_call", "call_id": t["id"], "name": t["name"], "arguments": t["arguments"]}
+                      for t in m["tool_calls"]]
+        else:
+            items.append({"type": "function_call_output", "call_id": m["id"], "output": m["content"]})
+    body = {"model": llm.model, "instructions": system, "input": items, "store": False, **llm.options}
+    if tools:
+        body["tools"] = [{"type": "function", **t} for t in tools]
+    return body
+
+
+class _ResponsesStream:
+    """增量只用来显示；最终结果取 response.completed 里的完整 response。"""
+
+    def __init__(self, emit):
+        self.emit, self.final = emit, None
+
+    def add(self, event):
+        kind = event.get("type", "")
+        if kind == "response.output_text.delta":
+            self.emit("text", event["delta"])
+        elif kind in ("response.reasoning_summary_text.delta", "response.reasoning_text.delta"):
+            self.emit("thinking", event["delta"])
+        elif kind in ("response.completed", "response.incomplete"):
+            self.final = event["response"]
+        elif kind == "response.failed":
+            raise LLMError(json.dumps(event["response"].get("error"), ensure_ascii=False)[:800])
+
+    def result(self):
+        if not self.final:
+            raise LLMError("流提前结束，没收到 response.completed")
+        output = self.final.get("output") or []
+        text = "".join(c.get("text", "") for i in output if i["type"] == "message"
+                       for c in i.get("content") or [] if c["type"] == "output_text")
+        thinking = "".join(s.get("text", "") for i in output if i["type"] == "reasoning"
+                           for s in (i.get("summary") or []) + (i.get("content") or []))
+        calls = [{"id": i["call_id"], "name": i["name"], "arguments": i.get("arguments") or "{}"}
+                 for i in output if i["type"] == "function_call"]
+        # store=false 时服务端不记 reasoning，没有加密内容的 reasoning 项回放会报错，丢掉
+        raw = [i for i in output if i["type"] != "reasoning" or i.get("encrypted_content")]
+        return {"role": "assistant", "text": text, "thinking": thinking, "tool_calls": calls, "raw": raw}
+
+
+# ---------------- anthropic ----------------
+
+def _safe_id(value):
+    """Anthropic 要求工具调用 id 匹配 ^[a-zA-Z0-9_-]{1,64}$，别家的 id 不一定满足。"""
+    return re.sub(r"[^A-Za-z0-9_-]", "_", value)[:64] or "call"
+
+
+def _image_block(url):
+    head, _, data = url.partition(",")
+    return {"type": "image", "source": {
+        "type": "base64", "media_type": head.removeprefix("data:").split(";")[0], "data": data}}
+
+
+def _anthropic_build(llm, system, messages, tools):
+    out = []
+
+    def push(role, blocks):
+        # 要求 user / assistant 交替：连续的 tool 结果并进同一条 user
+        if not blocks:
+            return
+        if out and out[-1]["role"] == role:
+            out[-1]["content"] += blocks
+        else:
+            out.append({"role": role, "content": list(blocks)})
+
+    for m in messages:
+        if m["role"] == "user":
+            push("user", [b for b in _parts(m["content"], "text", _image_block)
+                          if b["type"] != "text" or b["text"].strip()] or [{"type": "text", "text": "…"}])
+        elif m["role"] == "assistant":
+            if _native(llm, m):
+                push("assistant", m["raw"])
+                continue
+            blocks = [{"type": "text", "text": _plain(m)}] if _plain(m).strip() else []
+            blocks += [{"type": "tool_use", "id": _safe_id(t["id"]), "name": t["name"],
+                        "input": _json_or_empty(t["arguments"])} for t in m["tool_calls"]]
+            push("assistant", blocks)
+        else:
+            push("user", [{"type": "tool_result", "tool_use_id": _safe_id(m["id"]), "content": m["content"]}])
+
+    body = {"model": llm.model, "system": system, "messages": out, "max_tokens": 8192, **llm.options}
+    if tools:
+        body["tools"] = [{"name": t["name"], "description": t["description"], "input_schema": t["parameters"]}
+                         for t in tools]
+    return body
+
+
+def _json_or_empty(text):
+    try:
+        value = json.loads(text or "{}")
+        return value if isinstance(value, dict) else {}
+    except json.JSONDecodeError:
+        return {}
+
+
+class _AnthropicStream:
+    def __init__(self, emit):
+        self.emit, self.blocks = emit, {}
+
+    def add(self, event):
+        kind = event.get("type")
+        if kind == "content_block_start":
+            block = dict(event["content_block"])
+            if block["type"] == "tool_use":
+                block["input"], block["_json"] = {}, ""
+            self.blocks[event["index"]] = block
+        elif kind == "content_block_delta":
+            block, delta = self.blocks[event["index"]], event["delta"]
+            if delta["type"] == "text_delta":
+                block["text"] = block.get("text", "") + delta["text"]
+                self.emit("text", delta["text"])
+            elif delta["type"] == "thinking_delta":
+                block["thinking"] = block.get("thinking", "") + delta["thinking"]
+                self.emit("thinking", delta["thinking"])
+            elif delta["type"] == "signature_delta":
+                block["signature"] = block.get("signature", "") + delta["signature"]
+            elif delta["type"] == "input_json_delta":
+                block["_json"] += delta["partial_json"]
+
+    def result(self):
+        content = []
+        for _, block in sorted(self.blocks.items()):
+            if "_json" in block:
+                block["input"] = _json_or_empty(block.pop("_json"))
+            content.append(block)
+        return {
+            "role": "assistant",
+            "text": "".join(b["text"] for b in content if b["type"] == "text"),
+            "thinking": "".join(b.get("thinking", "") for b in content if b["type"] == "thinking"),
+            "tool_calls": [{"id": b["id"], "name": b["name"], "arguments": json.dumps(b["input"], ensure_ascii=False)}
+                           for b in content if b["type"] == "tool_use"],
+            "raw": content,
+        }
+
+
+PROTOCOLS = {
+    "openai-chat": (_chat_build, "/chat/completions", _ChatStream),
+    "openai-responses": (_responses_build, "/responses", _ResponsesStream),
+    "anthropic": (_anthropic_build, "/v1/messages", _AnthropicStream),
+}
+
+
+def make_llm(config, ref=None):
+    """ref 形如 deepseek/deepseek-flash。配置有问题直接抛 SystemExit，说清楚哪儿不对。"""
+    ref = ref or config.get("model")
+    if not ref or "/" not in ref:
+        raise SystemExit(f"模型要写成 <provider>/<model>，现在是：{ref!r}")
+    name, _, model = ref.partition("/")
+    provider = config.get("provider", {}).get(name)
+    if not provider:
+        raise SystemExit(f"配置里没有 provider {name!r}，已有：{'、'.join(config.get('provider', {}))}")
+    api = provider.get("api", "openai-chat")
+    if api not in PROTOCOLS:
+        raise SystemExit(f"{name}.api 只能是 {'、'.join(PROTOCOLS)}，现在是 {api!r}")
+    try:
+        base_url, api_key = expand(provider["baseURL"]), expand(provider.get("apiKey", ""))
+        options = expand({**provider.get("options", {}),
+                          **provider.get("models", {}).get(model, {}).get("options", {})})
+    except MissingEnv as error:
+        raise SystemExit(f"{name} 需要环境变量 {error}")
+    except KeyError:
+        raise SystemExit(f"{name} 没写 baseURL")
+    return LLM(ref, api, base_url, api_key, model, options)

mini_agent/mcp.py

@@ -0,0 +1,83 @@
+"""mini-agent.json 里的 mcp 段 -> 该连哪些 server，以及怎么连。
+
+    "mcp": {
+      "名字": {"type": "local",  "command": ["npx", "-y", "..."], "environment": {...}, "enabled": true},
+      "名字": {"type": "remote", "url": "https://...", "headers": {...}}
+    }
+
+单独跑可以先看配置：uv run python -m mini_agent.mcp
+"""
+
+import re
+
+from .config import MissingEnv, expand
+
+
+def load_servers(config):
+    """返回 (生效的 server 列表, 跳过原因)。一个 server 有问题只是少一批工具。"""
+    servers, notes = [], []
+    for name, raw in (config.get("mcp") or {}).items():
+        if raw.get("enabled") is False:
+            notes.append(f"{name}：enabled 是 false")
+            continue
+        try:
+            server = {"name": name, **expand(raw)}
+        except MissingEnv as error:
+            notes.append(f"{name}：环境变量 {error} 没设置")
+            continue
+        kind = server.get("type") or ("remote" if server.get("url") else "local")
+        if kind == "remote" and server.get("url"):
+            servers.append({**server, "type": "remote"})
+        elif kind == "local" and server.get("command"):
+            servers.append({**server, "type": "local"})
+        else:
+            notes.append(f"{name}：local 要写 command（数组），remote 要写 url")
+    return servers, notes
+
+
+async def open_session(stack, server):
+    """连上一个 server，生命周期挂到 AsyncExitStack 上，退出时统一关掉。"""
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+    from mcp.client.streamable_http import streamable_http_client
+
+    if server["type"] == "remote":
+        client = None
+        if server.get("headers"):
+            import httpx2  # mcp 自己的依赖
+
+            client = await stack.enter_async_context(httpx2.AsyncClient(headers=server["headers"], timeout=30))
+        transport = streamable_http_client(server["url"], http_client=client)
+    else:
+        command, *args = server["command"]
+        transport = stdio_client(StdioServerParameters(command=command, args=args, env=server.get("environment")))
+    read, write = await stack.enter_async_context(transport)
+    session = await stack.enter_async_context(ClientSession(read, write))
+    await session.initialize()
+    return session
+
+
+def describe(server):
+    """打印用。url 里常带 key，别原样打出来。"""
+    if server["type"] == "remote":
+        return "remote " + re.sub(r"((?:key|token)=)[^&]+", r"\1***", server["url"], flags=re.I)
+    return "local  " + " ".join(server["command"])
+
+
+def main():
+    from .config import load
+
+    config, sources = load()
+    servers, notes = load_servers(config)
+    print("配置：" + "、".join(map(str, sources)) + "\n")
+    print(f"生效的 server（{len(servers)} 个）：")
+    for s in servers:
+        print(f"  {s['name']:<20} {describe(s)}")
+    if notes:
+        print(f"\n跳过的（{len(notes)} 个）：")
+        for note in notes:
+            print(f"  {note}")
+
+
+if __name__ == "__main__":
+    main()

mini_agent/mini-agent.example.json

@@ -0,0 +1,81 @@
+// mini-agent 配置示例。首次运行会复制到 ~/.config/mini-agent/mini-agent.json。
+// 项目里放一个 mini-agent.json，会深度合并覆盖全局配置（从当前目录往上找到 git 根目录）。
+// 支持整行 // 注释。密钥写成 {env:变量名}，不要明文写进来。
+{
+  // 默认模型：<provider>/<model>。运行时可以用 --model 或 /model 切换
+  "model": "deepseek/deepseek-flash",
+
+  "provider": {
+    // api 三选一：
+    //   openai-chat       POST {baseURL}/chat/completions   绝大多数厂商都兼容
+    //   openai-responses  POST {baseURL}/responses
+    //   anthropic         POST {baseURL}/v1/messages
+    // options 原样并进请求体；models.<id>.options 只对那个模型生效，优先级更高
+    "deepseek": {
+      "api": "openai-chat",
+      "baseURL": "https://api.deepseek.com",
+      "apiKey": "{env:DEEPSEEK_API_KEY}"
+    },
+    "bailian": {
+      "api": "openai-chat",
+      "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      "apiKey": "{env:DASHSCOPE_API_KEY}",
+      // qwen3.8-flash 开思考时偶尔会忽略用户这一轮的问题（实测约 1/3），默认关掉；
+      // 换 plus / max 或想看思考过程（灰色显示）再打开
+      "options": { "enable_thinking": false }
+    },
+    "bailian-responses": {
+      "api": "openai-responses",
+      "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      "apiKey": "{env:DASHSCOPE_API_KEY}"
+    },
+    "bailian-anthropic": {
+      "api": "anthropic",
+      "baseURL": "https://dashscope.aliyuncs.com/apps/anthropic",
+      "apiKey": "{env:DASHSCOPE_API_KEY}",
+      "options": { "max_tokens": 8192 }
+    },
+    "openai": {
+      "api": "openai-responses",
+      "baseURL": "https://api.openai.com/v1",
+      "apiKey": "{env:OPENAI_API_KEY}"
+    },
+    "anthropic": {
+      "api": "anthropic",
+      "baseURL": "https://api.anthropic.com",
+      "apiKey": "{env:ANTHROPIC_API_KEY}",
+      "options": { "max_tokens": 16000 }
+    }
+  },
+
+  // type: local（启动子进程，stdio）或 remote（streamable HTTP）
+  // 缺 {env:} 变量或 enabled 为 false 的会被跳过，不影响启动
+  "mcp": {
+    "sequential-thinking": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-sequential-thinking"]
+    },
+    "brave-search": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-brave-search"],
+      "environment": { "BRAVE_API_KEY": "{env:BRAVE_API_KEY}" }
+    },
+    "amap": {
+      "type": "remote",
+      "url": "https://mcp.amap.com/mcp?key={env:AMAP_MAPS_API_KEY}",
+      "enabled": true
+    }
+  },
+
+  // 每类操作：ask（先问）/ allow（直接放行）/ deny（禁止）。--yes 会把 ask 全部当 allow
+  //   bash      执行命令
+  //   edit      write / edit 改文件
+  //   external  读工作目录和 skill 目录以外的路径
+  //   mcp       名字以 create / delete / send / run 等动词开头的 MCP 工具
+  "permission": {
+    "bash": "ask",
+    "edit": "ask",
+    "external": "ask",
+    "mcp": "ask"
+  }
+}

mini_agent/skills/mini-agent-config/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: mini-agent-config
+description: 当用户要添加、修改、删除、开关 MCP server，或者切换 / 新增模型厂商、调整权限时使用。负责改 mini-agent.json
+---
+
+# 修改 mini-agent 配置
+
+## 改哪个文件
+
+- 全局：`~/.config/mini-agent/mini-agent.json`（环境变量 `MINI_AGENT_CONFIG` 可能改了路径，先 `echo $MINI_AGENT_CONFIG` 确认）
+- 项目：git 根目录或当前目录下的 `mini-agent.json`，深度合并覆盖全局
+
+用户没说改哪个，就问一句：只在这个项目用，还是所有地方都用。完整格式见 `../../mini-agent.example.json`（相对本 skill 目录）。
+
+## 步骤
+
+1. 先 read 目标文件。文件是 JSON，允许整行 `//` 注释
+2. 用 edit 做最小改动，不要整体重写，保留用户原有的注释和顺序
+3. 密钥一律写成 `{env:变量名}`。用户把 key 直接贴给你时，不要写进文件，告诉用户用 `export 变量名=...` 加到 shell 配置里
+4. 改完用 bash 跑 `python3 -c "import re,json,sys; json.loads(re.sub(r'(?m)^\s*//.*$','',open(sys.argv[1]).read()))" <文件>` 确认还是合法 JSON
+5. 告诉用户输入 `/reload` 生效
+
+## MCP 格式
+
+```json
+"mcp": {
+  "名字": {"type": "local", "command": ["npx", "-y", "包名"], "environment": {"KEY": "{env:KEY}"}},
+  "名字": {"type": "remote", "url": "https://...", "headers": {"Authorization": "Bearer {env:TOKEN}"}},
+  "名字": {"...": "...", "enabled": false}
+}
+```
+
+- 不确定一个 MCP 包叫什么、要哪些环境变量时，先用 bash 查（`npm view <包名>`，或看它的 README），不要编
+- 关掉一个 server 用 `"enabled": false`，不要删掉整段
+
+## 模型格式
+
+```json
+"model": "provider名/模型id",
+"provider": {
+  "名字": {"api": "openai-chat | openai-responses | anthropic", "baseURL": "...", "apiKey": "{env:KEY}",
+           "options": {"原样并进请求体的参数": "..."}}
+}
+```
+
+baseURL 的写法和各家 SDK 一致：openai 两种协议写到 `/v1` 为止，anthropic 不带 `/v1`。