dsh-jev-decide 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nanami-0713
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# dsh-jev-decide
+
+把 [TypeSafe Jev](https://docs.typesafe.ai/)（"System One" 决策模型）接入 DSH：注册一个 agent 工具 **`jev_decide`**，让 agent 在需要"快而准的判断"时调用 Jev，而不是让对话模型凭感觉猜。
+
+## 为什么不是"再加一个对话模型"
+
+Jev 不生成文本。它对输入 `state` 回答类型化问题并返回**校准过的概率**：
+
+| type | 问法 | 返回 |
+| --- | --- | --- |
+| `noul` | 是/否问题 | `answer` = 是的概率 0..1 |
+| `choice` | 从选项里挑一个（需 `options` ≥2） | `answer` = 选中项 + `probabilities` 全分布 + `confidence` |
+| `score` | 按有序等级打分（需 `levels` ≥2） | `answer` = 概率加权分值 + 分布 + `confidence` |
+
+适合：消息紧急度分级、意图路由、guardrail 检查、二选一决策、按 rubric 打分。不适合：写代码、写文案、任何需要生成文本的活。
+
+## 工具签名
+
+```
+jev_decide({
+  state: string,            // 必填，要评估的内容（纯文本）
+  question: string,         // 必填，要做的判断
+  type?: 'noul' | 'choice' | 'score',   // 默认 noul
+  options?: string[],       // type=choice 时必填（≥2）
+  levels?: string[],        // type=score 时必填（≥2，从低到高）
+  model?: string,           // 默认 jev-latest（当前 jev-1.13.0）
+}) → { model, type, answer, confidence?, probabilities?, usage }
+```
+
+## 凭证解析顺序
+
+1. 插件配置的 `apiKey`（cordis patch config 或数据目录 config.json）
+2. 环境变量 `TYPESAFE_API_KEY`
+3. `~/.dsh/.credentials.yaml` 的 `refs.TYPESAFE_AI_API_KEY`（与 DSH 凭证缝同源——本机已配置，无需重复）
+
+## 配置
+
+数据目录 `$DSH_HOME/plugins/dsh-jev-decide/config.json`（或 cordis patch 的 `config:`）：
+
+```json
+{ "model": "jev-latest", "timeoutMs": 15000, "baseUrl": "https://api.typesafe.ai/v1" }
+```
+
+## 安装/接线
+
+**插件市场（npm 上架后）**：
+
+```sh
+dsh plugin --profile web add dsh-jev-decide
+```
+
+**手动接线（本机已完成的步骤）**：
+
+1. 源码：`~/dsh/plugins/dsh-jev-decide/`
+2. `~/.dsh/profiles/web/package.json` 依赖：`"dsh-jev-decide": "link:~/dsh/plugins/dsh-jev-decide"`
+3. `~/.dsh/profiles/web/cordis.patch.yml`：`- insert: [- id: dsh-jev-decide, name: dsh-jev-decide]`
+4. 因无 shell 无法建 pnpm symlink，`profiles/web/node_modules/dsh-jev-decide/` 放的是实体副本；下次 `pnpm install` 会把它规范成 link，无副作用。
+5. **生效需重启 DSH**（host 插件在进程启动时装配）。
+
+## 生态扫描：同类项目（2026-09-19）
+
+Jev 发布三天内 GitHub 上已出现多个 DSH 接入实现，各有侧重：
+
+| 项目 | 特点 |
+| --- | --- |
+| [noetion/dsh-jev](https://github.com/noetion/dsh-jev) | `jev_ask` 工具，**一次 state 可混搭多问题**；bundle + 内置 skill；配套 mock 传输测试，工程最完整 |
+| [kaijia323/dsh-plugin-jev](https://github.com/kaijia323/dsh-plugin-jev) | 同名 `jev_decide`；**双传输**（官方 API + Vercel AI Gateway）；指数退避重试、state/问题数上限守卫、置信度阈值路由示例 |
+| [buberlo/dsh-jev](https://github.com/buberlo/dsh-jev) | 决策层封装 |
+| [zhangxaochen/dsh-jev](https://github.com/zhangxaochen/dsh-jev) | 插件套件 |
+
+本插件的差异点：
+
+- **单文件、零构建**（纯 ESM JS），copy 即用，没有 TypeScript 工具链依赖
+- **凭证零配置**：直接复用 DSH 凭证缝（`~/.dsh/.credentials.yaml` 的 `TYPESAFE_AI_API_KEY`），不要求 env 也不在 patch 里落明文
+- 内建 429/529 官方建议的短退避重试
+- 只做一件事：把 `jev_decide` 注册进工具集；多问题、双网关等进阶需求请用上面的项目
+
+## 定价参考
+
+Jev 1.13：$0.042/百万输入 token，输出免费；官方限流 250k tok/s、1200 req/min（[模型页](https://docs.typesafe.ai/models)）。

package/lib/index.js

@@ -0,0 +1,262 @@
+/**
+ * dsh-jev-decide — 把 TypeSafe Jev（System One 决策模型）接入 DSH 的 agent 工具集。
+ *
+ * Jev 不生成文本：它对 `state` 回答类型化问题并返回校准过的概率
+ * （noul=是/否概率，choice=选项+分布，score=有序评分+分布）。
+ * 本插件把它注册为一个 agent 工具 `jev_decide`，适用于：
+ * 路由、分类、紧急度分级、guardrail 检查等"快而准的判断"场景，
+ * 而不是让对话模型凭感觉猜。
+ *
+ * API: POST {baseUrl}/systemone（官方文档 https://docs.typesafe.ai/api）
+ *   - 401/422/429/529 语义见文档；429/529 做一次短退避重试。
+ *
+ * 凭证解析顺序（第一个非空者生效）：
+ *   1. cordis patch / 插件 config 的 `apiKey` 字段
+ *   2. 环境变量 TYPESAFE_API_KEY
+ *   3. ~/.dsh/.credentials.yaml refs.TYPESAFE_AI_API_KEY（与 DSH 凭证缝同源，避免明文双份）
+ *
+ * 配置（cordis patch 的 config 或 $DSH_HOME/plugins/dsh-jev-decide/config.json）：
+ *   baseUrl   默认 https://api.typesafe.ai/v1
+ *   model     默认 jev-latest
+ *   timeoutMs 默认 15000
+ *   apiKey    可选，见上方解析顺序
+ */
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+
+export const name = 'dsh-jev-decide';
+export const inject = ['tools'];
+
+const DEFAULTS = Object.freeze({
+	baseUrl: 'https://api.typesafe.ai/v1',
+	model: 'jev-latest',
+	timeoutMs: 15000,
+});
+
+//#region ── 纯函数（导出仅为可测性）────────────────────────────────
+
+/** 依据工具入参构造一个 TypeSafe question 对象。校验失败抛 Error。 */
+export function buildQuestion(args) {
+	const type = args.type ?? 'noul';
+	switch (type) {
+		case 'noul':
+			return { type, instructions: args.question };
+		case 'choice': {
+			if (!Array.isArray(args.options) || args.options.length < 2) {
+				throw new Error('jev_decide: type=choice 需要 options（≥2 个选项字符串）');
+			}
+			const criteria = {};
+			for (const option of args.options) criteria[option] = null;
+			return { type, instructions: args.question, criteria };
+		}
+		case 'score': {
+			if (!Array.isArray(args.levels) || args.levels.length < 2) {
+				throw new Error('jev_decide: type=score 需要 levels（≥2 个有序等级描述）');
+			}
+			return { type, instructions: args.question, criteria: [...args.levels] };
+		}
+		default:
+			throw new Error(`jev_decide: 未知 question 类型 ${JSON.stringify(type)}（应为 noul/choice/score）`);
+	}
+}
+
+/** 构造 /v1/systemone 请求体。 */
+export function buildPayload(args, model) {
+	if (typeof args.state !== 'string' || args.state.length === 0) {
+		throw new Error('jev_decide: state 不能为空');
+	}
+	if (typeof args.question !== 'string' || args.question.length === 0) {
+		throw new Error('jev_decide: question 不能为空');
+	}
+	return {
+		model,
+		state: args.state,
+		questions: { decision: buildQuestion(args) },
+	};
+}
+
+/** 把 /v1/systemone 响应压缩成工具输出（answers.decision + usage）。 */
+export function summarize(response) {
+	const answer = response?.answers?.decision;
+	if (answer === undefined || answer === null) {
+		throw new Error(`jev_decide: 响应缺少 answers.decision：${JSON.stringify(response).slice(0, 300)}`);
+	}
+	const type = answer.type;
+	const output = {
+		model: typeof response.model === 'string' ? response.model : 'unknown',
+		type,
+		answer: type === 'noul' ? answer.noul
+			: type === 'choice' ? answer.choice
+			: type === 'score' ? answer.score
+			: answer,
+	};
+	if (typeof answer.confidence === 'number') output.confidence = answer.confidence;
+	if (answer.probabilities !== undefined && answer.probabilities !== null) {
+		output.probabilities = { ...answer.probabilities };
+	}
+	if (response.usage !== undefined && response.usage !== null) {
+		output.usage = {
+			input_tokens: response.usage.input_tokens ?? 0,
+			output_tokens: response.usage.output_tokens ?? 0,
+		};
+	}
+	return output;
+}
+
+//#endregion
+
+//#region ── 凭证与配置 ────────────────────────────────────────────
+
+function dshHome() {
+	return process.env.DSH_HOME || join(homedir(), '.dsh');
+}
+
+/** 极简读取 ~/.dsh/.credentials.yaml refs 里的一行引用（避免引入 YAML 依赖）。 */
+async function readCredentialRef(ref) {
+	try {
+		const raw = await readFile(join(dshHome(), '.credentials.yaml'), 'utf8');
+		const inRefs = /^refs:\s*$/m.test(raw);
+		if (!inRefs) return undefined;
+		for (const line of raw.split('\n')) {
+			const match = new RegExp(`^\\s{2}${ref}:\\s*(.+?)\\s*$`).exec(line);
+			if (match) return match[1];
+		}
+	} catch {
+		/* 文件不存在/不可读 → 视为未配置 */
+	}
+	return undefined;
+}
+
+async function loadPluginFileConfig() {
+	try {
+		const raw = await readFile(join(dshHome(), 'plugins', name, 'config.json'), 'utf8');
+		return JSON.parse(raw);
+	} catch {
+		return {};
+	}
+}
+
+async function resolveKey(config) {
+	if (typeof config.apiKey === 'string' && config.apiKey.length > 0) return config.apiKey;
+	if (typeof process.env.TYPESAFE_API_KEY === 'string' && process.env.TYPESAFE_API_KEY.length > 0) {
+		return process.env.TYPESAFE_API_KEY;
+	}
+	return readCredentialRef('TYPESAFE_AI_API_KEY');
+}
+
+//#endregion
+
+export async function apply(ctx, config = {}) {
+	const fileConfig = await loadPluginFileConfig();
+	const cfg = {
+		...DEFAULTS,
+		...fileConfig,
+		...config,
+	};
+
+	ctx.tools.register(defineTool({
+		name: 'jev_decide',
+		description: [
+			'Ask the TypeSafe Jev "System One" decision model a typed question about a state and get a calibrated, structured answer (NOT a chat/text model).',
+			'Use for fast decisions: urgency classification, intent routing, guardrails, ranking between options, scoring against a rubric.',
+			'type=noul → yes/no probability; type=choice → pick one option (requires options) and returns the full distribution; type=score → rating on ordered levels (requires levels, ≥2).',
+		].join(' '),
+		parameters: {
+			state: {
+				type: 'string',
+				required: true,
+				description: 'The content to evaluate: a message, an email, a log line, a short document… (text only)',
+			},
+			question: {
+				type: 'string',
+				required: true,
+				description: 'The decision to make, e.g. "Does this message convey urgency?" or "Which team should handle this?"',
+			},
+			type: {
+				type: 'string',
+				enum: ['noul', 'choice', 'score'],
+				description: 'Question type. Defaults to noul (yes/no probability).',
+			},
+			options: {
+				type: 'array',
+				description: 'For type=choice: the option labels (≥2), e.g. ["billing", "technical", "sales"].',
+				items: { type: 'string' },
+			},
+			levels: {
+				type: 'array',
+				description: 'For type=score: ordered level descriptions from low to high (≥2), e.g. ["Calm", "Frustrated", "Very angry"].',
+				items: { type: 'string' },
+			},
+			model: {
+				type: 'string',
+				description: 'TypeSafe model id. Defaults to jev-latest (currently jev-1.13.0).',
+			},
+		},
+		output: {
+			schema: {
+				type: 'object',
+				additionalProperties: false,
+				properties: {
+					model: { type: 'string', required: true },
+					type: { type: 'string', required: true },
+					answer: {
+						required: true,
+						oneOf: [
+							{ type: 'number', description: 'noul → yes-probability 0..1; score → probability-weighted level value' },
+							{ type: 'string', description: 'choice → the chosen option label' },
+						],
+					},
+					confidence: { type: 'number' },
+					probabilities: { type: 'object', additionalProperties: true },
+					usage: {
+						type: 'object',
+						additionalProperties: false,
+						properties: {
+							input_tokens: { type: 'integer' },
+							output_tokens: { type: 'integer' },
+						},
+					},
+				},
+			},
+			render: (_args, value) => [{
+				type: 'text',
+				text: JSON.stringify(value),
+			}],
+		},
+		timeoutMs: cfg.timeoutMs + 5000,
+		async execute(args, exec) {
+			const apiKey = await resolveKey(cfg);
+			if (!apiKey) {
+				throw new Error('jev_decide: 未找到 Typesafe API key（按序检查：插件 config.apiKey → 环境变量 TYPESAFE_API_KEY → ~/.dsh/.credentials.yaml refs.TYPESAFE_AI_API_KEY）');
+			}
+			const payload = buildPayload(args, typeof args.model === 'string' && args.model.length > 0 ? args.model : cfg.model);
+			const url = `${cfg.baseUrl.replace(/\/+$/, '')}/systemone`;
+
+			// 429/529 官方建议退避重试：这里做一次 1s 短退避，共最多 2 次尝试。
+			let response;
+			for (let attempt = 0; ; attempt++) {
+				response = await fetch(url, {
+					method: 'POST',
+					headers: {
+						authorization: `Bearer ${apiKey}`,
+						'content-type': 'application/json',
+					},
+					body: JSON.stringify(payload),
+					signal: exec.signal,
+				});
+				if ((response.status === 429 || response.status === 529) && attempt === 0) {
+					await new Promise((resolve) => setTimeout(resolve, 1000));
+					continue;
+				}
+				break;
+			}
+			if (!response.ok) {
+				const body = (await response.text()).slice(0, 300);
+				throw new Error(`jev_decide: Typesafe API HTTP ${response.status}: ${body}`);
+			}
+			return summarize(await response.json());
+		},
+	}));
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "dsh-jev-decide",
+  "version": "0.1.0",
+  "description": "DSH 插件：把 TypeSafe Jev（System One 决策模型）注册为 agent 工具 jev_decide。调用 https://api.typesafe.ai/v1/systemone，让 agent 在路由/分级/guardrail 等场景拿到带校准概率的结构化判定（noul/choice/score），而不是让大模型瞎猜。",
+  "private": false,
+  "type": "module",
+  "main": "./lib/index.js",
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "typesafe",
+    "jev",
+    "system-one",
+    "decision"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nanami-0713/dsh-jev-decide.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nanami-0713/dsh-jev-decide/issues"
+  },
+  "homepage": "https://github.com/nanami-0713/dsh-jev-decide#readme"
+}