CmsKit 新功能使用文档

最后更新：2026-04-07

1. 文章定时发布

功能说明

支持为文章设置定时发布时间，系统会在指定时间自动发布文章，并通知作者。

API 接口

设置定时发布

POST /api/cms/article/{articleId}/schedule
Authorization: Bearer {token}
Content-Type: application/json

"2026-04-01T10:00:00"

参数说明:

参数	类型	必填	说明
articleId	Guid	是	文章 ID
Body	DateTime	是	定时发布时间（必须是未来时间）

响应示例:

// 成功: 204 No Content
// 失败: 400 Bad Request
// "发布时间必须是未来时间"
// "只有审核通过或待审核的文章才能设置定时发布"

取消定时发布

POST /api/cms/article/{articleId}/cancel-schedule
Authorization: Bearer {token}

获取定时发布列表

GET /api/cms/article/scheduled/list
Authorization: Bearer {token}

响应示例:

[
  {
    "id": "guid",
    "title": "文章标题",
    "scheduledPublishTime": "2026-04-01T10:00:00",
    "auditStatus": 0,
    "statusText": "审核通过"
  }
]

使用流程

创建文章（草稿状态）
调用 schedule 接口设置发布时间
系统每分钟扫描待发布文章
到达发布时间后自动发布
发送系统通知告知作者

技术要点

后台任务每分钟执行一次扫描
发布后自动更新 MeiliSearch 搜索索引
仅审核通过或待审核的文章可设置定时发布

2. 回收站功能

功能说明

删除的内容进入回收站，支持 30 天内恢复，超期自动清理。

API 接口

获取回收站列表

GET /api/cms/recycle-bin/list?page=1&pageSize=20
Authorization: Bearer {token}

响应示例:

[
  {
    "id": "guid",
    "title": "文章标题",
    "entityType": "article",
    "deletedTime": "2026-03-30T10:00:00",
    "deleteUserId": "guid",
    "deleteUserName": "系统",
    "remainingDays": 28
  }
]

恢复文章

POST /api/cms/recycle-bin/article/{articleId}/restore
Authorization: Bearer {token}

恢复沸点

POST /api/cms/recycle-bin/shortmsg/{shortMsgId}/restore
Authorization: Bearer {token}

彻底删除文章

POST /api/cms/recycle-bin/article/{articleId}/delete
Authorization: Bearer {token}

彻底删除沸点

POST /api/cms/recycle-bin/shortmsg/{shortMsgId}/delete
Authorization: Bearer {token}

清空回收站

POST /api/cms/recycle-bin/clear
Authorization: Bearer {token}

使用流程

用户删除文章/沸点 → 进入回收站（软删除）
在回收站列表中查看已删除内容
可选择恢复或彻底删除
超过 30 天的内容自动清理

3. @用户功能

功能说明

在评论和沸点中提及用户，被提及的用户会收到通知。支持通过用户名和唯一用户ID两种方式提及，确保即使用户名重复也能准确识别。

使用方式

在评论或沸点内容中使用 @用户名 或 @userId 语法：

方式一：按用户名提及（当用户名唯一时）

这是一篇好文章，@张三 你也来看看

方式二：按用户ID提及（推荐，绝对唯一）

这是一篇好文章，@[userId:550e8400-e29b-41d4-a716-446655440000] 你也来看看

或简化格式：

这是一篇好文章，@550e8400-e29b-41d4-a716-446655440000 你也来看看

支持场景

✅ 文章评论
✅ 沸点评论

匹配规则

用户名匹配：支持用户名匹配，支持中文、英文、数字、下划线
唯一ID匹配：使用 UUID 格式，绝对唯一（推荐用于程序化提及）
昵称匹配：用户名匹配不到时，会尝试昵称匹配
自动去重：同一用户多次提及只通知一次
不会自己@自己

内部处理流程

解析评论文本中的所有 @提及
按以下优先级匹配用户：
- 优先匹配 UUID 格式（绝对唯一）

其次匹配用户名
最后尝试昵称匹配

去重：同一用户多次提及只创建一条通知
发送通知给所有被识别的用户

通知类型

被 @的用户会收到 NotificationType.Mention 类型的通知。

API 示例

方式一：用户名提及（用户名确保唯一时可用）

创建评论时自动触发 @用户通知：

POST /api/cms/comments
Authorization: Bearer {token}
Content-Type: application/json

