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

package/guides/04-REBUILD.md

@@ -0,0 +1,306 @@
+# 04 — 重建记忆宫殿（九步）
+
+## 先读这一段
+
+重建不是“点一下自动生成一套完美 A 表”。
+
+它是一次**有损的、需要判断的整理**：
+
+```text
+从已经存在的历史里
+导出文本
+重新打一遍标签
+再决定哪些东西值得变成 A
+```
+
+所以它有三条原则：
+
+```text
+先备份
+先 dry-run
+不覆盖已有表
+```
+
+**比如这种情况：**
+
+```text
+如果直接对 live index 跑 --write，
+而没有备份，
+则一次错误的 relabel 就可能把原来的 B 标签覆盖掉。
+```
+
+## 实战状态
+
+```text
+已验证：continuity preset 的 session，有真实历史
+未验证：standard preset 的 session
+```
+
+九步在 continuity preset 上跑通过。  
+standard preset 没有原生 recall/session_log，只有 80% 原生压缩；那条路仍算未验证。
+
+## 0. 对齐目标
+
+```text
+<sessionId> = 精确 session id
+<sessionDir> = ~/.dsh/continuity/sessions/<sessionId>/
+```
+
+只有 session 自己可以做重建。不要跨 session。
+
+**比如这种情况：**
+
+```text
+如果拿 0b 的 concepts.md 去给另一个 session 重建，
+则重建出来的不是那个 session 的记忆，只是 0b 的副本。
+```
+
+## 1. 数一遍并备份
+
+先回答：
+
+```text
+bc-index.jsonl 是否存在？
+多少行？
+maxTurn 是多少？
+session.v4.jsonl.zstd 是否还在？
+```
+
+然后把整个 `<sessionDir>` 复制到备份位置。
+
+为什么先数？
+
+因为后面每一步都要拿“行数/轮数”对照。没有基线，就无法判断有没有丢数据。
+
+**比如这种情况：**
+
+```text
+如果原 index 有 507 行，
+重建后只剩 490 行，
+但没有原行数做对照，
+则你可能以为只是“少了几个弱轮”，其实是丢了 17 轮。
+```
+
+## 2. 导出 turns
+
+```powershell
+python bin\export-turns.py `
+  --session-file 'C:\Users\...\session.v4.jsonl.zstd' `
+  --session-id '<sessionId>' `
+  --out '<sessionDir>\turns.jsonl'
+```
+
+它只导出真人 prompt：
+
+```text
+{ "turn": N, "text": "..." }
+```
+
+为什么不能直接拿 `bc-index.jsonl` 当 turns？
+
+因为 index 里只有指针和标签，没有完整用户文本。  
+relabel 需要原文才能重新算 B。
+
+**比如这种情况：**
+
+```text
+如果 turns 少了几个 turn，
+则 relabel 会报 missing turn text，
+或者悄悄只处理它能对上的部分。
+```
+
+## 3. 建/重标索引
+
+```powershell
+node bin\bc-relabel.mjs `
+  --index '<sessionDir>\bc-index.jsonl' `
+  --turns '<sessionDir>\turns.jsonl' `
+  --concepts '<sessionDir>\concepts.md' `
+  --out '<sessionDir>\bc-index.relabeled.jsonl'
+```
+
+先 dry-run。
+
+它做的是：
+
+```text
+读取旧 index
+读取 A 表
+用 A 给每一轮重新算 conceptScores / generic
+写到新文件
+不直接覆盖源文件
+```
+
+**比如这种情况：**
+
+```text
+如果 A 还是空的，
+则 relabel 会因为没有概念而无法产生有意义的 B。
+```
+
+所以第 3 步之前，至少要先有一个能用的 A 表；  
+如果没有，就先做第 6 步的种 A，再回来 relabel。
+
+## 4. 补 vec + chatter
+
+```powershell
+node bin\bc-relabel.mjs --vectors `
+  --index '<sessionDir>\bc-index.jsonl' `
+  --turns '<sessionDir>\turns.jsonl' `
+  --out '<sessionDir>\bc-index.vec.jsonl' --write
+```
+
+新记录通常已经有 `vec`/`chatter`。  
+这一步是给旧记录补。
+
+为什么审计需要 vec？
+
+因为审计要用向量聚类。  
+没有 vec，就只剩关键词，候选会很粗。
+
+**比如这种情况：**
+
+```text
+如果旧记录没有 vec，
+则审计可能跳过，或者聚类结果完全不可用。
+```
+
+## 5. 种 K
+
+```text
+只收专名：
+  出现 >= 2–3 次
+  能按名字直接定位
+  不是普通动词/泛词
+```
+
+写进：
+
+```text
+sessions/<id>/keywords.md
+```
+
+一行一个。
+
+**比如这种情况：**
+
+```text
+如果把“昨天”写进 K，
+则每次出现“昨天”都可能被当成精确锚，噪声会变大。
+```
+
+## 6. 种 A
+
+这是重建里最需要判断的一步。
+
+大致规则：
+
+```text
+k = clamp(round(N/50), 20, 60)
+簇大小 >= 10
+topicMax < 0.5
+名字是话题词，不是人名/道具/英文标识
+每次最多 +2；总数约 0.6*N
+两条覆盖 Jaccard > 0.6 就合并
+```
+
+写入：
+
+```text
+名字 | 描述词 | 参考覆盖 | kind
+kind = topic | workflow
+```
+
+为什么要限制数量？
+
+因为 A 不是越多越好。  
+太多、太碎，B 标签会变得没有区分度；  
+太少、太宽，B 又会把所有轮都归到同一个概念。
+
+**比如这种情况：**
+
+```text
+如果 A 只有“工作”和“生活”两个概念，
+则 B 几乎每轮都会落在这两个上，等于没有标签。
+```
+
+```text
+如果 A 有 200 个近义概念，
+则同一轮可能被拆到很多小标签里，也失去区分度。
+```
+
+## 7. 种 C + 别名
+
+```text
+cmap.md:
+  用户词 => B:概念 | K:关键词 | minB:1 | limit:20 | 摘要
+
+aliases.md:
+  只放跨语言标识符
+```
+
+为什么 C 不是 A？
+
+A 是“话题叫什么”，C 是“用户怎么称呼它”。
+
+**比如这种情况：**
+
+```text
+如果用户一直说“换箍”，
+而 A 里叫“示例主题”，
+则没有 C 的桥接，recall("换箍") 很难稳定命中。
+```
+
+## 8. 用新 A 重标一次
+
+重复第 3 步。
+
+为什么？
+
+因为第 3 步可能是在 A 还不完整时跑的。  
+新 A 建好后，历史轮需要重新用新 A 打分。
+
+**比如这种情况：**
+
+```text
+如果 A 加完了但不重标，
+则历史轮的 B 仍然是用旧 A / 空 A 算出来的。
+```
+
+## 9. 验收与审计
+
+```text
+index 行数覆盖预期轮次
+前几轮 A > 0，B > 0
+recall("A标签") 只显示本 session 的概念
+C/K 只命中本 session 的文件
+没有新的 gate-errors
+其他 session 没有被改
+```
+
+**比如这种情况：**
+
+```text
+如果 index 行数对，但 B 全是 weak，
+则可能 A 太宽，或者 relabel 用的 concepts.md 不是最新的。
+```
+
+## 失败规则
+
+```text
+没有备份就不覆盖
+不写别的 session 的文件
+不用改 header 来切 preset
+验证失败就恢复并停止
+```
+
+重建不是“跑完就算成功”。
+
+真正的成功是：
+
+```text
+数据对得上
+B 有区分度
+原文还能打开
+没有污染别的 session
+```

