# dsh-system1
**为 DeepSeek Harness 插件提供类型安全的 System One 判断服务。** 消费插件调用 `ctx.system1.decide()`，解释返回结果并自行决定后续动作。
[](https://github.com/exoticknight/dsh-system1/actions/workflows/check.yml) [](https://www.npmjs.com/package/dsh-system1) [](LICENSE) [](https://github.com/exoticknight/red)
[](https://dsh.pub/en/plugins/?q=exoticknight%2Fdsh-system1)
简体中文 | [English](README.md)
| 原语 | 返回结果 |
| -------- | ----------------------------------- |
| `noul` | 命题为真的概率（`probabilityTrue`） |
| `choice` | 候选键和完整概率分布 |
| `score` | 从 0 开始的期望等级和概率分布 |
| `box` | 对象在图片中的归一化边界坐标 |
服务提供请求与响应校验、逐题结果、取消、超时、provider 注册和执行元数据。TypeSafe/Jev 和 Cloudflare Clef 支持统一的图片附件；Jev 1.14 还支持 box 判断和可选的扩展上下文。其他后端可实现公开的 provider 契约。
## 从 npm 安装
在使用 System One 的项目中安装本包：
```sh
npm install dsh-system1
```
如需在 dsh 中启用随包提供的服务和 provider，请将 npm 包添加到实际运行的 profile。把 `` 替换为你的 profile 名称：
```sh
dsh plugin --profile add dsh-system1
```
`dsh plugin` 命令必须指定 profile；安装到一个 profile 不会在其他 profile 中启用该插件。如需从 GitHub 仓库安装，在上述命令中把 `dsh-system1` 替换为 `github:exoticknight/dsh-system1`。
随包提供的 patch 会挂载服务及内置 provider。默认模型为 `jev-latest`、provider id 为 `typesafe`，每次模型尝试的默认超时为 800 ms。可在插件设置页选择默认服务和模型，并按顺序添加备用模型；在对应服务组件中填写连接参数，将密钥保存到 DSH 凭据存储，也可在启动前配置对应环境变量。每个备用模型都会获得完整超时预算，因此总耗时可随链长增加。根据后端延迟调整 `timeoutMs`，本地 CPU 推理通常需要更长预算。
Cloudflare 使用 `cloudflare` provider 的 `clef`、`clef-flash` 或 `clef-omni`。配置步骤见[模型服务配置](docs/providers.md)。
## Agent 工具
安装后 agent 可以直接使用 `system1_decide` 工具，无需编写消费插件。主模型可以把是否判断、分类和打分交给 System One，再根据返回的概率决定下一步。该工具使用上面配置的默认服务和模型。
此功能由 bundle 中的 `system1-tool` 组件提供，默认开启。在插件页关闭该组件即可移除工具；headless profile 中可在对应条目上设置 `disabled: true`。参数和返回值见 [API 文档](docs/api.md#agent-工具)。
## 消费插件调用
在消费插件项目中使用上面的 npm 命令安装本包，然后声明 `inject: ['system1']`，并导入本包提供的 Cordis 类型扩展：
```ts
import type { Context } from '@deepseek-ai/cordis'
import type {} from 'dsh-system1'
export const inject = ['system1']
export async function apply(ctx: Context) {
const result = await ctx.system1.decide({
state: '用户询问退款进度。',
questions: {
refund: { type: 'noul', instructions: '用户是否在询问退款？' },
topic: {
type: 'choice',
instructions: '选择主题。',
criteria: { billing: '账单问题', technical: '技术支持' },
},
urgency: {
type: 'score',
instructions: '判断紧急程度。',
criteria: ['一般', '紧急', '非常紧急'],
},
},
})
if (result.answers.topic.status === 'ok') {
return result.answers.topic.answer.value // 'billing' | 'technical'
}
return result.answers.topic.error
}
```
`noul` 返回 `probabilityTrue`；`choice` 返回候选键及完整分布；`score` 返回期望等级和按 `criteria` 排列的概率；`box` 返回归一化图片边界。它们都是模型输出，阈值和后续动作由消费插件决定。运行故障通过逐题 `status: 'error'` 返回；调用结构无效时抛出 `System1InputError`。
完整契约见 [API 与 provider 开发](docs/api.md)，调用示例见[消费插件示例](examples/consumer.ts)。TypeSafe 支持 `jev-latest`、`jev-preview`、`jev-1.14.0` 和 `jev-1.13.0`；其他服务的模型与限制见[模型服务配置](docs/providers.md)。
## 开发
使用 `package.json` 中声明的 Node.js 和 pnpm 版本：
```sh
pnpm install --frozen-lockfile
pnpm verify
```
`pnpm test` 使用本地 fixture 运行插件和 provider 测试，与 CI 相同；`pnpm test ` 只运行其中一部分。真实模型探针 `pnpm probe ` 读取 `.env.local` 中的凭据，本地 target 首次运行时自动准备服务，见[测试与真实模型验证](docs/testing.md)。
更多内容见[贡献指南](CONTRIBUTING.zh-CN.md)和[发布流程](docs/releasing.md)。
## 许可证
本项目采用 [Apache License 2.0](LICENSE)。