nexforge-cli 0.1.0__py3-none-any.whl

nexforge/icons.py

@@ -0,0 +1,173 @@
+"""图标系统 —— SVG 单一源,按终端能力分级渲染。
+
+三级文本渲染:
+  nerd   终端装了 Nerd Font  → 图标字体(即插即用)
+  glyph  几何符号(默认,科技感单色,任何现代终端都显)
+  ascii  纯 ASCII 兜底(NO_COLOR / 老终端)
+
+加上图像协议模式(需 Kitty/iTerm2/Sixel + cairosvg):只用于横幅/大图,
+不在内联文本中使用。
+
+SVG 位于 assets/icons/<name>.svg,是设计的唯一真源。
+"""
+
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+from typing import Literal
+
+Mode = Literal["image", "nerd", "glyph", "ascii"]
+
+# name → (nerd, glyph, ascii)
+# nerd 栏为空表示该图标没有理想的 Nerd Font 字形,fallback 到 glyph
+ICONS: dict[str, tuple[str, str, str]] = {
+    "agent": ("", "◆", "#"),
+    "user": ("", "❯", ">"),
+    "read": ("", "▤", "r"),
+    "write": ("", "✎", "w"),
+    "edit": ("", "✎", "e"),
+    "shell": ("", "▸", "$"),
+    "search": ("", "⌕", "?"),
+    "dir": ("", "▸", "/"),
+    "web": ("", "◍", "@"),
+    "thinking": ("", "✦", "..."),
+    "ok": ("", "✓", "+"),
+    "err": ("", "✗", "x"),
+    "running": ("", "●", "*"),
+    "model": ("", "⬡", "M"),
+    "cost": ("", "$", "$"),
+    "file": ("", "▢", "f"),
+}
+
+# 工具名 → 图标名
+_TOOL_ICON = {
+    "read_file": "read",
+    "write_file": "write",
+    "edit_file": "edit",
+    "list_dir": "dir",
+    "run_shell": "shell",
+    "search_content": "search",
+    "search_files": "search",
+    "web_fetch": "web",
+}
+
+
+def detect_image_protocol() -> str | None:
+    """探测终端图像协议;探测不到返回 None。"""
+    env = os.environ
+    if env.get("KITTY_WINDOW_ID") or env.get("TERM") == "xterm-kitty":
+        return "kitty"
+    prog = env.get("TERM_PROGRAM", "")
+    if prog == "iTerm.app":
+        return "iterm2"
+    if prog == "WezTerm":
+        return "iterm2"
+    if "sixel" in env.get("TERM", ""):
+        return "sixel"
+    return None
+
+
+def _images_available() -> bool:
+    try:
+        import cairosvg  # noqa: F401
+
+        return True
+    except Exception:
+        return False
+
+
+def _nerd_font_available() -> bool:
+    """简单探测:环境变量 NERD_FONT=1 或用户设置 icons=nerd。"""
+    return os.environ.get("NERD_FONT") in ("1", "true", "yes")
+
+
+class IconRenderer:
+    """按配置 + 终端能力,把图标名解析成可打印文本。"""
+
+    def __init__(self, mode: str = "auto") -> None:
+        self.configured = mode
+        self.mode: Mode = self.resolve_mode(mode)
+        self.image_protocol = detect_image_protocol()
+
+    @staticmethod
+    def resolve_mode(configured: str) -> Mode:
+        if configured in ("ascii", "glyph", "nerd", "image"):
+            return configured  # type: ignore[return-value]
+        # auto: NO_COLOR → ascii, 图像 → image, nerd env → nerd, 默认 glyph
+        if os.environ.get("NO_COLOR") is not None:
+            return "ascii"
+        if detect_image_protocol() and _images_available():
+            return "image"
+        if _nerd_font_available():
+            return "nerd"
+        return "glyph"
+
+    def text(self, name: str) -> str:
+        """返回图标的文本表示:nerd → fallback 到 glyph, ascii → ascii。"""
+        nerd, glyph, ascii_ = ICONS.get(name, ("", "•", "*"))
+        if self.mode == "ascii":
+            return ascii_
+        if self.mode == "nerd" and nerd:
+            return nerd
+        return glyph
+
+    def rasterize(self, name: str, size: int = 24) -> bytes | None:
+        """把 SVG 转成 PNG 字节;缺 cairosvg 或缺文件时返回 None。"""
+        svg = svg_path(name)
+        if svg is None:
+            return None
+        try:
+            import cairosvg
+        except Exception:
+            return None
+        return cairosvg.svg2png(url=str(svg), output_width=size, output_height=size)
+
+
+# ---- 便捷助手 ---------------------------------------------------------------
+
+@lru_cache(maxsize=1)
+def _icons_dir() -> Path | None:
+    try:
+        pkg = resources.files("nexforge") / "assets" / "icons"
+        if pkg.is_dir():  # type: ignore[union-attr]
+            return Path(str(pkg))
+    except Exception:
+        pass
+    dev = Path(__file__).resolve().parent.parent.parent / "assets" / "icons"
+    return dev if dev.is_dir() else None
+
+
+def svg_path(name: str) -> Path | None:
+    d = _icons_dir()
+    if d is None:
+        return None
+    p = d / f"{name}.svg"
+    return p if p.exists() else None
+
+
+# 进程级默认渲染器
+default_icons = IconRenderer("auto")
+
+
+def icon(name: str) -> str:
+    return default_icons.text(name)
+
+
+def tool_icon(tool_name: str) -> str:
+    return default_icons.text(_TOOL_ICON.get(tool_name, "running"))
+
+
+def build_pngs(out_dir: str | Path, size: int = 24) -> list[str]:
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    r = IconRenderer("image")
+    made: list[str] = []
+    for name in ICONS:
+        data = r.rasterize(name, size=size)
+        if data:
+            (out / f"{name}.png").write_bytes(data)
+            made.append(f"{name}.png")
+    return made

