PerryLink/jevcore

jevcore
dshfind

DSH Market
OpenSSF Scorecard
jevcore MCP server

面向 DeepSeek Harness
以及任何其他 MCP 宿主的类型安全 Jev。

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 导入任何内容。 | 你想在普通脚本、服务或自己的宿主中使用 Jev |
| jevcore-dsh | DSH 插件：一个服务、三个工具、两个需主动开启的开关 | 你正在运行 DeepSeek Harness |
| jevcore-mcp | 通过 MCP 提供同样的三个工具，附带一个 stdio 二进制文件 | 你的宿主支持 MCP 但不是 DSH |

适配器刻意做得很薄。packages/dsh 只有四个文件：它声明工具 schema 并
转换 hook 载荷。所有与决策相关的部分——原语、提供方、出网
契约、策略、开关——都位于 core 中，因此新的适配器不会偏离
其他适配器所做出的保证。
三个包之间有一项运行时要求不同：jevcore-dsh 跟随宿主，需要
Node ^22.19.0 || >=24.0.0，而 jevcore 和 jevcore-mcp 需要 >=20。

为什么会有这个项目

在 2026-09-17 到 09-20 之间，出现了十九个将 Jev 接入 DSH 的插件。审计其源码
发现了一个一致的模式：被标记为 guard、gate 或 warden 的模块，同时也是
将提示词、工具参数和文件内容发送给第三方的模块，而 README 通常并未
说明这一点。其中几个默认启用。有一个门禁可以被它所守护的模型重新配置。

本项目是同样的想法，但将这些失败模式从设计上排除：

