类型化判断 LeonieKarabacak542/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 key 了。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 key —— 这是 OpenRouter 自己文档里的集成方式，所以不需要再维护第二个客户端保持同步。

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

- 你的状态会发给 OpenRouter，不是发给 TypeSafe。 这是另一个第三方，留存和日志策略都不同。启动报告会写明 endpoint，原因正是如此 —— 去读它，不要从服务商名字去推断目的地。
- 它会返回 cost，TypeSafe 自己的路线不返回，所以这里 usage.costUsd 有值，那边没有。

model id 必须是 System One 的。裸写 jev-latest 是默认值，不需要前缀；typesafe/ 可以加在带版本号的 id 上，比如 typesafe/jev-1.13，但不能加在浮动 tag 上 —— typesafe/jev-latest 这条路线不接受。其他任何 id 都会被路由到 chat model，它返回的是散文，这个插件没法把它当成决策来解读，所以会在调用前就拒绝，而不是调用后再误读。

两种方式下，凭据都先通过 DSH 的 credential service 解析，再找同名的环境变量。每次调用都会读取，所以进程运行期间新加的 key 也能被拾取。它从不写日志，从不从工具返回，也从不写入配置。每条路线都有自己的引用（apiKeyRef 和 openRouterApiKeyRef），所以两者不会意外共用同一个 key。

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

Configuration

| Key | Default | Meaning |
| provider | mock | mock（离线、确定性、合成）、live（TypeSafe）或 openrouter |
| apiKeyRef | TYPESAFE_API_KEY | live 路线的凭据引用 |
| openRouterApiKeyRef | OPENROUTER_API_KEY | openrouter 路线的凭据引用 |
| baseURL | https://api.typesafe.ai | live 路线的 API 根路径。非 HTTPS 会被拒绝，loopback 除外 |
| 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 个测试通过（core 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 为 alpha/decisions 路线发布的 zod schema 解析；脚本和那条路线现在都没了，因为 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 的第三个字节替换成了 ?。磁盘上已经修好了——四处出现，零处残留，源码和构建产物都已确认——但正在运行的进程在修复之前就加载了模块，不重启无法重新读取。破折号本身只是外观问题