dsh-annotator 0.5.4 → 0.6.0

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/index.js CHANGED
@@ -9,6 +9,8 @@
9
9
  import fs from 'node:fs';
10
10
 
11
11
  import { VisualPicker, availableBrowsers } from './session.js';
12
+ import { annotationMarkdown } from './shared/annotation-markdown.js';
13
+ import { isResend, pageKeyOf, pairIdsOf, pairedTargetsOf, pickRoleOf, refLabelOf } from './shared/page-roles.js';
12
14
  import { TOOL_OUTPUT_SCHEMA, TOOL_PARAMETERS } from './shared/tool-schema.js';
13
15
 
14
16
  export const name = 'dsh-annotator';
@@ -16,7 +18,7 @@ export const inject = ['webServer'];
16
18
 
17
19
  const ROUTE_PREFIX = '/api/visual-annotator';
18
20
  /** Proves which build of the host half is live in the running DSH. */
19
- const HOST_REV = 'v29-' + Date.now();
21
+ const HOST_REV = 'v56-' + Date.now();
20
22
  /** Populated when ctx.tools.register rejects the definition; surfaced by /state. */
21
23
  let toolError = null;
22
24
  /** True once visual_annotator_read is really in the live registry (not just declared). */
@@ -112,24 +114,15 @@ export function normalizeShots(value) {
112
114
  return 3;
113
115
  }
114
116
 
115
- /** Markdown for an id-filtered pick subset (same shape as VisualPicker.toMarkdown). */
117
+ /**
118
+ * Markdown for an id-filtered pick subset.
119
+ *
120
+ * 与面板「复制 Markdown」、HUD「复制提示词」共用 lib/shared/annotation-markdown.js:
121
+ * 三处各写一份版本时,工具输出的「参照:」行曾缺席面板版本,粘出去的提示词就丢了
122
+ * 改动↔参照的对照关系。无参照时保持历史单块格式(既有提示词与测试依赖这句话)。
123
+ */
116
124
  export function filteredPicksMarkdown(picks) {
117
- if (!picks.length) return '(没有匹配 id 的页面元素标注)';
118
- const lines = [`页面元素标注(${picks.length} 处)`];
119
- picks.forEach((pick, index) => {
120
- lines.push(
121
- '',
122
- `${index + 1}. \`${pick.selector || pick.tag}\` — ${pick.tag}${pick.text ? `:${pick.text.replace(/\s+/g, ' ').slice(0, 80)}` : ''}`,
123
- );
124
- if (pick.url) lines.push(` 页面:${pick.url}`);
125
- if (pick.pageRect)
126
- lines.push(
127
- ` 位置:x=${Math.round(pick.pageRect.x)} y=${Math.round(pick.pageRect.y)} ${Math.round(pick.pageRect.width)}×${Math.round(pick.pageRect.height)}`,
128
- );
129
- if (pick.comment) lines.push(` 评论:${pick.comment}`);
130
- if (pick.shotPath) lines.push(` 截图:${pick.shotPath}`);
131
- });
132
- return lines.join('\n');
125
+ return annotationMarkdown(picks, { empty: '(没有匹配 id 的页面元素标注)' });
133
126
  }
134
127
 
135
128
  /** Persists the chosen pick screenshots as durable attachments for the tool render. */
@@ -332,8 +325,10 @@ export function apply(ctx) {
332
325
  sendJson(res, 200, { ok: true, ...snapshot, markdown: picker.toMarkdown() });
333
326
  });
334
327
 
