jackie-cqz/dsh-jev-plugin

dsh-jev-plugin

一个让 DeepSeek Harness (DSH) 智能体使用 TypeSafe Jev (System One) 进行类型化决策的插件。

Jev 返回的是结构化判断，而非对话式文本。本插件将其三个原语暴露为工具：

| 原语 | 用途 | 结果 |
|---|---|---|
| noul | 是/否判断 | 0 到 1 之间的概率 |
| choice | 选择一个标签 | 所选标签、概率分布、置信度 |
| score | 在有序量表上评分 | 分数、概率分布、置信度 |

状态

- 版本：0.1.0（准备发布中）。
- 目标 DSH：0.1.6-alpha.2。声明范围：>=0.1.6-alpha.2 =22 |

构建和测试依赖已锁定在 package-lock.json 中。CI 已针对 Node 22 和 24 配置；本地发布检查已在 Node 24 上通过。

开发依赖

@deepseek-ai/dsh-tools@0.1.6-alpha.2 除 Cordis 外还声明了以下对等依赖：dsh-agent、dsh-invariants、dsh-llm、dsh-ptc-runtime、dsh-sandbox、dsh-sandbox-policy、dsh-scope、dsh-session、dsh-system-prompt 和 dsh-user-approval（均位于 @deepseek-ai/ 下）。由于 --legacy-peer-deps 不会自动安装对等依赖，因此它们在此被列为显式开发依赖。目标配置文件会在运行时提供它们。

TLS 故障排查

如果在 curl 能成功连接的情况下，Node 在 TLS 握手期间超时，可尝试使用 --tls-max-v1.2 作为诊断手段。如果你的环境需要，请对运行 DSH 的 Node 进程应用相同的选项。参见下方的开发部分。

安装

对于本地检出，请先在插件目录中运行 npm ci --legacy-peer-deps，然后将下面的示例路径替换为其实际位置：

dsh --profile jev-dev --from-default-profile web --dump-config
dsh plugin --profile jev-dev add /path/to/dsh-jev-plugin
dsh --profile jev-dev --dump-config   # Look for tool-jev
dsh --profile jev-dev

第一条命令会初始化一个新的 Web 配置文件；对于未使用过的配置文件名称，只需运行一次。在未选择 Web 模板的情况下将插件添加到新名称会创建一个仅含基础内容的配置文件。如果你的配置文件已存在，请省略初始化步骤。

从 GitHub 安装（将  替换为所需的修订版本；先按上述步骤初始化 Web 配置文件）：

dsh plugin --profile jev-dev add github:jackie-cqz/dsh-jev-plugin#
Git 安装会使用包的 prepare 脚本（npm run build）来构建产物。如果 pnpm 阻止了构建脚本，请按照其提示将该包添加到配置文件的 pnpm-workspace.yaml 中的 allowBuilds，然后重试。

配置

