dsh-knit 0.23.1 → 0.25.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 CHANGED
@@ -3,6 +3,131 @@
3
3
  本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
4
4
  版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
5
5
 
6
+ ## [0.25.0] - 2026-10-31
7
+
8
+ > **本版主题**:「看图」这件事从「点一下占半屏」变成**停一下看大图 / 双击看全屏**,
9
+ > 并第一次把**对话里生成的图**接进媒体档(只显示、只去重,不往你的项目里写任何文件)。
10
+ > 按 semver 这是 minor:多了用户可见能力 + 两条宿主路由;媒体档的交互变了,但那是新特性区。
11
+
12
+ ### 新增
13
+
14
+ - **对话里生成的图出现在媒体档**(`src/host/attachments.js` 新增):DSH 把对话里的图存在
15
+ `<dsh home>/attachments/v1/objects/<前两位>/<sha256>`,**在工作区之外** ⇒ Knit 之前完全看不到。
16
+ 现在从**本会话的 `tool/result` 事件**取元数据(零 I/O),显示时按 **sha256 只读**那一个对象。
17
+ 三条边界:① 只认 `sha256:<64 hex>`、**不接受任何路径**;② id 必须**在本会话工具产出里出现过**
18
+ (跨会话 / 用户自己贴的图一律 404);③ 只回 `image/*` `video/*`、走既有 `sendMedia`。
19
+ **去重按内容**:工作区里已有同字节文件 ⇒ 它从列表消失(存成什么名字都行)。
20
+ 两条新路由:`GET /knit/api/attachments`、`GET /knit/api/attachment`。⚠️ **改了宿主半边 ⇒ 升级后要重启 DSH**。
21
+ - **悬停看大图**:鼠标在图片卡片上停 350ms 弹出大图(上限 **420×420**,按可用空间收缩;优先摆在卡片左侧,
22
+ 左边放不下就翻右侧;滚动即收)。只做图片,`pointer-events:none` 不挡点击。
23
+ - **双击全屏查看器**:双击图片进**整屏**查看器(portal 到 `document.body` + 模态级层级 +
24
+ 毛玻璃遮罩,**随深色模式变**),左侧一列「当前这张附近 10 张」缩略图(**点缩略图直接切**,换图时当前那张自动滚进可视区),`↑↓`(左列是竖的)+ `←→` 翻页、**在图片区滚轮**也能翻(滚轮在左列上仍是滚列表,不被抢)、`Esc` / `✕` / 点图片以外关闭;工具条带**收藏 / 本地打开**。
25
+ - **媒体档排序固定按时间**:媒体档**不看相关性**(用户:「图片不需要有这种逻辑」)—— 请求直接发 `sort=time`,
26
+ 网格合并「工作区文件 + 对话图」后按时间倒序,收藏仍前移;那一档的排序组**禁用并如实显示「最新」在生效**。
27
+
28
+ ### 变更
29
+
30
+ - **媒体档取消「单击就地预览」**(用户裁决):单击 / `↑↓` **只移光标**,看东西走悬停或双击 / `Enter`。
31
+ 连带:**收藏 / 本地打开搬进全屏查看器**(对话图不显示这两个按钮 —— 它没有工作区路径);
32
+ **视频仍走就地预览**(查看器只做图片),入口改成双击 / `Enter`。
33
+ - **图片的双击**从「开新标签页」改为「进全屏查看器」(文档 / 代码的双击仍是开标签页)。
34
+
35
+ ### 修复 / 内部
36
+
37
+ - **修掉连续四个版本各红一次 CI 的那条 flake**:`index-incremental.test.mjs` 的「同 mtime 同 size」场景
38
+ 以前用 `utimesSync` 按浮点秒「还原」mtime,Linux 上还原不出逐位相同的 `mtimeMs` ⇒ 场景根本没造出来,
39
+ 指纹抽验没被考到(`v0.23.0` / `v0.23.1` / `v0.24.0` / `v0.25.0` 各红一次)。现在两次 mtime 都钉成
40
+ **同一个显式整数秒**,断言从 `|Δmtime| ≤ 1` 收紧到 `===`。
41
+ - SECURITY.md 增加一行:**读工作区之外的唯一一处**,三条边界逐条指向真实检查。
42
+ - 指令文件(L0/L1)同步:媒体档例外写进 §7.2 / §7.4,测试数 883、测试文件 35。
43
+
44
+ ### 验收状态
45
+
46
+ - 自动化:`npm test` **883/883**(35 个文件)、解包净室 **883/0**、指令预算闸门 ✓、
47
+ 每批新守卫都做过**突变证伪**(本版累计 30+ 条,全部如期变红)。
48
+ - ✅ **真机验收已过**(2026-10-31,用户逐条点过下面 4 条并判定通过):
49
+ ① 双击图片 → **全屏查看器盖住整个屏幕**(连左侧栏与对话一起;这一条是本版**唯一**在 Node 替身里验不到的
50
+ 机制 —— portal 到 `document.body`,那里只有形状守卫);② 查看器里 `↑↓` 翻页 / `Esc` 关闭 /
51
+ 点图片以外关闭 / **点图片本身不关**;③ 媒体档**单击不再弹预览**;④ 对话里生成的图出现在媒体档,**重启 DSH 后仍在**。
52
+ ⚠️ 交接单里其余条目由自动化守卫覆盖,**没有**逐条人工复核 —— 这里只记人确实看过的那 4 条。
53
+
54
+ ## [0.24.0] - 2026-10-14
55
+
56
+ > **本版定位**:新增一个**默认关闭**的能力 —— **Git 变更关联**:按工作区里**未提交的改动**
57
+ > 去找「还该一起看的文件」,依据是 Knit 已经有的那四类证据(引用 / 导入 / 测试配对 / 文档提及)。
58
+ > 按 semver 这是 minor:多了一条**用户可见**的能力、一条宿主路由,而且 `src/` 里**第一次**出现子进程。
59
+ >
60
+ > ⚠️ **本版占用了 `v0.24` 这个号**。v0.20.0 节曾把「语义/向量检索、把片段当排序基本实体、第二套预览框架」
61
+ > 写成「留 v0.24」—— 那是一次**非正式**的候选登记,不是承诺:其中「语义/向量检索」已由 **v0.23.0
62
+ > 的可选混合检索**落地;另外两条仍未做,**不因此占号**。旧节保持原样(历史不改写),以本节为准。
63
+ >
64
+ > **三条边界(本版的重点不是「找得更多」,而是「说得更准」)**:
65
+ > ① **`knit_docs` 与 `/knit/api/recent` 的契约一个字节未改** —— 关联走**独立接口**,专用结构,不往既有
66
+ > 响应里塞字段(`src/host/context.js` / `src/host/tool.js` 回到 v0.23.1 **逐字一致**);
67
+ > ② **只读** —— 固定 argv、不走 shell、关掉 fsmonitor 与可选索引刷新,且**子进程环境是白名单筛过的**;
68
+ > ③ **默认关** —— 关着时客户端一个请求都不发、宿主一个 git 进程都不 spawn。
69
+
70
+ ### 新增
71
+
72
+ - **`GET /knit/api/changes`**:独立只读接口,返回**专用结构**
73
+ (`git{available,reason,filesTotal,truncated,files[]}` +
74
+ `links[{target, kind, source, title, summary, mtimeMs, evidence[{origin,type,dir,line}], evidenceTotal, types}]` +
75
+ `linksTotal / unresolved / outOfScope`)。**起点 / 目标 / 关系类型 / 方向 / 行号**逐条给全;
76
+ `tests` 那一类是文件名约定,`line` 如实为 `null`,不编行号。
77
+ - **面板状态行多一格二态开关「变更」**(默认关)。开态只把字色提亮(`aria-pressed`),不换底色、不用品牌色;
78
+ 与「固定 / 关系」同属「这一份包里还装了什么」那一组,参与中点分隔、不参与编号。
79
+ - **变更关联区**:不编号的平行区,与三层互不影响;每条结果点开就是**既有那套行级证据**
80
+ (类型 · 起点 · 行号),零第二条渲染路径。
81
+ - **降级可辨(三种状态互不混淆)**:读到了没有变更写「变更 0」;有变更但零关联时**出区头 + 提示句**;
82
+ 读不到写「变更 —」并把原因**直接写在列表里**(不是只放悬停)。
83
+ - **两个开发量尺**(`tools/`,**不进包**):`changes-value-eval.mjs`(回放真实提交,量「当时漏改、
84
+ 后来被补上」)、`changes-forward-check.mjs`(前向对账:先写预判,再看它多说了什么)。
85
+
86
+ ### 安全 / 只读边界
87
+
88
+ - **`src/` 里第一次起子进程**:只允许 `status --porcelain=v1 -z --untracked-files=all` 与
89
+ `rev-parse --show-prefix` 两个子命令,argv 是数组、**从不走 shell**;2.5 s 超时 / 1 MiB stdout /
90
+ 200 条解析上限;五种失败各自收敛成一个 `reason`,**一条都不抛**。
91
+ - **每次都带 `--no-optional-locks --no-pager -c core.fsmonitor=false`**
92
+ —— 实测(git 2.50.1):裸 `status` 会**重写 `.git/index`**(300 文件 + untrackedCache + stat 缓存过期时 3/3 次)、
93
+ 会**执行 `core.fsmonitor` 指向的钩子**、会在 `core.fsmonitor=true` 时**拉起 builtin 守护进程**;带开关后三种全为 0。
94
+ - **子进程环境白名单**:只继承 `PATH` / locale / `HOME` / `XDG_CONFIG_HOME` / 临时目录等运行时必需品,
95
+ **任何 `GIT_*` 一律不从父进程继承**。实测:`GIT_DIR`+`GIT_WORK_TREE` 会让它去读**另一个仓库**
96
+ (本工作区的改动直接消失)、`GIT_INDEX_FILE` 会换掉索引、`GIT_TRACE` 会往任意路径**写日志**。
97
+ - **不读 diff、不读文件内容、不发网络请求**;载荷里**不含绝对路径**(只有工作区相对路径)。
98
+
99
+ ### 成本与降级
100
+
101
+ - 一轮轮询(两条请求)= **一次工作区扫描 + 一次 `git status`**:扫描备忘与 git 缓存**同窗 8 秒**、
102
+ 并发去重;**关闭时两者都是 0**。真机用例正面证明过复用(窗口内删掉一个文件,两边都还看不见;
103
+ 清掉缓存后同时反映)。
104
+ - 任何一步失败(不是仓库 / 没装 git / 超时 / 输出过大 / 读取失败 / 接口请求失败)都**只让这一区消失或说明原因**,
105
+ 普通列表与 Context Pack **一个字节都不坏**。
106
+
107
+ ### 变化
108
+
109
+ - **README / README.en.md**:安装示例里的测试数 775 → **828**(两份同步)。
110
+ - **`SECURITY.md`**:补上「只读 git」与「子进程环境白名单」两条,含实测数字。
111
+ - **测试 828 项 / 34 个文件**(新增 `test/git-changes.test.mjs` 与 `test/http-harness.mjs`;
112
+ `test/host-http.test.mjs` 的服务器替身抽到 `test/http-harness.mjs` 共用)。
113
+
114
+ ### 需要重启 DSH
115
+
116
+ 本版**改了宿主半边**(`src/host/*`)—— 与 v0.23.x「只要硬刷新」不同:**升级后需要重启 DSH**,
117
+ 否则 `/knit/api/changes` 不存在,状态行那一格会显示「变更 —」并写明原因。
118
+
119
+ > ✅ **2026-10-14 已发布**:轻量 tag `v0.24.0` = 发布提交 `cc51791` = npm `gitHead`;OIDC 可信发布
120
+ > run `38485942612`(**第 2 次尝试**才绿 —— 第 1 次又红在 `test/index-incremental.test.mjs:168` 那条
121
+ > **间歇性**用例上;这是**连续第三个版本**撞它 ⇒ 见发布 skill 台账 B27 / B32)、`conclusion=success`、
122
+ > **带 SLSA provenance**;registry `latest = 0.24.0`(共 **22 个**版本);GitHub Release
123
+ > `published_at 2026-10-13T23:47:54Z`。
124
+ > registry 上的真包 = **69 文件 / 802 076 B tarball / 2 357 111 B 解包**、
125
+ > shasum `4a9d1ac1e4369039dceb804a5ebae9f8cb1b871b`(= registry `dist.shasum`),下载解包后 `npm test` **828 / 0**。
126
+ > 本地 pack 基线 = **791 091 B / `2208ae8e832f3f6d2f2cfb5d728ea0582043b937` / 69 条目 / 解包 2 357 111 B**(连打两次逐字节相同)。
127
+ > ⚠️ 本地 pack 的字节数与 shasum 和 registry **历来对不上**(差的是 tar/gzip 框架元数据)—— 能跨端比的是
128
+ > 「下载件 sha1 == `dist.shasum`」与「`fileCount` / `unpackedSize` == 本地 pack」这两条。
129
+ > ⚠️ **这一行不在已发布的 tarball 里** —— 改它的提交只能在 `npm publish` 之后(同一版本号不能再发一次)。
130
+
6
131
  ## [0.23.1] - 2026-10-13
