dsh-tingxue · 听雪

DeepSeek Harness 的双模式虚拟生命插件：一个有人格、有长期记忆的 QQ 聊天对象，外加一个用完即焚的隔离文件处理会话。

听雪是一个跑在 DeepSeek Harness 上的自建插件。它的记忆不依赖任何托管服务——LanceDB 本地文件即库，关系图谱自己实现，语义推理走可插拔的小 LLM。

---

目录

• 特性
• 前置要求
• 安装
• 快速开始
• 配置
• 架构
• 会话隔离与模式自愈
• 记忆服务（HTTP API）
• AstrBot 群聊对接
• 开发
• 路线图
• 文档索引
• 贡献
• 许可证

---

特性

双模式	聊天模式（日常对话，人格 + 长期记忆，上下文结构对缓存友好）与 agent 模式（隔离的纯文件处理会话，用完即焚，归档进记忆）
全自动切换	全程只有 /agentstart 和 /agentstop 两条指令，自动建会话、自动绑定、自动回绑，不需要手动 /bind
自建记忆库	LanceDB 嵌入式向量库，本地文件即库、零服务器；4 张表（记忆条目 / 实体 / 关系 / 最新信息）
自建关系图谱	实体抽取 → 实体链接 → 三元组关系（带时间窗口与溯源）→ 图遍历增强检索；参考 Graphiti / Mem0 实践
可交互图谱 UI	零依赖 canvas 力导向蜘蛛网：节点聚类、邻居高亮、标签碰撞避免、小地图导航，离线可用
可插拔模型层	embedding 与语义推理抽象成统一接口，换模型只改配置，插件逻辑零改动
图形化配置	29 个配置项做成图形界面，设置侧边栏独立成页 + 插件配置标签页两个入口，含覆盖标记与单点重置
安装安全流程	scripts/install-check.mjs：一条命令把「装完静默失效」变成可机检断言，--fix 自动修复且失败自动回滚；活 profile 只读、凭据只比对不回显
推送隔离	通过 dsh-notifier 的 route:agents 精确分流，其他 DSH 会话的通知与审批不会打扰 QQ
模式自愈	启动自检 + 运行期 reconcile：mode 与 QQ 真实绑定不一致时自动退回聊天模式，不会静默丢掉人格与记忆

---

前置要求

依赖	版本	说明
Node.js	>= 22.19	见 package.json 的 engines
DeepSeek Harness	0.1.1-rc.2 或更高	插件运行宿主
dsh-notifier	0.9.0 + 补丁	QQ 通道。⚠️ 必须钉死 0.9.0 并打补丁，不是普通的 ^0.9.0（见 安装 与 发布形态与安装流程.md §4）
pnpm	任意近期版本	安装 @lancedb/lancedb 时需要解析原生依赖
一个 LLM / embedding 端点	—	默认走 sta1n 供应商，也可切换本地 OpenAI 兼容端点

外部依赖仅两个运行时包：@lancedb/lancedb 与 apache-arrow（版本锁 18.1.0）。

---

安装

[!IMPORTANT] 先装 dsh-notifier，并把它钉在 0.9.0 + 打上补丁（见下方第 2 步）。这不是可选项——不打补丁，QQ 收文件功能整个不存在（DSH 侧靠补丁拼出的 [文件] 名称\n下载地址: url 标记来下载文件），且超 2000 字会被硬切半句。原因与替代方案见 发布形态与安装流程.md §4。

# 1) 在 DSH profile 目录安装本插件
#    Windows 默认路径：%USERPROFILE%\.dsh\profiles\web
cd ~/.dsh/profiles/web
pnpm add file:/absolute/path/to/dsh-tingxue

# 2) 把 dsh-tingxue 加入 profile 的 package.json
#    "dsh": { "profile": { "bundles": [ ..., "dsh-tingxue" ] } }
#    —— 漏这一步会得到「已安装，未生效：未声明 dsh.bundle，已作为普通依赖安装」

# 3) 重启 DSH 让插件挂载

前置的 dsh-notifier（必须先做）：

cd ~/.dsh/profiles/web
pnpm add dsh-notifier@0.9.0          # 必须钉 0.9.0，补丁的行号基于此版本

# 把补丁放进 profiles/web/patches/，然后在 pnpm-workspace.yaml 里接线：
#   patchedDependencies:
#     dsh-notifier: patches/dsh-notifier.patch
pnpm install                          # 让补丁生效

补丁生效的验证：node_modules/dsh-notifier/src/inbound/_qq-segment.mjs 存在，且 src/inbound/message.mjs 里能搜到 parseQQFileAttachments。

[!IMPORTANT] DSH 插件的源码是进程启动时加载、不热重载的。改完源码必须两步走：① 同步到 profile 的 node_modules 副本 → ② 重启 DSH。 cordis.patch.yml 的配置改动会热重载，但 .mjs / client.js 源码不会。 浏览器端同理：__DSH_BOOT__ 是加载 HTML 那一刻注入的，重启 DSH 后还需要硬刷新页面（Ctrl + Shift + R）。

4) 装完自检（一条命令，别靠肉眼）

装完最容易出的不是报错，而是静默失效：插件装上了、进程也起来了，功能却不在。上面那几步手工动作，漏任何一条都是这个结果。所以装完最后跑一次：

cd ~/.dsh/profiles/web
node <插件仓库>/scripts/install-check.mjs          # 有问题 exit 1，全绿 exit 0
node <插件仓库>/scripts/install-check.mjs --json    # 机器可读

它逐条机检下面这些「漏了就静默失效」的点，并给出可执行的修复指引：

