dsh-annotator 0.5.5 → 0.6.1

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/lib/session.js CHANGED
@@ -11,6 +11,7 @@ import path from 'node:path';
11
11
  import { CdpWs } from './cdp.js';
12
12
  import { BINDING_NAME, OVERLAY_SCRIPT } from './overlay.js';
13
13
  import { decideAutoPick, nextUserTurnedOff } from './shared/auto-pick.js';
14
+ import { annotationMarkdown } from './shared/annotation-markdown.js';
14
15
  import { classifyBindingAction } from './shared/binding-action.js';
15
16
  import {
16
17
  ADOPT_RUNNING_ENV,
@@ -29,6 +30,25 @@ import { externalCandidates, parseVersionReply } from './shared/cdp-endpoint.js'
29
30
  import { EGO_AGENT_SPACE_NAME, isEgoBrowserCommand, isEgoOnboardingTarget, listeningPortsByPid } from './shared/ego.js';
30
31
  import { advancePendingConsume, popLastPick } from './shared/pick-actions.js';
31
32
  import { isDuplicatePick, pickSignature } from './shared/pick-dedupe.js';
33
+ import {
34
+ clearPairTo,
35
+ delegationSummary,
36
+ firstUnpairedTarget,
37
+ pairAllUnpaired,
38
+ pairIdsOf,
39
+ pairTo,
40
+ setPairIds,
41
+ unpair,
42
+ unpairAll,
43
+ normalizeSpec,
44
+ pageHudInfo,
45
+ pageKeyOf,
46
+ pagePickCounts,
47
+ pickRoleOf,
48
+ refLabelOf,
49
+ refLabelsOf,
50
+ SPEC_DIMENSIONS,
51
+ } from './shared/page-roles.js';
32
52
  import { cropPng, readPngSize } from './shared/png.js';
33
53
  import { isGuiPage } from './shared/gui-page.js';
34
54
  import { scratchDir } from './shared/scratch-dir.js';
@@ -39,6 +59,7 @@ import {
39
59
  filterTabsBySpace,
40
60
  nextSpaceName,
41
61
  normalizeSpaceId,
62
+ pickDefaultContextId,
42
63
  sanitizeSpaceName,
43
64
  } from './shared/spaces.js';
44
65
 
@@ -177,9 +198,18 @@ export class VisualPicker {
177
198
  activeTitle: '',
178
199
  mode: 'off',
179
200
  picks: [],
201
+ // 页面角色表(目标 0..1 / 参考 0..5 / 中性)。pick 通过 pageKey 继承它,
202
+ // 因此改一次页面角色就能一次改写那一页所有标注,不必逐条点。
203
+ pages: [],
180
204
  // Monotonic token bumped when the in-page HUD asks the panel to insert
181
205
  // everything; the panel compares tokens so one request inserts exactly once.
182
206
  pendingConsume: 0,
207
+ // 武装落位(面板「+ 新增改动 / + 添加参照」经 /arm 下发):记录下一处标注
208
+ // 应落的栏与目标。host 收到拾取时据此判断「点到的是不是已标注的元素」,
209
+ // 是就复用那一条(改角色、按需配对),而不是再造一张同元素的重复标注卡。
210
+ arming: null,
211
+ // 最近一次「复用已标注」通知:列表不会增长,面板靠它清武装色条并提示。
212
+ reuseNotice: null,
183
213
  tabs: [],
184
214
  // 宿主自带沙箱时 Chrome 的浏览器进程会立刻 SIGTRAP;这时我们会带
185
215
  // --no-sandbox 重试一次,面板据此提示「本机浏览器在无沙箱模式下运行」。
@@ -205,6 +235,13 @@ export class VisualPicker {
205
235
  this.windowKept = false;
206
236
  this.windowProfileDir = null;
207
237
  this.attached = new Map();
238
+ // 每个标签页的标注层是否真的在里面。新标签页只靠 Target.targetCreated 挂一次,
239
+ // attach 或注入失败过一次就永久没有 HUD(用户看到的是「第二个标签页没有 HUD,
240
+ // 快捷键也没反应」),所以这里记状态,由 refreshTabs 定期补挂与补注入。
241
+ this.overlayOk = new Map();
242
+ this.preloadDone = new Set();
243
+ this.overlayTriedAt = new Map();
244
+ this.attachTriedAt = new Map();
208
245
  this.activeTargetId = null;
209
246
  // 调试空间 = Chromium BrowserContext(与 ego lite 的 task space 同一原语):
210
247
  // 同一进程、同一 profile,但 cookie / storage / 标签页各自独立。'' = 默认空间,
@@ -271,12 +308,30 @@ export class VisualPicker {
271
308
  spaceName:
272
309
  this.spaceList().find((space) => space.id === normalizeSpaceId(this.activeSpace))?.name ?? DEFAULT_SPACE_NAME,
273
310
  // 只列当前空间的标签页:另一个空间开着的页面不该出现在这一格的标签条里。
274
- tabs: filterTabsBySpace(this.state.tabs, this.activeSpace, this.defaultContextId).map((tab) => ({
311
+ tabs: filterTabsBySpace(
312
+ this.state.tabs,
313
+ this.activeSpace,
314
+ this.defaultContextId,
315
+ this.spaces.map((space) => space.id),
316
+ ).map((tab) => ({
275
317
  ...tab,
276
318
  active: tab.targetId === this.activeTargetId,
319
+ // false = 这一页里没有标注层(host 会继续重试),面板据此标一个警示点,
320
+ // 不然用户只能看到「HUD 没出来」而不明白为什么。
321
+ hud: this.overlayOk.get(tab.targetId) !== false,
277
322
  })),
323
+ // 页面条:只是标注出处(哪一页、几处、R 几)。角色不在页面上,面板
324
+ // 也不用再自己推导一遍——picks[].role 是唯一权威。
325
+ pages: this.pageList(),
326
+ // 当前活动页的 key:面板用它高亮页面条里的那一枚 chip。
327
+ activePageKey: pageKeyOf(this.state.activeUrl),
328
+ // 参考集合的确定性委托摘要(不调模型);用户可编辑后再插入。
329
+ summary: delegationSummary({ picks: this.state.picks, activeTitle: this.state.activeTitle }),
278
330
  picks: this.state.picks.map((pick) => this._publicPick(pick)),
279
331
  pendingConsume: this.state.pendingConsume,
332
+ // 武装落位与复用通知:面板据此同步色条状态、提示「点的是旧标注不是新标了一条」。
333
+ arming: this.state.arming,
334
+ reuseNotice: this.state.reuseNotice,
280
335
  // Inserted picks leave the list but stay resolvable: their chips expand at
281
336
  // submit time, which can be minutes after the insert.
282
337
  archived: this.retired.length,
@@ -308,6 +363,9 @@ export class VisualPicker {
308
363
 
309
364
  /** The one public shape of a pick, shared by /state, /pick and the agent tool. */
310
365
  _publicPick(pick) {
366
+ const pageKey = pick.pageKey || pageKeyOf(pick.url);
367
+ const role = pickRoleOf(pick);
368
+ const spec = normalizeSpec(pick.spec);
311
369
  return {
312
370
  id: pick.id,
313
371
  seq: pick.seq,
@@ -323,9 +381,81 @@ export class VisualPicker {
323
381
  ts: pick.ts,
324
382
  shotPath: pick.shotPath ?? null,
325
383
  shotUrl: pick.shotPath ? `/api/visual-annotator/shot?id=${encodeURIComponent(pick.id)}` : null,
384
+ // 参考模式:角色、参考维度、「本次包含」。角色是标注自己的字段
385
+ // (高于页面),R 编号按参照标注首次出现的页序派生,见 shared/page-roles.js。
386
+ role,
387
+ roleSource: pick.roleSource === 'user' || pick.roleSource === 'landing' ? pick.roleSource : 'auto',
388
+ pageKey,
389
+ pageTitle: pick.pageTitle ?? pick.title ?? '',
390
+ refLabel: role === 'reference' ? refLabelOf(this.state.picks, pageKey) || 'R' : '',
391
+ spec,
392
+ included: pick.included !== false,
393
+ referencedAt: pick.referencedAt ?? null,
394
+ resend: role === 'reference' && pick.included === true && Boolean(pick.referencedAt),
395
+ pageClosed: this._pageClosed(pageKey),
396
+ // 目标标注参照的全部参考:面板靠它画「这条改动下面挂着哪几条参考」。
397
+ pairIds: pairIdsOf(pick),
398
+ pairId: pick.pairId == null ? null : String(pick.pairId),
326
399
  };
327
400
  }
328
401
 
402
+ /**
403
+ * Panel-facing page list: every recorded page plus the active one. Pages carry
404
+ * provenance only (which URL, how many picks, which R-number); the role lives on
405
+ * each pick, so one page can legitimately be both 改动 and 参照 at once.
406
+ */
407
+ pageList() {
408
+ const activeKey = pageKeyOf(this.state.activeUrl);
409
+ const labels = refLabelsOf(this.state.picks);
410
+ // 计数走 shared 里那个带单测的纯函数,别再手写一遍 bucket 累加:两份口径一旦
411
+ // 分叉,症状就是标签条写 3 条、HUD 写 2 处,用户不知道该信哪个。
412
+ const shape = (page) => ({
413
+ key: page.key,
414
+ url: page.url,
415
+ title: page.title,
416
+ label: labels.get(page.key) || '',
417
+ active: page.key === activeKey,
418
+ closed: this._pageClosed(page.key),
419
+ fullShot: page.fullShotPath ? `/api/visual-annotator/pageshot?key=${encodeURIComponent(page.key)}` : null,
420
+ picks: pagePickCounts(this.state.picks, page.key),
421
+ });
422
+ const pages = this.state.pages.map(shape);
423
+ // 当前页还没标注过时也在清单里:面板据此显示「本页 0 处」,标签条与出处
424
+ // 用的是同一份地址,不需要用户再单独指定一次页面。
425
+ if (activeKey && !pages.some((page) => page.key === activeKey)) {
426
+ pages.push(shape({ key: activeKey, url: this.state.activeUrl, title: this.state.activeTitle }));
427
+ }
428
+ return pages;
429
+ }
430
+
431
+ /**
432
+ * Remember a page we have seen, so the panel can offer 设为目标/设为参考 before
433
+ * anything is annotated there. Only the active page and pages with picks are
434
+ * recorded: an untouched background tab is not part of the task yet.
435
+ */
436
+ _touchPage(url, title) {
437
+ const key = pageKeyOf(url);
438
+ if (!key) return null;
439
+ let page = this.state.pages.find((item) => item.key === key);
440
+ if (!page) {
441
+ page = { key, url: String(url ?? ''), title: String(title ?? '') };
442
+ this.state.pages.push(page);
443
+ return page;
444
+ }
445
+ if (url) page.url = String(url);
446
+ if (title) page.title = String(title);
447
+ return page;
448
+ }
449
+
450
+ /** A page counts as closed when no open tab carries its key any more. */
451
+ _pageClosed(key) {
452
+ if (!key) return false;
453
+ const open = (this.state.tabs ?? []).some((tab) => pageKeyOf(tab.url) === key);
454
+ if (open) return false;
455
+ // 浏览器没连上时 tabs 为空:那不是「页面关了」,是没在跑。
456
+ return this.state.tabs.length > 0;
457
+ }
458
+
329
459
  /**
330
460
  * Resolve one pick by id, live or already inserted. A chip inserted in round 1 is
331
461
  * still submitted later, so "not in the list" must not mean "gone".
@@ -552,6 +682,10 @@ export class VisualPicker {
552
682
  await this.setMode(decideAutoPick('launch', this), { trigger: 'auto' });
553
683
  await this._seedTabs();
554
684
  await this._syncSpaces();
685
+ // 启动那一瞬的目标会被浏览器换掉(还是 about:blank,targetId 却换了)。
686
+ // 返回 ready 之前先按真实情况对一次,别让第一个 snapshot 报出 0 或 2 个
687
+ // 标签——面板第一次渲染就建在错的数据上,用户会看到一条空的标签条。
688
+ await this.refreshTabs({ force: true }).catch(() => {});
555
689
  // ego:新手引导窗口在这时候已经弹出来了,先关掉,再把调试页开进独立空间。
556
690
  if (browserId === 'ego') {
557
691
  await this._closeEgoOnboarding();
@@ -689,6 +823,9 @@ export class VisualPicker {
689
823
  this.state.activeTitle = preferred.title ?? '';
690
824
  }
691
825
  await this._seedTabs();
826
+ // 接回来的窗口里可能留着上一轮已经关掉的标签(事件发生在断开期间),
827
+ // 同样按真实情况对一遍再报 ready。
828
+ await this.refreshTabs({ force: true }).catch(() => {});
692
829
  return true;
693
830
  } catch {
694
831
  if (this.cdp === cdp) this.cdp = null;
@@ -721,9 +858,12 @@ export class VisualPicker {
721
858
  async _syncSpaces() {
722
859
  if (!this.cdp) return;
723
860
  let contextIds = [];
861
+ let authoritative = '';
724
862
  try {
725
863
  const reply = await this.cdp.send('Target.getBrowserContexts');
726
864
  contextIds = reply?.browserContextIds ?? [];
865
+ // 新版 CDP 在这里连带给出默认空间的 context id;老版本没有这个字段。
866
+ authoritative = normalizeSpaceId(reply?.defaultBrowserContextId);
727
867
  } catch {
728
868
  return;
729
869
  }
@@ -739,17 +879,29 @@ export class VisualPicker {
739
879
  // 「空间」,再新建一个空的「agent 空间」,页面就找不回来了。
740
880
  this._loadSpaces();
741
881
  const live = new Set(contextIds.filter(Boolean));
882
+ // 默认空间的 context 绝不能当空间登记:一旦登记进 spaces,它带的页面就会
883
+ // 被「只显示当前空间」这条规则从默认空间的标签条里全部筛掉。
884
+ if (authoritative) live.delete(authoritative);
742
885
  this.spaces = this.spaces.filter((space) => live.has(space.id));
743
886
  for (const id of live) {
744
887
  if (this.spaces.some((space) => space.id === id)) continue;
745
888
  this.spaces.push({ id, name: nextSpaceName(this.spaces.map((space) => space.name)) });
746
889
  }
747
- // 默认空间的 context id 没有 API 直给,但它有两个特征:带着页面、不在
748
- // Target.getBrowserContexts 的列表里。按这个差别认,比「第一个挂上的目标」
749
- // 稳——ego 启动后会直奔 agent 空间,先挂上的往往是空间页而不是默认页。
750
- const known = new Set(this.spaces.map((space) => space.id));
751
- const fallback = targets.map((info) => normalizeSpaceId(info.browserContextId)).find((id) => id && !known.has(id));
752
- if (fallback) this.defaultContextId = fallback;
890
+ // 默认空间的 context id:优先听浏览器自己说(defaultBrowserContextId),
891
+ // 其次看用户眼前这个页面落在哪个 context。老办法「第一个不属于已知空间的
892
+ // target」不稳——真实 profile 里扩展、内部页、另一个窗口的页面各带一个
893
+ // context,认错就会把真正的页面从标签条里筛掉(见 filterTabsBySpace)。
894
+ const known = this.spaces.map((space) => space.id);
895
+ const contextOf = (info) => normalizeSpaceId(info?.browserContextId);
896
+ const activeInfo = targets.find((info) => info.targetId === this.activeTargetId);
897
+ const preferred = pickDefaultContextId({
898
+ authoritative,
899
+ activeContext: contextOf(activeInfo),
900
+ pageContexts: targets.filter((info) => info.type === 'page').map(contextOf),
901
+ targetContexts: targets.map(contextOf),
902
+ knownContexts: known,
903
+ });
904
+ if (preferred && preferred !== this.defaultContextId) this.defaultContextId = preferred;
753
905
  this._saveSpaces();
754
906
  }
755
907
 
@@ -848,6 +1000,9 @@ export class VisualPicker {
848
1000
  this.state.activeTitle = preferred.title ?? '';
849
1001
  }
850
1002
  await this._seedTabs();
1003
+ // 接回来的窗口里可能留着上一轮已经关掉的标签(事件发生在断开期间),
1004
+ // 同样按真实情况对一遍再报 ready。
1005
+ await this.refreshTabs({ force: true }).catch(() => {});
851
1006
  return true;
852
1007
  } catch {
853
1008
  return false;
@@ -1012,8 +1167,7 @@ export class VisualPicker {
1012
1167
  await this.cdp.send('Page.enable', {}, sessionId).catch(() => {});
1013
1168
  await this.cdp.send('Runtime.enable', {}, sessionId).catch(() => {});
1014
1169
  await this.cdp.send('Runtime.addBinding', { name: BINDING_NAME }, sessionId).catch(() => {});
1015
- await this.cdp.send('Page.addScriptToEvaluateOnNewDocument', { source: OVERLAY_SCRIPT }, sessionId).catch(() => {});
1016
- await this._evaluate(OVERLAY_SCRIPT, sessionId).catch(() => {});
1170
+ await this._ensureOverlay(targetId, sessionId, { preload: true });
1017
1171
  await this._applyMode(sessionId).catch(() => {});
1018
1172
  await this._syncActiveTarget(targetId, sessionId);
1019
1173
  // 挂上时页面可能仍在导航(标题还是空的)。等它落定后各对一次真实信息;
@@ -1051,6 +1205,7 @@ export class VisualPicker {
1051
1205
  this.activeTargetId = targetId;
1052
1206
  this.state.activeUrl = url;
1053
1207
  this.state.activeTitle = parsed.title ?? '';
1208
+ this._touchPage(url, parsed.title ?? '');
1054
1209
  this._emit();
1055
1210
  } catch {
1056
1211
  /* target may be navigating */
@@ -1074,9 +1229,15 @@ export class VisualPicker {
1074
1229
  else if (action === 'mode') void this.setMode(payload.mode);
1075
1230
  else if (action === 'undo') this.undoLastPick();
1076
1231
  else if (action === 'consume') this._requestConsume();
1232
+ // HUD 上的落点开关:与面板按钮同一条语义,只是入口在页面里。
1233
+ else if (action === 'landing') void this._setLandingFromPage(payload.slot);
1077
1234
  return;
1078
1235
  }
1079
1236
  if (method === 'Page.loadEventFired') {
1237
+ // 导航会换掉整个文档:preload 正常时无需做什么,preload 没挂上(新标签页
1238
+ // 第一次 attach 恰好失败)时这里是唯一能把它救回来的时机。
1239
+ const targetId = this._targetOfSession(message.sessionId);
1240
+ if (targetId) void this._ensureOverlay(targetId, message.sessionId, { preload: true }).catch(() => {});
1080
1241
  void this._applyMode(message.sessionId);
1081
1242
  // 标题是页面加载后才有的:浏览器级 Target.targetInfoChanged 对新开/后台页
1082
1243
  // 并不保证送达(面板侧每秒 /state 轮询时靠 refreshTabs 兜住,但 host 自己没
@@ -1103,6 +1264,8 @@ export class VisualPicker {
1103
1264
  const targetId = message.params?.targetId;
1104
1265
  this.state.tabs = (this.state.tabs ?? []).filter((tab) => tab.targetId !== targetId);
1105
1266
  this.attached.delete(targetId);
1267
+ this.overlayOk.delete(targetId);
1268
+ this.preloadDone.delete(targetId);
1106
1269
  if (this.activeTargetId === targetId) {
1107
1270
  this.activeTargetId = null;
1108
1271
  const rest = this.state.tabs ?? [];
@@ -1154,8 +1317,38 @@ export class VisualPicker {
1154
1317
  const fingerprint = (tabs) =>
1155
1318
  JSON.stringify((tabs ?? []).map((tab) => [tab.targetId, tab.url, tab.title, tab.contextId]));
1156
1319
  const before = fingerprint(this.state.tabs);
1320
+ // 以 getTargets 为准对一遍,除了补新的,还要删掉已经不存在的:启动那一瞬
1321
+ // 的目标常常在开「发现」之前就被销毁,事件永远不会来,只增不删就会留一个
1322
+ // 「点不开的幽灵标签」——面板显示它还在,浏览器里其实早没了。
1323
+ const alive = new Set(targetInfos.map((info) => info.targetId));
1324
+ const gone = (this.state.tabs ?? []).filter((tab) => !alive.has(tab.targetId)).map((tab) => tab.targetId);
1325
+ if (gone.length) {
1326
+ this.state.tabs = (this.state.tabs ?? []).filter((tab) => alive.has(tab.targetId));
1327
+ for (const targetId of gone) {
1328
+ this.attached.delete(targetId);
1329
+ this.overlayOk.delete(targetId);
1330
+ this.preloadDone.delete(targetId);
1331
+ this.attachTriedAt.delete(targetId);
1332
+ if (this.activeTargetId === targetId) this.activeTargetId = null;
1333
+ }
1334
+ }
1157
1335
  for (const info of targetInfos) this._upsertTab(info, { emit: false });
1158
1336
  if (before !== fingerprint(this.state.tabs)) this._emit();
1337
+ // 新标签页原本只有 Target.targetCreated 一条命:事件漏了、或那一次 attach /
1338
+ // 注入失败,这个页就永远没有 HUD。轮询(面板每秒 /state)时补挂与补注入。
1339
+ for (const info of targetInfos) {
1340
+ if (!this.attached.has(info.targetId)) {
1341
+ if (now - (this.attachTriedAt.get(info.targetId) ?? 0) < 1500) continue;
1342
+ this.attachTriedAt.set(info.targetId, now);
1343
+ void this._attach(info.targetId).catch(() => {});
1344
+ continue;
1345
+ }
1346
+ if (this.overlayOk.get(info.targetId) !== false) continue;
1347
+ if (now - (this.overlayTriedAt.get(info.targetId) ?? 0) < 1500) continue;
1348
+ this.overlayTriedAt.set(info.targetId, now);
1349
+ const sid = this.attached.get(info.targetId);
1350
+ void this._ensureOverlay(info.targetId, sid, { preload: true }).catch(() => {});
1351
+ }
1159
1352
  }
1160
1353
 
1161
1354
  /** Pages that already exist when we connect never fire targetCreated. */
@@ -1178,17 +1371,142 @@ export class VisualPicker {
1178
1371
  return this.cdp.send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: false }, sessionId);
1179
1372
  }
1180
1373
 
1181
- async _applyMode(sessionId) {
1374
+ /**
1375
+ * 页面自己知道自己是不是参考页:这里按「这个标签页的 URL」算角色。
1376
+ * 用 activeUrl 算的话,后台那个参考页会被推成目标页(文案「怎么改」、也没有蓝色
1377
+ * 参考徽标),用户在同一套 HUD 上就会去改参考页。
1378
+ */
1379
+ async _applyMode(sessionId = null, url = null) {
1182
1380
  if (!this.cdp) return;
1183
- // sync() 是 host -> page 的唯一同步口:mode 加上当前已标注数一起推。
1184
- const info = JSON.stringify({ mode: this.state.mode, count: this.state.picks.length });
1185
- const expression = `window.__DSH_VP__ && window.__DSH_VP__.sync(${info})`;
1186
- if (sessionId) await this._evaluate(expression, sessionId).catch(() => {});
1187
- else for (const sid of this.attached.values()) await this._evaluate(expression, sid).catch(() => {});
1381
+ // 提示词只算一次:整份标注是同一份,逐个标签页重复生成只是白烧 CPU。
1382
+ const prompt = this.toMarkdown();
1383
+ const entries = sessionId ? [[this._targetOfSession(sessionId), sessionId]] : [...this.attached.entries()];
1384
+ for (const [targetId, sid] of entries) {
1385
+ if (!sid) continue;
1386
+ const info = JSON.stringify(
1387
+ pageHudInfo({
1388
+ url: url ?? this._urlOfTarget(targetId),
1389
+ picks: this.state.picks,
1390
+ // 落点决定「下一处会进哪一栏」,不是页面的多数票:HUD 说的是
1391
+ // 用户现在点下去会发生什么。
1392
+ landing: this.state.arming?.slot ?? null,
1393
+ mode: this.state.mode,
1394
+ specs: SPEC_DIMENSIONS,
1395
+ prompt,
1396
+ }),
1397
+ );
1398
+ await this._evaluate(`window.__DSH_VP__ && window.__DSH_VP__.sync(${info})`, sid).catch(() => {});
1399
+ }
1400
+ }
1401
+
1402
+ /** Which tab a session belongs to (reverse of this.attached). */
1403
+ _targetOfSession(sessionId) {
1404
+ for (const [targetId, sid] of this.attached) if (sid === sessionId) return targetId;
1405
+ return null;
1406
+ }
1407
+
1408
+ /** A tab's own address; falls back to the active page so unknown tabs keep old behaviour. */
1409
+ _urlOfTarget(targetId) {
1410
+ const tab = (this.state.tabs ?? []).find((item) => item.targetId === targetId);
1411
+ return tab?.url || this.state.activeUrl;
1412
+ }
1413
+
1414
+ /**
1415
+ * Make sure this tab really has the overlay: probe, and if it is missing inject and
1416
+ * probe again. A swallowed failure here used to leave the tab permanently dead —
1417
+ * no HUD, no ⌥A — with nothing in the panel saying why.
1418
+ */
1419
+ async _ensureOverlay(targetId, sessionId, { preload = false } = {}) {
1420
+ if (!sessionId) return false;
1421
+ const probe = () =>
1422
+ this._evaluate(
1423
+ "JSON.stringify({vp: typeof window.__DSH_VP__, hud: !!document.getElementById('__dsh-vp-root')})",
1424
+ sessionId,
1425
+ );
1426
+ try {
1427
+ if (preload && !this.preloadDone.has(targetId)) {
1428
+ await this.cdp.send('Page.addScriptToEvaluateOnNewDocument', { source: OVERLAY_SCRIPT }, sessionId);
1429
+ this.preloadDone.add(targetId);
1430
+ }
1431
+ const first = await probe();
1432
+ const seen = JSON.parse(first?.result?.value ?? '{}');
1433
+ if (seen.vp === 'object') {
1434
+ // 脚本在、挂载点没了(页面自己清了 body)时补一次挂载即可,别整段重注入。
1435
+ if (!seen.hud)
1436
+ await this._evaluate(
1437
+ 'window.__DSH_VP__ && window.__DSH_VP__.reattach && window.__DSH_VP__.reattach()',
1438
+ sessionId,
1439
+ );
1440
+ this._markOverlay(targetId, true);
1441
+ return true;
1442
+ }
1443
+ await this._evaluate(OVERLAY_SCRIPT, sessionId);
1444
+ const again = await probe();
1445
+ const ok = JSON.parse(again?.result?.value ?? '{}').vp === 'object';
1446
+ this._markOverlay(targetId, ok);
1447
+ return ok;
1448
+ } catch {
1449
+ this._markOverlay(targetId, false);
1450
+ return false;
1451
+ }
1452
+ }
1453
+
1454
+ _markOverlay(targetId, ok) {
1455
+ if (!targetId) return;
1456
+ const before = this.overlayOk.get(targetId);
1457
+ this.overlayOk.set(targetId, ok);
1458
+ if (ok && before === false) this.log?.('info', `标签页 ${targetId} 的标注层已补上`);
1459
+ if (!ok && before !== false) this.log?.('warn', `标签页 ${targetId} 注入标注层失败,面板会继续重试`);
1460
+ }
1461
+
1462
+ /**
1463
+ * 当前落点:面板点过「+ 新增改动 / + 添加参照」后一直有效,直到再点一次取消
1464
+ * (或 10 分钟没动静自己过期)。落点就是「下一处标注进哪一栏」,与页面无关。
1465
+ */
1466
+ _landing() {
1467
+ const arming = this.state.arming;
1468
+ if (!arming) return null;
1469
+ if (Date.now() - (Number(arming.ts) || 0) > 10 * 60 * 1000) {
1470
+ // 过期也要广播:直接清 state 的话,面板的落点色条与 HUD 的颜色会一直亮到
1471
+ // 下一次快照,用户点下去才发现落点其实已经回落到「改动」。
1472
+ this.setArming(null);
1473
+ return null;
1474
+ }
1475
+ return arming;
1476
+ }
1477
+
1478
+ /**
1479
+ * 刚落的一处参照归到哪条改动:面板上点「+ 添加参照」的那张改动卡优先
1480
+ * (pairId 只生效一次),否则配给第一条还没配对的改动。边标边配,不用再点第二下。
1481
+ */
1482
+ _pairFreshReference(role, pickId, landing) {
1483
+ if (role !== 'reference') return;
1484
+ const wanted = String(landing?.pairId ?? '');
1485
+ if (wanted) {
1486
+ this.setPair(wanted, pickId, { move: true });
1487
+ return;
1488
+ }
1489
+ const partner = firstUnpairedTarget(this.state.picks);
1490
+ if (partner && String(partner.id) !== String(pickId)) pairTo(this.state.picks, partner.id, pickId);
1491
+ }
1492
+
1493
+ /** 落点粘住(连续标多处都进同一栏);只有「配给某条改动」是一次性的。 */
1494
+ _settleLanding() {
1495
+ if (!this.state.arming) return;
1496
+ this.state.arming = { ...this.state.arming, pairId: '', ts: Date.now() };
1188
1497
  }
1189
1498
 
1190
1499
  async _recordPick(payload, sessionId) {
1191
1500
  const id = 'p' + ++this.seq;
1501
+ const url = payload.url ?? this.state.activeUrl;
1502
+ const title = payload.title ?? this.state.activeTitle;
1503
+ const page = this._touchPage(url, title);
1504
+ const pageKey = pageKeyOf(url);
1505
+ // 角色在这里当场定:面板上的落点(「+ 新增改动 / + 添加参照」)说了算,
1506
+ // 没有落点就是改动。页面只是出处,不再决定标注去哪一栏——按页面推、再由
1507
+ // 面板事后纠正,页签一多必然对不上,用户看到的就是「选的页签和标注不符」。
1508
+ const landing = this._landing();
1509
+ const role = landing ? landing.slot : 'target';
1192
1510
  const pick = {
1193
1511
  id,
1194
1512
  seq: payload.seq ?? this.seq,
@@ -1199,11 +1517,22 @@ export class VisualPicker {
1199
1517
  html: payload.html ?? '',
1200
1518
  rect: payload.rect ?? null,
1201
1519
  pageRect: payload.pageRect ?? null,
1202
- url: payload.url ?? this.state.activeUrl,
1203
- title: payload.title ?? this.state.activeTitle,
1520
+ url,
1521
+ title,
1204
1522
  ts: Date.now(),
1205
1523
  shotPath: null,
1206
1524
  sessionId,
1525
+ role,
1526
+ roleSource: landing ? 'landing' : 'auto',
1527
+ pageKey,
1528
+ pageTitle: page?.title || title || '',
1529
+ spec: normalizeSpec(payload.spec),
1530
+ included: true,
1531
+ referencedAt: null,
1532
+ // 目标标注参照哪几条参考标注(参考对照视图里挂在同一条目标下面)。
1533
+ // pairId 是 pairIds 的第一条,agent 工具契约只认它。
1534
+ pairIds: [],
1535
+ pairId: null,
1207
1536
  };
1208
1537
  // 页面脚本一次提交只应发一份,但旧版/多份注入脚本会让同一次提交投递多次,
1209
1538
  // 列表里就成了「三条一模一样的标注」。判重规则见 lib/shared/pick-dedupe.js。
@@ -1212,7 +1541,28 @@ export class VisualPicker {
1212
1541
  if (isDuplicatePick({ signature: this.lastPickSignature, at: this.lastPickAt }, signature, now)) return;
1213
1542
  this.lastPickSignature = signature;
1214
1543
  this.lastPickAt = now;
1544
+ // 落点落在已经标过的元素上:复用那一条(改角色、按需配对),不再造一张
1545
+ // 同元素的重复标注卡。「改动也可以参照已标注的元素」——重复标一遍只会多出
1546
+ // 一张一模一样的卡,不是用户要的。同元素判定=同一页 + 同一选择器。
1547
+ if (landing) {
1548
+ const existing = this.state.picks.find(
1549
+ (candidate) =>
1550
+ (candidate.pageKey || pageKeyOf(candidate.url)) === pageKey &&
1551
+ String(candidate.selector ?? '') === String(payload.selector ?? ''),
1552
+ );
1553
+ if (existing) {
1554
+ if (existing.role !== role) this.setPickRole(existing.id, role);
1555
+ this._pairFreshReference(role, existing.id, landing);
1556
+ if (String(payload.comment ?? '').trim()) this.setComment(existing.id, payload.comment);
1557
+ this._settleLanding();
1558
+ this.state.reuseNotice = { pickId: existing.id, role, ts: Date.now() };
1559
+ this._emit();
1560
+ return this.snapshot();
1561
+ }
1562
+ }
1215
1563
  this.state.picks.push(pick);
1564
+ this._pairFreshReference(role, pick.id, landing);
1565
+ this._settleLanding();
1216
1566
  if (payload.title) this.state.activeTitle = payload.title;
1217
1567
  if (payload.url) this.state.activeUrl = payload.url;
1218
1568
  this._emit();
@@ -1508,6 +1858,8 @@ export class VisualPicker {
1508
1858
  const index = this.state.picks.findIndex((pick) => pick.id === id);
1509
1859
  if (index < 0) return this.snapshot();
1510
1860
  const [removed] = this.state.picks.splice(index, 1);
1861
+ // 删掉的可能是一条参考:指向它的目标会留下悬空 pairId,一并解开。
1862
+ clearPairTo(this.state.picks, removed.id);
1511
1863
  await this._afterRemoval([removed], false);
1512
1864
  return this.snapshot();
1513
1865
  }
@@ -1518,6 +1870,7 @@ export class VisualPicker {
1518
1870
  const popped = popLastPick(this.state.picks);
1519
1871
  if (!popped) return this.snapshot();
1520
1872
  this.state.picks = popped.remaining;
1873
+ clearPairTo(this.state.picks, popped.removed.id);
1521
1874
  await this._afterRemoval([popped.removed], false);
1522
1875
  return this.snapshot();
1523
1876
  }
@@ -1539,16 +1892,30 @@ export class VisualPicker {
1539
1892
  */
1540
1893
  async consumePicks(ids) {
1541
1894
  const wanted = new Set((Array.isArray(ids) ? ids : []).map(String));
1542
- if (!wanted.size) return { ...this.snapshot(), consumed: 0 };
1895
+ if (!wanted.size) return { ...this.snapshot(), consumed: 0, referenced: 0 };
1543
1896
  const removed = [];
1544
- this.state.picks = this.state.picks.filter((pick) => {
1545
- if (!wanted.has(String(pick.id))) return true;
1897
+ // 参考标注插入后不离开列表:它们是可复用的只读规范,下次还可能再发。
1898
+ // 记录插入前的 included/referencedAt 快照,撤销一次插入要连这两个字段一起还原。
1899
+ const referenced = [];
1900
+ const keep = [];
1901
+ for (const pick of this.state.picks) {
1902
+ if (!wanted.has(String(pick.id))) {
1903
+ keep.push(pick);
1904
+ continue;
1905
+ }
1906
+ if (pickRoleOf(pick) === 'reference') {
1907
+ referenced.push({ pick, included: pick.included !== false, referencedAt: pick.referencedAt ?? null });
1908
+ pick.included = false;
1909
+ pick.referencedAt = Date.now();
1910
+ keep.push(pick);
1911
+ continue;
1912
+ }
1546
1913
  removed.push(pick);
1547
- return false;
1548
- });
1549
- if (!removed.length) return { ...this.snapshot(), consumed: 0 };
1550
- await this._afterRemoval(removed, true);
1551
- return { ...this.snapshot(), consumed: removed.length };
1914
+ }
1915
+ this.state.picks = keep;
1916
+ if (!removed.length && !referenced.length) return { ...this.snapshot(), consumed: 0, referenced: 0 };
1917
+ await this._afterRemoval(removed, true, { referenced });
1918
+ return { ...this.snapshot(), consumed: removed.length, referenced: referenced.length };
1552
1919
  }
1553
1920
 
1554
1921
  /**
@@ -1570,13 +1937,14 @@ export class VisualPicker {
1570
1937
  * 截图本身不删;否则(单条移除/撤销)截图留在槽里供 restore 用。被顶掉的旧槽
1571
1938
  * 截图无论如何都删——它已不可恢复。
1572
1939
  */
1573
- async _afterRemoval(removed, archive) {
1940
+ async _afterRemoval(removed, archive, extra = {}) {
1574
1941
  if (this.lastRemoved) for (const pick of this.lastRemoved.picks) this._deleteShot(pick);
1942
+ const referenced = extra.referenced ?? [];
1575
1943
  if (archive) {
1576
1944
  this._archive(removed);
1577
- this.lastRemoved = { picks: removed };
1945
+ this.lastRemoved = { picks: removed, referenced };
1578
1946
  } else {
1579
- this.lastRemoved = removed.length ? { picks: removed } : null;
1947
+ this.lastRemoved = removed.length ? { picks: removed, referenced } : null;
1580
1948
  }
1581
1949
  this._emit();
1582
1950
  await this._applyMode(null);
@@ -1587,6 +1955,14 @@ export class VisualPicker {
1587
1955
  const entry = this.lastRemoved;
1588
1956
  if (!entry) return { ...this.snapshot(), restored: 0 };
1589
1957
  this.lastRemoved = null;
1958
+ // 参考插入只是改了 included/referencedAt,标注本身还在列表里:先还原这两个
1959
+ // 字段,撤销一次「3 参考 + 2 目标」的插入才是完整复原。
1960
+ for (const item of entry.referenced ?? []) {
1961
+ const pick = this.state.picks.find((candidate) => candidate.id === item.pick.id);
1962
+ if (!pick) continue;
1963
+ pick.included = item.included;
1964
+ pick.referencedAt = item.referencedAt;
1965
+ }
1590
1966
  for (const pick of entry.picks) {
1591
1967
  let index = this.state.picks.length;
1592
1968
  for (let i = 0; i < this.state.picks.length; i++) {
@@ -1605,7 +1981,7 @@ export class VisualPicker {
1605
1981
  }
1606
1982
  this._emit();
1607
1983
  void this._applyMode(null);
1608
- return { ...this.snapshot(), restored: entry.picks.length };
1984
+ return { ...this.snapshot(), restored: entry.picks.length + (entry.referenced?.length ?? 0) };
1609
1985
  }
1610
1986
 
1611
1987
  _deleteShot(pick) {
@@ -1624,47 +2000,217 @@ export class VisualPicker {
1624
2000
  return this.snapshot();
1625
2001
  }
1626
2002
 
2003
+ /**
2004
+ * 换一条标注的角色:拖到另一栏、或落点落在一条已标过的元素上时走这里。
2005
+ * roleSource='user' 记录「这是用户亲手定的」,之后换落点不会动它。
2006
+ */
2007
+ setPickRole(id, role) {
2008
+ const pick = this.state.picks.find((item) => item.id === String(id ?? ''));
2009
+ if (!pick || (role !== 'target' && role !== 'reference'))
2010
+ return { ok: false, error: 'bad-pick-role', ...this.snapshot() };
2011
+ // 换角色等于换一侧:它自己挂在谁下面的关系先断,别人挂在它下面的关系也要断,
2012
+ // 否则会留下一条「目标参照一条目标」或指向不存在参考的悬空配对。
2013
+ if (pick.role !== role) setPairIds(pick, []);
2014
+ pick.role = role;
2015
+ pick.roleSource = 'user';
2016
+ if (role === 'target') pick.referencedAt = null;
2017
+ if (role === 'target') clearPairTo(this.state.picks, pick.id);
2018
+ this._emit();
2019
+ return { ok: true, ...this.snapshot() };
2020
+ }
2021
+
2022
+ /**
2023
+ * 配对:把一条参考标注挂到一条目标标注上(refId 传空=这条目标的参考全解开)。
2024
+ * 改一处可以参照多处(版式照 A、配色照 B),所以这里是追加而不是覆盖;
2025
+ * 已经挂着的重复挂不报错,拖拽来回放不会产生重复行。
2026
+ */
2027
+ setPair(targetId, refId, options = {}) {
2028
+ const target = this.state.picks.find((item) => item.id === String(targetId ?? ''));
2029
+ if (!target) return { ok: false, error: 'pick-not-found', ...this.snapshot() };
2030
+ if (refId === null || refId === undefined || refId === '') {
2031
+ unpairAll(this.state.picks, target.id);
2032
+ this._emit();
2033
+ return { ok: true, ...this.snapshot() };
2034
+ }
2035
+ const ref = this.state.picks.find((item) => item.id === String(refId));
2036
+ if (!ref || pickRoleOf(ref) !== 'reference')
2037
+ return { ok: false, error: 'bad-pair', message: '只有归到参照栏的标注才能挂到改动上', ...this.snapshot() };
2038
+ if (String(ref.id) === String(target.id))
2039
+ return { ok: false, error: 'bad-pair', message: '一条标注不能参照它自己', ...this.snapshot() };
2040
+ // move:这条参考只归这一条目标。落点标注时用——host 已经把它自动配给了
2041
+ // 「第一条没配的目标」,用户点的那一行才是真正的落点。
2042
+ if (options?.move) {
2043
+ for (const other of this.state.picks)
2044
+ if (String(other.id) !== String(target.id)) unpair(this.state.picks, other.id, ref.id);
2045
+ }
2046
+ pairTo(this.state.picks, target.id, ref.id);
2047
+ this._emit();
2048
+ return { ok: true, ...this.snapshot() };
2049
+ }
2050
+
2051
+ /** 只解开一条:右栏参考卡上的小 ×(其余参考还挂在这条目标上)。 */
2052
+ unpair(targetId, refId) {
2053
+ const target = this.state.picks.find((item) => item.id === String(targetId ?? ''));
2054
+ if (!target) return { ok: false, error: 'pick-not-found', ...this.snapshot() };
2055
+ unpair(this.state.picks, target.id, refId);
2056
+ this._emit();
2057
+ return { ok: true, ...this.snapshot() };
2058
+ }
2059
+
2060
+ /** 一条目标现在参照了哪几条参考(面板拖拽后刷新用)。 */
2061
+ pairStats() {
2062
+ const counts = new Map();
2063
+ for (const pick of this.state.picks) for (const id of pairIdsOf(pick)) counts.set(id, (counts.get(id) ?? 0) + 1);
2064
+ return counts;
2065
+ }
2066
+
2067
+ /**
2068
+ * 一条参考套用到所有还没配对的目标:同一条规范(配色、圆角)常常要落到好几处,
2069
+ * 逐条点下拉太慢。已经配过的目标不覆盖——那可能是用户特意挑的另一条参考。
2070
+ */
2071
+ pairAll(refId) {
2072
+ const ref = this.state.picks.find((item) => item.id === String(refId ?? ''));
2073
+ if (!ref || pickRoleOf(ref) !== 'reference')
2074
+ return { ok: false, error: 'bad-pair', message: '只有归到参照栏的标注才能挂到改动上', ...this.snapshot() };
2075
+ const touched = pairAllUnpaired(this.state.picks, ref.id);
2076
+ this._emit();
2077
+ return { ok: true, paired: touched.length, ...this.snapshot() };
2078
+ }
2079
+
2080
+ /**
2081
+ * 落点由面板经 /arm 下发(slot=target/reference,传 null 取消)。host 有两处用它:
2082
+ * 新标注当场归哪一栏,以及拾取落在已标过的元素上时该复用哪一栏。落点是粘性的,
2083
+ * 所以「连续标五处参照」只需要点一次按钮;pairId 只对下一处生效。
2084
+ */
2085
+ setArming(arming) {
2086
+ if (!arming || (arming.slot !== 'target' && arming.slot !== 'reference')) {
2087
+ this.state.arming = null;
2088
+ void this._applyMode(null);
2089
+ this._emit();
2090
+ return;
2091
+ }
2092
+ this.state.arming = { slot: arming.slot, pairId: arming.pairId ? String(arming.pairId) : '', ts: Date.now() };
2093
+ // 落点一变就得推给页面:HUD 的颜色与措辞说的就是「下一处进哪一栏」,不推的话
2094
+ // 用户在参照落点上仍看到橙色的「改动」,标下去就以为落错了栏。
2095
+ void this._applyMode(null);
2096
+ this._emit();
2097
+ }
2098
+
2099
+ /**
2100
+ * 页面 HUD 上的一键切换(⌥R / 点「改动·参照」开关)。换的只是下一处落点,
2101
+ * 顺手进标注模式:按这个键的人下一步就是点元素,不该再让他回面板开一次。
2102
+ */
2103
+ async _setLandingFromPage(slot) {
2104
+ this.setArming({ slot });
2105
+ if (this.state.mode !== 'pick') await this.setMode('pick');
2106
+ }
2107
+
2108
+ /** 「本次包含」:只有勾着的标注会被插入;参考插入后自动取消,重勾=重发。 */
2109
+ setPickInclude(id, included) {
2110
+ const pick = this.state.picks.find((item) => item.id === String(id ?? ''));
2111
+ if (!pick) return { ok: false, error: 'pick-not-found', ...this.snapshot() };
2112
+ pick.included = Boolean(included);
2113
+ this._emit();
2114
+ return { ok: true, ...this.snapshot() };
2115
+ }
2116
+
2117
+ /** 参考维度:布局/间距/配色/字体/字号/圆角/交互/文案,可多选。 */
2118
+ setPickSpec(id, spec) {
2119
+ const pick = this.state.picks.find((item) => item.id === String(id ?? ''));
2120
+ if (!pick) return { ok: false, error: 'pick-not-found', ...this.snapshot() };
2121
+ pick.spec = normalizeSpec(spec);
2122
+ this._emit();
2123
+ return { ok: true, ...this.snapshot() };
2124
+ }
2125
+
1627
2126
  /**
1628
2127
  * One-click clear. Picks move to the archive (chips still resolve) and stay
1629
2128
  * restorable as one batch, screenshots included, until the undo slot is
1630
2129
  * replaced or the window closes. Nothing to clear leaves the archive alone.
1631
2130
  */
1632
- async clear() {
1633
- const cleared = this.state.picks.slice();
2131
+ async clear(scope = 'all') {
2132
+ // 「清空」分三个口:目标(插入即消费,清空是补救)/ 参考(复用集清理)/ 全部。
2133
+ const wanted = scope === 'target' || scope === 'reference' ? scope : 'all';
2134
+ const match = (pick) => wanted === 'all' || pickRoleOf(pick) === wanted;
2135
+ const cleared = this.state.picks.filter(match);
1634
2136
  if (!cleared.length) return { ...this.snapshot(), cleared: 0 };
1635
- this.state.picks = [];
2137
+ this.state.picks = this.state.picks.filter((pick) => !match(pick));
2138
+ for (const gone of cleared) clearPairTo(this.state.picks, gone.id);
1636
2139
  await this._afterRemoval(cleared, true);
1637
2140
  return { ...this.snapshot(), cleared: cleared.length };
1638
2141
  }
1639
2142
 
1640
2143
  shotFile(id) {
1641
- const pick = this.state.picks.find((item) => item.id === id);
2144
+ const pick = this.state.picks.find((item) => item.id === id) ?? this.retired.find((item) => item.id === id);
1642
2145
  return pick?.shotPath && fs.existsSync(pick.shotPath) ? pick.shotPath : null;
1643
2146
  }
1644
2147
 
1645
- /** Markdown the panel injects into the composer / the agent tool returns. */
1646
- toMarkdown() {
1647
- const picks = this.state.picks;
1648
- if (!picks.length) return '(当前还没有页面元素标注)';
1649
- const lines = [];
1650
- lines.push(
1651
- `页面元素标注(${picks.length} 处,来源 ${this.state.browser ?? 'browser'}:${this.state.activeUrl || '未知页面'})`,
2148
+ /**
2149
+ * 整页截图,按需触发(对比层的「整页」视图)。元素裁剪图只截视口,元素滚动出
2150
+ * 视口就没有图;整页图要撑视口,用户会看到一次重排,所以绝不自动做,只由面板
2151
+ * 按下「整页」时调一次,失败也让面板显示「重试」而不是默默空着。
2152
+ */
2153
+ async capturePageShot(key) {
2154
+ if (!this.running) throw new Error('浏览器未运行');
2155
+ const wanted = String(key ?? '') || pageKeyOf(this.state.activeUrl);
2156
+ const page = this.state.pages.find((item) => item.key === wanted);
2157
+ if (!page) throw new Error('页面不在任务里');
2158
+ let targetId = null;
2159
+ for (const tid of this.attached.keys()) {
2160
+ const tab = (this.state.tabs ?? []).find((item) => item.targetId === tid);
2161
+ if (tab && pageKeyOf(tab.url) === wanted) {
2162
+ targetId = tid;
2163
+ break;
2164
+ }
2165
+ }
2166
+ if (!targetId) throw new Error('页面已关闭');
2167
+ let sessionId = this.attached.get(targetId);
2168
+ if (!sessionId) sessionId = await this._attach(targetId).catch(() => null);
2169
+ if (!sessionId) throw new Error('无法连接该页面');
2170
+ const metrics = await this.cdp.send('Page.getLayoutMetrics', {}, sessionId).catch(() => null);
2171
+ const size = metrics?.cssContentSize ?? metrics?.contentSize;
2172
+ if (!size || !(size.width > 0) || !(size.height > 0)) throw new Error('拿不到页面尺寸');
2173
+ const result = await this.cdp.send(
2174
+ 'Page.captureScreenshot',
2175
+ {
2176
+ format: 'png',
2177
+ captureBeyondViewport: true,
2178
+ fromSurface: true,
2179
+ clip: { x: 0, y: 0, width: Math.ceil(size.width), height: Math.ceil(size.height), scale: 1 },
2180
+ },
2181
+ sessionId,
1652
2182
  );
1653
- picks.forEach((pick, index) => {
1654
- lines.push('');
1655
- lines.push(
1656
- `${index + 1}. \`${pick.selector || pick.tag}\` — ${pick.tag}${pick.text ? `:${pick.text.replace(/\s+/g, ' ').slice(0, 80)}` : ''}`,
1657
- );
1658
- if (pick.url) lines.push(` 页面:${pick.url}`);
1659
- if (pick.pageRect)
1660
- lines.push(
1661
- ` 位置:x=${Math.round(pick.pageRect.x)} y=${Math.round(pick.pageRect.y)} ${Math.round(pick.pageRect.width)}×${Math.round(pick.pageRect.height)}`,
1662
- );
1663
- if (pick.comment) lines.push(` 评论:${pick.comment}`);
1664
- if (pick.html) lines.push(' HTML:' + ' `' + pick.html.replace(/\s+/g, ' ').slice(0, 300) + '`');
1665
- if (pick.shotPath) lines.push(` 截图:${pick.shotPath}`);
2183
+ if (!result?.data) throw new Error('整页截图失败');
2184
+ const dir = path.join(this.activeBaseDir ?? this.baseDir, 'page-shots');
2185
+ fs.mkdirSync(dir, { recursive: true });
2186
+ // 文件名由 pageKey 派生:同一页重复截只覆盖这一张,不在临时目录里堆垃圾。
2187
+ const name = Buffer.from(wanted).toString('base64url').slice(0, 48);
2188
+ const file = path.join(dir, name + '.png');
2189
+ fs.writeFileSync(file, Buffer.from(result.data, 'base64'));
2190
+ page.fullShotPath = file;
2191
+ this._emit();
2192
+ return {
2193
+ ok: true,
2194
+ key: wanted,
2195
+ fullShot: `/api/visual-annotator/pageshot?key=${encodeURIComponent(wanted)}`,
2196
+ };
2197
+ }
2198
+
2199
+ pageShotFile(key) {
2200
+ const page = this.state.pages.find((item) => item.key === String(key ?? ''));
2201
+ return page?.fullShotPath && fs.existsSync(page.fullShotPath) ? page.fullShotPath : null;
2202
+ }
2203
+
2204
+ /**
2205
+ * Markdown the panel injects into the composer / the agent tool returns.
2206
+ * 与工具输出共用 lib/shared/annotation-markdown.js:两处各写一份时,面板那份曾经
2207
+ * 漏掉「参照:」行,粘到别的 agent 里的提示词就丢了改动↔参照的对照关系。
2208
+ */
2209
+ toMarkdown() {
2210
+ return annotationMarkdown(this.state.picks, {
2211
+ empty: '(当前还没有页面元素标注)',
2212
+ source: `${this.state.browser ?? 'browser'}:${this.state.activeUrl || '未知页面'}`,
1666
2213
  });
1667
- return lines.join('\n');
1668
2214
  }
1669
2215
 
1670
2216
  /** Delete the browser profile when policy allows; shared/reused profiles survive. */
@@ -1699,6 +2245,8 @@ export class VisualPicker {
1699
2245
  }
1700
2246
  for (const pick of this.retired) this._deleteShot(pick);
1701
2247
  this.retired = [];
2248
+ // 页面角色表跟着 picks 走:关窗不清空标注(重开同一个窗口还看得见),
2249
+ // 所以角色与 pageKey 也一起留着,下次连上照旧解析。
1702
2250
  // 与运行期一致走 sync() 唯一同步口:先置 off,再由 _applyMode 广播
1703
2251
  // {mode,count};旧版 overlay 没有 sync,由 REV 接管机制兜底。
1704
2252
  this.state.mode = 'off';