KnowFlow 通过 API Key 自动发布文章（Copilot 指导文档）

本文档是 GitHub Copilot 在 KnowFlow 账户中自动发布文章的操作规范。目标是让 Copilot 在接到「发布文章」指令时，无需反复摸索，即可稳定、安全地把 Markdown 内容发布到指定账户并返回可访问 URL。

1. 发布通道概览

KnowFlow 提供两条等价的机器发布通道：

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

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

2. 前置条件

• 一个已注册且可登录的 KnowFlow 账号。
• 一个**有效（未吊销）**的 API Key。
• 目标站点地址，例如 https://knowflow.smartwingtech.com（本地开发为 http://localhost:3000）。

3. 获取 API Key

API Key 形如 kf_<48 位十六进制>，仅在创建时返回一次，请当场保存。

方式 A：Web 界面

1. 登录 KnowFlow。
2. 打开 设置页：/me/settings。
3. 在「API Key」卡片中创建新 Key，复制 kf_...。

方式 B：HTTP API（需先有登录会话）

curl -X POST "https://knowflow.smartwingtech.com/api/v1/keys" \
  -H "Content-Type: application/json" \
  -H "Cookie: <登录会话 Cookie>" \
  -d '{"name": "copilot-publish"}'

响应（201，key 仅此一次返回）：

{ "id": "…", "name": "copilot-publish", "key": "kf_…" }

辅助端点：

• 列出：GET /api/v1/keys
• 吊销：DELETE /api/v1/keys?id=<keyId>（返回 204）

4. 方式 A：官方 CLI 发布（推荐）

4.1 安装

npm i -g smartwing_knowflow
# 或
pnpm add -g smartwing_knowflow

要求 Node.js >= 20。

开发/源码场景：在仓库内 pnpm --dir <repo>/knowflow build:cli 后用 node bin/knowflow.js publish ...，或 pnpm --dir <repo>/knowflow link --global 全局链接。

4.2 配置（仅环境变量，禁止命令行传 key）

export KNOWFLOW_SITE="https://knowflow.smartwingtech.com"   # 本地开发用 http://localhost:3000
export KNOWFLOW_API_KEY="kf_…"

4.3 发布

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

参数说明：

参数	说明
<file.md>（位置参数）	要发布的 Markdown 文件，内容 ≤ 1MB
--title	覆盖标题；缺省取文件名（去 .md 后缀）
--space <slug>	发布到团队空间；提供时 visibility 自动为 space
--tags <list>	逗号分隔标签，去重后最多 5 个
--site <url>	覆盖 KNOWFLOW_SITE
--json / --quiet / --verbose	机器可读输出 / 静默 / 诊断

成功时 stdout 输出绝对 URL，退出码 0；用法/配置错误 2；API/网络错误 3（stderr 打印业务错误码）。

5. 方式 B：HTTP API 发布

5.1 端点与鉴权

POST /api/v1/posts
Authorization: Bearer <API Key>          # 必填，kf_ 前缀
Content-Type: application/json
Idempotency-Key: <唯一字符串>            # 推荐，重试安全

鉴权支持两种身份，二选一：

• 会话 Cookie（浏览器场景）；或
• Authorization: Bearer kf_…（机器身份，本文档场景）。

5.2 请求体字段

字段	类型	必填	约束	说明
title	string	是	1–200 字符	文章标题
markdown	string	是	1 字节–1MB	正文，Markdown 源码
visibility	string	否	public | space，默认 public	可见性
space_id	string	条件必填	空间 slug 或 UUID	visibility=space 时必填，且需为空间成员
tags	string[]	否	≤5 个，每个 ≤50 字符	用户标签（与自动分类合并）

发布即上线：POST /api/v1/posts 创建的文章 status 直接为 published。

5.3 curl 示例

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-2026-09-02-001" \
  -d '{
    "title": "示例文章标题",
    "markdown": "# 一级标题\n\n正文内容……",
    "visibility": "public",
    "tags": ["ai", "workflow"]
  }'

5.4 响应（201 Created）

