---
name: numa-jev
license: MIT
metadata:
  version: "0.1.0"
description: 通过企业 Jev MCP 与 DevOps 平台使用 TypeSafe 的结构化判断，协助终端 Agent、ChatGPT 做分类、路由、评分和验证，或为 K8s 自研 Agent 编写集成代码。按任务构造 state 与 choice、score、noul 问题，处理概率和失败；使用 Numa 用户或服务身份，不管理 OpenRouter 密钥。
---

# Numa Jev

Jev 为应用提供可组合的语义判断，不替代写代码或对话的主模型。代码处理规则、计算、查找、授权和执行，Jev 回答需要语义理解的具体问题。

本包基于官方 `typesafe-ai` Skill 定制，保留问题设计方法，改为企业 MCP / 平台接入。来源与许可见 [来源记录](references/upstream.md) 和 [LICENSE](LICENSE)。这是源码版本，安装、企业发布、MCP 注册和目标环境部署分别核验。

## 选择使用方式

- **现在做判断**：读取 [MCP 调用指引](references/mcp-usage.md)，使用已连接且授权的 Jev MCP 工具。终端 Agent 加载本 Skill；ChatGPT 依赖实际连接的远程工具及其说明，不能假定会加载本地 Skill 文件。
- **为应用接入 Jev**：读取 [应用集成指引](references/application-integration.md)。生成调用平台 API 或 MCP 的代码；K8s 运行时使用独立服务身份，不需要安装 Skill。
- **安装或修复连接**：加载同来源基础 Skill `numa-cli@1.4.1`，核实实际 CLI 帮助、环境和已发布资源，再完成用户授权的 Skill 安装与 MCP 配置。依赖 manifest 只声明 Skill，安装本包不会自动连接 MCP。缺少基础 Skill 时报告缺口并按既有授权恢复；不要猜测远端版本存在。

终端、ChatGPT 和服务端调用都通过平台授权。客户端不索取 OpenRouter Key，不设置上游代理，不因连接失败直连 OpenRouter。**平台到 OpenRouter 必须走已配置的服务端出网代理**；故障交给平台维护者处理，客户端不得解除代理或改换身份。

## 设计判断

先明确最终应用行为，再拆出必要的判断。字符串适合简单文本；多部分上下文使用命名 JSON 字段，放入相关事实、来源、当前状态和必要规则。只提交任务需要的上下文，不加入凭据。

| 结果含义 | 问题类型 | 使用要点 |
| --- | --- | --- |
| 从候选集中选一个 | `choice` | 给出候选及说明；可能都不匹配时包含 `other` / 无匹配项 |
| 某命题是否成立 | `noul` | 每个独立标签一个问题，可同时成立；返回成立概率 |
| 在有顺序的情形间评分 | `score` | 等级描述具体情形，每级能单独理解；多个维度分别评分 |

完整问题写进 `instructions`，候选定义写进 `criteria`。问题 ID 仅用于结果索引，不能替代问题语义。引用嵌套上下文时使用明确路径，例如 `ticket.message`。模型无法选择未提供的候选；选择原文值之前先检查候选覆盖。

每个问题描述一个可独立使用的判断。官方支持结构化描述；企业 MCP 和平台可能有更窄的校验，以当前工具 schema 和 capabilities 为准。暂不支持某种结构时，将必要定义表述清楚，避免丢失含义，也不要绕过平台。

**同一 state 上相互独立的问题合并为一次请求**。问题不能看到同批其他答案；预先提出的分支问题须明确假设，由代码只消费适用分支。只有需要前一步答案来查资料、构造新状态或生成下一组选项时，才发下一次请求。遵守平台问题数与大小限制，统计实际用量。

## 组合与解读

- `choice` 返回选择及各选项概率；`score` 返回等级位置与分布。Score 对 N 个等级通常在 0 到 N−1 间，可以是小数，不能当成百分比或成立概率。
- `noul` 是 0–1 的成立概率，无独立 confidence；接近 0.5 表示 yes/no 难分，不表示“中等程度”。
- Choice/Score 的 confidence 描述分布集中程度，不证明事实正确，也不授予执行权限。阈值须用用户领域样本和误判后果验证；不要把演示阈值当通用政策。
- 评分可以组合权重、排序或筛选；必须命中的规则单独判断，不能用其他高分抵消。证据与问题未变时，调整业务权重不必重新推理。
- 已知规则和最终执行留在代码/业务工作流。低置信度时按业务要求澄清或交给人/主 LLM；无需消费的分支不因低置信度影响主路径。
- 分清观察事实与推断；状态已变化时检查旧答案是否仍适用。报告类型化结果和必要用量，不编造 Jev 的推理过程。解释文字由当前 Agent 根据输入和答案组织。

## 文档与验证

开发集成前从 [官方索引](https://docs.typesafe.ai/llms.txt) 查相关页面，重点读取 [API](https://docs.typesafe.ai/api)、[置信度](https://docs.typesafe.ai/confidence) 和贴近业务的 cookbook；OpenRouter 的传输契约见 [Jev Decisions](https://openrouter.ai/docs/guides/community/jev)。官方直连地址、API Key 和 SDK 默认重试配置不能直接搬到企业调用中。

需要探索设计时，可从候选值选择、证据相关性、组合评分、声明验证和状态变化后的再判断中选择适合目标的形态，不局限于分类。以代表性样本验证最终业务行为，分别定位证据缺失、判断错误、组合代码错误和服务故障。

[请求示例](assets/decision.json) 是合成客服状态，含三个独立问题。先离线验证形状和业务分支；实际调用会产生上游用量，执行范围沿用用户任务授权。平台 capability 成功不等于 OpenRouter 推理链路已验证。