7
132
 
8
133
  > **本版定位**:这一版**不是纯 patch** —— 它一边修包装/文案,一边带了一次**用户可见的工具栏收敛**。
@@ -84,6 +209,17 @@
84
209
  不做禁用态的死控件;不重排三层、编号、预览与键盘导航的既有纪律。
85
210
  - **不承诺**语义收益:真 provider 的实测仍未跑(`value-evidence: pending`),本版只改**信息准确性**与**工具栏形状**。
86
211
 
212
+ > ✅ **2026-10-13 已发布**:轻量 tag `v0.23.1` = 发布提交 `2925ad3` = npm `gitHead`;OIDC 可信发布
213
+ > run `38322653330`(**第 2 次尝试**才绿 —— 第 1 次红在 `test/index-incremental.test.mjs` 那条 v0.22 带来的
214
+ > **间歇性**用例上;与 0.23.0 那次是**同一根因、不同断言**,见发布 skill 台账 **B26**)、
215
+ > `conclusion=success`、**带 SLSA provenance**;registry `latest = 0.23.1`(共 **21 个**版本);
216
+ > GitHub Release `published_at 2026-10-12T23:36:24Z`。
217
+ > registry 上的真包 = **65 文件 / 748 583 B tarball / 2 190 275 B 解包**、
218
+ > shasum `1182685ac18cacd6ff337e1963f82a0528978af1`(= registry `dist.shasum`),下载解包后 `npm test` **775 / 0**。
219
+ > 🔑 **本版发布的首要判据已达成**:包内 `README.md` 的 `728` = **0**、`775` = **2**(0.23.0 那份是 728×2)。
220
+ > `check-published.mjs --online` **27/27 全过、零红** —— 0.23.0 那次唯一红掉的正是这条内容判据。
221
+ > ⚠️ **这一行不在已发布的 tarball 里** —— 改它的提交只能在 `npm publish` 之后(同一版本号不能再发一次)。
222
+
87
223
  ## [0.23.0] - 2026-10-12
