dsh-knit 0.12.1 → 0.13.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +268 -0
- package/README.en.md +47 -3
- package/README.md +44 -5
- package/package.json +1 -1
- package/src/client/client.js +343 -138
- package/test/client.test.mjs +267 -93
- package/test/harness.mjs +4 -2
- package/test/tier1.test.mjs +97 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,274 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
+
## [0.13.1] - 2026-09-23
|
|
7
|
+
|
|
8
|
+
**只改文档,插件行为一行没动。** 没有新功能、没有修 bug ——
|
|
9
|
+
**装过 `0.13.0` 的人没有任何必须升级的理由。**
|
|
10
|
+
|
|
11
|
+
那为什么还要发一版?因为 **npm 页面上渲染的 README 是「已发布 tarball 里的那一份」**。
|
|
12
|
+
`0.13.0` 之后我们往 README 里补了重排动图和两张真机截图,但那个包的 README 是**冻结**的 ——
|
|
13
|
+
不重新发一版,npm 那个页面就永远停在老版本:没有动图、没有反馈入口。
|
|
14
|
+
|
|
15
|
+
### 包内实际变化
|
|
16
|
+
|
|
17
|
+
只有两个文件(其余改动不在 `package.json` 的 `files` 白名单里,压根不进包):
|
|
18
|
+
|
|
19
|
+
| 文件 | 变化 |
|
|
20
|
+
|---|---|
|
|
21
|
+
| `README.md` / `README.en.md` | 第 1 屏接上**重排动图**;新增「反馈」与「升级」两节;补「图片与视频」「全部」两档真机截图;图注篇数 `34 → 36`;更正关于下载量的说法;修掉过期的测试数 |
|
|
22
|
+
| `CHANGELOG.md` | 本节 |
|
|
23
|
+
|
|
24
|
+
### 不进包的改动(在仓库里,但 `files` 没收录)
|
|
25
|
+
|
|
26
|
+
| 文件 | 说明 |
|
|
27
|
+
|---|---|
|
|
28
|
+
| `docs/demo-reorder.gif`(新增 1.3 MB) | README 用**绝对 raw URL** 引用,所以 npm 页面上照样显示 |
|
|
29
|
+
| `docs/screenshot-media.png` / `screenshot-all.png`(新增) | 同上 |
|
|
30
|
+
| `screenshots.json` | **1 张 → 3 张**(市场详情页的相册会自动跟着变,不用提 PR) |
|
|
31
|
+
| `tools/make-demo-gif.mjs`(新增) | 录屏 → GIF 的编码器,含 `--crop` |
|
|
32
|
+
| `tools/market-recheck.mjs`(新增) | 市场索引 + 下载量复查,含「形状判读」 |
|
|
33
|
+
|
|
34
|
+
### 顺带纠正一句我们自己说错的话
|
|
35
|
+
|
|
36
|
+
npm 的下载量**不是人**。决定性证据:`0.5.0` 只当了 **28 分 09 秒** `latest` 就被下载 **155** 次,
|
|
37
|
+
而 `0.13.0` 当了 **59.6 小时** 才 **161** 次 —— **曝光时长差 127 倍,下载量只差 1.04 倍**
|
|
38
|
+
(皮尔逊 r = 0.317;真实安装应当接近 +1)。`npm install` 只解析 `latest`,
|
|
39
|
+
**没有哪个真人渠道能造出这个形状**。版本分布也是平线:8 个版本几乎均分,
|
|
40
|
+
`latest` 占比只有 **14.4%**(对照真包 60–80%)。
|
|
41
|
+
|
|
42
|
+
⇒ README 里现在按这个口径写:**那个数字不能读成「这么多人在用」。**
|
|
43
|
+
|
|
44
|
+
## [0.13.0] - 2026-09-20
|
|
45
|
+
|
|
46
|
+
**三件事,都是真机体验打回来之后改的:**
|
|
47
|
+
|
|
48
|
+
1. **文档列表响应式**:默认 1 列,宽了**最多 2 列**,多列时字段一个不少
|
|
49
|
+
2. **预览面板底色恒为纯白**:删掉「先灰、滚一下才变白」那一整套机制
|
|
50
|
+
3. **媒体网格响应式重写**:列数交给 CSS `auto-fill` 连续数,纵向不封顶
|
|
51
|
+
|
|
52
|
+
外加多列的**键盘与无障碍修复**(P0):选项语义、`←→` 跨行导航、网格里可见光标。
|
|
53
|
+
|
|
54
|
+
### 一、文档列表响应式:默认 1 列,宽了最多 **2 列**,多列时字段一个不少
|
|
55
|
+
|
|
56
|
+
用户提议:「文档这块也可能要支持随着宽度的适应……默认是一个文档在一行,
|
|
57
|
+
随着宽度的增加可能要增加到最多 4 个」。这一节改了**三版**,前两版都被否掉,
|
|
58
|
+
第三版又把上限从 4 收到 3:
|
|
59
|
+
|
|
60
|
+
| 版本 | 做法 | 结果 |
|
|
61
|
+
|---|---|---|
|
|
62
|
+
| 一 | 把 1 列的卡直接压窄成多列 | ❌ 632px / 4 列时标题只剩 **9 个字**,一屏还是 4 篇,只是把信息切碎 |
|
|
63
|
+
| 二 | 多列只留**标题 + 时间** | ❌ 「两行保留一行一样的列表数据,现在大于一行后只有标题与时间了」 |
|
|
64
|
+
| 三 | 多列**保留全部字段**、只改排版 | ⚠️ 字段对了,但仍允许 4 列 |
|
|
65
|
+
| 四 | 上限收到 3 列 | ⚠️ 「大于三行视觉跳动信息过载了」 |
|
|
66
|
+
| 五(当前) | 上限再收到 **2 列** | ✅ 交互评审:3 列摘要每行只剩 **16 个汉字**,读不下去 |
|
|
67
|
+
|
|
68
|
+
**「4 列」被否掉的理由值得记**:4 列不是「更密=更高效」,而是**一屏塞太满**——
|
|
69
|
+
扫读时视线要在四个窄栏之间反复跳跃,还要同时读摘要与路径,反而比 3 列更难定位。
|
|
70
|
+
**密度有上限,超过就变成信息过载。**
|
|
71
|
+
|
|
72
|
+
**实测数据(真实标题样本,632px 面板)** —— 这是第一版被否掉的依据:
|
|
73
|
+
|
|
74
|
+
| 列数 | 格子宽 | 标题能显 | 摘要每行能显 | 一屏几篇 |
|
|
75
|
+
|---|---|---|---|---|
|
|
76
|
+
| 1 列 | 616px | 52 字 | 56 字 | 4 篇 |
|
|
77
|
+
| 2 列 | 303px | 24 字 | 26 字 | 8 篇 |
|
|
78
|
+
| 4 列(150px 下限那版) | 146px | **10 字** | 11 字 | 4 篇 |
|
|
79
|
+
|
|
80
|
+
真实标题中位数 **18 字**、最长 43 字(`Knit_PRD-v0.11-agent价值与信任`)。
|
|
81
|
+
|
|
82
|
+
**最终版的两条设计:**
|
|
83
|
+
|
|
84
|
+
1. **格子下限从 150px 提到 205px** —— 宁可列数少一点,也要让 2–3 列的摘要还有 16 个汉字。
|
|
85
|
+
断点因此变成:<420px 1 列 / ≥420px **2 列(封顶)**。
|
|
86
|
+
默认 632px 面板落在 2 列(格子 303px,摘要 **26 字/行**),**标题、时间、摘要、路径全在**。
|
|
87
|
+
2. **多列只改排版,不改数据**:时间从「和标题挤一行」改成纵向排、标题与路径折两行。
|
|
88
|
+
摘要按格子宽度决定去留(`docLayoutFor().summary`;窄于 185px 才让位,
|
|
89
|
+
当前配置下达不到,属兜底分支)—— 与媒体卡「窄到 96px 以下让位给缩略图」同一套渐进让位。
|
|
90
|
+
|
|
91
|
+
**为什么不按列数藏字段**:一多列就砍数据等于**用「看得更多」换「看不到内容」**。
|
|
92
|
+
用户的判断是对的 —— 宽面板应该同时得到「更多篇」与「不丢信息」。
|
|
93
|
+
|
|
94
|
+
**为什么最终停在 2 列**(这一版是交互评审的结论,不是试出来的):
|
|
95
|
+
文档列表的用户任务有三种 —— ①按名字找一篇 ②**读摘要判断哪篇有用** ③看最近改了什么。
|
|
96
|
+
多列只对 ①③ 有微弱帮助,对 ② 没有:读文字的成本由「每行字数 + 换行次数」决定,
|
|
97
|
+
**不由「一屏几个卡片」决定**。实测每行可容纳的汉字数:
|
|
98
|
+
|
|
99
|
+
| 列数 | 格子宽 | 摘要每行 | 判断 |
|
|
100
|
+
|---|---|---|---|
|
|
101
|
+
| 1 列 | 616px | **56 字** | 大多摘要一屏读完 |
|
|
102
|
+
| 2 列 | 303px | **26 字** | 仍可读,一屏 8 篇 ✅ |
|
|
103
|
+
| 3 列 | 198px | **16 字** | 摘要碎成片段,读到「本文件是 Agent 进」就断了 ❌ |
|
|
104
|
+
| 4 列 | 146px | 11 字 | 标题都只剩 10 字 ❌ |
|
|
105
|
+
|
|
106
|
+
所以 2 列是**摘要仍然可读的上限**;再宽的收益只有「多一篇」,代价是每篇都读不下去。
|
|
107
|
+
|
|
108
|
+
⚠️ **别再加回 3 列**:真要提升宽面板的信息利用率,该做的是**让单列更舒展**
|
|
109
|
+
(时间/路径移到右侧同一基线、摘要可读宽度拉满),不是继续切栏。
|
|
110
|
+
|
|
111
|
+
### 关于「最多两行」
|
|
112
|
+
|
|
113
|
+
用户说「修改成最多两行」。这句有两种读法,我按 **B** 实现,并在此标出:
|
|
114
|
+
|
|
115
|
+
- **A:网格最多铺两行**(第 8 篇之后内部滚动)—— ❌ **没做**,因为那会重演媒体那次的坑:
|
|
116
|
+
按「两行」算死高度、后面的条目被截断或挤进嵌套滚动。
|
|
117
|
+
- **B:卡片最多折两行**(标题 2 行、路径 2 行、摘要本来就 2 行),行数不设上限、
|
|
118
|
+
由列表滚动 —— ✅ **做了**,与媒体「纵向铺满、不封顶」保持一致。
|
|
119
|
+
|
|
120
|
+
⚠️ 另记两个坑:
|
|
121
|
+
- **容器类名不能含 `knit-doc`**:第一版叫 `knit-doc-grid`,而 `byClass` 是**子串**匹配 ——
|
|
122
|
+
它把容器当成一个文档行,34 条测试当场红(§6.5 那个坑的第三次)。
|
|
123
|
+
改名 `knit-multicol`,**改的是命名不是测试**。
|
|
124
|
+
- **列数类只加在文档容器上**,不能加在 `.knit-list` 上 —— 那是唯一的滚动容器,
|
|
125
|
+
媒体档与「全部」都在它里面。
|
|
126
|
+
- **`cols-4` 的 CSS 已随上限一起删掉**:留着就是不可达的死代码,而且会让人以为 4 列还开着。
|
|
127
|
+
有条守卫盯着这件事(`docLayoutFor` 的上限 == 3 且 CSS 里不许出现 `cols-4`)。
|
|
128
|
+
|
|
129
|
+
### 一点五、多列的键盘与无障碍(P0 修复)
|
|
130
|
+
|
|
131
|
+
多列改造**引入了一个真实回归**,不是历史问题:列表的键盘模型还是「单列一条线」。
|
|
132
|
+
|
|
133
|
+
| 缺陷 | 事实 | 修法 |
|
|
134
|
+
|---|---|---|
|
|
135
|
+
| **选项无语义** | 容器是 `role="listbox"`,但条目是裸 `div` —— 读屏只能播报「一个列表框」,读不出「N 项中的第 i 项」,也读不出当前选中 | 每个条目加 `role="option"` + 稳定 `id`,容器加 `aria-activedescendant`;光标项 = 被指向的那一项,预览项 `aria-selected="true"` |
|
|
136
|
+
| **多列无 ←→** | 2 列网格里按 `↓` 视觉上**往右**走,而 `←→` 完全不响应 —— 看到的是两列,键盘只有一条线 | 抽出纯函数 `nextIndexFor(index, key, count, columns)`:`↑↓` 走相邻项、`←→` **跨一整行**(行首/行尾停住**不回绕**,回绕会让方向感更差)、`Home`/`End` 到首尾。**只在多列时接管 ←→**(单列拦它反而会挡掉宿主) |
|
|
137
|
+
| **网格里光标不可见** | 单列时靠 `:hover` 的 translateX 提供位置反馈,而网格里这条位移被关掉了(会给整格带来抖动)—— 键盘用户因此完全失去「我在哪」的线索 | 多列时给 `.knit-doc.cursor` 一圈**中性**描边环(与媒体卡光标同一套,不是品牌色,与 `.active` 区分) |
|
|
138
|
+
|
|
139
|
+
⚠️ 两个实现要点:
|
|
140
|
+
|
|
141
|
+
- **`id` 必须由 `rel` 哈希稳定推导,不能用计数器** —— `aria-activedescendant` 要指向真实存在的 id,
|
|
142
|
+
而渲染期自增的 id 会在不同帧漂移(渲染顺序、过滤、轮询刷新都会变)。
|
|
143
|
+
- **网格容器改 `role="presentation"`**(原来是 `group`):`option` 要是 `listbox` 的直接子级,
|
|
144
|
+
辅助技术才会把选项算进那个集合。
|
|
145
|
+
- 导航算术抽成纯函数是**为了可测**:真实列数靠 `ResizeObserver` 量,测试环境量不到、永远是 1 列 ——
|
|
146
|
+
不抽出来,多列分支就永远跑不到,又是一盏空转的绿灯(§6.12)。
|
|
147
|
+
|
|
148
|
+
### 二、预览面板:灰底 → 恒为纯阅读底色
|
|
149
|
+
|
|
150
|
+
用户原话:「文档选中后下拉出现详情时,背景是灰的,这个交互比较差……把它改成整个都是白」。
|
|
151
|
+
|
|
152
|
+
v0.10 起的行为是「先分层灰,用户一滚正文(> 4px)才**过渡**到纯白」。现在**一展开就是白的**,
|
|
153
|
+
而且**滚动、换篇都不会改变底色**。改的是根,不是参数:
|
|
154
|
+
|
|
155
|
+
- `.knit-preview` 的 `background` 从 `bg-module-platform`(浅 `#f5f6f7`)换成
|
|
156
|
+
**`bg-base`(浅 `#fff` / 深 `#151517`)**,`transition:background-color` 一并去掉
|
|
157
|
+
- 删掉 `.knit-preview.reading` 这条规则,以及**整套驱动它的机制**:
|
|
158
|
+
`READING_SCROLL_PX` 常量、模块级 `readingDocs` 集合、`readingTick` 状态、
|
|
159
|
+
正文的 `onScroll` 回调、`PreviewPanel` 的 `reading` / `onScrollBody` 两个 prop
|
|
160
|
+
- `readingKey()` 改名 `previewKey()` —— 它现在的使用者只剩引用条的展开态(`expandedLinks`)
|
|
161
|
+
|
|
162
|
+
⚠️ **别只写 `#fff`**:暗色主题下会白得刺眼。要走 `bg-base` 让两边都跟着主题走。
|
|
163
|
+
|
|
164
|
+
⚠️ **分层现在不靠底色了**:靠顶部圆角 + 上边界 + 向上柔影(三件都还在,没动)。
|
|
165
|
+
旧实现是靠「换一个明暗都不同的表面令牌」做层级,这条路现在废弃了 ——
|
|
166
|
+
留着记一笔是因为**「分层未必要靠底色」**才是那条经验的正文。
|
|
167
|
+
|
|
168
|
+
### 三、媒体网格的响应式重写 —— 花了三次才对,三次都是用户看出来的
|
|
169
|
+
|
|
170
|
+
起因是用户对着右边栏的「AIGC 资产中心」插件说:「它的图片这一块随着宽度伸缩,
|
|
171
|
+
适应得非常好」。对比之后确认,差的不是宽度监听,而是**列数由谁决定**。
|
|
172
|
+
|
|
173
|
+
三次修正对应三张真机截图,病灶一次比一次隐蔽:
|
|
174
|
+
|
|
175
|
+
| 第几次 | 病灶 | 用户原话 |
|
|
176
|
+
|---|---|---|
|
|
177
|
+
| 一 | JS 按**条目个数**反推列数(`Math.ceil(n/2)`,最多 8 列) | 参照 AIGC 的对比提出 |
|
|
178
|
+
| 二 | 改成「按条目数反算格宽」——**列数仍被条目数锁死** | 「要我拉到一定的宽度以后,它才从 4 个变成更多」「它不是真的响应式」 |
|
|
179
|
+
| 三 | 给网格设 `maxHeight` 封「两行」并让它自己滚 —— **第三行只露一点点** | 「本来有三行,结果第三行只显示了一点点,应该纵向也完整显示」 |
|
|
180
|
+
|
|
181
|
+
### 第一版(同一天上午,错的)
|
|
182
|
+
|
|
183
|
+
把「JS 按条目个数反推列数」改成「JS 按可用宽度和条目数算格子宽度 + CSS auto-fill」。
|
|
184
|
+
320px 下 5 列 48px 的病治好了,但**列数仍然被条目数锁死**:
|
|
185
|
+
|
|
186
|
+
| 面板宽 | v0.12.1 | 第一版(错) | 最终版 |
|
|
187
|
+
|---|---|---|---|
|
|
188
|
+
| 320px | 5 列 / 48px | 3 列 / 86px | **2 列 / 135px** |
|
|
189
|
+
| 420px | 5 列 / 68px | 5 列 / 68px | **3 列 / 120px** |
|
|
190
|
+
| 632px(默认) | 5 列 / 110px | 5 列 / 110px | **5 列 / 110px** |
|
|
191
|
+
| **700px** | 5 列 / 124px | 5 列 / 124px | **5 列 / 124px** |
|
|
192
|
+
| **900px** | 5 列 / 164px | 5 列 / 164px | **7 列 / 114px** |
|
|
193
|
+
| **1100px** | 5 列 / 207px | 5 列 / 204px | **9 列 / 108px** |
|
|
194
|
+
| **1400px** | 5 列 / 207px | 6 列 / 218px | **12 列 / 104px** |
|
|
195
|
+
|
|
196
|
+
(最终版那几列是实测读数:JS 报的列数与浏览器 `grid-template-columns` 的轨道数一致。)
|
|
197
|
+
|
|
198
|
+
用户的反馈:「**要我拉到一定的宽度以后,它才从 4 个变成更多**」
|
|
199
|
+
「它响应非常的快……就是它是真的是以这种响应式适应列表一样」
|
|
200
|
+
「**它不是真的响应式**」。实测确认:第一版从 **400px 到 1200px 列数一直卡在 5 列**,
|
|
201
|
+
只有格子从 64px 被吹到 224px。
|
|
202
|
+
|
|
203
|
+
### 最终版:只钉一个数,`count` 不许进函数,纵向不封顶
|
|
204
|
+
|
|
205
|
+
```css
|
|
206
|
+
grid-template-columns:repeat(auto-fill,minmax(var(--knit-media-track,104px),1fr));
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
- **格子基准固定 104px**,与条目数**完全无关**(实测渲染 104–155px)
|
|
210
|
+
- 列数 = 浏览器按可用宽度连续数出来的,**拖宽约 120px 就多一列**,没有平台期
|
|
211
|
+
- JS 侧 `mediaLayoutFor(width)` **只接受 width 一个参数** —— 签名里没有 `count`,
|
|
212
|
+
是横向那条唯一的结构性保证(测试里有源码级守卫盯着调用处)
|
|
213
|
+
- **纵向有多少行就铺多少行** —— 网格**不设 maxHeight、也不自己滚**,
|
|
214
|
+
滚动统一交给 `.knit-list`(第三版修正,见下)
|
|
215
|
+
|
|
216
|
+
### 第三版:把「两行封顶」整个删掉
|
|
217
|
+
|
|
218
|
+
前两版都给网格设了 `maxHeight`(按「两行」算死)+ `overflow-y:auto`,让它内部滚动。
|
|
219
|
+
真机上第三行只露出一点点 —— 用户发来截图:「本来有三行,结果第三行只显示了一点点,
|
|
220
|
+
应该纵向也完整显示」。
|
|
221
|
+
|
|
222
|
+
根因:**封顶高度是按「两行」算死的,与面板实际有多高无关**,媒体超过两行就必然截断;
|
|
223
|
+
而且「网格自己滚」在「全部」里还会与外层列表叠成嵌套滚动。
|
|
224
|
+
|
|
225
|
+
修法是**删掉这个机制本身**,而不是调参数:
|
|
226
|
+
|
|
227
|
+
- `MEDIA_ROWS` 常量删除,布局函数不再返回 `maxHeight`
|
|
228
|
+
- `.knit-media-grid` 去掉 `overflow-y:auto`(现在只有 `.knit-list` 滚)
|
|
229
|
+
- 渲染处不再写行内 `maxHeight`
|
|
230
|
+
|
|
231
|
+
与 AIGC 资产中心一致:它那边也是整页滚,网格自己不滚。
|
|
232
|
+
|
|
233
|
+
### 三个实测踩出来的坑(都写进了注释)
|
|
234
|
+
|
|
235
|
+
1. **轨道下限 104px 与 `1fr` 都不能省**:只写 `1fr` → 只有一个媒体时那张图撑满面板宽度;
|
|
236
|
+
只写固定宽 → 面板宽了留白、格子不跟着走。
|
|
237
|
+
2. **JS 的列数算术必须含 gap**:`floor((可用宽 + gap) / (104 + gap))`,不是 `floor(可用宽 / 104)`;
|
|
238
|
+
少算 gap 会让 JS 与真机差一列。
|
|
239
|
+
3. **CSS 注释里不能出现反引号**:那段样式是模板字符串,一个反引号就会把它提前截断 ——
|
|
240
|
+
这次**踩了两次**(第二次是给 `.knit-list` 加引号),`node --check` 报的是
|
|
241
|
+
`Unexpected identifier 'minmax'`(见 AGENTS §6.9)。
|
|
242
|
+
|
|
243
|
+
### 测试(280 → 282)
|
|
244
|
+
|
|
245
|
+
`mediaLayoutFor` 的断言整段重写。旧断言守着「最少 3 列 / 一屏 8 个 / 超过等比缩小」,
|
|
246
|
+
那是**旧算法的规则本身**,必须跟着改。新断言守五件事:
|
|
247
|
+
|
|
248
|
+
1. **列数只与宽度有关,与条目数无关** —— 传 120 个条目进去,结果必须与不传一样
|
|
249
|
+
2. **没有平台期**:每加 120px 宽度**至少多一列**(这条正是第一版会红的)
|
|
250
|
+
3. JS 报的列数与 CSS 的 `auto-fill` 判定**逐字一致**(含 gap)
|
|
251
|
+
4. **调用处不许传第二个参数** —— 源码级守卫:剥掉注释后扫每个
|
|
252
|
+
`mediaLayoutFor(...)` 的参数表,出现顶层逗号就红
|
|
253
|
+
5. **纵向不许封顶**(第三版)—— 布局函数连 `maxHeight` 这个键都不该有;
|
|
254
|
+
网格的 CSS 规则里不许出现 `overflow-y` / `max-height`;渲染处不许读 `mediaLayout.maxHeight`
|
|
255
|
+
|
|
256
|
+
### 怎么验的
|
|
257
|
+
|
|
258
|
+
- **横向**:无头 Chromium 加载**从产品源码抽出的真实 CSS**,17 个面板宽实测:
|
|
259
|
+
JS 列数 == 浏览器列数、格子方正(±2px)、宽度 ≥ 96px、行高一致、列数单调不减 ——
|
|
260
|
+
**全部通过**
|
|
261
|
+
- **纵向**:同法测 6 组(含 320px / 6 个 = 3 行这种原病灶场景)——
|
|
262
|
+
行数铺满、网格 `overflowY` 为 visible、`maxHeight` 为 none、
|
|
263
|
+
**最后一行完整**(末行底边不超过网格底边)—— **全部通过**
|
|
264
|
+
- 真机(DSH 右边栏)拖动宽度时列数跟随,详见 `03_发布/` 的验收记录
|
|
265
|
+
|
|
266
|
+
> 教训 1:**只要「条目数」还能影响格宽,列数就一定会被锁死。**
|
|
267
|
+
> 前两版在同一个地方栽跟头,区别只是第一版锁得狠(`Math.ceil(n/2)`)、
|
|
268
|
+
> 第二版锁得隐蔽(64px 下限把 raw 列数顶满)。**根治办法是把 `count` 从函数签名里拿掉。**
|
|
269
|
+
>
|
|
270
|
+
> 教训 2:**别用「算出来的高度」去封一块内容的高度。** 算的是「两行」,
|
|
271
|
+
> 装的是「三行」,差的那一行就是用户看到的那一点点。要么完全不封,
|
|
272
|
+
> 要么按**实际可视高度**封(那需要真的量容器)—— 前者是对的。
|
|
273
|
+
|
|
6
274
|
## [0.12.1] - 2026-09-19
|
|
7
275
|
|
|
8
276
|
**一张真机截图抓出来的修复版。** 没有新功能,两件事:把三处**硬编码中文**收进词典,
|
package/README.en.md
CHANGED
|
@@ -7,13 +7,21 @@
|
|
|
7
7
|
|
|
8
8
|

|
|
9
9
|
|
|
10
|
-
*Screenshot from a real machine, not a mock-up: a workspace with
|
|
10
|
+
*Screenshot from a real machine, not a mock-up: a workspace with 36 documents — the list, an inline
|
|
11
11
|
preview, and the references bar.*
|
|
12
12
|
*The references bar is new in v0.12: expand it to see which documents reference this one, and click
|
|
13
13
|
one to jump straight there.*
|
|
14
14
|
*The top line follows whatever you're talking about; when there isn't enough conversation yet it
|
|
15
15
|
falls back to newest-first and states its basis.*
|
|
16
16
|
|
|
17
|
+

|
|
18
|
+
|
|
19
|
+
*Order follows the conversation — same workspace, same session: ask "how is BM25 weighted for the
|
|
20
|
+
ranking?" and the sorting docs move to the top; then ask "how do I check plugin-market listings and
|
|
21
|
+
download counts?" and the market-research docs take over.*
|
|
22
|
+
*⚠️ The panel polls **every 5 seconds**, so the re-rank lands **0–5 s** after the message rather than
|
|
23
|
+
instantly, and the GIF runs faster than real time.*
|
|
24
|
+
|
|
17
25
|
Scans Markdown / images / video across the project folder · Order follows the conversation · No model calls, no network
|
|
18
26
|
|
|
19
27
|
```sh
|
|
@@ -172,6 +180,27 @@ Then **restart DSH** and hard-refresh the browser (`Cmd + Shift + R`).
|
|
|
172
180
|
**Optional**: if `dsh-better-sidebar` is installed, the panel also registers
|
|
173
181
|
as one of its tabs. Each host is an independent optional dependency; missing one doesn't affect the other.
|
|
174
182
|
|
|
183
|
+
**Upgrading**: same command as installing, and the same restart + hard-refresh afterwards.
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## Feedback
|
|
188
|
+
|
|
189
|
+
**Right now this project is not about adding features — it's about finding out whether
|
|
190
|
+
"rank project docs by the current conversation" is something anyone actually uses.**
|
|
191
|
+
So the most valuable thing you can send is not "could you add X" but **how you work around
|
|
192
|
+
this today** — including "I installed it and never opened it", which is more useful than a
|
|
193
|
+
feature request.
|
|
194
|
+
|
|
195
|
+
- 💬 [Tell us when you actually open it](https://github.com/PolinniZhong/dsh-knit/issues/new?template=feature.yml) — two fields, thirty seconds
|
|
196
|
+
- 🐞 [Won't install / panel won't open / ranking looks wrong](https://github.com/PolinniZhong/dsh-knit/issues/new?template=bug.yml)
|
|
197
|
+
- 📖 Check [known limitations](#known-limitations) first — short conversations degrade to time order and Chinese uses n-gram approximation; those are deliberate trade-offs, not bugs
|
|
198
|
+
|
|
199
|
+
> A single issue is treated as a real signal. So far this plugin has **no trace of a single
|
|
200
|
+
> real user** — the npm download count is automated version enumeration, not people
|
|
201
|
+
> (only 14% of it is `latest`, and a human install only ever pulls `latest`). One human reply
|
|
202
|
+
> changes what gets built next.
|
|
203
|
+
|
|
175
204
|
---
|
|
176
205
|
|
|
177
206
|
## Features
|
|
@@ -204,6 +233,21 @@ as one of its tabs. Each host is an independent optional dependency; missing one
|
|
|
204
233
|
> Relevance is deliberately **not visualised** (no percentages, no bars) — the ranking itself is
|
|
205
234
|
> the answer; position is relevance.
|
|
206
235
|
|
|
236
|
+
### The other two views
|
|
237
|
+
|
|
238
|
+

|
|
239
|
+
|
|
240
|
+
*Images & video: square thumbnails, with the **column count following the panel width continuously** —
|
|
241
|
+
six columns at this width, cells about 112px. Videos show their first frame as a poster with a play
|
|
242
|
+
glyph and a duration badge. These are the workspace's real image and SVG files; this particular
|
|
243
|
+
workspace happens to hold several screenshots and two icon files.*
|
|
244
|
+
|
|
245
|
+

|
|
246
|
+
|
|
247
|
+
*All: documents on top (max 4, with a "View all →" link when truncated) and images & video below
|
|
248
|
+
(**never truncated**, count only). Documents lay out in **two columns** here, and all four fields —
|
|
249
|
+
title, time, summary, path — are still present: column count changes the layout, never the data.*
|
|
250
|
+
|
|
207
251
|
---
|
|
208
252
|
|
|
209
253
|
## What it reads, and what it doesn't
|
|
@@ -254,7 +298,7 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
254
298
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
255
299
|
cd dsh-knit
|
|
256
300
|
|
|
257
|
-
npm test #
|
|
301
|
+
npm test # 285 tests, zero dependencies, no npm install needed
|
|
258
302
|
```
|
|
259
303
|
|
|
260
304
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -274,7 +318,7 @@ knit/
|
|
|
274
318
|
│ ├── host/index.js # /knit/api/recent · /doc · /raw
|
|
275
319
|
│ ├── host/relevance.js # the relevance engine: BM25 + keyword extraction
|
|
276
320
|
│ └── client/client.js # dual-host registration + panel UI
|
|
277
|
-
└── test/ #
|
|
321
|
+
└── test/ # 285 tests
|
|
278
322
|
```
|
|
279
323
|
|
|
280
324
|
Details and trade-offs live in the source comments; see [CONTRIBUTING.md](CONTRIBUTING.md)
|
package/README.md
CHANGED
|
@@ -7,10 +7,16 @@
|
|
|
7
7
|
|
|
8
8
|

|
|
9
9
|
|
|
10
|
-
*真机截图(不是原型):一个含
|
|
10
|
+
*真机截图(不是原型):一个含 36 篇文档的工作区 —— 列表 + 就地预览 + 引用条。*
|
|
11
11
|
*引用条是 v0.12 加的:展开就能看到「这篇被谁引用」,点一项直接跳过去。*
|
|
12
12
|
*顶行会跟着你正在聊什么变;对话内容还不足时它退回按时间排,并如实说明依据。*
|
|
13
13
|
|
|
14
|
+

|
|
15
|
+
|
|
16
|
+
*排序跟着对话走(同一个工作区、同一个会话):先问「排序算法用的 BM25 是怎么加权的?」,*
|
|
17
|
+
*顶上换成排序那几篇;再问「插件市场收录和下载量怎么查?」,顶上又换成市场调研那几篇。*
|
|
18
|
+
*⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
|
|
19
|
+
|
|
14
20
|
扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
|
|
15
21
|
|
|
16
22
|
```sh
|
|
@@ -125,6 +131,24 @@ dsh plugin --profile web add dsh-knit
|
|
|
125
131
|
**可选**:装了 `dsh-better-sidebar` 的话,面板也会注册成它的一个 tab;
|
|
126
132
|
没装不受影响,两边是各自独立的可选依赖。
|
|
127
133
|
|
|
134
|
+
**升级**:命令和首次安装是同一条,装完同样要**重启 DSH** + 硬刷新。
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## 反馈
|
|
139
|
+
|
|
140
|
+
**这个项目当前的重心不是加功能,是搞清楚「按对话给文档排序」这件事到底有没有人在用。**
|
|
141
|
+
所以最有价值的一句话不是「能不能加个 XX」,而是**你现在是怎么绕过它的** ——
|
|
142
|
+
哪怕结论是「装了,但一周没打开过」,也请直说,那比一个功能建议有用得多。
|
|
143
|
+
|
|
144
|
+
- 💬 [说说你在什么场景下会打开它](https://github.com/PolinniZhong/dsh-knit/issues/new?template=feature.yml) —— 两步、三十秒,不必客气
|
|
145
|
+
- 🐞 [装不上 / 面板打不开 / 排得不对](https://github.com/PolinniZhong/dsh-knit/issues/new?template=bug.yml)
|
|
146
|
+
- 📖 提之前先看一眼[已知限制](#已知限制) —— 短对话退化、中文用 n-gram 近似,这几条是已知的取舍,不是 bug
|
|
147
|
+
|
|
148
|
+
> 一条 issue 会被当成真实信号处理。这个插件到现在**一个真实用户的痕迹都没有**
|
|
149
|
+
> (npm 那个下载量是自动化版本枚举、不是人 —— `latest` 占比只有 14%,而真人只会装 `latest`)
|
|
150
|
+
> —— 一条有人味儿的反馈能直接改变接下来做什么。
|
|
151
|
+
|
|
128
152
|
---
|
|
129
153
|
|
|
130
154
|
## 功能
|
|
@@ -136,10 +160,11 @@ dsh plugin --profile web add dsh-knit
|
|
|
136
160
|
| 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
|
|
137
161
|
| 扫描会话工作区里的 `.md`(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist`) | ✅ |
|
|
138
162
|
| 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
|
|
163
|
+
| 面板拖宽后文档列表**自动排成 2 列**(<420px 保持 1 列);**多列时字段一个不少**,只是排版改成纵向、标题与路径折两行 | ✅ |
|
|
139
164
|
| 单击就地展开预览,再点收起 | ✅ |
|
|
140
165
|
| 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
|
|
141
166
|
| **文档 / 图片与视频 / 全部** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边 | ✅ |
|
|
142
|
-
|
|
|
167
|
+
| 图片与视频:方形缩略图网格,**格子基准固定 104px、列数由宽度连续数出来**(320px → 2 列 / 632px → 5 列 / 1200px → 10 列),格子大小基本不变;**纵向有多少行就铺多少行**,超出交给列表滚动;视频自动取首帧、叠播放三角与时长角标(零依赖、不转码) | ✅ |
|
|
143
168
|
| 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
|
|
144
169
|
| 「全部」视图**分上下两区**:文档最多 4 条(超出给「查看全部 →」);图片视频**不截断**,只给计数 | ✅ |
|
|
145
170
|
| 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出 | ✅ |
|
|
@@ -148,13 +173,27 @@ dsh plugin --profile web add dsh-knit
|
|
|
148
173
|
| 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
|
|
149
174
|
| **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
|
|
150
175
|
| **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局) | ✅ |
|
|
151
|
-
| 键盘导航:`↑` `↓` 移动即预览 / `Enter` 切换 / `Esc`
|
|
176
|
+
| 键盘导航:`↑` `↓` 移动即预览 / `Enter` 切换 / `Esc` 收起;多列时 `←` `→` 按屏幕位置跨行,`Home` / `End` 到首尾 | ✅ |
|
|
152
177
|
| 每 5 秒自动刷新 + 手动刷新;2 分钟内改动过的文档打 🆕 | ✅ |
|
|
153
178
|
| 中英双语,跟随 DSH 语言实时切换(不用重载插件) | ✅ |
|
|
179
|
+
| 列表是标准 `listbox`/`option` 语义,选中项用 `aria-activedescendant` 播报;多列时键盘焦点有可见描边 | ✅ |
|
|
154
180
|
| 零模型调用、零网络出口 | ✅ |
|
|
155
181
|
|
|
156
182
|
> 相关度**不做可视化**(不显示百分比、不画长条)—— 排序本身就是答案,名次即相关度。
|
|
157
183
|
|
|
184
|
+
### 另外两档长什么样
|
|
185
|
+
|
|
186
|
+

|
|
187
|
+
|
|
188
|
+
*图片与视频:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 112px。*
|
|
189
|
+
*视频取首帧当海报,中央叠播放三角、右下角叠时长。列出的就是工作区里真实的图片与 SVG 文件 ——*
|
|
190
|
+
*这个工作区里正好有几张截图和两个图标,所以看起来像一屏文件缩略图。*
|
|
191
|
+
|
|
192
|
+

|
|
193
|
+
|
|
194
|
+
*全部:上区文档(最多 4 条,超出时右侧给「查看全部 →」)、下区图片与视频(**不截断**,只给计数)。*
|
|
195
|
+
*文档在这一档排成 **2 列**,标题 / 时间 / 摘要 / 路径**四个字段一个不少** —— 列数只改排版,不砍数据。*
|
|
196
|
+
|
|
158
197
|
---
|
|
159
198
|
|
|
160
199
|
## 也给 agent 用:`knit_docs` 工具
|
|
@@ -229,7 +268,7 @@ Knit 一装上就有整个项目的历史文档可用。
|
|
|
229
268
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
230
269
|
cd dsh-knit
|
|
231
270
|
|
|
232
|
-
npm test #
|
|
271
|
+
npm test # 285 项,零依赖,不需要先 npm install
|
|
233
272
|
```
|
|
234
273
|
|
|
235
274
|
**改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
|
|
@@ -250,7 +289,7 @@ knit/
|
|
|
250
289
|
│ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
|
|
251
290
|
│ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
|
|
252
291
|
│ └── client/client.js # 双宿主注册 + 面板 UI
|
|
253
|
-
└── test/ #
|
|
292
|
+
└── test/ # 285 项测试
|
|
254
293
|
└── eval/ # 离线质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
|
|
255
294
|
```
|
|
256
295
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-knit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Find the doc your agent just wrote. Lists the DSH workspace's Markdown, images and video in the sidebar, ranked by relevance to the current conversation, with inline preview — and hands the same ranking to the agent as a tool, returning the passage that matched in each document. Zero model calls, zero network.",
|
|
6
6
|
"main": "./src/host/index.js",
|