轻言（Hitokoto Hub）

轻拾人间辞藻，言说万千心绪

轻言是一款 Halo 2.x 插件，为你的网站注入"一句话"的灵动与温度。它支持创建、管理海量句子，按分类归档，提供随机获取、关键词搜索、点赞互动、访客投递等丰富的开放接口。无论是诗词名言、影视台词还是生活感悟，轻言让你的网站成为一个会说话的角落。

• 演示站点：https://www.puresky.top/hitokoto

交流群：

• 点击加入：QQ交流群

目录

• 功能特性
• 演示与交流
• 插件截图
• 环境要求
• 安装
• 快速上手
• 主题集成
• 公开 API 文档
• 后台管理 API
• Finder API
• 数据模型
• 插件设置
• 定时任务
• AI 自动生成
• 访客提交
• 权限体系
• 项目结构
• 开发指南
• 可用数据源
• 常见问题
• 许可
• 致谢

功能特性

• 句子管理：创建、编辑、删除句子，支持 JSON 批量导入与 Excel（.xlsx）导入，自动映射字段
• 分类归档：自定义分类，侧边栏导航，Reconciler 自动统计各分类下的句子数量
• 随机获取：基于索引分页的随机算法，6000 条数据依然秒级响应；支持多分类筛选、返回数量限制、JSON / 纯文本两种响应格式
• 模糊搜索：基于索引的 spec.content 关键词搜索，支持按分类过滤
• 点赞互动：开放点赞 / 取消点赞接口，基于 IP 的冷却机制防止刷赞，自动记录点赞事件
• 浏览统计：随机获取句子时可自动累计浏览量，并生成 CategoryViewRecord 事件用于趋势分析
• 数据看板：后台概览页面展示句子总数、分类总数、发布状态分布；支持按天 / 周 / 月粒度的分类浏览趋势折线图（ECharts）
• 主题集成：提供 hitokotoFinder Finder API，可在 Halo 主题模板中直接调用；内置默认模板 /hitokoto，带樱花飘落动画
• AI 生成：可选依赖 AI Foundation，支持定时按主题自动生成句子并可配置自动发布
• 权限控制：基于 Halo RBAC 的三层角色模板（公共接口 / 查看 / 管理），公共接口自动授权给匿名用户
• 数据自清理：定时清理过期的点赞缓存与统计记录，支持按条数和天数双重保留策略
• 访客投递：默认模板内置投递入口，访客可在前台提交句子；后台提供 PENDING / APPROVED / REJECTED 三态审核工作流，支持基于 IP 的提交冷却与审核后自动发布
• AI 生成日志：每次 AI 生成任务都会写入 AiGenerateLog 记录运行状态、耗时与源数据，可在后台「AI 日志」查看，并支持手动触发与按状态过滤

演示与交流

• 演示站点：https://www.puresky.top/hitokoto
• 文档：https://www.puresky.top/docs/
• API 文档：https://plugin-hitokoto-hub.apifox.cn/

插件截图

轻言数据概览	轻言数据管理
轻言数据批量导入	轻言单条数据创建
轻言默认模板	轻言访客提交
轻言 AI 日志

环境要求

安装

方式一：应用市场安装（推荐）

在 Halo 后台「应用市场」中搜索「轻言」并一键安装。

方式二：手动上传安装

1. 前往 Releases 下载最新版 plugin-hitokoto-hub-x.x.x.jar
2. 在 Halo 后台的「插件」管理中点击「安装」，上传 jar 文件
3. 启用插件后，后台左侧菜单会出现「轻言」入口

方式三：从源码构建

参考下方 开发指南。

快速上手

1. 创建分类

进入「轻言 → 数据管理」，在左侧分类面板点击 + 号，填写分类名称与描述。

2. 新建句子

点击右上角「新建句子」，填写句子内容、作者、来源并选择分类。

• 若当前用户具有 super-role，句子将自动发布；否则默认未发布，需管理员审核发布。

3. 批量导入

支持两种格式：

