jev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

jev

jev

turns a judgment call into a typed answer with a calibrated probability. It reads a state (text or JSON) and answers named questions of three kinds —

noul

(P(yes)),

choice

(one of N),

score

(ordinal scale, at most 10 levels). It never generates text. A call costs about $0.00002, so 1,000 decisions run about 2 cents: use it wherever a script or an agent needs a quick, consistent verdict, and keep LLM reasoning for what survives the filter.

jev

可将判断需求转换为带校准概率的类型化答案。它接收状态输入（文本或JSON），可回答三类指定问题——

noul

（是/否概率）、

choice

（N选1）、

score

（序数等级，最多10级）。它绝不生成文本内容。单次调用成本约0.00002美元，即1000次判断仅需约2美分：凡是脚本或Agent需要快速、一致的判定结果的场景都可使用，将LLM推理能力留给通过筛选的内容。

Setup

安装配置

Run
```
jev --version
```
. If the command is missing, the CLI ships with this skill at
```
scripts/jev
```
(Python 3.9+, standard library only). Link it with
```
mkdir -p ~/.local/bin && ln -sf "<this skill's directory>/scripts/jev" ~/.local/bin/jev
```
, or call it by its absolute path.
Keys:
```
TYPESAFE_API_KEY
```
(default provider) or
```
OPENROUTER_API_KEY
```
, read from the environment, then
```
$JEV_ENV_FILE
```
, then
```
<config dir>/.env
```
. Provider:
```
--provider
```
→
```
$JEV_PROVIDER
```
→ the default pinned with
```
jev provider default ID
```
→ auto (TypeSafe if its key exists, else OpenRouter).
```
jev provider list
```
,
```
jev auth status
```
and
```
jev auth check
```
are read-only and never print a key — run them freely. On a missing key or a 401/403, ask the user to run
```
jev auth set
```
(plus
```
--provider openrouter
```
for that key) in their own terminal: it needs a TTY and hidden input, so you cannot run it for them. Never ask for a key in chat, pass one as an argument, pipe one into
```
auth set --stdin
```
, read or print a key file, or run
```
jev auth remove
```
unless the user asks.

For designing the questions themselves (choosing

noul

choice

score

, writing

criteria

, confidence and calibration semantics), see TypeSafe's own docs: primitives, confidence, full index at llms.txt.

运行
```
jev --version
```
。如果找不到该命令，本skill附带的CLI位于
```
scripts/jev
```
（仅需Python 3.9+ 标准库）。可通过以下命令创建软链：
```
mkdir -p ~/.local/bin && ln -sf "<本skill的目录>/scripts/jev" ~/.local/bin/jev
```
，也可直接使用绝对路径调用。
密钥配置：优先从环境变量读取
```
TYPESAFE_API_KEY
```
（默认服务商）或
```
OPENROUTER_API_KEY
```
，其次读取
```
$JEV_ENV_FILE
```
，最后读取
```
<config dir>/.env
```
。服务商选择优先级：
```
--provider
```
参数 →
```
$JEV_PROVIDER
```
环境变量 → 通过
```
jev provider default ID
```
设置的默认值 → 自动选择（存在TypeSafe密钥则用TypeSafe，否则用OpenRouter）。
```
jev provider list
```
、
```
jev auth status
```
和
```
jev auth check
```
都是只读命令，绝不会输出密钥——可放心运行。如果缺少密钥或返回401/403错误，请让用户在自己的终端运行
```
jev auth set
```
（如果是OpenRouter密钥需加上
```
--provider openrouter
```
）：该命令需要TTY和隐藏输入，因此你无法代用户执行。绝不要在聊天中索要密钥、将密钥作为参数传递、通过管道输入到
```
auth set --stdin
```
、读取或打印密钥文件，除非用户要求，否则也不要运行
```
jev auth remove
```
。

关于如何设计问题（选择

noul

choice

score

类型、编写

criteria

、置信度与校准语义），请参考TypeSafe官方文档：primitives、confidence，完整索引见 llms.txt。

Choose the verb

选择对应命令

