jev-agent

Jev Agent

Jev AI 是一项面向软件和 Agent 的决策服务。它接收应用状态以及明确的类型化问题，并返回带概率的结构化答案。工作流、权限、人工审批和最终操作仍由 Agent 或应用负责。

首次使用引导

在会话中首次请求 Jev 之前，请检查以下环境变量是否可用。不要从 shell 历史记录、仓库文件或无关文件中查找密钥。

JEV_LANGUAGE      optional response language: en-US or zh-CN; default en-US
JEV_API_KEY       required Jev AI key created in the user's Jev AI account
JEV_API_BASE_URL  optional API origin; default https://thejevai.com
JEV_MODEL         optional model id; default typesafe/jev-1.13

如果缺少 JEV_LANGUAGE，请询问用户希望此技能的引导内容和生成示例使用哪种语言。提供英语（en-US）和简体中文（zh-CN）选项；只有在告知用户 en-US 为默认选项后，才能将其设为默认值。语言设置控制 Agent 的沟通方式和问题措辞；不会改变模型的 API 契约。

如果缺少 JEV_API_KEY，请说明用户可以在 https://thejevai.com/settings/apikeys 创建密钥，然后请他们在 Agent 的本地环境中进行配置。使用占位命令，绝不要要求用户将真实密钥粘贴到对话中：

export JEV_API_KEY="sk_your_key_here"
export JEV_LANGUAGE="en-US"

绝不要打印、记录、提交 JEV_API_KEY，也不要将其放入源代码、包含真实值的 Markdown 示例、客户端包或生成的制品中。缺少密钥表示尚未完成设置，不是猜测密钥或悄悄使用 OpenRouter、TypeSafe 或第三方代理密钥的理由。

在引导过程中，请用已配置的语言显示以下简短帮助，然后返回用户的任务。默认的英语帮助为：

Jev Agent can help you:
- use Choice for classification, routing, and selecting among candidates;
- use Score for risk, priority, and quality ratings;
- use Noul for yes/no probabilities, gates, escalation, and human review.

Basic flow: prepare minimal state → ask a clear question → read answers → let
your code or agent decide the next action.
Jev judges; it does not write long-form content, execute tools, or grant
permissions.

当 JEV_LANGUAGE=zh-CN 时，请用简体中文显示相同的帮助：

Jev Agent 可以帮助你：
- 用 Choice 做分类、路由和候选项选择；
- 用 Score 做风险、优先级和质量评分；
- 用 Noul 做真假概率、放行、升级和人工复核判断。

基本流程：准备最小 state → 提出明确问题 → 读取 answers → 由代码或 Agent 执行动作。
Jev 负责判断，不负责写长文本、执行工具或授予权限。

如果用户之后请求 help、帮助、配置说明或设置检查，请用已配置的语言显示相同的帮助，并且只报告密钥是否存在；绝不要透露密钥值。

何时使用 Jev

当请求之前就能定义答案范围，且结果将用于程序或 Agent 分支判断时，请使用 Jev，例如：

• 将任务、工单、请求或上下文路由到几个已知路径之一；
• 对文本进行分类或提取有界值；
• 按有序标准评估紧急程度、风险、质量或复杂度；
• 判断证据是否充分、工具调用是否需要审核，或任务是否应升级处理；
• 决定是否保留、截断或丢弃旧上下文。

不要将 Jev 用于生成文案、生成代码、解释、精确数据库查询、算术、身份验证、授权或可用确定性规则表达的规则。对于高影响操作，Jev 可以提供风险信号，但确定性策略、权限和人工审批仍必须具有最终决定权。

API 合约

我们的托管 API 是一个基于 Jev 决策提供方的 REST 封装：

POST https://thejevai.com/v1/systemone
Authorization: Bearer $JEV_API_KEY
Content-Type: application/json

当用户明确提供其他兼容的源时，请使用 JEV_API_BASE_URL。此服务的默认模型为 typesafe/jev-1.13；除非用户确认目标服务器支持官方 TypeSafe 别名 jev-latest，否则不要将其替换为该别名。

