blogflare/.agents/skills/blogflare-api/SKILL.md

name, description

name	description
blogflare-api	如何调用 BlogFlare 本地或线上的 REST API 来管理（增删改查）文章，附带 OpenAPI schema 与使用示例。

BlogFlare API 操作指南

当用户要求你“通过接口/API读取文章”、“通过接口更新文章”或者当你需要远程管理 BlogFlare 的数据时，请使用本指南提供的 RESTful API。

认证机制

所有 /api/v1/posts 下的接口都需要在 HTTP 请求头中带上 Authorization: Bearer <Token>。 其中 Token 需要保存在数据库 settings 表的 agent.api_token 字段中。

如果在本地开发环境 (dev) 调试： 如果遇到 Token 未设置，你可以先帮用户在 settings 表插入/更新： INSERT INTO settings (key, value) VALUES ('agent.api_token', 'your_test_token') ON CONFLICT(key) DO UPDATE SET value = excluded.value;

接口说明

1. 获取文章列表 (GET /api/v1/posts)

参数：

• limit (默认 10)
• offset (默认 0)

响应格式：

{
	"data": [
		{
			"id": 1,
			"slug": "hello-world",
			"title": "...",
			"published_at": "...",
			"category_slug": "..."
		}
	],
	"meta": { "total": 10, "limit": 10, "offset": 0 }
}

2. 获取单篇文章详情 (GET /api/v1/posts/[slug])

响应格式：

{
	"data": {
		"id": 1,
		"slug": "hello-world",
		"title": "...",
		"content": "...",
		"published_at": "...",
		"updated_at": "...",
		"category_slug": "tech"
	}
}

3. 创建新文章 (POST /api/v1/posts)

Body (JSON)：

{
	"slug": "new-post-slug",
	"title": "New Post Title",
	"content": "Markdown content here...",
	"category_slug": "tech"
}

响应格式：

{ "success": true, "slug": "new-post-slug", "title": "New Post Title" }

4. 更新文章 (PUT /api/v1/posts/[slug])

Body (JSON) [可选字段]：

{
	"title": "Updated Title",
	"content": "Updated Markdown content...",
	"category_slug": "life"
}

响应格式：

{ "success": true, "slug": "the-post-slug" }

注意事项

• 本地调试可以运行 npm run dev，然后用 curl 测试。
• 请勿随意删除或覆盖已有的真实文章数据。在更新之前，最好先 GET 取回全量 content 进行 diff 确认。