★ FEATURED ARTICLE 【免费下载链接】agnes-harnessAgnes Harness: A pluggable agent harness for Forward Deployed Engineering (FDE). Built for trust. Made for the real world.项目地址https://gitcode.com/gh_mirrors/ag/agnes-harness点击查看免费下载如果你正在研究Agnes Harness的架构想搞清楚它的 agent 执行框架是如何工作的这篇文章会带你完整拆解三个核心问题一次请求如何从 CLI 或 Web 客户端一路走到 Core 内核请求路径、会话与执行状态分别由谁保管状态归属、以及为什么它的扩展体系把必要接缝Seam和可选扩展Extension分成了两套完全不同的机制Seam 扩展机制。Agnes Harness 是一个面向 FDEForward Deployed Engineering前置部署工程场景的可插拔 agent harness官方定位是LLM 是大脑Jev 是小脑Harness 是记忆MHS 是身体。一、架构总览四个角色一套运行时Agnes Harness 的架构可以用一个身体隐喻来理解每个角色对应仓库里一个明确的模块边界角色在 Agnes Harness 中意味着什么对应实现位置LLM / 大脑理解请求、推理任务、提出候选动作AI provider 层模型接入与流式解析⚙️Jev / 小脑路由、评分等结构化决策接入中当前主循环为内置 Core loop规划中尚无 Jev 适配器️Harness / 记忆会话历史、任务状态、执行记录、可复用方法SkillsCore 事件记录 与恢复机制MHS / 身体设备协议让任务能读取物理状态、请求设备动作MHS 包独立于 MCP这里有个关键原则值得新手特别注意模型只负责提议不负责决定。模型文本不能决定工具的授权、执行或持久化状态——这些一律由后台策略和审批流程裁决。这是理解整套架构安全模型的前提。想直接看官方讲解建议从架构文档入口读起docs/develop/architecture.md中文版本在 architecture.zh-CN.md。二、请求路径一次 prompt 的完整旅程一条典型的请求链是这样的CLI / TUI ──┐ ├── SDK ── Daemon ── Session / Service Worker ── Host ── Core Kernel ── AI Provider 浏览器 Web ──┘ │ ├── 受控工具执行 └── 事件账本与存储拆开来看每一站干什么客户端CLI / Web只负责输入、审批交互和结果展示。Web 端有两条通道——会话流量走 WebSocket 直连 daemonagnes/sdk/browser而资源管理和插件服务走同源 HTTP BFF 再转发给 daemon浏览器插件因此拿不到 Node 侧的管理能力。SDK负责协议、传输、会话句柄和请求日志是客户端视角的状态。Daemon / Worker共享实例与会话目录的控制面负责审批路由worker 承载真正的执行环境入口见 supervisor.ts 与 main.ts。Host装配运行环境——Profile、凭据、平台适配、插件快照并创建 Kernel。核心装配逻辑在 assemble.ts。Core Kernel推进模型 → 工具 → 模型的执行循环生成下一步、记录状态、消费结果循环主体在 session.ts。正因为 CLI、Web、SDK 共用同一份后台会话状态你可以在浏览器里发起任务再到终端里用/resume id无缝接管历史、工具记录和结果表都在。三、状态归属谁保管会话、审批和执行状态Agnes Harness 架构中最容易让新手困惑的一点是状态不集中在一个地方而是按层严格划分。官方给出的归属表如下层主要职责CLI / Web用户输入、审批交互、会话与结果展示SDK协议、传输、会话句柄、游标与请求日志daemon / worker共享实例与会话目录、控制面与审批路由HostProfile、凭据、平台适配、插件装配与 Kernel 创建Core执行状态机、事件事实与必要能力接缝AI / Base / Code提供方协议、标准能力与可编程工作流落到实际行为上就是这句话取消、失败、停驻parking、恢复全部由后台状态决定而不是客户端的显示状态。客户端读取的只是事件流或派生投影——这就是为什么任何两个客户端看到的永远是同一份事实。事件事实本身保存在 Core 日志模块 中配合完整性校验构成可恢复执行的基础。四、Seam 扩展机制深潜10 个必要执行位这是 Agnes Harness 架构里最有特色、也最值得理解的设计。官方把扩展分成了两类Seam接缝执行过程中必不可少的环节例如审批approval、事件账本ledger、沙箱sandbox。Extension扩展可选的贡献物例如注册一个工具、挂一个观察 hook、提供一个客户端面板槽位。两者的本质区别是缺了 Seam会话必须直接拒绝打开fail-closed绝不静默跳过而 Extension 缺失只是少一项功能。4.1 内置的 10 个 Seam在 effects/seams.ts 中Seam 被定义为一张固定清单Seam作用approval工具调用的人工/策略审批checkpoint执行检查点ledger事件账本所有事件事实的落盘sandbox命令沙箱与执行约束verifier执行结果校验repair循环卫生与修复策略artifacts本地工件管理principals本地主体身份管理platform平台后端感知自身操作系统、可终止进程树harness自我修正refine提案Kernel 在创建时会逐一检查任何一项缺失都会抛出E_SEAM_MISSING错误——这就是 fail-closed 的落地方式实现见 kernel.ts。4.2 Seam 如何被装配进会话标准 Seam 实现集中在 base 包以插件形式注册例如审批策略在 approval-policy 扩展中Host 侧通过 seam-init 工厂带超时地加载它们。而 seam-init.ts 的注释里有一段特别值得读的设计说明Seam 只能拿到它被允许触达的最小接口——比如平台后端知道如何杀进程树但 Seam 只拿到PlatformSeam上那四个提问方法没有任何多余的权限。4.3 Seam 与 Extension 的权限边界这一点直接关系到安全模型普通后端插件是受信进程内代码——审批和沙箱约束的是受支持的执行路径不等于对任意插件代码做了隔离普通扩展注册一个工具或 hook并不会因此获得替换审批、沙箱等必要 Seam 的权限——Seam 由受信部署配置选定前端浏览器与后端 Context不共享内存浏览器插件只能通过已声明的 relay 调用行服务拿不到 Host 管理对象。插件的装配由 Cordis 负责见 packages/cordis/src包治理由 package-manager 承担安装插件时先展示版本、来源、完整性摘要与能力哈希启用时绑定并校验哈希。五、运行时目标与热更新理解 Seam 之后最后一块拼图是插件如何活在运行时里PackageManager产生已核验的快照和治理状态runtime target组合普通行、资源行与平台合成的客户端行web:行不在 Host 普通树中执行Host在受限事务中对可变行、依赖和实际状态做协调合格变更增量应用即热更新而静态边界变化、失败补偿或状态被污染时则要求整体重建。MCP 与 Skills 也走同一套装配路径session worker 从资源快照为每个合格的 MCP 服务器挂载ext:行Skills 则在资源变化后由 Host 的 Skills 行增量刷新。发布逻辑见 runtime-target-publisher.ts增量应用测试见 incremental-apply.test.ts。六、总结如何继续深入 Agnes Harness 架构三句话回顾请求路径客户端只管展示SDK 管协议daemon/worker 管控制面Host 装配环境Core 推进执行循环状态归属会话、审批、取消与恢复都以后台状态为准事件账本是唯一事实来源Seam 扩展机制10 个必要接缝 fail-closed普通扩展只能贡献可选能力权限面严格分离。延伸阅读全部在仓库内无外部依赖架构详解docs/develop/architecture.md源码地图按行为找源码入口docs/develop/source-map.md插件开发指南docs/develop/plugins.md安全与信任模型docs/guide/security.mdCore 执行循环源码packages/core/srcHost 装配源码packages/host/src抓住模型只提议、后台才决定和Seam 缺失即拒绝这两条主线Agnes Harness 的整套架构对你就不再是黑盒了。赞分享【免费下载链接】agnes-harnessAgnes Harness: A pluggable agent harness for Forward Deployed Engineering (FDE). Built for trust. Made for the real world.项目地址https://gitcode.com/gh_mirrors/ag/agnes-harness点击查看免费下载相关推荐PostgREST 架构深度解析从 HTTP 请求到 PostgreSQL 查询的完整链路PostgREST 架构深度解析从 HTTP 请求到 PostgreSQL 查询的完整链路 PostgREST 将 PostgreSQL 数据库自动转化为 R后端API网关数据库拆解 Cursor2API-go 源码架构从 Gin 路由到服务层一条请求的完整旅程拆解 Cursor2API go 源码架构从 Gin 路由到服务层一条请求的完整旅程 Cursor2API go 是一个用 Go 编写的开源 AI 模型 A后端API网关LLM 网关人工智能Kanidm 服务端架构深度解析从 REST 请求到搜索与写入事务的完整数据路径Kanidm 服务端架构深度解析从 REST 请求到搜索与写入事务的完整数据路径 本文以 Kanidm 仓库中的官方架构设计文档 architecture.m后端认证鉴权安全上一篇智能定位打卡助手企业微信考勤自由定制终极指南下一篇夸克自动转存工具5分钟快速配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
