nexforge-cli 0.1.0__py3-none-any.whl

nexforge/core/agent.py

@@ -0,0 +1,244 @@
+"""AgentLoop —— 智能体主循环。
+
+以异步事件流形式产出(思考 / 正文 / 工具开始 / 工具结束 / 路由 / 完成),
+TUI 与 one-shot 模式共用同一循环。
+
+循环:向模型请求 → 若返回 tool_calls 则逐个执行并回灌结果 → 继续,
+直到模型不再调用工具(与 DeepSeek 官方 tool_calls 循环一致)。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from collections.abc import AsyncIterator, Awaitable, Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from nexforge.config import NexForgeConfig
+from nexforge.core.router import RouteDecision, Router
+from nexforge.core.session import Session
+from nexforge.core.types import AssistantMessage, ChunkKind
+from nexforge.provider.deepseek import DeepSeekProvider, ProviderError
+from nexforge.tools.base import BaseTool, ToolResult
+from nexforge.tools.registry import ToolRegistry, default_registry
+
+# 审批回调:传入 (tool, args),返回 bool(可为协程)。None 表示自动放行。
+ApproveFn = Callable[[BaseTool, dict], "bool | Awaitable[bool]"]
+
+
+class AgentEventKind(str, Enum):
+    ROUTE = "route"
+    REASONING = "reasoning"
+    CONTENT = "content"
+    TOOL_START = "tool_start"
+    TOOL_END = "tool_end"
+    TURN_DONE = "turn_done"
+    ERROR = "error"
+
+
+@dataclass
+class AgentEvent:
+    kind: AgentEventKind
+    text: str = ""
+    tool_name: str = ""
+    tool_preview: str = ""
+    tool_ok: bool = True
+    tool_summary: str = ""
+    route: RouteDecision | None = None
+    message: AssistantMessage | None = None
+
+
+async def _maybe_await(value: Any) -> Any:
+    if inspect.isawaitable(value):
+        return await value
+    return value
+
+
+class AgentLoop:
+    def __init__(
+        self,
+        config: NexForgeConfig,
+        provider: DeepSeekProvider,
+        session: Session,
+        registry: ToolRegistry | None = None,
+        approve: ApproveFn | None = None,
+    ):
+        self.config = config
+        self.provider = provider
+        self.session = session
+        self.registry = registry or default_registry()
+        if config.tools.enable_git_commit:
+            from nexforge.tools.registry import register_git_commit
+            register_git_commit(self.registry)
+        self.router = Router(config)
+        self._approve = approve
+
+    async def run_turn(self, user_text: str) -> AsyncIterator[AgentEvent]:
+        self.session.add_user(user_text)
+        tool_failures = 0
+        last_failed: tuple[str, str] = ("", "")
+        consecutive_fails = 0
+        try:
+            limit = self.config.tools.max_tool_iters
+            for _ in range(limit):
+                decision = self.router.choose(self.session, user_text, tool_failures)
+                yield AgentEvent(AgentEventKind.ROUTE, route=decision)
+
+                final_msg: AssistantMessage | None = None
+                active_tools = self._active_tools()
+                async for chunk in self.provider.stream(
+                    self.session.messages,
+                    tools=active_tools,
+                    tier=decision.tier,
+                    thinking=decision.thinking,
+                    effort=decision.effort,
+                ):
+                    if chunk.kind is ChunkKind.REASONING:
+                        yield AgentEvent(AgentEventKind.REASONING, text=chunk.text)
+                    elif chunk.kind is ChunkKind.CONTENT:
+                        yield AgentEvent(AgentEventKind.CONTENT, text=chunk.text)
+                    elif chunk.kind is ChunkKind.DONE:
+                        final_msg = chunk.message
+
+                assert final_msg is not None
+                self.session.add_assistant(final_msg)
+
+                if not final_msg.tool_calls:
+                    yield AgentEvent(AgentEventKind.TURN_DONE, message=final_msg)
+                    return
+
+                for tc in final_msg.tool_calls:
+                    args = self.registry.parse_args(tc.arguments)
+                    tool = self.registry.get(tc.name)
+                    preview = tool.preview(args) if tool else f"{tc.name}(?)"
+                    yield AgentEvent(
+                        AgentEventKind.TOOL_START,
+                        tool_name=tc.name,
+                        tool_preview=preview,
+                    )
+                    result = await self._exec_tool(tool, tc.name, args)
+                    self.session.add_tool_result(tc.id, result.to_content())
+                    if not result.ok:
+                        tool_failures += 1
+                        # 死循环检测:同一工具同一参数连续失败 3 次 → 注入提示
+                        fail_key = (tc.name, tc.arguments)
+                        if fail_key == last_failed:
+                            consecutive_fails += 1
+                        else:
+                            last_failed, consecutive_fails = fail_key, 1
+                        if consecutive_fails >= 3:
+                            self.session.messages.append({
+                                "role": "system",
+                                "content": (
+                                    f"[防死循环] 工具 {tc.name} 已连续失败 {consecutive_fails} 次。"
+                                    "请不要重复相同调用;换一种方法或跳过当前步骤,如无法完成则向用户说明原因并结束。"
+                                ),
+                            })
+                            consecutive_fails = 0  # 复位,避免重复注入
+                    else:
+                        # 成功 → 重置失败跟踪
+                        last_failed = ("", "")
+                        consecutive_fails = 0
+                    yield AgentEvent(
+                        AgentEventKind.TOOL_END,
+                        tool_name=tc.name,
+                        tool_ok=result.ok,
+                        tool_summary=result.summary or result.error or result.output[:60],
+                    )
+
+            yield AgentEvent(
+                AgentEventKind.ERROR,
+                text=f"已达工具调用轮数上限({limit}),停止本轮。",
+            )
+        except ProviderError as exc:
+            yield AgentEvent(AgentEventKind.ERROR, text=str(exc))
+
+    def _active_tools(self) -> list[dict]:
+        """根据当前模式返回可用工具 schema(plan 模式只读)。"""
+        all_specs = self.registry.specs()
+        if not self.config.ui.plan_mode:
+            return all_specs
+        READ_ONLY = {
+            "read_file", "list_dir", "search_content", "search_files",
+            "web_fetch", "git_status", "git_diff",
+        }
+        return [s for s in all_specs
+                if s.get("function", {}).get("name") in READ_ONLY]
+
+    async def _exec_tool(
+        self, tool: BaseTool | None, name: str, args: dict
+    ) -> ToolResult:
+        if tool is None:
+            return ToolResult(ok=False, error=f"未知工具:{name}")
+        # 权限判断
+        from nexforge.core.permissions import check as perm_check
+        action = perm_check(self.config.permissions.profile, name)  # type: ignore[arg-type]
+        if action == "ask" and self._approve is not None:
+            allowed = await _maybe_await(self._approve(tool, args))
+            if not allowed:
+                return ToolResult(ok=False, error="用户拒绝了该操作")
+        # 工具执行 + 超时保护
+        try:
+            return await asyncio.wait_for(
+                asyncio.to_thread(self.registry.execute, name, args),
+                timeout=self.config.tools.tool_timeout,
+            )
+        except asyncio.TimeoutError:
+            return ToolResult(ok=False, error=f"工具 {name} 执行超时({self.config.tools.tool_timeout}s)")
+
+
+# --------------------------------------------------------------------------
+# one-shot 模式:跑一轮,流式打印到 stdout,末尾把用量打到 stderr。
+# --------------------------------------------------------------------------
+
+def run_oneshot(config: NexForgeConfig, prompt: str) -> int:
+    import sys
+
+    async def _run() -> int:
+        try:
+            provider = DeepSeekProvider(config)
+        except ProviderError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+
+        session = Session()
+        agent = AgentLoop(config, provider, session)  # 自动放行工具(one-shot)
+        in_reasoning = False
+        had_error = False
+
+        async for ev in agent.run_turn(prompt):
+            if ev.kind is AgentEventKind.REASONING:
+                # 思考链输出到 stderr(灰色),不污染 stdout 主结果
+                if not in_reasoning:
+                    print("\033[2m", end="", file=sys.stderr)
+                    in_reasoning = True
+                print(ev.text, end="", flush=True, file=sys.stderr)
+            elif ev.kind is AgentEventKind.CONTENT:
+                if in_reasoning:
+                    print("\033[0m", file=sys.stderr)
+                    in_reasoning = False
+                print(ev.text, end="", flush=True)
+            elif ev.kind is AgentEventKind.TOOL_START:
+                print(f"\n\033[36m● {ev.tool_preview}\033[0m", file=sys.stderr)
+            elif ev.kind is AgentEventKind.TOOL_END:
+                mark = "✔" if ev.tool_ok else "✖"
+                print(f"  {mark} {ev.tool_summary}", file=sys.stderr)
+            elif ev.kind is AgentEventKind.ERROR:
+                print(f"\n\033[31m{ev.text}\033[0m", file=sys.stderr)
+                had_error = True
+            elif ev.kind is AgentEventKind.TURN_DONE:
+                u = session.total_usage
+                cost = u.cost_usd(config.price(config.models.default_tier))
+                print(
+                    f"\n\033[2m— tokens: {u.prompt_tokens}+{u.completion_tokens} "
+                    f"· ~${cost:.4f}\033[0m",
+                    file=sys.stderr,
+                )
+
+        print()  # 结尾换行
+        await provider.aclose()
+        return 1 if had_error else 0
+
+    return asyncio.run(_run())

nexforge/core/jobs.py

@@ -0,0 +1,97 @@
+"""后台作业管理器 —— 跑 dev server / 长任务,不阻塞主循环。
+
+进程级单例 JobManager 持有所有作业;工具层薄封装暴露给模型。
+"""
+
+from __future__ import annotations
+
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Job:
+    id: int
+    command: str
+    proc: subprocess.Popen
+    output: list[str] = field(default_factory=list)
+    _lock: threading.Lock = field(default_factory=threading.Lock)
+
+    @property
+    def running(self) -> bool:
+        return self.proc.poll() is None
+
+    @property
+    def exit_code(self) -> int | None:
+        return self.proc.poll()
+
+    def append(self, line: str) -> None:
+        with self._lock:
+            self.output.append(line)
+
+    def tail(self, n: int = 80) -> str:
+        with self._lock:
+            lines = self.output[-n:] if n else list(self.output)
+        return "".join(lines)
+
+
+class JobManager:
+    def __init__(self) -> None:
+        self._jobs: dict[int, Job] = {}
+        self._next_id = 1
+
+    def start(self, command: str) -> Job:
+        proc = subprocess.Popen(
+            command,
+            shell=True,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            bufsize=1,
+        )
+        self._jobs[job.id] = job
+        self._next_id += 1
+
+        def _pump() -> None:
+            assert proc.stdout is not None
+            for line in proc.stdout:
+                job.append(line)
+
+        threading.Thread(target=_pump, daemon=True).start()
+        return job
+
+    def get(self, job_id: int) -> Job | None:
+        return self._jobs.get(job_id)
+
+    def all(self) -> list[Job]:
+        return list(self._jobs.values())
+
+    def wait(self, job_id: int, timeout: float) -> Job | None:
+        job = self.get(job_id)
+        if job is None:
+            return None
+        deadline = time.time() + timeout
+        while job.running and time.time() < deadline:
+            time.sleep(0.1)
+        return job
+
+    def stop(self, job_id: int) -> Job | None:
+        job = self.get(job_id)
+        if job is None:
+            return None
+        if job.running:
+            job.proc.terminate()
+            try:
+                job.proc.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                job.proc.kill()
+        return job
+
+
+# 进程级单例
+job_manager = JobManager()

nexforge/core/permissions.py

@@ -0,0 +1,73 @@
+"""权限判断 —— 根据 profile 和工具名决定 allow/ask/deny。
+
+Profile:
+  safe       — 全部写操作需审批(审核模式)
+  supervised — 写文件自动,危险操作(删/Shell/git_commit)需审批(默认)
+  auto       — 全部放行(全自动)
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+Profile = Literal["safe", "supervised", "auto"]
+
+# 工具分类
+CATEGORIES: dict[str, str] = {
+    # 只读
+    "read_file": "read",
+    "list_dir": "read",
+    "search_content": "read",
+    "search_files": "read",
+    "web_fetch": "read",
+    "git_status": "read",
+    "git_diff": "read",
+    # 写文件
+    "write_file": "write_file",
+    "edit_file": "edit_file",
+    "multi_edit": "edit_file",
+    "create_dir": "manage_fs",
+    "move": "manage_fs",
+    "copy": "manage_fs",
+    # 危险操作
+    "delete": "danger",
+    "run_shell": "danger",
+    "run_background": "danger",
+    "stop_job": "danger",
+    "job_output": "read",
+    "wait_for_job": "read",
+    "list_jobs": "read",
+    "git_commit": "danger",
+}
+
+# 每个 profile 下各分类的权限:allow/ask/deny
+RULES: dict[Profile, dict[str, str]] = {
+    "safe": {
+        "read": "allow",
+        "write_file": "ask",
+        "edit_file": "ask",
+        "manage_fs": "ask",
+        "danger": "ask",
+    },
+    "supervised": {
+        "read": "allow",
+        "write_file": "allow",
+        "edit_file": "allow",
+        "manage_fs": "ask",
+        "danger": "ask",
+    },
+    "auto": {
+        "read": "allow",
+        "write_file": "allow",
+        "edit_file": "allow",
+        "manage_fs": "allow",
+        "danger": "allow",
+    },
+}
+
+
+def check(profile: Profile, tool_name: str) -> str:
+    """返回 'allow'/'ask'/'deny'。"""
+    cat = CATEGORIES.get(tool_name, "danger")  # 未知工具当危险
+    rule = RULES.get(profile, {})
+    return rule.get(cat, "ask")

