@numa-tech/numa 1.23.1 → 1.25.0

package/skills/numa-jev/SKILL.md

@@ -0,0 +1,54 @@
+---
+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 推理链路已验证。

package/skills/numa-jev/assets/decision.json

@@ -0,0 +1,37 @@
+{
+  "state": {
+    "ticket": {
+      "message": "客户说：付款失败了三天，请尽快帮忙。",
+      "source": "synthetic-example"
+    }
+  },
+  "questions": {
+    "urgent": {
+      "type": "noul",
+      "instructions": "ticket.message 是否明确要求紧急处理？",
+      "criteria": {
+        "true": "明确要求尽快处理或表达时间紧迫",
+        "false": "没有表达时间紧迫或要求尽快处理"
+      }
+    },
+    "department": {
+      "type": "choice",
+      "instructions": "根据 ticket.message 描述的问题，应由哪个团队先受理？",
+      "criteria": {
+        "billing": "付款、发票或退款问题",
+        "technical": "与付款无关的软件缺陷、故障或接口集成问题",
+        "sales": "购买、报价或升级问题",
+        "other": "以上团队都不适合，或内容不足以确定"
+      }
+    },
+    "frustration": {
+      "type": "score",
+      "instructions": "ticket.message 中客户表达的挫败程度如何？",
+      "criteria": [
+        "平静描述情况，没有表达不满",
+        "表达不满或焦急，但没有辱骂或强烈愤怒",
+        "表达强烈愤怒或辱骂"
+      ]
+    }
+  }
+}

package/skills/numa-jev/numa-skill.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "name": "numa-jev",
+  "version": "0.1.0",
+  "dependencies": [
+    { "name": "numa-cli", "version": "1.4.1" }
+  ]
+}

package/skills/numa-jev/references/application-integration.md

@@ -0,0 +1,36 @@
+# 为 K8s Agent 开发集成
+
+Skill 在开发阶段指导编码 Agent，运行容器不需要读取 Skill。应用可以使用已有 MCP 客户端调用 [同一工具合同](mcp-usage.md)，也可以直接调用平台 HTTP；两者必须保留真实服务主体，不能共享某个管理员的个人登录缓存。
+
+## HTTP 合同
+
+API base 使用目标环境已确认的配置，必要时包含网关服务前缀，不能默认选生产。路径：
+
+- `GET /api/v1/jev/capabilities`：`jev-runtime-access/view`。
+- `POST /api/v1/jev/decisions`：`jev-runtime-access/edit`，JSON 正文为 `{state, questions, model?}`，**HTTP 不带 MCP 的 `body` 外层**。
+
+成功 HTTP body 是原生结果 `{model, answers, usage, id?, provider?}`，没有 MCP 的 `structuredContent` 或 `status/data` 外层。API 失败保留 HTTP 状态与平台安全错误码，不能按成功答案解析。错误语义见 [MCP 指引](mcp-usage.md)。
+
+配置固定平台地址并限制重定向；使用服务端正常校验的 TLS。令牌只发到配置的企业服务端点，不传到 OpenRouter。设置超时和应用并发上限；每副本的并发限制不等于跨集群消费额度。POST 默认不自动重试，SDK/HTTP 框架的隐式重试也要关闭。
+
+## 服务身份
+
+复用团队现有的 OIDC `client_credentials` 机制：独立 confidential client、已登记服务账号、对应 Jev 功能授权，凭据由部署 Secret 注入。令牌在内存缓存并按到期刷新；不通过运行容器登录人类 CLI，不复制个人 token 文件。
+
+Node 应用可复用 Numa 的 `@numa-tech/cli-auth` 中 `ensureAccessToken` 和 `AuthConfig`，先核对项目已有版本。配置 `authenticationMode: "client_credentials"`、服务 client ID、目标 issuer/discovery、scope，以及唯一凭据源。`clientSecret` 可由 K8s Secret 环境注入；若选 `clientSecretFile`，当前库要求当前用户拥有的普通私有文件，不接受符号链接，需留意 K8s projected Secret 的挂载形式。不要因文件读取失败改宽权限。
+
+代码组织为令牌提供者 + 固定平台 HTTP 客户端 + 业务结果消费，测试时注入伪令牌提供者和 transport。鉴权库负责令牌生命周期，平台再次校验权限；`client_credentials` 令牌本身不保证业务权限。401 后刷新供下一次独立请求使用，不在未知执行状态下自动重放 POST。
+
+## 出网代理与部署边界
+
+K8s Agent 只需到身份服务、企业 Router 或平台 API 的网络连接。**OpenRouter 必须从 DevOps 平台经过已绑定的 `OPENROUTER` 服务代理出网**；客户端不携带代理 URL、代理密码、OpenRouter Key 或任意 provider 路由参数。
+
+平台部署先验证启用/密钥/授权/代理绑定。代理不可用应失败封闭，不回退直连。无密钥代理探测至多证明网络与 TLS 可达；只有一次授权的真实判断才能证明模型、账户、额度和出网链路可用。源码和离线测试不能替代目标环境验收。
+
+当前平台代理管理支持公网 HTTP CONNECT / HTTPS，带认证代理仅支持 HTTPS；SOCKS 和私网/sidecar 代理不在现有支持范围。实际代理地址需满足已配置的平台网络校验，不因接入失败关闭地址限制。
+
+## 业务验证
+
+先用合成/脱敏代表样本离线测试解析、缺失答案、低置信度分支及 401/403/429/超时处理，再在明确授权的环境做少量真实调用。保留每次观察的 state 版本与问题版本，防止将旧结果用于变化后的状态；不要把 state、凭据或原始上游错误写入通用日志。
+
+建立领域样本集测量模型误判和端到端行为：路由是否正确、不确定时是否升级处理、是否有漏掉的候选。固定规则仍由代码执行；低分、错误、超时均不能自动授予业务权限。

