类型化判定引擎 PaoloSchwarz/jevcore

jevcore

dshfind

DSH Market

jevcore MCP server

TypeSafe Jev，供 DeepSeek Harness 以及其他任何 MCP 宿主使用。

Jev 不是聊天模型。它回答带类型的问题——noul（是/否）、choice、score——并返回校准过的概率。它不写散文，让它写就是范畴错误。这个项目给智能体的正是这层接口，不多不少。

默认离线。出网行为全部披露。没有任何功能默认开启。

📖 生态知识库——实测数据，不是营销话术：插件开发指南 · 插件选型数据 · 维护标准。

⭐ 如果它帮到了你

这个插件是 DSH 插件家族的一员（40+ 个，全部 Apache-2.0）。如果你在用，给个 star —— 它不会解锁任何功能，但会让下一个人在搜索里更容易找到它。

English: part of a 40+ plugin family for DeepSeek Harness. If it is useful, a star helps the next person find it — nothing is gated behind it.

三个包，一层决策

| 包 | 是什么 | 什么时候用 |
| jevcore | 决策本身。不从 DeepSeek Harness 或 Cordis 导入任何东西。 | 你想在普通脚本、服务或自己的 harness 里用 Jev |
| jevcore-dsh | DSH 插件：一个服务、三个工具、两道需手动开启的闸门 | 你在跑 DeepSeek Harness |
| jevcore-mcp | 同样三个工具，走 MCP，带一个 stdio 二进制 | 你的宿主说 MCP，但不是 DSH |

适配层刻意做薄。packages/dsh 只有四个文件：声明工具 schema，转换钩子负载。所有决策相关的东西——原语、服务商、出网契约、策略、闸门——都在 core 里，这样新适配层不会偏离其他适配层给出的保证。
三个包有一处运行时要求不同：jevcore-dsh 跟随 harness，需要
Node ^22.19.0 || >=24.0.0，而 jevcore 和 jevcore-mcp 需要 >=20。

为什么做这个

2026-09-17 到 09-20 之间，冒出了十九个把 Jev 接进 DSH 的插件。审计它们的源码，发现一个一致的套路：标着 guard、gate 或 warden 的模块，同时也是把提示词、工具参数和文件内容发给第三方的模块，而 README 通常不说这件事。有几个还默认开启。有一道闸门，能被它守护的模型重新配置。
这个项目用同样的思路，把那些失败模式在设计上排除掉：

| 特性 | 这里如何保证 |
| 你不主动请求，就不会有网络调用 | 默认服务商是离线 mock；走真实链路需要同时满足 provider: live 和已解析的凭据 |
| 每次传输都在发生前点名 | 每个功能启动时打一行日志：off 或 SENDS <feature> { fields } |
| 禁用时网关不注册任何东西 | 由测试验证，不靠约定——禁用的网关完全不添加事件监听器 |
| 模型无法放宽自己的约束 | 没有任何工具暴露网关配置 |
| 判官答不上来，绝不等于「放行」 | 未决结果走显式配置，默认 ask |

出网契约

这部分值得在安装前先读。

传输按功能逐个决定，每个功能默认关闭。插件在加载时打印自己的契约：

[jevcore] provider=mock endpoint=none egress=OFF (no network calls will be made; every answer is synthetic)
[jevcore] ready - provider=mock - gates: safety=off context=off

设成 provider: live 并启用所有功能后，同一份报告会明确列出哪些数据离开本机：

[jevcore] provider=live endpoint=https://api.typesafe.ai egress=ON
[jevcore] SENDS tool:jev_ask { state<=16000c questions<=4000c }
[jevcore] SENDS tool:jev_rank { state<=16000c questions<=4000c }
[jevcore] SENDS tool:jev_check { state<=16000c questions<=4000c }
[jevcore] SENDS gate:safety { state<=8000c questions<=2000c }
[jevcore] SENDS gate:context { state<=6000c questions<=2000c }
[jevcore] redaction is best-effort; it removes named fields and known secret shapes, and cannot
recognise an unrecognised secret in free text

| 功能 | 默认关闭？ | 发送什么 |
| tool:jev_ask | 模型调用时才运行 | 模型传入的参数，脱敏后 |
| tool:jev_rank | 模型调用时才运行 | 查询加上每个候选 |
| tool:jev_check | 模型调用时才运行 | 断言及其证据 |
| gate:safety | 是——需显式开启 | 工具名、其参数、工作区根目录 |
| gate:context | 是——需显式开启 | 智能体刚收到的一大段工具结果 |

