argus-eye 0.1.0

package/bin.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { start } from './lib/index.mjs'
+
+start().catch((err) => {
+    console.error(err)
+    process.exit(1)
+})

package/lib/capture.d.ts

@@ -0,0 +1,11 @@
+import type { DisplayInfo } from './protocol';
+export interface CaptureOptions {
+    display?: number | string;
+    format?: 'png' | 'jpg';
+}
+export declare function listDisplays(): Promise<DisplayInfo[]>;
+export declare function capture(options?: CaptureOptions): Promise<{
+    buffer: Buffer;
+    mime: string;
+    display?: number | string;
+}>;

package/lib/client.d.ts

@@ -0,0 +1,42 @@
+import type { ResolvedConfig } from './config';
+import type { DisplayInfo } from './protocol';
+export interface ClientHooks {
+    onConnected?: (info: {
+        displays: DisplayInfo[];
+    }) => void;
+    onDisconnected?: (reason: string) => void;
+}
+export declare class ArgusClient {
+    private readonly config;
+    private readonly version;
+    private readonly hooks;
+    private socket?;
+    private displays;
+    /** 服务端看到的 display 索引(0..N-1) → 本机原生 id 的映射。 */
+    private nativeIds;
+    private stopped;
+    private reconnectAttempts;
+    private reconnectTimer?;
+    private heartbeatTimer?;
+    private lastSeen;
+    /** 是否已成功握手（hello_ack ok）。close 时根据这个判断是不是“瞬关”。 */
+    private handshaken;
+    private openedAt;
+    private fullscreen;
+    constructor(config: ResolvedConfig, version: string, hooks?: ClientHooks);
+    start(): Promise<void>;
+    stop(): void;
+    private connect;
+    private handleFrame;
+    private onHelloAck;
+    private onPeek;
+    /**
+     * 解析 cli 配置里 `--display` 在 displays 列表中对应的索引。
+     * 支持数字索引 / 名字（不区分大小写） / 原生 id。
+     */
+    private resolveDefaultIndex;
+    private startHeartbeat;
+    private clearHeartbeat;
+    private scheduleReconnect;
+    private send;
+}

package/lib/config.d.ts

@@ -0,0 +1,19 @@
+export interface ResolvedConfig {
+    server: string;
+    token: string;
+    name: string;
+    display?: number | string;
+    format: 'png' | 'jpg';
+    reconnect: boolean;
+    backoff: number;
+    color: boolean;
+    detectFullscreen: boolean;
+}
+export interface CliFlags {
+    help?: boolean;
+    version?: boolean;
+    listDisplays?: boolean;
+    config?: ResolvedConfig;
+}
+export declare function parseArgs(argv: string[]): CliFlags;
+export declare function getHelpText(): string;

package/lib/fullscreen.d.ts

