Pulse 协议 v1 — 可验证的 Changelog 协议

设计目标

为什么 Changelog 需要一个协议？

RSS 和 JSON Feed 已经存在了几十年，但对 AI Agent 来说有两个致命问题：它们不可验证，所以 Agent 不能信任它们；它们没有机器可读的语义，Agent 必须自行猜测 breaking / fix / feature 的含义。

Pulse Protocol v1 解决这两个问题：每一份 feed 都用项目持有的 Ed25519 私钥签名，任何第三方都能用 .well-known/pulse.json 中的公钥独立验证；每条 change 都带语义化的 kind 与 breaking 字段，Agent 不再需要猜。

架构

三层结构

每一层都可以独立被消费，互不依赖。

L1 · 人类

公共发布页

/c/[slug] 渲染按月分组的发布页、订阅框、自定义主题色。给最终用户与 RSS 阅读器使用。

RSS: /c/[slug]/rss.xml
JSON Feed: /c/[slug]/feed.json
订阅表单 + double opt-in

L2 · AI 友好

Agent 端点

为 LLM 与 Agent 设计的入口 — 用最少的 token 让对方理解你的项目。

/agent.md — Agent 入门说明
/llms.txt / llms-full.txt
/for-agents — 人类友好的索引

L3 · 可验证

协议层

Pulse Protocol v1 — 给程序用的、签名化的、可独立验证的协议层。

.well-known/pulse.json
/pulse/feed.json — SignedFeed
/pulse/keys/{keyId}.pub
/mcp — MCP 服务

自描述

1. .well-known/pulse.json

每个项目根目录下都有这个发现文档。Agent 只要拿到一个 slug，就能从这里得到所有需要的元数据——公钥、端点 URL、上下文字典。

字段说明

pulse_version — 协议版本（v1）
identifier — 项目 slug
endpoint — 协议根路径
owner — 项目名称 + 主页 URL
public_key — Ed25519 公钥 + verify_url
context — JSON-LD 上下文
vocabulary — 协议字典 YAML
feed / stream — 主端点
llms_txt / agent_md — AI 入口
federates — 是否参与 Pulse 联邦

GET /.well-known/pulse.json

"pulse_version": "v1", "endpoint": "/api/public/projects/acme/pulse", "identifier": "acme", "owner": { "name": "Acme Cloud", "url": "https://acme.pulseprotocol.org" }, "public_key": { "algorithm": "ed25519", "key_id": "k_2026_08", "value": "MCowBQYDK2VwAyEA..." }, "feed": "/api/public/projects/acme/pulse/feed.json", "stream": "/api/public/projects/acme/pulse/stream", "federates": true

可验证性

2. 签名化的信封（SignedEnvelope）

每一个 SignedFeed 与 SignedChange 都是一份"信封"——内部是业务数据，外部追加一个 Ed25519 签名块。

SignedFeed · JSON

{ "@context": "https://pulseprotocol.org/schema/v1", "@type": "SignedFeed", "id": "pulse://acme", "generated_at": "2026-08-17T01:23:45Z", "changes": [ { "@type": "Change", "title": "Webhook retries", "kind": "improvement", "breaking": false } ], "signature": { "algorithm": "ed25519", "key_id": "k_2026_08", "value": "5b8d...c4" } }

设计要点

每项目独立 Ed25519 密钥对，私钥永不离开 Pulse 服务器
Canonical JSON：所有键按字典序排序后再序列化，保证"同一份业务数据 → 同一份字节 → 同一份签名"
可独立验证：拿到任意一段 envelope，Agent 都能用 well-known 中的公钥在本地校验，不依赖 Pulse 服务
可在线轮换：POST /api/projects/{id}/pulse/rotate 签发新密钥，旧密钥自动标记为 rotated_at
可扩展信封类型：当前 v1 支持 SignedFeed / SignedChange，后续可加入 SignedTrust / SignedFederation

公共端点

3. 协议端点（15+）

所有端点都是 CORS-enabled、JSON-RPC 友好的对外接口，按功能分组。

