From b0a9cb3f58902e23fee0a4cb336af3d0a420392e Mon Sep 17 00:00:00 2001 From: hfshfg <38004547@qq.com> Date: Fri, 1 May 2026 15:41:42 +0800 Subject: [PATCH] fix(install): npm-cli.js path + CONTRIBUTING/PR template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit install.sh: bundled Node 的 INSTALL_NPM 之前指向 bin/npm shell wrapper, 通过 \"node npm\" 调用会失败。改为 lib/node_modules/npm/bin/npm-cli.js, 并加 run_npm() 帮助函数区分系统 Node(用 npm 可执行)和 bundled Node。 install.ps1: 系统 Node 场景下 npm-cli.js 路径推导脆弱。改为按候选路径 依次试探,找不到则直接退到 npm.cmd。 新增 CONTRIBUTING.md + .github/PULL_REQUEST_TEMPLATE.md,规范 PR 流程, 减少空白/无说明 PR(对应 issue PR #36)。 Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/PULL_REQUEST_TEMPLATE.md | 51 ++++++++++ CONTRIBUTING.md | 164 +++++++++++++++++++++++++++++++ install/install.ps1 | 18 ++-- install/install.sh | 18 +++- 4 files changed, 241 insertions(+), 10 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..34ef575 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,51 @@ + + +## 改动类型 / Type + + + +- [ ] 🐛 Bug 修复 +- [ ] ✨ 新功能 +- [ ] 📝 文档/README +- [ ] 🔧 脚本/构建（portable, install, bootable, u-claw-app） +- [ ] 🎨 技能 (skills-cn) +- [ ] ♻️ 重构（不改变行为） +- [ ] 🧪 测试 + +## 改动了什么 / What + + + +## 为什么 / Why + + + +## 测试方式 / How to verify + + + +## 影响范围 / Scope + + + +- [ ] portable/ (便携 USB) +- [ ] u-claw-app/ (Electron 桌面) +- [ ] bootable/ (Linux 可启动 U 盘) +- [ ] install/ (一键安装脚本) +- [ ] skills-cn/ (中国本地化技能) +- [ ] 仅文档 + +## 自检 / Checklist + +- [ ] 我已经在本地实际跑过相关脚本/功能 +- [ ] 没有提交 `node_modules/`、`app/`、`data/` 等运行时产物 +- [ ] 没有把任何 API Key、Token 写进文件 +- [ ] commit message 能说清楚改了什么 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6ef795b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,164 @@ +# 贡献指南 / Contributing to U-Claw + +感谢有兴趣参与 U-Claw 开发！这份文档会告诉你怎么开始、怎么提 issue、怎么提 PR。 + +## TL;DR + +- **报 bug** → 用 [Bug 模板](.github/ISSUE_TEMPLATE/bug_report.md)，**贴完整报错**，不要只发截图 +- **提需求** → 用 [Feature 模板](.github/ISSUE_TEMPLATE/feature_request.md)，先说清楚使用场景 +- **写代码** → 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) | + +## 开发环境 + +```bash +# 1. Clone +git clone https://github.com/dongsheng123132/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 + +**至少包含这四样**： + +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-cn): 增加 douyin-script 技能 +``` + +不接受："update"、"fix"、"修改若干文件" 这种。 + +### 分支与 PR 流程 + +```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，填好模板 +``` + +## 修改各形态时的注意事项 + +### `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/` 与独立仓库 `dongsheng123132/u-claw-linux` 内容保持同步，改一边记得同步另一边 + +### `install/` + +- Mac/Linux 走 `install.sh`，Windows 走 `install.ps1` +- 全部走 npmmirror.com 镜像，不能假设用户能访问 GitHub/npm 官方 +- 安装目录固定为 `~/.uclaw/`（Mac/Linux）或 `%USERPROFILE%\.uclaw\`（Windows） +- 启动脚本要找空闲端口（18789-18799），不要写死 + +### `skills-cn/` + +- 技能格式是 `/SKILL.md`，frontmatter 里有 `name`、`description`、`metadata` +- 技能内容用中文写，给中国用户看 +- 提交新技能前先看现有技能（小红书/微博/B 站等）的写法 + +## 行为准则 + +简单说： + +- 对人有礼貌，对事可以严格 +- 不要在 issue 里互相攻击 +- 维护者可能回复慢（这是开源副业），请耐心 +- 不接受任何形式的歧视、骚扰、钓鱼 + +## 联系 + +- Issue 区：日常问题、bug、需求 +- 官网：[u-claw.org](https://u-claw.org) +- 邮件（仅紧急安全问题）：见 README + +--- + +再次感谢！🦞 diff --git a/install/install.ps1 b/install/install.ps1 index fb07cee..f16aac1 100644 --- a/install/install.ps1 +++ b/install/install.ps1 @@ -93,12 +93,18 @@ if ($sysNode) { if ($major -ge 20) { Write-Green " [OK] System Node.js $sysVer found, reusing" $INSTALL_NODE = "node" - $npmCmd = (Get-Command npm -ErrorAction SilentlyContinue).Source - $npmRoot = Split-Path (Split-Path $npmCmd) - $NPM_CLI = "$npmRoot\node_modules\npm\bin\npm-cli.js" - if (-not (Test-Path $NPM_CLI)) { - $npmPrefix = & node -e "console.log(process.execPath.replace(/[\\\/]node\.exe$/i,''))" 2>$null - $NPM_CLI = "$npmPrefix\node_modules\npm\bin\npm-cli.js" + # Resolve npm-cli.js next to node.exe; fall back to npm.cmd as a launcher. + $nodeExeDir = Split-Path $sysNode.Source -Parent + $candidates = @( + "$nodeExeDir\node_modules\npm\bin\npm-cli.js", + "$env:APPDATA\npm\node_modules\npm\bin\npm-cli.js", + "$env:ProgramFiles\nodejs\node_modules\npm\bin\npm-cli.js" + ) + $NPM_CLI = $null + foreach ($p in $candidates) { if (Test-Path $p) { $NPM_CLI = $p; break } } + if (-not $NPM_CLI) { + # Last resort: use npm.cmd directly (don't pass through node.exe) + $NPM_CLI = (Get-Command npm -ErrorAction SilentlyContinue).Source } $USE_SYSTEM_NODE = $true } diff --git a/install/install.sh b/install/install.sh index 7e250d6..0945df4 100755 --- a/install/install.sh +++ b/install/install.sh @@ -121,7 +121,7 @@ if [ "$USE_SYSTEM_NODE" = "false" ]; then if [ -f "$NODE_INSTALL_DIR/bin/node" ]; then echo -e " ${GREEN}✓${NC} Node.js 已存在，跳过下载" INSTALL_NODE="$NODE_INSTALL_DIR/bin/node" - INSTALL_NPM="$NODE_INSTALL_DIR/bin/npm" + INSTALL_NPM="$NODE_INSTALL_DIR/bin/npm-cli.js" else echo -e " ${CYAN}↓${NC} 从国内镜像下载 Node.js $NODE_VERSION ($PLATFORM)..." TARBALL="node-${NODE_VERSION}-${PLATFORM}.tar.gz" @@ -144,7 +144,7 @@ if [ "$USE_SYSTEM_NODE" = "false" ]; then if [ -f "$NODE_INSTALL_DIR/bin/node" ]; then echo -e " ${GREEN}✓${NC} Node.js 安装完成" INSTALL_NODE="$NODE_INSTALL_DIR/bin/node" - INSTALL_NPM="$NODE_INSTALL_DIR/bin/npm" + INSTALL_NPM="$NODE_INSTALL_DIR/lib/node_modules/npm/bin/npm-cli.js" else echo -e " ${RED}✗ Node.js 下载失败${NC}" exit 1 @@ -152,6 +152,16 @@ if [ "$USE_SYSTEM_NODE" = "false" ]; then fi fi +# Helper: invoke npm. For bundled Node we have npm-cli.js (run via node). +# For system Node, INSTALL_NPM is the npm shell wrapper (executable). +run_npm() { + if [ "$USE_SYSTEM_NODE" = "true" ]; then + "$INSTALL_NPM" "$@" + else + "$INSTALL_NODE" "$INSTALL_NPM" "$@" + fi +} + echo "" # ============================================================ @@ -176,7 +186,7 @@ PKGJSON fi echo -e " ${CYAN}↓${NC} 从国内镜像安装..." - "$INSTALL_NODE" "$INSTALL_NPM" install --prefix "$CORE_DIR" --registry="$MIRROR" 2>&1 | tail -5 + run_npm install --prefix "$CORE_DIR" --registry="$MIRROR" 2>&1 | tail -5 echo -e " ${GREEN}✓${NC} OpenClaw 安装完成" fi @@ -191,7 +201,7 @@ if [ -d "$CORE_DIR/node_modules/@sliverp/qqbot" ]; then echo -e " ${GREEN}✓${NC} QQ 插件已安装，跳过" else echo -e " ${CYAN}↓${NC} 安装 QQ 插件..." - "$INSTALL_NODE" "$INSTALL_NPM" install @sliverp/qqbot@latest --prefix "$CORE_DIR" --registry="$MIRROR" 2>/dev/null || { + run_npm install @sliverp/qqbot@latest --prefix "$CORE_DIR" --registry="$MIRROR" 2>/dev/null || { echo -e " ${YELLOW}⚠${NC} QQ 插件安装失败（不影响主功能）" } if [ -d "$CORE_DIR/node_modules/@sliverp/qqbot" ]; then