buberlo/dsh-jev

dsh-jev

DeepSeek Harness (DSH) 的 Jev 决策层。

DSH 运行智能体。TypeSafe Jev 做出微小、快速的决策。你的代码决定这些答案意味着什么。

观看：无需打开数据库即可排查 Kubernetes 问题

观看 66 秒的 Kubernetes 故障排查演示： 健康的 Pod，发布后连接中断。智能体追踪 Ingress → Service → Pod 并修复网络路径。Jev 的站点策略对宽泛的“允许所有流量”捷径进行门控，因此门户可以恢复，而 PostgreSQL 保持隔离。同样新录制的模型调用在两个 harness 上针对一个真实的、一次性的 Kubernetes 集群运行，并带有实时 Jev 评估。带有清晰标注的、带神经解说的回放；此对比中没有实时重新规划。
视频 · 字幕 ·
方法、所有运行和限制。
回放还显示了一次无害的重置被阻止——一个已记录在案的误报。

user task
│
▼
┌───────────────────────────────────────────────────────────┐
│  DeepSeek Harness agent loop                              │
│  planning · tools · execution · sessions                  │
│                                                           │
│   pre-step ──▶ Jev: which tools are relevant?   → restrict│
│   tool call ──▶ Jev: is this call safe to run?  → ask/hold│
│   result ─────▶ deterministic loop guard (no model)       │
│   request ────▶ Jev: which model route fits?    → route   │
└───────────────────────────────────────────────────────────┘
│
▼
TypeSafe Jev (System One)  ← choice · score · noul

没有任何 Jev 调用是由 LLM 规划的，没有任何模型输出会成为解释，也没有任何模型答案可以扩大权限。Jev 只会收窄或门控。

一览

| | |
|---|---|
| 包 | @buberlo/jev-core（与 harness 无关）· @buberlo/dsh-jev（DSH 插件/捆绑包） |
| npm | npm view 2026-09-23 列出了 0.1.0、0.1.2、0.1.3 和 0.1.4。两个包的 dist-tag latest 均为 0.1.4。工作区为 0.1.4。npm install @buberlo/dsh-jev@0.1.4 会解析到 @buberlo/jev-core@^0.1.4。不要安装 @buberlo/dsh-jev@0.1.2 或 @0.1.3（字面量 workspace:^、EUNSUPPORTEDPROTOCOL）。0.1.3 在暂存版本冲突（E409）后被放弃。 |
| 已验证的 DSH | 0.1.6-alpha.2（提交 ddefc45）、@deepseek-ai/cordis 4.0.2 |
| 已验证的 TypeSafe SDK | @typesafe-ai/sdk 0.6.0 |
| 默认值 | provider: mock、mode: shadow — 离线，无行为变更 |
| 测试 | 147 个（85 个核心 + 62 个 DSH 集成）· 25 个评估夹具以及本地部署支持集 |
| 实时 API | 已实现，需要显式密钥；不属于任何默认配置 |
| 许可证 | MIT |

这是什么——以及不是什么
是： 一个将 Jev 绑定到真实 DSH 扩展点的插件，外加一个可复用的决策核心，你可以将其嵌入任何应用（游戏、搜索、MCP 路由器）。

不是： 一个 Jev 训练或托管项目、一个 DSH 分支、一个仪表盘、一个数据库或一个 MCP 平台。它从不自动应用模型建议，从不缓存审批，也从不默认发送仓库、日志或对话记录。

60 秒试用

以下所有内容均使用合成答案离线运行。无需密钥，无需网络。

git clone https://github.com/buberlo/dsh-jev
cd dsh-jev
pnpm install
pnpm build

pnpm example:coding    # tool selection + call assessment
pnpm example:dsh       # real DSH services + real plugin (still synthetic)
pnpm example:ops       # read-only incident router
pnpm example:game      # standalone game, imports only jev-core

pnpm example:coding 展示的内容（节选）：

=== 1. Dynamic tool selection ===
input task : Fix the failing billing test: read src/billing.test.ts and run the test suite
categories (independent relevance questions):
- files    relevance=0.97 relevant=true, pick=read_file p=0.88 conf=0.88
- tests    relevance=0.93 relevant=true, pick=run_tests p=0.91 conf=0.91
selected : read_file, run_tests

=== 2. Pre-execution assessment (proposed model call) ===
policy     : allow (applied=true)
values     : matches=0.96 missing=0.06 violates=0.04

pnpm example:dsh 更进一步：它挂载了真实的 DSH 工具流水线和实际插件，然后展示一个调用被拦截，并显示导致拦截的策略规则。每个模型值都明显是合成的（mock/jev-synthetic）。

Jev 在此决定什么

