feat: restructure repo for collaboration + add desktop app source

- Reorganize project: clean structure (portable/ u-claw-app/ usb-scripts/ website/) - Move docs into website/, rename uclaw-scripts to usb-scripts - Add u-claw-app/ Electron desktop source code - Add portable/setup.sh: one-command dev environment setup - Add portable/SkillHub.html: skill marketplace page - Update README: dev guide, contribution workflow, project structure - Update .gitignore: exclude runtime binaries and build artifacts - Expand China install guide: npm mirrors, detailed onboard wizard
2026-03-12 10:59:26 +08:00
parent 75b5daab57
commit be734cb111
21 changed files with 16931 additions and 171 deletions
--- a/README.md
+++ b/README.md
@@ -1,174 +1,198 @@
-# 🦞 U-Claw 虾盘
+# 🦞 U-Claw

-**Portable AI Agent — 插上就能用的 AI 助手**
-
-**Portable AI Agent — Double-click to run, no installation needed**
-
-> 像当年的雨林木风，把 AI 助手简化到"双击运行"。
-> Like the legendary YuLinMuFeng installer discs, but for AI.
+**把 AI 助手简化到"双击运行" — Portable AI Agent, double-click to run**

 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

+U-Claw 把 [OpenClaw](https://github.com/openclaw/openclaw) 打包成开箱即用的形态。Node.js + OpenClaw + 全部依赖 + QQ 插件，不需要翻墙，不需要命令行基础。
+
 ---

-## Why U-Claw? / 为什么需要 U-Claw？
-
-[OpenClaw](https://github.com/openclaw/openclaw) is the most powerful open-source AI assistant framework. But in China, installing it is a nightmare: GitHub blocked, npm timeout, Node.js download slow.
-
-[OpenClaw](https://github.com/openclaw/openclaw) 是最强的开源 AI 助手框架，但在中国安装它是个噩梦。
-
-**U-Claw bundles everything.** Node.js + OpenClaw + all dependencies + QQ plugin, pre-built and ready to run.
-
-**U-Claw 全部打包好。** Node.js + OpenClaw + 所有依赖 + QQ 插件，双击即用。
-
-## Quick Start / 快速开始
-
-### Option 1: Download Release / 从 Releases 下载（推荐）
-
-1. Download [U-Claw-v1.1.tar.gz](https://github.com/dongsheng123132/u-claw/releases)
-2. Extract anywhere (USB drive, Desktop, Documents)
-3. Mac: double-click `Mac-Start.command` / Windows: double-click `Windows-Start.bat`
-4. Browser opens automatically — configure your AI model and API key
-
-下载解压，双击启动，浏览器自动打开配置页面。
-
-### Option 2: USB Install Script / U 盘安装脚本
-
-USB drive has install scripts that auto-extract + launch:
- Mac: `Mac-Install.command`
- Windows: `Windows-Install.bat`
-
-### Option 3: Copy / 复制别人的
-
-Just copy the `U-Claw/` folder. That's it.
-
-直接复制 `U-Claw/` 文件夹就行。
-
-## Directory Structure / 目录结构
+## 项目结构

 ```
-U-Claw/                           (~2.3GB)
-├── Mac-Start.command             ← Mac: double-click to start
-├── Windows-Start.bat             ← Windows: double-click to start
-├── Mac-Menu.command              ← Mac: config & maintenance menu
-├── Windows-Menu.bat              ← Windows: config & maintenance menu
-├── U-Claw.html                   ← Navigation page / 导航页面
-├── app/
-│   ├── core/                     ← OpenClaw + deps + QQ plugin
+U-Claw/
+├── portable/              ← 🔥 U盘便携版（核心）
+│   ├── Mac-Start.command       Mac 启动脚本
+│   ├── Windows-Start.bat       Windows 启动脚本
+│   ├── Mac-Menu.command        Mac 菜单（8 个功能）
+│   ├── Windows-Menu.bat        Windows 菜单
+│   ├── Config.html             首次配置页面
+│   ├── U-Claw.html             导航首页
+│   ├── SkillHub.html           技能市场
+│   ├── default-config.json     默认配置模板
+│   └── migrate.js              配置迁移工具
+│
+├── u-claw-app/            ← 🖥 桌面安装版（Electron）
+│   ├── src/main.js             主进程（11K 行）
+│   ├── package.json            依赖 & 构建配置
+│   ├── assets/                 图标资源
+│   ├── resources/              Config.html + Node.js 运行时
+│   └── scripts/                构建脚本
+│
+├── usb-scripts/           ← 💾 U盘安装脚本
+│   ├── Mac-Install.command     Mac: 解压 + 启动
+│   └── Windows-Install.bat     Windows: 解压 + 启动
+│
+├── website/               ← 🌐 官网 + 教程（u-claw.org）
+│   ├── index.html              官网首页
+│   ├── guide.html              帮助指南
+│   ├── skills.html             技能市场页
+│   └── 教程-OpenClaw中国区完全指南.md
+│
+└── README.md
+```
+
+## 两个产品线
+
+### 1. U盘便携版 (`portable/`)
+
+**用户体验：** 插 U 盘 → 双击启动 → 浏览器打开配置页 → 开始用
+
+```
+portable/
+├── app/                    ← 运行时（不进 git，~2.3GB）
+│   ├── core/                  OpenClaw + 依赖 + QQ 插件
 │   └── runtime/
-│       ├── node-mac-arm64/       ← Mac Apple Silicon
-│       └── node-win-x64/         ← Windows 64-bit
-├── data/                         ← User data (config, memory, backups)
-└── system/
-    └── migrate.js                ← Config migration
+│       ├── node-mac-arm64/    Mac Apple Silicon
+│       └── node-win-x64/     Windows 64-bit
+├── data/                   ← 用户数据（不进 git）
+│   ├── .openclaw/             配置文件
+│   ├── memory/                AI 记忆
+│   └── backups/               备份
+└── [脚本和HTML]             ← 这些进 git
 ```

-## Menu / 菜单功能
+**分发方式：** 把整个 `portable/` + `app/` 打包成 `U-Claw.tar.gz`（约 743MB），用 `usb-scripts/` 的脚本解压启动。

-8 options, covering config and maintenance:
+**状态：** ✅ Mac Apple Silicon 可用 · 🚧 Windows 开发中 · ❌ Mac Intel / Linux 暂不支持

-```
-[1] Setup wizard (model, API key) / 配置向导
-[2] Open web dashboard / 打开网页控制台
-[3] QQ Bot (pre-installed) / QQ 机器人（已预装）
-[4] Other platforms (Feishu/Telegram/WeChat) / 其他平台
-[5] Diagnostics / 诊断修复
-[6] Backup / 备份配置
-[7] Restore / 恢复备份
-[8] System info / 系统信息
+### 2. 桌面安装版 (`u-claw-app/`)
+
+**用户体验：** 下载 DMG/EXE → 安装 → 打开 App → 自动配置
+
+```bash
+# 开发
+cd u-claw-app
+npm install
+npm start           # 本地运行
+
+# 构建
+npm run build:mac        # → release/U-Claw-x.x.x.dmg
+npm run build:mac-arm64  # → ARM64 版
+npm run build:win        # → release/U-Claw-x.x.x.exe
 ```

-## AI Models / 支持的 AI 模型
+**状态：** 🚧 Mac ARM64 基本可用 · 🚧 Windows 开发中 · ❌ Linux 暂不支持

-### Chinese Models (no VPN) / 国产模型（无需翻墙）
+## 支持的 AI 模型

-| Model 模型 | Best for 推荐场景 |
-|------------|-------------------|
-| DeepSeek | Coding, best value / 编程首选 |
-| Kimi K2.5 | Long docs, 256K context / 长文档 |
-| Qwen 通义千问 | Large free tier / 免费额度大 |
-| GLM 智谱 | Academic / 学术 |
-| MiniMax | Voice, multimodal / 语音 |
-| Doubao 豆包 | Volcano Engine / 火山引擎 |
+### 国产模型（无需翻墙）

-### International Models / 国际模型
+| 模型 | 推荐场景 |
+|------|----------|
+| DeepSeek | 编程首选，极便宜 |
+| Kimi K2.5 | 长文档，256K 上下文 |
+| 通义千问 Qwen | 免费额度大 |
+| 智谱 GLM | 学术场景 |
+| MiniMax | 语音多模态 |
+| 豆包 Doubao | 火山引擎 |

-Claude (Anthropic) · GPT (OpenAI) · Gemini (Google)
+### 国际模型

-## Chat Platforms / 聊天平台
+Claude · GPT · Gemini（需翻墙或中转）

-| Platform 平台 | Status 状态 | Notes 说明 |
-|---------------|------------|------------|
-| QQ | ✅ **Pre-installed 已预装** | Just enter AppID + Secret |
-| Feishu 飞书 | ✅ Built-in 内置 | Enterprise / 企业首选 |
-| Telegram | ✅ Built-in 内置 | International / 海外推荐 |
-| WhatsApp | ✅ Built-in 内置 | Baileys protocol |
-| Discord | ✅ Built-in 内置 | — |
-| Slack | ✅ Built-in 内置 | — |
-| WeChat 微信 | ✅ Community plugin | iPad protocol |
+## 支持的聊天平台

-### QQ Setup (1 min) / QQ 接入（1 分钟）
+| 平台 | 状态 | 说明 |
+|------|------|------|
+| QQ | ✅ 已预装 | 输入 AppID + Secret 即可 |
+| 飞书 | ✅ 内置 | 企业首选 |
+| Telegram | ✅ 内置 | 海外推荐 |
+| WhatsApp | ✅ 内置 | Baileys 协议 |
+| Discord | ✅ 内置 | — |
+| 微信 | ✅ 社区插件 | iPad 协议 |

-QQ plugin is pre-installed! Just:
-1. Visit q.qq.com, create a bot, get AppID and AppSecret
-2. Run `Mac-Menu.command`, choose [3] QQ Bot
-3. Enter AppID and AppSecret, done
+## 参与开发

-## System Requirements / 系统要求
+### 环境要求

- **macOS**: Apple Silicon (M1-M4), macOS 12+
- **Windows**: 10/11, 64-bit
- **RAM**: 2GB+ (4GB+ recommended)
- **Storage**: 3GB+
+- Node.js 22+
+- macOS 12+ 或 Windows 10+

-## Upgrade / 升级
+### 开发 portable 版

-Replace `app/` with new version. `data/` stays (config and memory preserved).
+```bash
+git clone https://github.com/dongsheng123132/u-claw.git
+cd u-claw/portable

-下载新版替换 `app/`，`data/` 不动。
-
-## USB Drive Structure / U 盘结构
+# 一键搭建运行环境（自动下载 Node.js + OpenClaw + QQ 插件）
+bash setup.sh

+# 启动测试
+bash Mac-Start.command   # Mac
+# 或双击 Windows-Start.bat  # Windows
 ```
-UCLAW (USB Drive)
-├── Mac-Install.command       ← First run (extract + launch)
-├── Windows-Install.bat
-├── U-Claw.tar.gz             ← Compressed package (743MB)
-├── README.txt                ← Instructions
-└── Toolkit/                  ← Engineer DIY kit
-    ├── node-v22-mac-arm64.pkg
-    ├── node-v22-win-x64.msi
-    ├── openclaw-source.tar.gz
-    └── npm-cache.tar.gz
+
+`setup.sh` 会自动：
+1. 检测你的系统（Mac ARM/Intel/Linux）
+2. 从国内镜像下载 Node.js v22
+3. 安装 OpenClaw + QQ 插件到 `app/` 目录
+
+### 开发桌面版
+
+```bash
+cd u-claw-app
+npm install --registry=https://registry.npmmirror.com
+npm start        # 开发模式运行
+npm run build:mac   # 打包
 ```

+### 提交代码
+
+```bash
+git checkout -b feat/your-feature
+# 改代码...
+git add -A
+git commit -m "feat: your change"
+git push -u origin feat/your-feature
+# 在 GitHub 上创建 PR
+```
+
+## 待开发 / 欢迎贡献
+
+- [ ] Windows 便携版完善测试
+- [ ] Mac Intel 支持
+- [ ] Linux 支持（AppImage）
+- [ ] 桌面版自动更新
+- [ ] 一键安装到电脑（永久模式）
+- [ ] 在线安装脚本（curl 一行安装）
+- [ ] SkillHub 技能市场功能完善
+- [ ] 多语言支持（English UI）
+
 ## FAQ

-**Q: Need VPN? / 需要翻墙吗？**
-No for installation. Runtime needs internet for AI APIs — Chinese models work without VPN.
+**Q: 需要翻墙吗？**
 安装不需要。运行需要联网调 API，国产模型无需翻墙。

-**Q: Can I share it? / 能分发吗？**
-Yes, MIT license, copy freely.
-可以，MIT 协议，随便复制。
+**Q: 能分发吗？**
+MIT 协议，随便复制。

-**Q: Windows needs WSL?**
-No. Bundled Windows Node.js runs natively.
+**Q: Mac 提示"未验证的开发者"？**
+右键脚本 → 打开。
+
+**Q: Windows 需要 WSL？**
 不需要，自带 Windows 版 Node.js。

-**Q: Mac says "unverified developer"?**
-Right-click the script → Open.
-右键点击脚本 → 打开。
-
 ## License

 [MIT](LICENSE)

-## Contact / 联系
+## 联系

- WeChat 微信: hecare888
+- 微信: hecare888
 - GitHub: [@dongsheng123132](https://github.com/dongsheng123132)
- Website 官网: [u-claw.org](https://u-claw.org)
+- 官网: [u-claw.org](https://u-claw.org)

 ---