Skip to content

Commit 267a497

Browse files
ericodingclaude
ericoding
and
claude
committed
feat(debug): implement Python debugging with DAP protocol support
Major Features: - Complete DAP (Debug Adapter Protocol) integration with debugpy - Full-featured debug panel with call stack, scopes, and variable inspection - Breakpoint management in Monaco Editor - Step debugging controls (Continue, Step Over, Step Into, Step Out) - Real-time debug event handling and output streaming Backend Implementation (Rust): - src-tauri/src/commands/debug.rs: Complete DAP client implementation - TCP connection management for debugpy - DAP message parsing and protocol handling - Debug session lifecycle management - Event loop for real-time debug events - Support for breakpoints, stack traces, scopes, and variables - Enhanced error handling and logging for debugging sessions - Async event processing with Tokio runtime Frontend Implementation (TypeScript/React): - src/components/DebugPanel.tsx: Interactive debug UI - Hierarchical variable tree with lazy loading - Unique key generation for React rendering stability - Scope selection and frame navigation - Real-time state synchronization - src/App.tsx: Debug session management - Debug event listeners (stopped, continued, terminated, output) - Toolbar integration with debug mode selector - Breakpoint collection and DAP format conversion - src/components/Editor.tsx: Breakpoint management - Visual breakpoint indicators in Monaco gutter - Click-to-toggle breakpoint functionality - src/lib/tauri.ts: Complete debug API bindings Architecture Improvements: - Fixed DebugPanel variable rendering with proper React keys - Enhanced DAP event loop error handling and cleanup - Added detailed debug logging for troubleshooting - Proper session state management and cleanup Testing: - test-project/debug_test.py: Comprehensive debug test scenarios - Function calls and stack frame navigation - Loop iteration and local variables - Complex data structures (dicts, lists, nested objects) - Multiple breakpoint locations Installer Fixes: - fix-uninstaller-icon.cjs: Post-build script to inject MUI_UNICON - Updated package.json with tauri:build script for icon fix workflow - NSIS uninstaller now displays correct application icon Documentation: - Updated user guides (zh-CN and en) with debugging instructions - Added debugging workflow and keyboard shortcuts - Documented debugpy installation requirements 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 9c987f0 commit 267a497

33 files changed

+2290
-146
lines changed

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,3 +72,9 @@ claude.md
7272
CLAUDE.md
7373
agents.md
7474
AGENTS.md
75+
76+
# Internal development documentation
77+
DEBUG_INTEGRATION_GUIDE.md
78+
DEBUG_INTEGRATION_GUIDE_EN.md
79+
调试功能完成说明.md
80+
DEBUG_COMPLETION_NOTE_EN.md

