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

package/guides/01-INSTALL.md

@@ -0,0 +1,207 @@
+# 01 — 安装
+
+## 1. 先理解“安装”到底装了什么
+
+这个包不是装完就自动有一份完整记忆。
+
+它装进去的是三层东西：
+
+```text
+宿主行：提供面板、路由、按 session 调度
+preset：提供压缩引擎、recall、session_log
+client：提供左侧“连续性”面板和右侧 A/B/C/K tab
+```
+
+三者缺一个，你看到的现象都不一样。
+
+**比如这种情况：**
+
+```text
+如果宿主行装了，但 client 没加载，
+则后台在写索引，你却看不到“连续性”入口。
+```
+
+```text
+如果 client 在，但 preset 不是 continuity，
+则面板可能有，但没有 band 引擎和原生 recall/session_log。
+```
+
+所以先不要用“有没有表”判断安装成功。
+
+## 2. 安装
+
+把 tgz 装进目标 DSH profile，备份 `~/.dsh/continuity`，然后重启 DSH。
+
+```text
+dsh-continuity-4.11.36.tgz
+```
+
+为什么必须重启？
+
+因为插件在 DSH 启动时挂载。  
+只把 tgz 放进目录、不重启，等于把书放上书架但没翻开。
+
+**比如这种情况：**
+
+```text
+如果装完没有重启，
+则新代码没进进程，面板可能还是旧版本，或者根本没有。
+```
+
+重启后确认版本：
+
+```text
+dsh-continuity 4.11.36
+```
+
+## 3. 第一次 pre-step 会做什么
+
+某个 session 第一次经过 pre-step 时，它会：
+
+```text
+1. 解析当前 session id
+2. 检查 persona 是否启用
+3. 创建缺失的 session 空壳：
+   concepts.md
+   cmap.md
+   keywords.md
+   aliases.md
+   rebuild.md
+4. 从 templates/rules.md 种 rules.md
+5. 从 templates/habits.md 种 habits.md
+6. 第一次索引时创建 bc-index.jsonl
+```
+
+它只创建缺失文件，不覆盖已有表。
+
+**比如这种情况：**
+
+```text
+如果 concepts.md 已经存在，
+则它不会用模板覆盖，哪怕模板更新了。
+```
+
+这就是为什么“升级插件”不等于“旧 session 的规则会自动变新”。
+
+## 4. 新 session 为什么是空表
+
+新 session 的：
+
+```text
+A 空
+C 空
+K 空
+```
+
+这是正常的。
+
+A 空会进一步导致：
+
+```text
+B 空
+审计跳过
+```
+
+**比如这种情况：**
+
+```text
+如果新 session 刚聊 3 轮，A 表空、B 空，
+则不是插件没工作，而是还没有人给 A 写第一条。
+```
+
+如果你希望它一开始就有概念，需要显式：
+
+```text
+写 concepts.md
+或从历史 rebuild
+```
+
+不要从别的 session 复制 A 表。
+
+## 5. 有历史、但没有表怎么办
+
+如果 session 已经聊了很长，A/B/C/K 还是空：
+
+```text
+不要从当前 live turn 开始补
+```
+
+先读 `04-REBUILD.md`。
+
+**比如这种情况：**
+
+```text
+如果 session 已经有 500 轮，A 仍然是空，
+则从第 501 轮开始正常聊，也不会自动补出前 500 轮的 B。
+```
+
+历史需要显式重建。
+
+## 6. preset 检查
+
+```text
+continuity preset：
+  band 引擎
+  原生 recall
+  原生 session_log
+
+standard preset：
+  原生 compaction-basic 80%
+  没有 band 引擎
+  没有原生 recall/session_log
+```
+
+已启动的 session 不能切 preset。  
+`agentPresets.select()` 会返回：
+
+```text
+agent-preset/locked
+```
+
+**比如这种情况：**
+
+```text
+如果为了“省事”去改 session header 的 agentPreset，
+则 session 可能从列表里消失，而不是升级成 continuity。
+```
+
+不要改 header。要换 preset，新建 session。
+
+## 7. 重启后的自检
+
+按顺序看：
+
+```text
+1. 版本 = 4.11.36
+2. 左侧有“连续性”
+3. 右侧“更多工具”下有 A/B/C/K
+4. sessions/<id>/ 有基础文件
+5. rules.md / habits.md 在 session 目录
+6. 面板能打开
+7. 没有新的 gate-errors
+```
+
+如果第 2 条没有，先不要查表，查 client。
+
+如果第 2 条有、第 3 条没有，查宿主是否支持 `sidebarRight`。
+
+如果第 3 条有、表是空的，回到第 4 节：这是正常的空表。
+
+## 8. 一个最小验收
+
+对新 session：
+
+```text
+发一句话
+等一次 pre-step
+打开 A/B/C/K
+确认 B 覆盖当前 turn
+```
+
+如果 B 仍然是空：
+
+```text
+检查 A 表有没有内容
+```
+
+因为没有 A，就没有 B。