package/guides/05-FIRST-RUN.md

@@ -0,0 +1,191 @@
+# 05 — 第一次运行
+
+## 1. 先确认这是一个新 session
+
+新 session 应该是：
+
+```text
+没有本地 bc-index.jsonl
+A/C/K 空
+```
+
+为什么强调这个？
+
+因为很多人会把“新 session 空表”误认为“插件没工作”。
+
+**比如这种情况：**
+
+```text
+如果 session 是新的，A 空、B 空，
+则这是正确起点，不是故障。
+```
+
+## 2. 安装并重启
+
+安装 tgz，重启 DSH，确认版本。
+
+```text
+dsh-continuity-4.11.36.tgz
+```
+
+**比如这种情况：**
+
+```text
+如果只复制了文件没有重启，
+则版本号和面板都可能是旧的。
+```
+
+## 3. 第一次启动应该看到什么
+
+```text
+sessions/<id>/ 出现基础文件
+rules.md / habits.md 来自 templates/
+第一次 pre-step 后出现 bc-index.jsonl
+左侧“连续性”出现
+右侧“更多工具”出现 A/B/C/K
+```
+
+如果左侧没有“连续性”：
+
+```text
+不是表空，是 client 没加载。
+```
+
+如果右侧没有 A/B/C/K：
+
+```text
+不是表空，是宿主缺少 sidebarRight 或 tab 注册失败。
+```
+
+如果 tab 打开是空表：
+
+```text
+正常，继续往下看。
+```
+
+## 4. 空表阶段
+
+```text
+A 空 -> B 空
+C 空 -> 没有 C 命中
+K 空 -> 没有 K 命中
+```
+
+这不是“什么都没发生”。  
+索引已经在积累，只是还没有概念。
+
+**比如这种情况：**
+
+```text
+如果 A 一直是空，
+则 B 也一直是空，
+即使已经聊了 500 轮。
+```
+
+因为 B 不是从对话自动生成，而是用 A 给对话打分。
+
+## 5. 前 200 轮做什么
+
+```text
+正常聊天
+需要回忆时用 recall(query)
+重要结论写进本 session 的 files 或工作区 log
+```
+
+不要做的：
+
+```text
+不要等系统自动生成 A
+不要复制别的 session 的 A
+不要为了“有表”而编概念
+```
+
+**比如这种情况：**
+
+```text
+如果前 200 轮一直在聊，但 A 从未写，
+则第一次审计也可能因为没有 A 而跳过。
+```
+
+这是当前设计的一个坑，4.9.112 起 rules 已明确要求维护 A，但已有 session 不会自动改 rules。
+
+## 6. 第一次写 A
+
+当聊天里出现一个稳定、反复出现的话题：
+
+```text
+在 sessions/<id>/concepts.md 追加一行：
+名字 | 描述词 | 参考覆盖 | kind
+```
+
+例子：
+
+```text
+示例主题 | 项目、决定、复盘 | 5 | topic
+```
+
+不需要一次写很多。  
+先写一条，观察 B 是否开始有区分度。
+
+**比如这种情况：**
+
+```text
+如果 A 只有一条“工作”，
+则 B 会把很多不同话题都打成“工作”，
+看起来有标签，其实没有区分。
+```
+
+## 7. 第一次审计
+
+到 200 轮左右，可能出现：
+
+```text
+[continuity:audit]
+```
+
+但它不是必然出现：
+
+```text
+A 空 -> 跳过
+没有 vec -> 可能跳过
+没有明显未决簇 -> 没有候选
+```
+
+**比如这种情况：**
+
+```text
+如果 200 轮到了但没有审计，
+不要立刻认为审计坏了；
+先看 A 是否为空、index 是否有 vec。
+```
+
+## 8. 第一次重建
+
+如果 session 已经有很长的历史，但 A/B/C/K 一直空：
+
+```text
+不要从当前轮开始补
+直接读 04-REBUILD.md
+```
+
+**比如这种情况：**
+
+```text
+如果已经聊了 507 轮，A 还是空，
+则从第 508 轮开始写 A，只能覆盖以后，
+前 507 轮仍然没有 B。
+```
+
+需要 rebuild + relabel 历史。
+
+## 9. 验收
+
+```text
+A/B/C/K 文件存在且只属于本 session
+recall 使用本 session 的索引
+B 对至少部分轮次有标签
+没有改到别的 session
+没有新的 gate-errors
+```
+
+如果这些都对，第一次运行才算完成。

