federation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ActivityPub Federation Protocol

ActivityPub 联邦协议

This skill provides understanding of the ActivityPub protocol specification and how federation works.

For supported features and compatibility: See FEDERATION.md for the complete list of implemented FEPs, supported standards, and federation compatibility details.

For implementation details: See AGENTS.md for transformers, handlers, and PHP code patterns.

本技能帮助理解ActivityPub协议规范以及联邦机制的工作原理。

支持的功能与兼容性： 查看FEDERATION.md获取已实现的FEP、支持的标准以及联邦兼容性的完整列表。

实现细节： 查看AGENTS.md了解转换器、处理器以及PHP代码模式。

Core Concepts

核心概念

Three Building Blocks

三大构建模块

Actors - Users/accounts in the system
- Each actor has a unique URI
- Required:
```
inbox
```
  ,
```
outbox
```
- Optional:
```
followers
```
  ,
```
following
```
  ,
```
liked
```
Activities - Actions taken by actors
- Create, Update, Delete, Follow, Like, Announce, Undo
- Wrap objects to describe how they're shared
Objects - Content being acted upon
- Notes, Articles, Images, Videos, etc.
- Can be embedded or referenced by URI

Actors（参与者） - 系统中的用户/账户
- 每个参与者拥有唯一的URI
- 必填项：
```
inbox
```
  （收件箱）、
```
outbox
```
  （发件箱）
- 可选项：
```
followers
```
  （关注者）、
```
following
```
  （关注的对象）、
```
liked
```
  （点赞内容）
Activities（活动） - 参与者执行的操作
- 包括创建（Create）、更新（Update）、删除（Delete）、关注（Follow）、点赞（Like）、转发（Announce）、撤销（Undo）
- 包裹对象以描述内容的分享方式
Objects（对象） - 被操作的内容
- 包括笔记（Notes）、文章（Articles）、图片（Images）、视频（Videos）等
- 可嵌入内容或通过URI引用

Actor Structure

参与者结构

json

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Person",
  "id": "https://example.com/@alice",
  "inbox": "https://example.com/@alice/inbox",
  "outbox": "https://example.com/@alice/outbox",
  "followers": "https://example.com/@alice/followers",
  "following": "https://example.com/@alice/following",
  "preferredUsername": "alice",
  "name": "Alice Example",
  "summary": "Bio text here"
}

json

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Person",
  "id": "https://example.com/@alice",
  "inbox": "https://example.com/@alice/inbox",
  "outbox": "https://example.com/@alice/outbox",
  "followers": "https://example.com/@alice/followers",
  "following": "https://example.com/@alice/following",
  "preferredUsername": "alice",
  "name": "Alice Example",
  "summary": "Bio text here"
}

Collections

集合

Standard Collections

标准集合

Inbox - Receives incoming activities

De-duplicate by activity ID
Filter based on permissions
Process activities for side effects

Outbox - Publishes actor's activities

Public record of what actor has posted
Filtered based on viewer permissions
Used for profile activity displays

Followers - Actors following this actor

Updated when Follow activities are Accepted
Used for delivery targeting

Following - Actors this actor follows

Tracks subscriptions
Used for timeline building

Inbox（收件箱） - 接收传入的活动

按活动ID去重
根据权限过滤
处理活动以产生相应的副作用

Outbox（发件箱） - 发布参与者的活动

记录参与者发布的所有内容
根据查看者权限过滤
用于展示个人主页的活动动态

Followers（关注者） - 关注当前参与者的其他参与者

当Follow活动被接受时更新
用于目标内容分发

Following（关注的对象） - 当前参与者关注的其他参与者

跟踪订阅关系
用于构建时间线

Public Addressing

公开寻址

Special collection:

https://www.w3.org/ns/activitystreams#Public

Makes content publicly accessible
Do not deliver to this URI - it's a marker, not a real inbox
Used in
```
to
```
,
```
cc
```
,
```
bto
```
,
```
bcc
```
fields for visibility

特殊集合：

https://www.w3.org/ns/activitystreams#Public

使内容可公开访问
请勿向此URI投递内容 - 它是一个标记，而非真实的收件箱
在
```
to
```
、
```
cc
```
、
```
bto
```
、
```
bcc
```
字段中用于控制可见性

Activity Types

活动类型

Create

Create（创建）

Wraps newly published content:

json

{
  "type": "Create",
  "actor": "https://example.com/@alice",
  "object": {
    "type": "Note",
    "content": "Hello, Fediverse!"
  }
}

包裹新发布的内容：

json

{
  "type": "Create",
  "actor": "https://example.com/@alice",
  "object": {
    "type": "Note",
    "content": "Hello, Fediverse!"
  }
}

Follow

Follow（关注）

Initiates subscription:

json

{
  "type": "Follow",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob"
}

Recipient should respond with Accept or Reject
Only add to followers upon Accept

发起订阅：

json

{
  "type": "Follow",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob"
}