{
  "subjectType": 1,
  "subjectId": "文章ID",
  "respUserId": "被回复用户ID",
  "text": "@李四 你觉得这个方案怎么样？",
  "respId": null,
  "rootCommentId": null
}

处理流程：

系统提取文本中的 @李四
查询数据库匹配用户名/昵称为"李四"的用户
对命中的用户自动去重并发送通知

方式二：唯一ID提及（✅ 推荐）

使用 @[userId:UUID] 格式确保精准匹配，彻底避免用户名重复导致的歧义：

POST /api/cms/comments
Authorization: Bearer {token}
Content-Type: application/json

{
  "subjectType": 1,
  "subjectId": "文章ID",
  "respUserId": "被回复用户ID",
  "text": "@[userId:550e8400-e29b-41d4-a716-446655440000] 你觉得这个方案怎么样？",
  "respId": null,
  "rootCommentId": null
}

处理流程：

系统识别 @[userId:xxx] 格式，直接按 UUID 精确匹配用户
无歧义，立即发送通知
前端渲染时可将 UUID 替换为友好的用户名或昵称显示

用户ID获取说明

当前 CmsKit 用户端未提供独立的 user/search 接口。建议前端在已有用户列表或个人页上下文中获取 userId，再使用 @[userId:UUID] 进行精确提及。

最佳实践

推荐做法：始终使用用户ID @[userId:xxx]，精准唯一，无歧义
简单场景：用户名确保全局唯一时，可使用 @用户名 快速提及
前端自动补全：提供用户搜索建议，显示用户头像和完整昵称以避免歧义
Markdown 富文本编辑：支持渲染为用户卡片，点击可查看用户资料

4. SEO 优化功能

功能说明

为文章生成 SEO 友好的元数据，包括 Slug、Meta 描述、Meta 关键字、Open Graph 等。

API 接口

获取文章 SEO 元数据

GET /api/cms/seo/article/{articleId}

响应示例:

{
  "title": "文章标题",
  "description": "文章描述（自动生成或自定义）",
  "keywords": "关键字1, 关键字2",
  "canonicalUrl": "https://example.com/article/my-article-abc12345",
  "ogTitle": "文章标题",
  "ogDescription": "文章描述",
  "ogImage": "https://example.com/thumbnail.jpg",
  "twitterCard": "summary_large_image"
}

通过 Slug 获取 SEO

GET /api/cms/seo/article/slug/{slug}

生成 Slug（预览）

POST /api/cms/seo/generate-slug
Content-Type: application/json

"我的第一篇文章"

响应示例:

"我的第一篇文章-abc12345"

更新文章 SEO 信息

POST /api/cms/seo/article/{articleId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "slug": "custom-slug",
  "metaDescription": "自定义描述",
  "metaKeywords": "关键字1, 关键字2"
}

Article 实体新增字段

字段	类型	说明
Slug	string?	SEO 友好 URL 标识
MetaDescription	string?	Meta 描述
MetaKeywords	string?	Meta 关键字

Slug 生成规则

保留：中文、英文、数字、连字符
替换：特殊字符替换为连字符
追加：自动追加 ID 前 8 位避免重复

技术要点

自动生成 Meta 描述（截取内容前 160 字符）
Open Graph 支持社交媒体分享优化
Twitter 卡片支持
规范 URL 生成

5. 草稿箱版本管理

功能说明

每次保存文章时创建版本快照，支持查看历史版本和恢复到任意版本。

API 接口

获取版本列表

GET /api/cms/article-version/article/{articleId}?page=1&pageSize=20
Authorization: Bearer {token}

响应示例:

[
  {
    "id": "guid",
    "articleId": "guid",
    "version": 3,
    "title": "文章标题",
    "contentPreview": "前 200 字预览...",
    "versionComment": "修改了引言部分",
    "isCurrentVersion": true,
    "saveReason": "ManualSave",
    "wordNumber": 2500,
    "readingTime": 10,
    "createTime": "2026-03-30T10:00:00"
  }
]

获取版本详情

GET /api/cms/article-version/{versionId}
Authorization: Bearer {token}

保存新版本

POST /api/cms/article-version/save
Authorization: Bearer {token}
Content-Type: application/json

{
  "articleId": "guid",
  "title": "文章标题",
  "content": "文章内容...",
  "excerpt": "文章摘要",
  "versionComment": "修改了引言部分",
  "saveReason": "ManualSave"
}

saveReason 可选值:

AutoSave - 自动保存
ManualSave - 手动保存
Publish - 发布时保存

恢复到指定版本