package/skills/numa-jev/references/mcp-usage.md

@@ -0,0 +1,53 @@
+# 终端 Agent 与 ChatGPT
+
+## 连接与发现
+
+通过 Numa 的实际 Skills/MCP 工作流分别安装本 Skill 和配置已发布的 Jev MCP 资源。先加载基础 `numa-cli` 的启动与 Skills/MCP 参考文档，核实当前命令帮助和 registry 中的 namespace、instance、版本、Router 健康状态。资源名称与工具名称不是同一概念，不能假定 MCP 资源必定叫 `numa-jev`。
+
+- **WorkBuddy 等终端 Agent**：由对应适配器配置企业 Router；只支持 stdio 的环境通过受支持的 Numa bridge 连接。客户端只得到 Router 连接资料，不能配置平台下游地址或上游凭据。
+- **ChatGPT**：目标接入是远程 HTTPS MCP + 用户 OAuth。需先完成平台与 Router 的远程 OAuth 兼容及工具导出，再由用户连接并核验工具；本次源码开发不代表该链路已经可用。工具描述应包含 Jev 使用语义，因为 ChatGPT 未必加载本地 Skill。CLI 产生连接信息不等于已经修改 ChatGPT 的连接设置。
+
+使用客户端的工具发现能力，确认实际工具 schema 和授权信息。有些客户端会给工具名添加服务前缀；按发现的工具调用，不猜前缀，不依赖本地 `numa serve` 就证明远程 Router 已导出同样工具。以下名称和参数是本包配套实现的契约，旧环境缺少时报告未部署/未连接。
+
+## 工具契约
+
+`numa_jev_capabilities` 无参数 `{}`，查询需要 `jev-runtime-access/view`。检查启用状态、密钥配置状态、模型与限制；能力查询不调用推理，也不能证明出网代理通畅。
+
+`numa_jev_decide` 输入是 **`body` 包装对象**：
+
+```json
+{
+  "body": {
+    "state": "客户说：付款失败了三天，请尽快帮忙。",
+    "questions": {
+      "urgent": {
+        "type": "noul",
+        "instructions": "客户是否明确要求尽快处理？",
+        "criteria": {"true": "明确要求尽快处理", "false": "没有此类诉求"}
+      }
+    }
+  }
+}
+```
+
+调用需要 `jev-runtime-access/edit`；获得 MCP 连接权限不自动获得 Jev 权限。`model` 可省略，让平台选默认模型。只有用户需要指定且 capability allowlist 支持时才提交；不要将 TypeSafe 直连的模型别名直接替换到 OpenRouter 协议。
+
+当前企业合同：1–16 个问题；Choice 2–32 个候选；Score 2–10 个等级；请求最大 256 KiB。以部署环境返回的能力及 schema 为准。state 可为字符串、对象、数组。核心示例使用字符串说明；若使用结构化 instructions/criteria，先确认目标部署支持该版本。
+
+成功结果读取 `structuredContent.data`，外层 `status` 应为成功状态，里面保留原生 `model`、`answers`、`usage` 及上游存在时的 `id`、`provider`。先检查 MCP `isError`，不要将错误内容当作答案；缺少预期问题答案或类型不符时停止业务分支。
+
+## 失败与结果
+
+| 现象 | 下一步 |
+| --- | --- |
+| 工具不可见 | 检查客户端连接、Router 工具导出与 scope；报告当前缺口 |
+| 401 | 检查平台用户 OAuth 或机器令牌；不复制浏览器 Cookie/令牌缓存 |
+| `JEV_ACCESS_DENIED` | 检查已发布 `jev-runtime-access` 权限及正确调用身份 |
+| `JEV_UPSTREAM_FORBIDDEN` | 平台维护者核对供应商账户、地区、模型；不换身份绕过 |
+| 402 / 上游额度错误 | 由平台账户维护者处理；客户端不索取上游 Key |
+| 429 | 区分平台并发和上游限流，记录安全错误码与 request ID |
+| 网络错误、5xx、代理未配置/不可达 | 报告服务故障；平台代理需修复，不能直连回退 |
+
+推理调用可能计费，超时、断连或审计失败时原请求可能已完成；不自动重复 `tools/call` 或 POST。机器令牌过期可以刷新以备后续独立请求，但不据此重放结果未知的判断。需要再次评估时沿用明确任务授权并告知可能重复用量。
+
+输出问题结果、必要分布/用量与本次限制。低置信度和服务错误是不同情况；服务错误不能填成 0 分或“无风险”。本工具只提供判断，后续部署、发送消息或修改数据仍按原业务工作流执行。