nexforge/mcp/__init__.py

@@ -0,0 +1,168 @@
+"""MCP 客户端 —— 挂载外部 MCP server 的工具。
+
+从 config.toml 的 [[mcp]] 数组读取 server 定义(stdio / SSE / streamable-http),
+启动时握手 → 获取工具列表 → 包装成 McpTool 注入 ToolRegistry。
+
+设计(M1):仅 stdio 运输,一个 client 管理一个 server 生命周期。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from dataclasses import dataclass, field
+
+from nexforge.tools.base import BaseTool, ToolResult
+
+
+@dataclass
+class McpToolInfo:
+    name: str
+    description: str = ""
+    parameters: dict = field(default_factory=lambda: {"type": "object", "properties": {}})
+
+
+@dataclass
+class McpServerConfig:
+    name: str
+    transport: str = "stdio"  # stdio | sse | streamable-http
+    command: str = ""
+    args: list[str] = field(default_factory=list)
+    url: str = ""
+    env: dict[str, str] = field(default_factory=dict)
+
+
+class McpTool(BaseTool):
+    """包装来自 MCP server 的工具。"""
+
+    def __init__(self, info: McpToolInfo, call_fn):
+        self.name = info.name
+        self.description = info.description
+        self.parameters = info.parameters
+        self._call = call_fn
+        self.requires_approval = False
+        self.parallel_safe = True
+
+    def run(self, **kwargs) -> ToolResult:
+        """同步封包(Agent 在 asyncio.to_thread 中调用)。"""
+        try:
+            result = asyncio.get_event_loop().run_until_complete(self._call(kwargs))
+            return ToolResult(ok=True, output=result, summary=f"MCP {self.name}")
+        except Exception as exc:
+            return ToolResult(ok=False, error=f"MCP 工具调用失败:{exc}")
+
+
+class McpClient:
+    """管理一个 MCP server 的连接与工具清单。"""
+
+    def __init__(self, cfg: McpServerConfig) -> None:
+        self.cfg = cfg
+        self._process: asyncio.subprocess.Process | None = None
+        self._tools: list[McpToolInfo] = []
+        self._connected = False
+
+    @property
+    def connected(self) -> bool:
+        return self._connected
+
+    async def connect(self) -> list[McpToolInfo]:
+        """启动 server 子进程,做 initialize → tools/list 握手。"""
+        if self.cfg.transport == "stdio":
+            self._process = await asyncio.create_subprocess_exec(
+                self.cfg.command,
+                *self.cfg.args,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env={**__import__("os").environ, **self.cfg.env},
+            )
+            # initialize
+            init = await self._send_jsonrpc("initialize", {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "NexForgeCLI", "version": "0.1.0"},
+            })
+            if "error" in init:
+                await self.disconnect()
+                raise RuntimeError(f"MCP init 失败:{init['error']}")
+            # 发送 initialized 通知
+            await self._send_jsonrpc_note("notifications/initialized", {})
+            # tools/list
+            resp = await self._send_jsonrpc("tools/list", {})
+            tools = resp.get("result", {}).get("tools", [])
+            self._tools = [
+                McpToolInfo(
+                    name=t["name"],
+                    description=t.get("description", ""),
+                    parameters=t.get("inputSchema", {"type": "object", "properties": {}}),
+                )
+                for t in tools
+            ]
+            self._connected = True
+            return self._tools
+        # SSE / streamable-http 留 TODO(需要 httpx async client)
+        raise RuntimeError(f"不支持的 transport:{self.cfg.transport}")
+
+    async def call_tool(self, name: str, args: dict) -> str:
+        if not self._connected:
+            raise RuntimeError("未连接")
+        resp = await self._send_jsonrpc("tools/call", {"name": name, "arguments": args})
+        contents = resp.get("result", {}).get("content", [])
+        text = "\n".join(
+            c.get("text", str(c)) for c in contents if isinstance(c, dict)
+        )
+        return text or json.dumps(contents)
+
+    async def disconnect(self) -> None:
+        if self._process:
+            try:
+                self._process.stdin.close()
+            except Exception:
+                pass
+            try:
+                self._process.terminate()
+            except Exception:
+                pass
+            try:
+                await asyncio.wait_for(self._process.wait(), timeout=3)
+            except Exception:
+                self._process.kill()
+            self._process = None
+        self._connected = False
+
+    async def _send_jsonrpc(self, method: str, params: dict) -> dict:
+        assert self._process and self._process.stdin and self._process.stdout
+        msg = json.dumps(
+            {"jsonrpc": "2.0", "id": 1, "method": method, "params": params}
+        )
+        self._process.stdin.write(msg.encode() + b"\n")
+        await self._process.stdin.drain()
+        line = await asyncio.wait_for(self._process.stdout.readline(), timeout=15)
+        return json.loads(line.decode())
+
+    async def _send_jsonrpc_note(self, method: str, params: dict) -> None:
+        assert self._process and self._process.stdin
+        msg = json.dumps(
+            {"jsonrpc": "2.0", "method": method, "params": params}
+        )
+        self._process.stdin.write(msg.encode() + b"\n")
+        await self._process.stdin.drain()
+
+
+# ---- 便捷:从配置实例化多个 client ----------------------------------------------
+
+
+async def load_mcp_clients(config: "NexForgeConfig") -> list[McpClient]:  # noqa: F821
+    servers: list[dict] = getattr(config, "_raw_toml", {}).get("mcp", [])
+    clients: list[McpClient] = []
+    for raw in servers:
+        cfg = McpServerConfig(
+            name=raw.get("name", "unnamed"),
+            transport=raw.get("transport", "stdio"),
+            command=raw.get("command", ""),
+            args=raw.get("args", []),
+            url=raw.get("url", ""),
+            env=raw.get("env", {}),
+        )
+        clients.append(McpClient(cfg))
+    return clients

nexforge/provider/__init__.py

@@ -0,0 +1 @@
+"""集成层:DeepSeek Provider。"""

nexforge/provider/balance.py

@@ -0,0 +1,37 @@
+"""DeepSeek 余额查询。"""
+
+from __future__ import annotations
+
+
+async def fetch_balance(api_key: str) -> str:
+    """查询 DeepSeek 账户余额。返回 ¥xx.xx 格式。"""
+    import httpx
+
+    endpoints = [
+        "https://api.deepseek.com/user/balance",
+    ]
+    for url in endpoints:
+        try:
+            async with httpx.AsyncClient(timeout=15) as cli:
+                resp = await cli.get(
+                    url,
+                    headers={"Authorization": f"Bearer {api_key}"},
+                )
+                if resp.status_code != 200:
+                    continue
+                data = resp.json()
+                # {"is_available":true,"balance_infos":[{"currency":"CNY","total_balance":"24.94",...}]}
+                bal = None
+                cur = "CNY"
+                items = data.get("balance_infos", [])
+                if items:
+                    bal = items[0].get("total_balance")
+                    cur = items[0].get("currency", "CNY")
+                if bal is not None:
+                    try:
+                        return f"¥{float(bal):,.2f}"
+                    except (ValueError, TypeError):
+                        return f"¥{bal}"
+        except Exception:
+            continue
+    return "(无法获取)"

nexforge/provider/deepseek.py

@@ -0,0 +1,204 @@
+"""DeepSeek V4 Provider —— 基于 OpenAI 兼容 SDK。
+
+要点(核实自 api-docs.deepseek.com):
+- 模型:deepseek-v4-flash / deepseek-v4-pro
+- 思考模式:extra_body={"thinking":{"type":"enabled"|"disabled"}} + reasoning_effort
+- 思考链走 reasoning_content(流式为 delta.reasoning_content)
+- 思考模式忽略 temperature/top_p/penalty,故思考开启时不传这些参数
+- 工具调用的回合必须回传 reasoning_content(由 Session/Agent 负责)
+- 缓存字段:usage.prompt_cache_hit_tokens / prompt_cache_miss_tokens
+"""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator
+
+from openai import AsyncOpenAI
+
+from nexforge.config import Effort, NexForgeConfig, Tier
+from nexforge.core.types import (
+    AssistantMessage,
+    ChunkKind,
+    StreamChunk,
+    ToolCall,
+    Usage,
+)
+
+
+class ProviderError(RuntimeError):
+    """Provider 层的可读错误(缺 key、网络、API 报错)。"""
+
+
+def _extra(obj: Any, name: str) -> Any:
+    """从 openai 返回对象里取标准字段或 extra 字段(DeepSeek 自定义字段)。"""
+    val = getattr(obj, name, None)
+    if val is not None:
+        return val
+    extra = getattr(obj, "model_extra", None)
+    if isinstance(extra, dict):
+        return extra.get(name)
+    return None
+
+
+class DeepSeekProvider:
+    def __init__(self, config: NexForgeConfig):
+        self.config = config
+        key = config.resolve_api_key()
+        if not key:
+            raise ProviderError(
+                f"未找到 API Key。请设置环境变量 {config.provider.api_key_env},"
+                f"或在 {config.provider.base_url} 对应的 config.toml 中填写 api_key。"
+            )
+        self._client = AsyncOpenAI(
+            api_key=key,
+            base_url=config.provider.base_url,
+            timeout=config.provider.timeout,
+            max_retries=config.provider.max_retries,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.close()
+
+    def _build_kwargs(
+        self,
+        messages: list[dict],
+        tools: list[dict] | None,
+        tier: Tier | None,
+        thinking: bool | None,
+        effort: Effort | None,
+    ) -> dict:
+        cfg = self.config
+        think = cfg.models.thinking if thinking is None else thinking
+        eff = effort or cfg.models.reasoning_effort
+        # DeepSeek 专有参数走 extra_body(直接进请求体顶层)
+        extra_body: dict[str, Any] = {
+            "thinking": {"type": "enabled" if think else "disabled"}
+        }
+        if think:
+            extra_body["reasoning_effort"] = eff
+
+        kwargs: dict[str, Any] = {
+            "model": cfg.model_id(tier),
+            "messages": messages,
+            "stream": True,
+            "stream_options": {"include_usage": True},
+            "extra_body": extra_body,
+        }
+        # max_tokens vs max_completion_tokens(DeepSeek 推荐新参数)
+        if cfg.models.use_max_completion_tokens:
+            kwargs["max_completion_tokens"] = cfg.models.max_output_tokens
+        else:
+            kwargs["max_tokens"] = cfg.models.max_output_tokens
+        # 采样参数(仅 thinking=off 生效)
+        if not think:
+            m = cfg.models
+            if m.temperature is not None:
+                kwargs["temperature"] = m.temperature
+            if m.top_p is not None:
+                kwargs["top_p"] = m.top_p
+            if m.frequency_penalty is not None:
+                kwargs["frequency_penalty"] = m.frequency_penalty
+            if m.presence_penalty is not None:
+                kwargs["presence_penalty"] = m.presence_penalty
+            if m.stop is not None:
+                kwargs["stop"] = m.stop
+        # JSON Mode
+        if cfg.ui.json_mode:
+            kwargs["response_format"] = {"type": "json_object"}
+        # 工具 + tool_choice(plan 模式强制 none)
+        if tools:
+            kwargs["tools"] = tools
+            kwargs["tool_choice"] = "none" if cfg.ui.plan_mode else "auto"
+        return kwargs
+
+    async def stream(
+        self,
+        messages: list[dict],
+        *,
+        tools: list[dict] | None = None,
+        tier: Tier | None = None,
+        thinking: bool | None = None,
+        effort: Effort | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """流式请求,逐块产出 reasoning / content,结束时产出完整 AssistantMessage。"""
+        resolved_tier: Tier = tier or self.config.models.default_tier
+        model_id = self.config.model_id(tier)
+        kwargs = self._build_kwargs(messages, tools, tier, thinking, effort)
+
+        content = ""
+        reasoning = ""
+        tool_buf: dict[int, dict] = {}
+        usage = Usage()
+
+        try:
+            stream = await self._client.chat.completions.create(**kwargs)
+            async for chunk in stream:
+                # 用量(include_usage 时最后一块携带,choices 可能为空)
+                if getattr(chunk, "usage", None):
+                    u = chunk.usage
+                    usage = Usage(
+                        prompt_tokens=u.prompt_tokens or 0,
+                        completion_tokens=u.completion_tokens or 0,
+                        prompt_cache_hit_tokens=_extra(u, "prompt_cache_hit_tokens") or 0,
+                        prompt_cache_miss_tokens=_extra(u, "prompt_cache_miss_tokens") or 0,
+                    )
+                if not chunk.choices:
+                    continue
+                delta = chunk.choices[0].delta
+                rc = _extra(delta, "reasoning_content")
+                if rc:
+                    reasoning += rc
+                    yield StreamChunk(ChunkKind.REASONING, rc)
+                if getattr(delta, "content", None):
+                    content += delta.content
+                    yield StreamChunk(ChunkKind.CONTENT, delta.content)
+                if getattr(delta, "tool_calls", None):
+                    for tc in delta.tool_calls:
+                        slot = tool_buf.setdefault(
+                            tc.index, {"id": "", "name": "", "arguments": ""}
+                        )
+                        if tc.id:
+                            slot["id"] = tc.id
+                        fn = tc.function
+                        if fn and fn.name:
+                            slot["name"] = fn.name
+                        if fn and fn.arguments:
+                            slot["arguments"] += fn.arguments
+        except ProviderError:
+            raise
+        except Exception as exc:  # openai / 网络异常 → 统一为可读错误
+            raise ProviderError(f"DeepSeek 请求失败:{exc}") from exc
+
+        tool_calls = [
+            ToolCall(id=slot["id"], name=slot["name"], arguments=slot["arguments"])
+            for _, slot in sorted(tool_buf.items())
+            if slot["name"]
+        ]
+        message = AssistantMessage(
+            content=content,
+            reasoning_content=reasoning,
+            tool_calls=tool_calls,
+            usage=usage,
+            model=model_id,
+            tier=resolved_tier,
+        )
+        yield StreamChunk(ChunkKind.DONE, message=message)
+
+    async def complete(
+        self,
+        messages: list[dict],
+        *,
+        tools: list[dict] | None = None,
+        tier: Tier | None = None,
+        thinking: bool | None = None,
+        effort: Effort | None = None,
+    ) -> AssistantMessage:
+        """非流式便捷封装:消费整个流,返回最终消息。"""
+        final: AssistantMessage | None = None
+        async for ch in self.stream(
+            messages, tools=tools, tier=tier, thinking=thinking, effort=effort
+        ):
+            if ch.kind is ChunkKind.DONE:
+                final = ch.message
+        assert final is not None
+        return final

nexforge/skills/loader.py

@@ -0,0 +1,102 @@
+"""SKILL.md 技能加载器。
+
+目录约定:
+  ~/.nexforge/skills/  (全局)
+  .nexforge/skills/    (项目)
+
+文件格式:
+  ---
+  name: code-review
+  description: 审查当前分支 diff
+  allowed_tools: [read_file, search_content, git_diff]
+  model: pro          # 可选:flash|pro
+  ---
+  (markdown 正文,作为一次性系统提示注入)
+
+/ skill <name> 命令调用:正文注入为 system 消息,引导模型按技能剧本行事。
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+HOME_SKILLS = Path.home() / ".nexforge" / "skills"
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str = ""
+    body: str = ""
+    allowed_tools: list[str] = field(default_factory=list)
+    model: str = ""
+    source: str = ""  # 文件路径
+
+
+def _parse_frontmatter(text: str) -> tuple[dict, str]:
+    """解析 YAML 前导(极简:仅支持顶级 key: value)。"""
+    m = re.match(r"^---\s*\n(.*?)\n---\s*\n", text, re.DOTALL)
+    if not m:
+        return {}, text
+    meta = {}
+    for line in m.group(1).splitlines():
+        if ":" in line:
+            k, v = line.split(":", 1)
+            v = v.strip().strip('"').strip("'")
+            meta[k.strip()] = v
+    return meta, text[m.end():]
+
+
+def load_skill(path: Path) -> Skill | None:
+    if not path.is_file():
+        return None
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except Exception:
+        return None
+    meta, body = _parse_frontmatter(raw)
+    name = meta.get("name") or path.stem
+    return Skill(
+        name=name,
+        description=meta.get("description", ""),
+        body=body.strip(),
+        allowed_tools=[
+            t.strip() for t in meta.get("allowed_tools", "").strip("[]").split(",")
+            if t.strip()
+        ],
+        model=meta.get("model", ""),
+        source=str(path),
+    )
+
+
+def discover_skills(project_dir: Path | None = None) -> list[Skill]:
+    skills: dict[str, Skill] = {}  # 项目覆盖全局同名项
+
+    # 全局技能
+    if HOME_SKILLS.is_dir():
+        for p in HOME_SKILLS.rglob("*.md"):
+            if s := load_skill(p):
+                skills[s.name] = s
+
+    # 项目技能
+    if project_dir:
+        proj = project_dir / ".nexforge" / "skills"
+        if proj.is_dir():
+            for p in proj.rglob("*.md"):
+                if s := load_skill(p):
+                    skills[s.name] = s
+
+    return list(skills.values())
+
+
+def skill_index_str(skills: list[Skill]) -> str:
+    if not skills:
+        return ""
+    lines = ["\n## 可用技能(SKILL.md)\n"]
+    for s in skills:
+        desc = f" — {s.description}" if s.description else ""
+        model = f" (推荐 {s.model})" if s.model else ""
+        lines.append(f"- `/skill {s.name}`{desc}{model}")
+    return "\n".join(lines)

nexforge/store/__init__.py

@@ -0,0 +1 @@
+"""持久化存储层。"""