Need	Command	Plain stdout	Exit code
Yes/no	`jev yes "QUESTION"`	`yes\t0.97`	0 yes · 1 no · 2 error
One of N	`jev pick "QUESTION" a="desc" b="desc" [--other]`	`a`	0 · 1 below `--min-confidence` · 2 error
Ordinal score	`jev score "QUESTION" low mid high` or `--range 1-5`	`1.43\tmid`	0 · 2 error
Keep matching lines	`jev filter "QUESTION"`	the matching input lines	0 some · 1 none · 2 error
Several questions at once	`jev run SPEC`	aligned table	0 · 2 error
Raw API body	`jev raw < body.json`	response JSON	0 · 2 error

Input comes from stdin,
```
-s "TEXT"
```
or
```
-s @file
```
. JSON objects and arrays go out as structured state (
```
--text
```
turns that off).
```
-l
```
makes one decision per input line: concurrent (
```
-j 8
```
), order preserved, streamed. For JSONL,
```
--field KEY
```
names the field to judge.
```
filter
```
always works per line.
Add
```
--json
```
whenever you parse results (JSONL with
```
-l
```
): each answer has
```
type
```
plus
```
noul
```
and
```
yes
```
, or
```
choice
```
, or
```
score
```
and
```
label
```
;
```
choice
```
and
```
score
```
also carry
```
probabilities
```
and
```
confidence
```
. Plain output suits humans and shell tests.
```
--verbose
```
prints provider, model, latency, tokens and cost to stderr (
```
≈$
```
when the cost is an estimate).
Speed: a single call opens a new connection, about 0.5–1 s in total.
```
-l
```
keeps each worker's connection open, so later calls take about 0.3–0.4 s. For more than a handful of items use
```
-l
```
or
```
filter
```
instead of looping single calls; raise
```
-j
```
for large batches (≤16).
```
yes
```
and
```
filter
```
take
```
-t P
```
(threshold, default 0.5) and
```
--true
```
/
```
--false
```
to spell out what yes and no mean.
```
pick -p
```
and
```
score -p
```
print the whole distribution.

bash

jev yes "用户在要求退款吗？" -s "Zipic 一打开就闪退，钱退我！"          # yes	0.97
jev pick "该交给谁处理" code="写代码或改项目" research="需要联网查资料" --other -s "$request" --json
jev score "这条评价给几星" --range 1-5 -s @review.txt                  # 3.30	3
tail -f app.log | jev filter "日志表示用户可见的故障" --false "调试信息、正常请求"
jev run feedback -l --field text --json < tickets.jsonl > labeled.jsonl

需求	命令	标准输出	退出码
是/否判断	`jev yes "QUESTION"`	`yes\t0.97`	0 表示是 · 1 表示否 · 2 表示错误
N选1	`jev pick "QUESTION" a="desc" b="desc" [--other]`	`a`	0 成功 · 1 低于 `--min-confidence` 阈值 · 2 表示错误
序数评分	`jev score "QUESTION" low mid high` 或 `--range 1-5`	`1.43\tmid`	0 成功 · 2 表示错误
保留匹配行	`jev filter "QUESTION"`	匹配的输入行	0 有匹配 · 1 无匹配 · 2 表示错误
同时判断多个问题	`jev run SPEC`	对齐的表格	0 成功 · 2 表示错误
原始API请求体	`jev raw < body.json`	响应JSON	0 成功 · 2 表示错误

输入可来自标准输入、
```
-s "TEXT"
```
参数或
```
-s @文件路径
```
。JSON对象和数组会作为结构化状态传入（使用
```
--text
```
可关闭该特性）。
```
-l
```
参数会对每一行输入分别执行一次判断：并发处理（
```
-j 8
```
指定并发数）、保持顺序、流式输出。对于JSONL格式，可通过
```
--field KEY
```
指定要判断的字段。
```
filter
```
命令始终按行处理。
如果需要解析结果，请添加
```
--json
```
参数（搭配
```
-l
```
时输出JSONL）：每个答案包含
```
type
```
字段，以及对应类型的字段（
```
noul
```
类型有
```
yes
```
字段，
```
choice
```
类型有对应选项字段，
```
score
```
类型有
```
score
```
和
```
label
```
字段）；
```
choice
```
和
```
score
```
类型还会返回
```
probabilities
```
和
```
confidence
```
字段。纯文本输出适合人工阅读和shell测试。
```
--verbose
```
参数会将服务商、模型、延迟、token数和成本输出到标准错误流（成本为估算时会显示
```
≈$
```
）。
速度说明：单次调用会新建连接，总耗时约0.5-1秒。
```
-l
```
模式下每个工作进程会保持连接，因此后续调用仅需约0.3-0.4秒。如果需要处理多个条目，请使用
```
-l
```
或
```
filter
```
而非循环调用单次命令；大批量处理时可提高
```
-j
```
并发数（最高16）。
```
yes
```
和
```
filter
```
命令支持
```
-t P
```
参数（阈值，默认0.5），以及
```
--true
```
/
```
--false
```
参数来明确定义“是”和“否”的含义。
```
pick -p
```
和
```
score -p
```
会输出完整的概率分布。