package/guides/06-EMBEDDING.md

@@ -0,0 +1,146 @@
+# 06 — vec / embedding 没跑起来
+
+## 1. 症状
+
+```text
+A/B/C/K 有内容
+面板正常
+但审计不来
+bc-index.jsonl 里 vec 为空
+```
+
+这不是 A 表的问题。  
+这是**索引里的向量没有生成**。
+
+## 2. vec 是干什么的
+
+B 的标签可以用概念词算，但审计要做聚类：
+
+```text
+把很多轮按语义放进不同的簇
+看哪个簇和现有 A 都不太像
+```
+
+聚类需要：
+
+```text
+bc-index.jsonl 的 vec
+```
+
+**比如这种情况：**
+
+```text
+如果 vec 为空，
+则审计没有可聚类的点，
+会报 "audit needs vec on at least 90% of records"。
+```
+
+## 3. 为什么 pnpm 会跳过
+
+本地 embedding 用：
+
+```text
+@huggingface/transformers
+onnxruntime-node
+```
+
+pnpm 默认可能不执行依赖的 install/postinstall 脚本。
+
+**比如这种情况：**
+
+```text
+如果 pnpm 跳过了 onnxruntime-node 的构建，
+则 transformers 加载模型时会失败，
+新记录的 vec 就会是空。
+```
+
+## 4. 先自检
+
+在安装目录运行：
+
+```powershell
+cd <dsh-continuity 安装目录>
+node bin\vec-check.mjs
+```
+
+成功应该看到：
+
+```text
+{ "ok": true, "dimensions": 512, ... }
+```
+
+失败会输出类似：
+
+```text
+embedding runtime unavailable ...
+```
+
+## 5. 修复 pnpm 的 build 跳过
+
+在 DSH profile 目录（不是工作区）执行：
+
+```powershell
+pnpm approve-builds
+```
+
+在列表里允许：
+
+```text
+onnxruntime-node
+sharp
+```
+
+然后：
+
+```powershell
+pnpm rebuild onnxruntime-node sharp
+```
+
+再跑一次：
+
+```powershell
+node bin\vec-check.mjs
+```
+
+如果 `ok: true`，embedding 恢复了。
+
+## 6. 已有空 vec 的记录怎么办
+
+不要删索引。
+
+先备份，然后回填：
+
+```powershell
+$s = 'C:\Users\...\sessions\<sessionId>'
+
+node bin\bc-relabel.mjs --vectors `
+  --index "$s\bc-index.jsonl" `
+  --turns "$s\turns.jsonl" `
+  --out "$s\bc-index.vec.jsonl" --write
+```
+
+这会把旧记录缺的 `vec`/`chatter` 补上。
+
+## 7. 然后审计才会运行
+
+```text
+vec 恢复
+-> 审计有聚类点
+-> 下一次达到 200 轮阈值时才会执行
+```
+
+**比如这种情况：**
+
+```text
+如果已经 507 轮，但 audit-state.lastAuditTurn 已经接近 507，
+则修好 vec 后不一定立刻触发；
+要等下一次满足阈值，或手动调整/重建审计状态。
+```
+
+## 8. 一句话
+
+```text
+A/B/C/K 有，不代表 vec 有。
+vec 空，审计就不工作。
+vec 空通常不是规则问题，是本机 onnxruntime 没构建。
+```