package/guides/02-TABLES.md

@@ -0,0 +1,225 @@
+# 02 — A / B / C / K
+
+这四张表不是四个同义词。它们回答的是四个不同问题：
+
+```text
+A：这个话题叫什么？
+B：这一轮大概属于哪些 A？
+C：用户说这个词时，指的是哪个 A？
+K：这个精确名字是什么，不能被拆？
+```
+
+理解这个区别，比记住文件格式重要。
+
+## 1. A — 概念表
+
+文件：
+
+```text
+sessions/<sessionId>/concepts.md
+```
+
+格式：
+
+```text
+名字 | 描述词 | 参考覆盖 | kind
+```
+
+例子：
+
+```text
+示例主题 | 项目、讨论、决定 | 12 | topic
+复盘流程 | 复盘、检查、收尾 | 5 | workflow
+```
+
+A 的作用不是“直接回答问题”。
+
+它的作用是：
+
+```text
+给 B 提供候选概念
+给 C 提供映射目标
+给审计提供 topicMax
+给面板提供展示
+```
+
+**比如这种情况：**
+
+```text
+如果 A 为空，
+则 B labeler 没有候选，B 一定为空。
+```
+
+这不是 B 坏了，是 B 的上游没有概念。
+
+### kind
+
+```text
+topic     一个话题/领域
+workflow  一个流程/做法
+```
+
+不确定时写 `topic`。
+
+不要为了凑数把“人名、道具、英文标识”塞进 A；那些通常属于 K。
+
+## 2. B — 每轮标签
+
+B 不在单独的文件里。它写在：
+
+```text
+sessions/<sessionId>/bc-index.jsonl
+```
+
+每轮记录里可能有：
+
+```text
+genericTopic
+genericWorkflow
+topicScore
+topicConfidence
+conceptScores
+labelVersion
+```
+
+B 是“这一轮大概像哪个 A”，不是“这一轮就是那个话题”。
+
+**比如这种情况：**
+
+```text
+如果一轮同时在聊 A 和 B 两个话题，
+则 B 可能只取分数最高的那个，另一个留在 conceptScores 里。
+```
+
+所以 B 不是事实，只是标签。
+
+`weak` 也不等于“这轮没内容”，只表示标签置信度低。
+
+## 3. C — 用户词
+
+文件：
+
+```text
+sessions/<sessionId>/cmap.md
+```
+
+格式：
+
+```text
+用户词 => B:概念 | K:关键词 | minB:1 | limit:20 | 摘要
+```
+
+C 解决的是：
+
+```text
+用户说“那个事”，到底指哪个 A？
+```
+
+例子：
+
+```text
+换箍 => B:示例主题 | minB:1 | limit:20
+```
+
+**比如这种情况：**
+
+```text
+如果用户一直说“换箍”，但 C 里没有这个映射，
+则 recall("换箍") 只能靠字面碰运气，不能稳定找到 A。
+```
+
+C 是桥，不是概念本身。
+
+## 4. K — 精确名
+
+文件：
+
+```text
+sessions/<sessionId>/keywords.md
+```
+
+一行一个名字。
+
+适合：
+
+```text
+项目名
+产品名
+人名
+代码标识符
+游戏名
+不能拆的专名
+```
+
+不适合：
+
+```text
+普通动词
+泛词
+“那个”“之前”
+```
+
+**比如这种情况：**
+
+```text
+如果把“昨天”写进 K，
+则每次出现“昨天”都可能被当成一个精确锚，反而噪声很大。
+```
+
+## 5. 别名
+
+文件：
+
+```text
+sessions/<sessionId>/aliases.md
+```
+
+只放跨语言/跨写法标识符：
+
+```text
+短信息 => sms
+```
+
+不要放同义词。同义词属于 C。
+
+## 6. 空表是合法的
+
+新 session：
+
+```text
+A 空
+C 空
+K 空
+B 空
+```
+
+这不是错误。
+
+**比如这种情况：**
+
+```text
+如果新 session 刚建立，A 空、B 空，
+则先聊，等有稳定话题再写 A；
+不要为了“看起来有东西”复制别人的表。
+```
+
+## 7. 加表之前先问三个问题
+
+```text
+1. 这个词是话题（A）、用户词（C）、还是精确名（K）？
+2. 它真的稳定出现吗，还是一次性说法？
+3. 加错之后能不能删掉/改回？
+```
+
+如果三个问题答不清，先不要加。
+
+## 8. 最小维护顺序
+
+```text
+先有稳定话题 -> 写 A
+再为常用说法 -> 写 C
+精确专名 -> 写 K
+最后才让 B 去用这些表打分
+```
+
+反过来做，通常会得到一堆看起来有表、但查不回来的数据。

