SEONIB AI Ecommerce SEO & Content Marketing Agent

Overview / 功能介绍

SEONIB helps ecommerce businesses create and distribute marketing content.
Generate SEO-optimized blogs, product articles, cover images, and publish to connected stores.

SEONIB 帮助电商商家自动生成、管理和发布营销内容。
支持 SEO 博客、产品文案、封面图片，并一键发布到已连接的店铺平台。

Core capabilities / 核心能力:

Supported platforms / 支持平台: Shopify · WordPress · Shopline · Shoplazza · Wix

API endpoints (agent-internal reference — never expose to user):

Decision Matrix

Trigger Keywords

Use this skill when users mention any of the following:

English:
ecommerce content, ecommerce SEO, Shopify blog, Amazon seller content,
product descriptions, product marketing, SEO articles, blog writer, AI writer,
content calendar, brand content, DTC marketing, cross-border ecommerce,
store marketing, improve Google rankings, AI search optimization, AEO content,
content automation, blog generation, marketing copy, product article

中文触发词：
电商内容营销、跨境电商、Shopify博客、SEO文章、AI写文章、商品推广文案、
产品介绍、品牌内容、独立站营销、谷歌SEO、AEO优化、博客生成、
内容营销、帮我写文章、生成博客、发布博客、店铺内容

Trigger Examples / 触发示例

English:
- "Write a blog for my Shopify store"
- "Create SEO content for my product"
- "Publish this article to WordPress"
- "Generate a blog about summer fashion"
- "Show my unpublished drafts"
- "Create a blog cover image"

中文：
- "帮我写一篇 Shopify 博客"
- "生成商品营销文章"
- "优化我的独立站 SEO"
- "发布文章到我的店铺"
- "查看我的博客草稿"
- "帮我生成博客封面"
- "写一篇关于夏季产品的 SEO 博客"

Common User Scenarios

0. Prerequisites — auth & base URL

Every endpoint requires a console JWT. Before calling anything, make sure you have:

• SEO_BASE_URL — API origin. Defaults to https://api.seonib.com (production); override only
  for local/staging. The helper script applies this default automatically.
• SEO_TOKEN - a valid JWT (Seonib 令牌). First time? Ask the user to open
  https://app.seonib.com/zh-CN/dashboard/skill/, find their Seonib 令牌, click 复制, and
  send it to you in chat. Then save it with bash skills/seonib/scripts/seo.sh save-token "<jwt>"
• cached to ~/.config/seonib/token (mode 600), so this is only needed once (no environment
  variables needed). The script resolves the token as: SEO_TOKEN env var (optional override)
  -> cache file -> interactive prompt (TTY only). If no token is available and the script cannot
  prompt, ask the user through the agent UI (see Interactive User Input).

Auth is sent as Authorization: Bearer <SEO_TOKEN>.
(The server also accepts ?_token=<jwt> as a query param or a token cookie, but prefer the
Bearer header.)

Standard response envelope

All handlers respond with the same shape:

// success
{ "message": "success", "data": <any>, "code": 0, "errorCode": 0 }

// failure
{ "message": "<error msg>", "code": -1, "errorCode": <int> }   // no `data` field

Treat code != 0 as an error and surface message to the user.

Two ways to call

A. Helper script (recommended — same behavior on every agent):

# One-time: save your JWT (interactive prompt, cached to ~/.config/seonib/token, mode 600).
bash skills/seonib/scripts/seo.sh login

# Then call any capability — token is read from the cache, an env var, or a prompt (if TTY).
bash skills/seonib/scripts/seo.sh <command> [arg]

Commands: login · integrations · brand-ai · blogs · gen-cover '<json>' · publish-content '<json>' · generate-blog '<json>'

B. Raw curl — see each capability below for the exact request.

1. 获取用户集成平台 — GET /api/v1/integrations

List every integration connected by the current user's team.

Request: no params.

Response data: array of ConsoleIntegration:

