jev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jev: decisions, not text

Jev：只做决策，不生成文本

One state, many typed questions, typed answers with real probability distributions. It cannot write — not a summary, not a line of code. It answers "which of these N?", "is this true?" and "how much, on this scale?".

Advisory, never an authorization boundary. Jev can be wrong, manipulated by content inside the state, or overconfident. Never map a returned label straight to an irreversible action without your own deterministic check.

一个状态，多个带类型的问题，返回带真实概率分布的类型化答案。它不会生成内容——既不能写摘要，也不能写一行代码。它只回答“这N个选项里选哪个？”、“是否成立？”以及“在这个尺度上得分多少？”。

仅作参考，绝不作为授权边界。 Jev可能出错，可能被状态内的内容操纵，也可能过度自信。在没有你自己的确定性校验的情况下，切勿将返回的标签直接映射到不可逆操作。

0. Is Jev the right tool?

0. Jev是合适的工具吗？

Decide this first: reaching for Jev out of novelty costs a round trip and returns nothing usable.

Signal	Verdict
You can enumerate the possible answers up front	Jev
The same judgement repeats over many items	Jev
The decision gates something expensive or risky	Jev
The data is large and mostly irrelevant	Jev (REDUCE, rule 3)
You need a sentence, summary or explanation	LLM
You need code	LLM
The answer set is open-ended ("find all possible…")	LLM
The answer needs step-by-step reasoning to be justified	LLM
You need to count, compare two states, or do date arithmetic	code, not either

Free check, no API call:

jevskill plan "<problem>"

names the pattern, the layers and the expected call count. A real decision costs about $0.000013.

请先确认这一点：出于新奇感使用Jev只会浪费一次往返调用，得不到任何有用的结果。

判断依据	结论
你可以预先枚举所有可能的答案	Jev
同一判断需要在多个条目上重复执行	Jev
该决策是高成本或高风险操作的门控	Jev
数据量庞大且大部分无关	Jev（REDUCE，规则3）
你需要生成句子、摘要或解释	LLM
你需要生成代码	LLM
答案集是开放式的（“找出所有可能的…”）	LLM
答案需要逐步推理才能验证合理性	LLM
你需要计数、比较两个状态或进行日期运算	代码，两者都不用

免费检查，无需API调用：

jevskill plan "<问题>"

会给出对应的模式、层级和预期调用次数。一次真实决策的成本约为0.000013美元。

1. The three primitives

1. 三种原语

Pick by the shape of the answer, never by topic.

You need	Primitive	Returns
yes / no	`noul`	`P(true)` , a float 0–1
one of N things	`choice`	winner + full distribution + confidence
how much on a scale	`score`	weighted mean, legend, distribution

All three in one call is the normal case — that is the bundle you send:

json

{
  "owner":      {"type": "choice", "instructions": "Which subsystem owns the fix?",
                 "criteria": {"billing": "Invoices, tax, payments.", "api": "HTTP layer.",
                              "db": "Schema, migrations, queries.",
                              "unclear": "Not enough information to decide."}},
  "risk":       {"type": "score", "instructions": "How risky is deploying this unreviewed?",
                 "criteria": ["Trivial", "Low", "Moderate", "High", "Critical"]},
  "needs_test": {"type": "noul", "instructions": "Does this change need a new test?"}
}

根据答案的形式选择，而非根据主题选择。

需求	原语	返回值
是/否判断	`noul`	`P(true)` ，0–1之间的浮点数
N个选项中选一个	`choice`	胜出选项 + 完整概率分布 + 置信度
尺度上的得分	`score`	加权平均值、图例、分布

通常情况下会在一次调用中同时使用这三种原语——也就是你发送的请求包：

json

{
  "owner":      {"type": "choice", "instructions": "Which subsystem owns the fix?",
                 "criteria": {"billing": "Invoices, tax, payments.", "api": "HTTP layer.",
                              "db": "Schema, migrations, queries.",
                              "unclear": "Not enough information to decide."}},
  "risk":       {"type": "score", "instructions": "How risky is deploying this unreviewed?",
                 "criteria": ["Trivial", "Low", "Moderate", "High", "Critical"]},
  "needs_test": {"type": "noul", "instructions": "Does this change need a new test?"}
}

