企业官网建设流程全解析

TypeSafe 提出了一种把 AI 能力"原语化"的编程模型：让 System One 模型（其旗舰模型 Jev）对自然语言和应用状态返回类型化判断与概率，而不是生成文本，从而让代码掌控工作流、模型只提供可编程的"常识"。本文以仓库中的 typesafe-ai 技能文档 为骨架，系统讲解 TypeSafe 的编程模型、三类判断原语（Choice / Noul / Score）、问题与状态设计原则、组合与验证方法，并结合本仓库中真实使用 Jev 的检索工具 jevgrep 的源码，说明这套方法论在工程中如何落地。

读完本文，你将掌握：如何从应用行为反推所需判断、如何用三种原语表达"选一个 / 是否成立 / 程度如何"、如何设计 state 与 criteria、如何在并行组合中正确解读概率与置信度，以及如何像 jevgrep 一样把 Jev 的判断接入真实的检索管线。

核心编程模型：AI 智能以原语形态进入代码

TypeSafe 的核心主张是：把"小单位的 AI 智能"当作编程原语来使用——一次调用返回一个快速、聚焦的判断，代码把这些判断组合成更大的能力。这与传统"让 LLM 生成一段文本或解释"的用法有本质区别：

• System One 模型返回的是类型化答案与概率，而非自然语言段落或推理说明；
• Jev是 TypeSafe 旗舰的、也是第一个 System One 模型，它"理解自然语言，返回类型化答案和概率"；
• 代码拥有工作流：判断的顺序、组合、重试、回退都由代码决定；模型只在普通代码需要语义理解的地方提供"可编程常识"。

这套定位决定了 TypeSafe 的典型应用形态：路由、排序、抽取、校验、交互式体验等，本质都是"把一次 LLM 的 prompt-and-parse 步骤变成一个结构化的决策"。

在本仓库中，Jev 正是被这样使用的：jevgrep 的核心诉求是"用自然语言问仓库问题，返回相关文件与源码片段"，而相关性判断完全交给 Jev。在 providers.ts 中可以看到 Jev 通过四个渠道接入：Vercel AI Gateway（模型typesafe-ai/jev）、TypeSafe 官方端点（模型jev-1.13.0）、OpenRouter（模型typesafe/jev-1.13）、OpenCode Zen（模型jev-1.13）。每次求值返回的是Record<string, number>这样的概率表（见 types.ts 中的Evaluator.evaluate签名），代码直接消费这些数值做阈值判断，而不是解析自然语言。

以实时文档为第一事实来源：技能使用的三条准则

技能文档反复强调：实时 TypeSafe 文档是事实来源，读取文档本身就是任务的一部分。技能文件只给出方向，概念、提示词指导、API 契约、SDK 用法、模型与限制、可运行示例都在文档中。实践上有三条准则：

1. 从文档索引出发做定向阅读：先读文档索引页发现相关页面与 cookbook，做"定向读取"而不是把整个站点加载进来。
2. 利用 Markdown 交付机制：Mintlify 通过在页面路径后追加.md返回 Markdown（例如把无扩展名页面链接转为.md），按需获取便于 Agent 阅读的纯文本版本。
3. 集成前必读、新流程必看 cookbook：写集成代码之前，先读当前 API 或 SDK 页面与问题设计指南；对于全新工作流，还要看最接近的 cookbook——它往往展示出比"通用分类器"更好的分解方式。

技能同时给出了兜底策略：索引不可用就用直接链接或站点导航；Markdown 抓取失败就访问普通页面；实时访问完全不可用则改用本地文档或已安装 SDK 的类型定义，明确说明这一限制，并避免臆造依赖版本号的细节。

下表是技能给出的"任务 → 起始资料"速查：

对应到本仓库，jevgrep 的 CLI 包说明 与 jevgrep 技能文件 扮演了类似角色：它们定义了jg的安装、认证、调用与输出语义，是 Agent 使用 Jev 检索能力的操作契约。

从用户行为反推判断：六类可组合的形态