{
  "id": "…",
  "title": "示例文章标题",
  "slug": "…",
  "html": "<h1>一级标题</h1>…",
  "categorySlug": "…",
  "visibility": "public",
  "status": "published",
  "authorId": "…",
  "orgId": null,
  "tags": ["ai", "workflow"],
  "version": 1,
  "publishedAt": "2026-09-02T00:00:00.000Z",
  "createdAt": "…",
  "updatedAt": "…",
  "url": "/posts/<slug>"
}

url 是相对路径，对外展示时用站点地址拼接为绝对 URL：new URL(post.url, site)。

5.5 Node.js（fetch）示例

const site = process.env.KNOWFLOW_SITE;
const apiKey = process.env.KNOWFLOW_API_KEY;

const res = await fetch(`${site}/api/v1/posts`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `my-article-${Date.now()}`,
  },
  body: JSON.stringify({
    title: "示例文章标题",
    markdown: "# 一级标题\n\n正文内容……",
    visibility: "public",
    tags: ["ai", "workflow"],
  }),
});

const post = await res.json();
if (res.ok) {
  console.log(new URL(post.url, site).toString());
} else {
  console.error(`${res.status} ${post.code}: ${post.message}`);
}

6. 错误码参考

统一错误体：{ code, message, details?, trace_id }。

状态码	code	触发场景	Copilot 应对
401	INVALID_API_KEY	缺失/无效/已吊销的 API Key	提示用户重新生成并配置 key，不重试
400	VALIDATION_ERROR	字段不合规（如超长、缺字段）	修正请求体后重试
403	FORBIDDEN	无空间权限等	检查 space_id 与成员身份
409	CONFLICT / INVALID_TRANSITION	版本冲突/非法状态流转	按提示修正
422	CONTENT_POLICY_VIOLATION	内容命中安全扫描	报告原因，不绕过
429	RATE_LIMITED	超过发布频率限制	指数退避后重试

7. 幂等性

• 通过请求头 Idempotency-Key 实现（CLI 自动生成 cli-<sha256 前 32 位>）。
• 同一用户 + 同一幂等键的重复请求返回首次结果，不会产生重复文章。
• Copilot 重试同一篇文章时必须复用同一个 key。

8. 速率限制与内容安全

• 发布接口按用户限流，默认 API_RATE_LIMIT_PER_MINUTE=30（每分钟）。批量发布请控制节奏并做好退避。
• 发布前会做内容安全扫描：命中「block」直接返回 422，不写库；命中「review」则标记待审。

9. Copilot 操作规范（务必遵守）

1. 仅在用户明确要求「发布/推送文章到 KnowFlow」时执行发布。
2. API Key 只从环境变量 KNOWFLOW_API_KEY 读取；站点只从 KNOWFLOW_SITE 读取（本地开发可回退 http://localhost:3000）。两者未配置时停止并提示用户，绝不要求用户在提示词里粘贴 key。
3. 发布前先把内容写入 Markdown 文件，再调用 CLI 或 API；不要内联巨量正文到命令里。
4. 优先使用官方 CLI；CLI 不可用时回退 HTTP API。
5. 每次发布生成唯一 Idempotency-Key，重试时复用。
6. 发布成功后返回绝对 URL，并建议用户打开页面检查自动美化、分类与标签。
7. 遇到 422 CONTENT_POLICY_VIOLATION 时如实报告原因，不得尝试绕过安全扫描。

10. 安全红线

• 禁止把真实 API Key 写入：源码、提示词、任务参数、VS Code 设置、.env 以外的已提交文件、任何版本控制文件。
• 本地环境变量用未纳入版本控制的 .env 或系统密钥管理器管理。
• 泄露/可疑后应立即吊销：DELETE /api/v1/keys?id=<keyId>。
• 不执行 push --force、删除性操作或生产数据变更。

11. 发布自检清单

• KNOWFLOW_SITE 与 KNOWFLOW_API_KEY 已配置且 key 以 kf_ 开头
• Markdown 文件已写入且 ≤1MB
• title 1–200 字符，tags ≤5 个
• 请求携带 Authorization: Bearer 与 Idempotency-Key
• 发布成功拿到 url 并拼接为绝对地址返回