@theseus-whale/dsh-continuity 0.0.0-stage → 4.12.2

package/docs/NEW-INSTANCE-HANDOFF.md

@@ -0,0 +1,219 @@
+# Continuity 4.11.36 — 新实例交接
+
+> 给下一个实例。你接手的是当前 session 的目录、规则和词表，不是另一个
+> session 的记忆。先读这份，再读当前 session 的 `rules.md` / `habits.md`。
+
+## 1. 版本与边界
+
+```text
+dsh-continuity 4.11.36
+安全模式：pointersOnly；peer 保留
+不包含：额外的提示词分类、自动标注或工作线注入。
+```
+
+它做：
+
+```text
+band 压缩 + [gist] 指针
+每个 session 自己的 B 索引
+每个 session 自己的 A/C/K
+每个 session 自己的 rules/habits
+recall(A/B/C/K + 字面)
+右侧面板 + peer_message
+```
+
+## 2. 每个 session 自己的全套
+
+```text
+~/.dsh/continuity/sessions/<sessionId>/
+  bc-index.jsonl
+  audit-state.json
+  expand-hint.jsonl
+  concepts.md
+  cmap.md
+  keywords.md
+  aliases.md
+  rules.md
+  habits.md
+  rebuild.md
+```
+
+新 session：
+
+```text
+A/C/K = 空
+rules.md   <- 插件 templates/rules.md
+habits.md  <- 插件 templates/habits.md
+```
+
+不继承另一个 session 的 A/C/K 或 rules/habits。
+
+persona 只是身份/启用开关：
+
+```text
+session-persona.json:
+  <sessionId> -> continuity | <pid>
+  default -> continuity
+
+personas/<pid>/persona.json:
+  {"enabled": true}
+```
+
+`continuity` 没文件也默认启用；disabled persona 会被 pre-step 跳过，面板
+返回 `persona-disabled`。
+
+## 3. 当前文件
+
+```text
+sessions/<id>/bc-index.jsonl
+sessions/<id>/audit-state.json
+sessions/<id>/expand-hint.jsonl
+sessions/<id>/concepts.md
+sessions/<id>/cmap.md
+sessions/<id>/keywords.md
+sessions/<id>/aliases.md
+sessions/<id>/rules.md
+sessions/<id>/habits.md
+sessions/<id>/dropped-ranges.json
+
+~/.dsh/continuity/
+  session-persona.json
+  personas/<pid>/persona.json
+  folds.json
+  passes.jsonl
+  context-log.jsonl
+```
+
+## 4. 检索
+
+```text
+recall()
+recall({ query: "跑团", recent: true })
+recall({ query: "A标签" })           // 当前 session 的 topic
+recall({ query: "A标签:workflow" })  // 当前 session 的 workflow
+recall({ query: "A标签:跑团叙事" })   // 任意 A 概念
+recall({ query: "B标签" })
+recall({ query: "C标签" })
+recall({ query: "K标签" })
+```
+
+- 索引和 A/C/K 只读当前 session。
+- `via`：`A | B | C | K | live`。
+- 候选不是事实，必须打开 turn/seq。
+
+## 5. 注入前缀
+
+```text
+[continuity:boot]    引导
+[continuity:audit]   审计
+[continuity:fold]    折叠回执
+```
+
+`[追忆]` 是 recall 的 tool result，不是 user 通道注入。
+
+## 6. 压缩与回执
+
+```text
+high 0.60W 触发
+low 0.40W 目标
+protect 0.30W
+一次 pass 折一个最老连续区
+budget 是上限，不是必然排干
+```
+
+可达下限：
+
+```text
+floor(T) = (protect * W + baseline(T)) / W
+```
+
+baseline 会变；当前值看最新 `context-log.jsonl`，历史 pass 用
+`passes.jsonl` 的 `afterBaselineTokens`。不要把 52.7% 当固定值。
+
+## 7. 标签版本
+
+```text
+v2（新轮）:
+  genericTopic / topicScore / topicConfidence / genericWorkflow
+  labelVersion: 2
+  generic = topic ∪ workflow
+
+v1（旧轮）:
+  labelVersion: 1
+  无 topicScore，不伪造
+```
+
+`topicConfidence` 的 0.4/0.5 只是展示标签，不是写入阈值。
+
+## 8. 启动自检
+
+```text
+1. 当前 session 的 persona enabled
+2. sessions/<id>/bc-index.jsonl 存在
+3. bc.json?sessionId=<id> 返回 available
+4. A标签 -> 当前 session 自己的 topic
+5. C/K 查询只命中当前 session 自己的表
+6. 另一 session 的目录不被本 session 修改
+7. 没有新增 gate-errors
+```
+
+## 9. 规则层级
+
+```text
+AGENTS.md        用户所有；实例不改
+sessions/<id>/rules.md    当前 session 硬规则；可改
+sessions/<id>/habits.md   当前 session 软偏好；可改
+sessions/<id>/concepts.md|cmap.md|keywords.md|aliases.md  当前 session 数据
+```
+
+`rules.md` 只能规定当前 session 的这些文件；不能授权改插件或别的 session。
+
+## 10. 保护
+
+```text
+不改 live profile 的 dsh-continuity 安装目录
+不改 cordis.patch.yml / package.json / lockfile / tgz
+```
+
+插件变更只能走：
+
+```text
+独立副本 -> 测试 -> 备份 -> 替换 -> 重启 -> 验证
+```
+
+工具层有 best-effort 路径守卫：session 只能碰自己的 `sessions/<id>/`。
+它不是 OS 安全边界；强隔离需要 ACL/容器。
+
+## 11. 常见故障
+
+```text
+没有 tab
+-> personas/<pid>/persona.json 是否 enabled
+-> bc.json 是否 persona-disabled
+
+A标签 是 0
+-> sessions/<id>/concepts.md 是否存在/为空
+-> 第 4 列 kind 是否存在
+
+recall 空
+-> sessions/<id>/bc-index.jsonl 是否存在
+-> C/K 是否在当前 session 目录
+
+rules 没更新
+-> 是否改的是当前 session 的 rules.md，而不是旧的全局文件
+
+另一 session 被改
+-> 工具层守卫只能挡常规工具；检查 ACL
+```
+
+## 12. 原则
+
+```text
+每个 session 自己的全套。
+候选不是事实。
+[gist] 不是原文。
+A 默认只看 topic。
+pass 回执 append-only。
+可达下限由 protect + baseline 现算。
+工具守卫不是 OS 安全边界。
+```

