@licity/qclaw-local-connector 1.3.0 → 1.3.1

package/README.md

@@ -16,36 +16,50 @@
 
 ### 方式一：npm 全局安装（推荐）
 
-**第一步：安装前提**
+**第一步：安装 Node.js**
 
-需要先安装 Node.js（访问 [nodejs.org](https://nodejs.org) 免费下载，安装完默认自带 npm 命令）。
+没有 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
 ```
 
-看到 `added X packages` 即安装成功。
+等待安装完成，看到 `added X packages` 字样即成功。安装过程中出现 `WARN` 字样是正常的，不影响使用。
 
 **第三步：创建工作目录**
 
-在电脑上选一个记得住的文件夹作为工作目录，例如在桌面新建一个 `licity` 文件夹。
+在电脑上选一个记得住的文件夹作为工作目录。例如在桌面新建一个 `licity` 文件夹。
 
-> ⚠️ **重要**：不要在 npm 全局安装目录（`node_modules/@licity/qclaw-local-connector`）里直接运行。请始终在你自己建的工作目录里运行。
+> ⚠️ **重要**：不要在 npm 全局安装目录里直接运行（路径包含 `node_modules/@licity`）。请始终在你自己建的工作目录里运行。
 
-**第四步：创建 `.env` 配置文件**
+**第四步：初次运行，自动生成 `.env` 配置文件**
 
-在工作目录中创建名为 `.env` 的文本文件（见下方第 4 步的详细说明），填写必要字段。
-
-**第五步：启动连接器**
-
-在工作目录里右键"在此处打开终端"，然后执行：
+在工作目录（例如桌面的 `licity` 文件夹）里右键 → 在此处打开终端，然后运行：
 
 ```bash
 licity-connector
 ```
 
+**如果是第一次运行且当前目录没有 `.env` 文件，连接器会自动在当前目录生成一个 `.env` 模板文件，然后退出并提示你填写。**
+
+用文本编辑器打开自动生成的 `.env` 文件，按第 4 步说明填写必填项，保存后重新运行 `licity-connector` 即可。
+
+不需要手动创建 `.env` 文件 — 第一次运行会帮你生成。
+
 ### 方式二：本地克隆 / 下载后运行
 
 进入连接器目录，执行：
@@ -162,9 +176,17 @@ npm install && npm run quickstart
 
 ### 第 4 步：第一次启动时补全 `.env`
 
-在工作目录（你自己建的那个 `licity` 文件夹）里新建一个名为 `.env` 的文本文件（没有任何后缀）。
+**方式一（npm 全局安装）用户：**
+
+不需要手动创建 `.env` 文件。第一次在工作目录运行 `licity-connector` 时，如果目录里没有 `.env`，程序会**自动生成**一份模板并退出，提示你填写。
+
+然后用记事本或任何文本编辑器打开生成的 `.env` 文件，按下面说明填写必填项，保存后重新运行 `licity-connector`。
+
+**方式二（本地克隆/下载）用户：**
+
+首次运行 `npm run quickstart` 时，安装助手会自动从 `.env.example` 生成一份 `.env` 模板，直接编辑那个文件即可。
 
-> 如果你用的是"方式二"本地克隆，首次运行 `npm run quickstart` 会自动从 `.env.example` 生成一份 `.env` 模板，直接编辑那个就好。
+---
 
 `.env` 文件的完整示例如下。复制粘贴后，按 **【必填/可选/勿改】** 说明逐行确认：
 

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.3.0",
+  "version": "1.3.1",
   "description": "里世界龙虾本地连接器 — 把 QClaw 或其他第三方本地 Runtime 接入里世界 APP",
   "main": "index.js",
   "bin": {