前言¶
在 DeepSeek Harness（DSH）里，Agent 常要在本地知识库或项目目录里找「和当前任务最相关的几个文件」。字面检索（glob、grep）召回面大，但容易把「正文里顺带出现关键词、主旨却无关」的文档一起捞上来；若让 Agent 逐个通读，上下文和延迟都会失控。
下面介绍社区插件 dsh-jev-screen（维护者 chaoguang668）：代码遍历目录并读取每个文件的前部摘要，Jev（OpenJev / Codiv 判别式模型）逐文件打分排序，把几十个候选压成短名单，供 Agent 再读全文做终审。插件归类为「模型推理」，MIT 许可，当前版本 0.3.0，零 npm 依赖——index.js 不 import 任何包。
这是什么¶
一句话：不是找全，是排序。 glob / grep 已经是召回超集；Jev 不提供「多找文件」的优势，而是在已有候选上做语义降噪。README 里的一次实测（154 个资料文件，query 为「量化交易 选股 回测 策略」）中，规则层读文件头部命中 34 个，Jev 层高度相关 4 个、部分相关 3 个，其余 147 个判无关，且没有出现「Jev 高相关但规则层漏掉」的额外召回——价值在于把 34 收敛到 4。文件名几乎不含查询词、但正文相关的文件，反而可能被 Jev 排到前面（README 举例：Agent记忆/02_金融数据源与实证方法论红线.md 被排到第 1，conf 0.964）。
DSH 生态里是「一切皆插件」；插件目录在 SkillHub，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
工具 jev_screen¶
Agent 通过 DSH 调用：
jev_screen(root = "/path/to/knowledge-base", query = "用量化方法做股票投资决策", top = 20)
root：待检索目录的绝对路径。query：自然语言检索目标，会编入分档标准；README 建议写清主题，而不是罗列关键词。top：返回条数，默认 20，上限 200。
返回按相关度排序的候选（路径、档位、归一化分、连续分、档位来源、置信度等）以及统计（扫描数、失败数、failedPaths、并列比例 tieRatio、tokens、耗时）。
代码侧保证的三件事¶
- 凭据类文件不外发：
.env、credentials*、密钥扩展名，以及.git、node_modules等目录在遍历阶段即排除，不读也不送到 Jev 端点。 - 逐文件一次请求：N 个文件对应 N 次请求，靠并发摊薄；不能把多文件塞进一份 state 做一次 Choice。
- 档位取
argmax(probabilities)：不能对连续score做round当档位；score作为连续分用于同级并列时的次级排序。
同质门控与失败名单¶
当同档并列占比 tieRatio 超过 tieWarnRatio（默认 0.3）时，输出会提示候选集同质、Jev 降不了噪——这只用于否决「别指望 Jev 筛掉噪音」，不能证明排序正确。请求失败的文件会在正文中逐个列出并计入 stats.failedPaths。
安装与启用¶
插件以当前 DSH 宿主进程权限运行；安装前请自行查看 GitHub 仓库 源码与 LICENSE。Node 要求 >=20。
方式一：本地路径登记为 bundle（README 推荐）¶
将仓库放到本地后，在 profile 的 package.json 里声明 file 依赖并加入 bundles（路径换成实际位置）：
{
"dependencies": {
"dsh-jev-screen": "file:/absolute/path/to/dsh-jev-screen"
},
"dsh": {
"profile": {
"bundles": ["dsh-jev-screen"]
}
}
}
方式二：tarball¶
在插件目录执行 npm pack 得到例如 dsh-jev-screen-0.3.0.tgz，再在 profile 里用 file:/absolute/path/to/dsh-jev-screen-0.3.0.tgz 引用。
方式三：插件管理器¶
若宿主提供 plugin_manager（DSH 桌面版自带）：
plugin_manager install_bundle /absolute/path/to/dsh-jev-screen
生效与验证¶
cordis.patch.yml 会向组合树插入 loader entry（id: jev-screen，name: dsh-jev-screen）。登记后执行 profile 的依赖解析（如 pnpm install 或插件管理器安装命令），宿主重启后 entry 生效。改插件代码后应 node --check 并重启宿主验证；README 说明存在版本闸，勿用强制热重载验证。
验证是否装好，可让模型调用：
jev_screen(root = "/path/to/some/dir", query = "这类文件是干什么的", top = 5)
凭据¶
工具按 apiKeyEnv（默认 TYPESAFE_API_KEY）从 DSH 凭据服务解析密钥，优先级为：进程环境 > $DSH_HOME/.credentials.yaml（可写）> 宿主 cwd 的 .env > $DSH_HOME/.env。插件不含内置密钥。示例：
export TYPESAFE_API_KEY=<your-key>
或通过凭据服务写入（值来自你自己的安全位置）：
await ctx.credentials.set('TYPESAFE_API_KEY', process.env.MY_JEV_KEY)
换 key 无需重启宿主。
配置¶
默认值可在 profile 的 cordis.patch.yml 里覆盖，常用项包括：
| 键 | 默认 | 说明 |
|---|---|---|
apiKeyEnv |
TYPESAFE_API_KEY |
凭据环境变量名 |
baseUrl |
https://api.codiv.ai |
OpenJev 兼容端点 |
model |
openjev-latest |
也可用 openjev-0.1 |
maxFiles |
400 |
送审文件数上限 |
concurrency |
6 |
并发请求数 |
headBytes |
4096 |
每文件读取字节数 |
headChars |
500 |
送审摘要字符数 |
tieWarnRatio |
0.3 |
同质警告阈值 |
完整表格见仓库 README。
本地 Laya（可选）¶
若使用 Jev 兼容的本地模型 convaiinnovations/laya-multilingual，须显式设置 model: multilingual，且 levelOrder 必须为 ascending（默认 descending 面向 Codiv Jev）。示例：
- id: jev-screen
name: dsh-jev-screen
config:
baseUrl: http://127.0.0.1:11500
model: multilingual
levelOrder: ascending
README 注明：Laya 适合快速粗筛，不宜替代终审；文件摘要仍会发往 baseUrl，敏感目录勿指向不可信端点。
适用场景与注意¶
适合：先用 grep 等拿到候选或在中等规模目录里做语义重排，再让 Agent 只读 top 短名单。
不适合：指望 Jev「找全」、交互式实时检索（README 记录单次调用 p50 约 2.0s，靠并发摊薄）、或把返回清单当最终结论而不读全文。
其他限制（来自 README）：摘要会出境到配置的 baseUrl；Codiv 公共服务稳定性取决于社区维护者环境；按文档估算成本约为输入 $0.042 / 百万 tokens。插件定位是降噪排序器，找全仍交给 grep。
结尾¶
dsh-jev-screen 把目录遍历与 Jev 逐文件打分接到 DSH 工具链里：在已有召回之上做精度排序，并用排除规则、失败名单和同质提示划清输出边界。进一步了解可访问 SkillHub 目录页 与 GitHub 仓库。