• JSON 批量导入：直接粘贴或上传符合 Sentence 结构的 JSON 数组
• Excel 导入：上传 .xlsx 文件，插件会自动识别表头（支持 hitokoto / content / sentence / 句子内容 / 内容 / 一言 等别名映射到句子内容字段，from_who / author / 作者 映射到作者，from / source / 来源 / 出处 映射到来源），也可在导入时手动指定列名

4. 调用公开接口

# 随机获取 1 条句子（默认返回 JSON）
curl 'https://your-domain.com/apis/public.api.hitokotohub.puresky.top/v1alpha1/sentence/random'

# 按分类随机获取 8 条，返回纯文本
curl 'https://your-domain.com/apis/public.api.hitokotohub.puresky.top/v1alpha1/sentence/random?categoryName=category-xxx&limit=8&encode=text'

# 获取所有分类
curl 'https://your-domain.com/apis/public.api.hitokotohub.puresky.top/v1alpha1/category/list'

# 点赞
curl 'https://your-domain.com/apis/public.api.hitokotohub.puresky.top/v1alpha1/sentence/like?name=sentence-xxxx&action=like'

# 取消点赞
curl 'https://your-domain.com/apis/public.api.hitokotohub.puresky.top/v1alpha1/sentence/like?name=sentence-xxxx&action=unlike'

# 访客投递句子（无需登录，受 IP 冷却限制）
curl -X POST 'https://your-domain.com/apis/public.api.hitokotohub.puresky.top/v1alpha1/sentence-submission/submit' \
  -H 'Content-Type: application/json' \
  -d '{"content":"愿你被这个世界温柔以待。","author":"佚名","source":"未知","categoryName":"category-xxx","submitterName":"路人甲"}'

5. 启用访客投递（可选）

进入「轻言 → 设置 → 访客提交设置」开启「启用访客提交」，并配置默认分类、提交冷却时间、审核通过后是否自动发布等。开启后默认模板 /hitokoto 右上角会出现「投递句子」按钮，访客提交后进入 PENDING 状态，管理员可在「轻言 → 访客提交」中审核。

主题集成

插件内置一个默认的展示模板，访问路径为 /hitokoto，带有逐字淡入动画与樱花飘落效果。你也可以通过 Finder API 或 REST API 在自己的主题中自定义展示方式。

方式一：Finder API（推荐）

在主题 Thymeleaf 模板中直接调用 hitokotoFinder：

<!-- 随机获取 1 条句子 -->
<div th:each="s : ${hitokotoFinder.randomSentences(1, null)}">
    <p th:text="${s.content}"></p>
    <span th:text="${s.author}"></span>
    <span th:text="${s.source}"></span>
    <span th:text="${s.likeCount}"></span>
    <span th:text="${s.viewCount}"></span>
</div>

<!-- 获取分类列表（仅返回有句子的分类） -->
<div th:each="c : ${hitokotoFinder.listCategories()}">
    <a th:href="@{/hitokoto(category=${c.name})}" th:text="${c.displayName}"></a>
    <span th:text="${c.sentenceCount}"></span>
</div>

<!-- 按分类随机获取 8 条 -->
<div th:each="s : ${hitokotoFinder.randomSentences(8, 'category-xxx')}">
    <p th:text="${s.content}"></p>
</div>

SentenceVo 字段：name、content、author、source、categoryName、likeCount、viewCount
CategoryVo 字段：name、displayName、description、sentenceCount

方式二：REST API

在前端脚本中直接调用公开 API：

// 随机获取句子
fetch('/apis/public.api.hitokotohub.puresky.top/v1alpha1/sentence/random?limit=8')
  .then(res => res.json())

// 按分类随机获取
fetch('/apis/public.api.hitokotohub.puresky.top/v1alpha1/sentence/random?categoryName=category-xxx&limit=8')
  .then(res => res.json())

// 获取分类
fetch('/apis/public.api.hitokotohub.puresky.top/v1alpha1/category/list')
  .then(res => res.json())

