Add AI install and repair skill

2026-10-07 16:48:03 +08:00 · 2026-05-26 08:57:22 +08:00
parent 7e6a1c938d
commit 0792605db6
2 changed files with 456 additions and 0 deletions
@@ -27,6 +27,8 @@ docs/backend_config.md

 ## 快速开始

+如果你想让 AI 助手代为安装和排错，可以把本仓库发给支持 Skills 的 AI 助手，并让它读取根目录 `SKILL.md`。
+
 ### 1. 安装后端

 如果你没有 Python，直接运行：
@@ -0,0 +1,454 @@
+---
+name: glm-coding-helper-install
+description: Install, configure, verify, explain, and repair the GLM Coding Helper project for non-technical Windows users. Use when a user wants an AI agent to set up the local CPU/GPU OCR backend, Tampermonkey userscript, GLM Coding Plan helper flow, captcha OCR service, GreasyFork/GitHub release copy, or troubleshoot backend/browser/OCR/payment-popup issues in this repository.
+---
+
+# GLM Coding Helper Install And Repair Skill
+
+This skill helps an AI agent install and repair the GLM Coding Helper project end to end.
+The target user may not know Python, PowerShell, Git, virtual environments, browser extension
+permissions, or OCR backends. Act as the user's local setup engineer.
+
+The project is a Tampermonkey userscript plus a local OCR backend:
+
+- Frontend userscript: `glm-coding-helper.user.js` at the repository root.
+- Compatibility userscript copy: `scripts/userscripts/glm-coding-helper.user.js`.
+- Backend startup wrapper: `scripts/start_backend.ps1`.
+- First-time Windows bootstrap: `scripts/bootstrap_windows.ps1`.
+- Backend setup wrapper: `scripts/setup_backend.ps1`.
+- Backend config reference: `docs/backend_config.md`.
+- Detector weights: `models/weights/yolo-captcha-detector.pt`.
+- Default backend URL: `http://127.0.0.1:8888`.
+
+Never expose or print the full built-in invite code. If checking for sensitive data, say that the
+full code was or was not found, but do not repeat it.
+
+## Operating Principles
+
+1. Prefer the repository scripts over manual package installation.
+2. Keep the user on Windows PowerShell unless they clearly use another OS.
+3. Verify every major step with a command or browser check.
+4. If a command fails, read the error and repair the specific cause instead of restarting blindly.
+5. Do not upload captcha screenshots to third-party OCR services. This project is designed for local OCR.
+6. Keep root `glm-coding-helper.user.js` and `scripts/userscripts/glm-coding-helper.user.js` synchronized if either one is edited.
+7. Default to safe payment behavior: invalid payment/rate-limit popups must not auto-close unless the user manually enables that setting.
+
+## Quick Install Workflow
+
+Use this workflow for a normal new Windows user.
+
+### 1. Locate The Repository
+
+Ask the user where the repository was downloaded or cloned. If you are already inside the repo,
+verify these files exist:
+
+```powershell
+Test-Path .\glm-coding-helper.user.js
+Test-Path .\scripts\bootstrap_windows.ps1
+Test-Path .\scripts\start_backend.ps1
+Test-Path .\models\weights\yolo-captcha-detector.pt
+```
+
+If any required file is missing, tell the user to download the full repository, not just the
+userscript file.
+
+### 2. Install The Backend
+
+If the user may not have Python installed, run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\bootstrap_windows.ps1 -Target auto
+```
+
+If Python is already installed, run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\setup_backend.ps1 -Target auto
+```
+
+Useful explicit modes:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\setup_backend.ps1 -Target cpu
+powershell -ExecutionPolicy Bypass -File scripts\setup_backend.ps1 -Target gpu
+powershell -ExecutionPolicy Bypass -File scripts\setup_backend.ps1 -Target both
+```
+
+Expected environments:
+
+- `.venv_paddle` for CPU inference.
+- `.venv_paddle_gpu` for GPU inference.
+
+### 3. Start The Backend
+
+Start with auto mode:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode auto
+```
+
+Force GPU:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode gpu
+```
+
+Force CPU:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode cpu
+```
+
+Force CPU with a worker count:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode cpu -CpuWorkers 3
+```
+
+If the user wants a visible backend window, use the normal wrapper above. If they want terminal-only
+operation, use the Python headless entry described in `docs/backend_config.md`.
+
+### 4. Verify The Backend
+
+Run:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:8888/health
+```
+
+The response should include fields like:
+
+- `backend.ocr_mode`
+- `backend.cpu_workers`
+- `backend.gpu_available`
+- selected YOLO/OCR settings
+
+If `/health` fails, the userscript cannot solve captchas. Fix the backend first.
+
+### 5. Install The Userscript
+
+Tell the user to install Tampermonkey, then:
+
+1. Open root `glm-coding-helper.user.js`.
+2. Copy all content.
+3. Create a new Tampermonkey script.
+4. Paste and save.
+5. Open the GLM Coding Plan page.
+
+For Chrome extension permissions, guide the user to:
+
+1. Open `chrome://extensions/`.
+2. Enable Developer mode in the top right.
+3. Open Tampermonkey details.
+4. Enable "Allow user scripts".
+5. Enable "Allow in Incognito" if they use incognito windows.
+6. Enable "Allow access to file URLs" if they install from a local file.
+
+### 6. Confirm Browser To Backend Connectivity
+
+The userscript sends captcha requests to:
+
+```text
+http://127.0.0.1:8888
+```
+
+If the browser shows network errors, confirm:
+
+- backend is running,
+- `/health` works,
+- local firewall did not block Python,
+- the userscript is enabled on the GLM page,
+- the page URL matches the script includes for `bigmodel.cn`.
+
+## Recommended User Operation During GLM Rush
+
+Use the user's own procedure when explaining the workflow:
+
+1. Install Tampermonkey, configure the userscript, and enable required Chrome extension permissions.
+2. Install the backend from GitHub manually or ask an AI assistant to follow this skill.
+3. Open the rush page and test that everything works before the real rush window.
+4. Enter the rush page before 9:50 every day. It may be hard to open later.
+5. Prepare mobile Alipay payment in advance. A payment page with an amount can still fail if payment is too late.
+6. Open several windows. Near 10:00, solve/click captchas but do not confirm too early; start confirming at 10:00.
+7. If the first wave fails, keep one window and let local OCR identify and click.
+8. The script defaults to not closing payment pages automatically.
+9. If a payment page has no amount, it usually means that attempt did not get stock; close it and continue.
+
+Shortcut keys:
+
+- `Esc`: close a busy/payment popup.
+- `Enter` or `Space`: click the captcha confirm button.
+
+## How It Works
+
+The userscript modifies and automates the GLM Coding Plan page:
+
+1. It makes package buttons clickable earlier when the page marks them disabled.
+2. It scans package/month choices in the configured priority order.
+3. It opens or watches purchase/captcha dialogs.
+4. When a Chinese click captcha appears, it sends the prompt text to the local backend.
+5. The backend captures/crops the captcha from the local browser window.
+6. YOLO detects the candidate character boxes.
+7. OCR recognizes the detected boxes using CPU or GPU PaddleOCR workers.
+8. Prompt-constrained matching maps the requested characters to detected boxes.
+9. The backend returns click positions.
+10. The userscript clicks the requested boxes and can press confirm with a shortcut.
+
+GPU mode is usually faster. CPU mode uses a parallel worker pool and should still be usable on
+ordinary machines. The backend auto mode tries GPU first when available, then falls back to CPU.
+
+Payment safety:
+
+- Real payment pages should stay open.
+- Invalid payment or rate-limit popups are not auto-closed by default.
+- Auto-close behavior exists only after the user manually enables it in the config panel.
+
+## Backend Configuration
+
+Prefer command-line flags first:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode auto
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode gpu
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode cpu -CpuWorkers 3
+```
+
+Use environment variables only for advanced repair:
+
+```powershell
+$env:CNCAPTCHA_PORT='8888'
+$env:CNCAPTCHA_OCR_MODE='cpu'
+$env:CNCAPTCHA_CPU_OCR_WORKERS='3'
+$env:CNCAPTCHA_YOLO_DEVICE='cpu'
+$env:CNCAPTCHA_SKIP_GPU_DETECT='1'
+```
+
+Common detector override:
+
+```powershell
+$env:CNCAPTCHA_DETECTOR_PATH='D:\path\to\yolo-captcha-detector.pt'
+```
+
+## QA And Troubleshooting
+
+### Q: The user has no Python.
+
+Run the bootstrap script:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\bootstrap_windows.ps1 -Target auto
+```
+
+It should find Python 3.12, install through `winget` if possible, or download the official Python
+installer. If corporate policy blocks installers, ask the user to install Python 3.12 manually,
+then run `scripts\setup_backend.ps1`.
+
+### Q: PowerShell says script execution is disabled.
+
+Use the per-command bypass form:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\setup_backend.ps1 -Target auto
+```
+
+Do not ask the user to permanently weaken system policy unless necessary.
+
+### Q: `winget` is missing.
+
+The bootstrap script should fall back to official Python download. If that fails, send the user to
+install Python 3.12 from python.org, then run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\setup_backend.ps1 -Target auto
+```
+
+### Q: GPU mode fails.
+
+Check:
+
+```powershell
+nvidia-smi
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode auto
+```
+
+If `nvidia-smi` is missing or Paddle cannot see CUDA, use CPU:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode cpu
+```
+
+Explain that users do not need GPU for correctness; GPU mainly reduces latency.
+
+### Q: CPU is slow.
+
+Try worker tuning:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode cpu -CpuWorkers 2
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode cpu -CpuWorkers 3
+```
+
+More workers are not always faster. On low-core machines, too many workers can slow down OCR.
+
+### Q: `/health` does not respond.
+
+Check whether the server process is running and whether port 8888 is occupied:
+
+```powershell
+netstat -ano | findstr :8888
+```
+
+If occupied by an old process, close the old backend window or kill the specific PID only after
+confirming it belongs to the old backend. Alternatively use another port:
+
+```powershell
+$env:CNCAPTCHA_PORT='8890'
+powershell -ExecutionPolicy Bypass -File scripts\start_backend.ps1 -Mode auto
+```
+
+If changing the port, the userscript must also be updated to call that port.
+
+### Q: Tampermonkey script does not run.
+
+Check:
+
+- script is enabled,
+- the page is under `bigmodel.cn`,
+- Chrome Developer mode is enabled,
+- Tampermonkey permissions are enabled,
+- the script was saved after paste,
+- browser console has no syntax error.
+
+If the user installed from GitHub, tell them to use root `glm-coding-helper.user.js`, not only a
+partial snippet.
+
+### Q: Captcha appears but no automatic click happens.
+
+Check in order:
+
+1. Backend `/health` works.
+2. Backend window logs receive a `/captcha` request.
+3. Browser console does not show connection refused.
+4. The GLM page is visible and not minimized.
+5. Windows scaling or multi-monitor layout did not move the screenshot area unexpectedly.
+6. The captcha prompt text contains Chinese characters.
+7. Detector weight exists at `models/weights/yolo-captcha-detector.pt`.
+
+If logs say the popup was not found or was closed, ask the user to keep the captcha popup visible
+and retry.
+
+### Q: OCR returns wrong positions.
+
+Collect one failing screenshot if the user agrees. Do not send it to third-party OCR. Inspect:
+
+- detected boxes count,
+- OCR text for each box,
+- whether prompt characters are visually similar,
+- whether the browser zoom/scaling is unusual,
+- whether the captcha is partially covered.
+
+Then retry CPU/GPU mode. If one mode is consistently better, force that mode.
+
+### Q: Error says OCR result cannot map prompt to boxes.
+
+This means detection or recognition produced boxes/text that cannot match the prompt. Fix by:
+
+1. ensuring the popup is fully visible,
+2. retrying once,
+3. switching OCR mode,
+4. reducing visual obstruction,
+5. checking whether the prompt text was read correctly.
+
+### Q: Payment page still auto-closes.
+
+Verify the userscript version is current and contains the safe default migration:
+
+- root `glm-coding-helper.user.js` should be installed,
+- `AUTO_CLOSE_INVALID` should default to `false`,
+- config panel should not have auto-close enabled,
+- Tampermonkey may still run an older saved script, so reinstall from root file if needed.
+
+The intended default is: payment/rate-limit popups stay open unless the user manually enables
+auto-close.
+
+### Q: User sees a payment page with no amount.
+
+Explain that a no-amount payment page usually means the attempt did not really get stock. The user
+can close it and continue. If they want speed, `Esc` closes the popup.
+
+### Q: User sees a payment page with an amount.
+
+Tell the user not to close it automatically. They should confirm the amount and pay manually.
+
+### Q: GitHub users cannot find the script.
+
+Point them to the repository root:
+
+```text
+glm-coding-helper.user.js
+```
+
+The nested `scripts/userscripts/` copy is for development and old-path compatibility.
+
+### Q: Root and nested userscripts differ.
+
+Synchronize them before release. On Windows:
+
+```powershell
+Copy-Item -LiteralPath .\glm-coding-helper.user.js -Destination .\scripts\userscripts\glm-coding-helper.user.js -Force
+Get-FileHash .\glm-coding-helper.user.js
+Get-FileHash .\scripts\userscripts\glm-coding-helper.user.js
+```
+
+The hashes should match.
+
+## Release Checks For Agents
+
+Before publishing changes:
+
+```powershell
+node --check .\glm-coding-helper.user.js
+node --check .\scripts\userscripts\glm-coding-helper.user.js
+Get-FileHash .\glm-coding-helper.user.js
+Get-FileHash .\scripts\userscripts\glm-coding-helper.user.js
+git diff --check
+git status --short
+```
+
+Search for sensitive data without printing secrets:
+
+```powershell
+rg -n "api[_-]?key|password|secret" .
+```
+
+Also search for any known private invite code if the maintainer provides it out of band, but do not
+print that code in logs, public docs, or final answers.
+
+## Escalation Guidance
+
+Ask the user before:
+
+- installing Python or dependencies,
+- changing firewall/security settings,
+- killing a process,
+- changing browser extension permissions on their behalf,
+- pushing to GitHub or publishing to GreasyFork.
+
+Proceed without asking when:
+
+- reading repository files,
+- checking file existence,
+- running `/health`,
+- running syntax checks,
+- updating documentation in the local working tree after the user asked for it.
+
+## Final Report Template
+
+When finished, tell the user:
+
+- what was installed or changed,
+- which commands verified it,
+- the backend URL,
+- whether CPU or GPU is active,
+- how to install/update the userscript,
+- any remaining manual step, especially browser permissions or payment confirmation.