@@ -0,0 +1,50 @@
+/** 当前活动窗口的简要信息，无法获取时为 undefined。 */
+export interface ActiveWindowInfo {
+    app: string;
+    title: string;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    displayBounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * 检测器：懒加载 `get-windows`（原生 npm 包，gyp 编译）。
+ * 该模块在某些平台 / 环境（Wayland、CI 容器、缺乏权限的 macOS）上不可用，
+ * 这种情况下返回 undefined，调用方按"无法判断"处理。
+ */
+export declare class FullscreenDetector {
+    private enabled;
+    private mod?;
+    private loading?;
+    private warnedFailure;
+    constructor(enabled: boolean);
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    /**
+     * 获取当前活动窗口。无法获取时返回 undefined。
+     */
+    getActiveWindow(): Promise<ActiveWindowInfo | undefined>;
+    /**
+     * 判断 `win` 是否在 `display` 上覆盖整块屏（全屏游戏 / 全屏视频 / 最大化应用）。
+     *
+     * 注意：`get-windows` 在 Windows 上返回的是 DPI 缩放后的逻辑像素，
+     * `screenshot-desktop` 报告的是物理像素。所以比较的是缩放比例，
+     * 该比例应该匹配某个常见的 DPI 缩放因子（100% / 125% / 150% / ...）。
+     *
+     * 这个检查会把"最大化的应用"也视作 fullscreen，这是有意为之 ——
+     * 用户的意图是「看到某个独占应用就别曝光画面」。
+     */
+    isFullscreen(win: ActiveWindowInfo, display: {
+        width?: number;
+        height?: number;
+    }): boolean;
+    private load;
+}

package/lib/index.d.ts

@@ -0,0 +1 @@
+export declare function start(): Promise<void>;

package/lib/index.mjs

@@ -0,0 +1,693 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/index.ts
+import { createRequire } from "node:module";
+
+// src/client.ts
+import WebSocket from "ws";
+
+// src/logger.ts
+import kleur from "kleur";
+var colorEnabled = true;
+function setColorEnabled(value) {
+  colorEnabled = value;
+  kleur.enabled = value;
+}
+__name(setColorEnabled, "setColorEnabled");
+function ts() {
+  const d = /* @__PURE__ */ new Date();
+  const pad = /* @__PURE__ */ __name((n) => String(n).padStart(2, "0"), "pad");
+  return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+__name(ts, "ts");
+function tag(label, color) {
+  const t = `[${ts()}]`;
+  if (!colorEnabled) return `${t} ${label}`;
+  return `${kleur.gray(t)} ${color(label)}`;
+}
+__name(tag, "tag");
+var logger = {
+  info(...args) {
+    console.log(tag("info ", kleur.cyan), ...args);
+  },
+  success(...args) {
+    console.log(tag("ok   ", kleur.green), ...args);
+  },
+  warn(...args) {
+    console.warn(tag("warn ", kleur.yellow), ...args);
+  },
+  error(...args) {
+    console.error(tag("error", kleur.red), ...args);
+  },
+  debug(...args) {
+    if (!process.env.ARGUS_DEBUG) return;
+    console.log(tag("debug", kleur.magenta), ...args);
+  }
+};
+
+// src/capture.ts
+import screenshot from "screenshot-desktop";
+async function listDisplays() {
+  const raw = await screenshot.listDisplays();
+  return raw.map((d) => ({
+    id: d.id,
+    name: d.name,
+    width: d.width,
+    height: d.height,
+    primary: d.primary
+  }));
+}
+__name(listDisplays, "listDisplays");
+async function capture(options = {}) {
+  const format = options.format ?? "jpg";
+  const mime = format === "png" ? "image/png" : "image/jpeg";
+  const opts = { format };
+  if (options.display !== void 0) {
+    opts.screen = options.display;
+  }
+  const buffer = await screenshot(opts);
+  return { buffer, mime, display: options.display };
+}
+__name(capture, "capture");
+
+// src/fullscreen.ts
+var FullscreenDetector = class {
+  constructor(enabled) {
+    this.enabled = enabled;
+  }
+  static {
+    __name(this, "FullscreenDetector");
+  }
+  mod;
+  loading;
+  warnedFailure = false;
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  /**
+   * 获取当前活动窗口。无法获取时返回 undefined。
+   */
+  async getActiveWindow() {
+    if (!this.enabled) return void 0;
+    const mod = await this.load();
+    if (!mod) return void 0;
+    try {
+      const win = await mod.activeWindow({
+        // 不要在 macOS 上触发权限弹窗
+        accessibilityPermission: false,
+        screenRecordingPermission: false
+      });
+      if (!win || !win.bounds) return void 0;
+      return {
+        app: win.owner?.name ?? "",
+        title: win.title ?? "",
+        bounds: win.bounds
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.debug(`activeWindow failed: ${message}`);
+      return void 0;
+    }
+  }
+  /**
+   * 判断 `win` 是否在 `display` 上覆盖整块屏（全屏游戏 / 全屏视频 / 最大化应用）。
+   *
+   * 注意：`get-windows` 在 Windows 上返回的是 DPI 缩放后的逻辑像素，
+   * `screenshot-desktop` 报告的是物理像素。所以比较的是缩放比例，
+   * 该比例应该匹配某个常见的 DPI 缩放因子（100% / 125% / 150% / ...）。
+   *
+   * 这个检查会把"最大化的应用"也视作 fullscreen，这是有意为之 ——
+   * 用户的意图是「看到某个独占应用就别曝光画面」。
+   */
+  isFullscreen(win, display) {
+    if (!display.width || !display.height) return false;
+    const { bounds } = win;
+    if (bounds.width <= 0 || bounds.height <= 0) return false;
+    const widthRatio = bounds.width / display.width;
+    const heightRatio = bounds.height / display.height;
+    const ratioMismatch = Math.abs(widthRatio - heightRatio) / Math.max(widthRatio, heightRatio);
+    if (ratioMismatch > 0.02) return false;
+    const scale = (widthRatio + heightRatio) / 2;
+    const dpiScales = [1, 0.8, 2 / 3, 4 / 7, 0.5, 4 / 9, 0.4];
+    const matchesDpi = dpiScales.some((s) => Math.abs(scale - s) < 0.01);
+    if (!matchesDpi) return false;
+    return Math.abs(bounds.x) <= 8 && Math.abs(bounds.y) <= 8;
+  }
+  load() {
+    if (this.mod) return Promise.resolve(this.mod);
+    if (this.loading) return this.loading;
+    this.loading = (async () => {
+      try {
+        const mod = await import("get-windows");
+        this.mod = mod;
+        return mod;
+      } catch (err) {
+        if (!this.warnedFailure) {
+          const message = err instanceof Error ? err.message : String(err);
+          logger.warn(
+            `fullscreen detection unavailable: ${message}. (get-windows failed to load; install it manually if you want this feature.)`
+          );
+          this.warnedFailure = true;
+        }
+        return void 0;
+      }
+    })();
+    return this.loading;
+  }
+};
+
+// src/client.ts
+var HEARTBEAT_TIMEOUT_MS = 9e4;
+var ArgusClient = class {
+  constructor(config, version, hooks = {}) {
+    this.config = config;
+    this.version = version;
+    this.hooks = hooks;
+    this.fullscreen = new FullscreenDetector(config.detectFullscreen);
+  }
+  static {
+    __name(this, "ArgusClient");
+  }
+  socket;
+  displays = [];
+  /** 服务端看到的 display 索引(0..N-1) → 本机原生 id 的映射。 */
+  nativeIds = [];
+  stopped = false;
+  reconnectAttempts = 0;
+  reconnectTimer;
+  heartbeatTimer;
+  lastSeen = 0;
+  /** 是否已成功握手（hello_ack ok）。close 时根据这个判断是不是“瞬关”。 */
+  handshaken = false;
+  openedAt = 0;
+  fullscreen;
+  async start() {
+    try {
+      const native = await listDisplays();
+      this.nativeIds = native.map((d) => d.id);
+      this.displays = native.map((d, i) => ({
+        id: i,
+        name: d.name ?? String(d.id),
+        width: d.width,
+        height: d.height,
+        primary: d.primary
+      }));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.warn(`failed to list displays: ${message}`);
+      this.displays = [];
+      this.nativeIds = [];
+    }
+    this.connect();
+  }
+  stop() {
+    this.stopped = true;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.clearHeartbeat();
+    if (this.socket) {
+      try {
+        this.send({ type: "bye", reason: "cli_exit" });
+      } catch {
+      }
+      try {
+        this.socket.close(1e3, "cli_exit");
+      } catch {
+      }
+    }
+  }
+  connect() {
+    if (this.stopped) return;
+    logger.info(`connecting to ${this.config.server} ...`);
+    let socket;
+    try {
+      socket = new WebSocket(this.config.server);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error(`failed to create socket: ${message}`);
+      this.scheduleReconnect();
+      return;
+    }
+    this.socket = socket;
+    this.handshaken = false;
+    this.openedAt = 0;
+    socket.on("open", () => {
+      this.openedAt = Date.now();
+      this.lastSeen = Date.now();
+      const defaultIndex = this.resolveDefaultIndex();
+      this.send({
+        type: "hello",
+        name: this.config.name,
+        token: this.config.token,
+        version: this.version,
+        displays: this.displays,
+        defaultDisplay: defaultIndex
+      });
+    });
+    socket.on("message", (raw, isBinary) => {
+      if (isBinary) return;
+      this.lastSeen = Date.now();
+      const text = typeof raw === "string" ? raw : raw.toString("utf8");
+      let frame;
+      try {
+        frame = JSON.parse(text);
+      } catch {
+        return;
+      }
+      this.handleFrame(frame);
+    });
+    socket.on("close", (code, reasonBuf) => {
+      const reason = reasonBuf?.toString() || `code_${code}`;
+      this.clearHeartbeat();
+      this.socket = void 0;
+      this.hooks.onDisconnected?.(reason);
+      if (code === 4001) {
+        logger.error("auth failed: token rejected by server. exiting.");
+        process.exit(2);
+      }
+      if (code === 4004) {
+        logger.error(
+          `auth failed: server rejected name "${this.config.name}". exiting.`
+        );
+        process.exit(2);
+      }
+      const justOpenedAndClosed = this.openedAt > 0 && !this.handshaken && Date.now() - this.openedAt < 3e3;
+      if (justOpenedAndClosed && (code === 1005 || code === 1006)) {
+        logger.warn(
+          `disconnected immediately after open (${code} ${reason}). check the WebSocket path: server is configured at ${this.config.server} ?`
+        );
+      } else {
+        logger.warn(`disconnected (${code} ${reason})`);
+      }
+      this.scheduleReconnect();
+    });
+    socket.on("error", (err) => {
+      logger.warn(`socket error: ${err.message}`);
+    });
+  }
+  handleFrame(frame) {
+    switch (frame.type) {
+      case "hello_ack":
+        return this.onHelloAck(frame);
+      case "peek":
+        return void this.onPeek(frame);
+      case "ping":
+        this.send({ type: "pong", t: frame.t });
+        return;
+      case "pong":
+        return;
+    }
+  }
+  onHelloAck(frame) {
+    if (!frame.ok) {
+      logger.error(`server rejected hello: ${frame.error ?? "unknown"}`);
+      return;
+    }
+    this.handshaken = true;
+    this.reconnectAttempts = 0;
+    logger.success(
+      `connected as "${this.config.name}"; ${this.displays.length} display(s) reported`
+    );
+    for (const d of this.displays) {
+      const size = d.width && d.height ? `${d.width}x${d.height}` : "unknown";
+      logger.info(`  · display ${d.id}: ${d.name ?? "-"} (${size})`);
+    }
+    logger.info(
+      `fullscreen detection: ${this.fullscreen.isEnabled() ? "on" : "off"}`
+    );
+    this.startHeartbeat();
+    this.hooks.onConnected?.({ displays: this.displays });
+  }
+  async onPeek(frame) {
+    let publicIndex;
+    let target;
+    if (frame.display !== void 0) {
+      const idx = typeof frame.display === "number" ? frame.display : Number(frame.display);
+      if (Number.isFinite(idx) && this.nativeIds[idx] !== void 0) {
+        publicIndex = idx;
+        target = this.nativeIds[idx];
+      } else {
+        this.send({
+          type: "peek_error",
+          id: frame.id,
+          error: `unknown_display:${frame.display}`
+        });
+        return;
+      }
+    } else {
+      publicIndex = this.resolveDefaultIndex();
+      target = publicIndex !== void 0 ? this.nativeIds[publicIndex] : void 0;
+    }
+    if (this.fullscreen.isEnabled()) {
+      const win = await this.fullscreen.getActiveWindow();
+      const display = publicIndex !== void 0 ? this.displays[publicIndex] : void 0;
+      if (win && display && this.fullscreen.isFullscreen(win, display)) {
+        logger.info(
+          `peek #${frame.id} → busy: ${win.app || win.title || "fullscreen"}`
+        );
+        this.send({
+          type: "peek_busy",
+          id: frame.id,
+          app: win.app,
+          title: win.title,
+          reason: "fullscreen"
+        });
+        return;
+      }
+    }
+    const start2 = Date.now();
+    try {
+      const result = await capture({
+        display: target,
+        format: this.config.format
+      });
+      const base64 = result.buffer.toString("base64");
+      this.send({
+        type: "peek_result",
+        id: frame.id,
+        image: base64,
+        mime: result.mime,
+        display: frame.display
+      });
+      const elapsed = Date.now() - start2;
+      const kb = (result.buffer.length / 1024).toFixed(1);
+      logger.info(
+        `peek #${frame.id} → display ${frame.display ?? "default"} (${kb} KB ${this.config.format}, ${elapsed}ms)`
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.warn(`peek #${frame.id} failed: ${message}`);
+      this.send({
+        type: "peek_error",
+        id: frame.id,
+        error: message
+      });
+    }
+  }
+  /**
+   * 解析 cli 配置里 `--display` 在 displays 列表中对应的索引。
+   * 支持数字索引 / 名字（不区分大小写） / 原生 id。
+   */
+  resolveDefaultIndex() {
+    const target = this.config.display;
+    if (target === void 0) {
+      const primary = this.displays.findIndex((d) => d.primary);
+      if (primary >= 0) return primary;
+      return this.displays.length > 0 ? 0 : void 0;
+    }
+    if (typeof target === "number" && this.displays[target]) return target;
+    const lower = String(target).toLowerCase();
+    for (let i = 0; i < this.displays.length; i++) {
+      const d = this.displays[i];
+      const nativeId = this.nativeIds[i];
+      if (String(d.id) === String(target) || String(nativeId).toLowerCase() === lower || d.name && d.name.toLowerCase() === lower) {
+        return i;
+      }
+    }
+    return this.displays.length > 0 ? 0 : void 0;
+  }
+  startHeartbeat() {
+    this.clearHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      const elapsed = Date.now() - this.lastSeen;
+      if (elapsed > HEARTBEAT_TIMEOUT_MS) {
+        logger.warn("heartbeat timeout, closing socket");
+        try {
+          this.socket?.terminate();
+        } catch {
+        }
+      }
+    }, 15e3);
+  }
+  clearHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = void 0;
+    }
+  }
+  scheduleReconnect() {
+    if (this.stopped) return;
+    if (!this.config.reconnect) {
+      logger.info("reconnect disabled, exiting.");
+      process.exit(1);
+    }
+    this.reconnectAttempts++;
+    const base = 1e3;
+    const exp = Math.min(this.reconnectAttempts - 1, 16);
+    const delay = Math.min(this.config.backoff, base * Math.pow(2, exp));
+    const jitter = Math.floor(Math.random() * 500);
+    const wait = delay + jitter;
+    logger.info(
+      `reconnecting in ${wait}ms (attempt #${this.reconnectAttempts}) ...`
+    );
+    this.reconnectTimer = setTimeout(() => this.connect(), wait);
+  }
+  send(frame) {
+    const socket = this.socket;
+    if (!socket || socket.readyState !== WebSocket.OPEN) return;
+    socket.send(JSON.stringify(frame));
+  }
+};
+
+// src/config.ts
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+import yargsParser from "yargs-parser";
+var HELP_TEXT = `argus-eye [options]
+
+  -s, --server <url>       WebSocket 地址（必填，如 ws://host:5140/argus）
+  -t, --token  <token>     鉴权 token（必填）
+  -n, --name   <name>      上报给服务端的名字（默认: os.hostname()）
+  -d, --display <id>       默认截哪块屏（数字 id，缺省=主屏）
+      --list-displays      列出本机显示器后退出
+      --format <png|jpg>   传输格式（默认 jpg，省流量）
+      --no-reconnect       禁用断线重连
+      --backoff <ms>       重连最大间隔（默认 30000）
+      --no-detect-fullscreen
+                           关闭"全屏即拒拍"行为（默认开启）。打开时若检测到
+                           当前焦点窗口铺满整块显示器（如全屏游戏 / 视频），
+                           则向服务端返回 peek_busy 而不是真截图。
+      --config <path>      JSON 配置文件
+      --no-color           关闭着色输出
+  -h, --help               显示帮助
+  -v, --version            显示版本
+
+环境变量：ARGUS_SERVER / ARGUS_TOKEN / ARGUS_NAME 也会被读取，
+优先级：argv > env > ~/.argus-eye.json (或 --config 指定) > 默认值。
+`;
+function parseArgs(argv) {
+  const parsed = yargsParser(argv, {
+    alias: {
+      server: ["s"],
+      token: ["t"],
+      name: ["n"],
+      display: ["d"],
+      help: ["h"],
+      version: ["v"]
+    },
+    string: ["server", "token", "name", "config", "format", "display"],
+    number: ["backoff"],
+    boolean: [
+      "help",
+      "version",
+      "reconnect",
+      "color",
+      "listDisplays",
+      "detectFullscreen"
+    ],
+    configuration: {
+      "camel-case-expansion": true,
+      "strip-aliased": true,
+      "unknown-options-as-args": false
+    },
+    default: {
+      reconnect: true,
+      color: true,
+      listDisplays: false,
+      detectFullscreen: true
+    }
+  });
+  if (parsed.help) return { help: true };
+  if (parsed.version) return { version: true };
+  const fileConfig = loadConfigFile(
+    typeof parsed.config === "string" ? parsed.config : void 0
+  );
+  const env = process.env;
+  const merged = {
+    server: asString(parsed.server) ?? env.ARGUS_SERVER ?? asString(fileConfig.server),
+    token: asString(parsed.token) ?? env.ARGUS_TOKEN ?? asString(fileConfig.token),
+    name: asString(parsed.name) ?? env.ARGUS_NAME ?? asString(fileConfig.name) ?? os.hostname(),
+    display: asDisplay(parsed.display) ?? asDisplay(fileConfig.display) ?? void 0,
+    format: asString(parsed.format) ?? asString(fileConfig.format) ?? "jpg",
+    reconnect: asBoolean(parsed.reconnect) ?? asBoolean(fileConfig.reconnect) ?? true,
+    backoff: asNumber(parsed.backoff) ?? asNumber(fileConfig.backoff) ?? 3e4,
+    color: asBoolean(parsed.color) ?? true,
+    detectFullscreen: asBoolean(parsed.detectFullscreen) ?? asBoolean(fileConfig.detectFullscreen) ?? true
+  };
+  if (parsed.listDisplays) {
+    return {
+      listDisplays: true,
+      config: {
+        server: merged.server ?? "",
+        token: merged.token ?? "",
+        name: merged.name ?? os.hostname(),
+        display: merged.display,
+        format: merged.format ?? "jpg",
+        reconnect: merged.reconnect ?? true,
+        backoff: merged.backoff ?? 3e4,
+        color: merged.color ?? true,
+        detectFullscreen: merged.detectFullscreen ?? true
+      }
+    };
+  }
+  if (!merged.server) {
+    throw new Error("missing --server (or ARGUS_SERVER)");
+  }
+  if (!merged.token) {
+    throw new Error("missing --token (or ARGUS_TOKEN)");
+  }
+  if (merged.format !== "png" && merged.format !== "jpg") {
+    throw new Error(`invalid --format: ${merged.format}`);
+  }
+  return {
+    config: {
+      server: merged.server,
+      token: merged.token,
+      name: merged.name ?? os.hostname(),
+      display: merged.display,
+      format: merged.format,
+      reconnect: merged.reconnect ?? true,
+      backoff: merged.backoff ?? 3e4,
+      color: merged.color ?? true,
+      detectFullscreen: merged.detectFullscreen ?? true
+    }
+  };
+}
+__name(parseArgs, "parseArgs");
+function getHelpText() {
+  return HELP_TEXT;
+}
+__name(getHelpText, "getHelpText");
+function loadConfigFile(explicit) {
+  const candidates = [
+    explicit,
+    path.join(os.homedir(), ".argus-eye.json"),
+    path.join(os.homedir(), ".config", "argus-eye", "config.json")
+  ].filter((p) => Boolean(p));
+  for (const file of candidates) {
+    try {
+      if (fs.existsSync(file)) {
+        const raw = fs.readFileSync(file, "utf-8");
+        return JSON.parse(raw);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.warn(`failed to read config ${file}: ${message}`);
+    }
+  }
+  return {};
+}
+__name(loadConfigFile, "loadConfigFile");
+function asString(v) {
+  if (typeof v === "string" && v.length > 0) return v;
+  return void 0;
+}
+__name(asString, "asString");
+function asNumber(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.length > 0 && !Number.isNaN(Number(v))) {
+    return Number(v);
+  }
+  return void 0;
+}
+__name(asNumber, "asNumber");
+function asBoolean(v) {
+  if (typeof v === "boolean") return v;
+  if (typeof v === "string") {
+    if (v === "true") return true;
+    if (v === "false") return false;
+  }
+  return void 0;
+}
+__name(asBoolean, "asBoolean");
+function asDisplay(v) {
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string" && v.length > 0) {
+    const n = Number(v);
+    if (!Number.isNaN(n) && /^-?\d+$/.test(v)) return n;
+    return v;
+  }
+  return void 0;
+}
+__name(asDisplay, "asDisplay");
+
+// src/index.ts
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+async function start() {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`argus-eye: ${message}
+
+`);
+    process.stderr.write(getHelpText());
+    process.exit(2);
+  }
+  if (parsed.help) {
+    process.stdout.write(getHelpText());
+    return;
+  }
+  if (parsed.version) {
+    process.stdout.write(`argus-eye v${pkg.version}
+`);
+    return;
+  }
+  if (parsed.config && !parsed.config.color) {
+    setColorEnabled(false);
+  } else {
+    setColorEnabled(true);
+  }
+  if (parsed.listDisplays) {
+    try {
+      const displays = await listDisplays();
+      if (displays.length === 0) {
+        process.stdout.write("no displays found\n");
+        return;
+      }
+      displays.forEach((d, i) => {
+        const size = d.width && d.height ? `${d.width}x${d.height}` : "unknown";
+        process.stdout.write(
+          `${i}	${d.name ?? "-"}	${size}${d.primary ? "	(primary)" : ""}	[native:${d.id}]
+`
+        );
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`failed to list displays: ${message}
+`);
+      process.exit(1);
+    }
+    return;
+  }
+  const config = parsed.config;
+  const client = new ArgusClient(config, pkg.version);
+  const handleSignal = /* @__PURE__ */ __name((signal) => {
+    logger.info(`received ${signal}, shutting down ...`);
+    client.stop();
+    setTimeout(() => process.exit(0), 200);
+  }, "handleSignal");
+  process.on("SIGINT", () => handleSignal("SIGINT"));
+  process.on("SIGTERM", () => handleSignal("SIGTERM"));
+  await client.start();
+}
+__name(start, "start");
+export {
+  start
+};

