企业官网建设流程全解析

如果你正在研究Agnes Harness的架构，想搞清楚它的 agent 执行框架是如何工作的，这篇文章会带你完整拆解三个核心问题：一次请求如何从 CLI 或 Web 客户端一路走到 Core 内核（请求路径）、会话与执行状态分别由谁保管（状态归属）、以及为什么它的扩展体系把"必要接缝（Seam）"和"可选扩展（Extension）"分成了两套完全不同的机制（Seam 扩展机制）。Agnes Harness 是一个面向 FDE（Forward Deployed Engineering，前置部署工程）场景的可插拔 agent harness，官方定位是："LLM 是大脑，Jev 是小脑，Harness 是记忆，MHS 是身体"。

一、架构总览：四个角色，一套运行时

Agnes Harness 的架构可以用一个"身体隐喻"来理解，每个角色对应仓库里一个明确的模块边界：

这里有个关键原则值得新手特别注意：模型只负责"提议"，不负责"决定"。模型文本不能决定工具的授权、执行或持久化状态——这些一律由后台策略和审批流程裁决。这是理解整套架构安全模型的前提。

想直接看官方讲解，建议从架构文档入口读起：docs/develop/architecture.md（中文版本在 architecture.zh-CN.md）。

二、请求路径：一次 prompt 的完整旅程

一条典型的请求链是这样的：

CLI / TUI ──┐ ├──> SDK ──> Daemon ──> Session / Service Worker ──> Host ──> Core Kernel ──> AI Provider 浏览器 Web ──┘ │ ├──> 受控工具执行 └──> 事件账本与存储

拆开来看每一站干什么：

1. 客户端（CLI / Web）：只负责输入、审批交互和结果展示。Web 端有两条通道——会话流量走 WebSocket 直连 daemon（@agnes/sdk/browser），而资源管理和插件服务走同源 HTTP BFF 再转发给 daemon，浏览器插件因此拿不到 Node 侧的管理能力。
2. SDK：负责协议、传输、会话句柄和请求日志，是"客户端视角的状态"。
3. Daemon / Worker：共享实例与会话目录的控制面，负责审批路由；worker 承载真正的执行环境，入口见 supervisor.ts 与 main.ts。
4. Host：装配运行环境——Profile、凭据、平台适配、插件快照，并创建 Kernel。核心装配逻辑在 assemble.ts。
5. Core Kernel：推进"模型 → 工具 → 模型"的执行循环，生成下一步、记录状态、消费结果，循环主体在 session.ts。

正因为 CLI、Web、SDK 共用同一份后台会话状态，你可以在浏览器里发起任务，再到终端里用/resume <id>无缝接管，历史、工具记录和结果表都在。

三、状态归属：谁保管会话、审批和执行状态

Agnes Harness 架构中最容易让新手困惑的一点是：状态不集中在一个地方，而是按层严格划分。官方给出的归属表如下：

落到实际行为上就是这句话：取消、失败、停驻（parking）、恢复，全部由后台状态决定，而不是客户端的显示状态。客户端读取的只是事件流或派生投影——这就是为什么任何两个客户端看到的永远是同一份事实。事件事实本身保存在 Core 日志模块 中，配合完整性校验，构成可恢复执行的基础。

四、Seam 扩展机制深潜：10 个"必要执行位"

这是 Agnes Harness 架构里最有特色、也最值得理解的设计。官方把扩展分成了两类：

• Seam（接缝）：执行过程中必不可少的环节，例如审批（approval）、事件账本（ledger）、沙箱（sandbox）。
• Extension（扩展）：可选的贡献物，例如注册一个工具、挂一个观察 hook、提供一个客户端面板槽位。

两者的本质区别是：缺了 Seam，会话必须直接拒绝打开（fail-closed），绝不静默跳过；而 Extension 缺失只是少一项功能。

4.1 内置的 10 个 Seam

在 effects/seams.ts 中，Seam 被定义为一张固定清单：

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 之后，最后一块拼图是插件如何"活"在运行时里：

1. PackageManager产生已核验的快照和治理状态；
2. runtime target组合普通行、资源行与平台合成的客户端行（web:行不在 Host 普通树中执行）；
3. Host在受限事务中对可变行、依赖和实际状态做协调，合格变更增量应用（即热更新），而静态边界变化、失败补偿或状态被污染时则要求整体重建。

MCP 与 Skills 也走同一套装配路径：session worker 从资源快照为每个合格的 MCP 服务器挂载ext:行；Skills 则在资源变化后由 Host 的 Skills 行增量刷新。发布逻辑见 runtime-target-publisher.ts，增量应用测试见 incremental-apply.test.ts。

六、总结：如何继续深入 Agnes Harness 架构

🧭三句话回顾：

1. 请求路径：客户端只管展示，SDK 管协议，daemon/worker 管控制面，Host 装配环境，Core 推进执行循环；
2. 状态归属：会话、审批、取消与恢复都以后台状态为准，事件账本是唯一事实来源；
3. Seam 扩展机制：10 个必要接缝 fail-closed，普通扩展只能贡献可选能力，权限面严格分离。

📚延伸阅读（全部在仓库内，无外部依赖）：

• 架构详解：docs/develop/architecture.md
• 源码地图（按行为找源码入口）：docs/develop/source-map.md
• 插件开发指南：docs/develop/plugins.md
• 安全与信任模型：docs/guide/security.md
• Core 执行循环源码：packages/core/src
• Host 装配源码：packages/host/src

抓住"模型只提议、后台才决定"和"Seam 缺失即拒绝"这两条主线，Agnes Harness 的整套架构对你就不再是黑盒了。