docs: 扩充 FAQ + 添加 Issue 模板
- README FAQ 新增 8 个高频问题（Node 版本兼容、npm 安装失败、U 盘格式、多 provider 配置、QQbot 编译等），中英文同步更新 - 新增 .github/ISSUE_TEMPLATE/：bug 报告模板（含环境信息字段）、功能建议模板、config.yml（禁用空白 issue，引导至 FAQ 和教程） Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
hfshfg
42
.github/ISSUE_TEMPLATE/bug_report.md
vendored
Normal file
42
.github/ISSUE_TEMPLATE/bug_report.md
vendored
Normal file
@@ -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.
|
||||||
|
|
||||||
|
## 已尝试的方法
|
||||||
|
|
||||||
|
<!-- 描述你试过哪些方法，避免重复建议 -->
|
||||||
|
|
||||||
|
## 截图（可选）
|
||||||
|
|
||||||
|
<!-- 如果有截图可以附上 -->
|
||||||
11
.github/ISSUE_TEMPLATE/config.yml
vendored
Normal file
11
.github/ISSUE_TEMPLATE/config.yml
vendored
Normal file
@@ -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
|
||||||
23
.github/ISSUE_TEMPLATE/feature_request.md
vendored
Normal file
23
.github/ISSUE_TEMPLATE/feature_request.md
vendored
Normal file
@@ -0,0 +1,23 @@
|
|||||||
|
---
|
||||||
|
name: 💡 功能建议
|
||||||
|
about: 建议新功能或改进现有功能
|
||||||
|
title: "[Feature] "
|
||||||
|
labels: enhancement
|
||||||
|
assignees: ''
|
||||||
|
---
|
||||||
|
|
||||||
|
## 建议描述
|
||||||
|
|
||||||
|
<!-- 你希望增加什么功能？解决什么问题？ -->
|
||||||
|
|
||||||
|
## 使用场景
|
||||||
|
|
||||||
|
<!-- 在什么情况下会用到这个功能？ -->
|
||||||
|
|
||||||
|
## 期望的效果
|
||||||
|
|
||||||
|
<!-- 描述理想的使用方式或界面 -->
|
||||||
|
|
||||||
|
## 补充信息
|
||||||
|
|
||||||
|
<!-- 其他相关背景、截图、参考项目等 -->
|
||||||
88
README.md
88
README.md
@@ -194,6 +194,50 @@ MIT 协议，随便复制分发。
|
|||||||
**Q: Mac 提示"未验证的开发者"？**
|
**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
|
- 微信: hecare888
|
||||||
@@ -413,6 +457,50 @@ MIT license — copy and share freely.
|
|||||||
**Q: Mac says "unverified developer"?**
|
**Q: Mac says "unverified developer"?**
|
||||||
Right-click the script → Open.
|
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
|
### Contact
|
||||||
|
|
||||||
- Telegram: [@dsds8848](https://t.me/dsds8848)
|
- Telegram: [@dsds8848](https://t.me/dsds8848)
|
||||||
|
|||||||
Reference in New Issue
Block a user