// 点赞句子
fetch('/apis/public.api.hitokotohub.puresky.top/v1alpha1/sentence/like?name=sentence-xxxx&action=like')
  .then(res => res.json())

// 取消点赞
fetch('/apis/public.api.hitokotohub.puresky.top/v1alpha1/sentence/like?name=sentence-xxxx&action=unlike')
  .then(res => res.json())

公开 API 文档

所有公开 API 前缀为 /apis/public.api.hitokotohub.puresky.top/v1alpha1，无需鉴权（自动授权给匿名用户）。

随机获取句子

GET /sentence/random

响应示例（JSON）：

{
  "categoryName": "温柔治愈",
  "maxRandomLimit": 20,
  "returned": 1,
  "sentences": [
    {
      "metaName": "sentence-xxxx",
      "author": "佚名",
      "content": "愿你被这个世界温柔以待。",
      "source": "未知",
      "createdBy": "admin",
      "likeCount": 12,
      "viewCount": 348
    }
  ]
}

点赞 / 取消点赞

GET /sentence/like

响应示例：

{
  "success": true,
  "code": "ok",
  "message": "点赞成功",
  "sentence": { "metaName": "sentence-xxxx", "content": "...", "likeCount": 13 }
}

同一 IP 对同一句子的点赞 / 取消点赞操作受冷却时间限制（默认 12 小时，可在设置中调整），冷却期内再次操作返回 code: "rate_limited"。

获取分类列表

GET /category/list

返回所有分类数组，每个元素包含 name、displayName、description、sentenceCount。

访客投递句子

POST /sentence-submission/submit

无需登录鉴权（自动授权给匿名用户）。请求体为 JSON：

响应示例：

{ "success": true, "code": "ok", "message": "投递成功，等待审核" }

错误码：

提交的句子会以 SentenceSubmission 资源保存，初始状态为 PENDING，需要管理员在后台审核通过后才会生成 Sentence。

后台管理 API

后台管理 API 前缀为 /apis/console.api.hitokotohub.puresky.top/v1alpha1，需具备 plugin:hitokoto-hub:manage 权限。

审核接口的错误响应：找不到提交记录返回 404，重复审核（非 PENDING 状态）返回 409 Conflict。

此外，插件通过 Halo 扩展机制暴露了标准的 CRUD 接口：

• /apis/hitokotohub.puresky.top/v1alpha1/sentences
• /apis/hitokotohub.puresky.top/v1alpha1/categories

完整的 API 定义可在 api-docs/openapi/v3_0/extensionApis.json 中查看，或参考 Apifox 文档。

Finder API

Finder 的随机算法与公开 API 一致：先按分类统计总数，随机选中一页，取回后再洗牌，确保返回结果随机且性能稳定。

数据模型

插件注册了五个自定义扩展模型（GVK group: hitokotohub.puresky.top，version: v1alpha1）：

Sentence

句子资源。

Category

分类资源。

CategoryViewRecord

分类事件记录，用于浏览 / 点赞趋势统计。

SentenceSubmission

访客投递句子记录，由公开 submit 接口创建，经管理员审核后转为 Sentence。

状态流转：PENDING → APPROVED（生成 Sentence 并写入 sentenceName）或 REJECTED（写入 reviewNote）。已处理的提交无法再次审核。提交记录的 IP 冷却基于内存缓存，插件重启后会重置。

AiGenerateLog

AI 生成任务运行日志，由 AiGenerateService 在每次定时 / 手动触发时创建。

Reconciler 会在 Sentence 增删改时自动更新对应 Category.status.sentenceCount；若分类被删除，其下所有句子也会被级联删除。

插件设置

插件设置位于「轻言 → 设置」，分为「基本设置」「AI 设置」「访客提交设置」三组。

基本设置

AI 设置

包含 AI 自动生成配置与 AI 日志保留策略。除下表所列项外，还包含：

修改 AI 设置后，定时任务会自动重新注册，无需重启 Halo。AI 生成的句子 createdBy 字段标记为 AI。