bash

jev yes "用户在要求退款吗？" -s "Zipic 一打开就闪退，钱退我！"          # yes\t0.97
jev pick "该交给谁处理" code="写代码或改项目" research="需要联网查资料" --other -s "$request" --json
jev score "这条评价给几星" --range 1-5 -s @review.txt                  # 3.30\t3
tail -f app.log | jev filter "日志表示用户可见的故障" --false "调试信息、正常请求"
jev run feedback -l --field text --json < tickets.jsonl > labeled.jsonl

Write questions Jev can answer

编写Jev可回答的问题

Jev reads conditions literally and does not infer intent. In testing,

filter "包含具体可行动的信息"

passed an ad ("加微信领取免费 AI 课程，限时三天") at about 0.9, because an ad is literally actionable.

filter "消息给出了具体的技术、产品或行业信息" --false "闲聊、问候、广告、引流、卖课"

excluded it.

State observable conditions, not goals. Define both sides with
```
--true
```
/
```
--false
```
.
Describe every option (
```
name="description"
```
); add
```
--other
```
when the list may not cover every input. Order score labels low to high, 2–10 of them.
Put questions about the same input into one spec: one call answers all of them for that input (
```
-l
```
still makes one call per line).
Trim the state to what the question needs, well below the context limit — irrelevant text dilutes the signal; do math and date arithmetic in code and put the result into the state.
Gate actions on certainty: act on high
```
confidence
```
or probability, ask the user or escalate on low ones (
```
pick --min-confidence 0.7
```
,
```
yes -t 0.8
```
). Jev only decides — narrow the set with it, then read, write or summarize the survivors yourself.

Jev会按字面意思理解条件，不会推断意图。在测试中，

filter "包含具体可行动的信息"

对一条广告（“加微信领取免费 AI 课程，限时三天”）的通过率约为0.9，因为广告从字面上看确实是可行动的。而

filter "消息给出了具体的技术、产品或行业信息" --false "闲聊、问候、广告、引流、卖课"

则会排除该广告。

描述可观察的条件，而非目标。使用
```
--true
```
/
```
--false
```
明确定义正反两面。
描述每个选项（
```
name="描述"
```
）；如果选项列表可能无法覆盖所有输入，添加
```
--other
```
。评分标签按从低到高排序，数量为2-10个。
将针对同一输入的多个问题放到同一个spec中：一次调用即可回答该输入的所有问题（
```
-l
```
模式下仍为每行一次调用）。
将输入状态裁剪为问题所需的内容，远低于上下文长度限制——无关文本会稀释信号；数学和日期运算请在代码中完成，再将结果放入状态中。
根据置信度决定是否执行操作：高
```
confidence
```
或高概率时直接执行，低置信度时询问用户或升级处理（可使用
```
pick --min-confidence 0.7
```
、
```
yes -t 0.8
```
等参数）。Jev仅负责判断——用它缩小范围后，再由你自己对筛选后的内容进行读写或总结。

Specs

规格配置

jev run

lists the specs;

jev run NAME

jev run path/to/spec.json

runs one. Built-ins:

mail

(category, urgency, needs reply, promo),

feedback

(intent, sentiment, needs human, churn risk),

signal

(worth reading, topic, novelty for chat messages, tweets, RSS),

commit

