# dsh-typesafe-ask

[English](README.md) | 中文

给 DeepSeek Harness 里的 agent 装一个**决策外部大脑**：`typesafe_ask` 调用
[TypeSafe](https://typesafe.ai) 的 **Jev** —— 一个 System One 模型，输入一段状态 + 若干
**typed questions**，返回结构化答案（从选项里选一个 / 按量规打分 / 判断真假），并附带校准过的概率。

当你需要的是**判断**而不是一段话时用它：把请求路由给对的处理器、给工单分类、判断有多紧急或多愤怒、
给候选排序、或者把某个动作卡在置信度阈值后面。

## 它给你什么

| 界面 | 作用 |
| --- | --- |
| 工具 `typesafe_ask` | 把 `state` + typed questions 发到 `POST /v1/systemone`，答案直接回到对话里 |
| 设置页 | **设置 → TypeSafe / Jev** —— 粘一次 API Key；它存在 harness 凭据库里，**不会**出现在任何 profile 配置文件里 |

## 安装

插件市场里装：**设置 → 插件市场 → 搜 `typesafe-ask` → 安装**。或者手动：

```sh
dsh plugin --profile <你的profile> add dsh-typesafe-ask
```

重启或刷新后打开 **设置 → TypeSafe / Jev**，把
[console.typesafe.ai/keys](https://console.typesafe.ai/keys) 里的 key 粘进去。

## 用法

设好 key 之后，直接用自然语言让 agent 判断（「这个工单该谁处理？」），或者让它自己调工具。工具参数：

| 参数 | 类型 | 必填 | 含义 |
| --- | --- | --- | --- |
| `state` | string \| object \| array | 是 | 要评估的内容：文本、记录或应用状态 |
| `questions` | object | 是 | 问题 id → typed question 的映射（见下） |
| `model` | string | 否 | 默认 `jev-latest` |

三种问题类型：

```jsonc
{
  "department": {                     // choice —— 从选项里选一个
    "type": "choice",
    "instructions": "Which team should handle this",
    "criteria": {
      "billing": "Payment or subscription issues",
      "technical": "Bugs or integration problems",
      "sales": "Pricing or account questions"
    }
  },
  "frustration": {                    // score —— 在有序量规上打分
    "type": "score",
    "instructions": "How frustrated the customer appears",
    "criteria": ["Calm, just stating facts", "Frustrated but civil", "Very angry, strong language"]
  },
  "is_urgent": {                      // noul —— 这句话为真的概率
    "type": "noul",
    "instructions": "The message conveys urgency or time-sensitivity"
  }
}
```

返回按你给的问题 id 对应：

```
department: choice=technical (confidence=0.78) [technical=0.85, billing=0.15, sales=0]
frustration: score=1=Frustrated but civil (confidence=1)
is_urgent: noul=0.99
```

## 怎么问才对

- **互不依赖的问题一次问完**：同一次请求里的问题对同一份 state **并行**执行，彼此看不到对方的答案。
  只有「需要上一个答案去取证据/构造新选项」时才发第二次。
- **一个问题只问一个窄而完整的判断**。独立维度拆开；问题 id 不发给模型，完整含义必须写在 `instructions` 里。
- **`noul` 没有独立 confidence**。多个标签可能同时成立时，逐标签各问一个 `noul`，别硬塞进 `choice`。
- **`score` 的每一级要能独立成立**，是具体情形而不是「低/中/高」。返回的 `score` 是概率加权位置，可以是小数。
- **confidence 低 = 选项本身有重叠**，不是模型坏了。应该回去把 `criteria` 改得更互斥，而不是降阈值硬压。
- **阈值属于你的数据**：在真实样本上校准；`noul ≈ 0.5` 表示是非各半，不是「强度中等」。

## 配置

需要改默认值时，在 profile 的插件行里配：

```yaml
- id: dsh-typesafe-ask
  name: 'dsh-typesafe-ask'
  config:
    apiKeyRef: TYPESAFE_API_KEY                          # 凭据引用名
    model: jev-latest
    baseUrl: https://api.typesafe.ai/v1/systemone
    timeoutMs: 60000
```

## 边界

- Jev **不生成文本、不写代码、不流式、不调工具**，所以它不能替代 agent 背后的对话模型 ——
  官方文档 [Jev with coding agents](https://docs.typesafe.ai/introduction/coding-agents.md) 写得很明确。
- API Key 是服务端密钥：只存在凭据库里，且只在真正发起工具调用时由 host 读取。
- 需要能访问 `api.typesafe.ai`。

## 许可证

MIT