Agent Zero WebSocket 端点 DOX 契约解析以 WsHello 测试处理器的完整调用链为例【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero本文以 api/ws_hello.py.dox.md 这份端点级 DOX文档档案文件为核心拆解 Agent Zero 中WsHello这个最小 WebSocket 处理器所承载的运行时契约并结合 helpers/ws.py 的基类实现、webui/js/websocket.js 的前端激活流程与 tests/test_ws_handlers.py 的测试约定说明该端点从连接握手、安全校验到事件分发的完整链路。读完后你可以掌握如何读懂 Agent Zero 每个 API 文件配套的.dox.md契约文档、WsHandler子类必须遵守的process(...)签名约定以及如何为自定义 WebSocket 端点做验证。ws_hello.py.dox.md端点级 DOX 档案的定位Agent Zero 的api/目录是刻意保持扁平的——每个 HTTP 或 WebSocket 端点单独一个.py文件并配一个同名的.py.dox.md档案文件。api/ws_hello.py.dox.md 就是其中一份它承担的职责在文档自身的 Purpose 一节中写得很明确拥有ws_hello.py这个 API 端点的文档档案该模块提供一个小型的 WebSocket hello/测试命名空间处理器由于目录刻意保持扁平必须让这份文件级 DOX 档案与ws_hello.py保持同步。Ownership归属一节定义了文档与代码之间的分工边界文件归属内容api/ws_hello.py运行时实现runtime implementationapi/ws_hello.py.dox.md关于职责、契约、副作用、验证方式的持久化笔记durable notes档案中登记的类结构只有一行但它精确对应了源码WsHello继承自WsHandler核心方法签名为async process(self, event: str, data: dict, sid: str) - dict | None。这与 api/ws_hello.py 第 5–13 行的实际实现逐字吻合class WsHello(WsHandler): Simple echo handler used for foundational testing. async def process(self, event: str, data: dict, sid: str) - dict | None: if event ! hello_request: return None name data.get(name) or stranger PrintStyle.info(fhello_request from {sid} ({name})) return {message: fHello, {name}!, handler: self.identifier}由此可以确认档案中声明的三个契约要素类继承约束WsHello必须是WsHandler的子类档案 Runtime Contracts 一节同时声明了对称规则——HTTP 处理器必须继承helpers.api.ApiHandlerWebSocket 处理器必须继承helpers.ws.WsHandler副作用面档案声明观察到的副作用区域为 WebSocket state对应源码中通过基类属性self.identifier回传处理器身份、并通过PrintStyle.info输出日志的行为依赖面档案列出的导入依赖helpers.print_style、helpers.ws与源码第 1–2 行的from helpers.ws import WsHandler、from helpers.print_style import PrintStyle一一对应。这份 DOX 的价值不在重复代码而在于它是一份可核查的契约清单每当请求载荷、认证/CSRF 要求、响应形状或路由副作用发生变化时档案要求同步更新该文件Runtime Contracts 一节的明确要求。WsHello 的事件契约hello_request 入、ack 回从源码结构看WsHello.process的契约由三段逻辑构成这也是所有WsHandler子类共用的模式事件过滤只响应event hello_request其他事件一律return None。返回None是WsHandler.process抽象方法的既定语义——基类 docstring 写明返回 dict 以纳入 ack 确认或返回None表示 fire-and-forget发后即忘语义见 helpers/ws.py缺省值处理name data.get(name) or stranger即客户端未提供name字段或提供空值时回落到stranger响应形状返回一个 JSON 可序列化字典{message: Hello, {name}!, handler: identifier}。其中self.identifier是基类属性返回值为模块路径.类名形式的字符串helpers/ws.py 中定义为f{self.__class__.__module__}.{self.__class__.__name__}对WsHello而言即api.ws_hello.WsHello。客户端凭此字段即可确认是哪一个处理器应答了本次事件这也是档案 Key Concepts 一节要求请求/响应与 helper 语义必须与源码变更同步记录的落点。需要注意适用前提WsHello是一个foundational testing用途的 echo 处理器它不创建任何会话状态也不调用emit_to/broadcast主动推送仅通过返回值完成一次请求-应答。生产流量的事件如state_request由 api/ws_webui.py 等其他处理器承担。WsHandler 基类WsHello 依赖的契约与工具DOX 档案声明WsHello是WsHandler而基类的实现细节决定了这个声明的全部含义。WsHandler定义在 helpers/ws.py其 docstring 说明它镜像 ApiHandler 的约定声明式安全标志、基于文件的动态加载以及process(event, data, sid)入口点并补充了一条对WsHello激活方式至关重要的规则处理器按连接激活依据是客户端在 Socket.IO 连接握手中发送的auth.handlers列表。基类为子类提供的主要契约点如下安全标志声明式类方法级requires_loopback()默认False、requires_api_key()默认False、requires_auth()默认True、requires_csrf()默认跟随requires_auth()helpers/ws.py。WsHello未覆盖任何标志因此它继承了必须认证 必须 CSRF的默认策略——这正是档案 Work Guidance 一节除非端点契约明确变更否则保留认证、CSRF、loopback 与 API-key 检查的源码依据生命周期钩子on_connect(sid)/on_disconnect(sid)默认空实现子类可选覆盖推送辅助方法emit_to(sid, event, data, *, correlation_idNone)与broadcast(event, data, *, exclude_sidsNone, correlation_idNone)二者都委托给WsManager做信封包装helpers/ws.py。WsHello未使用它们说明它只走返回值 ack通道命名空间所有api/下的 WS 处理器默认挂在NAMESPACE /wshelpers/ws.py。连接激活与事件分发WsHello 在服务器侧的完整链路register_ws_namespace()helpers/ws.py注册了/ws命名空间上的三个 Socket.IO 回调WsHello的每一次交互都经过这条链路。1connect 阶段——处理器解析与安全预检。_on_connect先调用validate_ws_origin(environ)做跨源握手校验对应 docs/developer/websockets.md 中保留认证与 CSRF 检查的规则该函数注释说明这是 RFC 6455 与 OWASP CSWSH 缓解建议的最小基线通过后把会话凭据打包进_SecurityContext认证哈希、CSRF token、cookie、远端地址、API key存入_ws_contexts[sid]。随后从auth[handlers]读取处理器路径列表对每个路径_resolve_handler按三级顺序解析内置api/path.py→ 用户目录files.USER_DIR/api/path.py→ 插件plugins/plugin_name/api/handler.py路径形如plugins/plugin_name/handler解析结果缓存在CACHE_AREA ws_handlers(api)(plugins)helpers/ws.py对解析出的类执行_check_security(handler_cls, ctx)失败则跳过该处理器实例化并调用on_connect(sid)成功者登记进_active_handlers[sid]。所以前端只有把ws_hello写进auth.handlersWsHello才会为这条连接激活。2event 阶段——统一分发管道。_dispatch捕获/ws上的所有事件helpers/ws.py先从载荷取correlationId缺失时生成 UUID再对已激活处理器逐个做安全预检通过的处理器交给WsManager.process_client_event有 manager 时否则内联调用instance.process(event, payload, sid)。返回值被统一包装为{ correlationId: 请求携带或新生成的 id, results: [ { handlerId: api.ws_hello.WsHello, ok: true, correlationId: id, data: { message: Hello, stranger!, handler: api.ws_hello.WsHello } } ] }处理器抛异常时该条results项变为{ok: false, error: {code: HANDLER_ERROR, ...}}且错误文案在响应中被归一为 Internal server error、完整信息只落服务端日志——WsHello返回的handler字段在此结构中正好与handlerId形成冗余校验便于前端确认应答来源。3安全失败码。_check_securityhelpers/ws.py在四类检查上依次返回固定错误码WsHello受其中两类约束因为默认只有 auth csrf 生效检查项失败码说明loopbackFORBIDDENrequires_loopback()为 True 时远端地址必须为本机认证AUTH_REQUIRED会话认证哈希与login.get_credentials_hash()不一致CSRFCSRF_MISSING/CSRF_INVALID/CSRF_COOKIEtoken 未初始化、客户端 token 不符、cookie 不匹配API keyAPI_KEY_REQUIREDkey 与设置项mcp_server_token不一致前端侧如何让 WsHello 生效webui/js/websocket.js 是默认 WebUI 的客户端实现它与WsHello的契约对接点有两处声明处理器addHandlers(handlers)在连接前声明要激活的处理器路径注释示例即ws_webui存入内部 Set若连接期间新增了处理器会主动disconnect()connect()重连以便更新后的 handler 列表通过 auth 回调发给服务器webui/js/websocket.js握手携带凭据Socket.IO 的auth回调在连接时拉取 CSRF token回调载荷为{ csrf_token, handlers }webui/js/websocket.js。服务端_on_connect读取的auth.csrf_token与auth.handlers正是来自这里。因此用浏览器控制台级别的脚本触发WsHello的最小流程是确保连接时handlers含ws_hello且 CSRF token 有效然后向/ws命名空间 emit 事件hello_request、载荷{name: ...}ack 中即可收到上文所述的{correlationId, results}结构。这同时满足了 docs/developer/websockets.md 提出的两条开发规则保留认证与 CSRF 检查、保持载荷 JSON 可序列化。验证与维护约定DOX 档案的 Verification 与 Work Guidanceapi/ws_hello.py.dox.md 的 Verification 一节给出了一条诚实而重要的事实按名称搜索未找到直接引用WsHello的测试档案因此建议选择最近邻的行为测试或做一次聚焦的冒烟检查。这与仓库现状一致tests/test_ws_handlers.py 覆盖了 WS 层的行为契约但没有针对hello_request的用例。可复用的参照测试包括test_ws_result_ok_clones_payload验证WsResult.ok对载荷做深拷贝防止响应数据被后续修改污染tests/test_ws_handlers.pytest_ws_result_error_contains_metadata验证错误载荷含code/error/details及correlationId、durationMs元数据tests/test_ws_handlers.py以及test_state_sync_handler_registers_and_routes_state_request它演示了用 fake SocketIO 构造WsManager 处理器实例 →handle_connect注册连接 → 直接await handler.process(event, data, sid)→ 断言返回值 → 清理断开的端到端写法tests/test_ws_handlers.py。为WsHello补测试时套用该模式构造WsHello(socketio, lock, managermanager, namespace/ws)并传入(hello_request, {name: x}, sid-1)即可断言返回{message: Hello, x!, handler: ...}Work Guidance 一节补充了两条跨端点纪律载荷形状变更时前端调用方、插件调用方与测试必须同步更新helpers.api.Response用于非 JSON 响应、文件、重定向或状态特化的回复这条主要面向 HTTP 侧的ApiHandler对 WS 侧的提醒是返回值保持 dictdocs/developer/websockets.md 则把 WS 工作的通用清单收敛为五条保留认证/CSRF 检查、载荷保持 JSON 可序列化、优先使用小而具名的事件而非大而全的 catch-all 事件WsHello只认hello_request正是这一条的示范、测试重连/超时/重复投递、面向用户的行为写进相应指南而非协议交接页。关键文件速查角色路径端点实现hello/echo 测试处理器api/ws_hello.py端点 DOX 契约档案本文核心api/ws_hello.py.dox.mdWsHandler 基类、安全校验、命名空间注册helpers/ws.py事件处理管线与 WsResult 封装helpers/ws_manager.py前端连接与处理器激活webui/js/websocket.jsWS 行为测试参照tests/test_ws_handlers.pyWS 开发规则交接页docs/developer/websockets.mdWsHello本身只有十几行代码但它把 Agent Zero WebSocket 端点的整套契约压缩到了最小可观察样本WsHandler继承约束、process签名与None语义、auth.handlers激活机制、声明式安全标志、correlationId信封包装以及源码变更必须同步 DOX 档案的文档纪律。以它为锚点读 helpers/ws.py 的分发管道是理解其余所有api/ws_*.py处理器最经济的路径。【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考