2. How to call it

2. 如何调用

Default path — the bundled script, nothing to install, standard library only. Claude Code prints this skill's base directory when it loads the skill: that is

$SKILL_DIR

. Other agents:

~/.agents/skills/jev

~/.claude/skills/jev

bash

python "$SKILL_DIR/scripts/jev_query.py" --state-file diff.txt \
  --question-type noul --name breaks_api \
  --instructions 'Does the diff at `state` change a public API signature?' \
  --true-text 'A public name, signature or return type changes.' \
  --false-text 'Only internals, comments, tests or formatting change.'

bash

python "$SKILL_DIR/scripts/jev_query.py" --state-file report.txt \
  --questions "$(cat bundle.json)" --json

Add

--reduce --keep 8

to shortlist a large file (rule 3);

--blocks

gates a structural unit rather than a line;

jev_recovery.py

reads back what REDUCE cut.

python -c "import jevskill"

succeeds, prefer

jevskill ask|batch|plan

— same wire format, plus the ledger, stage timings and

outcome

stats

advice

batch

applies one bundle to many items, the cheapest shape of all; name the item

`item`

and it is rewritten per item, so rule 1's naming cannot be forgotten:

bash

jevskill batch build.log --text-key line --question-type choice --name owner \
  --instructions 'Which team should own `item`?' \
  --options backend frontend infra unclear --intent ci-triage --out triaged.jsonl

Exit	Meaning	What to do
`0`	decided / scored	act on it
`2`	at least one answer needs review	escalate, widen the state, or re-ask — not an error
`3`	state over the token budget	nothing was sent; cut the data first (rule 3)
`1`	input, key, API or protocol error	fix the call

默认方式——使用内置脚本，无需安装，仅依赖标准库。Claude Code在加载该技能时会打印其根目录：即

$SKILL_DIR

。其他Agent的路径为：

~/.agents/skills/jev

或

~/.claude/skills/jev

。

bash

python "$SKILL_DIR/scripts/jev_query.py" --state-file diff.txt \
  --question-type noul --name breaks_api \
  --instructions 'Does the diff at `state` change a public API signature?' \
  --true-text 'A public name, signature or return type changes.' \
  --false-text 'Only internals, comments, tests or formatting change.'

bash

python "$SKILL_DIR/scripts/jev_query.py" --state-file report.txt \
  --questions "$(cat bundle.json)" --json

添加

--reduce --keep 8

可以对大文件进行筛选（规则3）；

--blocks

会对结构单元而非单行进行门控；

jev_recovery.py

可以回读REDUCE裁剪掉的内容。

如果

python -c "import jevskill"

执行成功，优先使用

jevskill ask|batch|plan

——传输格式相同，但额外提供台账、各阶段耗时以及

outcome

stats

advice

字段。

batch

会将一个请求包应用到多个条目上，是成本最低的调用方式；将条目命名为

`item`

，它会按条目自动替换，这样就不会忘记规则1的命名要求：

bash

jevskill batch build.log --text-key line --question-type choice --name owner \
  --instructions 'Which team should own `item`?' \
  --options backend frontend infra unclear --intent ci-triage --out triaged.jsonl

退出码	含义	处理方式
`0`	已决策/已打分	执行相应操作
`2`	至少有一个答案需要审核	升级处理、扩充状态或重新提问——这不是错误
`3`	状态超出token预算	未发送任何请求；先裁剪数据（规则3）
`1`	输入、密钥、API或协议错误	修复调用参数

3. The four rules that decide whether this works

3. 决定效果的四条规则

Rule 1 — Fan out. One call, many questions.

规则1——扇出：一次调用，多个问题

Questions over one state are evaluated in parallel; another question costs a few input tokens and almost no latency. Eight sequential calls cost 12.4× the time and 4.03× the tokens of the same eight batched, because you re-send the state eight times (

references/benchmarks.md

E3).

