@licity/qclaw-local-connector 1.2.0 → 1.3.1

package/README.md

@@ -16,16 +16,50 @@
 
 ### 方式一：npm 全局安装（推荐）
 
+**第一步：安装 Node.js**
+
+没有 Node.js 的需要先安装它（npm 命令附带在 Node.js 里）。
+
+1. 打开浏览器，访问 [nodejs.org](https://nodejs.org)
+2. 点击显示"LTS"的大按钮下载安装包（Windows 下载 `.msi` 文件）
+3. 下载完成后双击运行，一直点"Next"直到安装完成，保持所有默认选项
+4. 安装完后打开终端（见下一步），输入 `node -v`，能看到版本号说明安装成功
+
+**如何打开终端：**
+- **Windows 11/10**：按 `Win + X`，选择"终端"或"PowerShell"；或按 `Win + R`，输入 `cmd` 回车
+- **macOS**：按 `Cmd + 空格`，搜索"Terminal"打开
+- **或者**：在文件夹空白处右键，选择"在此处打开终端"/"在终端中打开"
+
+**第二步：全局安装连接器**
+
+在终端里输入以下命令并回车：
+
 ```bash
 npm install -g @licity/qclaw-local-connector
 ```
 
-安装后，在任意目录创建 `.env` 配置文件（见第 4 步），然后执行：
+等待安装完成，看到 `added X packages` 字样即成功。安装过程中出现 `WARN` 字样是正常的，不影响使用。
+
+**第三步：创建工作目录**
+
+在电脑上选一个记得住的文件夹作为工作目录。例如在桌面新建一个 `licity` 文件夹。
+
+> ⚠️ **重要**：不要在 npm 全局安装目录里直接运行（路径包含 `node_modules/@licity`）。请始终在你自己建的工作目录里运行。
+
+**第四步：初次运行，自动生成 `.env` 配置文件**
+
+在工作目录（例如桌面的 `licity` 文件夹）里右键 → 在此处打开终端，然后运行：
 
 ```bash
 licity-connector
 ```
 
+**如果是第一次运行且当前目录没有 `.env` 文件，连接器会自动在当前目录生成一个 `.env` 模板文件，然后退出并提示你填写。**
+
+用文本编辑器打开自动生成的 `.env` 文件，按第 4 步说明填写必填项，保存后重新运行 `licity-connector` 即可。
+
+不需要手动创建 `.env` 文件 — 第一次运行会帮你生成。
+
 ### 方式二：本地克隆 / 下载后运行
 
 进入连接器目录，执行：
@@ -142,29 +176,46 @@ npm install && npm run quickstart
 
 ### 第 4 步：第一次启动时补全 `.env`
 
-如果你是第一次运行，`npm run quickstart` 前，先打开本目录的 `.env` 文件。
+**方式一（npm 全局安装）用户：**
+
+不需要手动创建 `.env` 文件。第一次在工作目录运行 `licity-connector` 时，如果目录里没有 `.env`，程序会**自动生成**一份模板并退出，提示你填写。
 
-如果 `.env` 不存在，运行安装助手后会自动从 `.env.example` 生成一份。
+然后用记事本或任何文本编辑器打开生成的 `.env` 文件，按下面说明填写必填项，保存后重新运行 `licity-connector`。
 
-至少确认这些字段（路径按你的实际安装位置填写）：
+**方式二（本地克隆/下载）用户：**
+
+首次运行 `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 +223,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

@@ -449,7 +449,53 @@ function extractAgentMedia(result) {
   return null;
 }
 
-function parseAgentSuccess(rawStdout) {
+// 从 AI 回复文本中提取本地文件路径，当 agent 没有结构化附件输出时作为兜底
+function extractLocalFileFromReply(replyText) {
+  if (!replyText) return null;
+
+  // 匹配 Windows 绝对路径（含中文路径）和 Unix 绝对路径
+  const patterns = [
+    // Windows: C:\path\file.ext 或 C:/path/file.ext（包含中文字符和空格）
+    /[A-Za-z]:[\\\/][^\s`'"，。！？\]]{3,260}\.[a-zA-Z0-9]{1,10}/g,
+    // Unix: /Users/path/file.ext
+    /(?:\/(?:[^\s`'"，。！？\]]+\/)+[^\s`'"，。！？\]]+\.[a-zA-Z0-9]{1,10})/g,
+  ];
+
+  const candidates = [];
+  for (const pattern of patterns) {
+    const matches = replyText.matchAll(pattern);
+    for (const m of matches) {
+      // 去掉首尾的引号、反引号
+      const candidate = m[0].trim().replace(/^[`'"【]|[`'"】,，。！？]$/g, '');
+      if (candidate.length > 3) candidates.push(candidate);
+    }
+  }
+
+  // 按文件大小筛选：必须存在且 ≤ maxEmbeddedMediaBytes
+  for (const filePath of candidates) {
+    try {
+      if (!fs.existsSync(filePath)) continue;
+      const stat = fs.statSync(filePath);
+      if (stat.size === 0 || stat.size > maxEmbeddedMediaBytes) continue;
+      const fileName = path.basename(filePath);
+      const mimeType = guessMimeTypeFromPath(filePath);
+      const mediaType = normalizeMediaType(null, mimeType, fileName);
+      console.log(`[Task] 检测到本地文件，自动附加: ${fileName} (${Math.round(stat.size / 1024)}KB)`);
+      return {
+        media_base64: fs.readFileSync(filePath).toString('base64'),
+        media_type: mediaType,
+        media_mime_type: mimeType,
+        media_name: fileName,
+      };
+    } catch (_) {
+      // 忽略单个文件处理错误，继续检查下一个
+    }
+  }
+
+  return null;
+}
+
+
   const parsed = extractLastJsonObject(rawStdout);
   if (!parsed) {
     return null;
@@ -843,6 +889,11 @@ async function handleTask(task) {
             model: agentResult.raw?.result?.meta?.agentMeta?.model || null,
             action: 'openclaw_agent_reply',
           };
+          // 如果 agent 没有结构化附件，尝试从回复文本中提取本地文件路径
+          if (!agentResult.media && agentResult.reply) {
+            const detectedMedia = extractLocalFileFromReply(agentResult.reply);
+            if (detectedMedia) agentResult.media = detectedMedia;
+          }
           if (agentResult.media) {
             taskResult.mediaType = agentResult.media.media_type;
             taskResult.mediaName = agentResult.media.media_name;

package/package.json

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