‎ICON_UPDATE_GUIDE.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Pyra IDE 图标更新指南
2+
3+
## ✅ 已完成的更新
4+
5+
### 1. 图标文件生成
6+
- ✅ Windows: `icon.ico` (64.5 KB, 包含多尺寸)
7+
- ✅ macOS: `icon.icns` (包含所有Apple要求的尺寸)
8+
- ✅ Linux: `icon.png` 及各种PNG尺寸
9+
- ✅ NSIS安装界面: `nsis-header.bmp`, `nsis-sidebar.bmp`
10+
11+
### 2. 版本升级
12+
- ✅ 应用版本从 `0.1.0` 升级到 `0.1.1`
13+
- 这有助于Windows识别为新应用，避免图标缓存问题
14+
15+
### 3. 文件哈希验证
16+
```
17+
icon.ico SHA256: 688B47F08BF129B1DC2C2248E00A8FC6AB3A3746C0EABE756CD9EDB774DF4603
18+
文件大小: 64.5 KB
19+
主尺寸: 256x256 RGBA
20+
```
21+
22+
## 📋 用户安装步骤
23+
24+
### 方案A：标准安装（推荐）
25+
26+
1. **卸载旧版本**
27+
```bash
28+
# 通过Windows设置卸载
29+
# 设置 > 应用 > 已安装的应用 > Pyra > 卸载
30+
```
31+
32+
2. **清理图标缓存**（可选，如果仍显示旧图标）
33+
```powershell
34+
# 以管理员权限运行PowerShell
35+
.\force_icon_refresh.ps1
36+
```
37+
38+
3. **重新构建应用**
39+
```bash
40+
npm run tauri build
41+
```
42+
43+
4. **安装新版本**
44+
```
45+
运行: src-tauri\target\release\bundle\nsis\Pyra_0.1.1_x64-setup.exe
46+
```
47+
48+
5. **重启计算机**（如果图标仍未更新）
49+
50+
### 方案B：彻底清理（如果方案A无效）
51+
52+
1. **卸载应用**
53+
54+
2. **手动删除残留文件**
55+
```
56+
删除以下目录:
57+
%LOCALAPPDATA%\Pyra
58+
%APPDATA%\com.pyra.ide
59+
```
60+
61+
3. **运行图标缓存清理脚本**
62+
```powershell
63+
.\force_icon_refresh.ps1
64+
```
65+
66+
4. **重启计算机**
67+
68+
5. **重新安装**
69+
70+
## 🔧 图标缓存清理工具
71+
72+
### 使用 `force_icon_refresh.ps1`
73+
74+
此脚本会：
75+
- ✅ 停止Windows资源管理器
76+
- ✅ 删除所有图标缓存数据库文件
77+
- ✅ 清理开始菜单和任务栏缓存
78+
- ✅ 重建图标缓存
79+
- ✅ 刷新文件关联
80+
- ✅ 重启资源管理器
81+
82+
**运行方法：**
83+
```powershell
84+
# 右键点击 force_icon_refresh.ps1
85+
# 选择 "以管理员身份运行PowerShell"
86+
.\force_icon_refresh.ps1
87+
```
88+
89+
## 📝 注意事项
90+
91+
### Windows图标缓存特性
92+
- Windows会根据应用的**路径**、**版本**、**文件哈希**缓存图标
93+
- 即使更新了图标文件，旧缓存仍可能显示
94+
- 卸载后重新安装不一定清除缓存
95+
- 重启计算机是最可靠的缓存清理方法
96+
97+
### 如果仍显示旧图标
98+
1. 确认已完全卸载旧版本
99+
2. 运行图标缓存清理脚本
100+
3. 重启计算机
101+
4. 安装新版本 (0.1.1)
102+
5. 如果任务栏有快捷方式，取消固定后重新固定
103+
104+
### 开发环境注意
105+
如果您在开发环境中运行 `npm run tauri dev`，图标更新可能不会立即生效。这是正常的，因为：
106+
- 开发模式使用不同的应用路径
107+
- 需要重新构建才能看到图标更新
108+
- 建议测试图标时使用 `npm run tauri build` 构建正式版本
109+
110+
## 🎨 NSIS安装界面美化
111+
112+
安装/卸载程序现在包含：
113+
- 🎨 顶部横幅 (150x57) - 包含Pyra图标
114+
- 🎨 左侧边栏 (164x314) - 蓝色渐变背景
115+
- 🎨 格式化的安装/卸载进度信息
116+
- 🎨 友好的完成提示
117+
118+
## 🔄 未来更新图标
119+
120+
如果将来需要更新图标，请遵循以下步骤：
121+
122+
1. **准备新图标**
123+
- 图片必须是**正方形** (推荐1024x1024或512x512)
124+
- PNG格式，带透明背景 (RGBA)
125+
- 命名为 `icon.png`
126+
127+
2. **替换源图标**
128+
```bash
129+
# 替换文件
130+
cp new-icon.png src-tauri/icons/icon.png
131+
```
132+
133+
3. **重新生成所有平台图标**
134+
```bash
135+
npm run tauri icon "src-tauri/icons/icon.png"
136+
```
137+
138+
4. **升级版本号**
139+
```json
140+
// src-tauri/tauri.conf.json
141+
"version": "0.1.2" // 递增版本号
142+
```
143+
144+
5. **构建并测试**
145+
```bash
146+
npm run tauri build
147+
```
148+
149+
## 📞 问题反馈
150+
151+
如果遇到图标显示问题，请提供以下信息：
152+
- Windows版本
153+
- 是否运行了图标缓存清理脚本
154+
- 是否重启了计算机
155+
- Pyra版本号 (帮助 > 关于)
156+
- 截图显示问题
157+
158+
GitHub Issues: [项目仓库地址]

‎docs/USER_GUIDE.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,78 @@
8686
- **清空控制台** - 需要时重置输出
8787
- **可滚动历史** - 回顾之前的执行结果
8888

