World2Agent（W2A）是一个让 AI Agent「感知真实世界」的开源协议。它的核心是一套统一的信号格式：每个传感器（Sensor）都发出同一个结构的 JSON 信封，每个消费者（Agent）也接受同一个结构——线上不再有任何传感器私有的数据形状。本文带你完整拆解这套为 AI 设计的信号格式：信封里有什么字段、event为什么被称为信号的灵魂、结构化数据与非结构化内容该如何分流，以及这份规范在项目中的确切位置。

为什么要为AI设计统一信封

没有标准之前，每个 Agent 构建者都要为每个数据源写一次集成：解析不同的 API、发明不同的 JSON 结构，换一套 Agent 框架就全部失效。W2A 的思路很简单——协议只定义信号长什么样，传感器负责采集，Agent 负责决策。

一个统一的信号格式带来三个直接好处：

• 🔄即插即用的感知：装一个传感器，Agent 就获得结构化实时数据；换一个传感器，Agent 代码一行不改
• 🧩多传感器自由组合：所有传感器说同一种「语言」，同一段处理逻辑可匹配跨平台的同类事件
• 🤖为 AI 而非人类设计：协议是自然语言优先的，summary一句话说清发生了什么

信封全景：一条信号的全部字段

W2A 的规范 schema 位于 schema/0.1/schema.ts，生成的 schema/0.1/schema.json 在其旁边。一条完整的信号长这样：

💡 注意两个时间戳的设计：emitted_at是「传感器什么时候发的」，event.occurred_at是「真实事件什么时候发生的」。这种区分对审计和延迟分析很关键。

event：信号的灵魂

event.summary是 AI 最先读、也最该读得懂的一行。规范的原话是：如果只读 summary 不足以决定是否行动、如何行动，这条信号就失败了。

推荐写法遵循一个固定句式：

[Actor] [Action] [Object] in [Context]; [Impact]

✅ 好例子：

• "llm-agents/perception gained 523 stars in 24h and hit #3 on GitHub Trending; relevant to your active 'agent perception' research thread"
• "Zhang Wei asked about payment deployment safety in #engineering; staging error rate spiked 2h ago, blocking release pipeline"

❌ 差例子："new event"、"price moved"——含糊其辞，必须重写。

而event.type采用domain.entity.action三段式命名，且action 必须是过去式动词（opened、mentioned、threshold_crossed），因为信号描述的是已经发生的事：

这里有个精妙之处：domain是抽象源空间而非平台名。平台身份已放在source.source_type里——正因两者正交，一个 handler 可以一条规则匹配 Slack、Discord、Teams 的同类事件：handler.on("messaging.message.mentioned")通吃所有平台。

三条数据通道，各司其职

W2A 把信号内容拆成三个通道，边界非常清晰：

铁律两条：机器要用的结构化数据绝不塞进 attachment；大块内容绝不塞进source_event.data。

source_event的精髓是「自描述」——每个属性都应当带description。只声明类型（{ "type": "integer" }）会让消费者猜数值含义；加上描述（"Stars gained in the last 24 hours"）后，Agent 无需任何传感器专属知识就能理解数据。

attachments则是通过type字段区分的二选一结构：

• inline：内容直接内联（文本为 UTF-8，二进制为 base64）
• reference：只给 URI，消费者按需拉取——超过约几 KiB 或已有地址的内容优先用它

两种附件都必填description——AI 必须始终知道自己正在看什么。

设计哲学：无路由、目录化版本、_meta 扩展

规范末尾的三条设计原则值得记住：

1. 🚫协议里不做路由——过滤和优先级是消费者的事。同一个传感器可以零改动地同时喂给 Agent、Slack bot 和仪表盘
2. 📁目录即版本——schema 目录名（0.1）就是协议版本，破坏性变更升目录，增量变更原地演进，消费者固定引用目录而非main
3. 🧩_meta扩展点——几乎所有对象都带_meta字段，实现方可以挂载实验性或厂商字段而无需升级协议，消费者必须忽略未知键

去哪里看规范与示例

想深入，这些文件是最好的起点：

• 信号格式规范：docs/signal-format.md
• 规范 schema 源码（含逐字段 JSDoc）：schema/0.1/schema.ts
• 可运行的真实信号示例：schema/0.1/examples/hackernews-trending.json
• 示例校验脚本：scripts/validate-examples.mjs
• 架构设计详解：docs/architecture.md
• 快速上手指南：docs/quick-start.md

小结

W2A 的信号格式本质上是一个为 AI 优化的 JSON 信封：signal_id管去重、event管语义、source_event管事实、attachments管内容、_meta管扩展。每个字段都有明确职责，每条边界都有明确纪律。理解了这套信封，你就理解了 World2Agent「装一个传感器，Agent 获得一份感知」的全部魔法。