Files

Tests / test (push) Has been cancelled

Details

按 U-Claw-海外化改造方案.md 与 范围决策记录.md 实施。这是 fork，不回上游：
海外版删掉的正是上游的中国市场默认值。

阶段 0 地基
- 下载源全部改国际：脚本/CI 61 处 + lockfile 880 条 npmmirror URL 归零
  （lockfile 那 880 条是 npm 的 resolved 字段，脚本层参数化根本绕不过它）
- 移除 install.ps1 里三个第三方 GitHub 加速代理，bundle 改直连 + SHA256 校验
  （原来只检查"文件大于 1MB"就解压运行）
- 技能内容与分发分离：skills/manifest.json 单一来源，install.sh 1170→658 行、
  install.ps1 721→546 行，两者技能内容归零
  实测原来是三份不一致：skills-cn 完整、install.sh 约 40%、install.ps1 约 17%，
  且 7 个通用技能只有 U 盘版有 —— 一键安装的用户一个能用的技能都没有
- Node 版本三种（v22.14/16/22.1）统一，新建 NODE_VERSION 单一来源
- Config 页三份合一。portable/Config.html 用根相对路径调 API 却只从 file:// 打开，
  保存功能已静默失效两个月；现缩为 120 行重定向壳
- 测试接入 CI（此前 node --test 无人运行，所有断言形同虚设）

阶段 1 双语可用
- 浏览器侧 i18n：JSON 为源、生成经典 script（file:// 下 fetch 本地 JSON 被拦）
  语言跟盘走不跟机器走：启动器写 data/.openclaw/locale.js
- 8 处硬编码 lang="zh-CN" 归零，data-i18n 覆盖 213 处，词条 en/zh 各 279 条
- B3 单框 Key：12 张模型卡 → 一个输入框，前缀识别 provider，
  服务端 /api/test-key 发 1-token 请求实测，错误映射成人话
  Key 填错到得知：从"直到对话失败"降到 ≤1 秒
- 区域格式 SG：DD/MM/YYYY、12 小时、S$、Asia/Singapore
  （ICU 在 en-SG 下把 SGD 渲染成裸 $，与美元无法区分，故自行拼 S$）
- README 内容分叉而非翻译，§1.3 证据清单逐条清零

阶段 2 降门槛
- 启动逻辑上移 lib/start.mjs：Windows-Start.bat 220→28 行、
  Mac-Start.command 235→33 行
  修掉 Mac 侧两个 bug：控制台端口硬编码 18788（回落时打开死页）、
  微信插件从未在 Mac 上安装
- U 盘根目录 23 → 3 个可点文件，其余进 advanced/
- 首启向导：语言 → 用途（7 角色，manifest 驱动）→ 密钥，答过不再问
- 三档界面，Simple 档隐藏一切技术名词
- 自动自愈：启动失败先自查自修，修不好导出脱敏诊断包
  （Doctor 从"用户要知道去点的工具"变成后台机制）

阶段 3 技能库
- 19 个英文技能，planned 归零。sg-weather / sg-transport 的端点均实测过
- SkillHub 从 56 张手写第三方卡片改为 manifest 生成：703→125 行，中文归零

其他
- origin.json 收拢所有运行时地址，tests/origin.test.mjs 保证迁移不会漏
- portable/ 下用户可见中文归零（由断言保证）
- 82 项测试

未验证（本机无 Windows / 无 pwsh）：
- install.ps1、setup.ps1 约 210 行改动从未经 PowerShell 解析器
- 完整启动路径仅在假 node + 假 openclaw 上冒烟
- 8 个 .bat 的盘根推导仅静态断言
详见 U盘实测清单.md

受阻：
- 隐藏黑窗口 —— 需代码签名证书（.vbs 已被 Windows 弃用，替代方案都要签名）
- 场景卡 —— OpenClaw 上游 Dashboard 无预填 prompt 接口
- 官网 36 条 —— 上游 2026-04-14 拆到私有仓库，无权限

2026-08-17 18:37:49 +08:00

5.4 KiB

Raw Blame History

贡献指南 / Contributing to U-Claw

感谢有兴趣参与 U-Claw 开发！这份文档会告诉你怎么开始、怎么提 issue、怎么提 PR。

TL;DR

报 bug → 用 Bug 模板，贴完整报错，不要只发截图
提需求 → 用 Feature 模板，先说清楚使用场景
写代码 → fork → 改 → 自己跑过 → 提 PR，PR 说明照模板填，不要空白 PR
改文档 → 直接 PR 即可

项目结构（记住这个心智模型）

本仓库 = U 盘骨架：脚本 + HTML + 小文件 bash setup.sh 之后 = U 盘内容：骨架 + Node.js + OpenClaw

四种发布形态，互相独立，改其中一个不影响其它：

