Pulse · 开发者文档

5 分钟上手

1. 安装

SDK

TypeScript / Node 18+

npm

$ npm install @pulse-protocol/sdk

CLI

全局安装或在 npx 里直接用

shell

$ npm install -g @pulse/cli $ pulse --help

公共协议

2. Pulse Protocol 端点（无需鉴权）

所有 /api/public/* 端点都是 CORS-enabled 的公共读取；用 Agent Token 可拿到更高配额。

方法	路径	说明	认证
GET	`/api/public/projects/{slug}/.well-known/pulse.json`	发现文档（含公钥）	public
GET	`/api/public/projects/{slug}/pulse/context.jsonld`	JSON-LD 上下文	public
GET	`/api/public/projects/{slug}/pulse/vocabulary.yaml`	协议字典	public
GET	`/api/public/projects/{slug}/pulse/feed.json`	完整 SignedFeed	public
GET	`/api/public/projects/{slug}/pulse/breaking.json`	只含 breaking 变更	public
GET	`/api/public/projects/{slug}/pulse/since/{isoDate}`	指定时间之后的变更	public
GET	`/api/public/projects/{slug}/pulse/c/{entryId}.json`	单条 SignedChange	public
GET	`/api/public/projects/{slug}/pulse/r/{yyyy-MM}.json`	按月归档	public
GET	`/api/public/projects/{slug}/pulse/keys/{keyId}.pub`	取回公钥	public
GET	`/api/public/projects/{slug}/pulse/trust.json`	Trust Score	public
GET	`/api/public/projects/{slug}/pulse/search?q=...`	关键词搜索	public
GET	`/api/public/projects/{slug}/pulse/stream`	SSE 实时流	public
POST	`/api/public/projects/{slug}/mcp`	MCP / JSON-RPC 2.0	agent
GET	`/api/public/leaderboard?limit=20`	Trust Score 排行榜	public

认证

3. 三种凭证

所有鉴权头都是 Authorization: Bearer <token>。

USER Token (JWT)

登录后下发，HS384 签名，30 天有效。owner 写操作必备。

limit: 30 req / 5 min / IP

已上线

AGENT Token

专门给 AI Agent 用，可选限定到单项目。

limit: 300 req / 5 min / token

已上线

匿名

不带 token 的公共读取。

limit: 30 req / 5 min / IP

已上线

MCP

4. Model Context Protocol

每个项目一个 MCP 端点；6 个工具，全部 read-only。

PulseClient（MCP wrapper）

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

`pulse_get_well_known`

返回发现文档（含公钥）。

`pulse_get_feed`

签名化 feed。args: { limit?, breaking? }

`pulse_get_entry`

单条 SignedChange。args: { entry_id }

`pulse_search`

关键词搜索。args: { q, limit? }

`pulse_get_trust`

Trust Score。args: {}

`pulse_get_stream`

SSE 元信息。args: { duration_ms? }

SDK

5. TypeScript SDK 用法

verify()

在客户端独立验证 envelope（不调用 Pulse 服务器）。

import { verify , canonicalise } from "@pulse-protocol/sdk" const wellKnown = await fetch( "/api/public/projects/acme/.well-known/pulse.json" ).then(r => r.json()) const feed = await fetch( "/api/public/projects/acme/pulse/feed.json" ).then(r => r.json()) const ok = await verify({ envelope: feed, publicKey: wellKnown.public_key.value }) console.log("verified:", ok)

canonicalise()

把 envelope 序列化为"稳定字节"（按 key 排序）—— 用来重新签名或自建签名工具。

import { canonicalise } from "@pulse-protocol/sdk" const bytes = canonicalise(envelope) // 用于本地签 Ed25519 import * as ed from "@noble/ed25519" const sig = await ed.sign(bytes, privKey)

CLI

6. pulse · 命令行

实时 watch / 搜索 / 验证 —— Node 18+，基于 fetch + SSE。

pulse --help

Usage: pulse <command> [options] Commands: pulse watch <slug> SSE stream 实时打印发布事件 pulse search <slug> --q ... 搜索 changelog pulse feed <slug> 打印 SignedFeed（JSON） pulse trust <slug> 打印 Trust Score pulse verify <slug> --file 验证 envelope 文件 pulse rotate <slug> 请求轮换签名密钥 Options: --token <token> Agent Token（pulse_agent_xyz） --base <url> 默认 https://api.pulse.dev

实时 watch

$ pulse watch acme Watching acme on http://localhost:8080 [2026-08-17 01:23:45Z] entry.published: New: webhook retries [2026-08-17 01:25:12Z] entry.published: Fix: timezone in digest

搜索 + 自定义 base

$ pulse search acme --q "change" --token pulse_xyz... --base https://api.yourdomain.com

错误码

7. 错误码参考

HTTP	含义
200	成功
400	参数错误（如 `since` 不是合法 ISO-8601）
401	Token 缺失 / 无效
403	无权限（如非 owner 调 rotate）
404	Slug / entryId 不存在
429	速率限制（详见 `Retry-After` 头）