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 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
- 本插件未发布到 npm,用本地路径链接安装(克隆后指向仓库根目录即可):
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.2`。完整变更见 [CHANGELOG.md](CHANGELOG.md)。
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) lines.push('未登记(paths.yaml 没有条目):' + missing.join('、'))
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-local-kb",
3
- "version": "0.6.2",
3
+ "version": "0.6.4",
4
4
  "description": "知识库 + 长期记忆插件:每轮注入记忆索引与知识地图、索引硬上限、禁止 AI 删除、镜像同步到 WebDAV",
5
5
  "keywords": [
6
6
  "dsh-plugin",
@@ -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
- - **未入库 → 先按 `code-project.md` 流程 add 该项目**(建档),再写项目级记忆。
35
- - 不写全局暂存。全局记忆只装与具体项目无关的内容(`user` / 跨项目 `feedback` / 全局 `reference`)。
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 "~/.local-kb")
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 "~/.local-kb"))
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 "~/.local-kb")
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 str(path).split("/") if x]
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):