dsh-knit 0.22.0 → 0.23.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 +118 -3
- package/SECURITY.md +11 -5
- package/package.json +2 -2
- package/src/client/client.js +522 -99
- package/src/host/context.js +42 -3
- package/src/host/index.js +196 -7
- package/src/host/semantic.js +465 -0
- package/src/host/tool.js +44 -1
- package/test/client.test.mjs +636 -153
- package/test/harness.mjs +3 -1
- package/test/host-http.test.mjs +23 -0
- package/test/hybrid-eval.test.mjs +184 -0
- package/test/hybrid-retrieval.test.mjs +313 -0
- package/test/retrieval-corpus.mjs +379 -0
- package/test/retrieval-eval.mjs +231 -0
- package/test/semantic.test.mjs +257 -0
- package/test/tool.test.mjs +59 -4
package/src/host/context.js
CHANGED
|
@@ -237,6 +237,8 @@ function fieldCount(fields) {
|
|
|
237
237
|
* 5. `linkTarget` —— 被某个 Primary 引用
|
|
238
238
|
* 6. `linkSource` —— 引用了某个 Primary
|
|
239
239
|
* 7. `related` —— 兜底:名次靠后的命中项
|
|
240
|
+
* 8. `semantic` —— **v0.23**:语义候选补进来的(`raw === 0`、由 `doc.semantic` 标记)。
|
|
241
|
+
* 它**只可能**出现在「相关」层,而且**只追加在最后** —— 见下面 `semanticOnly`。
|
|
240
242
|
*
|
|
241
243
|
* v0.19 给代码换的只是**两个码的名字**,不是两套判据 —— 命中位置完全一样
|
|
242
244
|
* (文件名占的是 `title` 槽、目录占的是 `summary` 槽,见 `index.js` 的 `readCode()`)。
|
|
@@ -244,7 +246,8 @@ function fieldCount(fields) {
|
|
|
244
246
|
* 它的「标题」就是文件名。**判据没有分叉,只有称谓分叉。**
|
|
245
247
|
*
|
|
246
248
|
* @param {object} doc - 记录(`{rel, kind, matchedTerms}`;`matchedTerms[].fields` 是字段位图)
|
|
247
|
-
* @param {{linkTarget?:boolean, linkSource?:boolean}} [links] - 与 Primary
|
|
249
|
+
* @param {{linkTarget?:boolean, linkSource?:boolean, semantic?:boolean}} [links] - 与 Primary 的关系;
|
|
250
|
+
* `semantic` = v0.23 的「这条是语义候选补进来的」(只有在词法 / 关系证据都没有时才认它)
|
|
248
251
|
* @returns {{code:string, terms:string[], fields:number, term:string}} 理由
|
|
249
252
|
*/
|
|
250
253
|
export function explainContext(doc, links = {}) {
|
|
@@ -289,6 +292,10 @@ export function explainContext(doc, links = {}) {
|
|
|
289
292
|
}
|
|
290
293
|
if (links.linkTarget) return { code: 'linkTarget', terms: [], fields: 0, term: '' }
|
|
291
294
|
if (links.linkSource) return { code: 'linkSource', terms: [], fields: 0, term: '' }
|
|
295
|
+
// v0.23:语义补进来的那一条。**排在这里是有讲究的** ——
|
|
296
|
+
// · 前面几条都是**可复核的证据**(命中在哪个字段、哪条引用),语义只是「标题+摘要像」;
|
|
297
|
+
// · 所以只有前几条都不成立时才轮到它,而且它**不冒充**任何关键词命中(`terms: []`)。
|
|
298
|
+
if (links.semantic === true) return { code: 'semantic', terms: [], fields: 0, term: '' }
|
|
292
299
|
return { code: 'related', terms: [], fields: 0, term: '' }
|
|
293
300
|
}
|
|
294
301
|
|
|
@@ -308,6 +315,9 @@ const REASON_ORDER = {
|
|
|
308
315
|
linkTarget: 4,
|
|
309
316
|
linkSource: 5,
|
|
310
317
|
related: 6,
|
|
318
|
+
// v0.23:语义是**最弱**的一档 —— 它只在同层名次相同时才参与兜底排序,
|
|
319
|
+
// 而且实际装配里它总是追加在「相关」层最后(rank 最大)。
|
|
320
|
+
semantic: 7,
|
|
311
321
|
}
|
|
312
322
|
|
|
313
323
|
/**
|
|
@@ -393,6 +403,10 @@ export function buildContext(input = {}) {
|
|
|
393
403
|
// 不出现在任何返回值里。
|
|
394
404
|
strength: topRaw > 0 ? raw / topRaw : 0,
|
|
395
405
|
rank: index,
|
|
406
|
+
// v0.23:**这一条是语义候选补进来的吗**。如实带进来,因为它是准入判据的一部分
|
|
407
|
+
// (`semanticOnly` 只收 `raw === 0 && semantic === true`)——
|
|
408
|
+
// 漏带这一格,语义条目就会在装配层静默消失(写完守卫当场抓到过一次)。
|
|
409
|
+
semantic: doc.semantic === true,
|
|
396
410
|
}
|
|
397
411
|
})
|
|
398
412
|
|
|
@@ -400,6 +414,17 @@ export function buildContext(input = {}) {
|
|
|
400
414
|
// 零命中的文档只能靠「与 Primary 的引用关系」被带进 Supporting / Related(见下)。
|
|
401
415
|
const hit = records.filter((r) => r.raw > 0)
|
|
402
416
|
|
|
417
|
+
/* ── v0.23:语义补进来的那几条 ───────────────────────
|
|
418
|
+
* 它们是 `raw === 0`(BM25 一个词都没命中)但被语义通道标了 `doc.semantic` 的记录。
|
|
419
|
+
*
|
|
420
|
+
* 为什么要与 `hit` **分开收**(而不是把门槛放宽成 `raw > 0 || semantic`):
|
|
421
|
+
* · 进 Primary 要 `strength >= PRIMARY_MIN_SHARE`、进 Supporting 要 `isDocHit`(**正文**命中),
|
|
422
|
+
* 语义条目两样都没有 ⇒ 放宽门槛的结果仍然是「只能进 Related」;
|
|
423
|
+
* · 分开收能把结论**写成结构性保证**而不是纪律:语义条目**只**可能出现在「相关」层,
|
|
424
|
+
* 而且**只追加在最后** —— 既有条目(词法 + 关系)的成员与顺序因此可以逐条断言。
|
|
425
|
+
* 这是对抗性审查(2026-10-11)指出的那条:原方案以为「改个门槛就够」。 */
|
|
426
|
+
const semanticOnly = records.filter((r) => r.raw === 0 && r.semantic === true)
|
|
427
|
+
|
|
403
428
|
/* ── 焦点词 ─────────────────────────────────────────
|
|
404
429
|
* 一个话题词在这批结果的前 `FOCUS_WINDOW` 篇里**至少两篇**命中,才算「项目里真的
|
|
405
430
|
* 还有别处在讲它」—— 只有它才能把一个**正文**命中抬到 Supporting。
|
|
@@ -532,7 +557,8 @@ export function buildContext(input = {}) {
|
|
|
532
557
|
/* ── Related ────────────────────────────────────────
|
|
533
558
|
* 有命中、但没进上面两层的;再补上「引用了 Primary / 被 Primary 引用」的其余邻居。
|
|
534
559
|
*
|
|
535
|
-
* ⚠️ **只走 `hit`,不走 `noHit`**(2026-09-29 改,对齐 PRD §5 / SDD §25
|
|
560
|
+
* ⚠️ **只走 `hit`,不走 `noHit`**(2026-09-29 改,对齐 PRD §5 / SDD §25);
|
|
561
|
+
* **v0.23 唯一的例外是语义条目** —— 它们在下面**单独追加**,且只吃剩下的 `capRelated` 名额。
|
|
536
562
|
* PRD §5 对 Related 的定义是「**与当前任务有关**,但没有足够证据进入 Primary / Supporting 的资料」——
|
|
537
563
|
* 一个话题词都没命中、又没有引用关系的文档**不是「有关」**,它只是「工作区里还有这一篇」。
|
|
538
564
|
* 放进来会让它带着兜底理由码 `related` 出场,而客户端把那句翻译成
|
|
@@ -564,6 +590,14 @@ export function buildContext(input = {}) {
|
|
|
564
590
|
}
|
|
565
591
|
}
|
|
566
592
|
}
|
|
593
|
+
// v0.23:**最后**才轮到语义条目(词法 → 关系 → 语义),而且只吃剩下的名额。
|
|
594
|
+
// 顺序在这里是语义的一部分:capRelated 满的时候,被挤掉的必须是语义条目,不能是既有条目。
|
|
595
|
+
for (const record of semanticOnly) {
|
|
596
|
+
if (related.length >= capRelated) break
|
|
597
|
+
if (seenRelated.has(record.rel)) continue
|
|
598
|
+
seenRelated.add(record.rel)
|
|
599
|
+
related.push({ record, linkTarget: false, linkSource: false, semantic: true })
|
|
600
|
+
}
|
|
567
601
|
|
|
568
602
|
/**
|
|
569
603
|
* 把内部记录投影成对外的条目:**只有 rel / title / summary / mtimeMs / kind / source /
|
|
@@ -589,7 +623,12 @@ export function buildContext(input = {}) {
|
|
|
589
623
|
kind: record.kind,
|
|
590
624
|
source: record.source,
|
|
591
625
|
reason,
|
|
592
|
-
|
|
626
|
+
// v0.23:**三分支**。语义必须单独判 —— 否则它会从
|
|
627
|
+
// `RELATION_REASON` 的默认分支掉出去变成 `retrieval`(伪装成关键词命中),
|
|
628
|
+
// 或者(如果 `explainContext()` 还回 `related` 兜底码)被误标成 `relation`。
|
|
629
|
+
provenance: reason.code === 'semantic'
|
|
630
|
+
? 'semantic'
|
|
631
|
+
: (RELATION_REASON.has(reason.code) ? 'relation' : 'retrieval'),
|
|
593
632
|
}
|
|
594
633
|
if (incident) {
|
|
595
634
|
const found = relationsOf(incident, record.rel, MAX_RELATIONS_PER_ITEM)
|
package/src/host/index.js
CHANGED
|
@@ -35,6 +35,12 @@ import {
|
|
|
35
35
|
// v0.22:增量上下文索引的持久层。**不参与排序、不缓存正文** —— 它只回答
|
|
36
36
|
// 「这个文件的头部指纹和上次一样吗」。存储拿不到时它自己降级成空 Map。
|
|
37
37
|
import { sharedIndexStore, headHashOf, refsShapeOk } from './index-store.js'
|
|
38
|
+
// v0.23:可选混合检索(Phase A)。**默认零调用** —— 没有配置、或要的是词法模式时,
|
|
39
|
+
// 这一层连探测都不发(方案 §9.2 判据 1)。它只算「有界的语义候选数」,**不进三层、不改名次**
|
|
40
|
+
// (那是 Phase B 的规则变更,见 `Knit-v0.23-方案-可选混合检索.md` §3 第 6/7/8 条与 §11)。
|
|
41
|
+
import {
|
|
42
|
+
createSemanticEngine, sharedSemanticStore, normalizeProviderConfig,
|
|
43
|
+
} from './semantic.js'
|
|
38
44
|
// v0.14:上下文装配。同样由这里注入依赖(`list` / `read`),保持纯函数可单测。
|
|
39
45
|
// ⚠️ 这里**只 import `buildContext`**:Context Pack 的文本渲染只在 `tool.js` 的
|
|
40
46
|
// `renderToolText()` 里发生(模型看到的是那段文本,不是结构化 JSON)。曾经多导出一个
|
|
@@ -873,6 +879,15 @@ export function setIndexRegistry(store) {
|
|
|
873
879
|
indexRegistry = store || null
|
|
874
880
|
}
|
|
875
881
|
|
|
882
|
+
/**
|
|
883
|
+
* 装一次语义引擎(`apply()` 拿到 `ctx.storage` 时换成带持久化配置的那份;测试也走它)。
|
|
884
|
+
* @param {object|null} engine - `semantic.js` 的引擎;传 `null` 退回「没有配置」
|
|
885
|
+
* @returns {void}
|
|
886
|
+
*/
|
|
887
|
+
export function setSemanticEngine(engine) {
|
|
888
|
+
semanticEngine = engine || createSemanticEngine({ store: null })
|
|
889
|
+
}
|
|
890
|
+
|
|
876
891
|
/**
|
|
877
892
|
* 最近一轮扫描的索引计数(v0.22)。
|
|
878
893
|
*
|
|
@@ -1555,6 +1570,96 @@ function publicDoc(doc) {
|
|
|
1555
1570
|
*/
|
|
1556
1571
|
let controlRegistry = createControlRegistry(null)
|
|
1557
1572
|
|
|
1573
|
+
/**
|
|
1574
|
+
* v0.23 · 进程内的语义引擎(`apply()` 拿到 `ctx.storage` 时换成带持久化配置的那份)。
|
|
1575
|
+
*
|
|
1576
|
+
* ⚠️ **只持久化配置**;向量活在 `semantic.js` 的进程内有界缓存里 —— 持久化向量与
|
|
1577
|
+
* 「有界增量嵌入」是 Phase B 的事(方案 §6)。
|
|
1578
|
+
*/
|
|
1579
|
+
let semanticEngine = createSemanticEngine({ store: null })
|
|
1580
|
+
|
|
1581
|
+
/**
|
|
1582
|
+
* v0.23 Phase A:跑一轮**有界**语义候选。
|
|
1583
|
+
*
|
|
1584
|
+
* 三条不会变的行为(判据 1 / 5 / 7):
|
|
1585
|
+
* · 词法模式 ⇒ **一次 provider 调用都不发**(`available` 老实回 `null`:本轮没探测过);
|
|
1586
|
+
* · 任何失败 ⇒ 收敛成一个 `reason`,**绝不抛**(语义层坏了不许带坏检索);
|
|
1587
|
+
* · Phase A 只**数**候选,不往 `pool` 里塞任何东西 ⇒ 面板与工具载荷逐字不变。
|
|
1588
|
+
*
|
|
1589
|
+
* @param {string} root - 工作区根
|
|
1590
|
+
* @param {{retrieval: string, keywords: string[], task: string, docs: Array<object>}} input
|
|
1591
|
+
* @returns {Promise<object>} 语义状态行
|
|
1592
|
+
*/
|
|
1593
|
+
async function semanticPassFor(root, input) {
|
|
1594
|
+
const status = await semanticEngine.ready()
|
|
1595
|
+
const requested = input.retrieval === 'hybrid' ? 'hybrid' : 'lexical'
|
|
1596
|
+
// ⚠️ v0.23 修订(2026-10-11):**时间序下这一层整个不适用**。
|
|
1597
|
+
// 判据在代码里:`contextPayload()` 要求 `sort === 'relevance'` 才产出 Context Pack
|
|
1598
|
+
// (`contextPayload()` 的第一行),所以时间序**根本没有分层结构**,语义标记没有消费者;
|
|
1599
|
+
// 而这一轮如果照跑,就是「白花 provider 调用 + 界面上还显示成可用」。
|
|
1600
|
+
// ⇒ 直接如实回 `not-applicable`,**不探测、不嵌入**(判据 1 的同一条纪律:不该花的钱一分不花)。
|
|
1601
|
+
if (requested === 'hybrid' && input.applies !== true) {
|
|
1602
|
+
return {
|
|
1603
|
+
mode: 'lexical', requested, configured: status.configured, available: null,
|
|
1604
|
+
reason: 'not-applicable', candidates: 0, provider: status.provider, rels: [],
|
|
1605
|
+
}
|
|
1606
|
+
}
|
|
1607
|
+
if (requested !== 'hybrid') {
|
|
1608
|
+
return {
|
|
1609
|
+
mode: 'lexical', requested, configured: status.configured, available: null,
|
|
1610
|
+
reason: null, candidates: 0, provider: status.provider, rels: [],
|
|
1611
|
+
}
|
|
1612
|
+
}
|
|
1613
|
+
// ⚠️ 2026-10-11(Phase C 量尺发现):查询文本必须是**用户原话**。
|
|
1614
|
+
// 原来的顺序是 `task || keywords.join(' ')` —— 显式 `query` 路径(`knit_docs(query=…)`)下
|
|
1615
|
+
// `task` 是空的,于是拿去做嵌入的是 `extractKeywords()` **去重叠后的 3-gram 碎片**
|
|
1616
|
+
// (实测 `失效策略怎么定` → `["失效策","效策略"]`),语义那条路的质量因此明显更差。
|
|
1617
|
+
// 现在由调用方按「原话优先」传 `queryText`:显式 query > 会话原话 > 关键词(最后兜底)。
|
|
1618
|
+
const query = (input.queryText && String(input.queryText).trim())
|
|
1619
|
+
|| (input.task && String(input.task).trim())
|
|
1620
|
+
|| (Array.isArray(input.keywords) ? input.keywords.join(' ') : '')
|
|
1621
|
+
try {
|
|
1622
|
+
const result = await semanticEngine.pass({ root, query, docs: input.docs })
|
|
1623
|
+
// ⚠️ `mode` 报的是**实际生效**的模式,不是「你要的那个」:
|
|
1624
|
+
// 只有语义那一轮真的跑成功(`available === true`)才算 `hybrid`;
|
|
1625
|
+
// 没配置 / 探测失败 / 超时 / 形状不对一律**如实回 `lexical`** 并带上 `reason`
|
|
1626
|
+
// —— 判据 5 的「不许伪装成混合成功」在宿主这一侧就是这一行。
|
|
1627
|
+
const ok = result.available === true
|
|
1628
|
+
return {
|
|
1629
|
+
mode: ok ? 'hybrid' : 'lexical',
|
|
1630
|
+
requested,
|
|
1631
|
+
configured: !!result.provider,
|
|
1632
|
+
available: ok,
|
|
1633
|
+
reason: ok ? null : (result.reason || 'unavailable'),
|
|
1634
|
+
candidates: ok ? result.candidates : 0,
|
|
1635
|
+
provider: result.provider,
|
|
1636
|
+
rels: ok ? result.rels : [],
|
|
1637
|
+
}
|
|
1638
|
+
} catch {
|
|
1639
|
+
return {
|
|
1640
|
+
mode: 'lexical', requested, configured: true, available: false,
|
|
1641
|
+
reason: 'bad-response', candidates: 0, provider: status.provider, rels: [],
|
|
1642
|
+
}
|
|
1643
|
+
}
|
|
1644
|
+
}
|
|
1645
|
+
|
|
1646
|
+
/**
|
|
1647
|
+
* 把上面那一行压成**可以下发**的形状:`rels` 是内部输入(Phase B 要用),不下发。
|
|
1648
|
+
* @param {object} row - `semanticPassFor()` 的产物
|
|
1649
|
+
* @returns {object} 公开字段
|
|
1650
|
+
*/
|
|
1651
|
+
function publicSemantic(row) {
|
|
1652
|
+
return {
|
|
1653
|
+
mode: row.mode,
|
|
1654
|
+
requested: row.requested,
|
|
1655
|
+
configured: !!row.configured,
|
|
1656
|
+
available: row.available === null ? null : !!row.available,
|
|
1657
|
+
reason: row.reason || null,
|
|
1658
|
+
candidates: Number(row.candidates) || 0,
|
|
1659
|
+
provider: row.provider || null,
|
|
1660
|
+
}
|
|
1661
|
+
}
|
|
1662
|
+
|
|
1558
1663
|
export async function scan(root, limit, options = {}) {
|
|
1559
1664
|
// v0.19 修订:**扫的是展开符号链接后的那份路径**。
|
|
1560
1665
|
// 每条记录里的 `path`(`publicDoc()` 原样下发给客户端)就是「打开 / 定位」时
|
|
@@ -1579,6 +1684,9 @@ export async function scan(root, limit, options = {}) {
|
|
|
1579
1684
|
// 当前任务的**原文引用**(SDD §12)。只在「对话驱动」这条路上有值:
|
|
1580
1685
|
// 显式 query 路径下模型自己知道在问什么,把 query 当「任务」是编的。
|
|
1581
1686
|
let task = ''
|
|
1687
|
+
// v0.23:给语义通道的**查询原话**(显式 query 或会话里那条用户消息)。
|
|
1688
|
+
// 与 `task` 分开:`task` 是「包引用的任务原文」,这里是「拿去嵌入的文本」。
|
|
1689
|
+
let queryText = ''
|
|
1582
1690
|
|
|
1583
1691
|
if (wantRelevance) {
|
|
1584
1692
|
// 调用方给了明确的 query(v0.7 的 agent 工具走这条路):把它当成**一条最新的消息**,
|
|
@@ -1587,10 +1695,13 @@ export async function scan(root, limit, options = {}) {
|
|
|
1587
1695
|
const explicitQuery = typeof options.query === 'string' ? options.query.trim() : ''
|
|
1588
1696
|
if (explicitQuery) {
|
|
1589
1697
|
keywords = extractKeywords([explicitQuery], 30)
|
|
1698
|
+
// v0.23:语义那一层要的是**原话**,不是抽完的碎片(见 `semanticPassFor()` 的注释)。
|
|
1699
|
+
queryText = explicitQuery
|
|
1590
1700
|
} else {
|
|
1591
1701
|
const conv = conversationFor(options.session, sessionId)
|
|
1592
1702
|
keywords = conv.keywords
|
|
1593
1703
|
task = conv.task
|
|
1704
|
+
queryText = conv.task
|
|
1594
1705
|
}
|
|
1595
1706
|
// 没有对话可依据时老实退回时间序,而不是假装排了个序
|
|
1596
1707
|
mode = keywords.length > 0 ? 'relevance' : 'time'
|
|
@@ -1656,6 +1767,33 @@ export async function scan(root, limit, options = {}) {
|
|
|
1656
1767
|
}
|
|
1657
1768
|
}
|
|
1658
1769
|
|
|
1770
|
+
// ── v0.23:可选混合检索(Phase A)────────────────────────────────
|
|
1771
|
+
//
|
|
1772
|
+
// 位置是**刻意的**,两处都不能挪(方案 §3):
|
|
1773
|
+
// · 在**排除之后** ⇒ 被排除的文件不可能经语义路径回来(判据 3);
|
|
1774
|
+
// · 在 `rankByRelevance()` **之前** ⇒ 与未来 Phase B 的融合点一致。
|
|
1775
|
+
// Phase A 只算候选数、如实报告可用性 —— **不往 `pool` 里塞东西**(判据 2:载荷不变)。
|
|
1776
|
+
const semantic = await semanticPassFor(root, {
|
|
1777
|
+
retrieval: options.retrieval === 'hybrid' ? 'hybrid' : 'lexical',
|
|
1778
|
+
// 只有相关序才有 Context Pack(`contextPayload()` 的判据)⇒ 时间序下语义不适用。
|
|
1779
|
+
applies: mode === 'relevance',
|
|
1780
|
+
// 嵌入用的查询文本:**原话优先**(显式 query > 会话原话 > 关键词碎片兜底)。
|
|
1781
|
+
queryText,
|
|
1782
|
+
keywords,
|
|
1783
|
+
task,
|
|
1784
|
+
docs: pool,
|
|
1785
|
+
})
|
|
1786
|
+
|
|
1787
|
+
// v0.23 Phase B:把这一轮的语义候选**标进池子**(只标记 —— 不排序、不抬层、不改名次)。
|
|
1788
|
+
// 与词法同时命中的条目也照标:`context.js` **只在 `raw === 0` 时**才认这个标记,
|
|
1789
|
+
// 所以「有词法证据的仍按词法规则分层」是结构性保证,不靠纪律。
|
|
1790
|
+
// ⚠️ `pool` 里的对象就是后面 `rankByRelevance()` / `publicDoc()` 看到的那些;
|
|
1791
|
+
// `publicDoc()` 是白名单投影,所以这个标记**不会**下发到浏览器。
|
|
1792
|
+
if (semantic.mode === 'hybrid' && semantic.rels.length > 0) {
|
|
1793
|
+
const semanticRels = new Set(semantic.rels)
|
|
1794
|
+
for (const doc of pool) if (semanticRels.has(doc.rel)) doc.semantic = true
|
|
1795
|
+
}
|
|
1796
|
+
|
|
1659
1797
|
let ordered
|
|
1660
1798
|
let topic = ''
|
|
1661
1799
|
if (mode === 'relevance') {
|
|
@@ -1721,6 +1859,8 @@ export async function scan(root, limit, options = {}) {
|
|
|
1721
1859
|
// 剥掉不是为了保密(这是用户自己刚说过的话),而是为了不动 v0.13 的响应形状:
|
|
1722
1860
|
// `context.task` 已经把这个值带出去了,顶层再来一份是重复。
|
|
1723
1861
|
task: mode === 'relevance' ? task : '',
|
|
1862
|
+
// v0.23:检索模式 + 语义可用性 / 回退原因 / 有界候选数。**只计数、不进包**。
|
|
1863
|
+
semantic: publicSemantic(semantic),
|
|
1724
1864
|
docs: ordered.slice(0, limit).map(publicDoc),
|
|
1725
1865
|
// 全量列表(未按 limit 切片)。**内部输入**:v0.17 的 lifecycle 需要「被读过但
|
|
1726
1866
|
// 不一定落在当前页」的文档的当前 mtime。由 `publicScanPayload()` 剥掉。
|
|
@@ -1728,7 +1868,11 @@ export async function scan(root, limit, options = {}) {
|
|
|
1728
1868
|
// v0.19 扫描计数(需求 §50 要报的那几个数:见到的 / 准入的 / 被排除的 / 生成噪声)
|
|
1729
1869
|
// 加上 `corpusSize`(本档语料的实际大小,即 `allDocs.length`)。
|
|
1730
1870
|
// **内部输入**,由 `publicScanPayload()` 剥掉 —— HTTP 响应形状一个键都不加。
|
|
1731
|
-
stats: {
|
|
1871
|
+
stats: {
|
|
1872
|
+
...collected.stats, scanMs: collected.scanMs, corpusSize: ordered.length, controlSkipped, controlAlive,
|
|
1873
|
+
// v0.23:带 `rels` 的那一份**只在内部**(装配层 / 测试用)。
|
|
1874
|
+
semantic,
|
|
1875
|
+
},
|
|
1732
1876
|
}
|
|
1733
1877
|
}
|
|
1734
1878
|
|
|
@@ -1891,9 +2035,15 @@ function withStats(pack) {
|
|
|
1891
2035
|
* @returns {Promise<object|null>} Context Pack(带 `summary`)或 null
|
|
1892
2036
|
*/
|
|
1893
2037
|
async function contextPayload(root, payload, sort, kind) {
|
|
1894
|
-
|
|
2038
|
+
// v0.23(方案 A):面板的「全部」档也要一份包 —— 它是**包的原样**(三层混排文档 + 代码),
|
|
2039
|
+
// 媒体在三层之后单独成网格。所以 `all` 与 `doc` / `code` / `context` 一样产出 Context Pack。
|
|
2040
|
+
const contextKind = kind === 'doc' || kind === 'code' || kind === 'context' || kind === 'all'
|
|
1895
2041
|
if (!payload || payload.mode !== 'relevance' || sort !== 'relevance' || !contextKind) return null
|
|
1896
|
-
|
|
2042
|
+
// ⚠️ 媒体必须**在装配之前**剔掉,而且这不是洁癖:实测(2026-10-12)媒体能靠**文件名**命中
|
|
2043
|
+
// 查询词并拿到 `raw > 0`,`docs/clip.mp4` 甚至能进 Primary —— 一个没有正文的视频当「先看」
|
|
2044
|
+
// 是不可解释的上下文。剔掉之后「全部」档的语料与 `kind=context`(文档 + 代码)逐条一致。
|
|
2045
|
+
const ranked = (Array.isArray(payload.ranked) ? payload.ranked : [])
|
|
2046
|
+
.filter((doc) => doc && doc.kind !== KIND_IMAGE && doc.kind !== KIND_VIDEO)
|
|
1897
2047
|
if (ranked.length === 0) return null
|
|
1898
2048
|
try {
|
|
1899
2049
|
const pack = await buildContextFor(root, {
|
|
@@ -1903,7 +2053,8 @@ async function contextPayload(root, payload, sort, kind) {
|
|
|
1903
2053
|
total: payload.total,
|
|
1904
2054
|
// 引用图只在**真有命中**时才值得建(零命中时 Primary 为空,邻居逻辑没有锚点);
|
|
1905
2055
|
// 而且只有 Markdown 有图可建。
|
|
1906
|
-
|
|
2056
|
+
// 「全部」也建引用图:三层里要能看到与「文档」档同样的关系证据(同一张图,零额外 I/O)。
|
|
2057
|
+
withLinks: (kind === 'doc' || kind === 'all') && ranked.some((doc) => Number(doc.raw) > 0),
|
|
1907
2058
|
})
|
|
1908
2059
|
return withStats(pack)
|
|
1909
2060
|
} catch {
|
|
@@ -2583,10 +2734,14 @@ export function apply(ctx) {
|
|
|
2583
2734
|
// 它改的也只是 Knit 自己的控制状态,从不碰工作区里的任何文件。
|
|
2584
2735
|
const path = (req.url || '/').split('?')[0]
|
|
2585
2736
|
const isControl = path === `${ROUTE_PREFIX}/api/control`
|
|
2586
|
-
//
|
|
2587
|
-
//
|
|
2737
|
+
// v0.23:第二条(也是最后一条)写通道 —— 只写 Knit 自己的语义 provider 配置。
|
|
2738
|
+
// 它同样**只认 POST**(`GET /api/semantic` 一律 405,与 `GET /api/control` 一致)。
|
|
2739
|
+
const isSemantic = path === `${ROUTE_PREFIX}/api/semantic`
|
|
2740
|
+
const isWrite = isControl || isSemantic
|
|
2741
|
+
// 写通道**只认 POST**:别的路由仍然是纯 GET。
|
|
2742
|
+
// (写成「非 GET 一律 405,除非是写路由的 POST」会让 `GET /api/control`
|
|
2588
2743
|
// 掉进写分支里报 400 —— 那是「方法不对」不是「请求不对」。)
|
|
2589
|
-
if (req.method !== (
|
|
2744
|
+
if (req.method !== (isWrite ? 'POST' : 'GET')) {
|
|
2590
2745
|
sendJson(res, 405, { ok: false, code: ERROR_CODES.methodNotAllowed })
|
|
2591
2746
|
return
|
|
2592
2747
|
}
|
|
@@ -2596,6 +2751,29 @@ export function apply(ctx) {
|
|
|
2596
2751
|
const root = workspaceRootOf(webCtx, sessionId)
|
|
2597
2752
|
|
|
2598
2753
|
try {
|
|
2754
|
+
if (isSemantic) {
|
|
2755
|
+
// 只认 `{kind, base, model}`:三个都空 ⇒ **清空配置**;否则必须整份合法。
|
|
2756
|
+
// 配置是**机器级**的(不按工作区),所以这里不需要 sessionId / rel 校验 ——
|
|
2757
|
+
// 但**仍然**只回环、只 POST、坏 body 400(与 `/api/control` 同一条纪律,§6.9)。
|
|
2758
|
+
const body = await readJsonBody(req)
|
|
2759
|
+
const raw = body && typeof body === 'object' ? body : {}
|
|
2760
|
+
const empty = !raw.kind && !raw.base && !raw.model
|
|
2761
|
+
const config = empty ? null : normalizeProviderConfig(raw)
|
|
2762
|
+
if (!empty && !config) {
|
|
2763
|
+
sendJson(res, 400, { ok: false, code: ERROR_CODES.badRequest })
|
|
2764
|
+
return
|
|
2765
|
+
}
|
|
2766
|
+
await semanticEngine.configure(config)
|
|
2767
|
+
// 保存后**顺手探一次**:界面要的是「现在到底能不能用」,不是「我存下了」。
|
|
2768
|
+
const checked = config ? await semanticEngine.check() : { available: false, reason: 'no-provider' }
|
|
2769
|
+
sendJson(res, 200, {
|
|
2770
|
+
ok: true,
|
|
2771
|
+
configured: !!config,
|
|
2772
|
+
available: !!checked.available,
|
|
2773
|
+
reason: checked.available ? null : (checked.reason || 'probe-failed'),
|
|
2774
|
+
})
|
|
2775
|
+
return
|
|
2776
|
+
}
|
|
2599
2777
|
if (isControl) {
|
|
2600
2778
|
// 只认 `{action, rel}`;动作白名单在 `control.js` 里(一处真源)。
|
|
2601
2779
|
// `root` 由 sessionId 解析 —— 工作区**不能由请求指定**,与其余路由同一条纪律。
|
|
@@ -2632,6 +2810,8 @@ export function apply(ctx) {
|
|
|
2632
2810
|
: 'doc'
|
|
2633
2811
|
const payload = await scan(root, limit, {
|
|
2634
2812
|
session: sessionOf(webCtx, sessionId), sessionId, sort, kind,
|
|
2813
|
+
// v0.23:默认 `lexical`(不带这个参数的老客户端行为逐字不变)。
|
|
2814
|
+
retrieval: url.searchParams.get('retrieval') === 'hybrid' ? 'hybrid' : 'lexical',
|
|
2635
2815
|
})
|
|
2636
2816
|
const body = publicScanPayload(payload)
|
|
2637
2817
|
// v0.14:相关模式下顺带给出任务上下文分层。
|
|
@@ -2802,6 +2982,15 @@ export function apply(ctx) {
|
|
|
2802
2982
|
const store = sharedIndexStore(backend)
|
|
2803
2983
|
if (store) setIndexRegistry(store)
|
|
2804
2984
|
console.log(`[${name}] index storage: ${store ? 'attached' : 'memory-only'}`)
|
|
2985
|
+
|
|
2986
|
+
// ── v0.23:可选混合检索的**配置**持久化 ──────────────────────────
|
|
2987
|
+
//
|
|
2988
|
+
// 第三个 kv 单元(`knit_semantic`)。**只存配置**(一条全局记录,`single` 布局);
|
|
2989
|
+
// 向量活在进程内缓存里 —— 持久化向量是 Phase B 的事(方案 §6)。
|
|
2990
|
+
// 拿不到存储时引擎照样工作,只是配置活不过这次进程(面板会如实说)。
|
|
2991
|
+
const semanticStore = sharedSemanticStore(backend)
|
|
2992
|
+
if (semanticStore) semanticEngine = createSemanticEngine({ store: semanticStore })
|
|
2993
|
+
console.log(`[${name}] semantic storage: ${semanticStore ? 'attached' : 'memory-only'}`)
|
|
2805
2994
|
})
|
|
2806
2995
|
|
|
2807
2996
|
// ── v0.7:把同一个排序结果也交给模型 ──────────────────────────────
|