接收方应回复Accept（接受）或Reject（拒绝）
仅在Accept后将其添加到关注者列表

Like

Like（点赞）

Indicates appreciation:

json

{
  "type": "Like",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob/post/123"
}

表示对内容的赞赏：

json

{
  "type": "Like",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob/post/123"
}

Announce

Announce（转发）

Reshares/boosts content:

json

{
  "type": "Announce",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob/post/123"
}

转发/推广内容：

json

{
  "type": "Announce",
  "actor": "https://example.com/@alice",
  "object": "https://other.example/@bob/post/123"
}

Update

Update（更新）

Modifies existing content:

Supplied properties replace existing
```
null
```
values remove fields
Must include original object ID

修改现有内容：

提供的属性将替换原有属性
```
null
```
值会移除对应字段
必须包含原始对象的ID

Delete

Delete（删除）

Removes content:

May replace with Tombstone for referential integrity
Should cascade to related activities

移除内容：

可替换为Tombstone（墓碑）以保持引用完整性
应级联处理相关活动

Undo

Undo（撤销）

Reverses previous activities:

json

{
  "type": "Undo",
  "actor": "https://example.com/@alice",
  "object": {
    "type": "Follow",
    "id": "https://example.com/@alice/follow/123"
  }
}

撤销之前的活动：

json

{
  "type": "Undo",
  "actor": "https://example.com/@alice",
  "object": {
    "type": "Follow",
    "id": "https://example.com/@alice/follow/123"
  }
}

Server-to-Server Federation

服务器到服务器的联邦

Activity Delivery Process

活动投递流程

Resolve Recipients
- Check
```
to
```
  ,
```
bto
```
  ,
```
cc
```
  ,
```
bcc
```
  ,
```
audience
```
  fields
- Dereference collections to find individual actors
- De-duplicate recipient list
- Exclude activity's own actor
Discover Inboxes
- Fetch actor profiles
- Extract
```
inbox
```
  property
- Use
```
sharedInbox
```
  if available for efficiency
Deliver via HTTP POST
- Content-Type:
```
application/ld+json; profile="https://www.w3.org/ns/activitystreams"
```
- Include HTTP Signatures for authentication
- Handle delivery failures gracefully

解析接收方
- 检查
```
to
```
  、
```
bto
```
  、
```
cc
```
  、
```
bcc
```
  、
```
audience
```
  字段
- 解引用集合以找到单个参与者
- 对接收方列表去重
- 排除活动的发起者自身
发现收件箱
- 获取参与者的个人资料
- 提取
```
inbox
```
  属性
- 如果可用，使用
```
sharedInbox
```
  以提高效率
通过HTTP POST投递
- Content-Type:
```
application/ld+json; profile="https://www.w3.org/ns/activitystreams"
```
- 包含HTTP签名用于身份验证
- 优雅处理投递失败

Inbox Forwarding

收件箱转发

Ghost Replies Problem: When Alice replies to Bob's post that Carol follows, Carol might not see the reply if she doesn't follow Alice.

Solution: Inbox forwarding

When receiving activity addressing a local collection
If activity references local objects
Forward to collection members
Ensures conversation participants see replies

幽灵回复问题： 当Alice回复Bob的帖子，而Carol关注Bob但不关注Alice时，如果没有收件箱转发，Carol可能看不到该回复。

解决方案：收件箱转发

当接收到指向本地集合的活动时
如果活动引用了本地对象
将活动转发给集合成员
确保对话参与者能看到回复

Shared Inbox Optimization

共享收件箱优化

For public posts with many recipients on same server:

Use
```
sharedInbox
```
endpoint instead of individual inboxes
Reduces number of HTTP requests
Server distributes internally

对于同一服务器上有大量接收方的公开帖子：

使用
```
sharedInbox
```
端点而非单个收件箱
减少HTTP请求的数量
由服务器在内部分发内容

Addressing and Visibility

寻址与可见性

To/CC Fields

To/CC字段

```
to
```
- Primary recipients (public in UI)
```
cc
```
- Secondary recipients (copied/mentioned)
```
bto
```
- Blind primary (hidden in delivery)
```
bcc
```
- Blind secondary (hidden in delivery)

Important: Remove

bto

and

bcc

before delivery to preserve privacy

```
to
```
- 主要接收方（在UI中公开显示）
```
cc
```
- 次要接收方（抄送/提及对象）
```
bto
```
- 隐秘主要接收方（投递时隐藏）
```
bcc
```
- 隐秘次要接收方（投递时隐藏）

重要提示： 为保护隐私，在投递前需移除

bto

和

bcc

字段

Visibility Patterns

可见性模式

Public Post:

json

{
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://example.com/@alice/followers"]
}

Followers-Only:

json

{
  "to": ["https://example.com/@alice/followers"]
}

Direct Message:

json

{
  "to": ["https://other.example/@bob"],
  "cc": []
}

公开帖子：

json

