Ai-Punk：开源AI驱动的软件开发自动化助手

Ai-Punk 是一个开源的 AI 驱动软件开发助手，托管在 GitHub 上，由开发者 Netsky 开发。它基于 LangChain ReAct 模式，结合现代 AI 模型，帮助用户自动化完成编程任务。Ai-Punk 的核心特点是完全透明的思考过程，用户可实时查看 AI 的每一步推理。项目采用模块化设计，提供文件操作、代码搜索、终端命令等功能，支持多语言交互（英语和俄语）。Ai-Punk 强调安全性，所有操作限制在指定工作目录内，适合开发者、程序员和需要自动化任务的用户。代码公开，社区可自由贡献，项目活跃，更新频繁。

功能列表

• 完全透明的思考过程：实时显示 AI 的推理步骤，帮助用户理解操作逻辑。
• 自主任务执行：AI 能独立规划和执行复杂编程任务。
• 模块化架构：代码结构清晰，功能模块分离，便于维护和扩展。
• 安全工作空间：所有操作限制在用户选定的目录内，确保数据安全。
• 丰富工具集：支持文件操作、搜索、终端命令和代码编辑。
• 美观终端界面：提供直观的终端 UI，展示完整操作过程。
• 多语言支持：自动检测用户语言，支持英语和俄语交互。
• 智能文件搜索：支持语义搜索和模糊匹配，提升文件查找效率。
• 高性能集成：通过 LangChain 优化工具，运行速度快。

使用帮助

安装流程

要使用 Ai-Punk，需要从 GitHub 仓库获取代码并配置运行环境。以下是详细步骤：

1. 克隆或下载代码
   访问 https://github.com/netsky-devel/Ai-Punk，点击“Code”按钮，选择“Download ZIP”下载源代码，或使用 Git 命令克隆：

   git clone https://github.com/netsky-devel/Ai-Punk.git
   

   克隆后，进入项目目录：

   cd Ai-Punk
   

2. 安装依赖
   Ai-Punk 依赖 Python 3.8+ 及特定库。确保已安装 Python，然后运行以下命令安装依赖：

   pip install -r requirements.txt
   

   依赖包括 LangChain（用于 AI 模型集成）、Rich（用于终端界面美化）等，详见 requirements.txt。

3. 配置 AI 服务提供商
   Ai-Punk 需要连接 AI 服务（如 OpenAI、Google 或 Anthropic）。运行主程序并选择配置选项：

   python main.py
   

   在界面中选择“1 – Setup AI Provider”，输入你的 API 密钥。密钥需从 AI 服务提供商官网获取。配置信息会保存到 config/models.py 或环境变量中。

4. 选择工作目录
   运行程序后，选择“2 – Select Working Directory”，指定操作的工作目录。Ai-Punk 确保所有文件操作限制在此目录内，保障安全。
5. 初始化 AI 代理
   选择“3 – Initialize Agent”，初始化 AI 代理。系统会加载配置并准备工具集。
6. 开始交互
   选择“4 – Start Chat with Agent”，进入交互模式。用户可输入任务指令，AI 将自动执行并显示推理过程。

主要功能操作

Ai-Punk 的核心功能是自动化编程任务，以下是详细操作说明：

• 完全透明的思考过程
  Ai-Punk 的独特之处在于实时展示 AI 的推理步骤。例如，当用户要求分析项目结构时，终端会显示：

  ╭─ 🧠 Agent Thinking (Step 1) ───────────────────────────────╮
  │ 需要先分析项目结构，了解代码库内容。开始列出目录文件。│
  ╰──────────────────────────────────────────────────────────╯
  

  随后，AI 调用 list_directory 工具，列出目录内容并解释结果。用户可通过终端界面清晰看到每一步操作。

• 自主任务执行
  AI 能独立完成复杂任务。例如，用户输入“添加错误处理到 main.py”，AI 会：
  1. 读取 main.py 文件（使用 read_file 工具）。
  2. 分析代码结构，识别需要添加错误处理的位置。
  3. 使用 edit_file 工具插入 try-catch 语句。
  4. 显示修改后的代码并解释更改逻辑。
