@furongjun1999/dsh-memory 0.9.22 → 0.10.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 (179) hide show
  1. package/CHANGELOG.en.md +450 -0
  2. package/CHANGELOG.md +112 -0
  3. package/README.en.md +244 -0
  4. package/README.md +272 -260
  5. package/codebuddy/CODEBUDDY.md +1 -1
  6. package/docs/README.md +2 -0
  7. package/docs/discipline/templates/full.md.tmpl +1 -1
  8. package/docs/discipline/templates/rules.mdc.tmpl +1 -1
  9. package/docs/en/README.md +190 -0
  10. package/docs/en/TRANSLATION.md +78 -0
  11. package/docs/en/TRANSLATION_MANIFEST.json +170 -0
  12. package/docs/en/TRANSLATION_REPORT.md +11 -0
  13. package/docs/en/dev/README.md +10 -0
  14. package/docs/en/dev/coding-testing.md +72 -0
  15. package/docs/en/dev/switch-matrix.md +10 -0
  16. package/docs/en/glossary.md +97 -0
  17. package/docs/en/harnesses/claude.md +100 -0
  18. package/docs/en/harnesses/codebuddy.md +93 -0
  19. package/docs/en/harnesses/codex.md +88 -0
  20. package/docs/en/harnesses/dsh.md +84 -0
  21. package/docs/en/harnesses/zcode.md +42 -0
  22. package/docs/en/mdcg/ccg.md +32 -0
  23. package/docs/en/mdcg/generated-docs.md +20 -0
  24. package/docs/en/mdcg/guardrail-charter.md +170 -0
  25. package/docs/en/mdcg/mcp-tool-names.md +43 -0
  26. package/docs/en/mdcg/multi-harness.md +43 -0
  27. package/docs/en/mdcg/recall-metadata.md +30 -0
  28. package/docs/en/mdcg/world-model-endpoint.md +379 -0
  29. package/docs/en/mdcg/write-aliases.md +130 -0
  30. package/docs/en/ops/README.md +11 -0
  31. package/docs/en/ops/environment-known-issues.md +244 -0
  32. package/docs/en/ops/install.md +72 -0
  33. package/docs/en/ops/operations-troubleshooting.md +86 -0
  34. package/docs/en/ops/permissions-review.md +79 -0
  35. package/docs/en/ops/release-governance.md +49 -0
  36. package/docs/en/ops/tool-name-migration.md +30 -0
  37. package/docs/en/ops/ui-install-troubleshooting.md +53 -0
  38. package/docs/en/standards/ai-coding-standard-checklist.md +71 -0
  39. package/docs/en/standards/ai-coding-standard-lingshu.md +47 -0
  40. package/docs/en/standards/ai-coding-standard.md +185 -0
  41. package/docs/en/ui/minimal.md +62 -0
  42. package/docs/mdcg/cogmap_ops.md +16 -15
  43. package/lib/client.js +29 -3
  44. package/lib/hooks.d.ts +34 -0
  45. package/lib/hooks.js +167 -33
  46. package/lib/index.js +19 -3
  47. package/lib/lib/console_web.mjs +30 -3
  48. package/lib/lib/hook_audit.d.ts +3 -2
  49. package/lib/lib/hook_audit.js +14 -4
  50. package/lib/lib/mdcg_client.d.ts +5 -2
  51. package/lib/lib/mdcg_client.js +8 -4
  52. package/lib/lib/prompt_safety.d.ts +24 -0
  53. package/lib/lib/prompt_safety.js +77 -1
  54. package/lib/lib/token_store.js +5 -2
  55. package/lib/tools.js +5 -3
  56. package/md_cg/bucketindex.py +231 -0
  57. package/md_cg/bucketscope.py +339 -0
  58. package/md_cg/config_registry_bulk.py +19 -10
  59. package/md_cg/config_validate.py +14 -2
  60. package/md_cg/detrerank.py +137 -0
  61. package/md_cg/fsutil.py +215 -25
  62. package/md_cg/govern/__init__.py +23 -0
  63. package/md_cg/iface/__init__.py +46 -0
  64. package/md_cg/iface/_verify.py +609 -0
  65. package/md_cg/iface/contracts.py +337 -0
  66. package/md_cg/judgment_manifest.py +14 -0
  67. package/md_cg/kernel/__init__.py +27 -0
  68. package/md_cg/mcp_server.py +457 -23
  69. package/md_cg/mdcg.py +1034 -79
  70. package/md_cg/mdcos.py +263 -21
  71. package/md_cg/metacognition.py +66 -13
  72. package/md_cg/mutate_extract_shipped.py +126 -0
  73. package/md_cg/mutate_ledger_e2e.py +100 -0
  74. package/md_cg/nodefile.py +147 -23
  75. package/md_cg/op_table.py +22 -4
  76. package/md_cg/probe_c_ledger_integrity.py +258 -0
  77. package/md_cg/probe_d_retirement_discipline.py +263 -0
  78. package/md_cg/reconcile.py +9 -11
  79. package/md_cg/review_cli.py +6 -1
  80. package/md_cg/rollback.py +16 -1
  81. package/md_cg/run_tests.py +30 -1
  82. package/md_cg/scopeselect.py +214 -0
  83. package/md_cg/scrub.py +160 -23
  84. package/md_cg/security.py +4 -2
  85. package/md_cg/state_extract.py +149 -0
  86. package/md_cg/state_slots.py +58 -10
  87. package/md_cg/structboost.py +179 -0
  88. package/md_cg/test_alternatives_historical.py +162 -0
  89. package/md_cg/test_b2_sensitivity_landing.py +226 -223
  90. package/md_cg/test_b3_merge_keeps_content.py +608 -583
  91. package/md_cg/test_bucket_cards.py +85 -0
  92. package/md_cg/test_bucket_day_order.py +74 -0
  93. package/md_cg/test_bucket_quota.py +79 -0
  94. package/md_cg/test_bucket_recency_guards.py +75 -0
  95. package/md_cg/test_bucket_three_causes.py +83 -0
  96. package/md_cg/test_bucketindex.py +130 -0
  97. package/md_cg/test_bucketscope_early.py +71 -0
  98. package/md_cg/test_cond_term_fold.py +183 -0
  99. package/md_cg/test_cond_term_fold_gate.py +1210 -0
  100. package/md_cg/test_cond_term_neg_scope.py +147 -0
  101. package/md_cg/test_cond_terms_colon.py +348 -0
  102. package/md_cg/test_detrerank.py +157 -0
  103. package/md_cg/test_gate_four_kpi.py +136 -0
  104. package/md_cg/test_generation_guard.py +76 -43
  105. package/md_cg/test_issue192_move_layer_indices_guard.py +48 -0
  106. package/md_cg/test_issue362_neg_condition.py +44 -7
  107. package/md_cg/test_issue39_utf8_stdio.py +572 -572
  108. package/md_cg/test_issue413_preimage_failclosed.py +147 -9
  109. package/md_cg/test_issue444_scrub_evidence_plaintext.py +14 -8
  110. package/md_cg/test_issue677_flush_batch_io.py +139 -0
  111. package/md_cg/test_issue677_info_fast.py +82 -0
  112. package/md_cg/test_issue677_remember_dedupe.py +106 -0
  113. package/md_cg/test_issue712_tokens_sessions_read.py +199 -0
  114. package/md_cg/test_issue722_strict_conditions.py +96 -0
  115. package/md_cg/test_issue730_narrowing_audit.py +121 -0
  116. package/md_cg/test_issue733_verify_override.py +193 -0
  117. package/md_cg/test_issue733_verify_override_and_overwrite_inherit.py +315 -0
  118. package/md_cg/test_issue740_filelock_fd_leak.py +218 -0
  119. package/md_cg/test_issue741_content_hash_same_source.py +158 -0
  120. package/md_cg/test_issue747_slot_contradiction.py +125 -0
  121. package/md_cg/test_issue754_nested_root_guard.py +197 -0
  122. package/md_cg/test_issue757_index_hash_compare.py +85 -0
  123. package/md_cg/test_issue758_disk_hash_single.py +67 -0
  124. package/md_cg/test_issue759_twophase_hash.py +67 -0
  125. package/md_cg/test_issue768_overwrite_time_window_anchor.py +135 -0
  126. package/md_cg/test_issue789_log_plaintext_probe.py +100 -0
  127. package/md_cg/test_issue790_verb_negation.py +77 -0
  128. package/md_cg/test_issue810_root_guard.py +71 -0
  129. package/md_cg/test_issue812_info_index_stale.py +78 -0
  130. package/md_cg/test_issue827_weaken_dedup.py +361 -0
  131. package/md_cg/test_issue829_calibration_positive_gate.py +473 -0
  132. package/md_cg/test_kernel_iface_contracts.py +18 -0
  133. package/md_cg/test_md_cg_no_hive_dep.py +238 -17
  134. package/md_cg/test_n204_n205_n226_n227_n228_n229_exit_gates.py +545 -542
  135. package/md_cg/test_n209_verify_write_face_gates.py +5 -2
  136. package/md_cg/test_neg_condition_hits.py +336 -333
  137. package/md_cg/test_probe_cd_shipped.py +385 -0
  138. package/md_cg/test_recent_tail.py +93 -0
  139. package/md_cg/test_run_tests_entry_gates.py +110 -0
  140. package/md_cg/test_scopeselect.py +70 -0
  141. package/md_cg/test_scopeselect_clock.py +70 -0
  142. package/md_cg/test_scrub_source_line_false_positive.py +64 -0
  143. package/md_cg/test_session_attribution_consistency.py +835 -813
  144. package/md_cg/test_state_extract_shipped.py +162 -0
  145. package/md_cg/test_state_ledger_chain.py +207 -0
  146. package/md_cg/test_state_ledger_e2e.py +145 -0
  147. package/md_cg/test_structboost.py +102 -0
  148. package/md_cg/test_timeboost.py +83 -0
  149. package/md_cg/test_timeboost_relativedate.py +71 -0
  150. package/md_cg/test_topicagg.py +129 -0
  151. package/md_cg/test_twophase.py +286 -286
  152. package/md_cg/timeboost.py +223 -0
  153. package/md_cg/tokens.py +55 -7
  154. package/md_cg/topicagg.py +142 -0
  155. package/md_cg/twophase.py +15 -6
  156. package/md_cg/whitebox_kb/wisdom/code_compose.py +33 -5
  157. package/md_cg/whitebox_kb/wisdom/compose_engine.py +5 -1
  158. package/md_cg/whitebox_kb/wisdom/role_compose.py +271 -268
  159. package/md_cg/writepipe.py +35 -3
  160. package/package.json +4 -1
  161. package/scripts/workspace_index.py +2 -0
  162. package/src/hooks.ts +182 -34
  163. package/src/index.ts +19 -3
  164. package/src/lib/console_web.mjs +30 -3
  165. package/src/lib/hook_audit.ts +15 -5
  166. package/src/lib/mdcg_client.ts +8 -4
  167. package/src/lib/prompt_safety.ts +73 -1
  168. package/src/lib/token_store.ts +5 -2
  169. package/src/tools.ts +5 -3
  170. package/ui/minimal/integrity.json +2 -2
  171. package/ui/minimal/payload/build-ui.mjs +41 -2
  172. package/ui/minimal/payload/lib/client.js +29 -3
  173. package/ui/minimal/payload/lib/lib/console_web.mjs +30 -3
  174. package/ui/minimal/payload/src/lib/console_web.mjs +30 -3
  175. package/ui/minimal/payload/web/app.js +3 -1
  176. package/ui/minimal/payload/web/client.js +30 -3
  177. package/web/app.js +3 -1
  178. package/web/client.js +30 -3
  179. package/zcode/AGENTS.md +1 -1
