fix(install): npm-cli.js path + CONTRIBUTING/PR template

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) <noreply@anthropic.com>
2026-05-01 15:41:42 +08:00
parent b6ba958b79
commit b0a9cb3f58
4 changed files with 241 additions and 10 deletions
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,51 @@
+<!--
+感谢贡献 U-Claw！请按以下模板填写，方便维护者审阅。
+空白或仅有标题的 PR 通常会被关闭，请勿提交无说明的改动。
+-->
+
+## 改动类型 / Type
+
+<!-- 勾选适用的（[x]） -->
+
+- [ ] 🐛 Bug 修复
+- [ ] ✨ 新功能
+- [ ] 📝 文档/README
+- [ ] 🔧 脚本/构建（portable, install, bootable, u-claw-app）
+- [ ] 🎨 技能 (skills-cn)
+- [ ] ♻️ 重构（不改变行为）
+- [ ] 🧪 测试
+
+## 改动了什么 / What
+
+<!-- 一两句话说清楚这个 PR 做了什么。不要复制 git diff。 -->
+
+## 为什么 / Why
+
+<!-- 哪个 issue / 哪个使用场景驱动了这次改动？关联 issue: #xxx -->
+
+## 测试方式 / How to verify
+
+<!--
+告诉维护者怎么验证。比如：
+- 在 macOS Apple Silicon 上跑 `bash install/install.sh`，安装成功
+- 双击 `portable/Mac-Start.command`，能正常打开 dashboard
+- Windows 11 PowerShell 跑 `irm https://u-claw.org/install.ps1 | iex`，安装成功
+-->
+
+## 影响范围 / Scope
+
+<!-- 勾选受影响的模块 -->
+
+- [ ] portable/ (便携 USB)
+- [ ] u-claw-app/ (Electron 桌面)
+- [ ] bootable/ (Linux 可启动 U 盘)
+- [ ] install/ (一键安装脚本)
+- [ ] skills-cn/ (中国本地化技能)
+- [ ] 仅文档
+
+## 自检 / Checklist
+
+- [ ] 我已经在本地实际跑过相关脚本/功能
+- [ ] 没有提交 `node_modules/`、`app/`、`data/` 等运行时产物
+- [ ] 没有把任何 API Key、Token 写进文件
+- [ ] commit message 能说清楚改了什么
--- a/CONTRIBUTING.md
+++ 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-name>/SKILL.md`，frontmatter 里有 `name`、`description`、`metadata`
+- 技能内容用中文写，给中国用户看
+- 提交新技能前先看现有技能（小红书/微博/B 站等）的写法
+
+## 行为准则
+
+简单说：
+
+- 对人有礼貌，对事可以严格
+- 不要在 issue 里互相攻击
+- 维护者可能回复慢（这是开源副业），请耐心
+- 不接受任何形式的歧视、骚扰、钓鱼
+
+## 联系
+
+- Issue 区：日常问题、bug、需求
+- 官网：[u-claw.org](https://u-claw.org)
+- 邮件（仅紧急安全问题）：见 README
+
+---
+
+再次感谢！🦞
--- 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
    }
--- 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