dsh-mindmark 0.3.0 → 0.4.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/src/store.js CHANGED
@@ -34,9 +34,18 @@ export const MAX_ROOT_SELECTOR_LENGTH = 300
34
34
  export const MAX_SESSION_ID_LENGTH = 200
35
35
  export const MAX_MESSAGE_KEY_LENGTH = 200
36
36
  export const MAX_MESSAGE_TEXT_LENGTH = 20000
37
- export const ANNOTATION_STYLES = ['highlight', 'underline', 'strike', 'comment', 'rewrite']
37
+ export const ANNOTATION_STYLES = ['highlight', 'underline', 'strike', 'comment', 'rewrite', 'move', 'reference']
38
38
  /** Styles whose meaning needs the user's own words. */
39
39
  export const NOTE_STYLES = ['comment', 'rewrite']
40
+ /** Material attached to a `reference` annotation. */
41
+ export const MATERIAL_KINDS = ['text', 'url', 'file']
42
+ export const MAX_MATERIAL_CHARS = 200000
43
+ export const MAX_MATERIAL_TITLE = 120
44
+ export const MAX_MATERIAL_URL = 2000
45
+ export const MATERIAL_EXCERPT_CHARS = 600
46
+ /** Materials up to this size are sent whole; longer ones are read through the tool. */
47
+ export const MATERIAL_INLINE_CHARS = 2000
48
+ export const MATERIAL_CHUNK_CHARS = 8000
40
49
  export const ANNOTATION_STATUSES = ['pending', 'resolved']
41
50
  export const INJECTION_MODES = ['brief', 'full']
42
51
  export const DEFAULT_MODE = 'brief'
@@ -112,6 +121,123 @@ function optionalInteger(value) {
112
121
  return number
113
122
  }
114
123
 