工具只在模型选择调用时才传输，这在对话记录里看得见。网关会在每次匹配的工具调用上运行，这一点看不见，所以它们需要显式开启。

脱敏，以及它诚实的边界

发送任何内容之前，src/redact.ts 会跑两遍：敏感字段名（password、token、apiKey、authorization、……）下的值整体替换；漏进自由文本的密钥形态字符串做模式匹配（Bearer …、sk-…、ts_live_…、AWS/GitHub/Google 密钥形态、JWT、私钥头、连接串里的凭据）。

这是缓解措施，不是许可。一个密钥既藏在无法识别的键名下，又……
不匹配已知形状的内容会直接放行。如果你的工作负载无法接受这种可能，就不要启用 live 服务商。

安装

作为 DeepSeek Harness 插件

dsh plugin --profile <profile> add jevcore-dsh

或者从本地检出安装：

dsh plugin --profile <profile> add /absolute/path/to/jevcore/packages/dsh

packages/dsh 按名称导入 jevcore，所以从本地检出安装时，还需要让配置档能解析到 core（add /absolute/path/to/jevcore/packages/core）。

然后确认这一行已激活——插件列表里 jev 应显示为 active，而不是 failed——再检查日志里的启动报告。

作为 MCP 服务器

对于支持 MCP 的宿主，同样三个工具可通过 stdio 使用：

npx -y jevcore-mcp

要专门接入 DeepSeek Harness，安装一个仅含配置的 bundle，它的补丁会插入 harness 自带的 MCP 客户端：

- insert:
- id: jev-mcp
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: jev
transport: stdio
command: npx
args: ['-y', 'jevcore-mcp']
env:
TYPESAFE_API_KEY: '<the key>'
failOnStartupError: true

env 映射不是可选项：DSH 会把交给子进程的环境里所有形似凭据的变量名统统剥掉——只要名字含 KEY、PASSWORD、SECRET 或 TOKEN，不分大小写——然后再把这个映射合并回去。你在 shell 里导出的 key 永远到不了，服务器会一直停在离线 mock 上，还不报错。

服务商由环境变量决定：

| 变量 | 作用 |
| TYPESAFE_API_KEY | 存在时选用 TypeSafe 路由 |
| OPENROUTER_API_KEY | 存在且未设置 TypeSafe key 时选用 OpenRouter 路由 |
| JEV_PROVIDER | mock、live 或 openrouter——覆盖上面的判断规则 |
| TYPESAFE_MODEL / OPENROUTER_MODEL | 所选路由的模型 id |
| TYPESAFE_BASE_URL / OPENROUTER_BASE_URL | 所选路由的 API 根地址 |

两个 key 都没有时，它停在离线 mock 上。和插件不同，MCP 服务器只在启动时解析一次凭据，所以设了 JEV_PROVIDER=live 却缺 key，是启动错误，而不是每次调用才出意外。

它的出网报告写到 stderr，绝不写 stdout——在 stdio 传输里 stdout 就是协议通道，多一行就会破坏数据流。

启用 live

接入 Jev 有两条路由。两者调用同样的模型，返回同样的类型化答案；区别在于谁持有你的凭据、谁的服务器能看到你的状态。

直连 TypeSafe——如果你有 console.typesafe.ai 的 key，用这条：

- insert:
- id: jev
name: 'jevcore-dsh'
config:
provider: live
apiKeyRef: TYPESAFE_API_KEY # a reference, never the key
model: jev-latest

经由 OpenRouter——如果 TypeSafe key 不好弄，而你已经有 OpenRouter 密钥了。OpenRouter 提供 System One 模型的路径和 TypeSafe 一样，都是 POST /v1/systemone，位于它自己 API 根路径的下一级。所以这是通往 Jev 的官方文档路线，不是近似方案：

- insert:
- id: jev
name: 'jevcore-dsh'
config:
provider: openrouter
openRouterApiKeyRef: OPENROUTER_API_KEY
model: jev-latest # a bare jev-* id, or typesafe/jev-1.13

要走到这条路线，把官方 @typesafe-ai/sdk 指向 https://openrouter.ai/api，配上你的 OpenRouter 密钥即可。这是 OpenRouter 自己文档里的集成方式，不需要再维护第二个客户端。

关于 OpenRouter 路线，有两点要知道：

- 你的状态数据发往 OpenRouter，不发往 TypeSafe。 这是另一个第三方，数据保留和日志策略都不同。启动报告会写明端点，原因正在于此：去读报告，不要从服务商名字去推断目的地。
- 它会返回费用，TypeSafe 自己的路线不返回，所以这里会填上 usage.costUsd，那边没有。

