From 2b7522d173c2a6b438e6e6676bc18a5186bd3a58 Mon Sep 17 00:00:00 2001 From: hfshfg <38004547@qq.com> Date: Tue, 21 Apr 2026 11:47:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=89=A9=E5=85=85=20FAQ=20+=20?= =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20Issue=20=E6=A8=A1=E6=9D=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README FAQ 新增 8 个高频问题（Node 版本兼容、npm 安装失败、U 盘格式、多 provider 配置、QQbot 编译等），中英文同步更新 - 新增 .github/ISSUE_TEMPLATE/：bug 报告模板（含环境信息字段）、功能建议模板、config.yml（禁用空白 issue，引导至 FAQ 和教程） Co-Authored-By: Claude Sonnet 4.6 --- .github/ISSUE_TEMPLATE/bug_report.md | 42 +++++++++++ .github/ISSUE_TEMPLATE/config.yml | 11 +++ .github/ISSUE_TEMPLATE/feature_request.md | 23 ++++++ README.md | 88 +++++++++++++++++++++++ 4 files changed, 164 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..a48d51e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,42 @@ +--- +name: 🐛 Bug / 安装问题 +about: 运行出错、安装失败、功能异常 +title: "[Bug] " +labels: bug +assignees: '' +--- + +## 问题描述 + + + +## 环境信息 + +| 项目 | 填写 | +|------|------| +| 操作系统 | macOS / Windows 10 / Windows 11 | +| Node.js 版本 | `node -v` 的输出 | +| 使用方式 | 便携 U 盘版 / 一键安装版 / Electron 桌面版 / Linux 可启动版 | +| 出错步骤 | setup.bat / setup.sh / Windows-Start.bat / Mac-Start.command / 其他 | + +## 完整报错信息 + + + +``` +粘贴报错信息到这里 +``` + +## 复现步骤 + +1. +2. +3. + +## 已尝试的方法 + + + +## 截图（可选） + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..8868107 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: 📖 完整教程 + url: https://u-claw.org/tutorial.html + about: 从零开始的安装教程，含模型配置、平台接入 + - name: 🔍 查看 FAQ + url: https://github.com/dongsheng123132/u-claw#faq + about: 常见问题解答，先看这里 + - name: 💬 联系作者（微信） + url: https://u-claw.org/guide.html#remote-support + about: 远程协助安装，微信 hecare888 diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..926ce76 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: 💡 功能建议 +about: 建议新功能或改进现有功能 +title: "[Feature] " +labels: enhancement +assignees: '' +--- + +## 建议描述 + + + +## 使用场景 + + + +## 期望的效果 + + + +## 补充信息 + + diff --git a/README.md b/README.md index 382fdfe..180b351 100644 --- a/README.md +++ b/README.md @@ -194,6 +194,50 @@ MIT 协议，随便复制分发。 **Q: Mac 提示"未验证的开发者"？** 右键脚本 → 打开。 +**Q: setup.bat / setup.sh 执行失败，提示模块找不到？** +通常是 npm install 过程中网络中断导致 `node_modules` 不完整。解决步骤： +1. 删除不完整的依赖：`rmdir /s /q portable\app\core\node_modules`（Windows）或 `rm -rf portable/app/core/node_modules`（Mac） +2. 切换淘宝镜像重新安装：`cd portable/app/core && npm install --registry=https://registry.npmmirror.com` + +**Q: 系统已有 Node.js v24，安装失败？** +Node.js v24 是最新开发版，部分依赖尚不兼容。需要 **v20 或 v22 LTS**。删除已下载的 runtime 目录后重新运行 setup，它会自动下载内置的 Node v22： +```bash +# Windows +rmdir /s /q portable\app\runtime\node-win-x64 +setup.bat + +# Mac +rm -rf portable/app/runtime/node-mac-arm64 +bash setup.sh +``` + +**Q: Mac 上提示 `.toSorted is not a function`？** +系统旧版 Node.js 被检测到并跳过了内置版本下载，但旧版 Node 不支持 `.toSorted()`（需要 v20+）。删除 runtime 目录让脚本重新下载内置 Node v22： +```bash +rm -rf portable/app/runtime/node-mac-arm64 +bash setup.sh +``` + +**Q: 如何同时配置多个 AI 模型并切换？** +支持同时配置多个 provider！打开 `Config.html` → 在 Providers 区域点击「添加」，逐个填入各模型的 API Key 和地址（如 DeepSeek、Kimi、通义等）→ 保存后，在聊天界面左上角下拉菜单随时切换。配置持久保存在 U 盘上。 + +**Q: U 盘安装后无法创建文件 / 写入失败？** +两种可能：① U 盘侧面有物理写保护开关，拨到解锁位置；② U 盘格式不兼容，建议格式化为 **exFAT**（Mac/Windows/Linux 三端均支持读写）。 + +**Q: 从 Ubuntu 向 U 盘复制时符号链接丢失？** +`node_modules/.bin/` 下有大量符号链接，FAT32/exFAT 在直接 `cp -R` 时会跳过。用 `rsync -aL` 可将符号链接展开为真实文件： +```bash +rsync -aL --progress portable/ /media/YOUR_USB/U-Claw/ +``` + +**Q: QQbot 报错 `Unknown channel: qqbot`？** +Bundle 里的 `@sliverp/qqbot` 是未编译的 TypeScript 源码，需要先编译： +```bash +cd portable/app/core/node_modules/@sliverp/qqbot +npm install && npm run build +``` +正式 Release 包已修复此问题，建议从 [Releases](https://github.com/dongsheng123132/u-claw/releases) 下载最新版。 + ### 联系 - 微信: hecare888 @@ -413,6 +457,50 @@ MIT license — copy and share freely. **Q: Mac says "unverified developer"?** Right-click the script → Open. +**Q: setup.bat / setup.sh fails with "module not found"?** +Usually caused by a network interruption during `npm install`, leaving `node_modules` incomplete. Fix: +1. Delete incomplete dependencies: `rmdir /s /q portable\app\core\node_modules` (Windows) or `rm -rf portable/app/core/node_modules` (Mac) +2. Reinstall using China mirror: `cd portable/app/core && npm install --registry=https://registry.npmmirror.com` + +**Q: Already have Node.js v24 and installation fails?** +Node.js v24 is a dev release — some dependencies aren't compatible yet. You need **v20 or v22 LTS**. Delete the runtime folder to force a fresh download of the bundled Node v22: +```bash +# Windows +rmdir /s /q portable\app\runtime\node-win-x64 +setup.bat + +# Mac +rm -rf portable/app/runtime/node-mac-arm64 +bash setup.sh +``` + +**Q: Mac shows `.toSorted is not a function`?** +Your system Node.js was detected and the bundled version was skipped, but the system version is too old (needs v20+). Delete the runtime folder to re-download the bundled Node v22: +```bash +rm -rf portable/app/runtime/node-mac-arm64 +bash setup.sh +``` + +**Q: How do I use multiple AI models / providers?** +Multiple providers are supported! Open `Config.html` → click "Add" in the Providers section → enter API Key and endpoint for each model (DeepSeek, Kimi, Qwen, etc.) → save. Switch between models via the dropdown in the chat interface. Config is saved persistently on the USB drive. + +**Q: USB drive shows "cannot create file" / write errors?** +Two possibilities: ① The USB drive has a physical write-protect switch on the side — slide it to unlock; ② Format incompatibility — format the drive as **exFAT** (supported on Mac/Windows/Linux). + +**Q: Symlinks missing when copying from Ubuntu to USB?** +`node_modules/.bin/` contains many symlinks that get skipped during direct `cp -R`. Use `rsync -aL` to expand symlinks into real files: +```bash +rsync -aL --progress portable/ /media/YOUR_USB/U-Claw/ +``` + +**Q: QQbot error: `Unknown channel: qqbot`?** +The bundled `@sliverp/qqbot` is uncompiled TypeScript source. Compile it manually: +```bash +cd portable/app/core/node_modules/@sliverp/qqbot +npm install && npm run build +``` +This is fixed in the latest [Release](https://github.com/dongsheng123132/u-claw/releases) — downloading the pre-built release is recommended. + ### Contact - Telegram: [@dsds8848](https://t.me/dsds8848)