Pywen：一个专为软件开发打造的Python命令行AI助手

Pywen 的核心是一个基于Python构建的命令行界面（CLI）工具，它将阿里云最新的代码大模型Qwen3-Coder的能力直接集成到了开发者的终端里。它专门为处理各类智能软件工程任务而设计，为开发者提供一个高效、智能的代码助手。用户可以在熟悉的命令行环境中，通过对话式的自然语言指令，驱动一个先进的智能体系统来执行复杂的开发工作流程，例如编写代码、修复Bug、重构项目乃至创建完整的应用骨架。Pywen项目的设计哲学是提供一个透明且模块化的架构，它不仅是一个实用的开发工具，更是一个理想的研究平台。研究人员和开发者可以轻松地修改、扩展和分析其内部工作机制，非常适合用于研究AI智能体架构、进行消融实验和开发新的智能体功能。

功能列表

• Qwen3-Coder驱动：基于阿里云最新的代码专用大语言模型Qwen3-Coder-Plus，为代码生成、理解和调试提供强大支持。
• 命令行交互：通过在终端输入自然语言指令与智能体进行交互，完成复杂的软件开发任务。
• 模块化架构：采用模块化设计，易于扩展和定制，为研究和开发新的AI智能体能力提供了便利。
• 丰富的工具集：内置文件操作（创建、编辑、读取）、Bash命令执行、结构化问题分解等一系列实用工具。
• YOLO模式：提供一种“一键确认”模式（Ctrl+Y），允许智能体在命令行中自动执行所有操作，以加速工作流程。
• 轨迹记录：详细记录智能体（Agent）的每一次思考和操作，生成轨迹文件用于调试和行为分析。
• 智能配置：首次运行时会自动启动配置向导，引导用户完成API密钥等必要设置。
• 会话统计：可以实时追踪API的调用次数、Token消耗量以及各类工具的使用情况。

使用帮助

本使用帮助根据官方文档整理，旨在让用户能够快速上手并熟练使用Pywen。

1. 安装

Pywen作为一个Python包，可以通过pip命令直接从PyPI仓库安装。打开你的终端并运行以下命令：

pip install pywen

安装完成后，你就可以在终端的任何路径下使用pywen命令。

2. 首次使用与配置

安装后，直接在终端输入pywen命令来启动程序：

pywen

如果是第一次运行，Pywen会检测到没有配置文件，并自动启动一个配置向导来帮助你设置。

Configuration file not found, starting setup wizard...
API Key: [在这里输入你的Qwen API Key]
Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1
Model: qwen3-coder-plus
...
✅ Configuration saved to pywen_config.json

你只需要按照提示输入从阿里云Dashscope（通义千问）获取的API Key即可完成基础配置。配置文件pywen_config.json会保存在当前目录下。

3. 基本用法

配置完成后，Pywen会进入交互式命令行界面。现在，你可以像和人对话一样，直接用自然语言向它下达任务。
例如，你可以尝试：

> 创建一个Python脚本来计算斐波那契数列
> 重构 main.py 里的函数，让它们更高效
> 修复这个项目里的bug，并为主要功能添加单元测试
> 创建一个新的Flask Web应用，并包含合理的文件结构

Pywen的智能体会分析你的需求，并调用文件操作、代码生成、Shell命令等工具来一步步完成任务。

4. 系统命令

Pywen提供了一些以/开头的内置命令，用于程序管理和信息查询：

• /help：显示帮助信息。
• /tools：列出当前智能体可用的所有工具。
• /stats：查看当前会话的统计数据，如API调用次数和Token用量。
• /clear：清空屏幕和当前对话历史。
• /memory：查看和管理智能体的记忆内容。
• /quit：退出Pywen程序。
• !<命令>：在不退出Pywen的情况下，直接执行一个Shell/CMD命令，例如 !ls -l。

5. YOLO 模式（谨慎使用）

这是一个高级功能，用于提升执行效率。