[
  {
    "id": 7,
    "name": "My WordPress",
    "desc": "",
    "type": "wordpress",          // platform type — use this value in integrationStr
    "platform": "wordpress",
    "teamId": 3,
    "uid": 11,
    "state": 1,                   // 1 = configured/active, 0 = incomplete
    "config": { ... },            // platform-specific; do not modify blindly
    "handle": "",
    "instanceId": "",
    "accessToken": "...",
    "refreshToken": "...",
    "expireTime": 0,
    "scope": "",
    "createdAt": 1719900000000,
    "updatedAt": 1719900000000
  }
]

Only integrations with state == 1 can be publish targets. If a needed platform has
state == 0, tell the user to finish configuring it in the console.

bash skills/seonib/scripts/seo.sh integrations

2. 生成博客封面 — POST /api/v1/genImageV2

Generate a 1536×1024 WebP blog cover from a keyword. The service translates the keyword to
English internally, so a Chinese keyword is fine. Deducts image credits from the team.

Request body:

{ "keyword": "sustainable fashion tips" }

Response data: a string — the OSS URL of the generated image, e.g.
"https://.../runware/xxxx.webp".

> ⚠️ Known quirk: if image generation fails, the handler still returns HTTP 200 with
> data: "" (empty string) instead of an error. Treat an empty data as a failure and
> report it; do not present an empty string as a successful cover URL. (Credit-deduction errors
> are returned normally as failures.)

bash skills/seonib/scripts/seo.sh gen-cover '{"keyword":"sustainable fashion tips"}'

# raw:
curl -sS -X POST "$SEO_BASE_URL/api/v1/genImageV2" \
  -H "Authorization: Bearer $SEO_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"keyword":"sustainable fashion tips"}'

Display the cover: after generating, show the image to the user with markdown —
![cover](<url>) — not just the raw URL (also keep the URL copyable). New covers are served as
image/webp, so they render in GUI/IDE agents.

3. 获取我的品牌空间 — GET /api/v1/brandAi

Read the current team's 品牌空间. This is the primary context source for content
generation — bigJson holds brand information, products, internal links, external links, media
assets (images/videos), and SEO settings. Before generating a blog, fetch brand-ai and use
these assets to enrich the content (insert relevant internal/external links, images, videos,
and product references).

Request: no params. Scoped to the current user's team.

Response data: ConsoleBrandAi:

{
  "id": 5,
  "teamId": 3,
  "uid": 11,
  "bigJson": { /* 品牌空间配置 */ },
  "createdAt": 1719900000000,
  "updatedAt": 1719900000000
}

If the team has never set up 品牌空间, the server returns HTTP 404 with message: "Brand ai not found". When generating content, do not block on this — tell the user 品牌空间 yields
higher-quality blogs (auto-inserts their links, images, videos, products), suggest configuring
it in the Seonib Console, then proceed without enrichment.

bash skills/seonib/scripts/seo.sh brand-ai

4. 发布生成的内容 — POST /api/v1/publishContent