| 字段 | 默认值 | 描述 |
|---|---|---|
| apiKey | — | TypeSafe API 密钥；优先于 apiKeyEnv |
| apiKeyEnv | TYPESAFE_API_KEY | 当 apiKey 未设置时使用的环境变量 |
| baseURL | https://api.typesafe.ai/v1 | API 根地址；末尾斜杠会被移除 |
| model | jev-latest | 默认模型；工具可在每次调用时覆盖它 |
| timeoutMs | 10000 | 调用超时时间（毫秒） |
| retry.maxAttempts | 3 | 最大尝试次数，包括第一次 |
| retry.baseDelayMs | 500 | 初始退避时间（毫秒） |
| retry.maxDelayMs | 5000 | 尝试之间的最大延迟 |
| maxStateChars | 64000 | 最大序列化状态长度；0 表示禁用限制 |
| confidence.approveAt | 0.8 | 通过 verdictFor 自动接受所需的置信度阈值 |
| confidence.escalateBelow | 0.5 | 低于此置信度时升级；不得超过 approveAt |
| policy.enabled | false | 启用熔断器和最小调用间隔 |
| policy.failureThreshold | 5 | 打开熔断器前允许的连续失败次数 |
| policy.openMs | 30000 | 允许探测调用前的等待时间 |
| policy.minIntervalMs | 200 | 调用之间的最小间隔 |
| cache.enabled | false | 为相同的模型、状态和问题缓存响应 |
| cache.maxEntries | 100 | 最大缓存条目数；采用 LRU 淘汰 |
| cache.ttlMs | 60000 | 缓存条目生存时间 |
| guard.enabled | false | 启用 tools/pre-execute 风险门控 |
| guard.tools | [] | 要检查的工具；为空表示所有工具 |
| guard.question | 内置风险问题 | 提交给 Jev 的问题 |
| guard.levels | ["low","medium","high","critical"] | 有序风险标签；2–10 个条目 |
| guard.denyAt | 3 | 达到或超过此分数时拒绝 |
| guard.askAt | 1 | 达到或超过此分数时请求批准 |
| guard.escalateOnLowConfidence | true | 低于 confidence.escalateBelow 时请求批准 |
| guard.reviseAt | 最高级别索引 | 以修订指导拒绝；默认等于 denyAt，不留下修订区间 |
| guard.onError | "allow" | 门控失败行为：故障开放（allow）或故障关闭（deny） |
| rules.enabled | false | 启用同步离线拒绝规则；无需 API 密钥 |
| rules.tools | [] | 要检查的工具；为空表示所有工具 |
| rules.deny | [] | 额外的不区分大小写的拒绝正则表达式；无效模式在加载时失败 |
| review.enabled | false | 启用 tools/post-execute 审查；可能重写已完成的工具结果 |
| review.blockAt / review.onError | 0.8 / "accept" | 修正概率阈值和错误行为 |
| routing.enabled | false | 使用请求复杂度和 routing.models 在 agent/request 上路由模型 |
| context.enabled | false | 在 agent/pre-step 上启用上下文修剪 |
| context.maxDrops / context.shadow | 0 / false | 丢弃上限（0 表示无限制）；影子模式仅报告而不更改上下文 |
| intent.enabled | false | 决策逻辑存在，但指令注入未连接；启用此项不会注入消息 |
| quotaCooldownMs | 900000 | 402 后的冷却时间，独立于 policy.enabled；0 表示禁用 |
| enableDecide / enableEvaluate | true | 注册相应的工具 |
| telemetry.log | false | 为每次调用发出经过脱敏处理的结构化记录 |
| telemetry.sampleRate | 1 | 采样比例，从 0 到 1 |
| telemetry.errorRateAlert | 0.5 | 判定健康状态降级的错误率阈值 |
| telemetry.alertMinCalls | 10 | 报告健康状态前的最小样本量 |

请根据你的工作负载验证门控阈值：分数和置信度可能会有所不同。更改 guard.levels 会将默认阈值限制到范围内；显式配置的超出范围的值将无法通过验证。在允许上下文修剪移除消息之前，请先以影子模式启动它。

过大的状态会被拒绝，绝不会被截断，因此决策不会静默地使用不完整的输入。策略、缓存和风险门控默认处于禁用状态。意图注入仍不可用，因为宿主缺少一个记录插件作者身份的前置步骤消息通道。

优先使用环境变量，而不是将密钥存储在 cordis.patch.yml 中：

export TYPESAFE_API_KEY="..."

PowerShell：

$env:TYPESAFE_API_KEY = "..."

如果要将密钥存储在配置中，请使用 secret 角色并限制文件权限。该插件会从工具输出、错误消息和日志中隐藏 API 密钥。

工具

jev_decide

根据状态、问题、原语和可选标签做出单一决策。

| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| state | JSON | 是 | 要评估的字符串、普通对象或数组 |
| question | string | 是 | 向 Jev 提出的问题 |
| kind | noul / choice / score | 是 | 决策原语 |
| options | string[] | 否 | 选择标签（去重后 2–255 个）或有序分数标签（2–10 个） |
| model | string | 否 | 覆盖默认模型 |

state 会拒绝 null、数字和布尔值。示例响应：

{
"model": "jev-1.13.0",
"answer": {
"type": "choice",
"choice": "billing",
"probabilities": { "billing": 0.91, "technical": 0.08, "sales": 0.01 },
"confidence": 0.87
},
"usage": { "input_tokens": 320, "output_tokens": 34 }
}

jev_evaluate

传入 Jev 的原生 questions 映射，以在一次调用中回答多个问题，包括结构化指令和自定义标准。

| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| state | JSON | 是 | 与 jev_decide 接受相同的类型 |
| questions | JSON 对象 | 是 | 非空的原生 Jev 问题映射 |
| model | 字符串 | 否 | 覆盖默认模型 |

{
"state": "救命！我的付款已经连续失败 3 天了。",
"questions": {
"department": {
"type": "choice",
"instructions": "哪个团队应该处理这个问题？",
"criteria": { "billing": "支付问题", "technical": "缺陷", "sales": "定价" }
},
"is_urgent": { "type": "noul", "instructions": "这是否表达了紧迫性？" }
}
}