• 智能文件搜索
  Ai-Punk 提供语义搜索和模糊匹配功能。用户输入“查找所有配置文件”，AI 调用 file_search 工具，扫描目录并返回相关文件（如 config.json）。搜索支持正则表达式和语义分析。例如：

  python main.py --search "config.*\.json"
  

  结果会按相关性排序，显示文件路径和内容摘要。

• 文件操作
  Ai-Punk 支持多种文件操作：
  • 列出目录：运行 list_directory 工具，显示目录内容和文件详情。
  • 读取文件：使用 read_file，支持语法高亮显示代码。
  • 编辑文件：通过 edit_file，支持查找替换和批量修改。
  • 删除文件：使用 delete_file，确保安全删除并自动备份。
    例如，删除旧备份文件：

  python main.py --delete "backup_*.bak"
  

  AI 会验证文件并提示用户确认。

• 终端命令执行
  用户可通过 run_terminal 工具执行终端命令。例如：

  python main.py --terminal "git status"
  

  命令在受控环境中运行，防止意外操作。

特色功能操作

• 美观终端界面
  Ai-Punk 使用 Rich 库打造直观的终端 UI，显示推理过程、操作结果和错误信息。界面支持彩色高亮和结构化输出。例如，执行文件搜索时，结果以表格形式展示，包含文件名、路径和相关性得分。
• 多语言支持
  Ai-Punk 自动检测用户输入语言，支持英语和俄语。例如，用户输入“создай новый файл config.json”，AI 会用俄语回应并创建文件：

  python main.py --create "config.json"
  

  语言配置在 src/localization/ 目录管理，支持扩展其他语言。

• 安全工作空间
  所有操作限制在用户选定的工作目录内。AI 使用 src/workspace/manager.py 进行路径验证，确保不会访问外部文件。例如，尝试访问 ../sensitive.txt 会触发错误提示。

注意事项

• 依赖检查：运行前确保安装所有依赖，检查 requirements.txt 是否完整。
• API 配置：未配置 API 密钥会导致运行失败。参考 env.example 设置环境变量。
• 错误排查：运行报错时，查看终端输出的详细错误信息，或检查 logs/ 目录中的日志文件。
• 更新代码：定期运行 git pull 获取最新代码，保持与官方仓库同步。

应用场景

1. 代码库分析
   开发者需要快速了解大型项目结构时，Ai-Punk 可自动扫描目录，生成文件结构报告，适合接手新项目或代码审查。
2. 自动化代码修改
   程序员需要批量添加错误处理或重构代码时，Ai-Punk 可快速编辑多个文件，插入标准代码片段，节省手动操作时间。
3. 文件管理与清理
   开发团队需要清理旧备份文件或整理项目目录时，Ai-Punk 的安全文件操作工具可高效完成任务。
4. 多语言开发支持
   跨国团队使用英语或俄语交互时，Ai-Punk 自动适配语言，提供一致的开发体验。
5. 学习与调试
   编程初学者可通过透明的思考过程，学习 AI 如何分析和解决问题，适合教育场景。

QA

1. Ai-Punk 支持哪些 AI 模型？
   支持 OpenAI、Google 和 Anthropic 的模型，具体配置在 src/config/models.py 中设置。
2. 如何确保操作安全？
   Ai-Punk 限制所有操作在选定目录内，使用相对路径验证，防止访问外部文件。所有文件操作都会记录日志。
3. 如何扩展新功能？
   Fork 仓库，在 src/tools/ 添加新工具模块，更新 src/agent/wrappers/factory.py，然后提交 Pull Request。
4. 运行缓慢怎么办？
   检查网络连接（AI API 调用需要稳定网络），确保已安装优化后的依赖（如 LangChain 最新版）。
5. 如何切换语言？
   Ai-Punk 自动检测输入语言，无需手动切换。语言文件在 src/localization/messages/ 中管理。