访客提交设置

注：IP 冷却基于内存缓存，插件重启后会重置。submissionMaxKeep 设置已暴露在后台，但当前版本的定时清理任务尚未接入此策略，后续版本将补齐。

定时任务

插件内置以下定时任务，均无需手动配置：

AI 自动生成

插件可选集成 AI Foundation，实现按主题定时自动生成句子，每次运行都会写入一条 AiGenerateLog 记录。

启用步骤

1. 在 Halo 应用市场安装并启用 AI Foundation
2. 在 AI Foundation 中配置至少一个语言模型
3. 进入「轻言 → 设置 → AI 设置」，开启「启用 AI 生成」
4. 选择语言模型、设置生成主题、数量、目标分类、定时任务 Cron 表达式

手动触发

后台「轻言 → AI 日志」页面提供「立即生成」按钮，调用 POST /apis/console.api.hitokotohub.puresky.top/v1alpha1/ai-generate-logs/-/trigger 异步触发一次生成任务，运行结束后可在日志列表查看状态、耗时与生成内容。

访客提交

访客提交功能允许未登录用户在 /hitokoto 默认模板上投递句子，由管理员在后台审核。完整流程：

访客填写表单 ──► POST /sentence-submission/submit ──► SentenceSubmission (PENDING)
                                                          │
                                                  管理员审核（后台「访客提交」Tab）
                                                          │
                              ┌──────────────────────────┴──────────────────────────┐
                              ▼                                                       ▼
                       审核通过 (APPROVED)                                       拒绝 (REJECTED)
                       创建 Sentence                                            写入 reviewNote
                       记录 sentenceName                                         状态终止
                       可选自动发布

接入说明

• 默认模板已内置投递表单（含分类下拉、内容、作者、来源、昵称），无需额外开发
• 若要在自定义主题中接入，可直接调用公开接口 POST /sentence-submission/submit
• 公共提交权限已自动聚合到匿名用户，无需额外授权
• 审核操作需具备 plugin:hitokoto-hub:manage 权限

权限体系

插件部署后会自动创建以下角色模板：

对应 UI 权限标识：

• plugin:hitokoto-hub:manage — 管理权限
• plugin:hitokoto-hub:view — 查看权限

项目结构

plugin-hitokoto-hub/
├── src/main/java/top/puresky/hitokotohub/
│   ├── HitokotoHubPlugin.java          # 插件入口，注册 5 个扩展模型与索引
│   ├── HitokotoTemplateRouter.java     # 默认模板路由 /hitokoto
│   ├── PluginConfiguration.java        # 插件配置
│   ├── config/                         # 设置配置读取
│   │   ├── SettingConfig.java
│   │   └── impl/SettingConfigImpl.java
│   ├── endpoint/                       # 自定义 API 端点（公开 + 后台）
│   │   ├── CategoryPublicEndpoint.java
│   │   ├── SentencePublicEndpoint.java
│   │   ├── SentenceSubmissionPublicEndpoint.java   # 访客投递公开接口
│   │   ├── SentenceConsoleEndpoint.java
│   │   ├── SentenceSubmissionConsoleEndpoint.java  # 访客提交审核接口
│   │   ├── OverviewConsoleEndpoint.java
│   │   ├── AiGenerateLogConsoleEndpoint.java      # AI 日志查询 / 触发 / 删除
│   │   └── SentenceQuery.java
│   ├── extension/                      # 自定义扩展模型（GVK）
│   │   ├── Sentence.java
│   │   ├── Category.java
│   │   ├── CategoryViewRecord.java
│   │   ├── SentenceSubmission.java    # 访客投递记录
│   │   └── AiGenerateLog.java         # AI 生成任务日志
│   ├── finder/                         # 主题 Finder API
│   │   ├── HitokotoFinder.java
│   │   └── impl/HitokotoFinderImpl.java
│   ├── reconciler/                     # 资源 Reconciler
│   │   ├── SentenceReconciler.java
│   │   └── CategoryReconciler.java
│   ├── scheduled/                      # 定时任务
│   │   └── StatsCleanupScheduler.java   # 清理缓存/统计/AI 日志 + 注册 AI 生成任务
│   └── service/                        # AI 生成服务
│       ├── AiGenerateService.java
│       └── impl/AiGenerateServiceImpl.java
├── src/main/resources/
│   ├── extensions/                     # 角色模板与设置定义
│   │   ├── role-template-manage-hitokoto-hub.yaml
│   │   ├── role-template-public-hitokoto-hub.yaml
│   │   ├── role-template-view-hitokoto-hub.yaml
│   │   └── settings.yaml               # basic / ai / submission 三组设置
│   ├── templates/hitokoto.html         # 默认展示模板（含投递表单）
│   ├── plugin.yaml                     # 插件清单
│   └── logo.png
├── ui/                                 # 后台前端（Vue 3 + Element Plus）
│   └── src/
│       ├── api/generated/              # OpenAPI 自动生成的 API 客户端
│       ├── components/                 # Overview / CategoryList / SentenceList / SubmissionList
│       └── views/HomeView.vue          # Tab 容器（数据 / 访客提交 / AI 日志等）
├── api-docs/openapi/v3_0/              # 生成的 OpenAPI 文档
├── build.gradle                        # 后端构建脚本
├── gradle.properties
└── ui/build.gradle                     # 前端构建脚本

