# 阿美巴 AI 官网内容发布 API

用于“阿美巴内容判断引擎”将已经人工确认的终稿发布到 AI 官网知识中心。网站只保存和展示终稿，不会调用 AI 改写正文。

## 发布目标配置

```text
base_url: https://www.aiameiba.com
health_path: /api/internal/content/v1/health
upsert_path: /api/internal/content/v1/articles/upsert
auth_type: bearer
token_environment_name: CONTENT_INGEST_TOKEN
site_profile: ai
public_url_rule: https://www.aiameiba.com/knowledge/{slug-or-content_id}
```

服务端环境变量：

```dotenv
CONTENT_INGEST_TOKEN=请设置独立的长随机密钥
PUBLIC_SITE_URL=https://www.aiameiba.com
```

`CONTENT_INGEST_TOKEN` 只能存放在网站服务端环境变量中，不能放进前端环境变量、请求日志或 Git。

## 健康检查

```http
GET /api/internal/content/v1/health
Authorization: Bearer <CONTENT_INGEST_TOKEN>
```

成功响应：

```json
{
  "status": "ok",
  "service": "amaba-ai-website",
  "site_profile": "ai",
  "api_version": "v1"
}
```

## 新增或更新文章

```http
POST /api/internal/content/v1/articles/upsert
Authorization: Bearer <CONTENT_INGEST_TOKEN>
Content-Type: application/json
Idempotency-Key: <source_task_id>:<source_version_id>:ai
```

示例：

```json
{
  "request_id": "publish-request-001",
  "source_system": "amaba-content-core",
  "source_task_id": "task-001",
  "source_version_id": "version-002",
  "source_version_number": 2,
  "content_hash": "09d7e1cd4d3f8b3d3748bb8b4b3d6d4df97195d45d3e15f1d47dd38614c0fa11",
  "site_profile": "ai",
  "publish_mode": "publish",
  "article": {
    "title": "企业如何开始 AI 进化",
    "body_plain": "第一自然段。\n\n第二自然段。",
    "summary": "面向企业经营者的 AI 进化起步方法。",
    "slug": "how-to-start-ai-evolution",
    "primary_keyword": "企业AI进化",
    "keywords": ["企业AI", "企业进化"],
    "content_type": "methodology",
    "direction": "方法论",
    "target_audience": "企业经营者与管理者",
    "author_name": "阿美巴",
    "cover_image_url": null,
    "canonical_url": "https://www.ameiba.cn/insights/how-to-start-ai-evolution"
  },
  "quality": {
    "human_confirmed": true,
    "confirmed_at": "2026-09-11T10:00:00+08:00",
    "prompt_version": "AmAba-Audit-V1.2",
    "judgment_version": "AmAba-Judgment-V1.1",
    "model": "approved-model",
    "remaining_issue_levels": ["P3"]
  },
  "provenance": { "knowledge_refs": [] },
  "semantic": {
    "entities": ["阿美巴", "企业进化"],
    "questions": ["企业应该如何开始AI进化？"],
    "facts": [],
    "suggested_schema_type": "Article"
  }
}
```

首次成功发布返回 `201 Created`，更新返回 `200 OK`：

```json
{
  "success": true,
  "publication_id": "官网文章ID",
  "status": "published",
  "url": "https://www.aiameiba.com/knowledge/how-to-start-ai-evolution",
  "revision": 1,
  "content_hash": "09d7e1cd4d3f8b3d3748bb8b4b3d6d4df97195d45d3e15f1d47dd38614c0fa11",
  "published_at": "2026-09-11T02:00:00.000Z"
}
```

## 校验与限制

- `source_system` 必须为 `amaba-content-core`，`site_profile` 必须为 `ai`。
- `quality.human_confirmed` 必须为 `true`；`publish_mode` 仅支持 `draft` 和 `publish`。
- 标题最长 255 字符，摘要最长 1,200 字符，正文最长 200,000 字符；数组最多 50 项。
- 正文以纯文本保存并按空行渲染为段落，页面不会执行正文 HTML。
- `canonical_url` 可指向传统官网的同文 URL；AI 官网仍会保留可访问正文。
- 单个 IP 每分钟最多 30 次内部接口请求。

## 幂等与更新规则

- `Idempotency-Key` 必须唯一。相同键且相同 `content_hash` 会返回同一文章，不重复创建。
- 相同键但不同哈希返回 `409 CONTENT_CONFLICT`。
- 同一 `source_system + source_task_id + ai` 的新确认版本更新原文章，保持原详情 URL，并将 `revision` 加一。
- 首次发布使用请求中的合法 `slug`；后续更新不会改变已有 URL。

## 错误响应

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "字段不合法",
    "retryable": false
  }
}
```

| HTTP | code | 含义 |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | 请求字段不合法 |
| 401 | `UNAUTHORIZED` | Token 缺失或错误 |
| 409 | `CONTENT_CONFLICT` | 幂等键哈希冲突或 slug 冲突 |
| 413 | `CONTENT_TOO_LARGE` | 正文或数组超出限制 |
| 429 | `RATE_LIMITED` | 请求频率超限 |
| 503 | `SERVICE_UNAVAILABLE` | 网站未配置发布 Token |
| 500 | `INTERNAL_ERROR` | 临时服务故障，可重试 |

## 公开读取

不需要 Token：

```text
GET /api/public/articles
GET /api/public/articles/{content_id-or-slug}
GET /knowledge/{content_id-or-slug}
```

仅返回已发布文章；不暴露任务 ID、审核模型、提示词、来源内部日志或 Token。