@licity/qclaw-local-connector 1.1.0 → 1.3.0

package/README.md

@@ -16,11 +16,31 @@
 
 ### 方式一：npm 全局安装（推荐）
 
+**第一步：安装前提**
+
+需要先安装 Node.js（访问 [nodejs.org](https://nodejs.org) 免费下载，安装完默认自带 npm 命令）。
+
+**第二步：全局安装连接器**
+
 ```bash
 npm install -g @licity/qclaw-local-connector
 ```
 
-安装后，在任意目录创建 `.env` 配置文件（见第 4 步），然后执行：
+看到 `added X packages` 即安装成功。
+
+**第三步：创建工作目录**
+
+在电脑上选一个记得住的文件夹作为工作目录，例如在桌面新建一个 `licity` 文件夹。
+
+> ⚠️ **重要**：不要在 npm 全局安装目录（`node_modules/@licity/qclaw-local-connector`）里直接运行。请始终在你自己建的工作目录里运行。
+
+**第四步：创建 `.env` 配置文件**
+
+在工作目录中创建名为 `.env` 的文本文件（见下方第 4 步的详细说明），填写必要字段。
+
+**第五步：启动连接器**
+
+在工作目录里右键"在此处打开终端"，然后执行：
 
 ```bash
 licity-connector
@@ -142,29 +162,38 @@ npm install && npm run quickstart
 
 ### 第 4 步：第一次启动时补全 `.env`
 
-如果你是第一次运行，`npm run quickstart` 前，先打开本目录的 `.env` 文件。
+在工作目录（你自己建的那个 `licity` 文件夹）里新建一个名为 `.env` 的文本文件（没有任何后缀）。
 
-如果 `.env` 不存在，运行安装助手后会自动从 `.env.example` 生成一份。
+> 如果你用的是"方式二"本地克隆，首次运行 `npm run quickstart` 会自动从 `.env.example` 生成一份 `.env` 模板，直接编辑那个就好。
 
-至少确认这些字段（路径按你的实际安装位置填写）：
+`.env` 文件的完整示例如下。复制粘贴后，按 **【必填/可选/勿改】** 说明逐行确认：
 
 ```env
+# 里世界服务器地址，勿改
 LICITY_API_BASE_URL=https://li.city
+
+# 【必填】连接器验证密钥
+# 获取方式：打开里世界 APP → 我的龙虾 → 滑到底部 → 点击"复制连接密钥"按钮
+# 将复制的内容粘贴到等号后面（替换掉 replace-with-your-connector-secret）
 OPENCLAW_CONNECTOR_SECRET=replace-with-your-connector-secret
+
+# 连接器类型，勿改
 CONNECTOR_PROVIDER=qclaw-local
 
-# Windows 示例（路径按实际安装位置填写）
+# 【必填】QClaw 主程序路径（按你的实际安装位置填写）
+# Windows 示例：
 QCLAW_PATH=C:\QClaw\QClaw.exe
-QCLAW_STATE_DIR=%USERPROFILE%\.qclaw
-OPENCLAW_CONFIG_PATH=%USERPROFILE%\.qclaw\openclaw.json
+QCLAW_STATE_DIR=C:\Users\你的用户名\.qclaw
+OPENCLAW_CONFIG_PATH=C:\Users\你的用户名\.qclaw\openclaw.json
 OPENCLAW_CLI_PATH=C:\QClaw\resources\openclaw\node_modules\openclaw\openclaw.mjs
 
-# macOS / Linux 示例
+# macOS / Linux 示例（把上面 Windows 路径注释掉，取消下面几行的注释）：
 # QCLAW_PATH=/Applications/QClaw.app/Contents/MacOS/QClaw
 # QCLAW_STATE_DIR=~/.qclaw
 # OPENCLAW_CONFIG_PATH=~/.qclaw/openclaw.json
 # OPENCLAW_CLI_PATH=~/.nvm/versions/node/v20/lib/node_modules/openclaw/openclaw.mjs
 
+# 以下为可选项，默认值已经够用，一般不需要改
 OPENCLAW_AGENT_ID=main
 OPENCLAW_COMMAND_TIMEOUT_MS=60000
 CAPABILITY_SCOPES=private_chat,neighbor,anchor,time_travel
@@ -172,13 +201,14 @@ HEARTBEAT_INTERVAL_MS=25000
 POLL_INTERVAL_MS=3000
 ```
 
-其中最关键的是：
+**最关键的两项**：
 
-- `OPENCLAW_CONNECTOR_SECRET`
-- `QCLAW_PATH`
-- `OPENCLAW_CONFIG_PATH`
+| 字段 | 从哪里获取 |
+|------|-----------|
+| `OPENCLAW_CONNECTOR_SECRET` | 里世界 APP → 我的龙虾 → 底部"**复制连接密钥**"按钮 |
+| `QCLAW_PATH` | QClaw 实际安装路径（通常右键桌面图标→属性→目标可以看到） |
 
-如果连接器密钥没填，程序会直接阻止启动。
+如果 `OPENCLAW_CONNECTOR_SECRET` 没填或填错，程序会直接拒绝连接（提示"Connector 未授权"）而不会启动。
 
 ### 第 5 步：扫码连接到里世界 APP
 

package/index.js

@@ -12,6 +12,7 @@ const qrcode = require('qrcode-terminal');
 // 优先从运行目录加载 .env（全局安装时从 CWD），否则从安装包目录加载
 const envFromCwd = path.join(process.cwd(), '.env');
 const envFromPkg = path.join(__dirname, '.env');
+const envExamplePath = path.join(__dirname, '.env.example');
 require('dotenv').config({ path: fs.existsSync(envFromCwd) ? envFromCwd : envFromPkg });
 
 const pkg = require('./package.json');
@@ -39,7 +40,36 @@ const capabilityScopes = String(process.env.CAPABILITY_SCOPES || 'private_chat,n
 const execFileAsync = promisify(execFile);
 
 if (!connectorKey) {
-  console.error('缺少 OPENCLAW_CONNECTOR_SECRET，无法启动本地 Connector。');
+  // 当工作目录没有 .env 时，自动生成模板并引导用户
+  if (!fs.existsSync(envFromCwd)) {
+    const templateDest = path.join(process.cwd(), '.env');
+    const templateContent = fs.existsSync(envExamplePath)
+      ? fs.readFileSync(envExamplePath, 'utf8')
+      : [
+          'LICITY_API_BASE_URL=https://li.city',
+          'OPENCLAW_CONNECTOR_SECRET=',
+          'QCLAW_PATH=C:\\QClaw\\QClaw.exe',
+          `QCLAW_STATE_DIR=${path.join(os.homedir(), '.qclaw')}`,
+          `OPENCLAW_CONFIG_PATH=${path.join(os.homedir(), '.qclaw', 'openclaw.json')}`,
+        ].join('\n') + '\n';
+    fs.writeFileSync(templateDest, templateContent, 'utf8');
+    console.error('');
+    console.error('══════════════════════════════════════════════════════');
+    console.error('  首次运行：已在当前目录生成 .env 配置文件模板');
+    console.error(`  文件位置：${templateDest}`);
+    console.error('');
+    console.error('  请用文本编辑器打开 .env，填写以下必填项：');
+    console.error('    OPENCLAW_CONNECTOR_SECRET  — 从里世界 APP「我的龙虾」页');
+    console.error('                                  复制「连接密钥」后粘贴到这里');
+    console.error('    QCLAW_PATH                 — QClaw 主程序实际路径');
+    console.error('    QCLAW_STATE_DIR            — QClaw 数据目录（含用户名）');
+    console.error('');
+    console.error('  填写完毕后在同一目录重新运行：licity-connector');
+    console.error('══════════════════════════════════════════════════════');
+    console.error('');
+  } else {
+    console.error('缺少 OPENCLAW_CONNECTOR_SECRET，请在当前目录的 .env 文件中填写连接密钥。');
+  }
   process.exit(1);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@licity/qclaw-local-connector",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "里世界龙虾本地连接器 — 把 QClaw 或其他第三方本地 Runtime 接入里世界 APP",
   "main": "index.js",
   "bin": {