返回 { "model", "answers", "usage" }，并保留原始答案结构。插件会检查 questions 是否为非空对象；TypeSafe 会验证其更深层的结构。

使用 jev_decide 处理单个问题，使用 jev_evaluate 处理多个问题或自定义指令和标准。

输出契约

两个工具都要求响应信封中包含 model、answer（或 answers）和 usage。缺少字段会产生协议错误。

模型会收到一份可读的摘要，随后是完整的规范 JSON：

score: 2.99/3 = urgent (confidence=0.99)

{ "model": "jev-1.13.0", "answer": { ... }, "usage": { ... } }

摘要通过 legend 映射索引，并以百分比形式显示概率。如果某个答案无法被摘要，渲染会回退到规范 JSON，而不会丢失数据。

Web 结果卡片

该包包含 lib/client.js，由 DSH 模块加载器加载。它为两个工具注册结果卡片，显示决策标签、概率或分数，同时保留完整的 JSON 输出。不包含设置页面和输入工具栏开关。

错误

缺少键、无效参数、超时、取消、HTTP 错误和格式错误的响应都有对应的错误。402 会触发配额冷却；对于 401 / 403，请检查凭据和权限；对于 422，请检查请求参数。使用 /jev-status 检查配置、健康状况和冷却状态，而不会泄露密钥。

重试

- 默认最多尝试三次，包括第一次，采用指数退避和抖动，并由 retry.maxDelayMs 限制上限。
- 当存在 Retry-After 时，它优先，并受相同的延迟上限约束。
- 重试涵盖 429、529、500、502、503、504 以及瞬时网络故障。
- 401、403、422、验证失败和用户取消不会重试。
- 超时和调用方取消会限制执行。Jev 评估是只读的；重试不会重复写操作。

可选风险门控

默认禁用。启用后，门控会在 tools/pre-execute 上运行，要求 Jev 评估工具调用，并允许它、请求批准或拒绝它。

- id: tool-jev
config:
guard:
enabled: true
tools: ['run_shell', 'write_file']   # 空表示所有工具
denyAt: 3
askAt: 1
被评估的状态包含工具名称及其参数。常规的列表操作可能被允许；明确指示销毁生产数据的操作可能被拒绝。这些是模型判断，而非确定性保证。

- 除非启用，否则不会进行任何门控调用。
- 默认是故障开放（guard.onError: "allow"）：门控错误会让原始调用继续执行。使用 "deny" 实现故障关闭行为。
- 拒绝原因不包含参数内容。它们会报告工具、风险标签、评分、置信度和机器可读的错误代码；HTTP 失败会包含状态码，但不包含响应正文。

对于相同的输入，评分和置信度可能会有所不同，常规操作也可能触发审批。请在预期的工作流中验证阈值。

隐私： 启用门控会将工具名称和参数发送到 TypeSafe，并记录在 DSH 会话日志中。使用 guard.tools 来限制其范围。

可选的离线拒绝规则

独立于语义门控，这些同步文本规则使用 ctx.tools.guard()。它们不需要网络或 API 密钥，并且其拒绝无法被审批令牌覆盖。

- id: tool-jev
config:
rules:
enabled: true
tools: ['bash', 'run_shell']
deny: ['\bterraform\s+destroy\b']   # Add to the built-in rules

规则在语义门控之前注册，避免对已被离线拒绝的调用发起 Jev 请求。内置规则涵盖递归根目录删除、dd of=/dev/、mkfs、未受保护的强制推送、DROP/TRUNCATE、chmod -R 777 /、fork 炸弹、关机和重启。示例：

DENY   rm -rf /                    allow  rm -rf ./build
DENY   git push --force            allow  git push --force-with-lease
DENY   shutdown -h now             allow  echo reboot
DENY   dd if=/dev/zero of=/dev/sda
DENY   DROP TABLE users

这是一个事故预防层，而非安全边界。它匹配已知的文本模式，而不解释 shell 语义，也无法阻止通过变量、编码或间接脚本进行的故意规避。拒绝原因不会回显参数。

可观测性

ctx.jev.stats() 报告调用、失败、重试、令牌、延迟、模型、准入策略计数器和缓存计数器。ctx.jev.health() 返回 healthy、degraded 或 unknown；样本数少于 telemetry.alertMinCalls 时返回 unknown。