Publish agent-generated blog content directly to the user's connected integrations — without
needing a pre-existing seonib blog. Use this when the blog was generated in Codex/Claude (the
content is in the request body, not in seonib's database). The server stages the content to OSS
internally (the agent does no staging) and reuses seonib's integration publish pipeline.

Request body:

{
  "integrationStr": "wordpress",              // required, comma-separated platform types
  "blog": {
    "title": "Sustainable Fashion Tips",       // required
    "content": "# Sustainable Fashion\n\n...", // required, Markdown (or HTML if contentFormat="html")
    "desc": "A short summary",                 // optional
    "cover": "https://.../cover.webp",         // optional
    "slug": "sustainable-fashion-tips",        // optional, auto-generated from title if omitted
    "lang": "en",                              // optional (wix reads this)
    "author": "Jane",                          // optional
    "seo": {                                   // optional
      "title": "...", "description": "...", "keywords": "..."
    },
    "contentFormat": "markdown"                // optional, "markdown" (default) | "html"
  }
}

integrationStr platform types (must already be configured, see capability 1):
api-post, wordpress, shopline, shopify, shoplazza, wix.

Behavior:
- content is staged to OSS server-side. contentFormat:"html" uploads as .html (passed through
unchanged); markdown uploads as .md and is converted to HTML by the platform (matches the
blog-generation pipeline). Prefer Markdown.
- No seonib blog row is created (publish-only). No scheduling — always immediate.
- Success = dispatched. Publish returns nil once configs are valid and the per-platform
goroutines have run; per-platform HTTP delivery errors are logged server-side, not returned.
On a config-incomplete error, finish setup in the console first.
- Requires a non-free user level.

Response data: { "ossLink": "<oss url>", "slug": "<slug>" }.

Example:

bash skills/seonib/scripts/seo.sh publish-content \
  '{"integrationStr":"wordpress","blog":{"title":"Sustainable Fashion Tips","content":"# Sustainable Fashion\n\n...","slug":"sustainable-fashion-tips"}}'

# raw:
curl -sS -X POST "$SEO_BASE_URL/api/v1/publishContent" \
  -H "Authorization: Bearer $SEO_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"integrationStr":"wordpress","blog":{"title":"...","content":"# ..."}}'

Publishing workflow:

1. Ensure authentication (seo.sh login or a cached token).
2. List integrations (integrations) to see connected platforms and their type.
3. Verify the selected platform(s) have state == 1 (active). If not, ask the user to finish
   setup in the console.
4. Fetch brand-ai (brand-ai) and use it as context to generate the blog content. Use the
   品牌空间 internal links, external links, images, videos, and products to enrich the blog —
   insert them where relevant. If brand-ai returns 404, do not block — tell the user that
   configuring 品牌空间 produces higher-quality blogs (auto-inserts their links, images, videos,
   products), suggest setting it up in the Seonib Console, then proceed without enrichment.
5. Collect the generated blog's title and content (Markdown), plus any optional fields
   (desc, cover, slug, lang, tags, author, seo).
6. Review with the user before publishing. Show a summary of the payload — every field
   below, marking empty ones as "未设置"; do not silently omit any (including author and SEO):
   - 平台 (integrationStr)
   - 标题 (title)
   - slug
   - 摘要 (desc)
   - 封面 (cover)
   - 标签 (tags)
   - 语言 (lang)
   - 作者 (author)
   - SEO 源信息 — seo.title / seo.description / seo.keywords
   - 内容格式 (contentFormat)
   - 正文长度 (e.g. "~4,200 chars, Markdown") — do NOT print the full content

Then ask: "要补充或修改什么吗？可以补充，或跳过直接发布。"
- If the user wants to补充 → update those fields, then re-confirm (still without dumping content).
- If the user says skip / publish → go to step 7.
7. Call publish-content with integrationStr and the blog object.
8. Report success ({ossLink, slug}, code: 0) or the specific error. Note that success means
dispatched, not guaranteed delivery (per-platform errors are server-side logs).

5. 获取我的博客 - GET /api/v1/blogs

List the current team's blogs with optional filtering. Pass state=0 to fetch
unpublished / draft blogs - the most common use case (reviewing drafts, picking a blog to
publish, etc.). Scoped to the current user's team.

Query params (all optional, sent on the query string):

> lang is optional. Omit it to list blogs in all languages; pass a code (en, zh-CN, …)
> to scope to one language. If the user asks for a specific language, pass it; otherwise omit
> lang and each result's lang field tells you its language.

Response data: a page object:

{
  "data":  [ /* ConsoleBlog[] */ ],
  "total": 42,
  "page":  1,
  "size":  10
}

Each ConsoleBlog item (key fields):

{
  "id":     123,
  "title":  "Sustainable Fashion Tips",
  "desc":   "A short summary",
  "slug":   "sustainable-fashion-tips",
  "cover":  "https://.../cover.webp",
  "ossLink":"https://.../content.md",   // Markdown content on OSS - fetch this to read the body
  "state":  0,                          // 0未发布 1已发布 2预约发布中 3发布中
  "lang":   "en",
  "projectId": 5,
  "author": "Jane",
  "seo":    { "title":"...", "description":"...", "keywords":"..." },
  "tags":   ["fashion","sustainable"],
  "publishDate":         0,             // ms timestamp, 0 if not set
  "scheduledPublishDate":0,
  "createdAt": 1719900000000,
  "updatedAt": 1719900000000
}

> Note: the blog body is not in data.content - it lives at data.ossLink (a Markdown
> file on OSS). To read a blog's full content, fetch its ossLink URL (e.g.
> utils.FetchMarkdownAsHTML, or a plain curl/WebFetch). content is typically empty in this
> endpoint.