POST /api/cms/article-version/restore
Authorization: Bearer {token}
Content-Type: application/json

{
  "versionId": "guid",
  "createNewVersionBeforeRestore": true
}

参数说明:

参数	类型	说明
versionId	Guid	要恢复的版本 ID
createNewVersionBeforeRestore	bool	恢复前是否先保存当前版本

获取最新版本号

GET /api/cms/article-version/article/{articleId}/latest
Authorization: Bearer {token}

响应: 3

获取版本数量

GET /api/cms/article-version/article/{articleId}/count
Authorization: Bearer {token}

响应: 5

使用流程

编辑文章 → 自动/手动保存
系统创建版本快照（版本号 +1）
查看版本列表，了解修改历史
点击某个版本查看详情
可选择恢复到任意历史版本
恢复前可选择是否保存当前版本

技术要点

版本号从 1 开始递增
保存新版本时自动标记之前版本为非当前版本
记录客户端 IP 和地址
自动计算字数和阅读时长

6. 圈子角色体系

功能说明

为圈子提供完整的角色管理体系，支持圈主、管理员、嘉宾、普通成员四种角色。

角色类型

角色	值	权限说明
Owner	1	圈主，最高权限
Admin	2	管理员，管理权限
Guest	3	嘉宾，特殊成员
Member	4	普通成员，基础权限

API 接口

获取用户在圈子中的角色

GET /api/cms/club-role/club/{clubId}/user/{userId}
Authorization: Bearer {token}

响应示例:

{
  "id": "guid",
  "clubId": "guid",
  "userId": "guid",
  "role": 1,
  "roleName": "圈主",
  "isEnabled": true,
  "expireTime": null,
  "grantedTime": "2026-03-30T10:00:00",
  "grantedByUserId": "guid",
  "changeReason": "Grant",
  "remark": null
}

获取圈子成员列表

GET /api/cms/club-role/club/{clubId}/members?role=1&page=1&pageSize=50
Authorization: Bearer {token}

Query 参数:

参数	类型	必填	说明
role	int?	否	按角色筛选（1=圈主, 2=管理员, 3=嘉宾, 4=成员）
page	int	否	页码（默认 1）
pageSize	int	否	每页数量（默认 50）

授予角色

POST /api/cms/club-role/grant
Authorization: Bearer {token}
Content-Type: application/json

{
  "clubId": "guid",
  "userId": "guid",
  "role": 2,
  "expireTime": "2026-06-30T23:59:59",
  "changeReason": "表现优秀",
  "remark": "活跃贡献者"
}

撤销角色

POST /api/cms/club-role/revoke
Authorization: Bearer {token}
Content-Type: application/json

{
  "roleId": "guid",
  "reason": "违反社区规定"
}

转移圈主

POST /api/cms/club-role/transfer
Authorization: Bearer {token}
Content-Type: application/json

{
  "clubId": "guid",
  "newOwnerId": "guid",
  "oldOwnerNewRole": 2
}

oldOwnerNewRole 说明:

2 - 原圈主降级为管理员
3 - 原圈主降级为嘉宾
4 - 原圈主降级为普通成员
null - 原圈主离开圈子

检查用户角色

GET /api/cms/club-role/club/{clubId}/user/{userId}/check/{role}
Authorization: Bearer {token}

响应: true / false

检查是否是管理员

GET /api/cms/club-role/club/{clubId}/user/{userId}/is-admin
Authorization: Bearer {token}

响应: true / false

使用流程

创建圈子 → 创建者自动成为圈主
圈主可授予其他用户管理员/嘉宾角色
管理员可管理圈子内容
支持设置角色过期时间
支持圈主转移给其他用户
过期角色自动清理

变更原因（ChangeReason）

值	说明
Grant	授予角色
Revoke	撤销角色
Expire	角色过期
Transfer	圈主转移

7. RSS/Feed 分发

功能说明

提供标准的 RSS 2.0 和 Atom 1.0 Feed 输出，支持订阅最新文章、指定分类、指定用户的文章。

API 接口

获取最新文章 RSS

GET /api/cms/feed/rss?maxItems=20

响应: application/rss+xml

Query 参数:

参数	类型	必填	说明
maxItems	int	否	返回数量（默认 20）

获取指定分类 RSS

GET /api/cms/feed/rss/category/{categoryId}?maxItems=20

参数说明:

参数	类型	必填	说明
categoryId	Guid	是	分类 ID
maxItems	int	否	返回数量（默认 20）

