@furongjun1999/dsh-memory 0.9.18 → 0.9.21

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.
@@ -0,0 +1,384 @@
1
+ # 世界模型功能端 · 使用与运维指南(v1.0)
2
+
3
+ > **这一页回答一件事:语义时空图「状态层」上线后,你怎么记账、怎么查、开关在哪、怎么复跑读数、边界到哪。**
4
+ > 依据:`docs/plans/语义时空图补全_世界模型功能端_设计_v0.1.md`(六签收点)与 `docs/秤_记忆系统评测规范_v2.1.md` §5.1(账本完整性口径)。
5
+ > 使用者定位(2026-10-06):「0.7.4 把世界模型,也就是语义时空图的地基打好。」本页对应 P3 批(写侧入口 + 账本完整性探针 + 使用文档)。
6
+
7
+ ---
8
+
9
+ ## 一、一句话
10
+
11
+ **事件是源、槽位是投影、查询走 stg**:
12
+
13
+ ```
14
+ 记账(写口) 台账(源) 投影(物化视图,查询时现算) 查询面
15
+ cg(op=state_event) → <root>/_state_events.jsonl → md_cg/state_slots.py → stg(op=state_chain)
16
+ (MCP 面) append-only、不截断 (只读台账、不落盘、不缓存) (默认关)
17
+ ↘ CLI:python -m md_cg.state_slots
18
+ ```
19
+
20
+ 四个面各有单点真源,互不复制:写口只做权限/归一/落盘(`md_cg/mcp_server.py`),
21
+ 台账只管追加(`md_cg/state_events.py`),投影只管回放(`md_cg/state_slots.py`),
22
+ 查询面只管开关与返回体成形(`md_cg/stg.py`)。
23
+
24
+ ---
25
+
26
+ ## 二、台账(源)在哪、长什么样
27
+
28
+ | 项 | 内容 |
29
+ |---|---|
30
+ | 位置 | 库根下 `_state_events.jsonl`(与 `_recent.jsonl`、`_write_2pc.jsonl` 同级) |
31
+ | 性质 | **append-only**:只追加、不读改写、不截断(窗口滚动面 `_recent.jsonl` 不可作一等记录,故单立此账) |
32
+ | 一行一条 | `{t, subject, slot, old, new, kind, seq, evidence, actor}` |
33
+ | `kind` 五类 | `migration` 迁移 / `retraction` 撤回 / `enablement` 启用 / `acquisition` 获得 / `replacement` 替换;**未分类(None)合法** |
34
+ | 撤回语义 | `old` 有值、`new` 空 = 值作废、无新值;启用=old 空、new 有值;迁移/替换=皆有值 |
35
+ | 坏行 | 容忍 ≠ 静默:跳过时计数 + 有界样本 + stderr 告警(`state_events.BAD_ROWS` 可读) |
36
+ | 多进程 | 跨进程文件锁(`FileLock`),崩溃不留半截文件(flush+fsync) |
37
+
38
+ **记账不判语义**:`kind` 只是检索面标签,不进判据;「不是事实」的言语(玩笑/元层/回忆转述)
39
+ 之消歧标记(`not_fact`)**不在本批**(见 §八 边界)。
40
+
41
+ ---
42
+
43
+ ## 三、写:MCP 记账口 `cg(op=state_event)`
44
+
45
+ ### 用法
46
+
47
+ ```
48
+ cg(op="state_event", subject="鲸娘", slot="住所",
49
+ old="别墅", new="小屋", kind="migration", seq=1108, evidence="r1108")
50
+ ```
51
+
52
+ | 参数 | 必填 | 说明 |
53
+ |---|---|---|
54
+ | `subject` | 是 | 事件主体(谁的状态);去空白后为空即报错 |
55
+ | `slot` | 是 | 事件槽位(哪项状态);同上 |
56
+ | `old` / `new` | 至少一个 | 变更前/后值;**双空非法**(空事件无意义)。撤回=`new` 留空 |
57
+ | `kind` | 否 | 五类之一;缺省/空串/纯空白 → 归一为「未分类」(None);其它值报错 |
58
+ | `seq` | 否 | 轮或序号(回指语料位置用) |
59
+ | `evidence` | 否 | 出处(短证/轮号/文件路径皆可,回查用) |
60
+
61
+ 返回体:`{"ok": true, "event": {…落盘记录…}}`(`event` 即 append 落盘的那一行)。
62
+
63
+ ### 失败口径(fail-closed,不吞)
64
+
65
+ | 情形 | 结果 |
66
+ |---|---|
67
+ | 缺/空 `subject`、缺/空 `slot` | `ValueError`(点名缺哪项) |
68
+ | `old` 与 `new` 双空 | `ValueError` |
69
+ | `kind` 非法值 | `ValueError`(列出允许五类) |
70
+
71
+ 以上都是**原样上抛**的 `ValueError`(不是包装过的错误),客户端按普通错误处置即可——
72
+ **失败即不落盘**。
73
+
74
+ ---
75
+
76
+ ## 四、读:投影与查询
77
+
78
+ ### 1. 查询面 `stg(op=state_chain)`(默认关,见 §五)
79
+
80
+ ```
81
+ stg(op="state_chain", subject="鲸娘", slot="住所", include_retired=true)
82
+ ```
83
+
84
+ 返回体沿 stg 既有口径:`count`(条件命中总数,截断前)/ `items`(前 limit 条)/
85
+ `kept` / `truncated`。单元字段:
86
+
87
+ | 字段 | 语义 |
88
+ |---|---|
89
+ | `value` | 现值(撤回后为 null,直到下一个带值事件复活) |
90
+ | `state` | `active` / `retired`(**退役不删除**;缺省查询剔除 retired,`include_retired=true` 可见) |
91
+ | `t_from` / `t_to`、`seq_from` / `seq_to` | 生效区间与序号:`*_from` =最后产生当前值的事件;`*_to` =覆盖它的下一条事件(未被覆盖=null=仍有效/未闭合) |
92
+ | `tier` | 来源档位(台账行顶层 `tier` 透传;未带=`unspecified`,**不编造**) |
93
+ | `history` | 该槽位全部事件原样七字段(`t/seq/old/new/kind/evidence/actor`);`history=false` 时不带该键 |
94
+ | `alternatives` / `blindspots` | 结构在场、**恒空列表**(判定口径后置,见 §八) |
95
+ | `event_count` | 该槽位事件条数 |
96
+
97
+ **投影是物化视图不是第二真源**:查询时从台账现算,不落盘、不缓存——台账追加一条,
98
+ 下一次查询结果即变。
99
+
100
+ ### 2. CLI 人工入口(`md_cg.state_slots`,**恒可用**)
101
+
102
+ ```
103
+ python -X utf8 -m md_cg.state_slots --status
104
+ python -X utf8 -m md_cg.state_slots --subject 鲸娘 [--slot 住所] [--include-retired] [--no-history]
105
+ ```
106
+
107
+ 数据根取 `MDCG_ROOT`(缺省走 `datapath.mdcg_root()`)。本 CLI 与 `MDCG_STG_STATE`
108
+ 开关**无关**——那把开关管的是 MCP 读面;CLI 是只读人工排查入口(不改任何状态)。
109
+
110
+ ---
111
+
112
+ ## 五、开关
113
+
114
+ | 开关 | 缺省 | 管什么 |
115
+ |---|---|---|
116
+ | `MDCG_STG_STATE` | **关** | MCP 查询面 `stg(op=state_chain)`;关臂返回 `{"error": "disabled", "hint": …}`(**不是异常**——「没开」与「没命中」必须可分辨);与 `MDCG_STG_INDEX`/`MDCG_STG_QUALIFY` 同纪律 |
117
+ | (无开关) | — | `cg(op=state_event)` 记账口**恒可用**(受权限闸约束,见 §六);`md_cg.state_slots` CLI **恒可用** |
118
+
119
+ ---
120
+
121
+ ## 六、授权口径(与既有令牌面零新词)
122
+
123
+ - **`state_event` 走 `write` 词映射**:`cg` 面 op 作用域闸按 `write` 判定——
124
+ 凡 `ops_allow` 白名单含 `write` 的角色(或用 `"*"` 的设计者令牌)可记账;
125
+ guest/只读令牌照拒。令牌面**不引入新 op 词**(角色白名单与派生收窄面零改动)。
126
+ - **`actor` 恒取令牌**(请求参数不生效):落盘 `actor` 永远是令牌身份(无令牌形态为
127
+ `"system"`)——客户端不得改写归属(沿本仓既有防伪造口径)。
128
+ - **写闸双保险**:台账是直写盘面的 append-only 文件、**绕过库层节点写闸**,故记账口
129
+ 另显式补齐 `require_write("internal")`——`can_write` × `theory_ok` × 密级三态各自生效
130
+ (只读令牌、版本层校验未过、clearance 不足 internal 都会被拒且不落盘)。
131
+
132
+ ---
133
+
134
+ ## 七、读数与复跑:探针 + 守卫
135
+
136
+ ### 1. 账本完整性探针(《秤》5.1 口径)
137
+
138
+ ```
139
+ python -X utf8 scripts/probe_c_ledger_integrity.py \
140
+ --events %TEMP%/state_events.jsonl --expect-slots 住所,房贷,名字 \
141
+ [--out %TEMP%/probe_c_out]
142
+ ```
143
+
144
+ | 读数 | 口径 |
145
+ |---|---|
146
+ | ① 事件覆盖缺口率 | `--expect-slots` 清单中「台账无任何记录」的槽位占比(分子/分母都打印) |
147
+ | ② 无账可辨率 | 对「无记录槽位」+固定合成不存在槽位查询 `state_chain`:`count==0 且 items==[]`(**不编造、不反推**)的通过比例 |
148
+ | ③ 变迁史可查率 | 有记录槽位中 `state_chain`(`include_retired=True`、`history=True`)返回的 history 条数合计 == 台账该槽位记录数 的比例 |
149
+
150
+ 特性(硬性):只读输入;隔离 temp root(把 `--events` 拷为该 root 的
151
+ `_state_events.jsonl`)——**零记忆库写入**;`--out` 必须落在仓外(fail-closed);
152
+ **确定性**(同输入两次运行 stdout 与 `--out` 产物字节一致);
153
+ stdout 末行 `PROBE_C_LEDGER_JSON {...}` 摘要(机器可读),`--out` 时另落
154
+ `rates.json` + `probe_c_slots.jsonl`。
155
+
156
+ ### 2. 写口守卫
157
+
158
+ ```
159
+ python -X utf8 -m md_cg.test_state_event_op # 全链/双闸/防伪造/归一/校验/回归
160
+ python -X utf8 -m md_cg.test_state_event_op --mutate # 定点变异自证(每条机制必须能被断言钉红)
161
+ ```
162
+
163
+ ---
164
+
165
+ ## 八、边界(如实)
166
+
167
+ - `alternatives`(同期未决值)/ `blindspots`(声明缺口)判定口径**后置**:本批结构在场、
168
+ 恒空列表,**不臆造填充**。
169
+ - 「不是事实」的言语(玩笑/元层/回忆转述)之**消歧标记**(`not_fact` 等)不在本批
170
+ (P1 事件行无该信号)。
171
+ - 探针只测**账本面**可辨性;**生成器级「无账强答」未测**——那需要接生成器侧读数,后置。
172
+ - 槽位按**标签面精确匹配**(slot 名相等),不做同义归并/模糊匹配。
173
+ - `state_chain` 无 `time_axis` 语义:台账事件行只有落账时间戳 `t`,无第二轴(**不伪造**);
174
+ 需要轴语义请走 `stg` 的 timeline/relation/anchors。
175
+ - 单库=单台账:跨库/多租户合并不在此。
176
+
177
+ ---
178
+
179
+ ## 九、退役纪律:节点生命周期 `archived`(默认检索剔除)
180
+
181
+ > 《秤》v2.1 §5.2「退役纪律」口径的落地页。**先分清两个「退役」**(同名不同物):
182
+
183
+ | 说谁 | 字段 / 参数 | 谁管 |
184
+ |---|---|---|
185
+ | 台账**槽位单元**的生存态(§四) | 投影单元 `state` = `active`/`retired`,查询参数 `include_retired` | `md_cg/state_slots.py`(查询时现算) |
186
+ | **节点**(md 记忆条目)的归档态(本节) | frontmatter / 索引 `lifecycle_state` = `archived` | `md_cg/lifecycle.py` 状态机 + 读面剔除 |
187
+
188
+ ### 1. 语义(写定,逐档可对拍)
189
+
190
+ | `lifecycle_state` | 默认读/注入面(检索面 · stg 面 · 会话续接包全段) | 说明 |
191
+ |---|---|---|
192
+ | `active`(**缺键或非法值同此**) | 参与 | fail-open:存量节点零迁移、不误剔 |
193
+ | `converged` | 参与 | **降权轴**(同构聚合定型),不是退役 |
194
+ | `demoted` | 参与 | **降权轴**(弱化),不是退役 |
195
+ | `archived` | **默认剔除** | 退役不删除:节点文件仍在、可显式恢复 |
196
+
197
+ ### 2. 判据与落点(判据单点,三个消费面)
198
+
199
+ - 判据单点:`lifecycle.is_archived(e)`(`md_cg/lifecycle.py`)≡ `state_of(e) == "archived"`;
200
+ 全部消费点共同引用,不各写一份口径。
201
+ - 消费点 ①(**cg 检索面**):`MdCGOS._candidates`(`md_cg/mdcos.py`)——**检索类** cg 读 op
202
+ (`route` / `read` 的检索分支与 `budget_tokens` 预算召回分支 / `search` / `search_rrf` 及其
203
+ 内含的 lexical·bucket·entity·graph·chain·temporal 各路)都经这一个候选池;
204
+ `MdCGSecure._candidates` 经 `super()` 在其上叠加读可见性,判据同源。
205
+ 注意:cg 的读 op 并非全走候选池——见消费点 ③(会话续接面自持取数面)。
206
+ - 消费点 ②(**stg 扫描面**):`stg._scan_one`(`md_cg/stg.py`,`_scan` 的逐条实现单点)
207
+ ——`timeline` / `anchors` / `consistency` 三 op 的候选面同点覆盖,索引子集
208
+ (`MDCG_STG_INDEX=1`)与全量遍历两条分支逐位一致。`relation` 是显式 id 直读、
209
+ `state_chain` 走台账,两者都不经候选面(不受本节约束)。
210
+ - 消费点 ③(**会话续接注入面**):`MdCGOS.session_recall`(`md_cg/mdcos.py`)的
211
+ **四个取数段**——会话要点 `_session_notes`、活跃目标 `goals`、任务台账 `tasks`、
212
+ 未解问题 `unresolved`(`goals`/`tasks` 经 `_retired_by_id` 按 id 回查索引后交同一
213
+ 判据)。`cg(op=session, action=recall)` 自持取数面(不经 `_candidates`),它把节点
214
+ 内容装配成「续接包」回给调用方/注入上下文(=注入面),故同接本判据。台账两段
215
+ 取**全量窗**(`_LEDGER_WINDOW`)过滤后截断 `_PACK_ROWS=5` 条,故退役剔除不会让
216
+ 包「不足额」;`tasks.active_total/done_total` 随之取**剔除后**的全窗计数(与列表
217
+ 同源自洽)。`recent` 段是事件窗口(非节点)、`self_state` 是只读快照卡,不涉退役。
218
+ (独立复核 2026-10-06 两轮实测:接线前 archived 要点摘要、未解问题正文、活跃目标
219
+ 与任务卡均经该 op 照旧回出;现由守卫 R1.12/R1.13/R3.5/R3.6/R4.6 钉住。)
220
+
221
+ ### 3. 不受限面(「退役不删除」的另一半)
222
+
223
+ - `cg.get(node_id)` 直读、`cg(op=audit)` 证据审计视图:archived 期间**照常可达**;
224
+ - 工程台账面(`goal` / `task`)与统计面(`health` / `whoami` / conformance):直读索引,
225
+ 不受本节约束;
226
+ - **生命周期恢复**:库层入口 `MdCG.set_state(node, "archived"→"active")`
227
+ (`md_cg/mdcg.py:2619` → `lifecycle.set_state`,走合法迁移表、逐级不跳级);恢复后
228
+ 读面/续接面重新可见。**MCP 工具面没有独立生命周期入口**(`mcp_server.py` 全文无
229
+ `set_state` / `lifecycle` 字样)——「显式恢复」是库层调用面。
230
+ - 与 `op=restore` 的区别(易混,写明):`op=restore` 是 `op=forget` 的 `action=restore`
231
+ → `cg.restore`(`md_cg/mdcos.py:3029`)=把**已遗忘**(软删除进 `trash/`)的节点放回,
232
+ 是**删除轴**,与生命周期状态机无关;且放回时 `lifecycle_state` 按新节点(`active`)
233
+ 起判,`active→archived` 跳级被拒 ⇒ **不透传(落 `active`)**(既有行为,本轮未改)。
234
+
235
+ ### 4. 复跑读数
236
+
237
+ ```
238
+ python -X utf8 scripts/probe_d_retirement_discipline.py # 《秤》v2.1 §5.2 探针
239
+ python -X utf8 -m md_cg.test_lifecycle_retire_leak # 守卫 R1–R4
240
+ ```
241
+
242
+ | 读数(`PROBE_D_JSON`) | 口径 | 目标(面计数,括号内为比率) |
243
+ |---|---|---|
244
+ | ① 退役泄漏率 | 退役后 v2 仍出现在查证面(读面 search∪recall、时空面 timeline∪anchors)的面数 / 面数 | `0/2`(0.0) |
245
+ | ② 更新采纳率 | v2 写入后可见的面数 / 面数(防「一刀切全滤」的反向缺陷) | `2/2`(1.0) |
246
+ | ③ 旧事实残留率 | 退役步之后 v1 仍可见的面数 / 面数(不连带误剔) | `2/2`(1.0) |
247
+ | ④ 失效误判证伪率 | 退役节点被错误置 falsified/rejected 的条数 / 退役节点数(退役 ≠ 证伪) | `0/1`(0.0) |
248
+
249
+ (探针人读行打印的就是**面计数**「n/分母(目标 m)」;上表与它同单位,比率为换算值。)
250
+
251
+ 探针特性:隔离 temp root(零在役库写入)、纯 stdlib、无随机/无时间戳、
252
+ `--out` 必须落在仓外(fail-closed)、末行 `PROBE_D_JSON {...}`,**两遍运行 stdout 字节一致**。
253
+
254
+ ### 5. 边界(如实)
255
+
256
+ - 只剔 `archived`。要让 `converged`/`demoted` 不参与,请走既有其他维度
257
+ (`role` / `view` / `layer` / `session` / `validity`)——不得把它们并进退役判据。
258
+ - 台账单元退役(§四 `retired`)与节点退役(本节 `archived`)**各自独立、互不联动**。
259
+ - **面的判据(写死,供后续接线照此归类)**:**默认读/注入面**=调用方给查询/意图/会话视图,
260
+ **节点集合由库自选**且结果直接回给调用方或注入上下文 ⇒ 必须消费 `is_archived`;
261
+ **定向/管理/统计面**=调用方给出**显式节点选择键**(`node_id` / `subject:*` 标签 / 前缀 /
262
+ 层 / 状态)或面本身是诊断·统计·写面 ⇒ 直读,不受本节约束。
263
+ - 已接线消费面(3 处,4 子面):检索面 `_candidates`、stg 面 `_scan_one`、会话续接注入面
264
+ `session_recall` 的**全部四个取数段**(要点 `_session_notes` + 活跃目标 + 任务台账 +
265
+ 未解问题;后两段经 `_retired_by_id` 按 id 判据)(§2)。
266
+ - **已枚举但归入「定向/管理/统计面」(不受限,逐条申报)**:`cg.get` 直读、`op=audit`
267
+ 证据审计、**工程台账的显式管理查询面**(`cg(op=goal, action=list)` / `cg(op=task,
268
+ action=list)`——直读台账,archived 期间照样列出,守卫 R1.13c 钉住这一侧)、
269
+ `health`/`whoami`/`_role_counts`/`_sensitivity_counts`/`conformance`/`census`/`insight`
270
+ 统计、`review_records` 审核记录、`export`/`evidence` 导出与证据面、`crosscheck`/
271
+ `ghostref`/`consistency` 诊断面、`backfill*`/`writelimit`/`freshness`/`forgetting`
272
+ 维护写面、`mreview/govern` 治理面、白箱 KB 工具面。
273
+ **注意别与消费点 ③ 混读**:同一份 goal/task 台账,**注入面(续接包)剔除 archived、
274
+ 管理查询面直读**——这不是矛盾,是判据两侧的分工(守卫同时钉住两侧:R1.13b 剔除、
275
+ R1.13c 直读)。
276
+ 其中**会回内容且集合由库自选**的一个代表面如实点名:`identity.profile`
277
+ (`md_cg/identity.py:310`,按 `subject:<id>` 标签自选并回锚点正文摘录)——实测 archived
278
+ 锚点仍回出(取证:`identity.profile` 返回的 `anchors[0].content` 含归档节点正文标记);
279
+ 按上条判据它属**定向面**(`subject_id` 是显式选择键,与 `cg.get` 同族),故**本轮未接线**
280
+ (其文件不在本轮允许改动面内)。
281
+ - **面的接线状态(2026-10-06 使用者裁定批落地——原「已知未覆盖面」四项处置)**:
282
+ - **基类 `MdCG.search` → 已接线**(`md_cg/mdcg.py` 候选条件加 `lifecycle.is_archived`
283
+ 判据):plain `MdCG` 实例(白箱 KB / 离线脚本 / 测试)的默认检索面与生产路径
284
+ 同口径(守卫 R5,含「converged 降权轴不误剔」对照)。
285
+ - **因果链/图面 `chain.adjacency` → 已接线**(新增 `skip_archived=True` 缺省参数):
286
+ 退役节点出边整体不入表、指向退役目标的边截断——`cg(op=causal, action=chain)`、
287
+ `predict.*` 等读/预测面不再扩散进 archived(守卫 R6.0/R6.1/R6.4,含缓存已热
288
+ 时归档的实测腿)。**维护面显式旁路**:`scrub` 去污染抽查传
289
+ `skip_archived=False` 取全量表(守卫 R6.2/R6.3 钉住旁路——面的判据分工:
290
+ 默认读/注入面必消费、维护/管理面直读)。
291
+ - **缓存失效钩子(本批实证的兑现缺口)**:状态迁移改变 `is_archived` 读数,
292
+ 而 `chain` 邻接缓存在 `set_state` 后此前**未失效**(探针实证:归档后
293
+ `causal_chain` 仍含目标)——现 `lifecycle.set_state` 写盘点同点调用
294
+ `chain.invalidate_cache`(懒导入,`invalidate_cache` 自吞异常不阻断推进)。
295
+ - **结构/拓扑面 `subgraph.children_index` / `parents_index` → 裁定不接**
296
+ (调用方给显式父/子 id、返回 id 映射不回正文,属定向/结构面,直读)——
297
+ 守卫 R7.0/R7.1 把裁定**钉住**:子节点退役后映射仍在;未来若有人"顺手接线",
298
+ R7.1 转红即提醒先改裁定。
299
+ - **rust 检索内核 → 已接线**(`rust/src/store.rs`):`Entry` 增
300
+ `lifecycle_state` 字段(键名与 Python `lifecycle.STATE_FIELD` 同源)、
301
+ `candidates()` 剔除 `archived`(缺键/非法=active,fail-open;converged/
302
+ demoted 仍参与)——crate 单测 `archived_entries_excluded_from_candidates`
303
+ 与 `lifecycle_state_parsed_from_index_json` 双钉;两侧口径一致由
304
+ `rank_parity` 门禁腿继续看守(评测语料无 archived,逐位零位移)。
305
+ - 跨进程一致性:判据只读**本进程索引条目**(`lifecycle_state` 由
306
+ `lifecycle._sync_index` 随迁移同步并落 `_index_log`),他进程刚归档、本进程索引
307
+ 尚未重载的窗口内读数可能滞后(与 `lifecycle.set_state` 的既有落盘口径同源)。
308
+
309
+ ---
310
+
311
+ ## 十、多主体状态追踪(核心能力与常驻读取视图)
312
+
313
+ > 使用者 2026-10-06 定位:「这个功能可以常驻,维护其他角色的状态追踪,这应该要
314
+ > 作为语义时空图的核心功能。」
315
+
316
+ **能力陈述**:状态追踪(多主体 · 五元事件 · 槽位投影)是语义时空图的**核心功能**——
317
+ `subject` 参数化到任意主体(角色/机构/我),台账(`_state_events.jsonl`)为唯一真源,
318
+ 其余全为投影/视图。
319
+
320
+ **常驻形态**=**查询时现算的只读视图**(与 `state_slots` 同哲学,不存第二真源):
321
+ 任何时刻调用即得最新;不依赖后台任务。工具面(均在 `scripts/`):
322
+
323
+ | 件 | 用途 |
324
+ |---|---|
325
+ | `state_atlas.py` | **通用多主体追踪图**(常驻件):一份 md=全角色世界书(现值/退役/变迁史/大事记/分幕)+可选 `--worldbook-json`(酒馆风格 key/content) |
326
+ | `whale_state_tracker.py` | 语料线抽取器(把会话语料转五元事件;鲸娘规则集,机件可仿建他角色规则包) |
327
+ | `whale_state_atlas.py` | 语料线专用追踪图(从抽取产物 md 生成) |
328
+ | `state_slots.py`(CLI) | 槽位投影只读入口(恒可用,`--status` 等) |
329
+ | `stg(op=state_chain)` | MCP 查询面(flag `MDCG_STG_STATE` 默认关——纪律不变,与 CLI 恒可用互补) |
330
+
331
+ **库根解析(与 zcode MCP 同源,防双库分叉)**:`--root` > env `MDCG_ROOT` >
332
+ `~/.zcode/cli/config.json` 的 `mcp.servers.mdcg.env.MDCG_ROOT` > `mdcg_root()` 缺省。
333
+ **只读纪律**:工具面只读,`--out` 一律仓外(fail-closed)。
334
+
335
+ **记账纪律(通用指引,从鲸娘线三层消歧口径提炼)**:①状态变更发生时记账(谁的
336
+ 什么槽位、old/new、五类 kind);②**用户侧声明优先**(用户明确说出的状态为准,
337
+ 角色自述的「记错」不复盖真值);③非事实三类(玩笑/元层/回忆转述)如实标注、
338
+ 不覆盖真值;④撤回=old 有值 new 空(显式作废,不做静默改写)。
339
+
340
+ **在役现状(2026-10-06 实测)**:权威库(AEIS 数据区库根——根解析同源口径见上)
341
+ 台账**0 条事件**——机制全链就位、数据处女地;多主体渲染由隔离库演示验证
342
+ (2 主体/30 事件/15 槽位/15 条 worldbook 条目,读数见 `docs/eval/` 报告 v1.2 节)。
343
+
344
+ **待裁(常驻自动化的可选增强)**:是否在睡眠周期「整理」档挂一步
345
+ 「按主体预生成追踪图 md → 状态面」——现状为**按需现算**(打开即最新),预生成仅为
346
+ 「打开就有文件」的缓存物;改常驻循环属生产行为变更,须单独立项。
347
+
348
+ ### 会话链路接入(轮写入链第二步;使用者 2026-10-06 裁定)
349
+
350
+ > 「把这个功能作为会话的 10 轮信息写入,并在写入 mdcg 的时候做处理……每次写入
351
+ > 异步加了一些过程,但是好处是得到了可维护的状态,同时具备了认知图和语义时空图,
352
+ > 原始信息的关系追溯。」
353
+
354
+ - **接线单点**:`scripts/sync_zcode_session.py::sync_to_window`(zcode 端每轮——
355
+ Stop 钩子/冷启动/压缩恢复共用同一链路)——写 `_recent` 窗口的**同一循环内**对同一轮
356
+ 调 `scripts/state_extract.py` 保守抽取 → `state_events.append` 进台账。钩子在轮末以
357
+ 子进程运行(会话外处理,即「异步」),**逐轮 fail-soft**(抽取失败绝不影响窗口写入
358
+ 与轮次推进)。
359
+ - **保守口径(写入在役库的纪律:宁可漏不可误)**:只抽**用户轮**(真人=事实源);
360
+ 仅两条高精度规则(`地点·所在` 迁移 / `情感·偏好`,负向显式记「不喜欢:」);值剥
361
+ 句尾语气词;**同值去重**(防每轮重复记账);证据 `[auto] session=… turn=…`、
362
+ `actor=state_extract`——可整体甄别/清理;开关 `MDCG_STATE_EXTRACT` **缺省开**
363
+ (=0 关)。探针已证:裸词形(承诺 138 / 因果 59/225 命中)不进规则表。
364
+ - **三层同源+关系追溯**:认知图(`_recent`/知识面)+语义时空图(台账/`state_slots`
365
+ 投影/`state_atlas` 视图)+原文(会话 md 镜像/全量转写)——事件 `evidence` 带
366
+ session/轮号/短证,任一层可回查另两层。
367
+ - **读数**:守卫 `scripts/test_state_extract.py` **10/10**(噪声三族零命中、去重、
368
+ 变值成链、证据格式、开关、接线单点)+全量 **359/359**。
369
+ - **DSH 端**:同款接线位于插件侧(TS)——属后续件(须改插件并随包发布);本批仅
370
+ zcode 端在线,DSH 端行为不变。
371
+ - **已知边界(留裁决)**:「住在这里」类泛化词形会命中(值取「里」等)——v1 词形
372
+ 如此,收窄与否归使用者。
373
+
374
+ ---
375
+
376
+ ## 修订记录
377
+
378
+ | 日期 | 要点 |
379
+ |---|---|
380
+ | 2026-10-06 | v1.0 首版(P3 批):全链(台账→投影→查询→记账口→CLI→探针)/ 开关 `MDCG_STG_STATE` 默认关与 CLI 恒可用 / 授权口径(`state_event`→`write` 词映射,actor 恒取令牌)/ 探针三读数复跑命令 / 边界如实(§一–§八) |
381
+ | 2026-10-06 | 补 §九「退役纪律」:节点 `lifecycle_state=archived` 的默认检索剔除(判据单点 `lifecycle.is_archived`,消费面 `MdCGOS._candidates` + `stg._scan_one` + 会话续接注入面 `session_recall` 四段〔要点/活跃目标/任务台账/未解问题〕)/ 两套「退役」词义分界 / 不受限面(直读·审计·**台账管理查询面**·统计)与「生命周期恢复 ≠ `op=restore`(删除轴)」/ 《秤》5.2 探针四读数(面计数口径)与守卫复跑 / 边界如实(未覆盖面:基类 `MdCG.search`、因果链面 `chain.adjacency`、结构面 `subgraph`、rust 内核、定向面 `identity.profile`) |
382
+ | 2026-10-06 | **边界四项裁定批落地(使用者裁定:1/2/4 接、3 不接)**:基类 `MdCG.search` 接线(R5)/ `chain.adjacency` 接线(`skip_archived` 参数,R6;scrub 维护面显式旁路)/ rust 内核接线(crate 单测双钉)/ `subgraph` 结构面**裁定不接**(R7 钉住裁定);并补 `lifecycle.set_state` 的 `chain.invalidate_cache` 同点失效(本批探针实证的缓存缺口);守卫 36→45 断言 |
383
+ | 2026-10-06 | **补 §十「多主体状态追踪」(核心能力定位,使用者 2026-10-06)**:常驻形态=查询时现算只读视图(不存第二真源);工具面四件(`state_atlas` 通用多主体 / 语料线两件 / CLI);库根解析与 MCP 同源(防双库分叉);记账纪律四条(从鲸娘线三层消歧口径提炼);在役台账 0 条实测+隔离多主体演示读数;睡眠档预生成列为待裁 |
384
+ | 2026-10-06 | **补 §十「会话链路接入」(轮写入链第二步,使用者 2026-10-06 裁定)**:`sync_to_window` 同循环内对同一轮保守抽取(`state_extract`:仅用户轮/两条高精度规则/去重/证据可甄别;开关缺省开)→ 台账;三层同源+关系追溯;守卫 `test_state_extract` 10/10、全量 359/359;DSH 端同款接线列后续件 |
@@ -0,0 +1,128 @@
1
+ # 写入别名(aliases)规范 v0.6
2
+
3
+ > 2026-10-31 · 起因:issue #722「条件闸门按字面匹配,自然问法普遍判 DEFER」
4
+ > **本规范有实测闭环支撑**:机制已就绪(#719)、案例已验证有效、库内使用率 0%。
5
+ > v0.1–v0.5 五版走的都是「改判定 / 改条件质量」,均被实测推翻;本版改走**写入侧补别名**。
6
+
7
+ ## 一、实测依据(全部可复现)
8
+
9
+ ### 1.1 决定性案例(issue 报告人给出)
10
+
11
+ 条件:聊交接、换会话、压缩、或他流露舍不得时
12
+ 查询:我不想你被换掉
13
+
14
+ | 匹配方式 | 结果 |
15
+ |---|---|
16
+ | **整词 in**(现状) | ❌ 不命中 |
17
+ | **二元组重叠** | ❌ 换会/会话 vs 我不/不想/想你/你被/被换/换掉 —— **交集空** |
18
+ | **查询扩展**(expand_query_terms) | ❌ 扩出 换掉/被换,与 换会话 **仍无交集** |
19
+ | **现有同义词表**(10 组,全技术词) | ❌ 无 会话/换掉 组 |
20
+ | **加 aliases**(换掉/被换/别消失/舍不得/不想你走/会交接/换会话/压缩上下文) | ✅ **命中**(False → True) |
21
+
22
+ ⇒ **四条字面路全废,只有别名有效。**
23
+
24
+ ### 1.2 库内现状(全量 + 抽样)
25
+
26
+ | 项 | 读数 |
27
+ |---|---|
28
+ | aliases 覆盖率 | **0 / 120 = 0%** |
29
+ | 生效条件为**元数据**的比例 | **65 / 85 = 76.5%**(抽样 120,结构化槽标签判据) |
30
+ | knowledge 层里 role=None(索引卡片) | **99.7%**(30,468 / 30,558) |
31
+ | 自然问法召回条数 | **2 条 / 32,845** |
32
+
33
+ ⇒ **机制有、有效、但没人用**——这是 #722 的全部真相。
34
+
35
+ ## 二、规范
36
+
37
+ ### 2.1 写什么
38
+
39
+ > **写记忆时,aliases 至少包含「用户可能怎么问这件事」的说法。**
40
+
41
+ **不是**:技术术语缩写、字段名、路径片段。
42
+ **而是**:用户会说的口语、情绪表达、近义说法。
43
+
44
+ 以 1.1 的案例为例,条件是 聊交接、换会话、压缩、或他流露舍不得时,
45
+ aliases 写成:换掉 / 被换 / 别消失 / 舍不得 / 不想你走 / 会交接 / 换会话 / 压缩上下文。
46
+
47
+ ### 2.2 为什么不写进 tags
48
+
49
+ tags 已被机器判据占用(是不是任务卡:tasks.py;能不能当锚点:anchor.py / predict.py)。
50
+ 塞别名会**改变那些判据**。aliases 与 tags **物理分离**,只参与检索召回。
51
+
52
+ ### 2.3 怎么生成(**推荐用 LLM 自问**)
53
+
54
+ > **写别名时,先自问一句:「以后我会怎么问这件事?」——把那些问法原样写进 aliases。**
55
+
56
+ 具体做法(写入方=LLM 时):
57
+
58
+ 1. 读完这条记忆,**先不看条件**,自问:「如果三个月后我忘了这条,我会用什么话把它问出来?」
59
+ 2. 写出 **3–8 个**这样的问法/关键词(口语、情绪、近义说法都算);
60
+ 3. 把它们写进 `aliases`;原文里已有的词不必重复(判据会判"薄")。
61
+
62
+ **示范**(#722 案例):
63
+
64
+ ```
65
+ 条件:聊交接、换会话、压缩、或他流露舍不得时
66
+ 自问:以后会怎么问?
67
+ → 「换掉」「被换」「别消失」「舍不得」「不想你走」「会交接」「压缩上下文」
68
+ aliases: 换掉 / 被换 / 别消失 / 舍不得 / 不想你走 / 会交接 / 换会话 / 压缩上下文
69
+ ```
70
+
71
+ ⚠️ **不要机械抽词**。实测(2026-10-31):从功能名按空格切词自动生成别名,
72
+ 5 个真实问法 × 20 条节点 = **提升 +0**——因为中文功能名没有空格,切出的是整句,
73
+ 与"用户会怎么说"毫无关系。**别名必须由理解内容的一方预判,不能自动生成。**
74
+
75
+ ### 2.4 判据(可执行)
76
+
77
+ `aliases_is_thin(fm) -> bool`:**无 aliases**,或**所有别名都能在正文/条件里原样找到**
78
+ (= 只重复已有词、没扩召回首)⇒ 判为「薄」。
79
+
80
+ ⚠️ **不判「数量够不够」**——3 个精准别名可能胜过 10 个噪声别名。
81
+
82
+ ## 三、写入守卫(warn 优先)
83
+
84
+ 复用 #708 的 write_gate 三档:
85
+
86
+ | 档 | 行为 |
87
+ |---|---|
88
+ | off | 不检查 |
89
+ | **warn(默认)** | 写入成功 + 计数 + 提示「本条无扩展别名,自然问法可能召不回」 |
90
+ | enforce | 拒绝写入 |
91
+
92
+ **不阻断写入**:别名是锦上添花,不是正确性前提。缺它不该让记忆写不进去。
93
+
94
+ ## 四、旧数据(明确不批量回填)
95
+
96
+ 32,845 节点批量补别名**不现实**(需要理解每条内容)。现实路径:
97
+
98
+ 1. **新写入**按本规范(守卫 warn 起步);
99
+ 2. **热点优先**:对实际召不回的查询**事后补**别名(哪个召不回补哪个);
100
+ 3. **可观测**:`cg(op=info)` 透出「无别名节点数」,作为改进基线。
101
+
102
+ ## 五、验证方式(每条都要能测)
103
+
104
+ | 断言 | 怎么测 | 现状 |
105
+ |---|---|---|
106
+ | 别名能救 #722 案例 | 同 1.1 的对比 | ✅ **已测**(False → True) |
107
+ | 库内别名覆盖率 | 抽样读 fm.aliases | ✅ **已测**(0/120) |
108
+ | 字面路全废 | 整词 / bigram / 扩展 / 同义词表逐一对比 | ✅ **已测**(全部空交集) |
109
+ | aliases_is_thin 能识别现状 | 对抽样跑,≈100% 判为薄 | 待建 |
110
+ | 别名不污染 tags 判据 | 加别名后「是不是任务卡」「能不能当锚点」不变 | ✅ **已测**(PR #719 的 C/D 组守卫) |
111
+ | warn 档不阻断写入 | 无别名节点仍写入成功、只计数 | 待建 |
112
+
113
+ ## 六、不适用条件
114
+
115
+ 1. **不解决「完全没预判到的说法」**——别名靠人写,写不到的仍召不回;
116
+ 2. **不替代语义检索**——semantic 覆盖率为 0,是另一条工程线;
117
+ 3. **不批量回填旧数据**;
118
+ 4. **不改变 tags 语义**(那个字段的机器判据不动);
119
+ 5. **不支持自动生成别名**——实测(2026-10-31):从功能名/正文机械抽词,5 个真实问法 × 20 条 = **提升 +0**。
120
+ 别名必须由理解内容的一方(人或 LLM)**预判用户会怎么问**来写。
121
+
122
+ ## 七、判据演进留痕(勿重蹈)
123
+
124
+ | 版 | 方向 | 为什么被推翻 |
125
+ |---|---|---|
126
+ | v0.1–v0.4 | 改判定算法(文本来源 / 弱态 / S3 图扩散 / 主题面) | **对象错配**:被判定的是 99.7% 的索引卡片 |
127
+ | v0.5 | 改条件质量(判是否元数据) | **诊断而非解法**——元数据条件是索引器产物,改不了 |
128
+ | **v0.6** | **写入侧补 aliases** | ✅ 机制现成(#719)+ 案例验证有效 |
package/md_cg/mdcg.py CHANGED
@@ -5412,7 +5412,13 @@ class MdCG:
5412
5412
  # 正是为了让旧调用方零改动(钩子由调用点显式传入,不靠 self 解析)。
5413
5413
  if index_keys and index_keys.get("hit"):
5414
5414
  return True
5415
- tags = " ".join(str(t) for t in (fm.get("tags") or []))
5415
+ # 命名与检索规范 R2(2026-10-30):`aliases` 是**名称别名表**,与 `tags` 物理分离——
5416
+ # 只参与检索召回,**不参与**身份/路由判据(tasks 的「是不是任务卡」、predict 的
5417
+ # 「能不能当锚点」都只读 tags,别名不得混入,否则会翻转那些判据)。
5418
+ # 容错:aliases 非 list 时按空处理(脏 frontmatter 不抛)。
5419
+ _aliases = fm.get("aliases")
5420
+ _aliases = _aliases if isinstance(_aliases, list) else []
5421
+ tags = " ".join(str(t) for t in ((fm.get("tags") or []) + _aliases))
5416
5422
  if body_lower is not None:
5417
5423
  body_l = body_lower(entry, content)
5418
5424
  else:
package/md_cg/mdcos.py CHANGED
@@ -4686,6 +4686,12 @@ class MdCGOS(MdCG):
4686
4686
  # 修前只留 role/text/t,模型因此无法判断「这条是哪个会话说的、私有还是
4687
4687
  # 共有、谁说的」——「跨窗口串台」的用户侧困惑正源于此。
4688
4688
  # 取值一律防御式(meta 可能缺失/非 dict),与上一段的既有写法同款。
4689
+ # 宪章第十五条(复读污染)· 注入过滤:给重复事件**加标注**(不折叠、不删条目——
4690
+ # 用户可能真的把同一句话说两遍,实测库里就有一条 x7 的是真发的)。
4691
+ # 只标不折:条数不变,模型能看到「这条重复了 N 次」。(history 去重
4692
+ # `repeat_guard.dedupe` 留给显式要求折叠的调用方,本段不用它。)
4693
+ from . import repeat_guard as _rg
4694
+ evs = _rg.annotate(evs)
4689
4695
  pack["recent"] = [{"role": r.get("role"),
4690
4696
  "text": (r.get("text") or "")[:300],
4691
4697
  "t": r.get("t"),
@@ -4697,7 +4703,9 @@ class MdCGOS(MdCG):
4697
4703
  # 只透出**归因必需**的,不透权限快照(理由见 remember_event 注释)。
4698
4704
  "token_id": (r.get("meta") or {}).get("token_id"),
4699
4705
  "identity_role": (r.get("meta") or {}).get("identity_role"),
4700
- "parent": (r.get("meta") or {}).get("parent")}
4706
+ "parent": (r.get("meta") or {}).get("parent"),
4707
+ # 宪章第十五条:复读标注(只在命中时有键,未命中不占位)
4708
+ **(dict(repeat=r["repeat"]) if isinstance(r.get("repeat"), dict) else {})}
4701
4709
  for r in evs]
4702
4710
  except Exception: # noqa: BLE001
4703
4711
  pack["degraded"].append("recent")