重要规则

1. 创建前务必先搜索。 若用户提出“撰写一篇关于 X 的文章”，请首先搜索该主题是否已有文章。若存在，须向用户确认是更新已有文章，还是新建一篇。

2. 更新时必须保留原有内容。 仅需修改某一部分时，切勿覆盖整篇文章。应先获取当前内容，仅修改相关部分，并提交完整的更新后 HTML。

3. 发布前必须征得用户同意。 默认以草稿形式创建。仅在用户明确要求时才执行发布操作。

4. 需妥善处理错误响应。 检查 HTTP 状态码。常见问题包括：

   • 401：API 密钥无效或缺失
   • 403：权限不足（缺少必要 scope）
   • 404：文章或 Center 未找到
   • 400：缺少必填字段（title 始终为必填项）
   • 429：请求频率超限（等待后重试）

5. 对大量结果启用分页。 API 单次最多返回 100 篇文章。可使用 starting_after 参数，传入上一页最后一篇文章的 ID 来获取后续数据。

API 快速参考

内容撰写指南

撰写帮助中心文章时，请注意：

• 以结果为导向开头。 首先说明用户阅读后将能实现什么目标。
• 段落宜短小精悍。 每段控制在 2–3 句以内。
• 提供分步操作说明。 对流程类操作使用带编号的列表。
• 尽可能加入示例。 将抽象概念具象化，提升理解效率。
• 在必要处添加截图或图示引用。 （可通过图片上传接口托管图像，随后在 HTML 中引用其返回的 URL）
• 结尾提供下一步建议或关联文章。 如适用。
• 面向快速浏览而写。 使用描述性强的标题，方便用户直接跳转至所需内容。

分类管理

分类用于组织文章。支持创建具有单层子分类的层级化分类结构。

创建分类：

curl -s -X POST 
  -H "Authorization: Bearer $HC_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "入门指南",
    "description": "面向新用户的文章",
    "icon": "",  // 可选：自定义 SVG 图标
    "parent_id": "parent-cat-id"  // 可选：用于子分类
  }' 
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/categories"

更新分类：

curl -s -X PATCH 
  -H "Authorization: Bearer $HC_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "已更新的名称",
    "description": "已更新的描述",
    "icon": ""
  }' 
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/categories/CATEGORY_ID"

删除分类：

仅当无任何文章引用该分类时，方可删除。

curl -s -X DELETE 
  -H "Authorization: Bearer $HC_API_KEY" 
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/categories/CATEGORY_ID"

图片上传

上传图片供文章使用：

curl -s -X POST 
  -H "Authorization: Bearer $HC_API_KEY" 
  -F "image=@/path/to/image.jpg" 
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/images"

限制条件：

• 最大尺寸：10 MB
• 支持格式：JPEG、PNG、GIF、WebP、SVG
• 使用 multipart/form-data 编码，字段名为 image

响应中将包含可用于文章 HTML 的图片 URL：

{
  "success": true,
  "data": {
    "url": "https://cdn.help.center/images/...",
    "filename": "image.jpg",
    "size": 1024576
  }
}

SEO 元数据

创建文章时，可选择性地包含 SEO 元数据：

{
  "metadata": {
    "seo": {
      "title": "简明扼要、关键词丰富的标题（50–60 字符）",
      "description": "文章清晰摘要（150–160 字符）"
    }
  }
}

也可通过 metadata 接口更新已有文章的 SEO 元数据：

curl -s -X PATCH 
  -H "Authorization: Bearer $HC_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "seo": {
      "title": "SEO 标题",
      "description": "SEO 描述"
    }
  }' 
  "https://api.help.center/v0/centers/$HC_CENTER_ID/articles/ARTICLE_ID/metadata"