nexforge/core/router.py

@@ -0,0 +1,62 @@
+"""auto 档位的客户端路由器。
+
+官方无 auto 模型,这里在客户端决定 (model 档位, thinking, effort):
+- default_tier 明确为 flash/pro 时:直接采用,不路由。
+- default_tier=auto 时:默认 flash 起步;命中升级信号 → pro + 思考 + 更高 effort。
+升级信号:关键词、上下文体量、同一任务工具连续失败次数。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from nexforge.config import Effort, NexForgeConfig, Tier
+from nexforge.core.session import Session
+
+
+@dataclass
+class RouteDecision:
+    tier: Tier
+    thinking: bool
+    effort: Effort
+    reason: str = ""
+
+
+class Router:
+    def __init__(self, config: NexForgeConfig):
+        self.config = config
+
+    def choose(
+        self, session: Session, user_text: str, tool_failures: int = 0
+    ) -> RouteDecision:
+        cfg = self.config
+        # 非 auto:尊重用户显式选择
+        if cfg.models.default_tier != "auto":
+            return RouteDecision(
+                tier=cfg.models.default_tier,
+                thinking=cfg.models.thinking,
+                effort=cfg.models.reasoning_effort,
+                reason="固定档位",
+            )
+
+        r = cfg.router
+        text_low = user_text.lower()
+        hit_kw = next((k for k in r.escalate_keywords if k.lower() in text_low), None)
+        big_ctx = session.approx_context_tokens() >= r.escalate_context_tokens
+        many_fail = tool_failures >= r.escalate_on_tool_failures
+
+        if hit_kw or big_ctx or many_fail:
+            why = (
+                f"关键词'{hit_kw}'" if hit_kw
+                else "上下文过大" if big_ctx
+                else f"工具失败×{tool_failures}"
+            )
+            return RouteDecision(
+                tier=r.escalate_to, thinking=True, effort="max",
+                reason=f"升级→{r.escalate_to}({why})",
+            )
+
+        return RouteDecision(
+            tier=r.entry, thinking=cfg.models.thinking,
+            effort=cfg.models.reasoning_effort, reason=f"默认{r.entry}",
+        )

nexforge/core/session.py

@@ -0,0 +1,55 @@
+"""会话状态:消息列表 + 累计用量。
+
+关键规则(DeepSeek):发生工具调用的回合,assistant 的 reasoning_content
+必须回传给 API,否则 400;无工具调用的最终回合无需回传。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from nexforge.core.types import AssistantMessage, Usage
+
+DEFAULT_SYSTEM = (
+    "你是 NexForgeCLI,一个运行在终端里的智能体助手,由 DeepSeek V4 驱动。\n"
+    "你可以调用工具读写文件、执行命令来完成用户的编码任务。\n"
+    "回答用简洁的中文;修改文件用 edit_file 工具;需要执行命令用 run_shell。\n"
+    "完成任务后用一两句话总结你做了什么。\n"
+    "不要用 emoji(📦🌤等),用纯文本或 Markdown 列表/表格表示信息。\n"
+    "执行 Shell 命令前先用 run_shell 探测操作系统(Windows用cmd命令,Linux/macOS用bash命令)。"
+)
+
+
+@dataclass
+class Session:
+    system_prompt: str = DEFAULT_SYSTEM
+    messages: list[dict] = field(default_factory=list)
+    total_usage: Usage = field(default_factory=Usage)
+
+    def __post_init__(self) -> None:
+        if not self.messages:
+            self.messages.append({"role": "system", "content": self.system_prompt})
+
+    def add_user(self, text: str) -> None:
+        self.messages.append({"role": "user", "content": text})
+
+    def add_assistant(self, msg: AssistantMessage) -> None:
+        # 始终回传 reasoning_content(DeepSeek 多轮思考对话要求)
+        include_reasoning = bool(msg.reasoning_content)
+        self.messages.append(msg.to_message_dict(include_reasoning=include_reasoning))
+        if msg.usage:
+            self.total_usage = self.total_usage + msg.usage
+
+    def add_tool_result(self, tool_call_id: str, content: str) -> None:
+        self.messages.append(
+            {"role": "tool", "tool_call_id": tool_call_id, "content": content}
+        )
+
+    def inject_skill_index(self, idx: str) -> None:
+        """在 system 消息后插入技能索引。"""
+        if idx and self.messages:
+            self.messages.insert(1, {"role": "system", "content": idx})
+
+    def approx_context_tokens(self) -> int:
+        chars = sum(len(str(m.get("content") or "")) for m in self.messages)
+        return chars // 4

