docs: 中文 README 与英文版同步

中文版一直是上游的旧内容，和英文版已经完全对不上：虾盘云首选卡片、 10 个中国技能、QQ 列为预装、还夹着上游另一个产品的推广段落。312 → 165 行。现在两版讲同一个产品，面向新加坡的华语用户，而不是中国市场。顺带修掉一条和事实相反的建议：中文版原来写着「U 盘请用 NTFS 格式（不要 exFAT/FAT32）」。macOS 对 NTFS 只读 —— 照做的话「配置跟着盘走」在 Mac 上直接失效，首次启动连配置都写不进去。这和 release.yml 里那条是同一个错误，两处都改了。英文版补上 fork 说明（原来只写在 CLAUDE.md 里），两版现在都写明这是 dongsheng123132/u-claw 的分支、且不向上游提交。新增断言 tests/i18n-pages.test.mjs：两版必须互链、必须都写明是 fork、必须都建议 exFAT 且不得出现推荐 NTFS 的措辞、中文版不得再出现英文版已经删掉的那批上游内容。这条断言的存在是因为它们上次就是这么漂开的。
2026-08-17 19:29:03 +08:00
parent 45026b9d35
commit d2cd9d4528
3 changed files with 137 additions and 246 deletions
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,15 +1,15 @@
 <p align="center">
-  <img src="assets/readme/hero.svg" alt="U-Claw：随身携带的 AI 工作空间" width="100%" />
+  <img src="assets/readme/hero.svg" alt="U-Claw —— 装在 U 盘里的 AI 工作空间" width="100%" />
 </p>

-<h1 align="center">U-Claw（虾盘）</h1>
+<h1 align="center">U-Claw</h1>

-<p align="center"><strong>把 AI 工作空间装进 U 盘：插上任意电脑，配置、记忆和工具都跟着走。</strong></p>
+<p align="center"><strong>装在 U 盘里的 AI 工作空间。插到任何一台电脑上，设置、记忆和工具都跟着走。</strong></p>

 <p align="center">
-  <a href="https://gitea.fanghe.it.com/zhenghy/u-claw/releases">下载便携版</a> ·
-  <a href="https://u-claw.org/tutorial.html">完整教程</a> ·
-  <a href="#快速开始制作便携版-u-盘">从源码制作</a> ·
+  <a href="https://gitea.fanghe.it.com/zhenghy/u-claw/releases">下载</a> ·
+  <a href="#三步开始">三步开始</a> ·
+  <a href="#自己构建">从源码构建</a> ·
  <a href="README.md">English</a>
 </p>

@@ -20,293 +20,146 @@
 </p>

 > [!IMPORTANT]
-> 这不是 U 盘制作工具。这个仓库就是 U 盘的文件骨架：运行一次 `setup.sh` 补齐运行时，再把整个 `portable/` 拷到盘里即可。
+> 这个仓库不是"做 U 盘的工具"，**它本身就是 U 盘里的内容**。跑一次 `setup.sh` 把运行时补齐，然后把 `portable/` 整个拷到盘里就行。
+
+## 为什么是 U 盘
+
+三个理由，也就是这个产品的全部卖点：
+
+1. **公司电脑经常不让装软件。** 金融、政府外包和多数受监管行业都锁得很死。U 盘不需要安装程序，也不需要管理员权限。
+2. **你的配置跟着你走。** 模型密钥、聊天记录、项目记忆都在盘上的 `data/` 里，不在你临时借用的那台机器上。
+3. **主机上不留东西。** 拔盘走人。（有一条要说清楚：为了让慢速 U 盘启动不至于难以忍受，U-Claw 会往主机本地磁盘写一份可重建的缓存。`advanced/` 里有一键清理。）

 ## 三步开始