124
+ function hostOf(url) {
125
+ try {
126
+ return new URL(url).host
127
+ } catch {
128
+ return url.slice(0, MAX_MATERIAL_TITLE)
129
+ }
130
+ }
131
+
132
+ /**
133
+ * Validate the material of a `reference` annotation (wire format). Returns
134
+ * `{ meta, content }`: `meta` is what the annotation record keeps, `content`
135
+ * goes to its own file under `annotations/materials/`.
136
+ */
137
+ export function validateMaterialInput(raw) {
138
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
139
+ throw new AnnotateInputError('missing-material', '依据需要附上参考材料(粘贴文本、链接或文件)。')
140
+ }
141
+ if (!MATERIAL_KINDS.includes(raw.kind)) {
142
+ throw new AnnotateInputError('invalid-material-kind', '材料类型必须是 text、url 或 file。')
143
+ }
144
+ const content = typeof raw.content === 'string' ? raw.content.trim() : ''
145
+ if (content === '') {
146
+ throw new AnnotateInputError('missing-material', '参考材料不能为空。')
147
+ }
148
+ let title = typeof raw.title === 'string' ? raw.title.trim().replace(/\s+/g, ' ').slice(0, MAX_MATERIAL_TITLE) : ''
149
+ if (raw.kind === 'url') {
150
+ if (content.length > MAX_MATERIAL_URL || !/^https?:\/\/\S+$/i.test(content)) {
151
+ throw new AnnotateInputError('invalid-material-url', '链接必须是以 http:// 或 https:// 开头的网址。')
152
+ }
153
+ if (title === '') title = hostOf(content)
154
+ return { meta: { kind: 'url', title, url: content, length: 0, excerpt: '' }, content }
155
+ }
156
+ if (content.length > MAX_MATERIAL_CHARS) {
157
+ throw new AnnotateInputError(
158
+ 'material-too-long',
159
+ `材料太长:最多 ${MAX_MATERIAL_CHARS} 字,请只保留和这一段相关的部分。`,
160
+ )
161
+ }
162
+ if (title === '') title = raw.kind === 'file' ? '文件' : '粘贴的材料'
163
+ return {
164
+ meta: { kind: raw.kind, title, length: content.length, excerpt: content.slice(0, MATERIAL_EXCERPT_CHARS) },
165
+ content,
166
+ }
167
+ }
168
+
169
+ function normalizeStoredMaterial(raw) {
170
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
171
+ if (!MATERIAL_KINDS.includes(raw.kind)) return null
172
+ const title = truncate(typeof raw.title === 'string' ? raw.title : '', MAX_MATERIAL_TITLE)
173
+ if (raw.kind === 'url') {
174
+ const url = truncate(raw.url, MAX_MATERIAL_URL)
175
+ if (!/^https?:\/\//i.test(url)) return null
176
+ return { kind: 'url', title, url, length: 0, excerpt: '' }
177
+ }
178
+ return {
179
+ kind: raw.kind,
180
+ title,
181
+ length: optionalInteger(raw.length) ?? 0,
182
+ excerpt: truncate(raw.excerpt, MATERIAL_EXCERPT_CHARS),
183
+ }
184
+ }
185
+
186
+ /**
187
+ * Where a `move` annotation goes, inside the same message. Either an insertion
188
+ * point (the caret: the passage goes right after `targetPrefix`), or, when the
189
+ * user selected text as the target, that text (`targetQuote`), which the moved
190
+ * passage replaces. `targetPrefix` / `targetSuffix` are the text right before
191
+ * and after the point or the replaced text; `targetOffset` (and `targetEnd`
192
+ * for a replacement) are offsets in the captured message when the source
193
+ * passage is anchored there.
194
+ */
195
+ function moveTargetOf(raw, anchor) {
196
+ const targetPrefix = contextString(raw.targetPrefix, MAX_CONTEXT_LENGTH)
197
+ const targetSuffix = contextString(raw.targetSuffix, MAX_CONTEXT_LENGTH)
198
+ let targetQuote = ''
199
+ if (raw.targetQuote !== undefined && raw.targetQuote !== null && raw.targetQuote !== '') {
200
+ if (typeof raw.targetQuote !== 'string' || raw.targetQuote.length > MAX_QUOTE_LENGTH) {
201
+ throw new AnnotateInputError('invalid-move-target', `被替换的文字必须是 1–${MAX_QUOTE_LENGTH} 个字符。`)
202
+ }
203
+ targetQuote = raw.targetQuote.trim() === '' ? '' : raw.targetQuote
204
+ }
205
+ if (targetPrefix === '' && targetSuffix === '' && targetQuote === '') {
206
+ throw new AnnotateInputError('missing-move-target', '移动需要指定目标位置。')
207
+ }
208
+ const target = { targetPrefix, targetSuffix }
209
+ if (targetQuote !== '') target.targetQuote = targetQuote
210
+ const offset = optionalInteger(raw.targetOffset)
211
+ if (anchor !== undefined && offset !== undefined) {
212
+ if (targetQuote === '') {
213
+ if (offset >= anchor.start && offset <= anchor.end) {
214
+ throw new AnnotateInputError('invalid-move-target', '目标位置不能在被移动的文字里面,也不能是原处。')
215
+ }
216
+ } else {
217
+ const end = optionalInteger(raw.targetEnd) ?? offset + targetQuote.length
218
+ if (offset < anchor.end && end > anchor.start) {
219
+ throw new AnnotateInputError('invalid-move-target', '被替换的文字不能和被移动的文字重叠。')
220
+ }
221
+ target.targetEnd = end
222
+ }
223
+ target.targetOffset = offset
224
+ }
225
+ return target
226
+ }
227
+
228
+ /** Drop the style-specific fields a record of another style must not carry. */
229
+ function stripForeignFields(record) {
230
+ if (record.style !== 'move') {
231
+ delete record.targetPrefix
232
+ delete record.targetSuffix
233
+ delete record.targetOffset
234
+ delete record.targetEnd
235
+ delete record.targetQuote
236
+ }
237
+ if (record.style !== 'reference') delete record.material
238
+ return record
239
+ }
240
+
115
241
  /**
116
242
  * Normalize one incoming Annotation (wire format, client -> Host). Missing
117
243
  * optional fields are filled in; anything shaped wrongly is rejected with a
@@ -195,6 +321,14 @@ export function validateAnnotationInput(raw) {
195
321
  status: 'pending',
196
322
  injections: 0,
197
323
  }
324
+ stripForeignFields(record)
325
+ delete record.targetOffset
326
+ delete record.targetEnd
327
+ delete record.targetQuote
328
+ if (record.style === 'move') {
329
+ Object.assign(record, moveTargetOf(raw, anchored ? { start: messageStart, end: messageEnd } : undefined))
330
+ }
331
+ if (record.style === 'reference') record.material = validateMaterialInput(raw.material).meta
198
332
  return withAnchor(record, anchored ? messageStart : undefined, anchored ? messageEnd : undefined, optionalInteger(raw.turn))
199
333
  }
200
334
 
@@ -268,6 +402,26 @@ function normalizeStoredAnnotation(raw) {
268
402
  if (record.lastInjectedTurn !== undefined && optionalInteger(record.lastInjectedTurn) === undefined) {
269
403
  delete record.lastInjectedTurn
270
404
  }
405
+ stripForeignFields(record)
406
+ if (record.style === 'move') {
407
+ record.targetPrefix = truncate(raw.targetPrefix, MAX_CONTEXT_LENGTH)
408
+ record.targetSuffix = truncate(raw.targetSuffix, MAX_CONTEXT_LENGTH)
409
+ const targetQuote = typeof raw.targetQuote === 'string' && raw.targetQuote.trim() !== '' ? truncate(raw.targetQuote, MAX_QUOTE_LENGTH) : ''
410
+ if (targetQuote === '') delete record.targetQuote
411
+ else record.targetQuote = targetQuote
412
+ if (record.targetPrefix === '' && record.targetSuffix === '' && targetQuote === '') return null
413
+ const offset = optionalInteger(raw.targetOffset)
414
+ if (offset === undefined || !anchored) delete record.targetOffset
415
+ else record.targetOffset = offset
416
+ const end = optionalInteger(raw.targetEnd)
417
+ if (targetQuote === '' || record.targetOffset === undefined || end === undefined || end <= offset) delete record.targetEnd
418
+ else record.targetEnd = end
419
+ }
420
+ if (record.style === 'reference') {
421
+ const material = normalizeStoredMaterial(raw.material)
422
+ if (material === null) return null
423
+ record.material = material
424
+ }
271
425
  return record
272
426
  }
273
427
 
@@ -472,10 +626,93 @@ export class AnnotationStore {
472
626
  this.filePath = filePath ?? resolveStatePath()
473
627
  this.logger = logger
474
628
  this.defaultMode = INJECTION_MODES.includes(defaultMode) ? defaultMode : DEFAULT_MODE
629
+ this.materialsDir = path.join(path.dirname(this.filePath), 'materials')
475
630
  this.state = loadStateFile(this.filePath, { logger })
476
631
  this.lastSaveError = null
477
632
  // Canonicalize what was loaded (and create the file early, best effort).
478
633
  this.persist()
634
+ this.sweepMaterials()
635
+ }
636
+
637
+ // ------------------------------------------------------------ materials
638
+
639
+ materialPath(id) {
640
+ return path.join(this.materialsDir, `${String(id).replace(/[^A-Za-z0-9_-]/g, '_')}.txt`)
641
+ }
642
+
643
+ writeMaterial(id, content) {
644
+ fs.mkdirSync(this.materialsDir, { recursive: true })
645
+ fs.writeFileSync(this.materialPath(id), content, { encoding: 'utf8', mode: 0o600 })
646
+ }
647
+
648
+ readMaterialFile(id) {
649
+ try {
650
+ return fs.readFileSync(this.materialPath(id), 'utf8')
651
+ } catch {
652
+ return undefined
653
+ }
654
+ }
655
+
656
+ deleteMaterials(records) {
657
+ for (const record of records) {
658
+ if (record?.style !== 'reference') continue
659
+ try {
660
+ fs.rmSync(this.materialPath(record.id), { force: true })
661
+ } catch (error) {
662
+ this.logger?.warn?.(`dsh-mindmark: cannot delete material ${record.id}: ${String(error)}`)
663
+ }
664
+ }
665
+ }
666
+
667
+ /** Remove material files no annotation refers to any more (best effort). */
668
+ sweepMaterials() {
669
+ let names
670
+ try {
671
+ names = fs.readdirSync(this.materialsDir)
672
+ } catch {
673
+ return
674
+ }
675
+ const keep = new Set()
676
+ for (const session of Object.values(this.state.sessions)) {
677
+ for (const item of session?.annotations ?? []) {
678
+ if (item.style === 'reference') keep.add(path.basename(this.materialPath(item.id)))
679
+ }
680
+ }
681
+ for (const name of names) {
682
+ if (!name.endsWith('.txt') || keep.has(name)) continue
683
+ try {
684
+ fs.rmSync(path.join(this.materialsDir, name), { force: true })
685
+ } catch {
686
+ // Harmless leftover.
687
+ }
688
+ }
689
+ }
690
+
691
+ /**
692
+ * Read one chunk of the material of a `reference` annotation. Returns
693
+ * undefined when the annotation or its material is gone.
694
+ */
695
+ material(sessionId, id, { offset = 0, limit = MATERIAL_CHUNK_CHARS } = {}) {
696
+ const record = this.sessionFor(sessionId)?.annotations.find(item => item.id === id)
697
+ if (record === undefined || record.style !== 'reference') return undefined
698
+ const meta = record.material
699
+ if (meta.kind === 'url') {
700
+ return { id, kind: 'url', title: meta.title, url: meta.url, total: 0, offset: 0, content: '', nextOffset: -1 }
701
+ }
702
+ const content = this.readMaterialFile(id)
703
+ if (content === undefined) return undefined
704
+ const start = Math.max(0, Math.min(Number.isInteger(offset) ? offset : 0, content.length))
705
+ const size = Number.isInteger(limit) && limit > 0 ? Math.min(limit, MATERIAL_CHUNK_CHARS) : MATERIAL_CHUNK_CHARS
706
+ const end = Math.min(content.length, start + size)
707
+ return {
708
+ id,
709
+ kind: meta.kind,
710
+ title: meta.title,
711
+ total: content.length,
712
+ offset: start,
713
+ content: content.slice(start, end),
714
+ nextOffset: end < content.length ? end : -1,
715
+ }
479
716
  }
480
717
 
481
718
  /** Session id -> safe session object, or undefined. */
@@ -546,13 +783,23 @@ export class AnnotationStore {
546
783
  /** Everything the injection builder needs for one session. */
547
784
  snapshot(sessionId) {
548
785
  const session = this.sessionFor(sessionId)
786
+ const annotations = this.list(sessionId)
787
+ // Short materials travel whole; longer ones are read through the tool.
788
+ const materials = {}
789
+ for (const item of annotations) {
790
+ if (item.style !== 'reference' || item.material.kind === 'url') continue
791
+ if (item.material.length > MATERIAL_INLINE_CHARS) continue
792
+ const content = this.readMaterialFile(item.id)
793
+ if (content !== undefined) materials[item.id] = content
794
+ }
549
795
  return {
550
796
  mode: this.getMode(sessionId),
551
- annotations: this.list(sessionId),
797
+ annotations,
552
798
  messages:
553
799
  session === undefined
554
800
  ? {}
555
801
  : Object.fromEntries(Object.entries(session.messages).map(([key, value]) => [key, { ...value }])),
802
+ materials,
556
803
  }
557
804
  }
558
805
 
@@ -576,18 +823,26 @@ export class AnnotationStore {
576
823
  } else if (record.messageKey !== '' && session.messages[record.messageKey] === undefined) {
577
824
  // Anchored to a message we never captured: keep the offsets harmless.
578
825
  record.messageKey = ''
579
- record.messageStart = undefined
580
- record.messageEnd = undefined
826
+ delete record.messageStart
827
+ delete record.messageEnd
828
+ delete record.targetOffset
829
+ delete record.targetEnd
581
830
  }
831
+ const material = record.style === 'reference' ? validateMaterialInput(annotation.material) : null
582
832
  const index = session.annotations.findIndex(
583
833
  item =>
584
834
  item.style === record.style &&
585
835
  item.quote === record.quote &&
586
836
  item.prefix === record.prefix &&
587
837
  item.suffix === record.suffix &&
588
- item.note === record.note,
838
+ item.note === record.note &&
839
+ (item.style !== 'move' ||
840
+ (item.targetPrefix === record.targetPrefix &&
841
+ item.targetSuffix === record.targetSuffix &&
842
+ (item.targetQuote ?? '') === (record.targetQuote ?? ''))),
589
843
  )
590
844
  let result
845
+ let stored
591
846
  if (index >= 0) {
592
847
  const existing = session.annotations[index]
593
848
  const anchorSource = record.messageKey !== '' ? record : existing
@@ -601,16 +856,37 @@ export class AnnotationStore {
601
856
  delete refreshed.resolvedAt
602
857
  delete refreshed.resolvedBy
603
858
  delete refreshed.lastInjectedTurn
859
+ // A re-marked reference takes the newly attached material.
860
+ if (material !== null) refreshed.material = material.meta
861
+ if (record.style === 'move') {
862
+ if (record.targetOffset !== undefined) refreshed.targetOffset = record.targetOffset
863
+ else if (refreshed.messageStart === undefined) delete refreshed.targetOffset
864
+ if (record.targetEnd !== undefined) refreshed.targetEnd = record.targetEnd
865
+ else if (refreshed.targetOffset === undefined) delete refreshed.targetEnd
866
+ }
604
867
  session.annotations.splice(index, 1)
605
868
  session.annotations.push(refreshed)
869
+ stored = refreshed
606
870
  result = { annotation: { ...refreshed }, deduped: true }
607
871
  } else {
608
872
  session.annotations.push({ ...record })
609
873
  if (session.annotations.length > MAX_ANNOTATIONS_PER_SESSION) {
610
- session.annotations.splice(0, session.annotations.length - MAX_ANNOTATIONS_PER_SESSION)
874
+ const dropped = session.annotations.splice(0, session.annotations.length - MAX_ANNOTATIONS_PER_SESSION)
875
+ this.deleteMaterials(dropped)
611
876
  }
877
+ stored = record
612
878
  result = { annotation: { ...record }, deduped: false }
613
879
  }
880
+ if (material !== null) {
881
+ try {
882
+ this.writeMaterial(stored.id, material.content)
883
+ } catch (error) {
884
+ // Without its material a new reference is meaningless: undo it.
885
+ if (!result.deduped) session.annotations = session.annotations.filter(item => item.id !== stored.id)
886
+ this.logger?.warn?.(`dsh-mindmark: cannot save material: ${String(error)}`)
887
+ throw new AnnotateInputError('material-save-failed', '参考材料保存失败。')
888
+ }
889
+ }
614
890
  this.pruneMessages(session)
615
891
  this.persist()
616
892
  return result
@@ -630,12 +906,13 @@ export class AnnotationStore {
630
906
  if (session === undefined) return 0
631
907
  const wanted = cleanIds(ids)
632
908
  if (wanted.size === 0) return 0
633
- const before = session.annotations.length
909
+ const dropped = session.annotations.filter(item => wanted.has(item.id))
634
910
  session.annotations = session.annotations.filter(item => !wanted.has(item.id))
635
- const removed = before - session.annotations.length
911
+ const removed = dropped.length
636
912
  if (removed > 0) {
637
913
  this.pruneMessages(session)
638
914
  this.persist()
915
+ this.deleteMaterials(dropped)
639
916
  }
640
917
  return removed
641
918
  }
@@ -644,10 +921,14 @@ export class AnnotationStore {
644
921
  clear(sessionId) {
645
922
  const session = this.sessionFor(sessionId)
646
923
  if (session === undefined) return 0
647
- const removed = session.annotations.length
924
+ const dropped = session.annotations
925
+ const removed = dropped.length
648
926
  session.annotations = []
649
927
  session.messages = {}
650
- if (removed > 0) this.persist()
928
+ if (removed > 0) {
929
+ this.persist()
930
+ this.deleteMaterials(dropped)
931
+ }
651
932
  return removed
652
933
  }
653
934