技能给出的第一设计原则是：从用户想要的行为出发，倒推它需要的判断。用户希望应用"展示 / 选择 / 改变 / 交接"什么？需要哪些判断？已知规则、计算、精确查找与执行留在代码里；只在"语义理解有帮助"的地方引入 TypeSafe，并保留用户既有的技术栈与范围。

在此基础上，技能列出了六类可组合的形态，它们不是固定配方，而是起点：

1. 路由并填充已知参数（Route and fill known arguments）：请求可以选择一个 handler 及其类型化参数。提前提出对分支有用的问题，只消费相关答案。可参考函数调用（function calling）与投机式扇出（speculative fan-out）两个模式。
2. 选择而非生成（Select instead of generate）：在代码中找出候选值或源码区间，用一次判断选出目标值，再复制或规范化它。代码也可以把源码拼装成格式化文档或阅读指南。对应预解析值抽取与结构恢复（autoformat）。
3. 检索并判定证据（Find and judge evidence）：先取回候选，再对比它们与查询的相关性，选出有用上下文。对应重排序（reranking）与分层分类（hierarchical classification）。
4. 把判断沉淀为可复用数据（Turn judgments into reusable data）：一次性对多个维度打分，让代码或用户控件改变权重、阈值、排序与视图；有了标注结果，这些信号还能变成经典 ML 特征。对应组合打分与特征发现。
5. 校验并升级（Verify and escalate）：针对具体声明或字段对照证据核验；把不确定或失败的情况交给人或推理模型。对应引文核查与抽取级联（extraction cascades）。
6. 响应变化中的状态（Respond to changing state）：代码保留目标与观察，让新鲜的判断指导下一个有界步骤。保持"推断状态"与"观察到的事实"分离，在把结果套用到已变化的情境前先检查新鲜度。

对于开放式请求，技能建议只给出最贴合用户目标的少数方向并推荐一个起点；对于具体请求，直接选择相关模式开始构建，不必把头脑风暴当作必经步骤。

jevgrep 的检索管线（retrieve.ts）几乎可以逐条对应这些形态：它"取回候选并判定证据"（对目录、文件、声明打分）、"选择而非生成"（在源码中定位并抽出区间而非生成答案）、"路由并填充参数"（按目录层级逐层决定是否进入子目录）。最有代表性的一处：技能要求"保持推断状态与观察到的事实分离，应用结果前检查新鲜度"，而 retrieve.ts 中每个候选在每次求值前都要通过unchanged()用内容哈希（contentHash）重新校验源文件，源已变化就作废该候选，正是"新鲜度检查"的工程实现。

设计判断：Choice / Noul / Score 三种原语

技能给出了三张核心原语表，按"答案的含义"选择：

围绕这三个原语，技能给出了一套问题设计规范，这些规范直接决定判断质量：

• 给足相关的 state：问题要有足够的上下文——源文本、身份、关系、策略、当前事实。上下文有多个部分时优先用命名的 JSON 字段；用反引号路径（如ticket.messages[0].text）引用嵌套状态。
• instructions 与 criteria 分工：把"要判断什么"放进 instructions，把"答案有哪些可能"定义进 criteria。
• question ID 只给代码：问题 ID 用于代码索引，不会发送给模型；问题的完整含义必须写进问题本身。
• 每个问题只问一个狭窄、连贯的判断：拆分独立有用的维度，但不要破坏被判断的关系。"有界动作选择"或"上下文解释"是合法的；"原子"不意味着"只抽取字面事实"或"一句话限制"。
• 表达方式按需选择：简单问题用字符串；当定义、对比、排除或示例有助于澄清 instructions 或 criteria 时，使用结构化对象或数组。Score 的等级必须描述具体情境、能独立成立。
• 保证答案可用：什么都不匹配时要有 no-match 结果；当"是否存在"本身独立有用时，用单独的 presence 判断；对"从源码取值"的选择，要检查候选覆盖——模型无法选择一个被遗漏的值。

本仓库完美印证了"question ID 只给代码"这一设计：在 retrieve.ts 中，一批导航项（NavigationItem）被打包进一个求值请求，返回的分数表以q${index}作为键（scores[q${index}]），代码用这些键把概率映射回对应项目——模型侧看到的是结构化的判断请求，q0/q1这类索引只存在于代码侧。