{
  "to": ["https://www.w3.org/ns/activitystreams#Public"],
  "cc": ["https://example.com/@alice/followers"]
}

仅关注者可见：

json

{
  "to": ["https://example.com/@alice/followers"]
}

直接消息：

json

{
  "to": ["https://other.example/@bob"],
  "cc": []
}

Content Verification

内容验证

Security Considerations

安全注意事项

Verify Origins
- Don't trust claimed sources without verification
- Check HTTP Signatures
- Validate actor owns referenced objects
Prevent Spoofing
- Mallory could claim Alice posted something
- Always verify before processing side effects
Rate Limiting
- Limit recursive dereferencing
- Protect against denial-of-service
- Implement spam filtering
Content Sanitization
- Clean HTML before browser rendering
- Validate media types
- Check for malicious payloads

验证来源
- 未经验证，不要信任声称的来源
- 检查HTTP签名
- 验证参与者拥有引用的对象
防止伪造
- Mallory可能冒充Alice发布内容
- 处理副作用前务必验证
速率限制
- 限制递归解引用
- 防止拒绝服务攻击
- 实现垃圾邮件过滤
内容清理
- 在浏览器渲染前清理HTML
- 验证媒体类型
- 检查恶意负载

Protocol Extensions

协议扩展

Supported Standards

支持的标准

See FEDERATION.md for the complete list of implemented standards and FEPs, including:

WebFinger - Actor discovery.
HTTP Signatures - Request authentication.
NodeInfo - Server metadata.
Various FEPs (Fediverse Enhancement Proposals).

查看FEDERATION.md获取已实现的标准和FEP的完整列表，包括：

WebFinger - 参与者发现
HTTP Signatures - 请求身份验证
NodeInfo - 服务器元数据
各种FEP（联邦宇宙增强提案，Fediverse Enhancement Proposals）

FEPs (Fediverse Enhancement Proposals)

FEP（联邦宇宙增强提案）

FEPs extend ActivityPub with additional features. Common FEP categories include:

Long-form text support.
Quote posts.
Activity intents.
Follower synchronization.
Actor metadata extensions.

For supported FEPs in this plugin: See FEDERATION.md for the authoritative list of implemented FEPs.

FEP为ActivityPub扩展了额外功能。常见的FEP类别包括：

长文本支持
引用帖子
活动意图
关注者同步
参与者元数据扩展

本插件支持的FEP： 查看FEDERATION.md获取已实现FEP的权威列表。

Implementation Notes

实现说明

WordPress Plugin Specifics

WordPress插件细节

This plugin implements:

Actor Types: User, Blog, Application
Transformers: Convert WordPress content to ActivityPub objects
Handlers: Process incoming activities

For implementation details, see:

AGENTS.md for code structure
Integration Guide for extending

本插件实现了：

参与者类型：用户、博客、应用
转换器：将WordPress内容转换为ActivityPub对象
处理器：处理传入的活动

实现细节请查看：

AGENTS.md了解代码结构
集成指南了解扩展方式

Testing Federation

测试联邦

bash

undefined

bash

undefined

Test actor endpoint

测试参与者端点

curl -H "Accept: application/activity+json"
https://site.com/@username

Test WebFinger

测试WebFinger

curl https://site.com/.well-known/webfinger?resource=acct:user@site.com

Test NodeInfo

测试NodeInfo

curl https://site.com/.well-known/nodeinfo

undefined

curl https://site.com/.well-known/nodeinfo

undefined

federation

Original

Translation

ActivityPub Federation Protocol

ActivityPub 联邦协议

Core Concepts

核心概念

Three Building Blocks

三大构建模块

Actor Structure

参与者结构

Collections

集合

Standard Collections

标准集合

Public Addressing

公开寻址

Activity Types

活动类型

Create

Create（创建）

Follow

Follow（关注）

Like

Like（点赞）

Announce

Announce（转发）

Update

Update（更新）

Delete

Delete（删除）

Undo

Undo（撤销）

Server-to-Server Federation

服务器到服务器的联邦

Activity Delivery Process

活动投递流程

Inbox Forwarding

收件箱转发

Shared Inbox Optimization

共享收件箱优化

Addressing and Visibility

寻址与可见性

To/CC Fields

To/CC字段

Visibility Patterns

可见性模式

Content Verification

内容验证

Security Considerations

安全注意事项

Protocol Extensions

协议扩展

Supported Standards

支持的标准

FEPs (Fediverse Enhancement Proposals)

FEP（联邦宇宙增强提案）

Implementation Notes

实现说明

WordPress Plugin Specifics

WordPress插件细节

Testing Federation

测试联邦

Test actor endpoint

测试参与者端点

Test WebFinger

测试WebFinger

Test NodeInfo

测试NodeInfo

Common Issues

常见问题

Activities Not Received

活动未接收

Replies Not Federated

回复未联邦

Follower Sync Issues

关注者同步问题

Resources

资源