获取指定用户 RSS

GET /api/cms/feed/rss/user/{userId}?maxItems=20

参数说明:

参数	类型	必填	说明
userId	Guid	是	用户 ID
maxItems	int	否	返回数量（默认 20）

获取 Atom Feed

GET /api/cms/feed/atom?maxItems=20

响应: application/atom+xml

RSS 输出示例

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
  <channel>
    <title>最新文章</title>
    <description>最新发布的博客文章</description>
    <link>https://localhost:5000</link>
    <language>zh-CN</language>
    <lastBuildDate>Sun, 30 Mar 2026 10:00:00 +0800</lastBuildDate>
    <generator>FreeKit CmsKit</generator>
    <item>
      <title>文章标题</title>
      <description>文章摘要...</description>
      <link>https://localhost:5000/article/my-article-abc12345</link>
      <guid>article-id</guid>
      <pubDate>Sun, 30 Mar 2026 08:00:00 +0800</pubDate>
      <author>作者名称</author>
      <category>分类名称</category>
      <category>标签1</category>
      <category>标签2</category>
      <content:encoded><![CDATA[<p>文章完整内容</p>]]></content:encoded>
    </item>
  </channel>
</rss>

使用方式

复制 RSS 链接
在 RSS 阅读器中添加订阅（如 Feedly、Inoreader）
自动获取最新文章更新

技术要点

使用 System.ServiceModel.Syndication 生成标准 RSS 2.0
支持 Atom 1.0 Feed 格式
包含文章标题、摘要、内容、作者、分类、标签
支持自定义返回数量
UTF-8 编码，支持中文
公开访问（AllowAnonymous）

8. 智能推荐流

功能说明

推荐接口已支持“推荐流/热门流”分离，包含用户画像、多路召回、排序融合、可解释字段与多样性控制。

API 接口

获取推荐文章

GET /api/cms/recommendations/articles?flowType=Recommend&limit=12&recentDays=30&enableDiversity=true&maxSameAuthorCount=2&maxSameChannelCount=3
Authorization: Bearer {token 可选}

Query 参数:

参数	类型	必填	说明
flowType	string	否	Recommend 或 Hot，默认 Recommend
limit	int	否	返回数量，默认 12，最大 50
recentDays	int	否	用户行为画像窗口，默认 30
includeViewed	bool	否	是否包含已浏览文章，默认 false
enableDiversity	bool	否	是否启用多样性控制，默认 true
maxSameAuthorCount	int	否	单作者最多返回条数，默认 2
maxSameChannelCount	int	否	单频道最多返回条数，默认 3
articleCategory	int	否	文章分类过滤
channelId	Guid	否	频道过滤

响应示例:

[
  {
    "id": "guid",
    "title": "文章标题",
    "excerpt": "摘要",
    "channelId": "guid",
    "authorId": "guid",
    "tags": ["C#", "DDD"],
    "score": 96.2,
    "recallSource": "follow-author+tag+hot",
    "reason": "来自你关注的作者",
    "publishedTime": "2026-04-07T10:00:00"
  }
]

使用建议

首页默认使用 Recommend 流。
榜单页或冷启动场景可切换 Hot 流。
若希望更多样内容，保持 enableDiversity=true 并限制作者/频道上限。

附录：新增枚举值

NotificationType

public enum NotificationType
{
    UserSubscribeUser = 0,      // 用户关注用户
    UserLikeArticle = 2,        // 用户点赞随笔
    UserLikeShortMsg = 4,       // 用户点赞沸点
    UserLikeArticleComment = 8, // 用户点赞评论
    UserLikeShortMsgComment = 16,
    UserCommentOnArticle = 32,  // 用户评论随笔
    UserCommentOnArticleComment = 64,
    UserCommentOnShortMsg = 128,
    UserCommentOnShortMsgComment = 256,
    System = 512,               // 系统通知（新增）
    Mention = 1024,             // @提及通知（新增）
}

ClubRole

public enum ClubRole
{
    Owner = 0,   // 圈主
    Admin = 1,   // 管理员
    Guest = 2,   // 嘉宾
    Member = 3,  // 普通成员
}

快速开始

1. 定时发布文章

# 设置定时发布
curl -X POST "https://localhost:5001/api/cms/article/{articleId}/schedule" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '"2026-04-01T10:00:00"'

# 查看定时发布列表
curl "https://localhost:5001/api/cms/article/scheduled/list" \
  -H "Authorization: Bearer {token}"