89+
## <i class="fas fa-bug"></i> 调试代码
90+
91+
### 开始调试
92+
1. **打开 Python 文件**（.py）
93+
2. **设置断点** - 点击行号左侧区域，会出现红色圆点
94+
3. **启动调试** - 点击工具栏的调试按钮（<i class="fas fa-bug"></i> 橙色虫子图标）
95+
4. **选择调试模式** - 从下拉菜单选择"调试"
96+
97+
### 调试控制操作
98+
- **<i class="fas fa-play"></i> 继续（F5）** - 继续执行直到下一个断点
99+
- **<i class="fas fa-arrow-right"></i> 单步跳过（F10）** - 执行当前行，不进入函数内部
100+
- **<i class="fas fa-arrow-down"></i> 单步进入（F11）** - 进入函数调用内部
101+
- **<i class="fas fa-arrow-up"></i> 单步跳出（Shift+F11）** - 跳出当前函数
102+
- **<i class="fas fa-stop"></i> 停止** - 停止调试会话
103+
104+
### 调试信息面板
105+
当程序暂停在断点时，调试面板会显示：
106+
107+
- **调用栈（Call Stack）**：
108+
- 显示函数调用层次
109+
- 点击不同的栈帧查看对应代码位置
110+
- 了解程序执行路径
111+
112+
- **变量查看器（Variables）**：
113+
- **局部变量（Locals）** - 当前函数内的变量
114+
- **全局变量（Globals）** - 全局作用域的变量
115+
- 展开嵌套对象查看详细内容
116+
- 实时显示变量值的变化
117+
118+
### 断点管理
119+
- **添加断点** - 点击行号左侧区域
120+
- **删除断点** - 再次点击红色圆点
121+
- **多个断点** - 可在不同位置设置多个断点
122+
- **断点验证** - 调试启动后断点会被验证
123+
124+
### 调试技巧
125+
- **在关键位置设置断点** - 在可能出错的代码行设置断点
126+
- **使用单步执行** - 逐行跟踪代码执行过程
127+
- **检查变量值** - 确认变量是否符合预期
128+
- **观察调用栈** - 了解函数调用顺序
129+
130+
### 安装 debugpy
131+
首次使用调试功能时，需要安装 debugpy：
132+
133+
1. **通过包管理器安装**：
134+
- 打开项目面板（<i class="fas fa-clipboard"></i>）
135+
- 搜索 "debugpy"
136+
- 点击安装
137+
138+
2. **或者使用命令行**：
139+
```bash
140+
# Windows
141+
.venv\Scripts\pip install debugpy
142+
143+
# Linux/macOS
144+
.venv/bin/pip install debugpy
145+
```
146+
147+
### 调试故障排除
148+
149+
**问：调试启动失败**
150+
- 答：确保已安装 debugpy（通过包管理器安装）
151+
- 答：确保虚拟环境已创建
152+
153+
**问：断点未命中**
154+
- 答：确保断点设置在可执行代码行（非空行或注释）
155+
- 答：重新启动调试会话
156+
157+
**问：变量显示不正确**
158+
- 答：确保程序已暂停在断点处
159+
- 答：点击调用栈中的正确栈帧
160+
89161
## <i class="fas fa-cog"></i> 设置与自定义
90162

91163
### 主题选项

‎docs/USER_GUIDE_EN.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,78 @@ Welcome to Pyra IDE! This guide will help you get started with our lightweight P
8686
- **Clear Console** - Reset output when needed
8787
- **Scrollable History** - Review previous execution results
8888