• 切换方式：在交互界面按下Ctrl+Y可以开启或关闭YOLO模式。
• 默认行为：在普通模式下，每当智能体需要执行一个潜在的风险操作（如修改文件、执行命令），它都会请求用户确认。
• YOLO模式行为：开启后，所有工具调用都会被自动批准，不再需要用户手动确认。这会极大加快任务执行速度，但同时也移除了安全防护。
• 风险提示：由于AI可能会误解指令，YOLO模式下它可能会执行错误或破坏性的操作。请在明确任务目标且风险可控的情况下使用此模式。

6. 环境与配置

Pywen通过pywen_config.json文件进行配置，同时支持环境变量。

• 配置文件：程序启动时会读取当前目录下的pywen_config.json。
• 环境变量：你也可以通过设置环境变量来提供API密钥，这在持续集成（CI/CD）或Docker环境中特别有用。

  # Qwen API Key (必需)
  export QWEN_API_KEY="your-qwen-api-key"
  # 工具API Key (推荐配置，用于增强功能)
  export SERPER_API_KEY="your-serper-api-key"  # 用于网页搜索
  export JINA_API_KEY="your-jina-api-key"      # 用于读取网页内容
  

• 配置优先级：命令行参数 > 配置文件 > 环境变量 > 默认值。

应用场景

1. 快速原型开发
   当你有一个新想法时，可以直接在命令行告诉Pywen：“用FastAPI创建一个待办事项应用的后端服务，包含数据库模型和增删改查API”。Pywen会为你生成项目结构、编写样板代码，让你迅速进入业务逻辑的开发阶段。
2. 代码重构与优化
   对于项目中的老旧或低效代码，你可以让Pywen来处理：“分析data_processor.py文件的性能瓶颈，并重构其中的函数以提升效率”。智能体会读取、分析并修改代码，同时保持功能不变。
3. 自动化测试与调试
   你可以将整个项目交给Pywen，并下达指令：“为这个项目中的所有公开函数编写单元测试，并修复所有测试失败的地方”。Pywen可以调用测试框架、执行测试、分析错误报告并尝试自动修复bug。
4. AI智能体架构研究
   对于AI研究者，Pywen是一个绝佳的实验平台。其模块化的设计和透明的轨迹记录功能，可以方便地用于测试新的Agent决策逻辑、工具组合或记忆机制，并通过分析轨迹文件来验证研究假设。

QA

1. 问：Pywen 和 Qwen3-Coder 是什么关系？
   答：Pywen 是一个上层应用工具，而 Qwen3-Coder 是其底层的驱动引擎。可以理解为，Qwen3-Coder 是负责思考和生成内容的“大脑”，而 Pywen 则是提供了让这个“大脑”与你的电脑文件系统、命令行进行交互的“身体”和“四肢”，并提供了一个用户友好的命令行界面。
2. 问：使用Pywen是免费的吗？
   答：Pywen 这个软件本身是开源且免费的（遵循MIT许可证）。但是，它的运行依赖于调用阿里云通义千问（Dashscope）提供的Qwen模型API。这些API调用会产生费用，你需要根据阿里云的官方定价为你的API Key使用量付费。
3. 问：为什么需要配置 SERPER_API_KEY 或 JINA_API_KEY？
   答：这些是可选的增强工具。SERPER_API_KEY让智能体具备了网页搜索的能力，当遇到它知识范围外或需要最新信息的问题时，可以上网查找资料。JINA_API_KEY则让智能体能高效地“阅读”和理解网页内容。配置它们能极大扩展智能体的能力边界。
4. 问：YOLO模式有什么具体风险？
   答：风险在于AI可能会误解你的指令。例如，当你要求“清理旧日志文件”时，如果你的指令不够明确，AI可能会错误地将重要的配置文件也识别为“旧文件”并执行删除操作。在YOLO模式下，这个删除动作会未经你确认直接发生，可能导致项目损坏或数据丢失。