dsh-marker 0.0.0-stage → 0.1.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/docs/DETAIL.md ADDED
@@ -0,0 +1,45 @@
1
+ # dsh-marker
2
+
3
+ 批注在浏览器里产生,上下文在 Harness 里被消费。
4
+
5
+ ## 它做什么
6
+
7
+ 在 Firefox / Zen 里按 `Alt+Shift+A`,页面进入批注态:划词、点元素、拖框三种手势随便用,写完评论回车即可;评论可留空,留空就只把标记本身发过去。批注连同**裁剪截图**、DOM 选择器、计算样式和页面状态一起进入 DSH 队列,Agent 用 `annotate_*` 工具读取。
8
+
9
+ 反过来也行:Agent 说不清「哪个按钮」时调用 `annotate_pick`,浏览器顶部弹出它写的问题,你点一下,Agent 立即拿到结果继续干活。
10
+
11
+ ## 端点
12
+
13
+ - `ws://127.0.0.1:3080/ext/anno` —— 唯一通道,挂在 DSH 宿主 webserver 上,随 `dsh web` 同生共死。
14
+ - `http://127.0.0.1:3080/ext/anno/health` —— 健康检查与协议版本;带 `instanceId`(本进程的十六进制短 id)。
15
+ - `http://127.0.0.1:30810-30812/ext/anno/locate` —— 发现端口:只在宿主端口不是 `3080` 时监听(Desktop、`--port 0`、自定义端口),只答一个 `GET`,内容是当前 `origin`、`wsUrl`、`instanceId` 和时间戳;不含任何批注、会话或令牌。`POST`/`HEAD` 返回 `405`,`Host` 不是 `127.0.0.1`/`localhost` 返回 `403`,不发 CORS 头。
16
+ - `GET /ext/anno/sessions?token=…` —— 目标选择器的会话目录,`defaultSessionId` 跟随网页里正在看的会话。
17
+ - 下面四条只服务宿主自己的页面(要求 `sec-fetch-site: same-origin`),扩展永远看不到它们:
18
+ - `POST /ext/anno/focus` —— 网页汇报它当前显示的会话。
19
+ - `GET /ext/anno/queue?session=…` / `POST /ext/anno/queue/ack` —— 待插入编辑框的引用。
20
+ - `GET /ext/anno/item?id=…` —— 一条批注的展示投影(chip hover 卡片用)。
21
+ - `GET /ext/anno/image?id=…` —— 那条批注的裁剪截图 PNG。
22
+
23
+ ## 工具
24
+
25
+ | 工具 | 用途 |
26
+ |---|---|
27
+ | `annotate_list` | 列出待处理批注(默认只看 open) |
28
+ | `annotate_get` | 读一条:裁剪图 + 完整锚点 JSON |
29
+ | `annotate_resolve` | 标记已处理,备注即时显示在页面角标 |
30
+ | `annotate_pick` | 让用户在浏览器里点一下,阻塞等待结果 |
31
+ | `annotate_delete` | 直接删除批注(记录、裁剪图、角标一起消失),用于清理测试痕迹 |
32
+ | `annotate_clear` | 批量清理历史 |
33
+
34
+ ## 数据落在哪
35
+
36
+ - 元数据:`$DSH_HOME/annotations/queue.jsonl`(append-only,事件溯源,自动压缩)
37
+ - 图片:交给 DSH 原生 attachment 服务,日志里只存引用
38
+ - 待插入引用:`$DSH_HOME/annotations/pending-mentions.json`
39
+ - 当前显示的会话:`$DSH_HOME/annotations/focus.json`(六小时后失效)
40
+ - 桥接令牌:`$DSH_HOME/ext-bridge-token`(首次生成,0600)
41
+ - 当前地址:`$DSH_HOME/ext-bridge-endpoint.json`(每次启动写到实际端口,0600/用户配置目录 ACL;**只有地址**,令牌不进来——它永远只在上一条里)
42
+
43
+ ## 边界
44
+
45
+ 不替代浏览器自动化(导航、填表还是 `dsh-browser-firefox` 的活),不写 DSH 的 todo/日程,不起独立后台进程(除宿主进程内的发现端口外没有额外监听,默认 `3080` 上连它也不开),不上云。
package/icon.svg ADDED
@@ -0,0 +1,8 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="dsh-marker">
2
+ <rect width="32" height="32" rx="8" fill="#1f6feb"/>
3
+ <rect x="8" y="6" width="16" height="20" rx="2.5" fill="#ffffff" fill-opacity="0.94"/>
4
+ <rect x="11" y="11" width="10" height="3" rx="1.5" fill="#1f6feb" fill-opacity="0.35"/>
5
+ <rect x="11" y="16.5" width="7" height="3" rx="1.5" fill="#1f6feb" fill-opacity="0.2"/>
6
+ <circle cx="21.5" cy="22.5" r="4.5" fill="#f0883e"/>
7
+ <circle cx="21.5" cy="22.5" r="1.8" fill="#ffffff"/>
8
+ </svg>
package/index.js ADDED
@@ -0,0 +1,204 @@
1
+ /**
2
+ * dsh-marker — host half.
3
+ *
4
+ * Mounts one websocket endpoint (`/ext/anno`) and one health route on the DSH
5
+ * host webserver, keeps annotations in an append-only log under `$DSH_HOME`,
6
+ * and exposes them to the model as `annotate_*` tools. No daemon, and on the
7
+ * default `3080` deployment no extra port: it lives and dies with `dsh web`. A
8
+ * host whose port the launcher chose also publishes that address — a record
9
+ * file and, when the port is not `3080`, a loopback locator — so a browser can
10
+ * find it without a second data path (see `docs/DISCOVERY.md`).
11
+ *
12
+ * @module dsh-marker
13
+ */
14
+
15
+ import { randomBytes } from 'node:crypto'
16
+
17
+ import { ensureToken, annotationsDir } from './src/paths.js'
18
+ import { AnnotationStore } from './src/store.js'
19
+ import { createBridge, tokenMatches } from './src/bridge.js'
20
+ import { createDiscovery, isIpv4Loopback, shouldLocate } from './src/discovery.js'
21
+ import { createFocusStore, focusedSession, registerFocusRoute } from './src/focus.js'
22
+ import { startLocator } from './src/locator.js'
23
+ import { createAnnotationMentions } from './src/mentions.js'
24
+ import { registerPresentationRoutes } from './src/presentation.js'
25
+ import { createMentionQueue, registerQueueRoutes } from './src/queue.js'
26
+ import { createSessionCatalog, registerSessionsRoute } from './src/sessions.js'
27
+ import { createTools } from './src/tools.js'
28
+ import { LOCATE_HOST, describeAnchor, formatAnnoMention } from './src/protocol.js'
29
+
30
+ export const name = 'dsh-marker'
31
+ export const inject = ['tools']
32
+
33
+ /** Annotation tools are additive: a profile without `webServer` still lists them. */
34
+ export async function apply(ctx, config = {}) {
35
+ const log = typeof ctx.logger === 'function' ? ctx.logger('dsh-marker') : console
36
+ const logger = {
37
+ debug: (...args) => log.debug?.(...args),
38
+ info: (...args) => log.info?.(...args),
39
+ warn: (...args) => log.warn?.(...args),
40
+ }
41
+
42
+ // One id per process, shared by the three things that must agree on "who is
43
+ // this host": the locator answer, the endpoint record, and `/ext/anno/health`.
44
+ const instanceId = randomBytes(8).toString('hex')
45
+ /** Discovery is on unless a profile turns it off; an unknown value is on. */
46
+ const discoveryMode = config?.discovery === 'off' ? 'off' : 'auto'
47
+
48
+ const store = new AnnotationStore({ dir: annotationsDir(), logger })
49
+ await store.load()
50
+ const token = await ensureToken()
51
+
52
+ // Mentions waiting for a target Session's composer. Loaded before the bridge
53
+ // so a create that arrives first cannot race the queue file.
54
+ const queue = createMentionQueue({ dir: annotationsDir(), logger })
55
+ await queue.load()
56
+ await queue.prune((id) => store.get(id) !== undefined)
57
+
58
+ // Which Session the Web Client is showing. Its absence is normal: a profile
59
+ // without the Client half never reports one.
60
+ const focus = createFocusStore({ dir: annotationsDir(), logger })
61
+ await focus.load()
62
+
63
+ const bridge = createBridge({
64
+ store,
65
+ token,
66
+ instanceId,
67
+ logger,
68
+ onCreated: async (record) => {
69
+ const routed = record.routing?.sessionId
70
+ // An annotation with no target still has one the user would have picked:
71
+ // the conversation they were looking at when they marked the page. The
72
+ // overlay defaults to it, and this covers the case where it could not ask
73
+ // (an older overlay, or a catalog that failed to load). An agent-authored
74
+ // annotation is not the user pointing at their own page, so it never
75
+ // adopts that default.
76
+ const adoptable = record.routing?.source !== 'agent'
77
+ const sessionId =
78
+ typeof routed === 'string' && routed !== '' ? routed : adoptable ? focusedSession(focus) : undefined
79
+ if (typeof sessionId !== 'string' || sessionId === '') return
80
+ if (sessionId !== routed) {
81
+ await store.patch(record.id, { routing: { ...record.routing, sessionId } })
82
+ logger.info?.(`annotations: ${record.id} routed to the focused ${sessionId}`)
83
+ }
84
+ const patched = store.get(record.id) ?? record
85
+ const label =
86
+ typeof patched.routing?.label === 'string' && patched.routing.label !== ''
87
+ ? patched.routing.label
88
+ : describeAnchor(patched)
89
+ const mention = formatAnnoMention({ id: patched.id, label })
90
+ if (mention === '') return
91
+ await queue.enqueue({ id: patched.id, sessionId, mention, label })
92
+ logger.info?.(`annotations: ${patched.id} queued for ${sessionId}`)
93
+ },
94
+ saveImage: async ({ data, mediaType, name }) => {
95
+ const attachments = ctx.get('attachments')
96
+ if (attachments === undefined) throw new Error('no attachment service is mounted')
97
+ return attachments.saveImage({ data, mediaType, name })
98
+ },
99
+ })
100
+
101
+ for (const tool of createTools({ store, bridge })) {
102
+ ctx.effect(() => ctx.tools.register(tool), `dsh-marker: ${tool.name}`)
103
+ }
104
+
105
+ // A `dsh-anno:` mention in a prompt draft is the user's own citation: resolve
106
+ // it before the model sees the turn, so the annotation arrives as context
107
+ // rather than as a token the model has to ask about.
108
+ const mentions = createAnnotationMentions({ store, logger })
109
+ ctx.effect(
110
+ () =>
111
+ ctx.on(
112
+ 'agent/pre-step',
113
+ async (_payload, next) => {
114
+ const decision = await next()
115
+ if (decision.kind === 'reject') return decision
116
+ return { ...decision, messages: await mentions.prepare(decision.messages) }
117
+ },
118
+ { prepend: true },
119
+ ),
120
+ 'dsh-marker: annotation mentions',
121
+ )
122
+
123
+ ctx.inject(['webServer'], (webCtx) => {
124
+ webCtx.effect(() => bridge.attach(webCtx.webServer), 'dsh-marker: /ext/anno bridge')
125
+ webCtx.effect(
126
+ () =>
127
+ registerSessionsRoute(webCtx.webServer, {
128
+ catalog: createSessionCatalog({ get: (service) => ctx.get(service), logger }),
129
+ token,
130
+ matchesToken: tokenMatches,
131
+ preferred: () => focusedSession(focus),
132
+ }),
133
+ 'dsh-marker: /ext/anno/sessions catalog',
134
+ )
135
+ webCtx.effect(() => registerQueueRoutes(webCtx.webServer, { queue }), 'dsh-marker: /ext/anno/queue hand-off')
136
+ webCtx.effect(() => registerFocusRoute(webCtx.webServer, { store: focus }), 'dsh-marker: /ext/anno/focus report')
137
+ webCtx.effect(
138
+ () =>
139
+ registerPresentationRoutes(webCtx.webServer, {
140
+ store,
141
+ readImage: async (ref) => {
142
+ const attachments = ctx.get('attachments')
143
+ if (attachments === undefined) throw new Error('no attachment service is mounted')
144
+ return attachments.readImage(ref)
145
+ },
146
+ }),
147
+ 'dsh-marker: /ext/anno/item and /ext/anno/image',
148
+ )
149
+ logger.info?.(`annotations: listening on ${webCtx.webServer.getOrigin?.() ?? 'the host webserver'}`)
150
+
151
+ // ── discovery ───────────────────────────────────────────────────────────
152
+ // Both artifacts answer "where is this host", never "may I talk to it": the
153
+ // token stays in `$DSH_HOME/ext-bridge-token` and nothing here reads it.
154
+ // The record is written on every start, because it is the manual and
155
+ // diagnostic path; the locator only exists for a port that moves.
156
+ const discovery = createDiscovery({
157
+ webServer: webCtx.webServer,
158
+ focus,
159
+ profile: ctx.get('profileContext')?.name ?? null,
160
+ logger,
161
+ instanceId,
162
+ })
163
+
164
+ webCtx.effect(() => {
165
+ // The write is tracked so a stop that lands mid-write cannot leave a
166
+ // record behind: the disposer removes the file the write just created.
167
+ const written = discovery.write()
168
+ return async () => {
169
+ await written
170
+ await discovery.dispose()
171
+ }
172
+ }, 'dsh-marker: endpoint record')
173
+
174
+ if (shouldLocate({ port: webCtx.webServer.port, host: webCtx.webServer.host, mode: discoveryMode })) {
175
+ webCtx.effect(() => {
176
+ // `startLocator` returns before the bind settles, so this disposer can
177
+ // still close a listener that wins the race a moment later.
178
+ const locator = startLocator({ card: () => discovery.card(), logger })
179
+ void locator.ready.then((port) => {
180
+ if (port !== null) logger.info?.(`annotations: locator on ${LOCATE_HOST}:${port}`)
181
+ })
182
+ return () => locator.dispose()
183
+ }, 'dsh-marker: locator')
184
+ } else if (
185
+ discoveryMode === 'auto' &&
186
+ webCtx.webServer.port !== undefined &&
187
+ !isIpv4Loopback(webCtx.webServer.host)
188
+ ) {
189
+ // The extension has no permission for a non-loopback origin, so there is
190
+ // nothing to publish that it could use. Say so instead of failing later.
191
+ logger.warn?.(
192
+ `annotations: no locator on ${webCtx.webServer.host}: automatic discovery needs an IPv4 loopback bind; use the endpoint record or a manual address`,
193
+ )
194
+ }
195
+ })
196
+
197
+ ctx.effect(
198
+ () => () => {
199
+ bridge.cancelAllPicks()
200
+ void store.flush()
201
+ },
202
+ 'dsh-marker: shutdown',
203
+ )
204
+ }
package/locale/en.json ADDED
@@ -0,0 +1,7 @@
1
+ {
2
+ "meta": {
3
+ "title": "dsh-marker",
4
+ "description": "Mark text, elements, or regions in Firefox/Zen and hand them to the agent with a cropped screenshot.",
5
+ "detail": "docs/DETAIL.md"
6
+ }
7
+ }
package/locale/zh.json ADDED
@@ -0,0 +1,7 @@
1
+ {
2
+ "meta": {
3
+ "title": "dsh-marker 浏览器批注",
4
+ "description": "在 Firefox / Zen 里划词、点选元素或框选区域,连同裁剪截图一起交给 Agent。",
5
+ "detail": "docs/DETAIL.md"
6
+ }
7
+ }
package/package.json CHANGED
@@ -1,6 +1,61 @@
1
1
  {
2
2
  "name": "dsh-marker",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Visual annotation bridge: mark text, elements, or regions in Firefox/Zen and hand them to DeepSeek Harness as first-class context",
5
+ "type": "module",
6
+ "license": "MIT",
7
+ "main": "./index.js",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/modenicheng/dsh-annotate.git",
11
+ "directory": "packages/plugin"
12
+ },
13
+ "homepage": "https://github.com/modenicheng/dsh-annotate#readme",
14
+ "bugs": {
15
+ "url": "https://github.com/modenicheng/dsh-annotate/issues"
16
+ },
17
+ "exports": {
18
+ ".": "./index.js",
19
+ "./client": "./client.js",
20
+ "./locale/*.json": "./locale/*.json",
21
+ "./icon": "./icon.svg"
22
+ },
23
+ "files": [
24
+ "index.js",
25
+ "client.js",
26
+ "src",
27
+ "cordis.patch.yml",
28
+ "locale/*.json",
29
+ "docs",
30
+ "icon.svg"
31
+ ],
32
+ "dependencies": {
33
+ "ws": "^8.18.0"
34
+ },
35
+ "dsh": {
36
+ "bundle": {
37
+ "patch": "./cordis.patch.yml"
38
+ },
39
+ "client": {
40
+ "platform": "web",
41
+ "immediately": true,
42
+ "inject": [
43
+ "@deepseek-ai/dsh-client-ui-conversation"
44
+ ]
45
+ }
46
+ },
47
+ "engines": {
48
+ "node": ">=22",
49
+ "dsh": "^0.2.0"
50
+ },
51
+ "keywords": [
52
+ "dsh",
53
+ "dsh-plugin",
54
+ "annotation",
55
+ "marker",
56
+ "browser",
57
+ "firefox",
58
+ "zen",
59
+ "deepseek-harness"
60
+ ]
61
+ }