全部是 WordPress REST，
没有第二套鉴权。

01五分钟上手

公开读端点不需要任何凭据。写端点需要登录态，凭据通过 X-WP-Nonce 头传递——nonce 由服务端在页面里下发（window.smcConfig.nonce），不要自己伪造，它是与当前登录用户绑定的。

# 公开端点，无需凭据
curl "https://example.com/wp-json/starmap-cluster/v1/posts?order=recent&page=1"

# 写端点：带 REST nonce
curl -X POST "https://example.com/wp-json/starmap-cluster/v1/posts" \
  -H "X-WP-Nonce: <nonce>" \
  -H "Content-Type: application/json" \
  -d '{"body":"今夜视宁度 1.4 角秒，M42 尘埃带清晰。","title":"冷湖夜记"}'

02鉴权与访客可读

读端点是否对访客开放，取决于站长在后台的「访客可读」开关。这是一个站点级策略，不是单条内容的可见性：

nonce 的有效期与 WordPress 登录 cookie 绑定。过期后写操作会返回 403 rest_cookie_invalid_nonce，正确做法是刷新页面重新取 smcConfig.nonce，而不是重试。

03路由总表

按资源分组。「登录」一列指是否要求登录态。

04一条星藏的字段

星藏的结构是星群的核心契约。媒体只存结构化引用、不存 HTML——这样渲染永远由插件自己的模板负责，客户端拿到的永远是数据。字段全部 camelCase，转换发生在 Posts::prepare_post() 一处。

{
  "id": 101,
  "title": "零下十八度，等到了 M42 的尘埃带",
  "body": "冷湖的风把视宁度压到 1.2 角秒…",
  "url": "https://example.com/cluster/p/101/",
  "createdAt": 1761926400,
  "starCount": 1284,
  "replyCount": 96,
  "views": 41209,
  "liked": false,
  "starred": false,
  "author": { "id": 2, "name": "沈墨白", "avatar": "…", "isFollowing": true },
  "group": { "key": "deep-sky", "name": "深空摄影研习社", "url": "…" },
  "star": { "url": "…", "title": "M42 猎户座大星云", "icon": "…" },
  "media": [
    { "kind": "image", "provider": "attachment", "url": "…", "thumb": "…" }
  ]
}

05限流档位

限流按「用户 + 动作」计数，用 transient 实现。触发时返回 429 与错误码 smc_throttled，响应里没有 Retry-After——按下面的窗口自己退避。

06错误码

错误响应是 WordPress 标准结构。message 是可以直接展示给用户的中文，code 才是给你做分支的。

07用过滤器扩展，而不是改插件

星群把可扩展点都做成了 apply_filters。改插件源码的代价是下次升级必然冲突，而下面这些钩子是有意暴露的稳定接口。

// 1) 注入设计令牌（颜色 / 间距），作用域限定 .smc-app
add_filter( 'starmap_cluster_theme_tokens', function ( $tokens, $view ) {
    $tokens['--smc-gold'] = '#7fb6ff';   // 换强调色
    return $tokens;
}, 10, 2 );

// 2) 扩展可嵌入的外部平台白名单
add_filter( 'starmap_cluster_media_providers', function ( $providers ) {
    $providers['vimeo']['enabled'] = true;
    return $providers;
} );

// 3) 追加通知类型（需与子主题的通知面板成对实现）
add_filter( 'starmap_cluster_notification_types', function ( $types ) {
    $types['smc_mention'] = '有人在星群里 @ 了你';
    return $types;
} );

// 4) 追加 body class / head 片段
add_filter( 'starmap_cluster_body_class', function ( $classes ) {
    $classes[] = 'my-custom-theme';
    return $classes;
} );

08明确没有的东西

避免你在文档里找半天：

• 没有 OAuth。第三方应用无法代用户操作，只能读公开数据或在用户自己的 cookie 会话里跑。
• 没有 webhook。想要实时推送请用子主题的 VAPID 链路，那是另一个模块。
• 没有批量端点。不要并发打出上百个请求，限流会按用户维度拦住你。
• 没有历史版本。帖子软删保留行做审计，但没有版本回滚 API。