jev-agent-skill

# jev-agent-skill — 给 AI 编码代理装上「免费决策前置反射弧」





把**高频小判断**（分类 / 初筛 / 打分 / 核查）从主模型卸载给 [Jev](https://docs.typesafe.ai/concepts/system-one)（TypeSafe System One 决策模型，OpenCode Zen 免费档），主模型专心生成，判断走免费通道。适配 Claude Code / ZCode 及任何带 skills 目录的 agent。

| | 主模型做判断 | Jev 做判断 |
|---|---|---|
| 单次成本 | 数百~数千 token 推理 + 进上下文被反复计费 | ~400 输入 token，**$0**，不进上下文 |
| 输出 | 自由文本，需解析 | 类型化 schema（choice/noul/score），零格式错误 |
| 并发 | 串行 | 一次请求多问并行 |

实测（2026-09-20，10+ 次真实调用）：单次输入 283–694 token、`cost: 0`、端到端 ~2s；一次请求并行 4 问正常；中文 state/criteria 正常。**详细对比（tokens 消耗 & 内容质量，含 3 连发一致性实测）见 [benchmark 报告](references/benchmark-jev-vs-mainmodel.md)。**

## 为什么省 token

批量场景是收益大头：50 条评论初筛，主模型直读 ≈ 几万字进上下文（且此后**每一轮对话都在为它付费**）；走本 skill，原始条目留在脚本里，回上下文的只有 50 行结论。

## 快速开始

```bash
# 1. 拿一个 OpenCode Zen key（免费档即可），放进 ~/.jev/zen.key 或 export ZEN_API_KEY=...
# 2. 把本仓库 clone 到 agent 的技能目录
git clone https://github.com/yuyang2230/jev-agent-skill.git ~/.claude/skills/jev   # Claude Code
# ZCode: ~/.zcode/skills/jev
# 3. 冒烟
echo '{"state":"Payment system down 3h, users complaining","questions":{"is_urgent":{"type":"noul","instructions":"Urgent?"}}}' | python ~/.claude/skills/jev/jev.py
# -> is_urgent: 0.95
```

装好后，agent 读到 SKILL.md 的触发规则，遇到分类/初筛/打分/核查类任务会**自动**调 `jev.py`，不需要你点名。

## 触发场景

| 任务形态 | 原语 |
|---|---|
| 分类/路由：工单、评论、留言、日志归哪类、给谁 | `choice` |
| 批量初筛：哪些值得细看、哪些丢弃 | `noul` ×N |
| 打分/排序：按明确标准，权重在代码里组合 | `score` |
| 核查：陈述是否有证据、输出是否达标、有无违禁意 | `noul` |

不适用：生成文字/代码、需跨多轮上下文综合的决策、一次性琐碎判断。

## API 坑位（全部实战踩过）

| 症状 | 原因/修法 |
|---|---|
| 之前能用的 payload 突然 `HTTP 500` | Zen 网关瞬时故障（<1s 快速失败），重试 1–2 次（`jev.py` 已内置） |
| Python 直连 `HTTP 403` | WAF 拦裸 urllib UA，带 `User-Agent: curl/8.9.1` |
| Windows 下 `surrogates not allowed` | GBK 管道污染，读 `sys.stdin.buffer` 自己按 UTF-8 解 |
| key 正常却 `HTTP 401` | 模型名没权限/拼错，用 `jev-1.13-free` 不是 `jev-lates