dsh-annotator 0.5.4 → 0.5.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # dsh-annotator
2
2
 
3
- [![CI](https://github.com/ZhongqiXiao/dsh-annotator/actions/workflows/ci.yml/badge.svg)](https://github.com/ZhongqiXiao/dsh-annotator/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/dsh-annotator)](https://www.npmjs.com/package/dsh-annotator) [![node](https://img.shields.io/badge/node-%3E%3D22-339933)](https://www.npmjs.com/package/dsh-annotator) [![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/zhongqixiao/dsh-annotator)
3
+ [![CI](https://github.com/ZhongqiXiao/dsh-annotator/actions/workflows/ci.yml/badge.svg)](https://github.com/ZhongqiXiao/dsh-annotator/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/dsh-annotator)](https://www.npmjs.com/package/dsh-annotator) [![node](https://img.shields.io/badge/node-%3E%3D22-339933)](https://www.npmjs.com/package/dsh-annotator)
4
4
 
5
5
  一个 [DeepSeek Harness](https://www.deepseek.com) Desktop 插件:在**真实的 Chrome / Edge / ego lite 页面**上拾取、标注、评论、截图页面元素,并把元素定位 + 评论 + 截图一并交给 agent —— 让 agent 按照「你实际看到的页面」做前端可视化修改。
6
6
 
@@ -30,7 +30,7 @@
30
30
 
31
31
  **DSH 自带「插件」页**:侧栏 → **插件** → **添加插件**,输入准确包名 `dsh-annotator` → 安装。装完提供「立即启用」,需要重启时会提示。
32
32
 
33
- **社区插件市场**:装了 [DSH Plugin Hub](https://dsh-plugin.org)(npm 包 `dsh-plugin`)或 [dshmarket](https://dshmarket.com)(npm 包 `dshmarket`)之后,直接在市场里搜 `dsh-annotator` 安装。DSH Plugin Hub 的[插件页](https://dsh-plugin.org/plugins/zhongqixiao/dsh-annotator)上也有「复制安装命令」按钮。社区市场由第三方维护,收录不代表背书。
33
+ **社区插件市场**:[dshmarket](https://dshmarket.com)(npm 包 `dshmarket`)收录了本插件,装上之后在市场里搜 `dsh-annotator` 即可安装;插件介绍与收录页见 [awesome-dsh-plugin](https://awesome-dsh-plugin.com/zh/p/ZhongqiXiao/dsh-annotator)。社区市场由第三方维护,收录不代表背书。
34
34
 
35
35
  ### 方式 B:命令行从 npm 安装(推荐)
36
36
 
@@ -80,7 +80,7 @@ dsh web
80
80
 
81
81
  1. 打开 DSH GUI 右侧边栏的 **元素标注** 面板。
82
82
  2. 输入地址(可以像浏览器地址栏那样只写域名:`gitee.com` 自动补成 `https://gitee.com/`,`localhost:5173` 补成 `http://`,带空格的一句会当成搜索词),按需在左侧选择浏览器(选过一次就记住),点击 **启动** —— 第一次会打开所选浏览器的真实窗口,之后都接回同一个实例;新地址在同一窗口新开标签页。选 ego lite 时会优先接管你已经开着的那个 ego lite,并在其中切到「agent 空间」。
83
- 3. 开启 **拾取模式**,hover 高亮元素,点击完成拾取。
83
+ 3. 启动成功后**自动进入拾取模式**——打开新网页、切标签页、切空间也一样,不用再点一次;hover 高亮元素,点击完成拾取。面板里把开关**关掉**之后,本次会话内不会再自动开启(手动再打开即恢复自动)。
84
84
  4. 为该元素填写评论,点击卡片上的 **插入**(或底部 **全部插入(N 条)**)—— 输入框里出现引用芯片 + 元素截图附件。
85
85
  5. 插入的同时,这些标注会从列表里移除(底部提示条可 **撤销** 恢复),所以下一轮标注天然从零开始,不用手动逐条清理。
86
86
  6. 正常提交对话;agent 收到完整定位信息,随后即可对照页面修改前端代码。
@@ -132,16 +132,17 @@ dsh web
132
132
 
133
133
  ## 环境变量
134
134
 
135
- | 变量 | 作用 |
136
- | ------------------------------------------------ | ----------------------------------------------------------- |
137
- | `DSH_VISUAL_ANNOTATOR_CHROME` / `_EDGE` / `_EGO` | 覆盖对应浏览器的可执行文件路径 |
138
- | `DSH_VISUAL_ANNOTATOR_WINDOW` | 标注窗口尺寸,如 `1440x900`(DIP);不设则最大化启动 |
139
- | `DSH_VISUAL_ANNOTATOR_HEADLESS` | `1` 时无头启动,仅供插件自测 |
140
- | `DSH_VISUAL_ANNOTATOR_BROWSER_ARGS` | 额外追加给浏览器的启动开关(逃生口,平时不需要) |
141
- | `DSH_VISUAL_ANNOTATOR_SANDBOX_FALLBACK` | 设 `0` 关掉「沙箱崩溃后自动改用 `--no-sandbox` 重试一次」 |
142
- | `DSH_VISUAL_ANNOTATOR_ADOPT_RUNNING` | 设 `0` 不接管你已开着的 ego lite,改为自己起一个新实例 |
143
- | `DSH_VISUAL_ANNOTATOR_DIR` | 覆盖临时文件根目录(默认系统临时目录下的同名目录) |
144
- | `DSH_VISUAL_ANNOTATOR_CDP_URL` | 可选:改为连接该调试端点上的外部浏览器,如 `127.0.0.1:9222` |
135
+ | 变量 | 作用 |
136
+ | ------------------------------------------------ | -------------------------------------------------------------- |
137
+ | `DSH_VISUAL_ANNOTATOR_CHROME` / `_EDGE` / `_EGO` | 覆盖对应浏览器的可执行文件路径 |
138
+ | `DSH_VISUAL_ANNOTATOR_WINDOW` | 标注窗口尺寸,如 `1440x900`(DIP);不设则最大化启动 |
139
+ | `DSH_VISUAL_ANNOTATOR_HEADLESS` | `1` 时无头启动,仅供插件自测 |
140
+ | `DSH_VISUAL_ANNOTATOR_BROWSER_ARGS` | 额外追加给浏览器的启动开关(逃生口,平时不需要) |
141
+ | `DSH_VISUAL_ANNOTATOR_SANDBOX_FALLBACK` | 设 `0` 关掉「沙箱崩溃后自动改用 `--no-sandbox` 重试一次」 |
142
+ | `DSH_VISUAL_ANNOTATOR_ADOPT_RUNNING` | 设 `0` 不接管你已开着的 ego lite,改为自己起一个新实例 |
143
+ | `DSH_VISUAL_ANNOTATOR_AUTO_PICK` | 设 `0` 关掉「启动 / 打开网页自动进入标注模式」,改成每次手动开 |
144
+ | `DSH_VISUAL_ANNOTATOR_DIR` | 覆盖临时文件根目录(默认系统临时目录下的同名目录) |
145
+ | `DSH_VISUAL_ANNOTATOR_CDP_URL` | 可选:改为连接该调试端点上的外部浏览器,如 `127.0.0.1:9222` |
145
146
 
146
147
  插件**不往代码仓写文件**:浏览器 profile 与元素截图都在系统临时目录(macOS `$TMPDIR`、Linux `/tmp`、Windows `%TEMP%`)下的 `dsh-visual-annotator/`。面板带上会话 cwd 时,落点进一步细分到 `<项目名>-<cwd 哈希前 8 位>/`:不同项目各用一份 profile 与截图目录,不会串登录态,也不会互相覆盖。系统重启或临时目录清理后会自然消失,无需手动删除。
147
148
 
package/lib/session.js CHANGED
@@ -10,6 +10,7 @@ import path from 'node:path';
10
10
 
11
11
  import { CdpWs } from './cdp.js';
12
12
  import { BINDING_NAME, OVERLAY_SCRIPT } from './overlay.js';
13
+ import { decideAutoPick, nextUserTurnedOff } from './shared/auto-pick.js';
13
14
  import { classifyBindingAction } from './shared/binding-action.js';
14
15
  import {
15
16
  ADOPT_RUNNING_ENV,
@@ -198,6 +199,8 @@ export class VisualPicker {
198
199
  // 复用用户已经开着的 ego lite(见 _tryAttachRunningEgo)。默认开;测试与
199
200
  // 「别碰我日常浏览器」场景可用 DSH_VISUAL_ANNOTATOR_ADOPT_RUNNING=0 关掉。
200
201
  this.adoptRunning = options.adoptRunning ?? process.env[ADOPT_RUNNING_ENV] !== '0';
202
+ this.autoPickEnabled = process.env.DSH_VISUAL_ANNOTATOR_AUTO_PICK !== '0';
203
+ this.userTurnedOff = false;
201
204
  // 窗口与 profile 都留在磁盘上反复用:断开只丢 socket,下次 launch 按这个目录重连。
202
205
  this.windowKept = false;
203
206
  this.windowProfileDir = null;
@@ -388,6 +391,7 @@ export class VisualPicker {
388
391
  this.profilePerLaunch = false;
389
392
  this.profileDir = null;
390
393
  this.cleanProfile = cleanProfile === undefined ? null : cleanProfile === true;
394
+ this.userTurnedOff = false;
391
395
  // 截图目录要先建好:无论走「接外部窗口」还是「自己起窗口」,_capture 都写这里。
392
396
  fs.mkdirSync(path.join(this.activeBaseDir ?? this.baseDir, 'shots'), { recursive: true });
393
397
  // 没点名(旧的 /launch 调用、或面板只发 url)时用第一个装了的浏览器,
@@ -406,6 +410,7 @@ export class VisualPicker {
406
410
  this.state.status = 'ready';
407
411
  this.state.error = null;
408
412
  this._emit();
413
+ await this.setMode(decideAutoPick('launch', this), { trigger: 'auto' });
409
414
  await this._syncSpaces();
410
415
  // ego:接管来的窗口是用户自己的,插件只在独立空间里开页,不动他当前那屏。
411
416
  if (browserId === 'ego') await this._ensureAgentSpace(browserId, url);
@@ -418,6 +423,7 @@ export class VisualPicker {
418
423
  this.state.status = 'ready';
419
424
  this.state.error = null;
420
425
  this._emit();
426
+ await this.setMode(decideAutoPick('launch', this), { trigger: 'auto' });
421
427
  // 用户自己的窗口不关引导:他要是正开着「欢迎使用 ego」,关掉就是抢他的窗口。
422
428
  await this._ensureAgentSpace(browserId, url);
423
429
  return this.snapshot();
@@ -444,6 +450,7 @@ export class VisualPicker {
444
450
  // the old instance and die with "pipe closed" — the duplicate-window bug.
445
451
  if (await this._tryAdopt(profileDir, browserId)) {
446
452
  this.state.status = 'ready';
453
+ await this.setMode(decideAutoPick('launch', this), { trigger: 'auto' });
447
454
  await this._syncSpaces();
448
455
  if (browserId === 'ego') {
449
456
  await this._closeEgoOnboarding();
@@ -542,6 +549,7 @@ export class VisualPicker {
542
549
  this.state.error = null;
543
550
  this.windowKept = true;
544
551
  this.windowProfileDir = profileDir;
552
+ await this.setMode(decideAutoPick('launch', this), { trigger: 'auto' });
545
553
  await this._seedTabs();
546
554
  await this._syncSpaces();
547
555
  // ego:新手引导窗口在这时候已经弹出来了,先关掉,再把调试页开进独立空间。
@@ -570,6 +578,7 @@ export class VisualPicker {
570
578
  if (await this._tryAdopt(profileDir, browserId)) {
571
579
  this._retried = false;
572
580
  this.state.status = 'ready';
581
+ await this.setMode(decideAutoPick('launch', this), { trigger: 'auto' });
573
582
  if (url && url !== 'about:blank') await this.navigate(url);
574
583
  this._emit();
575
584
  return this.snapshot();
@@ -1007,9 +1016,19 @@ export class VisualPicker {
1007
1016
  await this._evaluate(OVERLAY_SCRIPT, sessionId).catch(() => {});
1008
1017
  await this._applyMode(sessionId).catch(() => {});
1009
1018
  await this._syncActiveTarget(targetId, sessionId);
1019
+ // 挂上时页面可能仍在导航(标题还是空的)。等它落定后各对一次真实信息;
1020
+ // 有 load 事件的会先被 _onCdpEvent 那条路径刷新,这里兜住无事件的接管场景。
1021
+ this._refreshTabLater();
1010
1022
  return sessionId;
1011
1023
  }
1012
1024
 
1025
+ _refreshTabLater() {
1026
+ for (const delay of [300, 1200]) {
1027
+ const timer = setTimeout(() => void this.refreshTabs({ force: true }).catch(() => {}), delay);
1028
+ timer.unref?.();
1029
+ }
1030
+ }
1031
+
1013
1032
  async _syncActiveTarget(targetId, sessionId) {
1014
1033
  try {
1015
1034
  const result = await this.cdp.send(
@@ -1059,6 +1078,10 @@ export class VisualPicker {
1059
1078
  }
1060
1079
  if (method === 'Page.loadEventFired') {
1061
1080
  void this._applyMode(message.sessionId);
1081
+ // 标题是页面加载后才有的:浏览器级 Target.targetInfoChanged 对新开/后台页
1082
+ // 并不保证送达(面板侧每秒 /state 轮询时靠 refreshTabs 兜住,但 host 自己没
1083
+ // 在轮询)。加载完主动对一次,标签条上的标题就不必等下一次轮询才回填。
1084
+ void this.refreshTabs({ force: true }).catch(() => {});
1062
1085
  return;
1063
1086
  }
1064
1087
  if (method === 'Target.targetCreated' || method === 'Target.targetInfoChanged') {
@@ -1285,8 +1308,12 @@ export class VisualPicker {
1285
1308
  }
1286
1309
  }
1287
1310
 
1288
- async setMode(mode) {
1289
- this.state.mode = mode === 'pick' ? 'pick' : 'off';
1311
+ async setMode(mode, options = {}) {
1312
+ const nextMode = mode === 'pick' ? 'pick' : 'off';
1313
+ if (options.trigger !== 'auto') {
1314
+ this.userTurnedOff = nextUserTurnedOff(nextMode === 'pick' ? 'user-on' : 'user-off', this.userTurnedOff);
1315
+ }
1316
+ this.state.mode = nextMode;
1290
1317
  if (this.running) await this._applyMode(null);
1291
1318
  this._emit();
1292
1319
  return this.snapshot();
@@ -1304,6 +1331,7 @@ export class VisualPicker {
1304
1331
  this.spaces.push({ id: browserContextId, name: label });
1305
1332
  this._saveSpaces();
1306
1333
  await this.useSpace(browserContextId, url);
1334
+ await this.setMode(decideAutoPick('open-page', this), { trigger: 'auto' });
1307
1335
  return this.snapshot();
1308
1336
  }
1309
1337
 
@@ -1324,6 +1352,7 @@ export class VisualPicker {
1324
1352
  const sessionId = this.attached.get(page.targetId);
1325
1353
  if (sessionId) await this._syncActiveTarget(page.targetId, sessionId);
1326
1354
  if (url && url !== 'about:blank' && page.url !== url) await this.navigate(url);
1355
+ else await this.setMode(decideAutoPick('open-page', this), { trigger: 'auto' });
1327
1356
  this._emit();
1328
1357
  return this.snapshot();
1329
1358
  }
@@ -1347,6 +1376,7 @@ export class VisualPicker {
1347
1376
  }
1348
1377
  }
1349
1378
  if (url && url !== 'about:blank') this.state.activeUrl = url;
1379
+ await this.setMode(decideAutoPick('open-page', this), { trigger: 'auto' });
1350
1380
  this._emit();
1351
1381
  await sleep(300);
1352
1382
  const sessionId = this.attached.get(created.targetId);
@@ -1401,6 +1431,7 @@ export class VisualPicker {
1401
1431
  this.activeTargetId = existing.targetId;
1402
1432
  this.state.activeUrl = existing.url ?? url;
1403
1433
  this.state.activeTitle = existing.title ?? '';
1434
+ await this.setMode(decideAutoPick('open-page', this), { trigger: 'auto' });
1404
1435
  this._emit();
1405
1436
  return this.snapshot();
1406
1437
  }
@@ -1413,6 +1444,7 @@ export class VisualPicker {
1413
1444
  await this._attach(targetId);
1414
1445
  this.activeTargetId = targetId;
1415
1446
  this.state.activeUrl = url;
1447
+ await this.setMode(decideAutoPick('open-page', this), { trigger: 'auto' });
1416
1448
  this._emit();
1417
1449
  await sleep(300);
1418
1450
  const sessionId = this.attached.get(targetId);
@@ -1430,6 +1462,7 @@ export class VisualPicker {
1430
1462
  this.activeTargetId = targetId;
1431
1463
  await this._syncActiveTarget(targetId, sessionId);
1432
1464
  }
1465
+ await this.setMode(decideAutoPick('open-page', this), { trigger: 'auto' });
1433
1466
  this._emit();
1434
1467
  return this.snapshot();
1435
1468
  }
@@ -1669,6 +1702,7 @@ export class VisualPicker {
1669
1702
  // 与运行期一致走 sync() 唯一同步口:先置 off,再由 _applyMode 广播
1670
1703
  // {mode,count};旧版 overlay 没有 sync,由 REV 接管机制兜底。
1671
1704
  this.state.mode = 'off';
1705
+ this.userTurnedOff = false;
1672
1706
  await this._applyMode(null);
1673
1707
  this.attached.clear();
1674
1708
  this.activeTargetId = null;
@@ -1718,6 +1752,7 @@ export class VisualPicker {
1718
1752
  this.activeBaseDir = null;
1719
1753
  if (this.state.status !== 'error') this.state.status = 'idle';
1720
1754
  this.state.mode = 'off';
1755
+ this.userTurnedOff = false;
1721
1756
  this._emit();
1722
1757
  return this.snapshot();
1723
1758
  }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * 自动进入标注模式的纯函数判定:host 侧只喂 trigger + 状态,不在 session 里写分支。
3
+ */
4
+
5
+ const AUTO_PICK_TRIGGERS = new Set(['launch', 'open-page']);
6
+
7
+ /**
8
+ * trigger:
9
+ * - launch: 浏览器启动成功
10
+ * - open-page: 打开网页 / 切页 / 切空间
11
+ * - user-on / user-off: 用户显式开关(用于统一判定与单测)
12
+ */
13
+ export function decideAutoPick(trigger, state = {}) {
14
+ const autoPickEnabled = state?.autoPickEnabled !== false;
15
+ const userTurnedOff = state?.userTurnedOff === true;
16
+ // 逃生阀只关「自动」,不锁用户手里的开关:user-on 是显式操作,先于它判定。
17
+ if (trigger === 'user-on') return 'pick';
18
+ if (!autoPickEnabled) return 'off';
19
+ if (trigger === 'user-off') return 'off';
20
+ if (AUTO_PICK_TRIGGERS.has(trigger)) return userTurnedOff ? 'off' : 'pick';
21
+ return 'off';
22
+ }
23
+
24
+ /** 用户手动关掉要粘住;手动再打开则恢复自动。 */
25
+ export function nextUserTurnedOff(trigger, current = false) {
26
+ if (trigger === 'user-off') return true;
27
+ if (trigger === 'user-on') return false;
28
+ return current === true;
29
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-annotator",
3
- "version": "0.5.4",
3
+ "version": "0.5.5",
4
4
  "description": "Visual element picker for DSH: highlight, annotate, comment and screenshot elements of a real Chrome/Edge page, then hand the selector + comment + shot to the agent.",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",
@@ -33,16 +33,17 @@
33
33
  },
34
34
  "scripts": {
35
35
  "test": "node --test",
36
- "test:e2e": "DSH_VISUAL_ANNOTATOR_E2E=1 DSH_VISUAL_ANNOTATOR_HEADLESS=1 DSH_VISUAL_ANNOTATOR_ADOPT_RUNNING=0 node --test --test-force-exit test/e2e-browsers.test.mjs",
36
+ "test:e2e": "DSH_VISUAL_ANNOTATOR_E2E=1 DSH_VISUAL_ANNOTATOR_HEADLESS=1 DSH_VISUAL_ANNOTATOR_ADOPT_RUNNING=0 node --test --test-concurrency=1 --test-force-exit test/e2e-browsers.test.mjs",
37
37
  "lint": "eslint .",
38
38
  "lint:fix": "eslint . --fix",
39
39
  "format": "prettier --write .",
40
40
  "format:check": "prettier --check .",
41
- "check": "node --check lib/index.js && node --check lib/session.js && node --check lib/cdp.js && node --check lib/client.js && node --check lib/overlay.js && node --check lib/shared/gui-page.js && node --check lib/shared/binding-action.js && node --check lib/shared/pick-actions.js && node --check lib/shared/scratch-dir.js && node --check lib/shared/tool-schema.js && node --check lib/shared/cdp-endpoint.js && node --check lib/shared/browsers.js && node --check lib/shared/spaces.js && node --check lib/shared/ego.js && node --check lib/shared/tabs.js && node --check lib/shared/url.js && node --check lib/shared/host-rev.js && node --check lib/shared/embedded-runtime.js && node --check scripts/check-build-sync.mjs && node --check scripts/check-embedded-runtime.mjs && node --check scripts/canary-gates.mjs && node --check scripts/assess-ai-native.mjs && node --check hooks/verify-before-finish.mjs",
41
+ "check": "node --check lib/index.js && node --check lib/session.js && node --check lib/cdp.js && node --check lib/client.js && node --check lib/overlay.js && node --check lib/shared/gui-page.js && node --check lib/shared/binding-action.js && node --check lib/shared/pick-actions.js && node --check lib/shared/auto-pick.js && node --check lib/shared/scratch-dir.js && node --check lib/shared/tool-schema.js && node --check lib/shared/cdp-endpoint.js && node --check lib/shared/browsers.js && node --check lib/shared/spaces.js && node --check lib/shared/ego.js && node --check lib/shared/tabs.js && node --check lib/shared/url.js && node --check lib/shared/host-rev.js && node --check lib/shared/embedded-runtime.js && node --check scripts/check-build-sync.mjs && node --check scripts/check-embedded-runtime.mjs && node --check scripts/canary-gates.mjs && node --check scripts/assess-ai-native.mjs && node --check scripts/mutation-test.mjs && node --check hooks/verify-before-finish.mjs",
42
42
  "gates": "node scripts/check-build-sync.mjs && node scripts/check-embedded-runtime.mjs",
43
43
  "canary": "node scripts/canary-gates.mjs",
44
44
  "assess": "node scripts/assess-ai-native.mjs",
45
45
  "assess:gate": "node scripts/assess-ai-native.mjs --min-score 80",
46
+ "mutate": "node scripts/mutation-test.mjs",
46
47
  "verify": "npm run check && npm run lint && npm run format:check && npm test && npm run gates && npm run canary"
47
48
  },
48
49
  "devDependencies": {