# unpublished drafts, first 20 (all languages):
bash skills/seonib/scripts/seo.sh blogs 'state=0&page=1&size=20'

# unpublished, scoped to English:
bash skills/seonib/scripts/seo.sh blogs 'state=0&lang=en'

# all states, search by title:
bash skills/seonib/scripts/seo.sh blogs 'state=-1&lang=en&search=fashion'

# no arg = state=0 (unpublished), all languages:
bash skills/seonib/scripts/seo.sh blogs

# raw:
curl -sS -X GET "$SEO_BASE_URL/api/v1/blogs?state=0&page=1&size=20" \
  -H "Authorization: Bearer $SEO_TOKEN" \
  -H "Accept: application/json"

Typical use: fetch unpublished blogs (state=0) to review drafts. To publish a seonib-stored
blog, use the console's blog-publish flow; for agent-generated content that isn't in seonib's
database, use publish-content (capability 4).

6. 触发博客生成 - POST /api/v1/bulkGenerateBlog

Trigger seonib's own blog-generation pipeline to create blog(s) from a keyword or topic. The
agent does not write the content - it only passes the user's requirements; seonib generates
the blog asynchronously. This is the counterpart to publish-content (capability 4), which
publishes content the agent wrote.

Use this when: the user chose seonib 生成 mode - the agent asks which mode first
(see 生成博客 / Write a Blog in Interactive User Input); this capability is for when they want
seonib to produce the blog from a keyword/topic, not the agent writing it inline.

Request body - only topics[].name (the keyword) is required. Include other fields only
when the user explicitly asks for them; omit everything else and seonib uses its defaults.

// minimal - just the keyword is enough:
{ "topics": [ { "name": "sustainable fashion tips" } ] }

All settable fields (only name is required; add the rest per user request):

{
  "topics": [                            // REQUIRED, non-empty - one blog per topic
    {
      "name": "sustainable fashion tips", // REQUIRED - the generation keyword (used as Keywords)
      "link": "https://example.com/ref"  // optional reference URL
    }
  ],
  // --- generation options (all optional) ---
  "tone":               "professional",     // writing tone
  "wordCount":          "2",                // "1"=800-1000  "2"=1000-2000  "3"=2000-3000
  "perspective":        "first-person",     // 文章视角
  "audience":           "eco-conscious shoppers",
  "industry":           "fashion",
  "targetLanguage":     "en",               // output language
  "targetCountry":      "US",
  "targetRegion":       "North America",
  "translateLanguages": "",                 // comma-separated, to also translate the output
  "brand":              "EcoStyle",         // brand name (product/productLink come from team)
  // --- generation flags (0/1) ---
  "isNeedImages":       1,
  "isNeedSeo":          1,
  "isNeedSlug":         1,
  "isNeedCover":        1,
  "needInternalLink":   1
}

Behavior:
- Credits are deducted per topic (type bulk_blog_generate). If the team has insufficient
credits, the call fails with a deduction error.
- The server creates one ConsoleBlogGenerateQueue task per topic and enqueues it. Returns
"ok" - success means queued, not generated.
- Generation is asynchronous (handled by the seonib worker). The finished blog later appears in
GET /api/v1/blogs (capability 5); poll there to see results.
- product and productLink are taken from the team settings, not the request body - don't
bother passing them.
- Each topic's name is the keyword; pass multiple topics to generate multiple blogs in one call.

Response data: "ok" (string) on success.

Example:

# minimal - just the keyword:
bash skills/seonib/scripts/seo.sh generate-blog '{"topics":[{"name":"sustainable fashion tips"}]}'

# with user-specified preferences (include only what the user asked for):
bash skills/seonib/scripts/seo.sh generate-blog \
  '{"topics":[{"name":"sustainable fashion tips"}],"targetLanguage":"en","tone":"professional","wordCount":"2"}'

