zrcoder 0.2.0__tar.gz → 0.4.0__tar.gz

{zrcoder-0.2.0 → zrcoder-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zrcoder
-Version: 0.2.0
+Version: 0.4.0
 Summary: Terminal coding agent chat — OpenAI-compatible APIs, tools, and slash commands
 Keywords: cli,agent,coding,terminal,openai
 Author: Zr
@@ -18,6 +18,7 @@ Classifier: Topic :: Software Development
 Requires-Dist: prompt-toolkit>=3.0.53
 Requires-Dist: pydantic-ai>=2.40.0
 Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: questionary>=2.1.1
 Requires-Dist: rich>=15.0.0
 Requires-Python: >=3.12
 Project-URL: Homepage, https://github.com/ZRMYDYCG/ClaudeCode
@@ -28,7 +29,11 @@ Description-Content-Type: text/markdown
 
 # Zrcoder
 
-终端里的编程助手：连 OpenAI 兼容 API，可读写文件、执行命令，并支持 `/help` 等斜杠命令。
+<p align="center">
+  <img src="docs/zrcoder-banner.jpg" alt="Zrcoder — AI Terminal CLI" width="100%">
+</p>
+
+终端里的编程助手：连 OpenAI 兼容 API，可读写文件、执行命令，并支持斜杠命令与会话恢复。
 
 ## 安装
 
@@ -48,7 +53,11 @@ pip install zrcoder
 
 ## 配置
 
-在环境变量或项目目录的 `.env` 中设置（可参考 `.env.example`）：
+设置环境变量，或在以下位置之一创建 `.env`（可参考 `.env.example`）：
+
+- 当前目录：`./.env`
+- 用户配置：`~/.config/zrcoder/.env`
+- 兼容路径：`~/.zrcoder.env`
 
 ```bash
 export API_KEY=your_api_key
@@ -63,7 +72,7 @@ export BASE_URL=https://api.example.com/v1
 zrcoder
 ```
 
-常用命令：`/help`、`/status`、`/new`、`/api-detail`、`/exit`。
+常用命令：`/help`、`/status`、`/new`、`/resume`、`/api-detail`、`/exit`。
 
 ## 变更与发版
 

{zrcoder-0.2.0 → zrcoder-0.4.0}/README.md

@@ -1,6 +1,10 @@
 # Zrcoder
 
-终端里的编程助手：连 OpenAI 兼容 API，可读写文件、执行命令，并支持 `/help` 等斜杠命令。
+<p align="center">
+  <img src="docs/zrcoder-banner.jpg" alt="Zrcoder — AI Terminal CLI" width="100%">
+</p>
+
+终端里的编程助手：连 OpenAI 兼容 API，可读写文件、执行命令，并支持斜杠命令与会话恢复。
 
 ## 安装
 
@@ -20,7 +24,11 @@ pip install zrcoder
 
 ## 配置
 
-在环境变量或项目目录的 `.env` 中设置（可参考 `.env.example`）：
+设置环境变量，或在以下位置之一创建 `.env`（可参考 `.env.example`）：
+
+- 当前目录：`./.env`
+- 用户配置：`~/.config/zrcoder/.env`
+- 兼容路径：`~/.zrcoder.env`
 
 ```bash
 export API_KEY=your_api_key
@@ -35,7 +43,7 @@ export BASE_URL=https://api.example.com/v1
 zrcoder
 ```
 
-常用命令：`/help`、`/status`、`/new`、`/api-detail`、`/exit`。
+常用命令：`/help`、`/status`、`/new`、`/resume`、`/api-detail`、`/exit`。
 
 ## 变更与发版
 

zrcoder-0.4.0/core/agent/hooks.py

@@ -0,0 +1,179 @@
+"""
+挂在 Agent 上的 hooks：
+1. API 调用元数据记录（/api-detail 命令用）
+2. API 请求失败时的自动重试（wrap_model_request）
+3. 工具调用权限检查（on_tool_execute）
+4. 工具执行异常的兜底处理（on_tool_execute_error）
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any
+
+from pydantic_ai.capabilities import Hooks
+from pydantic_ai.exceptions import ModelAPIError, ModelHTTPError, UnexpectedModelBehavior
+
+from core import permissions
+from core.ui.render import console
+
+MAX_RETRIES = 3
+
+
+@dataclass
+class ApiCall:
+    """
+    一次 model API 调用的元数据。before_model_request 创建并填充上半部分，
+    after_model_request 填充下半部分。
+    """
+
+    # request 侧
+    model: str
+    messages_count: int
+    # 这次发送给模型的 messages 中最后一条消息的最后一个 part
+    last_part: Any
+    tools: list[str]
+    # response 侧（after hook 填充）
+    finish_reason: str = ""
+    parts_kinds: list[str] = field(default_factory=list)
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+# 主循环在每轮 agent.iter() 之前清空它
+api_call_log: list[ApiCall] = []
+
+hooks = Hooks()
+
+
+# ---------- API 调用记录 ----------
+
+
+@hooks.on.before_model_request
+async def _record_request(ctx: Any, request_context: Any) -> Any:
+    """
+    每次发起 model 调用之前，创建一条 ApiCall 记录。
+    """
+    msgs = list(request_context.messages)
+    last_part = msgs[-1].parts[-1] if msgs and msgs[-1].parts else None
+    try:
+        tool_names = [t.name for t in request_context.model_request_parameters.function_tools]
+    except AttributeError:
+        tool_names = []
+    api_call_log.append(
+        ApiCall(
+            model=request_context.model.model_name,
+            messages_count=len(msgs),
+            last_part=last_part,
+            tools=tool_names,
+        )
+    )
+    return request_context
+
+
+@hooks.on.after_model_request
+async def _record_response(ctx: Any, *, request_context: Any, response: Any) -> Any:
+    """
+    每次 model 调用返回后，填充上面这条 ApiCall 的 response 字段。
+    """
+    if api_call_log:
+        call = api_call_log[-1]
+        call.finish_reason = str(response.finish_reason) if response.finish_reason else "unknown"
+        call.parts_kinds = [p.part_kind for p in response.parts]
+        call.input_tokens = response.usage.input_tokens
+        call.output_tokens = response.usage.output_tokens
+    return response
+
+
+# ---------- API 请求重试 ----------
+
+
+@hooks.on.model_request
+async def _retry_on_error(ctx: Any, *, request_context: Any, handler: Any) -> Any:
+    """
+    包裹 model 请求，遇到可重试错误时自动指数退避重试。
+
+    重试在 wrap 内部完成，对话历史和 before/after hooks 不受影响。
+    兼容网关偶发的 UnexpectedModelBehavior（响应 schema 不对）也会重试。
+    """
+    for attempt in range(MAX_RETRIES + 1):
+        try:
+            return await handler(request_context)
+        except ModelHTTPError as e:
+            if e.status_code < 500:
+                raise
+            if attempt >= MAX_RETRIES:
+                console.print(f"[bold red]✗ HTTP {e.status_code}，重试 {MAX_RETRIES} 次后仍失败[/]")
+                raise
+            wait = 2**attempt
+            console.print(
+                f"[bold yellow]⟳ HTTP {e.status_code}，{wait}s 后重试 "
+                f"({attempt + 1}/{MAX_RETRIES})...[/]"
+            )
+            await asyncio.sleep(wait)
+        except UnexpectedModelBehavior as e:
+            if attempt >= MAX_RETRIES:
+                console.print(f"[bold red]✗ 模型响应异常，重试 {MAX_RETRIES} 次后仍失败：{e}[/]")
+                raise
+            wait = 2**attempt
+            console.print(
+                f"[bold yellow]⟳ 模型响应异常，{wait}s 后重试 ({attempt + 1}/{MAX_RETRIES})...[/]"
+            )
+            await asyncio.sleep(wait)
+        except ModelAPIError:
+            if attempt >= MAX_RETRIES:
+                console.print(f"[bold red]✗ 网络连接失败，重试 {MAX_RETRIES} 次后仍无法连接[/]")
+                raise
+            wait = 2**attempt
+            console.print(
+                f"[bold yellow]⟳ 网络连接失败，{wait}s 后重试 ({attempt + 1}/{MAX_RETRIES})...[/]"
+            )
+            await asyncio.sleep(wait)
+
+    raise RuntimeError("unreachable")  # pragma: no cover
+
+
+# ---------- 工具调用权限检查 ----------
+
+
+@hooks.on.tool_execute
+async def _check_permission(ctx: Any, *, call: Any, tool_def: Any, args: Any, handler: Any) -> Any:
+    """
+    工具执行前的权限关卡。allow 就调用 handler 真正执行；
+    ask 就弹审批列表；deny 则把拒绝原因当作工具结果回填，让模型自行纠正。
+    """
+    decision = permissions.compute_decision(call.tool_name, args)
+    if decision == "allow":
+        # 放行，handler(args) 才是真正执行工具的那一步
+        return await handler(args)
+
+    # decision == "ask"，弹审批让用户决定
+    choice = await permissions.prompt_approval(call.tool_name, args)
+    if choice == "once":
+        return await handler(args)
+    if choice == "always":
+        # 记进会话白名单，本会话内这个工具不再询问
+        permissions.state.session_allowed.add(call.tool_name)
+        return await handler(args)
+
+    # 拒绝：不执行工具，把拒绝原因回填给模型，让它停下来等用户发话，而不是自作主张绕过去
+    return (
+        f"用户拒绝了对 {call.tool_name} 的调用，这次调用没有执行。"
+        "请停下手上的事，等用户告诉你接下来该怎么做。"
+    )
+
+
+# ---------- 工具执行异常兜底 ----------
+
+
+@hooks.on.tool_execute_error
+async def _handle_tool_error(
+    ctx: Any, *, call: Any, tool_def: Any, args: Any, error: Exception
+) -> str:
+    """
+    工具函数抛出未捕获异常时，不让进程崩溃，
+    而是把错误信息作为 tool result 返回给模型，让它自行纠正。
+    """
+    console.print(f"[bold red]✗ 工具 {call.tool_name} 出错：{error}[/]")
+    return f"工具执行出错：{type(error).__name__}: {error}"

zrcoder-0.4.0/core/agent/tools.py

@@ -0,0 +1,96 @@
+"""
+Coding Agent 用到的三个工具：读文件、写文件、跑 shell 命令。
+
+每个工具自己处理已知错误：能靠换参数纠正的（路径不存在、没权限）抛 ModelRetry
+让模型重试，不能纠正的（二进制文件、命令出错）直接返回错误信息。
+意料之外的异常由 hooks 里的 on_tool_execute_error 统一兜底。
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from typing import Any
+
+from pydantic_ai.exceptions import ModelRetry
+
+from core import permissions
+
+
+def read_file(path: str) -> str:
+    """
+    读取指定文件的内容。
+    """
+    try:
+        with open(path, encoding="utf-8") as f:
+            return f.read()
+    except FileNotFoundError as e:
+        raise ModelRetry(f"文件 {path} 不存在，请确认路径或换一个文件") from e
+    except PermissionError as e:
+        raise ModelRetry(f"没有权限读取 {path}，请换一个可读的文件") from e
+    except IsADirectoryError as e:
+        raise ModelRetry(f"{path} 是一个目录，请指定目录下的具体文件") from e
+    except UnicodeDecodeError:
+        return f"错误：{path} 不是文本文件，无法读取"
+
+
+def write_file(path: str, content: str) -> str:
+    """
+    将内容写入指定文件。
+    """
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(content)
+        return f"已写入 {path}"
+    except FileNotFoundError as e:
+        raise ModelRetry(f"目录不存在，无法写入 {path}，请换一个已存在的目录") from e
+    except PermissionError as e:
+        raise ModelRetry(f"没有权限写入 {path}，请换一个可写的路径") from e
+    except OSError as e:
+        return f"错误：写入 {path} 失败 ({e})"
+
+
+def run_command(command: str) -> str:
+    """
+    执行一条 shell 命令并返回输出。
+    """
+    try:
+        result = subprocess.run(
+            command, shell=True, capture_output=True, text=True, errors="replace", timeout=10
+        )
+        output = result.stdout
+        if result.returncode != 0:
+            output += f"\n[错误] {result.stderr}"
+        return output or "(无输出)"
+    except subprocess.TimeoutExpired:
+        return "[错误] 命令执行超时（10秒）"
+    except OSError as e:
+        return f"[错误] 无法执行命令 ({e})"
+
+
+# 高危命令的特征：删除文件、提权、直写磁盘
+DANGEROUS_PATTERNS = [
+    r"\brm\b",
+    r"\bsudo\b",
+    r"\bdd\b",
+    r"\bmkfs\w*\b",
+]
+
+
+def run_command_self_check(args: dict[str, Any]) -> str | None:
+    """
+    run_command 的权限自检：扫一遍命令字符串，命中高危特征就要求审批。
+    误伤的代价不过是多弹一次窗，绝不能把真正的高危命令漏过去。
+    """
+    command = str(args.get("command", ""))
+    if any(re.search(pattern, command) for pattern in DANGEROUS_PATTERNS):
+        return "ask"
+    # 没命中高危特征，交给通用规则决定
+    return None
+
+
+# 把自检挂到权限模块的注册表上
+permissions.register_self_check("run_command", run_command_self_check)
+
+# Pydantic AI 支持 tools=[plain_function]，从函数签名 + docstring 自动生成 JSON Schema
+TOOLS = [read_file, write_file, run_command]

zrcoder-0.4.0/core/cli.py

@@ -0,0 +1,119 @@
+"""
+终端主循环：读输入、分发斜杠命令、驱动 Agent。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any, Literal
+
+from pydantic_ai import Agent
+from pydantic_graph import End
+
+from core.agent import MODEL_NAME, agent, api_call_log
+from core.session import append_messages, new_session_id
+from core.ui.commands import COMMANDS, SessionState, print_part
+from core.ui.input import Repl
+from core.ui.render import console, print_welcome_banner
+
+CommandAction = Literal["pass", "continue", "break"]
+
+
+async def handle_command(user_input: str, state: SessionState) -> CommandAction:
+    """
+    处理以 / 开头的命令。
+    返回 'pass'：不是命令，交给 Agent；
+    返回 'continue'：命令已处理，进入下一轮；
+    返回 'break'：命令要求退出程序。
+    """
+    if not user_input.startswith("/"):
+        return "pass"
+    cmd_name = user_input[1:].split()[0]
+    command = COMMANDS.get(cmd_name)
+    if command is None:
+        console.print(f"未知命令：/{cmd_name}，输入 /help 查看可用命令\n")
+        return "continue"
+    result = command.handler(state)
+    # 个别命令（如 /resume）要弹交互式列表，是异步的，需要 await
+    if inspect.isawaitable(result):
+        result = await result
+    return "continue" if result else "break"
+
+
+def apply_result(state: SessionState, result: Any) -> None:
+    """
+    跑完一轮 Agent 后，把结果同步到 SessionState，并追加写入会话文件。
+    """
+    state.history = result.all_messages()
+    usage = result.usage
+    state.input_tokens += usage.input_tokens
+    state.output_tokens += usage.output_tokens
+    state.last_api_calls = list(api_call_log)
+    append_messages(state.session_id, result.new_messages())
+
+
+async def run_agent_loop(user_input: str, state: SessionState) -> None:
+    """
+    展开 agent.run_sync()，逐节点驱动 Agent 循环，每步实时打印。
+    """
+    api_call_log.clear()
+
+    async with agent.iter(user_input, message_history=state.history) as run:
+        node = run.next_node
+
+        while not isinstance(node, End):
+            node = await run.next(node)
+
+            if Agent.is_call_tools_node(node):
+                for response_part in node.model_response.parts:
+                    print_part(response_part)
+
+            elif Agent.is_model_request_node(node):
+                for request_part in node.request.parts:
+                    kind = getattr(request_part, "part_kind", None)
+                    if kind in ("tool-return", "retry-prompt"):
+                        print_part(request_part)
+
+        apply_result(state, run.result)
+    console.print()
+
+
+async def async_main() -> None:
+    state = SessionState(
+        model_name=MODEL_NAME,
+        session_id=new_session_id(),
+    )
+    print_welcome_banner("Zrcoder")
+
+    # 常驻输入区：输入框整个会话期间不消失
+    repl = Repl(state)
+
+    async def on_submit(user_input: str) -> None:
+        # 每次回车提交一行输入，都走这里
+        # 先处理 / 开头的命令
+        action = await handle_command(user_input, state)
+        if action == "break":
+            # 命令要求退出，结束常驻输入区
+            repl.exit()
+            return
+        if action == "continue":
+            return
+
+        # 核心 Agent 循环：开请求时显示 working...，结束 / 被打断后由 Repl 统一隐藏；
+        # 中途按 ESC / Ctrl+C 会打断
+        repl.start_working()
+        await run_agent_loop(user_input, state)
+
+    await repl.run(on_submit)
+
+
+def main() -> None:
+    try:
+        asyncio.run(async_main())
+    except (KeyboardInterrupt, EOFError):
+        pass
+
+
+if __name__ == "__main__":
+    main()