@restregular/dsh-memory 0.4.0 → 0.5.0
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.
- package/README.md +231 -36
- package/lib/client.js +19 -7
- package/lib/inject/apply.js +27 -8
- package/lib/inject/inject.js +75 -3
- package/lib/panel.js +106 -12
- package/lib/provider/apply.js +40 -1
- package/lib/provider/index.js +270 -31
- package/lib/provider/scope.js +338 -0
- package/lib/provider/store.js +56 -9
- package/lib/tools/apply.js +123 -103
- package/lib/tools/index.js +370 -221
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,36 +1,124 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-memory
|
|
2
2
|
|
|
3
|
-
DeepSeek Harness 的本地长期记忆插件 ——
|
|
3
|
+
DeepSeek Harness 的本地长期记忆插件 —— **一个包、一条 Loader entry、四个半边**:JSONL 存储 + 本地向量检索(llama-server,OpenAI 兼容)+ 四个模型工具 + 自动召回注入 + 设置页管理面板。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@restregular/dsh-memory)
|
|
6
|
+
[](./LICENSE)
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
English: Local, durable memory for DeepSeek Harness — one npm package, one loader entry: a JSONL store, local vector recall through llama-server, four model-facing tools, automatic recall injection, and a management panel in the settings page.
|
|
9
|
+
|
|
10
|
+
## 它给你什么
|
|
11
|
+
|
|
12
|
+
| 能力 | 说明 |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| **落盘存储** | 每条记忆一行 JSONL,按 scope 分文件(会话 / project / global / 自定义),同 scope 内按内容去重;写入前过凭据扫描 |
|
|
15
|
+
| **作用域** | 默认写进**当前会话**;读默认合并「会话 + 项目 + global」。也能写 `global`、当前项目,或任意自定义名(首次写入自动建) |
|
|
16
|
+
| **双通道检索** | 词法(IDF + CJK bigram)**+** 向量(llama-server 的 `/v1/embeddings`)。向量缺席时自动降级为纯词法,**不报错、不阻塞** |
|
|
17
|
+
| **自动召回** | `agent/pre-step` 注入相关记忆(可关、有 token 预算、按 topK 截断,范围同为会话+项目+global) |
|
|
18
|
+
| **四个工具** | `memory_save` / `memory_search` / `memory_list` / `memory_forget` |
|
|
19
|
+
| **管理面板** | 设置页「记忆」:浏览 / 搜索 / 编辑 / 删除、向量服务启停、模型与硬件、维护(卸载 / 清空) |
|
|
20
|
+
| **向量后端一键装** | 面板里选模型 → 下 llama.cpp 运行时 + 模型 → 托管 `llama-server` 进程;内置 8 个模型 + 硬件推荐 + 自定义 GGUF |
|
|
21
|
+
|
|
22
|
+
## 安装 / Install
|
|
8
23
|
|
|
9
24
|
```bash
|
|
10
25
|
pnpm add @restregular/dsh-memory
|
|
26
|
+
# 或 npm i @restregular/dsh-memory
|
|
11
27
|
```
|
|
12
28
|
|
|
13
|
-
|
|
29
|
+
装进任意 DSH profile(桌面端 `~/.dsh/profiles/desktop`,Web 端 `~/.dsh/profiles/web`)。包自带 `cordis.patch.yml`,装好后自动注册**唯一一条** entry:
|
|
30
|
+
|
|
31
|
+
```yaml
|
|
32
|
+
- insert:
|
|
33
|
+
- id: dsh-memory
|
|
34
|
+
name: '@restregular/dsh-memory'
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**不写任何配置就能用**:检索退化为词法,一个网络请求都不发。
|
|
38
|
+
|
|
39
|
+
### 为什么是一个包
|
|
14
40
|
|
|
15
|
-
|
|
41
|
+
宿主的 `dsh-client-modules` 只在「某条**活的** Loader entry 能解析到包名」时才为该包提供 client bundle,并且 `reconcilePackage` 要求**一个包名只有一个解析源**(否则抛 `resolves from multiple active Loader sources` → 客户端图组合失败 → 桌面端 fail-loud 起不来)。所以「一个包 + 一个面板」的稳定形态只有一个:**一个包名、一条 entry、两侧都在**(与 `dshmarket` 同形)。
|
|
42
|
+
|
|
43
|
+
早期把 provider / 工具 / 注入 / 面板拆成两个包、四条 entry;现在合并为一条 entry,由 `lib/index.js` 组合四个半边,每个半边各自 try/catch —— **任何一半失败都只记一行日志,绝不让 DSH 启动失败**。
|
|
44
|
+
|
|
45
|
+
| 半边 | 作用 |
|
|
16
46
|
| --- | --- |
|
|
17
|
-
| provider | 提供 `memory` 服务:JSONL
|
|
18
|
-
| tools | 注册 `memory_save` / `memory_search` / `memory_list` / `memory_forget` |
|
|
19
|
-
| inject | 在 `agent/pre-step` 注入召回块(
|
|
20
|
-
| panel |
|
|
47
|
+
| `lib/provider` | 提供 `memory` 服务:JSONL 存储、双通道检索、向量回填、向量后端生命周期与一键安装 |
|
|
48
|
+
| `lib/tools` | 注册 `memory_save` / `memory_search` / `memory_list` / `memory_forget` |
|
|
49
|
+
| `lib/inject` | 在 `agent/pre-step` 注入召回块(可关) |
|
|
50
|
+
| `lib/panel` | `/memory/api` 管理接口(含同源 / 登录围栏) |
|
|
51
|
+
| `lib/client.js` | 设置页「记忆」区块(注册 id == 包名) |
|
|
52
|
+
|
|
53
|
+
## 快速开始
|
|
54
|
+
|
|
55
|
+
**1. 存一条记忆**(模型自己会调,你也可以在对话里要求):
|
|
21
56
|
|
|
22
|
-
|
|
57
|
+
```jsonc
|
|
58
|
+
memory_save({
|
|
59
|
+
"content": "本仓库用 pnpm 11 安装依赖,PATH 上的 pnpm 10 会踩 ERR_PNPM_UNEXPECTED_STORE", // 必填,自洽的一句话
|
|
60
|
+
"scope": "session", // 可省略 = 当前会话;global(所有项目) / project(当前工作区) / 任意自定义名
|
|
61
|
+
"kind": "fact", // fact / decision / preference / procedure / note
|
|
62
|
+
"tags": ["pnpm", "toolchain"],
|
|
63
|
+
"importance": 0.8 // 0~1
|
|
64
|
+
})
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
作用域怎么选:
|
|
68
|
+
|
|
69
|
+
| 写法 | 含义 |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| 省略 / `session` | **当前会话**(子代理共享父会话;拿不到会话信息时回退到当前项目) |
|
|
72
|
+
| `project` | 当前工作区(键是 `project:<cwd>`) |
|
|
73
|
+
| `global` | 所有项目共享 |
|
|
74
|
+
| `handbook`、`项目笔记` … | **自定义作用域**:任意名字,首次 `memory_save` 时自动创建 |
|
|
75
|
+
| `session:<id>` / `project:<path>` | 显式钉住某个会话 / 某个工作区 |
|
|
76
|
+
| `all` / `*` | **只在读取时可用**:跨所有已发现的作用域;写入会明确报错 |
|
|
23
77
|
|
|
24
|
-
|
|
78
|
+
**2. 检索**:`memory_search({ query: "pnpm 装依赖", topK: 5 })` —— 省略 `scope` = 会话 + 项目 + global 合并(按来源标注、按 id 去重);`scope: "all"` 查所有作用域;写具体名字则只查那一个。
|
|
79
|
+
**3. 列出 / 忘记**:`memory_list({ limit: 20 })`(默认只列当前会话,末尾附作用域清单 + 记录数)、`memory_forget({ id })` 或 `memory_forget({ query, scope })`(按内容删默认**只作用于当前会话**,防止跨作用域误删)。
|
|
25
80
|
|
|
26
|
-
|
|
81
|
+
**4. 打开面板**:设置页 →「记忆」。面板里能做的事:
|
|
82
|
+
|
|
83
|
+
- 顶部统计(记忆数 / 作用域数 / 待嵌入向量数)与记录列表(搜索、按作用域筛选、展开编辑、删除)
|
|
84
|
+
- 作用域下拉**动态枚举实际存在的作用域**:`global` 显示「全局」、project 显示 cwd、会话 scope 显示会话标题(拿不到就显示「会话 <id 前 8 位>」)、自定义 scope 显示原名
|
|
85
|
+
- 「向量服务」:状态、地址、启停开关、**模型与硬件**(见下)、维护(卸载向量服务 / 清空记忆数据,两步确认)
|
|
86
|
+
|
|
87
|
+
面板后端在 `/memory/api`,全部路由:`GET /status`、`GET /records`、`POST /update`、`POST /delete`、`GET /embed/status`、`POST /embed/start|stop`、`GET /embed/model`、`POST /embed/model/refresh|install|install/cancel|uninstall`、`POST /data/wipe`。
|
|
88
|
+
|
|
89
|
+
## 数据与文件布局
|
|
90
|
+
|
|
91
|
+
| 路径 | 内容 |
|
|
92
|
+
| --- | --- |
|
|
93
|
+
| `<storeDir>/global.jsonl` | global 作用域的记忆,一行一条 |
|
|
94
|
+
| `<storeDir>/projects/<sha1(scope)>.jsonl` | 其它作用域(会话 / 项目 / 自定义)各一个文件;文件名是 scope 键的 SHA-1,所以名字里带路径分隔符也不可能穿越 |
|
|
95
|
+
| `<storeDir>/projects/<sha1(scope)>.vec` | 向量边车。首行是身份头 `#<model>\t<dims>`,后面每行 `id\t<base64 向量>` |
|
|
96
|
+
| `<installRoot>/llamacpp/` | llama-server 运行时(exe + 依赖 dll + `llama-server.log`) |
|
|
97
|
+
| `<installRoot>/models/` | 下载的 GGUF 模型 |
|
|
98
|
+
| `<installRoot>/selected-model.json` | 面板里选过哪一档(比配置优先级低) |
|
|
99
|
+
|
|
100
|
+
`storeDir` 默认 `.dsh-memory`(相对启动目录),**建议显式配一个绝对路径**。文件是**首次写入才创建**(读一个不存在的 scope 只会得到空结果,不会造出空文件);`projects/` 目录在插件启动时就建好。
|
|
101
|
+
|
|
102
|
+
scope 键的三种形态:`global`、`project:<cwd>`、`session:<会话 id>`,其余都是自定义名(小写折叠、内部空白折成一个空格、最长 64 字符,禁止 `:`、路径分隔符、控制字符、`..` 与保留名 `global/project/session/all`)。**0.5.0 没有任何数据迁移**:旧的 `project:<cwd>` 文件继续原样读写。
|
|
103
|
+
|
|
104
|
+
`installRoot` 默认 `~/.dsh/memory-vector`;显式配了 `storeDir` 时取**它的父目录**(所以手写的 `<root>/llamacpp` + `<root>/models` 布局会被直接认出来)。
|
|
105
|
+
|
|
106
|
+
> **换模型 = 向量作废重建**。`.vec` 的身份头记录 `model` 与 `dims`,对不上就整份丢弃并重新嵌入;重建期间检索暂时只用词法。面板会在换之前告诉你涉及多少条记忆。
|
|
107
|
+
|
|
108
|
+
## 配置 / Configuration
|
|
109
|
+
|
|
110
|
+
provider 的配置在顶层,工具 / 注入 / 面板各占一个小节(合并前它们各是独立 entry 的 `config`):
|
|
27
111
|
|
|
28
112
|
```yaml
|
|
29
113
|
- id: dsh-memory
|
|
30
114
|
name: '@restregular/dsh-memory'
|
|
31
115
|
config:
|
|
32
116
|
storeDir: '~/.dsh/memory-store'
|
|
33
|
-
scopes:
|
|
117
|
+
scopes:
|
|
118
|
+
global: true
|
|
119
|
+
project: true
|
|
120
|
+
session: true # 会话作用域(默认开)
|
|
121
|
+
custom: { enabled: true, max: 200 } # 自定义作用域:开关 + 数量上限(只数自定义的)
|
|
34
122
|
retrieval:
|
|
35
123
|
topK: 5
|
|
36
124
|
recallN: 30
|
|
@@ -39,44 +127,151 @@ pnpm add @restregular/dsh-memory
|
|
|
39
127
|
endpoint: 'http://127.0.0.1:8078/v1/embeddings'
|
|
40
128
|
model: bge-m3
|
|
41
129
|
dims: 1024
|
|
42
|
-
timeoutMs: 300 #
|
|
130
|
+
timeoutMs: 300 # 交互检索(短查询)预算,要紧
|
|
43
131
|
writeTimeoutMs: 10000 # 保存时嵌整条记录
|
|
44
132
|
backfillTimeoutMs: 30000 # 批量回填
|
|
133
|
+
backfillMaxChars: 8000
|
|
134
|
+
spawn: # 让插件托管 llama-server 进程(opt-in)
|
|
135
|
+
enabled: true
|
|
136
|
+
exe: '/path/to/llama-server.exe'
|
|
137
|
+
model: '/path/to/bge-m3-Q4_K_M.gguf'
|
|
138
|
+
cwd: '/path/to/llamacpp' # 该目录须含 llama-server-impl.dll
|
|
139
|
+
logFile: '/path/to/llama-server.log'
|
|
45
140
|
llm: { enabled: false } # LLM 重排(可选)
|
|
46
141
|
limits: { maxRecordsPerScope: 2000, maxRecordChars: 4000 }
|
|
47
142
|
secrets: { enabled: true, mode: refuse }
|
|
48
|
-
tools: { defaultScope:
|
|
49
|
-
inject: { enabled: true, tokenBudget: 500, topK: 5 }
|
|
143
|
+
tools: { defaultScope: session } # session(新默认)/ project / global;projectScope 默认 project:<会话 cwd>
|
|
144
|
+
inject: { enabled: true, tokenBudget: 500, topK: 5 } # 可加 extraScopes: ['handbook']
|
|
50
145
|
panel: { route: '/memory/api' }
|
|
51
146
|
```
|
|
52
147
|
|
|
53
|
-
|
|
148
|
+
- **`tools.defaultScope`** 决定*省略 scope 时写到哪*:`session`(0.5.0 起的默认)、`project`、`global`。会话写不进去(宿主没给会话信息、或 `scopes.session: false`)时**自动回退到当前项目**,不报错。
|
|
149
|
+
- **`scopes.custom.max`** 只统计自定义作用域(已发现 + 已加载去重);到上限后 `memory_save` 新建会被拒并提示可复用的名字(`SCOPE_LIMIT`),写已有作用域不受限。会话/项目/global 既不计入也不受限。
|
|
150
|
+
- **读与写的默认是一致的**:写进会话的东西,`memory_search` 默认就能读回来(合并会话 + 项目 + global,按 id 去重,同分时 session > project > 自定义 > global)。想只看某一个就显式给 `scope`。
|
|
151
|
+
- 旧配置(只有 `scopes: { global: true, project: true }`、`tools.defaultScope: project`)照常工作 —— 不写新字段就是新默认值(`session: true`、`custom: { enabled: true, max: 200 }`),想保持 0.4.x 的老行为就显式写 `tools.defaultScope: project`。
|
|
152
|
+
|
|
153
|
+
向量检索是**按配置启用**的:写了 `endpoint`、配了 `spawn`、或面板里装了本地后端才会碰网络,否则一个请求都不发,检索自动降级为纯词法(IDF + CJK bigram)。不需要自动召回就 `inject.enabled: false`。
|
|
154
|
+
|
|
155
|
+
`spawn.enabled: true` 时:应用启动后台拉起向量服务、退出时自动关闭;带 PID 文件的遗留实例会被接管,没有 PID 文件的外部实例不接管。
|
|
156
|
+
|
|
157
|
+
### 模型与硬件
|
|
158
|
+
|
|
159
|
+
面板「记忆 → 向量服务」里有两行状态气泡 + 一块折叠区:
|
|
160
|
+
|
|
161
|
+
```
|
|
162
|
+
本机配置:[12 核][14GB 内存][显卡 …][磁盘剩余 9GB] [重新检测硬件]
|
|
163
|
+
当前模型:[Qwen3-Embedding-0.6B][Q8_0][1024 维][last][cpu] [下载并安装]
|
|
164
|
+
▸ 模型与硬件
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
- **本机配置 / 当前模型**两行是**标签气泡**,超宽横向滚动(不换行、不显示滚动条);本机配置在**面板一出现**就取一次(服务端对硬件探测有 10 分钟缓存,通常只是读缓存)。
|
|
168
|
+
- **内置清单 8 个模型**,下载源与体积都实测过:BGE-M3(Q4_K_M / Q8_0)、Qwen3-Embedding 0.6B / 4B / 8B、Nomic Embed v1.5、BGE 中文 small / base / large。每个模型自带 `dims` 与 `pooling`,**选它就自动配对** —— 维度写错会让检索静默退化成词法,这是最容易踩的坑。
|
|
169
|
+
- **按本机推荐**:探测 CPU 核数 / 内存 / 磁盘剩余 / 显卡与显存,推荐那一档在列表里带「推荐」气泡并默认选中。规则:质量优先;能整块放进显存就用 GPU;CPU 上重罚 4B/8B;中文环境优先中文 / 多语言;显存 < 4GB 的核显不算可用显卡(实测:共享显存的核显并不比多核 CPU 快)。
|
|
170
|
+
- **运行时风味** `cpu` / `vulkan` / `cuda` / `metal` / `auto`:Vulkan 自包含(驱动自带即可);**CUDA 会把 cudart 伴随包一起下**(llama.cpp 把 cuBLAS 拆在另一个资产里,不配对就起不来);所选风味找不到时退回 CPU 并在面板里说明。
|
|
171
|
+
- **自定义 GGUF**:填 URL + 维度即可装清单之外的模型(`pooling` 默认交给 GGUF 元数据决定);需要前缀的模型(Nomic 的 `search_query:` / `search_document:`)会自动带上。
|
|
172
|
+
- **一次只保留一份**:已经装了运行时与某个模型时**不能再装第二个** —— 按钮变成「需先卸载」并置灰,换模型要先去「维护」里卸载向量服务(否则 `<root>` 下会堆好几份模型,而配置只能指向一份,"现在跑的是哪个"就说不清了)。按钮四态:下载并安装 / 下载中… / 已安装 / 需先卸载。
|
|
173
|
+
- **选择会被记住**:写在 `<installRoot>/selected-model.json`,重启后仍生效;配置里写了 `preset` / `customModel` 时**配置优先**。
|
|
174
|
+
|
|
175
|
+
```yaml
|
|
176
|
+
retrieval:
|
|
177
|
+
vector:
|
|
178
|
+
preset: 'qwen3-embedding-0.6b' # 清单 id(配合 variant 选量化档)
|
|
179
|
+
variant: 'q8_0'
|
|
180
|
+
flavor: 'auto' # auto = 按探测到的硬件选;也可写死 cpu/vulkan/cuda/metal
|
|
181
|
+
# customModel: { url: 'https://…/model.gguf', dims: 1024, pooling: 'auto' }
|
|
182
|
+
# 覆盖项:dims / pooling / gpuLayers
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## 安全 / Security
|
|
186
|
+
|
|
187
|
+
- `/memory/api` 的**每条**路由都先过 `refuseRequest`:宿主 `connection.requestRejection`(Host/Origin 围栏 + 浏览器登录)可用时以它为准,围栏自己抛错一律 403(失败关闭);旧宿主没有该服务时退化为「只认 loopback 权威 + 同源」。原因:注册在裸 `webServer` 上的路由**不在**宿主 `/api` 围栏与浏览器登录之后,而这里的接口能读、改、删、清空全部记忆。
|
|
188
|
+
- 记忆内容写入前过凭据扫描(`secrets.mode: refuse | redact`),默认拒绝。
|
|
189
|
+
- 清空记忆是两步确认 + 接口要求显式 `confirm: "delete"`。
|
|
190
|
+
|
|
191
|
+
## 卸载 / Uninstall
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
pnpm remove @restregular/dsh-memory # 再从 profile 的 patch 里删掉那条 entry
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
**卸载插件不会移除已配置的向量服务与记忆文件** —— 它们不在 node_modules 里,而是在 `<storeDir>` 与 `<installRoot>`。要清掉,先打开面板「记忆 → 维护」:
|
|
198
|
+
|
|
199
|
+
- **卸载向量服务**:删掉运行时与模型(两步确认,显示将释放多少空间);记忆数据保留。
|
|
200
|
+
- **清空记忆数据**:删掉全部 JSONL 与向量边车(两步确认,不可恢复)。
|
|
201
|
+
|
|
202
|
+
插件被卸掉后面板就打不开了,所以这件事只能在卸载**之前**做。想手动清理,直接删上面那两个目录即可。
|
|
203
|
+
|
|
204
|
+
## 构建与测试 / Build & test
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
npm test # node --experimental-strip-types --test source/*/test/*.test.ts
|
|
208
|
+
npm run build # source/ → packages/dsh-memory(顺带跑产物契约检查)
|
|
209
|
+
npm run verify # 构建到 .verify/,不落 packages/(CI 或改动后自检)
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
构建用 Node 内置的类型剥离(`stripTypeScriptTypes`,无额外工具链),相对 `.ts` 说明符改写为 `.js`,跨半边相对 import 重映射,每个产出文件 `node --check`。
|
|
213
|
+
|
|
214
|
+
产物契约检查(错了会**静默失败**的几处,所以做成会失败的检查):
|
|
215
|
+
|
|
216
|
+
1. patch **恰好一行** insert,且 `name` 就是包名;
|
|
217
|
+
2. `package.json` 同时声明 `dsh.bundle.patch` 与 `dsh.client.platform: web`,并导出 `./client`;
|
|
218
|
+
3. `lib/client.js` 的 `__ModuleLoader__.load({ id })` 等于包名;
|
|
219
|
+
4. 入口里四条半边的相对 import 都在(改写没生效时,只有装到用户机器上才会 `Cannot find module`)。
|
|
220
|
+
|
|
221
|
+
可选的真实加载验证(证明产物在没有 TS 支持的普通 node 里能跑):
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
node tools/build-single-package.mjs --scope @restregular --version 0.4.0 \
|
|
225
|
+
--host-modules <一个 @deepseek-ai 目录> # 或设 DSH_HOST_MODULES
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
## 仓库结构 / Layout
|
|
229
|
+
|
|
230
|
+
```
|
|
231
|
+
source/memory-plugin/ 单入口:组合四个半边(唯一一条 entry 的实现)
|
|
232
|
+
source/memory-local/ provider:存储 / 检索 / 向量后端 / 一键安装 / 模型清单与硬件推荐
|
|
233
|
+
source/tool-memory/ 四个模型工具
|
|
234
|
+
source/memory-inject/ 召回注入
|
|
235
|
+
source/memory-panel/ 面板:lib/index.js(服务端)+ lib/client.js(客户端 bundle)
|
|
236
|
+
packages/dsh-memory/ 构建产物 → 发布为 @restregular/dsh-memory(与 npm 上的包逐字节一致)
|
|
237
|
+
tools/build-single-package.mjs 构建(产物契约检查 + 可选加载验证)
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
## 测试 / Tests
|
|
54
241
|
|
|
55
|
-
|
|
242
|
+
`npm test` 覆盖存储 / 检索打分 / 边车身份 / 回填重试 / 安装器(含真实发行包解压)/ 卸载边界 / 模型清单与推荐规则 / 硬件解析 / 面板渲染冒烟 / 围栏判定 / 产物契约。测试用宿主的 DSH 包作为解析依赖(`@deepseek-ai/cordis`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-llm`),它们不随本仓库分发。
|
|
56
243
|
|
|
57
|
-
|
|
244
|
+
## 常见问题
|
|
58
245
|
|
|
59
|
-
|
|
246
|
+
**向量服务起不来**
|
|
247
|
+
看 `<installRoot>/llamacpp/llama-server.log`。三个常见原因:端口被占(换 `spawn` 的端口或停掉占用者)、`cwd` 里缺 `llama-server-impl.dll`(llama.cpp 的 Windows 包需要同目录的依赖)、模型与运行时风味不匹配(比如 GPU 风味但没驱动)。
|
|
60
248
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
3. **自己管进程**:配 `retrieval.vector.spawn`(exe / model / cwd / logFile),由插件托管启动与关闭。
|
|
249
|
+
**检索结果很差 / 全是词法命中**
|
|
250
|
+
先看面板「当前模型」那行的**维度**是否与模型一致,再看 `.vec` 身份头。维度或 pooling 写错不会报错,只会让向量通道悄悄失效。另外 `minScore` 默认 0.5 是按 BGE 的 CLS 噪声底定的,**换模型后可能需要微调**(太少就调低,太杂就调高)。
|
|
64
251
|
|
|
65
|
-
|
|
252
|
+
**下载中断 / 装到一半**
|
|
253
|
+
安装器先写 `.part` 再 rename,所以磁盘上不会留半成品;面板会显示「重试下载」。
|
|
66
254
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
- 清空记忆需要两步确认,且接口要求显式 `confirm: "delete"`。
|
|
255
|
+
**想换模型**
|
|
256
|
+
0.4.0 起必须先「维护 → 卸载向量服务」再装(理由见「模型与硬件」)。换完现有记忆会重新嵌入。
|
|
70
257
|
|
|
71
|
-
|
|
258
|
+
**面板里看不到「记忆」**
|
|
259
|
+
包名与 Loader entry 必须一一对应(见「为什么是一个包」)。检查 profile 的 patch 里是否只有一条 `@restregular/dsh-memory`,以及 profile 是否真的装上了这个依赖(`ls node_modules/@restregular/dsh-memory`)。
|
|
72
260
|
|
|
73
|
-
|
|
261
|
+
## 版本
|
|
74
262
|
|
|
75
|
-
|
|
263
|
+
- **0.5.0** —— 作用域重构:
|
|
264
|
+
- **默认作用域 = 当前会话**:`memory_save` 省略 `scope` 时写进 `session:<会话 id>`(子代理共享父会话;拿不到会话信息或 `scopes.session: false` 时回退当前项目,不报错)。
|
|
265
|
+
- **读写默认一致**:0.4.x 的写路径默认是 `project:<cwd>`、而 provider 的读路径默认是 `global` —— 写进去的记忆默认检索不到。现在两边都是「会话 + 项目 + global」合并去重(同分时 session > project > 自定义 > global)。
|
|
266
|
+
- **自定义作用域**:`scope` 可以填任意名字(如 `handbook`、`项目笔记`),首次写入时自动创建;新增 `scopes.custom.enabled` / `scopes.custom.max`(默认 200,只统计自定义的)与 `SCOPE_LIMIT` / `SCOPE_INVALID` 明确报错 —— **取消了"认不出的 scope 静默回退默认值"**。
|
|
267
|
+
- **`scope: 'all'`**(或 `*`)跨所有已发现作用域读取;写入路径明确报错。`memory_forget({query})` 默认只作用于当前会话,`all` + query 直接拒绝,防批量误删。
|
|
268
|
+
- **读路径不再创建文件**:`memory_search` / `memory_list` / `memory_forget` / 面板对不存在的 scope 返回空结果;只有 `memory_save` 才会建文件。
|
|
269
|
+
- 面板:作用域下拉与「作用域数」动态枚举现存作用域,会话 scope 显示会话标题(拿不到就「会话 <id 前 8 位>」)。
|
|
270
|
+
- **不迁移、不重命名任何文件**:旧的 `global.jsonl` 与 `projects/<sha1>.jsonl` 仍按原路径原样读写;`tools.defaultScope` 保留,新增取值 `session` 并作为默认。
|
|
271
|
+
- 要完全保持 0.4.x 的写行为:`tools.defaultScope: project`。
|
|
272
|
+
- **0.4.0** —— 单包合并里程碑:面板并入主包(一条 entry)、模型清单与硬件推荐、自定义 GGUF、运行时风味、"一次只保留一份"。
|
|
273
|
+
- **0.3.x 及更早** —— 拆分结构(provider / tools / inject / panel 各自独立 entry)。从 0.3.x 升级请按上面的单行 entry 重新挂载,并把旧的多条 entry 删掉。
|
|
76
274
|
|
|
77
|
-
##
|
|
275
|
+
## License
|
|
78
276
|
|
|
79
|
-
|
|
80
|
-
- 作用域:`global` 与 `project:<cwd>`。
|
|
81
|
-
- 任何异常都被吞掉并记日志,绝不让 DSH 启动失败。
|
|
82
|
-
- License: MIT
|
|
277
|
+
MIT
|
package/lib/client.js
CHANGED
|
@@ -156,11 +156,20 @@ window.__ModuleLoader__.load({
|
|
|
156
156
|
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`
|
|
157
157
|
}
|
|
158
158
|
|
|
159
|
-
|
|
160
|
-
|
|
159
|
+
/**
|
|
160
|
+
* scope 键 → 展示标签。优先用 /status 返回的 `label`(服务端能查会话标题、能解析
|
|
161
|
+
* project 的 cwd);服务端没给(旧 provider / 还没加载到)时用本地回退。
|
|
162
|
+
*/
|
|
163
|
+
function scopeLabel(scope, labels) {
|
|
164
|
+
const mapped = labels && labels[scope]
|
|
165
|
+
if (typeof mapped === 'string' && mapped.length > 0) return mapped
|
|
166
|
+
if (scope === 'global') return '全局'
|
|
167
|
+
if (scope.startsWith('project:')) return scope.slice(8)
|
|
168
|
+
if (scope.startsWith('session:')) return `会话 ${scope.slice(8, 16)}`
|
|
169
|
+
return scope
|
|
161
170
|
}
|
|
162
171
|
|
|
163
|
-
function RecordCard({ rec, vectorOn, onSaved, onDeleted }) {
|
|
172
|
+
function RecordCard({ rec, vectorOn, labels, onSaved, onDeleted }) {
|
|
164
173
|
// collapsed by default: the list stays scannable, full text on demand
|
|
165
174
|
const [expanded, setExpanded] = React.useState(false)
|
|
166
175
|
const [editing, setEditing] = React.useState(false)
|
|
@@ -215,7 +224,7 @@ window.__ModuleLoader__.load({
|
|
|
215
224
|
},
|
|
216
225
|
},
|
|
217
226
|
h('span', { className: open ? 'chev open' : 'chev' }, '▶'),
|
|
218
|
-
h('span', { className: 'badge scope', title: rec.scope }, scopeLabel(rec.scope)),
|
|
227
|
+
h('span', { className: 'badge scope', title: rec.scope }, scopeLabel(rec.scope, labels)),
|
|
219
228
|
h('span', { className: 'badge' }, rec.kind),
|
|
220
229
|
rec.supersedes ? h('span', { className: 'badge', title: `修正 #${rec.supersedes}` }, '修正') : null,
|
|
221
230
|
// 只在"待嵌入"时提示:已嵌入是常态,向量没启用时这条也没有行动价值。
|
|
@@ -648,6 +657,9 @@ window.__ModuleLoader__.load({
|
|
|
648
657
|
|
|
649
658
|
const total = scopes.reduce((n, s) => n + s.records, 0)
|
|
650
659
|
const pending = scopes.reduce((n, s) => n + s.pendingEmbeds, 0)
|
|
660
|
+
// 服务端 /status 给的 scope → label 映射(会话标题、project 的 cwd 只有服务端知道)
|
|
661
|
+
const labels = {}
|
|
662
|
+
for (const s of scopes) if (s && s.scope && typeof s.label === 'string') labels[s.scope] = s.label
|
|
651
663
|
|
|
652
664
|
// 向量卡片的状态判定。provider 给的 mode 决定"该不该有启停开关":
|
|
653
665
|
// off 没配置任何后端 → 不给开关,模型与安装入口都在「模型与硬件」里
|
|
@@ -795,11 +807,11 @@ window.__ModuleLoader__.load({
|
|
|
795
807
|
onChange: (e) => setQ(e.target.value),
|
|
796
808
|
onKeyDown: (e) => { if (e.key === 'Enter') load(q, scopeFilter) },
|
|
797
809
|
}),
|
|
798
|
-
// 作用域也用同一个自绘下拉(与模型/运行时统一)
|
|
810
|
+
// 作用域也用同一个自绘下拉(与模型/运行时统一);标签优先用服务端给的 label
|
|
799
811
|
h(Dropdown, {
|
|
800
812
|
items: [
|
|
801
813
|
{ value: '', label: '全部作用域' },
|
|
802
|
-
...scopes.map((s) => ({ value: s.scope, label: scopeLabel(s.scope) })),
|
|
814
|
+
...scopes.map((s) => ({ value: s.scope, label: s.label || scopeLabel(s.scope) })),
|
|
803
815
|
],
|
|
804
816
|
value: scopeFilter,
|
|
805
817
|
disabled: loading,
|
|
@@ -812,7 +824,7 @@ window.__ModuleLoader__.load({
|
|
|
812
824
|
!loading && !error && records.length === 0
|
|
813
825
|
? h('div', { className: 'empty' }, filtering ? '没有匹配的记忆' : '还没有记忆')
|
|
814
826
|
: h('div', { className: 'list' },
|
|
815
|
-
records.map((rec) => h(RecordCard, { key: rec.id, rec, vectorOn: configured && vectorEnabled, onSaved: () => load(), onDeleted: () => load() }))),
|
|
827
|
+
records.map((rec) => h(RecordCard, { key: rec.id, rec, vectorOn: configured && vectorEnabled, labels: labels, onSaved: () => load(), onDeleted: () => load() }))),
|
|
816
828
|
)
|
|
817
829
|
}
|
|
818
830
|
|
package/lib/inject/apply.js
CHANGED
|
@@ -14,11 +14,18 @@
|
|
|
14
14
|
*/
|
|
15
15
|
|
|
16
16
|
import { createUserMessage } from '@deepseek-ai/dsh-llm'
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
import {
|
|
18
|
+
MemoryInjector,
|
|
19
|
+
defaultInjectConfig,
|
|
20
|
+
normalizeExtraScopes,
|
|
21
|
+
resolveInjectScopes,
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
} from './inject.js'
|
|
19
26
|
|
|
20
27
|
|
|
21
|
-
|
|
28
|
+
|
|
22
29
|
|
|
23
30
|
|
|
24
31
|
|
|
@@ -30,14 +37,22 @@ export function apply(ctx , config = {}) {
|
|
|
30
37
|
tokenBudget: config.tokenBudget ?? defaultInjectConfig.tokenBudget,
|
|
31
38
|
topK: config.topK ?? defaultInjectConfig.topK,
|
|
32
39
|
}
|
|
40
|
+
const extraScopes = normalizeExtraScopes(config.extraScopes ?? [])
|
|
41
|
+
const readScopesFor = (memory , agent ) =>
|
|
42
|
+
resolveInjectScopes(memory, agent, extraScopes, ctx.get?.('sessions') )
|
|
33
43
|
|
|
34
44
|
// One injector per activation: its repeat-suppression state must live across
|
|
35
45
|
// the steps of a turn (a per-step instance would re-inject every step).
|
|
36
46
|
const injector = new MemoryInjector(
|
|
37
|
-
async (query, signal) => {
|
|
38
|
-
const memory = ctx.get('memory')
|
|
47
|
+
async (query, signal, scopes) => {
|
|
48
|
+
const memory = ctx.get('memory')
|
|
39
49
|
if (!memory?.search) return []
|
|
40
|
-
return memory.search({
|
|
50
|
+
return memory.search({
|
|
51
|
+
text: query,
|
|
52
|
+
signal,
|
|
53
|
+
topK: cfg.topK,
|
|
54
|
+
...(scopes !== undefined ? { scopes: [...scopes] } : {}),
|
|
55
|
+
})
|
|
41
56
|
},
|
|
42
57
|
cfg,
|
|
43
58
|
)
|
|
@@ -48,10 +63,14 @@ export function apply(ctx , config = {}) {
|
|
|
48
63
|
// A rejected step must pass through untouched — never rebuild the decision.
|
|
49
64
|
if (!decision || decision.kind === 'reject' || input.signal?.aborted) return decision
|
|
50
65
|
// optional capability: absence (or partial load) → pass through untouched
|
|
51
|
-
|
|
66
|
+
const memory = ctx.get('memory')
|
|
67
|
+
if (!memory) return decision
|
|
52
68
|
|
|
69
|
+
// 会话上下文只在 pre-step 里拿得到:交给 search 的 `scopes`,与 memory_search 的
|
|
70
|
+
// 默认合并集合用同一套解析(provider 的 resolveReadScopes)。
|
|
71
|
+
const scopes = readScopesFor(memory, (input ).agent)
|
|
53
72
|
const text = await injector.maybeInject(
|
|
54
|
-
{ messages: input.messages , signal: input.signal },
|
|
73
|
+
{ messages: input.messages , signal: input.signal, ...(scopes !== undefined ? { scopes } : {}) },
|
|
55
74
|
{ messages: decision.messages },
|
|
56
75
|
)
|
|
57
76
|
if (!text) return decision
|
package/lib/inject/inject.js
CHANGED
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
*/
|
|
8
8
|
|
|
9
9
|
import { estimateTokens } from '../provider/rerank.js'
|
|
10
|
+
import { normalizeScopeInput } from '../provider/scope.js'
|
|
10
11
|
|
|
11
12
|
|
|
12
13
|
|
|
@@ -14,6 +15,11 @@ import { estimateTokens } from '../provider/rerank.js'
|
|
|
14
15
|
|
|
15
16
|
|
|
16
17
|
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
|
|
17
23
|
|
|
18
24
|
|
|
19
25
|
export const defaultInjectConfig = {
|
|
@@ -22,6 +28,66 @@ export const defaultInjectConfig = {
|
|
|
22
28
|
topK: 5,
|
|
23
29
|
}
|
|
24
30
|
|
|
31
|
+
/** 召回注入能用到的那部分 provider 能力。 */
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
/** 宿主里"按会话 id 找 live session"的那一小部分能力(拿不到就不做父会话召回)。 */
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* 把 config.extraScopes 规范化成 scope 键列表;非法项忽略并记一行日志
|
|
44
|
+
* (配置写错不该让整个注入半边失效)。
|
|
45
|
+
*/
|
|
46
|
+
export function normalizeExtraScopes(raw , warn = console.warn) {
|
|
47
|
+
const out = []
|
|
48
|
+
for (const item of raw) {
|
|
49
|
+
const normalized = normalizeScopeInput(item)
|
|
50
|
+
if (!normalized.ok) {
|
|
51
|
+
warn(`[dsh-memory-inject] 忽略非法的 inject.extraScopes 项 ${JSON.stringify(item)}: ${normalized.message}`)
|
|
52
|
+
continue
|
|
53
|
+
}
|
|
54
|
+
if (normalized.scope !== undefined && !out.includes(normalized.scope)) out.push(normalized.scope)
|
|
55
|
+
}
|
|
56
|
+
return out
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* 无显式 scope 时的召回范围:当前会话 + 当前项目 + global(provider 解析)
|
|
61
|
+
* + inject.extraScopes + 父会话(fork 时,只读召回)。
|
|
62
|
+
* 任何一步拿不到都只降级,绝不抛(注入路径抛错会打断整个 agent 循环)。
|
|
63
|
+
*/
|
|
64
|
+
export function resolveInjectScopes(
|
|
65
|
+
memory ,
|
|
66
|
+
agent ,
|
|
67
|
+
extraScopes ,
|
|
68
|
+
sessions ,
|
|
69
|
+
) {
|
|
70
|
+
const scopes = []
|
|
71
|
+
try {
|
|
72
|
+
for (const scope of memory.resolveReadScopes?.(agent) ?? []) {
|
|
73
|
+
if (!scopes.includes(scope)) scopes.push(scope)
|
|
74
|
+
}
|
|
75
|
+
} catch { /* 降级为 extraScopes */ }
|
|
76
|
+
for (const scope of extraScopes) if (!scopes.includes(scope)) scopes.push(scope)
|
|
77
|
+
// fork 出来的会话:父会话的记忆也值得召回(只读)。父会话可能已不在内存里,拿不到就跳过。
|
|
78
|
+
try {
|
|
79
|
+
const header = (agent )?.session?.header
|
|
80
|
+
const parent = typeof header?.parentSession === 'string' ? header.parentSession : undefined
|
|
81
|
+
if (parent !== undefined && header?.origin !== 'subagent') {
|
|
82
|
+
if (sessions?.get?.(parent) !== undefined) {
|
|
83
|
+
const scope = `session:${parent}`
|
|
84
|
+
if (!scopes.includes(scope)) scopes.push(scope)
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
} catch { /* 父会话召回是可选增强 */ }
|
|
88
|
+
return scopes.length > 0 ? scopes : undefined
|
|
89
|
+
}
|
|
90
|
+
|
|
25
91
|
/** Minimal structural view of the messages we inspect (role + text blocks). */
|
|
26
92
|
|
|
27
93
|
|
|
@@ -31,6 +97,12 @@ export const defaultInjectConfig = {
|
|
|
31
97
|
|
|
32
98
|
|
|
33
99
|
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
|
|
34
106
|
|
|
35
107
|
|
|
36
108
|
|
|
@@ -89,11 +161,11 @@ export function recallText(text ) {
|
|
|
89
161
|
*/
|
|
90
162
|
export class MemoryInjector {
|
|
91
163
|
lastText = ''
|
|
92
|
-
search
|
|
164
|
+
search
|
|
93
165
|
cfg
|
|
94
166
|
|
|
95
167
|
constructor(
|
|
96
|
-
search
|
|
168
|
+
search ,
|
|
97
169
|
cfg ,
|
|
98
170
|
) {
|
|
99
171
|
this.search = search
|
|
@@ -110,7 +182,7 @@ export class MemoryInjector {
|
|
|
110
182
|
|
|
111
183
|
let hits
|
|
112
184
|
try {
|
|
113
|
-
hits = await this.search(query, input.signal)
|
|
185
|
+
hits = await this.search(query, input.signal, input.scopes)
|
|
114
186
|
} catch {
|
|
115
187
|
return undefined // retrieval failure never breaks the agent loop
|
|
116
188
|
}
|