dsh-wiki-notes 1.3.0 → 1.4.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.
Files changed (23) hide show
  1. package/README.md +104 -24
  2. package/docs/README.md +70 -0
  3. package/docs//345/245/221/347/272/246-stage0/knowledge-gateway.v1.schema.json +1180 -0
  4. package/docs//345/245/221/347/272/246-stage0/samples/_verify_probe.json +46 -0
  5. package/docs//345/245/221/347/272/246-stage0/samples/context.cq-shenlun.json +612 -0
  6. package/docs//345/245/221/347/272/246-stage0/samples/verify.context-corrupt.json +20 -0
  7. package/docs//345/245/221/347/272/246-stage0/samples/verify.context-expired.json +20 -0
  8. package/docs//345/245/221/347/272/246-stage0/samples/verify.fabricated-quote.json +31 -0
  9. package/docs//345/245/221/347/272/246-stage0/samples/verify.right-with-limit.json +14 -0
  10. package/docs//345/245/221/347/272/246-stage0/samples/verify.scope-mismatch.json +27 -0
  11. package/docs//345/245/221/347/272/246-stage0/samples/verify.wrong-five.json +43 -0
  12. package/docs//345/245/221/347/272/246-stage0//350/247/202/345/257/237/346/234/237/346/226/271/346/241/210.md +81 -0
  13. package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2650-/345/256/241/350/256/241/344/270/216/345/245/221/347/272/246.md +204 -0
  14. package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2651-/346/225/260/345/200/274/345/210/244/346/215/256/344/270/216/345/274/225/346/223/216/347/212/266/346/200/201.md +107 -0
  15. package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2652-/345/277/253/347/205/247/344/270/216TTL.md +84 -0
  16. package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2653-/346/224/257/346/214/201/345/216/237/345/233/240.md +98 -0
  17. package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2654-/346/217/222/344/273/266/346/216/245/345/205/245.md +143 -0
  18. package/docs//345/245/221/347/272/246-stage0//351/230/266/346/256/2655-/350/247/202/345/257/237/351/227/255/347/216/257/344/270/216/345/256/236/346/210/230/351/252/214/346/224/266.md +109 -0
  19. package/lib/bridge.js +210 -0
  20. package/lib/client.js +1 -1
  21. package/lib/config.js +59 -0
  22. package/lib/index.js +268 -4
  23. package/package.json +2 -2
