dsh-jev：DeepSeek Harness 的 TypeSafe Jev 结构化数据工具

前言¶

DeepSeek Harness (DSH) 允许开发者通过插件扩展智能体能力。在某些场景下，需要 Agent 输出结构化的评分、选择或概率，而非自由文本。dsh-jev 是一个 DSH bundle，它在 profile 中注册了 jev_ask 工具，使 DSH Agent 能够将类型化的 noul、choice 和 score 问题发送给 TypeSafe 的 Jev 模型。

功能定位¶

该插件的核心作用是桥接 DSH 与 TypeSafe Jev 系统。它不生成常规的聊天或代码，而是专注于返回结构化的 JSON 数据。一个调用请求可以混合多种问题类型，Agent 决定何时调用该工具。

环境要求¶

在安装和使用前，需确保环境满足以下条件：
* DSH 版本：必须使用 DSH 0.1.5-rc.2（npm next dist-tag）。
* Node 版本：Node.js 22.19 或更高版本（22.x 系列），或 Node.js 24 及更高版本。
* API Key：需要有效的 TypeSafe API Key。可通过环境变量 TYPESAFE_API_KEY 设置，或存储在 DSH 凭据中。

安装与配置¶

安装时建议固定 Commit SHA 以确保可重现性。

dsh plugin --profile web add github:noetion/dsh-jev#<commit>

首次安装时，pnpm 可能会拒绝运行 prepare 脚本。此时需在 profile 目录下的 pnpm-workspace.yaml 中添加 allowBuilds 字段。通常直接使用 dsh-jev，但某些版本的 pnpm 会打印完整路径如 dsh-jev@github:...，请使用报错中提示的字符串。

allowBuilds:
  dsh-jev: true

添加后，重新执行安装命令即可。

配置选项¶

插件支持通过 cordis.yml 配置与 TypeSafe Jev 的连接。可选字段包括：

model：默认为 jev-latest。
endpoint：默认为 https://api.typesafe.ai/v1/systemone。
apiKeyEnv：默认为 TYPESAFE_API_KEY。

插件在每次调用时读取 Key，不会将其写入配置文件中。

使用方式¶

Agent 可以被指令调用 jev_ask 工具，或者直接调用捆绑的 jev skill。以下是一个混合调用 noul 和 choice 类型的示例：

{
  "state": "Help! My payouts have been failing for 3 days.",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    },
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Jev 返回的 JSON 结果中：
* noul 类型的答案携带 noul 字段（通常为概率）。
* choice 或 score 类型的答案携带 probabilities 和 confidence。

注意事项¶

非 LLM 适配器：Jev 不支持流式输出，它返回的是结构化答案而非聊天流，因此该插件不属于传统的 LLM 适配器。
版本锁定：@deepseek-ai/dsh-tools 依赖被锁定在 0.1.5-rc.2，npm latest 版本过旧，不可替换。
许可证与支持：采用 MIT 许可证。作者不承诺响应时间，建议通过 GitHub Issue 提问或提交包含 pnpm run check 的 PR。
安全：不要在 state 字段中包含密钥或敏感信息。