335
- route('/clear', async (_req, res) => {
336
- const snapshot = await picker.clear();
328
+ route('/clear', async (req, res) => {
329
+ const body = await readJson(req);
330
+ // scope: 'target' | 'reference' | 'all'(缺省 all)。参考标注是复用资产,清空要保持精准。
331
+ const snapshot = await picker.clear(body.scope);
337
332
  sendJson(res, 200, { ok: true, ...snapshot, markdown: picker.toMarkdown() });
338
333
  });
339
334
 
@@ -344,6 +339,91 @@ export function apply(ctx) {
344
339
  sendJson(res, 200, { ok: true, ...snapshot, markdown: picker.toMarkdown() });
345
340
  });
346
341
 
342
+ // 换一条标注的角色(拖到另一栏):角色属于标注,不属于页面,所以这里只收 id。
343
+ route('/pick-role', async (req, res) => {
344
+ const body = await readJson(req);
345
+ const result = picker.setPickRole(String(body.id ?? ''), body.role);
346
+ sendJson(res, 200, { ...result, markdown: picker.toMarkdown() });
347
+ });
348
+
349
+ route('/pick-include', async (req, res) => {
350
+ const body = await readJson(req);
351
+ const result = picker.setPickInclude(String(body.id ?? ''), body.included !== false);
352
+ sendJson(res, 200, { ...result, markdown: picker.toMarkdown() });
353
+ });
354
+
355
+ // 落点:面板把「下一处标注进哪一栏」同步给 host(null = 取消)。host 用它当场
356
+ // 决定新标注的角色;落点粘住,连续标多处只需点一次按钮。
357
+ route('/arm', async (req, res) => {
358
+ const body = await readJson(req).catch(() => null);
359
+ picker.setArming(body && (body.slot === 'target' || body.slot === 'reference') ? body : null);
360
+ sendJson(res, 200, { ok: true });
361
+ });
362
+
363
+ // 配对:把一条目标标注配到一条参考标注上(参考模式「一行一对」的对应关系)。
364
+ route('/pair', async (req, res) => {
365
+ const body = await readJson(req);
366
+ const result = picker.setPair(String(body.targetId ?? ''), body.refId == null ? '' : String(body.refId), {
367
+ move: body.move === true,
368
+ });
369
+ sendJson(res, 200, { ...result, markdown: picker.toMarkdown() });
370
+ });
371
+
372
+ // 只解开一条参考(右栏参考卡上的小 ×),其余参考还挂在这条目标上。
373
+ route('/unpair', async (req, res) => {
374
+ const body = await readJson(req);
375
+ const result = picker.unpair(String(body.targetId ?? ''), String(body.refId ?? ''));
376
+ sendJson(res, 200, { ...result, markdown: picker.toMarkdown() });
377
+ });
378
+
379
+ route('/pair-all', async (req, res) => {
380
+ const body = await readJson(req);
381
+ const result = picker.pairAll(String(body.refId ?? ''));
382
+ sendJson(res, 200, { ...result, markdown: picker.toMarkdown() });
383
+ });
384
+
385
+ route('/pick-spec', async (req, res) => {
386
+ const body = await readJson(req);
387
+ const result = picker.setPickSpec(String(body.id ?? ''), body.spec);
388
+ sendJson(res, 200, { ...result, markdown: picker.toMarkdown() });
389
+ });
390
+
391
+ // 对比层按需整页截图:POST 触发一次 CDP 抓取,GET 取回字节。
392
+ route('/pageshot', async (req, res) => {
393
+ const url = new URL(req.url ?? '/', 'http://127.0.0.1');
394
+ const isPost = (req.method ?? 'GET').toUpperCase() === 'POST';
395
+ if (isPost) {
396
+ const body = await readJson(req);
397
+ try {
398
+ const result = await picker.capturePageShot(body.key);
399
+ sendJson(res, 200, { ...result, ...picker.snapshot() });
400
+ } catch (error) {
401
+ sendJson(res, 200, {
402
+ ok: false,
403
+ error: String(error?.message ?? error),
404
+ error_message: String(error?.message ?? error),
405
+ ...picker.snapshot(),
406
+ });
407
+ }
408
+ return;
409
+ }
410
+ const key = url.searchParams.get('key') ?? '';
411
+ const file = picker.pageShotFile(key);
412
+ if (!file) {
413
+ sendJson(res, 404, { ok: false, error: 'page shot not found' });
414
+ return;
415
+ }
416
+ try {
417
+ const bytes = fs.readFileSync(file);
418
+ res.statusCode = 200;
419
+ res.setHeader('Content-Type', 'image/png');
420
+ res.setHeader('Cache-Control', 'no-store');
421
+ res.end(bytes);
422
+ } catch (error) {
423
+ sendJson(res, 500, { ok: false, error: String(error?.message ?? error) });
424
+ }
425
+ });
426
+
347
427
  route('/shot', async (req, res) => {
348
428
  const id = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('id') ?? '';
349
429
  const file = picker.shotFile(id);
@@ -374,7 +454,7 @@ export function apply(ctx) {
374
454
  const dispose = tools.register({
375
455
  name: 'visual_annotator_read',
376
456
  description:
377
- "读取用户在 Visual Picker 面板里对网页元素的标注(CSS 选择器、元素文本、评论、截图路径)。用户说“看我的标注/元素标注/截图”时先调用。当用户消息中出现「[标注 #pN]」引用标记时必须调用本工具,并用 ids 参数只取对应标注。返回 markdown、picks 列表,并按 shots 参数把元素截图作为图片附件内联。参数 shots:'none' 不带截图;'all' 内联全部;正整数 n=只内联最近 n 张;缺省内联最近 3 张。参数 wait_seconds(0-60,默认 0):浏览器运行中且自上次读取后没有新标注时轮询等待,出现新标注或超时立即返回,可替代轮询实现“用户标注完成即推送”。",
457
+ "读取用户在 Visual Picker 面板里对网页元素的标注(CSS 选择器、元素文本、评论、截图路径)。用户说“看我的标注/元素标注/截图”时先调用。当用户消息中出现「[标注 #pN]」引用标记时必须调用本工具,并用 ids 参数只取对应标注。返回 markdown、picks 列表,并按 shots 参数把元素截图作为图片附件内联。参数 shots:'none' 不带截图;'all' 内联全部;正整数 n=只内联最近 n 张;缺省内联最近 3 张。参数 wait_seconds(0-60,默认 0):浏览器运行中且自上次读取后没有新标注时轮询等待,出现新标注或超时立即返回,可替代轮询实现“用户标注完成即推送”。参数 roles 可按角色过滤:'target' 只要改动对象、'reference' 只要只读参照规范。标注带 role 字段,角色由用户落标时选的那一栏决定(左栏改动 / 右栏参照),与标注出自哪个标签页无关:role=reference 是右栏参照标注,只用于提取视觉/交互规范:只读的是它指向的那个元素,不是它所在的整页——参照和改动常常就在同一页,那种情况照常改 role=target 指向的元素,别动 role=reference 指向的那个;role=target 是左栏改动对象。改动可以参照任意页面(包括它自己所在的那一页)的标注。目标标注可能为 0(纯参照任务),此时按参照标注给出的规范新建。参照对照模式:目标标注的 pairIds 是它参照的全部参照标注(pairId 是第一条,兼容旧用法),pairedTargets 是这条参照被哪几条目标引用。改一处可以同时参照多处;markdown 里每个目标下面都有一行「参照:R1-1、R2-2 的配色、圆角」,照着改即可。",
378
458
  parameters: TOOL_PARAMETERS,
379
459
  timeoutMs: 90000,
380
460
  output: {
@@ -404,21 +484,55 @@ export function apply(ctx) {
404
484
  }
405
485
  // Includes picks already inserted: a chip keeps its id, and the agent may
406
486
  // be asked about that id long after the panel list moved on.
407
- const all = picker.readablePicks().map((pick) => ({
408
- id: pick.id,
409
- selector: pick.selector,
410
- tag: pick.tag,
411
- text: pick.text,
412
- comment: pick.comment,
413
- shotPath: pick.shotPath ?? null,
414
- url: pick.url,
415
- pageRect: pick.pageRect ?? null,
416
- }));
487
+ const live = picker.readablePicks();
488
+ const all = live.map((pick) => {
489
+ const pageKey = pick.pageKey || pageKeyOf(pick.url);
490
+ // 角色是标注自带的字段,不是从页面推出来的:一条标注属于哪一栏,
491
+ // 取决于用户把它落在哪一栏(或后来拖过去),与它出自哪个页签无关。
492
+ const role = pickRoleOf(pick);
493
+ return {
494
+ id: pick.id,
495
+ selector: pick.selector,
496
+ tag: pick.tag,
497
+ text: pick.text,
498
+ comment: pick.comment,
499
+ shotPath: pick.shotPath ?? null,
500
+ url: pick.url,
501
+ pageRect: pick.pageRect ?? null,
502
+ role,
503
+ roleSource: pick.roleSource ?? 'auto',
504
+ pageKey,
505
+ pageTitle: pick.pageTitle ?? '',
506
+ // R 编号按「参照标注首次出现的页序」派生,同一页的参照永远同一个 R。
507
+ refLabel: role === 'reference' ? refLabelOf(live, pageKey) : '',
508
+ spec: pick.spec ?? [],
509
+ included: pick.included !== false,
510
+ referenced: Boolean(pick.referencedAt),
511
+ resend: isResend(pick),
512
+ pageClosed: Boolean(pick.pageClosed),
513
+ pairId: pick.pairId == null ? null : String(pick.pairId),
514
+ // 这条目标参照的全部参考(一条改法可以同时照多处:版式照 A、配色照 B)。
515
+ pairIds: pairIdsOf(pick),
516
+ // 参考标注被哪几条目标标注引用:agent 才知道一条规范要落到几处。
517
+ pairedTargets: pairedTargetsOf(live, pick.id),
518
+ };
519
+ });
417
520
  lastReadCount = all.length;
418
521
  // Reference mode: the composer only carries [标注 #pN] markers, so the
419
522
  // tool must be able to fetch exactly the referenced subset.
420
523
  const wanted = Array.isArray(args?.ids) ? args.ids.map((id) => String(id)) : null;
421
- const picks = wanted && wanted.length ? all.filter((pick) => wanted.includes(pick.id)) : all;
524
+ // roles: 'target' | 'reference' | 'all' 或数组;缺省全部。
525
+ const roleArg = args?.roles;
526
+ const roleList = Array.isArray(roleArg)
527
+ ? roleArg.map((role) => String(role))
528
+ : roleArg == null || roleArg === 'all'
529
+ ? null
530
+ : [String(roleArg)];
531
+ let picks = wanted && wanted.length ? all.filter((pick) => wanted.includes(pick.id)) : all.slice();
532
+ if (roleList && roleList.length) {
533
+ const allowed = new Set(roleList.map((role) => (role === 'ref' ? 'reference' : role)));
534
+ picks = picks.filter((pick) => allowed.has(pick.role));
535
+ }
422
536
  const attachments = await saveShotAttachments(ctx, picks, shots);
423
537
  return {
424
538
  ok: true,