第十六节 — 通信协议
这一节回答：FinBayes 各组件间用什么协议通信？外部接口的协议是什么？为什么这样选？
通信关系总览
按通信范围分四类：
| 类别 | 范围 | 主要协议 |
|---|---|---|
| 进程内 | runtime 内部子系统间 | Python 函数调用 + asyncio 协程 |
| 本机进程间 | runtime 与本机其他进程 | stdio / Unix domain socket / 本地 HTTP |
| 本机内 UI | runtime 与用户的浏览器 / 终端 | HTTP / WebSocket / 终端 stdin&stdout |
| 跨网络外部 | runtime 与外部 Provider | HTTPS（OpenAI-compatible / 各家 SDK） |
进程内通信
主要场景：CHAP-09 的 6 个子系统之间。
实现：直接 Python 函数调用（同步或异步协程）。
特点：
- 零序列化开销
- 类型安全（Python type hints + Pydantic 数据对象）
- 不依赖网络
- 同进程异常直接传播（不需 RPC 序列化）
关键约束：
- 子系统间的接口契约用 Python class / function signature 表达，并在 CHAP-09 各子系统的"关键接口"段落明示
- 即使是进程内通信，跨子系统的数据对象必须通过 Pydantic schema 校验（防内部数据不一致）
本机 UI 入口的通信
CLI 入口
协议：终端 stdin / stdout / stderr
特点：
- 单次提问一次性返回（除非用户主动开 streaming 模式
--stream） - 输出格式默认人类可读；
--json切换 JSON - 退出码语义化（0 = 成功 / 10 = 输入错误 / 20 = Provider 不可用 / 30 = 边界拒收 / 等）
TUI 入口
协议：终端原生（用 Textual / Rich 等 TUI 框架）
特点：
- 持续运行，键盘事件驱动
- 实时呈现流式输出（部分结果 + 最终归并）
- 支持多 Session 切换 / Watchlist 浏览 / Judgment 查看 / 状态确认动作
Web API Server
协议：HTTP（任务请求 / 状态动作）+ WebSocket（task event 流式更新）
| 端点 | 协议 | 用途 |
|---|---|---|
POST /api/task | HTTP | 创建认知任务（请求体含 task request schema） |
GET /api/task/{id} | HTTP | 查询任务状态 |
GET /api/task/{id}/stream | WebSocket | 实时接收 task event |
POST /api/state-action | HTTP | 用户确认 / 拒绝 / 编辑候选状态 |
GET /api/session/list | HTTP | 列出用户 Session |
POST /api/session/action | HTTP | Session 创建 / 切换 / 归档 / 删除 |
鉴权（本地优先单机部署）：
- 本机访问默认无鉴权（同主机进程间信任）
- Web UI 与 Web API 通过 localhost 通信，外部网络访问被拒绝
- 远程访问需用户显式启用并配置 token（不在第一阶段范围）
Contract Versioning：
- 每个 API 端点的 schema 含
contract_version字段 - 新增 optional 字段不升 major；删除字段 / 改语义升 major
- 不兼容版本拒绝服务并返回
INVALID_CONTRACT_VERSION错误码
MCP Server
协议：标准 MCP（Model Context Protocol，Anthropic 提出）—— 基于 stdio 的 JSON-RPC
特点：
- 外部 Agent（如 Claude Code / Codex / 其他 MCP-compatible Agent）可调用 FinBayes 的能力
- runtime 作为 MCP server 暴露工具（如
finbayes_analyze/finbayes_review_judgment/ 等） - stdio 协议天然适合本地 Agent 间通信（无需起 HTTP 服务）
MCP 工具池：FinBayes 暴露给外部 Agent 的工具是 Capability Registry 的子集（不暴露所有内部工具，仅暴露对外 API 级的）。
Channel Adapter
协议：因 channel 平台而异
| Channel | 协议 |
|---|---|
| Telegram | Telegram Bot API（HTTPS webhook 或 long polling） |
| Discord | Discord API（HTTPS + WebSocket gateway） |
| Slack | Slack API（HTTPS webhook） |
| 其他 | 按平台 SDK |
特点：
- Channel 入口主要为主动信号推送（"你对 ETH 的判断 X 失效条件被触及"）
- 也支持用户从 Channel 直接提问（视 Channel 平台特性）
- Channel 输出是低噪音摘要 + 回链到 Web Session 继续复盘
鉴权：每个 Channel 的 webhook secret / Bot token 走 Credential Store。
跨网络外部通信
LLM Provider 调用
协议：HTTPS
API 规范：
- 主流云端 Provider（OpenAI / Anthropic / DeepSeek / Qwen API）都支持 OpenAI-compatible 接口形态
- 本地 LLM 服务（Ollama / vLLM / LM Studio）也提供 OpenAI-compatible API
- Provider Adapter 内部用统一 OpenAI-compatible 客户端（如 LiteLLM 或自实现），屏蔽各家 SDK 差异
鉴权：API key 从 Credential Store 读取，通过 HTTPS Authorization 头传输（不进入代码 / 配置 / 日志）。
流式：所有 Provider 支持 SSE（Server-Sent Events）流式响应。Provider Adapter 统一为内部异步生成器。
外部数据 Provider 调用
协议：HTTPS（个别老旧 Provider 可能要求 HTTP，但默认拒绝）
鉴权方式：
| 类型 | 处理 |
|---|---|
| API key in header（如 yfinance / Alpha Vantage） | 走 Credential Store |
| OAuth（如某些券商数据 API） | 走 Credential Store + 刷新 token 管理 |
| 公开无鉴权（如 SEC EDGAR） | 直接调用，注意限流 |
限流处理：
- 每个 Provider 配置 rate limit
- runtime 用
asyncio.Semaphore控并发 - 超限时排队等待 + 必要时降级到 fallback Provider
Data Horizon 接口
协议：HTTPS（具体接口形态待 Data Horizon 项目定义）
FinBayes 视角的契约要求：
- 提供整理过的金融素材（事件 / 实体 / 时间线 / 数据）
- 支持订阅式实时推送（可选）+ 按需查询
- 不替 FinBayes 做判断（仅提供素材）
协议安全约束
所有协议层共同的安全约束：
| 约束 | 工程承接 |
|---|---|
| 凭证不进入协议消息体 | Provider API key 走 HTTP Authorization 头不写入 request body / 日志；Channel secret 同理 |
| TLS 不可降级 | 所有外部网络通信强制 HTTPS（HTTP 拒绝） |
| 本机 socket 限制 | Web API / MCP 默认仅监听 127.0.0.1，外部网络访问被拒绝 |
| 错误响应不泄露敏感 | 错误消息不含凭证 / 用户画像 / 内部 trace；详细 trace 仅写审计 trail |
错误码语义
跨协议统一的错误码语义（详细在附录数据对象 schema 索引）：
| 错误码 | 含义 |
|---|---|
INVALID_CONTRACT_VERSION | 请求或响应版本不兼容 |
INVALID_INPUT | 输入空 / 格式不合法 / 附件不可解析 |
PROVIDER_NOT_READY | LLM 或数据 Provider 未配置 / 不可用 |
EVIDENCE_UNAVAILABLE | 必需证据不可获得 |
UNSUPPORTED_SCOPE | 超出第一阶段范围 |
EXECUTION_TOOL_BLOCKED | 试图注册或调用执行类工具（边界硬约束） |
BOUNDARY_REJECT | 输入含凭证类内容被拒收 |
STATE_STORE_READONLY | State Store 进入只读模式 |
TASK_CANCELLED | 任务被取消 |
TASK_TIMEOUT | 任务超时 |
协议演化策略
| 演化情境 | 处理 |
|---|---|
| 新增 LLM Provider 类型 | Provider Adapter 内加新适配器；接口契约不变 |
| 接口契约小升级（新增 optional 字段） | minor 版本递增，向后兼容 |
| 接口契约破坏性变更 | major 版本递增 + 不兼容 client 拒绝 + 升级指南 |
| Channel 平台 API 变化 | Channel Adapter 内部适配，runtime 业务代码不变 |
详细的契约版本化策略在演化与版本管理章节。