dsh-wiki-notes 0.0.0-stage → 1.1.1
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 +21 -0
- package/README.md +145 -2
- package/bin/cli.mjs +68 -0
- package/cordis.patch.yml +8 -0
- package/docs/metrics.md +105 -0
- package/docs//345/272/223/347/273/223/346/236/204.md +163 -0
- package/examples/sample-wiki/index.md +24 -0
- package/examples/sample-wiki/log.md +9 -0
- package/examples/sample-wiki//345/256/236/344/275/223-entities//344/270/212/344/270/213/346/226/207/347/252/227/345/217/243.md +25 -0
- package/examples/sample-wiki//345/257/271/346/257/224-comparisons//345/276/256/350/260/203/344/270/216/346/243/200/347/264/242/345/242/236/345/274/272.md +36 -0
- package/examples/sample-wiki//346/200/273/350/247/210-overview.md +24 -0
- package/examples/sample-wiki//346/246/202/345/277/265-concepts//344/270/212/344/270/213/346/226/207/345/267/245/347/250/213.md +33 -0
- package/examples/sample-wiki//346/246/202/345/277/265-concepts//350/256/260/345/277/206/347/263/273/347/273/237.md +29 -0
- package/examples/sample-wiki//347/273/274/345/220/210-syntheses//350/257/201/346/215/256/346/200/216/344/271/210/345/210/206/347/272/247.md +37 -0
- package/examples/sample-wiki//350/265/204/346/226/231-sources//346/237/220/350/257/276/347/250/213/347/254/254/344/270/211/350/256/262/302/267/350/265/204/346/226/231/346/221/230/350/246/201.md +33 -0
- package/lib/client.js +689 -0
- package/lib/config.js +176 -0
- package/lib/corpus.js +471 -0
- package/lib/engine.js +921 -0
- package/lib/index.js +886 -0
- package/package.json +64 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 xyzOvO
|
|
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,146 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-wiki-notes
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/deepseek-ai)
|
|
4
|
+
|
|
5
|
+
**Read-only retrieval for a folder of Markdown notes, exposed as one tool call.**
|
|
6
|
+
|
|
7
|
+
Built for [DeepSeek Harness](https://github.com/deepseek-ai). Instead of a 5-step loop — read the overview, read the index, shell out to a search script, open the page, chase its sources — `wiki_recall` returns **the matching section's full text plus a page-level citation** in one call.
|
|
8
|
+
|
|
9
|
+
> 中文文档从下面开始。实测:73 页的库,旧流程单次 ≈ 18.7k 字符,新流程 ≈ 2.5k。
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 设计从哪来
|
|
14
|
+
|
|
15
|
+
库结构来自 [Karpathy 的 `llm-wiki.md`](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f):与其每次提问都从原始文档重新检索(知识不累积),不如让 LLM 增量维护一个持久的 wiki。本插件只加速其中的 **Query** 一段。
|
|
16
|
+
|
|
17
|
+
| gist 里的概念 | 本插件默认位置 |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| Raw sources(不可变) | `原始资料-raw/` |
|
|
20
|
+
| The wiki(LLM 维护) | `知识层-wiki/` |
|
|
21
|
+
| The schema | 库根 `AGENTS.md` |
|
|
22
|
+
| `index.md` + `log.md` | 同名同格式 |
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 库该长什么样
|
|
27
|
+
|
|
28
|
+
**一个目录 + 一堆 `.md` 就能用。** 更细的约定见 [docs/库结构.md](docs/库结构.md):frontmatter 七字段(英文写法 `title/type/tags/aliases/status/created/updated/sources` 也认)、`index.md` 摘要目录、`log.md` 时间线、`总览-overview.md`,满足得越多检索越准。可跑的样例在 [`examples/sample-wiki/`](examples/sample-wiki/)。
|
|
29
|
+
|
|
30
|
+
路径指到上一层(比如 `LLM-Wiki/`,里面还有 `原始资料-raw/` 和 `知识层-wiki/`)也没关系:插件会认 `index.md`,自动下钻到知识层,并在返回里注明它实际读的是哪一层。
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## 装
|
|
35
|
+
|
|
36
|
+
在 DSH 里说一句即可:**「帮我装一个 DSH 插件,目录是 `<绝对路径>`」**。或自己发:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
返回 `application: applied` 就生效,不用重启。改 `lib/*.js` 后关开插件热重载;改 `lib/client.js`(设置页)要重启 DSH。
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 配
|
|
47
|
+
|
|
48
|
+
**设置 →「知识库」**,填路径 → 测试 → 保存。四层优先级:
|
|
49
|
+
|
|
50
|
+
| 优先级 | 来源 |
|
|
51
|
+
| --- | --- |
|
|
52
|
+
| 1 | 插件 config 的 `root` |
|
|
53
|
+
| 2 | 环境变量 `DSH_WIKI_ROOT` |
|
|
54
|
+
| 3 | `wiki-notes.config.json`(设置页写这里) |
|
|
55
|
+
| 4 | `lib/config.js` 的 `DEFAULT_WIKI_ROOT`(默认空) |
|
|
56
|
+
|
|
57
|
+
没配时工具会直接告诉你「还没配置知识库路径」,不会静默扫空目录。
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 用
|
|
62
|
+
|
|
63
|
+
| mode | 干什么 | 参数 |
|
|
64
|
+
| --- | --- | --- |
|
|
65
|
+
| `search`(默认) | 关键词 AND 检索 | `query`、`limit`(5,≤12)、`sectionChars`(900,≤3000) |
|
|
66
|
+
| `page` | 按页名/别名取整页 | `name`、`pageChars`(6000) |
|
|
67
|
+
| `list` | 按类型/标签/状态列目录 | `type`、`tags`、`status`、`limit`(40,≤200) |
|
|
68
|
+
| `overview` | 总览 + 规模行 + 最近日志 + 健康计数 | `pageChars`(4000)、`logLimit`(5,≤20) |
|
|
69
|
+
| `lint` | 库健康检查:孤儿页、断链名字、缺字段、别名冲突、久未更新、无出链、草稿、index 与磁盘不一致 | `limit`(8,≤40)、`staleDays`(120) |
|
|
70
|
+
| `draft` | 把好答案回写成新页的落盘骨架(目录、frontmatter、index 行、log 条),不写文件 | `title`、`type`、`tags`、`summary`、`sources` |
|
|
71
|
+
|
|
72
|
+
```jsonc
|
|
73
|
+
{ "mode": "search", "query": "上下文 预算", "limit": 5 }
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
每条命中带 `kind`(note / raw-summary / source)、`sources`(来源数,**证据强度的唯一可靠代理**)、`status`、`gist`、`section`(命中小节正文,不是 90 字片段)、`citation`(`← [[页名]] §小节 → 路径`)、`brokenLinks`(指向不存在页的双链 = 「库里没依据」的硬信号)。`overview` 额外给三项健康信号:index 有磁盘无、磁盘有 index 无、跨目录重名。
|
|
77
|
+
|
|
78
|
+
模型怎么知道该查库:插件会从你库里现有的 `标签` 算出主题词,注入一行(约 50 token,例如「本地知识库 73 页,主题:上下文工程、ai、agent…」)。换库自动变,所以问题沾这些主题时它自己会去查,不用你提醒。设置页里可以关掉(不占上下文)、换成自己的整段、或在末尾追加一句,改完下一回合生效。
|
|
79
|
+
|
|
80
|
+
主题词怎么挑:跳过 `总览`/`index` 这类结构页,跳过 `数据`/`工具`/`meta` 这类空泛标签,默认只留出现 ≥2 次的标签(设置页可改回 ≥1)。全被滤掉时退回不过滤的前五 —— 小库不至于一条提示都没有。
|
|
81
|
+
|
|
82
|
+
> `limit` 默认 5,一次约 2.5–3k token。嫌多可以传 3 省四成,但默认留 5 —— 少一次往返比省四成更值钱。
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 设置页
|
|
87
|
+
|
|
88
|
+
设置 →「知识库」。状态栏圆点表示实时同步是否生效,三个数字是页面 / 资料 / 红链页,下面是路径卡片和 `测试 · 保存并生效 · 重新扫描`。一次没配过时,卡片会变成三步引导。
|
|
89
|
+
|
|
90
|
+
浏览器半侧走同源 HTTP `/api/wiki-notes/*`(`state` / `check` / `save` / `rescan`),不碰 RPC。
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## 实时同步
|
|
95
|
+
|
|
96
|
+
`fs.watch(root, { recursive: true })`,`.md` 新增 / 改 / 删 → 400ms 防抖 → 作废缓存。监听失败自动退回 30 秒 TTL 缓存。`recursive` 在 Linux 需 Node 20.13+,这也是 `engines` 的下限。
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## 检索质量
|
|
101
|
+
|
|
102
|
+
与一个零依赖的 python 检索脚本做 A/B:14 条 query、比 top5 集合,**召回 65 / 65,无遗漏**。单条查询 0–2ms,扫 73 页约 50ms。
|
|
103
|
+
|
|
104
|
+
评分刻意朴素:标题全等 120 / 标题含 60 / 别名含 50 / 标签含 25 / 正文词频 ×3(封顶 36)/ index 摘要只在其它通道全 0 时补 8。三处经验细节:摘要分只补漏不抢位、同分用码点序(拼音序不可复现)、选节排除清单类与元讨论类小节。
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 上下游(可选)
|
|
109
|
+
|
|
110
|
+
- **进料**:[Obsidian Web Clipper](https://github.com/obsidianmd/obsidian-clipper) —— 网页剪藏成 Markdown 落进 raw 层。模板里写好 `类型` / `来源数量` / `标签`,本插件的 `kind`、`sources`、证据强度才有东西可用。
|
|
111
|
+
- **维护**:[kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) —— 六个 `SKILL.md`,教 agent 写 Obsidian 语法(wikilink / `.base` / `.canvas` / CLI),少猜少往返。
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## 已知局限
|
|
116
|
+
|
|
117
|
+
- 中文不分词,靠空格切分;连写词靠 `别名` 补。
|
|
118
|
+
- 页名本身是查询词时,正文很少重复该词,选节可能偏。
|
|
119
|
+
- 每次调用全量扫描;70–100 页无所谓,再大一个数量级要上增量索引。
|
|
120
|
+
- 只读。不写库、不改页、不修红链。
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## 目录 / 开发
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
lib/corpus.js 扫描 + frontmatter / 小节 / 双链解析
|
|
128
|
+
lib/engine.js 评分、选节、六种模式(纯函数)
|
|
129
|
+
lib/config.js 库路径解析与配置读写
|
|
130
|
+
lib/index.js 插件入口:工具、渲染、设置页 API、目录监听
|
|
131
|
+
lib/client.js 设置页(手写 bundle,无构建)
|
|
132
|
+
bin/cli.mjs 命令行,不装插件也能跑
|
|
133
|
+
docs/库结构.md 库结构约定(这份才是一手文档)
|
|
134
|
+
examples/ 可跑的最小样例库
|
|
135
|
+
tests/ smoke / watch / client bundle
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
node --run test # 跑样例库,不需要本地知识库
|
|
140
|
+
node bin/cli.mjs search 上下文 --root=examples/sample-wiki
|
|
141
|
+
WIKI_ROOT="/path/your/wiki" node tests/smoke.mjs # 拿自己的库跑通就行(不校验答案)
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## License
|
|
145
|
+
|
|
146
|
+
MIT
|
package/bin/cli.mjs
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* cli.mjs —— 本地验证用:不开 DSH 也能看见工具会返回什么。
|
|
4
|
+
*
|
|
5
|
+
* node bin/cli.mjs search "上下文 预算"
|
|
6
|
+
* node bin/cli.mjs search "记忆 系统" --limit 3
|
|
7
|
+
* node bin/cli.mjs page 上下文
|
|
8
|
+
* node bin/cli.mjs list --type 资料
|
|
9
|
+
* node bin/cli.mjs overview
|
|
10
|
+
* node bin/cli.mjs bench # 批量跑一组查询,看耗时与命中
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { fileURLToPath } from 'node:url'
|
|
14
|
+
|
|
15
|
+
import { loadCorpus } from '../lib/corpus.js'
|
|
16
|
+
import { run } from '../lib/engine.js'
|
|
17
|
+
import { resolveWikiRoot } from '../lib/config.js'
|
|
18
|
+
|
|
19
|
+
const argv = process.argv.slice(2)
|
|
20
|
+
const command = argv[0] ?? 'search'
|
|
21
|
+
const rest = argv.slice(1)
|
|
22
|
+
|
|
23
|
+
const flags = {}
|
|
24
|
+
const positional = []
|
|
25
|
+
for (const item of rest) {
|
|
26
|
+
if (item.startsWith('--')) {
|
|
27
|
+
const [key, value] = item.slice(2).split('=')
|
|
28
|
+
flags[key] = value ?? true
|
|
29
|
+
} else {
|
|
30
|
+
positional.push(item)
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
// fileURLToPath 会处理百分号编码(路径里有空格或中文时 pathname 是 %E4%B8%AD 这种)
|
|
35
|
+
const root = resolveWikiRoot(fileURLToPath(new URL('..', import.meta.url)), flags.root)
|
|
36
|
+
|
|
37
|
+
function fmtNumber(value) {
|
|
38
|
+
return value === null || value === undefined ? '-' : String(value)
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
async function main() {
|
|
42
|
+
const t0 = Date.now()
|
|
43
|
+
const corpus = await loadCorpus(root)
|
|
44
|
+
const loadMs = Date.now() - t0
|
|
45
|
+
process.stderr.write(`[扫描] ${corpus.stats.pages} 页 / ${corpus.stats.resources} 资料 / ${corpus.stats.brokenPages} 页有断链 / ${loadMs}ms / root=${root}\n`)
|
|
46
|
+
|
|
47
|
+
if (command === 'bench') {
|
|
48
|
+
const queries = ['上下文 工程', '记忆 系统', '检索 增强', '微调', '证据 分级', '窗口']
|
|
49
|
+
for (const query of queries) {
|
|
50
|
+
const started = Date.now()
|
|
51
|
+
const result = run(corpus, { mode: 'search', query, limit: 3 })
|
|
52
|
+
const names = result.hits.map((hit) => `${hit.name}(${hit.score})`).join('、')
|
|
53
|
+
console.log(`${query.padEnd(14, ' ')} ${String(Date.now() - started).padStart(3)}ms ${result.hits.length} 命中 ${names}`)
|
|
54
|
+
}
|
|
55
|
+
return
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const started = Date.now()
|
|
59
|
+
const result = run(corpus, { mode: command, query: positional[0], name: positional[0], type: flags.type, tags: flags.tags, limit: flags.limit, pageChars: flags.chars })
|
|
60
|
+
const queryMs = Date.now() - started
|
|
61
|
+
process.stderr.write(`[查询] ${queryMs}ms\n`)
|
|
62
|
+
console.log(JSON.stringify(result, null, 2))
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
main().catch((error) => {
|
|
66
|
+
console.error(`失败:${String(error && error.stack || error)}`)
|
|
67
|
+
process.exitCode = 1
|
|
68
|
+
})
|
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# dsh-wiki-notes 的 bundle 补丁层:把本插件作为一行插进 profile 的条目列表。
|
|
2
|
+
#
|
|
3
|
+
# name 必须是【裸包名】dsh-wiki-notes,与 package.json 的 name 一致 —— dsh-web 的
|
|
4
|
+
# 客户端模块扫描只解析裸包名行,靠这行找到本包的 package.json、读到 dsh.client 字段,
|
|
5
|
+
# 才会把 lib/client.js(设置页里的「知识库」页)服务给网页。
|
|
6
|
+
- insert:
|
|
7
|
+
- id: wiki-notes
|
|
8
|
+
name: dsh-wiki-notes
|
package/docs/metrics.md
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# 检索一致性指标(v1)
|
|
2
|
+
|
|
3
|
+
这套指标回答的是一个问题:**当前引擎检索到的页,和 python 基线检索到的页,有多一致。**
|
|
4
|
+
|
|
5
|
+
它不回答「检索得准不准」。`search.py` 的排序不是标准答案,只是这套库上人类已经用了一阵的参照系。
|
|
6
|
+
真正的质量评估需要人工标注相关性(每个查询标出哪些页确实该被召回),那是另一件事,不在本文范围内。
|
|
7
|
+
|
|
8
|
+
因此本文所有指标都叫**一致性指标**,不叫质量指标。名字选错,后面所有人都会拿它当正确答案。
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 三个指标
|
|
13
|
+
|
|
14
|
+
记查询集合为 $Q$,基线对查询 $q$ 的 Top-5 为 $B_q$,当前引擎的 Top-5 为 $M_q$。
|
|
15
|
+
|
|
16
|
+
### 1. Recall@5(micro)
|
|
17
|
+
|
|
18
|
+
$$
|
|
19
|
+
\mathrm{Recall@5}=\frac{\sum_{q\in Q}|B_q\cap M_q|}{\sum_{q\in Q}|B_q|}
|
|
20
|
+
$$
|
|
21
|
+
|
|
22
|
+
- 分母是**基线槽位总数**,不是查询数。
|
|
23
|
+
- 基线里点名、但当前语料里已经不存在的页,**仍然计入分母,仍然算 miss**,同时单独累计
|
|
24
|
+
`missingFromLibrary`。不从分母里剔除 —— 剔除会让 Recall 因为库内容变化而虚高。
|
|
25
|
+
- 基线槽位不足 5 条的查询,分母按实际条数算,不补空位。
|
|
26
|
+
|
|
27
|
+
### 2. Top-1 一致率
|
|
28
|
+
|
|
29
|
+
$$
|
|
30
|
+
\mathrm{Top1}=\frac{|\{q:|B_q|\ge 1 \land B_q[0]=M_q[0]\}|}{|\{q:|B_q|\ge 1\}|}
|
|
31
|
+
$$
|
|
32
|
+
|
|
33
|
+
- 页名整串精确相等,不做大小写、别名、去后缀归一。
|
|
34
|
+
- 只比首位,不接受「首位在对方的 Top-5 里」这种放宽。
|
|
35
|
+
|
|
36
|
+
### 3. Top-5 集合一致率(Jaccard,macro)
|
|
37
|
+
|
|
38
|
+
$$
|
|
39
|
+
J(B_q,M_q)=
|
|
40
|
+
\begin{cases}
|
|
41
|
+
1 & B_q\cup M_q=\varnothing\\
|
|
42
|
+
\dfrac{|B_q\cap M_q|}{|B_q\cup M_q|} & \text{otherwise}
|
|
43
|
+
\end{cases}
|
|
44
|
+
$$
|
|
45
|
+
|
|
46
|
+
$$
|
|
47
|
+
\mathrm{Top5Jaccard}=\frac{1}{|Q|}\sum_{q\in Q}J(B_q,M_q)
|
|
48
|
+
$$
|
|
49
|
+
|
|
50
|
+
- 空并集定义为 1:两边都没结果,视为一致。不定义会得到 `NaN`,静默污染均值。
|
|
51
|
+
- 用 Jaccard 而不是除以 5:基线槽位 3~5 不等,除以 5 会让「完美召回但基线只有 3 条」的查询也只拿 60%。
|
|
52
|
+
- 用 macro(每查询等权),因为查询是实验单元。Recall@5 用 micro,是总量问题;
|
|
53
|
+
两者聚合方式不同是**故意的**,不是疏漏。
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 前置条件(缺一条就不出数)
|
|
58
|
+
|
|
59
|
+
1. **基线指纹**:`tests/local/ab_baseline.meta.json` 里的 `library.fingerprint`。
|
|
60
|
+
计算方式与导出时一致:对 `name|body.length` 排序后取 sha256 前 16 位。
|
|
61
|
+
2. **引擎版本**:报告里打印当次 `lib/engine.js` 的 git commit。
|
|
62
|
+
3. **基线版本**:v2,14 查询 / 68 槽位。不与其他历史快照混合统计。
|
|
63
|
+
|
|
64
|
+
## 判定顺序(严格按序,先中先停)
|
|
65
|
+
|
|
66
|
+
| 顺序 | 条件 | 结论 | 含义 |
|
|
67
|
+
| --- | --- | --- | --- |
|
|
68
|
+
| 1 | 没有 `WIKI_ROOT` | 跳过 | 本地回归,不是 CI 用例 |
|
|
69
|
+
| 2 | 元数据缺失 / 无指纹 | `BASELINE_STALE` | 无法证明基线对应哪份库 |
|
|
70
|
+
| 3 | 指纹不一致 | `BASELINE_STALE` | **库变了**,先重新导出基线;不判算法失败 |
|
|
71
|
+
| 4 | 指纹一致,Recall@5 < 100% | `GATE_FAIL` | **算法退步**,必须逐条解释漏项 |
|
|
72
|
+
| 5 | 其余 | `PASS` | |
|
|
73
|
+
|
|
74
|
+
指纹不一致时拒绝出数,是为了防止把「知识库自然演化」误判成「引擎回归」。
|
|
75
|
+
反过来,指纹一致还漏槽,就没有库变化这个借口了。
|
|
76
|
+
|
|
77
|
+
## 门禁
|
|
78
|
+
|
|
79
|
+
- **Recall@5 = 100% 硬门禁。** 它是回归红线。
|
|
80
|
+
- **Top-1 / Top-5 不设门禁,只记 delta。** 排序变化可能是改进;用阈值卡住,等于把
|
|
81
|
+
「和 python 一样」当成正确性。
|
|
82
|
+
|
|
83
|
+
## 报告字段
|
|
84
|
+
|
|
85
|
+
| 字段 | 用途 |
|
|
86
|
+
| --- | --- |
|
|
87
|
+
| `missingFromLibrary` | 基线页名在当前语料中不存在的数量 |
|
|
88
|
+
| `recallMisses` | 未召回的基线槽位数 |
|
|
89
|
+
| `top1Matches` | 首位完全一致的查询数 |
|
|
90
|
+
| `top5Jaccard` | 各查询 Jaccard 的均值(macro) |
|
|
91
|
+
| `gate` | `PASS` / `GATE_FAIL` / `BASELINE_STALE` |
|
|
92
|
+
|
|
93
|
+
## 退出码
|
|
94
|
+
|
|
95
|
+
| 码 | 含义 |
|
|
96
|
+
| --- | --- |
|
|
97
|
+
| 0 | PASS,或没有 `WIKI_ROOT` 而跳过 |
|
|
98
|
+
| 2 | `GATE_FAIL` |
|
|
99
|
+
| 3 | `BASELINE_STALE` |
|
|
100
|
+
|
|
101
|
+
## 本文不测什么
|
|
102
|
+
|
|
103
|
+
- 不测检索质量。没有相关性标注,就没有质量指标 —— 只有一致性。
|
|
104
|
+
- 不用这些数字调 `termScore` / `compareHits` 的权重。基线是测量工具,不是优化目标。
|
|
105
|
+
- 不覆盖 `page` / `list` / `overview` / `lint` / `draft`。它们没有「Top-5 召回」这个概念。
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# 库结构约定
|
|
2
|
+
|
|
3
|
+
这个插件不猜你的笔记怎么组织,它按下面这套约定读。**你可以只满足第一层,其余全是加分项**——
|
|
4
|
+
越往上满足,检索越准。
|
|
5
|
+
|
|
6
|
+
> **这套约定的出处**:三层结构(不可变的原始资料 / LLM 维护的 wiki / 描述规矩的 schema 文件)与
|
|
7
|
+
> `index.md` 内容目录 + `log.md` 时间线的做法,来自 Andrej Karpathy 的
|
|
8
|
+
> [`llm-wiki.md`](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)。
|
|
9
|
+
> 那份 gist 讲的是模式与理由,本文档把它落成了**插件能读的具体字段与文件名**。
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 第 0 层:最小可用(只要这一条就能用)
|
|
14
|
+
|
|
15
|
+
> 一个目录,里面放着 `.md` 文件。
|
|
16
|
+
|
|
17
|
+
满足这条,`wiki_recall` 就能按「文件名 + 正文关键词」检索。别的什么都不需要。
|
|
18
|
+
|
|
19
|
+
插件会跳过:`.` 开头的目录(如 `.obsidian`、`.git`)、`_` 开头的目录、`index.md`、`log.md`。
|
|
20
|
+
单页超过 512 KB 只记元数据,不读正文(防止某个巨型资料页把上下文吃穿)。
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 第 1 层:frontmatter 字段(决定「搜得准不准」)
|
|
25
|
+
|
|
26
|
+
页面开头的 YAML 属性块,七个字段。**缺失不报错,只是那一路加分失效。**
|
|
27
|
+
|
|
28
|
+
```markdown
|
|
29
|
+
---
|
|
30
|
+
类型: 概念
|
|
31
|
+
状态: 演进中
|
|
32
|
+
标签: [AI, 上下文]
|
|
33
|
+
别名: [Context Engineering, 上下文工程学]
|
|
34
|
+
来源数量: 3
|
|
35
|
+
创建: 2026-10-01
|
|
36
|
+
更新: 2026-10-20
|
|
37
|
+
---
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
| 字段 | 取值 | 用途 | 缺失后果 |
|
|
41
|
+
| --- | --- | --- | --- |
|
|
42
|
+
| `类型` | 概念 / 实体 / 对比 / 综合 / 资料 | 类型筛选;同分时排序(综合 > 概念/实体/对比 > 资料) | 类型筛选失效,排序退化为默认档 |
|
|
43
|
+
| `状态` | 草稿 / 演进中 / 已提纯 | 状态筛选;「这页成熟到什么程度」 | 状态筛选失效 |
|
|
44
|
+
| `标签` | `[a, b]` 或 `[a,b]`(中英文逗号都认) | 标签筛选;命中 +25 分 | 标签通道失效 |
|
|
45
|
+
| `别名` | `[a, b]` | **别名命中 +50 分**——中英文/缩写/旧称都能搜到 | 只能靠页名和正文,缩写查不到 |
|
|
46
|
+
| `来源数量` | 数字 | **证据强度的唯一可靠代理**(库里没有「可信档」字段,按它推) | 不显示证据强度 |
|
|
47
|
+
| `创建` / `更新` | `YYYY-MM-DD` | 同分时新的排前面;显示新鲜度 | 排序退化为名字序 |
|
|
48
|
+
|
|
49
|
+
资料页(`类型: 资料`)额外建议三个字段:`标题`、`作者`、`来源`,以及可选的
|
|
50
|
+
`覆盖文件`(例:`原始资料-raw/某课程/(9 篇)`),用来做「哪些页来自同一批原料」的聚集。
|
|
51
|
+
|
|
52
|
+
> 别自己发明「可信档」这种字段——它不会被读。证据强度就用 `来源数量` + `状态` 两个字段推。
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 第 2 层:`index.md`(决定「一次调用能不能直接回答」)
|
|
57
|
+
|
|
58
|
+
人工提炼的一句话摘要。**它比正文片段值钱**,因为摘要本身就是「这页讲了什么」的答案。
|
|
59
|
+
|
|
60
|
+
```markdown
|
|
61
|
+
# 索引
|
|
62
|
+
|
|
63
|
+
**当前规模**:213 份资料 · 72 个页面 · 最后更新 2026-11-02
|
|
64
|
+
|
|
65
|
+
## 概念
|
|
66
|
+
|
|
67
|
+
- [[上下文工程]] — 不是写更好的提示词,而是决定每一步把什么放进模型的视野(3 份资料,更新于 2026-10-20)
|
|
68
|
+
- [[记忆系统]] — 把「这次说过的话」变成「下次还能拿出来用的东西」的那层机制(1 份资料,更新于 2026-10-12)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
行格式:
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
- [[页名]] — 一句话摘要(N 份资料,更新于 YYYY-MM-DD)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
括号里的元数据三种写法都认:`(2 份资料,2026-11-01)`、`(2 份,2026-11-01)`、
|
|
78
|
+
`(2 份资料,更新于 2026-11-01)`。没有括号也行,整行都当摘要。
|
|
79
|
+
|
|
80
|
+
`**当前规模**:…` 这行会被 `overview` 模式原样显示,写什么就是什么。
|
|
81
|
+
|
|
82
|
+
**注意**:摘要分只在「其它通道全为 0」时才给(8 分)——只补漏、不抢位。
|
|
83
|
+
否则摘要里提过某个词的资料页会顶掉真正相关的笔记页。
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## 第 3 层:`log.md`(时间线)
|
|
88
|
+
|
|
89
|
+
只追加,不修改。每条一个二级标题:
|
|
90
|
+
|
|
91
|
+
```markdown
|
|
92
|
+
## [2026-10-15] ingest | 某课程第三讲(3 篇原始资料)
|
|
93
|
+
## [2026-10-20] query | 上下文预算怎么分配
|
|
94
|
+
## [2026-11-01] lint | 全库红链检查
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
类型(竖线前那一段)随便写,惯例是 `init` / `ingest` / `query` / `archive` / `lint` / `schema` / `fix`。
|
|
98
|
+
`overview` 模式会显示最近 5 条。
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 第 4 层:`总览-overview.md`(全库当前认知状态)
|
|
103
|
+
|
|
104
|
+
`overview` 模式会把这一页的正文整段返回。文件名认 `总览-overview.md` 或 `总览.md`。
|
|
105
|
+
|
|
106
|
+
建议写四块:这个库在讲什么 / 各页成熟度 / 未裁决的分歧 / 待补缺口。
|
|
107
|
+
它是「新会话开场先读什么」的答案——省掉模型自己拼全貌的成本。
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## 双链与红链
|
|
112
|
+
|
|
113
|
+
正文里 `[[页名]]` 或 `[[页名|显示名]]` 会被解析:
|
|
114
|
+
|
|
115
|
+
- 指向存在的页(或存在页的别名)→ 正常关系
|
|
116
|
+
- 指向不存在的页 → **红链**,工具会在结果里标出来
|
|
117
|
+
|
|
118
|
+
红链不是错误,是信号:**「这里引用了一个库里没有的判断」**。模型看到红链就知道
|
|
119
|
+
这段话缺页级支撑,转述时该降级表述。`overview` 会汇总全库红链。
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 为什么这么设计
|
|
124
|
+
|
|
125
|
+
1. **原始资料与知识分离**:`原始资料-raw/` 只读,`知识层-wiki/` 由人(或 LLM)维护。
|
|
126
|
+
压缩稿可以重写,原文不能动——否则「追源」就断了。
|
|
127
|
+
2. **索引由人写**:`index.md` 的一句话摘要必须是人(或至少是一次有判断的提炼)写的。
|
|
128
|
+
自动生成的摘要没有判断,检索时反而制造噪音。
|
|
129
|
+
3. **只追加的日志**:`log.md` 记的是「什么时候发生了什么」,改它等于篡改历史。
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 五分鐘起步
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
mkdir my-wiki && cd my-wiki
|
|
137
|
+
mkdir 概念-concepts
|
|
138
|
+
cat > 概念-concepts/示例页.md <<'EOF'
|
|
139
|
+
---
|
|
140
|
+
类型: 概念
|
|
141
|
+
状态: 草稿
|
|
142
|
+
标签: [示例]
|
|
143
|
+
别名: []
|
|
144
|
+
来源数量: 1
|
|
145
|
+
创建: 2026-11-02
|
|
146
|
+
更新: 2026-11-02
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
# 示例页
|
|
150
|
+
|
|
151
|
+
## 它是什么
|
|
152
|
+
|
|
153
|
+
一句话说清这个概念。
|
|
154
|
+
EOF
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
然后在设置 →「知识库」里填这个目录,或者:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
WIKI_ROOT="$PWD" node bin/cli.mjs search 概念
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
更完整的可跑样例见 `examples/sample-wiki/`(6 页,含 index、log、总览、红链、别名)。
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# 索引
|
|
2
|
+
|
|
3
|
+
**当前规模**:6 份资料 · 6 个页面 · 最后更新 2026-11-01
|
|
4
|
+
|
|
5
|
+
## 概念
|
|
6
|
+
|
|
7
|
+
- [[上下文工程]] — 不是写更好的提示词,而是决定每一步把什么放进模型的视野(3 份资料,更新于 2026-10-20)
|
|
8
|
+
- [[记忆系统]] — 把「这次说过的话」变成「下次还能拿出来用的东西」的那层机制(1 份资料,更新于 2026-10-12)
|
|
9
|
+
|
|
10
|
+
## 实体
|
|
11
|
+
|
|
12
|
+
- [[上下文窗口]] — 模型一次能同时看见的 token 上限(2 份资料,更新于 2026-10-18)
|
|
13
|
+
|
|
14
|
+
## 对比
|
|
15
|
+
|
|
16
|
+
- [[微调与检索增强]] — 改权重还是改上下文:两条让模型知道更多的路线怎么选(4 份资料,更新于 2026-10-22)
|
|
17
|
+
|
|
18
|
+
## 综合
|
|
19
|
+
|
|
20
|
+
- [[证据怎么分级]] — 材料的可靠性决定能不能引,但不保证引了就一定对(8 份资料,更新于 2026-11-01)
|
|
21
|
+
|
|
22
|
+
## 资料
|
|
23
|
+
|
|
24
|
+
- [[某课程第三讲·资料摘要]] — 把上下文当预算:顺序比数量重要,摘要要留数字(1 份资料,更新于 2026-10-15)
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
类型: 实体
|
|
3
|
+
状态: 草稿
|
|
4
|
+
标签: [AI, 概念实体]
|
|
5
|
+
别名: [Context Window, 上下文长度]
|
|
6
|
+
来源数量: 2
|
|
7
|
+
创建: 2026-10-03
|
|
8
|
+
更新: 2026-10-18
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# 上下文窗口
|
|
12
|
+
|
|
13
|
+
> 定义:模型一次能「同时看见」的 token 上限,包括输入与输出。
|
|
14
|
+
|
|
15
|
+
## 事实
|
|
16
|
+
|
|
17
|
+
- 是硬上限,不是软建议:超了就被截断或直接报错。
|
|
18
|
+
- 不同模型的窗口大小不同,同一模型不同版本也可能不同。
|
|
19
|
+
- 「窗口大」不代表「效果好」:中间位置的内容容易被忽略。
|
|
20
|
+
|
|
21
|
+
## 实践含义
|
|
22
|
+
|
|
23
|
+
窗口大小决定的是**上限**,实际该用多少是另一回事。多数任务在远小于上限时达到最佳性价比。
|
|
24
|
+
|
|
25
|
+
相关页:[[上下文工程]]、[[记忆系统]]
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
---
|
|
2
|
+
类型: 对比
|
|
3
|
+
状态: 演进中
|
|
4
|
+
标签: [AI, 训练, 检索]
|
|
5
|
+
别名: [Fine-tuning vs RAG, 微调对比检索]
|
|
6
|
+
来源数量: 4
|
|
7
|
+
创建: 2026-10-02
|
|
8
|
+
更新: 2026-10-22
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# 微调与检索增强
|
|
12
|
+
|
|
13
|
+
> 定义:两条让模型「知道更多」的路线——改权重,还是改上下文。
|
|
14
|
+
|
|
15
|
+
## 一句话区分
|
|
16
|
+
|
|
17
|
+
- **微调**把知识写进参数:改的是「模型会什么」。
|
|
18
|
+
- **检索增强**把知识放进上下文:改的是「模型此刻看到什么」。
|
|
19
|
+
|
|
20
|
+
## 该选哪个
|
|
21
|
+
|
|
22
|
+
| 你的问题 | 选 |
|
|
23
|
+
| --- | --- |
|
|
24
|
+
| 知识天天变,改一次就要重训 | 检索增强 |
|
|
25
|
+
| 要改的是说话风格、输出格式 | 微调 |
|
|
26
|
+
| 需要引用原文、能追溯到出处 | 检索增强 |
|
|
27
|
+
| 要在小模型上压成本、提速度 | 微调(蒸馏) |
|
|
28
|
+
|
|
29
|
+
两者不冲突:先用检索解决「不知道」,再用微调解决「不会按要求说」。
|
|
30
|
+
|
|
31
|
+
## 常见误判
|
|
32
|
+
|
|
33
|
+
把「模型答错了」直接归因于「知识不够」,然后去微调——很多时候真正的原因是
|
|
34
|
+
**上下文里根本没有那段资料**。先查检索,再谈训练。
|
|
35
|
+
|
|
36
|
+
相关页:[[上下文工程]]、[[证据怎么分级]]
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# 总览
|
|
2
|
+
|
|
3
|
+
**当前规模**:6 份资料 · 6 个页面 · 最后更新 2026-11-01
|
|
4
|
+
|
|
5
|
+
## 这个库在讲什么
|
|
6
|
+
|
|
7
|
+
一组关于「怎么把资料变成能用的判断」的笔记。主线是上下文工程,支线是证据分级与训练/检索的取舍。
|
|
8
|
+
|
|
9
|
+
## 成熟度
|
|
10
|
+
|
|
11
|
+
- [[上下文工程]] —— 演进中,四个杠杆已成框架
|
|
12
|
+
- [[证据怎么分级]] —— 演进中,分级表稳定,限制部分还在补
|
|
13
|
+
- [[微调与检索增强]] —— 演进中,选型表可用
|
|
14
|
+
- [[记忆系统]] —— 草稿,只有定义和三尺度表
|
|
15
|
+
- [[上下文窗口]] —— 草稿,事实层
|
|
16
|
+
|
|
17
|
+
## 待补缺口
|
|
18
|
+
|
|
19
|
+
- 「指代消解」还没有页,多处引用是红链
|
|
20
|
+
- 缺一个「怎么判断摘要质量」的页
|
|
21
|
+
|
|
22
|
+
## 阅读顺序
|
|
23
|
+
|
|
24
|
+
先 [[上下文工程]],再 [[记忆系统]],然后 [[微调与检索增强]],最后 [[证据怎么分级]]。
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
类型: 概念
|
|
3
|
+
状态: 演进中
|
|
4
|
+
标签: [AI, 上下文]
|
|
5
|
+
别名: [Context Engineering, 上下文工程学]
|
|
6
|
+
来源数量: 3
|
|
7
|
+
创建: 2026-10-01
|
|
8
|
+
更新: 2026-10-20
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# 上下文工程
|
|
12
|
+
|
|
13
|
+
> 定义:不是「写更好的提示词」,而是决定在每一步把哪些信息放进模型的视野、按什么顺序放、放多少。
|
|
14
|
+
|
|
15
|
+
## 为什么它比提示词工程更根本
|
|
16
|
+
|
|
17
|
+
提示词工程假设模型缺的是「话术」。上下文工程假设模型缺的是「视野」——
|
|
18
|
+
它看不到的东西,话术再怎么优化也补不上。
|
|
19
|
+
|
|
20
|
+
同一个模型,给三行摘要和给三千字原文,输出质量的差距远大于换十种 prompt 措辞。
|
|
21
|
+
|
|
22
|
+
## 四个可操作的杠杆
|
|
23
|
+
|
|
24
|
+
1. **选什么** —— 检索、摘要、压缩。决定进上下文的信息集合。
|
|
25
|
+
2. **放哪** —— 位置影响注意力。关键约束放开头和结尾,别埋中间。
|
|
26
|
+
3. **放多少** —— 上下文越长,单位 token 的信息密度越低,成本还更高。
|
|
27
|
+
4. **什么时候撤** —— 用完的信息要及时压掉,否则它会挤占后面的空间。
|
|
28
|
+
|
|
29
|
+
## 常见误区
|
|
30
|
+
|
|
31
|
+
- 把「上下文越长越好」当默认。实测多数任务在 8k 以内就能达到峰值。
|
|
32
|
+
- 用摘要替代原文去做需要精确引用的事。摘要会丢数字。
|
|
33
|
+
- 相关页:[[记忆系统]]、[[微调与检索增强]]
|