检查	漏了会怎样
C1 插件声明了 dsh.bundle，且有 files 白名单	profile 会把它当普通依赖装
C2 插件在 dsh.profile.bundles 名单里	正是那句「已安装，未生效：未声明 dsh.bundle」
C3 dsh-notifier 钉死 0.9.0（不是 ^0.9.0）；已装版本也是 0.9.0	补丁带行号 hunk，升级后 pnpm install 直接失败。有 pnpm-lock.yaml 时本机今天不会立刻炸，但换机器 / 删 lock / pnpm update 会
C4 补丁接线在 pnpm-workspace.yaml 的 patchedDependencies（不在 profile 的 package.json 里）	补丁文件躺在磁盘上也不会被应用
C4-applied 补丁真的生效了（_qq-segment.mjs 在 + message.mjs 含 parseQQFileAttachments）	QQ 收文件功能整个不存在；接完必须再 pnpm install
C5 运行副本 node_modules/dsh-tingxue 与仓库的 src/ client/ 补丁层逐字节一致	profile 用 file: + nodeLinker: hoisted，运行副本是真实目录拷贝不是 junction → 改仓库不生效（本项目最隐蔽的失效模式）
C6 仓库里没有活配置的凭据明文（扫全部跟踪文件），工作区干净	凭据进仓库
C7 活 profile 里的明文凭据被识别出来	真实风险面其实在仓库外（见 SECURITY.md）
C8 npm pack --dry-run 清单无泄漏	.gitignore 拦不住 npm 打包，files 白名单才是权威
C9 profile 的 cordis.patch.yml 结构上真的能解析	一条缩进坏掉的补丁层会让整个 profile 起不来（DSH 启动即失败），而 git status 与肉眼都看不出来

C9 是被真实事故加的。 手改 cordis.patch.yml 时删多/删少一行，留下的悬挂键会让 YAML 解析直接失败，两个解析器都会拒绝；而当时的工具链里没有任何东西能发现它——一重启 DSH 就起不来。C9 只做结构校验（可解析、是补丁项数组、无重复映射键），不检查语义。

⚠️ scripts/ 不随 npm 包发布（files 白名单只含 scripts/selfcheck.mjs）。所以 install-check.mjs 只对从仓库克隆的使用者可用；用 npm 安装的人没有这个文件。要跑自检请克隆仓库。

C5 对 manifest 只比对运行时字段（version/main/exports/dsh/dependencies/peerDependencies/engines/type）——仓库 URL 这类元数据差异不点红，免得把「永远有条红的忽略掉」训出来。

C3 与 C5 按「现在是不是真的坏了」分级，不是一刀切报红——一条永远挂着的红等于没红：

情形	判定
C3：^0.9.0，但 pnpm-lock.yaml 锁住了 0.9.0	warn（地雷，不是当下的火：今天不会炸，换机器 / 删 lock / pnpm update 才踩）
C3：^0.9.0，且没有 lock	fail（下次安装就会拉到新版）
C3：已安装的版本不是 0.9.0	fail（补丁的行号上下文必然错位，当下的火）
C5：运行副本 == 仓库工作树	ok
C5：差异全是未提交的在制品（运行副本 == HEAD）	warn（已提交的那份没坏；但在制品要生效必须先同步 + 重启）
C5：存在已提交却没同步的文件	fail（跑的就是旧代码）

自动回滚：加 --fix 才会写盘，且动手前逐文件备份原始字节与 SHA256；只要有一条修完复检仍不过，就整批回滚并给出还原前后的哈希对比。

# 先复制一份 profile 再让它修（推荐；活 profile 默认拒写）
node <插件仓库>/scripts/install-check.mjs --fix --profile-dir /path/to/profile-copy

两条护栏：