目录	形态	入口
`portable/`	便携 USB	`setup.sh` → `Mac-Start.command` / `Windows-Start.bat`
`u-claw-app/`	Electron 桌面	`npm run dev` / `npm run build:mac-arm64`
`bootable/`	Linux 可启动 U 盘	`1-prepare-usb.ps1` → `4-copy-to-usb.ps1`
`install/`	一键在线安装	`install.sh` (Mac/Linux) / `install.ps1` (Windows)

开发环境

# 1. Clone
git clone https://gitea.fanghe.it.com/zhenghy/u-claw.git
cd u-claw

# 2. 选一个形态调试。最快的是 portable/
cd portable
bash setup.sh                    # 下载 Node.js + OpenClaw 到 app/
bash Mac-Start.command           # macOS 启动
# 或 Windows: 双击 Windows-Start.bat

平台支持现状：

macOS Apple Silicon (ARM64)：✅ 主开发平台
macOS Intel：✅ 工作（需先跑 setup.sh 下 node-mac-x64）
Windows x64：🚧 持续完善
Linux x64 (Bootable USB)：✅ 用 bootable/

提 Issue 的好习惯

报 bug

至少包含这四样：

操作系统 + 版本（如 macOS 14.5 / Windows 11 23H2）
使用的形态（portable / install / bootable / u-claw-app）
完整的错误日志（贴文字，不要只截图）
你试过哪些步骤

不写复现步骤的 issue，维护者通常没办法处理。

提需求

先说使用场景，再说功能。
"我希望能 X" → 不够。"我在做 Y，需要 X，因为 Z" → 才能讨论。

提 PR 的好习惯

提交前先想清楚

改动是不是真的有人需要？ 大改动建议先开 issue 讨论。
改动会不会破坏其它形态？ 比如改 portable/ 不要影响 bootable/。
你跑过吗？ PR 模板里要求列出测试方式，不是装饰。

不要做的事

❌ 提交 node_modules/、app/、data/、*.dmg、*.exe（已在 .gitignore）
❌ 把 API Key、Token、密码写进任何文件
❌ 改 README 加自己的推广链接
❌ 提空白 PR（只有标题没说明）—— 会直接关闭
❌ 大规模格式化无关代码（"顺手 prettier 全仓"这种）

Commit message

短、说人话、能让维护者一眼看懂改了什么：

fix(portable): node-extract path missing intermediate dir
fix(install.sh): npm wrapper不能用 node 直接执行
docs: 补充 Windows 11 ARM64 支持说明
feat(skills): 增加 linkedin-post 技能

不接受："update"、"fix"、"修改若干文件" 这种。

分支与 PR 流程

# 1. fork → clone 你的 fork
git clone https://github.com/<你的用户名>/u-claw.git

# 2. 创建分支（不要在 main 上直接改）
git checkout -b fix/install-sh-npm-path

# 3. 改 → 自己跑过 → 提交
git add <具体文件>          # 不要 git add .
git commit -m "fix(install): ..."

# 4. 推到你的 fork
git push origin fix/install-sh-npm-path

# 5. 在 GitHub 上发起 PR，填好模板

修改各形态时的注意事项

`portable/`

不要在仓库里提交 app/ 或 data/，那是 setup.sh 下载/生成的
Mac 启动脚本要 chmod +x，并清理 quarantine 属性
Windows 启动脚本要正确处理 cd /d "%DIR%core"
配置文件放 data/.openclaw/openclaw.json，便携属性靠这个

`u-claw-app/` (Electron)

main.js 大约 400 行，改前先理解整体流程
Node.js 要找 resources/runtime/node-{platform}-{arch}，找不到再 fall back 到系统 node
用户配置在 app.getPath('userData')/.openclaw/，不要硬编码路径

`bootable/`

4 步 PowerShell 脚本必须按顺序跑
ISO 下载走清华/阿里/中科大镜像，不要直接用 ubuntu.com
bootable/ 与独立仓库 zhenghy/u-claw-linux 内容保持同步，改一边记得同步另一边

`install/`

Mac/Linux 走 install.sh，Windows 走 install.ps1
全部走 npmmirror.com 镜像，不能假设用户能访问 GitHub/npm 官方
安装目录固定为 ~/.uclaw/（Mac/Linux）或 %USERPROFILE%\.uclaw\（Windows）
启动脚本要找空闲端口（18789-18799），不要写死

`skills/`

技能格式是 <skill-name>/SKILL.md，frontmatter 里有 name、description、metadata
技能内容用中文写，给中国用户看
提交新技能前先看现有技能（小红书/微博/B 站等）的写法

行为准则

简单说：

对人有礼貌，对事可以严格
不要在 issue 里互相攻击
维护者可能回复慢（这是开源副业），请耐心
不接受任何形式的歧视、骚扰、钓鱼

联系

Issue 区：日常问题、bug、需求
官网：u-claw.org
邮件（仅紧急安全问题）：见 README

再次感谢！🦞

5.4 KiB Raw Blame History Unescape Escape