权益小助手开发
4.8 KiB
name, description
| name | description |
|---|---|
| bugpack-deploy | 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 on Windows using MSYS2 environment.
Prerequisites
- Windows OS
- MSYS2 installed (usually at
C:\msys64orD:\msys64) - Internet connection for downloading packages
Environment Setup
1. MSYS2 Configuration
Open MSYS2 terminal and update the system:
pacman -Syu
# If prompted to close terminal, close and reopen, then run:
pacman -Su
2. Install Required Tools
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:
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)
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
# 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
npm install
3. Build Project
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:
// 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
# 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:
export PATH="/mingw64/bin:$PATH"
Issue 2: libnode.dll: cannot open shared object file
Cause: DLL not found in library path.
Solution:
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:
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:
# 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:
- Check internet connection
- Switch to different network
- Or configure specific mirror:
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:
# 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:
{
"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}