在 Cursor 里用 Jev:规则、技能与自建 MCP 包装层
Cursor 是一个带 agent 的编辑器,而 agent 身上有四个地方可以放指令和集成:.cursor/rules 里的项目规则、AGENTS.md、.cursor/skills 下的技能、以及 mcp.json 里的 MCP server。这篇文章讲的是:当你接进来的东西是 jev api——一个不对着文本续写、只对一份 state 回答结构化问题的模型——这四个地方分别该放什么。
来源说明: 下文中每一条 Cursor 行为都来自 Cursor 官方文档(
cursor.com/docs/rules、/docs/skills、/docs/mcp,2026-11-12 读取);每一条 TypeSafe 行为、阈值和实测答案都来自docs.typesafe.ai(introduction/coding-agents、agent-skill、introduction/quickstart、models、confidence、primitives/choice、changelog,同日读取)。文中出现的数字就是源文档里的数字,没有编造的示例。
先说清楚:Cursor 能用 Jev 做什么、不能做什么
TypeSafe 的 coding-agents 页面在这件事上罕见地直接,搞错了就是浪费好几天:
Jev 不是 Claude Code、Cursor、opencode、Copilot、Muse Spark、Grok Bot 之类工具背后那个 LLM 的替代品。
原因是结构性的。Cursor 的 agent 会流式输出文本、调工具、按自然语言指令改文件;Jev 一样都不做——它拿一份 state 和一组带类型的问题,每个问题回一个答案,答案被约束在你给的选项里。Cursor 的模型下拉框里没有 Jev 这一项,也没有哪一行 model: "jev-latest" 能改变编辑器的行为。
按 TypeSafe 自己的分法,你真正想做的事属于下面四类之一:
| 你其实想做什么 | 官方指的路 |
|---|---|
| 让 Cursor 更会写调用 TypeSafe 的代码 | 装 TypeSafe 的 agent 技能,里面带问题类型、架构模式和请求组织规范,agent 就能生成正确的集成代码 |
| 在你正在做的应用或 agent 里面用 Jev——分流、分类、打分、护栏 | 从 Quick start 开始,再看 primitives 参考和 patterns |
| 换掉 Cursor agent 背后的模型 | 不是这件事该用的工具。继续用 LLM 做 agent,Jev 单独用 |
| 先不写代码试一下 Jev | 用 Playground:贴一段 state,加几个问题,看答案 |
下面所有内容都属于第一行和第二行。第三行是死路,第四行根本不需要集成。
四个位置,各管什么
| 位置 | 在哪里 | 接 Jev 时适合干什么 | 干不了什么 |
|---|---|---|---|
| 项目规则 | .cursor/rules/*.mdc(进版本库) | 长期约定:问题和阈值放在哪个模块、门槛是多少、答案怎么记日志 | 装不了可执行代码;规则里写 @template.py 只是让 agent 自己去读的指针,内容不会被内联进提示词 |
AGENTS.md | 项目根目录和任意子目录 | 同样的约定,用纯 markdown 写,不需要 frontmatter 和元数据 | 没有 glob 作用域,也没有「只手动触发」模式 |
| 技能 | .agents/skills/、.cursor/skills/、~/.agents/skills/、~/.cursor/skills/ | 一个含 SKILL.md 加 scripts/、references/、assets/ 的目录——真正调 Jev 的代码放这里 | 按需加载,不是保证加载;相关性由 agent 自己判断 |
| MCP server | .cursor/mcp.json(项目)或 ~/.cursor/mcp.json(全局) | 一个对外暴露 judge 工具的进程,任何一轮都能调 | 要你自己写、自己托管;TypeSafe 没有可安装的现成 server |
规则、技能、MCP server 不是三个互斥选项。一个干净的 Jev 项目这样分层:规则放约定,技能或普通模块放代码,只有当你希望「不用 agent 现场写调用点也能拿到判断」时才加一层 MCP 包装。
规则:frontmatter 三字段决定它什么时候加载
项目规则必须用 .mdc 扩展名。Cursor 文档明确说,.cursor/rules 里的纯 .md 文件会被规则系统忽略,因为它没有 frontmatter 来承载 description、globs、alwaysApply。想用纯 markdown,就去用 AGENTS.md。
三个字段互相作用,决定规则何时被包含:
alwaysApply | description | globs | 行为 |
|---|---|---|---|
true | — | — | 永远包含;globs 和 description 被忽略 |
false | — | 有 | 上下文中出现匹配文件时自动挂载 |
false | 有 | 无 | agent 读 description,觉得相关就拉进来 |
false | 无 | 无 | 只有你在对话里 @ 这条规则时才包含 |
接 Jev 要的是第二行。你的调用代码在特定文件里——一个 api/ 包、一个 judgments/ 模块——只有改那些文件时才需要这条规则占上下文。写成这样,它自己会在你动那个目录时挂上:
---
description: Conventions for calling the jev api from this repo's judgment layer
globs: src/judgments/**/*.py, src/api/**/*.py
alwaysApply: false
---
- All question ids, criteria and thresholds live in `src/judgments/questions.py`.
Never inline a dictionary of options at a call site.
- Every call sends a state plus a map of questions; treat the response as typed
data, not as text to parse.
- Branch on `probabilities[choice]` for Choice answers and on the Noul value
itself. Do not invent a second confidence check for Choice.
- Log the answer id, the chosen option and the probability. Never log the API key.
那两条最要紧。第一条不是随便定的:Cursor 文档建议把常量集中在一处便于 review,TypeSafe 的 agent-skill 页面从另一头说同一件事——「把常量(问题和阈值)集中在一个地方,方便 review」,并补了一句:agent 不擅长写好问题,所以要准备和它来回改,而不是照单全收。
第二条是对直觉的真实纠正。TypeSafe 的 agent-skill 页面把「到处置 confidence 阈值」列成常见问题,给的修法是:Noul 阈值设在值上;Choice 阈值设在 probabilities[choice] 上;confidence 留给 Score,用来看答案是不是分摊在相距很远的档位。
真能收窄范围的 glob
Cursor 文档给的这几种写法,行为跟 gitignore 风格的 glob 一致:
| 模式 | 匹配 |
|---|---|
* | 任意单个文件名段 |
** | 任意层级目录(递归) |
*.ts | 根目录下所有 .ts |
**/*.ts | 任意目录下所有 .ts |
src/** | src/ 下任意位置的所有文件 |
docs/**/*.md, docs/**/*.mdx | docs/ 下的 .md 和 .mdx,逗号分隔 |
规则里该省掉什么
文档列了四件该避免的事,写 Jev 规则时四件都齐:把整份风格指南抄进去(该用 linter)、把每条命令都写一遍(agent 认识 npm、git、pytest)、为很少出现的边界情况写指令、以及把代码库里已有的东西再抄一遍而不是指向一个标准示例。规则控制在 500 行以内,太长就拆分。
优先级,以及它为什么跟团队有关
规则按 Team Rules → Project Rules → User Rules 的顺序应用,所有适用的规则合并,靠前的来源在冲突时优先。所以一条被强制执行的团队规则——「所有 Jev 调用都走 src/judgments/client.py」——成员的个人规则关不掉,个人的 Jev 偏好也压不过它。管理侧在 dashboard 上有「Enforce this rule」开关;不强制时,团队成员可以在 Customize 里自己关。
AGENTS.md,包括嵌套写法
AGENTS.md 是不带元数据的纯 markdown。在 Jev 项目里,它就是放简短易读约定的地方,省得维护 .mdc 的 frontmatter:
# Project Instructions
## Judgment layer
- Jev answers questions; it does not write code. Do not ask it to.
- Call site: `src/judgments/client.py`. Question constants: `src/judgments/questions.py`.
- Noul: act above 0.7, escalate below 0.3, and give 0.3–0.7 its own branch.
Cursor 支持项目根目录和子目录里的 AGENTS.md,嵌套文件会跟父目录合并,更具体的指令优先。在 monorepo 里这正好对上多个判断层:services/billing/AGENTS.md 放账务的选项名和阈值,根目录那份放通用规则。
技能:可执行的那部分放这里
Agent Skills 是一个开放标准,Cursor 从四个位置发现技能:项目级 .agents/skills/ 和 .cursor/skills/,本机级 ~/.agents/skills/ 和 ~/.cursor/skills/。为了兼容,它还会从 .claude/skills/、.codex/skills/、~/.claude/skills/、~/.codex/skills/ 加载——这就是为什么一份写好的技能能同时服务 Cursor、Claude Code 和 Codex。
Cursor 期待的目录结构:
.cursor/skills/
└── jev-judgments/
├── SKILL.md
├── scripts/
│ └── judge.py
└── references/
└── QUESTIONS.md
SKILL.md 带 YAML frontmatter,要关心的字段:
| 字段 | 必填 | 作用 |
|---|---|---|
name | 是 | 小写字母、数字、连字符;必须和所在文件夹同名 |
description | 是 | 这个技能做什么、什么时候用——agent 拿它做匹配 |
paths | 否 | 把技能限定到匹配文件上的 glob;逗号分隔字符串或列表 |
disable-model-invocation | 否 | 设为 true 就变成只能斜杠命令调用,永不自动套用 |
icon、color | 否 | 技能作为 Custom Mode 时的徽章样式 |
有一个容易踩的过时点:旧的 globs 字段仍作为兜底被接受,但新技能该用 paths。从老平台抄过来的技能,要改的就是这个字段。
一个 Jev 技能可以很短,因为重活在脚本里:
---
name: jev-judgments
description: Call the jev api to make a bounded judgement about a file, diff or
ticket — one Choice, Score or Noul question, with probabilities returned.
paths:
- "src/judgments/**"
---
# Jev judgments
Run `scripts/judge.py` with a question id from `references/QUESTIONS.md`.
## Instructions
- Read `references/QUESTIONS.md` before adding a question. Options are fixed there.
- Pass the state as a file path or `-` for stdin; never retype the text into the script.
- The script prints one JSON object. Branch on `probability` for Choice answers.
从 TypeSafe 的技能指引里该带走两条设计经验。一是 description 开头那几个词就是触发词,所以第一句要自包含,别写成泛泛的标签——官方文档把这件事压缩成「前 57 字是自包含的触发句」。二是技能里的 schema 过期时,症状很具体:agent 会自己发明请求或响应字段。这个故障模式值得记住,因为解法是更新技能,不是把提示词写得更长。
如果你已经攒了一堆「智能应用」规则和斜杠命令,Cursor 有内建的 /migrate-to-skills(文档说随 2.4 提供),把 alwaysApply: false 且没有 globs 的动态规则转成技能,把斜杠命令转成带 disable-model-invocation: true 的技能。带 alwaysApply: true 或明确 globs 的规则不会被迁移,因为它们的触发条件本来就跟技能行为不同。
MCP:包装层得自己写
大多数教程在这一段会悄悄地编东西。TypeSafe 没有发布 MCP server。截至 2026-11-12,TypeSafe 的完整文档包 docs.typesafe.ai/llms-full.txt(1,359,974 字节)里 MCP 一次都没出现——按词边界匹配是零命中。Cursor 那边的 MCP 页面讲的是协议和配置格式,不是一个可以安装的 TypeSafe server。所以诚实的接法是自己写一个薄 server:一个工具,一次 HTTP 调用。
Cursor 的配置分项目和全局两个文件:项目里的 .cursor/mcp.json 放项目专用工具,家目录的 ~/.cursor/mcp.json 放到处都能用的工具。stdio 条目用 type、command、args,可选 env 和 envFile:
{
"mcpServers": {
"jev": {
"type": "stdio",
"command": "/absolute/path/to/.venv/bin/python",
"args": ["/absolute/path/to/jev_mcp_server.py"],
"env": { "TYPESAFE_API_KEY": "${env:TYPESAFE_API_KEY}" }
}
}
}
envFile 只对 stdio 有效——远端 server 不支持,Cursor 给的替代方案是用 shell 配置里的变量做配置插值。插值可用于 command、args、env、url、headers,${workspaceFolder} 解析为项目根。
server 本身很短,因为 MCP Python SDK 会从类型标注和 docstring 生成工具 schema。下面这段的形状严格贴着两个官方来源:SDK 的 MCPServer 加 @mcp.tool() 装饰器,以及 TypeSafe Quick start 里的请求体。
# jev_mcp_server.py — stdio 传输
import json
import logging
import os
import urllib.request
from mcp.server import MCPServer
# stdio 传输下 stdout 承载 JSON-RPC,日志一律走 stderr。
logging.basicConfig(level=logging.INFO)
log = logging.getLogger(__name__)
mcp = MCPServer("jev")
ENDPOINT = "https://api.typesafe.ai/v1/systemone"
@mcp.tool()
def judge_choice(
state: str,
question_id: str,
instructions: str,
options: dict[str, str],
) -> dict:
"""Ask the jev api one Choice question about a state; return the choice, its probability and confidence."""
body = {
"model": "jev-latest",
"state": state,
"questions": {
question_id: {
"type": "choice",
"instructions": instructions,
"criteria": options,
}
},
}
request = urllib.request.Request(
ENDPOINT,
data=json.dumps(body).encode(),
headers={
"Authorization": "Bearer " + os.environ["TYPESAFE_API_KEY"],
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request, timeout=30) as response:
payload = json.loads(response.read())
answer = payload["answers"][question_id]
choice = answer["choice"]
log.info("jev %s=%s p=%.3f", question_id, choice, answer["probabilities"][choice])
return {
"choice": choice,
"probability": answer["probabilities"][choice],
"confidence": answer["confidence"],
"usage": payload.get("usage", {}),
}
这段里三处约束都在干实事,而且各有出处。禁 print 不是风格问题,是协议问题:stdio 传输下 JSON-RPC 消息走 stdout,MCP 官方文档要求绝不要往那里写,要用 logging,它走 stderr。model: "jev-latest" 是 TypeSafe 自己那段 curl 示例里发的字符串。answers 用你给的问题 id 做键是文档写明的契约——模型从来看不到这个 id,所以你选的 id 就是回来的那个键。
一个诚实的边界:上面这段代码是按那两份官方文档拼起来的,写这篇文章时没有用真实 TypeSafe key 跑过,所以请当作「形状已验证」而不是「二进制已测试」。端点、请求头、jev-latest 模型串、响应结构都是照源文档抄的;重试策略不是,而那正是上线前要你自己补的部分。
该写进规则、不该写进提示词的数字
一条只说「检查置信度」的 Cursor 规则,生成出来的代码会去查错的那个数。下面是官方给的起点,原样写进规则正文。
Noul。 值本身就是「这句话为真」的概率。TypeSafe 给的起点是 0.7 判是、0.3 判否,并说 0.3–0.7 这一段要给它在代码里单独的结果,而不是四舍五入到某一边。
Choice。 confidence 由最高概率算出来,所以拿它设阈值不构成第二重校验。该设阈值的是 probabilities[choice],它直接读作「所选选项有多可能对」。文档给的那张换算表说明了为什么绝对数字只有相对于选项数量才有意义:
| 选项数 | confidence 恰好 0.5 时对应的最高概率 |
|---|---|
| 2 | 0.75 |
| 3 | 0.67 |
| 10 | 0.55 |
Score。 这里 confidence 带着「位置」藏起来的信息。三个档位时,probabilities (0, 0.5, 0.5) 的 confidence 是 0.25——卡在相邻两档之间;而 (0.5, 0, 0.5) 是 0——卡在两端。文档那个算例 probabilities (0, 0.57, 0.43) 得出约 0.35。
一个「健康答案」长什么样。 Quick start 记录的那次工单响应很适合当校准参照:department 回 technical,confidence 1.0,probabilities 1.0/0.0/0.0;frustration 得 0.67,confidence 0.5,probabilities 0.33/0.67/0.0;is_urgent 回 0.99;usage 是 input_tokens 428、output_tokens 73。TypeSafe 明确说这些是示例结果、跨版本可能变化——这正是规则里不该硬写「一定会回什么」的理由。
成本。 当前所有模型同价 $42/Btok、$0.042/Mtok,只按输入计费,输出 token 免费。这个数字该写在批量决策旁边的注释里:一个请求为 state 付费一次,挂多少个问题都算一次。
信任这套集成之前过一遍
- 规则用
globs收窄,除非约定真的适用于每个文件,否则不要alwaysApply: true。 .cursor/rules里的纯.md文件,要么改成.mdc,要么换AGENTS.md。- 问题 id、选项、阈值集中在一个模块,评审的人一屏能读完。
- 代码在 Noul 值上和
probabilities[choice]上分支,不是一刀切查 confidence。 - 自己写了 MCP server 的话:日志走
logging不走print;API key 通过env插值传入,不写进仓库。 - 技能 frontmatter 的
description以自包含触发句开头;参考文件里列清选项名,免得 agent 自己发明。 - 测试里的答案值当 fixture 记录,并标上出自哪个 model id——TypeSafe 说值会跨版本变。
什么情况下这套没用
如果你要的是一个更快或更便宜的 Cursor,上面全部内容都改变不了这一点——Cursor 的 agent 还是跑在自己的模型上,加一个 Jev MCP server 只是多给它一件工具。如果你的判断是开放式的(「把这个重构写了」),Jev 的答案空间形状就不对,规则写得再多也补不上。还有,如果你不打算亲自 review 问题文本,技能会很乐意生成一批听起来很合理、但选项边界写错的问题;TypeSafe 自己的建议就是准备和它一起改,别照单全收。