(Conventional Commit type, secret leak, breaking change, risk for

git diff --cached

route

(handler, complexity, needs web, needs private data for a user request). Built-ins ship as JSON so every Python 3.9+ can load them. A spec's own

model

(if set) is normalized for whichever provider is active.

A spec mirrors the API body. Save new ones under

<config dir>/specs/

(

~/.config/jev/specs/

unless

XDG_CONFIG_HOME

is set), which survives reinstalling the skill. JSON works on every supported Python; TOML needs Python 3.11+ (

tomllib

) and errors clearly below that:

json

{
  "description": "One line shown by `jev run`",
  "threshold": 0.5,
  "questions": {
    "category": { "type": "choice", "instructions": "Which kind of request is this?",
      "criteria": { "bug": "Crash or broken feature", "billing": "Payment or license problem", "other": "None of the above" } },
    "urgency": { "type": "score", "instructions": "How soon must someone act?",
      "criteria": ["can wait", "this week", "today", "now"] },
    "needs_reply": { "type": "noul", "instructions": "The sender expects a personal reply",
      "criteria": { "true": "Asks a question or waits for a decision", "false": "Notice or receipt only" } }
  }
}

criteria

differs by type:

choice

and

noul

take a

{name: description}

map (

noul

needs both

true

and

false

score

takes an ordered array, low to high. A question may hold only

type

instructions

and

criteria

; anything else is rejected before a request is sent.

jev run

可列出所有可用spec；

jev run 名称

或

jev run path/to/spec.json

可运行指定spec。内置spec包括：

mail

（分类、紧急程度、是否需要回复、是否为促销）、

feedback

（意图、情感、是否需要人工处理、流失风险）、

signal

（是否值得阅读、主题、聊天消息/推文/RSS的新颖度）、

commit

（Conventional Commit类型、密钥泄露、破坏性变更、

git diff --cached

的风险）、

route

（处理者、复杂度、是否需要web、用户请求是否需要私有数据）。内置spec以JSON格式提供，因此所有Python 3.9+ 环境都可加载。spec中如果设置了

model

字段，会根据当前使用的服务商自动适配。

spec的结构与API请求体一致。新的spec可保存到

<config dir>/specs/

目录下（未设置

XDG_CONFIG_HOME

时默认为

~/.config/jev/specs/

），重新安装skill后仍会保留。JSON格式支持所有受支持的Python版本；TOML格式需要Python 3.11+（

tomllib

库），低于该版本会明确报错：

json

{
  "description": "One line shown by `jev run`",
  "threshold": 0.5,
  "questions": {
    "category": { "type": "choice", "instructions": "Which kind of request is this?",
      "criteria": { "bug": "Crash or broken feature", "billing": "Payment or license problem", "other": "None of the above" } },
    "urgency": { "type": "score", "instructions": "How soon must someone act?",
      "criteria": ["can wait", "this week", "today", "now"] },
    "needs_reply": { "type": "noul", "instructions": "The sender expects a personal reply",
      "criteria": { "true": "Asks a question or waits for a decision", "false": "Notice or receipt only" } }
  }
}

criteria

的格式因类型而异：

choice

和

noul

类型使用

{名称: 描述}

映射（

noul

必须同时包含

true

和

false

），

score

类型使用从低到高的有序数组。每个问题只能包含

type

、

instructions

和

criteria

字段；发送请求前会校验，多余字段会被拒绝。

Limits

使用限制

Decisions only: no text, no field extraction.
```
score
```
allows at most 10 levels.
TypeSafe native: 64K token context per request, 32K for state + the longest question, about 1,200 requests/min. OpenRouter:
```
https://openrouter.ai/api/alpha/decisions
```
is an alpha endpoint and may move — override with
```
JEV_BASE_URL
```
if it does.
The CLI retries 429/5xx with backoff on both providers; errors go to stderr as
```
jev: API 错误 (HTTP n): …
```
, exit code 2.

Full option reference, provider table, exit codes, error shapes and recipes: references/cli.md.

仅支持判断功能：不生成文本，不支持字段提取。
```
score
```
最多支持10个等级。
TypeSafe原生接口：单次请求上下文为64K token，其中状态+最长问题占32K，请求速率约1200次/分钟。OpenRouter接口：
```
https://openrouter.ai/api/alpha/decisions
```
是alpha阶段端点，可能会变动——如果变动可通过
```
JEV_BASE_URL
```
覆盖。
CLI对两个服务商的429/5xx错误都会采用退避重试策略；错误会以
```
jev: API 错误 (HTTP n): …
```
的格式输出到标准错误流，退出码为2。

完整的选项参考、服务商对比表、退出码、错误格式和使用示例：references/cli.md。