| 属性 | 在此如何得到保证 |
|---|---|
| 除非你主动请求，否则不会发起网络调用 | 默认提供程序是离线模拟；实时路径需要同时满足 provider: live 和已解析的凭据 |
| 每次传输在发生前都会被命名 | 每个功能一行启动日志：off 或 SENDS  { 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 add jevcore-dsh

或者从检出目录安装：

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

packages/dsh 按名称导入 jevcore，因此检出目录还需要让核心包能从该 profile 中解析（add /absolute/path/to/jevcore/packages/core）。

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

作为 MCP 服务器

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

npx -y jevcore-mcp

要专门将其接入 DeepSeek Harness，请安装一个仅含配置的 bundle，其 patch 会插入 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: ''
failOnStartupError: true

env 映射不是可选项：DSH 会从交给所生成服务器的环境中剥离所有凭据形态的名称——任何包含 KEY、PASSWORD、SECRET 或 TOKEN 的名称，不区分大小写——然后再将此映射合并回去。在你的 shell 中导出的密钥永远不会到达，服务器会停留在离线 mock 上而不报告错误。

提供方从环境中选择：

| 变量 | 效果 |
|---|---|
| TYPESAFE_API_KEY | 存在时选择 TypeSafe 路由 |
| OPENROUTER_API_KEY | 存在且未设置 TypeSafe 密钥时选择 OpenRouter 路由 |
| JEV_PROVIDER | mock、live 或 openrouter——覆盖上述启发式规则 |
| TYPESAFE_MODEL / OPENROUTER_MODEL | 所选路由的模型 id |
| TYPESAFE_BASE_URL / OPENROUTER_BASE_URL | 所选路由的 API 根地址 |

两个密钥都没有时，它会停留在离线 mock 上。与插件不同，MCP 服务器在启动时一次性解析其凭据，因此缺少密钥且 JEV_PROVIDER=live 是启动错误，而不是每次调用时的意外。

它的出口报告发往 stderr，绝不发往 stdout——在 stdio 传输上，stdout 是协议通道，那里出现一行杂散输出会破坏流。

上线

通往 Jev 有两条路由。两者调用相同的模型，且都返回相同的类型化答案；区别在于谁持有你的凭据，以及谁的服务器能看到你的状态。

直接使用 TypeSafe——如果你有来自 console.typesafe.ai 的密钥，请使用此方式：

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

通过 OpenRouter——如果 TypeSafe 密钥不切实际，而你已经有一个 OpenRouter 密钥，请使用此方式。OpenRouter 在与 TypeSafe 相同的 POST /v1/systemone 路径上提供 System One 模型，只多一层
在它自己的 API 根路径之下，因此这是通往 Jev 的文档化路由，而非其近似：

- insert:
- id: jev
name: 'jevcore-dsh'
config:
provider: openrouter
openRouterApiKeyRef: OPENROUTER_API_KEY
model: jev-latest              # 一个裸的 jev-* id，或 typesafe/jev-1.13

通过将官方 @typesafe-ai/sdk 指向 https://openrouter.ai/api 并带上你的 OpenRouter 密钥即可到达该路由——这是 OpenRouter 自己文档化的集成方式，因此无需维护第二个客户端来保持同步。

关于 OpenRouter 路由，有两点需要了解：

- 你的状态会发送到 OpenRouter，而不是 TypeSafe。 这是一个不同的第三方，具有不同的保留和日志策略。启动报告正是出于这个原因会指明端点——请阅读它，而不是从提供商的名称推断目的地。
- 它会返回成本，而 TypeSafe 自己的路由不会，因此 usage.costUsd 在这里会被填充，而在那里则缺失。

模型 id 必须是 System One 的。裸的 jev-latest 是默认值，无需前缀；typesafe/ 可用于带版本的 id，例如 typesafe/jev-1.13，但不能用于移动标签——typesafe/jev-latest 不被该路由接受。任何其他 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 个字符，安全门和上下文门分别为 8,000 / 6,000。maxStateChars 会替换所有这些值，启动报告显示的是生效值而非声明值，因此它打印什么，就强制执行什么。

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

ask 是一个问题，因此它需要有可询问的对象。一个未组合任何审批服务的部署无法升级到人工，此时 DeepSeek Harness 会拒绝该调用而不是运行它：安全门匹配的每个工具都会被拒绝，操作员会体验到该插件破坏了 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 时，每个答案都派生自问题和状态的哈希，因此测试可以断言精确的值，并且不会打开任何套接字。合成结果在三处被标记为合成：provider: "mock"、模型名称 mock/jev-synthetic，以及结果上的 warning 字段。一个可能被误认为是真实判断的 mock 会比完全没有 mock 更糟糕。

状态

对已核实和未核实内容的诚实说明。

已核实
- 三个包中共有 410 个测试通过（314 个 core、66 个 DSH、30 个 MCP），且无网络访问、无
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，
以及在一个四级评分标准上的 score 为 1.05，用量报告为
{ inputTokens: 469, outputTokens: 68, costUsd: 0.000019698 }。jev_rank 将一份凭据
运行手册排在计费指南之上；jev_check 返回了 contradicted。两个脚本都需要
OPENROUTER_API_KEY，并被排除在 CI 之外。
- 载荷形状已对照供应商自己的类型定义进行检查。
test/vendor-conformance.test.ts 将本项目的 question 和 answer 类型固定到两个 SDK 上，因此任一方向的
偏离都会成为编译错误，而不是在唯一一条既花钱又传输数据的路由上发出格式错误的请求。正是这项检查发现了 score.criteria 在 API 要求有序数组时却被作为键控映射发送——这个缺陷在打桩的单元测试中一直被忽略
始终。还有一个脚本将我们的载荷对照 OpenRouter 为 alpha/decisions 路由发布的 zod
schema 进行解析；该脚本和该路由都已不复存在，因为
OpenRouter 提供程序现在通过 TypeSafe 所使用的同一客户端走文档化的 /v1/systemone 路径，而一致性测试
已经覆盖了这一点。
- 该插件在运行中的 harness 里激活，且其工具可正常工作。 插件行报告为 active；
jev_ask 在 1 毫秒内针对 mock 返回了 urgent=true (0.8307) 和 team=billing (0.5027)，并且
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）在使用前都已对照已安装的运行时进行检查，且载荷类型来自已安装的声明文件。

未验证，或已知损坏
- TypeSafe 路由已被使用，但只是轻度使用。 packages/core/scripts/probe-live.mjs
（pnpm --filter jevcore run probe:typesafe）向真实 API 询问三件事：十对判定结果已知的
主张/证据对、一个重复六次的问题，以及一个携带 criteria: {true, false} 边界条件的 noul。
两次独立运行结果一致——支持性证据得分 0.95，矛盾证据 0.10，对主张保持沉默的证据 0.03，
重复问题的波动不超过 0.01。边界条件被接受。尚未测试的是围绕请求本身而非请求之外的一切：
真实账户上的配额、速率限制和权益行为。
- jev_ask 的描述在当前运行的构建上带有一个损坏的破折号。 它显示为
branches on —?routing，而那里本应是一个 em dash 后跟一个空格。原因：开发早期的一次
UTF-8 往返转换将 em dash 的第三个字节替换成了 ?。它在磁盘上已修复——四处出现，零处
残留，已在源代码和构建输出中确认——但正在运行的进程在修复之前就已加载其模块，不重启
就无法重新读取。破折号本身只是外观问题，但陈旧性不是：同一进程还缺少自其启动以来的
所有修复，包括防止 0.51 被解读为确定“是”的 band 字段。
- MCP 服务器已由真实的 MCP 客户端通过 stdio 端到端驱动
（pnpm --filter jevcore-mcp run smoke）：握手、工具发现、三次成功调用，以及针对无效
批次的错误结果。它尚未被任何其他第三方宿主驱动。
- 实时流量上的门行为。这些门已针对合成答案和真实钩子载荷形状进行测试，但没有任何真实
工具调用被端到端地门控过。
- 上下文门无法恢复已消耗的上下文。它阻止结果到达 agent；它不会追溯性地修剪任何内容，
任何声称相反的插件的 README 都应被审慎看待。
- 没有长时间运行或对抗性测试。脱敏是基于模式的，会漏掉未识别的
秘密形态。

设计说明

有三个决策很容易做错，而且做错的代价很高：

一个无法作答的裁判，绝不能意味着“允许”。 如果 Jev 不可达，或者回答低于置信度下限，门控会通过 onUndecided 来裁决，其默认值是 ask。想要得到失败开放（fail-open）行为，唯一的方法就是显式配置它。上下文门控是有意设置的例外：它会无条件失败开放，因为让一个真实的工具结果因为一个虚假的“无关”判定而丢失，比保留一个没有信息量的结果更糟。

模型能说的任何话都不能改变门控。 没有任何工具会暴露门控配置、阈值或作用域。一个被守护进程能够重新配置的守卫，就不是守卫。

概率不是许可。 Jev 返回的是数字；src/policy.ts 会根据本地配置的阈值把它们转换成 allow/ask/deny。如果一个回答给出了声明标准之外的值，它就是 invalid，并且会拒绝——类型化决策模型的保证在于，它不可能返回一个未声明的值，所以一旦出现违规，就意味着上游某个地方出了问题。

开发

pnpm install
pnpm run check      # typecheck + tests + build
pnpm test           # tests only

没有任何测试需要凭据或网络连接，CI 通过在清空 TYPESAFE_API_KEY 的情况下运行来强制保证这一点。

许可证

Apache License 2.0 © 2026 jevcore contributors

TypeSafe、Jev 和 System One 是 TypeSafe AI 的商标。本项目是一个独立集成，不隶属于 TypeSafe AI，也未获得其认可。