package/lib/logger.d.ts

@@ -0,0 +1,8 @@
+export declare function setColorEnabled(value: boolean): void;
+export declare const logger: {
+    info(...args: unknown[]): void;
+    success(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+};

package/lib/protocol.d.ts

@@ -0,0 +1,60 @@
+export interface DisplayInfo {
+    id: number | string;
+    name?: string;
+    width?: number;
+    height?: number;
+    primary?: boolean;
+}
+export interface HelloFrame {
+    type: 'hello';
+    name: string;
+    token: string;
+    version?: string;
+    displays?: DisplayInfo[];
+    defaultDisplay?: number;
+}
+export interface HelloAckFrame {
+    type: 'hello_ack';
+    ok: boolean;
+    error?: string;
+}
+export interface PeekRequestFrame {
+    type: 'peek';
+    id: string;
+    display?: number | string;
+}
+export interface PeekResultFrame {
+    type: 'peek_result';
+    id: string;
+    image: string;
+    mime?: string;
+    width?: number;
+    height?: number;
+    display?: number | string;
+}
+export interface PeekErrorFrame {
+    type: 'peek_error';
+    id: string;
+    error: string;
+}
+export interface PeekBusyFrame {
+    type: 'peek_busy';
+    id: string;
+    app?: string;
+    title?: string;
+    reason?: 'fullscreen' | string;
+}
+export interface PingFrame {
+    type: 'ping';
+    t?: number;
+}
+export interface PongFrame {
+    type: 'pong';
+    t?: number;
+}
+export interface ByeFrame {
+    type: 'bye';
+    reason?: string;
+}
+export type ServerFrame = HelloAckFrame | PeekRequestFrame | PingFrame | PongFrame;
+export type ClientFrame = HelloFrame | PeekResultFrame | PeekErrorFrame | PeekBusyFrame | PingFrame | PongFrame | ByeFrame;

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "argus-eye",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Argus eye —— koishi-plugin-argus 的截图客户端 CLI。",
+  "author": "dingyi222666 <dingyi222666@foxmail.com>",
+  "license": "MIT",
+  "bin": "./bin.mjs",
+  "main": "./lib/index.mjs",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib",
+    "bin.mjs",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "yarn yakumo build",
+    "bump": "yarn yakumo version",
+    "dep": "yarn yakumo upgrade",
+    "pub": "yarn yakumo publish",
+    "lint": "yarn eslint src --ext=ts",
+    "lint-fix": "yarn eslint src --ext=ts --fix"
+  },
+  "dependencies": {
+    "kleur": "^4.1.5",
+    "screenshot-desktop": "^1.15.0",
+    "ws": "^8.18.0",
+    "yargs-parser": "^21.1.1"
+  },
+  "optionalDependencies": {
+    "get-windows": "^9.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@types/screenshot-desktop": "^1.12.3",
+    "@types/ws": "^8.5.10",
+    "@types/yargs-parser": "^21.0.3",
+    "@typescript-eslint/eslint-plugin": "^7.18.1-alpha.3",
+    "@typescript-eslint/parser": "^8.45.1-alpha.0",
+    "esbuild": "^0.25.10",
+    "esbuild-register": "npm:@shigma/esbuild-register@^1.1.1",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-n": "^16.6.2",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-promise": "^7.2.1",
+    "yakumo": "^1.0.0",
+    "yakumo-esbuild": "^1.0.0",
+    "yakumo-tsc": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "argus",
+    "argus-eye",
+    "koishi",
+    "screenshot",
+    "remote",
+    "cli"
+  ],
+  "homepage": "https://github.com/dingyi222666/argus-eye#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dingyi222666/argus-eye.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dingyi222666/argus-eye/issues"
+  }
+}