text

GOOD:  1 call  {q1, q2, q3, q4, q5, q6}
BAD:   6 calls, each with one question and the same state

A loop that calls Jev once per question is a bug. Rewrite it as one dict.

针对同一状态的问题会并行评估；新增一个问题只会消耗少量输入token，几乎不增加延迟。8次顺序调用的耗时是批量调用8个问题的12.4倍，token消耗是4.03倍，因为你需要重复发送8次状态（

references/benchmarks.md

E3）。

text

GOOD:  1 call  {q1, q2, q3, q4, q5, q6}
BAD:   6 calls, each with one question and the same state

循环中每个问题调用一次Jev是错误的做法。请将其改写为单个字典的一次调用。

Rule 2 — Decompose into atomic signals, combine in code.

规则2——分解为原子信号，在代码中组合

One broad question hides several judgements and gets worse as it broadens. Several narrow

noul

gates in one call, weighted by code you own, beat it.

text

risk = 0.45*claims_tests_pass + 0.30*(1 - cites_changed_line) + 0.25*contradicts_diff

Query Jev broadly as a signal generator, not once as an oracle (

references/prompting.md

§9).

一个宽泛的问题隐含了多个判断，而且问题越宽泛，效果越差。在一次调用中使用多个窄范围的

noul

门控，再通过你自己的代码加权，效果要好得多。

text

risk = 0.45*claims_tests_pass + 0.30*(1 - cites_changed_line) + 0.25*contradicts_diff

可以宽泛地查询Jev作为信号生成器，而不是把它当作神谕只调用一次（

references/prompting.md

第9节）。

Rule 3 — Budget the state; cut it with code first.

规则3——为状态设定预算；先用代码裁剪

Irrelevant state is a distractor that degrades the answer, and it is billed. Default budget: 8,000 tokens of state. Filter in code first — grep, slice, dedupe. What code cannot filter, REDUCE can:

bash

jevskill plan "keep the salient lines" --state-file build.log
python "$SKILL_DIR/scripts/jev_query.py" --state-file build.log --reduce --keep 8 \
  --instructions 'Does the log line at `L{i}` report a problem worth investigating?'

Do not answer "it does not fit" by raising the budget.

无关状态会干扰结果，降低答案质量，而且还会计费。默认预算：8000 token的状态内容。先用代码过滤——比如grep、切片、去重。代码过滤不了的，可以用REDUCE：

bash

jevskill plan "keep the salient lines" --state-file build.log
python "$SKILL_DIR/scripts/jev_query.py" --state-file build.log --reduce --keep 8 \
  --instructions 'Does the log line at `L{i}` report a problem worth investigating?'

不要用提高预算的方式来解决“装不下”的问题。

Rule 4 — Route on uncertainty. Narrow once, then escalate.

规则4——基于不确定性路由：先收窄，再升级

choice

is a distribution, not a label. When the top two are close, re-ask over just those two plus the context that discriminates them:

text

round 1:  net/client.py 0.51   net/retry.py 0.44   …   -> gap 0.07: NARROW
round 2:  net/retry.py 0.91    net/client.py 0.09      -> gap 0.82: ACCEPT

Two rounds is the budget. Beyond that, hand it to the LLM or a human — never guess.

choice

的结果是一个概率分布，而非一个标签。当排名前二的选项得分接近时，仅针对这两个选项加上能区分它们的上下文重新提问：

text

round 1:  net/client.py 0.51   net/retry.py 0.44   …   -> gap 0.07: NARROW
round 2:  net/retry.py 0.91    net/client.py 0.09      -> gap 0.82: ACCEPT

最多两轮。超过两轮的话，交给LLM或人工处理——切勿猜测。

4. Reading an answer

4. 解读答案

