rol-websocket-channel 1.1.1 → 1.1.2

package/MQTT-API /351/205/215/345/257/271/344/277/256/346/224/271.md"

@@ -1655,4 +1655,80 @@ openclaw admin-bridge pair <key> --endpoint https://api.deotaland.ai
 
 ---
 
-```
+```
+```
+
+## Artifacts 文件下载（按需上传对象存储）
+
+如果文件之前已经上传过，则不会重复上传，而是直接复用已有 `fileUrl`。
+
+
+
+
+### 下载前先获取列表
+
+建议前端不要直接拿路径去调下载，而是先调用一次 `artifactsList`，确认当前可下载文件的 `artifactId`、`relativePath`、`storageStatus`。
+
+MQTT 请求示例：
+
+```json
+{
+  "type": "artifactsList",
+  "trace_id": "artifact-list-before-download-001",
+  "data": {}
+}
+```
+
+典型顺序：
+
+1. `artifactsList`
+2. 用户选择某个文件
+3. `artifactsEnsureUploaded`
+4. 使用返回的 `downloadUrl`
+
+
+
+### MQTT 请求示例
+
+```json
+{
+  "type": "artifactsEnsureUploaded",
+  "trace_id": "artifact-download-006",
+  "data": {
+    "baseUrl": "http://api.deotaland.local",
+    "authToken": "123",
+    "relativePath": "me.pdf",
+    "presignedPostBody": {
+      "dir": "artifacts/"
+    }
+  }
+}
+```
+
+### 成功返回示例
+
+```json
+{
+  "type": "receiver",
+  "trace_id": "artifact-download-006",
+  "source": "system",
+  "timestamp": 1777364603366,
+  "success": true,
+  "data": {
+    "ok": true,
+    "scope": "workspace",
+    "uploaded": true,
+    "artifactId": "art_fe4672f1badd",
+    "objectKey": "uploads/666ff786-9d01-4159-b4ae-338f385d6ae2.pdf",
+    "downloadUrl": "https://draft-user.s3.us-east-2.amazonaws.com/uploads/666ff786-9d01-4159-b4ae-338f385d6ae2.pdf"
+  }
+}
+```
+
+### 前端使用方式
+
+1. 调 `artifactsList` 获取文件列表
+2. 用户点击下载时，调 `artifactsEnsureUploaded`
+3. 直接使用返回的 `data.downloadUrl`
+4. 如果返回 `uploaded: false`，表示这次没有重新上传，而是复用了历史上传结果
+

package/message-handler.ts

@@ -7,6 +7,15 @@ import { getContext } from './src/shared/context.js';
 import { wrapAdminCall } from './src/shared/wrapper.js';
 import { getAgents, getConfig } from './src/admin/methods/admin.js';
 import { createAgent, deleteAgent, listAgents, updateAgent } from './src/admin/methods/agents-extended.js';
+import {
+  createArtifactRecord,
+  ensureArtifactUploaded,
+  getArtifactContent,
+  getArtifactPresignedPost,
+  listArtifacts,
+  markArtifactUploaded,
+  refreshArtifacts
+} from './src/admin/methods/artifacts.js';
 import {
   addCron,
   disableCron,
@@ -463,6 +472,55 @@ export class MessageHandler {
     });
   }
 
+  async artifactsList(data: any): Promise<any> {
+    return wrapAdminCall(async () => {
+      const context = getContext();
+      return await listArtifacts(data, context);
+    });
+  }
+
+  async artifactsRefresh(data: any): Promise<any> {
+    return wrapAdminCall(async () => {
+      const context = getContext();
+      return await refreshArtifacts(data, context);
+    });
+  }
+
+  async artifactsGetContent(data: any): Promise<any> {
+    return wrapAdminCall(async () => {
+      const context = getContext();
+      return await getArtifactContent(data, context);
+    });
+  }
+
+  async artifactsEnsureUploaded(data: any): Promise<any> {
+    return wrapAdminCall(async () => {
+      const context = getContext();
+      return await ensureArtifactUploaded(data, context);
+    });
+  }
+
+  async artifactsGetPresignedPost(data: any): Promise<any> {
+    return wrapAdminCall(async () => {
+      const context = getContext();
+      return await getArtifactPresignedPost(data, context);
+    });
+  }
+
+  async artifactsCreateRecord(data: any): Promise<any> {
+    return wrapAdminCall(async () => {
+      const context = getContext();
+      return await createArtifactRecord(data, context);
+    });
+  }
+
+  async artifactsMarkUploaded(data: any): Promise<any> {
+    return wrapAdminCall(async () => {
+      const context = getContext();
+      return await markArtifactUploaded(data, context);
+    });
+  }
+
   async mem9Install(_data: any): Promise<any> {
     return wrapAdminCall(async () => {
       const context = getContext();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rol-websocket-channel",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Unified OpenClaw plugin: MQTT Channel + Admin Bridge for remote management",
   "license": "MIT",
   "author": "nixgnehc",

package/src/admin/methods/artifacts.test.ts

@@ -0,0 +1,320 @@
+import { afterEach, describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  ensureArtifactUploaded,
+  listArtifacts,
+  markArtifactUploaded,
+  refreshArtifacts
+} from './artifacts.js';
+
+const tempDirs: string[] = [];
+const originalFetch = globalThis.fetch;
+
+afterEach(async () => {
+  globalThis.fetch = originalFetch;
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+describe('artifacts workspace scope', () => {
+  test('only indexes allowed artifact types inside workspace', async () => {
+    const context = await createMethodContext();
+    const workspaceRoot = path.join(context.openclawRoot, 'workspace');
+
+    await fs.writeFile(path.join(workspaceRoot, 'SOUL.md'), '# root noise\n', 'utf8');
+    await fs.mkdir(path.join(workspaceRoot, 'exports'), { recursive: true });
+    await fs.mkdir(path.join(workspaceRoot, 'logs'), { recursive: true });
+    await fs.mkdir(path.join(workspaceRoot, 'nested', 'media'), { recursive: true });
+
+    await fs.writeFile(
+      path.join(workspaceRoot, 'exports', 'preview.png'),
+      'png-data',
+      'utf8'
+    );
+    await fs.writeFile(
+      path.join(workspaceRoot, 'exports', 'report.pdf'),
+      'pdf-data',
+      'utf8'
+    );
+    await fs.writeFile(
+      path.join(workspaceRoot, 'nested', 'media', 'archive.zip'),
+      'zip-data',
+      'utf8'
+    );
+    await fs.writeFile(
+      path.join(workspaceRoot, 'nested', 'media', 'video.mp4'),
+      'mp4-data',
+      'utf8'
+    );
+    await fs.writeFile(
+      path.join(workspaceRoot, 'exports', 'spec.docx'),
+      'docx-data',
+      'utf8'
+    );
+    await fs.writeFile(
+      path.join(workspaceRoot, 'exports', 'ignored.md'),
+      '# markdown noise\n',
+      'utf8'
+    );
+    await fs.writeFile(
+      path.join(workspaceRoot, 'exports', 'ignored.json'),
+      '{"noise":true}\n',
+      'utf8'
+    );
+    await fs.writeFile(
+      path.join(workspaceRoot, 'logs', 'ignored.pdf'),
+      'log pdf noise',
+      'utf8'
+    );
+    await fs.writeFile(
+      path.join(workspaceRoot, 'artifacts.json'),
+      '[]',
+      'utf8'
+    );
+
+    const result = await refreshArtifacts({}, context) as {
+      scope: string;
+      count: number;
+      items: Array<{ relativePath: string; fileName: string }>;
+      manifestPath: string;
+      workspaceRoot: string;
+    };
+
+    assert.equal(result.scope, 'workspace');
+    assert.equal(result.count, 5);
+    assert.deepEqual(
+      result.items.map((item) => item.relativePath),
+      [
+        'nested/media/archive.zip',
+        'exports/preview.png',
+        'exports/report.pdf',
+        'exports/spec.docx',
+        'nested/media/video.mp4'
+      ]
+    );
+    assert.equal(result.workspaceRoot, workspaceRoot);
+    assert.equal(
+      result.manifestPath,
+      path.join(workspaceRoot, 'artifacts.json')
+    );
+  });
+
+  test('list reads workspace manifest without taskId', async () => {
+    const context = await createMethodContext();
+    const workspaceRoot = path.join(context.openclawRoot, 'workspace');
+
+    await fs.mkdir(path.join(workspaceRoot, 'exports'), { recursive: true });
+    await fs.writeFile(path.join(workspaceRoot, 'exports', 'me.pdf'), 'pdf-data', 'utf8');
+
+    const refreshed = await refreshArtifacts({}, context) as {
+      count: number;
+      items: Array<{ relativePath: string }>;
+    };
+    assert.equal(refreshed.count, 1);
+
+    const listed = await listArtifacts({ refresh: false }, context) as {
+      scope: string;
+      count: number;
+      items: Array<{ relativePath: string }>;
+      manifestPath: string;
+      workspaceRoot: string;
+    };
+
+    assert.equal(listed.scope, 'workspace');
+    assert.equal(listed.count, 1);
+    assert.deepEqual(listed.items.map((item) => item.relativePath), ['exports/me.pdf']);
+    assert.equal(listed.manifestPath, path.join(workspaceRoot, 'artifacts.json'));
+    assert.equal(listed.workspaceRoot, workspaceRoot);
+  });
+
+  test('ensureUploaded uploads local artifact and updates manifest', async () => {
+    const context = await createMethodContext();
+    const workspaceRoot = path.join(context.openclawRoot, 'workspace');
+    const artifactPath = path.join(workspaceRoot, 'exports', 'me.pdf');
+
+    await writeApiCoreBotConfig(context.openclawRoot, 'https://api.example.com');
+    await fs.mkdir(path.dirname(artifactPath), { recursive: true });
+    await fs.writeFile(artifactPath, 'pdf-data', 'utf8');
+
+    const refreshed = await refreshArtifacts({}, context) as {
+      items: Array<{ id: string; relativePath: string }>;
+    };
+    const artifactId = refreshed.items[0]?.id;
+    assert.ok(artifactId);
+
+    const calls: Array<{ url: string; method: string }> = [];
+    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = typeof input === 'string'
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+      const method = init?.method ?? (input instanceof Request ? input.method : 'GET');
+      calls.push({ url, method });
+
+      if (url === 'https://api.example.com/api-core-bot/front/s3/get-presigned-post') {
+        assert.equal(init?.body !== undefined, true);
+        const parsedBody = JSON.parse(String(init?.body)) as Record<string, unknown>;
+        assert.equal(parsedBody.dir, 'artifacts/');
+        assert.equal(parsedBody.filename, 'me.pdf');
+        assert.equal(parsedBody.file_name, undefined);
+        return new Response(JSON.stringify({
+          code: 0,
+          message: '',
+          success: true,
+          data: {
+            url: 'https://upload.example.com',
+            fields: {
+              key: 'artifacts/me.pdf',
+              policy: 'policy-token'
+            },
+            file_key: 'artifacts/me.pdf',
+            file_url: 'https://cdn.example.com/artifacts/me.pdf'
+          }
+        }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' }
+        });
+      }
+
+      if (url === 'https://upload.example.com') {
+        assert.ok(init?.body instanceof FormData);
+        return new Response(null, { status: 204 });
+      }
+
+      throw new Error(`Unexpected fetch call: ${url}`);
+    }) as typeof globalThis.fetch;
+
+    const ensured = await ensureArtifactUploaded({
+      artifactId,
+      presignedPostBody: {
+        dir: 'artifacts/'
+      }
+    }, context) as {
+      ok: boolean;
+      uploaded: boolean;
+      downloadUrl: string;
+      objectKey: string;
+      item: {
+        storageStatus: string;
+        fileUrl: string | null;
+        objectKey: string | null;
+      };
+    };
+
+    assert.equal(ensured.ok, true);
+    assert.equal(ensured.uploaded, true);
+    assert.equal(ensured.downloadUrl, 'https://cdn.example.com/artifacts/me.pdf');
+    assert.equal(ensured.objectKey, 'artifacts/me.pdf');
+    assert.equal(ensured.item.storageStatus, 'uploaded');
+    assert.equal(ensured.item.fileUrl, 'https://cdn.example.com/artifacts/me.pdf');
+    assert.equal(ensured.item.objectKey, 'artifacts/me.pdf');
+    assert.deepEqual(calls, [
+      {
+        url: 'https://api.example.com/api-core-bot/front/s3/get-presigned-post',
+        method: 'POST'
+      },
+      {
+        url: 'https://upload.example.com',
+        method: 'POST'
+      }
+    ]);
+
+    const listed = await listArtifacts({ refresh: false }, context) as {
+      items: Array<{
+        relativePath: string;
+        storageStatus: string;
+        fileUrl: string | null;
+        objectKey: string | null;
+      }>;
+    };
+    assert.equal(listed.items.length, 1);
+    assert.equal(listed.items[0]?.relativePath, 'exports/me.pdf');
+    assert.equal(listed.items[0]?.storageStatus, 'uploaded');
+    assert.equal(listed.items[0]?.fileUrl, 'https://cdn.example.com/artifacts/me.pdf');
+    assert.equal(listed.items[0]?.objectKey, 'artifacts/me.pdf');
+  });
+
+  test('ensureUploaded reuses existing uploaded artifact without fetching', async () => {
+    const context = await createMethodContext();
+    const workspaceRoot = path.join(context.openclawRoot, 'workspace');
+    const artifactPath = path.join(workspaceRoot, 'exports', 'me.pdf');
+
+    await fs.mkdir(path.dirname(artifactPath), { recursive: true });
+    await fs.writeFile(artifactPath, 'pdf-data', 'utf8');
+
+    const refreshed = await refreshArtifacts({}, context) as {
+      items: Array<{ id: string }>;
+    };
+    const artifactId = refreshed.items[0]?.id;
+    assert.ok(artifactId);
+
+    await markArtifactUploaded({
+      artifactId,
+      objectKey: 'artifacts/me.pdf',
+      fileUrl: 'https://cdn.example.com/artifacts/me.pdf'
+    }, context);
+
+    globalThis.fetch = (async () => {
+      throw new Error('fetch should not be called for existing uploaded artifact');
+    }) as typeof globalThis.fetch;
+
+    const ensured = await ensureArtifactUploaded({ artifactId }, context) as {
+      ok: boolean;
+      uploaded: boolean;
+      downloadUrl: string;
+      item: {
+        storageStatus: string;
+        fileUrl: string | null;
+      };
+    };
+
+    assert.equal(ensured.ok, true);
+    assert.equal(ensured.uploaded, false);
+    assert.equal(ensured.downloadUrl, 'https://cdn.example.com/artifacts/me.pdf');
+    assert.equal(ensured.item.storageStatus, 'uploaded');
+    assert.equal(ensured.item.fileUrl, 'https://cdn.example.com/artifacts/me.pdf');
+  });
+});
+
+async function createMethodContext(): Promise<{ projectRoot: string; openclawRoot: string }> {
+  const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), 'artifacts-task-scope-'));
+  tempDirs.push(rootDir);
+
+  const openclawRoot = path.join(rootDir, '.openclaw');
+  const workspaceRoot = path.join(openclawRoot, 'workspace');
+  await fs.mkdir(workspaceRoot, { recursive: true });
+
+  return {
+    projectRoot: rootDir,
+    openclawRoot
+  };
+}
+
+async function writeApiCoreBotConfig(openclawRoot: string, baseUrl: string): Promise<void> {
+  await fs.writeFile(
+    path.join(openclawRoot, 'openclaw.json'),
+    JSON.stringify({
+      plugins: {
+        entries: {
+          'rol-websocket-channel': {
+            config: {
+              apiCoreBot: {
+                baseUrl
+              }
+            }
+          }
+        }
+      }
+    }, null, 2),
+    'utf8'
+  );
+}