SignalOS：AI 操作内核的神经通路

每一个生物体都通过神经通路感知环境 — 数百万信号向内流动，被分类、过滤、路由到正确的响应中枢。SignalOS 赋予 OctopusOS 同样的能力：一个统一的 IO/信号/流控制面，将原始的环境变化转化为经过治理的、可操作的智能。

1. 为什么 AI OS 需要神经通路

传统 AI 代理是被动的：等待显式提示，处理后返回结果。但一个真正的 AI 操作内核必须持续感知 — 感知磁盘上的文件变更、流经服务器的 HTTP 流量、内部模块冒出的日志异常，以及连接设备的硬件事件。

如果没有统一的信号平面，每个子模块各自实现临时的事件处理：文件监控可能遗漏变更，日志解析器无法与网络事件关联，硬件监控器孤立运行。结果就是一个对自身环境”失聪”的代理。

SignalOS 通过引入一条统一的、类型化的、受治理的信号总线来解决这个问题 — 每个 IO 域都向其中注入信号，每个治理模块都可以观察。

2. 四大 IO 域

OctopusOS 将所有输入输出归类为四个基本域。每个进入总线的信号都携带域标签，支持域级别的治理策略和路由规则。

3. SignalEnvelope：统一事件语言

SignalOS 的核心是 SignalEnvelope — 一个冻结的、不可变的数据类，作为统一事件格式。无论来自哪个源域，每个信号在进入总线之前都被标准化为这个形态。

@dataclass(frozen=True)
class SignalEnvelope:
    signal_id:        str              # 唯一标识
    origin:           SignalOrigin      # 来源信息
    kind:             SignalKind        # 事件类型
    ts_ms:            int              # 毫秒时间戳
    object_ref:       str              # 目标对象（路径、URL、设备）
    action:           str              # 发生了什么（created、modified、GET、ERROR）
    payload:          dict             # 结构化事件数据
    sensitivity:      SensitivityLevel # public | internal | confidential | restricted
    trust_level:      TrustLevel       # verified | authenticated | anonymous | untrusted
    priority:         SignalPriority   # critical | high | normal | low | bulk
    phase:            SignalPhase      # observe | understand | govern | act
    correlation_id:   str              # 因果链关联
    ttl_ms:           int              # 生存时间（防风暴）

设计原则：

• 冻结不可变 — 信号一旦创建就不可修改，确保审计链的完整性
• 域无关 — 同一个信封承载文件变更和 HTTP 请求
• 自描述 — 治理决策所需的每个字段都嵌入在信号本身中
• 因果链接 — correlation_id 和 parent_signal_id 支持完整的因果链重建

4. 四阶段控制循环

每个信号都必须经过严格的四阶段生命周期。没有信号可以在未经治理的情况下触发副作用。

阶段隔离保证

这是一个关键的架构不变量：只有处于 act 阶段的信号才能触发副作用。 内核通过追踪每个信封上的 phase 字段来强制执行。observe 和 understand 阶段的信号只能被读取和分析；govern 阶段的信号只能产生路由决策。这防止了事件驱动架构中最危险的一类缺陷：观察-执行混淆，即原始传感器数据直接触发动作而绕过治理审查。

5. 五层架构模型

SignalOS 跨越五个层次实现，每一层都有明确的职责和严格的依赖方向。

层级放置规则：

• L1（适配器） 位于 server/shared/ports_impl/signal_adapters/ — 唯一执行实际 I/O 的模块
• L2-L3（标准化 + 治理） 位于 kernel/domains/signal_os/ — 纯函数，零 I/O，完全可测
• L4（执行） 位于 kernel/runtime/_wl_signal_os.py — Worker Loop Mixin，每 tick 编排管道
• L5（智能） 位于 kernel/domains/signal_os/ — 纯分析模块，用于事后模式检测

6. 防事件风暴架构

事件驱动架构中最危险的故障模式是事件风暴：信号级联淹没处理能力。SignalOS 实现了四层防御。

背压状态机

当优先级通道达到队列深度上限时，总线进入饱和状态。该通道的新信号被丢弃并记录丢弃计数。/api/signals/backpressure/{lane_id} 端点实时暴露此状态。

@dataclass(frozen=True)
class BackpressureState:
    lane_id: str          # "hot" | "warm" | "cold"
    queue_depth: int      # 当前队列大小
    max_depth: int        # 配置的上限
    drop_count: int       # 因饱和丢弃的信号数
    is_saturated: bool    # queue_depth >= max_depth

