API
四种语言的函数对照、检测参数、取样规则、结果字段和错误处理。
四种语言的函数一一对应，结果字段名也相同。TypeScript、Rust 和 Python 的字段名和 JSON 一样用 snake_case；Go 的结构体字段用 Go 的命名，序列化成 JSON 后和其他语言相同。
函数
loadDetector(options?: { source?: string | readonly string[]; cache?: string; ttl?: number }): Promise<Detector>
detector.builtAt: string
detector.analyze(outputs: Output[], options?: { strict?: boolean }): Analysis
detector.detect(config: DetectConfig, options?: { signal?: AbortSignal; onSample?: (index: number, sample: Sample) => void }): Promise<DetectResult>
generateChallenges(count = 3): Challenge[]
parseNumbers(text: string): number[]
buildRequest(config: DetectConfig, prompt: string): { url, headers, body } | { error: string }
requestSample(config: DetectConfig, challenge: Challenge): Promise<Sample>
DEFAULT_DATA_URLS: readonly string[]- 加载：
source是数据来源的 URL 列表，或者一个本地目录；cache是缓存文件，ttl是缓存多久检查一次更新。行为见参考数据。built_at是参考库的生成时间，可以用来判断数据有没有更新。 - 评分：
analyze的输入是一到三条{ text, expected_count }。expected_count是挑战要求的整数个数，必须是正整数。 - 生成挑战：
count取 1–3，每道挑战带id、prompt和expected_count，同一轮的expected_count各不相同。 - 解析数字：返回回答里最长的一段 1–355 之间的整数。字母会把数字分成不同的段，标点和空白不会。
- 构造请求：返回
detect会发出的 URL、请求头和 JSON 请求体，不发送请求，可以用来检查参数是否正确。 - 发送一道挑战：只发一个请求并检查回答，不评分；失败写在返回样本的
error里。
检测参数
TypeScript 用 camelCase（baseUrl），Go 用结构体字段（BaseURL），Rust 和 Python 用 snake_case（base_url）。
| 参数 | 说明 | 默认值 |
|---|---|---|
base_url | Base URL 或完整端点。只写到主机名时补上 /v1；带路径时保留路径，再加上所选 API 的端点 | 必填 |
api_key | API Key，只出现在请求头里；错误信息中的 Key 会被替换成 [REDACTED] | 必填 |
model | 请求的模型名 | 必填 |
api | responses、chat_completions 或 messages。Rust 用 Api 枚举，Go 用 APIResponses 等常量 | responses |
effort | 推理强度，例如 low、high；Messages 下 none 表示关闭思考 | 空，不发送 |
service_tier | flex、default、fast 或 ultrafast。Messages 中作为 speed 发送，其他 API 中作为 service_tier 发送 | default，不发送 |
stream | 用 SSE 流式响应；关闭后用普通 JSON 响应。Go 用 NoStream 字段关闭 | 开启 |
strict | 严格模式：不截断，三条回答都完整有效才评分；要求 count 为 3 | 关闭 |
count | 每轮的挑战数，1–3 | 3 |
parallel | 并发请求数，1–3，不超过 count | 3 |
timeout | 时限，单位秒（Go 是 time.Duration）。设为 0（Go 为负数）关闭超时。SSE 只限制等第一个响应体数据的时间，开始传输后不再限时；JSON 限制整个响应。Rust 和 Python 不能中途取消，关闭超时后，如果连接已建立但服务端一直不返回数据，detect 会永久阻塞 | 120 |
Go 的字段零值就是默认值，比如 Count: 0 表示 3 道挑战。Rust 用 DetectConfig::new(base_url, api_key, model) 创建默认配置，再修改字段。Python 的 detect 用关键字参数；build_request 和 request_sample 接受同名键的字典。
配置无效时，detect 和 build_request 在发出请求前报错，信息是下列之一：
base_url, api_key, and model are required.
api must be responses, chat_completions, or messages.
service_tier must be flex, default, fast, or ultrafast.
count must be an integer from 1 to 3.
parallel must be an integer from 1 to 3.
timeout must be 0 (no timeout) or between 0.001 and 2147483.647 seconds.
strict requires count 3.
Base URL must be a valid HTTP or HTTPS URL.
Base URL must use HTTP or HTTPS without credentials, a query, or a fragment.
The endpoint in --baseurl does not match --api.进度
detect 可以传一个回调，样本每变化一次就调用一次，参数是样本在 challenges 和 samples 里的下标和当时的样本。
const result = await detector.detect(config, {
onSample: (index, sample) => console.log(index, sample.state, `${sample.count}/${sample.expected_count}`),
})每条样本的状态依次是：
queued：发请求前，所有样本按下标各报一次。waiting：请求已经发出。streaming：收到第一个 SSE 响应体数据，first_byte_ms有值了。之后每收到一段文本就再报一次，count逐渐增加。JSON 响应没有这一步，状态停在waiting，直到读完整个响应。- 最终状态：
complete、truncated、failed或cancelled。每条样本只报一次，和返回结果里的样本相同。
同一个状态可能连续报多次。流式响应每到一段文本就回调一次，界面需要的话自己限制刷新频率。
回调不会同时执行，所以不用自己加锁。Rust、Go 和 Python 的回调在 SDK 的工作线程里执行，回调慢会拖慢取样。回调出错不会让样本失败：TypeScript 中抛出的错误会作为未捕获异常单独报告，检测继续；Rust 和 Go 的 panic、Python 的异常会从 detect 传出来。
取样规则
detect 的取样规则和命令行检测相同：
- 宽松模式下，流式回答收到
expected_count个整数后就停止读取，样本状态为truncated；JSON 回答超出的部分会被截掉。 - 回答必须正常结束：结束原因是
stop、end_turn或completed。拒答、内容过滤和未完成的回答都算失败，除非宽松模式已经截断。 - 有效回答至少要有
max(80, ceil(expected_count × 0.55))个整数。 - 不跟随重定向，不自动重试。失败的样本留在结果里。
结果
Analysis
analyze 返回的、以及 detect 结果里的 analysis：
| 字段 | 说明 |
|---|---|
decision | scored、partial、unscorable 或 not_model，见读结果 |
prediction、prediction_name | 第一名的模型 ID 和显示名；没有排名时 ID 为空 |
family_prediction、family_prediction_name | 第一名所属的模型家族 |
results | 全部候选，按排名分数从高到低：model、display_name、family、family_name、score、probability |
ranking_score | 第一名的排名分数，没有排名时为 null |
probability | 第一名的置信度，即参考库内的封闭集合概率；只有 scored 且校准有效时才有值 |
probability_status | reference_calibrated 或 unavailable |
probability_scope、calibration | 置信度的范围和所用校准，没有置信度时为 null |
used_outputs | 有效回答的条数 |
diagnostics | 每条回答的解析情况：parsed_numbers、minimum_numbers、accepted，以及超出 1–355 的数字个数 raw_out_of_range_count |
sequence | 语言模型回答检查的指标：autocorrelation、small_step_share、model_like；没有有效回答时为 null |
method、model_version | 评分方法和检测参数的版本 |
evidence | 结果的标签 label 和英文说明 reason |
Sample
detect 结果里的每条样本，也是 request_sample 的返回值：
| 字段 | 说明 |
|---|---|
state | complete、truncated 或 failed；TypeScript 和 Go 取消时为 cancelled。进度回调里还会出现 queued、waiting 和 streaming |
text | 用来评分的文本；截断时只保留前 expected_count 个整数 |
raw_text | 收到的原始文本 |
count、expected_count | 解析出的整数个数和要求的个数 |
first_byte_ms | 从发出请求到收到第一个 SSE 响应体数据的毫秒数；JSON 响应是到读完并解析整个响应。没收到时为 null |
response_model、response_id | 接口返回的模型名和响应 ID，没有时为 null |
error | 失败原因，成功时为 null |
DetectResult
detect 的返回值有四个字段：challenges（这一轮的挑战）、samples、analysis 和 error。error 为 null 时，analysis 一定有排名。error 不为空的情况有：
error | 原因 |
|---|---|
No valid samples. This round cannot be scored. | 所有样本都失败 |
Strict mode requires 3/3 successful samples; received N/3. | 严格模式下有样本失败 |
analysis.evidence.reason 的内容 | 有 analysis 但没有排名，比如 not_model |
Cancelled. This round was not scored. | 检测被取消（TypeScript 和 Go） |
Scoring failed. Check that the reference bank and detector files are valid. | 数据文件损坏 |
错误处理
| 语言 | 方式 |
|---|---|
| TypeScript | 抛出 Error；buildRequest 例外，返回 { error } |
| Rust | 返回 Result<T, lmfpd::Error> |
| Go | 返回 error |
| Python | 抛出 lmfpd.LmfpdError |
analyze 的输入不是一到三条带正整数 expected_count 的回答时报错：Each input round must contain one to three outputs with text and a positive integer expected_count. request_sample 不报错，配置错误和请求失败都写在样本的 error 里。
取消
TypeScript 的 detect 用 options.signal 取消，Go 的 Detect 和 RequestSample 跟随 ctx。取消时，进行中的请求立即中止，还没发出的挑战不再发送，样本状态为 cancelled，这一轮不评分。Rust 和 Python 的 detect 不能中途取消，只能靠 timeout 结束卡住的请求，所以在这两种语言里把 timeout 设为 0 时，一个连上后不返回数据的请求会让 detect 和 request_sample 永久阻塞。
最后更新于