企业官网建设流程全解析

World2Agent（W2A）是一个标准化 AI Agent 如何感知真实世界的开放协议，而官方的build-w2a-sensor技能可以让 AI 编程智能体替你完成传感器开发的全流程：从数据源调研、信号设计、项目脚手架，到最终npm publish上架，核心代码仅需约 50 行。本文将带你完整走一遍这个技能的工作流，看看它是如何把"写一个传感器"变成一句自然语言指令的。

什么是 World2Agent？为什么需要传感器？

W2A 的核心思想一句话：World → Sensor → Agent。

传感器（Sensor）是一个监听数据源的小程序，按统一的 W2A 协议格式发出结构化信号（Signal），你的 AI Agent 收到信号后自行决定如何处理。每个传感器都是一个标准的 npm 包，装一个就多一种感知能力，且可以自由替换——它们说的是同一种"语言"。

这套架构的价值在于：感知能力变成了可插拔的组件。不用为每个数据源写一次性集成代码，也不用自研互不兼容的信号格式。想深入了解背景，可以读 docs/why-w2a.md 和 docs/architecture.md。

一条命令安装 build-w2a-sensor 技能

技能本身就是给 AI 编程智能体看的"操作手册"，安装只要一条命令：

npx skills add https://gitcode.com/gh_mirrors/wo/world2agent/skills/build-w2a-sensor

安装后，在任何支持技能机制的 AI 编程环境中，直接对它说：

Build a W2A sensor for Hacker News trending.

技能会接管后续所有环节。它的完整逻辑就写在 skills/build-w2a-sensor/SKILL.md，值得通读一遍。

深度解析：技能的 6 个阶段工作流

这个技能最精彩的地方在于它先设计、后写码——跳过多问几个问题的传感器，要么配置项泛滥，要么信号质量低劣，这两种病都很难后期修。

阶段 1：拷问数据源（Discovery）

技能的第一项工作是"发现"而非写代码。它会让 AI 一次性问你 4 个问题：

1. 连什么平台？——决定source_type、包命名和事件命名空间
2. 事件怎么到达？——优先用官方推送（webhook / SSE / WebSocket），其次 API 轮询，最后才是爬取
3. 发哪些事件类型？——按domain.entity.action三段式命名，如messaging.message.mentioned
4. 需要什么配置？——凭据 + 最少的行为字段，"5 个字段已经算多"

💡 注意一个细节：domain是抽象空间（messaging、repo、market），不是平台名。Slack 传感器发的是messaging.message.mentioned而不是slack.message.mentioned——这样消费者写一次handler.on("messaging.message.mentioned")就能同时匹配 Slack、Discord、飞书的消息。

阶段 2：设计信号（Signal Design）

对每种事件类型，先定好信号长什么样再动手。两个核心要求：

• event.summary是信号的灵魂——Agent 只看这一行就得能决定"要不要行动、怎么行动"。遵循模式：[主语] [动作] [对象] in [背景]; [影响]。"new message"、"PR update" 这种模糊摘要会被直接打回重写。
• 三条通道各司其职：event存归一化分类，source_event存带 JSON Schema 描述的自解释结构化数据，attachments存非结构化内容块。

完整的字段规范见 docs/signal-format.md，权威 schema 在 schema/0.1/schema.ts。一个真实例子可以看看 hackernews-trending.json。

阶段 3：搭建项目脚手架（Scaffolding）

确认前两阶段的答案后，技能才开始生成代码，标准目录结构如下：

<package-dir>/ ├── package.json ├── SETUP.md — 安装/Q&A 配方 ├── README.md └── src/ ├── index.ts — defineSensor 定义 ├── start.ts — 主循环（webhook / ws / 轮询） ├── transform.ts — 源事件 → W2ASignal ├── types.ts — zod 配置 schema └── bin.ts — CLI 入口

生成的最小传感器大概长这样（约 50 行）：

import { defineSensor } from "@world2agent/sdk/sensor"; import { createSignal } from "@world2agent/sdk"; export default defineSensor({ id: "my-sensor", version: "0.1.0", source_type: "my-source", configSchema: myConfigSchema, async start(ctx) { const data = await fetchMySource(ctx.config.token); const signal = createSignal(this, { event: { type: "tasks.item.created", summary: `${data.author} created "${data.title}"; assigned to you`, }, source_event: { schema: {...}, data: {...} }, }); await ctx.emit(signal); }, });

更多细节（webhook 验签、WebSocket 自动重连、轮询游标持久化）都在 SKILL.md 的 Phase 3 中给了骨架代码。

阶段 4：编写 SETUP.md——安装体验本身

这是新手最容易忽略的一步。SETUP.md是消费方 Agent 安装你的传感器时读取的"安装配方"，它定义了安装时的 Q&A 问答、写入~/.world2agent/config.json的字段、以及处理信号的 handler skill 模板。

技能对 Q&A 有严格的"问题经济学"：总共不超过 5 个问题、凭据合并成一问、每个问题必须驱动一个具体产出。如果用户只想说"全用默认值"，说明你的问题问多了。

阶段 5：测试与迭代

构建 → 用createTestHarness()驱动transform函数跑夹具数据 → 在目标宿主里 dry-run 安装流程 → 连真实数据源确认summary对人类可读。摘要不可读？回到阶段 2 重做。

阶段 6：询问并发布到 npm

⚠️ 技能不会擅自发布。它会先问你："传感器本地已经能跑了，要发布到 npm 让别人直接安装吗？" 你同意后，它走一套完整的发布清单：

1. 预检package.json（命名、keywords 里 5 个必备 W2A 标签 +source_type）
2. npm pack --dry-run预览产物
3. npm publish --dry-run二次确认
4. 正式发布，postpublish钩子自动通知 SensorHub，约 30 秒内即可在传感器目录中检索到

npm publish

至此，你的传感器全世界可装。整个 docs/build-a-sensor.md 文档和 docs/sensorhub.md 补充了手动路径的细节。

新手避坑：3 条黄金原则

1. 推送优先于轮询——有官方 push 通道就别默认轮询，延迟更低、调用更省
2. 配置保持精简——v0.1 版本字段不超过 5 个，调优旋钮等真实用户开口再补
3. 协议是唯一权威——字段形状与 schema/0.1/ 冲突时，以 schema 为准

📚延伸阅读

• 信号格式规范：docs/signal-format.md
• 构建传感器完整指南：docs/build-a-sensor.md
• 快速上手（三种接入方式）：docs/quick-start.md
• 技能源码：skills/build-w2a-sensor/SKILL.md
• 多传感器组合：docs/multi-sensor.md

小结

build-w2a-sensor技能把传感器开发中最难的部分——信号设计——提前到写代码之前，由 AI 编程智能体带着你一步步走完 6 个阶段。对新手来说，你只需要想清楚"我想让 Agent 感知什么"，剩下的脚手架、安装配方、测试和发布流程，一句话搞定。这正是 W2A 作为开放协议的野心：协议和第一批传感器已经有了，真正的突破等你来写。