@workclaw/cli 1.0.313 → 1.0.315

package/README.md

@@ -2,80 +2,232 @@
 
 WorkClaw CLI 是一个用于初始化和配置 WorkClaw 插件的命令行工具。
 
-## 特性
+## ✨ 特性
 
 - 🚀 **快速初始化** - 一键安装 WorkClaw 插件
 - 🔐 **安全认证** - RSA 加密密码，保护用户隐私
 - 🌐 **多平台支持** - Windows, macOS, Linux
 - 📊 **详细日志** - 完整的请求/响应日志
 - 🎨 **友好界面** - 彩色输出和加载动画
+- 📦 **npm 安装** - 支持自定义安装路径
+- 🔧 **灵活配置** - 支持自定义 OpenClaw 安装目录
 
-## 安装
+## 📋 前置要求
 
-```bash
-npm install -g @workclaw/cli
-```
+- **Node.js**: >= 20.0.0
+- **包管理器**: npm / pnpm / yarn（推荐 pnpm）
 
-## 快速开始
+## 🚀 快速开始
 
-### 本地账户安装
+### 使用 npx（推荐，无需安装）
 
 ```bash
-workclaw local
+# 本地账户安装
+npx @workclaw/cli local
+
+# 盒子设备安装
+npx @workclaw/cli box
+
+# 查看帮助
+npx @workclaw/cli --help
 ```
 
-### 盒子设备安装
+### 全局安装后使用
 
 ```bash
+# 全局安装
+npm install -g @workclaw/cli
+
+# 本地账户安装
+workclaw local
+
+# 盒子设备安装
 workclaw box
 ```
 
-## 使用文档
+## 📖 两种安装模式
+
+### local 命令 - 本地账户安装
+
+**适用场景**：个人电脑或需要用户登录的设备
+
+**特点**：
+- ✅ 需要用户登录（手机号 + 密码）
+- ✅ 自动获取 appKey 和 appSecret
+- ✅ 支持多账号管理
+- ✅ 自动创建和管理配置
+
+**安装流程**：
+1. 用户登录（RSA 加密密码）
+2. 获取绑定配置
+3. 通过手机号补全配置
+4. 下载并安装插件
+5. 更新配置文件
+
+### box 命令 - 盒子设备安装
+
+**适用场景**：专用设备或无需用户登录的环境
+
+**特点**：
+- ✅ 无需登录（直接使用 appKey + appSecret）
+- ✅ 适合批量部署
+- ✅ 配置文件默认设置为开放策略
+- ✅ 更快的安装速度
+
+**安装流程**：
+1. 清理旧版本插件
+2. 下载并安装插件
+3. 更新配置文件（`dmPolicy: "open"`）
+
+## 📖 使用文档
 
 ### 命令
 
 ```bash
-# 本地账户安装
-workclaw local [options]
+# 本地账户安装（需要登录）
+npx @workclaw/cli local [options]
 
-# 盒子设备安装
-workclaw box [options]
+# 盒子设备安装（无需登录）
+npx @workclaw/cli box [options]
 
-# 帮助
-workclaw --help
+# 查看帮助
+npx @workclaw/cli --help
 ```
 
 ### local 命令参数
 
-| 参数              | 必填 | 说明             |
-| --------------- | -- | -------------- |
-| --phone         | ❌  | 手机号码           |
-| --user-pass     | ❌  | 用户密码           |
-| --scenario      | ❌  | 安装场景           |
-| --env           | ❌  | 环境 (test/prod) |
-| --plugin-version | ❌  | 插件版本号（默认最新版） |
-| --debug         | ❌  | 开启调试日志         |
+| 参数               | 说明                                      |
+| --------------- | --------------------------------------- |
+| --phone         | 手机号码（登录账号），未填写时会交互式提示输入         |
+| --user-pass     | 用户密码，未填写时会交互式提示输入                 |
+| --env           | 环境 (test/prod)，默认 test，未填写时会交互式提示选择 |
+| --plugin-version | 插件版本号（默认安装最新版）                      |
+| --openclaw-path | OpenClaw 安装目录（默认 ~/.openclaw）         |
+| --debug         | 开启调试日志                               |
 
 ### box 命令参数
 
