Web API、RPC 与会话流
本页介绍仓库中与 Web API、RPC 网关以及会话流传输相关的代码入口，重点覆盖 packages/api/gateway 下的流协议、客户端、服务端和不同流类型模块。由于本页的源代码读取预算已用尽，以下内容严格限定为文件发现结果与仓库说明中能够确认的信息；具体方法签名、请求格式、错误分支和运行时行为尚未从实现代码中核实。
Purpose and Scope
本页的范围是远程网关与会话流这一叶子主题，包含：
packages/api/gateway/src/stream-protocol.ts：流协议入口；packages/api/gateway/src/stream-server.ts：流服务端入口；packages/api/gateway/src/client/stream-client.ts：流客户端入口；packages/api/gateway/src/client/remote-stream.ts、snapshot-stream.ts、journal-stream.ts：不同远程数据流入口；packages/api/gateway/src/client/remote-events.ts：远程事件入口；packages/api/gateway/src/types.ts与remote-error-codes.ts：网关类型和错误码入口；packages/api/gateway/src/index.ts：网关包导出入口。
账户控制器、浏览器凭据以及具体前端页面不在本页展开。仓库说明将 api/ 定义为 remote BFF，并将 core/ 定义为 agent/session API；因此，若需要了解会话领域模型或远程 BFF 的整体边界，应分别查看对应目录的兄弟文档。仓库的 AGENTS.md 还指出公共 API 处于 pre-stable 状态，并要求同步更新所有消费者；这意味着本主题的协议变更需要同时检查客户端、服务端和相关测试消费者。
Overview
文件布局表明网关采用“协议与类型 + 服务端 + 客户端流适配器”的组织方式。stream-protocol.ts 和 types.ts 代表共享契约；stream-server.ts 代表服务端传输边界；stream-client.ts 代表客户端通用流消费能力；remote-stream.ts、snapshot-stream.ts 和 journal-stream.ts 则按远程流语义拆分客户端侧适配器。remote-events.ts 单独承载远程事件相关入口，remote-error-codes.ts 集中承载错误码，index.ts 提供包级导出。
这种拆分的直接价值是把协议稳定性与具体流用途隔离：协议或错误码属于跨端契约，服务端负责提供传输端点，客户端通用层负责连接与消费，不同流类型只需依赖共享契约。具体的序列化方式、连接建立方式、背压策略、重试策略和会话关联字段，Implementation details not found in source（当前读取范围未包含实现内容）。
Architecture
下面的图只反映已发现的实际模块边界，不把未读取的函数调用关系当作已验证事实。箭头表示“按文件职责推定的契约分层”，不是已从实现中确认的调用链。
组件边界
| 组件 | 可确认职责 | 当前证据边界 |
|---|---|---|
stream-protocol.ts | 流协议模块 | 文件名确认；消息字段和帧格式未读取 |
stream-server.ts | 流服务端模块 | 文件名确认；监听器、路由和生命周期未读取 |
stream-client.ts | 通用流客户端模块 | 文件名确认；连接、消费和关闭 API 未读取 |
remote-stream.ts | 远程流模块 | 文件名确认；与通用客户端的实际依赖未读取 |
snapshot-stream.ts | 快照流模块 | 文件名确认；快照边界和一致性语义未读取 |
journal-stream.ts | 日志/变更记录流模块 | 文件名确认；游标和重放语义未读取 |
remote-events.ts | 远程事件模块 | 文件名确认；事件类型和订阅机制未读取 |
remote-error-codes.ts | 远程错误码模块 | 文件名确认；错误码映射未读取 |
Main Content
协议与实现的分层
从文件布局可以确认协议层与传输实现是分离的：共享协议位于 stream-protocol.ts，服务端实现位于 stream-server.ts，客户端通用实现位于 client/stream-client.ts。这通常允许服务端和客户端围绕同一契约演进，但本页不能进一步确认是否采用 JSON、二进制帧、SSE、WebSocket、HTTP streaming 或其他传输方式；不能根据“Web API”或“stream”名称推断具体协议。
多种会话流入口
客户端目录同时存在 remote-stream.ts、snapshot-stream.ts 与 journal-stream.ts，说明代码库至少区分远程流、快照流和日志流三个概念入口。工程维护者在扩展此区域时，应先确认新需求属于哪一种流语义，再判断是否应扩展通用 stream-client.ts、共享 stream-protocol.ts，还是增加新的专用适配器。具体选择规则、数据结构和状态机尚未从源代码核实。
事件和错误的独立建模
remote-events.ts 与 remote-error-codes.ts 被单独建文件，表明远程事件和远程错误码不是仅以内联常量存在。事件订阅顺序、错误码的可恢复性、错误到异常的转换，以及客户端是否会自动重连，均需要以实现和测试为准；当前没有足够源代码证据描述这些行为。
Core Flow
基于已发现的模块边界，可以给出一个保守的概念流。虚线表示待源代码验证的关系，避免把文件名误写成确定的运行时调用。
调试顺序
在排查 Web API 或 RPC 会话流问题时，建议按仓库的模块边界检查：
- 先确认
stream-protocol.ts与types.ts中的契约是否发生不兼容变化； - 再检查
stream-server.ts是否仍然产生客户端期望的流形态； - 检查
stream-client.ts的消费边界，以及专用流适配器是否正确选择； - 对事件问题检查
remote-events.ts； - 对失败分类检查
remote-error-codes.ts； - 最后检查
gateway/src/index.ts是否仍导出需要被消费者使用的符号。
上述顺序是按文件职责组织的排查建议；具体调用链、重试和关闭顺序未读取，不能据此推断运行时保证。
Usage Examples
当前源代码读取预算在发现阶段已经耗尽，未能读取实现文件，因此不能提供符合要求的真实代码摘录。为避免伪造 API 或协议示例，本页不包含虚构的 TypeScript 代码块。
No code example available.
Configuration Options
已发现的 packages/api/gateway 文件列表中没有读取到配置文件，无法确认该子系统的环境变量、默认值、超时、端口、重试次数或缓冲区设置。
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| — | — | — | Implementation details not found in source |
API Reference
由于未读取 stream-protocol.ts、stream-server.ts、stream-client.ts 和 types.ts 的实现，不能安全地写出方法签名、参数、返回类型或异常。请以实际导出的 TypeScript 类型和函数为准；不要根据文件名猜测 API。
Failure Modes, Edge Cases & Concurrency
目前能够确认的只有错误码存在独立模块 remote-error-codes.ts。错误码的具体集合、协议错误与网络错误的区别、重连行为、重复事件处理、快照与日志流的一致性、并发订阅安全性和取消语义，均未读取实现或测试，因而不能作出源代码级结论。
Performance and Operational Notes
文件名显示系统包含持续流和快照/日志类流，但当前证据不足以确认是否存在背压、批处理、游标、缓存、心跳、超时或资源上限。部署、监控和容量规划细节未在本次读取范围内找到。
Extension Points
从目录结构可观察到两个潜在扩展边界：
- 新增流语义：参考现有
remote-stream.ts、snapshot-stream.ts、journal-stream.ts的实际抽象后再决定是否增加专用模块； - 修改跨端契约：同步检查
stream-protocol.ts、types.ts、服务端、通用客户端及所有测试消费者。
仓库 AGENTS.md 明确指出公共 API 处于 pre-stable 状态，并要求更新每个消费者；因此任何协议或类型修改都不应只修改单一文件。具体兼容策略和版本迁移规则应继续参考仓库中的会话格式状态文档。
Tests
已发现 packages/api/gateway/tests/ 下包含 control-retry.client.spec.ts、echo-stream.host.spec.ts、gateway-stream.host.spec.ts 和 gateway.client.spec.ts 等测试文件名。这些文件名表明测试范围可能包含控制重试、回显流、网关流和客户端行为；由于测试内容未读取，不能把这些名称扩展为已验证的断言或保证。