-1. 从 [Releases](https://gitea.fanghe.it.com/zhenghy/u-claw/releases) 下载 Windows 便携版，解压到 U 盘后双击 `START HERE - Windows.bat`。
-2. 或克隆仓库，在 `portable/` 运行 `bash setup.sh`，下载 Node.js 与 OpenClaw。
-3. 首次启动在本地配置模型 Key；配置只保存在 U 盘的 `data/.openclaw/openclaw.json`。
+1. 从 [Releases](https://gitea.fanghe.it.com/zhenghy/u-claw/releases) 下载便携版，解压到 U 盘，双击 `START HERE - Windows.bat`（或 `START HERE - Mac.command`）
+2. 设置页会自动打开。**粘贴一个 API 密钥就行** —— U-Claw 会自己认出是哪家的，并在接受之前先测一下通不通
+3. 开始对话

-| 你得到什么 | 为什么重要 |
-| --- | --- |
-| 随身 AI 工作空间 | 换电脑时带走配置、记忆与工具，不在主机残留用户数据。 |
-| 本地优先 | 不绑定设备、不打指纹、不上传本地配置。 |
-| 多种使用方式 | 便携 U 盘、在线一键安装、可启动 Linux U 盘各自独立。 |
+**还没有密钥？** [Google Gemini](https://aistudio.google.com/apikey) 最容易拿：用 Google 账号登录，不用绑卡，有免费额度。想一个密钥用多种模型的话，[OpenRouter](https://openrouter.ai/keys) 是不错的第二选择。

-> [!TIP]
-> ### 👑 同作者新品：U-King · AI 装机管家
-> 一键装好 **Claude Code / Codex / OpenClaw / Hermes** 四大 AI 神器，驱动自动配好——一个 Key 直用 Claude、GPT、DeepSeek、Kimi 等 24+ 全球模型，免翻墙。绿色版仅几 MB，双击即用，还带 AI 作图 / 视频 / 本地大模型 / 多终端工作台。
->
-> **免费下载：[www.u-king.org](https://www.u-king.org)**（国内镜像 [cloud.u-claw.org/uking](https://cloud.u-claw.org/uking/)）
->
-> *U-Claw 让 AI 住进 U 盘；U-King 帮你把全套 AI 编程神器装进电脑。*
-> *EN: U-King — one-click installer for Claude Code / Codex / OpenClaw, with one API key for 24+ global models → [u-king.org](https://www.u-king.org)*
+## 用哪个模型

---
+| 模型 | 适合 |
+|---|---|
+| **Claude** | 综合最强 |
+| **GPT** | 用的人最多 |
+| **Gemini** | 有免费额度，注册最简单 |
+| **SEA-LION** | 马来语、泰米尔语、Singlish —— AI Singapore 做的 |
+| **本地模型** | 离线。数据不出这台机器。 |

-<a id="中文"></a>
+其他模型（DeepSeek、Kimi、通义、GLM 等）在设置页的「高级」里填自己的接口地址即可。

-## 中文
+> **关于 SEA-LION**：托管 API 免费，但目前限流 **每人每分钟 10 次请求**，且官方没公布付费档。聊天够用，agent 类工作量偏紧 —— 所以它是特色选项而不是默认。

-### 这是什么
-
-U-Claw（虾盘）是一个**制作教程 + 全套源代码**，教你把 [OpenClaw](https://github.com/openclaw/openclaw)（开源 AI 助手框架）做成 U 盘——插上任意电脑，双击就能用 AI。为什么叫虾盘？U-Claw = USB + Claw（虾钳），U 盘 + AI = 虾盘。
-
-代码库本身就是 U 盘的文件骨架，运行 `setup.sh` 补齐大依赖后，整个 `portable/` 目录直接拷贝到 U 盘即可。
-
-> 📖 **[完整教程](https://u-claw.org/tutorial.html)** — 从零开始的手工安装指南、模型配置、聊天平台接入，小白也能看懂。
-
-### 🧩 模型随便选：国内外大模型都能用
-
-U-Claw 是纯开源工具，**不绑定设备、不打指纹、不上传任何数据**。首次启动会自动打开 Config 页面，选一个模型、填入自己的 API Key 即可一键启动：
-
- **虾盘云（首选 · 中转站）**：一个 Key 调用 DeepSeek / Claude / GPT / 通义 等国内外全部大模型，无需翻墙。注册并充值：[u-claw.org/cloud.html](https://u-claw.org/cloud.html)
- **各家官方 Key 也行**：DeepSeek、通义千问、Kimi、智谱 GLM、豆包、MiniMax（国内）/ OpenAI、Claude、Groq（国外）/ 硅基流动、任意 OpenAI 兼容地址（自定义）
- **配置只存在本地** `data/.openclaw/openclaw.json`，拔盘不留痕
-
-### 一键安装（推荐）
-
-不需要 U 盘，一行命令直接装到电脑：
-
-```bash
-# Mac / Linux
-curl -fsSL https://u-claw.org/install.sh | bash
-
-# Windows (PowerShell 管理员)
-irm https://u-claw.org/install.ps1 | iex
-```
-
-自动完成: Node.js 下载 → OpenClaw 安装 → 10 个中国技能 → 模型配置 → 启动脚本生成。全程国内镜像，无需翻墙。
-
-详见 [`install/README.md`](install/README.md)。
-
-### 快速开始：制作便携版 U 盘
-
-```bash
-# 1. 克隆代码
-git clone https://gitea.fanghe.it.com/zhenghy/u-claw.git
-
-# 2. 补齐大依赖（Node.js + OpenClaw，国内镜像，约 1 分钟）
-cd u-claw/portable/advanced && bash setup.sh
-
-# 3. 拷贝到 U 盘
-cp -R portable/ /Volumes/你的U盘/U-Claw/   # Mac
-# 或 Windows 资源管理器直接拖过去
-```
-
-**完成！** 插上 U 盘，双击启动脚本就能用。
-
-### U 盘功能一览
-
-| 功能 | Mac | Windows |
-|------|-----|---------|
-| **免安装运行** | `START HERE - Mac.command` | `START HERE - Windows.bat` |
-| **功能菜单** | `Mac-Menu.command` | `Windows-Menu.bat` |
-| **安装到电脑** | `Mac-Install.command` | `Windows-Install.bat` |
-| **首次配置** | `Config.html` | `Config.html` |
-
-### U 盘文件结构
-
-```
-U-Claw/                          ← 整个拷到 U 盘
-├── START HERE - Mac.command             Mac 免安装运行
-├── Mac-Menu.command              Mac 功能菜单
-├── Mac-Install.command           安装到 Mac
-├── START HERE - Windows.bat             Windows 免安装运行
-├── Windows-Menu.bat              Windows 功能菜单
-├── Windows-Install.bat           安装到 Windows
-├── Config.html                   首次配置页面
-├── setup.sh                      补齐依赖（开发者用）
-├── app/                          ← 大依赖（setup.sh 下载，不进 git）
-│   ├── core/                        OpenClaw + QQ 插件
-│   └── runtime/
-│       ├── node-mac-arm64/          Mac Apple Silicon
-│       ├── node-mac-x64/           Mac Intel
-│       └── node-win-x64/           Windows 64-bit
-└── data/                         ← 用户数据（不进 git）
-    ├── .openclaw/                   配置文件
-    ├── memory/                      AI 记忆
-    └── backups/                     备份
-```
-
-### Linux 可启动版
-
-连操作系统都没有？没关系。可启动版可以让任意电脑从 U 盘直接启动 Ubuntu + AI：
-
- 本仓库内：[`bootable/`](bootable/) 目录（与其他模块完全独立，互不影响）
- 独立仓库：[u-claw-linux](https://gitea.fanghe.it.com/zhenghy/u-claw-linux)（内容一致，方便单独克隆）
-
-基于 Ventoy + Ubuntu 24.04 LTS + 持久化存储，在 Windows 上运行 4 步 PowerShell 脚本即可制作。详见 [`bootable/README.md`](bootable/README.md)。
-
-> **关于桌面安装版（Electron）**：`u-claw-app/` 的 Electron 桌面版（`.exe` 安装版 / 绿色版 / `.dmg`）**已于 2026-06-19 停止发布并归档**，原因见 [`u-claw-app/DEPRECATED.md`](u-claw-app/DEPRECATED.md)。U-Claw 现在只发布「便携 U 盘版」——这才是产品的本质：插上 U 盘、解压即用。
-
-### 直接下载发行版
-
-[GitHub Releases](https://gitea.fanghe.it.com/zhenghy/u-claw/releases) 提供便携 U 盘版：
-
- `u-claw-portable-windows-vX.Y.Z.zip` — Windows 便携完整版（已预装 Node + OpenClaw，**解压到 U 盘双击 `START HERE - Windows.bat` 即用**）
- **Mac**：源码在 [`portable/`](portable/) 目录，`bash setup.sh` 自动下载 Node + OpenClaw（国内镜像约 1 分钟），双击 `START HERE - Mac.command` 启动
-
-> ⚠️ **U 盘请用 NTFS 格式**（不要 exFAT/FAT32）：Node.js 在 exFAT 上 IO 极慢且不支持符号链接，可能导致启动失败。
-
-### 支持的 AI 模型
-
-**国产模型（无需翻墙）：**
-
-| 模型 | 推荐场景 |
-|------|----------|
-| DeepSeek | 编程首选，极便宜 |
-| Kimi K2.5 | 长文档，256K 上下文 |
-| 通义千问 Qwen | 免费额度大 |
-| 智谱 GLM | 学术场景 |
-| MiniMax | 语音多模态 |
-| 豆包 Doubao | 火山引擎 |
-
-**国际模型：** Claude · GPT · Gemini（需翻墙或中转）
-
-### 支持的聊天平台
+## 聊天软件

 | 平台 | 状态 | 说明 |
-|------|------|------|
-| QQ | ✅ 已预装 | 输入 AppID + Secret 即可 |
-| 飞书 | ✅ 内置 | 企业首选 |
-| Telegram | ✅ 内置 | 海外推荐 |
-| WhatsApp | ✅ 内置 | Baileys 协议 |
+|---|---|---|
+| Telegram | ✅ 内置 | — |
+| WhatsApp | ⚠️ 内置 | 用的是 Baileys 非官方协议，**账号有被封的真实风险**。接入之前先看设置页里的提示，不要接你离不开的号码 |
 | Discord | ✅ 内置 | — |
-| 微信 | ✅ 社区插件 | iPad 协议 |
+| Slack | ✅ 内置 | — |
+| 微信 · QQ · 飞书 · 钉钉 | 可选 | 主要给在中国的用户，在设置页的折叠区里 |

-### 国内镜像
-
-所有脚本默认走国内镜像，无需翻墙：
-
-| 资源 | 镜像 |
-|------|------|
-| npm 包 | `registry.npmmirror.com` |
-| Node.js | `npmmirror.com/mirrors/node` |
-| Electron | `npmmirror.com/mirrors/electron` |
-
-### 开发 & 贡献
+## 自己构建

 ```bash
-git clone https://gitea.fanghe.it.com/zhenghy/u-claw.git
-cd u-claw/portable/advanced && bash setup.sh
-bash "START HERE - Mac.command"   # Mac 测试
+git clone ssh://git@gitea.fanghe.it.com:222/zhenghy/u-claw.git
+cd u-claw/portable/advanced && bash setup.sh     # 下载 Node.js + OpenClaw，约一分钟
+
+cp -R portable/ /Volumes/你的U盘/U-Claw/          # Mac
+# Windows 上直接把文件夹拖到盘里
 ```

-**平台支持：**
+## 盘上有什么

-| 平台 | 状态 | 说明 |
-|------|------|------|
-| Mac Apple Silicon (M1-M4) | ✅ | 便携版 |
-| Mac Intel (x64) | ✅ | 便携版 |
-| Windows x64 | 🚧 开发中 | 便携版 |
-| Linux x64（可启动 U 盘） | ✅ | [`bootable/`](bootable/) 目录 |
+U 盘里**只有三个能点的文件**，其余都在 `advanced/` 里。

-欢迎 PR！特别需要：Windows 脚本完善、教程翻译。
+| | Mac | Windows |
+|---|---|---|
+| **启动** | `START HERE - Mac.command` | `START HERE - Windows.bat` |
+| **看说明** | `Read me first.html` | `Read me first.html` |
+| **设置** | 首次启动自动打开 | 首次启动自动打开 |
+| *诊断、命令行、装到本机* | `advanced/` | `advanced/` |

-### 🦞 寻找技术伙伴
+```
+U-Claw/
+├── START HERE - Windows.bat      ← 双击这个
+├── START HERE - Mac.command      ← 或这个
+├── Read me first.html            三步上手
+├── advanced/                     诊断、命令行、装到电脑、构建脚本
+├── skills/                       技能内容和 manifest.json
+├── lib/                          启动器、i18n、辅助脚本
+├── app/                          运行时（setup.sh 下载，不在 git 里）
+└── data/                         你的数据（不在 git 里）
+    ├── .openclaw/                配置
+    ├── memory/                   AI 记住的东西
+    └── backups/
+```

-U-Claw 是一个快速成长的开源项目，目前已有不少商业合作机会。
+## Linux 可启动 U 盘

-我们正在寻找：
- **技术伙伴** — 全栈 / Node.js / Electron / 脚本自动化
- **资源合作** — 渠道、内容、社区运营
+目标电脑上连操作系统都没有？从盘启动进 Ubuntu，U-Claw 已经装好。见 [`bootable/`](bootable/)，基于 Ventoy + Ubuntu 24.04 LTS + 持久化。

-如果你对 AI 工具的落地和商业化感兴趣，欢迎联系：
+> Electron 桌面版（`u-claw-app/`）**已于 2026-06-19 停止发布**，代码仅作存档，见 [`u-claw-app/DEPRECATED.md`](u-claw-app/DEPRECATED.md)。便携 U 盘版才是产品本体。

- 微信: hecare888
- Telegram: [@dsds8848](https://t.me/dsds8848)
- Twitter/X: [@Bitplus888](https://x.com/Bitplus888)
- Email: [hefangsheng@gmail.com](mailto:hefangsheng@gmail.com)
- GitHub: [@dongsheng123132](https://github.com/dongsheng123132)
- 官网: [u-claw.org](https://u-claw.org)
+## 这安全吗

-### FAQ
+- **你的 API 密钥只写在盘上。** 除了你自己选的那家模型服务商，不会发到任何地方。
+- **没有任何遥测。** 不打设备指纹、不上报使用情况、不需要注册账号 —— 这些代码在这个版本里根本不存在。
+- **对话记录留在盘上的 `data/` 里。**
+- **确实会离开这台机器的**：你发的消息会到你配置的那家模型服务商，和你直接用他们的 App 是一样的。如果这对你的数据不可接受，请用本地模型。

-**Q: 需要翻墙吗？**
-不需要。安装和运行全程使用国内镜像，国产模型 API 直连。
+## U 盘用什么格式

-**Q: U 盘需要多大？**
-4GB+（完整约 2.3GB）。
+**exFAT。不要用 NTFS。**

-**Q: 能分发吗？**
-MIT 协议，随便复制分发。
+macOS 对 NTFS **只读**，用 NTFS 的话「配置跟着盘走」这件事在 Mac 上直接失效 —— 首次启动连配置都写不进去。

-**Q: Mac 提示"未验证的开发者"？**
-右键脚本 → 打开。
+exFAT 处理大量小文件确实慢，所以 U-Claw 启动时会把可重建的缓存挪到主机本地磁盘。你的实际数据仍然留在盘上。

-**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`
+## 参与开发
+
+见 [CONTRIBUTING.md](CONTRIBUTING.md)。每次 push 前会跑测试：

-**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
+node --test
 ```

-**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
-```
+> 不是 `node --test tests/` —— Node 会把那个路径当模块加载并报 `Cannot find module`，一个测试都不跑。

-**Q: 如何同时配置多个 AI 模型并切换？**
-支持同时配置多个 provider！打开 `Config.html` → 在 Providers 区域点击「添加」，逐个填入各模型的 API Key 和地址（如 DeepSeek、Kimi、通义等）→ 保存后，在聊天界面左上角下拉菜单随时切换。配置持久保存在 U 盘上。
+它检查的是那些会悄悄坏掉的东西：启动器有没有保持精简、`.bat` 有没有保持纯 ASCII、有没有中国下载源溜回来、两个安装器对技能的处理是否一致、每个界面字符串是不是在每种语言里都有。

-**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://gitea.fanghe.it.com/zhenghy/u-claw/releases) 下载最新版。
+**Mac 和 Windows 都能用吗？**
+同一个盘，两边都能用。Windows 版发布时已经带好运行时；Mac 第一次启动会自己下载，约一分钟。

-### 联系 & 合作
+**我的设置存在哪？**
+盘上的 `data/.openclaw/openclaw.json`。复制这个盘，就复制了你的整套配置。

-<img src="assets/wechat-qr.jpg" width="220" alt="微信二维码 — 贺去病 ai 工作室" align="right" />
+**能离线用吗？**
+可以，用本地模型。其他都需要能连上你的模型服务商。

- 微信: hecare888（或扫右侧二维码）
- Telegram: [@dsds8848](https://t.me/dsds8848)
- Twitter/X: [@Bitplus888](https://x.com/Bitplus888)
- Email: [hefangsheng@gmail.com](mailto:hefangsheng@gmail.com)
- GitHub: [@dongsheng123132](https://github.com/dongsheng123132)
- 官网: [u-claw.org](https://u-claw.org)
+**界面语言能改吗？**
+能，设置页里。而且**语言记在盘上而不是浏览器里** —— 你把盘插到同事的英文系统上，看到的仍然是中文。

-**🤝 招募代理 / 带货合作**
+## 关于这个分支

-虾盘 3.0 体验极佳，退货率极低，售后由我们负责——你只管卖货：
+这是 [dongsheng123132/u-claw](https://github.com/dongsheng123132/u-claw) 的一个 fork，面向新加坡 / 东南亚市场做了改造：默认值国际化、界面双语、降低非技术用户的上手门槛。

- **抖店 / 直播带货**：提供最高佣金比例，产品已在多个直播间验证转化
- **代理分销**：买断或按单分润均可谈，支持定制版本
- **技术合作**：有开发能力者欢迎深度合作
- **👑 U-King 装机管家分销（新）**：[U-King](https://www.u-king.org) 软件本身免费送客户，客户按用量给 AI 模型 API 充值，你拿**持续分润**——不压货、零售后（我们负责），赚的是长期流水。适合装机店、AI 培训、社群主理人
+**我们不向上游提交改动** —— 这个版本移除的中国市场默认值，恰恰是上游项目存在的意义。

-有意向请微信联系（备注「代理合作」优先处理）。
-
---
-
-<a id="english"></a>
+## 联系

+- Issues — [gitea.fanghe.it.com/zhenghy/u-claw/issues](https://gitea.fanghe.it.com/zhenghy/u-claw/issues)

 ---

 <p align="center"><a href="README.md">English</a> · <strong>中文</strong></p>
+
+<p align="center">MIT License</p>