package/readme.md

@@ -0,0 +1,73 @@
+# argus-eye
+
+> [`koishi-plugin-argus`](https://www.npmjs.com/package/koishi-plugin-argus) 的截图客户端 CLI。
+> 在你自己电脑上跑一个，群里就能用 `/peek` 偷窥你了（自带模糊）。
+
+## 立即使用
+
+```bash
+npx argus-eye \
+  --server ws://your-koishi-host:5140/argus \
+  --token  your-secret-token \
+  --name   dingyi
+```
+
+## 命令行参数
+
+```
+argus-eye [options]
+
+  -s, --server <url>       WebSocket 地址（必填，如 ws://host:5140/argus）
+  -t, --token  <token>     鉴权 token（必填）
+  -n, --name   <name>      上报给服务端的名字（默认: os.hostname()）
+                            群里 /peek <name> 即用此名
+      --list-displays      列出本机显示器后退出
+  -d, --display <id>       默认截哪块屏（数字 id，缺省=主屏）
+      --format <png|jpg>   传输格式（默认 jpg，更省流量）
+      --no-reconnect       禁用断线重连
+      --backoff <ms>       重连最大间隔（默认 30000）
+      --no-detect-fullscreen
+                           关闭"全屏即拒拍"行为（默认开启）
+      --config <path>      JSON 配置文件
+      --no-color           关闭着色输出
+  -h, --help               显示帮助
+  -v, --version            显示版本
+
+## 全屏检测
+
+CLI 默认开启全屏检测：当截屏时检测到当前焦点窗口铺满整块显示器（典型如全屏游戏 / 全屏视频），
+就向服务端返回一段「客户端正忙：xxx」的提示而不是真截图。
+群友看到的是程序名（"League of Legends" / "Bilibili" 等），看不到画面。
+如果你想关掉这个行为，加 `--no-detect-fullscreen`。
+
+底层使用 [`get-windows`](https://www.npmjs.com/package/get-windows)（optional dependency）。
+该包是原生 napi 模块，部分平台（Linux Wayland）不支持，加载失败时会自动降级为永远「不忙」。
+```
+
+## 配置文件
+
+支持把常用参数写到 `~/.argus-eye.json` 或通过 `--config` 指定，命令行参数 > 环境变量 > 配置文件 > 默认值：
+
+```json
+{
+    "server": "ws://my.box:5140/argus",
+    "token": "xxx",
+    "name": "dingyi-pc",
+    "display": 0,
+    "format": "jpg"
+}
+```
+
+环境变量：`ARGUS_SERVER` / `ARGUS_TOKEN` / `ARGUS_NAME`。
+
+## 平台说明
+
+底层使用 [`screenshot-desktop`](https://www.npmjs.com/package/screenshot-desktop)：
+
+- macOS：内置 `screencapture`，无需额外依赖。
+- Windows：自带打包脚本，无需额外依赖。
+- Linux：需要安装 `imagemagick` 或 `scrot`。
+
+## 许可
+
+MIT