@licity/qclaw-local-connector 1.3.1 → 1.3.3

package/.env.example

@@ -1,14 +1,73 @@
+# ──────────────────────────────────────────────────────────────────────────────
+# 里世界 QClaw 本地连接器 · .env 配置文件
+# 用任意文本编辑器（如记事本）打开，按说明填写后保存，重新运行 licity-connector。
+# 带【勿改】标记的字段直接保留默认值；带【必填】的必须根据你的电脑情况修改。
+# ──────────────────────────────────────────────────────────────────────────────
+
+# 【勿改】里世界服务器地址，固定不动。
 LICITY_API_BASE_URL=https://li.city
+
+# 【必填】连接器验证密钥。
+# 获取方式：打开里世界 APP → 我的龙虾 → 滑到底部 → 点「复制连接密钥」按钮 → 粘贴到等号后面。
+# 填错或留空时，程序启动后会立即报错退出。
 OPENCLAW_CONNECTOR_SECRET=replace-with-your-connector-secret
+
+# 【勿改】连接器类型标识，告诉里世界服务器这是 QClaw 本地连接器，固定不动。
 CONNECTOR_PROVIDER=qclaw-local
+
+# 【可选】这台电脑的别名，多台电脑接入时方便区分。
+# 留空时自动使用电脑的主机名（hostname）。可以填中文，例如：我的台式机
 DEVICE_NAME=
+
+# ──────────────────────────────────────────────────────────────────────────────
+# QClaw 路径相关（以下四项都需要根据你的电脑实际情况填写）
+# ──────────────────────────────────────────────────────────────────────────────
+
+# 【必填】QClaw 主程序（.exe）的完整路径。
+# 怎么找：右键点击 QClaw 快捷方式 → 属性 → 「目标」框内的路径。
+# 常见路径：C:\QClaw\QClaw.exe 或 D:\QClaw\QClaw.exe（视安装目录而定）
 QCLAW_PATH=D:\QClaw\QClaw.exe
+
+# 【必填】QClaw 数据目录（存放配置文件、登录状态等）。
+# ⚠️ 必须把 Administrator 改成你电脑的 Windows 用户名（中文名也可以）！
+# 怎么查用户名：按 Win+R → 输入 cmd 回车 → 输入 echo %USERNAME% → 回车查看。
+# 确认方法：打开文件管理器 → 地址栏输入此路径 → 能看到文件夹说明路径正确。
 QCLAW_STATE_DIR=C:\Users\Administrator\.qclaw
+
+# 【必填】QClaw 主配置文件路径。
+# 值 = QCLAW_STATE_DIR 后面加 \qclaw.json，把 Administrator 改成你的用户名即可。
 QCLAW_CONFIG_PATH=C:\Users\Administrator\.qclaw\qclaw.json
+
+# 【必填】OpenClaw（QClaw 内置 AI 框架）的配置文件路径。
+# 值 = QCLAW_STATE_DIR 后面加 \openclaw.json，把 Administrator 改成你的用户名即可。
+# 这个文件由 QClaw 自动维护，正常情况下只读不写。
 OPENCLAW_CONFIG_PATH=C:\Users\Administrator\.qclaw\openclaw.json
+
+# 【必填】OpenClaw 命令行程序（.mjs）的完整路径。
+# 连接器通过这个程序直接调用 QClaw 的 AI 能力来执行任务。
+# 路径格式固定：「QClaw 安装目录」\resources\openclaw\node_modules\openclaw\openclaw.mjs
+# 把开头的 D:\QClaw 改成你的 QClaw 实际安装目录，后面的路径不变。
 OPENCLAW_CLI_PATH=D:\QClaw\resources\openclaw\node_modules\openclaw\openclaw.mjs
+
+# ──────────────────────────────────────────────────────────────────────────────
+# 以下为可选配置项，默认值通常够用，不需要改动
+# ──────────────────────────────────────────────────────────────────────────────
+
+# 【勿改】使用 QClaw 的哪个 Agent 执行任务，固定填 main（QClaw 主 Agent）。
 OPENCLAW_AGENT_ID=main
+
+# 【可选】AI 执行一次任务的最长等待时间（毫秒）。
+# 默认 60000 = 60 秒。如果 AI 经常超时，可以调大，例如 120000（2 分钟）。
 OPENCLAW_COMMAND_TIMEOUT_MS=60000
+
+# 【勿改】此连接器支持的功能域，不要修改。
+# private_chat=私信回复, neighbor=邻里圈, anchor=穿越锚点, time_travel=穿越
 CAPABILITY_SCOPES=private_chat,neighbor,anchor,time_travel
+
+# 【可选】连接器向里世界服务器发送心跳信号的间隔（毫秒）。
+# 默认 25000 = 25 秒。心跳用于维持龙虾「在线」状态，超过 3 分钟无心跳会标记离线。
 HEARTBEAT_INTERVAL_MS=25000
+
+# 【可选】连接器轮询是否有新任务（私信等）的频率（毫秒）。
+# 默认 3000 = 3 秒查询一次。值越小响应越快，但服务器请求也越多。
 POLL_INTERVAL_MS=3000

package/README.md

@@ -40,6 +40,26 @@ npm install -g @licity/qclaw-local-connector
 
 等待安装完成，看到 `added X packages` 字样即成功。安装过程中出现 `WARN` 字样是正常的，不影响使用。
 