• 活 profile 默认只读。--fix 对 ~/.dsh/profiles/** 下的文件一律拒写（报告里记为 skipped），要真写必须显式加 --allow-live-profile。校验模式（不加 --fix）永远不写任何文件。
• 凭据只比对、不回显。脚本会读出活配置里的凭据字面量用于比对，但绝不把值写进输出——只报处数与文件名。校验完 git status --porcelain 仍应为空。

它不会替你做的两件事（会改变活环境，交回你的手）：跑 pnpm install、同步运行副本并重启 DSH。这两条它只会报红并说清该做什么。

---

快速开始

装好并重启后，在 QQ 里直接说话即可进入聊天模式。

（直接发消息）          → 聊天模式：有人格、有记忆、四块上下文组装
/agentstart           → 进入 agent 模式：新建隔离会话并自动绑定
（发文件、多轮讨论）      → 文件作为上下文持续处理
/agentstop            → 归档对话到记忆库、删除工作副本、销毁隔离会话、自动回绑聊天会话

两条指令之外没有任何手动步骤——不用 /bind，也不用 /unbind。

发文件：QQ 附件经 [文件] 标记由 pre-step 下载到 dataDir/workcopy/ 并注入上下文。文本文件直接进上下文（单文件上限 5 MB、正文截取 8000 字符）；二进制文件只给文件名与大小元信息。聊天模式与 agent 模式都支持。

图谱面板：默认监听 http://127.0.0.1:8765，浏览器打开即可看到实时的实体关系蜘蛛网。

---

配置

配置方式

有两种，优先级从高到低：

1. 图形界面（推荐）——DSH Web GUI 的「设置」：
   • 设置侧边栏 →「听雪」（主入口，独占一页）
   • 设置 → 插件 → 插件配置（次入口，卡片形态）
   • 两处入口共用同一个 settings scope，内容永远同步；写入 settings 用户层（$DSH_HOME/settings.yaml）
2. 配置文件——profile 的 cordis.patch.yml，作为 settings 的 base 层保留

界面里标「已覆盖」的字段表示它覆盖了部署配置，可单点重置回落到部署层。写入用 revision 设栅，表单漂移会被拒绝而不是覆盖并发修改。

Host 与浏览器两个半侧各有一份同构的字段表（src/settings/index.mjs 的 SETTINGS_FIELDS 与 client/client.js 的 FIELDS），当前各 29 项，分组与键一一对应。

配置项

配置项	默认	说明
人格与记忆
profilePath	''	听雪档案 txt 路径（人格提示词，由用户自写）
dataDir	cwd/.dsh-tingxue	记忆库数据目录（LanceDB 本地文件即库，state.json 也在这里）
recentRounds	10	最近 N 轮滑动窗口（仅在打开「重复注入最近对话」时生效）
injectRecentRounds	false	重复注入最近对话。默认关：DSH 会话历史本身已含最近对话，再注入一遍等于同一段话付两次 token（实测约 1.5K/轮）
memoryBudgetTokens	1600	向量记忆检索块 token 上限
latestInfoBudgetTokens	1000	最新信息块 token 上限
模型
modelBackend	sta1n	模型后端：sta1n / local / custom
embeddingModel	gemini-embedding-2	向量模型（同库单一模型铁律）。设置页可点「选择模型」从端点列表里挑
embeddingDimensions	3072	向量维度，须与模型实际输出一致
llmModel	gemini-3.1-flash-lite	语义推理小 LLM（实体抽取 / 摘要）。设置页可点「选择模型」从端点列表里挑
baseURL	''	local / custom 时的 OpenAI 兼容 base URL
apiKey	''	留空则回落到 DSH 凭据服务里的 STA1N_API_KEY
双模式命令
agentStartKeyword	/agentstart	进入 agent 模式的关键词
agentStopKeyword	/agentstop	退出 agent 模式的关键词
fileDeleteScope	workcopy	文件删除范围：workcopy 只删工作副本 / keep 一律保留
绑定与推送
channel	qq	绑定通道（dsh-notifier 的 channel）
userId	''	绑定用户（dsh-notifier 的 userId）
chatSessionId	''	自愈回绑用的可信聊天会话 id
notifierStateFile	''	留空用默认的 dsh-notifier state.json
routeWorkspace	dsh	被静音的默认 workspace
quietOtherWorkspace	true	只让听雪自己的消息送达 QQ
qqStatusNotice	true	QQ 是否显示任务状态提示（🚀 任务开始 / ✅ 任务完成 / ⏹ 任务已中止 / ⏱ 心跳 / ⚠️ 疑似卡住）。关掉后这些状态行不发，回复正文照常送达（回复本体走 turn/end 通知的正文，见 交接文档.md §16.2）；❌ 出错通知保留
approvalAllowlistOnly	true	审批是否只推 QQ 对话会话。打开后只有被显式放行出站的会话（听雪聊天会话 / tingxue-agent-* 隔离会话）的批准询问发到 QQ，其他 DSH 会话的审批只在桌面弹（需配套的 dsh-notifier 补丁，见 交接文档.md §16.3）
面板与服务
graphDashboardEnable	true	是否启用关系图谱面板
graphDashboardHost	127.0.0.1	图谱面板监听地址（默认仅本机 loopback）
graphDashboardPort	8765	图谱面板端口
memoryServiceEnable	true	是否启用记忆服务（管家）
memoryServiceHost	127.0.0.1	记忆服务监听地址
memoryServicePort	8766	记忆服务端口

还有若干只在配置文件中生效的字段（routeWorkspaceChannels、provider、model、cwd 等），不暴露在界面上。

生效时机

• 标了 applies: 'restart' 的命名空间：dataDir、模型、端口这类启动期读取的字段，改动需重启 DSH。
• recentRounds、injectRecentRounds、记忆 / 最新信息预算这类按次读取的字段，保存后立即生效。
• qqStatusNotice / approvalAllowlistOnly 保存后立即生效：它们被写成 dsh-notifier 的 prefs:tingxue 状态键，由 dsh-notifier 补丁在每次推送 / 审批时实时读取（500ms 读收敛）。
• graphDashboardEnable / memoryServiceEnable 等开关由插件启动期读取，需重启 DSH。

---

架构

项目结构

dsh-tingxue/
├── src/                          # Host 半侧
│   ├── plugin-entry.mjs          # 插件入口：组装各层、接入 DSH 事件管线、注入与推送隔离
│   ├── models/index.mjs          # 模型适配层（embedding + 小 LLM + 模型列表，可插拔）
│   ├── memory/store.mjs          # LanceDB 记忆存储（4 张表）
│   ├── graph/index.mjs           # 关系图谱（抽取 / 链接 / 关系 / 图遍历）
│   ├── graph-dashboard/index.mjs # 关系图谱面板（零依赖 canvas 力导向蜘蛛网）
│   ├── memory-service/index.mjs  # 记忆服务（管家）：DSH 唯一写者，HTTP API 供 AstrBot 对接
│   ├── model-catalog/index.mjs   # 模型目录路由：设置页模型选择器问端点有哪些模型
│   ├── context/assemble.mjs      # 聊天模式四块上下文组装
│   ├── context/inject.mjs        # 注入接线：异步瀑布取真值（避开 section.text 同步求值）
│   ├── http/index.mjs            # 共享 HTTP 工具（端口探测 / JSON 读写响应）
│   ├── state/index.mjs           # 双模式状态机（持久化 + 滑动窗口裁剪）
│   ├── commands/index.mjs        # 关键词命令处理（含绑定失败回滚）
│   ├── bind/index.mjs            # dsh-notifier 绑定读写 + 推送隔离 + 通知偏好
│   ├── settings/index.mjs        # Host 半侧：注册 settings 命名空间
│   ├── segment.mjs               # QQ 长消息句子完整分段器
│   └── agent/index.mjs           # agent 模式（文件生命周期、归档）
├── client/client.js              # 浏览器半侧：手写 lazy-CJS bundle（设置界面）
├── test/                         # 单元测试（含 test/patches/ 补丁验证，不随主测试集）
├── astrbot-plugin/               # AstrBot 群聊对接插件（Python）
├── research/                     # 第三方参考材料（不进公开仓库）
├── cordis.patch.yml              # bundle patch（插件行声明）
└── package.json

记忆库表结构（LanceDB）

表	用途	关键字段
memories	记忆条目（向量检索主表）	text vector scene identity source createdAt entityIds
entities	实体节点	name type summary vector
relations	关系边（三元组）	sourceId targetId relation validFrom validTo
latest	最新信息（文件摘要 / 待办）	kind text createdAt

聊天模式上下文组装

顺序固定，前缀稳定以命中缓存：

[1] 听雪档案        —— 从 profilePath 读取，固定不变（稳定缓存前缀）
[2] 向量记忆检索     —— 按当前输入语义检索，有界（默认 1600 token），命中才插入
[3] 最近 N 轮对话    —— 默认关闭（见下方说明）
[4] 最新信息        —— 最近文件摘要 / 待办，有界（默认 1000 token）

关于 [3]：DSH 会话本身就是「全部交互历史的仅追加真源，LLM 消息历史由它派生」（packages/core/session/README.md）。最近对话本来就在会话历史里，插件再塞进 system 一遍 = 同一段话在模型眼里出现两次，实测每轮白付约 1.5K token。因此 [3] 由 injectRecentRounds 守卫，默认不注入；只有换绑到新会话、会话历史不可用时才需要打开。

关于 [4]：组装逻辑（src/context/assemble.mjs）具备该块，但 pushLatest() 目前在插件里没有调用点，实测 71 条请求命中 0 次——属死代码，不是故障。要用需先接上写入侧。

精确一点：store.addLatest / store.listLatest 都是已实现且已导出的（src/memory/store.mjs），但全仓没有任何调用者调用 addLatest（插件写的是 state.latestInfo，实测为 []）。所以真正的情况是「读取侧接线、写入侧缺失」：store 里那张 latest 表永远是空的，[4] 因此恒不出现。处理建议：要么删掉 [4]（连 latestInfoBudgetTokens），要么给 addLatest 接上写入者——后者会增加常驻上下文，与「上下文别涨」的目标相反，故推荐前者，除非确实要用「文件摘要/待办」。

把 recentRounds 调小为什么不会让上下文变小（实测归因）

用户体感「滑动窗口设成 10，DSH 统计的上下文长度却还在涨」。实测归因（真机聊天会话 136 轮，逐帧解压 session.jsonl.zstd 后按 request/header 统计）：

组成部分	实测字符数	说明
[1] 听雪档案	7,022（恒定）	就是 profilePath 那个文件，改档案＝永久变大（该文件现为 10,415 字符，改动即 +3.4K）
[2] 向量记忆	12,088 – 14,981（逐轮不同）	取决于本轮检索命中几条；预算 1600 token 截断
[3] 最近对话	0	被 injectRecentRounds 守卫，实测未开启
[4] 最新信息	0	无写入者（见上）
注入小计	约 20.3K（占 91%）	真正由插件贡献的部分
非注入部分（DSH 本体提示词 + 67 个工具 schema）	1,850（恒定）	实测各轮完全相同

结论（三条判据）：

1. 不是 DSH 历史累积导致的增长 —— 非注入部分恒为 1,850 字符，在 turn 126→136 之间完全没有变化。会话历史确实在累积（它是仅追加真源），但它在本机不进入 system 提示词，所以「DSH 统计的上下文长度」的跳动不是它造成的。
2. 不是压缩没生效 —— 压缩在正常工作：实测 compaction/start ×24、compaction/end ×24、compaction/prune ×2、compaction/summary ×1（summary 15,284 字符，带 shadowedRange / shadowedTokenCount）。压缩是有损的，不会把上下文压回一个固定值。
3. 跳动来自插件自己的注入 —— 逐轮 total 在 20,808–23,853 字符之间摆动 ±2,000，来源只有两个：[2] 记忆块命中多少条、以及 [1] 档案文件被改写。

所以 recentRounds 这个旋钮的语义要读对：它只控制「重复注入最近 N 轮对话」，而 [3] 默认关闭，所以调它既不会让上下文变大、也不会变小。要缩小上下文，该动的是：档案文件长度（[1]）、memoryBudgetTokens（[2] 上限）、以及关掉 [4]/不要接线。

可复核的命令：

node scripts/selfcheck.mjs            # 逐轮 system 长度 / 同一个回合内是否变动（唯一判据）
node scripts/selfcheck.mjs --json --full

（另有 --started=<ISO 时刻> 可覆盖「进程启动时刻」，只在诊断/测试判据②时用，见下文「运行状态自检」。）

另有一个独立（非增长类）缺陷已由 selfcheck 报出：同一个回合内 system 长度会变动（34 轮里 15 轮，最大摆动 2,992 字符，turn 136 出现 【相关记忆】 整块消失的一次）。这是「记忆块在轮内不稳定」，属于注入抖动，不是本节的增长归因；排查入口是 turnInput 缓存键与 agent/inbox/inserted 的时序。

注入走异步瀑布，不走 section.text（重要）

DSH 的 SystemPrompt.section() 要求 text 是同步函数返回 string。但 assemble() 的内部顺序是：

packages/core/system-prompt/src/index.ts:510   同步求值每个 section.text   ← 缓存在这里被读走
packages/core/system-prompt/src/index.ts:532   await system-prompt/assemble 瀑布
packages/core/agent-loop/src/agent.ts:230      preStep 先 await assemble()，再发 agent/pre-step

同步求值结构上必然早于任何异步检索。所以「异步预算写入缓存 + text() 同步读缓存」的做法不是偶发竞态，而是首轮必空、之后恒错位一轮——实测表现就是 system 提示词在 6827（DSH 本体裸大小，一块都没注入）与 13872 之间抖动，人格块命中率只有 42%。

正确做法是 system-prompt/assemble 瀑布（src/context/inject.mjs）：它能 await，且返回值是权威装配。section 只注册一个空占位块保住名字与顺序，真值在瀑布里就地组装后就位替换。DSH 自己的 installModelSelection（packages/core/agent/src/model-selection.ts:40）也是这么用的。

实现要点：

点	原因
就位替换，不 push 到末尾	块声明 order: 100，push 会掉到 100–199 的工具指引之后，破坏块顺序
校验 context.agent === agent	瀑布是 scope 继承的，不校验会收到别的会话的装配 → 跨会话串线
按用户输入串缓存	assemble() 每个 step 都跑一次；多步回合（工具调用）不缓存就每步都 embed + 向量检索
未 ready / agent 模式返回 null 且不落缓存键	否则 mode 切回聊天后会一直读到空串
installContextInjection 幂等	有 agent/created 与启动补注入两个入口，重复 section() 会因重名抛错
预热 + 瀑布共用同一次检索	embed + 检索实测约 790ms。在写 lastUserText 的监听器里不 await 地预热，瀑布 await 同一个 in-flight promise——既把延迟藏起来，又不重复检索
缓存带代号，只有最新那次能落缓存	用户连发两条时，先发起的慢检索晚回来会用旧结果覆盖新结果
refreshDisposer 不碰缓存	它注册得比写 lastUserText 的监听器早；在那里 invalidate 会把刚预热好的结果丢掉，白白多检索一次
检索输入与缓存键用 turnInput，不用 lastUserText	assistant/message 每个 step 都触发，step0 结束会把 lastUserText 清空（配对写滑动窗口 + 记忆）。若检索用它，step1 起 currentInput 变空 → 记忆块在同一轮里整块消失。这两个变量不能合并：lastUserText 是「待配对输入」（配对后清空），turnInput 是「本轮输入」（整轮不变）

回归测试见 test/inject.test.mjs：它用假 systemPrompt 精确复刻「先同步读 text → 再 await 瀑布」的顺序，因此能真正抓住这个 bug（在旧设计下会失败）。另有并发与多 step 回归：预热与瀑布共用同一次检索、慢检索晚回来不覆盖新结果、同一轮 step1 起记忆块不消失（同轮 system 必须完全一致）。

关系图谱

• 实体抽取：小 LLM 从文本抽取实体（person / place / thing / concept）
• 实体链接：实体名归一化 + 向量相似，把新实体关联到已有实体
• 关系建立：抽取实体间三元组关系，带时间窗口与溯源
• 图遍历：从种子实体沿关系扩展，用于增强记忆检索（assembleContext 里从命中记忆的 entityIds 扩展 depth=1、limit=5）
• 交互 UI：graph-dashboard 自绘 canvas 力导向蜘蛛网，零外部依赖、离线可用

图谱面板的工程细节：

• 性能：拖动节点 / 空白平移时暂停每帧 O(n²) 全对斥力计算（animOn=false 仅静态重绘），松手后短暂恢复模拟让邻域收敛；鼠标与触屏双 handler 均已处理。
• 视觉：① 按类型聚类（clusterCenters）② hover 邻居高亮 + 非邻居淡出（focusSet）③ 标签碰撞避免（labelRects 包围盒跳过重叠）④ 右下角小地图（标准缩略图模式，点击跳转视口）⑤ 背景网格固定视口，不随缩放平移移动。
• 两个坑：HTML 模板字符串里的内联 onclick 绝不能用 \' 转义单引号（要用 HTML 实体 '）；canvas 顶部有 56px 标题栏，所有事件坐标必须经 canvasOffset() + evtPos() 转成画布相对坐标。

双模式与会话隔离

聊天模式（默认） QQ 一进来就是聊天会话，四块上下文组装，有人格与长期记忆。

agent 模式（隔离会话，用完即焚）

• 进入：/agentstart → 用 ctx.agents.create() 新建隔离会话（只注入听雪档案，不含聊天记忆与历史）→ 自动绑定。
• 处理：文件作为上下文持续处理，可多轮。
• 退出：/agentstop → 归档对话与文件摘要到记忆库 → 删除工作副本 → dispose() 销毁隔离会话 → 自动回绑聊天会话。

会话隔离铁律

session/event 与 agent/inbox/inserted 监听器对所有会话生效，因此必须按 session.id 过滤：聊天模式只在 sessionId === chatSessionId 时写记忆；agent 模式只在 isAgentSession(session) 时补全待归档轮次。两种会话的记忆与上下文完全隔离。

dsh-tingxue-context 段的注册位置

systemPrompt.section 是作用域继承的：注册在插件 root ctx 会对该 profile 下所有会话生效（人格/记忆泄漏到无关会话 = 上下文串线）。因此本插件把它注册在聊天会话自己的 agent 作用域（agent.ctx.get('systemPrompt').section() + agent.ctx.effect），只对聊天会话可见，并随该 agent dispose 自动卸载。

推送隔离

通过 dsh-notifier 的 route:agents 做出口分流：静默默认 workspace（channels: []），再精确放行听雪的聊天会话。插件 init 时写一次，/agentstart / /agentstop 期间动态维护。结果是其他 DSH 会话的 turn/end、审批与错误通知不再广播到 QQ。

审批与远程提问是另一条更容易漏的出口：approval/router.mjs 的 resolveApprovalChannels() 只取 channelTypes、忽略 quiet，而空集还会回落全局广播。配套补丁把判据换成「只推 route:agents 里被显式放行的会话」，见 交接文档.md §16.3 / §16.8。

模型适配层（可插拔）

src/models/index.mjs 把两种能力抽象成统一接口：

embed(texts)        // 文本 → 向量
complete(prompt)    // 小 LLM 语义推理

后端	说明
sta1n（默认）	走 sta1n 供应商的 OpenAI 兼容端点，零部署
local	走本地 OpenAI 兼容端点（ollama / llama.cpp）
custom	完全自定义

接口有三个方法：embed(texts) 文本 → 向量、complete(prompt) 小 LLM 语义推理、listModels() 列出端点当前提供的模型（供设置页的选择器用，见下节）。

换模型只需改配置，插件逻辑零改动。 注意记忆库的单一向量模型铁律：同库内必须模型与维度一致，换 embedding 模型需要全量重嵌入。

设置页的模型选择器

「向量模型」和「语义推理小 LLM」两个字段旁边有一个选择模型按钮：点开询问当前端点提供哪些模型，从真实列表里挑一个填进去（带搜索框，sta1n 的列表有 102 项，靠眼睛翻不现实），不用手敲模型 id。输入框照旧可以直接手填。

数据通路：

环节	位置	说明
客户端弹窗	client/client.js 的 ModelPicker	结构照 DSH「设置 → 模型」的 ModelListEditor：询问端点 → 从候选里挑
HTTP 路由	src/model-catalog/index.mjs	POST /dsh-tingxue/models
适配层	src/models/index.mjs 的 listModels()	打 GET <base>/v1/models

两个实现选择值得记下来：

• 走宿主自己的 webServer（与 GUI 同一个端口），不另开监听端口。因此不存在跨源问题，也不需要额外的鉴权层——和 GUI 同源。DSH 把 llm.discoverModels 钉在 loopback 上，这里用同样的判据（同源 + 回环兜底），因为它同样会拿着一把可能明文的 key 去问端点。
• 不用 DSH 的 llm.discoverModels seam：那个由 llm-pi-ai 适配器回答，只认它命名空间里声明过的 provider profile；听雪的模型后端是插件自己的配置（modelBackend / baseURL / apiKey），问它只会得到「未知 provider」。这里用听雪自己的适配层问同一条协议，端点、协议、key 的解析方式与真正发请求时完全一致——选择器看到的就是实际会用的那份列表。

请求体是「表单当前显示的值」而非已保存的配置：刚填进去、还没保存的端点或 key 也能立刻试。服务端只读，不写任何配置，apiKey 只用于这一次询问、不存储也不回显。

宿主没有 webServer 服务时路由静默跳过，选择器退化成手填模型 id，不影响其他功能。

API Key 的解析走 DSH credentials 服务，每次 resolve 时重新 ctx.get('credentials')，不能在 init 时同步捕获闭包——init 早于 credentials 挂载时闭包会固定为 undefined，之后每次取 key 都 401。模型适配层与模型目录路由共用 plugin-entry.mjs 里的同一份 resolveApiKey，保证两条路径取到同一把 key。

换 key 只改一处：$DSH_HOME/.credentials.yaml 里的 STA1N_API_KEY（sta1n 后端的 apiKeyEnv）。插件、运行时副本、AstrBot 插件都不需要改——插件经凭据服务取 key，AstrBot 经 HTTP 服务间接使用。改完重启 DSH 生效。

settings.yaml 里 llm-pi-ai.providers.sta1n.models 是模型下拉列表，必须与实际线上列表一致，否则选到已下线的模型会直接 400/404。核对方式：

# 拉线上列表（需要有效 key），与 settings.yaml 的 - id: 条目对比
node -e "fetch('https://cdn.sta1n.cn/v1/models',{headers:{Authorization:'Bearer '+process.env.K}}).then(r=>r.json()).then(j=>console.log(j.data.map(m=>m.id).sort().join('\n')))"

---

会话隔离与模式自愈

这是本项目历史上踩得最贵的两个坑，均已修复并固化。

症状

state.json 的 mode 残留在 agent，但 dsh-notifier 的 bind:qq:<userId> 实际还指向聊天会话。此时：

• QQ 消息仍然投递到聊天会话（绑定没变）；
• 但上下文注入在 agent 模式下直接返回空（旧实现是 refreshContext() 置空 cachedContextText，现在等价于 buildContextText() 在 state.isAgentMode() 时返回 null）；
• 结果：人格、记忆、最近对话三块全部静默消失，而"隔离"根本没发生——静默失忆的最坏组合。

真机实测：system 提示词从 11,682 字符掉到 6,827 字符，听雪的块全部消失，QQ 那头毫无提示。

根因

1. POST /agentstart 路径里，createIsolatedAgent() 无论 setBinding() 成功与否都返回 { ok: true }，调用方只检查 result.ok → 绑定没切成也照样 state.enterAgent()。
2. 「agent 模式就置空注入」是唯一一处"置空"逻辑（旧实现是 refreshContext() 的第二行，现在等价于 buildContextText() 里的 state.isAgentMode() 早退），agent 模式一旦误判就全线失守。
3. mode 是持久化的，误判会跨重启存活。

三层防御（已实现）

层	位置	行为
写前守卫	commands/index.mjs	createIsolatedAgent() 回传 bound；/agentstart 在 !result.bound 时调用 rollbackIsolatedAgent()（dispose 会话 + 清精确放行路由）并保持聊天模式，直接回复失败原因
启动自检	plugin-entry.mjs §5.1.3	启动时若 state.isAgentMode() 且 bind 未指向 state.agentSessionId，立即 exitAgent() 并告警
运行期 reconcile	plugin-entry.mjs	agent/inbox/inserted 命中聊天会话且处于 agent 模式时调用 reconcileAgentMode()（reconciling 标志防重入），比对真实绑定；漂移则 exitAgent() + ensureContextText(true) 强制重组装恢复注入

判据统一为一句话：agent 模式只有在 QQ 确实绑着那个隔离会话时才算数。

副作用记录：/agentstart 曾经在失败路径留下 295 字节的空壳隔离会话（tingxue-agent-*）。rollbackIsolatedAgent() 就是为了不留残留而加的。

---

记忆服务（HTTP API）

src/memory-service/index.mjs 是记忆的唯一写者，默认监听 http://127.0.0.1:8766（仅 loopback）。它把所有写操作经内部先进先出队列串行化，保证 LanceDB 永远只有一个写者，规避多进程并发写冲突。

方法	路径	说明
POST	/memory	写入一条记忆（服务端负责 embedding）。快速返回：只同步落库正文与向量，实体抽取挪到响应之后异步做
GET	/memory/search	按语义检索记忆（q / limit / scene）
GET	/memory/entities	列出实体（上限 1500）
GET	/memory/relations	列出关系（上限 6000）
GET	/memory/expand	从种子实体沿关系扩展（entityId / depth）
GET	/profile	返回人格文本（供多端共用同一份人格）
GET	/health	健康检查

为什么 /memory 是快速返回：实体抽取是一次慢的小 LLM 调用。早期实现把它放在响应路径里，AstrBot 客户端 15 s 超时先到，日志只留一句空异常的 asyncio.TimeoutError，服务端其实已经写成功 → 客户端重试就写出重复记忆。现在响应体带 async: true，抽取在 writeChain 之后跑，失败只记日志。

---

AstrBot 群聊对接

目标是让 DSH（私人） 与 AstrBot（群聊） 互相独立、共享同一份记忆与人格：

DSH（唯一写者）──写──► 记忆库(LanceDB) ◄──HTTP── AstrBot
        │                        ▲
        └── 暴露 HTTP 记忆服务 ───┘

• DSH 是唯一写者：AstrBot 只通过 HTTP 记忆服务读写，不直接碰 LanceDB 文件。
• embedding 一致性：embedding 统一由 DSH 生成，AstrBot 只传文本。
• 人格通用：两边各自加载同一份人格 txt，DSH 通过 GET /profile 提供。
• 记忆储存策略（仿人脑）：不按群组织，每个人物是独立实体节点，人物之间有关系边，记忆挂到相关人物上。

对接插件在 astrbot-plugin/（当前 v1.3.0），提供群聊 + 私聊自动记忆与 /回忆 /图谱 /记忆状态 命令，并严格隔离私聊。它通过 @filter.on_llm_request() 在 LLM 请求发出前检索记忆与人格，追加进 system_prompt（位于滚动窗口历史之前，滚动窗口与压缩都动不到）。

记忆注入与人格注入是两个独立开关（inject_memory / inject_profile），各自失败都不影响另一路。

[!NOTE] AstrBot 侧 LLM 建议使用 DeepSeek 官方端点：sta1n 对 openai SDK 的 x-stainless-* 请求头一律返回 403。

---

开发

环境准备

git clone <repo-url>
cd dsh-tingxue
pnpm install

运行测试

# 方式一：一次性跑全部
pnpm test

# 方式二：逐个运行（推荐在受限沙箱下使用）
# node --test 在部分沙箱环境会因 spawn EPERM 失败，直接运行测试文件即可
node "test/store.test.mjs"
node "test/context.test.mjs"
node "test/graph.test.mjs"
node "test/bind.test.mjs"
node "test/dashboard.test.mjs"
node "test/memory-service.test.mjs"
node "test/segment.test.mjs"
node "test/settings.test.mjs"      # Host 半侧：settings 命名空间注册
node "test/client-card.test.mjs"   # 浏览器半侧：设置界面 bundle
node "test/state.test.mjs"         # 双模式状态机 + 滑动窗口裁剪
node "test/inject.test.mjs"        # 注入时序（异步瀑布取真值）
node "test/selfcheck.test.mjs"     # 自检脚本自身（证明它会红，不是橡皮图章）
node "test/notifier-suppress.test.mjs"     # 命令消费不该被报成「任务被阻塞」
node "test/bigint.test.mjs"        # LanceDB Int64 是 BigInt（含真机契约：expand 不得挂死）
node "test/agent-mode-e2e.test.mjs"        # /agentstart → /agentstop 真机全流程（34 项）
node "test/install-check.test.mjs"         # 安装安全流程：坏环境真判红 + 回滚真还原 + 凭据不回显
node "test/patches/_qq-segment.test.mjs"   # 历史 QQ 分段补丁（不随主测试集）

运行安装自检

装完/改完 profile 后跑，判断「装上了但没生效」：

这个脚本不随 npm 包发布（files 白名单只含 scripts/selfcheck.mjs），只有克隆仓库才有。用 npm 安装的话请克隆仓库后再跑。

node scripts/install-check.mjs               # 校验活 profile（只读，不写任何文件）
node scripts/install-check.mjs --json        # 机器可读
node scripts/install-check.mjs --self-test   # 自带回归（零依赖，临时目录内自建夹具）
node scripts/install-check.mjs --self-test --live   # 真机项也计入退出码（默认仅提示）
node scripts/install-check.mjs --profile-dir <副本> --fix   # 修复 + 失败自动回滚

--self-test 与标准套件是同一份实现：核心 31 条通过脚本导出的 registerCoreCases 注册，test/install-check.test.mjs 调用的也是它 —— 所以 node --test test/*.test.mjs 覆盖的就是这 31 条，不存在「回归只活在自检里、门禁看不见」的盲区。2 条真机项读活 profile，默认只提示不计退出码（保证在无 profile 的环境也能跑绿），要当硬门禁就加 --live。

检查项与被覆盖的失效形态见 安装 §4；脚本自身的回归测试见 test/install-check.test.mjs。

运行状态自检

一条命令看清「重启后有没有退回旧毛病」——修完代码最容易踩的坑就是忘了重启，跑的还是旧代码：

node scripts/selfcheck.mjs          # 人类可读；有问题 exit 1，全绿 exit 0
node scripts/selfcheck.mjs --json   # 机器可读
node scripts/selfcheck.mjs --full   # 解全部日志帧（默认只解尾部 2000 帧，快）
node scripts/selfcheck.mjs --started=2026-09-26T18:13:29+08:00   # 覆盖「DSH 进程启动时刻」

--started 只在诊断/测试时用：默认从监听 3080 的进程反查启动时刻，一般不用传。它的用途是把「运行代码是否最新」这条判据摆到可控时间点上——例如副本刚同步完、进程还没重启时，用它复现「需要重启」的结论，或反向证明某次同步确实已被进程加载。

输出示例：

  ✓ 运行副本与仓库源码一致（内容哈希）
      18 个文件哈希全等；改仓库仍需「同步副本 + 重启 DSH」才生效
  ✓ 运行代码是最新的
      DSH 启动 2026/9/26 18:13:29；副本最新写入 2026/9/26 17:02:11 早于进程启动；且副本内容 == 仓库工作树（不看仓库侧 mtime，故同内容重写不误报）

副本写入晚于进程启动时，上面第二条会变成 fail（此时内容可能仍是一致的——进程加载的是写入前那份）：

  ✓ 运行副本与仓库源码一致（内容哈希）
  ✗ 需要重启 DSH —— 副本在进程启动后被写入
      副本最新写入的是 src/plugin-entry.mjs：2026/9/26 19:24:44；而 DSH 进程启动于 2026/9/26 18:13:29 —— 副本晚 71 分钟。
      Node 在 import 期就加载完了模块，所以该进程装的仍是写入前的那份内容；副本内容虽与仓库一致，也必须重启 DSH 才真正生效。

「运行代码是否最新」由两条并存的判据共同回答，两者互不覆盖：①内容哈希——副本内容是否 == 仓库工作树（仓库侧 mtime 不参与，故同内容重写不误报）；②时点——副本里运行时文件（src/、client/、cordis.patch.yml）的最新写入时刻是否晚于进程启动。只查①会漏掉「副本已同步、进程却在同步之前就起来了」，这正是最容易被误判成「已生效」的形态。

零成本：只读本地文件 + 打 /health、/profile 这类纯本地端点，绝不调用 /memory/search 之类会触发 embedding 的接口（那是要花钱的）。只读：不写记忆库、不改任何配置。

检查项见 test/selfcheck.test.mjs。核心判据是「同一轮内 system 长度必须唯一」——新回合首条 header 天然带 change 是正常行为，不是漂移；真正的 bug 特征是长度在一轮内出现多个值（记忆块中途消失）。

AstrBot 侧离线自检（不联网、不写记忆库）：

cd astrbot-plugin
python test_private_handler.py

开发注意事项

1. 不热重载——源码改动必须同步到 profile 的 node_modules 副本并重启 DSH，浏览器端还要硬刷新页面。同步后请核对 SHA256。
2. settings 命名空间注册要内联 ctx.get('settings') + settings.register()，不要导入 installSettingsSection / settingsNamespace 这两个具名导出：上游删除过它们，而缺失的具名导出是模块求值期的 SyntaxError，会让宿主启动失败。没有 settings 服务的旧宿主下应优雅降级。
3. 两半侧字段表必须同步改——src/settings/index.mjs 的 SETTINGS_FIELDS 与 client/client.js 的 FIELDS，漏一边会出现「Host 认这个键、界面画不出来」或反之。
4. 异步上下文不要靠 section.text 同步缓存——assemble() 同步求值 text 之后才跑瀑布，所以同步缓存首轮必空、之后恒错位一轮。要用 system-prompt/assemble 瀑布（见 上下文组装 与 src/context/inject.mjs）。
5. 注册作用域决定可见范围——要只对聊天会话生效，就必须注册在 agent 作用域，不能注册在插件 root ctx。
6. 跨插件不要做值导入——client bundle 的纯净度门禁拒绝跨插件的值导入，协作走 cordis 服务。
7. 装完/改完 profile 先跑 scripts/install-check.mjs——「装上了但没生效」不会有报错，只会静默。改动 src/ 后尤其要跑：C5 会逐字节比对运行副本与仓库源码，专门抓「改完忘了同步 / 忘了重启」。

---

路线图

• 聊天模式 + 长期记忆
• agent 模式隔离会话（全自动双会话）
• 关系图谱 + 可交互蜘蛛网 UI
• 记忆服务（HTTP）与 AstrBot 群聊对接
• 图形化配置（设置侧边栏独立入口）
• 模式自愈（启动自检 + 运行期 reconcile）
• 记忆写入去重（/memory 快速返回 + 异步实体抽取）
• 注入时序收敛（改走 system-prompt/assemble 异步瀑布取真值；section.text 同步求值结构上不可能赶上检索）
• 运行状态自检（scripts/selfcheck.mjs，九项，零成本只读）
• 安装安全流程（scripts/install-check.mjs，八项机检 + --fix 自动修复与失败自动回滚）
• 图谱面板「鹰眼模式」小地图（内容随主视图缩放，作为标准缩略图模式的可选增强）
• 记忆库主干架构的多端一致性加固

---

文档索引

文档	内容
README.md	本文件：安装、配置、架构、开发、排障
CONTRIBUTING.md	贡献指南：四条铁律、上下文注入约束、测试约定
CHANGELOG.md	版本变更记录
SECURITY.md	安全策略与敏感面说明
astrbot-plugin/README.md	AstrBot 插件说明
astrbot-plugin/SYNC.md	AstrBot 插件同步铁律
发布形态与安装流程.md	发布形态设计：发布出去长什么样、用户下载什么、按什么顺序装（含 dsh-notifier 补丁现状与上游演进）

内部文档不随仓库发布。 设计文档（需求规格.md、交接文档.md、记忆库主干架构*.md、astrbot接入方案.md、调研报告-*.md、发布注意事项.md）已由 .gitignore 挡在仓库外——它们含本机路径、会话 ID 等隐私信息。克隆本仓库看不到这些文件是正常的。

发布形态与安装流程.md 不在这个清单里：它经过穷举扫描（密钥字面量 / QQ id / session id / 凭据路径 / 本机绝对路径 / 内部术语 全部 0 命中），不含隐私，是给使用者看的公开文档，因此纳入版本控制。

---

贡献

这是一个个人自用项目，没有正式的贡献流程。如果你基于它做二次开发：

1. 先确认改动落在正确的半侧——Host（src/）还是浏览器（client/）。
2. 新功能请补对应测试，并保持 node test/*.test.mjs 全绿。
3. 提交前检查四条铁律没有被破坏：会话隔离、注册作用域、单一向量模型、源码必须同步到 node_modules 并重启。

---

许可证

MIT