| DSH 时刻 | Jev 问题（示例） | 确定性后果 |
|---|---|---|
| agent/pre-step | 来自类别“files”的工具是否相关？ | 通过作用域内的 tools.restrict 缩小可见工具范围 |
| tools/pre-execute | 这个特定的 call 是否匹配任务？它是否需要缺失的信息？该调用本身是否违反了已声明的限制？（观察 ≠ 修改） | allow · ask（审批）· hold · deny |
| agent/request | 哪条已配置的路由适合此任务？ | 仅当目标经验证可用时才切换提供商/模型 |
| ctx.skills | 这一轮是否需要一项技能？哪一项？ | 注入一条有界提示；仅当模型请求时才加载正文 |

Jev 回答三类问题；核心保持它们的含义相互区分：

| 原语 | 含义 | 代码用它做什么 |
|---|---|---|
| Choice | 一个已定义集合中的某一项，外加完整的概率分布和置信度 | 将概率与阈值比较，或根据所选标签分支 |
| Score | 在命名层级上的序数位置（可以落在层级之间） | 加权/排序；从不显示为“风险百分比” |
| Noul | 一个是/否陈述成立的概率（无置信度字段） | 通过阈值转化为布尔决策 |

独立问题会在一个请求中发送（它们无法看到彼此的
答案），因此代码会发送它可能需要的每个问题，并忽略其余部分。

模式与提供方

两个独立的开关——答案来自哪里，以及它们是否可以采取行动：

| 模式 | Jev 请求 | 行为变化 | 典型用途 |
|---|---|---|---|
| off | 无 | 无 | 终止开关 |
| shadow | 是 | 无（决策会被记录） | 在执行前观察 |
| enforce | 是 | 决策会被应用 | 生产环境 |

| 提供方 | 网络 | 答案 |
|---|---|---|
| mock | 无 | 确定性的合成场景（默认） |
| live | TypeSafe API | 真实的 Jev；需要显式的 apiKey |

从默认的 mock + shadow 开始，观察日志，然后切换到
enforce，如果你想要真实的 Jev 答案，再切换到 live。live + shadow 仍然
会将状态传输到 TypeSafe——它只是跳过应用决策。

用例

- 编码助手——只保留任务所需的工具，在风险调用运行前进行门控，停止相同的重试循环。
examples/coding
- 只读运维路由器——将事件路由到诊断，同时硬性
策略使补救措施无法触及。examples/ops-readonly
- 交互式应用和游戏——将自由文本映射到有界动作集，
并具有确定性后果，无需聊天模型。
examples/standalone-game
- 任何智能体框架——核心与框架无关；LangChain 团队
用 TypeSafeClassifier、模型路由和
工具风险门控中间件描述了相同的模式（参见 docs/architecture.md）。

详情和设计说明：docs/use-cases.md。

安装到 DSH 配置文件

当前注册表发布版本是 0.1.4（两个包的 latest，npm view
2026-09-23）。npm install @buberlo/dsh-jev@0.1.4 成功并拉取
@buberlo/jev-core@0.1.4（^0.1.4，由 pnpm 重写）。完整的 DSH 配置文件
启动已在 2026-09-19 针对 0.1.0 验证，尚未针对
0.1.4 重复验证。

dsh plugin --profile  add @buberlo/dsh-jev@0.1.4
dsh --profile  --dump-config   # shows the "# == @buberlo/dsh-jev" layer

不要安装 @buberlo/dsh-jev@0.1.2 或 @0.1.3。那些 tarball 仍然
包含 "@buberlo/jev-core": "workspace:^"（用 npm 打包，而不是 pnpm）。
npm install 会失败并报 EUNSUPPORTEDPROTOCOL。0.1.3 已被废弃：一个
细粒度的绕过 2FA 令牌暂存了该版本，重新发布返回 E409。
0.1.4 是替代它的发布版本。工作区 package.json 是 0.1.4。

检出代码会打包相同的版本。使用 pnpm 以便 workspace: 被重写：

pnpm --filter @buberlo/jev-core pack --pack-destination ./packs
pnpm --filter @buberlo/dsh-jev pack --pack-destination ./packs
dsh plugin --profile  add ./packs/buberlo-dsh-jev-0.1.4.tgz
overlay packs/buberlo-jev-core-0.1.4.tgz on the profile
(see BENCH_LOCAL_PACKS in docs/benchmark.md)
dsh --profile  --dump-config   # shows the "# == @buberlo/dsh-jev" layer
该 bundle 插入一行；通过覆盖该行的 config 来配置它：

- id: jev
name: '@buberlo/dsh-jev'
config:
provider: mock            # mock | live
mode: shadow              # off | shadow | enforce