组合与验证：并行提问、概率语义与策略显式化

技能对"如何把多个判断组合起来"有明确指导：

• 对同一份 state 上相互独立的问题一起提问，包括有用的投机性问题（speculative questions）。它们并行运行、互相看不到对方的答案；每个投机前提都要显式陈述，代码只消费适用的答案。只有当"需要前一个答案才能取证据、构造新 state 或确定下一组选项"时，才值得发起第二次请求。
• 额外的问题同样消耗 token：要实测请求预算、成本与端到端延迟，而不是想当然。
• 用概率和置信度引导行为，阈值要在用户数据与后果上评估：Choice/Score 的置信度总结的是"分布集中度"，不是"整个工作流正确性"或"行动许可"。Noul 接近 0.5 意味着 yes 与 no 概率相近，而不是中等强度；多个可接受选项也会摊薄概率，所以低置信度不一定意味着无害偏好选择无效；对未使用的分支要忽略不确定性。
• 策略保持显式、原始判断保持可复用：加权分数适合"互相补偿的偏好"，而"任一严重违规即拒绝"需要独立条件。证据与问题含义不变时，改权重或显示过滤无需重跑推理。类型化输出保证的是接口契约，不是事实；System One 模型经过校准训练，但要在目标领域验证其表现。
• 测试有代表性的用例与最终应用行为：失败时检查精确的 state、问题、候选、答案、组合方式与观察结果，区分"证据缺失 / 模型错误 / 代码错误 / 服务故障"。cookbook 中的阈值与演示结果是供评估的示例，不是放之四海皆准的规则，更不是模型的永久限制。Web 应用中的 API 凭据必须保存在服务端。

jevgrep 的管线是这套组合哲学的完整示范（retrieve.ts）：发现阶段用 32 个并发 worker（stageWorkers = 32，与 CLI 文档中"默认 32 并发上限"一致）并行地对目录/文件打分；分数按批提交，单批最多 128 项或 JSON 不超过 38,000 字节；目录与文件以probability > 0.5为接纳阈值——这正是"阈值要在用户数据上评估"的实例化。批次失败时还会对半拆分重试（retrieve.ts），区分"可恢复的提供方错误"与"真正失败"。技能要求"独立问题并行、互相看不到答案"，对应求值器每次调用返回独立概率表；而"证据缺失 / 模型错误 / 代码错误 / 服务故障"的四分法，对应 retrieve.ts 中对 issue 的分类记录（authentication、request-limit、cancelled、interrupted等）与最终incomplete状态的上报。

仓库实践：jevgrep 如何把 Jev 判断接入检索管线

提供方与凭据

Jev 通过四个提供方接入（providers.ts）：

凭据管理在 auth.ts 中实现，与技能"凭据保存在服务端"的原则一致：jg auth交互式选择提供方并输入密钥；jg auth --provider NAME --stdin支持从管道读取密钥用于自动化。密钥写入$XDG_CONFIG_HOME/jevgrep/credentials.json（缺省~/.config/jevgrep/credentials.json），目录权限0700、文件权限0600，并通过"临时文件 + rename"原子写入；密钥校验要求非空、无空白、不超过 8 KiB（auth.ts）。

CLI 参数与退出码

技能文档指向"阅读当前 API 文档"；对 jevgrep 来说，操作契约就是 args.ts 与 CLI 包说明：

• jg "question" [root]：根目录默认当前目录；
• jg auth [--provider NAME --stdin]：选择提供方并保存密钥；
• jg doctor：用合成输入验证 Jev 访问与连通性；
• jg skill [--agent NAME] [--global] [--yes]：把 jevgrep 技能 安装进 Agent 所在项目；
• jg cache clear与--no-cache：本地求值缓存控制；
• 搜索选项：--max-source-bytes N（0 表示不限，默认值定义于 render.ts）、--hidden、--no-ignore、--include-dependencies、--include-sensitive（各旗标只放宽对应的排除类别，Git 元数据与 jevgrep 自身存储始终排除）、--concurrency N（慢网络推荐 1–4，默认 32）；
• 退出码：0完成、1失败、2不完整、130中断；所有输出走 stdout，不生成报告文件。

