dsh-knit
查找你的代理刚刚编写的文档。在侧边栏中列出 DSH 工作区的 Markdown、图像和视频，并根据与当前对话的相关性排序，同时提供内联预览——还会将相同的排序作为工具提供给代理，返回每个文档中匹配的段落。零模型调用，零网络请求，零
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-knit@0.12.1查找你的代理刚刚编写的文档。在侧边栏中列出 DSH 工作区的 Markdown、图像和视频，并根据与当前对话的相关性排序，同时提供内联预览——还会将相同的排序作为工具提供给代理，返回每个文档中匹配的段落。零模型调用，零网络请求。
Knit 以 dsh-knit 发布，当前版本为 0.12.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Agent 一天产出 20 篇文档，你找不到刚才那篇。 Knit 把它们放到对话旁边 —— 你正在聊什么，相关的那篇就在最上面。
你的 agent 也一样。 同一份排序也给它当工具用 —— 它问「哪几篇相关」，拿回排名加每篇里命中的那段原文。
Knit 面板真机截图：右侧栏按相关性列出工作区文档，就地展开 Markdown 预览，预览头下方是引用条
真机截图（不是原型）：一个含 34 篇文档的工作区 —— 列表 + 就地预览 + 引用条。 引用条是 v0.12 加的：展开就能看到「这篇被谁引用」，点一项直接跳过去。 顶行会跟着你正在聊什么变；对话内容还不足时它退回按时间排，并如实说明依据。
扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
dsh plugin --profile web add dsh-knit
是的，但有两个关键区别：
三句话说完它是什么：
没有玄学，就是字符串运算。三步：
1. 读当前会话。 取最近 6 条用户 / 助手消息，只认真人输入的用户消息
（agent.inject() 塞进来的合成上下文不算，那会把话题带偏）。越新的消息权重越高：3 / 2 / 1 / 1 …
2. 抽关键词。
chokidar、mtime 这种精确词）3. 给文档打分 —— BM25。
每个词先算 IDF：在语料里越罕见越值钱 ln(1 + (N - df + 0.5) / (df + 0.5))
再按字段加权求和：标题 ×4 + 摘要 ×2 + 正文前 2500 字 ×1
每个字段都按 BM25 饱和 + 长度归一化（k1 = 1.2，b = 0.3 / 0.5 / 0.75）
再叠 10% 的时间新鲜度微调（主排序仍是相关性）
为什么是 BM25 而不是「命中次数 × 权重」（那是最初的做法，已换掉）：
k1 / b 才是为这件事设计的实测（test/eval/fixture.mjs，21 个用例，两版引擎跑同一套语料）：
| top-1 命中 | MRR | |
|---|---|---|
| 旧做法（加权命中） | 76.2% | 0.830 |
| BM25 | 95.2% | 0.976 |
这套评测在 npm test 里跑，基线由 test/eval/legacy.mjs 冻结的旧引擎现算，
所以「新引擎必须显著更好」是自动验证的，而不是引用一个写死的数字。
跟「自己数关键词」比（knit/tools/scale-benchmark.mjs，N = 20/60/180/540）：
语料刻意做成有真实陷阱的 —— 12 篇短而聚焦的主题文档，加上一堆「每条主题各提 5 次、
但哪一件都没讲」的长干扰文档（真实项目里的 CHANGELOG 就长这样）。
主题文档一半用描述性文件名，一半看不出内容。
| 路线 | 文件名说得清 | 文件名看不出 | MRR 随规模 |
|---|---|---|---|
| Knit（BM25） | 100% | 100% | 1.000（不随规模变） |
自己 grep -c 数关键词 | 17% | 0% | 0.313 → 0.089 |
| 只看文件名 | 100% | 0% | 0.602 |
三件事：排序强于自己数关键词（所以让 agent 重算是不理性的）； 文件名匹配只在名字描述内容时好使，Knit 是唯一两种都 100% 的； 自己数的可靠性随规模单调下降。
关于那行「按「xxx」排序」：显示的是命中词在原文里覆盖的那一段，不是词表里的碎片。
中文没有词边界，候选里必然有跨词的碎片（「项目文档」会切出 项目文 / 目文档），
直接显示就成了乱码 —— 把它们的区间合并再切原文，正好还原出 项目文档。
标签是你自己打的字，所以大小写原样保留（打 BM25 就显示 BM25）。
全是字符串运算 —— 没有 embedding，没有模型调用。
并且老实说边界：
df 的取值范围太窄，动态范围被压扁。
文档越多这个排序越准 —— 这正是它该有的样子dsh plugin --profile web add dsh-knit
装完重启 DSH，然后硬刷新浏览器（Cmd + Shift + R）。
怎么打开：
可选：装了 dsh-better-sidebar 的话，面板也会注册成它的一个 tab；
没装不受影响，两边是各自独立的可选依赖。
| 能力 | |
|---|---|
| 按当前对话相关性排序（BM25 + IDF，纯本地，零模型） | ✅ |
给 agent 用的 knit_docs 工具：让模型自己查「这个项目里跟当前话题最相关的文档」 | ✅ |
| 相关性 / 修改时间双模式一键切换（偏好记在 localStorage） | ✅ |
扫描会话工作区里的 .md（递归，深度 ≤ 6，跳过 node_modules / .git / dist） | ✅ |
| 每项显示：H1 标题（无则文件名）+ 相对时间 + 首段摘要 | ✅ |
| 单击就地展开预览，再点收起 | ✅ |
相对路径图片真正渲染（./img/a.png、../assets/b.png） | ✅ |
| 文档 / 图片与视频 / 全部 三类一键切换（偏好记住，默认仍是文档，老体验不变）；选中态是中性灰填充，不带品牌色描边 | ✅ |
| 图片与视频：方形缩略图网格，最少 3 列、宽了才加列；格子 64px 起步，一屏基准 8 个，超过 8 个不隐藏而是整块等比缩小；视频自动取首帧、叠播放三角与时长角标（零依赖、不转码） | ✅ |
| 点图片 / 视频在面板内就地预览：图片大图、视频可播放可拖动（HTTP Range 流式，不全量下载） | ✅ |
| 「全部」视图分上下两区：文档最多 4 条（超出给「查看全部 →」）；图片视频不截断，只给计数 | ✅ |
预览面板可拖高度（20%–80%，位置记住）、可全屏，Esc 退出 | ✅ |
| 「在本地打开」：用系统默认应用打开当前预览的这篇文档（预览头的路径面包屑同样可点） | ✅ |
| 双击在新标签页打开（官方文档预览，带 PDF 渲染器与渲染方式切换） | ✅ |
| 过滤框：按标题 / 摘要 / 路径实时过滤 | ✅ |
| 点工作区路径：用系统文件管理器打开项目文件夹 | ✅ |
| 悬停入口按钮偷看：弹只读浮层列最近 5 篇，点击才进右边栏（不推挤布局） | ✅ |
键盘导航：↑ ↓ 移动即预览 / Enter 切换 / Esc 收起 | ✅ |
| 每 5 秒自动刷新 + 手动刷新；2 分钟内改动过的文档打 🆕 | ✅ |
| 中英双语，跟随 DSH 语言实时切换（不用重载插件） | ✅ |
| 零模型调用、零网络出口 | ✅ |
相关度不做可视化（不显示百分比、不画长条）—— 排序本身就是答案，名次即相关度。
knit_docs 工具同一份排序，除了给你看，也开了一个口子给模型。
装好之后，agent 的工具列表里会多一个 knit_docs：它可以问
「这个项目里跟当前话题最相关的文档是哪几篇」，拿到按相关性排好序的
路径 + 标题 + 摘要，再用它自己的 read 打开其中一篇。
为什么有用：agent 想引用项目里已有的文档时，只能靠猜路径、或者把 glob
出来的路径一个个 read 试过去 —— 费 token 又慢。而这份排序 Knit 每一轮已经算好了，
这个工具只是把它交出去。
只读，且不存储任何东西：它读的是项目里现成的文件，不是「记忆」。 和记忆类插件的区别是：它们起点是空的（agent 得先记过才有东西可召回）， Knit 一装上就有整个项目的历史文档可用。
三个细节：
read 工具；Knit 负责发现，不负责搬运。⚠️ 代价要说清楚：工具描述会进每一次请求的系统提示词。 装 Knit 的用户每个会话都会多占一点 token。这是「让 agent 有能力」的必要成本。
.md、图片与视频（路径越出工作区一律拒绝）；媒体只取元信息，不读画面内容knit_docs 工具只读：不写任何文件、不落盘任何索引fetch 都指向插件自己的同源路由install / postinstall）nosniff 与 default-src 'none'; sandbox面板里那份「相关度」只影响排序，不显示也不外传。
上面每一条都有自动化检查守着，逐条列在 SECURITY.md 里 —— 每条属性都指向一个真实存在的测试。
npm test会校验那张表本身没腐烂。
df 的取值范围被压扁，
排序更接近按命中次数排；文档越多越准png/jpg/jpeg/gif/webp/avif/bmp/ico/svg、
视频 mp4/m4v/webm/mov/ogv；图片 ≤ 12MB、视频 ≤ 256MB，超出不列出git clone https://github.com/PolinniZhong/dsh-knit.git
cd dsh-knit
npm test # 215 项，零依赖，不需要先 npm install
改动生效方式：宿主半边（src/host/）改了必须重启 DSH（实测不热加载）；
客户端半边（src/client/）改了硬刷新浏览器即可。
没有构建步骤：客户端半边是手写的 window.__ModuleLoader__.load({...})，
用 React.createElement 而不是 JSX，所以不需要 tsdown / tsc。
静态资源也是内联的 —— 改图标要同时改 assets/ 源文件和 src/client/client.js 里的
KNIT_ICON_PATH，test/icon.test.mjs 会核对两者逐字一致。
knit/
├── package.json # dsh.bundle.patch + dsh.client
├── cordis.patch.yml # 挂进 plugin tree 的 insert 行
├── assets/ # 图标源文件（path 已内联进 client.js）
├── src/
│ ├── host/index.js # /knit/api/recent · /doc · /raw
│ ├── host/relevance.js # 相关性引擎：BM25 + 关键词抽取（纯函数）
│ ├── host/tool.js # agent 文档工具 knit_docs（手写 ToolDefinition）
│ └── client/client.js # 双宿主注册 + 面板 UI
└── test/ # 215 项测试
└── eval/ # 离线质量评测：语料 + 用例 + 冻结的 v0.5.2 基线
细节和取舍写在源码注释里；贡献流程见 CONTRIBUTING.md， 版本变更见 CHANGELOG.md。
版本策略：
0.x表示功能还在动，可能有破坏性变更。1.0.0留给「真实留存被验证之后」，不因为功能做完就发。
MIT © Polinni