-| 参数              | 必填 | 说明             |
-| --------------- | -- | -------------- |
-| --app-key       | ❌  | App Key        |
-| --app-secret    | ❌  | App Secret     |
-| --env           | ❌  | 环境 (test/prod) |
-| --plugin-version | ❌  | 插件版本号（默认最新版） |
-| --debug         | ❌  | 开启调试日志         |
+| 参数               | 说明                                      |
+| --------------- | --------------------------------------- |
+| --app-key       | App Key，未填写时会交互式提示输入                  |
+| --app-secret    | App Secret，未填写时会交互式提示输入             |
+| --env           | 环境 (test/prod)，默认 test，未填写时会交互式提示选择 |
+| --plugin-version | 插件版本号（默认安装最新版）                      |
+| --openclaw-path | OpenClaw 安装目录（默认 ~/.openclaw）         |
+| --debug         | 开启调试日志                               |
 
-## 安装场景
+## 💡 使用示例
 
-| 场景            | 说明             |
-| ------------- | -------------- |
-| windows-local | Windows 本地安装   |
-| mac-local     | macOS 本地安装     |
-| linux-local   | Linux 本地安装     |
-| linux-box     | Linux Box 环境安装 |
+### 本地账户安装
+
+```bash
+# 交互式安装（会提示输入手机号和密码）
+npx @workclaw/cli local
+
+# 指定手机号和密码
+npx @workclaw/cli local --phone 18111657826 --user-pass yourpassword
+
+# 指定正式环境
+npx @workclaw/cli local --env prod --phone 18111657826 --user-pass yourpassword
+
+# 自定义安装路径
+npx @workclaw/cli local --openclaw-path "C:\CustomPath\OpenClaw" --phone 18111657826 --user-pass yourpassword
+
+# 开启调试模式
+npx @workclaw/cli local --debug --phone 18111657826 --user-pass yourpassword
+```
+
+### 盒子设备安装
+
+```bash
+# 交互式安装（会提示输入 AppKey 和 AppSecret）
+npx @workclaw/cli box
 
-## 开发
+# 指定参数
+npx @workclaw/cli box --app-key your-app-key --app-secret your-app-secret
+
+# 指定正式环境
+npx @workclaw/cli box --env prod --app-key your-app-key --app-secret your-app-secret
+
+# 自定义安装路径
+npx @workclaw/cli box --openclaw-path "/custom/path" --app-key your-app-key --app-secret your-app-secret
+
+# 开启调试模式
+npx @workclaw/cli box --debug --app-key your-app-key --app-secret your-app-secret
+```
+
+## 🔧 技术实现
+
+### 安装机制
+
+1. **插件下载**
+   - 使用 `npm pack` 从 npm 镜像源下载插件包
+   - 默认使用腾讯云 npm 镜像：`https://mirrors.tencent.com/npm/`
+   - 支持重试机制（最多 3 次）
+
+2. **文件解压**
+   - 使用 `tar.extract()` 解压到目标目录
+   - 自动创建必要的目录结构
+
+3. **依赖安装**
+   - 使用 `npm install --omit=dev` 安装生产依赖
+   - 自动跳过开发依赖，减小安装体积
+
+### 路径结构
+
+```
+~/.openclaw/                    # 或自定义路径
+├── openclaw.json              # 主配置文件
+├── extensions/
+│   └── openclaw-workclaw/     # 插件目录
+│       ├── package.json
+│       ├── dist/
+│       └── ...
+├── workspace/                 # 工作空间
+└── .temp/                    # 临时文件
+```
+
+### 路径验证
+
+工具会自动验证用户输入的 `--openclaw-path` 参数：
+- ✅ 必须是绝对路径
+- ✅ 不能包含非法字符：`< > : " | ? *`
+
+## ❓ 常见问题
+
+### Q: 安装失败，提示"网络错误"？
+
+**A**: 检查网络连接，可以尝试：
+- 使用代理或 VPN
+- 配置 npm 镜像源：`npm config set registry https://registry.npmmirror.com`
+
+### Q: 提示"路径必须是绝对路径"？
+
+**A**: `--openclaw-path` 需要使用绝对路径，例如：
+- Windows: `C:\OpenClaw` 或 `C:/OpenClaw`
+- Linux/macOS: `/opt/openclaw`
+
+### Q: 如何查看详细日志？
+
+**A**: 使用 `--debug` 参数：
+```bash
+npx @workclaw/cli local --debug --phone 18111657826 --user-pass yourpassword
+```
+
+### Q: 如何指定插件版本？
+
+**A**: 使用 `--plugin-version` 参数：
+```bash
+npx @workclaw/cli local --plugin-version 1.0.100 --phone 18111657826 --user-pass yourpassword
+```
+
+### Q: local 和 box 命令有什么区别？
+
+**A**: 
+- **local**: 需要用户登录，适合个人设备，支持多账号
+- **box**: 无需登录，直接使用 appKey+appSecret，适合专用设备
+
+## 🛠 开发
 
 ### 项目结构
 
