1. 先搞清楚 Pi Agent 和 Claude Code 到底在比什么看到“反向极简”和“硬刚”这种词第一反应往往是性能或效果的对决。但这次的核心不是比谁生成的代码更准而是比在极简条件下一个智能体Agent能否完成复杂任务。Pi Agent 这个项目本质上是一个“概念验证”它试图证明一个 Agent 不需要庞大的上下文窗口仅 300 token和复杂的工具链仅 4 个工具也能通过合理的架构设计去模拟或完成类似 Claude Code一个以代码生成为核心的 AI 助手所能处理的任务。这解决了一个很实际的痛点很多 AI Agent 框架或项目入门门槛高资源消耗大架构复杂让人望而却步。Pi Agent 反其道而行用最少的“弹药”去挑战一个明确的目标这种思路对于想理解 Agent 核心工作原理、或者想在资源受限环境比如边缘设备、低成本服务器中尝试 Agent 应用的开发者来说非常有价值。所以这篇文章适合两类人看一是对 AI Agent 感兴趣但被各种复杂框架吓退想从最小可运行实例入手的开发者二是已经用过 Claude Code 这类工具想了解其背后任务分解与执行逻辑并思考如何用更轻量的方式实现类似能力的技术爱好者。最关键的价值在于通过拆解这个极简项目你能清晰地看到 Agent 的“思考-行动-观察”循环是如何在代码层面落地的而不是迷失在庞大的库和抽象概念里。2. 极简架构的核心300 Token 与 4 工具如何分工在深入环境搭建之前必须理解 Pi Agent 设计的约束条件这决定了它所有的架构选择。300 token 的上下文窗口在今天动辄 128K 甚至 1M 上下文的模型面前堪称“袖珍”。这意味着 Agent 的“工作记忆”非常有限无法携带长篇的对话历史或复杂的中间结果。因此它的架构必须是高度模块化和目标导向的。300 Token 的生存策略 这个限制迫使设计者必须精打细算每一个 token。通常这 300 token 可能用于系统提示词System Prompt精炼地定义 Agent 的角色、目标和可用工具这是行动的“宪法”。当前用户请求需要处理的具体任务描述。工具调用与返回的摘要不能把完整的工具执行结果可能很长都塞进去只能提取最关键的状态信息或结论。下一步行动的推理基于以上信息决定接下来调用哪个工具或给出最终答案。这种设计倒逼出一种高效的“流水线”思维Agent 更像一个调度员它不亲自处理大量数据而是指挥工具干活并只关心工具的“报告摘要”。4 个工具的选型与职责 Pi Agent 只配备了 4 个工具这需要它们个个都能打且覆盖任务的关键环节。虽然原项目未明确列出具体工具但结合“硬刚 Claude Code”一个代码助手的目标我们可以合理推断并构建一套最小可行工具集工具名称推断核心职责为什么是它替代方案思考代码搜索/查找工具在指定目录或项目中根据关键词或函数名查找相关代码文件、函数定义或类。Claude Code 的核心能力之一是理解项目上下文。一个极简 Agent 必须能“看到”现有代码。可以是简单的grep命令封装或调用ripgrep等更高效的命令行工具。代码解析/理解工具对找到的代码片段进行摘要提取关键信息如函数签名、输入输出、依赖关系。300 token 装不下大段代码需要此工具将代码“消化”成简短描述。可以基于 AST抽象语法树解析或使用轻量级代码分析库。代码生成/编辑工具根据指令和上下文创建新文件、修改现有代码或编写代码片段。这是代码助手的核心产出能力。可能直接调用一个本地的小型代码生成模型或者使用模板填充的方式。文件系统操作工具创建、读取、写入、删除文件以及列出目录内容。Agent 需要与项目文件系统交互这是执行代码生成和编辑结果的基础。通常是操作系统 API 的封装确保操作在安全沙箱内进行。这 4 个工具形成了一个闭环查找 - 理解 - 生成/修改 - 落地。Pi Agent 的“大脑”大语言模型负责规划调用这些工具的序列并理解它们的返回结果从而一步步逼近用户的目标比如“为我的 Flask 项目添加一个用户登录接口”。注意这里的工具是逻辑概念。在实际项目中一个工具函数可能融合多个能力如“代码编辑工具”本身就包含了文件读写。关键是功能覆盖而非数量。3. 从零搭建环境、依赖与第一个可运行实例理解了架构思想我们动手把它跑起来。这里的关键不是复现一个完全一样的 Pi Agent因为其具体实现未开源而是基于其设计理念构建一个具有同等核心能力300 token 约束4工具的极简 Agent 原型。我们将使用 Python 和流行的LangChain框架来快速搭建因为 LangChain 对工具调用和 Agent 循环有很好的抽象。3.1 基础环境准备首先你需要一个 Python 环境3.8。更推荐使用虚拟环境来管理依赖。# 创建并激活虚拟环境以 venv 为例 python -m venv pi_agent_env source pi_agent_env/bin/activate # Linux/macOS # pi_agent_env\Scripts\activate # Windows # 安装核心依赖 pip install langchain langchain-community langchain-openai这里我们使用 LangChain 作为 Agent 框架并使用 OpenAI 的 API 作为“大脑”LLM。你需要准备一个 OpenAI API Key。对于本地测试也可以使用Ollama运行本地模型但考虑到 300 token 的精准控制和对工具调用的良好支持初期使用 GPT-3.5-turbo 这类模型更容易验证流程。3.2 实现四个核心工具我们将在tools.py文件中定义四个工具函数它们对应上一节分析的四个职责。# tools.py import os import subprocess import ast from pathlib import Path from typing import Dict, Any def search_code(query: str, path: str “.”) - str: 工具1代码搜索工具。使用 grep 在指定路径递归搜索代码。 参数: query: 搜索关键词 path: 搜索根目录默认为当前目录 返回: 匹配行的摘要信息 try: # 使用 grep 进行简单搜索-r 递归-n 显示行号-I 忽略二进制文件 result subprocess.run( [“grep”, “-rIn”, query, path], capture_outputTrue, textTrue, timeout10 ) lines result.stdout.strip().split(‘\n’)[:5] # 最多返回5条结果控制长度 if not lines or lines [”]: return f“未找到包含 ‘{query}’ 的代码。” summary “\n”.join([f“{line}” for line in lines[:3]]) # 只展示前3条详情 return f“找到 {len(lines)} 处匹配前3条如下\n{summary}” except subprocess.TimeoutExpired: return “搜索超时请尝试更具体的关键词。” except Exception as e: return f“搜索过程出错{str(e)}” def parse_code(file_path: str) - str: 工具2代码解析工具。解析指定文件提取函数和类定义。 参数: file_path: 代码文件路径 返回: 文件中的函数和类摘要 try: with open(file_path, ‘r’, encoding‘utf-8’) as f: code_content f.read() tree ast.parse(code_content) definitions [] for node in ast.walk(tree): if isinstance(node, ast.FunctionDef): args [arg.arg for arg in node.args.args] def_str f“函数: {node.name}({‘, ‘.join(args)})” if node.lineno: def_str f“ (行号: {node.lineno})” definitions.append(def_str) elif isinstance(node, ast.ClassDef): def_str f“类: {node.name}” if node.lineno: def_str f“ (行号: {node.lineno})” definitions.append(def_str) if definitions: return f“文件 ‘{file_path}’ 中发现 {len(definitions)} 个定义\n” “\n”.join(definitions[:5]) # 限制输出 else: return f“文件 ‘{file_path}’ 中未发现函数或类定义。” except FileNotFoundError: return f“错误文件 ‘{file_path}’ 不存在。” except SyntaxError: return f“错误文件 ‘{file_path}’ 存在语法错误无法解析。” except Exception as e: return f“解析文件时出错{str(e)}” def write_code(file_path: str, content: str) - str: 工具3代码写入工具。创建或覆盖写入代码文件。 参数: file_path: 要写入的文件路径 content: 要写入的代码内容 返回: 操作结果状态 try: # 确保目录存在 os.makedirs(os.path.dirname(file_path), exist_okTrue) with open(file_path, ‘w’, encoding‘utf-8’) as f: f.write(content) return f“成功将代码写入文件{file_path}” except Exception as e: return f“写入文件时出错{str(e)}” def list_files(directory: str “.”) - str: 工具4文件列表工具。列出指定目录下的文件和子目录。 参数: directory: 要列出的目录路径默认为当前目录 返回: 目录列表的字符串表示 try: path Path(directory) if not path.exists(): return f“目录 ‘{directory}’ 不存在。” items [] for item in path.iterdir(): if item.is_file(): items.append(f“[文件] {item.name}”) elif item.is_dir(): items.append(f“[目录] {item.name}/”) if not items: return f“目录 ‘{directory}’ 为空。” # 限制返回数量避免 token 爆炸 listed “\n”.join(items[:10]) if len(items) 10: listed f“\n…以及另外 {len(items) - 10} 个项目” return f“目录 ‘{directory}’ 内容\n{listed}” except Exception as e: return f“列出目录时出错{str(e)}”3.3 构建 Agent 并施加 300 Token 约束接下来在main.py中我们将这些工具装配给 Agent并关键地设置上下文长度限制。# main.py import os from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_openai import ChatOpenAI from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.tools import Tool from langchain.memory import ConversationBufferWindowMemory from tools import search_code, parse_code, write_code, list_files # 1. 设置 OpenAI API Key (请替换为你的 key或从环境变量读取) os.environ[“OPENAI_API_KEY”] “your-api-key-here” # 2. 初始化 LLM并严格限制最大输出 token 和上下文关联性 # 注意我们通过 max_tokens 限制单次输出但上下文窗口限制需要在 Memory 和 Prompt 设计中体现 llm ChatOpenAI( model“gpt-3.5-turbo”, temperature0, # 降低随机性让 Agent 更确定 max_tokens150, # 强制 LLM 每次回复精简为工具调用和结果留出 token 空间 ) # 3. 将函数包装成 LangChain Tool 对象 tools [ Tool( name“SearchCode”, funcsearch_code, description“在项目目录中搜索包含特定关键词的代码行。输入应为搜索关键词。” ), Tool( name“ParseCodeFile”, funcparse_code, description“解析一个代码文件提取其中的函数和类定义。输入应为文件路径。” ), Tool( name“WriteCodeToFile”, funcwrite_code, description“创建或覆盖一个代码文件。输入应为 ‘file_path: content’ 格式用冒号分隔路径和内容。” ), Tool( name“ListDirectory”, funclist_files, description“列出指定目录下的文件和子目录。输入应为目录路径默认为当前目录 ‘.’。” ), ] # 4. 设计系统提示词这是控制 token 消耗和 Agent 行为的关键 # 提示词必须极其精炼明确指令和约束。 system_prompt “””你是一个高效的代码助手 Agent。你的上下文窗口非常有限约300 token因此必须遵循以下规则 1. 保持思考极其简洁。 2. 优先使用工具完成任务。一次只使用一个最必要的工具。 3. 仔细阅读工具返回的结果它们包含了继续行动所需的关键信息。 4. 如果工具返回的结果很长只提取最关键的信息用于后续思考。 5. 你的最终目标是准确理解用户请求并完成代码相关的任务。 你可以使用的工具 - SearchCode: 用于搜索代码。 - ParseCodeFile: 用于理解代码文件结构。 - WriteCodeToFile: 用于创建或修改代码文件。 - ListDirectory: 用于浏览项目目录。 现在开始处理用户请求。记住简洁是关键。“”” # 5. 构建 Prompt Template prompt ChatPromptTemplate.from_messages([ (“system”, system_prompt), MessagesPlaceholder(variable_name“chat_history”), (“human”, “{input}”), MessagesPlaceholder(variable_name“agent_scratchpad”), ]) # 6. 使用有窗口的记忆这是实现 300 token 上下文约束的核心技巧。 # ConversationBufferWindowMemory 只保留最近 k 轮对话。 # 假设每轮对话用户输入AI响应工具调用平均消耗 100 token那么 k3 可大致将历史控制在 300 token 内。 memory ConversationBufferWindowMemory( memory_key“chat_history”, k3, # 只记住最近3轮交互 return_messagesTrue ) # 7. 创建 Agent 和执行器 agent create_openai_tools_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, # 打开详细日志方便观察 Agent 的思考过程 handle_parsing_errorsTrue, # 处理解析错误 max_iterations5, # 防止 Agent 陷入死循环 ) # 8. 运行测试 if __name__ “__main__”: # 测试一个简单任务 query “查看当前目录下有什么文件” print(f“用户: {query}”) response agent_executor.invoke({“input”: query}) print(f“Agent: {response[‘output’]}”)运行python main.py你应该能看到 Agent 调用ListDirectory工具并返回结果。通过verboseTrue的日志你可以清晰地看到 LLM 的思考链ReAct 模式思考要做什么 - 决定调用哪个工具 - 传入参数 - 解析工具结果 - 给出最终回答或下一步思考。4. 实战推演用极简 Agent 处理真实代码任务现在我们让这个“麻雀虽小五脏俱全”的 Agent 尝试一个更接近 Claude Code 的典型任务。这个任务会串联多个工具考验 Agent 在有限上下文下的规划能力。任务描述“在我的项目中查找所有使用了requests库的文件然后为其中一个文件添加错误处理逻辑。”这个任务可以分解为搜索找到包含import requests或from requests的文件。解析查看其中一个文件的内容理解其结构。生成与写入修改该文件为其添加 try-except 块。让我们一步步观察 Agent 如何工作。你需要先准备一个简单的测试项目目录。# 创建测试目录和文件 mkdir -p test_project cd test_project # 创建文件1使用了 requests cat api_client.py ‘EOF’ import requests def fetch_data(url): response requests.get(url) return response.json() EOF # 创建文件2也使用了 requests cat data_downloader.py ‘EOF’ import requests import json def download_file(url, save_path): r requests.get(url, streamTrue) with open(save_path, ‘wb’) as f: for chunk in r.iter_content(chunk_size8192): f.write(chunk) EOF # 创建文件3未使用 requests cat utils.py ‘EOF’ def format_text(text): return text.strip().lower() EOF回到项目根目录pi_agent_env所在目录修改main.py最后的测试部分# … (前面的代码不变) if __name__ “__main__”: # 复杂任务测试 complex_query “”” 在 ‘test_project’ 目录中查找所有使用了 requests 库的 Python 文件。 然后选择第一个找到的文件为其中的 fetch_data 或 download_file 函数看哪个存在添加基本的错误处理try-except。 如果函数不存在就为第一个找到的 requests 相关函数添加。 “”” print(f“用户: {complex_query}”) response agent_executor.invoke({“input”: complex_query}) print(f“\n最终输出: {response[‘output’]}”)运行后通过verbose日志你会看到类似以下的思考过程已简化思考用户想找用了 requests 的文件然后修改。我需要先搜索。行动调用SearchCode工具输入query“import requests”, path“test_project”。观察工具返回找到了api_client.py和data_downloader.py。思考我需要查看第一个文件api_client.py的内容来理解函数。行动调用ParseCodeFile工具输入file_path“test_project/api_client.py”。观察工具返回文件中有函数fetch_data(url)。思考现在需要为这个函数添加错误处理。我需要生成新的代码内容并写入。行动调用WriteCodeToFile工具输入file_path“test_project/api_client.py”, content新的代码字符串。观察工具返回写入成功。思考任务完成告知用户。在这个过程中300 token 的约束无处不在系统提示词必须短小精悍。工具描述必须准确简洁。LLM 的每次输出被max_tokens150限制迫使它给出精准的“下一步”指令而不是长篇大论。记忆窗口k3确保对话历史不会无限膨胀只保留最近的关键交互。最终api_client.py文件应该被修改为import requests def fetch_data(url): try: response requests.get(url) response.raise_for_status() # 检查 HTTP 错误 return response.json() except requests.exceptions.RequestException as e: print(f“请求发生错误: {e}”) return None至此这个极简 Agent 完成了一次多步骤的代码理解和编辑任务。它没有一次性理解整个项目而是在工具的辅助下像“探针”一样一步步探索、理解、然后行动完美适应了其有限的“工作内存”。5. 深度拆解Pi Agent 设计哲学与 Claude Code 的差异通过上面的构建和实战我们可以回过头来更深刻地理解“反向极简”和“硬刚”背后的设计哲学以及它与 Claude Code 这类成熟产品的本质区别。1. 资源分配策略的截然不同Claude Code (及同类产品)其背后是强大的大语言模型如 Claude 3拥有巨大的上下文窗口通常 100K。它倾向于将大量项目上下文多个文件一次性加载到提示词中让模型进行全局分析和规划。这好比给了一位建筑师整个工地的完整蓝图他可以做出非常整体和协调的设计。优势是规划能力强代码一致性高劣势是对资源消耗极大响应可能较慢且不适合低资源环境。Pi Agent (极简思路)它承认资源有限因此采用增量式、工具驱动的探索策略。它不试图一次性记住所有东西而是像一位现场工程师手里只有一张简易地图系统提示词通过不断使用“望远镜”搜索工具、“说明书”解析工具和“对讲机”文件操作工具来了解局部情况然后做出当前最优决策。优势是极其轻量、快速启动、适合自动化集成劣势是缺乏全局视野复杂任务可能需要更多轮交互且规划可能不是最优。2. 任务处理范式的区别Claude Code基于理解的生成。它努力理解你的整个请求和项目上下文然后生成一个完整的、通常是正确的解决方案。你与它的交互更像是“提出需求 - 获得成品”。Pi Agent基于规划的执行。它将你的需求分解成一个动作序列规划然后通过调用工具一步步执行这个序列。你与它的交互更像是“下达指令 - 观察其一系列操作 - 获得结果”。这个过程更透明也更容易调试和干预。3. “硬刚”的实质Pi Agent 用 300 token 4 工具去“硬刚” Claude Code并不是要在代码生成质量上超越对方而是要证明复杂性并非必需很多智能任务可以通过简单的工具组合和有限的“思考”来完成。可解释性与可控性极简架构的每一步都清晰可见工具调用失败可以精确定位这比黑盒大模型生成错误代码后再去排查要容易得多。部署友好性它可以在资源极其有限的环境中运行为 AI Agent 在边缘计算、嵌入式系统或低成本自动化流程中打开了可能性。6. 避坑指南与生产化思考如果你基于这个原型继续开发或用于实际场景以下几个坑点和优化方向需要重点关注1. Token 限制的精准控制我们的实现通过ConversationBufferWindowMemory(k3)和max_tokens150来模拟约束但这并不精确。在生产中你需要精确计算使用模型的tiktoken库或其他方法实时计算整个提示词系统提示 历史 工具结果 用户输入的 token 数量。动态裁剪当历史超过阈值时不是简单丢弃最老的而是可能需要对历史进行摘要只保留最关键的决定性信息。这本身就是一个有趣的子问题。2. 工具的设计与可靠性工具需要健壮我们的示例工具很简单。真实工具必须处理各种边界情况如文件不存在、权限不足、网络超时、解析异常并返回结构化的、机器可读的错误信息而不仅仅是字符串。工具需要精确WriteCodeToFile工具的输入格式file_path: content很脆弱。更好的设计是使用 Pydantic 模型来定义结构化输入或者让 LLM 输出 JSON 格式的参数。增加关键工具对于代码任务一个代码执行/测试工具可能至关重要。让 Agent 能够运行单元测试或执行脚本根据结果判断修改是否成功形成“感知-行动-验证”的闭环。3. 规划能力的提升当前 Agent 依赖于 LLM 的单步推理。对于复杂任务它可能陷入循环或做出短视决策。可以考虑任务分解在 Agent 行动前先让一个“规划器”LLM 将用户需求分解成一个清晰的、线性的或树状的任务列表。子Agent为特定复杂子任务如“设计一个数据库连接池”创建专门的子Agent主 Agent 负责调度。4. 安全与沙箱权限控制绝对不能让 Agent 拥有无限制的文件系统或网络访问权限。必须运行在沙箱中严格限制其可访问的目录和可执行的命令。操作确认对于删除文件、覆盖重要代码、安装系统包等危险操作应该设计“人工确认”环节或者有完整的回滚机制。5. 评估与迭代如何判断你的极简 Agent 是否合格建立一套评估标准任务完成率针对一系列基准任务如“添加错误处理”、“重命名变量”、“提取函数”计算成功完成的比例。平均交互轮数完成一个任务需要多少次“思考-行动”循环轮数越少说明效率越高。工具调用准确率Agent 选择的工具和传入的参数是否正确最终代码质量生成的代码能否通过基础语法检查甚至简单的单元测试我个人更建议在将此类 Agent 投入生产前先在一个受控的、代码库快照的环境中进行大量测试。极简 Agent 的魅力在于其清晰和可控而这份可控性正是通过严谨的设计、健壮的工具和充分的测试来保障的。它可能永远无法在“一次性生成完美代码”上超越 Claude Code但在特定自动化、可解释性要求高或资源受限的场景下它提供了一条截然不同且极具潜力的技术路径。