@@ -0,0 +1,244 @@
1
+ > **Languages:** [中文](../../ops/环境与已知问题.md) · English
2
+
3
+ # Environments and known issues
4
+
5
+ > **Scope of this page**: it collects only phenomena that **look like a bug but are actually environment, installation, or contract** issues, together with the evidence used to classify them.
6
+ > For functional defects, open an [issue](https://github.com/FuRongJun-1999/dsh-memory/issues) (with trigger conditions + a minimal reproduction + measured readings);
7
+ > installation steps are in [Installation and prerequisites](install.md), and upgrades and operations are in [Operations and troubleshooting](operations-troubleshooting.md).
8
+
9
+ ---
10
+
11
+ ## 1. DSH Desktop startup warnings (host side, outside this repository's fix scope)
12
+
13
+ **Symptom**: every startup logs a `migration failed` (about 2.6 seconds) and a `profile maintenance frozen`, and the log writes
14
+ `@deepseek-ai/schemastery does not resolve from the installation closure`.
15
+
16
+ **Mechanism** (verifiable): DSH Desktop's `installer.mjs` first hoists every `@deepseek-ai/*` package out of the generation as a **host singleton** (`hoistHostSingletons`), and then **validates the dependency closure against that same generation directory**. The pair of rules "remove it first, then validate it in place" necessarily reports "cannot resolve" for any plugin that declares host packages as normal dependencies.
17
+
18
+ **Functional impact**: **none**. At runtime the host's `host-module-fallback` catches imports with the `@deepseek-ai/` prefix and serves them from the copy shipped with the host (memory writes/recall and `cg(op=info)` all work normally).
19
+
20
+ **Why the package declaration is not changed**: switching to `peerDependencies` would make "import after a bare npm install" fail outright (the original defect in issue #222; `test/issue222_optional_peer.test.ts` guards that contract). Both contracts cannot hold under the current dependency shape; this plugin targets the DSH **web UI**, so the status quo stands and is recorded here (analysis in issue #660; upstream has it logged as deepseek-harness discussion #10940).
21
+
22
+ ---
23
+
24
+ ## 2. Size and deployment: it is not "copy a few .py files and it runs"
25
+
26
+ `md_cg/` is **coupled as an entire directory**: code + assets (`whitebox_kb` / `lexicon` / `semantic` / `knowledge`) live in one tree.
27
+ MCP mode also depends on `utf8_boot.py` at the **package root**.
28
+
29
+ | Item | Measured (v0.9.13 main) |
30
+ |---|---|
31
+ | `md_cg/` total | **71.9 MB / 2765 files** |
32
+ | `whitebox_kb/` | 20.8 MB / 580 files |
33
+ | `lexicon/` | 1.6 MB |
34
+ | `semantic/` | 1.2 MB |
35
+
36
+ **Criterion**: copying only some modules throws `ImportError: cannot import name 'nodefile' from partially initialized module` at import time (`mdcg.py` has a top-level `from . import (nodefile, protect, routing, subgraph, chain, provenance, pooling, …)`). Ship the whole directory, or wait for package splitting (issue #672 has it registered as an evaluation item).
37
+
38
+ ---
39
+
40
+ ## 3. Persist timing: node files synchronous, index derivatives asynchronous (#677 P2)
41
+
42
+ A single `cg(op=write)` persists in **two layers** with **different** timing (a design trade-off, not a defect):
43
+
44
+ | Layer | Timing | Semantics |
45
+ |---|---|---|
46
+ | Node file `<root>/<layer>/<id>.md` | **synchronous** (on disk before the return) | source of truth; authoritative data |
47
+ | In-memory index (retrieval visibility) | **synchronous** (same `_stage` hook) | "searchable immediately after a write" is **not degraded** |
48
+ | Index derivative `_index_log/` shard logs (the flush triggered by the threshold) | **asynchronous** (background thread `mdcg-index-flush`) | derived data; rebuildable by replaying node files |
49
+
50
+ **Why asynchronous**: that flush must append entry by entry under a `FileLock` and open/close shard handles, which is the main cost on the RPC return path. The client's 60s timeout measures the **entire chain**, so "persisted but no reply" is read as a failure, and a retry creates duplicate entries (three pieces of evidence in issue #677). Moving this work off the return path sharply narrows the chance of "timeout ≠ failure".
51
+
52
+ **The price of asynchrony and the three exits** (lose any one and it degrades into "silent degradation"):
53
+
54
+ 1. **To be certain it persisted** -> `cg(op=maintain, action=flush)`: explicitly and **synchronously** writes the pending index
55
+ (returns `{ok, action:"flush", async, pending_dirty, worker_alive, last_error}`);
56
+ `cg.close()` / a normal process exit also persist synchronously (close semantics unchanged: return means persisted).
57
+ 2. **To see whether the index derivative lags the on-disk state** -> `os.index_flush` in `cg(op=info)`
58
+ (`{async, pending_dirty, worker_alive, last_error}`). A background persist failure **always leaves a trace**
59
+ (`last_error` + one stderr warning); it never lives only inside an exception.
60
+ 3. **To turn asynchrony off (back to the bit-for-bit old behavior)** -> the `MDCG_ASYNC_FLUSH=0` environment variable.
61
+
62
+ **An existing shape derived from this**: in the same process, after `del cg; gc.collect(); shutil.rmtree(path)` the directory may
63
+ **be recreated** (file timestamps carry the moment of deletion). To clean up a temporary store in tests, **start another process** (`subprocess` / a standalone script),
64
+ or call `cg.close()` explicitly before exiting.
65
+
66
+ ## 4. Timeout ≠ failure: look first, then write (#677 P1/P3)
67
+
68
+ On the write surface, **a timeout does not mean the write did not land**. The correct order after a timeout is **look first, then write**:
69
+
70
+ ```js
71
+ try { write({ content, dedupe: true }) } // dedupe:同层同内容复用既有节点(opt-in)
72
+ catch (e) {
73
+ const hit = await route(intent); // ① 先看落没落盘
74
+ if (!hit) write({ content, node_id }); // ② 确认没有再写,且**自带固定 node_id**
75
+ }
76
+ ```
77
+
78
+ - **Two ways to be idempotent**: supply your own `node_id` (overwriting the same id is naturally idempotent); or `dedupe: true`
79
+ (short-circuit reuse of an existing node by "same layer + content fingerprint", returning `deduped: true` and `content_sha`).
80
+ - **Neither is the default**: when `node_id` is not passed, the server generates one, so a retry adds a node — existing contract, unchanged.
81
+ - Where the rule lives: `md_cg/writepipe.py` (the idempotency gate short-circuits at the head of the chain, before reference resolution or edge creation).
82
+ - **Automatic memory is deduplicated by default** (issue #677 @1, 2026-11-05): the three kinds written by the
83
+ plugin (user/assistant/tool) carry `dedupe: true`, so a retry after a timeout no longer adds a duplicate node.
84
+ - **Deduplication is session-scoped** (the server compares `session`): the same text written by two different
85
+ sessions does **not** collapse — otherwise, with `sessionPrivate` on, the second session would "hit" the
86
+ first session's private node and silently read nothing.
87
+ - **Cost**: the same message repeated within one session is kept once — occurrence count, timestamps and
88
+ attribution are lost (tool results suffer most). Set `memory.dedupe` to `false` to keep duplicates.
89
+ - A hit adds no node but does **not** skip this round's gates (dedupe short-circuits at the head of
90
+ `mdcg_remember`; it reuses a node that already passed the gates). A dedicated `audit.deduped` counter is
91
+ not implemented yet.
92
+
93
+ ---
94
+
95
+ ## 5. The `rmtree` quirk on Windows + Python 3.12 (a Python issue, not this repository's)
96
+
97
+ `shutil.rmtree(root)` throws `FileNotFoundError`, yet `os.path.exists(root)` is `False` (the tree is in fact already gone).
98
+ The combination of nested directories and lock files makes it more likely. **Handling**: ignore the exception; do not treat it as a failed delete and retry the write.
99
+
100
+ ---
101
+
102
+ ## 6. Design trade-offs: they look like bugs but are contracts
103
+
104
+ ### 5.1 The default value and source of `importance`
105
+
106
+ The write surface gives `importance` a default (0.5 at the library layer, 0.6 commonly used by the plugin hint surface), and tags the source in `importance_source` (such as `hint`).
107
+ **This is not "a dirty store"** — the automatic memory surface writes at the "worth remembering" default tier and converges through later `scrub` / calibration.
108
+
109
+ ### 5.2 `importance >= 0.7` is a **hard protection**; a wrong write cannot be undone
110
+
111
+ `md_cg/scrub.py` says verbatim: **protected nodes (self/anchor/importance≥0.7/explicitly protected) are skipped; never deleted**.
112
+ The single-point constant is `protect.AUTO_PROTECT_IMPORTANCE = 0.70`.
113
+ **Meaning**: a high importance value is an application for never-forget protection; deleting after a wrong write requires an explicit `override`.
114
+
115
+ ### 5.3 `calibration` only suggests; it does not apply automatically
116
+
117
+ Calibration output looks like `{suggested_offset: -0.15, applied: false}`:
118
+ `suggested_offset` is a **suggested value**, and `applied` always reports whether it was actually applied (by default confidence is **not changed automatically**).
119
+ **This is a "human in the loop" trade-off, not a "knows but does not change it" bug**; applying it requires passing `apply` explicitly.
120
+
121
+ ### 5.4 `validity` excludes only "expired", not "not yet effective"
122
+
123
+ The `validity` semantics of `search` / `search_rrf` are **exclude expired** (`not_yet` is kept), while the name reads easily as "only valid ones".
124
+ Both read paths now report this faithfully in `meta.validity_scope`: `expired_only` (enabled) / `off` (not enabled).
125
+
126
+ ### 5.6 Minimum score thresholds: both `0` and `-1` mean "off"
127
+
128
+ The two threshold switches have **different defaults**, which is easy to misread:
129
+
130
+ | Variable | Default | Semantics |
131
+ |---|---|---|
132
+ | `MDCG_MIN_SCORE` | `0` | minimum score threshold of the fusion surface / T3 exit; **0 = off** (no filtering) |
133
+ | `MDCG_RECALL_MIN_SCORE` | `-1` | minimum score threshold of the recall surface (token-budget packing); **-1 = off**; set `0.01` to enable |
134
+
135
+ **The rule is unified as: only `> 0` counts as enabled**: a value of `0` or a negative number is always "off", not "threshold 0 (everything qualifies)" — the latter looks equivalent but actually erases the difference between "a real candidate that S5 pushed down to 0" and "a zero-score fallback".
136
+
137
+ Invalid values (non-numeric / `nan` / `±inf`) **fall back to the default and are recorded**: `min_score_input=invalid` in the read-surface meta means the setting is wrong.
138
+
139
+ One historical measurement-basis difference, for completeness (now unified): the fusion surface used `>0` while the recall surface used `>=0`, so `MDCG_MIN_SCORE=0` was off on one side and on for the other, and `-0.0` still opened the gate. Both now go through the same single parsing point.
140
+
141
+ ### 5.5 Orphan nodes must remain reachable by fallback recall
142
+
143
+ Nodes with empty `edges` and `access_count: 0` are hit by `T2_global_like` (the global lexical fallback path), and **this is a contract requirement**:
144
+ `md_cg/routing.py` says verbatim "the node stays in the ORPHAN/fallback pool (**it must remain reachable by fallback recall when S1 converges**, see contract §3, S1 invariant)". If you want "high-confidence results only", use the qualification adjudication tier (`judge` / `cg(op=route)`), not a threshold on the fallback path.
145
+
146
+ ---
147
+
148
+ ## 7. Session-level exclusion for automatic memory (#695)
149
+
150
+ An external bridge (e.g. a QQ bridge) calls `sessions.prompt()` with a wake-up/management protocol plus a chat snapshot,
151
+ and DSH projects that into a `user/message` whose `source.kind` is still `user` — and, **measured, it also carries**
152
+ `rpcId` (12/12), while a normal Web input only differs by the optional `clientTimeZone`. So lingshu **cannot** tell
153
+ "human input" from "bridge-synthesized prompt" by event shape alone; the `source_shapes` audit is two marginal
154
+ distributions (no kind × shape joint table).
155
+
156
+ Explicit fallback: `memory.excludeSessions` (default `[]`).
157
+
158
+ ```jsonc
159
+ { "memory": { "userMessage": true, "excludeSessions": ["sess_bridge_*"] } }
160
+ ```
161
+
162
+ - Exact match; entries ending with `*` match by prefix (`sess_bridge_*`). A bare `*` is **ignored** (otherwise one
163
+ entry would silently disable every session; use `userMessage=false` to disable globally).
164
+ - A matching session writes **nothing to the knowledge track** (user / assistant / tool skipped) and does not count
165
+ toward the every-ten-turns reminder.
166
+ - **The context-window write side still runs** (`_recent.jsonl`: runtime state, not searchable, not knowledge nodes);
167
+ the injection side is untouched.
168
+ - **No content-marker filtering**: strings like `【会话令牌】` are never used as a criterion.
169
+ - Malformed configuration (not an array / non-string items) means **no exclusion** (safe degradation).
170
+
171
+ ### Known costs
172
+
173
+ 1. **If a session mixes human input with synthetic prompts, the human content is dropped too.** Exclusion is
174
+ session-level, while a bridge is often "one group = one session". **Recommended: give bridge control prompts
175
+ their own session** (e.g. `sess_bridge_<channel>_*`).
176
+ 2. **Sessions with an empty `sid` (unassigned) cannot be excluded** — if the bridge does not pass a session id,
177
+ the switch silently does nothing.
178
+ 3. **Audit surface change**: `counts.filtered` gains a `session_excluded` key; `sumCounts` only tolerates a
179
+ missing **new** key, while a missing old key still marks the file corrupt.
180
+
181
+ ### Cleaning up already-polluted nodes (this switch only stops new ones)
182
+
183
+ ```text
184
+ cg(op=read, query="【会话令牌】") # or "【本次消息快照】"
185
+ # after manual confirmation, delete (importance >= 0.7 needs override=True)
186
+ ```
187
+
188
+ > **"No content-marker filtering" ≠ "cannot clean by marker"**: the marker stays out of code (it would kill real
189
+ > memories) and lives only in this runbook.
190
+
191
+ > True attribution needs a trustworthy source field from the host (option A in issue #695). Until then this switch is
192
+ > the honest "remember less rather than misremember" choice; real bridge chat should use a separate entry point.
193
+
194
+ ---
195
+
196
+ ## 8. Session memory isolation: `sessionPrivate` and the narrowing surface (#730)
197
+
198
+ ### 8.1 "Each session reads its own" uses the existing sensitivity mechanism
199
+
200
+ Server-side `_readable` (`md_cg/mdcos.py`): `public`/`internal` are cross-session levels;
201
+ `private`/`secret` are **session-bound** (only the owning `frontmatter.session` can read them,
202
+ `can_admin` exempts). Session-bound nodes without an owner are fail-closed (designer only).
203
+
204
+ So the plugin only needs to mark automatic memories `private`:
205
+
206
+ ```jsonc
207
+ { "memory": { "userMessage": true, "sessionPrivate": true } }
208
+ ```
209
+
210
+ - Default **false** (cross-session continuity is the existing default; cross-session recall is still a
211
+ product decision, see #749).
212
+ - When on, user / assistant / tool memories carry `sensitivity: "private"`.
213
+ - **Unassigned sessions are never marked private** — a private node without an owner is visible only to
214
+ the designer, i.e. effectively lost.
215
+
216
+ ### 8.3 Costs of enabling `sessionPrivate`
217
+
218
+ 1. **The session id must be stable across restarts**: visibility is `fm.session == principal.session`. If the host
219
+ generates a new `sess_*` on every start, private memories written last run cannot be read next run (not
220
+ "isolated" — lost; `recall` just returns less without error). The `s5` identity chain covers only part of the
221
+ paths — if the assistant seems to "forget" after enabling, turn the switch off and check session identity.
222
+ 2. **`private` is an encrypted level**: writing needs a master key (KEK/DEK). Without one the write is
223
+ fail-closed (not written), so on a keyless deployment enabling private means **no automatic memory at all**,
224
+ not "isolation works".
225
+ 3. **Only session flowing memories are affected**: knowledge-layer / distilled / direct `remember` writes stay
226
+ `internal`. Cross-session continuity should ride on **distilled knowledge**, not raw session turns — that is how
227
+ `sessionPrivate` and #749 coexist.
228
+ 4. **No owner, no private** (`sid` empty or exactly the `unassigned` sentinel) — private without an owner is
229
+ designer-only, i.e. written into the void.
230
+
231
+ > One line: **enable only if you want isolation; enabling costs cross-session continuity and restart readability.**### 8.2 `sessions_read` and the `narrowed_principal` narrowing surface
232
+
233
+ `sessions_read` limits the recent-event window in the resume package (it is **not** search visibility —
234
+ that is governed by sensitivity).
235
+
236
+ - Issue/derive: `tokens.issue(..., sessions_read=[...])` / `tokens.derive(..., sessions_read=[...])`
237
+ (derive takes the **intersection**; an empty intersection raises `TokenError`).
238
+ - CLI: `--sessions-read a,b`.
239
+ - Request-level narrowing: `as_unit` goes through `narrowed_principal`, which now propagates the owner
240
+ `sessions_read` (previously dropped: an owner restriction silently widened to unlimited, fail-open).
241
+ - Single source of narrowing fields: `tokens.NARROWING_FIELDS` (clearance / can_write / can_admin /
242
+ layers_allow / ops_allow / sessions_read), guarded by `test_issue730_narrowing_audit`.
243
+ - **No `as_session`**: `_readable` already rules that session identity cannot be self-declared;
244
+ switching sessions is privilege-neutral, not a narrowing.
@@ -0,0 +1,72 @@
1
+ > **Languages:** [中文](../../ops/安装与前置.md) · English
2
+
3
+ # Install and prerequisites
4
+
5
+ > This page was split from the original `README.md` (source: the "⚡ Quick start" section of the original README (L50–L116)).
6
+
7
+
8
+ ## One-command setup (recommended)
9
+
10
+ ### One-command setup (recommended)
11
+
12
+ ```bash
13
+ npx @furongjun1999/dsh-memory init
14
+ ```
15
+
16
+ After three interactive questions (**① entry point** 1=DSH plugin / 2=Claude Code / 3=Codex CLI / 4=generic MCP · **② memory root directory** (default `~/.lingshu/memory`) · **③ Python interpreter** (default `python`/`python3` depending on platform)), it produces:
17
+
18
+ 1. The **mcp.json config snippet** for the chosen entry point (with `MDCG_ROOT` / `MDCG_PYTHON` / the `command + args` command form, printed to the terminal);
19
+ 2. The snippet file **`lingshu-mcp-snippet.json`** (written to the current directory; copy the `mcpServers` key straight into the host configuration);
20
+ 3. **Next-step guidance**: where the snippet belongs (differs per host: cordis.yml / `.mcp.json` / `~/.codex/config.toml`), the [token issuance command](operations-troubleshooting.md#-write-credentials-make-memory-actually-persist) (requires a Python environment + this package's `md_cg`), discipline injection, and a brain self-check.
21
+
22
+ No appetite for questions? With all parameters supplied, run non-interactively (arguments after `--` go straight to the command):
23
+
24
+ ```bash
25
+ npx @furongjun1999/dsh-memory init -- --end claude --root /path/to/memory --python python3
26
+ ```
27
+
28
+ > init **only generates configuration** — it does not create directories, start a service, or write to the store; reruns produce identical output (idempotent). Global command forms: `lingshu init` / `lingshu-init`. **Or continue with the manual steps below.**
29
+
30
+ ## Choosing an entry point per host
31
+
32
+ > **Choose an entry point per host**: **DSH** -> the three steps below | **CodeBuddy · ZCode · Codex CLI · Claude Code** -> [Multi-harness integration](../mdcg/multi-harness.md#multi-harness-integration-directories-per-endpoint) (independent three-step instructions per host) | **Other MCP hosts** -> mount the brain directly with `python -m md_cg.mcp_server` (Windows) / `python3 -m md_cg.mcp_server` (Linux·macOS) (stdio MCP), then inject Engineering Discipline as needed
33
+
34
+ ## Manual three steps (DSH plugin form)
35
+
36
+ ```bash
37
+ # ① 克隆并构建插件本体
38
+ git clone https://github.com/FuRongJun-1999/dsh-memory.git
39
+ cd dsh-memory
40
+ npm install && npm run build # tsc → lib/
41
+
42
+ # ② 装进 DSH profile(pnpm 协调正确入口,勿用裸 npm install 装进 profile)
43
+ dsh plugin --profile web add .
44
+
45
+ # ③ 在 <profile>/cordis.yml 启用(配置示例见 dsh/cordis.yml.example)
46
+ ```
47
+
48
+ ```yaml
49
+ - id: furongjun1999-dsh-memory
50
+ name: '@furongjun1999/dsh-memory'
51
+ config:
52
+ mdcg:
53
+ # 记忆唯一真源(md 认知图)。留空 = 用户级默认位置
54
+ # ~/.dsh/.dsh-memory/data/mdcg(更新插件不丢);换位置请填**绝对路径**。
55
+ # 勿填包内相对路径(如 'data/mdcg')——那会把记忆写进插件包目录,
56
+ # pnpm 更新该包时连目录一起删掉(详见 dsh/cordis.yml.example 头注)。
57
+ root: ''
58
+ identity: '灵枢'
59
+ tools: 'core' # 'core'(默认, 仅 cg/stg) | 'brain' | 'all'
60
+ ```
61
+
62
+ ## Prerequisites, verified environments, and troubleshooting leads
63
+
64
+ - **Prerequisites**: Node ≥ 22.19 · DSH kernel ≥ 0.1.2-rc.1 · **verified up to DSH 0.17.2** · **the DSH 2.0 (`0.2.0-rc.2`) interface surface has been rechecked against the installed package, and real session event surfaces have been observed** (real occurrences of `origin='subagent'` / `delegationDepth>0` / `form='relay'` have still not been observed; see the [detailed version](../../mdcg/README详细版_v0.4.10.md)) · **zero-install brain** (`md_cg` ships with the package; no engine to pip install) · **a Python interpreter** (the plugin picks one per platform: Windows `python` / Linux·macOS `python3`; override with `MDCG_PYTHON` when the interpreter name is unusual)
65
+ - **Python versions (verified)**: **3.12.10 / 3.13.14 / 3.14.7 (Windows) pass this repository's own runs** · **no third-party runtime dependencies** (pure standard library, zero pip dependencies)
66
+ - **Full-suite prerequisites (six groups)**: the Rust toolchain plus `cd rust && cargo build --release` (evaluator cross-check surface) and `cd hive && cargo build --release` (Hive serve/routing surface); the suite discovers six groups by existence (`md_cg` / `compiler` / `swarm` / `scripts` / `hive` / `test`), **the target count changes with the checked-out content**; check it yourself with `python scripts/run_tests.py --list` (local run on 2026-10-05: 357 total)
67
+ - **Write permission is off by default**: without credentials it runs as a read-only `guest` (read / recall / timeline work; writes do not persist). To actually persist, see "Write credentials"
68
+ - Full configuration options (30+) · automatic memory mechanism · DSH watchdog -> [detailed README version](../../mdcg/README详细版_v0.4.10.md)
69
+ - **Non-DSH hosts** (CodeBuddy / ZCode / Codex CLI / Claude Code): use [Multi-harness integration](../mdcg/multi-harness.md#multi-harness-integration-directories-per-endpoint); each host has its own three-step integration instructions
70
+ - **Post-install verification**: after restarting DSH, tell the Agent "list your memory tools"; you should see `cg` / `stg` (plus `mdcg_*` when `tools: 'all'`); direct brain check: `python -m md_cg.mcp_server` (Windows) / `python3 -m md_cg.mcp_server` (Linux·macOS) (stdio JSON-RPC) is up as soon as it answers initialize; **if the tools never register and the logs keep printing `灵枢调用超时`**, first check the bridge probe `~/.dsh/logs/lingshu-bridge-debug.log` for `spawn … ENOENT` — that is the first cause (interpreter name mismatched with the platform); "call timed out" is only a secondary symptom. For more detail see the [detailed README version](../../mdcg/README详细版_v0.4.10.md)
71
+ - **Scope of automatic injection** (issue #554 §2/§4): automatic injection covers only **this session's recent timeline** (`stg(op=timeline, session=<当前会话>)`); **it does not recall across sessions**; use explicit `cg(op=route)` / `cg(op=read)`. Isolated or multi-`DSH_HOME` installs must explicitly set `MDCG_DSH_SESSIONS_ROOT=<该 home>/sessions`, otherwise node sessions degrade to `anonymous` and automatic injection finds no data.
72
+ - **Automatic memory troubleshooting** (issue #56): the three filter branches (subagent sessions / relay messages / `source.kind !== 'user'`) and the write/skip paths each leave an **on-disk** trace: the bounded on-disk audit at `~/.dsh/logs/dsh-memory-hook-audit.json` (same directory and conventions as the bridge probe above): which messages were filtered by design, the `source.kind` distribution, write/skip counts (redacted to empty / cognitive map not ready / write failed), and the most recent ≤20 summaries (only action/reason/kind/role, **never message content**). When "it was clearly said in the conversation but memory does not have it", look there first: filtered by design is recorded as `filtered`, write failure or a missed record as `skipped`
@@ -0,0 +1,86 @@
1
+ > **Languages:** [中文](../../ops/运维与排障.md) · English
2
+
3
+ # Operations and troubleshooting
4
+
5
+ > This page was split from the original `README.md` (source: the three sections "Write credentials", "Restart after an upgrade", and "FAQ" of the original README (L118–L195)).
6
+
7
+
8
+ ## Restart the long-running MCP process after an upgrade (generation check)
9
+
10
+ ### ♻️ Restart the long-running MCP process after an upgrade (generation check)
11
+
12
+ > **The one-line operational premise**: **when the code changes, restart the resident MCP process** — do not wait for an `ImportError` before you start troubleshooting.
13
+
14
+ **Root cause (confirmed)**: the LINGSHU brain (`md_cg`) is a **long-running stdio process** that only reads from disk at a module's **first import**; meanwhile `md_cg` contains **many deferred imports written inside functions** (a good share of them to avoid circular imports). The two combine: after an upgrade (switching packages / `git pull` / reinstall), **old-generation modules loaded before the upgrade** and **new-generation modules imported lazily after it** are mixed across generations in the same process. Measured symptom: a `cg` write returns `ImportError: cannot import name 'mint_auto_id' from 'md_cg.mdcg'` while **the on-disk state is perfectly fine** (a fresh interpreter imports the same module normally) — the error point is far from the root cause and is easily misjudged as "the code is broken".
15
+
16
+ **Self-check**: call `cg(op=info)` once against the **running** serve and read these five fields:
17
+
18
+ | Field | Meaning |
19
+ |---|---|
20
+ | `code_generation` | the first 12 characters of the code fingerprint **at the moment the process started** (= the generation the process actually holds) |
21
+ | `disk_generation` | the first 12 characters of the fingerprint of the code **on disk right now** |
22
+ | `stale_on_disk` | the two differ ⇒ the on-disk code has moved to a new generation (`true`) |
23
+ | `restart_required` | same truth value as `stale_on_disk` — time to restart |
24
+ | `hint` | a one-line handling hint in Chinese |
25
+
26
+ The fingerprint is a **content hash** (sha256 over the sorted (relative path, file bytes) of `md_cg/**/*.py`, skipping `__pycache__` and `test_*.py`), so a "rewrite with no change" (packing, unpacking, checksum write-back) does not falsely report a new generation. `stale_on_disk: true` means this process is stuck on the old generation.
27
+
28
+ **Handling**: **restart the resident MCP process** — on the DSH side, restart DSH (or refresh the Web UI so the plugin re-pulls the brain subprocess); other hosts reconnect to that MCP server. **Memory data is lossless**: not one byte of the on-disk source of truth moved; the restart only makes the process read one generation of code anew.
29
+
30
+ **There is also a startup gate**: before the service actually starts serving, every "deferred import inside a function" on disk is trial-resolved once (import the target module -> take the name); a missing name **refuses startup** and makes the process exit non-zero, with stderr naming the offending submodule and name. A "half-upgraded" package therefore exposes itself at startup rather than blowing up during some later write.
31
+
32
+ ## Write credentials (make memory actually persist)
33
+
34
+ ## 🔑 Write credentials (make memory actually persist)
35
+
36
+ ```bash
37
+ # 签发(明文不进配置文件)
38
+ python -m md_cg.tokens issue --role designer --actor dsh-memory --clearance internal ^
39
+ --ops-allow info,route,read,write,recent,goal,identity,whitebox,verify ^
40
+ --layers-allow knowledge,contextual,structural,self,goals,unresolved,rejected
41
+ setx MDCG_TOKEN "mdcg1.xxxxx" # 然后重启 DSH
42
+ ```
43
+
44
+ ```yaml
45
+ env:
46
+ MDCG_TOKEN: !!js process.env.MDCG_TOKEN
47
+ ```
48
+
49
+ > `--role recorder` is the least-privilege version (automatic memory / transcription only; `whitebox`, `identity`, and `verify` are rejected).
50
+ > **The necessary and sufficient condition for persisting = the final verdict is ACCEPT**: `cg(op=write)` must pass through the three gates audit -> consistency -> gated (three questions, four states) in order; anything other than ACCEPT adds no persist point.
51
+ > **Do not treat `ok: true` as a successful write**: when nothing persists the response looks like `{"ok": true, "committed": false, "moved_to": "review_queue"}` — `ok` only means the request was accepted; **persisting is decided by `committed` alone**. `text` writes are reviewed under the **default policy** (the policy ships with the package: `<package>/data/policy.json`, overridable with `MDCG_POLICY_FILE`) — missing any of the six CCG elements or hitting the forbidden list yields `REJECT` (`moved_to: "rejected"`, recorded in negative memory); to persist immediately, use a verifiable type such as `content_kind: 'code'` (AST parse passes = `ACCEPT`). **When the policy itself is unavailable** (`MDCG_POLICY_FILE` points at a bad path, the packaged default cannot be read either, **or the policy content shape is invalid**), writes **fail-closed**: nothing persists and nothing enters the review queue (returns `moved_to: "policy_unavailable"` + an error code and hint), and the body is never stuffed into `hippocampus/inbox.jsonl`. **Invalid shape criterion**: if any value of the four list-typed keys `forbidden` / `required` / `required_kinds` / `required_labels` is not an array (written as a scalar such as `1` / `true`, or written as a string), it is invalid — values outside arrays have no single reading, so the gate does not guess and does not split a string into per-character rules (error code `policy_bad_shape`). The policy source is visible in the startup stderr, `python -m md_cg.mcp_server --show-config`, and the `write_policy` field of `cg(op=info)` (`env` / `package_default` / `unavailable`); the diagnostic surface **always exits 0**, and when the policy is unavailable `available: false` with `error` giving the error code and an actionable hint — if `--show-config` reports `policy_bad_shape`, the policy file has a wrong key type.
52
+ > **`text` writes must carry the six CCG elements** (function name / effective condition / sub-functions / execution / verification method / non-applicable conditions, one per line, each starting with `# 要素名:`): missing elements are rejected outright by the write gate (`moved_to: "rejected"`, `committed: false`, recorded in negative memory), and the response's `verdict.detail.missing` gives the **complete list of what is missing** — rewrite with the list filled in; you do not have to wait for a read-back to discover it. The requirement is defined by the rule base's `required` and `required_kinds` (default policy = `data/policy.json` in the package, shipped with the npm package; a policy pointed to by `MDCG_POLICY_FILE` overrides it), and **you can adjust it**: change the policy by editing that file (or keep your own copy and set `MDCG_POLICY_FILE`), not the code.
53
+
54
+ ## FAQ
55
+
56
+ ## ❓ FAQ
57
+
58
+ <details>
59
+ <summary><b>Why can't I install into the profile with a bare <code>npm install</code>?</b></summary>
60
+
61
+ Installation must use `dsh plugin --profile <name> add .`: the plugin declares 6 `peerDependencies` (cordis / dsh-llm / dsh-session / dsh-system-prompt / dsh-tools / schemastery), and `dsh plugin add` goes through pnpm, which resolves the peer versions the host provides correctly; a bare `npm install` installs the wrong dependency versions into the profile and breaks loading. `npm install` at the repository root is only for development builds (`npm run build`).
62
+ </details>
63
+
64
+ <details>
65
+ <summary><b>Installed the plugin / configured the credentials and nothing took effect?</b></summary>
66
+
67
+ DSH uses the Cordis bundle mechanism; after adding or updating a plugin you must **restart the DSH process** (or refresh the Web UI page) for it to reload; the same holds after configuring `MDCG_TOKEN` via `setx` — a restart is required for it to be visible (see [Write credentials](#-write-credentials-make-memory-actually-persist)).
68
+ </details>
69
+
70
+ <details>
71
+ <summary><b>How do I confirm the Agent really wrote the memory in?</b></summary>
72
+
73
+ Look at the <code>committed</code> field of the response, and <strong>do not treat <code>ok: true</code> as a successful write</strong> — <code>{"ok": true, "committed": false, "moved_to": "review_queue"}</code> means the request was accepted but <strong>not persisted</strong> (the content went into the review queue). The necessary and sufficient condition for persisting = all three gates finally return <code>ACCEPT</code>.
74
+ </details>
75
+
76
+ <details>
77
+ <summary><b>Why did my write not persist?</b></summary>
78
+
79
+ The three most common causes: ① no write credentials configured -> read-only <code>guest</code>, writes do not persist (for credentials see <a href="#-write-credentials-make-memory-actually-persist">Write credentials</a>); ② <code>content_kind</code> omitted or set to <code>text</code> -> reviewed under the **default policy** (<code>data/policy.json</code> in the package, overridable with <code>MDCG_POLICY_FILE</code>): missing any of the six CCG elements or hitting the forbidden list means <code>REJECT</code> (recorded in negative memory, not persisted) -> use a verifiable type such as <code>content_kind: 'code'</code> (AST parse passes = ACCEPT); ③ it did not pass any of the audit -> consistency -> gated gates (three questions, four states).
80
+ </details>
81
+
82
+ <details>
83
+ <summary><b>Do other hosts such as CodeBuddy / ZCode / Codex CLI / Claude Code work too?</b></summary>
84
+
85
+ Yes. The brain <code>md_cg/</code> is a standard stdio MCP server (<code>python -m md_cg.mcp_server</code>), so any host that supports MCP can mount it directly; the five integrations differ only in how discipline is injected, see <a href="../mdcg/multi-harness.md#multi-harness-integration-directories-per-endpoint">Multi-harness integration</a>.
86
+ </details>
@@ -0,0 +1,79 @@
1
+ > **Languages:** [中文](../../ops/权限与复核模型.md) · English
2
+
3
+ # Permissions and review model: read / write / adjudicate layers
4
+
5
+ > This document is the full version of the README "Permissions" section: token issuance and narrowing, layered write gates, dual-unit adjudication, and an error reference.
6
+
7
+ LINGSHU runs as a **read-only guest** by default (it can read but cannot write). Writing and adjudication require a token and follow the three rulings of 2026-10-27:
8
+
9
+ > **The Designer is read-only · writes must be careful · adjudication requires review by reflection and verification units.**
10
+ > The reason: drift and amnesia of the self persona are destructive, and full permissions on an unreliable system are a disaster.
11
+
12
+ ## 1) Tokens: issue, narrow, health-check
13
+
14
+ ```bash
15
+ # 签发(不传 --ops-allow 即角色默认;designer 的默认是 ["*"] 全集)
16
+ python -m md_cg.tokens issue --role designer --actor my-agent
17
+
18
+ # 收窄成「只读面」——给界面、自动化、子智能体用这个(只能收窄,不能放大)
19
+ python -m md_cg.tokens issue --role designer --actor ui-panel \
20
+ --ops-allow info,help,status,edges,read,route,recent,identity,self_state,\
21
+ metacognition,review,protect,evolution,sustain,goal,task,whitebox
22
+
23
+ # 体检(含 designer 覆盖面缺口报告)
24
+ python -m md_cg.tokens verify --token-file-in <令牌文件>
25
+ ```
26
+
27
+ | Surface | Suggested for | op boundary |
28
+ |---|---|---|
29
+ | **Read-only surface** (17 ops) | UI panels, subagents, read-only inspection | as listed above; **excludes** `write` / `verify` / `forget` / `scrub` / `consolidate` / `index_*` / `export` / `maintain` / `link` |
30
+ | Write surface | recording units | adds `write` (+ `session` / `ingest` / `ccg` as needed) |
31
+ | Adjudication surface | verification units | adds `verify`; the `redteam` gate and re-approval still apply |
32
+
33
+ After issuance, inject it into the host: `config.env.MDCG_TOKEN` (for example the DSH profile config), or write it to the keyring at `~/.mdcg/token`;
34
+ the token store defaults to `~/.mdcg/_tokens.json` (override with `MDCG_TOKEN_FILE`).
35
+
36
+ ## 2) Layered writes: each layer stricter than the last
37
+
38
+ `MDCG_WRITE_GATE` controls whether this table takes effect (`off` by default / `warn` records only / `enforce` actually blocks):
39
+
40
+ > **Where to see `warn` records**: `cg(op=info).write_gate` -> `{mode, total, by_layer, recent, hint}`.
41
+ > They are recorded **in-process** (not on disk, reset on restart), so they do not depend on whether the host forwards subprocess stderr —
42
+ > this matters: DSH does **not** forward MCP subprocess stderr by default, so looking only at the logs makes it seem like "warn recorded nothing".
43
+
44
+ | Tier | Layer | Required when a review channel exists | **When no review channel exists** |
45
+ |---|---|---|---|
46
+ | 0 | `contextual` · `goals` · `unresolved` · `rejected` | none | ✅ direct write allowed (relaxed channel) |
47
+ | 1 | `knowledge` | reflection unit | ❌ write rejected |
48
+ | 2 | `structural` | reflection + verification unit | ❌ write rejected |
49
+ | 3 | `self` · `anchor` | reflection + verification + **human adjudication** | ❌ write rejected |
50
+
51
+ Review channels are **declared** with `MDCG_REVIEW_CHANNELS` (any of `hive,subagent,team`). Note: the variable is a **deployment declaration**; empty only means "never declared" and does **not** mean this machine has no subagents, Hive, or teams.
52
+
53
+ ## 3) Adjudication: dual-unit review, no self-certification
54
+
55
+ With `MDCG_REVIEW_DUAL_CHECK=1` enabled, an adjudication must carry both kinds of review unit:
56
+
57
+ ```python
58
+ cg(op="review", action="decide", pid="…", decision="accept",
59
+ reviewed_by=["反思单元", "验证单元"]) # 中英文同义均可:reflect / verify / human
60
+ ```
61
+
62
+ | Condition | Behavior |
63
+ |---|---|
64
+ | Missing reflection or verification | `dual_check_required` (names the missing side) |
65
+ | Two of the same kind (two reflections) | still counts as missing verification — **same-side mutual confirmation is not review** |
66
+ | Adjudicator == proposer | `self_review_forbidden` |
67
+ | Unknown unit | `unknown_review_unit` (not silently counted) |
68
+
69
+ It is **orthogonal** to the existing gates: `redteam` + `needs_reapproval` handle rejection and re-approval; `verify_readonly` handles "criteria are declared by propose and cannot change at adjudication time"; this gate only answers "who reviewed it".
70
+
71
+ ## 4) Error quick reference
72
+
73
+ | Error | Meaning | Action |
74
+ |---|---|---|
75
+ | `AccessDenied: 本令牌的 ops 作用域不含 op=xxx` | the token's ops scope is narrowed and lacks that op | re-issue with the missing `--ops-allow`, or switch to a token that has it |
76
+ | `designer_coverage_gap` (`verify` output) | the Designer token lacks the inspect/adjudicate surface | re-issue with the missing ops; the gaps are listed |
77
+ | `write_gate ... deny` | the target layer needs review and there is no channel/evidence right now | declare `MDCG_REVIEW_CHANNELS` or add review units; or switch to `warn` first and observe |
78
+ | `dual_check_required` / `self_review_forbidden` | see the table above | add units / change the adjudicator |
79
+ | `redteam_required` / `reapproval_required` | red-team gate and re-approval | include `redteam.verdict=pass` (round count increments) |
@@ -0,0 +1,49 @@
1
+ > **Languages:** [中文](../../ops/发布与治理.md) · English
2
+
3
+ # Release and repository governance (decision record v1.0)
4
+
5
+ > This page records governance decisions that are **deliberately this way**, so that later maintainers or an AI do not treat them as defects and "fix" them. Every entry states: the decision / the reason / the conditions under which it changes.
6
+
7
+ ## 1. Release is a single point (one person and a manual OTP): **deliberately maintained**
8
+
9
+ **Current state**: npm releases are published only by the maintainer in person, running `npm publish` on their own machine, which requires an interactive OTP. **No CI auto-publish is configured**, and no `NPM_TOKEN` secret is added.
10
+
11
+ **Reasons (maintainer ruling, 2026-10-20)**:
12
+
13
+ 1. The core asset of this project is not the code but the **intelligence theory / theoretical architecture**, and nobody (and no AI) can currently take over that theory;
14
+ 2. Auto-publishing would strip the "release decision" away from theoretical judgment and create a channel where "a machine ships automatically on a tag", which conflicts with the fact that the theory has too large a blast radius to ship without the single person who understands it acting as the gate;
15
+ 3. The manual cost of single-point release (one OTP) is far smaller than the theoretical spillover cost of one wrong release.
16
+
17
+ **Compensating controls in place**:
18
+
19
+ - `main` branch protection: required checks (`run-tests` / `discipline` / `cogmap` / `workspace-index` / `publish-artifact`), force pushes blocked, branch deletion blocked;
20
+ - Pre-release gate: the `prepublishOnly` hook of `npm publish` runs `build && test && gate`;
21
+ - Tag discipline: a `v*` tag is placed only on a commit where CI is fully green;
22
+ - Release notes must state "known limitations" and must not leave the illusion that "everything looked green".
23
+
24
+ **Conditions that change this** (re-evaluate automation when any one holds):
25
+
26
+ 1. A second maintainer appears who **understands the theoretical architecture** (not merely someone with repository write access);
27
+ 2. The release frequency grows until manual OTP is a real bottleneck (currently about 1-2 times per week, which is not a bottleneck);
28
+ 3. npm offers a mechanism that is equivalent to OTP and also persists "who approved what" as an auditable record.
29
+
30
+ ## 2. `main` protection: **enabled**
31
+
32
+ - Required status checks: see above;
33
+ - `enforce_admins = false`: the maintainer keeps an emergency bypass (which leaves a GitHub audit record), because a single-person project has no second person who could approve instead;
34
+ - PR approvals are not required: in a single-person project that would be the formalism of approving your own work; CI carries the quality gate.
35
+
36
+ ## 3. CI concurrency and queuing
37
+
38
+ Every workflow enables `concurrency` (runs of the same workflow on the same ref are cancelled on a new push), so that several pushes in one day do not queue `run-tests` for more than 30 minutes.
39
+
40
+ **Paths filtering is deliberately not added to `python-tests`**: the workflow already contains a design comment: the suite spans `md_cg/`, `hive/`, `compiler/`, `swarm/`, and `scripts/`, and a single omission in a paths allowlist would bring back the blind spot where "a change does not enter the gate".
41
+
42
+ ## 4. Dependency updates
43
+
44
+ dependabot opens one group of PRs per week for `npm` and one for `github-actions` (minor and patch combined, at most 3), turning dependency rot from a pulse of discoveries into small routine fixes.
45
+
46
+ ## 5. Where this does not apply
47
+
48
+ - This document does not govern the **code quality gate** (that is decided by each workflow and `npm run gate`);
49
+ - This document does not cover where release credentials are stored (credentials live only in the maintainer's local keychain; they are not committed to the repository and not added to CI secrets).
@@ -0,0 +1,30 @@
1
+ > **Languages:** [中文](../../ops/工具名迁移_0.9.9.md) · English
2
+
3
+ # Tool name migration (as of 0.9.9)
4
+
5
+ ## What changed
6
+
7
+ | Version | Tool names |
8
+ |---|---|
9
+ | ≤ 0.9.8 | lingshu_cg / lingshu_stg / lingshu_mdcg_reflect |
10
+ | ≥ 0.9.9 | cg / stg / mdcg_reflect |
11
+
12
+ Reason: previously the prefix was composed from serverName, which produced identification errors where "the same MCP service showed different tool names on different hosts".
13
+ serverName is still used for internal provider/log identification.
14
+
15
+ ## Impact (issue #634)
16
+
17
+ Long-running sessions, agent orchestration, or scripts that are **running** during the upgrade hit `unknown tool` immediately after the upgrade if they hard-code the old names;
18
+ newly opened sessions are unaffected. The host logs and the plugin logs both show successful registration, and the error appears only in the caller — that is the hardest part to troubleshoot.
19
+
20
+ ## Migration
21
+
22
+ 1. Caller side: drop the `lingshu_` prefix (lingshu_cg -> cg);
23
+ 2. Configuration side: the tools selection table in the profile matches the raw MCP-side names, so writing either lingshu_cg or cg does not change the selection result;
24
+ 3. Compatibility: from 0.9.12 the lingshu_* aliases are also registered by default (their description carries the `已弃用别名` deprecated-alias label and points to the same implementation);
25
+ set toolAliases: false to keep only the bare names.
26
+
27
+ ## Why aliases are not kept long term
28
+
29
+ Two sets of names would put "one tool with two identities" into the model context, and would make audit logs contain two spellings.
30
+ Aliases are only an upgrade buffer and are planned for removal after one minor cycle; the README and this page will note it then.
@@ -0,0 +1,53 @@
1
+ > **Languages:** [中文](../../ops/图形界面_安装与排障.md) · English
2
+
3
+ # Graphical interface: installation, pages, and troubleshooting
4
+
5
+ > This page is the full version of the "Graphical interface" section in the README: installer behavior, the semantics of the seven pages, three pitfalls confirmed by testing, and how changes take effect.
6
+
7
+ LINGSHU itself is an MCP server and plugin and ships no interface of its own. `ui/minimal/` is an **optional add-on package**: after it is installed into the LINGSHU plugin directory,
8
+ a "LINGSHU" panel appears on the left side of DSH, and you can also visit `http://127.0.0.1:<DSH端口>/lingshu` directly.
9
+
10
+ ```powershell
11
+ # 先只检查(不写任何文件,可随时跑)
12
+ powershell -ExecutionPolicy Bypass -File ui/minimal/install.ps1 -PluginPath <你的灵枢插件目录> -CheckOnly
13
+
14
+ # 安装(就地上屏;只改 UI 代码与插件清单)
15
+ powershell -ExecutionPolicy Bypass -File ui/minimal/install.ps1 -PluginPath <你的灵枢插件目录>
16
+
17
+ # 卸载(逐文件恢复安装前内容)
18
+ powershell -ExecutionPolicy Bypass -File ui/minimal/install.ps1 -PluginPath <你的灵枢插件目录> -Uninstall
19
+ ```
20
+
21
+ > **Since 0.9.15: the wiring ships with the repository and the npm package**: `dsh.client` / `exports["./client"]` (in `package.json`) and the
22
+ > `installConsoleWeb(...)` call (in `src/index.ts`) are both in the repository; static artifacts are generated by `scripts/build_ui.py`
23
+ > (run automatically by `build` and `prepublishOnly`; `--check` only validates). So **changing the plugin manifest no longer requires reinstalling the UI**.
24
+ > When installing from the npm package into a local plugin directory, `install.ps1` only needs to lay down the static artifacts; for **old plugin packages without wiring** it still completes the manifest automatically.
25
+
26
+ | What the installer lays down | What the installer does **not** touch |
27
+ |---|---|
28
+ | the 9 payload files (`web/` · `lib/client.js` · `console_web.mjs` · `build-ui.mjs`) | the DSH profile / plugin root / memory store |
29
+ | (old packages without wiring only) adds the `dsh.client`, `exports["./client"]`, and `lib/index.js` wiring | credentials, tokens, the automatic memory switch |
30
+ | - | your existing node data |
31
+
32
+ **How changes take effect**: the client bundle and the `/plugins/lingshu/*` routes are registered **when DSH starts**, so **DSH must be restarted** after installation (the installer prints the same reminder).
33
+
34
+ ## The seven pages and the "command panel" semantics
35
+
36
+ | Page | Content |
37
+ |---|---|
38
+ | Overview / Memory | loads on open (recent memories, retrieval, and write entry points) |
39
+ | Goals and tasks · Self-cognition · Spatiotemporal relations · Review and maintenance | **command panel**: opens empty; pick an operation first, then click "Run query" |
40
+ | Toolbench | reads the real LINGSHU tool catalog live; fill in a form or write JSON directly to invoke |
41
+
42
+ > Write operations and adjudications **require a second confirmation** in the interface (the request carries `confirm:true`, otherwise the server returns 409); read-only queries do not.
43
+
44
+ ## Troubleshooting (three pitfalls confirmed by testing)
45
+
46
+ | Symptom | Cause | Action |
47
+ |---|---|---|
48
+ | `分享包文件缺失或损坏:web/index.html` (the file is clearly there) | the payload was checked out with CRLF and mismatches `integrity.json` (which records the sha256 over LF) | since 0.9.15 `.gitattributes` pins `eol=lf`; on older versions, have git re-check out that directory (`git rm --cached -r ui/minimal/payload && git checkout -- ui/minimal/payload`) |
49
+ | `之前安装的文件发生改变` / the same message on uninstall | a stale `.lingshu-ui-backup-v1/state.json` from an older version is left in the plugin directory (it records an outdated hash) | move that directory out of the plugin directory as a whole (keeping the backup), then re-run the installer |
50
+ | No "LINGSHU" panel on the left after installation | (1) DSH was not restarted (2) `package.json` lacks `dsh.client` (3) the browser cached the old frontend | (1) restart (2) re-run the installer (3) hard refresh (Ctrl+Shift+R) |
51
+
52
+ > Data does not leave this machine: the UI reuses the local brain bridge of your existing LINGSHU install; `/plugins/lingshu/call` enforces same-origin checks plus CSRF plus the DSH login state, and returns 401 without a login.
53
+ > Step-by-step instructions for end users are in [`ui/minimal/使用说明.md`](../ui/minimal.md).