A
```
noul
```
is a probability, not a boolean.
```
0.62
```
is not "true".
```
confidence
```
is concentration, not correctness: it can be high while the top two options sit within noise of each other. Read the margin between them.
An answer with no
```
unclear
```
/
```
none
```
option is a forced answer. Always ship the escape hatch, named after the reason ("not enough information to decide").
Thresholds are policy, not fact. The vendor's worked example: a 0.6 floor for acting at all, 0.85 before an irreversible action, per action type. Calibrate on your own labelled cases;
```
--review-below 0.75
```
/
```
--review-margin 0.10
```
are illustrative defaults, not calibrated guarantees.
Never map a label straight to a destructive action. Re-check it in code.

```
noul
```
的结果是概率，不是布尔值。
```
0.62
```
不代表“成立”。
```
confidence
```
（置信度）是集中度，而非正确率：当前两名的差距处于噪声范围内时，置信度也可能很高。请关注两者之间的差值。
没有
```
unclear
```
/
```
none
```
选项的答案是强制选择的结果。请始终提供逃生通道，并以原因命名（比如“信息不足，无法决策”）。
阈值是策略，不是事实。 厂商的示例：根据操作类型，最低行动阈值为0.6，不可逆操作阈值为0.85。请用你自己的标注数据校准；
```
--review-below 0.75
```
/
```
--review-margin 0.10
```
只是示例默认值，并非校准后的保证。
切勿将标签直接映射到破坏性操作。请用代码再次校验。

5. Key and provider

5. 密钥与服务商

One key, read from the environment and then the Windows registry:

JEV_API_KEY

TYPESAFE_API_KEY

(the vendor endpoint) or

OPENROUTER_API_KEY

(the aggregator). Same model, same price. Precedence:

--provider

, then

JEVSKILL_PROVIDER

, then the config file; with none of those, the first key found by name, vendor names first. To check whether a key is configured — without ever printing one:

bash

jevskill doctor --json      # or: python "$SKILL_DIR/scripts/jev.py" doctor --json

It reports

key_found

key_name

key_source

and an 8-hex

key_fingerprint

, never key material. Neither do you.

No key? Ask — never simulate silently. Check only that a key exists, then ask the user, in their language, to pick:

