dsh-wiki-notes 1.5.0 → 1.6.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/CHANGELOG.md +47 -0
- package/README.md +23 -7
- package/lib/bridge.js +13 -1
- package/lib/calls.js +20 -4
- package/lib/corpus.js +21 -2
- package/lib/engine.js +300 -19
- package/lib/index.js +49 -38
- package/lib/jsonl-store.js +61 -7
- package/package.json +4 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# 变更记录
|
|
2
|
+
|
|
3
|
+
本文件的体例:只记「对使用者有影响的行为变化」,不记内部重构。版本号遵循 semver,`0.x` 阶段不承诺兼容。
|
|
4
|
+
|
|
5
|
+
## 1.6.0
|
|
6
|
+
|
|
7
|
+
### 检索
|
|
8
|
+
|
|
9
|
+
- **字面覆盖率兜底**:整句中文(无空格)在 AND 与 OR 双双落空时,降级为「中文二字组 / 拉丁整词」的覆盖率匹配(阈值 45%,`degraded: true`),并在结果里说明这是降级而非「库里没有」。长句查询的 Recall@5 从 23.1% 提到 61.5%。
|
|
10
|
+
- **NFKC 归一化**:全角输入(`AI`、`()`)先归一化再切词;全角查询的命中率从 0% 到 100%。
|
|
11
|
+
- **疑问词只剥两端**:`X 是什么`、`X 怎么安排` 里的问法不再当检索词;**只剥首尾**,不从前中段切(从中间切会造伪词,把一句完整查询切成两个不存在的词)。
|
|
12
|
+
- **查询长度上限 200 字符下沉到引擎**:以前只在工具层拦,`bin/cli.mjs`、设置页 `/search`、Python 桥都绕得过去。
|
|
13
|
+
- **标签 / 别名的逗号串**(`标签: a, b, c` 这种 YAML 裸标量)现在会被拆成多项,打分与 `list {tags}` 筛选口径一致(以前打分沾得上、筛选筛不到)。
|
|
14
|
+
- **`brokenLinks` 改为页级**,并复用语料层的双链解析(不再自己扫正文,避免把行内代码里的 `[[示例]]` 当断链)。
|
|
15
|
+
|
|
16
|
+
### 给模型看的解释
|
|
17
|
+
|
|
18
|
+
- **`note` 不再被吞**:`run()` 会给结果加 `status`,渲染层原来的条件导致所有 `note` 都印不出来;现在非 ok 时由 warnings 承载、ok 时由 note 承载。
|
|
19
|
+
- **`no_match` / 过滤空结果 / 覆盖率兜底** 都会说明原因(「库里没有这个主题」与「过滤条件把它排除了」是两回事)。
|
|
20
|
+
- **取页更诚实**:别名被多页共用时判 `partial` 并点名两页;命中只有 frontmatter 的空页会说明「这页没有正文」。
|
|
21
|
+
- **网关错误能印出 code**:以前只印 `知识网关调用失败:? — `,现在印 `E_PYTHON_UNAVAILABLE — …`。
|
|
22
|
+
|
|
23
|
+
### 账本与审计
|
|
24
|
+
|
|
25
|
+
- **测试不再往真实账本写**:11 个会 `apply()` 的测试文件改走临时目录,跑一遍 `npm test` 不再往「调用记录」里塞 33 条假调用。
|
|
26
|
+
- **`calls.read()` 合并顺序修正**:同一秒的多条不再倒序,轮转裁掉的旧行不再被内存补回来(窗口不再越读越长)。
|
|
27
|
+
- **JSONL 存储**:轮转阈值差一(5000 行会先长到 5001)、轮转改为 `.tmp` + `rename` 原子替换、末尾半行自动补换行(不再把新记录粘在坏行后面)、轮转按物理行计数(满盘坏行也能轮转)、`onRotate` 钩子让内存缓冲跟着裁。
|
|
28
|
+
|
|
29
|
+
### Python 桥
|
|
30
|
+
|
|
31
|
+
- **`stdin` 写入失败不再变成未捕获异常**:python 提前退出、而这边还在写大 payload 时会抛 `EPIPE`,以前会让宿主进程收到一个没人接的 error 事件;现在只记录并在错误消息里说明。
|
|
32
|
+
|
|
33
|
+
### 测试与工具
|
|
34
|
+
|
|
35
|
+
- 新增 `tests/tier.mjs`(类型层)、`tests/render.mjs`(渲染文本)、`tests/bridge.mjs`(桥的 11 条失败路径,用 `node` 冒充 python)、`tests/store.mjs`(JSONL 存储边界)、`tests/calls-read.mjs`(账本合并)。`npm test` 从 21 个文件到 **25 个**。
|
|
36
|
+
- 新增 `tests/local/recall.mjs`(质量评测:Recall@5 / Top-1 / MRR,按标签分组,低于 floor 退 2)与 `tests/local/queries.example.json`。
|
|
37
|
+
- `tools/probe.mjs` 同时接受 `--root=<path>` 与 `--root <path>`(以前只认后者,`--k=v` 会被当成参数名丢掉)。
|
|
38
|
+
|
|
39
|
+
## 1.5.0
|
|
40
|
+
|
|
41
|
+
- 本地知识网关的**双模式治理**:系统提示注入 + 四个工具的 description + 渲染层追加 + 治理账本,四层叠加约束「先查一次库、别自动升级成完整核验、结尾披露可信度」。
|
|
42
|
+
- `lib/index.js` 的 `inject` 补上 `sessions`(strict inject 下缺它会让插件整片不激活),新增 `tests/inject.mjs`。
|
|
43
|
+
- `wiki_observe` 只认 `kind: 'observe_stats'`(此前把日志事件的 kind 当成返回值的 kind,治理指标静默不合并)。
|
|
44
|
+
|
|
45
|
+
## 1.4.3
|
|
46
|
+
|
|
47
|
+
- 公开仓库的样例、契约文档与测试查询词全部换成虚构语料;发版前解包 `npm pack` 产物逐文件扫一遍。
|
package/README.md
CHANGED
|
@@ -221,9 +221,15 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
221
221
|
|
|
222
222
|
## 检索质量
|
|
223
223
|
|
|
224
|
-
|
|
224
|
+
三条线分开看,别混成一个数字:
|
|
225
225
|
|
|
226
|
-
|
|
226
|
+
- **对齐(parity)**:`tests/local/ab.mjs` 比的是「JS 引擎的前 5 是否覆盖 Python `search.py` 的前 5」,当前 **166/166,漏 0**;`tests/local/metrics.mjs` 比同一批槽位的集合与排序,Recall@5 100%、Jaccard 0.63,当硬门禁。两侧刻意保留少量已知分歧(疑问词剥离是有意改进、index 摘要 +8、类型层平局裁决),名单在本地 `tests/local/parity-exceptions.json`,**不入仓库**。
|
|
227
|
+
- **质量(recall)**:`tests/local/recall.mjs` 跑人工标注的评测集,报 Recall@5 / Top-1 / MRR@5 并按标签分组。当前基线 **Recall@5 85.2% · Top-1 76.3% · MRR 0.819**(59 条查询 / 194 个槽位),低于基线即 exit 2。评测集 `tests/local/queries.json` 含真实笔记主题,**不入仓库**;仓库里只有中性 6 条的 `queries.example.json`。
|
|
228
|
+
- **性能**:123 页扫一遍约 51ms,单条查询 4ms 上下;`tools/probe.mjs` 另攒一条 hit@1 / hit@3 / Recall@5 的趋势 CSV。
|
|
229
|
+
|
|
230
|
+
评分刻意朴素:标题全等 120 / 标题含 60 / 别名含 50 / 标签含 25 / 正文词频 ×3(封顶 36)/ index 摘要只在其它通道全 0 时补 8;同分再比类型层(综合 3 · 总览 3 / 概念·实体·对比 2 / 资料 1)→ 更新时间 → 码点序。四处经验细节:摘要分只补漏不抢位、同分用码点序(拼音序不可复现)、选节排除清单类与元讨论类小节、总览与综合同层(总览是全库唯一入口页,跨模块的词在它里面出现分量不同)。
|
|
231
|
+
|
|
232
|
+
中文连写整句在 AND / OR 双双落空时会降级到**字面覆盖率兜底**(中文二字组 / 拉丁整词,覆盖率 ≥45% 才入选,`degraded: true` 并在结果里说明),这是缓解不是语义检索;查询先做 NFKC 归一化并剥掉两端疑问词。
|
|
227
233
|
|
|
228
234
|
---
|
|
229
235
|
|
|
@@ -262,9 +268,10 @@ plugin_manager { action: "install_bundle", target: "<绝对路径>" }
|
|
|
262
268
|
|
|
263
269
|
## 已知局限
|
|
264
270
|
|
|
265
|
-
- 中文不分词,靠空格切分;连写词靠 `别名`
|
|
271
|
+
- 中文不分词,靠空格切分;连写词靠 `别名` 补。整句中文拿不到命中时会降级成字面覆盖率排序,那是**字面**匹配,语义相近但用词不同照样认不出。
|
|
266
272
|
- 页名本身是查询词时,正文很少重复该词,选节可能偏。
|
|
267
|
-
- 每次调用全量扫描;
|
|
273
|
+
- 每次调用全量扫描;123 页约 51ms,再大一个数量级要上增量索引。
|
|
274
|
+
- 每命中一页要塞约 900 字符正文(`sectionChars` 可调),一次返回 5 页就是 4–5k 字符 —— 瓶颈常在上下文预算而不在检索速度。
|
|
268
275
|
- **重启后第一次扫描是冷盘读**:95 页实测 5,217ms(此后 29ms)。插件启动就预热一次,所以这段延迟通常落在你还没提问的时候;但第一条查询正好赶上也确实要等。
|
|
269
276
|
- **面板没打开时 `/`、`Ctrl/⌘ + K` 不会有反应**:快捷键绑在面板上,而宿主的 `sidebarRightTabs` 只提供 `register()`,没有「打开 / 激活页签」的接口,插件没法从外面把面板叫出来。
|
|
270
277
|
- **知识网关那套仍是两套实现**:JS 侧 `wiki_recall` 和 Python 侧 `wiki_context` 各自解析页面,差在结构解读层。统一方向未定。
|
|
@@ -287,28 +294,37 @@ tools/probe.mjs 检索质量探针:hit@1 / hit@3 / Recall@5,追加趋势 CSV
|
|
|
287
294
|
tools/preview.mjs 把面板渲染成静态页(真组件 + 真 CSS),改样式不必重启 DSH
|
|
288
295
|
docs/库结构.md 库结构约定(这份才是一手文档)
|
|
289
296
|
docs/README.md 文档导航页
|
|
297
|
+
CHANGELOG.md 版本变更记录
|
|
290
298
|
docs/superpowers/specs/ 检索面板的设计稿
|
|
291
299
|
docs/契约-stage0/ 知识网关的设计与验收记录
|
|
292
300
|
examples/ 可跑的最小样例库
|
|
293
|
-
tests/ smoke / status / lint / explain / api / help / contract / watch / client
|
|
301
|
+
tests/ smoke / status / lint / explain / api / help / contract / watch / client
|
|
302
|
+
/ tier / render / bridge / store / calls / calls-read / gateway
|
|
303
|
+
tests/local/ 作者本机的评测集与回归基线(query 与基线文件不入仓库,只留 *.example)
|
|
304
|
+
tests/support/ 测试用小工具(quiet-ledger:把账本重定向到临时目录,别写进你的调用记录)
|
|
294
305
|
```
|
|
295
306
|
|
|
296
307
|
```bash
|
|
297
|
-
npm test #
|
|
308
|
+
npm test # 跑样例库,不需要本地知识库(25 个文件)
|
|
298
309
|
node bin/cli.mjs search 上下文 --root=examples/sample-wiki
|
|
299
310
|
WIKI_ROOT="/path/your/wiki" node tests/smoke.mjs # 拿自己的库跑通就行(不校验答案)
|
|
311
|
+
WIKI_ROOT="/path/your/wiki" node tests/local/recall.mjs # 质量评测:Recall@5 / Top-1 / MRR(低于 floor 退 2)
|
|
300
312
|
npm run probe -- --root "/path/your/wiki" # 攒一行检索质量趋势
|
|
301
313
|
node tools/preview.mjs # 出 preview/panel.html,浏览器直接看面板
|
|
302
314
|
node tools/preview.mjs --diag # 同上,并量一遍宽度 / 截断 / 溢出 / 对比度
|
|
303
315
|
```
|
|
304
316
|
|
|
317
|
+
`tests/local/` 那套要先把 `queries.example.json` 复制成 `queries.json` 再按自己的库改(`expect` 写「必须进前 5 的页名」,由人标,不依赖任何旧引擎的输出)。基线文件 `ab_baseline.json` 也是本地产物,重导用 `python ab_export.py > ab_baseline.json`。
|
|
318
|
+
|
|
305
319
|
跑知识网关那两段真实通路,要给两个环境变量(不给就整段跳过,不会假装通过):
|
|
306
320
|
|
|
307
321
|
```bash
|
|
308
322
|
WIKI_ROOT="/path/your/知识层-wiki" WIKI_TOOLS="/path/your/工具-tools" node tests/gateway.mjs
|
|
309
323
|
```
|
|
310
324
|
|
|
311
|
-
发版:改 `version` → `npm test` 全绿(`scripts.test`
|
|
325
|
+
发版:改 `version` → `npm test` 全绿(`scripts.test` 只串跑 `node tests/*.mjs`,25 个文件;`node --run test` 要 Node 22+,别在低版本上用它,也别拿它当门槛的证明)→ `npm pack --dry-run` 看一眼打包内容(`files` 只含 `lib`/`bin`/`docs`/`examples`/`README.md`/`CHANGELOG.md`/`LICENSE`/`cordis.patch.yml`,`preview/` 与 `tools/` 与 `tests/` 都不进包)→ **显式** `npm publish --registry=https://registry.npmjs.org/`。发布前先 `npm whoami --registry=https://registry.npmjs.org/` 确认已登录(本机 token 在 `.npmrc` 的 `//registry.npmjs.org/:_authToken=`;注意 `npm config get registry` 指向 npmmirror,而 npmmirror 那边不认这个 token,登录状态要显式指定 registry 去查)。发完要当场核三件事:`npm view <pkg>@<ver> dist.tarball` 取回的地址(带 fresh cache 与 REST cachebust)、下载 tarball 对 SHA256、`gh release view` 的 `isLatest`(注意它不能直接 `--json isLatest`)。
|
|
326
|
+
|
|
327
|
+
打包进了你的笔记标题怎么办:`tests/local/` 的 query 集、分歧白名单、回归基线与 `calls.jsonl` / `governance.jsonl` / `probe-history.csv` 都在 `.gitignore` 里,只在本机跑。发版前用 `git diff --cached | Select-String '<你的用户名>|<你的库路径>|<真实页名>'` 过一遍暂存区,命中就改口径再提交。
|
|
312
328
|
|
|
313
329
|
改样式的两条经验:
|
|
314
330
|
|
package/lib/bridge.js
CHANGED
|
@@ -110,6 +110,7 @@ export function runBridge({
|
|
|
110
110
|
let outBytes = 0
|
|
111
111
|
let settled = false
|
|
112
112
|
let timer = null
|
|
113
|
+
let stdinError = null
|
|
113
114
|
|
|
114
115
|
const finish = (result) => {
|
|
115
116
|
if (settled) return
|
|
@@ -169,6 +170,14 @@ export function runBridge({
|
|
|
169
170
|
if (err.join('').length > 20000) err.splice(0, err.length - 8)
|
|
170
171
|
})
|
|
171
172
|
|
|
173
|
+
// python 先退出、这边还在写大 payload 时,stdin 会抛 EPIPE/EOF。
|
|
174
|
+
// **没有这个监听它就是一个没人接的 error 事件 —— 直接把宿主进程带崩**(实测 4MB payload + 立刻 exit 的子进程)。
|
|
175
|
+
// 只记下来,不在这里结算:py 完全不读 stdin 也是合法的(比如只回一句常数),
|
|
176
|
+
// 真正成不成要看 close 时有没有输出。
|
|
177
|
+
child.stdin.on('error', (error) => {
|
|
178
|
+
stdinError = error
|
|
179
|
+
})
|
|
180
|
+
|
|
172
181
|
child.on('close', (code) => {
|
|
173
182
|
const stdout = Buffer.concat(out).toString('utf8').trim()
|
|
174
183
|
const stderr = err.join('')
|
|
@@ -177,7 +186,10 @@ export function runBridge({
|
|
|
177
186
|
finish({
|
|
178
187
|
ok: false, data: null, stderr,
|
|
179
188
|
error: errorEnvelope('E_BRIDGE_CRASH',
|
|
180
|
-
|
|
189
|
+
stdinError === null
|
|
190
|
+
? `Python 没有输出(退出码 ${code})`
|
|
191
|
+
: `Python 没有输出(退出码 ${code}),stdin 写入也失败了(${stdinError.code ?? 'EPIPE'}):它可能没读完参数就退了`,
|
|
192
|
+
'bridge', tail(`${stdinError?.message ?? ''}\n${stderr}`)),
|
|
181
193
|
})
|
|
182
194
|
return
|
|
183
195
|
}
|
package/lib/calls.js
CHANGED
|
@@ -75,7 +75,14 @@ export function normalizeEntry(raw) {
|
|
|
75
75
|
*/
|
|
76
76
|
export function createCallLog({ file, enabled = true, maxLines = MAX_LINES, keepLines = KEEP_LINES } = {}) {
|
|
77
77
|
const buffer = []
|
|
78
|
-
const store = createJsonlStore({
|
|
78
|
+
const store = createJsonlStore({
|
|
79
|
+
file, maxLines, keepLines,
|
|
80
|
+
// 轮转后文件里只剩最后 keepLines 条;内存缓冲若还留着被裁掉的那些,
|
|
81
|
+
// read() 会把它们当「文件缺的行」补回去 —— 窗口越读越长,而且补的是已经不存在的历史。
|
|
82
|
+
onRotate: ({ kept }) => {
|
|
83
|
+
while (buffer.length > kept) buffer.shift()
|
|
84
|
+
},
|
|
85
|
+
})
|
|
79
86
|
let on = enabled !== false
|
|
80
87
|
let warned = false
|
|
81
88
|
|
|
@@ -112,16 +119,25 @@ export function createCallLog({ file, enabled = true, maxLines = MAX_LINES, keep
|
|
|
112
119
|
|
|
113
120
|
function read({ limit = DEFAULT_LIMIT, source = 'all', only = 'all' } = {}) {
|
|
114
121
|
const fileRows = store.readRows()
|
|
115
|
-
//
|
|
122
|
+
// 文件里可能只有历史的一部分:要么写盘失败过(缺的是**最新**那几条),
|
|
123
|
+
// 要么被轮转/被外部删掉过(缺的是**更旧**那几条)。两种都要补回来,
|
|
124
|
+
// 但得放对位置 —— 直接往后追加会让旧行排到新行后面(真跑出来的顺序是 q2,q1,q0,q7,q6…)。
|
|
116
125
|
// 键带上 hits / ms:同一秒里两次相同的查询是不同的两件事,不该被去重吃掉。
|
|
117
126
|
const seen = new Set(fileRows.map((row) => `${row.ts}|${row.tool}|${row.query}|${row.hits}|${row.ms}`))
|
|
118
|
-
const
|
|
127
|
+
const firstTs = fileRows.length === 0 ? '' : String(fileRows[0].ts ?? '')
|
|
128
|
+
const missing = []
|
|
119
129
|
for (const row of buffer) {
|
|
120
130
|
const key = `${row.ts}|${row.tool}|${row.query}|${row.hits}|${row.ms}`
|
|
121
131
|
if (seen.has(key)) continue
|
|
122
132
|
seen.add(key)
|
|
123
|
-
|
|
133
|
+
missing.push(row)
|
|
124
134
|
}
|
|
135
|
+
// ts 只到秒,所以「同一秒」一律当成更旧(它们先写、文件后写):宁可让同秒的记录排前面,
|
|
136
|
+
// 也不要让列表撒谎。窗口最大不超过 maxLines —— 否则轮转等于没发生。
|
|
137
|
+
const older = firstTs === '' ? [] : missing.filter((row) => String(row.ts ?? '') <= firstTs)
|
|
138
|
+
const newer = firstTs === '' ? missing : missing.filter((row) => String(row.ts ?? '') > firstTs)
|
|
139
|
+
let merged = [...older, ...fileRows, ...newer]
|
|
140
|
+
if (merged.length > maxLines) merged = merged.slice(-maxLines)
|
|
125
141
|
merged.sort((a, b) => String(a.ts ?? '').localeCompare(String(b.ts ?? '')))
|
|
126
142
|
|
|
127
143
|
const scanned = merged.slice(-TOTALS_MAX)
|
package/lib/corpus.js
CHANGED
|
@@ -475,8 +475,18 @@ const TYPE_ALIASES = {
|
|
|
475
475
|
overview: '总览', note: '笔记', notes: '笔记',
|
|
476
476
|
}
|
|
477
477
|
|
|
478
|
-
|
|
479
|
-
|
|
478
|
+
/** 语义上就是列表的字段:允许多种写法,解析后统一成字符串数组。 */
|
|
479
|
+
const LIST_FIELDS = ['标签', '别名']
|
|
480
|
+
|
|
481
|
+
/** `agent, llm` / `agent、llm` / `agent;llm` → 数组;没有分隔符就原样(单标签不该被切)。 */
|
|
482
|
+
function splitListText(text) {
|
|
483
|
+
const raw = String(text).trim()
|
|
484
|
+
if (raw === '') return raw
|
|
485
|
+
const parts = raw.split(/[,,、;;]\s*/).map((part) => part.trim()).filter((part) => part !== '')
|
|
486
|
+
return parts.length > 1 ? parts : raw
|
|
487
|
+
}
|
|
488
|
+
|
|
489
|
+
export function normalizeFields(input) { const fields = { ...(input || {}) }
|
|
480
490
|
for (const [canonical, aliases] of Object.entries(FIELD_ALIASES)) {
|
|
481
491
|
if (fields[canonical] !== undefined && fields[canonical] !== '') continue
|
|
482
492
|
for (const alias of aliases) {
|
|
@@ -506,6 +516,15 @@ export function normalizeFields(input) {
|
|
|
506
516
|
}
|
|
507
517
|
if (count !== null) fields['来源数量'] = count
|
|
508
518
|
}
|
|
519
|
+
// 标签 / 别名:本库约定写成 `[a, b]`,但人手写时经常只写 `a, b`。
|
|
520
|
+
// YAML 会把裸标量整串当**一个**标签,结果「标签里明明有 agent,按标签筛却筛不到这页」——
|
|
521
|
+
// 打分那边 String.includes 能沾上,筛选那边精确比就漏了,两套口径不一致。
|
|
522
|
+
// 所以在解析层就统一成数组:有分隔符才切,单值原样留。
|
|
523
|
+
for (const key of LIST_FIELDS) {
|
|
524
|
+
if (fields[key] === undefined) continue
|
|
525
|
+
if (Array.isArray(fields[key])) continue
|
|
526
|
+
if (typeof fields[key] === 'string') fields[key] = splitListText(fields[key])
|
|
527
|
+
}
|
|
509
528
|
// 类型值:concept → 概念,好让排序分层与 list 的类型筛认得
|
|
510
529
|
const type = fields['类型']
|
|
511
530
|
if (typeof type === 'string') {
|
package/lib/engine.js
CHANGED
|
@@ -21,11 +21,75 @@ function intOption(options, key, fallback, lo, hi) {
|
|
|
21
21
|
return Math.max(lo, Math.min(value, hi))
|
|
22
22
|
}
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
// 中文疑问词。它们出现在查询里几乎从不出现在页面正文里,留着就会变成「必须同时命中」的
|
|
25
|
+
// 硬条件:`Agent Harness 是什么` 里那个「是什么」会把真正该命中的页筛掉。
|
|
26
|
+
// 只剥疑问词,不碰「的 / 了 / 和」—— 那些字在「目的」「和平」里是真词,剥了会切坏词。
|
|
27
|
+
const QUESTION_WORDS = ['是什么样的', '是什么', '什么样', '怎么样', '怎么办', '咋办', '咋整', '做什么', '怎么', '怎样', '如何', '为什么', '为何', '哪些', '哪个', '哪种', '是否', '有没有', '能不能', '要不要', '多少', '吗', '呢', '吧']
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* 剥掉查询两端的疑问词。
|
|
31
|
+
*
|
|
32
|
+
* 只剥**贴在两端**的,不从中间切:中文没有词边界,一从中间切就造伪词。
|
|
33
|
+
* 反例(真跑出来的):「甲方案的实施顺序应该怎么安排」按旧的「全局 split」切出来是
|
|
34
|
+
* 「甲方案的实施顺序应该」+「安排」——两个都不是词,AND 全落空,覆盖率兜底也没机会,
|
|
35
|
+
* 于是最该命中的那页总览反而进不了前五。
|
|
36
|
+
*
|
|
37
|
+
* 三种情形:
|
|
38
|
+
* part 整个就是一个疑问词 → 丢掉(它不含内容,留着只会当硬条件)
|
|
39
|
+
* 疑问词在头或在尾,剥完还剩 ≥2 字 → 剥
|
|
40
|
+
* 其余(含剥完不足 2 字) → 原样保留,宁可搜不到,也不把查询悄悄缩窄
|
|
41
|
+
*/
|
|
42
|
+
function stripQuestionWords(part) {
|
|
43
|
+
for (const word of QUESTION_WORDS) {
|
|
44
|
+
if (part === word) return []
|
|
45
|
+
if (part.endsWith(word)) {
|
|
46
|
+
const head = part.slice(0, part.length - word.length).trim()
|
|
47
|
+
if (head.length >= 2) return [head]
|
|
48
|
+
return [part]
|
|
49
|
+
}
|
|
50
|
+
if (part.startsWith(word)) {
|
|
51
|
+
const tail = part.slice(word.length).trim()
|
|
52
|
+
if (tail.length >= 2) return [tail]
|
|
53
|
+
return [part]
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
return [part]
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* 输入卫生:去掉两端包着的标点,丢掉既没有文字也没有数字的片段。
|
|
61
|
+
*
|
|
62
|
+
* 两件真事逼出来的:`???` 经 NFKC 变成 `???` 会当成一个检索词(结果页显示「没有命中」,
|
|
63
|
+
* 但实际上查询本身就没内容,该报空查询);`"引号"` 带着引号去匹配,永远只能落在覆盖率兜底。
|
|
64
|
+
* 只去引号/括号/句读,不动 `+ # . _ -`:`C#`、`F#`、`node.js` 里的符号是词的一部分。
|
|
65
|
+
*/
|
|
66
|
+
const EDGE_PUNCT = /^["'“”‘’「」『』()()《》〈〉【】[\]!?!?。,,、;;::]+|["'“”‘’「」『』()()《》〈〉【】[\]!?!?。,,、;;::]+$/g
|
|
67
|
+
const HAS_WORD_CHAR = /[\p{L}\p{N}]/u
|
|
68
|
+
|
|
69
|
+
function cleanPart(part) {
|
|
70
|
+
return part.replace(EDGE_PUNCT, '').trim()
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* 把用户 query 拆成检索词。中文没有空格,所以整句当一个词;有空格才算多词 AND。
|
|
75
|
+
*
|
|
76
|
+
* 两处归一化,都是被评测集逼出来的(queries.json 的「全角」「中英混写」两组):
|
|
77
|
+
* NFKC —— 全角「RAG」要能命中半角「RAG」。search.py 第一步就是这一步,之前这边漏了。
|
|
78
|
+
* 疑问词剥离 —— 见 QUESTION_WORDS,不让「是什么」当硬条件。
|
|
79
|
+
*/
|
|
25
80
|
export function tokenize(query) {
|
|
26
|
-
|
|
81
|
+
// 200 字上限放在这里,而不是只放在工具层:CLI、设置页 /search、Python 桥都走这条路,
|
|
82
|
+
// 上一层拦住的长度到这里不该又变回一个 300 字的「词元」——它会拖慢每个页面的比对,
|
|
83
|
+
// 还会被原样回显进 note(`"<整段查询>" 被当成一个词元`)。
|
|
84
|
+
const trimmed = String(query ?? '').normalize('NFKC').trim().slice(0, MAX_QUERY_CHARS)
|
|
27
85
|
if (trimmed === '') return []
|
|
28
|
-
const
|
|
86
|
+
const rawParts = trimmed
|
|
87
|
+
.split(/[\s,,、。;;/|]+/)
|
|
88
|
+
.map((part) => cleanPart(part))
|
|
89
|
+
.filter((part) => part !== '' && HAS_WORD_CHAR.test(part))
|
|
90
|
+
// 整条查询就是一个疑问词(「多少」「怎么样」)时退回原样:宁可搜不到,也不把查询悄悄变成空
|
|
91
|
+
const stripped = rawParts.flatMap(stripQuestionWords)
|
|
92
|
+
const parts = stripped.length > 0 ? stripped : rawParts
|
|
29
93
|
// 去重但保留顺序
|
|
30
94
|
const seen = new Set()
|
|
31
95
|
const out = []
|
|
@@ -145,8 +209,15 @@ function explainTerms(page, indexLine, tokens) {
|
|
|
145
209
|
*/
|
|
146
210
|
const INDEX_ONLY_SCORE = 8
|
|
147
211
|
|
|
148
|
-
/**
|
|
149
|
-
|
|
212
|
+
/**
|
|
213
|
+
* 类型分层:同分时结构化笔记优先于原始资料摘要 —— 笔记是消化过的结论。
|
|
214
|
+
*
|
|
215
|
+
* 总览放在最高一档而不是默认档:它是全库唯一的入口页,一个跨模块的词(「复盘」「数据」
|
|
216
|
+
* 这类)在总览里出现的意义,和它在某个模块综合页里出现的意义不是一回事。2026-11-08 用
|
|
217
|
+
* tests/local/ab_export.py 重导基线后暴露:某一查询里总览与某个模块综合页同分 15,
|
|
218
|
+
* 按旧表(总览落到默认档 2)被挤到第 6 位,与 search.py 的前 5 不一致。
|
|
219
|
+
*/
|
|
220
|
+
const TYPE_TIER = { 综合: 3, 总览: 3, 概念: 2, 实体: 2, 对比: 2, 资料: 1 }
|
|
150
221
|
|
|
151
222
|
function typeTier(page) {
|
|
152
223
|
return TYPE_TIER[String(page.fields['类型'] ?? '')] ?? 2
|
|
@@ -293,6 +364,89 @@ function oversizedRelevance(corpus, tokens, indexMap) {
|
|
|
293
364
|
return { total, via }
|
|
294
365
|
}
|
|
295
366
|
|
|
367
|
+
// 字面覆盖率兜底的阈值,与 search.py 的 COVERAGE_MIN 取同一个数。
|
|
368
|
+
// 低于这条线不是「相关性弱」,是「根本不像在说同一件事」,放进结果里只会骗人。
|
|
369
|
+
const COVERAGE_MIN = 0.45
|
|
370
|
+
// 查询长度上限,与工具层 schema 的意思对齐(那边拦的是模型,这里拦的是 CLI / /search / 桥)。
|
|
371
|
+
const MAX_QUERY_CHARS = 200
|
|
372
|
+
const CJK_RE = /[\u3400-\u9fff]/
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* 把查询切成「字面原子」:中文按二字组、拉丁按整词。
|
|
376
|
+
*
|
|
377
|
+
* 为什么需要这一步:中文没有空格,一句「甲方案的实施顺序应该怎么安排」在 tokenize 眼里
|
|
378
|
+
* 就是**一个词元**,而库里不可能逐字出现这句话,于是 AND、OR 双双落空。用户看到的是
|
|
379
|
+
* 「库里没有」,可库里明明有一页在讲这件事。search.py 的降级层就是干这个的,
|
|
380
|
+
* 这里补上同一层,只在前面全落空时才启用。
|
|
381
|
+
*/
|
|
382
|
+
function coverageAtomsOf(text) {
|
|
383
|
+
const atoms = []
|
|
384
|
+
const seen = new Map()
|
|
385
|
+
const push = (atom, weight) => {
|
|
386
|
+
const previous = seen.get(atom) ?? 0
|
|
387
|
+
if (previous >= weight) return
|
|
388
|
+
if (previous === 0) atoms.push(atom)
|
|
389
|
+
seen.set(atom, weight)
|
|
390
|
+
}
|
|
391
|
+
for (const chunk of String(text).match(/[\u3400-\u9fff]+|[A-Za-z0-9][A-Za-z0-9._+#-]*/g) ?? []) {
|
|
392
|
+
if (CJK_RE.test(chunk)) {
|
|
393
|
+
if (chunk.length === 1) push(chunk, 1)
|
|
394
|
+
else for (let i = 0; i < chunk.length - 1; i += 1) push(chunk.slice(i, i + 2), 1)
|
|
395
|
+
} else {
|
|
396
|
+
// 一个拉丁词比一个二字组信息量大:权重 3,与 search.py 的整段权重对齐
|
|
397
|
+
push(chunk.toLowerCase(), 3)
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
return atoms.map((atom) => ({ atom, weight: seen.get(atom) ?? 1 }))
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
/**
|
|
404
|
+
* 覆盖率通道:不要求整句出现,只要求「查询里的字面片段在这页出现了多少」。
|
|
405
|
+
* 分数刻意做成覆盖率 × 100 + 结构加分,量级远低于正常命中(页名全等 120),
|
|
406
|
+
* 所以它永远排在真命中后面 —— 这一层只负责「别报空」。
|
|
407
|
+
*/
|
|
408
|
+
function coveragePass(corpus, tokens, { typeFilter, tagFilter }) {
|
|
409
|
+
const atoms = coverageAtomsOf(tokens.join(' '))
|
|
410
|
+
const totalWeight = atoms.reduce((sum, item) => sum + item.weight, 0)
|
|
411
|
+
if (atoms.length === 0 || totalWeight === 0) return []
|
|
412
|
+
const indexMap = buildIndexMap(corpus)
|
|
413
|
+
const out = []
|
|
414
|
+
for (const page of corpus.pages) {
|
|
415
|
+
if (page.oversized === true) continue
|
|
416
|
+
if (typeFilter !== null && String(page.fields['类型'] ?? '') !== typeFilter) continue
|
|
417
|
+
if (tagFilter.length > 0) {
|
|
418
|
+
const pageTags = asList(page.fields['标签'])
|
|
419
|
+
if (!tagFilter.some((tag) => matchesTag(pageTags, tag))) continue
|
|
420
|
+
}
|
|
421
|
+
const body = page.body.toLowerCase()
|
|
422
|
+
const title = page.name.toLowerCase()
|
|
423
|
+
const aliasText = asList(page.fields['别名']).join(' ').toLowerCase()
|
|
424
|
+
const tagText = asList(page.fields['标签']).join(' ').toLowerCase()
|
|
425
|
+
let hitWeight = 0
|
|
426
|
+
const hitAtoms = []
|
|
427
|
+
for (const { atom, weight } of atoms) {
|
|
428
|
+
if (!body.includes(atom)) continue
|
|
429
|
+
hitWeight += weight
|
|
430
|
+
hitAtoms.push(atom)
|
|
431
|
+
}
|
|
432
|
+
const coverage = hitWeight / totalWeight
|
|
433
|
+
if (coverage < COVERAGE_MIN) continue
|
|
434
|
+
let bonus = 0
|
|
435
|
+
if (hitAtoms.some((atom) => title.includes(atom))) bonus += 20
|
|
436
|
+
if (hitAtoms.some((atom) => aliasText.includes(atom))) bonus += 10
|
|
437
|
+
if (hitAtoms.some((atom) => tagText.includes(atom))) bonus += 5
|
|
438
|
+
out.push({
|
|
439
|
+
page,
|
|
440
|
+
indexLine: indexMap.get(page.name) ?? null,
|
|
441
|
+
score: Math.round(coverage * 100) + bonus,
|
|
442
|
+
matched: hitAtoms.length,
|
|
443
|
+
allTerms: false,
|
|
444
|
+
atoms: hitAtoms,
|
|
445
|
+
})
|
|
446
|
+
}
|
|
447
|
+
return out
|
|
448
|
+
}
|
|
449
|
+
|
|
296
450
|
/**
|
|
297
451
|
* mode 2:search
|
|
298
452
|
* 返回 hits(按分数降序),每项带索引摘要、命中小节正文、citation、断链。
|
|
@@ -353,14 +507,32 @@ export function search(corpus, query, options = {}) {
|
|
|
353
507
|
list = scored
|
|
354
508
|
}
|
|
355
509
|
|
|
510
|
+
// 最后一道兜底:AND 和 OR 都一条没有,但查询本身是「一句话」时,用字面覆盖率再找一遍。
|
|
511
|
+
// 只在结果为 0 时启用 —— 有任何一条真命中就不碰,所以它不可能把好结果挤掉。
|
|
512
|
+
let coverageFallback = false
|
|
513
|
+
if (list.length === 0) {
|
|
514
|
+
const covered = coveragePass(corpus, tokens, { typeFilter, tagFilter })
|
|
515
|
+
if (covered.length > 0) {
|
|
516
|
+
coverageFallback = true
|
|
517
|
+
degraded = true
|
|
518
|
+
list = covered
|
|
519
|
+
}
|
|
520
|
+
}
|
|
521
|
+
|
|
356
522
|
list.sort(compareHits)
|
|
357
523
|
|
|
524
|
+
// 覆盖率通道下,整句作为一个词元在正文里必然找不到,选节会退化成「取第一段」。
|
|
525
|
+
// 改用命中的字面片段去选节:pickSection 本身没动,只是换了喂进去的词。
|
|
526
|
+
const sectionTokensOf = (item) => (coverageFallback ? item.atoms ?? tokens : tokens)
|
|
527
|
+
|
|
358
528
|
const hits = list.slice(0, limit).map((item) => {
|
|
359
|
-
const section = pickSection(item.page,
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
529
|
+
const section = pickSection(item.page, sectionTokensOf(item))
|
|
530
|
+
// 断链按整页算,不按命中小节算:选节会把页面截成一段,断链常落在文末的「相关」里,
|
|
531
|
+
// 只报小节内的会让模型把「这一页没有断链」当成结论 —— README 给它的语义是页级硬信号。
|
|
532
|
+
// 复用 corpus 已经解析好的 page.links,而不是在这里再扫一遍正文:
|
|
533
|
+
// 那边会跳过行内代码里的 `[[示例]]`(那是举例,不是链接),这边自己扫就会把示例当红链。
|
|
534
|
+
const broken = [...new Set(item.page.links ?? [])]
|
|
535
|
+
.filter((link) => !corpus.byName.has(link) && !corpus.byAlias.has(link.toLowerCase()))
|
|
364
536
|
return {
|
|
365
537
|
name: item.page.name,
|
|
366
538
|
kind: pageKind(item.page),
|
|
@@ -384,6 +556,23 @@ export function search(corpus, query, options = {}) {
|
|
|
384
556
|
|
|
385
557
|
const oversized = oversizedRelevance(corpus, tokens, indexMap)
|
|
386
558
|
|
|
559
|
+
// 单字查询命中过半页时,排序确实没有区分度(「的」「a」会命中几乎整库)。
|
|
560
|
+
// 不改结果——改了就是动排序,那是 §13.1 的地界;但必须让模型知道这批结果别当真。
|
|
561
|
+
const trivialQuery = tokens.length === 1 && tokens[0].length <= 1 && considered > 20 && scored.length >= considered * 0.5
|
|
562
|
+
|
|
563
|
+
// 过滤器把候选清空时,「这次没命中」和「库里根本没这种页」是两件事。
|
|
564
|
+
// 不说清楚,模型会把「库里没有资料类型的页」读成「库里没有这个主题」。
|
|
565
|
+
// 还有第三种:过了滤、也有页参与,但整句一页都没命中 —— 那时同样得说话,
|
|
566
|
+
// 否则「词不对」和「命中页被 type 过滤掉了」在模型看来长得一模一样(真库实测过)。
|
|
567
|
+
const filterApplied = typeFilter !== null || tagFilter.length > 0
|
|
568
|
+
const filterNote = !filterApplied
|
|
569
|
+
? ''
|
|
570
|
+
: considered === 0
|
|
571
|
+
? filterEmptyNote(corpus, typeFilter, tagFilter)
|
|
572
|
+
: (scored.length === 0 && list.length === 0
|
|
573
|
+
? `过滤后仍有 ${considered} 页参与检索,但整句没有命中任何一页(字面覆盖率兜底 ${Math.round(COVERAGE_MIN * 100)}% 也没过)。这可能是词不对,也可能命中的页被 type/tags 过滤掉了——去掉过滤再搜一次就能分开。`
|
|
574
|
+
: '')
|
|
575
|
+
|
|
387
576
|
return {
|
|
388
577
|
mode: 'search',
|
|
389
578
|
query,
|
|
@@ -392,14 +581,20 @@ export function search(corpus, query, options = {}) {
|
|
|
392
581
|
// 这三件事决定「结果为空」该怪词、怪库,还是怪匹配模式。
|
|
393
582
|
// missedTerms / matchMode 常驻(模型看到「这个词没用上」才可能换词重查,成本两个短字段);
|
|
394
583
|
// 每个词在多少页上得分的明细只有 explain 时才给,那是面板的事。
|
|
395
|
-
|
|
584
|
+
// 覆盖率兜底下调时不能报「这些词一页都没命中」——命中正是靠这些词的字面片段捞到的,
|
|
585
|
+
// 两句话放在一起自相矛盾,note 里已经交代清楚。
|
|
586
|
+
missedTerms: coverageFallback ? [] : tokens.filter((token) => (termPages.get(token) ?? 0) === 0),
|
|
396
587
|
matchMode: degraded ? 'or' : 'and',
|
|
588
|
+
// 覆盖率兜底是 or 的下一层(仍标 matchMode/or 以保持面板与既有断言的两值语义),
|
|
589
|
+
// 但必须单独标出来:这时候「命中」只是字面沾边,精度比 OR 更低,模型叙述时要收着写。
|
|
590
|
+
coverageFallback,
|
|
591
|
+
trivialQuery,
|
|
397
592
|
...(explain ? { termPages: tokens.map((token) => ({ term: token, pages: termPages.get(token) ?? 0 })) } : {}),
|
|
398
593
|
total: list.length,
|
|
399
594
|
degraded,
|
|
400
595
|
// 调用级统计:分母各是各的,别合成一个数字
|
|
401
596
|
considered,
|
|
402
|
-
matched: scored.length,
|
|
597
|
+
matched: coverageFallback ? list.length : scored.length,
|
|
403
598
|
allTerms: scored.filter((item) => item.allTerms).length,
|
|
404
599
|
returned: hits.length,
|
|
405
600
|
// 超大页里「标题或 index 摘要」沾到查询词的数量:决定这次要不要提醒覆盖缺口,
|
|
@@ -407,10 +602,42 @@ export function search(corpus, query, options = {}) {
|
|
|
407
602
|
oversizedRelevant: oversized.total,
|
|
408
603
|
oversizedRelevantVia: oversized.via,
|
|
409
604
|
hits,
|
|
410
|
-
note:
|
|
605
|
+
note: filterNote
|
|
606
|
+
|| (coverageFallback
|
|
607
|
+
? `整句没有命中任何页(中文不分词,"${query}" 被当成一个词元),已降级为字面覆盖率匹配(≥${Math.round(COVERAGE_MIN * 100)}%)。结果只作线索:命中是字面沾边,不是这页回答了你。`
|
|
608
|
+
: degraded
|
|
609
|
+
? '没有同时命中全部检索词,已降级为 OR(命中任一):命中面变宽、精度下降'
|
|
610
|
+
: trivialQuery
|
|
611
|
+
? `查询只有一个字("${tokens[0]}"),它在这 ${considered} 页里出现了 ${scored.length} 页——这个字到处都有,排序没有区分度。换个更具体的词再搜。`
|
|
612
|
+
: ''),
|
|
411
613
|
}
|
|
412
614
|
}
|
|
413
615
|
|
|
616
|
+
/** 过滤器把候选清空时,说清楚是「库里没这种页」而不是「库里没这个主题」。 */
|
|
617
|
+
function filterEmptyNote(corpus, typeFilter, tagFilter, statusFilter = null) {
|
|
618
|
+
const dist = new Map()
|
|
619
|
+
const statuses = new Map()
|
|
620
|
+
for (const page of corpus.pages) {
|
|
621
|
+
if (page.oversized === true) continue
|
|
622
|
+
const type = String(page.fields['类型'] ?? '') || '(无类型)'
|
|
623
|
+
dist.set(type, (dist.get(type) ?? 0) + 1)
|
|
624
|
+
const status = String(page.fields['状态'] ?? '') || '(无状态)'
|
|
625
|
+
statuses.set(status, (statuses.get(status) ?? 0) + 1)
|
|
626
|
+
}
|
|
627
|
+
const tally = (map) => [...map.entries()]
|
|
628
|
+
.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0], 'zh'))
|
|
629
|
+
.map(([key, count]) => `${key} ${count}`)
|
|
630
|
+
.join(' / ')
|
|
631
|
+
const asked = [
|
|
632
|
+
typeFilter === null ? '' : `type=${typeFilter}`,
|
|
633
|
+
statusFilter === null ? '' : `status=${statusFilter}`,
|
|
634
|
+
tagFilter.length === 0 ? '' : `tags=${tagFilter.join('/')}`,
|
|
635
|
+
].filter((part) => part !== '').join(' ')
|
|
636
|
+
const typeShown = tally(dist)
|
|
637
|
+
const statusShown = tally(statuses)
|
|
638
|
+
return `库里没有符合 ${asked} 的页(现有类型:${typeShown === '' ? '无' : typeShown}${statusFilter === null ? '' : `;现有状态:${statusShown === '' ? '无' : statusShown}`})。这是过滤条件的问题,不是主题不存在——去掉过滤再搜。`
|
|
639
|
+
}
|
|
640
|
+
|
|
414
641
|
/** mode 2:page —— 按页名/别名/模糊取整页。取不到就给最像的 5 个候选。 */
|
|
415
642
|
export function page(corpus, name, options = {}) {
|
|
416
643
|
const wanted = String(name ?? '').trim()
|
|
@@ -419,12 +646,24 @@ export function page(corpus, name, options = {}) {
|
|
|
419
646
|
|
|
420
647
|
const indexMap = buildIndexMap(corpus)
|
|
421
648
|
const exact = corpus.byName.get(wanted) ?? corpus.byName.get(wanted.replace(/\.md$/i, ''))
|
|
422
|
-
if (exact !== undefined)
|
|
649
|
+
if (exact !== undefined) {
|
|
650
|
+
const found = renderPage(corpus, exact, indexMap, limit)
|
|
651
|
+
const note = pageBodyNote(found)
|
|
652
|
+
return { mode: 'page', found, candidates: [], ...(note === '' ? {} : { note }) }
|
|
653
|
+
}
|
|
423
654
|
|
|
424
655
|
const aliasHits = corpus.byAlias.get(wanted.toLowerCase()) ?? []
|
|
425
656
|
if (aliasHits.length > 0) {
|
|
426
657
|
const first = aliasHits[0]
|
|
427
|
-
return {
|
|
658
|
+
return {
|
|
659
|
+
mode: 'page',
|
|
660
|
+
found: renderPage(corpus, first, indexMap, limit),
|
|
661
|
+
candidates: [],
|
|
662
|
+
// 别名是检索入口,被两页共用时「按名字取页」就是抛硬币 —— 必须点名,别让引用悄悄指错。
|
|
663
|
+
...(aliasHits.length > 1
|
|
664
|
+
? { note: aliasCollisionNote(aliasHits, first, wanted), aliasConflict: true }
|
|
665
|
+
: {}),
|
|
666
|
+
}
|
|
428
667
|
}
|
|
429
668
|
|
|
430
669
|
// 模糊:包含关系 → 相似度
|
|
@@ -457,6 +696,18 @@ export function page(corpus, name, options = {}) {
|
|
|
457
696
|
}
|
|
458
697
|
}
|
|
459
698
|
|
|
699
|
+
/** 命中的页没有正文时会话里最容易出的错:模型引用一个空页当依据。 */
|
|
700
|
+
function pageBodyNote(found) {
|
|
701
|
+
const body = typeof found?.body === 'string' ? found.body.trim() : ''
|
|
702
|
+
return body === '' ? '这页没有正文(只有 frontmatter 或文件是空的):别把它当依据,回到原始资料或换一页' : ''
|
|
703
|
+
}
|
|
704
|
+
|
|
705
|
+
/** 别名被多页共用:按别名取页等于抛硬币,点名让人改。 */
|
|
706
|
+
function aliasCollisionNote(aliasHits, chosen, wanted) {
|
|
707
|
+
const names = aliasHits.map((item) => `${item.name}(${item.file})`).join('、')
|
|
708
|
+
return `别名「${wanted}」被 ${aliasHits.length} 页共用:${names};这次给的是 ${chosen.name}。引用前先确认是哪一篇,或把别名改成唯一。`
|
|
709
|
+
}
|
|
710
|
+
|
|
460
711
|
function renderPage(corpus, page, indexMap, limit) {
|
|
461
712
|
const body = clip(page.body, limit)
|
|
462
713
|
return {
|
|
@@ -507,6 +758,13 @@ export function list(corpus, options = {}) {
|
|
|
507
758
|
const limit = intOption(options, 'limit', 40, 1, 200)
|
|
508
759
|
const shown = rows.slice(0, limit)
|
|
509
760
|
|
|
761
|
+
// 空目录同样要区分「库里没这种页」与「库里没这个东西」:list 的调用方拿到的是一张空表,
|
|
762
|
+
// 不给一句话它只能猜。与 search 的 filterEmptyNote() 同一套说法,维度多一个 status。
|
|
763
|
+
const filtered = typeFilter !== null || statusFilter !== null || tagFilter.length > 0
|
|
764
|
+
const note = rows.length === 0 && filtered
|
|
765
|
+
? filterEmptyNote(corpus, typeFilter, tagFilter, statusFilter)
|
|
766
|
+
: ''
|
|
767
|
+
|
|
510
768
|
return {
|
|
511
769
|
mode: 'list',
|
|
512
770
|
total: rows.length,
|
|
@@ -515,6 +773,7 @@ export function list(corpus, options = {}) {
|
|
|
515
773
|
byType,
|
|
516
774
|
scale: corpus.scaleLine,
|
|
517
775
|
rows: shown,
|
|
776
|
+
...(note === '' ? {} : { note }),
|
|
518
777
|
}
|
|
519
778
|
}
|
|
520
779
|
|
|
@@ -1041,23 +1300,45 @@ export function decideStatus(corpus, mode, args = {}, result = {}) {
|
|
|
1041
1300
|
warnings.push(dupWarning)
|
|
1042
1301
|
return { status: 'partial', warnings }
|
|
1043
1302
|
}
|
|
1303
|
+
// 别名被多页共用与同名页是同一类风险(引错版本),只是入口不同:一个按页名,一个按别名。
|
|
1304
|
+
if (mode === 'page' && result.aliasConflict === true) {
|
|
1305
|
+
warnings.push(engineNote(result) || '这个别名被多页共用,这次给的不一定是你要的那篇')
|
|
1306
|
+
return { status: 'partial', warnings }
|
|
1307
|
+
}
|
|
1044
1308
|
if (mode === 'search' && result.degraded === true) {
|
|
1045
1309
|
// 降级与「超大页可能相关」可以同时成立:状态按约定取 degraded,但两条事实都要输出 ——
|
|
1046
1310
|
// 别让一个状态值把覆盖缺口吞掉。
|
|
1047
1311
|
if (oversizedHit) warnings.push(oversizedWarning)
|
|
1048
|
-
|
|
1312
|
+
// 引擎自己知道这次是「命中任一词」还是「整句只沾字面」(覆盖率兜底),
|
|
1313
|
+
// 让它的说法优先:模型要做的动作不一样 —— 前者该收窄词,后者该换更短的词或直接查页面。
|
|
1314
|
+
// 固定文案只当兜底(老调用方不带 note 时)。
|
|
1315
|
+
warnings.push(engineNote(result)
|
|
1316
|
+
|| '只命中部分检索词,已降级为 OR:命中面变宽、精度下降;想收窄就改用页面标题或更少的词重查一次')
|
|
1049
1317
|
return { status: 'degraded', warnings }
|
|
1050
1318
|
}
|
|
1051
1319
|
if (oversizedHit) {
|
|
1320
|
+
// 目录/检索为空而库里恰好有超大页时,两件事都得说:先说「为什么是空的」(可能是过滤条件写错),
|
|
1321
|
+
// 再说「还漏了超大页」。只报后者的话,模型会以为过滤是对的、只是内容太大。
|
|
1322
|
+
const why = engineNote(result)
|
|
1323
|
+
if (why !== '') warnings.push(why)
|
|
1052
1324
|
warnings.push(oversizedWarning)
|
|
1053
1325
|
return { status: 'partial', warnings }
|
|
1054
1326
|
}
|
|
1055
|
-
|
|
1327
|
+
// 零命中也要带上「为什么零命中」:过滤器清空与主题不存在是两件事,
|
|
1328
|
+
// 引擎写在 note 里的那句话如果在这里丢掉,模型只能自己猜。
|
|
1329
|
+
if (empty) {
|
|
1330
|
+
const why = engineNote(result)
|
|
1331
|
+
return { status: 'no_match', warnings: why === '' ? [] : [why] }
|
|
1332
|
+
}
|
|
1056
1333
|
return { status: 'ok', warnings: [] }
|
|
1057
1334
|
}
|
|
1058
1335
|
|
|
1059
|
-
/**
|
|
1060
|
-
function
|
|
1336
|
+
/** 引擎写好的那句话(降级原因 / 单字无区分度),没有就返回空串。 */
|
|
1337
|
+
function engineNote(result) {
|
|
1338
|
+
return typeof result?.note === 'string' ? result.note.trim() : ''
|
|
1339
|
+
}
|
|
1340
|
+
|
|
1341
|
+
/** 把「超大页靠什么沾上查询词」翻成一句人话,别在 warnings 里塞枚举值。 */function viaText(via) {
|
|
1061
1342
|
if (via === '标题') return '标题命中查询词'
|
|
1062
1343
|
if (via === '摘要') return 'index 摘要命中查询词'
|
|
1063
1344
|
return '标题或 index 摘要命中查询词'
|
package/lib/index.js
CHANGED
|
@@ -207,11 +207,11 @@ const PARAMETERS = {
|
|
|
207
207
|
* 「必须 / 不得 / 先…再…」这几条得真的落在模型看得见的描述里。
|
|
208
208
|
*/
|
|
209
209
|
const RECALL_TRIGGERS =
|
|
210
|
-
'
|
|
210
|
+
'涉及本地知识、笔记原文或需要引用库内依据时,必须且只调用一次 wiki_recall;不得反复检索,不得在普通快速回答里自动转去 wiki_context / wiki_verify。'
|
|
211
211
|
const CONTEXT_TRIGGERS =
|
|
212
|
-
'
|
|
212
|
+
'用户明确要求查看原文时,必须且仅按需调用一次 wiki_context;明确要求核验,或问题涉及高风险、后果重大的重要事实,或库内存在复杂冲突时,必须先调用 wiki_context 再进入深度核验;不得在普通快速回答里自动调用 wiki_context。'
|
|
213
213
|
const VERIFY_TRIGGERS =
|
|
214
|
-
'
|
|
214
|
+
'只有进入深度核验模式,才必须用 wiki_verify 核验候选答案;不得因答案含数字、引文或未填槽位就在快速回答里自动核验,不得绕过 violations_found。'
|
|
215
215
|
const OBSERVE_TRIGGERS =
|
|
216
216
|
'要查核验链有没有收敛、违规有没有被改正时,必须用 wiki_observe 看观察统计;不得用日志缺行反推结论。'
|
|
217
217
|
|
|
@@ -221,42 +221,40 @@ const OBSERVE_TRIGGERS =
|
|
|
221
221
|
* 每个拟议模型步骤重算 text 时拿到的都是同一段常量。
|
|
222
222
|
*/
|
|
223
223
|
const GOVERNANCE_TEXT = [
|
|
224
|
-
'
|
|
225
|
-
'-
|
|
226
|
-
'-
|
|
227
|
-
'-
|
|
228
|
-
'-
|
|
229
|
-
'-
|
|
230
|
-
'-
|
|
231
|
-
'- 纯通用常识且回答不依赖本地知识库时,可以跳过检索。凡涉及本地知识、笔记原文或需要引用库内依据的内容,应先检索。检索无结果不代表知识库不存在对应内容。',
|
|
224
|
+
'本地知识网关的双模式纪律(凡用到本地知识库就适用):',
|
|
225
|
+
'- 默认快速回答:命中库内已知线索、个人记录、长期整理的领域,或要求引用 / 转述 / 核对笔记原文时,先调用一次 wiki_recall 查库再作答;纯通用常识且回答不依赖本地知识库时可跳过检索,检索无结果不代表知识库不存在对应内容。',
|
|
226
|
+
'- 快速回答只调用一次 wiki_recall,据检索结果直接作答;不得自动调用 wiki_context / wiki_verify,不反复检索、不自我验证。',
|
|
227
|
+
'- 快速回答结尾加一句简短可信度提醒;status 非 ok、warnings 非空、零命中或正文被截断时须明说资料不足,不为回答而编造,也不偷偷启动多轮检索。',
|
|
228
|
+
'- 深度核验按需启用:用户只想查看原文时,可仅按需调用一次 wiki_context;明确要求核验,或问题涉及高风险、后果重大的重要事实,或库内存在复杂冲突时,才先调用 wiki_context 取结构化证据,再用 wiki_verify 核验候选答案;普通数字题、概念题不升级。',
|
|
229
|
+
'- 深度核验发现违规时定向修正答案,不得绕过 violations_found;最多再核验一次,复核仍有违规即停止并披露,不得无限循环、不能悄悄收尾。',
|
|
230
|
+
'- 多页 / 多来源时须披露证据边界与来源独立性;不承诺核验一般性跨页推导。数字或引文本身不触发强制核验,只有进入深度模式才核验。',
|
|
232
231
|
].join('\n')
|
|
233
232
|
|
|
234
233
|
const DESCRIPTION = `本地 LLM-Wiki 知识库检索(只读,不会改动任何文件)。
|
|
235
234
|
|
|
236
235
|
何时必须调用(命中任一):
|
|
237
|
-
-
|
|
236
|
+
- 涉及库内已知线索:页名、别名、标签或注入的主题词;
|
|
238
237
|
- 问个人记录(「我之前怎么记的」「笔记里写了什么」);
|
|
239
|
-
-
|
|
238
|
+
- 涉及长期整理的学科或领域;
|
|
240
239
|
- 点名具体工具、框架、模型、项目、论文;
|
|
241
240
|
- 要求引用、转述、核对笔记原文;
|
|
242
|
-
-
|
|
241
|
+
- 下判断、写结论或回写新页之前:先查再动笔。
|
|
243
242
|
|
|
244
|
-
|
|
245
|
-
|
|
243
|
+
何时可以不查:纯通用常识且不依赖本地知识库时跳过。
|
|
244
|
+
默认快速回答:只调用一次 wiki_recall,据结果直接答,不自动调 wiki_context / wiki_verify、不反复检索或自我验证;结尾加一句简短可信度提醒,资料不足就明说不足、不编造、不偷偷多轮检索。
|
|
246
245
|
${RECALL_TRIGGERS}
|
|
247
246
|
|
|
248
247
|
mode 用法:
|
|
249
|
-
- search
|
|
248
|
+
- search(默认):1-4 个关键词,空格分隔做 AND,别传整句问话。
|
|
250
249
|
- page / list / overview / lint / draft:取整页 / 列目录 / 看总览 / 查健康 / 拿落盘骨架。
|
|
251
|
-
|
|
252
|
-
机制说明、每个 mode 的返回格式、status 各取值的含义、全部参数 —— 用 mode:"help" 查一次。
|
|
253
|
-
描述只讲「什么时候该调」,讲不全的细节都在 help 里,不确定就查,比猜便宜。
|
|
250
|
+
机制、返回格式、status 与全部参数 —— 用 mode:"help" 查一次。
|
|
254
251
|
|
|
255
252
|
怎么读结果:
|
|
256
|
-
- kind=note 是消化过的笔记(最可信);raw-summary
|
|
253
|
+
- kind=note 是消化过的笔记(最可信);raw-summary 是资料压缩稿;source 是资料页。
|
|
257
254
|
- sources 是「来源数量」,判断证据强度用:1 份和 12 份不是一回事。
|
|
258
|
-
-
|
|
259
|
-
-
|
|
255
|
+
- 标了「可能已过时」的页,引用时说明时间。
|
|
256
|
+
- 一次 search 给元数据 + 摘要 + 命中小节正文,不是整页全文;status 非 ok、warnings 非空、零命中或正文被截断时须披露资料不足。
|
|
257
|
+
- 一条都没命中不代表话题不存在,换同义词或先用 list 看目录再搜。`
|
|
260
258
|
|
|
261
259
|
/** 知识层的候选目录名:路径指到上一层时,自动下钻到这些名字。 */
|
|
262
260
|
const DRILL_DIRS = ['知识层-wiki', '知识层', 'wiki', 'Wiki']
|
|
@@ -872,12 +870,23 @@ function readPluginVersion(pluginRoot) {
|
|
|
872
870
|
/** 插件版本:契约里要填,读一次就够。 */
|
|
873
871
|
const PLUGIN_VERSION = readPluginVersion(pluginRoot)
|
|
874
872
|
|
|
873
|
+
/**
|
|
874
|
+
* Bridge 的错误信封比别处多一层:{kind:'error', contract_version, bridge_version, error:{code,message}}。
|
|
875
|
+
* 直接取 value.error.code 会拿到 undefined,模型就只能看到「失败:? — 」,等于没给原因。
|
|
876
|
+
*/
|
|
877
|
+
function errorBrief(value) {
|
|
878
|
+
const outer = value?.error ?? {}
|
|
879
|
+
const inner = outer.error ?? outer
|
|
880
|
+
const code = inner.code ?? '?'
|
|
881
|
+
const message = inner.message ?? ''
|
|
882
|
+
return message === '' ? code : `${code} — ${message}`
|
|
883
|
+
}
|
|
884
|
+
|
|
875
885
|
/** context 结果的一行摘要:先给结论面,细节交给结构化字段。 */
|
|
876
886
|
function renderContext(args, value) {
|
|
877
887
|
if (!value || typeof value !== 'object') return '(没有结果)'
|
|
878
888
|
if (value.kind === 'error') {
|
|
879
|
-
|
|
880
|
-
return `知识网关调用失败:${e.code ?? '?'} — ${e.message ?? ''}`
|
|
889
|
+
return `知识网关调用失败:${errorBrief(value)}`
|
|
881
890
|
}
|
|
882
891
|
const status = value.status ?? {}
|
|
883
892
|
const lines = [
|
|
@@ -925,8 +934,7 @@ function renderContext(args, value) {
|
|
|
925
934
|
function renderVerify(args, value) {
|
|
926
935
|
if (!value || typeof value !== 'object') return '(没有结果)'
|
|
927
936
|
if (value.kind === 'error') {
|
|
928
|
-
|
|
929
|
-
return `核验没跑成:${e.code ?? '?'} — ${e.message ?? ''}`
|
|
937
|
+
return `核验没跑成:${errorBrief(value)}`
|
|
930
938
|
}
|
|
931
939
|
const lines = [`核验状态:${value.status ?? '?'}`]
|
|
932
940
|
const violations = value.violations ?? []
|
|
@@ -942,9 +950,9 @@ function renderVerify(args, value) {
|
|
|
942
950
|
lines.push(`提示 ${notices.length} 条:${notices.map((n) => n.rule ?? '').join('、')}`)
|
|
943
951
|
}
|
|
944
952
|
// 违规处置纪律:ok 只说明这次核验没发现越界,不等于逐项必核规则都查过;
|
|
945
|
-
//
|
|
953
|
+
// 发现违规就定向改答案,最多复核一次;复核仍有违规即停止并披露,不再循环。
|
|
946
954
|
if (violations.length > 0 || value.status === 'violations_found') {
|
|
947
|
-
lines.push('', '不得绕过 violations_found
|
|
955
|
+
lines.push('', '不得绕过 violations_found:定向修正答案后最多再跑一次 wiki_verify;复核仍有违规即停止并披露,不再循环核验。')
|
|
948
956
|
}
|
|
949
957
|
return lines.join('\n')
|
|
950
958
|
}
|
|
@@ -1017,8 +1025,7 @@ function renderGovernanceLines(g) {
|
|
|
1017
1025
|
function renderObserve(args, value) {
|
|
1018
1026
|
if (!value || typeof value !== 'object') return '(没有结果)'
|
|
1019
1027
|
if (value.kind === 'error') {
|
|
1020
|
-
|
|
1021
|
-
return `观察统计没跑成:${e.code ?? '?'} — ${e.message ?? ''}`
|
|
1028
|
+
return `观察统计没跑成:${errorBrief(value)}`
|
|
1022
1029
|
}
|
|
1023
1030
|
const totals = value.totals ?? {}
|
|
1024
1031
|
const window = value.window ?? {}
|
|
@@ -1101,8 +1108,8 @@ const registerGateway = () => {
|
|
|
1101
1108
|
name: 'wiki_context',
|
|
1102
1109
|
description:
|
|
1103
1110
|
'向本地知识库要一份「带证据的上下文」:检索、抽证据、标缺口、给回答约束,一次完成。'
|
|
1104
|
-
+ '
|
|
1105
|
-
+ '
|
|
1111
|
+
+ '仅在按需深度证据时使用:用户明确要求查看原文 / 核验,或问题涉及高风险、后果重大的重要事实,或库内存在复杂冲突;普通快速回答不要调用,'
|
|
1112
|
+
+ '也不要自己连续调 wiki_recall。返回里 status.support 与 status.degraded 必须分别看待:'
|
|
1106
1113
|
+ 'support 说的是「知识够不够」,degraded 说的是「引擎有没有坏」,后者为真时不能把 support 当结论。'
|
|
1107
1114
|
+ '返回的 context_id 可交给 wiki_verify 核验后续回答。'
|
|
1108
1115
|
+ CONTEXT_TRIGGERS,
|
|
@@ -1157,7 +1164,7 @@ const registerGateway = () => {
|
|
|
1157
1164
|
name: 'wiki_verify',
|
|
1158
1165
|
description:
|
|
1159
1166
|
'拿一份已有的 wiki_context 结果去核验一段回答,不重新检索。'
|
|
1160
|
-
+ '
|
|
1167
|
+
+ '仅在深度核验模式下使用:写完候选答案后按需自查,不因答案含数字、范围、年份或引文就在快速回答里自动调用。'
|
|
1161
1168
|
+ '返回 status 与 violations:violations 非空说明回答越过了证据允许的边界;'
|
|
1162
1169
|
+ 'context_expired / context_missing 是快照问题,不等于回答错了,需要重新取上下文再核验。'
|
|
1163
1170
|
+ VERIFY_TRIGGERS,
|
|
@@ -1214,7 +1221,8 @@ const registerGateway = () => {
|
|
|
1214
1221
|
disposers.push(ctx.tools.register({
|
|
1215
1222
|
name: 'wiki_observe',
|
|
1216
1223
|
description:
|
|
1217
|
-
'
|
|
1224
|
+
'仅诊断深度核验链的观察统计。'
|
|
1225
|
+
+ '查观察日志的统计:这段时间 wiki_context 被问过多少次、支持状态怎么分布、'
|
|
1218
1226
|
+ 'wiki_verify 挑出过哪些违规类型。只读诊断,不参与回答,也不改检索行为。'
|
|
1219
1227
|
+ OBSERVE_TRIGGERS,
|
|
1220
1228
|
parameters: {
|
|
@@ -1569,9 +1577,11 @@ function renderSearch(value) {
|
|
|
1569
1577
|
// 这里是「这个具体的词在库里一页都没沾到」—— 后者才指着该换哪个词。
|
|
1570
1578
|
const missed = Array.isArray(value.missedTerms) ? value.missedTerms : []
|
|
1571
1579
|
if (missed.length > 0) out.push(`没沾到:${missed.join('、')}(这些词在库里一页都没命中,换同义词或干脆去掉)`)
|
|
1572
|
-
// 降级说明已由 warnings 承载(degraded
|
|
1573
|
-
//
|
|
1574
|
-
|
|
1580
|
+
// 降级说明已由 warnings 承载(degraded 时必有一条,用的就是同一段文字);只有 status 仍是 ok
|
|
1581
|
+
// 或老调用方(结果里没有 status 字段)才需要这里的 note —— 否则同一句话模型会读两遍。
|
|
1582
|
+
// ok 也要放行:单字查询「这个字到处都有、排序没有区分度」是 ok 状态下唯一能说这句话的出口,
|
|
1583
|
+
// 而 ok 按契约不带 warnings 键(tests/status.mjs 守着「正常路径零额外 token」)。
|
|
1584
|
+
if (value.note && (value.status === undefined || value.status === 'ok')) out.push(`⚠️ ${value.note}`)
|
|
1575
1585
|
|
|
1576
1586
|
const hits = Array.isArray(value.hits) ? value.hits : []
|
|
1577
1587
|
if (hits.length === 0) {
|
|
@@ -1629,6 +1639,7 @@ function renderPage(value) {
|
|
|
1629
1639
|
}
|
|
1630
1640
|
const page = value.found
|
|
1631
1641
|
out.push(`【${page.name}】⟨${metaLine(page)}⟩`)
|
|
1642
|
+
if (value.note && value.status === 'ok') out.push(`⚠️ ${value.note}`)
|
|
1632
1643
|
if (page.summary) out.push(`摘要:${page.summary}`)
|
|
1633
1644
|
if (Array.isArray(page.aliases) && page.aliases.length > 0) out.push(`别名:${page.aliases.join(' / ')}`)
|
|
1634
1645
|
if (Array.isArray(page.sections) && page.sections.length > 0) out.push(`小节:${page.sections.join(' / ')}`)
|
package/lib/jsonl-store.js
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* 纪律:写失败一律抛给调用方,由调用方决定 warn 还是静默 ——
|
|
9
9
|
* 账本永远是旁路,不能改变工具返回值。
|
|
10
10
|
*/
|
|
11
|
-
import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readFileSync, readSync, statSync, writeFileSync } from 'node:fs'
|
|
11
|
+
import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readFileSync, readSync, renameSync, statSync, writeFileSync } from 'node:fs'
|
|
12
12
|
|
|
13
13
|
/** 超过这么多行就轮转。 */
|
|
14
14
|
export const MAX_LINES = 5000
|
|
@@ -68,6 +68,20 @@ export function parseLines(text) {
|
|
|
68
68
|
return rows
|
|
69
69
|
}
|
|
70
70
|
|
|
71
|
+
/**
|
|
72
|
+
* 数「物理行」,不是「能解析的行」。
|
|
73
|
+
*
|
|
74
|
+
* 轮转看的是文件会不会无限长,所以坏行也算一行 —— 否则一份满是坏行的账本
|
|
75
|
+
* 永远数出 0 行,轮转一辈子不触发。
|
|
76
|
+
*/
|
|
77
|
+
export function countPhysicalLines(file) {
|
|
78
|
+
try {
|
|
79
|
+
return readFileSync(file, 'utf8').split('\n').filter((line) => line.trim() !== '').length
|
|
80
|
+
} catch {
|
|
81
|
+
return 0
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
71
85
|
export function countLines(file) {
|
|
72
86
|
try {
|
|
73
87
|
return parseLines(readFileSync(file, 'utf8')).length
|
|
@@ -85,27 +99,67 @@ export function lineCountOf(file) {
|
|
|
85
99
|
* 建一个 JSONL 账本。同一个文件可以有多个实例(宿主一个、测试一个),
|
|
86
100
|
* 它们各记各的内存缓冲,文件是共享的。
|
|
87
101
|
*/
|
|
88
|
-
export function createJsonlStore({ file, maxLines = MAX_LINES, keepLines = KEEP_LINES, tailBytes = TAIL_BYTES } = {}) {
|
|
102
|
+
export function createJsonlStore({ file, maxLines = MAX_LINES, keepLines = KEEP_LINES, tailBytes = TAIL_BYTES, onRotate = null } = {}) {
|
|
89
103
|
let lineCount = null
|
|
90
104
|
|
|
91
105
|
function rotateIfNeeded() {
|
|
92
|
-
if (lineCount === null) lineCount =
|
|
93
|
-
|
|
106
|
+
if (lineCount === null) lineCount = countPhysicalLines(file)
|
|
107
|
+
// 到 maxLines 就先轮转再写:这样文件永远不超过 maxLines。
|
|
108
|
+
// (原来写的是 `<=`,于是 5000 行上限实际会先长到 5001 行才收。)
|
|
109
|
+
if (lineCount < maxLines) return
|
|
94
110
|
let kept = []
|
|
95
111
|
try {
|
|
96
112
|
kept = parseLines(readFileSync(file, 'utf8')).slice(-keepLines)
|
|
97
113
|
} catch {
|
|
98
114
|
kept = []
|
|
99
115
|
}
|
|
100
|
-
|
|
116
|
+
// 先写临时文件再 rename:账本被清空一半比不轮转更糟(并发读的人要么看到旧的、要么看到新的)。
|
|
117
|
+
const tmp = `${file}.tmp`
|
|
118
|
+
writeFileSync(tmp, kept.map((row) => JSON.stringify(row) + '\n').join(''))
|
|
119
|
+
renameSync(tmp, file)
|
|
101
120
|
lineCount = kept.length
|
|
121
|
+
// 轮转把更旧的行从文件里裁掉了。调用方若还把它们留在内存缓冲里,
|
|
122
|
+
// 展示时又会补回列表(窗口越读越长,还都是已经不存在于账本里的行)——
|
|
123
|
+
// 所以这里给一个钩子,让它能同步裁掉自己那份副本。
|
|
124
|
+
if (typeof onRotate === 'function') {
|
|
125
|
+
try {
|
|
126
|
+
onRotate({ kept: kept.length, maxLines, keepLines })
|
|
127
|
+
} catch {
|
|
128
|
+
// 钩子出错不能连带把记账搞坏
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* 文件是不是以换行结尾。
|
|
135
|
+
*
|
|
136
|
+
* 上一次写到一半被 kill 时,最后那行没有换行符;直接 append 会把新记录
|
|
137
|
+
* 粘在坏行后面(`{"broken":{"ok":3}`)——**坏行毁掉的是新写进去的那条**,
|
|
138
|
+
* 而它正是唯一还在内存里的。所以写之前先补一个换行,让坏行自己坏掉。
|
|
139
|
+
*/
|
|
140
|
+
function endsWithNewline() {
|
|
141
|
+
try {
|
|
142
|
+
const size = statSync(file).size
|
|
143
|
+
if (size === 0) return true
|
|
144
|
+
const fd = openSync(file, 'r')
|
|
145
|
+
try {
|
|
146
|
+
const one = Buffer.alloc(1)
|
|
147
|
+
readSync(fd, one, 0, 1, size - 1)
|
|
148
|
+
return one[0] === 0x0a
|
|
149
|
+
} finally {
|
|
150
|
+
closeSync(fd)
|
|
151
|
+
}
|
|
152
|
+
} catch {
|
|
153
|
+
return true
|
|
154
|
+
}
|
|
102
155
|
}
|
|
103
156
|
|
|
104
157
|
function append(entry) {
|
|
105
158
|
if (file === undefined || file === null || file === '') return
|
|
106
159
|
rotateIfNeeded()
|
|
107
|
-
|
|
108
|
-
|
|
160
|
+
const prefix = endsWithNewline() ? '' : '\n'
|
|
161
|
+
appendFileSync(file, `${prefix}${JSON.stringify(entry)}\n`)
|
|
162
|
+
lineCount = Math.min((lineCount ?? 0) + 1, maxLines)
|
|
109
163
|
}
|
|
110
164
|
|
|
111
165
|
/** 尾部读(调用账本用):只认最后一段。 */
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-wiki-notes",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.6.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Read-only knowledge gateway over a local Markdown vault for DeepSeek Harness — recall, evidence pack, answer verification, call audit | 本地 Markdown 笔记库的只读知识网关:检索、证据包、核验、调用审计",
|
|
6
6
|
"keywords": [
|
|
@@ -33,13 +33,14 @@
|
|
|
33
33
|
"examples",
|
|
34
34
|
"cordis.patch.yml",
|
|
35
35
|
"README.md",
|
|
36
|
-
"LICENSE"
|
|
36
|
+
"LICENSE",
|
|
37
|
+
"CHANGELOG.md"
|
|
37
38
|
],
|
|
38
39
|
"engines": {
|
|
39
40
|
"node": ">=20.13.0"
|
|
40
41
|
},
|
|
41
42
|
"scripts": {
|
|
42
|
-
"test": "node tests/smoke.mjs && node tests/status.mjs && node tests/params.mjs && node tests/fields.mjs && node tests/robust.mjs && node tests/lint.mjs && node tests/lintdiff.mjs && node tests/config.mjs && node tests/explain.mjs && node tests/cli.mjs && node tests/api.mjs && node tests/help.mjs && node tests/contract.mjs && node tests/topics.mjs && node tests/draft.mjs && node tests/calls.mjs && node tests/governance.mjs && node tests/inject.mjs && node tests/watch.mjs && node tests/client.mjs",
|
|
43
|
+
"test": "node tests/smoke.mjs && node tests/status.mjs && node tests/params.mjs && node tests/fields.mjs && node tests/robust.mjs && node tests/lint.mjs && node tests/lintdiff.mjs && node tests/config.mjs && node tests/explain.mjs && node tests/cli.mjs && node tests/api.mjs && node tests/help.mjs && node tests/contract.mjs && node tests/topics.mjs && node tests/draft.mjs && node tests/calls.mjs && node tests/governance.mjs && node tests/inject.mjs && node tests/watch.mjs && node tests/client.mjs && node tests/tier.mjs && node tests/render.mjs && node tests/calls-read.mjs && node tests/store.mjs && node tests/bridge.mjs",
|
|
43
44
|
"cli": "node bin/cli.mjs",
|
|
44
45
|
"probe": "node tools/probe.mjs"
|
|
45
46
|
},
|