2. 恢复删除的文章

# 查看回收站
curl "https://localhost:5001/api/cms/recycle-bin/list" \
  -H "Authorization: Bearer {token}"

# 恢复文章
curl -X POST "https://localhost:5001/api/cms/recycle-bin/article/{articleId}/restore" \
  -H "Authorization: Bearer {token}"

3. 获取 SEO 元数据

# 获取文章 SEO
curl "https://localhost:5001/api/cms/seo/article/{articleId}"

# 生成 Slug
curl -X POST "https://localhost:5001/api/cms/seo/generate-slug" \
  -H "Content-Type: application/json" \
  -d '"我的第一篇文章"'

4. 订阅 RSS

# 订阅最新文章
curl "https://localhost:5001/api/cms/feed/rss"

# 订阅指定分类
curl "https://localhost:5001/api/cms/feed/rss/category/{categoryId}"

注意事项

定时发布：需要后台任务 ScheduledPublishJob 正常运行
回收站：保留期限 30 天，超期自动清理
@用户：需要用户已注册，用户名或昵称匹配
SEO：Slug 需唯一，建议使用自动生成
版本管理：建议定期清理过期版本以节省存储
圈子角色：仅圈主可执行转移操作
RSS：公开接口，无需认证

目录​

1. 文章定时发布​

功能说明​

API 接口​

设置定时发布​

取消定时发布​

获取定时发布列表​

使用流程​

技术要点​

2. 回收站功能​

功能说明​

API 接口​

获取回收站列表​

恢复文章​

恢复沸点​

彻底删除文章​

彻底删除沸点​

清空回收站​

使用流程​

3. @用户功能​

功能说明​

使用方式​

支持场景​

匹配规则​

内部处理流程​

通知类型​

API 示例​

用户ID获取说明​

最佳实践​

4. SEO 优化功能​

功能说明​

API 接口​

获取文章 SEO 元数据​

通过 Slug 获取 SEO​

生成 Slug（预览）​

更新文章 SEO 信息​

Article 实体新增字段​

Slug 生成规则​

技术要点​

5. 草稿箱版本管理​

功能说明​

API 接口​

获取版本列表​

获取版本详情​

保存新版本​

恢复到指定版本​

获取最新版本号​

获取版本数量​

使用流程​

技术要点​

6. 圈子角色体系​

功能说明​

角色类型​

API 接口​

获取用户在圈子中的角色​

获取圈子成员列表​

授予角色​

撤销角色​

转移圈主​

检查用户角色​

检查是否是管理员​

使用流程​

变更原因（ChangeReason）​

7. RSS/Feed 分发​

功能说明​

API 接口​

获取最新文章 RSS​

获取指定分类 RSS​

获取指定用户 RSS​

获取 Atom Feed​

RSS 输出示例​

使用方式​

技术要点​

8. 智能推荐流​

功能说明​

API 接口​

获取推荐文章​

使用建议​

附录：新增枚举值​

NotificationType​

目录

1. 文章定时发布

功能说明

API 接口

设置定时发布

取消定时发布

获取定时发布列表

使用流程

技术要点

2. 回收站功能

功能说明

API 接口

获取回收站列表

恢复文章

恢复沸点

彻底删除文章

彻底删除沸点

清空回收站

使用流程

3. @用户功能

功能说明

使用方式

支持场景

匹配规则

内部处理流程

通知类型

API 示例

用户ID获取说明

最佳实践

4. SEO 优化功能

功能说明

API 接口

获取文章 SEO 元数据

通过 Slug 获取 SEO

生成 Slug（预览）

更新文章 SEO 信息

Article 实体新增字段

Slug 生成规则

技术要点

5. 草稿箱版本管理

功能说明

API 接口

获取版本列表

获取版本详情

保存新版本

恢复到指定版本

获取最新版本号

获取版本数量

使用流程

技术要点

6. 圈子角色体系

功能说明

角色类型

API 接口

获取用户在圈子中的角色

获取圈子成员列表

授予角色

撤销角色

转移圈主

检查用户角色

检查是否是管理员

使用流程

变更原因（ChangeReason）

7. RSS/Feed 分发

功能说明

API 接口

获取最新文章 RSS

获取指定分类 RSS

获取指定用户 RSS

获取 Atom Feed

RSS 输出示例

使用方式

技术要点

8. 智能推荐流

功能说明

API 接口

获取推荐文章

使用建议

附录：新增枚举值

NotificationType