模型 id 必须是 System One 的。裸写 jev-latest 是默认值，不需要前缀；带版本号的 id 如 typesafe/jev-1.13 可以加 typesafe/，但移动标签不行——这条路线不接受 typesafe/jev-latest。其他任何 id 都会被路由到聊天模型，它返回的是散文，本插件无法把它解读成决策。所以这类 id 在调用前就被拒绝，而不是调用后再误读。

两种情况下，凭据都先通过 DSH 的凭据服务解析，再找同名环境变量。每次调用都会读取，所以进程运行期间新增的密钥也能生效。密钥从不写日志，从不从工具返回，也从不写入配置。每条路线各有自己的引用（apiKeyRef 和 openRouterApiKeyRef），两者不会意外共用同一个密钥。

@typesafe-ai/sdk 是唯一的可选依赖；插件离线也能加载和运行，两者都不需要，只在你选的那条路线上才需要它。

配置

| 键 | 默认值 | 含义 |
| provider | mock | mock（离线、确定性、合成）、live（TypeSafe）或 openrouter |
| apiKeyRef | TYPESAFE_API_KEY | live 路线的凭据引用 |
| openRouterApiKeyRef | OPENROUTER_API_KEY | openrouter 路线的凭据引用 |
| baseURL | https://api.typesafe.ai | live 路线的 API 根路径。非 HTTPS 一律拒绝，回环地址除外 |
| openRouterBaseURL | https://openrouter.ai/api | openrouter 路线的 API 根路径。规则相同 |
| model | jev-latest | 随每个请求发送。OpenRouter 路线上裸默认值可用；typesafe/ 需要带版本号的 id，如 typesafe/jev-1.13，不接受 typesafe/jev-latest |
| logLevel | warn | silent \| warn \| info \| debug |
| minConfidence | 0.7 | 低于此值，不采纳答案 |
| minProbability | 0.6 | 低于此值，不采纳决策 |
| maxStateChars | 按功能 | 替换每个功能的 state 上限。0 表示「保留声明的上限」 |
| gates.safety | false | 派发前判断工具调用 |
| gates.context | false | 扣留体积大、信息量低的工具结果 |

声明的 state 上限为：三个工具 16,000 字符，safety 与 context 两个门控分别为 8,000 / 6,000。maxStateChars 会替换全部上限，启动报告显示生效值而非声明值，所以打印出来的就是实际执行的。

门控接受裸布尔值（safety: false），也接受带 onUndecided 的对象：ask（默认）、allow 或 deny。

ask 是一个问题，所以需要有对象可问。部署时若没有组合任何审批服务，就无法升级到人工，DeepSeek Harness 会拒绝该调用而不是执行它：safety 门控匹配到的每个工具都会被拒绝，运维人员看到的现象就是插件把 shell 命令弄坏了。docs/approval.md 讲了机制，插件 README 讲了部署视角。

未知值在加载时会被拒绝，并给出指明键名的消息，而不是静默忽略——配置里的笔误不该悄悄改变隐私姿态。

使用方式

从另一个插件调用，不经过模型

服务是主要入口。这正是决策模型的意义所在：路由或门控决策不该花掉一次模型往返。

const jev = ctx.get('jev')
const result = await jev.ask({
feature: 'tool:jev_ask',
state: { ticket: 'I was charged twice.' },
questions: {
urgent: { type: 'noul', instructions: 'Does this convey urgency?' },
team: {
type: 'choice',
instructions: 'Which team should handle this?',
criteria: { billing: 'Payments, invoices, refunds', technical: 'Bugs, outages' },
},
},
})

result.answers 携带概率与置信度。拿它们做什么由你的代码决定——src/policy.ts 有一个完整示例，带明确的置信度下限，答案不确定时产出 ask 而不是 allow。

从模型调用

三个工具，刻意保持少量且正交：

- jev_ask —— 针对同一份状态的一批带类型问题。
- jev_rank —— 按单一标准给候选打分并排序，每个候选一个问题，一次往返完成。概率是各候选独立的判断，不是分布。
- jev_check —— 这份证据支持这个主张吗？返回 supported、contradicted、conflicted、insufficient、undecided 或 unknown。矛盾优先于支持，因为既支持又反驳的证据是冲突，不是弱肯定。

内置技能

插件注册了一个技能 typesafe-ai-dsh，教智能体在何时使用 Jev 判断在什么情况下是合适的工具，在什么情况下是范畴错误。它通过技能注册表注册，而不是作为目录随插件发布、让服务商去扫描，因此不依赖配置档把技能存放在哪里，插件移除时也能干净地消失。