A — get a key (https://openrouter.ai/settings/keys or https://console.typesafe.ai/keys) and I use real Jev; B — I judge it myself, with the same state, options and criteria, without calling Jev.

Wait for an explicit A or B. Consent covers this task only; a key appearing later does not convert an approved B into A; API errors are not consent to simulate — report them. In B, label every result

mode: agent_simulation

jev_called: false

, probabilities

null

needs_review: true

, and never apply confidence thresholds to a simulated judgement or mix it into Jev's numbers.

密钥从环境变量和Windows注册表中读取，支持：

JEV_API_KEY

、

TYPESAFE_API_KEY

（厂商端点）或

OPENROUTER_API_KEY

（聚合服务商）。模型相同，价格一致。优先级：

--provider

参数 >

JEVSKILL_PROVIDER

环境变量 > 配置文件；如果都没有，则按名称查找第一个密钥，厂商名称优先。要检查是否已配置密钥——且不会打印密钥内容：

bash

jevskill doctor --json      # or: python "$SKILL_DIR/scripts/jev.py" doctor --json

它会返回

key_found

、

key_name

、

key_source

和8位十六进制的

key_fingerprint

，绝不会返回密钥本身。你也不应该泄露密钥。

没有密钥？询问用户——切勿静默模拟。 只需确认密钥是否存在，然后用用户的语言询问其选择：

A — 获取密钥（https://openrouter.ai/settings/keys 或 https://console.typesafe.ai/keys），我将使用真实的Jev；B — 我自己判断，使用相同的状态、选项和标准，不调用Jev。

请等待用户明确选择A或B。同意仅适用于本次任务；后续出现密钥不会将已批准的B模式转换为A模式；API错误不等于同意模拟——请如实报告。在B模式下，所有结果都要标注

mode: agent_simulation

、

jev_called: false

，概率设为

null

，

needs_review: true

，且绝不能对模拟判断应用置信度阈值，也不能将其与Jev的结果混合。

6. Hard constraints, and the failure modes that cost the most

6. 严格约束与最高成本的失败模式

No text output. No prose, code, summaries or explanations. Ever.
Options are fixed per request. It picks from your set; it cannot invent one.
Text input only. No images, no audio.
Context: 32K tokens on OpenRouter, 64K on the vendor — and accuracy degrades well before the limit.
Not OpenAI-compatible, and hosted only: no self-hosting, no air-gap.

Anti-pattern	Do instead
A loop calling Jev once per question	one call, many questions (rule 1)
The question does not name its target value	name it: `L7` , `ticket.message` — otherwise it silently returns a flat ~0.74 for every item ( `prompting.md` §1)
Accepting a 0.51 winner	narrow and re-ask (rule 4)
No `unclear` / `none` option	always ship an escape hatch
Asking Jev to count, compare two states, or diff	do it in code — it returns a plausible coin flip ( `prompting.md` §0, §11)
Treating a guard's answer as authorisation	the guard advises; your code and the user decide

无文本输出。 绝不生成散文、代码、摘要或解释。
每个请求的选项固定。 它只能从你提供的集合中选择，不能创造新选项。
仅支持文本输入。 不支持图像、音频。
上下文长度：OpenRouter上为32K token，厂商端为64K token——而且在达到上限之前，准确率就已经下降了。
不兼容OpenAI接口，且仅支持托管模式：不支持自托管，不支持物理隔离环境。

反模式	正确做法
循环中每个问题调用一次Jev	一次调用，多个问题（规则1）
问题没有指明目标值	明确命名：比如 `L7` 、 `ticket.message` ——否则它会对每个条目都返回约0.74的固定值（ `prompting.md` 第1节）
接受0.51的胜出选项	收窄范围后重新提问（规则4）
没有 `unclear` / `none` 选项	始终提供逃生通道
要求Jev计数、比较两个状态或做diff	用代码实现——它只会返回看似合理的随机结果（ `prompting.md` 第0、11节）
将门控的答案当作授权	门控仅提供建议；最终由你的代码和用户决定

7. Read only the slice you need

7. 只读取你需要的部分

Load one file, not all of them.

Need	Read
Request/response shapes, errors, providers, official SDKs	`references/api.md`
Every command, flag and script invocation	`references/commands.md`
The nine patterns, and how they map to the vendor's four	`references/patterns.md`
Writing questions: the vendor's weakness list (§0), naming the value (§1), what belongs in code (§11)	`references/prompting.md`
Every measurement, with method and threats to validity	`references/benchmarks.md`
The ledger, `stats` , `advice` , stage timings — is this skill paying for itself?	`references/measure.md`
A hot loop: `hot=True` , hedged requests, warm-up	`references/hotloop.md`
A GUI / computer-use step, end to end	`references/act.md`
Speculation, self-consistency, beam over the cascade — measured, all three off	`references/speculate.md`

Official docs index: https://docs.typesafe.ai/llms.txt · Model card: https://openrouter.ai/typesafe/jev-1.13

只加载需要的文件，不要全部加载。

需求	读取文件
请求/响应格式、错误处理、服务商、官方SDK	`references/api.md`
所有命令、参数和脚本调用方式	`references/commands.md`
九种模式，以及它们如何映射到厂商的四种模式	`references/patterns.md`
问题编写：厂商的弱点列表（第0节）、值的命名（第1节）、哪些逻辑应该放在代码里（第11节）	`references/prompting.md`
所有性能测试数据，包含测试方法和有效性威胁	`references/benchmarks.md`
台账、 `stats` 、 `advice` 、各阶段耗时——这个技能是否划算？	`references/measure.md`
热循环： `hot=True` 、对冲请求、预热	`references/hotloop.md`
GUI/计算机操作步骤，端到端流程	`references/act.md`
推测、自一致性、级联束搜索——已测试，三者默认均关闭	`references/speculate.md`

官方文档索引：https://docs.typesafe.ai/llms.txt · 模型卡片：https://openrouter.ai/typesafe/jev-1.13