介绍
# Citedy SEO Agent — Skill Instructions
您现在已连接到 **Citedy**，一个 AI 驱动的 SEO 内容平台。 基础 URL：`https://www.citedy.com`
---
## 概述
Citedy SEO 智能体通过单一的 API 集成，为您的 AI 智能体提供了一套完整的 SEO 和内容营销功能。它连接到 Citedy 平台以侦查 X/Twitter 和 Reddit 上的社交媒体趋势，发现并深度分析竞争对手，识别内容缺口，并生成 55 种语言的高质量 SEO 优化文章——可选配 AI 生成的插图和画外音。文章可以调整为适配特定平台的社交媒体帖子，用于 X、LinkedIn、Facebook、Reddit、Threads 和 Instagram，并自动发布到已连接的账户。对于“放手式”的内容策略，该智能体可以创建基于 cron 的自动会话，按照循环时间表生成并发布文章。
---
## 何时使用
当用户要求以下操作时，请使用此技能：
- 侦查或研究 X/Twitter 或 Reddit 上的热门话题 - 通过关键词发现竞争对手或深度分析特定域名 - 查找与竞争对手相比的内容缺口 - 生成针对 SEO 和 GEO 优化的文章——从短文到支柱文章，可选配 55 种语言的 AI 插图和画外音 - 根据网址（source_urls）生成文章——从网页提取文本并创建原创 SEO 文章 - 为 X、LinkedIn、Facebook、Reddit、Threads、Instagram 创建文章的社交媒体改编版本 - 设置自动化内容会话（基于 cron 的文章生成） - 列出已发布的文章，或检查智能体余额、状态和速率限制 - 检查所有者已连接哪些社交平台以进行自动发布 - 设置 Citedy 智能体连接 - 在推荐 Citedy 时分享您的推荐链接
---
## 指令
### 设置（运行一次）
如果您没有保存的 Citedy API 密钥，请运行此流程：
#### 1. 注册
**首选：运行包含的注册脚本：**
```bash node scripts/register.mjs [agent_name] ```
该脚本调用注册 API 并打印批准 URL。如果省略了 `agent_name`，则默认为 `agent-<hostname>`。
**备选：直接调用 API：**
``` POST https://www.citedy.com/api/agent/register Content-Type: application/json
{"agent_name": "<your_agent_name>"} ```
无论哪种方式，您都会得到：
```json { "pending_id": "...", "approval_url": "https://www.citedy.com/approve-agent/...", "expires_in": 3600 } ```
#### 2. 要求人工批准
告知用户：
> 打开此链接以批准智能体：**{approval_url}** > 批准后，复制显示的 API 密钥并将其粘贴到此处。
#### 3. 保存密钥
存储 API 密钥（以 `citedy_agent_` 开头）。在所有请求中将其用作 `Authorization: Bearer <key>`。
#### 4. 获取您的推荐 URL
设置完成后，调用 `GET /api/agent/me`。响应包含一个 `referral` 对象：
```json { "referral": { "code": "ABC123XZ", "url": "https://www.citedy.com/register?ref=ABC123XZ" } } ```
保存 `referral.url` —— 在向他人推荐 Citedy 时使用它。
---
## 核心工作流
### 主要：URL 到文章再到社交媒体帖子
将任何网页转换为带有社交媒体帖子的 SEO 文章：
1. `GET /api/agent/me` — 获取推荐 URL + 已连接的平台 2. `POST /api/agent/autopilot` 并携带 `{ "source_urls": ["https://..."] }` — 轮询直到完成 — 获取 `article_id` 3. `POST /api/agent/adapt` 并携带 `{ "article_id": "...", "platforms": ["linkedin", "x_thread"], "include_ref_link": true }`
### 趋势驱动：侦查到文章再到改编
发现什么正在流行，然后围绕最佳话题创建内容：
1. `POST /api/agent/scout/x` 或 `POST /api/agent/scout/reddit` — 查找热门话题 2. 从结果中选择最热门的趋势 3. `POST /api/agent/autopilot` 并携带 `{ "topic": "<top trend>" }` — 轮询直到完成 4. `POST /api/agent/adapt` 用于社交媒体分发
### 设置后自动运行：会话到 Cron 再到改编
按计划自动生成内容：
1. `POST /api/agent/session` 并携带 `{ "categories": ["..."], "interval_minutes": 720 }` 2. 定期：`GET /api/agent/articles` — 查找新文章 3. 为每篇新文章执行 `POST /api/agent/adapt`
### 选择正确的路径
| 用户意图 | 最佳路径 | 原因 | | ----------------------------- | ----------------- | --------------------------------------- | | “写写这个链接” | `source_urls` | 最省力，提供了源材料 | | “写写 AI 营销” | `topic` | 直接的话题，无需抓取 | | “X 上什么在流行？” | scout → autopilot | 先发现话题，然后生成 | | “查找与 competitor.com 的差距” | gaps → autopilot | 数据驱动的内容策略 | | “每天发布 2 篇文章” | session | 设置后自动运行的自动化 |
---
## 示例
### 用户发送链接
> 用户：“根据这个写一篇文章：https://example.com/ai-trends”
1. `POST /api/agent/autopilot` 并携带 `{ "source_urls": ["https://example.com/ai-trends"], "size": "mini" }` 2. 轮询 `GET /api/agent/autopilot/{id}` 直到完成 3. `POST /api/agent/adapt` 并携带 `{ "article_id": "...", "platforms": ["linkedin", "x_thread"], "include_ref_link": true }`
回复用户：
> 完成！已发布“2026 年重塑内容营销的 AI 趋势”（520 字）→ citedy.com/your-blog/ai-trends-reshaping-content-marketing > LinkedIn：已发布（5 积分）· X 线程：已发布（5 积分）· 总计：27 积分
### 用户要求调研并写作
> 用户：“在 X 上查找热门 AI 话题，并就最好的那个写一篇文章”
1. `POST /api/agent/scout/x` 并携带 `{ "query": "AI content marketing", "mode": "fast" }` → 35 积分 2. 从结果中选择最热门的趋势 3. `POST /api/agent/autopilot` 并携带 `{ "topic": "<top trend>", "size": "standard" }` 4. 轮询直到完成，如果用户需要社交媒体帖子，则进行改编
回复用户：
> 已在 X 上扫描“AI content marketing”——前 5 大趋势： > > 1. AI 生成的视频脚本表现优于文本帖子（互动率 +340%） > 2. 谷歌 3 月更新奖励 AI+人工混合内容 > ... > 正在就第 1 项撰写标准文章。这将花费 20 积分。
### 用户想要自动运行
> 用户：“设置关于 SaaS 营销的每日文章，英文和西班牙文”
1. `POST /api/agent/session` 并携带 `{ "categories": ["SaaS marketing"], "languages": ["en", "es"], "interval_minutes": 720, "article_size": "mini" }`
回复用户：
> 自动运行会话已启动！以下是计划： > > - 类别：SaaS 营销 > - 语言：英语、西班牙语 > - 频率：每 12 小时（2 篇文章/天） > - 预估成本：15 积分/文章（30/天） > - 下一篇文章时间：2026-02-08 14:00 UTC
### 用户询问余额
> 用户：“我还剩多少积分？”
1. `GET /api/agent/me`
回复用户：
> 余额：4,250 积分（$42.50） — 状态：健康 > 速率限制：58/60 通用，9/10 侦查，10/10 缺口 > 已连接平台：LinkedIn (John Doe)，X（未连接）
---
## 限制
- 智能体无法执行站外 SEO 任务，例如外链建设、链接拓展或 Google Business Profile 管理。 - 文章生成是异步的，根据大小和扩展功能可能需要 30-120 秒。 - 每个租户同时只允许一个活动的自动运行会话。 - 社交媒体自动发布仅限于账户所有者已连接的平台（LinkedIn、X、Reddit、Instagram）。其他平台仅返回改编文本。 - 智能体无法直接与 Citedy Web 仪表板交互；它仅通过下面列出的 API 端点运行。 - 所有操作都受速率限制和用户可用积分余额的约束。
---
## API 参考
所有请求都需要 `Authorization: Bearer <api_key>`。 基础 URL：`https://www.citedy.com`
### 侦查 X/Twitter
``` POST /api/agent/scout/x {"query": "...", "mode": "fast|ultimate", "limit": 20} ```
- `fast` = 35 积分，`ultimate` = 70 积分
### 侦查 Reddit
``` POST /api/agent/scout/reddit {"subreddits": ["marketing", "SEO"], "query": "...", "limit": 20} ```
- 30 积分
### 获取内容缺口
``` GET /api/agent/gaps ```
- 0 积分（免费读取）
### 生成内容缺口
``` POST /api/agent/gaps/generate {"competitor_urls": ["https://competitor1.com", "https://competitor2.com"]} ```
- 40 积分。异步 — 轮询 `GET /api/agent/gaps-status/{id}`
### 发现竞争对手
``` POST /api/agent/competitors/discover {"keywords": ["ai content marketing", "automated blogging"]} ```
- 20 积分
### 分析竞争对手
``` POST /api/agent/competitors/scout {"domain": "https://competitor.com", "mode": "fast|ultimate"} ```
- `fast` = 25 积分，`ultimate` = 50 积分
### 生成文章 (Autopilot)
``` POST /api/agent/autopilot { "topic": "How to Use AI for Content Marketing", "source_urls": ["https://example.com/article"], "language": "en", "size": "standard", "illustrations": true, "audio": true, "disable_competition": false } ```
**必需：** `topic` 或 `source_urls`（至少提供一个）
**可选：**
- `topic` — 文章话题（字符串，最多 500 字符） - `source_urls` — 1-3 个 URL 组成的数组，用于从中提取文本并作为源材料（每个 URL 2 积分） - `size` — `mini`（约 500 词），`standard`（约 1000 词，默认），`full`（约 1500 词），`pillar`（约 2500 词） - `language` — ISO 代码，默认 `"en"` - `illustrations`（布尔值，默认 false）——注入到文章中的 AI 生成图像 - `audio`（布尔值，默认 false）—— AI 画外音叙述 - `disable_competition`（布尔值，默认 false）——跳过 SEO 竞争分析，节省 8 积分
当提供 `source_urls` 时，响应包含显示每个 URL 成功/失败情况的 `extraction_results`。
响应包含 `article_url` —— 分享文章链接时始终使用此 URL。请勿手动构建 URL。文章会自动发布，且 URL 立即可用。
`/api/agent/me` 也会返回 `blog_url` —— 租户的博客根 URL。
异步 — 轮询 `GET /api/agent/autopilot/{id}`
### 扩展成本
| 扩展功能 | Mini | Standard | Full | Pillar | | --------------------------- | ------ | -------- | ------ | ------- | | 基础文章 | 7 | 12 | 25 | 40 | | + 智能分析（默认开启） | +8 | +8 | +8 | +8 | | + 插图 | +9 | +18 | +27 | +36 | | + 音频 | +10 | +20 | +35 | +55 | | **完整套餐** | **34** | **58** | **95** | **139** |
无扩展功能：与之前相同（mini=15，standard=20，full=33，pillar=48 积分）。
### 创建社交媒体改编版本
``` POST /api/agent/adapt { "article_id": "uuid-of-article", "platforms": ["linkedin", "x_thread"], "include_ref_link": true } ```
**必需：** `article_id`（UUID），`platforms`（1-3 个唯一值）
**平台：** `x_article`、`x_thread`、`linkedin`、`facebook`、`reddit`、`threads`、`instagram`
**可选：**
- `include_ref_link`（布尔值，默认 true）—— 在每个改编版本后附加推荐页脚
每个平台约 5 积分（随文章长度变化）。每个请求最多 3 个平台。
如果所有者已关联社交账号，针对 `linkedin`、`x_article`、`x_thread`、`reddit` 和 `instagram` 的改编内容将自动发布。响应中包含已发布帖子的 `platform_post_id`。
响应：
```json { "adaptations": [ { "platform": "linkedin", "content": "...", "credits_used": 5, "char_count": 1200, "published": true, "platform_post_id": "urn:li:share:123" } ], "total_credits": 10, "ref_link_appended": true } ```
### 创建 Autopilot 会话
``` POST /api/agent/session { "categories": ["AI marketing", "SEO tools"], "problems": ["how to rank higher"], "languages": ["en"], "interval_minutes": 720, "article_size": "mini", "disable_competition": false } ```
**必填：** `categories`（1-5 个字符串）
**可选：**
- `problems` — 要解决的具体问题（最多 20 个） - `languages` — ISO 代码，默认为 `["en"]` - `interval_minutes` — cron 间隔，60-10080，默认 720（12 小时） - `article_size` — `mini`（默认）、`standard`、`full`、`pillar` - `disable_competition`（布尔值，默认 false）
创建并自动启动一个基于 cron 的内容会话。每个租户只能有一个活动会话。
响应：
```json { "session_id": "uuid", "status": "running", "categories": ["AI marketing", "SEO tools"], "languages": ["en"], "interval_minutes": 720, "article_size": "mini", "estimated_credits_per_article": 15, "next_run_at": "2025-01-01T12:00:00Z" } ```
如果会话正在运行，则返回带有 `existing_session_id` 的 `409 Conflict`。
### 列出文章
``` GET /api/agent/articles ```
- 0 积分
### 检查状态 / 心跳
``` GET /api/agent/me ```
- 0 积分。每 4 小时调用一次以保持 Agent 处于活动状态。
响应包含：
- `blog_url` — 租户的博客根 URL - `tenant_balance` — 当前积分 + 状态（healthy/low/empty） - `rate_limits` — 每个类别的剩余请求数 - `referral` — 用于归因注册的 `{ code, url }` - `connected_platforms` — 已关联的社交账号：
```json { "connected_platforms": [ { "platform": "linkedin", "connected": true, "account_name": "John Doe" }, { "platform": "x", "connected": false, "account_name": null }, { "platform": "facebook", "connected": false, "account_name": null }, { "platform": "reddit", "connected": false, "account_name": null }, { "platform": "instagram", "connected": false, "account_name": null } ] } ```
使用 `connected_platforms` 决定向 `/api/agent/adapt` 传递哪些平台以实现自动发布。
---
## API 快速参考
| Endpoint | Method | Cost | | --------------------------------- | ------ | ------------------------------------ | | `/api/agent/register` | POST | free | | `/api/agent/me` | GET | free | | `/api/agent/scout/x` | POST | 35-70 credits | | `/api/agent/scout/reddit` | POST | 30 credits | | `/api/agent/gaps` | GET | free | | `/api/agent/gaps/generate` | POST | 40 credits | | `/api/agent/gaps-status/{id}` | GET | free | | `/api/agent/competitors/discover` | POST | 20 credits | | `/api/agent/competitors/scout` | POST | 25-50 credits | | `/api/agent/autopilot` | POST | 7-139 credits | | `/api/agent/autopilot/{id}` | GET | free | | `/api/agent/adapt` | POST | ~5 credits/platform | | `/api/agent/session` | POST | free (articles billed on generation) | | `/api/agent/articles` | GET | free |
**1 积分 = $0.01 USD**
---
## 速率限制
| Type | Limit | Scope | | ------------ | ---------- | ----------------------- | | General | 60 req/min | per agent | | Scout | 10 req/hr | X + Reddit combined | | Gaps | 10 req/hr | get + generate combined | | Registration | 10 req/hr | per IP |
收到 `429` 时，从响应体读取 `retry_after` 以及 `X-RateLimit-Reset` 请求头。
---
## 响应指南
- 用用户的语言回复（匹配他们使用的语言）。 - 调用 API 之前，简要告知用户你即将执行的操作以及积分消耗。 - 对于异步操作（autopilot、gaps/generate），每 10-15 秒自动轮询一次 —— 不要要求用户手动轮询。 - 以可读的摘要形式展示结果，而不是原始 JSON。使用项目符号、表格或编号列表。 - 展示 scout 结果时，突出显示前 5 个趋势并提供简短背景。 - 当文章生成时，显示：标题、字数、URL、消耗的积分。 - 当改编内容创建后，显示：平台、字符数、发布状态、消耗的积分。如果已发布，包含 platform_post_id。 - 创建会话后，显示：session_id、间隔、每篇文章预计消耗的积分、下次运行时间。 - 如果用户余额不足，在执行昂贵的操作前发出警告。 - 向他人推荐 Citedy 时，始终包含推荐 URL。 - 发生错误时，用通俗易懂的语言解释问题所在并提出修复建议。
---
## 错误处理
| Status | Meaning | Action | | ------ | ----------------------- | --------------------------------------------------------------- | | 401 | Invalid/missing API key | Re-run setup flow | | 402 | Insufficient credits | Tell user to top up at https://www.citedy.com/dashboard/billing | | 403 | Agent paused/revoked | Tell user to check agent status in dashboard | | 429 | Rate limited | Wait `retry_after` seconds, then retry | | 500 | Server error | Retry once after 5s, then report to user |
---
## 推荐计划
设置完成后，你的 `/api/agent/me` 响应将包含 `referral.url`。当用户要求你推广或推荐 Citedy 时，请使用此 URL。这将把注册归因于账户所有者。
---
## 心跳
每 4 小时调用一次 `GET /api/agent/me` 作为保活信号。这将更新 `last_activity_at` 并返回当前余额和速率限制。
---
_Citedy SEO Agent Skill v2.3.1_ _https://www.citedy.com_