89+
## <i class="fas fa-bug"></i> Debugging Code
90+
91+
### Starting Debug
92+
1. **Open a Python file** (.py)
93+
2. **Set Breakpoints** - Click the line number gutter, red dots will appear
94+
3. **Start Debugging** - Click the debug button in toolbar (<i class="fas fa-bug"></i> orange bug icon)
95+
4. **Select Debug Mode** - Choose "Debug" from the dropdown menu
96+
97+
### Debug Controls
98+
- **<i class="fas fa-play"></i> Continue (F5)** - Continue execution until next breakpoint
99+
- **<i class="fas fa-arrow-right"></i> Step Over (F10)** - Execute current line without entering functions
100+
- **<i class="fas fa-arrow-down"></i> Step Into (F11)** - Step into function calls
101+
- **<i class="fas fa-arrow-up"></i> Step Out (Shift+F11)** - Exit current function
102+
- **<i class="fas fa-stop"></i> Stop** - Stop the debug session
103+
104+
### Debug Information Panel
105+
When the program pauses at a breakpoint, the debug panel displays:
106+
107+
- **Call Stack**:
108+
- Shows function call hierarchy
109+
- Click different stack frames to view corresponding code location
110+
- Understand program execution path
111+
112+
- **Variables Viewer**:
113+
- **Locals** - Variables in current function scope
114+
- **Globals** - Variables in global scope
115+
- Expand nested objects to view details
116+
- Real-time display of variable value changes
117+
118+
### Breakpoint Management
119+
- **Add Breakpoint** - Click the line number gutter
120+
- **Remove Breakpoint** - Click the red dot again
121+
- **Multiple Breakpoints** - Set breakpoints at different locations
122+
- **Breakpoint Verification** - Breakpoints are verified after debug starts
123+
124+
### Debugging Tips
125+
- **Set breakpoints at key locations** - Place breakpoints where errors might occur
126+
- **Use step execution** - Track code execution line by line
127+
- **Check variable values** - Verify variables match expectations
128+
- **Observe call stack** - Understand function call sequence
129+
130+
### Installing debugpy
131+
First-time use of debugging requires installing debugpy:
132+
133+
1. **Install via Package Manager**:
134+
- Open project panel (<i class="fas fa-clipboard"></i>)
135+
- Search for "debugpy"
136+
- Click Install
137+
138+
2. **Or use command line**:
139+
```bash
140+
# Windows
141+
.venv\Scripts\pip install debugpy
142+
143+
# Linux/macOS
144+
.venv/bin/pip install debugpy
145+
```
146+
147+
### Debug Troubleshooting
148+
149+
**Q: Debug fails to start**
150+
- A: Ensure debugpy is installed (via package manager)
151+
- A: Ensure virtual environment is created
152+
153+
**Q: Breakpoints not hit**
154+
- A: Ensure breakpoint is on executable code line (not empty or comment)
155+
- A: Restart debug session
156+
157+
**Q: Variables display incorrectly**
158+
- A: Ensure program is paused at breakpoint
159+
- A: Click the correct stack frame in call stack
160+
89161
## <i class="fas fa-cog"></i> Settings & Customization
90162

91163
### Theme Options

‎fix-uninstaller-icon.cjs‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Post-build script to fix uninstaller icon in NSIS installer
2+
const fs = require('fs');
3+
const path = require('path');
4+
5+
const installerPath = path.join(__dirname, 'src-tauri', 'target', 'release', 'nsis', 'x64', 'installer.nsi');
6+
7+
console.log('[Fix Uninstaller Icon] Reading installer.nsi...');
8+
9+
if (!fs.existsSync(installerPath)) {
10+
console.error('[Fix Uninstaller Icon] installer.nsi not found at:', installerPath);
11+
process.exit(1);
12+
}
13+
14+
let content = fs.readFileSync(installerPath, 'utf8');
15+
16+
// Check if MUI_UNICON is already defined
17+
if (content.includes('MUI_UNICON')) {
18+
console.log('[Fix Uninstaller Icon] MUI_UNICON already defined, skipping...');
19+
process.exit(0);
20+
}
21+
22+
// Find the MUI_ICON definition and add MUI_UNICON right after it
23+
const muiIconPattern = /(!define MUI_ICON "\$\{INSTALLERICON\}")/;
24+
25+
if (!muiIconPattern.test(content)) {
26+
console.error('[Fix Uninstaller Icon] Could not find MUI_ICON definition');
27+
process.exit(1);
28+
}
29+
30+
content = content.replace(
31+
muiIconPattern,
32+
'$1\n !define MUI_UNICON "${INSTALLERICON}"'
33+
);
34+
35+
fs.writeFileSync(installerPath, content, 'utf8');
36+
37+
console.log('[Fix Uninstaller Icon] Successfully added MUI_UNICON to installer.nsi');
38+
console.log('[Fix Uninstaller Icon] Now rebuilding NSIS installer...');

0 commit comments

Comments
 (0)