88
224
 
89
225
  > **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** (it needs a provider you configure; with a **remote** provider it receives file
15
- **titles and summaries**, never bodies) — see below.
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; with a **remote** provider it sends
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 the workspace files' **titles and summaries** (**never bodies**); 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 | ✅ |
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 # 775 tests, zero dependencies, no npm install needed
830
+ npm test # 883 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/ # 775 tests
858
+ └── test/ # 883 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
- 可选的**混合模式默认关闭**(需你自己配置 provider;配了**远程** provider 时它会收到文件的**标题与摘要**,正文不发送),见下。
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
- 可选的**混合模式默认关闭**:配了**远程** provider 时它只把文件的**标题与摘要**发过去(正文不发送),
109
- 指向**本机服务(loopback)**时内容不出这台机器。⚠️ 语义收益仍待真 provider 实测(`value-evidence: pending`),不承诺召回提升。
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
 
@@ -149,15 +172,17 @@ dsh plugin --profile web add dsh-knit
149
172
  | 代码预览:行号 + 等宽 + 横向滚动 + 复制 + 「本地打开」;同名 `app.js.map` 存在时预览页脚多一个低权重「Source map」入口(点开按纯文本看,`.map` 本身不进上下文) | ✅ |
150
173
  | 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
151
174
  | 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径**重复,只保留后者 | ✅ |
