PatchPal：极简AI编码代理实现-平芜编程栈

代理编码助手现在已广泛普及（例如Aider、Claude Code、OpenCode）。在花时间使用Claude Code和OpenCode后，我想要一些可以在本地运行、端到端检查、无需浏览大型框架即可修改和扩展的东西。

这种好奇心导致了开发一个开源的、基于Python的代理编码助手，名为PatchPal。

**PatchPal**是一个精简的受Claude Code启发的AI编码代理，纯粹用Python实现，旨在帮助完成以下工作：

构建、调试和修改软件
数据分析和可视化，包括通过网页抓取和API交互进行数据策划
研究问题并报告综合发现（例如网页搜索、日志文件分析）
自动化任务并使用技能、工具和即时代码生成/执行解决问题
基于权限的交互模型与Claude Code使用的模型一致，提供了熟悉的工作流程。

与许多较大的编码代理不同，PatchPal故意保持小巧和透明：

$ ls patchpal __init__.py agent.py cli.py context.py permissions.py skills.py system_prompt.md tool_schema.py tools.py

1、如何安装

PatchPal通过PyPI分发：

pip install patchpal

支持Linux、macOS和Windows。

2、快速开始

PatchPal支持通过LiteLLM使用云模型和本地模型。

选项1：云模型（最快尝试）

设置API密钥并运行patchpal命令：

# 使用Anthropic（默认模型目前是Claude Sonnet 4.5） export ANTHROPIC_API_KEY=your_key_here patchpal # 使用Anthropic的Claude Opus 4.5代替默认模型 patchpal --model anthropic/claude-opus-4-5 # 使用OpenAI模型 export OPENAI_API_KEY=your_key_here patchpal --model openai/gpt-5.2 # 或gpt-5-mini、gpt-4o等 # 使用LiteLLM包支持的任何提供商 # 例如，AWS上的bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0 patchpal --model <在此输入litellm模型路径>

PatchPal兼容LiteLLM包支持的每个LLM提供商。默认模型目前是Anthropic的Claude Sonnet 4.5——与Claude Code相同。

选项2：使用Ollama的本地模型

Ollama也很好用，有一个重要要求：你必须将上下文窗口增加到至少32K token。

# 必需：增加上下文大小 export OLLAMA_CONTEXT_LENGTH=32768 # 启动Ollama ollama serve # 使用Ollama运行PatchPal patchpal --model ollama_chat/gpt-oss:20b

没有更大的上下文窗口，代理工作流会以微妙的方式失败——这是最常见的Ollama陷阱。此外，并非所有Ollama模型都能在工具调用代理工作流中很好地工作。Ollama推荐的一些模型是gpt-oss和qwen3-coder。

选项3：使用vLLM的本地模型

如果你有较大的GPU，你还可以使用vLLM以更高性能的方式本地运行模型。

vllm serve openai/gpt-oss-20b \ --api-key token-abc123 \ --tool-call-parser openai \ --enable-auto-tool-choice

然后，在另一个终端：

export HOSTED_VLLM_API_BASE=http://localhost:8000 export HOSTED_VLLM_API_KEY=token-abc123 patchpal --model hosted_vllm/openai/gpt-oss-20b

示例任务

启动后，PatchPal支持与Claude Code类似的对话交互。

3、构建应用或新功能

在下面的示例中，我们使用从SCOTUSblog网页抓取的数据构建一个最高法院案件的Streamlit仪表板。最终应用包括仪表板和一个用于收集和策划数据的网页抓取脚本。

应用构建示例。### 3.1 修复错误

IEEE Spectrum最近发表了一篇题为AI编码助手正在变得更糟的文章。然而，我们发现文章中的实验不支持作者的中心主张。下面的示例演示了作者声称当前LLM无法可靠解决的以下代码问题的解决方案：

# 损坏的代码 df = pd.read_csv('data.csv') df['new_column'] = df['index_value'] + 1 #没有'index_value'列

错误修复示例### 3.2 数据分析和可视化

除了代码编辑之外，代理编码助手还可用于数据分析和可视化，以及数据策划和网页抓取。

在生成前5个下载量最大的Python包的条形图时，代理将默认遵循透明的、基于权限的工作流程：

来源识别：代理启动自主网页搜索以识别Python包下载统计数据的权威数据源。它首先请求用户许可继续执行建议的搜索查询。
数据获取：在找到合适的数据源后，代理提示用户许可访问（下载和解析）分析所需的网页内容。
代码生成和执行：然后代理生成必要的Python代码来处理数据、创建条形图并显示可视化。它在执行此代码之前请求最终用户授权。

数据分析和可视化示例## 4、技能：可复用的代理工作流

PatchPal还支持代理技能，这是一种用于用Markdown编写的可复用、命名工作流的开放格式。

你可以使用skills-creator技能为代理创建新技能，然后简单地将它们放到~/.patchpal/skills文件夹中供PatchPal使用。（Anthropic还维护着一个更大的代理技能公共存储库，所有这些都与PatchPal兼容。）

PatchPal的可配置技能系统## 5、创建你自己的工具

