dsh-local-kb 0.6.2 → 0.6.4
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 +54 -7
- package/inject.js +4 -2
- package/package.json +1 -1
- package/skills/local-kb/references/agents-snippet.md +3 -0
- package/skills/local-kb/references/memory.md +7 -3
- package/skills/local-kb/tools/kb-card.py +4 -1
- package/skills/local-kb/tools/kb-check.py +2 -1
- package/skills/local-kb/tools/kb-search.py +3 -1
- package/skills/local-kb/tools/kb_common.py +2 -2
package/README.md
CHANGED
|
@@ -37,6 +37,7 @@ AI 每轮记得你的项目与结论 · 写入有护栏 · 一键备份到 WebDA
|
|
|
37
37
|
- [安全](#安全)
|
|
38
38
|
- [排障](#排障)
|
|
39
39
|
- [限制](#限制)
|
|
40
|
+
- [平台支持](#平台支持)
|
|
40
41
|
- [卸载](#卸载)
|
|
41
42
|
- [版本与兼容](#版本与兼容)
|
|
42
43
|
- [发布前校验](#发布前校验)
|
|
@@ -84,7 +85,11 @@ dsh-local-kb 让 AI 在每次对话开始时自动带上你的**记忆索引**
|
|
|
84
85
|
|
|
85
86
|
### 1. 安装
|
|
86
87
|
|
|
87
|
-
|
|
88
|
+
```sh
|
|
89
|
+
dsh plugin --profile web add dsh-local-kb
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
本地开发用链接:
|
|
88
93
|
|
|
89
94
|
```sh
|
|
90
95
|
dsh plugin --profile web add link:/path/to/dsh-local-kb
|
|
@@ -96,11 +101,7 @@ dsh plugin --profile web add link:/path/to/dsh-local-kb
|
|
|
96
101
|
### 2. 初始化知识库
|
|
97
102
|
|
|
98
103
|
第一次让 AI 存东西时,技能会按模板创建 `~/.local-kb/`(`README.md`、`paths.yaml`、`memory/`)。
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
```sh
|
|
102
|
-
KB_ROOT=/data/kb dsh web
|
|
103
|
-
```
|
|
104
|
+
需要换位置见[配置 · 知识库位置](#知识库位置),快速开始不用管。
|
|
104
105
|
|
|
105
106
|
### 3. 配 WebDAV(可选)
|
|
106
107
|
|
|
@@ -302,6 +303,34 @@ python3 skills/local-kb/tools/kb-archive-note.py ~/.local-kb --path projects/<id
|
|
|
302
303
|
|
|
303
304
|
WebDAV 的地址、账户、密码、远程目录、自动同步不走这里,由设置页管理。
|
|
304
305
|
|
|
306
|
+
### 知识库位置
|
|
307
|
+
|
|
308
|
+
默认 `~/.local-kb`。优先级:**`cordis.patch.yml` 的 `kbRoot` > `KB_ROOT` 环境变量 > 默认**。
|
|
309
|
+
|
|
310
|
+
长期固定用配置:
|
|
311
|
+
|
|
312
|
+
```yaml
|
|
313
|
+
# cordis.patch.yml
|
|
314
|
+
config:
|
|
315
|
+
kbRoot: /data/kb
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
临时试或容器里用环境变量:
|
|
319
|
+
|
|
320
|
+
```sh
|
|
321
|
+
KB_ROOT=/data/kb dsh web
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
**两者建议保持一致**:插件读配置或环境变量;脚本(`kb-check.py` 等)默认只读 `KB_ROOT`。
|
|
325
|
+
只写配置不设环境变量时,手动跑脚本要显式传路径,否则会去查 `~/.local-kb`。
|
|
326
|
+
|
|
327
|
+
### 命名不可改
|
|
328
|
+
|
|
329
|
+
下列文件名/目录名是工具链契约,没有开关,改了等于换协议:
|
|
330
|
+
|
|
331
|
+
`MEMORY.md`、`paths.yaml`、`archive/`、`projects/<id>/<id>.md`、`memory/`;
|
|
332
|
+
项目 id 固定按「最短唯一路径后缀」推导(中文目录原样保留)。
|
|
333
|
+
|
|
305
334
|
环境变量:
|
|
306
335
|
|
|
307
336
|
| 变量 | 作用 |
|
|
@@ -444,6 +473,22 @@ WebDAV 的地址、账户、密码、远程目录、自动同步不走这里,
|
|
|
444
473
|
|
|
445
474
|
---
|
|
446
475
|
|
|
476
|
+
## 平台支持
|
|
477
|
+
|
|
478
|
+
| 平台 | 状态 | 说明 |
|
|
479
|
+
|---|---|---|
|
|
480
|
+
| macOS | ✅ 开发与测试平台 | 全功能,测试在此跑 |
|
|
481
|
+
| Linux(Debian / CentOS / Armbian 等) | ✅ 预期支持 | 需要 Node 24+ 与 Python 3.9+;`python3` 可用即可;本仓库 CI 未覆盖各发行版 |
|
|
482
|
+
| Windows | ⚠️ 部分支持、未实测 | Node 侧有 win32 处理(`python` 命令、路径大小写);脚本已兼容反斜杠与盘符;建议 WSL / Git Bash |
|
|
483
|
+
|
|
484
|
+
跨平台的已知处理:
|
|
485
|
+
|
|
486
|
+
- 路径一律走 `path.join` / `os.path.join`,不拼字符串;
|
|
487
|
+
- 项目 id 推导同时接受 `/` 与 `\`(含 `C:` 盘符);
|
|
488
|
+
- Windows 上启动 Python 用 `python` 而非 `python3`(插件侧自动判断);
|
|
489
|
+
- 换行:`kb-check` 写回时保持原文件行尾风格,CRLF 不会被改成 LF;
|
|
490
|
+
- 编码:读写统一 UTF-8,非 UTF-8 文件用容错读取,不崩。
|
|
491
|
+
|
|
447
492
|
## 限制
|
|
448
493
|
|
|
449
494
|
- **删除拦截只认 shell 删除命令**:脚本内部删除、远程命令删除判不出来。
|
|
@@ -484,10 +529,12 @@ node install-skill.js --uninstall
|
|
|
484
529
|
|
|
485
530
|
## 版本与兼容
|
|
486
531
|
|
|
487
|
-
当前版本 `0.6.
|
|
532
|
+
当前版本 `0.6.4`。完整变更见 [CHANGELOG.md](CHANGELOG.md)。
|
|
488
533
|
|
|
489
534
|
| 版本 | 主题 |
|
|
490
535
|
|---|---|
|
|
536
|
+
| 0.6.4 | 写入前置收成一句「未入库先入库」,堵住全局 docs 旁路 |
|
|
537
|
+
| 0.6.3 | 脚本默认根读 KB_ROOT、Windows 路径兼容、位置与命名文档、平台支持矩阵 |
|
|
491
538
|
| 0.6.2 | 归档与建档工具、注入钩子 ≤24 字(上限 120 行/12KB)、问句骨架剥离与置信封顶 |
|
|
492
539
|
| 0.6.1 | 写入回报协议、run_code 直写识别(体检与同步不再漏) |
|
|
493
540
|
| 0.6.0 | 卡片 v4 与共享模块、查询命令收敛、回源按时间、kb-move 安全开关、死代码与打包清理 |
|
package/inject.js
CHANGED
|
@@ -593,7 +593,9 @@ export function knowledgeMapText({ kbRoot, cwd, cache = new Map() }) {
|
|
|
593
593
|
if (stale.length > 0) {
|
|
594
594
|
lines.push('路径失效(登记的是原设备路径,用 git_remote 重新登记):' + stale.join('、'))
|
|
595
595
|
}
|
|
596
|
-
if (missing.length > 0)
|
|
596
|
+
if (missing.length > 0) {
|
|
597
|
+
lines.push('未登记(paths.yaml 没有条目):' + missing.join('、') + ' —— 写记忆前先跑 kb-add-project.py')
|
|
598
|
+
}
|
|
597
599
|
|
|
598
600
|
const project = projectForPath(cwd, entries)
|
|
599
601
|
if (project !== undefined) {
|
|
@@ -620,7 +622,7 @@ export function knowledgeMapText({ kbRoot, cwd, cache = new Map() }) {
|
|
|
620
622
|
lines.push(' 概念表未填:项目页「中文概念 → 位置」为空,定位请现读源码')
|
|
621
623
|
}
|
|
622
624
|
} else if (cwd !== undefined) {
|
|
623
|
-
lines.push('当前目录未入库(不在 paths.yaml
|
|
625
|
+
lines.push('当前目录未入库(不在 paths.yaml)。写任何项目知识前先跑 kb-add-project.py 建档;只检索则按关键词,别猜项目。')
|
|
624
626
|
}
|
|
625
627
|
|
|
626
628
|
const docs = globalDocs(kbRoot)
|
package/package.json
CHANGED
|
@@ -34,6 +34,9 @@
|
|
|
34
34
|
### 写入
|
|
35
35
|
|
|
36
36
|
- 学到即写(决策/纠正/约束/可复用的坑);**收尾过一遍**:晋升结论、退休临时状态,没值得留的就说明,别硬写。
|
|
37
|
+
- **未入库先入库**:给项目写知识(项目页、docs/、memory/)前,看注入地图的「当前项目」——
|
|
38
|
+
未标注或标「未入库」→ 直接跑 `kb-add-project.py`(空文件夹也建);项目相关文档不进全局 `docs/`。
|
|
39
|
+
**禁止只回复「已记住」而不落盘**;写完回报「已写入知识库:<相对路径>」。
|
|
37
40
|
- 一事实一文件,frontmatter `name/description/type/created/updated`,type ∈
|
|
38
41
|
`user|feedback|project|reference`;指针只进同目录 `MEMORY.md`;改事实更新旧笔记,推翻标
|
|
39
42
|
`> Superseded <日期>`,不删。
|
|
@@ -25,14 +25,18 @@
|
|
|
25
25
|
> 装了 dsh 插件时,全局与当前项目的 `MEMORY.md` 会**每轮注入上下文**(标题 `## 记忆索引`)。
|
|
26
26
|
> 已经看到注入内容就别再 read 索引文件;只有没看到时才读。
|
|
27
27
|
|
|
28
|
-
##
|
|
28
|
+
## 写入前置:项目知识必须先入库
|
|
29
29
|
|
|
30
30
|
- 写某项目的记忆(`project` / 本项目 `reference`)前:检查项目页 `<KB_ROOT>/projects/<id>/<id>.md` **存在**。
|
|
31
31
|
只有 `memory/` 没有项目页 = 半建档,记忆会写进一个 AI 通过项目页永远找不到的项目。
|
|
32
32
|
项目页缺失 → 先按 `code-project.md` 建档,再写记忆。
|
|
33
33
|
**记忆永远写入知识库目录(带 `<KB_ROOT>/` 前缀),绝不写进源项目里的 `memory/` 目录**。
|
|
34
|
-
-
|
|
35
|
-
|
|
34
|
+
- **未入库先入库**:给项目写知识(项目页、`docs/`、`memory/`)前,确认项目页存在且 `paths.yaml` 已登记;
|
|
35
|
+
未登记 → 直接按 `code-project.md` 流程 add(空文件夹也建),再写;远程/无本地代码项目按 ops-project 手工登记。
|
|
36
|
+
- **半建档**:有 `memory/` 但缺项目页 → 先补项目页,再写。
|
|
37
|
+
- **建档失败**:`kb-add-project.py` exit 1 → 先修错误,别继续写。
|
|
38
|
+
- **不写全局暂存**:全局只装与具体项目无关的跨项目事实(`user` / 跨项目 `feedback` / 全局 `reference`)。
|
|
39
|
+
项目相关文档不得放进全局 `docs/` 绕过建档。
|
|
36
40
|
- **项目级记忆的指针只进项目级 `MEMORY.md`,绝不放进全局索引**。全局索引里的 `../` 指针 = 断裂指针,AI 按协议不会打开,记忆等于隐形。
|
|
37
41
|
|
|
38
42
|
## 记忆文件格式
|
|
@@ -13,6 +13,9 @@ import os
|
|
|
13
13
|
import re
|
|
14
14
|
import sys
|
|
15
15
|
|
|
16
|
+
# 默认知识库根:与环境变量保持一致(插件侧也读 KB_ROOT)
|
|
17
|
+
DEFAULT_KB = os.environ.get("KB_ROOT") or "~/.local-kb"
|
|
18
|
+
|
|
16
19
|
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
|
17
20
|
from kb_common import CARD_DIR, CARD_VERSION, frontmatter, iter_docs, read_version, slug_of, version_path
|
|
18
21
|
|
|
@@ -220,7 +223,7 @@ def build_card(kb_root, rel, full):
|
|
|
220
223
|
|
|
221
224
|
|
|
222
225
|
def main(argv):
|
|
223
|
-
kb_root = os.path.expanduser(argv[1] if len(argv) > 1 and not argv[1].startswith("-") else
|
|
226
|
+
kb_root = os.path.expanduser(argv[1] if len(argv) > 1 and not argv[1].startswith("-") else DEFAULT_KB)
|
|
224
227
|
check_only = "--check" in argv
|
|
225
228
|
prune = "--prune" in argv
|
|
226
229
|
force = "--force" in argv
|
|
@@ -34,6 +34,7 @@ CJK = r"\u4e00-\u9fff"
|
|
|
34
34
|
TYPES = {"user", "feedback", "project", "reference"}
|
|
35
35
|
STATUSES = {"active", "completed", "archived"}
|
|
36
36
|
STALE = re.compile(r"待办|进行中|正在进行|正在编译|当前瓶颈|未完成|下一步")
|
|
37
|
+
DEFAULT_KB = os.environ.get("KB_ROOT") or "~/.local-kb"
|
|
37
38
|
SOFT_LINES, SOFT_KB = 150, 20
|
|
38
39
|
HARD_LINES, HARD_KB = 200, 25
|
|
39
40
|
# 索引行钩子上限:超过就是把内容写回索引(one short hook + link)。
|
|
@@ -450,7 +451,7 @@ ARGV = [a for a in sys.argv[1:] if not a.startswith("--")]
|
|
|
450
451
|
JSON_MODE = "--json" in sys.argv[1:]
|
|
451
452
|
FIX_MODE = "--fix" in sys.argv[1:]
|
|
452
453
|
WRITE_MODE = "--write" in sys.argv[1:]
|
|
453
|
-
KB = os.path.abspath(os.path.expanduser(ARGV[0] if ARGV else
|
|
454
|
+
KB = os.path.abspath(os.path.expanduser(ARGV[0] if ARGV else DEFAULT_KB))
|
|
454
455
|
SRC_PATHS = project_source_paths()
|
|
455
456
|
PROJECT_ROOT_ROOT = os.path.join(KB, "projects")
|
|
456
457
|
GLOBAL_MEM_ROOT = os.path.join(KB, "memory")
|
|
@@ -19,6 +19,8 @@ import sys
|
|
|
19
19
|
# 同目录模块:被 importlib 直接加载时 sys.path 里没有脚本目录,显式补上
|
|
20
20
|
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
|
21
21
|
from kb_common import CARD_DIR, CARD_VERSION, frontmatter, iter_docs, read_version, slug_of, version_path
|
|
22
|
+
# 默认知识库根:与环境变量保持一致(插件侧也读 KB_ROOT)
|
|
23
|
+
DEFAULT_KB = os.environ.get("KB_ROOT") or "~/.local-kb"
|
|
22
24
|
MAX_HITS_PER_DOC = 3
|
|
23
25
|
SNIPPET_CHARS = 110
|
|
24
26
|
TITLE_WEIGHT = 8 # 标题/文件名命中是强信号,实测 3 → 8 把 hit@1 从 13/18 拉到 15/18
|
|
@@ -459,7 +461,7 @@ def main(argv):
|
|
|
459
461
|
continue
|
|
460
462
|
rest.append(a)
|
|
461
463
|
i += 1
|
|
462
|
-
kb_root = os.path.expanduser(rest[0] if rest else
|
|
464
|
+
kb_root = os.path.expanduser(rest[0] if rest else DEFAULT_KB)
|
|
463
465
|
cards_dir = os.path.join(kb_root, CARD_DIR)
|
|
464
466
|
|
|
465
467
|
if "--rebuild" in argv:
|
|
@@ -87,8 +87,8 @@ def kebab_seg(seg):
|
|
|
87
87
|
|
|
88
88
|
|
|
89
89
|
def path_segments(path):
|
|
90
|
-
"""绝对路径 → kebab
|
|
91
|
-
return [kebab_seg(x) for x in
|
|
90
|
+
"""绝对路径 → kebab 化后的段列表(忽略根与空段;兼容 Windows 反斜杠与盘符)。"""
|
|
91
|
+
return [kebab_seg(x) for x in re.split(r"[\\/]+", str(path)) if x]
|
|
92
92
|
|
|
93
93
|
|
|
94
94
|
def shortest_unique_suffix(parts, siblings):
|