152
- | 单击就地展开预览,再点收起 | ✅ |
175
+ | 单击就地展开预览,再点收起(**媒体档例外**:单击只移光标,看东西用悬停 / 双击,见下两行) | ✅ |
153
176
  | 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
154
177
  | **代码上下文**(v0.19):`.js .mjs .cjs .ts .tsx .jsx .py .json .html .htm .css .scss .yaml .yml .sh .bash .zsh` 与 Markdown **进同一个检索池**,共用同一份 BM25、同一个 Context Pack、同一套生命周期 —— 不是第二套「代码搜索」 | ✅ |
155
178
  | **文档 / 代码 / 媒体** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**下划线式页签**(v0.14 起就是这个;不带品牌色描边、也**没**退回灰底按钮 —— 2026-09-29 明确裁定过;页签「媒体」2026-10-06 由「图片与视频」改短,「代码」v0.19 加入;**「全部」档 v0.23.1 已从 UI 删除**) | ✅ |
156
179
  | 图片与视频:方形缩略图网格,**格子基准固定 104px、列数由宽度连续数出来**(320px → 2 列 / 632px → 5 列 / 1200px → 10 列),格子大小基本不变;**纵向有多少行就铺多少行**,超出交给列表滚动;视频自动取首帧、叠播放三角与时长角标(零依赖、不转码) | ✅ |
