dsh-knit 0.23.1 → 0.24.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 +76 -0
- package/README.en.md +36 -7
- package/README.md +30 -6
- package/SECURITY.md +5 -2
- package/package.json +3 -3
- package/src/client/client.js +295 -8
- package/src/host/changes.js +208 -0
- package/src/host/git.js +377 -0
- package/src/host/index.js +228 -5
- package/test/client.test.mjs +270 -4
- package/test/git-changes.test.mjs +1238 -0
- package/test/host-http.test.mjs +4 -58
- package/test/http-harness.mjs +79 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,71 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
+
## [0.24.0] - 2026-10-14
|
|
7
|
+
|
|
8
|
+
> **本版定位**:新增一个**默认关闭**的能力 —— **Git 变更关联**:按工作区里**未提交的改动**
|
|
9
|
+
> 去找「还该一起看的文件」,依据是 Knit 已经有的那四类证据(引用 / 导入 / 测试配对 / 文档提及)。
|
|
10
|
+
> 按 semver 这是 minor:多了一条**用户可见**的能力、一条宿主路由,而且 `src/` 里**第一次**出现子进程。
|
|
11
|
+
>
|
|
12
|
+
> ⚠️ **本版占用了 `v0.24` 这个号**。v0.20.0 节曾把「语义/向量检索、把片段当排序基本实体、第二套预览框架」
|
|
13
|
+
> 写成「留 v0.24」—— 那是一次**非正式**的候选登记,不是承诺:其中「语义/向量检索」已由 **v0.23.0
|
|
14
|
+
> 的可选混合检索**落地;另外两条仍未做,**不因此占号**。旧节保持原样(历史不改写),以本节为准。
|
|
15
|
+
>
|
|
16
|
+
> **三条边界(本版的重点不是「找得更多」,而是「说得更准」)**:
|
|
17
|
+
> ① **`knit_docs` 与 `/knit/api/recent` 的契约一个字节未改** —— 关联走**独立接口**,专用结构,不往既有
|
|
18
|
+
> 响应里塞字段(`src/host/context.js` / `src/host/tool.js` 回到 v0.23.1 **逐字一致**);
|
|
19
|
+
> ② **只读** —— 固定 argv、不走 shell、关掉 fsmonitor 与可选索引刷新,且**子进程环境是白名单筛过的**;
|
|
20
|
+
> ③ **默认关** —— 关着时客户端一个请求都不发、宿主一个 git 进程都不 spawn。
|
|
21
|
+
|
|
22
|
+
### 新增
|
|
23
|
+
|
|
24
|
+
- **`GET /knit/api/changes`**:独立只读接口,返回**专用结构**
|
|
25
|
+
(`git{available,reason,filesTotal,truncated,files[]}` +
|
|
26
|
+
`links[{target, kind, source, title, summary, mtimeMs, evidence[{origin,type,dir,line}], evidenceTotal, types}]` +
|
|
27
|
+
`linksTotal / unresolved / outOfScope`)。**起点 / 目标 / 关系类型 / 方向 / 行号**逐条给全;
|
|
28
|
+
`tests` 那一类是文件名约定,`line` 如实为 `null`,不编行号。
|
|
29
|
+
- **面板状态行多一格二态开关「变更」**(默认关)。开态只把字色提亮(`aria-pressed`),不换底色、不用品牌色;
|
|
30
|
+
与「固定 / 关系」同属「这一份包里还装了什么」那一组,参与中点分隔、不参与编号。
|
|
31
|
+
- **变更关联区**:不编号的平行区,与三层互不影响;每条结果点开就是**既有那套行级证据**
|
|
32
|
+
(类型 · 起点 · 行号),零第二条渲染路径。
|
|
33
|
+
- **降级可辨(三种状态互不混淆)**:读到了没有变更写「变更 0」;有变更但零关联时**出区头 + 提示句**;
|
|
34
|
+
读不到写「变更 —」并把原因**直接写在列表里**(不是只放悬停)。
|
|
35
|
+
- **两个开发量尺**(`tools/`,**不进包**):`changes-value-eval.mjs`(回放真实提交,量「当时漏改、
|
|
36
|
+
后来被补上」)、`changes-forward-check.mjs`(前向对账:先写预判,再看它多说了什么)。
|
|
37
|
+
|
|
38
|
+
### 安全 / 只读边界
|
|
39
|
+
|
|
40
|
+
- **`src/` 里第一次起子进程**:只允许 `status --porcelain=v1 -z --untracked-files=all` 与
|
|
41
|
+
`rev-parse --show-prefix` 两个子命令,argv 是数组、**从不走 shell**;2.5 s 超时 / 1 MiB stdout /
|
|
42
|
+
200 条解析上限;五种失败各自收敛成一个 `reason`,**一条都不抛**。
|
|
43
|
+
- **每次都带 `--no-optional-locks --no-pager -c core.fsmonitor=false`**
|
|
44
|
+
—— 实测(git 2.50.1):裸 `status` 会**重写 `.git/index`**(300 文件 + untrackedCache + stat 缓存过期时 3/3 次)、
|
|
45
|
+
会**执行 `core.fsmonitor` 指向的钩子**、会在 `core.fsmonitor=true` 时**拉起 builtin 守护进程**;带开关后三种全为 0。
|
|
46
|
+
- **子进程环境白名单**:只继承 `PATH` / locale / `HOME` / `XDG_CONFIG_HOME` / 临时目录等运行时必需品,
|
|
47
|
+
**任何 `GIT_*` 一律不从父进程继承**。实测:`GIT_DIR`+`GIT_WORK_TREE` 会让它去读**另一个仓库**
|
|
48
|
+
(本工作区的改动直接消失)、`GIT_INDEX_FILE` 会换掉索引、`GIT_TRACE` 会往任意路径**写日志**。
|
|
49
|
+
- **不读 diff、不读文件内容、不发网络请求**;载荷里**不含绝对路径**(只有工作区相对路径)。
|
|
50
|
+
|
|
51
|
+
### 成本与降级
|
|
52
|
+
|
|
53
|
+
- 一轮轮询(两条请求)= **一次工作区扫描 + 一次 `git status`**:扫描备忘与 git 缓存**同窗 8 秒**、
|
|
54
|
+
并发去重;**关闭时两者都是 0**。真机用例正面证明过复用(窗口内删掉一个文件,两边都还看不见;
|
|
55
|
+
清掉缓存后同时反映)。
|
|
56
|
+
- 任何一步失败(不是仓库 / 没装 git / 超时 / 输出过大 / 读取失败 / 接口请求失败)都**只让这一区消失或说明原因**,
|
|
57
|
+
普通列表与 Context Pack **一个字节都不坏**。
|
|
58
|
+
|
|
59
|
+
### 变化
|
|
60
|
+
|
|
61
|
+
- **README / README.en.md**:安装示例里的测试数 775 → **828**(两份同步)。
|
|
62
|
+
- **`SECURITY.md`**:补上「只读 git」与「子进程环境白名单」两条,含实测数字。
|
|
63
|
+
- **测试 828 项 / 34 个文件**(新增 `test/git-changes.test.mjs` 与 `test/http-harness.mjs`;
|
|
64
|
+
`test/host-http.test.mjs` 的服务器替身抽到 `test/http-harness.mjs` 共用)。
|
|
65
|
+
|
|
66
|
+
### 需要重启 DSH
|
|
67
|
+
|
|
68
|
+
本版**改了宿主半边**(`src/host/*`)—— 与 v0.23.x「只要硬刷新」不同:**升级后需要重启 DSH**,
|
|
69
|
+
否则 `/knit/api/changes` 不存在,状态行那一格会显示「变更 —」并写明原因。
|
|
70
|
+
|
|
6
71
|
## [0.23.1] - 2026-10-13
|
|
7
72
|
|
|
8
73
|
> **本版定位**:这一版**不是纯 patch** —— 它一边修包装/文案,一边带了一次**用户可见的工具栏收敛**。
|
|
@@ -84,6 +149,17 @@
|
|
|
84
149
|
不做禁用态的死控件;不重排三层、编号、预览与键盘导航的既有纪律。
|
|
85
150
|
- **不承诺**语义收益:真 provider 的实测仍未跑(`value-evidence: pending`),本版只改**信息准确性**与**工具栏形状**。
|
|
86
151
|
|
|
152
|
+
> ✅ **2026-10-13 已发布**:轻量 tag `v0.23.1` = 发布提交 `2925ad3` = npm `gitHead`;OIDC 可信发布
|
|
153
|
+
> run `38322653330`(**第 2 次尝试**才绿 —— 第 1 次红在 `test/index-incremental.test.mjs` 那条 v0.22 带来的
|
|
154
|
+
> **间歇性**用例上;与 0.23.0 那次是**同一根因、不同断言**,见发布 skill 台账 **B26**)、
|
|
155
|
+
> `conclusion=success`、**带 SLSA provenance**;registry `latest = 0.23.1`(共 **21 个**版本);
|
|
156
|
+
> GitHub Release `published_at 2026-10-12T23:36:24Z`。
|
|
157
|
+
> registry 上的真包 = **65 文件 / 748 583 B tarball / 2 190 275 B 解包**、
|
|
158
|
+
> shasum `1182685ac18cacd6ff337e1963f82a0528978af1`(= registry `dist.shasum`),下载解包后 `npm test` **775 / 0**。
|
|
159
|
+
> 🔑 **本版发布的首要判据已达成**:包内 `README.md` 的 `728` = **0**、`775` = **2**(0.23.0 那份是 728×2)。
|
|
160
|
+
> `check-published.mjs --online` **27/27 全过、零红** —— 0.23.0 那次唯一红掉的正是这条内容判据。
|
|
161
|
+
> ⚠️ **这一行不在已发布的 tarball 里** —— 改它的提交只能在 `npm publish` 之后(同一版本号不能再发一次)。
|
|
162
|
+
|
|
87
163
|
## [0.23.0] - 2026-10-12
|
|
88
164
|
|
|
89
165
|
> **Optional Hybrid Retrieval(可选混合检索)** —— 在**保留「可解释的词法检索」为默认**的前提下,
|
package/README.en.md
CHANGED
|
@@ -11,8 +11,10 @@ read, and whether they changed after being read**.
|
|
|
11
11
|
|
|
12
12
|
**Find → Organise → Track**, all of it plain string work on your own machine in the **default lexical
|
|
13
13
|
mode** — no model calls, no network, no latency, nothing leaves the machine. The optional **hybrid mode
|
|
14
|
-
is off by default
|
|
15
|
-
|
|
14
|
+
is off by default**: only if you configure a provider **and** switch to hybrid by hand does anything
|
|
15
|
+
leave the machine, and what leaves is **your query text plus each candidate file's title and summary**
|
|
16
|
+
(**never full bodies or absolute paths**) — with two easy-to-miss caveats spelled out under
|
|
17
|
+
**What hybrid mode actually sends** below.
|
|
16
18
|
|
|
17
19
|
```text
|
|
18
20
|
Current task
|
|
@@ -117,11 +119,37 @@ The three differences that matter:
|
|
|
117
119
|
verifiable reason) and **tracking** (which were really read, and whether they changed).
|
|
118
120
|
|
|
119
121
|
**No model calls, no network** in the default lexical mode: all plain string work, no latency, no cost,
|
|
120
|
-
nothing leaves the machine. Optional hybrid mode is off by default
|
|
121
|
-
file **titles and summaries** (never bodies) to that service, and a **loopback** provider keeps
|
|
122
|
+
nothing leaves the machine. Optional hybrid mode is off by default, and a **loopback** provider keeps
|
|
122
123
|
everything on this machine. ⚠️ The **benefit** of semantic retrieval still awaits a real-provider run
|
|
123
124
|
(tracked in-repo as `value-evidence: pending`) — no recall improvement is claimed.
|
|
124
125
|
|
|
126
|
+
### What hybrid mode actually sends
|
|
127
|
+
|
|
128
|
+
This section is written from **recorded request bodies**, not from design intent — for the exact
|
|
129
|
+
commands and per-claim assertions see
|
|
130
|
+
[`docs/evaluations/hybrid-retrieval.md`](https://github.com/PolinniZhong/dsh-knit/blob/main/docs/evaluations/hybrid-retrieval.md) (the audit script
|
|
131
|
+
`tools/semantic-request-audit.mjs` records the body of every request and then checks it claim by claim).
|
|
132
|
+
|
|
133
|
+
**What leaves the machine** (the request body has exactly two top-level fields, `{ model, input }`, and
|
|
134
|
+
`input` is a list of strings):
|
|
135
|
+
|
|
136
|
+
| # | What | Exact boundary |
|
|
137
|
+
|---|---|---|
|
|
138
|
+
| ① | **Your query text** | On the panel path it is the latest user message with substance, truncated to **80 characters**; on the `knit_docs(query=…)` path up to 2000. **Re-sent on every refresh** (document vectors are cached, the query is not) |
|
|
139
|
+
| ② | **Each candidate file's title** | Markdown: the first `# heading` in the body (falling back to the file name). Code: the file name **with** its extension. Images / video: the file name **without** its extension |
|
|
140
|
+
| ③ | **Each candidate file's summary** | Markdown: the **first real prose paragraph, truncated to ≤ 60 characters** — it **comes from the body**. Code: the **workspace-relative directory** (e.g. `src/host/`). Media: none |
|
|
141
|
+
|
|
142
|
+
**What does not leave the machine**: full bodies (the audit probed every long-enough file in the
|
|
143
|
+
workspace at both "first 200 chars" and "middle 200 chars" — not one hit), absolute paths (workspace
|
|
144
|
+
root / home directory / `file://` — not one hit), conversation history, files in your workspace that
|
|
145
|
+
were not selected.
|
|
146
|
+
|
|
147
|
+
⚠️ **Two things that are easy to assume wrongly**:
|
|
148
|
+
① **"summary" does not mean "metadata unrelated to the body"** — a Markdown summary is an excerpt of the
|
|
149
|
+
body, so **up to 60 characters of body text do leave the machine**;
|
|
150
|
+
② **image / video file names are sent too** (they have no summary, so what is sent is the file name
|
|
151
|
+
itself, e.g. `screenshot-media`).
|
|
152
|
+
|
|
125
153
|
---
|
|
126
154
|
|
|
127
155
|
## Install
|
|
@@ -177,7 +205,8 @@ as one of its tabs. Each host is an independent optional dependency; missing one
|
|
|
177
205
|
| Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
|
|
178
206
|
| Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
|
|
179
207
|
| **Zero model calls / zero network egress by default**: the default **lexical mode** is plain string work on this machine | ✅ |
|
|
180
|
-
| **Optional hybrid mode (off by default)** (v0.23): needs a provider you configure (Ollama / OpenAI-compatible). With a **remote** provider, what leaves the machine is
|
|
208
|
+
| **Optional hybrid mode (off by default)** (v0.23): needs a provider you configure (Ollama / OpenAI-compatible). With a **remote** provider, what leaves the machine is **your query text plus each candidate file's title and summary** — never full bodies or absolute paths, but note that a Markdown "summary" is a **≤ 60-character excerpt of the body** and image / video files send their **file name** (the exact boundaries are in **What hybrid mode actually sends** above); vectors live in memory only and the config sits in its own DSH storage unit (`knit_semantic`). A **loopback** provider keeps everything local. ⚠️ The **benefit** of semantic retrieval still awaits a real-provider run (`value-evidence: pending`) — no recall improvement is claimed | ✅ |
|
|
209
|
+
| **Git change links (off by default)** (v0.24): lists "what else to look at" from your **uncommitted changes**, using the evidence Knit already has (references / imports / test pairing / doc mentions) — every row names its **origin, kind and line**. **Read-only**: one `git status` (fsmonitor and optional index refresh disabled, child-process environment whitelisted so no `GIT_*` is inherited), **no diff, no file bodies, no network**; when it cannot read, it writes the reason in the panel instead of hiding it in a tooltip. ⚠️ This version adds a host route — **restart DSH after upgrading** | ✅ |
|
|
181
210
|
| **A `knit_docs` tool for the agent** — read-only, so the model can find this project's relevant docs itself | ✅ |
|
|
182
211
|
|
|
183
212
|
> Relevance is deliberately **not visualised** (no percentages, no bars) — the ranking itself is
|
|
@@ -798,7 +827,7 @@ feature request.
|
|
|
798
827
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
799
828
|
cd dsh-knit
|
|
800
829
|
|
|
801
|
-
npm test #
|
|
830
|
+
npm test # 828 tests, zero dependencies, no npm install needed
|
|
802
831
|
```
|
|
803
832
|
|
|
804
833
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -826,7 +855,7 @@ knit/
|
|
|
826
855
|
│ ├── host/feedback.js # usage feedback: read-time attribution / Context Epoch / delta (pure)
|
|
827
856
|
│ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
|
|
828
857
|
│ └── client/client.js # dual-host registration + panel UI
|
|
829
|
-
└── test/ #
|
|
858
|
+
└── test/ # 828 tests
|
|
830
859
|
├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
|
|
831
860
|
└── context/ # context tiering: 24-doc corpus + 12 real-task cases
|
|
832
861
|
```
|
package/README.md
CHANGED
|
@@ -9,7 +9,9 @@ Knit 接的是**当前任务**和**整个工作区**之间那一层:从工作
|
|
|
9
9
|
再持续追踪这些上下文**有没有被读、被读之后有没有变**。
|
|
10
10
|
|
|
11
11
|
**找到 → 组织 → 追踪**,默认的**词法模式**三步都在本机用字符串运算完成 —— 不调模型、不联网、零延迟、内容不出本机。
|
|
12
|
-
|
|
12
|
+
可选的**混合模式默认关闭**:只有你自己配好 provider **并且**手动切到混合检索,才会有出网请求;
|
|
13
|
+
那时发出去的是**你这句查询原话 + 每篇候选文件的标题与摘要**(**完整正文、绝对路径都不发**)——
|
|
14
|
+
⚠️ 这里有两个容易想当然的地方,见下面的「**混合模式到底发出去了什么**」。
|
|
13
15
|
|
|
14
16
|
```text
|
|
15
17
|
当前任务
|
|
@@ -105,8 +107,29 @@ v0.19 起代码进了同一条链路。再往后,「排在前面」也不够
|
|
|
105
107
|
3. **它不止于「找」**:找完还要**组织**(三层 + 可核验的理由)和**追踪**(哪些真被读了、读完有没有变)。
|
|
106
108
|
|
|
107
109
|
**默认词法模式下不调模型、不联网**:全是本地字符串运算,零延迟、零成本、内容不出本机。
|
|
108
|
-
|
|
109
|
-
|
|
110
|
+
可选的**混合模式默认关闭**,指向**本机服务(loopback)**时内容不出这台机器。
|
|
111
|
+
⚠️ 语义收益仍待真 provider 实测(`value-evidence: pending`),不承诺召回提升。
|
|
112
|
+
|
|
113
|
+
### 混合模式到底发出去了什么
|
|
114
|
+
|
|
115
|
+
这段是**按报文实测**写的,不是按设计意图写的 —— 复现命令与逐条断言见
|
|
116
|
+
[`docs/evaluations/hybrid-retrieval.md`](https://github.com/PolinniZhong/dsh-knit/blob/main/docs/evaluations/hybrid-retrieval.md)(审计脚本
|
|
117
|
+
`tools/semantic-request-audit.mjs` 会把每一次请求的 body 录下来再逐条判)。
|
|
118
|
+
|
|
119
|
+
**发出去了**(请求体只有 `{ model, input }` 两个字段,`input` 是一串文本):
|
|
120
|
+
|
|
121
|
+
| # | 内容 | 精确边界 |
|
|
122
|
+
|---|---|---|
|
|
123
|
+
| ① | **你这句查询原话** | 面板走会话路径时是「最近一条有实质内容的用户消息」,截到 **80 字**;`knit_docs(query=…)` 走显式路径时最多 2000 字。**每一轮刷新都会重发一次**(文档向量有缓存,查询没有) |
|
|
124
|
+
| ② | **每篇候选文件的标题** | Markdown 是正文里的第一个 `# 标题`(没有就用文件名);代码是**带扩展名的文件名**;图片 / 视频是**去掉扩展名的文件名** |
|
|
125
|
+
| ③ | **每篇候选文件的摘要** | Markdown 的「摘要」是**正文首个正文段落的节选(≤ 60 字)**——它**来自正文**;代码的「摘要」是**工作区相对目录**(如 `src/host/`);媒体没有摘要 |
|
|
126
|
+
|
|
127
|
+
**没有发出去**:完整正文(审计对工作区里每一篇够长的文件都做了「开头 200 字 + 中段 200 字」两处探针,一处都没出现)、
|
|
128
|
+
绝对路径(工作区根 / 家目录 / `file://` 一条都没出现)、会话历史、你工作区里没被选中的文件。
|
|
129
|
+
|
|
130
|
+
⚠️ **两个容易想当然的地方**:
|
|
131
|
+
①**「摘要」不等于「与正文无关的元数据」**——Markdown 的摘要是正文的节选,所以**会有至多 60 字的正文离开本机**;
|
|
132
|
+
②**图片 / 视频的文件名也会被发出去**(它们没有摘要,发的是文件名本身,例如 `screenshot-media`)。
|
|
110
133
|
|
|
111
134
|
---
|
|
112
135
|
|
|
@@ -167,7 +190,8 @@ dsh plugin --profile web add dsh-knit
|
|
|
167
190
|
| 中英双语,跟随 DSH 语言实时切换(不用重载插件) | ✅ |
|
|
168
191
|
| 列表是标准 `listbox`/`option` 语义,选中项用 `aria-activedescendant` 播报;媒体网格里的键盘焦点有可见描边 | ✅ |
|
|
169
192
|
| **默认零模型 / 零网络出口**:默认的**词法模式**全程在本机做字符串运算 —— 不调模型、不联网、零延迟 | ✅ |
|
|
170
|
-
| **可选混合模式(默认关闭)**(v0.23):需你自己配置 provider(Ollama / OpenAI 兼容)。配了**远程** provider
|
|
193
|
+
| **可选混合模式(默认关闭)**(v0.23):需你自己配置 provider(Ollama / OpenAI 兼容)。配了**远程** provider 时,发出去的是**你这句查询原话 + 每篇候选文件的标题与摘要** —— 完整正文与绝对路径都不发,但 Markdown 的「摘要」是**正文首个段落 ≤ 60 字的节选**、图片 / 视频发的是**文件名**(逐条口径见上面的「**混合模式到底发出去了什么**」);向量只在内存里,配置存在 DSH 存储的独立单元 `knit_semantic`。指向**本机服务(loopback)**时内容不出这台机器。⚠️ **语义收益的证据仍待真 provider 实测**(`value-evidence: pending`)—— 本项目**不承诺**召回提升 | ✅ |
|
|
194
|
+
| **Git 变更关联(默认关闭)**(v0.24):按工作区里**未提交的改动**列出「还该一起看的文件」,依据是 Knit 已有的四类证据(引用 / 导入 / 测试配对 / 文档提及),每条都给出**起点 + 类型 + 行号**。**只读**:只跑一条 `git status`(关掉 fsmonitor 与可选索引刷新,子进程环境白名单 —— 任何 `GIT_*` 都不继承),**不读 diff、不读文件正文、不发网络**;读不到时如实写出原因(不是只放在悬停里)。⚠️ 本版新增宿主接口,**升级后需要重启 DSH** | ✅ |
|
|
171
195
|
|
|
172
196
|
> 相关度**不做可视化**(不显示百分比、不画长条)—— 排序本身就是答案,名次即相关度。
|
|
173
197
|
|
|
@@ -737,7 +761,7 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
737
761
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
738
762
|
cd dsh-knit
|
|
739
763
|
|
|
740
|
-
npm test #
|
|
764
|
+
npm test # 828 项,零依赖,不需要先 npm install
|
|
741
765
|
node tools/clean-room-test.mjs # 发版前闸门:npm pack → 解包 → 在解包目录里再跑一遍测试
|
|
742
766
|
```
|
|
743
767
|
|
|
@@ -768,7 +792,7 @@ knit/
|
|
|
768
792
|
│ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
|
|
769
793
|
│ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
|
|
770
794
|
│ └── client/client.js # 双宿主注册 + 面板 UI
|
|
771
|
-
└── test/ #
|
|
795
|
+
└── test/ # 828 项测试
|
|
772
796
|
├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线 + Deep Context 四指标
|
|
773
797
|
└── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
|
|
774
798
|
```
|
package/SECURITY.md
CHANGED
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
> **Knit 的安全属性 —— 每一条都指向一个真实存在的检查。**
|
|
4
4
|
>
|
|
5
|
-
> 最后更新:2026-10-
|
|
5
|
+
> 最后更新:2026-10-14(v0.24.0)—— **本版动过安全面**:`src/` 里第一次起子进程(只读 git),
|
|
6
|
+
> 因此新增两条 —— 子命令 / argv 白名单,以及**子进程环境白名单**(任何 `GIT_*` 都不从父进程继承);
|
|
6
7
|
> 版本号随每版前移,好让「安全表被漏掉」与「本版没动安全面」在版本一致性检查里能分开
|
|
7
8
|
>
|
|
8
9
|
> 📌 **v0.23.0(2026-10-12)那次改了什么**:写通道由一条变两条(新增 `POST /knit/api/semantic`,只存 provider 配置)、
|
|
@@ -39,8 +40,10 @@ Knit 的安全属性其实一直成立 —— 但它们此前只散落在文档
|
|
|
39
40
|
| 只允许 GET、只允许回环地址(写通道是**例外**,不是放开 POST) | ✅ | `test/host-http.test.mjs`。写路由**只认 POST**、GET 打它回 405;**别的路由的 POST 仍回 405**(有对照断言);坏 body 回 400。v0.21 起有 `POST /knit/api/control`(写固定 / 排除,只接受 `pin`/`unpin`/`exclude`/`restore` 四个动作 + 一条工作区内的相对路径) |
|
|
40
41
|
| 会写盘的东西只有三类,且只写 DSH 给的存储单元 —— **不碰工作区里的任何文件** | ✅ | 三个 kv 单元各开各的:`knit_control`(`src/host/control.js`,v0.21,固定 / 排除)、`knit_index`(`src/host/index-store.js`,v0.22,增量索引,**非 HTTP 触发**)、`knit_semantic`(`src/host/semantic.js`,v0.23,**只存 provider 配置**,向量只在内存)。落盘路径由 DSH 的 storage 服务决定,Knit 不自己拼;`test/control.test.mjs` + `test/index-store.test.mjs` |
|
|
41
42
|
| 第二条写通道 `POST /knit/api/semantic` 的主机侧 e2e 守卫 | ⚠️ | **如实说明(v0.23 新增,尚未补)**:它目前只有**客户端侧**断言(`test/client.test.mjs` 认这条 URL),**没有**像 `/api/control` 那样在真实回环端口上验「GET→405 / 别的路由 POST→405 / 坏 body→400」。两条写路由在 `src/host/index.js` 里共用同一段前置守卫,但「共用同一段代码」**不等于**「被验过」 |
|
|
43
|
+
| **Git 变更关联只跑一条只读的 `git status`**(v0.25;这是 `src/` 里**唯一**会起子进程的地方) | ✅ | `src/host/git.js` 只允许两个子命令(`GIT_STATUS_ARGS` = `status --porcelain=v1 -z --untracked-files=all`、`GIT_PREFIX_ARGS` = `rev-parse --show-prefix`),argv 是**数组**、从不走 shell;`test/git-changes.test.mjs` 把这两个 argv 与 19 个写动词(`add`/`commit`/`checkout`/`reset`/`clean`/`stash`/`push`…)逐个比对,并断言**不开** `--ignored`。**并且**子进程环境是**白名单筛过的**(`gitEnv()` / `GIT_ENV_ALLOW`):只继承 `PATH` / locale / `HOME` / `XDG_CONFIG_HOME` / 临时目录等运行时必需品,**任何 `GIT_*` 一律不从父进程继承**(前缀规则,git 将来新增的变量自动覆盖)—— 实测这些变量真的会改变行为:`GIT_DIR`+`GIT_WORK_TREE` 会让 `git status` **去读另一个仓库**(本工作区的改动直接消失)、`GIT_INDEX_FILE` 会**换掉索引**(已提交的文件被报成 `D`+`??`,结果里混进别的仓库的文件名)、`GIT_TRACE` 会**往指定路径写日志**;`spawn` 另带 `--no-optional-locks --no-pager -c core.fsmonitor=false` + 环境 `GIT_OPTIONAL_LOCKS=0` / `GIT_PAGER=cat` / `GIT_TERMINAL_PROMPT=0` —— 这一层挡的是「git 自己被配置牵着去写盘 / 去起进程」:实测(git 2.50.1)裸 `status` 会**重写 `.git/index`**(300 文件 + untrackedCache + stat 缓存过期时 3/3 次)、会**执行 `core.fsmonitor` 指向的钩子**、会在 `core.fsmonitor=true` 时**拉起 builtin 守护进程**(`.git/fsmonitor--daemon` 落盘);加了上面这些之后三种副作用全部为 0。有界:2.5 s 超时、1 MiB stdout、200 条解析;五种失败各自收敛成一个 reason,**一条都不抛**。它**不读 diff、不读文件内容、不发网络请求** |
|
|
42
44
|
| 响应带 `nosniff` 与 `default-src 'none'; sandbox` | ✅ | `test/host-http.test.mjs`(两个指令各自断言) |
|
|
43
|
-
|
|
|
45
|
+
| 客户端半边零网络出口:`src/client/client.js` 的全部 `fetch` 都是同源相对路径 | ✅ | `src/client/client.js` 的三个接口常量都是 `/knit/api/*`;`test/security.test.mjs` 断言无协议头。HTML 的「网页预览」按钮是把文件交给 **DSH 自己的**文档预览标签页去渲染(Knit 这一侧一个请求都不发),渲染的沙箱与 CSP 归 DSH 管 —— 所以这条承诺不变。⚠️ **这只覆盖浏览器半边**;宿主半边在**可选混合模式**下会出网,见下面那一条 |
|
|
46
|
+
| 宿主半边的出网只有一个点,且**默认一次都不发**:`src/host/semantic.js` 的 `createSemanticProvider()` | ⚠️ | **如实说明**:默认词法模式下**一次 provider 调用都不发**(`test/hybrid-retrieval.test.mjs` 判据 1 钉住,连探测都不发);只有「用户配好 provider **且**手动切到混合检索」才会走那条路。发出的是**查询原话 + 标题 + 摘要**,不含完整正文与绝对路径 —— 报文级实测在仓库根 tools/semantic-request-audit.mjs(**该脚本不随包发布**,所以这条目前是**人工跑的量尺**,不是 `npm test` 里的守卫) |
|
|
44
47
|
| 宿主半边不 import `@deepseek-ai/*` | ✅ | `test/security.test.mjs` 扫三个宿主文件,注释里提到可以、真实 `import` 不行 |
|
|
45
48
|
| `knit_docs` 工具只读,不写任何文件 | ✅ | `src/host/tool.js` 只调注入进来的 `scan` 与只读的 `readDocument`;无写文件调用 |
|
|
46
49
|
| 未经第三方安全审计 | ⚠️ | **如实说明**:这张表是**自证**。没有外部审计报告,也没有自动化扫描评分 —— 它不等于「已证明安全」 |
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-knit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.24.0",
|
|
4
4
|
"type": "module",
|
|
5
|
-
"description": "
|
|
5
|
+
"description": "Context retrieval for DeepSeek Harness: ranks docs, code and media by relevance into a sidebar Context Pack. Lexical and fully local by default. Hybrid is off until you configure a provider; it sends your query and file titles/summaries, not bodies.",
|
|
6
6
|
"main": "./src/host/index.js",
|
|
7
7
|
"exports": {
|
|
8
8
|
".": "./src/host/index.js",
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
],
|
|
25
25
|
"scripts": {
|
|
26
26
|
"agents:budget": "node tools/agents-budget.mjs",
|
|
27
|
-
"test": "node --test test/host.test.mjs test/host-http.test.mjs test/client.test.mjs test/tier1.test.mjs test/entry.test.mjs test/i18n.test.mjs test/icon.test.mjs test/path.test.mjs test/peek.test.mjs test/eval.test.mjs test/tool.test.mjs test/label.test.mjs test/links.test.mjs test/relations.test.mjs test/control.test.mjs test/security.test.mjs test/context.test.mjs test/context-eval.test.mjs test/feedback.test.mjs test/context-delta.test.mjs test/context-feedback-eval.test.mjs test/context-effectiveness.test.mjs test/document-lifecycle.test.mjs test/classification.test.mjs test/code-context.test.mjs test/deep-context.test.mjs test/deep-eval.test.mjs test/deep-scale.test.mjs test/index-store.test.mjs test/index-incremental.test.mjs test/hybrid-eval.test.mjs test/semantic.test.mjs test/hybrid-retrieval.test.mjs"
|
|
27
|
+
"test": "node --test test/host.test.mjs test/host-http.test.mjs test/client.test.mjs test/tier1.test.mjs test/entry.test.mjs test/i18n.test.mjs test/icon.test.mjs test/path.test.mjs test/peek.test.mjs test/eval.test.mjs test/tool.test.mjs test/label.test.mjs test/links.test.mjs test/relations.test.mjs test/control.test.mjs test/security.test.mjs test/context.test.mjs test/context-eval.test.mjs test/feedback.test.mjs test/context-delta.test.mjs test/context-feedback-eval.test.mjs test/context-effectiveness.test.mjs test/document-lifecycle.test.mjs test/classification.test.mjs test/code-context.test.mjs test/deep-context.test.mjs test/deep-eval.test.mjs test/deep-scale.test.mjs test/index-store.test.mjs test/index-incremental.test.mjs test/hybrid-eval.test.mjs test/semantic.test.mjs test/hybrid-retrieval.test.mjs test/git-changes.test.mjs"
|
|
28
28
|
},
|
|
29
29
|
"dsh": {
|
|
30
30
|
"bundle": {
|