nexforge/core/types.py

@@ -0,0 +1,103 @@
+"""核心数据类型:消息、工具调用、用量、流式事件。
+
+设计成 provider 与 agent/ui 之间的稳定契约,避免各处直接依赖 openai 的返回类型。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+@dataclass
+class Usage:
+    """一次请求的 token 用量(含 DeepSeek 缓存命中拆分)。"""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    prompt_cache_hit_tokens: int = 0
+    prompt_cache_miss_tokens: int = 0
+
+    def normalized(self) -> "Usage":
+        """若没有 hit/miss 拆分,则把全部输入按未命中计,保证费用不低估。"""
+        if self.prompt_cache_hit_tokens == 0 and self.prompt_cache_miss_tokens == 0:
+            return Usage(
+                prompt_tokens=self.prompt_tokens,
+                completion_tokens=self.completion_tokens,
+                prompt_cache_hit_tokens=0,
+                prompt_cache_miss_tokens=self.prompt_tokens,
+            )
+        return self
+
+    def cost_usd(self, price: Any) -> float:
+        """price 为 config.PricingTier(每百万 token 单价)。"""
+        u = self.normalized()
+        return (
+            u.prompt_cache_hit_tokens * price.input_cache_hit
+            + u.prompt_cache_miss_tokens * price.input_cache_miss
+            + u.completion_tokens * price.output
+        ) / 1_000_000
+
+    def __add__(self, other: "Usage") -> "Usage":
+        return Usage(
+            prompt_tokens=self.prompt_tokens + other.prompt_tokens,
+            completion_tokens=self.completion_tokens + other.completion_tokens,
+            prompt_cache_hit_tokens=self.prompt_cache_hit_tokens
+            + other.prompt_cache_hit_tokens,
+            prompt_cache_miss_tokens=self.prompt_cache_miss_tokens
+            + other.prompt_cache_miss_tokens,
+        )
+
+
+@dataclass
+class ToolCall:
+    """模型请求的一次工具调用(OpenAI 格式)。arguments 为原始 JSON 串。"""
+
+    id: str
+    name: str
+    arguments: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "type": "function",
+            "function": {"name": self.name, "arguments": self.arguments},
+        }
+
+
+@dataclass
+class AssistantMessage:
+    """一轮助手输出:正文 + 思考链 + 工具调用。"""
+
+    content: str = ""
+    reasoning_content: str = ""
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    usage: Usage | None = None
+    model: str = ""
+    tier: str = ""
+
+    def to_message_dict(self, *, include_reasoning: bool) -> dict:
+        """转成可回灌 API 的 assistant 消息。
+
+        include_reasoning:发生工具调用的回合必须为 True(否则 DeepSeek 返回 400)。
+        """
+        msg: dict = {"role": "assistant", "content": self.content or ""}
+        if self.tool_calls:
+            msg["tool_calls"] = [tc.to_dict() for tc in self.tool_calls]
+        if include_reasoning and self.reasoning_content:
+            msg["reasoning_content"] = self.reasoning_content
+        return msg
+
+
+class ChunkKind(str, Enum):
+    REASONING = "reasoning"  # 思考链增量
+    CONTENT = "content"      # 正文增量
+    DONE = "done"            # 结束,携带完整 AssistantMessage
+
+
+@dataclass
+class StreamChunk:
+    kind: ChunkKind
+    text: str = ""
+    message: AssistantMessage | None = None  # 仅 DONE 携带