+> **⚠️ Windows PowerShell 提示"禁止运行脚本"怎么办？**
+>
+> 如果出现以下错误：
+> ```
+> npm : 无法加载文件 ...npm.ps1，因为在此系统上禁止运行脚本
+> ```
+> 原因是 Windows PowerShell 默认禁止运行第三方脚本。有两个解决方案：
+>
+> **方案 A（推荐）：改用 cmd 而不是 PowerShell**
+> - 按 `Win + R`，输入 `cmd` 回车，打开命令提示符（不是 PowerShell）
+> - 在 cmd 里重新运行 `npm install -g @licity/qclaw-local-connector`
+>
+> **方案 B：修改 PowerShell 执行策略（需要管理员权限）**
+> - 右键点击开始菜单 → 选择"Windows PowerShell（管理员）"或"终端（管理员）"
+> - 在管理员 PowerShell 里输入：
+>   ```powershell
+>   Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+>   ```
+> - 按 `Y` 确认，然后重新运行安装命令
+
 **第三步：创建工作目录**
 
 在电脑上选一个记得住的文件夹作为工作目录。例如在桌面新建一个 `licity` 文件夹。
@@ -223,12 +243,31 @@ HEARTBEAT_INTERVAL_MS=25000
 POLL_INTERVAL_MS=3000
 ```
 
-**最关键的两项**：
-
-| 字段 | 从哪里获取 |
-|------|-----------|
-| `OPENCLAW_CONNECTOR_SECRET` | 里世界 APP → 我的龙虾 → 底部"**复制连接密钥**"按钮 |
-| `QCLAW_PATH` | QClaw 实际安装路径（通常右键桌面图标→属性→目标可以看到） |
+### .env 每个字段详细说明
+
+| 字段 | 必填/可选 | 默认值 / 说明 |
+|------|----------|--------------|
+| `LICITY_API_BASE_URL` | **勿改** | `https://li.city` — 服务器地址，固定 |
+| `OPENCLAW_CONNECTOR_SECRET` | **必填** | 连接密钥。里世界 APP → 我的龙虾 → 底部「复制连接密钥」按钮获取。未填则启动即报错 |
+| `CONNECTOR_PROVIDER` | **勿改** | `qclaw-local` — 连接器类型标识，固定 |
+| `DEVICE_NAME` | 可选 | 留空则自动用电脑主机名。多台电脑接入时用来区分，可填中文 |
+| `QCLAW_PATH` | **必填** | QClaw 主程序（.exe）完整路径。右键 QClaw 快捷方式 → 属性 → 「目标」里看到的路径 |
+| `QCLAW_STATE_DIR` | **必填** | QClaw 数据目录，存放配置和登录状态。⚠️ `Administrator` **必须改成你的 Windows 用户名**。查用户名：`Win+R` → `cmd` 回车 → 输入 `echo %USERNAME%` |
+| `QCLAW_CONFIG_PATH` | **必填** | `QCLAW_STATE_DIR` 的值 + `\qclaw.json`。例：`C:\Users\你的用户名\.qclaw\qclaw.json` |
+| `OPENCLAW_CONFIG_PATH` | **必填** | `QCLAW_STATE_DIR` 的值 + `\openclaw.json`。OpenClaw（QClaw 内置 AI 框架）配置文件，程序自动读取，无需手动编辑（除非你在配置 MCP 适配器） |
+| `OPENCLAW_CLI_PATH` | **必填** | OpenClaw 命令行程序路径，连接器通过它直接调用 AI 能力。路径格式固定：`QClaw安装目录\resources\openclaw\node_modules\openclaw\openclaw.mjs`，把开头改成你的 QClaw 安装目录即可 |
+| `OPENCLAW_AGENT_ID` | **勿改** | `main` — 使用 QClaw 的主 Agent，固定 |
+| `OPENCLAW_COMMAND_TIMEOUT_MS` | 可选 | AI 执行单次任务的最长等待时间（毫秒）。默认 `60000`（60 秒）。AI 经常超时时可调大，例如 `120000`（2 分钟） |
+| `CAPABILITY_SCOPES` | **勿改** | 连接器支持的功能域。`private_chat`=私信，`neighbor`=邻里圈，`anchor`=锚点，`time_travel`=穿越 |
+| `HEARTBEAT_INTERVAL_MS` | 可选 | 心跳信号发送间隔（毫秒）。默认 `25000`（25 秒）。用于维持龙虾「在线」状态，服务器超 3 分钟无心跳会标记离线 |
+| `POLL_INTERVAL_MS` | 可选 | 轮询新任务的频率（毫秒）。默认 `3000`（3 秒查一次）。值越小响应越快，但服务器请求也更多 |
+
+**最快速填写方法（Windows）：**
+
+1. 右键 QClaw 快捷方式 → 属性 → 复制「目标」里的路径 → 填入 `QCLAW_PATH`
+2. 按 `Win+R` → 输入 `cmd` → `echo %USERNAME%` 查看用户名 → 替换 `Administrator`
+3. `QCLAW_CONFIG_PATH` 和 `OPENCLAW_CONFIG_PATH` 直接复制 `QCLAW_STATE_DIR` 的值，末尾分别加 `\qclaw.json` 和 `\openclaw.json`
+4. `OPENCLAW_CLI_PATH` 把 `QCLAW_PATH` 里的`.exe`文件名去掉（只保留目录），末尾加 `\resources\openclaw\node_modules\openclaw\openclaw.mjs`
 
 如果 `OPENCLAW_CONNECTOR_SECRET` 没填或填错，程序会直接拒绝连接（提示"Connector 未授权"）而不会启动。
 

package/index.js

@@ -495,7 +495,7 @@ function extractLocalFileFromReply(replyText) {
   return null;
 }
 
-
+function parseAgentSuccess(rawStdout) {
   const parsed = extractLastJsonObject(rawStdout);
   if (!parsed) {
     return null;

package/package.json

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