正文放在 skills/typesafe-ai-dsh/SKILL.md，加载时读取，而不是内嵌，所以人编辑的文件就是发布出去的文件。有测试断言两者不会漂移。

注册表声明为可选依赖：没有组合技能子系统的配置档仍然能拿到服务和三个工具，只是会收到一条警告，说明技能被跳过。

mock 服务商

设置 provider: mock 后，每个答案都由问题和状态的哈希推导出来，所以测试可以断言精确值，也不会打开任何 socket。合成结果在三处标明身份：provider: "mock"、模型名 mock/jev-synthetic，以及结果上的 warning 字段。一个可能被误认成真实判断的 mock，比没有 mock 更糟。

状态

如实交代哪些验证过、哪些没有。

已验证
- 三个包共 410 个测试通过（核心 314、DSH 66、MCP 30），全程无网络访问，也没有 TYPESAFE_API_KEY。CI 会清空该变量，并期望测试套件照样通过。
- OpenRouter 路线已对真实 API 验证。 pnpm --filter jevcore run probe:live 驱动服务商，pnpm --filter jevcore-mcp run smoke:live 驱动整个 MCP 表面——传输、工具 schema、服务和服商——对真实的 System One 模型（typesafe/jev-1.13-20260917）。一个三原语批次返回了 0.91 的 noul、0.97 的 choice，以及四级评分表上 1.05 的 score，用量报告为 { inputTokens: 469, outputTokens: 68, costUsd: 0.000019698 }。jev_rank 把一份凭据操作手册排在账单指南之前；jev_check 返回 contradicted。两个脚本都需要 OPENROUTER_API_KEY，且不纳入 CI。
- 载荷形状已对照厂商自己的类型定义检查。 test/vendor-conformance.test.ts 把本项目的问题类型和答案类型钉在两个 SDK 上，所以任一方向的漂移都会变成编译错误，而不是在唯一花钱又传数据的路线上发出畸形请求。正是这项检查发现了 score.criteria 被当作键值映射发送，而 API 要求有序数组——这个缺陷此前一直被打桩的单元测试放过。还有一个脚本用 OpenRouter 公布的 zod schema 解析我们的载荷，针对 alpha/decisions 路线；脚本和那条路线都已移除，因为 OpenRouter 服务商现在走文档记载的 /v1/systemone 路径，用的是 TypeSafe 所用的同一个客户端，一致性测试已经覆盖。
- 插件能在运行中的 harness 里激活，工具可用。 插件行报告 active； jev_ask 对 mock 返回了 urgent=true (0.8307) 和 team=billing (0.5027)，耗时 1 ms；jev_check 返回了 verdict="insufficient" 及其三个概率。每个结果都带有 provider: "mock"，token 用量为零，因此默认路径没有发起网络调用。
- 内置技能完成注册。 typesafe-ai-dsh 出现在会话技能目录中。
- 默认路径不发起网络调用：挂载插件并通过服务应答时，对 globalThis.fetch 做了监视断言；组装 MCP 运行时的时候也做了同样的断言。
- 禁用的门禁不会注册事件监听器，被拒绝的出口流量也永远到不了服务商。
- Config 满足 Cordis 在插件启动前要求的 Standard Schema 协议。
- 这里用到的每个 DSH API（ctx.provide、ctx.effect、tools.register、defineTool、tools/pre-execute、tools/post-execute、credentials.resolve）在使用前都对照已安装的运行时检查过，payload 类型来自已安装的声明文件。

未验证，或已知有问题
- TypeSafe 路线跑通了，但只是轻度验证。 packages/core/scripts/probe-live.mjs（pnpm --filter jevcore run probe:typesafe）向真实 API 问了三个问题：十组判定结果已知的 claim/evidence 对、同一个问题重复六次、一个带有 criteria: {true, false} 边界的 noul。两次独立运行结果一致——支持性证据得分 0.95，矛盾证据 0.10，对 claim 保持沉默的证据 0.03，重复问题的波动不超过 0.01。边界被接受。尚未测试的是请求周边的一切，而不是请求本身：真实账号上的配额、限流和权益行为。
- 当前运行的构建里，jev_ask 的描述带有一个损坏的破折号。 它读作 branches on —?routing，而正确的位置应该是一个 em dash 加一个空格。原因：开发早期的一次 UTF-8 往返把 em dash 的第三个字节替换成了 ?。磁盘上已经修好——共四处，剩余零处，源码和构建产物都已确认——但正在运行的进程在修复之前就加载了模块，不重启就无法重新读取。破折号本身只是外观问题