# raw:
curl -sS -X POST "$SEO_BASE_URL/api/v1/bulkGenerateBlog" \
  -H "Authorization: Bearer $SEO_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"topics":[{"name":"sustainable fashion tips"}]}'

Product-based generation: if the user gives a product (name + URL) instead of a keyword,
use POST /api/v1/bulkGenerateBlogByGoods with a goods array
([{name, url, image, longTailKeywords, blogTitle, blogAngle}]) - same generation options, same
credit deduction. No script command; call it via raw curl. Prefer generate-blog for
keyword-driven blogs.

Workflow:
1. Collect the keyword/topic (required) and any preferences (tone, word count, language, etc.).
If the user doesn't specify a preference, omit the field - seonib uses sensible defaults.
2. (Optional) fetch brand-ai (capability 3) to confirm brand/product context - the generation
uses the team's product settings automatically.
3. Call generate-blog with topics (one per blog) and the collected options.
4. Tell the user the blog is being generated (queued), not done yet. To check results, list
blogs (blogs, capability 5) - new blogs appear with state=0 (未发布) once generated.

Interactive User Input

When any required input is missing, do not guess. Ask the user, wait for the answer, then
continue. Combine related questions into a single interaction whenever possible. After receiving
answers, proceed automatically without asking for extra confirmation — except for outward-facing

Talk to the user in plain language - never expose API details. The user does not know APIs. Do not mention endpoint paths, HTTP methods, capability numbers, JSON field names, or internal command names. Translate to simple terms the user understands:

Use the API internally; present questions and results in human terms. Capability numbers and
field names in this doc are for your reference - do not repeat them to the user.
actions like publishing, where you must review with the user first (see Publish Blog).

Authentication

If no valid SEO_TOKEN is available (env, cache, or interactive prompt), do not just tell the
user to "run login" - they won't know where the token comes from. Walk them through it in plain
language:

1. Tell the user: "请打开 https://app.seonib.com/zh-CN/dashboard/skill/ ，找到 Seonib 令牌，
   点 复制，然后直接发给我。"
2. When the user sends the token in chat, save it with:
   bash bash skills/seonib/scripts/seo.sh save-token "<jwt>"
   It's cached to ~/.config/seonib/token (mode 600), so this is only needed once.
3. Proceed with the API call - the script reads the cached token automatically.

Do not invent or reuse an expired token. (The interactive seo.sh login command still exists for
users who prefer a terminal, but the chat flow above is the default.)

Publish Blog

Use publish-content (capability 4) to publish agent-generated content. Make sure every required
input is available:

• Before generating the content → fetch brand-ai (capability 3) and use it as context to
  enrich the blog — insert relevant internal links, external links, images, videos, and product
  references from the 品牌空间. If brand-ai returns 404, do not block: tell the user 品牌空间
  yields higher-quality blogs (auto-inserts links/images/videos/products), suggest configuring it
  in the Seonib Console, then proceed without enrichment.
• Target platform unknown → ask "Which platform would you like to publish to?" Available
  types: wordpress, shopify, shopline, shoplazza, wix, api-post. If several are
  connected, let the user pick one or more.
• Title or content missing → ask for the blog title and the Markdown content before calling
  the API. Do not fabricate content.
• publish-content is always immediate (no scheduling).
• Always review before publishing. Show the user every field with a plain Chinese label (do NOT show API field names): 发布平台, 标题, 网址路径, 摘要, 封面, 标签, 语言, 作者, SEO 信息 (标题/描述/关键词), 内容格式, 正文长度 - mark empty ones as "未设置". Do not print the full 正文, and do not silently omit 作者 or SEO. Ask whether to补充 or publish now. If they补充, update and re-confirm; if they say publish, proceed. Do not call the API until the user confirms.

Generate Blog Cover

If no keyword is provided, ask: "What keyword should I use for the blog cover?" Wait for the
answer before calling gen-cover. After it returns, display the cover as a markdown image
(![cover](<url>)), not just the URL — the user should see it. Also keep the URL copyable.

品牌空间

