一篇文章助你掌握 Jev 开发所需的一切

代码、架构、图表……你需要的所有内容，助你跟随构建并打造属于自己的方案。 https://t.co/0hy2KdKUNI

---

如何使用 Jev 构建智能体控制框架（开发者指南）

我将逐步讲解如何使用 Jev 构建一个智能体控制框架，并详细说明决策层的设计思路，包含每一步的代码和图表解释。

太长不看版：若不想阅读这 3500+ 字的长文，可直接使用此 GitHub 仓库并交给你的智能体 ➡️ https://github.com/codejunkie99/keel

现在开始（正文启动）

代码之前：为决策赋予形态

我想要一个能持续改进的编码智能体。 同时希望清晰了解其每次变化。

系统仍需选择模型并限制工具范围，随后需验证选择并评估结果。

这正是 Jev 工程的用武之地：为系统提供可审查的选择，并保留足够证据来判断该选择是否有效。

有效决策的要素

每个小决策需要三要素：

• 明确的选项列表。
• 代码可验证的结果。
• 后续发生的记录。

最后一点至关重要。每次额外的模型调用都必须证明其价值。

我们构建的框架概览

本文将分三部分讲解：

• 我们如何将 Jev 作为决策层。
• 为何编码框架是部署该层的理想位置。
• 在 Keel 中构建的内容及各组件协作方式。

第四部分将探讨标题承诺的“自我改进”：决策记录能实现什么，尚不能证明什么。

模型可建议下一步行动，但宿主始终掌握最终决定权。

这一区分看似微小，却改变了整体架构。

01 / Jev 的应用方式

赋予 Jev 精准明确的职责

在本构建中，Jev 从宿主预设的列表中进行选择。“宿主”指围绕模型的应用程序代码。

宿主在 Jev 介入前已确定可用选项。

它返回类型化结果：固定格式供代码验证。结果表示“选择此项”或“无法选择”。

这就是全部契约。

保持菜单由宿主控制

宿主准备菜单；Jev 从中选择；宿主再次验证选择。

限制接口范围有实际考量：

若允许模型返回任意指令，应用中所有调用方都需解析该指令含义。

使结果易于验证

固定格式使任务变得简单明了：读取结果、核对当前状态、接受或使用备选方案。

可将其类比为繁忙车间的调度员。调度员可决定哪个工位获得任务，但无法暗中修改锯床的安全规则。

选择器可操作的两个场景

选择器可在两个编码工作流决策点发挥作用。它们看似相似，但发生于不同时机。

1. 为新任务选择路径

当新任务未指定提供方或模型时，宿主可准备合格的提供方/模型候选列表。

Jev 或本地 Laya 可从中选择或弃权。

指定路径是用户已选定的方案。选择器会保留该选择，包括实时和恢复的会话。

在请求前过滤选项

“选择最佳模型”需界定范围。宿主必须能运行其提供的每个选项。

在 Jev 查看前先过滤选项。 宿主移除无法提供的路径：

• 提供方未安装或启用。
• 模型不可用。
• 请求的推理级别不支持。

即使路径通过宿主检查，提供方仍会在会话开始时验证登录状态。

2. 在 DeepSeek 内部选择下一步骤

循环提供四种聚焦选择：

• 检查
• 实现
• 验证
• 回答

每个选择映射到宿主定义的工具包。

选择器返回聚焦 ID。宿主查找允许的工具，并在使用前核对当前工具定义。

“回答”意味着无工具

“回答”是个典型示例。它不配备任何工具。

若选择器返回“回答”，系统不会交付命令行并寄望其遵守规则。

允许的工具包为空，因为这就是“回答”在此处的含义。

这些不同于要求 Jev 控制应用中所有编码智能体。它并不具备此能力。

通过小示例厘清分工

假设请求应用修复解析器错误。这是示例说明，非实际构建测量结果。

若已指定提供方，该选择将保持不变。

若为未指定的新任务且自动选择已启用，宿主可提供合格路径。

选择器在此列表中选择；它无法调用不存在的提供方。

现在选择下一步骤

随后在嵌入式 DeepSeek 循环内，决策更细分：检查、实现、验证或回答。选择“验证”会改变允许的工具包。

这不能证明补丁正确。 检查仍需运行，且结果需有实际意义。

这正是设计精妙之处。

