Release v0.1.0: 小程序使用建议跳转腾讯文档 + 配置导入导出功能

2026-05-04 17:09:07 +08:00
commit 7d90523164
89 changed files with 18289 additions and 0 deletions
@@ -0,0 +1,221 @@
+---
+name: "bugpack-deploy"
+description: "Deploy and configure BugPack (bug screenshot to AI instructions tool) on Windows with MSYS2. Invoke when user asks to setup/install/deploy BugPack or fix its build/runtime issues."
+---
+
+# BugPack Deploy Skill
+
+This skill guides the deployment of [BugPack](https://github.com/duhuazhu/BugPack) on Windows using MSYS2 environment.
+
+## Prerequisites
+
+- Windows OS
+- MSYS2 installed (usually at `C:\msys64` or `D:\msys64`)
+- Internet connection for downloading packages
+
+## Environment Setup
+
+### 1. MSYS2 Configuration
+
+Open MSYS2 terminal and update the system:
+
+```bash
+pacman -Syu
+# If prompted to close terminal, close and reopen, then run:
+pacman -Su
+```
+
+### 2. Install Required Tools
+
+```bash
+pacman -S --noconfirm git curl make
+pacman -S --noconfirm mingw-w64-x86_64-nodejs
+pacman -S --noconfirm mingw-w64-x86_64-gcc
+```
+
+### 3. Node.js Environment Variables
+
+Add to `~/.bashrc` or export manually:
+
+```bash
+export PATH="/mingw64/bin:$PATH"
+export LD_LIBRARY_PATH="/mingw64/bin:$LD_LIBRARY_PATH"
+```
+
+**Note**: `LD_LIBRARY_PATH` is required because `libnode.dll` is in `/mingw64/bin`.
+
+### 4. Create Node.js Symlinks (Optional but recommended)
+
+```bash
+ln -sf /mingw64/bin/node.exe /usr/bin/node
+ln -sf /mingw64/lib/node_modules/npm/bin/npm-cli.js /usr/bin/npm
+ln -sf /mingw64/lib/node_modules/npm/bin/npx-cli.js /usr/bin/npx
+```
+
+## Deployment Steps
+
+### 1. Download BugPack
+
+```bash
+# Option A: Clone with git
+git clone https://github.com/duhuazhu/BugPack.git
+cd BugPack
+
+# Option B: Download and extract ZIP
+curl -L -o BugPack.zip https://github.com/duhuazhu/BugPack/archive/refs/heads/main.zip
+unzip BugPack.zip
+cd BugPack-main
+```
+
+### 2. Install Dependencies
+
+```bash
+npm install
+```
+
+### 3. Build Project
+
+```bash
+npm run build
+```
+
+### 4. Fix Static File Path (Production Mode)
+
+**Issue**: Server looks for `src/client/index.html` but built files are in `dist/client/`.
+
+**Fix**: Edit `src/server/index.ts`:
+
+```typescript
+// Before (line ~47):
+const clientDir = path.resolve(__dirname, '../client')
+
+// After:
+const clientDir = path.resolve(__dirname, '../../dist/client')
+const devClientDir = path.resolve(__dirname, '../client')
+const staticDir = fs.existsSync(clientDir) ? clientDir : devClientDir
+
+if (fs.existsSync(staticDir)) {
+  app.use(express.static(staticDir))
+  app.get('*', (req, res) => {
+    if (!req.path.startsWith('/api') && !req.path.startsWith('/uploads')) {
+      res.sendFile(path.join(staticDir, 'index.html'))
+    }
+  })
+}
+```
+
+### 5. Start Server
+
+```bash
+# Development mode (with auto-reload)
+npm run dev:server
+
+# Or specify custom port
+PORT=3458 npm run dev:server
+```
+
+Server will start at `http://localhost:3457` (or your custom port).
+
+## Common Issues & Solutions
+
+### Issue 1: `node: command not found`
+
+**Cause**: Node.js installed in `/mingw64/bin` but not in PATH.
+
+**Solution**:
+```bash
+export PATH="/mingw64/bin:$PATH"
+```
+
+### Issue 2: `libnode.dll: cannot open shared object file`
+
+**Cause**: DLL not found in library path.
+
+**Solution**:
+```bash
+export LD_LIBRARY_PATH="/mingw64/bin:$LD_LIBRARY_PATH"
+```
+
+### Issue 3: `better-sqlite3` build fails with `make: cc: No such file`
+
+**Cause**: C compiler not installed.
+
+**Solution**:
+```bash
+pacman -S --noconfirm mingw-w64-x86_64-gcc make
+```
+
+### Issue 4: `ENOENT: no such file or directory, stat '.../src/client/index.html'`
+
+**Cause**: Server configured for dev mode but running production build.
+
+**Solution**: Apply the static file path fix in Step 4 above.
+
+### Issue 5: `EADDRINUSE: address already in use :::3457`
+
+**Cause**: Another instance is running.
+
+**Solution**:
+```bash
+# Use different port
+PORT=3458 npm run dev:server
+```
+
+### Issue 6: MSYS2 mirror network issues
+
+**Symptom**: All mirrors return "Could not resolve host".
+
+**Solution**: Network environment issue. Try:
+1. Check internet connection
+2. Switch to different network
+3. Or configure specific mirror:
+```bash
+cat > /etc/pacman.d/mirrorlist.mingw64 << 'EOF'
+Server = https://mirrors.tuna.tsinghua.edu.cn/msys2/mingw/x86_64/
+Server = https://mirrors.ustc.edu.cn/msys2/mingw/x86_64/
+EOF
+pacman -Syy
+```
+
+## Verification
+
+After deployment, verify:
+
+```bash
+# Check server is running
+curl -s http://localhost:3457 | head -5
+
+# Expected output: HTML content starting with <!DOCTYPE html>
+```
+
+## MCP Server Configuration
+
+To integrate with Trae/Cursor/Claude Code, add MCP config:
+
+```json
+{
+  "mcpServers": {
+    "bugpack": {
+      "command": "npx",
+      "args": ["bugpack-mcp", "--mcp"]
+    }
+  }
+}
+```
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| Frontend | React 18 + TypeScript + Tailwind CSS |
+| Backend | Express + Node.js |
+| Database | SQLite (better-sqlite3) |
+| Annotation | Fabric.js v6 |
+| Build Tool | Vite |
+
+## Data Storage
+
+All data stored locally:
+- **Data directory**: `~/.bugpack/data/`
+- **Database**: `bugpack.db`
+- **Screenshots**: `uploads/{ProjectName}/{uuid}.{ext}`