argus-eye 0.2.0 → 0.2.1

package/lib/config.d.ts

@@ -8,6 +8,10 @@ export interface ResolvedConfig {
     backoff: number;
     color: boolean;
     detectFullscreen: boolean;
+    /** 永不视为 busy 的应用名列表（不区分大小写、子串匹配）。空数组 = 用默认列表。 */
+    allowApps: string[];
+    /** 强制视为 busy 的应用名列表。优先级高于 allowApps。 */
+    busyApps: string[];
 }
 export interface CliFlags {
     help?: boolean;

package/lib/fullscreen.d.ts

@@ -8,24 +8,43 @@ export interface ActiveWindowInfo {
         width: number;
         height: number;
     };
-    displayBounds?: {
+    contentBounds?: {
         x: number;
         y: number;
         width: number;
         height: number;
     };
 }
+/**
+ * 默认的"允许截图"应用名（不区分大小写、子串匹配）。
+ * 这些是即使全屏也是普通工作 / 浏览场景，应当能被群友看到的应用。
+ */
+export declare const DEFAULT_ALLOW_APPS: string[];
+export interface FullscreenDetectorOptions {
+    enabled: boolean;
+    /** 不算 busy 的应用名（不区分大小写、子串匹配）。 */
+    allowApps?: string[];
+    /** 强制视为 busy 的应用名（不区分大小写、子串匹配）。优先级高于 allowApps。 */
+    busyApps?: string[];
+}
+export interface FullscreenCheckResult {
+    busy: boolean;
+    /** 命中的判定原因，方便排查 */
+    reason?: 'allow_app' | 'busy_app' | 'fullscreen_geometry';
+}
 /**
  * 检测器：懒加载 `get-windows`（原生 npm 包，gyp 编译）。
  * 该模块在某些平台 / 环境（Wayland、CI 容器、缺乏权限的 macOS）上不可用，
  * 这种情况下返回 undefined，调用方按"无法判断"处理。
  */
 export declare class FullscreenDetector {
-    private enabled;
+    private options;
     private mod?;
     private loading?;
     private warnedFailure;
-    constructor(enabled: boolean);
+    private allowApps;
+    private busyApps;
+    constructor(options: FullscreenDetectorOptions);
     setEnabled(enabled: boolean): void;
     isEnabled(): boolean;
     /**
@@ -33,15 +52,32 @@ export declare class FullscreenDetector {
      */
     getActiveWindow(): Promise<ActiveWindowInfo | undefined>;
     /**
-     * 判断 `win` 是否在 `display` 上覆盖整块屏（全屏游戏 / 全屏视频 / 最大化应用）。
+     * 综合判定当前窗口是否应当视为 busy。
+     *
+     * 优先级：
+     *  1. allowApps 命中 → 永不 busy（即使 F11 全屏 chrome）
+     *  2. busyApps 命中 → 永远 busy
+     *  3. 几何全屏：bounds 起点贴近 (0,0) AND `contentBounds == bounds`
+     *     AND 覆盖整块显示器 → busy
+     */
+    check(win: ActiveWindowInfo, display: {
+        width?: number;
+        height?: number;
+    }): FullscreenCheckResult;
+    private matchAny;
+    /**
+     * 几何上是否是真正的全屏（区别于"最大化窗口"）。
      *
-     * 注意：`get-windows` 在 Windows 上返回的是 DPI 缩放后的逻辑像素，
-     * `screenshot-desktop` 报告的是物理像素。所以比较的是缩放比例，
-     * 该比例应该匹配某个常见的 DPI 缩放因子（100% / 125% / 150% / ...）。
+     * 关键观察（Windows 上）：
+     *  - 最大化的普通窗口：`bounds.x = -7, bounds.y = -7`（aero 边框 overscan），
+     *    `contentBounds` 比 `bounds` 小一圈（标题栏 / 边框被排除）
+     *  - 真正的全屏（F11 / 全屏游戏）：`bounds.x = 0, bounds.y = 0`，
+     *    `contentBounds == bounds`，整体尺寸贴合整块显示器
      *
-     * 这个检查会把"最大化的应用"也视作 fullscreen，这是有意为之 ——
-     * 用户的意图是「看到某个独占应用就别曝光画面」。
+     * macOS / Linux 通常没有 contentBounds，退化为只看起点和尺寸。
      */
+    private isFullscreenGeometry;
+    /** 兼容旧名字。新代码用 `check`。 */
     isFullscreen(win: ActiveWindowInfo, display: {
         width?: number;
         height?: number;

package/lib/index.mjs

@@ -72,9 +72,82 @@ async function capture(options = {}) {
 __name(capture, "capture");
 
 // src/fullscreen.ts
+var DEFAULT_ALLOW_APPS = [
+  // browsers
+  "chrome",
+  "edge",
+  "firefox",
+  "safari",
+  "opera",
+  "brave",
+  "vivaldi",
+  "arc",
+  // IDE / editors
+  "code",
+  // VS Code
+  "cursor",
+  "visual studio",
+  "devenv",
+  "idea",
+  "webstorm",
+  "pycharm",
+  "goland",
+  "rider",
+  "clion",
+  "rustrover",
+  "phpstorm",
+  "datagrip",
+  "fleet",
+  "sublime",
+  "atom",
+  "notepad",
+  "typora",
+  "obsidian",
+  "notion",
+  "logseq",
+  // shells / terminals
+  "windowsterminal",
+  "powershell",
+  "pwsh",
+  "cmd",
+  "conhost",
+  "wezterm",
+  "iterm",
+  "alacritty",
+  "kitty",
+  "tabby",
+  "hyper",
+  // file managers
+  "explorer",
+  "finder",
+  // common IM / collab
+  "wechat",
+  "weixin",
+  "qq",
+  "tim",
+  "telegram",
+  "discord",
+  "slack",
+  "teams",
+  "zoom",
+  "feishu",
+  "lark",
+  "dingtalk",
+  // office
+  "word",
+  "excel",
+  "powerpoint",
+  "wps",
+  "acrobat",
+  "sumatra"
+];
 var FullscreenDetector = class {
-  constructor(enabled) {
-    this.enabled = enabled;
+  constructor(options) {
+    this.options = options;
+    this.allowApps = (options.allowApps ?? DEFAULT_ALLOW_APPS).map(
+      (s) => s.toLowerCase()
+    );
+    this.busyApps = (options.busyApps ?? []).map((s) => s.toLowerCase());
   }
   static {
     __name(this, "FullscreenDetector");
@@ -82,17 +155,19 @@ var FullscreenDetector = class {
   mod;
   loading;
   warnedFailure = false;
+  allowApps;
+  busyApps;
   setEnabled(enabled) {
-    this.enabled = enabled;
+    this.options.enabled = enabled;
   }
   isEnabled() {
-    return this.enabled;
+    return this.options.enabled;
   }
   /**
    * 获取当前活动窗口。无法获取时返回 undefined。
    */
   async getActiveWindow() {
-    if (!this.enabled) return void 0;
+    if (!this.options.enabled) return void 0;
     const mod = await this.load();
     if (!mod) return void 0;
     try {
@@ -105,7 +180,8 @@ var FullscreenDetector = class {
       return {
         app: win.owner?.name ?? "",
         title: win.title ?? "",
-        bounds: win.bounds
+        bounds: win.bounds,
+        contentBounds: win.contentBounds
       };
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -114,28 +190,64 @@ var FullscreenDetector = class {
     }
   }
   /**
-   * 判断 `win` 是否在 `display` 上覆盖整块屏（全屏游戏 / 全屏视频 / 最大化应用）。
+   * 综合判定当前窗口是否应当视为 busy。
    *
-   * 注意：`get-windows` 在 Windows 上返回的是 DPI 缩放后的逻辑像素，
-   * `screenshot-desktop` 报告的是物理像素。所以比较的是缩放比例，
-   * 该比例应该匹配某个常见的 DPI 缩放因子（100% / 125% / 150% / ...）。
+   * 优先级：
+   *  1. allowApps 命中 → 永不 busy（即使 F11 全屏 chrome）
+   *  2. busyApps 命中 → 永远 busy
+   *  3. 几何全屏：bounds 起点贴近 (0,0) AND `contentBounds == bounds`
+   *     AND 覆盖整块显示器 → busy
+   */
+  check(win, display) {
+    const app = win.app.toLowerCase();
+    const title = win.title.toLowerCase();
+    if (this.matchAny(this.busyApps, app, title)) {
+      return { busy: true, reason: "busy_app" };
+    }
+    if (this.matchAny(this.allowApps, app, title)) {
+      return { busy: false, reason: "allow_app" };
+    }
+    if (this.isFullscreenGeometry(win, display)) {
+      return { busy: true, reason: "fullscreen_geometry" };
+    }
+    return { busy: false };
+  }
+  matchAny(patterns, ...haystack) {
+    if (patterns.length === 0) return false;
+    return patterns.some((p) => haystack.some((h) => h.includes(p)));
+  }
+  /**
+   * 几何上是否是真正的全屏（区别于"最大化窗口"）。
+   *
+   * 关键观察（Windows 上）：
+   *  - 最大化的普通窗口：`bounds.x = -7, bounds.y = -7`（aero 边框 overscan），
+   *    `contentBounds` 比 `bounds` 小一圈（标题栏 / 边框被排除）
+   *  - 真正的全屏（F11 / 全屏游戏）：`bounds.x = 0, bounds.y = 0`，
+   *    `contentBounds == bounds`，整体尺寸贴合整块显示器
    *
-   * 这个检查会把"最大化的应用"也视作 fullscreen，这是有意为之 ——
-   * 用户的意图是「看到某个独占应用就别曝光画面」。
+   * macOS / Linux 通常没有 contentBounds，退化为只看起点和尺寸。
    */
-  isFullscreen(win, display) {
+  isFullscreenGeometry(win, display) {
     if (!display.width || !display.height) return false;
-    const { bounds } = win;
+    const { bounds, contentBounds } = win;
     if (bounds.width <= 0 || bounds.height <= 0) return false;
+    if (Math.abs(bounds.x) > 1 || Math.abs(bounds.y) > 1) return false;
+    if (contentBounds) {
+      const sameOrigin = contentBounds.x === bounds.x && contentBounds.y === bounds.y;
+      const sameSize = contentBounds.width === bounds.width && contentBounds.height === bounds.height;
+      if (!sameOrigin || !sameSize) 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;
+    return dpiScales.some((s) => Math.abs(scale - s) < 0.01);
+  }
+  /** 兼容旧名字。新代码用 `check`。 */
+  isFullscreen(win, display) {
+    return this.check(win, display).busy;
   }
   load() {
     if (this.mod) return Promise.resolve(this.mod);
@@ -198,7 +310,13 @@ var ArgusClient = class {
     this.config = config;
     this.version = version;
     this.hooks = hooks;
-    this.fullscreen = new FullscreenDetector(config.detectFullscreen);
+    this.fullscreen = new FullscreenDetector({
+      enabled: config.detectFullscreen,
+      // 用户传的 allowApps 与默认列表合并（用户的不区分大小写补丁是为了
+      // 不会因为忘记加常见应用而误伤）
+      allowApps: [...DEFAULT_ALLOW_APPS, ...config.allowApps],
+      busyApps: config.busyApps
+    });
   }
   static {
     __name(this, "ArgusClient");
@@ -375,18 +493,21 @@ var ArgusClient = class {
     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;
+      if (win && display) {
+        const result = this.fullscreen.check(win, display);
+        if (result.busy) {
+          logger.info(
+            `peek #${frame.id} → busy (${result.reason}): ${win.app || win.title || "fullscreen"}`
+          );
+          this.send({
+            type: "peek_busy",
+            id: frame.id,
+            app: win.app,
+            title: win.title,
+            reason: result.reason ?? "fullscreen"
+          });
+          return;
+        }
       }
     }
     const start2 = Date.now();
@@ -500,9 +621,11 @@ var HELP_TEXT = `argus-eye [options]
       --no-reconnect       禁用断线重连
       --backoff <ms>       重连最大间隔（默认 30000）
       --no-detect-fullscreen
-                           关闭"全屏即拒拍"行为（默认开启）。打开时若检测到
-                           当前焦点窗口铺满整块显示器（如全屏游戏 / 视频），
-                           则向服务端返回 peek_busy 而不是真截图。
+                           关闭"全屏即拒拍"行为（默认开启）。
+      --allow-app <name>   不视为 busy 的应用关键词（可重复）。
+                           会与默认白名单（chrome / edge / vscode / 终端 / IM 等）合并。
+      --busy-app <name>    强制视为 busy 的应用关键词（可重复），
+                           优先级高于 allow-app。例如 --busy-app valorant --busy-app csgo
       --config <path>      JSON 配置文件
       --no-color           关闭着色输出
   -h, --help               显示帮助
@@ -522,6 +645,7 @@ function parseArgs(argv) {
       version: ["v"]
     },
     string: ["server", "token", "name", "config", "format", "display"],
+    array: ["allowApp", "busyApp"],
     number: ["backoff"],
     boolean: [
       "help",
@@ -558,7 +682,9 @@ function parseArgs(argv) {
     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
+    detectFullscreen: asBoolean(parsed.detectFullscreen) ?? asBoolean(fileConfig.detectFullscreen) ?? true,
+    allowApps: asStringArray(parsed.allowApp) ?? asStringArray(fileConfig.allowApps) ?? [],
+    busyApps: asStringArray(parsed.busyApp) ?? asStringArray(fileConfig.busyApps) ?? []
   };
   if (parsed.listDisplays) {
     return {
@@ -572,7 +698,9 @@ function parseArgs(argv) {
         reconnect: merged.reconnect ?? true,
         backoff: merged.backoff ?? 3e4,
         color: merged.color ?? true,
-        detectFullscreen: merged.detectFullscreen ?? true
+        detectFullscreen: merged.detectFullscreen ?? true,
+        allowApps: merged.allowApps ?? [],
+        busyApps: merged.busyApps ?? []
       }
     };
   }
@@ -595,7 +723,9 @@ function parseArgs(argv) {
       reconnect: merged.reconnect ?? true,
       backoff: merged.backoff ?? 3e4,
       color: merged.color ?? true,
-      detectFullscreen: merged.detectFullscreen ?? true
+      detectFullscreen: merged.detectFullscreen ?? true,
+      allowApps: merged.allowApps ?? [],
+      busyApps: merged.busyApps ?? []
     }
   };
 }
@@ -656,6 +786,18 @@ function asDisplay(v) {
   return void 0;
 }
 __name(asDisplay, "asDisplay");
+function asStringArray(v) {
+  if (Array.isArray(v)) {
+    const out = v.map((x) => typeof x === "string" ? x.trim() : "").filter((x) => x.length > 0);
+    return out.length > 0 ? out : void 0;
+  }
+  if (typeof v === "string" && v.length > 0) {
+    const out = v.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    return out.length > 0 ? out : void 0;
+  }
+  return void 0;
+}
+__name(asStringArray, "asStringArray");
 
 // src/index.ts
 var require2 = createRequire(import.meta.url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argus-eye",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Argus eye —— koishi-plugin-argus 的截图客户端 CLI。",
   "author": "dingyi222666 <dingyi222666@foxmail.com>",

package/readme.md

@@ -35,10 +35,43 @@ argus-eye [options]
 
 ## 全屏检测
 
-CLI 默认开启全屏检测：当截屏时检测到当前焦点窗口铺满整块显示器（典型如全屏游戏 / 全屏视频），
+CLI 默认开启全屏检测：当截屏时检测到当前焦点窗口是**真正的全屏**（典型如全屏游戏），
 就向服务端返回一段「客户端正忙：xxx」的提示而不是真截图。
 群友看到的是程序名（"League of Legends" / "Bilibili" 等），看不到画面。
-如果你想关掉这个行为，加 `--no-detect-fullscreen`。
+
+判定规则（按优先级从高到低）：
+
+1. `--busy-app` 显式黑名单命中 → 视为忙
+2. `--allow-app` 命中（默认包含 chrome、edge、firefox、vscode、cursor、idea、
+   终端、explorer、QQ、微信、Discord、Office 等常见应用）→ 永远不忙
+3. 几何上是真全屏：起点贴 `(0, 0)`、`bounds == contentBounds`、覆盖整块显示器
+   → 视为忙
+
+第二条让最大化的 Chrome / VSCode 这种正常工作场景照常出图；
+第三条用 `bounds == contentBounds` 区分"真全屏"和"最大化"
+（最大化窗口在 Windows 上 `bounds.x = -7` 且 `contentBounds` 比 `bounds` 小一圈）。
+
+例：
+
+```bash
+# 把 valorant / csgo / lol 直接列到黑名单
+argus-eye -s ... -t ... --busy-app valorant --busy-app csgo --busy-app "league of legends"
+
+# 把"魔兽世界"也加进白名单（如果你想被群友看到）
+argus-eye -s ... -t ... --allow-app wow
+
+# 关掉这个行为
+argus-eye -s ... -t ... --no-detect-fullscreen
+```
+
+也可以写在 `~/.argus-eye.json`：
+
+```json
+{
+    "busyApps": ["valorant", "csgo", "league of legends"],
+    "allowApps": ["mygame"]
+}
+```
 
 底层使用 [`get-windows`](https://www.npmjs.com/package/get-windows)（optional dependency）。
 该包是原生 napi 模块，部分平台（Linux Wayland）不支持，加载失败时会自动降级为永远「不忙」。