“使用哪个工作者？”与“接下来用哪些工具？”需要分别界定边界，因为它们是不同职责且具有不同故障模式。

关键边界：外部智能体保持独立循环

Keel 可通过智能体通信协议（ACP）托管多个编码提供方。

这些提供方运行自己的工具循环，也可能暴露工具、上下文大小或交接控制。

Keel 并不从始至终控制所有步骤。

在此构建中，Jev 和 Laya 不接管这些内部流程。

已列命令仍需可用 API

我们可读取提供方能力描述。仅有描述不足以让宿主执行该操作。

已列的斜杠命令不会自动成为 Jev 可调用的操作。

当前实现中，斜杠命令可能仅作为提供方的提示文本。

明确每个循环的所有者

该边界在图中易被模糊。“智能体”一词使一切看似统一智能体。

实践中存在宿主、决策层，以及可能存在的提供方自有智能体循环。宿主可将新任务路由至提供方。

这并未说明谁控制提供方的下一次工具调用。

能力审计有助于界定此边界。Keel 列出命令、技能、模式和工具。

在代码可执行处划定边界

这些描述说明提供方公开展示的能力。宿主仍需真实方式调用操作并验证结果。

这就是最初 Jev 优先愿景如何演变为更聚焦的实现。边界遵循我们控制的代码。

在架构图上添加箭头不会创建 API。

相邻接口：计算机操作

Keel 亦提供计算机操作决策功能。它允许 Laya 或 Jev 选择宿主准备的低风险操作 ID 或弃权。

该命令不执行桌面操作。

此区分在阅读代码时很重要。选择提议的点击与执行点击是不同职责。

兼容的 ACP 智能体可通过 MCP（工具连接协议）使用已安装的桌面工具。这些智能体仍保持内部循环。

选择与授权是不同概念

Jev 可选择候选方案，但不能批准危险操作。

若工具需要权限，常规权限路径仍然适用。应用要求用户批准时仍需用户授权。

模型选择不授权，高置信度值同样不授权。

操作前再次验证状态

应用选择前，它会检查操作是否仍匹配当前任务状态。

若提供方列表变更或路径过时，宿主可拒绝操作并使用备选方案。

使用前再次检查工具

• 在 DeepSeek 循环内，宿主核对工具集与当前工具定义。运行前再次检查指定工具。
• 两次检查目的相同：防止旧决策作用于已变更的系统。
• 这是必要流程。安全检查正需如此严谨。

为不确定性提供明确路径

“无法选择”是有效结果。 宿主仍需知晓后续步骤。

图表展示路径选择流程。这些流程均不授予工具运行权限。

在调用选择器前定义备选方案。随后记录使用情况，避免备选方案被计入选择器成功案例。

记录展现的内容

应用可在选择器调用期间显示活动。

宿主验证结果并观察结果后，可写入决策事件或回执。

这些记录因其可回答常规工程问题而有价值：

• 候选方案有哪些？
• 选择器是否选择或弃权？
• 验证是否接受？
• 是否发生备选方案？
• 后续工具结果如何？

记录操作与结果

这些并非私有思维链。

我们需要知道：选择是否被允许、宿主是否接受、以及后续情况。

这是有意权衡。收集足够信息以评估系统。

模型解释不能证明事件原因。

02 / 为何置于编码框架中

编码是连续决策链

人们常将编码智能体简化为单次调用：输入提示，输出补丁。

实际工作更似一系列分支：

• 应由哪个模型处理此任务？
• 智能体应先检查文件还是直接编辑？
• 当前相关工具有哪些？
• 决策进行时仓库是否变更？
• 系统应重试、弃权还是询问用户？
• 变更是否编译通过、通过重点检查并保持用户意图？

这些决策成本各异。在小重命名任务中使用慢速模型会浪费时间。

考虑错误选择的成本

错误选择可能比慢速选择代价更高。 快速模型在大型迁移中可能需要更多重试。

工具选择在某工作区可能无害，在另一工作区则可能至关重要。

框架需掌握影响每项操作的细节：

• 当前仓库状态。
• 可用提供方与工具定义。
• 权限与任务状态。
• 检查结果。

模型是系统的一部分，而非系统本身。

框架为决策提供落脚点

独立决策演示可展示模型从三个标签中选择。

这是起点，但无法判断选择是否可用。

在编码框架内，宿主可回答具体问题：