方法	路径	说明	状态
GET	`/.well-known/pulse.json`	自描述发现文档（公钥、端点、上下文字典）	v1
GET	`/pulse/context.jsonld`	JSON-LD 上下文，映射协议字段到 schema.org 词汇	v1
GET	`/pulse/vocabulary.yaml`	协议字典（kind / tag / source_type 等枚举）	v1
GET	`/pulse/feed.json`	完整 SignedFeed，含所有已发布条目	v1
GET	`/pulse/breaking.json`	只包含 breaking 变更的子集	v1
GET	`/pulse/since/{isoDate}`	指定 ISO-8601 时间之后的变更	v1
GET	`/pulse/c/{entryId}.json`	单条 SignedChange（按 entryId 取）	v1
GET	`/pulse/r/{yyyy-MM}.json`	按月归档（"release"）	v1
GET	`/pulse/keys/{keyId}.pub`	取回指定 key 的公钥	v1
GET	`/pulse/trust.json`	Trust Score：A/B/C/F 等级 + 5 个维度评分	v1
GET	`/pulse/search?q=...`	TF-IDF 关键词搜索（title 3x / summary 2x / md 1x）	v1
GET	`/pulse/stream`	SSE 实时流，事件：`entry.published`、`entry.updated`、`key.rotated`	v1
POST	`/mcp`	MCP / JSON-RPC 2.0 端点（`pulse_*` 工具）	v1
GET	`/api/public/leaderboard`	全局 Trust Score 排行榜（≥ 3 releases）	v1
POST	`/api/projects/{id}/pulse/rotate`	轮换签名密钥（owner only）	v1

MCP · JSON-RPC 2.0

4. 原生 Model Context Protocol 端点

每个项目都有一个独立的 MCP 端点：/api/public/projects/{slug}/mcp。Claude Desktop / Cursor / Windsurf 等客户端可以直接接入。

握手流程

1

initialize

声明协议版本（2024-11-05）和能力（tools）。

2

tools/list

返回 6 个 pulse_* 工具的清单与 JSON Schema。

3

tools/call

按需调用 read-only 工具获取数据。

4

ping

健康检查。

POST /mcp · tools/call

// 请求 { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "pulse_get_trust", "arguments": {} } } // 响应 { "jsonrpc": "2.0", "result": { "content": [{ "type": "text", "text": "{...}" }], "isError": false } }

6 个 `pulse_*` 工具

`pulse_get_well_known`

返回发现文档（含公钥）。Agent 第一次握手必用。

`pulse_get_feed`

取完整 SignedFeed。可选 limit、breaking。

`pulse_get_entry`

按 entry_id 取单条 SignedChange。

`pulse_search`

关键词搜索（TF-IDF），title 3x / summary 2x / md 1x 权重。

`pulse_get_trust`

返回项目的 Trust Score 与 5 个维度的分项评分。

`pulse_get_stream`

返回 SSE 信息（事件列表、建议直连 /pulse/stream）。

验证流程

5. 拿到一段 envelope → 自己验证它

不必相信 Pulse 服务器，Agent 拿到任意一段数据都可以在本地完成验证。

服务端校验接口

owner 在控制台点 "Verify" 按钮调用：

POST /api/projects/{id}/pulse/verify

"verified": true, "key_id": "k_2026_08", "algorithm": "ed25519"

客户端独立校验

用 @pulse-protocol/sdk 在 Node / 浏览器里验证：

node · verify()

import { verify } from "@pulse-protocol/sdk" const ok = await verify({ envelope: feedJson, publicKey: wellKnown.public_key.value })

工具链

6. SDK 与 CLI

协议不应该只活在服务端 —— 我们提供官方 TypeScript SDK 与 Node CLI，把签名化 feed 变成任何应用都能用的依赖。

@pulse-protocol/sdk

TypeScript SDK：canonicalise / verify / client。

npm install @pulse-protocol/sdk

import { PulseClient } from "@pulse-protocol/sdk" const client = new PulseClient({ base: "https://acme.pulse.dev", token: "pulse_agent_xyz..." }) const feed = await client.feed() const hits = await client.search("webhook")

pulse · CLI

命令行：实时 watch / 搜索 / 验证。

$ npx @pulse/cli

# 实时监听发布事件 $ pulse watch acme Watching acme on http://localhost:8080 [2026-08-17 01:23] entry.published: New: webhook retries [2026-08-17 01:25] entry.published: Fix: timezone in digest # 带 agent token $ pulse watch acme --token pulse_xyz... --base https://api.yourdomain.com # 搜索 $ pulse search acme --q "change"

认证

7. Agent Token（pulse_agent_xyz）

为 AI Agent 准备的独立速率桶与项目作用域，方便对外分发最少权限的密钥。

USER Token

注册用户使用，默认 per-user 速率限制。

scope: USER limit: 30 req / 5 min / IP

AGENT Token

通过 POST /api/account/api-tokens 签发，可选 project_id 限定范围。

scope: AGENT limit: 300 req / 5 min / token scope: optional project_id

匿名流量

未携带 token 的公共读取，限流防止滥用。

scope: anonymous limit: 30 req / 5 min / IP