package/skills/numa-jev/references/upstream.md

@@ -0,0 +1,13 @@
+# 来源与定制范围
+
+基础是 [typesafe-ai/skills](https://github.com/typesafe-ai/skills) 的 `typesafe-ai` Skill，版权为 `Copyright (c) 2026 TypeSafe AI`，MIT 许可原文随本包 [LICENSE](../LICENSE) 保留。
+
+本次读取本地已安装 `typesafe-ai/SKILL.md`，SHA-256：
+`71ea90d7906c6554c4f4c460ef7361b2d26f59116ccdae986dc6d997b9389f52`。
+未从安装内容确认 Git commit，因此不声称对应某个上游发布版本。维护时比较该文件与新的官方 Skill，保留许可并复核改变的 API/概率语义。
+
+定制内容是企业认证与 MCP 接入、平台代理边界、三种客户端场景和故障处理。保留官方关于状态、问题含义、独立问题并行、概率解释及程序组合的设计方法；不复制全部在线手册。
+
+平台仓库旧版 `skills/numa-jev` 指导 `numa request` / Python 包装脚本调用 HTTP。本包优先指导 Agent 使用已连接的 MCP 工具；HTTP 仍供服务端应用集成。迁移时分别发布新的 Skill 和 MCP 定义，验证工具可见后切换；不覆盖旧版安装目录，也不假设同名 Skill 会自动更新。发布前检查同名资源已有版本，以实际 registry 信息确定版本，`0.1.0` 仅为当前源码版本。
+
+在线资料核验日期：2026-09-28。已读取文档索引、API、Score、Confidence、结构化描述、Intent routing 和 OpenRouter Jev 文档。`.md` 地址失败时使用标准页面；概念以官方资料为准，企业实际支持范围以平台能力和工具 schema 为准。