selection:                # dynamic tool preselection
enabled: true
alwaysAllow: [read_file]
categories:
files: 'Reading or writing workspace files'
tests: 'Running or inspecting tests'
toolCategories:
read_file: [files]
write_file: [files]
run_tests: [tests]

assessment:               # per-call semantic check
enabled: true
onFailure: ask          # ask | hold   (never an allow)

skills:                   # route the vendored TypeSafe skill
enabled: true
routingHints:
typesafe-ai: 'especially for TypeSafe/Jev integration, System One models, classifiers'

modelRouting:             # map route classes to real models
enabled: false
routes:
fast: { provider: deepseek-official, model: deepseek-v4-flash }
reasoning: { provider: deepseek-official, model: deepseek-v4-pro }

实时 API —— 两个显式设置，绝不隐式：

provider: live
apiKey: !!js process.env.TYPESAFE_API_KEY

从 Web 客户端配置它

在 Web/桌面配置文件中，该 bundle 附带一个配置页面：打开 Plugins 页面以及该 bundle 自己的页面，即可找到 Jev 卡片。它解释了 Jev 在循环中的作用，并实时编辑安全子集：

- 模式（off / shadow / enforce）—— 立即生效，无需重启；
- 五个功能开关（selection、assessment、loop guard、skills、model routing）。

Provider、model 和 API key 保留在 cordis.yml 中（key 是机密，绝不会显示）。无头配置文件没有 Web 客户端，会直接忽略这一半；插件从其组合配置运行，行为完全相同。

所有配置字段及其默认值

| 字段 | 默认值 | 含义 |
|---|---|---|
| provider | mock | 答案来源 |
| mode | shadow | off / shadow / enforce |
| model、apiKey、baseURL | — | 实时 provider 设置（key 显式指定） |
| timeoutMs / budgetMs | 5000 / 8000 | 每次尝试超时 / 整个调用预算 |
| maxRetries | 1 | SDK 拥有的 HTTP 重试；没有第二层重试循环 |
| maxConcurrent | 2 | 并发 provider 请求数 |
| maxStateChars / maxArgumentChars | 4000 / 1200 | 传输状态和参数边界 |
| thresholds.* | 见 docs/policy.md | 未校准的默认值；请在你的数据上调整 |
| selection.alwaysAllow | [] | 选择永远不能隐藏的工具 |
| selection.toolCategories | {} | 工具 id → 类别 id（默认：工具 id 作为类别） |
| loopDetection.maxRepeats | 2 | 在下一个调用被保持之前，允许的相同已完成调用次数 |
| skills.routingHints | {} | 按技能名称提供的额外路由指导 |
| skills.maxDescriptionChars | 240 | 每部分元数据边界 |
| modelRouting.routes | {} | 路由类别 → 真实提供商/模型 |
| mock.delayMs / mock.answers | 0 / {} | 确定性的离线场景 |
| logDecisions | true | 结构化决策日志 |

该集成如何保持安全

- 无隐式实时访问。 provider: live 在没有显式密钥时会在插件加载时失败——已通过真实的 dsh 加载器验证。
- 无源自模型的权限。 失败、超时、中止、过期快照和验证错误会产生 ask/hold；配置会拒绝其他任何情况。
- 无过早允许。 评估监听器始终先调用 next() 并以单调方式组合（deny > hold > ask > allow）；后续策略绝不会被跳过。
- 无扩大。 Jev 选择会与现有约束求交集，只能隐藏工具，绝不能添加工具。
- 无过期决策。 异步结果绑定到轮次/目录快照；快照变更会丢弃结果并应用失败规则。
- 无持久缓存。 批准按调用进行；参数变更会重新评估。循环防护是一个有界、确定性的计数器。
- 有界、脱敏的数据。 只有任务文本、工具元数据和有界参数会离开进程；脱敏是一项额外措施，而非匿名化。

实测价值

Kubernetes 网络支持演示 针对真实集群重放全新的 DeepSeek 工具调用，并带有实时 Jev 评估，以将门控的效果与规划器选择差异隔离开来。它比较了门户的恢复与数据库隔离的保持。方法、所有运行与限制。

同一任务，两个 AI 代理——没有 Jev 时文件被删除，有 Jev 时文件得以保留

带旁白的讲解视频：英语 · 德语
原始终端回放：GIF · 英语 · 德语

Jev 是否增加价值？

Jev 阻止了每一次尝试：在较弱的模型上，代理在 10/10 次运行中都试图删除受保护的审计追踪——31 次拒绝，零次执行——而没有 Jev 时它得逞了。老实说，脚注：提示词中的一条规则在我们的运行中也同样有效，而且成本更低。Jev 在规划模型上下文之外增加了可审计的评估；确定性门控执行其决策，但模型判断本身并非安全保证。完整方法、原始数据、视频与限制：
docs/benchmark.md。

