Communitygithub.com

thinslatelabs/keepp-skill

管理 Keepp 页面的 Agent 技能:支持产品卡片、促销代码、线索采集和页面设置,通过 Keepp Agent API 实现。

keepp-skill 是什么?

该技能允许 AI Agent(如 Claude Code、Cursor 等)通过 Keepp Agent API 管理创作者或小企业的社交链接页面。它能创建、列出、更新和删除产品“卡片”(目录),并调整页面模式(仅链接、仅目录或两者)、关于文本、英雄按钮、卡片默认行为和主题。技能要求使用 Pro 账户生成的 API 密钥进行 Bearer 认证。在操作卡片时,支持设置图片、标题、描述、价格、促销代码、类别以及行为(点击后直接触发或打开详情)。对于服务型业务,技能支持线索采集模式,通过页面表单收集用户信息。此外,用户需要了解:链接块、社交媒体图标和个人资料(如头像、显示名称)只能通过 Keepp 仪表盘管理,无法通过此 API 修改。该技能非常适合需要批量更新目录、批量创建带促销代码的商品卡片、或快速调整页面布局和风格的场景。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add thinslatelabs/keepp-skill

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

管理 Keepp 页面

什么是 Keepp

Keepp 将创作者或小企业的社交链接页面转化为一个页面:一个可分享的集合,包含产品“卡片”和链接,旨在将关注者转化为买家并获取线索。它被卖家、联盟营销者、教练、课程创作者以及 Instagram、YouTube、TikTok、Pinterest 和 X 上的链接简介创作者广泛使用。

一个 Keepp 页面由以下部分组成:

  • 个人资料 — 头像、显示名称、简短简介
  • 社交图标 — 指向所有者社交账户的链接
  • 链接块 — 指向网站、预约页面、WhatsApp 等的按钮(以及分区标题)
  • 目录卡片 — 可购买的产品卡片(图片、价格、促销代码、行动按钮)
  • 模式 — 仅链接、仅目录 或 链接与目录

此 API 控制的内容

此 API 管理两件事:

  1. 目录卡片(帖子) — 创建、列出、更新和删除所有者目录中的产品卡片。
  2. 页面设置 — 页面的布局模式、关于文本、英雄按钮、目录卡片默认值和主题(请参阅下方“页面设置”)。

通过此 API 无法更改的内容:社交图标、链接块 和 个人资料详细信息(显示名称、头像、页面 URL)。这些内容由所有者通过 Keepp 仪表盘设置——如果用户询问,请引导其前往 Keepp 仪表盘。

身份认证

每次请求都需要所有者的 API 密钥作为 Bearer 令牌:

Authorization: Bearer keepp_live_…

基础 URL:https://api.keepp.link。密钥由 Pro 账户在仪表盘的 AI Agent 下生成。如果您没有密钥,请向用户索取。

端点

方法路径用途
GET/api/v1/posts?cursor=列出目录中的卡片(分页)。
POST/api/v1/posts创建一张卡片。
GET/api/v1/posts/:postId获取一张卡片。
PATCH/api/v1/posts/:postId更新一张卡片。
DELETE/api/v1/posts/:postId删除一张卡片。

卡片内容模型

创建/更新卡片时需提供三个顶级字段:imageUrls、userContent 和 cardOverrides。

{
  "imageUrls": ["https://…/photo.jpg"],   // 最多 5 张;系统会为您获取并存储。每张 ≤10MB,JPEG/PNG/WebP/GIF 格式,需为公开的直接 URL
  "userContent": {
    "name": "真丝围巾",                  // 简短标题(可选)
    "description": "手工染色桑蚕丝,90×90cm。",   // 必填
    "price": "$72",                        // 自由文本 — "$72"、"From $50"、"₹1,499"(可选)
    "promoCode": "SAVE15",                 // 促销 / 推荐 / 折扣代码(可选)
    "category": "accessories",             // 下方类别之一(可选)
    "links": ["https://…"],                // 卡片上显示的额外链接(可选)
    "contacts": [{ "type": "whatsapp", "value": "+15551234567" }]   // 可选
  },
  "cardOverrides": {                       // 卡片行为(可选;省略则继承页面默认值)
    "clickAction": "open_detail",          // "open_detail" | "trigger_cta"
    "ctaType": "link",                     // "message" | "link" | "lead_collection"
    "ctaUrl": "https://shop…/scarf",       // 当 ctaType 为 "link" 时必填
    "ctaLabel": "立即购买"                  // 按钮文本
  }
}

description 是唯一必填字段。其他均为可选;省略 cardOverrides 将继承所有者页面的全局默认值。

类别: clothing、jewellery、accessories、home_decor、beauty、food_beverage、art、stationery、plants、fitness、travel、real_estate、services、pets、kids_baby、books_media、crafts、other。

联系方式类型: phone、email、whatsapp、telegram、other。

卡片行为——两种决策

1. clickAction — 点击卡片时的行为:

  • open_detail(默认)— 打开详细视图(全部图片、完整描述、价格、促销代码、行动按钮)。适用于买家在行动前需要了解上下文的情况。
  • trigger_cta — 点击后直接触发行动,不显示详情屏幕。适用于自解释商品,旨在最小化操作步骤。