If the user asks about 品牌空间 / brand settings, call brand-ai. If it returns 404 "Brand ai
not found", tell the user 品牌空间 must be configured in the Seonib Console first.

我的博客 / 未发布博客

Use blogs (capability 5) to list the team's blogs. If the user asks for "未发布" / drafts /
unpublished blogs, pass state=0. lang is optional - omit it to list blogs in all languages,
or pass a code (en, zh-CN, …) if the user wants a specific language. Present the results as a
concise list (标题, 状态, 语言, 封面 if present) in plain terms - not a raw JSON dump. To
read a blog's full body, fetch its ossLink (Markdown on OSS); do not assume content is
populated.

生成博客 / Write a Blog

When the user asks to "generate / write a blog" (帮我生成/写一篇博客), first ask which mode -
do not assume:

• seonib 生成 (generate-blog, capability 6): seonib's pipeline writes the content; the agent
  only passes the keyword + options. Costs credits, asynchronous (queued) - the blog
  appears as a draft (state=0) in blogs (capability 5) when done, not instantly. Best when the
  user wants seonib's SEO-optimized generation and doesn't need the content in-chat.
• 本地 agent 编写 (publish-content, capability 4): the agent writes the content inline (use
  brand-ai as context), reviews it with the user, then publishes to a connected platform. No
  generation credits (only the publish). Best when the user wants to see/edit the content now or
  publish immediately.

Ask the user in plain terms: "想让系统自动生成，还是我来帮你写？" (do not mention API names). If they pick 系统生成 -> see below. If 我来帮你写 -> follow the Publish Blog workflow (fetch brand-ai -> write content -> review -> publish-content).

If seonib 生成 (generate-blog): Required: at least one topic keyword - if missing, ask
"想生成什么主题的博客？" Collect optional preferences (tone, word count, target language, audience)
only if the user cares - otherwise omit them (seonib uses defaults). Remind the user that
generation costs credits and is asynchronous (queued). Generated blogs are drafts
(state=0); publish later via publish-content or the console.

Error Recovery

If an API returns an authentication failure, missing/invalid token, or invalid parameters, ask
the user for the required information. Never fabricate values. On integration.config_incomplete,
list integrations and ask the user to finish setup.

Working rules for the agent

1. Don't guess credentials. SEO_BASE_URL defaults to https://api.seonib.com (override
   only for local/staging). SEO_TOKEN is required — prefer seo.sh login for first-time
   setup; don't require users to set environment variables. The script reads the token from the
   cache, an env var, or an interactive prompt. If none are available (the script errors with
   "SEO_TOKEN is required"), follow Interactive User Input → Authentication. Never echo or
   log the token; never invent one.
2. Check the envelope. code != 0 (or missing data) means failure — report message.
3. Before publishing, list integrations and only pass state==1 platform types in
   integrationStr. Don't publish to a platform the user hasn't connected.
4. genImageV2 empty string = failure, not success.
5. Return concise, parsed results to the user (e.g. the cover URL or the publish outcome), not
   raw JSON dumps unless asked.
6. Use publish-content for agent-generated content. Never fabricate blog content or pass
   made-up values.
7. blogs defaults to unpublished (state=0); lang is optional. Omit lang to list blogs
   in all languages, or pass a code (en, zh-CN, …) to scope. The blog body lives at each
   item's ossLink (Markdown on OSS), not in content.
8. When the user wants a blog written, ask which mode first - don't assume. "seonib 生成" ->
   generate-blog (capability 6): agent passes only keyword + options, seonib generates async
   (costs credits, returns "ok" = queued, poll blogs for results; product/productLink
   come from team settings). "本地 agent 编写" -> publish-content (capability 4): the agent
   writes the content inline, reviews it, then publishes.
9. Talk to the user in plain language - hide API details. Never expose endpoint paths,
   capability numbers, JSON field names, or command names to the user. Say 让系统生成 / 我来帮你写
   (not generate-blog / publish-content), 网址路径 / 摘要 / 发布平台 / SEO 标题·描述·关键词
   (not slug / desc / integrationStr / seo.*). Use APIs internally; present everything in
   simple terms. See the plain-language table in Interactive User Input.