请求正文包含三个必填字段：

{
  "model": "typesafe/jev-1.13",
  "state": "A customer was charged twice for the same order.",
  "questions": {
    "needs_human": {
      "type": "noul",
      "instructions": "Does this case require human review before a refund?"
    }
  }
}

state 可以是字符串、对象或数组。只发送决策所需的事实，并移除密钥、支付凭据和无关的个人数据。

问题类型：

• choice：从 criteria 对象中选择一个选项；
• score：根据 criteria 数组评估有序量表；
• noul：返回是／否陈述为真的概率。

每个问题只提出一个范围明确的判断。如果相关且独立的问题共享同一状态，则可在一个请求中批量处理。不要让同一请求中的后续问题依赖较早问题的答案；应用获取所需证据后，再发送第二个请求。

API 使用标准的 Jev AI 信封格式响应：

{
  "code": 0,
  "message": "ok",
  "data": {
    "result": {
      "answers": {
        "needs_human": {
          "type": "noul",
          "noul": 0.94
        }
      },
      "usage": {
        "input_tokens": 42,
        "output_tokens": 0
      },
      "elapsedMs": 180
    },
    "creditsUsed": 1
  }
}

对于 choice 和 score，请检查返回的 choice 或 score、其 probabilities 以及 confidence。对于 noul，请检查取值范围为 0 到 1 的 noul。将概率和置信度视为参考信号，而非证明或授权。应根据用户的实际风险和历史数据选择阈值；不要臆造通用阈值。

调用 API

使用用户现有的技术栈和服务端代码。仅在有意进行低风险测试时，才适合使用精简的 shell 请求。不要仅为演示 Skill 的存在而发起实时请求；当用户要求使用 Jev 的工作流时，应将请求作为该工作流的一部分发起。

JEV_BASE_URL="${JEV_API_BASE_URL:-https://thejevai.com}"
curl -sS "$JEV_BASE_URL/v1/systemone" \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": "The customer has tried to connect Stripe for three days.",
    "questions": {
      "urgent": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }'

如果请求并非用户要求，且会消耗额度或包含敏感数据，请先征求用户同意。Jev 请求本身不会执行所评估的操作。

明确处理故障：

• 非 2xx 响应：显示状态码和安全的错误消息；
• code 不等于 0：不要将 data 读取为有效结果；
• 缺少 data.result.answers：将响应视为无效；
• 401：请用户检查本地 API 密钥配置；
• 402：请用户充值或使用有效的账户密钥；
• 超时、429 或上游故障：仅当外围工作流可安全重试时，才进行有界退避重试；
• 绝不要仅仅因为决策请求失败，就重复执行会产生重大后果的操作。

Agent 安全边界

此 Skill 用于指导 Agent 何时以及如何向 Jev 请求判断。它不会创建新工具、授予权限、拦截 shell 调用，也不会在 Agent 现有权限之外强制执行策略。Agent 仍必须在需要时征求用户确认、遵守当前工作区和工具限制，并确保不可逆操作始终受到确定性检查和常规审批流程的约束。

将问题定义、业务阈值和操作映射保存在精简且易于审查的代码位置。当工作流需要审计记录时，记录模型版本、问题定义、安全的输入摘要、决策和最终操作，但绝不要记录 API 密钥。

安装和帮助

使用 Agent 的常规 Skill 安装程序，从公共仓库安装此 Skill：

npx skills add jev-ai/jev-agent-skill

如需手动进行项目本地安装，请将此文件复制到 .agents/skills/jev-agent/SKILL.md。安装后，请 Agent use the Jev Agent skill 或运行配置／帮助请求。首次使用时，必须先完成上述引导流程，然后才能发起第一条 Jev 实时请求。

如需了解当前产品详情和账户操作，请访问：

• API 文档：https://thejevai.com/docs
• API 密钥管理：https://thejevai.com/settings/apikeys
• Playground：https://thejevai.com/playground