7. 三条神经通路

在当前实现中，OctopusOS 有三条活跃的”神经纤维”持续向总线注入信号：

HTTP 神经（Network IO）

FastAPI 中间件捕获每个 HTTP 请求和响应。HttpInterceptAdapter 提取方法、路径、状态码、耗时和客户端主机 — 为每个 API 调用创建一个 network_io / http_request 信号。可配置的采样率防止自引用风暴（信号端点产生关于自身的信号）。

Log 神经（Stream IO）

自定义的 SignalLoggingHandler 在 WARNING 级别及以上挂载到 Python 根日志器。每个警告、错误或严重日志自动成为 stream_io / log_line 信号 — 让 OctopusOS 实时感知自身内部健康状况，无需任何显式代码埋点。

File 神经（Host IO）

FileWatcherAdapter 每个 tick 周期轮询工作区目录树。通过比较 (mtime, size) 元组与上次已知状态来检测文件创建和修改。每个变更成为一个 host_io / file_change 信号。

8. 治理管道详解

每个进入总线的信号在到达任何处理器之前，都要经过多阶段治理管道：

9. 回放与因果智能

SignalOS 不仅处理信号 — 它还记忆信号。回放层支持事后分析信号链、模式检测和根因追溯。

因果链

每个信号都可以携带 correlation_id 和 parent_signal_id，形成一个因果关联事件的有向无环图。build_chain() 函数将这些组装成 SignalChain 对象，包含根信号识别、时间跨度分析和有序信号序列。

模式检测

detect_patterns() 模块分析信号链集合以识别重复出现的序列 — 例如，检测到 file_change -> log_line(ERROR) -> http_request(500) 在时间窗口内反复发生。这些模式被存储为 SignalPattern 对象，包含出现次数和时间范围。

根因追溯

给定一个目标信号（如错误响应），trace_root_cause() 沿因果链向后遍历以找到起始信号。这支持自动化的根因分析：“这个 500 错误是由文件变更触发模块重载失败导致的。“

10. Flywheel 桥接

SignalOS 不是孤立存在的 — 它通过 flywheel_link 模块与 OctopusOS 现有的 Flywheel 智能循环双向连接。

这座桥梁意味着 SignalOS 检测到的模式会反馈进飞轮的学习循环，而飞轮的洞察可以被重新摄入为信号进行进一步治理 — 创造一个自我强化的智能循环。

11. API 接口

SignalOS 暴露四个 REST 端点用于外部集成和可观测性：

12. 实现指标

13. 设计哲学

SignalOS 体现三个核心架构信念：

1. 先观察，后行动。 阶段隔离保证确保没有信号可以在未经分类、风险评估和路由的情况下触发副作用。这是整个架构最重要的安全属性。

2. 每个信号都是一等公民。 文件变更和 HTTP 请求获得相同的类型化信封、相同的治理管道和相同的回放能力。不存在绕过治理的二等事件。

3. 纵深防御对抗风暴。 四层独立防护 — 适配器去抖、总线背压、治理节流和 TTL 过期 — 意味着没有单点故障可以引发事件级联。每一层独立运作，即使一层配置错误，其余层依然守住。

14. 应用场景

自愈基础设施

当 SignalOS 检测到 file_change -> log_line(ERROR) 的重复模式时，它可以自动将文件修改与错误关联，并建议（或执行）回滚 — 无需人工干预。

安全监控

携带敏感载荷的 SSH 事件被自动检测、脱敏（密码被替换），并路由到 hot 优先级通道。被封锁的来源在到达任何处理器之前就被拒绝。

性能可观测

每个 HTTP 请求生成一个带有耗时指标的信号。回放层可以检测延迟模式 — 例如，识别出对 /api/knowledge/query 的请求在 KB 目录发生 file_change 事件后持续飙升。

代理感知

代理生命周期事件（任务开始、步骤完成、失败）作为 stream_io / agent_stream_event 信号流经 SignalOS。这让治理层可以观察代理行为，支持跨代理群体的配额执行和异常检测。

硬件集成

GPIO 状态变化、串口数据流和摄像头帧作为 hardware_io 信号进入总线。治理管道确保摄像头帧（标记为 restricted 敏感度）在没有显式策略批准的情况下永远不会被持久化，而 GPIO 读数（标记为 internal）可以自由流向监控仪表板。