@@ -0,0 +1,1180 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://dsh-wiki-notes.local/contracts/knowledge-gateway.v1.json",
4
+ "title": "dsh-wiki-notes · LLMWiki Knowledge Gateway Contract v1.0",
5
+ "description": "三个 MCP 工具(wiki_context / wiki_verify / wiki_observe)共用的线缆契约。判别字段 kind。所有证据判定由 Python 管线计算,插件只做参数校验与转发。",
6
+ "type": "object",
7
+ "required": [
8
+ "kind",
9
+ "contract_version"
10
+ ],
11
+ "properties": {
12
+ "kind": {
13
+ "enum": [
14
+ "context",
15
+ "verify",
16
+ "observe",
17
+ "error",
18
+ "observe_stats"
19
+ ]
20
+ },
21
+ "contract_version": {
22
+ "const": "1.0"
23
+ },
24
+ "plugin_version": {
25
+ "type": "string",
26
+ "examples": [
27
+ "1.4.0"
28
+ ]
29
+ },
30
+ "bridge_version": {
31
+ "type": "string",
32
+ "examples": [
33
+ "0.1.0"
34
+ ]
35
+ },
36
+ "pipeline_version": {
37
+ "type": "string",
38
+ "examples": [
39
+ "2026-11-05"
40
+ ]
41
+ }
42
+ },
43
+ "oneOf": [
44
+ {
45
+ "$ref": "#/$defs/context"
46
+ },
47
+ {
48
+ "$ref": "#/$defs/verify"
49
+ },
50
+ {
51
+ "$ref": "#/$defs/observe"
52
+ },
53
+ {
54
+ "$ref": "#/$defs/error_envelope"
55
+ },
56
+ {
57
+ "$ref": "#/$defs/observe_stats"
58
+ }
59
+ ],
60
+ "$defs": {
61
+ "err": {
62
+ "type": "object",
63
+ "description": "运行环境故障。与 status.support 严格分离:这里是「跑不起来」,那边是「知识不足」。",
64
+ "required": [
65
+ "code",
66
+ "message"
67
+ ],
68
+ "properties": {
69
+ "code": {
70
+ "enum": [
71
+ "E_QUERY_EMPTY",
72
+ "E_CONTRACT_VERSION_MISMATCH",
73
+ "E_PYTHON_UNAVAILABLE",
74
+ "E_BRIDGE_SPAWN_FAILED",
75
+ "E_BRIDGE_TIMEOUT",
76
+ "E_BRIDGE_CRASH",
77
+ "E_BRIDGE_BAD_JSON",
78
+ "E_CONTEXT_NOT_FOUND",
79
+ "E_CONTEXT_EXPIRED",
80
+ "E_CONTEXT_CORRUPT",
81
+ "E_VERIFY_EMPTY_ANSWER",
82
+ "E_ENGINE_UNAVAILABLE",
83
+ "E_WIKI_ROOT_MISSING",
84
+ "E_INTERNAL"
85
+ ]
86
+ },
87
+ "message": {
88
+ "type": "string"
89
+ },
90
+ "retryable": {
91
+ "type": "boolean"
92
+ },
93
+ "stage": {
94
+ "enum": [
95
+ "plan",
96
+ "retrieve",
97
+ "read",
98
+ "extract",
99
+ "policy",
100
+ "observe",
101
+ "bridge",
102
+ "validate",
103
+ "snapshot",
104
+ "import",
105
+ "build",
106
+ "verify",
107
+ "input",
108
+ "argv"
109
+ ]
110
+ },
111
+ "detail": {
112
+ "type": [
113
+ "object",
114
+ "string",
115
+ "null"
116
+ ],
117
+ "description": "诊断细节;环境类错误给异常的字符串形式"
118
+ }
119
+ }
120
+ },
121
+ "engine_slot": {
122
+ "type": "object",
123
+ "required": [
124
+ "status"
125
+ ],
126
+ "properties": {
127
+ "status": {
128
+ "enum": [
129
+ "ok",
130
+ "empty",
131
+ "error",
132
+ "timeout",
133
+ "disabled"
134
+ ]
135
+ },
136
+ "candidates": {
137
+ "type": "integer",
138
+ "minimum": 0
139
+ },
140
+ "queries_run": {
141
+ "type": "integer",
142
+ "minimum": 0
143
+ },
144
+ "elapsed_ms": {
145
+ "type": "number"
146
+ },
147
+ "error": {
148
+ "$ref": "#/$defs/err"
149
+ }
150
+ }
151
+ },
152
+ "found_by": {
153
+ "type": "object",
154
+ "required": [
155
+ "query_id",
156
+ "engine"
157
+ ],
158
+ "properties": {
159
+ "query_id": {
160
+ "type": "string"
161
+ },
162
+ "unit_query": {
163
+ "type": "string"
164
+ },
165
+ "unit_variant": {
166
+ "enum": [
167
+ "original",
168
+ "decomposed",
169
+ "keyword",
170
+ "unknown"
171
+ ]
172
+ },
173
+ "engine": {
174
+ "enum": [
175
+ "search.py",
176
+ "wiki_recall",
177
+ "injected"
178
+ ]
179
+ },
180
+ "rank": {
181
+ "type": [
182
+ "integer",
183
+ "null"
184
+ ]
185
+ },
186
+ "tier": {
187
+ "type": [
188
+ "integer",
189
+ "string",
190
+ "null"
191
+ ]
192
+ }
193
+ }
194
+ },
195
+ "provenance": {
196
+ "type": "object",
197
+ "required": [
198
+ "engine"
199
+ ],
200
+ "properties": {
201
+ "engine": {
202
+ "enum": [
203
+ "search.py",
204
+ "wiki_recall",
205
+ "injected"
206
+ ]
207
+ },
208
+ "rank": {
209
+ "type": [
210
+ "integer",
211
+ "null"
212
+ ]
213
+ },
214
+ "query_id": {
215
+ "type": [
216
+ "string",
217
+ "null"
218
+ ]
219
+ },
220
+ "score": {
221
+ "type": [
222
+ "number",
223
+ "null"
224
+ ]
225
+ }
226
+ }
227
+ },
228
+ "support": {
229
+ "type": "object",
230
+ "required": [
231
+ "slot",
232
+ "quote_support",
233
+ "quote",
234
+ "section",
235
+ "page"
236
+ ],
237
+ "properties": {
238
+ "slot": {
239
+ "type": "string"
240
+ },
241
+ "quote_support": {
242
+ "enum": [
243
+ "supported",
244
+ "conditional",
245
+ "clue"
246
+ ],
247
+ "description": "supported=直接支持;conditional=有条件支持(note 必填);clue=只是线索,不能当支持用,只能用来引路"
248
+ },
249
+ "support_confidence": {
250
+ "enum": [
251
+ "high",
252
+ "medium",
253
+ "low",
254
+ "unknown"
255
+ ]
256
+ },
257
+ "needs_review": {
258
+ "type": "boolean"
259
+ },
260
+ "note": {
261
+ "type": [
262
+ "string",
263
+ "null"
264
+ ],
265
+ "description": "conditional 时必须非空"
266
+ },
267
+ "section": {
268
+ "type": "string"
269
+ },
270
+ "quote": {
271
+ "type": "string",
272
+ "description": "必须是页面原文子串"
273
+ },
274
+ "page": {
275
+ "type": "string",
276
+ "description": "库根相对路径"
277
+ },
278
+ "relation": {
279
+ "enum": [
280
+ "core",
281
+ "related",
282
+ "clue"
283
+ ]
284
+ },
285
+ "method": {
286
+ "type": [
287
+ "string",
288
+ "null"
289
+ ]
290
+ },
291
+ "values": {
292
+ "type": [
293
+ "object",
294
+ "null"
295
+ ]
296
+ }
297
+ }
298
+ },
299
+ "evidence_page": {
300
+ "type": "object",
301
+ "required": [
302
+ "page",
303
+ "title",
304
+ "page_type",
305
+ "source_relation",
306
+ "evidence_grade"
307
+ ],
308
+ "properties": {
309
+ "page": {
310
+ "type": "string"
311
+ },
312
+ "title": {
313
+ "type": "string"
314
+ },
315
+ "page_type": {
316
+ "type": "string"
317
+ },
318
+ "status": {
319
+ "type": "string",
320
+ "description": "页面 frontmatter 的状态"
321
+ },
322
+ "sources": {
323
+ "type": [
324
+ "integer",
325
+ "string"
326
+ ]
327
+ },
328
+ "source_relation": {
329
+ "enum": [
330
+ "core",
331
+ "related",
332
+ "clue"
333
+ ]
334
+ },
335
+ "evidence_grade": {
336
+ "enum": [
337
+ "direct",
338
+ "related",
339
+ "weak",
340
+ "unknown"
341
+ ]
342
+ },
343
+ "retrieval_mode": {
344
+ "type": "string"
345
+ },
346
+ "matched": {
347
+ "type": "object"
348
+ },
349
+ "found_by": {
350
+ "type": "array",
351
+ "items": {
352
+ "$ref": "#/$defs/found_by"
353
+ }
354
+ },
355
+ "provenance": {
356
+ "type": "array",
357
+ "items": {
358
+ "$ref": "#/$defs/provenance"
359
+ }
360
+ },
361
+ "supports": {
362
+ "type": "array",
363
+ "items": {
364
+ "$ref": "#/$defs/support"
365
+ }
366
+ }
367
+ }
368
+ },
369
+ "evidence_item": {
370
+ "type": "object",
371
+ "description": "去重后的证据单元:同段内容多页出现时一条证据、多个出处。",
372
+ "required": [
373
+ "evidence_id",
374
+ "slot",
375
+ "quote",
376
+ "provenance"
377
+ ],
378
+ "properties": {
379
+ "evidence_id": {
380
+ "type": "string"
381
+ },
382
+ "slot": {
383
+ "type": "string"
384
+ },
385
+ "quote": {
386
+ "type": "string"
387
+ },
388
+ "page_count": {
389
+ "type": "integer"
390
+ },
391
+ "engine_count": {
392
+ "type": "integer"
393
+ },
394
+ "near_duplicate": {
395
+ "type": "boolean"
396
+ },
397
+ "provenance": {
398
+ "type": "array",
399
+ "items": {
400
+ "type": "object",
401
+ "required": [
402
+ "page"
403
+ ],
404
+ "properties": {
405
+ "page": {
406
+ "type": "string"
407
+ },
408
+ "section": {
409
+ "type": "string"
410
+ }
411
+ }
412
+ }
413
+ }
414
+ }
415
+ },
416
+ "missing": {
417
+ "type": "object",
418
+ "required": [
419
+ "slot",
420
+ "reason"
421
+ ],
422
+ "properties": {
423
+ "slot": {
424
+ "type": "string"
425
+ },
426
+ "target": {
427
+ "type": "string"
428
+ },
429
+ "reason": {
430
+ "enum": [
431
+ "not_found",
432
+ "not_verifiable",
433
+ "not_covered_in_wiki",
434
+ "recorded_unresolved"
435
+ ]
436
+ },
437
+ "status": {
438
+ "enum": [
439
+ "unresolved"
440
+ ]
441
+ },
442
+ "must_preserve_disagreement": {
443
+ "type": "boolean"
444
+ }
445
+ }
446
+ },
447
+ "conflict": {
448
+ "type": "object",
449
+ "properties": {
450
+ "slot": {
451
+ "type": "string"
452
+ },
453
+ "status": {
454
+ "type": "string"
455
+ },
456
+ "reason": {
457
+ "type": "string"
458
+ },
459
+ "claims": {
460
+ "type": "array",
461
+ "items": {
462
+ "type": "object",
463
+ "properties": {
464
+ "page": {
465
+ "type": "string"
466
+ },
467
+ "value": {
468
+ "type": [
469
+ "string",
470
+ "number",
471
+ "null"
472
+ ]
473
+ },
474
+ "quote": {
475
+ "type": "string"
476
+ }
477
+ }
478
+ }
479
+ }
480
+ }
481
+ },
482
+ "status_block": {
483
+ "type": "object",
484
+ "description": "三个维度互相独立,不许互相推导。",
485
+ "required": [
486
+ "retrieval",
487
+ "support",
488
+ "stage"
489
+ ],
490
+ "properties": {
491
+ "retrieval": {
492
+ "enum": [
493
+ "none",
494
+ "direct",
495
+ "related",
496
+ "weak_only",
497
+ "unknown"
498
+ ],
499
+ "description": "检索层面:找到的页面有多可信"
500
+ },
501
+ "support": {
502
+ "enum": [
503
+ "sufficient",
504
+ "partial",
505
+ "insufficient"
506
+ ],
507
+ "description": "证据层面:找到的东西能不能回答这个槽位"
508
+ },
509
+ "stage": {
510
+ "enum": [
511
+ "no_candidates",
512
+ "unreadable",
513
+ "no_evidence",
514
+ "slot_unfilled",
515
+ "ok"
516
+ ],
517
+ "description": "管线停在哪一步"
518
+ },
519
+ "degraded": {
520
+ "type": "boolean",
521
+ "description": "有引擎故障/降级时 true;此时 support 不可单独采信"
522
+ },
523
+ "degraded_sources": {
524
+ "type": "array",
525
+ "items": {
526
+ "type": "string"
527
+ }
528
+ }
529
+ }
530
+ },
531
+ "context": {
532
+ "type": "object",
533
+ "required": [
534
+ "kind",
535
+ "contract_version",
536
+ "request_id",
537
+ "context_id",
538
+ "query",
539
+ "status",
540
+ "engines",
541
+ "evidence",
542
+ "missing",
543
+ "unresolved",
544
+ "conflicts",
545
+ "answer",
546
+ "timing_ms"
547
+ ],
548
+ "properties": {
549
+ "kind": {
550
+ "const": "context"
551
+ },
552
+ "contract_version": {
553
+ "const": "1.0"
554
+ },
555
+ "request_id": {
556
+ "type": "string",
557
+ "pattern": "^req_[A-Za-z0-9]+$"
558
+ },
559
+ "context_id": {
560
+ "type": "string",
561
+ "pattern": "^ctx_[A-Za-z0-9]+$"
562
+ },
563
+ "query": {
564
+ "type": "string",
565
+ "minLength": 1
566
+ },
567
+ "plan": {
568
+ "type": "object",
569
+ "properties": {
570
+ "original_query": {
571
+ "type": "string"
572
+ },
573
+ "query_units": {
574
+ "type": "array",
575
+ "items": {
576
+ "type": "object",
577
+ "required": [
578
+ "id",
579
+ "query"
580
+ ],
581
+ "properties": {
582
+ "id": {
583
+ "type": "string"
584
+ },
585
+ "query": {
586
+ "type": "string"
587
+ },
588
+ "query_variant": {
589
+ "enum": [
590
+ "original",
591
+ "decomposed",
592
+ "keyword"
593
+ ]
594
+ },
595
+ "slot": {
596
+ "type": [
597
+ "string",
598
+ "null"
599
+ ]
600
+ },
601
+ "anchors": {
602
+ "type": "array"
603
+ }
604
+ }
605
+ }
606
+ },
607
+ "anchors": {
608
+ "type": "array"
609
+ },
610
+ "has_constraint_anchor": {
611
+ "type": "boolean"
612
+ }
613
+ }
614
+ },
615
+ "engines": {
616
+ "type": "object",
617
+ "description": "两引擎结果永不合分、永不互推。",
618
+ "required": [
619
+ "search",
620
+ "wiki_recall"
621
+ ],
622
+ "properties": {
623
+ "requested": {
624
+ "enum": [
625
+ "both",
626
+ "search",
627
+ "plugin"
628
+ ]
629
+ },
630
+ "search": {
631
+ "$ref": "#/$defs/engine_slot"
632
+ },
633
+ "wiki_recall": {
634
+ "$ref": "#/$defs/engine_slot"
635
+ }
636
+ }
637
+ },
638
+ "status": {
639
+ "$ref": "#/$defs/status_block"
640
+ },
641
+ "evidence": {
642
+ "type": "array",
643
+ "items": {
644
+ "$ref": "#/$defs/evidence_page"
645
+ }
646
+ },
647
+ "evidence_items": {
648
+ "type": "array",
649
+ "items": {
650
+ "$ref": "#/$defs/evidence_item"
651
+ }
652
+ },
653
+ "missing": {
654
+ "type": "array",
655
+ "items": {
656
+ "$ref": "#/$defs/missing"
657
+ }
658
+ },
659
+ "unresolved": {
660
+ "type": "array"
661
+ },
662
+ "conflicts": {
663
+ "type": "array",
664
+ "items": {
665
+ "$ref": "#/$defs/conflict"
666
+ }
667
+ },
668
+ "conflict_status": {
669
+ "enum": [
670
+ "none_detected",
671
+ "conflict",
672
+ "incomparable",
673
+ "not_applicable",
674
+ "not_checked"
675
+ ]
676
+ },
677
+ "metrics": {
678
+ "type": "object"
679
+ },
680
+ "answer": {
681
+ "type": "object",
682
+ "required": [
683
+ "policy",
684
+ "constraints",
685
+ "contract_text"
686
+ ],
687
+ "properties": {
688
+ "policy": {
689
+ "type": "object"
690
+ },
691
+ "constraints": {
692
+ "type": "object"
693
+ },
694
+ "contract_text": {
695
+ "type": "string"
696
+ }
697
+ }
698
+ },
699
+ "observe_id": {
700
+ "type": [
701
+ "string",
702
+ "null"
703
+ ],
704
+ "pattern": "^obs_[A-Za-z0-9]+$"
705
+ },
706
+ "timing_ms": {
707
+ "type": "object",
708
+ "properties": {
709
+ "total": {
710
+ "type": "number"
711
+ },
712
+ "plan": {
713
+ "type": "number"
714
+ },
715
+ "retrieve": {
716
+ "type": "number"
717
+ },
718
+ "read": {
719
+ "type": "number"
720
+ },
721
+ "extract": {
722
+ "type": "number"
723
+ },
724
+ "policy": {
725
+ "type": "number"
726
+ },
727
+ "observe": {
728
+ "type": "number"
729
+ }
730
+ }
731
+ },
732
+ "error": {
733
+ "$ref": "#/$defs/err"
734
+ },
735
+ "support_reason": {
736
+ "allOf": [
737
+ {
738
+ "$ref": "#/$defs/support_reason"
739
+ }
740
+ ],
741
+ "description": "F3:support_status 的可解释性。不属于 required —— 老调用方不传不报错。"
742
+ }
743
+ }
744
+ },
745
+ "violation": {
746
+ "type": "object",
747
+ "required": [
748
+ "type",
749
+ "rule"
750
+ ],
751
+ "properties": {
752
+ "type": {
753
+ "enum": [
754
+ "conditional_limit_missing",
755
+ "answered_unfilled_slot",
756
+ "gap_not_disclosed",
757
+ "unresolved_disclosure_missing",
758
+ "unresolved_arbitrated",
759
+ "review_flag_missing",
760
+ "duplicate_as_independent",
761
+ "fabricated_quote",
762
+ "conclusion_without_evidence",
763
+ "unsupported_numeric_claim",
764
+ "numeric_check_failed"
765
+ ],
766
+ "description": "契约语义层类型"
767
+ },
768
+ "rule": {
769
+ "type": "string",
770
+ "description": "管线原始规则名,如 conditional.limit_not_with_claim"
771
+ },
772
+ "slot": {
773
+ "type": "string"
774
+ },
775
+ "claim": {
776
+ "type": "string",
777
+ "description": "被核验的回答原文片段(数值主张)"
778
+ },
779
+ "reason": {
780
+ "type": "string"
781
+ },
782
+ "page": {
783
+ "type": "string"
784
+ },
785
+ "status": {
786
+ "enum": [
787
+ "contradicted",
788
+ "scope_mismatch",
789
+ "unverifiable"
790
+ ],
791
+ "description": "数值判据的判定态:contradicted=同指标同范围数值冲突;scope_mismatch=证据适用范围不符;unverifiable=有一侧范围未知,不能视为匹配"
792
+ }
793
+ }
794
+ },
795
+ "verify": {
796
+ "type": "object",
797
+ "required": [
798
+ "kind",
799
+ "contract_version",
800
+ "context_id",
801
+ "status",
802
+ "violations"
803
+ ],
804
+ "properties": {
805
+ "kind": {
806
+ "const": "verify"
807
+ },
808
+ "contract_version": {
809
+ "const": "1.0"
810
+ },
811
+ "request_id": {
812
+ "type": "string"
813
+ },
814
+ "context_id": {
815
+ "type": "string",
816
+ "pattern": "^ctx_[A-Za-z0-9]+$"
817
+ },
818
+ "status": {
819
+ "enum": [
820
+ "ok",
821
+ "violations_found",
822
+ "context_missing",
823
+ "context_expired",
824
+ "context_corrupt"
825
+ ]
826
+ },
827
+ "violations": {
828
+ "type": "array",
829
+ "items": {
830
+ "$ref": "#/$defs/violation"
831
+ }
832
+ },
833
+ "checked_rules": {
834
+ "type": [
835
+ "integer",
836
+ "null"
837
+ ],
838
+ "description": "本次实际参与核验的规则条数;快照缺失时为空"
839
+ },
840
+ "snapshot_created": {
841
+ "type": [
842
+ "string",
843
+ "null"
844
+ ],
845
+ "description": "快照创建时间;快照缺失时为空"
846
+ },
847
+ "timing_ms": {
848
+ "type": "object"
849
+ },
850
+ "error": {
851
+ "$ref": "#/$defs/err"
852
+ },
853
+ "notices": {
854
+ "type": "array",
855
+ "items": {
856
+ "$ref": "#/$defs/notice"
857
+ },
858
+ "description": "非违规的核验提示;与 violations 分开,避免把「说不清」当成「说错了」"
859
+ }
860
+ }
861
+ },
862
+ "observe": {
863
+ "type": "object",
864
+ "required": [
865
+ "kind",
866
+ "contract_version",
867
+ "observe_id",
868
+ "ts"
869
+ ],
870
+ "properties": {
871
+ "kind": {
872
+ "const": "observe"
873
+ },
874
+ "contract_version": {
875
+ "const": "1.0"
876
+ },
877
+ "observe_id": {
878
+ "type": "string",
879
+ "pattern": "^obs_[A-Za-z0-9]+$"
880
+ },
881
+ "context_id": {
882
+ "type": [
883
+ "string",
884
+ "null"
885
+ ]
886
+ },
887
+ "ts": {
888
+ "type": "string"
889
+ },
890
+ "engine": {
891
+ "type": "string"
892
+ },
893
+ "query": {
894
+ "type": "string"
895
+ },
896
+ "status": {
897
+ "$ref": "#/$defs/status_block"
898
+ },
899
+ "metrics": {
900
+ "type": "object"
901
+ },
902
+ "logic": {
903
+ "type": "string",
904
+ "description": "查询逻辑清单(锚点/子问题/关键词),不含正文引文"
905
+ },
906
+ "timing_ms": {
907
+ "type": "object"
908
+ },
909
+ "error": {
910
+ "$ref": "#/$defs/err"
911
+ }
912
+ }
913
+ },
914
+ "notice": {
915
+ "type": "object",
916
+ "required": [
917
+ "rule",
918
+ "claim"
919
+ ],
920
+ "properties": {
921
+ "rule": {
922
+ "type": "string"
923
+ },
924
+ "claim": {
925
+ "type": "string"
926
+ },
927
+ "reason": {
928
+ "type": "string"
929
+ }
930
+ },
931
+ "description": "不阻断核验、但必须让调用方看见的提示(如 unverifiable 的数值主张)"
932
+ },
933
+ "support_reason_item": {
934
+ "type": "object",
935
+ "description": "一条可追溯的原因:code 是机器可判的原因码,detail 是人能读懂的一句话,slots/engines/stage 指向导致该原因的槽位、引擎或管线阶段。",
936
+ "required": [
937
+ "code",
938
+ "label",
939
+ "detail"
940
+ ],
941
+ "properties": {
942
+ "code": {
943
+ "type": "string",
944
+ "enum": [
945
+ "conflicting_evidence",
946
+ "no_candidates",
947
+ "no_usable_evidence",
948
+ "recorded_unresolved",
949
+ "required_slots_missing",
950
+ "partial_slot_coverage",
951
+ "conditional_evidence_only",
952
+ "scope_gap",
953
+ "conflict_candidate",
954
+ "engine_degraded",
955
+ "all_required_slots_supported",
956
+ "unknown"
957
+ ]
958
+ },
959
+ "label": {
960
+ "type": "string",
961
+ "description": "原因码的中文短标签"
962
+ },
963
+ "detail": {
964
+ "type": "string",
965
+ "minLength": 1,
966
+ "description": "为什么得到该原因,必须能追溯到实际槽位/证据/管线状态"
967
+ },
968
+ "slots": {
969
+ "type": "array",
970
+ "items": {
971
+ "type": "string"
972
+ }
973
+ },
974
+ "engines": {
975
+ "type": "array",
976
+ "items": {
977
+ "type": "string"
978
+ }
979
+ },
980
+ "stage": {
981
+ "type": "string",
982
+ "description": "pipeline.stage 的值"
983
+ }
984
+ },
985
+ "additionalProperties": false
986
+ },
987
+ "support_reason": {
988
+ "type": "object",
989
+ "description": "解释 support_status 是怎么来的。只解释现有判定,不改变 support_status、证据、provenance 或 answer_policy 结论;不判断用户答案对错。",
990
+ "required": [
991
+ "primary",
992
+ "primary_label",
993
+ "reasons"
994
+ ],
995
+ "properties": {
996
+ "primary": {
997
+ "type": "string",
998
+ "enum": [
999
+ "conflicting_evidence",
1000
+ "no_candidates",
1001
+ "no_usable_evidence",
1002
+ "recorded_unresolved",
1003
+ "required_slots_missing",
1004
+ "partial_slot_coverage",
1005
+ "conditional_evidence_only",
1006
+ "scope_gap",
1007
+ "conflict_candidate",
1008
+ "engine_degraded",
1009
+ "all_required_slots_supported",
1010
+ "unknown"
1011
+ ],
1012
+ "description": "解释 support_status 本身的主原因;有多个原因时取严重度最高的一条"
1013
+ },
1014
+ "primary_label": {
1015
+ "type": "string"
1016
+ },
1017
+ "reasons": {
1018
+ "type": "array",
1019
+ "minItems": 1,
1020
+ "description": "全部可识别原因,按严重度排序,不因 primary 而丢弃",
1021
+ "items": {
1022
+ "$ref": "#/$defs/support_reason_item"
1023
+ }
1024
+ }
1025
+ },
1026
+ "additionalProperties": false
1027
+ },
1028
+ "error_envelope": {
1029
+ "type": "object",
1030
+ "additionalProperties": false,
1031
+ "description": "失败响应。业务失败也走 200 + 这个信封,调用方按 error.code 分诊:E_PYTHON_UNAVAILABLE / E_BRIDGE_* 是环境问题,E_CONTEXT_* 是快照问题,E_QUERY_EMPTY / E_VERIFY_EMPTY_ANSWER 是入参问题。",
1032
+ "required": [
1033
+ "kind",
1034
+ "contract_version",
1035
+ "error"
1036
+ ],
1037
+ "properties": {
1038
+ "kind": {
1039
+ "const": "error"
1040
+ },
1041
+ "contract_version": {
1042
+ "const": "1.0"
1043
+ },
1044
+ "plugin_version": {
1045
+ "type": "string"
1046
+ },
1047
+ "bridge_version": {
1048
+ "type": "string"
1049
+ },
1050
+ "pipeline_version": {
1051
+ "type": "string"
1052
+ },
1053
+ "error": {
1054
+ "$ref": "#/$defs/err"
1055
+ }
1056
+ }
1057
+ },
1058
+ "observe_stats": {
1059
+ "type": "object",
1060
+ "required": [
1061
+ "kind",
1062
+ "contract_version",
1063
+ "observe_id",
1064
+ "ts",
1065
+ "window",
1066
+ "totals"
1067
+ ],
1068
+ "properties": {
1069
+ "kind": {
1070
+ "const": "observe_stats"
1071
+ },
1072
+ "contract_version": {
1073
+ "const": "1.0"
1074
+ },
1075
+ "observe_id": {
1076
+ "type": "string",
1077
+ "pattern": "^obs_[A-Za-z0-9]+$"
1078
+ },
1079
+ "ts": {
1080
+ "type": "string"
1081
+ },
1082
+ "window": {
1083
+ "type": "object",
1084
+ "required": [
1085
+ "days",
1086
+ "from",
1087
+ "to"
1088
+ ],
1089
+ "properties": {
1090
+ "days": {
1091
+ "type": "integer",
1092
+ "minimum": 1
1093
+ },
1094
+ "from": {
1095
+ "type": "string"
1096
+ },
1097
+ "to": {
1098
+ "type": "string"
1099
+ }
1100
+ }
1101
+ },
1102
+ "totals": {
1103
+ "type": "object",
1104
+ "required": [
1105
+ "contexts",
1106
+ "verifies"
1107
+ ],
1108
+ "properties": {
1109
+ "contexts": {
1110
+ "type": "integer",
1111
+ "minimum": 0
1112
+ },
1113
+ "verifies": {
1114
+ "type": "integer",
1115
+ "minimum": 0
1116
+ },
1117
+ "legacy": {
1118
+ "type": "integer",
1119
+ "minimum": 0
1120
+ },
1121
+ "malformed": {
1122
+ "type": "integer",
1123
+ "minimum": 0
1124
+ }
1125
+ }
1126
+ },
1127
+ "support_distribution": {
1128
+ "type": "object"
1129
+ },
1130
+ "retrieval_distribution": {
1131
+ "type": "object"
1132
+ },
1133
+ "support_reason_distribution": {
1134
+ "type": "object"
1135
+ },
1136
+ "violation_types": {
1137
+ "type": "object"
1138
+ },
1139
+ "recent": {
1140
+ "type": "array",
1141
+ "items": {
1142
+ "type": "object"
1143
+ }
1144
+ },
1145
+ "timing_ms": {
1146
+ "type": "object"
1147
+ },
1148
+ "revision": {
1149
+ "type": "object",
1150
+ "properties": {
1151
+ "contexts_verified": {
1152
+ "type": "integer",
1153
+ "minimum": 0
1154
+ },
1155
+ "corrected": {
1156
+ "type": "integer",
1157
+ "minimum": 0
1158
+ },
1159
+ "unresolved": {
1160
+ "type": "integer",
1161
+ "minimum": 0
1162
+ },
1163
+ "correction_rate": {
1164
+ "type": [
1165
+ "number",
1166
+ "null"
1167
+ ]
1168
+ },
1169
+ "sequences": {
1170
+ "type": "array",
1171
+ "items": {
1172
+ "type": "object"
1173
+ }
1174
+ }
1175
+ }
1176
+ }
1177
+ }
1178
+ }
1179
+ }
1180
+ }