检索管线中的判断调用

retrieve.ts 是"代码拥有工作流"的完整实现，判断全部由 Jev 提供：

1. 发现（discover）：从根目录逐层列出条目，目录预阅最多 64 项或 4096 字节，文件预阅取开头 16,384 字节；超过 100,000 条目录项触发resource_limit。大文件按 12,000 字节切块（splitSource），每个切块作为独立候选。
2. 导航打分：对一批候选提交navigationRequest，probability > 0.5的目录继续深入、文件进入候选表，其余目录被剪枝（pruned）。若在候选中发现.context结尾的声明类（class），会以它为锚点（anchor）对剪枝目录做一次"关系重审"。
3. 文件评估与选择：selectFile定位有用源码单元与周边上下文；fileAssessmentRequest并行产出角色标签（如test）与优先级，标签阈值同为> 0.5。
4. 证据复选与测试体选择：已选片段作为证据供第二轮选择参考；被标记为测试的文件再走selectTestBodies，把测试体也纳入呈现。
5. 局部调用上下文与仓库上下文：localCallContext补充调用者线索（callLeads）；repositoryContext汇总指令文件与 pytest 文件，供后续编码阶段使用。

整个管线对每次求值都做内容哈希新鲜度校验，最终产出 types.ts 定义的RetrievalResult：status（complete / incomplete / interrupted）、文件证据列表（path、score、roles、leads、selected、excerpts、sourceOmitted 等）、issue 清单与请求/缓存命中/检视文件计数。

输出契约：证据而非答案

技能强调"类型化输出保证接口，不保证事实"；jevgrep 的输出同样如此。按 jevgrep 技能文件 的约定：摘要与排序文件列表在前，随后是逐字源码摘录与详细位置；没有摘录的路径是额外阅读线索；摘录可能是部分的，需要借助文件与行号继续阅读；相关性标签是估计值，不保证完整性；完整上下文以End context.结束。仓库 README 也明确：输出是给 Agent 的证据，不是生成的答案，也不保证找到了所有相关文件——检索不完整或出错时，把缺失的上下文视为未知，jg doctor负责排查提供方配置。

这与技能"用判断引导行为、把 cookbook 结果当示例评估"的态度一脉相承：Jev 提供校准过的判断与概率，工作流、阈值、回退与验证全部由 jevgrep 的代码显式承担。

从技能到工程：落地检查清单

综合技能文档与仓库实现，把 TypeSafe 集成进真实应用时，可以按以下清单自查：

1. 形态：从用户行为倒推判断；能留在代码里的规则、计算、精确查找不要外包给模型。
2. 原语：按答案含义选择 Choice / Noul / Score；每个问题狭窄、连贯、含义完整自足。
3. state：命名 JSON 字段、反引号路径引用嵌套状态；问题要能独立回答。
4. 覆盖率：包含 no-match 结果；选择类任务检查候选覆盖，模型选不到未提供的值。
5. 组合：同一 state 上的独立问题并行提问，投机性前提显式声明；第二次请求只在必要时发起。
6. 概率语义：Noul 0.5 是"是/否概率相当"而非中等强度；低置信度不自动否决无害偏好；未用分支忽略不确定性。
7. 策略：显式表达策略（加权 vs 一票否决）；证据与问题不变时，调权重/过滤不重跑推理。
8. 验证：代表性用例 + 失败四分类（证据缺失 / 模型错误 / 代码错误 / 服务故障）；阈值在用户数据上校准；凭据只存服务端。

jevgrep 用 Jev 判断目录、文件与声明的相关性，把"自然语言问仓库"变成可组合、可校验的检索管线，正是这套方法论在真实工程中的一次完整落地。想进一步深入检索、解析、缓存与失败处理的设计细节，可以继续阅读本仓库的 架构文档、实现记录 与 基准评估说明。