2. ctaType — 行动按钮的功能:

  • message — 打开向商家发送消息的界面。当没有结账链接时的安全默认值。
  • link — 打开 ctaUrl(Shopify/Etsy 页面、联盟链接、预约页面、Google 表单)。需要 ctaUrl。适用于有专用目标链接的情况。
  • lead_collection — 在页面上打开一个简短表单,捕获访问者的联系方式并保存为线索。适用于捕获尚未准备购买的人群(候补名单、销售名单、咨询)。收集的字段通过页面设置端点中的 catalogCard.leadCollection 在页面级别设置(详见下方)——这些设置适用于所有卡片,而非每张卡片独立设置。

将 ctaLabel 设置为与行动匹配的文本:"Buy now"、"Order now"、"Get the lookbook"、"Reserve yours"、"Get notified"。

页面设置

读取和更改页面的整体配置。

方法路径用途
GET/api/v1/storefront获取当前页面设置。
PATCH/api/v1/storefront更改设置。仅发送您要更改的字段——它们会合并到当前配置中。

可编辑字段:

{
  "mode": "links_and_catalog",   // "links_only" | "catalog_only" | "links_and_catalog"
  "about": "来自里斯本工作室的手工陶瓷。",  // 页面简短标语(≤280 字符)
  "mainCta": {                    // 页面顶部的英雄按钮
    "enabled": true,
    "label": "预约通话",
    "url": "https://cal.com/me"   // 启用时必填
  },
  "catalogCard": {                // 所有卡片的页面级别默认值
    "showCardDetails": true,
    "clickAction": "open_detail", // "open_detail" | "trigger_cta"
    "ctaType": "message",         // "message" | "link" | "lead_collection"
    "ctaUrl": "https://…",        // 当 ctaType 为 "link" 时必填
    "ctaLabel": "立即下单",
    "leadCollection": { "phone": true, "email": true, "instagram": false, "message": true }
  },
  "theme": {
    "useCustomTheme": true,       // 必须为 true,否则 preset/brandColor 不会生效
    "preset": "professional",     // "calm" | "professional" | "playful" | "dark"
    "brandColor": "#d7494c"       // 6 位十六进制颜色
  }
}
  • 部分更新会合并。 PATCH {"theme":{"useCustomTheme":true,"brandColor":"#000000"}} 仅更改主题;模式、卡片等保持不变。
  • 主题保护: 除非 useCustomTheme 为 true,否则 preset/brandColor 会被忽略——请在同一请求中发送 useCustomTheme。
  • catalogCard 是所有卡片的默认值。 卡片的 cardOverrides(见上文)的优先级高于这些设置。更改这些设置可一次性重新样式化所有卡片。
  • leadCollection 设置页面级线索表单收集哪些字段(没有按卡片单独选择字段)。
  • 无效组合会被拒绝并返回 400 INVALID_STOREFRONT_CONFIG(例如 ctaType:"link" 但未提供 ctaUrl)。

用例示例

联盟营销/网红产品 + 促销代码 → 外部链接

{
  "imageUrls": ["https://example.com/serum.jpg"],
  "userContent": { "name": "维生素C精华", "description": "我的每日焕肤精华——使用我的代码享受 15% 折扣。", "price": "$28", "promoCode": "GLOW15", "category": "beauty" },
  "cardOverrides": { "clickAction": "trigger_cta", "ctaType": "link", "ctaUrl": "https://brand.com/serum?ref=me", "ctaLabel": "使用我的代码购买" }
}

通过自有商店销售精品产品

{
  "imageUrls": ["https://example.com/scarf.jpg"],
  "userContent": { "name": "真丝围巾", "description": "手工染色桑蚕丝,90×90cm。", "price": "$72", "category": "accessories" },
  "cardOverrides": { "clickAction": "open_detail", "ctaType": "link", "ctaUrl": "https://myshop.com/scarf", "ctaLabel": "立即购买" }
}

教练/服务——捕获线索而非直接销售

{
  "imageUrls": ["https://example.com/program.jpg"],
  "userContent": { "name": "1对1辅导", "description": "6周项目,帮你获得前5个客户。", "price": "From $400", "category": "services" },
  "cardOverrides": { "clickAction": "trigger_cta", "ctaType": "lead_collection", "ctaLabel": "立即申请" }
}

响应与错误

成功:{ "ok": true, "data": { … } }。错误:{ "ok": false, "error": { "code": "…", "message": "…" } }。

  • 401 NO_API_TOKEN / INVALID_API_TOKEN — 密钥缺失或已撤销。请向用户索取有效密钥。
  • 403 PLAN_REQUIRED — 账户不是 Pro 版本。
  • 422 INVALID_IMAGE — 无法获取图片 URL,或类型/大小错误、重定向或解析为私有地址。请使用直接、公开的 https 图片 URL。
  • 429 RATE_LIMITED — 每分钟超过 60 次请求。请降低频率后重试。

指导

  • 删除卡片前请与用户确认。
  • 只要有 price 和 promoCode,请务必设置它们——它们会显示在卡片和详情视图中,是联盟营销和促销场景的核心。
  • 批量创建时,请保持每分钟不超过 60 次请求。
  • 卡片会立即发布到页面上。
  • 您可以管理卡片和页面设置(模式、关于文本、英雄按钮、卡片默认值、主题)。对于链接、社交图标和个人资料详情(名称、头像、页面 URL),请告知用户使用 Keepp 仪表盘。

更多信息

Keepp 的使用指南详细介绍了 Keepp 页面:

相关技能