157
- | 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
180
+ | **悬停看大图**:鼠标停在图片卡片上 350ms 弹出一张大图(上限 420×420,按可用空间收缩;优先摆左侧,放不下翻右侧;滚动即收)。只做图片 | ✅ |
181
+ | **双击图片 → 整屏查看器**:portal 到整页、模态级层级、**毛玻璃遮罩随深色模式变**;左侧一列「当前这张附近 10 张」缩略图(**点缩略图切图**,当前那张自动滚进可视区);`↑↓` / `←→` / **图片区滚轮**都能翻页、`Esc` / `✕` / 点图片以外关闭;工具条带**收藏 / 本地打开** | ✅ |
182
+ | 双击**视频** → 面板内**就地预览**:可播放可拖动(HTTP Range 流式,不全量下载)。查看器只做图片,视频不进去 | ✅ |
158
183
  | 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出;**全屏时头部 / 排序条 / 类型档 / 使用情况 / 列表全部让位**,预览铺满整个面板 | ✅ |
159
184
  | **「本地打开」**:用系统默认应用打开当前预览的这篇文档;**预览头那条路径点开的是它「所在的文件夹」并顺带选中这个文件**(reveal,macOS 是 Finder 里 `open -R`;与顶部那行工作区路径同一套机制,差别只在「打开目录」vs「定位到文件」,完整相对路径在悬停提示里) | ✅ |
160
- | 双击在新标签页打开(官方文档预览,带 PDF 渲染器与渲染方式切换) | ✅ |
185
+ | 双击**文档 / 代码**在新标签页打开(官方文档预览,带 PDF 渲染器与渲染方式切换);图片的双击改成了查看器 | ✅ |
161
186
  | **HTML 的「网页预览」**(v0.19 追加):预览头只对 `.html` / `.htm` 多一个按钮,点了在官方文档预览标签页里**按网页渲染** —— 那一侧是 DSH 自带的 HTML 渲染器(默认静态档:清洗过的文档 + 不给 sandbox 权限的 iframe + CSP 挡脚本 / 外部资源 / 表单 / 嵌套框架,内联 `<style>` 与 `data:` 图片保留)。就地预览给的是**源码**,两者不重复;其余代码类型不给这个按钮 | ✅ |
162
187
  | 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
163
188
  | **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
@@ -167,7 +192,8 @@ dsh plugin --profile web add dsh-knit
167
192
  | 中英双语,跟随 DSH 语言实时切换(不用重载插件) | ✅ |
168
193
  | 列表是标准 `listbox`/`option` 语义,选中项用 `aria-activedescendant` 播报;媒体网格里的键盘焦点有可见描边 | ✅ |
169
194
  | **默认零模型 / 零网络出口**:默认的**词法模式**全程在本机做字符串运算 —— 不调模型、不联网、零延迟 | ✅ |
