USER_GUIDE.md

Pyra IDE 用户指南

欢迎使用 Pyra IDE！本指南将帮助您快速上手我们的轻量级 Python 开发环境。

快速入门

首次启动

1. 打开 Pyra IDE - 应用程序将启动并加载默认测试项目
2. 创建虚拟环境 - 如有提示，为您的项目创建 Python 虚拟环境
3. 熟悉界面 - 了解布局和工具的使用方法

界面概览

主要区域

• 文件浏览器（左侧）：浏览和管理项目文件
• 代码编辑器（中央）：编写和编辑 Python 代码
• 控制台（底部）：查看脚本输出和错误信息
• 项目面板（右侧，可切换）：管理 Python 包和环境

工具栏操作

• 新建文件 - 创建新的 Python 文件
• 新建文件夹 - 创建新目录
• 刷新 - 刷新文件树
• 运行 - 执行当前 Python 脚本
• 停止 - 停止正在运行的脚本
• 格式化 - 使用 Ruff 格式化代码
• 检查 - 使用 Ruff 检查代码质量

项目管理

创建新项目

1. 点击工具栏中的 新建项目
2. 从可用模板中选择：
   • 基础 Python 项目 - 简单结构
   • 数据科学项目 - 支持 Jupyter notebook
   • Web 框架项目 - Flask/FastAPI 设置
3. 输入项目名称和位置
4. 点击 创建项目

打开现有项目

1. 点击工具栏中的 打开项目
2. 导航到您的项目文件夹
3. 选择项目目录
4. Pyra 将自动检测 Python 文件和配置

Python 环境管理

虚拟环境设置

• 自动检测：Pyra 检查现有的 .venv 文件夹
• 便捷创建：如果不存在虚拟环境，会提示创建
• Python 版本选择：可选择 Python 3.9、3.10、3.11 或 3.12

包管理

1. 打开项目面板 - 点击 按钮或使用"显示面板"
2. 安装包：
   • 在搜索框中输入包名
   • 点击 安装 添加到项目
   • 包通过 uv pip 安装
3. 查看已安装包 - 查看虚拟环境中的所有包
4. 更新依赖 - 保持包的最新状态

代码编辑

功能特性

• 语法高亮 - 完整的 Python 语法支持
• 自动补全 - Python 关键字和函数的智能提示
• 错误检测 - 实时错误高亮显示
• 多文件支持 - 同时处理多个 Python 文件

代码质量工具

• 格式化代码（）：使用 Ruff 自动格式化代码
• 代码检查（）：检查代码质量问题和潜在错误
• 实时反馈：在您输入时显示检查问题

运行代码

执行脚本

1. 在编辑器中打开 Python 文件
2. 点击运行（）或使用键盘快捷键
3. 在下方控制台中查看输出
4. 监控执行 - 查看实时输出和错误

控制台功能

• 实时输出 - 查看 print 语句的实时执行结果
• 错误信息 - 清晰的错误报告，包含行号
• 清空控制台 - 需要时重置输出
• 可滚动历史 - 回顾之前的执行结果

调试代码

开始调试

1. 打开 Python 文件（.py）
2. 设置断点 - 点击行号左侧区域，会出现红色圆点
3. 启动调试 - 点击工具栏的调试按钮（ 橙色虫子图标）
4. 选择调试模式 - 从下拉菜单选择"调试"

调试控制操作

• 继续（F5） - 继续执行直到下一个断点
• 单步跳过（F10） - 执行当前行，不进入函数内部
• 单步进入（F11） - 进入函数调用内部
• 单步跳出（Shift+F11） - 跳出当前函数
• 停止 - 停止调试会话

调试信息面板

当程序暂停在断点时，调试面板会显示：

• 调用栈（Call Stack）：

  • 显示函数调用层次
  • 点击不同的栈帧查看对应代码位置
  • 了解程序执行路径

• 变量查看器（Variables）：

  • 局部变量（Locals） - 当前函数内的变量
  • 全局变量（Globals） - 全局作用域的变量
  • 展开嵌套对象查看详细内容
  • 实时显示变量值的变化

断点管理

• 添加断点 - 点击行号左侧区域
• 删除断点 - 再次点击红色圆点
• 多个断点 - 可在不同位置设置多个断点
• 断点验证 - 调试启动后断点会被验证

调试技巧

• 在关键位置设置断点 - 在可能出错的代码行设置断点
• 使用单步执行 - 逐行跟踪代码执行过程
• 检查变量值 - 确认变量是否符合预期
• 观察调用栈 - 了解函数调用顺序

安装 debugpy

首次使用调试功能时，需要安装 debugpy：

1. 通过包管理器安装：

   • 打开项目面板（）
   • 搜索 "debugpy"
   • 点击安装

2. 或者使用命令行：

   # Windows
   .venv\Scripts\pip install debugpy
   
   # Linux/macOS
   .venv/bin/pip install debugpy

调试故障排除

问：调试启动失败

• 答：确保已安装 debugpy（通过包管理器安装）
• 答：确保虚拟环境已创建

问：断点未命中

• 答：确保断点设置在可执行代码行（非空行或注释）
• 答：重新启动调试会话

问：变量显示不正确

• 答：确保程序已暂停在断点处
• 答：点击调用栈中的正确栈帧

设置与自定义

主题选项

1. 打开设置 - 点击 设置按钮
2. 选择主题：
   • Catppuccin Mocha（暗色主题）
   • Catppuccin Latte（亮色主题）
3. 应用更改 - 主题立即更新

编辑器偏好设置

• 字体大小 - 调整编辑器字体大小
• 制表符大小 - 配置缩进偏好
• 自动换行 - 启用/禁用行换行
• 小地图 - 显示/隐藏代码小地图

使用技巧与最佳实践

项目组织

• 使用虚拟环境 - 始终为项目创建隔离环境
• 整理文件 - 将相关代码保存在文件夹中
• 版本控制 - 使用 git 跟踪更改（Pyra 外部）

代码质量

• 定期格式化 - 使用格式化按钮保持一致的代码风格
• 修复检查问题 - 处理 Ruff 高亮显示的警告和错误
• 测试代码 - 经常运行脚本以及早发现错误

性能优化

• 关闭未使用的文件 - 只保持必要文件打开
• 清空控制台 - 输出过长时重置
• 必要时重启 - 如果应用程序无响应，请刷新

故障排除

常见问题

问：找不到虚拟环境

• 答：在提示时点击"创建环境"，或使用项目面板设置 Python 环境

问：包安装失败

• 答：确保您有活动的虚拟环境和互联网连接

问：代码无法运行

• 答：检查文件是否已保存且具有 .py 扩展名

问：检查错误持续存在

• 答：使用格式化按钮自动修复许多样式问题

问：控制台输出缺失

• 答：确保您的脚本包含 print 语句或输出命令

获取帮助

• 检查控制台 - 错误信息通常提供有用的详细信息
• 检查代码 - 使用检查工具识别问题
• 重启应用程序 - 如果问题持续存在，请关闭并重新打开 Pyra

其他资源

• English User Guide - 英文版用户指南
• 项目文档 - 中文技术文档
• 主 README - 项目概览和开发信息

---

使用 Pyra IDE 愉快编程！