package/docs/README.md

@@ -0,0 +1,37 @@
+# 文档索引
+
+现行文档：
+
+```text
+SESSION-LAYOUT.md          权威路径、角色、权限（中文）
+ARCHITECTURE.md            当前架构（英文技术附录）
+NEW-INSTANCE-HANDOFF.md    新实例交接（英文技术附录）
+```
+
+经典说明书在包根/`guides/`：
+
+```text
+00-READ-FIRST.md
+01-INSTALL.md
+02-TABLES.md
+03-AUDIT.md
+04-REBUILD.md
+05-FIRST-RUN.md
+```
+
+历史/设计档案（保留来源；路径和行为可能属于旧版本）：
+
+```text
+API-NOTES.md
+CACHE.md
+CONDUCT.md
+CREATOR-HANDOFF.md
+EXPERIMENT.md
+FACET-MVP-REPORT.md
+GUIDE-0.4.66.md
+GUIDE.md
+MECHANISM.md
+```
+
+现行行为以 `SESSION-LAYOUT.md` 和 `ARCHITECTURE.md` 为准。  
+历史文件不是操作说明。

package/docs/SESSION-LAYOUT.md

@@ -0,0 +1,151 @@
+# Session 布局与权限 — 4.9.102
+
+这是本包路径/权限的权威文档。若其他文档与它冲突，以本文为准。
+
+## 1. 一个 session，一套完整记忆
+
+```text
+~/.dsh/continuity/sessions/<sessionId>/
+  bc-index.jsonl          B 指针索引，只属于这个 session
+  bc-index-state.json     索引游标
+  audit-state.json        审计游标
+  expand-hint.jsonl       待注入审计提示
+  concepts.md             A: 名字 | 描述词 | 覆盖 | kind
+  cmap.md                 C: 用户词 -> 概念
+  keywords.md             K: 精确名
+  aliases.md              别名
+  rules.md                硬规则，从 templates/rules.md 起
+  habits.md               软偏好，从 templates/habits.md 起
+  rebuild.md              本地重建说明
+  turns.jsonl             可选，relabel 用
+  dropped-ranges.json     本 session 的合并覆盖（只属于本 session）
+```
+
+以上全部是 session-local。任何 session 都不读另一个 session 的 A/C/K、
+rules、habits、index、审计、提示或 dropped-ranges。
+
+新 session：
+
+```text
+A/C/K 空
+rules.md   <- templates/rules.md
+habits.md  <- templates/habits.md
+rebuild.md <- 空壳
+index      <- 第一次 pre-step
+```
+
+## 2. 共享文件
+
+```text
+~/.dsh/continuity/
+  session-persona.json       sessionId -> 身份
+  personas/<pid>/persona.json {"enabled": true|false}
+  folds.json                 全局折叠历史
+  passes.jsonl               全局 pass 回执
+  context-log.jsonl          上下文测量
+  handoff-pending.json       交接标记
+```
+
+`session-persona.json` 只解析身份，不选择词表路径。  
+`persona.json` 只是启用开关。
+
+`personas/<pid>/concepts.md|cmap.md|keywords.md|aliases.md` 是**弃用归档**，
+不是读取路径。
+
+## 3. 权限
+
+### 内部引擎
+
+continuity preset 挂载的引擎可以读写：
+
+```text
+自己的 session 目录（含 dropped-ranges.json）
+folds.json / passes.jsonl / context-log.jsonl
+```
+
+这是宿主代码，不是模型工具。
+
+### 模型工具
+
+普通工具调用可以碰：
+
+```text
+workspace 文件
+自己的 sessions/<sessionId>/ 目录
+```
+
+不能碰：
+
+```text
+另一个 session 的 sessions/<other>/
+personas/
+session-persona.json
+folds.json / passes.jsonl
+continuity 根目录的 rules.md / habits.md
+```
+
+守卫在 `src/session-guard.mjs`。它只检查带路径的参数，不扫描完整消息/文件
+正文；`send_message`、`peer_message`、`present` 不受影响。
+
+守卫是 **best effort**，不是 OS ACL。任意有完整文件权限的代码可以绕过；
+强隔离需要 OS ACL/容器。
+
+### 禁用的 persona
+
+禁用的 persona：
+
+```text
+面板：persona-disabled
+pre-step：跳过
+普通 workspace 工具：仍可用
+continuity 路径：拒绝
+```
+
+## 4. Preset
+
+| session | 自己的一套 | 原生工具 |
+|---|---|---|
+| continuity preset | A/B/C/K/rules/habits/index | `recall`、`session_log`、band 引擎 |
+| standard preset | A/B/C/K/rules/habits/index | 没有原生 recall/session_log；原生 compaction-basic 80% |
+| 禁用 persona | 不启用 | 只有 workspace 工具 |
+
+standard session 仍有面板和自己的文件，但没有 continuity band 引擎和原生
+recall/session_log。
+
+preset 在第一个 turn 后固定。`agentPresets.select` 对已启动 session 返回
+`agent-preset/locked`。改 session header 不是受支持的迁移路径。
+
+## 5. 不变量
+
+```text
+一个 session 拥有完整一套。
+不继承词表/规则/习惯。
+任何 session 不得修改另一个 session 的 continuity 文件。
+`personas/` 已弃用。
+全局 folds/passes 归引擎，不由模型编辑。
+候选不是事实；必须打开 turn/seq。
+[gist] 是重建，不是原文。
+```
+
+## 维护者访问（operator）
+
+默认没有跨 session 访问。需要人工维护另一个 session 时，在
+`~/.dsh/continuity/operator-sessions.json` 写一个显式 session id 数组：
+
+```json
+["session-..."]
+```
+
+`session-guard` 只对这份清单里的 session 放行；清单为空或不存在时，仍按
+persona + 本 session 的规则拦截。这个文件是维护入口，不是日常权限。
+## 根级身份/诊断文件
+
+`read` 工具可以读取这三个根级文件（只读）：
+
+```text
+~/.dsh/continuity/session-persona.json
+~/.dsh/continuity/operator-sessions.json
+~/.dsh/continuity/context-log.jsonl
+```
+
+写入仍被拦；shell 命令里的路径也仍被拦。用 `read`，不要用 `Get-Content`。