170
- | **可选混合模式(默认关闭)**(v0.23):需你自己配置 provider(Ollama / OpenAI 兼容)。配了**远程** provider 时,发出去的是工作区文件的**标题与摘要**(**不发送正文**);向量只在内存里,配置存在 DSH 存储的独立单元 `knit_semantic`。指向**本机服务(loopback)**时内容不出这台机器。⚠️ **语义收益的证据仍待真 provider 实测**(`value-evidence: pending`)—— 本项目**不承诺**召回提升 | ✅ |
195
+ | **可选混合模式(默认关闭)**(v0.23):需你自己配置 provider(Ollama / OpenAI 兼容)。配了**远程** provider 时,发出去的是**你这句查询原话 + 每篇候选文件的标题与摘要** —— 完整正文与绝对路径都不发,但 Markdown 的「摘要」是**正文首个段落 ≤ 60 字的节选**、图片 / 视频发的是**文件名**(逐条口径见上面的「**混合模式到底发出去了什么**」);向量只在内存里,配置存在 DSH 存储的独立单元 `knit_semantic`。指向**本机服务(loopback)**时内容不出这台机器。⚠️ **语义收益的证据仍待真 provider 实测**(`value-evidence: pending`)—— 本项目**不承诺**召回提升 | ✅ |
196
+ | **Git 变更关联(默认关闭)**(v0.24):按工作区里**未提交的改动**列出「还该一起看的文件」,依据是 Knit 已有的四类证据(引用 / 导入 / 测试配对 / 文档提及),每条都给出**起点 + 类型 + 行号**。**只读**:只跑一条 `git status`(关掉 fsmonitor 与可选索引刷新,子进程环境白名单 —— 任何 `GIT_*` 都不继承),**不读 diff、不读文件正文、不发网络**;读不到时如实写出原因(不是只放在悬停里)。⚠️ 本版新增宿主接口,**升级后需要重启 DSH** | ✅ |
171
197
 
172
198
  > 相关度**不做可视化**(不显示百分比、不画长条)—— 排序本身就是答案,名次即相关度。
173
199
 
@@ -737,7 +763,7 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
737
763
  git clone https://github.com/PolinniZhong/dsh-knit.git
738
764
  cd dsh-knit
739
765
 
740
- npm test # 775 项,零依赖,不需要先 npm install
766
+ npm test # 883 项,零依赖,不需要先 npm install
741
767
  node tools/clean-room-test.mjs # 发版前闸门:npm pack → 解包 → 在解包目录里再跑一遍测试
742
768
  ```
743
769
 
@@ -768,7 +794,7 @@ knit/
768
794
  │ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
769
795
  │ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
770
796
  │ └── client/client.js # 双宿主注册 + 面板 UI
771
- └── test/ # 775 项测试
797
+ └── test/ # 883 项测试
772
798
  ├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线 + Deep Context 四指标
773
799
  └── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
774
800
  ```
package/SECURITY.md CHANGED
@@ -2,9 +2,14 @@
2
2
 
3
3
  > **Knit 的安全属性 —— 每一条都指向一个真实存在的检查。**
4
4
  >
5
- > 最后更新:2026-10-13(v0.23.1)—— 本版**无安全相关改动**(只动客户端工具栏与产品文案);
5
+ > 最后更新:2026-10-31(v0.25.0)—— **本版动过安全面**:新增「**读工作区之外的唯一一处**」——
6
+ > 对话里工具产出的图(`GET /knit/api/attachment`):只认 `sha256:<64 hex>`、**不接受任何路径**、
7
+ > id 必须在本会话的工具产出里出现过;三条边界都有 e2e 与**证伪记录**,见下表新增的那一行。
6
8
  > 版本号随每版前移,好让「安全表被漏掉」与「本版没动安全面」在版本一致性检查里能分开
7
9
  >
10
+ > 📌 **v0.24.0(2026-10-14)那次改了什么**:`src/` 里第一次起子进程(只读 git),因此新增两条 ——
11
+ > 子命令 / argv 白名单,以及**子进程环境白名单**(任何 `GIT_*` 都不从父进程继承)
12
+ >
8
13
  > 📌 **v0.23.0(2026-10-12)那次改了什么**:写通道由一条变两条(新增 `POST /knit/api/semantic`,只存 provider 配置)、
9
14
  > 会落盘的单元由两个变三个(`knit_index` 起于 v0.22、`knit_semantic` 起于 v0.23);
10
15
  > 「**唯一的**写动作」那条从 v0.22 起就已经不成立,那次按实际改写,并补一条 ⚠️ 说明第二条写通道的守卫缺口
@@ -39,8 +44,11 @@ Knit 的安全属性其实一直成立 —— 但它们此前只散落在文档
39
44
  | 只允许 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
45
  | 会写盘的东西只有三类,且只写 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