开发指南

技术栈

• 后端：Java 21、Spring WebFlux、Reactor、Halo Extension API
• 前端：Vue 3、Element Plus、ECharts、TailwindCSS、Rsbuild、TypeScript
• 构建：Gradle（后端）、pnpm + Rsbuild（前端）

本地开发

# 1. 克隆项目
git clone https://github.com/imorisun/plugin-hitokoto-hub.git
cd plugin-hitokoto-hub

# 2. 构建前端
cd ui
pnpm install
pnpm build

# 3. 构建插件
cd ..
./gradlew build
# 构建产物位于 build/libs/plugin-hitokoto-hub-1.0.0-SNAPSHOT.jar

开发模式

前端开发模式下会监听文件变化并实时构建到 ui/dist：

cd ui
pnpm dev

后端可配合 Halo Plugin Devtools 进行调试，build.gradle 中已配置 haloPlugin 扩展。

重新生成 API 客户端

当后端 API 发生变化时，可重新生成前端使用的 API 客户端代码：

./gradlew generateOpenApiClient

生成的代码位于 ui/src/api/generated/。

可用数据源

可从以下数据源导入句子到轻言：

• sentences-bundle — 一言社区官方句子库
• sentences-bundle-JSDelivr — JSDelivr CDN 镜像

常见问题

更新插件后出现问题

由于部分版本可能修改了设置项结构，更新后请：

1. 进入「插件 → 轻言 → 设置」，点击「重置」恢复默认设置
2. 重新配置所需设置项
3. 若仍有问题，重启 Halo

AI 生成功能不可用

AI 自动生成需要同时满足：

1. 已安装并启用 AI Foundation
2. 在 AI Foundation 中已配置可用的语言模型
3. 在轻言设置中选择了对应的语言模型

句子未在前台显示

前台随机接口仅返回 status.isPublished = true 的句子。非 super-role 用户创建的句子默认未发布，需管理员在后台手动发布。

访客投递接口返回 403

code: "submitted_disabled" 表示后台未开启访客提交。进入「轻言 → 设置 → 访客提交设置」，将「启用访客提交」打开并保存。

访客投递接口返回 429

code: "rate_limited" 表示同一 IP 在冷却期内重复提交。可在「访客提交设置 → 提交冷却时间」中调小或置 0 关闭限制。注意：冷却基于内存缓存，插件重启后会重置。

许可

GPL-3.0 © imorisun

致谢

• Halo — 强大易用的开源建站工具
• 一言 — 一言项目，灵感来源
• sentences-bundle — 句子数据源
• AI Foundation — Halo 官方 AI 基座