知识库发布接口文档

通过本接口，已授权的服务端应用可以查询已发布的知识库文章，并新增中英文文章。新增内容直接发布到 COS 知识库，获得中文和英文访问地址。

1. 接口与凭证

生产 API 地址：https://project.xiaotunqifu.com。请求使用 HTTPS、POST 和 Content-Type: application/json。

使用分配的 KNOWLEDGE_RELEASE_SECRET_ID 和 KNOWLEDGE_RELEASE_SECRET_KEY。Secret Key 是 64 位十六进制字符串，解码为 32 字节密钥。凭证应在调用方服务端配置；网页端不需要持有凭证。

2. 加密、鉴权与解密

请求和成功响应使用 AES-256-GCM。UTF-8 编码的 JSON 为明文，每次加密生成新的 12 字节随机 IV，认证标签为 16 字节。iv、ciphertext、tag 使用标准 Base64 编码（带 padding），标签独立于密文。

请求 JSON 包含以下字段：

附加认证数据 AAD 是以下各行用 \n 连接后的 UTF-8 字节，末尾没有换行。path 为上表完整路径，不包含域名、查询参数或末尾斜杠：

BW-RELEASE-V1
request
POST
{path}
{secretId}
{timestamp}
{nonce}

成功响应为 {"code":0,"status":200,"data":{...加密信封...}}。取出 data，使用同一密钥解密；AAD 第二行改为 response，时间戳使用响应中的值，其余规则相同。响应 nonce 与本次请求一致。必须校验 GCM tag，并确认 Secret ID、nonce 和时间戳后再使用结果。HTTP 错误返回未加密的错误对象，含 message 和 status。

每个 nonce 仅可使用一次。超时或重试时重新生成 nonce、时间戳和 IV，文章 ID 与文章内容保持一致。Node.js Crypto 文档提供 GCM、AAD 和认证标签的实现说明。

3. 获取文章列表

加密前的 JSON：

{"page":1,"size":20}

page 默认 1，最大 100000；size 默认 20，范围 1–100。解密后返回 version、page、size、total 和 records。每条记录包含 id、routeSlug、aliases、hash 及 zh、en 元数据（标题、摘要、分类、标签、更新时间），列表不含正文。

后续分页传入第一页的 version，如 {"page":2,"size":20,"version":"..."}。若发布版本发生变化，返回 HTTP 409，需从第一页重新查询。中文地址为 /faq/{routeSlug}，英文地址为 /en/faq/{routeSlug}。

4. 新增文章

加密前的 JSON 示例：

{
  "id": "faq-api-crm-approval-guide",
  "zh": {
    "q": "CRM 审批流程如何设计？",
    "summary": "从审批角色、权限和记录追溯规划 CRM 审批。",
    "category": "软件定制",
    "tags": ["CRM", "审批流程"],
    "updatedAt": "2026-09-24T10:00:00+08:00",
    "a": "## 审批角色\n\n先确定发起人、审批人和可见范围。"
  },
  "en": {
    "q": "How to design CRM approval workflows",
    "summary": "Plan approval roles, permissions and an auditable history for your CRM.",
    "category": "Custom Software",
    "tags": ["CRM", "Approvals"],
    "updatedAt": "2026-09-24T10:00:00+08:00",
    "a": "## Approval roles\n\nDefine who submits, who approves and who can view each request."
  }
}

id 由调用方生成并固定，格式为 faq-api- 加小写字母、数字及单个短横线分隔的词，总长不超过 150。相同 ID、相同内容可安全重试；相同 ID、不同内容返回 409。本接口提供新增功能。

zh、en 均必填。每种语言的 q（标题，最多 200 字符）、summary（摘要，最多 2000）、category（分类，最多 100）、updatedAt（ISO 日期时间）、a（Markdown 正文，最多 200000）均为非空字符串。tags 为最多 20 个非空字符串，每项最多 80 字符，可传空数组。英文标题应使用英文字符，系统据此生成稳定的英文 URL；URL 与现有文章或专题冲突时返回 409。

成功解密后的结果示例：

{
  "id": "faq-api-crm-approval-guide",
  "version": "64位发布版本摘要",
  "created": true,
  "published": true,
  "status": "complete",
  "pending": [],
  "urls": {
    "zh": "/faq/how-to-design-crm-approval-workflows",
    "en": "/en/faq/how-to-design-crm-approval-workflows"
  }
}

published: true 表示 COS 已发布；status: complete 表示搜索与网页缓存同步完成。status: pending 时，pending 会包含 search 或 website-cache，可再次提交相同文章恢复同步。重复提交时 created: false。若请求超时或返回 503，发布结果可能尚不确定，同样使用原 ID 和原内容重试。

5. Node.js 完整调用示例

下载 release-client.mjs，它包含请求加密、HTTP 调用和响应解密，适用于 Node.js 24。将凭证设置到环境变量后：

import { readFile } from 'node:fs/promises';
import { releaseRequest } from './release-client.mjs';

console.log(await releaseRequest('list', { page: 1, size: 20 }));

// article.json 使用第 4 节结构；仅在准备发布时执行。
const article = JSON.parse(await readFile('./article.json', 'utf8'));
console.log(await releaseRequest('create', article));

可通过 KNOWLEDGE_RELEASE_BASE_URL 指定其他已配置的 API 环境。调用函数也支持第三个参数 { baseUrl, secretId, secretKey }。

6. 错误处理