@@ -83,12 +235,16 @@ workclaw --help
 packages/cli/
 ├── src/
 │   ├── bin/              # CLI 入口
-│   ├── lib/              # 核心库和基类
-│   ├── local/            # 本地账户命令
-│   ├── box/              # 盒子设备命令
-│   ├── command/          # 命令基类
+│   ├── local/            # 本地账户安装模块
+│   │   ├── installer/    # 安装器
+│   │   ├── apis/        # API 调用
+│   │   ├── types/       # 类型定义
+│   │   ├── error/       # 错误处理
+│   │   └── utils/       # 工具函数
+│   ├── box/              # 盒子设备安装模块
 │   ├── shared/           # 共享模块
 │   └── utils/            # 工具函数
+├── package.json
 ├── vite.config.ts
 └── README.md
 ```
@@ -96,25 +252,38 @@ packages/cli/
 ### 构建
 
 ```bash
-npm run build    # 构建
+# 安装依赖
+pnpm install
+
+# 构建项目
+pnpm build
+
+# 代码检查
+pnpm lint
+
+# 自动修复
+pnpm lint:fix
 ```
 
-## 更新日志
+## 📝 更新日志
 
-### v1.0.30 (2026-04-23)
+### v1.0.313 (2026-04-23)
+
+- ✨ 新增 `--openclaw-path` 参数 - 支持自定义安装路径
+- 🔧 新增路径验证功能 - 检查绝对路径和非法字符
+- ⚡ 优化安装流程 - 使用 npm pack + tar 替代 openclaw 命令
+- 🔒 移除 `--scenario` 参数 - 自动检测系统环境
+- 📦 更新 npm 镜像源 - 使用腾讯云 npm 镜像
+- 📝 完善文档和错误提示
+
+### v1.0.30 (2026-04-08)
 
 - ✨ 新增 local 命令 - 本地账户安装（需要登录）
 - ✨ 新增 box 命令 - 盒子设备安装（无需登录）
 - 🔧 重构命令结构，分离 local 和 box 命令
-
-### v2.0.0 (2026-04-08)
-
-- ✨ 新增 phone + userPass 认证方式
 - 🔒 新增 RSA 密码加密
 - 📝 新增完整请求日志
 - 🎨 优化交互式提示和进度显示
-- 🌐 支持 NPM 安装插件
-- 🔧 统一错误码管理
 
 ### v1.0.0
 
@@ -122,18 +291,18 @@ npm run build    # 构建
 - ✨ 支持 appKey + appSecret 认证
 - ✨ 支持多平台安装
 
-## 许可证
+## 📄 许可证
 
 MIT License
 
-## 联系方式
+## 📞 联系方式
 
-- 项目主页: [GitHub]()
-- 问题反馈: [Issue Tracker]()
+如有问题，请联系项目维护者。
 
-## 致谢
+## 🙏 致谢
 
 - [commander](https://github.com/tj/commander.js) - 命令行解析
 - [chalk](https://github.com/chalk/chalk) - 彩色输出
 - [ora](https://github.com/sindresorhus/ora) - 加载动画
 - [axios](https://github.com/axios/axios) - HTTP 客户端
+- [tar](https://github.com/isaacs/node-tar) - tar 文件解压

package/dist/box/installer/installer.d.ts

@@ -5,7 +5,6 @@ export declare class BoxInstaller {
     private prefixText;
     constructor(config: BoxInstallerConfig);
     validateConfig(): void;
-    private validateOpenclawPath;
     private getPaths;
     private updateSpinner;
     getPrefixText(): string;

package/dist/box/installer/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../../src/box/installer/installer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,UAAU,CAAA;AAqDhE,qBAAa,YAAY;IAIX,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,UAAU,CAAa;gBAEX,MAAM,EAAE,kBAAkB;IAI9C,cAAc,IAAI,IAAI;IAatB,OAAO,CAAC,oBAAoB;IAyB5B,OAAO,CAAC,QAAQ;IA2BhB,OAAO,CAAC,aAAa;IAMrB,aAAa,IAAI,MAAM;IAIvB,OAAO,CAAC,cAAc;IAOhB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YA0BhB,eAAe;YA0Bf,iBAAiB;YAoHjB,cAAc;CAiR7B"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../../src/box/installer/installer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,UAAU,CAAA;AAqDhE,qBAAa,YAAY;IAIX,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,UAAU,CAAa;gBAEX,MAAM,EAAE,kBAAkB;IAI9C,cAAc,IAAI,IAAI;IAatB,OAAO,CAAC,QAAQ;IAiChB,OAAO,CAAC,aAAa;IAMrB,aAAa,IAAI,MAAM;IAIvB,OAAO,CAAC,cAAc;IAOhB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YA0BhB,eAAe;YA0Bf,iBAAiB;YAoHjB,cAAc;CAiR7B"}

package/dist/{index-BZh3SXHn.js → index-CkTwizLH.js}

@@ -21,6 +21,19 @@ function debugLog(...args) {
     console.log(chalk.gray(`[DEBUG]`), ...args);
   }
 }
+function validateOpenclawPath(openclawPath) {
+  debugLog(`[路径验证] 开始验证路径: ${openclawPath}`);
+  if (!path.isAbsolute(openclawPath)) {
+    debugLog(`[路径验证] 失败: 路径不是绝对路径`);
+    throw new Error(`路径必须是绝对路径，当前输入: ${openclawPath}`);
+  }
+  const invalidChars = /[<>:"|?*]/.test(openclawPath);
+  if (invalidChars) {
+    debugLog(`[路径验证] 失败: 路径包含特殊字符`);
+    throw new Error('路径不能包含特殊字符: < > : " | ? *');
+  }
+  debugLog(`[路径验证] 通过: ${openclawPath}`);
+}
 const ERROR_CODES$1 = {
   APP_KEY_REQUIRED: "APP_KEY_REQUIRED",
   APP_SECRET_REQUIRED: "APP_SECRET_REQUIRED",
@@ -124,31 +137,17 @@ class BoxInstaller {
     }
     debugLog("[验证配置] 配置检查通过");
   }
-  validateOpenclawPath(openclawPath) {
-    debugLog(`[路径验证] 开始验证路径: ${openclawPath}`);
-    if (!path.isAbsolute(openclawPath)) {
-      debugLog("[路径验证] 失败: 不是绝对路径");
-      throw new AppError$1(
-        ERROR_CODES$1.INVALID_OPENCLAW_PATH,
-        `路径必须是绝对路径，当前输入: ${openclawPath}`
-      );
-    }
-    const invalidChars = /[<>:"|?*]/.test(openclawPath);
-    if (invalidChars) {
-      debugLog("[路径验证] 失败: 包含非法字符");
-      throw new AppError$1(
-        ERROR_CODES$1.INVALID_OPENCLAW_PATH,
-        '路径不能包含特殊字符: < > : " | ? *'
-      );
-    }
-    debugLog("[路径验证] 通过");
-  }
   getPaths() {
     const config = getConfig(this.config.env);
     let baseDir;
     if (this.config.openclawPath) {
       debugLog(`[路径验证] 验证自定义路径: ${this.config.openclawPath}`);
-      this.validateOpenclawPath(this.config.openclawPath);
+      try {
+        validateOpenclawPath(this.config.openclawPath);
+        debugLog("[路径验证] 通过");
+      } catch (error) {
+        throw new AppError$1(ERROR_CODES$1.INVALID_OPENCLAW_PATH, error.message);
+      }
       baseDir = this.config.openclawPath;
     } else {
       const home = getHomeDir$1();
@@ -4781,25 +4780,6 @@ class LocalInstaller {
     }
     debugLog("[验证配置] 配置验证通过");
   }
-  validateOpenclawPath(openclawPath) {
-    debugLog(`[路径验证] 开始验证路径: ${openclawPath}`);
-    if (!path.isAbsolute(openclawPath)) {
-      debugLog("[路径验证] 失败: 不是绝对路径");
-      throw new AppError2(
-        ERROR_CODES.INVALID_OPENCLAW_PATH,
-        `路径必须是绝对路径，当前输入: ${openclawPath}`
-      );
-    }
-    const invalidChars = /[<>:"|?*]/.test(openclawPath);
-    if (invalidChars) {
-      debugLog("[路径验证] 失败: 包含非法字符");
-      throw new AppError2(
-        ERROR_CODES.INVALID_OPENCLAW_PATH,
-        '路径不能包含特殊字符: < > : " | ? *'
-      );
-    }
-    debugLog("[路径验证] 通过");
-  }
   async install() {
     try {
       debugLog("[安装开始]");
@@ -4809,7 +4789,12 @@ class LocalInstaller {
       let baseDir;
       if (this.config.openclawPath) {
         debugLog(`[路径验证] 验证自定义路径: ${this.config.openclawPath}`);
-        this.validateOpenclawPath(this.config.openclawPath);
+        try {
+          validateOpenclawPath(this.config.openclawPath);
+          debugLog("[路径验证] 通过");
+        } catch (error) {
+          throw new AppError2(ERROR_CODES.INVALID_OPENCLAW_PATH, error.message);
+        }
         baseDir = this.config.openclawPath;
       } else {
         const homeDir = getHomeDir();

package/dist/index.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import("./index-BZh3SXHn.js").then((cli) => {
+import("./index-CkTwizLH.js").then((cli) => {
   cli.default();
 });

package/dist/local/installer/installer.d.ts

@@ -5,7 +5,6 @@ export declare class LocalInstaller {
     private prefixText;
     constructor(config: LocalInstallerConfig);
     validateConfig(): void;
-    private validateOpenclawPath;
     install(): Promise<void>;
     getPrefixText(): string;
     private getPackageName;

package/dist/local/installer/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../../src/local/installer/installer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA6B,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAuD/E,qBAAa,cAAc;IAIb,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,UAAU,CAAa;gBAEX,MAAM,EAAE,oBAAoB;IAIhD,cAAc,IAAI,IAAI;IAYtB,OAAO,CAAC,oBAAoB;IAyBtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA4C9B,aAAa,IAAI,MAAM;IAIvB,OAAO,CAAC,cAAc;YAOR,OAAO;YAoBP,kBAAkB;YAalB,eAAe;YAmBf,iBAAiB;YAmHjB,cAAc;CA+M7B"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../../src/local/installer/installer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA6B,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAuD/E,qBAAa,cAAc;IAIb,OAAO,CAAC,MAAM;IAH1B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,UAAU,CAAa;gBAEX,MAAM,EAAE,oBAAoB;IAIhD,cAAc,IAAI,IAAI;IAYhB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkD9B,aAAa,IAAI,MAAM;IAIvB,OAAO,CAAC,cAAc;YAOR,OAAO;YAoBP,kBAAkB;YAalB,eAAe;YAmBf,iBAAiB;YAmHjB,cAAc;CA+M7B"}

package/dist/shared/utils/index.d.ts

@@ -1,4 +1,5 @@
 export { debugLog, isDebugMode, setDebug } from './debug';
 export { createLogger, logger } from './logger';
 export type { Logger } from './logger';
+export { validateOpenclawPath } from './path';
 //# sourceMappingURL=index.d.ts.map

package/dist/shared/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAC/C,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAC/C,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAA"}

package/dist/shared/utils/path.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 验证 OpenClaw 安装路径
+ * @param openclawPath - 待验证的路径
+ * @throws Error - 如果路径无效，抛出包含错误信息的 Error
+ */
+export declare function validateOpenclawPath(openclawPath: string): void;
+//# sourceMappingURL=path.d.ts.map

package/dist/shared/utils/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/path.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAiB/D"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@workclaw/cli",
   "type": "module",
-  "version": "1.0.313",
+  "version": "1.0.315",
   "description": "WorkClaw CLI 工具 - 用于初始化和配置 WorkClaw 插件",
   "license": "MIT",
   "keywords": [