46
  | 第二条写通道 `POST /knit/api/semantic` 的主机侧 e2e 守卫 | ⚠️ | **如实说明(v0.23 新增,尚未补)**:它目前只有**客户端侧**断言(`test/client.test.mjs` 认这条 URL),**没有**像 `/api/control` 那样在真实回环端口上验「GET→405 / 别的路由 POST→405 / 坏 body→400」。两条写路由在 `src/host/index.js` 里共用同一段前置守卫,但「共用同一段代码」**不等于**「被验过」 |
47
+ | **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、不读文件内容、不发网络请求** |
48
+ | **读工作区之外的唯一一处:对话里「工具产出」的图**(v0.25,`/knit/api/attachment`) | ✅ | 三条边界**都可机检**:① 只收 `sha256:<64 hex>`,**不接受任何路径**(`objectPath()` 由哈希算出路径 ⇒ 给不出穿越);② id 必须出现在**本会话的 `tool/result` 事件**里(`createAttachmentStore.has()`;跨会话 / 没出现过 / 用户自己贴的图一律 404);③ 只回 `image/*` `video/*`,走既有的 `sendMedia`。证据:`test/attachments.test.mjs` 的 6 条 e2e(真实回环端口 + 真的附件库形状)与 5 条突变证伪 —— 去掉去重 / 去掉会话 id 校验 / 去掉 `tool/result` 收窄 / 放宽类型 / 读不存在的对象,各自都会红 |
42
49
  | 响应带 `nosniff` 与 `default-src 'none'; sandbox` | ✅ | `test/host-http.test.mjs`(两个指令各自断言) |
43
- | 零网络出口:客户端 `fetch` 全部同源相对路径 | ✅ | `src/client/client.js` 的三个接口常量都是 `/knit/api/*`;`test/security.test.mjs` 断言无协议头。HTML 的「网页预览」按钮是把文件交给 **DSH 自己的**文档预览标签页去渲染(Knit 这一侧一个请求都不发),渲染的沙箱与 CSP 归 DSH 管 —— 所以这条承诺不变 |
50
+ | 客户端半边零网络出口:`src/client/client.js` 的全部 `fetch` 都是同源相对路径 | ✅ | `src/client/client.js` 的三个接口常量都是 `/knit/api/*`;`test/security.test.mjs` 断言无协议头。HTML 的「网页预览」按钮是把文件交给 **DSH 自己的**文档预览标签页去渲染(Knit 这一侧一个请求都不发),渲染的沙箱与 CSP 归 DSH 管 —— 所以这条承诺不变。⚠️ **这只覆盖浏览器半边**;宿主半边在**可选混合模式**下会出网,见下面那一条 |
51
+ | 宿主半边的出网只有一个点,且**默认一次都不发**:`src/host/semantic.js` 的 `createSemanticProvider()` | ⚠️ | **如实说明**:默认词法模式下**一次 provider 调用都不发**(`test/hybrid-retrieval.test.mjs` 判据 1 钉住,连探测都不发);只有「用户配好 provider **且**手动切到混合检索」才会走那条路。发出的是**查询原话 + 标题 + 摘要**,不含完整正文与绝对路径 —— 报文级实测在仓库根 tools/semantic-request-audit.mjs(**该脚本不随包发布**,所以这条目前是**人工跑的量尺**,不是 `npm test` 里的守卫) |
44
52
  | 宿主半边不 import `@deepseek-ai/*` | ✅ | `test/security.test.mjs` 扫三个宿主文件,注释里提到可以、真实 `import` 不行 |
45
53
  | `knit_docs` 工具只读,不写任何文件 | ✅ | `src/host/tool.js` 只调注入进来的 `scan` 与只读的 `readDocument`;无写文件调用 |
46
54
  | 未经第三方安全审计 | ⚠️ | **如实说明**:这张表是**自证**。没有外部审计报告,也没有自动化扫描评分 —— 它不等于「已证明安全」 |
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "dsh-knit",
3
- "version": "0.23.1",
3
+ "version": "0.25.0",
4
4
  "type": "module",
5
- "description": "Workspace context retrieval for DeepSeek Harness: ranks documents, source files and media by relevance to the current conversation into a sidebar Context Pack with inline preview. Lexical and fully local by default — zero model calls, zero network. Optional hybrid mode is off by default and needs a provider you configure; a remote provider receives file titles and summaries (not bodies). Loopback stays local.",
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 test/attachments.test.mjs"
28
28
  },
29
29
  "dsh": {
30
30
  "bundle": {