> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 插件

> 为 Claude Code 安装 Ayrshare 插件，直接在编辑器中发布、排期和分析社交帖子 —— 支持发布前校验、发布前确认提示、品牌调性草拟以及数据回读。

Ayrshare Claude Code 插件已内置 [MCP Server](/additional/mcp-action-server) 配置、初始化命令、代理、技能以及安全钩子。安装后，你可以直接在 Claude Code 中发布帖子、获取历史与分析数据、管理配置文件等。任何内容上线前，代理都会先根据目标平台的规则对每条帖子进行校验，并请求你的确认，从而提前避免可预见的拒绝。历史帖子可用于匹配品牌调性，分析数据也可以回读以指导下一条帖子。

该插件是开源的。仓库地址：[ayrshare/ayrshare-social-media-api-claude-plugin](https://github.com/ayrshare/ayrshare-social-media-api-claude-plugin)。

## 安装

<Steps>
  <Step title="添加 marketplace（仅需一次）">
    ```bash theme={"system"}
    claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin
    ```
  </Step>

  <Step title="安装插件">
    ```bash theme={"system"}
    claude plugin install ayrshare@ayrshare
    ```
  </Step>
</Steps>

### 安装作用域

| 作用域               | 适用范围            |
| ----------------- | --------------- |
| Global（默认）        | 本机上所有项目。        |
| `--scope local`   | 当前项目，不会提交到 git。 |
| `--scope project` | 当前项目，会提交并与团队共享。 |

<Note>
  Claude Code CLI 中，全局作用域被称为 `--scope user`。
</Note>

## 凭据

可通过以下任一方式提供 Ayrshare API 密钥：

<ul class="custom-bullets">
  <li>运行 `/ayrshare:setup` 来配置或轮换密钥。</li>
  <li>设置 `AYRSHARE_API_KEY` 环境变量。</li>
</ul>

插件自带的 `.mcp.json` 已声明了 `Authorization` 请求头，以及可选的 `Profile-Key` 和 X BYOK 请求头，每一项都带有一个空的默认值（`${VAR:-}`），因此只需设置对应的环境变量即可启用相应请求头（Claude Code 会在启动时替换这些值）。要让每次调用都以某个子配置文件为目标，请设置 `AYRSHARE_PROFILE_KEY`（通过 `/ayrshare:setup` 或 `settings.json` 的 `env` 块设置），然后重启 Claude Code；自带的 `Profile-Key` 请求头会自动携带该值，未设置时则保持为空（等同于未提供）。若只想让某一次调用以子配置文件为目标，则在工具调用中传入 `profileKey` 参数（无需修改配置）。你无需编辑自带的 `.mcp.json`，也不应该编辑，因为 `claude plugin update` 会覆盖它。

<Warning>
  MCP 服务器在会话启动时初始化。安装插件或修改密钥后，请 **重启 Claude Code**。
</Warning>

### X/Twitter 自带（BYO）凭据

向 X/Twitter 发帖需要你自己的 X 开发者应用凭据（X BYO-key 强制规定，自 2026 年 3 月 31 日起生效；参见 [API 概览](/apis/overview#xtwitter-byo-credentials)）。自带的 `.mcp.json` 已经声明了两个 X BYOK 请求头，并附带空的默认值，同时也声明了 `Authorization` 和 `Profile-Key`：

```json theme={"system"}
"headers": {
  "Authorization": "Bearer ${AYRSHARE_API_KEY}",
  "Profile-Key": "${AYRSHARE_PROFILE_KEY:-}",
  "X-Twitter-OAuth1-Api-Key": "${X_TWITTER_OAUTH1_API_KEY:-}",
  "X-Twitter-OAuth1-Api-Secret": "${X_TWITTER_OAUTH1_API_SECRET:-}"
}
```

因此你只需通过 `/ayrshare:setup` 或 `settings.json` 的 `env` 设置对应的环境变量（`X_TWITTER_OAUTH1_API_KEY`、`X_TWITTER_OAUTH1_API_SECRET`），然后 **重启 Claude Code**；请勿修改自带的 `.mcp.json`（它会在 `claude plugin update` 时被覆盖）。**两者要么都设置，要么都不设置**：都未设置时，X/Twitter 调用会返回错误 `419`（`x_credentials_required`）；只设置了其中一个时，会返回错误 `400`。这是每个 Ayrshare 账户对应一对密钥，在每次以 X 为目标的请求中都会发送（同一对密钥适用于所有子配置文件）。

<Note>
  更希望使用直连方式而非插件？相同的 BYO 请求头可以通过 `claude mcp add --header` 传入 —— 请参见 [Connect & Setup → X/Twitter BYO 凭据](/additional/mcp-action-connect#xtwitter-byo-credentials)。
</Note>

## 插件包含哪些内容

### 命令

<ul class="custom-bullets">
  <li>`/ayrshare:setup` —— 配置或轮换 Ayrshare API 密钥。</li>
</ul>

### 代理（Agents）

<ul class="custom-bullets">
  <li>`social-manager`：在多个平台上发布、排期并分析内容。</li>
  <li>`profile-manager`：在 Business 账户下创建和列出配置文件，并为客户配置文件生成 JWT 社交账户关联 URL。</li>
  <li>`insights-analyst`：只读报表。拉取指标与帖子历史并汇总表现；不会发布、评论、发送私信或修改任何内容。</li>
</ul>

### 技能（Skills）

| 技能                           | 用途                |
| ---------------------------- | ----------------- |
| `getting-started`            | 首次使用时的引导与连接。      |
| `post`                       | 创建、校验、更新与重试帖子。    |
| `history`                    | 获取帖子与平台历史记录。      |
| `analytics`                  | 拉取单条帖子与账户级分析数据。   |
| `comments`                   | 读取、发表和回复评论。       |
| `messages`                   | 读取和发送私信，并配置自动回复。  |
| `profiles`                   | 创建和列出子配置文件。       |
| `media`                      | 校验媒体 URL 是否可访问。   |
| `generate`                   | AI 生成帖子文案并推荐话题标签。 |
| `webhooks`                   | 注册、注销并列出 Webhook。 |
| `errors`                     | 解读 Ayrshare 错误码。  |
| `draft-in-brand-voice`       | 以一致的品牌调性草拟帖子文案。   |
| `plan-and-schedule-campaign` | 规划并排期多条帖子构成的营销活动。 |

### 确认钩子

`PreToolUse` 钩子会在任何发布或发送操作前请求你的确认。它覆盖以下 7 个工具：

<ul class="custom-bullets">
  <li>`create_post`</li>
  <li>`update_post`</li>
  <li>`retry_post`</li>
  <li>`add_comment`</li>
  <li>`reply_comment`</li>
  <li>`send_message`</li>
  <li>`set_auto_response`</li>
</ul>

## 常见问题（FAQ）

<AccordionGroup>
  <Accordion title="插件会在发布前校验帖子吗？">
    会。插件会在发布前运行 `validate_post` 对你的内容进行干跑（dry-run）校验，检查是否符合每个平台的规则 —— 长度、格式和媒体要求 —— 从而提前避免可预见的拒绝。
  </Accordion>

  <Accordion title="发布到我的真实账户前会向我确认吗？">
    会。`PreToolUse` 确认钩子会在任何发布或发送操作前请求你的确认，涉及的工具包括：`create_post`、`update_post`、`retry_post`、`add_comment`、`reply_comment`、`send_message` 和 `set_auto_response`。
  </Accordion>

  <Accordion title="插件能匹配我的品牌调性吗？">
    可以。`draft-in-brand-voice` 技能会读取你的历史帖子，以一致的品牌调性草拟新文案。它只生成草稿 —— 未经你确认，不会发布任何内容。
  </Accordion>

  <Accordion title="我可以读取分析数据来指导下一条帖子吗？">
    可以。分析工具会返回单条帖子和账户级的指标，方便你回读结果并据此指导下一条帖子。
  </Accordion>

  <Accordion title="使用该插件需要准备什么？">
    一个 Ayrshare API 密钥（涉及配置文件与子配置文件时，需要 Business 套餐的密钥）以及 Claude Code。通过 `/ayrshare:setup` 或 `AYRSHARE_API_KEY` 环境变量配置密钥，然后重启 Claude Code。
  </Accordion>

  <Accordion title="向 X/Twitter 发帖需要额外设置吗？">
    需要。X/Twitter 需要你自己的 OAuth 1.0a 凭据，并作为两个连接请求头（`X-Twitter-OAuth1-Api-Key` 和 `X-Twitter-OAuth1-Api-Secret`）添加。参见上文的 [X/Twitter BYO 凭据](#xtwitter-byo-credentials)。
  </Accordion>
</AccordionGroup>

## 后续步骤

<CardGroup cols={2}>
  <Card title="Connect & Setup" icon="plug" href="/additional/mcp-action-connect" horizontal>
    身份认证、配置文件定位与 BYO 凭据。
  </Card>

  <Card title="工具目录" icon="list" href="/additional/mcp-action-tools" horizontal>
    按领域分组的 27 个工具，包含作用范围与用途。
  </Card>
</CardGroup>