状态

| 领域 | 状态 |
|---|---|
| @buberlo/jev-core | 已实现，82 个单元测试 |
| @buberlo/dsh-jev | 已实现，38 个集成测试（真实 ToolRuntime、真实代理循环、真实批准服务、真实设置提供程序） |
| 动态工具选择 | 已测试，包括预先存在的拒绝和并行会话 |
| 调用评估 + 审批 | 已测试，包括变更参数和故障关闭路径 |
| 循环防护 | 已测试（按代理隔离，影子模式 vs 强制执行） |
| 模型路由 | 已测试，带经验证的可用性回退 |
| 技能路由 + 内置 TypeSafe 技能 | 已针对真实文件系统提供程序测试 |
| Web 客户端配置页面 | 已实现（按 bundle 键控的 Plugins 页面）；设置写入和卡片交互已测试；模块由运行中的 Web 应用提供 |
| 真实 dsh CLI 配置文件/加载器 | 已验证（见 docs/upstream-compatibility.md） |
| 已发布包 | npm view 2026-09-23：0.1.0、0.1.2、0.1.3、0.1.4；latest 为 0.1.4。@buberlo/dsh-jev@0.1.4 随 @buberlo/jev-core@^0.1.4 安装。插件 @0.1.2 和 @0.1.3 已损坏（workspace:^），不得安装。0.1.3 已废弃（暂存 E409）。端到端 dsh 配置文件安装已针对 0.1.0 验证（2026-09-19），未针对 0.1.4 重新运行。 |
| 实时 TypeSafe API | 于 2026-09-19 执行（jev-1.13.0）：25/25 夹具一致，0 错误，平均 483 ms——这是一次测量，而非准确性声明 |
| 阈值校准 | pnpm calibrate 测量一次并扫描阈值；实时运行报告一致性范围（默认值位于其中），而非校准后的操作点 |
| 带/不带 Jev 的基准测试 | 执行了两个层级以及一个带视频的用例（OpenCode Go、deepseek-v4.1-flash、10 次运行/变体）：模拟 Jev 约 0 开销；Jev 为 3 个决策增加 +4.6 s/轮；基线在 4/10 次运行中破坏了审计追踪，而 Jev 拒绝了每一次尝试——见 docs/benchmark.md |
| 代码模式（PTC） | 嵌套分派已测试；完整 PTC 运行时未挂载 |

仓库布局

packages/jev-core/     与 harness 无关的决策核心
packages/dsh-jev/      真实 Cordis/DSH 插件（bundle）
examples/              编码 · 运维只读 · 独立游戏 · DSH 运行时
evals/fixtures/        版本化的 de/en 评估数据集
.agents/skills/        内置 TypeSafe 代理技能（固定上游提交）
docs/                  架构 · 上游兼容性 · 策略 · 评估 · 路线图 · 技能 · 用例
scripts/               verify.sh · packaging-test.mjs · run-evals.ts

文档

| 文档 | 回答 |
|---|---|
| docs/getting-started.md | 分步指南：首次运行、阅读输出、上线 |
| docs/use-cases.md | 构建什么以及为什么有效 |
| docs/architecture.md | 各部分如何组合、扩展点、相关工作 |
| docs/policy.md | 问题、阈值、决策、失败规则 |
| docs/upstream-compatibility.md | 已验证版本、接口、限制 |
| docs/evaluation.md | 模拟 vs 实时、数据集、报告 |
| docs/skills.md | 内置 TypeSafe 技能及其路由 |
| docs/roadmap.md | 诚实的现状和限制 |
| docs/publishing.md | 手动发布运行手册（无发布自动化） |
| docs/benchmark.md | 使用/不使用 Jev 的实测对比、方法与局限 |

开发

pnpm install          # 工作区安装
pnpm build            # 对两个包执行 tsc
pnpm test             # 147 个测试（85 个核心 + 62 个 DSH）
pnpm calibrate        # 对 25 个决策夹具进行阈值扫描（mock；带密钥时使用 --live）
pnpm bench:compare    # 使用/不使用 Jev：真实循环、脚本化模型，无需密钥
pnpm bench:cli        # CLI A/B 运行测试框架（需要兼容 OpenAI 的网关）
pnpm evals            # 25 个 mock 评估夹具以及本地部署支持集
pnpm verify           # install → build → typecheck → tests → evals → examples → packaging

AGENTS.md 保存永久项目规则（固定依赖、无隐式密钥、
单调决策、无发布自动化）。

许可证

MIT