koishi-plugin-argus 0.1.0

package/lib/types.d.ts

@@ -0,0 +1,75 @@
+export interface DisplayInfo {
+    id: number | string;
+    name?: string;
+    width?: number;
+    height?: number;
+    primary?: boolean;
+}
+/** Client → Server: 上线握手 */
+export interface HelloFrame {
+    type: 'hello';
+    name: string;
+    token: string;
+    version?: string;
+    displays?: DisplayInfo[];
+    defaultDisplay?: number;
+}
+/** Server → Client: 握手响应 */
+export interface HelloAckFrame {
+    type: 'hello_ack';
+    ok: boolean;
+    error?: string;
+}
+/** Server → Client: 请求一次截图 */
+export interface PeekRequestFrame {
+    type: 'peek';
+    id: string;
+    display?: number | string;
+}
+/** Client → Server: 截图结果 */
+export interface PeekResultFrame {
+    type: 'peek_result';
+    id: string;
+    /** PNG/JPEG base64（不带 data: 前缀）。*/
+    image: string;
+    mime?: string;
+    width?: number;
+    height?: number;
+    display?: number | string;
+}
+/** Client → Server: 截图失败 */
+export interface PeekErrorFrame {
+    type: 'peek_error';
+    id: string;
+    error: string;
+}
+/**
+ * Client → Server: 客户端拒绝截图（例如正在全屏游戏 / 全屏应用）。
+ * Plugin 收到此帧时不再返回截图，而是返回一段文字提示。
+ */
+export interface PeekBusyFrame {
+    type: 'peek_busy';
+    id: string;
+    /** 当前活动应用程序名（如 "League of Legends" / "explorer.exe"） */
+    app?: string;
+    /** 窗口标题 */
+    title?: string;
+    /** 自定义原因（默认 fullscreen） */
+    reason?: 'fullscreen' | string;
+}
+/** 双向心跳 */
+export interface PingFrame {
+    type: 'ping';
+    t?: number;
+}
+export interface PongFrame {
+    type: 'pong';
+    t?: number;
+}
+/** Client → Server: 优雅断线 */
+export interface ByeFrame {
+    type: 'bye';
+    reason?: string;
+}
+export type ClientFrame = HelloFrame | PeekResultFrame | PeekErrorFrame | PeekBusyFrame | PingFrame | PongFrame | ByeFrame;
+export type ServerFrame = HelloAckFrame | PeekRequestFrame | PingFrame | PongFrame;

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "koishi-plugin-argus",
+  "description": "百眼巨人 Argus：让群友通过 /peek 命令偷窥你电脑屏幕的 Koishi 插件。",
+  "version": "0.1.0",
+  "main": "lib/index.cjs",
+  "module": "lib/index.mjs",
+  "typings": "lib/index.d.ts",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.mjs",
+      "require": "./lib/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "type": "module",
+  "files": [
+    "lib",
+    "dist"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin",
+    "argus",
+    "peek",
+    "screenshot",
+    "remote"
+  ],
+  "peerDependencies": {
+    "@koishijs/plugin-server": "^3.2.7",
+    "koishi": "^4.18.9"
+  },
+  "dependencies": {
+    "@jimp/core": "^1.6.0",
+    "jimp": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.10",
+    "@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",
+    "ws": "^8.18.0",
+    "yakumo": "^1.0.0",
+    "yakumo-esbuild": "^1.0.0",
+    "yakumo-mocha": "^1.0.0",
+    "yakumo-tsc": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "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"
+  },
+  "koishi": {
+    "description": {
+      "zh": "百眼巨人 Argus：通过 /peek 命令让群友偷窥你的电脑屏幕。"
+    },
+    "service": {
+      "required": [
+        "server"
+      ]
+    }
+  },
+  "author": "dingyi222666 <dingyi222666@foxmail.com>",
+  "homepage": "https://github.com/dingyi222666/koishi-plugin-argus#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dingyi222666/koishi-plugin-argus.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dingyi222666/koishi-plugin-argus/issues"
+  }
+}

package/readme.md

@@ -0,0 +1,70 @@
+# koishi-plugin-argus
+
+> 百眼巨人 Argus —— 让群友通过 `/peek` 命令偷窥你的电脑屏幕。
+
+插件本体作为 WebSocket 服务，配套 CLI 客户端 [`argus-eye`](https://www.npmjs.com/package/argus-eye)
+连接上来后，群里就能通过命令拉取实时模糊截图。
+
+## 安装
+
+```bash
+npm i koishi-plugin-argus
+```
+
+依赖 `@koishijs/plugin-server`（需要在 koishi 配置中先启用并指定端口）。
+
+## 使用
+
+### 1. 启用插件
+
+在 koishi 中加载 `argus` 插件，至少配置 `token`：
+
+```yaml
+plugins:
+    server:
+        port: 5140
+    argus:
+        token: 'a-strong-secret'
+        path: '/argus'
+        blur: 40
+```
+
+### 2. 在你自己的电脑跑 CLI
+
+```bash
+npx argus-eye -s ws://your-koishi-host:5140/argus -t a-strong-secret -n dingyi
+```
+
+### 3. 群里偷窥
+
+```
+/peek                 # 在线只有一个客户端时直接截
+/peek dingyi          # 指定客户端
+/peek dingyi -d 1     # 指定客户端的某块显示器
+/peek dingyi -b 80    # 临时加大模糊（不能低于 minBlur）
+/peek dingyi -f       # 强制重新截图，绕过 5 分钟缓存（需要 forceAuthority）
+/peek --list          # 查看在线客户端
+/dingyi               # registerAlias=true 时的别名（等价于 /peek dingyi）
+```
+
+群友连按 `/peek` 时不会让你电脑反复截图：默认 5 分钟内的同一客户端 + 同一显示器，
+插件会复用上一次的图（消息后面带 `(缓存，剩余 4m12s)` 之类的提示）。
+如果当时正在玩全屏游戏 / 全屏视频，CLI 会直接返回程序名，群里只会看到一行
+「客户端「dingyi」正忙：League of Legends」，不会真的把画面发出去。
+
+## 配置项
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `path` | `string` | `/argus` | WebSocket 挂载路径 |
+| `token` | `string` | `''` | 客户端鉴权 token，必填 |
+| `commandName` | `string` | `peek` | 顶层命令名 |
+| `blur` | `number` | `40` | 默认模糊半径（pixel）|
+| `blurMode` | `'gaussian' \| 'fast'` | `'fast'` | 模糊算法 |
+| `minBlur` | `number` | `10` | 命令里调小模糊时不可低于此值 |
+| `maxImageBytes` | `number` | `8 * 1024 * 1024` | 单张截图大小上限 |
+| `timeout` | `number` | `15000` | 等待客户端响应超时（ms）|
+| `cacheDuration` | `number` | `300000` | 截图缓存时长（ms），默认 5 分钟，0 = 关闭缓存 |
+| `registerAlias` | `boolean` | `true` | 是否给每个客户端注册同名别名 |
+| `authority` | `number` | `1` | 命令所需权限等级 |
+| `forceAuthority` | `number` | `3` | 使用 `-f` 绕过缓存所需权限等级 |