虽然技能为代理提供了要遵循的指令和模板，但自定义工具通过可执行的Python函数扩展了代理的功能，这些函数按需运行。

将一个.py文件放到~/.patchpal/tools/中，PatchPal会在启动时自动发现并集成你的函数。然后代理可以像调用任何内置工具一样调用它们。

实现很简单：编写一个带有类型提示和文档字符串的函数，PatchPal会自动生成LLM工具模式。希望代理查询你的数据库？解析你的自定义文件格式？调用你公司的API？只需编写函数，代理就知道如何使用它。

在下面的示例中，我们实现了一个简单的计算器工具calculator.py，代理可以使用它。

"""文件名：calculator.py PatchPal的示例自定义工具。 此文件演示如何创建扩展PatchPal功能的自定义工具。工具从~/.patchpal/tools/自动发现 工具函数的要求： - 所有参数的类型提示 - 带有描述和Args部分的文档字符串 - 模块级函数（非嵌套） - 返回类型通常应为str（供LLM消费） """ def add(x: int, y: int) -> str: """将两个数字相加。 Args: x: 第一个数字 y: 第二个数字 Returns: 和作为字符串 """ result = x + y return f"{x} + {y} = {result}" def subtract(x: int, y: int) -> str: """减去两个数字。 Args: x: 第一个数字 y: 从x中减去的第二个数字 Returns: 差作为字符串 """ result = x - y return f"{x} - {y} = {result}" def multiply(x: float, y: float) -> str: """将两个数字相乘。 Args: x: 第一个数字 y: 第二个数字 Returns: 积作为字符串 """ result = x * y return f"{x} × {y} = {result}" def divide(x: float, y: float) -> str: """将两个数字相除。 Args: x: 分子 y: 分母 Returns: 商作为字符串 """ if y == 0: return "错误：不能除以零" result = x / y return f"{x} ÷ {y} = {result}"

工具在需要时由代理自动使用：

你：12345*654是多少？ 🤔 思考中... 🔧 multiply({'x': 12345, 'y': 654}) 🤔 思考中... =================================== 代理 =================================== 12345 × 654 = 8,073,630 ===================================

自定义工具超越了文件操作和shell命令，进入特定领域的任务——分析业务数据、检查系统健康、处理自定义文件格式或与内部API集成。代理可以直接访问你审查过的函数，而无需通过shell命令即时生成和执行代码。

自定义工具在终端CLI（自动发现）和Python API（作为参数传递）中都可用，这将在接下来讨论。

6、通过Python访问PatchPal

PatchPal也可以从Python脚本或REPL中以编程方式使用，通过简单的API提供完整的代理功能。

在Python API中，自定义工具可以直接提供给create_agent。在下面的示例中，我们为代理提供了一个用于搜索GitHub仓库的自定义工具。

from patchpal.agent import create_agent # 用于搜索GitHub仓库的自定义工具 from typing import Optional import requests def search_github_repos(query: str, language: Optional[str] = None, max_results: int = 5) -> str: """按关键词搜索GitHub仓库。 Args: query: 搜索查询（例如"machine learning"、"web framework"） language: 可选的编程语言过滤器（例如"Python"、"JavaScript"） max_results: 返回的最大结果数（默认：5） Returns: 格式化的仓库列表，包含星标数、描述和URL """ if requests is None: return "错误：未安装'requests'库。使用以下命令安装：pip install requests" try: search_query = query if language: search_query += f" language:{language}" url = "https://api.github.com/search/repositories" params = {"q": search_query, "sort": "stars", "order": "desc", "per_page": max_results} response = requests.get(url, params=params, timeout=10) if response.status_code != 200: return f"错误：GitHub API请求失败（HTTP {response.status_code}）" data = response.json() repos = data.get("items", []) if not repos: return f"未找到'{query}'的仓库" result = [f"找到{len(repos)}个'{query}'的仓库"] if language: result[0] += f"（语言：{language}）" result.append("") for i, repo in enumerate(repos, 1): stars = repo["stargazers_count"] forks = repo["forks_count"] language_name = repo["language"] or "N/A" result.append(f"{i}. {repo['full_name']} ⭐ {stars:,} 🍴 {forks:,}") result.append(f" 语言：{language_name}") description = repo["description"] or "无描述" if len(description) > 100: description = description[:97] + "..." result.append(f" {description}") result.append(f" {repo['html_url']}") result.append("") return "\n".join(result) except requests.exceptions.Timeout: return "错误：搜索GitHub时请求超时" except requests.exceptions.ConnectionError: return "错误：无法连接到GitHub API。请检查你的互联网连接。" except KeyError as e: return f"错误：来自GitHub API的意外响应格式：缺少{e}" except Exception as e: return f"搜索GitHub时出错：{str(e)}" # 使用自定义工具创建代理 agent = create_agent( model_id="anthropic/claude-sonnet-4-5", custom_tools=[search_github_repos] ) # 使用代理 - 它会在适当的时候调用你的自定义工具 response = agent.run("给我看一些ML GitHub仓库") print(response) # 所有内置工具仍然可用（例如web_search、run_shell等） response = agent.run("搜索法院案件的数据源") print(response)