dsh-local-kb 0.0.0-stage → 0.6.2

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 gege9527 (https://github.com/gege9527)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,534 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <h1>dsh-local-kb</h1>
4
+
5
+ <p><b>给 DSH 的知识库 + 长期记忆插件</b><br>
6
+ AI 每轮记得你的项目与结论 · 写入有护栏 · 一键备份到 WebDAV</p>
7
+
8
+ <p>
9
+ <a href="CHANGELOG.md"><img alt="version" src="https://img.shields.io/badge/version-0.6.0-blue"></a>
10
+ <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-green"></a>
11
+ <img alt="node" src="https://img.shields.io/badge/node-%3E%3D18-339933">
12
+ <img alt="DSH" src="https://img.shields.io/badge/DSH-0.1.0%20~%200.2.x-6366f1">
13
+ </p>
14
+
15
+ <p>
16
+ <a href="#快速开始">快速开始</a> ·
17
+ <a href="#能做什么">能做什么</a> ·
18
+ <a href="#排障">排障</a> ·
19
+ <a href="CHANGELOG.md">变更日志</a>
20
+ </p>
21
+
22
+ </div>
23
+
24
+ ---
25
+
26
+ ## 目录
27
+
28
+ - [它是什么](#它是什么)
29
+ - [能做什么](#能做什么)
30
+ - [快速开始](#快速开始)
31
+ - [平时怎么用](#平时怎么用)
32
+ - [自动做的事](#自动做的事)
33
+ - [备份与恢复](#备份与恢复)
34
+ - [设置页](#设置页)
35
+ - [知识库结构](#知识库结构)
36
+ - [配置](#配置)
37
+ - [安全](#安全)
38
+ - [排障](#排障)
39
+ - [限制](#限制)
40
+ - [卸载](#卸载)
41
+ - [版本与兼容](#版本与兼容)
42
+ - [发布前校验](#发布前校验)
43
+ - [相关文档](#相关文档)
44
+ - [License](#license)
45
+
46
+ ---
47
+
48
+ ## 它是什么
49
+
50
+ dsh-local-kb 让 AI 在每次对话开始时自动带上你的**记忆索引**与**项目地图**,并在它写库、删库、
51
+ 全盘乱搜时兜底。记忆本体是你磁盘上的普通 Markdown 文件,不存在数据库里。
52
+
53
+ 一句话分工:**技能告诉 AI 怎么记、怎么查;插件保证它真的做到,而且不出格。**
54
+
55
+ 四条边界:
56
+
57
+ - **不创建知识库**:首次使用时由技能按模板建目录。
58
+ - **不替你写记忆**:写什么由 AI 判断,插件只在写入前校验、写入后体检。
59
+ - **不改技能协议**:技能随插件加载,升级不会加载到旧版。
60
+ - **不接管文件**:知识库就是普通文件夹,随便 grep、随便 git 管。
61
+
62
+ ---
63
+
64
+ ## 能做什么
65
+
66
+ | 能力 | 你会感觉到 |
67
+ |---|---|
68
+ | **记忆自动带回** | 新会话不用重复交代项目背景,AI 直接知道上次结论、坑和偏好 |
69
+ | **项目地图** | AI 知道知识库里有哪些项目、当前项目在哪、有哪些文档可查 |
70
+ | **稳定的检索顺序** | 先记忆、再查知识库、最后才全盘搜索,不靠 AI 自觉 |
71
+ | **索引不膨胀** | 记忆索引超过上限时,AI 想再堆会被拒绝,倒逼压缩整理 |
72
+ | **不会删库** | AI 只能归档,物理删除永远由你手动做 |
73
+ | **不会乱扫盘** | 没查过知识库就全盘 grep/rg,会被拦一次并提示正确做法 |
74
+ | **写后自检** | 每次改知识库,1.5 秒后自动体检,断链与漏索引当场暴露 |
75
+ | **写入回报** | 每次写入,AI 回复里固定一行「已写入知识库:…」,不用翻设置页 |
76
+ | **长对话提醒** | 上下文快到一半以上时,提醒 AI 把进度写成可恢复的记忆 |
77
+ | **跑偏提醒** | 联网查本地问题、搜盘没碰记忆时,补一句不打断的提醒 |
78
+ | **WebDAV 备份** | 上传镜像、下载覆盖,也能选择写入后自动上传 |
79
+ | **设置页** | 知识库位置、内容概览、备份配置、同步与体检状态一目了然 |
80
+
81
+ ---
82
+
83
+ ## 快速开始
84
+
85
+ ### 1. 安装
86
+
87
+ 本插件未发布到 npm,用本地路径链接安装(克隆后指向仓库根目录即可):
88
+
89
+ ```sh
90
+ dsh plugin --profile web add link:/path/to/dsh-local-kb
91
+ ```
92
+
93
+ > [!IMPORTANT]
94
+ > **装完必须重启 `dsh web`。** 插件是 host 侧代码,热重载接不上,浏览器半也要重新打包。
95
+
96
+ ### 2. 初始化知识库
97
+
98
+ 第一次让 AI 存东西时,技能会按模板创建 `~/.local-kb/`(`README.md`、`paths.yaml`、`memory/`)。
99
+ 也可以用环境变量换位置:
100
+
101
+ ```sh
102
+ KB_ROOT=/data/kb dsh web
103
+ ```
104
+
105
+ ### 3. 配 WebDAV(可选)
106
+
107
+ 打开 **设置 → 知识库**,填地址、账户、密码 → **测试链接** → **保存配置** → **上传到云端**。
108
+
109
+ > [!TIP]
110
+ > 默认**不会自动上传**:写知识库只改本地,什么时候推由你决定。
111
+ > 但**体检是常开的**——只要写进知识库,1.5 秒后就会自检一次,与自动同步开关无关。
112
+
113
+ ---
114
+
115
+ ## 平时怎么用
116
+
117
+ 不需要记命令,用自然语言即可:
118
+
119
+ | 你说 | 会发生什么 |
120
+ |---|---|
121
+ | 「存进知识库」「记住这个」 | AI 把一个项目或一条结论写成笔记,更新索引 |
122
+ | 「查…在哪」「…怎么实现」 | AI 先查知识库,再定位源码,给出文件与行号 |
123
+ | 「归档这个笔记」「这个项目不用了」 | 内容移进 `archive/`,索引指针删除,文件不丢 |
124
+ | 「知识库里有什么」 | 列出项目、文档与最近记忆 |
125
+
126
+ 写入后可以随时在设置页看体检状态;也可以在技能目录下跑 `tools/kb-check.py` 做完整检查。
127
+
128
+ ---
129
+
130
+ ## 自动做的事
131
+
132
+ 以下都在后台发生,不需要你操作;不想用时可以逐项关闭(见[配置](#配置))。
133
+
134
+ **1. 每轮带上记忆与地图**
135
+ AI 每次开始工作,都会看到全局记忆索引、当前项目(含父项目)的记忆索引,以及一张知识地图:
136
+ 哪些项目、当前项目在哪、有哪些文档。只给索引与目录名,不灌文档正文。
137
+
138
+ **2. 写索引前拦上限**
139
+ 记忆索引超过 **200 行 / 25 KB** 时,AI 再往里加内容会被拒绝,提示先压缩或归档。
140
+ 整理时变短的写入一律放行,避免索引一旦超限就再也改不动。
141
+
142
+ **3. 改库后自动体检**
143
+ 任何写进知识库的改动,1.5 秒后自动跑一次体检,检查断链索引、漏索引、frontmatter、
144
+ 项目页资料链接等。识别覆盖 `write` / `edit`、bash 命令写文件,以及 `run_code` 里的
145
+ `fs.writeFileSync` 直写(PTC 模式)。体检结果只记录、不阻塞保存,也不阻塞同步。
146
+
147
+ **4. 长对话提醒落盘**
148
+ 上下文占用超过 60% 时,提醒 AI 把「目标 / 当前状态 / 阻塞 / 下一步」写成一条活跃记忆,
149
+ 避免压缩后想不起来。任务已结束或本来就是一问一答,会明确跳过。
150
+
151
+ **5. 搜索跑偏时兜底**
152
+ - 本会话还没查过知识库就全盘 grep/rg:拦一次,告诉 AI 先查库。
153
+ - 联网查本地问题、搜盘没碰记忆:追加一句提醒,不打断、不改结果。
154
+ - 提醒有频率上限,长会话不会反复刷屏。
155
+
156
+ ---
157
+
158
+ ## 备份与恢复
159
+
160
+ ### 两个方向
161
+
162
+ | 操作 | 语义 |
163
+ |---|---|
164
+ | **上传到云端** | 本地覆盖云端。云端有、本地没有的文件会被删除(镜像)。 |
165
+ | **从云端下载** | 云端覆盖本地同名文件。本地多出的文件保留。 |
166
+
167
+ ### 同步什么
168
+
169
+ - **同步**:`docs/`、`projects/`(记忆、项目页、归档)、`memory/`、`README.md`、`paths.yaml`
170
+ - **不同步**:系统垃圾文件、卡片索引(生成物)、同步状态文件、`.backup/`(改名前的整库快照,只用于本地回滚)
171
+ - **增量**:只传变化的文件;本地没改动时连远端都不扫
172
+ - **远端目录**:默认 `local-kb-sync`,可改成多级路径
173
+
174
+ ### 自动同步
175
+
176
+ 默认**关闭**。打开后,每次写入知识库并体检完,自动上传一次。手动「上传到云端」不受开关影响。
177
+
178
+ ### 换设备
179
+
180
+ 同步知识库目录 → 把 `paths.yaml` 里的本机路径改成新机器路径 → 缺失的项目**先问你是否克隆**,
181
+ 同意才按 `git_remote` 克隆;拒绝或没有远程地址,则标记缺失,本次不查源码。
182
+
183
+ 代码永远不进知识库:知识库只存索引、文档与记忆。
184
+
185
+ > [!WARNING]
186
+ > **单写者**:同一时间只让一台设备上传,另一台下载后不要再上传。两端都写会互相删除;
187
+ > 同名笔记两边都改,后同步的会覆盖先同步的。多设备自动合并**尚未实现**。
188
+
189
+ ---
190
+
191
+ ## 设置页
192
+
193
+ 入口:**设置 → 知识库**。
194
+
195
+ | 区域 | 内容 |
196
+ |---|---|
197
+ | 知识库位置 | 显示实际路径,用系统文件管理器打开 |
198
+ | 知识库内容 | 项目数、文档数、每个项目的记忆条数与索引行数、路径是否有效 |
199
+ | WebDAV 备份 | 地址、用户名、密码、远程根目录、自动同步开关 |
200
+ | 操作 | 保存配置、测试链接、清除配置、上传到云端、从云端下载 |
201
+ | 状态 | 上次同步结果、最近体检结果、最多 3 条警告 |
202
+
203
+ 细节:
204
+
205
+ - 密码保存后永不回显,留空表示不改。
206
+ - 改了地址但没保存就点同步,会提示先保存,避免以为新地址已生效。
207
+ - 上传/下载都会二次确认,并说明「云端多出的会被删除」「本地多出的会保留」。
208
+ - 大目录首次上传如果本地网络慢,页面 30 秒会超时提示;可稍后看状态行或重试。
209
+
210
+ ---
211
+
212
+ ## 知识库结构
213
+
214
+ ```text
215
+ <KB_ROOT>/
216
+ ├── README.md 检索指引(给 AI 看)
217
+ ├── paths.yaml 唯一写项目路径的地方
218
+ ├── memory/
219
+ │ ├── MEMORY.md 全局记忆索引
220
+ │ └── *.md 每条记忆一个文件
221
+ ├── docs/ 跨项目知识,扁平存放
222
+ │ └── <主题>/ 多文件文档集才建子目录
223
+ ├── projects/
224
+ │ └── <project_id>/
225
+ │ ├── <project_id>.md 项目主页(概览、状态、概念表)
226
+ │ ├── docs/ 项目产出文档
227
+ │ └── memory/
228
+ │ ├── MEMORY.md 项目记忆索引
229
+ │ └── *.md 项目记忆
230
+ └── archive/ 归档区,永不删除
231
+ ├── projects/<id>/
232
+ ├── docs/<文档集>/
233
+ └── memory/<slug>.md
234
+ ```
235
+
236
+ 三条规则:
237
+
238
+ 1. **路径只写 `paths.yaml`**:笔记、索引、项目页里出现绝对路径,换设备就废。
239
+ 2. **索引只放指针**:`MEMORY.md` 一行一个笔记,正文永远在笔记文件里。
240
+ 3. **归档不是删除**:`archive/` 不参与检索、不注入,但文件还在。
241
+
242
+ ### 项目命名与移动
243
+
244
+ 项目 ID 取能保证唯一的最短路径后缀:目录名唯一就用目录名;同名目录逐级加父目录名;中文目录原样保留。
245
+
246
+ 新项目**用一条命令建档**,别手写 id:
247
+
248
+ ```sh
249
+ python3 skills/local-kb/tools/kb-add-project.py ~/.local-kb --path <绝对路径> \
250
+ --title <项目名> --description "<一句话>" --alias <中文别名>
251
+ ```
252
+
253
+ 它按全库路径推导 id(`/Desktop/test` → `test`;已有 `apps/api` 时 `work/api` → `work-api`)、
254
+ 查重(同路径或同 `git_remote` 直接拒绝)、追加 `paths.yaml`、建目录与记忆索引、生成项目页骨架,
255
+ 最后跑一遍体检;`--dry-run` 只看计划不落盘。
256
+
257
+ 项目移动或改名后,别只手改 `paths.yaml`:
258
+
259
+ ```sh
260
+ python3 skills/local-kb/tools/kb-move-project.py ~/.local-kb --from-path <旧> --to-path <新> --plan /tmp/move.json
261
+ python3 skills/local-kb/tools/kb-move-project.py ~/.local-kb --apply --plan /tmp/move.json
262
+ ```
263
+
264
+ 它会更新路径与项目 ID、改目录与项目页、替换全库引用、清理孤儿卡片、跑体检;执行前自动备份。
265
+
266
+ `--apply` 默认不改正文里的裸 id(短 id 会误伤普通用词与源码路径):命中时会列出文件与行号并拒绝,
267
+ 确认后加 `--allow-body-rewrite` 再执行。
268
+
269
+ ### 归档
270
+
271
+ 归档 = 移进 `archive/`,**不删除、不留标记**;归档后不再进检索、不再注入。
272
+
273
+ ```sh
274
+ # 整个项目(目录 + 记忆 + 项目页),同时删掉 paths.yaml 登记
275
+ python3 skills/local-kb/tools/kb-archive-project.py ~/.local-kb --id <id> --apply
276
+
277
+ # 单条记忆
278
+ python3 skills/local-kb/tools/kb-archive-note.py ~/.local-kb --path projects/<id>/memory/<slug>.md --apply
279
+ ```
280
+
281
+ 两者默认 dry-run,`--apply` 才写。项目归档会改写全库 `projects/<id>/` 引用、清卡片、跑体检,
282
+ 并打印归档日期(不写进项目页)。恢复用手工:`mv` 回原位 + 补回登记(工具不做 restore)。
283
+
284
+ ---
285
+
286
+ ## 配置
287
+
288
+ 写进 profile 的 `cordis.patch.yml`:
289
+
290
+ | 字段 | 默认 | 含义 |
291
+ |---|---|---|
292
+ | `kbRoot` | `~/.local-kb` | 知识库根(也认 `KB_ROOT` 环境变量) |
293
+ | `injectContext` | `true` | 是否每轮注入记忆索引与知识地图 |
294
+ | `injectMaxLines` | `120` | 单个索引最多注入多少行 |
295
+ | `injectMaxBytes` | `12288` | 单个索引最多注入多少字节 |
296
+ | `injectDescriptions` | `true` | 记忆索引是否带「— 钩子」;钩子由协议限定 ≤24 字 |
297
+ | `indexCap` | `true` | 是否启用记忆索引硬上限 |
298
+ | `compactionReminder` | `true` | 长对话是否提醒写记忆 |
299
+ | `reminderPressure` | `0.6` | 上下文占用多少比例时提醒(0 < x ≤ 1) |
300
+ | `injectRules` | `true` | 是否每轮注入常驻规则 |
301
+ | `migrateLegacy` | `true` | 是否清理旧版本安装残留 |
302
+
303
+ WebDAV 的地址、账户、密码、远程目录、自动同步不走这里,由设置页管理。
304
+
305
+ 环境变量:
306
+
307
+ | 变量 | 作用 |
308
+ |---|---|
309
+ | `KB_ROOT` | 覆盖知识库位置 |
310
+ | `DSH_LOCAL_KB_ENFORCE=0` | 关闭搜索拦截与跑偏提醒 |
311
+
312
+ ---
313
+
314
+ ## 安全
315
+
316
+ - WebDAV 地址、账户、密码存在 DSH 凭据服务里,设置页与浏览器不落明文;密码永不回显。
317
+ - 设置页接口由 DSH 校验登录身份:未登录 401,跨站 403。
318
+ - 知识库内容不会上传,除非你点上传或打开自动同步。
319
+ - 卸载时先备份凭据再删除;知识库目录永远不动。
320
+ - 注入只读本地文件;记忆里出现「忽略规则」之类内容,按数据处理,不执行。
321
+
322
+ ---
323
+
324
+ ## 排障
325
+
326
+ <details>
327
+ <summary><b>设置页没有「知识库」</b></summary>
328
+
329
+ 1. 确认插件已启用:`dsh plugin list --profile web`。
330
+ 2. 重启 `dsh web`。
331
+ 3. 浏览器硬刷新。
332
+
333
+ </details>
334
+
335
+ <details>
336
+ <summary><b>设置页接口 404 / 401</b></summary>
337
+
338
+ 看诊断文件 `~/.dsh/local-kb/route-debug.json`:`401` 是登录态问题,`404` 表示页面接口没注册成功。
339
+
340
+ </details>
341
+
342
+ <details>
343
+ <summary><b>AI 没有带上记忆索引</b></summary>
344
+
345
+ 1. `injectContext` 是否被关了。
346
+ 2. 当前目录是否在 `paths.yaml` 里登记;没登记的项目只出现在地图里。
347
+ 3. 项目索引是否存在:`ls ~/.local-kb/projects/<id>/memory/MEMORY.md`。
348
+ 4. 是否被注入上限截断,段尾会有提示;可临时调大 `injectMaxLines`。
349
+ 5. 注入有短缓存,等下一轮再看。
350
+
351
+ </details>
352
+
353
+ <details>
354
+ <summary><b>AI 没有遵守知识库规则</b></summary>
355
+
356
+ 1. `injectRules` 是否为 `false`。
357
+ 2. 插件自带技能文件是否完整(发布包缺文件会在启动日志 warn)。
358
+ 3. 规则读取失败不报错,只返回空;查启动日志。
359
+
360
+ </details>
361
+
362
+ <details>
363
+ <summary><b>同步失败</b></summary>
364
+
365
+ | 报错 | 原因 | 修法 |
366
+ |---|---|---|
367
+ | 401 / 403 | 账号密码错,或服务不支持 Basic 认证 | 重填密码;换支持 Basic 的服务 |
368
+ | 404 | 远程根目录不存在 | 改远程根,或先手动建目录 |
369
+ | 超时 | 网络或服务慢 | 重试;首次建链可能慢 |
370
+ | 路径越界 | 远端返回了知识库之外的路径 | 拒绝是正确行为,检查远端目录 |
371
+
372
+ 失败只记录状态,不打断对话;修好后手动上传一次即可。
373
+
374
+ </details>
375
+
376
+ <details>
377
+ <summary><b>新设备地图标「路径失效」</b></summary>
378
+
379
+ 正常。`paths.yaml` 同步过来了,但里面是旧机器的绝对路径。
380
+ 在新路径下重新登记,或手改那一条 `path` 即可。地图只报告失效,不会拿错路径去查。
381
+
382
+ </details>
383
+
384
+ <details>
385
+ <summary><b>技能列表里没有 local-kb</b></summary>
386
+
387
+ 1. 包内技能是否存在。
388
+ 2. profile 配置里是否有技能那一行(`dsh plugin add` 会负责)。
389
+ 3. 旧副本是否还压着:`ls ~/.dsh/skills/local-kb`(应不存在)。
390
+ 4. 重启 dsh,看启动日志。
391
+
392
+ </details>
393
+
394
+ <details>
395
+ <summary><b>写入被拒:「索引超过上限」</b></summary>
396
+
397
+ 索引到了 200 行 / 25 KB。压缩,不要调上限:把已完成的笔记归档并从索引删指针;合并同主题笔记;
398
+ 只留最近、最常命中的条目。体检工具只补缺失指针,不替你删。
399
+
400
+ </details>
401
+
402
+ <details>
403
+ <summary><b>全盘搜索被拦</b></summary>
404
+
405
+ 先让 AI 查一次知识库(检索或读库内文件),再重试即可。
406
+ 应急可设 `DSH_LOCAL_KB_ENFORCE=0` 重启,连跑偏提醒一起关。
407
+
408
+ </details>
409
+
410
+ <details>
411
+ <summary><b>提醒没出现 / 太吵</b></summary>
412
+
413
+ - 没查过库或没有上下文时不提醒。
414
+ - 每类每任务 1 次、每会话最多 3 次,提醒过的类别不会重复。
415
+ - 彻底关闭:`DSH_LOCAL_KB_ENFORCE=0`。
416
+
417
+ </details>
418
+
419
+ <details>
420
+ <summary><b>长对话不提醒写记忆</b></summary>
421
+
422
+ 提醒依赖上下文用量与窗口大小;拿不到就不提醒(宁可不说,也不瞎猜)。
423
+ 确认 `compactionReminder` 没关。
424
+
425
+ </details>
426
+
427
+ <details>
428
+ <summary><b>自动同步没触发</b></summary>
429
+
430
+ 1. 自动同步开关是否打开。
431
+ 2. 写入是否落在知识库目录内。
432
+ 3. 写入后要等 1.5 秒体检跑完。
433
+ 4. 体检有错不影响上传,看状态行的同步结果,别把体检失败当成没同步。
434
+
435
+ </details>
436
+
437
+ <details>
438
+ <summary><b>上传一直显示「上传中…」</b></summary>
439
+
440
+ 页面 30 秒会超时提示。超时后服务端可能仍在继续,稍后看状态行与远端。
441
+ 大目录首次同步建议手动点一次,别依赖写入后自动。
442
+
443
+ </details>
444
+
445
+ ---
446
+
447
+ ## 限制
448
+
449
+ - **删除拦截只认 shell 删除命令**:脚本内部删除、远程命令删除判不出来。
450
+ - **索引上限只覆盖记忆索引**:项目页与文档不设行数上限。
451
+ - **注入按 `paths.yaml` 匹配**:没登记的项目只出现在地图里,不注入它的记忆。
452
+ - **检索是词面匹配**:拆词 + 评分 + 别名,不懂同义词;查不到时换说法。
453
+ - **单写者同步**:多设备同时写会互相覆盖,自动合并尚未实现。
454
+ - **设置页跟随浏览器语言**:只区分中英文,未接入 DSH 语言设置。
455
+ - **长对话提醒是粗粒度**:按上下文占比估算,不预测真实压缩点。
456
+ - **搜索拦截只防一种情况**:防「不知道去哪就全盘扫」,不防「知道去哪但去错地方」。
457
+ - **同步不做冲突合并**:上传与下载都是整文件覆盖,没有 diff 或三方合并。
458
+ - **写入不在对话里弹提示**:插件不注入额外消息。写入是否发生,看 AI 回复里的
459
+ 「已写入知识库:…」一行(技能协议要求),以及设置页的体检/同步状态。
460
+ - **run_code 写入靠文本判定**:解析代码里的 fs 写调用与路径,变量深度拼接的路径判不出来,
461
+ 会漏触发一次体检;手动跑一次 `kb-check.py` 即可。
462
+
463
+ ---
464
+
465
+ ## 卸载
466
+
467
+ ```sh
468
+ dsh plugin remove dsh-local-kb
469
+ node install-skill.js --uninstall
470
+ ```
471
+
472
+ 第二条命令清理旧版本残留与凭据:
473
+
474
+ | 删除 | 说明 |
475
+ |---|---|
476
+ | 旧技能副本 | 0.3.x 安装的遗留;软链只解链接 |
477
+ | `AGENTS.md` 里的旧规则块 | 只摘标记之间,块外不动 |
478
+ | WebDAV 凭据 | 删除前备份凭据文件 |
479
+ | 插件状态目录 | 设置、同步基准、覆盖前备份 |
480
+
481
+ **不会删知识库目录**——那是你的数据。
482
+
483
+ ---
484
+
485
+ ## 版本与兼容
486
+
487
+ 当前版本 `0.6.2`。完整变更见 [CHANGELOG.md](CHANGELOG.md)。
488
+
489
+ | 版本 | 主题 |
490
+ |---|---|
491
+ | 0.6.2 | 归档与建档工具、注入钩子 ≤24 字(上限 120 行/12KB)、问句骨架剥离与置信封顶 |
492
+ | 0.6.1 | 写入回报协议、run_code 直写识别(体检与同步不再漏) |
493
+ | 0.6.0 | 卡片 v4 与共享模块、查询命令收敛、回源按时间、kb-move 安全开关、死代码与打包清理 |
494
+ | 0.5.0 | 技能随插件加载、规则注入、旧安装迁移、体检与上传解耦、发布前校验 |
495
+ | 0.4.0 | 卡片摘要回退、孤儿卡片清理、置信分级修正、安装器幂等 |
496
+ | 0.3.0 | 检索别名层与置信分级;卡片格式 v2 |
497
+ | 0.2.0 | 每轮注入、索引上限、禁止删除、WebDAV 镜像同步 |
498
+
499
+ 兼容 DSH `>=0.1.0 <0.3.0-0`,已验证 `0.2.2-alpha.2`。
500
+
501
+ ---
502
+
503
+ ## 发布前校验
504
+
505
+ `npm publish` 前自动跑两道闸(`prepublishOnly`,任一失败即中止发布):
506
+
507
+ 1. **载荷完整**(`scripts/check-package.mjs`):包内技能文件、provider 配置、`files` 覆盖。
508
+ 2. **隐私**(`scripts/check-privacy.mjs`):扫描 `files` 白名单内所有文本文件,命中即阻断——
509
+ 本机绝对路径(`/Users/`、`/home/`、`C:\Users\`)、本机用户名、私钥块、疑似真实凭据、内网 IP;
510
+ 公开署名(`©`)与常量键名放行。
511
+
512
+ 单独跑:`npm run check:privacy`。
513
+
514
+ ## 上游与致谢
515
+
516
+ 记忆协议的结构(两级存储、限长索引、召回与写入纪律)参考了
517
+ [tinqiao-oss/engramory](https://github.com/tinqiao-oss/engramory)
518
+ (MIT License,Copyright © 2026 Beijing Tinqiao Technology Co., Ltd.)。
519
+ 本项目的协议文本与代码为独立重写,未复制上游源码。
520
+
521
+ ---
522
+
523
+ ## 相关文档
524
+
525
+ - [CHANGELOG.md](CHANGELOG.md) —— 版本变更
526
+ - [skills/local-kb/SKILL.md](skills/local-kb/SKILL.md) —— 技能协议本体(模型读的那份)
527
+ - [skills/local-kb/references/](skills/local-kb/references/) —— 记忆、文档、代码项目、模板细则
528
+ - [LICENSE](LICENSE) —— MIT
529
+
530
+ ---
531
+
532
+ ## License
533
+
534
+ [MIT](LICENSE) © lyu