@furongjun1999/dsh-memory 0.9.6 → 0.9.7

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 (216) hide show
  1. package/data/policy.json +38 -38
  2. package/docs/discipline/templates/spec.txt.tmpl +1 -1
  3. package/dsh/cordis.yml.example +139 -139
  4. package/lib/hooks.d.ts +19 -0
  5. package/lib/hooks.js +29 -6
  6. package/lib/index.js +11 -2
  7. package/lib/lib/hook_audit.js +38 -2
  8. package/lib/lib/prompt_safety.js +14 -3
  9. package/lib/tools.d.ts +7 -0
  10. package/lib/tools.js +22 -1
  11. package/md_cg/_guard_kit.py +121 -121
  12. package/md_cg/anchor.py +114 -114
  13. package/md_cg/audit.py +15 -2
  14. package/md_cg/chain.py +3 -2
  15. package/md_cg/config_registry_guard.py +487 -487
  16. package/md_cg/conformance.py +747 -747
  17. package/md_cg/consolidate.py +1793 -1793
  18. package/md_cg/crypto.py +794 -794
  19. package/md_cg/hyperedge.py +262 -262
  20. package/md_cg/interface_schema.py +146 -146
  21. package/md_cg/lifecycle.py +426 -426
  22. package/md_cg/mdcos.py +12 -8
  23. package/md_cg/predict.py +1103 -1103
  24. package/md_cg/protect.py +654 -654
  25. package/md_cg/provenance.py +606 -606
  26. package/md_cg/queue_health.py +130 -130
  27. package/md_cg/refine.py +613 -613
  28. package/md_cg/retrieve.py +128 -128
  29. package/md_cg/revise.py +140 -140
  30. package/md_cg/rollback.py +657 -657
  31. package/md_cg/rollback_cli.py +124 -124
  32. package/md_cg/rotate.py +346 -346
  33. package/md_cg/routing.py +490 -490
  34. package/md_cg/self_surface.py +50 -50
  35. package/md_cg/semantic/canonical.py +144 -144
  36. package/md_cg/semantic/zh_en_atoms.py +141 -141
  37. package/md_cg/sources.py +1091 -1091
  38. package/md_cg/stg.py +3 -2
  39. package/md_cg/test_audit_rotate_parity.py +279 -279
  40. package/md_cg/test_autonomy_modes.py +2013 -2013
  41. package/md_cg/test_cn_recall_grams.py +206 -206
  42. package/md_cg/test_code_kind_forbidden.py +101 -0
  43. package/md_cg/test_condaccept.py +156 -156
  44. package/md_cg/test_condgate.py +141 -141
  45. package/md_cg/test_heartbeat_ledger.py +557 -557
  46. package/md_cg/test_i50e_readside_protection.py +658 -658
  47. package/md_cg/test_issue111_gate_order.py +76 -76
  48. package/md_cg/test_issue111_scoring_contract.py +86 -86
  49. package/md_cg/test_issue121_calibration_bounds.py +293 -293
  50. package/md_cg/test_issue145_sleep_no_silent_rollback.py +167 -167
  51. package/md_cg/test_issue147_pack_id_escape.py +378 -378
  52. package/md_cg/test_issue148_merge_downgrade_leak.py +192 -192
  53. package/md_cg/test_issue149_accel_default_face.py +248 -248
  54. package/md_cg/test_issue150_empty_query_terms.py +328 -328
  55. package/md_cg/test_issue151_153_157_write_cache_index.py +151 -151
  56. package/md_cg/test_issue152_sealed_postings.py +309 -309
  57. package/md_cg/test_issue153b_index_generation_invalidation.py +142 -142
  58. package/md_cg/test_issue157b_index_remainder.py +344 -344
  59. package/md_cg/test_issue189_conclusion_bidirectional.py +223 -223
  60. package/md_cg/test_issue191_import_trust.py +382 -382
  61. package/md_cg/test_issue193_write_scope.py +378 -378
  62. package/md_cg/test_issue212_writeface_gaps.py +349 -349
  63. package/md_cg/test_issue214_reject_sensitivity.py +266 -266
  64. package/md_cg/test_issue215_condition_source_gap.py +272 -272
  65. package/md_cg/test_issue216_clash_routes.py +214 -214
  66. package/md_cg/test_issue217_slot_routes.py +248 -248
  67. package/md_cg/test_issue218_postcondition_value_blind.py +222 -222
  68. package/md_cg/test_issue258_pack_sensitivity.py +468 -468
  69. package/md_cg/test_issue265_coldverify_multiproc.py +438 -438
  70. package/md_cg/test_issue274_read_node_id_none.py +341 -341
  71. package/md_cg/test_issue275_layer_param.py +250 -250
  72. package/md_cg/test_issue277_node_id_traversal.py +384 -384
  73. package/md_cg/test_issue278_neg_separated_tension.py +271 -271
  74. package/md_cg/test_issue278_neg_window.py +294 -294
  75. package/md_cg/test_issue278_negative_layering.py +83 -83
  76. package/md_cg/test_issue284_skip_not_pass.py +291 -291
  77. package/md_cg/test_issue294_flywheel_sensitivity.py +573 -573
  78. package/md_cg/test_issue301_baseline_corpus_gate.py +245 -245
  79. package/md_cg/test_issue303_design_boundaries.py +262 -262
  80. package/md_cg/test_issue315_merge_branch_sensitivity.py +383 -383
  81. package/md_cg/test_issue319_tenant_unregistered_bypass.py +256 -256
  82. package/md_cg/test_issue321_mcp_deep_json.py +304 -304
  83. package/md_cg/test_issue322_node_write_lock.py +727 -727
  84. package/md_cg/test_issue324_write_size_fields.py +214 -214
  85. package/md_cg/test_issue325_audit_poison.py +229 -229
  86. package/md_cg/test_issue326_ingest_auto_whitelist.py +331 -331
  87. package/md_cg/test_issue326_key_perms.py +355 -355
  88. package/md_cg/test_issue326_twin_parser_parity.py +323 -323
  89. package/md_cg/test_issue326_vm_call_frame.py +569 -569
  90. package/md_cg/test_issue345_writelimit_effective_sens.py +233 -233
  91. package/md_cg/test_issue346_overwrite_sensitivity_gate.py +424 -424
  92. package/md_cg/test_issue348_insight_verify_op.py +199 -199
  93. package/md_cg/test_issue348_merge_rmw_lock.py +345 -345
  94. package/md_cg/test_issue350_casefold_collision.py +235 -235
  95. package/md_cg/test_issue351_ingest_root_fallback.py +201 -201
  96. package/md_cg/test_issue352_imgaudit.py +418 -418
  97. package/md_cg/test_issue352_pathsjson.py +537 -537
  98. package/md_cg/test_issue352_refindex.py +412 -412
  99. package/md_cg/test_issue352_rollback.py +604 -604
  100. package/md_cg/test_issue354_p2_writelimit_toctou.py +327 -327
  101. package/md_cg/test_issue354_rust_index_containment.py +571 -571
  102. package/md_cg/test_issue354_rust_wal_containment.py +606 -606
  103. package/md_cg/test_issue358_truncation_observable.py +247 -247
  104. package/md_cg/test_issue360_tidy_private_excerpt.py +195 -195
  105. package/md_cg/test_issue361_blindspot_not_silent_drop.py +494 -494
  106. package/md_cg/test_issue362_neg_condition.py +468 -468
  107. package/md_cg/test_issue363_lexical_idf.py +275 -275
  108. package/md_cg/test_issue370_readcache_assembly.py +488 -488
  109. package/md_cg/test_issue376_heartbeat_failed.py +293 -293
  110. package/md_cg/test_issue377_layer_protect_stamp.py +324 -324
  111. package/md_cg/test_issue378_protected_floor.py +310 -310
  112. package/md_cg/test_issue383_state_event_write_gate.py +462 -462
  113. package/md_cg/test_issue397_sens_eff_wiring.py +435 -435
  114. package/md_cg/test_issue398_toolface_op_parity.py +511 -511
  115. package/md_cg/test_issue399_hive_json_shape.py +317 -317
  116. package/md_cg/test_issue401_wisdom_codegen.py +295 -295
  117. package/md_cg/test_issue404_heal_receipt.py +389 -389
  118. package/md_cg/test_issue409_compact_index_completeness.py +509 -509
  119. package/md_cg/test_issue410_verify_demote_write.py +366 -366
  120. package/md_cg/test_issue411_scrub_idempotence.py +575 -575
  121. package/md_cg/test_issue412_discipline_producer_parity.py +311 -311
  122. package/md_cg/test_issue413_preimage_failclosed.py +239 -239
  123. package/md_cg/test_issue413_preimage_twin.py +339 -339
  124. package/md_cg/test_issue415_deps_gate_probe.py +357 -357
  125. package/md_cg/test_issue416_entry_key_subset.py +525 -525
  126. package/md_cg/test_issue417_twophase_merge_landed.py +423 -423
  127. package/md_cg/test_issue425_ingest_library_path.py +331 -331
  128. package/md_cg/test_issue426c_enqueue_not_silent.py +346 -346
  129. package/md_cg/test_issue426e_restore_overwrite_live.py +310 -310
  130. package/md_cg/test_issue426f_paths_gbk_failclosed.py +301 -301
  131. package/md_cg/test_issue427_serve_status_shape.py +191 -191
  132. package/md_cg/test_issue431_432_468_protect_single_point.py +322 -322
  133. package/md_cg/test_issue433_outlook_threshold_single_point.py +278 -278
  134. package/md_cg/test_issue434_435_float_gate.py +90 -90
  135. package/md_cg/test_issue439_sibling_sensitivity_inherit.py +448 -448
  136. package/md_cg/test_issue43_default_policy.py +874 -874
  137. package/md_cg/test_issue444_scrub_evidence_plaintext.py +281 -281
  138. package/md_cg/test_issue445_metacognition_ledger_gate.py +454 -454
  139. package/md_cg/test_issue446_453_403_verified_evidence.py +382 -382
  140. package/md_cg/test_issue450_sensitivity_fallback_reason.py +51 -51
  141. package/md_cg/test_issue450_writegate_unknown_sens.py +203 -203
  142. package/md_cg/test_issue451_audit_actor.py +313 -313
  143. package/md_cg/test_issue452_ingest_root_sensitivity.py +299 -299
  144. package/md_cg/test_issue463_ghost_prune_guard.py +259 -259
  145. package/md_cg/test_issue466_basis_registry.py +469 -469
  146. package/md_cg/test_issue467_identity_sensitivity_parity.py +360 -360
  147. package/md_cg/test_issue469_scrub_override_passthrough.py +126 -126
  148. package/md_cg/test_issue470_wal_event_durable.py +427 -427
  149. package/md_cg/test_issue471_identity_readable.py +136 -136
  150. package/md_cg/test_issue472_audit_chain.py +90 -90
  151. package/md_cg/test_issue472_prune_ledger.py +105 -105
  152. package/md_cg/test_issue472_rollback_degraded.py +81 -81
  153. package/md_cg/test_issue491_compose_sandbox.py +460 -460
  154. package/md_cg/test_issue498_merge_trace_stale_index.py +280 -280
  155. package/md_cg/test_issue511_scoreboard_bad_files.py +256 -256
  156. package/md_cg/test_issue521_rotate_lock_suffix.py +110 -110
  157. package/md_cg/test_issue524_orphan_noise_no_demote.py +88 -88
  158. package/md_cg/test_issue525_read_null_semantics.py +52 -52
  159. package/md_cg/test_issue547_append_jsonl_whitelist.py +114 -114
  160. package/md_cg/test_issue547_audit_durable.py +96 -96
  161. package/md_cg/test_issue557_r2_write_entries_size_gate.py +83 -83
  162. package/md_cg/test_issue559_refine_prefix.py +69 -69
  163. package/md_cg/test_issue562_retired_faces.py +150 -0
  164. package/md_cg/test_issue71_queue_backlog.py +376 -376
  165. package/md_cg/test_issue72_coldverify_controlled_drain.py +420 -420
  166. package/md_cg/test_issue82_credential_rules.py +271 -271
  167. package/md_cg/test_issue91_verifier_sandbox.py +314 -314
  168. package/md_cg/test_issue93_remember_redaction.py +282 -282
  169. package/md_cg/test_logref.py +1141 -1141
  170. package/md_cg/test_md_access_parity.py +330 -330
  171. package/md_cg/test_md_cg_no_hive_dep.py +139 -139
  172. package/md_cg/test_mutation_residue.py +119 -119
  173. package/md_cg/test_mutation_rollback.py +835 -835
  174. package/md_cg/test_n123_derive_expiry_chain.py +210 -210
  175. package/md_cg/test_n209_verify_write_face_gates.py +466 -466
  176. package/md_cg/test_n62_tenant_bind_failclosed.py +200 -200
  177. package/md_cg/test_neg_tail_honesty.py +733 -733
  178. package/md_cg/test_p21_tokens.py +294 -294
  179. package/md_cg/test_p27_docindex.py +792 -792
  180. package/md_cg/test_p28_refcheck.py +1053 -1053
  181. package/md_cg/test_p2_six_elements.py +476 -476
  182. package/md_cg/test_p33_ccg_wiring.py +300 -300
  183. package/md_cg/test_p3_legacy_closure.py +438 -438
  184. package/md_cg/test_p40_refine_worklist.py +244 -244
  185. package/md_cg/test_p4_freshness.py +781 -781
  186. package/md_cg/test_p9c_dedup_hints.py +288 -288
  187. package/md_cg/test_policy_required_ccg.py +444 -444
  188. package/md_cg/test_retr_s5.py +312 -312
  189. package/md_cg/test_s1_ast_judge.py +109 -109
  190. package/md_cg/test_state_event_op.py +521 -521
  191. package/md_cg/test_stgidx_index_parity.py +1024 -1024
  192. package/md_cg/test_sustain_bounded.py +652 -652
  193. package/md_cg/test_trust_edge_reachability.py +405 -405
  194. package/md_cg/test_w7_redlines.py +659 -659
  195. package/md_cg/test_write_return_shape.py +919 -919
  196. package/md_cg/test_writepipe.py +228 -228
  197. package/md_cg/trust.py +1114 -1114
  198. package/md_cg/twophase.py +303 -303
  199. package/md_cg/whitebox.py +536 -536
  200. package/md_cg/whitebox_kb/wisdom/compose_engine.py +1634 -1634
  201. package/md_cg/whitebox_kb/wisdom/core/condition_vm.py +318 -318
  202. package/md_cg/whitebox_kb/wisdom/core/parser.py +1082 -1082
  203. package/md_cg/whitebox_kb/wisdom/md_access.py +490 -490
  204. package/md_cg/whitebox_kb/wisdom/migrate_wisdom.py +497 -497
  205. package/md_cg/whitebox_kb/wisdom/mini_python.py +995 -995
  206. package/md_cg/whitebox_kb/wisdom/net_units.py +2900 -2900
  207. package/md_cg/whitebox_kb/wisdom/semantic_translate.py +4060 -4060
  208. package/md_cg/writepipe.py +1337 -1337
  209. package/package.json +3 -2
  210. package/scripts/workspace_index.py +328 -0
  211. package/src/hooks.ts +30 -6
  212. package/src/index.ts +14 -5
  213. package/src/lib/hook_audit.ts +282 -256
  214. package/src/lib/mdcg_client.ts +469 -469
  215. package/src/lib/prompt_safety.ts +17 -3
  216. package/src/tools.ts +23 -1