package/docs/history-map.md

@@ -0,0 +1,249 @@
+# History map 的既定行为
+
+> 2026-11-06。适用于 `dsh-continuity` 的 active history-map。
+>
+> 这不是“可调度摘要”：它必须自动进 surface。否则它跟一份文件没有区别。
+
+## 1. 位置
+
+```text
+system/message
+[continuity:history-map]     ← system 之后第一条
+...
+retained original tail
+```
+
+`ensureHistoryMap` 用：
+
+```text
+surfaceOp: { op:'replace', startSeq, endSeq }
+sourceEventSeqs: [...]       // 顶层字段，不在 surfaceOp 里
+```
+
+把最前面的一段替换成 map。
+
+不是 append 到尾部。  
+append 只能加在末尾，不能构成“摘要 + 原文”的顺序。
+
+## 2. 刷新条件
+
+```text
+hash 不变 + carrier 在 surface  -> 不动
+hash 变（新 fold / excerpt 规则变）-> replace front 单节点刷新
+carrier 不在 surface（被折叠/清除）-> 重新注入
+```
+
+`history-map-probe.json` 每次 `ensureHistoryMap` 写一次，字段：
+
+```text
+at / sessionId / nodeCount / frontSeq / frontIsCarrier
+mapPath / mapPathExists / indexRecords / builtChars
+range / reason / error / carrierSeq
+startSeq / endSeq / seqCount / seqFirst / seqLast
+```
+
+常见 `reason`：
+
+```text
+returned-front-carrier     front 已是 map，hash 未变
+updated-front-carrier      front 已是 map，hash 变了并刷新
+returned-no-index          summaries/index.json 不存在
+returned-no-range          找不到可替换区间（兜底应只换 front）
+returned-dedup             进程内 bootstrap 记录命中（仅同进程热路径，非持久状态）
+ok                         首次 front replace 成功
+error                      读 index / build / replace 抛错
+```
+
+`returned-dedup` 不能当作“已注入”的持久证据：进程重启后 Map 清空，它会重新走 front replace。
+
+### 模式
+
+```text
+~/.dsh/continuity/history-map-mode
+  off       完全不动作（默认）
+  observe   只写 probe，不注入 / 不 replace / 不 stub
+  auto      注入 + 自刷新（实验档）
+```
+
+默认 `off`：native checkpoint 是唯一小抄，fold 必写，位置由 native 保证。  
+history-map 不再作为默认中间层；`auto` 只保留为实验档。
+
+`auto` 下 front 已是 `compact-checkpoint` 时 no-op，不再用 map 替换 native summary。  
+`observe` 下 `oldestRange` 不跳过 map，便于观察 native fold 是否把旧 map 折入。
+
+## 3. 显隐
+
+```text
+surface 上：1 条 active map + 若干 map-stub
+raw 里：历史 map / stub 事件都保留
+```
+
+`map-stub` 用独立 marker：
+
+```text
+[continuity:map-stub] (superseded)
+```
+
+原因：stub 也以 `[continuity:history-map]` 开头的话，会被 `findHistoryMapCarriers` 当成 carrier，
+导致每轮都误判 extras、重复注入。
+
+stub 的 replace 也必须带顶层：
+
+```text
+sourceEventSeqs: [seq]
+```
+
+## 4. cap 取舍
+
+顺序：
+
+```text
+位置
+-> 最新区间（新 -> 旧）
+-> 上次索引之后的 fold
+-> 长期结构
+-> 取原文
+```
+
+规则：
+
+```text
+单个区间 excerpt 上限：6,000 字（总 cap 内的分配，不是每段都保证 6,000）
+同一区间多条 record：toSeq 降序，再按正文长度降序；最多取 2 条并均分 excerpt
+超 cap：先丢最老区间，保最新区间
+长期结构最后才丢
+```
+
+当前 0b 实测：
+
+```text
+总长 12,587 字 ≈ 3,147 tokens（cap 4k）
+最近区间 83294-84075 6,012 字
+80911-81009 被 cap 丢掉（预期）
+```
+
+## 5. 信息边界
+
+```text
+map 是索引，不是原文。
+细节以 raw / session_log 为准。
+```
+
+`front replace` 会真的从 **surface** 移除旧文本。  
+raw 仍在 session log；这不是删除原文。
+
+既定代价：
+
+```text
+surface 上的摘要可能比 raw 短；
+map 替换 native checkpoint 后，surface 不再有那份 checkpoint 原文；
+需要原文时按 seq 回 session_log 取。
+```
+
+不要因为“surface 摘要比 raw 短”把它当成新 bug。
+
+## 6. bootstrap replace 与 archive
+
+成功 front replace 后，engine 写：
+
+```text
+sessions/<id>/summaries/bootstrap-ranges.json
+```
+
+summary-index 构建时读取这个侧车，把 bootstrap replace 的区间并入 coverage，
+避免重建 index 时把这段误判成 pending window。
+
+可核对的分叉信号：
+
+```text
+pendingWindows 变大 = 分叉开始
+现在 pending 仍 0，所以尚未分叉
+```
+
+两个语义边界：
+
+```text
+1 boot 段是 covered-without-summary
+   并入 coverage 后 pendingWindows 会被结构性压到 0，
+   即使那段没有可读摘要文本。
+   pending 0 不等于“都有摘要”，只等于“有 surface 替代”。
+
+2 boot 段没有 release 语义
+   如果 front map 被折叠/删除，sidecar 记录仍在，coverage 仍宣称覆盖。
+   记录带 carrierSeq，但当前扫描不校验 carrier 是否还存在。
+   以后要加：carrier 不在 surface 时把该段标 stale，不并入 coverage。
+```
+
+侧车形状：
+
+```text
+{ version:1, ranges:[{ fromSeq, toSeq, tokens, carrierSeq, at }] }
+```
+
+## 7. pending window 生成器
+
+当 `pendingWindows > 0`，可以显式生成抽取式 window summary：
+
+```bash
+node bin/summary-index.mjs --raw <session.v4.jsonl.zstd> --session-dir <dir> \
+  --extract-pending --apply
+```
+
+行为：
+
+```text
+1 先建 base index，列出 pending
+2 对每个 pending 生成 300-800 tokens 的抽取式摘要
+3 写 summaries/windows/<from>-<to>.json
+4 用 windowRanges + windowRecords 重建 index
+   pending 归零；window 以 kind:'window-extractive'、quality:'extractive' 进入 records
+```
+
+抽取式内容是 fallback，不是 LLM 摘要；结构保留用户/助手/工具和 raw seq 指针。
+
+过滤掉的注入前缀：
+
+```text
+[continuity:* / 追忆 / 抽取 / 工作线 / 标签 / 规则 / 规矩 / 习惯 / 技能 / 归位 / 候选 / 存? / 闸 / 回正 / 学习 / 记忆 / 创 / peer]
+<system-reminder>
+Current runtime context
+Time sampled while preparing
+```
+
+2026-11-06 live 0b 第一次 apply 混入 `[规则]`（实际是 peer `[创]` 正文引用），已回滚；
+最终版本把 peer 保留为独立角色：
+
+```text
+window-84076-88063
+kind window-extractive / quality extractive
+2,205 字 / 552 tokens
+## 用户   只留真实用户
+## 同伴   [创] 内容，标 (peer) seq ...
+## 助手   只抽有正文的 assistant/message
+standalone [规则] line = false
+records 159 / pending 0 / windows 1
+map preview 87FDA63E / 11,772 字 / 2,943 tokens
+backup: backups/summary-index-window-20261106/index.json.before-assistant-sampling
+```
+
+peer 内容不再过滤，也不会被归进「用户」。  
+assistant 采样只收 `textOf(event)` 非空的节点，避免 479 条里只抽到空段。
+
+## 8. 已知未完成
+
+```text
+1 window 生成器目前是抽取式 fallback，不是 LLM 摘要
+2 band / protect 未改；protect 仍是 0.20
+```
+
+snapshot/summary 事件已按 `session.seq` 增量缓存；首轮全量，后续只读新增 seq。
+
+## 9. 修改前检查
+
+```text
+1 sourceEventSeqs 必须在 append options 顶层
+2 replace 端点用 surface 顺序，不要 min/max 归一化
+3 stub 必须带顶层 sourceEventSeqs
+4 cap 顺序不能反过来
+5 改完先看 history-map-probe.json 的 reason
+```