@bomon/nestjs-cct-explorer 0.1.0

package/dist/cct-explorer.controller.d.ts

@@ -0,0 +1,24 @@
+import type { Response } from 'express';
+import { DeviceGateway } from './device-gateway.interface';
+import { CctExplorerModuleOptions } from './tokens';
+export declare class CctExplorerController {
+    private readonly gateway;
+    private readonly options;
+    constructor(gateway: DeviceGateway, options: CctExplorerModuleOptions);
+    renderBrowser(res: Response): Promise<void>;
+    getDevices(): Promise<{
+        devices: import("./device-gateway.interface").DeviceInfo[];
+    }>;
+    readDir(device: string, virtualPath?: string): Promise<{
+        entries: import("./device-gateway.interface").DirEntry[];
+    }>;
+    readFile(device: string, virtualPath: string | undefined, res: Response): Promise<void>;
+    deleteFile(device: string, virtualPath?: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    writeFile(device: string, virtualPath: string | undefined, content: string): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+}

package/dist/cct-explorer.controller.js

@@ -0,0 +1,161 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CctExplorerController = void 0;
+const common_1 = require("@nestjs/common");
+const node_path_1 = require("node:path");
+const tokens_1 = require("./tokens");
+const path_utils_1 = require("./path-utils");
+let CctExplorerController = class CctExplorerController {
+    constructor(gateway, options) {
+        this.gateway = gateway;
+        this.options = options;
+    }
+    async renderBrowser(res) {
+        const filePath = (0, node_path_1.join)(__dirname, 'public', 'browser.html');
+        res.sendFile(filePath);
+    }
+    async getDevices() {
+        const devices = await this.gateway.listDevices();
+        return { devices };
+    }
+    async readDir(device, virtualPath = '') {
+        if (!device || !virtualPath) {
+            throw new common_1.HttpException({ code: '400', message: '缺少 device 或 path' }, common_1.HttpStatus.BAD_REQUEST);
+        }
+        const parsed = (0, path_utils_1.parseVirtualPath)(device, virtualPath);
+        if ('error' in parsed) {
+            throw new common_1.HttpException({ code: String(parsed.code), message: parsed.error }, parsed.code);
+        }
+        const entries = await this.gateway.readDir(device, parsed.devicePath);
+        return { entries };
+    }
+    async readFile(device, virtualPath = '', res) {
+        if (!device || !virtualPath) {
+            throw new common_1.HttpException({ code: '400', message: '缺少 device 或 path' }, common_1.HttpStatus.BAD_REQUEST);
+        }
+        const parsed = (0, path_utils_1.parseVirtualPath)(device, virtualPath);
+        if ('error' in parsed) {
+            throw new common_1.HttpException({ code: String(parsed.code), message: parsed.error }, parsed.code);
+        }
+        let buf;
+        try {
+            buf = await this.gateway.readFile(device, parsed.devicePath);
+        }
+        catch (e) {
+            const err = e;
+            if (err?.message === 'file_not_found') {
+                throw new common_1.HttpException({ code: '404', message: '文件不存在' }, common_1.HttpStatus.NOT_FOUND);
+            }
+            throw new common_1.HttpException({ code: '500', message: err?.message || '读取文件失败' }, common_1.HttpStatus.INTERNAL_SERVER_ERROR);
+        }
+        const filename = virtualPath.split('/').pop() || 'file';
+        const ext = filename.substring(filename.lastIndexOf('.')).toLowerCase();
+        const mime = {
+            '.js': 'application/javascript',
+            '.mjs': 'application/javascript',
+            '.ts': 'application/typescript',
+            '.json': 'application/json',
+            '.html': 'text/html',
+            '.txt': 'text/plain',
+            '.png': 'image/png',
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.webp': 'image/webp',
+            '.gif': 'image/gif',
+        };
+        res.setHeader('Content-Type', mime[ext] || 'application/octet-stream');
+        res.setHeader('Content-Disposition', `inline; filename="${encodeURIComponent(filename)}"`);
+        res.send(buf);
+    }
+    async deleteFile(device, virtualPath = '') {
+        if (!device || !virtualPath) {
+            throw new common_1.HttpException({ code: '400', message: '缺少 device 或 path' }, common_1.HttpStatus.BAD_REQUEST);
+        }
+        const parsed = (0, path_utils_1.parseVirtualPath)(device, virtualPath);
+        if ('error' in parsed) {
+            throw new common_1.HttpException({ code: String(parsed.code), message: parsed.error }, parsed.code);
+        }
+        await this.gateway.removeFile(device, parsed.devicePath);
+        return { ok: true, message: 'deleted' };
+    }
+    async writeFile(device, virtualPath = '', content) {
+        if (!this.gateway.writeFile) {
+            throw new common_1.HttpException({ code: '400', message: '当前网关未实现写文件能力' }, common_1.HttpStatus.BAD_REQUEST);
+        }
+        if (!device || !virtualPath) {
+            throw new common_1.HttpException({ code: '400', message: '缺少 device 或 path' }, common_1.HttpStatus.BAD_REQUEST);
+        }
+        const parsed = (0, path_utils_1.parseVirtualPath)(device, virtualPath);
+        if ('error' in parsed) {
+            throw new common_1.HttpException({ code: String(parsed.code), message: parsed.error }, parsed.code);
+        }
+        await this.gateway.writeFile(device, parsed.devicePath, content ?? '');
+        return { ok: true, message: 'saved' };
+    }
+};
+exports.CctExplorerController = CctExplorerController;
+__decorate([
+    (0, common_1.Get)('browser'),
+    __param(0, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], CctExplorerController.prototype, "renderBrowser", null);
+__decorate([
+    (0, common_1.Get)('api/devices'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], CctExplorerController.prototype, "getDevices", null);
+__decorate([
+    (0, common_1.Get)('api/fs/dir'),
+    __param(0, (0, common_1.Query)('device')),
+    __param(1, (0, common_1.Query)('path')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], CctExplorerController.prototype, "readDir", null);
+__decorate([
+    (0, common_1.Get)('api/fs/file'),
+    __param(0, (0, common_1.Query)('device')),
+    __param(1, (0, common_1.Query)('path')),
+    __param(2, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, Object]),
+    __metadata("design:returntype", Promise)
+], CctExplorerController.prototype, "readFile", null);
+__decorate([
+    (0, common_1.Delete)('api/fs/file'),
+    __param(0, (0, common_1.Query)('device')),
+    __param(1, (0, common_1.Query)('path')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], CctExplorerController.prototype, "deleteFile", null);
+__decorate([
+    (0, common_1.Post)('api/fs/file'),
+    __param(0, (0, common_1.Body)('device')),
+    __param(1, (0, common_1.Body)('path')),
+    __param(2, (0, common_1.Body)('content')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object, String]),
+    __metadata("design:returntype", Promise)
+], CctExplorerController.prototype, "writeFile", null);
+exports.CctExplorerController = CctExplorerController = __decorate([
+    (0, common_1.Controller)(),
+    __param(0, (0, common_1.Inject)(tokens_1.DEVICE_GATEWAY_TOKEN)),
+    __param(1, (0, common_1.Inject)(tokens_1.CCT_EXPLORER_OPTIONS)),
+    __metadata("design:paramtypes", [Object, Object])
+], CctExplorerController);

package/dist/cct-explorer.module.d.ts

@@ -0,0 +1,5 @@
+import { DynamicModule } from '@nestjs/common';
+import { CctExplorerModuleOptions } from './tokens';
+export declare class CctExplorerModule {
+    static forRoot(options: CctExplorerModuleOptions): DynamicModule;
+}

package/dist/cct-explorer.module.js

@@ -0,0 +1,38 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var CctExplorerModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CctExplorerModule = void 0;
+const common_1 = require("@nestjs/common");
+const cct_explorer_controller_1 = require("./cct-explorer.controller");
+const tokens_1 = require("./tokens");
+let CctExplorerModule = CctExplorerModule_1 = class CctExplorerModule {
+    static forRoot(options) {
+        const { deviceGatewayClass, ...rest } = options;
+        return {
+            module: CctExplorerModule_1,
+            controllers: [cct_explorer_controller_1.CctExplorerController],
+            providers: [
+                {
+                    provide: tokens_1.CCT_EXPLORER_OPTIONS,
+                    useValue: rest,
+                },
+                deviceGatewayClass,
+                {
+                    provide: tokens_1.DEVICE_GATEWAY_TOKEN,
+                    useExisting: deviceGatewayClass,
+                },
+            ],
+            exports: [tokens_1.CCT_EXPLORER_OPTIONS, tokens_1.DEVICE_GATEWAY_TOKEN],
+        };
+    }
+};
+exports.CctExplorerModule = CctExplorerModule;
+exports.CctExplorerModule = CctExplorerModule = CctExplorerModule_1 = __decorate([
+    (0, common_1.Module)({})
+], CctExplorerModule);

package/dist/device-gateway.interface.d.ts

@@ -0,0 +1,15 @@
+export interface DeviceInfo {
+    name: string;
+    connectedAt?: string;
+}
+export interface DirEntry {
+    name: string;
+    type: 'file' | 'dir';
+}
+export interface DeviceGateway {
+    listDevices(): Promise<DeviceInfo[]>;
+    readDir(device: string, devicePath: string): Promise<DirEntry[]>;
+    readFile(device: string, devicePath: string): Promise<Buffer>;
+    removeFile(device: string, devicePath: string): Promise<void>;
+    writeFile?(device: string, devicePath: string, content: Buffer | string): Promise<void>;
+}

package/dist/device-gateway.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './device-gateway.interface';
+export * from './tokens';
+export * from './path-utils';
+export * from './cct-explorer.module';

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./device-gateway.interface"), exports);
+__exportStar(require("./tokens"), exports);
+__exportStar(require("./path-utils"), exports);
+__exportStar(require("./cct-explorer.module"), exports);

package/dist/path-utils.d.ts

@@ -0,0 +1,12 @@
+export declare const ALLOWED_PREFIXES: readonly ["local_scripts", "screenshots"];
+export interface ParseResult {
+    devicePath: string;
+}
+export interface ParseError {
+    error: string;
+    code: number;
+}
+/**
+ * 校验并解析虚拟路径：/{device}/local_scripts/xxx -> local_scripts/xxx
+ */
+export declare function parseVirtualPath(device: string, virtualPath: string): ParseResult | ParseError;

package/dist/path-utils.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_PREFIXES = void 0;
+exports.parseVirtualPath = parseVirtualPath;
+exports.ALLOWED_PREFIXES = ['local_scripts', 'screenshots'];
+/**
+ * 校验并解析虚拟路径：/{device}/local_scripts/xxx -> local_scripts/xxx
+ */
+function parseVirtualPath(device, virtualPath) {
+    const normalized = virtualPath.replace(/^\/+/, '').replace(/\\/g, '/');
+    const parts = normalized.split('/').filter(Boolean);
+    if (parts.length < 2 || parts[0] !== device) {
+        return {
+            error: 'path 须为 /{device_name}/local_scripts/... 或 /{device_name}/screenshots/...',
+            code: 400,
+        };
+    }
+    const second = parts[1];
+    if (!exports.ALLOWED_PREFIXES.includes(second)) {
+        return { error: '仅允许 local_scripts 或 screenshots 目录', code: 400 };
+    }
+    const devicePath = parts.slice(1).join('/');
+    return { devicePath };
+}

package/dist/public/browser.html

@@ -0,0 +1,806 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+
+<head>
+  <meta charset="UTF-8" />
+  <title>设备资源浏览器 - cdp-client-tool</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    :root {
+      color-scheme: dark light;
+      --bg: #0f172a;
+      --bg-elevated: #020617;
+      --bg-soft: #111827;
+      --border-subtle: #1f2937;
+      --accent: #38bdf8;
+      --accent-soft: rgba(56, 189, 248, 0.1);
+      --accent-strong: rgba(56, 189, 248, 0.2);
+      --text: #e5e7eb;
+      --text-muted: #9ca3af;
+      --danger: #f97373;
+      --danger-soft: rgba(248, 113, 113, 0.12);
+      --radius-lg: 10px;
+      --radius-md: 8px;
+      --radius-sm: 6px;
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      margin: 0;
+      padding: 0;
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Text",
+        "Segoe UI", Roboto, sans-serif;
+      background: radial-gradient(circle at top left, #1e293b 0, #020617 45%);
+      color: var(--text);
+      height: 100vh;
+      display: flex;
+      align-items: stretch;
+      justify-content: center;
+    }
+
+    .app-shell {
+      display: flex;
+      width: 100%;
+      max-width: 1320px;
+      margin: 16px;
+      border-radius: 18px;
+      overflow: hidden;
+      border: 1px solid rgba(148, 163, 184, 0.18);
+      background: radial-gradient(circle at top, #020617 0, #020617 40%, #020617 90%);
+      box-shadow:
+        0 22px 45px rgba(15, 23, 42, 0.9),
+        0 0 0 1px rgba(15, 23, 42, 0.9),
+        0 0 0 1px rgba(15, 23, 42, 0.9) inset;
+    }
+
+    .sidebar {
+      width: 260px;
+      border-right: 1px solid rgba(31, 41, 55, 0.9);
+      background: radial-gradient(circle at top left, #020617 0, #020617 55%, #020617 100%);
+      display: flex;
+      flex-direction: column;
+    }
+
+    .sidebar-header {
+      padding: 16px 18px 10px;
+      border-bottom: 1px solid rgba(31, 41, 55, 0.7);
+    }
+
+    .sidebar-title {
+      font-size: 14px;
+      font-weight: 600;
+      letter-spacing: 0.02em;
+      color: #e5e7eb;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .sidebar-title-badge {
+      font-size: 10px;
+      padding: 2px 7px;
+      border-radius: 999px;
+      border: 1px solid rgba(148, 163, 184, 0.45);
+      color: var(--text-muted);
+      text-transform: uppercase;
+    }
+
+    .sidebar-sub {
+      margin-top: 6px;
+      font-size: 12px;
+      color: var(--text-muted);
+    }
+
+    .devices-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 10px 16px 8px;
+      font-size: 11px;
+      color: var(--text-muted);
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+    }
+
+    .devices-refresh-btn {
+      border: none;
+      background: transparent;
+      color: var(--text-muted);
+      cursor: pointer;
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      font-size: 11px;
+      padding: 2px 4px;
+      border-radius: 999px;
+    }
+
+    .devices-refresh-btn:hover {
+      background: rgba(15, 23, 42, 0.9);
+      color: var(--text);
+    }
+
+    .device-list {
+      flex: 1;
+      overflow: auto;
+      padding: 4px 8px 10px;
+    }
+
+    .device-item {
+      display: flex;
+      align-items: center;
+      border-radius: 10px;
+      padding: 8px 10px;
+      cursor: pointer;
+      margin: 2px 0;
+      gap: 8px;
+      transition: background 0.15s ease, transform 0.08s ease, box-shadow 0.15s ease;
+    }
+
+    .device-item:hover {
+      background: rgba(15, 23, 42, 0.9);
+      transform: translateY(-0.5px);
+    }
+
+    .device-item.active {
+      background: linear-gradient(90deg, var(--accent-soft), rgba(15, 23, 42, 0.9));
+      box-shadow: 0 0 0 1px rgba(56, 189, 248, 0.3);
+    }
+
+    .device-dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 999px;
+      background: #22c55e;
+      box-shadow: 0 0 0 4px rgba(34, 197, 94, 0.15);
+    }
+
+    .device-name {
+      font-size: 13px;
+      font-weight: 500;
+    }
+
+    .device-meta {
+      font-size: 11px;
+      color: var(--text-muted);
+    }
+
+    .sidebar-footer {
+      padding: 8px 14px 12px;
+      border-top: 1px solid rgba(31, 41, 55, 0.9);
+      font-size: 11px;
+      color: var(--text-muted);
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .sidebar-footer span {
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .pill {
+      padding: 2px 8px;
+      border-radius: 999px;
+      border: 1px solid rgba(148, 163, 184, 0.55);
+      font-size: 10px;
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+    }
+
+    /* Main */
+    .main {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      background: radial-gradient(circle at top, #020617 0, #020617 45%, #020617 100%);
+    }
+
+    .main-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 14px 18px 10px;
+      border-bottom: 1px solid rgba(31, 41, 55, 0.7);
+    }
+
+    .breadcrumbs {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      font-size: 12px;
+      color: var(--text-muted);
+      flex-wrap: wrap;
+    }
+
+    .breadcrumb-part {
+      cursor: pointer;
+      padding: 2px 7px;
+      border-radius: 999px;
+      transition: background 0.15s ease, color 0.15s ease;
+    }
+
+    .breadcrumb-part:hover {
+      background: rgba(15, 23, 42, 0.9);
+      color: var(--text);
+    }
+
+    .breadcrumb-part.current {
+      background: var(--accent-soft);
+      color: var(--accent);
+    }
+
+    .breadcrumb-sep {
+      opacity: 0.4;
+    }
+
+    .main-actions {
+      display: flex;
+      gap: 8px;
+    }
+
+    .btn {
+      border-radius: 999px;
+      border: 1px solid rgba(148, 163, 184, 0.5);
+      background: #020617;
+      color: var(--text-muted);
+      font-size: 11px;
+      padding: 5px 10px;
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      cursor: pointer;
+    }
+
+    .btn-primary {
+      border-color: rgba(56, 189, 248, 0.7);
+      background: linear-gradient(90deg, rgba(56, 189, 248, 0.18), rgba(56, 189, 248, 0.06));
+      color: var(--accent);
+    }
+
+    .btn:hover {
+      background: rgba(15, 23, 42, 0.9);
+      color: var(--text);
+    }
+
+    .btn-primary:hover {
+      background: linear-gradient(90deg, rgba(56, 189, 248, 0.28), rgba(56, 189, 248, 0.12));
+    }
+
+    .main-body {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      padding: 10px 16px 14px;
+      gap: 10px;
+    }
+
+    .panel {
+      border-radius: var(--radius-lg);
+      border: 1px solid rgba(31, 41, 55, 0.9);
+      background: radial-gradient(circle at top, #020617 0, #020617 60%, #020617 100%);
+      padding: 10px 12px;
+      display: flex;
+      flex-direction: column;
+      min-height: 0;
+    }
+
+    .panel-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      margin-bottom: 6px;
+    }
+
+    .panel-title {
+      font-size: 12px;
+      color: var(--text-muted);
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+    }
+
+    .panel-sub {
+      font-size: 12px;
+      color: var(--text-muted);
+    }
+
+    .file-table-wrapper {
+      flex: 1;
+      overflow: auto;
+      border-radius: var(--radius-md);
+      border: 1px solid rgba(31, 41, 55, 0.95);
+      background: rgba(15, 23, 42, 0.96);
+    }
+
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 12px;
+    }
+
+    thead {
+      position: sticky;
+      top: 0;
+      background: rgba(15, 23, 42, 0.98);
+      z-index: 1;
+    }
+
+    th,
+    td {
+      padding: 7px 10px;
+      text-align: left;
+      border-bottom: 1px solid rgba(31, 41, 55, 0.9);
+    }
+
+    th {
+      font-size: 11px;
+      text-transform: uppercase;
+      letter-spacing: 0.06em;
+      color: var(--text-muted);
+    }
+
+    tbody tr {
+      cursor: default;
+      transition: background 0.12s ease;
+    }
+
+    tbody tr:hover {
+      background: rgba(17, 24, 39, 0.86);
+    }
+
+    .row-folder {
+      cursor: pointer;
+    }
+
+    .file-name-cell {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .file-icon {
+      width: 16px;
+      height: 16px;
+      border-radius: 4px;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 11px;
+    }
+
+    .file-icon.folder {
+      background: rgba(56, 189, 248, 0.12);
+      color: var(--accent);
+    }
+
+    .file-icon.file {
+      background: rgba(59, 130, 246, 0.18);
+      color: #93c5fd;
+    }
+
+    .file-icon.image {
+      background: rgba(16, 185, 129, 0.18);
+      color: #6ee7b7;
+    }
+
+    .file-icon.script {
+      background: rgba(251, 191, 36, 0.18);
+      color: #facc15;
+    }
+
+    .file-meta {
+      font-size: 11px;
+      color: var(--text-muted);
+    }
+
+    .file-actions {
+      display: flex;
+      gap: 6px;
+      justify-content: flex-end;
+    }
+
+    .link-icon {
+      border: none;
+      background: transparent;
+      color: var(--text-muted);
+      padding: 2px 4px;
+      cursor: pointer;
+      border-radius: 999px;
+      display: inline-flex;
+      align-items: center;
+      font-size: 11px;
+    }
+
+    .link-icon:hover {
+      background: rgba(15, 23, 42, 0.9);
+      color: var(--text);
+    }
+
+    .link-icon.danger:hover {
+      background: var(--danger-soft);
+      color: var(--danger);
+    }
+
+    .status-bar {
+      font-size: 11px;
+      color: var(--text-muted);
+      padding: 2px 2px 0;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .status-badge {
+      padding: 2px 8px;
+      border-radius: 999px;
+      background: rgba(15, 23, 42, 0.98);
+      border: 1px solid rgba(31, 41, 55, 0.9);
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+    }
+
+    .status-dot {
+      width: 6px;
+      height: 6px;
+      border-radius: 999px;
+      background: #22c55e;
+    }
+
+    .status-dot.warn {
+      background: #f97316;
+    }
+
+    .status-dot.err {
+      background: #ef4444;
+    }
+
+    .status-text {
+      max-width: 280px;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .badge-soft {
+      padding: 2px 6px;
+      border-radius: 999px;
+      background: rgba(15, 23, 42, 0.9);
+      border: 1px solid rgba(31, 41, 55, 0.9);
+    }
+
+    @media (max-width: 960px) {
+      .app-shell {
+        flex-direction: column;
+      }
+
+      .sidebar {
+        width: 100%;
+        border-right: none;
+        border-bottom: 1px solid rgba(31, 41, 55, 0.9);
+        max-height: 220px;
+      }
+    }
+  </style>
+</head>
+
+<body>
+  <div class="app-shell">
+    <aside class="sidebar">
+      <div class="sidebar-header">
+        <div class="sidebar-title">
+          设备资源浏览器
+          <span class="sidebar-title-badge">CDP CLIENT</span>
+        </div>
+        <div class="sidebar-sub">
+          通过 socket.io 网关浏览各设备脚本与截图
+        </div>
+      </div>
+
+      <div class="devices-header">
+        <span>Devices</span>
+        <button class="devices-refresh-btn" id="btn-refresh-devices">
+          ⟳ 刷新
+        </button>
+      </div>
+
+      <div class="device-list" id="device-list">
+        <!-- 动态插入设备列表 -->
+      </div>
+
+      <div class="sidebar-footer">
+        <span id="selected-device-label">未选择设备</span>
+        <span class="pill">SOCKET.IO</span>
+      </div>
+    </aside>
+
+    <main class="main">
+      <div class="main-header">
+        <div class="breadcrumbs" id="breadcrumbs">
+          <span style="font-size:12px;color:var(--text-muted)">请选择左侧设备</span>
+        </div>
+        <div class="main-actions">
+          <button class="btn" id="btn-root-local">local_scripts</button>
+          <button class="btn" id="btn-root-screenshots">screenshots</button>
+          <button class="btn-primary btn" id="btn-refresh-dir">刷新目录</button>
+        </div>
+      </div>
+
+      <div class="main-body">
+        <section class="panel" style="flex: 1 1 auto; min-height: 0;">
+          <div class="panel-header">
+            <div class="panel-title">当前目录</div>
+            <div class="panel-sub" id="panel-subtitle"></div>
+          </div>
+          <div class="file-table-wrapper">
+            <table>
+              <thead>
+                <tr>
+                  <th style="width: 40%;">名称</th>
+                  <th style="width: 20%;">类型</th>
+                  <th style="width: 20%;">所属设备</th>
+                  <th style="width: 20%; text-align: right;">操作</th>
+                </tr>
+              </thead>
+              <tbody id="file-tbody">
+                <!-- 动态插入行 -->
+              </tbody>
+            </table>
+          </div>
+        </section>
+
+        <div class="status-bar">
+          <div class="status-badge">
+            <span class="status-dot" id="status-dot"></span>
+            <span style="font-size:11px;">状态</span>
+            <span class="status-text" id="status-text">已加载界面，等待选择设备…</span>
+          </div>
+          <div style="display:flex;gap:6px;align-items:center;">
+            <span class="badge-soft">GET api/devices</span>
+            <span class="badge-soft">GET api/fs/dir</span>
+            <span class="badge-soft">GET api/fs/file</span>
+            <span class="badge-soft">DELETE api/fs/file</span>
+          </div>
+        </div>
+      </div>
+    </main>
+  </div>
+
+  <script>
+    (function () {
+      const deviceListEl = document.getElementById('device-list');
+      const selectedDeviceLabelEl = document.getElementById('selected-device-label');
+      const breadcrumbsEl = document.getElementById('breadcrumbs');
+      const fileTbodyEl = document.getElementById('file-tbody');
+      const panelSubtitleEl = document.getElementById('panel-subtitle');
+      const statusTextEl = document.getElementById('status-text');
+      const statusDotEl = document.getElementById('status-dot');
+
+      const btnRefreshDevices = document.getElementById('btn-refresh-devices');
+      const btnRootLocal = document.getElementById('btn-root-local');
+      const btnRootScreenshots = document.getElementById('btn-root-screenshots');
+      const btnRefreshDir = document.getElementById('btn-refresh-dir');
+
+      const state = {
+        devices: [],
+        currentDevice: null,
+        currentPath: null,
+      };
+
+      function setStatus(text, level) {
+        level = level || 'info';
+        statusTextEl.textContent = text;
+        statusDotEl.classList.remove('warn', 'err');
+        if (level === 'warn') statusDotEl.classList.add('warn');
+        else if (level === 'error') statusDotEl.classList.add('err');
+      }
+
+      function joinPath(base, name) {
+        if (!base.endsWith('/')) base += '/';
+        return base + name.replace(/^\/+/, '');
+      }
+
+      function buildFileIcon(name, type) {
+        if (type === 'dir') return { cls: 'folder', label: '📁' };
+        const lower = name.toLowerCase();
+        if (/\.(png|jpg|jpeg|webp)$/.test(lower)) return { cls: 'image', label: '🖼' };
+        if (/\.(js|mjs|ts)$/.test(lower)) return { cls: 'script', label: '</>' };
+        return { cls: 'file', label: '•' };
+      }
+
+      function renderDevices() {
+        deviceListEl.innerHTML = '';
+        if (!state.devices.length) {
+          const empty = document.createElement('div');
+          empty.style.fontSize = '12px';
+          empty.style.color = 'var(--text-muted)';
+          empty.style.padding = '8px 10px';
+          empty.textContent = '暂无在线设备';
+          deviceListEl.appendChild(empty);
+          return;
+        }
+        state.devices.forEach((d) => {
+          const item = document.createElement('div');
+          item.className = 'device-item' + (state.currentDevice === d.name ? ' active' : '');
+          item.innerHTML = '<span class="device-dot"></span><div style="flex:1;min-width:0;"><div class="device-name">' + d.name + '</div><div class="device-meta">' + (d.connectedAt ? new Date(d.connectedAt).toLocaleString() : '已连接') + '</div></div>';
+          item.addEventListener('click', () => {
+            state.currentDevice = d.name;
+            state.currentPath = null;
+            selectedDeviceLabelEl.textContent = '当前设备：' + d.name;
+            renderDevices();
+            renderRootForDevice();
+            setStatus('已选择设备 ' + d.name + '，请选择目录。');
+          });
+          deviceListEl.appendChild(item);
+        });
+      }
+
+      function renderRootForDevice() {
+        const device = state.currentDevice;
+        if (!device) {
+          breadcrumbsEl.innerHTML = '<span style="font-size:12px;color:var(--text-muted)">请选择左侧设备</span>';
+          fileTbodyEl.innerHTML = '';
+          panelSubtitleEl.textContent = '';
+          return;
+        }
+        state.currentPath = null;
+        breadcrumbsEl.innerHTML = '';
+        const rootCrumb = document.createElement('span');
+        rootCrumb.className = 'breadcrumb-part current';
+        rootCrumb.textContent = '/' + device;
+        breadcrumbsEl.appendChild(rootCrumb);
+        panelSubtitleEl.textContent = '根目录：/' + device + '，选择 local_scripts 或 screenshots';
+        fileTbodyEl.innerHTML = '';
+        [{ name: 'local_scripts', type: 'dir', hint: '脚本文件' }, { name: 'screenshots', type: 'dir', hint: '截图文件' }].forEach((entry) => {
+          const tr = document.createElement('tr');
+          tr.className = 'row-folder';
+          tr.innerHTML = '<td><div class="file-name-cell"><span class="file-icon folder">📁</span><div><div>' + entry.name + '</div><div class="file-meta">' + entry.hint + '</div></div></div></td><td>目录</td><td>' + device + '</td><td></td>';
+          tr.addEventListener('click', () => openDir('/' + device + '/' + entry.name));
+          fileTbodyEl.appendChild(tr);
+        });
+      }
+
+      function renderBreadcrumbs(path) {
+        const device = state.currentDevice;
+        breadcrumbsEl.innerHTML = '';
+        if (!device) return;
+        const parts = path.replace(/^\/+/, '').split('/');
+        const segments = [];
+        for (let i = 0; i < parts.length; i++) {
+          const seg = parts[i];
+          if (!seg) continue;
+          const prev = segments[segments.length - 1] || '';
+          segments.push((prev ? prev + '/' + seg : seg).replace(/^\/+/, ''));
+        }
+        segments.forEach((seg, idx) => {
+          const name = seg.split('/').pop();
+          if (!name) return;
+          if (idx > 0) {
+            const sep = document.createElement('span');
+            sep.className = 'breadcrumb-sep';
+            sep.textContent = '>';
+            breadcrumbsEl.appendChild(sep);
+          }
+          const span = document.createElement('span');
+          span.className = 'breadcrumb-part' + (idx === segments.length - 1 ? ' current' : '');
+          span.textContent = '/' + name;
+          span.addEventListener('click', () => { if (idx === 0) renderRootForDevice(); else openDir('/' + seg); });
+          breadcrumbsEl.appendChild(span);
+        });
+      }
+
+      async function fetchJSON(url) {
+        const res = await fetch(url, { headers: { 'Accept': 'application/json' } });
+        if (!res.ok) {
+          let msg = res.status + ' ' + res.statusText;
+          try { const data = await res.json(); if (data && data.message) msg = data.message; } catch (_) {}
+          throw new Error(msg);
+        }
+        return res.json();
+      }
+
+      async function loadDevices() {
+        try {
+          setStatus('正在加载设备列表…');
+          const data = await fetchJSON('api/devices');
+          state.devices = data.devices || [];
+          renderDevices();
+          if (!state.currentDevice && state.devices.length) {
+            state.currentDevice = state.devices[0].name;
+            selectedDeviceLabelEl.textContent = '当前设备：' + state.currentDevice;
+            renderDevices();
+            renderRootForDevice();
+            setStatus('已加载设备列表，当前设备：' + state.currentDevice);
+          } else if (!state.devices.length) {
+            selectedDeviceLabelEl.textContent = '未选择设备';
+            fileTbodyEl.innerHTML = '';
+            breadcrumbsEl.innerHTML = '<span style="font-size:12px;color:var(--text-muted)">暂无在线设备</span>';
+            setStatus('暂无在线设备。', 'warn');
+          } else {
+            setStatus('已刷新设备列表。');
+          }
+        } catch (err) {
+          setStatus('加载设备列表失败：' + err.message, 'error');
+        }
+      }
+
+      async function openDir(path) {
+        const device = state.currentDevice;
+        if (!device) { setStatus('请先选择设备。', 'warn'); return; }
+        state.currentPath = path;
+        try {
+          panelSubtitleEl.textContent = '目录：' + path;
+          setStatus('正在读取目录 ' + path + ' …');
+          const params = new URLSearchParams({ device: device, path: path });
+          const data = await fetchJSON('api/fs/dir?' + params.toString());
+          const entries = data.entries || [];
+          renderBreadcrumbs(path);
+          fileTbodyEl.innerHTML = '';
+          if (!entries.length) {
+            const tr = document.createElement('tr');
+            tr.innerHTML = '<td colspan="4" style="font-size:12px;color:var(--text-muted);padding:12px 10px;">当前目录下没有文件或子目录。</td>';
+            fileTbodyEl.appendChild(tr);
+          } else {
+            entries.forEach((e) => {
+              const tr = document.createElement('tr');
+              const icon = buildFileIcon(e.name, e.type);
+              tr.innerHTML = '<td><div class="file-name-cell"><span class="file-icon ' + icon.cls + '">' + icon.label + '</span><div><div>' + e.name + '</div><div class="file-meta">' + (e.type === 'dir' ? '目录' : '文件') + '</div></div></div></td><td>' + (e.type === 'dir' ? '目录' : '文件') + '</td><td>' + device + '</td><td><div class="file-actions">' + (e.type === 'file' ? '<button class="link-icon" data-action="view">查看</button><button class="link-icon danger" data-action="delete">删除</button>' : '') + '</div></td>';
+              if (e.type === 'dir') {
+                tr.classList.add('row-folder');
+                tr.addEventListener('click', () => openDir(joinPath(path, e.name)));
+              } else {
+                const actionsCell = tr.querySelector('.file-actions');
+                if (actionsCell) {
+                  actionsCell.addEventListener('click', function (ev) {
+                    ev.stopPropagation();
+                    const target = ev.target;
+                    const filePath = joinPath(path, e.name);
+                    if (target.matches('[data-action="view"]')) window.open('api/fs/file?' + new URLSearchParams({ device, path: filePath }).toString(), '_blank');
+                    else if (target.matches('[data-action="delete"]')) { if (confirm('确定要删除文件 ' + e.name + ' 吗？此操作不可恢复。')) deleteFile(device, filePath); }
+                  });
+                }
+              }
+              fileTbodyEl.appendChild(tr);
+            });
+          }
+          setStatus('目录加载完成：' + path);
+        } catch (err) {
+          setStatus('读取目录失败：' + err.message, 'error');
+        }
+      }
+
+      async function deleteFile(device, path) {
+        try {
+          setStatus('正在删除文件 ' + path + ' …');
+          const params = new URLSearchParams({ device, path });
+          const res = await fetch('api/fs/file?' + params.toString(), { method: 'DELETE' });
+          if (!res.ok) {
+            let msg = res.status + ' ' + res.statusText;
+            try { const data = await res.json(); if (data && data.message) msg = data.message; } catch (_) {}
+            throw new Error(msg);
+          }
+          setStatus('文件已删除：' + path);
+          if (state.currentPath) openDir(state.currentPath);
+        } catch (err) {
+          setStatus('删除文件失败：' + err.message, 'error');
+        }
+      }
+
+      btnRefreshDevices.addEventListener('click', loadDevices);
+      btnRootLocal.addEventListener('click', () => { if (state.currentDevice) openDir('/' + state.currentDevice + '/local_scripts'); else setStatus('请先选择设备。', 'warn'); });
+      btnRootScreenshots.addEventListener('click', () => { if (state.currentDevice) openDir('/' + state.currentDevice + '/screenshots'); else setStatus('请先选择设备。', 'warn'); });
+      btnRefreshDir.addEventListener('click', () => { if (state.currentPath) openDir(state.currentPath); else if (state.currentDevice) renderRootForDevice(); else setStatus('请先选择设备。', 'warn'); });
+
+      loadDevices();
+    })();
+  </script>
+</body>
+
+</html>

package/dist/tokens.d.ts

@@ -0,0 +1,14 @@
+import type { DeviceGateway } from './device-gateway.interface';
+export declare const DEVICE_GATEWAY_TOKEN: unique symbol;
+export interface CctExplorerModuleOptions {
+    /**
+     * 实现 DeviceGateway 的类，由宿主应用提供，会在本模块内注册以便 Controller 注入
+     */
+    deviceGatewayClass: new (...args: any[]) => DeviceGateway;
+    /**
+     * HTTP 路径前缀，例如 'cct' 则接口为 /cct/api/devices、/cct/browser
+     * 空字符串表示挂载在根路径
+     */
+    pathPrefix?: string;
+}
+export declare const CCT_EXPLORER_OPTIONS: unique symbol;

package/dist/tokens.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CCT_EXPLORER_OPTIONS = exports.DEVICE_GATEWAY_TOKEN = void 0;
+exports.DEVICE_GATEWAY_TOKEN = Symbol('DEVICE_GATEWAY_TOKEN');
+exports.CCT_EXPLORER_OPTIONS = Symbol('CCT_EXPLORER_OPTIONS');

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@bomon/nestjs-cct-explorer",
+  "version": "0.1.0",
+  "description": "NestJS 模块：封装 CDP client 的设备资源浏览器 HTTP 接口与 /browser 页面",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').cpSync('src/public', 'dist/public', { recursive: true })\""
+  },
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "keywords": [
+    "nestjs",
+    "cdp",
+    "puppeteer",
+    "socket.io",
+    "file-browser"
+  ],
+  "author": "",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^9.0.0 || ^10.0.0",
+    "@nestjs/core": "^9.0.0 || ^10.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "@types/node": "^20.0.0",
+    "@types/express": "^4.17.0",
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,49 @@
+# @bomon/nestjs-cct-explorer
+
+NestJS 模块：为 CDP Client 网关提供设备资源浏览器 HTTP 接口与 `/browser` 页面。
+
+## 安装
+
+```bash
+pnpm add @bomon/nestjs-cct-explorer
+# 或
+npm i @bomon/nestjs-cct-explorer
+```
+
+## 使用
+
+1. 在你的网关项目中实现 `DeviceGateway` 接口（例如基于 Socket.IO 转发到设备）。
+2. 在根模块中通过 `forRoot` 传入你的网关类（需实现 `DeviceGateway`）：
+
+```ts
+import { Module } from '@nestjs/common';
+import { CctExplorerModule } from '@bomon/nestjs-cct-explorer';
+import { SocketIoDeviceGateway } from './socket-io-device.gateway'; // 你的实现
+
+@Module({
+  imports: [
+    CctExplorerModule.forRoot({
+      deviceGatewayClass: SocketIoDeviceGateway, // 必填
+      pathPrefix: '', // 可选，例如 'cct' 时需配合挂载路径
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+3. 若使用全局前缀（如 `setGlobalPrefix('cct')`），则访问 `http://localhost:3000/cct/browser`，页面内 API 使用相对路径，会自动请求 `/cct/api/*`。
+
+## 路由
+
+| 路径 | 方法 | 说明 |
+|------|------|------|
+| `/browser` | GET | 资源浏览器单页 |
+| `/api/devices` | GET | 设备列表 |
+| `/api/fs/dir` | GET | 读目录 |
+| `/api/fs/file` | GET | 读文件 |
+| `/api/fs/file` | DELETE | 删文件 |
+| `/api/fs/file` | POST | 写文件（需网关实现 writeFile） |
+
+## 依赖
+
+需实现并注入 `DeviceGateway`（见包内 `device-gateway.interface.ts`）。