/jev-status 命令显示已启用的功能、阈值、模型和端点、密钥来源、调用和重试计数以及健康状态。其 Notes 部分会解释不活动的原因，例如门控被禁用、没有已检查的调用、采样、遥测接收器错误或缺少密钥。
启用 telemetry.log 后，每次采样调用（包括缓存命中）都会发出一个 channel: 'ops' 记录，其中仅包含结果、模型、时长、令牌数、重试次数、缓存标志和错误码。状态、工具参数、结果和密钥均被排除在遥测接口之外。记录使用宿主的 ctx.sessionTelemetry 后端；此插件不依赖 OpenTelemetry。没有后端时，它仅保留计数器而不导出记录。

jev-decisions 技能

随附的技能说明了何时使用这些工具、如何在它们之间进行选择，以及如何解读结果。从插件检出目录中，将其安装到在 ~/.agents/skills/ 下发现技能的宿主中：

cp -r skills/jev-decisions ~/.agents/skills/

该技能涵盖未校准的概率、从零开始的分数索引和 legend、低置信度、不合适的任务、遵守门控决策，以及状态会离开本机这一事实。此位置使该技能在兼容宿主中跨项目可用。

限制与安全

- 状态会发送到 TypeSafe，并可能出现在 DSH 会话日志中。避免不必要的机密数据。
- Jev 不是计算器或事实数据库。已知的薄弱领域包括精确计数、算术、日期、间接推理、双重否定，以及缺少相关状态的长上下文。非英语的准确率可能低于英语准确率。
- 不要仅依赖 Jev 来判断对抗性输入。
- 过大的状态会被拒绝，而不是被截断。
- 可选钩子和 Web 卡片已实现；钩子默认禁用。DSH 凭据/设置集成和意图指令注入不可用。

开发

发布检查

npm ci --legacy-peer-deps
npm run check:release

这会运行类型检查、测试、服务器和客户端构建、严格的打包检查，以及 tarball 安装冒烟测试。prepublishOnly 生命周期会在发布前运行相同的门控。

- npm run check:pack 需要先进行构建，并检查九个打包文件、入口点、bundle 补丁、非空产物、两个 README 及其语言链接，以及常见的私钥/令牌模式。模式扫描无法检测所有密钥格式。
- npm run check:install 从现有产物构建真实的 tarball，并在禁用生命周期脚本的情况下将其安装到 .release-smoke-* 中。使用目标 DSH 0.1.6-alpha.2 运行时和模拟 API，它检查调用、释放、客户端工厂和槽位注册。测试夹具保留以供检查，并被排除在 Git 和发布之外。
- 安装检查需要注册表访问权限，但不需要 TypeSafe 密钥。它们不能替代 DSH CLI 配置文件或浏览器验收测试。
- CI 已针对 Ubuntu/Windows 和 Node 22/24 配置。对于手动验收，请安装到单独的 DSH 配置文件中，启动 Web UI，调用所有三个 jev_decide 原语和多问题 jev_evaluate，并检查结果卡片。

本地验证

npm install --legacy-peer-deps
npm run typecheck
npm testsh
npm run build   # dist/index.js、dist/index.d.ts 和 lib/client.js

真实的 API 冒烟测试需要 TYPESAFE_API_KEY：
sh
TYPESAFE_API_KEY=... npm run smoke
TYPESAFE_API_KEY=... npm run cases
TYPESAFE_API_KEY=... npm run cases -- score

在 PowerShell 中，请先设置 $env:TYPESAFE_API_KEY，然后运行 npm 命令，不要使用内联赋值。

冒烟脚本通过真实的 DSH 工具注册表来测试构建后的插件：三个原语、多问题评估、对象/数组状态，以及缺失或无效的密钥。cases 脚本提供了 17 个场景用例，外加四个已知弱点的探测，分别针对计数、算术、日期比较和双重否定。它会检查响应结构，并在适用时检查黄金预期；弱点探测会被记录，但不会导致运行失败。

如果 Node 握手超时而 curl 成功，请尝试临时限制为 TLS 1.2：
sh
TYPESAFE_API_KEY=... node --tls-max-v1.2 scripts/smoke.mjs
TYPESAFE_API_KEY=... node --tls-max-v1.2 scripts/jev-cases.mjs

该插件通常使用平台的 TLS 默认值。只有在故障排查确认你的环境需要时，才将此选项应用于 DSH Node 进程。

参考资料

- TypeSafe 简介
- TypeSafe API
- Jev 模型局限性