✦ 创作与发布指南 ✦

本站支持两种发文方式：管理员在后台手动发布，以及让 AI / 自动化脚本通过接口导入。这一页把两条路都讲清楚，第一次用照着走即可。

方式一 · 管理员后台发文

适合日常写作：所见即所得的富文本编辑器，支持标题、列表、引用、代码、超链接，以及站内特色内容块（Callout、B站时间戳、按键连招、GIF 演示等）。

1
登录管理后台
打开 /admin 并使用管理员账号登录。
打开管理后台 →
2
进入「教程」集合
在左侧菜单找到 Tutorials / 教程，点击「新建」。
直达教程管理 →
3
填写必要字段
至少填写：教程标题、URL Slug、文章摘要、内容类型、正文内容、状态。
4
上传封面（可选）
先在 Media / 媒体集合上传图片，再回到文章的「封面图片」字段选择它。
打开媒体库 →
5
检查目录设置
正文目录自动读取 h2 / h3 标题生成；想显示目录就保持「显示目录」勾选。
6
先草稿，再发布
先保存为草稿，打开 /guides/<slug> 预览确认；无误后把「状态」改为「已发布」。

方式二 · AI / 自动化接口导入

把下面的接口说明发给 AI（或自动化脚本）即可。鉴权使用服务器 .env 里的 ARTICLES_IMPORT_SECRET，密钥不要写进公开文档或聊天记录。默认创建草稿，人工确认后再发布。

发起请求

bash · 创建草稿文章

curl -X POST https://万态拟物.com/api/admin/articles/import \
  -H "Authorization: Bearer <你的导入密钥>" \
  -H "Content-Type: application/json" \
  --data '{
    "title": "文章标题",
    "slug": "article-slug",
    "excerpt": "文章摘要",
    "contentFormat": "markdown",
    "content": "## 开始\n正文支持 [链接](https://example.com)。\n\n### 小节\n- 第一条\n- 第二条",
    "status": "draft",
    "contentType": "guide",
    "toc": true,
    "tags": ["AI 导入"],
    "upsert": true,
    "importMeta": { "model": "模型名称" }
  }'

成功响应

json · 返回结果

{
  "ok": true,
  "action": "created",
  "article": {
    "id": 1,
    "slug": "article-slug",
    "status": "draft",
    "title": "文章标题",
    "url": "/guides/article-slug"
  }
}

拿到 url 后，先在后台预览草稿，确认排版无误再发布。

本地文件导入（可选）

如果稿子已经是本地 Markdown 文件，在项目目录里用自带脚本更方便：

bash · 本地导入脚本

# Markdown 文件导入（默认存为草稿）
npm run import:article -- ./drafts/article.md --secret <你的导入密钥> --upsert

# 带封面图
npm run import:article -- ./drafts/article.md --secret <你的导入密钥> --cover ./drafts/cover.png --upsert

# 直接发布（谨慎使用）
npm run import:article -- ./drafts/article.md --secret <你的导入密钥> --publish --upsert

给 AI 的写稿格式建议

让 AI 输出 Markdown 正文时参考下面的结构。注意：目录只读取 ## 和 ### 两级标题；配图建议通过封面字段传入，正文内精细图文排版由管理员在后台补充更稳。

markdown · 正文模板

# 文章标题

## 第一部分

正文，支持 [链接文字](https://example.com)。

### 子标题

- 列表项
- 列表项

## 第二部分

继续正文。

常见问题

检查请求头 Authorization 是否为「Bearer <ARTICLES_IMPORT_SECRET>」，密钥要与服务器 .env 中配置的 ARTICLES_IMPORT_SECRET 完全一致。

同一个 slug 已存在时，在请求里加 "upsert": true 即可按 slug 更新已有文章。

先确认文章状态是否为「已发布」。草稿在后台可见，但前台列表和详情页只展示已发布内容。

确认三件事：文章的「显示目录」已开启；正文里有 h2 或 h3 标题；访问的是 /guides/<slug> 页面。

不会。导入接口默认创建草稿，只有显式传 "status": "published"（或脚本加 --publish）才会发布。建议保持默认，人工预览后再发布。

JSON 请求里传 coverImage.url（外链图片会自动抓取入库），或改用 multipart/form-data，payload 字段放 JSON、cover 字段放图片文件。接口只接受图片类型文件。

还有问题？完整字段与接口契约见项目内 docs/features/article-authoring/ 文档。

✦ 创作与发布指南 ✦

方式一 · 管理员后台发文

登录管理后台

进入「教程」集合

填写必要字段

上传封面（可选）