用 AI 助手通过 API Key 自动发布文章到 KnowFlow

本文记录了一次真实的发布链路验证：从阅读官方文档、检查本机环境，到最终由 AI 助手把这次对话本身整理成文章发布到 KnowFlow——也就是你正在阅读的这篇文章。

背景

KnowFlow 提供了两条机器发布通道，让 AI 助手（或任何脚本）可以在不打开浏览器的情况下发布文章：

通道 适用场景 前置条件
官方 CLI（推荐） 批量/单篇发布，最省事 npm i -g smartwing_knowflow
HTTP API 无 CLI 环境、需要脚本化集成 任意 HTTP 客户端

两条通道共用同一套凭据：API Key（kf_ 前缀）+ 站点地址。

能不能用？先检查环境

在动手之前，AI 助手先做了一次环境自检：

SITE=https://knowflow.smartwingtech.com
KEY=已设置(51字符, 前缀: kf_)
CLI 已安装 (knowflow 0.1.0)
Node v22.22.2  ✅ 满足 >= 20 的要求

四项全部就绪：站点地址和 API Key 已通过环境变量 KNOWFLOW_SITE / KNOWFLOW_API_KEY 配置，官方 CLI 已全局安装。

结论：可以直接发布。

发布方式速览

方式一：官方 CLI

export KNOWFLOW_SITE="https://knowflow.smartwingtech.com"
export KNOWFLOW_API_KEY="kf_…"

knowflow publish ./article.md
knowflow publish ./article.md --title "自定义标题" --tags ai,workflow
knowflow publish ./article.md --space team-docs --tags ai

要点：

  • 正文为 Markdown 文件，大小 ≤ 1MB
  • --title 缺省取文件名（去 .md 后缀）
  • --tags 逗号分隔，去重后最多 5 个
  • --space <slug> 发布到团队空间，可见性自动为 space

方式二：HTTP API

curl -X POST "https://knowflow.smartwingtech.com/api/v1/posts" \
  -H "Authorization: Bearer $KNOWFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-article-001" \
  -d '{
    "title": "文章标题",
    "markdown": "# 一级标题\n\n正文内容……",
    "visibility": "public",
    "tags": ["ai", "workflow"]
  }'

关键字段：title（1–200 字符）、markdown（1 字节–1MB）、visibility（public / space）、space_id（发布到空间时必填）、tags（≤5 个）。发布即上线，status 直接为 published。

几条值得注意的机制

  1. 幂等性：通过请求头 Idempotency-Key 实现。同一用户 + 同一幂等键的重复请求会返回首次结果，不会产生重复文章。重试时务必复用同一个 key（CLI 会自动生成 cli-<sha256 前 32 位>）。
  2. 速率限制：默认每分钟 30 次，批量发布要控制节奏。
  3. 内容安全扫描：命中 block 直接返回 422 且不写库；命中 review 则标记待审。遇到 422 CONTENT_POLICY_VIOLATION 应如实报告原因，不做绕过。
  4. 错误码语义清晰：401 key 无效（不重试，重新生成）、400 字段不合规（修正后重试）、403 空间权限问题、429 限流（指数退避）。

安全规范

  • API Key 只从环境变量读取，绝不写入源码、提示词或任何会提交到版本控制的文件
  • Key 仅在创建时返回一次，泄露后应立即通过 DELETE /api/v1/keys?id=<keyId> 吊销
  • AI 助手只在用户明确要求发布时执行发布动作，发布前先落盘 Markdown 文件，不把巨量正文内联到命令里

结语

这篇文章本身就是这条链路的产物：AI 助手读取文档 → 自检环境 → 把对话整理成 Markdown → 调用 CLI 发布 → 返回文章 URL。整个过程没有打开浏览器，也没有在任何地方暴露 API Key。对于希望把内部产出（会议纪要、复盘报告、技术笔记）定期沉淀到知识库的团队来说，这是一个可以自动化复制的工作流。

发布时间：2026-09-03 · 由 AI 助手通过 KnowFlow API 自动发布