• 这些选择是否真的可用？
• 任务是新的、已指定的还是运行中的？
• 执行开始时所选工具是否仍存在？
• 权限层是否允许该操作？
• 工具返回什么结果？
• 验证是否发现回归？

这些细节让我们可测试决策。同时帮助宿主将选择限制在边界内。

我的观点是：展示选项、选择与结果。 否则智能体改进的说法多属主观臆测。

三种模式，三种不同选择

Laya 与 Jev 是独立选择器。普通模式跳过选择。 图表展示各路径需求及宿主验证结果的位置。

Core ML 是 Apple 的本地模型运行时。Jev 使用设备上已有的保护凭证；本构建无密钥输入界面。

“始终使用最智能模型”忽视延迟、隐私、凭证与用户意图。模式选择为这些权衡在应用中提供位置。

额外调用必须证明其价值

简要说明：路由可能演变成官僚体系。

若选择工作者耗时超过任务本身，我们将制造出精致的候诊室。我关注的比较指标是总任务成本：选择器时间、工作者时间、重试次数与评审精力。

更廉价的决策调用仅在整体任务受益时才有价值。 我们尚未通过编码基准测试证明此收益。

另一明显局限是：选择器无法选择宿主遗忘提供的优质选项。

优秀框架明确区分决策与执行。

• 路由选择时，模型接收候选 ID：引用宿主准备的选项标签。
• 这些 ID 不允许模型发明新命令或提供方。宿主保留运行选择所需详情。
• 嵌入式 DeepSeek 循环内，选择器返回单个聚焦 ID。宿主将该 ID 转化为特定允许工具集。

保持决策层可替换

宿主随后再次检查。

• 这意味着决策层可替换。 调用方无需信任其文本。
• 它依赖宿主检查。这些检查需清晰到可供审查。
• 这正是我青睐小接口的原因。你可精确指出其做出的选择及该选择允许的工具。
• 增加自由度也意味着当运行出错时，需解释更多行为。

框架可展示不确定性而不隐藏

模型系统即使在运营状况混乱时也常生成整洁摘要。框架应保留重要的混乱细节。

• 若选择器弃权，需显示。若宿主拒绝过时操作，需显示。
• 若宿主回退到用户原始路径，需记录备选方案。

这些细节不是杂乱信息。

它们让我们可追踪决策：

• 宿主提供这些选项。
• 选择器返回此 ID。
• 宿主在这些规则下接受或拒绝。

框架无法保证什么

将决策层置于框架内不能保证每次结果正确。 它使边界更易界定，结果更易审查。

它不能证明 Jev 选择了最佳模型，也不意味着成功构建由选择器导致。

追踪每个模型运行位置

• 这些问题仍需证据，部分问题需超出单元测试的验证。
• 此外，“本地 Laya”描述的是选择器。你的编码工作者仍可能调用托管模型。
• 本地运行的 ACP 客户端也可实现。在描述整个工作流为本地或私有前，我会追踪每一跳。

03 / 我们的构建内容

构建版本为 Keel 0.2.0

此次构建是 Keel 0.2.0，一款本地优先的 Mac 编码应用。

• 基础：基于 Avid 派生的编码工作区。
• 语言：Rust。
• 界面框架：GPUI。
• 平台：Apple Silicon，需 macOS 15 或更高版本。

此细节重要，因故事中涉及两类工作：

一是应用程序：具备会话、提供方连接、工具和本地决策模式的真实编码工作区。

二是 Jev 工程研究与评估材料。

两者相关，但非相同交付物。

从可用编码工作区起步

我们从编码环境开始。 它已具备任务、仓库、提供方会话与工具。

这为工作提供了实践核心：当决策附着于任务、仓库、提供方会话与工具执行时的行为表现。

设计过程：保持选择可读性

有价值的设计问题很简单：Jev 可在何处做出应用仍能验证的选择？

该问题为我们决定其归属提供了方法。

也让我们停止在宿主无法执行结果处添加它。

1. 识别决策边界

选择器可在不接管整个智能体的情况下做出哪些选择？新任务路由和受限的下一步聚焦都是可行选项。

提供方内部操作不可行，因宿主不控制这些循环。

2. 明确选项

宿主需知晓哪些提供方与模型已安装、启用且适用于当前任务。选择器接收候选方案；它不制造候选方案。