不是翻译 —— 多数文档描述的行为已经不存在了。 先修一个更基本的问题：我们不拥有 u-claw.org 域名，那是上游的。所以之前写在 README、诊断包提示、联系方式里的 help@u-claw.org 全都会把用户的问题发给 上游 —— 一个没有理由回复的人。改为指向我们自己的 issue tracker，并加断言 禁止再出现指向该域名的支持入口。 重写（内容过时，不是语言问题）： - install/README.md —— 还写着 10 个中国技能、DeepSeek 优先、国内镜像。 现在按实际流程写：技能读 manifest、模型菜单 Gemini 优先、bundle 有 SHA256 校验。并如实写明 curl|bash 在受管企业电脑上会被 EDR 拦。 - CLAUDE.md 的模型配置整节 —— 还在描述虾盘云首选卡片和 12 个 provider， 那个界面已经换成单框 Key 输入了。 - SECURITY.md —— 安全报告原本指向上游维护者个人邮箱。fork 之后那条路由 是错的：漏洞会发给写不了这份代码、也修不了的人。 - CONTRIBUTING.md —— 补上 fork 关系、pre-push 钩子怎么装、以及 `node --test tests/` 为什么不能用。 翻译并保留： - bootable/README.md、TROUBLESHOOTING.md —— 面向用户，顺带把 「国内镜像」「小米/华为 BIOS 按键」等换成目标市场的实际情况 HANDOFF.md 重写为一份事故复盘：原文一半是过时的一次性交接笔记（引用的 website/guide.html 已不在本仓库），另一半是 persistence.dat 未格式化导致 启动失败的排查记录 —— 后者有长期价值，尤其是「读 offset 1080 的两字节 验证 ext4」这个判断方法，已同时写进 bootable/README.md。 bootable/IMPROVEMENTS_SUMMARY.md 保留中文，加了说明：它是上游 fork 前的 历史改进记录，没人引用，描述的是已完成的工作而非当前行为。翻译它反而会 让人误以为是现行文档。 新增 skills/en/uclaw-help —— 把「怎么用、东西在哪、出问题怎么办」做成 内置知识，每个角色都装。方案 C10.8：能问的产品才是不需要学的产品。
This commit is contained in:
237
CONTRIBUTING.md
237
CONTRIBUTING.md
@@ -1,164 +1,147 @@
|
||||
# 贡献指南 / Contributing to U-Claw
|
||||
# Contributing
|
||||
|
||||
感谢有兴趣参与 U-Claw 开发！这份文档会告诉你怎么开始、怎么提 issue、怎么提 PR。
|
||||
## The mental model, first
|
||||
|
||||
## TL;DR
|
||||
> **This repository is the USB drive's contents** — scripts, HTML, small files.
|
||||
> **After `setup.sh` it is a working drive** — the above plus Node.js and OpenClaw.
|
||||
|
||||
- **报 bug** → 用 [Bug 模板](.github/ISSUE_TEMPLATE/bug_report.md)，**贴完整报错**，不要只发截图
|
||||
- **提需求** → 用 [Feature 模板](.github/ISSUE_TEMPLATE/feature_request.md)，先说清楚使用场景
|
||||
- **写代码** → fork → 改 → 自己跑过 → 提 PR，PR 说明照模板填，不要空白 PR
|
||||
- **改文档** → 直接 PR 即可
|
||||
It is not a build tool that produces a drive. It *is* the drive. That one idea
|
||||
explains most of the layout.
|
||||
|
||||
## 项目结构（记住这个心智模型）
|
||||
Four distribution forms, deliberately independent — changing one does not touch
|
||||
the others:
|
||||
|
||||
> **本仓库 = U 盘骨架**：脚本 + HTML + 小文件
|
||||
> **`bash setup.sh` 之后 = U 盘内容**：骨架 + Node.js + OpenClaw
|
||||
| Directory | Form | Entry point |
|
||||
|---|---|---|
|
||||
| `portable/` | USB drive — **the main product** | `advanced/setup.sh` → `START HERE - Mac.command` |
|
||||
| `bootable/` | Linux USB that boots a machine with no OS | `1-prepare-usb.ps1` → `4-copy-to-usb.ps1` |
|
||||
| `install/` | One-line network install | `install.sh` / `install.ps1` |
|
||||
| `u-claw-app/` | Electron desktop — **deprecated**, archive only | not built |
|
||||
|
||||
四种发布形态，互相独立，改其中一个不影响其它：
|
||||
## This is a fork
|
||||
|
||||
| 目录 | 形态 | 入口 |
|
||||
|------|------|------|
|
||||
| `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) |
|
||||
Upstream is `github.com/dongsheng123132/u-claw`. We host at
|
||||
`gitea.fanghe.it.com/zhenghy/u-claw` and **do not send changes back**: this build
|
||||
removes the China-market defaults that are the point of the upstream project.
|
||||
|
||||
## 开发环境
|
||||
If you are fixing something we inherited unchanged, consider telling them too.
|
||||
|
||||
## Getting set up
|
||||
|
||||
```bash
|
||||
# 1. Clone
|
||||
git clone https://gitea.fanghe.it.com/zhenghy/u-claw.git
|
||||
git clone ssh://git@gitea.fanghe.it.com:222/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
|
||||
# Enable the pre-push hook. Nothing installs it for you, and it is the only
|
||||
# thing reliably running the tests — see below.
|
||||
git config core.hooksPath .githooks
|
||||
|
||||
# The fastest thing to iterate on is the portable build
|
||||
cd portable/advanced && bash setup.sh # fetches Node.js + OpenClaw into ../app/
|
||||
cd .. && bash "START HERE - Mac.command"
|
||||
```
|
||||
|
||||
平台支持现状：
|
||||
| Platform | State |
|
||||
|---|---|
|
||||
| macOS Apple Silicon | ✅ main development platform |
|
||||
| macOS Intel | ✅ works — `setup.sh` fetches `node-mac-x64` first |
|
||||
| Windows x64 | 🚧 **needs verification** — see below |
|
||||
| Linux x64 | ✅ via `bootable/` |
|
||||
|
||||
- macOS Apple Silicon (ARM64)：✅ 主开发平台
|
||||
- macOS Intel：✅ 工作（需先跑 setup.sh 下 node-mac-x64）
|
||||
- Windows x64：🚧 持续完善
|
||||
- Linux x64 (Bootable USB)：✅ 用 `bootable/`
|
||||
> **Windows currently carries unverified changes.** A large amount of PowerShell
|
||||
> and several `.bat` path-resolution changes were written on a Mac with no
|
||||
> PowerShell available, so they have never been through a parser. If you have a
|
||||
> Windows machine, running that check is the single most useful thing you can do
|
||||
> right now. `U盘实测清单.md` in the workspace root has the exact commands.
|
||||
|
||||
## 提 Issue 的好习惯
|
||||
|
||||
### 报 bug
|
||||
|
||||
**至少包含这四样**：
|
||||
|
||||
1. 操作系统 + 版本（如 macOS 14.5 / Windows 11 23H2）
|
||||
2. 使用的形态（portable / install / bootable / u-claw-app）
|
||||
3. **完整的错误日志**（贴文字，不要只截图）
|
||||
4. 你试过哪些步骤
|
||||
|
||||
不写复现步骤的 issue，维护者通常没办法处理。
|
||||
|
||||
### 提需求
|
||||
|
||||
- 先说**使用场景**，再说功能。
|
||||
- "我希望能 X" → 不够。"我在做 Y，需要 X，因为 Z" → 才能讨论。
|
||||
|
||||
## 提 PR 的好习惯
|
||||
|
||||
### 提交前先想清楚
|
||||
|
||||
1. **改动是不是真的有人需要？** 大改动建议先开 issue 讨论。
|
||||
2. **改动会不会破坏其它形态？** 比如改 `portable/` 不要影响 `bootable/`。
|
||||
3. **你跑过吗？** 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 流程
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
# 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，填好模板
|
||||
node --test # everything
|
||||
node --test tests/windows-launchers.test.mjs # one file
|
||||
```
|
||||
|
||||
## 修改各形态时的注意事项
|
||||
**Not `node --test tests/`.** Node reads that path as a module to load and dies
|
||||
with "Cannot find module" — zero tests run, exit code 1. That form was the
|
||||
documented command here for a long time, which is a good part of why the suite
|
||||
went unrun for the life of the project.
|
||||
|
||||
### `portable/`
|
||||
The suite asserts on the *text and behaviour* of scripts rather than spawning
|
||||
OpenClaw: that `.bat` files stay pure ASCII (Chinese Windows `cmd.exe` reads
|
||||
non-ASCII as GBK and mis-parses), that `.command` files stay LF-only, that no
|
||||
China-routed download source comes back, that both installers resolve skills
|
||||
identically, that every UI string exists in every language, and that nothing
|
||||
points at a host `origin.json` does not declare.
|
||||
|
||||
- **不要在仓库里提交 `app/` 或 `data/`**，那是 `setup.sh` 下载/生成的
|
||||
- Mac 启动脚本要 `chmod +x`，并清理 quarantine 属性
|
||||
- Windows 启动脚本要正确处理 `cd /d "%DIR%core"`
|
||||
- 配置文件放 `data/.openclaw/openclaw.json`，便携属性靠这个
|
||||
CI runs it where a runner exists (`.gitea/workflows/tests.yml`, mirrored to
|
||||
`.github/`). On our Gitea there is currently no registered runner, so the
|
||||
pre-push hook is doing the work. Install it.
|
||||
|
||||
### `u-claw-app/` (Electron)
|
||||
## Filing an issue
|
||||
|
||||
- `main.js` 大约 400 行，改前先理解整体流程
|
||||
- Node.js 要找 `resources/runtime/node-{platform}-{arch}`，找不到再 fall back 到系统 node
|
||||
- 用户配置在 `app.getPath('userData')/.openclaw/`，不要硬编码路径
|
||||
**A bug report needs four things**, or nobody can act on it:
|
||||
|
||||
### `bootable/`
|
||||
1. OS and version — `macOS 14.5`, `Windows 11 23H2`
|
||||
2. Which form — portable / install / bootable
|
||||
3. **The full error as text.** Not a screenshot of text.
|
||||
4. What you already tried
|
||||
|
||||
- 4 步 PowerShell 脚本必须**按顺序**跑
|
||||
- ISO 下载走清华/阿里/中科大镜像，不要直接用 ubuntu.com
|
||||
- `bootable/` 与独立仓库 `zhenghy/u-claw-linux` 内容保持同步，改一边记得同步另一边
|
||||
**A feature request needs a situation, not a feature.** "I'd like X" is not
|
||||
enough to discuss. "I'm doing Y, I need X, because Z" is.
|
||||
|
||||
### `install/`
|
||||
## Sending a change
|
||||
|
||||
- Mac/Linux 走 `install.sh`，Windows 走 `install.ps1`
|
||||
- 全部走 npmmirror.com 镜像，不能假设用户能访问 GitHub/npm 官方
|
||||
- 安装目录固定为 `~/.uclaw/`（Mac/Linux）或 `%USERPROFILE%\.uclaw\`（Windows）
|
||||
- 启动脚本要找空闲端口（18789-18799），不要写死
|
||||
Before you write it:
|
||||
|
||||
### `skills/`
|
||||
- **Does anyone need this?** For anything large, open an issue first.
|
||||
- **Does it break another form?** A change in `portable/` should not affect
|
||||
`bootable/`.
|
||||
- **Did you run it?** Not just the tests — the actual thing.
|
||||
|
||||
- 技能格式是 `<skill-name>/SKILL.md`，frontmatter 里有 `name`、`description`、`metadata`
|
||||
- 技能内容用中文写，给中国用户看
|
||||
- 提交新技能前先看现有技能（小红书/微博/B 站等）的写法
|
||||
Do not:
|
||||
|
||||
## 行为准则
|
||||
- Commit `node_modules/`, `app/`, `data/`, `*.dmg`, `*.exe` — all in `.gitignore`
|
||||
- Put an API key, token or password in any file
|
||||
- Reformat unrelated code ("ran prettier over everything" makes review impossible)
|
||||
- Open a PR with a title and no description
|
||||
|
||||
简单说：
|
||||
Commit messages: say what changed and why, in a sentence someone can act on.
|
||||
|
||||
- 对人有礼貌，对事可以严格
|
||||
- 不要在 issue 里互相攻击
|
||||
- 维护者可能回复慢（这是开源副业），请耐心
|
||||
- 不接受任何形式的歧视、骚扰、钓鱼
|
||||
```
|
||||
fix(install.sh): npm wrapper cannot be run through node directly
|
||||
feat(skills): add linkedin-post
|
||||
docs: note Windows 11 ARM64 support
|
||||
```
|
||||
|
||||
## 联系
|
||||
Not `update`, `fix`, or `changed some files`.
|
||||
|
||||
- Issue 区：日常问题、bug、需求
|
||||
- 官网：[u-claw.org](https://u-claw.org)
|
||||
- 邮件（仅紧急安全问题）：见 README
|
||||
```bash
|
||||
git switch -c fix/something # never work on main
|
||||
git add <specific files> # not git add .
|
||||
git push -u origin fix/something
|
||||
```
|
||||
|
||||
---
|
||||
## Notes per form
|
||||
|
||||
再次感谢！🦞
|
||||
**`portable/`**
|
||||
- Never commit `app/` or `data/` — `setup.sh` produces them
|
||||
- `.command` files need the executable bit and LF endings
|
||||
- `.bat` files must be pure ASCII with CRLF, and must not contain an unescaped
|
||||
`)` inside an `IF (...)` block — that closes the block early and the window
|
||||
flash-exits. There is a test for it, and it has caught real regressions.
|
||||
- User config lives in `data/.openclaw/openclaw.json`. That file being on the
|
||||
drive is the entire portability story; do not move it.
|
||||
- User-facing text belongs in `lib/messages/*.json`, never in a script
|
||||
|
||||
**`bootable/`**
|
||||
- The four PowerShell scripts must run **in order**
|
||||
- Fully self-contained: it references nothing from `portable/` on purpose
|
||||
|
||||
**`install/`**
|
||||
- These run through `curl | bash` with **no checkout**, so they cannot read
|
||||
`origin.json` and carry URLs as literals. `tests/origin.test.mjs` fails if
|
||||
those literals drift from `origin.json` — that is what stops a host migration
|
||||
from half-happening.
|
||||
- Neither script may contain skill text. Both call `lib/install-skills.mjs`.
|
||||
|
||||
**`u-claw-app/`** — deprecated 2026-06-19, kept for archive. Do not add to it.
|
||||
|
||||
Reference in New Issue
Block a user