@@ -1,469 +1,469 @@
1
- /**
2
- * mdcg_client.ts —— 认知图显式客户端(LIB 本地库)
3
- *
4
- * 架构定位(2026-09-10 决定)
5
- * --------------------------
6
- * · md_cg = 记忆操作系统 / **唯一真源**(记忆的写、读、裁决、留痕)。
7
- * · AEIS = **能力库**(白箱引擎、角色扮演生成等),不再是记忆真源。
8
- *
9
- * 本模块是插件侧调用 md_cg 的**唯一显式入口**:只暴露 `cg` / `stg` 两个
10
- * 认知基元,每个方法 = 一条 MCP 调用,不做隐式魔法。
11
- *
12
- * 显式调用映射(详见 docs/功能调用映射表_v0.1.md)
13
- * ------------------------------------------------
14
- * 路由/召回 → MdcgClient.route() → MCP cg(op=route)
15
- * 读取节点 → MdcgClient.read() → MCP cg(op=read)
16
- * 记忆沉淀 → MdcgClient.remember() → MCP mdcg_remember(gated=true)
17
- * 语义召回 → MdcgClient.recall() → MCP cg(op=read, query)
18
- * 写入记忆 → MdcgClient.write() → MCP mdcg_remember(gated=false)
19
- * 外部裁决回填 → MdcgClient.verify() → MCP cg(op=verify)
20
- * 最近记忆时间线 → MdcgClient.timeline() → MCP stg(op=timeline)
21
- * 近期事件窗口 → MdcgClient.recent() → MCP cg(op=recent)
22
- * 窗口追加事件 → MdcgClient.recentAdd() → MCP cg(op=recent, action=add)
23
- * 会话续接包 → MdcgClient.sessionRecall() → MCP cg(op=session, action=recall)
24
- * 身份读取 → MdcgClient.identity() → MCP cg(op=identity)
25
- * 白箱能力验证 → MdcgClient.whitebox() → MCP cg(op=whitebox)
26
- * 服务信息 → MdcgClient.serviceInfo()→ MCP cg(op=info)
27
- * 互维主张核验 → MdcgClient.verifyClaim()→ cg(op=read) + 依据强度判定
28
- * 角色/转录落图 → MdcgClient.writeRole() / writeTranscript() → mdcg_remember
29
- *
30
- * 写入为什么不能走 cg(op=write)(关键约束,勿回退)
31
- * ------------------------------------------------
32
- * `cg(op=write)` 是**带审核**的写路径:先过 `audit.audit(content_kind)`,
33
- * 未声明 content_kind 且未配置 `MDCG_POLICY_FILE` 时恒判 BLINDSPOT/DEFER ——
34
- * 只进审核队列、**永不落盘**(自动记忆会静默全失败,实测 0 篇 md 文档)。
35
- * 而 `mdcg_remember`(`md_cg/mcp_server.py:1691`)直接调 `MdCG.remember_gated`
36
- * / `MdCG.add`,跳过审核,是 mcp_server 顶部文档定义的「写」入口。故本客户端
37
- * 的**所有写入**(记忆沉淀 / 角色定义 / 对话转录)统一经 `mdcg_remember`。
38
- */
39
-
40
- import { delimiter } from 'node:path'
41
- import { LingshuBridge, type McpCallResult } from '../bridge.js'
42
- import { pythonPathValue, runRoot } from './datapath.js'
43
- // 租户单点(#224):签发侧(token_store)与运行侧(本文件的 mdcgChildEnv)必须
44
- // 用同一函数算出租户——N62 之后服务端对「令牌记录租户 ≠ 入参租户」fail-closed,
45
- // 两侧各算一遍就必然分叉(签发按 default、运行按 work ⇒ rc=3 拒启)。
46
- import { effectiveTenant } from './token_store.js'
47
-
48
- /** md_cg 子进程与根目录配置。 */
49
- export interface MdcgOptions {
50
- /** Python 可执行文件,默认取 config.python。 */
51
- python: string
52
- /** 启动参数,默认 ['-m', 'md_cg.mcp_server']。 */
53
- args?: string[]
54
- /** 认知图根目录(MDCG_ROOT)。 */
55
- root: string
56
- /** Python 子进程工作目录,默认 `runRoot()`——**插件包目录之外**的稳定目录
57
- * (issue #18:Windows 不允许删除/改名「正被某进程当作 cwd」的目录,
58
- * cwd 落在包内会让 pnpm 更新本包必然 `ERR_PNPM_EBUSY` 且永不自愈)。
59
- * 模块解析**不依赖 cwd**:`python -m` 靠 `PYTHONPATH`
60
- * (见 `pythonPathValue()`)解析随包 md_cg,issue #12 口径不变。
61
- * 显式传入本项时完全尊重原值。 */
62
- cwd?: string
63
- /** 调用主体标识(MDCG_ACTOR)。私有内容按 (tenant, actor) 派生 DEK,
64
- * 故与迁移脚本 --actor 必须一致,否则读不到已迁移节点。 */
65
- actor?: string
66
- /** 租户(MDCG_TENANT),默认 default。 */
67
- tenant?: string
68
- /** 调用方密级(MDCG_CLEARANCE):只能读写 ≤ 该密级的节点,默认 private。 */
69
- clearance?: string
70
- /** 身份主体(MDCG_IDENTITY)。 */
71
- identity?: string
72
- /** 额外环境变量。 */
73
- env?: Record<string, string>
74
- /** MCP 工具面(MDCG_MCP_SURFACE):'kernel' = 仅 cg/stg 两基元;
75
- * 'full' = 另含 `mdcg_*` 细粒度工具。
76
- *
77
- * ⚠️ 本客户端**必须**用 full:唯一写入通道是 `mdcg_remember`(细粒度),
78
- * kernel 面下该工具不存在 → 写入静默失败(角色/转录/自动记忆全部不落盘)。
79
- * 默认 'full',勿改。 */
80
- surface?: 'kernel' | 'full'
81
- timeoutMs?: number
82
- maxRetryDelayMs?: number
83
- }
84
-
85
- const DEFAULT_ARGS = ['-m', 'md_cg.mcp_server']
86
-
87
- /** 子进程环境构造参数(`MdcgOptions` 中与环境相关的那半)。 */
88
- export interface MdcgChildEnvOptions {
89
- root: string
90
- surface?: 'kernel' | 'full'
91
- tenant?: string
92
- clearance?: string
93
- actor?: string
94
- identity?: string
95
- env?: Record<string, string>
96
- }
97
-
98
- /**
99
- * MCP 子进程环境:**唯一构造点**(导出即为了让机械守卫能断言它——
100
- * 见 `test/python-utf8-mode.test.ts`)。勿在别处另拼 env。
101
- *
102
- * ⚠️ 两条编码注入是**硬约束**,不是可选项:
103
- *
104
- * ① `PYTHONIOENCODING=utf-8`(子进程**自身** stdio):Windows 下 piped 子进程默认
105
- * gbk + surrogateescape,Node 写出的 UTF-8 中文会被解成孤立代理字符(\udcXX),
106
- * md_cg 在落盘 / 回写 stdout 时抛 UnicodeEncodeError——中文记忆(主场景)全失败。
107
- *
108
- * ② `PYTHONUTF8=1`(子进程**后代**的默认 text 编码,PEP 540):`PYTHONIOENCODING`
109
- * 会被后代继承(后代于是往管道写 UTF-8),但**文本解码口径不被继承**——后代读
110
- * `subprocess.run(..., text=True)` 时取的是 locale(本机 cp936),于是
111
- * 「子进程写 UTF-8、父进程按 gbk 读」→ 读线程崩死、诊断静默丢失。
112
- * 2026-09-20 实证现场(`npm test` 周期复现,来源为子进程的后代代码单元):
113
- * Exception in thread Thread-N (_readerthread):
114
- * UnicodeDecodeError: 'gbk' codec can't decode byte 0x82 in position 181
115
- * UTF-8 模式把默认 text 编码改为 UTF-8,读写两侧同口径(且解码结果正确,
116
- * 而非 `errors="replace"` 那种替换字符)。
117
- *
118
- * 确定性对照实验(P1 复现 / P3 消除)见 `test/python-utf8-mode.test.ts`。
119
- * `opts.env` 最后展开——显式覆盖优先。**唯一例外是 `MDCG_TENANT`**(#224):
120
- * 它由 `effectiveTenant()` 单点决定(`opts.env.MDCG_TENANT` > `opts.tenant` >
121
- * default),放在 `opts.env` 之后写入——否则 `opts.env` 里的空串/其它值会把
122
- * 「签发侧算出的租户」再覆盖一次,两侧分叉。其余键的覆盖顺序不变。
123
- */
124
- export function mdcgChildEnv(opts: MdcgChildEnvOptions): Record<string, string> {
125
- return {
126
- PYTHONIOENCODING: 'utf-8',
127
- PYTHONUTF8: '1',
128
- MDCG_ROOT: opts.root,
129
- // 工具面必须是 full:写入通道 mdcg_remember 属细粒度工具(见 MdcgOptions.surface)。
130
- MDCG_MCP_SURFACE: opts.surface ?? 'full',
131
- MDCG_CLEARANCE: opts.clearance ?? 'private',
132
- PYTHONPATH: pythonPathValue(),
133
- ...(opts.actor ? { MDCG_ACTOR: opts.actor } : {}),
134
- ...(opts.identity ? { MDCG_IDENTITY: opts.identity } : {}),
135
- ...(opts.env ?? {}),
136
- // 租户单点(见 effectiveTenant):与 token_store 签发/复核同一口径。
137
- MDCG_TENANT: effectiveTenant(opts.tenant, opts.env),
138
- }
139
- }
140
-
141
- /** 认知图依据强度:这些 basis 视为「强依据」,可支撑 pass。
142
- * 取值须在 md_cg.mdcg.VERIFICATION_BASIS 允许集内:
143
- * compiler | test | measurement | formal_proof | data | other(other 不算强依据)。 */
144
- const STRONG_BASIS = new Set(['compiler', 'test', 'measurement', 'formal_proof', 'data'])
145
-
146
- /**
147
- * 请求级**单元身份**(MCP 参数 `as_unit`)。
148
- *
149
- * 与 `md_cg/tokens.py` 的 `POSITION_ROLES` 同源(record/reflect/verify/
150
- * output/sustain);大脑侧 `narrowed_principal` 对未知值 fail-closed 报错。
151
- *
152
- * 语义(关键):`as_unit` 只能**收窄**权限、不能放大——大脑侧以「与 owner 求交 +
153
- * 管理权恒 False」保证,故填错的最坏结果等于不填(owner 全权),**不可能提权**。
154
- *
155
- * 本客户端**只在写入 / 裁决路径注入**,且只注入与落层确定匹配的单元:
156
- * · 记忆沉淀 / 转录 / 角色定义 → `record`(落 contextual / knowledge,在 record
157
- * 的 layers_allow 内);
158
- * · 外部裁决回填 → `verify`(cg op=verify)。
159
- * **只读调用一律不注入**:record / output 的 `clearance_cap=internal`,注入会把
160
- * owner 的 private 读能力一并压低(读不到私有记忆=功能退化),而读无副作用,
161
- * 收窄无收益。`write()` 同样不注入——它被用于写 self / structural 层(角色锚点
162
- * 需 designer 权限),注入 `record` 会直接打断角色落图。
163
- */
164
- export type LingshuUnit = 'record' | 'reflect' | 'verify' | 'output' | 'sustain'
165
-
166
- function collectItems(payload: unknown): Array<Record<string, unknown>> {
167
- if (Array.isArray(payload)) return payload as Array<Record<string, unknown>>
168
- if (payload && typeof payload === 'object') {
169
- const obj = payload as Record<string, unknown>
170
- for (const key of ['results', 'items', 'nodes', 'hits', 'data', 'records']) {
171
- if (Array.isArray(obj[key])) return obj[key] as Array<Record<string, unknown>>
172
- }
173
- }
174
- return []
175
- }
176
-
177
- /**
178
- * 认知图显式客户端。
179
- *
180
- * 生命周期与桥一致:懒启动 + 自动重连;未就绪时调用会快速失败。
181
- * 未就绪的处置:互维 verify 走 fail-closed(见 index.ts 的注入),
182
- * 自动记忆静默跳过——**不再有"回退 aeis 能力库"路径**(该库已剥离)。
183
- */
184
- export class MdcgClient {
185
- readonly bridge: LingshuBridge
186
-
187
- constructor(opts: MdcgOptions) {
188
- // 子进程 cwd 必须落在插件包目录之外,否则 pnpm 更新本插件时
189
- // rmdir 包目录会撞上 Windows 的「目录被当作 CWD」共享冲突 → ERR_PNPM_EBUSY。
190
- // 模块解析不依赖 cwd:PYTHONPATH(pythonPathValue())已锚定随包 md_cg;
191
- // opts.env 显式提供 PYTHONPATH 时完全接管(其展开在最后)。详见 datapath.runRoot()。
192
- const cwd = opts.cwd ?? runRoot()
193
- // 编码与模块解析口径见 mdcgChildEnv() 头注(含 2026-09-20 读线程崩溃现场)。
194
- const env = mdcgChildEnv(opts)
195
- this.bridge = new LingshuBridge({
196
- python: opts.python,
197
- args: opts.args ?? DEFAULT_ARGS,
198
- env,
199
- cwd,
200
- timeoutMs: opts.timeoutMs ?? 60_000,
201
- maxRetryDelayMs: opts.maxRetryDelayMs ?? 30_000,
202
- })
203
- }
204
-
205
- start(): void {
206
- this.bridge.start()
207
- }
208
-
209
- async waitReady(): Promise<boolean> {
210
- return this.bridge.waitReady()
211
- }
212
-
213
- /** 桥是否已握手就绪。
214
- *
215
- * ⚠️ 不可缓存 waitReady() 的结果:waitReady() 在**首次心跳失败**时会立即
216
- * resolve(false)(见 bridge.ts 的 failed 分支),但桥仍会后台重连成功——
217
- * 若把这次 false 缓存下来,isReady() 将永久为假,自动记忆 / 互维核验会在
218
- * 重连成功后静默失效。故一律以桥的实时状态为准。 */
219
- isReady(): boolean {
220
- return this.bridge.isReady()
221
- }
222
-
223
- dispose(): void {
224
- this.bridge.dispose()
225
- }
226
-
227
- /** 原始 cg 调用(逃生口;显式传参,不做推断)。
228
- * `asUnit` = 本次调用的请求级单元身份(见 LingshuUnit);只收窄、不提权。 */
229
- async cg(args: Record<string, unknown>, asUnit?: LingshuUnit): Promise<unknown> {
230
- return this.call('cg', args, asUnit)
231
- }
232
-
233
- /** 原始 stg 调用(时间线/关系/锚点/一致性)。 */
234
- async stg(args: Record<string, unknown>, asUnit?: LingshuUnit): Promise<unknown> {
235
- return this.call('stg', args, asUnit)
236
- }
237
-
238
- private async call(tool: string, args: Record<string, unknown>,
239
- asUnit?: LingshuUnit): Promise<unknown> {
240
- // as_unit 由大脑侧 mcp_server.call_tool 在同一进程内消费并收窄 principal,
241
- // 不从 args 向下透传,故不会污染各 tool handler 的参数解析。
242
- const payload = asUnit ? { ...args, as_unit: asUnit } : args
243
- const result: McpCallResult = await this.bridge.callTool(tool, payload)
244
- const text = (result.content ?? [])
245
- .filter((c) => c.type === 'text')
246
- .map((c) => c.text ?? '')
247
- .join('')
248
- if (result.isError) throw new Error(text || `md_cg ${tool} 调用失败`)
249
- try {
250
- return JSON.parse(text)
251
- } catch {
252
- return text
253
- }
254
- }
255
-
256
- // -- 显式认知能力(每个方法一条 MCP 调用) --------------------------------
257
-
258
- /** 路由:意图 → 相关知识 + 建议能力。 */
259
- route(intent: string, extra: Record<string, unknown> = {}): Promise<unknown> {
260
- return this.cg({ op: 'route', intent, ...extra })
261
- }
262
-
263
- /** 读取:按语义召回节点。 */
264
- read(query: string, extra: Record<string, unknown> = {}): Promise<unknown> {
265
- return this.cg({ op: 'read', query, ...extra })
266
- }
267
-
268
- /** 按 id 精确读取单个节点。 */
269
- get(nodeId: string): Promise<unknown> {
270
- return this.cg({ op: 'read', node_id: nodeId })
271
- }
272
-
273
- /** 认知图写入入口(MCP `mdcg_remember`)。
274
- *
275
- * ⚠️ 唯一写入通道:**不可**改用 `cg(op=write)`(那条路径会被 audit 拦住,
276
- * 见文件头「写入为什么不能走 cg(op=write)」)。gated=false 直写 `MdCG.add`
277
- * (默认 layer=knowledge),gated=true 走主动遗忘闸门。 */
278
- private writeNode(args: Record<string, unknown>,
279
- asUnit?: LingshuUnit): Promise<unknown> {
280
- return this.call('mdcg_remember', args, asUnit)
281
- }
282
-
283
- /** 写入:新增/覆盖一个记忆节点(直写 `MdCG.add`,不经审核队列)。 */
284
- write(content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
285
- return this.writeNode({ content, ...extra })
286
- }
287
-
288
- /** 记忆沉淀(AEIS `remember` 的对应物):写入情景层并过**主动遗忘闸门**。
289
- *
290
- * `mdcg_remember(gated=true)` → `MdCG.remember_gated`:三问 → 四态,
291
- * ACCEPT 落盘 / MERGE 并入既有(= 去重强化,不新增节点)/ DROP 丢弃低熵
292
- * 噪音 / DEFER 待定;四种结果都写 `_forgetting.jsonl`,可审计。
293
- * `importance` 作为 importance_hint 传入(≥0.7 时保护优先、直接 ACCEPT)。
294
- *
295
- * layer 默认 contextual:md_cg 对 DSH 会话事件约定的落层就是 contextual,
296
- * role 取 user | assistant | tool-output(见 md_cg/sources.py 的
297
- * SESSION_LAYER / DSHSessionSource 事件映射)。 */
298
- remember(content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
299
- // 落层 contextual 固定在 record 白名单内 → 声明 record 单元(不得写 self/anchor)。
300
- return this.writeNode({ content, gated: true, layer: 'contextual', ...extra }, 'record')
301
- }
302
-
303
- /** 语义召回(AEIS `recall` 的对应物):`cg(op=read, query)` → md_cg 检索。
304
- * 读取会记 access log(复用观测),供 importance / scrub 陈旧度使用。 */
305
- recall(query: string, k = 5): Promise<unknown> {
306
- return this.read(query, { k })
307
- }
308
-
309
- /** 外部裁决回填:为已有节点写 confirmed/weakened/falsified。 */
310
- verify(nodeId: string, evidence: string, verdict: string): Promise<unknown> {
311
- // 裁决回填声明 verify 单元:只写 rejected/contextual,不得改被验证内容。
312
- return this.cg({ op: 'verify', node_id: nodeId, evidence, verdict }, 'verify')
313
- }
314
-
315
- /** 最近记忆。 */
316
- recent(limit = 20): Promise<unknown> {
317
- return this.cg({ op: 'recent', limit })
318
- }
319
-
320
- /** 追加一条**近期事件窗口**记录(`cg(op=recent, action=add)` →
321
- * `md_cg` 的 `remember_event(role, text, tags, meta, window)`)。
322
- *
323
- * 这是「滑动窗口」写侧:事件落 `_recent.jsonl`(**运行态面**),按窗口滚动
324
- * 淘汰(服务端缺省 200 条,`mdcg.py:91 DEFAULT_RECENT_WINDOW`)——它**不是
325
- * 知识节点**:不占 knowledge 层、不进检索正排,与 `remember()` 的知识面沉淀
326
- * 是两条独立的轨道(见 src/hooks.ts 文件头的 contextWindow 头注)。
327
- *
328
- * ⚠️ **不注入 as_unit**(与 `write()` 同款理由的反面):本调用不写任何层的
329
- * 节点(服务端 `remember_event` 不做层白名单校验),收窄单元无收益且可能压低
330
- * 事件密级(缺省 internal);`meta.session` 由调用方显式给出(沿本文件
331
- * `remember()` 的 sessionTag 口径)。
332
- *
333
- * ⚠️ 服务端对 `meta` 做 `setdefault`(tenant/session/harness/unit,见
334
- * `mdcos.py:5057 remember_event`):调用方已写的键**不被覆盖**。 */
335
- recentAdd(role: string, text: string,
336
- meta: Record<string, unknown> = {},
337
- tags: string[] = []): Promise<unknown> {
338
- return this.cg({ op: 'recent', action: 'add', role, text, meta, tags })
339
- }
340
-
341
- /** **会话续接包**(`cg(op=session, action=recall)` → `md_cg` 的
342
- * `session_recall`):一次取回 notes / goals / tasks / **recent 事件窗口** /
343
- * unresolved / self_state,按 `budget_tokens` 整包裁剪(服务端
344
- * `mdcos.py:3351-3362`:交替丢 recent / notes 尾部)。
345
- *
346
- * 本插件消费其中的 `recent` 段——滑动窗口的**注入面**(见 src/hooks.ts)。
347
- * `recent_limit` 语义 = 近期事件**条数**(非「轮数」);服务端读取时会按
348
- * `max(1, recent_limit or 10)` 归一(`mdcos.py:3309`)。
349
- *
350
- * ⚠️ 两条服务端事实(决定注入侧的可达性,勿据本方法名臆测):
351
- * ① `recent` 段取 `recent_events(limit=recent_limit)` —— **不按 session
352
- * 过滤**(近期事件是运行态滚动窗口,会话归属只写在每条事件的 meta 里);
353
- * ② budget 是**整包**预算:库内 notes/tasks/self_state 占位越多,同样
354
- * budget 下 recent 段被裁得越短(实测:空库 + 10 条窗口条目,
355
- * budget_tokens=600 → recent 8 条;1200 → 10 条)。
356
- *
357
- * 只读调用,不注入 as_unit(同其它读路径:读无副作用,收窄只会压低 owner
358
- * 的 private 读能力)。 */
359
- sessionRecall(session: string, recentLimit: number, budgetTokens: number): Promise<unknown> {
360
- return this.cg({
361
- op: 'session', action: 'recall',
362
- session, recent_limit: recentLimit, budget_tokens: budgetTokens,
363
- })
364
- }
365
-
366
- /** 最近记忆**时间线**(AEIS `timeline` 的对应物):`stg(op=timeline)` →
367
- * `{count, limit, items:[{id, layer, start, end, preview}]}`,按时间倒序。
368
- *
369
- * 只收录带时间区间的节点;而 `cg.add()` 在调用方未给 time_window 时会以
370
- * **写入时刻**自动填充(见 mdcg.py 的 OBSERVATION_WINDOW_SEC 分支),故经
371
- * 本客户端写入的记忆都能进入时间线。
372
- * 要原始近期**事件**(未结构化对话窗口)请用 `recent()`。 */
373
- timeline(limit = 4, extra: Record<string, unknown> = {}): Promise<unknown> {
374
- return this.stg({ op: 'timeline', limit, desc: true, ...extra })
375
- }
376
-
377
- /** 身份维度读取。 */
378
- identity(subjectId?: string, extra: Record<string, unknown> = {}): Promise<unknown> {
379
- return this.cg({ op: 'identity', ...(subjectId ? { subject_id: subjectId } : {}), ...extra })
380
- }
381
-
382
- /** 白箱能力库:显式调用 + 能力验证。 */
383
- whitebox(action: string, extra: Record<string, unknown> = {}): Promise<unknown> {
384
- return this.cg({ op: 'whitebox', action, ...extra })
385
- }
386
-
387
- /** 服务信息(信任透明度)。 */
388
- serviceInfo(): Promise<unknown> {
389
- return this.cg({ op: 'info' })
390
- }
391
-
392
- // -- 语义化封装(互维 / 角色扮演显式使用认知图) --------------------------
393
-
394
- /**
395
- * 互维主张核验(memory 通道):用认知图替代 AEIS `wisdom_verify`。
396
- * 返回结构与 VerifyResult['whitebox'] 对齐,便于直接注入 mutual。
397
- */
398
- async verifyClaim(claim: string): Promise<{
399
- judgment: string
400
- best: string
401
- d_norm: number
402
- record_id: string
403
- }> {
404
- const payload = await this.read(claim, { k: 4 })
405
- const scored = collectItems(payload)
406
- .map((it) => {
407
- const node = (it['node'] as Record<string, unknown>) ?? it
408
- const fm = (node['frontmatter'] as Record<string, unknown>) ?? node
409
- const score = typeof it['score'] === 'number'
410
- ? it['score'] as number
411
- : Number(it['score'] ?? 0)
412
- return {
413
- id: String(node['id'] ?? it['id'] ?? ''),
414
- score: Number.isFinite(score) ? score : 0,
415
- basis: String(fm['verification_basis'] ?? node['verification_basis'] ?? ''),
416
- content: String(node['content'] ?? ''),
417
- }
418
- })
419
- .filter((x) => x.id)
420
- .sort((a, b) => b.score - a.score)
421
- const best = scored[0]
422
- if (best && best.score > 0 && STRONG_BASIS.has(best.basis)) {
423
- return {
424
- judgment: `采纳:认知图已有强依据节点 ${best.id}(basis=${best.basis})`,
425
- best: best.content.slice(0, 200),
426
- d_norm: Math.min(1, best.score),
427
- record_id: best.id,
428
- }
429
- }
430
- if (best && best.score > 0) {
431
- return {
432
- judgment: `待定:命中节点 ${best.id} 但依据不足(basis=${best.basis || 'unknown'})`,
433
- best: best.content.slice(0, 200),
434
- d_norm: -1,
435
- record_id: best.id,
436
- }
437
- }
438
- return { judgment: '未命中:认知图中无相关节点', best: '', d_norm: -1, record_id: '' }
439
- }
440
-
441
- /** 角色定义落图:layer=knowledge,tags=['roleplay','role:<id>']。 */
442
- writeRole(roleId: string, content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
443
- // 落层固定 knowledge(在 record 白名单内)→ 声明 record 单元。
444
- // ⚠️ 不经 this.write():那是不注入单元的通用直写口(还要写 self 层锚点)。
445
- return this.writeNode({
446
- content,
447
- node_id: `roleplay_role_${roleId}`,
448
- layer: 'knowledge',
449
- tags: ['roleplay', `role:${roleId}`, 'roleplay:role'],
450
- importance: 0.7,
451
- ...extra,
452
- }, 'record')
453
- }
454
-
455
- /** 角色对话转录落图:layer=contextual,tags=['roleplay','role:<id>','session:<cid>']。 */
456
- writeTranscript(roleId: string, sessionId: string, who: 'user' | 'assistant',
457
- content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
458
- const stamp = Date.now()
459
- // 落层固定 contextual(在 record 白名单内)→ 声明 record 单元。
460
- return this.writeNode({
461
- content,
462
- node_id: `roleplay_turn_${roleId}_${sessionId}_${stamp}`,
463
- layer: 'contextual',
464
- tags: ['roleplay', `role:${roleId}`, `session:${sessionId}`, `turn:${who}`],
465
- importance: 0.4,
466
- ...extra,
467
- }, 'record')
468
- }
469
- }
1
+ /**
2
+ * mdcg_client.ts —— 认知图显式客户端(LIB 本地库)
3
+ *
4
+ * 架构定位(2026-09-10 决定)
5
+ * --------------------------
6
+ * · md_cg = 记忆操作系统 / **唯一真源**(记忆的写、读、裁决、留痕)。
7
+ * · AEIS = **能力库**(白箱引擎、角色扮演生成等),不再是记忆真源。
8
+ *
9
+ * 本模块是插件侧调用 md_cg 的**唯一显式入口**:只暴露 `cg` / `stg` 两个
10
+ * 认知基元,每个方法 = 一条 MCP 调用,不做隐式魔法。
11
+ *
12
+ * 显式调用映射(详见 docs/功能调用映射表_v0.1.md)
13
+ * ------------------------------------------------
14
+ * 路由/召回 → MdcgClient.route() → MCP cg(op=route)
15
+ * 读取节点 → MdcgClient.read() → MCP cg(op=read)
16
+ * 记忆沉淀 → MdcgClient.remember() → MCP mdcg_remember(gated=true)
17
+ * 语义召回 → MdcgClient.recall() → MCP cg(op=read, query)
18
+ * 写入记忆 → MdcgClient.write() → MCP mdcg_remember(gated=false)
19
+ * 外部裁决回填 → MdcgClient.verify() → MCP cg(op=verify)
20
+ * 最近记忆时间线 → MdcgClient.timeline() → MCP stg(op=timeline)
21
+ * 近期事件窗口 → MdcgClient.recent() → MCP cg(op=recent)
22
+ * 窗口追加事件 → MdcgClient.recentAdd() → MCP cg(op=recent, action=add)
23
+ * 会话续接包 → MdcgClient.sessionRecall() → MCP cg(op=session, action=recall)
24
+ * 身份读取 → MdcgClient.identity() → MCP cg(op=identity)
25
+ * 白箱能力验证 → MdcgClient.whitebox() → MCP cg(op=whitebox)
26
+ * 服务信息 → MdcgClient.serviceInfo()→ MCP cg(op=info)
27
+ * 互维主张核验 → MdcgClient.verifyClaim()→ cg(op=read) + 依据强度判定
28
+ * 角色/转录落图 → MdcgClient.writeRole() / writeTranscript() → mdcg_remember
29
+ *
30
+ * 写入为什么不能走 cg(op=write)(关键约束,勿回退)
31
+ * ------------------------------------------------
32
+ * `cg(op=write)` 是**带审核**的写路径:先过 `audit.audit(content_kind)`,
33
+ * 未声明 content_kind 且未配置 `MDCG_POLICY_FILE` 时恒判 BLINDSPOT/DEFER ——
34
+ * 只进审核队列、**永不落盘**(自动记忆会静默全失败,实测 0 篇 md 文档)。
35
+ * 而 `mdcg_remember`(`md_cg/mcp_server.py:1691`)直接调 `MdCG.remember_gated`
36
+ * / `MdCG.add`,跳过审核,是 mcp_server 顶部文档定义的「写」入口。故本客户端
37
+ * 的**所有写入**(记忆沉淀 / 角色定义 / 对话转录)统一经 `mdcg_remember`。
38
+ */
39
+
40
+ import { delimiter } from 'node:path'
41
+ import { LingshuBridge, type McpCallResult } from '../bridge.js'
42
+ import { pythonPathValue, runRoot } from './datapath.js'
43
+ // 租户单点(#224):签发侧(token_store)与运行侧(本文件的 mdcgChildEnv)必须
44
+ // 用同一函数算出租户——N62 之后服务端对「令牌记录租户 ≠ 入参租户」fail-closed,
45
+ // 两侧各算一遍就必然分叉(签发按 default、运行按 work ⇒ rc=3 拒启)。
46
+ import { effectiveTenant } from './token_store.js'
47
+
48
+ /** md_cg 子进程与根目录配置。 */
49
+ export interface MdcgOptions {
50
+ /** Python 可执行文件,默认取 config.python。 */
51
+ python: string
52
+ /** 启动参数,默认 ['-m', 'md_cg.mcp_server']。 */
53
+ args?: string[]
54
+ /** 认知图根目录(MDCG_ROOT)。 */
55
+ root: string
56
+ /** Python 子进程工作目录,默认 `runRoot()`——**插件包目录之外**的稳定目录
57
+ * (issue #18:Windows 不允许删除/改名「正被某进程当作 cwd」的目录,
58
+ * cwd 落在包内会让 pnpm 更新本包必然 `ERR_PNPM_EBUSY` 且永不自愈)。
59
+ * 模块解析**不依赖 cwd**:`python -m` 靠 `PYTHONPATH`
60
+ * (见 `pythonPathValue()`)解析随包 md_cg,issue #12 口径不变。
61
+ * 显式传入本项时完全尊重原值。 */
62
+ cwd?: string
63
+ /** 调用主体标识(MDCG_ACTOR)。私有内容按 (tenant, actor) 派生 DEK,
64
+ * 故与迁移脚本 --actor 必须一致,否则读不到已迁移节点。 */
65
+ actor?: string
66
+ /** 租户(MDCG_TENANT),默认 default。 */
67
+ tenant?: string
68
+ /** 调用方密级(MDCG_CLEARANCE):只能读写 ≤ 该密级的节点,默认 private。 */
69
+ clearance?: string
70
+ /** 身份主体(MDCG_IDENTITY)。 */
71
+ identity?: string
72
+ /** 额外环境变量。 */
73
+ env?: Record<string, string>
74
+ /** MCP 工具面(MDCG_MCP_SURFACE):'kernel' = 仅 cg/stg 两基元;
75
+ * 'full' = 另含 `mdcg_*` 细粒度工具。
76
+ *
77
+ * ⚠️ 本客户端**必须**用 full:唯一写入通道是 `mdcg_remember`(细粒度),
78
+ * kernel 面下该工具不存在 → 写入静默失败(角色/转录/自动记忆全部不落盘)。
79
+ * 默认 'full',勿改。 */
80
+ surface?: 'kernel' | 'full'
81
+ timeoutMs?: number
82
+ maxRetryDelayMs?: number
83
+ }
84
+
85
+ const DEFAULT_ARGS = ['-m', 'md_cg.mcp_server']
86
+
87
+ /** 子进程环境构造参数(`MdcgOptions` 中与环境相关的那半)。 */
88
+ export interface MdcgChildEnvOptions {
89
+ root: string
90
+ surface?: 'kernel' | 'full'
91
+ tenant?: string
92
+ clearance?: string
93
+ actor?: string
94
+ identity?: string
95
+ env?: Record<string, string>
96
+ }
97
+
98
+ /**
99
+ * MCP 子进程环境:**唯一构造点**(导出即为了让机械守卫能断言它——
100
+ * 见 `test/python-utf8-mode.test.ts`)。勿在别处另拼 env。
101
+ *
102
+ * ⚠️ 两条编码注入是**硬约束**,不是可选项:
103
+ *
104
+ * ① `PYTHONIOENCODING=utf-8`(子进程**自身** stdio):Windows 下 piped 子进程默认
105
+ * gbk + surrogateescape,Node 写出的 UTF-8 中文会被解成孤立代理字符(\udcXX),
106
+ * md_cg 在落盘 / 回写 stdout 时抛 UnicodeEncodeError——中文记忆(主场景)全失败。
107
+ *
108
+ * ② `PYTHONUTF8=1`(子进程**后代**的默认 text 编码,PEP 540):`PYTHONIOENCODING`
109
+ * 会被后代继承(后代于是往管道写 UTF-8),但**文本解码口径不被继承**——后代读
110
+ * `subprocess.run(..., text=True)` 时取的是 locale(本机 cp936),于是
111
+ * 「子进程写 UTF-8、父进程按 gbk 读」→ 读线程崩死、诊断静默丢失。
112
+ * 2026-09-20 实证现场(`npm test` 周期复现,来源为子进程的后代代码单元):
113
+ * Exception in thread Thread-N (_readerthread):
114
+ * UnicodeDecodeError: 'gbk' codec can't decode byte 0x82 in position 181
115
+ * UTF-8 模式把默认 text 编码改为 UTF-8,读写两侧同口径(且解码结果正确,
116
+ * 而非 `errors="replace"` 那种替换字符)。
117
+ *
118
+ * 确定性对照实验(P1 复现 / P3 消除)见 `test/python-utf8-mode.test.ts`。
119
+ * `opts.env` 最后展开——显式覆盖优先。**唯一例外是 `MDCG_TENANT`**(#224):
120
+ * 它由 `effectiveTenant()` 单点决定(`opts.env.MDCG_TENANT` > `opts.tenant` >
121
+ * default),放在 `opts.env` 之后写入——否则 `opts.env` 里的空串/其它值会把
122
+ * 「签发侧算出的租户」再覆盖一次,两侧分叉。其余键的覆盖顺序不变。
123
+ */
124
+ export function mdcgChildEnv(opts: MdcgChildEnvOptions): Record<string, string> {
125
+ return {
126
+ PYTHONIOENCODING: 'utf-8',
127
+ PYTHONUTF8: '1',
128
+ MDCG_ROOT: opts.root,
129
+ // 工具面必须是 full:写入通道 mdcg_remember 属细粒度工具(见 MdcgOptions.surface)。
130
+ MDCG_MCP_SURFACE: opts.surface ?? 'full',
131
+ MDCG_CLEARANCE: opts.clearance ?? 'private',
132
+ PYTHONPATH: pythonPathValue(),
133
+ ...(opts.actor ? { MDCG_ACTOR: opts.actor } : {}),
134
+ ...(opts.identity ? { MDCG_IDENTITY: opts.identity } : {}),
135
+ ...(opts.env ?? {}),
136
+ // 租户单点(见 effectiveTenant):与 token_store 签发/复核同一口径。
137
+ MDCG_TENANT: effectiveTenant(opts.tenant, opts.env),
138
+ }
139
+ }
140
+
141
+ /** 认知图依据强度:这些 basis 视为「强依据」,可支撑 pass。
142
+ * 取值须在 md_cg.mdcg.VERIFICATION_BASIS 允许集内:
143
+ * compiler | test | measurement | formal_proof | data | other(other 不算强依据)。 */
144
+ const STRONG_BASIS = new Set(['compiler', 'test', 'measurement', 'formal_proof', 'data'])
145
+
146
+ /**
147
+ * 请求级**单元身份**(MCP 参数 `as_unit`)。
148
+ *
149
+ * 与 `md_cg/tokens.py` 的 `POSITION_ROLES` 同源(record/reflect/verify/
150
+ * output/sustain);大脑侧 `narrowed_principal` 对未知值 fail-closed 报错。
151
+ *
152
+ * 语义(关键):`as_unit` 只能**收窄**权限、不能放大——大脑侧以「与 owner 求交 +
153
+ * 管理权恒 False」保证,故填错的最坏结果等于不填(owner 全权),**不可能提权**。
154
+ *
155
+ * 本客户端**只在写入 / 裁决路径注入**,且只注入与落层确定匹配的单元:
156
+ * · 记忆沉淀 / 转录 / 角色定义 → `record`(落 contextual / knowledge,在 record
157
+ * 的 layers_allow 内);
158
+ * · 外部裁决回填 → `verify`(cg op=verify)。
159
+ * **只读调用一律不注入**:record / output 的 `clearance_cap=internal`,注入会把
160
+ * owner 的 private 读能力一并压低(读不到私有记忆=功能退化),而读无副作用,
161
+ * 收窄无收益。`write()` 同样不注入——它被用于写 self / structural 层(角色锚点
162
+ * 需 designer 权限),注入 `record` 会直接打断角色落图。
163
+ */
164
+ export type LingshuUnit = 'record' | 'reflect' | 'verify' | 'output' | 'sustain'
165
+
166
+ function collectItems(payload: unknown): Array<Record<string, unknown>> {
167
+ if (Array.isArray(payload)) return payload as Array<Record<string, unknown>>
168
+ if (payload && typeof payload === 'object') {
169
+ const obj = payload as Record<string, unknown>
170
+ for (const key of ['results', 'items', 'nodes', 'hits', 'data', 'records']) {
171
+ if (Array.isArray(obj[key])) return obj[key] as Array<Record<string, unknown>>
172
+ }
173
+ }
174
+ return []
175
+ }
176
+
177
+ /**
178
+ * 认知图显式客户端。
179
+ *
180
+ * 生命周期与桥一致:懒启动 + 自动重连;未就绪时调用会快速失败。
181
+ * 未就绪的处置:互维 verify 走 fail-closed(见 index.ts 的注入),
182
+ * 自动记忆静默跳过——**不再有"回退 aeis 能力库"路径**(该库已剥离)。
183
+ */
184
+ export class MdcgClient {
185
+ readonly bridge: LingshuBridge
186
+
187
+ constructor(opts: MdcgOptions) {
188
+ // 子进程 cwd 必须落在插件包目录之外,否则 pnpm 更新本插件时
189
+ // rmdir 包目录会撞上 Windows 的「目录被当作 CWD」共享冲突 → ERR_PNPM_EBUSY。
190
+ // 模块解析不依赖 cwd:PYTHONPATH(pythonPathValue())已锚定随包 md_cg;
191
+ // opts.env 显式提供 PYTHONPATH 时完全接管(其展开在最后)。详见 datapath.runRoot()。
192
+ const cwd = opts.cwd ?? runRoot()
193
+ // 编码与模块解析口径见 mdcgChildEnv() 头注(含 2026-09-20 读线程崩溃现场)。
194
+ const env = mdcgChildEnv(opts)
195
+ this.bridge = new LingshuBridge({
196
+ python: opts.python,
197
+ args: opts.args ?? DEFAULT_ARGS,
198
+ env,
199
+ cwd,
200
+ timeoutMs: opts.timeoutMs ?? 60_000,
201
+ maxRetryDelayMs: opts.maxRetryDelayMs ?? 30_000,
202
+ })
203
+ }
204
+
205
+ start(): void {
206
+ this.bridge.start()
207
+ }
208
+
209
+ async waitReady(): Promise<boolean> {
210
+ return this.bridge.waitReady()
211
+ }
212
+
213
+ /** 桥是否已握手就绪。
214
+ *
215
+ * ⚠️ 不可缓存 waitReady() 的结果:waitReady() 在**首次心跳失败**时会立即
216
+ * resolve(false)(见 bridge.ts 的 failed 分支),但桥仍会后台重连成功——
217
+ * 若把这次 false 缓存下来,isReady() 将永久为假,自动记忆 / 互维核验会在
218
+ * 重连成功后静默失效。故一律以桥的实时状态为准。 */
219
+ isReady(): boolean {
220
+ return this.bridge.isReady()
221
+ }
222
+
223
+ dispose(): void {
224
+ this.bridge.dispose()
225
+ }
226
+
227
+ /** 原始 cg 调用(逃生口;显式传参,不做推断)。
228
+ * `asUnit` = 本次调用的请求级单元身份(见 LingshuUnit);只收窄、不提权。 */
229
+ async cg(args: Record<string, unknown>, asUnit?: LingshuUnit): Promise<unknown> {
230
+ return this.call('cg', args, asUnit)
231
+ }
232
+
233
+ /** 原始 stg 调用(时间线/关系/锚点/一致性)。 */
234
+ async stg(args: Record<string, unknown>, asUnit?: LingshuUnit): Promise<unknown> {
235
+ return this.call('stg', args, asUnit)
236
+ }
237
+
238
+ private async call(tool: string, args: Record<string, unknown>,
239
+ asUnit?: LingshuUnit): Promise<unknown> {
240
+ // as_unit 由大脑侧 mcp_server.call_tool 在同一进程内消费并收窄 principal,
241
+ // 不从 args 向下透传,故不会污染各 tool handler 的参数解析。
242
+ const payload = asUnit ? { ...args, as_unit: asUnit } : args
243
+ const result: McpCallResult = await this.bridge.callTool(tool, payload)
244
+ const text = (result.content ?? [])
245
+ .filter((c) => c.type === 'text')
246
+ .map((c) => c.text ?? '')
247
+ .join('')
248
+ if (result.isError) throw new Error(text || `md_cg ${tool} 调用失败`)
249
+ try {
250
+ return JSON.parse(text)
251
+ } catch {
252
+ return text
253
+ }
254
+ }
255
+
256
+ // -- 显式认知能力(每个方法一条 MCP 调用) --------------------------------
257
+
258
+ /** 路由:意图 → 相关知识 + 建议能力。 */
259
+ route(intent: string, extra: Record<string, unknown> = {}): Promise<unknown> {
260
+ return this.cg({ op: 'route', intent, ...extra })
261
+ }
262
+
263
+ /** 读取:按语义召回节点。 */
264
+ read(query: string, extra: Record<string, unknown> = {}): Promise<unknown> {
265
+ return this.cg({ op: 'read', query, ...extra })
266
+ }
267
+
268
+ /** 按 id 精确读取单个节点。 */
269
+ get(nodeId: string): Promise<unknown> {
270
+ return this.cg({ op: 'read', node_id: nodeId })
271
+ }
272
+
273
+ /** 认知图写入入口(MCP `mdcg_remember`)。
274
+ *
275
+ * ⚠️ 唯一写入通道:**不可**改用 `cg(op=write)`(那条路径会被 audit 拦住,
276
+ * 见文件头「写入为什么不能走 cg(op=write)」)。gated=false 直写 `MdCG.add`
277
+ * (默认 layer=knowledge),gated=true 走主动遗忘闸门。 */
278
+ private writeNode(args: Record<string, unknown>,
279
+ asUnit?: LingshuUnit): Promise<unknown> {
280
+ return this.call('mdcg_remember', args, asUnit)
281
+ }
282
+
283
+ /** 写入:新增/覆盖一个记忆节点(直写 `MdCG.add`,不经审核队列)。 */
284
+ write(content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
285
+ return this.writeNode({ content, ...extra })
286
+ }
287
+
288
+ /** 记忆沉淀(AEIS `remember` 的对应物):写入情景层并过**主动遗忘闸门**。
289
+ *
290
+ * `mdcg_remember(gated=true)` → `MdCG.remember_gated`:三问 → 四态,
291
+ * ACCEPT 落盘 / MERGE 并入既有(= 去重强化,不新增节点)/ DROP 丢弃低熵
292
+ * 噪音 / DEFER 待定;四种结果都写 `_forgetting.jsonl`,可审计。
293
+ * `importance` 作为 importance_hint 传入(≥0.7 时保护优先、直接 ACCEPT)。
294
+ *
295
+ * layer 默认 contextual:md_cg 对 DSH 会话事件约定的落层就是 contextual,
296
+ * role 取 user | assistant | tool-output(见 md_cg/sources.py 的
297
+ * SESSION_LAYER / DSHSessionSource 事件映射)。 */
298
+ remember(content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
299
+ // 落层 contextual 固定在 record 白名单内 → 声明 record 单元(不得写 self/anchor)。
300
+ return this.writeNode({ content, gated: true, layer: 'contextual', ...extra }, 'record')
301
+ }
302
+
303
+ /** 语义召回(AEIS `recall` 的对应物):`cg(op=read, query)` → md_cg 检索。
304
+ * 读取会记 access log(复用观测),供 importance / scrub 陈旧度使用。 */
305
+ recall(query: string, k = 5): Promise<unknown> {
306
+ return this.read(query, { k })
307
+ }
308
+
309
+ /** 外部裁决回填:为已有节点写 confirmed/weakened/falsified。 */
310
+ verify(nodeId: string, evidence: string, verdict: string): Promise<unknown> {
311
+ // 裁决回填声明 verify 单元:只写 rejected/contextual,不得改被验证内容。
312
+ return this.cg({ op: 'verify', node_id: nodeId, evidence, verdict }, 'verify')
313
+ }
314
+
315
+ /** 最近记忆。 */
316
+ recent(limit = 20): Promise<unknown> {
317
+ return this.cg({ op: 'recent', limit })
318
+ }
319
+
320
+ /** 追加一条**近期事件窗口**记录(`cg(op=recent, action=add)` →
321
+ * `md_cg` 的 `remember_event(role, text, tags, meta, window)`)。
322
+ *
323
+ * 这是「滑动窗口」写侧:事件落 `_recent.jsonl`(**运行态面**),按窗口滚动
324
+ * 淘汰(服务端缺省 200 条,`mdcg.py:91 DEFAULT_RECENT_WINDOW`)——它**不是
325
+ * 知识节点**:不占 knowledge 层、不进检索正排,与 `remember()` 的知识面沉淀
326
+ * 是两条独立的轨道(见 src/hooks.ts 文件头的 contextWindow 头注)。
327
+ *
328
+ * ⚠️ **不注入 as_unit**(与 `write()` 同款理由的反面):本调用不写任何层的
329
+ * 节点(服务端 `remember_event` 不做层白名单校验),收窄单元无收益且可能压低
330
+ * 事件密级(缺省 internal);`meta.session` 由调用方显式给出(沿本文件
331
+ * `remember()` 的 sessionTag 口径)。
332
+ *
333
+ * ⚠️ 服务端对 `meta` 做 `setdefault`(tenant/session/harness/unit,见
334
+ * `mdcos.py:5057 remember_event`):调用方已写的键**不被覆盖**。 */
335
+ recentAdd(role: string, text: string,
336
+ meta: Record<string, unknown> = {},
337
+ tags: string[] = []): Promise<unknown> {
338
+ return this.cg({ op: 'recent', action: 'add', role, text, meta, tags })
339
+ }
340
+
341
+ /** **会话续接包**(`cg(op=session, action=recall)` → `md_cg` 的
342
+ * `session_recall`):一次取回 notes / goals / tasks / **recent 事件窗口** /
343
+ * unresolved / self_state,按 `budget_tokens` 整包裁剪(服务端
344
+ * `mdcos.py:3351-3362`:交替丢 recent / notes 尾部)。
345
+ *
346
+ * 本插件消费其中的 `recent` 段——滑动窗口的**注入面**(见 src/hooks.ts)。
347
+ * `recent_limit` 语义 = 近期事件**条数**(非「轮数」);服务端读取时会按
348
+ * `max(1, recent_limit or 10)` 归一(`mdcos.py:3309`)。
349
+ *
350
+ * ⚠️ 两条服务端事实(决定注入侧的可达性,勿据本方法名臆测):
351
+ * ① `recent` 段取 `recent_events(limit=recent_limit)` —— **不按 session
352
+ * 过滤**(近期事件是运行态滚动窗口,会话归属只写在每条事件的 meta 里);
353
+ * ② budget 是**整包**预算:库内 notes/tasks/self_state 占位越多,同样
354
+ * budget 下 recent 段被裁得越短(实测:空库 + 10 条窗口条目,
355
+ * budget_tokens=600 → recent 8 条;1200 → 10 条)。
356
+ *
357
+ * 只读调用,不注入 as_unit(同其它读路径:读无副作用,收窄只会压低 owner
358
+ * 的 private 读能力)。 */
359
+ sessionRecall(session: string, recentLimit: number, budgetTokens: number): Promise<unknown> {
360
+ return this.cg({
361
+ op: 'session', action: 'recall',
362
+ session, recent_limit: recentLimit, budget_tokens: budgetTokens,
363
+ })
364
+ }
365
+
366
+ /** 最近记忆**时间线**(AEIS `timeline` 的对应物):`stg(op=timeline)` →
367
+ * `{count, limit, items:[{id, layer, start, end, preview}]}`,按时间倒序。
368
+ *
369
+ * 只收录带时间区间的节点;而 `cg.add()` 在调用方未给 time_window 时会以
370
+ * **写入时刻**自动填充(见 mdcg.py 的 OBSERVATION_WINDOW_SEC 分支),故经
371
+ * 本客户端写入的记忆都能进入时间线。
372
+ * 要原始近期**事件**(未结构化对话窗口)请用 `recent()`。 */
373
+ timeline(limit = 4, extra: Record<string, unknown> = {}): Promise<unknown> {
374
+ return this.stg({ op: 'timeline', limit, desc: true, ...extra })
375
+ }
376
+
377
+ /** 身份维度读取。 */
378
+ identity(subjectId?: string, extra: Record<string, unknown> = {}): Promise<unknown> {
379
+ return this.cg({ op: 'identity', ...(subjectId ? { subject_id: subjectId } : {}), ...extra })
380
+ }
381
+
382
+ /** 白箱能力库:显式调用 + 能力验证。 */
383
+ whitebox(action: string, extra: Record<string, unknown> = {}): Promise<unknown> {
384
+ return this.cg({ op: 'whitebox', action, ...extra })
385
+ }
386
+
387
+ /** 服务信息(信任透明度)。 */
388
+ serviceInfo(): Promise<unknown> {
389
+ return this.cg({ op: 'info' })
390
+ }
391
+
392
+ // -- 语义化封装(互维 / 角色扮演显式使用认知图) --------------------------
393
+
394
+ /**
395
+ * 互维主张核验(memory 通道):用认知图替代 AEIS `wisdom_verify`。
396
+ * 返回结构与 VerifyResult['whitebox'] 对齐,便于直接注入 mutual。
397
+ */
398
+ async verifyClaim(claim: string): Promise<{
399
+ judgment: string
400
+ best: string
401
+ d_norm: number
402
+ record_id: string
403
+ }> {
404
+ const payload = await this.read(claim, { k: 4 })
405
+ const scored = collectItems(payload)
406
+ .map((it) => {
407
+ const node = (it['node'] as Record<string, unknown>) ?? it
408
+ const fm = (node['frontmatter'] as Record<string, unknown>) ?? node
409
+ const score = typeof it['score'] === 'number'
410
+ ? it['score'] as number
411
+ : Number(it['score'] ?? 0)
412
+ return {
413
+ id: String(node['id'] ?? it['id'] ?? ''),
414
+ score: Number.isFinite(score) ? score : 0,
415
+ basis: String(fm['verification_basis'] ?? node['verification_basis'] ?? ''),
416
+ content: String(node['content'] ?? ''),
417
+ }
418
+ })
419
+ .filter((x) => x.id)
420
+ .sort((a, b) => b.score - a.score)
421
+ const best = scored[0]
422
+ if (best && best.score > 0 && STRONG_BASIS.has(best.basis)) {
423
+ return {
424
+ judgment: `采纳:认知图已有强依据节点 ${best.id}(basis=${best.basis})`,
425
+ best: best.content.slice(0, 200),
426
+ d_norm: Math.min(1, best.score),
427
+ record_id: best.id,
428
+ }
429
+ }
430
+ if (best && best.score > 0) {
431
+ return {
432
+ judgment: `待定:命中节点 ${best.id} 但依据不足(basis=${best.basis || 'unknown'})`,
433
+ best: best.content.slice(0, 200),
434
+ d_norm: -1,
435
+ record_id: best.id,
436
+ }
437
+ }
438
+ return { judgment: '未命中:认知图中无相关节点', best: '', d_norm: -1, record_id: '' }
439
+ }
440
+
441
+ /** 角色定义落图:layer=knowledge,tags=['roleplay','role:<id>']。 */
442
+ writeRole(roleId: string, content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
443
+ // 落层固定 knowledge(在 record 白名单内)→ 声明 record 单元。
444
+ // ⚠️ 不经 this.write():那是不注入单元的通用直写口(还要写 self 层锚点)。
445
+ return this.writeNode({
446
+ content,
447
+ node_id: `roleplay_role_${roleId}`,
448
+ layer: 'knowledge',
449
+ tags: ['roleplay', `role:${roleId}`, 'roleplay:role'],
450
+ importance: 0.7,
451
+ ...extra,
452
+ }, 'record')
453
+ }
454
+
455
+ /** 角色对话转录落图:layer=contextual,tags=['roleplay','role:<id>','session:<cid>']。 */
456
+ writeTranscript(roleId: string, sessionId: string, who: 'user' | 'assistant',
457
+ content: string, extra: Record<string, unknown> = {}): Promise<unknown> {
458
+ const stamp = Date.now()
459
+ // 落层固定 contextual(在 record 白名单内)→ 声明 record 单元。
460
+ return this.writeNode({
461
+ content,
462
+ node_id: `roleplay_turn_${roleId}_${sessionId}_${stamp}`,
463
+ layer: 'contextual',
464
+ tags: ['roleplay', `role:${roleId}`, `session:${sessionId}`, `turn:${who}`],
465
+ importance: 0.4,
466
+ ...extra,
467
+ }, 'record')
468
+ }
469
+ }