package/guides/03-AUDIT.md

@@ -0,0 +1,201 @@
+# 03 — 自动审计
+
+## 1. 审计不是“自动整理记忆”
+
+它不是每隔 200 轮就把对话总结成一张新 A 表。
+
+它做的是：
+
+```text
+在当前 index 里找一些可能值得看的话题簇
+把它们作为候选提示交给你
+```
+
+写不写 A，仍然由这个 session 自己决定。
+
+**比如这种情况：**
+
+```text
+如果审计提示了一个候选，但实例直接忽略，
+则什么都不会改变，A 表不会自己长。
+```
+
+## 2. 为什么是 200 轮
+
+200 轮是一个折中：
+
+```text
+太短：话题还没稳定，候选全是噪声
+太长：发现得太晚，前面已经散掉
+```
+
+所以默认：
+
+```text
+每 200 轮最多触发一次
+```
+
+不是每轮都检查，也不是永不检查。
+
+**比如这种情况：**
+
+```text
+如果 session 只有 50 轮，
+则还没到第一次审计的阈值，不应该期待 [continuity:audit]。
+```
+
+## 3. 审计读什么
+
+它读的是已经存在的索引：
+
+```text
+bc-index.jsonl 的 vec
+bc-index.jsonl 的 chatter
+bc-index.jsonl 的 keywords
+bc-index.jsonl 的 conceptScores
+```
+
+它不重读全部原文。
+
+所以：
+
+```text
+如果旧记录没有 vec
+则审计可能无法正常做聚类
+```
+
+这也是为什么重建流程里有“补 vec”这一步。
+
+## 4. 候选怎么来的
+
+大致是：
+
+```text
+把带 vec 的记录做聚类
+簇大小至少 10
+算簇内最高概念分的平均值 topicMax
+topicMax < 0.5 才算候选
+按 topicMax 升序，最多 5 条
+```
+
+直觉：
+
+```text
+一个簇如果和已有 A 都不太像，
+它可能是“还没被命名的新话题”
+```
+
+**比如这种情况：**
+
+```text
+如果 A 表本身是空的，
+则没有概念可以算 topicMax，
+审计会直接跳过。
+```
+
+这就是 500 轮没有审计提示的常见原因。
+
+## 5. 审计结果放在哪
+
+```text
+sessions/<id>/expand-hint.jsonl       候选记录
+sessions/<id>/expand-hint.pending.json 下一轮要注入的文本
+sessions/<id>/audit-state.json         上次审计轮次/运行状态
+```
+
+下一轮 pre-step 会把 pending 注入成：
+
+```text
+[continuity:audit]
+```
+
+只有真的以 `role=user` 出现，才算送达。
+
+**比如这种情况：**
+
+```text
+如果 pending 写入了，但承载消息被折叠掉，
+则实例可能根本没看到这次审计。
+```
+
+## 6. 审计和 A 的关系
+
+顺序是：
+
+```text
+A 非空 -> 审计有东西可算 -> 可能产生候选
+A 空   -> 审计跳过
+```
+
+**比如这种情况：**
+
+```text
+如果 A 空，B 也空，审计也不来，
+则不是三个功能同时坏了；
+根因只有一个：A 没有建立。
+```
+
+## 7. 你看到审计时应该做什么
+
+先看：
+
+```text
+turn 范围
+size
+topicMax
+chatter
+kw
+```
+
+然后：
+
+```text
+多数叙事簇是噪声 -> 跳过
+确实是稳定话题 -> 才写一条 A
+不确定 -> 不写
+```
+
+不要因为“审计来了”就必须加表。
+
+## 8. 审计不替代 rebuild
+
+审计是增量提示。
+
+如果历史已经有 500 轮，A 还是空：
+
+```text
+审计不会替你补前 500 轮
+```
+
+这种情况应该走 `04-REBUILD.md`。
+
+**比如这种情况：**
+
+```text
+如果 500 轮都空着，只等下一次审计，
+则即使下一次审计来了，也只能看到最近的簇，
+前面的历史仍然没有 A/B。
+```
+
+## 9. vec 为空
+
+如果 A/B/C/K 有，但 vec 为空，审计同样跑不起来。
+见 `06-EMBEDDING.md`。
+
+## 10. fold 验收（K-04）
+
+折后瞬时值只是 provisional，不能用来验收。判据只用下一次正常 pre-step 的稳定值：
+
+```text
+稳定 est ≈ low×W (±3%)               → 达成
+稳定 est < low×W − 3%                → overshoot
+稳定 est > low×W + 3% 且 protectBinds → 保护咬合
+```
+
+`protectBinds` 用触发时的 `preBaseline` 算：
+
+```text
+floor = preBaseline + protect × W
+```
+
+实际减少量可以大于 `budget`，因为 budget 只按被折的 surface 计价，关联的 non-surface 前缀会一并被带走。